agent-accelerator 0.4.0 → 0.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-accelerator",
-  "version": "0.4.0",
+  "version": "0.4.5",
   "description": "High-performance SDK for AI agents with a unified API across AI providers. Optimized for high cache hit rates, observability, and seamless agent orchestration. Built to power production-grade agentic systems and harnesses for teams at any scale.",
   "license": "MIT",
   "author": "Sashvat Bharat",

package/src/agent/agent.ts

@@ -12,7 +12,8 @@ import { runAgentLoop, streamAgentLoop, type SteerEntry } from "./loop.ts";
 import { createSessionId } from "../utils/session.ts";
 import { getSubAgentTrace, subscribeToSubAgent, listSubAgentTraceIds, type SubAgentTrace } from "./delegation.ts";
 import { saveSessionDir, saveSessionFile } from "../session/store.ts";
-import { clearSessionRouting } from "../providers.ts";
+import { clearSessionRouting, normalizeStructuredOutput } from "../providers.ts";
+import type { StructuredOutputSpec } from "../types/model.ts";
 import { clearInteractionChains } from "../providers/google.ts";
 import { getModel, getSubModel } from "../utils/env.ts";
 import { validateModelThinking, ensureModelCatalogFresh } from "../models/catalog.ts";
@@ -139,6 +140,10 @@ export class Agent {
   readonly tools: Record<string, ToolDefinition> = {};
   /** Normalized reasoning configuration. */
   readonly thinkingConfig?: ThinkingConfig;
+  /** Canonical structured-output request (raw `AgentConfig.output`). */
+  readonly output?: unknown;
+  /** Normalized structured-output spec sent to providers. */
+  readonly outputSpec?: StructuredOutputSpec;
   /** Cache retention/session settings. */
   readonly cacheConfig?: CacheConfig;
   /** Provider service tier. */
@@ -298,6 +303,12 @@ export class Agent {
     const mpThinking = (rawModel as any)?.thinkingLevel;
     this.thinkingConfig = normalizeThinking(config, mpThinking);
 
+    // Structured outputs: validate early so invalid schemas fail fast at construction.
+    if (config.output !== undefined && config.output !== null) {
+      this.output = config.output;
+      this.outputSpec = normalizeStructuredOutput(config.output);
+    }
+
     // DX5: cache retention short|medium|long, undefined = no explicit
     this.cacheConfig = {
       sessionId: this.sessionId,
@@ -798,6 +809,7 @@ export class Agent {
           : { ...this.cacheConfig, sessionId: runOptions?.sessionId || this.sessionId },
         serviceTier: this.serviceTier,
         sessionId: runOptions?.sessionId || this.sessionId,
+        ...(this.outputSpec ? { output: this.outputSpec } : {}),
       };
 
       const loopConfig = {
@@ -815,6 +827,7 @@ export class Agent {
         onSteerInjected: () => this.persistNow(),
         // Q-22: loop enforces these (plus local timeout races).
         limits: { ...this.runLimits },
+        ...(this.output !== undefined ? { output: this.output } : {}),
       };
 
       const res = await runAgentLoop(loopConfig);
@@ -865,6 +878,7 @@ export class Agent {
         : { ...this.cacheConfig, sessionId: runOptions?.sessionId || this.sessionId },
       serviceTier: this.serviceTier,
       sessionId: runOptions?.sessionId || this.sessionId,
+      ...(this.outputSpec ? { output: this.outputSpec } : {}),
     };
 
     const loopConfig = {
@@ -882,6 +896,7 @@ export class Agent {
       onSteerInjected: () => this.persistNow(),
       // Q-22: loop enforces these (plus local timeout races).
       limits: { ...this.runLimits },
+      ...(this.output !== undefined ? { output: this.output } : {}),
     };
 
     const s = streamAgentLoop(loopConfig);

package/src/agent/loop.ts

@@ -12,7 +12,7 @@ import { toStandardToolDeclarations } from "../tools/tool.ts";
 import { executeToolCalls } from "../tools/executor.ts";
 import { getModelFromCatalog, ensureModelCatalogFresh, validateModelThinking } from "../models/catalog.ts";
 import { preprocessFilePartsForBypass } from "../utils/documents.ts";
-import { noteProviderTurn } from "../providers.ts";
+import { noteProviderTurn, normalizeStructuredOutput, parseStructuredOutput } from "../providers.ts";
 
 /** One mid-session steer request buffered while a run is active. */
 export interface SteerEntry {
@@ -42,6 +42,12 @@ export interface AgentLoopConfig {
   steerInbox?: SteerEntry[];
   /** Called after steer entries are injected (streaming loops also push `steer_injected` events). */
   onSteerInjected?: (injectedPrompts: string[]) => void;
+  /**
+   * Canonical structured-output request (raw `AgentConfig.output`).
+   * Normalized per turn for the provider wire; validated once at the end
+   * into `AgentResponse.parsed`. Agent-level only.
+   */
+  output?: unknown;
 }
 
 /** Short preview for `steer_injected` / `queued` event payloads (bounded, display-only). */
@@ -105,6 +111,30 @@ function emitProgress(config: { onProgress?: () => void }): void {
   try { config.onProgress?.(); } catch {}
 }
 
+// ---------------------------------------------------------------------------
+// Structured outputs (canonical output wiring for the loop).
+// ---------------------------------------------------------------------------
+
+function resolveLoopOutput(config: AgentLoopConfig): { raw: unknown; spec: import("../types/model.ts").StructuredOutputSpec | undefined } {
+  const raw = (config as { output?: unknown }).output;
+  const fromOptions = (config.options as { output?: import("../types/model.ts").StructuredOutputSpec } | undefined)?.output;
+  if (raw !== undefined && raw !== null) {
+    // Throws ValidationError for invalid shapes — caught by run/stream catch
+    // with partial attached, same as other config validation.
+    const spec = normalizeStructuredOutput(raw);
+    return { raw, spec };
+  }
+  if (fromOptions) return { raw: fromOptions, spec: fromOptions };
+  return { raw: undefined, spec: undefined };
+}
+
+function parseFinalStructuredOutput(text: string, raw: unknown, spec: import("../types/model.ts").StructuredOutputSpec | undefined): unknown | undefined {
+  if (raw === undefined && spec === undefined) return undefined;
+  // Strict-fail when opted in: invalid JSON/schema throws ValidationError.
+  // Tool turns skip this (called only for final no-tool text).
+  return parseStructuredOutput(text, raw ?? spec);
+}
+
 /**
  * Normalizes `maxTurns` to a safe positive integer (default Infinity).
  * `0` means infinite (no limit), matching the `timeout: 0` convention.
@@ -493,6 +523,8 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
   const fallbackMaxTurns = normalizeMaxTurns(rawMaxTurns);
   const limits = resolveLoopLimits(config, fallbackMaxTurns);
   const maxTurns = limits.maxTurns;
+  // Structured outputs: normalize once (throws ValidationError for bad shapes).
+  const loopOutput = resolveLoopOutput(config);
   // Q-19: pre-run checkpoint for onFailure rollback.
   const preRunCp = context.checkpoint();
   const sessionIdForRollback = loopSessionId(config);
@@ -544,6 +576,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
       cache: options?.cache,
       tools: standardTools.length > 0 ? standardTools : undefined,
       signal: runOptions?.signal,
+      ...(loopOutput.spec ? { output: loopOutput.spec } : {}),
     };
     // Q-22: per-request timeout pass-through (providers honor timeoutMs).
     try {
@@ -720,8 +753,16 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
     );
   }
 
+  // Structured outputs: validate final text only (tool turns skip this).
+  // Strict-fail throws ValidationError with partial attached via catch below.
+  let parsedOutput: unknown | undefined;
+  if (loopOutput.raw !== undefined && !truncatedByMaxTurns) {
+    parsedOutput = parseFinalStructuredOutput(finalResult?.text || "", loopOutput.raw, loopOutput.spec);
+  }
+
   return new AgentResponse({
     text: finalResult?.text || "",
+    ...(parsedOutput !== undefined ? { parsed: parsedOutput } : {}),
     thinking: finalResult?.thinking,
     thoughtSignature: finalResult?.thoughtSignature,
     toolCalls: allToolCalls,
@@ -869,6 +910,17 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
       const maxTurns = streamLimits.maxTurns;
 
       const standardTools = toStandardToolDeclarations(tools);
+      // Structured outputs: normalize once for the whole stream run.
+      let streamOutputRaw: unknown;
+      let streamOutputSpec: import("../types/model.ts").StructuredOutputSpec | undefined;
+      try {
+        const resolved = resolveLoopOutput(config);
+        streamOutputRaw = resolved.raw;
+        streamOutputSpec = resolved.spec;
+      } catch (err) {
+        outerStream.fail(err instanceof Error ? err : new Error(String(err)));
+        return;
+      }
 
       accumulatedUsage = {
         inputTokens: 0,
@@ -900,6 +952,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
           cache: options?.cache,
           tools: standardTools.length > 0 ? standardTools : undefined,
           signal: linked.signal,
+          ...(streamOutputSpec ? { output: streamOutputSpec } : {}),
         };
         try {
           if (Number.isFinite(streamLimits.requestTimeoutMs) && streamLimits.requestTimeoutMs !== Infinity) {
@@ -1137,8 +1190,28 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
       }
       const truncatedFinish = canonicalFinishReason(lastResponse?.finishReason, truncatedByMaxTurns);
 
+      let streamParsed: unknown | undefined;
+      if (streamOutputRaw !== undefined && !truncatedByMaxTurns) {
+        try {
+          streamParsed = parseFinalStructuredOutput(lastResponse?.text || "", streamOutputRaw, streamOutputSpec);
+        } catch (err) {
+          const raw = err instanceof Error ? err : new Error(String(err));
+          try { (raw as unknown as { partial?: unknown }).partial ??= {
+            usage: accumulatedUsage,
+            cost: accumulatedUsage.cost,
+            turns,
+            toolCalls: allToolCalls,
+            toolResults: allToolResults,
+            text: lastResponse?.text,
+          }; } catch {}
+          outerStream.fail(raw);
+          return;
+        }
+      }
+
       const finalAgentResponse = new AgentResponse({
         text: lastResponse?.text || "",
+        ...(streamParsed !== undefined ? { parsed: streamParsed } : {}),
         thinking: lastResponse?.thinking,
         thoughtSignature: lastResponse?.thoughtSignature,
         toolCalls: allToolCalls,

package/src/index.ts

@@ -210,6 +210,15 @@ export {
   mapToolChoiceToOpenAI,
   normalizeToolChoice,
   parseStreamedToolArguments,
+  normalizeStructuredOutput,
+  extractOutputValidator,
+  parseStructuredOutput,
+  mapOutputToOpenAI,
+  mapOutputToGoogle,
+  mapOutputToOpenRouterChat,
+  mapOutputToCompatChat,
+  buildStructuredOutputInstruction,
+  augmentSystemPromptWithStructuredOutput,
 } from "./providers.ts";
 export type {
   ProviderCapabilityStatus,
@@ -217,13 +226,21 @@ export type {
   OpenRouterToolChoice,
   OpenRouterChatToolChoice,
   OpenAIToolChoice,
+  ChatCompletionsResponseFormat,
 } from "./providers.ts";
 
 export {
   GOOGLE_MODELS,
   OPENAI_MODELS,
   OPENROUTER_MODELS,
+  modelSupportsStructuredOutput,
 } from "./models/catalog.ts";
+export {
+  hasAuthHeader,
+  clampToolCallId,
+  hasTruncatedToolArguments,
+  shortHashId,
+} from "./providers/shared.ts";
 
 export {
   isValidThoughtSignature,
@@ -368,6 +385,7 @@ export type {
   ProviderRequestOptions,
   ProviderGenerateResult,
   ProviderRawData,
+  StructuredOutputSpec,
 } from "./types/model.ts";
 
 export type {
@@ -388,6 +406,7 @@ export type {
   WhenBusyMode,
   ModelRef,
   ThinkingOption,
+  StructuredOutputOption,
   SamplingConfig,
   RetryPolicyConfig,
   AgentLogger,

package/src/models/catalog.ts

@@ -138,6 +138,7 @@ function mapCapabilities(raw: any, cost: ModelCost, reasoning: boolean, toolCall
     supportsExplicitCaching: cost.cache_read !== undefined,
     supportsParallelToolCalls: toolCall,
     supportsStreaming: true,
+    supportsStructuredOutput: raw.structured_output === undefined ? true : !!raw.structured_output,
     supportsReasoningToggle: Array.isArray(raw.reasoning_options) && raw.reasoning_options.some((o: any) => o.type === "toggle"),
     supportsReasoningEffort: Array.isArray(raw.reasoning_options) && raw.reasoning_options.some((o: any) => o.type === "effort"),
     modalities: [...(modalities.input || []), ...(modalities.output || [])].filter((v: any, i: any, a: any) => a.indexOf(v) === i),
@@ -588,6 +589,30 @@ export {
   type RefreshCatalogOptions,
 } from "./catalog-cache.ts";
 
+/**
+ * True when the model can enforce `response_format`/`text.format` natively.
+ * Unknown models (custom endpoints, dynamic routers) count as capable —
+ * the provider verdict stands, matching `assertModalitiesSupported`.
+ * Models with catalog `structured_output: false` return false so callers can
+ * emulate via prompt instruction + client validation instead of 400ing.
+ *
+ * @example `modelSupportsStructuredOutput("openrouter", "inclusionai/ling-3.0-flash-sante:free")`
+ */
+export function modelSupportsStructuredOutput(provider: string, modelId: string): boolean {
+  try {
+    const spec = getModelFromCatalog(provider, modelId);
+    if (!spec) return true;
+    if (typeof spec.capabilities?.supportsStructuredOutput === "boolean") {
+      return spec.capabilities.supportsStructuredOutput;
+    }
+    const raw = (spec as { raw?: { structured_output?: unknown } }).raw;
+    if (raw && typeof raw.structured_output === "boolean") return raw.structured_output;
+    return true;
+  } catch {
+    return true;
+  }
+}
+
 /**
  * Permissive placeholder so custom endpoints never fail preflight:
  * allows every ThinkingLevel (none -> max + dynamic).
@@ -622,6 +647,7 @@ export function createGenericModelSpec(provider: string, modelId: string): Model
       supportsLongCacheRetention: false,
       supportsParallelToolCalls: true,
       supportsStreaming: true,
+      supportsStructuredOutput: true,
       modalities: ["text"],
     },
     pricing: {},

package/src/providers/google.ts

@@ -48,9 +48,11 @@ import {
   incompleteStreamError,
   combinedSignal,
   timeoutFor,
+  hasAuthHeader,
+  clampToolCallId,
 } from "./shared.ts";
 import { createGenericModelSpec } from "../models/catalog.ts";
-import { getModelFromCatalog, getModelsForProvider } from "../models/catalog.ts";
+import { getModelFromCatalog, getModelsForProvider, modelSupportsStructuredOutput } from "../models/catalog.ts";
 import {
   mapThinkingLevelToGoogle,
   mapServiceTierToGoogle,
@@ -59,6 +61,10 @@ import {
   lastProviderFor,
   noteProviderTurn,
   parseStreamedToolArguments,
+  mapOutputToGoogle,
+  normalizeStructuredOutput,
+  augmentSystemPromptWithStructuredOutput,
+  emitProviderWarning,
 } from "../providers.ts";
 
 // ---------------------------------------------------------------------------
@@ -176,7 +182,10 @@ function resolveBaseUrl(options?: ProviderRequestOptions): string {
 }
 
 function resolveApiKey(options?: ProviderRequestOptions): string | undefined {
-  return options?.apiKey || getApiKey("google", undefined, options?.env);
+  const key = getApiKey("google", options?.apiKey, options?.env);
+  if (key) return key;
+  if (hasAuthHeader(options?.headers)) return "unused";
+  return undefined;
 }
 
 function cleanModelId(model: string | ModelSpec): string {
@@ -517,11 +526,43 @@ export class GoogleInteractionsProvider implements Provider {
         input: "",
         ...(stream ? { stream: true } : {}),
       };
-      if (context.systemPrompt) body.system_instruction = context.systemPrompt;
+      // Structured outputs: native `response_format` when supported, else
+      // emulated via system instruction (catalog `structured_output: false`
+      // would 400 on the wire shape).
+      let outputEmulated = false;
+      let outputSpec: import("../types/model.ts").StructuredOutputSpec | undefined;
+      try {
+        outputSpec = normalizeStructuredOutput(options?.output ?? (options as { outputSchema?: unknown })?.outputSchema);
+      } catch {
+        outputSpec = undefined;
+      }
+      let effectiveSystemPrompt = context.systemPrompt;
+      if (outputSpec && !modelSupportsStructuredOutput("google", modelId)) {
+        outputEmulated = true;
+        effectiveSystemPrompt = augmentSystemPromptWithStructuredOutput(context.systemPrompt, outputSpec);
+        emitProviderWarning({
+          provider: "google",
+          capability: "structured output",
+          requested: `${outputSpec.name} (google/${modelId})`,
+          reason: "the catalog reports structured_output: false for this model, so native response_format is unsupported.",
+          fallback: "emulated JSON instruction + client validation (no response_format is sent)",
+        });
+      }
+      if (effectiveSystemPrompt) body.system_instruction = effectiveSystemPrompt;
       const googleTools = toGoogleTools(tools);
       if (googleTools) body.tools = googleTools;
       if (Object.keys(generationConfig).length > 0) body.generation_config = generationConfig;
       if (serviceTier) body.service_tier = serviceTier;
+      // Structured outputs: Interactions `response_format{type:text,mime_type:application/json,schema}`.
+      // Skipped when emulated (instruction already in `system_instruction`).
+      if (outputSpec && !outputEmulated) {
+        try {
+          const mapped = mapOutputToGoogle(outputSpec);
+          if (mapped) (body as unknown as Record<string, unknown>)["response_format"] = mapped.responseFormat;
+        } catch {
+          // why: invalid output shapes fail fast at Agent construction/loop validation.
+        }
+      }
 
       const prevProvider = lastProviderFor(sessionId);
       const switched = !!prevProvider && prevProvider !== "google";
@@ -564,8 +605,9 @@ export class GoogleInteractionsProvider implements Provider {
     }
     // Q-17: key travels as the `x-goog-api-key` header (never `?key=` in the
     // URL, which would leak into logs). Case-insensitive merge so a custom
-    // `X-Goog-Api-Key` never duplicates the canonical header.
-    setHeaderCaseInsensitive(headers, "x-goog-api-key", apiKey);
+    // `X-Goog-Api-Key` never duplicates the canonical header. Proxy flows
+    // (`apiKey === "unused"`) preserve custom auth instead of overwriting.
+    if (apiKey !== "unused") setHeaderCaseInsensitive(headers, "x-goog-api-key", apiKey);
     return { method: "POST", headers, body: JSON.stringify(body), signal };
   }
 
@@ -598,14 +640,21 @@ export class GoogleInteractionsProvider implements Provider {
     modelId: string
   ): void {
     if (status >= 200 && status < 300) return;
-    const { message, code, errorType } = readErrorPayload(bodyText);
-    const err: Record<string, unknown> & Error = new Error(message) as Record<string, unknown> & Error;
+    const { message, code, errorType, raw } = readErrorPayload(bodyText);
+    const hint =
+      status === 401
+        ? " Check GEMINI_API_KEY/GOOGLE_API_KEY (no quotes/spaces, correct provider), GOOGLE_BASE_URL, and that the key is loaded (bun --env-file=.env.local)."
+        : "";
+    const fullMessage = `${message}${hint}`;
+    const err: Record<string, unknown> & Error = new Error(fullMessage) as Record<string, unknown> & Error;
     (err as Record<string, unknown>)["statusCode"] = status;
     (err as Record<string, unknown>)["status"] = status;
     (err as Record<string, unknown>)["responseBody"] = bodyText.slice(0, 500);
     (err as Record<string, unknown>)["url"] = url.split("?")[0];
+    (err as Record<string, unknown>)["data"] = { error: { message: fullMessage } };
     if (code !== undefined) (err as Record<string, unknown>)["code"] = code;
     if (errorType) (err as Record<string, unknown>)["errorType"] = errorType;
+    if (raw) (err as Record<string, unknown>)["raw"] = raw;
     throw toConciseProviderError(err, "google", modelId);
   }