Repository navigation
feat(agents): template selector becomes the definition panel's header with private fork-on-edit - #8307
Conversation
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of All evidence gathered. The test_agent.py deltas are pure black reformatting (matching the baseline removal) plus new fork tests — no deleted pins. Counts are run. Emitting the review. First-Principles-Verdict: CONCERNS Undeclared rider: every named-agent session start now aborts on an unreadable Not justified as shipped
What this change shipsInventory (10 items) — 6 justifiedIntent: let a user customize one crew's agent without silently mutating the shared template other crews use — fork-on-first-edit with lineage and a publish path. ADDITION.
Watch
Subtractions
[FIRST-PRINCIPLES-REVIEWED] 1b9e2b7 |
Design Review (Fable 5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS Sound copy-on-write design with rigorously argued boundaries; residual risks are stale owning specs and a bookkeeping file now coupled to every session start. Watch
Suggestions
[DESIGN-REVIEWED] 1b9e2b7 |
UX Review (Fable 5) — 🟡 CONCERNSUX-level review of I have the full picture. Evidence status: the PR body embeds eight screenshots, but they live at an earlier branch commit ( UX-Verdict: CONCERNS Solid, carefully-copied surface — but this revision dropped its screenshots, so the blind read never ran and nothing here has been seen cold. Watch
Evidence gaps
Suggestions
[UX-REVIEWED] 1b9e2b7 |
GPT 5.6 Review — ✅ human override acceptedHuman judgment by @CrysisDeu overrides the GPT 5.6 finding for This comment is updated in place on each push. The model was not re-run because an authorized human decision supersedes it. False positive or not applicable? A repository writer can comment: |
Opus 4.8 Review — ✅ no blocking findingsReviewed Review detailsThe single candidate falsifies cleanly. The overlap guard ( No findings. [OPUS-REVIEWED] 1b9e2b7 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
0701ce3 to
f071f4a
Compare
|
|
|
|
|
|
|
Open PR relationship auditThis is a consolidated, point-in-time code-level audit note. It compares complete merge-base diffs and current/merged code; it does not treat a shared topic as duplication or partial coverage as completion. Relationship findings
No PR, Issue, label, branch, or review state was changed by the relationship-note portion of this audit. |
|
Pushed 2e06d1e -> c2cfff7. The delegated-workspace span is clear (GPT no longer flags Fix: that step now follows the same rule as the existing Diff vs 2e06d1e: 3 files, +65 -15. Single commit, author preserved; static gates pass. -- @xuejinT FYI |
|
/ai-review override gpt d6aac07: same as the override on ee194bb — the "published template leaves governance reprojection" finding is a pre-existing repo-wide gap for every template in the agents dir, not something this PR introduces; tracked in #9598. (The KiroCrewAgentsPage.tsx template-switch resync finding on c2cfff7 is NOT overridden: it is fixed in this head.) |
|
AI-review override not recorded: |
|
Pushed c2cfff7 -> d6aac07 for the GPT BLOCK on c2cfff7 ( Fix: the catch now reads the authoritative roster directly ( tsc + eslint clean; no frontend test added for this path — it needs the full edit-sheet + template-pane harness and I cannot run vitest locally under the babysit rules, so I did not want to ship an unvalidated test. Diff vs c2cfff7: 1 file, +24 -3. -- @xuejinT FYI |
|
AI-review override not recorded: |
|
Pushed d6aac07 -> a663b83: my own type error from the previous push. |
Human judgment recorded@CrysisDeu marked the gpt AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
|
Pushed a663b83 -> bb5f2c8: mypy regression from my publish change ( The GPT BLOCK on a663b83 ( |
|
Correction for the record: the GPT 5.6 lane on bb5f2c8 reports "human override accepted" and did NOT re-run the model — the |
|
/ai-review override gpt 24fb0e5: same as the override on ee194bb — the "published template leaves governance reprojection" finding is a pre-existing repo-wide gap for every template in the agents dir, not something this PR introduces; tracked in #9598. (Note for the human reader: the lane treats this as a whole-commit override and skips the model, so the sandbox.py:860 symlinked-agents-dir finding from a663b83 remains open and unreviewed on this head.) |
Human judgment recorded@CrysisDeu marked the gpt AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
|
Human judgment recorded, but the following reviewer lane(s) could not be re-run automatically: GPT 5.6. Re-run the lane's latest workflow run for |
|
Pushed bb5f2c8 -> 24fb0e5. Two things folded into one head:
All other checks on bb5f2c8 were green (60/67, 4 skipped, 0 other failures). Static gates pass ( |
… with private fork-on-edit
Blueprint semantics for the Agents page: editing a crew's template definition
forks a private copy on first edit instead of mutating the shared template.
The template selector becomes the definition panel's header bar, with a
Customized state, a live change-count popover, a scoped 'Reset my changes',
and 'Save as new template'. All behind the agent_template_pane feature flag.
- fork endpoint (POST /api/agents/detail/{name}/fork) + publish endpoint
- fork lineage sidecar (forked_from/private_to) in agent_model_state.json
- sync loop skips auto-creating private copies; fork refresh keeps copies
aligned with owned-template dynamic fields without clobbering user edits
- panel UI: header selector, source badges, Customized tag, changes popover,
scoped reset, save-as-new-template dialog, switch-away confirm
- i18n for 11 locales; 96 backend + 36 frontend tests; capture harness
|
/ai-review override gpt 1b9e2b7: same as the override on ee194bb — the "published template leaves governance reprojection" finding is a pre-existing repo-wide gap for every template in the agents dir, not something this PR introduces; tracked in #9598. (Lane treats this as whole-commit; the sandbox.py:860 symlinked-agents-dir finding remains open and unreviewed.) |
Human judgment recorded@CrysisDeu marked the gpt AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
|
Human judgment recorded, but the following reviewer lane(s) could not be re-run automatically: GPT 5.6. Re-run the lane's latest workflow run for |
|
Rebased onto main (24fb0e5 -> 1b9e2b7) to pick up #9861, which regenerates |
Problem / Motivation
On the Agents page, a crew's agent template is a shared object: editing the prompt, tools, or model of a template while configuring one crew silently mutates that template for every other crew bound to it. There is no safe way to customize an agent for one crew, no visibility that a crew's agent has diverged from the template it came from, and no path to promote a good customization back into a reusable template.
Why it matters
Shared-mutation editing is a silent cross-crew data-loss class: a user tuning one crew's agent breaks the others without any warning, and there is no way back because the original template text is overwritten in place. It also blocks the common workflow of "start from a built-in template, tweak it for this crew".
What changed (motivation → approach → change)
Goal: make per-crew customization safe while keeping templates reusable — blueprint semantics, where a template is a starting point and edits never propagate backward.
Approach chosen: private fork-on-first-edit with the template selector as the definition panel's header (over alternatives of explicit "duplicate template" buttons or an edit-lock on shared templates, both of which push bookkeeping onto the user). The first edit to a template-bound agent transparently creates an auto-named private copy scoped to that crew; the panel header then shows a "Customized" state with the origin template's name.
What was built (behind the
agent_template_panefeature flag):Two small pieces ship un-flagged for all users, deliberately: template dropdown rows gain source badges (built-in / custom / private copy), and the Agent Templates tab's badges move to the shared
kirocrew_ownedmarker with a neutral tone — both are display-only relabels with no behavior change, and gating pure labels would fork the render path for no benefit.dashboard/handlers/agents.py, routes):api_agent_fork(create the private copy, record lineage, rebind the crew) andapi_agent_publish(promote a private copy to a named user-level template). Both owner-gated, config-lock-serialized, path-confined to the agents dir, idempotent.agent_state.py): a sidecar recordsforked_from/private_toper fork;agent_discovery.list_agentsenriches rows with it in one sidecar read per scan.agent.py):_refresh_dynamic_fields(..., fork=True)keeps a fork's own prompt/model instead of overwriting from the template, while security hooks, managed MCP, and the data-home pin still apply;_refresh_forked_templates()(cycle-guarded) keeps forks' managed fields current on setup. Reviewer note: the hooks-refresh /_refresh_forked_templatescomposition is the security-relevant seam of this diff — worth a close read.AgentTemplateDetail.tsx,KiroCrewAgentsPage.tsx): the selector IS the panel header; Customized badge with origin template name; changed-field count in a detail-on-demand popover; scoped Reset (back to origin, with a destructive confirm listing what is discarded); Switch template (same confirm shape); Save as new template. Private copies are filtered out of other crews' template dropdowns.destructiveConfirm.test.ts.409 stale_bindingwhen the crew is no longer bound to the named template (a stale or racing request cannot clobber a newer binding); publish prunes fork lineage only after the superseded file is actually removed (a locked file stays recorded as private instead of surfacing as shared); the gateway-startuprebuild_agent_config()call is offloaded viaasyncio.to_thread(the fork refresh made the synchronous rebuild heavier); every new error response carries a machine-readablecode; the customized header keeps to two action controls (Reset lives inside the change popover) and the popover trigger uses a LucideChevronDown; the feature map's Crews row names the new endpoints and panel component.agents_spec_lock, a sidecar lockfile in the agents dir); spec files are only ever created with exclusive-create (open('x')), so a raced or differing-case destination is refused instead of truncated; template names are reserved case-insensitively (matching APFS/NTFS defaults); and crew rebinds go throughupdate_config_lockedas a binding-only delta with the stale-binding check re-run inside the critical section, replacing the full-snapshotcfg.save()that could silently revert concurrent config writes. Detail-pane errors render through the sharedErrorNoticecomponent (the publish-dialog variant deliberately opts out of the ask-agent hand-off, which would destroy the unsaved name draft)._apply_allowed_tools_ceiling,_strip_ungoverned_auto_approve) before every fork write —allowedTools/autoApprovenever reach the PreToolUse gate, so a fork carrying grants the ceiling later tightened against must be re-filtered on refresh (regression-tested); and theagent_statesidecar's mutating read-modify-writes hold a cross-process file lock (agent_model_state.json.lock), so a dashboard fork racing a CLI model-state write can no longer erase fork lineage via a stale whole-file replacement. Model/reset failures in the pane surface inline throughErrorNoticewith the hint copy declaring "saved as you go" in all 13 catalogs; the fork/publish spec-scan closures are collapsed into one shared loader (call-site attribution ratchet updated to its sanctioned forward form).Tests
test/test_agent_fork_endpoint.py+test/test_agent_publish_endpoint.py(26 tests): fork creates the copy + lineage + rebinding, publish renames/promotes, name-collision 409 (including a differing-case name —Reviewervs existingreviewer.json— matching case-insensitive filesystem semantics), reserved-name refusal, owner gating, idempotency,stale_bindingrefusals for both endpoints, and lineage preserved when the superseded copy cannot be deleted.test/test_agent_discovery_fork_info.py: lineage enrichment and cache invalidation on fork/publish.test/test_agent_refresh_fork.py:fork=Truepreserves fork-owned fields while applying managed security fields.destructiveConfirm.test.tspins the four new confirm keys to the quoted-operand contract in every catalog.Manual verification
Verified with the repo's scripted-Playwright capture harness (
website/scripts/capture-agent-template-pane.mjs) against an isolated instance: template-bound, customized, and private-copy states, the change popover, and the template dropdown. Frames below are the same evidence.Screenshots / video
More states
Related Issues
no linked issue: this implements the Agents-page redesign agreed in design review; no tracking issue was filed for it.
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)Fifth review round: the shared spec writer now runs
sanitize_agent_config_governance(the sanctioned whole-config funnel) before every fork/publish write, both endpoints compensate on any rebind failure (locked undo, 500rebind_failed) instead of leaking an orphan template, and everyErrorNoticesite carries an explicit hand-off decision (askAgentor a no-hand-off comment). Two regression tests pin the governance filter and the compensation.Sixth review round: every sidecar mutation reachable from an async handler (fork lineage, publish model tracking, the PATCH model branch, DELETE prune) is offloaded with
asyncio.to_thread, so the cross-process sidecar lock never blocks the event loop.Seventh review round: the fork prompt refresh preserves live custom
file://prompts (only the managed pointer and dangling stale pointers are rewritten), and a sidecar bookkeeping failure after fork/publish spec creation now compensates like a rebind failure — failure-resilient undo (unlink runs even if the sidecar prune fails), 500bookkeeping_failed. Five regression tests pin the prompt-guard branches and both compensations.Eighth review round: the PATCH overwrite is now a full read-merge-write inside
agents_spec_lock— fresh re-read, merge of only this patch's delta (a concurrent refresh's changes to untouched keys survive), thensanitize_agent_config_governanceimmediately before persisting. This closes the governance funnel across all four whole-spec writers (PUT, fork, publish, PATCH). Two regression tests pin the sanitized write and the concurrent-merge semantics.Ninth review round: spec writes are durable and portable — a failed exclusive create is unlinked (no truncated name-squatter), the PATCH overwrite is atomic (tmp+replace), fork and publish re-read the source inside the spec lock (no stale copies), post-commit lineage cleanup is non-throwing, and Windows-reserved basenames (CON, NUL, COM1-9…) are refused on publish and suffixed past on fork. Five regression tests.
Tenth review round: publish's superseded-copy cleanup unlinks the RESOLVED source file (a fork whose stem differs from its declared name is no longer missed), and the failed-create unlink runs after the handle closes (Windows sharing violation) and never on FileExistsError (a concurrent creator's file is never ours to remove).
Eleventh review round: the
agent_template_paneflag is now modeled end-to-end (field, load, save, resolution allow-list — theconnections_uishape), soagent_template_pane: truein config actually reaches the browser and enables the panel; and the DELETE handler's unlink+prune run in oneagents_spec_lockhold off the event loop, so a concurrent fork refresh can no longer resurrect a deleted private copy as a shared template.Twelfth review round: the lineage sidecar (and its lock/temp siblings) is write-fenced from agent tools via the existing
_WRITE_PROTECTED_HOME_PATHSmechanism; reset is a server-side transaction (POST /api/agents/detail/{name}/reset— origin and binding validated before any mutation, copy deleted only after the rebind persisted) and the panel calls it; rollback keeps or grants private lineage when a file cannot be removed; ambiguous template names are refused; the sheet footer is hidden while the pane is active (one save model per surface, hint names the reset path in all 13 locales); the Built-in→Customized chip transition is animated with a reduced-motion fallback.