Repository navigation
refactor(acp): move the rest of AcpSessionHandle into owner modules - #21989
Conversation
session_handle.py still carries 4,873 lines after the first PR of KC28 G06 (part of #20192): the MCP, KAS, native-child, model, steering, permission and session/update members of AcpSessionHandle, and the class statement itself. This second PR brings the file under the repository's 2,000-line cap and deletes its line-cap baseline row. Seven owner modules take those members, each with one responsibility the owning spec names: the session's MCP servers, what KAS speaks beyond ACP, harness-native child sessions, the session's model, steering a live turn, permission requests and in-band refusals, and session/update frames. Bodies move as module-level functions taking self, with the same AST apart from two listed call sites, and the class binds them by name as in the first PR. The class statement moves to session_handle_class.py and sets __module__ to kiro_crew.acp.session_handle, so reprs, pickles and type hints still name the facade. session_handle.py keeps only the compatibility facade and drops to 363 lines.
Sensitive change review
|
Sensitive Change ReviewSensitive files changed:
|
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS
[DESIGN-REVIEWED] f74b8f1 Description read[DESCRIPTION-READ] b83ac55b502a5670ca07e91b34b15d372d506e0cfda32107c59a2df88b598641 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS One patch seam moved: What this change shipsInventory (6 items) — 6 justifiedIntent: get
[FIRST-PRINCIPLES-REVIEWED] f74b8f1 Description read[DESCRIPTION-READ] 734a81bb9e2125266f82c5c266adf215ac4cb8b835b9d019e88d1456fe6b20bb That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
|
|
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Every review lane on the head is clean (only runner notices and PR Scope size warnings); held by the triage cron on size, path or checklist rules alone. Approved on the watch holder's request.
Problem / Motivation
Goal: Bring
src/kiro_crew/acp/session_handle.pyunder the repository's 2,000-line cap by moving the rest ofAcpSessionHandle(its MCP, KAS, native-child, model, steering, permission and session/update members) and the class statement into owner modules, with every behaviour, import path and patch seam unchanged.session_handle.pyis 4,873 lines after the first PR of this series (#21590), still more than twice the cap, and it is in.github/file-line-cap-baseline.txtonly so it can shrink. What is left is the rest of one class: the MCP server handling, the KAS extensions, harness-native child sessions, model selection, steering, permissions and thesession/updatedecoder, plus the class statement and its constructor.Why it matters
Every runtime-backed Kiro Crew session (kiro-cli, KAS, codex and the other harnesses on the shared
AcpRuntime) runs through this class. Until the file is under the cap it stays on the baseline, every feature PR that touches the session transport adds to it, and a reader cannot see where a responsibility lives. This PR finishes KC28 scope G06 (umbrella #20192): it moves the remaining members and deletes the file's baseline row.Not a goal
selfannotation for type checkers, black's reflow of a few dedented lines, three comment rewords for the comment-history gate and one brand-spelling fix, all listed there._input_wait_status) the series plan assigned to the watchdog owner in this PR.acp/session_handle*.py. Elsewhere only citations, path-keyed rows, the source-pin joins in tests and the baseline row change, and no caller's import path changes.What changed (motivation → approach → change)
What is left of
AcpSessionHandlestill shares its state on the instance, and tests still reach that state, patch members on the class and call them unbound. So this PR uses the same binding shape as the first one (L33): each member body becomes a module-level function in an owner, and the class binds it by name.Seven owners take the remaining members, each with one responsibility the owning spec's table names:
acp/session_handle_mcp.py(the session's MCP servers),_kas.py(what KAS speaks beyond ACP, including #21907's checkpoint rewinddiscard_unanswered_prompt),_native_children.py(harness-native child sessions),_model_selection.py(the session's model),_steering.py(steering a live turn),_permissions.py(permission requests and in-band refusals) and_updates.py(session/updateframes asAcpEventvalues). The watchdog owner gains_input_wait_status, as the series plan set out.The class statement itself moves to
acp/session_handle_class.py, which sets__module__ = "kiro_crew.acp.session_handle": reprs, pickles andtyping.get_type_hintskeep naming the facade, andkiro_crew.acp.session_handle.AcpSessionHandleandkiro_crew.acp.runtime.AcpSessionHandlestay the same class object.session_handle.pykeeps only the mirror facade and drops from 4,873 to 363 lines; its line-cap baseline row is deleted.Backwards compatibility
Compatible: every name
kiro_crew.acp.session_handlebound before is still bound or served there (test/campaign_facade_inventories/kiro_crew.acp.session_handle.json), everyAcpSessionHandlemember keeps its name, kind, coroutine shape and signature (frozen intest/test_session_handle_bindings.py), and the class keeps its module name.One accepted consequence (the G03 precedent):
inspect.getsource(AcpSessionHandle)raisesOSError, because__module__names the facade, which holds noclass AcpSessionHandlestatement. Nothing reads it; a member's source still resolves through__code__, andacp-client.mdsays where the class statement lives. On Python 3.13 and later,inspectwould instead return the facade's lines at the class's__firstlineno__; that follow-up belongs to the Python-upgrade work.Six public module-level functions leave the file's text. Each is re-imported by the facade, so its old import path resolves to the same function object:
Reader: src/kiro_crew/acp/liveness.py:mcp_launch_roster -- chat -- a comment names
session_handle.mcp_launch_roster; the facade binds the name, and test_acp_liveness_remote_flat.py imports it from the facadeReader: src/kiro_crew/acp/client_model_selection.py:parse_advertised_models -- chat -- the function-local
from kiro_crew.acp.session_handle import parse_advertised_modelsresolves through the facade's re-import (test_acp_client_session_setup.py, test_acp_runtime_models.py)Reader: src/kiro_crew/acp/client_model_selection.py:models_from_config_options -- chat -- the function-local import resolves through the facade's re-import (test_acp_codex_harness.py, test_acp_deepseek_backend_effort.py)
Reader: test/test_kas_model_select_capture.py:model_select_envelope -- chat -- imports it from the facade, which re-binds the owner's function
Reader: src/kiro_crew/acp/session_handle.py:session_models_envelope -- chat -- nothing outside the session_handle family reads it; the facade still binds it (pinned by test/campaign_facade_inventories/kiro_crew.acp.session_handle.json), and test_acp_codex_harness.py::test_both_model_readers_answer_from_one_fold exercises it through the handle's model readers
Reader: src/kiro_crew/acp/runtime.py:advertised_models_from_session -- chat -- runtime.py's module-level
from kiro_crew.acp.session_handle import (... advertised_models_from_session ...)still resolves; cron and subagent sessions run on the same runtime, and client_model_selection.py's function-local import resolves the same way (test_harness_parity.py)Tests
test/test_session_handle_bindings.py, regenerated for the full split:kiro_crew.acp.session_handleas its__module__and pickle path;parse_advertised_modelsnormalizes through the owner's_normalize_models, the function the class binds: a sentinel patched over it comes back from both input shapes;Manual verification
N/A. This is a structural move, and the unit floor below exercises every moved member. An installed-wheel import smoke of the new modules ran from a
git archiveexport.Related Issues
Part of #20192
Follow-up: #21320
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Move audit
Normalized audit, the G03 R5 comparator: docstrings via
inspect.cleandoc, theselfannotation dropped, a removed@staticmethodignored. Changed units:parse_advertised_models: two callsAcpSessionHandle._normalize_models(...)become_normalize_models(...), the owner's own function, which the class binds as its static method (the class is not importable from the owner at run time). Pinned bytest_the_model_parsers_normalize_through_the_function_the_class_binds._emit_tool_interrupted_sel: the docstring's "KiroCrew" becomes "Kiro Crew" (brand gate on moved prose)._SESSION_HANDLE_OWNERS,_SERVEDand theTYPE_CHECKINGmanifest: facade glue for the new owners.Edits that leave the AST unchanged:
session_handle_kas._handle_kas_session_info's andsession_handle_model_selection.set_model's "no longer describe" now read "do not describe";session_handle_model_selection.store_session_config's "a previously-stored list" now reads "an already-stored list"._emit_tool_interrupted_sel's docstring "KiroCrew" now reads "Kiro Crew" (also listed above, since a docstring is part of the normalized audit).logger.warningcall andapply_session_permission_routing'sifcondition).Glue:
EntitlementRevalidatingimport keeps its line, and itsnoqareason reads "re-exported" instead of "raised here", since the raise moved tosession_handle_model_selection.Diff alignment (L36)
git diffandgit diff --minimaladd the same lines in every changed file:.github/file-line-cap-baseline.txtdocs/system-specs/common/injected-messages.mddocs/system-specs/modules/acp-client.mddocs/system-specs/modules/agent-host-contract.mddocs/system-specs/modules/harness-parity.mddocs/system-specs/modules/metrics.mdsrc/kiro_crew/acp/kas_wire.pysrc/kiro_crew/acp/runtime.pysrc/kiro_crew/acp/session_handle.pysrc/kiro_crew/acp/session_handle_class.pysrc/kiro_crew/acp/session_handle_kas.pysrc/kiro_crew/acp/session_handle_mcp.pysrc/kiro_crew/acp/session_handle_model_selection.pysrc/kiro_crew/acp/session_handle_native_children.pysrc/kiro_crew/acp/session_handle_permissions.pysrc/kiro_crew/acp/session_handle_steering.pysrc/kiro_crew/acp/session_handle_updates.pysrc/kiro_crew/acp/session_handle_watchdog.pysrc/kiro_crew/agent_sdk/backends_mcp.pysrc/kiro_crew/agent_sdk/backends_turns.pysrc/kiro_crew/dashboard/handlers/usage.pysrc/kiro_crew/instances/constants.pysrc/kiro_crew/security_posture.pysrc/kiro_crew/session_compaction.pytest/campaign_facade_inventories/kiro_crew.acp.session_handle.jsontest/test_decisions_model_route_apply.pytest/test_deny_bounded_write.pytest/test_fallback_row_attribution_8560.pytest/test_harness_parity.pytest/test_session_handle_bindings.pytest/test_usage_blank_model_8531.pySource pins (L30 / L40(8)) and rows
test_harness_parity.pydeny-set readers (B2)test_harness_parity.pyidentity rows,_RUNTIME_PATH_MODULES(C1)_build_permission_event→ permissions,set_model/ensure_served_default→ model selection,_handle_update→ updates; the new owners and the class home join the scantest_deny_bounded_write.pySITES(C2)approve_tool's floor warning loses its sanitizer → red; an unlisted id slot in the class home → redsecurity_posture.NON_EGRESS_REDACTION_MODULES.github/file-line-cap-baseline.txtBaselined growth (L56 addendum 1b)
src/kiro_crew/security_posture.py: main 3,413 lines (row 3,181), HEAD 3,416 (+3): four exact-pathNON_EGRESS_REDACTION_MODULESrows the redactor drift guard requires, with no added comment, less the facade's row.CI path references
None. No workflow path filter or file list names
session_handle.py.Prose citations (L29)
Comment and docstring citations of where a moved construct is defined, path or name only, in place (line numbers at the merge base):
src/kiro_crew/acp/runtime.py:5:AcpSessionHandle(insession_handle.py) -> (insession_handle_class.py)src/kiro_crew/acp/runtime.py:9: the handle, protocol and exceptions live insession_handle.py/session_handle_runtime_contract.py->session_handle_class.py/session_handle_runtime_contract.pysrc/kiro_crew/acp/kas_wire.py:9: the frame handlers live in :mod:kiro_crew.acp.session_handle-> :mod:kiro_crew.acp.session_handle_kas(sub-agent frames in :mod:kiro_crew.acp.session_handle_native_children), one line longersrc/kiro_crew/agent_sdk/backends_mcp.py:290: (acp/runtime.py,acp/session_handle.py) -> (acp/runtime.py,acp/session_handle_class.py)src/kiro_crew/agent_sdk/backends_turns.py:287: (acp/session_handle.py) -> (acp/session_handle_kas.py)src/kiro_crew/session_compaction.py:615: (acp/session_handle.py) -> (acp/session_handle_kas.py)src/kiro_crew/instances/constants.py:350: _READ_PATH_PROBE_DEADLINE_SECS in acp/session_handle.py -> acp/session_handle_model_selection.pysrc/kiro_crew/dashboard/handlers/usage.py:105:session_handle.py__init__->session_handle_class.py__init__(the first PR's citation, followed to the class home)test/test_fallback_row_attribution_8560.py:39:session_handle.py:1379-1384-> (session_handle_model_selection.py,set_model)test/test_decisions_model_route_apply.py:753: backend default (acp/session_handle.py) -> (acp/session_handle_model_selection.py), re-wrapped within the same three docstring linestest/test_usage_blank_model_8531.py:154: (session_handle.py / session_provider.py) -> (session_handle_class.py / session_provider.py)acp-client.md(the owner table gains the seven owners and the class home, and the closing paragraph names where the class statement lives),harness-parity.md(H6 and H16 cells),metrics.md(two rows),injected-messages.md,agent-host-contract.md.References not edited (cost)
website/playwright/chat.spec.ts:23(_MCP_DRAIN_NO_REPORT_CEILING(6 s, src/kiro_crew/acp/session_handle.py) -> src/kiro_crew/acp/session_handle_mcp.py): a comment-only cite underwebsite/, left for the batched docs PR (L50).Logger names (L25)
The new owners that log bind
logging.getLogger("kiro_crew.acp.session_handle"), the facade's logger, as the first PR's owners do.Local gate
scripts/local-gate.py --base <merge-base> --dry-runselects more than 600 test files, so it was not run whole (SD14). The floor that ran instead is 706 test files: every file that imports, patches or namessession_handle,AcpSessionHandleorkiro_crew.acp, plus the facade, mirror, posture, line-cap and tree-scan guards. Result on this series' PR2 tree: 32,975 passed, 75 skipped, 0 failed. After the last recipe fold (one docstring citation inruntime.py, the generated declared-field set in the guard), the guard, the facade and mirror contracts, the posture, harness-parity and deny-row tests and the edited citation files were re-run: 2,080 passed, 0 failed (17 files). Mutation proofs: 16 of 16 planted mutations turn their pin red (reports/G06/mutations-pr2.txt). After the review fold (the normalizer pin made behavioural, thekas_wire.pycitation), the guard, harness parity and the mirror guards were re-run: 898 passed, 0 failed;mypy src/kiro_crew/acp/is clean (80 files). After the rebase onto the main that carries S26's_dispatch.pysplit (#21554), the guard, contracts, posture, harness-parity and deny-row tests and every test main changed that namessession_handleor_dispatchwere re-run: 4,753 passed, 0 failed (53 files); coldmypy src/kiro_crewis clean (3,101 source files). Also run on this head: coldmypy src/kiro_crewon agit archiveexport, both alone (no issues in 3,030 source files) and merged with S26's_dispatch.pysplit head (no issues in 3,038 source files); semgrep 1.78 with the CI configs and--baseline-commit(0 findings, 0 errors, no parse errors, 23 files); an installed-wheel import of all eight new modules;docs_lint, comment-history, brand, harness-parity, black, isort, flake8, subprocess-encoding, agent-sdk boundary, line-cap, take-away (sixReader:lines) and the L52check_inventory(197 names, none missing); and the L59 check against #21590's owners (the only lines this PR takes out of them are the planned_input_wait_statusmove into the watchdog owner).