melchizedek-agents 0.9.0 → 0.9.3

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 {};