Repository navigation
feat(workflows): Kiro Agent workflow engine router and runtime hooks - #25449
kyleseaman wants to merge 2 commits into
Conversation
Sensitive Change ReviewSensitive files changed:
How to clear this check:
Only the author's comment counts this way. A reviewer can instead |
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the engine stays off unless Notes
[DESIGN-REVIEWED] 31930a7 Description read[DESCRIPTION-READ] f6a0ca650970f6b5208d38fe3a06982219b38833a7e57a9c55f23b0d8cef152d That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks: the feature sits behind Notes
What this change shipsInventory (8 items) — 6 justifiedIntent: with Kiro Agent as the backend, a developer can turn on Kiro Workflows and launch, watch, answer and control runs, and every question or approval a run raises is held for a person. This is an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 31930a7 Description read[DESCRIPTION-READ] d7b489ea65b7426f0fc343f6d8fec7b8e0528576371df1a8ec8a41b7c5c5e3c6 That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
b8172e4 to
34493fd
Compare
1b3bd69 to
be39318
Compare
bd01ffa to
3a99302
Compare
97adf5a to
3f3cfc9
Compare
3f3cfc9 to
ac93e55
Compare
ac93e55 to
235f2af
Compare
Code change approver recommendation: A person should decideWhy: the decider thinks the change is probably fine but estimates a 20% chance that this change introduces a defect, above the 12% limit for approving on its own. This PR adds the router and runtime hooks for Kiro Agent (KAS) workflows. In production it does nothing yet: An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
d6acbd5 to
91df23c
Compare
91df23c to
16b05a1
Compare
16b05a1 to
070d653
Compare
070d653 to
f171dd8
Compare
f171dd8 to
7fbb2a2
Compare
7145fa2 to
c4ca870
Compare
The engine half of Kiro Workflows on Kiro Agent: the router that launches runs on the parent chat's own KAS process, routes each runtime's workflow frames into the one run mirror, holds step approvals and questions (kas_workflows/router.py, asks.py, policy.py), reads a step's transcript (transcript.py), and recovers interrupted runs; the ACP runtime and session-handle hooks that carry those frames and the observed engine turns (acp/workflow_sink.py, session_handle_kas.py, runtime_*); and the live-capture recorder (scripts/capture_kas_workflow.py). A project directory a caller names is resolved and confined to server-held roots (home, KIROCREW_PROJECT_DIR, recent projects) before any filesystem use (kas_workflows/project_root.py). Router, asks and transcript redact the text they hand to any surface, and are registered as redaction sinks. All of it is inert unless agent.kas_workflows is on and the backend is Kiro Agent.
…line cap kas_workflows/router.py was 2,829 lines, over the repository's file line cap. Its types, limits and pure helpers move to router_base.py, and three groups of KasWorkflowRouter methods move to owner modules the class binds back by name (own_methods), the pattern AcpRuntime and AcpSessionHandle use: router_reads.py (requests, rows, recipes, run lists, step transcripts), router_controls.py (run, step and recovery controls) and router_recovery.py (ledger, reconnects, boot recovery). router.py keeps the class, every method that redacts, the module entry points and the singleton, and imports every moved name, so router.<name> still resolves for callers and tests. Every redactor call stays in router.py, the module the security posture registry names; the new modules call none. The moved code is AST-identical except one line in schedule_reattach that unpacks the binding before the closure, so mypy can type it. scripts/capture_kas_workflow.py reads the kiro-cli and Kiro Agent versions after the drive instead of before it: kiro-cli extracts its engine on the first acp spawn, so a fresh HOME has no @kiro/agent package.json until then. The new waits in test_acp_observe_turn.py, test_kas_workflows_parity.py and test_kas_workflows_step_user_input.py take their bound from kiro_crew.testing.wait (default_timeout, or async_wait_until's own default) instead of a short literal, as the flake ratchet's K19 rule asks. A KAS question the chat itself asks (_kiro/userInput) is left to main's elicitation path, which holds it for a person under every approval mode. The workflow surface answers only a step's question, one on a session nobody reads, and one its sink fails on, each "answered" with text built by acp.elicitation's user_input_response, so a dismiss, deny, blank answer or failure never sends a reply KAS reads as yes. With the switch off, only a KAS chat's session/new says workflows.enabled:false. The kas_client_capabilities toggle is gone: main declares userInput on every KAS handshake. A step's command is resolved once, from KAS's _meta.kiro.command and the call's rawInput, for the deny screen, the grant key and every approval mode; a command named in a shape it cannot read, or two that disagree, is held for a person and never matched by a grant. Run and step routes are kept only for runs the mirror holds and go when it evicts them, and a step ask's answer task counts against the runtime's shared answer cap. agent.kas_creator_effort, AcpEvent.answers_only and the chat question-card helpers are gone: nothing in the stack reads them. Every value the router keeps from a KAS frame or a launch is bounded where it is stored: titles, options, plan views, question ids, launch fields and reconnect tokens are capped, and an id or grant input over its cap is refused or gets no grant, never cut. Inspections run only for runs the mirror holds, and the mirror refuses a run id over its cap instead of cutting it. A step's permission request or question is claimed by the router only while the run's chat has an approval-mode reader registered (note_chat_session), read at request time. With none, nothing would ever answer a held request, so the runtime's own fail-closed reply answers it: the permission is rejected and a question gets the no-answer reply. A person's "Always" on a step's tool is sent to KAS as allow-once on every path, so Crew's own step grant is the only "always"; the grant is recorded only when the call has a grant key, and the card says "once" when it has none. A step that offers only an always-allow is refused and stays held, so it can still be rejected. A request that names a command is never taken for a plan handoff. The chat gate (kas_workflows.chat.chat_workflows_enabled) also requires the dashboard to have installed the router's turn starter, read on every call: until the dashboard wiring that answers a run's steps is installed, a switched-on KAS chat is sent workflows.enabled:false and no workflow tools, so the setting changes nothing, as its help text says. A question nobody reads waits for answer capacity like every other answer instead of being dropped. acp/session_provider.py was at the 2,000-line cap, so the provider's KAS-only verbs (the observed turn, the unanswered-prompt rewind and the /context, /knowledge, /code forwarders) live in acp/session_provider_observe.py, bound back onto AcpSessionProvider by name. A step's tool inputs go through the chat turn's own screen before any allow: tool_approval.tool_input_screen (the title and tool-input tiers, moved out of _resolve_permission unchanged so both callers run the same code) over the event build_permission_event makes from the step's request, with the inputs a step's request carries (rawInput, locations, KAS's consent resource). It runs once in _admit, before a request can be granted, auto-approved or held, and a hit or a screen that cannot run is answered with the step's reject. Every decision on a workflow step is made on one tool identity, derived the way a chat turn derives it. KAS sends a step's tool_call frame on its session before the permission request, as on a chat session; the router watches those frames for the sessions it knows are steps and feeds them through the chat path's own parse_session_update into per-step caches under the same admission bound, releasing a settled call's rows at its terminal frame as the session handle does (agent_sdk/kas_step_identity.py, behind the agent SDK boundary, re-exported by kas_workflows/step_identity.py), and the request is built by the chat path's build_permission_event over them. A request with no verified identity is refused. On that event (router_gate.py) admission runs the deny-rule screen, the title and tool-input screen and the tool gate: HookManager.on_tool_call through permission_floor's refusal_for (governance ceiling, auto_deny_tools, every deny tier), the Hooks page's PreToolUse hooks on the call's own arguments and a moved Bot's held rules, under the owning chat's key. A deny or a hook block rejects the step and a held rule keeps it for a person. A plan handoff meets the same screens and is never auto-approved; a request that names a command is never taken for a question. The mode-change sweep and a person's allow judge the kept event again (without firing the hooks twice, as the chat path re-judges a held call on the gate alone), a refusal rejecting the step, and every person's answer is written to the security event log. A held step keeps a bounded snapshot of what the screens read, none for a plan. Under Trust reads a step's git command always waits for a person, as on a chat turn, and the read is the identity event's own command. An "Always" grant binds the key a chat turn's "Always" binds for the same identity (trust_patterns. approval_command: a shell call's command, an argument-free MCP call's server and tool; no one-file grant, which a chat turn binds only after a link check on the path), never the title or KAS's fused tool id, and any other call (or one whose input was redacted) is allowed once and asked again; the card says which. The mode sweep leaves a step a person is answering, before and after it judges it. Only the runtime that drives a step names its calls, and a step's identity is read when its request arrives, in frame order, so a later frame cannot change it. A step note's agent name and node id are redacted, and every plan-tree string a plan approval card shows (node ids and labels, agent, model and effort names, an included recipe's name and path, kept step ids, the plan's kind and omitted note) is redacted before its cap, as asks.py's sink row says. Every string from a step, plan or question that reaches a card or the security event log (a held step's title and option names, the picked option id, a question's prompt, option labels and answer line, every audit row's title and node id) has its control and bidi characters neutralized, is redacted over a bounded window and only then capped. A step's transcript (kas_workflows/transcript.py) shows its tool names, ids, kinds, statuses, titles, agent and model the same way, and its text keeps line breaks but loses control and bidi characters; its streamed chunks are joined raw and redacted once, so a secret split across two chunks is redacted whole. An organization's ask rule on a KAS web call holds a step for a person, as on a chat turn. A step whose call carries no title is refused, as a chat turn refuses it. The mode sweep never restores the card of a request whose session's asks were withdrawn while it waited. After a step is stopped no allow for any of its requests reaches Kiro Agent and each gets exactly one answer, logged (kas_workflows/router_answers.py): every request is claimed when it is read, every answer is checked and consumed under the runtime's stdin write lock in the write's own critical section (AcpRuntime.send_response's withdrawal_check), Stop marks the step before its session/cancel is queued, and a request read after the Stop is answered cancelled at once, as the chat path's answer_late_permission does. Each cancelled answer writes a rejected_on_cancel row first. A held step keeps only what its re-checks read: the identity event without its offered options, and none at all when any of its strings is over its bound, which then refuses rather than allows.
Off by default behind
agent.kas_workflows(Developer › Feature Previews); with it off, behaviour is main's.Problem / Motivation
Goal: When Crew's agent backend is Kiro Agent (KAS), a developer can turn on Kiro Workflows and launch, watch, answer and control KAS workflow runs from the dashboard, with every question or approval a run raises held for a person.
Why it matters
Kiro Agent is the default harness and ships its own workflow engine (recipes, multi-step runs, steps that park for input), but Crew drops the whole
_kiro/workflow/*surface: a KAS chat cannot start a workflow, nobody sees a run's steps, and a step that asks a question stalls with no sign anywhere. A run left to channel auto-answer paths could have a person's answer given on their behalf.Not a goal
agent.kas_workflows); with it off, Crew behaves exactly as main.workflow_run, saved Crew workflows). They keep running.auto_approvedrow in the log; it is followed by the request'srejected_on_cancelrow, and only thecancelledanswer reaches Kiro Agent.cancelled. A re-drive ends only the Stops it was sent over, never one marked while it waited.What changed (motivation → approach → change)
The engine: a run starts from INSIDE its chat's turn on the chat's own KAS process, so the chat is its visible parent; every KAS runtime routes its workflow frames into the one run mirror.
kas_workflows/router.py, with its types and helpers inrouter_base.pyand three method groups it binds by name (router_reads.py,router_controls.py,router_recovery.py), so no file passes the 2,000-line cap; every redaction stays inrouter.py_meta.kiro.commandand the call'srawInput) for the deny-rule screen, grants and every approval mode; one it cannot read is held for a person and never matched by a grantkas_workflows/asks.py,kas_workflows/policy.pykas_workflows/transcript.pypy/path-injection)kas_workflows/chat.py,kas_workflows/project_root.py_kiro/userInputquestion stays on main's elicitation path; a step's question, one on a session nobody reads, and one the sink fails on are answeredansweredwith text, never a reply KAS reads as yes.AcpEvent.answers_onlyrides the provider copyacp/workflow_sink.py,acp/session_handle_*,acp/_dispatch_parts/permission_requests.py,acp/runtime_*,acp/types.py,agent_sdk/kas_workflows_driver.py,providers/acp_turns.pymessaging/workflow_markers.pyacpspawn extracts it)scripts/capture_kas_workflow.pyRouter, asks and transcript redact what they hand to a chat, a bell note, the security event log or a card, and are registered as redaction sinks (below). All of it is inert unless the switch is on and the backend is Kiro Agent.
Stack
Split out of #25395, which was over the 1 MB review cap. Merge bottom-up. Only a PR based on
maingets CI (ci.ymlandfast-gate.ymlrun onpull_request: branches: [main]), so each stacked PR is rebased ontomainonce the one below it merges. A and the B1a protocol PR do not depend on each other. C2's UI uses A's card, so C2 carries A's commit until A merges.feat/kas-wf-1-session-cardsmainfeat/kas-wf-2-backendmainfeat/kas-wf-2b-enginemainfeat/kas-wf-2c-dashboardfeat/kas-wf-2b-enginefeat/kas-wf-3-person-holdsfeat/kas-wf-2c-dashboardfeat/kas-wf-4-frontendfeat/kas-wf-3-person-holdsfeat/kas-wf-4b-frontend-uifeat/kas-wf-4-frontendBackwards compatibility
Compatible: with the switch off (the default) no chat session gets the workflow surface, and every chat's
_kiro/userInputquestion takes main's elicitation path unchanged. An ordinary Kiro Agent chat'ssession/newandsession/loadare main's frames byte for byte (pinned against main's unchanged golden,test/fixtures/acp_harness_wire/kas.json). The only exception is thesession/loadof a session Crew itself last started or loaded with workflows on (recorded in memory,kas_workflows/chat.pynote_workflow_session). That load carries_meta.kiro.settings.workflows.enabled:false, because KAS resolvesenabled ?? persisted ?? falseon a load and would otherwise keep the surface. The key rides in_meta.kiro.settings, the same object Crew already sends KAS's memory setting in on every load. ACP's extensibility page says custom data in_metais added "without breaking peers that don't know about it", though it states no explicit must-ignore rule. The oldest Kiro Agent the repo states a floor for is kiro-cli 2.33.1 / KAS 0.66.58 (KAS_AGENT_PROMPT_MIN_KIRO_CLI,src/kiro_crew/acp/harness/kas.py:139); no frame carrying the key has been captured on that release. After a gateway restart Crew knows no such session and sends nothing, as main does.Removes nothing: only additions.
Tests
test_kas_workflows_router.py,_round4.py,_parity.py,_transcript.py,_runtime_sink.py,_step_user_input.py,_chat_user_input.py(a chat's question takes main's elicitation path with the switch off and on; every reply the surface sends isansweredwith text),_off_switch_wire.py(with the switch off, a chat'ssession/newand a never-workflowssession/loadequal main's golden; only the load of a session last driven with workflows on carriesworkflows.enabled:false, once); each fails when its fix is reverted,_policy.py,_project_root.py(each refusal fails without the confinement),test_acp_observe_turn.py,test_session_handle_bindings.py,test_harness_parity.py.Local gates on this head as for every Python PR in the stack;
test_security_posture.pypasses with the new rows.The router split (second commit):
scripts/check_file_line_cap.pyfails on the first commit (router.py2,829 lines) and passes on the second;test_facade_bindings.pynow pins that each methodKasWorkflowRouterbinds from an owner module reads as its own. An AST comparison finds every moved statement identical to the first commit's, docstring indentation aside, except one line inschedule_reattachthat unpacks the binding before the closure so mypy can type it.test_kas_workflows_policy.pyandtest_kas_workflows_router.py(the command resolver, native and unreadable shapes),_router_bounds.py(routes after eviction, the shared answer cap),_recovery.py,_chat.py,_driver.py,test_kas_workflow_markers.py; each fix's test fails when that fix is reverted.Determinism: the new and changed test files (166 tests) pass 20 of 20 runs at
-n0, 10 of 10 at-n 4, and 3 of 3 runs in a shuffled order; their waits take their bound fromkiro_crew.testing.wait, sotest_flake_pattern_ratchet.pypasses.Proof: not provable -- other: feature PR, not a fix; each behaviour has its own test named above.
Manual verification
N/A — the dashboard routes that drive this arrive in the next PR; unit and fixture coverage only here.
Screenshots / video
N/A — this PR changes no website file, so it has no rendered surface.
Sensitive change
This PR adds rows to
src/kiro_crew/security_posture_sinks_gateway.py(SCR-watched): three rows, forkas_workflows/router.py,kas_workflows/asks.pyandkas_workflows/transcript.py. Nothing elseunder the Sensitive Change Review globs changes. The router split leaves the three rows as they were: every redactor call the router makes is still in
router.py, androuter_base.py,router_reads.py,router_controls.pyandrouter_recovery.pycall none, so they need no row. Draft for the owner to post as the review comment:Sensitive change review
Head: 31930a7
kas_workflows/router.py,kas_workflows/asks.pyandkas_workflows/transcript.py; no redactor, scanner or allowlist changes.redact_via_contextbut sit in no registry, so the omission ratchet fails; after, each is a named sink with its real egress (chat markers, bell, SEL, approval and question cards, step transcript) and the panel counts it.Related Issues
N/A — no tracking issue, by the owner's choice.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)