@tangle-network/agent-provider-tangle 0.4.6 → 0.4.7

package/README.md

@@ -1,6 +1,6 @@
 # @tangle-network/agent-provider-tangle
 
-Wraps `@tangle-network/sandbox` as an `AgentEnvironmentProvider`.
+Wraps `@tangle-network/sandbox` 0.17 or newer as an `AgentEnvironmentProvider`.
 
 ```ts
 import { Sandbox } from '@tangle-network/sandbox'
@@ -11,6 +11,17 @@ 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.
+Result, replay, and cancel operations select that exact execution instead of whichever execution most recently changed the shared session.
+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.
+
 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.
 Set `teamId` inside `exactProcess` to scope create, lookup, and recovery to one team.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { BackendType, CreateSandboxOptions, ExecResult as SandboxExecResult, PromptOptions, PromptResult, SandboxEvent } from "@tangle-network/sandbox";
-import type { AgentEnvironmentCapabilities, AgentEnvironmentProvider, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
+import { type AgentEnvironmentCapabilities, type AgentEnvironmentProvider, type CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
 import type { InputPart } from "@tangle-network/agent-interface";
 import { type TangleExactProcessOptions } from "./exact-process.js";
 export type { TangleExactProcessOptions } from "./exact-process.js";
@@ -93,11 +93,16 @@ export interface SandboxSessionLike {
     status(): Promise<unknown | null>;
     events(options?: {
         since?: string;
+        executionId?: string;
         signal?: AbortSignal;
     }): AsyncIterable<SandboxEvent>;
-    result(): Promise<PromptResult>;
+    result(options?: {
+        executionId?: string;
+    }): Promise<PromptResult>;
     prompt(message: string | InputPart[], options?: PromptOptions): Promise<PromptResult>;
-    interrupt(): Promise<{
+    interrupt(options?: {
+        executionId?: string;
+    }): Promise<{
         cancelled: boolean;
     }>;
 }

package/dist/index.js

@@ -1,3 +1,6 @@
+import { createHash, randomUUID } from "node:crypto";
+import { AgentEnvironmentCapabilitiesSchema, } from "@tangle-network/agent-interface/environment-provider";
+import { AgentRunControlRefSchema, ContextTransferReceiptSchema, } from "@tangle-network/agent-interface";
 import { createTangleExactProcessProvider, } from "./exact-process.js";
 export function createTangleProvider(options) {
     const providerName = options.name ?? "tangle-sandbox";
@@ -8,34 +11,41 @@ export function createTangleProvider(options) {
             providerName,
         })
         : undefined;
+    const resolveCapabilities = async () => {
+        const configured = options.capabilities
+            ? typeof options.capabilities === "function"
+                ? await options.capabilities()
+                : options.capabilities
+            : defaultTangleSandboxCapabilities();
+        if (!exactProcess && configured.exactProcess) {
+            throw new Error("Tangle capabilities cannot advertise exactProcess without exactProcess configuration");
+        }
+        return AgentEnvironmentCapabilitiesSchema.parse(exactProcess
+            ? {
+                ...configured,
+                exactProcess: { egress: ["blocked", "strict"] },
+            }
+            : configured);
+    };
     return {
         name: providerName,
         ...(exactProcess ? { exactProcess } : {}),
-        capabilities: async () => {
-            const capabilities = options.capabilities
-                ? typeof options.capabilities === "function"
-                    ? await options.capabilities()
-                    : options.capabilities
-                : defaultTangleSandboxCapabilities();
-            if (!exactProcess && capabilities.exactProcess) {
-                throw new Error("Tangle capabilities cannot advertise exactProcess without exactProcess configuration");
-            }
-            return exactProcess
-                ? { ...capabilities, exactProcess: { egress: ["blocked", "strict"] } }
-                : capabilities;
-        },
+        capabilities: resolveCapabilities,
         ...(options.validateProfile ? { validateProfile: options.validateProfile } : {}),
         async create(input) {
+            const capabilities = await resolveCapabilities();
             const createOptions = options.mapCreateInput?.(input) ??
                 sandboxOptionsFromCreateInput(input, options.defaultBackend ?? "opencode");
             const box = await options.client.create(createOptions, input.signal ? { signal: input.signal } : undefined);
-            return sandboxInstanceAsEnvironment(box, providerName, options.client);
+            return sandboxInstanceAsEnvironment(box, providerName, options.client, capabilities);
         },
         ...(options.client.get
             ? {
                 async get(id) {
                     const box = await options.client.get?.(id);
-                    return box ? sandboxInstanceAsEnvironment(box, providerName, options.client) : null;
+                    return box
+                        ? sandboxInstanceAsEnvironment(box, providerName, options.client, await resolveCapabilities())
+                        : null;
                 },
             }
             : {}),
@@ -55,7 +65,7 @@ export function createTangleProvider(options) {
             : {}),
     };
 }
-function sandboxInstanceAsEnvironment(box, providerName, client) {
+function sandboxInstanceAsEnvironment(box, providerName, client, capabilities) {
     return {
         id: String(box.id),
         provider: providerName,
@@ -65,44 +75,60 @@ function sandboxInstanceAsEnvironment(box, providerName, client) {
             return statusFromUnknown(box.status);
         },
         async *stream(input) {
-            for await (const event of box.streamPrompt(promptFromTurnInput(input), promptOptionsFromTurnInput(input))) {
-                yield environmentEventFromSandboxEvent(event);
+            const expectedExecutionId = executionIdFromTurnInput(input);
+            const expectedSessionId = input.sessionId ?? input.controlRef?.sessionId;
+            for await (const event of box.streamPrompt(promptFromTurnInput(input), promptOptionsFromTurnInput(input, {
+                provider: providerName,
+                environmentId: String(box.id),
+            }))) {
+                yield environmentEventFromSandboxEvent(event, {
+                    executionId: expectedExecutionId,
+                    sessionId: expectedSessionId,
+                });
             }
         },
-        ...(box.dispatchPrompt
+        ...(capabilities.streaming.detach && box.dispatchPrompt
             ? {
                 async dispatch(input) {
-                    const dispatched = await box.dispatchPrompt?.(promptFromTurnInput(input), promptOptionsFromTurnInput(input));
-                    return sessionRefFromSandboxDispatch(dispatched, providerName);
+                    const dispatched = await box.dispatchPrompt?.(promptFromTurnInput(input), promptOptionsFromTurnInput(input, {
+                        provider: providerName,
+                        environmentId: String(box.id),
+                    }));
+                    return sessionRefFromSandboxDispatch(dispatched, providerName, String(box.id), executionIdFromTurnInput(input));
                 },
             }
             : {}),
-        ...(box.session
+        ...((capabilities.sessions.continue ||
+            capabilities.streaming.replay ||
+            capabilities.streaming.detach) &&
+            box.session
             ? {
-                session(id) {
+                session(id, options) {
                     const session = box.session?.(id);
                     if (!session)
                         throw new Error("sandbox session(id) returned undefined");
-                    return sandboxSessionAsAgentSession(session);
+                    return sandboxSessionAsAgentSession(session, resolveRetainedSessionControlRef(options?.controlRef, session.id, providerName, String(box.id)), providerName, String(box.id));
                 },
             }
             : {}),
-        ...(box.read ? { read: box.read.bind(box) } : {}),
-        ...(box.write
+        ...(capabilities.workspace.read && box.read
+            ? { read: box.read.bind(box) }
+            : {}),
+        ...(capabilities.workspace.write && box.write
             ? {
                 async write(path, content) {
                     await box.write?.(path, content);
                 },
             }
             : {}),
-        ...(box.exec
+        ...(capabilities.workspace.exec && box.exec
             ? {
                 async exec(command, options) {
                     return execResultFromSandboxExecResult(await box.exec?.(command, options));
                 },
             }
             : {}),
-        ...(box.checkpoint
+        ...(capabilities.branching.checkpoint && box.checkpoint
             ? {
                 async checkpoint(options) {
                     const result = await box.checkpoint?.(options);
@@ -110,19 +136,23 @@ function sandboxInstanceAsEnvironment(box, providerName, client) {
                 },
             }
             : {}),
-        ...(box.fork
+        ...(capabilities.branching.fork && box.fork
             ? {
                 async fork(checkpoint, options) {
                     const forked = await box.fork?.(checkpoint.id, options);
                     if (!forked)
                         throw new Error("sandbox fork returned no environment");
-                    return sandboxInstanceAsEnvironment(forked, providerName, client);
+                    return sandboxInstanceAsEnvironment(forked, providerName, client, capabilities);
+                },
+            }
+            : {}),
+        ...(capabilities.placement
+            ? {
+                async placement() {
+                    return placementInfoFromLoopPlacement(client.describePlacement?.(box), box);
                 },
             }
             : {}),
-        async placement() {
-            return placementInfoFromLoopPlacement(client.describePlacement?.(box), box);
-        },
         async refresh() {
             await box.refresh?.();
         },
@@ -131,9 +161,13 @@ function sandboxInstanceAsEnvironment(box, providerName, client) {
         },
     };
 }
-function sandboxSessionAsAgentSession(session) {
+function sandboxSessionAsAgentSession(session, controlRef, provider, environmentId) {
+    let activeControlRef = controlRef;
     return {
         id: session.id,
+        get controlRef() {
+            return activeControlRef;
+        },
         async status() {
             const status = await session.status();
             if (!status)
@@ -141,17 +175,105 @@ function sandboxSessionAsAgentSession(session) {
             return sessionStatusFromUnknown(status.status);
         },
         async *events(options) {
-            for await (const event of session.events(options))
-                yield environmentEventFromSandboxEvent(event);
+            if (options?.executionId !== undefined &&
+                activeControlRef?.executionId !== undefined &&
+                options.executionId !== activeControlRef.executionId) {
+                throw new Error("Tangle replay executionId conflicts with the control reference");
+            }
+            const executionId = activeControlRef?.executionId ?? options?.executionId;
+            if (options?.since !== undefined && executionId === undefined) {
+                throw new Error("Tangle cursor replay requires an exact executionId from its control reference");
+            }
+            const seenEventIds = new Set();
+            for await (const event of session.events({
+                ...(options?.since !== undefined ? { since: options.since } : {}),
+                ...(executionId !== undefined ? { executionId } : {}),
+                ...(options?.signal ? { signal: options.signal } : {}),
+            })) {
+                if (options?.since !== undefined && event.id === options.since)
+                    continue;
+                const converted = environmentEventFromSandboxEvent(event, {
+                    executionId,
+                    sessionId: session.id,
+                });
+                if (executionId !== undefined && converted.id === undefined) {
+                    throw new Error("Tangle exact session replay received an event without a stable id");
+                }
+                if (converted.id !== undefined) {
+                    if (seenEventIds.has(converted.id)) {
+                        throw new Error(`Tangle session replay repeated event id ${converted.id}`);
+                    }
+                    seenEventIds.add(converted.id);
+                }
+                yield converted;
+            }
         },
         async result() {
-            return agentTurnResultFromPromptResult(await session.result());
+            const expectedExecutionId = activeControlRef?.executionId;
+            if (expectedExecutionId === undefined) {
+                throw new Error("Tangle session result requires an exact executionId from its control reference");
+            }
+            const result = await session.result({ executionId: expectedExecutionId });
+            const resultRecord = validatedSandboxPromptResult(result);
+            if (resultRecord.executionId !== expectedExecutionId) {
+                throw new Error("Tangle session result did not confirm its exact executionId");
+            }
+            return agentTurnResultFromPromptRecord(resultRecord);
         },
         async prompt(input) {
-            return agentTurnResultFromPromptResult(await session.prompt(promptFromTurnInput(input), promptOptionsFromTurnInput(input)));
+            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 !== undefined &&
+                requestedControlRef !== undefined &&
+                !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");
+            }
+            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 result = await session.prompt(promptFromTurnInput(input), promptOptionsFromTurnInput({
+                ...input,
+                sessionId: session.id,
+                executionId,
+                controlRef: undefined,
+            }, {
+                provider,
+                environmentId,
+                sessionId: session.id,
+            }));
+            const resultRecord = validatedSandboxPromptResult(result);
+            if (resultRecord.executionId !== executionId) {
+                throw new Error("Tangle session prompt did not confirm its exact executionId");
+            }
+            if (replay) {
+                activeControlRef =
+                    sourceControlRef ??
+                        retainedSessionControlRef(session.id, executionId, provider, environmentId);
+                return agentTurnResultFromPromptRecord(resultRecord);
+            }
+            activeControlRef = retainedSessionControlRef(session.id, executionId, provider, environmentId);
+            return agentTurnResultFromPromptRecord(resultRecord);
         },
         async cancel() {
-            await session.interrupt();
+            const executionId = activeControlRef?.executionId;
+            if (executionId === undefined) {
+                throw new Error("Tangle session cancellation requires an exact executionId from its control reference");
+            }
+            await session.interrupt({ executionId });
         },
     };
 }
@@ -188,14 +310,42 @@ function inlineAgentProfile(profile) {
     }
     return profile;
 }
-function environmentEventFromSandboxEvent(event) {
-    const data = event.data && typeof event.data === "object"
-        ? event.data
-        : {};
+function environmentEventFromSandboxEvent(event, expected = {}) {
+    if (!event || typeof event !== "object") {
+        throw new Error("Tangle Sandbox emitted a non-object event");
+    }
+    const record = event;
+    if (typeof record.type !== "string" || record.type.length === 0) {
+        throw new Error("Tangle Sandbox event omitted its type");
+    }
+    if (!record.data ||
+        typeof record.data !== "object" ||
+        Array.isArray(record.data)) {
+        throw new Error("Tangle Sandbox event omitted its object data");
+    }
+    if (record.id !== undefined &&
+        (typeof record.id !== "string" || record.id.length === 0)) {
+        throw new Error("Tangle Sandbox event contained an invalid event id");
+    }
+    const data = record.data;
+    const eventExecutionId = optionalNonEmptyString(data.executionId, "Tangle Sandbox event executionId");
+    const eventSessionId = optionalNonEmptyString(data.sessionId, "Tangle Sandbox event sessionId");
+    // Sandbox binds the stream with session.events({ executionId }). Individual
+    // event variants do not all repeat that selector, so validate IDs when present.
+    if (expected.executionId !== undefined &&
+        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) {
+        throw new Error("Tangle exact session event identified a different sessionId");
+    }
     return {
-        type: String(event.type),
+        type: record.type,
         data,
-        ...(event.id ? { id: event.id } : {}),
+        ...(typeof record.id === "string" ? { id: record.id } : {}),
         usage: tokenUsageFromData(data),
         providerEvent: event,
     };
@@ -205,21 +355,102 @@ function promptFromTurnInput(input) {
         return input.parts;
     return input.prompt ?? "";
 }
-function promptOptionsFromTurnInput(input) {
+function executionIdFromTurnInput(input) {
+    return input.executionId ?? input.controlRef?.executionId;
+}
+function promptOptionsFromTurnInput(input, target) {
+    if (input.contextTransfer !== undefined) {
+        throw new Error("Tangle provider does not yet support portable context transfer");
+    }
+    if (input.nativeContinuation !== undefined) {
+        throw new Error("Tangle provider does not yet support verified native continuation");
+    }
+    const controlRef = input.controlRef
+        ? AgentRunControlRefSchema.parse(input.controlRef)
+        : undefined;
+    if (controlRef) {
+        if (controlRef.provider !== target.provider ||
+            controlRef.environmentId !== target.environmentId ||
+            (target.sessionId !== undefined &&
+                controlRef.sessionId !== target.sessionId)) {
+            throw new Error("Tangle control reference does not match this 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");
+        }
+        if (input.executionId !== undefined &&
+            input.executionId !== controlRef.executionId) {
+            throw new Error("Tangle executionId conflicts with the control reference");
+        }
+    }
+    const sessionId = input.sessionId ?? controlRef?.sessionId;
+    const executionId = input.executionId ?? controlRef?.executionId;
     return {
-        ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+        ...(sessionId ? { sessionId } : {}),
         ...(input.model ? { model: input.model } : {}),
-        ...(input.timeoutMs ? { timeoutMs: input.timeoutMs } : {}),
+        ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
         ...(input.context ? { context: input.context } : {}),
         ...(input.signal ? { signal: input.signal } : {}),
-        ...(input.executionId ? { executionId: input.executionId } : {}),
+        ...(executionId ? { executionId } : {}),
         ...(input.lastEventId ? { lastEventId: input.lastEventId } : {}),
         ...(input.turnId ? { turnId: input.turnId } : {}),
         ...(input.detach !== undefined ? { detach: input.detach } : {}),
     };
 }
-function agentTurnResultFromPromptResult(result) {
+function validatedSandboxPromptResult(result) {
+    if (!result || typeof result !== "object" || Array.isArray(result)) {
+        throw new Error("Tangle prompt returned no result object");
+    }
     const record = result;
+    if (typeof record.success !== "boolean") {
+        throw new Error("Tangle prompt result omitted its success status");
+    }
+    const statuses = new Set([
+        "success",
+        "failed",
+        "blocked_on_approval",
+        "awaiting_question",
+        "awaiting_plan_decision",
+    ]);
+    if (typeof record.status !== "string" ||
+        !statuses.has(record.status)) {
+        throw new Error("Tangle prompt result contained an invalid run status");
+    }
+    if (record.success !== (record.status === "success")) {
+        throw new Error("Tangle prompt result success flag conflicts with its run status");
+    }
+    if (typeof record.durationMs !== "number" ||
+        !Number.isFinite(record.durationMs) ||
+        record.durationMs < 0) {
+        throw new Error("Tangle prompt result contained an invalid duration");
+    }
+    for (const field of [
+        "executionId",
+        "response",
+        "text",
+        "finalText",
+        "error",
+        "errorCode",
+        "traceId",
+    ]) {
+        if (record[field] !== undefined && typeof record[field] !== "string") {
+            throw new Error(`Tangle prompt result contained an invalid ${field}`);
+        }
+    }
+    if (record.executionId === "") {
+        throw new Error("Tangle prompt result contained an empty executionId");
+    }
+    tokenUsageFromData(record);
+    return record;
+}
+function agentTurnResultFromPromptRecord(record) {
     const text = typeof record.response === "string"
         ? record.response
         : typeof record.text === "string"
@@ -227,15 +458,22 @@ function agentTurnResultFromPromptResult(result) {
             : typeof record.finalText === "string"
                 ? record.finalText
                 : "";
-    const success = typeof record.success === "boolean" ? record.success : true;
+    const contextTransferReceipt = ContextTransferReceiptSchema.safeParse(record.contextTransferReceipt);
+    if (record.contextTransferReceipt !== undefined &&
+        !contextTransferReceipt.success) {
+        throw new Error("Tangle prompt result contained an invalid context receipt");
+    }
     return {
         text,
-        success,
+        success: record.success,
         ...(typeof record.error === "string" ? { error: record.error } : {}),
         usage: tokenUsageFromData(record),
+        ...(contextTransferReceipt.success
+            ? { contextTransferReceipt: contextTransferReceipt.data }
+            : {}),
     };
 }
-function sessionRefFromSandboxDispatch(dispatched, providerName) {
+function sessionRefFromSandboxDispatch(dispatched, providerName, environmentId, expectedExecutionId) {
     const record = dispatched && typeof dispatched === "object"
         ? dispatched
         : undefined;
@@ -243,21 +481,91 @@ function sessionRefFromSandboxDispatch(dispatched, providerName) {
     if (typeof id !== "string" || id.length === 0 || !record) {
         throw new Error("sandbox dispatch returned no session id");
     }
+    const executionId = nonEmptyString(record.executionId);
+    if (executionId === undefined) {
+        throw new Error("sandbox dispatch returned no exact execution id for durable replay");
+    }
+    if (expectedExecutionId !== undefined &&
+        executionId !== expectedExecutionId) {
+        throw new Error("sandbox dispatch returned an execution id different from the requested run");
+    }
     return {
         id,
         provider: providerName,
+        controlRef: retainedSessionControlRef(id, executionId, providerName, environmentId),
         metadata: {
             ...(record.status ? { status: record.status } : {}),
             ...(record.alreadyExisted !== undefined ? { alreadyExisted: record.alreadyExisted } : {}),
+            ...(record.dispatched !== undefined ? { dispatched: record.dispatched } : {}),
         },
     };
 }
+function retainedSessionControlRef(sessionId, executionId, provider, environmentId) {
+    return AgentRunControlRefSchema.parse({
+        runId: executionId,
+        provider,
+        environmentId,
+        sessionId,
+        executionId,
+    });
+}
+function sessionPromptExecutionId(provider, environmentId, sessionId, turnId) {
+    if (turnId === undefined)
+        return randomUUID();
+    const digest = createHash("sha256")
+        .update(`${provider}\0${environmentId}\0${sessionId}\0${turnId}`)
+        .digest("hex");
+    return `session-turn-${digest}`;
+}
+function sameRunControlRef(left, right) {
+    return (left.runId === right.runId &&
+        left.provider === right.provider &&
+        left.environmentId === right.environmentId &&
+        left.sessionId === right.sessionId &&
+        left.executionId === right.executionId);
+}
+function resolveRetainedSessionControlRef(candidate, sessionId, provider, environmentId) {
+    if (candidate === undefined)
+        return undefined;
+    const controlRef = AgentRunControlRefSchema.parse(candidate);
+    if (controlRef.provider !== provider ||
+        controlRef.environmentId !== environmentId ||
+        controlRef.sessionId !== sessionId) {
+        throw new Error("Tangle control reference does not match this session");
+    }
+    if (controlRef.executionId === undefined ||
+        controlRef.runId !== controlRef.executionId) {
+        throw new Error("Tangle session control reference requires runId to equal executionId");
+    }
+    return controlRef;
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function optionalNonEmptyString(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`${label} must be a non-empty string`);
+    }
+    return value;
+}
 function execResultFromSandboxExecResult(result) {
-    const record = (result ?? {});
+    if (!result || typeof result !== "object") {
+        throw new Error("Tangle Sandbox exec returned no result");
+    }
+    const record = result;
+    if (typeof record.exitCode !== "number" ||
+        !Number.isSafeInteger(record.exitCode)) {
+        throw new Error("Tangle Sandbox exec returned an invalid exit code");
+    }
+    if (typeof record.stdout !== "string" || typeof record.stderr !== "string") {
+        throw new Error("Tangle Sandbox exec returned invalid output streams");
+    }
     return {
-        exitCode: finiteNumber(record.exitCode) ?? finiteNumber(record.code) ?? 0,
-        stdout: typeof record.stdout === "string" ? record.stdout : "",
-        stderr: typeof record.stderr === "string" ? record.stderr : "",
+        exitCode: record.exitCode,
+        stdout: record.stdout,
+        stderr: record.stderr,
     };
 }
 function checkpointIdFromResult(result) {
@@ -280,22 +588,26 @@ function placementInfoFromLoopPlacement(placement, box) {
     };
 }
 function tokenUsageFromData(data) {
+    if (data.usage !== undefined &&
+        (!data.usage || typeof data.usage !== "object" || Array.isArray(data.usage))) {
+        throw new Error("Tangle usage must be an object");
+    }
+    if (data.tokenUsage !== undefined &&
+        (!data.tokenUsage ||
+            typeof data.tokenUsage !== "object" ||
+            Array.isArray(data.tokenUsage))) {
+        throw new Error("Tangle token usage must be an object");
+    }
     const usageRecord = data.usage && typeof data.usage === "object"
         ? data.usage
         : data.tokenUsage && typeof data.tokenUsage === "object"
             ? data.tokenUsage
             : data;
-    const inputTokens = finiteNumber(usageRecord.inputTokens) ??
-        finiteNumber(usageRecord.tokensIn) ??
-        finiteNumber(usageRecord.prompt_tokens);
-    const outputTokens = finiteNumber(usageRecord.outputTokens) ??
-        finiteNumber(usageRecord.tokensOut) ??
-        finiteNumber(usageRecord.completion_tokens);
-    const cost = finiteNumber(usageRecord.cost) ??
-        finiteNumber(usageRecord.costUsd) ??
-        finiteNumber(usageRecord.totalCostUsd) ??
-        finiteNumber(data.costUsd) ??
-        finiteNumber(data.totalCostUsd);
+    const inputTokens = firstValidatedNumber(usageRecord, ["inputTokens", "tokensIn", "prompt_tokens"], "input token count", true);
+    const outputTokens = firstValidatedNumber(usageRecord, ["outputTokens", "tokensOut", "completion_tokens"], "output token count", true);
+    const nestedCost = firstValidatedNumber(usageRecord, ["cost", "costUsd", "totalCostUsd"], "usage cost", false);
+    const topLevelCost = firstValidatedNumber(data, ["costUsd", "totalCostUsd"], "result cost", false);
+    const cost = nestedCost ?? topLevelCost;
     if (inputTokens === undefined && outputTokens === undefined && cost === undefined)
         return undefined;
     return {
@@ -304,6 +616,22 @@ function tokenUsageFromData(data) {
         ...(cost !== undefined ? { cost } : {}),
     };
 }
+function firstValidatedNumber(record, fields, label, integer) {
+    let selected;
+    for (const field of fields) {
+        const value = record[field];
+        if (value === undefined)
+            continue;
+        if (typeof value !== "number" ||
+            !Number.isFinite(value) ||
+            value < 0 ||
+            (integer && !Number.isSafeInteger(value))) {
+            throw new Error(`Tangle ${label} is invalid`);
+        }
+        selected ??= value;
+    }
+    return selected;
+}
 function statusFromUnknown(status) {
     if (status === "pending" || status === "provisioning" || status === "running")
         return status;
@@ -318,9 +646,6 @@ function sessionStatusFromUnknown(status) {
         return status;
     return statusFromUnknown(status);
 }
-function finiteNumber(value) {
-    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
-}
 export function defaultTangleSandboxCapabilities() {
     return {
         profile: {
@@ -347,7 +672,7 @@ export function defaultTangleSandboxCapabilities() {
         streaming: { live: true, replay: true, detach: true, turnIdempotency: true },
         sessions: { continue: true, list: true, messages: true },
         workspace: { read: true, write: true, exec: true, git: true, upload: true, download: true },
-        branching: { checkpoint: true, fork: true },
+        branching: { checkpoint: false, fork: false },
         placement: true,
         usage: true,
         confidential: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",
@@ -31,10 +31,10 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "0.40.0"
+    "@tangle-network/agent-interface": "0.41.0"
   },
   "peerDependencies": {
-    "@tangle-network/sandbox": ">=0.13.0-develop.20260726215211.b0dddb3 <1.0.0"
+    "@tangle-network/sandbox": ">=0.17.0 <1.0.0"
   },
   "peerDependenciesMeta": {
     "@tangle-network/sandbox": {
@@ -42,11 +42,11 @@
     }
   },
   "devDependencies": {
-    "@tangle-network/sandbox": "0.13.0-develop.20260726215211.b0dddb3",
+    "@tangle-network/sandbox": "0.17.0",
     "@types/node": "25.6.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5",
-    "@tangle-network/agent-provider-testkit": "0.3.10"
+    "@tangle-network/agent-provider-testkit": "0.4.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",