Skip to content

feat: render an agent's welcomeMessage when it becomes active - #11413

Merged
bolichen97 merged 1 commit into
mainfrom
fix/1775-render-welcome-message
Sep 18, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/1775-render-welcome-message

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

An agent spec may carry a welcomeMessage — a usage hint its author writes for
whoever the agent is about to help. Nothing reads it. On main the only
occurrences are agent_capabilities.py's passthrough field list, docs, and the
three bundled pptx_maker agent JSONs that write one. Switching agents prints
only 🔄 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_message in src/kiro_crew/agent_discovery.py is now the field's
one reader, and _surface_agent_welcome in
src/kiro_crew/dashboard/chat_runner.py its one emitter. Two activation points
feed it: a cold session start, and a provider-side EVENT_AGENT_SWITCHED, where the
hint lands immediately after the Switched to agent row so the two read in
causal 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 slot
slot.agent is the member alias, which names no agent spec, so the alias would
miss 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:

  • outside _TRANSIENT_ROLES, so it persists and survives a reload — a transcript
    entry, not a banner;
  • neither user nor assistant, so the history replay never feeds it back to
    the model — the per-turn cost the system-prompt workaround pays;
  • drawn by NoticeCard as plain text, so agent-config copy cannot render as
    instructions and no frontend change was needed.

One shot per activation, via a _welcomed_agent field added to _ChatSlot in
src/kiro_crew/dashboard/state.py. A switch and the cold start its own session
reset 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 including
its ellipsis, and it goes
through the same _redact_display_text credential/exfil-URL redactors as any
other 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_message asks
list_agents for the roster, takes the row whose name matches, and parses only
that 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.md gains the owning
### Agent welcome message (welcomeMessage) section in the same commit.

Tests

test/test_agent_welcome_message.py — 40 tests in five groups:

  • Reader coercion and ceiling — plain string; absent key; five non-string
    shapes (null, int, object, list, bool); whitespace-only; surrounding
    whitespace; exactly-at-cap kept verbatim; over-cap truncated with an ellipsis.
  • Reader resolution — user-level read; unknown agent; empty name; a declared
    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.
  • Agreement with the roster — one test walks a mixed directory (a duplicate
    declared name, a package spec, a stem-only spec, a project shadow) row by row
    and asserts that the hint equals the welcomeMessage of whichever file
    list_agents named, from the scope directory that row names. The precedence
    outcomes are list_agents' own contract, covered by its own suite, so they are
    deliberately not re-asserted through this reader; the project-shadow and
    project-only tests cover the scope-to-directory mapping this reader does own.
  • Bundled agents — the pptx_maker specs that ship a welcomeMessage now
    render one.
  • Emitter — role is notice; the row is durable (outside
    _TRANSIENT_ROLES); the row is not a role the model replays; a second
    activation 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.project scopes the read; an AKIA… credential in the
    hint is redacted out of the appended row; an unreadable hint neither fails the
    turn nor is retried.
  • Runner turns, driven through _run_chat with the real reader — a new
    session on a named agent renders the hint; a warm session renders nothing (the
    is_new gate, which only a runner turn exercises); a second turn on the same
    session 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 agent row.

test/test_agent_spec_hardened_reads.py registers the reader's hardened-read call
site in the existing attribution ratchet.

Manual verification

N/A — unit coverage is sufficient: both activation points are exercised end to
end through _run_chat against a real on-disk agent spec, which is the same path
a live turn takes.

Screenshots / video

N/A — no new or changed component, layout or theme. The hint renders through the
existing NoticeCard with its existing styling, so there is no visual delta to
show; only the row's text content is new.

Related Issues

Fixes #1775

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
  • 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

@iamwhatever
iamwhatever requested review from a team and smeyffret September 17, 2026 00:55
@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: checking Automated validation is still running labels Sep 17, 2026
@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Eyeball one near-cap (2000-char) hint in NoticeCard once — "no visual delta" is asserted, not shown, and this is its first long-text payload.

Suggestions

  • The channel surfaces now re-create the original harm one level up (hint works in dashboard, silently absent on Slack/Discord); file the follow-up issue so the deliberate scope-out is tracked, not rediscovered.

[DESIGN-REVIEWED] 11739b4

@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 11739b47d0b130b05ae05107b8a54797ab55ea45 and found no blocking issues.

This comment is updated in place on each push.

Review details

FINDING -- src/kiro_crew/dashboard/chat_runner.py:694 -- changing projects can activate a shadowing same-name agent, but "slot._welcomed_agent == agent" suppresses its welcome -> Fix: key the claim by agent and project.
[GPT-REVIEWED] 11739b4

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

@iamwhatever
iamwhatever force-pushed the fix/1775-render-welcome-message branch from e02751f to f76bb0c Compare September 17, 2026 01:00
@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

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

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 ships

Inventory (9 items) — 9 justified

Intent: an agent author's welcomeMessage should reach the user when that agent starts answering — ADDITION (linked issue #1775; the field is verifiably dead on base: 3 bundled specs write it, only the ORDINARY_FIELDS publish passthrough touches it, zero readers).

  1. Agent's welcome hint appears as a persistent notice at cold session start — justified
  2. The hint appears again right after the "Switched to agent" row — justified
  3. A crew slot greets with the resolved template, not the member alias — justified
  4. Hints over 2000 chars are truncated with an ellipsis — justified
  5. Credentials/exfil URLs in a hint are redacted before rendering — justified
  6. Non-string, empty, or unreadable hints render nothing instead of erroring — justified
  7. Returning to an agent after the default crew greets again; same activation never repeats — justified
  8. New reader functions in agent_discovery (one counted consumer each, ungeneralized; grepped welcomeMessage, agent_welcome_message) — justified
  9. Owning spec section added in the same commit (AGENTS.md mandate) — justified

Reuses every existing seam: spec_str, list_agents' roster, the hardened spec reader, the existing notice role (10+ existing emitters), _redact_display_text, NoticeCard (renders text as a bare JSX child — the plain-text claim holds). No deleted pins; no undeclared items; sibling dead field keyboardShortcut is a different feature, not this fix generalized.

[FIRST-PRINCIPLES-REVIEWED] 11739b4

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

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

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

Review details

The 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 list_agents (deduped one-row-per-name, project shadows global, edition rows add-only), reconstructs the directory from the row's two-value scope (SCOPE_PROJECT → project dir, else _kiro_agents_dir()), and any missing/edition-only/package file simply yields "" via a None read — no crash, no wrong-file read. The emitter claims _welcomed_agent before the offloaded await (race-safe), releases it on the empty-agent path, persists a non-replayed notice row, and redacts untrusted text. Truncation keeps the ellipsis inside the budget. No reachable crash, security hole, data loss, or removed guard on the added lines.

No findings.

[OPUS-REVIEWED] 11739b4

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

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

@iamwhatever
iamwhatever force-pushed the fix/1775-render-welcome-message branch 2 times, most recently from 918ce04 to 2340131 Compare September 17, 2026 02:14
@iamwhatever

Copy link
Copy Markdown
Contributor Author

CI status on 2340131ba2 — two reds are main's, not this PR's

Rebased onto 04727ebe0f to pick up #11415, which fixed the flake8 F401 in
src/kiro_crew/dashboard/handlers/sessions.py that this PR was inheriting. That
lane should now be green.

Two failures remain that this branch does not cause. Both were reproduced on a
pristine origin/main checkout (git worktree add --detach origin/main,
zero changes applied), so they are not sensitive to anything here:

1. test/test_fargate_launch_engine.py — 2 failures

test_engine_satisfies_the_launch_engine_protocol
  AssertionError: begin_signin: ['instance_id', 'profile', 'region']
                             != ['instance_id', 'profile', 'region', 'login_target']
test_signin_handle_has_every_signin_handle_protocol_member

The engine's begin_signin is missing the login_target parameter the protocol
declares. Untouched here; this PR changes no file under src/kiro_crew/cloud/.

2. test/test_remove_slot_for_history_key.py::TestSessionLedgerOnPermanentDelete::test_a_ledger_a_writer_still_owns_is_left_to_retention

kiro_crew.ledger.errors.LedgerError: data.agent: is required and absent

Appeared with the newer base (it passed on e65ec3ece7), and reproduces on
pristine origin/main under -n 8 --dist loadgroup. Untouched here; this PR
changes nothing in src/kiro_crew/ledger/ or the permanent-delete path.

Neither is fixed in this PR: both are unrelated subsystems, and folding either
one in would make this an undeclared rider on a feature change.

What this PR's own gates say

All eight review and scan lanes passed on the previous head (918ce04022, same
tree plus the rebase): GPT 5.6, Opus 4.8, Design, First Principles, UX, Security
Scope, CodeQL, SAST (Semgrep), plus internal-content-scan and Docs Lint.

Locally against the current base: black / isort / flake8 src/kiro_crew test
clean, mypy --platform linux src/kiro_crew clean (1614 files),
check_comment_history.py and docs-lint.sh pass. Suites green:
test_agent_welcome_message.py (40 new), test_agent_spec_hardened_reads.py
(71), test_agent_discovery.py (65), test_dashboard_chat.py (796), and the
tree-scan contract set (test_agent_sdk_boundary /
test_sync_io_in_async_gate / test_lazy_data_home_paths /
test_leaf_test_scope / test_ci_surface_tests, 311).

@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 Sep 17, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Update: every remaining red on 2340131ba2 is main's, and the ledger one has a named culprit

The five failing shards contain exactly two upstream defects and nothing else.
Both reproduce on a pristine origin/main checkout at 04727ebe0f — git worktree add --detach origin/main, zero changes applied.

A. Ledger data validation — 45 failures

kiro_crew.ledger.errors.LedgerError: data.agent: is required and absent
kiro_crew.ledger.errors.LedgerError: entry type domain must be a plain name
                                     or app:<name>: 'crew:qa/report'

Files: test_ledger_retention.py (44), test_ledger_types.py,
test_ledger_kinds.py, test_remove_slot_for_history_key.py.

Introduced by 039d3e83d7 — feat(ledger): declare the session entry types and
validate data on write
(#11317). It began validating data on write without
updating the fixtures that append without an agent. Reproduced on pristine
main: 45 failed, 153 passed.

B. Fargate signin protocol — 2 failures

begin_signin: ['instance_id', 'profile', 'region']
           != ['instance_id', 'profile', 'region', 'login_target']

test_fargate_launch_engine.py. Reproduced on pristine main: 2 failed, 43
passed
.

Shard-by-shard, with the sole contents of each failure set:

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.

@iamwhatever
iamwhatever force-pushed the fix/1775-render-welcome-message branch from 2340131 to 7e54a6b Compare September 17, 2026 06:27
@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 Sep 17, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Intent: Make an agent's welcomeMessage reach the user once, as a durable transcript row, at the moment that agent becomes the one answering — so the field an author writes (and that Kiro Crew's own bundled agents ship) stops being silently inert, without costing per-turn context the way inlining it into the system prompt does.

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.

@iamwhatever
iamwhatever force-pushed the fix/1775-render-welcome-message branch from 7e54a6b to 11d1730 Compare September 17, 2026 08:22
@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 Sep 17, 2026
@iamwhatever
iamwhatever force-pushed the fix/1775-render-welcome-message branch from 11d1730 to 0bb6d13 Compare September 17, 2026 17:49
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • duplicate declared names returned the first spec while list_agents() prefers the package spec — fixed in 0bb6d136e3 span=bd43b2b711db
    self-added: yes
    mechanism: _package_filename_parts shared by the roster row builder and the hint reader; _welcome_scope_winner applies the roster's package-first precedence per scope.

Legitimate and reachable. list_agents dedupes by name preferring a row with a
package ({package}-{name}.json) over a bare-filename one, so with both
helper.json and pkg-helper.json declaring helper the picker listed the
package agent while the reader returned the bare file's hint — the greeting
described an agent that was not running, the exact disagreement the reader's own
docstring promised not to have.
Fixed at the shared rule, not this call site: the filename convention now lives
in _package_filename_parts, called by BOTH _global_agent_info (roster row)
and the new _welcome_scope_winner. The duplicated arithmetic is what let the
two drift; patching only the reader leaves the next consumer free to drift again.
Precedence is a WITHIN-scope tie-break — project scope still shadows the user dir
entirely, and _project_agent_info reads no package out of a checkout, so the
scope carries a flag. Keyed on the package STRING, not the boolean:
local-{name}.json is a package filename with an EMPTY package, and the boolean
would let it outrank a real one.
Four tests cross-check the reader against list_agents on the same directory
rather than a hardcoded winner. Two fail with the precedence reverted and the
tests otherwise unchanged; the other two guard against over-fixing.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • channel surfaces could reuse agent_welcome_message at their own activation point — correct, and out of scope for this PR span=7595d06b0cad

The suggestion reads the design right: the reader / emitter split is what makes a
channel emitter additive. agent_welcome_message takes an agent name plus an
optional project and returns display-ready text, so Slack or Discord needs no
change to it — only its own call at its own activation moment. Nothing here has
to change for that to land later, which is the property the item itself notes.
Disproportional to fold in here, and the PR's stated non-goal. The channels have
a different activation model: no _ChatSlot, so no slot._welcomed_agent to
make the hint one-shot, and no notice role — their transcript is the channel
itself. Where the one-shot state lives, and whether an edited message or a new
one carries the hint, is a per-channel design question, not a mechanical second
call site. Answering it would widen a dashboard-scoped change into every
messaging transport and re-arm every lane on that whole diff.
Recorded as scope, not as tracked work: no issue is filed, because this is a
PASS-verdict suggestion about a future surface, not a defect in this diff.

@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 Sep 17, 2026
@iamwhatever
iamwhatever force-pushed the fix/1775-render-welcome-message branch from 0bb6d13 to ba4a86b Compare September 17, 2026 19:19
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • Item 2 — point patch: 3 non-dashboard "Switched to agent" sites do not emit the hint — rebutted: the reported defect is dashboard-scoped span=ab64e0da41ab

Taking the item's own second clearing condition, which is the one the evidence
supports. Issue #1775 is titled "Render an agent's welcomeMessage when the agent
becomes active in the dashboard"; its reproduction is the macOS desktop app,
its "Proposed behaviour" asks for the transcript next to the dashboard's
"Agent changed to" line, and it closes by scoping itself to "KiroCrew's
observable behavior". So the three Slack sites are not unfixed siblings of the
reported defect; they are a different surface the report does not claim.
The PR says so in its own words: "Not a goal: ... no change to the channels
(Slack, Discord, cron) — only the dashboard chat session's own activation
points."
They are also not mechanically the same fix, which is why folding them in is
not the smaller option. A Slack thread has no _ChatSlot, so there is no
slot._welcomed_agent to make the hint one-shot, and no notice role — its
transcript is the channel itself, where the hint would either edit an existing
message or post a new one. Choosing that, per transport, is design work the
report does not settle, and doing it here would re-arm every lane on a diff
spanning every messaging transport.
The reader/emitter split is what keeps that additive: agent_welcome_message
takes a name plus an optional project and returns display-ready text, so each
channel needs only its own call at its own activation moment.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • Item 7 — _welcome_scope_winner re-spells list_agents' duplicate-name winner: 2 copies kept agreeing by tests — fixed by making the deletion in ba4a86b4df span=24fc0dfdc774

Correct, and the subtraction is the right call: four cross-check tests are
evidence the copies agree TODAY, not a reason they cannot drift. Deleted rather
than defended.
agent_welcome_message now asks list_agents for the roster, takes the row
whose name matches, and parses only that row's file. It states no precedence of
its own — project shadowing, declared-over-filename, package-wins-a-duplicate
and last-seen-among-project-duplicates all stay where they already lived.
Round 1's two helpers are gone with it: _welcome_scope_winner deleted, and
_package_filename_parts reverted back inline into _global_agent_info, whose
only caller it ever had. Net effect on this file is 99 lines deleted against 61
added, leaving it closer to main than round 1 left it.
Neither candidate constraint blocks the reuse. SEL attribution is preserved:
the winner's file is re-read through _read_agent_spec under this function's
own agent_welcome_message label, so a denial is still attributed to the hint
and not to a listing, and the reopen re-applies the full guard set. Nothing is
read off AgentInfo but name, filename and scope, so its serialization
is untouched — no new field, no /api/agents payload change.
The tests were rewritten to assert the law instead of the rules: each now checks
only that the hint equals the welcomeMessage of whichever file the roster
selected.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • duplicate project specs greeted from the first file while list_agents() activates the last — fixed in ba4a86b4df span=bd43b2b711db
    self-added: yes
    mechanism: none added — the local precedence was DELETED; agent_welcome_message now reads list_agents' winning row.

Legitimate. list_agents walks the project files after the user ones and
assigns seen[name] = info unconditionally, so among two project specs
declaring one name the LAST wins, while declared[0] took the first.
Not fixed by selecting the last row for project scope, which would have been a
third spelling of the roster's rules. The whole local precedence is gone:
agent_welcome_message asks list_agents for the roster and parses only the
row it selected, so project ordering, package precedence and declared-over-stem
are all read rather than reproduced. This closes First Principles' Item 7
subtraction in the same edit.
A regression test pins the case directly: two project specs declaring one name,
asserted against the file the roster names rather than against a hardcoded
winner.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • truncation exceeded the documented 2000-character ceiling by one — fixed in ba4a86b4df span=bd43b2b711db
    self-added: yes
    mechanism: none added — the slice now reserves the ellipsis's character inside the existing cap.

Legitimate: text[:WELCOME_MESSAGE_MAX_CHARS] + "…" returned cap+1 characters
while the docstring promised truncation AT the cap, and the test asserted the
wrong number rather than catching it.
The ellipsis is part of the budget, not an addition to it, so the slice now
takes WELCOME_MESSAGE_MAX_CHARS - 1. The result is exactly the cap, and the
two tests that asserted cap+1 were corrected to the cap.

@iamwhatever
iamwhatever force-pushed the fix/1775-render-welcome-message branch from ba4a86b to f35c64c Compare September 17, 2026 21:01
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • the empty-agent early return preserved the claim, so A → default → A never greeted again — fixed in f35c64c6bf span=8023cfe9506b
    self-added: yes
    mechanism: none added — the existing guard now RELEASES slot._welcomed_agent on the empty agent instead of returning past it.

Legitimate, and the diagnosis is exact: if not agent or slot._welcomed_agent == agent: return left the field naming A while the default crew answered, so
A's next activation read as already welcomed and was swallowed.
This is an under-correction of the one-shot rule, not an over-built one. The
rule is per ACTIVATION, which the suite already asserted for a different
agent (test_switching_to_a_different_agent_emits_again) but never for a
return to the same one.
Fixed as suggested, by clearing rather than skipping: the empty branch now sets
slot._welcomed_agent = "" before returning. No new state and no new mechanism
— the release is the missing half of the claim the field already held.
test_returning_to_an_agent_after_the_default_greets_again pins it: A →
default → A must emit twice and read the spec twice. It fails with the branch
reverted and the test otherwise unchanged.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • round-2 retrospective: verification bulk, not logic, was the remaining excess — subtraction taken — fixed in f35c64c6bf span=24fc0dfdc774
    self-added: yes
    mechanism: none added — 120 net lines REMOVED (tests −162, spec −41 rewritten to the contract).

Round 2's retrospective (read-only, opus-pinned) ruled the production side close
to minimal after this lane's own Item 7 deletion, and located the remaining
excess in what surrounds it. Its subtractions, all taken:
Six roster-agreement tests DELETED. Once agent_welcome_message reads
list_agents' winning row, those tests assert list_agents' precedence, which
its own suite owns; two even asserted roster internals
(roster[0].filename == "pkg-helper.json") through this reader, and one still
reasoned in its docstring about _package_filename_parts, deleted in round 1.
One test now carries the reader's real contract: the hint equals the
welcomeMessage of whichever file the roster named, walked row by row over a
mixed directory.
Also deleted: a near-duplicate project-shadow case, the literal "notice"
string pin (the durability and not-replayed tests subsume it), and the runner
default-crew case the emitter's empty-name test already proved.
The 41-line spec section was rewritten as a contract list, with the rationale
left in the three docstrings it was duplicating.
One departure, stated rather than silently skipped: the retrospective offered
"smaller replacement" on the ellipsis-inside-the-cap guarantee. KEPT. Removing
it returns the result to cap+1, which is precisely the finding the GPT lane
raised and this PR already recorded as fixed — so the smaller option reopens a
settled defect, which is the one case the rule says keeps the mechanism.
Net: 921 → 801 insertions, no behavioural guarantee lost.

@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 Sep 17, 2026
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
@iamwhatever
iamwhatever force-pushed the fix/1775-render-welcome-message branch from f35c64c to 11739b4 Compare September 17, 2026 22:19
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • a crew alias passed slot.agent instead of its resolved template, omitting the running agent's welcome — fixed in 11739b47d0 span=8023cfe9506b
    self-added: yes
    mechanism: none added — the session-start call site now forwards kiro_agent or slot.agent.

Legitimate. On a crew slot slot.agent is the member the human picked, which
names no agent spec, so the roster lookup missed and the hint of the template
that actually answers the turn was dropped in silence. The comment two lines
below the call site already said as much — "slot.agent is the member the human
picked; kiro_agent is the template it resolved to" — so the call site was
reading the wrong one of a pair the file already distinguishes.
Fixed exactly as suggested: kiro_agent or slot.agent. kiro_agent is bound to
None before the resolution block and set from bindings.kiro_agent, so the
fallback covers an ordinary slot, where no template resolution happened and the
two are the same name. Both empty is still the default crew, which has no spec.
The switch site is unchanged: it already greets for the provider-reported agent,
which IS the running one.
test_a_crew_alias_greets_with_its_resolved_template pins it through
_run_chat: only the template carries a hint, the slot carries the alias, and
the recorded call must name the template. Reverting the argument reproduces the
defect verbatim — AssertionError: greeted for ['crew-alias'], not the resolved template.

@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 Sep 17, 2026
@bolichen97
bolichen97 merged commit 86d3ca5 into main Sep 18, 2026
86 checks passed
@bolichen97
bolichen97 deleted the fix/1775-render-welcome-message branch September 18, 2026 00:28
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 18, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…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>
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.

Render an agent's welcomeMessage when the agent becomes active in the dashboard

2 participants