Repository navigation
feat: render an agent's welcomeMessage when it becomes active - #11413
Conversation
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Eyeball one near-cap (2000-char) hint in Suggestions
[DESIGN-REVIEWED] 11739b4 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsFINDING -- src/kiro_crew/dashboard/chat_runner.py:694 -- changing projects can activate a shadowing same-name agent, but False positive or not applicable? A repository writer can comment: |
e02751f to
f76bb0c
Compare
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Verify issue #1775 covers this dashboard-only notice-row shape; everything else — dead field, plain-text NoticeCard, redaction, cause-level reader — checked out locally. What this change shipsInventory (9 items) — 9 justifiedIntent: an agent author's
Reuses every existing seam: [FIRST-PRINCIPLES-REVIEWED] 11739b4 |
Opus 4.8 Review — ✅ no blocking findingsReviewed Review detailsThe candidate list contains no candidates (the discovery pass found nothing), and my own falsification of the changed code confirms it. The reader resolves the live spec through No findings. [OPUS-REVIEWED] 11739b4 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
918ce04 to
2340131
Compare
CI status on
|
Update: every remaining red on
|
| Shard | Failing files |
|---|---|
| Backend Tests (3.12, 2) | test_ledger_retention.py ×44, test_ledger_types.py, test_ledger_kinds.py, test_fargate_launch_engine.py ×2 |
| Backend Tests (3.12, 3) | test_remove_slot_for_history_key.py |
| Backend Tests (Windows) (3) | test_fargate_launch_engine.py |
| Backend Tests (Windows) (4) | test_ledger_retention.py, test_ledger_types.py |
| Backend Tests (Windows) (6) | test_remove_slot_for_history_key.py |
Nothing in this PR touches src/kiro_crew/ledger/, src/kiro_crew/cloud/, or
the permanent-delete path. Fixing either defect here would make a feature change
an undeclared rider on two unrelated subsystems, so both are left to their
owners; this branch will go green on a rebase once #11317's fixture debt and the
begin_signin signature land.
The earlier flake8 F401 inheritance is resolved — this head is rebased onto
04727ebe0f, which includes #11415, and Backend Lint & Type Check (3.12) is
green.
Everything this PR is responsible for is green: all 6 AI review lanes (GPT 5.6,
Opus 4.8, Design, First Principles, UX, Security Scope), CodeQL, SAST (Semgrep),
internal-content-scan, Docs Lint, Comment History Gate, Backend Lint & Type
Check, Frontend/Desktop/Wheel builds, and E2E — 63 passing checks.
2340131 to
7e54a6b
Compare
|
Intent: Make an agent's Not a goal: No new config surface, no rendering of the hint anywhere outside the dashboard chat transcript, no repeat per turn, and no change to any other agent-spec field or to the channels (Slack, Discord, cron) — only the dashboard chat session's own activation points. |
7e54a6b to
11d1730
Compare
11d1730 to
0bb6d13
Compare
|
|
0bb6d13 to
ba4a86b
Compare
|
|
|
|
ba4a86b to
f35c64c
Compare
|
|
An agent spec may carry `welcomeMessage`, a usage hint its author wants read when that agent starts answering. The field had zero readers: it was accepted silently, shipped by the bundled pptx-maker agents, and rendered nowhere, so authors reasonably assumed it worked and the only workaround was to inline the hint into the system prompt, where it is re-sent every turn. `agent_discovery.agent_welcome_message` is now its one reader and `chat_runner._surface_agent_welcome` its one emitter. Two activation points feed it: a cold session start on a non-empty `slot.agent`, and a provider-side agent switch, where the hint lands immediately after the "Switched to agent" row so the two read in causal order. The row is `role="notice"`, which is what makes it a transcript entry rather than prompt context: outside `_TRANSIENT_ROLES` so it persists and survives a reload, but neither `user` nor `assistant`, so the history replay never feeds it back to the model. `NoticeCard` draws it as plain text, never markdown or HTML. One shot per activation, via `slot._welcomed_agent`: a switch and the cold start its own session reset produces are two events for a single activation, so both call sites clear through that field. It is claimed before the offloaded read, so racing events cannot both pass, and a failed read counts as welcomed so a broken agents directory cannot re-scan on every later event. The field is untrusted config data reaching a persisted window: absent, empty, whitespace-only and non-string values render nothing, the text is capped at 2000 chars, and it goes through the same display redactors as any other foreign string on that path. Resolution mirrors `list_agents` so the hint comes from the spec the picker showed. Fixes #1775
f35c64c to
11739b4
Compare
|
…tdev#11413) An agent spec may carry `welcomeMessage`, a usage hint its author wants read when that agent starts answering. The field had zero readers: it was accepted silently, shipped by the bundled pptx-maker agents, and rendered nowhere, so authors reasonably assumed it worked and the only workaround was to inline the hint into the system prompt, where it is re-sent every turn. `agent_discovery.agent_welcome_message` is now its one reader and `chat_runner._surface_agent_welcome` its one emitter. Two activation points feed it: a cold session start on a non-empty `slot.agent`, and a provider-side agent switch, where the hint lands immediately after the "Switched to agent" row so the two read in causal order. The row is `role="notice"`, which is what makes it a transcript entry rather than prompt context: outside `_TRANSIENT_ROLES` so it persists and survives a reload, but neither `user` nor `assistant`, so the history replay never feeds it back to the model. `NoticeCard` draws it as plain text, never markdown or HTML. One shot per activation, via `slot._welcomed_agent`: a switch and the cold start its own session reset produces are two events for a single activation, so both call sites clear through that field. It is claimed before the offloaded read, so racing events cannot both pass, and a failed read counts as welcomed so a broken agents directory cannot re-scan on every later event. The field is untrusted config data reaching a persisted window: absent, empty, whitespace-only and non-string values render nothing, the text is capped at 2000 chars, and it goes through the same display redactors as any other foreign string on that path. Resolution mirrors `list_agents` so the hint comes from the spec the picker showed. Fixes kirodotdev#1775 Co-authored-by: Joe Guo <zejiangg@amazon.com>
Problem / Motivation
An agent spec may carry a
welcomeMessage— a usage hint its author writes forwhoever the agent is about to help. Nothing reads it. On
mainthe onlyoccurrences are
agent_capabilities.py's passthrough field list, docs, and thethree bundled
pptx_makeragent JSONs that write one. Switching agents printsonly
🔄 Switched to agent: <name>; the hint never appears.Why it matters
The field is accepted silently and Kiro Crew's own agents ship values for it, so
an author reasonably assumes it works and never learns otherwise. The only
workaround is to inline the hint into the system prompt, where it is re-sent on
every single turn — paying context forever for a string meant to be read once.
What changed (motivation → approach → change)
Goal: the hint reaches the user exactly when the agent becomes the one
answering, and costs nothing after that.
agent_welcome_messageinsrc/kiro_crew/agent_discovery.pyis now the field'sone reader, and
_surface_agent_welcomeinsrc/kiro_crew/dashboard/chat_runner.pyits one emitter. Two activation pointsfeed it: a cold session start, and a provider-side
EVENT_AGENT_SWITCHED, where thehint lands immediately after the
Switched to agentrow so the two read incausal order. At session start the name used is the RESOLVED template
(
kiro_agent or slot.agent), not the name the human picked: on a crew slotslot.agentis the member alias, which names no agent spec, so the alias wouldmiss the roster and drop the hint of the template that is actually answering.
The row is
role="notice", and that single choice is the design:_TRANSIENT_ROLES, so it persists and survives a reload — a transcriptentry, not a banner;
usernorassistant, so the history replay never feeds it back tothe model — the per-turn cost the system-prompt workaround pays;
NoticeCardas plain text, so agent-config copy cannot render asinstructions and no frontend change was needed.
One shot per activation, via a
_welcomed_agentfield added to_ChatSlotinsrc/kiro_crew/dashboard/state.py. A switch and the cold start its own sessionreset produces are two events for one activation, so both call sites clear
through that one field. The claim is taken before the offloaded read, so racing
events cannot both pass; a failed read counts as welcomed, so a broken agents
directory does not re-scan; and it is released on the empty agent, so returning
to an agent after the default crew greets again.
The field is untrusted input reaching a persisted window and every open tab:
absent, empty, whitespace-only and non-string values all render nothing
(
spec_str's existing rule), the text is capped at 2000 characters includingits ellipsis, and it goes
through the same
_redact_display_textcredential/exfil-URL redactors as anyother foreign string on that path. The read is offloaded to a thread and total —
an unreadable spec renders nothing rather than failing the turn.
Which spec is live is not decided here at all:
agent_welcome_messageaskslist_agentsfor the roster, takes the row whose name matches, and parses onlythat row's file. The roster is what the picker shows and what the backend
activates, so reading its winner is what makes the greeting describe the agent
that is running. Every rule the choice needs already lives there — scope
shadowing, declared-name over filename, package-installed and last-seen
duplicate winners — and reproducing any of it here would be a second copy that
can disagree, however well tested.
The winning file is re-read through the same hardened reader under this
function's own operation label, so a denial is attributed to the hint rather than
to a listing, with every guard re-applied on the reopen.
docs/system-specs/modules/learn-cron-dashboard.mdgains the owning### Agent welcome message (welcomeMessage)section in the same commit.Tests
test/test_agent_welcome_message.py— 40 tests in five groups:shapes (
null, int, object, list, bool); whitespace-only; surroundingwhitespace; exactly-at-cap kept verbatim; over-cap truncated with an ellipsis.
name beating a matching filename; a filename used when nothing declares the
name; project scope shadowing user level; a project-only agent; user level
still winning for a name the project lacks; a corrupt spec not hiding a good
neighbour; a missing agents directory; the cap applied to a spec read off disk.
declared name, a package spec, a stem-only spec, a project shadow) row by row
and asserts that the hint equals the
welcomeMessageof whichever filelist_agentsnamed, from the scope directory that row names. The precedenceoutcomes are
list_agents' own contract, covered by its own suite, so they aredeliberately not re-asserted through this reader; the project-shadow and
project-only tests cover the scope-to-directory mapping this reader does own.
pptx_makerspecs that ship awelcomeMessagenowrender one.
notice; the row is durable (outside_TRANSIENT_ROLES); the row is not a role the model replays; a secondactivation of the same agent emits nothing and does not re-read; a different
agent emits again; two concurrent activations emit once; no hint appends no
row; an empty agent name reads nothing; returning to an agent after the default
crew greets again;
slot.projectscopes the read; anAKIA…credential in thehint is redacted out of the appended row; an unreadable hint neither fails the
turn nor is retried.
_run_chatwith the real reader — a newsession on a named agent renders the hint; a warm session renders nothing (the
is_newgate, which only a runner turn exercises); a second turn on the samesession does not repeat it; a crew alias greets with its resolved template
rather than the alias; an in-turn agent switch renders the switched-to
agent's hint, positioned after the
Switched to agentrow.test/test_agent_spec_hardened_reads.pyregisters the reader's hardened-read callsite in the existing attribution ratchet.
Manual verification
N/A — unit coverage is sufficient: both activation points are exercised end to
end through
_run_chatagainst a real on-disk agent spec, which is the same patha live turn takes.
Screenshots / video
N/A — no new or changed component, layout or theme. The hint renders through the
existing
NoticeCardwith its existing styling, so there is no visual delta toshow; only the row's text content is new.
Related Issues
Fixes #1775
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)