Skip to content

refactor: split llm_helpers.py and mcp_cron.py into owner modules - #21598

Merged
iamwhatever merged 1 commit into
mainfrom
refactor/linecap-s19-llm-helpers
Oct 19, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
refactor/linecap-s19-llm-helpers

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Bring llm_helpers.py (4,008 lines) and mcp_cron.py (3,870) under the 2,000-line cap by moving their definitions into focused owner modules, with every import path and patch seam unchanged.

Both files were among the largest hand-written modules in the tree. llm_helpers.py changed 13 times in the last week, so each feature PR added to a file nobody could read in one sitting, and the line-cap guard already listed both files as over the cap.

Why it matters

The user's rule is that no hand-written file exceeds 2,000 lines. These two files also hold security-relevant code that reviewers have to read whole: the unattended tool-approval gate (_resolve_permission, 573 lines) and the cron shell gate (_vet_shell_command and its scanners). Splitting them by responsibility gives each new change one obvious home and keeps the next feature PR from landing on a 4,000-line file.

Not a goal

  • No behaviour change: every moved definition is byte-identical apart from the edits listed under Move audit.
  • No change to which names kiro_crew.llm_helpers and kiro_crew.mcp_cron offer, or to how tests patch them.
  • No change to the security posture, the cron gate's rules, or the tool-approval policies.
  • No test is split or rewritten; tests change only where they read a moved construct by path or by module text.

What changed (motivation → approach → change)

Both files become kiro_crew._facade_mirror facades: the module path stays the import path and the patch surface, and a write through it (monkeypatch.setattr, mock.patch) reaches every owner that binds the name, so moved code reads its own globals unchanged.

File Before After Owners (lines)
src/kiro_crew/llm_helpers.py 4,042 283 (pure facade) llm_helpers_parts/: backend_errors 427, turn_usage 317, model_fallback 875, tool_input_denials 328, tool_approval 797, turn_results 250, turn_stream 608, background_turns 633
src/kiro_crew/mcp_cron.py 3,870 1,503 (keeps the server: call path, caller checks, tool bodies, entry point) mcp_cron_shell_scan.py 938, mcp_cron_vet.py 831, mcp_cron_tool_list.py 430, mcp_cron_list_render.py 430

The llm_helpers owners need the ACP layer's names at run time (EVENT_*, LLMEvent, LLMProvider, AcpError, TurnUsage, resolve_billing_stats, ...), and the agent-sdk boundary gate refuses a new kiro_crew.acp/kiro_crew.providers import. They read them from a new agent_sdk/drivers/acp_turn_vocab.py, which re-exports exactly the objects llm_helpers.py imported (the acp_vocab.py pattern), and _provider_label reaches provider_label through the agent_sdk/drivers/acp.py wrapper the sub-agent split added. llm_helpers.py drops from 5 boundary edges to 0. The facade also imports each owner module under a private alias (from kiro_crew.llm_helpers_parts import turn_usage as _turn_usage): without a real import edge, mypy checked the facade's importers before the owners and reported [has-type] where history_consolidation, subagent and chat_runner read an owner's name at import time inside one import cycle. The mcp_cron owners are top-level siblings rather than a package. The owner maps and "new work goes to" lines are in docs/system-specs/modules/providers.md (Turn helpers) and docs/architecture/mcp.md.

Backwards compatibility

Compatible: every BASE public name of both modules still resolves on the facade to the same object, pinned by test/campaign_facade_inventories/kiro_crew.llm_helpers.json and kiro_crew.mcp_cron.json; every name the test trees patch through either facade reaches every module that binds it (test_llm_helpers_facade.py, test_mcp_cron_facade.py, test_facade_mirror_guards.py).

The public module-level defs below moved out of llm_helpers.py / mcp_cron.py; each is still served by the facade:

Reader: src/kiro_crew/llm_helpers.py:is_transient_backend_error -- chat -- served from llm_helpers_parts/backend_errors.py (same object); pinned by test/test_acp_credential_propagation_retry.py
Reader: src/kiro_crew/llm_helpers.py:is_prompt_busy -- chat -- served from llm_helpers_parts/backend_errors.py (same object); channel.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:is_context_overflow_error -- chat -- served from llm_helpers_parts/backend_errors.py (same object); pinned by test/test_context_overflow_recovery.py
Reader: src/kiro_crew/llm_helpers.py:acp_error_is_transient -- chat -- served from llm_helpers_parts/backend_errors.py (same object); acp/session_handle.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:acp_error_is_session_not_found -- chat -- served from llm_helpers_parts/backend_errors.py (same object); acp/transport_errors.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:acp_error_needs_fresh_credentials -- chat -- served from llm_helpers_parts/backend_errors.py (same object); channel.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:credential_give_up_text -- chat -- served from llm_helpers_parts/backend_errors.py (same object); channel.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:acp_error_after_tool_activity -- chat -- served from llm_helpers_parts/backend_errors.py (same object); slack/gateway.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:transient_retry_delay -- chat -- served from llm_helpers_parts/backend_errors.py (same object); dashboard/chat_runner.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:acp_error_is_connection_failure -- chat -- served from llm_helpers_parts/backend_errors.py (same object); dashboard/chat_runner.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:connection_recovery_open -- chat -- served from llm_helpers_parts/backend_errors.py (same object); dashboard/chat_runner.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:connection_retry_delay -- chat -- served from llm_helpers_parts/backend_errors.py (same object); dashboard/chat_runner.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:first_advertised_fallback -- chat -- served from llm_helpers_parts/model_fallback.py (same object); dashboard/chat_runner.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:fallback_rewound_transient_budget -- chat -- served from llm_helpers_parts/model_fallback.py (same object); dashboard/chat_runner.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:fallback_story_of -- chat -- served from llm_helpers_parts/model_fallback.py (same object); pinned by test/test_llm_helpers.py
Reader: src/kiro_crew/llm_helpers.py:append_fallback_story -- cron -- served from llm_helpers_parts/model_fallback.py (same object); heartbeat.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:annotate_model_fallback -- cron -- served from llm_helpers_parts/model_fallback.py (same object); slack/gateway_runtime/cron_dispatch.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:provider_fallback_active -- chat -- served from llm_helpers_parts/model_fallback.py (same object); dashboard/chat_runner.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:provider_model_pin_refused -- chat -- served from llm_helpers_parts/model_fallback.py (same object); dashboard/chat_handlers.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:provider_model_pin_partial -- chat -- served from llm_helpers_parts/model_fallback.py (same object); slack/gateway.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:next_fallback_candidate -- chat -- served from llm_helpers_parts/model_fallback.py (same object); pinned by test/test_llm_helpers.py
Reader: src/kiro_crew/llm_helpers.py:advance_fallback_candidate -- chat -- served from llm_helpers_parts/model_fallback.py (same object); dashboard/chat_turn/model_fallback.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:pick_epoch_host -- chat -- served from llm_helpers_parts/model_fallback.py (same object); decisions/points/model_route.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:route_baseline_latch -- chat -- served from llm_helpers_parts/model_fallback.py (same object); dashboard/chat_runner.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:latch_route_baseline -- chat -- served from llm_helpers_parts/model_fallback.py (same object); dashboard/chat_runner.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:slot_switch_session_lock -- chat -- served from llm_helpers_parts/model_fallback.py (same object); dashboard/session_control.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:resolve_substitute_set_model -- chat -- served from llm_helpers_parts/model_fallback.py (same object); dashboard/chat_runner.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:provider_advertised_ids -- chat -- served from llm_helpers_parts/model_fallback.py (same object); decisions/points/model_route.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:provider_backend -- chat -- served from llm_helpers_parts/model_fallback.py (same object); decisions/points/model_route.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:provider_active_model -- chat -- served from llm_helpers_parts/model_fallback.py (same object); dashboard/chat_runner.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:provider_raw_model -- chat -- served from llm_helpers_parts/model_fallback.py (same object); dashboard/chat_runner.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:probe_fallback_restore -- chat -- served from llm_helpers_parts/model_fallback.py (same object); dashboard/chat_turn/model_fallback.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:configured_fallback_chain -- chat -- served from llm_helpers_parts/model_fallback.py (same object); dashboard/chat_turn/model_fallback.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:record_interaction_event -- chat -- served from llm_helpers_parts/turn_usage.py (same object); dashboard/chat_runner.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:run_bg_oneliner -- chat -- served from llm_helpers_parts/background_turns.py (same object); dashboard/card_lifecycle.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:usage_has_billing -- chat -- served from llm_helpers_parts/turn_usage.py (same object); dashboard/chat_utils_turn_recovery.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:provider_last_turn_usage -- chat -- served from llm_helpers_parts/turn_usage.py (same object); providers/base.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:background_turn -- chat -- served from llm_helpers_parts/background_turns.py (same object); history_consolidation_pass.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:unfinished_turn_error -- chat -- served from llm_helpers_parts/turn_stream.py (same object); cli_chat.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:stream_and_collect -- app -- served from llm_helpers_parts/turn_stream.py (same object); apps/builtins/issue_radar/backend/http_routes/ai.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:stream_and_collect_json -- subagent -- served from llm_helpers_parts/turn_stream.py (same object); taskrunner.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:parse_llm_json -- app -- served from llm_helpers_parts/turn_results.py (same object); apps/builtins/issue_radar/backend/http_routes/ai.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:parse_llm_json_list -- chat -- served from llm_helpers_parts/turn_results.py (same object); pinned by test/test_llm_helpers.py
Reader: src/kiro_crew/llm_helpers.py:save_conversation_turn -- chat -- served from llm_helpers_parts/turn_results.py (same object); slack/transport_dispatch.py imports it from the facade
Reader: src/kiro_crew/llm_helpers.py:save_conversation_turn_off_loop -- chat -- served from llm_helpers_parts/turn_results.py (same object); slack/transport_dispatch.py imports it from the facade
Reader: src/kiro_crew/mcp_cron.py:vet_job_at_fire_time -- cron -- served from mcp_cron_vet.py (same object); slack/gateway.py imports it from the facade

Logger names are unchanged: every owner binds logging.getLogger("kiro_crew.llm_helpers") / ("kiro_crew.mcp_cron") (L25), so the caplog captures keyed on those names (test_llm_helpers_deny_notice.py, test_cron_app_disabled_fire_time_gate.py) still see the records. Moved classes (FallbackState, ToolApprovalPolicy, PromptBusyExhaustedError, _ScanTooComplex) report their owner's __module__; nothing reads it (no pickling, __module__/__qualname__ assertion or user-visible class path; checked by the patch-seam sweep).

Move audit

src/kiro_crew/llm_helpers.py: 4042 -> 283 lines; moved 96.41% (python-ast)
   changed: _steer_host_deny [AsyncFunctionDef] 76 lines
   changed: _provider_label [FunctionDef] 33 lines
   changed: usage_has_billing [FunctionDef] 17 lines
   changed: If [If] 3 lines
src/kiro_crew/mcp_cron.py: 3870 -> 1503 lines; moved 100.0% (python-ast)
  • _provider_label: its two lazy ACP imports become kiro_crew.agent_sdk.drivers.acp.provider_label and kiro_crew.agent_sdk.drivers.acp_turn_vocab.PROVIDER_LABEL_DEFAULT, still lazy inside its try (providers.acp is still read at call time); its docstring's "this module" names kiro_crew.llm_helpers.
  • usage_has_billing: docstring reworded for the comment-history gate (drops (#6758)).
  • _steer_host_deny: docstring only -- "this module" / "the file" now name kiro_crew.llm_helpers, since its deny sites span two owners (this edit takes llm_helpers.py from 98.5% to 96.4% moved unchanged; both targets together 98.3%).
  • If: BASE's one TYPE_CHECKING block (ConversationLog, HookManager) goes to the owners that annotate with them.
  • Comment-only edits on moved lines: _TRANSIENT_MARKERS' two #1550 references reworded (comment-history); the # ── Stream and Collect ── header dropped from background_turns (it would head the wrong owner).
  • Glue: owner imports, one literal-name logger per owner, the facades' owner loop, mirror install and TYPE_CHECKING manifests, and llm_helpers.py's private owner-module aliases (the mypy ordering above).

L36 (default vs --minimal added lines, per file): mcp_cron.py 164/164; every other changed file equal; llm_helpers.py 249/243 — the six differing added lines are all blank (a pure-glue facade). Layout search: 72 glue-order/logger layouts, 256 top-level blank-line layouts, 31 in-block blank-line patterns and the no-facade-logger shape; none is equal, and the closest equal layout needs getLogger(__name__), which breaks python -m kiro_crew.llm_helpers.

Diff: 798,447 bytes.

Prose citations (L29): CONTRIBUTING.md:253 now says cron tools live in mcp_cron.py (their bodies) and mcp_cron_tool_list.py (their schemas). The other doc edits are the owning specs' file-form citations (sel.md, history.md, subagent.md, governance.md, platform-context.md, learn-cron-dashboard.md, resource-protection.md) and the RFC line cite llm_helpers.py:299 -> llm_helpers.run_bg_oneliner.

Upstream ports (L16), each carried byte for byte by re-running the recipe on the new main: #19745's READ_ONLY deepseek_read_only_issue branch moves with _resolve_permission into llm_helpers_parts/tool_approval.py; #20973's cloud_credential_error recycle (acp_error_is_session_not_found, acp_error_needs_fresh_credentials, credential_give_up_text, CREDENTIAL_RELOAD_RETRY_NOTICE) moves into llm_helpers_parts/backend_errors.py; #20687's sensitive_write_path_refusal import and _edit_target_denial write-path branch move into llm_helpers_parts/tool_input_denials.py; #21907's throttle pieces (THROTTLE_RETRY_BASE_DELAY, throttle_retry_delay, acp_error_is_throttle, and the provider_error_client import they read) move into llm_helpers_parts/backend_errors.py.

Baselined growth (L56 addendum 1b): src/kiro_crew/security_posture.py main row 3,181, BASE 3,449, HEAD 3,452 — NON_EGRESS_REDACTION_MODULES path rows only: llm_helpers.py becomes llm_helpers_parts/model_fallback.py (same reason comment) plus llm_helpers_parts/tool_approval.py; mcp_cron_list_render.py and mcp_cron_vet.py beside mcp_cron.py.

Baselines: line-cap rows for both targets deleted; .github/agent-sdk-boundary-baseline.txt row 5 src/kiro_crew/llm_helpers.py deleted (0 edges); the line-ref docs-lint row for rfc-resumable-subagent-sessions.md / llm_helpers.py:299 deleted (the cite is now llm_helpers.run_bg_oneliner).

Tests

  • New test/test_llm_helpers_facade.py, test/test_mcp_cron_facade.py: every name the test trees patch through the facade reaches every module holding it (with a known-seams non-vacuity check), owners = the package / mcp_cron_*.py siblings in layer order, each served outside name is visible to type checkers, one logger named for the facade, python -m <facade> still imports, and (llm_helpers) each acp_turn_vocab name is its kiro_crew.acp/kiro_crew.providers object and only llm_helpers_parts imports it at run time.
  • Source pins re-pointed or joined to the owners, assertions unchanged, each with a mutation proof (the guard goes red when the construct changes in its new home): test_llm_helpers_deny_notice.py (deny-site walk over facade + owners), test_crew_log_resolver.py, test_meetings_session.py, test_name_grant_surfaces.py (facade + llm_helpers._OWNERS), test_start_priority.py (path), test_transport_permission_floor.py and test_hooks.py (row re-key), test_mcp_call_site_auth_coverage.py (mcp_cron_*.py glob), test_skill_home_paths.py, test_instance_credential_pairing.py (owner rows), test_security_posture.py (census row) and security_posture.py (NON_EGRESS_REDACTION_MODULES rows).
  • Local floor (520 files: every test naming either module, the agent-SDK vocabulary or security_posture, plus every rglob/source_corpus tree scanner; scripts/local-gate.py --dry-run selects 2,156 backend files, so the full set is CI's): 39,744 passed, 1 failed — test_external_logout_detection_retirement.py::TestRetirementCoverage::test_every_sid_writer_is_registration_or_identity_fenced hit the 120 s timeout at host load 52 and passes alone in 44 s (environmental, not this change). Cold mypy src/kiro_crew: no issues in 2,695 files. Facade and mirror guards re-run after the last facade edit: 320 passed.
  • Determinism: the new tests wait on nothing, use tmp_path/monkeypatch, and read sets sorted; the two new files passed 5 runs at -n0 and one at -n 3; test_flake_pattern_ratchet.py passes.

Manual verification

N/A — a structural move proven by the move audit and the facade/seam tests; an env -i import smoke and an installed-wheel import of every new module ran clean (15 modules imported from the wheel built from a git archive export).

Related Issues

Part of #20192

Follow-up: #21371 (pre-existing order-dependent sel binding; test/test_name_grant_surfaces.py::TestGatewayReadsModeSurface::test_refused_grant_falls_to_the_human_prompt fails after test/test_llm_helpers_deny_notice.py in one process, on unmodified main too)

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

@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 6aa44e0
  • What rule changed: no rule; security_posture.NON_EGRESS_REDACTION_MODULES gets path rows for the owner modules that now hold the moved redactor calls (llm_helpers.py becomes llm_helpers_parts/model_fallback.py with its reason comment, plus llm_helpers_parts/tool_approval.py; mcp_cron_list_render.py and mcp_cron_vet.py beside mcp_cron.py), and the _BASELINE_LOG_SITE_CENSUS row moves from mcp_cron.py to mcp_cron_vet.py.
  • Before -> after (what was allowed/blocked, now): unchanged; the same redactor calls run in the same moved code, classified under their new files; no sink, scrubber or posture rule changes.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): a moved redactor call is left unclassified and test_security_posture fails in CI; nothing at run time reads these rows to decide behaviour.
  • Evidence checked (which sandbox result proves it): test/test_security_posture.py passes on this head, and dropping the llm_helpers_parts/tool_approval.py row or restoring the old census row makes it fail (recorded mutation proofs); no sandbox path or seal is touched.
  • No regression:
    • Tools still work (which tools/commands were run, result): the llm_helpers and transport_errors test floor (134 files) passed 8,836 tests and the focused guard set passed 3,219 on the gated commit.
    • Backward compatible (old config / old data / old callers still work, how checked): registry path rows only; every public name of both facades is pinned by its campaign inventory and resolves to the same object.
    • Existing tests (which suites passed on this head): test_security_posture.py, test_facade_mirror_guards.py, test_llm_helpers_facade.py and test_mcp_cron_facade.py passed locally.
  • How to undo: revert this one commit; the rows go back with the code.

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners October 17, 2026 10:52
@bolichen97
bolichen97 requested a review from buluoray October 17, 2026 10:52
@github-actions

github-actions Bot commented Oct 17, 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 83d1d44.

@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 83d1d44dbe737a23ba62dd55eebe3ad950cdde1f 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 17, 2026
@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Check that the full CI suite is green. The facade-mirror patch seams decide whether the many monkeypatch.setattr(llm_helpers, ...) tests still reach the moved owner modules.

[DESIGN-REVIEWED] 83d1d44

Description read

[DESCRIPTION-READ] 4ecec60aca494c7fa90bcddffd4f798597b1dd1370169f42bcb60ea662d2848a

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

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

acp_turn_vocab.py is a second ACP re-export module next to acp_vocab.py, which already does that job and already re-exports AcpError.

Not justified as shipped

  • Item 3 — duplicate of src/kiro_crew/agent_sdk/drivers/acp_vocab.py: the new module's docstring says it "follows kiro_crew.agent_sdk.drivers.acp_vocab", the module that "carries the names application code reads by value". So it is the same mechanism under a second spelling. Both modules bind AcpError from kiro_crew.acp.client. acp_vocab has 14 importing files in src (grep drivers.acp_vocab import). The new module has 8 import lines (grep acp_turn_vocab import), all of them in llm_helpers_parts/ or the facade. The only reason given for a separate module is that it is scoped, and that is symmetry with acp_vocab, not a named harm.
    Subtraction: delete acp_turn_vocab.py, move its 13 names into acp_vocab.__all__, and drop the test that pins "no module outside llm_helpers_parts imports this one".
    Clears when: the module is folded into acp_vocab.py, or the PR names something that breaks if the two are one module (for example, a boot-path import of acp_vocab that must not load providers.base).

What this change ships

Inventory (8 items) — 7 justified

Intent: keep two oversized modules under the 2,000-line cap without changing any caller or patch seam. This is a refactor (mandated by AGENTS.md's line cap), not a fix or an addition.

  1. llm_helpers.py becomes a facade over eight owner modules — justified
  2. mcp_cron.py keeps the server and moves its scanners, vetting and list rendering into four sibling modules — justified
  3. A new boundary re-export module for ACP turn names — duplicate of agent_sdk/drivers/acp_vocab.py
  4. The facade imports each owner under a private alias to fix mypy [has-type] errors — justified
  5. Both files leave the line-cap baseline, and llm_helpers.py leaves the boundary baseline — justified
  6. The security-posture registries and tests now point at the owner files — justified
  7. New facade inventory tests pin every public name and patch seam — justified
  8. Spec, architecture and RFC docs point at the new owner modules — justified

[FIRST-PRINCIPLES-REVIEWED] 83d1d44

Description read

[DESCRIPTION-READ] 57ceaf422afa98c8a01c8e15de3352c20479e607fcdb16987f99060039b32ac1

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 83d1d44

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

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

Comment thread src/kiro_crew/mcp_cron_vet.py Dismissed
Comment thread src/kiro_crew/mcp_cron_vet.py Dismissed
Comment thread src/kiro_crew/mcp_cron_vet.py Dismissed
@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 83d1d44

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

@bolichen97
bolichen97 enabled auto-merge (squash) October 17, 2026 11:05
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=861594dbc02e acp_turn_vocab.py next to acp_vocab.py — rebutted

Named constraint: an importer fence acp_vocab.py cannot carry. 8 of the 13 names are the provider interface from kiro_crew.providers.base (LLMProvider, LLMEvent, the EVENT_* kinds, resolve_billing_stats), not ACP vocabulary.
acp_vocab.py is imported, unfenced, by 10+ modules across the tree (messaging, slack/telegram transport, subagent, task_executor, dashboard handlers). Putting the provider interface there would open a sanctioned route around check_agent_sdk_boundary.py for every one of them.
acp_turn_vocab.py is pinned to its readers: test/test_llm_helpers_facade.py asserts no module outside kiro_crew.llm_helpers_parts imports it (AST scan of the tree, 14-case self-test), and that each name is its home module's object.
The two import blocks in turn_stream.py are BASE's: llm_helpers.py already imported AcpTimeoutError / STOP_* from acp_vocab, and that import moved verbatim.
No import cost either way (acp_vocab already loads providers.base); the split keeps the hole as narrow as the code that needs it.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Source-text ratchets keyed to mcp_cron.py / llm_helpers.py scan the owners — answered

Swept every test that reads either file by path, __file__, read_text, getsource(<module>) or a tree scan. Each that pins moved code is joined or re-pointed, assertions unchanged:
joins (facade + owners): test_llm_helpers_deny_notice, test_crew_log_resolver, test_meetings_session, test_name_grant_surfaces, test_mcp_call_site_auth_coverage (mcp_cron_*.py glob).
re-points: test_start_priority, test_transport_permission_floor, test_hooks helper sites, test_skill_home_paths, test_instance_credential_pairing, the security_posture census and NON_EGRESS_REDACTION_MODULES rows.
Each carries a mutation proof (break the construct in its owner, the test goes red). getsource(<function>) readers and path-agnostic tree scans reach the moved code unchanged.
Patch reach is pinned by corpus-derived guards in test_llm_helpers_facade.py / test_mcp_cron_facade.py, each with a non-vacuity self-test.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Oct 17, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD at 6aa44e0.

This PR has a merge conflict with main, so I can't approve it. A rebase produces a new head, which needs its own review.

What I checked at this head: the moved code is near-verbatim by line-multiset comparison, and the NON_EGRESS_REDACTION_MODULES rows follow the moved redactor calls without dropping coverage. The CodeQL alerts on mcp_cron_vet.py are dismissed false positives on moved code. The First Principles and Design items have evidence-backed answers.

This PR also moves the tool-approval gate and the cron shell gate, and it is not purely mechanical: _provider_label now resolves through agent_sdk/drivers/acp.py, and the owners import through the new acp_turn_vocab.py. After the rebase, a human reviewer should confirm the gate code is unchanged.

What would clear this: rebase onto main, get CI green again, and have a human review the gate moves.

— crew-pr-reviewer (r109)

@bolichen97
bolichen97 force-pushed the refactor/linecap-s19-llm-helpers branch from 6aa44e0 to 643c678 Compare October 17, 2026 18:35
@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 643c678
  • What rule changed: no rule; security_posture.NON_EGRESS_REDACTION_MODULES gets path rows for the owner modules that now hold the moved redactor calls (llm_helpers.py becomes llm_helpers_parts/model_fallback.py with its reason comment, plus llm_helpers_parts/tool_approval.py; mcp_cron_list_render.py and mcp_cron_vet.py beside mcp_cron.py), and the _BASELINE_LOG_SITE_CENSUS row moves from mcp_cron.py to mcp_cron_vet.py.
  • Before -> after (what was allowed/blocked, now): unchanged; the same redactor calls run in the same moved code, classified under their new files; no sink, scrubber or posture rule changes.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): a moved redactor call is left unclassified and test_security_posture fails in CI; nothing at run time reads these rows to decide behaviour.
  • Evidence checked (which sandbox result proves it): test/test_security_posture.py passes on this head, and dropping the llm_helpers_parts/tool_approval.py row or restoring the old census row makes it fail (recorded mutation proofs); no sandbox path or seal is touched.
  • No regression:
    • Tools still work (which tools/commands were run, result): the 199 test files that import, patch or read llm_helpers / mcp_cron (test_security_posture.py and test_hooks.py among them) passed 13,953 tests on the gated commit.
    • Backward compatible (old config / old data / old callers still work, how checked): registry path rows only; every public name of both facades is pinned by its campaign inventory and resolves to the same object.
    • Existing tests (which suites passed on this head): test_security_posture.py, test_facade_mirror_guards.py, test_llm_helpers_facade.py and test_mcp_cron_facade.py passed locally.
  • How to undo: revert this one commit; the rows go back with the code.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main changed src/kiro_crew/llm_helpers.py (#20687, b290c52) after this PR's last head, so this head re-cuts the split on main 3f68ca0 and carries #20687's sensitive_write_path_refusal import and _edit_target_denial branch byte for byte into llm_helpers_parts/tool_input_denials.py (in-slot rebase onto 4be3332, which touches neither target). It supersedes 6aa44e0; CI re-running.

@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 17, 2026
@bolichen97

bolichen97 commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=900164cc404b acp_turn_vocab.py next to acp_vocab.py — rebutted

The constraint is an importer fence that acp_vocab.py cannot carry. It is not an import cycle: acp_vocab already loads providers.base, so folding the names in costs nothing at import time.
8 of the 13 names are the provider interface from kiro_crew.providers.base (LLMProvider, LLMEvent, the EVENT_* kinds, resolve_billing_stats). None of them is ACP vocabulary.
acp_vocab.py has 10 unfenced importer modules outside llm_helpers (messaging, slack and telegram transport, subagent, task_executor, dashboard handlers). Folding these names in would let every one of them reach the provider interface without naming kiro_crew.providers, so check_agent_sdk_boundary.py would never see it.
acp_turn_vocab.py is pinned to the code that needs it. test/test_llm_helpers_facade.py fails if any module outside kiro_crew.llm_helpers_parts imports it (a tree AST scan with a 14-case self-test), and it checks that each name is the same object as in its home module.
The two import blocks in turn_stream.py come from BASE: llm_helpers.py already imported AcpTimeoutError / STOP_* from acp_vocab, and that import moved verbatim.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • test_script_body_is_never_a_shell_gate_subject still reaches the moved vetter — answered, with mutation proofs

The test patches mcp_cron.is_sensitive_bash_command on the mirror facade, and the facade writes the patch into every owner that binds the same object, mcp_cron_vet.py included. It then runs _vet_script_contents in its new home.
Mutation 1: a direct is_sensitive_bash_command(text) call at the top of _vet_script_contents in mcp_cron_vet.py makes the test FAIL ("shell matcher reached with a source body").
Mutation 2: a new from kiro_crew.security import is_sensitive_bash_command in mcp_cron_shell_scan.py, called from _matched_sensitive_name (which the vetter calls), also makes it FAIL.
Unmutated, the test passes. A call through security.is_sensitive_bash_command is caught by the test's own security patch.

@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 17, 2026
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 19, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • test_mcp_cron_facade covers the security ratchets' facade patches — answered

test/test_mcp_cron_facade.py scans every test-tree file for patches through kiro_crew.mcp_cron. Its _KNOWN_SEAMS includes is_sensitive_bash_command, sensitive_path_refusal, fd_real_path, _vet_script_contents, _vet_script_file, _vet_command_governance and _audit_fire_time_decision. test_the_patch_scan_finds_every_known_seam fails if the scan misses one, so it cannot pass over nothing.
test_a_facade_patch_of_every_scanned_name_reaches_every_module_holding_it patches each scanned name on the facade. It asserts that every family module binding that name (mcp_cron_vet, mcp_cron_shell_scan, ...) sees the patched object and that the undo restores all of them. It also asserts that the mirror index has no divergent holders.
Behavioural check: inserting an is_sensitive_bash_command call into _vet_script_contents (mcp_cron_vet.py) or into _matched_sensitive_name (mcp_cron_shell_scan.py) makes test_script_body_is_never_a_shell_gate_subject fail through that facade patch. Both are mutation proofs in guard_reach_sweep.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=0f629b7c2aea acp_turn_vocab.py next to acp_vocab.py — rebutted

The harm a separate, single-package module prevents is that the provider interface would leak past the agent-sdk boundary to every acp_vocab importer.
8 of its 13 names are kiro_crew.providers.base's provider interface (LLMProvider, LLMEvent, the EVENT_* kinds, resolve_billing_stats), not ACP vocabulary. acp_vocab.py has 10 unfenced importer modules (messaging, slack and telegram transport, subagent, task_executor, dashboard handlers).
Folding these names into acp_vocab would let any of those modules use the provider interface without naming kiro_crew.providers, and check_agent_sdk_boundary.py would not see it.
acp_turn_vocab is fenced: test/test_llm_helpers_facade.py fails if a module outside kiro_crew.llm_helpers_parts imports it (a tree AST scan with a 14-case self-test), and it checks that each name is its home module's object.
The module-scope and boot-path rules are shared because both modules re-export by value; that is not duplication. acp_vocab already loads providers.base, so there is no import-cost reason either way.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Oct 19, 2026
Both files were over the 2,000-line cap (4,042 and 3,870 lines). Each
stays the import path and the patch surface as a _facade_mirror facade:
a write through it reaches every owner that binds the name, so moved
code reads its own globals unchanged.

llm_helpers.py becomes a pure facade over llm_helpers_parts/: backend
errors, turn usage, model fallback, tool-input denials, tool approval,
turn results, turn stream and background turns. The owners read the
ACP layer's names from the new agent_sdk/drivers/acp_turn_vocab.py,
so llm_helpers.py has no agent-sdk boundary edge left. mcp_cron.py
keeps the server itself (call path, caller checks, tool bodies, entry
point) over four sibling owners: the shell scanners, the cron gate,
the tool list and the cron_list renderings.

Source pins that read moved code by path or module text are re-pointed
or joined to the owners; registry rows, baselines, the owning specs
and doc citations follow the move.

Part of #20192
@bolichen97
bolichen97 force-pushed the refactor/linecap-s19-llm-helpers branch from 1d35245 to 83d1d44 Compare October 19, 2026 04:45
@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 83d1d44
  • What rule changed: no rule; security_posture.NON_EGRESS_REDACTION_MODULES gets path rows for the owner modules that now hold the moved redactor calls (llm_helpers.py becomes llm_helpers_parts/model_fallback.py with its reason comment, plus llm_helpers_parts/tool_approval.py; mcp_cron_list_render.py and mcp_cron_vet.py beside mcp_cron.py), and the _BASELINE_LOG_SITE_CENSUS row moves from mcp_cron.py to mcp_cron_vet.py.
  • Before -> after (what was allowed/blocked, now): unchanged; the same redactor calls run in the same moved code, classified under their new files; no sink, scrubber or posture rule changes.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): a moved redactor call is left unclassified and test_security_posture fails in CI; nothing at run time reads these rows to decide behaviour.
  • Evidence checked (which sandbox result proves it): test/test_security_posture.py passes on this head, and dropping the llm_helpers_parts/tool_approval.py row or restoring the old census row makes it fail (recorded mutation proofs); no sandbox path or seal is touched.
  • No regression:
    • Tools still work (which tools/commands were run, result): the 210 test files that import, patch or read llm_helpers / mcp_cron (test_security_posture.py and test_hooks.py among them) passed 14,278 tests on the gated commit.
    • Backward compatible (old config / old data / old callers still work, how checked): registry path rows only; every public name of both facades is pinned by its campaign inventory and resolves to the same object.
    • Existing tests (which suites passed on this head): test_security_posture.py, test_facade_mirror_guards.py, test_llm_helpers_facade.py and test_mcp_cron_facade.py passed locally.
  • How to undo: revert this one commit; the rows go back with the code.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased onto main 1862203: #21672 and #21951 rewrote lines next to two of this PR's edits (the llm_helpers.run_bg_oneliner cite in rfc-resumable-subagent-sessions.md and the mcp_cron_*.py row in test_mcp_call_site_auth_coverage.py). Union kept: main's text plus this PR's edits. The patch is otherwise unchanged; this head supersedes 1d35245. CI re-running.

@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 19, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=99313b9dc676 acp_turn_vocab.py next to acp_vocab.py — rebutted

What breaks if the two are one module is the importer fence, not the boot path. acp_vocab already loads providers.base transitively, so nothing changes at import time.
8 of acp_turn_vocab's 13 names are kiro_crew.providers.base's provider interface (LLMProvider, LLMEvent, the EVENT_* kinds, resolve_billing_stats), not ACP vocabulary. test/test_llm_helpers_facade.py fails if any module outside kiro_crew.llm_helpers_parts imports acp_turn_vocab (a tree AST scan with a 14-case self-test).
acp_vocab has 10 unfenced importer modules (messaging, slack and telegram transport, subagent, task_executor, dashboard handlers). One merged module cannot keep that fence: it would hand the provider interface to all of them without naming kiro_crew.providers, and check_agent_sdk_boundary.py would not see it.
The shared AcpError re-export is the same object in both modules; the fence test asserts identity with its home module.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Full CI on this head, and the facade-mirror patch seams — answered

Every backend job is green on this head: Backend Tests (3.12) shards 1-8, Backend Tests (Windows) shards 1-8, IPv6 (ubuntu, windows), namespace sandbox, crew container, Kernel Lock Owner, Integration (in-process gateway), and E2E (stub ACP, private namespace, gateway boot on ubuntu and windows). The macOS suite is skipped by its own selector.
Patch reach is pinned. test/test_llm_helpers_facade.py and test/test_mcp_cron_facade.py collect every name the test trees patch through each facade, with a known-seam non-vacuity table. They patch each name on the facade and assert that every owner binding it sees the patched object, that the undo restores all of them, and that the mirror index has no divergent holders. test/test_facade_mirror_guards.py applies the same rules to every mirror facade.

@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 19, 2026

@iamwhatever iamwhatever 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 83d1d44.

This PR touches the tool-approval gate, the cron shell gate and security_posture.py, so I checked that it is a pure move. An AST comparison against merge base 1862203 found every top-level definition from both original files in the facade or an owner module: 107 for llm_helpers.py and 98 for mcp_cron.py. Apart from two docstring-only edits, the loggers' literal names, and _provider_label reaching the same provider_label through the SDK wrapper, they are identical. That includes _resolve_permission and _vet_shell_command. There are no global rebinds or duplicate definitions, and pyflakes finds no undefined names. The NON_EGRESS_REDACTION_MODULES rows follow the redactor calls, whose counts are unchanged (8 in llm_helpers, 20 in mcp_cron).

The First Principles concern about acp_turn_vocab.py is answered at this head with a concrete harm: merging it into acp_vocab would give the provider interface to that module's unfenced importers. The Design check is also answered. CodeQL 1105-1107 are dismissed false positives on byte-identical moved code. CI is green with nothing pending, and the earlier conflict is gone. #21371 tracks the pre-existing order-dependent test.

I did not run the suite locally.

— crew-pr-reviewer (r112)

@iamwhatever
iamwhatever merged commit 79663b7 into main Oct 19, 2026
104 of 105 checks passed
@iamwhatever
iamwhatever deleted the refactor/linecap-s19-llm-helpers branch October 19, 2026 13:53
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 19, 2026
bolichen97 added a commit that referenced this pull request Oct 19, 2026
…me_grant patch-scan spelling)

#21753 committed a live claude saved-member-spec capture that a test
replays, so the x-capture gate fails main with "allowlisted but now
proven; delete the entry". Delete that one row from
scripts/check_harness_parity.py.

#21598 split llm_helpers.py, and its facade now serves name_grant from
llm_helpers_parts/tool_approval.py through its TYPE_CHECKING manifest.
test_name_grant_facade's spelling scan read only module-level imports, so
it lost the llm_helpers.name_grant spelling (which
test_llm_helpers_deny_notice.py patches) and its helper-binding case
fails. Count a module-level if TYPE_CHECKING: block as module level.

Part of #20192
bolichen97 added a commit that referenced this pull request Oct 19, 2026
… edits

#21753 committed a live claude saved-member-spec capture that a test
replays, so the x-capture gate fails main with "allowlisted but now
proven; delete the entry". Delete that row from
scripts/check_harness_parity.py.

The same commit's three claude captures carry agent_version but no
agent_name in their _meta header, so test_acp_frame_replay's live-header
check fails against their own initialize agentInfo. Add
"agent_name": "@agentclientprotocol/claude-agent-acp" to each header.

test_backend_cards_advertised's SET_GATE_ALLOWLIST overstates three
counts after recent backend edits (its shrink half fails): drop the
acp_cli_overlay.py and model_choice.py KIRO_SLASH_COMMANDS rows (now 0)
and lower acp_model_effort.py to 2.

#21598 split llm_helpers.py, and its facade now serves name_grant from
llm_helpers_parts/tool_approval.py through its TYPE_CHECKING manifest.
test_name_grant_facade's spelling scan read only module-level imports, so
it lost the llm_helpers.name_grant spelling (which
test_llm_helpers_deny_notice.py patches) and its helper-binding case
fails. Count a module-level if TYPE_CHECKING: block as module level.

Part of #20192
bolichen97 added a commit that referenced this pull request Oct 19, 2026
… edits (#22178)

#21753 committed a live claude saved-member-spec capture that a test
replays, so the x-capture gate fails main with "allowlisted but now
proven; delete the entry". Delete that row from
scripts/check_harness_parity.py.

The same commit's three claude captures carry agent_version but no
agent_name in their _meta header, so test_acp_frame_replay's live-header
check fails against their own initialize agentInfo. Add
"agent_name": "@agentclientprotocol/claude-agent-acp" to each header.

test_backend_cards_advertised's SET_GATE_ALLOWLIST overstates three
counts after recent backend edits (its shrink half fails): drop the
acp_cli_overlay.py and model_choice.py KIRO_SLASH_COMMANDS rows (now 0)
and lower acp_model_effort.py to 2.

#21598 split llm_helpers.py, and its facade now serves name_grant from
llm_helpers_parts/tool_approval.py through its TYPE_CHECKING manifest.
test_name_grant_facade's spelling scan read only module-level imports, so
it lost the llm_helpers.name_grant spelling (which
test_llm_helpers_deny_notice.py patches) and its helper-binding case
fails. Count a module-level if TYPE_CHECKING: block as module level.

Part of #20192
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