agent-accelerator 0.6.5 → 0.6.6

package/src/agent/options.ts

@@ -0,0 +1,166 @@
+/**
+ * Option handling for an Agent: the normalized run limits, the thinking level, the tool choice and the one function
+ * that turns agent config plus per-run options into what every provider call receives.
+ */
+import type { AgentConfig, AgentRunOptions, RetryPolicyConfig, ToolChoiceOption } from "../types/agent.ts";
+import type { ProviderRequestOptions, StructuredOutputSpec } from "../types/model.ts";
+import type { CacheOption, ServiceTier, ThinkingConfig, ThinkingLevel } from "../types/core.ts";
+import type { Prompts } from "../prompts/prompts.ts";
+import { normalizeThinkingV2 } from "../tools/tool.ts";
+import { validateModelThinking } from "../models/catalog.ts";
+import { telemetryBus } from "../telemetry.ts";
+
+/**
+ * Resolves a per-run thinking override without mutating agent config.
+ */
+export function resolveEffectiveThinking(base?: ThinkingConfig, overrideLevel?: string): ThinkingConfig | undefined {
+  if (!overrideLevel) return base;
+  if (overrideLevel === "none") return { enabled: false, level: "none", budgetTokens: 0 };
+  if (overrideLevel === "dynamic") return { enabled: true, level: "dynamic", budgetTokens: -1 };
+  return { enabled: true, level: overrideLevel as ThinkingConfig["level"] };
+}
+
+/** Normalized per-run limits. Sub-agents inherit these unless overridden. */
+export interface AgentRunLimits {
+  maxTurns?: number;
+  deadlineMs?: number;
+  maxToolCallsPerRun?: number;
+  maxTotalTokens?: number;
+  requestTimeoutMs: number;
+  firstByteTimeoutMs: number;
+  streamIdleTimeoutMs: number;
+}
+
+/** Resolves `(config as any).limits` with defaults (timeouts tolerate reasoning). */
+export function resolveAgentLimits(config: { limits?: Record<string, unknown> }): AgentRunLimits {
+  const raw = (config as { limits?: Record<string, unknown> }).limits ?? {};
+  const num = (v: unknown): number | undefined => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+  // A network timeout: `0` or `Infinity` turns it off, any other number is milliseconds, anything else is unset (the default applies).
+  const timeout = (v: unknown): number | undefined => (typeof v === "number" && !Number.isNaN(v) ? v : undefined);
+  return {
+    ...(num(raw.maxTurns) !== undefined ? { maxTurns: Math.max(1, Math.floor(num(raw.maxTurns)!)) } : {}),
+    ...(num(raw.deadlineMs) !== undefined ? { deadlineMs: num(raw.deadlineMs)! } : {}),
+    ...(num(raw.maxToolCallsPerRun) !== undefined
+      ? { maxToolCallsPerRun: Math.max(1, Math.floor(num(raw.maxToolCallsPerRun)!)) }
+      : {}),
+    ...(num(raw.maxTotalTokens) !== undefined
+      ? { maxTotalTokens: Math.max(1, Math.floor(num(raw.maxTotalTokens)!)) }
+      : {}),
+    requestTimeoutMs: timeout(raw.requestTimeoutMs) ?? 300_000,
+    firstByteTimeoutMs: timeout(raw.firstByteTimeoutMs) ?? 120_000,
+    streamIdleTimeoutMs: timeout(raw.streamIdleTimeoutMs) ?? 300_000,
+  };
+}
+
+/** The Agent settings `buildProviderOptions` reads. */
+export interface ProviderOptionSource {
+  apiKey?: string;
+  baseUrl?: string;
+  customHeaders?: Record<string, string>;
+  thinkingConfig?: ThinkingConfig;
+  cache?: CacheOption;
+  serviceTier?: ServiceTier;
+  sessionId: string;
+  outputSpec?: StructuredOutputSpec;
+  prompts: Prompts;
+  googleTier?: "free" | "paid";
+  callDefaults: {
+    toolChoice?: ToolChoiceOption;
+    maxOutputTokens?: number;
+    retry?: RetryPolicyConfig;
+    env?: Record<string, string>;
+    fetch?: typeof fetch;
+  };
+}
+
+/**
+ * Single place that turns agent config + per-run options into the options
+ * every provider call receives. Per-run values override agent defaults
+ * (objects such as `retry` and `env` merge key by key).
+ */
+export function buildProviderOptions(
+  agent: ProviderOptionSource,
+  runOptions: AgentRunOptions | undefined
+): ProviderRequestOptions {
+  const d = agent.callDefaults;
+  const sessionId = runOptions?.sessionId || agent.sessionId;
+  const toolChoice = normalizeToolChoiceOption(runOptions?.toolChoice ?? d.toolChoice);
+  const retry = { ...d.retry, ...runOptions?.retry };
+  const env = { ...d.env, ...runOptions?.env };
+  const maxOutputTokens = runOptions?.maxOutputTokens ?? d.maxOutputTokens;
+  const fetchImpl = runOptions?.fetch ?? d.fetch;
+  return {
+    apiKey: agent.apiKey,
+    baseUrl: agent.baseUrl,
+    headers: { ...(agent.customHeaders ?? {}), ...(runOptions?.headers ?? {}) },
+    thinking: resolveEffectiveThinking(agent.thinkingConfig, runOptions?.thinkingLevel),
+    ...(agent.cache ? { cache: agent.cache } : {}),
+    serviceTier: agent.serviceTier,
+    sessionId,
+    ...(agent.outputSpec ? { output: agent.outputSpec } : {}),
+    prompts: { structuredOutput: agent.prompts.structuredOutput, toolBridge: agent.prompts.toolBridge },
+    ...(agent.googleTier ? { googleTier: agent.googleTier } : {}),
+    ...(toolChoice !== undefined ? { toolChoice } : {}),
+    ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
+    ...(Object.keys(env).length > 0 ? { env } : {}),
+    ...(fetchImpl ? { fetch: fetchImpl } : {}),
+    ...(retry.maxRetries !== undefined ? { maxRetries: retry.maxRetries } : {}),
+    ...(retry.maxDelayMs !== undefined ? { maxRetryDelayMs: retry.maxDelayMs } : {}),
+    ...(retry.baseDelayMs !== undefined ? { retryBaseDelayMs: retry.baseDelayMs } : {}),
+    ...(retry.budgetMs !== undefined ? { retryBudgetMs: retry.budgetMs } : {}),
+  };
+}
+
+/** Normalizes the public `thinkingLevel` flag into provider-neutral thinking settings. */
+export function normalizeThinking(config: AgentConfig, fallbackLevel?: string): ThinkingConfig | undefined {
+  // DX4: only thinkingLevel, values: none, dynamic, minimal, low, medium, high, xhigh, max
+  // `thinking` (canonical) wins over legacy `thinkingLevel`; `{ level }` objects are unwrapped.
+  const rawLevel = normalizeThinkingV2(config.thinking, config.thinkingLevel) ?? fallbackLevel;
+  if (typeof config.thinking === "object" && config.thinking?.budgetTokens !== undefined) {
+    // No provider maps an explicit token budget yet: say so instead of ignoring it silently.
+    telemetryBus.emitWarning(
+      "config.thinking_budget_ignored",
+      "[Agent Accelerator] thinking.budgetTokens is not forwarded by any provider adapter yet; the level alone is used.",
+      { budgetTokens: config.thinking.budgetTokens }
+    );
+  }
+  const level = rawLevel as ThinkingLevel | undefined;
+
+  if (!level) return undefined;
+
+  // Validate model thinking from catalog if model is configured
+  if (config.model) {
+    try {
+      const rawModel: any = (config.model as any)?.model ? (config.model as any).model : config.model;
+      const modelStr = typeof rawModel === "string" ? rawModel : rawModel?.id || "";
+      const provStr =
+        typeof rawModel === "object" && rawModel?.provider
+          ? rawModel.provider
+          : modelStr.includes("/")
+            ? modelStr.split("/")[0]
+            : "";
+      const actualModelId = modelStr.includes("/") ? modelStr.split("/").slice(1).join("/") : modelStr;
+      if (actualModelId) {
+        validateModelThinking(provStr || "openrouter", actualModelId, level);
+      }
+    } catch (e) {
+      throw e;
+    }
+  }
+
+  if (level === "none") {
+    return { enabled: false, level: "none", budgetTokens: 0 };
+  }
+  if (level === "dynamic") {
+    return { enabled: true, level: "dynamic", budgetTokens: -1 };
+  }
+  return { enabled: true, level };
+}
+
+/** Maps the public `toolChoice` option onto the provider wire-neutral form. */
+export function normalizeToolChoiceOption(choice: ToolChoiceOption | undefined): ProviderRequestOptions["toolChoice"] {
+  if (!choice) return undefined;
+  if (typeof choice === "string") return choice;
+  if (choice.tool) return { type: "function", function: { name: choice.tool } };
+  return choice.mode;
+}

package/src/agent/run-control.ts

@@ -0,0 +1,248 @@
+/**
+ * Mid-session control of one Agent: the run that is active now, the follow-ups waiting behind it, and what happens when
+ * a new prompt arrives while busy (`steer`, `queue`, `interrupt`). `Agent` keeps the public methods and calls into this
+ * class; the class only needs the few things in {@link RunHost}.
+ */
+import type { AgentRunOptions, MidSessionConfig } from "../types/agent.ts";
+import type { ContentPart } from "../types/message.ts";
+import type { AgentResponse, StreamEvent } from "../types/response.ts";
+import type { AssistantMessageEventStream } from "../streaming/event-stream.ts";
+import { ValidationError } from "../types/errors.ts";
+import type { SteerEntry } from "./loop.ts";
+
+/** The run that is active right now. */
+export interface ActiveRun {
+  steerInbox: SteerEntry[];
+  outerStream?: AssistantMessageEventStream;
+  runPromise?: Promise<AgentResponse>;
+  abortController: AbortController;
+}
+
+/** A prompt waiting for the active run to finish. */
+export interface QueuedPrompt {
+  prompt: string | ContentPart[];
+  options?: AgentRunOptions;
+  isStream: boolean;
+  deferredStream?: AssistantMessageEventStream;
+  resolve: (res: AgentResponse) => void;
+  reject: (err: unknown) => void;
+  /** Put here by `interrupt(message)`: runs before every other waiting prompt. */
+  urgent?: boolean;
+}
+
+/** What the run control needs from its Agent. */
+export interface RunHost {
+  persistNow(): void;
+  run(prompt: string | ContentPart[], options?: AgentRunOptions): Promise<AgentResponse>;
+  startNonStreamingRun(prompt: string | ContentPart[], options?: AgentRunOptions): Promise<AgentResponse>;
+  startStreamingRun(prompt: string | ContentPart[], options?: AgentRunOptions): AssistantMessageEventStream;
+  readonly midSessionConfig: Required<Pick<MidSessionConfig, "mode">> & MidSessionConfig;
+  readonly maxSteers: number;
+}
+
+/** The active run and the waiting queue of one Agent. */
+export class RunControl {
+  /** The run in flight, or null when idle. */
+  current: ActiveRun | null = null;
+  /** Prompts waiting behind it (urgent ones first). */
+  readonly queue: QueuedPrompt[] = [];
+
+  constructor(private readonly host: RunHost) {}
+
+  /** Throws when the steer inbox is at its bound. */
+  assertSteerRoom(inbox: SteerEntry[]): void {
+    const max = this.host.maxSteers ?? 20;
+    if (inbox.length >= max) {
+      throw new ValidationError(
+        `[Agent Accelerator] Steer inbox is full (${inbox.length}/${max}). Wait for the active run to drain or increase midSession.maxSteers.`
+      );
+    }
+  }
+
+  // Picks steer or queue for a call that arrives while busy: the developer's enforced midSession mode wins over the per-call request; in: run()/stream() `enqueue`, out: their busy branch.
+  resolveEnqueueMode(requested?: "steer" | "queue"): "steer" | "queue" {
+    const enforced = this.host.midSessionConfig.mode;
+    if (enforced === "steer" || enforced === "queue") return enforced;
+    return requested === "steer" ? "steer" : "queue";
+  }
+
+  // Aborts the active run (provider request, tools, workers, stream) through its own controller; no-op when idle; in: interrupt and queueUrgent, out: the run settles as AbortError.
+  abortActive(reason?: Error): void {
+    const active = this.current;
+    if (!active) return;
+    try {
+      active.abortController.abort(reason ?? new Error("Agent interrupted"));
+    } catch {}
+    try {
+      active.outerStream?.cancel(reason);
+    } catch {}
+  }
+
+  // Puts a prompt ahead of everything waiting (behind earlier interrupts) and aborts the active run, so it starts as soon as that run has settled; ignores midSession mode and maxQueued; in: run()/stream() with enqueue "interrupt", out: pendingQueue + the abort.
+  queueUrgent(entry: QueuedPrompt): void {
+    entry.urgent = true;
+    const firstOrdinary = this.queue.findIndex((e) => !e.urgent);
+    this.queue.splice(firstOrdinary < 0 ? this.queue.length : firstOrdinary, 0, entry);
+    this.host.persistNow();
+    this.abortActive();
+  }
+
+  /**
+   * Buffers a steer prompt into the active run and returns a promise for ITS
+   * reply: the active run's response when the prompt is injected, or (if the
+   * run ends first and the prompt becomes a queued follow-up) the follow-up
+   * run's response, so a late steer's answer is never lost.
+   */
+  steerInto(active: ActiveRun, prompt: string | ContentPart[], options?: AgentRunOptions): Promise<AgentResponse> {
+    this.assertSteerRoom(active.steerInbox);
+    const runDone = active.runPromise ?? active.outerStream?.result();
+    if (!runDone) return this.host.run(prompt, options) as Promise<AgentResponse>;
+    const entry: SteerEntry = { prompt, options };
+    const reply = new Promise<AgentResponse>((resolve, reject) => {
+      entry.settle = { resolve, reject };
+    });
+    reply.catch(() => {}); // a fire-and-forget caller must not trigger an unhandled rejection
+    active.steerInbox.push(entry);
+    this.host.persistNow();
+    runDone.then(
+      (res) => {
+        if (!entry.settle?.deferredToQueue) entry.settle?.resolve(res);
+      },
+      (err) => {
+        if (!entry.settle?.deferredToQueue) entry.settle?.reject(err);
+      }
+    );
+    return reply;
+  }
+
+  // Starts the next waiting prompt (urgent ones first, aborted ones rejected) as a streaming or non-streaming run once the agent is idle; in: finishCurrentRun and queue changes, out: a new run whose result settles the queued caller.
+  pumpQueue(): void {
+    if (this.current !== null) return;
+    const next = this.queue.shift();
+    if (!next) return;
+    this.host.persistNow();
+    // Reject queued items whose signal aborted before start.
+    try {
+      if ((next.options as { signal?: AbortSignal } | undefined)?.signal?.aborted) {
+        const reason = ((next.options as { signal?: AbortSignal }).signal as unknown as { reason?: unknown })?.reason;
+        const abortErr = Object.assign(
+          reason instanceof Error ? reason : new Error("Queued run aborted before start"),
+          { name: "AbortError" }
+        );
+        try {
+          next.reject(abortErr);
+        } catch {}
+        try {
+          next.deferredStream?.fail(abortErr instanceof Error ? abortErr : new Error(String(abortErr)));
+        } catch {}
+        queueMicrotask(() => this.pumpQueue());
+        return;
+      }
+    } catch {}
+    if (next.isStream && next.deferredStream) {
+      const deferred = next.deferredStream;
+      try {
+        const real = this.host.startStreamingRun(next.prompt, next.options);
+        try {
+          (deferred as any).__piped = true;
+        } catch {}
+        const forward = (e: StreamEvent) => {
+          try {
+            deferred.push(e);
+          } catch {}
+        };
+        real.on("*", forward as any);
+        try {
+          deferred.onCancel(() => {
+            try {
+              real.cancel();
+            } catch {}
+          });
+        } catch {}
+        real.result().then(
+          (res) => {
+            try {
+              next.resolve(res);
+            } catch {}
+            try {
+              deferred.end(res);
+            } catch {}
+          },
+          (err) => {
+            try {
+              next.reject(err);
+            } catch {}
+            // Pipe failures into the deferred stream so for-await sees them.
+            try {
+              deferred.fail(err instanceof Error ? err : new Error(String(err)));
+            } catch {}
+          }
+        );
+      } catch (err) {
+        try {
+          next.reject(err);
+        } catch {}
+        try {
+          deferred.fail(err instanceof Error ? err : new Error(String(err)));
+        } catch {}
+        // Keep draining even if starting failed.
+        queueMicrotask(() => this.pumpQueue());
+      }
+      return;
+    }
+    this.host.startNonStreamingRun(next.prompt, next.options).then(next.resolve, next.reject);
+  }
+
+  // Ends the active run slot: leftover steers become follow-ups at the FRONT of the queue (behind urgent ones), then the queue is pumped; in: a settled run, out: pendingQueue + persistNow.
+  finishCurrentRun(): void {
+    // Leftover steer entries become queued follow-ups instead of dropping.
+    let leftover: SteerEntry[] = [];
+    try {
+      leftover = this.current?.steerInbox?.splice(0) ?? [];
+    } catch {
+      leftover = [];
+    }
+    this.current = null;
+    if (leftover.length > 0) {
+      try {
+        const max = this.host.midSessionConfig.maxQueued ?? 20;
+        // Late steers were typed BEFORE anything already queued: they go to the front, in the order they arrived.
+        const lateSteers: QueuedPrompt[] = [];
+        for (const entry of leftover) {
+          try {
+            if ((entry.options as { signal?: AbortSignal } | undefined)?.signal?.aborted) {
+              entry.settle?.reject(
+                Object.assign(new Error("Steer aborted before it could run"), { name: "AbortError" })
+              );
+              continue;
+            }
+          } catch {
+            continue;
+          }
+          if (this.queue.length + lateSteers.length >= max) {
+            entry.settle?.reject(
+              new ValidationError("[Agent Accelerator] Steer dropped: the follow-up queue is full.")
+            );
+            continue;
+          }
+          // The steer was never injected: it now runs as a follow-up, and the
+          // caller's promise resolves with that run's response.
+          if (entry.settle) entry.settle.deferredToQueue = true;
+          lateSteers.push({
+            prompt: entry.prompt,
+            options: entry.options,
+            isStream: false,
+            resolve: entry.settle?.resolve ?? (() => {}),
+            reject: entry.settle?.reject ?? (() => {}),
+          });
+        }
+        // ...but behind an interrupt(message), which is the newest and most urgent instruction.
+        const firstOrdinary = this.queue.findIndex((e) => !e.urgent);
+        this.queue.splice(firstOrdinary < 0 ? this.queue.length : firstOrdinary, 0, ...lateSteers);
+      } catch {}
+    }
+    this.host.persistNow();
+    // Defer pump so the completing run's .then handlers settle first.
+    queueMicrotask(() => this.pumpQueue());
+  }
+}

package/src/index.ts

@@ -115,7 +115,7 @@ export {
   type CatalogStatus,
   type RefreshCatalogOptions,
 } from "./models/catalog.ts";
-export { resolveEffectiveThinking } from "./agent/agent.ts";
+export { resolveEffectiveThinking } from "./agent/options.ts";
 export { withRetries, isTransientError } from "./utils/retry.ts";
 export { toConciseProviderError, assertModalitiesSupported, assertNoVideoPartsOnResponses } from "./utils/errors.ts";
 // Native provider implementations.
@@ -222,7 +222,7 @@ export {
 } from "./types/errors.ts";
 export type { AgentAccelErrorCode, AgentAccelErrorContext } from "./types/errors.ts";
 // Normalized run limits (sub-agents inherit unless overridden)
-export type { AgentRunLimits } from "./agent/agent.ts";
+export type { AgentRunLimits } from "./agent/options.ts";
 
 // Telemetry bus: warnings, anomalies and per-turn thinking traces (attach with `telemetryBus.onEvent`)
 export { telemetryBus } from "./telemetry.ts";

package/src/providers/google.ts

@@ -1559,8 +1559,7 @@ export class GoogleInteractionsProvider implements Provider {
         // (JSON mocks) where no SSE frames were ever seen.
         const hasTerminal = completedBody !== undefined || sawFinishReason || sawUsage;
         // Trim provider trailing blank lines from finalized thinking (live
-        // deltas already emitted raw; display collapse happens in the
-        // wrapThinking presentation layer). Stateful bodies unaffected.
+        // deltas already emitted raw). Stateful bodies unaffected.
         const cleanThinkingEarly = thinking.replace(/\n{3,}/g, "\n\n").trim();
         const ctEntry = Object.entries(responseHeaders).find(([k]) => k.toLowerCase() === "content-type");
         const isSSEPayload =

package/src/streaming/event-stream.ts

@@ -10,7 +10,7 @@ export interface EventStreamOptions {
   /**
    * When false, `partialText`/`partialThinking` cumulative fields are stripped
    * from events before delivery. Default true for compat (providers attach
-   * cumulative partials; consumers like wrapThinking rely on them).
+   * cumulative partials).
    */
   includePartial?: boolean;
   /** Max buffered events when no iterator is attached. Default 1000. Oldest dropped. */

package/src/types/agent.ts

@@ -392,8 +392,6 @@ export interface AgentRunOptions {
   onThinkingDelta?: (delta: string, event: import("./response.ts").StreamEvent) => void;
   /** Called for every stream event (text_delta, thinking_delta, tool_call_complete, subagent_complete, etc.). */
   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;
   // Per-run knobs (all optional, additive; `output` intentionally

package/src/utils/headers.ts

@@ -24,7 +24,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.6.5";
+  return "0.6.6";
 }
 
 // User-Agent string with version and platform; in: AGENT_ACCEL_USER_AGENT, out: a string.