agent-accelerator 0.1.0 → 0.3.0

package/src/agent/loop.ts

@@ -7,8 +7,9 @@ import { AssistantMessageEventStream } from "../streaming/event-stream.ts";
 import { AgentContext } from "./context.ts";
 import { toStandardToolDeclarations } from "../tools/tool.ts";
 import { executeToolCalls } from "../tools/executor.ts";
-import { getModelFromCatalog, ensureModelCatalogFresh } from "../models/catalog.ts";
-import { countTokens } from "../tokens/counter.ts";
+import { getModelFromCatalog, ensureModelCatalogFresh, validateModelThinking } from "../models/catalog.ts";
+import { preprocessFilePartsForBypass } from "../utils/documents.ts";
+import { noteProviderTurn } from "../providers.ts";
 
 export interface AgentLoopConfig {
   agentName?: string;
@@ -19,6 +20,55 @@ export interface AgentLoopConfig {
   options?: ProviderRequestOptions;
   runOptions?: AgentRunOptions;
   maxTurns?: number;
+  /** Convert `file` parts client-side for pdf-incapable models (see Agent flag). */
+  bypassInputFileModality?: boolean;
+  /** Called after every turn for durable persistence checkpoints (never fails a turn). */
+  onProgress?: () => void;
+}
+
+function emitTurn(
+  runOptions: AgentRunOptions | undefined,
+  turn: { turns: number; text?: string; thinking?: string; toolCalls?: ToolCallRecord[]; toolResults?: ToolResultRecord[] }
+): void {
+  try {
+    runOptions?.onTurn?.({
+      turns: turn.turns,
+      text: turn.text,
+      thinking: turn.thinking,
+      toolCalls: turn.toolCalls?.map((c) => ({ id: c.id, name: c.name })),
+      toolResults: turn.toolResults?.map((r) => ({ id: r.id, name: r.name, isError: r.isError })),
+    });
+  } catch {}
+}
+
+function emitProgress(config: { onProgress?: () => void }): void {
+  try { config.onProgress?.(); } catch {}
+}
+
+/**
+ * Normalizes `maxTurns` to a safe positive integer (default Infinity).
+ * `0` means infinite (no limit), matching the `timeout: 0` convention.
+ * Prevents silent zero-turn runs from negative values (clamped to 1).
+ */
+function normalizeMaxTurns(value?: number): number {
+  if (value === undefined) return Infinity;
+  if (value === 0 || value === Infinity) return Infinity;
+  if (!Number.isFinite(value as number)) return Infinity;
+  return Math.max(1, Math.floor(value as number));
+}
+
+/**
+ * Warns when an agent run stops because `maxTurns` was exhausted while
+ * the model still wanted to call tools. Without this, the loop simply
+ * returns the last tool-turn text (often empty) with `finishReason:
+ * "tool_calls"`, which looks like success while dropping pending work.
+ */
+function warnMaxTurnsHit(agentName: string | undefined, maxTurns: number, pendingTools: string[]): void {
+  const who = agentName ? `"${agentName}"` : "Agent";
+  const tools = pendingTools.length > 0 ? ` Pending tool calls dropped: ${pendingTools.join(", ")}.` : "";
+  // Leading newline: runs often end mid-line on streamed output; without it
+  // the warning glues onto the last streamed chunk.
+  console.warn(`\n[Agent Accelerator] WARNING [agent] ${who} hit maxTurns (${maxTurns}) with unfinished tool calls.${tools} Increase maxTurns or split the task.`);
 }
 
 export function computeCostFromPricing(usage: TokenUsage, spec?: ModelSpec): TokenUsage["cost"] {
@@ -67,6 +117,13 @@ function accumulateUsage(target: TokenUsage, source: TokenUsage, spec?: ModelSpe
   target.cacheWriteTokens = (target.cacheWriteTokens ?? 0) + (source.cacheWriteTokens ?? 0);
   target.thinkingTokens = (target.thinkingTokens ?? 0) + (source.thinkingTokens ?? 0);
 
+  // Canonical invariant (provider-agnostic): cache hits are a subset of
+  // input. Some providers occasionally report cached > input on long chained
+  // runs, which surfaces as >100% hit rates downstream. Clamp the aggregate
+  // so no consumer can observe an impossible ratio.
+  target.cachedTokens = Math.min(target.cachedTokens ?? 0, target.inputTokens);
+  target.cacheReadTokens = Math.min(target.cacheReadTokens ?? 0, target.inputTokens);
+
   const sourceCost = computeCostFromPricing(source, spec);
   if (sourceCost) {
     source.cost = sourceCost;
@@ -121,6 +178,7 @@ async function executeToolCallsWithRepeatGuard(options: {
   agentName?: string;
   signal?: AbortSignal;
   sessionId?: string;
+  onSubagentEvent?: (event: { trackingId: string; delta?: string; thinkingDelta?: string; partialText?: string; partialThinking?: string }) => void;
 }): Promise<{ results: ToolResultRecord[]; fingerprints: Set<string> }> {
   const { toolCalls, previousFingerprints } = options;
   const currentFingerprints = new Set<string>();
@@ -153,14 +211,29 @@ async function executeToolCallsWithRepeatGuard(options: {
         parallel: true,
         signal: options.signal,
         sessionId: options.sessionId,
+        onSubagentEvent: options.onSubagentEvent,
       })
     : [];
-  const byId = new Map<string, ToolResultRecord>();
-  for (const result of executed) byId.set(result.id, result);
-  for (const [id, result] of blocked) byId.set(id, result);
+  const byId = new Map<string, ToolResultRecord[]>();
+  for (const result of executed) {
+    const queue = byId.get(result.id) ?? [];
+    queue.push(result);
+    byId.set(result.id, queue);
+  }
+  for (const [id, result] of blocked) {
+    const queue = byId.get(id) ?? [];
+    queue.push(result);
+    byId.set(id, queue);
+  }
 
   return {
-    results: toolCalls.map((call) => byId.get(call.id)!).filter(Boolean),
+    // Consume per-id queues in call order: some open-weights models reuse one
+    // id for several distinct calls in a turn, and a plain id->result map
+    // would hand every call the last result. Queues keep each result aligned
+    // with its own call.
+    results: toolCalls
+      .map((call) => byId.get(call.id)?.shift())
+      .filter((r): r is ToolResultRecord => Boolean(r)),
     fingerprints: currentFingerprints,
   };
 }
@@ -178,8 +251,17 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
     tools,
     options,
     runOptions,
-    maxTurns = 10,
+    maxTurns: rawMaxTurns = Infinity,
   } = config;
+  const maxTurns = normalizeMaxTurns(rawMaxTurns);
+
+  if (config.bypassInputFileModality) {
+    await preprocessFilePartsForBypass(config.context.messages, {
+      providerId: provider.id,
+      modelId,
+      signal: runOptions?.signal,
+    });
+  }
 
   const standardTools = toStandardToolDeclarations(tools);
   const startTime = Date.now();
@@ -204,30 +286,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
   while (turns < maxTurns) {
     turns++;
 
-    // Battle-tested context window check — trim oldest history if needed, keep cached prefix (system+tools)
     const spec = getModelFromCatalog(provider.id, modelId);
-    const contextWindow = spec?.limit?.context ?? spec?.contextWindow ?? 128000;
-    const maxOutput = spec?.limit?.output ?? spec?.maxOutputTokens ?? 8192;
-    // Reserve for output + 10% headroom, ensure first turn already cache-friendly
-    const budgetForInput = Math.floor(contextWindow * 0.9) - maxOutput;
-    let estimated = 0;
-    try {
-      estimated = countTokens({ systemPrompt: context.systemPrompt, messages: context.messages, tools: standardTools as any });
-    } catch {}
-    if (estimated > budgetForInput && context.messages.length > 2) {
-      // Keep system + last 70% of history, drop oldest middle (preserve cached prefix stability)
-      const keepCount = Math.max(2, Math.floor(context.messages.length * 0.7));
-      const toKeep = context.messages.slice(-keepCount);
-      // Preserve at least system and first user if possible
-      const firstUserIdx = context.messages.findIndex((m) => m.role === "user");
-      if (firstUserIdx >= 0 && firstUserIdx < context.messages.length - keepCount) {
-        // Drop middle, keep head + tail for cache stability
-        const head = context.messages.slice(0, 1);
-        context.messages = [...head, ...toKeep];
-      } else {
-        context.messages = toKeep;
-      }
-    }
 
     const providerOptions: ProviderRequestOptions = {
       ...options,
@@ -250,6 +309,12 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
 
     finalResult = genResult;
 
+    // Canonical session routing: lets adapters detect provider switches.
+    noteProviderTurn(
+      runOptions?.sessionId || options?.sessionId || options?.cache?.sessionId,
+      provider.id
+    );
+
     // Safety fallback: if no tool calls and text is empty, rescue answer from thinking
     if ((!genResult.text || genResult.text.trim() === "") && (!genResult.toolCalls || genResult.toolCalls.length === 0) && genResult.thinking) {
       if (genResult.thinking.includes("</think>")) {
@@ -274,6 +339,8 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
 
     // If no tool calls, generation is complete!
     if (!genResult.toolCalls || genResult.toolCalls.length === 0) {
+      emitTurn(runOptions, { turns, text: genResult.text, thinking: genResult.thinking });
+      emitProgress(config);
       break;
     }
 
@@ -310,10 +377,31 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
 
     allToolResults.push(...sanitizedResults);
     context.addToolResults(sanitizedResults);
+    emitTurn(runOptions, {
+      turns,
+      text: genResult.text,
+      thinking: genResult.thinking,
+      toolCalls: genResult.toolCalls,
+      toolResults: sanitizedResults,
+    });
+    emitProgress(config);
 
     if (runOptions?.signal?.aborted) break;
   }
 
+  // maxTurns exhausted while the model still requested tools: the tool
+  // results above were never sent back, so the run is truncated — surface
+  // it via finishReason + warning instead of silently returning.
+  const truncatedByMaxTurns =
+    turns >= maxTurns && !!finalResult?.toolCalls && finalResult.toolCalls.length > 0;
+  if (truncatedByMaxTurns) {
+    warnMaxTurnsHit(
+      agentName,
+      maxTurns,
+      finalResult.toolCalls.map((c: ToolCallRecord) => c.name)
+    );
+  }
+
   return new AgentResponse({
     text: finalResult?.text || "",
     thinking: finalResult?.thinking,
@@ -325,7 +413,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
     responseId: finalResult?.responseId,
     model: modelId,
     provider: provider.id,
-    finishReason: finalResult?.finishReason,
+    finishReason: truncatedByMaxTurns ? "max_turns" : finalResult?.finishReason,
     durationMs: Date.now() - startTime,
     raw: finalResult?.raw,
     turns,
@@ -340,7 +428,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
   const startTime = Date.now();
 
   // Cancellation: merge user signal + outer cancel() into one linked controller.
-  // Vercel doStream honors abortSignal for all providers, so aborting this
+  // Native fetch honors abortSignal on every provider, so aborting this
   // stops the HTTP request; we also cancel the active inner provider stream.
   const linked = new AbortController();
   const userSignal = config.runOptions?.signal;
@@ -365,6 +453,27 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
   (async () => {
     try {
       await ensureModelCatalogFresh();
+      // Re-validate after refresh: Agent.stream() validates before the catalog
+      // is guaranteed fresh, so a cold cache validates permissively. A mismatch
+      // discovered here fails the stream instead of reaching the provider.
+      {
+        const lvl = config.runOptions?.thinkingLevel ?? config.options?.thinking?.level;
+        if (lvl) {
+          try {
+            validateModelThinking(config.provider.id, config.modelId, lvl);
+          } catch (err) {
+            outerStream.fail(err instanceof Error ? err : new Error(String(err)));
+            return;
+          }
+        }
+      }
+      if (config.bypassInputFileModality) {
+        await preprocessFilePartsForBypass(config.context.messages, {
+          providerId: config.provider.id,
+          modelId: config.modelId,
+          signal: config.runOptions?.signal,
+        });
+      }
       const {
         agentName,
         provider,
@@ -373,8 +482,9 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         tools,
         options,
         runOptions,
-        maxTurns = 10,
+        maxTurns: rawMaxTurns = Infinity,
       } = config;
+      const maxTurns = normalizeMaxTurns(rawMaxTurns);
 
       const standardTools = toStandardToolDeclarations(tools);
 
@@ -399,25 +509,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         throwIfCancelled();
         turns++;
 
-        // Same context-window trim as non-stream (ensure cache prefix stable)
         const spec2 = getModelFromCatalog(provider.id, modelId);
-        const cw2 = spec2?.limit?.context ?? spec2?.contextWindow ?? 128000;
-        const mo2 = spec2?.limit?.output ?? spec2?.maxOutputTokens ?? 8192;
-        const budget2 = Math.floor(cw2 * 0.9) - mo2;
-        try {
-          const est2 = countTokens({ systemPrompt: context.systemPrompt, messages: context.messages, tools: standardTools as any });
-          if (est2 > budget2 && context.messages.length > 2) {
-            const keep2 = Math.max(2, Math.floor(context.messages.length * 0.7));
-            const toKeep = context.messages.slice(-keep2);
-            const firstUserIdx = context.messages.findIndex((m) => m.role === "user");
-            if (firstUserIdx >= 0 && firstUserIdx < context.messages.length - keep2) {
-              const head = context.messages.slice(0, 1);
-              context.messages = [...head, ...toKeep];
-            } else {
-              context.messages = toKeep;
-            }
-          }
-        } catch {}
 
         const providerOptions: ProviderRequestOptions = {
           ...options,
@@ -449,6 +541,11 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         currentInner = null;
         throwIfCancelled();
         lastResponse = turnResponse;
+        // Canonical session routing: lets adapters detect provider switches.
+        noteProviderTurn(
+          runOptions?.sessionId || options?.sessionId || options?.cache?.sessionId,
+          provider.id
+        );
 
         // Safety fallback: if no tool calls and text is empty, rescue answer from thinking
         if ((!turnResponse.text || turnResponse.text.trim() === "") && (!turnResponse.toolCalls || turnResponse.toolCalls.length === 0) && turnResponse.thinking) {
@@ -472,6 +569,8 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         );
 
         if (!turnResponse.toolCalls || turnResponse.toolCalls.length === 0) {
+          emitTurn(runOptions, { turns, text: turnResponse.text, thinking: turnResponse.thinking });
+          emitProgress(config);
           break;
         }
 
@@ -483,6 +582,18 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
           agentName,
           signal: linked.signal,
           sessionId: runOptions?.sessionId || options?.sessionId || options?.cache?.sessionId,
+          onSubagentEvent: (ev) => {
+            try {
+              outerStream.push({
+                type: "subagent_delta",
+                subagentTrackingId: ev.trackingId,
+                delta: ev.delta,
+                thinkingDelta: ev.thinkingDelta,
+                partialText: ev.partialText,
+                partialThinking: ev.partialThinking,
+              });
+            } catch {}
+          },
         });
         throwIfCancelled();
         const results = guarded.results;
@@ -518,7 +629,26 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
 
         allToolResults.push(...sanitizedResults);
         context.addToolResults(sanitizedResults);
+        emitTurn(runOptions, {
+          turns,
+          text: turnResponse.text,
+          thinking: turnResponse.thinking,
+          toolCalls: turnResponse.toolCalls,
+          toolResults: sanitizedResults,
+        });
+        emitProgress(config);
+      }
+
+      const truncatedByMaxTurns =
+        turns >= maxTurns && !!lastResponse?.toolCalls && lastResponse.toolCalls.length > 0;
+      if (truncatedByMaxTurns) {
+        warnMaxTurnsHit(
+          agentName,
+          maxTurns,
+          lastResponse!.toolCalls.map((c) => c.name)
+        );
       }
+      const truncatedFinishReason = truncatedByMaxTurns ? "max_turns" : lastResponse?.finishReason;
 
       const finalAgentResponse = new AgentResponse({
         text: lastResponse?.text || "",
@@ -531,7 +661,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         responseId: lastResponse?.responseId,
         model: modelId,
         provider: provider.id,
-        finishReason: lastResponse?.finishReason,
+        finishReason: truncatedFinishReason,
         durationMs: Date.now() - startTime,
         raw: lastResponse?.raw as any,
         turns,
@@ -541,7 +671,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         type: "done",
         delta: "",
         usage: accumulatedUsage,
-        finishReason: lastResponse?.finishReason,
+        finishReason: truncatedFinishReason,
         responseId: lastResponse?.responseId,
       });
 

package/src/data/README.md

@@ -11,13 +11,13 @@ Agent Accelerator references a catalog of **7,500+ models across 200+ providers*
 To keep the repository and published npm/Bun package lightweight and blazing fast:
 
 1. **Excluded from Production Package & Git**:
-   * The ~4.5 MB full catalog snapshot (`models-cache.json` / `models.dev.json`) is **never** committed to git and is **excluded** from the npm/Bun distribution bundle.
-   * Both files are tracked in `.gitignore` and `.npmignore`.
+   * The ~4.5 MB full catalog snapshot (`models.dev.json`) is **never** committed to git and is **excluded** from the npm/Bun distribution bundle.
+   * The file is tracked in `.gitignore` and `.npmignore`.
 
 2. **Dynamic 12-Hour Automated TTL Cache**:
-   * On agent execution (`runAgentLoop` / `streamAgentLoop`), Agent Accelerator checks the status of `src/data/models-cache.json`.
+   * On agent execution (`runAgentLoop` / `streamAgentLoop`), Agent Accelerator checks the status of `src/data/models.dev.json`.
    * **Cache Hit (< 12h)**: Instant memory/disk load with zero network overhead.
-   * **Cache Miss / Expired (≥ 12h)**: Automatically downloads the latest catalog directly from `https://models.dev/api.json`, caches it to `src/data/models-cache.json`, and loads the catalog into memory.
+   * **Cache Miss / Expired (≥ 12h)**: Automatically downloads the latest catalog directly from `https://models.dev/api.json`, caches it to `src/data/models.dev.json`, and loads the catalog into memory.
    * **Resilience**: If an existing cache exists on disk, temporary upstream network issues will safely continue using the local cached copy.
 
 ---
@@ -36,7 +36,7 @@ bun run update-models
 bun run update-models --force
 
 # Custom TTL (e.g., 24 hours)
-bun scripts/update-models.ts --ttl=24h
+bun src/update-models.ts --ttl=24h
 ```
 
 ---
@@ -80,5 +80,5 @@ setCatalogTTL(6 * 60 * 60 * 1000);
 ```text
 src/data/
 ├── README.md               # This documentation
-└── models-cache.json       # Auto-generated on first run (gitignored, excluded from bundle)
+└── models.dev.json         # Auto-generated on first run (gitignored, excluded from bundle)
 ```