Skip to content

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

Merged
bolichen97 merged 2 commits into
mainfrom
feat/chat-folder-delete-tool
Oct 3, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
feat/chat-folder-delete-tool

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An agent that organizes sidebar sessions can delete a folder it created and has emptied, and never a folder the person made or uses.

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.
  • Deleting a folder the person created, reused, edited, or filed a session into, even when it is empty. An empty folder can still be one the person relies on.
  • 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:

  • chat_folders.py: an agent create (internal secret plus a live X-Session-Key) stamps created_by_session on the NEW row; a same-name reuse returns the existing row unmarked. A browser write removes the field for good when it renames, moves, restyles, hides or regenerates the icon of the folder, or moves another folder into it (api_chat_folder_update; collapsed and order alone do not count), files a session into it (api_chat_slot_folder), opens a chat in it (api_chat_slot_create), or nests a folder under it (create_folder_record). Each removal runs in the same locked folder-store step as its write. The if_empty delete refuses with 403 folder_not_agent_owned unless the row still carries the caller's own key, checked again under the lock. A row from before this field has none, so every existing folder reads as the person's. The field is on the row in folders.json, so it survives a restart.
  • 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 28 to 29, 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), creator rules: a folder the person created is kept; another session's folder is kept; reusing the person's same-name folder does not mark it; a browser call carrying a session key is not an agent; a person's rename, colour, hide, move or icon regenerate claims it; a person moving a folder in and back out claims the parent; a collapse or reorder does not; an agent's own rename keeps the mark; a session the person filed then removed, or a subfolder the person made then deleted, leaves the folder claimed; the mark and a claim both survive a reload of folders.json.
  • Same file, emptiness rules: 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. After adding the creator rules: every test file that touches the folder routes (64 files, 5,387 tests) passes; black, isort, flake8 and mypy are clean on the changed files.

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

@chenmingwei23
chenmingwei23 requested a review from a team as a code owner October 1, 2026 07:08
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 1, 2026
@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Check that every browser path that puts a session in a folder clears created_by_session, not just the four call sites this patch changes.

Suggestions

  • The "person claimed this folder" rule now lives at separate call sites: api_chat_folder_update, api_chat_slot_folder, api_chat_slot_create and create_folder_record. A future sidebar write path that forgets to drop the mark would quietly let an agent delete an empty folder the person relies on. Clearing the mark in one place, wherever a dashboard-origin write reaches the folder store, would close that off.

[DESIGN-REVIEWED] d5a669e

Description read

[DESCRIPTION-READ] 51720aaf3f07523646cb2701e1a4b991f48cc77c930edf71af31c759b54f4d81

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 1, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of d5a669e8fe9f6d748f2b6fbf2c46e22e645f0c11 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] d5a669e

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

@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of d5a669e8fe9f6d748f2b6fbf2c46e22e645f0c11 — 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

Before merge, a human should accept the residue the PR records: a session filed and closed during the archive scan keeps a dangling folder id.

What this change ships

Inventory (8 items) — 7 justified

Intent: an agent can clean up an empty sidebar folder it created itself, and never one the person made or uses. ADDITION.

  1. Agents gain a chat_folder_delete tool on the dashboard server that removes only empty folders — justified
  2. The folder-delete route gains an ?if_empty=true mode that checks occupancy under the store lock and refuses with 409 — justified
  3. A folder created by an agent through MCP now stores created_by_session in folders.json, and the mark survives restarts — justified
  4. When the person edits, files into, opens a chat in, or nests under a folder, the mark is removed for good — justified
  5. Any agent delete of a folder it didn't create, or one the person has claimed, is refused with 403 folder_not_agent_owned — justified
  6. _delete in mcp_core accepts the verified session_key — justified
  7. The conductor grant audit lists the verb as WITHHELD — rides along
  8. Session-control docs, tool count 28→29, MCP docstring, tool title — justified

[FIRST-PRINCIPLES-REVIEWED] d5a669e

Description read

[DESCRIPTION-READ] 869a10b0263a4be6c9a084daa2620cdfeb172cfd41d03999f32343831e6f9d0b

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 added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 1, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/chat-folder-delete-tool branch from 82ca546 to 7330a7c Compare October 1, 2026 07:56
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Rebased onto main to pick up the vector_memory row-stem helper fix that was failing Windows shard 6 (test_vector_memory_composition_contract). No change to this PR's diff. New head 7330a7c. The previous head's review-lane reds were GitHub API rate-limit failures, not verdicts.

@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 1, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/chat-folder-delete-tool branch from 7330a7c to 70df1ec Compare October 1, 2026 08:04
@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 1, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/chat-folder-delete-tool branch from 70df1ec to 7577478 Compare October 1, 2026 08:17
@chenmingwei23

chenmingwei23 commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=f261602aa4b3: docs/architecture/mcp.md still says no MCP tool exposes deletion

Outcome: fixed in 7577478.
The app-delete paragraph now says the verb is withheld from apps, and a new paragraph names chat_folder_delete, its if_empty mode, which checks run inside the locked folder-store step, and the one seam left open.

@chenmingwei23

chenmingwei23 commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=662daedae348: the close-during-scan seam ships as undeclared residue

Outcome: declared, in the PR body (new Known residue section) and in docs/architecture/mcp.md, as of 7577478.
A session filed and then closed inside the one archive scan is in neither store at the locked check, so its archived transcript keeps the gone folder id. Nothing in the transcript is lost and every reader renders it as unfiled, the same state the full sidebar delete leaves on every archived session it removes the folder of. Closing it needs a registry of in-flight closes across about twenty slot-removal sites, which this verb does not justify.

@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 1, 2026
@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

FINDING: the new empty-only delete skips the cron-job and channel references that the bulk cleanup checks.

FINDING — src/kiro_crew/dashboard/chat_folders.py:2276 — the empty-only delete can remove an agent-created folder that a person's saved cron job still names. In _remove_if_empty, the if_empty branch checks only parent_id children and live state._slots. It never reads state.crons.chat_folder_ids_async() or channel_folder_names(), which the bulk api_chat_folder_cleanup treats as referents. A cron save does not clear CREATED_BY_SESSION, so chat_folder_delete still succeeds. The job's later tab then lands unfiled, logged by cron_inject as "chat folder %s is gone". → Fix: in the if_empty branch, read the cron folder ids and channel folder names the way _referents() does, and refuse with folder_not_empty when either one names fid.

[OPUS-REVIEWED] d5a669e

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

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

@chenmingwei23
chenmingwei23 force-pushed the feat/chat-folder-delete-tool branch from 5d50388 to badd74f Compare October 1, 2026 10:15
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

/ai-review override gpt badd74f: The residue is one session closed during the archive scan whose transcript keeps a deleted folder id and renders as unfiled, with no transcript loss and the same state the sidebar delete already leaves archived sessions in, documented under Known residue.

@github-actions

github-actions Bot commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

Human judgment recorded

@chenmingwei23 marked the gpt AI finding as false positive, not applicable, or explicitly accepted for badd74fe5e80a137a64788bf8939d466c9ef578b.

The residue is one session closed during the archive scan whose transcript keeps a deleted folder id and renders as unfiled, with no transcript loss and the same state the sidebar delete already leaves archived sessions in, documented under Known residue.

This decision applies only to this commit. A new push requires a new judgment.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Oct 1, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Read-only review note, leaving approval to a maintainer because it deletes a folder row and there is no 'only folders you created' rule: any person-scoped session can delete any empty folder, including an app-owned one (apps themselves are refused at :2098 and :2135). Under the lock _remove_if_empty re-checks existence, no child and no live slot, so no live session is unfiled and no subfolder lifted. The archived-session count (:2165) is a disk scan before the lock, so a session filed and closed during the scan ends up unfiled (disclosed). Gaps: no if_empty route test for an app or member caller (the MCP test mocks the refusal), and the crew-member refusal was not confirmable from the diff alone.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 2, 2026
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.
@chenmingwei23
chenmingwei23 force-pushed the feat/chat-folder-delete-tool branch from badd74f to 0e05e31 Compare October 3, 2026 04: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: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 3, 2026
…untouched folder

An agent create now stamps the creating session's key on the new folder
row as created_by_session. A browser write that renames, moves, restyles
or hides the folder, files a session into it, opens a chat in it, or
nests a folder under it removes the field for good; collapsing it or
reordering its siblings does not. The empty-only delete refuses with
403 folder_not_agent_owned unless the row still carries the caller's own
key, decided under the folder-store lock with the occupancy checks, so a
folder the person created or reused is never removed by an agent.

Emptiness is decided under the same lock: subfolders and live slots are
re-checked in the locked step that removes the row.
@chenmingwei23
chenmingwei23 force-pushed the feat/chat-folder-delete-tool branch from 0e05e31 to d5a669e Compare October 3, 2026 05:08
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision 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 commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

@chenmingwei23 — handing this back to you. The rebase-onto-main replacement (#16337) is being closed so you can finish the design here. Summary of what's outstanding:

First Principles objection (design): the new delete-empty-folder path (?if_empty=true) duplicates the existing POST /api/chat/folders/cleanup, which already deletes an empty folder under the store lock. First Principles wants the second spelling removed rather than hardened in parallel.

Fenced GPT security block (chat_folders.py:2248): the archive-scan close race (a filed-and-closed session during the off-loop archive disk scan) is security-fenced; it is adjudicated LOW (lost folder placement renders as Unfiled and is re-fileable, transcript intact) but clears only via a human /ai-review override.

Maintainer direction: track folder creation through a NEW crew-log event, so chat_folder_delete can check who created a folder from the crew log instead of the current approach. That gives the delete a durable provenance signal and avoids the parallel occupancy checks the reviews objected to.

Keeping this PR open for you to pick up.

@bolichen97 bolichen97 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.

LGTM. Delete is empty-only and owner-gated: the created_by_session mark is re-checked with subfolders and live slots under the folder-store lock, and any person edit clears the mark. Archived count sits outside the lock, which the comment names as accepted residue. Tool stays withheld from conductor specs until a skill needs it — good.

@bolichen97
bolichen97 merged commit b3bc324 into main Oct 3, 2026
99 of 105 checks passed
@bolichen97
bolichen97 deleted the feat/chat-folder-delete-tool branch October 3, 2026 06:06
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 3, 2026
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.

3 participants