agent-accelerator 0.2.0 → 0.3.0

package/src/agent/loop.ts

@@ -22,6 +22,53 @@ export interface AgentLoopConfig {
   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"] {
@@ -131,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>();
@@ -163,6 +211,7 @@ async function executeToolCallsWithRepeatGuard(options: {
         parallel: true,
         signal: options.signal,
         sessionId: options.sessionId,
+        onSubagentEvent: options.onSubagentEvent,
       })
     : [];
   const byId = new Map<string, ToolResultRecord[]>();
@@ -202,8 +251,9 @@ 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, {
@@ -289,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;
     }
 
@@ -325,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,
@@ -340,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,
@@ -409,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);
 
@@ -495,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;
         }
 
@@ -506,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;
@@ -541,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 || "",
@@ -554,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,
@@ -564,7 +671,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         type: "done",
         delta: "",
         usage: accumulatedUsage,
-        finishReason: lastResponse?.finishReason,
+        finishReason: truncatedFinishReason,
         responseId: lastResponse?.responseId,
       });
 

package/src/index.ts

@@ -31,8 +31,14 @@ export {
   buildAgentTools,
   agentToTool,
   createSubagentSpawnTool,
+  createChildSessionId,
+  createFixedChildSessionId,
+  isSessionDescendant,
+  getSubAgentTrace,
+  listSubAgentTraceIds,
+  subscribeToSubAgent,
 } from "./agent/delegation.ts";
-export type { DynamicSubagentTask, AgentAsToolTarget } from "./agent/delegation.ts";
+export type { DynamicSubagentTask, AgentAsToolTarget, SubAgentTrace } from "./agent/delegation.ts";
 
 // Providers & Registry — unified multi-provider layer, all native REST
 export {
@@ -160,8 +166,32 @@ export { SSEParser } from "./streaming/sse-parser.ts";
 // Responses
 export { AgentResponse } from "./types/response.ts";
 
+// Session persistence & telemetry (conversation history + cost rollup)
+export {
+  SessionTelemetry,
+  loadSessionFile,
+  saveSessionFile,
+  loadSessionDir,
+  saveSessionDir,
+  writeFileAtomic,
+  findLatestSessionDir,
+  sessionDirFor,
+  extractMediaToDir,
+  resolveMediaPaths,
+  buildSessionData,
+  serializeSession,
+  deserializeSession,
+  getSessionContextWindow,
+  computeSessionTurnCost,
+  formatSessionTokens,
+  formatSessionCost,
+  formatSessionBanner,
+  emptyTotals,
+} from "./session/store.ts";
+export type { PersistedAgentSession, SessionTotals, SessionAgentLike, LoadedSessionDir, PersistedSubAgentTrace } from "./session/store.ts";
+
 // Utilities
-export { createSessionId } from "./utils/session.ts";
+export { createSessionId, hashSessionPart, createTrackingId } from "./utils/session.ts";
 export { getApiKey, getEnv } from "./utils/env.ts";
 export { buildSessionHeaders } from "./utils/headers.ts";
 export { normalizeMediaInput, inferMimeType } from "./utils/media.ts";
@@ -218,6 +248,7 @@ export type {
 export type {
   AgentResponseJSON,
   SubAgentExecutionMetadata,
+  SubAgentStep,
   StreamEvent,
   StreamEventType,
 } from "./types/response.ts";
@@ -225,6 +256,7 @@ export type {
 export type {
   AgentConfig,
   AgentRunOptions,
+  AgentTurnEvent,
   DynamicSubagentsConfig,
 } from "./types/agent.ts";
 

package/src/models/catalog.ts

@@ -244,7 +244,7 @@ export function getModelThinkingInfo(provider: string, modelId: string): ModelTh
   if (!spec) {
     return {
       supportsThinking: true,
-      allowedLevels: ["none", "minimal", "low", "medium", "high", "xhigh", "dynamic"],
+      allowedLevels: ["none", "minimal", "low", "medium", "high", "xhigh", "max", "dynamic"],
       supportsDisable: true,
       description: "Model not found in catalog; generic thinking levels allowed.",
     };
@@ -295,6 +295,7 @@ export function getModelThinkingInfo(provider: string, modelId: string): ModelTh
     allowed.add("medium");
     allowed.add("high");
     allowed.add("xhigh");
+    allowed.add("max");
   }
 
   // Fixed reasoning model (no reasoning_options) e.g. DeepSeek-R1, QwQ-32B
@@ -510,7 +511,7 @@ export {
 
 /**
  * Permissive placeholder so custom endpoints never fail preflight:
- * allows every ThinkingLevel (none -> xhigh + dynamic).
+ * allows every ThinkingLevel (none -> max + dynamic).
  * @example `const spec = createGenericModelSpec("groq", "llama-3.3-70b-versatile");`
  */
 export function createGenericModelSpec(provider: string, modelId: string): ModelSpec {
@@ -527,7 +528,7 @@ export function createGenericModelSpec(provider: string, modelId: string): Model
     reasoning: true,
     reasoning_options: [
       { type: "toggle" },
-      { type: "effort", values: ["minimal", "low", "medium", "high", "xhigh"] },
+      { type: "effort", values: ["minimal", "low", "medium", "high", "xhigh", "max"] },
       { type: "budget_tokens", min: 0, max: 128000 },
     ],
     tool_call: true,

package/src/providers.ts

@@ -108,7 +108,7 @@ export function clearSessionRouting(sessionId?: string): void {
 
 /**
  * Maps a canonical ThinkingLevel onto Google Interactions `thinking_level`.
- * Google values: minimal|low|medium|high (no off switch, no xhigh).
+ * Google values: minimal|low|medium|high (no off switch, no xhigh/max).
  */
 export function mapThinkingLevelToGoogle(
   level: ThinkingLevel | string | undefined
@@ -126,7 +126,7 @@ export function mapThinkingLevelToGoogle(
     });
     return {};
   }
-  if (norm === "xhigh") {
+  if (norm === "xhigh" || norm === "max") {
     emitProviderWarning({
       provider: "google",
       capability: "thinking level",
@@ -155,7 +155,7 @@ export function mapServiceTierToGoogle(tier: ServiceTier | undefined): "flex" |
  * 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).
+ * through. `max` rides the same verbatim path. `dynamic` omits (server default).
  */
 export function mapThinkingLevelToOpenRouterChat(
   level: ThinkingLevel | string | undefined
@@ -169,7 +169,8 @@ export function mapThinkingLevelToOpenRouterChat(
     norm === "low" ||
     norm === "medium" ||
     norm === "high" ||
-    norm === "xhigh"
+    norm === "xhigh" ||
+    norm === "max"
   ) {
     return { effort: norm };
   }
@@ -179,8 +180,8 @@ export function mapThinkingLevelToOpenRouterChat(
 /**
  * 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.
+ * Wire-validated extras: `none` disables reasoning output; `xhigh`/`max` are
+ * echoed but are NOT documented levels, so they clamp to `high` with a warning.
  *
  * @deprecated The Responses skin is discontinued for OpenRouter
  * (`src/providers/openrouter-responses.ts`, archived). Use
@@ -194,7 +195,7 @@ export function mapThinkingLevelToOpenRouter(
   const norm = String(level).toLowerCase().trim();
   if (norm === "dynamic") return {}; // server default (medium)
   if (norm === "none") return { effort: "none" };
-  if (norm === "xhigh") {
+  if (norm === "xhigh" || norm === "max") {
     emitProviderWarning({
       provider: "openrouter",
       capability: "thinking level",
@@ -327,7 +328,7 @@ export function mapToolChoiceToOpenRouter(
  * 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).
+ * and max natively so they pass through verbatim. `dynamic` omits (server default).
  */
 export function mapThinkingLevelToOpenAI(
   level: ThinkingLevel | string | undefined
@@ -341,7 +342,8 @@ export function mapThinkingLevelToOpenAI(
     norm === "low" ||
     norm === "medium" ||
     norm === "high" ||
-    norm === "xhigh"
+    norm === "xhigh" ||
+    norm === "max"
   ) {
     return { effort: norm };
   }