melchizedek-agents 0.16.2 → 0.18.0

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);
+}

package/dist/lib/observability/audit.d.ts

@@ -0,0 +1,21 @@
+import type { Pool } from 'pg';
+export type AuditEventName = 'auth.failure' | 'task.end' | 'memory.erase';
+export interface AuditEvent {
+    event: AuditEventName;
+    /** denied | ok | the task's final status. */
+    outcome: string;
+    /** The authenticated caller's name ('shared-secret', a caller token's name, 'jwt'). */
+    caller?: string;
+    /** SHA-256 prefix of the scope key, never the key. */
+    scopeHash?: string;
+    sourceIp?: string;
+    agentId?: string;
+    taskId?: string;
+    /** Small, content-free facts: a reason code, counts, a path. */
+    detail?: Record<string, unknown>;
+}
+export type AuditSink = (event: AuditEvent) => void;
+/** The scope's SHA-256 prefix, as the task log writes it. */
+export declare function scopeHashOf(scopeKey: string | undefined): string | undefined;
+/** Appends events to melchizedek_audit through the storage pool. */
+export declare function postgresAuditSink(pool: Pick<Pool, 'query'>, warn?: (m: string) => void): AuditSink;

package/dist/lib/observability/audit.js

@@ -0,0 +1,39 @@
+/**
+ * lib/observability/audit.ts — the audit trail: who did what, when, from
+ * where (ADR 0042).
+ *
+ * The ledger (adk_turns) records what a turn said. An auditor asks a
+ * different question: which caller, authenticated how, from which address,
+ * did what, and was it allowed. Those events are written to
+ * melchizedek_audit (db/migrations/0012), which a trigger keeps
+ * append-only. An event never carries conversation content or a scope
+ * key: a scope is a SHA-256 prefix, as in the task log.
+ *
+ * The sink is fire-and-forget: an audit write never delays or fails a
+ * request. A failed write is logged once per outage, and the event is
+ * written to stderr as one JSON line instead, so it is not lost silently.
+ */
+import { createHash } from 'node:crypto';
+/** The scope's SHA-256 prefix, as the task log writes it. */
+export function scopeHashOf(scopeKey) {
+    return scopeKey ? createHash('sha256').update(scopeKey).digest('hex').slice(0, 12) : undefined;
+}
+/** Appends events to melchizedek_audit through the storage pool. */
+export function postgresAuditSink(pool, warn = (m) => console.warn(m)) {
+    let failing = false;
+    return (e) => {
+        pool
+            .query('INSERT INTO melchizedek_audit (event, outcome, caller, scope_hash, source_ip, agent_id, task_id, detail) VALUES ($1, $2, $3, $4, $5, $6, $7, $8)', [e.event, e.outcome, e.caller ?? null, e.scopeHash ?? null, e.sourceIp ?? null, e.agentId ?? null, e.taskId ?? null, JSON.stringify(e.detail ?? {})])
+            .then(() => {
+            if (failing)
+                warn('[audit] writes to melchizedek_audit succeed again.');
+            failing = false;
+        })
+            .catch((err) => {
+            if (!failing)
+                warn(`[audit] could not write to melchizedek_audit (${err instanceof Error ? err.message : String(err)}); events go to stderr until it recovers.`);
+            failing = true;
+            console.error(JSON.stringify({ audit: { ...e, at: new Date().toISOString() } }));
+        });
+    };
+}

package/dist/lib/observability/metrics.d.ts

@@ -10,6 +10,12 @@
  */
 /** One finished (or refused) task, as the executor reports it. */
 export interface TaskRecord {
+    /** The A2A task id: joins this record to the task store and the audit trail. */
+    taskId?: string;
+    /** The turn's trace id: joins this record to its spans and its ledger row. */
+    traceId?: string;
+    /** The trace id of the caller's `traceparent`, when it sent one: the turn's root span links to it. */
+    callerTraceId?: string;
     /** The agent id the task was sent to; '' is the default syndicate. */
     agentId: string;
     syndicate: string;

package/dist/lib/observability/tracer.d.ts

@@ -1,3 +1,4 @@
+import type { SpanContext } from '@opentelemetry/api';
 import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
 import type { Event, LlmResponse } from '@google/adk';
 /**
@@ -67,6 +68,14 @@ export interface TraceMetadata {
         traceId: string;
         spanId: string;
     }) => void;
+    /**
+     * A caller's W3C `traceparent`. The turn's root span LINKS to the caller's
+     * span (and records `caller.trace_id`) instead of joining its trace: a turn's
+     * trace id keys its ledger attribution, its in-process stats and erasure,
+     * so it must stay unique to the turn and never be chosen by a caller.
+     * Ignored unless well formed (validTraceparent).
+     */
+    traceparent?: string;
     /**
      * Identity of the turn. These are what make a stored turn joinable to
      * its session row (`adk_sessions.id` = app:user:session) and to the ADK
@@ -103,9 +112,13 @@ export declare function serverToolEvents(ev: any): Array<{
     name: 'ToolCall' | 'ToolResponse';
     attributes: Record<string, string | boolean>;
 }>;
+/** A well-formed version-00 W3C traceparent, or undefined. Never throws. */
+export declare function validTraceparent(value: unknown): string | undefined;
+/** The caller's span a turn links to, from its `traceparent`; undefined when absent or malformed. */
+export declare function callerSpanContext(traceparent: string | undefined): SpanContext | undefined;
 export declare function traceAgentRun(stream: AsyncIterableIterator<Event>, metadata: TraceMetadata): AsyncGenerator<Event, void, void>;
 export interface LlmCallMeta {
-    /** Provider id, e.g. 'anthropic', 'openai', 'xai', 'ollama', 'gemini'. */
+    /** Provider id, e.g. 'anthropic', 'openai', 'xai', 'moonshot', 'ollama', 'gemini'. */
     provider: string;
     /** The model id as declared in the agent YAML (e.g. 'ollama/qwen3:8b'). */
     model: string;

package/dist/lib/observability/tracer.js

@@ -1,4 +1,4 @@
-import { trace, context } from '@opentelemetry/api';
+import { trace, context, defaultTextMapGetter, ROOT_CONTEXT } from '@opentelemetry/api';
 import { createRequire } from 'node:module';
 import { TELEMETRY_SCHEMA_VERSION, engineVersion } from './lineage.js';
 import { FilteringSpanExporter, otlpContentMode } from './otlpFilter.js';
@@ -345,9 +345,23 @@ export function serverToolEvents(ev) {
     }
     return out;
 }
+const TRACEPARENT = /^00-(?!0{32})[0-9a-f]{32}-(?!0{16})[0-9a-f]{16}-[0-9a-f]{2}$/;
+/** A well-formed version-00 W3C traceparent, or undefined. Never throws. */
+export function validTraceparent(value) {
+    return typeof value === 'string' && TRACEPARENT.test(value.trim().toLowerCase()) ? value.trim().toLowerCase() : undefined;
+}
+/** The caller's span a turn links to, from its `traceparent`; undefined when absent or malformed. */
+export function callerSpanContext(traceparent) {
+    const tp = validTraceparent(traceparent);
+    if (!tp)
+        return undefined;
+    const ctx = new core.W3CTraceContextPropagator().extract(ROOT_CONTEXT, { traceparent: tp }, defaultTextMapGetter);
+    return trace.getSpanContext(ctx);
+}
 export async function* traceAgentRun(stream, metadata) {
     initializeTracing();
-    const span = tracer.startSpan(`Syndicate Execution: ${metadata.syndicateName}`);
+    const caller = callerSpanContext(metadata.traceparent);
+    const span = tracer.startSpan(`Syndicate Execution: ${metadata.syndicateName}`, caller ? { links: [{ context: caller }], attributes: { 'caller.trace_id': caller.traceId } } : undefined);
     turnContexts.set(span.spanContext().traceId, {
         sessionId: metadata.sessionId,
         userId: metadata.userId,

package/dist/lib/persistence/supabaseProvider.d.ts

@@ -9,12 +9,8 @@
  */
 import type { BaseSessionService, BaseMemoryService } from '@google/adk';
 import type { Embedder, MemoryExtractor } from '../memory/providers.ts';
-export interface RlsHardeningStatus {
-    /** true only when db/hardening.sql has been applied and RLS is on for both tables. */
-    applied: boolean;
-    /** Human-readable explanation for logs. */
-    detail: string;
-}
+import type { RlsHardeningStatus } from '../storage/rlsStatus.ts';
+export type { RlsHardeningStatus } from '../storage/rlsStatus.ts';
 export interface PersistenceServices {
     sessionService: BaseSessionService;
     memoryService: BaseMemoryService | undefined;

package/dist/lib/persistence/supabaseProvider.js

@@ -8,6 +8,7 @@
  *     - Service construction (SupabaseSessionService, SupabaseVectorMemoryService)
  */
 import { isPlaceholderValue } from '../loadEnv.js';
+import { evaluateRlsRows } from '../storage/rlsStatus.js';
 /**
  * Returns true if all required Supabase credentials are present in the
  * environment. Does NOT throw — callers use this to decide whether to
@@ -59,37 +60,7 @@ export async function createSupabaseServices(options) {
                     detail: 'db/hardening.sql has not been applied (status function missing)',
                 };
             }
-            const rows = (data ?? []);
-            const unprotected = ['adk_memory_facts', 'adk_sessions'].filter((t) => !rows.some((r) => r.table_name === t && r.rls_enabled));
-            if (unprotected.length > 0) {
-                return {
-                    applied: false,
-                    detail: `RLS is disabled on: ${unprotected.join(', ')}`,
-                };
-            }
-            // adk_agent_registry is optional (only deployments that boot
-            // `registry:<id>` create it) but NOT advisory: an unprotected registry
-            // is agent takeover via the anon key, so a present-and-open table
-            // fails the check outright. Absent table => no row => nothing to say.
-            const registryRow = rows.find((r) => r.table_name === 'adk_agent_registry');
-            if (registryRow && !registryRow.rls_enabled) {
-                return {
-                    applied: false,
-                    detail: 'RLS is disabled on: adk_agent_registry (agent definitions are ' +
-                        'writable with the anon key) — re-run db/hardening.sql',
-                };
-            }
-            // Advisory only — adk_telemetry is optional (db/telemetry.sql). If it
-            // exists but hardening.sql wasn't re-run afterwards, say so without
-            // failing the check (the mandatory tables are protected).
-            const telemetryRow = rows.find((r) => r.table_name === 'adk_telemetry');
-            if (telemetryRow && !telemetryRow.rls_enabled) {
-                return {
-                    applied: true,
-                    detail: 'RLS enabled on adk_memory_facts and adk_sessions — but NOT on adk_telemetry; re-run db/hardening.sql',
-                };
-            }
-            return { applied: true, detail: 'RLS enabled on adk_memory_facts and adk_sessions' };
+            return evaluateRlsRows((data ?? []));
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);