@tangle-network/agent-app 0.44.23 → 0.44.25

package/dist/sandbox/index.d.ts

@@ -16,6 +16,186 @@ type Outcome<T> = {
     error: Error;
 };
 
+/** Define configuration options for resolving a provider and its model with optional API keys and routing details */
+interface ProviderResolutionConfig {
+    routerBaseUrl?: string;
+    apiKey?: string;
+    providerName?: string;
+    modelName?: string;
+    defaultModel?: string;
+    openaiApiKey?: string;
+    allowKeylessModel?: boolean;
+}
+/** Represent a fully configured model with optional API key and base URL for sandbox platform integration */
+interface ResolvedModel {
+    model: string;
+    provider: string;
+    apiKey?: string;
+    baseUrl?: string;
+}
+/**
+ * Why a model failed to resolve into something transportable to the sandbox
+ * platform. `no_provider` — a model id exists but no provider name could be
+ * derived (no explicit `providerName`, and no key present to infer one from).
+ * `no_api_key` — a provider AND model both resolved, but no credential is
+ * configured and the caller did not opt into `allowKeylessModel`.
+ */
+type ModelSelectionError = 'no_provider' | 'no_api_key';
+/**
+ * Which precedence slot supplied the failed/succeeded model id:
+ * `override` — the caller's per-turn `{ model }` argument.
+ * `config` — `provider.modelName`.
+ * `default` — `provider.defaultModel` (only ever consulted for an
+ * openai/openai-compat provider shape).
+ */
+type ModelSelectionSource = 'override' | 'config' | 'default';
+/**
+ * A model id was named (by override, config, or default) but is not
+ * transportable to the sandbox platform. Carries enough to explain WHY
+ * without the caller re-deriving the override/config/default precedence
+ * chain itself (that re-derivation is how gtm-agent#665 happened — a caller
+ * guessed loudness from the wrong slot and dropped a user-selected model).
+ */
+type ModelSelectionFailure = {
+    succeeded: false;
+    error: 'no_provider';
+    model: string;
+    source: ModelSelectionSource;
+} | {
+    succeeded: false;
+    error: 'no_api_key';
+    model: string;
+    provider: string;
+    source: ModelSelectionSource;
+};
+/**
+ * The three-state outcome of resolving a model: `{ succeeded: true, value:
+ * undefined }` means NOTHING was requested (the legitimate box-default
+ * configuration — not an error); `{ succeeded: true, value: ResolvedModel }`
+ * means a fully transportable model resolved; anything else is a
+ * {@link ModelSelectionFailure} — a model WAS named but can't be sent.
+ */
+type ModelSelection = {
+    succeeded: true;
+    value: ResolvedModel | undefined;
+} | ModelSelectionFailure;
+/**
+ * Resolve a provider + model configuration into a typed three-state outcome
+ * that separates "nothing requested" from "something requested but
+ * untransportable" — the distinction {@link resolveModel} collapses and the
+ * one that caused gtm-agent#665 (a validated user-selected model silently
+ * dropped, box default substituted, durable row still recording the user's
+ * choice).
+ *
+ * Precedence (identical to the legacy `resolveModel`, byte-for-byte):
+ * provider is computed first (`providerName`, else inferred `openai-compat`
+ * from a present key, else inferred `openai` from a present
+ * `openaiApiKey`, else unresolved); the model id is `override.model` else
+ * `config.modelName` else — ONLY when the provider is `openai` or
+ * `openai-compat` — `config.defaultModel`; the api key is
+ * `override.modelApiKey` else `config.apiKey` else — only for provider
+ * `openai` — `config.openaiApiKey`.
+ *
+ * Two behavioral deltas from the legacy function:
+ *  1. Every string field (`routerBaseUrl`, `apiKey`, `providerName`,
+ *     `modelName`, `defaultModel`, `openaiApiKey`, `override.model`,
+ *     `override.modelApiKey`) is normalized through {@link trimOrNull} first,
+ *     so `''` (and whitespace-only strings) are treated as absent instead of
+ *     poisoning the `??` precedence chain — the issue's second stated defect.
+ *     This also means a value is trimmed (`' gpt-5 '` resolves to `'gpt-5'`).
+ *  2. The outcome is three-state instead of collapsing to `undefined`: no
+ *     model derivable from any slot → `{ succeeded: true, value: undefined }`
+ *     (still the legitimate "let the box pick its own default" case, NOT an
+ *     error); a model id resolved but no provider could be derived → a
+ *     `no_provider` failure; a model + provider resolved but no api key (and
+ *     `allowKeylessModel` was not set) → a `no_api_key` failure. Both failure
+ *     arms carry `source` so a caller can apply a loudness policy without
+ *     re-deriving which precedence slot supplied the model.
+ */
+declare function resolveModelSelection(config: ProviderResolutionConfig | undefined, override?: {
+    model?: string;
+    modelApiKey?: string;
+}): ModelSelection;
+/**
+ * Resolve and return the appropriate model configuration based on provider
+ * settings and optional overrides.
+ *
+ * Migration note (intentionally NOT tagged `@deprecated`): this is a thin,
+ * source-compatible wrapper over {@link resolveModelSelection} that collapses
+ * its three-state outcome back down to `ResolvedModel | undefined`, exactly
+ * as before. It stays correct for the common case (no explicit model requested, or a
+ * fully-transportable one), but it CANNOT distinguish "nothing was
+ * requested" from "a named model could not be transported" — the ambiguity
+ * that caused gtm-agent#665. Prefer {@link resolveModelSelection} directly,
+ * or {@link requireTransportableModel} for the fail-loud-on-explicit-model
+ * policy the internal sandbox callers use. Not tagged `@deprecated`: it
+ * remains the correct call for a caller that never sets an explicit
+ * override and only wants "the box's default is fine" semantics; a hard
+ * deprecation is a later-major decision, not this fix's.
+ *
+ * The only behavior change on this entry point versus before is the
+ * empty-string bugfix that comes free through delegation (issue #302's
+ * second defect) — every signature and the `undefined` return semantics are
+ * unchanged.
+ */
+declare function resolveModel(config: ProviderResolutionConfig | undefined, override?: {
+    model?: string;
+    modelApiKey?: string;
+}): ResolvedModel | undefined;
+/**
+ * Thrown by {@link requireTransportableModel} when a model that was
+ * EXPLICITLY requested via a per-turn `{ model }` override cannot be
+ * transported to the sandbox platform. The message names the model, which
+ * precedence slot supplied it, what's missing, and the fix, and states
+ * plainly that the requested model was NOT sent to the box (the failure mode
+ * this error exists to make impossible to miss — gtm-agent#665 silently
+ * substituted the box default instead of a user-selected model).
+ *
+ * The error class itself carries no opinion about *when* it should be
+ * thrown — it is constructed from any {@link ModelSelectionFailure},
+ * regardless of `source`. A caller wanting a stricter policy (e.g. also
+ * fail-loud on an untransportable configured `provider.modelName`) can call
+ * {@link resolveModelSelection} directly and throw this itself.
+ */
+declare class SandboxModelResolutionError extends Error {
+    readonly code: ModelSelectionError;
+    readonly model: string;
+    readonly provider?: string;
+    readonly source: ModelSelectionSource;
+    constructor(failure: ModelSelectionFailure, context: string);
+}
+/**
+ * Shared fail-loud policy for the sandbox platform's three internal model
+ * callers (`ensureWorkspaceSandbox`'s `backendModelAtCreate`,
+ * `streamSandboxPrompt`, `driveSandboxTurn`): a `ModelSelection` in, a plain
+ * `ResolvedModel | undefined` out, so downstream code is unchanged from
+ * before this fix.
+ *
+ * The policy: success delegates straight through. A failure whose `source`
+ * is `'override'` means a PER-TURN model was explicitly selected THIS turn
+ * (a live, user-driven choice — passed as `{ model }`) and could not be
+ * sent; substituting the box default there is exactly the gtm-agent#665
+ * defect, so it throws {@link SandboxModelResolutionError} rather than
+ * silently falling back.
+ *
+ * A failure whose `source` is `'config'` or `'default'` means a
+ * *configured* `provider.modelName` / `provider.defaultModel` couldn't
+ * resolve — nobody made a choice this turn; the value came from board
+ * config that may simply describe "the platform supplies the credential."
+ * Shipped consumers rely on exactly that: tax-agent ships a shell with
+ * `provider: { providerName: 'openai-compat', modelName, routerBaseUrl }`
+ * and no `apiKey`/`allowKeylessModel`, with a contract test asserting
+ * `ensureWorkspaceSandbox` creation SUCCEEDS with the model silently
+ * dropped so the sandbox platform mints its own in-container credential
+ * (`apps/web/tests/sandbox-service-contract.test.ts`). A config-loud policy
+ * here would break every fresh tax sandbox provisioning and every tax turn.
+ * So both `'config'` and `'default'` keep the pre-#302 logged-skip
+ * behavior: `console.error` and drop, letting the box use its own default.
+ * A product wanting strict enforcement of a configured `provider.modelName`
+ * can call {@link resolveModelSelection} directly and apply its own policy.
+ */
+declare function requireTransportableModel(selection: ModelSelection, context: string): ResolvedModel | undefined;
+
 /**
  * Reading arbitrary bytes out of a sandbox over an exec channel that only
  * speaks text.
@@ -358,16 +538,6 @@ interface SandboxResourceConfig {
     maxLifetimeSeconds: number;
     idleTimeoutSeconds: number;
 }
-/** Define configuration options for resolving a provider and its model with optional API keys and routing details */
-interface ProviderResolutionConfig {
-    routerBaseUrl?: string;
-    apiKey?: string;
-    providerName?: string;
-    modelName?: string;
-    defaultModel?: string;
-    openaiApiKey?: string;
-    allowKeylessModel?: boolean;
-}
 /** Define the context for building a sandbox including workspace, integrations, and optional user ID */
 interface SandboxBuildContext {
     workspaceId: string;
@@ -521,6 +691,23 @@ type ExistingBoxStage = 'reused' | 'resumed';
 declare class SandboxRuntimeAuthRefreshError extends Error {
     constructor(stage: ExistingBoxStage, name: string, detail: string, cause?: unknown);
 }
+/** Which step of the state-preserving stop→resume recovery failed. `stop` with a
+ *  driver-unsupported cause means the platform cannot restart this box (the
+ *  `tangle` driver exposes create/delete only); `probe` means the box restarted
+ *  but is still unresponsive. */
+type SandboxRecoveryPhase = 'stop' | 'resume' | 'probe';
+/**
+ * Thrown when an unresponsive box could not be recovered by a state-preserving
+ * restart. Contract: this error is only ever thrown with the workspace intact —
+ * recovery never deletes. The caller decides what to do next (retry, surface to
+ * the user, or explicitly replace via `forceNew`).
+ */
+declare class SandboxRecoveryFailedError extends Error {
+    readonly boxKey: string;
+    readonly stage: ExistingBoxStage;
+    readonly phase: SandboxRecoveryPhase;
+    constructor(stage: ExistingBoxStage, boxKey: string, phase: SandboxRecoveryPhase, detail: string, cause?: unknown);
+}
 /** Define options to control execution timeout, pacing, and retry behavior when writing profile files */
 interface WriteProfileFilesOptions {
     execTimeoutMs?: number;
@@ -629,18 +816,6 @@ declare function peekWorkspaceSandbox(shell: SandboxRuntimeConfig, options: {
 }): Promise<PeekWorkspaceSandboxOutcome>;
 /** Resolve or create a workspace sandbox instance with optional reuse and progress tracking */
 declare function ensureWorkspaceSandbox(shell: SandboxRuntimeConfig, options: EnsureWorkspaceSandboxOptions): Promise<SandboxInstance>;
-/** Represent a fully configured model with optional API key and base URL for sandbox platform integration */
-interface ResolvedModel {
-    model: string;
-    provider: string;
-    apiKey?: string;
-    baseUrl?: string;
-}
-/** Resolve and return the appropriate model configuration based on provider settings and optional overrides */
-declare function resolveModel(config: ProviderResolutionConfig | undefined, override?: {
-    model?: string;
-    modelApiKey?: string;
-}): ResolvedModel | undefined;
 /** Extract a single element type from the array parameter of SandboxInstance's streamPrompt method */
 type PromptInputPart = Extract<Parameters<SandboxInstance['streamPrompt']>[0], readonly unknown[]>[number];
 /** Build a single string combining conversation history and the current user message */
@@ -801,4 +976,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 AuthenticatedSandboxUser, type BuildAppToolMcpServersOptions, type BuildSandboxToolFileMountsOptions, DEFAULT_SANDBOX_RESOURCES, type DriveSandboxTurnOptions, ENV_TOTAL_MAX_BYTES, ENV_VALUE_MAX_BYTES, type EnsureWorkspaceSandboxOptions, type LivenessProbeConfig, type MemberSyncSeam, type Outcome, PROVISION_PAYLOAD_MAX_BYTES, type PeekWorkspaceSandboxOutcome, type ProfileComposeOptions, type PromptInputPart, type ProviderResolutionConfig, type ProvisionPayloadSections, type ProvisionProfileSection, type ResolveSandboxClientCredentialsOptions, type ResolvedModel, type SandboxApiCredentials, type SandboxBuildContext, type SandboxClientCredentials, type SandboxCredentialEnvironment, type SandboxExecChannel, type SandboxExecOptions, type SandboxFileBytesOutcome, type SandboxFileSizeOutcome, type SandboxPermissionLevel, type SandboxResourceConfig, type SandboxRestoreSpec, SandboxRuntimeAuthRefreshError, type SandboxRuntimeConfig, type SandboxRuntimeConnection, type SandboxScope, type SandboxStepTransition, type SandboxTerminalTokenOptions, type SandboxTerminalTokenResult, type SandboxTerminalTokenSubject, type SandboxTerminalWsMatch, type SandboxToolPathOptions, type SandboxToolSpec, type ScopedTokenResult, type SecretStore, type StoppedSandboxResumeFailure, type StoppedSandboxResumeRecovery, type StreamSandboxPromptOptions, type TerminalProxyIdentity, type WorkspaceSandboxConnectionArgs, type WorkspaceSandboxConnectionHandlerOptions, type WorkspaceSandboxEnsureContext, type WorkspaceSandboxInstanceLike, type WorkspaceSandboxManager, type WorkspaceSandboxManagerOptions, type WorkspaceSandboxRuntimeProxyArgs, type WorkspaceSandboxRuntimeProxyHandlerOptions, type WorkspaceSandboxTerminalUpgradeHandlerOptions, type WriteProfileFilesOptions, assertEnvWithinLimits, assertProvisionPayloadWithinCap, attachReasoningEffort, bearerSubprotocolToken, bearerToken, buildAppToolMcpServers, buildSandboxRuntimeProxyHeaders, buildSandboxToolFileMounts, buildSandboxToolPathSetupScript, classifySeveredStream, collectSandboxPromptText, createSandboxTerminalToken, createWorkspaceSandboxConnectionHandler, createWorkspaceSandboxManager, createWorkspaceSandboxRuntimeProxyHandler, createWorkspaceSandboxTerminalUpgradeHandler, deferredCorpusHash, deleteSecret, detectInteractiveQuestion, driveSandboxTurn, encodeSandboxRuntimePath, ensureWorkspaceSandbox, flattenHistory, getClient, isSandboxTerminalWsUpgrade, isTerminalPromptEvent, matchSandboxTerminalWsPath, mergeExtraMcp, mergeHistoryIntoParts, mintSandboxScopedToken, mintTerminalProxyToken, peekWorkspaceSandbox, readSandboxBinaryBytes, readSecret, resetClientCache, resolveModel, resolveSandboxClientCredentials, runSandboxPrompt, runSandboxToolPathSetup, sandboxToolBinDir, sandboxToolPath, sandboxToolRootDir, secretStoreFromClient, shellQuote, splitDeferredProfileFiles, statSandboxFileSize, storeSecret, streamSandboxPrompt, syncSandboxMemberAdd, syncSandboxMemberRemove, syncSandboxMemberRole, terminalTokenFromRequest, verifySandboxTerminalToken, verifyTerminalProxyToken, writeProfileFilesToBox };
+export { type AppToolDescriptor, type AuthenticatedSandboxUser, type BuildAppToolMcpServersOptions, type BuildSandboxToolFileMountsOptions, DEFAULT_SANDBOX_RESOURCES, 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, PROVISION_PAYLOAD_MAX_BYTES, type PeekWorkspaceSandboxOutcome, type ProfileComposeOptions, type PromptInputPart, type ProviderResolutionConfig, type ProvisionPayloadSections, type ProvisionProfileSection, type ResolveSandboxClientCredentialsOptions, type ResolvedModel, type SandboxApiCredentials, type SandboxBuildContext, type SandboxClientCredentials, type SandboxCredentialEnvironment, type SandboxExecChannel, type SandboxExecOptions, type SandboxFileBytesOutcome, type SandboxFileSizeOutcome, SandboxModelResolutionError, type SandboxPermissionLevel, SandboxRecoveryFailedError, type SandboxRecoveryPhase, type SandboxResourceConfig, type SandboxRestoreSpec, SandboxRuntimeAuthRefreshError, type SandboxRuntimeConfig, type SandboxRuntimeConnection, type SandboxScope, type SandboxStepTransition, type SandboxTerminalTokenOptions, type SandboxTerminalTokenResult, type SandboxTerminalTokenSubject, type SandboxTerminalWsMatch, type SandboxToolPathOptions, type SandboxToolSpec, type ScopedTokenResult, type SecretStore, type StoppedSandboxResumeFailure, type StoppedSandboxResumeRecovery, type StreamSandboxPromptOptions, type TerminalProxyIdentity, type WorkspaceSandboxConnectionArgs, type WorkspaceSandboxConnectionHandlerOptions, type WorkspaceSandboxEnsureContext, type WorkspaceSandboxInstanceLike, type WorkspaceSandboxManager, type WorkspaceSandboxManagerOptions, type WorkspaceSandboxRuntimeProxyArgs, type WorkspaceSandboxRuntimeProxyHandlerOptions, type WorkspaceSandboxTerminalUpgradeHandlerOptions, type WriteProfileFilesOptions, assertEnvWithinLimits, assertProvisionPayloadWithinCap, attachReasoningEffort, bearerSubprotocolToken, bearerToken, buildAppToolMcpServers, buildSandboxRuntimeProxyHeaders, buildSandboxToolFileMounts, buildSandboxToolPathSetupScript, classifySeveredStream, collectSandboxPromptText, createSandboxTerminalToken, createWorkspaceSandboxConnectionHandler, createWorkspaceSandboxManager, createWorkspaceSandboxRuntimeProxyHandler, createWorkspaceSandboxTerminalUpgradeHandler, deferredCorpusHash, deleteSecret, detectInteractiveQuestion, driveSandboxTurn, encodeSandboxRuntimePath, ensureWorkspaceSandbox, flattenHistory, getClient, isSandboxTerminalWsUpgrade, isTerminalPromptEvent, matchSandboxTerminalWsPath, mergeExtraMcp, mergeHistoryIntoParts, mintSandboxScopedToken, mintTerminalProxyToken, peekWorkspaceSandbox, readSandboxBinaryBytes, readSecret, requireTransportableModel, resetClientCache, resolveModel, resolveModelSelection, resolveSandboxClientCredentials, runSandboxPrompt, runSandboxToolPathSetup, sandboxToolBinDir, sandboxToolPath, sandboxToolRootDir, secretStoreFromClient, shellQuote, splitDeferredProfileFiles, statSandboxFileSize, storeSecret, streamSandboxPrompt, syncSandboxMemberAdd, syncSandboxMemberRemove, syncSandboxMemberRole, terminalTokenFromRequest, verifySandboxTerminalToken, verifyTerminalProxyToken, writeProfileFilesToBox };

package/dist/sandbox/index.js

@@ -3,6 +3,8 @@ import {
   ENV_TOTAL_MAX_BYTES,
   ENV_VALUE_MAX_BYTES,
   PROVISION_PAYLOAD_MAX_BYTES,
+  SandboxModelResolutionError,
+  SandboxRecoveryFailedError,
   SandboxRuntimeAuthRefreshError,
   assertEnvWithinLimits,
   assertProvisionPayloadWithinCap,
@@ -38,8 +40,10 @@ import {
   peekWorkspaceSandbox,
   readSandboxBinaryBytes,
   readSecret,
+  requireTransportableModel,
   resetClientCache,
   resolveModel,
+  resolveModelSelection,
   resolveSandboxClientCredentials,
   runSandboxPrompt,
   runSandboxToolPathSetup,
@@ -59,7 +63,7 @@ import {
   verifySandboxTerminalToken,
   verifyTerminalProxyToken,
   writeProfileFilesToBox
-} from "../chunk-2ZSSOYXP.js";
+} from "../chunk-Q74BS43G.js";
 import "../chunk-LWSJK546.js";
 import "../chunk-CQZSAR77.js";
 import "../chunk-ICOHEZK6.js";
@@ -72,6 +76,8 @@ export {
   ENV_TOTAL_MAX_BYTES,
   ENV_VALUE_MAX_BYTES,
   PROVISION_PAYLOAD_MAX_BYTES,
+  SandboxModelResolutionError,
+  SandboxRecoveryFailedError,
   SandboxRuntimeAuthRefreshError,
   assertEnvWithinLimits,
   assertProvisionPayloadWithinCap,
@@ -107,8 +113,10 @@ export {
   peekWorkspaceSandbox,
   readSandboxBinaryBytes,
   readSecret,
+  requireTransportableModel,
   resetClientCache,
   resolveModel,
+  resolveModelSelection,
   resolveSandboxClientCredentials,
   runSandboxPrompt,
   runSandboxToolPathSetup,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-app",
-  "version": "0.44.23",
+  "version": "0.44.25",
   "packageManager": "pnpm@10.33.4",
   "description": "Application-shell framework for Tangle agent products: a bounded tool loop, the structured agent→app tool side channel, integration-hub client, per-workspace billing, and crypto — composed over the Tangle agent substrate through typed seams.",
   "keywords": [