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

package/README.md

@@ -1,6 +1,7 @@
 # @tangle-network/agent-provider-tangle
 
-Wraps `@tangle-network/sandbox` 0.17 or newer as an `AgentEnvironmentProvider`.
+Wraps `@tangle-network/sandbox` as an `AgentEnvironmentProvider`.
+The peer range is `>=0.19.6 <1.0.0`; retained-run cancellation (`session.cancelRun`) first shipped in 0.19.6, and this package is developed and tested against 0.21.1.
 
 ```ts
 import { Sandbox } from '@tangle-network/sandbox'
@@ -13,14 +14,25 @@ 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.
+Session status with an exact control reference reports a state only when the payload names that execution; a payload bound to a different or unnamed execution reports `unknown`.
+
+The provider claims `retainedControl` only from probed facts.
+A lazy instance handle minted from the linked Sandbox SDK over the client's `fetch` transport must prove `dispatchPrompt`, `session`, and `cancelRun`, and the client must expose `get` for reconstruction; the probe sends no request and creates no resource.
+The probe measures the linked SDK's method surface, not the connected service; service-side truth needs the sidecar capability endpoint and is a follow-up.
+A client that cannot prove those facts gets no claim, so the runtime rejects retained dispatch before any sandbox is created.
+Each concrete sandbox narrows the declared document independently against its own measured method surface, so a capable sandbox keeps retained control even when the provider-level claim failed closed.
+
+Pass the SDK client itself when retained control matters.
+An object-spread wrapper (`{ ...client }`) drops class prototype methods, including `fetch`, so the provider treats the wrapper as a non-SDK client and claims no retained control.
+A wrapper must delegate the SDK methods instead of copying properties.
 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.
 It also rejects `contextTransfer` and `nativeContinuation` inputs explicitly until those operations have native Sandbox support instead of silently dropping them.
-The default adapter does not advertise legacy checkpoint or fork operations because Sandbox 0.17 exposes snapshots and branches with different semantics.
-A custom compatible client may opt into the legacy methods explicitly; durable workspace branching remains unadvertised until checkpoint lookup, retry, conflict, and cleanup are implemented together.
+The adapter never advertises `branching.checkpoint` or `branching.fork`.
+Sandbox exposes `snapshot`, `listSnapshots`, `deleteSnapshot`, and `branch(count)` with different semantics; durable workspace branching stays unadvertised until the full `AgentWorkspaceBranching` contract — retry, lookup, conflict, and cleanup together — is implemented over that surface.
 
 Pass `exactProcess: {}` only when the Sandbox deployment supports `agent: false` creates and reports `metadata.runtimeMode: "control"`.
 The optional capability creates an ephemeral sandbox with an authenticated control service but no managed agent workload or agent credentials, explicit resources, exact blocked/domain egress, bounded binary file reads, shell-free launch, and recoverable process output plus terminal reason.

package/dist/tangle-capabilities.d.ts

@@ -4,36 +4,54 @@ import type { SandboxClientLike, SandboxInstanceLike } from "./tangle-types.js";
  * The full capability document this adapter supports when the Sandbox client
  * implements every optional method.
  *
- * This is an upper bound, not a claim. `capabilitiesForSandbox()` narrows it
- * to what a specific client actually exposes, because a capability the client
- * cannot back becomes an action the caller selects and finds missing.
+ * This is an upper bound, not a claim. `capabilitiesForClient()` and
+ * `capabilitiesForSandbox()` narrow it to what the deployment actually
+ * exposes, because a capability the client cannot back becomes an action the
+ * caller selects and finds missing.
  */
 export declare function defaultTangleSandboxCapabilities(harness?: HarnessType): AgentEnvironmentCapabilities;
-/** Optional methods whose absence must clear the matching declared capability. */
+/**
+ * Deployment facts that gate declared capabilities. Every fact defaults to
+ * false when it cannot be established; a false fact clears the matching
+ * declared capability.
+ */
 export interface SandboxCapabilitySupport {
+    /** The provider can rebuild an environment by id (`client.get`). */
+    reconstruct: boolean;
     dispatchPrompt: boolean;
     session: boolean;
     read: boolean;
     write: boolean;
     exec: boolean;
-    checkpoint: boolean;
-    fork: boolean;
     placement: boolean;
     destroy: boolean;
+    cancelRun: boolean;
 }
 export declare function sandboxCapabilitySupport(box: SandboxInstanceLike, client: SandboxClientLike): SandboxCapabilitySupport;
 /**
- * Narrow provider-level claims to capabilities the client can actually back.
- *
- * 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.
+ * Establish client-stage facts before any sandbox exists. Two sources:
+ * the client's own members (get, describePlacement) and, for an SDK-backed
+ * client, the linked SDK surface via `linkedSdkProbeInstance`. Retained
+ * control fails closed: without a probe handle nothing proves `cancelRun`,
+ * so the provider must not claim it. Box-scoped workspace and streaming
+ * facts stay at the declared upper bound when no handle can be minted —
+ * each concrete sandbox re-narrows them in `capabilitiesForSandbox`.
  */
-export declare function capabilitiesForClient(declared: AgentEnvironmentCapabilities, client: SandboxClientLike): AgentEnvironmentCapabilities;
+export declare function clientCapabilitySupport(client: SandboxClientLike): SandboxCapabilitySupport;
 /**
- * Narrow a declared capability document to what this Sandbox instance backs.
+ * Narrow a declared capability document to established facts.
  *
  * Braid derives product actions from these flags, so an over-claimed flag is
- * an offered action that throws at the moment the user selects it.
+ * an offered action that throws at the moment the user selects it. Retained
+ * control requires the complete fact set: exact dispatch, a session handle,
+ * canonical cancellation, and environment reconstruction by id.
  */
+export declare function narrowedTangleCapabilities(declared: AgentEnvironmentCapabilities, support: SandboxCapabilitySupport): AgentEnvironmentCapabilities;
+/**
+ * Narrow provider-level claims to facts the client can prove before any
+ * sandbox exists. `clientCapabilitySupport` documents which facts stay at
+ * the declared upper bound when the client offers no probe surface.
+ */
+export declare function capabilitiesForClient(declared: AgentEnvironmentCapabilities, client: SandboxClientLike): AgentEnvironmentCapabilities;
+/** Narrow a declared capability document to what this Sandbox instance backs. */
 export declare function capabilitiesForSandbox(declared: AgentEnvironmentCapabilities, support: SandboxCapabilitySupport): AgentEnvironmentCapabilities;

package/dist/tangle-capabilities.js

@@ -1,11 +1,13 @@
 import { harnessSystemPromptIntents } from "@tangle-network/agent-interface";
+import { SandboxInstance } from "@tangle-network/sandbox";
 /**
  * The full capability document this adapter supports when the Sandbox client
  * implements every optional method.
  *
- * This is an upper bound, not a claim. `capabilitiesForSandbox()` narrows it
- * to what a specific client actually exposes, because a capability the client
- * cannot back becomes an action the caller selects and finds missing.
+ * This is an upper bound, not a claim. `capabilitiesForClient()` and
+ * `capabilitiesForSandbox()` narrow it to what the deployment actually
+ * exposes, because a capability the client cannot back becomes an action the
+ * caller selects and finds missing.
  */
 export function defaultTangleSandboxCapabilities(harness) {
     return {
@@ -31,10 +33,22 @@ export function defaultTangleSandboxCapabilities(harness) {
             validation: true,
         },
         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.
-        sessions: { continue: false, list: false, messages: false },
+        // Retained control is declared as intent here and stripped by narrowing
+        // wherever the facts cannot prove dispatchPrompt, session, cancelRun,
+        // and environment reconstruction by id. The four sub-flags are
+        // all-or-nothing by design: this adapter implements the identities
+        // together over one Sandbox surface, and the capability schema refuses
+        // a partial block, so they stand or fall on the same probed fact set.
+        sessions: { continue: true, list: false, messages: false },
+        retainedControl: {
+            exactRunIdentity: true,
+            resultIdentity: true,
+            eventIdentity: true,
+            cancellationIdempotency: true,
+        },
         workspace: { read: true, write: true, exec: true, git: false, upload: true, download: true },
+        // Sandbox exposes snapshot/branch, not the checkpoint/fork contract, and
+        // durable branching needs retry, lookup, conflict, and cleanup together.
         branching: { checkpoint: false, fork: false },
         placement: true,
         usage: false,
@@ -43,98 +57,153 @@ export function defaultTangleSandboxCapabilities(harness) {
         confidential: false,
     };
 }
+// One reserved id names both probe handles; neither ever reaches the service.
+const CAPABILITY_PROBE_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_ID);
+        }
+        catch {
+            // A client that cannot produce a session handle cannot prove retained control.
+        }
+    }
     return {
+        reconstruct: typeof client.get === "function",
         dispatchPrompt: typeof box.dispatchPrompt === "function",
         session: typeof box.session === "function",
         read: typeof box.read === "function",
         write: typeof box.write === "function",
         exec: typeof box.exec === "function",
-        checkpoint: typeof box.checkpoint === "function",
-        fork: typeof box.fork === "function",
         placement: typeof client.describePlacement === "function",
         destroy: typeof box.delete === "function",
+        cancelRun: typeof session?.cancelRun === "function",
     };
 }
 /**
- * Narrow provider-level claims to capabilities the client can actually back.
- *
- * 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.
+ * Mint a lazy instance handle from the sandbox SDK linked into this process.
+ * The handle measures the LINKED SDK's instance and session method surface —
+ * an adapter-capability fact, not deployment truth. It is valid exactly when
+ * the client is SDK-backed (carries the SDK `fetch` transport), because the
+ * sandboxes such a client returns are instances of these same classes.
+ * Deployment truth (what the connected service honors) needs the sidecar
+ * capability endpoint and is a follow-up. The handle and its probe session
+ * never leave the process: construction and `session(id)` are lazy in the
+ * SDK, so no request is sent and no billable resource is created.
  */
-export function capabilitiesForClient(declared, client) {
-    const narrowed = {
-        ...declared,
-        streaming: {
-            ...declared.streaming,
-            replay: declared.streaming.replay,
-            detach: declared.streaming.detach,
-            turnIdempotency: declared.streaming.turnIdempotency,
-        },
-        sessions: { ...declared.sessions, continue: false, list: false, messages: false },
-        workspace: { ...declared.workspace, git: false },
-        usage: false,
-        branching: {
-            ...declared.branching,
-            checkpoint: false,
-            fork: false,
-            ...(declared.branching.retrySafe !== undefined ? { retrySafe: false } : {}),
-            ...(declared.branching.lookup !== undefined ? { lookup: false } : {}),
-            ...(declared.branching.cleanup !== undefined ? { cleanup: false } : {}),
-        },
-        placement: declared.placement && typeof client.describePlacement === "function",
+function linkedSdkProbeInstance(client) {
+    if (typeof client.fetch !== "function")
+        return undefined;
+    try {
+        return new SandboxInstance(client, {
+            id: CAPABILITY_PROBE_ID,
+            status: "stopped",
+            createdAt: new Date(0),
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Establish client-stage facts before any sandbox exists. Two sources:
+ * the client's own members (get, describePlacement) and, for an SDK-backed
+ * client, the linked SDK surface via `linkedSdkProbeInstance`. Retained
+ * control fails closed: without a probe handle nothing proves `cancelRun`,
+ * so the provider must not claim it. Box-scoped workspace and streaming
+ * facts stay at the declared upper bound when no handle can be minted —
+ * each concrete sandbox re-narrows them in `capabilitiesForSandbox`.
+ */
+export function clientCapabilitySupport(client) {
+    const probe = linkedSdkProbeInstance(client);
+    if (probe)
+        return sandboxCapabilitySupport(probe, client);
+    return {
+        reconstruct: typeof client.get === "function",
+        dispatchPrompt: true,
+        session: true,
+        read: true,
+        write: true,
+        exec: true,
+        placement: typeof client.describePlacement === "function",
+        destroy: true,
+        cancelRun: false,
     };
-    delete narrowed.interactions;
-    delete narrowed.retainedControl;
-    delete narrowed.nativeContinuation;
-    return narrowed;
 }
 /**
- * Narrow a declared capability document to what this Sandbox instance backs.
+ * Narrow a declared capability document to established facts.
  *
  * Braid derives product actions from these flags, so an over-claimed flag is
- * an offered action that throws at the moment the user selects it.
+ * an offered action that throws at the moment the user selects it. Retained
+ * control requires the complete fact set: exact dispatch, a session handle,
+ * canonical cancellation, and environment reconstruction by id.
  */
-export function capabilitiesForSandbox(declared, support) {
-    const narrowed = { ...declared };
-    delete narrowed.interactions;
-    delete narrowed.retainedControl;
-    delete narrowed.nativeContinuation;
-    return {
-        ...narrowed,
+export function narrowedTangleCapabilities(declared, support) {
+    const supportsRetainedControl = declared.sessions.continue === true &&
+        declared.streaming.detach === true &&
+        declared.streaming.replay === true &&
+        declared.streaming.turnIdempotency === true &&
+        support.reconstruct &&
+        support.dispatchPrompt &&
+        support.session &&
+        support.cancelRun;
+    // A cleared fact forces false; a held fact passes the declared value
+    // through unchanged, so a malformed declaration still reaches the schema
+    // at the provider boundary instead of being laundered into a boolean.
+    const narrowed = {
+        ...declared,
         streaming: {
             ...declared.streaming,
-            detach: declared.streaming.detach && support.dispatchPrompt,
-            replay: declared.streaming.replay && support.session,
-            turnIdempotency: declared.streaming.turnIdempotency && support.session,
+            detach: support.dispatchPrompt ? declared.streaming.detach : false,
+            replay: support.session ? declared.streaming.replay : false,
+            turnIdempotency: support.session
+                ? declared.streaming.turnIdempotency
+                : false,
         },
         sessions: {
             ...declared.sessions,
-            continue: false,
+            continue: supportsRetainedControl ? declared.sessions.continue : false,
             list: false,
             messages: false,
         },
         workspace: {
             ...declared.workspace,
-            read: declared.workspace.read && support.read,
-            write: declared.workspace.write && support.write,
-            exec: declared.workspace.exec && support.exec,
+            read: support.read ? declared.workspace.read : false,
+            write: support.write ? declared.workspace.write : false,
+            exec: support.exec ? declared.workspace.exec : false,
             git: false,
-            upload: declared.workspace.upload && support.write,
-            download: declared.workspace.download && support.read,
+            upload: support.write ? declared.workspace.upload : false,
+            download: support.read ? declared.workspace.download : false,
         },
         branching: {
-            ...narrowed.branching,
+            ...declared.branching,
             checkpoint: false,
             fork: false,
-            ...(declared.branching.retrySafe !== undefined
-                ? { retrySafe: false }
-                : {}),
+            ...(declared.branching.retrySafe !== undefined ? { retrySafe: false } : {}),
             ...(declared.branching.lookup !== undefined ? { lookup: false } : {}),
             ...(declared.branching.cleanup !== undefined ? { cleanup: false } : {}),
         },
-        placement: narrowed.placement && support.placement,
+        placement: support.placement ? declared.placement : false,
         usage: false,
     };
+    delete narrowed.interactions;
+    delete narrowed.nativeContinuation;
+    if (!supportsRetainedControl)
+        delete narrowed.retainedControl;
+    return narrowed;
+}
+/**
+ * Narrow provider-level claims to facts the client can prove before any
+ * sandbox exists. `clientCapabilitySupport` documents which facts stay at
+ * the declared upper bound when the client offers no probe surface.
+ */
+export function capabilitiesForClient(declared, client) {
+    return narrowedTangleCapabilities(declared, clientCapabilitySupport(client));
+}
+/** Narrow a declared capability document to what this Sandbox instance backs. */
+export function capabilitiesForSandbox(declared, support) {
+    return narrowedTangleCapabilities(declared, support);
 }

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,17 +28,15 @@ export function hasReplayPayload(input) {
         input.providerOptions !== undefined);
 }
 export async function interruptAfterAbort(box, reference) {
-    const sessionId = reference.id;
+    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 executionId = reference.controlRef?.executionId;
     if (!box.session || executionId === undefined)
         return;
-    try {
-        await box.session(sessionId)?.interrupt({ executionId });
-    }
-    catch {
-        // The original abort remains the caller-visible outcome; the provider has
-        // no stronger cleanup primitive when the late dispatch result is lost.
-    }
+    await interruptExecutionAfterAbort(box, reference.id, executionId);
 }
 export async function interruptExecutionAfterAbort(source, sessionId, executionId) {
     try {

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 {};