Skip to content

refactor(dashboard): move chat runner helpers into chat_turn owners - #20755

Merged
chenmingwei23 merged 1 commit into
mainfrom
refactor/linecap-g01-chat-runner-p3
Oct 15, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
refactor/linecap-g01-chat-runner-p3

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Move the dashboard chat runner's top-level helpers into chat_turn/ owners by responsibility, so chat_runner.py sheds about 2,500 lines with no change to what a turn does.

src/kiro_crew/dashboard/chat_runner.py is about 20,900 lines; the campaign rule is that no hand-written file goes over 2,000 lines. About 3,300 of those lines are module-level helpers _run_chat calls (deny rows, tool rows, native sub-agent cards, crew-log attribution, spec-hook notices, file-change snapshots, the stats footer, recovery cards), each already the responsibility of a chat_turn/ owner or of a new one. The previous PR made compose discover owners and bind their names on the runner, so a helper can now move without a re-export per name.

Why it matters

Every dashboard, Slack and channel turn runs through these helpers. Each one that stays in the runner keeps the file far over the cap and keeps unrelated work in one review surface. Moving them as whole definitions, with every guard that reads them by path pointed at their new homes, shrinks the runner while every patch of chat_runner.<name> keeps reaching the moved code.

Not a goal

  • No change to what a turn does: helpers move verbatim, and their callers stay where they are.
  • Nothing is cut out of _run_chat itself; its phases move in the next PRs of the series.
  • The helpers below _RECIPIENT_LOGGED (the account-identity gate, the cross-surface legs, the decisions hooks and the Jev routing) stay for the next PR: moving them in the same diff makes git's default diff show kept code as rewritten.

What changed (motivation → approach → change)

Eighty-two top-level units (2,414 lines) move, whole, into twelve owners, five of them new; each owner owns one responsibility, recorded in the composition section of learn-cron-dashboard.md. compose binds every moved name on the runner, so chat_runner.<name> still resolves and a test's patch of it still reaches the moved code; names a production module imports from the runner (turn_stats_meta, refusal_card_text, unavailable_agent_message and others) keep a by-name import there. The runner is exempt from F401 because pyflakes reads only its own text, and test_chat_runner_compose_binding.py checks every runner import is read in the runner or an owner.

Owner New What moved in
tool_rows yes tool-row meta, the WS payload, the refinement rewrite, the tool-call identity key, the rows-only save
deny_chokepoints yes redacted deny rows, the audit before the wire (_reject_attributed), the bounded in-band steer
turn_spec_hooks yes the session agent spec's hooks and the welcome, run-nowhere and withheld-hooks notices
crew_log_attribution yes the predecessor store, served model, lineage, seeded tree, inherited parent, workspace and class
native_cards yes native sub-agent Activity cards and the native AskUserQuestion card
turn_context, turn_stats, recovery, acp_recovery, model_fallback, file_changes, mcp_session no the helpers of each one's responsibility (stats footer and turn metric, refusal and compaction cards, the canary's settings, the pinned-model verdict, the snapshot flush, the MCP OAuth banner)

Repository guards that read a moved construct by path read its new home: the composition contract's homes map and owner set, security_posture's non-egress registry for the owners that now hold redactor calls and the gate-side log census, the transcript seam's publication fence, the bounded-steer spelling check, the config-dir guard's file list, the redact-before-bound scan (it reads the chat_turn package whole, with a floor of 7 redacting owners) and the two backend-identity ratchets (they read the runner's owners as part of the runner). The composition contract records each moved name's kind and signature from the base runner, and the import-read check covers imports inside the runner's functions. Docs that named a moved helper's home name its owner, and each extended owner's docstring names what it holds.

Backwards compatibility

Compatible: every name chat_runner bound at the base is still bound, as the same object (the base-names contract test); every patch target still reaches the code it reached.

Reader: src/kiro_crew/slack/gateway.py:turn_stats_meta -- cron -- from kiro_crew.dashboard.chat_runner import turn_stats_meta resolves through the runner's re-export of chat_turn/turn_stats.py (test_cron_turn_stats_footer.py)
Reader: src/kiro_crew/dashboard/chat_runner.py:refusal_card_text -- chat -- the runner imports it from chat_turn/recovery.py and _run_chat calls it there (test_acp_structured_refusal.py)
Reader: src/kiro_crew/dashboard/chat_runner.py:unavailable_agent_message -- chat -- the runner imports it from chat_turn/turn_context.py (test_chat_runner_composition_contract.py::test_every_name_the_runner_bound_at_the_base_still_resolves)

Tests

  • Every guard that reads a construct by path has a mutation of that construct, in the file that holds it after the move, that turns it red: 84 mutants, every one killed. That is PR2's 73, re-aimed at each construct's new home, plus 6 for this PR's registry edits (the bounded-steer spelling, the rows-only save's fence, the census row, the non-egress row, a guarded construct's new home, and the config-dir guard reading a new owner) and 5 for the guards this PR widens (a slice inside a redactor call in an owner, a backend literal and a backend-identity read in an owner, a moved name's changed signature, an unread import inside a runner function).
  • 309 test files that import, patch or read chat_runner or chat_turn, plus the flake, wait, line-cap, base-names, security-posture and path-inventory guards: 19,081 passed (-n 3 --dist loadgroup); 5 more hit the 120 s test timeout under a host load average near 50, and all 12 tests of those 5 groups pass when run on their own.
  • Line coverage of every owner over that run: 91% to 100% (crew_log_attribution 91%, deny_chokepoints 94%, native_cards 99%, tool_rows 94%, turn_spec_hooks 94%; the extended owners 92% to 100%).
  • L41: each owner with a coroutine spells its stdlib modules as plain imports; planting time.sleep(1) in each one's first coroutine is reported by the sync-io gate's own scanner (13 of 13).
  • mypy over src/kiro_crew: clean. semgrep 1.78 (CI configs, baseline at the base): 0 findings after one nosemgrep on a moved warning that logs only the server's name; 0 parse errors. black, isort, flake8, comment-history, brand, docs-lint, agent-sdk, subprocess-encoding and sync-io gates: clean.

Move audit: chat_runner.py 20,966 → 18,473 lines, 224 units, 100% moved, 0 changed. L36: every file's default and --minimal diffs add the same lines. Line cap: 0 failures; chat_runner.py 20,966 → 18,473, and its row in .github/file-line-cap-baseline.txt is lowered to 18,473 by hand.

Manual verification

N/A — a structural move; the turn-level characterization suite and the mutation-proven guards are the verification.

Related Issues

Part of #20192

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

Move audit

src/kiro_crew/dashboard/chat_runner.py: 20966 -> 18473 lines; moved 100.0% (python-ast)

Edits to moved lines, each a gate's requirement: two moved comments restated in present tense (comment history), one # nosemgrep with its reason (the moved warning is new to semgrep because its file is), and # noqa: F811 on two function-local imports in _run_chat whose module-level twins stay for the owners.

Follow-ups

Comments outside this PR's claim that still place a moved helper in chat_runner.py. The dotted names resolve through the runner, so none of them is a behaviour defect:

  • website/src/pages/chat/ToolCallLine.tsx (two comments), website/src/pages/chat/toolDiff.ts, website/src/test/ToolCallLine.test.tsx: _tool_meta is in chat_turn/tool_rows.py.
  • src/kiro_crew/acp/session_handle.py: _native_subagent_sync is in chat_turn/native_cards.py; src/kiro_crew/acp/client.py: _pinned_model_verdict is in chat_turn/model_fallback.py.
  • src/kiro_crew/dashboard/state.py, dashboard/session_control.py, dashboard/handlers/usage.py, dashboard/cron_inject.py, deny_notice.py, security/denied_rules.py, security_posture.py (the deny_notice.py row's comment), messaging/dispatch.py, and the auto_research and spec_builder backends.

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners October 15, 2026 08:46
@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 9861992
  • What rule changed: none. security_posture.NON_EGRESS_REDACTION_MODULES lists the seven dashboard/chat_turn/ owners that now hold redactor calls moved out of dashboard/chat_runner.py, and test_security_posture.py's gate-side log census moves one site from the runner (9 to 8) to chat_turn/native_cards.py (1).
  • Before -> after (what was allowed/blocked, now): the same redactor calls, with the same arguments, run on the same text and reach the same surfaces; only the module that holds each call changed, and the registry names that module.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): a redactor site counted under the wrong module, so the posture panel's site count is off; no redaction, command or gate changes, since every moved definition is byte-identical (move audit: 100% moved, 0 changed).
  • Evidence checked (which sandbox result proves it): no sandbox path changes; the move audit, the omission and census tests in test_security_posture.py, and mutants that drop the non-egress row or the census row and turn those tests red.
  • No regression:
    • Tools still work (which tools/commands were run, result): the dashboard turn suites (test_chat_runner_turn_*.py, 94 tests that run whole turns) and every test that imports, patches or reads the runner pass on this head.
    • Backward compatible (old config / old data / old callers still work, how checked): every name chat_runner bound at the base is still bound as the same object (test_campaign_facades_base_public_names.py, the composition contract's base-surface rows), so callers and patches of chat_runner.<name> are unchanged.
    • Existing tests (which suites passed on this head): test_security_posture.py, test_core_path_redact_before_bound.py and the 309 files that touch the runner or its owners (19,081 passed; 5 load timeouts that pass on their own).
  • How to undo: revert this one commit; no data or config changes.

@bolichen97
bolichen97 enabled auto-merge (squash) October 15, 2026 09:05
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/security_posture.py

  • @bolichen97 posted a complete reasoning template for ba655d1.

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision ba655d158b2e4d655bfef417dca01379a1580574 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 15, 2026
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] ba655d1

Description read

[DESCRIPTION-READ] 8d5ddf702cdafc253dafab1fb7fefa20874ec34ba2cefd5b7b6a938e3bf69b94

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 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

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

The file-wide F401 exemption on the 18k-line chat_runner.py now relies only on test_chat_runner_compose_binding.py to catch an unread import.

What this change ships

Inventory (7 items) — 7 justified

Intent: shrink chat_runner.py toward the 2,000-line cap by moving its top-level helpers, unchanged, into chat_turn/ owners. This is a refactor, not a FIX or an ADDITION.

  1. Eighty-two helpers move unchanged from chat_runner.py into twelve chat_turn/ owners, five of them new. Users see no change. — justified
  2. chat_runner still exposes every name it had before, so imports and patches of chat_runner.<name> still work. — justified
  3. chat_runner.py is exempt from flake8's unused-import check (F401) in setup.cfg. The Slack gateway facade already has the same exemption. — justified
  4. The import-read test now also checks imports inside the runner's own functions. — justified
  5. Guards that find code by file path now point at the helpers' new homes: the redact, steer, config-dir and identity ratchets, the security-posture registry and the transcript seam. — justified
  6. The line-cap baseline row for chat_runner.py drops to 18,473. — justified
  7. Docs and the agent-SDK boundary RFC now name each moved helper's new owner. The RFC's status is not edited. — justified

[FIRST-PRINCIPLES-REVIEWED] ba655d1

Description read

[DESCRIPTION-READ] 1fe5b3b70be695d7c29ec6f37b4067ce4e1853691f92a52f44a3ed9ed2206408

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 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] ba655d1

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

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

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ba655d1

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

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Design punchline: the re-pointed security guards still cover every owner that holds redactor calls -- already covered

test_security_posture.py::test_every_redactor_call_site_is_a_registered_sink_or_allowlisted scans every module under src/kiro_crew, every chat_turn owner included, and fails on any redactor caller missing from _REDACTION_SINKS and NON_EGRESS_REDACTION_MODULES. Dropping one owner's row turns it red (mutant PR3-non-egress-row).
The redact-before-bound scan lists src/kiro_crew/dashboard/chat_turn as a package scanned whole, so a new owner is scanned with no edit. Its floor of 7 is the number of owners that call a redactor today. A slice planted inside a redactor call in native_cards turns it red (mutant PR3R-slice-inside-redact-in-an-owner).

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • First Principles punchline: compose_binding fails on a dead runner import now that F401 is off for chat_runner.py -- already covered

test_chat_runner_compose_binding.py::test_every_name_the_runner_imports_is_read fails on any module-level import that nothing in the runner or an owner reads. Planting import colorsys at the top of the runner turns it red (mutant R7-a-dead-runner-import).
The same test checks imports inside the runner's functions (_unread_local_imports, which the per-file F401 exemption also silences). A dead import colorsys inside a function turns it red (mutant PR3R-a-dead-function-local-import). Both helpers have self-tests on synthetic source.

@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 Oct 15, 2026
Move 82 top-level helpers of chat_runner.py, whole, into the chat_turn
owner of each one's responsibility: five new owners (tool_rows,
deny_chokepoints, turn_spec_hooks, crew_log_attribution, native_cards)
and seven existing ones. compose binds every moved name on the runner,
so chat_runner.<name> still resolves and a patch of it still reaches
the moved code; names production imports from the runner keep a
by-name import there.

Guards that read a moved construct by path read its new home: the
composition contract's owner set, homes map and the base kind and
signature of every moved name, the security posture non-egress
registry and log census, the transcript seam's fence, the
bounded-steer spelling check, the config-dir guard's file list, the
redact-before-bound scan and the two backend-identity ratchets.
The runner is exempt from F401 because pyflakes reads only its own
text; test_chat_runner_compose_binding.py checks every import, module
level or inside a function, is read.

Part of #20192
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 15, 2026
@bolichen97
bolichen97 force-pushed the refactor/linecap-g01-chat-runner-p3 branch from 9861992 to ba655d1 Compare October 15, 2026 13:48
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased onto main e660192 (Master refresh; #20764 changed _run_chat). The recipe re-applied on the new main gives the same added and removed lines in every file as 9861992, except the line-cap row (18,473, the runner's size now).

Upstream changes carried: #20764's empty-response ladder edit (if _empty_activity.productive or slot._empty_episode_productive: and its comment) sits in _run_chat, which this PR keeps in chat_runner.py, so it is carried as is; test_dashboard_chat_empty_response_ladder.py passes on this head. CI re-running.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: ba655d1
  • What rule changed: none. security_posture.NON_EGRESS_REDACTION_MODULES lists the seven dashboard/chat_turn/ owners that now hold redactor calls moved out of dashboard/chat_runner.py, and test_security_posture.py's gate-side log census moves one site from the runner (9 to 8) to chat_turn/native_cards.py (1).
  • Before -> after (what was allowed/blocked, now): the same redactor calls, with the same arguments, run on the same text and reach the same surfaces; only the module that holds each call changed, and the registry names that module.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): a redactor site counted under the wrong module, so the posture panel's site count is off; no redaction, command or gate changes, since every moved definition is byte-identical (move audit: 100% moved, 0 changed).
  • Evidence checked (which sandbox result proves it): no sandbox path changes; the move audit, the omission and census tests in test_security_posture.py, and mutants that drop the non-egress row or the census row and turn those tests red.
  • No regression:
    • Tools still work (which tools/commands were run, result): the dashboard turn suites (test_chat_runner_turn_*.py, 94 tests that run whole turns) and every test that imports, patches or reads the runner pass on this head.
    • Backward compatible (old config / old data / old callers still work, how checked): every name chat_runner bound at the base is still bound as the same object (test_campaign_facades_base_public_names.py, the composition contract's base-surface rows), so callers and patches of chat_runner.<name> are unchanged.
    • Existing tests (which suites passed on this head): test_security_posture.py, test_core_path_redact_before_bound.py and the 309 files that touch the runner or its owners (19,081 passed; 5 load timeouts that pass on their own).
  • How to undo: revert this one commit; no data or config changes.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • First Principles punchline: the runner's F401 exemption relies on compose_binding alone to catch an unread import -- intended, and covered

pyflakes reads only the runner's own text. Every import whose last reader moved to an owner would be a false F401 there, so the per-file exemption is what lets those imports stay for the owners compose runs on the runner's globals.
test_chat_runner_compose_binding.py::test_every_name_the_runner_imports_is_read reads the runner and every owner. It fails on a module-level import nothing reads (mutant R7-a-dead-runner-import, a planted import colorsys) and on an unread import inside a runner function (mutant PR3R-a-dead-function-local-import). Both of its helpers have self-tests on synthetic source.
The exemption is F401 alone: the rest of flake8, mypy and the import-read check still run on the file.

@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 Oct 15, 2026

@chenmingwei23 chenmingwei23 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.

Approving: readiness gate passed, no conflicts, checks green.

@chenmingwei23
chenmingwei23 merged commit 22581b7 into main Oct 15, 2026
106 of 107 checks passed
@chenmingwei23
chenmingwei23 deleted the refactor/linecap-g01-chat-runner-p3 branch October 15, 2026 15:41
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 15, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approved by a maintainer after reading the review lanes: every lane is clean on this head, and the automated triage held it only on a size, path, category or doc rule.

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.

3 participants