Skip to content

feat(workflows): Kiro Agent workflow protocol, run mirror and opt-in - #25447

Merged
bolichen97 merged 2 commits into
mainfrom
feat/kas-wf-2-backend
Nov 5, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
feat/kas-wf-2-backend

Conversation

@kyleseaman

@kyleseaman kyleseaman commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

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

  • Turning Kiro Workflows on by default. It stays a developer opt-in (agent.kas_workflows); with it off, Crew behaves exactly as main.
  • Replacing Crew's own workflows (workflow_run, saved Crew workflows). They keep running.
  • Workflows on other harnesses. KAS is the only engine that has them.
  • The session-message cards: they are their own PR (A in the stack).

What changed (motivation → approach → change)

The first slice: the protocol model and the switch, with nothing reading the switch yet.

Piece Where
_kiro/workflow/* method and notification names, tolerant parsers, run-row control rules, NODE_PATH_SEP kas_workflows/wire.py
The reducer that folds lifecycle frames and list / load answers into run rows; every KAS input is bounded on the way in (strings cut to 1000 characters, lists and whole payloads capped), a run holds at most 2000 node ids and paths, the mirror at most 500 live runs, and each input that loses anything to a cap logs one line and adds to a running count kas_workflows/mirror.py
Which engine a chat's workflows use, and the single gate (Kiro Agent AND the switch) kas_workflows/engine.py
native_workflows capability, ACP_BACKENDS_NATIVE_WORKFLOWS (KAS only), its backend card agent_sdk/backends_routing.py, capabilities.py, backend_cards.py
KAS turn-boundary and user-input wire names, read first by the engine PR above (#25449) acp/kas_wire.py
The opt-in agent.kas_workflows (default off), set only in config.json: no dashboard control and no reader on this head config/sections_agent.py, config/loader_builders.py, config-baseline.json
kas_wire.py dropped from the black baseline (it is now black-clean) .github/black-baseline.txt
Live capture behind the capability set, registered in X_FEATURE_SETS test/fixtures/acp_frames/kas/workflow-run-live.jsonl, scripts/check_harness_parity.py

Stack

Split out of #25395, which was over the 1 MB review cap. Merge bottom-up. Only a PR based on main gets CI (ci.yml and fast-gate.yml run on pull_request: branches: [main]), so each stacked PR is rebased onto main once 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.

# PR Branch Base
1 #25470 feat/kas-wf-1-session-cards main
2 #25447 (this PR) feat/kas-wf-2-backend main
3 #25449 feat/kas-wf-2b-engine feat/kas-wf-2-backend
4 #25450 feat/kas-wf-2c-dashboard feat/kas-wf-2b-engine
5 #25459 feat/kas-wf-3-person-holds feat/kas-wf-2c-dashboard
6 #25466 feat/kas-wf-4-frontend feat/kas-wf-3-person-holds
7 #25471 feat/kas-wf-4b-frontend-ui feat/kas-wf-4-frontend

Backwards compatibility

Compatible: the new switch defaults to off and nothing reads it in this PR; the capability set adds a field.

Removes nothing: only additions.

Tests

  • test_kas_workflows_mirror.py: the five bound tests (test_every_kept_kas_text_is_cut_to_the_reason_cap, test_per_id_maps_stop_taking_new_node_ids_at_the_cap, test_ids_sessions_models_and_list_rows_are_cut_like_any_kas_text, test_wide_lists_and_plans_are_capped_as_a_whole, test_live_runs_past_the_cap_are_not_recorded_and_each_lossy_input_logs_once) fail on the first commit and pass on the second.
  • test_kas_workflows_wire.py, test_kas_workflows_mirror.py, test_agent_sdk_capabilities.py, test_editable_config_enum_parity.py.
  • test_kas_workflows_engine.py: the engine choice and the single gate (KAS AND the opt-in, off on any doubt).
  • test_kas_workflows_live_capture.py folds the live capture (KAS 0.66.70, kiro-cli 2.37.1, at the fixture floor) through the mirror, and checks the recipes_changed push KAS 0.66 sends.
  • Local gates on this head: black/isort/flake8/mypy, semgrep, comment-history, feature-map, portability, check_harness_parity.py (tree and base), check_acp_frame_host_data.py, config baseline, pytest over the KAS and contract tests.

Proof: not provable -- other: feature PR, not a fix; each behaviour has its own test named above.

Manual verification

N/A — no runtime path reads this code yet; the live capture is the end-to-end evidence.

Screenshots / video

N/A — this PR changes no website file, so it has no rendered surface.

Related Issues

N/A — no tracking issue, by the owner's choice.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|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

@kyleseaman
kyleseaman requested review from a team and KiroCrewCaptain as code owners October 28, 2026 21:39
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 28, 2026
@github-actions

github-actions Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 752a066d7e4508ce2a77677a47b9f810c1135681 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 752a066d7e4508ce2a77677a47b9f810c1135681 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the change only adds code, the switch defaults to off, and nothing reads the new protocol, mirror or capability until #25449 lands.

Notes

[DESIGN-REVIEWED] 752a066

Description read

[DESCRIPTION-READ] b1078592daaa482a577b264b9db142a0d28556076354538ea54776364898e6dc

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 752a066d7e4508ce2a77677a47b9f810c1135681 — 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 does not.

First-Principles-Verdict: PASS

This PR is one layer of a stack. It adds opt-in surface, off by default, that nothing on this head reads yet. All of it can be removed later, because unknown config keys round-trip (config/resolution.py:207).

Notes

  • Item 5 — inherited: the engine.py docstrings describe callers that don't exist. One says "the settings UI reads it", but the description says "no dashboard control". Another says it "replaced the old per-device preview flag and the separate chat-workflows toggle", and neither of those exists on main. Subtraction: delete those two sentences from backend_brings_kas_workflows and kas_workflows_enabled.
  • Items 6–7 — zero consumers: grepping src/ finds 0 callers outside kas_wire.py for turn_boundary(, KIND_TURN_START, METHOD_USER_INPUT and CAPABILITY_USER_INPUT. Subtraction: move these to feat(workflows): Kiro Agent workflow engine router and runtime hooks #25449 (turn boundary) and the person-holds PR (userInput), where they first get read.
  • Item 1 — zero consumers: grepping src/ finds 0 readers of agent.kas_workflows outside kas_workflows/engine.py, and kas_workflows_enabled itself has 0 callers. Subtraction: move the key to feat(workflows): Kiro Agent workflow engine router and runtime hooks #25449, the PR that reads it.

What this change ships

Inventory (9 items) — 5 justified

Intent: let a developer on Kiro Agent opt in to driving and watching KAS's own workflow runs from Crew — ADDITION (first slice).

  1. New config key agent.kas_workflows, off by default, read by nothing yet — zero consumers
  2. KAS gets a native_workflows capability and a backend-card line — justified
  3. _kiro/workflow/* method names, parsers and run-row control rules — justified
  4. A reducer that turns KAS run frames into capped in-memory run rows — justified
  5. The engine choice and the single gate (KAS AND opt-in) — inherited: docstrings name callers that don't exist
  6. Turn-start/turn-end wire names and the turn_boundary() parser — zero consumers
  7. _kiro/userInput wire names — zero consumers
  8. STEERING_KINDS reformatted; kas_wire.py dropped from the black baseline — rides along
  9. A live KAS capture fixture, registered in the parity script — justified

[FIRST-PRINCIPLES-REVIEWED] 752a066

Description read

[DESCRIPTION-READ] 71c80c4bb0de3678e892dc29f57faa38870c7779989c9618f8c336e9d1c3db99

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 752a066d7e4508ce2a77677a47b9f810c1135681 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 752a066

Verdict parsed from the review's SHA-scoped output markers for commit 752a066d7e4508ce2a77677a47b9f810c1135681.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 752a066d7e4508ce2a77677a47b9f810c1135681 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 752a066d7e4508ce2a77677a47b9f810c1135681 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 752a066

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 752a066d7e4508ce2a77677a47b9f810c1135681 false-positive: <reason, 20 to 500 characters>

@kyleseaman

Copy link
Copy Markdown
Contributor Author

self-added: no
resolution: removed

  • Two editable config keys with no reader — zero consumers span=61fc07a11d25

fixed in b8172e4: agent.kas_creator_effort is gone from this PR (field, KAS_CREATOR_EFFORT_LEVELS, loader branch, schema entry, baseline rows, enum-parity row), and agent.kas_workflows is no longer in _EDITABLE_CONFIG.
agent.kas_workflows stays as a config field only because the justified engine gate reads it; its help text now says no surface reads it on this head.
Both editable entries and creator effort move to the stacked PR whose kas_workflows/chat.py first reads them (#25449).

@kyleseaman

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: _text() cuts every kept KAS string to MAX_REASON_CHARS; _admit_node() caps per-id maps at MAX_PATHS_PER_RUN distinct ids

  • mirror.py:821 count cap does not bound retained KAS text span=4c1a7655b187

fixed in b8172e4: every KAS free text the mirror keeps (failureReason, node_paused reason, pauseReason, workflowName/name/runLabel, retry-wait and plan-update reasons) goes through _text, cut to MAX_REASON_CHARS, in node_reason and path_state alike.
Bare-id maps now admit a new node id only while the run holds fewer than MAX_PATHS_PER_RUN ids (_admit_node); a held id keeps updating. They are capped by distinct ids, not tied to the path cap, because a loop body keeps its latest instance under one id and freezing it at the 2000th instance would show a stale step.
Tests: test_every_kept_kas_text_is_cut_to_the_reason_cap and test_per_id_maps_stop_taking_new_node_ids_at_the_cap fail on the first commit, pass on the fix.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

self-added: no
resolution: removed

  • sections_agent.py:1051 setting promises effects no code carries out span=a1d96c0c714d

fixed in b8172e4: agent.kas_workflows and agent.kas_creator_effort are out of _EDITABLE_CONFIG, creator effort is removed entirely, and the kas_workflows help text (also in config-baseline.json) now says only that it is an off-by-default developer opt-in no surface reads on this head.
The stale comment citations in kas_wire.py and backends_routing.py (kas_workflows.asks, acp.types.kas_client_capabilities, scripts/capture_kas_workflow.py, the workflows.kas_native preview) are rewritten to what this head holds.

@kyleseaman
kyleseaman force-pushed the feat/kas-wf-2-backend branch from b8172e4 to 34493fd Compare October 29, 2026 00:33
@kyleseaman

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: bound every KAS input at the mirror door (_bounded for raw payloads, _bounded_record for list rows) instead of per stored field

  • mirror.py:837 count caps leave per-entry strings and lists unbounded span=4c1a7655b187

fixed in 34493fd: every notification and load answer is copied through _bounded before any handler reads it, and every list row through _bounded_record, so ids, path segments, sessions, models, efforts, timestamps and reasons are all cut to MAX_REASON_CHARS, each list and mapping keeps MAX_LIST_ITEMS, and one payload brings at most MAX_PAYLOAD_VALUES (attention, plan width, queued steps).
Paths deeper than a plan can be are refused, live runs are capped at MAX_LIVE_RUNS, an over-wide scope list is not remembered, and every cut or refusal is counted on RunMirror.dropped with the first one logged.
Tests: three new bound tests (ids/list rows, wide lists and plans, live-run cap with one log line) fail on the first commit and pass on the fix.

@kyleseaman
kyleseaman force-pushed the feat/kas-wf-2-backend branch from 34493fd to b831385 Compare October 29, 2026 00:58
@kyleseaman

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: per-input drop tally (Budget) reported by each apply* call

  • mirror.py:471 cap overflow logged once per mirror lifetime span=4c1a7655b187

fixed in b831385: each apply_* call now tallies its own cuts and refusals (string cuts, list and payload caps, refused node ids and paths, a live run refused at MAX_LIVE_RUNS, an over-wide scope list) on one _Budget and _report_dropped logs one warning per input that lost anything, with that input's count and the running total on RunMirror.dropped.
The test now pins one log line per lossy input (seven inputs, eight dropped values, seven lines).

@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 Oct 29, 2026
@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Nov 3, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requesting changes: the new live capture is below the fixture floor.

Backend Tests (3.12, 6) (and the Windows shard 6) fail with 1 failure, 32880 passed:

FAILED test/test_real_adapter_fixture_pins.py::test_every_live_kiro_and_kas_fixture_is_at_its_floor - AssertionError: kas/workflow-run-live.jsonl:agent_version is 0.58.7, below floor 0.66.33: re-capture it

This PR adds test/fixtures/acp_frames/kas/workflow-run-live.jsonl, captured off KAS 0.58.7, while the live floor for kas fixtures is 0.66.33. Please re-capture it on a build at or above the floor (and update workflow-run-live.expected.json and the README row to match). Coverage Gate fails closed from the backend lane and should clear with that.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 5, 2026
@kyleseaman
kyleseaman force-pushed the feat/kas-wf-2-backend branch from b4874fb to 1b0bd51 Compare November 5, 2026 16:25
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 5, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, re-checked at 1b0bd51. My earlier point is fixed: Backend Tests (3.12, 6) and the Windows shard pass, so the live capture now meets the fixture floor.

What I checked on this head:

  • The opt-in really defaults off: agent.kas_workflows is default=False. kas_workflows_enabled needs both a Kiro Agent backend and the setting, and is "off on any doubt".
  • No regex in product code.
  • No new refusals.
  • .github/black-baseline.txt only shrinks (kas_wire.py is now formatted).

One blocking point, Coverage Gate:

1 file(s) below 80% and not baselined — add tests, do not extend the baseline:
     66.7%  kas_workflows/engine.py  (10/15)

engine.py is small, so a few unit tests cover it:

  • engine_for returns ENGINE_KAS for a backend whose capabilities have native_workflows and ENGINE_CREW otherwise;
  • kas_workflows_enabled is False with no agent section, False for a non-KAS backend with the setting on, False for KAS with the setting off, and True only for KAS with it on.

I'll approve once Coverage Gate is green.

@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 Nov 5, 2026
@kyleseaman
kyleseaman force-pushed the feat/kas-wf-2-backend branch from 1b0bd51 to 0e76028 Compare November 5, 2026 17:49
@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 Nov 5, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, re-checked at 0e76028. The coverage point is addressed: test/test_kas_workflows_engine.py now covers engine_for and every case of kas_workflows_enabled. Coverage Gate is still running, and I'll confirm engine.py once it reports.

One new blocking point, from the GPT 6.1 lane (upheld on adjudication), kas_workflows/mirror.py:466: loads skip the mirror's own run limits. A completed load or inspect goes through apply_load() → _fold_load() with no eviction, so 210 distinct responses keep 210 terminal rows. With 500 live rows held, loading another completed run and then applying its run_start passes _ensure(), because the row already exists, and promotes it to running. Both retention limits the mirror already declares are bypassed, the run store grows from harness input without bound, and dropped stays 0.

Please:

  • evict terminal overflow after a load, as the event path does;
  • apply the existing live-row limit before a terminal row moves back to running, and count it in dropped;
  • add a test that loads past the terminal cap and restarts past the live cap.

Happy to approve once that and Coverage Gate are green.

@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 Nov 5, 2026
Kyle Seaman added 2 commits November 5, 2026 18:52
The first slice of Kiro Workflows on Kiro Agent (KAS): the
_kiro/workflow/* method and notification names with tolerant parsers
(kas_workflows/wire.py), the run mirror that folds lifecycle frames and
list/load answers into run rows (kas_workflows/mirror.py), the
native_workflows backend capability (ACP_BACKENDS_NATIVE_WORKFLOWS, KAS
only), and the developer opt-in agent.kas_workflows (off by default).

The capability set is backed by a live KAS capture
(test/fixtures/acp_frames/kas/workflow-run-live.jsonl) that
test_kas_workflows_live_capture.py folds through the mirror, and is
registered in check_harness_parity.py's X_FEATURE_SETS. Nothing reads the
opt-in yet; with it off, behaviour matches main.
@kyleseaman
kyleseaman force-pushed the feat/kas-wf-2-backend branch from 0e76028 to 752a066 Compare November 5, 2026 18:53
@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 Nov 5, 2026
@kyleseaman

kyleseaman commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: run-count caps enforced at every admission and promotion, not only on row creation

  • Loads and restarts bypass run-count limits span=4ebced12a169

fixed in 752a066: _fold_load now evicts terminal overflow like the list and notification paths, so loaded finished runs stay within MAX_TERMINAL_RUNS.
_fold_notification refuses any notification for a finished run while the mirror holds MAX_LIVE_RUNS live runs (counted on dropped, logged per input), so neither a restart run_start nor a parked run_complete can revive it past the cap. _apply_summary / _apply_state already cannot revive a finished run (_stale_live).
Tests: test_loads_of_finished_runs_are_held_to_the_terminal_cap and test_a_finished_run_cannot_come_back_live_past_the_live_cap fail before the fix and pass on it.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 5, 2026
@kyleseaman

Copy link
Copy Markdown
Contributor Author

@bolichen97 re your review of Nov 4 at b4874fb (fixture floor): re-captured, now on head 752a066.

  • test/fixtures/acp_frames/kas/workflow-run-live.jsonl is a new live capture off KAS 0.66.70 (kiro-cli 2.37.1), above the 0.66.33 / 2.27.0 floors. test_every_live_kiro_and_kas_fixture_is_at_its_floor passes, and Backend Tests (3.12, 6) and the Windows shard 6 are green.
  • workflow-run-live.expected.json was regenerated with scripts/update_acp_frame_snapshots.py (all 109 snapshots match).
  • The kas/ row in test/fixtures/acp_frames/README.md now reads "off KAS 0.66.70 (kiro-cli 2.37.1)", and also names the recipes_changed push 0.66 sends, which test_kas_workflows_live_capture.py now checks.
  • check_acp_frame_host_data.py passes on the new file.

Your later points on the same head are in too: test/test_kas_workflows_engine.py brings engine.py to 100% (Coverage Gate green), and the GPT finding on mirror.py (loads skipping terminal eviction, a restart reviving a finished run past the live cap) is fixed with two tests. All checks pass on 752a066.

@kyleseaman
kyleseaman requested a review from bolichen97 November 5, 2026 20:10

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-checked at 752a066. Every point from my reviews is fixed:

  • the shard-6 fixture floor;
  • engine.py coverage, now pinned by test_kas_workflows_engine.py (Coverage Gate passes);
  • the run-cap finding: loads evict down to the terminal cap, and a finished run can't come back live past the live cap, counted in dropped, with a test for each.

The opt-in stays off by default, there is no regex in product code and no new refusal. After a rerun for the installation rate limit, Opus 5.5, GPT 6.1, Design, First Principles and UX all pass, and all 97 checks are green. Approving.

@bolichen97
bolichen97 merged commit ccf5db7 into main Nov 5, 2026
99 of 101 checks passed
@bolichen97
bolichen97 deleted the feat/kas-wf-2-backend branch November 5, 2026 21:51
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 5, 2026
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