@tangle-network/agent-provider-tangle 1.0.1 → 1.1.0

package/README.md

@@ -1,8 +1,8 @@
 # @tangle-network/agent-provider-tangle
 
 Wraps `@tangle-network/sandbox` as an `AgentEnvironmentProvider`.
-The peer range is `>=0.34.4 <1.0.0`, and this package is developed and tested against 0.34.4.
-The floor is 0.34.4 because exact interactive attachment needs the host receiver, and workspace branching needs keyed snapshot, fork, lookup, and cleanup operations.
+The peer range is `>=0.34.6 <1.0.0`, and this package is developed and tested against 0.34.6.
+The floor is 0.34.6 because exact interactive attachment needs the host receiver, and workspace branching needs keyed snapshots, durable restores, inventory recovery, and cleanup.
 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.
 
@@ -15,6 +15,75 @@ const provider = createTangleProvider({
 });
 ```
 
+## `create()` returns a ready environment
+
+`provider.create()` does not return until the sandbox reports `running`.
+This is the contract `AgentEnvironmentProvider.create` states, and every runtime seam relies on it: a caller streams the first turn immediately after create, with nothing in between.
+A sandbox that never reaches running fails the create call with the platform's reason, and the adapter deletes the sandbox it could not hand over.
+
+The gap this closes is narrow and specific.
+`client.create()` waits by itself only when the create response reports `pending` or `provisioning`.
+A response that already reports `running` skips that wait, and `running` alone is not usable: the SDK's own `waitFor` treats the target as reached only when `filesystemIncarnationReadiness` is `ready`, because the sandbox filesystem is still being built until then.
+So `create()` can return a sandbox that reports `running` while the platform still holds a lifecycle operation on it, and the first turn lands on that lock.
+
+Composing an environment also reads the sandbox's deployment capability document once, and a sandbox that is not yet running cannot answer that read, so an environment composed during provisioning would claim nothing for the rest of its life.
+
+`readyTimeoutMs` bounds the wait and defaults to `DEFAULT_TANGLE_READY_TIMEOUT_MS` (120 seconds, the Sandbox SDK's own default).
+
+```ts
+const provider = createTangleProvider({
+  client: new Sandbox({ apiKey: process.env.TANGLE_API_KEY }),
+  readyTimeoutMs: 180_000,
+});
+
+const environment = await provider.create({ profile: { name: "worker" } });
+for await (const event of environment.stream({ prompt: "run the task" })) {
+  // The sandbox is running. No caller-side wait, poll, or retry stands here.
+}
+```
+
+The platform owns the wait, and this adapter runs no status loop of its own.
+It calls `waitFor("running")` on the created instance when the linked SDK offers it, because that refreshes the created instance in place and keeps its create receipt.
+It falls back to `client.waitForRunning(id)`, then refreshes the created instance.
+A client that offers neither cannot prove readiness, so the sandbox it returned has to report `running` by itself or the create call fails.
+
+The adapter reads the platform's answer back rather than trusting the wait to have resolved for the right reason.
+A create call returns only a sandbox that reports `running`: `failed`, `stopped`, and `expired` are refused with the status named, and so is a wait that resolves while the sandbox still reports `provisioning`.
+
+## Per-turn backend options
+
+`AgentTurnInput.providerOptions.backend` reaches `PromptOptions.backend` on the Sandbox prompt call.
+This is the exact block agent-runtime emits for a per-turn backend or model override, so a turn can select its model, its inline profile, or a session credential bundle without any change to the environment.
+
+```ts
+await environment.stream({
+  prompt: "run the task",
+  providerOptions: {
+    backend: {
+      type: "opencode",
+      model: {
+        provider: "zai",
+        model: "glm-5.2",
+        authMode: "oauth",
+        authFiles: [{ path: ".config/opencode/auth.json", content: seatCredentials, mode: 0o600 }],
+      },
+    },
+  },
+});
+```
+
+A field the Sandbox prompt options do not declare is refused, in `providerOptions`, in `backend`, and in `backend.model`.
+The SDK drops what it does not declare, so a forwarded unknown field would run the turn on different settings with no error anywhere.
+The accepted field sets are pinned to the SDK's `BackendConfig` at compile time, at all three levels including `authFiles`, so a field the SDK adds or removes fails this package's build instead of reaching a caller as a wrong refusal.
+Values are checked, not just field names: an inline `backend.profile` is read by `agentProfileSchema`, the package that owns profile rules, and `backend.metadata.traceAttributes` is held to the entry and length limits the Sandbox platform states for it.
+`AgentTurnInput.interactions` and `backend.interactions` state the same posture, and a disagreement between them is refused rather than resolved by preference.
+A turn `model` that disagrees with `backend.model.model` is refused for the same reason.
+`AgentTurnInput.interactions` still maps to `backend.interactions` for a turn that carries no backend block at all.
+
+Backend options are part of the retained request digest, so a retry under the same `turnId` with a changed model, profile, or seat conflicts instead of replaying work that ran on other settings.
+Bearer material is excluded from that identity: `model.apiKey` is dropped and `authFiles` are reduced to the paths and modes they install.
+A rotated seat token is the same seat running the same work, so an ordinary refresh continues its run rather than conflicting with it.
+
 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.
 Created and reconstructed environments expose a recursively frozen Sandbox metadata snapshot for constant-time annotation checks.
@@ -22,8 +91,6 @@ Sandbox metadata can include caller-authored values and does not authenticate it
 Reconstruct an exact session with `environment.session(reference.id, { controlRef: reference.controlRef })`; replay cursors are exclusive at both the agent interface and Sandbox session stream.
 Result, replay, and cancel operations select that exact execution instead of whichever execution most recently changed the shared session.
 Session status with an exact control reference reports a state only when the payload names that execution; a payload bound to a different or unnamed execution reports `unknown`.
-`AgentTurnInput.interactions` maps unchanged to `PromptOptions.backend.interactions` for the selected Sandbox turn.
-The requested posture is part of the retained request digest, so a retry with changed interaction behavior conflicts instead of reusing prior work.
 
 ## Two capability documents
 
@@ -112,7 +179,7 @@ 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
+surface: keyed `snapshot`, durable snapshot restore, inventory recovery, and
 explicit deletion outcomes.
 An incomplete SDK surface clears every branching flag and omits
 `environment.workspaceBranching`.
@@ -122,9 +189,10 @@ 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.
+metadata so a fresh process can recover the exact interface digest.
+Snapshot-created children are validated through the marker and complete
+account inventory, while legacy fork markers also require the Sandbox fork
+ledger to report a settled success.
 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

package/dist/exact-process.d.ts

@@ -4,4 +4,6 @@ export declare function createTangleExactProcessProvider(input: {
     client: SandboxClientLike;
     options: TangleExactProcessOptions;
     providerName: string;
+    /** How long create() waits for the new sandbox to reach `running`. */
+    readyTimeoutMs: number;
 }): AgentExactProcessProvider;

package/dist/exact-process.js

@@ -1,9 +1,10 @@
 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 { awaitSandboxRunning } from "./tangle-readiness.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;
 export function createTangleExactProcessProvider(input) {
-    const { client, options, providerName } = input;
+    const { client, options, providerName, readyTimeoutMs } = input;
     boundedIdentifier(providerName, "Tangle exact process provider");
     if (options.teamId !== undefined) {
         boundedIdentifier(options.teamId, "Tangle exact process team id");
@@ -51,7 +52,18 @@ export function createTangleExactProcessProvider(input) {
             }
             try {
                 createInput.signal?.throwIfAborted();
+                // Ownership is decided from metadata this call already holds, so it is
+                // decided before the wait. A foreign sandbox returned under a reused
+                // idempotency key is a conflict now, not two minutes from now.
                 assertExactProcessSandbox(box, providerName, options.teamId, identityDigest);
+                // A launch starts a process on this sandbox, so create() returns only
+                // after the sandbox can run one. The caller's provisioning budget owns
+                // the deadline when it named one.
+                await awaitSandboxRunning(box, client, {
+                    timeoutMs: createInput.provisionTimeoutMs ?? readyTimeoutMs,
+                    ...(createInput.signal ? { signal: createInput.signal } : {}),
+                });
+                createInput.signal?.throwIfAborted();
                 return sandboxInstanceAsExactProcessEnvironment(box, providerName);
             }
             catch (error) {

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export type { TangleExactProcessOptions } from "./tangle-types.js";
 export * from "./tangle-types.js";
 export { createTangleProvider } from "./tangle-provider.js";
+export { DEFAULT_TANGLE_READY_TIMEOUT_MS } from "./tangle-readiness.js";
 export { defaultTangleSandboxCapabilities } from "./tangle-capabilities.js";
 export { createTangleWorkspaceBranching, supportsWorkspaceBranching, } from "./tangle-workspace-branching.js";
 export type { TangleWorkspaceBranchingOptions } from "./tangle-workspace-branching.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from "./tangle-types.js";
 export { createTangleProvider } from "./tangle-provider.js";
+export { DEFAULT_TANGLE_READY_TIMEOUT_MS } from "./tangle-readiness.js";
 export { defaultTangleSandboxCapabilities } from "./tangle-capabilities.js";
 export { createTangleWorkspaceBranching, supportsWorkspaceBranching, } from "./tangle-workspace-branching.js";
 export { decodeTangleConfidentialAttestationQuote, encodeTangleConfidentialAttestationQuote, MAX_TEE_EVIDENCE_BYTES, MAX_TEE_MEASUREMENT_BYTES, TANGLE_CONFIDENTIAL_ATTESTATION_QUOTE_KIND, TANGLE_CONFIDENTIAL_ATTESTATION_QUOTE_VERSION, } from "./tangle-confidential-attestation.js";

package/dist/tangle-capabilities.js

@@ -92,6 +92,13 @@ export function defaultTangleSandboxCapabilities(harness) {
         },
         placement: true,
         usage: false,
+        // Create carries both fields to the Sandbox API unchanged. The API still authorizes the
+        // caller for a delegated billing owner, and it rejects the create when it does not, so this
+        // states only that neither field is dropped on the way.
+        create: {
+            egress: ["open", "strict", "blocked"],
+            billingOwner: true,
+        },
         // This is intent only. Narrowing requires both raw TEE evidence and the
         // caller's external provider-key verifier before the flag survives.
         confidential: true,

package/dist/tangle-create-options.js

@@ -1,4 +1,4 @@
-import { WorkspaceRequestSchema, workspaceCwdPathForBase, } from "@tangle-network/agent-interface/environment-provider";
+import { AgentEnvironmentEgressPolicySchema, WorkspaceRequestSchema, workspaceCwdPathForBase, } from "@tangle-network/agent-interface/environment-provider";
 import { assertBoundedJson, boundedIdentifier, boundedString, MAX_ARRAY_LENGTH, MAX_MAP_ENTRIES, } from "./tangle-contract-safety.js";
 import { sandboxResourcesFromResourceRequest } from "./tangle-resources.js";
 export function sandboxOptionsFromCreateInput(input, defaultBackend, parsedWorkspace) {
@@ -32,6 +32,9 @@ export function sandboxOptionsFromCreateInput(input, defaultBackend, parsedWorks
     if (input.idempotencyKey !== undefined) {
         boundedIdentifier(input.idempotencyKey, "Tangle idempotency key");
     }
+    if (input.billingOwner !== undefined) {
+        boundedIdentifier(input.billingOwner, "Tangle billing owner");
+    }
     const resources = sandboxResourcesFromResourceRequest(input.resources);
     // Sandbox injects secrets by name from its own store. Accepting a name/value
     // record and dropping it would create an environment with no credentials and
@@ -53,6 +56,8 @@ export function sandboxOptionsFromCreateInput(input, defaultBackend, parsedWorks
         ...(resources ? { resources } : {}),
         ...(input.env ? { env: input.env } : {}),
         ...(Array.isArray(input.secrets) ? { secrets: input.secrets } : {}),
+        ...(input.egress === undefined ? {} : { egressPolicy: sandboxEgressPolicy(input.egress) }),
+        ...(input.billingOwner === undefined ? {} : { billingOwnerId: input.billingOwner }),
         ...(input.metadata ? { metadata: input.metadata } : {}),
         ...(input.name === undefined ? {} : { name: input.name }),
         ...(input.idempotencyKey === undefined ? {} : { idempotencyKey: input.idempotencyKey }),
@@ -64,6 +69,27 @@ export function sandboxOptionsFromCreateInput(input, defaultBackend, parsedWorks
     };
     return mapped;
 }
+/**
+ * Project the portable egress policy onto the Sandbox policy.
+ *
+ * The schema is a strict discriminated union, so a domain list outside `strict` is refused rather
+ * than sent: Sandbox IGNORES `allowDomains` in `open` and `blocked` mode, and a silently ignored
+ * allowlist is a policy the caller believes is in force and is not.
+ *
+ * `includeImplicitDomains` stays unset, which is the Sandbox default of false. A strict policy
+ * therefore reaches the named domains plus the model endpoints the platform provisioned, matching
+ * what {@link AgentEnvironmentEgressPolicy} states; opting in would silently add ~40 hosts,
+ * including public source hosts.
+ */
+function sandboxEgressPolicy(policy) {
+    const parsed = AgentEnvironmentEgressPolicySchema.parse(policy);
+    if (parsed.mode !== "strict")
+        return { mode: parsed.mode };
+    return {
+        mode: "strict",
+        ...(parsed.allowDomains === undefined ? {} : { allowDomains: [...parsed.allowDomains] }),
+    };
+}
 /** Reject value-bearing secret maps before any custom mapper can drop them. */
 export function assertNoInlineSecretValues(input, parsedWorkspace) {
     if (input.providerOptions !== undefined) {
@@ -126,6 +152,8 @@ export function assertCreateInputShape(input, parsedWorkspace) {
         "resources",
         "env",
         "secrets",
+        "egress",
+        "billingOwner",
         "metadata",
         "name",
         "idempotencyKey",
@@ -175,6 +203,33 @@ export function assertMappedCreateOptions(options) {
     }
     if (options.idempotencyKey !== undefined)
         boundedIdentifier(options.idempotencyKey, "Tangle mapped idempotency key");
+    if (options.billingOwnerId !== undefined)
+        boundedIdentifier(options.billingOwnerId, "Tangle mapped billing owner");
+    if (options.egressPolicy !== undefined) {
+        if (!options.egressPolicy || typeof options.egressPolicy !== "object" || Array.isArray(options.egressPolicy)) {
+            throw new Error("Tangle mapped egress policy must be an object");
+        }
+        if (!["open", "strict", "blocked"].includes(options.egressPolicy.mode)) {
+            throw new Error("Tangle mapped egress policy mode is invalid");
+        }
+        if (options.egressPolicy.mode !== "strict" && options.egressPolicy.allowDomains !== undefined) {
+            throw new Error("Tangle mapped egress policy allows domains only in strict mode");
+        }
+        // The default path is schema-checked, so this gate holds a custom mapper to the same shape.
+        // A non-string or padded host reaches the platform, matches nothing, and leaves the caller
+        // believing an allowlist is in force that is not.
+        if (options.egressPolicy.allowDomains !== undefined) {
+            if (!Array.isArray(options.egressPolicy.allowDomains)) {
+                throw new Error("Tangle mapped egress allowed domains must be an array");
+            }
+            if (options.egressPolicy.allowDomains.length > MAX_ARRAY_LENGTH) {
+                throw new Error("Tangle mapped egress allowed domains exceed their bound");
+            }
+            for (const domain of options.egressPolicy.allowDomains) {
+                boundedIdentifier(domain, "Tangle mapped egress allowed domain");
+            }
+        }
+    }
     if (options.env !== undefined)
         assertStringRecord(options.env, "Tangle mapped");
     assertMappedSecretNames(options);

package/dist/tangle-environment-control.js

@@ -1,5 +1,7 @@
 import { canonicalCandidateDigest } from "@tangle-network/agent-interface";
+import { backendFromTurnProviderOptions, backendRequestIdentity, } from "./tangle-prompt.js";
 export function sessionPromptRequestDigest(input, provider, environmentId, sessionId, options = {}) {
+    const backend = backendRequestIdentity(backendFromTurnProviderOptions(input.providerOptions));
     return canonicalCandidateDigest({
         provider,
         environmentId,
@@ -18,6 +20,12 @@ export function sessionPromptRequestDigest(input, provider, environmentId, sessi
         ...(input.interactions === undefined
             ? {}
             : { interactions: input.interactions }),
+        // Per-turn backend options select the model, the profile, and the seat the
+        // turn runs on. Leaving them out of the identity would let a retry under
+        // the same turn id reuse work that ran on other settings. The bearer
+        // material inside them is excluded, so a token refresh does not conflict
+        // with the run it continues.
+        ...(backend === undefined ? {} : { backend }),
     });
 }
 export function hasReplayPayload(input) {

package/dist/tangle-environment.d.ts

@@ -15,8 +15,10 @@ import type { TangleConfidentialAttestationVerifier } from "./tangle-types.js";
  * The document is measured once, here. A sandbox that is not yet running
  * cannot answer, so an environment composed during provisioning claims
  * nothing and keeps claiming nothing: the exposed operations and the document
- * are composed together and a caller may already hold either one. Compose the
- * environment again through `provider.get(id)` once the sandbox is running.
+ * are composed together and a caller may already hold either one. This is why
+ * `provider.create()` holds until the sandbox is running before it composes
+ * (see `tangle-readiness.ts`). `provider.get(id)` composes whatever the
+ * sandbox is at that moment, so compose again once a starting sandbox runs.
  *
  * @param request What the create call asked for. An environment rebuilt by id
  * carries none of it, so its observation reports the requested compute shape

package/dist/tangle-environment.js

@@ -32,8 +32,10 @@ import { confidentialVerifierOption, createTangleWorkspaceBranching, } from "./t
  * The document is measured once, here. A sandbox that is not yet running
  * cannot answer, so an environment composed during provisioning claims
  * nothing and keeps claiming nothing: the exposed operations and the document
- * are composed together and a caller may already hold either one. Compose the
- * environment again through `provider.get(id)` once the sandbox is running.
+ * are composed together and a caller may already hold either one. This is why
+ * `provider.create()` holds until the sandbox is running before it composes
+ * (see `tangle-readiness.ts`). `provider.get(id)` composes whatever the
+ * sandbox is at that moment, so compose again once a starting sandbox runs.
  *
  * @param request What the create call asked for. An environment rebuilt by id
  * carries none of it, so its observation reports the requested compute shape

package/dist/tangle-prompt.d.ts

@@ -1,4 +1,4 @@
-import type { PromptOptions, PromptResult } from "@tangle-network/sandbox";
+import type { BackendConfig, 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";
 export declare function promptFromTurnInput(input: AgentTurnInput): string | InputPart[];
@@ -8,6 +8,71 @@ export declare function promptOptionsFromTurnInput(input: AgentTurnInput, target
     environmentId: string;
     sessionId?: string;
 }): PromptOptions;
+/**
+ * The `BackendConfig` fields the Sandbox prompt options declare.
+ *
+ * A turn may carry any of them and nothing else. An undeclared field is
+ * refused instead of forwarded, because the SDK drops what it does not
+ * declare: the turn would then run on different settings with no error
+ * anywhere, which is the silent substitution the SDK's own `model` field
+ * exists to prevent.
+ */
+declare const SANDBOX_BACKEND_FIELD_LIST: readonly ["type", "profile", "model", "server", "interactions", "metadata"];
+/**
+ * The `BackendConfig["model"]` fields the Sandbox prompt options declare.
+ *
+ * This is the block that carries per-turn credentials — `authMode: "oauth"`
+ * with `authFiles` for a subscription seat — so it is checked field by field
+ * rather than passed through as opaque JSON.
+ */
+declare const SANDBOX_BACKEND_MODEL_FIELD_LIST: readonly ["provider", "model", "apiKey", "baseUrl", "maxThinkingTokens", "mode", "apiKeyEnv", "authMode", "authFiles"];
+/**
+ * The two lists above are the SDK's field sets, restated as values because a
+ * TypeScript type cannot be read at run time. This pin keeps them exact in
+ * both directions: a field the SDK adds, renames, or removes fails the build
+ * here rather than reaching a caller as a wrong refusal or a silent drop.
+ */
+type Exhaustive<T extends never> = T;
+type SandboxBackendModel = NonNullable<BackendConfig["model"]>;
+type UncoveredBackendField = Exhaustive<Exclude<keyof BackendConfig, (typeof SANDBOX_BACKEND_FIELD_LIST)[number]>>;
+type StaleBackendField = Exhaustive<Exclude<(typeof SANDBOX_BACKEND_FIELD_LIST)[number], keyof BackendConfig>>;
+type UncoveredBackendModelField = Exhaustive<Exclude<keyof SandboxBackendModel, (typeof SANDBOX_BACKEND_MODEL_FIELD_LIST)[number]>>;
+type StaleBackendModelField = Exhaustive<Exclude<(typeof SANDBOX_BACKEND_MODEL_FIELD_LIST)[number], keyof SandboxBackendModel>>;
+declare const SANDBOX_AUTH_FILE_FIELD_LIST: readonly ["path", "content", "mode"];
+type SandboxAuthFile = NonNullable<SandboxBackendModel["authFiles"]>[number];
+type UncoveredAuthFileField = Exhaustive<Exclude<keyof SandboxAuthFile, (typeof SANDBOX_AUTH_FILE_FIELD_LIST)[number]>>;
+type StaleAuthFileField = Exhaustive<Exclude<(typeof SANDBOX_AUTH_FILE_FIELD_LIST)[number], keyof SandboxAuthFile>>;
+type SandboxBackendFieldCoverage = [
+    UncoveredBackendField,
+    StaleBackendField,
+    UncoveredBackendModelField,
+    StaleBackendModelField,
+    UncoveredAuthFileField,
+    StaleAuthFileField
+];
+export type { SandboxBackendFieldCoverage };
+type SandboxPromptBackend = NonNullable<PromptOptions["backend"]>;
+/**
+ * Read the per-turn backend options a caller sent through `providerOptions`.
+ *
+ * `AgentTurnInput.providerOptions.backend` is the exact shape agent-runtime
+ * emits for a per-turn backend or model override, so refusing it dropped the
+ * caller's model, profile, and session credential bundle at the adapter
+ * boundary. Every field is checked against what the Sandbox prompt options
+ * declare, and the result is bounded JSON the SDK reads once.
+ */
+export declare function backendFromTurnProviderOptions(providerOptions: Record<string, unknown> | undefined): SandboxPromptBackend | undefined;
+/**
+ * The part of the backend options that decides which work a turn is.
+ *
+ * Bearer material is deliberately absent. A rotated seat token is the same
+ * seat running the same work, so digesting the token bytes would make an
+ * ordinary refresh conflict with the run it is continuing. The auth files are
+ * reduced to the paths and modes they install, which states that the turn
+ * carries a credential bundle and which slots it fills, without binding the
+ * identity to the secret inside.
+ */
+export declare function backendRequestIdentity(backend: SandboxPromptBackend | undefined): Record<string, unknown> | undefined;
 type SandboxRunStatus = "success" | "failed" | "blocked_on_approval" | "awaiting_question" | "awaiting_interaction" | "awaiting_plan_decision";
 type ValidatedSandboxPromptResult = Record<string, unknown> & {
     success: boolean;
@@ -22,4 +87,3 @@ export declare function agentTurnResultFromPromptRecord(record: ValidatedSandbox
     sessionId?: string;
     controlRef?: AgentExactRunControlRef;
 }): AgentTurnResult;
-export {};

package/dist/tangle-prompt.js

@@ -1,6 +1,6 @@
-import { AgentExactRunControlRefSchema, AgentTurnInputSchema, ContextTransferReceiptSchema, contextTransferResultMatchesRequest, } from "@tangle-network/agent-interface";
+import { agentProfileSchema, AgentExactRunControlRefSchema, AgentTurnInputSchema, ContextTransferReceiptSchema, contextTransferResultMatchesRequest, } from "@tangle-network/agent-interface";
 import { tokenUsageFromData } from "./tangle-result-values.js";
-import { assertBoundedJson } from "./tangle-contract-safety.js";
+import { assertBoundedJson, boundedString } from "./tangle-contract-safety.js";
 export function promptFromTurnInput(input) {
     AgentTurnInputSchema.parse(input);
     if (input.parts)
@@ -40,17 +40,13 @@ export function promptOptionsFromTurnInput(input, target) {
             throw new Error("Tangle executionId conflicts with the control reference");
         }
     }
-    if (input.providerOptions && Object.keys(input.providerOptions).length > 0) {
-        throw new Error("Tangle prompt providerOptions are not supported");
-    }
+    const backend = turnBackendOptions(input);
     const sessionId = input.sessionId ?? controlRef?.sessionId;
     const executionId = input.executionId ?? controlRef?.executionId;
     return {
         ...(sessionId ? { sessionId } : {}),
         ...(input.model ? { model: input.model } : {}),
-        ...(input.interactions === undefined
-            ? {}
-            : { backend: { interactions: input.interactions } }),
+        ...(backend === undefined ? {} : { backend }),
         ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
         ...(input.context ? { context: input.context } : {}),
         ...(input.signal ? { signal: input.signal } : {}),
@@ -61,6 +57,294 @@ export function promptOptionsFromTurnInput(input, target) {
         ...(input.detach !== undefined ? { detach: input.detach } : {}),
     };
 }
+/**
+ * The `BackendConfig` fields the Sandbox prompt options declare.
+ *
+ * A turn may carry any of them and nothing else. An undeclared field is
+ * refused instead of forwarded, because the SDK drops what it does not
+ * declare: the turn would then run on different settings with no error
+ * anywhere, which is the silent substitution the SDK's own `model` field
+ * exists to prevent.
+ */
+const SANDBOX_BACKEND_FIELD_LIST = [
+    "type",
+    "profile",
+    "model",
+    "server",
+    "interactions",
+    "metadata",
+];
+const SANDBOX_BACKEND_FIELDS = new Set(SANDBOX_BACKEND_FIELD_LIST);
+/**
+ * The `BackendConfig["model"]` fields the Sandbox prompt options declare.
+ *
+ * This is the block that carries per-turn credentials — `authMode: "oauth"`
+ * with `authFiles` for a subscription seat — so it is checked field by field
+ * rather than passed through as opaque JSON.
+ */
+const SANDBOX_BACKEND_MODEL_FIELD_LIST = [
+    "provider",
+    "model",
+    "apiKey",
+    "baseUrl",
+    "maxThinkingTokens",
+    "mode",
+    "apiKeyEnv",
+    "authMode",
+    "authFiles",
+];
+const SANDBOX_BACKEND_MODEL_FIELDS = new Set(SANDBOX_BACKEND_MODEL_FIELD_LIST);
+const SANDBOX_AUTH_FILE_FIELD_LIST = ["path", "content", "mode"];
+/**
+ * Read the per-turn backend options a caller sent through `providerOptions`.
+ *
+ * `AgentTurnInput.providerOptions.backend` is the exact shape agent-runtime
+ * emits for a per-turn backend or model override, so refusing it dropped the
+ * caller's model, profile, and session credential bundle at the adapter
+ * boundary. Every field is checked against what the Sandbox prompt options
+ * declare, and the result is bounded JSON the SDK reads once.
+ */
+export function backendFromTurnProviderOptions(providerOptions) {
+    if (providerOptions === undefined)
+        return undefined;
+    assertDeclaredFields(providerOptions, new Set(["backend"]), "Tangle prompt providerOptions");
+    if (!Object.hasOwn(providerOptions, "backend"))
+        return undefined;
+    return sandboxPromptBackend(providerOptions.backend);
+}
+function sandboxPromptBackend(value) {
+    const present = plainRecord(value, "Tangle prompt backend options");
+    assertDeclaredFields(present, SANDBOX_BACKEND_FIELDS, "Tangle prompt backend options");
+    const backend = {
+        ...(present.type === undefined
+            ? {}
+            : { type: boundedString(present.type, "Tangle prompt backend type") }),
+        // The profile decides tools, permissions, mounts, and the security policy
+        // of the turn, so it is read by the schema that owns those rules rather
+        // than passed through as bounded JSON.
+        ...(present.profile === undefined
+            ? {}
+            : { profile: agentProfileSchema.parse(present.profile) }),
+        ...(present.model === undefined
+            ? {}
+            : { model: sandboxPromptBackendModel(present.model) }),
+        ...(present.server === undefined
+            ? {}
+            : { server: sandboxPromptBackendServer(present.server) }),
+        ...(present.interactions === undefined
+            ? {}
+            : { interactions: sandboxPromptInteractions(present.interactions) }),
+        ...(present.metadata === undefined
+            ? {}
+            : { metadata: sandboxPromptBackendMetadata(present.metadata) }),
+    };
+    assertBoundedJson(backend);
+    return backend;
+}
+function sandboxPromptBackendModel(value) {
+    const present = plainRecord(value, "Tangle prompt backend model options");
+    assertDeclaredFields(present, SANDBOX_BACKEND_MODEL_FIELDS, "Tangle prompt backend model options");
+    const model = {};
+    for (const field of ["provider", "model", "apiKey", "baseUrl", "apiKeyEnv"]) {
+        if (present[field] === undefined)
+            continue;
+        if (typeof present[field] !== "string" || present[field] === "") {
+            throw new Error(`Tangle prompt backend model ${field} must be a non-empty string`);
+        }
+        model[field] = boundedString(present[field], `Tangle prompt backend model ${field}`);
+    }
+    if (present.maxThinkingTokens !== undefined) {
+        if (!Number.isSafeInteger(present.maxThinkingTokens) ||
+            present.maxThinkingTokens < 0) {
+            throw new Error("Tangle prompt backend model maxThinkingTokens must be a non-negative integer");
+        }
+        model.maxThinkingTokens = present.maxThinkingTokens;
+    }
+    if (present.mode !== undefined) {
+        if (present.mode !== "api" && present.mode !== "cli") {
+            throw new Error('Tangle prompt backend model mode must be "api" or "cli"');
+        }
+        model.mode = present.mode;
+    }
+    if (present.authMode !== undefined) {
+        if (present.authMode !== "api-key" && present.authMode !== "oauth") {
+            throw new Error('Tangle prompt backend model authMode must be "api-key" or "oauth"');
+        }
+        model.authMode = present.authMode;
+    }
+    if (present.authFiles !== undefined) {
+        model.authFiles = sandboxPromptAuthFiles(present.authFiles);
+    }
+    return model;
+}
+function sandboxPromptBackendServer(value) {
+    const present = plainRecord(value, "Tangle prompt backend server options");
+    assertDeclaredFields(present, new Set(["port", "hostname"]), "Tangle prompt backend server options");
+    const server = {};
+    if (present.port !== undefined) {
+        if (!Number.isSafeInteger(present.port) ||
+            present.port < 1 ||
+            present.port > 65_535) {
+            throw new Error("Tangle prompt backend server port must be a TCP port number");
+        }
+        server.port = present.port;
+    }
+    if (present.hostname !== undefined) {
+        if (typeof present.hostname !== "string" || present.hostname === "") {
+            throw new Error("Tangle prompt backend server hostname must be a non-empty string");
+        }
+        server.hostname = boundedString(present.hostname, "Tangle prompt backend server hostname");
+    }
+    return server;
+}
+function sandboxPromptInteractions(value) {
+    const present = plainRecord(value, "Tangle prompt backend interactions");
+    assertDeclaredFields(present, new Set(["permission", "question", "plan"]), "Tangle prompt backend interactions");
+    const interactions = {};
+    for (const kind of ["permission", "question", "plan"]) {
+        if (present[kind] === undefined)
+            continue;
+        if (typeof present[kind] !== "boolean") {
+            throw new Error(`Tangle prompt backend interaction ${kind} must be a boolean`);
+        }
+        interactions[kind] = present[kind];
+    }
+    return interactions;
+}
+/** Sandbox caps trace attributes, and its own documentation forbids secrets there. */
+const MAX_TRACE_ATTRIBUTES = 32;
+const MAX_TRACE_ATTRIBUTE_KEY_LENGTH = 128;
+const MAX_TRACE_ATTRIBUTE_VALUE_LENGTH = 1_024;
+function sandboxPromptBackendMetadata(value) {
+    const present = plainRecord(value, "Tangle prompt backend metadata");
+    assertDeclaredFields(present, new Set(["containerType", "traceAttributes"]), "Tangle prompt backend metadata");
+    const metadata = {};
+    if (present.containerType !== undefined) {
+        if (typeof present.containerType !== "string" || present.containerType === "") {
+            throw new Error("Tangle prompt backend metadata containerType must be a non-empty string");
+        }
+        metadata.containerType = boundedString(present.containerType, "Tangle prompt backend metadata containerType");
+    }
+    if (present.traceAttributes !== undefined) {
+        const attributes = plainRecord(present.traceAttributes, "Tangle prompt backend metadata traceAttributes");
+        const entries = Object.entries(attributes);
+        if (entries.length > MAX_TRACE_ATTRIBUTES) {
+            throw new Error(`Tangle prompt backend metadata traceAttributes exceeds ${MAX_TRACE_ATTRIBUTES} entries`);
+        }
+        for (const [key, attribute] of entries) {
+            if (key.length > MAX_TRACE_ATTRIBUTE_KEY_LENGTH) {
+                throw new Error("Tangle prompt backend metadata traceAttributes key exceeds its bound");
+            }
+            if (typeof attribute !== "string" ||
+                attribute.length > MAX_TRACE_ATTRIBUTE_VALUE_LENGTH) {
+                throw new Error("Tangle prompt backend metadata traceAttributes value must be a bounded string");
+            }
+        }
+        metadata.traceAttributes = { ...attributes };
+    }
+    return metadata;
+}
+function sandboxPromptAuthFiles(value) {
+    if (!Array.isArray(value)) {
+        throw new Error("Tangle prompt backend authFiles must be an array");
+    }
+    return value.map((entry) => {
+        const present = plainRecord(entry, "Tangle prompt backend auth file");
+        assertDeclaredFields(present, new Set(SANDBOX_AUTH_FILE_FIELD_LIST), "Tangle prompt backend auth file fields");
+        if (typeof present.path !== "string" || present.path.length === 0) {
+            throw new Error("Tangle prompt backend auth file requires a path");
+        }
+        if (typeof present.content !== "string") {
+            throw new Error("Tangle prompt backend auth file requires string content");
+        }
+        if (present.mode !== undefined && !Number.isSafeInteger(present.mode)) {
+            throw new Error("Tangle prompt backend auth file mode must be an integer");
+        }
+        return {
+            path: boundedString(present.path, "Tangle prompt backend auth file path"),
+            content: present.content,
+            ...(present.mode === undefined ? {} : { mode: present.mode }),
+        };
+    });
+}
+function assertDeclaredFields(record, declared, label) {
+    const unsupported = Object.keys(record).filter((key) => !declared.has(key));
+    if (unsupported.length > 0) {
+        throw new Error(`${label} are not supported: ${unsupported.sort().join(", ")}`);
+    }
+}
+function plainRecord(value, label) {
+    if (!value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        (Object.getPrototypeOf(value) !== Object.prototype &&
+            Object.getPrototypeOf(value) !== null)) {
+        throw new Error(`${label} must be a JSON object`);
+    }
+    return value;
+}
+/**
+ * The part of the backend options that decides which work a turn is.
+ *
+ * Bearer material is deliberately absent. A rotated seat token is the same
+ * seat running the same work, so digesting the token bytes would make an
+ * ordinary refresh conflict with the run it is continuing. The auth files are
+ * reduced to the paths and modes they install, which states that the turn
+ * carries a credential bundle and which slots it fills, without binding the
+ * identity to the secret inside.
+ */
+export function backendRequestIdentity(backend) {
+    if (backend === undefined)
+        return undefined;
+    const model = backend.model;
+    if (model === undefined)
+        return { ...backend };
+    const { apiKey: _apiKey, authFiles, ...rest } = model;
+    return {
+        ...backend,
+        model: {
+            ...rest,
+            ...(authFiles === undefined
+                ? {}
+                : {
+                    authFiles: authFiles.map((file) => ({
+                        path: file.path,
+                        ...(file.mode === undefined ? {} : { mode: file.mode }),
+                    })),
+                }),
+        },
+    };
+}
+/**
+ * Combine the turn's requested interaction posture with its backend options.
+ *
+ * agent-runtime emits both: it maps `backend.interactions` onto the canonical
+ * `AgentTurnInput.interactions` and carries the whole backend block through
+ * `providerOptions`. The two must agree, and a disagreement is refused rather
+ * than resolved by preference, because either answer would run the turn on a
+ * posture the caller did not ask for.
+ */
+function turnBackendOptions(input) {
+    const backend = backendFromTurnProviderOptions(input.providerOptions);
+    const backendModel = backend?.model?.model;
+    if (input.model !== undefined &&
+        backendModel !== undefined &&
+        backendModel !== input.model) {
+        throw new Error("Tangle turn model conflicts with its backend model");
+    }
+    if (input.interactions === undefined)
+        return backend;
+    if (backend === undefined)
+        return { interactions: input.interactions };
+    if (backend.interactions !== undefined &&
+        !sameRequestedInteractions(backend.interactions, input.interactions)) {
+        throw new Error("Tangle turn interactions conflict with its backend interactions");
+    }
+    return { ...backend, interactions: input.interactions };
+}
+function sameRequestedInteractions(left, right) {
+    return ["permission", "question", "plan"].every((kind) => (left[kind] ?? false) === (right[kind] ?? false));
+}
 const SANDBOX_OPTIONAL_RESULT_FIELDS = new Set([
     "executionId",
     "response",

package/dist/tangle-provider.js

@@ -5,16 +5,22 @@ 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 { awaitSandboxRunning, DEFAULT_TANGLE_READY_TIMEOUT_MS, } from "./tangle-readiness.js";
 import { requestedResourceProfile } from "./tangle-resources.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");
+    const readyTimeoutMs = options.readyTimeoutMs ?? DEFAULT_TANGLE_READY_TIMEOUT_MS;
+    if (!Number.isFinite(readyTimeoutMs) || readyTimeoutMs <= 0) {
+        throw new Error("Tangle readyTimeoutMs must be a positive number of milliseconds");
+    }
     const exactProcess = options.exactProcess
         ? createTangleExactProcessProvider({
             client: options.client,
             options: options.exactProcess,
             providerName,
+            readyTimeoutMs,
         })
         : undefined;
     const resolveDeclaredCapabilities = async () => {
@@ -88,6 +94,14 @@ export function createTangleProvider(options) {
             throw error;
         }
         try {
+            input.signal?.throwIfAborted();
+            // The environment this call returns must accept a turn, and composing it
+            // reads a deployment document that a starting sandbox cannot answer.
+            // Both facts wait here, once, so no caller repeats the wait.
+            await awaitSandboxRunning(box, options.client, {
+                timeoutMs: readyTimeoutMs,
+                ...(input.signal ? { signal: input.signal } : {}),
+            });
             input.signal?.throwIfAborted();
             const requestedResources = requestedResourceProfile(input.resources);
             const environment = await sandboxInstanceAsEnvironment(box, providerName, options.client, declaredCapabilities, input.signal ? { signal: input.signal } : undefined, {

package/dist/tangle-readiness.d.ts

@@ -0,0 +1,43 @@
+import type { SandboxClientLike, SandboxInstanceLike } from "./tangle-types.js";
+/**
+ * How long `create()` waits for a new sandbox to reach `running`.
+ *
+ * The value is the Sandbox SDK's own wait default, so the adapter states no
+ * second deadline that disagrees with the platform's.
+ */
+export declare const DEFAULT_TANGLE_READY_TIMEOUT_MS = 120000;
+/**
+ * Hold `create()` until the sandbox can accept a turn.
+ *
+ * The gap this closes is narrow and specific. `client.create()` waits by
+ * itself only when the create response reports `pending` or `provisioning`.
+ * A response that already reports `running` skips that wait, and `running`
+ * alone is not usable: the SDK's own `waitFor` treats the target as reached
+ * only when `filesystemIncarnationReadiness` is `ready`, because the box's
+ * filesystem is still being built until then. So `create()` can return a box
+ * that reports `running` while the platform still holds a lifecycle operation
+ * on it, and the first turn lands on that lock.
+ *
+ * Measured against that mechanism, 2026-09-01, discovery-lab#467: one box
+ * (`sandbox-97943ce9526d`) came back from `create()`, and the first
+ * `environment.stream()` failed 78 seconds later with "A sandbox lifecycle
+ * operation is already in progress". That string is the platform's, not the
+ * SDK's, and n is 1, so the incarnation window is the mechanism this wait
+ * addresses rather than a proven cause. A lifecycle lock held by a genuinely
+ * concurrent operation is a different failure, and no client-side wait
+ * prevents it.
+ *
+ * Readiness also decides what the environment can claim. Composing an
+ * environment reads the sandbox's deployment capability document once, and a
+ * sandbox that is not yet running cannot answer that read, so an environment
+ * composed during provisioning claims nothing for the rest of its life.
+ *
+ * The platform owns the wait, and this adapter runs no status loop of its own.
+ * `waitFor` on the created instance is preferred because it refreshes that
+ * instance in place, which keeps the create receipt and gains the runtime
+ * connection the environment reads.
+ */
+export declare function awaitSandboxRunning(box: SandboxInstanceLike, client: SandboxClientLike, options: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<void>;

package/dist/tangle-readiness.js

@@ -0,0 +1,100 @@
+import { awaitWithSignal } from "./tangle-contract-safety.js";
+import { statusFromUnknown } from "./tangle-environment-values.js";
+/**
+ * How long `create()` waits for a new sandbox to reach `running`.
+ *
+ * The value is the Sandbox SDK's own wait default, so the adapter states no
+ * second deadline that disagrees with the platform's.
+ */
+export const DEFAULT_TANGLE_READY_TIMEOUT_MS = 120_000;
+/**
+ * Hold `create()` until the sandbox can accept a turn.
+ *
+ * The gap this closes is narrow and specific. `client.create()` waits by
+ * itself only when the create response reports `pending` or `provisioning`.
+ * A response that already reports `running` skips that wait, and `running`
+ * alone is not usable: the SDK's own `waitFor` treats the target as reached
+ * only when `filesystemIncarnationReadiness` is `ready`, because the box's
+ * filesystem is still being built until then. So `create()` can return a box
+ * that reports `running` while the platform still holds a lifecycle operation
+ * on it, and the first turn lands on that lock.
+ *
+ * Measured against that mechanism, 2026-09-01, discovery-lab#467: one box
+ * (`sandbox-97943ce9526d`) came back from `create()`, and the first
+ * `environment.stream()` failed 78 seconds later with "A sandbox lifecycle
+ * operation is already in progress". That string is the platform's, not the
+ * SDK's, and n is 1, so the incarnation window is the mechanism this wait
+ * addresses rather than a proven cause. A lifecycle lock held by a genuinely
+ * concurrent operation is a different failure, and no client-side wait
+ * prevents it.
+ *
+ * Readiness also decides what the environment can claim. Composing an
+ * environment reads the sandbox's deployment capability document once, and a
+ * sandbox that is not yet running cannot answer that read, so an environment
+ * composed during provisioning claims nothing for the rest of its life.
+ *
+ * The platform owns the wait, and this adapter runs no status loop of its own.
+ * `waitFor` on the created instance is preferred because it refreshes that
+ * instance in place, which keeps the create receipt and gains the runtime
+ * connection the environment reads.
+ */
+export async function awaitSandboxRunning(box, client, options) {
+    const { timeoutMs, signal } = options;
+    signal?.throwIfAborted();
+    const waitOptions = {
+        timeoutMs,
+        ...(signal ? { signal } : {}),
+    };
+    const wait = waitForRunning(box, client, waitOptions);
+    if (wait === undefined) {
+        // A client that offers no wait cannot prove readiness, so the sandbox it
+        // returned has to prove it by itself or the create call fails.
+        assertRunning(box, box.status, "the linked client provides neither instance waitFor() nor client waitForRunning()");
+        return;
+    }
+    let observed;
+    try {
+        observed = await awaitWithSignal(wait(), signal);
+    }
+    catch (error) {
+        // An abort is the caller's own outcome and keeps its identity.
+        if (signal?.aborted)
+            throw error;
+        throw new Error(`Tangle sandbox ${box.id} did not reach running: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    // A wait that resolves is the platform's answer, and the status it leaves
+    // behind is that answer in a readable form. Reading it back costs nothing
+    // and refuses a client whose wait resolves over a sandbox that is not
+    // running, which is the one way a half-started environment could still
+    // reach the caller.
+    assertRunning(box, observed, "its wait resolved without reaching running");
+}
+function assertRunning(box, status, reason) {
+    const observed = statusFromUnknown(status);
+    if (observed === "running")
+        return;
+    throw new Error(`Tangle create cannot return sandbox ${box.id}: it reports ${observed} and ${reason}`);
+}
+function waitForRunning(box, client, options) {
+    const instanceWait = box.waitFor;
+    if (instanceWait) {
+        return async () => {
+            await instanceWait.call(box, "running", options);
+            // `waitFor` refreshes this instance in place, so this instance now holds
+            // the status the platform answered with.
+            return box.status;
+        };
+    }
+    const clientWait = client.waitForRunning;
+    if (clientWait) {
+        return async () => {
+            const ready = await clientWait.call(client, box.id, options);
+            // The client-side wait resolves a second instance for the same id. That
+            // instance carries the platform's answer; the created instance still
+            // holds what it was returned with until it refreshes.
+            await box.refresh?.(options.signal);
+            return ready?.id === box.id ? ready.status : undefined;
+        };
+    }
+    return undefined;
+}

package/dist/tangle-types.d.ts

@@ -37,6 +37,15 @@ export interface SandboxClientLike {
     get?(id: string, requestOptions?: {
         signal?: AbortSignal;
     }): Promise<SandboxInstanceLike | null>;
+    /**
+     * Poll a sandbox to `running` by id, and report a provision failure with the
+     * platform's own reason. It resolves a second instance for the same id, so a
+     * caller that holds the created instance refreshes that instance afterwards.
+     */
+    waitForRunning?(id: string, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<SandboxInstanceLike>;
     list?(options?: {
         scope?: string;
         limit?: number;
@@ -455,6 +464,15 @@ export interface SandboxInstanceLike {
      * by id or when the platform reported no receipt.
      */
     createReceipt?(): SandboxCreateReceiptLike | null;
+    /**
+     * Hold until this sandbox reaches a lifecycle status, refreshing this
+     * instance in place. Preferred over the client-side wait because the created
+     * instance keeps its create receipt and gains its runtime connection.
+     */
+    waitFor?(status: "running", options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
     refresh?(signal?: AbortSignal): Promise<void>;
     delete?(options?: {
         signal?: AbortSignal;
@@ -565,6 +583,12 @@ export interface TangleProviderOptions {
     validateProfile?: AgentEnvironmentProvider["validateProfile"];
     mapCreateInput?: (input: CreateAgentEnvironmentInput) => CreateSandboxOptions;
     exactProcess?: TangleExactProcessOptions;
+    /**
+     * How long `create()` waits for a new sandbox to reach `running` before it
+     * fails. Defaults to `DEFAULT_TANGLE_READY_TIMEOUT_MS`, exported from this
+     * package, which is the Sandbox SDK's own wait default of 120 seconds.
+     */
+    readyTimeoutMs?: number;
     /** External provider-key and measurement verifier for confidential forks. */
     confidentialAttestationVerifier?: TangleConfidentialAttestationVerifier;
 }

package/dist/tangle-workspace-branching.js

@@ -303,47 +303,64 @@ export function createTangleWorkspaceBranching(options) {
                 : "Sandbox checkpoint inventory is unavailable", true);
         }
         const metadata = forkMarkerMetadata(request);
-        let result;
+        let returnedChild;
+        let outcome;
         try {
-            result = await awaitWithSignal(box.fork?.(1, {
-                metadata,
+            // Sandbox fork copies live VM memory, not the durable workspace view.
+            // Restore the checkpoint so files written before the checkpoint survive.
+            returnedChild = await awaitWithSignal(client.create({
+                fromSnapshot: request.checkpoint.checkpointId,
+                fromSandboxId: box.id,
                 idempotencyKey: request.idempotencyKey,
-            }), operation?.signal);
+                metadata,
+                ...(request.name === undefined ? {} : { name: request.name }),
+            }, operation?.signal === undefined
+                ? undefined
+                : { signal: operation.signal }), operation?.signal);
+            const receipt = returnedChild.createReceipt?.();
+            if (!receipt ||
+                receipt.idempotencyKeyApplied !== true ||
+                (receipt.outcome !== "created" &&
+                    receipt.outcome !== "idempotent_replay")) {
+                const compensation = await compensateCreatedForkChild(returnedChild, receipt?.outcome === "created" ? "created" : "replayed", operation?.signal);
+                const removed = compensation === "destroyed" || compensation === "already_absent";
+                return forkUnknown(request, removed
+                    ? "Sandbox snapshot restore returned no complete create receipt; the newly created child was removed"
+                    : "Sandbox snapshot restore returned no complete create receipt; child cleanup was not confirmed", !removed);
+            }
+            outcome =
+                receipt.outcome === "idempotent_replay" ? "replayed" : "created";
         }
         catch (error) {
             operation?.signal?.throwIfAborted();
             const conflict = await forkConflictFromRemote(client, box, provider, request, options.confidentialAttestationVerifier, operation?.signal);
             return (conflict ??
-                forkUnknown(request, `Sandbox fork outcome is unresolved: ${safeError(error)}`, true));
-        }
-        if (!result ||
-            !validForkResult(result) ||
-            result.idempotency === undefined ||
-            (result.idempotency.outcome !== "created" &&
-                result.idempotency.outcome !== "replayed") ||
-            safeString(result.idempotency.requestDigest) === undefined) {
-            return forkUnknown(request, "Sandbox fork returned no complete idempotent acknowledgement", true);
-        }
-        if (result.children.length !== 1 || result.complete !== true) {
-            return forkUnknown(request, "Sandbox fork did not materialize exactly one complete child", true);
+                forkUnknown(request, `Sandbox snapshot restore outcome is unresolved: ${safeError(error)}`, true));
+        }
+        if (!returnedChild ||
+            typeof returnedChild !== "object" ||
+            safeIdentifier(returnedChild.id) === undefined ||
+            returnedChild.id === box.id) {
+            const compensation = returnedChild
+                ? await compensateCreatedForkChild(returnedChild, outcome, operation?.signal)
+                : "not_attempted";
+            const removed = compensation === "destroyed" || compensation === "already_absent";
+            return forkUnknown(request, removed
+                ? "Sandbox snapshot restore returned an invalid child; the newly created child was removed"
+                : "Sandbox snapshot restore returned an invalid child; child cleanup was not confirmed", !removed);
         }
-        const returnedChild = result.children[0];
         const child = await completeForkChild(client, returnedChild, operation?.signal);
         if (!child) {
-            const compensation = forkMarkerFromMetadata(returnedChild.metadata) === undefined
-                ? await compensateUnmarkedForkChild(result, returnedChild, operation?.signal)
-                : "not_attempted";
+            const compensation = await compensateCreatedForkChild(returnedChild, outcome, operation?.signal);
             const removed = compensation === "destroyed" || compensation === "already_absent";
             return forkUnknown(request, removed
-                ? "Sandbox fork returned a child without a complete identity; the newly created child was removed"
-                : compensation === "unconfirmed"
-                    ? "Sandbox fork returned a child without a complete identity; child cleanup was not confirmed"
-                    : "Sandbox fork returned a child without a complete identity", !removed);
+                ? "Sandbox snapshot restore returned a child without a complete identity; the newly created child was removed"
+                : "Sandbox snapshot restore returned a child without a complete identity; child cleanup was not confirmed", !removed);
         }
         const childMarker = forkMarkerFromMetadata(child.metadata);
         if (childMarker) {
             if (!markerBelongsToSource(childMarker, provider, box.id)) {
-                return forkUnknown(request, "Sandbox fork returned a child marked for another source", true);
+                return forkUnknown(request, "Sandbox snapshot restore returned a child marked for another source", true);
             }
             if (childMarker.idempotencyKey !== request.idempotencyKey ||
                 childMarker.requestDigest !== request.requestDigest) {
@@ -351,21 +368,19 @@ export function createTangleWorkspaceBranching(options) {
             }
         }
         if (!childMarker) {
-            const compensation = await compensateUnmarkedForkChild(result, child, operation?.signal);
+            const compensation = await compensateCreatedForkChild(returnedChild, outcome, operation?.signal);
             const removed = compensation === "destroyed" || compensation === "already_absent";
             return forkUnknown(request, removed
-                ? "Sandbox fork acknowledgement omitted its provider recovery marker; the newly created child was removed"
-                : compensation === "unconfirmed"
-                    ? "Sandbox fork acknowledgement omitted its provider recovery marker; child cleanup was not confirmed"
-                    : "Sandbox fork acknowledgement omitted its provider recovery marker", !removed);
+                ? "Sandbox snapshot restore acknowledgement omitted its provider recovery marker; the newly created child was removed"
+                : "Sandbox snapshot restore acknowledgement omitted its provider recovery marker; child cleanup was not confirmed", !removed);
         }
         const environment = await environmentFromChild(request, child, provider, child.createdAt, options.confidentialAttestationVerifier, operation?.signal);
         if (!environment) {
-            return forkUnknown(request, "Sandbox fork returned a child without a valid identity", true);
+            return forkUnknown(request, "Sandbox snapshot restore returned a child without a valid identity", true);
         }
         const record = { request, environment, child };
         forks.set(request.idempotencyKey, record);
-        return forkSuccess(request, environment, result.idempotency.outcome);
+        return forkSuccess(request, environment, outcome);
     };
     const lookupFork = async (input, operation) => {
         const request = WorkspaceOperationLookupRequestSchema.parse(input);
@@ -461,14 +476,13 @@ export function createTangleWorkspaceBranching(options) {
 }
 /** Capability support requires every operation used by recovery and cleanup. */
 export function supportsWorkspaceBranching(box, client) {
-    return (typeof client.list === "function" &&
+    return (typeof client.create === "function" &&
+        typeof client.list === "function" &&
         typeof client.get === "function" &&
         typeof box.snapshot === "function" &&
         typeof box.listSnapshots === "function" &&
         typeof box.deleteSnapshot === "function" &&
-        typeof box.getSnapshotOperation === "function" &&
-        typeof box.fork === "function" &&
-        typeof box.getForkOperation === "function");
+        typeof box.getSnapshotOperation === "function");
 }
 /** Drop every in-process record for a resource the platform no longer holds. */
 function forgetRecords(records, matches) {
@@ -689,16 +703,6 @@ function validSnapshotInfo(snapshot, sandboxId) {
         safeIdentifier(snapshot.sandboxId) !== undefined &&
         (sandboxId === undefined || snapshot.sandboxId === sandboxId));
 }
-function validForkResult(result) {
-    return (!!result &&
-        Array.isArray(result.children) &&
-        result.children.every((child) => child !== null &&
-            typeof child === "object" &&
-            safeIdentifier(child.id) !== undefined) &&
-        result.requestedCount === 1 &&
-        result.materializedCount === result.children.length &&
-        typeof result.complete === "boolean");
-}
 function validOperationRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -750,7 +754,7 @@ function legacyCheckpointMarkerTags(request) {
         ...chunks.map((chunk, index) => `${base}:material:${index}:${chunks.length}:${chunk}`),
     ];
 }
-function forkMarkerMetadata(request) {
+function forkMarkerMetadata(request, materialization = "snapshot") {
     if (request.metadata && Object.hasOwn(request.metadata, FORK_METADATA_KEY)) {
         throw new Error(`fork metadata reserves ${FORK_METADATA_KEY}`);
     }
@@ -760,6 +764,7 @@ function forkMarkerMetadata(request) {
         idempotencyKey: request.idempotencyKey,
         requestDigest: request.requestDigest,
         request,
+        ...(materialization === "snapshot" ? { materialization } : {}),
     };
     assertBoundedJson(marker);
     return {
@@ -787,11 +792,18 @@ async function checkpointOperationSucceeded(box, marker, signal) {
         lookup.kind === "checkpoint" &&
         lookup.state === "succeeded");
 }
-/** The fork equivalent of {@link checkpointOperationSucceeded}. */
+/** Confirm a fork child through its marker or the legacy fork ledger. */
 async function forkOperationLookup(box, marker, signal) {
+    if (marker.materialization === "snapshot") {
+        return {
+            outcome: "found",
+            kind: "fork",
+            state: "succeeded",
+        };
+    }
     const lookup = await awaitWithSignal(box.getForkOperation?.(marker.idempotencyKey, {
         count: 1,
-        metadata: forkMarkerMetadata(marker.request),
+        metadata: forkMarkerMetadata(marker.request, marker.materialization),
     }), signal);
     return lookup;
 }
@@ -1023,9 +1035,9 @@ async function completeForkChild(client, child, signal) {
         return undefined;
     }
 }
-/** Remove only a child this exact call confirmed it created. */
-async function compensateUnmarkedForkChild(result, child, signal) {
-    if (result.idempotency?.outcome !== "created")
+/** Remove only a child this exact create call confirmed it created. */
+async function compensateCreatedForkChild(child, outcome, signal) {
+    if (outcome !== "created")
         return "not_attempted";
     if (typeof child.delete !== "function")
         return "unconfirmed";
@@ -1266,6 +1278,10 @@ function forkMarkerFromMetadata(metadata, key) {
         typeof parsed.idempotencyKey !== "string" ||
         typeof parsed.requestDigest !== "string")
         return undefined;
+    if (parsed.materialization !== undefined &&
+        parsed.materialization !== "snapshot") {
+        return undefined;
+    }
     if (key !== undefined && parsed.idempotencyKey !== key)
         return undefined;
     const request = WorkspaceForkRequestSchema.safeParse(parsed.request);
@@ -1279,6 +1295,9 @@ function forkMarkerFromMetadata(metadata, key) {
         idempotencyKey: parsed.idempotencyKey,
         requestDigest: parsed.requestDigest,
         request: request.data,
+        ...(parsed.materialization === "snapshot"
+            ? { materialization: "snapshot" }
+            : {}),
     };
 }
 /**

package/package.json

@@ -1,16 +1,15 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "dist/index.js",
+  "types": "src/index.ts",
   "exports": {
     ".": {
       "import": "./dist/index.js",
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+      "types": "./src/index.ts"
     }
   },
   "repository": {
@@ -20,7 +19,16 @@
   },
   "publishConfig": {
     "access": "public",
-    "registry": "https://registry.npmjs.org"
+    "registry": "https://registry.npmjs.org",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "import": "./dist/index.js",
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
   },
   "files": [
     "dist/index.d.ts",
@@ -75,6 +83,8 @@
     "dist/tangle-prompt.js",
     "dist/tangle-provider.d.ts",
     "dist/tangle-provider.js",
+    "dist/tangle-readiness.d.ts",
+    "dist/tangle-readiness.js",
     "dist/tangle-result-values.d.ts",
     "dist/tangle-result-values.js",
     "dist/tangle-session-control.d.ts",
@@ -88,8 +98,15 @@
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check-types": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "pnpm run build",
+    "test": "vitest run src"
+  },
   "dependencies": {
-    "@tangle-network/agent-interface": "^2.0.0"
+    "@tangle-network/agent-interface": "^2.2.0"
   },
   "peerDependencies": {
     "@tangle-network/sandbox": ">=0.34.6 <1.0.0"
@@ -101,17 +118,11 @@
   },
   "devDependencies": {
     "@tangle-network/agent-eval": "0.170.0",
+    "@tangle-network/agent-provider-testkit": "workspace:*",
     "@tangle-network/agent-runtime": "0.184.0",
     "@tangle-network/sandbox": "0.34.6",
-    "@types/node": "26.4.0",
+    "@types/node": "catalog:",
     "typescript": "7.0.2",
-    "vitest": "4.1.11",
-    "@tangle-network/agent-provider-testkit": "0.8.6"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "check-types": "tsc --noEmit",
-    "clean": "rm -rf dist",
-    "test": "vitest run src"
+    "vitest": "catalog:"
   }
-}
+}