Repository navigation
feat(kas): project welcomeMessage and includePowers onto the customAgents wire - #13015
Conversation
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/docs/agent-spec-fields.md:312 -- a project-local shadow can make False positive or not applicable? A repository writer can comment: |
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Confirm you accept the git-history case that the [DESIGN-REVIEWED] 97b6f8a |
First Principles Review (Fable 5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS
Not justified as shipped
What this change shipsInventory (6 items) — 5 justifiedIntent: make a spec author's
[FIRST-PRINCIPLES-REVIEWED] 97b6f8a |
5efd80b to
b501860
Compare
|
Answering the BLOCK's
class TestDeliberateOmissions:
"""Fields left out on purpose; each would misbehave if projected.
``mcpServers`` would double-register against the session-level injection,
``model`` would compete with the dedicated model verb, and ``permissions``
would require guessing KAS's capability identifiers.
"""
@pytest.mark.parametrize("key", ["mcpServers", "model", "permissions", "welcomeMessage"])Three of the four keys carry a reason in that docstring. So the list was an inventory of what the projection did not yet emit, not a set of reasoned refusals. The base docstring says as much about its own former members: " The dates make the point independently. When the pin was written, The doc row is the same kind of artefact: The full chain is now in the PR description under "Why the base's On the inventory framing: the description said "gap" for both halves, and for the
|
Opus 5 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: |
`ClientCustomAgentSchema` has a slot for both and the projection filled neither, so an agent spec that carries them reached a KAS session without them: a welcome hint the author wrote was invisible to the backend, and `includePowers: true` did not widen the agent's tool set there. `welcomeMessage` goes through `spec_welcome_message`, the same reading the dashboard transcript renders. One reader for both surfaces, so the hint a KAS session registers and the hint Crew shows cannot disagree -- and the cap, the whitespace rule and the non-string-is-absent rule that reading already applies to this user-writable field are not re-argued for a second path onto the wire. `includePowers` gets the shape `includeMcpJson` already had: forwarded when the spec states a bool, dropped when it states anything else, because `z.boolean()` rejects a non-bool and a client agent that fails the wire schema is dropped WHOLE. Both flags widen which tools are VISIBLE, not which are auto-approved: a tool they reveal still has no `permissions` rule, and this projection derives that policy from `allowedTools` alone, so the call resolves to `ask`. `includeMcpJson`'s behaviour is unchanged, and the absent case is now recorded as a decision rather than left looking like an oversight. No default is synthesized for an absent flag, because absence does not mean the same thing on the two hosts Crew writes specs for: kiro-cli reads an absent `includeMcpJson` as true, while KAS's own disk schema defaults it to false. Sending a default would be Crew inventing one host's answer and shipping it to the other. Nothing is lost by the silence -- the wire schema has no default and KAS's tool filter resolves an absent flag to false itself, which is already its disk default, so an absent flag reaches the same outcome the file would have on KAS with no guess from this side. `model` and `effortLevel` stay unprojected. They are not projection gaps: `model` has its own protocol verb and config option, and `effortLevel` has no wire slot at all. A test now pins both, plus `dispatchKind`. The `welcomeMessage` spec section claimed one reader and one emitter; it now names the wire projection as a second consumer sharing the one reading.
b501860 to
97b6f8a
Compare
GPT 5.6 Review —
|
…rodotdev#13015) `ClientCustomAgentSchema` has a slot for both and the projection filled neither, so an agent spec that carries them reached a KAS session without them: a welcome hint the author wrote was invisible to the backend, and `includePowers: true` did not widen the agent's tool set there. `welcomeMessage` goes through `spec_welcome_message`, the same reading the dashboard transcript renders. One reader for both surfaces, so the hint a KAS session registers and the hint Crew shows cannot disagree -- and the cap, the whitespace rule and the non-string-is-absent rule that reading already applies to this user-writable field are not re-argued for a second path onto the wire. `includePowers` gets the shape `includeMcpJson` already had: forwarded when the spec states a bool, dropped when it states anything else, because `z.boolean()` rejects a non-bool and a client agent that fails the wire schema is dropped WHOLE. Both flags widen which tools are VISIBLE, not which are auto-approved: a tool they reveal still has no `permissions` rule, and this projection derives that policy from `allowedTools` alone, so the call resolves to `ask`. `includeMcpJson`'s behaviour is unchanged, and the absent case is now recorded as a decision rather than left looking like an oversight. No default is synthesized for an absent flag, because absence does not mean the same thing on the two hosts Crew writes specs for: kiro-cli reads an absent `includeMcpJson` as true, while KAS's own disk schema defaults it to false. Sending a default would be Crew inventing one host's answer and shipping it to the other. Nothing is lost by the silence -- the wire schema has no default and KAS's tool filter resolves an absent flag to false itself, which is already its disk default, so an absent flag reaches the same outcome the file would have on KAS with no guess from this side. `model` and `effortLevel` stay unprojected. They are not projection gaps: `model` has its own protocol verb and config option, and `effortLevel` has no wire slot at all. A test now pins both, plus `dispatchKind`. The `welcomeMessage` spec section claimed one reader and one emitter; it now names the wire projection as a second consumer sharing the one reading. Co-authored-by: Joe Guo <zejiangg@amazon.com>
What
KAS's
ClientCustomAgentSchemahas a slot forwelcomeMessageandincludePowers, and Crew's projection filled neither. An agent spec carrying them reached a KAS session without them: a welcome hint its author wrote was invisible to the backend, andincludePowers: truedid not widen the agent's tool set there.Three fields, two of them new projections and one a decision recorded in place.
welcomeMessageincludePowersincludeMcpJsonwelcomeMessageProjected through
spec_welcome_message, the same functionagent_welcome_messageresolves to for the chat transcript. One reader for both surfaces, so the hint a KAS session registers and the hint Crew shows cannot disagree — and the cap (WELCOME_MESSAGE_MAX_CHARS), the whitespace rule and the non-string-is-absent rule that reading already applies to this user-writable, tool-shared field are not re-argued for a second path onto the wire._redact_display_textdeliberately does not reach the wire value: that redactor is about what a transcript row persists and re-broadcasts to open tabs, not about what the spec tells the backend — the same posturepromptanddescriptionalready have.includePowersGiven the shape
includeMcpJsonalready had: forwarded when the spec states a bool, dropped when it states anything else. A non-bool is not coerced becausez.boolean()rejects it and a client agent that fails the wire schema is dropped WHOLE (validateAndConvertClientCustomAgentslogsclient.agent.drop.invalidand moves on), which would cost the session its injected agent — not just the flag.Both flags widen which tools are VISIBLE, not which are auto-approved, so neither crosses the governance ceiling that filters
allowedTools. A tool they reveal still has nopermissionsrule, and this projection derives that policy fromallowedToolsalone, so KAS resolves the call toask. A test pins that: turning both flags on does not change the projectedpermissionsortools.includeMcpJson— behaviour unchanged, decision recordedNo default is synthesized for an absent flag, and that is now stated as a decision rather than left looking like an oversight.
"Absent" does not mean the same thing on the two hosts Crew writes specs for. kiro-cli reads an absent
includeMcpJsonas true (agent_capabilities.py,spec.get("includeMcpJson", True)); KAS's own disk schema defaults it to false (services/custom-agents/types.ts). Sending a default would be Crew inventing one host's answer and shipping it to the other.Nothing is lost by the silence. KAS's wire schema has no default (
resolve-client-agents.tscopies the field only when it is notundefined) and its consumer resolves an absent flag tofalseitself —tools/tool-filter.tsdestructuresincludeMcpJson = false, includePowers = falseand testspolicy.includeMcpJson === true. So an absent flag reaches exactly the outcome the file would have on KAS, with no guess from this side.Deliberately not touched
modelandeffortLevel. Neither is a projection gap:modelhas its own protocol verb and config option (kas_agents.py), andeffortLevelhas no wire slot at all.dispatchKindlikewise has no slot. A test now pins all three as unprojected, replacing the old parametrization that listedwelcomeMessagethere.Why the base's
welcomeMessagepin does not standThe first-principles lane is right that the base recorded
welcomeMessageas a deliberate omission, and right to ask for the pin's own reasoning rather than a fresh safety argument. Here it is, from git.The pin was born in
9d42ae227b("feat(kas): enable KAS as a working chat backend (#3435)", 2026-08-13), as a four-key list:Three of the four keys get a reason.
welcomeMessagegets none — not in that docstring, not in the module docstring (which arguesmodel,permissionsandmcpServersby name and never mentions it), and not anywhere in9d42ae227b's commit message.de75ef53da("fix(kas): carry auto-approve and the agent definition across the KAS seam (#4614)") later rewrote that same docstring and edited that same parametrize, and its message likewise never mentions the field.The list was an inventory of what the projection did not yet emit, not a set of reasoned refusals — and the project has already reversed two of its four entries on finding each was a defect. The base docstring says so in its own words: "
permissionsis NOT in this list", and "mcpServersis not in this list either: omitting it left a KAS session with@serverrefs naming nothing". The reasoned entries were the ones that turned out wrong; the unreasoned one is the one this PR reverses.The dates settle it. At the time of the pin,
welcomeMessagehad no reader anywhere in Crew. The transcript renderer landed on 2026-09-17, five weeks later (86d3ca5a8a, "feat: render an agent's welcomeMessage when it becomes active (#11413)"), and the spec section records exactly that: "the field had no reader at all before them, which is why the bundledpptx_makeragents ship a value nothing rendered". A field nothing in the process read cannot have been refused on the wire for a reason; there was no behaviour to refuse.The doc row is the same shape of artefact.
welcomeMessage | Crew-only (chat transcript) | same | samewas written on 2026-09-19 inc28c78e6db, a docs-only "add agent spec field reference" commit — a description of then-current behaviour written two days after the transcript reader landed, not a decision taken about the wire.So the surface added here is one
spec_welcome_messagecall and its tests, reversing the single entry in that list that no commit ever justified.modelstays pinned, and noweffortLevelanddispatchKindjoin it — those three have stated reasons (own protocol verb; no wire slot at all).Tests
test/test_kas_agents.py, two new classes plus an amended omissions test:TestWelcomeMessageProjection— present, absent, blank/whitespace/non-string, whitespace stripping, the cap with its ellipsis inside the budget, and an equivalence assertion that the wire value is byte-identical to what the transcript would render for the same spec.TestInclusionFlagProjection— both flags, both bool values forwarded verbatim; absent stays absent rather than defaulted; seven non-bool shapes dropped; and the permissions/tools invariance check above.TestDeliberateOmissions—model,effortLevel,dispatchKind, each asserted against a spec that actually declares the key.Revert-verify: removing the
welcomeMessageprojection and droppingincludePowersfrom the forwarded pair fails 6 of the new tests; restoring passes 190.Verification
test/test_kas_agents.py190 passed; withtest_kas_permissions.py,test_agent_welcome_message.py,test_agent_spec_fields_doc.py322 passed; with the remaining projection consumers (test_acp_harness_contract.py,test_worker_agent.py,test_member_dispatch_mount.py,test_markdown_agent_specs.py) a further 387 passed.flake8,mypy,black --checkclean on both changed Python files.scripts/docs_lint.pyall checks passed; diff-scopedcheck_comment_history.pyandcheck_brand_name.pypass.scripts/local-gate.pybackend related set: the only reds are 53 intest/test_acp_runtime.py, reproduced identically (52 failed / 396 passed under-n 2) in a detached worktree at cleanorigin/main. Main-side, not this diff.Docs and spec
src/kiro_crew/docs/agent-spec-fields.md:welcomeMessageandincludeMcpJsonrows updated, anincludePowersrow added, and both per-surface table rows corrected.docs/system-specs/modules/learn-cron-dashboard.md: thewelcomeMessagesection claimed one reader and one emitter. It now names the wire projection as a second consumer that shares the one reading, and says which of the untrusted-input rules follow it there.