agent-accelerator 0.5.0 → 0.5.2

package/src/session/store.ts

@@ -24,7 +24,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { Message, ContentPart } from "../types/message.ts";
-import type { TokenUsage, CacheConfig, ServiceTier } from "../types/core.ts";
+import { CACHE_OPTIONS, type TokenUsage, type CacheOption, type ServiceTier } from "../types/core.ts";
 import type { ModelSpec } from "../types/model.ts";
 import type { AgentResponse } from "../types/response.ts";
 import { base64ToBytes, bytesToBase64 } from "../utils/base64.ts";
@@ -68,12 +68,11 @@ export interface PersistedAgentSession {
   model: string;
   subagentModel?: string;
   thinkingLevel?: string;
-  cache?: CacheConfig;
+  cache?: CacheOption;
   /** Legacy read-only: pre-compact files duplicated base instructions here;
   * no longer written (`systemPrompt` already embeds them). */
   instructions?: string;
   systemPrompt?: string;
-  cachedContentId?: string;
   messages: Message[];
   totals?: SessionTotals;
   /** Parent session this snapshot was spawned from, when applicable. */
@@ -283,11 +282,11 @@ export interface SessionAgentLike {
   modelStringOrSpec: unknown;
   subagentModel?: unknown;
   thinkingConfig?: { level?: string };
-  cacheConfig?: CacheConfig;
+  cache?: CacheOption;
   instructions?: string;
   parentSessionId?: unknown;
   subagentTraces?: Record<string, PersistedSubAgentTrace>;
-  context: { systemPrompt?: string; messages: Message[]; cachedContentId?: string };
+  context: { systemPrompt?: string; messages: Message[] };
 }
 
 function snapshotSubagents(traces: Record<string, PersistedSubAgentTrace> | undefined): Record<string, PersistedSubAgentTrace> | undefined {
@@ -416,17 +415,6 @@ export function buildSessionData(agent: SessionAgentLike, telemetry?: SessionTel
     typeof (agent as any)?.parentSessionId === "string" ? (agent as any).parentSessionId as string : undefined;
   const subagents = snapshotSubagents((agent as any)?.subagentTraces as Record<string, PersistedSubAgentTrace> | undefined);
   const messages = inlineBinaryMedia(stripRedundantRawArguments(agent.context.messages));
-  // `cache.sessionId` echoes the top-level `sessionId` (affinity alias): drop
-  // it from the file when identical so it isn't stored twice. Readers still
-  // accept legacy files carrying it (`importSession`, loop fallbacks).
-  const cacheForFile = (() => {
-    if (!agent.cacheConfig) return undefined;
-    if (agent.cacheConfig.sessionId === agent.sessionId) {
-      const { sessionId: _dropped, ...rest } = agent.cacheConfig;
-      return Object.keys(rest).length > 0 ? rest : undefined;
-    }
-    return agent.cacheConfig;
-  })();
   // Field order is the on-disk layout contract: identity → config →
   // systemPrompt → totals → messages → lineage/traces. `instructions` is
   // intentionally never written: `systemPrompt` already embeds it (plus the
@@ -438,9 +426,8 @@ export function buildSessionData(agent: SessionAgentLike, telemetry?: SessionTel
     model,
     ...(subagentModel ? { subagentModel: String(subagentModel) } : {}),
     ...(agent.thinkingConfig?.level ? { thinkingLevel: agent.thinkingConfig.level as string } : {}),
-    ...(cacheForFile ? { cache: cacheForFile } : {}),
+    ...(agent.cache ? { cache: agent.cache } : {}),
     ...(agent.context.systemPrompt ? { systemPrompt: agent.context.systemPrompt } : {}),
-    ...(agent.context.cachedContentId ? { cachedContentId: agent.context.cachedContentId } : {}),
     ...(totals ? { totals } : {}),
     messages,
     ...(parentSessionId ? { parentSessionId } : {}),
@@ -511,6 +498,14 @@ export interface SessionLimits {
 /** Marker for a structurally valid payload that exceeds the configured limits. */
 const OVER_LIMIT = Symbol("session-over-limit");
 
+// Reads a stored `cache` field: a current string value, or a pre-0.5.1 `{ retention }` object (short=5m, medium=1h, long=12h); in: a parsed session file, out: `PersistedAgentSession.cache`.
+function toCacheOption(raw: unknown): CacheOption | undefined {
+  if (typeof raw === "string") return (CACHE_OPTIONS as readonly string[]).includes(raw) ? (raw as CacheOption) : undefined;
+  const legacy: Record<string, CacheOption> = { implicit: "implicit", short: "5m", medium: "1h", long: "12h" };
+  const retention = (raw as { retention?: unknown } | null)?.retention;
+  return typeof retention === "string" ? legacy[retention] : undefined;
+}
+
 function parseSession(raw: string, limits?: SessionLimits): PersistedAgentSession | null | typeof OVER_LIMIT {
   const maxMessages = limits?.maxMessages ?? MAX_SESSION_MESSAGES;
   const maxBytes = limits?.maxBytes ?? MAX_SESSION_JSON_BYTES;
@@ -525,8 +520,7 @@ function parseSession(raw: string, limits?: SessionLimits): PersistedAgentSessio
       let model = "";
       let subagentModel: string | undefined;
       let thinkingLevel: string | undefined;
-      let cache: CacheConfig | undefined;
-      let cachedContentId: string | undefined;
+      let cache: CacheOption | undefined;
       let systemPrompt: string | undefined;
       let instructions: string | undefined;
       let parentSessionId: string | undefined;
@@ -540,8 +534,7 @@ function parseSession(raw: string, limits?: SessionLimits): PersistedAgentSessio
           const obj: any = JSON.parse(t);
           if (obj.type === "session") {
             sessionId = obj.id ?? obj.sessionId ?? sessionId;
-            cache = obj.cache ?? cache;
-            cachedContentId = obj.cachedContentId ?? cachedContentId;
+            cache = toCacheOption(obj.cache) ?? cache;
             model = obj.model ?? model;
             thinkingLevel = obj.thinkingLevel ?? thinkingLevel;
             parentSessionId = obj.parentSessionId ?? parentSessionId;
@@ -553,8 +546,7 @@ function parseSession(raw: string, limits?: SessionLimits): PersistedAgentSessio
             subagentModel = obj.id ?? obj.model ?? subagentModel;
           } else if (obj.type === "metrics" || obj.type === "totals") {
             totals = (obj.metrics ?? obj.totals ?? totals) as SessionTotals | undefined;
-            cache = obj.cache ?? cache;
-            cachedContentId = obj.cachedContentId ?? cachedContentId;
+            cache = toCacheOption(obj.cache) ?? cache;
           } else if (obj.type === "modelChange") {
             model = obj.modelId ?? obj.model ?? model;
           } else if (obj.type === "thinkingLevelChange") {
@@ -581,7 +573,6 @@ function parseSession(raw: string, limits?: SessionLimits): PersistedAgentSessio
         ...(cache ? { cache } : {}),
         ...(instructions ? { instructions } : {}),
         ...(systemPrompt ? { systemPrompt } : {}),
-        ...(cachedContentId ? { cachedContentId } : {}),
         messages,
         ...(totals ? { totals } : {}),
         ...(parentSessionId ? { parentSessionId } : {}),
@@ -602,10 +593,9 @@ function parseSession(raw: string, limits?: SessionLimits): PersistedAgentSessio
         model: obj.model ?? "",
         subagentModel: obj.subagentModel,
         thinkingLevel: obj.thinkingLevel ?? obj.thinkingLevelChange,
-        cache: obj.cache,
+        cache: toCacheOption(obj.cache),
         instructions: obj.instructions,
         systemPrompt: obj.context.systemPrompt,
-        cachedContentId: obj.cachedContentId ?? obj.context.cachedContentId,
         messages: obj.context.messages as Message[],
         totals: obj.totals ?? obj.metrics,
         parentSessionId: obj.parentSessionId,
@@ -622,10 +612,9 @@ function parseSession(raw: string, limits?: SessionLimits): PersistedAgentSessio
       model: obj.model ?? "",
       subagentModel: obj.subagentModel,
       thinkingLevel: obj.thinkingLevel,
-      cache: obj.cache,
+      cache: toCacheOption(obj.cache),
       instructions: obj.instructions,
       systemPrompt: obj.systemPrompt,
-      cachedContentId: obj.cachedContentId,
       messages: Array.isArray(obj.messages) ? (obj.messages as Message[]) : [],
       totals: obj.totals,
       parentSessionId: obj.parentSessionId,

package/src/types/agent.ts

@@ -2,7 +2,7 @@ import type { ModelSpec } from "./model.ts";
 import type { ToolDefinition } from "./tool.ts";
 import type {
   ThinkingLevel,
-  CacheConfig,
+  CacheOption,
   ServiceTier,
 } from "./core.ts";
 import type { ModelProviderInstance } from "../providers/registry.ts";
@@ -17,7 +17,7 @@ import type { z } from "zod";
 //   is a deprecated alias (still honored: dynamicSubagents.model ??
 //   subagentModel ?? SUB_AGENT_MODEL ?? parent model).
 // - Session identity: agent-level `sessionId` only (per-run `sessionId`
-//   selects a named session entry; `cache.sessionId` is a deprecated alias).
+//   selects a named session entry).
 // - Model identity: `ModelRef` = string (`provider/model`) | catalog
 //   `ModelSpec` | `ModelProviderInstance` ({ provider, model, apiKey?,
 //   baseUrl? }). Explicit `Agent` config always wins over env; constructing
@@ -96,17 +96,13 @@ export interface AgentConfig {
    * See `normalizeThinkingV2` (re-exported from the root entry).
    */
   thinking?: ThinkingOption;
-  /** Prompt-cache retention and session-affinity settings. */
-  cache?: CacheConfig;
-  /** Provider service tier, when supported. */
-  serviceTier?: ServiceTier;
   /**
-   * When true, `file` parts are converted client-side to `<Document>` Markdown
-   * for models lacking native support (capable models still receive files
-   * natively; unknown models count as capable). Also auto-registers the
-   * `convert_document_to_markdown` tool for path/URL mentions in plain text.
+   * Prompt-cache lifetime: `"implicit" | "5m" | "30m" | "1h" | "12h"`. Omit for the provider default.
+   * A value the provider does not support falls back to its default with one `provider_warning`.
    */
-  bypassInputFileModality?: boolean;
+  cache?: CacheOption;
+  /** Provider service tier, when supported. */
+  serviceTier?: ServiceTier;
   /** Stable conversation/cache session ID. */
   sessionId?: string;
   /** Headers merged into every provider request. */
@@ -186,10 +182,9 @@ export interface AgentConfig {
    */
   telemetry?: { persist?: boolean };
   /**
-   * Local file policy. With `roots` set, every local-path media part and the
-   * built-in `convert_document_to_markdown` tool must resolve inside them
-   * (`[]` denies all local paths). Without it, developer-supplied parts are
-   * unrestricted and the model-callable tool is limited to `process.cwd()`.
+   * Local file policy. With `roots` set, every local-path media part must
+   * resolve inside them (`[]` denies all local paths). Without it, local
+   * paths in message parts are unrestricted.
    */
   fileAccess?: { roots?: string[] };
   /**

package/src/types/core.ts

@@ -24,40 +24,13 @@ export interface ThinkingConfig {
 }
 
 /**
- * Cache retention:
- * - "implicit": automatic prefix caching ($0.00 storage fee, session affinity preserved)
- * - "short": 5 minutes explicit TTL
- * - "medium": 1 hour explicit TTL
- * - "long": 12 hours explicit TTL
- * - undefined: no explicit caching enforced (implicit may still happen)
+ * Prompt-cache lifetime: `"implicit"` (automatic prefix caching) or an explicit TTL. Each provider honours only
+ * the values it supports; others fall back to its default with one warning. Omit for the provider default.
  */
-/** Prompt-cache retention policy. */
-export type CacheRetention = "implicit" | "short" | "medium" | "long";
+export type CacheOption = "implicit" | "5m" | "30m" | "1h" | "12h";
 
-/** Prompt-cache IDs, retention, TTL, and session-affinity settings. */
-export interface CacheConfig {
-  /**
-   * Retention duration:
-   * - "implicit": automatic prefix caching ($0.00 storage fee, no explicit cloud cache entities created)
-   * - "short": 5 minutes TTL
-   * - "medium": 1 hour TTL
-   * - "long": 12 hours TTL
-   * - undefined: no explicit caching enforced (implicit may still happen)
-   */
-  retention?: CacheRetention;
-  /**
-   * Explicit cache ID / reference if using pre-created context cache
-   */
-  cachedContentId?: string;
-  /**
-   * Session ID for cache affinity routing (e.g. x-session-id)
-   */
-  sessionId?: string;
-  /**
-   * Explicit TTL in seconds for created caches (overrides retention mapping)
-   */
-  ttlSeconds?: number;
-}
+/** Every accepted {@link CacheOption}, for runtime validation. */
+export const CACHE_OPTIONS: readonly CacheOption[] = ["implicit", "5m", "30m", "1h", "12h"];
 
 /**
  * Service tier controls — bloatfree: only flex / priority (standard is default, no flag needed)

package/src/types/message.ts

@@ -9,6 +9,9 @@ export interface TextPart {
   thoughtSignature?: string;
 }
 
+/** Detail level a provider spends on one image or video (more detail = more input tokens). Google only; other providers ignore it with a warning. */
+export type MediaResolution = "low" | "medium" | "high" | "ultra_high";
+
 /** Image content accepted as a URL, data, path, or binary value. */
 export interface ImagePart {
   type: "image";
@@ -17,6 +20,8 @@ export interface ImagePart {
    */
   image: string | Uint8Array | ArrayBuffer;
   mimeType?: string;
+  /** Detail level for this image (Google: `low` 280, `medium` 560, `high` 1120, `ultra_high` 2240 tokens). */
+  resolution?: MediaResolution;
 }
 
 /** Audio content accepted as a URL, data, path, or binary value. */
@@ -48,6 +53,8 @@ export interface VideoPart {
    */
   video: string | Uint8Array | ArrayBuffer;
   mimeType?: string;
+  /** Detail level per frame (Google: `low`/`medium` 70, `high` 280 tokens). */
+  resolution?: MediaResolution;
 }
 
 /** Assistant-generated structured tool invocation. */
@@ -100,12 +107,20 @@ export type ContentPart =
 
 export type MessageRole = "system" | "user" | "assistant" | "tool";
 
+/** A provider's raw output steps for one assistant turn, kept to replay history byte-exact (only the tagged provider reads them). */
+export interface ProviderSteps {
+  provider: string;
+  steps: unknown[];
+}
+
 /** Normalized conversation message. */
 export interface Message {
   role: MessageRole;
   content: string | ContentPart[];
   name?: string;
   thoughtSignature?: string;
+  /** Raw provider output steps of an assistant turn (opaque; e.g. Google `steps`). */
+  providerSteps?: ProviderSteps;
 }
 
 /**
@@ -116,5 +131,4 @@ export interface ProviderContext {
   systemPrompt?: string;
   messages: Message[];
   tools?: Record<string, unknown>[];
-  cachedContentId?: string;
 }

package/src/types/model.ts

@@ -1,5 +1,5 @@
-import type { ThinkingConfig, CacheConfig, ServiceTier, TokenUsage } from "./core.ts";
-import type { ProviderContext } from "./message.ts";
+import type { ThinkingConfig, CacheOption, ServiceTier, TokenUsage } from "./core.ts";
+import type { ProviderContext, ProviderSteps } from "./message.ts";
 import type { StandardToolDeclaration, ToolCallRecord } from "./tool.ts";
 import type { AssistantMessageEventStream } from "../streaming/event-stream.ts";
 
@@ -166,7 +166,7 @@ export interface ProviderRequestOptions {
   baseUrl?: string;
   headers?: Record<string, string>;
   thinking?: ThinkingConfig;
-  cache?: CacheConfig;
+  cache?: CacheOption;
   serviceTier?: ServiceTier;
   tools?: StandardToolDeclaration[];
   toolChoice?: "auto" | "none" | "required" | { type: "function"; function: { name: string } };
@@ -226,6 +226,8 @@ export interface ProviderGenerateResult {
   provider: ProviderId;
   raw: ProviderRawData;
   durationMs: number;
+  /** Raw output steps for exact history replay (stored on the assistant message). */
+  providerSteps?: ProviderSteps;
 }
 
 /** Provider contract implemented by native REST transports. */
@@ -244,4 +246,6 @@ export interface Provider {
     context: ProviderContext,
     options?: ProviderRequestOptions
   ): AssistantMessageEventStream;
+  /** True when this call may legitimately run far past the request timeouts (e.g. Google long decode); the loop then leaves timing to the adapter's own per-request timeouts. */
+  isLongRunning?(model: string | ModelSpec, options?: ProviderRequestOptions): boolean;
 }

package/src/types/response.ts

@@ -1,6 +1,7 @@
 import type { TokenUsage } from "./core.ts";
 import type { ToolCallRecord, ToolResultRecord } from "./tool.ts";
 import type { ProviderRawData, ProviderId } from "./model.ts";
+import type { ProviderSteps } from "./message.ts";
 
 /** One logged step inside a sub-agent worker run (surfaced via `agent.track(id)`). */
 export interface SubAgentStep {
@@ -142,6 +143,8 @@ export class AgentResponse {
   readonly durationMs: number;
   readonly raw: ProviderRawData;
   readonly turns: number;
+  /** Raw provider output steps of a single streamed turn (history replay only; not in `toJSON`). */
+  readonly providerSteps?: ProviderSteps;
 
   /**
    * Constructs a normalized response. Agent runs create this automatically;
@@ -167,6 +170,7 @@ export class AgentResponse {
     durationMs: number;
     raw: ProviderRawData;
     turns?: number;
+    providerSteps?: ProviderSteps;
   }) {
     this.text = data.text;
     if (data.parsed !== undefined) (this as { parsed?: unknown }).parsed = data.parsed;
@@ -184,6 +188,7 @@ export class AgentResponse {
     this.durationMs = data.durationMs;
     this.raw = data.raw;
     this.turns = data.turns ?? 1;
+    if (data.providerSteps) this.providerSteps = data.providerSteps;
   }
 
   /** Returns the final assistant text. */

package/src/utils/cache.ts

@@ -1,14 +1,4 @@
-/**
- * Battle-tested cache helper — single source for 80-90% hit rate
- * Based on agent-accel: openai-prompt-cache.ts + applyAnthropicCacheControl
- * - First turn already cache-optimized: system + tools + first user get cache_control
- * - Stable sessionId (64 clamp) + prompt_cache_key ensures affinity
- * - 4 breakpoint cap (Anthropic limit)
- * - Retention mapping: short=5m (no ttl), medium=1h, long=24h (prompt) / 1h (anthropic)
- */
-
-import type { CacheRetention } from "../types/core.ts";
-import { getApiKey } from "./env.ts";
+/** Cache-key clamping and central secret redaction shared by the provider adapters. */
 
 const CACHE_KEY_MAX = 64;
 
@@ -20,132 +10,6 @@ export function clampCacheKey(key?: string): string | undefined {
   return chars.slice(0, CACHE_KEY_MAX).join("");
 }
 
-/** Maps retention to explicit-cache TTL seconds. short=5m, medium=1h, long=12h. Explicit ttlSeconds wins. */
-export function retentionToTtlSeconds(retention?: CacheRetention, ttlSeconds?: number): number | undefined {
-  if (ttlSeconds && ttlSeconds > 0) return Math.floor(ttlSeconds);
-  if (!retention || retention === "implicit") return undefined;
-  if (retention === "short") return 300;
-  if (retention === "medium") return 3600;
-  if (retention === "long") return 43200;
-  return undefined;
-}
-
-/** Maps retention settings to OpenRouter prompt-cache TTL values. */
-export function getPromptCacheRetention(retention?: CacheRetention, supportsLong = true): "24h" | "1h" | undefined {
-  if (!retention || retention === "implicit") return undefined;
-  if (retention === "long" && supportsLong) return "24h";
-  if (retention === "medium" && supportsLong) return "1h";
-  if (retention === "long") return "24h"; // fallback even if supportsLong false, provider may ignore
-  return undefined;
-}
-
-// ============================================================================
-// Explicit Context Caching (Google cachedContents API)
-// ============================================================================
-
-export interface CachedContentMetadata {
-  name: string;
-  displayName?: string;
-  model: string;
-  createTime: string;
-  updateTime: string;
-  expireTime: string;
-  usageMetadata?: {
-    totalTokenCount?: number;
-  };
-}
-
-export interface CreateExplicitCacheOptions {
-  model: string;
-  contents?: any[];
-  systemInstruction?: string;
-  tools?: any[];
-  toolConfig?: any;
-  displayName?: string;
-  ttlSeconds?: number;
-  retention?: CacheRetention;
-  expireTime?: string | Date;
-  apiKey?: string;
-  baseUrl?: string;
-}
-
-/**
- * Creates an explicit cached content object using Google Gemini's cachedContents API.
- * REST: POST https://generativelanguage.googleapis.com/v1beta/cachedContents (key in the `x-goog-api-key` header)
- */
-/**
- * Creates a Google Gemini cachedContents resource through the REST API.
- *
- * @example `const cache = await createExplicitCache({ model: "google/gemini-3.5-flash-lite", contents });`
- */
-export async function createExplicitCache(
-  options: CreateExplicitCacheOptions
-): Promise<CachedContentMetadata> {
-  const apiKey = getApiKey("google", options.apiKey);
-  if (!apiKey) {
-    throw new Error("API key is required to create explicit cache (GEMINI_API_KEY)");
-  }
-
-  const baseUrl = options.baseUrl || "https://generativelanguage.googleapis.com/v1beta";
-  const ttlSeconds = retentionToTtlSeconds(options.retention, options.ttlSeconds) ?? 3600;
-  const ttl = options.expireTime ? undefined : `${ttlSeconds}s`;
-
-  let modelName = options.model;
-  if (!modelName.startsWith("models/")) {
-    modelName = `models/${modelName.replace(/^google\//, "")}`;
-  }
-
-  const payload: Record<string, unknown> = {
-    model: modelName,
-    contents: options.contents ?? [],
-    ...(ttl ? { ttl } : {}),
-    ...(options.expireTime
-      ? { expireTime: options.expireTime instanceof Date ? options.expireTime.toISOString() : options.expireTime }
-      : {}),
-  };
-
-  if (options.displayName) {
-    payload.displayName = options.displayName;
-    (payload as any).display_name = options.displayName;
-  }
-
-  if (options.systemInstruction) {
-    payload.systemInstruction = {
-      parts: [{ text: options.systemInstruction }],
-    };
-    (payload as any).system_instruction = payload.systemInstruction;
-  }
-
-  if (options.tools && options.tools.length > 0) {
-    payload.tools = options.tools;
-  }
-
-  if (options.toolConfig) {
-    payload.toolConfig = options.toolConfig;
-    (payload as any).tool_config = options.toolConfig;
-  }
-
-  // The key travels in a header, never in the URL (URLs end up in proxy and access logs).
-  const url = `${baseUrl}/cachedContents`;
-  const response = await fetch(url, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "x-goog-api-key": apiKey,
-    },
-    body: JSON.stringify(payload),
-  });
-
-  if (!response.ok) {
-    const errorBody = await response.text();
-    throw new Error(
-      `Failed to create explicit cache (${response.status} ${response.statusText}): ${errorBody}`
-    );
-  }
-
-  return (await response.json()) as CachedContentMetadata;
-}
-
 // ---------------------------------------------------------------------------
 // Central redaction helpers (Q-11, temporary home to avoid owner conflicts).
 // Providers must call these instead of maintaining local deny-lists.

package/src/utils/errors.ts

@@ -140,11 +140,8 @@ export function assertModalitiesSupported(
   if (!supported) return;
   const missing = [...needed].filter((k) => !supported.includes(k));
   if (missing.length === 0) return;
-  const docHint = missing.includes("pdf")
-    ? " Documents can be converted client-side with the convert_document_to_markdown tool (bun add @firecrawl/anydoc) or Agent bypassInputFileModality: true."
-    : "";
   const err = new Error(
-    `[${displayModel(providerId, modelId)}] unsupported ${missing.join("+")} input (supports: ${supported.join(", ") || "text"}). Use a capable model or drop the ${missing.join("+")} part.${docHint}`
+    `[${displayModel(providerId, modelId)}] unsupported ${missing.join("+")} input (supports: ${supported.join(", ") || "text"}). Use a capable model or drop the ${missing.join("+")} part.`
   );
   err.name = "AgentAccelProviderError";
   Object.defineProperties(err, {

package/src/utils/headers.ts

@@ -1,5 +1,4 @@
 import type { ProviderId } from "../types/model.ts";
-import type { CacheConfig } from "../types/core.ts";
 import { clampCacheKey } from "./cache.ts";
 
 export function isBrowserRuntime(): boolean {
@@ -24,7 +23,7 @@ export function getPackageVersion(): string {
     const v = (globalThis as any).process?.env?.npm_package_version;
     if (typeof v === "string" && v) return v;
   } catch {}
-  return "0.5.0";
+  return "0.5.2";
 }
 
 function getAgentAccelUserAgent(): string {
@@ -106,19 +105,6 @@ export function setHeaderCaseInsensitive(
 // Thought-signature namespacing (Q-18).
 // ---------------------------------------------------------------------------
 
-/**
- * Tags a captured thought signature with its issuing provider so history
- * builders echo it only on the same provider. Untagged (legacy) signatures
- * echo everywhere for backward compat.
- */
-export function withProviderSignature(
-  sig: string | undefined,
-  provider: string
-): { thoughtSignature?: string; thoughtSignatureProvider?: string } {
-  if (!sig) return {};
-  return { thoughtSignature: sig, thoughtSignatureProvider: provider };
-}
-
 /**
  * Returns true when a stored signature may be echoed on `currentProvider`:
  * untagged (legacy) echoes everywhere, tagged echoes only on a match.
@@ -163,11 +149,10 @@ function stripForBrowser(headers: Record<string, string>): Record<string, string
  * runtimes this returns only CORS-safe attribution headers (OpenRouter
  * `HTTP-Referer` / `X-Title`); session affinity still flows via `providerOptions`
  * (`promptCacheKey`), never via headers.
- * @example `const headers = buildSessionHeaders("google", { sessionId: "session-123" });`
+ * @example `const headers = buildSessionHeaders("google", undefined, "session-123");`
  */
 export function buildSessionHeaders(
   provider: ProviderId | string,
-  cache?: CacheConfig,
   customHeaders?: Record<string, string>,
   explicitSessionId?: string
 ): Record<string, string> {
@@ -183,8 +168,7 @@ export function buildSessionHeaders(
     headers[k] = v;
   }
 
-  const rawSessionId = explicitSessionId || cache?.sessionId;
-  const sessionId = clampCacheKey(rawSessionId);
+  const sessionId = clampCacheKey(explicitSessionId);
   const isFirstClass = FIRST_CLASS.has(provider);
 
   const getHeader = (name: string): string | undefined => {

package/src/utils/retry.ts

@@ -43,7 +43,8 @@ function readRetryAfterMs(error: unknown): number | undefined {
   return Math.min(60_000, secs * 1000);
 }
 
-function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+// Waits `ms`, rejecting with an AbortError as soon as `signal` aborts; in: retry backoff and Google background polling, out: the awaiting caller.
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
   if (ms <= 0) return Promise.resolve();
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => {

package/src/utils/safe-io.ts

@@ -3,11 +3,11 @@
 import type { Message } from "../types/message.ts";
 import { SecurityPolicyError } from "../types/errors.ts";
 
-/** Default cap for one remote media/document download (bytes). */
+/** Default cap for one remote media download (bytes). */
 export const MAX_REMOTE_FETCH_BYTES = 200_000_000;
 
 /**
- * True when a media/document string would be read from the local filesystem
+ * True when a media string would be read from the local filesystem
  * by `normalizeMediaInput` (i.e. it is not a data URL, an http(s) URL, or an
  * embedded base64 payload). Mirrors the classification order used there.
  */