agent-accelerator 0.1.0

package/src/utils/cache.ts

@@ -0,0 +1,146 @@
+/**
+ * Battle-tested cache helper — single source for 80-90% hit rate
+ * Based on agent-accel: openai-prompt-cache.ts + applyAnthropicCacheControl
+ * - First turn already cache-optimized: system + tools + first user get cache_control
+ * - Stable sessionId (64 clamp) + prompt_cache_key ensures affinity
+ * - 4 breakpoint cap (Anthropic limit)
+ * - Retention mapping: short=5m (no ttl), medium=1h, long=24h (prompt) / 1h (anthropic)
+ */
+
+import type { CacheRetention } from "../types/core.ts";
+import type { ModelSpec } from "../types/model.ts";
+import { getApiKey } from "./env.ts";
+
+const CACHE_KEY_MAX = 64;
+
+/** Clamps a cache/session affinity key to the provider-safe 64-character limit. */
+export function clampCacheKey(key?: string): string | undefined {
+  if (!key) return undefined;
+  const chars = Array.from(key);
+  if (chars.length <= CACHE_KEY_MAX) return key;
+  return chars.slice(0, CACHE_KEY_MAX).join("");
+}
+
+/** Maps retention to explicit-cache TTL seconds. short=5m, medium=1h, long=12h. Explicit ttlSeconds wins. */
+export function retentionToTtlSeconds(retention?: CacheRetention, ttlSeconds?: number): number | undefined {
+  if (ttlSeconds && ttlSeconds > 0) return Math.floor(ttlSeconds);
+  if (!retention || retention === "implicit") return undefined;
+  if (retention === "short") return 300;
+  if (retention === "medium") return 3600;
+  if (retention === "long") return 43200;
+  return undefined;
+}
+
+/** Maps retention settings to OpenCode/OpenRouter prompt-cache TTL values. */
+export function getPromptCacheRetention(retention?: CacheRetention, supportsLong = true): "24h" | "1h" | undefined {
+  if (!retention || retention === "implicit") return undefined;
+  if (retention === "long" && supportsLong) return "24h";
+  if (retention === "medium" && supportsLong) return "1h";
+  if (retention === "long") return "24h"; // fallback even if supportsLong false, provider may ignore
+  return undefined;
+}
+
+// ============================================================================
+// Explicit Context Caching (Google cachedContents API)
+// ============================================================================
+
+export interface CachedContentMetadata {
+  name: string;
+  displayName?: string;
+  model: string;
+  createTime: string;
+  updateTime: string;
+  expireTime: string;
+  usageMetadata?: {
+    totalTokenCount?: number;
+  };
+}
+
+export interface CreateExplicitCacheOptions {
+  model: string;
+  contents?: any[];
+  systemInstruction?: string;
+  tools?: any[];
+  toolConfig?: any;
+  displayName?: string;
+  ttlSeconds?: number;
+  retention?: CacheRetention;
+  expireTime?: string | Date;
+  apiKey?: string;
+  baseUrl?: string;
+}
+
+/**
+ * Creates an explicit cached content object using Google Gemini's cachedContents API.
+ * REST: POST https://generativelanguage.googleapis.com/v1beta/cachedContents?key=...
+ */
+/**
+ * Creates a Google Gemini cachedContents resource through the REST API.
+ *
+ * @example `const cache = await createExplicitCache({ model: "google/gemini-3.5-flash-lite", contents });`
+ */
+export async function createExplicitCache(
+  options: CreateExplicitCacheOptions
+): Promise<CachedContentMetadata> {
+  const apiKey = getApiKey("google", options.apiKey);
+  if (!apiKey) {
+    throw new Error("API key is required to create explicit cache (GEMINI_API_KEY)");
+  }
+
+  const baseUrl = options.baseUrl || "https://generativelanguage.googleapis.com/v1beta";
+  const ttlSeconds = retentionToTtlSeconds(options.retention, options.ttlSeconds) ?? 3600;
+  const ttl = options.expireTime ? undefined : `${ttlSeconds}s`;
+
+  let modelName = options.model;
+  if (!modelName.startsWith("models/")) {
+    modelName = `models/${modelName.replace(/^google\//, "")}`;
+  }
+
+  const payload: Record<string, unknown> = {
+    model: modelName,
+    contents: options.contents ?? [],
+    ...(ttl ? { ttl } : {}),
+    ...(options.expireTime
+      ? { expireTime: options.expireTime instanceof Date ? options.expireTime.toISOString() : options.expireTime }
+      : {}),
+  };
+
+  if (options.displayName) {
+    payload.displayName = options.displayName;
+    (payload as any).display_name = options.displayName;
+  }
+
+  if (options.systemInstruction) {
+    payload.systemInstruction = {
+      parts: [{ text: options.systemInstruction }],
+    };
+    (payload as any).system_instruction = payload.systemInstruction;
+  }
+
+  if (options.tools && options.tools.length > 0) {
+    payload.tools = options.tools;
+  }
+
+  if (options.toolConfig) {
+    payload.toolConfig = options.toolConfig;
+    (payload as any).tool_config = options.toolConfig;
+  }
+
+  const url = `${baseUrl}/cachedContents?key=${apiKey}`;
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    const errorBody = await response.text();
+    throw new Error(
+      `Failed to create explicit cache (${response.status} ${response.statusText}): ${errorBody}`
+    );
+  }
+
+  return (await response.json()) as CachedContentMetadata;
+}

package/src/utils/env.ts

@@ -0,0 +1,78 @@
+/**
+ * Safe environment lookup for API keys and configurations
+ */
+/**
+ * Reads an environment/global value without assuming a Node-only runtime.
+ *
+ * @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];
+  }
+  return fallback;
+}
+
+export type ProviderEnv = Record<string, string>;
+
+/**
+ * Resolves a provider API key from explicit input, overrides, and standard aliases.
+ *
+ * @example `const key = getApiKey("google");`
+ */
+export function getApiKey(provider: string, explicitKey?: string, env?: ProviderEnv): string | undefined {
+  if (explicitKey) return explicitKey;
+  // 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];
+    // 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"];
+    }
+    // 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"];
+    }
+  }
+
+  switch (provider.toLowerCase()) {
+    case "google":
+    case "gemini":
+      return (
+        getEnv("GEMINI_API_KEY") ||
+        getEnv("GOOGLE_API_KEY") ||
+        getEnv("GOOGLE_GENAI_API_KEY")
+      );
+    case "opencode":
+    case "opencode-go":
+      return (
+        getEnv("OPENCODE_API_KEY") ||
+        getEnv("OPENCODE_ZEN_API_KEY") ||
+        getEnv("OPENCODE_GO_API_KEY")
+      );
+    case "openrouter":
+      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`);
+  }
+}
+
+/** Reads MODEL or MODEL_NAME, with an optional fallback. */
+export function getModel(fallback?: string): string | undefined {
+  return getEnv("MODEL") || getEnv("MODEL_NAME") || fallback;
+}
+
+/** Reads SUB_AGENT_MODEL, with an optional fallback. */
+export function getSubModel(fallback?: string): string | undefined {
+  return getEnv("SUB_AGENT_MODEL") || fallback;
+}

package/src/utils/headers.ts

@@ -0,0 +1,110 @@
+import type { ProviderId } from "../types/model.ts";
+import type { CacheConfig } from "../types/core.ts";
+import { clampCacheKey } from "./cache.ts";
+
+export function isBrowserRuntime(): boolean {
+  try {
+    return typeof (globalThis as any).window !== "undefined" && typeof (globalThis as any).window.document !== "undefined";
+  } catch {
+    return false;
+  }
+}
+
+function getAgentAccelUserAgent(): string {
+  try {
+    const os = (globalThis as any).process?.getBuiltinModule?.("node:os") ?? null;
+    if (os) {
+      return `agent-accel (${os.platform()} ${os.release()}; ${os.arch()})`;
+    }
+  } catch {}
+  return "agent-accel (linux; x64)";
+}
+
+const BROWSER_DROPPED = new Set([
+  "user-agent",
+  "x-session-id",
+  "x-client-request-id",
+  "session_id",
+  "x-opencode-session",
+  "x-opencode-client",
+  "x-goog-api-client",
+]);
+
+function stripForBrowser(headers: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (BROWSER_DROPPED.has(k.toLowerCase())) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Builds provider-specific session, cache-affinity, and attribution headers.
+ *
+ * Browser note: custom `x-*` session/affinity headers force a CORS preflight
+ * (`OPTIONS`) and providers only allow-list their own documented headers, so a
+ * preflight failure surfaces as a bare `TypeError: Failed to fetch`. In browser
+ * runtimes this returns only CORS-safe attribution headers (OpenRouter
+ * `HTTP-Referer` / `X-Title`); session affinity still flows via `providerOptions`
+ * (`promptCacheKey`), never via headers.
+ * @example `const headers = buildSessionHeaders("google", { sessionId: "session-123" });`
+ */
+export function buildSessionHeaders(
+  provider: ProviderId | string,
+  cache?: CacheConfig,
+  customHeaders?: Record<string, string>,
+  explicitSessionId?: string
+): Record<string, string> {
+  const browser = isBrowserRuntime();
+  const headers: Record<string, string> = {
+    ...(browser ? {} : { "User-Agent": "Agent-Accelerator/1.0" }),
+    ...(customHeaders ?? {}),
+  };
+
+  const rawSessionId = explicitSessionId || cache?.sessionId;
+  const sessionId = clampCacheKey(rawSessionId);
+
+  if (sessionId && !browser) {
+    if (provider === "opencode" || provider === "opencode-go") {
+      headers["x-opencode-session"] = sessionId;
+      headers["x-session-id"] = sessionId;
+      headers["x-client-request-id"] = sessionId;
+      headers["session_id"] = sessionId;
+      headers["x-opencode-client"] = "agent-accel";
+      headers["User-Agent"] = getAgentAccelUserAgent();
+    } else if (provider === "openrouter") {
+      headers["x-session-id"] = sessionId;
+      headers["x-client-request-id"] = sessionId;
+      headers["HTTP-Referer"] = "https://sashvat.com";
+      headers["X-Title"] = "Agent Accelerator";
+    } else if (provider === "google") {
+      headers["x-goog-api-client"] = "agent-accel/1.0";
+      headers["x-session-id"] = sessionId;
+      headers["x-client-request-id"] = sessionId;
+    } else {
+      headers["x-session-id"] = sessionId;
+      headers["x-client-request-id"] = sessionId;
+      headers["session_id"] = sessionId;
+    }
+  } else if (provider === "openrouter") {
+    if (!headers["HTTP-Referer"]) headers["HTTP-Referer"] = "https://sashvat.com";
+    if (!headers["X-Title"]) headers["X-Title"] = "Agent Accelerator";
+  }
+
+  if (provider === "google" && !browser && !headers["x-goog-api-client"]) {
+    headers["x-goog-api-client"] = "agent-accel/1.0";
+  }
+
+  if (
+    (provider === "opencode" || provider === "opencode-go") &&
+    !browser &&
+    !headers["x-opencode-client"]
+  ) {
+    headers["x-opencode-client"] = "agent-accel";
+    headers["User-Agent"] = getAgentAccelUserAgent();
+  }
+
+  if (browser) return stripForBrowser(headers);
+  return headers;
+}

package/src/utils/media.ts

@@ -0,0 +1,137 @@
+// NOTE: no static node:fs import — it breaks browser bundles. Local file
+// paths are loaded via a lazy dynamic import so browsers never resolve it.
+import { bytesToBase64 } from "./base64.ts";
+
+export interface NormalizedMedia {
+  mimeType: string;
+  base64Data: string;
+  dataUrl: string;
+}
+
+/**
+ * Detects MIME type from common file signatures or extensions
+ */
+/**
+ * Infers a MIME type from a URL/path extension.
+ *
+ * @example `const mime = inferMimeType("photo.webp");`
+ */
+export function inferMimeType(input: string, fallback = "application/octet-stream"): string {
+  const clean = input.toLowerCase().split("?")[0]!;
+  if (clean.endsWith(".png")) return "image/png";
+  if (clean.endsWith(".jpg") || clean.endsWith(".jpeg")) return "image/jpeg";
+  if (clean.endsWith(".webp")) return "image/webp";
+  if (clean.endsWith(".gif")) return "image/gif";
+  if (clean.endsWith(".mp3")) return "audio/mp3";
+  if (clean.endsWith(".wav")) return "audio/wav";
+  if (clean.endsWith(".ogg")) return "audio/ogg";
+  if (clean.endsWith(".mp4")) return "video/mp4";
+  if (clean.endsWith(".webm")) return "video/webm";
+  if (clean.endsWith(".mov")) return "video/quicktime";
+  if (clean.endsWith(".pdf")) return "application/pdf";
+  return fallback;
+}
+
+/**
+ * Normalizes an image, audio, or video input into raw base64 and data URL
+ */
+/**
+ * Normalizes a path, URL, data URL, base64 string, or binary value into media payloads.
+ *
+ * @example `const image = await normalizeMediaInput("https://example.com/photo.png");`
+ */
+export async function normalizeMediaInput(
+  input: string | Uint8Array | ArrayBuffer,
+  explicitMimeType?: string
+): Promise<NormalizedMedia> {
+  // 1. If input is ArrayBuffer or Uint8Array
+  if (input instanceof Uint8Array || input instanceof ArrayBuffer) {
+    const bytes = input instanceof Uint8Array ? input : new Uint8Array(input);
+    const mimeType = explicitMimeType || "application/octet-stream";
+    const base64Data = bytesToBase64(bytes);
+    return {
+      mimeType,
+      base64Data,
+      dataUrl: `data:${mimeType};base64,${base64Data}`,
+    };
+  }
+
+  // 2. If input is data URL (data:image/png;base64,...)
+  if (typeof input === "string" && input.startsWith("data:")) {
+    const match = input.match(/^data:([^;]+);base64,(.+)$/);
+    if (match && match[1] && match[2]) {
+      return {
+        mimeType: explicitMimeType || match[1],
+        base64Data: match[2],
+        dataUrl: input,
+      };
+    }
+  }
+
+  // 3. If input is a remote HTTP URL (check before base64 to avoid misclassifying URL as base64)
+  if (typeof input === "string" && (input.startsWith("http://") || input.startsWith("https://"))) {
+    const response = await fetch(input);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch media from URL: ${input} (${response.statusText})`);
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    const buffer = new Uint8Array(arrayBuffer);
+    const mimeType =
+      explicitMimeType ||
+      response.headers.get("content-type") ||
+      inferMimeType(input);
+    const base64Data = bytesToBase64(buffer);
+    return {
+      mimeType,
+      base64Data,
+      dataUrl: `data:${mimeType};base64,${base64Data}`,
+    };
+  }
+
+  // 4. If input is already raw base64 string (stricter: length threshold + no file markers)
+  if (
+    typeof input === "string" &&
+    !input.includes("/") && // file paths contain /
+    !input.includes("\\") &&
+    input.length > 100 &&
+    /^[A-Za-z0-9+/=\n\r]+$/.test(input.slice(0, 200)) &&
+    input.length % 4 === 0
+  ) {
+    const mimeType = explicitMimeType || "image/jpeg";
+    return {
+      mimeType,
+      base64Data: input.replace(/\s/g, ""),
+      dataUrl: `data:${mimeType};base64,${input.replace(/\s/g, "")}`,
+    };
+  }
+
+  // 5. If input is local file path (Node only — browsers use data URLs / FileReader)
+  if (typeof input === "string") {
+    try {
+      const { promises: fs } = await import("node:fs");
+      const buffer = await fs.readFile(input);
+      const mimeType = explicitMimeType || inferMimeType(input);
+      const base64Data = bytesToBase64(buffer);
+      return {
+        mimeType,
+        base64Data,
+        dataUrl: `data:${mimeType};base64,${base64Data}`,
+      };
+    } catch (err) {
+      // S11: don't silently return path string as base64 (would 400). Re-check if it's actually base64 with "/"
+      const trimmed = input.replace(/\s/g, "");
+      const isMaybeBase64 = trimmed.length > 100 && /^[A-Za-z0-9+/=\n\r]+$/.test(trimmed.slice(0, 500)) && trimmed.length % 4 === 0;
+      if (isMaybeBase64) {
+        const mimeType = explicitMimeType || "image/jpeg";
+        return {
+          mimeType,
+          base64Data: trimmed,
+          dataUrl: `data:${mimeType};base64,${trimmed}`,
+        };
+      }
+      throw new Error(`Failed to normalize media input: not a valid file path, data URL, http URL, or base64 string: ${input.slice(0, 80)}`);
+    }
+  }
+
+  throw new Error(`Unsupported media input type: ${typeof input}`);
+}

package/src/utils/serialization.ts

@@ -0,0 +1,91 @@
+import { bytesToBase64 } from "./base64.ts";
+/**
+ * Converts arbitrary tool output into values that are safe to put in model
+ * context or JSON responses. Circular references and unsupported primitives
+ * are represented instead of causing JSON.stringify to throw.
+ */
+/**
+ * Converts arbitrary tool output into a circular/reference-safe JSON value.
+ *
+ * @example `const safe = toJsonSafe({ result, request });`
+ */
+export function toJsonSafe(value: unknown, seen = new WeakSet<object>()): unknown {
+  if (value === null || value === undefined) return value === undefined ? null : value;
+  if (typeof value === "bigint") return `${value.toString()}n`;
+  if (typeof value === "number" && !Number.isFinite(value)) return String(value);
+  if (typeof value === "function") return `[Function${value.name ? `: ${value.name}` : ""}]`;
+  if (typeof value === "symbol") return value.toString();
+  if (typeof value !== "object") return value;
+
+  if (seen.has(value as object)) return "[Circular]";
+  seen.add(value as object);
+
+  try {
+    if (value instanceof Error) {
+      const error: Record<string, unknown> = {
+        name: value.name,
+        message: value.message,
+        ...(value.stack ? { stack: value.stack } : {}),
+      };
+      for (const key of Object.keys(value as any)) {
+        error[key] = toJsonSafe((value as any)[key], seen);
+      }
+      return error;
+    }
+
+    if (value instanceof Date) return value.toISOString();
+
+    if (value instanceof Uint8Array) {
+      return {
+        type: "Uint8Array",
+        base64: bytesToBase64(value),
+        byteLength: value.byteLength,
+      };
+    }
+
+    if (value instanceof ArrayBuffer) {
+      const bytes = new Uint8Array(value);
+      return {
+        type: "ArrayBuffer",
+        base64: bytesToBase64(bytes),
+        byteLength: bytes.byteLength,
+      };
+    }
+
+    if (value instanceof Map) {
+      return Array.from(value.entries()).map(([key, entry]) => [
+        toJsonSafe(key, seen),
+        toJsonSafe(entry, seen),
+      ]);
+    }
+
+    if (value instanceof Set) {
+      return Array.from(value.values()).map((entry) => toJsonSafe(entry, seen));
+    }
+
+    if (Array.isArray(value)) {
+      return value.map((entry) => toJsonSafe(entry, seen));
+    }
+
+    const output: Record<string, unknown> = {};
+    for (const key of Object.keys(value as any)) {
+      output[key] = toJsonSafe((value as any)[key], seen);
+    }
+    return output;
+  } finally {
+    seen.delete(value as object);
+  }
+}
+
+/**
+ * Safely serializes arbitrary values without throwing on circular or unsupported data.
+ *
+ * @example `logger.info(safeStringify(toolResult));`
+ */
+export function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(toJsonSafe(value)) ?? "null";
+  } catch {
+    return String(value);
+  }
+}

package/src/utils/session.ts

@@ -0,0 +1,26 @@
+import { clampCacheKey } from "./cache.ts";
+
+/**
+ * Creates or formats a unique session ID for prompt caching affinity (clamped to 64 chars like agent-accel)
+ */
+/**
+ * Creates a unique, provider-safe session ID for cache affinity.
+ *
+ * @example `const sessionId = createSessionId("checkout");`
+ */
+export function createSessionId(prefix = "accel"): string {
+  let id: string;
+  try {
+    const webCrypto =
+      (globalThis as any)?.crypto ?? (typeof crypto !== "undefined" ? crypto : undefined);
+    if (webCrypto && typeof webCrypto.randomUUID === "function") {
+      id = `${prefix}-${webCrypto.randomUUID()}`;
+    } else {
+      throw new Error("no randomUUID");
+    }
+  } catch {
+    // Fallback — still clamp
+    id = `${prefix}-${Math.random().toString(36).slice(2, 11)}-${Date.now().toString(36)}`;
+  }
+  return clampCacheKey(id) || id;
+}

package/src/utils/thought-signature.ts

@@ -0,0 +1,27 @@
+/**
+ * Utilities for Gemini thought signatures via OpenAI-compatible endpoints & Google AI Studio.
+ */
+
+const base64SigPattern = /^[A-Za-z0-9+/]+={0,2}$/;
+
+/**
+ * Checks whether a Gemini thought signature has valid base64 shape.
+ * @example `const valid = isValidThoughtSignature(signature);`
+ */
+export function isValidThoughtSignature(sig?: string): boolean {
+  if (!sig) return false;
+  if (sig.length % 4 !== 0) return false;
+  return base64SigPattern.test(sig);
+}
+
+/** Keeps an incoming signature when present, otherwise preserves the existing one. */
+export function retainThoughtSignature(existing?: string, incoming?: string): string | undefined {
+  if (typeof incoming === "string" && incoming.length > 0) return incoming;
+  return existing;
+}
+
+/** Extracts a Google thought signature from OpenAI-compatible metadata. */
+export function extractGoogleThoughtSignature(obj: any): string | undefined {
+  const sig = obj?.extra_content?.google?.thought_signature;
+  return typeof sig === "string" && sig.length > 0 ? sig : undefined;
+}

package/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "types": ["bun"],
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  },
+  "include": ["src/**/*", "examples/**/*"],
+  "exclude": ["references", "node_modules"]
+}