agent-accelerator 0.1.0

package/src/types/provider-payloads.ts

@@ -0,0 +1,434 @@
+/**
+ * Provider wire payload and schema types for complete backwards compatibility.
+ * All providers use Vercel AI SDK under the hood, but these types allow existing
+ * applications and tests to type-check requests and responses seamlessly.
+ */
+
+// ============================================================================
+// Google AI Studio Payload Types
+// ============================================================================
+
+export type GoogleThinkingLevel = "OFF" | "MINIMAL" | "LOW" | "MEDIUM" | "HIGH";
+
+export interface GoogleThinkingConfig {
+  thinkingLevel?: GoogleThinkingLevel;
+  includeThoughts?: boolean;
+}
+
+export type GoogleFunctionCallingMode = "AUTO" | "NONE" | "ANY";
+
+export interface GoogleFunctionCallingConfig {
+  mode: GoogleFunctionCallingMode;
+  allowedFunctionNames?: string[];
+}
+
+export interface GoogleToolConfig {
+  functionCallingConfig?: GoogleFunctionCallingConfig;
+}
+
+export interface GoogleFunctionDeclaration {
+  name: string;
+  description?: string;
+  parameters?: Record<string, unknown>;
+}
+
+export interface GoogleTool {
+  functionDeclarations?: GoogleFunctionDeclaration[];
+}
+
+export interface GoogleBlob {
+  mimeType: string;
+  data: string; // base64
+}
+
+export interface GooglePart {
+  text?: string;
+  inlineData?: GoogleBlob;
+  functionCall?: {
+    name: string;
+    args: Record<string, unknown>;
+    id?: string;
+    thoughtSignature?: string;
+  };
+  functionResponse?: {
+    name: string;
+    response: Record<string, unknown>;
+    id?: string;
+  };
+  thought?: boolean;
+  thoughtSignature?: string;
+}
+
+export interface GoogleContent {
+  role: "user" | "model" | "function";
+  parts: GooglePart[];
+}
+
+export interface GoogleGenerationConfig {
+  temperature?: number;
+  topP?: number;
+  topK?: number;
+  candidateCount?: number;
+  maxOutputTokens?: number;
+  stopSequences?: string[];
+  responseMimeType?: string;
+  thinkingConfig?: GoogleThinkingConfig;
+}
+
+export interface GoogleCandidate {
+  content?: GoogleContent;
+  finishReason?: string;
+  index?: number;
+  safetyRatings?: Array<Record<string, unknown>>;
+  groundingMetadata?: Record<string, unknown>;
+}
+
+export interface GoogleUsageMetadata {
+  promptTokenCount?: number;
+  candidatesTokenCount?: number;
+  totalTokenCount?: number;
+  cachedContentTokenCount?: number;
+}
+
+export interface GoogleGenerateContentRequest {
+  contents: GoogleContent[];
+  systemInstruction?: GoogleContent | { parts: GooglePart[] };
+  tools?: GoogleTool[];
+  toolConfig?: GoogleToolConfig;
+  generationConfig?: GoogleGenerationConfig;
+  cachedContent?: string;
+}
+
+export interface GoogleGenerateContentResponse {
+  candidates?: GoogleCandidate[];
+  usageMetadata?: GoogleUsageMetadata;
+  modelVersion?: string;
+}
+
+// ============================================================================
+// OpenCode Payload Types
+// ============================================================================
+
+export type OpenCodeReasoningEffort = "low" | "medium" | "high";
+export type OpenCodePromptCacheRetention = "none" | "1h" | "24h";
+
+export interface OpenCodeCacheControl {
+  type: "ephemeral";
+  ttl?: "1h";
+}
+
+export interface OpenCodeUsage {
+  prompt_tokens?: number;
+  completion_tokens?: number;
+  total_tokens?: number;
+  prompt_tokens_details?: {
+    cached_tokens?: number;
+    cache_read?: number;
+    cache_creation?: number;
+  };
+}
+
+export interface OpenCodeChatRequest {
+  model: string;
+  messages: any[];
+  tools?: any[];
+  tool_choice?: any;
+  temperature?: number;
+  top_p?: number;
+  max_tokens?: number;
+  stop?: string | string[];
+  stream?: boolean;
+  reasoning_effort?: OpenCodeReasoningEffort;
+  prompt_cache_retention?: OpenCodePromptCacheRetention;
+  session_id?: string;
+}
+
+export interface OpenCodeChatResponse {
+  id?: string;
+  object?: string;
+  created?: number;
+  model?: string;
+  choices?: Array<{
+    index?: number;
+    message?: any;
+    delta?: any;
+    finish_reason?: string;
+  }>;
+  usage?: OpenCodeUsage;
+}
+
+export interface OpenCodeResponsesInputItem {
+  role: string;
+  content: any;
+  cache_control?: OpenCodeCacheControl;
+}
+
+export interface OpenCodeResponsesOutputItem {
+  id?: string;
+  type?: string;
+  status?: string;
+  content?: any;
+  name?: string;
+  call_id?: string;
+  arguments?: string;
+}
+
+export interface OpenCodeResponsesRequest {
+  model: string;
+  input: OpenCodeResponsesInputItem[];
+  tools?: any[];
+  parameters?: Record<string, unknown>;
+  session_id?: string;
+}
+
+export interface OpenCodeResponsesResponse {
+  id?: string;
+  output?: OpenCodeResponsesOutputItem[];
+  usage?: OpenCodeUsage;
+}
+
+// ============================================================================
+// OpenRouter Payload Types
+// ============================================================================
+
+export interface OpenRouterProviderRouting {
+  order?: string[];
+  allow_fallbacks?: boolean;
+  require_parameters?: boolean;
+  data_collection?: "allow" | "deny";
+  ignore?: string[];
+  quantizations?: string[];
+}
+
+export interface OpenRouterReasoning {
+  effort?: "high" | "medium" | "low";
+  max_tokens?: number;
+  exclude?: boolean;
+}
+
+export interface OpenRouterParameters {
+  temperature?: number;
+  top_p?: number;
+  top_k?: number;
+  max_tokens?: number;
+  seed?: number;
+  stop?: string | string[];
+  repetition_penalty?: number;
+  presence_penalty?: number;
+  frequency_penalty?: number;
+  reasoning?: OpenRouterReasoning;
+  provider?: OpenRouterProviderRouting;
+  transforms?: string[];
+  models?: string[];
+  route?: "fallback";
+}
+
+export interface OpenRouterUsage {
+  prompt_tokens?: number;
+  completion_tokens?: number;
+  total_tokens?: number;
+  cached_tokens?: number;
+  prompt_tokens_details?: {
+    cached_tokens?: number;
+  };
+  total_cost?: number;
+}
+
+export interface OpenRouterChatRequest {
+  model: string;
+  messages: any[];
+  tools?: any[];
+  tool_choice?: any;
+  stream?: boolean;
+  temperature?: number;
+  top_p?: number;
+  top_k?: number;
+  max_tokens?: number;
+  seed?: number;
+  stop?: string | string[];
+  reasoning?: OpenRouterReasoning;
+  provider?: OpenRouterProviderRouting;
+  transforms?: string[];
+  models?: string[];
+  route?: "fallback";
+}
+
+export interface OpenRouterResponse {
+  id?: string;
+  model?: string;
+  choices?: Array<{
+    index?: number;
+    message?: any;
+    delta?: any;
+    finish_reason?: string;
+  }>;
+  usage?: OpenRouterUsage;
+}
+
+// ============================================================================
+// OpenAI Payload Types
+// ============================================================================
+
+export type OpenAIMessageRole = "system" | "user" | "assistant" | "tool";
+export type OpenAIReasoningEffort = "low" | "medium" | "high";
+export type OpenAIServiceTier = "auto" | "default";
+
+export interface OpenAITextPart {
+  type: "text";
+  text: string;
+}
+
+export interface OpenAIImageUrlPart {
+  type: "image_url";
+  image_url: {
+    url: string;
+    detail?: "auto" | "low" | "high";
+  };
+}
+
+export interface OpenAIInputAudioPart {
+  type: "input_audio";
+  input_audio: {
+    data: string;
+    format: "wav" | "mp3";
+  };
+}
+
+export interface OpenAIVideoUrlPart {
+  type: "video_url";
+  video_url: {
+    url: string;
+  };
+}
+
+export type OpenAIContentPart =
+  | OpenAITextPart
+  | OpenAIImageUrlPart
+  | OpenAIInputAudioPart
+  | OpenAIVideoUrlPart;
+
+export interface OpenAIToolCall {
+  id: string;
+  type: "function";
+  function: {
+    name: string;
+    arguments: string;
+  };
+  extra_content?: {
+    google?: {
+      thought_signature?: string;
+    };
+  };
+}
+
+export interface OpenAIMessage {
+  role: OpenAIMessageRole;
+  content: string | OpenAIContentPart[];
+  name?: string;
+  tool_call_id?: string;
+  tool_calls?: OpenAIToolCall[];
+  reasoning_content?: string;
+}
+
+export interface OpenAITool {
+  type: "function";
+  function: {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    strict?: boolean;
+  };
+}
+
+export type OpenAIToolChoice =
+  | "none"
+  | "auto"
+  | "required"
+  | { type: "function"; function: { name: string } };
+
+export interface OpenAIUsage {
+  prompt_tokens: number;
+  completion_tokens: number;
+  total_tokens: number;
+  prompt_tokens_details?: {
+    cached_tokens?: number;
+  };
+  completion_tokens_details?: {
+    reasoning_tokens?: number;
+  };
+}
+
+export interface OpenAIChoice {
+  index: number;
+  message: {
+    role: "assistant";
+    content: string | null;
+    reasoning_content?: string;
+    tool_calls?: OpenAIToolCall[];
+  };
+  finish_reason: "stop" | "length" | "tool_calls" | "content_filter" | null;
+}
+
+export interface OpenAIDelta {
+  role?: string;
+  content?: string | null;
+  reasoning_content?: string;
+  tool_calls?: Array<{
+    index: number;
+    id?: string;
+    type?: "function";
+    function?: {
+      name?: string;
+      arguments?: string;
+    };
+    extra_content?: {
+      google?: {
+        thought_signature?: string;
+      };
+    };
+  }>;
+}
+
+export interface OpenAIChunkChoice {
+  index: number;
+  delta: OpenAIDelta;
+  finish_reason: "stop" | "length" | "tool_calls" | "content_filter" | null;
+}
+
+export interface OpenAIChatCompletionRequest {
+  model: string;
+  messages: OpenAIMessage[];
+  tools?: OpenAITool[];
+  tool_choice?: OpenAIToolChoice;
+  temperature?: number;
+  top_p?: number;
+  max_tokens?: number;
+  max_completion_tokens?: number;
+  stop?: string | string[];
+  stream?: boolean;
+  stream_options?: { include_usage?: boolean };
+  reasoning_effort?: OpenAIReasoningEffort;
+  service_tier?: OpenAIServiceTier;
+  response_format?: { type: "text" | "json_object" };
+}
+
+export interface OpenAIChatCompletionResponse {
+  id: string;
+  object: string;
+  created: number;
+  model: string;
+  choices: OpenAIChoice[];
+  usage?: OpenAIUsage;
+  service_tier?: string;
+  system_fingerprint?: string;
+}
+
+export interface OpenAIChatCompletionChunk {
+  id: string;
+  object: string;
+  created: number;
+  model: string;
+  choices: OpenAIChunkChoice[];
+  usage?: OpenAIUsage;
+  system_fingerprint?: string;
+}

package/src/types/response.ts

@@ -0,0 +1,158 @@
+import type { TokenUsage } from "./core.ts";
+import type { ToolCallRecord, ToolResultRecord } from "./tool.ts";
+import type { ProviderRawData, ProviderId } from "./model.ts";
+
+/** Per-worker result and usage metadata attached to an AgentResponse. */
+export interface SubAgentExecutionMetadata {
+  name: string;
+  role?: string;
+  task: string;
+  model: string;
+  provider: ProviderId | string;
+  durationMs: number;
+  usage: TokenUsage;
+  turns: number;
+  finishReason?: string;
+  responseId?: string;
+  text: string;
+  thinking?: string;
+  toolCalls?: ToolCallRecord[];
+  raw?: ProviderRawData;
+  isError?: boolean;
+  error?: string;
+}
+
+/** JSON representation returned by AgentResponse.toJSON(). */
+export interface AgentResponseJSON {
+  text: string;
+  thinking?: string;
+  thoughtSignature?: string;
+  toolCalls?: ToolCallRecord[];
+  toolResults?: ToolResultRecord[];
+  subagents?: SubAgentExecutionMetadata[];
+  usage: TokenUsage;
+  responseId?: string;
+  model: string;
+  provider: ProviderId | string;
+  finishReason?: string;
+  durationMs: number;
+  raw: ProviderRawData;
+  turns: number;
+}
+
+/** Normalized final result returned by every Agent run. */
+export class AgentResponse {
+  readonly text: string;
+  readonly thinking?: string;
+  readonly thoughtSignature?: string;
+  readonly toolCalls: ToolCallRecord[];
+  readonly toolResults: ToolResultRecord[];
+  readonly subagents: SubAgentExecutionMetadata[];
+  readonly usage: TokenUsage;
+  readonly responseId?: string;
+  readonly model: string;
+  readonly provider: ProviderId | string;
+  readonly finishReason?: string;
+  readonly durationMs: number;
+  readonly raw: ProviderRawData;
+  readonly turns: number;
+
+  /**
+   * Constructs a normalized response. Agent runs create this automatically;
+   * construct one directly when adapting a custom provider integration.
+   *
+   * @param data Response text, model metadata, usage, timing, and optional
+   * tool/sub-agent records.
+   */
+  constructor(data: {
+    text: string;
+    thinking?: string;
+    thoughtSignature?: string;
+    toolCalls?: ToolCallRecord[];
+    toolResults?: ToolResultRecord[];
+    subagents?: SubAgentExecutionMetadata[];
+    usage: TokenUsage;
+    responseId?: string;
+    model: string;
+    provider: ProviderId | string;
+    finishReason?: string;
+    durationMs: number;
+    raw: ProviderRawData;
+    turns?: number;
+  }) {
+    this.text = data.text;
+    this.thinking = data.thinking;
+    this.thoughtSignature = data.thoughtSignature;
+    this.toolCalls = data.toolCalls ?? [];
+    this.toolResults = data.toolResults ?? [];
+    this.subagents = data.subagents ?? [];
+    this.usage = data.usage;
+    this.responseId = data.responseId;
+    this.model = data.model;
+    this.provider = data.provider;
+    this.finishReason = data.finishReason;
+    this.durationMs = data.durationMs;
+    this.raw = data.raw;
+    this.turns = data.turns ?? 1;
+  }
+
+  /** Returns the final assistant text. */
+  toString(): string {
+    return this.text;
+  }
+
+  /** Returns a JSON-safe representation including usage, tools, and raw wire data. */
+  toJSON(): AgentResponseJSON {
+    return {
+      text: this.text,
+      thinking: this.thinking,
+      thoughtSignature: this.thoughtSignature,
+      toolCalls: this.toolCalls.length > 0 ? this.toolCalls : undefined,
+      toolResults: this.toolResults.length > 0 ? this.toolResults : undefined,
+      subagents: this.subagents.length > 0 ? this.subagents : undefined,
+      usage: this.usage,
+      responseId: this.responseId,
+      model: this.model,
+      provider: this.provider,
+      finishReason: this.finishReason,
+      durationMs: this.durationMs,
+      raw: this.raw,
+      turns: this.turns,
+    };
+  }
+}
+
+/** Event names emitted by AssistantMessageEventStream. */
+export type StreamEventType =
+  | "start"
+  | "text_start"
+  | "text_delta"
+  | "text_end"
+  | "thinking_start"
+  | "thinking_delta"
+  | "thinking_end"
+  | "tool_call_start"
+  | "tool_call_delta"
+  | "tool_call_complete"
+  | "tool_result"
+  | "subagent_complete"
+  | "usage"
+  | "done"
+  | "error";
+
+/** Payload for one streaming text, thinking, tool, usage, or lifecycle event. */
+export interface StreamEvent {
+  type: StreamEventType;
+  delta?: string;
+  thinkingDelta?: string;
+  toolCall?: ToolCallRecord;
+  toolResult?: ToolResultRecord;
+  subagent?: SubAgentExecutionMetadata;
+  usage?: TokenUsage;
+  responseId?: string;
+  finishReason?: string;
+  error?: Error | unknown;
+  partialText?: string;
+  partialThinking?: string;
+  raw?: ProviderRawData;
+}

package/src/types/tool.ts

@@ -0,0 +1,61 @@
+import type { z } from "zod";
+
+export interface ToolExecutionContext {
+  /** Unique ID for the model-generated invocation. */
+  toolCallId: string;
+  /** Name of the owning agent, when invoked through an Agent. */
+  agentName?: string;
+  /** Abort signal for parent cancellation or a tool timeout. */
+  signal?: AbortSignal;
+  /** Session identifier associated with this invocation. */
+  sessionId?: string;
+}
+
+export type ToolExecuteFn<TInput = any, TOutput = any> = (
+  input: TInput,
+  context: ToolExecutionContext
+) => Promise<TOutput> | TOutput;
+
+export interface ToolDefinition<TInput = any, TOutput = any> {
+  /** Optional public name; record keys are used when omitted. */
+  name?: string;
+  /** Description shown to the model when selecting tools. */
+  description: string;
+  /** Zod schema (or JSON Schema object) used to validate the model input. */
+  input?: z.ZodType<TInput> | Record<string, unknown>;
+  /** Explicit JSON Schema, taking precedence over `input` for provider declarations. */
+  parameters?: Record<string, unknown>;
+  /** Whether providers should enforce strict function-argument validation. */
+  strict?: boolean;
+  /** Maximum best-effort wall-clock time for one execution attempt in milliseconds. 0/undefined means no bound. Cancellation is cooperative via `signal`. */
+  timeoutMs?: number;
+  /** Maximum total attempts for transient failures. 0/undefined means no configured retry limit. */
+  maxTries?: number | string;
+  /** Maximum simultaneous calls for this tool. 0/undefined uses the global pool. */
+  maxConcurrency?: number | string;
+  /** Function executed after validation; its result is made JSON-safe for model context. */
+  execute: ToolExecuteFn<TInput, TOutput>;
+}
+
+export interface StandardToolDeclaration {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  strict?: boolean;
+}
+
+export interface ToolCallRecord {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+  rawArguments?: string;
+  thoughtSignature?: string;
+}
+
+export interface ToolResultRecord {
+  id: string;
+  name: string;
+  result: unknown;
+  isError?: boolean;
+  durationMs?: number;
+}

package/src/utils/base64.ts

@@ -0,0 +1,27 @@
+/** Runtime-agnostic base64 helpers — no Node Buffer, safe in browsers. */
+
+export function base64ToBytes(b64: string): Uint8Array {
+  const clean = b64.replace(/\s/g, "");
+  const nodeBuffer = (globalThis as any)?.Buffer;
+  if (nodeBuffer && typeof nodeBuffer.from === "function") {
+    const buf = nodeBuffer.from(clean, "base64");
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+  }
+  const bin = atob(clean);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+export function bytesToBase64(bytes: Uint8Array): string {
+  const nodeBuffer = (globalThis as any)?.Buffer;
+  if (nodeBuffer && typeof nodeBuffer.from === "function") {
+    return nodeBuffer.from(bytes).toString("base64");
+  }
+  let bin = "";
+  const CHUNK = 0x8000;
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(bin);
+}