agent-accelerator 0.3.0 → 0.4.5

package/src/types/response.ts

@@ -43,9 +43,66 @@ export interface SubAgentExecutionMetadata {
   steps?: SubAgentStep[];
 }
 
+/** Canonical finish reasons surfaced on AgentResponse (provider-agnostic).
+ * Vendors use varied strings (`end_turn`, `stop_sequence`, `max_tokens`,
+ * `tool_use`, ...); adapters map them to these values and preserve the
+ * original in `rawFinishReason`. Unknown non-empty reasons map to `"error"`.
+ * The `(string & {})` extension keeps vendor passthrough assignable at
+ * provider call sites that forward raw strings (normalize with
+ * `normalizeFinishReason` to canonicalize). */
+export type FinishReason =
+  | "stop"
+  | "tool_calls"
+  | "length"
+  | "content_filter"
+  | "refusal"
+  | "max_turns"
+  | "error"
+  | (string & {});
+
+/** Maps a vendor finish reason to canonical FinishReason + raw passthrough.
+ * Known aliases collapse to the canonical set; empty/undefined stays
+ * undefined; any other non-empty string maps to `"error"` with the original
+ * preserved in `rawFinishReason` (Q-04). */
+export function normalizeFinishReason(raw?: string): {
+  finishReason?: FinishReason;
+  rawFinishReason?: string;
+} {
+  if (raw === undefined || raw === null || raw === "") return {};
+  const r = String(raw);
+  const lower = r.toLowerCase();
+  const map: Record<string, FinishReason> = {
+    stop: "stop",
+    end_turn: "stop",
+    stop_sequence: "stop",
+    completed: "stop",
+    complete: "stop",
+    done: "stop",
+    tool_calls: "tool_calls",
+    tool_use: "tool_calls",
+    function_call: "tool_calls",
+    tool_call: "tool_calls",
+    length: "length",
+    max_tokens: "length",
+    max_turns: "max_turns",
+    content_filter: "content_filter",
+    refusal: "refusal",
+    refused: "refusal",
+    error: "error",
+    failed: "error",
+    cancelled: "error",
+    canceled: "error",
+  };
+  const mapped = map[lower] ?? map[r];
+  if (mapped) return r === mapped ? { finishReason: mapped } : { finishReason: mapped, rawFinishReason: r };
+  return { finishReason: "error", rawFinishReason: r };
+}
+
 /** 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[];
@@ -55,7 +112,9 @@ export interface AgentResponseJSON {
   responseId?: string;
   model: string;
   provider: ProviderId | string;
-  finishReason?: string;
+  finishReason?: FinishReason;
+  /** Original vendor finish string when it differs from canonical `finishReason` (Q-04). */
+  rawFinishReason?: string;
   durationMs: number;
   raw: ProviderRawData;
   turns: number;
@@ -64,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[];
@@ -73,7 +134,9 @@ export class AgentResponse {
   readonly responseId?: string;
   readonly model: string;
   readonly provider: ProviderId | string;
-  readonly finishReason?: string;
+  readonly finishReason?: FinishReason;
+  /** Original vendor finish string when it differs from canonical `finishReason` (Q-04). */
+  readonly rawFinishReason?: string;
   readonly durationMs: number;
   readonly raw: ProviderRawData;
   readonly turns: number;
@@ -87,6 +150,7 @@ export class AgentResponse {
    */
   constructor(data: {
     text: string;
+    parsed?: unknown;
     thinking?: string;
     thoughtSignature?: string;
     toolCalls?: ToolCallRecord[];
@@ -96,12 +160,14 @@ export class AgentResponse {
     responseId?: string;
     model: string;
     provider: ProviderId | string;
-    finishReason?: string;
+    finishReason?: FinishReason;
+    rawFinishReason?: string;
     durationMs: number;
     raw: ProviderRawData;
     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 ?? [];
@@ -112,6 +178,7 @@ export class AgentResponse {
     this.model = data.model;
     this.provider = data.provider;
     this.finishReason = data.finishReason;
+    this.rawFinishReason = data.rawFinishReason;
     this.durationMs = data.durationMs;
     this.raw = data.raw;
     this.turns = data.turns ?? 1;
@@ -126,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,
@@ -136,6 +204,7 @@ export class AgentResponse {
       model: this.model,
       provider: this.provider,
       finishReason: this.finishReason,
+      rawFinishReason: this.rawFinishReason,
       durationMs: this.durationMs,
       raw: this.raw,
       turns: this.turns,
@@ -156,8 +225,12 @@ export type StreamEventType =
   | "tool_call_delta"
   | "tool_call_complete"
   | "tool_result"
+  | "tool_start"
+  | "tool_end"
   | "subagent_complete"
   | "subagent_delta"
+  | "steer_injected"
+  | "queued"
   | "usage"
   | "done"
   | "error";
@@ -165,18 +238,75 @@ export type StreamEventType =
 /** Payload for one streaming text, thinking, tool, usage, or lifecycle event. */
 export interface StreamEvent {
   type: StreamEventType;
+  /** Schema version for typed consumers (Q-40). Currently always 1 when present. */
+  schemaVersion?: 1;
   delta?: string;
   thinkingDelta?: string;
   toolCall?: ToolCallRecord;
   toolResult?: ToolResultRecord;
+  /** Batch tool calls for `tool_start` events (Q-40). */
+  toolCalls?: ToolCallRecord[];
+  /** Batch tool results for `tool_end` events (Q-40). */
+  toolResults?: ToolResultRecord[];
   subagent?: SubAgentExecutionMetadata;
   /** Tracking id of the worker emitting a `subagent_delta` event. */
   subagentTrackingId?: string;
+  /** Steered prompt text injected via `steer()` (`steer_injected` events). */
+  injectedPrompt?: string;
+  /** Queued prompt text accepted as a next-turn follow-up (`queued` events). */
+  queuedPrompt?: string;
+  /** Pending queue length at the time of a `queued`/`steer_injected` event. */
+  queueLength?: number;
   usage?: TokenUsage;
   responseId?: string;
+  /** Canonical finish reason when known; vendor strings pass through as-is
+   * for provider compat (normalize with `normalizeFinishReason`). */
   finishReason?: string;
+  /** Original vendor finish string when it differs from canonical (Q-04). */
+  rawFinishReason?: string;
   error?: Error | unknown;
   partialText?: string;
   partialThinking?: string;
   raw?: ProviderRawData;
 }
+
+/** Typed (discriminated) stream event schema, version 1 (Q-40).
+ * `StreamEvent` stays the permissive compat shape; use this union when you
+ * want exhaustive switching (e.g. `tool_start`/`tool_end` lifecycle). */
+export type StreamEventV2 =
+  | { schemaVersion: 1; type: "start"; responseId?: string }
+  | { schemaVersion: 1; type: "text_start"; responseId?: string }
+  | { schemaVersion: 1; type: "text_delta"; delta: string; partialText?: string }
+  | { schemaVersion: 1; type: "text_end"; partialText?: string }
+  | { schemaVersion: 1; type: "thinking_start"; responseId?: string }
+  | { schemaVersion: 1; type: "thinking_delta"; thinkingDelta: string; partialThinking?: string }
+  | { schemaVersion: 1; type: "thinking_end"; partialThinking?: string }
+  | { schemaVersion: 1; type: "tool_call_start"; toolCall: ToolCallRecord }
+  | { schemaVersion: 1; type: "tool_call_delta"; toolCall: ToolCallRecord; delta?: string }
+  | { schemaVersion: 1; type: "tool_call_complete"; toolCall: ToolCallRecord }
+  | { schemaVersion: 1; type: "tool_result"; toolResult: ToolResultRecord }
+  | { schemaVersion: 1; type: "tool_start"; toolCalls: ToolCallRecord[] }
+  | { schemaVersion: 1; type: "tool_end"; toolResults: ToolResultRecord[] }
+  | { schemaVersion: 1; type: "subagent_complete"; subagent: SubAgentExecutionMetadata }
+  | {
+      schemaVersion: 1;
+      type: "subagent_delta";
+      subagentTrackingId: string;
+      delta?: string;
+      thinkingDelta?: string;
+      partialText?: string;
+      partialThinking?: string;
+    }
+  | { schemaVersion: 1; type: "steer_injected"; injectedPrompt: string; queueLength?: number }
+  | { schemaVersion: 1; type: "queued"; queuedPrompt: string; queueLength?: number }
+  | { schemaVersion: 1; type: "usage"; usage: TokenUsage }
+  | {
+      schemaVersion: 1;
+      type: "done";
+      delta?: string;
+      usage?: TokenUsage;
+      finishReason?: FinishReason | string;
+      rawFinishReason?: string;
+      responseId?: string;
+    }
+  | { schemaVersion: 1; type: "error"; error: Error | unknown };

package/src/types/tool.ts

@@ -1,5 +1,16 @@
 import type { z } from "zod";
 
+/** Minimal logger surface accepted by tool contexts (Q-54/Q-55, additive). */
+export interface ToolLogger {
+  debug?: (...args: unknown[]) => void;
+  info?: (...args: unknown[]) => void;
+  warn?: (...args: unknown[]) => void;
+  error?: (...args: unknown[]) => void;
+}
+
+/** Live-event emitter handed to tools that stream progress (Q-55, additive). */
+export type ToolEmitFn = (event: { type: string; [k: string]: unknown }) => void;
+
 export interface ToolExecutionContext {
   /** Unique ID for the model-generated invocation. */
   toolCallId: string;
@@ -11,6 +22,13 @@ export interface ToolExecutionContext {
   sessionId?: string;
   /** Forwards live sub-agent deltas (used by `spawn_subagents` for realtime tracking). */
   onSubagentEvent?: (event: { trackingId: string; delta?: string; thinkingDelta?: string; partialText?: string; partialThinking?: string }) => void;
+  // Q-55 Tool API v2 context additions (all optional, additive).
+  /** Stable id for this run (`newRunId`). Mirrors SubAgentRunIds.runId. */
+  runId?: string;
+  /** Live-event emitter for tools that stream progress. */
+  emit?: ToolEmitFn;
+  /** Structured logger for tool implementations (defaults to no-op). */
+  logger?: ToolLogger;
 }
 
 export type ToolExecuteFn<TInput = any, TOutput = any> = (
@@ -37,6 +55,57 @@ export interface ToolDefinition<TInput = any, TOutput = any> {
   maxConcurrency?: number | string;
   /** Function executed after validation; its result is made JSON-safe for model context. */
   execute: ToolExecuteFn<TInput, TOutput>;
+  // Q-55 Tool API v2 additions (all optional, additive; loop reads via `(toolDef as any).*`).
+  /**
+   * Canonical alias for `maxTries`. When both are set, `maxTries` wins.
+   * Normalized by `normalizeMaxAttempts` (see tools/tool.ts).
+   */
+  maxAttempts?: number | string;
+  /**
+   * Whether this tool is safe to retry on transient failures. Retry defaults
+   * to a single attempt unless this is `true` (bounded retries) or `maxTries`/
+   * `maxAttempts` explicitly overrides the attempt count.
+   */
+  idempotent?: boolean;
+  /**
+   * Explicit retry policy. Preferred over bare `maxTries` for new code;
+   * `maxTries`/`maxAttempts` map to `{ maxRetries: n - 1 }`.
+   */
+  retry?: { maxRetries?: number; baseDelayMs?: number; maxDelayMs?: number };
+  /**
+   * Whether an identical call may repeat across consecutive turns. Defaults to
+   * `true` for idempotent tools, `false` otherwise. Honored by repeat guards.
+   */
+  repeatable?: boolean;
+  /**
+   * Maximum characters of a string tool result kept for model context.
+   * Longer strings are truncated with a `[Truncated: ...]` marker.
+   * `0`/omitted uses the executor default (20000).
+   */
+  maxResultChars?: number | string;
+  /** Optional hook to redact/replace the error message sent back to the model. */
+  redactError?: (err: unknown) => string;
+  /**
+   * Canonical alias for `redactError`. When both are set, `redactError` wins.
+   * Kept short for Q-55 Tool API v2 parity.
+   */
+  redact?: (err: unknown) => string;
+  /** Free-form tags for grouping/filtering tools (e.g. `["web", "readonly"]`). */
+  tags?: string[];
+  /**
+   * When true, the host must approve this call before execution (human-in-the-
+   * loop). The loop reads via `(toolDef as any).needsApproval`; enforcement
+   * is wired by the host, default open (undefined = no gate).
+   */
+  needsApproval?: boolean;
+  /**
+   * Optional output schema (Zod or JSON Schema) used to validate/coerce the
+   * tool's return value before it reaches model context. Stored as `unknown`
+   * so `zod` stays an optional peer for type-only consumers.
+   */
+  output?: unknown;
+  /** Opaque brand marker narrowing bare object literals to `tool()` output. */
+  readonly __brand?: "ToolDefinition";
 }
 
 export interface StandardToolDeclaration {

package/src/update-models.ts

@@ -8,10 +8,12 @@
  *   bun src/update-models.ts --ttl=24h
  */
 
-import { refreshModelCatalog, getCatalogStatus } from "./index.ts";
+import { refreshModelCatalog } from "./index.ts";
+import { ConfigError } from "./types/errors.ts";
 
 const args = process.argv.slice(2);
-const force = args.includes("--force") || !args.some((a) => a.startsWith("--ttl"));
+// Q-34: force is true only with explicit --force (previously also true when no --ttl).
+const force = args.includes("--force");
 
 let customTtlMs: number | undefined;
 for (const arg of args) {
@@ -24,6 +26,10 @@ for (const arg of args) {
     } else {
       customTtlMs = parseFloat(val);
     }
+    // Q-34: reject non-numeric TTLs (e.g. --ttl=abc) instead of silently caching NaN.
+    if (!Number.isFinite(customTtlMs)) {
+      throw new ConfigError(`Invalid --ttl value "${val}": expected a number with optional h/m suffix (e.g. --ttl=24h).`);
+    }
   }
 }
 

package/src/utils/cache.ts

@@ -8,7 +8,6 @@
  */
 
 import type { CacheRetention } from "../types/core.ts";
-import type { ModelSpec } from "../types/model.ts";
 import { getApiKey } from "./env.ts";
 
 const CACHE_KEY_MAX = 64;
@@ -144,3 +143,71 @@ export async function createExplicitCache(
 
   return (await response.json()) as CachedContentMetadata;
 }
+
+// ---------------------------------------------------------------------------
+// Central redaction helpers (Q-11, temporary home to avoid owner conflicts).
+// Providers must call these instead of maintaining local deny-lists.
+// ---------------------------------------------------------------------------
+
+/** Header-name deny-list (case-insensitive substring match). */
+const REDACT_HEADER_SUBSTRINGS = ["key", "token", "secret", "cookie", "authorization"];
+
+/** Secret-looking value prefixes. */
+const REDACT_VALUE_PREFIXES = ["sk-", "AIza", "gsk-", "xox-"];
+
+function headerNameIsSensitive(name: string): boolean {
+  const lower = String(name ?? "").toLowerCase();
+  return REDACT_HEADER_SUBSTRINGS.some((s) => lower.includes(s));
+}
+
+function valueLooksSensitive(value: unknown): boolean {
+  if (typeof value !== "string") return false;
+  const v = value.trim();
+  if (REDACT_VALUE_PREFIXES.some((p) => v.includes(p))) return true;
+  // Bearer-style long tokens: "Bearer <20+ chars>"
+  if (/^bearer\s+\S{20,}/i.test(v)) return true;
+  return false;
+}
+
+/**
+ * Redacts a single value: sensitive strings become "[REDACTED]" (Q-11).
+ */
+export function redactValue(value: unknown): unknown {
+  if (typeof value !== "string") return value;
+  if (valueLooksSensitive(value)) return "[REDACTED]";
+  return value;
+}
+
+/**
+ * Redacts sensitive header values (Q-11). Returns a shallow copy; input untouched.
+ * Deny-list (name contains): *key*, *token*, *secret*, cookie, authorization.
+ * Value patterns (redacted regardless of name): sk-, AIza, gsk-, xox-.
+ */
+export function redactHeadersCentral(
+  headers: Record<string, unknown> | undefined | null
+): Record<string, unknown> {
+  if (!headers || typeof headers !== "object") return {};
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (headerNameIsSensitive(k) || valueLooksSensitive(v)) out[k] = "[REDACTED]";
+    else out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Redacts secret-looking substrings inside free text (Q-11).
+ * Replaces `sk-...`, `AIza...`, `gsk-...`, `xox-...` tokens with "[REDACTED]".
+ */
+export function redactText(text: string): string {
+  if (typeof text !== "string" || !text) return text;
+  // Note: longer prefixes (gsk-/gsk_) first so the generic sk- pattern
+  // does not partially match inside them (e.g. "gsk-abc" -> one token).
+  return text
+    .replace(/gsk_[A-Za-z0-9]{8,}/g, "[REDACTED]")
+    .replace(/gsk-[A-Za-z0-9-_]{8,}/g, "[REDACTED]")
+    .replace(/xox-[A-Za-z0-9-]{8,}/g, "[REDACTED]")
+    .replace(/AIza[A-Za-z0-9-_]{10,}/g, "[REDACTED]")
+    .replace(/sk-[A-Za-z0-9-_]{8,}/g, "[REDACTED]")
+    .replace(/Bearer\s+[A-Za-z0-9\-._~+/=]{20,}/gi, "Bearer [REDACTED]");
+}

package/src/utils/env.ts

@@ -2,16 +2,17 @@
  * Safe environment lookup for API keys and configurations
  */
 /**
- * Reads an environment/global value without assuming a Node-only runtime.
+ * Reads an environment value. Process env only. No globalThis fallback:
+ * DOM-clobberable in browsers (Q-05).
  *
  * @example `const apiKey = getEnv("OPENAI_API_KEY");`
  */
 export function getEnv(key: string, fallback?: string): string | undefined {
   if (typeof process !== "undefined" && process.env && process.env[key]) {
-    return process.env[key];
-  }
-  if (typeof globalThis !== "undefined" && (globalThis as any)[key]) {
-    return (globalThis as any)[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;
 }
@@ -24,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;
     }
   }
 
@@ -53,8 +65,6 @@ export function getApiKey(provider: string, explicitKey?: string, env?: Provider
       return getEnv("OPENROUTER_API_KEY");
     case "openai":
       return getEnv("OPENAI_BASE_API_KEY") || getEnv("OPENAI_API_KEY");
-    case "anthropic":
-      return getEnv("ANTHROPIC_API_KEY");
     default:
       return getEnv(`${provider.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`);
   }

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;
 }