@agentskit/adapters 0.12.0 → 0.12.2

package/dist/index.js

@@ -1,3 +1,5 @@
+import { ConfigError, ErrorCodes, AdapterError } from '@agentskit/core';
+
 // src/createAdapter.ts
 function createAdapter(config) {
   return {
@@ -1094,8 +1096,6 @@ function vertex(config) {
   };
 }
 var vertexAdapter = vertex;
-
-// src/bedrock.ts
 var cachedSdk = null;
 async function loadSdk() {
   if (!cachedSdk) {
@@ -1107,9 +1107,11 @@ async function loadSdk() {
           moduleId
         );
       } catch {
-        throw new Error(
-          "Install @aws-sdk/client-bedrock-runtime to use the bedrock adapter: npm install @aws-sdk/client-bedrock-runtime"
-        );
+        throw new AdapterError({
+          code: ErrorCodes.AK_ADAPTER_MISSING,
+          message: "Install @aws-sdk/client-bedrock-runtime to use the bedrock adapter: npm install @aws-sdk/client-bedrock-runtime",
+          hint: "bedrock depends on the optional peer @aws-sdk/client-bedrock-runtime."
+        });
       }
     })();
   }
@@ -1210,9 +1212,11 @@ async function* parseAnthropicBedrockEvents(events) {
 function bedrock(config) {
   const { model, region, maxTokens = 4096 } = config;
   if (!isAnthropicModel(model)) {
-    throw new Error(
-      `bedrock: model "${model}" is not supported in v1. Only anthropic.* models are wired up; Titan + others are tracked as a follow-up.`
-    );
+    throw new ConfigError({
+      code: ErrorCodes.AK_CONFIG_INVALID,
+      message: `bedrock: model "${model}" is not supported in v1. Only anthropic.* models are wired up; Titan + others are tracked as a follow-up.`,
+      hint: 'Pass an anthropic.* model id like "anthropic.claude-3-5-sonnet-20241022-v2:0".'
+    });
   }
   let clientPromise = null;
   const getClient = async () => {
@@ -1271,8 +1275,6 @@ function bedrock(config) {
   };
 }
 var bedrockAdapter = bedrock;
-
-// src/webllm.ts
 var cachedSdk2 = null;
 async function loadSdk2() {
   if (!cachedSdk2) {
@@ -1284,7 +1286,11 @@ async function loadSdk2() {
           moduleId
         );
       } catch {
-        throw new Error("Install @mlc-ai/web-llm to use the webllm adapter: npm install @mlc-ai/web-llm");
+        throw new AdapterError({
+          code: ErrorCodes.AK_ADAPTER_MISSING,
+          message: "Install @mlc-ai/web-llm to use the webllm adapter: npm install @mlc-ai/web-llm",
+          hint: "webllm is browser-only and depends on the optional peer @mlc-ai/web-llm."
+        });
       }
     })();
   }
@@ -1334,8 +1340,6 @@ function webllm(config) {
   };
 }
 var webllmAdapter = webllm;
-
-// src/router.ts
 function requireCapabilities(request) {
   const needs = {};
   if (request.context?.tools && request.context.tools.length > 0) needs.tools = true;
@@ -1362,7 +1366,13 @@ function pickSyncPolicy(pool, policy) {
 }
 function createRouter(options) {
   const { candidates } = options;
-  if (candidates.length === 0) throw new Error("createRouter requires at least one candidate");
+  if (candidates.length === 0) {
+    throw new ConfigError({
+      code: ErrorCodes.AK_CONFIG_INVALID,
+      message: "createRouter requires at least one candidate",
+      hint: "Pass at least one candidate, e.g. createRouter({ candidates: [{ id, adapter, capabilities }] })."
+    });
+  }
   const policy = options.policy ?? "cheapest";
   return {
     createSource: (request) => {
@@ -1385,7 +1395,13 @@ function createRouter(options) {
           pickedBy = "classify:tags";
         }
       }
-      if (pool.length === 0) throw new Error("no candidate satisfies the request");
+      if (pool.length === 0) {
+        throw new AdapterError({
+          code: ErrorCodes.AK_ADAPTER_STREAM_FAILED,
+          message: "no candidate satisfies the request",
+          hint: "Ensure at least one candidate declares the required capabilities (tools, json, etc.)."
+        });
+      }
       if (typeof policy === "function") {
         const maybe = policy({ request, candidates: pool });
         if (maybe instanceof Promise) {
@@ -1395,14 +1411,26 @@ function createRouter(options) {
             stream: async function* () {
               const id = await maybe;
               const c3 = pool.find((x) => x.id === id);
-              if (!c3) throw new Error(`policy returned unknown id: ${id}`);
+              if (!c3) {
+                throw new ConfigError({
+                  code: ErrorCodes.AK_CONFIG_INVALID,
+                  message: `policy returned unknown id: ${id}`,
+                  hint: "Custom policy functions must return one of the candidate ids."
+                });
+              }
               options.onRoute?.({ id: c3.id, reason: pickedBy ?? "custom policy", request });
               for await (const chunk of c3.adapter.createSource(request).stream()) yield chunk;
             }
           };
         }
         const c2 = pool.find((x) => x.id === maybe);
-        if (!c2) throw new Error(`policy returned unknown id: ${maybe}`);
+        if (!c2) {
+          throw new ConfigError({
+            code: ErrorCodes.AK_CONFIG_INVALID,
+            message: `policy returned unknown id: ${maybe}`,
+            hint: "Custom policy functions must return one of the candidate ids."
+          });
+        }
         options.onRoute?.({ id: c2.id, reason: pickedBy ?? "custom policy", request });
         return c2.adapter.createSource(request);
       }
@@ -1412,8 +1440,6 @@ function createRouter(options) {
     }
   };
 }
-
-// src/ensemble.ts
 async function drain(source, timeoutMs) {
   const chunks = [];
   let text = "";
@@ -1458,7 +1484,11 @@ function majorityVote(branches, candidates) {
 }
 function createEnsembleAdapter(options) {
   if (options.candidates.length === 0) {
-    throw new Error("createEnsembleAdapter requires at least one candidate");
+    throw new ConfigError({
+      code: ErrorCodes.AK_CONFIG_INVALID,
+      message: "createEnsembleAdapter requires at least one candidate",
+      hint: "Pass at least one candidate, e.g. createEnsembleAdapter({ candidates: [{ id, adapter }] })."
+    });
   }
   const aggregate = options.aggregate ?? "majority-vote";
   return {
@@ -1498,7 +1528,14 @@ function createEnsembleAdapter(options) {
           if (aborted) return;
           const text = await finalText(branches);
           if (!text && branches.every((b) => b.error)) {
-            throw new Error("all ensemble branches failed");
+            const summary = branches.map((b) => `${b.id}: ${b.error?.message ?? "unknown"}`).join("; ");
+            const err = new AdapterError({
+              code: ErrorCodes.AK_ADAPTER_STREAM_FAILED,
+              message: `all ensemble branches failed (${summary})`,
+              hint: "Inspect each branch error via options.onBranches or the err.branchErrors field."
+            });
+            err.branchErrors = branches.map((b) => ({ id: b.id, error: b.error }));
+            throw err;
           }
           yield { type: "text", content: text, metadata: { ensemble: branches.map((b) => ({ id: b.id, bytes: b.text.length, error: b.error?.message })) } };
           yield { type: "done" };
@@ -1507,11 +1544,13 @@ function createEnsembleAdapter(options) {
     }
   };
 }
-
-// src/fallback.ts
 function createFallbackAdapter(candidates, options = {}) {
   if (candidates.length === 0) {
-    throw new Error("createFallbackAdapter requires at least one candidate");
+    throw new ConfigError({
+      code: ErrorCodes.AK_CONFIG_INVALID,
+      message: "createFallbackAdapter requires at least one candidate",
+      hint: 'Pass at least one candidate, e.g. createFallbackAdapter([{ id: "primary", adapter }]).'
+    });
   }
   return {
     createSource: (request) => {
@@ -1566,14 +1605,16 @@ function createFallbackAdapter(candidates, options = {}) {
             }
           }
           const summary = errors.map((e) => `${e.id}: ${e.error.message}`).join("; ");
-          throw new Error(`all fallback candidates failed (${summary})`);
+          throw new AdapterError({
+            code: ErrorCodes.AK_ADAPTER_STREAM_FAILED,
+            message: `all fallback candidates failed (${summary})`,
+            hint: "Check each candidate adapter's configuration and provider keys."
+          });
         }
       };
     }
   };
 }
-
-// src/mock.ts
 function mockAdapter(options) {
   const { response, delayMs = 0, history } = options;
   let callIndex = 0;
@@ -1658,7 +1699,11 @@ function inMemorySink() {
 }
 function replayAdapter(fixture) {
   if (fixture.length === 0) {
-    throw new Error("replayAdapter: fixture is empty");
+    throw new ConfigError({
+      code: ErrorCodes.AK_CONFIG_INVALID,
+      message: "replayAdapter: fixture is empty",
+      hint: "Pass a non-empty fixture; record one with recordingAdapter() first."
+    });
   }
   return mockAdapter({
     response: fixture.map((turn) => turn.chunks)
@@ -1667,11 +1712,13 @@ function replayAdapter(fixture) {
 
 // src/embedders/openai.ts
 async function fetchAvailableModels(baseUrl, apiKey) {
-  const response = await fetch(`${baseUrl}/v1/models`, {
+  const url = `${baseUrl}/v1/models`;
+  const response = await fetch(url, {
     headers: { "Authorization": `Bearer ${apiKey}` }
   });
   if (!response.ok) {
-    throw new Error(`HTTP ${response.status}`);
+    const body = await response.text().catch(() => "");
+    throw new Error(`HTTP ${response.status} from ${url}: ${body.slice(0, 200)}`);
   }
   const data = await response.json();
   return data.data.map((m) => m.id).filter((id) => id.includes("embed")).sort();
@@ -1712,9 +1759,11 @@ function openaiEmbedder(config) {
 
 // src/embedders/gemini.ts
 async function fetchAvailableModels2(baseUrl, apiKey) {
-  const response = await fetch(`${baseUrl}/v1beta/models?key=${apiKey}`);
+  const url = `${baseUrl}/v1beta/models?key=${apiKey}`;
+  const response = await fetch(url);
   if (!response.ok) {
-    throw new Error(`HTTP ${response.status}`);
+    const body = await response.text().catch(() => "");
+    throw new Error(`HTTP ${response.status} from gemini ${baseUrl}/v1beta/models: ${body.slice(0, 200)}`);
   }
   const data = await response.json();
   return data.models.filter((m) => m.supportedGenerationMethods.includes("embedContent")).map((m) => m.name.replace("models/", "")).sort();
@@ -1762,9 +1811,11 @@ function geminiEmbedder(config) {
 
 // src/embedders/ollama.ts
 async function fetchAvailableModels3(baseUrl) {
-  const response = await fetch(`${baseUrl}/api/tags`);
+  const url = `${baseUrl}/api/tags`;
+  const response = await fetch(url);
   if (!response.ok) {
-    throw new Error(`HTTP ${response.status}`);
+    const body = await response.text().catch(() => "");
+    throw new Error(`HTTP ${response.status} from ollama ${url}: ${body.slice(0, 200)}`);
   }
   const data = await response.json();
   return data.models.map((m) => m.name).filter((name) => name.includes("embed")).sort();
@@ -1799,14 +1850,14 @@ function ollamaEmbedder(config) {
     return data.embeddings[0];
   };
 }
-
-// src/embedders/openai-compatible.ts
 async function fetchAvailableModels4(baseUrl, apiKey) {
-  const response = await fetch(`${baseUrl}/v1/models`, {
+  const url = `${baseUrl}/v1/models`;
+  const response = await fetch(url, {
     headers: { "Authorization": `Bearer ${apiKey}` }
   });
   if (!response.ok) {
-    throw new Error(`HTTP ${response.status}`);
+    const body = await response.text().catch(() => "");
+    throw new Error(`HTTP ${response.status} from ${url}: ${body.slice(0, 200)}`);
   }
   const data = await response.json();
   return data.data.map((m) => m.id).filter((id) => id.includes("embed")).sort();
@@ -1827,7 +1878,11 @@ async function buildModelError4(provider, baseUrl, apiKey, originalError) {
 function createOpenAICompatibleEmbedder(provider, defaultBaseUrl) {
   return function embedder(config) {
     if (!config.model) {
-      throw new Error(`Model is required for ${provider}. Pass { model: "<model-name>" }.`);
+      throw new ConfigError({
+        code: ErrorCodes.AK_CONFIG_INVALID,
+        message: `Model is required for ${provider}. Pass { model: "<model-name>" }.`,
+        hint: `${provider} does not infer a default; pick a recent embedding model and pass it explicitly.`
+      });
     }
     const { apiKey, model, baseUrl = defaultBaseUrl } = config;
     return async (text) => {