[refactor] Make sandbox-agent orchestration readable

[mmabrouk]

Context

The sandbox-agent engine had become difficult to change safely. Its 2,144-line entrypoint owned the public API, request policy, daemon setup, environment acquisition, session lifecycle, event routing, per-turn approval handling, tracing, usage, and teardown. A reviewer had to understand nearly the whole runtime to change one phase.

The surrounding modules also erased stable SDK and remote-sandbox contracts to any, and the session pool mixed pure continuation identity policy with mutable lifecycle state.

Changes

The entrypoint is now a 32-line public facade. Cold-run composition lives in a 59-line engine module, while environment setup, environment acquisition, per-turn execution, runtime contracts, connection policy, and session event routing have explicit owners.

Before:

sandbox_agent.ts (2,144 lines)
  public exports + policy + setup + acquire + turn + teardown

After:

sandbox_agent.ts          public facade
sandbox_agent/engine.ts   cold acquire -> turn -> destroy composition
environment-setup.ts      ownership, mount signing, plan, daemon env
environment.ts            resource acquisition and session lifecycle
run-turn.ts               one prompt/approval/trace/usage turn
runtime-contracts.ts      shared dependency and lifecycle contracts
runtime-policy.ts         credentials, connection, model, transport policy
session-events.ts         session-lifetime event demultiplexing

Continuation fingerprints and credential epochs now live in session-identity.ts; session-pool.ts focuses on mutable capacity, timers, checkout, parking, and teardown. Remote helpers use narrow filesystem and process ports. ACP compatibility payloads and usage JSON are narrowed at runtime instead of crossing the runner as unchecked values.

No API, wire, or runtime behavior changes are intended. Production changes remain inside the runner.

How to review

1. Start with sandbox_agent.ts and sandbox_agent/engine.ts to see the public surface and cold-run lifecycle.
2. Read environment-setup.ts, then environment.ts, to follow setup and session-scoped resource acquisition.
3. Read run-turn.ts for the per-turn prompt, approval, relay, tracing, usage, and continuity flow.
4. Review runtime-contracts.ts, runtime-policy.ts, and session-events.ts as the seams shared by those workflows.
5. Finish with session-identity.ts, the smaller session-pool.ts, and the typed boundary changes in the helper modules.

Tests / notes

• pnpm run typecheck
• pnpm test (66 files, 1,015 tests)
• pnpm run build:extension
• TypeScript unused-symbol scan on every extracted module
• git diff --check

[vercel]

@mmabrouk is attempting to deploy a commit to the agenta projects Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 34b02f7f-c8ca-49c1-9170-e876e20dbdb9

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

🤖 The AI agent says:

This draft is ready for structural review. Please focus on whether the new facade, setup, environment, turn, contract, policy, and event boundaries make the runtime easier to follow without changing lifecycle behavior.