@tangle-network/agent-provider-tangle 0.6.2 → 0.6.3

package/README.md

@@ -13,8 +13,9 @@ const provider = createTangleProvider({
 
 Detached dispatch returns the immutable Sandbox execution receipt in `controlRef`.
 The adapter validates its complete capability document and omits optional environment methods whose capabilities are disabled.
-Reconstruct an exact session with `environment.session(reference.id, { controlRef: reference.controlRef })`; replay cursors are exclusive at the agent interface even though the Sandbox stream is inclusive.
+Reconstruct an exact session with `environment.session(reference.id, { controlRef: reference.controlRef })`; replay cursors are exclusive at both the agent interface and Sandbox session stream.
 Result, replay, and cancel operations select that exact execution instead of whichever execution most recently changed the shared session.
+Retained control is advertised only when the Sandbox exposes dispatch, replay, exact results and events, turn idempotency, and `cancelRun`; native continuation remains absent.
 After `session.prompt()` admits another turn, that session object's `controlRef` advances only when Sandbox returns the requested execution ID; a mismatched receipt fails without advancing local state.
 Sandbox keeps execution identifiers optional for older or unproven service paths, so this adapter fails closed when a dispatch or prompt does not return one and never falls back to latest-session state.
 Sessions reconstructed without a control reference may start a new prompt, but result lookup, cancellation, and cursor replay fail before calling Sandbox because those operations could otherwise select the newest unrelated execution.

package/dist/tangle-capabilities.d.ts

@@ -20,6 +20,7 @@ export interface SandboxCapabilitySupport {
     fork: boolean;
     placement: boolean;
     destroy: boolean;
+    cancelRun: boolean;
 }
 export declare function sandboxCapabilitySupport(box: SandboxInstanceLike, client: SandboxClientLike): SandboxCapabilitySupport;
 /**
@@ -28,6 +29,8 @@ export declare function sandboxCapabilitySupport(box: SandboxInstanceLike, clien
  * A client without placement metadata cannot satisfy placement(), and this
  * adapter has no durable branching, interaction, or native-continuation
  * implementation regardless of an overly broad configured document.
+ * Per-sandbox retained-run claims are narrowed later, after a concrete
+ * session handle proves that cancelRun is available.
  */
 export declare function capabilitiesForClient(declared: AgentEnvironmentCapabilities, client: SandboxClientLike): AgentEnvironmentCapabilities;
 /**

package/dist/tangle-capabilities.js

@@ -33,6 +33,7 @@ export function defaultTangleSandboxCapabilities(harness) {
         streaming: { live: true, replay: true, detach: true, turnIdempotency: true },
         // A Sandbox session id is not a Braid context-boundary proof. Native
         // continuation stays unavailable until this adapter can verify one.
+        // Retained control stays opt-in until a concrete session exposes cancelRun.
         sessions: { continue: false, list: false, messages: false },
         workspace: { read: true, write: true, exec: true, git: false, upload: true, download: true },
         branching: { checkpoint: false, fork: false },
@@ -43,7 +44,19 @@ export function defaultTangleSandboxCapabilities(harness) {
         confidential: false,
     };
 }
+const CAPABILITY_PROBE_SESSION_ID = "__tangle-capability-probe__";
 export function sandboxCapabilitySupport(box, client) {
+    let session;
+    if (typeof box.session === "function") {
+        try {
+            // Sandbox session handles are lazy. Inspecting one does not call the
+            // service, and keeps retained-control claims tied to the actual handle.
+            session = box.session(CAPABILITY_PROBE_SESSION_ID);
+        }
+        catch {
+            // A client that cannot produce a session handle cannot prove retained control.
+        }
+    }
     return {
         dispatchPrompt: typeof box.dispatchPrompt === "function",
         session: typeof box.session === "function",
@@ -54,6 +67,7 @@ export function sandboxCapabilitySupport(box, client) {
         fork: typeof box.fork === "function",
         placement: typeof client.describePlacement === "function",
         destroy: typeof box.delete === "function",
+        cancelRun: typeof session?.cancelRun === "function",
     };
 }
 /**
@@ -62,8 +76,11 @@ export function sandboxCapabilitySupport(box, client) {
  * A client without placement metadata cannot satisfy placement(), and this
  * adapter has no durable branching, interaction, or native-continuation
  * implementation regardless of an overly broad configured document.
+ * Per-sandbox retained-run claims are narrowed later, after a concrete
+ * session handle proves that cancelRun is available.
  */
 export function capabilitiesForClient(declared, client) {
+    const canReconstructRetainedEnvironment = typeof client.get === "function";
     const narrowed = {
         ...declared,
         streaming: {
@@ -72,7 +89,12 @@ export function capabilitiesForClient(declared, client) {
             detach: declared.streaming.detach,
             turnIdempotency: declared.streaming.turnIdempotency,
         },
-        sessions: { ...declared.sessions, continue: false, list: false, messages: false },
+        sessions: {
+            ...declared.sessions,
+            continue: declared.sessions.continue && canReconstructRetainedEnvironment,
+            list: false,
+            messages: false,
+        },
         workspace: { ...declared.workspace, git: false },
         usage: false,
         branching: {
@@ -86,7 +108,8 @@ export function capabilitiesForClient(declared, client) {
         placement: declared.placement && typeof client.describePlacement === "function",
     };
     delete narrowed.interactions;
-    delete narrowed.retainedControl;
+    if (!canReconstructRetainedEnvironment)
+        delete narrowed.retainedControl;
     delete narrowed.nativeContinuation;
     return narrowed;
 }
@@ -98,9 +121,17 @@ export function capabilitiesForClient(declared, client) {
  */
 export function capabilitiesForSandbox(declared, support) {
     const narrowed = { ...declared };
+    const supportsRetainedControl = declared.sessions.continue &&
+        declared.streaming.detach &&
+        declared.streaming.replay &&
+        declared.streaming.turnIdempotency &&
+        support.dispatchPrompt &&
+        support.session &&
+        support.cancelRun;
     delete narrowed.interactions;
-    delete narrowed.retainedControl;
     delete narrowed.nativeContinuation;
+    if (!supportsRetainedControl)
+        delete narrowed.retainedControl;
     return {
         ...narrowed,
         streaming: {
@@ -111,7 +142,7 @@ export function capabilitiesForSandbox(declared, support) {
         },
         sessions: {
             ...declared.sessions,
-            continue: false,
+            continue: declared.sessions.continue && supportsRetainedControl,
             list: false,
             messages: false,
         },

package/dist/tangle-environment-control.d.ts

@@ -1,6 +1,9 @@
 import type { AgentSessionRef, AgentTurnInput } from "@tangle-network/agent-interface/environment-provider";
 import type { SandboxInstanceLike, SandboxSessionLike } from "./tangle-types.js";
-export declare function sessionPromptRequestDigest(input: AgentTurnInput, provider: string, environmentId: string, sessionId: string, executionId: string): `sha256:${string}`;
+export declare function sessionPromptRequestDigest(input: AgentTurnInput, provider: string, environmentId: string, sessionId: string, options?: {
+    executionId?: string;
+    nonce?: string;
+}): `sha256:${string}`;
 export declare function hasReplayPayload(input: AgentTurnInput): boolean;
 export declare function interruptAfterAbort(box: SandboxInstanceLike, reference: AgentSessionRef): Promise<void>;
 export declare function interruptExecutionAfterAbort(source: SandboxInstanceLike | SandboxSessionLike, sessionId: string, executionId: string): Promise<void>;

package/dist/tangle-environment-control.js

@@ -1,10 +1,13 @@
 import { canonicalCandidateDigest } from "@tangle-network/agent-interface";
-export function sessionPromptRequestDigest(input, provider, environmentId, sessionId, executionId) {
+export function sessionPromptRequestDigest(input, provider, environmentId, sessionId, options = {}) {
     return canonicalCandidateDigest({
         provider,
         environmentId,
         sessionId,
-        executionId,
+        ...(options.executionId === undefined
+            ? {}
+            : { executionId: options.executionId }),
+        ...(options.nonce === undefined ? {} : { nonce: options.nonce }),
         ...(input.turnId === undefined ? {} : { turnId: input.turnId }),
         ...(input.prompt === undefined ? {} : { prompt: input.prompt }),
         ...(input.parts === undefined ? {} : { parts: input.parts }),
@@ -25,6 +28,11 @@ export function hasReplayPayload(input) {
         input.providerOptions !== undefined);
 }
 export async function interruptAfterAbort(box, reference) {
+    const metadata = reference.metadata;
+    // A duplicate dispatch receipt identifies work owned by another caller.
+    // Only a receipt that proves this call admitted new work may be interrupted.
+    if (metadata?.dispatched !== true || metadata.alreadyExisted === true)
+        return;
     const sessionId = reference.id;
     const executionId = reference.controlRef?.executionId;
     if (!box.session || executionId === undefined)

package/dist/tangle-environment-dispatch.js

@@ -1,23 +1,61 @@
-import { AgentTurnInputSchema } from "@tangle-network/agent-interface";
-import { executionIdFromTurnInput, promptFromTurnInput, promptOptionsFromTurnInput, } from "./tangle-prompt.js";
-import { retainedSessionControlRef, sessionRefFromSandboxDispatch } from "./tangle-session-control.js";
+import { AgentExactRunControlRefSchema, AgentTurnInputSchema, } from "@tangle-network/agent-interface";
+import { promptFromTurnInput, promptOptionsFromTurnInput, } from "./tangle-prompt.js";
+import { retainedSessionControlRef, sessionPromptExecutionId, sessionPromptSessionId, sessionRefFromSandboxDispatch, } from "./tangle-session-control.js";
 import { awaitWithSignal } from "./tangle-contract-safety.js";
 import { interruptAfterAbort, sessionPromptRequestDigest, } from "./tangle-environment-control.js";
 export function dispatchEnvironmentRun(box, provider, environmentId) {
     return async (input) => {
         AgentTurnInputSchema.parse(input);
         input.signal?.throwIfAborted();
-        const expectedSessionId = input.sessionId ?? input.controlRef?.sessionId;
-        const promise = box.dispatchPrompt?.(promptFromTurnInput(input), promptOptionsFromTurnInput(input, { provider, environmentId }));
+        const callerControlRef = input.controlRef === undefined
+            ? undefined
+            : AgentExactRunControlRefSchema.parse(input.controlRef);
+        if (callerControlRef !== undefined) {
+            if (callerControlRef.provider !== provider ||
+                callerControlRef.environmentId !== environmentId) {
+                throw new Error("Tangle control reference does not match this environment");
+            }
+            if (input.sessionId !== undefined &&
+                input.sessionId !== callerControlRef.sessionId) {
+                throw new Error("Tangle sessionId conflicts with the control reference");
+            }
+            if (input.executionId !== undefined &&
+                input.executionId !== callerControlRef.executionId) {
+                throw new Error("Tangle executionId conflicts with the control reference");
+            }
+        }
+        const expectedSessionId = input.sessionId ??
+            callerControlRef?.sessionId ??
+            sessionPromptSessionId(provider, environmentId, input.turnId);
+        if (expectedSessionId === undefined) {
+            throw new Error("Tangle detached dispatch requires an exact sessionId or turnId");
+        }
+        const exactInput = { ...input, sessionId: expectedSessionId };
+        const requestedExecutionId = input.executionId ?? callerControlRef?.executionId;
+        const baseRequestDigest = sessionPromptRequestDigest(exactInput, provider, environmentId, expectedSessionId);
+        const expectedExecutionId = requestedExecutionId ?? sessionPromptExecutionId(baseRequestDigest);
+        const requestDigest = sessionPromptRequestDigest(exactInput, provider, environmentId, expectedSessionId, { executionId: expectedExecutionId });
+        if (callerControlRef !== undefined) {
+            if (callerControlRef.requestDigest !== requestDigest) {
+                throw new Error("Tangle prompt request digest conflicts with the control reference");
+            }
+        }
+        const runControlRef = retainedSessionControlRef(expectedSessionId, expectedExecutionId, provider, environmentId, requestDigest, callerControlRef?.runId);
+        const dispatchInput = {
+            ...exactInput,
+            executionId: expectedExecutionId,
+            controlRef: runControlRef,
+        };
+        const promise = box.dispatchPrompt?.(promptFromTurnInput(dispatchInput), promptOptionsFromTurnInput(dispatchInput, { provider, environmentId }));
         let dispatched;
         try {
             dispatched = await awaitWithSignal(promise, input.signal);
         }
         catch (error) {
-            if (input.signal?.aborted && promise) {
+            if (input.signal?.aborted && input.detach !== true && promise) {
                 void promise
                     .then((late) => {
-                    const lateRef = sessionRefFromSandboxDispatch(late, provider, environmentId, executionIdFromTurnInput(input));
+                    const lateRef = sessionRefFromSandboxDispatch(late, provider, environmentId, expectedExecutionId, requestDigest, expectedSessionId, callerControlRef);
                     return interruptAfterAbort(box, lateRef);
                 })
                     .catch(() => undefined);
@@ -26,7 +64,7 @@ export function dispatchEnvironmentRun(box, provider, environmentId) {
         }
         let reference;
         try {
-            reference = sessionRefFromSandboxDispatch(dispatched, provider, environmentId, executionIdFromTurnInput(input), undefined, expectedSessionId);
+            reference = sessionRefFromSandboxDispatch(dispatched, provider, environmentId, expectedExecutionId, requestDigest, expectedSessionId, callerControlRef);
         }
         catch (error) {
             try {
@@ -41,20 +79,12 @@ export function dispatchEnvironmentRun(box, provider, environmentId) {
             }
             throw error;
         }
-        const executionId = reference.controlRef?.executionId;
-        const requestDigest = executionId === undefined
-            ? undefined
-            : sessionPromptRequestDigest(input, provider, environmentId, reference.id, executionId);
-        const boundReference = executionId === undefined || requestDigest === undefined
-            ? reference
-            : {
-                ...reference,
-                controlRef: retainedSessionControlRef(reference.id, executionId, provider, environmentId, requestDigest),
-            };
-        if (input.signal?.aborted) {
+        const boundReference = reference;
+        if (input.signal?.aborted && input.detach !== true) {
             await interruptAfterAbort(box, boundReference);
             input.signal.throwIfAborted();
         }
+        input.signal?.throwIfAborted();
         return boundReference;
     };
 }

package/dist/tangle-environment-session.d.ts

@@ -1,4 +1,13 @@
-import type { AgentSession } from "@tangle-network/agent-interface/environment-provider";
-import type { AgentRunControlRef } from "@tangle-network/agent-interface";
+import type { AgentSession, AgentSessionRef, AgentTurnInput } from "@tangle-network/agent-interface/environment-provider";
+import type { AgentExactRunControlRef, AgentRunControlRef } from "@tangle-network/agent-interface";
+import type { SandboxEvent } from "@tangle-network/sandbox";
 import type { SandboxSessionLike } from "./tangle-types.js";
-export declare function sandboxSessionAsAgentSession(session: SandboxSessionLike, controlRef: AgentRunControlRef | undefined, provider: string, environmentId: string): AgentSession;
+type ExactExecutionEventStream = (options: {
+    sessionId: string;
+    executionId: string;
+    since?: string;
+    signal?: AbortSignal;
+    controlRef?: AgentExactRunControlRef;
+}) => AsyncIterable<SandboxEvent>;
+export declare function sandboxSessionAsAgentSession(session: SandboxSessionLike, controlRef: AgentRunControlRef | undefined, provider: string, environmentId: string, dispatch?: (input: AgentTurnInput) => Promise<AgentSessionRef>, exactExecutionEvents?: ExactExecutionEventStream): AgentSession;
+export {};

package/dist/tangle-environment-session.js

@@ -1,17 +1,45 @@
+import { randomUUID } from "node:crypto";
 import { AgentTurnInputSchema } from "@tangle-network/agent-interface";
-import { environmentEventFromSandboxEvent } from "./tangle-events.js";
+import { AgentRunCancellationAcknowledgementSchema, AgentRunCancellationRequestSchema, agentRunCancellationAcknowledgementMatchesRequest, } from "@tangle-network/agent-interface";
+import { environmentEventFromSandboxEvent, isSandboxConnectionMarker, sandboxEventIdentity, } from "./tangle-events.js";
 import { agentTurnResultFromPromptRecord, promptFromTurnInput, promptOptionsFromTurnInput, validatedSandboxPromptResult, } from "./tangle-prompt.js";
 import { retainedSessionControlRef, resolveRetainedSessionControlRef, sameRunControlRef, sessionPromptExecutionId, } from "./tangle-session-control.js";
 import { sessionStatusFromUnknown } from "./tangle-environment-values.js";
 import { awaitWithSignal, boundedIdentifier, } from "./tangle-contract-safety.js";
 import { assertOptionKeys } from "./tangle-environment-validation.js";
 import { hasReplayPayload, interruptExecutionAfterAbort, sessionPromptRequestDigest, } from "./tangle-environment-control.js";
-export function sandboxSessionAsAgentSession(session, controlRef, provider, environmentId) {
-    let activeControlRef = controlRef;
+export function sandboxSessionAsAgentSession(session, controlRef, provider, environmentId, dispatch, exactExecutionEvents) {
+    let activeControlRef = controlRef
+        ? resolveRetainedSessionControlRef(controlRef, session.id, provider, environmentId)
+        : undefined;
+    let promptInFlight = false;
+    const cancelRunMethod = session.cancelRun;
+    const cancelRun = typeof cancelRunMethod === "function"
+        ? async (request, options) => {
+            assertOptionKeys(options, ["signal"], "Tangle exact session cancellation");
+            const exactRequest = AgentRunCancellationRequestSchema.parse(request);
+            const expectedRun = activeControlRef;
+            if (expectedRun === undefined) {
+                throw new Error("Tangle exact session cancellation requires an exact run control reference");
+            }
+            if (!sameRunControlRef(exactRequest.run, expectedRun)) {
+                throw new Error("Tangle exact session cancellation targets another run, session, execution, or request");
+            }
+            options?.signal?.throwIfAborted();
+            const acknowledgement = await awaitWithSignal(cancelRunMethod.call(session, exactRequest, options?.signal ? { signal: options.signal } : undefined), options?.signal);
+            options?.signal?.throwIfAborted();
+            const exactAcknowledgement = AgentRunCancellationAcknowledgementSchema.parse(acknowledgement);
+            if (!agentRunCancellationAcknowledgementMatchesRequest(exactRequest, exactAcknowledgement) ||
+                !sameRunControlRef(exactAcknowledgement.run, expectedRun)) {
+                throw new Error("Tangle exact session cancellation returned an acknowledgement for another run, session, execution, or request");
+            }
+            return exactAcknowledgement;
+        }
+        : undefined;
     return {
         id: session.id,
         get controlRef() {
-            return activeControlRef;
+            return activeControlRef === undefined ? undefined : { ...activeControlRef };
         },
         async status(options) {
             assertOptionKeys(options, ["signal"], "Tangle session status");
@@ -36,11 +64,20 @@ export function sandboxSessionAsAgentSession(session, controlRef, provider, envi
             }
             options?.signal?.throwIfAborted();
             const seenEventIds = new Set();
-            const iterator = session.events({
-                ...(options?.since !== undefined ? { since: options.since } : {}),
-                ...(executionId !== undefined ? { executionId } : {}),
-                ...(options?.signal ? { signal: options.signal } : {}),
-            })[Symbol.asyncIterator]();
+            const useExactExecutionStream = exactExecutionEvents !== undefined && executionId !== undefined;
+            const iterator = (useExactExecutionStream
+                ? exactExecutionEvents({
+                    sessionId: session.id,
+                    executionId,
+                    ...(options?.since !== undefined ? { since: options.since } : {}),
+                    ...(options?.signal ? { signal: options.signal } : {}),
+                    ...(activeControlRef ? { controlRef: activeControlRef } : {}),
+                })
+                : session.events({
+                    ...(options?.since !== undefined ? { since: options.since } : {}),
+                    ...(executionId !== undefined ? { executionId } : {}),
+                    ...(options?.signal ? { signal: options.signal } : {}),
+                }))[Symbol.asyncIterator]();
             let completed = false;
             try {
                 while (true) {
@@ -50,16 +87,28 @@ export function sandboxSessionAsAgentSession(session, controlRef, provider, envi
                         break;
                     }
                     options?.signal?.throwIfAborted();
-                    if (options?.since !== undefined && next.value.id === options.since)
+                    if (isSandboxConnectionMarker(next.value)) {
+                        const markerIdentity = sandboxEventIdentity(next.value);
+                        if (executionId !== undefined &&
+                            markerIdentity.executionId !== undefined &&
+                            markerIdentity.executionId !== executionId) {
+                            throw new Error("Tangle exact session connection identified a different executionId");
+                        }
+                        if (markerIdentity.sessionId !== undefined &&
+                            markerIdentity.sessionId !== session.id) {
+                            throw new Error("Tangle exact session connection identified a different sessionId");
+                        }
                         continue;
+                    }
                     const converted = environmentEventFromSandboxEvent(next.value, {
                         executionId,
                         sessionId: session.id,
+                        ...(useExactExecutionStream ? { streamBound: true } : {}),
                     });
                     if (converted.id === undefined)
                         throw new Error("Tangle session event arrived without a stable id");
                     if (seenEventIds.has(converted.id))
-                        throw new Error(`Tangle session replay repeated event id ${converted.id}`);
+                        continue;
                     seenEventIds.add(converted.id);
                     options?.signal?.throwIfAborted();
                     yield converted;
@@ -82,63 +131,160 @@ export function sandboxSessionAsAgentSession(session, controlRef, provider, envi
             const resultRecord = validatedSandboxPromptResult(result);
             if (resultRecord.executionId !== expectedExecutionId)
                 throw new Error("Tangle session result did not confirm its exact executionId");
-            return agentTurnResultFromPromptRecord(resultRecord, { sessionId: session.id });
+            return agentTurnResultFromPromptRecord(resultRecord, {
+                sessionId: session.id,
+                controlRef: activeControlRef,
+            });
         },
         async prompt(input) {
             AgentTurnInputSchema.parse(input);
             input.signal?.throwIfAborted();
-            if (input.sessionId !== undefined && input.sessionId !== session.id)
-                throw new Error("Tangle sessionId conflicts with this session");
-            const requestedControlRef = resolveRetainedSessionControlRef(input.controlRef, session.id, provider, environmentId);
-            if (activeControlRef && requestedControlRef && !sameRunControlRef(activeControlRef, requestedControlRef))
-                throw new Error("Tangle prompt control reference conflicts with this session");
-            const sourceControlRef = requestedControlRef ?? activeControlRef;
-            const replay = input.lastEventId !== undefined;
-            if (replay && sourceControlRef?.executionId !== undefined && input.executionId !== undefined && input.executionId !== sourceControlRef.executionId)
-                throw new Error("Tangle replay executionId conflicts with the control reference");
-            if (replay && sourceControlRef?.requestDigest === undefined) {
-                throw new Error("Tangle replay requires an exact request digest from its control reference");
-            }
-            const executionId = replay ? input.executionId ?? sourceControlRef?.executionId : input.executionId ?? sessionPromptExecutionId(provider, environmentId, session.id, input.turnId);
-            if (executionId === undefined)
-                throw new Error("Tangle session replay requires the exact executionId from its control reference");
-            const computedRequestDigest = sessionPromptRequestDigest(input, provider, environmentId, session.id, executionId);
-            const sameExecution = sourceControlRef?.executionId === executionId;
-            if (sourceControlRef?.requestDigest !== undefined &&
-                sameExecution &&
-                (!replay || hasReplayPayload(input)) &&
-                sourceControlRef.requestDigest !== computedRequestDigest) {
-                throw new Error("Tangle prompt request digest conflicts with the control reference");
+            if (promptInFlight) {
+                throw new Error("Tangle session already has a prompt in flight");
             }
-            const requestDigest = replay || sameExecution
-                ? sourceControlRef?.requestDigest
-                : computedRequestDigest;
-            if (requestDigest === undefined) {
-                throw new Error("Tangle prompt could not establish an exact request digest");
-            }
-            const promptInput = replay
-                ? { ...input, sessionId: session.id, executionId, controlRef: sourceControlRef }
-                : { ...input, sessionId: session.id, executionId, controlRef: undefined };
+            promptInFlight = true;
             try {
-                const result = await awaitWithSignal(session.prompt(promptFromTurnInput(input), promptOptionsFromTurnInput(promptInput, { provider, environmentId, sessionId: session.id })), input.signal);
-                input.signal?.throwIfAborted();
-                const resultRecord = validatedSandboxPromptResult(result);
-                if (resultRecord.executionId !== executionId) {
-                    void interruptExecutionAfterAbort(session, session.id, executionId);
-                    throw new Error("Tangle session prompt did not confirm its exact executionId");
+                if (input.sessionId !== undefined && input.sessionId !== session.id) {
+                    throw new Error("Tangle sessionId conflicts with this session");
                 }
-                activeControlRef = retainedSessionControlRef(session.id, executionId, provider, environmentId, requestDigest);
-                return agentTurnResultFromPromptRecord(resultRecord, {
-                    sessionId: session.id,
-                    ...(input.contextTransfer ? { contextTransferRequest: input.contextTransfer } : {}),
-                    ...(input.contextTransfer ? { contextTransferRequested: true } : {}),
+                const requestedControlRef = resolveRetainedSessionControlRef(input.controlRef, session.id, provider, environmentId);
+                if (activeControlRef &&
+                    requestedControlRef &&
+                    !sameRunControlRef(activeControlRef, requestedControlRef)) {
+                    throw new Error("Tangle prompt control reference conflicts with this session");
+                }
+                if (requestedControlRef?.executionId !== undefined &&
+                    input.executionId !== undefined &&
+                    requestedControlRef.executionId !== input.executionId) {
+                    throw new Error("Tangle executionId conflicts with the control reference");
+                }
+                if (input.detach === true && input.lastEventId === undefined) {
+                    if (dispatch === undefined) {
+                        throw new Error("Tangle detached session prompt requires the sandbox dispatch primitive");
+                    }
+                    const detachedInput = {
+                        ...input,
+                        signal: undefined,
+                        controlRef: undefined,
+                        sessionId: session.id,
+                        detach: true,
+                        ...(input.turnId === undefined ? { turnId: randomUUID() } : {}),
+                    };
+                    const reference = await dispatch(detachedInput);
+                    const nextControlRef = resolveRetainedSessionControlRef(reference.controlRef, session.id, provider, environmentId);
+                    if (nextControlRef === undefined) {
+                        throw new Error("Tangle detached session dispatch returned no exact control reference");
+                    }
+                    // The admission receipt is the durability boundary. Store it before
+                    // waiting for the result so an aborted caller can reconnect later.
+                    activeControlRef = nextControlRef;
+                    const result = await awaitWithSignal(session.result({
+                        executionId: nextControlRef.executionId,
+                        ...(input.signal ? { signal: input.signal } : {}),
+                    }), input.signal);
+                    input.signal?.throwIfAborted();
+                    const resultRecord = validatedSandboxPromptResult(result);
+                    if (resultRecord.executionId !== nextControlRef.executionId) {
+                        throw new Error("Tangle detached session prompt did not confirm its exact executionId");
+                    }
+                    return agentTurnResultFromPromptRecord(resultRecord, {
+                        sessionId: session.id,
+                        controlRef: nextControlRef,
+                    });
+                }
+                const sourceControlRef = requestedControlRef ?? activeControlRef;
+                const replay = input.lastEventId !== undefined;
+                if (replay &&
+                    sourceControlRef?.executionId !== undefined &&
+                    input.executionId !== undefined &&
+                    input.executionId !== sourceControlRef.executionId) {
+                    throw new Error("Tangle replay executionId conflicts with the control reference");
+                }
+                if (replay && sourceControlRef?.requestDigest === undefined) {
+                    throw new Error("Tangle replay requires an exact request digest from its control reference");
+                }
+                const requestedExecutionId = input.executionId ?? requestedControlRef?.executionId;
+                const nonce = !replay &&
+                    input.turnId === undefined &&
+                    requestedExecutionId === undefined &&
+                    requestedControlRef === undefined
+                    ? randomUUID()
+                    : undefined;
+                const baseRequestDigest = sessionPromptRequestDigest(input, provider, environmentId, session.id, nonce === undefined ? {} : { nonce });
+                const executionId = replay
+                    ? input.executionId ?? sourceControlRef?.executionId
+                    : requestedExecutionId ?? sessionPromptExecutionId(baseRequestDigest);
+                if (executionId === undefined) {
+                    throw new Error("Tangle session replay requires the exact executionId from its control reference");
+                }
+                const explicitRequestDigest = sessionPromptRequestDigest(input, provider, environmentId, session.id, {
+                    executionId,
+                    ...(nonce === undefined ? {} : { nonce }),
                 });
-            }
-            catch (error) {
-                if (input.signal?.aborted) {
-                    void interruptExecutionAfterAbort(session, session.id, executionId);
+                if (!replay &&
+                    requestedControlRef?.requestDigest !== undefined &&
+                    requestedControlRef.requestDigest !== explicitRequestDigest) {
+                    throw new Error("Tangle prompt request digest conflicts with the control reference");
+                }
+                if (replay &&
+                    hasReplayPayload(input) &&
+                    sourceControlRef?.requestDigest !== explicitRequestDigest) {
+                    throw new Error("Tangle prompt request digest conflicts with the control reference");
                 }
-                throw error;
+                const requestDigest = replay
+                    ? sourceControlRef?.requestDigest
+                    : requestedControlRef?.requestDigest ?? explicitRequestDigest;
+                if (requestDigest === undefined) {
+                    throw new Error("Tangle prompt could not establish an exact request digest");
+                }
+                const targetControlRef = retainedSessionControlRef(session.id, executionId, provider, environmentId, requestDigest, requestedControlRef?.runId);
+                const promptInput = replay
+                    ? {
+                        ...input,
+                        sessionId: session.id,
+                        executionId,
+                        controlRef: sourceControlRef,
+                    }
+                    : {
+                        ...input,
+                        sessionId: session.id,
+                        executionId,
+                        controlRef: targetControlRef,
+                    };
+                try {
+                    const result = await awaitWithSignal(session.prompt(promptFromTurnInput(input), promptOptionsFromTurnInput(promptInput, {
+                        provider,
+                        environmentId,
+                        sessionId: session.id,
+                    })), input.signal);
+                    input.signal?.throwIfAborted();
+                    const resultRecord = validatedSandboxPromptResult(result);
+                    if (resultRecord.executionId !== executionId) {
+                        void interruptExecutionAfterAbort(session, session.id, executionId);
+                        throw new Error("Tangle session prompt did not confirm its exact executionId");
+                    }
+                    const nextControlRef = targetControlRef;
+                    activeControlRef = nextControlRef;
+                    return agentTurnResultFromPromptRecord(resultRecord, {
+                        sessionId: session.id,
+                        controlRef: nextControlRef,
+                        ...(input.contextTransfer
+                            ? { contextTransferRequest: input.contextTransfer }
+                            : {}),
+                        ...(input.contextTransfer
+                            ? { contextTransferRequested: true }
+                            : {}),
+                    });
+                }
+                catch (error) {
+                    if (input.signal?.aborted && input.detach !== true) {
+                        void interruptExecutionAfterAbort(session, session.id, executionId);
+                    }
+                    throw error;
+                }
+            }
+            finally {
+                promptInFlight = false;
             }
         },
         async cancel(options) {
@@ -152,5 +298,6 @@ export function sandboxSessionAsAgentSession(session, controlRef, provider, envi
             if (result.cancelled !== true)
                 throw new Error("Tangle sandbox did not confirm cancellation");
         },
+        ...(cancelRun ? { cancelRun } : {}),
     };
 }

package/dist/tangle-environment.js

@@ -21,6 +21,18 @@ export function sandboxInstanceAsEnvironment(box, providerName, client, declared
     }
     const support = sandboxCapabilitySupport(box, client);
     const capabilities = capabilitiesForSandbox(declaredCapabilities, support);
+    const dispatch = capabilities.streaming.detach && box.dispatchPrompt
+        ? dispatchEnvironmentRun(box, providerName, environmentId)
+        : undefined;
+    const exactExecutionEvents = (options) => box.streamPrompt("", {
+        sessionId: options.sessionId,
+        executionId: options.executionId,
+        // The execution replay endpoint owns stable event IDs. A missing cursor
+        // starts at the beginning so the caller can journal a complete run.
+        lastEventId: options.since ?? "0",
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.controlRef ? { runControlRef: options.controlRef } : {}),
+    });
     return {
         id: environmentId,
         provider: providerName,
@@ -51,6 +63,9 @@ export function sandboxInstanceAsEnvironment(box, providerName, client, declared
                     const converted = environmentEventFromSandboxEvent(next.value, {
                         executionId: expectedExecutionId,
                         sessionId: expectedSessionId,
+                        ...(expectedExecutionId !== undefined || expectedSessionId !== undefined
+                            ? { streamBound: true }
+                            : {}),
                     });
                     input.signal?.throwIfAborted();
                     yield converted;
@@ -58,6 +73,7 @@ export function sandboxInstanceAsEnvironment(box, providerName, client, declared
             }
             catch (error) {
                 if (input.signal?.aborted &&
+                    input.detach !== true &&
                     expectedSessionId !== undefined &&
                     expectedExecutionId !== undefined) {
                     void interruptExecutionAfterAbort(box, expectedSessionId, expectedExecutionId);
@@ -71,9 +87,7 @@ export function sandboxInstanceAsEnvironment(box, providerName, client, declared
             }
             input.signal?.throwIfAborted();
         },
-        ...(capabilities.streaming.detach && box.dispatchPrompt
-            ? { dispatch: dispatchEnvironmentRun(box, providerName, environmentId) }
-            : {}),
+        ...(dispatch ? { dispatch } : {}),
         ...((capabilities.sessions.continue || capabilities.streaming.replay || capabilities.streaming.detach) &&
             box.session
             ? {
@@ -89,7 +103,12 @@ export function sandboxInstanceAsEnvironment(box, providerName, client, declared
                     if (session.id !== id) {
                         throw new Error("sandbox session(id) returned an unrelated session");
                     }
-                    return sandboxSessionAsAgentSession(session, resolveRetainedSessionControlRef(options?.controlRef, id, providerName, environmentId), providerName, environmentId);
+                    const agentSession = sandboxSessionAsAgentSession(session, resolveRetainedSessionControlRef(options?.controlRef, id, providerName, environmentId), providerName, environmentId, dispatch, exactExecutionEvents);
+                    if (capabilities.sessions.continue &&
+                        typeof agentSession.cancelRun !== "function") {
+                        throw new Error("Tangle retained session support requires SandboxSession.cancelRun");
+                    }
+                    return agentSession;
                 },
             }
             : {}),

package/dist/tangle-events.d.ts

@@ -1,6 +1,14 @@
 import type { SandboxEvent } from "@tangle-network/sandbox";
 import type { AgentEnvironmentEvent } from "@tangle-network/agent-interface/environment-provider";
+/** The sidecar sends this envelope when an SSE connection is ready. */
+export declare function isSandboxConnectionMarker(event: SandboxEvent): boolean;
+/** Read identity from both run frames and /agents/events session envelopes. */
+export declare function sandboxEventIdentity(event: SandboxEvent): {
+    executionId?: string;
+    sessionId?: string;
+};
 export declare function environmentEventFromSandboxEvent(event: SandboxEvent, expected?: {
     executionId?: string;
     sessionId?: string;
+    streamBound?: boolean;
 }): AgentEnvironmentEvent;

package/dist/tangle-events.js

@@ -1,6 +1,48 @@
+import { CanonicalStreamEventSchema, } from "@tangle-network/agent-interface";
 import { assertBoundedJson } from "./tangle-contract-safety.js";
 import { optionalNonEmptyString } from "./tangle-environment-values.js";
 import { tokenUsageFromData } from "./tangle-result-values.js";
+/** The sidecar sends this envelope when an SSE connection is ready. */
+export function isSandboxConnectionMarker(event) {
+    if (!event || typeof event !== "object")
+        return false;
+    const record = event;
+    if (record.type === "connection.established")
+        return true;
+    const data = record.data;
+    return (data !== null &&
+        typeof data === "object" &&
+        !Array.isArray(data) &&
+        data.type === "connection.established");
+}
+/** Read identity from both run frames and /agents/events session envelopes. */
+export function sandboxEventIdentity(event) {
+    const record = event;
+    const data = record.data;
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        return {};
+    }
+    const dataRecord = data;
+    const properties = dataRecord.properties &&
+        typeof dataRecord.properties === "object" &&
+        !Array.isArray(dataRecord.properties)
+        ? dataRecord.properties
+        : undefined;
+    const info = properties?.info &&
+        typeof properties.info === "object" &&
+        !Array.isArray(properties.info)
+        ? properties.info
+        : undefined;
+    return {
+        executionId: optionalNonEmptyString(dataRecord.executionId ?? properties?.executionId ?? info?.executionId, "Tangle Sandbox event executionId"),
+        sessionId: optionalNonEmptyString(dataRecord.sessionId ??
+            dataRecord.sessionID ??
+            properties?.sessionId ??
+            properties?.sessionID ??
+            info?.sessionId ??
+            info?.sessionID, "Tangle Sandbox event sessionId"),
+    };
+}
 export function environmentEventFromSandboxEvent(event, expected = {}) {
     if (!event || typeof event !== "object") {
         throw new Error("Tangle Sandbox emitted a non-object event");
@@ -30,27 +72,145 @@ export function environmentEventFromSandboxEvent(event, expected = {}) {
     if (Object.prototype.hasOwnProperty.call(data, "contextTransferReceipt")) {
         throw new Error("Tangle Sandbox emitted an unsolicited context transfer receipt");
     }
-    const eventExecutionId = optionalNonEmptyString(data.executionId, "Tangle Sandbox event executionId");
-    const eventSessionId = optionalNonEmptyString(data.sessionId, "Tangle Sandbox event sessionId");
+    const { executionId: eventExecutionId, sessionId: eventSessionId } = sandboxEventIdentity(event);
     if (expected.executionId !== undefined &&
-        (eventExecutionId === undefined || eventExecutionId !== expected.executionId)) {
+        ((eventExecutionId === undefined && expected.streamBound !== true) ||
+            (eventExecutionId !== undefined && eventExecutionId !== expected.executionId))) {
         throw new Error("Tangle exact session event identified a different executionId");
     }
     if (expected.sessionId !== undefined &&
-        (eventSessionId === undefined || eventSessionId !== expected.sessionId)) {
+        ((eventSessionId === undefined && expected.streamBound !== true) ||
+            (eventSessionId !== undefined && eventSessionId !== expected.sessionId))) {
         throw new Error("Tangle exact session event identified a different sessionId");
     }
     const usage = tokenUsageFromData(data);
+    const normalized = normalizeSandboxEvent(record.type, data);
     return {
         type: record.type,
         data,
         ...(typeof record.id === "string" ? { id: record.id } : {}),
+        ...(normalized ? { normalized } : {}),
         // Absent rather than zeroed: an event that reported no usage must not
         // contribute a total to whatever sums these events.
         ...(usage ? { usage } : {}),
         providerEvent: event,
     };
 }
+function normalizeSandboxEvent(type, data) {
+    const supplied = data.normalized;
+    if (supplied !== undefined) {
+        const parsed = CanonicalStreamEventSchema.safeParse(supplied);
+        if (!parsed.success) {
+            throw new Error("Tangle Sandbox emitted an invalid normalized event");
+        }
+        if (parsed.data.type !== type) {
+            throw new Error(`Tangle Sandbox normalized event type "${parsed.data.type}" does not match transport type "${type}"`);
+        }
+        return parsed.data;
+    }
+    switch (type) {
+        case "status": {
+            const status = statusFromSandboxValue(data.status);
+            if (!status)
+                return undefined;
+            return {
+                type: "status",
+                status,
+                ...detailFromSandboxData(data),
+            };
+        }
+        case "message.part.updated": {
+            const candidate = {
+                type,
+                ...(data.part !== undefined ? { part: data.part } : {}),
+                ...(typeof data.delta === "string" ? { delta: data.delta } : {}),
+            };
+            const parsed = CanonicalStreamEventSchema.safeParse(candidate);
+            return parsed.success ? parsed.data : undefined;
+        }
+        case "tool-heartbeat":
+            return parseCanonical({
+                type,
+                toolName: data.toolName,
+                partId: data.partId,
+                elapsedMs: data.elapsedMs,
+            });
+        case "tool-slow":
+            return parseCanonical({
+                type,
+                toolName: data.toolName,
+                partId: data.partId,
+                elapsedMs: data.elapsedMs,
+                thresholdMs: data.thresholdMs,
+            });
+        case "model-processing":
+            return parseCanonical({
+                type,
+                phase: data.phase,
+                ...(typeof data.toolName === "string" ? { toolName: data.toolName } : {}),
+                ...(typeof data.elapsedMs === "number" ? { elapsedMs: data.elapsedMs } : {}),
+            });
+        case "warning":
+            return parseCanonical({
+                type,
+                code: data.code,
+                message: data.message,
+            });
+        case "session.updated":
+            return parseCanonical({
+                type,
+                sessionId: data.sessionId ?? data.sessionID,
+                ...(typeof data.title === "string" ? { title: data.title } : {}),
+                ...(data.time !== undefined ? { time: data.time } : {}),
+            });
+        case "interaction":
+            return parseCanonical({ type, request: data.request });
+        case "interaction.cancel":
+            return parseCanonical({
+                type,
+                id: data.id,
+                ...(typeof data.reason === "string" ? { reason: data.reason } : {}),
+            });
+        case "plan.submitted":
+            return parseCanonical({ type, plan: data.plan });
+        case "result":
+        case "done":
+        default:
+            // These transport frames carry terminal/result data, but they are not
+            // members of the provider-neutral canonical event union. The exact
+            // result endpoint remains the authoritative result surface.
+            return undefined;
+    }
+}
+function parseCanonical(value) {
+    const parsed = CanonicalStreamEventSchema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
+function statusFromSandboxValue(value) {
+    if (typeof value !== "string")
+        return undefined;
+    switch (value) {
+        case "started":
+        case "queued":
+            return "started";
+        case "processing":
+        case "running":
+            return "processing";
+        case "completed":
+        case "success":
+            return "completed";
+        case "failed":
+        case "error":
+        case "cancelled":
+            return "failed";
+        default:
+            return undefined;
+    }
+}
+function detailFromSandboxData(data) {
+    const detail = [data.detail, data.error, data.message].find((value) => typeof value === "string" && value.length > 0);
+    return detail === undefined ? {} : { detail };
+}
 function assertBoundedRecord(value) {
     if (Object.keys(value).length > 256) {
         throw new Error("Tangle Sandbox event data has too many fields");

package/dist/tangle-prompt.d.ts

@@ -1,13 +1,14 @@
-import type { PromptOptions, PromptResult } from "@tangle-network/sandbox";
+import type { PromptResult } from "@tangle-network/sandbox";
 import type { AgentTurnInput, AgentTurnResult } from "@tangle-network/agent-interface/environment-provider";
-import type { InputPart } from "@tangle-network/agent-interface";
+import type { AgentExactRunControlRef, InputPart } from "@tangle-network/agent-interface";
+import type { TanglePromptOptions } from "./tangle-types.js";
 export declare function promptFromTurnInput(input: AgentTurnInput): string | InputPart[];
 export declare function executionIdFromTurnInput(input: AgentTurnInput): string | undefined;
 export declare function promptOptionsFromTurnInput(input: AgentTurnInput, target: {
     provider: string;
     environmentId: string;
     sessionId?: string;
-}): PromptOptions;
+}): TanglePromptOptions;
 type SandboxRunStatus = "success" | "failed" | "blocked_on_approval" | "awaiting_question" | "awaiting_plan_decision";
 type ValidatedSandboxPromptResult = Record<string, unknown> & {
     success: boolean;
@@ -20,5 +21,6 @@ export declare function agentTurnResultFromPromptRecord(record: ValidatedSandbox
     contextTransferRequested?: boolean;
     contextTransferRequest?: import("@tangle-network/agent-interface").ContextTransferRequest;
     sessionId?: string;
+    controlRef?: AgentExactRunControlRef;
 }): AgentTurnResult;
 export {};

package/dist/tangle-prompt.js

@@ -31,9 +31,6 @@ export function promptOptionsFromTurnInput(input, target) {
         if (controlRef.sessionId === undefined || controlRef.executionId === undefined) {
             throw new Error("Tangle control reference requires exact sessionId and executionId");
         }
-        if (controlRef.runId !== controlRef.executionId) {
-            throw new Error("Tangle control reference requires runId to equal executionId");
-        }
         if (input.sessionId !== undefined &&
             input.sessionId !== controlRef.sessionId) {
             throw new Error("Tangle sessionId conflicts with the control reference");
@@ -55,6 +52,7 @@ export function promptOptionsFromTurnInput(input, target) {
         ...(input.context ? { context: input.context } : {}),
         ...(input.signal ? { signal: input.signal } : {}),
         ...(executionId ? { executionId } : {}),
+        ...(controlRef ? { runControlRef: controlRef } : {}),
         ...(input.lastEventId ? { lastEventId: input.lastEventId } : {}),
         ...(input.turnId ? { turnId: input.turnId } : {}),
         ...(input.detach !== undefined ? { detach: input.detach } : {}),
@@ -118,6 +116,18 @@ const AWAITING_STATUSES = new Set([
     "awaiting_plan_decision",
 ]);
 export function agentTurnResultFromPromptRecord(record, options = {}) {
+    const controlRef = options.controlRef
+        ? AgentExactRunControlRefSchema.parse(options.controlRef)
+        : undefined;
+    if (controlRef !== undefined &&
+        options.sessionId !== undefined &&
+        controlRef.sessionId !== options.sessionId) {
+        throw new Error("Tangle prompt result sessionId conflicts with its control reference");
+    }
+    if (controlRef !== undefined &&
+        record.executionId !== controlRef.executionId) {
+        throw new Error("Tangle prompt result did not confirm its exact executionId");
+    }
     const text = typeof record.response === "string"
         ? record.response
         : typeof record.text === "string"
@@ -155,6 +165,13 @@ export function agentTurnResultFromPromptRecord(record, options = {}) {
         // "the agent is asking you something" indistinguishable from "the turn
         // failed", while the sandbox stayed alive waiting for an answer.
         metadata: {
+            ...(controlRef
+                ? {
+                    runId: controlRef.runId,
+                    executionId: controlRef.executionId,
+                    requestDigest: controlRef.requestDigest,
+                }
+                : {}),
             status: record.status,
             awaitingInteraction: awaiting,
             terminal: !awaiting,

package/dist/tangle-session-control.d.ts

@@ -1,7 +1,8 @@
-import type { AgentRunControlRef } from "@tangle-network/agent-interface";
+import type { AgentExactRunControlRef, AgentRunControlRef } from "@tangle-network/agent-interface";
 import type { AgentSessionRef } from "@tangle-network/agent-interface/environment-provider";
-export declare function sessionRefFromSandboxDispatch(dispatched: unknown, providerName: string, environmentId: string, expectedExecutionId: string | undefined, requestDigest?: `sha256:${string}` | undefined, expectedSessionId?: string | undefined): AgentSessionRef;
-export declare function retainedSessionControlRef(sessionId: string, executionId: string, provider: string, environmentId: string, requestDigest?: `sha256:${string}`): AgentRunControlRef;
-export declare function sessionPromptExecutionId(provider: string, environmentId: string, sessionId: string, turnId: string | undefined): string;
+export declare function sessionRefFromSandboxDispatch(dispatched: unknown, providerName: string, environmentId: string, expectedExecutionId: string | undefined, requestDigest?: `sha256:${string}` | undefined, expectedSessionId?: string | undefined, callerControlRef?: AgentExactRunControlRef | undefined): AgentSessionRef;
+export declare function retainedSessionControlRef(sessionId: string, executionId: string, provider: string, environmentId: string, requestDigest?: `sha256:${string}`, runId?: string): AgentExactRunControlRef;
+export declare function sessionPromptExecutionId(requestDigest: `sha256:${string}`): string;
+export declare function sessionPromptSessionId(provider: string, environmentId: string, turnId: string | undefined): string | undefined;
 export declare function sameRunControlRef(left: AgentRunControlRef, right: AgentRunControlRef): boolean;
-export declare function resolveRetainedSessionControlRef(candidate: AgentRunControlRef | undefined, sessionId: string, provider: string, environmentId: string): AgentRunControlRef | undefined;
+export declare function resolveRetainedSessionControlRef(candidate: AgentRunControlRef | undefined, sessionId: string, provider: string, environmentId: string): AgentExactRunControlRef | undefined;

package/dist/tangle-session-control.js

@@ -1,8 +1,8 @@
-import { createHash, randomUUID } from "node:crypto";
+import { createHash } from "node:crypto";
 import { AgentExactRunControlRefSchema, canonicalCandidateDigest, } from "@tangle-network/agent-interface";
 import { nonEmptyString } from "./tangle-environment-values.js";
 import { assertBoundedJson, boundedIdentifier, } from "./tangle-contract-safety.js";
-export function sessionRefFromSandboxDispatch(dispatched, providerName, environmentId, expectedExecutionId, requestDigest = undefined, expectedSessionId = undefined) {
+export function sessionRefFromSandboxDispatch(dispatched, providerName, environmentId, expectedExecutionId, requestDigest = undefined, expectedSessionId = undefined, callerControlRef = undefined) {
     const record = dispatched && typeof dispatched === "object" && !Array.isArray(dispatched)
         ? dispatched
         : undefined;
@@ -34,11 +34,26 @@ export function sessionRefFromSandboxDispatch(dispatched, providerName, environm
     if (record.dispatched !== undefined && typeof record.dispatched !== "boolean") {
         throw new Error("sandbox dispatch returned an invalid dispatched flag");
     }
+    const accepted = record.runControlRef === undefined
+        ? callerControlRef === undefined
+            ? undefined
+            : AgentExactRunControlRefSchema.safeParse(callerControlRef)
+        : AgentExactRunControlRefSchema.safeParse(record.runControlRef);
+    if (accepted === undefined || !accepted.success) {
+        throw new Error("sandbox dispatch did not return the exact run control reference");
+    }
+    if (accepted.data.provider !== providerName ||
+        accepted.data.environmentId !== environmentId ||
+        accepted.data.sessionId !== id ||
+        accepted.data.executionId !== executionId ||
+        (requestDigest !== undefined && accepted.data.requestDigest !== requestDigest)) {
+        throw new Error("sandbox dispatch returned an exact control reference for another run");
+    }
+    const controlRef = Object.freeze(accepted.data);
     return {
         id,
         provider: providerName,
-        controlRef: retainedSessionControlRef(id, executionId, providerName, environmentId, requestDigest ??
-            canonicalCandidateDigest({ provider: providerName, environmentId, id, executionId })),
+        controlRef,
         metadata: {
             ...(record.status ? { status: record.status } : {}),
             ...(record.alreadyExisted !== undefined ? { alreadyExisted: record.alreadyExisted } : {}),
@@ -46,24 +61,27 @@ export function sessionRefFromSandboxDispatch(dispatched, providerName, environm
         },
     };
 }
-export function retainedSessionControlRef(sessionId, executionId, provider, environmentId, requestDigest) {
-    return AgentExactRunControlRefSchema.parse({
-        runId: executionId,
+export function retainedSessionControlRef(sessionId, executionId, provider, environmentId, requestDigest, runId = executionId) {
+    return Object.freeze(AgentExactRunControlRefSchema.parse({
+        runId,
         provider,
         environmentId,
         sessionId,
         executionId,
         requestDigest: requestDigest ??
             canonicalCandidateDigest({ provider, environmentId, sessionId, executionId }),
-    });
+    }));
+}
+export function sessionPromptExecutionId(requestDigest) {
+    return `session-turn-${requestDigest.slice("sha256:".length)}`;
 }
-export function sessionPromptExecutionId(provider, environmentId, sessionId, turnId) {
+export function sessionPromptSessionId(provider, environmentId, turnId) {
     if (turnId === undefined)
-        return randomUUID();
+        return undefined;
     const digest = createHash("sha256")
-        .update(`${provider}\0${environmentId}\0${sessionId}\0${turnId}`)
+        .update(`${provider}\0${environmentId}\0${turnId}`)
         .digest("hex");
-    return `session-turn-${digest}`;
+    return `session-${digest}`;
 }
 export function sameRunControlRef(left, right) {
     return (left.runId === right.runId &&
@@ -82,8 +100,5 @@ export function resolveRetainedSessionControlRef(candidate, sessionId, provider,
         controlRef.sessionId !== sessionId) {
         throw new Error("Tangle control reference does not match this session");
     }
-    if (controlRef.runId !== controlRef.executionId) {
-        throw new Error("Tangle session control reference requires runId to equal executionId");
-    }
-    return controlRef;
+    return retainedSessionControlRef(sessionId, controlRef.executionId, provider, environmentId, controlRef.requestDigest, controlRef.runId);
 }

package/dist/tangle-types.d.ts

@@ -1,6 +1,9 @@
 import type { BackendType, CreateSandboxOptions, ExecResult as SandboxExecResult, PromptOptions, PromptResult, SandboxEvent } from "@tangle-network/sandbox";
-import type { InputPart } from "@tangle-network/agent-interface";
+import type { AgentExactRunControlRef, AgentRunCancellationAcknowledgement, AgentRunCancellationRequest, InputPart } from "@tangle-network/agent-interface";
 import type { AgentEnvironmentCapabilities, AgentEnvironmentProvider, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
+export type TanglePromptOptions = PromptOptions & {
+    runControlRef?: AgentExactRunControlRef;
+};
 export interface TangleExactProcessOptions {
     teamId?: string;
 }
@@ -53,9 +56,9 @@ export interface SandboxInstanceLike {
     name?: string;
     status?: unknown;
     metadata?: Record<string, unknown>;
-    streamPrompt(message: string | InputPart[], options?: PromptOptions): AsyncIterable<SandboxEvent>;
-    prompt?(message: string | InputPart[], options?: PromptOptions): Promise<PromptResult>;
-    dispatchPrompt?(message: string | InputPart[], options?: PromptOptions): Promise<unknown>;
+    streamPrompt(message: string | InputPart[], options?: TanglePromptOptions): AsyncIterable<SandboxEvent>;
+    prompt?(message: string | InputPart[], options?: TanglePromptOptions): Promise<PromptResult>;
+    dispatchPrompt?(message: string | InputPart[], options?: TanglePromptOptions): Promise<unknown>;
     session?(id: string, options?: {
         signal?: AbortSignal;
     }): SandboxSessionLike;
@@ -122,13 +125,16 @@ export interface SandboxSessionLike {
         executionId?: string;
         signal?: AbortSignal;
     }): Promise<PromptResult>;
-    prompt(message: string | InputPart[], options?: PromptOptions): Promise<PromptResult>;
+    prompt(message: string | InputPart[], options?: TanglePromptOptions): Promise<PromptResult>;
     interrupt(options?: {
         executionId?: string;
         signal?: AbortSignal;
     }): Promise<{
         cancelled: boolean;
     }>;
+    cancelRun?(request: AgentRunCancellationRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentRunCancellationAcknowledgement>;
 }
 export interface TangleProviderOptions {
     client: SandboxClientLike;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",
@@ -78,7 +78,8 @@
     }
   },
   "devDependencies": {
-    "@tangle-network/sandbox": "0.17.0",
+    "@tangle-network/agent-runtime": "0.132.6",
+    "@tangle-network/sandbox": "0.19.4",
     "@types/node": "25.6.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5",