feat(kanban): add orchestrator board tools — kanban_list + kanban_unblock (carve-out of #20568)#23012
Merged
Merged
Conversation
Adapted from PR #20568 commit ce35185 (Eric Litovsky / @kallidean). Adds two-tier gating for the kanban tool surface so dispatcher-spawned workers see only task-lifecycle tools (show/complete/block/heartbeat/ comment/create/link) while orchestrator profiles with `toolsets: [kanban]` also see board-routing tools (kanban_list, kanban_unblock). Workers shouldn't be enumerating or unblocking the board — they should close their own task via the lifecycle tools. Hiding board-routing tools from worker schemas keeps the worker focused and the toolset-isolation contract honest. Plus inherited from the same upstream commit: - 50/200 row bound on kanban_list with `truncated` + `next_limit` metadata. - Belt-and-suspenders runtime guard `_require_orchestrator_tool()` inside the orchestrator handlers in case a stale registration ever routes a worker to one of them. - Tests for the new gate, the stricter bound, and the fact that even a worker with `toolsets: [kanban]` in config still doesn't see board routing. Co-authored-by: Eric Litovsky <elitovsky@zenproject.net>
Contributor
🔎 Lint report:
|
19 tasks
1 task
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds two new orchestrator-only Kanban tools (
kanban_list,kanban_unblock) that close the discovery + recovery gap orchestrator profiles hit on a real board. Workers (HERMES_KANBAN_TASK set) keep their focused 7-tool surface; profiles withtoolsets: [kanban]and no task scope additionally see the two routing tools.Why these two and not all four
The original PR added 4 orchestrator tools (
kanban_list,kanban_assign,kanban_unblock,kanban_archive). This salvage keeps the two without workarounds:kanban_listis the discovery primitive — without it an orchestrator can callkanban_show(t_abc)only if it already has the ID. There's no other tool path to enumerate "what's in triage / blocked / P1".kanban_unblockis the recovery primitive — orchestrators routinely sweep the blocked column and lift blocks once external dependencies clear. No tool path otherwise (workers can't unblock foreign tasks, and the existingkanban_blockis the inverse only).kanban_assignandkanban_archiveare deferred — orchestrators can punt assign viakanban_create(parents=[...])workarounds and archive viakanban_complete. We can revisit if real users complain. Schema bloat is paid by every orchestrator turn; +2 tools instead of +4 is meaningful.Two-tier gating (orchestrator vs worker)
Adopted from the upstream PR's last commit: board-routing tools (
kanban_list,kanban_unblock) use a separate_check_kanban_orchestrator_mode()gate that returns False wheneverHERMES_KANBAN_TASKis set — so dispatcher-spawned task workers see only their 7 lifecycle tools (show/complete/block/heartbeat/comment/create/link). The worker-vs-orchestrator distinction is enforced both at schema-registration time (check_fn) and at handler-entry time (_require_orchestrator_toolruntime guard) for defense in depth.Changes
tools/kanban_tools.py: addkanban_list+kanban_unblockschemas/handlers; introduce_check_kanban_orchestrator_mode()and_require_orchestrator_tool()gates;kanban_listis bounded to 50 rows by default / 200 max withtruncated+next_limitmetadata so the model can paginate without dumping the board.toolsets.py: add the two new tools to the kanban toolset.tests/tools/test_kanban_tools.py: schema visibility tests for all three roles (worker / orchestrator / normal chat); handler happy-path + error-case coverage for both new tools; regression test that a worker withtoolsets: [kanban]in config still does NOT see board-routing tools.website/docs/user-guide/features/kanban.md+kanban-tutorial.md: list the two new tools in the worker tool table; clarify the worker-vs-orchestrator visibility split.Validation
tests/tools/test_kanban_tools.pytests/hermes_cli/test_kanban_db.py + test_kanban_core_functionality.py + test_kanban_cli.pytoolsets: [kanban], no env)Closes #20048 via salvage. Carve-out of #20568; original commits by @kallidean (Eric Litovsky) preserved in the cherry-picked feat + parsing fixes; the orchestrator-restriction commit is co-authored to retain credit for the two-tier gating design. AUTHOR_MAP entry added.
Issues #19931, #19932, and #20157 — the bigger architectural asks (specialist worker lane contracts, persistent lane registry, GitHub bridge) — are NOT addressed here. They were clustered with #20048 in triage but are separate scope and need a design call before any implementation.