melchizedek-agents 0.9.6 → 0.16.0

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

@@ -1,7 +1,7 @@
 /**
  * lib/observability/embeddings.ts — embeddings for ledger search.
  *
- * The same model and dimensionality as long-term memory (lib/config.ts), so
+ * The same embedder as long-term memory (lib/memory/providers.ts), so
  * a query embedded here is comparable to a turn embedded by
  * `npm run telemetry:embed`, and the `match_turns` RPC (db/telemetry.sql)
  * compares apples to apples. Kept out of the exporter on purpose: an API
@@ -9,12 +9,21 @@
  * batches after the fact.
  */
 import { EMBEDDING_DIMENSIONS, EMBEDDING_MODEL } from '../config.ts';
+import type { Embedder } from '../memory/providers.ts';
 export interface EmbedOptions {
+    /** The Gemini key, when the configured embedder is Gemini (the default). */
     apiKey?: string;
     /** Characters kept per text (long answers are truncated, not skipped). */
     maxChars?: number;
+    /** Test seam; default the deployment's memory embedder (lib/memory/providers.ts). */
+    embedder?: Embedder;
 }
-/** Embeds each text; a failed text yields an empty vector rather than a throw. */
+/**
+ * Embeds each text with the SAME embedder long-term memory uses, so the two
+ * vector columns stay comparable and a deployment that moved memory off
+ * Google does not keep sending ledger text there. A failed text yields an
+ * empty vector rather than a throw: this is a batch job over stored turns.
+ */
 export declare function embedTexts(texts: string[], options?: EmbedOptions): Promise<number[][]>;
 /** The text a turn is embedded by: the question and the answer, in that order. */
 export declare function turnEmbeddingText(input: string | null | undefined, output: string | null | undefined): string;

package/dist/lib/observability/embeddings.js

@@ -1,22 +1,31 @@
 /**
  * lib/observability/embeddings.ts — embeddings for ledger search.
  *
- * The same model and dimensionality as long-term memory (lib/config.ts), so
+ * The same embedder as long-term memory (lib/memory/providers.ts), so
  * a query embedded here is comparable to a turn embedded by
  * `npm run telemetry:embed`, and the `match_turns` RPC (db/telemetry.sql)
  * compares apples to apples. Kept out of the exporter on purpose: an API
  * call per turn would put inference on the export path; a job embeds in
  * batches after the fact.
  */
-import { GoogleGenAI } from '@google/genai';
-import { EMBEDDING_DIMENSIONS, EMBEDDING_MODEL } from "../config.js";
+import { EMBEDDING_DIMENSIONS, EMBEDDING_MODEL } from '../config.js';
+import { memoryProvidersFromEnv } from '../memory/providers.js';
 const MAX_CHARS = 8_000;
-/** Embeds each text; a failed text yields an empty vector rather than a throw. */
+/**
+ * Embeds each text with the SAME embedder long-term memory uses, so the two
+ * vector columns stay comparable and a deployment that moved memory off
+ * Google does not keep sending ledger text there. A failed text yields an
+ * empty vector rather than a throw: this is a batch job over stored turns.
+ */
 export async function embedTexts(texts, options = {}) {
-    const apiKey = options.apiKey ?? process.env.GOOGLE_GENAI_API_KEY ?? process.env.GEMINI_API_KEY;
-    if (!apiKey)
-        throw new Error('GOOGLE_GENAI_API_KEY is required for embeddings');
-    const genai = new GoogleGenAI({ apiKey });
+    let embedder = options.embedder;
+    if (!embedder) {
+        const apiKey = options.apiKey ?? process.env.GOOGLE_GENAI_API_KEY ?? process.env.GEMINI_API_KEY;
+        const provider = (process.env.MEMORY_EMBEDDING_PROVIDER?.trim() || 'gemini').toLowerCase();
+        if (provider === 'gemini' && !apiKey)
+            throw new Error('GOOGLE_GENAI_API_KEY is required for Gemini embeddings');
+        embedder = memoryProvidersFromEnv(process.env, apiKey).embedder;
+    }
     const limit = options.maxChars ?? MAX_CHARS;
     const out = [];
     for (const text of texts) {
@@ -26,12 +35,7 @@ export async function embedTexts(texts, options = {}) {
             continue;
         }
         try {
-            const response = await genai.models.embedContent({
-                model: EMBEDDING_MODEL,
-                contents: clipped,
-                config: { outputDimensionality: EMBEDDING_DIMENSIONS },
-            });
-            out.push(response.embeddings?.[0]?.values ?? []);
+            out.push((await embedder.embed([clipped]))[0] ?? []);
         }
         catch (err) {
             console.warn(`[embeddings] failed: ${err instanceof Error ? err.message : String(err)}`);

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

@@ -0,0 +1,36 @@
+/**
+ * lib/observability/metrics.ts — Prometheus metrics for the A2A server
+ * (ADR 0026), from one record per finished task. No dependency: the text
+ * exposition format is a few lines.
+ *
+ * Labels are the agent, the outcome and the caller name. A caller name is
+ * an operator-chosen identifier (a caller token's name, 'shared-secret',
+ * 'jwt' or 'jwt:<tenant>'), never a user id, so the label set stays small
+ * and holds no personal data. Scopes are never a label.
+ */
+/** One finished (or refused) task, as the executor reports it. */
+export interface TaskRecord {
+    /** The agent id the task was sent to; '' is the default syndicate. */
+    agentId: string;
+    syndicate: string;
+    caller?: string;
+    /** SHA-256 prefix of the scope key: joins log lines without naming a user. */
+    scopeHash: string;
+    /** input-required: the turn paused for an approval (ADR 0028); the answer is a new task. */
+    status: 'completed' | 'failed' | 'canceled' | 'rejected' | 'input-required';
+    /** Why a task was rejected or failed: 'policy', 'capacity', 'input', or the turn's error code. */
+    reason?: string;
+    durationMs: number;
+    usage: {
+        llmCalls: number;
+        inputTokens: number;
+        outputTokens: number;
+        thinkingTokens: number;
+    };
+}
+export interface Metrics {
+    observeTask(record: TaskRecord): void;
+    /** Prometheus text exposition. `inFlight` is read at scrape time. */
+    render(inFlight?: number): string;
+}
+export declare function createMetrics(): Metrics;

package/dist/lib/observability/metrics.js

@@ -0,0 +1,86 @@
+/**
+ * lib/observability/metrics.ts — Prometheus metrics for the A2A server
+ * (ADR 0026), from one record per finished task. No dependency: the text
+ * exposition format is a few lines.
+ *
+ * Labels are the agent, the outcome and the caller name. A caller name is
+ * an operator-chosen identifier (a caller token's name, 'shared-secret',
+ * 'jwt' or 'jwt:<tenant>'), never a user id, so the label set stays small
+ * and holds no personal data. Scopes are never a label.
+ */
+const BUCKETS = [1, 2.5, 5, 10, 20, 40, 60, 120, 300, 900];
+const key = (l) => JSON.stringify(Object.entries(l).sort(([a], [b]) => a.localeCompare(b)));
+const fmt = (l) => Object.keys(l).length
+    ? `{${Object.entries(l)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => `${k}="${v.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n')}"`)
+        .join(',')}}`
+    : '';
+export function createMetrics() {
+    const counters = new Map();
+    const hist = new Map();
+    const inc = (name, labels, by = 1) => {
+        if (!by)
+            return;
+        const series = counters.get(name) ?? new Map();
+        counters.set(name, series);
+        const k = key(labels);
+        const cur = series.get(k) ?? { labels, value: 0 };
+        cur.value += by;
+        series.set(k, cur);
+    };
+    const HELP = {
+        melchizedek_a2a_tasks_total: ['counter', 'Tasks finished or refused, by agent, outcome and caller.'],
+        melchizedek_a2a_llm_calls_total: ['counter', 'Model calls made by tasks.'],
+        melchizedek_a2a_tokens_total: ['counter', 'Tokens reported by the providers, by kind (input, output, thinking).'],
+        melchizedek_a2a_task_duration_seconds: ['histogram', 'Wall-clock duration of tasks that ran.'],
+        melchizedek_a2a_tasks_in_flight: ['gauge', 'Tasks running now.'],
+    };
+    return {
+        observeTask(r) {
+            const base = { agent: r.agentId || 'default', caller: r.caller ?? 'none' };
+            inc('melchizedek_a2a_tasks_total', { ...base, status: r.status, reason: r.reason ?? '' });
+            inc('melchizedek_a2a_llm_calls_total', base, r.usage.llmCalls);
+            inc('melchizedek_a2a_tokens_total', { ...base, kind: 'input' }, r.usage.inputTokens);
+            inc('melchizedek_a2a_tokens_total', { ...base, kind: 'output' }, r.usage.outputTokens);
+            inc('melchizedek_a2a_tokens_total', { ...base, kind: 'thinking' }, r.usage.thinkingTokens);
+            if (r.status === 'rejected')
+                return;
+            const labels = { agent: base.agent };
+            const k = key(labels);
+            const h = hist.get(k) ?? { labels, buckets: BUCKETS.map(() => 0), sum: 0, count: 0 };
+            const secs = r.durationMs / 1000;
+            BUCKETS.forEach((b, i) => {
+                if (secs <= b)
+                    h.buckets[i] += 1;
+            });
+            h.sum += secs;
+            h.count += 1;
+            hist.set(k, h);
+        },
+        render(inFlight) {
+            const out = [];
+            const head = (name) => {
+                const [type, help] = HELP[name];
+                out.push(`# HELP ${name} ${help}`, `# TYPE ${name} ${type}`);
+            };
+            for (const name of ['melchizedek_a2a_tasks_total', 'melchizedek_a2a_llm_calls_total', 'melchizedek_a2a_tokens_total']) {
+                head(name);
+                for (const { labels, value } of counters.get(name)?.values() ?? [])
+                    out.push(`${name}${fmt(labels)} ${value}`);
+            }
+            const hn = 'melchizedek_a2a_task_duration_seconds';
+            head(hn);
+            for (const h of hist.values()) {
+                BUCKETS.forEach((b, i) => out.push(`${hn}_bucket${fmt({ ...h.labels, le: String(b) })} ${h.buckets[i]}`));
+                out.push(`${hn}_bucket${fmt({ ...h.labels, le: '+Inf' })} ${h.count}`);
+                out.push(`${hn}_sum${fmt(h.labels)} ${h.sum}`, `${hn}_count${fmt(h.labels)} ${h.count}`);
+            }
+            if (inFlight !== undefined) {
+                head('melchizedek_a2a_tasks_in_flight');
+                out.push(`melchizedek_a2a_tasks_in_flight ${inFlight}`);
+            }
+            return `${out.join('\n')}\n`;
+        },
+    };
+}

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

@@ -0,0 +1,29 @@
+/**
+ * lib/observability/redact.ts — scrubs user text before it reaches the
+ * telemetry ledger (adk_turns, adk_telemetry, adk_payloads; ADR 0026).
+ *
+ * The ledger keeps what a conversation said so a turn can be debugged and
+ * judged; it should not keep the credentials or personal identifiers that
+ * people paste into a chat. One redactor runs on every row the exporter
+ * writes, over every text value except the identifier columns joins depend
+ * on (ids, timestamps, model and agent names).
+ *
+ *   TELEMETRY_REDACT=secret                   (default) key-shaped credentials
+ *   TELEMETRY_REDACT=secret,email,phone,card,ssn
+ *   TELEMETRY_REDACT=off
+ *   setTelemetryRedactor((text) => myDlp(text))   your own, in code
+ *
+ * Sessions and memory are NOT redacted: they must hold the conversation for
+ * the agent to work. Erasure (`DELETE /memory`) is the answer there.
+ */
+export type Redactor = (text: string) => string;
+/** Built-in patterns. Each match becomes `[redacted:<kind>]`. */
+export declare const REDACTION_PATTERNS: Record<string, RegExp>;
+/** A redactor applying the named built-in patterns, in a fixed order. */
+export declare function patternRedactor(kinds: string[]): Redactor;
+/** Plug in your own redactor (a DLP service, say); `null` turns redaction off. */
+export declare function setTelemetryRedactor(redactor: Redactor | null): void;
+/** The redactor in force: the one set in code, else TELEMETRY_REDACT (default `secret`). */
+export declare function telemetryRedactor(env?: NodeJS.ProcessEnv): Redactor | undefined;
+/** Every text value in a row, redacted, except identifier columns. */
+export declare function redactRow<T>(row: T, redactor: Redactor): T;

package/dist/lib/observability/redact.js

@@ -0,0 +1,102 @@
+/**
+ * lib/observability/redact.ts — scrubs user text before it reaches the
+ * telemetry ledger (adk_turns, adk_telemetry, adk_payloads; ADR 0026).
+ *
+ * The ledger keeps what a conversation said so a turn can be debugged and
+ * judged; it should not keep the credentials or personal identifiers that
+ * people paste into a chat. One redactor runs on every row the exporter
+ * writes, over every text value except the identifier columns joins depend
+ * on (ids, timestamps, model and agent names).
+ *
+ *   TELEMETRY_REDACT=secret                   (default) key-shaped credentials
+ *   TELEMETRY_REDACT=secret,email,phone,card,ssn
+ *   TELEMETRY_REDACT=off
+ *   setTelemetryRedactor((text) => myDlp(text))   your own, in code
+ *
+ * Sessions and memory are NOT redacted: they must hold the conversation for
+ * the agent to work. Erasure (`DELETE /memory`) is the answer there.
+ */
+/** Built-in patterns. Each match becomes `[redacted:<kind>]`. */
+export const REDACTION_PATTERNS = {
+    secret: new RegExp([
+        'sk-(?:ant-|proj-)?[A-Za-z0-9_-]{20,}', // Anthropic, OpenAI
+        'AIza[0-9A-Za-z_-]{35}', // Google
+        'xai-[A-Za-z0-9]{20,}', // xAI
+        'gh[pousr]_[A-Za-z0-9]{30,}', // GitHub
+        'xox[abprs]-[A-Za-z0-9-]{10,}', // Slack
+        'AKIA[0-9A-Z]{16}', // AWS access key id
+        'eyJ[A-Za-z0-9_-]{8,}\\.eyJ[A-Za-z0-9_-]{8,}\\.[A-Za-z0-9_-]{8,}', // a JWT
+        '(?<=Bearer\\s)[A-Za-z0-9._~+/-]{20,}=*', // a bearer token in pasted headers
+    ].join('|'), 'g'),
+    email: /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g,
+    // Card and SSN run before phone, which would otherwise take their digits.
+    card: /(?<!\d)(?:\d[ -]?){12,18}\d(?!\d)/g,
+    ssn: /(?<!\d)\d{3}-\d{2}-\d{4}(?!\d)/g,
+    // Never starts or ends inside a longer run of digit groups (an order number).
+    phone: /(?<![\w.+]|\d[\s.-])\+?\d{1,3}[\s.-]?\(?\d{2,4}\)?[\s.-]?\d{3,4}[\s.-]?\d{3,4}(?![\w.]|[\s.-]\d)/g,
+};
+/** Passes the Luhn check: what separates a card number from any long number. */
+function luhn(digits) {
+    let sum = 0;
+    let double = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let d = digits.charCodeAt(i) - 48;
+        if (double) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+        double = !double;
+    }
+    return sum % 10 === 0;
+}
+/** A redactor applying the named built-in patterns, in a fixed order. */
+export function patternRedactor(kinds) {
+    const unknown = kinds.filter((k) => !REDACTION_PATTERNS[k]);
+    if (unknown.length)
+        throw new Error(`TELEMETRY_REDACT: unknown kind(s) ${unknown.join(', ')} (use ${Object.keys(REDACTION_PATTERNS).join(', ')}, or off)`);
+    const order = Object.keys(REDACTION_PATTERNS).filter((k) => kinds.includes(k));
+    return (text) => {
+        let out = text;
+        for (const kind of order) {
+            const re = new RegExp(REDACTION_PATTERNS[kind].source, REDACTION_PATTERNS[kind].flags);
+            out = out.replace(re, (m) => (kind === 'card' && !luhn(m.replace(/\D/g, '')) ? m : `[redacted:${kind}]`));
+        }
+        return out;
+    };
+}
+let custom;
+/** Plug in your own redactor (a DLP service, say); `null` turns redaction off. */
+export function setTelemetryRedactor(redactor) {
+    custom = redactor;
+}
+/** The redactor in force: the one set in code, else TELEMETRY_REDACT (default `secret`). */
+export function telemetryRedactor(env = process.env) {
+    if (custom !== undefined)
+        return custom ?? undefined;
+    const raw = (env.TELEMETRY_REDACT ?? 'secret').trim().toLowerCase();
+    if (raw === 'off' || raw === 'none' || raw === 'false')
+        return undefined;
+    const kinds = raw === 'all' ? Object.keys(REDACTION_PATTERNS) : raw.split(',').map((s) => s.trim()).filter(Boolean);
+    return patternRedactor(kinds);
+}
+/** Columns that identify and join rows: never rewritten. */
+const IDENTIFIER_KEY = /(^|[_.])(id|ts|at|hash|version)$|[a-z](Id|ID)$|^(syndicate|agent|model|models|provider|route|stage|span_name|surface|surface_guild|surface_channel|surface_user|kind|reason|eval_[a-z]+|schema_version|error_code)$/;
+/** Every text value in a row, redacted, except identifier columns. */
+export function redactRow(row, redactor) {
+    const walk = (value, key) => {
+        if (typeof value === 'string')
+            return key && IDENTIFIER_KEY.test(key) ? value : redactor(value);
+        if (Array.isArray(value))
+            return value.map((v) => walk(v, key));
+        if (value && typeof value === 'object' && !(value instanceof Date)) {
+            const out = {};
+            for (const [k, v] of Object.entries(value))
+                out[k] = walk(v, k);
+            return out;
+        }
+        return value;
+    };
+    return walk(row, undefined);
+}

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

@@ -146,6 +146,8 @@ export declare function isRootSpan(span: ReadableSpan): boolean;
 export declare function isPayloadSpan(span: ReadableSpan): boolean;
 /** `syndicate.input` is JSON.stringify of either a string or A2A parts. */
 export declare function parseInputText(raw: unknown): string;
+/** Span attributes minus the payload capture (`llm.payload.*`). */
+export declare function withoutPayloadAttributes(attrs: Record<string, unknown>): Record<string, unknown>;
 /** Flatten an llm.request or root span into one adk_telemetry row. */
 export declare function toTelemetryRow(span: ReadableSpan): TelemetryRow;
 /** Project a root span into the adk_turns system-of-record row. */

package/dist/lib/observability/supabaseSpanExporter.js

@@ -38,8 +38,9 @@ import { appendFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import core from '@opentelemetry/core';
 const { ExportResultCode } = core;
-import { hasSupabaseCredentials } from "../persistence/supabaseProvider.js";
-import { TELEMETRY_SCHEMA_VERSION } from "./lineage.js";
+import { hasSupabaseCredentials } from '../persistence/supabaseProvider.js';
+import { TELEMETRY_SCHEMA_VERSION } from './lineage.js';
+import { redactRow, telemetryRedactor } from './redact.js';
 /**
  * TELEMETRY_PAYLOADS: off | errors | sample (default) | all
  * TELEMETRY_PAYLOAD_SAMPLE: 0..1, default 0.10
@@ -154,11 +155,22 @@ function spanJson(span) {
         spanId: span.spanContext().spanId,
         name: span.name,
         durationMs: durationMs(span),
-        attributes: attrsOf(span),
+        // The full request/response of a failed call (llm.payload.*) belongs only
+        // in adk_payloads, which honours TELEMETRY_PAYLOADS and expires; copying
+        // it into this indefinitely-kept row bypassed both.
+        attributes: withoutPayloadAttributes(attrsOf(span)),
         events: span.events.map((e) => ({ name: e.name, attributes: e.attributes ?? {} })),
         status: span.status,
     };
 }
+/** Span attributes minus the payload capture (`llm.payload.*`). */
+export function withoutPayloadAttributes(attrs) {
+    const out = {};
+    for (const [k, v] of Object.entries(attrs))
+        if (!k.startsWith('llm.payload.'))
+            out[k] = v;
+    return out;
+}
 /** Flatten an llm.request or root span into one adk_telemetry row. */
 export function toTelemetryRow(span) {
     const attrs = attrsOf(span);
@@ -358,12 +370,16 @@ export class SupabaseSpanExporter {
             }
         }
         this.pruneBuffers();
+        // Credentials and (by choice) personal identifiers never reach the
+        // ledger or its dead-letter file (lib/observability/redact.ts).
+        const redactor = telemetryRedactor();
+        const clean = (rows) => (redactor ? rows.map((r) => redactRow(r, redactor)) : rows);
         if (telemetryRows.length)
-            this.insert('adk_telemetry', telemetryRows);
+            this.insert('adk_telemetry', clean(telemetryRows));
         if (turnRows.length)
-            this.insert('adk_turns', turnRows);
+            this.insert('adk_turns', clean(turnRows));
         if (payloadRows.length)
-            this.insert('adk_payloads', payloadRows);
+            this.insert('adk_payloads', clean(payloadRows));
         resultCallback({ code: ExportResultCode.SUCCESS });
     }
     pruneBuffers() {

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

@@ -91,6 +91,16 @@ export interface TraceMetadata {
  * Wraps an ADK `Runner.runAsync` stream with a root OpenTelemetry span.
  * Accumulates token counts, records variables (bindings) and the raw input/output.
  */
+/**
+ * ToolCall/ToolResponse span events for the server-side tool calls a
+ * Responses adapter (gptLlm.ts) carried on a final event's customMetadata.
+ * Pure, so the projection is testable without an OTEL provider. Partial
+ * (streamed) events carry none and repeat nothing.
+ */
+export declare function serverToolEvents(ev: any): Array<{
+    name: 'ToolCall' | 'ToolResponse';
+    attributes: Record<string, string | boolean>;
+}>;
 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'. */

package/dist/lib/observability/tracer.js

@@ -1,13 +1,14 @@
 import { trace, context } from '@opentelemetry/api';
 import { createRequire } from 'node:module';
-import { TELEMETRY_SCHEMA_VERSION, engineVersion } from "./lineage.js";
+import { TELEMETRY_SCHEMA_VERSION, engineVersion } from './lineage.js';
+import { chargeLlmCall, chargeTokens } from '../runtime/turnControl.js';
 import sdkNode from '@opentelemetry/sdk-trace-node';
 const { NodeTracerProvider } = sdkNode;
 import sdkBase from '@opentelemetry/sdk-trace-base';
 const { SimpleSpanProcessor } = sdkBase;
 import core from '@opentelemetry/core';
 const { ExportResultCode } = core;
-import { SupabaseSpanExporter, telemetrySinkEnabled, } from "./supabaseSpanExporter.js";
+import { SupabaseSpanExporter, telemetrySinkEnabled, } from './supabaseSpanExporter.js';
 /**
  * Optional OTLP export for a live trace viewer (Phoenix, Langfuse, Grafana
  * Tempo, Jaeger — anything that speaks OTLP/HTTP). Set
@@ -102,7 +103,10 @@ class JsonConsoleExporter {
                 startTime: span.startTime,
                 endTime: span.endTime,
                 durationMs: span.duration[0] * 1000 + span.duration[1] / 1000000,
-                attributes: span.attributes,
+                // Never the payload capture: a failed call carries its whole prompt
+                // in llm.payload.request, and stdout is a log drain with its own
+                // retention, outside every prune and erasure path.
+                attributes: Object.fromEntries(Object.entries(span.attributes).filter(([k]) => !k.startsWith('llm.payload.'))),
                 events: span.events.map(e => ({
                     name: e.name,
                     time: e.time,
@@ -278,9 +282,24 @@ export function initializeTracing() {
     }
     const provider = new NodeTracerProvider({ spanProcessors, ...(resource ? { resource } : {}) });
     provider.register();
+    // `register()` points the proxy of the @opentelemetry/api copy the SDK
+    // resolves. An installed package can resolve a DIFFERENT copy for this
+    // module (npm nests one under melchizedek-agents when versions differ), and
+    // the module-level `tracer` below is a proxy on THAT copy: unpointed, every
+    // span it starts is a no-op and the ledger silently stays empty. Point our
+    // own proxy too; with one shared copy this repeats what register() did.
+    trace._proxyTracerProvider?.setDelegate?.(provider);
     adoptAdkTracerApi(provider);
     tracerProvider = provider;
     isOtelInitialized = true;
+    // Fail loudly, not silently: a tracer that does not record means no
+    // ledger rows, no metrics from spans and no OTLP export.
+    const probe = trace.getTracer('melchizedek-tracer').startSpan('melchizedek.tracer.probe');
+    const recording = probe.isRecording();
+    probe.end();
+    if (!recording && (telemetryExporter || otlp)) {
+        console.warn('[TELEMETRY] ⚠ spans are not recording: telemetry is configured but nothing will be exported (two @opentelemetry/api copies?).');
+    }
 }
 const tracer = trace.getTracer('melchizedek-tracer');
 /** Turn identity by trace id, so llm.request children can carry it too. */
@@ -289,6 +308,36 @@ const turnContexts = new Map();
  * Wraps an ADK `Runner.runAsync` stream with a root OpenTelemetry span.
  * Accumulates token counts, records variables (bindings) and the raw input/output.
  */
+/**
+ * ToolCall/ToolResponse span events for the server-side tool calls a
+ * Responses adapter (gptLlm.ts) carried on a final event's customMetadata.
+ * Pure, so the projection is testable without an OTEL provider. Partial
+ * (streamed) events carry none and repeat nothing.
+ */
+export function serverToolEvents(ev) {
+    const calls = ev?.partial ? undefined : ev?.customMetadata?.['responses.server_tool_calls'];
+    if (!Array.isArray(calls))
+        return [];
+    const out = [];
+    for (const c of calls) {
+        const name = String(c?.name ?? 'server_tool');
+        out.push({
+            name: 'ToolCall',
+            attributes: { 'tool.name': name, 'tool.args': JSON.stringify(c?.args ?? {}), 'tool.server_side': true },
+        });
+        if (Array.isArray(c?.sources) && c.sources.length > 0) {
+            out.push({
+                name: 'ToolResponse',
+                attributes: {
+                    'tool.name': name,
+                    'tool.data_gathered': JSON.stringify({ sources: c.sources }),
+                    'tool.server_side': true,
+                },
+            });
+        }
+    }
+    return out;
+}
 export async function* traceAgentRun(stream, metadata) {
     initializeTracing();
     const span = tracer.startSpan(`Syndicate Execution: ${metadata.syndicateName}`);
@@ -402,6 +451,13 @@ export async function* traceAgentRun(stream, metadata) {
                     }
                 }
             }
+            // Server-side tools (xAI web_search/x_search via the Responses
+            // adapters) run inside one model call and never surface as
+            // functionCall parts. gptLlm.ts carries them on the final response's
+            // customMetadata; recording them here is what makes adk_turns.tool_calls
+            // count a searched Grok answer instead of reporting zero.
+            for (const e of serverToolEvents(ev))
+                span.addEvent(e.name, e.attributes);
             yield event;
         }
     }
@@ -488,6 +544,15 @@ function refineErrorCode(code, message) {
  */
 export async function* traceLlmGeneration(meta, inner) {
     initializeTracing();
+    // Every model call on every provider passes here, so this is where the
+    // turn's step budget and cancellation are enforced (lib/runtime/
+    // turnControl.ts). A refused call never reaches the provider.
+    const charge = chargeLlmCall();
+    if (!charge.ok) {
+        await inner.return?.(undefined);
+        yield { errorCode: charge.code, errorMessage: charge.message };
+        return;
+    }
     const span = tracer.startSpan('llm.request');
     span.setAttribute('llm.provider', meta.provider);
     span.setAttribute('llm.model', meta.model);
@@ -555,6 +620,8 @@ export async function* traceLlmGeneration(meta, inner) {
         throw error;
     }
     finally {
+        // The turn's usage (budgets, metrics, the task log) counts every call.
+        chargeTokens(inputTokens, outputTokens, thinkingTokens);
         if (thinkingPreview) {
             span.addEvent('llm.thinking', { 'thinking.preview': thinkingPreview });
         }

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

@@ -8,6 +8,7 @@
  *     - Service construction (SupabaseSessionService, SupabaseVectorMemoryService)
  */
 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;
@@ -24,12 +25,22 @@ export interface PersistenceServices {
      * throws — callers use this to warn operators at boot, not to gate.
      */
     checkRlsHardening: () => Promise<RlsHardeningStatus>;
+    /** RPC access for operations that span stores (lib/memory/erase.ts). */
+    rpcClient: {
+        rpc: (fn: string, args?: Record<string, unknown>) => any;
+    };
+    /** The highest migration recorded in melchizedek_schema_version; null if none. */
+    schemaVersion: () => Promise<number | null>;
 }
 export interface SupabaseProviderOptions {
     /** The Gemini API key passed to SupabaseVectorMemoryService for embeddings. */
     apiKey: string;
     /** Whether to construct the SupabaseVectorMemoryService (long-term memory). */
     withMemory: boolean;
+    /** Fact extractor and embedder for memory (lib/memory/providers.ts).
+     *  Default: from the environment (MEMORY_* variables), Gemini when unset. */
+    extractor?: MemoryExtractor;
+    embedder?: Embedder;
 }
 /**
  * Returns true if all required Supabase credentials are present in the

package/dist/lib/persistence/supabaseProvider.js

@@ -7,14 +7,26 @@
  *     - App initialization
  *     - Service construction (SupabaseSessionService, SupabaseVectorMemoryService)
  */
+import { isPlaceholderValue } from '../loadEnv.js';
 /**
  * Returns true if all required Supabase credentials are present in the
  * environment. Does NOT throw — callers use this to decide whether to
  * fall back to in-memory services.
  */
 export function hasSupabaseCredentials() {
-    return !!(process.env.SUPABASE_URL &&
-        process.env.SUPABASE_SERVICE_ROLE_KEY);
+    const url = process.env.SUPABASE_URL?.trim();
+    const key = process.env.SUPABASE_SERVICE_ROLE_KEY?.trim();
+    if (!url || !key || isPlaceholderValue(url) || isPlaceholderValue(key))
+        return false;
+    // A value that is not an http(s) URL is a misconfiguration, not credentials:
+    // treating it as present crashed supabase-js before the first prompt.
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === 'https:' || parsed.protocol === 'http:';
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * Initializes the Supabase client and constructs the
@@ -26,13 +38,13 @@ export async function createSupabaseServices(options) {
     const supabaseKey = process.env.SUPABASE_SERVICE_ROLE_KEY;
     const supabase = createClient(supabaseUrl, supabaseKey);
     // ── Session service ────────────────────────────────────────────────────────
-    const { SupabaseSessionService } = await import("../session/supabaseSessionService.js");
+    const { SupabaseSessionService } = await import('../session/supabaseSessionService.js');
     const sessionService = new SupabaseSessionService(supabase);
     // ── Memory service (optional) ──────────────────────────────────────────────
     let memoryService;
     if (options.withMemory) {
-        const { SupabaseVectorMemoryService } = await import("../memory/supabaseMemoryService.js");
-        memoryService = new SupabaseVectorMemoryService({ apiKey: options.apiKey }, supabase);
+        const { SupabaseVectorMemoryService } = await import('../memory/supabaseMemoryService.js');
+        memoryService = new SupabaseVectorMemoryService({ apiKey: options.apiKey, extractor: options.extractor, embedder: options.embedder }, supabase);
     }
     // ── Hardening probe ─────────────────────────────────────────────────────────
     // Calls the melchizedek_rls_status() function created by db/hardening.sql.
@@ -84,5 +96,19 @@ export async function createSupabaseServices(options) {
             return { applied: false, detail: `hardening check failed: ${msg}` };
         }
     };
-    return { sessionService, memoryService, checkRlsHardening };
+    const schemaVersion = async () => {
+        const { data, error } = await supabase
+            .from('melchizedek_schema_version')
+            .select('version')
+            .order('version', { ascending: false })
+            .limit(1);
+        if (error) {
+            // No version table: the migrations were never applied.
+            if (/does not exist|PGRST205|42P01/i.test(`${error.message} ${error.code ?? ''}`))
+                return null;
+            throw new Error(`Reading melchizedek_schema_version: ${error.message}`);
+        }
+        return data?.[0]?.version == null ? null : Number(data[0].version);
+    };
+    return { sessionService, memoryService, checkRlsHardening, rpcClient: supabase, schemaVersion };
 }