melchizedek-agents 0.9.0

package/dist/lib/models/schemaNormalize.js

@@ -0,0 +1,58 @@
+/**
+ * lib/models/schemaNormalize.ts — JSON-Schema dialect bridge.
+ *
+ * WHY this file exists:
+ *   The ADK is Gemini-native, and Gemini's Schema type spells JSON-Schema
+ *   types in UPPERCASE ('OBJECT', 'STRING', …). Every other provider this
+ *   framework routes to (Anthropic, OpenAI, xAI, Ollama's OpenAI-compatible
+ *   endpoint) requires standard lowercase JSON-Schema types and rejects the
+ *   Gemini spelling — Anthropic, for example, with:
+ *     400 invalid_request_error: tools.N.custom.input_schema.type:
+ *         Input should be 'object'
+ *   Tools are declared once (YAML / MCP discovery) in the Gemini dialect, so
+ *   every non-Gemini adapter runs its tool schemas through this function at
+ *   request-build time. See DOCUMENTATION.md §7.1.
+ */
+/**
+ * Deep-clones a Gemini/ADK-style JSON schema, lowercasing every `type` value
+ * ('OBJECT' → 'object', ['STRING','NULL'] → ['string','null']) while leaving
+ * `description`, `enum`, `required`, `format`, and unknown keywords untouched.
+ * Never mutates the input — a Gemini agent may hold the same tool object.
+ */
+export function toLowercaseJsonSchema(schema) {
+    const result = normalizeNode(schema);
+    if (result && typeof result === 'object' && !Array.isArray(result)) {
+        return result;
+    }
+    return { type: 'object', properties: {} };
+}
+function normalizeNode(node) {
+    if (Array.isArray(node))
+        return node.map(normalizeNode);
+    if (!node || typeof node !== 'object')
+        return node;
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (key === 'type') {
+            // `type` may be a string or an array of strings (nullable unions).
+            if (typeof value === 'string') {
+                out[key] = value.toLowerCase();
+            }
+            else if (Array.isArray(value)) {
+                out[key] = value.map((v) => (typeof v === 'string' ? v.toLowerCase() : v));
+            }
+            else {
+                out[key] = value;
+            }
+        }
+        else if (key === 'enum' || key === 'required') {
+            // Value lists, not schema nodes — copy verbatim (enum values are data
+            // and must keep their original casing).
+            out[key] = Array.isArray(value) ? [...value] : value;
+        }
+        else {
+            out[key] = normalizeNode(value);
+        }
+    }
+    return out;
+}

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

@@ -0,0 +1,35 @@
+/**
+ * lib/observability/supabaseSpanExporter.ts — optional OpenTelemetry sink
+ * that persists model-request telemetry to Supabase.
+ *
+ * WHY this file exists:
+ *   The console exporter in tracer.ts prints every span as an
+ *   [OTEL_SPAN_JSON] line — good for a terminal, gone when it scrolls.
+ *   Operators who want durable usage data (tokens per model, per provider,
+ *   over time) can opt in with TELEMETRY_SUPABASE=true, and every
+ *   `llm.request` and `Syndicate Execution:*` span is also inserted into
+ *   the adk_telemetry table (schema: db/telemetry.sql, RLS: db/hardening.sql).
+ *
+ * DESIGN NOTES:
+ *   - Fire-and-forget: an insert failure is logged once and never thrown
+ *     into the tracing pipeline — telemetry must not break inference.
+ *   - Only spans that carry usage are exported (name filter below); ADK's
+ *     internal spans stay console-only to keep row volume sane.
+ */
+import type { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+/** True when the operator has opted into the Supabase telemetry sink. */
+export declare function telemetrySinkEnabled(): boolean;
+export declare class SupabaseSpanExporter implements SpanExporter {
+    /** Lazily created on first export so constructing the exporter is free
+     *  and synchronous (NodeTracerProvider wants processors at construction). */
+    private clientPromise;
+    private insertFailureLogged;
+    private pendingInserts;
+    private getClient;
+    export(spans: ReadableSpan[], resultCallback: (result: any) => void): void;
+    /** Waits for in-flight inserts so short-lived scripts don't drop rows. */
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+    /** Flatten a span into one adk_telemetry row. */
+    private toRow;
+}

package/dist/lib/observability/supabaseSpanExporter.js

@@ -0,0 +1,115 @@
+/**
+ * lib/observability/supabaseSpanExporter.ts — optional OpenTelemetry sink
+ * that persists model-request telemetry to Supabase.
+ *
+ * WHY this file exists:
+ *   The console exporter in tracer.ts prints every span as an
+ *   [OTEL_SPAN_JSON] line — good for a terminal, gone when it scrolls.
+ *   Operators who want durable usage data (tokens per model, per provider,
+ *   over time) can opt in with TELEMETRY_SUPABASE=true, and every
+ *   `llm.request` and `Syndicate Execution:*` span is also inserted into
+ *   the adk_telemetry table (schema: db/telemetry.sql, RLS: db/hardening.sql).
+ *
+ * DESIGN NOTES:
+ *   - Fire-and-forget: an insert failure is logged once and never thrown
+ *     into the tracing pipeline — telemetry must not break inference.
+ *   - Only spans that carry usage are exported (name filter below); ADK's
+ *     internal spans stay console-only to keep row volume sane.
+ */
+import core from '@opentelemetry/core';
+const { ExportResultCode } = core;
+import { hasSupabaseCredentials } from "../persistence/supabaseProvider.js";
+/** True when the operator has opted into the Supabase telemetry sink. */
+export function telemetrySinkEnabled() {
+    return process.env.TELEMETRY_SUPABASE === 'true' && hasSupabaseCredentials();
+}
+const EXPORTED_SPAN_NAMES = /^(llm\.request$|Syndicate Execution: )/;
+export class SupabaseSpanExporter {
+    /** Lazily created on first export so constructing the exporter is free
+     *  and synchronous (NodeTracerProvider wants processors at construction). */
+    clientPromise;
+    insertFailureLogged = false;
+    pendingInserts = new Set();
+    getClient() {
+        if (!this.clientPromise) {
+            this.clientPromise = import('@supabase/supabase-js').then(({ createClient }) => createClient(process.env.SUPABASE_URL, process.env.SUPABASE_SERVICE_ROLE_KEY));
+        }
+        return this.clientPromise;
+    }
+    export(spans, resultCallback) {
+        const rows = spans
+            .filter((span) => EXPORTED_SPAN_NAMES.test(span.name))
+            .map((span) => this.toRow(span));
+        if (rows.length === 0) {
+            resultCallback({ code: ExportResultCode.SUCCESS });
+            return;
+        }
+        // Fire-and-forget: report success to the pipeline immediately; log the
+        // first insert failure so a misconfigured table is visible without
+        // spamming every span batch.
+        const insert = this.getClient()
+            .then((client) => client.from('adk_telemetry').insert(rows))
+            .then(({ error }) => {
+            if (error && !this.insertFailureLogged) {
+                this.insertFailureLogged = true;
+                console.warn(`[TELEMETRY] Supabase insert failed (${error.message}). ` +
+                    'Has db/telemetry.sql been applied? Telemetry rows are being dropped; ' +
+                    'console [OTEL_SPAN_JSON] output is unaffected.');
+            }
+        })
+            .catch((err) => {
+            if (!this.insertFailureLogged) {
+                this.insertFailureLogged = true;
+                console.warn(`[TELEMETRY] Supabase sink error: ${err instanceof Error ? err.message : err}`);
+            }
+        })
+            .finally(() => this.pendingInserts.delete(insert));
+        this.pendingInserts.add(insert);
+        resultCallback({ code: ExportResultCode.SUCCESS });
+    }
+    /** Waits for in-flight inserts so short-lived scripts don't drop rows. */
+    async shutdown() {
+        await Promise.allSettled([...this.pendingInserts]);
+    }
+    async forceFlush() {
+        await Promise.allSettled([...this.pendingInserts]);
+    }
+    /** Flatten a span into one adk_telemetry row. */
+    toRow(span) {
+        const attrs = span.attributes;
+        const num = (key) => typeof attrs[key] === 'number' ? attrs[key] : null;
+        const str = (key) => typeof attrs[key] === 'string' ? attrs[key] : null;
+        // Root spans are named "Syndicate Execution: <name>"; llm.request spans
+        // carry syndicate context only if the caller set syndicate.name.
+        const syndicate = str('syndicate.name') ??
+            (span.name.startsWith('Syndicate Execution: ')
+                ? span.name.slice('Syndicate Execution: '.length)
+                : null);
+        return {
+            ts: new Date(span.startTime[0] * 1000 + span.startTime[1] / 1e6).toISOString(),
+            trace_id: span.spanContext().traceId,
+            span_id: span.spanContext().spanId,
+            span_name: span.name,
+            syndicate,
+            agent: str('llm.agent'),
+            provider: str('llm.provider'),
+            model: str('llm.model'),
+            input_tokens: num('llm.tokens.input') ?? num('syndicate.tokens.input'),
+            output_tokens: num('llm.tokens.output') ?? num('syndicate.tokens.output'),
+            thinking_tokens: num('llm.tokens.thinking') ?? num('syndicate.tokens.thinking'),
+            latency_ms: span.duration[0] * 1000 + span.duration[1] / 1e6,
+            span: {
+                traceId: span.spanContext().traceId,
+                spanId: span.spanContext().spanId,
+                name: span.name,
+                durationMs: span.duration[0] * 1000 + span.duration[1] / 1e6,
+                attributes: attrs,
+                events: span.events.map((e) => ({
+                    name: e.name,
+                    attributes: e.attributes ?? {},
+                })),
+                status: span.status,
+            },
+        };
+    }
+}

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

@@ -0,0 +1,44 @@
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import type { Event, LlmResponse } from '@google/adk';
+/**
+ * Flushes buffered span processors (console is synchronous; the Supabase
+ * batch sink is not). Call before process exit in short-lived scripts so
+ * telemetry rows aren't dropped.
+ */
+export declare function flushTracing(): Promise<void>;
+/** Subscribe to finished spans. Returns an unsubscribe function. */
+export declare function onSpanEnd(listener: (span: ReadableSpan) => void): () => void;
+export declare function initializeTracing(): void;
+export interface TraceMetadata {
+    syndicateName: string;
+    bindings?: Record<string, any>;
+    input?: any;
+}
+/**
+ * Wraps an ADK `Runner.runAsync` stream with a root OpenTelemetry span.
+ * Accumulates token counts, records variables (bindings) and the raw input/output.
+ */
+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: string;
+    /** The model id as declared in the agent YAML (e.g. 'ollama/qwen3:8b'). */
+    model: string;
+}
+/**
+ * Wraps one adapter `generateContentAsync` invocation in an `llm.request`
+ * span — one span per model call, for EVERY provider. Records provider,
+ * model, input/output/thinking token counts, latency, and a truncated
+ * thinking summary as a span event. Adapters call this around their own
+ * generator; TracedGemini (lib/models/registry.ts) does the same for Gemini,
+ * so per-request telemetry is uniform across the fleet.
+ *
+ * Adapters can decorate the active llm.request span with extra attributes
+ * (e.g. llm.web_search.native) via setLlmSpanAttribute below.
+ */
+export declare function traceLlmGeneration(meta: LlmCallMeta, inner: AsyncGenerator<LlmResponse, void>): AsyncGenerator<LlmResponse, void>;
+/**
+ * Sets an attribute on the currently active llm.request span, if any.
+ * Used by adapters for per-request flags like llm.web_search.omitted.
+ */
+export declare function setLlmSpanAttribute(key: string, value: string | number | boolean): void;

package/dist/lib/observability/tracer.js

@@ -0,0 +1,242 @@
+import { trace, context } from '@opentelemetry/api';
+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";
+let isOtelInitialized = false;
+let tracerProvider;
+let telemetryExporter;
+/**
+ * Flushes buffered span processors (console is synchronous; the Supabase
+ * batch sink is not). Call before process exit in short-lived scripts so
+ * telemetry rows aren't dropped.
+ */
+export async function flushTracing() {
+    await tracerProvider?.forceFlush?.();
+    await telemetryExporter?.forceFlush?.();
+}
+// ── In-process span listeners ────────────────────────────────────────────────
+// Lets a script (e.g. scripts/demo_model_optionality.ts) read finished spans
+// without scraping its own stdout for [OTEL_SPAN_JSON] lines.
+const spanEndListeners = new Set();
+/** Subscribe to finished spans. Returns an unsubscribe function. */
+export function onSpanEnd(listener) {
+    spanEndListeners.add(listener);
+    return () => spanEndListeners.delete(listener);
+}
+class JsonConsoleExporter {
+    export(spans, resultCallback) {
+        for (const span of spans) {
+            for (const listener of spanEndListeners) {
+                try {
+                    listener(span);
+                }
+                catch {
+                    /* a listener bug must not break the export pipeline */
+                }
+            }
+            // Create a clean JSON representation of the span
+            const jsonSpan = {
+                traceId: span.spanContext().traceId,
+                spanId: span.spanContext().spanId,
+                name: span.name,
+                startTime: span.startTime,
+                endTime: span.endTime,
+                durationMs: span.duration[0] * 1000 + span.duration[1] / 1000000,
+                attributes: span.attributes,
+                events: span.events.map(e => ({
+                    name: e.name,
+                    time: e.time,
+                    attributes: e.attributes || {}
+                })),
+                status: span.status,
+            };
+            // Print to stdout with a specific prefix so test_local.py can easily extract it
+            console.log(`[OTEL_SPAN_JSON] ${JSON.stringify(jsonSpan)}`);
+        }
+        resultCallback({ code: ExportResultCode.SUCCESS });
+    }
+    shutdown() {
+        return Promise.resolve();
+    }
+}
+export function initializeTracing() {
+    if (isOtelInitialized)
+        return;
+    // Set up the global OpenTelemetry provider
+    // Since we register this globally, any internal ADK spans (e.g. tool calls, model calls)
+    // will also automatically route to this provider and show up in the console.
+    const spanProcessors = [
+        new SimpleSpanProcessor(new JsonConsoleExporter()),
+    ];
+    // Optional durable sink (TELEMETRY_SUPABASE=true + Supabase credentials):
+    // llm.request and Syndicate Execution spans also land in adk_telemetry.
+    // Batched so inserts never sit on the inference hot path; the exporter
+    // creates its Supabase client lazily on first export.
+    if (telemetrySinkEnabled()) {
+        const { BatchSpanProcessor } = sdkBase;
+        telemetryExporter = new SupabaseSpanExporter();
+        spanProcessors.push(new BatchSpanProcessor(telemetryExporter));
+        console.log('[TELEMETRY] Supabase sink enabled → adk_telemetry');
+    }
+    const provider = new NodeTracerProvider({ spanProcessors });
+    provider.register();
+    tracerProvider = provider;
+    isOtelInitialized = true;
+}
+const tracer = trace.getTracer('melchizedek-tracer');
+/**
+ * Wraps an ADK `Runner.runAsync` stream with a root OpenTelemetry span.
+ * Accumulates token counts, records variables (bindings) and the raw input/output.
+ */
+export async function* traceAgentRun(stream, metadata) {
+    initializeTracing();
+    const span = tracer.startSpan(`Syndicate Execution: ${metadata.syndicateName}`);
+    if (metadata.bindings) {
+        span.setAttribute('syndicate.bindings', JSON.stringify(metadata.bindings));
+    }
+    if (metadata.input) {
+        span.setAttribute('syndicate.input', JSON.stringify(metadata.input));
+    }
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    let totalThinkingTokens = 0;
+    let outputText = '';
+    const ctx = trace.setSpan(context.active(), span);
+    try {
+        const wrappedStream = {
+            [Symbol.asyncIterator]() {
+                return {
+                    async next() { return context.with(ctx, () => stream.next()); },
+                    async return(value) { return stream.return ? context.with(ctx, () => stream.return(value)) : { done: true, value }; },
+                    async throw(e) { return stream.throw ? context.with(ctx, () => stream.throw(e)) : Promise.reject(e); }
+                };
+            }
+        };
+        for await (const event of wrappedStream) {
+            if (event.usageMetadata) {
+                // Aggregation caveat: a multi-turn run repeats the growing prompt on
+                // every model call, so Math.max under-reports true billed input. The
+                // per-call llm.request spans (traceLlmGeneration) carry the honest
+                // per-request numbers; this root-span figure is the peak context size.
+                if (event.usageMetadata.promptTokenCount) {
+                    totalInputTokens = Math.max(totalInputTokens, event.usageMetadata.promptTokenCount);
+                }
+                if (event.usageMetadata.candidatesTokenCount) {
+                    totalOutputTokens += event.usageMetadata.candidatesTokenCount;
+                }
+                if (event.usageMetadata.thoughtsTokenCount) {
+                    totalThinkingTokens += event.usageMetadata.thoughtsTokenCount;
+                }
+            }
+            if (event.content && event.content.parts) {
+                for (const part of event.content.parts) {
+                    const p = part;
+                    if (p.text && !p.thought) {
+                        outputText += p.text;
+                    }
+                    if (p.functionCall) {
+                        span.addEvent('ToolCall', {
+                            'tool.name': p.functionCall.name,
+                            'tool.args': JSON.stringify(p.functionCall.args || {})
+                        });
+                    }
+                    if (p.functionResponse) {
+                        let respData = p.functionResponse.response;
+                        if (typeof respData !== 'string') {
+                            respData = JSON.stringify(respData);
+                        }
+                        span.addEvent('ToolResponse', {
+                            'tool.name': p.functionResponse.name,
+                            'tool.data_gathered': respData
+                        });
+                    }
+                }
+            }
+            yield event;
+        }
+    }
+    catch (error) {
+        span.recordException(error);
+        throw error;
+    }
+    finally {
+        span.setAttribute('syndicate.name', metadata.syndicateName);
+        span.setAttribute('syndicate.tokens.input', totalInputTokens);
+        span.setAttribute('syndicate.tokens.output', totalOutputTokens);
+        span.setAttribute('syndicate.tokens.thinking', totalThinkingTokens);
+        span.setAttribute('syndicate.output', outputText);
+        span.end();
+    }
+}
+const THINKING_EVENT_MAX_CHARS = 600;
+/**
+ * Wraps one adapter `generateContentAsync` invocation in an `llm.request`
+ * span — one span per model call, for EVERY provider. Records provider,
+ * model, input/output/thinking token counts, latency, and a truncated
+ * thinking summary as a span event. Adapters call this around their own
+ * generator; TracedGemini (lib/models/registry.ts) does the same for Gemini,
+ * so per-request telemetry is uniform across the fleet.
+ *
+ * Adapters can decorate the active llm.request span with extra attributes
+ * (e.g. llm.web_search.native) via setLlmSpanAttribute below.
+ */
+export async function* traceLlmGeneration(meta, inner) {
+    initializeTracing();
+    const span = tracer.startSpan('llm.request');
+    span.setAttribute('llm.provider', meta.provider);
+    span.setAttribute('llm.model', meta.model);
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let thinkingTokens = 0;
+    let thinkingPreview = '';
+    const ctx = trace.setSpan(context.active(), span);
+    try {
+        while (true) {
+            const { value: resp, done } = await context.with(ctx, () => inner.next());
+            if (done)
+                break;
+            if (resp.usageMetadata) {
+                // One llm.request span covers one API call; the last usage report
+                // for that call is authoritative (streaming may repeat partials).
+                inputTokens = resp.usageMetadata.promptTokenCount ?? inputTokens;
+                outputTokens = resp.usageMetadata.candidatesTokenCount ?? outputTokens;
+                thinkingTokens = resp.usageMetadata.thoughtsTokenCount ?? thinkingTokens;
+            }
+            if (resp.errorCode) {
+                span.setAttribute('llm.error_code', resp.errorCode);
+            }
+            for (const part of resp.content?.parts ?? []) {
+                const p = part;
+                if (p.thought && p.text && thinkingPreview.length < THINKING_EVENT_MAX_CHARS) {
+                    thinkingPreview = (thinkingPreview + p.text).slice(0, THINKING_EVENT_MAX_CHARS);
+                }
+            }
+            yield resp;
+        }
+    }
+    catch (error) {
+        span.recordException(error);
+        throw error;
+    }
+    finally {
+        if (thinkingPreview) {
+            span.addEvent('llm.thinking', { 'thinking.preview': thinkingPreview });
+        }
+        span.setAttribute('llm.tokens.input', inputTokens);
+        span.setAttribute('llm.tokens.output', outputTokens);
+        span.setAttribute('llm.tokens.thinking', thinkingTokens);
+        // llm.latency_ms mirrors the span duration for the flat adk_telemetry row.
+        span.end();
+    }
+}
+/**
+ * Sets an attribute on the currently active llm.request span, if any.
+ * Used by adapters for per-request flags like llm.web_search.omitted.
+ */
+export function setLlmSpanAttribute(key, value) {
+    trace.getActiveSpan()?.setAttribute(key, value);
+}

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

@@ -0,0 +1,44 @@
+/**
+ * lib/persistence/supabaseProvider.ts — Supabase initialization factory.
+ *
+ * WHY this file exists:
+ *   This module encapsulates ALL Supabase-specific concerns:
+ *     - Credential detection (reads env vars)
+ *     - App initialization
+ *     - Service construction (SupabaseSessionService, SupabaseVectorMemoryService)
+ */
+import type { BaseSessionService, BaseMemoryService } from '@google/adk';
+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;
+}
+export interface PersistenceServices {
+    sessionService: BaseSessionService;
+    memoryService: BaseMemoryService | undefined;
+    /**
+     * Checks whether the database hardening in db/hardening.sql has been
+     * applied (RLS enabled on adk_memory_facts, adk_sessions and — where it
+     * exists — adk_agent_registry). Never
+     * throws — callers use this to warn operators at boot, not to gate.
+     */
+    checkRlsHardening: () => Promise<RlsHardeningStatus>;
+}
+export interface SupabaseProviderOptions {
+    /** The Gemini API key passed to SupabaseVectorMemoryService for embeddings. */
+    apiKey: string;
+    /** Whether to construct the SupabaseVectorMemoryService (long-term memory). */
+    withMemory: boolean;
+}
+/**
+ * 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 declare function hasSupabaseCredentials(): boolean;
+/**
+ * Initializes the Supabase client and constructs the
+ * SupabaseSessionService and optionally the SupabaseVectorMemoryService.
+ */
+export declare function createSupabaseServices(options: SupabaseProviderOptions): Promise<PersistenceServices>;

package/dist/lib/persistence/supabaseProvider.js

@@ -0,0 +1,88 @@
+/**
+ * lib/persistence/supabaseProvider.ts — Supabase initialization factory.
+ *
+ * WHY this file exists:
+ *   This module encapsulates ALL Supabase-specific concerns:
+ *     - Credential detection (reads env vars)
+ *     - App initialization
+ *     - Service construction (SupabaseSessionService, SupabaseVectorMemoryService)
+ */
+/**
+ * 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);
+}
+/**
+ * Initializes the Supabase client and constructs the
+ * SupabaseSessionService and optionally the SupabaseVectorMemoryService.
+ */
+export async function createSupabaseServices(options) {
+    const { createClient } = await import('@supabase/supabase-js');
+    const supabaseUrl = process.env.SUPABASE_URL;
+    const supabaseKey = process.env.SUPABASE_SERVICE_ROLE_KEY;
+    const supabase = createClient(supabaseUrl, supabaseKey);
+    // ── Session service ────────────────────────────────────────────────────────
+    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);
+    }
+    // ── Hardening probe ─────────────────────────────────────────────────────────
+    // Calls the melchizedek_rls_status() function created by db/hardening.sql.
+    // If the function is missing, hardening was never run — that is itself the
+    // answer, not an error.
+    const checkRlsHardening = async () => {
+        try {
+            const { data, error } = await supabase.rpc('melchizedek_rls_status');
+            if (error) {
+                return {
+                    applied: false,
+                    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' };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { applied: false, detail: `hardening check failed: ${msg}` };
+        }
+    };
+    return { sessionService, memoryService, checkRlsHardening };
+}

package/dist/lib/session/supabaseSessionService.d.ts

@@ -0,0 +1,26 @@
+import { BaseSessionService } from '@google/adk';
+import type { CreateSessionRequest, GetSessionRequest, ListSessionsRequest, ListSessionsResponse, DeleteSessionRequest, Session, Event } from '@google/adk';
+import type { SupabaseClient } from '@supabase/supabase-js';
+export declare class SupabaseSessionService extends BaseSessionService {
+    private supabase;
+    constructor(supabaseClient: SupabaseClient);
+    private getDbId;
+    createSession(request: CreateSessionRequest): Promise<Session>;
+    getSession(request: GetSessionRequest): Promise<Session | undefined>;
+    /**
+     * ADK's ListSessions contract carries paging: `limit` with either `page`
+     * (1-based, wins) or `offset` (0-based), plus an optional sort by last
+     * update, and the response must report where in the set the caller is.
+     * The window is pushed down to Postgres via .range(), and `count:
+     * 'exact'` returns the TOTAL matching rows alongside the page — so
+     * totalItems is the real total, not the slice length. With no `limit`,
+     * the whole set is one page, which is what the ADK's own docs specify
+     * ("Page size used. Equals `totalItems` when no limit was requested").
+     */
+    listSessions(request: ListSessionsRequest): Promise<ListSessionsResponse>;
+    deleteSession(request: DeleteSessionRequest): Promise<void>;
+    appendEvent(request: {
+        session: Session;
+        event: Event;
+    }): Promise<Event>;
+}