@tangle-network/agent-app 0.45.4 → 0.45.5

package/dist/sandbox/index.d.ts

@@ -261,6 +261,81 @@ 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>;
 
+/**
+ * Read a sandbox provisioning failure without leaking what it carries.
+ *
+ * Provisioning errors arrive as deep `cause` chains from the sandbox API, the
+ * runtime sidecar, and the app's own vault code, and they routinely carry
+ * bearer tokens and signed URLs in their messages. Every app on this shell
+ * needs the same three things from one: a redacted shape it can log, a
+ * classification it can act on, and a sentence it can show a person. Before
+ * this module each app either wrote its own or — far more often — wrote none,
+ * and surfaced the raw error or a generic apology.
+ *
+ * The classifiers are deliberately narrow. `isSandboxApiSandboxMissingFailure`
+ * does not fire on a 404 from inside a live box; `isSandboxHostCapacityFailure`
+ * does not fire on capacity wording from any origin but the sandbox API. A
+ * classifier that over-matches turns a transient failure into a box deletion.
+ */
+/** Error code an app raises when a stopped box's egress proxy must be rebuilt
+ *  before the box can be reused. Declared here so the classifier below stands
+ *  alone; apps that model this failure re-export the same literal. */
+declare const EGRESS_PROXY_RECOVERY_REQUIRED = "EGRESS_PROXY_RECOVERY_REQUIRED";
+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 +1073,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 +1363,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_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, 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, formatSandboxProvisioningSupportDetails, formatSandboxProvisioningUserMessage, getClient, isSandboxApiBearerAuthFailure, isSandboxApiSandboxMissingFailure, isSandboxAuthFailure, isSandboxHostCapacityFailure, isTerminalPromptEvent, mergeExtraMcp, mergeHistoryIntoParts, mintSandboxScopedToken, peekWorkspaceSandbox, readSandboxBinaryBytes, readSecret, requireTransportableModel, resetClientCache, resolveModel, resolveModelSelection, resolveSandboxClientCredentials, runSandboxPrompt, runSandboxToolPathSetup, sandboxToolBinDir, sandboxToolPath, sandboxToolRootDir, secretStoreFromClient, serializeSandboxProvisioningError, shellQuote, splitDeferredProfileFiles, statSandboxFileSize, storeSecret, streamSandboxPrompt, syncSandboxMemberAdd, syncSandboxMemberRemove, syncSandboxMemberRole, writeProfileFilesToBox };

package/dist/sandbox/index.js

@@ -2,6 +2,7 @@ import {
   DEFAULT_PREWARM_CLAIM_TABLE,
   DEFAULT_SANDBOX_RESOURCES,
   DEFAULT_SIDECAR_PROCESS_PATTERN,
+  EGRESS_PROXY_RECOVERY_REQUIRED,
   ENV_TOTAL_MAX_BYTES,
   ENV_VALUE_MAX_BYTES,
   PREWARM_CLAIM_TABLE_DDL,
@@ -28,7 +29,13 @@ import {
   driveSandboxTurn,
   ensureWorkspaceSandbox,
   flattenHistory,
+  formatSandboxProvisioningSupportDetails,
+  formatSandboxProvisioningUserMessage,
   getClient,
+  isSandboxApiBearerAuthFailure,
+  isSandboxApiSandboxMissingFailure,
+  isSandboxAuthFailure,
+  isSandboxHostCapacityFailure,
   isTerminalPromptEvent,
   mergeExtraMcp,
   mergeHistoryIntoParts,
@@ -47,6 +54,7 @@ import {
   sandboxToolPath,
   sandboxToolRootDir,
   secretStoreFromClient,
+  serializeSandboxProvisioningError,
   shellQuote,
   splitDeferredProfileFiles,
   statSandboxFileSize,
@@ -56,7 +64,7 @@ import {
   syncSandboxMemberRemove,
   syncSandboxMemberRole,
   writeProfileFilesToBox
-} from "../chunk-CS6MJDIM.js";
+} from "../chunk-QGHQ2IRC.js";
 import "../chunk-LWSJK546.js";
 import "../chunk-73F3CKVK.js";
 import "../chunk-ITCINLSU.js";
@@ -68,6 +76,7 @@ export {
   DEFAULT_PREWARM_CLAIM_TABLE,
   DEFAULT_SANDBOX_RESOURCES,
   DEFAULT_SIDECAR_PROCESS_PATTERN,
+  EGRESS_PROXY_RECOVERY_REQUIRED,
   ENV_TOTAL_MAX_BYTES,
   ENV_VALUE_MAX_BYTES,
   PREWARM_CLAIM_TABLE_DDL,
@@ -94,7 +103,13 @@ export {
   driveSandboxTurn,
   ensureWorkspaceSandbox,
   flattenHistory,
+  formatSandboxProvisioningSupportDetails,
+  formatSandboxProvisioningUserMessage,
   getClient,
+  isSandboxApiBearerAuthFailure,
+  isSandboxApiSandboxMissingFailure,
+  isSandboxAuthFailure,
+  isSandboxHostCapacityFailure,
   isTerminalPromptEvent,
   mergeExtraMcp,
   mergeHistoryIntoParts,
@@ -113,6 +128,7 @@ export {
   sandboxToolPath,
   sandboxToolRootDir,
   secretStoreFromClient,
+  serializeSandboxProvisioningError,
   shellQuote,
   splitDeferredProfileFiles,
   statSandboxFileSize,

package/package.json

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