Repository navigation
feat(agents): manage agent templates from an Agent templates tab - #12481
Conversation
|
Intent: Give the shared agent templates under |
Design Review (Fable 5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS The delete guard's holder list is completeness-by-convention: any future store that persists a template name silently reopens the dangling-reference hole the guard exists to close. WatchThe guard enumerates six holder kinds by hand ( [DESIGN-REVIEWED] 7b46278 |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS Apply & Restart's new confirm dialog is an added step every Capabilities-tab user pays, justified only by a hypothesis about hesitant readers — no named failure. Not justified as shipped
What this change shipsInventory (10 items) — 8 justifiedIntent: let a user see, edit, create, and retire the shared agent templates from the dashboard instead of hand-editing files under
More items exist (13 locale catalogs, spec/docs updates in the same commit — both mandated by documented invariants); capped at the 10 a person would notice. [FIRST-PRINCIPLES-REVIEWED] 7b46278 |
UX Review (Fable 5) — 🟡 CONCERNSUX-level review of UX-Verdict: CONCERNS Users still won't dare press Apply & Restart — its reassurance lives behind the click, and nothing shows which running chats it would touch. Watch
Suggestions
[UX-REVIEWED] 7b46278 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 4.8 Review — ✅ no blocking findingsReviewed Review detailsI've reviewed the full backend logic ( No findings. [OPUS-REVIEWED] 7b46278 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
35c3e11 to
7a87e87
Compare
|
|
|
|
|
|
|
|
|
|
|
7a87e87 to
5a255dd
Compare
GPT 5.6 Review —
|
|
|
|
|
|
|
|
GPT 5.6 Review — 🔴 changes requested (blocking)GPT 5.6 found at least one blocking issue that must be resolved before merging This comment is updated in place on each push. BLOCKING -- src/kiro_crew/dashboard/handlers/agent_templates.py:831 -- Schedule creation can race template deletion |
|
The definitions a chat or a crewmate runs had no management surface of
their own. The crew editor's Template pane edits one crew's PRIVATE copy
of a template, so a template no crew is bound to -- every freshly
installed package agent -- had nowhere to be seen, and the dashboard could
change only a template's model and skills. Creating a template meant
publishing some crew's private copy; deleting one meant removing the
file by hand.
Add an Agent templates tab beside Crews under Agent Capabilities. It
lists every installed global template by origin (Mine / Private copies /
From packages / Built-in) with what still runs it, edits an owned
template's description, model, prompt, tools and auto-approval marks as
one draft, edits skills through the existing skills editor, and shows
resources and MCP servers read-only. A package, runtime, markdown or
private-copy template is read-only with Duplicate to edit. New template
starts blank or copies an installed one; Delete is refused with the
reference list while a crewmate, the default agent, a schedule or a
private copy still names the template. Chat with this template opens a
chat in the template namespace; Enroll as crewmate binds a member to it.
Backend: `handlers/agent_templates.py` adds `GET/POST /api/agents/
templates` and revives `DELETE /api/agents/detail/{name}` from the
handler retired with the old standalone page, keeping its lock
discipline and widening the reference guard to schedules and private
copies. The detail PATCH accepts the definition keys and refuses them on
a read-only spec (`409 template_read_only`).
|
|
|
|
|
|
|
|
|
|
|
|
|
Problem / Motivation
The definitions a chat or a crewmate runs — the agent templates under
~/.kiro/agents/— have no management surface of their own. The crew editor'sTemplate pane edits one crew's private copy of a template (blueprint
semantics), so a template no crew is bound to, which is every freshly installed
package agent, has nowhere to be seen. The dashboard can change only a template's
model and skills; prompt, tools and description say "edit the file". Creating a
template means publishing some crew's private copy; deleting one means removing
the file by hand and hoping nothing still points at it.
Why it matters
#12224 made templates first-class execution choices in chat without enrolling
them as crewmates. That only pays off if a user can also see, edit, create and
retire templates in the app: otherwise "try this template" leads to a file the
UI cannot show. And a delete done on disk while a crewmate, a schedule or a
private copy still names the template leaves sessions that silently start on
the default agent — the exact failure a guard in the product prevents.
What changed (motivation → approach → change)
Goal: manage the shared templates themselves, beside the pane that manages
private copies, without changing what either a crewmate or a private copy is.
Approach: one read-only roster endpoint that returns editability and references
with each row, so the tab can say up front what it can edit and what a delete
would hit; the existing detail PATCH widened to the definition keys, gated by a
server-side read-only rule; and the template delete rebuilt from the handler
this repo retired with the old standalone page (lock discipline and 409 guard
kept, guard widened). MCP servers stay read-only on purpose — a server is a
capability grant with its own admission path.
src/kiro_crew/dashboard/handlers/agent_templates.py(+routes/agents.py):GET /api/agents/templates— every global discovery row (package-controlledstrings through
_roster_mask, as the sibling rosters do) plusread_only(
null, orpackage/runtime/markdown/private_copy; a row withno spec file beneath the agents directory — an edition catalog row with an
empty or foreign
filename— isruntime, never offered an action thatcould only 404) and
used_by(crews, the default agent, schedules by what they dispatch — a multi-entry
agent_sequenceover a dormantagent_id, else the capturedexecution_context.template_id— where the dispatcher reads the template ajob runs, and the ONLY place a schedule created from a template chat names
it — falling back to
agent_idfor a legacy record, script jobs overneither; that rule now lives once, in
src/kiro_crew/cron.py::dispatched_agents_from_disk(loadable_only=…),which the guard calls with
True(only records the scheduler could buildpin a template) and
kirocrew doctor'sjob_agent_names_from_diskwrapsbest-effort with
False, so the two readers cannot drift; the same moduleexposes its store lock as
cron_store_lock(one implementation,_file_lockdelegates) for the delete guard to hold across walk + rename — chat
folders by
default_agent, webhook tokens byagent, and private copies byforked_from; an open chat that picked the template is deliberately not aholder — the module docstring records why);
POST /api/agents/templates— create blank or as alineage-free copy of an installed template, refusing a name an installed spec
or a crew binding resolves (
409 ambiguous_template_namewhen two filesdeclare the name);
DELETE /api/agents/detail/{name}— refused astemplate_read_onlyfor the four kinds above and astemplate_referenced(with the list, masked like
used_by) while anything names it; a row whosefilenameis not a plain basename resolving to a file directly under theagents directory is a 404, never an unlink; a name more than one file reaches
(by declared
nameor stem) is409 ambiguous_template_name, never the firsthit — the matches come from the raw spec-file walk the PATCH uses, not the
deduplicated roster, so
foo.jsondeclaringbarbesidebar.json, or twofiles both declaring
bar(one roster row), refuse instead of unlinkingwhichever the scan listed first. Under the
spec lock the FILE decides: it is re-read and classified from its own contents
(the way discovery and the PATCH classify a file), the requested name must be
one it answers to (declared name or stem, else 404), the ambiguity check is
re-run so the name still reaches exactly this file (a claimant landing after
the probe is 409, not an unlink), it must be deletable from
this tab (else
409 template_read_onlywith the file's reason), and its owndeclared name joins the reference guard's aliases — an edition row saying
rogueovervictim.json, or calling a package file plain, unlinks nothing. The reference check and the unlinkare one off-loop critical section under the locks whose writers this handler
can serialize with — the folder store held across it (a new snapshot-handing
state.hold_folders, the sibling ofmutate_folders' own held write), theconfig.jsonadvisory lock and theconfig.local.jsonoverlay lock nestedinside it (cross-process, writing nothing; the effective merged config and
the fork sidecar are read under them), and the spec lock around the unlink
— the shape
_unlink_copy_unless_referencedestablished; both mutations(create's write, delete's section) run through
drained_to_thread, so arequest cancelled mid-write drains the worker before the locks unwind
instead of committing a file nobody audits. Webhook tokens are read inside
that section and their writers now commit under the same spec lock
(
handlers/hooks.py::_commit_pinned_tokenre-verifies the agent insideagents_spec_lockbefore a mint or a re-pin), so a token cannot land pointingat a template being removed. Schedules are pinned with the scheduler's own
store lock:
cron.cron_store_lock(the one implementation, whichCronService._file_locknow delegates to) is held from the dispatch-referencewalk through the rename, innermost in the delete's lock order, so a schedule
cannot be saved against the template between "nothing dispatches this" and
the file going; a holder that keeps it past the bounded wait is
503 schedule_store_busy, nothing unlinked. A writer that bypasses the lock (ahand edit) is still caught: once the file is gone the store is re-read and a
schedule that landed anyway is named in a WARNING and a SEL row (outcome
dangling_reference). Acrons.jsonthat is present but unreadable fails thedelete closed (
503 schedule_store_unreadable, nothing unlinked) — before theunlink; after it, a store that fails to read is a WARNING, never a refusal
about a file that is gone. The unlink is a rename to a one-deep tombstone
(
<name>.json.bak.<epoch>, the janitor's own backup shape, invisible todiscovery; the rename comes first and the older grave goes only after it
succeeded, so a refused rename keeps both the live file and the previous
recovery copy; the sweep matches only a genuine grave,
<name>.bak.<digits>,never a spec —
foo.json.bak.5is a legal template name), so the tab's one irreversible action is undoable by hand andthe SEL row names where the file went. The create's
locked check re-scans by declared name too, so a package file landing after the
probe refuses instead of producing an ambiguous name. The
defaultholder isagent.default_agent(a template name); the top-leveldefault_agentis acrew alias and that crew is already counted as a crew. Create applies the
same two-layer binding check, so a name bound only in the overlay is refused,
and a duplicate re-resolves its source inside the spec lock — the name must
reach exactly the file the probe chose, so a second claimant or a replacement
landing after the probe is a 409, not a copy of a definition never validated —
and re-reads it there (the fork/publish shape). Both mutations keep the
dispatch snapshot current as well as the roster cache: a create publishes the
new name (
publish_materialized_agents) before scheduling the off-looprescan, so "Chat with this template" resolves it on the next turn instead of
a slot being stored against the default agent; a delete awaits
refresh_materialized_agentsoff-loop before answering, so the deleted nameis not bindable in a deferred-refresh window. A successful create or delete
emits an operation-labelled SEL line beside the middleware's request-level
record.
src/kiro_crew/dashboard/handlers/agents.py: the detail PATCH acceptsdescription,prompt,tools,allowedTools(shape-checked,400 invalid_definition, each tool entry capped in length) and refuses them on aread-only spec (
409 template_read_only) and when two files claim the name(
409 ambiguous_template_name, neither touched — for every PATCH key, andre-checked under the write lock). The read-only rule classifies the
FILE the PATCH targets (name, declared name, fork sidecar), not the
deduplicated roster's answer for its declared name, so a plain
atlas.jsonbeside a package
SomePkg-atlas.jsoncannot let the package file through;model/skillskeep their existing reach for the crew pane's private copies.website/src/pages/overview/AgentTemplatesTab.tsx, wired as the Agenttemplates tab in
website/src/pages/CapabilitiesPage.tsx: list grouped byorigin via
lib/templateSource.ts(Mine / Crewmate overrides / From packages/ Built-in — a crewmate's private copy is a "crewmate override" in the UI,
including the shared
lib.templateSourcebadge the crew pane shows for thesame file; Duplicate yields "a template of your own"), detail editor with one dirty draft
(description, model, prompt, tools with auto-approval marks) saved through
api.agentPatchwith ONLY the keys the draft changed (a non-emptymodelis read by the server as an explicit pin that flips
model_managedoff, so aprompt-only save must not resend a managed spec's concrete model) — a
background refetch never reseeds a dirty draft — skills
through
AgentSkillsEditor(saved on their own, under its own heading; eachsaved list is written into the detail cache before the refetch, so a second
toggle in that window cannot PATCH the first away),
resources and MCP servers read-only (string-valued fields only, since a spec
is hand-editable; a rejected detail read shows its error rather than
Loading). The header holds two controls: Chat with this template
(
createSlotwithagent_kind: 'template') and an overflow menu with Enrollas crewmate (its row says what enrolling starts), Duplicate and Delete
(reference dialog on refusal); a read-only template's banner carries the
reason once with Duplicate to edit beside it (a private copy gets Open
crewmate instead, and its reference row links to the crew's pane); a tool
pill is name + worded state tag (the toggle, styled with the shared button
recipe; the caption says a click switches it and that removing or toggling
changes nothing until saved, and on a read-only template — inert tags — says
"read-only here" instead of instructing a click) + divider-separated remove; the Add tool input
shows an example placeholder; the enroll row says the crewmate appears under
Agents; the save bar's buttons never wrap;
resources are plain rows, not chips; the save bar says how many crewmates a
save affects and carries both halves of the save-vs-restart model (new chats
use a save at once; running chats after Apply & Restart), and a refused save is reported
in that bar beside Save (inline
ErrorNotice) rather than at the top of thescrolling pane; the glossary says in visible text that Apply & Restart only
relaunches running sessions; a private copy's banner ends "open the crewmate
to edit it", matching its button; the model badge's title spells out "auto
(backend default)"; list badges read "Runs N crewmates" / "N crewmate
overrides" (the group heading's word), both counts in the same muted pill as the model, and the
usage line says "Runs N crewmates" in the badge's words, not "Runs as"; read-only reasons say outcomes, not mechanism; a delete leaves
"Deleted “name”." in the bar's slot over the next row; the tab's own links (usage-line holders,
Open crewmate, the refused-delete dialog) ask the shell's leave gate before
navigating and
beforeunloadis armed while a draft is dirty; the glossary isterm-led (Template / Chat / Crewmate, one line each) with the save-vs-restart
sentence saying chats and history stay; the delete confirm states the blast
radius, and is asked only when the row shows no holder — with holders in hand Delete opens the reference list directly, no confirm and no request; read-only banners lead with a bold two-word reason and a read-only
prompt is a visibly locked block; the save bar wraps at 320px; Chat with this
template stays enabled while dirty and asks first; the header's
Apply & Restart (
components/RestartButton.tsx) now carries its own tooltipsaying what it is for and what a relaunch does to work in progress, and asks
the same in a confirm at the click (chats and history stay; a reply in
progress stops); the MCP servers heading is glossed "external tool
connections"; the glossary's Chat line says "a one-off session that runs a
template — nothing is created or enrolled"; the chat
button, the tool-pill remove and the model badge carry titles saying what they
do. The tab is lazy-loaded so it does not ride in the dashboard shell's
Appchunk, and the lazy chunk sits inside an
ErrorBoundaryinCapabilitiesPage.tsxso a stale chunk after a deploy degrades to the tab, notthe dashboard.
website/src/api/client.tsaddsagentTemplates,agentTemplateCreate,agentTemplateDelete.website/src/i18n/locales/*.json+pluralKeys.json: the tab's copy in alltwelve catalogs, plural forms per locale.
src/kiro_crew/dashboard/folder_repository.py+dashboard/state.py:hold/hold_folders, the store lock held across an awaitable read-onlysection (the delete guard's use above).
.github/black-baseline.txt: thetouched
test/test_folder_store_writer.pygraduated off the black baseline,as the ratchet requires.
docs/system-specs/modules/crew-mode.md(new section, components andtest rows),
docs/system-specs/modules/learn-cron-dashboard.md(endpointcontract; the "Template deletion" passage now describes the revived route),
docs/feature-map/README.md(Agent Templates row; the Capabilities rail nowhosts nine tabs),
src/kiro_crew/docs/agents.md.Backwards compatibility
Compatible: every existing request keeps its behaviour. The detail PATCH's
modelandskillspaths are unchanged (the crew pane still edits privatecopies with them); only requests carrying the new definition keys meet the
read-only rule.
DELETE /api/agents/detail/{name}was absent on main, so nocaller depended on its absence. No config key, spec field or route was renamed
or removed; package, runtime and markdown specs are never written.
Tests
test/test_agent_templates_endpoint.py(70): the roster marks editability perorigin (a row with no spec file beneath the agents directory — empty, foreign
or absent
filename— is read-only for the runtime's reason), lists crew / schedule (as dispatched: sequence over dormantagent_id, script jobs skipped) / chat-folder / webhook / private-copyreferences, and masks package-controlled strings (dropping a row whose name
would be masked); a cron record the scheduler cannot load holds nothing; the
detail PATCH refuses an ambiguous name for every key (model included) with neither file touched, and re-checks ambiguity under the write lock; a row whose filename is absolute, traversing or nested is
never unlinked (404, file intact); a delete refusal masks its reference
labels;
create writes a minimal runnable spec, copies a package template without
lineage, refuses an invalid, reserved, taken or crew-bound name and a
malformed body (a name bound only in
config.local.jsonincluded), copiesthe source as it is inside the spec lock, refuses a source made ambiguous or
replaced after the probe (409, nothing written), answers 409 (not 500) for an
ambiguous source name, publishes a created name to the dispatch snapshot and
awaits the rescan after a delete (a refusal touches neither), and a successful create/delete emit their SEL events; delete refuses a
referenced template listing the references (including a folder pin, a
webhook pin and a binding that lives only in the overlay), checks and unlinks
inside one folder-store hold so a pin that lands while the guard runs is
seen, holds the cron store lock from the reference walk through the rename
(probed on both sides) and answers 503
schedule_store_busywith the fileintact when another holder keeps it, names a schedule written past the lock
(warning + SEL row), fails closed on an unreadable cron store (503, file intact), runs create and delete through the drained seam, refuses a create whose name a file declared after the probe, does not count a template that merely shares the default crew's alias, refuses the default agent by stem, refuses package and runtime specs,
retires an unreferenced template to a one-deep tombstone (and prunes its
bookkeeping; the rename precedes the prune, so a refused rename keeps the
older grave, same-second graves stay distinct, and a live template whose
name looks like a grave is spared), never turns a post-delete store read failure into a failed
response, 404s an unknown name, refuses a name two files reach (a crossover, and a same-name twin the roster collapses) with neither unlinked, refuses a row whose file does not answer to the requested name, a second claimant landing after the probe (ambiguity re-checked under the lock) and a row that calls a package file plain (file re-read under the lock);
the detail PATCH writes the definition keys on an owned template (an MCP ref
survives the governance sanitizer, a builtin auto-approval is withheld by
it), refuses them on a package template, classifies the targeted file rather
than its declared name, and validates their shape including the per-tool
length cap.
test/test_agent_spec_hardened_reads.py: the call-site label ratchet liststhe new
_read_agent_speccaller.test/test_folder_store_writer.py:hold_folderskeeps the store lockacross a section that hops off the loop, hands it a snapshot, and a mutation
queued meanwhile commits only after the section returns.
test/test_webhooks_api.py(+1): a mint whose agent vanishes between theloop-side pre-check and the locked commit mints nothing, and a re-pin in the
same window leaves the stored pin alone, while a label-only PATCH never takes
the spec lock.
test/test_doctor_deprecated_agents.py(+2): the shared cron walk carries jobids and gates on loadability only for the guard; doctor still reads a partial
record, and reports the captured execution's template over a stale or empty
agent_id(a malformed context falls back toagent_id).website/src/components/RestartButton.cov80.test.tsx(+1, 7): Apply & Restartasks first, naming what stays and what stops; declined does nothing, and the
existing confirmed-path cases answer the ask yes.
website/src/test/AgentTemplatesTab.test.tsx(25): grouping by origin; thetwo-control action row and its overflow menu (enroll hint / already-enrolled
state, Delete on an owned row vs Duplicate to edit and a disabled prompt on a
package row, the read-only reason shown once); the definition save through
agentPatchwith the auto-approval toggle; a dirty draft survives abackground refetch of the detail; a rejected detail read renders its error
rather than Loading; only string-valued MCP fields render from a hand-edited
spec; a dirty draft is not carried into a newly created template (New template
asks first; the create drops the draft before selecting); a save is confirmed
in the bar's slot and the Add tool label stays visible while typing; deleting
a delete names the deleted template over the next row, and deleting
a dirty template on a narrow viewport returns to the list; every in-app link
the tab owns routes through the shell's leave gate with its target, and
beforeunloadis armed only while the draft is dirty; the overrides groupis glossed and its row described as an override; resources render as plain rows, not chips; a read-only template with no
stored prompt says so instead of showing an empty editor (no character count beside it); one Skills heading;
the dirty-draft confirm on a row switch; the server's read-only refusal
reported inside the save bar beside Save, cleared by Discard (which asks
first; declined keeps the draft); a saved skill list lands in the detail
cache before the refetch; Chat with this template
dispatches
createSlotin the template namespace; a referenced delete opensthe reference dialog, naming a chat folder among the rows and linking a
private-copy row to its crew; a private copy's banner offers Open crewmate;
blank create vs a
duplicate that sends
from, with the created row selected after the rosterrefetch; a name the server would refuse is refused before sending; the usage
line names chat-folder and webhook holders and each drills in to where the
holder lives. The
ApiErrorstub carries theraw response text like the real one, which is what caught the reference list
being read off the wrong shape.
delete_confirmis pinned inQUOTED_OPERAND_CONFIRM_KEYS.Manual verification
Against an isolated gateway (
KIROCREW_HOMEunder scratch,KIRO_HOMEpointedat a scratch agents directory holding two package templates and three owned
ones, port 6799, this worktree's dist), with a crewmate
pr-botand a chatfolder
Reviewsboth pinned topr-reviewer: the roster listspr-revieweras used by the crewmate and the folder, each holder a link to where it is held; editing its prompt raises the save bar
("Unsaved changes · affects 1 crewmate", "Press Save template to keep these
edits: new chats use them at once; chats already running pick them up after
Apply & Restart"); the overflow menu shows Enroll with its explanation, Duplicate and
Delete; the Skills section carries one heading; confirming Delete opens "Can't delete pr-reviewer yet" with a Crewmate
row and a Chat folder row, each with Open →, and the file stays; the package
template
atlasshows "Read-only · path" in the header, the reason once in thebanner with Duplicate to edit beside it, and a disabled editor; Duplicate
to edit opens New template in duplicate mode with
atlasin "Copy of". Thereference dialog probe is what exposed the
ApiError.bodyshape bug fixed inthis round.
Screenshots / video
Owned template — two-control header, usage line linking to the crewmate and the chat folder, editable definition:
Delete refused while referenced — one row per holder (crewmate, chat folder), each with a jump:
Package template — "Read-only · path" header, the reason once in the banner with Duplicate to edit, disabled editor:
Save bar, Tools editor (editable and read-only), overflow menu, New template in duplicate mode
Save bar after a prompt edit — affected crewmates, the save hint, Save template and Discard:
After Save — the bar is gone and "Template saved." sits in its slot:
Tools editor on an owned template — ✓ marks auto-approval, Add tool open; Skills, Resources and MCP servers below:
The same sections on a package template, read-only:
Overflow menu — Enroll as crewmate with what it starts, Duplicate, Delete:
New template opened from the header — the blank / duplicate choice:
Duplicate dialog, seeded from the selected template and titled by its entry point:
The other read-only variants — runtime (Built-in group), markdown-defined, and a crewmate's private copy (Private copies group) — and the empty state:
Related Issues
N/A — follows #12224 (templates as chat execution choices); no tracked issue.
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)