@tangle-network/agent-provider-tangle 0.13.2 → 0.14.0

package/README.md

@@ -1,8 +1,9 @@
 # @tangle-network/agent-provider-tangle
 
 Wraps `@tangle-network/sandbox` as an `AgentEnvironmentProvider`.
-The peer range is `>=0.30.1 <1.0.0`, and this package is developed and tested against 0.30.1.
-The floor is 0.30.1 because interaction claims use the Sandbox backend catalog exposed by `listBackends()`.
+The peer range is `>=0.33.1 <1.0.0`, and this package is developed and tested against 0.33.1.
+The floor is 0.33.1 because workspace branching uses the keyed snapshot, fork,
+lookup, and cleanup operations added to that SDK.
 The provider fails closed when the configured backend or its catalog entry cannot be read.
 Newer SDKs may also provide `getBackend()` as a lookup over the same catalog.
 
@@ -104,8 +105,95 @@ After `session.prompt()` admits another turn, that session object's `controlRef`
 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 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.
+
+### Workspace branching
+
+`environment.workspaceBranching` is the single operation surface for creating
+and recovering a checkpoint, forking one managed child, and cleaning both
+resources in dependency order.
+The adapter advertises `branching.checkpoint`, `branching.fork`, `retrySafe`,
+`lookup`, and `cleanup` only when the linked SDK exposes the complete managed
+surface: keyed `snapshot` and `fork`, operation lookup, inventory recovery, and
+explicit deletion outcomes.
+An incomplete SDK surface clears every branching flag and omits
+`environment.workspaceBranching`.
+
+Every operation validates the canonical agent-interface request digest before
+calling Sandbox.
+Retries with the same key replay the original resource, while changed material
+returns a conflict containing the original interface digest.
+The provider stores a bounded request marker in snapshot tags and child
+metadata so a fresh process can recover the exact interface digest, but the
+marker only names a candidate: the Sandbox operation ledger still has to report
+a settled success before the adapter returns the resource.
+Checkpoint deletion reports `in_use` with every verified child that still
+references it; delete the child first, then retry checkpoint deletion.
+The adapter never treats an SDK response without an explicit idempotency or
+deletion outcome as success.
+
+After a provider process restart, `provider.workspaceBranching.forEnvironment()`
+returns a fresh source-scoped handle for lookup and cleanup, or `null` when it
+cannot prove the complete operation surface.
+
+Recovery reads the account inventory through Sandbox offset pages of at most
+1,000 sandboxes and continues until a short page proves the inventory is
+complete.
+The adapter also reads checkpoints from the previous marker format while writing only the current bounded format.
+Malformed, repeated, failed, or over-bound pages return `unknown` and do not
+mutate a resource.
+Sandbox exposes snapshots only through the live source instance.
+If that source was deleted, this provider cannot recover its checkpoints or
+forked children through the public SDK.
+Clean branch resources before deleting the source or use a platform reaper.
+
+```ts
+import {
+  workspaceCheckpointRequestDigest,
+  workspaceForkRequestDigest,
+} from '@tangle-network/agent-interface'
+
+const checkpoint = await environment.workspaceBranching?.checkpoint({
+  source: exactRun,
+  idempotencyKey: 'checkpoint-before-analysis',
+  requestDigest: workspaceCheckpointRequestDigest({ source: exactRun }),
+})
+
+if (checkpoint?.status === 'created' || checkpoint?.status === 'replayed') {
+  const fork = await environment.workspaceBranching?.fork({
+    checkpoint: checkpoint.checkpoint,
+    placement: { kind: 'sandbox', sandboxId: 'analysis-worker' },
+    idempotencyKey: 'analysis-worker',
+    requestDigest: workspaceForkRequestDigest({
+      checkpoint: checkpoint.checkpoint,
+      placement: { kind: 'sandbox', sandboxId: 'analysis-worker' },
+    }),
+  })
+}
+```
+
+### Confidential forks
+
+Sandbox returns raw TEE evidence, not a verified claim.
+Pass `confidentialAttestationVerifier` to `createTangleProvider` to connect a
+trusted provider-key and measurement verifier.
+The callback receives the raw report, the expected environment binding, and
+the canonical request-bound attestation material.
+It returns a provider key id, signature, and optional normalized measurement
+only after verification succeeds.
+Returning `null`, throwing, a mismatched measurement, or a copied quote leaves
+the result unverified while preserving `confidentialRequested: true`.
+The same unverified result occurs when no trusted verifier is configured.
+The adapter does not trust the requested nonce, child metadata, or any legacy
+`confidential: true` assertion as proof.
+`verifyTangleQuote` below represents a verifier supplied by the caller.
+
+```ts
+const provider = createTangleProvider({
+  client: new Sandbox({ apiKey: process.env.TANGLE_API_KEY }),
+  confidentialAttestationVerifier: async ({ report, attestation }) =>
+    (await verifyTangleQuote({ report, attestation })) ?? null,
+})
+```
 
 ## Environment observation
 

package/dist/exact-process.js

@@ -1,8 +1,7 @@
-import { assertBoundedJson, attachCleanupHandle, awaitWithSignal, boundedIdentifier, boundedString, exactProcessRequestDigest, isBoundedJson, MAX_LIST_RESULTS, } from "./tangle-contract-safety.js";
+import { assertBoundedJson, attachCleanupHandle, awaitWithSignal, boundedIdentifier, boundedString, exactProcessRequestDigest, isBoundedJson, MAX_LIST_RESULTS, SANDBOX_LIST_PAGE_SIZE, } from "./tangle-contract-safety.js";
 import { sandboxInstanceAsExactProcessEnvironment } from "./tangle-exact-process-environment.js";
 import { assertExactProcessSandbox, assertSupportedProviderOptions, assertUnreservedMetadata, EXACT_PROCESS_METADATA_KEY, isExactProcessRequestConflict, isExactProcessSandbox, metadataMatches, assertSignalOptions, } from "./tangle-exact-process-validation.js";
 const IMMUTABLE_TANGLE_IMAGE = /^(?:sha256:[a-f0-9]{64}|\S+@sha256:[a-f0-9]{64})$/i;
-const LIST_PAGE_SIZE = 1_000;
 export function createTangleExactProcessProvider(input) {
     const { client, options, providerName } = input;
     boundedIdentifier(providerName, "Tangle exact process provider");
@@ -98,7 +97,7 @@ export function createTangleExactProcessProvider(input) {
             assertSupportedProviderOptions(query?.providerOptions);
             assertExactProcessListQuery(query);
             const matches = [];
-            for (let offset = 0;; offset += LIST_PAGE_SIZE) {
+            for (let offset = 0;; offset += SANDBOX_LIST_PAGE_SIZE) {
                 if (offset > MAX_LIST_RESULTS) {
                     throw new Error("Tangle exact process list exceeded its page bound");
                 }
@@ -107,11 +106,11 @@ export function createTangleExactProcessProvider(input) {
                     ...(options.teamId
                         ? { scope: `team:${options.teamId}` }
                         : { scope: "personal" }),
-                    limit: LIST_PAGE_SIZE,
+                    limit: SANDBOX_LIST_PAGE_SIZE,
                     offset,
                     ...(signal ? { signal } : {}),
                 }), signal);
-                if (!Array.isArray(page) || page.length > LIST_PAGE_SIZE) {
+                if (!Array.isArray(page) || page.length > SANDBOX_LIST_PAGE_SIZE) {
                     throw new Error("Tangle exact process list returned an invalid page size");
                 }
                 if (offset + page.length > MAX_LIST_RESULTS) {
@@ -132,7 +131,7 @@ export function createTangleExactProcessProvider(input) {
                         }
                     }
                 }
-                if (page.length < LIST_PAGE_SIZE)
+                if (page.length < SANDBOX_LIST_PAGE_SIZE)
                     return matches;
             }
         },

package/dist/index.d.ts

@@ -2,4 +2,6 @@ export type { TangleExactProcessOptions } from "./tangle-types.js";
 export * from "./tangle-types.js";
 export { createTangleProvider } from "./tangle-provider.js";
 export { defaultTangleSandboxCapabilities } from "./tangle-capabilities.js";
+export { createTangleWorkspaceBranching, supportsWorkspaceBranching, } from "./tangle-workspace-branching.js";
+export type { TangleWorkspaceBranchingOptions } from "./tangle-workspace-branching.js";
 export { safeEndpointFromConnection } from "./tangle-observation.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from "./tangle-types.js";
 export { createTangleProvider } from "./tangle-provider.js";
 export { defaultTangleSandboxCapabilities } from "./tangle-capabilities.js";
+export { createTangleWorkspaceBranching, supportsWorkspaceBranching, } from "./tangle-workspace-branching.js";
 export { safeEndpointFromConnection } from "./tangle-observation.js";

package/dist/tangle-capabilities.d.ts

@@ -4,6 +4,7 @@ import type { SandboxClientLike, SandboxInstanceLike } from "./tangle-types.js";
 import type { DeploymentCapabilitySupport } from "./tangle-deployment-capabilities.js";
 import type { ResourceProfile } from "@tangle-network/agent-interface";
 import { type ObservationSurfaceSupport } from "./tangle-observation.js";
+import type { TangleConfidentialAttestationVerifier } from "./tangle-types.js";
 /**
  * The full capability document this adapter supports when the Sandbox client
  * implements every optional method.
@@ -47,6 +48,10 @@ export interface SandboxCapabilitySupport {
     interactiveTerminal: boolean;
     /** The SDK can drive the existing native TUI and read its terminal metadata. */
     interactiveAgent: boolean;
+    /** Snapshot/fork methods and inventory recovery are all present. */
+    workspaceBranching: boolean;
+    /** The SDK can request raw TEE evidence for this sandbox. */
+    confidentialAttestation: boolean;
 }
 export declare function sandboxCapabilitySupport(box: SandboxInstanceLike, client: SandboxClientLike, requestedResources?: ResourceProfile): SandboxCapabilitySupport;
 /**
@@ -99,7 +104,9 @@ export declare function tangleInteractiveAgentSupported(declared: AgentEnvironme
  * idempotency needs the deployment to honor the exact reference that
  * identifies a repeated turn.
  */
-export declare function narrowedTangleCapabilities(declared: AgentEnvironmentCapabilities, support: SandboxCapabilitySupport, deployment: DeploymentCapabilitySupport): AgentEnvironmentCapabilities;
+export declare function narrowedTangleCapabilities(declared: AgentEnvironmentCapabilities, support: SandboxCapabilitySupport, deployment: DeploymentCapabilitySupport, options?: {
+    confidentialAttestationVerifier?: TangleConfidentialAttestationVerifier;
+}): AgentEnvironmentCapabilities;
 /**
  * Narrow provider-level claims to facts the client can prove before any
  * sandbox exists.
@@ -112,7 +119,9 @@ export declare function narrowedTangleCapabilities(declared: AgentEnvironmentCap
  * the answer as `AgentEnvironment.capabilities`, which is the document a
  * caller reads to decide which operation to offer against that environment.
  */
-export declare function capabilitiesForClient(declared: AgentEnvironmentCapabilities, client: SandboxClientLike): AgentEnvironmentCapabilities;
+export declare function capabilitiesForClient(declared: AgentEnvironmentCapabilities, client: SandboxClientLike, options?: {
+    confidentialAttestationVerifier?: TangleConfidentialAttestationVerifier;
+}): AgentEnvironmentCapabilities;
 /**
  * Freeze a capability document before an environment publishes it.
  *
@@ -125,4 +134,6 @@ export declare function frozenCapabilityDocument<T>(document: T): T;
  * Narrow a declared capability document to what this Sandbox instance backs
  * and what the deployment behind it reports.
  */
-export declare function capabilitiesForSandbox(declared: AgentEnvironmentCapabilities, support: SandboxCapabilitySupport, deployment: DeploymentCapabilitySupport): AgentEnvironmentCapabilities;
+export declare function capabilitiesForSandbox(declared: AgentEnvironmentCapabilities, support: SandboxCapabilitySupport, deployment: DeploymentCapabilitySupport, options?: {
+    confidentialAttestationVerifier?: TangleConfidentialAttestationVerifier;
+}): AgentEnvironmentCapabilities;

package/dist/tangle-capabilities.js

@@ -4,6 +4,7 @@ import { ADAPTER_CEILING_DEPLOYMENT, deploymentBacksInteractiveAgent, deployment
 import { clientObservationSurfaceSupport, observationSurfaceSupport, } from "./tangle-observation.js";
 import { sandboxBacksInteractiveTerminal } from "./tangle-terminal.js";
 import { sandboxBacksInteractiveAgent } from "./tangle-interactive.js";
+import { supportsWorkspaceBranching } from "./tangle-workspace-branching.js";
 /**
  * The full capability document this adapter supports when the Sandbox client
  * implements every optional method.
@@ -72,14 +73,20 @@ export function defaultTangleSandboxCapabilities(harness) {
             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 },
+        // The complete Sandbox SDK surface backs this contract. Narrowing below
+        // removes every flag when any recovery or cleanup method is absent.
+        branching: {
+            checkpoint: true,
+            fork: true,
+            retrySafe: true,
+            lookup: true,
+            cleanup: true,
+        },
         placement: true,
         usage: false,
-        // Confidential execution needs verified attestation evidence, which this
-        // adapter does not yet obtain, so it is never declared by default.
-        confidential: false,
+        // This is intent only. Narrowing requires both raw TEE evidence and the
+        // caller's external provider-key verifier before the flag survives.
+        confidential: true,
         // Observation surfaces are declared as intent and narrowed per sandbox to
         // the sources that can put a value on each one.
         observation: {
@@ -171,6 +178,8 @@ export function sandboxCapabilitySupport(box, client, requestedResources) {
         observation: observationSurfaceSupport(box, client, requestedResources),
         interactiveTerminal: sandboxBacksInteractiveTerminal(box),
         interactiveAgent: sandboxBacksInteractiveAgent(box),
+        workspaceBranching: supportsWorkspaceBranching(box, client),
+        confidentialAttestation: typeof box.getTeeAttestation === "function",
     };
 }
 /**
@@ -231,6 +240,8 @@ export function clientCapabilitySupport(client) {
         observation,
         interactiveTerminal: true,
         interactiveAgent: false,
+        workspaceBranching: false,
+        confidentialAttestation: false,
     };
 }
 /**
@@ -292,7 +303,14 @@ export function tangleInteractiveAgentSupported(declared, support, deployment) {
  * idempotency needs the deployment to honor the exact reference that
  * identifies a repeated turn.
  */
-export function narrowedTangleCapabilities(declared, support, deployment) {
+export function narrowedTangleCapabilities(declared, support, deployment, options) {
+    // JavaScript callers can omit required fields before schema validation.
+    // Missing branching intent must disable the surface, not throw while it is
+    // being narrowed.
+    const declaredBranching = declared.branching ?? {
+        checkpoint: false,
+        fork: false,
+    };
     const supportsRetainedControl = tangleRetainedControlSupported(declared, support, deployment);
     const supportsDetach = support.dispatchPrompt && support.session && deployment.exactDispatch;
     // A cleared fact forces false; a held fact passes the declared value
@@ -325,14 +343,18 @@ export function narrowedTangleCapabilities(declared, support, deployment) {
             upload: support.write ? declared.workspace.upload : false,
             download: support.read ? declared.workspace.download : 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 } : {}),
-        },
+        // An incomplete Sandbox surface clears every branching flag together. A
+        // partial claim would let a caller start an operation it cannot recover.
+        branching: support.workspaceBranching
+            ? { ...declaredBranching }
+            : {
+                ...declaredBranching,
+                checkpoint: false,
+                fork: false,
+                ...(declaredBranching.retrySafe !== undefined ? { retrySafe: false } : {}),
+                ...(declaredBranching.lookup !== undefined ? { lookup: false } : {}),
+                ...(declaredBranching.cleanup !== undefined ? { cleanup: false } : {}),
+            },
         placement: support.placement ? declared.placement : false,
         usage: false,
         ...(declared.observation === undefined
@@ -358,6 +380,11 @@ export function narrowedTangleCapabilities(declared, support, deployment) {
     delete narrowed.nativeContinuation;
     if (!supportsRetainedControl)
         delete narrowed.retainedControl;
+    if (narrowed.confidential &&
+        (!support.confidentialAttestation ||
+            typeof options?.confidentialAttestationVerifier !== "function")) {
+        narrowed.confidential = false;
+    }
     return narrowed;
 }
 /**
@@ -417,8 +444,8 @@ function narrowedInteractiveAgent(declared, supported) {
  * the answer as `AgentEnvironment.capabilities`, which is the document a
  * caller reads to decide which operation to offer against that environment.
  */
-export function capabilitiesForClient(declared, client) {
-    return narrowedTangleCapabilities(declared, clientCapabilitySupport(client), ADAPTER_CEILING_DEPLOYMENT);
+export function capabilitiesForClient(declared, client, options) {
+    return narrowedTangleCapabilities(declared, clientCapabilitySupport(client), ADAPTER_CEILING_DEPLOYMENT, options);
 }
 /**
  * Freeze a capability document before an environment publishes it.
@@ -434,6 +461,6 @@ export function frozenCapabilityDocument(document) {
  * Narrow a declared capability document to what this Sandbox instance backs
  * and what the deployment behind it reports.
  */
-export function capabilitiesForSandbox(declared, support, deployment) {
-    return narrowedTangleCapabilities(declared, support, deployment);
+export function capabilitiesForSandbox(declared, support, deployment, options) {
+    return narrowedTangleCapabilities(declared, support, deployment, options);
 }

package/dist/tangle-contract-safety.d.ts

@@ -2,6 +2,8 @@ import type { CreateAgentExactProcessEnvironmentInput } from "@tangle-network/ag
 import type { TangleExactProcessOptions } from "./tangle-types.js";
 export declare const MAX_EXACT_FILE_BYTES: number;
 export declare const MAX_LIST_RESULTS = 100000;
+/** Sandbox caps list responses at 1,000 resources. */
+export declare const SANDBOX_LIST_PAGE_SIZE = 1000;
 export declare const MAX_IDENTIFIER_LENGTH = 512;
 export declare const MAX_STRING_LENGTH = 16384;
 export declare const MAX_ARRAY_LENGTH = 1024;

package/dist/tangle-contract-safety.js

@@ -1,6 +1,8 @@
 import { canonicalCandidateDigest } from "@tangle-network/agent-interface";
 export const MAX_EXACT_FILE_BYTES = 64 * 1024 * 1024;
 export const MAX_LIST_RESULTS = 100_000;
+/** Sandbox caps list responses at 1,000 resources. */
+export const SANDBOX_LIST_PAGE_SIZE = 1_000;
 export const MAX_IDENTIFIER_LENGTH = 512;
 export const MAX_STRING_LENGTH = 16_384;
 export const MAX_ARRAY_LENGTH = 1_024;

package/dist/tangle-environment.d.ts

@@ -1,5 +1,6 @@
 import type { AgentEnvironment, AgentEnvironmentCapabilities, ResourceProfile } from "@tangle-network/agent-interface/environment-provider";
 import type { SandboxClientLike, SandboxInstanceLike } from "./tangle-types.js";
+import type { TangleConfidentialAttestationVerifier } from "./tangle-types.js";
 /**
  * Compose one concrete sandbox into an environment.
  *
@@ -25,4 +26,5 @@ export declare function sandboxInstanceAsEnvironment(box: SandboxInstanceLike, p
     signal?: AbortSignal;
 }, request?: {
     resources?: ResourceProfile;
+    confidentialAttestationVerifier?: TangleConfidentialAttestationVerifier;
 }): Promise<AgentEnvironment>;

package/dist/tangle-environment.js

@@ -17,6 +17,7 @@ import { createExecutionUsageLog } from "./tangle-usage-log.js";
 import { observeTangleEnvironment } from "./tangle-observation.js";
 import { createTangleTerminalRegistry } from "./tangle-terminal.js";
 import { createTangleInteractiveAgentRegistry } from "./tangle-interactive.js";
+import { confidentialVerifierOption, createTangleWorkspaceBranching, } from "./tangle-workspace-branching.js";
 /**
  * Compose one concrete sandbox into an environment.
  *
@@ -49,7 +50,18 @@ export async function sandboxInstanceAsEnvironment(box, providerName, client, de
     }
     const support = sandboxCapabilitySupport(box, client, request?.resources);
     const deployment = await readDeploymentCapabilitySupport(box, operation);
-    const capabilities = frozenCapabilityDocument(AgentEnvironmentCapabilitiesSchema.parse(capabilitiesForSandbox(declaredCapabilities, support, deployment)));
+    const capabilities = frozenCapabilityDocument(AgentEnvironmentCapabilitiesSchema.parse(capabilitiesForSandbox(declaredCapabilities, support, deployment, confidentialVerifierOption(request?.confidentialAttestationVerifier))));
+    const workspaceBranching = capabilities.branching.checkpoint &&
+        capabilities.branching.fork &&
+        capabilities.branching.lookup === true &&
+        capabilities.branching.cleanup === true
+        ? createTangleWorkspaceBranching({
+            box,
+            client,
+            provider: providerName,
+            ...confidentialVerifierOption(request?.confidentialAttestationVerifier),
+        })
+        : undefined;
     // The published document is the single source for what this environment
     // offers, so the session surface reads its grant from there.
     const retainedControl = capabilities.retainedControl !== undefined;
@@ -84,9 +96,12 @@ export async function sandboxInstanceAsEnvironment(box, providerName, client, de
         ...(box.name ? { name: boundedString(box.name, "Tangle environment name") } : {}),
         ...(box.metadata ? { metadata: snapshotMetadata(box.metadata) } : {}),
         capabilities,
+        ...(workspaceBranching === undefined
+            ? {}
+            : { workspaceBranching }),
         async status(options) {
             assertOptionKeys(options, ["signal"], "Tangle environment status");
-            await awaitWithSignal(box.refresh?.(options), options?.signal);
+            await awaitWithSignal(box.refresh?.(options?.signal), options?.signal);
             return statusFromUnknown(box.status);
         },
         async *stream(input) {
@@ -284,7 +299,7 @@ export async function sandboxInstanceAsEnvironment(box, providerName, client, de
         async refresh(options) {
             assertOptionKeys(options, ["signal"], "Tangle refresh");
             options?.signal?.throwIfAborted();
-            await awaitWithSignal(box.refresh?.(options), options?.signal);
+            await awaitWithSignal(box.refresh?.(options?.signal), options?.signal);
             options?.signal?.throwIfAborted();
         },
         ...(support.destroy

package/dist/tangle-observation.js

@@ -167,7 +167,7 @@ async function refreshBeforeObservation(box, options) {
         return "the Sandbox client cannot refresh this environment";
     }
     try {
-        await awaitWithSignal(box.refresh(options), options?.signal);
+        await awaitWithSignal(box.refresh(options?.signal), options?.signal);
         return undefined;
     }
     catch (error) {

package/dist/tangle-prompt.js

@@ -68,6 +68,7 @@ const SANDBOX_OPTIONAL_RESULT_FIELDS = new Set([
     "errorCode",
     "toolInvocations",
     "approval",
+    "interaction",
     "question",
     "plan",
     "traceId",

package/dist/tangle-provider.js

@@ -2,10 +2,11 @@ import { AgentEnvironmentCapabilitiesSchema, createAgentEnvironmentWithIdempoten
 import { createTangleExactProcessProvider, } from "./exact-process.js";
 import { capabilitiesForClient, defaultTangleSandboxCapabilities, narrowTangleCapabilitiesToBackend, } from "./tangle-capabilities.js";
 import { sandboxInstanceAsEnvironment } from "./tangle-environment.js";
+import { confidentialVerifierOption, createTangleWorkspaceBranching, } from "./tangle-workspace-branching.js";
 import { assertCreateInputShape, assertMappedCreateOptions, assertMappedSecretNames, assertNoInlineSecretValues, sandboxOptionsFromCreateInput } from "./tangle-create-options.js";
 import { statusFromUnknown } from "./tangle-environment-values.js";
 import { requestedResourceProfile } from "./tangle-resources.js";
-import { assertBoundedJson, attachCleanupHandle, awaitWithSignal, boundedIdentifier, boundedString, MAX_LIST_RESULTS, } from "./tangle-contract-safety.js";
+import { assertBoundedJson, attachCleanupHandle, awaitWithSignal, boundedIdentifier, boundedString, MAX_LIST_RESULTS, SANDBOX_LIST_PAGE_SIZE, } from "./tangle-contract-safety.js";
 export function createTangleProvider(options) {
     const providerName = options.name ?? "tangle-sandbox";
     boundedIdentifier(providerName, "Tangle provider name");
@@ -38,7 +39,7 @@ export function createTangleProvider(options) {
     };
     // 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 narrowedProviderCapabilities = (declared) => AgentEnvironmentCapabilitiesSchema.parse(capabilitiesForClient(declared, options.client, confidentialVerifierOption(options.confidentialAttestationVerifier)));
     const resolveCapabilities = async () => narrowedProviderCapabilities(await resolveDeclaredCapabilities());
     const createRecords = new Map();
     const createEnvironment = async (input) => {
@@ -89,7 +90,12 @@ export function createTangleProvider(options) {
         try {
             input.signal?.throwIfAborted();
             const requestedResources = requestedResourceProfile(input.resources);
-            const environment = await sandboxInstanceAsEnvironment(box, providerName, options.client, declaredCapabilities, input.signal ? { signal: input.signal } : undefined, requestedResources === undefined ? undefined : { resources: requestedResources });
+            const environment = await sandboxInstanceAsEnvironment(box, providerName, options.client, declaredCapabilities, input.signal ? { signal: input.signal } : undefined, {
+                ...(requestedResources === undefined
+                    ? {}
+                    : { resources: requestedResources }),
+                ...confidentialVerifierOption(options.confidentialAttestationVerifier),
+            });
             input.signal?.throwIfAborted();
             return environment;
         }
@@ -109,9 +115,30 @@ export function createTangleProvider(options) {
             throw error;
         }
     };
+    const workspaceBranching = options.client.get
+        ? {
+            async forEnvironment(sourceEnvironmentId, operation) {
+                assertProviderOperationOptions(operation, "Tangle workspaceBranching.forEnvironment");
+                const environmentId = boundedIdentifier(sourceEnvironmentId, "Tangle workspace branching source environment id");
+                operation?.signal?.throwIfAborted();
+                const box = await awaitWithSignal(options.client.get?.(environmentId, operation), operation?.signal);
+                operation?.signal?.throwIfAborted();
+                if (!box || box.id !== environmentId)
+                    return null;
+                boundedIdentifier(box.id, "Tangle workspace branching environment id");
+                return (createTangleWorkspaceBranching({
+                    box,
+                    client: options.client,
+                    provider: providerName,
+                    ...confidentialVerifierOption(options.confidentialAttestationVerifier),
+                }) ?? null);
+            },
+        }
+        : undefined;
     return {
         name: providerName,
         ...(exactProcess ? { exactProcess } : {}),
+        ...(workspaceBranching === undefined ? {} : { workspaceBranching }),
         capabilities: resolveCapabilities,
         ...(options.validateProfile ? { validateProfile: options.validateProfile } : {}),
         create(input) {
@@ -129,7 +156,7 @@ export function createTangleProvider(options) {
                     operation?.signal?.throwIfAborted();
                     if (!box || boundedIdentifier(box.id, "Tangle environment id") !== id)
                         return null;
-                    return await sandboxInstanceAsEnvironment(box, providerName, options.client, declaredCapabilities, operation?.signal ? { signal: operation.signal } : undefined);
+                    return await sandboxInstanceAsEnvironment(box, providerName, options.client, declaredCapabilities, operation?.signal ? { signal: operation.signal } : undefined, confidentialVerifierOption(options.confidentialAttestationVerifier));
                 },
             }
             : {}),
@@ -156,9 +183,26 @@ export function createTangleProvider(options) {
                         }
                         assertBoundedJson(query.metadata);
                     }
-                    const boxes = await awaitWithSignal(options.client.list?.(operation?.signal ? { signal: operation.signal } : undefined), operation?.signal);
-                    if (!Array.isArray(boxes) || boxes.length > MAX_LIST_RESULTS) {
-                        throw new Error("Tangle environment list exceeded its result bound");
+                    const boxes = [];
+                    for (let offset = 0;; offset += SANDBOX_LIST_PAGE_SIZE) {
+                        if (offset > MAX_LIST_RESULTS) {
+                            throw new Error("Tangle environment list exceeded its page bound");
+                        }
+                        operation?.signal?.throwIfAborted();
+                        const page = await awaitWithSignal(options.client.list?.({
+                            limit: SANDBOX_LIST_PAGE_SIZE,
+                            offset,
+                            ...(operation?.signal ? { signal: operation.signal } : {}),
+                        }), operation?.signal);
+                        if (!Array.isArray(page) || page.length > SANDBOX_LIST_PAGE_SIZE) {
+                            throw new Error("Tangle environment list returned an invalid page size");
+                        }
+                        if (boxes.length + page.length > MAX_LIST_RESULTS) {
+                            throw new Error("Tangle environment list exceeded its result bound");
+                        }
+                        boxes.push(...page);
+                        if (page.length < SANDBOX_LIST_PAGE_SIZE)
+                            break;
                     }
                     const summaries = (boxes ?? []).filter((box) => {
                         boundedIdentifier(box.id, "Tangle environment id");