feat(loops): inProcessSandboxClient — typed in-process box, no more SandboxInstance casts

[drewstone]

What

Lifts the hand-rolled offline-box pattern into a reusable substrate primitive, inProcessSandboxClient, next to inlineSandboxClient. Examples no longer cast as unknown as SandboxInstance.

Why

Four example spots each built the SAME shape by hand — a SandboxClient whose create() returns a box implementing only the subset runLoop / openSandboxRun actually call ({id, streamPrompt} + optional fs.read/write / exec / delete) — and cast it via as unknown as SandboxInstance. The cast is forced because SandboxInstance is a declare class with private fields that no object literal can structurally satisfy. The pattern already earned a substrate home once (createInProcessUiAuditClient) and is the structural sibling of inlineSandboxClient (which adapts an Executor → box). This gives the offline-box pattern its own typed home so user code never casts.

The primitive

inProcessSandboxClient({ onPrompt, workdir?, id? }) returns a properly-typed SandboxClient. The single unavoidable cast (object literal → declare class) lives inside the primitive, documented and tested.

• onPrompt(prompt, ctx) => SandboxEvent[] | AsyncIterable<SandboxEvent> — the per-turn behavior IS the box. ctx carries round (per-box turn counter), workdir, and signal.
• workdir? — opt in to a real temp-dir-backed box: fs.read/fs.write + exec over it, delete() tears it down. Omit for a pure event-only box.
• id?: string | (seq) => string — override the box id (placement demos read on a meaningful sandbox id).

Casts removed (4 spots → 0)

File	Before	After
examples/driver-loop/scripted-worker.ts	{ id, streamPrompt } as unknown as SandboxInstance	one-line onPrompt callback
examples/researcher-loop/synthetic-researcher.ts	{ id, streamPrompt } as unknown as SandboxInstance	one-line onPrompt callback
examples/fleet-delegation/fleet-delegation.ts (×2)	{ id } as unknown as SandboxInstance	inProcessSandboxClient({ id, onPrompt: () => [] })

Each example keeps its scenario script + teaching intact (driver-loop's fold, researcher-loop's namespace-leak firewall, fleet-delegation's placement tagging — meaningful ids preserved via the id override). The coding-benchmark/offline-box.ts cast is out of scope. The one correct cast inside src/runtime/inline-sandbox-client.ts (and now in-process-sandbox-client.ts) stays.

Verification

• pnpm run build / pnpm run typecheck (src + examples) / pnpm run lint — all green
• pnpm test — 116 files, 1125 passed, 2 skipped, 0 failed (incl. a new 5-case test for the primitive: end-to-end runLoop drive, round counter, workdir fs/exec + delete cleanup, id override, async-iterable stream)
• pnpm run docs:api regenerated the catalog for the new export; pnpm run docs:check green
• driver-loop + researcher-loop + fleet-delegation run offline and fire unchanged
• grep confirms 0 as unknown as SandboxInstance in the rewired example files

[tangletools]

✅ Auto-approved PR — 99057fea

Blanket team auto-approval is enabled for this reviewer service.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: blanket_auto_approve · 2026-06-24T18:09:25Z}