@tangle-network/agent-provider-tangle 1.0.2 → 1.1.1

package/README.md

@@ -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
 

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
@@ -69,6 +71,8 @@ export async function sandboxInstanceAsEnvironment(box, providerName, client, de
     // Usage is measured per execution, so the log collects what runs through
     // this handle and the observation reports the newest record it holds.
     const usageLog = createExecutionUsageLog();
+    // The single destroy this handle performs, once it has been asked for.
+    let destruction;
     const terminals = capabilities.interactiveTerminal?.attach === true
         ? createTangleTerminalRegistry(box)
         : undefined;
@@ -308,7 +312,31 @@ export async function sandboxInstanceAsEnvironment(box, providerName, client, de
                         throw new Error("Tangle sandbox client cannot delete this environment");
                     assertOptionKeys(options, ["signal"], "Tangle destroy");
                     options?.signal?.throwIfAborted();
-                    await awaitWithSignal(box.delete(options), options?.signal);
+                    // One environment has more than one owner of its end. A runtime
+                    // that destroys on settle AND tears the executor down calls this
+                    // twice for the same box, and the platform refuses the second
+                    // DELETE with "A sandbox lifecycle operation is already in
+                    // progress" while the first one's cleanup still holds the
+                    // sandbox's lifecycle lease. Measured 2026-09-01 on
+                    // `sandbox-b525e04a551b`: of two concurrent deletes one answered
+                    // 200 `destroyed` and the other 409, and a third delete 0.4 s
+                    // after the 200 was still refused. That refusal cost two
+                    // completed agent turns their result
+                    // (tangle-network/agent-sdk#280), because the second destroy ran
+                    // in a caller's `finally` and its throw replaced the run's own
+                    // outcome.
+                    //
+                    // So destroy is answered once per environment and every later
+                    // caller joins that answer. This is not a retry and hides no
+                    // platform error: a delete that fails is not remembered, and the
+                    // next caller issues a real one.
+                    destruction ??= awaitWithSignal(box.delete(options), options?.signal)
+                        .then(() => undefined)
+                        .catch((error) => {
+                        destruction = undefined;
+                        throw error;
+                    });
+                    await awaitWithSignal(destruction, options?.signal);
                     options?.signal?.throwIfAborted();
                 },
             }

package/dist/tangle-exact-process-environment.js

@@ -11,6 +11,9 @@ export function sandboxInstanceAsExactProcessEnvironment(box, providerName) {
     const process = box.process;
     const fs = box.fs;
     const destroy = box.delete.bind(box);
+    // The same single delete this environment performs, once it is asked for.
+    // See the destroy() below for why one is all the platform accepts.
+    let destruction;
     return {
         id: box.id,
         provider: providerName,
@@ -177,7 +180,22 @@ export function sandboxInstanceAsExactProcessEnvironment(box, providerName) {
         async destroy(options = {}) {
             assertSignalOptions(options, "Tangle exact process destroy");
             options.signal?.throwIfAborted();
-            await awaitWithSignal(destroy(), options.signal);
+            // Deleting one sandbox twice is refused, not repeated: the platform
+            // holds a per-sandbox lifecycle lease past the first DELETE's own
+            // response while its deferred cleanup runs, so a second DELETE inside
+            // that window answers "A sandbox lifecycle operation is already in
+            // progress". Measured 2026-09-01 (issue #280) on the streaming
+            // environment, which has the same shape and the same platform route.
+            // This environment is destroyed once and later callers join that
+            // answer; a delete that fails is not remembered, so nothing hides a
+            // real error.
+            destruction ??= awaitWithSignal(destroy(), options.signal)
+                .then(() => undefined)
+                .catch((error) => {
+                destruction = undefined;
+                throw error;
+            });
+            await awaitWithSignal(destruction, options.signal);
             options.signal?.throwIfAborted();
         },
     };

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. An environment composed before
+ * that is an environment that cannot accept a turn.
+ *
+ * WHAT THIS WAIT IS NOT FOR. An earlier version of this comment claimed the
+ * wait also closed the platform's "A sandbox lifecycle operation is already in
+ * progress", and that claim is withdrawn: measured 2026-09-01 (issue #280),
+ * that refusal comes from `DELETE /v1/sandboxes/:id`, not from a turn. The
+ * platform guards exactly three routes with the per-sandbox lifecycle lease —
+ * resume, stop and delete — and the runtime path a prompt takes is not one of
+ * them, so no readiness wait here can prevent it and none is trying to. The
+ * collision is answered where it happens, in `destroy()`
+ * (`tangle-environment.ts`).
+ *
+ * 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. An environment composed before
+ * that is an environment that cannot accept a turn.
+ *
+ * WHAT THIS WAIT IS NOT FOR. An earlier version of this comment claimed the
+ * wait also closed the platform's "A sandbox lifecycle operation is already in
+ * progress", and that claim is withdrawn: measured 2026-09-01 (issue #280),
+ * that refusal comes from `DELETE /v1/sandboxes/:id`, not from a turn. The
+ * platform guards exactly three routes with the per-sandbox lifecycle lease —
+ * resume, stop and delete — and the runtime path a prompt takes is not one of
+ * them, so no readiness wait here can prevent it and none is trying to. The
+ * collision is answered where it happens, in `destroy()`
+ * (`tangle-environment.ts`).
+ *
+ * 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/package.json

@@ -1,16 +1,15 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "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:"
   }
-}
+}