3. modularize session context

[kevinjosethomas]

• Moves compaction, refinement, and continuation state and cleanup out of AgentSession into six focused modules under src/session/. AgentSession falls from 11,028 to 8,990 lines and keeps public coordination. Stacked on 2. modularize session runtime #2185; tracks ENG-5938.
• Preserves existing persistence, event, cancellation, and continuation ordering. Self and automatic refinement still dispatch through public session wrappers; custom reviewers retain their receiver and promise timing. No protocol or format change.
• Validation: 794 tests across 35 files, npm run check, and git diff --check pass at d1fba70304e4a1af1000e32ff13986ba649458a6. Independent static review verified the refinement corrections. Separate Astra Prime Sandbox validation and benchmarks must assess this exact head against dc66f163d1a7e809e962f649f2825f4b857d2b48; earlier 71bf evidence is diagnostic. Macroscope skipped the earlier review because of its cost cap.

Note

Modularize AgentSession into compaction, refinement, and continuation owners

• Extracts SessionCompaction, SessionRefinement, AutoRefinement, RefinementExecution, SessionContinuation, and performSessionCompaction into dedicated modules under packages/coding-agent/src/session/, each with its own host interface
• Replaces in-class state machines and local fields in agent-session.ts with delegation to the new owner instances, passing host callbacks for model access, persistence, event emission, and scheduling
• Adds harness-digest generation at cold context boundaries using merged refinement harness state and available tools/skills
• Migrates all test suites to use the new nested owner paths (refinement.execution, refinement.auto, compaction, continuation) instead of flat private fields, and adds boundary/regression tests for ownership, cancellation, and ordering
• Risk: AgentSession no longer exposes flat internal fields like in-flight refinement promises or compaction abort controllers; out-of-tree tests or integrations reading those private paths will break. The RefineSkippedError and CompactionSkippedError types are re-exported from new module locations

^{Macroscope summarized 827d1d4.}

---

Note

High Risk
Large move of concurrency-sensitive compaction, refinement, and continuation logic; regressions in cancellation, ordering, or persistence would affect core agent turns without changing the public API surface much.

Overview
Pulls compaction, refinement, and post-compaction continuation out of AgentSession into dedicated session/ owners, wired through typed host callbacks for model/auth, persistence, extensions, scheduling, and events. AgentSession now composes SessionCompaction, SessionRefinement (with AutoRefinement + execution helpers), and SessionContinuation, and delegates public methods like compact(), refine(), host compact.* / refine.* requests, and threshold checks instead of keeping large private state machines inline.

Behavior is intended to stay the same: manual/automatic compaction lifecycle, overflow recovery, semantic-edge ordering before transcript commit, serialized vs interactive auto-refine, and continuation settlement/cancellation rules are documented in README and implemented in the new modules (performSessionCompaction, continuation commit-fence release, refinement apply barriers). Types and events are re-exported from the new locations (CompactionReason, CompactionSkippedError, RefineSkippedError, compaction events) so external callers keep stable imports from the session facade.

Docs and tests add a session-context module map, boundary preservation notes, and coverage pointers for owner-level lifecycle tests.

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

[macroscopeapp]

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

This review would cost an estimated $11.06, 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	123.38KB	$6.17
packages/coding-agent/src/session/refinement.ts	34.30KB	$1.72
packages/coding-agent/src/session/compaction.ts	19.56KB	$0.98

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]

Stale Bugbot comment from a previous run.

[github-actions]

Prime Agent performance — completed

PR 827d1d4b compared with main 1eee2938.

Overall: 0 regressed · 0 improved · 17 no clear change.

Metric	Main	This PR	Change
Cold startup	3,133.3 ms	3,178.9 ms	≈ +45.6 ms (+1.46%)
Warm startup	1,857.8 ms	1,912.7 ms	≈ +54.9 ms (+2.96%)
Installation	30.19 s	31.34 s	≈ +1.15 s (+3.80%)
Compressed release artifacts	11.12 MB	11.15 MB	≈ +0.03 MB (+0.30%)
Installed footprint	597.49 MB	597.67 MB	≈ +0.18 MB (+0.03%)
Idle memory, summed RSS	1,124.97 MB	1,155.84 MB	≈ +30.86 MB (+2.74%)

Python runtime

Metric	Main	This PR	Change
Python kernel startup	121.7 ms	127.3 ms	≈ +5.6 ms (+4.63%)
Python cell round trip	0.546 ms	0.500 ms	≈ -0.046 ms (-8.41%)
Empty bash command	11.5 ms	11.2 ms	≈ -0.2 ms (-1.87%)
Bash git status	17.1 ms	17.2 ms	≈ +0.066 ms (+0.39%)
Bash 32 KiB output	11.3 ms	11.9 ms	≈ +0.5 ms (+4.69%)
35 cells / 9 shell calls	160.7 ms	178.2 ms	≈ +17.4 ms (+10.84%)
Python interrupt to done	1.379 ms	1.466 ms	≈ +0.087 ms (+6.33%)
Python state snapshot	25.6 ms	25.8 ms	≈ +0.2 ms (+0.68%)
Python state restore	345.1 ms	365.2 ms	≈ +20.1 ms (+5.82%)
Python idle RSS	35.20 MB	35.76 MB	≈ +0.56 MB (+1.60%)
Python RSS after pandas workload	97.28 MB	98.37 MB	≈ +1.08 MB (+1.11%)

Sandbox cost: ~$0.0954 — no inference calls.
Run, logs, and downloadable raw results

Methodology and samples

Main resolved at 2026-09-10T23:42:51.727337+00:00. Harness 1eee2938.
Linux x64, 4 vCPU, 8 GB RAM, 20 GB disk; region us.
Image: node:24-bookworm@sha256:be23f54a88d34e8824c741b19b91064094f92c1c97b194144bfc8b50d67258e2.
Stock tools, skills, daemon, and Python bootstrap enabled; fresh homes and a fixed Git fixture.
Onboarding is dismissed; the editor starts without a selected model or submitted prompt.
Medians shown. Arrows require a 20% timing/memory change plus absolute floors and IQR.
These practical noise floors are not a statistical significance test.
Cold means stopped Prime processes; OS filesystem caches are not flushed.
No model requests or credentials. Installation excludes build/setup time.
Installer tarballs use loopback; npm/Python downloads use the network with fresh caches.
Artifact size counts release tarballs; footprint after first use includes registry packages.
MB is decimal. Summed RSS can double-count shared pages; PSS is recorded when available.
Provisioning, setup, and build durations are recorded separately in the raw results.
Kernel probes use the installed JSONL runtime, outside the TUI/TypeScript host.
Per trial: 50 Python cells, 5 calls per shell case, and one 35-cell mix (9 git status calls).
Cell/shell values are batch means; other runtime timings are single operations.
State fixture: a 10,000-row × 8-column integer DataFrame and a 10,000-integer list.
Restore runs in a fresh kernel, including pandas imports; kernel startup is excluded.
Kernel RSS covers the isolated Python process; loaded RSS follows the pandas workload.
Costs estimate full sandbox lifetimes at configured rates, including setup and build.
Budget target: $1; not a billing cap. Checks are informational.

Metric	Main successful/attempted	PR successful/attempted	Main spread	PR spread
Cold startup	10/10	10/10	IQR 124.2 ms	IQR 77.2 ms
Warm startup	10/10	10/10	IQR 59.9 ms	IQR 111.4 ms
Installation	3/3	3/3	range 0.73 s	range 1.03 s
Compressed release artifacts	1/1	1/1	—	—
Installed footprint	1/1	1/1	—	—
Idle memory, summed RSS	10/10	10/10	IQR 128.32 MB	IQR 31.08 MB
Python kernel startup	10/10	10/10	IQR 5.0 ms	IQR 6.8 ms
Python cell round trip	10/10	10/10	IQR 0.071 ms	IQR 0.058 ms
Empty bash command	10/10	10/10	IQR 1.2 ms	IQR 0.9 ms
Bash git status	10/10	10/10	IQR 1.9 ms	IQR 3.0 ms
Bash 32 KiB output	10/10	10/10	IQR 0.5 ms	IQR 1.5 ms
35 cells / 9 shell calls	10/10	10/10	IQR 13.4 ms	IQR 19.8 ms
Python interrupt to done	10/10	10/10	IQR 0.106 ms	IQR 0.266 ms
Python state snapshot	10/10	10/10	IQR 2.9 ms	IQR 2.1 ms
Python state restore	10/10	10/10	IQR 13.7 ms	IQR 31.7 ms
Python idle RSS	10/10	10/10	IQR 3.76 MB	IQR 5.13 MB
Python RSS after pandas workload	10/10	10/10	IQR 3.78 MB	IQR 5.08 MB

[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 827d1d4. Configure here.}

[cursor]

Internal type re-exported without consumers

Low Severity

SerializedBackgroundPlanResult is re-exported from AgentSession after the move, but nothing outside SessionRefinement and its tests imports that type. AutoRefineReviewer still needs a public export; this internal plan result does not.

 

^{Triggered by project rule: Review rules}

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