@agentskit/adapters 0.13.13 → 0.14.0

package/README.md

@@ -1,6 +1,8 @@
 # @agentskit/adapters
 
-<p align="center"><img src="https://raw.githubusercontent.com/AgentsKit-io/agentskit/main/apps/docs-next/public/brand/logo-wordmark.svg" alt="AgentsKit" width="180" /></p>
+Profile: <code>major-package</code>
+
+<p align="center"><img alt="AgentsKit" src="https://raw.githubusercontent.com/AgentsKit-io/agentskit/main/apps/docs-next/public/brand/logo-wordmark.svg" width="180" /></p>
 
 Connect to any LLM provider — and swap between them — without touching your app code.
 
@@ -13,6 +15,12 @@ Connect to any LLM provider — and swap between them — without touching your
 
 **Tags:** `ai` · `agents` · `llm` · `agentskit` · `openai` · `anthropic` · `claude` · `gemini` · `chatgpt` · `ollama` · `embeddings` · `providers`
 
+## Verified proof
+
+- Package metadata and tests live under `packages/adapters/`.
+- Package guide: https://www.agentskit.io/docs/packages/adapters
+- Stability map: [docs/STABILITY.md](../../docs/STABILITY.md)
+
 ## How this fits the ecosystem
 
 @agentskit/adapters is the provider layer: swap OpenAI, Anthropic, Gemini, Ollama, local models, and embedding providers without rewriting your agent.
@@ -33,14 +41,16 @@ Docs: [package guide](https://www.agentskit.io/docs/packages/adapters) · [agent
 
 ## Install
 
+<!-- readme-command:install -->
 ```bash
 npm install @agentskit/adapters
 ```
 
 ## Quick example
 
+<!-- readme-example:quickstart -->
 ```ts
-import { anthropic, openai, ollama } from '@agentskit/adapters'
+import { anthropic } from '@agentskit/adapters'
 import { createRuntime } from '@agentskit/runtime'
 
 // Switch provider by swapping one import
@@ -72,10 +82,19 @@ const rag = createRAG({
 
 - Providers: Anthropic, OpenAI, Gemini, Ollama, DeepSeek, Grok, Kimi, Mistral, Cohere, Together, Groq, Fireworks, OpenRouter, Hugging Face, LM Studio, vLLM, llama.cpp, LangChain, LangGraph, Vercel AI SDK, generic `ReadableStream`
 - Embedders: `openaiEmbedder`, `geminiEmbedder`, `ollamaEmbedder`, `deepseekEmbedder`, `grokEmbedder`, `kimiEmbedder`, `createOpenAICompatibleEmbedder`
-- All adapters satisfy `Adapter` contract v1 (ADR 0001) — substitutable anywhere in the ecosystem
+- Fetch-backed adapters run against the shared `Adapter` contract v1 suite (ADR 0001); SDK-backed adapters have provider-specific contract and resilience coverage
 - Custom adapter authoring via `createAdapter()`
 - Higher-order adapters: `createRouter` (cost/latency/classifier), `createEnsembleAdapter` (fan-out + merge), `createFallbackAdapter` (ordered try-next)
 
+## Stream guarantees
+
+- A stream terminates exactly once with `done` or `error`; terminal errors carry an `Error` in `metadata.error`.
+- Provider streams that close before their native completion marker are treated as truncated, not successful.
+- `abort(reason)` propagates to active fetch readers and SDK requests and terminates with the same error semantics.
+- Native tool histories preserve call/result correlation. Parallel tool results are encoded in a single provider turn where required.
+- Credentials stay in provider headers when the protocol supports them; Gemini API keys are never placed in request URLs.
+- `vercelAI` consumes the Vercel AI SDK UI message stream v1 protocol, including its required response header and `[DONE]` marker.
+
 ## Higher-order adapters
 
 ```ts
@@ -158,3 +177,14 @@ MIT — see [LICENSE](../../LICENSE).
 ## Docs
 
 [Full documentation](https://www.agentskit.io) · [GitHub](https://github.com/AgentsKit-io/agentskit)
+
+## Maturity and compatibility
+
+- Stability: **beta** — see [docs/STABILITY.md](../../docs/STABILITY.md)
+- The implementation is hardened for a future freeze, but promotion still requires the 90-day beta window, two released minor lines, accepted package RFC, and repository evidence required by ADR 0024.
+- **Node.js 20+** and **TypeScript** strict mode
+- Published as `@agentskit/adapters`
+
+## Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) and the monorepo [LICENSE](../../LICENSE).

package/dist/catalog/index.cjs

@@ -1,5 +1,7 @@
 'use strict';
 
+var core = require('@agentskit/core');
+
 // src/catalog/schema.ts
 var catalogSnapshotSchema = {
   $schema: "http://json-schema.org/draft-07/schema#",
@@ -153379,42 +153381,7 @@ function applyOverrides(snapshot, overrides) {
   return { ...snapshot, providers };
 }
 
-// src/utils.ts
-function toProviderMessages(messages) {
-  const knownToolCallIds = /* @__PURE__ */ new Set();
-  const output = [];
-  for (const message of messages) {
-    if (message.role === "tool") {
-      const id = message.toolCallId;
-      if (!id || !knownToolCallIds.has(id)) continue;
-      output.push({
-        role: "tool",
-        content: message.content,
-        tool_call_id: id
-      });
-      continue;
-    }
-    if (message.role === "assistant" && message.toolCalls && message.toolCalls.length > 0) {
-      for (const tc of message.toolCalls) knownToolCallIds.add(tc.id);
-      output.push({
-        role: "assistant",
-        content: message.content || null,
-        tool_calls: message.toolCalls.map((tc) => ({
-          id: tc.id,
-          type: "function",
-          function: {
-            name: tc.name,
-            arguments: typeof tc.args === "string" ? tc.args : JSON.stringify(tc.args ?? {})
-          }
-        }))
-      });
-      continue;
-    }
-    if (message.role === "assistant" && !message.content) continue;
-    output.push({ role: message.role, content: message.content });
-  }
-  return output;
-}
+// src/stream-lines.ts
 async function* readSSELines(stream) {
   const reader = stream.getReader();
   const decoder = new TextDecoder();
@@ -153436,23 +153403,135 @@ async function* readSSELines(stream) {
     reader.releaseLock();
   }
 }
+function isAbortError(err) {
+  if (err instanceof DOMException && err.name === "AbortError") return true;
+  if (err instanceof Error && err.name === "AbortError") return true;
+  return false;
+}
+function adapterErrorChunk(message, options) {
+  const error = new core.AdapterError({
+    code: options?.code ?? core.ErrorCodes.AK_ADAPTER_STREAM_FAILED,
+    message,
+    cause: options?.cause
+  });
+  return {
+    type: "error",
+    content: message,
+    metadata: { error }
+  };
+}
+function parseCompleteToolArgs(args) {
+  const raw = args.length > 0 ? args : "{}";
+  try {
+    JSON.parse(raw);
+    return { ok: true, args: raw };
+  } catch (cause) {
+    return {
+      ok: false,
+      error: new core.AdapterError({
+        code: core.ErrorCodes.AK_ADAPTER_STREAM_FAILED,
+        message: "Incomplete or malformed tool-call arguments JSON",
+        cause
+      })
+    };
+  }
+}
+function raceAbort(promise, signal) {
+  if (signal.aborted) {
+    return Promise.reject(new DOMException("Aborted", "AbortError"));
+  }
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener("abort", onAbort);
+      reject(new DOMException("Aborted", "AbortError"));
+    };
+    signal.addEventListener("abort", onAbort);
+    promise.then(
+      (value) => {
+        if (settled) return;
+        settled = true;
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (err) => {
+        if (settled) return;
+        settled = true;
+        signal.removeEventListener("abort", onAbort);
+        reject(err);
+      }
+    );
+  });
+}
+async function abortableSleep(ms, signal, sleep) {
+  if (signal.aborted) throw new DOMException("Aborted", "AbortError");
+  await raceAbort(sleep(ms), signal);
+  if (signal.aborted) throw new DOMException("Aborted", "AbortError");
+}
+async function cancelBody(body) {
+  if (!body) return;
+  try {
+    await body.cancel();
+  } catch {
+  }
+}
+
+// src/openai-stream.ts
+var SUCCESS_FINISH_REASONS = /* @__PURE__ */ new Set(["stop", "tool_calls", "function_call"]);
 async function* parseOpenAIStream(stream) {
   const pendingToolCalls = /* @__PURE__ */ new Map();
+  let finishReason;
+  const terminalError = (message, extra) => {
+    const chunk = adapterErrorChunk(message);
+    return {
+      ...chunk,
+      metadata: { ...chunk.metadata, ...extra, finishReason }
+    };
+  };
+  const flushToolCalls = function* () {
+    for (const [, toolCall] of pendingToolCalls) {
+      const parsed = parseCompleteToolArgs(toolCall.args);
+      if (!parsed.ok) {
+        pendingToolCalls.clear();
+        yield {
+          type: "error",
+          content: parsed.error.message,
+          metadata: { error: parsed.error, finishReason }
+        };
+        return false;
+      }
+      yield {
+        type: "tool_call",
+        toolCall: { id: toolCall.id, name: toolCall.name, args: parsed.args }
+      };
+    }
+    pendingToolCalls.clear();
+    return true;
+  };
   for await (const data of readSSELines(stream)) {
     if (data === "[DONE]") {
-      for (const [, tc] of pendingToolCalls) {
-        yield { type: "tool_call", toolCall: { id: tc.id, name: tc.name, args: tc.args || "{}" } };
+      if (finishReason !== void 0 && !SUCCESS_FINISH_REASONS.has(finishReason)) {
+        pendingToolCalls.clear();
+        yield terminalError(
+          `OpenAI stream ended with non-success finish reason "${finishReason}".`,
+          { finishReason }
+        );
+        return;
       }
-      pendingToolCalls.clear();
+      if (!(yield* flushToolCalls())) return;
       yield { type: "done" };
       return;
     }
     try {
       const event = JSON.parse(data);
       const delta = event.choices?.[0]?.delta;
-      if (typeof delta?.content === "string") {
-        yield { type: "text", content: delta.content };
-      }
+      const candidateFinishReason = event.choices?.find(
+        (choice) => typeof choice.finish_reason === "string"
+      )?.finish_reason;
+      if (typeof candidateFinishReason === "string") finishReason = candidateFinishReason;
+      if (typeof delta?.content === "string") yield { type: "text", content: delta.content };
       if (Array.isArray(delta?.tool_calls)) {
         for (const toolCall of delta.tool_calls) {
           const index = toolCall.index ?? 0;
@@ -153481,12 +153560,59 @@ async function* parseOpenAIStream(stream) {
     } catch {
     }
   }
-  for (const [, tc] of pendingToolCalls) {
-    yield { type: "tool_call", toolCall: { id: tc.id, name: tc.name, args: tc.args || "{}" } };
+  if (finishReason !== void 0 && !SUCCESS_FINISH_REASONS.has(finishReason)) {
+    pendingToolCalls.clear();
+    yield terminalError(
+      `OpenAI stream ended with non-success finish reason "${finishReason}".`,
+      { finishReason }
+    );
+    return;
+  }
+  if (!finishReason) {
+    pendingToolCalls.clear();
+    yield terminalError("OpenAI stream ended before a terminal marker.");
+    return;
   }
-  pendingToolCalls.clear();
+  if (!(yield* flushToolCalls())) return;
   yield { type: "done" };
 }
+
+// src/utils.ts
+function toProviderMessages(messages) {
+  const knownToolCallIds = /* @__PURE__ */ new Set();
+  const output = [];
+  for (const message of messages) {
+    if (message.role === "tool") {
+      const id = message.toolCallId;
+      if (!id || !knownToolCallIds.has(id)) continue;
+      output.push({
+        role: "tool",
+        content: message.content,
+        tool_call_id: id
+      });
+      continue;
+    }
+    if (message.role === "assistant" && message.toolCalls && message.toolCalls.length > 0) {
+      for (const tc of message.toolCalls) knownToolCallIds.add(tc.id);
+      output.push({
+        role: "assistant",
+        content: message.content || null,
+        tool_calls: message.toolCalls.map((tc) => ({
+          id: tc.id,
+          type: "function",
+          function: {
+            name: tc.name,
+            arguments: typeof tc.args === "string" ? tc.args : JSON.stringify(tc.args ?? {})
+          }
+        }))
+      });
+      continue;
+    }
+    if (message.role === "assistant" && !message.content) continue;
+    output.push({ role: message.role, content: message.content });
+  }
+  return output;
+}
 var DEFAULT_RETRY = {
   maxAttempts: 3,
   baseDelayMs: 500,
@@ -153496,7 +153622,7 @@ var DEFAULT_RETRY = {
     if (response) {
       return [408, 429, 500, 502, 503, 504].includes(response.status);
     }
-    if (error instanceof DOMException && error.name === "AbortError") return false;
+    if (isAbortError(error)) return false;
     return true;
   }
 };
@@ -153534,20 +153660,25 @@ async function fetchWithRetry(doFetch, signal, retryOpt = {}) {
       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(() => {
-      });
+      await cancelBody(response.body);
+      await abortableSleep(delay, signal, sleep);
     } catch (err) {
       lastError = err;
-      if (err instanceof DOMException && err.name === "AbortError") throw err;
+      if (isAbortError(err)) 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);
+      retryOpt.onRetry?.({
+        attempt,
+        delayMs: delay,
+        reason: err instanceof Error ? err.message : String(err)
+      });
+      await abortableSleep(delay, signal, sleep);
     }
   }
   throw lastError ?? new Error("fetchWithRetry: exhausted attempts");
 }
+
+// src/stream-source.ts
 function createStreamSource(doFetch, parse, errorLabel, retry) {
   let abortController = new AbortController();
   return {
@@ -153556,17 +153687,23 @@ function createStreamSource(doFetch, parse, errorLabel, retry) {
       if (!controller) return;
       try {
         const response = await fetchWithRetry(doFetch, controller.signal, retry ?? {});
-        if (!response.ok || !response.body) {
-          yield { type: "error", content: `${errorLabel} error: ${response.status}` };
+        if (!response.ok) {
+          await cancelBody(response.body);
+          yield adapterErrorChunk(`${errorLabel} error: ${response.status}`);
+          return;
+        }
+        if (!response.body) {
+          yield adapterErrorChunk(`${errorLabel} error: empty response body`);
           return;
         }
-        yield* parse(response.body);
+        for await (const chunk of parse(response.body, response)) {
+          if (controller.signal.aborted || abortController === null) return;
+          yield chunk;
+        }
       } catch (err) {
-        if (err instanceof DOMException && err.name === "AbortError") return;
-        yield {
-          type: "error",
-          content: err instanceof Error ? err.message : String(err)
-        };
+        if (isAbortError(err) || controller.signal.aborted || abortController === null) return;
+        const message = err instanceof Error ? err.message : String(err);
+        yield adapterErrorChunk(message, { cause: err });
       }
     },
     abort: () => {