agent-accelerator 0.1.0

package/src/types/agent.ts

@@ -0,0 +1,87 @@
+import type { ProviderId, ModelSpec } from "./model.ts";
+import type { ToolDefinition } from "./tool.ts";
+import type {
+  ThinkingLevel,
+  CacheConfig,
+  ServiceTier,
+} from "./core.ts";
+import type { ModelProviderInstance } from "../ai-sdk/registry.ts";
+import type { Agent } from "../agent/agent.ts";
+
+/** Configuration used to construct an {@link Agent}. */
+export interface AgentConfig {
+  /** Display name used in tool and sub-agent metadata. */
+  name?: string;
+  /** Human-readable description used when this agent is delegated to. */
+  description?: string;
+  /** Stable system instructions for the agent. */
+  instructions?: string;
+  /** Model string (`provider/model`), catalog spec, or ModelProvider helper result. */
+  model?: string | ModelSpec | ModelProviderInstance;
+  /** Developer-only model for dynamically spawned sub-agents. Never exposed to the Main Agent LLM. */
+  subagentModel?: string | ModelSpec | ModelProviderInstance;
+  /** Dynamic sub-agent spawning policy. `subagents` lists pre-defined workers; this enables LLM-spawned stateless workers. */
+  dynamicSubagents?: DynamicSubagentsConfig;
+  /** Per-agent API key override. */
+  apiKey?: string;
+  /** Per-agent provider base URL override. */
+  baseUrl?: string;
+  /** Tools exposed to the model, keyed by name or supplied as an array. */
+  tools?: Record<string, ToolDefinition> | ToolDefinition[];
+  /** Requested reasoning level, validated against the model catalog. */
+  thinkingLevel?: ThinkingLevel;
+  /** Prompt-cache retention and session-affinity settings. */
+  cache?: CacheConfig;
+  /** Provider service tier, when supported. */
+  serviceTier?: ServiceTier;
+  /** Stable conversation/cache session ID. */
+  sessionId?: string;
+  /** Headers merged into every provider request. */
+  headers?: Record<string, string>;
+  /** Maximum model/tool turns per run. Defaults to 10. */
+  maxTurns?: number;
+  /** Fixed worker agents exposed as delegation tools. */
+  subagents?: (Agent | { name: string; description: string; agent: Agent })[];
+  /** Clears conversation state before and after every run. */
+  stateless?: boolean;
+}
+
+/** Developer-configured policy for LLM-spawned dynamic sub-agents. */
+export interface DynamicSubagentsConfig {
+  /** Enables the automatic `spawn_subagents` tool. Defaults to true when the object is present. */
+  enabled?: boolean;
+  /** Developer-only worker model override. Never choosable by the Main Agent LLM. Falls back to top-level `subagentModel`, then `SUB_AGENT_MODEL` env, then the parent model. */
+  model?: string | ModelSpec | ModelProviderInstance;
+  /** Max workers the Main Agent may spawn in a single `spawn_subagents` call. Extras are trimmed safely. Defaults to 4. */
+  maxSpawn?: number;
+  /** Fixed reasoning level for all dynamic workers. The Main Agent cannot override it. Falls back to the parent level when omitted. */
+  thinkingLevel?: ThinkingLevel;
+  /** Tool pool available to dynamic workers. Workers receive zero tools unless the Main Agent grants a per-task `tools` subset by name. */
+  tools?: Record<string, ToolDefinition> | ToolDefinition[];
+  /** Per-worker timeout in ms. `0` (default) = no limit. `-1` = the Main Agent sets a per-task `timeoutMs`. `>0` = fixed timeout for every worker. */
+  timeout?: number;
+}
+
+/** Per-run overrides for {@link Agent.run}, {@link Agent.ask}, and {@link Agent.stream}. */
+export interface AgentRunOptions {
+  /** Per-run reasoning-level override, validated against the selected model. */
+  thinkingLevel?: ThinkingLevel;
+  /** Return a streaming object instead of waiting for a final response. */
+  stream?: boolean;
+  /** Cancels provider, tool, and sub-agent work. */
+  signal?: AbortSignal;
+  /** Overrides the agent session for this run. */
+  sessionId?: string;
+  /** Context added only to this user turn, preserving the stable system prompt. */
+  additionalContext?: string;
+  /** Headers merged for this run only. */
+  headers?: Record<string, string>;
+  /** Called for each text delta as it streams (only when stream:true). */
+  onDelta?: (delta: string, event: import("./response.ts").StreamEvent) => void;
+  /** Called for each thinking/reasoning delta (only when stream:true). */
+  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;
+}

package/src/types/core.ts

@@ -0,0 +1,86 @@
+/**
+ * Level-based reasoning — single flag for all levels (bloatfree)
+ */
+/** Public reasoning control accepted by AgentConfig. */
+export type ThinkingLevel =
+  | "none"
+  | "dynamic"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh";
+
+// Internal normalized config (SDK-internal, not exposed as Agent flag)
+/** Internal normalized reasoning configuration passed to providers. */
+export interface ThinkingConfig {
+  enabled?: boolean;
+  level?: ThinkingLevel;
+  budgetTokens?: number;
+  budget?: number;
+  thinking_budget?: number;
+  includeThoughts?: boolean;
+}
+
+/**
+ * Cache retention:
+ * - "implicit": automatic prefix caching ($0.00 storage fee, session affinity preserved)
+ * - "short": 5 minutes explicit TTL
+ * - "medium": 1 hour explicit TTL
+ * - "long": 12 hours explicit TTL
+ * - undefined: no explicit caching enforced (implicit may still happen)
+ */
+/** Prompt-cache retention policy. */
+export type CacheRetention = "implicit" | "short" | "medium" | "long";
+
+/** Prompt-cache IDs, retention, TTL, and session-affinity settings. */
+export interface CacheConfig {
+  /**
+   * Retention duration:
+   * - "implicit": automatic prefix caching ($0.00 storage fee, no explicit cloud cache entities created)
+   * - "short": 5 minutes TTL
+   * - "medium": 1 hour TTL
+   * - "long": 12 hours TTL
+   * - undefined: no explicit caching enforced (implicit may still happen)
+   */
+  retention?: CacheRetention;
+  /**
+   * Explicit cache ID / reference if using pre-created context cache
+   */
+  cachedContentId?: string;
+  /**
+   * Session ID for cache affinity routing (e.g. x-session-id, x-opencode-session)
+   */
+  sessionId?: string;
+  /**
+   * Explicit TTL in seconds for created caches (overrides retention mapping)
+   */
+  ttlSeconds?: number;
+}
+
+/**
+ * Service tier controls — bloatfree: only flex / priority (standard is default, no flag needed)
+ */
+/** Optional provider service-priority routing tier. */
+export type ServiceTier = "flex" | "priority";
+
+/**
+ * Token and cost usage — actual provider values, not heuristic
+ */
+/** Normalized provider usage and optional calculated cost. */
+export interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+  cachedTokens?: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+  thinkingTokens?: number;
+  cost?: {
+    inputCost?: number;
+    outputCost?: number;
+    cacheReadCost?: number;
+    cacheWriteCost?: number;
+    totalCost?: number;
+  };
+}

package/src/types/message.ts

@@ -0,0 +1,115 @@
+/**
+ * Multimodal input modalities supported: Text, Image, Audio, Video, File
+ */
+
+/** Text content within a multimodal message. */
+export interface TextPart {
+  type: "text";
+  text: string;
+  thoughtSignature?: string;
+}
+
+/** Image content accepted as a URL, data, path, or binary value. */
+export interface ImagePart {
+  type: "image";
+  /**
+   * Raw base64 data, data URL (data:image/...;base64,...), remote URL (https://...), or local file path
+   */
+  image: string | Uint8Array | ArrayBuffer;
+  mimeType?: string;
+}
+
+/** Audio content accepted as a URL, data, path, or binary value. */
+export interface AudioPart {
+  type: "audio";
+  /**
+   * Raw base64 data, data URL (data:audio/...;base64,...), remote URL, or local file path
+   */
+  audio: string | Uint8Array | ArrayBuffer;
+  mimeType?: string;
+}
+
+/** File/document content (PDF, text, etc.) accepted as a URL, data, path, or binary value. */
+export interface FilePart {
+  type: "file";
+  /**
+   * Raw base64 data, data URL (data:...;base64,...), remote URL (https://...), or local file path
+   */
+  file: string | Uint8Array | ArrayBuffer;
+  mimeType?: string;
+  filename?: string;
+}
+
+/** Video content accepted as a URL, data, path, or binary value. */
+export interface VideoPart {
+  type: "video";
+  /**
+   * Raw base64 data, data URL (data:video/...;base64,...), remote URL, or local file path
+   */
+  video: string | Uint8Array | ArrayBuffer;
+  mimeType?: string;
+}
+
+/** Assistant-generated structured tool invocation. */
+export interface ToolCallPart {
+  type: "tool_call";
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+  /**
+   * Raw stringified arguments if available
+   */
+  rawArguments?: string;
+  /**
+   * Optional Gemini thought signature associated with this tool call
+   */
+  thoughtSignature?: string;
+}
+
+/** Tool execution result returned to the model context. */
+export interface ToolResultPart {
+  type: "tool_result";
+  id: string;
+  name: string;
+  result: unknown;
+  isError?: boolean;
+}
+
+/** Provider reasoning/thinking content. */
+export interface ThinkingPart {
+  type: "thinking";
+  thinking: string;
+  thoughtSignature?: string;
+}
+
+/** Any supported text, media, reasoning, tool-call, or tool-result part. */
+export type ContentPart =
+  | TextPart
+  | ImagePart
+  | AudioPart
+  | VideoPart
+  | FilePart
+  | ToolCallPart
+  | ToolResultPart
+  | ThinkingPart;
+
+export type MessageRole = "system" | "user" | "assistant" | "tool";
+
+/** Normalized conversation message. */
+export interface Message {
+  role: MessageRole;
+  content: string | ContentPart[];
+  name?: string;
+  thoughtSignature?: string;
+}
+
+/**
+ * Normalized input context passed to AI providers
+ */
+/** Provider-neutral prompt context passed into generate/stream calls. */
+export interface ProviderContext {
+  systemPrompt?: string;
+  messages: Message[];
+  tools?: Record<string, unknown>[];
+  cachedContentId?: string;
+}

package/src/types/model.ts

@@ -0,0 +1,212 @@
+import type { ThinkingConfig, CacheConfig, ServiceTier, TokenUsage } from "./core.ts";
+import type { ProviderContext, Message, ContentPart } from "./message.ts";
+import type { StandardToolDeclaration, ToolCallRecord } from "./tool.ts";
+import type { AssistantMessageEventStream } from "../streaming/event-stream.ts";
+
+// ---------------------------------------------------------------------------
+// Provider identity — battle-tested: matches models.dev provider keys
+// Known first-class: google | opencode | openrouter, plus aliases. Allow string for future.
+// ---------------------------------------------------------------------------
+/** Supported provider IDs plus arbitrary custom prefixes. */
+export type ProviderId = "google" | "opencode" | "opencode-go" | "openrouter" | "openai" | (string & {});
+
+// ---------------------------------------------------------------------------
+// Raw models.dev shapes — battle-tested, 1:1 with https://models.dev/api.json
+// ---------------------------------------------------------------------------
+export interface ModelLimit {
+  /** Total context window (input + output). Canonical field: limit.context */
+  context: number;
+  /** Max output tokens. Canonical: limit.output */
+  output: number;
+  /** Optional extra limits (e.g. input) */
+  input?: number;
+  [k: string]: unknown;
+}
+
+export interface ModelCost {
+  input?: number; // $ per 1M input tokens
+  output?: number; // $ per 1M output tokens
+  cache_read?: number;
+  cache_write?: number;
+  // provider-specific: input_audio, etc.
+  input_audio?: number;
+  // tiered pricing when context > threshold
+  tiers?: Array<{
+    tier: { type: string; size: number };
+    input: number;
+    output: number;
+    cache_read?: number;
+  }>;
+  context_over_200k?: { input: number; output: number; cache_read: number };
+  [k: string]: unknown;
+}
+
+export interface ModelModalities {
+  input: Array<"text" | "image" | "audio" | "video" | "pdf">;
+  output: Array<"text" | "image" | "audio" | "video">;
+}
+
+export type ReasoningOption =
+  | { type: "toggle" }
+  | { type: "effort"; values: string[] }
+  | { type: "budget_tokens"; min: number; max: number };
+
+export interface RawModelData {
+  id: string;
+  name: string;
+  description?: string;
+  family?: string;
+  attachment?: boolean;
+  reasoning?: boolean;
+  reasoning_options?: ReasoningOption[];
+  tool_call?: boolean;
+  structured_output?: boolean;
+  temperature?: boolean;
+  knowledge?: string;
+  release_date?: string;
+  last_updated?: string;
+  status?: string;
+  open_weights?: boolean;
+  modalities?: ModelModalities;
+  limit?: ModelLimit;
+  cost?: ModelCost;
+  provider?: { npm?: string; api?: string };
+  api?: string;
+  [k: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Capabilities — normalized, battle-tested from raw flags
+// ---------------------------------------------------------------------------
+export interface ModelCapabilities {
+  supportsThinking?: boolean;
+  supportsThinkingBudget?: boolean;
+  supportsThinkingLevel?: boolean;
+  supportsImplicitCaching?: boolean;
+  supportsExplicitCaching?: boolean;
+  supportsLongCacheRetention?: boolean;
+  supportsParallelToolCalls?: boolean;
+  supportsStreaming?: boolean;
+  modalities?: ("text" | "image" | "audio" | "video" | "pdf")[];
+  // derived
+  supportsReasoningToggle?: boolean;
+  supportsReasoningEffort?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Pricing — normalized per-1M
+// ---------------------------------------------------------------------------
+export interface ModelPricing {
+  inputPerMillion?: number;
+  outputPerMillion?: number;
+  cacheReadPerMillion?: number;
+  cacheWritePerMillion?: number;
+  inputAudioPerMillion?: number;
+}
+
+// ---------------------------------------------------------------------------
+// ModelSpec — battle-tested, single source from models.dev
+// Keep legacy aliases contextWindow/maxOutputTokens for BC, plus full raw.
+// ---------------------------------------------------------------------------
+/** Normalized model catalog entry used for routing, validation, and pricing. */
+export interface ModelSpec {
+  id: string;
+  provider: ProviderId;
+  name: string;
+  description?: string;
+  family?: string;
+  api?: string; // agent-accel-style: openai-completions | openai-responses | anthropic-messages | google-generative-ai etc.
+  /** @deprecated alias for limit.context */
+  contextWindow: number;
+  /** @deprecated alias for limit.output */
+  maxOutputTokens: number;
+  // Full battle-tested fields (optional for BC with stale per-provider files, required when from catalog)
+  limit?: ModelLimit;
+  cost?: ModelCost;
+  modalities?: ModelModalities;
+  reasoning?: boolean;
+  reasoning_options?: ReasoningOption[];
+  tool_call?: boolean;
+  attachment?: boolean;
+  knowledge?: string;
+  release_date?: string;
+  last_updated?: string;
+  capabilities: ModelCapabilities;
+  pricing?: ModelPricing;
+  compat?: Record<string, unknown>;
+  // raw passthrough for advanced checks
+  raw?: RawModelData;
+}
+
+// ---------------------------------------------------------------------------
+// Provider plumbing — unchanged API
+// ---------------------------------------------------------------------------
+/** Request controls passed from Agent to a provider implementation. */
+export interface ProviderRequestOptions {
+  apiKey?: string;
+  baseUrl?: string;
+  headers?: Record<string, string>;
+  thinking?: ThinkingConfig;
+  cache?: CacheConfig;
+  serviceTier?: ServiceTier;
+  tools?: StandardToolDeclaration[];
+  toolChoice?: "auto" | "none" | "required" | { type: "function"; function: { name: string } };
+  signal?: AbortSignal;
+  sessionId?: string;
+  env?: Record<string, string>;
+  maxRetries?: number;
+  maxRetryDelayMs?: number;
+}
+
+/** Auditable request/response wire payload captured in AgentResponse. */
+export interface ProviderRawData {
+  request: {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body: unknown;
+  };
+  response?: {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: unknown;
+  };
+}
+
+/** Normalized single provider generation result. */
+export interface ProviderGenerateResult {
+  text: string;
+  thinking?: string;
+  thoughtSignature?: string;
+  toolCalls?: ToolCallRecord[];
+  usage: TokenUsage;
+  finishReason?: string;
+  responseId?: string;
+  model: string;
+  provider: ProviderId;
+  raw: ProviderRawData;
+  durationMs: number;
+}
+
+/** Provider contract implemented by the AI-SDK transport layer. */
+export interface Provider {
+  id: ProviderId;
+  name: string;
+  models: ModelSpec[];
+  getModel(modelId: string): ModelSpec | undefined;
+  generate(
+    model: string | ModelSpec,
+    context: ProviderContext,
+    options?: ProviderRequestOptions
+  ): Promise<ProviderGenerateResult>;
+  stream(
+    model: string | ModelSpec,
+    context: ProviderContext,
+    options?: ProviderRequestOptions
+  ): AssistantMessageEventStream;
+  countTokens(
+    model: string | ModelSpec,
+    context: ProviderContext
+  ): Promise<number>;
+}