agent-accelerator 0.5.9 → 0.6.5

package/src/tools/tool-content.ts

@@ -0,0 +1,32 @@
+/**
+ * A tool result made of text and media. A tool returns `toolContent([...])` when the model should SEE a file (a chart
+ * image, a scanned page, a recording) and not only read text about it. The brand is a private Symbol, so only the
+ * tool's own code can produce it: JSON a tool fetched from the web can never become media for the provider.
+ */
+import type { ContentPart } from "../types/message.ts";
+
+/** Parts a tool may return: plain strings (text) and the usual text, image, audio, video and file parts. */
+export type ToolContentPart = string | Extract<ContentPart, { type: "text" | "image" | "audio" | "video" | "file" }>;
+
+const TOOL_CONTENT_BRAND: unique symbol = Symbol("agent-accelerator.tool-content") as never;
+
+/** What `toolContent` returns; the executor turns it into a tool result with `parts`. */
+export interface ToolContent {
+  readonly parts: ToolContentPart[];
+  readonly [TOOL_CONTENT_BRAND]: true;
+}
+
+/**
+ * Wraps text and media for a tool's return value, e.g.
+ * `return toolContent(["instrument.jpg", { type: "image", image: bytes, mimeType: "image/jpeg" }])`.
+ * Media may be bytes, a data URL, a path or a URL (the tool's own code is trusted with these). Google passes the media
+ * to the model inside the function result; other providers get the text only, with one warning.
+ */
+export function toolContent(parts: ToolContentPart[]): ToolContent {
+  return { parts: [...parts], [TOOL_CONTENT_BRAND]: true };
+}
+
+/** True only for values made by {@link toolContent}. */
+export function isToolContent(value: unknown): value is ToolContent {
+  return !!value && typeof value === "object" && (value as Record<symbol, unknown>)[TOOL_CONTENT_BRAND] === true;
+}

package/src/tools/tool.ts

@@ -1,9 +1,5 @@
 import { z } from "zod";
-import type {
-  ToolDefinition,
-  StandardToolDeclaration,
-  ToolExecuteFn,
-} from "../types/tool.ts";
+import type { ToolDefinition, StandardToolDeclaration, ToolExecuteFn } from "../types/tool.ts";
 import type { ThinkingLevel } from "../types/core.ts";
 import type { ThinkingOption } from "../types/agent.ts";
 import { zodToJsonSchema } from "./schema.ts";
@@ -54,9 +50,10 @@ export function normalizeThinkingV2(
  *
  * @example `resolveWhenBusy({ whenBusy: "queue", mode: "steer" }); // "queue"`
  */
-export function resolveWhenBusy(
-  config?: { mode?: "steer" | "queue" | "auto"; whenBusy?: "steer" | "queue" | "auto" }
-): "steer" | "queue" | "auto" {
+export function resolveWhenBusy(config?: {
+  mode?: "steer" | "queue" | "auto";
+  whenBusy?: "steer" | "queue" | "auto";
+}): "steer" | "queue" | "auto" {
   const v = config?.whenBusy ?? config?.mode ?? "auto";
   return v === "steer" || v === "queue" ? v : "auto";
 }
@@ -67,9 +64,10 @@ export function resolveWhenBusy(
  *
  * @example `normalizeMaxAttempts({ maxAttempts: 3 }); // 3`
  */
-export function normalizeMaxAttempts(
-  config?: { maxTries?: number | string; maxAttempts?: number | string }
-): number | string | undefined {
+export function normalizeMaxAttempts(config?: {
+  maxTries?: number | string;
+  maxAttempts?: number | string;
+}): number | string | undefined {
   return config?.maxTries ?? config?.maxAttempts;
 }
 

package/src/types/agent.ts

@@ -1,13 +1,10 @@
 import type { ModelSpec } from "./model.ts";
 import type { ToolDefinition } from "./tool.ts";
-import type {
-  ThinkingLevel,
-  CacheOption,
-  ServiceTier,
-} from "./core.ts";
+import type { ThinkingLevel, CacheOption, ServiceTier } from "./core.ts";
 import type { ModelProviderInstance } from "../providers/registry.ts";
 import type { Agent } from "../agent/agent.ts";
 import type { z } from "zod";
+import type { PromptOverrides } from "../prompts/prompts.ts";
 
 // ---------------------------------------------------------------------------
 // Canonical option types (all additive; nothing renamed).
@@ -51,10 +48,8 @@ export type ToolChoiceOption =
   | "auto"
   | "none"
   | "required"
-  | { mode?: "auto" | "none" | "required"; tool?: string };
-
-/** Canonical stop control: sequence(s) halting generation. */
-export type StopOption = string | string[];
+  | "validated"
+  | { mode?: "auto" | "none" | "required" | "validated"; tool?: string };
 
 /** Canonical structured-output input. Zod, JSON Schema, or explicit form. */
 export type StructuredOutputOption =
@@ -160,17 +155,16 @@ export interface AgentConfig {
    * Canonical tool-selection control (`"auto"` default). `"none"` applies to
    * every turn of a run; `"required"` and a pinned tool (`{ tool: "name" }`)
    * apply to the FIRST model turn only, since forcing a tool call on every
-   * turn would make a run unable to finish.
+   * turn would make a run unable to finish. `"validated"` (Google only) lets the
+   * model decide whether to call a tool but makes it keep every call valid against
+   * the tool's schema; it holds for the whole run. Other providers ignore it
+   * with one warning.
    */
   toolChoice?: ToolChoiceOption;
   /** Google Interactions storage tier for the chain-TTL gate: `"free"` (23h, default) or `"paid"` (54d). */
   googleTier?: "free" | "paid";
   /** Maximum output tokens for one model call. */
   maxOutputTokens?: number;
-  /** Stop sequence(s). */
-  stop?: StopOption;
-  /** Deterministic seed, when the provider supports it. */
-  seed?: number;
   /**
    * Optional output schema (Zod, JSON Schema, or `{ name, schema, strict }`,
    * see `StructuredOutputOption`, stored as `unknown` so `zod`
@@ -230,12 +224,29 @@ export interface AgentConfig {
   budget?: Budget;
   /** Run + network limits. Turn/budget caps unlimited by default; network timeouts finite. */
   limits?: AgentRunLimits;
+  /**
+   * A spending cap for the WHOLE chat, for its whole life: what the agent, all its workers (the `subagents` tool,
+   * `agent.workers` at any depth, fixed `subagents`) and their model calls cost, added up. It survives restarts: a
+   * persisted agent starts from what its saved sessions already spent. Once the total reaches `maxCostUsd` or
+   * `maxTotalTokens`, the next model call anywhere in the chat throws a `BudgetExceededError` ("Usage limit reached").
+   * Unlike `budget` (per run) it never resets. Scheduled actions are separate and never count. Models with unknown
+   * pricing add tokens but $0 to the cost. Unset = no cap.
+   */
+  usageLimit?: Pick<Budget, "maxCostUsd" | "maxTotalTokens">;
   /**
    * The only models this agent may use, as `provider/model` strings compared as written. Unset (default) = any model.
    * Checked when the Agent is built (also for a config an agent edited through {@link Agent.fromConfig}); a model
    * outside the list throws a `ConfigError`. Workers and `subagentModel` are not affected.
    */
   allowedModels?: string[];
+  /**
+   * Replaces single prompts the SDK puts in front of the model (the reasoning directive, tool refusals, the worker
+   * headers, the tool manuals ...). Every prompt you leave out keeps its default; see `DEFAULT_PROMPTS` for the names, the
+   * shipped text and the `{{placeholders}}` the SDK fills in. Keeping the original text is recommended: it is what the SDK
+   * is tested with, and a good reference for writing your own. Workers inherit it. A prompt is part of the cached prompt
+   * prefix when it is in the system prompt or a tool description, so change it once, not per run.
+   */
+  prompts?: PromptOverrides;
 }
 
 /**
@@ -316,12 +327,20 @@ export interface DynamicSubagentsConfig {
   /** Fixed reasoning level for all dynamic workers. The Main Agent cannot override it. Falls back to the parent level when omitted. */
   thinkingLevel?: ThinkingLevel;
   /**
-   * Spending cap of EACH worker (the `subagents` tool, `agent.workers` and scheduled actions), set as that worker's own
-   * per-run `budget`: a spawn, a message or a scheduled run is one run, and the usage of the worker's own workers counts
-   * toward it. Exceeding it fails that call with a budget error and leaves the worker open. Default: unlimited. Models
-   * with unknown pricing count $0 toward `maxCostUsd`. Passed down to the workers' own workers.
+   * Spending cap of EACH chat worker (the `subagents` tool and `agent.workers`), set as that worker's own per-run
+   * `budget`: a spawn or a message is one run, and the usage of the worker's own workers counts toward it. Exceeding it
+   * fails that call with a budget error and leaves the worker open. Default: unlimited. Models with unknown pricing count
+   * $0 toward `maxCostUsd`. Passed down to the workers' own workers. Scheduled actions have their own cap:
+   * `scheduledActionBudget`.
    */
   workerBudget?: Pick<Budget, "maxCostUsd" | "maxTotalTokens">;
+  /**
+   * Spending cap of EACH scheduled-action run, set as that run's own per-run `budget` (attempts included: a retry is part
+   * of the same run). Scheduled actions are detached from the chat, so neither `workerBudget` nor `usageLimit` applies to
+   * them. Exceeding it records a failed run. Default: unlimited. Models with unknown pricing count $0 toward
+   * `maxCostUsd`.
+   */
+  scheduledActionBudget?: Pick<Budget, "maxCostUsd" | "maxTotalTokens">;
   /**
    * How many levels of workers may exist below this agent. Default: no limit. `1` = workers cannot start workers of their
    * own; `3` = a worker may start workers that start workers. A worker with levels left gets its own `subagents` tool, and
@@ -383,10 +402,6 @@ export interface AgentRunOptions {
   toolChoice?: ToolChoiceOption;
   /** Per-run output-token cap. */
   maxOutputTokens?: number;
-  /** Per-run stop sequence(s). */
-  stop?: StopOption;
-  /** Per-run seed. */
-  seed?: number;
   /** Per-run retry override. */
   retry?: RetryPolicyConfig;
   /** Per-run fetch override. */

package/src/types/architecture.md

@@ -2,18 +2,19 @@
 
 Shared contracts. Types only, plus a few tiny helpers that belong to a type.
 
-| File | What it defines |
-| :-- | :-- |
-| `agent.ts` | `AgentConfig`, `AgentRunOptions`, `DynamicSubagentsConfig`, `Budget`, `EditableAgentConfig`, run/turn event shapes. |
-| `core.ts` | `ThinkingLevel`, `CacheOption` (+ `CACHE_OPTIONS`), `ServiceTier`, `TokenUsage`. |
-| `message.ts` | `Message` and the content parts (text, image, audio, video, file, tool call/result, thinking), `ProviderSteps`. |
-| `model.ts` | `ModelSpec`, `Provider`, `ProviderRequestOptions`, `ProviderGenerateResult`, structured-output spec. |
-| `response.ts` | `AgentResponse`, `FinishReason` + `normalizeFinishReason`, `StreamEvent`, worker metadata. |
-| `tool.ts` | `ToolDefinition`, `ToolExecutionContext` (`log`, `stop`, `emit`), call/result records, the truncated-arguments marker. |
-| `scheduler.ts` | Scheduled-action input, record and delivery types. |
-| `errors.ts` | The typed error family (`AgentAccelError` and subclasses), `isAbortError`. |
+| File           | What it defines                                                                                                        |
+| :------------- | :--------------------------------------------------------------------------------------------------------------------- |
+| `agent.ts`     | `AgentConfig`, `AgentRunOptions`, `DynamicSubagentsConfig`, `Budget`, `EditableAgentConfig`, run/turn event shapes.    |
+| `core.ts`      | `ThinkingLevel`, `CacheOption` (+ `CACHE_OPTIONS`), `ServiceTier`, `TokenUsage`.                                       |
+| `message.ts`   | `Message` and the content parts (text, image, audio, video, file, tool call/result, thinking), `ProviderSteps`.        |
+| `model.ts`     | `ModelSpec`, `Provider`, `ProviderRequestOptions`, `ProviderGenerateResult`, structured-output spec.                   |
+| `response.ts`  | `AgentResponse`, `FinishReason` + `normalizeFinishReason`, `StreamEvent`, worker metadata.                             |
+| `tool.ts`      | `ToolDefinition`, `ToolExecutionContext` (`log`, `stop`, `emit`), call/result records, the truncated-arguments marker. |
+| `scheduler.ts` | Scheduled-action input, record and delivery types.                                                                     |
+| `errors.ts`    | The typed error family (`AgentAccelError` and subclasses), `isAbortError`.                                             |
 
 ## Invariants
+
 - Adding a field to a public type is a public API change: update `README.md` and `docs/`.
 - Abort means `signal.aborted` or `name === "AbortError"`, never a message match.
 - Error messages are one line and ANSI-free.

package/src/types/core.ts

@@ -2,15 +2,7 @@
  * Level-based reasoning — single flag for all levels (bloatfree)
  */
 /** Public reasoning control accepted by AgentConfig. */
-export type ThinkingLevel =
-  | "none"
-  | "dynamic"
-  | "minimal"
-  | "low"
-  | "medium"
-  | "high"
-  | "xhigh"
-  | "max";
+export type ThinkingLevel = "none" | "dynamic" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 
 // Internal normalized config (SDK-internal, not exposed as Agent flag)
 /** Internal normalized reasoning configuration passed to providers. */
@@ -50,6 +42,10 @@ export interface TokenUsage {
   cacheReadTokens?: number;
   cacheWriteTokens?: number;
   thinkingTokens?: number;
+  /** Media part of `inputTokens` (a subset, report only: pricing never reads it). OpenRouter reports audio and video. */
+  inputDetails?: { audioTokens?: number; videoTokens?: number };
+  /** Media part of `outputTokens` (a subset, report only). OpenRouter reports audio and image. */
+  outputDetails?: { audioTokens?: number; imageTokens?: number };
   cost?: {
     inputCost?: number;
     outputCost?: number;

package/src/types/errors.ts

@@ -40,7 +40,11 @@ export class AgentAccelError extends Error {
   readonly code: AgentAccelErrorCode;
   readonly retryable: boolean;
   readonly context: AgentAccelErrorContext;
-  constructor(code: AgentAccelErrorCode, message: string, opts?: { retryable?: boolean; context?: AgentAccelErrorContext; cause?: unknown }) {
+  constructor(
+    code: AgentAccelErrorCode,
+    message: string,
+    opts?: { retryable?: boolean; context?: AgentAccelErrorContext; cause?: unknown }
+  ) {
     super(message);
     this.name = "AgentAccelError";
     this.code = code;
@@ -59,10 +63,26 @@ export class ConfigError extends AgentAccelError {
 
 export class ProviderError extends AgentAccelError {
   readonly status?: number;
-  constructor(message: string, opts?: { status?: number; provider?: string; model?: string; requestId?: string; retryable?: boolean; context?: AgentAccelErrorContext }) {
+  constructor(
+    message: string,
+    opts?: {
+      status?: number;
+      provider?: string;
+      model?: string;
+      requestId?: string;
+      retryable?: boolean;
+      context?: AgentAccelErrorContext;
+    }
+  ) {
     super("provider", message, {
       retryable: opts?.retryable ?? false,
-      context: { ...opts?.context, provider: opts?.provider, model: opts?.model, status: opts?.status, requestId: opts?.requestId },
+      context: {
+        ...opts?.context,
+        provider: opts?.provider,
+        model: opts?.model,
+        status: opts?.status,
+        requestId: opts?.requestId,
+      },
     });
     this.name = "ProviderError";
     this.status = opts?.status;
@@ -124,7 +144,9 @@ export function isAbortError(error: unknown): boolean {
 /** Format without ANSI for CLI pretty-printing. */
 export function formatErrorPlain(err: unknown): string {
   if (err instanceof AgentAccelError) {
-    const ctx = err.context?.provider ? ` [${err.context.provider}${err.context.model ? `/${err.context.model}` : ""}]` : "";
+    const ctx = err.context?.provider
+      ? ` [${err.context.provider}${err.context.model ? `/${err.context.model}` : ""}]`
+      : "";
     const status = err.context?.status ? ` (${err.context.status})` : "";
     return `[${err.code}]${ctx}${status}: ${err.message}`;
   }

package/src/types/message.ts

@@ -12,6 +12,9 @@ export interface TextPart {
 /** Detail level a provider spends on one image or video (more detail = more input tokens). Google (images and videos) and OpenRouter (images, as `image_url.detail`) honour it; other providers ignore it with a warning. */
 export type MediaResolution = "low" | "medium" | "high" | "ultra_high";
 
+/** How a provider reads a video: `"static"` (fixed-rate frames, the default) or `"agentic"` (the model navigates the timeline and loads only what the prompt needs). Only Google honours it, and agentic mode only on some Gemini models; other providers ignore it with a warning. */
+export type VideoProcessing = "static" | "agentic";
+
 /** Image content accepted as a URL, data, path, or binary value. */
 export interface ImagePart {
   type: "image";
@@ -55,6 +58,8 @@ export interface VideoPart {
   mimeType?: string;
   /** Detail level per frame (Google: `low`/`medium` 70, `high` 280 tokens). */
   resolution?: MediaResolution;
+  /** How the video is read (Google: `"agentic"` lets the model explore a long video instead of loading every frame). */
+  processing?: VideoProcessing;
 }
 
 /** Assistant-generated structured tool invocation. */
@@ -89,6 +94,8 @@ export interface ToolResultPart {
   logFile?: string;
   /** The tool ended the run with `ctx.stop(reason)` (see `ToolExecutionContext.stop`). */
   stopped?: boolean;
+  /** Media the tool returned with `toolContent` (inline data URLs; `result` holds its text). Google sends it to the model. */
+  parts?: ContentPart[];
 }
 
 /** Provider reasoning/thinking content. */

package/src/types/model.ts

@@ -2,6 +2,7 @@ import type { ThinkingConfig, CacheOption, ServiceTier, TokenUsage } from "./cor
 import type { ProviderContext, ProviderSteps } from "./message.ts";
 import type { StandardToolDeclaration, ToolCallRecord } from "./tool.ts";
 import type { AssistantMessageEventStream } from "../streaming/event-stream.ts";
+import type { Prompts } from "../prompts/prompts.ts";
 
 // ---------------------------------------------------------------------------
 // Provider identity — battle-tested: matches models.dev provider keys
@@ -169,7 +170,7 @@ export interface ProviderRequestOptions {
   cache?: CacheOption;
   serviceTier?: ServiceTier;
   tools?: StandardToolDeclaration[];
-  toolChoice?: "auto" | "none" | "required" | { type: "function"; function: { name: string } };
+  toolChoice?: "auto" | "none" | "required" | "validated" | { type: "function"; function: { name: string } };
   signal?: AbortSignal;
   sessionId?: string;
   env?: Record<string, string>;
@@ -185,12 +186,10 @@ export interface ProviderRequestOptions {
   googleTier?: "free" | "paid";
   /** Upper bound on generated tokens for one model call. */
   maxOutputTokens?: number;
-  /** Stop sequence(s). Chat Completions only; other wires warn+drop. */
-  stop?: string[];
-  /** Deterministic-sampling seed. Chat Completions only; other wires warn+drop. */
-  seed?: number;
   /** `fetch` implementation used for the provider request (defaults to global `fetch`). */
   fetch?: typeof fetch;
+  /** The SDK prompts adapters put in a request (`AgentConfig.prompts`); defaults when unset. */
+  prompts?: Pick<Prompts, "structuredOutput" | "toolBridge">;
   /** Base backoff delay in ms for provider retries (default 250). */
   retryBaseDelayMs?: number;
   /** Total time budget in ms for provider retries (default 30000). */

package/src/types/scheduler.ts

@@ -18,12 +18,12 @@ export interface ScheduleSpec {
   /**
    * What happens when the host program was not running at a delivery time. `"skip"`: move on to the next time (a one-shot
    * is done). `"run"`: run it as soon as the program is back. Omitted: the action is marked `missed` and waits for
-   * `runScheduledAction` or `skipScheduledAction`.
+   * `agent.scheduled.run` or `agent.scheduled.skip`.
    */
   onMissed?: "skip" | "run";
 }
 
-/** What `createScheduledAction` receives: dynamic sub-agent fields plus the schedule. */
+/** What `agent.scheduled.create` receives: dynamic sub-agent fields plus the schedule. */
 export interface ScheduledActionInput {
   role?: string;
   instructions: string;
@@ -40,7 +40,7 @@ export interface ScheduledActionInput {
   };
 }
 
-/** What `updateScheduledAction` may change. `id` and the creating agent are immutable. */
+/** What `agent.scheduled.update` may change. `id` and the creating agent are immutable. */
 export type ScheduledActionPatch = Partial<Omit<ScheduledActionInput, "scheduled_action">> & {
   scheduled_action?: Partial<Omit<ScheduledActionInput["scheduled_action"], "id">>;
 };
@@ -81,7 +81,7 @@ export interface ScheduledDelivery {
   late: boolean;
 }
 
-/** Result of `deleteScheduledAction`. */
+/** Result of `agent.scheduled.delete`. */
 export type DeleteResult =
   | { ok: true }
   | { ok: false; reason: "not_found" }

package/src/types/tool.ts

@@ -21,7 +21,13 @@ export interface ToolExecutionContext {
   /** Session identifier associated with this invocation. */
   sessionId?: string;
   /** Forwards live sub-agent deltas (used by the `subagents` tool for realtime tracking). */
-  onSubagentEvent?: (event: { trackingId: string; delta?: string; thinkingDelta?: string; partialText?: string; partialThinking?: string }) => void;
+  onSubagentEvent?: (event: {
+    trackingId: string;
+    delta?: string;
+    thinkingDelta?: string;
+    partialText?: string;
+    partialThinking?: string;
+  }) => void;
   // Tool API v2 context additions (all optional, additive).
   /** Stable id for this run (`newRunId`). Mirrors SubAgentRunIds.runId. */
   runId?: string;
@@ -147,6 +153,8 @@ export interface ToolResultRecord {
   logFile?: string;
   /** The tool ended the run with `ctx.stop(reason)`; `result` is the reason. */
   stopped?: boolean;
+  /** Media returned with `toolContent`, as inline data URLs (`result` is its text). Set only by the executor. */
+  parts?: import("./message.ts").ContentPart[];
 }
 
 /**
@@ -161,5 +169,9 @@ export const TRUNCATED_ARGS_KEY = "__truncated_raw";
 export function isTruncatedArguments(args: unknown): boolean {
   if (!args || typeof args !== "object" || Array.isArray(args)) return false;
   const keys = Object.keys(args as Record<string, unknown>);
-  return keys.length === 1 && keys[0] === TRUNCATED_ARGS_KEY && typeof (args as Record<string, unknown>)[TRUNCATED_ARGS_KEY] === "string";
+  return (
+    keys.length === 1 &&
+    keys[0] === TRUNCATED_ARGS_KEY &&
+    typeof (args as Record<string, unknown>)[TRUNCATED_ARGS_KEY] === "string"
+  );
 }

package/src/update-models.ts

@@ -28,7 +28,9 @@ for (const arg of args) {
     }
     // Reject non-numeric TTLs (e.g. --ttl=abc) instead of silently caching NaN.
     if (!Number.isFinite(customTtlMs)) {
-      throw new ConfigError(`Invalid --ttl value "${val}": expected a number with optional h/m suffix (e.g. --ttl=24h).`);
+      throw new ConfigError(
+        `Invalid --ttl value "${val}": expected a number with optional h/m suffix (e.g. --ttl=24h).`
+      );
     }
   }
 }
@@ -42,13 +44,11 @@ try {
   const ttlHours = (result.ttlMs / (1000 * 60 * 60)).toFixed(1);
 
   if (result.fromCache) {
-    console.log(
-      `\x1b[32m✓\x1b[0m Models catalog is already fresh (within ${ttlHours}h TTL).`
-    );
+    console.log(`\x1b[32m✓\x1b[0m Models catalog is already fresh (within ${ttlHours}h TTL).`);
   } else {
     console.log(
       `\x1b[32m✓\x1b[0m Successfully downloaded and cached \x1b[1m${result.modelCount.toLocaleString()}\x1b[0m models ` +
-      `across \x1b[1m${result.providerCount}\x1b[0m providers in ${duration}s.`
+        `across \x1b[1m${result.providerCount}\x1b[0m providers in ${duration}s.`
     );
   }
   console.log(`  \x1b[90mCache location: ${result.cachePath}\x1b[0m`);

package/src/utils/architecture.md

@@ -2,23 +2,24 @@
 
 Small shared helpers. Each file has one job.
 
-| File | What it does |
-| :-- | :-- |
-| `durable.ts` | The ONE disk writer (`writeFileDurable`: temp, fsync, `.bak`, rename, folder fsync), `readWithBackup`, `lockFolder` (one process per folder, used for session folders; stale-lock takeover, temp sweep) and `withFileMutex` (short per-file lock for state several processes change, e.g. one scheduled action). |
-| `home.ts` | `resolveHome` / `setHome`: the single folder everything is stored in. |
-| `env.ts` | Process-env lookups and API key resolution. No `globalThis` fallback. |
-| `headers.ts` | Session-affinity headers, opt-in attribution, browser stripping, package version fallback. |
-| `media.ts` | Normalizes a path, URL, data URL, base64 or bytes to base64 and a MIME type; magic-byte sniffing. |
-| `safe-io.ts` | `fileAccess.roots` containment and the guarded remote fetch (private hosts refused, redirects re-checked, size cap). |
-| `raw-capture.ts` | The `captureRaw` policy for `AgentResponse.raw`. |
-| `cache.ts` | Cache-key clamp (64 chars) and the central secret redaction. |
-| `errors.ts` | `toConciseProviderError` (any raw provider failure becomes one-line `ProviderError`: `code` `"provider"`, `retryable` from status/code, the provider's code as `providerCode`; SDK errors pass through), `isTransientError`, and the pre-network modality guards (`ValidationError`). |
-| `retry.ts` | `withRetries`, `isTransientError` (re-exported from `errors.ts`), `isRetryableRun`, `sleep`. Structured data only (status, code, flags), never message text. |
-| `session.ts` | Id helpers (`createSessionId`, `hashSessionPart`, `createTrackingId`, run/turn ids), `parseModelRef`, `previewPrompt`. |
-| `serialization.ts` | `toJsonSafe`, `safeStringify`, `escapeXml`. |
-| `base64.ts`, `thought-signature.ts` | Runtime-agnostic base64; Gemini thought-signature helpers. |
+| File                                | What it does                                                                                                                                                                                                                                                                                                     |
+| :---------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `durable.ts`                        | The ONE disk writer (`writeFileDurable`: temp, fsync, `.bak`, rename, folder fsync), `readWithBackup`, `lockFolder` (one process per folder, used for session folders; stale-lock takeover, temp sweep) and `withFileMutex` (short per-file lock for state several processes change, e.g. one scheduled action). |
+| `home.ts`                           | `resolveHome` / `setHome`: the single folder everything is stored in.                                                                                                                                                                                                                                            |
+| `env.ts`                            | Process-env lookups and API key resolution. No `globalThis` fallback.                                                                                                                                                                                                                                            |
+| `headers.ts`                        | Session-affinity headers, opt-in attribution, browser stripping, package version fallback.                                                                                                                                                                                                                       |
+| `media.ts`                          | Normalizes a path, URL, data URL, base64 or bytes to base64 and a MIME type; magic-byte sniffing.                                                                                                                                                                                                                |
+| `safe-io.ts`                        | `fileAccess.roots` containment and the guarded remote fetch (private hosts refused, redirects re-checked, size cap).                                                                                                                                                                                             |
+| `raw-capture.ts`                    | The `captureRaw` policy for `AgentResponse.raw`.                                                                                                                                                                                                                                                                 |
+| `cache.ts`                          | Cache-key clamp (64 chars) and the central secret redaction.                                                                                                                                                                                                                                                     |
+| `errors.ts`                         | `toConciseProviderError` (any raw provider failure becomes one-line `ProviderError`: `code` `"provider"`, `retryable` from status/code, the provider's code as `providerCode`; SDK errors pass through), `isTransientError`, and the pre-network modality guards (`ValidationError`).                            |
+| `retry.ts`                          | `withRetries`, `isTransientError` (re-exported from `errors.ts`), `isRetryableRun`, `sleep`. Structured data only (status, code, flags), never message text.                                                                                                                                                     |
+| `session.ts`                        | Id helpers (`createSessionId`, `hashSessionPart`, `createTrackingId`, run/turn ids), `parseModelRef`, `previewPrompt`.                                                                                                                                                                                           |
+| `serialization.ts`                  | `toJsonSafe`, `safeStringify`, `escapeXml`.                                                                                                                                                                                                                                                                      |
+| `base64.ts`, `thought-signature.ts` | Runtime-agnostic base64; Gemini thought-signature helpers.                                                                                                                                                                                                                                                       |
 
 ## Invariants
+
 - Never write state with a bare `writeFileSync`; use `writeFileDurable`.
 - `media.ts` and `safe-io.ts` import `node:*` lazily so browser bundles keep working.
 - Redaction is central (`cache.ts`); adapters must not keep their own deny-lists.

package/src/utils/cache.ts

@@ -58,9 +58,7 @@ export function redactValue(value: unknown): unknown {
  * Deny-list (name contains): *key*, *token*, *secret*, cookie, authorization.
  * Value patterns (redacted regardless of name): sk-, AIza, gsk-, xox-.
  */
-export function redactHeadersCentral(
-  headers: Record<string, unknown> | undefined | null
-): Record<string, unknown> {
+export function redactHeadersCentral(headers: Record<string, unknown> | undefined | null): Record<string, unknown> {
   if (!headers || typeof headers !== "object") return {};
   const out: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(headers)) {

package/src/utils/durable.ts

@@ -32,7 +32,11 @@ export function fsyncFolder(dir: string): void {
  * Durable atomic write: temp file (0600) -> fsync -> previous version kept as `<file>.bak` (hard link, no copy)
  * -> rename -> fsync of the folder. Throws on failure; the temp file is removed. `backup: false` skips the `.bak`.
  */
-export function writeFileDurable(filePath: string, content: string | Uint8Array, opts: { backup?: boolean } = {}): void {
+export function writeFileDurable(
+  filePath: string,
+  content: string | Uint8Array,
+  opts: { backup?: boolean } = {}
+): void {
   const dir = path.dirname(filePath);
   try {
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -73,7 +77,10 @@ export function writeFileDurable(filePath: string, content: string | Uint8Array,
  * Reads `file`; when `isValid` rejects it, falls back to `<file>.bak`. `undefined` when the file is missing (a deleted
  * file is never resurrected from its backup). When both are invalid the primary text comes back, `fromBackup: false`.
  */
-export function readWithBackup(file: string, isValid: (text: string) => boolean): { text: string; fromBackup: boolean } | undefined {
+export function readWithBackup(
+  file: string,
+  isValid: (text: string) => boolean
+): { text: string; fromBackup: boolean } | undefined {
   let text: string;
   try {
     text = fs.readFileSync(file, "utf8");
@@ -234,7 +241,8 @@ const heldMutexes = new Set<string>();
  */
 export function withFileMutex<T>(lockFile: string, fn: () => T): T {
   const file = path.resolve(lockFile);
-  if (heldMutexes.has(file)) throw new ConfigError(`[Agent Accelerator] Mutex "${file}" is already held by this process (nested use).`);
+  if (heldMutexes.has(file))
+    throw new ConfigError(`[Agent Accelerator] Mutex "${file}" is already held by this process (nested use).`);
   const mine = JSON.stringify({ pid: process.pid, host: os.hostname(), at: Date.now() });
   const deadline = Date.now() + MUTEX_WAIT_MS;
   let unreadable = 0;
@@ -265,7 +273,8 @@ export function withFileMutex<T>(lockFile: string, fn: () => T): T {
       owner = undefined;
     }
     let stale = false;
-    if (typeof owner?.pid !== "number") stale = ++unreadable > 5; // empty or garbage: another process may be mid-write
+    if (typeof owner?.pid !== "number")
+      stale = ++unreadable > 5; // empty or garbage: another process may be mid-write
     else if (owner.host === os.hostname() && !processAlive(owner.pid)) stale = true;
     else if (Date.now() - mtime > MUTEX_MAX_AGE_MS) stale = true;
     if (stale) {
@@ -276,7 +285,10 @@ export function withFileMutex<T>(lockFile: string, fn: () => T): T {
       }
       continue;
     }
-    if (Date.now() > deadline) throw new ConfigError(`[Agent Accelerator] Timed out after ${MUTEX_WAIT_MS} ms waiting for the lock "${file}" (held by process ${String(owner?.pid)}).`);
+    if (Date.now() > deadline)
+      throw new ConfigError(
+        `[Agent Accelerator] Timed out after ${MUTEX_WAIT_MS} ms waiting for the lock "${file}" (held by process ${String(owner?.pid)}).`
+      );
     pause(typeof owner?.pid === "number" ? 2 : 40);
   }
   heldMutexes.add(file);

package/src/utils/env.ts

@@ -11,7 +11,10 @@ export function getEnv(key: string, fallback?: string): string | undefined {
   if (typeof process !== "undefined" && process.env && process.env[key]) {
     // Trim quotes/whitespace from .env files (`sk-..."\n` -> 401 otherwise).
     const raw = String(process.env[key]);
-    const trimmed = raw.trim().replace(/^["']|["']$/g, "").trim();
+    const trimmed = raw
+      .trim()
+      .replace(/^["']|["']$/g, "")
+      .trim();
     if (trimmed) return trimmed;
   }
   return fallback;
@@ -27,7 +30,10 @@ export type ProviderEnv = Record<string, string>;
 export function getApiKey(provider: string, explicitKey?: string, env?: ProviderEnv): string | undefined {
   const clean = (v: unknown): string | undefined => {
     if (typeof v !== "string") return undefined;
-    const t = v.trim().replace(/^["']|["']$/g, "").trim();
+    const t = v
+      .trim()
+      .replace(/^["']|["']$/g, "")
+      .trim();
     return t || undefined;
   };
   const cleanedExplicit = clean(explicitKey);
@@ -56,11 +62,7 @@ export function getApiKey(provider: string, explicitKey?: string, env?: Provider
   switch (provider.toLowerCase()) {
     case "google":
     case "gemini":
-      return (
-        getEnv("GEMINI_API_KEY") ||
-        getEnv("GOOGLE_API_KEY") ||
-        getEnv("GOOGLE_GENAI_API_KEY")
-      );
+      return getEnv("GEMINI_API_KEY") || getEnv("GOOGLE_API_KEY") || getEnv("GOOGLE_GENAI_API_KEY");
     case "openrouter":
       return getEnv("OPENROUTER_API_KEY");
     case "openai":