agent-accelerator 0.5.0 → 0.5.2

package/README.md

@@ -17,7 +17,7 @@ import { Agent } from "agent-accelerator";
 const agent = new Agent({
   model: "google/gemini-3.5-flash-lite",
   instructions: "You are a concise research engineer.",
-  cache: { retention: "short" },
+  cache: "implicit",
 });
 
 const res = await agent.run("Explain HBM pricing in 3 bullets");
@@ -32,10 +32,10 @@ console.log(res.usage);
 
 ```bash
 # Bun (recommended)
-bun add agent-accelerator
+bun add agent-accelerator zod
 
 # npm
-npm install agent-accelerator
+npm install agent-accelerator zod
 
 # pnpm
 pnpm add agent-accelerator
@@ -46,7 +46,7 @@ yarn add agent-accelerator
 
 Requires `bun` or `node 22+`.
 
-Core dependencies are `zod` only. Document conversion additionally uses the optional `@firecrawl/anydoc` peer. All provider transports are native REST (`fetch`, no SDK).
+The only dependency is `zod` (a peer dependency: install it next to the SDK and import `z` from `"zod"`). All provider transports are native REST (`fetch`, no SDK).
 
 ---
 
@@ -123,9 +123,8 @@ An `Agent` holds:
 | `subagentModel`   | `string \| ModelSpec \| ModelProviderInstance`       | Developer-only model for dynamically spawned workers. Never choosable by the Main Agent. Deprecated alias of `dynamicSubagents.model` (which wins). Falls back to `SUB_AGENT_MODEL`. |
 | `dynamicSubagents` | `DynamicSubagentsConfig`                            | Enables and constrains LLM-spawned stateless workers: `{ enabled, model?, maxSpawn?, thinkingLevel?, tools?, timeout?, allowScheduledActions? }`. See [Pre-defined vs Dynamic Delegation](#pre-defined-vs-dynamic-delegation) and [Scheduled actions](#scheduled-actions). |
 | `thinking`        | `ThinkingOption`                                     | Canonical reasoning option: `none \| dynamic \| minimal \| low \| medium \| high \| xhigh \| max`, or `{ level, budgetTokens }`. Legacy `thinkingLevel` still works (canonical wins). Validated against the model catalog before a request.                                      |
-| `cache`           | `CacheConfig`                                        | `{ retention, sessionId, cachedContentId, ttlSeconds }`. Controls cache reuse.                                                                             |
+| `cache`           | `CacheOption`                                        | `"implicit" \| "5m" \| "30m" \| "1h" \| "12h"`. Prompt-cache lifetime; unsupported values warn and fall back (see [Cache](#cache)).                                                                             |
 | `serviceTier`     | `"flex" \| "priority"`                               | Cost / priority routing where supported. Omit for standard routing.                                                                                        |
-| `bypassInputFileModality` | `boolean`                                      | When `true`, `file` parts are converted client-side to Markdown for models lacking native support. Capable models still receive files natively. Defaults to `false`. |
 | `maxTurns`        | `number`                                             | Maximum model → tool → model loops per `run`. Infinite by default (`0` or omitted = no limit). Hitting a finite limit with pending tool calls warns and sets `finishReason: "max_turns"`. |
 | `sessionId`       | `string`                                             | Stable identifier used for cache affinity. Auto-generated when omitted.                                                                                    |
 | `headers`         | `Record<string,string>`                              | Additional headers merged into every request.                                                                                                              |
@@ -239,7 +238,6 @@ const lead = new Agent({
 ### Differences from Agent
 
 * `model` resolves as `config.model ?? SUB_AGENT_MODEL ?? MODEL` and throws if empty.
-* `cache` defaults to `{ retention: "short" }`.
 * `.asTool(name?, desc?)` / `.toTool(name?, desc?)` converts the subagent into a `ToolDefinition` for manual registration.
 * `stateless: true` is supported for one-shot judges that must not retain history.
 
@@ -378,7 +376,8 @@ telemetryBus.onEvent((e) => {
 ## Tools
 
 ```ts
-import { Agent, tool, z } from "agent-accelerator";
+import { Agent, tool } from "agent-accelerator";
+import { z } from "zod";
 
 const agent = new Agent({
   model: "google/gemini-3.5-flash-lite",
@@ -404,7 +403,6 @@ const agent = new Agent({
 * `zodToJsonSchema(schema)` — converts Zod schemas using native conversion with a fallback extractor.
 * `cleanJsonSchema(schema)` — removes `$schema`, `$defs`, and `definitions`, resolves `$ref`, and preserves explicit `additionalProperties`.
 * `executeToolCalls({ tools, toolCalls, agentName?, parallel?, signal?, sessionId? })` — executes tool calls. Calls validate Zod input, use bounded parallelism, enforce per-tool timeouts, retry transient failures, recover namespace/camel-case tool-name aliases, and return `ToolResultRecord[]`. Missing tools and aborts are represented as error results rather than thrown.
-* `convert_document_to_markdown` — built-in, model-callable version of `convertDocumentToMarkdown` (PDF/Word/PowerPoint/Excel/OpenDocument/RTF/EPUB/CSV, local path or URL) for models without native document parsing. Returns a `<Document>` envelope, is auto-registered with `bypassInputFileModality: true`, and requires the optional `@firecrawl/anydoc` peer.
 
 The agent loop answers the 3rd consecutive identical call (same name and arguments) with a `repeat_blocked` error, so the model can reuse the prior result or change its arguments. Tools marked `repeatable: true`, or `idempotent: true` unless `repeatable` is set, are exempt.
 
@@ -522,6 +520,24 @@ Model resolution never silently selects a default model: an empty model throws.
 
 An unknown prefix with no catalog match still routes to a custom provider, allowing private model IDs and endpoints.
 
+### Google long decode (Gemini 4)
+
+Google caps one request at 65,536 output tokens. Set `maxOutputTokens` above
+that on a `gemini-4-*` model and the SDK runs the request as a background
+interaction automatically (no extra option): up to 1,048,576 tokens minus the
+input, for up to 24 hours. `run()` polls until it finishes (2 s, then every
+5 s); `stream()` reconnects after a dropped or silent connection
+(`last_event_id`, 15 min of silence counts as dropped). Aborting cancels the
+interaction on Google's side, so it stops billing. Each HTTP request is still
+timed by `limits.requestTimeoutMs`, but the whole run is not. Any other Google
+model with `maxOutputTokens` above 65,536 fails before the network with a
+`ConfigError`. Use it for hard reasoning, not chat: you pay for every token of
+every 64K hop.
+
+A custom `Provider` can opt into the same treatment with the optional
+`isLongRunning(model, options)` method: when it returns `true`, the loop skips
+its whole-call, first-byte and idle timers and leaves timing to the adapter.
+
 ### Registry
 
 * `resolveModel("google/x" | ModelSpec)` → `{ provider, modelId, modelSpec? }`. Use to inspect routing before execution.
@@ -587,11 +603,10 @@ Google-specific handling includes:
 
 * Isolating `thoughtSignature` per part for prefix stability.
 * Converting JSON Schema to OpenAPI 3.0 through `stripSchemaForGoogle`.
-* Implicit/automatic caching only; explicit retention and `cachedContentId` are dropped (see [Cache](#cache)).
+* Implicit caching only; other `cache` values warn and fall back (see [Cache](#cache)).
 
 Helpers:
 
-* `createExplicitCache({ model, systemInstruction?, contents?, tools?, displayName?, ttlSeconds?, expireTime?, apiKey?, baseUrl? })`
 * `isValidThoughtSignature(sig)`
 * `retainThoughtSignature(existing, incoming)`
 * `extractGoogleThoughtSignature(obj)`
@@ -724,26 +739,20 @@ Fixed-reasoning models reject `none`.
 ## Cache
 
 ```ts
-CacheConfig {
-  retention?,
-  cachedContentId?,
-  sessionId?,
-  ttlSeconds?
-}
+cache?: "implicit" | "5m" | "30m" | "1h" | "12h"   // CacheOption; omit for the provider default
 ```
 
-```ts
-CacheRetention =
-  | "implicit"
-  | "short"
-  | "medium"
-  | "long";
-```
+One value sets the prompt-cache lifetime. Each provider honours only the values it supports; any other value falls back to the provider default and emits one `provider_warning` naming the supported values.
 
-### Retention
+| Provider | Supported | Sent on the wire |
+| --- | --- | --- |
+| Google (Interactions) | `implicit` | nothing (implicit caching is always on) |
+| OpenRouter, `anthropic/*` models | `implicit`, `5m`, `1h` | top-level `cache_control: { type: "ephemeral", ttl }` |
+| OpenRouter, other models | `implicit` | nothing (automatic caching + sticky routing) |
+| OpenAI | `implicit`, `12h` | `12h` sends `prompt_cache_retention: "24h"` when the catalog allows long retention |
+| Custom endpoints | `implicit` | nothing (strict endpoints reject unknown fields) |
 
-* `implicit` — automatic prefix reuse without an explicit cache object or storage fee. This is the only retention the native adapters act on (by doing nothing special — stable prompts plus session affinity do the work).
-* `short` / `medium` / `long` — TTL hints (`5m` / `1h` / `12h`) consumed only by the opt-in `createExplicitCache` helper. Provider adapters warn about and drop any non-`implicit` retention: none of the native transports expose retention control.
+Session files written before 0.5.1 with the old `{ retention }` object still load (`short`=`5m`, `medium`=`1h`, `long`=`12h`). Passing the object form to `new Agent()` throws `ConfigError`.
 
 ### Session Affinity
 
@@ -757,26 +766,7 @@ Reuse the same session ID across turns when cache affinity is desired.
 
 In browser runtimes custom `x-*` headers are stripped to avoid CORS preflights: OpenAI keeps affinity through its body key, while custom endpoints lose affinity entirely on browsers.
 
-### Explicit Caches
-
-`createExplicitCache` mints a Google `cachedContents/...` resource directly (TTL via `retention`/`ttlSeconds`).
-
-`cachedContentId` is accepted and carried in context, but no native adapter currently sends it — explicit references are warned about and dropped, so stable prompts plus session affinity remain the cache-reuse path.
-
-`ttlSeconds` overrides the retention mapping.
-
-### Provider Cache Mechanisms
-
-* **Google** keeps system prompts and tools stable and isolates signatures (implicit caching only).
-* **OpenAI** pins affinity with `prompt_cache_key`.
-* **OpenRouter** pins affinity with body `session_id` plus headers (sticky routing from the first request).
-* **Custom endpoints** get headers-only affinity; anything else cache-related is warned about and dropped.
-
-The following cache helpers are exported:
-
-* `getPromptCacheRetention`
-* `retentionToTtlSeconds`
-* `clampCacheKey`
+`clampCacheKey` (exported) shortens affinity keys to the provider-safe 64 characters.
 
 For the best cache reuse, keep `instructions` and the tool set stable. Put changing data in user messages or `additionalContext`.
 
@@ -1146,18 +1136,26 @@ Message {
   role: "system" | "user" | "assistant" | "tool",
   content: string | ContentPart[],
   name?,
-  thoughtSignature?
+  thoughtSignature?,
+  providerSteps?   // { provider, steps }: raw output steps of an assistant turn
 }
 ```
 
+`providerSteps` keeps a provider's raw output for one assistant turn (today:
+Google's `steps`, including thought signatures). When Google needs the full
+history again (after a restart, an expired chain or a provider switch), those
+turns are resent exactly as received, which keeps reasoning continuity and
+the implicit-cache prefix intact. Other providers ignore it. Adapters return
+it on `ProviderGenerateResult` / per-turn stream `AgentResponse`; it is never
+part of `toJSON()`.
+
 ### ProviderContext
 
 ```ts
 ProviderContext {
   systemPrompt?,
   messages,
-  tools?,
-  cachedContentId?
+  tools?
 }
 ```
 
@@ -1169,9 +1167,9 @@ Supported content parts include:
 * `ThinkingPart { type:"thinking", thinking, thoughtSignature? }` — preserved reasoning.
 * `ToolCallPart { type:"tool_call", id, name, arguments, rawArguments?, thoughtSignature? }`
 * `ToolResultPart { type:"tool_result", id, name, result, isError? }`
-* `ImagePart { type:"image", image, mimeType? }`
+* `ImagePart { type:"image", image, mimeType?, resolution? }`
 * `AudioPart { type:"audio", audio, mimeType? }`
-* `VideoPart { type:"video", video, mimeType? }`
+* `VideoPart { type:"video", video, mimeType?, resolution? }`
 * `FilePart { type:"file", file, mimeType?, filename? }` — PDFs/documents.
 
 `image`, `audio`, `video`, and `file` inputs accept:
@@ -1200,6 +1198,20 @@ Media normalization is handled automatically by providers (mapped to provider-na
 Provider matrix: text + image + wav/mp3 audio + PDF work on all supported
 providers. Video works on Gemini only.
 
+On Google, links Google fetches itself go as a `uri` without downloading:
+YouTube links, Files API links, `gs://` objects and public `https://` URLs of
+URL-supported types (PDF, CSV, text, JSON, PNG/JPEG/WebP/BMP, common video;
+max 15 MB). Audio URLs and `http://` links are downloaded and inlined. Inline
+types are checked before the network; Google reads only PDF and CSV
+documents. The supported lists are the `GOOGLE_*_MIME` constants at the top of
+`src/providers/google.ts`.
+
+`resolution` (`MediaResolution`: `"low" | "medium" | "high" | "ultra_high"`)
+sets how much detail Google spends on one image or video, and so how many
+input tokens it costs (image: 280 / 560 / 1120 / 2240; video per frame:
+`low` and `medium` 70, `high` 280). Omit it for Google's default. Other
+providers ignore it with one `provider_warning`.
+
 Before any network call, the executor checks `image` / `audio` / `video` /
 `file`-as-PDF parts against the catalog's `modalities.input` for that
 provider/model and fails fast with a one-line error naming the gap
@@ -1219,8 +1231,6 @@ never in the gitignored snapshot.
 * `getApiKey(provider, explicit?, env?)` — resolves API keys using the configured environment lookup order.
 * `buildSessionHeaders(provider, cache?, custom?, sessionId?)` — builds provider-specific affinity headers. Normally handled automatically.
 * `withRetries(fn, { maxRetries?, maxRetryDelayMs?, signal?, label? })` / `isTransientError(err)` — bounded retries for transient provider failures (defaults: 2 retries, 5s cap, aborts never retried).
-* `convertDocumentToMarkdown(input, { filename?, format?, mimeType?, maxChars? })` — converts PDF/Word/PowerPoint/Excel/OpenDocument/RTF/EPUB/CSV to Markdown via the optional `@firecrawl/anydoc` peer. Throws `DocumentConversionError` on failure.
-* `z` — re-exported from Zod so tools do not require a separate Zod import.
 
 ---
 ## Examples
@@ -1253,9 +1263,6 @@ bun run examples/09-multimodal_document.ts
 bun run examples/08-multimodal_video.ts
 # video input (video-capable model required)
 
-bun run examples/10-document_markdown.ts
-# document → Markdown preprocessing (any model, optional @firecrawl/anydoc peer)
-
 bun run examples/11-session-identity.ts
 # sub-agent TrackingIDs, live worker boxes, lineage, track(), durable sessions
 
@@ -1319,7 +1326,7 @@ saveSessionFile(".session.json", agent, telemetry);
 
 * `agent.exportSession(telemetry)` / `agent.importSession(saved)` round-trip messages, system prompt, model, thinking level, instructions, cache, worker model, and sub-agent traces without touching `AgentContext` internals.
 * `SessionTelemetry` accumulates `input / output / cacheRead / cacheWrite / reasoning / cost`, with clamped `turnHitRate()` / `totalHitRate()`, a dual `formatBar(res)`, and `formatSessionBanner(saved, telemetry, path)` for startup. Cost follows the [TokenUsage](#response-usage-and-raw-data) rules.
-* Files are JSON with one line per top-level field and one line per turn (2-space indent), written atomically (temp + rename).
+* Files are JSON with one line per top-level field and one line per turn (2-space indent), written atomically (temp + rename). Google turns also store their raw `providerSteps`, so a resumed session replays them exactly.
 * Binary media (bytes, data URLs, base64) is extracted to `media/` on save via `saveSessionDir("sessions", agent, telemetry)` → `sessions/<sessionId>/{session.json, media/*}`; remote URLs and local paths stay references. `loadSessionDir(dir)` resolves `media/…` refs back to absolute paths, and `findLatestSessionDir("sessions")` resumes the most recent session.
 * Sub-agent traces persist in a dedicated `subagents` section keyed by TrackingID (`{ trackingId, name, sessionId, parentSessionId, status, task, turns, usage, steps, text }`). Files stay lean: redundant `rawArguments` and repeated step text are dropped on save (rebuilt/kept live in memory).
 * With `persist: { dir }` or `{ file }`, the session file is rewritten after every step, so a crash loses at most the in-flight step.
@@ -1347,7 +1354,7 @@ src/
 ├── tools/      # tool(), schema, executor
 ├── streaming/  # event stream, SSE parser
 ├── types/      # agent, core, message, model, response, tool
-└── utils/      # base64, cache, env, headers, media, serialization, session, thought-signature, documents, retry, errors
+└── utils/      # base64, cache, env, headers, media, serialization, session, thought-signature, retry, errors
 examples/        # live demos 01-14 (see Examples), plus files/, prompts/, research-agent.ts, _shared.ts
 test/            # unit + mocked-provider tests mirroring src/
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-accelerator",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "High-performance SDK for AI agents with a unified API across AI providers. Optimized for high cache hit rates, observability, and seamless agent orchestration. Built to power production-grade agentic systems and harnesses for teams at any scale.",
   "license": "MIT",
   "author": "Sashvat Bharat",
@@ -42,22 +42,15 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "bun test test/",
-    "update-models": "bun src/update-models.ts"
-  },
-  "devDependencies": {
-    "@firecrawl/anydoc": "^0.2.4",
-    "@types/bun": "latest",
-    "typescript": "^7.0.0"
+    "update-models": "bun src/update-models.ts",
+    "fetch-latest-provider-docs": "bun references/documentations/fetch-latest.ts"
   },
   "peerDependencies": {
-    "@firecrawl/anydoc": "^0.2.4"
-  },
-  "peerDependenciesMeta": {
-    "@firecrawl/anydoc": {
-      "optional": true
-    }
+    "zod": "^4.4.3"
   },
-  "dependencies": {
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^7.0.0",
     "zod": "^4.4.3"
   }
 }

package/src/agent/agent.ts

@@ -3,7 +3,7 @@ import type { TokenUsage } from "../types/core.ts";
 import type { ProviderRequestOptions } from "../types/model.ts";
 import { normalizeThinkingV2, resolveWhenBusy, normalizeWorkerTimeout } from "../tools/tool.ts";
 import type { ToolDefinition } from "../types/tool.ts";
-import type { ThinkingLevel, ThinkingConfig, CacheConfig, ServiceTier } from "../types/core.ts";
+import { CACHE_OPTIONS, type ThinkingLevel, type ThinkingConfig, type CacheOption, type ServiceTier } from "../types/core.ts";
 import type { ContentPart } from "../types/message.ts";
 import { AgentResponse, type StreamEvent } from "../types/response.ts";
 import { AssistantMessageEventStream } from "../streaming/event-stream.ts";
@@ -16,7 +16,6 @@ import {
   resolveMainModel,
 } from "./worker.ts";
 import * as path from "node:path";
-import { createConvertDocumentTool } from "../utils/documents.ts";
 import { registerAgent } from "../scheduler/scheduler.ts";
 import { resolveHome } from "../scheduler/store.ts";
 import { persistTelemetry } from "../telemetry-file.ts";
@@ -171,17 +170,13 @@ export class Agent {
   readonly output?: unknown;
   /** Normalized structured-output spec sent to providers. */
   readonly outputSpec?: StructuredOutputSpec;
-  /** Cache retention/session settings. */
-  readonly cacheConfig?: CacheConfig;
+  /** Prompt-cache lifetime (see `AgentConfig.cache`); unset = provider default. */
+  readonly cache?: CacheOption;
   /** Provider service tier. */
   readonly serviceTier?: ServiceTier;
-  /** Convert `file` parts client-side for pdf-incapable models. */
-  readonly bypassInputFileModality: boolean;
   /**
-   * Local-file policy. `roots` set: every local-path media part and the
-   * built-in document tool must resolve inside them (`[]` denies all paths).
-   * Unset: developer-supplied parts are unrestricted and the model-callable
-   * tool is limited to the working directory.
+   * Local-file policy. `roots` set: every local-path media part must resolve
+   * inside them (`[]` denies all paths). Unset: local paths are unrestricted.
    */
   readonly fileAccess?: { roots?: string[] };
   /** Failure policy for the conversation (see `AgentConfig.onFailure`). */
@@ -310,7 +305,7 @@ export class Agent {
         : Number.isFinite(config.maxTurns as number)
           ? Math.max(1, Math.floor(config.maxTurns as number))
           : Infinity;
-    this.sessionId = config.sessionId || config.cache?.sessionId || createSessionId();
+    this.sessionId = config.sessionId || createSessionId();
     (this as any).subagentTraces = {};
     this.home = resolveHome(config.home);
     // `persist: {}` (neither dir nor file) means the default sessions folder under home.
@@ -346,16 +341,14 @@ export class Agent {
       this.outputSpec = normalizeStructuredOutput(config.output);
     }
 
-    // DX5: cache retention short|medium|long, undefined = no explicit
-    this.cacheConfig = {
-      sessionId: this.sessionId,
-      ...(config.cache ?? {}),
-    };
-    // C11: wire explicit cachedContentId into context for Google explicit cache
-    const initialCachedId = (this.cacheConfig as any)?.cachedContentId;
+    if (config.cache !== undefined && !CACHE_OPTIONS.includes(config.cache)) {
+      throw new ConfigError(
+        `[Agent Accelerator] Invalid cache ${JSON.stringify(config.cache)}: expected one of ${CACHE_OPTIONS.map((v) => `"${v}"`).join(", ")}, or omit it for the provider default.`
+      );
+    }
+    this.cache = config.cache;
 
     this.serviceTier = config.serviceTier;
-    this.bypassInputFileModality = config.bypassInputFileModality ?? false;
     this.onFailure =
       config.onFailure === "rollback" || config.onFailure === "keep" ? config.onFailure : "auto";
     this.forkConfig = { ...config };
@@ -400,10 +393,6 @@ export class Agent {
       }
     }
 
-    if (this.bypassInputFileModality && !this.tools["convert_document_to_markdown"]) {
-      this.tools["convert_document_to_markdown"] = createConvertDocumentTool({ roots: this.fileAccess?.roots });
-    }
-
     const dyn = this.dynamicSubagents;
     if ((dyn?.enabled === true || dyn?.allowScheduledActions) && !this.subagentModel) {
       throw new SubAgentModelError(
@@ -425,9 +414,6 @@ export class Agent {
     assertNoToolCollisions(this.tools);
 
     this.context = new AgentContext(this.getFullInstructions());
-    if (initialCachedId) {
-      this.context.cachedContentId = initialCachedId;
-    }
     if (dyn?.allowScheduledActions) registerAgent(this);
   }
 
@@ -474,7 +460,6 @@ export class Agent {
     const sid = this.sessionId;
     this.context.messages = [];
     this.context.thoughtSignatures = [];
-    this.context.cachedContentId = (this.cacheConfig as any)?.cachedContentId;
     this.context.systemPrompt = this.getFullInstructions();
     // Q-25: reset also drops session-scoped provider chaining/routing.
     try { clearInteractionChains(sid); } catch {}
@@ -533,10 +518,6 @@ export class Agent {
       return existing.context;
     }
     const fresh = new AgentContext(this.getFullInstructions());
-    try {
-      const cached = (this.cacheConfig as unknown as { cachedContentId?: string })?.cachedContentId;
-      if (cached) fresh.cachedContentId = cached;
-    } catch {}
     this.sessions.set(sid, { context: fresh, lastAccess: now });
     // LRU eviction (oldest lastAccess first).
     try {
@@ -961,9 +942,7 @@ export class Agent {
       baseUrl: this.baseUrl,
       headers: { ...(this.customHeaders ?? {}), ...(runOptions?.headers ?? {}) },
       thinking: resolveEffectiveThinking(this.thinkingConfig, runOptions?.thinkingLevel),
-      cache: this.stateless
-        ? { sessionId }
-        : { ...this.cacheConfig, sessionId },
+      ...(this.cache ? { cache: this.cache } : {}),
       serviceTier: this.serviceTier,
       sessionId,
       ...(this.outputSpec ? { output: this.outputSpec } : {}),
@@ -1013,7 +992,6 @@ export class Agent {
         options: providerOptions,
         runOptions,
         maxTurns: this.maxTurns,
-        bypassInputFileModality: this.bypassInputFileModality,
         ...(this.fileAccess ? { fileAccess: this.fileAccess } : {}),
         onFailure: this.onFailure,
         ...(this.captureRaw !== undefined ? { captureRaw: this.captureRaw } : {}),
@@ -1076,7 +1054,6 @@ export class Agent {
       options: providerOptions,
       runOptions,
       maxTurns: this.maxTurns,
-      bypassInputFileModality: this.bypassInputFileModality,
       ...(this.fileAccess ? { fileAccess: this.fileAccess } : {}),
       onFailure: this.onFailure,
       ...(this.captureRaw !== undefined ? { captureRaw: this.captureRaw } : {}),
@@ -1291,13 +1268,7 @@ export class Agent {
             : { enabled: true, level: lvl };
     }
     if (typeof data.instructions === "string") this.instructions = data.instructions;
-    if (data.cache) {
-      (this as any).cacheConfig = {
-        ...this.cacheConfig,
-        ...data.cache,
-        sessionId: data.sessionId ?? this.sessionId,
-      };
-    }
+    if (data.cache) (this as { cache?: CacheOption }).cache = data.cache;
     if (data.subagentModel) {
       (this as any).subagentModel = data.subagentModel;
       const dyn = (this as any).dynamicSubagents;
@@ -1319,8 +1290,6 @@ export class Agent {
     } else {
       this.context.systemPrompt = this.getFullInstructions();
     }
-    this.context.cachedContentId =
-      data.cachedContentId ?? (this.cacheConfig as any)?.cachedContentId;
     // Q-25: importing a snapshot invalidates prior provider chaining/routing
     // for both the previous and the restored session.
     try { clearInteractionChains(prevSid); } catch {}
@@ -1383,10 +1352,6 @@ export class Agent {
     } else if (ctx.systemPrompt !== fullInstructions) {
       ctx.systemPrompt = fullInstructions;
     }
-    // C11: keep context cachedContentId in sync with cacheConfig if updated via options
-    if (options?.headers && (this.cacheConfig as any)?.cachedContentId && !ctx.cachedContentId) {
-      ctx.cachedContentId = (this.cacheConfig as any).cachedContentId;
-    }
     ctx.addUserMessage(prompt);
   }
 

package/src/agent/context.ts

@@ -1,4 +1,4 @@
-import type { Message, ContentPart } from "../types/message.ts";
+import type { Message, ContentPart, ProviderSteps } from "../types/message.ts";
 import type { ToolCallRecord, ToolResultRecord } from "../types/tool.ts";
 import { safeStringify } from "../utils/serialization.ts";
 import { clearSessionRouting } from "../providers.ts";
@@ -27,7 +27,6 @@ export class AgentContext {
   systemPrompt?: string;
   messages: Message[] = [];
   thoughtSignatures: string[] = [];
-  cachedContentId?: string;
 
   constructor(systemPrompt?: string) {
     this.systemPrompt = systemPrompt;
@@ -57,11 +56,13 @@ export class AgentContext {
     });
   }
 
+  // Stores one model turn as an assistant message (text, thinking, tool calls, raw provider steps for replay); in: a provider turn from the loop, out: history.
   addAssistantMessage(
     text: string,
     toolCalls?: ToolCallRecord[],
     thinking?: string,
-    thoughtSignature?: string
+    thoughtSignature?: string,
+    providerSteps?: ProviderSteps
   ): void {
     const parts: ContentPart[] = [];
     const hasToolCalls = Boolean(toolCalls && toolCalls.length > 0);
@@ -111,6 +112,7 @@ export class AgentContext {
       role: "assistant",
       content: parts.length > 0 ? parts : text,
       thoughtSignature,
+      ...(providerSteps ? { providerSteps } : {}),
     });
 
     if (thoughtSignature) {
@@ -158,7 +160,6 @@ export class AgentContext {
       }
     }
     next.thoughtSignatures = [...this.thoughtSignatures];
-    next.cachedContentId = this.cachedContentId;
     return next;
   }
 

package/src/agent/delegation.ts

@@ -140,10 +140,6 @@ export const SUBAGENT_SUBSCRIBE_TTL_MS = 5 * 60 * 1000;
 /** Last-write wall-clock per canonical trackingId (drives TTL; reads do not extend it). */
 const traceTouchedAt = new Map<string, number>();
 
-function canonicalOf(trace: SubAgentTrace): string {
-  return trace.trackingId;
-}
-
 function deleteTraceByCanonical(canonical: string): void {
   for (const [key, t] of [...subagentTraces]) {
     if (t.trackingId === canonical) subagentTraces.delete(key);
@@ -381,10 +377,6 @@ function readBudget(parentAgent: Agent): Budget | undefined {
   return (parentAgent as unknown as { budget?: Budget }).budget;
 }
 
-function readBudgetState(parentAgent: Agent): BudgetState | undefined {
-  return (parentAgent as unknown as { budgetState?: BudgetState }).budgetState;
-}
-
 function ensureBudgetState(parentAgent: Agent): BudgetState {
   const host = parentAgent as unknown as { budgetState?: BudgetState };
   if (!host.budgetState) {
@@ -711,7 +703,7 @@ export function createSubagentSpawnTool(parentAgent: Agent): ToolDefinition {
               try { (parentAgent as any).persistNow?.(); } catch {}
             };
             // Unified live worker state machine (shared with fixed workers).
-            const { onWorkerTurn, onWorkerDelta, attachToStream } = createLiveWorker(trace, trackingId, displayId, {
+            const { onWorkerTurn, attachToStream } = createLiveWorker(trace, trackingId, displayId, {
               trim: (t) => trimTraceSteps(t),
               touch: (id) => touchTrace(id),
               notify: (id) => notifyTrace(id),