melchizedek-agents 0.16.0 → 0.16.2

package/.env.example

@@ -229,7 +229,12 @@ WIKI_AGENT_MODEL=
 # Send every span to any OTLP/HTTP backend (Phoenix, Langfuse, Jaeger, Tempo):
 # a local Phoenix is `docker run -p 6006:6006 arizephoenix/phoenix`.
 # OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:6006
+# OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer%20<token>   # a hosted backend's auth, if any
 # OTEL_SERVICE_NAME=melchizedek
+# How much conversation leaves with the spans (lib/observability/otlpFilter.ts):
+# redacted (default: the TELEMETRY_REDACT rules below), off (no conversation
+# text, user id hashed; timings, models, tokens, routes, errors stay), raw.
+# OTEL_EXPORT_CONTENT=redacted
 # Print [OTEL_SPAN_JSON] lines to stdout. Off by default: the root span carries
 # the full user message and answer.
 # OTEL_CONSOLE_SPANS=false

package/CHANGELOG.md

@@ -4,6 +4,29 @@ Consumers of the package read this file; it records changes to the
 **published API surface** (the exports map in `package.json`, the bins,
 the starter pack and the templates), not the repo's full history.
 
+## 0.16.2 — 2026-10-02
+
+- **`OTEL_EXPORT_CONTENT=off` also drops library content attributes.** In
+  0.16.1, `off` removed the engine's own conversation attributes but let
+  through ADK's: its `call_llm` span carries the full model request and
+  response as `gcp.vertex.agent.llm_request` / `_response`. `off` now drops
+  any text attribute whose name marks content (request, response, input,
+  output, args, prompt, messages, thinking, payload, …) unless the name
+  marks metadata (model, name, id, finish reasons); numbers always stay.
+  Verified end to end against Jaeger. **If you export OTLP with
+  `OTEL_EXPORT_CONTENT=off`, upgrade.** The default `redacted` mode
+  already ran the redactor on those attributes.
+
+## 0.16.1 — 2026-10-02
+
+- **OTLP export is filtered before it leaves** (`OTEL_EXPORT_CONTENT`).
+  Spans sent to `OTEL_EXPORTER_OTLP_ENDPOINT` carried the conversation
+  unredacted, while the ledger scrubs it (`TELEMETRY_REDACT`). The exporter
+  now applies the same redactor by default; `OTEL_EXPORT_CONTENT=off` drops
+  every conversation attribute (input, output, thinking, tool arguments and
+  results, payloads) and hashes `user.id`, keeping timings, models, token
+  counts, routes and errors; `raw` restores the old behaviour.
+
 ## 0.16.0 — 2026-10-02
 
 ### Breaking — read before upgrading

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

@@ -0,0 +1,18 @@
+import type { ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
+import type { Redactor } from './redact.ts';
+export type OtlpContentMode = 'redacted' | 'off' | 'raw';
+/** Span attributes that carry what a conversation said. */
+export declare const CONTENT_ATTRIBUTES: Set<string>;
+export declare function otlpContentMode(env?: NodeJS.ProcessEnv): OtlpContentMode;
+/** One span's attributes as they may leave under `mode`. */
+export declare function filterAttributes(attributes: Record<string, unknown>, mode: OtlpContentMode, redactor: Redactor | undefined): Record<string, unknown>;
+/** Wraps the OTLP exporter so every span is filtered before it is sent. */
+export declare class FilteringSpanExporter implements SpanExporter {
+    private readonly inner;
+    private readonly mode;
+    private readonly redactor;
+    constructor(inner: SpanExporter, mode: OtlpContentMode, redactor: Redactor | undefined);
+    export(spans: ReadableSpan[], resultCallback: Parameters<SpanExporter['export']>[1]): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}

package/dist/lib/observability/otlpFilter.js

@@ -0,0 +1,105 @@
+/**
+ * lib/observability/otlpFilter.ts — what leaves for an external trace backend.
+ *
+ * Spans carry the conversation: a turn's input and output, the model's
+ * thinking, tool arguments and results, the full request and response. The
+ * ledger scrubs those before it writes them (redact.ts, TELEMETRY_REDACT); an
+ * OTLP backend is a third party, so the same rule applies on the way out,
+ * and an adopter can choose to send no conversation at all.
+ *
+ *   OTEL_EXPORT_CONTENT=redacted   (default) the ledger's redactor runs on
+ *                                  every text attribute and event
+ *   OTEL_EXPORT_CONTENT=off        conversation attributes are dropped (the
+ *                                  engine's and any library's, by name) and
+ *                                  the user id is hashed; timings, models,
+ *                                  token counts, routes, error codes and ids
+ *                                  remain
+ *   OTEL_EXPORT_CONTENT=raw        spans are sent as recorded
+ */
+import { createHash } from 'node:crypto';
+/** Span attributes that carry what a conversation said. */
+export const CONTENT_ATTRIBUTES = new Set([
+    'syndicate.input',
+    'syndicate.output',
+    'syndicate.bindings',
+    'syndicate.route.reason',
+    'syndicate.error.message',
+    'llm.thinking',
+    'llm.error_message',
+    'tool.args',
+    'tool.data_gathered',
+]);
+const CONTENT_PREFIXES = ['llm.payload.'];
+const PERSON_ATTRIBUTES = new Set(['user.id']);
+/**
+ * Libraries add their own content attributes (ADK puts the whole model request
+ * on its call_llm span as `gcp.vertex.agent.llm_request`, and the response and
+ * tool calls beside it), and a later version can add more. So `off` also drops
+ * any text attribute whose name says it carries content, unless the name says
+ * it is metadata (a model, a name, an id, a finish reason).
+ */
+const CONTENT_KEY = /(^|[._])(request|response|input|output|args|arguments|prompt|completion|messages?|content|thinking|payload|data_gathered|bindings|reason|error_message)([._]|$)/i;
+const METADATA_KEY = /([._])(model|name|id|system|description|finish_reasons|type|kind|version|stage)$/i;
+export function otlpContentMode(env = process.env) {
+    const raw = (env.OTEL_EXPORT_CONTENT ?? 'redacted').trim().toLowerCase();
+    if (raw === 'off' || raw === 'none' || raw === 'false')
+        return 'off';
+    if (raw === 'raw')
+        return 'raw';
+    return 'redacted';
+}
+const isText = (v) => typeof v === 'string' || (Array.isArray(v) && v.some((x) => typeof x === 'string'));
+const isContent = (key, value) => CONTENT_ATTRIBUTES.has(key) ||
+    CONTENT_PREFIXES.some((p) => key.startsWith(p)) ||
+    (isText(value) && CONTENT_KEY.test(key) && !METADATA_KEY.test(key));
+const hashed = (v) => `sha256:${createHash('sha256').update(String(v)).digest('hex').slice(0, 16)}`;
+/** One span's attributes as they may leave under `mode`. */
+export function filterAttributes(attributes, mode, redactor) {
+    if (mode === 'raw')
+        return attributes;
+    const out = {};
+    for (const [key, value] of Object.entries(attributes)) {
+        if (mode === 'off') {
+            if (isContent(key, value))
+                continue;
+            out[key] = PERSON_ATTRIBUTES.has(key) ? hashed(value) : value;
+            continue;
+        }
+        out[key] =
+            redactor && typeof value === 'string'
+                ? redactor(value)
+                : redactor && Array.isArray(value)
+                    ? value.map((v) => (typeof v === 'string' ? redactor(v) : v))
+                    : value;
+    }
+    return out;
+}
+/** A span whose attributes and events are filtered; everything else reads through. */
+function filtered(span, mode, redactor) {
+    const view = Object.create(span);
+    Object.defineProperty(view, 'attributes', { value: filterAttributes(span.attributes, mode, redactor) });
+    Object.defineProperty(view, 'events', {
+        value: span.events.map((e) => (e.attributes ? { ...e, attributes: filterAttributes(e.attributes, mode, redactor) } : e)),
+    });
+    return view;
+}
+/** Wraps the OTLP exporter so every span is filtered before it is sent. */
+export class FilteringSpanExporter {
+    inner;
+    mode;
+    redactor;
+    constructor(inner, mode, redactor) {
+        this.inner = inner;
+        this.mode = mode;
+        this.redactor = redactor;
+    }
+    export(spans, resultCallback) {
+        this.inner.export(this.mode === 'raw' ? spans : spans.map((s) => filtered(s, this.mode, this.redactor)), resultCallback);
+    }
+    shutdown() {
+        return this.inner.shutdown();
+    }
+    forceFlush() {
+        return this.inner.forceFlush?.() ?? Promise.resolve();
+    }
+}

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

@@ -7,6 +7,8 @@ import type { Event, LlmResponse } from '@google/adk';
  * every span — ADK's included, so the viewer gets the waterfall — is also
  * sent there. OTEL_EXPORTER_OTLP_HEADERS is honoured by the exporter itself
  * (api keys); OTEL_SERVICE_NAME names the service (default "melchizedek").
+ * OTEL_EXPORT_CONTENT decides how much conversation leaves with the spans:
+ * redacted (default, the ledger's TELEMETRY_REDACT rules), off, or raw.
  * Supabase stays the system of record; this is a viewer.
  */
 export declare function otlpEndpoint(): string | undefined;

package/dist/lib/observability/tracer.js

@@ -1,6 +1,8 @@
 import { trace, context } from '@opentelemetry/api';
 import { createRequire } from 'node:module';
 import { TELEMETRY_SCHEMA_VERSION, engineVersion } from './lineage.js';
+import { FilteringSpanExporter, otlpContentMode } from './otlpFilter.js';
+import { telemetryRedactor } from './redact.js';
 import { chargeLlmCall, chargeTokens } from '../runtime/turnControl.js';
 import sdkNode from '@opentelemetry/sdk-trace-node';
 const { NodeTracerProvider } = sdkNode;
@@ -16,6 +18,8 @@ import { SupabaseSpanExporter, telemetrySinkEnabled, } from './supabaseSpanExpor
  * every span — ADK's included, so the viewer gets the waterfall — is also
  * sent there. OTEL_EXPORTER_OTLP_HEADERS is honoured by the exporter itself
  * (api keys); OTEL_SERVICE_NAME names the service (default "melchizedek").
+ * OTEL_EXPORT_CONTENT decides how much conversation leaves with the spans:
+ * redacted (default, the ledger's TELEMETRY_REDACT rules), off, or raw.
  * Supabase stays the system of record; this is a viewer.
  */
 export function otlpEndpoint() {
@@ -33,8 +37,11 @@ function otlpProcessor() {
         const mod = createRequire(import.meta.url)('@opentelemetry/exporter-trace-otlp-http');
         const OTLPTraceExporter = mod.OTLPTraceExporter ?? mod.default?.OTLPTraceExporter;
         const { BatchSpanProcessor } = sdkBase;
-        console.log(`[TELEMETRY] OTLP export enabled → ${url}`);
-        return new BatchSpanProcessor(new OTLPTraceExporter({ url }));
+        // What leaves for a third-party backend is filtered first (otlpFilter.ts).
+        const mode = otlpContentMode();
+        console.log(`[TELEMETRY] OTLP export enabled → ${url} (content: ${mode})`);
+        const exporter = new OTLPTraceExporter({ url });
+        return new BatchSpanProcessor(mode === 'raw' ? exporter : new FilteringSpanExporter(exporter, mode, telemetryRedactor()));
     }
     catch (err) {
         console.warn(`[TELEMETRY] OTLP exporter unavailable (${err instanceof Error ? err.message : err}); spans not sent to ${url}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "melchizedek-agents",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "description": "A multi-model, multi-agent orchestration framework on Google ADK — YAML-defined syndicates, Supabase session persistence, pgvector long-term memory. Companion repo to the lyceumagents.com curriculum.",
   "type": "module",
   "license": "MIT",