4. modularize child and kernel lifecycle

[kevinjosethomas]

• moves child lifecycle, usage accounting, tools, extensions, and kernel resources into twelve focused modules with explicit ownership.
• preserves public dispatch, cancellation, and teardown ordering; stacks on 3. modularize session context #2190 and tracks eng-5939.
• 415 tests and repository checks pass; independent review is clear, with exact-revision prime sandbox validation continuing.

---

Note

Medium Risk
Large refactor of session teardown, child cancellation/publication ordering, and kernel replacement gates; regressions would affect orchestration and billing attribution even though behavior is intended to be preserved.

Overview
AgentSession is slimmed down by delegating RLM child orchestration, IPython kernel provisioning, tool registry/ACP MCP handling, and extension reload/bindings to dedicated session/* owners (SessionChildren, SessionChildState, SessionChildUsage, SessionKernel, KernelEnvironment, SessionTools, SessionExtensions, plus child-run, child-projection, and kernel-host-handlers).

Public entry points (runRlmChild, listRlmSubagents, dispose/disposeAsync, tool APIs, reload, ACP MCP replace/release) stay on AgentSession but forward to those owners with the same teardown ordering called out in the README (children complete before kernel disposal; usage flushes at the parent event boundary).

Child spawn/admission, deletion retries, quiescence waits, usage attribution, and snapshot/list projections move out of the monolith into launchChildTask and SessionChildren, while depth/max-depth, parent-reply state, and recap updates live in SessionChildState. Kernel host handlers are composed via createSessionKernelHostHandlers instead of a large inline map in AgentSession.

The package README gains Child agent lifecycle and Tools, extensions, and kernel resources sections documenting file responsibilities and invariants, plus pointers to new test/session/ and regression coverage.

^{Reviewed by Cursor Bugbot for commit b7a44e8. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Modularize child and kernel lifecycle into dedicated session modules

• Extracts AgentSession's child lifecycle, kernel, tool, extension, and usage management into dedicated facade classes under packages/coding-agent/src/session/.
• AgentSession now delegates runtime building, disposal, child orchestration, and prompt rebuilding to SessionKernel, SessionTools, SessionExtensions, SessionChildren, SessionChildState, and SessionChildUsage.
• Updates existing regression and characterization tests to use the new facades and prototype spies rather than direct private-field mutation, and adds new boundary test suites for the extracted modules.
• Risk: SessionChildState.parseDepth now throws a named validation error for invalid non-negative-integer depth configurations instead of accepting them. KernelEnvironment conditionally injects a Serper API key only when the websearch skill is loaded and no inherited environment variable exists.

^{Macroscope summarized b7a44e8.}

[macroscopeapp]

Macroscope skipped reviewing this pull request. Per-review cost limit exceeded (workspace setting).

This review would cost an estimated $14.22, which exceeds your per-review limit of $10.00.

The top 3 files driving up this estimate:

File	Diff Size	Estimate
packages/coding-agent/src/core/agent-session.ts	149.73KB	$7.49
packages/coding-agent/src/session/children.ts	40.99KB	$2.05
packages/coding-agent/src/session/tools.ts	16.02KB	$0.80

Tip

To get this pull request reviewed, you can:

1. Comment @macroscope-app on this PR to request a manual review (monthly spend limits still apply).
2. Exclude the file(s) above from review by adding a pattern to your .macroscope/ignore.md — note that creating this file replaces Macroscope's built-in default ignores rather than extending them.
3. Raise your cost limit in your workspace billing settings.

^{Turn off this reminder going forward}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f43cc8e. Configure here.}

[github-actions]

Prime Agent performance — running

PR b7a44e8a compared with main 5255a6b8.

Benchmarking the latest PR commit. Results will appear here when this run finishes.

Run, logs, and downloadable raw results