melchizedek-agents 0.16.2 → 0.18.0

package/dist/lib/index.js

@@ -17,6 +17,7 @@ export { loadSyndicate, loadSyndicateFromRegistry, parseCliBindings, validateReg
 export { runSyndicateTurn, ingestTurnMemory } from './runtime/syndicateTurn.js';
 export { approvalResponsePart, pendingApproval, APPROVAL_REQUEST } from './runtime/approvals.js';
 export { compileGraph, compileSubagent } from './compile.js';
+export { compileWorkflow, isWorkflowSyndicate, describeInput } from './workflow.js';
 // ── Serve it over A2A, or call a remote A2A agent ───────────────────────────
 export { createA2AApp, compileAgentCard, currentRequestContext } from './a2a/app.js';
 export { callerTokens, firstOf, hashCallerToken, jwtIdentity, parseCallers, scopeSegment, sharedSecret, trustedHeader, } from './a2a/identity.js';

package/dist/lib/loadEnv.d.ts

@@ -19,6 +19,11 @@
  * as a credential. Before this, `cp .env.example .env` crashed the default
  * quickstart (`Invalid supabaseUrl`), made the doctor report every provider
  * funded, and turned the example bearer secret into a live one.
+ *
+ * `MELCHIZEDEK_DOTENV=off` in the environment skips every file: the process
+ * runs on its ambient environment alone. A container whose secrets arrive as
+ * real variables wants that, and so does a test that starts a bin from a
+ * clone holding a real `.env`, which must never reach live services.
  */
 /** True for template placeholders that must never act as real values. */
 export declare function isPlaceholderValue(value: string | undefined): boolean;

package/dist/lib/loadEnv.js

@@ -19,6 +19,11 @@
  * as a credential. Before this, `cp .env.example .env` crashed the default
  * quickstart (`Invalid supabaseUrl`), made the doctor report every provider
  * funded, and turned the example bearer secret into a live one.
+ *
+ * `MELCHIZEDEK_DOTENV=off` in the environment skips every file: the process
+ * runs on its ambient environment alone. A container whose secrets arrive as
+ * real variables wants that, and so does a test that starts a bin from a
+ * clone holding a real `.env`, which must never reach live services.
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
@@ -69,6 +74,8 @@ export function parseEnvFile(raw) {
  *   clone run from another directory still finds its own `.env`.
  */
 export function loadEnv(moduleUrl) {
+    if (process.env.MELCHIZEDEK_DOTENV?.trim().toLowerCase() === 'off')
+        return;
     const files = [join(process.cwd(), '.env')];
     if (moduleUrl) {
         const own = join(findRepoRoot(dirname(fileURLToPath(moduleUrl))), '.env');

package/dist/lib/loadSyndicate.d.ts

@@ -1,5 +1,12 @@
 import type { DispatchConfig } from './dispatch.ts';
 export type { DispatchConfig } from './dispatch.ts';
+import type { SkillsConfig } from './tools/skillToolset.ts';
+import type { OpenApiConfig } from './tools/openapiTools.ts';
+import type { ContextConfig, ExampleConfig } from './compile.ts';
+export type { OpenApiConfig } from './tools/openapiTools.ts';
+export type { SkillsConfig } from './tools/skillToolset.ts';
+import type { WorkflowConfig } from './workflowConfig.ts';
+export type { WorkflowConfig } from './workflowConfig.ts';
 export interface ThinkingConfig {
     /** Token budget for internal reasoning. 0 = off, -1 = dynamic. */
     thinkingBudget?: number;
@@ -81,6 +88,30 @@ export interface AgentYamlConfig {
      */
     outputSchema?: Record<string, unknown>;
     mcp_server_url?: string;
+    /** The MCP server's tools this agent may use; the rest are not exposed. */
+    mcp_tools?: string[];
+    /** Answers when `model` fails provider-side, or its provider's circuit is open (ADR 0044). */
+    fallback_model?: string;
+    /**
+     * Agent Skills (SKILL.md directories) this agent holds the way a coding
+     * harness does: the index in its instruction, a skill read on demand, its
+     * scripts run only after approval. lib/tools/skillToolset.ts.
+     */
+    skills?: SkillsConfig;
+    /**
+     * HTTP APIs this agent may call, each from an OpenAPI 3 spec file: one tool
+     * per operation, the GET operations unless `operations` names others, auth
+     * from environment variables. lib/tools/openapiTools.ts.
+     */
+    openapi?: OpenApiConfig[];
+    /** `gemini`: the model's Python runs in Gemini's server-side sandbox (ADR 0033). Gemini models only. */
+    code_execution?: 'gemini';
+    /** Compact a long conversation into a summary past a token threshold (ADR 0033). Delegate orchestrator only. */
+    context?: ContextConfig;
+    /** `task`: the agent works until it calls finish_task; its arguments are the node's output. Workflow nodes only. */
+    mode?: 'task';
+    /** Few-shot exchanges added to every request's instruction (ADK's ExampleTool). */
+    examples?: ExampleConfig[];
     orchestration?: {
         role?: 'primary' | 'sub-agent';
         delegates?: string[];
@@ -121,6 +152,24 @@ export interface SyndicateYamlConfig {
      * See lib/dispatch.ts for the full contract.
      */
     dispatch?: DispatchConfig;
+    /**
+     * Self-correction (ADK's reflect-and-retry plugins), on by default:
+     * `model_errors` retries a model reply ADK marks malformed (default 2),
+     * `tool_errors` caps a tool's retries after it throws, with structured
+     * guidance to the model (default 3). 0 turns either off. ADR 0034.
+     */
+    retries?: {
+        model_errors?: number;
+        tool_errors?: number;
+    };
+    /**
+     * Opts this syndicate into a WORKFLOW: a graph whose nodes are its agents
+     * (plus join, map, tool and ask_user nodes) and whose edges say what runs
+     * after what and on which route. The orchestrator is a node like any
+     * other; nothing delegates. Cannot be combined with `dispatch`.
+     * Contract: lib/workflow.ts.
+     */
+    workflow?: WorkflowConfig;
     /** Optional default variable definitions for {{token}} interpolation. */
     variables?: VariableMap;
     /** Defines the persistence and semantic memory layer for the syndicate. */
@@ -237,6 +286,7 @@ export declare function loadSyndicate(filename: string, options?: LoadSyndicateO
 export declare function readSyndicateFile(filename: string, options?: Pick<LoadSyndicateOptions, 'agentsDir' | 'shippedFallback'>): {
     raw: unknown;
     label: string;
+    filePath: string;
 };
 /**
  * Every nested `yaml_reference:` a syndicate reaches, read raw from the agents

package/dist/lib/loadSyndicate.js

@@ -228,8 +228,24 @@ export function collectGuards(config, loadNested = nestedLoader(config), seen =
 }
 export function loadSyndicate(filename, options = {}) {
     const { bindings = {}, overrides } = options;
-    const { raw, label } = readSyndicateFile(filename, options);
-    return resolveAndValidate(raw, label, { bindings, overrides });
+    const { raw, label, filePath } = readSyndicateFile(filename, options);
+    return anchorSpecPaths(resolveAndValidate(raw, label, { bindings, overrides }), path.dirname(filePath));
+}
+/**
+ * An `openapi:` spec path is written relative to the syndicate file, so a
+ * file copied with its specs keeps working from any working directory. A
+ * definition from the registry has no file and resolves against the cwd.
+ */
+function anchorSpecPaths(config, dir) {
+    const anchor = (agent) => {
+        for (const entry of agent?.openapi ?? [])
+            if (!path.isAbsolute(entry.spec))
+                entry.spec = path.resolve(dir, entry.spec);
+    };
+    anchor(config.orchestrator);
+    for (const sub of config.subagents ?? [])
+        anchor(sub);
+    return config;
 }
 /**
  * Read one syndicate file, unparsed values and all, from the agents root (the
@@ -266,7 +282,7 @@ export function readSyndicateFile(filename, options = {}) {
     // is under it), so a multi-file nested load says WHICH file is wrong.
     const rel = path.relative(process.cwd(), filePath);
     const label = rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? rel : filePath;
-    return { raw: parse(fileContent), label };
+    return { raw: parse(fileContent), label, filePath };
 }
 /**
  * Every nested `yaml_reference:` a syndicate reaches, read raw from the agents

package/dist/lib/memory/erase.d.ts

@@ -8,6 +8,11 @@
  * markers, and (without a namespace) its task tools' list and jobs
  * (migration 0010), in one transaction. Returns what each store lost.
  *
+ * With a namespace, ledger turns and A2A tasks are kept only when their
+ * conversation is still live in another namespace (migration 0011): they do
+ * not record the namespace, and a conversation whose session expired must
+ * not survive an erase.
+ *
  * Throws on any failure: a deletion request that silently did nothing is
  * worse than an error the caller can surface and retry.
  */

package/dist/lib/memory/erase.js

@@ -8,6 +8,11 @@
  * markers, and (without a namespace) its task tools' list and jobs
  * (migration 0010), in one transaction. Returns what each store lost.
  *
+ * With a namespace, ledger turns and A2A tasks are kept only when their
+ * conversation is still live in another namespace (migration 0011): they do
+ * not record the namespace, and a conversation whose session expired must
+ * not survive an erase.
+ *
  * Throws on any failure: a deletion request that silently did nothing is
  * worse than an error the caller can surface and retry.
  */

package/dist/lib/memory/providers.d.ts

@@ -97,3 +97,30 @@ export interface MemoryProviders {
  * model or embedder is Gemini.
  */
 export declare function memoryProvidersFromEnv(env?: NodeJS.ProcessEnv, geminiKey?: string): MemoryProviders;
+/**
+ * Where long-term memory sends a syndicate's transcripts: the provider that
+ * extracts facts and the one that embeds them. By default both are Gemini,
+ * whatever the agents run on, so a deployment approved for one provider can
+ * send transcripts to another without noticing; the server warns when they
+ * differ (memoryCrossesProviders).
+ */
+export declare function memoryDestinations(env?: NodeJS.ProcessEnv, override?: {
+    extractor?: {
+        model: string;
+    };
+    embedder?: {
+        provider: string;
+    };
+}): {
+    extraction: string;
+    embeddings: string;
+};
+/**
+ * The memory destinations a syndicate's own agents do not already use, or []
+ * when memory stays with the agents' providers. An embedding endpoint the
+ * operator configured themselves (`openai-compatible`) is not counted.
+ */
+export declare function memoryCrossesProviders(models: Array<string | undefined>, dest: {
+    extraction: string;
+    embeddings: string;
+}): string[];

package/dist/lib/memory/providers.js

@@ -238,3 +238,31 @@ export function memoryProvidersFromEnv(env = process.env, geminiKey) {
     }
     return { extractor, embedder };
 }
+/**
+ * Where long-term memory sends a syndicate's transcripts: the provider that
+ * extracts facts and the one that embeds them. By default both are Gemini,
+ * whatever the agents run on, so a deployment approved for one provider can
+ * send transcripts to another without noticing; the server warns when they
+ * differ (memoryCrossesProviders).
+ */
+export function memoryDestinations(env = process.env, override = {}) {
+    const model = override.extractor?.model ?? (env.MEMORY_EXTRACTION_MODEL?.trim() || MEMORY_EXTRACTION_MODEL);
+    return {
+        extraction: providerForModel(model),
+        embeddings: (override.embedder?.provider ?? (env.MEMORY_EMBEDDING_PROVIDER?.trim() || 'gemini')).toLowerCase(),
+    };
+}
+/**
+ * The memory destinations a syndicate's own agents do not already use, or []
+ * when memory stays with the agents' providers. An embedding endpoint the
+ * operator configured themselves (`openai-compatible`) is not counted.
+ */
+export function memoryCrossesProviders(models, dest) {
+    const agents = new Set(models.filter((m) => !!m).map((m) => providerForModel(m)));
+    const out = new Set();
+    if (!agents.has(dest.extraction))
+        out.add(dest.extraction);
+    if (dest.embeddings !== 'openai-compatible' && !agents.has(dest.embeddings))
+        out.add(dest.embeddings);
+    return [...out];
+}

package/dist/lib/models/capabilities.js

@@ -37,6 +37,7 @@ function directPlatform(provider) {
 export const SERVER_SIDE_TOOLS = {
     web_search: ['gemini', 'anthropic', 'openai', 'xai'],
     google_search: ['gemini'],
+    url_context: ['gemini'],
     x_search: ['xai'],
     collections_search: ['xai'],
 };
@@ -171,6 +172,15 @@ export const CAPABILITY_MATRIX = {
         vision: ok('test', 'user-turn images only'),
         native_search: nativeSearch('xai'),
     },
+    moonshot: {
+        delegation: ok(),
+        memory_tools: ok(),
+        structured_output: ok('test', 'strict json_schema; kimi-k2.6 is documented as unstable on complex schemas ($ref, oneOf)'),
+        thinking_with_tools: degraded('reasoning_content is not replayed across tool calls, which Moonshot asks for on kimi-k3, so the model re-reasons each step; effort travels as reasoning_effort (K3) or a thinking switch (K2.x)'),
+        streaming: ok(),
+        vision: ok('test', 'user-turn images only, sent as base64 (Moonshot takes no public image URLs)'),
+        native_search: unsupported("Moonshot's model-side $web_search retires 2026-10-20 and its successor is a REST call, not a request field; the web_search sentinel is dropped (use web_extract)"),
+    },
     ollama: {
         delegation: ok(),
         memory_tools: ok(),

package/dist/lib/models/endpoints.d.ts

@@ -11,7 +11,7 @@
  *   gemini     direct | vertex           Google Application Default Credentials
  *   anthropic  direct | bedrock | vertex AWS credential chain / Google ADC
  *   openai     direct | azure            AZURE_OPENAI_API_KEY, else Entra ID
- *   xai, ollama direct only
+ *   xai, moonshot, ollama  direct only (moonshot: MOONSHOT_BASE_URL for a proxy)
  *
  * Configuration comes from the environment (`endpointFromEnv`) or, per
  * request, from the server's `credentials` plug point, which may return an

package/dist/lib/models/endpoints.js

@@ -11,7 +11,7 @@
  *   gemini     direct | vertex           Google Application Default Credentials
  *   anthropic  direct | bedrock | vertex AWS credential chain / Google ADC
  *   openai     direct | azure            AZURE_OPENAI_API_KEY, else Entra ID
- *   xai, ollama direct only
+ *   xai, moonshot, ollama  direct only (moonshot: MOONSHOT_BASE_URL for a proxy)
  *
  * Configuration comes from the environment (`endpointFromEnv`) or, per
  * request, from the server's `credentials` plug point, which may return an
@@ -35,6 +35,7 @@ export const PLATFORMS_FOR = {
     anthropic: ['direct', 'bedrock', 'vertex'],
     openai: ['direct', 'azure'],
     xai: ['direct'],
+    moonshot: ['direct'],
     ollama: ['direct'],
 };
 const PLATFORM_ENV = {
@@ -99,6 +100,8 @@ export function endpointFromEnv(provider, env = process.env) {
             return { ...base, ...(trimmed(env.ANTHROPIC_BASE_URL) ? { baseURL: trimmed(env.ANTHROPIC_BASE_URL) } : {}) };
         case 'openai/direct':
             return { ...base, ...(trimmed(env.OPENAI_BASE_URL) ? { baseURL: trimmed(env.OPENAI_BASE_URL) } : {}) };
+        case 'moonshot/direct':
+            return { ...base, ...(trimmed(env.MOONSHOT_BASE_URL) ? { baseURL: trimmed(env.MOONSHOT_BASE_URL) } : {}) };
         case 'openai/azure': {
             const endpoint = trimmed(env.AZURE_OPENAI_ENDPOINT);
             const key = trimmed(env.AZURE_OPENAI_API_KEY);

package/dist/lib/models/fallback.d.ts

@@ -0,0 +1,41 @@
+/**
+ * lib/models/fallback.ts — a fallback model and a per-provider circuit
+ * breaker for an agent that declares `fallback_model:` (ADR 0044).
+ *
+ * WHY: lib/models/retry.ts makes one call survive a blip. It does nothing for
+ * an outage: every turn on a provider that is down spends its retries and
+ * fails. An agent that names a fallback model now answers from it instead,
+ * and a provider that keeps failing is skipped for a cooldown rather than
+ * tried on every turn.
+ *
+ * THE RULES:
+ *   - Only provider-side failures count: what retry.ts classifies retryable
+ *     (408/409/425/429/5xx, connection resets) once the adapter's own retries
+ *     are spent. A 4xx is the request's fault and is thrown as it is; a
+ *     canceled turn is never counted or redirected.
+ *   - The fallback runs only if the primary produced nothing yet: a stream
+ *     that failed midway is thrown, never replayed on another model.
+ *   - The breaker is per provider, shared by every agent in the process:
+ *     MODEL_BREAKER_THRESHOLD consecutive failures (default 5; 0 disables)
+ *     open it for MODEL_BREAKER_COOLDOWN_MS (default 30 s). While open, a
+ *     wrapped agent goes straight to its fallback; after the cooldown one
+ *     call is let through, and a success closes the circuit.
+ */
+import { BaseLlm } from '@google/adk';
+import type { BaseLlmConnection, LlmRequest, LlmResponse } from '@google/adk';
+/** True while `provider`'s circuit is open (calls skip it). */
+export declare function circuitOpen(provider: string, now?: number): boolean;
+/** For tests: close every circuit. */
+export declare function resetCircuits(): void;
+/** A provider-side failure: worth counting against the provider and worth a fallback. */
+export declare function isProviderFailure(err: unknown): boolean;
+export declare class FallbackLlm extends BaseLlm {
+    readonly primary: BaseLlm;
+    readonly fallback: BaseLlm;
+    private readonly log;
+    private readonly primaryProvider;
+    constructor(primary: BaseLlm, fallback: BaseLlm, log?: (m: string) => void);
+    generateContentAsync(llmRequest: LlmRequest, stream?: boolean, abortSignal?: AbortSignal): AsyncGenerator<LlmResponse, void>;
+    private onFallback;
+    connect(llmRequest: LlmRequest): Promise<BaseLlmConnection>;
+}

package/dist/lib/models/fallback.js

@@ -0,0 +1,105 @@
+/**
+ * lib/models/fallback.ts — a fallback model and a per-provider circuit
+ * breaker for an agent that declares `fallback_model:` (ADR 0044).
+ *
+ * WHY: lib/models/retry.ts makes one call survive a blip. It does nothing for
+ * an outage: every turn on a provider that is down spends its retries and
+ * fails. An agent that names a fallback model now answers from it instead,
+ * and a provider that keeps failing is skipped for a cooldown rather than
+ * tried on every turn.
+ *
+ * THE RULES:
+ *   - Only provider-side failures count: what retry.ts classifies retryable
+ *     (408/409/425/429/5xx, connection resets) once the adapter's own retries
+ *     are spent. A 4xx is the request's fault and is thrown as it is; a
+ *     canceled turn is never counted or redirected.
+ *   - The fallback runs only if the primary produced nothing yet: a stream
+ *     that failed midway is thrown, never replayed on another model.
+ *   - The breaker is per provider, shared by every agent in the process:
+ *     MODEL_BREAKER_THRESHOLD consecutive failures (default 5; 0 disables)
+ *     open it for MODEL_BREAKER_COOLDOWN_MS (default 30 s). While open, a
+ *     wrapped agent goes straight to its fallback; after the cooldown one
+ *     call is let through, and a success closes the circuit.
+ */
+import { BaseLlm } from '@google/adk';
+import { classifyError } from './retry.js';
+import { providerForModel } from './providerMap.js';
+const circuits = new Map();
+function breakerSettings(env = process.env) {
+    const n = (name, fallback) => {
+        const v = Number(env[name]);
+        return Number.isFinite(v) && v >= 0 ? Math.floor(v) : fallback;
+    };
+    return { threshold: n('MODEL_BREAKER_THRESHOLD', 5), cooldownMs: n('MODEL_BREAKER_COOLDOWN_MS', 30_000) };
+}
+/** True while `provider`'s circuit is open (calls skip it). */
+export function circuitOpen(provider, now = Date.now()) {
+    const c = circuits.get(provider);
+    return !!c && c.openUntil > now;
+}
+function recordFailure(provider, now = Date.now()) {
+    const { threshold, cooldownMs } = breakerSettings();
+    if (threshold === 0)
+        return;
+    const c = circuits.get(provider) ?? { failures: 0, openUntil: 0 };
+    c.failures += 1;
+    if (c.failures >= threshold)
+        c.openUntil = now + cooldownMs;
+    circuits.set(provider, c);
+}
+function recordSuccess(provider) {
+    circuits.delete(provider);
+}
+/** For tests: close every circuit. */
+export function resetCircuits() {
+    circuits.clear();
+}
+/** A provider-side failure: worth counting against the provider and worth a fallback. */
+export function isProviderFailure(err) {
+    if (err?.name === 'AbortError')
+        return false;
+    return classifyError(err).retryable;
+}
+export class FallbackLlm extends BaseLlm {
+    primary;
+    fallback;
+    log;
+    primaryProvider;
+    constructor(primary, fallback, log = (m) => console.warn(m)) {
+        super({ model: primary.model });
+        this.primary = primary;
+        this.fallback = fallback;
+        this.log = log;
+        this.primaryProvider = providerForModel(primary.model);
+    }
+    async *generateContentAsync(llmRequest, stream, abortSignal) {
+        if (circuitOpen(this.primaryProvider)) {
+            yield* this.onFallback(llmRequest, stream, abortSignal, `${this.primaryProvider} circuit is open`);
+            return;
+        }
+        let yielded = false;
+        try {
+            for await (const r of this.primary.generateContentAsync(llmRequest, stream, abortSignal)) {
+                yielded = true;
+                yield r;
+            }
+            recordSuccess(this.primaryProvider);
+        }
+        catch (err) {
+            if (abortSignal?.aborted || !isProviderFailure(err))
+                throw err;
+            recordFailure(this.primaryProvider);
+            if (yielded)
+                throw err;
+            yield* this.onFallback(llmRequest, stream, abortSignal, `${this.primary.model} failed (${err instanceof Error ? err.message.slice(0, 120) : String(err)})`);
+        }
+    }
+    async *onFallback(llmRequest, stream, abortSignal, why) {
+        this.log(`[models] ${why}; answering from ${this.fallback.model}.`);
+        const request = { ...llmRequest, model: this.fallback.model };
+        yield* this.fallback.generateContentAsync(request, stream, abortSignal);
+    }
+    connect(llmRequest) {
+        return this.primary.connect(llmRequest);
+    }
+}

package/dist/lib/models/gateway.d.ts

@@ -4,7 +4,7 @@
  * WHY this file exists:
  *   A newcomer should be able to run every starter-pack syndicate with ONE
  *   credential when they choose to. A hosted gateway (Vercel AI Gateway,
- *   OpenRouter) fronts OpenAI, Anthropic, Google and xAI behind a single
+ *   OpenRouter) fronts OpenAI, Anthropic, Google, xAI and Moonshot behind a single
  *   OpenAI-compatible endpoint, so a model id whose direct key is absent can
  *   still be served. This module owns that decision and nothing else.
  *
@@ -80,7 +80,7 @@ export declare function gatewayUsable(): boolean;
  * Gateways prefix every id with the upstream provider's slug and spell
  * Anthropic's version segment with a dot ("claude-sonnet-4-6" is
  * "anthropic/claude-sonnet-4.6" on both Vercel and OpenRouter). Gemini,
- * GPT and Grok ids already carry dots, so only the prefix is added. An id
+ * GPT, Grok and Kimi ids already carry dots, so only the prefix is added. An id
  * the mapper gets wrong is fixed in MODEL_GATEWAY_MODEL_MAP, not in code.
  */
 export declare function gatewayWireModel(model: string, gateway: GatewayInfo): string;

package/dist/lib/models/gateway.js

@@ -4,7 +4,7 @@
  * WHY this file exists:
  *   A newcomer should be able to run every starter-pack syndicate with ONE
  *   credential when they choose to. A hosted gateway (Vercel AI Gateway,
- *   OpenRouter) fronts OpenAI, Anthropic, Google and xAI behind a single
+ *   OpenRouter) fronts OpenAI, Anthropic, Google, xAI and Moonshot behind a single
  *   OpenAI-compatible endpoint, so a model id whose direct key is absent can
  *   still be served. This module owns that decision and nothing else.
  *
@@ -49,14 +49,14 @@ export const GATEWAYS = {
         label: 'Vercel AI Gateway',
         baseUrl: 'https://ai-gateway.vercel.sh/v1',
         consoleUrl: 'https://vercel.com/ai-gateway',
-        slugs: { gemini: 'google', anthropic: 'anthropic', openai: 'openai', xai: 'xai' },
+        slugs: { gemini: 'google', anthropic: 'anthropic', openai: 'openai', xai: 'xai', moonshot: 'moonshotai' },
     },
     openrouter: {
         id: 'openrouter',
         label: 'OpenRouter',
         baseUrl: 'https://openrouter.ai/api/v1',
         consoleUrl: 'https://openrouter.ai/keys',
-        slugs: { gemini: 'google', anthropic: 'anthropic', openai: 'openai', xai: 'x-ai' },
+        slugs: { gemini: 'google', anthropic: 'anthropic', openai: 'openai', xai: 'x-ai', moonshot: 'moonshotai' },
     },
 };
 /**
@@ -119,7 +119,7 @@ function modelMapFromEnv() {
  * Gateways prefix every id with the upstream provider's slug and spell
  * Anthropic's version segment with a dot ("claude-sonnet-4-6" is
  * "anthropic/claude-sonnet-4.6" on both Vercel and OpenRouter). Gemini,
- * GPT and Grok ids already carry dots, so only the prefix is added. An id
+ * GPT, Grok and Kimi ids already carry dots, so only the prefix is added. An id
  * the mapper gets wrong is fixed in MODEL_GATEWAY_MODEL_MAP, not in code.
  */
 export function gatewayWireModel(model, gateway) {

package/dist/lib/models/kimiLlm.d.ts

@@ -0,0 +1,123 @@
+/**
+ * lib/models/kimiLlm.ts — Moonshot AI (Kimi) provider for the ADK LLMRegistry.
+ *
+ * WHY this file exists:
+ *   Model optionality is a primary driver of this framework: the agent YAML
+ *   declares `model`, and the registry routes it to the right provider.
+ *   Kimi K3 (July 2026) is the strongest open-weight model on the public
+ *   coding and research boards, and Moonshot serves it first-party with
+ *   tool calling, strict structured output and vision, so it earns a
+ *   direct adapter rather than only the gateway path.
+ *
+ * WHY it subclasses the chat-completions base (lib/models/openAiCompatibleLlm.ts):
+ *   Moonshot's API is OpenAI Chat Completions at https://api.moonshot.ai/v1
+ *   (it also serves Responses on the same base and Anthropic Messages at
+ *   /anthropic; neither adds a capability the chat dialect lacks here).
+ *   The base provides tool calling, strict `json_schema` structured output
+ *   (Moonshot documents `strict: true`), SSE streaming with usage, image
+ *   parts as base64 data URIs (Moonshot rejects public image URLs, which is
+ *   what the base never sends), `reasoning_content` surfaced as THINKING
+ *   output, retries, and the llm.request span.
+ *
+ * HOW TO ENABLE:
+ *   1. Create a key at https://platform.moonshot.ai (international; the
+ *      .cn console serves mainland China) and put it in .env as
+ *      MOONSHOT_API_KEY.
+ *   2. Set model: "kimi-k3" (or any kimi-* id) in your YAML.
+ *   registerAvailableProviders() registers this adapter when the key is set.
+ *   Optional: MOONSHOT_BASE_URL for a proxy that speaks the same dialect.
+ *
+ * THE FAMILY (platform.moonshot.ai › Model list, October 2026; USD per 1M tokens):
+ *
+ *     model                      context   in / cache hit / out   use it for
+ *     ──────────────────────────────────────────────────────────────────────
+ *     kimi-k3                    1M        $3.00 / $0.30 / $15    DEFAULT — the flagship: 2.8T MoE, vision,
+ *                                                                 always-on thinking, effort low|high|max
+ *     kimi-k2.6                  256K      $0.95 / $0.16 / $4     the cheaper general tier: vision, thinking
+ *                                                                 switchable; fragile on complex schemas
+ *     kimi-k2.7-code             256K      $0.95 / $0.19 / $4     coding; thinking cannot be turned off
+ *     kimi-k2.7-code-highspeed   256K      $1.90 / $0.38 / $8     the same model at ~180 tokens/s
+ *
+ * CHOOSING A MODEL (cost is a design property; see the model-routing skill):
+ *   K3 is priced like a mid-tier closed model, not like an open-weight
+ *   bargain: $3 / $15 is Claude Sonnet 4.6's price, and Claude Sonnet 5.5
+ *   ($2 / $10, cache reads $0.20) undercuts it on every token while sitting
+ *   above it on the coding boards. Two things make K3 dearer than its list
+ *   price: thinking is always on and billed as output, and Moonshot's
+ *   default effort is max — hence the pinned DEFAULT_KIMI_REASONING_EFFORT
+ *   and the zoo agent at "low". What K3 buys is the strongest open-weight
+ *   model (a self-host option) and a 1M context at a flat rate. For cost,
+ *   reach for kimi-k2.6 (a quarter of K3's price, vision and tools) on
+ *   subagent and bulk work, or serve K3 through the gateway: OpenRouter's
+ *   endpoints range from about $0.88 to $3.45 per 1M input, the cheap ones
+ *   quantized, with fidelity as the trade.
+ *
+ *   There is no small or "flash" K3; K2.6 is the light tier. K3's weights
+ *   are open (moonshotai/Kimi-K3 on Hugging Face), so the id is also served
+ *   by OpenRouter, Together, Fireworks, Vercel AI Gateway and others; with
+ *   no direct key, MODEL_GATEWAY serves it as `moonshotai/kimi-k3`
+ *   (lib/models/gateway.ts). kimi-k2.5 and the moonshot-v1 ids were retired
+ *   on 2026-08-31 and are not routed here on purpose.
+ *
+ * REASONING:
+ *   K3 always thinks; the lever is the top-level `reasoning_effort`
+ *   (low | high | max, Moonshot's default max). Requests pin
+ *   DEFAULT_KIMI_REASONING_EFFORT (lib/config.ts) unless the agent sets
+ *   generateContentConfig.reasoningEffort; "none" is mapped to "low" on
+ *   K3, which cannot switch thinking off. K2.x models take no
+ *   reasoning_effort: a `thinking: { type }` switch instead, so on those
+ *   ids reasoningEffort "none" or thinkingBudget 0 sends `disabled` and
+ *   any effort value is dropped from the body (K2.7 Code rejects
+ *   disabled thinking; Moonshot's own error says so).
+ *
+ * LIMITATIONS:
+ *   - web_search: Moonshot's model-side `$web_search` built-in retires on
+ *     2026-10-20 and its replacement is a separate REST API
+ *     (POST /v1/tools/search, billed per call), not a tool the model
+ *     enables in the request. The sentinel is therefore dropped with a
+ *     warning, like on Ollama; `web_extract` works, and `MOONSHOT_API_KEY`
+ *     would fund a client-side search tool over that REST API if one is
+ *     added (lib/tools/).
+ *   - Thinking with tools: Moonshot asks that K3's `reasoning_content` be
+ *     passed back with the assistant message on a tool loop. This base
+ *     keeps scratchpads out of history, so K3 re-reasons each step
+ *     (degraded, stated in lib/models/capabilities.ts); if Moonshot ever
+ *     enforces it, the turn ends with MOONSHOT_HTTP_ERROR naming the field.
+ *   - Every cell of its capability row is asserted against the request body
+ *     the adapter sends (tests/capabilityMatrix.test.ts), as for every other
+ *     provider. Verified live on 2026-10-03 through `npm run demo:models`:
+ *     kimi-k3 at low effort answered the zoo's explainer prompt in 17.9 s,
+ *     440 tokens in, 486 out, 262 of them thinking, the scratchpad surfaced
+ *     from reasoning_content; tool loops and search were not exercised.
+ */
+import type { LlmRequest, LlmResponse } from '@google/adk';
+import { OpenAiCompatibleLlm } from './openAiCompatibleLlm.ts';
+export declare const MOONSHOT_BASE_URL = "https://api.moonshot.ai/v1";
+/** The flagship takes `reasoning_effort`; the K2 generation takes a `thinking` switch. */
+export declare function isKimiK3(model: string): boolean;
+export declare class KimiLlm extends OpenAiCompatibleLlm {
+    /** Any model: "kimi-*" in a YAML config routes here after registration. */
+    static readonly supportedModels: Array<string | RegExp>;
+    private readonly apiKey?;
+    private readonly baseUrl;
+    constructor({ model, apiKey, baseUrl }: {
+        model: string;
+        apiKey?: string;
+        baseUrl?: string;
+    });
+    protected providerId(): string;
+    protected endpointUrl(): string;
+    private key;
+    protected headers(): Record<string, string>;
+    protected missingRequirement(): LlmResponse | undefined;
+    protected httpError(status: number, detail: string): LlmResponse;
+    /**
+     * The reasoning controls, per generation (see the header). The base has
+     * already put `reasoning_effort` in the body when the agent set one;
+     * these fields are merged after it, so an `undefined` here removes it
+     * (JSON.stringify drops undefined keys).
+     */
+    protected extraBodyFields(llmRequest: LlmRequest): Record<string, unknown>;
+}
+/** Registers KimiLlm with the ADK LLMRegistry (called when MOONSHOT_API_KEY is set). */
+export declare function registerKimiLlm(): void;