agent-accelerator 0.1.0 → 0.3.0

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

@@ -13,6 +13,8 @@ export interface ExecuteToolsOptions {
   parallel?: boolean;
   signal?: AbortSignal;
   sessionId?: string;
+  /** Forwards live sub-agent deltas (realtime worker thinking/text) to the caller. */
+  onSubagentEvent?: (event: { trackingId: string; delta?: string; thinkingDelta?: string; partialText?: string; partialThinking?: string }) => void;
 }
 
 const DEFAULT_TOOL_CONCURRENCY = 8;
@@ -36,7 +38,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 +102,7 @@ class Semaphore {
     resolve: (release: () => void) => void;
     reject: (error: Error) => void;
     signal?: AbortSignal;
+    onAbort?: () => void;
   }> = [];
 
   constructor(private readonly limit: number) {}
@@ -110,13 +114,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 +140,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;
     }
@@ -222,7 +235,7 @@ async function executeAttempt(
 export async function executeToolCalls(
   options: ExecuteToolsOptions
 ): Promise<ToolResultRecord[]> {
-  const { tools, toolCalls, agentName, parallel = true, signal, sessionId } = options;
+  const { tools, toolCalls, agentName, parallel = true, signal, sessionId, onSubagentEvent } = options;
   const globalSemaphore = new Semaphore(DEFAULT_TOOL_CONCURRENCY);
   const perToolSemaphores = new Map<string, Semaphore>();
 
@@ -271,6 +284,7 @@ export async function executeToolCalls(
         agentName,
         signal,
         sessionId,
+        onSubagentEvent,
       };
 
       // Validate input if Zod schema is provided
@@ -306,9 +320,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,16 +34,31 @@ 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. */
   headers?: Record<string, string>;
-  /** Maximum model/tool turns per run. Defaults to 10. */
+  /** Maximum model/tool turns per run. `0` or omitted means infinite. */
   maxTurns?: number;
   /** Fixed worker agents exposed as delegation tools. */
   subagents?: (Agent | { name: string; description: string; agent: Agent })[];
   /** Clears conversation state before and after every run. */
   stateless?: boolean;
+  /**
+   * Durable session persistence: when set, the session file is rewritten
+   * after every step (user turn, assistant turn, tool batch, sub-agent
+   * step) so a crash loses at most the in-flight step. Pass `{ dir }` for
+   * `sessions/<sessionId>/session.json` layout or `{ file }` for a single
+   * pretty `.session.json` file. Writes are atomic and never fail a turn.
+   */
+  persist?: { dir?: string; file?: string };
 }
 
 /** Developer-configured policy for LLM-spawned dynamic sub-agents. */
@@ -84,4 +99,20 @@ export interface AgentRunOptions {
   onEvent?: (event: import("./response.ts").StreamEvent) => void;
   /** When true, wraps reasoning stream as <think>\n...\n</think>\n\n — no manual isThinking needed. */
   wrapThinking?: boolean;
+  /** Called after every model/tool turn with a turn summary (also drives sub-agent step logs + durable persistence). */
+  onTurn?: (turn: AgentTurnEvent) => void;
+}
+
+/** Turn summary emitted to `AgentRunOptions.onTurn` after each loop turn. */
+export interface AgentTurnEvent {
+  /** 1-based turn count within this run. */
+  turns: number;
+  /** Assistant text produced this turn, if any. */
+  text?: string;
+  /** Reasoning produced this turn, if any. */
+  thinking?: string;
+  /** Tool calls requested this turn, if any. */
+  toolCalls?: Array<{ id: string; name: string }>;
+  /** Tool results executed this turn, if any. */
+  toolResults?: Array<{ id: string; name: string; isError?: boolean }>;
 }

package/src/types/core.ts

@@ -9,7 +9,8 @@ export type ThinkingLevel =
   | "low"
   | "medium"
   | "high"
-  | "xhigh";
+  | "xhigh"
+  | "max";
 
 // Internal normalized config (SDK-internal, not exposed as Agent flag)
 /** Internal normalized reasoning configuration passed to providers. */
@@ -49,7 +50,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;
   /**

package/src/types/message.ts

@@ -64,6 +64,11 @@ export interface ToolCallPart {
    * Optional Gemini thought signature associated with this tool call
    */
   thoughtSignature?: string;
+  /**
+   * Provider pairing identifier (e.g. Responses `call_id`), preserved so
+   * history builders can pair results without inventing ids.
+   */
+  callId?: string;
 }
 
 /** Tool execution result returned to the model context. */

package/src/types/model.ts

@@ -5,10 +5,10 @@ import type { AssistantMessageEventStream } from "../streaming/event-stream.ts";
 
 // ---------------------------------------------------------------------------
 // Provider identity — battle-tested: matches models.dev provider keys
-// Known first-class: google | opencode | openrouter, plus aliases. Allow string for future.
+// Known first-class: google | openrouter | openai, plus aliases. Allow string for future.
 // ---------------------------------------------------------------------------
 /** Supported provider IDs plus arbitrary custom prefixes. */
-export type ProviderId = "google" | "opencode" | "opencode-go" | "openrouter" | "openai" | (string & {});
+export type ProviderId = "google" | "openrouter" | "openai" | (string & {});
 
 // ---------------------------------------------------------------------------
 // Raw models.dev shapes — battle-tested, 1:1 with https://models.dev/api.json
@@ -189,7 +189,7 @@ export interface ProviderGenerateResult {
   durationMs: number;
 }
 
-/** Provider contract implemented by the AI-SDK transport layer. */
+/** Provider contract implemented by native REST transports. */
 export interface Provider {
   id: ProviderId;
   name: string;
@@ -205,8 +205,4 @@ export interface Provider {
     context: ProviderContext,
     options?: ProviderRequestOptions
   ): AssistantMessageEventStream;
-  countTokens(
-    model: string | ModelSpec,
-    context: ProviderContext
-  ): Promise<number>;
 }

package/src/types/provider-payloads.ts

@@ -1,7 +1,7 @@
 /**
  * Provider wire payload and schema types for complete backwards compatibility.
- * All providers use Vercel AI SDK under the hood, but these types allow existing
- * applications and tests to type-check requests and responses seamlessly.
+ * These types allow existing applications and tests to type-check requests
+ * and responses seamlessly.
  */
 
 // ============================================================================
@@ -105,88 +105,6 @@ export interface GoogleGenerateContentResponse {
   modelVersion?: string;
 }
 
-// ============================================================================
-// OpenCode Payload Types
-// ============================================================================
-
-export type OpenCodeReasoningEffort = "low" | "medium" | "high";
-export type OpenCodePromptCacheRetention = "none" | "1h" | "24h";
-
-export interface OpenCodeCacheControl {
-  type: "ephemeral";
-  ttl?: "1h";
-}
-
-export interface OpenCodeUsage {
-  prompt_tokens?: number;
-  completion_tokens?: number;
-  total_tokens?: number;
-  prompt_tokens_details?: {
-    cached_tokens?: number;
-    cache_read?: number;
-    cache_creation?: number;
-  };
-}
-
-export interface OpenCodeChatRequest {
-  model: string;
-  messages: any[];
-  tools?: any[];
-  tool_choice?: any;
-  temperature?: number;
-  top_p?: number;
-  max_tokens?: number;
-  stop?: string | string[];
-  stream?: boolean;
-  reasoning_effort?: OpenCodeReasoningEffort;
-  prompt_cache_retention?: OpenCodePromptCacheRetention;
-  session_id?: string;
-}
-
-export interface OpenCodeChatResponse {
-  id?: string;
-  object?: string;
-  created?: number;
-  model?: string;
-  choices?: Array<{
-    index?: number;
-    message?: any;
-    delta?: any;
-    finish_reason?: string;
-  }>;
-  usage?: OpenCodeUsage;
-}
-
-export interface OpenCodeResponsesInputItem {
-  role: string;
-  content: any;
-  cache_control?: OpenCodeCacheControl;
-}
-
-export interface OpenCodeResponsesOutputItem {
-  id?: string;
-  type?: string;
-  status?: string;
-  content?: any;
-  name?: string;
-  call_id?: string;
-  arguments?: string;
-}
-
-export interface OpenCodeResponsesRequest {
-  model: string;
-  input: OpenCodeResponsesInputItem[];
-  tools?: any[];
-  parameters?: Record<string, unknown>;
-  session_id?: string;
-}
-
-export interface OpenCodeResponsesResponse {
-  id?: string;
-  output?: OpenCodeResponsesOutputItem[];
-  usage?: OpenCodeUsage;
-}
-
 // ============================================================================
 // OpenRouter Payload Types
 // ============================================================================

package/src/types/response.ts

@@ -2,6 +2,19 @@ import type { TokenUsage } from "./core.ts";
 import type { ToolCallRecord, ToolResultRecord } from "./tool.ts";
 import type { ProviderRawData, ProviderId } from "./model.ts";
 
+/** One logged step inside a sub-agent worker run (surfaced via `agent.track(id)`). */
+export interface SubAgentStep {
+  turn: number;
+  type: "assistant" | "tool_call" | "tool_result";
+  name?: string;
+  text?: string;
+  thinking?: string;
+  isError?: boolean;
+  timestamp: number;
+  /** True while the worker is still streaming this step; finalized on turn end. */
+  partial?: boolean;
+}
+
 /** Per-worker result and usage metadata attached to an AgentResponse. */
 export interface SubAgentExecutionMetadata {
   name: string;
@@ -20,6 +33,14 @@ export interface SubAgentExecutionMetadata {
   raw?: ProviderRawData;
   isError?: boolean;
   error?: string;
+  /** Stable display id: `SUBAGENT-NAME-{TrackingID}` (32-char hex, see `createTrackingId`). */
+  trackingId?: string;
+  /** Provider session id used by this worker (≤64 chars, affinity-safe). */
+  sessionId?: string;
+  /** Parent session this worker was spawned from. */
+  parentSessionId?: string;
+  /** Ordered step log for this worker (also persisted in the session file). */
+  steps?: SubAgentStep[];
 }
 
 /** JSON representation returned by AgentResponse.toJSON(). */
@@ -136,6 +157,7 @@ export type StreamEventType =
   | "tool_call_complete"
   | "tool_result"
   | "subagent_complete"
+  | "subagent_delta"
   | "usage"
   | "done"
   | "error";
@@ -148,6 +170,8 @@ export interface StreamEvent {
   toolCall?: ToolCallRecord;
   toolResult?: ToolResultRecord;
   subagent?: SubAgentExecutionMetadata;
+  /** Tracking id of the worker emitting a `subagent_delta` event. */
+  subagentTrackingId?: string;
   usage?: TokenUsage;
   responseId?: string;
   finishReason?: string;

package/src/types/tool.ts

@@ -9,6 +9,8 @@ export interface ToolExecutionContext {
   signal?: AbortSignal;
   /** Session identifier associated with this invocation. */
   sessionId?: string;
+  /** Forwards live sub-agent deltas (used by `spawn_subagents` for realtime tracking). */
+  onSubagentEvent?: (event: { trackingId: string; delta?: string; thinkingDelta?: string; partialText?: string; partialThinking?: string }) => void;
 }
 
 export type ToolExecuteFn<TInput = any, TOutput = any> = (
@@ -50,6 +52,12 @@ export interface ToolCallRecord {
   arguments: Record<string, unknown>;
   rawArguments?: string;
   thoughtSignature?: string;
+  /**
+   * Provider pairing identifier, distinct from the item `id` when the
+   * provider uses both (e.g. Responses `call_id` alongside the `fc_…` item
+   * id). Tool results pair against this when present.
+   */
+  callId?: string;
 }
 
 export interface ToolResultRecord {

package/src/update-models.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env bun
+/**
+ * Developer script to manually download and refresh the models.dev catalog.
+ *
+ * Usage:
+ *   bun src/update-models.ts
+ *   bun src/update-models.ts --force
+ *   bun src/update-models.ts --ttl=24h
+ */
+
+import { refreshModelCatalog, getCatalogStatus } from "./index.ts";
+
+const args = process.argv.slice(2);
+const force = args.includes("--force") || !args.some((a) => a.startsWith("--ttl"));
+
+let customTtlMs: number | undefined;
+for (const arg of args) {
+  if (arg.startsWith("--ttl=")) {
+    const val = arg.slice(6);
+    if (val.endsWith("h")) {
+      customTtlMs = parseFloat(val) * 60 * 60 * 1000;
+    } else if (val.endsWith("m")) {
+      customTtlMs = parseFloat(val) * 60 * 1000;
+    } else {
+      customTtlMs = parseFloat(val);
+    }
+  }
+}
+
+console.log("\x1b[36m[Agent Accelerator]\x1b[0m Checking models catalog from https://models.dev/api.json...");
+const startTime = Date.now();
+
+try {
+  const result = await refreshModelCatalog({ force, ttlMs: customTtlMs });
+  const duration = ((Date.now() - startTime) / 1000).toFixed(2);
+  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).`
+    );
+  } 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.`
+    );
+  }
+  console.log(`  \x1b[90mCache location: ${result.cachePath}\x1b[0m`);
+  console.log(`  \x1b[90mTTL: ${ttlHours} hours\x1b[0m`);
+  if (result.expiresAt) {
+    console.log(`  \x1b[90mNext refresh after: ${new Date(result.expiresAt).toLocaleString()}\x1b[0m`);
+  }
+} catch (error: any) {
+  console.error(`\x1b[31m✖ Failed to refresh model catalog:\x1b[0m`, error.message || error);
+  process.exit(1);
+}

package/src/utils/cache.ts

@@ -31,7 +31,7 @@ export function retentionToTtlSeconds(retention?: CacheRetention, ttlSeconds?: n
   return undefined;
 }
 
-/** Maps retention settings to OpenCode/OpenRouter prompt-cache TTL values. */
+/** 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";