Repository navigation
feat(members): give every crew a configurable webview in its drawer - #8468
Conversation
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify the first consumer PR is queued: until it lands, every drawer shows the empty state and nothing exercises publish-to-render end to end. [DESIGN-REVIEWED] 6c636a3 |
UX Review (Fable 5) — 🟡 CONCERNSUX-level review of UX-Verdict: CONCERNS "Published 3d ago" renders over a blank frame in the first-mint-failure state — the blind reader "cannot tell what was published or where it went." Watch
[UX-REVIEWED] 6c636a3 |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS Template discovery and selection machinery ships against exactly one installed template — the bespoke-template path it exists for has zero instances yet. Not justified as shipped
What this change shipsInventory (10 items) — 9 justifiedIntent: let an operator see a long-running crew's self-reported state in the drawer they already watch, without a per-crew frontend release — an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 6c636a3 |
GPT 5.6 Review — ✅ no blocking findings (all downgraded on adjudication)GPT 5.6 flagged blocking issues on This comment is updated in place on each push. Review detailsBLOCKING -- src/kiro_crew/dashboard/handlers/agent_panel.py:424 -- valid crew names cannot read their published webview Adjudication (Opus 4.8) — is blocking on each finding proportionate?Harm rung: LOW. Conditions: read rejects any [ADJUDICATION] 6c636a3 total=1 uphold=0 downgrade=1 False positive or not applicable? A repository writer can comment: |
Opus 4.8 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
cae7136 to
541af4c
Compare
541af4c to
9bb189f
Compare
9bb189f to
63885d7
Compare
63885d7 to
4ca968f
Compare
GPT 5.6 Review —
|
|
|
|
|
|
|
|
|
|
|
|
|
A crew that runs unattended accumulates the state an operator actually wants:
how many workers it is holding, which one is stuck, what it is waiting on. The
drawer showed activity counts, a path list and config instead, none of which
answer those. This adds a free-form HTML webview that the crew fills in at
runtime.
The split that makes free-form HTML safe: a human authors the TEMPLATE --
versioned in the repository, or dropped on disk by the operator -- and the crew
publishes only DATA. The template directory is fenced from agent file tools, so
a crew cannot author its own markup; the only way it influences its webview is
by publishing a data object. The data lands as an inert application/json island,
escaped so a published string cannot close the script element early, and a
template reads it with JSON.parse and renders through textContent only. The
composed document is served behind a single-use minted URL into an iframe
sandboxed to allow-scripts and nothing else.
A crew whose name matches an installed template gets that template; a crew with
no template of its own falls back to a generic one that renders any data object.
That is the entire wiring mechanism -- installing <crew-name>.html is the act of
wiring a bespoke view up, so there is no registry, no mapping table and no
per-crew config to keep in sync.
The MCP server ships registered but gated off for every agent (opt_in), so a
default session pays nothing for the capability: not a tool-list entry, not a
line of context, not a spawned backend. An agent that should publish a panel is
granted the set in its own spec, and a refresh keeps an existing grant current
without ever minting one.
The publishing crew is derived from the vetted calling session and never from the
request body, so one crew cannot publish a webview that presents as another's. A
body field naming a crew is rejected by the schema rather than ignored, so a
caller is never left believing it retargeted the write. The drawer's read at GET
/api/members/{slug}/panel is cookie-authed; the /api/agent-panel writes sit
behind the MCP-only prefix.
Published field order is preserved end to end. Field order is presentation -- a
template renders a stat strip in key order -- so the record is dumped without
sorting keys instead of silently alphabetising the operator's dashboard.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
buluoray
left a comment
There was a problem hiding this comment.
Re-verified at 6c636a36 after the force-push dismissed my earlier review. Went at the five load-bearing surfaces first rather than the whole 20-file diff.
sandbox.py — every hunk tightens, nothing widens. crew-panels joins _CREW_HIDDEN_LEAVES and the hidden-dir precreate set; panel-templates joins _CREW_READONLY_LEAVES and the readonly precreate set; the new _CREW_NO_ALIAS_LEAVES + _refuse_if_aliased_protected_leaf turns an aliased protected leaf from warn-and-continue into a hard spawn refusal (:1587, :1677, :2032). The one behaviour change — _sealable_absent_ceilings materializing hidden leaves too — is required, since an absent dir gives the bind-mask no target on a fresh install. No seal, mask, or no-follow pin is relaxed.
Publish surface is strict-internal and the crew is never taken from the body: request["internal_auth"] (constant-time secret), then awaited _deny_app_caller before slot.agent is read, then _recognize_session, then restricted-session refusal; the crew comes from the vetted session's get_agent_selection and only when namespace is member (_resolve_publishing_crew). Prefix is in server._STRICT_INTERNAL_API_PATHS (server.py:493). Read route is cookie-authed, requires an exact member param matched against the stored ownership digest, and fails closed on an unowned record.
No arbitrary-path serving: template ids go through TEMPLATE_ID_RE (^[a-z0-9-]{1,64}$, no separators) plus a second is_relative_to(root) symlink check (agent_panel.py:400); the record path is slug-validated, containment-checked and link-refused. Untrusted data is escaped once at a single boundary into an inert application/json island and rendered through DOM text APIs; the iframe is sandbox="allow-scripts" only — null origin, no same-origin, no popups — with egress closed by the CSP buildSrcdoc injects. Publish-time credential/exfil scrubbing covers keys as well as values.
panel_published is declared to the "panels" scope (not Tier-0) and carries {slug} only, deliberately withholding the ownership digest, so a client acting on it must re-read through the ownership-checked route. Same shape as artifact_update.
Packaging is right: agent_panel_templates/*.html is in both MANIFEST.in (sdist) and setup.cfg package_data (wheel), so the template ships on pip and DMG rather than the feature arriving broken.
MCP registration is mount-not-approve: kirocrew-panel is opt_in=True, in OPT_IN_BIN_MCP_SERVERS rather than ALWAYS_ON, and carries no autoApprove key, so calls reach hooks.on_tool_call and stay subject to trust mode. Publish identity requires require_strict_session_key, so a subagent is refused.
One imprecision, not worth a revision: _refuse_if_aliased_protected_leaf's docstring says it detects "a regular file with an extra hardlink," but the implementation refuses any non-directory/non-symlink entry and never reads st_nlink. The behaviour is stricter than the prose, so the effect is safe — only the sentence is wrong.
The "ships no consumer yet" note from Design/First Principles is real and acknowledged; the feature is opt-in and off by default, so it is a scope judgment rather than a defect. GPT's "valid crew names cannot read their panel" does not hold — crew_key digests the raw name before redaction/clamp (agent_panel.py:663), so a credential-shaped name still matches itself.
Did not line-read the ~15 locale JSONs, the website/capture/* harnesses, or onboarding_import.py.
The crew's dashboard, docked in its drawer -- the crew decides what goes here:
Expanded to the full window:
A crew that has published nothing says so, rather than showing an empty box:
When the panel read fails, the drawer shows the error notice, an agent hand-off, and a "Try again" retry rather than an empty box:
While the read is in flight, a pulsing skeleton stands in for the dashboard:
The expanded view while a render is in flight, and the aged band when a
re-mint fails and an older document stays on screen:
The expanded view when the FIRST mint fails, so nothing has ever rendered: the band
carries the hard sentence, the frame below it holds nothing, and the retry stays:
The expanded view when a NEWER version was published and its refresh failed: the bar's chip dates the new version, the band names the version still on screen, so the two ages are two different facts rather than one clock read twice:
Expand and collapse, recorded from the built SPA:
08-expand-collapse.webm
1. What is the problem
A crew has nowhere to show its own state.
The member drawer shows what KiroCrew knows about a crew -- session counts, wake sources, configuration. It shows nothing the crew itself wants to say. A conductor running a fleet of workers knows things no generic UI can guess: which item is blocked on a human ruling, which worker has been stuck for two cycles, what it intends to do next, and why a count does not add up. Today that exists only in chat scrollback, so it is gone by the next turn and invisible unless someone reads the transcript.
The obvious fix does not scale. A native panel per crew means every new crew shape needs a frontend change, a release, and a schema the crew must be taught. And a crew is an LLM: whatever it produces cannot be handed the dashboard's origin.
2. Why it matters to the user
Someone supervising a long-running crew has to read a transcript to answer the only question they actually have: does this need me? The drawer is where they already look, and it cannot tell them.
This also removes a per-crew frontend release from the loop. A crew that wants to surface something new publishes different data; nobody ships a UI change to make it visible.
3. How our fix solves it
The root cause is that presentation was coupled to the frontend release cycle, and the only party that knows what matters -- the crew -- had no way to influence it.
The fix splits the panel in two: a human-authored template and crew-published data. Only the data comes from the crew.
Records live in a gateway-only, sandbox-hidden subtree. This is the part worth reading closely, because two earlier placements were wrong and the reasons are the design. Storing under the crew's own member space failed because
members/is deliberately unfenced -- a crew owns its own published data -- so nothing stopped one crew writing another crew'spanel.jsondirectly, forging its state past both ownership resolution and the redactors in a single write. Moving totrust/closed that route through the agent's file tools but not through a sandboxed shell, which can construct the path at runtime and so is never caught by command matching. The record now lives in a dedicated hidden leaf with a precreate disposition, so the directory exists before an agent can create it: a fence only fences a path that is there. All three write paths -- the MCP route, agent file tools, and a sandboxed shell -- are closed on the same location, and the module docstring records why each earlier placement was rejected so the next reader does not undo it.Template selection needs no registry. A crew whose name matches an installed template gets that template; everything else gets
default. No mapping table, no per-crew config, and a bespoke template activates by being installed.defaultrenders any data object: scalars become a tile strip, sentences become their own section, arrays of objects become tables with derived headings, arrays of scalars become lists, objects become key/value blocks. Fields render in the order the crew published them, so a crew that puts its alert first gets it read first.Rendering is bounded, not just the input. The data cap bounds what a crew can publish, but derived table headings take the union of keys across rows, so a payload well inside that cap could still expand to millions of cells and hang the browser. Rows and unique columns are capped independently, with an explicit truncation notice rather than a silent drop.
Two conventions come from the Issue Radar Pipeline dashboard, which solves the same legibility problem at a larger scale. A missing value renders as an explicit placeholder rather than vanishing, so "we do not know" is distinguishable from "none". And a
<field>_notekey renders as a caveat directly under the thing it qualifies, which is how a crew explains why a number does not reconcile.Writes are MCP-only. A new opt-in server (
kirocrew-panel) carriespanel_publishandpanel_templates, registered across every declaration surface the repo has -- the managed-server registries, the schema-posture view, the redaction sinks, the MCP call-site auth scan, the sandbox mask, the feature map, and the architecture specs -- and gated off for every agent by default. Neither tool takes a crew or session argument: the publishing crew is resolved from the vetted calling session through the shared strict-session gate, never from the request body, and never from the lenient resolver that would resolve a subagent to its parent's crew. The publish routes are strict-internal; the drawer's read route is cookie-authed and deliberately outside that prefix. The read route takes one snapshot and composes both halves from it, so the summary and the document can never disagree.One shared theme reader. The webview frame is the seventh caller of the same theme-variable read. Rather than add a seventh local copy,
widgetSrcdoc.readThemeVarsbecomes the single export and the other copies are deleted, mochi's included: itsWidgetFramenow passes computed theme values throughsanitizeCssValuelike every other caller, which is the one behaviour change outside this feature's own surface. Section 5 has the detail.The drawer has two states, and only one of them is a document. Docked is a native summary -- title, the crew's leading sentence, a few counters, and a labelled button. Expanded is the crew's document in a sandboxed frame. This is not cosmetic: a 250px column cannot host a dashboard, and trying put the most important line below the fold. It also means no document is minted until someone opens it, and the minted URL is single-use, so the frame is created on first expand and kept mounted across collapse.
Containment, stated precisely. The shared sandbox-document serve route sets one CSP header for every consumer and is unchanged here; it grants popups. What holds is that sandbox restrictions combine rather than union, so the frame's own
sandbox="allow-scripts"is the binding constraint: no popups, a null origin, no cookies, no storage, no parent DOM, no top-level navigation. Egress is closed by the document's own CSP. Scripts do run, by design.The sandbox is defence in depth, not the only defence. The untrusted half is data, not markup: it is escaped once in Python at a single boundary, redacted on the way into storage, and the template directory is read-only to the sandbox so an agent cannot author its own template. Templates reach the DOM only through text APIs, pinned by a test that greps the source for DOM sinks. The native docked summary renders crew strings as React text children, pinned by a test that a hostile string injects no element.
The sandbox dispositions are written down where the next reader looks.
docs/system-specs/modules/security.mdis the canonical registry of fenced leaves, and it now carries both of this change's:crew-panels/as hidden and precreated,panel-templates/as read-only and additionally write-protected rather than on the read-plus-write floor, so the operator who authored a template can still read it back while no agent can rewrite it. It also carries_CREW_NO_ALIAS_LEAVES, which refuses the spawn outright when either leaf is reachable under a second name, and why that differs from every other leaf's warn-and-continue: neither is a config file anyone has a reason to symlink, and a warning is what let the log claim a path was sealed while the writes went elsewhere.The failure band and the empty state were rewritten after UX review. The expanded view's failure banner used to be one string in two states, laid over the frame as an absolute overlay: when a later mint failed while a document was still on screen, the reader was told the dashboard "could not be rendered" while looking at a rendered one, with the banner covering that document's own freshness line. There are now two strings -- a refresh failure names itself as one and says the last loaded version is showing -- and the band stacks between the Contained bar and the frame, so the document keeps every pixel. The empty state, which is the first state every operator meets while the server ships off, now states the task instead of naming a settings surface to go hunting for, and carries a control that opens the crew manager on that member through the page's own draft guard. Both are pinned, and both pins were mutation-checked: restoring the overlay, collapsing the two strings back into one, and suppressing the control each redden exactly the assertion that guards them. The copy also stops calling one thing by two names -- "member", matching the sibling copy in the same drawer, not "crew".
4. What tests we did
5. Any other suggestions
readThemeVarswas duplicated seven times; this change extracts one shared export and deletes all seven local copies. That is scope beyond the feature, taken because a duplication that is merely disclosed is still a duplication. It carries one behaviour change that the earlier wording of this section did not name: mochi'sWidgetFramehad the one local copy that readgetPropertyValue(name).trim()raw, with nosanitizeCssValueand no SSR guard, so moving it onto the shared reader means that frame now sanitizes theme values it previously interpolated unchecked. Strictly safer, but a change to a surface this feature does not otherwise touch, and a reviewer is right to want it stated rather than inferred from the diff.temp-screenshots/, which.gitignoreexcludes precisely because review evidence belongs on the pull request;docs/ci/ci-and-reviews.mdsays the same. The files are now GitHub attachments and the directory is gone from the commit, so the images above no longer depend on repository history.kirocrew-panelserver row there does not yet say it is what enables this drawer's dashboard. That cue belongs to the crew manager's copy and is a follow-up on that page, not a change to this drawer.