agent-accelerator 0.3.0 → 0.4.0

package/src/agent/subagent.ts

@@ -7,13 +7,44 @@ import { getSubModel, getModel } from "../utils/env.ts";
 /** AgentConfig alias for a delegated worker agent. */
 export interface SubAgentConfig extends AgentConfig {}
 
+/**
+ * Canonical env-based construction (Q-56): builds an `Agent` reading
+ * `MODEL`/`SUB_AGENT_MODEL` only for the fields the caller omits, via
+ * `getModel()`/`getSubModel()`. Explicit config always wins; constructing an
+ * `Agent` with an explicit `model` reads no env for routing. The static
+ * `Agent.fromEnv()` (attached below without touching `agent.ts`, owned by
+ * another audit lane) delegates here.
+ */
+export function agentFromEnv(
+  config?: Omit<AgentConfig, "model"> & { model?: AgentConfig["model"] }
+): Agent {
+  return new Agent({
+    ...config,
+    model: config?.model ?? getModel() ?? getSubModel(),
+  } as AgentConfig);
+}
+
 /**
  * SubAgent is a specialized Agent designed for modular delegation,
  * evaluation, reviewing, or parallel task execution.
  *
+ * @deprecated Prefer composing a plain `Agent` and exposing it via
+ * `agentToTool()`/`buildAgentTools()` (or `subagents: [...]`) instead of
+ * subclassing. `SubAgent` stays for compat and receives no new features.
+ *
  * It inherits 100% of the capabilities of Agent, defaults to SUB_AGENT_MODEL,
  * and provides .asTool() and .toTool() for seamless registration into parent agents.
  *
+ * Model fallback chain (Q-56, canonical): explicit `config.model` ??
+ * `SUB_AGENT_MODEL` (`getSubModel()`) ?? `MODEL` (`getModel()`). Missing
+ * everything throws. Constructing any `Agent`/`SubAgent` with an explicit
+ * `model` reads no env for routing.
+ *
+ * Q-47 decomposition boundary: this class stays a thin wrapper. The run/stream
+ * loops live in `agent.ts`/`loop.ts`, spawning in `delegation.ts`
+ * (`agentToTool`), and model parsing in `utils/session.ts` (`parseModelRef`).
+ * No loop, transport, or formatting logic is duplicated here.
+ *
  * @example
  * ```ts
  * const researcher = new SubAgent({
@@ -81,3 +112,31 @@ export class SubAgent extends Agent {
     return this.asTool(nameOverride, descriptionOverride);
   }
 }
+
+// Q-56: `Agent.fromEnv()` static without touching `agent.ts` (owned by
+// another lane). Wired at module load; typed via the declaration below so
+// `Agent.fromEnv({...})` typechecks wherever this module is imported.
+declare module "./agent.ts" {
+  namespace Agent {
+    /**
+     * Builds an `Agent` from env (`MODEL`/`SUB_AGENT_MODEL`) for omitted
+     * fields. Explicit config always wins. See `agentFromEnv`.
+     */
+    function fromEnv(
+      config?: Omit<import("../types/agent.ts").AgentConfig, "model"> & {
+        model?: import("../types/agent.ts").AgentConfig["model"];
+      }
+    ): Agent;
+  }
+}
+
+try {
+  const Ctor = Agent as unknown as {
+    fromEnv?: (config?: SubAgentConfig) => Agent;
+  };
+  if (typeof Ctor.fromEnv !== "function") {
+    Ctor.fromEnv = (config?: SubAgentConfig) => agentFromEnv(config);
+  }
+} catch {
+  // why: static attachment must never break module load (host may freeze Agent).
+}

package/src/index.ts

@@ -1,12 +1,59 @@
 import { z } from "zod";
+import type { AssistantMessageEventStream as AssistantMessageEventStreamT } from "./streaming/event-stream.ts";
+import type { AgentResponse as AgentResponseT } from "./types/response.ts";
+
+// Q-50 public API budget: ~25 core runtime exports + compat/deprecation shims.
+// Core = Agent, tool, SubAgent (deprecated alias), AgentResponse,
+// AssistantMessageEventStream, document conversion, delegation primitives,
+// provider registry, catalog, errors, and option/normalization helpers.
+// Everything else below is a shim kept for compat and marked @deprecated
+// toward a future `/internal` entry. Nothing is deleted (would break tests).
+//
+// Q-27 node split (deferred): this root entry pulls `session/store.ts`, which
+// imports `node:fs` for session persistence. A future `/node` subpath will
+// host the fs-backed persistence/telemetry surface; the root entry stays
+// runtime-agnostic. Until then, browser/bundler consumers should import the
+// documented core shims only.
+//
+// Q-51 one way to run: `run()` is canonical. `ask()` and `run/stream: true`
+// remain for compat but are deprecated — prefer `run()` for single-shot and
+// `stream()` for event iteration. `Run` (below) is the typed streaming handle.
+
+/**
+ * Typed streaming run handle (Q-51): the `AssistantMessageEventStream`
+ * returned by `stream()`/`run(stream:true)`, with its terminal `result()` and
+ * `cancel()` surfaced on the type for callers that only need the handle.
+ */
+export type Run = AssistantMessageEventStreamT & {
+  result: () => Promise<AgentResponseT>;
+  cancel: (reason?: unknown) => void;
+};
 
 // Core Agent & Tool Classes
 export { Agent, SubAgentModelError } from "./agent/agent.ts";
-export { SubAgent } from "./agent/subagent.ts";
+/**
+ * @deprecated Compat alias: prefer composing a plain `Agent` and exposing it
+ * via `agentToTool()`/`buildAgentTools()` (or `subagents: [...]`). `SubAgent`
+ * stays for compat and receives no new features (Q-56).
+ */
+export { SubAgent, agentFromEnv } from "./agent/subagent.ts";
 export type { SubAgentConfig } from "./agent/subagent.ts";
-export { tool, toStandardToolDeclarations } from "./tools/tool.ts";
+export {
+  tool,
+  toStandardToolDeclarations,
+  assertValidToolName,
+  TOOL_NAME_PATTERN,
+  normalizeThinkingV2,
+  resolveWhenBusy,
+  normalizeWorkerTimeout,
+  normalizeMaxAttempts,
+} from "./tools/tool.ts";
 export type { CreateToolOptions } from "./tools/tool.ts";
 export { zodToJsonSchema, cleanJsonSchema } from "./tools/schema.ts";
+/**
+ * @deprecated Internal executor surface. Prefer `Agent` runs; for direct
+ * execution import from the future `/internal` entry (Q-50).
+ */
 export { executeToolCalls } from "./tools/executor.ts";
 
 // Client-side document conversion (optional anydoc peer — see utils/documents.ts)
@@ -35,10 +82,23 @@ export {
   createFixedChildSessionId,
   isSessionDescendant,
   getSubAgentTrace,
+  getSubAgentTraceScoped,
   listSubAgentTraceIds,
   subscribeToSubAgent,
+  appendSubAgentStep,
+  pruneTraces,
+  trimTraceSteps,
+  checkBudget,
+  chargeBudgetUsage,
+  reserveSpawn,
+  isStreamingLoop,
+  escapeXml as escapeXmlFromDelegation,
+  MAX_SUBAGENT_TRACES,
+  SUBAGENT_TRACE_TTL_MS,
+  MAX_SUBAGENT_STEPS_PER_TRACE,
+  SUBAGENT_SUBSCRIBE_TTL_MS,
 } from "./agent/delegation.ts";
-export type { DynamicSubagentTask, AgentAsToolTarget, SubAgentTrace } from "./agent/delegation.ts";
+export type { DynamicSubagentTask, AgentAsToolTarget, SubAgentTrace, StreamingLoopHandle } from "./agent/delegation.ts";
 
 // Providers & Registry — unified multi-provider layer, all native REST
 export {
@@ -57,6 +117,9 @@ export {
   getModelThinkingInfo,
   validateModelThinking,
   getModelsForProvider,
+  registerModel,
+  clearCustomModels,
+  getModelSource,
   ThinkingLevelError,
   refreshModelCatalog,
   ensureModelCatalogFresh,
@@ -74,34 +137,56 @@ export {
 export { resolveEffectiveThinking } from "./agent/agent.ts";
 export { withRetries, isTransientError } from "./utils/retry.ts";
 export { toConciseProviderError, assertModalitiesSupported, assertNoVideoPartsOnResponses } from "./utils/errors.ts";
-// Native provider implementations. `openrouter-responses.ts` (discontinued
-// beta-Responses transport) stays importable directly but is wired nowhere.
+// Native provider implementations.
+/** @deprecated The discontinued beta-Responses transport was removed
+ * directly for frozen wire-contract evidence only. It is wired nowhere and
+ * must not be extended or re-exported here (Q-46). */
 export {
   OpenAICompatibleChatProvider,
-  OpenAICompatibleChatProvider as OpenAICompatibleProvider,
   createOpenAICompatibleProvider,
   createCustomProvider,
   CustomProvider,
 } from "./providers/openai-compat.ts";
+/**
+ * @deprecated Compat alias of `OpenAICompatibleChatProvider` (canonical).
+ * Kept for back-compat only; new code uses the canonical name (Q-50).
+ */
+export { OpenAICompatibleChatProvider as OpenAICompatibleProvider } from "./providers/openai-compat.ts";
 export type { CustomProviderOptions } from "./providers/openai-compat.ts";
 
 // Canonical provider contract (provider-agnostic) + native adapters.
 export {
   GoogleInteractionsProvider,
-  GoogleInteractionsProvider as GoogleAIStudioProvider,
   clearInteractionChains,
 } from "./providers/google.ts";
+/**
+ * @deprecated Compat alias of `GoogleInteractionsProvider` (canonical).
+ * Kept for back-compat only; new code uses the canonical name (Q-50).
+ */
+export { GoogleInteractionsProvider as GoogleAIStudioProvider } from "./providers/google.ts";
 export {
   OpenRouterChatCompletionsProvider,
-  OpenRouterChatCompletionsProvider as OpenRouterProvider,
 } from "./providers/openrouter.ts";
-// Discontinued beta-Responses transport, retained frozen as migration
-// evidence (importable via `./providers/openrouter-responses.ts`, not wired
-// anywhere): OpenRouterResponsesProvider.
+/**
+ * @deprecated Compat alias of `OpenRouterChatCompletionsProvider`
+ * (canonical). Kept for back-compat only (Q-50).
+ */
+export { OpenRouterChatCompletionsProvider as OpenRouterProvider } from "./providers/openrouter.ts";
+// Discontinued beta-Responses transport, removed from core
+// (was frozen migration evidence, wired nowhere): OpenRouterResponsesProvider.
 export {
   OpenAIResponsesProvider,
-  OpenAIResponsesProvider as OpenAIProvider,
 } from "./providers/openai.ts";
+/**
+ * @deprecated Compat alias of `OpenAIResponsesProvider` (canonical).
+ * Kept for back-compat only; new code uses the canonical name (Q-50).
+ */
+export { OpenAIResponsesProvider as OpenAIProvider } from "./providers/openai.ts";
+/**
+ * @deprecated Internal provider mappers/routing helpers. Prefer the
+ * provider-agnostic registry (`resolveModel`/`getProvider`); direct mapper
+ * use moves to the future `/internal` entry (Q-50).
+ */
 export {
   emitProviderWarning,
   clearEmittedWarnings,
@@ -161,11 +246,34 @@ export type {
 
 // Streaming & Events
 export { AssistantMessageEventStream } from "./streaming/event-stream.ts";
+/**
+ * @deprecated Internal SSE plumbing. Prefer `AssistantMessageEventStream`;
+ * direct parser use moves to the future `/internal` entry (Q-50).
+ */
 export { SSEParser } from "./streaming/sse-parser.ts";
+export type { SteerEntry } from "./agent/loop.ts";
 
 // Responses
 export { AgentResponse } from "./types/response.ts";
 
+// Core error taxonomy (Q-50 core surface)
+export {
+  AgentAccelError,
+  ConfigError,
+  ProviderError,
+  TimeoutError,
+  BudgetExceededError,
+  ToolError,
+  ValidationError,
+  SessionLoadError,
+  SecurityPolicyError,
+  isAbortError,
+  formatErrorPlain,
+} from "./types/errors.ts";
+export type { AgentAccelErrorCode, AgentAccelErrorContext } from "./types/errors.ts";
+// Normalized run limits (Q-22; sub-agents inherit unless overridden)
+export type { AgentRunLimits } from "./agent/agent.ts";
+
 // Session persistence & telemetry (conversation history + cost rollup)
 export {
   SessionTelemetry,
@@ -191,14 +299,29 @@ export {
 export type { PersistedAgentSession, SessionTotals, SessionAgentLike, LoadedSessionDir, PersistedSubAgentTrace } from "./session/store.ts";
 
 // Utilities
-export { createSessionId, hashSessionPart, createTrackingId } from "./utils/session.ts";
+/**
+ * @deprecated Session-routing internals. Prefer agent-level `sessionId`;
+ * direct use moves to the future `/internal` entry (Q-50).
+ */
+export { createSessionId, hashSessionPart, createTrackingId, nowMs, newRunId, newTurnId, previewPrompt, parseModelRef, resolveAgentConfig } from "./utils/session.ts";
+export type { ParsedModelRef, ResolvedAgentConfig } from "./utils/session.ts";
+/**
+ * @deprecated Raw env access. Prefer explicit `Agent` config (which wins over
+ * env) and `Agent.fromEnv()`/`agentFromEnv()`; direct use moves to the future
+ * `/internal` entry (Q-50).
+ */
 export { getApiKey, getEnv } from "./utils/env.ts";
 export { buildSessionHeaders } from "./utils/headers.ts";
 export { normalizeMediaInput, inferMimeType } from "./utils/media.ts";
 export { base64ToBytes, bytesToBase64 } from "./utils/base64.ts";
 export { toJsonSafe, safeStringify, escapeXml } from "./utils/serialization.ts";
 
-// Re-export Zod
+// Re-export Zod (compat only)
+/**
+ * @deprecated Compat re-export: prefer adding `zod` as a direct (peer)
+ * dependency and importing from `"zod"` (Q-50). Kept so existing
+ * `import { z } from "agent-accelerator"` code keeps working.
+ */
 export { z };
 
 // TypeScript Type Exports
@@ -233,6 +356,8 @@ export type {
   ToolCallRecord,
   ToolResultRecord,
   StandardToolDeclaration,
+  ToolLogger,
+  ToolEmitFn,
 } from "./types/tool.ts";
 
 export type {
@@ -258,50 +383,20 @@ export type {
   AgentRunOptions,
   AgentTurnEvent,
   DynamicSubagentsConfig,
+  MidSessionConfig,
+  MidSessionMode,
+  WhenBusyMode,
+  ModelRef,
+  ThinkingOption,
+  SamplingConfig,
+  RetryPolicyConfig,
+  AgentLogger,
+  ToolChoiceOption,
+  StopOption,
+  Budget,
+  BudgetState,
+  SubAgentRunIds,
 } from "./types/agent.ts";
 
- // Provider wire payload types (back-compat inspection of raw requests/responses,
-// e.g. `res.raw.request.body as OpenAIChatCompletionRequest`).
-// NOTE: wire `OpenAIToolChoice` intentionally omitted — it duplicates the
-// canonical `OpenAIToolChoice` exported above (same shape); use that one.
-export type {
-  GoogleThinkingLevel,
-  GoogleThinkingConfig,
-  GoogleFunctionCallingMode,
-  GoogleFunctionCallingConfig,
-  GoogleToolConfig,
-  GoogleFunctionDeclaration,
-  GoogleTool,
-  GoogleBlob,
-  GooglePart,
-  GoogleContent,
-  GoogleGenerationConfig,
-  GoogleCandidate,
-  GoogleUsageMetadata,
-  GoogleGenerateContentRequest,
-  GoogleGenerateContentResponse,
-  OpenRouterProviderRouting,
-  OpenRouterReasoning,
-  OpenRouterParameters,
-  OpenRouterUsage,
-  OpenRouterChatRequest,
-  OpenRouterResponse,
-  OpenAIMessageRole,
-  OpenAIReasoningEffort,
-  OpenAIServiceTier,
-  OpenAITextPart,
-  OpenAIImageUrlPart,
-  OpenAIInputAudioPart,
-  OpenAIVideoUrlPart,
-  OpenAIContentPart,
-  OpenAIToolCall,
-  OpenAIMessage,
-  OpenAITool,
-  OpenAIUsage,
-  OpenAIChoice,
-  OpenAIDelta,
-  OpenAIChunkChoice,
-  OpenAIChatCompletionRequest,
-  OpenAIChatCompletionResponse,
-  OpenAIChatCompletionChunk,
-} from "./types/provider-payloads.ts";
+// Minimalist core: harness modules (RLM/RSI, OTel, testing, CLI doctor, hooks,
+// context-ops, run-tree/record, session-store, legacy wire types) live in userland.

package/src/models/catalog-cache.ts

@@ -1,13 +1,21 @@
 import * as path from "node:path";
 import * as fs from "node:fs";
+import { createHash } from "node:crypto";
 import { getEnv } from "../utils/env.ts";
 
 /** Default TTL: 12 Hours (in milliseconds). */
 export const DEFAULT_CATALOG_TTL_MS = 12 * 60 * 60 * 1000;
 
+/** Max accepted models.dev payload size: 15MB (Q-16a). Larger payloads are rejected before parse. */
+export const MAX_CATALOG_PAYLOAD_BYTES = 15 * 1024 * 1024;
+
 let globalCatalogTtlMs = DEFAULT_CATALOG_TTL_MS;
 
-/** Sets the global model catalog cache TTL in milliseconds. */
+/** Sets the global model catalog cache TTL in milliseconds.
+ * Note (Q-16a): cache files carry their own `ttlMs`. A global `setCatalogTTL`
+ * does not rewrite in-flight file TTLs; it takes effect on the next refresh
+ * (fresh download) or when the cached file has no `ttlMs` of its own.
+ */
 export function setCatalogTTL(ttlMs: number): void {
   if (Number.isFinite(ttlMs) && ttlMs > 0) {
     globalCatalogTtlMs = ttlMs;
@@ -77,9 +85,9 @@ export function getCacheDir(): string {
   return path.resolve(process.cwd(), "src/data");
 }
 
-/** Non-configurable cache file path: src/data/models.dev.json */
+/** Cache file path: `<cacheDir>/models.dev.json`, honoring AGENT_CACHE_DIR (Q-16a/Q-34). */
 export function getCacheFilePath(): string {
-  return path.resolve(process.cwd(), "src/data/models.dev.json");
+  return path.join(getCacheDir(), "models.dev.json");
 }
 
 function readJsonFileSync(filePath: string): any {
@@ -97,7 +105,20 @@ function writeJsonFileSync(filePath: string, data: any): void {
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
   }
-  fs.writeFileSync(filePath, JSON.stringify(data), "utf-8");
+  // Atomic tmp+rename with 0600 so a crash never leaves half-written JSON (Q-16a).
+  const rand = Math.random().toString(36).slice(2, 10);
+  const tmp = `${filePath}.tmp-${process.pid}-${rand}`;
+  fs.writeFileSync(tmp, JSON.stringify(data), { encoding: "utf-8", mode: 0o600 });
+  try { fs.chmodSync(tmp, 0o600); } catch {}
+  fs.renameSync(tmp, filePath);
+}
+
+/** Verifies optional sha256 pin from MODELS_DEV_SHA256 (Q-16a). Returns false on mismatch. */
+export function verifyCatalogSha256(text: string): boolean {
+  const pin = getEnv("MODELS_DEV_SHA256")?.trim().toLowerCase();
+  if (!pin) return true;
+  const hex = createHash("sha256").update(text, "utf8").digest("hex").toLowerCase();
+  return hex === pin;
 }
 
 // In-memory catalog state
@@ -225,6 +246,17 @@ export async function refreshModelCatalog(options: RefreshCatalogOptions = {}):
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   let freshData: Record<string, any>;
 
+  const fallbackToDiskCache = (): void => {
+    const existing = readJsonFileSync(cachePath);
+    if (existing && existing.data) {
+      activeCatalog = existing.data;
+      activeFetchedAt = existing.fetchedAt;
+      activeTtlMs = existing.ttlMs || effectiveTtl;
+      activeFromCache = true;
+      notifyUpdateListeners();
+    }
+  };
+
   try {
     const res = await fetch(apiUrl, {
       headers: {
@@ -238,33 +270,40 @@ export async function refreshModelCatalog(options: RefreshCatalogOptions = {}):
       throw new Error(`HTTP ${res.status} ${res.statusText}`);
     }
 
-    freshData = (await res.json()) as Record<string, any>;
+    // Q-16a: size-cap before parse (check text length, reject >15MB).
+    const text = await res.text();
+    if (text.length > MAX_CATALOG_PAYLOAD_BYTES) {
+      clearTimeout(timer);
+      fallbackToDiskCache();
+      return getCatalogStatus();
+    }
+    // Q-16a: optional sha256 pin via MODELS_DEV_SHA256.
+    if (!verifyCatalogSha256(text)) {
+      clearTimeout(timer);
+      fallbackToDiskCache();
+      return getCatalogStatus();
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      clearTimeout(timer);
+      fallbackToDiskCache();
+      return getCatalogStatus();
+    }
+    freshData = parsed as Record<string, any>;
 
     // Never let a non-catalog payload (mocked fetch, proxy error page,
     // chat-completion stub) overwrite the good on-disk cache.
     if (!isValidCatalogPayload(freshData)) {
       clearTimeout(timer);
-      const existing = readJsonFileSync(cachePath);
-      if (existing && existing.data) {
-        activeCatalog = existing.data;
-        activeFetchedAt = existing.fetchedAt;
-        activeTtlMs = existing.ttlMs || effectiveTtl;
-        activeFromCache = true;
-        notifyUpdateListeners();
-      }
+      fallbackToDiskCache();
       return getCatalogStatus();
     }
   } catch (err: any) {
     clearTimeout(timer);
     // If download fails, retain disk cache if available
-    const existing = readJsonFileSync(cachePath);
-    if (existing && existing.data) {
-      activeCatalog = existing.data;
-      activeFetchedAt = existing.fetchedAt;
-      activeTtlMs = existing.ttlMs || effectiveTtl;
-      activeFromCache = true;
-      notifyUpdateListeners();
-    }
+    fallbackToDiskCache();
     return getCatalogStatus();
   } finally {
     clearTimeout(timer);
@@ -281,19 +320,23 @@ export async function refreshModelCatalog(options: RefreshCatalogOptions = {}):
 
   // Update in-memory state FIRST so a read-only filesystem still serves the
   // fresh catalog for this process; disk persistence below is best-effort.
+  // Q-34: a real download is NOT from cache.
   activeCatalog = freshData;
   activeFetchedAt = fetchedAt;
   activeTtlMs = effectiveTtl;
-  activeFromCache = true;
+  activeFromCache = false;
 
   // Save to src/data/models.dev.json (or the AGENT_CACHE_DIR override)
   try {
     writeJsonFileSync(cachePath, cachePayload);
   } catch (err) {
     activeFromCache = false;
-    console.warn(
-      `[Agent Accelerator] Could not write model catalog cache to ${cachePath} (${err instanceof Error ? err.message : String(err)}). Continuing with the in-memory catalog.`
-    );
+    try {
+      (globalThis as any).__agentAccelTelemetry?.emitWarning?.({
+        code: "catalog_cache_write_failed",
+        message: `[Agent Accelerator] Could not write model catalog cache (${err instanceof Error ? err.message : String(err)}). Continuing with the in-memory catalog.`,
+      });
+    } catch {}
   }
 
   notifyUpdateListeners();