agent-accelerator 0.4.0 → 0.4.5

package/src/types/agent.ts

@@ -7,6 +7,7 @@ import type {
 } from "./core.ts";
 import type { ModelProviderInstance } from "../providers/registry.ts";
 import type { Agent } from "../agent/agent.ts";
+import type { z } from "zod";
 
 // ---------------------------------------------------------------------------
 // Q-52/Q-53/Q-54 canonical option types (all additive; nothing renamed).
@@ -61,6 +62,17 @@ export type ToolChoiceOption =
 /** Canonical stop control (Q-54): sequence(s) halting generation. */
 export type StopOption = string | string[];
 
+/** Canonical structured-output input (Q-61). Zod, JSON Schema, or explicit form. */
+export type StructuredOutputOption =
+  | z.ZodType
+  | Record<string, unknown>
+  | {
+      name?: string;
+      description?: string;
+      schema: z.ZodType | Record<string, unknown>;
+      strict?: boolean;
+    };
+
 /** Configuration used to construct an {@link Agent}. */
 export interface AgentConfig {
   /** Display name used in tool and sub-agent metadata. */
@@ -142,9 +154,12 @@ export interface AgentConfig {
   /** Deterministic seed, when the provider supports it. */
   seed?: number;
   /**
-   * Optional output schema (Zod or JSON Schema, stored as `unknown` so `zod`
+   * Optional output schema (Zod, JSON Schema, or `{ name, schema, strict }`,
+   * see `StructuredOutputOption`, stored as `unknown` so `zod`
    * stays optional for type-only consumers). Agent-level only; per-run
-   * overrides are intentionally unsupported.
+   * overrides are intentionally unsupported. When set, the model answer is
+   * constrained to the schema on all providers and `AgentResponse.parsed`
+   * carries the validated value.
    */
   output?: unknown;
   /** Retry policy for provider calls. */

package/src/types/model.ts

@@ -87,6 +87,7 @@ export interface ModelCapabilities {
   supportsLongCacheRetention?: boolean;
   supportsParallelToolCalls?: boolean;
   supportsStreaming?: boolean;
+  supportsStructuredOutput?: boolean;
   modalities?: ("text" | "image" | "audio" | "video" | "pdf")[];
   // derived
   supportsReasoningToggle?: boolean;
@@ -138,6 +139,24 @@ export interface ModelSpec {
   raw?: RawModelData;
 }
 
+// ---------------------------------------------------------------------------
+// Structured outputs — normalized, provider-agnostic spec.
+// Canonical input is `AgentConfig.output` (Zod, JSON Schema, or explicit
+// `{ name, schema, strict }`); `normalizeStructuredOutput` in
+// `src/providers.ts` produces this shape for adapters.
+// ---------------------------------------------------------------------------
+/** Normalized structured-output request passed from Agent to providers. */
+export interface StructuredOutputSpec {
+  /** Format name (1-64 chars, `[a-zA-Z0-9_-]`). Defaults to `structured_output`. */
+  name: string;
+  /** JSON Schema for the final answer (already converted from Zod when needed). */
+  schema: Record<string, unknown>;
+  /** Strict schema adherence (OpenAI/OpenRouter only; ignored by Google). Defaults to true. */
+  strict?: boolean;
+  /** Optional description of what the format is for. */
+  description?: string;
+}
+
 // ---------------------------------------------------------------------------
 // Provider plumbing — unchanged API
 // ---------------------------------------------------------------------------
@@ -156,6 +175,8 @@ export interface ProviderRequestOptions {
   env?: Record<string, string>;
   maxRetries?: number;
   maxRetryDelayMs?: number;
+  /** Normalized structured-output spec (see `normalizeStructuredOutput`). */
+  output?: StructuredOutputSpec;
 }
 
 /** Auditable request/response wire payload captured in AgentResponse. */

package/src/types/response.ts

@@ -101,6 +101,8 @@ export function normalizeFinishReason(raw?: string): {
 /** JSON representation returned by AgentResponse.toJSON(). */
 export interface AgentResponseJSON {
   text: string;
+  /** Validated structured-output value when `AgentConfig.output` was set. */
+  parsed?: unknown;
   thinking?: string;
   thoughtSignature?: string;
   toolCalls?: ToolCallRecord[];
@@ -121,6 +123,8 @@ export interface AgentResponseJSON {
 /** Normalized final result returned by every Agent run. */
 export class AgentResponse {
   readonly text: string;
+  /** Validated structured-output value when `AgentConfig.output` was set. */
+  readonly parsed?: unknown;
   readonly thinking?: string;
   readonly thoughtSignature?: string;
   readonly toolCalls: ToolCallRecord[];
@@ -146,6 +150,7 @@ export class AgentResponse {
    */
   constructor(data: {
     text: string;
+    parsed?: unknown;
     thinking?: string;
     thoughtSignature?: string;
     toolCalls?: ToolCallRecord[];
@@ -162,6 +167,7 @@ export class AgentResponse {
     turns?: number;
   }) {
     this.text = data.text;
+    if (data.parsed !== undefined) (this as { parsed?: unknown }).parsed = data.parsed;
     this.thinking = data.thinking;
     this.thoughtSignature = data.thoughtSignature;
     this.toolCalls = data.toolCalls ?? [];
@@ -187,6 +193,7 @@ export class AgentResponse {
   toJSON(): AgentResponseJSON {
     return {
       text: this.text,
+      ...(this.parsed !== undefined ? { parsed: this.parsed } : {}),
       thinking: this.thinking,
       thoughtSignature: this.thoughtSignature,
       toolCalls: this.toolCalls.length > 0 ? this.toolCalls : undefined,

package/src/utils/env.ts

@@ -9,7 +9,10 @@
  */
 export function getEnv(key: string, fallback?: string): string | undefined {
   if (typeof process !== "undefined" && process.env && process.env[key]) {
-    return process.env[key];
+    // Trim quotes/whitespace from .env files (`sk-..."\n` -> 401 otherwise).
+    const raw = String(process.env[key]);
+    const trimmed = raw.trim().replace(/^["']|["']$/g, "").trim();
+    if (trimmed) return trimmed;
   }
   return fallback;
 }
@@ -22,20 +25,31 @@ export type ProviderEnv = Record<string, string>;
  * @example `const key = getApiKey("google");`
  */
 export function getApiKey(provider: string, explicitKey?: string, env?: ProviderEnv): string | undefined {
-  if (explicitKey) return explicitKey;
+  const clean = (v: unknown): string | undefined => {
+    if (typeof v !== "string") return undefined;
+    const t = v.trim().replace(/^["']|["']$/g, "").trim();
+    return t || undefined;
+  };
+  const cleanedExplicit = clean(explicitKey);
+  if (cleanedExplicit) return cleanedExplicit;
   // ProviderEnv override takes precedence (agent-accel inspiration, SDK-light)
   if (env) {
     const upper = `${provider.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`;
-    if (env[upper]) return env[upper];
+    const fromEnv = clean(env[upper]);
+    if (fromEnv) return fromEnv;
     // google aliases
     if (provider.toLowerCase().startsWith("google") || provider.toLowerCase() === "gemini") {
-      if (env["GEMINI_API_KEY"]) return env["GEMINI_API_KEY"];
-      if (env["GOOGLE_API_KEY"]) return env["GOOGLE_API_KEY"];
+      const g1 = clean(env["GEMINI_API_KEY"]);
+      if (g1) return g1;
+      const g2 = clean(env["GOOGLE_API_KEY"]);
+      if (g2) return g2;
     }
     // openai aliases
     if (provider.toLowerCase() === "openai") {
-      if (env["OPENAI_BASE_API_KEY"]) return env["OPENAI_BASE_API_KEY"];
-      if (env["OPENAI_API_KEY"]) return env["OPENAI_API_KEY"];
+      const o1 = clean(env["OPENAI_BASE_API_KEY"]);
+      if (o1) return o1;
+      const o2 = clean(env["OPENAI_API_KEY"]);
+      if (o2) return o2;
     }
   }
 

package/src/utils/errors.ts

@@ -54,7 +54,18 @@ export function toConciseProviderError(error: unknown, providerId: string, model
   const err = error as any;
   const status = readStatus(err);
   const url = readUrl(err);
-  const detail = readProviderMessage(err);
+  let detail = readProviderMessage(err);
+  // Append OpenRouter-style raw metadata once (pi api/openai-completions.ts:719
+  // rule): normalize already stringifies error.error, so only append raw when
+  // absent to avoid double-printing.
+  const rawMeta =
+    (typeof err?.raw === "string" && err.raw.trim() ? err.raw.trim() : undefined) ??
+    (typeof err?.error?.metadata?.raw === "string" && err.error.metadata.raw.trim()
+      ? err.error.metadata.raw.trim()
+      : undefined);
+  if (rawMeta && !detail.includes(rawMeta.slice(0, 80))) {
+    detail = `${detail}\n${rawMeta.slice(0, 500)}`.slice(0, 800);
+  }
   const concise = new Error(
     `[${displayModel(providerId, modelId)}] request failed${status ? ` (${status})` : ""}: ${detail}`
   );
@@ -75,6 +86,9 @@ export function toConciseProviderError(error: unknown, providerId: string, model
     ...(typeof err?.errorType === "string"
       ? { errorType: { value: err.errorType, enumerable: false } }
       : {}),
+    ...(typeof (err as { raw?: unknown })?.raw === "string"
+      ? { raw: { value: (err as { raw: string }).raw.slice(0, 500), enumerable: false } }
+      : {}),
   });
   return concise;
 }

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.4.0";
+  return "0.4.5";
 }
 
 function getAgentAccelUserAgent(): string {