@agentskit/adapters 0.4.2 → 0.5.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _agentskit_core from '@agentskit/core';
-import { AdapterRequest, StreamChunk, AdapterFactory, EmbedFn } from '@agentskit/core';
+import { AdapterRequest, StreamChunk, AdapterFactory, StreamSource, EmbedFn } from '@agentskit/core';
 
 interface CreateAdapterConfig {
     send: (request: AdapterRequest) => Promise<ReadableStream | Response>;
@@ -14,11 +14,75 @@ declare function createAdapter(config: CreateAdapterConfig): AdapterFactory;
 
 declare function generic(config: GenericAdapterConfig): AdapterFactory;
 
+/**
+ * Retry knobs for adapter fetches. Tunable per call to createStreamSource.
+ *
+ * Default behavior:
+ *   - 3 attempts total (1 initial + 2 retries)
+ *   - exponential backoff: 500ms, 1000ms, 2000ms ... (capped at maxDelayMs)
+ *   - full jitter on each delay
+ *   - retry on HTTP 408, 429, 500, 502, 503, 504
+ *   - retry on network errors (fetch throws)
+ *   - DO NOT retry on 4xx other than 408/429 (those are bad requests / auth)
+ *   - retries only the initial fetch — never mid-stream
+ *   - respects Retry-After header when present
+ */
+interface RetryOptions {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    jitter?: boolean;
+    retryOn?: (info: {
+        error?: unknown;
+        response?: Response;
+        attempt: number;
+    }) => boolean;
+    /** Hook for tests + logging. Called after every failed attempt. */
+    onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        reason: string;
+    }) => void;
+    /** Sleep override for tests. Defaults to setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Run a fetch with retries on transient failures. Returns the final
+ * Response (whether successful or not — caller decides), or throws if
+ * the AbortSignal fires or all attempts fail with a thrown error.
+ */
+declare function fetchWithRetry(doFetch: (signal: AbortSignal) => Promise<Response>, signal: AbortSignal, retryOpt?: RetryOptions): Promise<Response>;
+/**
+ * Chunk-splitter that turns one large string into N streamable text chunks.
+ * Useful when a provider returns the full response in one shot and you
+ * want to feed it to a UI that expects streaming.
+ *
+ * Default splits by whitespace boundaries with a target chunk size of ~32
+ * characters.
+ */
+declare function chunkText(text: string, targetSize?: number): string[];
+/**
+ * Build a StreamSource from a non-streaming fetch. The adapter is
+ * auto-completing: it fetches once, then yields the text as a sequence
+ * of chunks so UIs see the same streaming shape they'd see from a
+ * native streaming provider.
+ *
+ * Use this when you're wiring a provider that only has a non-streaming
+ * endpoint but you want consumers (useChat, the runtime) to get
+ * identical ergonomics.
+ */
+declare function simulateStream(doFetch: (signal: AbortSignal) => Promise<Response>, extractText: (response: Response) => Promise<string>, errorLabel: string, options?: {
+    chunkSize?: number;
+    delayMs?: number;
+    retry?: RetryOptions;
+}): StreamSource;
+
 interface AnthropicConfig {
     apiKey: string;
     model: string;
     baseUrl?: string;
     maxTokens?: number;
+    retry?: RetryOptions;
 }
 declare function anthropic(config: AnthropicConfig): AdapterFactory;
 
@@ -26,6 +90,7 @@ interface OpenAIConfig {
     apiKey: string;
     model: string;
     baseUrl?: string;
+    retry?: RetryOptions;
 }
 declare function openai(config: OpenAIConfig): AdapterFactory;
 
@@ -33,6 +98,7 @@ interface GeminiConfig {
     apiKey: string;
     model: string;
     baseUrl?: string;
+    retry?: RetryOptions;
 }
 declare function gemini(config: GeminiConfig): AdapterFactory;
 
@@ -46,6 +112,7 @@ declare const grok: (config: OpenAICompatibleConfig) => _agentskit_core.AdapterF
 interface OllamaConfig {
     model: string;
     baseUrl?: string;
+    retry?: RetryOptions;
 }
 declare function ollama(config: OllamaConfig): AdapterFactory;
 
@@ -74,9 +141,90 @@ declare function langgraph(config: LangGraphConfig): AdapterFactory;
 interface VercelAIConfig {
     api: string;
     headers?: Record<string, string>;
+    retry?: RetryOptions;
 }
 declare function vercelAI(config: VercelAIConfig): AdapterFactory;
 
+type MockResponse = StreamChunk[] | ((request: AdapterRequest) => StreamChunk[]);
+interface MockAdapterOptions {
+    /**
+     * Static chunks, a request-aware function, or a sequence of responses
+     * (the i-th call returns the i-th item, looping when exhausted).
+     */
+    response: MockResponse | MockResponse[];
+    /** ms between yielded chunks. Default 0 (synchronous). */
+    delayMs?: number;
+    /** Track every request the adapter received. Useful for assertions. */
+    history?: AdapterRequest[];
+}
+/**
+ * A deterministic adapter for tests, demos, and dry-run experiments.
+ *
+ * Conforms to ADR 0001 — Adapter contract:
+ * - createSource is pure (A1) — no work until stream() runs
+ * - Always emits a terminal chunk (A3)
+ * - abort() is safe (A6)
+ * - Does not mutate input messages (A7)
+ *
+ * Examples:
+ *
+ *   // Static
+ *   const adapter = mockAdapter({
+ *     response: [
+ *       { type: 'text', content: 'Hello!' },
+ *       { type: 'done' },
+ *     ],
+ *   })
+ *
+ *   // Request-aware
+ *   const adapter = mockAdapter({
+ *     response: req => {
+ *       const last = req.messages[req.messages.length - 1]?.content ?? ''
+ *       return [
+ *         { type: 'text', content: 'Echo: ' + last },
+ *         { type: 'done' },
+ *       ]
+ *     },
+ *   })
+ *
+ *   // Sequenced — different output each call
+ *   const adapter = mockAdapter({
+ *     response: [
+ *       [{ type: 'text', content: 'first' }, { type: 'done' }],
+ *       [{ type: 'text', content: 'second' }, { type: 'done' }],
+ *     ],
+ *   })
+ */
+declare function mockAdapter(options: MockAdapterOptions): AdapterFactory;
+interface RecordedTurn {
+    /** ISO timestamp when this turn was recorded. */
+    recordedAt: string;
+    /** The request that produced this turn. */
+    request: AdapterRequest;
+    /** Every chunk yielded by the wrapped adapter. */
+    chunks: StreamChunk[];
+}
+type RecordingFixture = RecordedTurn[];
+interface RecordingSink {
+    push(turn: RecordedTurn): void | Promise<void>;
+}
+/**
+ * Wrap a real adapter so every turn is captured to a sink. Use this in
+ * dev to build up a fixture, then replay with replayAdapter() in tests.
+ */
+declare function recordingAdapter(inner: AdapterFactory, sink: RecordingSink): AdapterFactory;
+/**
+ * In-memory recording sink — useful for tests and ephemeral capture.
+ */
+declare function inMemorySink(): RecordingSink & {
+    fixture: RecordingFixture;
+};
+/**
+ * Replay an adapter from a recorded fixture. Each turn maps 1:1 to a
+ * recorded entry by index — call N replays fixture[N % fixture.length].
+ */
+declare function replayAdapter(fixture: RecordingFixture): AdapterFactory;
+
 interface OpenAIEmbedderConfig {
     apiKey: string;
     model?: string;
@@ -116,4 +264,4 @@ interface KimiEmbedderConfig extends OpenAICompatibleEmbedderConfig {
 }
 declare const kimiEmbedder: (config: OpenAICompatibleEmbedderConfig) => _agentskit_core.EmbedFn;
 
-export { type AnthropicConfig, type CreateAdapterConfig, type DeepSeekConfig, type DeepSeekEmbedderConfig, type GeminiConfig, type GeminiEmbedderConfig, type GenericAdapterConfig, type GrokConfig, type GrokEmbedderConfig, type KimiConfig, type KimiEmbedderConfig, type LangChainConfig, type LangGraphConfig, type OllamaConfig, type OllamaEmbedderConfig, type OpenAICompatibleEmbedderConfig, type OpenAIConfig, type OpenAIEmbedderConfig, type VercelAIConfig, anthropic, createAdapter, createOpenAICompatibleEmbedder, deepseek, deepseekEmbedder, gemini, geminiEmbedder, generic, grok, grokEmbedder, kimi, kimiEmbedder, langchain, langgraph, ollama, ollamaEmbedder, openai, openaiEmbedder, vercelAI };
+export { type AnthropicConfig, type CreateAdapterConfig, type DeepSeekConfig, type DeepSeekEmbedderConfig, type GeminiConfig, type GeminiEmbedderConfig, type GenericAdapterConfig, type GrokConfig, type GrokEmbedderConfig, type KimiConfig, type KimiEmbedderConfig, type LangChainConfig, type LangGraphConfig, type MockAdapterOptions, type MockResponse, type OllamaConfig, type OllamaEmbedderConfig, type OpenAICompatibleEmbedderConfig, type OpenAIConfig, type OpenAIEmbedderConfig, type RecordedTurn, type RecordingFixture, type RecordingSink, type RetryOptions, type VercelAIConfig, anthropic, chunkText, createAdapter, createOpenAICompatibleEmbedder, deepseek, deepseekEmbedder, fetchWithRetry, gemini, geminiEmbedder, generic, grok, grokEmbedder, inMemorySink, kimi, kimiEmbedder, langchain, langgraph, mockAdapter, ollama, ollamaEmbedder, openai, openaiEmbedder, recordingAdapter, replayAdapter, simulateStream, vercelAI };

package/dist/index.js

@@ -253,12 +253,73 @@ async function* parseOllamaStream(stream) {
   }
   yield { type: "done" };
 }
-function createStreamSource(doFetch, parse, errorLabel) {
+var DEFAULT_RETRY = {
+  maxAttempts: 3,
+  baseDelayMs: 500,
+  maxDelayMs: 8e3,
+  jitter: true,
+  retryOn: ({ error, response }) => {
+    if (response) {
+      return [408, 429, 500, 502, 503, 504].includes(response.status);
+    }
+    if (error instanceof DOMException && error.name === "AbortError") return false;
+    return true;
+  }
+};
+function defaultSleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+function computeDelay(attempt, opts) {
+  const exp = Math.min(opts.maxDelayMs, opts.baseDelayMs * Math.pow(2, attempt - 1));
+  if (!opts.jitter) return exp;
+  return Math.floor(Math.random() * exp);
+}
+function parseRetryAfter(value) {
+  if (!value) return void 0;
+  const n = Number(value);
+  if (!Number.isNaN(n)) return n * 1e3;
+  const date = Date.parse(value);
+  if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+  return void 0;
+}
+async function fetchWithRetry(doFetch, signal, retryOpt = {}) {
+  const opts = {
+    ...DEFAULT_RETRY,
+    ...retryOpt
+  };
+  const sleep = retryOpt.sleep ?? defaultSleep;
+  let lastError;
+  for (let attempt = 1; attempt <= opts.maxAttempts; attempt++) {
+    if (signal.aborted) throw new DOMException("Aborted", "AbortError");
+    try {
+      const response = await doFetch(signal);
+      if (response.ok) return response;
+      if (attempt >= opts.maxAttempts || !opts.retryOn({ response, attempt })) {
+        return response;
+      }
+      const retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
+      const delay = retryAfterMs ?? computeDelay(attempt, opts);
+      retryOpt.onRetry?.({ attempt, delayMs: delay, reason: `HTTP ${response.status}` });
+      await sleep(delay);
+      response.body?.cancel().catch(() => {
+      });
+    } catch (err) {
+      lastError = err;
+      if (err instanceof DOMException && err.name === "AbortError") throw err;
+      if (attempt >= opts.maxAttempts || !opts.retryOn({ error: err, attempt })) throw err;
+      const delay = computeDelay(attempt, opts);
+      retryOpt.onRetry?.({ attempt, delayMs: delay, reason: err.message });
+      await sleep(delay);
+    }
+  }
+  throw lastError ?? new Error("fetchWithRetry: exhausted attempts");
+}
+function createStreamSource(doFetch, parse, errorLabel, retry) {
   let abortController = new AbortController();
   return {
     stream: async function* () {
       try {
-        const response = await doFetch(abortController.signal);
+        const response = await fetchWithRetry(doFetch, abortController.signal, retry ?? {});
         if (!response.ok || !response.body) {
           yield { type: "error", content: `${errorLabel} error: ${response.status}` };
           return;
@@ -278,11 +339,78 @@ function createStreamSource(doFetch, parse, errorLabel) {
     }
   };
 }
+function chunkText(text, targetSize = 32) {
+  if (text.length <= targetSize) return [text];
+  const out = [];
+  let i = 0;
+  while (i < text.length) {
+    let end = Math.min(text.length, i + targetSize);
+    if (end < text.length) {
+      const nextSpace = text.indexOf(" ", end);
+      if (nextSpace !== -1 && nextSpace - end <= 8) end = nextSpace + 1;
+    }
+    out.push(text.slice(i, end));
+    i = end;
+  }
+  return out;
+}
+function simulateStream(doFetch, extractText, errorLabel, options = {}) {
+  const { chunkSize = 32, delayMs = 8, retry } = options;
+  let abortController = new AbortController();
+  return {
+    stream: async function* () {
+      try {
+        const response = await fetchWithRetry(doFetch, abortController.signal, retry ?? {});
+        if (!response.ok) {
+          yield { type: "error", content: `${errorLabel} error: ${response.status}` };
+          return;
+        }
+        const text = await extractText(response);
+        const chunks = chunkText(text, chunkSize);
+        for (const chunk of chunks) {
+          if (abortController === null) return;
+          if (delayMs > 0) {
+            await new Promise((resolve2, reject) => {
+              const timer = setTimeout(resolve2, delayMs);
+              abortController?.signal.addEventListener(
+                "abort",
+                () => {
+                  clearTimeout(timer);
+                  reject(new DOMException("Aborted", "AbortError"));
+                },
+                { once: true }
+              );
+            });
+          }
+          yield { type: "text", content: chunk };
+        }
+        yield { type: "done" };
+      } catch (err) {
+        if (err instanceof DOMException && err.name === "AbortError") return;
+        yield {
+          type: "error",
+          content: err instanceof Error ? err.message : String(err)
+        };
+      }
+    },
+    abort: () => {
+      abortController?.abort();
+      abortController = null;
+    }
+  };
+}
 
 // src/anthropic.ts
 function anthropic(config) {
-  const { apiKey, model, baseUrl = "https://api.anthropic.com", maxTokens = 4096 } = config;
+  const { apiKey, model, baseUrl = "https://api.anthropic.com", maxTokens = 4096, retry } = config;
   return {
+    capabilities: {
+      streaming: true,
+      tools: true,
+      reasoning: model.includes("sonnet") || model.includes("opus"),
+      multiModal: true,
+      usage: true
+    },
     createSource: (request) => {
       const body = {
         model,
@@ -308,7 +436,8 @@ function anthropic(config) {
           signal
         }),
         parseAnthropicStream,
-        "Anthropic API"
+        "Anthropic API",
+        retry
       );
     }
   };
@@ -316,8 +445,17 @@ function anthropic(config) {
 
 // src/openai.ts
 function openai(config) {
-  const { apiKey, model, baseUrl = "https://api.openai.com" } = config;
+  const { apiKey, model, baseUrl = "https://api.openai.com", retry } = config;
   return {
+    capabilities: {
+      streaming: true,
+      tools: true,
+      // o1 / o3 models emit reasoning; older models don't. Accurate per-model
+      // detection would need a model registry; 'true' is the safer default here.
+      reasoning: model.startsWith("o1") || model.startsWith("o3"),
+      multiModal: model.startsWith("gpt-4") || model.startsWith("o"),
+      usage: true
+    },
     createSource: (request) => {
       const body = {
         model,
@@ -345,7 +483,8 @@ function openai(config) {
           signal
         }),
         parseOpenAIStream,
-        "OpenAI API"
+        "OpenAI API",
+        retry
       );
     }
   };
@@ -353,8 +492,14 @@ function openai(config) {
 
 // src/gemini.ts
 function gemini(config) {
-  const { apiKey, model, baseUrl = "https://generativelanguage.googleapis.com" } = config;
+  const { apiKey, model, baseUrl = "https://generativelanguage.googleapis.com", retry } = config;
   return {
+    capabilities: {
+      streaming: true,
+      tools: true,
+      multiModal: true,
+      usage: true
+    },
     createSource: (request) => {
       const body = {
         contents: request.messages.filter((message) => message.role !== "system").map((message) => ({
@@ -377,7 +522,8 @@ function gemini(config) {
           }
         ),
         parseGeminiStream,
-        "Gemini API"
+        "Gemini API",
+        retry
       );
     }
   };
@@ -398,8 +544,14 @@ var grok = createOpenAICompatibleAdapter("https://api.x.ai");
 
 // src/ollama.ts
 function ollama(config) {
-  const { model, baseUrl = "http://localhost:11434" } = config;
+  const { model, baseUrl = "http://localhost:11434", retry } = config;
   return {
+    capabilities: {
+      streaming: true,
+      tools: false,
+      // varies by model; default 'false' — enable via capabilities.extensions if your model supports it
+      multiModal: model.includes("llava") || model.includes("vision")
+    },
     createSource: (request) => {
       const body = {
         model,
@@ -417,7 +569,8 @@ function ollama(config) {
           signal
         }),
         parseOllamaStream,
-        "Ollama API"
+        "Ollama API",
+        retry
       );
     }
   };
@@ -514,8 +667,12 @@ async function* parseVercelStream(stream) {
   yield { type: "done" };
 }
 function vercelAI(config) {
-  const { api, headers = {} } = config;
+  const { api, headers = {}, retry } = config;
   return {
+    capabilities: {
+      // Vercel AI routes can do any of these — whether they do depends on
+      // your route handler. Omit the field instead of lying.
+    },
     createSource: (request) => {
       const body = {
         messages: request.messages.map((message) => ({ role: message.role, content: message.content })),
@@ -530,12 +687,105 @@ function vercelAI(config) {
           signal
         }),
         parseVercelStream,
-        "API"
+        "API",
+        retry
       );
     }
   };
 }
 
+// src/mock.ts
+function mockAdapter(options) {
+  const { response, delayMs = 0, history } = options;
+  let callIndex = 0;
+  return {
+    capabilities: {
+      streaming: true,
+      tools: true,
+      reasoning: true,
+      multiModal: true,
+      usage: true
+    },
+    createSource: (request) => {
+      history?.push(request);
+      const myCall = callIndex++;
+      let cancelled = false;
+      return {
+        stream: async function* () {
+          const chunks = resolve(response, myCall, request);
+          let endedExplicitly = false;
+          for (const chunk of chunks) {
+            if (cancelled) return;
+            if (delayMs > 0) await new Promise((r) => setTimeout(r, delayMs));
+            yield chunk;
+            if (chunk.type === "done" || chunk.type === "error") {
+              endedExplicitly = true;
+            }
+          }
+          if (!endedExplicitly) yield { type: "done" };
+        },
+        abort: () => {
+          cancelled = true;
+        }
+      };
+    }
+  };
+}
+function resolve(response, callIndex, request) {
+  if (Array.isArray(response) && response.length > 0 && Array.isArray(response[0])) {
+    const sequence = response;
+    const item = sequence[callIndex % sequence.length];
+    return item;
+  }
+  if (Array.isArray(response) && response.length > 0 && typeof response[0] === "function") {
+    const sequence = response;
+    return sequence[callIndex % sequence.length](request);
+  }
+  if (typeof response === "function") {
+    return response(request);
+  }
+  return response;
+}
+function recordingAdapter(inner, sink) {
+  return {
+    createSource: (request) => {
+      const innerSource = inner.createSource(request);
+      const captured = [];
+      const recordedAt = (/* @__PURE__ */ new Date()).toISOString();
+      return {
+        stream: async function* () {
+          try {
+            for await (const chunk of innerSource.stream()) {
+              captured.push(chunk);
+              yield chunk;
+            }
+          } finally {
+            await sink.push({ recordedAt, request, chunks: captured });
+          }
+        },
+        abort: () => innerSource.abort()
+      };
+    }
+  };
+}
+function inMemorySink() {
+  const fixture = [];
+  return {
+    fixture,
+    push(turn) {
+      fixture.push(turn);
+    }
+  };
+}
+function replayAdapter(fixture) {
+  if (fixture.length === 0) {
+    throw new Error("replayAdapter: fixture is empty");
+  }
+  return mockAdapter({
+    response: fixture.map((turn) => turn.chunks)
+  });
+}
+
 // src/embedders/openai.ts
 async function fetchAvailableModels(baseUrl, apiKey) {
   const response = await fetch(`${baseUrl}/v1/models`, {
@@ -730,6 +980,6 @@ var grokEmbedder = createOpenAICompatibleEmbedder("Grok", "https://api.x.ai");
 // src/embedders/kimi.ts
 var kimiEmbedder = createOpenAICompatibleEmbedder("Kimi", "https://api.moonshot.ai");
 
-export { anthropic, createAdapter, createOpenAICompatibleEmbedder, deepseek, deepseekEmbedder, gemini, geminiEmbedder, generic, grok, grokEmbedder, kimi, kimiEmbedder, langchain, langgraph, ollama, ollamaEmbedder, openai, openaiEmbedder, vercelAI };
+export { anthropic, chunkText, createAdapter, createOpenAICompatibleEmbedder, deepseek, deepseekEmbedder, fetchWithRetry, gemini, geminiEmbedder, generic, grok, grokEmbedder, inMemorySink, kimi, kimiEmbedder, langchain, langgraph, mockAdapter, ollama, ollamaEmbedder, openai, openaiEmbedder, recordingAdapter, replayAdapter, simulateStream, vercelAI };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map