melchizedek-agents 0.9.2 → 0.9.3

package/dist/lib/models/openAiCompatibleLlm.js

@@ -30,7 +30,7 @@
 import { BaseLlm } from '@google/adk';
 import { traceLlmGeneration, setLlmSpanAttribute, } from "../observability/tracer.js";
 import { wantsWebSearch, isWebSearchSentinel, } from "../tools/webSearchTool.js";
-import { toLowercaseJsonSchema } from "./schemaNormalize.js";
+import { toLowercaseJsonSchema, toStrictJsonSchema } from "./schemaNormalize.js";
 /** Splits "<think>…</think>" scratchpad from the reply. */
 export function splitThinkBlocks(text) {
     const blocks = [];
@@ -50,6 +50,10 @@ export class OpenAiCompatibleLlm extends BaseLlm {
         return this.model;
     }
     /** Provider-specific request body fields (merged last). */
+    /** Whether the endpoint accepts response_format json_schema (strict). */
+    supportsJsonSchemaFormat() {
+        return true;
+    }
     extraBodyFields(_llmRequest) {
         return {};
     }
@@ -115,10 +119,15 @@ export class OpenAiCompatibleLlm extends BaseLlm {
                 ? { max_tokens: cfg.maxOutputTokens }
                 : {}),
             ...(openAiTools.length > 0 ? { tools: openAiTools } : {}),
-            // critic-style structured output: responseMimeType JSON → json mode
-            ...(cfg.responseMimeType === 'application/json'
-                ? { response_format: { type: 'json_object' } }
-                : {}),
+            // Structured output: an ADK outputSchema becomes a strict json_schema
+            // response_format where the endpoint supports it (xAI does; Ollama's
+            // OpenAI-compatible endpoint does not, see supportsJsonSchemaFormat),
+            // else plain JSON mode.
+            ...(cfg.responseSchema && this.supportsJsonSchemaFormat()
+                ? { response_format: { type: 'json_schema', json_schema: { name: 'response', strict: true, schema: toStrictJsonSchema(cfg.responseSchema) } } }
+                : cfg.responseMimeType === 'application/json' || cfg.responseSchema
+                    ? { response_format: { type: 'json_object' } }
+                    : {}),
             ...this.extraBodyFields(llmRequest),
         };
         // web_search: enable the provider's native search, or omit with a warning.

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

@@ -20,3 +20,12 @@
  * Never mutates the input — a Gemini agent may hold the same tool object.
  */
 export declare function toLowercaseJsonSchema(schema: unknown): Record<string, unknown>;
+/**
+ * The lowercase schema in the shape OpenAI-style "strict" structured output
+ * demands: every object node carries `additionalProperties: false` and lists
+ * ALL of its properties as required. Optional fields are expressed by the
+ * model emitting a null/empty value, not by omission — that is the strict
+ * contract, and it is what makes a judge's rubric fields arrive under the
+ * names the harness expects rather than improvised ones.
+ */
+export declare function toStrictJsonSchema(schema: unknown): Record<string, unknown>;

package/dist/lib/models/schemaNormalize.js

@@ -56,3 +56,37 @@ function normalizeNode(node) {
     }
     return out;
 }
+/**
+ * The lowercase schema in the shape OpenAI-style "strict" structured output
+ * demands: every object node carries `additionalProperties: false` and lists
+ * ALL of its properties as required. Optional fields are expressed by the
+ * model emitting a null/empty value, not by omission — that is the strict
+ * contract, and it is what makes a judge's rubric fields arrive under the
+ * names the harness expects rather than improvised ones.
+ */
+export function toStrictJsonSchema(schema) {
+    return strictNode(toLowercaseJsonSchema(schema));
+}
+function strictNode(node) {
+    if (Array.isArray(node))
+        return node.map(strictNode);
+    if (!node || typeof node !== 'object')
+        return node;
+    const out = { ...node };
+    const type = out.type;
+    const isObject = type === 'object' || (Array.isArray(type) && type.includes('object')) || isPlainObject(out.properties);
+    if (isObject && isPlainObject(out.properties)) {
+        const props = {};
+        for (const [k, v] of Object.entries(out.properties))
+            props[k] = strictNode(v);
+        out.properties = props;
+        out.required = Object.keys(props);
+        out.additionalProperties = false;
+    }
+    if (out.items !== undefined)
+        out.items = strictNode(out.items);
+    return out;
+}
+function isPlainObject(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}

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

@@ -0,0 +1,21 @@
+/**
+ * lib/observability/embeddings.ts — embeddings for ledger search.
+ *
+ * The same model and dimensionality as long-term memory (lib/config.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 { EMBEDDING_DIMENSIONS, EMBEDDING_MODEL } from '../config.ts';
+export interface EmbedOptions {
+    apiKey?: string;
+    /** Characters kept per text (long answers are truncated, not skipped). */
+    maxChars?: number;
+}
+/** Embeds each text; a failed text yields an empty vector rather than a throw. */
+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;
+export { EMBEDDING_DIMENSIONS, EMBEDDING_MODEL };

package/dist/lib/observability/embeddings.js

@@ -0,0 +1,47 @@
+/**
+ * lib/observability/embeddings.ts — embeddings for ledger search.
+ *
+ * The same model and dimensionality as long-term memory (lib/config.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";
+const MAX_CHARS = 8_000;
+/** Embeds each text; a failed text yields an empty vector rather than a throw. */
+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 });
+    const limit = options.maxChars ?? MAX_CHARS;
+    const out = [];
+    for (const text of texts) {
+        const clipped = (text ?? '').slice(0, limit);
+        if (!clipped.trim()) {
+            out.push([]);
+            continue;
+        }
+        try {
+            const response = await genai.models.embedContent({
+                model: EMBEDDING_MODEL,
+                contents: clipped,
+                config: { outputDimensionality: EMBEDDING_DIMENSIONS },
+            });
+            out.push(response.embeddings?.[0]?.values ?? []);
+        }
+        catch (err) {
+            console.warn(`[embeddings] failed: ${err instanceof Error ? err.message : String(err)}`);
+            out.push([]);
+        }
+    }
+    return out;
+}
+/** The text a turn is embedded by: the question and the answer, in that order. */
+export function turnEmbeddingText(input, output) {
+    return `${(input ?? '').trim()}\n\n${(output ?? '').trim()}`.trim();
+}
+export { EMBEDDING_DIMENSIONS, EMBEDDING_MODEL };

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

@@ -0,0 +1,35 @@
+/**
+ * lib/observability/lineage.ts — provenance stamps for the ledger.
+ *
+ * A stored output is evidence only if you know exactly what produced it.
+ * Every turn row carries two stamps computed here:
+ *
+ *   config_hash     SHA-256 (first 16 hex) of the RESOLVED syndicate config
+ *                   with every nested `yaml_reference` inlined — the exact
+ *                   prompts, models, tools and generation settings that ran.
+ *                   Two deployments serving "the same" syndicate with a
+ *                   drifted registry row or a stale file produce different
+ *                   hashes, which is the first time that drift is visible in
+ *                   stored data. Eval runs hash the overridden config, so a
+ *                   variant's rows are distinguishable from production's.
+ *   engine_version  package version plus the git commit (or the platform's
+ *                   SOURCE_VERSION / HEROKU_SLUG_COMMIT), so a behaviour
+ *                   change can be pinned to a deploy.
+ *
+ * Both are deterministic and cheap; neither touches the network.
+ */
+import type { SyndicateYamlConfig } from '../loadSyndicate.ts';
+/** Schema version stamped on every ledger row (adk_turns / adk_payloads). */
+export declare const TELEMETRY_SCHEMA_VERSION = 2;
+/** JSON with object keys sorted at every depth — stable across reloads. */
+export declare function stableStringify(value: unknown): string;
+/** The config with every `yaml_reference` replaced by the loaded syndicate. */
+export declare function inlineReferences(config: SyndicateYamlConfig, loadNested: (ref: string) => SyndicateYamlConfig, seen?: Set<string>): Record<string, unknown>;
+/**
+ * Hash of the fully resolved config. `loadNested` is the same loader the
+ * caller compiles with (the server's plain loadSyndicate; the observatory's
+ * override-applying loader), so the hash describes what actually ran.
+ */
+export declare function configDigest(config: SyndicateYamlConfig, loadNested: (ref: string) => SyndicateYamlConfig): string;
+/** "<package version>+<commit>" — commit from the platform env or git, else "local". */
+export declare function engineVersion(): string;

package/dist/lib/observability/lineage.js

@@ -0,0 +1,96 @@
+/**
+ * lib/observability/lineage.ts — provenance stamps for the ledger.
+ *
+ * A stored output is evidence only if you know exactly what produced it.
+ * Every turn row carries two stamps computed here:
+ *
+ *   config_hash     SHA-256 (first 16 hex) of the RESOLVED syndicate config
+ *                   with every nested `yaml_reference` inlined — the exact
+ *                   prompts, models, tools and generation settings that ran.
+ *                   Two deployments serving "the same" syndicate with a
+ *                   drifted registry row or a stale file produce different
+ *                   hashes, which is the first time that drift is visible in
+ *                   stored data. Eval runs hash the overridden config, so a
+ *                   variant's rows are distinguishable from production's.
+ *   engine_version  package version plus the git commit (or the platform's
+ *                   SOURCE_VERSION / HEROKU_SLUG_COMMIT), so a behaviour
+ *                   change can be pinned to a deploy.
+ *
+ * Both are deterministic and cheap; neither touches the network.
+ */
+import { createHash } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Schema version stamped on every ledger row (adk_turns / adk_payloads). */
+export const TELEMETRY_SCHEMA_VERSION = 2;
+/** JSON with object keys sorted at every depth — stable across reloads. */
+export function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const obj = value;
+    const keys = Object.keys(obj)
+        .filter((k) => obj[k] !== undefined)
+        .sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(',')}}`;
+}
+/** The config with every `yaml_reference` replaced by the loaded syndicate. */
+export function inlineReferences(config, loadNested, seen = new Set()) {
+    return {
+        ...config,
+        subagents: (config.subagents ?? []).map((sub) => {
+            if (!sub.yaml_reference || seen.has(sub.yaml_reference))
+                return sub;
+            const next = new Set(seen);
+            next.add(sub.yaml_reference);
+            let nested;
+            try {
+                nested = inlineReferences(loadNested(sub.yaml_reference), loadNested, next);
+            }
+            catch (err) {
+                nested = { unresolved: sub.yaml_reference, error: err instanceof Error ? err.message : String(err) };
+            }
+            return { ...sub, resolved_reference: nested };
+        }),
+    };
+}
+/**
+ * Hash of the fully resolved config. `loadNested` is the same loader the
+ * caller compiles with (the server's plain loadSyndicate; the observatory's
+ * override-applying loader), so the hash describes what actually ran.
+ */
+export function configDigest(config, loadNested) {
+    const resolved = inlineReferences(config, loadNested);
+    return createHash('sha256').update(stableStringify(resolved)).digest('hex').slice(0, 16);
+}
+let cachedEngineVersion;
+/** "<package version>+<commit>" — commit from the platform env or git, else "local". */
+export function engineVersion() {
+    if (cachedEngineVersion)
+        return cachedEngineVersion;
+    let pkgVersion = '0.0.0';
+    try {
+        const pkgPath = join(process.cwd(), 'package.json');
+        if (existsSync(pkgPath)) {
+            pkgVersion = String(JSON.parse(readFileSync(pkgPath, 'utf-8')).version ?? pkgVersion);
+        }
+    }
+    catch {
+        /* no package.json in cwd — version stays 0.0.0 */
+    }
+    let commit = process.env.SOURCE_VERSION ?? process.env.HEROKU_SLUG_COMMIT ?? process.env.GIT_COMMIT ?? '';
+    if (!commit) {
+        try {
+            commit = execSync('git rev-parse --short HEAD', { stdio: ['ignore', 'pipe', 'ignore'] })
+                .toString()
+                .trim();
+        }
+        catch {
+            commit = 'local';
+        }
+    }
+    cachedEngineVersion = `${pkgVersion}+${commit.slice(0, 12)}`;
+    return cachedEngineVersion;
+}

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

@@ -1,35 +1,203 @@
 /**
- * lib/observability/supabaseSpanExporter.ts — optional OpenTelemetry sink
- * that persists model-request telemetry to Supabase.
+ * lib/observability/supabaseSpanExporter.ts — the observability ledger sink.
  *
  * 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).
+ *   [OTEL_SPAN_JSON] line — good for a terminal, gone when it scrolls. With
+ *   TELEMETRY_SUPABASE=true (and Supabase credentials) every turn and every
+ *   model call is also written to Supabase, in three tiers with three
+ *   lifetimes (schema: db/telemetry.sql, lockdown: db/hardening.sql):
+ *
+ *     adk_turns      one row per turn — the system of record: input, output,
+ *                    route, agent, errors, tokens, model-vs-tool time, the
+ *                    tool calls WITH their responses, the ids that join it to
+ *                    the session (session_id, invocation_id) and the task,
+ *                    and provenance (config_hash, engine_version).
+ *     adk_telemetry  one row per span — llm.request and root spans, raw.
+ *     adk_payloads   full request/response per model call, captured by
+ *                    POLICY and expiring. ADK's own call_llm spans carry the
+ *                    assembled prompt and raw response; they are 10-100x a
+ *                    turn row, so: errors and fallbacks always, a
+ *                    deterministic sample of the rest, 30-day TTL.
  *
  * 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.
+ *   - Never on the hot path: inserts are fire-and-forget behind a
+ *     BatchSpanProcessor; a failure is logged once per table and the rows
+ *     are spooled to a dead-letter file (OUTPUTS_DIR/telemetry-deadletter.ndjson)
+ *     so a sink outage loses nothing silently. `npm run telemetry:stats`
+ *     shows what landed; `telemetry:replay` re-sends the spool.
+ *   - Payload decisions need the TURN's outcome (error? fallback?), which is
+ *     only known when the root span ends — after its call_llm children. So
+ *     call_llm spans wait in a per-trace buffer until their root arrives,
+ *     then the decision is applied to all of them at once. Children that
+ *     arrive after the root (a later batch) find the decision cached.
+ *   - Sampling is deterministic in the trace id: a trace keeps all of its
+ *     payloads or none, and a re-run of the same policy keeps the same set.
  */
 import type { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';
-/** True when the operator has opted into the Supabase telemetry sink. */
+/** Row shape for adk_telemetry (raw spans). */
+export interface TelemetryRow {
+    ts: string;
+    trace_id: string;
+    span_id: string;
+    span_name: string;
+    syndicate: string | null;
+    agent: string | null;
+    provider: string | null;
+    model: string | null;
+    input_tokens: number | null;
+    output_tokens: number | null;
+    thinking_tokens: number | null;
+    latency_ms: number;
+    session_id: string | null;
+    user_id: string | null;
+    task_id: string | null;
+    invocation_id: string | null;
+    schema_version: number;
+    span: Record<string, unknown>;
+}
+/** Row shape for adk_turns (the system of record). */
+export interface TurnRow {
+    ts: string;
+    trace_id: string;
+    span_id: string;
+    session_id: string | null;
+    user_id: string | null;
+    task_id: string | null;
+    invocation_id: string | null;
+    syndicate: string;
+    stage: string;
+    agent: string | null;
+    route: string | null;
+    route_reason: string | null;
+    route_fell_back: boolean | null;
+    route_via_override: boolean | null;
+    relay_fallback: boolean;
+    input: string;
+    output: string;
+    error_code: string | null;
+    error_message: string | null;
+    input_tokens: number | null;
+    output_tokens: number | null;
+    thinking_tokens: number | null;
+    latency_ms: number;
+    model_ms: number | null;
+    tool_ms: number | null;
+    llm_calls: number | null;
+    tool_calls: number;
+    models: string[];
+    tool_events: Array<Record<string, unknown>>;
+    config_hash: string | null;
+    engine_version: string | null;
+    eval_run: string | null;
+    eval_suite: string | null;
+    eval_case: string | null;
+    eval_variant: string | null;
+    eval_trial: number | null;
+    attributes: Record<string, unknown>;
+    schema_version: number;
+}
+export type PayloadReason = 'error' | 'fallback' | 'sample' | 'all';
+/** Row shape for adk_payloads. */
+export interface PayloadRow {
+    ts: string;
+    trace_id: string;
+    span_id: string;
+    session_id: string | null;
+    invocation_id: string | null;
+    agent: string | null;
+    provider: string | null;
+    model: string | null;
+    reason: PayloadReason;
+    request: unknown;
+    response: unknown;
+    request_chars: number;
+    response_chars: number;
+    expires_at: string;
+    schema_version: number;
+}
+export type PayloadMode = 'off' | 'errors' | 'sample' | 'all';
+export interface PayloadPolicy {
+    mode: PayloadMode;
+    /** Fraction of non-error, non-fallback traces kept in 'sample' mode. */
+    sampleRate: number;
+    ttlDays: number;
+}
+/**
+ * TELEMETRY_PAYLOADS: off | errors | sample (default) | all
+ * TELEMETRY_PAYLOAD_SAMPLE: 0..1, default 0.10
+ * TELEMETRY_PAYLOAD_TTL_DAYS: default 30
+ */
+export declare function payloadPolicyFromEnv(env?: NodeJS.ProcessEnv): PayloadPolicy;
+/** Deterministic 0..1 value from a trace id (first 8 hex chars). */
+export declare function traceSampleValue(traceId: string): number;
+export interface TurnFacts {
+    error: boolean;
+    fallback: boolean;
+}
+/** Which payloads of a turn to keep, given the policy and the turn's outcome. */
+export declare function payloadDecision(policy: PayloadPolicy, traceId: string, facts: TurnFacts): PayloadReason | null;
+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;
+/** 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. */
+export declare function toTurnRow(span: ReadableSpan): TurnRow;
+/** The facts a payload decision needs, read off a root span. */
+export declare function turnFacts(span: ReadableSpan): TurnFacts;
+/** Map an ADK call_llm span into an adk_payloads row. */
+export declare function toPayloadRow(span: ReadableSpan, reason: PayloadReason, ttlDays: number, turn: {
+    sessionId: string | null;
+    invocationId: string | null;
+} | undefined): PayloadRow;
+/** True when the operator has opted into the Supabase ledger. */
 export declare function telemetrySinkEnabled(): boolean;
+export declare function deadLetterPath(): string;
+export interface ExportStats {
+    inserted: Record<string, number>;
+    failed: Record<string, number>;
+    deadLettered: number;
+    payloadsDropped: number;
+}
+interface SupabaseLikeClient {
+    from(table: string): {
+        insert(rows: unknown[]): PromiseLike<{
+            error: {
+                message: string;
+            } | null;
+        }>;
+    };
+}
+export interface ExporterOptions {
+    /** Injected client (tests); default: lazily created supabase-js client. */
+    client?: SupabaseLikeClient;
+    policy?: PayloadPolicy;
+    /** Where failed batches are spooled; '' disables the spool. */
+    deadLetterFile?: string;
+}
 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 readonly policy;
+    private readonly deadLetterFile;
+    private readonly failureLogged;
+    private readonly pendingInserts;
+    /** call_llm spans waiting for their root span's outcome, by trace id. */
+    private readonly pendingPayloads;
+    /** Decisions already taken for a trace, for children arriving late. */
+    private readonly decisions;
+    private pendingCount;
+    readonly stats: ExportStats;
+    constructor(options?: ExporterOptions);
     private getClient;
     export(spans: ReadableSpan[], resultCallback: (result: any) => void): void;
+    private pruneBuffers;
+    /** Fire-and-forget insert; failures are logged once per table and spooled. */
+    private insert;
+    private onFailure;
     /** 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;
 }
+export {};