@tangle-network/agent-provider-tangle 0.14.1 → 0.14.3

package/README.md

@@ -1,19 +1,19 @@
 # @tangle-network/agent-provider-tangle
 
 Wraps `@tangle-network/sandbox` as an `AgentEnvironmentProvider`.
-The peer range is `>=0.33.1 <1.0.0`, and this package is developed and tested against 0.33.1.
-The floor is 0.33.1 because workspace branching uses the keyed snapshot, fork,
+The peer range is `>=0.34.0 <1.0.0`, and this package is developed and tested against 0.34.3.
+The floor is 0.34.0 because workspace branching uses the keyed snapshot, fork,
 lookup, and cleanup operations added to that SDK.
 The provider fails closed when the configured backend or its catalog entry cannot be read.
 Newer SDKs may also provide `getBackend()` as a lookup over the same catalog.
 
 ```ts
-import { Sandbox } from '@tangle-network/sandbox'
-import { createTangleProvider } from '@tangle-network/agent-provider-tangle'
+import { Sandbox } from "@tangle-network/sandbox";
+import { createTangleProvider } from "@tangle-network/agent-provider-tangle";
 
 const provider = createTangleProvider({
   client: new Sandbox({ apiKey: process.env.TANGLE_API_KEY }),
-})
+});
 ```
 
 Detached dispatch returns the immutable Sandbox execution receipt in `controlRef`.
@@ -43,16 +43,16 @@ One provider reaches deployments of different ages, which is why the environment
 
 Each deployment flag this adapter reads gates the claims it backs, and no flag is read that gates nothing:
 
-| Deployment flag | Claims it gates |
-| --- | --- |
-| `dispatch.runControlRef` | `streaming.detach`, `streaming.turnIdempotency`, `sessions.continue`, `retainedControl`, `session.cancelRun` |
+| Deployment flag                   | Claims it gates                                                                                              |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `dispatch.runControlRef`          | `streaming.detach`, `streaming.turnIdempotency`, `sessions.continue`, `retainedControl`, `session.cancelRun` |
 | `dispatch.executionIdOnAdmission` | `streaming.detach`, `streaming.turnIdempotency`, `sessions.continue`, `retainedControl`, `session.cancelRun` |
-| `cancel.canonicalRunCancellation` | `sessions.continue`, `retainedControl`, `session.cancelRun` |
-| `cancel.digestBound` | `sessions.continue`, `retainedControl`, `session.cancelRun` |
-| `cancel.idempotent` | `sessions.continue`, `retainedControl`, `session.cancelRun` |
-| `runs.eventReplay` | `streaming.replay`, `sessions.continue`, `retainedControl`, `session.cancelRun` |
-| `runs.executionScopedStatus` | `sessions.continue`, `retainedControl`, `session.cancelRun` |
-| `interactions.responseDedupe` | `interactions`, `environment.respondToInteraction`, `session.respondToInteraction` |
+| `cancel.canonicalRunCancellation` | `sessions.continue`, `retainedControl`, `session.cancelRun`                                                  |
+| `cancel.digestBound`              | `sessions.continue`, `retainedControl`, `session.cancelRun`                                                  |
+| `cancel.idempotent`               | `sessions.continue`, `retainedControl`, `session.cancelRun`                                                  |
+| `runs.eventReplay`                | `streaming.replay`, `sessions.continue`, `retainedControl`, `session.cancelRun`                              |
+| `runs.executionScopedStatus`      | `sessions.continue`, `retainedControl`, `session.cancelRun`                                                  |
+| `interactions.responseDedupe`     | `interactions`, `environment.respondToInteraction`, `session.respondToInteraction`                           |
 
 Detached dispatch carries the caller's exact reference and refuses a receipt that does not name the execution back, so it needs both `dispatch` flags and a session handle to reach the run through.
 `sessions.continue`, `retainedControl`, and `session.cancelRun` need every flag in the table, because the capability schema refuses a partial retained-control block and each identity rests on its own flag.
@@ -70,19 +70,19 @@ The claim and the two methods stand or fall together.
 It is offered on the environment and on a session handle; the environment routes the command to the session its binding names.
 The command carries only the answer the caller supplied. No field is filled in on the caller's behalf, and an answer the outstanding ask's spec rejects is refused with the field named.
 
-| Result | Acknowledgement status |
-| --- | --- |
-| The deployment recorded and delivered the response | `accepted` |
-| The deployment already holds this exact response | `already_resolved_same` |
+| Result                                                        | Acknowledgement status                                           |
+| ------------------------------------------------------------- | ---------------------------------------------------------------- |
+| The deployment recorded and delivered the response            | `accepted`                                                       |
+| The deployment already holds this exact response              | `already_resolved_same`                                          |
 | The deployment already holds a different response for the ask | `already_resolved_different`, message naming the recorded digest |
-| The command names another provider, environment, or session | `binding_mismatch` |
-| The deployment refuses the binding | `binding_mismatch` |
-| The ask is unknown to the deployment | `unknown_interaction` |
-| The session is unknown to the deployment | `unknown_run` |
-| The ask left the outstanding set on a deadline | `expired` |
-| The ask's spec rejects the answer | `invalid_response`, message naming each field |
-| The response is recorded and delivery is unconfirmed | `transport_failure`, `retryable: true` |
-| The request did not reach the route | `transport_failure`, `retryable: true` |
+| The command names another provider, environment, or session   | `binding_mismatch`                                               |
+| The deployment refuses the binding                            | `binding_mismatch`                                               |
+| The ask is unknown to the deployment                          | `unknown_interaction`                                            |
+| The session is unknown to the deployment                      | `unknown_run`                                                    |
+| The ask left the outstanding set on a deadline                | `expired`                                                        |
+| The ask's spec rejects the answer                             | `invalid_response`, message naming each field                    |
+| The response is recorded and delivery is unconfirmed          | `transport_failure`, `retryable: true`                           |
+| The request did not reach the route                           | `transport_failure`, `retryable: true`                           |
 
 A refusal is never reported as a success, and a recorded response whose delivery the deployment does not confirm is never reported as `accepted`.
 
@@ -150,24 +150,24 @@ Clean branch resources before deleting the source or use a platform reaper.
 import {
   workspaceCheckpointRequestDigest,
   workspaceForkRequestDigest,
-} from '@tangle-network/agent-interface'
+} from "@tangle-network/agent-interface";
 
 const checkpoint = await environment.workspaceBranching?.checkpoint({
   source: exactRun,
-  idempotencyKey: 'checkpoint-before-analysis',
+  idempotencyKey: "checkpoint-before-analysis",
   requestDigest: workspaceCheckpointRequestDigest({ source: exactRun }),
-})
+});
 
-if (checkpoint?.status === 'created' || checkpoint?.status === 'replayed') {
+if (checkpoint?.status === "created" || checkpoint?.status === "replayed") {
   const fork = await environment.workspaceBranching?.fork({
     checkpoint: checkpoint.checkpoint,
-    placement: { kind: 'sandbox', sandboxId: 'analysis-worker' },
-    idempotencyKey: 'analysis-worker',
+    placement: { kind: "sandbox", sandboxId: "analysis-worker" },
+    idempotencyKey: "analysis-worker",
     requestDigest: workspaceForkRequestDigest({
       checkpoint: checkpoint.checkpoint,
-      placement: { kind: 'sandbox', sandboxId: 'analysis-worker' },
+      placement: { kind: "sandbox", sandboxId: "analysis-worker" },
     }),
-  })
+  });
 }
 ```
 
@@ -192,7 +192,7 @@ const provider = createTangleProvider({
   client: new Sandbox({ apiKey: process.env.TANGLE_API_KEY }),
   confidentialAttestationVerifier: async ({ report, attestation }) =>
     (await verifyTangleQuote({ report, attestation })) ?? null,
-})
+});
 ```
 
 The provider stores the raw report in `ConfidentialAttestation.quote` through
@@ -208,19 +208,19 @@ reports before verification.
 Every surface carries a freshness discriminator, so a value the Sandbox SDK does not report is visibly absent instead of arriving as a measured zero.
 The `observation` capability flag for a surface is true only when a source can put a value on it for that environment; the observation itself always carries the surface, with `unavailable` and its reason when there is nothing to report.
 
-| Surface | Sandbox source | State when the source is missing |
-| --- | --- | --- |
-| `identity` | provider name and `box.id` | always known |
-| `lifecycle.status` | `box.status` after a refresh | `stale` with the refresh failure |
-| `lifecycle.cleanup` | `box.expiresAt` as a scheduled retirement | omitted from the lifecycle value |
-| `endpoint` | scheme, host, and explicit port of `connection.runtimeUrl` | `unavailable` |
-| `placement.verified` | `client.describePlacement(box)` | `unavailable` |
-| `resources.requested` | the `create()` resource request | omitted on an environment rebuilt by id |
-| `resources.effective` | cgroup `memoryLimitMb` and the attached GPU lease | `unavailable` |
-| `resourceUse.current` / `peak` | cgroup `memoryCurrentMb` / `memoryPeakMb` | `unavailable` |
-| `modelUsage` | the newest execution this handle measured | `unavailable` |
-| `computeBilling` | the GPU lease's billed or estimated customer cost | `unavailable` |
-| `accountUsage` | `client.subscription()` and `client.usage()` | `unavailable` |
+| Surface                        | Sandbox source                                             | State when the source is missing        |
+| ------------------------------ | ---------------------------------------------------------- | --------------------------------------- |
+| `identity`                     | provider name and `box.id`                                 | always known                            |
+| `lifecycle.status`             | `box.status` after a refresh                               | `stale` with the refresh failure        |
+| `lifecycle.cleanup`            | `box.expiresAt` as a scheduled retirement                  | omitted from the lifecycle value        |
+| `endpoint`                     | scheme, host, and explicit port of `connection.runtimeUrl` | `unavailable`                           |
+| `placement.verified`           | `client.describePlacement(box)`                            | `unavailable`                           |
+| `resources.requested`          | the `create()` resource request                            | omitted on an environment rebuilt by id |
+| `resources.effective`          | cgroup `memoryLimitMb` and the attached GPU lease          | `unavailable`                           |
+| `resourceUse.current` / `peak` | cgroup `memoryCurrentMb` / `memoryPeakMb`                  | `unavailable`                           |
+| `modelUsage`                   | the newest execution this handle measured                  | `unavailable`                           |
+| `computeBilling`               | the GPU lease's billed or estimated customer cost          | `unavailable`                           |
+| `accountUsage`                 | `client.subscription()` and `client.usage()`               | `unavailable`                           |
 
 Four quantities have no Sandbox source at all, and the adapter reports them as absent rather than deriving them.
 There is no effective CPU or disk figure anywhere in the SDK, so `resources.effective` carries memory and the accelerator only.
@@ -266,16 +266,16 @@ Set `teamId` inside `exactProcess` to scope create, lookup, and recovery to one
 const provider = createTangleProvider({
   client: new Sandbox({ apiKey: process.env.TANGLE_API_KEY }),
   exactProcess: {},
-})
+});
 
 const environment = await provider.exactProcess!.create({
-  image: 'ghcr.io/acme/agent@sha256:<64-hex-manifest-digest>',
-  egress: { mode: 'blocked' },
+  image: "ghcr.io/acme/agent@sha256:<64-hex-manifest-digest>",
+  egress: { mode: "blocked" },
   maxLifetimeMs: 120_000,
   resources: { cpu: 1, memoryMb: 1024, diskMb: 1024 },
-  metadata: { executionId: 'run-1' },
-  idempotencyKey: 'run-1',
-})
+  metadata: { executionId: "run-1" },
+  idempotencyKey: "run-1",
+});
 ```
 
 The adapter rejects ordinary sandboxes during create, recovery, and list operations.

package/dist/tangle-failure-reason.js

@@ -23,9 +23,12 @@ function failureCause(error) {
     if (name === "TimeoutError")
         return "timed out";
     const status = httpStatus(detail.status);
+    const code = bareIdentifier(detail.code);
+    if (status !== undefined && code !== undefined) {
+        return `HTTP ${status}; code ${code}`;
+    }
     if (status !== undefined)
         return `HTTP ${status}`;
-    const code = bareIdentifier(detail.code);
     if (code !== undefined)
         return `code ${code}`;
     // A bare `Error` names no cause beyond the message, which is never carried.

package/dist/tangle-interactive.d.ts

@@ -10,8 +10,8 @@ export interface TangleInteractiveAgentRegistry {
 /**
  * Test the linked SDK surface without accepting any older interactive shape.
  *
- * The current public Sandbox release fails this test. That is intentional:
- * it has no receipt, control claim, or mutation acknowledgement protocol.
+ * Sandbox owns the exact reference, control claim, terminal binding, and
+ * mutation acknowledgements. An older handle shape fails this test closed.
  */
 export declare function sandboxBacksInteractiveAgent(box: SandboxInstanceLike): boolean;
 /**

package/dist/tangle-interactive.js

@@ -1,21 +1,20 @@
-import { AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStatusSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionStopAcknowledgementMatchesCommand, canonicalCandidateDigest, exactAgentInteractiveSessionStart, } from "@tangle-network/agent-interface";
-import { parseBackendType } from "@tangle-network/sandbox";
+import { AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStatusSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, TerminalReplayWindowSchema, TerminalSessionRefSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionStatusMatchesRef, agentInteractiveSessionStopAcknowledgementMatchesCommand, canonicalCandidateDigest, exactAgentInteractiveSessionStart, } from "@tangle-network/agent-interface";
 import { assertOptionKeys } from "./tangle-environment-validation.js";
 import { transportFailureReason } from "./tangle-failure-reason.js";
-import { bindTangleInteractiveControl, closeTangleStreamQuietly, createTangleTerminalStreamCapture, prepareTangleTerminalAttachment, } from "./tangle-terminal.js";
 /**
  * Test the linked SDK surface without accepting any older interactive shape.
  *
- * The current public Sandbox release fails this test. That is intentional:
- * it has no receipt, control claim, or mutation acknowledgement protocol.
+ * Sandbox owns the exact reference, control claim, terminal binding, and
+ * mutation acknowledgements. An older handle shape fails this test closed.
  */
 export function sandboxBacksInteractiveAgent(box) {
     if (typeof box.session !== "function")
         return false;
     try {
-        const candidate = box.session("__tangle-interactive-probe__").interactive?.();
-        return (isSandboxInteractiveSession(candidate) &&
-            typeof box.terminals?.get === "function");
+        const candidate = box
+            .session("__tangle-interactive-probe__")
+            .interactive?.();
+        return isSandboxInteractiveSession(candidate);
     }
     catch {
         return false;
@@ -29,9 +28,9 @@ export function sandboxBacksInteractiveAgent(box) {
  * never creates a second record for any of those facts.
  */
 export function createTangleInteractiveAgentRegistry(box, providerName, environmentId) {
-    const exactHandle = (sessionId) => {
+    const exactHandle = (sessionId, binding) => {
         const session = box.session?.(sessionId);
-        const candidate = session?.interactive?.();
+        const candidate = session?.interactive?.(binding);
         if (!isSandboxInteractiveSession(candidate)) {
             throw new Error("the linked Sandbox SDK does not expose the exact interactive control API");
         }
@@ -50,10 +49,13 @@ export function createTangleInteractiveAgentRegistry(box, providerName, environm
             throw new Error("the Sandbox returned a different interactive session ref");
         }
     };
-    const assertControl = (ref, control) => {
+    const assertControlMatchesRef = (ref, control) => {
         if (!agentInteractiveSessionControlClaimMatchesRef(ref, control)) {
             throw new Error("the interactive control claim belongs to another process");
         }
+    };
+    const assertActiveControl = (ref, control) => {
+        assertControlMatchesRef(ref, control);
         if (Date.parse(control.expiresAt) <= Date.now()) {
             throw new Error("the interactive control claim has expired");
         }
@@ -62,70 +64,68 @@ export function createTangleInteractiveAgentRegistry(box, providerName, environm
         async start(request, options) {
             assertOptionKeys(options, ["signal"], "Tangle interactive agent start");
             const exactRequest = exactAgentInteractiveSessionStart(request);
-            const requestedHarness = exactRequest.profile.harness;
-            if (requestedHarness === undefined) {
+            if (exactRequest.profile.harness === undefined) {
                 throw new Error("interactive agent sessions require AgentProfile.harness");
             }
-            let harness;
-            try {
-                harness = parseBackendType(requestedHarness);
-            }
-            catch {
-                throw new Error("the requested AgentProfile harness has no Tangle Sandbox runner");
-            }
             options?.signal?.throwIfAborted();
             const handle = exactHandle(exactRequest.run.sessionId);
             let observed;
             try {
-                observed = await handle.start({
-                    harness,
-                    ...(exactRequest.profile.model?.default === undefined
-                        ? {}
-                        : { model: exactRequest.profile.model.default }),
-                    ...(exactRequest.cwd === undefined ? {} : { cwd: exactRequest.cwd }),
-                    ...(exactRequest.cols === undefined ? {} : { cols: exactRequest.cols }),
-                    ...(exactRequest.rows === undefined ? {} : { rows: exactRequest.rows }),
-                    profile: exactRequest.profile,
-                    ...(exactRequest.initialPrompt === undefined
-                        ? {}
-                        : { initialPrompt: exactRequest.initialPrompt }),
-                    idempotencyKey: exactRequest.run.runId,
-                    requestDigest: exactRequest.run.requestDigest,
-                });
+                observed = await handle.start(exactRequest, options);
             }
             catch (error) {
                 options?.signal?.throwIfAborted();
                 throw new Error(transportFailureReason("interactive start", error));
             }
             options?.signal?.throwIfAborted();
-            const ref = refFromStart(exactRequest, observed);
+            const ref = AgentInteractiveSessionRefSchema.parse(observed.ref);
+            const control = AgentInteractiveSessionControlClaimSchema.parse(observed.control);
             if (!agentInteractiveSessionRefMatchesStart(exactRequest, ref)) {
                 throw new Error("the Sandbox returned an interactive session with a different admission receipt");
             }
+            assertControlMatchesRef(ref, control);
+            if (observed.state === "running")
+                assertActiveControl(ref, control);
+            if (observed.state === "running" && observed.streamUrl.length === 0) {
+                throw new Error("the Sandbox returned a running session without a stream");
+            }
             return ref;
         },
         get(value) {
             const ref = exactRef(value);
-            const handle = exactHandle(ref.run.sessionId);
+            const handle = exactHandle(ref.run.sessionId, { ref });
+            const mutationHandle = (control) => exactHandle(ref.run.sessionId, { ref, control });
             const readStatus = async (options) => {
                 assertOptionKeys(options, ["signal"], "Tangle interactive agent status");
                 options?.signal?.throwIfAborted();
                 let observed;
                 try {
-                    observed = await handle.status();
+                    observed = await handle.status(options);
                 }
                 catch (error) {
                     options?.signal?.throwIfAborted();
                     throw new Error(transportFailureReason("interactive status", error));
                 }
                 options?.signal?.throwIfAborted();
-                return statusFromSandbox(ref, observed);
+                if (observed === null) {
+                    return AgentInteractiveSessionStatusSchema.parse({
+                        state: "unknown",
+                        ref,
+                        message: "the Sandbox no longer knows this interactive agent session",
+                        retryable: false,
+                    });
+                }
+                const status = AgentInteractiveSessionStatusSchema.parse(observed);
+                if (!agentInteractiveSessionStatusMatchesRef(ref, status)) {
+                    throw new Error("the Sandbox reported a different interactive agent session identity");
+                }
+                return status;
             };
             const validateControl = async (control, options) => {
-                assertControl(ref, control);
+                assertActiveControl(ref, control);
                 options?.signal?.throwIfAborted();
                 try {
-                    await handle.validateControl(control);
+                    await mutationHandle(control).validateControl(control, options);
                 }
                 catch (error) {
                     options?.signal?.throwIfAborted();
@@ -142,7 +142,7 @@ export function createTangleInteractiveAgentRegistry(box, providerName, environm
                     options?.signal?.throwIfAborted();
                     let raw;
                     try {
-                        raw = await handle.claimControl(exactRequest);
+                        raw = await handle.claimControl(exactRequest, options);
                     }
                     catch (error) {
                         options?.signal?.throwIfAborted();
@@ -160,59 +160,33 @@ export function createTangleInteractiveAgentRegistry(box, providerName, environm
                     assertOptionKeys(options, ["signal"], "Tangle interactive agent attach");
                     const exactRequest = AgentInteractiveSessionAttachSchema.parse(request ?? {});
                     await validateControl(exactRequest.control, options);
-                    const before = await readStatus(options);
-                    if (before.state !== "running") {
-                        throw new Error("the exact interactive agent session is not running");
-                    }
-                    const terminals = box.terminals;
-                    if (terminals === undefined || typeof terminals.get !== "function") {
-                        throw new Error("the Sandbox client cannot read exact interactive terminal metadata");
-                    }
-                    const capture = createTangleTerminalStreamCapture(exactRequest);
-                    let stream;
+                    let terminal;
                     try {
-                        stream = await handle.attach({
-                            control: exactRequest.control,
-                            ...(exactRequest.cols === undefined ? {} : { cols: exactRequest.cols }),
-                            ...(exactRequest.rows === undefined ? {} : { rows: exactRequest.rows }),
-                            handlers: capture.handlers,
-                        });
+                        terminal = await mutationHandle(exactRequest.control).attachAgentTerminal(exactRequest, options);
                     }
                     catch (error) {
                         options?.signal?.throwIfAborted();
                         throw new Error(transportFailureReason("interactive attach", error));
                     }
-                    if (options?.signal?.aborted) {
-                        await closeTangleStreamQuietly(stream);
-                        options.signal.throwIfAborted();
-                    }
-                    const prepared = await prepareTangleTerminalAttachment({
-                        stream,
-                        capture,
-                        terminals,
-                        parentExecutionId: ref.run.executionId,
-                        expectedSessionId: ref.run.sessionId,
-                        signal: options?.signal,
-                        beforeMutation: (operation) => {
-                            if (operation === "detach")
-                                return Promise.resolve();
-                            return validateControl(exactRequest.control, options);
-                        },
-                    });
-                    if (prepared.status === "unknown") {
-                        throw new Error(prepared.message);
-                    }
-                    if (prepared.acknowledgement.restored !== true) {
-                        await prepared.session.detach();
-                        throw new Error("the exact interactive attach did not restore the coding-agent PTY");
+                    try {
+                        options?.signal?.throwIfAborted();
+                        const returnedControl = AgentInteractiveSessionControlClaimSchema.parse(terminal.control);
+                        const returnedRef = TerminalSessionRefSchema.parse(terminal.ref);
+                        TerminalReplayWindowSchema.parse(terminal.cursors);
+                        if (canonicalCandidateDigest(returnedControl) !==
+                            canonicalCandidateDigest(exactRequest.control) ||
+                            returnedRef.terminalSessionId !== ref.run.sessionId ||
+                            returnedRef.parentExecutionId !== ref.run.executionId ||
+                            returnedRef.expiresAt !== exactRequest.control.expiresAt ||
+                            !returnedRef.isRunning) {
+                            throw new Error("the Sandbox returned a terminal with a different interactive identity");
+                        }
                     }
-                    const after = await readStatus(options);
-                    if (after.state !== "running") {
-                        await prepared.session.detach();
-                        throw new Error("the exact interactive agent exited while its terminal attached");
+                    catch (error) {
+                        await terminal.detach().catch(() => undefined);
+                        throw error;
                     }
-                    const terminal = bindTangleInteractiveControl(prepared.session, exactRequest.control);
-                    return terminal;
+                    return validatedTerminal(terminal, exactRequest.control, validateControl, ref);
                 },
                 async sendPrompt(command, options) {
                     assertOptionKeys(options, ["signal"], "Tangle interactive agent prompt");
@@ -221,7 +195,7 @@ export function createTangleInteractiveAgentRegistry(box, providerName, environm
                     await validateControl(exactCommand.control, options);
                     let raw;
                     try {
-                        raw = await handle.sendPrompt(exactCommand);
+                        raw = await mutationHandle(exactCommand.control).sendPrompt(exactCommand, options);
                     }
                     catch (error) {
                         options?.signal?.throwIfAborted();
@@ -241,7 +215,7 @@ export function createTangleInteractiveAgentRegistry(box, providerName, environm
                     await validateControl(exactCommand.control, options);
                     let raw;
                     try {
-                        raw = await handle.stop(exactCommand);
+                        raw = await mutationHandle(exactCommand.control).stop(exactCommand, options);
                     }
                     catch (error) {
                         options?.signal?.throwIfAborted();
@@ -266,62 +240,43 @@ function isSandboxInteractiveSession(value) {
         "start",
         "claimControl",
         "status",
-        "attach",
+        "attachAgentTerminal",
         "validateControl",
         "sendPrompt",
         "stop",
     ].every((key) => typeof candidate[key] === "function");
 }
-function refFromStart(request, observed) {
-    if (observed.sessionId !== request.run.sessionId ||
-        observed.harness !== request.profile.harness) {
-        throw new Error("the Sandbox returned a different interactive session identity");
-    }
-    return AgentInteractiveSessionRefSchema.parse({
-        run: request.run,
-        preparationReceipt: observed.preparationReceipt,
-        incarnationId: observed.incarnationId,
-        startedAt: observed.startedAt,
-    });
-}
-function statusFromSandbox(ref, observed) {
-    if (observed === null) {
-        return AgentInteractiveSessionStatusSchema.parse({
-            state: "unknown",
-            ref,
-            message: "the Sandbox no longer knows this interactive agent session",
-            retryable: false,
-        });
-    }
-    const observedRef = AgentInteractiveSessionRefSchema.parse({
-        run: { ...ref.run, sessionId: observed.sessionId },
-        preparationReceipt: observed.preparationReceipt,
-        incarnationId: observed.incarnationId,
-        startedAt: observed.startedAt,
-    });
-    if (observed.harness !== ref.preparationReceipt.harness ||
-        !sameExactSessionRef(ref, observedRef)) {
-        throw new Error("the Sandbox reported a different interactive agent session identity");
-    }
-    if (observed.state === "running") {
-        if (observed.streamUrl.length === 0) {
-            throw new Error("the Sandbox reported a running session without a stream");
-        }
-        return AgentInteractiveSessionStatusSchema.parse({ state: "running", ref });
-    }
-    return AgentInteractiveSessionStatusSchema.parse({
-        state: "exited",
-        ref,
-        endedAt: observed.endedAt,
-        reason: observed.reason,
-        ...(Number.isSafeInteger(observed.exitCode)
-            ? { exitCode: observed.exitCode }
-            : {}),
-        ...(typeof observed.exitSignal === "string" && observed.exitSignal.length > 0
-            ? { exitSignal: observed.exitSignal }
-            : {}),
-    });
+function validatedTerminal(terminal, control, validate, expectedRef) {
+    const boundControl = Object.freeze({ ...control });
+    return {
+        get ref() {
+            const ref = TerminalSessionRefSchema.parse(terminal.ref);
+            if (ref.terminalSessionId !== expectedRef.run.sessionId ||
+                ref.parentExecutionId !== expectedRef.run.executionId) {
+                throw new Error("the Sandbox terminal changed its interactive session identity");
+            }
+            return ref;
+        },
+        get cursors() {
+            return TerminalReplayWindowSchema.parse(terminal.cursors);
+        },
+        control: boundControl,
+        async input(input, options) {
+            await validate(boundControl, options);
+            await terminal.input(input, options);
+        },
+        async resize(resize, options) {
+            await validate(boundControl, options);
+            await terminal.resize(resize, options);
+        },
+        detach: (options) => terminal.detach(options),
+        async close(options) {
+            await validate(boundControl, options);
+            return terminal.close(options);
+        },
+        events: (options) => terminal.events(options),
+    };
 }
 function sameExactSessionRef(expected, candidate) {
-    return canonicalCandidateDigest(expected) === canonicalCandidateDigest(candidate);
+    return (canonicalCandidateDigest(expected) === canonicalCandidateDigest(candidate));
 }