Skip to content

feat(mcp-dashboard): chat_folder_delete removes an empty sidebar folder - #16337

Closed
iamwhatever wants to merge 2 commits into
mainfrom
rebase/15753-chat-folder-delete
Closed

iamwhatever wants to merge 2 commits into
mainfrom
rebase/15753-chat-folder-delete

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Replaces #15753 by @chenmingwei23, rebased onto current main. Their two commits are preserved with authorship intact (Rebase-and-merge lands their commits). This PR exists only because #15753 could not be fast-forwarded after main moved; the change itself is unaltered beyond conflict resolution.

Rebase notes

main has since added chat_folder_file_self and session_reload to the kirocrew-dashboard set and bumped the documented tool count. The two doc conflicts (docs/architecture/mcp.md tool-inventory row, src/kiro_crew/docs/index.md Session Control row) were resolved to keep both main's additions and this PR's chat_folder_delete, and the documented tool count is now 29 (not 28) across index.md and session-control.md. No code conflicts; all auto-merged hunks verified.

Overlap with #16331 (delete_contents, replacing #13878): that in-flight PR adds an opt-in delete_contents subtree-delete to folder deletion and touches the same files (chat_folders.py, mcp_dashboard.py, validation.py, mcp_tool_titles.json, docs). This PR is the complementary empty-only delete. They are not mutually exclusive — one adds ?if_empty=true, the other adds a subtree mode — but whichever lands second will need a small rebase over the other's edits to the shared tool list / count / schema registry. No conflict exists against current main.


Problem / Motivation

Goal: An agent that organizes sidebar sessions can delete a folder it has emptied.

The kirocrew-dashboard MCP server can read the folder tree, create folders, move folders and file sessions into them, but it has no delete verb. When an agent moves every session out of a folder, the empty folder stays in the sidebar and the person has to delete it by hand. An agent asked "delete these empty folders" can only answer that it has no tool for it.

Why it matters

Session control creates folders as a side effect (session_create with folder=, chat_folder_file_self, mkdir -p in chat_folder_create). Every workstream an agent stands up leaves folders behind, and the only cleanup path is clicking each one in the sidebar.

Not a goal

  • Deleting a folder that holds anything (subfolders, live sessions, archived sessions). That relocates the person's filing, and stays a sidebar action.
  • Letting an app agent or a crew member delete folders. DELETE /api/chat/folders/{id} keeps refusing both.
  • Granting the new verb to the conductor agents' auto-approved set.

What changed (motivation -> approach -> change)

Goal: remove a folder with nothing in it, without giving the MCP set any way to unfile or relocate a session.

Approach: the tool calls the existing DELETE /api/chat/folders/{id} route with a new ?if_empty=true mode. The emptiness check has to live in the endpoint: a check in the tool reads the tree, then deletes, and a session filed in between would be unfiled by the full delete (review caught this on the first head). Empty-only keeps this server's posture: nothing it does can unfile a session, lift a subfolder or leave an archived session pointing at a gone folder.

Change:

  • mcp_dashboard.py: new chat_folder_delete(folder). It passes the same _refuse_tree_shaping_if_unverifiable gate as create/move, resolves the folder by id or path, refuses root, and sends DELETE ...?if_empty=true with the verified caller key. A folder_not_empty refusal is returned with a hint to empty the folder first. Module docstring updated.
  • chat_folders.py (api_chat_folder_delete): new if_empty mode. It counts archived sessions first (a disk scan, off the loop), then re-checks subfolders and live slots inside the mutate_folders callback that removes the row. A slot PATCH sets folder_id before it re-checks the folder under that same lock, and a child create checks its parent there too, so neither can land between the check and the removal. The mode never unfiles a slot or lifts a subfolder; refusals are 409 folder_not_empty and carry no count or name. The plain DELETE the sidebar sends is unchanged.
  • mcp_core._delete: takes session_key= like _patch / _put, so a strictly-verified key is what reaches the endpoint.
  • validation.py: CHAT_FOLDER_DELETE_SCHEMA, registered in MCP_DASHBOARD_SCHEMAS.
  • agent.py: conductor grant audit records the verb as WITHHELD.
  • Docs: docs/architecture/mcp.md (the app-delete section now names this tool and its one residue), session-control.md (tool table, count 27 to 28, note on the empty-only rule), docs/index.md count, docs/architecture/mcp.md tool list, mcp_tool_titles.json title.

Known residue

One seam stays open, by choice. A session that is filed into the folder and then closed while the archive scan runs is in neither store when the locked check runs: closing pops it from the live slot table before its archival save lands. The delete then proceeds, and that archived transcript keeps the gone folder's id. Nothing in the transcript is lost: every reader renders a session whose folder is gone as unfiled, which is the state the person's full sidebar delete already leaves on every archived session in the folder it removes. It needs the person to file and close a session into the very folder their own session is deleting, inside one disk scan; apps are refused before any of this runs. Closing it would mean registering every in-flight close across all of the slot-removal paths (about twenty pop sites), which this verb does not justify. docs/architecture/mcp.md records the same.

Backwards compatibility

Compatible: one new tool, one optional keyword argument on _delete, and one optional query flag on the delete route. Without the flag the route behaves exactly as before.

Tests

  • test/test_chat_folder_delete_if_empty.py (new, real route): deletes an empty folder; refuses a live session, a subfolder and an archived session without unfiling or lifting anything; a session filed during the archive scan is still seen and still refused; a folder deleted during the scan answers 404; without the flag a full folder is still deleted and unfiled as before.
  • test/test_mcp_dashboard_folders.py::TestFolderDelete: sends ?if_empty=true with the verified key; does no tree pre-check of its own; surfaces a folder_not_empty refusal without naming a session; refuses root and an unknown folder without writing; surfaces the endpoint's app refusal verbatim; refuses an unverifiable caller; requires folder.
  • test/test_mcp_dashboard_registration.py and TestAdvertisedSet: the ratcheted tool set includes chat_folder_delete.
  • test/test_session_control_doc.py passes against the updated page and count.

Ran locally: the files above plus the conductor, session-control, member-gate, caller-identity and call-site-auth suites (about 2,300 tests), all green.

Manual verification

N/A: the tool is a proxy over an existing route whose person / app / member behavior is already covered by the route tests; the new logic is the empty-only gate, which the unit cases exercise.

Related Issues

no linked issue: new tool request from the dashboard owner

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • 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

The dashboard MCP server could create, move and file into sidebar folders
but had no way to remove one, so an agent that organized sessions left
every emptied folder behind for the person to delete by hand.

chat_folder_delete deletes a folder only when it holds no subfolder, no
live session and no archived session, so it never unfiles or relocates
anything. The endpoint still refuses every app and crew-member caller.
@iamwhatever
iamwhatever requested a review from a team as a code owner October 3, 2026 00:23
@iamwhatever
iamwhatever requested a review from bolichen97 October 3, 2026 00:23
@github-actions

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — 🟡 CONCERNS

Design-level review of 8530d12d03ba00e98199c4a46f98b117935e07cb — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

The description and the remediation hint both say "empty-only", but the endpoint also refuses empty folders for cron, channel and saved-settings reasons that the agent cannot fix.

Watch

  • The description doesn't match the diff. ## What changed lists three occupancy checks: live sessions, subfolders and archived sessions. The if_empty branch goes further. It also refuses a folder that a cron job references, that a channel references, that carries _keeps_itself settings (project_dir/default_agent/steering_dirs/tags/color/icon), or whose id appears twice in the store. When it cannot read those references it answers with a new fail-closed 503, folder_refs_unreadable. The diff also adds a crew-member refusal "in EITHER mode", and a channel.py block plus a dispatch-time refusal for channel: callers. None of this appears in the description. So no human ever agreed that, for example, an empty folder with an icon is out of the tool's reach, and the documented tests cover none of these paths.
    Clears when: the description lists each extra refusal (cron, channel, settings, duplicate id, 503, member, channel caller) with its reason and the test that pins it.
  • One error code covers refusals that need different fixes. Every reason from _remove_if_empty comes back as "code": "folder_not_empty". The MCP tool turns that code into the hint "Empty it first with chat_folder_move / chat_folder_move_session …". Now take a folder that is already empty and is refused because of a cron reference or an icon. The agent is told to empty it, can't, and either loops or tells the user something false.
    Clears when: settings, cron and channel refusals return a separate code (e.g. folder_kept), and the tool tells the agent the person has to remove the setting or reference first.

[DESIGN-REVIEWED] 8530d12

Description read

[DESCRIPTION-READ] 248ee12f03780e73ede2e002973c423c0499d401c9f21d88bd994b60ca486a2b

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 Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🔴 BLOCK

Premise-level review of 8530d12d03ba00e98199c4a46f98b117935e07cb — 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: BLOCK

The new ?if_empty=true delete mode copies POST /api/chat/folders/cleanup, which already deletes one previewed folder only if it is empty, checked under the store lock.

Not justified as shipped

  • Item 2 — duplicate of src/kiro_crew/dashboard/chat_folder_cleanup.py::api_chat_folders_cleanup. The diff says "The bulk-cleanup path treats both as occupancy… the empty-delete has to as well", and then copies that path's _referents/prepare read, its duplicate-id refusal, its icon-epoch cleanup and its push.
    Subtraction: delete the if_empty branch from api_chat_folder_delete. The tool already fetches /api/chat/folders, so it can refuse when that row's history_count > 0, then POST cleanup {ids:[fid], include_top_level:true} and read deleted.
    Clears when: the branch is removed, or the PR names a guarantee the cleanup route plus history_count cannot give.
  • Item 4 — inherited: "the auth middleware already admits only PATCH on this path for a member". The only stated harm is "a later change to the admitted method set", which is speculative. The change also touches the person's full-delete route.
    Subtraction: delete the member_principal refusal block.
    Clears when: the block is removed, or a path is shown that reaches it today.

What this change ships

Inventory (8 items) — 4 justified

Intent: let an agent delete a sidebar folder it has emptied. This is an ADDITION.

  1. Agents mounting kirocrew-dashboard get a chat_folder_delete tool that only deletes empty folders — justified
  2. The DELETE folder route gets an empty-only ?if_empty=true mode — duplicate of chat_folder_cleanup.api_chat_folders_cleanup
  3. The empty-only delete also refuses a folder with cron or channel references, saved settings, or duplicate ids — undeclared
  4. The endpoint refuses crew-member callers in both delete modes — rides along; middleware already refuses
  5. Channel agents are refused at dispatch and blocklisted for the tool — undeclared
  6. The channel refusal text for the existing board-write tools is reworded — rides along
  7. _delete sends the verified caller session key — justified
  8. Tool title, tool list and the doc tool count (29) are updated — justified

Blockers

Second spelling of the folder cleanup delete
Two routes now decide whether a folder is empty. Both run chat_folder_ids_async, channel_folder_names and _keeps_itself inside mutate_folders(prepare=…), and both refuse duplicate ids and drop icon epochs. The only difference is the archived-session check, and GET /api/chat/folders already returns it as history_count, which the tool already reads. Item 2's subtraction resolves it.
Clears when: the if_empty branch is deleted and the tool calls the cleanup route.

[FIRST-PRINCIPLES-REVIEWED] 8530d12

Description read

[DESCRIPTION-READ] eb6e39cfd76ce1cc270190d9f27ca81ea4c5cfbf1b5790fecd7ffb73ff2c6d14

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 Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — 🔴 changes requested (blocking)

GPT 6.1 found at least one blocking issue that must be resolved before merging 8530d12d03ba00e98199c4a46f98b117935e07cb. 1 of 1 blocking finding(s) are security-class and were withheld from adjudication, so the blocking verdict stands.

This comment is updated in place on each push.

BLOCKING -- src/kiro_crew/dashboard/chat_folders.py:2329 -- Empty-only deletion loses a concurrently archived session’s filing

folders[:] = [f for f in folders if f["id"] != fid]
Filing and closing a session during _folder_history_counts → api_chat_slot_folder persists its placement, then _close_slot pops it → stale archive counts and the empty live-slot check permit deletion → resuming the session clears its dangling folder_id, losing the saved placement.
Anchor: residual/crash-data-loss-corruption
Fix: Serialize the archive scan and removal against filing and close-to-archive transitions, so occupancy cannot escape both checks.
[BLOCK-MERGE] 8530d12
[GPT-REVIEWED] 8530d12

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

F1 (fenced): The harm is real but small: the session loses its folder placement, while its transcript survives and shows as unfiled. Every step it needs is in the code:

  • The archive count is a disk scan run outside the lock (chat_folders.py:2248).
  • The live-slot re-check under the lock only sees slots that are still open (:2320).
  • So a session that is filed and then closed inside that one scan gets past both checks before the row is removed (:2329).
  • Only the person's own session or the dashboard can send this delete; apps and crew members are refused earlier (:2188, :2221).
  • The handler documents this exact gap as a known leftover risk (:2231-2238, :2179).

Recovery: the person files the session into a folder again by hand. No transcript content is lost.

[ADJUDICATION] 8530d12d03ba00e98199c4a46f98b117935e07cb total=0 uphold=0 downgrade=0
[GPT-ADJUDICATED] 8530d12d03ba00e98199c4a46f98b117935e07cb

[ADJUDICATION-FENCED] 8530d12d03ba00e98199c4a46f98b117935e07cb fenced=1 flagged=1
FLAG F1 src/kiro_crew/dashboard/chat_folders.py:2329 -- Reaching this needs the person to file and close a session in the same folder they are deleting with if_empty during the off-lock archive scan (:2248); only the person's own session or the dashboard can send that delete (apps and members are refused at :2188/:2221), the transcript survives and only its folder placement is lost (it can be filed again by hand), and the handler already documents this gap (:2231-2238).
[GPT-ADJUDICATED-FENCED] 8530d12d03ba00e98199c4a46f98b117935e07cb

🏷️ Fenced finding(s) machine-flagged as likely edge case

The security fence keeps these findings blocking regardless of adjudication; the only clearance path is a human override. The annotate-only pass judged the condition combination each one requires extreme, and pre-drafted the override rationale below. A repository writer must independently verify a rationale before posting it — it is machine-authored, and a wrong override on a security-class finding ships exactly the class the fence exists to stop.

  • F1 src/kiro_crew/dashboard/chat_folders.py:2329 — Reaching this needs the person to file and close a session in the same folder they are deleting with if_empty during the off-lock archive scan (:2248); only the person's own session or the dashboard can send that delete (apps and members are refused at :2188/:2221), the transcript survives and only its folder placement is lost (it can be filed again by hand), and the handler already documents this gap (:2231-2238).

    /ai-review override gpt 8530d12d03ba00e98199c4a46f98b117935e07cb: Reaching this needs the person to file and close a session in the same folder they are deleting with if_empty during the off-lock archive scan (:2248); only the person's own session or the dashboard can send that delete (apps and members are refused at :2188/:2221), the transcript survives and only its folder placement is lost (it can be filed again by hand), and the handler already documents this gap (:2231-2238).
    

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 8530d12d03ba00e98199c4a46f98b117935e07cb: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 8530d12d03ba00e98199c4a46f98b117935e07cb — this comment is updated in place on each push.

Review details

No findings block this merge.

FINDING — src/kiro_crew/mcp_dashboard.py:528 — a folder_not_empty 409 can come from "folder holds saved settings or a channel reference" or "folder is referenced by a saved cron job", but the tool still tells the agent to "Empty it first with chat_folder_move / chat_folder_move_session". Neither tool can clear those causes, so the agent is sent to do work that cannot unblock the delete. The table row in session-control.md:528 also lists only the subfolder, live-session and archived-session refusals. → Fix: give the settings and reference refusals their own code (or show the hint only for the occupancy reasons), and list the cron, channel and saved-settings refusals in the docs row.

[OPUS-REVIEWED] 8530d12

Verdict parsed from the review's SHA-scoped output markers for commit 8530d12d03ba00e98199c4a46f98b117935e07cb.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 8530d12d03ba00e98199c4a46f98b117935e07cb: <one-sentence reason>

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Oct 3, 2026
@iamwhatever
iamwhatever force-pushed the rebase/15753-chat-folder-delete branch from a2af94c to 0ff774c Compare October 3, 2026 01:47
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 3, 2026
@iamwhatever
iamwhatever force-pushed the rebase/15753-chat-folder-delete branch from 0ff774c to 40a336b Compare October 3, 2026 02:09
@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 Oct 3, 2026
@iamwhatever
iamwhatever force-pushed the rebase/15753-chat-folder-delete branch 5 times, most recently from 0728b30 to 0468a28 Compare October 3, 2026 03:39
…tore lock

Review found that the tool checked subfolders and live sessions, then sent a
plain DELETE. A session filed between that read and the DELETE was unfiled by
the full delete.

The tool now sends ?if_empty=true. In that mode the endpoint counts archived
sessions first, then re-checks subfolders and live slots inside the folder-store
mutation that removes the row. A slot PATCH sets folder_id before it re-checks
the folder under the same lock, and a child create checks its parent there too,
so neither can land between the check and the removal. The mode never unfiles a
slot or lifts a subfolder. The plain DELETE the sidebar sends is unchanged.
@iamwhatever
iamwhatever force-pushed the rebase/15753-chat-folder-delete branch from 0468a28 to 8530d12 Compare October 3, 2026 03:52
@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 Oct 3, 2026
@iamwhatever

iamwhatever commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor Author

Closing this replacement PR so @chenmingwei23 can finish the design on #15753. Thanks — the rebase onto current main is done and 5 GPT/Opus findings were fixed, but First Principles asks for a different design (route folder-delete through the existing cleanup mechanism rather than a new if_empty path), which is an author call best finished on the original PR. See #15753 for the handoff and maintainer direction.

@iamwhatever iamwhatever closed this Oct 3, 2026
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 3, 2026
@bolichen97
bolichen97 deleted the rebase/15753-chat-folder-delete branch November 6, 2026 07:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants