@tangle-network/agent-provider-tangle 0.6.3 → 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'
@@ -15,13 +16,23 @@ 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 both the agent interface and Sandbox session stream.
 Result, replay, and cancel operations select that exact execution instead of whichever execution most recently changed the shared session.
-Retained control is advertised only when the Sandbox exposes dispatch, replay, exact results and events, turn idempotency, and `cancelRun`; native continuation remains absent.
+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,39 +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.
- * Per-sandbox retained-run claims are narrowed later, after a concrete
- * session handle proves that cancelRun is available.
+ * 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,11 +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.
-        // Retained control stays opt-in until a concrete session exposes cancelRun.
-        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,
@@ -44,128 +57,153 @@ export function defaultTangleSandboxCapabilities(harness) {
         confidential: false,
     };
 }
-const CAPABILITY_PROBE_SESSION_ID = "__tangle-capability-probe__";
+// 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_SESSION_ID);
+            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.
- * Per-sandbox retained-run claims are narrowed later, after a concrete
- * session handle proves that cancelRun is available.
+ * 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 canReconstructRetainedEnvironment = typeof client.get === "function";
-    const narrowed = {
-        ...declared,
-        streaming: {
-            ...declared.streaming,
-            replay: declared.streaming.replay,
-            detach: declared.streaming.detach,
-            turnIdempotency: declared.streaming.turnIdempotency,
-        },
-        sessions: {
-            ...declared.sessions,
-            continue: declared.sessions.continue && canReconstructRetainedEnvironment,
-            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;
-    if (!canReconstructRetainedEnvironment)
-        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 };
-    const supportsRetainedControl = declared.sessions.continue &&
-        declared.streaming.detach &&
-        declared.streaming.replay &&
-        declared.streaming.turnIdempotency &&
+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;
-    delete narrowed.interactions;
-    delete narrowed.nativeContinuation;
-    if (!supportsRetainedControl)
-        delete narrowed.retainedControl;
-    return {
-        ...narrowed,
+    // 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: declared.sessions.continue && supportsRetainedControl,
+            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.js

@@ -33,17 +33,10 @@ export async function interruptAfterAbort(box, reference) {
     // Only a receipt that proves this call admitted new work may be interrupted.
     if (metadata?.dispatched !== true || metadata.alreadyExisted === true)
         return;
-    const sessionId = reference.id;
     const executionId = reference.controlRef?.executionId;
     if (!box.session || executionId === undefined)
         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-session.js

@@ -4,7 +4,7 @@ import { AgentRunCancellationAcknowledgementSchema, AgentRunCancellationRequestS
 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";
@@ -47,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) {

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";
@@ -104,6 +104,10 @@ export function sandboxInstanceAsEnvironment(box, providerName, client, declared
                         throw new Error("sandbox session(id) returned an unrelated session");
                     }
                     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");
@@ -152,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-prompt.d.ts

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

package/dist/tangle-provider.js

@@ -15,7 +15,7 @@ export function createTangleProvider(options) {
             providerName,
         })
         : undefined;
-    const resolveCapabilities = async () => {
+    const resolveDeclaredCapabilities = async () => {
         const configured = options.capabilities
             ? typeof options.capabilities === "function"
                 ? await options.capabilities()
@@ -24,14 +24,17 @@ export function createTangleProvider(options) {
         if (!exactProcess && configured.exactProcess) {
             throw new Error("Tangle capabilities cannot advertise exactProcess without exactProcess configuration");
         }
-        const withExactProcess = exactProcess
+        return exactProcess
             ? {
                 ...configured,
                 exactProcess: { egress: ["blocked", "strict"] },
             }
             : configured;
-        return AgentEnvironmentCapabilitiesSchema.parse(capabilitiesForClient(withExactProcess, options.client));
     };
+    // Provider-boundary document: client-stage facts only. It also validates
+    // the configured document, so create() and get() call it before any effect.
+    const narrowedProviderCapabilities = (declared) => AgentEnvironmentCapabilitiesSchema.parse(capabilitiesForClient(declared, options.client));
+    const resolveCapabilities = async () => narrowedProviderCapabilities(await resolveDeclaredCapabilities());
     return {
         name: providerName,
         ...(exactProcess ? { exactProcess } : {}),
@@ -44,7 +47,11 @@ export function createTangleProvider(options) {
             if (input.providerOptions && Object.keys(input.providerOptions).length > 0) {
                 throw new Error("Tangle create providerOptions are not supported");
             }
-            const capabilities = await resolveCapabilities();
+            // The sandbox stage narrows from the declared document, not the
+            // provider-boundary one: the client stage cannot observe box-scoped
+            // facts, so measured instance facts must decide them per sandbox.
+            const declaredCapabilities = await resolveDeclaredCapabilities();
+            narrowedProviderCapabilities(declaredCapabilities);
             const createOptions = options.mapCreateInput?.(input) ??
                 sandboxOptionsFromCreateInput(input, options.defaultBackend ?? "opencode");
             assertMappedCreateOptions(createOptions);
@@ -76,7 +83,7 @@ export function createTangleProvider(options) {
             }
             try {
                 input.signal?.throwIfAborted();
-                const environment = sandboxInstanceAsEnvironment(box, providerName, options.client, capabilities);
+                const environment = sandboxInstanceAsEnvironment(box, providerName, options.client, declaredCapabilities);
                 input.signal?.throwIfAborted();
                 return environment;
             }
@@ -101,14 +108,14 @@ export function createTangleProvider(options) {
                 async get(id, operation) {
                     assertProviderOperationOptions(operation, "Tangle get");
                     boundedIdentifier(id, "Tangle environment id");
+                    const declaredCapabilities = await resolveDeclaredCapabilities();
+                    narrowedProviderCapabilities(declaredCapabilities);
                     operation?.signal?.throwIfAborted();
                     const box = await awaitWithSignal(options.client.get?.(id, operation), operation?.signal);
                     operation?.signal?.throwIfAborted();
                     if (!box || boundedIdentifier(box.id, "Tangle environment id") !== id)
                         return null;
-                    return box
-                        ? sandboxInstanceAsEnvironment(box, providerName, options.client, await resolveCapabilities())
-                        : null;
+                    return sandboxInstanceAsEnvironment(box, providerName, options.client, declaredCapabilities);
                 },
             }
             : {}),

package/dist/tangle-types.d.ts

@@ -1,9 +1,6 @@
 import type { BackendType, CreateSandboxOptions, ExecResult as SandboxExecResult, PromptOptions, PromptResult, SandboxEvent } from "@tangle-network/sandbox";
-import type { AgentExactRunControlRef, AgentRunCancellationAcknowledgement, AgentRunCancellationRequest, InputPart } from "@tangle-network/agent-interface";
+import type { AgentRunCancellationAcknowledgement, AgentRunCancellationRequest, InputPart } from "@tangle-network/agent-interface";
 import type { AgentEnvironmentCapabilities, AgentEnvironmentProvider, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
-export type TanglePromptOptions = PromptOptions & {
-    runControlRef?: AgentExactRunControlRef;
-};
 export interface TangleExactProcessOptions {
     teamId?: string;
 }
@@ -12,6 +9,17 @@ export interface SandboxClientLike {
         signal?: AbortSignal;
         timeoutMs?: number;
     }): Promise<SandboxInstanceLike>;
+    /**
+     * SDK HttpClient transport, present on `Sandbox` and `TangleSandboxClient`.
+     * Retained control requires it: the provider mints a lazy probe instance
+     * over this surface to read the linked SDK's method surface before any
+     * sandbox exists. An object-spread wrapper (`{ ...client }`) drops class
+     * prototype methods including this one, so such a wrapper never claims
+     * retained control; pass the SDK client itself or delegate its methods.
+     */
+    fetch?(path: string, options?: RequestInit, fetchOptions?: {
+        timeoutMs?: number;
+    }): Promise<Response>;
     get?(id: string, requestOptions?: {
         signal?: AbortSignal;
     }): Promise<SandboxInstanceLike | null>;
@@ -56,9 +64,9 @@ export interface SandboxInstanceLike {
     name?: string;
     status?: unknown;
     metadata?: Record<string, unknown>;
-    streamPrompt(message: string | InputPart[], options?: TanglePromptOptions): AsyncIterable<SandboxEvent>;
-    prompt?(message: string | InputPart[], options?: TanglePromptOptions): Promise<PromptResult>;
-    dispatchPrompt?(message: string | InputPart[], options?: TanglePromptOptions): Promise<unknown>;
+    streamPrompt(message: string | InputPart[], options?: PromptOptions): AsyncIterable<SandboxEvent>;
+    prompt?(message: string | InputPart[], options?: PromptOptions): Promise<PromptResult>;
+    dispatchPrompt?(message: string | InputPart[], options?: PromptOptions): Promise<unknown>;
     session?(id: string, options?: {
         signal?: AbortSignal;
     }): SandboxSessionLike;
@@ -98,12 +106,6 @@ export interface SandboxInstanceLike {
         }): Promise<unknown>;
     };
     process?: SandboxProcessManagerLike;
-    checkpoint?(options?: {
-        signal?: AbortSignal;
-    } & Record<string, unknown>): Promise<unknown>;
-    fork?(checkpointId: string, options?: {
-        signal?: AbortSignal;
-    } & Record<string, unknown>): Promise<SandboxInstanceLike>;
     refresh?(options?: {
         signal?: AbortSignal;
     }): Promise<void>;
@@ -125,7 +127,7 @@ export interface SandboxSessionLike {
         executionId?: string;
         signal?: AbortSignal;
     }): Promise<PromptResult>;
-    prompt(message: string | InputPart[], options?: TanglePromptOptions): Promise<PromptResult>;
+    prompt(message: string | InputPart[], options?: PromptOptions): Promise<PromptResult>;
     interrupt(options?: {
         executionId?: string;
         signal?: AbortSignal;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",
@@ -70,7 +70,7 @@
     "@tangle-network/agent-interface": "0.47.0"
   },
   "peerDependencies": {
-    "@tangle-network/sandbox": ">=0.17.0 <1.0.0"
+    "@tangle-network/sandbox": ">=0.19.6 <1.0.0"
   },
   "peerDependenciesMeta": {
     "@tangle-network/sandbox": {
@@ -78,8 +78,9 @@
     }
   },
   "devDependencies": {
-    "@tangle-network/agent-runtime": "0.132.6",
-    "@tangle-network/sandbox": "0.19.4",
+    "@tangle-network/agent-eval": "0.145.3",
+    "@tangle-network/agent-runtime": "0.132.13",
+    "@tangle-network/sandbox": "0.21.1",
     "@types/node": "25.6.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5",