Skip to content

feat(mcp): board column tools for the dashboard MCP server - #15432

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
Pearcekieser:feat/mcp-tag-columns
Oct 1, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
Pearcekieser:feat/mcp-tag-columns

Conversation

@Pearcekieser

@Pearcekieser Pearcekieser commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An agent can list the sidebar board's columns, add a column for a tag, and move a column next to another, through the dashboard MCP server.

The board (the Trello-style columns behind /api/chat/tag-columns) has no MCP tool. An agent that sorts its worker sessions with chat_tag_create and chat_tag_assign cannot see which columns exist, cannot add a column for a status tag it just created, and cannot place that column beside the related ones. The person does those steps by hand.

Why it matters

Agents that already manage folders, tags and pins stop one step short of the board view the person reads. Every new status tag an agent coins needs a manual trip to the board UI before it shows up as a column.

Not a goal

  • No delete, rename, retag, filter-mode or include_untagged edits from MCP. Those remove or change a view the person built.
  • No live-state lane creation from MCP; the board UI's lane toggle covers it.
  • No generic MCP verb registry; the tools use the existing hand-written pattern.

What changed (motivation → approach → change)

Agents get three board tools in mcp_dashboard.py (argument schemas in validation.py), and the board's write endpoints refuse the same agent principals the tag vocabulary refuses.

Tool Sends Result
chat_tag_column_list GET /api/chat/tag-columns Columns in board order, each with its id, name, and the tags or live-state lane it shows
chat_tag_column_create(name, tag) POST /api/chat/tag-columns with tag_ids: [tag] and ensure: true Appends a column for one existing tag. The endpoint returns an existing column with the same name and tag instead of a twin
chat_tag_column_move(column, before or after) PUT /api/chat/tag-columns/order with the full id list and base_ids Moves one column next to another; the rest keep their order. A board that changed since the read is refused 409 stale_base

The board is the person's own layout and has no owner, like the tag vocabulary, so the tools follow the chat_tag_create rules and the rules live in the endpoints. The four column write handlers in chat_tags.py (create, update, delete, reorder) call _refuse_vocabulary_write: an app agent or crew member gets 403 app_forbidden, and a caller naming a closed slot gets caller_unattributable. Both new body fields are opt-in and decided under the board's write lock: ensure closes the race where two agents creating the same column both append, and base_ids stops a stale full order from overwriting the person's reorder. The board UI sends neither, so its behaviour is unchanged. Each column write records the real caller in the SEL audit (request_origin), so an agent's board change is not logged as the person's. Column create draws on its own TAG_COLUMN_CREATE budget, charged only when a column is actually appended so an ensure retry costs nothing in create_rate_limit.py, the same size as the tag budget, and the browser stays exempt. The crew-member chat-route gate in handlers/_shared.py admits GET /api/chat/tag-columns only, so a member can list the board. The two writes are on the channel-agent blocklist in channel.py and are refused again at dispatch for a channel: caller, as chat_session_pin is.

There is no delete or retag tool: either would remove a view the person built. The tools are withheld from the unattended conductor grant list in agent.py, like the tag verbs. session-control.md (including the new budget and the channel block), docs/architecture/mcp.md, docs/index.md and mcp_tool_titles.json name the three tools. mcp_dashboard.py imports sel at module scope, as the top-level-imports rule asks.

Backwards compatibility

Breaking: an app-scoped or crew-member caller can no longer create, update, delete or reorder board columns over /api/chat/tag-columns (403 app_forbidden), and an internal caller creating more than 10 columns in 5 minutes gets 429. Writer sweep on origin/main @ 31a6511: the only writers are the dashboard board UI (website/src/pages/chat-sidebar/board.ts, browser caller, unaffected) and tests; no MCP tool, app or crew path wrote the board before this PR, and crew members were already refused at the route gate.

Tests

  • test/test_mcp_dashboard_tag_columns.py (new): list rendering and order, create body and the verified key, an existing column the endpoint returns reported as existing, unknown-tag and blank-name refusal, the app_forbidden message, the id order and base_ids a move sends, the stale_base message, the untagged-column label, a hand-edited non-list tag_ids rendered instead of crashing, the no-change, self-anchor and empty-side cases, a shared column name refused rather than guessed, and the channel refusal for both writes.
  • test/test_chat_tag_column_writers.py (new): every column write refuses an app, a member and a gone slot with the board unchanged; apps and members still read; the person keeps every write; ensure converges on one column while a create without it still appends; a stale base_ids is refused and a fresh one applied; the create budget holds for an internal caller and not for the browser, and an ensure retry does not spend it; ensure does not match a column that also shows untagged sessions or one whose persisted tag_ids is not a list; an MCP-driven create, ensure hit and reorder are audited as mcp/kirocrew-dashboard.
  • test/test_member_chat_folders_gate.py: the gate admits GET on the column list and nothing else under /tag-columns.
  • test/test_mcp_dashboard_registration.py: the granted set includes the three column tools.
  • test/test_session_control_doc.py: the page quotes the board-column budget constant.
  • test/test_mcp_dashboard_pin.py and test/test_mcp_dashboard_folders.py: patch sel where it now lives, and list the three column tools in the advertised set.

Manual verification

N/A — unit coverage sufficient: the tools are thin wrappers over existing endpoints whose behaviour is covered by the endpoint tests above, and there is no UI change.

Related Issues

Fixes #15425

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Sep 30, 2026
@dwu96

dwu96 commented Sep 30, 2026

Copy link
Copy Markdown
Contributor

👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review.

When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically.

@Pearcekieser
Pearcekieser marked this pull request as ready for review September 30, 2026 15:00
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Intent: Let an agent on the dashboard MCP server read the sidebar board, add a column for one existing tag, and move a column next to another, with the board's write endpoints refusing the same agent principals the tag vocabulary refuses.
Not a goal: Deleting, renaming or retagging columns, creating live-state lanes, or changing how the board UI writes columns.

@Pearcekieser
Pearcekieser requested a review from a team as a code owner September 30, 2026 15:00
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 30, 2026
@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of ae8352ebd8861e07c227047a82f04f5fb902a95e via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Confirm the breaking 403 fence on the pre-existing column write endpoints for app/crew callers is what #15425 asked for.

The change follows the tag-vocabulary precedent exactly (same refusal, same budget shape, same channel/dispatch split, refusals at the endpoint layer rather than the tool), the writer-sweep claim checks out against the base tree (the board UI in website/src/pages/chat-sidebar/board.ts is the only writer), ensure/base_ids are opt-in and lock-scoped so the browser path is untouched, and no docs/decisions/ entry covers the board. No rendered evidence is required: nothing under website/src/ changes.

[DESIGN-REVIEWED] ae8352e

Description read

[DESCRIPTION-READ] baa387668de15d99e6a2c44d8be2fafefe702a6bfbc655e4b7675124f4fd4f90

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of ae8352ebd8861e07c227047a82f04f5fb902a95e via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify one reversal: the member gate's pinned exclusion of /api/chat/tag-columns now admits GET — confirm members reading the board's tag/lane layout is intended.

What this change ships

Inventory (10 items, 1 more capped) — 10 justified

Intent: let an agent list, add, and place board columns via the dashboard MCP server — an ADDITION.

  1. Agents can list the board's columns (chat_tag_column_list) — justified
  2. Agents can add a column for an existing tag (chat_tag_column_create) — justified
  3. Agents can move a column before/after another (chat_tag_column_move) — justified
  4. App and crew-member callers now get 403 on all four board write endpoints — justified
  5. Opt-in ensure create field dedups under the write lock — justified
  6. Opt-in base_ids reorder field refuses a stale order with 409 — justified
  7. Internal callers get a 10-per-5-min column-create budget; browser exempt — justified
  8. Board writes are audited as the real caller, not "dashboard" — justified
  9. Crew members can now read the column list (gate admits GET only) — justified
  10. Channel agents are blocked from the two board writes, at prompt and dispatch — justified

Capped: an 11th item, sel imported at module scope in mcp_dashboard.py — rides along (declared chore, mandated by the top-level-imports rule).

[FIRST-PRINCIPLES-REVIEWED] ae8352e

Description read

[DESCRIPTION-READ] db35a37bb5ec65c3d0d49a75e5ee9aa0a6d134e31f5fcd55f5b4b710c9b74218

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed ae8352ebd8861e07c227047a82f04f5fb902a95e via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ae8352e

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

Reviewed ae8352ebd8861e07c227047a82f04f5fb902a95e via the fork AI-review pipeline; updated in place on each push.

Review details

The chat_tag_column_create tool advertises a safe no-op the endpoint's twin check does not deliver.

FINDING — src/kiro_crew/dashboard/chat_tags.py:1517 — _tag_column_twin also requires str(col.get("mode") or "any") and bool(col.get("include_untagged")) to match, so on a board where the person ticked the "include untagged sessions" checkbox (ChatSidebar.tsx:6313) or picked mode: "all" on their Doing column, the tool's fixed body {"name": safe_name, "tag_ids": [tid], "mode": "any", "ensure": True} finds no twin and appends a second column headed Doing — contradicting the description this PR adds ("calling this again is a safe no-op"), leaving a duplicate in the person's layout that no tool can remove (create-only server) and making that heading unusable for chat_tag_column_move, which then answers "{len(named)} columns share the name ..." → Fix: either restrict the twin comparison to name + tag_ids (the identity the tool controls), or drop the "safe no-op" sentence from the tool description and say the dedup also requires the same match mode and untagged setting.

[OPUS-REVIEWED] ae8352e

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 30, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • Fixed: function-local sel import (span=74c260d15da4)

Outcome: fixed in a344662.
mcp_dashboard.py imports sel at module scope. The pin handler's local copy was removed too, and its test patches kiro_crew.mcp_dashboard.sel.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • Fixed: column writes audited as the browser (span=14af36d9eaf9)

Outcome: fixed in a344662.
All four column handlers take (source, caller) from request_origin and pass it to every log_api_access row. The ensure twin-hit now writes its own audit row.
test_an_agent_write_is_audited_as_the_agent_not_the_browser asserts that an MCP create, an ensure hit and a reorder log mcp/kirocrew-dashboard.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • Fixed: unmeasured "end of the board" claim (span=a294930262a0)

Outcome: fixed in a344662.
The create result no longer states a position. It points the agent at chat_tag_column_move to place the column, and chat_tag_column_list shows the real order.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • Fixed: session-control page missed the new budget and channel block (span=0d67cfb96c8c)

Outcome: fixed in a344662.
The rate-limit sentence now names 10 board-column creates, and test_the_documented_limits_match_their_constants pins it to MAX_TAG_COLUMN_CREATES_PER_WINDOW. The channel paragraph names both blocked column writes.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in files this PR imports (mcp_tools/spawn.py, acp/skill_projection.py) since this head went green (aec8141 -> 2b91a6b); CI re-running. The same push carries the four advisory fixes answered above. The round-1 Windows shard red (test_session_transfer.py::test_concurrent_expansions_are_bounded_and_the_excess_is_refused) also fails on aec8141 without this change, and the round-1 lint job hit the 25-minute runner timeout.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 30, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • Fixed: move described as passing the conductor invariant (span=53782b78323f)

Outcome: fixed in the next head.
agent.py now lists chat_tag_column_move separately as WITHHELD on the invariant, because it mutates the order of columns the person arranged. List and create keep their "no conductor step needs them" reason.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • Fixed: empty before/after resolved as the literal "None" (span=a294930262a0)

Outcome: fixed in the next head.
The move handler normalizes an empty before/after to not-given before the exactly-one check, so {"before": ""} is refused and {"before": "", "after": X} moves after X. test_an_empty_side_counts_as_not_given covers both.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • Rebutted: one column per tag is not the intent (span=49a9b417289d)

Outcome: rebutted; the code stays as it is.
The board allows several columns on one tag, and the person builds them in the UI (for example, one heading per team). ensure exists to make a retry of the SAME create converge, so it keys on name, tag and mode.
Folding a differently named column into an existing one would drop the heading the caller asked for. test_same_tag_under_a_new_name_is_a_new_column pins this.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 30, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased: #15166 (session_end_wait) merged and conflicted in the tool lists and tool count in docs/architecture/mcp.md, src/kiro_crew/docs/index.md and src/kiro_crew/docs/session-control.md. Resolved by keeping both sets of tools (count 24 -> 27); no code change. Now on 2d4278a, and CI is re-running.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 30, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • Fixed: ensure retries spent the create budget (span=943bdd3ef2fa)

Outcome: fixed in the next head.
api_chat_tag_column_create now charges TAG_COLUMN_CREATE just before the append, under the write lock. An ensure twin-hit or an existing lane returns without spending it.
test_an_ensure_retry_does_not_spend_the_create_budget sends 13 ensure retries, then a fresh create, and gets 201.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • Accepted and deferred: an open sidebar does not refetch columns after an agent write (span=14af36d9eaf9)

Outcome: accepted-and-deferred to #15558.
The gap is real, but it is not new to this PR. The tag vocabulary has the same one today: chat_tag_create / chat_tag_update writes are not pushed to ['chat-tags'] either, because both queries keep staleTime: Infinity and only browser mutations invalidate them.
The fix is a generation counter on the WS slots frame for both keys, like foldersGeneration. It spans state.py, ws.py and slotList.ts, which is a frontend sync change outside this PR's backend-only scope. #15558 names that task.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 30, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased onto 3ecea02 with the design-lane budget fix answered above; CI re-running. Maintainer ask: the Opus finding is deferred to #15558, which needs the deferred-finding label and an assignee. A fork contributor cannot set either.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 30, 2026
chat_tag_column_list, chat_tag_column_create and chat_tag_column_move let an agent read the sidebar board, add a column for one existing tag, and move a column next to another. The four /api/chat/tag-columns write handlers apply _refuse_vocabulary_write, column create gets its own TAG_COLUMN_CREATE budget, the member chat-route gate admits GET on the list only, and the two writes are blocked for channel agents.

Fixes kirodotdev#15425
@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • Fixed: a hand-edited non-list tag_ids aborted the board tools (span=87b6117c9a6b)

Outcome: fixed in ae8352e.
_chat_tag_column_label treats a tag_ids that is not a list as no filter ("all sessions"). _tag_column_twin treats such a column as not a match, so neither iterates the value.
Tests: test_a_hand_edited_non_list_tag_ids_renders_instead_of_crashing for the list tool, and test_ensure_skips_a_hand_edited_column_with_non_list_tag_ids, which gets 201, for create.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • Fixed: ensure twin ignored include_untagged (span=f3e008276bed)

Outcome: fixed in ae8352e.
_tag_column_twin now also requires an equal include_untagged, so a column that also shows untagged sessions is not returned for a plain tag create.
test_ensure_does_not_match_a_column_that_also_shows_untagged covers it.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased onto current main with the two GPT fixes answered above; CI re-running. The round-4 Windows shard 7 red was test_runtime_cleanup_windows.py::test_windows_failed_owner_drain_recovers_after_owner_drop, which is outside this diff.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 1, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed. Three tools (list, create with ensure, move with base_ids compare-and-set), no delete/rename/retag tool and a test pins that. _refuse_vocabulary_write is the first statement in all four chat_tags.py handlers (app agents and crew members get 403 app_forbidden); handlers/_shared.py admits members to GET only on the exact collection path, so /{id} and /order are refused at the gate too; channel: callers refused by the blocklist and again at dispatch. Names redacted, stripped, capped at 60; ambiguous name refused. TAG_COLUMN_CREATE rate limit charged only on an actual append from a non-dashboard source. Deleting a column removes only the view, never session tags.

Non-blocking: mcp_dashboard.py move builds base_ids from string ids only while the endpoint compares str(id), so a hand-edited non-string id would stale_base every move.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(mcp): board column tools (chat_tag_column_list/create/move)

3 participants