Repository navigation
refactor(session): compose SessionManager from session_parts owners - #21009
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Check that [DESIGN-REVIEWED] a48fb2b Description read[DESCRIPTION-READ] e04d5c75df393bc0b05c6c83a27958991e545fd728f4caa7e8f24d6d13b3067c 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 Check that the two pytest-timeout failures in the local floor run (whole-tree scans, ~45 s each, also slow on BASE) pass on CI's matrix. What this change shipsInventory (8 items) — 8 justifiedIntent: bring
[FIRST-PRINCIPLES-REVIEWED] a48fb2b Description read[DESCRIPTION-READ] bdfdcb12bbd5ae9b9ea65b4ec18a40b032413a71dd2f337fa0dcbfcbafbe2c64 That sha256 names the PR description this verdict read. Recompute it with |
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: |
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: |
d347b46 to
fb37eba
Compare
fb37eba to
613d409
Compare
613d409 to
22c46b7
Compare
22c46b7 to
2a4a77b
Compare
Sensitive change review
|
|
Rebased: this head (
Upstream changes to
|
Sensitive Change ReviewSensitive files changed:
|
|
|
HOLD at 2a4a77b. This is a policy hold. I found no defect. The move checks out. I compared Why it waits for a human: the diff edits a sandbox file ( — crew-pr-reviewer (r107) |
2a4a77b to
7684b52
Compare
Sensitive change review
|
|
Rebased: this head ( Upstream changes to
Main's |
session.py was 4,103 lines, over the 2,000-line cap, and kept growing because every SessionManager delegation, state view and constant lived in one file. It is now a 1,181-line facade over eleven owner modules in src/kiro_crew/session_parts/. Each member body moves verbatim into its owner as a function whose first parameter is self, and the class binds it by name; each state view is a StateProperty the owner builds from the same getter and setter. Module-level helpers and constants move to policy, provider_probes and record. kiro_crew._facade_mirror keeps the patch surface whole: a patch through kiro_crew.session reaches every owner that reads the name, and a derived __all__ keeps the star-import set. session.py keeps the code that reads the ACP layer (the agent-SDK boundary forbids it in a new file), the two members that name SessionManager itself and the two listener setters. Owners log on the kiro_crew.session logger and moved classes keep that module name. test/test_session_bindings.py pins the frozen member inventory, owner identity, the state views against BASE, the binding constraints and the mirror. Source-reading tests are re-pointed or joined to the owners with their assertions unchanged; specs, RFC citations and source comments name the new homes; the file's line-cap and docs-lint rows are pruned. Part of #20192
7684b52 to
a48fb2b
Compare
Sensitive change review
|
|
Rebased: this head ( |
|
|
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approved by a maintainer. The triage automation held this on a size, path, category or move-check rule only; every review lane is clean.
Problem / Motivation
Goal: Bring
src/kiro_crew/session.pyfrom 4,088 lines to 1,186 under the 2,000-line cap, with every caller, patch target and behaviour ofSessionManagerunchanged.session.pyheldSessionManager(a 2,786-line class) plus the module helpers and constants around it. The class was already a delegating facade oversession_allocation,session_lifecycle,session_cleanup,session_compaction,session_poolandsession_background, but every delegation, state view and constant still lived in one file, so the file kept growing past the cap.Why it matters
The repository rule is that no hand-written file exceeds 2,000 lines (
scripts/check_file_line_cap.py).session.pywas 4,088 lines with 18 commits in seven days, so every session change landed in an oversized file that reviewers and agents read in pieces.Not a goal
session_allocation.py,session_lifecycle.py,session_map.py,session_pid.py,session_storage.py,session_ledger.py); other campaign scopes own them.SessionManagermember, module-level name or patch target.session.py; the agent-SDK boundary keeps them there.What changed (motivation → approach → change)
session.pyis too large for one module, but tests patch its globals and the class's members in about 450 places, so the import path, patch seams and member set have to stay exactly as they are.The split follows the binding shape
acp/client.pyalready uses. Each member body moves verbatim into an owner module undersrc/kiro_crew/session_parts/as a function whose first parameter isself: SessionManager, and the class binds it by name. A state view becomes aStateProperty(a typedproperty) the owner builds from the same getter and setter. Module-level helpers and constants move to three owners, andsession.pyimports back every name its own code reads.kiro_crew._facade_mirrorkeeps the patch surface whole: a patch throughkiro_crew.sessionreaches every owner that reads the name.session_parts/)policyprovider_probesClaudeCodeProvidersentinelrecord_Session,FirstTurnState, queued temp-file cleanupstate_viewsclaimsget_or_create, the ending fence, admission, queueruntimesturn_contextlinksconfig_applyteardownsweepssession.pykeeps the code that reads the ACP layer, because no new file may import it:__init__,_allocation_deps,_lifecycle_deps, the lazy ACP loaders and the four members that call them. It also keeps the two members that nameSessionManageritself and the two listener setters whose bodies call same-named functions. The docstring's compaction and process-sweep sections move to the owners they describe. The session spec names each owner.Backwards compatibility
Compatible: every BASE module-level name still resolves on
kiro_crew.sessionto the same object (pinned bytest/test_campaign_facades_base_public_names.py), everySessionManagermember keeps its kind, coroutine-ness and signature (pinned bytest/test_session_bindings.py), andmonkeypatch/mock.patchthrough the facade reaches every owner (test/test_facade_mirror_guards.py).Reader: src/kiro_crew/dashboard/chat_runner.py:process_shutdown_requested -- chat --
kiro_crew.sessionstill binds it (imported back fromsession_parts.claims); the same object, pinned by test_campaign_facades_base_public_namesReader: src/kiro_crew/dashboard/chat_turn/turn_marker.py:process_shutdown_requested -- chat -- reads chat_runner's re-export, which is the same object
Reader: src/kiro_crew/dashboard/handlers/mcp.py:process_shutdown_requested -- crew page -- imports it from
kiro_crew.session, which binds itReader: src/kiro_crew/slack/events.py:unlink_queued_temp_paths -- chat -- imports it from
kiro_crew.session, which binds it (imported back fromsession_parts.record)Reader: src/kiro_crew/session_allocation.py:unlink_queued_temp_paths -- chat -- reached through
AllocationDeps, whichSessionManager._allocation_depsstill builds insession.pyTests
test/test_session_bindings.py(new): the frozen member inventory (287 members: kind, coroutine, signature digest, owner) and identity with each owner's object; each state view is a realpropertywhose docstring and accessor bodies digest-equal BASE's;getattr_staticandcreate_autospecread the class as at BASE; no bound body needs its class (super(),__class__, mangling); no owner imports the facade at run time; owners import lowest layer first; each owner's docstring names the fields it reads and writes (aself.__dict__["<f>"]key counts as field<f>); owners log underkiro_crew.session; moved classes keepkiro_crew.sessionas__module__; the mirror serves exactly the moved names the facade does not read; a patch through the facade reaches the owner and is undone;from kiro_crew.session import *binds BASE's 138 names. Every structural scan has a self-test. 410 cases, green in 5 shuffled-order runs at-n0and in the-n 3floor run.-n 3with coverage: 22,185 passed, 2 failed. Both failures are pytest-timeout (120 s) on whole-tree scans under coverage and host load:test_app_backend_composition_contract.py::TestPatchSpellings::test_no_test_patches_a_forwarded_name_with_create_trueandtest_sync_io_in_async_gate.py::TestReportMode::test_report_runs_and_covers_the_baselined_files. Each passes alone (48.7 s and 36.3 s here; 45.4 s and 32.5 s on BASE). Another 182 tree-scanning test files: 12,580 passed.scripts/local-gate.py --dry-runselects 3,234 backend and 1,374 frontend files, so the floor runs instead and CI owns the full matrix.test_app_slot_ownership,test_reinjection_gate,test_turn_ceiling,test_decisions_compaction_hook,test_channel_transport_outbound_authz,test_pid_reader_ratchet,test_process_identity_structural,test_agent_import_hoist,test_agent_sdk_backend_identity,test_autocompact_default,test_session_provider_liveness.test/campaign_facade_inventories/kiro_crew.session.json(new):kiro_crew.session's 115 BASE public names and the 100 it binds again by import, whichtest/test_campaign_facades_base_public_names.pychecks resolve to the same objects.Move audit
Every unit the audit lists as
changedis binding re-plumbing: the member's body is the same AST, itsselfparameter is annotatedSessionManager, and@property/@x.setter/@staticmethodgive way to the class binding (x = _owner.x,StateProperty(_get_x, _set_x),staticmethod(_owner.f)). A normalized audit that applies exactly that re-plumbing finds 397 of the 399 BASE units unchanged (95.63% of lines). The two left over:session_parts.turn_contextandsession_parts.sweepsdocstrings, and a pointer stays;_companion_runtime_pids: its docstring drops a commit reference (rewords below).Rewords on moved text, for the comment-history gate:
# itself may no longer fit.→# itself may not fit.;Since the AcpRuntime unify (commit 0bf3b85a) every runtime records its→Every AcpRuntime records its; theClaudeCodeProvidersentinel's comment says in present tense that Claude Code is driven through the ACP adapter.Logger: every owner logs on
logging.getLogger("kiro_crew.session"), the original module's logger, because about 40caplogsites filter on that name. The moved classes_Session,FirstTurnState,_CompactCallbackand_RecycleCallbackkeep__module__ == "kiro_crew.session".Layout: an owner package,
src/kiro_crew/session_parts/(it has an__init__.py). The cross-platform added-line scan finds no POSIX-only primitive on the moved lines.L36: git's default diff and
--minimaladd the same lines in all 53 changed files,src/kiro_crew/session.pyincluded (473 and 473). The facade's class body lists the binding block and the two kept listener setters (set_unbind_listener,set_bind_listener, bodies unchanged) between_lifecycle_depsand__init__, and imports the mirror asimport kiro_crew._facade_mirror as _facade_mirror: with main'ssession.pyabove 4,096 lines git's default diff otherwise re-shows the head of the kept__init__, and this layout is the one a measured search of 248 variants found that keeps both diffs equal (re-measured on every rebase).Non-move position edits (L36), all in
session.py's glue, bodies unchanged: the two kept listener settersset_unbind_listenerandset_bind_listenersit before__init__instead of at the end of the class, the binding block follows_lifecycle_deps, and one blank line in the mirror tail is gone. Why: git's xdiff marks a line as multi-matching once it occurs more often than a limit that doubles from 64 to 128 when the older file passes 4,096 lines; main'ssession.pyis now 4,103 lines, so its blank lines enter the comparison and the default diff otherwise mis-pairs the head of__init__.Source pins and citations
Re-pointed or joined, assertions unchanged, each proven by a mutation of the construct in its new home that turns the test red:
test/test_app_slot_ownership.pysession_parts/turn_context.py(2 sites)test/test_reinjection_gate.py_IMPLEMENTERSnamessession_parts/turn_context.pytest/test_turn_ceiling.pyEXEMPTkeysession_parts/claims.pytest/test_decisions_compaction_hook.pysession_parts/turn_context.pytest/test_channel_transport_outbound_authz.py("session_parts/links.py", "set_mirror_link")test/test_pid_reader_ratchet.pysession.pyrow split intosession_parts/claims.py+session_parts/provider_probes.py(total 144 unchanged)test/test_process_identity_structural.pyREAPER_MODULES; the pid-collection allowlist key issession_parts/runtimes.pytest/test_agent_import_hoist.py_HOISTED_FILEStest/test_agent_sdk_backend_identity.py,test/test_autocompact_default.py,test/test_session_provider_liveness.pyProse citations corrected (path or symbol only):
src/kiro_crew/session_pid.py(2),session_cleanup.py(2),session_token_sig.py,pycache_gc.py,sandbox_argv.py(thecleanup_stale_sandbox_profilesdocstring), and the rootconftest.pydocstring of_isolate_sandbox_mount_source_roots; and in docs,session.md,slack-gateway.md,resource-protection.md,learn-cron-dashboard.md,security.md,metrics.md,heartbeat.md,session-control.md,agent-host-contract.md,tool-stall-watchdog-placement.md, seven RFCs and the RFC index. Thesession.py:NNNline citations among them become symbol names, and their docs-lintline-refrows are pruned.Baselines (own rows only, by hand):
.github/file-line-cap-baseline.txtdrops thesession.pyrow, and.github/docs-lint-baseline.txtdrops the tenline-refrows of the rewritten citations.The one cite first relayed to a live scope,
sandbox_argv.py's "periodic cleanup sweep in session.py", is corrected here now that its scope has finished.CI path references
None. No workflow path filter or explicit file list names
session.py. Outside CI logic,AUTOSDE.yaml'sharness-parityrule gains the pathsrc/kiro_crew/session_parts/*.pynext tosrc/kiro_crew/session.py.Manual verification
N/A — a structural move with no behaviour change; the unit floor below covers it.
Related Issues
Part of #20192
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)