agent-accelerator 0.1.0 → 0.2.0

package/src/providers.ts

@@ -0,0 +1,490 @@
+/**
+ * Canonical provider contract for Agent Accelerator.
+ *
+ * This module is provider-agnostic: it defines how canonical Agent Accelerator
+ * capabilities map onto provider concepts WITHOUT containing any
+ * provider-specific HTTP, endpoints, headers, or response parsing. Those live
+ * in `src/providers/<provider>.ts` (e.g. `src/providers/google.ts`).
+ *
+ * Rule: OpenAI, OpenRouter, and future providers must be addable here without
+ * redesigning this abstraction — only new per-provider mappers/adapters.
+ */
+import type { CacheConfig, ServiceTier, ThinkingLevel } from "./types/core.ts";
+
+/** Classification of a canonical capability on a given provider. */
+export type ProviderCapabilityStatus =
+  | "NATIVE"
+  | "TRANSLATED"
+  | "AUTOMATIC"
+  | "EMULATED"
+  | "UNSUPPORTED";
+
+/**
+ * Single warning mechanism for provider capability differences.
+ *
+ * There is no pre-existing logger in `src/` (only CLI logs in
+ * `update-models.ts`), so this `console.warn` line IS the mechanism — do not
+ * introduce a second one. Used when a requested capability cannot be applied
+ * as-is (e.g. Google explicit cache retention) so it never silently
+ * disappears.
+ *
+ * Warnings are deduped per provider+capability+requested: agent loops call
+ * mappers once per turn, and repeating the same warning every turn is noise.
+ * A repeated identical request logs once per process.
+ *
+ * @example `emitProviderWarning({ provider: "google", capability: "cache retention", requested: "high", reason: "...", fallback: "..." })`
+ */
+const emittedWarnings = new Set<string>();
+
+export function emitProviderWarning(options: {
+  provider: string;
+  capability: string;
+  requested?: string;
+  reason: string;
+  fallback: string;
+}): void {
+  const key = `${options.provider}::${options.capability}::${options.requested ?? ""}`;
+  if (emittedWarnings.has(key)) return;
+  emittedWarnings.add(key);
+  const requested = options.requested ? ` (requested: "${options.requested}")` : "";
+  // Leading newline: warnings fire at the start of a turn's request build,
+  // when the previous turn's streamed text may have left the terminal cursor
+  // mid-line. Without it the warning glues onto streamed output.
+  console.warn(
+    `\n[Agent Accelerator] WARNING [${options.provider}] ${options.capability}${requested}: ${options.reason} Using ${options.fallback} instead.`
+  );
+}
+
+/** Clears deduped-warning state (mainly for tests). */
+export function clearEmittedWarnings(): void {
+  emittedWarnings.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Per-session provider routing state (canonical conversation stays agnostic)
+// ---------------------------------------------------------------------------
+
+interface SessionRoutingState {
+  /** Provider id that served the last turn in this session. */
+  lastProvider?: string;
+  /** True once a session mixed providers and must stay on explicit history. */
+  mixedProviders?: boolean;
+}
+
+const sessionRouting = new Map<string, SessionRoutingState>();
+
+/** Records which provider served a turn so adapters can detect switches. */
+export function noteProviderTurn(sessionId: string | undefined, providerId: string): void {
+  if (!sessionId) return;
+  const state = sessionRouting.get(sessionId) ?? {};
+  if (state.lastProvider && state.lastProvider !== providerId) {
+    state.mixedProviders = true;
+  }
+  state.lastProvider = providerId;
+  sessionRouting.set(sessionId, state);
+}
+
+/** Returns the provider id that served the previous turn in this session. */
+export function lastProviderFor(sessionId: string | undefined): string | undefined {
+  if (!sessionId) return undefined;
+  return sessionRouting.get(sessionId)?.lastProvider;
+}
+
+/** True when this session already mixed providers (history must be explicit). */
+export function isMixedProviderSession(sessionId: string | undefined): boolean {
+  if (!sessionId) return false;
+  return sessionRouting.get(sessionId)?.mixedProviders === true;
+}
+
+/** Clears routing state for a session (mainly for tests). */
+export function clearSessionRouting(sessionId?: string): void {
+  if (sessionId) sessionRouting.delete(sessionId);
+  else sessionRouting.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Canonical capability mappers (pure, no I/O)
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps a canonical ThinkingLevel onto Google Interactions `thinking_level`.
+ * Google values: minimal|low|medium|high (no off switch, no xhigh).
+ */
+export function mapThinkingLevelToGoogle(
+  level: ThinkingLevel | string | undefined
+): { thinkingLevel?: string } {
+  if (!level) return {};
+  const norm = String(level).toLowerCase().trim();
+  if (norm === "dynamic") return {}; // server dynamic default (NATIVE)
+  if (norm === "none") {
+    emitProviderWarning({
+      provider: "google",
+      capability: "thinking level",
+      requested: String(level),
+      reason: "the Interactions API has no disable/off level — thought steps are always present.",
+      fallback: "the server default (omit thinking_level)",
+    });
+    return {};
+  }
+  if (norm === "xhigh") {
+    emitProviderWarning({
+      provider: "google",
+      capability: "thinking level",
+      requested: String(level),
+      reason: "Google's maximum thinking level is high.",
+      fallback: "thinking_level high",
+    });
+    return { thinkingLevel: "high" };
+  }
+  if (norm === "minimal" || norm === "low" || norm === "medium" || norm === "high") {
+    return { thinkingLevel: norm };
+  }
+  return {};
+}
+
+/** Maps canonical ServiceTier onto Google `service_tier` (omit = standard). */
+export function mapServiceTierToGoogle(tier: ServiceTier | undefined): "flex" | "priority" | undefined {
+  if (tier === "flex" || tier === "priority") return tier;
+  return undefined;
+}
+
+/**
+ * Maps a canonical ThinkingLevel onto OpenRouter Chat Completions
+ * `reasoning.effort`.
+ *
+ * Completions documents `reasoning_effort: xhigh|high|medium|low|minimal|none`
+ * (parameters.md) and live probes accept `xhigh` verbatim (`03`), so — unlike
+ * the discontinued Responses skin, which clamped `xhigh` — everything passes
+ * through. `dynamic` omits (server default).
+ */
+export function mapThinkingLevelToOpenRouterChat(
+  level: ThinkingLevel | string | undefined
+): { effort?: string } {
+  if (!level) return {};
+  const norm = String(level).toLowerCase().trim();
+  if (norm === "dynamic") return {}; // server default
+  if (
+    norm === "none" ||
+    norm === "minimal" ||
+    norm === "low" ||
+    norm === "medium" ||
+    norm === "high" ||
+    norm === "xhigh"
+  ) {
+    return { effort: norm };
+  }
+  return {};
+}
+
+/**
+ * Maps a canonical ThinkingLevel onto OpenRouter Responses `reasoning.effort`.
+ * Documented efforts: minimal|low|medium|high (server default medium).
+ * Wire-validated extras: `none` disables reasoning output; `xhigh` is echoed
+ * but is NOT a documented level, so it clamps to `high` with a warning.
+ *
+ * @deprecated The Responses skin is discontinued for OpenRouter
+ * (`src/providers/openrouter-responses.ts`, archived). Use
+ * {@link mapThinkingLevelToOpenRouterChat} with the stable Chat Completions
+ * transport instead.
+ */
+export function mapThinkingLevelToOpenRouter(
+  level: ThinkingLevel | string | undefined
+): { effort?: string } {
+  if (!level) return {};
+  const norm = String(level).toLowerCase().trim();
+  if (norm === "dynamic") return {}; // server default (medium)
+  if (norm === "none") return { effort: "none" };
+  if (norm === "xhigh") {
+    emitProviderWarning({
+      provider: "openrouter",
+      capability: "thinking level",
+      requested: String(level),
+      reason: "OpenRouter documents reasoning efforts up to high.",
+      fallback: "reasoning effort high",
+    });
+    return { effort: "high" };
+  }
+  if (norm === "minimal" || norm === "low" || norm === "medium" || norm === "high") {
+    return { effort: norm };
+  }
+  return {};
+}
+
+/** Maps canonical ServiceTier onto OpenRouter `service_tier` (omit = auto). */
+export function mapServiceTierToOpenRouter(tier: ServiceTier | undefined): "flex" | "priority" | undefined {
+  if (tier === "flex" || tier === "priority") return tier;
+  return undefined;
+}
+
+/**
+ * Applies canonical cache config for OpenRouter. Session affinity flows via
+ * top-level body `session_id` (sent by the adapter) plus the `x-session-id`
+ * header fallback; there is no retention body primitive, so explicit
+ * retention/cachedContentId are UNSUPPORTED: warn and drop.
+ */
+export function applyCacheForOpenRouter(
+  cache: CacheConfig | undefined,
+  modelRef: string
+): void {
+  if (!cache) return;
+  if (cache.retention && cache.retention !== "implicit") {
+    emitProviderWarning({
+      provider: "openrouter",
+      capability: "cache retention",
+      requested: `${cache.retention} (${modelRef})`,
+      reason: "OpenRouter documents no retention control on the stable Chat Completions endpoint.",
+      fallback: "default gateway caching with headers-only session affinity (no retention payload is sent)",
+    });
+  }
+  if (cache.cachedContentId) {
+    emitProviderWarning({
+      provider: "openrouter",
+      capability: "explicit cached content",
+      requested: cache.cachedContentId,
+      reason: "cached content references do not exist on the Responses API.",
+      fallback: "full-history sends instead (cachedContentId is ignored)",
+    });
+  }
+}
+
+/**
+ * Applies canonical cache config for custom OpenAI-compatible endpoints.
+ * Affinity is headers-only (`x-session-id`): unknown body properties make
+ * strict endpoints (groq, ollama, …) fail, so nothing cache-related is ever
+ * placed in the body. Explicit retention/cachedContentId are UNSUPPORTED:
+ * warn and drop.
+ */
+export function applyCacheForCustom(
+  prefix: string,
+  cache: CacheConfig | undefined,
+  modelRef: string
+): void {
+  if (!cache) return;
+  if (cache.retention && cache.retention !== "implicit") {
+    emitProviderWarning({
+      provider: prefix,
+      capability: "cache retention",
+      requested: `${cache.retention} (${modelRef})`,
+      reason: "custom OpenAI-compatible endpoints define no retention control, and strict endpoints reject unknown body properties.",
+      fallback: "default caching with headers-only session affinity (no retention payload is sent)",
+    });
+  }
+  if (cache.cachedContentId) {
+    emitProviderWarning({
+      provider: prefix,
+      capability: "explicit cached content",
+      requested: cache.cachedContentId,
+      reason: "cached content references do not exist on OpenAI-compatible endpoints.",
+      fallback: "full-history sends instead (cachedContentId is ignored)",
+    });
+  }
+}
+
+/** OpenRouter Chat Completions `tool_choice` wire values. */
+export type OpenRouterChatToolChoice =
+  | "auto"
+  | "none"
+  | "required"
+  | { type: "function"; function: { name: string } };
+
+/**
+ * Maps canonical toolChoice onto Chat Completions `tool_choice`.
+ * `auto` is the server default (omitted); `required` is documented
+ * (parameters.md) and accepted live (`05`); a function pin passes through
+ * verbatim. Note the shape differs from the discontinued Responses skin
+ * (`{type:function,name}`): completions nests the name under `function`.
+ */
+export function mapToolChoiceToOpenRouterChat(
+  choice: "auto" | "none" | "required" | { type: "function"; function: { name: string } } | undefined
+): OpenRouterChatToolChoice | undefined {
+  if (!choice || choice === "auto") return undefined;
+  if (choice === "none" || choice === "required") return choice;
+  const name = choice.function?.name;
+  if (name) return { type: "function", function: { name } };
+  return undefined;
+}
+
+/** OpenRouter Responses `tool_choice` wire values.
+ * @deprecated Discontinued skin; see {@link OpenRouterChatToolChoice}. */
+export type OpenRouterToolChoice = "auto" | "none" | "required" | { type: "function"; name: string };
+
+/**
+ * Maps canonical toolChoice onto OpenRouter Responses `tool_choice`.
+ * `auto` is the server default (omitted); `required` is natively supported
+ * (validated); a function pin passes through verbatim.
+ */
+export function mapToolChoiceToOpenRouter(
+  choice: "auto" | "none" | "required" | { type: "function"; function: { name: string } } | undefined
+): OpenRouterToolChoice | undefined {
+  if (!choice || choice === "auto") return undefined;
+  if (choice === "none" || choice === "required") return choice;
+  const name = choice.function?.name;
+  if (name) return { type: "function", name };
+  return undefined;
+}
+
+/**
+ * Maps a canonical ThinkingLevel onto OpenAI Responses `reasoning.effort`.
+ * Documented efforts: none|minimal|low|medium|high|xhigh|max (server default
+ * medium). Unlike OpenRouter (which clamps xhigh), OpenAI documents xhigh
+ * natively so it passes through verbatim. `dynamic` omits (server default).
+ */
+export function mapThinkingLevelToOpenAI(
+  level: ThinkingLevel | string | undefined
+): { effort?: string } {
+  if (!level) return {};
+  const norm = String(level).toLowerCase().trim();
+  if (norm === "dynamic") return {}; // server default
+  if (
+    norm === "none" ||
+    norm === "minimal" ||
+    norm === "low" ||
+    norm === "medium" ||
+    norm === "high" ||
+    norm === "xhigh"
+  ) {
+    return { effort: norm };
+  }
+  return {};
+}
+
+/** Maps canonical ServiceTier onto OpenAI `service_tier` (omit = auto). */
+export function mapServiceTierToOpenAI(tier: ServiceTier | undefined): "flex" | "priority" | undefined {
+  if (tier === "flex" || tier === "priority") return tier;
+  return undefined;
+}
+
+/**
+ * Applies canonical cache config for OpenAI. Session affinity flows via
+ * `prompt_cache_key` (handled by the adapter); explicit retention control
+ * lives in `prompt_cache_options` (gpt-5.6+ explicit breakpoints) which is
+ * out of scope for the most-important subset, so retention/cachedContentId
+ * are UNSUPPORTED: warn and drop. `prompt_cache_retention` is deprecated.
+ */
+export function applyCacheForOpenAI(
+  cache: CacheConfig | undefined,
+  modelRef: string
+): void {
+  if (!cache) return;
+  if (cache.retention && cache.retention !== "implicit") {
+    emitProviderWarning({
+      provider: "openai",
+      capability: "cache retention",
+      requested: `${cache.retention} (${modelRef})`,
+      reason: "the native Responses adapter uses prompt_cache_key affinity only; explicit retention modes are out of scope.",
+      fallback: "default caching with prompt_cache_key affinity (no retention payload is sent)",
+    });
+  }
+  if (cache.cachedContentId) {
+    emitProviderWarning({
+      provider: "openai",
+      capability: "explicit cached content",
+      requested: cache.cachedContentId,
+      reason: "cached content references do not exist on the Responses API.",
+      fallback: "full-history sends instead (cachedContentId is ignored)",
+    });
+  }
+}
+
+/** OpenAI Responses `tool_choice` wire values (most-important subset). */
+export type OpenAIToolChoice = "auto" | "none" | "required" | { type: "function"; name: string };
+
+/**
+ * Maps canonical toolChoice onto OpenAI Responses `tool_choice`.
+ * `auto` is the server default (omitted); `required` forces one or more
+ * calls; a function pin passes through verbatim. Built-in/MCP/allowed_tools
+ * variants are out of scope and never emitted.
+ */
+export function mapToolChoiceToOpenAI(
+  choice: "auto" | "none" | "required" | { type: "function"; function: { name: string } } | undefined
+): OpenAIToolChoice | undefined {
+  if (!choice || choice === "auto") return undefined;
+  if (choice === "none" || choice === "required") return choice;
+  const name = choice.function?.name;
+  if (name) return { type: "function", name };
+  return undefined;
+}
+
+/**
+ * Applies canonical cache config for Google. The Interactions API supports
+ * implicit/automatic caching ONLY — there is no cache payload to send.
+ * Explicit retention/cachedContentId are UNSUPPORTED: warn and drop.
+ */
+export function applyCacheForGoogle(
+  cache: CacheConfig | undefined,
+  modelRef: string
+): void {
+  if (!cache) return;
+  if (cache.retention && cache.retention !== "implicit") {
+    emitProviderWarning({
+      provider: "google",
+      capability: "cache retention",
+      requested: `${cache.retention} (${modelRef})`,
+      reason: "the Interactions API does not support user-defined explicit cache retention.",
+      fallback: "Google automatic/implicit caching (no cache payload is sent)",
+    });
+  }
+  if (cache.cachedContentId) {
+    emitProviderWarning({
+      provider: "google",
+      capability: "explicit cached content",
+      requested: cache.cachedContentId,
+      reason: "cachedContents resources do not exist on the Interactions API.",
+      fallback: "stateful interaction chaining / stateless history instead (cachedContentId is ignored)",
+    });
+  }
+}
+
+/** Normalized tool-choice mode shared by provider adapters. */
+export type CanonicalToolChoiceMode = "auto" | "any" | "none";
+
+/**
+ * Normalizes canonical toolChoice into a provider-neutral mode + optional
+ * pinned tool name. Google renders this as
+ * `{ allowed_tools: { mode, tools? } }` in its own adapter.
+ */
+export function normalizeToolChoice(
+  choice: "auto" | "none" | "required" | { type: "function"; function: { name: string } } | undefined,
+  availableToolNames: string[]
+): { mode: CanonicalToolChoiceMode; tools?: string[] } | undefined {
+  if (!choice) return undefined;
+  if (typeof choice === "string") {
+    if (choice === "auto") return undefined; // server default
+    if (choice === "none") return { mode: "none" };
+    if (choice === "required") {
+      return availableToolNames.length > 0 ? { mode: "any", tools: availableToolNames } : { mode: "any" };
+    }
+    return undefined;
+  }
+  const name = choice.function?.name;
+  if (name) return { mode: "any", tools: [name] };
+  return { mode: "any" };
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Reconstructs tool arguments from streamed chunks.
+ *
+ * Wire behavior varies across providers: some send the complete JSON in a
+ * single delta after an empty initial payload, others genuinely split
+ * partials across start + deltas. Concatenating blindly can yield
+ * `"{}{...}"` (unparseable), so candidates are tried in order and the first
+ * chunk that parses to a plain object wins.
+ *
+ * @example `parseStreamedToolArguments("{}", '{"location":"Paris"}')`
+ */
+export function parseStreamedToolArguments(startText: string, deltaText: string): Record<string, unknown> {
+  const candidates = [startText + deltaText, deltaText, startText].filter((c) => c && c.trim());
+  for (const candidate of candidates) {
+    try {
+      const parsed: unknown = JSON.parse(candidate);
+      if (isPlainObject(parsed)) return parsed;
+    } catch {
+      // try next candidate
+    }
+  }
+  return { raw: startText + deltaText };
+}

package/src/streaming/sse-parser.ts

@@ -56,8 +56,9 @@ export class SSEParser {
         // Comment / ping
         continue;
       } else if (line.startsWith("data:")) {
-        const val = line.slice(5);
-        this.currentData.push(val.startsWith(" ") ? val.slice(1) : val.trimStart());
+        // Per WHATWG SSE, strip exactly one leading space — never tabs or
+        // further whitespace, so indented code/JSON payloads survive intact.
+        this.currentData.push(line.startsWith("data: ") ? line.slice(6) : line.slice(5));
       } else if (line.startsWith("event:")) {
         const val = line.slice(6);
         this.currentEvent = (val.startsWith(" ") ? val.slice(1) : val).trim();
@@ -76,8 +77,9 @@ export class SSEParser {
     const messages: SSEMessage[] = [];
     // S7: flush pending currentData first, then treat remaining buffer as final lines (avoid duplication)
     if (this.buffer.trim() !== "") {
-      // Feed remaining buffer as if terminated
-      const pending = this.feed(this.buffer + "\n\n");
+      // Terminate the leftover buffer in place: feed() appends its argument
+      // to this.buffer, so re-feeding the buffer itself would duplicate it.
+      const pending = this.feed("\n\n");
       messages.push(...pending);
       this.buffer = "";
     }

package/src/tools/executor.ts

@@ -36,7 +36,8 @@ function integerOption(value: number | string | undefined): number | undefined {
   return parsed === undefined ? undefined : Math.floor(parsed);
 }
 
-function normalizeToolName(name: string): string {
+/** Normalizes a tool name for case/format-insensitive matching (shared with delegation grants). */
+export function normalizeToolName(name: string): string {
   return name
     .trim()
     .replace(/^(?:functions?|tools?)\./i, "")
@@ -99,6 +100,7 @@ class Semaphore {
     resolve: (release: () => void) => void;
     reject: (error: Error) => void;
     signal?: AbortSignal;
+    onAbort?: () => void;
   }> = [];
 
   constructor(private readonly limit: number) {}
@@ -110,13 +112,19 @@ class Semaphore {
       return Promise.resolve(() => this.release());
     }
     return new Promise((resolve, reject) => {
-      const waiter = { resolve, reject, signal };
-      this.waiters.push(waiter);
+      const waiter: {
+        resolve: (release: () => void) => void;
+        reject: (error: Error) => void;
+        signal?: AbortSignal;
+        onAbort?: () => void;
+      } = { resolve, reject, signal };
       const onAbort = () => {
         const index = this.waiters.indexOf(waiter);
         if (index >= 0) this.waiters.splice(index, 1);
         reject(new Error("Tool execution aborted"));
       };
+      waiter.onAbort = onAbort;
+      this.waiters.push(waiter);
       signal?.addEventListener("abort", onAbort, { once: true });
     });
   }
@@ -130,6 +138,9 @@ class Semaphore {
         continue;
       }
       this.active++;
+      // The waiter is leaving the queue: drop its abort listener so long-lived
+      // session signals don't accumulate one listener per queued tool call.
+      if (waiter.onAbort) waiter.signal?.removeEventListener("abort", waiter.onAbort);
       waiter.resolve(() => this.release());
       return;
     }
@@ -306,9 +317,11 @@ export async function executeToolCalls(
       }
 
       const configuredTries = integerOption(toolDef.maxTries);
-      // A positive value is the total attempt count.  0/omitted deliberately
-      // means there is no configured retry limit for transient failures.
-      const maxAttempts = configuredTries && configuredTries > 0 ? configuredTries : Number.POSITIVE_INFINITY;
+      // A positive value is the total attempt count. 0/omitted falls back to
+      // a bounded default: an unbounded retry loop on a persistently failing
+      // dependency (e.g. steady 503/429) would hang the agent loop forever,
+      // so callers opt into more attempts explicitly via maxTries.
+      const maxAttempts = configuredTries && configuredTries > 0 ? configuredTries : 3;
       const timeoutMs = numericOption(toolDef.timeoutMs);
       // Telemetry starts when the tool body is about to run, excluding queue
       // wait and schema validation. Retries/backoff remain part of this call.

package/src/tools/schema.ts

@@ -65,7 +65,7 @@ export function zodToJsonSchema(schema: unknown): Record<string, unknown> {
  *
  * @example `const clean = cleanJsonSchema(rawSchema);`
  */
-export function cleanJsonSchema(schema: any, rootDefs?: Record<string, any>): Record<string, unknown> {
+export function cleanJsonSchema(schema: any, rootDefs?: Record<string, any>, seenRefs: Set<string> = new Set()): Record<string, unknown> {
   if (typeof schema !== "object" || schema === null) {
     return schema;
   }
@@ -78,8 +78,18 @@ export function cleanJsonSchema(schema: any, rootDefs?: Record<string, any>): Re
     if (target) {
       // Merge sibling props (e.g. description) with target
       const { $ref, ...siblings } = schema;
-      const resolved = cleanJsonSchema(target, defs);
-      return { ...resolved, ...cleanJsonSchema(siblings, defs) } as any;
+      if (seenRefs.has(refName)) {
+        // Recursive schema (AST nodes, trees, nested categories): stop
+        // expanding to avoid overflowing the stack; keep siblings.
+        return { type: "object", ...cleanJsonSchema(siblings, defs, seenRefs) } as any;
+      }
+      seenRefs.add(refName);
+      try {
+        const resolved = cleanJsonSchema(target, defs, seenRefs);
+        return { ...resolved, ...cleanJsonSchema(siblings, defs, seenRefs) } as any;
+      } finally {
+        seenRefs.delete(refName);
+      }
     }
   }
   const { $schema, $defs, definitions, ...rest } = schema;
@@ -94,22 +104,22 @@ export function cleanJsonSchema(schema: any, rootDefs?: Record<string, any>): Re
   if (rest.properties && typeof rest.properties === "object") {
     const cleanedProps: Record<string, unknown> = {};
     for (const [key, value] of Object.entries(rest.properties)) {
-      cleanedProps[key] = cleanJsonSchema(value, defs);
+      cleanedProps[key] = cleanJsonSchema(value, defs, seenRefs);
     }
     rest.properties = cleanedProps;
   }
 
   if (rest.items) {
-    rest.items = cleanJsonSchema(rest.items, defs);
+    rest.items = cleanJsonSchema(rest.items, defs, seenRefs);
   }
-  if (rest.anyOf) rest.anyOf = (rest.anyOf as any[]).map((v: any) => cleanJsonSchema(v, defs));
-  if (rest.oneOf) rest.oneOf = (rest.oneOf as any[]).map((v: any) => cleanJsonSchema(v, defs));
-  if (rest.allOf) rest.allOf = (rest.allOf as any[]).map((v: any) => cleanJsonSchema(v, defs));
-  if (rest.prefixItems) rest.prefixItems = (rest.prefixItems as any[]).map((v: any) => cleanJsonSchema(v, defs));
+  if (rest.anyOf) rest.anyOf = (rest.anyOf as any[]).map((v: any) => cleanJsonSchema(v, defs, seenRefs));
+  if (rest.oneOf) rest.oneOf = (rest.oneOf as any[]).map((v: any) => cleanJsonSchema(v, defs, seenRefs));
+  if (rest.allOf) rest.allOf = (rest.allOf as any[]).map((v: any) => cleanJsonSchema(v, defs, seenRefs));
+  if (rest.prefixItems) rest.prefixItems = (rest.prefixItems as any[]).map((v: any) => cleanJsonSchema(v, defs, seenRefs));
   // Recursively clean nested $ref inside properties that were not top-level
   for (const k of Object.keys(rest)) {
     if (rest[k] && typeof rest[k] === "object" && !Array.isArray(rest[k]) && (rest[k] as any).$ref) {
-      rest[k] = cleanJsonSchema(rest[k], defs);
+      rest[k] = cleanJsonSchema(rest[k], defs, seenRefs);
     }
   }
   return rest;
@@ -167,7 +177,7 @@ function inferZodPropertyType(prop: any): Record<string, unknown> {
   }
   if (tn.includes("literal")) {
     const val = unwrapped._def?.value;
-    return { type: typeof val, enum: [val], ...(description ? { description } : {}) };
+    return { type: val === null ? "null" : typeof val, enum: [val], ...(description ? { description } : {}) };
   }
   if (tn.includes("array") || tn === "zodarray") {
     const elem = unwrapped._def?.type || unwrapped._def?.element || unwrapped._def?.valueType || {};

package/src/types/agent.ts

@@ -5,7 +5,7 @@ import type {
   CacheConfig,
   ServiceTier,
 } from "./core.ts";
-import type { ModelProviderInstance } from "../ai-sdk/registry.ts";
+import type { ModelProviderInstance } from "../providers/registry.ts";
 import type { Agent } from "../agent/agent.ts";
 
 /** Configuration used to construct an {@link Agent}. */
@@ -34,6 +34,13 @@ export interface AgentConfig {
   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.
+   */
+  bypassInputFileModality?: boolean;
   /** Stable conversation/cache session ID. */
   sessionId?: string;
   /** Headers merged into every provider request. */

package/src/types/core.ts

@@ -49,7 +49,7 @@ export interface CacheConfig {
    */
   cachedContentId?: string;
   /**
-   * Session ID for cache affinity routing (e.g. x-session-id, x-opencode-session)
+   * Session ID for cache affinity routing (e.g. x-session-id)
    */
   sessionId?: string;
   /**