@tangle-network/agent-app 0.45.4 → 0.45.6

package/dist/sandbox/index.d.ts

@@ -261,6 +261,277 @@ declare function statSandboxFileSize(box: SandboxExecChannel, absolutePath: stri
  *  mismatch is reported, never returned as a short buffer. */
 declare function readSandboxBinaryBytes(box: SandboxExecChannel, absolutePath: string, expectedSize: number, options?: SandboxExecOptions): Promise<SandboxFileBytesOutcome>;
 
+/**
+ * What an app does after the platform hands back a sandbox it cannot use.
+ *
+ * `replaceUnbringableBox` (see `./index`) decides whether to abandon a dead box.
+ * This decides everything around that: which box key the next attempt uses,
+ * whether the old box's snapshot is safe to restore from, whether an owner has
+ * to confirm the loss first, and what the person waiting is told. It is
+ * bookkeeping, not I/O — the app supplies storage through
+ * {@link WorkspaceSandboxRecoveryStore}.
+ *
+ * ── Why the tables ──────────────────────────────────────────────────────────
+ * Every fact about an action or a code lives in ACTIONS/CODES below, and the
+ * types are DERIVED from those tables. That is deliberate, and it is the whole
+ * reliability argument for this module.
+ *
+ * The hand-maintained alternative — a union type plus a separate `x === 'a' ||
+ * x === 'b' || …` list per question — silently drops anything not on the list.
+ * A recovery recorded under an unlisted action is written to storage, read
+ * back, discarded as malformed, and the workspace re-provisions the box it just
+ * abandoned. Nothing throws. The fix looks correct, ships, and does nothing.
+ * That failure was hit twice inside one change before this module existed.
+ *
+ * With the tables, adding an action or code is a compile error until every
+ * question about it is answered. There is no list to forget.
+ */
+/** The box exists and still holds unsnapshotted state, so discarding it is an
+ *  owner's decision, not the runtime's. */
+declare const EGRESS_PROXY_RECOVERY_REQUIRED = "EGRESS_PROXY_RECOVERY_REQUIRED";
+declare const EGRESS_PROXY_RECOVERY_PHASE = "egress_proxy_recovery";
+/** The platform no longer has the box. Nothing to confirm, delete, or restore. */
+declare const WORKSPACE_SANDBOX_MISSING = "WORKSPACE_SANDBOX_MISSING";
+/** The box exists but its host has no free slot, so it can never be resumed
+ *  where it is. A replacement can be placed on a host with room. */
+declare const WORKSPACE_SANDBOX_HOST_EXHAUSTED = "WORKSPACE_SANDBOX_HOST_EXHAUSTED";
+/** The platform ran its own recovery, failed, and asked for a replacement.
+ *  Covers every way a box ends up unbringable with no more specific cause. */
+declare const WORKSPACE_SANDBOX_UNRECOVERABLE = "WORKSPACE_SANDBOX_UNRECOVERABLE";
+declare const WORKSPACE_SANDBOX_SNAPSHOT_MAX_AGE_MS: number;
+/**
+ * Every recovery cause, and the one thing the runtime must know about each:
+ * whether the box it names can still be read from.
+ *
+ * `snapshotUsable: false` is not a preference. A snapshot is addressed by the
+ * sandbox it was taken from, so when that sandbox cannot be started the restore
+ * fails exactly the way the resume did — and an app that tried it would turn a
+ * recoverable workspace into a stuck one.
+ */
+declare const CODES: {
+    readonly EGRESS_PROXY_RECOVERY_REQUIRED: {
+        readonly snapshotUsable: true;
+    };
+    readonly WORKSPACE_SANDBOX_MISSING: {
+        readonly snapshotUsable: false;
+    };
+    readonly WORKSPACE_SANDBOX_HOST_EXHAUSTED: {
+        readonly snapshotUsable: false;
+    };
+    readonly WORKSPACE_SANDBOX_UNRECOVERABLE: {
+        readonly snapshotUsable: false;
+    };
+};
+type WorkspaceSandboxRecoveryCode = keyof typeof CODES;
+/**
+ * Every recovery action, and whether it means a replacement box has been
+ * CHOSEN — the single question that decides which box key the next provisioning
+ * attempt uses.
+ *
+ * `replacementChosen: false` covers the states where a key may be recorded but
+ * must not be used yet: an owner has been asked and has not answered, or has
+ * answered no. Handing back a key in those states replaces a box the owner
+ * declined to lose.
+ */
+declare const ACTIONS: {
+    readonly confirmation_required: {
+        readonly replacementChosen: false;
+    };
+    readonly deletion_declined: {
+        readonly replacementChosen: false;
+    };
+    readonly replacement_authorized: {
+        readonly replacementChosen: false;
+    };
+    readonly snapshot_replacement_authorized: {
+        readonly replacementChosen: false;
+    };
+    readonly replacement_started: {
+        readonly replacementChosen: true;
+    };
+    readonly replacement_completed: {
+        readonly replacementChosen: true;
+    };
+    readonly snapshot_replacement_started: {
+        readonly replacementChosen: true;
+    };
+    readonly snapshot_restore_failed: {
+        readonly replacementChosen: true;
+    };
+    readonly snapshot_replacement_completed: {
+        readonly replacementChosen: true;
+    };
+    readonly missing_replacement_started: {
+        readonly replacementChosen: true;
+    };
+    readonly missing_replacement_completed: {
+        readonly replacementChosen: true;
+    };
+    readonly unrecoverable_replacement_started: {
+        readonly replacementChosen: true;
+    };
+    readonly unrecoverable_replacement_completed: {
+        readonly replacementChosen: true;
+    };
+};
+type WorkspaceSandboxRecoveryAction = keyof typeof ACTIONS;
+type WorkspaceSandboxSnapshotAvailability = 'available' | 'missing' | 'stale';
+type WorkspaceSandboxSnapshotFreshness = 'fresh' | 'stale' | 'unknown';
+/** A snapshot the app took of a box, addressed by the box it came from. */
+interface WorkspaceSandboxSnapshot {
+    fromSandboxId: string;
+    createdAt: string;
+    [key: string]: unknown;
+}
+interface WorkspaceSandboxSnapshotAssessment {
+    availability: WorkspaceSandboxSnapshotAvailability;
+    freshness: WorkspaceSandboxSnapshotFreshness;
+    snapshot?: WorkspaceSandboxSnapshot;
+}
+interface WorkspaceSandboxRecoveryState {
+    code: WorkspaceSandboxRecoveryCode;
+    sandboxId: string;
+    detectedAt: string;
+    snapshot: WorkspaceSandboxSnapshotAssessment;
+    action: WorkspaceSandboxRecoveryAction;
+    replacementBoxKey?: string;
+    replacementSandboxId?: string;
+    confirmedAt?: string;
+}
+type WorkspaceSandboxRecoveryDecision = 'replace' | 'decline';
+/** Raised when chat cannot continue until an owner decides about the box. */
+declare class WorkspaceSandboxRecoveryRequiredError extends Error {
+    readonly code = "EGRESS_PROXY_RECOVERY_REQUIRED";
+    readonly status = 409;
+    readonly phase = "egress_proxy_recovery";
+    readonly recovery: WorkspaceSandboxRecoveryState;
+    constructor(recovery: WorkspaceSandboxRecoveryState, cause: Error);
+}
+declare function isEgressProxyRecoveryRequiredError(error: unknown): boolean;
+declare function isWorkspaceSandboxSnapshotRestoreError(error: unknown): boolean;
+/**
+ * Judge a snapshot against the box being replaced.
+ *
+ * Fresh means BOTH that it came from this exact sandbox and that it is inside
+ * the age bound — a snapshot from a different box restores someone else's
+ * filesystem, which is worse than starting empty.
+ */
+declare function assessWorkspaceSandboxSnapshot(snapshot: WorkspaceSandboxSnapshot | undefined, sandboxId: string, now?: number): WorkspaceSandboxSnapshotAssessment;
+declare function isWorkspaceSandboxRecoveryAction(value: unknown): value is WorkspaceSandboxRecoveryAction;
+declare function isWorkspaceSandboxRecoveryCode(value: unknown): value is WorkspaceSandboxRecoveryCode;
+declare function isWorkspaceSandboxRecoveryState(value: unknown): value is WorkspaceSandboxRecoveryState;
+declare function workspaceSandboxRecoveryFromError(error: unknown): WorkspaceSandboxRecoveryState | undefined;
+/** What to tell the person waiting. Never names the product, so an app can
+ *  surface it verbatim. */
+declare function workspaceSandboxRecoveryMessage(recovery: WorkspaceSandboxRecoveryState): string;
+declare function workspaceSandboxRecoveryRecommendedActions(recovery: WorkspaceSandboxRecoveryState): string[];
+/** Flat key/value shape for a log line — no nesting, no secrets. */
+declare function workspaceSandboxRecoveryDiagnostic(recovery: WorkspaceSandboxRecoveryState): Record<string, string | undefined>;
+/**
+ * The box key the next provisioning attempt should use, or undefined to keep
+ * using the workspace's own key.
+ *
+ * Reads {@link ACTIONS} rather than a hand-kept list, because the failure mode
+ * of a hand-kept list here is invisible: the key is recorded, silently ignored,
+ * and provisioning goes back to the box the app just decided to abandon.
+ */
+declare function preferredWorkspaceSandboxRecoveryBoxKey(recovery: WorkspaceSandboxRecoveryState | undefined): string | undefined;
+/** Whether the replacement should be restored from the old box's snapshot. */
+declare function shouldRestoreWorkspaceSandboxRecovery(recovery: WorkspaceSandboxRecoveryState | undefined): boolean;
+/**
+ * Where an app keeps recovery state. One row per workspace, last write wins —
+ * a recovery is a current situation, not a history.
+ */
+interface WorkspaceSandboxRecoveryStore {
+    read: (workspaceId: string) => Promise<WorkspaceSandboxRecoveryState | undefined>;
+    write: (workspaceId: string, recovery: WorkspaceSandboxRecoveryState) => Promise<void>;
+}
+interface WorkspaceSandboxRecoveryManager {
+    read: (workspaceId: string) => Promise<WorkspaceSandboxRecoveryState | undefined>;
+    record: (workspaceId: string, recovery: WorkspaceSandboxRecoveryState) => Promise<void>;
+    /** Record an owner's decision. Returns undefined when the stored recovery does
+     *  not name this sandbox — a decision about a box that has already been
+     *  replaced must not resurrect it. */
+    decide: (args: {
+        workspaceId: string;
+        sandboxId: string;
+        decision: WorkspaceSandboxRecoveryDecision;
+        replacementBoxKey?: string;
+    }) => Promise<WorkspaceSandboxRecoveryState | undefined>;
+    /** Mark a replacement finished and name the box that took over. */
+    complete: (args: {
+        workspaceId: string;
+        replacementSandboxId: string;
+    }) => Promise<WorkspaceSandboxRecoveryState | undefined>;
+}
+/**
+ * Bind the recovery bookkeeping to an app's storage.
+ *
+ * The app owns persistence — a D1 column, a KV key, a Postgres row — and
+ * nothing else. Every rule about which action means what stays here, so it
+ * cannot drift between apps.
+ */
+declare function createWorkspaceSandboxRecoveryManager(store: WorkspaceSandboxRecoveryStore): WorkspaceSandboxRecoveryManager;
+/** Every declared action, for exhaustiveness tests in apps and here. */
+declare const WORKSPACE_SANDBOX_RECOVERY_ACTIONS: readonly WorkspaceSandboxRecoveryAction[];
+/** Every declared cause. */
+declare const WORKSPACE_SANDBOX_RECOVERY_CODES: readonly WorkspaceSandboxRecoveryCode[];
+
+interface SafeSandboxErrorCause {
+    name?: string;
+    message?: string;
+    code?: string | number;
+    status?: string | number;
+    phase?: string;
+    endpoint?: string;
+    origin?: string;
+    retryAfterMs?: number;
+    sidecarVersion?: string;
+    containerImage?: string;
+}
+interface SafeSandboxErrorDiagnostics {
+    message: string;
+    causes: SafeSandboxErrorCause[];
+    truncated: boolean;
+    truncatedAtDepth?: number;
+    cycle: boolean;
+}
+declare function serializeSandboxProvisioningError(error: unknown, options?: {
+    maxDepth?: number;
+}): SafeSandboxErrorDiagnostics;
+declare function formatSandboxProvisioningSupportDetails(diagnostics: SafeSandboxErrorDiagnostics): string;
+declare function isSandboxAuthFailure(diagnostics: SafeSandboxErrorDiagnostics): boolean;
+declare function isSandboxApiBearerAuthFailure(diagnostics: SafeSandboxErrorDiagnostics): boolean;
+/**
+ * True when the sandbox API answered 404 for a specific sandbox resource — the
+ * box behind a persisted sandbox id no longer exists.
+ *
+ * A sandbox id is a cache of where a workspace's box lives, not the workspace's
+ * identity: the platform reaps, suspends, and loses boxes as ordinary lifecycle
+ * events. Callers use this to discard the dead id and provision a replacement,
+ * so the match is deliberately narrow — a 404 from the runtime sidecar
+ * (`/runtime/...`, a missing file or session inside a live box) is NOT this.
+ */
+declare function isSandboxApiSandboxMissingFailure(diagnostics: SafeSandboxErrorDiagnostics): boolean;
+/**
+ * True when a resume failed because the host the box is pinned to cannot seat
+ * it — the host's slot budget is exhausted, not the box's fault and not
+ * something waiting fixes.
+ *
+ * A box lives on one host. When that host fills, every future resume for every
+ * box on it fails identically and permanently, so a workspace whose box landed
+ * on a full host is bricked until it is placed somewhere else. Callers use this
+ * the same way they use {@link isSandboxApiSandboxMissingFailure}: discard the
+ * dead id and provision a replacement, which the orchestrator is free to place
+ * on a host with room. The workspace itself is preserved — it lives in the
+ * Vault, not in the box's filesystem.
+ *
+ * Matched on the message because the sandbox API returns a generic
+ * `SERVER_ERROR` for it; a dedicated code upstream would replace this.
+ */
+declare function isSandboxHostCapacityFailure(diagnostics: SafeSandboxErrorDiagnostics): boolean;
+declare function formatSandboxProvisioningUserMessage(diagnostics: SafeSandboxErrorDiagnostics): string;
+
 /** Define the shape of a workspace sandbox instance including its connection details and status. */
 interface WorkspaceSandboxInstanceLike {
     id: string;
@@ -998,6 +1269,7 @@ declare class SandboxEgressPolicyMismatchError extends Error {
     readonly desiredPolicy: EgressPolicy;
     constructor(stage: SandboxExistingBoxStage, boxName: string, currentPolicy: EgressPolicy, currentSource: SandboxEgressPolicySource, desiredPolicy: EgressPolicy);
 }
+
 /** Represent an error thrown when sandbox runtime authentication refresh fails for a specific stage and name */
 declare class SandboxRuntimeAuthRefreshError extends Error {
     constructor(stage: SandboxExistingBoxStage, name: string, detail: string, cause?: unknown);
@@ -1287,4 +1559,4 @@ declare function isTerminalPromptEvent(event: unknown): boolean;
 /** Resolve the interactive question text from a structured event or return null if none found */
 declare function detectInteractiveQuestion(event: unknown): string | null;
 
-export { type AppToolDescriptor, type BuildAppToolMcpServersOptions, type BuildSandboxToolFileMountsOptions, type D1PrewarmClaimStoreOptions, DEFAULT_PREWARM_CLAIM_TABLE, DEFAULT_SANDBOX_RESOURCES, DEFAULT_SIDECAR_PROCESS_PATTERN, type DriveSandboxTurnOptions, ENV_TOTAL_MAX_BYTES, ENV_VALUE_MAX_BYTES, type EnsureWorkspaceSandboxOptions, type LivenessProbeConfig, type MemberSyncSeam, type ModelSelection, type ModelSelectionError, type ModelSelectionFailure, type ModelSelectionSource, type Outcome, PREWARM_CLAIM_TABLE_DDL, PROVISION_PAYLOAD_MAX_BYTES, type PeekWorkspaceSandboxOutcome, type PrewarmClaimD1Like, type PrewarmClaimStore, type PrewarmDecision, type PrewarmEvent, type PrewarmOutcome, type PrewarmResult, type ProfileComposeOptions, type PromptInputPart, type ProviderResolutionConfig, type ProvisionPayloadSections, type ProvisionProfileSection, type ResolveSandboxClientCredentialsOptions, type ResolvedModel, type SandboxBuildContext, type SandboxClientCredentials, type SandboxCredentialEnvironment, SandboxEgressPolicyMismatchError, type SandboxEgressPolicySource, type SandboxExecChannel, type SandboxExecOptions, type SandboxExistingBoxStage, type SandboxFileBytesOutcome, type SandboxFileSizeOutcome, SandboxModelResolutionError, type SandboxPermissionLevel, type SandboxPrewarmScope, type SandboxPrewarmer, type SandboxPrewarmerOptions, type SandboxReadiness, SandboxRecoveryFailedError, type SandboxRecoveryPhase, type SandboxResourceConfig, type SandboxRestoreSpec, SandboxRuntimeAuthRefreshError, type SandboxRuntimeConfig, type SandboxScope, type SandboxStepTransition, type SandboxTerminalConnectionRouteOptions, type SandboxToolPathOptions, type SandboxToolSpec, type ScopedTokenResult, type SecretStore, type StoppedSandboxResumeFailure, type StoppedSandboxResumeRecovery, type StreamSandboxPromptOptions, type TerminalConnectionBoxLike, type WorkspaceSandboxEnsureContext, type WorkspaceSandboxInstanceLike, type WorkspaceSandboxManager, type WorkspaceSandboxManagerOptions, type WriteProfileFilesOptions, assertEnvWithinLimits, assertProvisionPayloadWithinCap, attachReasoningEffort, buildAppToolMcpServers, buildSandboxToolFileMounts, buildSandboxToolPathSetupScript, classifySeveredStream, collectSandboxPromptText, createD1PrewarmClaimStore, createSandboxPrewarmer, createSandboxTerminalConnectionRoute, createWorkspaceSandboxManager, deferredCorpusHash, deleteSecret, detectInteractiveQuestion, driveSandboxTurn, ensureWorkspaceSandbox, flattenHistory, getClient, isTerminalPromptEvent, mergeExtraMcp, mergeHistoryIntoParts, mintSandboxScopedToken, peekWorkspaceSandbox, readSandboxBinaryBytes, readSecret, requireTransportableModel, resetClientCache, resolveModel, resolveModelSelection, resolveSandboxClientCredentials, runSandboxPrompt, runSandboxToolPathSetup, sandboxToolBinDir, sandboxToolPath, sandboxToolRootDir, secretStoreFromClient, shellQuote, splitDeferredProfileFiles, statSandboxFileSize, storeSecret, streamSandboxPrompt, syncSandboxMemberAdd, syncSandboxMemberRemove, syncSandboxMemberRole, writeProfileFilesToBox };
+export { type AppToolDescriptor, type BuildAppToolMcpServersOptions, type BuildSandboxToolFileMountsOptions, type D1PrewarmClaimStoreOptions, DEFAULT_PREWARM_CLAIM_TABLE, DEFAULT_SANDBOX_RESOURCES, DEFAULT_SIDECAR_PROCESS_PATTERN, type DriveSandboxTurnOptions, EGRESS_PROXY_RECOVERY_PHASE, EGRESS_PROXY_RECOVERY_REQUIRED, ENV_TOTAL_MAX_BYTES, ENV_VALUE_MAX_BYTES, type EnsureWorkspaceSandboxOptions, type LivenessProbeConfig, type MemberSyncSeam, type ModelSelection, type ModelSelectionError, type ModelSelectionFailure, type ModelSelectionSource, type Outcome, PREWARM_CLAIM_TABLE_DDL, PROVISION_PAYLOAD_MAX_BYTES, type PeekWorkspaceSandboxOutcome, type PrewarmClaimD1Like, type PrewarmClaimStore, type PrewarmDecision, type PrewarmEvent, type PrewarmOutcome, type PrewarmResult, type ProfileComposeOptions, type PromptInputPart, type ProviderResolutionConfig, type ProvisionPayloadSections, type ProvisionProfileSection, type ResolveSandboxClientCredentialsOptions, type ResolvedModel, type SafeSandboxErrorCause, type SafeSandboxErrorDiagnostics, type SandboxBuildContext, type SandboxClientCredentials, type SandboxCredentialEnvironment, SandboxEgressPolicyMismatchError, type SandboxEgressPolicySource, type SandboxExecChannel, type SandboxExecOptions, type SandboxExistingBoxStage, type SandboxFileBytesOutcome, type SandboxFileSizeOutcome, SandboxModelResolutionError, type SandboxPermissionLevel, type SandboxPrewarmScope, type SandboxPrewarmer, type SandboxPrewarmerOptions, type SandboxReadiness, SandboxRecoveryFailedError, type SandboxRecoveryPhase, type SandboxResourceConfig, type SandboxRestoreSpec, SandboxRuntimeAuthRefreshError, type SandboxRuntimeConfig, type SandboxScope, type SandboxStepTransition, type SandboxTerminalConnectionRouteOptions, type SandboxToolPathOptions, type SandboxToolSpec, type ScopedTokenResult, type SecretStore, type StoppedSandboxResumeFailure, type StoppedSandboxResumeRecovery, type StreamSandboxPromptOptions, type TerminalConnectionBoxLike, WORKSPACE_SANDBOX_HOST_EXHAUSTED, WORKSPACE_SANDBOX_MISSING, WORKSPACE_SANDBOX_RECOVERY_ACTIONS, WORKSPACE_SANDBOX_RECOVERY_CODES, WORKSPACE_SANDBOX_SNAPSHOT_MAX_AGE_MS, WORKSPACE_SANDBOX_UNRECOVERABLE, type WorkspaceSandboxEnsureContext, type WorkspaceSandboxInstanceLike, type WorkspaceSandboxManager, type WorkspaceSandboxManagerOptions, type WorkspaceSandboxRecoveryAction, type WorkspaceSandboxRecoveryCode, type WorkspaceSandboxRecoveryDecision, type WorkspaceSandboxRecoveryManager, WorkspaceSandboxRecoveryRequiredError, type WorkspaceSandboxRecoveryState, type WorkspaceSandboxRecoveryStore, type WorkspaceSandboxSnapshot, type WorkspaceSandboxSnapshotAssessment, type WorkspaceSandboxSnapshotAvailability, type WorkspaceSandboxSnapshotFreshness, type WriteProfileFilesOptions, assertEnvWithinLimits, assertProvisionPayloadWithinCap, assessWorkspaceSandboxSnapshot, attachReasoningEffort, buildAppToolMcpServers, buildSandboxToolFileMounts, buildSandboxToolPathSetupScript, classifySeveredStream, collectSandboxPromptText, createD1PrewarmClaimStore, createSandboxPrewarmer, createSandboxTerminalConnectionRoute, createWorkspaceSandboxManager, createWorkspaceSandboxRecoveryManager, deferredCorpusHash, deleteSecret, detectInteractiveQuestion, driveSandboxTurn, ensureWorkspaceSandbox, flattenHistory, formatSandboxProvisioningSupportDetails, formatSandboxProvisioningUserMessage, getClient, isEgressProxyRecoveryRequiredError, isSandboxApiBearerAuthFailure, isSandboxApiSandboxMissingFailure, isSandboxAuthFailure, isSandboxHostCapacityFailure, isTerminalPromptEvent, isWorkspaceSandboxRecoveryAction, isWorkspaceSandboxRecoveryCode, isWorkspaceSandboxRecoveryState, isWorkspaceSandboxSnapshotRestoreError, mergeExtraMcp, mergeHistoryIntoParts, mintSandboxScopedToken, peekWorkspaceSandbox, preferredWorkspaceSandboxRecoveryBoxKey, readSandboxBinaryBytes, readSecret, requireTransportableModel, resetClientCache, resolveModel, resolveModelSelection, resolveSandboxClientCredentials, runSandboxPrompt, runSandboxToolPathSetup, sandboxToolBinDir, sandboxToolPath, sandboxToolRootDir, secretStoreFromClient, serializeSandboxProvisioningError, shellQuote, shouldRestoreWorkspaceSandboxRecovery, splitDeferredProfileFiles, statSandboxFileSize, storeSecret, streamSandboxPrompt, syncSandboxMemberAdd, syncSandboxMemberRemove, syncSandboxMemberRole, workspaceSandboxRecoveryDiagnostic, workspaceSandboxRecoveryFromError, workspaceSandboxRecoveryMessage, workspaceSandboxRecoveryRecommendedActions, writeProfileFilesToBox };

package/dist/sandbox/index.js

@@ -2,6 +2,8 @@ import {
   DEFAULT_PREWARM_CLAIM_TABLE,
   DEFAULT_SANDBOX_RESOURCES,
   DEFAULT_SIDECAR_PROCESS_PATTERN,
+  EGRESS_PROXY_RECOVERY_PHASE,
+  EGRESS_PROXY_RECOVERY_REQUIRED,
   ENV_TOTAL_MAX_BYTES,
   ENV_VALUE_MAX_BYTES,
   PREWARM_CLAIM_TABLE_DDL,
@@ -10,8 +12,16 @@ import {
   SandboxModelResolutionError,
   SandboxRecoveryFailedError,
   SandboxRuntimeAuthRefreshError,
+  WORKSPACE_SANDBOX_HOST_EXHAUSTED,
+  WORKSPACE_SANDBOX_MISSING,
+  WORKSPACE_SANDBOX_RECOVERY_ACTIONS,
+  WORKSPACE_SANDBOX_RECOVERY_CODES,
+  WORKSPACE_SANDBOX_SNAPSHOT_MAX_AGE_MS,
+  WORKSPACE_SANDBOX_UNRECOVERABLE,
+  WorkspaceSandboxRecoveryRequiredError,
   assertEnvWithinLimits,
   assertProvisionPayloadWithinCap,
+  assessWorkspaceSandboxSnapshot,
   attachReasoningEffort,
   buildAppToolMcpServers,
   buildSandboxToolFileMounts,
@@ -22,18 +32,31 @@ import {
   createSandboxPrewarmer,
   createSandboxTerminalConnectionRoute,
   createWorkspaceSandboxManager,
+  createWorkspaceSandboxRecoveryManager,
   deferredCorpusHash,
   deleteSecret,
   detectInteractiveQuestion,
   driveSandboxTurn,
   ensureWorkspaceSandbox,
   flattenHistory,
+  formatSandboxProvisioningSupportDetails,
+  formatSandboxProvisioningUserMessage,
   getClient,
+  isEgressProxyRecoveryRequiredError,
+  isSandboxApiBearerAuthFailure,
+  isSandboxApiSandboxMissingFailure,
+  isSandboxAuthFailure,
+  isSandboxHostCapacityFailure,
   isTerminalPromptEvent,
+  isWorkspaceSandboxRecoveryAction,
+  isWorkspaceSandboxRecoveryCode,
+  isWorkspaceSandboxRecoveryState,
+  isWorkspaceSandboxSnapshotRestoreError,
   mergeExtraMcp,
   mergeHistoryIntoParts,
   mintSandboxScopedToken,
   peekWorkspaceSandbox,
+  preferredWorkspaceSandboxRecoveryBoxKey,
   readSandboxBinaryBytes,
   readSecret,
   requireTransportableModel,
@@ -47,7 +70,9 @@ import {
   sandboxToolPath,
   sandboxToolRootDir,
   secretStoreFromClient,
+  serializeSandboxProvisioningError,
   shellQuote,
+  shouldRestoreWorkspaceSandboxRecovery,
   splitDeferredProfileFiles,
   statSandboxFileSize,
   storeSecret,
@@ -55,8 +80,12 @@ import {
   syncSandboxMemberAdd,
   syncSandboxMemberRemove,
   syncSandboxMemberRole,
+  workspaceSandboxRecoveryDiagnostic,
+  workspaceSandboxRecoveryFromError,
+  workspaceSandboxRecoveryMessage,
+  workspaceSandboxRecoveryRecommendedActions,
   writeProfileFilesToBox
-} from "../chunk-CS6MJDIM.js";
+} from "../chunk-4XNCMUVI.js";
 import "../chunk-LWSJK546.js";
 import "../chunk-73F3CKVK.js";
 import "../chunk-ITCINLSU.js";
@@ -68,6 +97,8 @@ export {
   DEFAULT_PREWARM_CLAIM_TABLE,
   DEFAULT_SANDBOX_RESOURCES,
   DEFAULT_SIDECAR_PROCESS_PATTERN,
+  EGRESS_PROXY_RECOVERY_PHASE,
+  EGRESS_PROXY_RECOVERY_REQUIRED,
   ENV_TOTAL_MAX_BYTES,
   ENV_VALUE_MAX_BYTES,
   PREWARM_CLAIM_TABLE_DDL,
@@ -76,8 +107,16 @@ export {
   SandboxModelResolutionError,
   SandboxRecoveryFailedError,
   SandboxRuntimeAuthRefreshError,
+  WORKSPACE_SANDBOX_HOST_EXHAUSTED,
+  WORKSPACE_SANDBOX_MISSING,
+  WORKSPACE_SANDBOX_RECOVERY_ACTIONS,
+  WORKSPACE_SANDBOX_RECOVERY_CODES,
+  WORKSPACE_SANDBOX_SNAPSHOT_MAX_AGE_MS,
+  WORKSPACE_SANDBOX_UNRECOVERABLE,
+  WorkspaceSandboxRecoveryRequiredError,
   assertEnvWithinLimits,
   assertProvisionPayloadWithinCap,
+  assessWorkspaceSandboxSnapshot,
   attachReasoningEffort,
   buildAppToolMcpServers,
   buildSandboxToolFileMounts,
@@ -88,18 +127,31 @@ export {
   createSandboxPrewarmer,
   createSandboxTerminalConnectionRoute,
   createWorkspaceSandboxManager,
+  createWorkspaceSandboxRecoveryManager,
   deferredCorpusHash,
   deleteSecret,
   detectInteractiveQuestion,
   driveSandboxTurn,
   ensureWorkspaceSandbox,
   flattenHistory,
+  formatSandboxProvisioningSupportDetails,
+  formatSandboxProvisioningUserMessage,
   getClient,
+  isEgressProxyRecoveryRequiredError,
+  isSandboxApiBearerAuthFailure,
+  isSandboxApiSandboxMissingFailure,
+  isSandboxAuthFailure,
+  isSandboxHostCapacityFailure,
   isTerminalPromptEvent,
+  isWorkspaceSandboxRecoveryAction,
+  isWorkspaceSandboxRecoveryCode,
+  isWorkspaceSandboxRecoveryState,
+  isWorkspaceSandboxSnapshotRestoreError,
   mergeExtraMcp,
   mergeHistoryIntoParts,
   mintSandboxScopedToken,
   peekWorkspaceSandbox,
+  preferredWorkspaceSandboxRecoveryBoxKey,
   readSandboxBinaryBytes,
   readSecret,
   requireTransportableModel,
@@ -113,7 +165,9 @@ export {
   sandboxToolPath,
   sandboxToolRootDir,
   secretStoreFromClient,
+  serializeSandboxProvisioningError,
   shellQuote,
+  shouldRestoreWorkspaceSandboxRecovery,
   splitDeferredProfileFiles,
   statSandboxFileSize,
   storeSecret,
@@ -121,6 +175,10 @@ export {
   syncSandboxMemberAdd,
   syncSandboxMemberRemove,
   syncSandboxMemberRole,
+  workspaceSandboxRecoveryDiagnostic,
+  workspaceSandboxRecoveryFromError,
+  workspaceSandboxRecoveryMessage,
+  workspaceSandboxRecoveryRecommendedActions,
   writeProfileFilesToBox
 };
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-app",
-  "version": "0.45.4",
+  "version": "0.45.6",
   "packageManager": "pnpm@11.17.0",
   "description": "Build agent applications with typed chat, tools, sandboxes, integrations, billing, and evaluation.",
   "keywords": [