@agentskit/adapters 0.12.2 → 0.13.0

package/dist/index.d.cts

@@ -1,82 +1,13 @@
+import { G as GenericAdapterConfig } from './createAdapter-Dfnf3Iio.cjs';
+export { C as CreateAdapterConfig, c as createAdapter } from './createAdapter-Dfnf3Iio.cjs';
 import * as _agentskit_core from '@agentskit/core';
-import { AdapterRequest, StreamChunk, AdapterFactory, StreamSource, AdapterCapabilities, EmbedFn } from '@agentskit/core';
-
-interface CreateAdapterConfig {
-    send: (request: AdapterRequest) => Promise<ReadableStream | Response>;
-    parse: (stream: ReadableStream) => AsyncIterableIterator<StreamChunk>;
-    abort?: () => void;
-}
-interface GenericAdapterConfig {
-    send: (request: AdapterRequest) => Promise<ReadableStream>;
-}
-
-declare function createAdapter(config: CreateAdapterConfig): AdapterFactory;
+import { AdapterFactory, AdapterRequest, DataRegion, AdapterCapabilities, StreamChunk, EmbedFn } from '@agentskit/core';
+export { DataRegion } from '@agentskit/core';
+import { R as RetryOptions } from './utils-ddwu4MN4.cjs';
+export { c as chunkText, f as fetchWithRetry, s as simulateStream } from './utils-ddwu4MN4.cjs';
 
 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;
@@ -428,6 +359,8 @@ declare const webllmAdapter: typeof webllm;
 interface RouterCandidate {
     id: string;
     adapter: AdapterFactory;
+    /** Data residency region for this adapter endpoint. */
+    region?: DataRegion;
     /**
      * Relative cost hint (lower wins for policy='cheapest'). Only
      * relative values matter — use $/1M tokens or any consistent unit.
@@ -443,13 +376,24 @@ interface RouterCandidate {
     capabilities?: AdapterCapabilities;
     /** Free-form tags used by classifier routing (e.g. 'fast', 'coding'). */
     tags?: string[];
+    /**
+     * Estimated grid CO2 intensity (gCO2eq per 1k tokens) for this
+     * adapter+region. Lower wins for `policy='greenest'`. Use
+     * `applyCarbonTable()` to populate from `DEFAULT_CARBON_TABLE` or
+     * a custom table.
+     */
+    gCO2PerKtok?: number;
 }
-type RouterPolicy = 'cheapest' | 'fastest' | 'capability-match' | ((input: {
+type RouterPolicy = 'cheapest' | 'fastest' | 'greenest' | 'green-cost' | 'capability-match' | ((input: {
     request: AdapterRequest;
     candidates: RouterCandidate[];
 }) => string | Promise<string>);
 interface RouterOptions {
     candidates: RouterCandidate[];
+    /** Require all selected adapters to match this data-residency region. */
+    region?: DataRegion;
+    /** Dynamic region selector. Takes precedence over `region`. */
+    regionOf?: (request: AdapterRequest) => DataRegion | undefined;
     /** Policy when `classify` doesn't pick a candidate. Default 'cheapest'. */
     policy?: RouterPolicy;
     /**
@@ -474,6 +418,66 @@ interface RouterOptions {
  */
 declare function createRouter(options: RouterOptions): AdapterFactory;
 
+/**
+ * Carbon-aware routing data. Estimated grid CO2 intensity (gCO2eq per
+ * 1k tokens) per provider+region. Numbers are best-effort approximations
+ * derived from public grid-mix data and provider PUE disclosures — they
+ * are good enough to differentiate "very dirty" from "very clean" but
+ * are not audited.
+ *
+ * Sources:
+ *   - Electricity Maps (electricitymaps.com) for grid carbon intensity.
+ *   - Provider PUE / efficiency reports (Anthropic, Google, AWS).
+ *   - LLMCarbon (Faiz et al., 2024) for tok→J coefficients.
+ *
+ * Pull-requests welcome to refine. The table is community-updateable
+ * and ships at compile time; a runtime table can be passed via
+ * `applyCarbonTable(candidates, customTable)`.
+ *
+ * Closes part of issue #209.
+ */
+type ProviderRegionKey = `${string}:${string}`;
+type CarbonTable = Record<ProviderRegionKey, number>;
+/**
+ * Default carbon table. Keys are `provider:region`; values are
+ * estimated gCO2eq per 1k tokens of typical mixed input/output. Lower
+ * is greener.
+ */
+declare const DEFAULT_CARBON_TABLE: CarbonTable;
+interface ApplyCarbonOptions {
+    /** Override the default table. */
+    table?: CarbonTable;
+    /**
+     * How to derive the lookup key for a candidate. Defaults to
+     * `${provider}:${region}` where `provider` is the candidate id
+     * before the first `-` and `region` is `candidate.region`.
+     */
+    keyFor?: (candidate: RouterCandidate) => ProviderRegionKey | undefined;
+    /** Fallback gCO2eq per 1k tokens when no table entry is found. */
+    fallback?: number;
+}
+/**
+ * Decorate a list of router candidates with `gCO2PerKtok` from a
+ * carbon table. Returns a new list — does not mutate the input.
+ *
+ * ```ts
+ * const candidates = applyCarbonTable([
+ *   { id: 'openai-eu',   adapter: openai({...}), region: 'swedencentral', cost: 0.6 },
+ *   { id: 'anthropic-us', adapter: anthropic({...}), region: 'us-east-1',   cost: 0.5 },
+ * ])
+ *
+ * const router = createRouter({ candidates, policy: 'green-cost' })
+ * ```
+ */
+declare function applyCarbonTable(candidates: RouterCandidate[], options?: ApplyCarbonOptions): RouterCandidate[];
+/**
+ * Estimated CO2 emitted by a single completion (grams). Multiply
+ * `gCO2PerKtok` by `tokens / 1000`. Provided as a convenience for
+ * dashboards / chargeback reports — runtimes typically derive this
+ * from token usage events.
+ */
+declare function estimateCO2Grams(gCO2PerKtok: number | undefined, tokens: number): number;
+
 interface EnsembleCandidate {
     id: string;
     adapter: AdapterFactory;
@@ -656,4 +660,125 @@ interface KimiEmbedderConfig extends OpenAICompatibleEmbedderConfig {
 }
 declare const kimiEmbedder: (config: OpenAICompatibleEmbedderConfig) => _agentskit_core.EmbedFn;
 
-export { type AnthropicConfig, type AzureOpenAIConfig, type BailConfig, type BedrockConfig, type BedrockRuntimeClientLike, type CerebrasConfig, type CohereConfig, type CreateAdapterConfig, type DeepSeekConfig, type DeepSeekEmbedderConfig, type EnsembleAggregator, type EnsembleBranchResult, type EnsembleCandidate, type EnsembleOptions, type FallbackCandidate, type FallbackOptions, type FireworksConfig, type GeminiConfig, type GeminiEmbedderConfig, type GenericAdapterConfig, type GrokConfig, type GrokEmbedderConfig, type GroqConfig, type HuggingFaceConfig, type KimiConfig, type KimiEmbedderConfig, type LMStudioConfig, type LangChainConfig, type LangGraphConfig, type LlamaCppConfig, type MistralConfig, type MockAdapterOptions, type MockResponse, type OllamaConfig, type OllamaEmbedderConfig, type OpenAICompatibleEmbedderConfig, type OpenAIConfig, type OpenAIEmbedderConfig, type OpenRouterConfig, type RecordedTurn, type RecordingFixture, type RecordingSink, type ReplicateConfig, type RetryOptions, type RouterCandidate, type RouterOptions, type RouterPolicy, type TogetherConfig, type VLLMConfig, type VercelAIConfig, type VertexConfig, type WebLlmConfig, type WebLlmEngineLike, 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 };
+/**
+ * Provider model deprecation policy. When a provider deprecates a
+ * model, today the adapter silently 404s in production. This module
+ * lets you ship a deprecation table per provider and pick a behaviour:
+ *
+ *  - `warn`  — log once at startup, keep using the model.
+ *  - `remap` — auto-substitute the configured successor.
+ *  - `fail`  — throw at startup so deploys catch it.
+ *
+ * The deprecation table is community-updateable: the default export
+ * holds known deprecations as of the AgentsKit release; consumers can
+ * pass their own table to override or extend.
+ *
+ * Closes issue #800.
+ */
+type DeprecationAction = 'warn' | 'remap' | 'fail';
+interface ModelDeprecation {
+    provider: string;
+    model: string;
+    /** ISO date the provider's sunset takes effect. */
+    sunsetOn?: string;
+    /** Suggested successor — used when `onDeprecation: 'remap'`. */
+    successor?: string;
+    /** Optional human-readable reason / link. */
+    note?: string;
+}
+interface DeprecationPolicy {
+    onDeprecation: DeprecationAction;
+    table?: ModelDeprecation[];
+    /** Sink for warnings. Defaults to `console.warn`. */
+    logger?: (msg: string) => void;
+}
+/**
+ * Known deprecations (current as of AgentsKit shipping). Bump on each
+ * release; PRs welcome. Successor picks lean towards the same
+ * provider's current default unless the entire family is gone.
+ */
+declare const DEFAULT_DEPRECATION_TABLE: ModelDeprecation[];
+interface ResolveModelInput {
+    provider: string;
+    model: string;
+}
+interface ResolveModelResult {
+    /** Final model id to use (may differ from input if remapped). */
+    model: string;
+    remapped: boolean;
+    deprecation?: ModelDeprecation;
+}
+declare function resolveModel(input: ResolveModelInput, policy: DeprecationPolicy): ResolveModelResult;
+/**
+ * Wrap an `AdapterFactory` so that any model field on its requests is
+ * checked against the deprecation policy at startup. Convenience for
+ * adapters that don't want to plumb the check into their own code:
+ *
+ * ```ts
+ * const adapter = withDeprecationPolicy(openai({ apiKey, model: 'gpt-3.5-turbo-0301' }), {
+ *   provider: 'openai',
+ *   onDeprecation: 'remap',
+ * })
+ * ```
+ *
+ * For adapters with internal model state (most), prefer calling
+ * `resolveModel()` inside the factory and substituting before the
+ * first request — this wrapper is a fallback for opaque adapters.
+ */
+declare function withDeprecationPolicy<F extends AdapterFactory>(factory: F, options: {
+    provider: string;
+    model: string;
+} & DeprecationPolicy): F;
+
+/**
+ * Credential rotation hook for adapters. Today rotating a provider key
+ * means bouncing the runtime — unacceptable for 24/7 production.
+ *
+ * Adapters opt in by accepting `apiKey` as either a `string`, a
+ * `() => string | Promise<string>`, or a `RotatingCredentials` holder.
+ * The holder lets external code (Vault, AWS Secrets Manager, KMS)
+ * push a new value without restart, and `refreshCredentials()` is the
+ * one-call API that performs the swap and emits an audit event.
+ *
+ * Closes issue #799.
+ */
+type CredentialResolver = () => string | Promise<string>;
+interface RotatingCredentials {
+    /** Resolve the current secret. Adapters call this on every request. */
+    current: CredentialResolver;
+    /** Replace the in-memory secret. Returns the new value. */
+    rotate: (next: string) => Promise<string>;
+    /** Subscribe to rotation events. Returns an unsubscribe handle. */
+    onRotate: (handler: (event: CredentialRotationEvent) => void) => () => void;
+}
+interface CredentialRotationEvent {
+    /** ISO timestamp of the rotation. */
+    rotatedAt: string;
+    /** Stable id (e.g. provider name) for audit-log correlation. */
+    id: string;
+    /** Last 4 chars of the new secret — useful for "did the rotation actually happen?" without leaking the key. */
+    fingerprint: string;
+}
+interface CredentialRefreshable {
+    /**
+     * Adapters that support credential rotation expose this method.
+     * Calling it replaces the in-memory secret. The next request uses
+     * the new value; in-flight requests are unaffected.
+     */
+    refreshCredentials: (next: string) => Promise<void>;
+}
+declare function createRotatingCredentials(initial: string, options: {
+    id: string;
+}): RotatingCredentials;
+/**
+ * Refresh credentials on any object that implements
+ * `CredentialRefreshable`. A no-op (with a debug log) if the adapter
+ * doesn't support rotation, so callers can run the rotation playbook
+ * across a heterogeneous set of adapters without branching.
+ */
+declare function refreshCredentials(adapter: unknown, next: string, options?: {
+    id?: string;
+    logger?: (msg: string) => void;
+}): Promise<boolean>;
+
+export { type AnthropicConfig, type ApplyCarbonOptions, type AzureOpenAIConfig, type BailConfig, type BedrockConfig, type BedrockRuntimeClientLike, type CarbonTable, type CerebrasConfig, type CohereConfig, type CredentialRefreshable, DEFAULT_CARBON_TABLE, DEFAULT_DEPRECATION_TABLE, type DeepSeekConfig, type DeepSeekEmbedderConfig, type DeprecationAction, type DeprecationPolicy, type EnsembleAggregator, type EnsembleBranchResult, type EnsembleCandidate, type EnsembleOptions, type FallbackCandidate, type FallbackOptions, type FireworksConfig, type GeminiConfig, type GeminiEmbedderConfig, GenericAdapterConfig, type GrokConfig, type GrokEmbedderConfig, type GroqConfig, type HuggingFaceConfig, type KimiConfig, type KimiEmbedderConfig, type LMStudioConfig, type LangChainConfig, type LangGraphConfig, type LlamaCppConfig, type MistralConfig, type MockAdapterOptions, type MockResponse, type ModelDeprecation, type OllamaConfig, type OllamaEmbedderConfig, type OpenAICompatibleEmbedderConfig, type OpenAIConfig, type OpenAIEmbedderConfig, type OpenRouterConfig, type ProviderRegionKey, type RecordedTurn, type RecordingFixture, type RecordingSink, type ReplicateConfig, type ResolveModelInput, type ResolveModelResult, RetryOptions, type RotatingCredentials, type RouterCandidate, type RouterOptions, type RouterPolicy, type TogetherConfig, type VLLMConfig, type VercelAIConfig, type VertexConfig, type WebLlmConfig, type WebLlmEngineLike, 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, openai, openaiEmbedder, openrouter, qwen, recordingAdapter, refreshCredentials, replayAdapter, replicate, replicateAdapter, resolveModel, together, vercelAI, vertex, vertexAdapter, vllm, webllm, webllmAdapter, withDeprecationPolicy };

package/dist/index.d.ts

@@ -1,82 +1,13 @@
+import { G as GenericAdapterConfig } from './createAdapter-Dfnf3Iio.js';
+export { C as CreateAdapterConfig, c as createAdapter } from './createAdapter-Dfnf3Iio.js';
 import * as _agentskit_core from '@agentskit/core';
-import { AdapterRequest, StreamChunk, AdapterFactory, StreamSource, AdapterCapabilities, EmbedFn } from '@agentskit/core';
-
-interface CreateAdapterConfig {
-    send: (request: AdapterRequest) => Promise<ReadableStream | Response>;
-    parse: (stream: ReadableStream) => AsyncIterableIterator<StreamChunk>;
-    abort?: () => void;
-}
-interface GenericAdapterConfig {
-    send: (request: AdapterRequest) => Promise<ReadableStream>;
-}
-
-declare function createAdapter(config: CreateAdapterConfig): AdapterFactory;
+import { AdapterFactory, AdapterRequest, DataRegion, AdapterCapabilities, StreamChunk, EmbedFn } from '@agentskit/core';
+export { DataRegion } from '@agentskit/core';
+import { R as RetryOptions } from './utils-ddwu4MN4.js';
+export { c as chunkText, f as fetchWithRetry, s as simulateStream } from './utils-ddwu4MN4.js';
 
 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;
@@ -428,6 +359,8 @@ declare const webllmAdapter: typeof webllm;
 interface RouterCandidate {
     id: string;
     adapter: AdapterFactory;
+    /** Data residency region for this adapter endpoint. */
+    region?: DataRegion;
     /**
      * Relative cost hint (lower wins for policy='cheapest'). Only
      * relative values matter — use $/1M tokens or any consistent unit.
@@ -443,13 +376,24 @@ interface RouterCandidate {
     capabilities?: AdapterCapabilities;
     /** Free-form tags used by classifier routing (e.g. 'fast', 'coding'). */
     tags?: string[];
+    /**
+     * Estimated grid CO2 intensity (gCO2eq per 1k tokens) for this
+     * adapter+region. Lower wins for `policy='greenest'`. Use
+     * `applyCarbonTable()` to populate from `DEFAULT_CARBON_TABLE` or
+     * a custom table.
+     */
+    gCO2PerKtok?: number;
 }
-type RouterPolicy = 'cheapest' | 'fastest' | 'capability-match' | ((input: {
+type RouterPolicy = 'cheapest' | 'fastest' | 'greenest' | 'green-cost' | 'capability-match' | ((input: {
     request: AdapterRequest;
     candidates: RouterCandidate[];
 }) => string | Promise<string>);
 interface RouterOptions {
     candidates: RouterCandidate[];
+    /** Require all selected adapters to match this data-residency region. */
+    region?: DataRegion;
+    /** Dynamic region selector. Takes precedence over `region`. */
+    regionOf?: (request: AdapterRequest) => DataRegion | undefined;
     /** Policy when `classify` doesn't pick a candidate. Default 'cheapest'. */
     policy?: RouterPolicy;
     /**
@@ -474,6 +418,66 @@ interface RouterOptions {
  */
 declare function createRouter(options: RouterOptions): AdapterFactory;
 
+/**
+ * Carbon-aware routing data. Estimated grid CO2 intensity (gCO2eq per
+ * 1k tokens) per provider+region. Numbers are best-effort approximations
+ * derived from public grid-mix data and provider PUE disclosures — they
+ * are good enough to differentiate "very dirty" from "very clean" but
+ * are not audited.
+ *
+ * Sources:
+ *   - Electricity Maps (electricitymaps.com) for grid carbon intensity.
+ *   - Provider PUE / efficiency reports (Anthropic, Google, AWS).
+ *   - LLMCarbon (Faiz et al., 2024) for tok→J coefficients.
+ *
+ * Pull-requests welcome to refine. The table is community-updateable
+ * and ships at compile time; a runtime table can be passed via
+ * `applyCarbonTable(candidates, customTable)`.
+ *
+ * Closes part of issue #209.
+ */
+type ProviderRegionKey = `${string}:${string}`;
+type CarbonTable = Record<ProviderRegionKey, number>;
+/**
+ * Default carbon table. Keys are `provider:region`; values are
+ * estimated gCO2eq per 1k tokens of typical mixed input/output. Lower
+ * is greener.
+ */
+declare const DEFAULT_CARBON_TABLE: CarbonTable;
+interface ApplyCarbonOptions {
+    /** Override the default table. */
+    table?: CarbonTable;
+    /**
+     * How to derive the lookup key for a candidate. Defaults to
+     * `${provider}:${region}` where `provider` is the candidate id
+     * before the first `-` and `region` is `candidate.region`.
+     */
+    keyFor?: (candidate: RouterCandidate) => ProviderRegionKey | undefined;
+    /** Fallback gCO2eq per 1k tokens when no table entry is found. */
+    fallback?: number;
+}
+/**
+ * Decorate a list of router candidates with `gCO2PerKtok` from a
+ * carbon table. Returns a new list — does not mutate the input.
+ *
+ * ```ts
+ * const candidates = applyCarbonTable([
+ *   { id: 'openai-eu',   adapter: openai({...}), region: 'swedencentral', cost: 0.6 },
+ *   { id: 'anthropic-us', adapter: anthropic({...}), region: 'us-east-1',   cost: 0.5 },
+ * ])
+ *
+ * const router = createRouter({ candidates, policy: 'green-cost' })
+ * ```
+ */
+declare function applyCarbonTable(candidates: RouterCandidate[], options?: ApplyCarbonOptions): RouterCandidate[];
+/**
+ * Estimated CO2 emitted by a single completion (grams). Multiply
+ * `gCO2PerKtok` by `tokens / 1000`. Provided as a convenience for
+ * dashboards / chargeback reports — runtimes typically derive this
+ * from token usage events.
+ */
+declare function estimateCO2Grams(gCO2PerKtok: number | undefined, tokens: number): number;
+
 interface EnsembleCandidate {
     id: string;
     adapter: AdapterFactory;
@@ -656,4 +660,125 @@ interface KimiEmbedderConfig extends OpenAICompatibleEmbedderConfig {
 }
 declare const kimiEmbedder: (config: OpenAICompatibleEmbedderConfig) => _agentskit_core.EmbedFn;
 
-export { type AnthropicConfig, type AzureOpenAIConfig, type BailConfig, type BedrockConfig, type BedrockRuntimeClientLike, type CerebrasConfig, type CohereConfig, type CreateAdapterConfig, type DeepSeekConfig, type DeepSeekEmbedderConfig, type EnsembleAggregator, type EnsembleBranchResult, type EnsembleCandidate, type EnsembleOptions, type FallbackCandidate, type FallbackOptions, type FireworksConfig, type GeminiConfig, type GeminiEmbedderConfig, type GenericAdapterConfig, type GrokConfig, type GrokEmbedderConfig, type GroqConfig, type HuggingFaceConfig, type KimiConfig, type KimiEmbedderConfig, type LMStudioConfig, type LangChainConfig, type LangGraphConfig, type LlamaCppConfig, type MistralConfig, type MockAdapterOptions, type MockResponse, type OllamaConfig, type OllamaEmbedderConfig, type OpenAICompatibleEmbedderConfig, type OpenAIConfig, type OpenAIEmbedderConfig, type OpenRouterConfig, type RecordedTurn, type RecordingFixture, type RecordingSink, type ReplicateConfig, type RetryOptions, type RouterCandidate, type RouterOptions, type RouterPolicy, type TogetherConfig, type VLLMConfig, type VercelAIConfig, type VertexConfig, type WebLlmConfig, type WebLlmEngineLike, 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 };
+/**
+ * Provider model deprecation policy. When a provider deprecates a
+ * model, today the adapter silently 404s in production. This module
+ * lets you ship a deprecation table per provider and pick a behaviour:
+ *
+ *  - `warn`  — log once at startup, keep using the model.
+ *  - `remap` — auto-substitute the configured successor.
+ *  - `fail`  — throw at startup so deploys catch it.
+ *
+ * The deprecation table is community-updateable: the default export
+ * holds known deprecations as of the AgentsKit release; consumers can
+ * pass their own table to override or extend.
+ *
+ * Closes issue #800.
+ */
+type DeprecationAction = 'warn' | 'remap' | 'fail';
+interface ModelDeprecation {
+    provider: string;
+    model: string;
+    /** ISO date the provider's sunset takes effect. */
+    sunsetOn?: string;
+    /** Suggested successor — used when `onDeprecation: 'remap'`. */
+    successor?: string;
+    /** Optional human-readable reason / link. */
+    note?: string;
+}
+interface DeprecationPolicy {
+    onDeprecation: DeprecationAction;
+    table?: ModelDeprecation[];
+    /** Sink for warnings. Defaults to `console.warn`. */
+    logger?: (msg: string) => void;
+}
+/**
+ * Known deprecations (current as of AgentsKit shipping). Bump on each
+ * release; PRs welcome. Successor picks lean towards the same
+ * provider's current default unless the entire family is gone.
+ */
+declare const DEFAULT_DEPRECATION_TABLE: ModelDeprecation[];
+interface ResolveModelInput {
+    provider: string;
+    model: string;
+}
+interface ResolveModelResult {
+    /** Final model id to use (may differ from input if remapped). */
+    model: string;
+    remapped: boolean;
+    deprecation?: ModelDeprecation;
+}
+declare function resolveModel(input: ResolveModelInput, policy: DeprecationPolicy): ResolveModelResult;
+/**
+ * Wrap an `AdapterFactory` so that any model field on its requests is
+ * checked against the deprecation policy at startup. Convenience for
+ * adapters that don't want to plumb the check into their own code:
+ *
+ * ```ts
+ * const adapter = withDeprecationPolicy(openai({ apiKey, model: 'gpt-3.5-turbo-0301' }), {
+ *   provider: 'openai',
+ *   onDeprecation: 'remap',
+ * })
+ * ```
+ *
+ * For adapters with internal model state (most), prefer calling
+ * `resolveModel()` inside the factory and substituting before the
+ * first request — this wrapper is a fallback for opaque adapters.
+ */
+declare function withDeprecationPolicy<F extends AdapterFactory>(factory: F, options: {
+    provider: string;
+    model: string;
+} & DeprecationPolicy): F;
+
+/**
+ * Credential rotation hook for adapters. Today rotating a provider key
+ * means bouncing the runtime — unacceptable for 24/7 production.
+ *
+ * Adapters opt in by accepting `apiKey` as either a `string`, a
+ * `() => string | Promise<string>`, or a `RotatingCredentials` holder.
+ * The holder lets external code (Vault, AWS Secrets Manager, KMS)
+ * push a new value without restart, and `refreshCredentials()` is the
+ * one-call API that performs the swap and emits an audit event.
+ *
+ * Closes issue #799.
+ */
+type CredentialResolver = () => string | Promise<string>;
+interface RotatingCredentials {
+    /** Resolve the current secret. Adapters call this on every request. */
+    current: CredentialResolver;
+    /** Replace the in-memory secret. Returns the new value. */
+    rotate: (next: string) => Promise<string>;
+    /** Subscribe to rotation events. Returns an unsubscribe handle. */
+    onRotate: (handler: (event: CredentialRotationEvent) => void) => () => void;
+}
+interface CredentialRotationEvent {
+    /** ISO timestamp of the rotation. */
+    rotatedAt: string;
+    /** Stable id (e.g. provider name) for audit-log correlation. */
+    id: string;
+    /** Last 4 chars of the new secret — useful for "did the rotation actually happen?" without leaking the key. */
+    fingerprint: string;
+}
+interface CredentialRefreshable {
+    /**
+     * Adapters that support credential rotation expose this method.
+     * Calling it replaces the in-memory secret. The next request uses
+     * the new value; in-flight requests are unaffected.
+     */
+    refreshCredentials: (next: string) => Promise<void>;
+}
+declare function createRotatingCredentials(initial: string, options: {
+    id: string;
+}): RotatingCredentials;
+/**
+ * Refresh credentials on any object that implements
+ * `CredentialRefreshable`. A no-op (with a debug log) if the adapter
+ * doesn't support rotation, so callers can run the rotation playbook
+ * across a heterogeneous set of adapters without branching.
+ */
+declare function refreshCredentials(adapter: unknown, next: string, options?: {
+    id?: string;
+    logger?: (msg: string) => void;
+}): Promise<boolean>;
+
+export { type AnthropicConfig, type ApplyCarbonOptions, type AzureOpenAIConfig, type BailConfig, type BedrockConfig, type BedrockRuntimeClientLike, type CarbonTable, type CerebrasConfig, type CohereConfig, type CredentialRefreshable, DEFAULT_CARBON_TABLE, DEFAULT_DEPRECATION_TABLE, type DeepSeekConfig, type DeepSeekEmbedderConfig, type DeprecationAction, type DeprecationPolicy, type EnsembleAggregator, type EnsembleBranchResult, type EnsembleCandidate, type EnsembleOptions, type FallbackCandidate, type FallbackOptions, type FireworksConfig, type GeminiConfig, type GeminiEmbedderConfig, GenericAdapterConfig, type GrokConfig, type GrokEmbedderConfig, type GroqConfig, type HuggingFaceConfig, type KimiConfig, type KimiEmbedderConfig, type LMStudioConfig, type LangChainConfig, type LangGraphConfig, type LlamaCppConfig, type MistralConfig, type MockAdapterOptions, type MockResponse, type ModelDeprecation, type OllamaConfig, type OllamaEmbedderConfig, type OpenAICompatibleEmbedderConfig, type OpenAIConfig, type OpenAIEmbedderConfig, type OpenRouterConfig, type ProviderRegionKey, type RecordedTurn, type RecordingFixture, type RecordingSink, type ReplicateConfig, type ResolveModelInput, type ResolveModelResult, RetryOptions, type RotatingCredentials, type RouterCandidate, type RouterOptions, type RouterPolicy, type TogetherConfig, type VLLMConfig, type VercelAIConfig, type VertexConfig, type WebLlmConfig, type WebLlmEngineLike, 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, openai, openaiEmbedder, openrouter, qwen, recordingAdapter, refreshCredentials, replayAdapter, replicate, replicateAdapter, resolveModel, together, vercelAI, vertex, vertexAdapter, vllm, webllm, webllmAdapter, withDeprecationPolicy };