melchizedek-agents 0.16.2 → 0.17.0

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/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/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;

package/dist/lib/models/kimiLlm.js

@@ -0,0 +1,171 @@
+/**
+ * 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 { LLMRegistry } from '@google/adk';
+import { DEFAULT_KIMI_REASONING_EFFORT } from '../config.js';
+import { OpenAiCompatibleLlm } from './openAiCompatibleLlm.js';
+export const MOONSHOT_BASE_URL = 'https://api.moonshot.ai/v1';
+/** The flagship takes `reasoning_effort`; the K2 generation takes a `thinking` switch. */
+export function isKimiK3(model) {
+    return /^kimi-k3\b/.test(model);
+}
+// ── KimiLlm ───────────────────────────────────────────────────────────────────
+export class KimiLlm extends OpenAiCompatibleLlm {
+    /** Any model: "kimi-*" in a YAML config routes here after registration. */
+    static supportedModels = [/^kimi-.+/];
+    apiKey;
+    baseUrl;
+    constructor({ model, apiKey, baseUrl }) {
+        super({ model });
+        this.apiKey = apiKey;
+        this.baseUrl = (baseUrl || process.env.MOONSHOT_BASE_URL || MOONSHOT_BASE_URL).replace(/\/+$/, '');
+    }
+    providerId() {
+        return 'moonshot';
+    }
+    endpointUrl() {
+        return `${this.baseUrl}/chat/completions`;
+    }
+    key() {
+        return this.apiKey ?? process.env.MOONSHOT_API_KEY;
+    }
+    headers() {
+        return { Authorization: `Bearer ${this.key() ?? ''}` };
+    }
+    missingRequirement() {
+        if (this.key())
+            return undefined;
+        return {
+            errorCode: 'MOONSHOT_MISSING_KEY',
+            errorMessage: 'MOONSHOT_API_KEY is not set in environment.',
+        };
+    }
+    httpError(status, detail) {
+        const hint = status === 401
+            ? ' Check MOONSHOT_API_KEY (platform.moonshot.ai).'
+            : status === 404
+                ? ` Is "${this.model}" a current Kimi id? kimi-k2.5 and moonshot-v1-* were retired on 2026-08-31.`
+                : '';
+        return {
+            errorCode: 'MOONSHOT_HTTP_ERROR',
+            errorMessage: `Moonshot returned ${status}: ${detail.slice(0, 4000)}.${hint}`,
+        };
+    }
+    /**
+     * 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).
+     */
+    extraBodyFields(llmRequest) {
+        const cfg = llmRequest.config ?? {};
+        const effort = cfg.reasoningEffort;
+        if (isKimiK3(this.model)) {
+            if (effort === undefined)
+                return { reasoning_effort: DEFAULT_KIMI_REASONING_EFFORT };
+            if (effort === 'none')
+                return { reasoning_effort: 'low' }; // K3 cannot switch thinking off
+            return {};
+        }
+        const budget = cfg.thinkingConfig?.thinkingBudget;
+        const off = effort === 'none' || budget === 0;
+        return {
+            reasoning_effort: undefined,
+            ...(off ? { thinking: { type: 'disabled' } } : {}),
+        };
+    }
+}
+// ── Registration helper ───────────────────────────────────────────────────────
+/** Registers KimiLlm with the ADK LLMRegistry (called when MOONSHOT_API_KEY is set). */
+export function registerKimiLlm() {
+    LLMRegistry.register(KimiLlm);
+}

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

@@ -10,9 +10,9 @@
  * Model-name conventions (see DOCUMENTATION.md §7):
  *   claude-*   → anthropic     gpt-* / o<digit>* → openai
  *   grok-*     → xai           ollama/<model>    → ollama (local, keyless)
- *   everything else            → gemini (the ADK-native default)
+ *   kimi-*     → moonshot      everything else   → gemini (the ADK-native default)
  */
-export type ProviderId = 'gemini' | 'anthropic' | 'openai' | 'xai' | 'ollama';
+export type ProviderId = 'gemini' | 'anthropic' | 'openai' | 'xai' | 'moonshot' | 'ollama';
 interface ProviderInfo {
     /** Env var holding the API key; null = keyless (local). */
     keyEnv: string | null;

package/dist/lib/models/providerMap.js

@@ -10,13 +10,14 @@
  * Model-name conventions (see DOCUMENTATION.md §7):
  *   claude-*   → anthropic     gpt-* / o<digit>* → openai
  *   grok-*     → xai           ollama/<model>    → ollama (local, keyless)
- *   everything else            → gemini (the ADK-native default)
+ *   kimi-*     → moonshot      everything else   → gemini (the ADK-native default)
  */
 export const PROVIDERS = {
     gemini: { keyEnv: 'GOOGLE_GENAI_API_KEY', label: 'Google Gemini' },
     anthropic: { keyEnv: 'ANTHROPIC_API_KEY', label: 'Anthropic Claude' },
     openai: { keyEnv: 'OPENAI_API_KEY', label: 'OpenAI GPT' },
     xai: { keyEnv: 'XAI_API_KEY', label: 'xAI Grok' },
+    moonshot: { keyEnv: 'MOONSHOT_API_KEY', label: 'Moonshot Kimi' },
     ollama: { keyEnv: null, label: 'Ollama (local)' },
 };
 /** Maps a model id to its provider. Unknown ids default to gemini — the
@@ -30,6 +31,8 @@ export function providerForModel(model) {
         return 'openai';
     if (/^grok-/.test(model))
         return 'xai';
+    if (/^kimi-/.test(model))
+        return 'moonshot';
     return 'gemini';
 }
 /** True when the provider's key is present (always true for local Ollama). */

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

@@ -11,7 +11,7 @@
  *      registry then string-matches supportedModels patterns:
  *        claude-*  → ClaudeLlm      gpt-* / o<digit>* → GptLlm
  *        grok-*    → GrokLlm        ollama/<model>    → OllamaLlm
- *        gemini-*  → TracedGemini (ADK's Gemini + llm.request spans)
+ *        kimi-*    → KimiLlm        gemini-*          → TracedGemini (ADK's Gemini + llm.request spans)
  *
  *   2. resolveModel() — instance factory for BYOK paths (scripts/
  *      a2a_server.ts), where a per-request API key from an HTTP header must

package/dist/lib/models/registry.js

@@ -11,7 +11,7 @@
  *      registry then string-matches supportedModels patterns:
  *        claude-*  → ClaudeLlm      gpt-* / o<digit>* → GptLlm
  *        grok-*    → GrokLlm        ollama/<model>    → OllamaLlm
- *        gemini-*  → TracedGemini (ADK's Gemini + llm.request spans)
+ *        kimi-*    → KimiLlm        gemini-*          → TracedGemini (ADK's Gemini + llm.request spans)
  *
  *   2. resolveModel() — instance factory for BYOK paths (scripts/
  *      a2a_server.ts), where a per-request API key from an HTTP header must
@@ -26,11 +26,12 @@ import { Gemini, LLMRegistry } from '@google/adk';
 import { endpointFromEnv, endpointProblems, mergeEndpoint, platformModel, providerReady } from './endpoints.js';
 import { currentTurnSignal } from '../runtime/turnControl.js';
 import { errorStatus, retryUntilFirstYield } from './retry.js';
-import { DEFAULT_CLAUDE_MODEL, DEFAULT_GEMINI_MODEL, DEFAULT_GPT_MODEL, DEFAULT_GROK_MODEL, DEFAULT_OLLAMA_MODEL, } from '../config.js';
+import { DEFAULT_CLAUDE_MODEL, DEFAULT_GEMINI_MODEL, DEFAULT_GPT_MODEL, DEFAULT_GROK_MODEL, DEFAULT_KIMI_MODEL, DEFAULT_OLLAMA_MODEL, } from '../config.js';
 import { traceLlmGeneration, setLlmSpanAttribute, } from '../observability/tracer.js';
 import { ClaudeLlm, registerClaudeLlm } from './claudeLlm.js';
 import { GptLlm, registerGptLlm } from './gptLlm.js';
 import { GrokLlm, registerGrokLlm } from './grokLlm.js';
+import { KimiLlm, registerKimiLlm } from './kimiLlm.js';
 import { OllamaLlm, registerOllamaLlm } from './ollamaLlm.js';
 import { GatewayLlm, registerGatewayLlm } from './gatewayLlm.js';
 import { gatewayConfig, gatewayProblem, gatewayUsable, planTransport, } from './gateway.js';
@@ -144,6 +145,7 @@ const REGISTRARS = {
     anthropic: registerClaudeLlm,
     openai: registerGptLlm,
     xai: registerGrokLlm,
+    moonshot: registerKimiLlm,
     ollama: registerOllamaLlm,
 };
 /**
@@ -159,6 +161,7 @@ const PATTERNS = {
     anthropic: ClaudeLlm.supportedModels,
     openai: GptLlm.supportedModels,
     xai: GrokLlm.supportedModels,
+    moonshot: KimiLlm.supportedModels,
 };
 let providersRegistered = false;
 /**
@@ -209,6 +212,8 @@ function modelHint(provider) {
             return 'gpt-*/o*';
         case 'xai':
             return 'grok-*';
+        case 'moonshot':
+            return 'kimi-*';
         case 'ollama':
             return 'ollama/*';
         case 'gemini':
@@ -220,6 +225,7 @@ const DEFAULT_MODEL_FOR = {
     anthropic: DEFAULT_CLAUDE_MODEL,
     openai: DEFAULT_GPT_MODEL,
     xai: DEFAULT_GROK_MODEL,
+    moonshot: DEFAULT_KIMI_MODEL,
     ollama: DEFAULT_OLLAMA_MODEL,
 };
 /**
@@ -257,13 +263,15 @@ export function resolveModel(model, options = {}) {
             return new GptLlm({ model: resolved, apiKey, endpoint });
         case 'xai':
             return new GrokLlm({ model: resolved, apiKey });
+        case 'moonshot':
+            return new KimiLlm({ model: resolved, apiKey, baseUrl: endpoint?.baseURL });
         case 'gemini':
             return new TracedGemini({ model: resolved, apiKey, endpoint });
     }
 }
 function normalizeProvider(provider) {
     const p = provider?.toLowerCase();
-    if (p === 'ollama' || p === 'anthropic' || p === 'openai' || p === 'xai') {
+    if (p === 'ollama' || p === 'anthropic' || p === 'openai' || p === 'xai' || p === 'moonshot') {
         return p;
     }
     return 'gemini';

package/dist/lib/net/redirects.d.ts

@@ -0,0 +1,14 @@
+export declare const MAX_REDIRECTS = 5;
+export interface RedirectPolicy {
+    /** Why the request may not follow a redirect to `url`, or null to follow it. */
+    hopProblem(url: URL, crossOrigin: boolean): Promise<string | null>;
+}
+type Fetch = typeof globalThis.fetch;
+/**
+ * `fetch(input, init)` with redirects followed manually under `policy`.
+ * Throws when a hop is refused or the chain is too long.
+ */
+export declare function fetchWithRedirectPolicy(input: string | URL | Request, init: RequestInit | undefined, policy: RedirectPolicy, fetchImpl: Fetch): Promise<Response>;
+/** Run `fn` with every globalThis.fetch it makes following redirects under `policy`. */
+export declare function withRedirectGuard<T>(policy: RedirectPolicy, fn: () => Promise<T>): Promise<T>;
+export {};

package/dist/lib/net/redirects.js

@@ -0,0 +1,94 @@
+/**
+ * lib/net/redirects.ts — follow HTTP redirects one hop at a time, each hop
+ * held to a policy, for code that calls `globalThis.fetch` itself.
+ *
+ * WHY: fetch follows redirects by default, so a guard that vets only the URL
+ * a request starts at is bypassed by any server that answers 302: an allowed
+ * public API with an open redirect can send a call to 169.254.169.254, and
+ * fetch forwards every header but Authorization and Cookie (an API key in a
+ * custom header crosses origins). web_extract follows redirects manually for
+ * this reason; ADK's RestApiTool (the OpenAPI tools) calls globalThis.fetch
+ * with no hook to pass a fetch of our own.
+ *
+ * HOW: `withRedirectGuard(policy, fn)` runs `fn` in an AsyncLocalStorage
+ * context. A wrapper installed on globalThis.fetch (once, and again if
+ * something replaced it) applies the guard only inside such a context and
+ * calls the original fetch untouched everywhere else, so no other request in
+ * the process changes behaviour and concurrent calls never see each other's
+ * policy. Inside the context every request uses `redirect: 'manual'`; each
+ * hop's URL goes to `policy.hopProblem` before it is fetched, a hop to
+ * another origin keeps only content-negotiation headers, and a chain longer
+ * than MAX_REDIRECTS is an error. 303, and 301/302 after a POST, continue as
+ * a GET without a body, as browsers do.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+export const MAX_REDIRECTS = 5;
+/** The headers a request keeps when a redirect moves it to another origin. */
+const CROSS_ORIGIN_HEADERS = new Set(['accept', 'accept-language', 'content-language', 'content-type', 'user-agent']);
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/**
+ * `fetch(input, init)` with redirects followed manually under `policy`.
+ * Throws when a hop is refused or the chain is too long.
+ */
+export async function fetchWithRedirectPolicy(input, init, policy, fetchImpl) {
+    let url = new URL(input instanceof Request ? input.url : String(input));
+    let method = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
+    let headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+    let body = init?.body;
+    for (let hop = 0;; hop++) {
+        const res = await fetchImpl(url, { ...init, method, headers, body, redirect: 'manual' });
+        const location = res.headers.get('location');
+        if (!REDIRECT_STATUSES.has(res.status) || !location)
+            return res;
+        await res.body?.cancel().catch(() => { });
+        if (hop >= MAX_REDIRECTS)
+            throw new Error(`more than ${MAX_REDIRECTS} redirects from ${url.host}`);
+        let next;
+        try {
+            next = new URL(location, url);
+        }
+        catch {
+            throw new Error(`redirect to an unparseable URL from ${url.host}`);
+        }
+        const crossOrigin = next.origin !== url.origin;
+        const problem = await policy.hopProblem(next, crossOrigin);
+        if (problem)
+            throw new Error(`redirect refused: ${problem}`);
+        if (res.status === 303 || ((res.status === 301 || res.status === 302) && method === 'POST')) {
+            if (method !== 'HEAD')
+                method = 'GET';
+            body = undefined;
+            headers.delete('content-type');
+            headers.delete('content-length');
+        }
+        if (crossOrigin) {
+            const kept = new Headers();
+            headers.forEach((value, name) => {
+                if (CROSS_ORIGIN_HEADERS.has(name.toLowerCase()))
+                    kept.set(name, value);
+            });
+            headers = kept;
+        }
+        url = next;
+    }
+}
+const guardContext = new AsyncLocalStorage();
+const WRAPPED = Symbol.for('melchizedek.redirectGuardedFetch');
+/** Wrap whatever globalThis.fetch is now, unless it is already our wrapper. */
+function ensureInstalled() {
+    const current = globalThis.fetch;
+    if (current[WRAPPED])
+        return;
+    const inner = current;
+    const wrapped = ((input, init) => {
+        const policy = guardContext.getStore();
+        return policy ? fetchWithRedirectPolicy(input, init, policy, inner) : inner(input, init);
+    });
+    wrapped[WRAPPED] = true;
+    globalThis.fetch = wrapped;
+}
+/** Run `fn` with every globalThis.fetch it makes following redirects under `policy`. */
+export function withRedirectGuard(policy, fn) {
+    ensureInstalled();
+    return guardContext.run(policy, fn);
+}