@agentskit/adapters 0.12.0 → 0.13.0

package/dist/index.js

@@ -1,25 +1,7 @@
-// src/createAdapter.ts
-function createAdapter(config) {
-  return {
-    createSource: (request) => ({
-      stream: async function* () {
-        try {
-          const result = await config.send(request);
-          const stream = result instanceof Response ? result.body : result;
-          yield* config.parse(stream);
-        } catch (err) {
-          yield {
-            type: "error",
-            content: err instanceof Error ? err.message : String(err)
-          };
-        }
-      },
-      abort: () => {
-        config.abort?.();
-      }
-    })
-  };
-}
+export { createAdapter } from './chunk-6FPLWOVE.js';
+import { createStreamSource, parseAnthropicStream, parseGeminiStream, parseOllamaStream, toProviderMessages, parseOpenAIStream, openai } from './chunk-726IKNNR.js';
+export { chunkText, fetchWithRetry, openai, simulateStream } from './chunk-726IKNNR.js';
+import { ConfigError, ErrorCodes, AdapterError } from '@agentskit/core';
 
 // src/generic.ts
 function generic(config) {
@@ -56,429 +38,6 @@ function generic(config) {
   };
 }
 
-// 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;
-}
-async function* readSSELines(stream) {
-  const reader = stream.getReader();
-  const decoder = new TextDecoder();
-  let buffer = "";
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      buffer += decoder.decode(value, { stream: true });
-      const lines = buffer.split("\n");
-      buffer = lines.pop() ?? "";
-      for (const line of lines) {
-        if (!line.startsWith("data: ")) continue;
-        const data = line.slice(6).trim();
-        if (data) yield data;
-      }
-    }
-  } finally {
-    reader.releaseLock();
-  }
-}
-async function* readNDJSONLines(stream) {
-  const reader = stream.getReader();
-  const decoder = new TextDecoder();
-  let buffer = "";
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      buffer += decoder.decode(value, { stream: true });
-      const lines = buffer.split("\n");
-      buffer = lines.pop() ?? "";
-      for (const line of lines) {
-        const trimmed = line.trim();
-        if (trimmed) yield trimmed;
-      }
-    }
-  } finally {
-    reader.releaseLock();
-  }
-}
-async function* parseOpenAIStream(stream) {
-  const pendingToolCalls = /* @__PURE__ */ new Map();
-  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 || "{}" } };
-      }
-      pendingToolCalls.clear();
-      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 };
-      }
-      if (Array.isArray(delta?.tool_calls)) {
-        for (const toolCall of delta.tool_calls) {
-          const index = toolCall.index ?? 0;
-          const existing = pendingToolCalls.get(index);
-          if (toolCall?.function?.name) {
-            pendingToolCalls.set(index, {
-              id: toolCall.id ?? existing?.id ?? `tool-${index}-${Date.now()}`,
-              name: toolCall.function.name,
-              args: (existing?.args ?? "") + (toolCall.function.arguments ?? "")
-            });
-          } else if (existing && toolCall?.function?.arguments) {
-            existing.args += toolCall.function.arguments;
-          }
-        }
-      }
-      if (event.usage) {
-        yield {
-          type: "usage",
-          usage: {
-            promptTokens: event.usage.prompt_tokens ?? 0,
-            completionTokens: event.usage.completion_tokens ?? 0,
-            totalTokens: event.usage.total_tokens ?? 0
-          }
-        };
-      }
-    } catch {
-    }
-  }
-  for (const [, tc] of pendingToolCalls) {
-    yield { type: "tool_call", toolCall: { id: tc.id, name: tc.name, args: tc.args || "{}" } };
-  }
-  pendingToolCalls.clear();
-  yield { type: "done" };
-}
-async function* parseAnthropicStream(stream) {
-  const pendingToolCalls = /* @__PURE__ */ new Map();
-  for await (const data of readSSELines(stream)) {
-    if (data === "[DONE]") continue;
-    try {
-      const event = JSON.parse(data);
-      if (event.type === "content_block_delta" && event.delta?.type === "text_delta" && event.delta?.text) {
-        yield { type: "text", content: event.delta.text };
-      } else if (event.type === "content_block_delta" && event.delta?.type === "input_json_delta") {
-        const index = event.index ?? 0;
-        const existing = pendingToolCalls.get(index);
-        if (existing) {
-          existing.args += event.delta.partial_json ?? "";
-        }
-      } else if (event.type === "content_block_start" && event.content_block?.type === "tool_use") {
-        const index = event.index ?? 0;
-        pendingToolCalls.set(index, {
-          id: event.content_block.id,
-          name: event.content_block.name,
-          args: ""
-        });
-      } else if (event.type === "content_block_stop") {
-        const index = event.index ?? 0;
-        const tc = pendingToolCalls.get(index);
-        if (tc) {
-          yield {
-            type: "tool_call",
-            toolCall: {
-              id: tc.id,
-              name: tc.name,
-              args: tc.args || "{}"
-            }
-          };
-          pendingToolCalls.delete(index);
-        }
-      } else if (event.type === "message_delta" && event.usage) {
-        yield {
-          type: "usage",
-          usage: {
-            promptTokens: event.usage.input_tokens ?? 0,
-            completionTokens: event.usage.output_tokens ?? 0,
-            totalTokens: (event.usage.input_tokens ?? 0) + (event.usage.output_tokens ?? 0)
-          }
-        };
-      } else if (event.type === "message_start" && event.message?.usage) {
-        yield {
-          type: "usage",
-          usage: {
-            promptTokens: event.message.usage.input_tokens ?? 0,
-            completionTokens: 0,
-            totalTokens: event.message.usage.input_tokens ?? 0
-          }
-        };
-      } else if (event.type === "message_stop") {
-        for (const [, tc] of pendingToolCalls) {
-          yield { type: "tool_call", toolCall: { id: tc.id, name: tc.name, args: tc.args || "{}" } };
-        }
-        pendingToolCalls.clear();
-        yield { type: "done" };
-        return;
-      }
-    } catch {
-    }
-  }
-  for (const [, tc] of pendingToolCalls) {
-    yield { type: "tool_call", toolCall: { id: tc.id, name: tc.name, args: tc.args || "{}" } };
-  }
-  pendingToolCalls.clear();
-  yield { type: "done" };
-}
-async function* parseGeminiStream(stream) {
-  for await (const data of readSSELines(stream)) {
-    try {
-      const event = JSON.parse(data);
-      if (event.usageMetadata) {
-        yield {
-          type: "usage",
-          usage: {
-            promptTokens: event.usageMetadata.promptTokenCount ?? 0,
-            completionTokens: event.usageMetadata.candidatesTokenCount ?? 0,
-            totalTokens: event.usageMetadata.totalTokenCount ?? 0
-          }
-        };
-      }
-      const parts = event.candidates?.[0]?.content?.parts;
-      if (!Array.isArray(parts)) continue;
-      for (const part of parts) {
-        if (typeof part.text === "string" && part.text) {
-          yield { type: "text", content: part.text };
-        } else if (part.functionCall) {
-          const fc = part.functionCall;
-          yield {
-            type: "tool_call",
-            toolCall: {
-              id: fc.id ?? `${fc.name}-${Date.now()}`,
-              name: fc.name,
-              args: JSON.stringify(fc.args ?? {})
-            }
-          };
-        }
-      }
-    } catch {
-    }
-  }
-  yield { type: "done" };
-}
-async function* parseOllamaStream(stream) {
-  for await (const data of readNDJSONLines(stream)) {
-    try {
-      const event = JSON.parse(data);
-      if (event.message?.content) {
-        yield { type: "text", content: event.message.content };
-      }
-      if (Array.isArray(event.message?.tool_calls)) {
-        for (const tc of event.message.tool_calls) {
-          if (tc?.function?.name) {
-            yield {
-              type: "tool_call",
-              toolCall: {
-                id: tc.id ?? `${tc.function.name}-${Date.now()}`,
-                name: tc.function.name,
-                args: typeof tc.function.arguments === "string" ? tc.function.arguments : JSON.stringify(tc.function.arguments ?? {})
-              }
-            };
-          }
-        }
-      }
-      if (event.done) {
-        if (typeof event.prompt_eval_count === "number" || typeof event.eval_count === "number") {
-          const promptTokens = event.prompt_eval_count ?? 0;
-          const completionTokens = event.eval_count ?? 0;
-          yield {
-            type: "usage",
-            usage: {
-              promptTokens,
-              completionTokens,
-              totalTokens: promptTokens + completionTokens
-            }
-          };
-        }
-        yield { type: "done" };
-        return;
-      }
-    } catch {
-    }
-  }
-  yield { type: "done" };
-}
-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 fetchWithRetry(doFetch, abortController.signal, retry ?? {});
-        if (!response.ok || !response.body) {
-          yield { type: "error", content: `${errorLabel} error: ${response.status}` };
-          return;
-        }
-        yield* parse(response.body);
-      } 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;
-    }
-  };
-}
-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, retry } = config;
@@ -522,55 +81,6 @@ function anthropic(config) {
   };
 }
 
-// src/openai.ts
-function openai(config) {
-  const { apiKey, model, baseUrl = "https://api.openai.com", retry } = config;
-  const includeUsage = config.includeUsage ?? baseUrl.startsWith("https://api.openai.com");
-  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,
-        messages: toProviderMessages(request.messages),
-        tools: request.context?.tools?.map((tool) => ({
-          type: "function",
-          function: {
-            name: tool.name,
-            description: tool.description,
-            parameters: tool.schema
-          }
-        })),
-        temperature: request.context?.temperature,
-        max_tokens: request.context?.maxTokens,
-        stream: true
-      };
-      if (includeUsage) body.stream_options = { include_usage: true };
-      return createStreamSource(
-        (signal) => fetch(`${baseUrl}/v1/chat/completions`, {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            "Authorization": `Bearer ${apiKey}`
-          },
-          body: JSON.stringify(body),
-          signal
-        }),
-        parseOpenAIStream,
-        "OpenAI API",
-        retry
-      );
-    }
-  };
-}
-
 // src/gemini.ts
 function gemini(config) {
   const { apiKey, model, baseUrl = "https://generativelanguage.googleapis.com", retry } = config;
@@ -582,15 +92,13 @@ function gemini(config) {
       usage: true
     },
     createSource: (request) => {
+      const systemMessage = request.messages.find((message) => message.role === "system");
       const body = {
         contents: request.messages.filter((message) => message.role !== "system").map((message) => ({
           role: message.role === "assistant" ? "model" : "user",
           parts: [{ text: message.content }]
         })),
-        systemInstruction: request.messages.find((message) => message.role === "system") ? {
-          role: "system",
-          parts: [{ text: request.messages.find((message) => message.role === "system").content }]
-        } : void 0
+        systemInstruction: systemMessage ? { role: "system", parts: [{ text: systemMessage.content }] } : void 0
       };
       return createStreamSource(
         (signal) => fetch(
@@ -1056,15 +564,13 @@ function vertex(config) {
       reasoning: model.includes("pro")
     },
     createSource: (request) => {
+      const systemMessage = request.messages.find((message) => message.role === "system");
       const body = {
         contents: request.messages.filter((message) => message.role !== "system").map((message) => ({
           role: message.role === "assistant" ? "model" : "user",
           parts: [{ text: message.content }]
         })),
-        systemInstruction: request.messages.find((message) => message.role === "system") ? {
-          role: "system",
-          parts: [{ text: request.messages.find((message) => message.role === "system").content }]
-        } : void 0,
+        systemInstruction: systemMessage ? { role: "system", parts: [{ text: systemMessage.content }] } : void 0,
         tools: request.context?.tools && request.context.tools.length > 0 ? [{
           functionDeclarations: request.context.tools.map((tool) => ({
             name: tool.name,
@@ -1094,8 +600,6 @@ function vertex(config) {
   };
 }
 var vertexAdapter = vertex;
-
-// src/bedrock.ts
 var cachedSdk = null;
 async function loadSdk() {
   if (!cachedSdk) {
@@ -1107,9 +611,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 +716,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 +779,6 @@ function bedrock(config) {
   };
 }
 var bedrockAdapter = bedrock;
-
-// src/webllm.ts
 var cachedSdk2 = null;
 async function loadSdk2() {
   if (!cachedSdk2) {
@@ -1284,7 +790,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 +844,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;
@@ -1358,34 +866,75 @@ function pickSyncPolicy(pool, policy) {
     const c = pool.reduce((best, x) => (x.latencyMs ?? Infinity) < (best.latencyMs ?? Infinity) ? x : best, pool[0]);
     return { c, reason: "fastest" };
   }
+  if (policy === "greenest") {
+    const c = pool.reduce((best, x) => (x.gCO2PerKtok ?? Infinity) < (best.gCO2PerKtok ?? Infinity) ? x : best, pool[0]);
+    return { c, reason: "greenest" };
+  }
+  if (policy === "green-cost") {
+    const carbonValues = pool.map((p) => p.gCO2PerKtok).filter((v) => v != null);
+    const costValues = pool.map((p) => p.cost).filter((v) => v != null);
+    const maxC = Math.max(1, ...carbonValues);
+    const maxCost = Math.max(1, ...costValues);
+    const score = (x) => {
+      const carbon = (x.gCO2PerKtok ?? maxC / 2) / maxC;
+      const cost = (x.cost ?? maxCost / 2) / maxCost;
+      return carbon + cost;
+    };
+    const c = pool.reduce((best, x) => score(x) < score(best) ? x : best, pool[0]);
+    return { c, reason: "green-cost" };
+  }
   return { c: pool[0], reason: "capability-match" };
 }
+function matchesRegion(candidate, region) {
+  return region === void 0 || candidate.region === region;
+}
 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) => {
       const need = requireCapabilities(request);
+      const region = options.regionOf?.(request) ?? options.region;
       const capable = candidates.filter((c2) => matchesCapabilities(need, c2.capabilities ?? c2.adapter.capabilities));
+      const eligible = capable.filter((c2) => matchesRegion(c2, region));
+      if (capable.length > 0 && eligible.length === 0 && region !== void 0) {
+        throw new ConfigError({
+          code: ErrorCodes.AK_CONFIG_INVALID,
+          message: `no candidate satisfies required region: ${region}`,
+          hint: "Set candidate.region to the requested data-residency region, or remove the router region requirement."
+        });
+      }
       const classified = options.classify?.(request);
       if (typeof classified === "string") {
-        const c2 = capable.find((x) => x.id === classified);
+        const c2 = eligible.find((x) => x.id === classified);
         if (c2) {
-          options.onRoute?.({ id: c2.id, reason: "classify:id", request });
+          options.onRoute?.({ id: c2.id, reason: region ? `classify:id:${region}` : "classify:id", request });
           return c2.adapter.createSource(request);
         }
       }
-      let pool = capable;
+      let pool = eligible;
       let pickedBy;
       if (Array.isArray(classified) && classified.length > 0) {
-        const filtered = capable.filter((c2) => c2.tags && classified.every((t) => c2.tags.includes(t)));
+        const filtered = eligible.filter((c2) => c2.tags && classified.every((t) => c2.tags.includes(t)));
         if (filtered.length > 0) {
           pool = filtered;
-          pickedBy = "classify:tags";
+          pickedBy = region ? `classify:tags:${region}` : "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 +944,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);
       }
@@ -1413,7 +974,56 @@ function createRouter(options) {
   };
 }
 
-// src/ensemble.ts
+// src/carbon.ts
+var DEFAULT_CARBON_TABLE = {
+  // Anthropic — primarily AWS us-east-* / eu-west-* via Bedrock-style fronts.
+  "anthropic:us-east-1": 0.42,
+  "anthropic:us-west-2": 0.18,
+  "anthropic:eu-central-1": 0.32,
+  "anthropic:eu-west-1": 0.27,
+  // OpenAI — Azure East US / West Europe / Sweden Central.
+  "openai:eastus": 0.4,
+  "openai:westus3": 0.19,
+  "openai:swedencentral": 0.04,
+  "openai:westeurope": 0.28,
+  // Google (Vertex / Gemini) — typically reports lowest PUE.
+  "google:us-central1": 0.34,
+  "google:us-west1": 0.16,
+  "google:europe-west1": 0.21,
+  "google:europe-north1": 0.05,
+  // AWS Bedrock direct.
+  "aws:us-east-1": 0.42,
+  "aws:us-west-2": 0.18,
+  "aws:eu-west-1": 0.27,
+  // Local / on-device — only the device's grid matters.
+  "ollama:local": 0.3,
+  "webllm:browser": 0.3,
+  "lmstudio:local": 0.3,
+  // Self-hosted / community.
+  "groq:us-east-1": 0.4,
+  "fireworks:us-west-2": 0.18,
+  "together:us-east-1": 0.42,
+  "cerebras:us-west-2": 0.18
+};
+function defaultKey(candidate) {
+  if (!candidate.region) return void 0;
+  const provider = candidate.id.split(/[-:]/)[0];
+  return `${provider}:${candidate.region}`;
+}
+function applyCarbonTable(candidates, options = {}) {
+  const table = options.table ?? DEFAULT_CARBON_TABLE;
+  const keyFor = options.keyFor ?? defaultKey;
+  return candidates.map((c) => {
+    if (c.gCO2PerKtok != null) return c;
+    const key = keyFor(c);
+    const value = key ? table[key] : void 0;
+    return { ...c, gCO2PerKtok: value ?? options.fallback };
+  });
+}
+function estimateCO2Grams(gCO2PerKtok, tokens) {
+  if (gCO2PerKtok == null) return 0;
+  return tokens / 1e3 * gCO2PerKtok;
+}
 async function drain(source, timeoutMs) {
   const chunks = [];
   let text = "";
@@ -1458,7 +1068,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 +1112,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 +1128,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 +1189,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,21 +1283,34 @@ 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)
   });
 }
 
+// src/embedders/shared.ts
+var ERROR_BODY_PREVIEW_CHARS = 200;
+async function throwIfNotOk(response, label, url) {
+  if (response.ok) return;
+  const body = await response.text().catch(() => "");
+  throw new Error(
+    `HTTP ${response.status} from ${label} ${url}: ${body.slice(0, ERROR_BODY_PREVIEW_CHARS)}`
+  );
+}
+
 // 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}`);
-  }
+  await throwIfNotOk(response, "openai", url);
   const data = await response.json();
   return data.data.map((m) => m.id).filter((id) => id.includes("embed")).sort();
 }
@@ -1712,10 +1350,9 @@ function openaiEmbedder(config) {
 
 // src/embedders/gemini.ts
 async function fetchAvailableModels2(baseUrl, apiKey) {
-  const response = await fetch(`${baseUrl}/v1beta/models?key=${apiKey}`);
-  if (!response.ok) {
-    throw new Error(`HTTP ${response.status}`);
-  }
+  const url = `${baseUrl}/v1beta/models?key=${apiKey}`;
+  const response = await fetch(url);
+  await throwIfNotOk(response, "gemini", `${baseUrl}/v1beta/models`);
   const data = await response.json();
   return data.models.filter((m) => m.supportedGenerationMethods.includes("embedContent")).map((m) => m.name.replace("models/", "")).sort();
 }
@@ -1762,10 +1399,9 @@ function geminiEmbedder(config) {
 
 // src/embedders/ollama.ts
 async function fetchAvailableModels3(baseUrl) {
-  const response = await fetch(`${baseUrl}/api/tags`);
-  if (!response.ok) {
-    throw new Error(`HTTP ${response.status}`);
-  }
+  const url = `${baseUrl}/api/tags`;
+  const response = await fetch(url);
+  await throwIfNotOk(response, "ollama", url);
   const data = await response.json();
   return data.models.map((m) => m.name).filter((name) => name.includes("embed")).sort();
 }
@@ -1799,21 +1435,18 @@ function ollamaEmbedder(config) {
     return data.embeddings[0];
   };
 }
-
-// src/embedders/openai-compatible.ts
-async function fetchAvailableModels4(baseUrl, apiKey) {
-  const response = await fetch(`${baseUrl}/v1/models`, {
+async function fetchAvailableModels4(provider, baseUrl, apiKey) {
+  const url = `${baseUrl}/v1/models`;
+  const response = await fetch(url, {
     headers: { "Authorization": `Bearer ${apiKey}` }
   });
-  if (!response.ok) {
-    throw new Error(`HTTP ${response.status}`);
-  }
+  await throwIfNotOk(response, provider, url);
   const data = await response.json();
   return data.data.map((m) => m.id).filter((id) => id.includes("embed")).sort();
 }
 async function buildModelError4(provider, baseUrl, apiKey, originalError) {
   try {
-    const models = await fetchAvailableModels4(baseUrl, apiKey);
+    const models = await fetchAvailableModels4(provider, baseUrl, apiKey);
     const list = models.length > 0 ? models.join(", ") : "none found";
     return new Error(
       `${provider} embedding failed: ${originalError}. Available embedding models: ${list}`
@@ -1827,7 +1460,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) => {
@@ -1858,7 +1495,91 @@ var grokEmbedder = createOpenAICompatibleEmbedder("Grok", "https://api.x.ai");
 
 // src/embedders/kimi.ts
 var kimiEmbedder = createOpenAICompatibleEmbedder("Kimi", "https://api.moonshot.ai");
+var DEFAULT_DEPRECATION_TABLE = [
+  // OpenAI
+  { provider: "openai", model: "gpt-3.5-turbo-0301", successor: "gpt-4o-mini", sunsetOn: "2024-09-13" },
+  { provider: "openai", model: "gpt-3.5-turbo-0613", successor: "gpt-4o-mini", sunsetOn: "2024-09-13" },
+  { provider: "openai", model: "gpt-4-0314", successor: "gpt-4o", sunsetOn: "2024-06-13" },
+  { provider: "openai", model: "gpt-4-32k", successor: "gpt-4o", sunsetOn: "2024-06-06" },
+  { provider: "openai", model: "text-davinci-003", successor: "gpt-4o-mini", sunsetOn: "2024-01-04" },
+  // Anthropic
+  { provider: "anthropic", model: "claude-2.0", successor: "claude-3-5-sonnet-latest", sunsetOn: "2025-07-21" },
+  { provider: "anthropic", model: "claude-2.1", successor: "claude-3-5-sonnet-latest", sunsetOn: "2025-07-21" },
+  { provider: "anthropic", model: "claude-instant-1.2", successor: "claude-3-5-haiku-latest", sunsetOn: "2024-07-22" },
+  { provider: "anthropic", model: "claude-3-sonnet-20240229", successor: "claude-3-5-sonnet-latest", sunsetOn: "2025-07-21" },
+  // Google
+  { provider: "google", model: "gemini-1.0-pro", successor: "gemini-1.5-pro", sunsetOn: "2025-02-15" },
+  { provider: "google", model: "gemini-pro-vision", successor: "gemini-1.5-pro", sunsetOn: "2024-07-12" }
+];
+function resolveModel(input, policy) {
+  const table = policy.table ?? DEFAULT_DEPRECATION_TABLE;
+  const hit = table.find((d) => d.provider === input.provider && d.model === input.model);
+  if (!hit) return { model: input.model, remapped: false };
+  const log = policy.logger ?? ((msg) => console.warn(msg));
+  const sunset = hit.sunsetOn ? ` (sunset ${hit.sunsetOn})` : "";
+  const successor = hit.successor ? ` Suggested successor: ${hit.successor}.` : "";
+  const base = `[agentskit] Model "${input.provider}:${input.model}" is deprecated${sunset}.${successor}`;
+  switch (policy.onDeprecation) {
+    case "fail":
+      throw new ConfigError({
+        code: ErrorCodes.AK_CONFIG_INVALID,
+        message: base,
+        hint: hit.successor ? `Set model to "${hit.successor}".` : "Pick a supported model from the provider."
+      });
+    case "remap": {
+      if (!hit.successor) {
+        throw new ConfigError({
+          code: ErrorCodes.AK_CONFIG_INVALID,
+          message: `${base} No successor available \u2014 cannot remap.`
+        });
+      }
+      log(`${base} Auto-remapping to "${hit.successor}".`);
+      return { model: hit.successor, remapped: true, deprecation: hit };
+    }
+    case "warn":
+    default:
+      log(base);
+      return { model: input.model, remapped: false, deprecation: hit };
+  }
+}
+function withDeprecationPolicy(factory, options) {
+  resolveModel({ provider: options.provider, model: options.model }, options);
+  return factory;
+}
+
+// src/credential-rotation.ts
+function createRotatingCredentials(initial, options) {
+  let value = initial;
+  const handlers = /* @__PURE__ */ new Set();
+  return {
+    current: () => value,
+    rotate: async (next) => {
+      value = next;
+      const event = {
+        rotatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        id: options.id,
+        fingerprint: next.slice(-4)
+      };
+      for (const h of handlers) h(event);
+      return next;
+    },
+    onRotate: (handler) => {
+      handlers.add(handler);
+      return () => handlers.delete(handler);
+    }
+  };
+}
+async function refreshCredentials(adapter, next, options) {
+  const log = options?.logger ?? ((msg) => console.log(msg));
+  if (adapter && typeof adapter === "object" && "refreshCredentials" in adapter && typeof adapter.refreshCredentials === "function") {
+    await adapter.refreshCredentials(next);
+    log(`[agentskit] credentials refreshed${options?.id ? ` (${options.id})` : ""}`);
+    return true;
+  }
+  log(`[agentskit] adapter does not support credential rotation; restart required${options?.id ? ` (${options.id})` : ""}`);
+  return false;
+}
 
-export { anthropic, azureOpenAI, azureOpenAIAdapter, bail, bailAdapter, bedrock, bedrockAdapter, cerebras, cerebrasAdapter, chunkText, cohere, cohereAdapter, createAdapter, createEnsembleAdapter, createFallbackAdapter, createOpenAICompatibleEmbedder, createRouter, deepseek, deepseekEmbedder, fetchWithRetry, fireworks, gemini, geminiEmbedder, generic, grok, grokEmbedder, groq, groqAdapter, huggingface, inMemorySink, kimi, kimiEmbedder, langchain, langgraph, llamacpp, lmstudio, mistral, mockAdapter, ollama, ollamaEmbedder, openai, openaiEmbedder, openrouter, qwen, recordingAdapter, replayAdapter, replicate, replicateAdapter, simulateStream, together, vercelAI, vertex, vertexAdapter, vllm, webllm, webllmAdapter };
+export { DEFAULT_CARBON_TABLE, DEFAULT_DEPRECATION_TABLE, anthropic, applyCarbonTable, azureOpenAI, azureOpenAIAdapter, bail, bailAdapter, bedrock, bedrockAdapter, cerebras, cerebrasAdapter, cohere, cohereAdapter, createEnsembleAdapter, createFallbackAdapter, createOpenAICompatibleEmbedder, createRotatingCredentials, createRouter, deepseek, deepseekEmbedder, estimateCO2Grams, fireworks, gemini, geminiEmbedder, generic, grok, grokEmbedder, groq, groqAdapter, huggingface, inMemorySink, kimi, kimiEmbedder, langchain, langgraph, llamacpp, lmstudio, mistral, mockAdapter, ollama, ollamaEmbedder, openaiEmbedder, openrouter, qwen, recordingAdapter, refreshCredentials, replayAdapter, replicate, replicateAdapter, resolveModel, together, vercelAI, vertex, vertexAdapter, vllm, webllm, webllmAdapter, withDeprecationPolicy };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map