@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/sandbox/model.d.ts

@@ -0,0 +1,179 @@
+/** Define configuration options for resolving a provider and its model with optional API keys and routing details */
+export 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 */
+export 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`.
+ */
+export 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).
+ */
+export 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).
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function requireTransportableModel(selection: ModelSelection, context: string): ResolvedModel | undefined;

package/dist/sandbox/outcome.d.ts

@@ -0,0 +1,10 @@
+/** Represent success or failure of an operation with corresponding value or error information */
+export type Outcome<T> = {
+    succeeded: true;
+    value: T;
+} | {
+    succeeded: false;
+    error: Error;
+};
+export declare const ok: <T>(value: T) => Outcome<T>;
+export declare const fail: (error: unknown) => Outcome<never>;

package/dist/sandbox/prewarm-claim-d1.d.ts

@@ -0,0 +1,80 @@
+/**
+ * `createD1PrewarmClaimStore` — the cross-isolate half of
+ * `createSandboxPrewarmer`'s single-flight, implemented once.
+ *
+ * WHY THIS SHIPS HERE. `SandboxPrewarmerOptions.claim` is REQUIRED and has no
+ * default, which is correct — the unsafe behaviour must be said out loud. But
+ * "required with no implementation" is how five products end up hand-rolling
+ * five subtly different atomic leases, and a lease that is subtly wrong is
+ * indistinguishable from one that works until two tabs leak a box. Every
+ * agent-app product deploys to Cloudflare Workers with a D1 binding, so the
+ * store is the same code in all of them: it is mechanism, not domain, and it
+ * belongs beside the prewarmer.
+ *
+ * The measured stake (staging-sandbox, 2026-07-28): two concurrent
+ * `POST /v1/sandboxes` with an identical name BOTH returned HTTP 201 and left
+ * two running boxes. The platform does not dedupe by name, so nothing below
+ * this line is defensive programming — an unclaimed race genuinely doubles
+ * spend.
+ *
+ * ── ATOMICITY IS THE WHOLE POINT ───────────────────────────────────────────
+ * `acquire` is ONE statement. A `SELECT` followed by an `INSERT` is exactly the
+ * race this exists to close: both isolates read "free", both write, both warm.
+ * The upsert's `DO UPDATE ... WHERE expires_at <= now` means an unexpired claim
+ * makes the conflict path a no-op, and `RETURNING` then yields no row — so the
+ * loser learns it lost from the same statement that would have made it the
+ * winner. `RETURNING` is used rather than `meta.changes` because a no-op upsert
+ * reporting `changes: 0` is a SQLite detail, whereas "no row came back" is the
+ * statement telling you directly.
+ *
+ * ── STRUCTURAL, NOT A DEPENDENCY ───────────────────────────────────────────
+ * The binding is taken as the narrow shape actually used (`prepare().bind()`,
+ * `.first()`, `.run()`), per the package's structural-over-hard-dep rule. No
+ * `@cloudflare/workers-types` import, so `/sandbox` stays importable in a plain
+ * node test. A real `D1Database` satisfies it.
+ *
+ * ── THE TABLE IS THE PRODUCT'S MIGRATION, NOT A LAZY CREATE ────────────────
+ * The store never runs DDL. A `CREATE TABLE IF NOT EXISTS` on every project
+ * open costs a round trip on the exact path this feature exists to keep fast,
+ * and it hides schema drift instead of failing on it. `PREWARM_CLAIM_TABLE_DDL`
+ * is exported so a product pastes it into a real migration. If the table is
+ * missing, `acquire` throws — and the prewarmer treats a throwing claim as a
+ * failed warm: it records the failure, emits `onEvent({type:'failed'})`, and
+ * degrades to the lazy path. Fail-closed and loud, never a silent double-warm.
+ */
+/** The columns and statements this store uses, and nothing else. A real
+ *  `D1Database` structurally satisfies it. */
+export interface PrewarmClaimD1Like {
+    prepare(query: string): {
+        bind(...values: unknown[]): {
+            first<T = Record<string, unknown>>(): Promise<T | null>;
+            run(): Promise<unknown>;
+        };
+    };
+}
+export interface D1PrewarmClaimStoreOptions {
+    /** Defaults to `sandbox_prewarm_claims`. Must be a bare SQL identifier — it
+     *  is interpolated, because a table name cannot be a bound parameter. */
+    table?: string;
+    /** Clock seam for tests. */
+    now?(): number;
+}
+export declare const DEFAULT_PREWARM_CLAIM_TABLE = "sandbox_prewarm_claims";
+/** Paste into a migration. `expires_at` is epoch MILLISECONDS, matching
+ *  `Date.now()`, so no unit conversion sits between the lease and its clock. */
+export declare const PREWARM_CLAIM_TABLE_DDL = "CREATE TABLE IF NOT EXISTS sandbox_prewarm_claims (\n  key TEXT PRIMARY KEY,\n  expires_at INTEGER NOT NULL\n)";
+/**
+ * A `PrewarmClaimStore` backed by one D1 table.
+ *
+ * ```ts
+ * const prewarmer = createSandboxPrewarmer(shell, {
+ *   claim: createD1PrewarmClaimStore(env.DB),
+ *   mode: 'create-or-resume',
+ * })
+ * ```
+ */
+export declare function createD1PrewarmClaimStore(db: PrewarmClaimD1Like, options?: D1PrewarmClaimStoreOptions): {
+    acquire(key: string, ttlSeconds: number): Promise<boolean>;
+    release(key: string): Promise<void>;
+    isHeld(key: string): Promise<boolean>;
+};

package/dist/sandbox/prewarm.d.ts

@@ -0,0 +1,193 @@
+/**
+ * `createSandboxPrewarmer` — "this user just opened this project; start warming
+ * their box" as a shell primitive, so every agent-app product gets the same
+ * answer instead of forking one.
+ *
+ * WHY THIS IS SHELL, NOT ENGINE. The engine rule asks whether the capability
+ * makes sense without a specific app's side channel. "Warm a box" does — but
+ * `@tangle-network/sandbox` has no notion of a WORKSPACE. It keys boxes by an
+ * opaque sandbox id; the workspace→box mapping, the harness match, and the
+ * profile materialisation all live in `ensureWorkspaceSandbox` here. A
+ * prewarmer is that mapping plus a scheduling policy, so it belongs beside it.
+ * It is deliberately NOT a new subpath: it composes `peekWorkspaceSandbox` and
+ * `ensureWorkspaceSandbox` directly and needs exactly the peers `/sandbox`
+ * already needs, so a separate entry would add a second place to look for "how
+ * do I get a box" and buy no peer isolation (the reason `/work-product-react`
+ * is split out).
+ *
+ * WHAT IT IS NOT. It does not make cold starts fast — they already are.
+ * Measured on the real platform (staging-sandbox, n=5, 2026-07-28): a box goes
+ * from nothing to terminal-ready in 2.34–3.19 s (median 2.73 s), and an
+ * already-running box answers in 1.16–2.29 s (median 1.35 s). Prewarming buys
+ * ~1.4 s. The reason it matters is not latency: it is that a product which
+ * only ever provisions lazily, on a path whose guard never passes, never
+ * provisions AT ALL — and the UI then shows a spinner over a box that does not
+ * exist and is not being created. That is the failure this primitive removes.
+ *
+ * ── COST POSTURE (read before adopting) ────────────────────────────────────
+ * A warmed box is a REAL charge. It bills from creation until the platform's
+ * idle timeout reclaims it — `SandboxRuntimeConfig`'s create-time
+ * `idleTimeoutSeconds`, not anything this module sets. A product warming on
+ * every project open pays that timeout for every user who opens and bounces.
+ * With a 3600 s idle timeout against a ~131 s mean session life, a bounce
+ * costs an hour of box time to save ~1.4 s. THAT TRADE IS USUALLY WRONG.
+ *
+ * So the levers are explicit and the defaults are the cheap ones:
+ *   - `mode: 'resume-only'` (DEFAULT) never creates a box that does not exist.
+ *     It only revives one the user already has, so the spend is bounded by
+ *     boxes the user already caused. This is the safe fleet default.
+ *   - `mode: 'create-or-resume'` is the owner-requested behaviour — warm on
+ *     open even for a first-time user. Opt in per product, and lower the
+ *     shell's `idleTimeoutSeconds` when you do.
+ *   - `shouldPrewarm(scope)` is the product's own policy hook (paid tier only,
+ *     returning user only, has-documents only …). Returning false costs nothing.
+ *   - `failureCooldownMs` stops a hard-failing workspace from retry-storming;
+ *     every retry is another create attempt, which is more spend.
+ * Warm with the SAME harness the next turn will use. `ensureWorkspaceSandbox`
+ * DELETES and recreates a name-matched box whose harness differs, so warming
+ * `opencode` and then turning `claude-code` pays for two boxes and is slower
+ * than not warming at all. The prewarm key includes the harness so the two are
+ * never deduped into one.
+ *
+ * ── SINGLE-FLIGHT (measured, not assumed) ──────────────────────────────────
+ * The sandbox platform does NOT dedupe by box name. Two concurrent
+ * `POST /v1/sandboxes` with an identical name both returned HTTP 201 and left
+ * two running boxes (verified against staging-sandbox, 2026-07-28). So two
+ * tabs, or two isolates, racing a warm genuinely leak a box — a prewarm that
+ * races is worse than no prewarm. Hence two layers:
+ *   1. an in-process map, which is free and catches same-isolate races
+ *      (double-mount, two requests on one isolate);
+ *   2. a `claim` store the product supplies, which is the only thing that can
+ *      make this correct ACROSS isolates — the usual deployment target here is
+ *      Cloudflare Workers, where "same isolate" guarantees nothing.
+ * `claim` is REQUIRED, with `'single-isolate-only'` as the explicit opt-out,
+ * so nobody gets the unsafe behaviour by forgetting a field. Say it out loud
+ * or supply a store.
+ *
+ * ── FAILURE IS LOUD, NEVER FATAL ───────────────────────────────────────────
+ * A failed warm degrades to exactly today's lazy path: the next real request
+ * calls `ensureWorkspaceSandbox` itself. It never throws into the caller's
+ * render path — `completion` RESOLVES with `{ ok: false }` rather than
+ * rejecting, because an unhandled rejection handed to `waitUntil` can fail the
+ * request it rode in on. But it is never silent: every failure fires
+ * `onEvent({ type: 'failed' })` and is readable afterwards through
+ * `readiness()` as `{ status: 'failed' }`. The bug class this whole module
+ * exists to kill is a soft failure that surfaces as an unusable panel ten
+ * minutes later, so a warm that dies must leave a trace a product can render.
+ */
+import type { Harness } from '../harness/index';
+import { type SandboxRuntimeConfig } from './index';
+/** The workspace a warm targets. Mirrors `EnsureWorkspaceSandboxOptions`'
+ *  identity fields — the prewarmer forwards them verbatim so a warmed box is
+ *  byte-identical to the one the lazy path would have built. */
+export interface SandboxPrewarmScope {
+    workspaceId: string;
+    userId?: string;
+    /** Must match the harness the next turn will use — see the cost note above. */
+    harness: Harness;
+    billingOwnerId?: string;
+}
+/**
+ * Cross-isolate claim. `acquire` must be atomic (a D1 conditional insert, a DO,
+ * a KV `put` with `onlyIf`) — a read-then-write is exactly the race this exists
+ * to close. `ttlSeconds` bounds a claim leaked by an isolate that died
+ * mid-warm; without expiry a single crash wedges a workspace forever.
+ */
+export interface PrewarmClaimStore {
+    /** True when THIS caller now owns the right to warm `key`. */
+    acquire(key: string, ttlSeconds: number): Promise<boolean>;
+    /** Best-effort release. A throw here is swallowed — the TTL is the backstop. */
+    release(key: string): Promise<void>;
+    /** Optional: lets `readiness()` report `warming` for a warm running in
+     *  ANOTHER isolate. Without it, `warming` is only visible in the isolate
+     *  that started it, and every other one reports `absent`. */
+    isHeld?(key: string): Promise<boolean>;
+}
+/** What `prewarm()` decided. Every value except `started` means no box was
+ *  created and nothing was spent on this call. */
+export type PrewarmOutcome = 'started' | 'already-running' | 'already-warming' | 'warming-elsewhere' | 'declined-by-policy' | 'cooling-down' | 'absent-and-resume-only';
+/** Terminal result of a warm this caller owns. Never a rejection. */
+export interface PrewarmResult {
+    ok: boolean;
+    boxId?: string;
+    error?: string;
+    /** Wall time of the warm itself, for the product's own timing trace. */
+    ms: number;
+}
+export interface PrewarmDecision {
+    outcome: PrewarmOutcome;
+    /** Present ONLY when `outcome === 'started'`. Hand it to `ctx.waitUntil` so a
+     *  client disconnect cannot kill the warm. Never rejects. */
+    completion?: Promise<PrewarmResult>;
+}
+/** Readiness for the UI. `ready`/`warming` reuse the vocabulary
+ *  `createSandboxFileIndexRoute` (`/chat-routes`) and `useFileMentions`
+ *  (`/web-react`) already speak, so a product renders ONE warming state rather
+ *  than inventing a second spinner for boxes. */
+export type SandboxReadiness = {
+    status: 'ready';
+    boxId: string;
+} | {
+    status: 'warming';
+} | {
+    status: 'absent';
+} | {
+    status: 'failed';
+    error: string;
+    retryAfterMs: number;
+};
+export type PrewarmEvent = {
+    type: 'started';
+    key: string;
+    workspaceId: string;
+} | {
+    type: 'succeeded';
+    key: string;
+    workspaceId: string;
+    boxId: string;
+    ms: number;
+} | {
+    type: 'failed';
+    key: string;
+    workspaceId: string;
+    error: string;
+    ms: number;
+} | {
+    type: 'skipped';
+    key: string;
+    workspaceId: string;
+    outcome: PrewarmOutcome;
+};
+export interface SandboxPrewarmerOptions {
+    /** Cross-isolate single-flight, or the explicit acknowledgement that you are
+     *  accepting per-isolate dedupe only. No default — see the header. */
+    claim: PrewarmClaimStore | 'single-isolate-only';
+    /** `'resume-only'` (default) never creates a box that does not exist.
+     *  `'create-or-resume'` warms from nothing — the expensive one. */
+    mode?: 'resume-only' | 'create-or-resume';
+    /** Product policy gate. Not called when a box is already running. */
+    shouldPrewarm?(scope: SandboxPrewarmScope): boolean | Promise<boolean>;
+    /** Observability seam. A failed warm MUST be visible somewhere. */
+    onEvent?(event: PrewarmEvent): void;
+    /** Claim lifetime. Default 180 s — comfortably over a cold create. */
+    claimTtlSeconds?: number;
+    /** Suppress re-warming a workspace that just failed. Default 60_000 ms. */
+    failureCooldownMs?: number;
+    /** Clock seam for tests. */
+    now?(): number;
+}
+export interface SandboxPrewarmer {
+    /**
+     * Non-blocking warm. The returned promise settles as soon as the DECISION is
+     * known (at most one `list()` against the platform, plus a claim `acquire`);
+     * the provisioning itself rides on `completion`. On a render path either
+     * ignore the returned promise or run the whole call inside `waitUntil` — do
+     * not await `completion` before responding.
+     */
+    prewarm(scope: SandboxPrewarmScope): Promise<PrewarmDecision>;
+    /** Zero-provisioning status read for a UI. Never creates or resumes. */
+    readiness(scope: SandboxPrewarmScope): Promise<SandboxReadiness>;
+    /** Clear a recorded failure so the next `prewarm` retries immediately. */
+    clearFailure(scope: SandboxPrewarmScope): void;
+}
+export declare function createSandboxPrewarmer(shell: SandboxRuntimeConfig, options: SandboxPrewarmerOptions): SandboxPrewarmer;