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

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 { executionBoundSessionStatus, 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");
@@ -19,6 +47,12 @@ export function sandboxSessionAsAgentSession(session, controlRef, provider, envi
             options?.signal?.throwIfAborted();
             if (!status)
                 return null;
+            const expectedExecutionId = activeControlRef?.executionId;
+            // Sandbox reports session-wide status. With an exact control reference,
+            // the answer is only valid when the payload binds to that execution.
+            if (expectedExecutionId !== undefined) {
+                return executionBoundSessionStatus(status, expectedExecutionId);
+            }
             return sessionStatusFromUnknown(status.status);
         },
         async *events(options) {
@@ -36,11 +70,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 +93,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 +137,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");
+            if (promptInFlight) {
+                throw new Error("Tangle session already has a prompt in flight");
             }
-            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");
-            }
-            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");
+                }
+                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;
                 }
-                throw error;
+            }
+            finally {
+                promptInFlight = false;
             }
         },
         async cancel(options) {
@@ -152,5 +304,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-validation.d.ts

@@ -1,11 +1,4 @@
-import type { CheckpointRef, CheckpointRequest, ExecRequest, ForkRequest } from "@tangle-network/agent-interface/environment-provider";
+import type { ExecRequest } from "@tangle-network/agent-interface/environment-provider";
 export declare function assertOptionKeys(value: object | undefined, allowed: readonly string[], label: string): void;
 export declare function assertRecord(value: unknown, label: string): asserts value is Record<string, unknown>;
 export declare function assertExecOptions(options: ExecRequest | undefined): void;
-export declare function assertCheckpointOptions(options: (CheckpointRequest & {
-    signal?: AbortSignal;
-}) | undefined): void;
-export declare function assertCheckpointRef(checkpoint: CheckpointRef): void;
-export declare function assertForkOptions(options: (ForkRequest & {
-    signal?: AbortSignal;
-}) | undefined): void;

package/dist/tangle-environment-validation.js

@@ -36,28 +36,3 @@ export function assertExecOptions(options) {
         throw new Error("Tangle exec timeoutMs must be a positive safe integer");
     }
 }
-export function assertCheckpointOptions(options) {
-    assertOptionKeys(options, ["name", "metadata", "signal"], "Tangle checkpoint");
-    if (options?.name !== undefined)
-        boundedString(options.name, "Tangle checkpoint name");
-    if (options?.metadata !== undefined)
-        assertRecord(options.metadata, "Tangle checkpoint metadata");
-}
-export function assertCheckpointRef(checkpoint) {
-    if (!checkpoint || typeof checkpoint !== "object" || Array.isArray(checkpoint)) {
-        throw new Error("Tangle fork checkpoint must be an object");
-    }
-    assertOptionKeys(checkpoint, ["id", "provider", "metadata"], "Tangle fork checkpoint");
-    boundedIdentifier(checkpoint.id, "Tangle checkpoint id");
-    if (checkpoint.provider !== undefined)
-        boundedIdentifier(checkpoint.provider, "Tangle checkpoint provider");
-    if (checkpoint.metadata !== undefined)
-        assertRecord(checkpoint.metadata, "Tangle checkpoint metadata");
-}
-export function assertForkOptions(options) {
-    assertOptionKeys(options, ["name", "metadata", "signal"], "Tangle fork");
-    if (options?.name !== undefined)
-        boundedString(options.name, "Tangle fork name");
-    if (options?.metadata !== undefined)
-        assertRecord(options.metadata, "Tangle fork metadata");
-}

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

@@ -2,7 +2,17 @@ import type { AgentEnvironmentStatus, AgentSessionStatus, PlacementInfo } from "
 import type { SandboxInstanceLike } from "./tangle-types.js";
 export declare function nonEmptyString(value: unknown): string | undefined;
 export declare function optionalNonEmptyString(value: unknown, label: string): string | undefined;
-export declare function checkpointIdFromResult(result: unknown): string;
 export declare function placementInfoFromLoopPlacement(placement: unknown, box: SandboxInstanceLike): PlacementInfo;
 export declare function statusFromUnknown(status: unknown): AgentEnvironmentStatus;
 export declare function sessionStatusFromUnknown(status: unknown): AgentSessionStatus;
+/**
+ * Bind a session-wide status payload to one exact execution.
+ *
+ * The Sandbox status endpoint reports the whole session. Its execution
+ * identity fields — activeExecutionId, latestExecutionId, runControlRef,
+ * failureReason.executionId — are the only proof of which execution the
+ * lifecycle state describes. A payload that names a different execution, or
+ * none, must not be attributed to the exact run, so the result degrades to
+ * "unknown" instead of fabricating an execution-scoped answer.
+ */
+export declare function executionBoundSessionStatus(payload: unknown, executionId: string): AgentSessionStatus;

package/dist/tangle-environment-values.js

@@ -1,4 +1,3 @@
-import { assertBoundedJson } from "./tangle-contract-safety.js";
 const MAX_IDENTIFIER_LENGTH = 512;
 export function nonEmptyString(value) {
     return typeof value === "string" &&
@@ -19,18 +18,6 @@ export function optionalNonEmptyString(value, label) {
     }
     return value;
 }
-export function checkpointIdFromResult(result) {
-    assertBoundedJson(result);
-    const record = result && typeof result === "object" ? result : {};
-    const id = record.checkpointId ?? record.id;
-    if (typeof id !== "string" ||
-        id.length === 0 ||
-        id.length > MAX_IDENTIFIER_LENGTH ||
-        id.trim() !== id) {
-        throw new Error("sandbox checkpoint returned no checkpoint id");
-    }
-    return id;
-}
 export function placementInfoFromLoopPlacement(placement, box) {
     if (!placement || typeof placement !== "object") {
         return { kind: "sandbox", sandboxId: boundedId(box.id, "sandbox id") };
@@ -75,6 +62,10 @@ export function statusFromUnknown(status) {
         return status;
     if (status === "completed" || status === "cancelled")
         return "stopped";
+    // A queued session is admitted work that has not started: pending, not
+    // unknown — "unknown" also means "not attributable" in exact-status binding.
+    if (status === "queued")
+        return "pending";
     return "unknown";
 }
 export function sessionStatusFromUnknown(status) {
@@ -82,3 +73,47 @@ export function sessionStatusFromUnknown(status) {
         return status;
     return statusFromUnknown(status);
 }
+/**
+ * Bind a session-wide status payload to one exact execution.
+ *
+ * The Sandbox status endpoint reports the whole session. Its execution
+ * identity fields — activeExecutionId, latestExecutionId, runControlRef,
+ * failureReason.executionId — are the only proof of which execution the
+ * lifecycle state describes. A payload that names a different execution, or
+ * none, must not be attributed to the exact run, so the result degrades to
+ * "unknown" instead of fabricating an execution-scoped answer.
+ */
+export function executionBoundSessionStatus(payload, executionId) {
+    const record = payload && typeof payload === "object" && !Array.isArray(payload)
+        ? payload
+        : {};
+    const sessionStatus = sessionStatusFromUnknown(record.status);
+    const active = nonEmptyString(record.activeExecutionId);
+    const latest = nonEmptyString(record.latestExecutionId);
+    const admitted = record.runControlRef && typeof record.runControlRef === "object"
+        ? nonEmptyString(record.runControlRef.executionId)
+        : undefined;
+    const failed = record.failureReason && typeof record.failureReason === "object"
+        ? nonEmptyString(record.failureReason.executionId)
+        : undefined;
+    // An attributed failure outranks liveness: failureReason.executionId is the
+    // only field that names the execution its state describes, so it decides
+    // the failed case in both directions. Naming this execution proves the
+    // failure; naming another execution proves the failed state is not this
+    // run's, even when a contradictory payload also marks this execution live.
+    if (sessionStatus === "failed" && failed !== undefined) {
+        return failed === executionId ? "failed" : "unknown";
+    }
+    // A live execution owns the session's current state; any other live
+    // execution means this payload says nothing exact about the bound run.
+    if (active !== undefined) {
+        return active === executionId ? sessionStatus : "unknown";
+    }
+    // With nothing live, the state belongs to the newest execution. Trust the
+    // admitted-run reference only when no newer execution is named.
+    if (latest === executionId)
+        return sessionStatus;
+    if (latest === undefined && admitted === executionId)
+        return sessionStatus;
+    return "unknown";
+}

package/dist/tangle-environment.js

@@ -2,11 +2,11 @@ import { AgentTurnInputSchema } from "@tangle-network/agent-interface";
 import { environmentEventFromSandboxEvent } from "./tangle-events.js";
 import { executionIdFromTurnInput, promptFromTurnInput, promptOptionsFromTurnInput, } from "./tangle-prompt.js";
 import { resolveRetainedSessionControlRef } from "./tangle-session-control.js";
-import { checkpointIdFromResult, placementInfoFromLoopPlacement, statusFromUnknown, } from "./tangle-environment-values.js";
+import { placementInfoFromLoopPlacement, statusFromUnknown, } from "./tangle-environment-values.js";
 import { execResultFromSandboxExecResult } from "./tangle-result-values.js";
 import { capabilitiesForSandbox, sandboxCapabilitySupport } from "./tangle-capabilities.js";
-import { attachCleanupHandle, awaitWithSignal, assertBoundedJson, boundedIdentifier, boundedString, } from "./tangle-contract-safety.js";
-import { assertCheckpointOptions, assertCheckpointRef, assertExecOptions, assertForkOptions, assertOptionKeys, } from "./tangle-environment-validation.js";
+import { awaitWithSignal, assertBoundedJson, boundedIdentifier, boundedString, } from "./tangle-contract-safety.js";
+import { assertExecOptions, assertOptionKeys, } from "./tangle-environment-validation.js";
 import { interruptExecutionAfterAbort, } from "./tangle-environment-control.js";
 import { dispatchEnvironmentRun } from "./tangle-environment-dispatch.js";
 import { sandboxSessionAsAgentSession } from "./tangle-environment-session.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,16 @@ 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);
+                    // sessions.continue was granted from a probe-session fact; this
+                    // backstop holds every concrete session to that fact, so a client
+                    // whose sessions diverge from its probe surface fails loud here
+                    // instead of failing at the first cancellation.
+                    if (capabilities.sessions.continue &&
+                        typeof agentSession.cancelRun !== "function") {
+                        throw new Error("Tangle retained session support requires SandboxSession.cancelRun");
+                    }
+                    return agentSession;
                 },
             }
             : {}),
@@ -133,56 +156,6 @@ export function sandboxInstanceAsEnvironment(box, providerName, client, declared
                 },
             }
             : {}),
-        ...(capabilities.branching.checkpoint && box.checkpoint
-            ? {
-                async checkpoint(options) {
-                    assertCheckpointOptions(options);
-                    options?.signal?.throwIfAborted();
-                    const result = await awaitWithSignal(box.checkpoint?.(options), options?.signal);
-                    options?.signal?.throwIfAborted();
-                    return { id: checkpointIdFromResult(result), provider: providerName };
-                },
-            }
-            : {}),
-        ...(capabilities.branching.fork && box.fork
-            ? {
-                async fork(checkpoint, options) {
-                    assertCheckpointRef(checkpoint);
-                    assertForkOptions(options);
-                    if (checkpoint.provider !== undefined && checkpoint.provider !== providerName) {
-                        throw new Error("Tangle fork checkpoint belongs to another provider");
-                    }
-                    boundedIdentifier(checkpoint.id, "Tangle checkpoint id");
-                    options?.signal?.throwIfAborted();
-                    const forked = await awaitWithSignal(box.fork?.(checkpoint.id, options), options?.signal);
-                    if (!forked)
-                        throw new Error("sandbox fork returned no environment");
-                    try {
-                        options?.signal?.throwIfAborted();
-                        if (boundedIdentifier(forked.id, "Tangle fork environment id") === environmentId) {
-                            throw new Error("Tangle fork returned the source environment");
-                        }
-                        return sandboxInstanceAsEnvironment(forked, providerName, client, capabilities);
-                    }
-                    catch (error) {
-                        if (!forked.delete) {
-                            const baseError = error instanceof Error ? error : new Error(String(error));
-                            attachCleanupHandle(baseError, forked);
-                            throw baseError;
-                        }
-                        try {
-                            await forked.delete();
-                        }
-                        catch (cleanupError) {
-                            const combined = new AggregateError([error, cleanupError], "Tangle fork validation and cleanup both failed");
-                            attachCleanupHandle(combined, forked, cleanupError);
-                            throw combined;
-                        }
-                        throw error;
-                    }
-                },
-            }
-            : {}),
         ...(capabilities.placement
             ? {
                 async placement(options) {

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;