Skip to content

feat(kas): project welcomeMessage and includePowers onto the customAgents wire - #13015

Merged
chenmingwei23 merged 1 commit into
mainfrom
feat/kas-project-wire-fields
Sep 23, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
feat/kas-project-wire-fields

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

What

KAS's ClientCustomAgentSchema has a slot for welcomeMessage and includePowers, 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, and includePowers: true did not widen the agent's tool set there.

Three fields, two of them new projections and one a decision recorded in place.

Field Before After
welcomeMessage not projected projected, through the dashboard's own reading
includePowers not projected forwarded when the spec states a bool
includeMcpJson forwarded only when explicitly set unchanged; the absent case is now argued in the code

welcomeMessage

Projected through spec_welcome_message, the same function agent_welcome_message resolves 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_text deliberately 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 posture prompt and description already have.

includePowers

Given the shape includeMcpJson already had: forwarded when the spec states a bool, dropped when it states anything else. A non-bool is not coerced because z.boolean() rejects it and a client agent that fails the wire schema is dropped WHOLE (validateAndConvertClientCustomAgents logs client.agent.drop.invalid and 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 no permissions rule, and this projection derives that policy from allowedTools alone, so KAS resolves the call to ask. A test pins that: turning both flags on does not change the projected permissions or tools.

includeMcpJson — behaviour unchanged, decision recorded

No 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 includeMcpJson as 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.ts copies the field only when it is not undefined) and its consumer resolves an absent flag to false itself — tools/tool-filter.ts destructures includeMcpJson = false, includePowers = false and tests policy.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

model and effortLevel. Neither is a projection gap: model has its own protocol verb and config option (kas_agents.py), and effortLevel has no wire slot at all. dispatchKind likewise has no slot. A test now pins all three as unprojected, replacing the old parametrization that listed welcomeMessage there.

Why the base's welcomeMessage pin does not stand

The first-principles lane is right that the base recorded welcomeMessage as 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:

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 get a reason. welcomeMessage gets none — not in that docstring, not in the module docstring (which argues model, permissions and mcpServers by name and never mentions it), and not anywhere in 9d42ae227b'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: "permissions is NOT in this list", and "mcpServers is not in this list either: omitting it left a KAS session with @server refs 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, welcomeMessage had 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 bundled pptx_maker agents 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 | same was written on 2026-09-19 in c28c78e6db, 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_message call and its tests, reversing the single entry in that list that no commit ever justified. model stays pinned, and now effortLevel and dispatchKind join 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 welcomeMessage projection and dropping includePowers from the forwarded pair fails 6 of the new tests; restoring passes 190.

Verification

  • test/test_kas_agents.py 190 passed; with test_kas_permissions.py, test_agent_welcome_message.py, test_agent_spec_fields_doc.py 322 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 --check clean on both changed Python files.
  • scripts/docs_lint.py all checks passed; diff-scoped check_comment_history.py and check_brand_name.py pass.
  • scripts/local-gate.py backend related set: the only reds are 53 in test/test_acp_runtime.py, reproduced identically (52 failed / 396 passed under -n 2) in a detached worktree at clean origin/main. Main-side, not this diff.

Docs and spec

src/kiro_crew/docs/agent-spec-fields.md: welcomeMessage and includeMcpJson rows updated, an includePowers row added, and both per-surface table rows corrected.

docs/system-specs/modules/learn-cron-dashboard.md: the welcomeMessage section 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.

@iamwhatever
iamwhatever requested review from a team and cixuuz September 23, 2026 06:09
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 23, 2026
@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 97b6f8ace6beba501f0353daa1263af6bd9064a6 and found no blocking issues.

This comment is updated in place on each push.

Review details

FINDING -- src/kiro_crew/docs/agent-spec-fields.md:312 -- a project-local shadow can make "the two surfaces cannot disagree" false because KAS reads the user-level spec while the transcript resolves the project spec -> Fix: state that only normalization is shared and name both readers. (origin: validation)
[GPT-REVIEWED] 97b6f8a

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

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Confirm you accept the git-history case that the welcomeMessage omission pin was unreasoned inventory — the PR reverses it on that argument alone.

[DESIGN-REVIEWED] 97b6f8a

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of 97b6f8ace6beba501f0353daa1263af6bd9064a6 — 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: CONCERNS

includePowers rests entirely on an unread external premise — KAS's schema slot and tool-filter default are asserted, not confirmable from anything in this repo.

Not justified as shipped

  • Item 2 — unverified provider claim: "z.boolean() rejects it… tools/tool-filter.ts destructures includeMcpJson = false, includePowers = false" is a reading of kiro-team/kiro-agent source nothing in-repo pins (unlike _KAS_WIRE_SCHEMA_KEYS, which pins the sibling transcription with provenance and date); grep includePowers repo-wide finds 0 producing specs (3 bundled specs produce welcomeMessage; only a kiro-cli doc row mentions includePowers). If the slot reading is wrong, KAS's zod object strips the key and this half ships a silent no-op.
    Subtraction: if unconfirmed, drop includePowers from the forwarded pair at kas_agents.py:764 — the welcomeMessage fix stands without it.
    Clears when: the ClientCustomAgentSchema slot and the includePowers = false destructure are confirmed on kiro-team/kiro-agent main (resolve-client-agents.ts, tools/tool-filter.ts).

What this change ships

Inventory (6 items) — 5 justified

Intent: make a spec author's welcomeMessage and includePowers take effect on the KAS backend, where the projection silently dropped them — a FIX (new tests fail on base; 3 bundled pptx_maker specs ship unread hints).

  1. A spec's welcome hint now reaches a KAS session, capped and stripped by the same reading the transcript renders — justified
  2. A spec's includePowers bool is now forwarded to KAS — unverified provider claim (see above)
  3. includeMcpJson unchanged; its absent-case is now argued in comments (agent_capabilities.py:957 absent→true verified) — justified
  4. The deliberate-omissions pin drops welcomeMessage, adds effortLevel/dispatchKind — justified (the base pin's own docstring reasons model/permissions/mcpServers and never welcomeMessage; the description quotes the git history)
  5. Spec-field and host-contract doc rows updated in the same commit — justified (AGENTS.md mandate)
  6. New tests pin cap, whitespace, non-bool drop, and permissions invariance — justified

[FIRST-PRINCIPLES-REVIEWED] 97b6f8a

@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 23, 2026
@iamwhatever
iamwhatever force-pushed the feat/kas-project-wire-fields branch from 5efd80b to b501860 Compare September 23, 2026 06:47
@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 23, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Answering the BLOCK's Clears when on its own terms — the commit that placed welcomeMessage in TestDeliberateOmissions, and what it says about the field.

9d42ae227b ("feat(kas): enable KAS as a working chat backend (#3435)", 2026-08-13) created the list as four keys:

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. welcomeMessage carries none — not there, not in the module docstring (which argues model, permissions and mcpServers by name and never mentions it), and nowhere in 9d42ae227b's commit message. de75ef53da (#4614) later rewrote that docstring and edited that parametrize, and its message never mentions the field either.

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: "permissions is NOT in this list", and "mcpServers is not in this list either: omitting it left a KAS session with @server refs naming nothing". Two of its four entries had stated reasons and were reversed anyway, each on finding the omission was a defect. This PR reverses the one entry no commit ever justified.

The dates make the point independently. When the pin was written, welcomeMessage had no reader anywhere in Crew — the transcript renderer landed five weeks later, on 2026-09-17 (86d3ca5a8a, #11413). The spec section states it plainly: "the field had no reader at all before them, which is why the bundled pptx_maker agents ship a value nothing rendered." A field nothing in the process read was not being refused on the wire for a reason; there was no behaviour to refuse.

The doc row is the same kind of artefact: welcomeMessage | Crew-only (chat transcript) | same | same was written on 2026-09-19 in c28c78e6db, a docs-only "add agent spec field reference" commit — a description of then-current behaviour recorded two days after the reader landed, not a decision about the wire.

The full chain is now in the PR description under "Why the base's welcomeMessage pin does not stand", since that is what the lane reads.

On the inventory framing: the description said "gap" for both halves, and for the welcomeMessage half "addition reversing an unreasoned pin" is the more accurate word. That is now what the description says.

model stays pinned, and effortLevel and dispatchKind join it. Those three have stated reasons — model has its own protocol verb and config option, and neither effortLevel nor dispatchKind has a wire slot at all.

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 97b6f8ace6beba501f0353daa1263af6bd9064a6 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 97b6f8a

Verdict parsed from the review's SHA-scoped output markers for commit 97b6f8ace6beba501f0353daa1263af6bd9064a6.

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

@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 23, 2026
`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.
@iamwhatever
iamwhatever force-pushed the feat/kas-project-wire-fields branch from b501860 to 97b6f8a Compare September 23, 2026 07:29
@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ⚠️ review incomplete

GPT 5.6 did not produce a complete verdict for 97b6f8ace6beba501f0353daa1263af6bd9064a6; inspect the workflow logs and re-run it.

This comment is updated in place on each push.

See the GPT 5.6 Review job logs; this commit has no completed GPT verdict.

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

@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 23, 2026
@chenmingwei23
chenmingwei23 merged commit c9a982f into main Sep 23, 2026
140 of 148 checks passed
@chenmingwei23
chenmingwei23 deleted the feat/kas-project-wire-fields branch September 23, 2026 16:08
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 23, 2026
wknight1 pushed a commit to wknight1/KiroCrew that referenced this pull request Oct 5, 2026
…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>
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.

2 participants