feat(runtime): compose steerable provider sessions

[drewstone]

Summary

• Opt-in provider steering delegates to the existing createSteerableSandboxSession; the low-level one-shot provider executor is unchanged.
• Steering mode requires the exact AgentProfile.harness and fails loudly on a missing harness or a conflicting AgentSpec.harness / provider default backend — no silent backend fallback.
• Turn aborts call the active AgentSession.cancel(), and provider-specific stream/cancel failures become the existing interrupt signal so a forced steer can re-plan.
• Exact AgentProfile identity, provider options, normalized events, usage fields, live progress, and trace data survive the adapter boundary; the one-shot executor path keeps provider-owned backend defaults.
• Providers must declare live streaming and session continuation — and expose environment.session() — before this mode creates an environment.

No new agent loop or provider-specific coordinator is introduced.

Proof

• Focused provider/session checks: 47/47 (environment-provider.test.ts, sandbox-events.test.ts)
• Full tests: 2,079 passed, 6 skipped (rebased onto current main)
• Lint: 513 files
• TypeScript and examples: pass
• Package build, exports, publint, attw, edge checks: pass
• Generated API reference and freshness check: pass
• git merge-tree --write-tree origin/main HEAD: clean

Retained risk

The package has no configured third-party environment provider, so the live network-provider check remains an integration responsibility; the PR proves the public Interface 0.39 contract with exact provider events and session controls.

@tangle-network/agent-provider-cli-bridge@0.2.33 advertises continuation but does not expose environment.session(), so this mode rejects it before creation. @tangle-network/agent-provider-tangle@0.4.5 exposes the required session controls; adding them to the CLI-bridge provider is a separate upstream change.

[tangletools]

✅ Auto-approved drewstone PR — d046ca71

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: drewstone_author · 2026-08-01T00:28:10Z}

[tangletools]

🟢 Value Audit — sound

Verdict	sound
Concerns	0 (none)
Heuristic	0.0s
Duplication	0.0s
Interrogation	86.6s (2 bridge agents)
Total	86.6s

💰 Value — error

value agent produced no parseable value-audit JSON.

• Model: opencode/deepseek/deepseek-v4-pro
• Bridge attempts: 3
• Bridge error: opencode/kimi-for-coding/k2p7: bridge stream ended without value-audit content; opencode/zai-coding-plan/glm-5.2: Bridge returned 503: {"error":{"message":"cli-bridge admission timed out after 30000ms","type":"admission_rejected","reason":"queue_timeout","admission":{"active":20,"queued":4,"maxActive":20,"maxQueue":48}}}; opencode/deepseek/deepseek-v4-pro: Bridge returned 503: {"error":{"message":

🎯 Usefulness — sound

Opt-in provider steering composes the existing steerable sandbox session loop through the existing SandboxClient adapter — no new loop, fail-loud preconditions, plus a real reasoning-token usage fix.

• Integration: Reachable through the public createExecutor({ backend: 'provider', provider, steering }) branch (src/runtime/supervise/runtime.ts:1667). createExecutor is the single built-in factory, registered in the executor registry (runtime.ts:1752) and consumed throughout the runtime. The new branch reuses providerAsSandboxClient (environment-provider.ts:187) and sandboxExecutor's steering mode (runt
• Fit with existing patterns: Fits the established grain precisely. createExecutor is explicitly 'backend as data' (runtime.ts:1622), and the provider backend already had a one-shot path via providerAsExecutor. The sandbox-session.ts header (lines 11-22) states the design goal: ONE steerable session shape shared across runtimes (sandbox + cli-bridge). This extends that same shape to providers by adapting the provider to
• Real-world viability: Error paths are handled and tested. Pre-creation capability gate checks streaming.live + sessions.continue before any environment is made (environment-provider.ts:212-219); post-creation session() absence triggers destroy-then-throw (environment-provider.ts:221-226, tested at environment-provider.test.ts:527). Harness conflicts and missing harness throw before probing/creating (runtime.ts:17
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 1

No concerns — sound change, no better or existing approach found. ✅

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260801T003002Z}