melchizedek-agents 0.9.0 → 0.9.3

package/dist/lib/observability/tracer.js

@@ -1,4 +1,6 @@
 import { trace, context } from '@opentelemetry/api';
+import { createRequire } from 'node:module';
+import { TELEMETRY_SCHEMA_VERSION, engineVersion } from "./lineage.js";
 import sdkNode from '@opentelemetry/sdk-trace-node';
 const { NodeTracerProvider } = sdkNode;
 import sdkBase from '@opentelemetry/sdk-trace-base';
@@ -6,6 +8,38 @@ const { SimpleSpanProcessor } = sdkBase;
 import core from '@opentelemetry/core';
 const { ExportResultCode } = core;
 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
+ * OTEL_EXPORTER_OTLP_ENDPOINT (e.g. http://localhost:6006 for Phoenix) and
+ * 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").
+ * Supabase stays the system of record; this is a viewer.
+ */
+export function otlpEndpoint() {
+    const raw = process.env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim();
+    if (!raw)
+        return undefined;
+    return /\/v1\/traces\/?$/.test(raw) ? raw : `${raw.replace(/\/$/, '')}/v1/traces`;
+}
+function otlpProcessor() {
+    const url = otlpEndpoint();
+    if (!url)
+        return undefined;
+    try {
+        // Synchronous load: NodeTracerProvider wants its processors at construction.
+        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 }));
+    }
+    catch (err) {
+        console.warn(`[TELEMETRY] OTLP exporter unavailable (${err instanceof Error ? err.message : err}); spans not sent to ${url}`);
+        return undefined;
+    }
+}
 let isOtelInitialized = false;
 let tracerProvider;
 let telemetryExporter;
@@ -27,6 +61,17 @@ export function onSpanEnd(listener) {
     spanEndListeners.add(listener);
     return () => spanEndListeners.delete(listener);
 }
+// ADK's own spans (scope "gcp.vertex.agent": invocation, invoke_agent,
+// call_llm, execute_tool) carry the FULL model request and response as
+// attributes. They reach the in-process listeners — that is how per-agent
+// attribution and the observatory work — but are not printed unless asked:
+// on a server they would put every prompt into the log stream.
+const ADK_SCOPE = 'gcp.vertex.agent';
+const PRINT_ALL_SPANS = process.env.OTEL_CONSOLE_ALL_SPANS === 'true';
+function spanScopeName(span) {
+    const s = span;
+    return s.instrumentationScope?.name ?? s.instrumentationLibrary?.name ?? '';
+}
 class JsonConsoleExporter {
     export(spans, resultCallback) {
         for (const span of spans) {
@@ -38,6 +83,8 @@ class JsonConsoleExporter {
                     /* a listener bug must not break the export pipeline */
                 }
             }
+            if (!PRINT_ALL_SPANS && spanScopeName(span) === ADK_SCOPE)
+                continue;
             // Create a clean JSON representation of the span
             const jsonSpan = {
                 traceId: span.spanContext().traceId,
@@ -63,6 +110,131 @@ class JsonConsoleExporter {
         return Promise.resolve();
     }
 }
+// ── Span lineage (per-agent attribution) ─────────────────────────────────────
+// ADK wraps every agent turn in an `invoke_agent <name>` span and every model
+// call in a `call_llm` child of it; our llm.request span is a child of THAT.
+// A span cannot read its parent's name through the OTEL API, so a processor
+// records each span's name and parent at start, and llm.request walks up the
+// chain to find the agent it belongs to. This is what fills the `agent`
+// column of adk_telemetry — per-subagent cost and latency attribution — and
+// what lets the observatory say which agent made which call.
+const spanLineage = new Map();
+const SPAN_LINEAGE_CAP = 10_000;
+const traceStats = new Map();
+const TRACE_STATS_TTL_MS = 60 * 60 * 1000;
+function statsFor(traceId) {
+    let s = traceStats.get(traceId);
+    if (!s) {
+        s = { modelMs: 0, toolMs: 0, llmCalls: 0, models: new Set(), startedAt: Date.now() };
+        traceStats.set(traceId, s);
+        if (traceStats.size > 2_000) {
+            const cutoff = Date.now() - TRACE_STATS_TTL_MS;
+            for (const [id, st] of traceStats)
+                if (st.startedAt < cutoff)
+                    traceStats.delete(id);
+        }
+    }
+    return s;
+}
+/** Read-and-forget the stats for a finished trace. */
+export function takeTraceStats(traceId) {
+    const s = traceStats.get(traceId);
+    traceStats.delete(traceId);
+    return s;
+}
+function spanDurationMs(span) {
+    return span.duration[0] * 1000 + span.duration[1] / 1e6;
+}
+class SpanLineageProcessor {
+    onStart(span) {
+        const ctx = span.spanContext();
+        const parent = span.parentSpanContext?.spanId ?? span.parentSpanId ?? undefined;
+        spanLineage.set(ctx.spanId, { name: span.name, parent });
+        // ADK's call_llm span (the one carrying the full request/response
+        // payloads) learns its agent the same way llm.request does, so a
+        // payload row can be attributed without re-walking the tree later.
+        if (span.name === 'call_llm') {
+            const agent = agentForSpan(parent);
+            if (agent)
+                span.setAttribute('llm.agent', agent);
+        }
+        if (spanLineage.size > SPAN_LINEAGE_CAP) {
+            // A runaway process must never grow this without bound; parents end
+            // after their children, so evicting the oldest entry is safe.
+            const oldest = spanLineage.keys().next().value;
+            if (oldest !== undefined)
+                spanLineage.delete(oldest);
+        }
+    }
+    onEnd(span) {
+        spanLineage.delete(span.spanContext().spanId);
+        const traceId = span.spanContext().traceId;
+        if (span.name === 'llm.request') {
+            const s = statsFor(traceId);
+            s.modelMs += spanDurationMs(span);
+            s.llmCalls += 1;
+            const model = span.attributes['llm.model'];
+            if (typeof model === 'string' && model)
+                s.models.add(model);
+        }
+        else if (span.name.startsWith('execute_tool ')) {
+            statsFor(traceId).toolMs += spanDurationMs(span);
+        }
+    }
+    shutdown() { return Promise.resolve(); }
+    forceFlush() { return Promise.resolve(); }
+}
+/** Name of the nearest enclosing ADK `invoke_agent` span, or null. */
+export function agentForSpan(spanId) {
+    let cursor = spanId;
+    for (let depth = 0; cursor && depth < 12; depth++) {
+        const entry = spanLineage.get(cursor);
+        if (!entry)
+            return null;
+        if (entry.name.startsWith('invoke_agent '))
+            return entry.name.slice('invoke_agent '.length);
+        cursor = entry.parent;
+    }
+    return null;
+}
+/**
+ * Hands the provider to ADK's private copy of @opentelemetry/api.
+ *
+ * WHY: @google/adk pins its own @opentelemetry/api (nested under its
+ * node_modules) and creates its tracer at module-import time —
+ * `trace.getTracer("gcp.vertex.agent")` in telemetry/tracing.js. That call
+ * runs BEFORE any entrypoint can register a provider, so it binds to that
+ * copy's ProxyTracerProvider, whose delegate is only ever set by a
+ * `setGlobalTracerProvider` call made through the SAME copy. Ours goes
+ * through the top-level copy; the global registration is shared (it lives
+ * on a well-known Symbol), but the proxy's delegate is not. Result: every
+ * ADK span — invoke_agent, call_llm, execute_tool — was a no-op, and
+ * llm.request spans had no parent. Setting the delegate on ADK's proxy
+ * fixes both: ADK spans now export, and the context manager (global,
+ * shared) threads our llm.request spans under ADK's call_llm.
+ *
+ * `_proxyTracerProvider` is a private field of TraceAPI; this is the only
+ * place that touches it, it is guarded, and a failure just means ADK spans
+ * stay invisible — as they were.
+ */
+function adoptAdkTracerApi(provider) {
+    try {
+        const requireHere = createRequire(import.meta.url);
+        const adkEntry = requireHere.resolve('@google/adk');
+        const adkApi = createRequire(adkEntry)('@opentelemetry/api');
+        if (adkApi?.trace === trace)
+            return true;
+        const proxy = adkApi?.trace?._proxyTracerProvider;
+        if (proxy && typeof proxy.setDelegate === 'function') {
+            proxy.setDelegate(provider);
+            return true;
+        }
+    }
+    catch {
+        /* ADK not installed or its api copy changed shape — see WHY above */
+    }
+    return false;
+}
 export function initializeTracing() {
     if (isOtelInitialized)
         return;
@@ -70,6 +242,7 @@ export function initializeTracing() {
     // 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 SpanLineageProcessor(),
         new SimpleSpanProcessor(new JsonConsoleExporter()),
     ];
     // Optional durable sink (TELEMETRY_SUPABASE=true + Supabase credentials):
@@ -82,12 +255,27 @@ export function initializeTracing() {
         spanProcessors.push(new BatchSpanProcessor(telemetryExporter));
         console.log('[TELEMETRY] Supabase sink enabled → adk_telemetry');
     }
-    const provider = new NodeTracerProvider({ spanProcessors });
+    const otlp = otlpProcessor();
+    if (otlp)
+        spanProcessors.push(otlp);
+    let resource;
+    try {
+        const res = createRequire(import.meta.url)('@opentelemetry/resources');
+        const make = res.resourceFromAttributes ?? res.Resource?.default?.bind(res.Resource);
+        resource = make ? make({ 'service.name': process.env.OTEL_SERVICE_NAME ?? 'melchizedek' }) : undefined;
+    }
+    catch {
+        resource = undefined;
+    }
+    const provider = new NodeTracerProvider({ spanProcessors, ...(resource ? { resource } : {}) });
     provider.register();
+    adoptAdkTracerApi(provider);
     tracerProvider = provider;
     isOtelInitialized = true;
 }
 const tracer = trace.getTracer('melchizedek-tracer');
+/** Turn identity by trace id, so llm.request children can carry it too. */
+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.
@@ -95,16 +283,53 @@ const tracer = trace.getTracer('melchizedek-tracer');
 export async function* traceAgentRun(stream, metadata) {
     initializeTracing();
     const span = tracer.startSpan(`Syndicate Execution: ${metadata.syndicateName}`);
+    turnContexts.set(span.spanContext().traceId, {
+        sessionId: metadata.sessionId,
+        userId: metadata.userId,
+        taskId: metadata.taskId,
+    });
     if (metadata.bindings) {
         span.setAttribute('syndicate.bindings', JSON.stringify(metadata.bindings));
     }
     if (metadata.input) {
         span.setAttribute('syndicate.input', JSON.stringify(metadata.input));
     }
+    if (metadata.route) {
+        span.setAttribute('syndicate.route', metadata.route.route);
+        if (metadata.route.reason)
+            span.setAttribute('syndicate.route.reason', metadata.route.reason);
+        span.setAttribute('syndicate.route.fell_back', metadata.route.fellBack === true);
+        span.setAttribute('syndicate.route.via_override', metadata.route.viaOverride === true);
+    }
+    if (metadata.sessionId) {
+        span.setAttribute('session.id', metadata.sessionId);
+        span.setAttribute('gen_ai.conversation.id', metadata.sessionId);
+    }
+    if (metadata.userId)
+        span.setAttribute('user.id', metadata.userId);
+    if (metadata.taskId)
+        span.setAttribute('a2a.task_id', metadata.taskId);
+    if (metadata.stage)
+        span.setAttribute('syndicate.stage', metadata.stage);
+    if (metadata.configHash)
+        span.setAttribute('syndicate.config_hash', metadata.configHash);
+    span.setAttribute('engine.version', engineVersion());
+    span.setAttribute('telemetry.schema_version', TELEMETRY_SCHEMA_VERSION);
+    for (const [key, value] of Object.entries(metadata.attributes ?? {})) {
+        span.setAttribute(key, value);
+    }
+    metadata.onSpanStart?.({
+        traceId: span.spanContext().traceId,
+        spanId: span.spanContext().spanId,
+    });
     let totalInputTokens = 0;
     let totalOutputTokens = 0;
     let totalThinkingTokens = 0;
     let outputText = '';
+    let invocationId = '';
+    let respondingAgent = '';
+    let errorCode = '';
+    let errorMessage = '';
     const ctx = trace.setSpan(context.active(), span);
     try {
         const wrappedStream = {
@@ -117,6 +342,13 @@ export async function* traceAgentRun(stream, metadata) {
             }
         };
         for await (const event of wrappedStream) {
+            const ev = event;
+            if (!invocationId && typeof ev.invocationId === 'string')
+                invocationId = ev.invocationId;
+            if ((ev.errorCode || ev.errorMessage) && ev.errorCode !== 'STOP') {
+                errorCode = String(ev.errorCode ?? 'ERROR');
+                errorMessage = String(ev.errorMessage ?? '');
+            }
             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
@@ -137,6 +369,8 @@ export async function* traceAgentRun(stream, metadata) {
                     const p = part;
                     if (p.text && !p.thought) {
                         outputText += p.text;
+                        if (ev.author)
+                            respondingAgent = String(ev.author);
                     }
                     if (p.functionCall) {
                         span.addEvent('ToolCall', {
@@ -169,6 +403,31 @@ export async function* traceAgentRun(stream, metadata) {
         span.setAttribute('syndicate.tokens.output', totalOutputTokens);
         span.setAttribute('syndicate.tokens.thinking', totalThinkingTokens);
         span.setAttribute('syndicate.output', outputText);
+        if (invocationId)
+            span.setAttribute('adk.invocation_id', invocationId);
+        if (respondingAgent)
+            span.setAttribute('syndicate.agent', respondingAgent);
+        if (errorCode) {
+            span.setAttribute('syndicate.error.code', errorCode);
+            span.setAttribute('syndicate.error.message', errorMessage.slice(0, 2000));
+        }
+        turnContexts.delete(span.spanContext().traceId);
+        const stats = takeTraceStats(span.spanContext().traceId);
+        if (stats) {
+            span.setAttribute('syndicate.latency.model_ms', Math.round(stats.modelMs));
+            span.setAttribute('syndicate.latency.tool_ms', Math.round(stats.toolMs));
+            span.setAttribute('syndicate.llm_calls', stats.llmCalls);
+            span.setAttribute('syndicate.models', [...stats.models].sort().join(','));
+        }
+        try {
+            for (const [key, value] of Object.entries(metadata.onEnd?.() ?? {})) {
+                if (value !== undefined)
+                    span.setAttribute(key, value);
+            }
+        }
+        catch {
+            /* a consumer's onEnd must never break the span */
+        }
         span.end();
     }
 }
@@ -189,6 +448,26 @@ export async function* traceLlmGeneration(meta, inner) {
     const span = tracer.startSpan('llm.request');
     span.setAttribute('llm.provider', meta.provider);
     span.setAttribute('llm.model', meta.model);
+    // OpenTelemetry GenAI semantic conventions alongside the llm.* names, so
+    // an OTLP backend (Phoenix, Langfuse, Tempo) reads these spans natively.
+    span.setAttribute('gen_ai.system', meta.provider);
+    span.setAttribute('gen_ai.request.model', meta.model);
+    const agent = agentForSpan(span.spanContext().spanId);
+    if (agent) {
+        span.setAttribute('llm.agent', agent);
+        span.setAttribute('gen_ai.agent.name', agent);
+    }
+    const turn = turnContexts.get(span.spanContext().traceId);
+    if (turn) {
+        if (turn.sessionId) {
+            span.setAttribute('session.id', turn.sessionId);
+            span.setAttribute('gen_ai.conversation.id', turn.sessionId);
+        }
+        if (turn.userId)
+            span.setAttribute('user.id', turn.userId);
+        if (turn.taskId)
+            span.setAttribute('a2a.task_id', turn.taskId);
+    }
     let inputTokens = 0;
     let outputTokens = 0;
     let thinkingTokens = 0;
@@ -229,6 +508,8 @@ export async function* traceLlmGeneration(meta, inner) {
         span.setAttribute('llm.tokens.input', inputTokens);
         span.setAttribute('llm.tokens.output', outputTokens);
         span.setAttribute('llm.tokens.thinking', thinkingTokens);
+        span.setAttribute('gen_ai.usage.input_tokens', inputTokens);
+        span.setAttribute('gen_ai.usage.output_tokens', outputTokens);
         // llm.latency_ms mirrors the span duration for the flat adk_telemetry row.
         span.end();
     }

package/dist/scripts/a2a_server.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
 import express from 'express';
 import { collectGrounding, describeGrounding, newGroundingState, webSourcesLine } from "../lib/grounding.js";
 import rateLimit from 'express-rate-limit';
@@ -8,13 +10,13 @@ import { loadEnv } from "../lib/loadEnv.js";
 import { DefaultRequestHandler, InMemoryTaskStore } from '@a2a-js/sdk/server';
 import { AsyncLocalStorage } from 'async_hooks';
 import { agentCardHandler, jsonRpcHandler, restHandler, UserBuilder } from '@a2a-js/sdk/server/express';
-import { Runner, LlmAgent, AgentTool, InMemorySessionService, getFunctionCalls, getFunctionResponses, setLogLevel, LogLevel } from '@google/adk';
+import { Runner, InMemorySessionService, getFunctionCalls, getFunctionResponses, setLogLevel, LogLevel } from '@google/adk';
 import { loadSyndicate } from "../lib/loadSyndicate.js";
 import { isDispatchSyndicate, matchRouteOverride, resolveRoute } from "../lib/dispatch.js";
 import { traceAgentRun } from "../lib/observability/tracer.js";
+import { configDigest } from "../lib/observability/lineage.js";
 import { resolveModel } from "../lib/models/registry.js";
-import { resolveTools as resolveNamedTools } from "../lib/toolRegistry.js";
-import { createMcpTools } from "../lib/tools/mcpToolFactory.js";
+import { compileGraph as compileGraphShared, compileSubagent as compileSubagentShared } from "../lib/compile.js";
 import { hasSupabaseCredentials, createSupabaseServices } from "../lib/persistence/supabaseProvider.js";
 import { ProjectedSessionService, renderTranscriptDigest } from "../lib/session/transcript.js";
 const requestContextStorage = new AsyncLocalStorage();
@@ -108,11 +110,24 @@ class SyndicateExecutor {
     config;
     sessionService;
     memoryService;
+    /** Provenance stamp for every turn this executor serves (lineage.ts). */
+    configHash;
     constructor(config, sessionService, memoryService) {
         this.config = config;
         this.sessionService = sessionService;
         this.memoryService = memoryService;
     }
+    configHashFor() {
+        if (!this.configHash) {
+            try {
+                this.configHash = configDigest(this.config, (ref) => loadSyndicate(ref));
+            }
+            catch {
+                this.configHash = 'unhashable';
+            }
+        }
+        return this.configHash;
+    }
     /**
      * Run ONE agent for ONE turn against a named session, draining its event
      * stream. DELEGATE mode calls this once (the orchestrator); PLAN-DISPATCH
@@ -136,16 +151,36 @@ class SyndicateExecutor {
             newMessage: { role: 'user', parts: userParts },
             ...(this.config.max_steps !== undefined ? { maxSteps: this.config.max_steps } : {})
         });
+        let combinedText = '';
+        let lastToolResultText = '';
+        const invokedToolNames = new Set();
+        // The DELEGATE relay-fallback predicate, evaluated by the tracer in its
+        // finally (after the last event) so the turn row records whether the
+        // orchestrator's relay failed. Same rule as the substitution below.
+        const normalizeName = (s) => s.replace(/[^a-z0-9]/gi, '').toLowerCase();
+        const relayFallbackFired = () => {
+            const text = combinedText.trim();
+            const echoed = text.length > 0 && [...invokedToolNames].some((n) => normalizeName(n) === normalizeName(text));
+            return (!text || echoed) && !!lastToolResultText;
+        };
         if (params.trace) {
             stream = traceAgentRun(stream, {
                 syndicateName: this.config.syndicate_name || 'melchizedek-syndicate',
                 bindings: this.config.variables || {},
-                input: userParts
+                input: userParts,
+                route: params.route,
+                // Identity: the CONVERSATION id (contextId), not the classifier's
+                // throwaway lane — every stage of one turn shares session/task ids.
+                sessionId: contextId,
+                userId,
+                taskId,
+                stage: params.stage,
+                configHash: this.configHashFor(),
+                onEnd: () => ({
+                    'syndicate.relay_fallback': params.stage === 'delegate' && relayFallbackFired(),
+                }),
             });
         }
-        let combinedText = '';
-        let lastToolResultText = '';
-        const invokedToolNames = new Set();
         let lastTokenTotal = 0;
         let lastThinkingTokens = 0;
         let error;
@@ -307,71 +342,19 @@ class SyndicateExecutor {
                 apiKey: authContext.apiKey,
                 defaultProvider: authContext.provider,
             });
-            const resolveTools = (toolNames = []) => resolveNamedTools(toolNames, (name) => console.warn(`[A2A] WARNING: Unknown tool '${name}' — skipping.`));
-            // Compile ADK Nodes dynamically.
-            //
-            // compileSubagent builds ONE runnable agent from a subagent entry. In
-            // DELEGATE mode compileGraph wraps its result in an AgentTool; in
-            // PLAN-DISPATCH the same agent is run directly as the chosen route, so
-            // both methods dispatch to identical agents and can never drift.
-            const compileSubagent = async (subCfg) => {
-                if (subCfg.yaml_reference) {
-                    console.log(`[A2A] Loading nested syndicate: ${subCfg.yaml_reference}`);
-                    const nestedConfig = loadSyndicate(subCfg.yaml_reference);
-                    return compileGraph(nestedConfig, subCfg.name, subCfg.description);
-                }
-                const subTools = resolveTools(subCfg.tools);
-                if (subCfg.mcp_server_url) {
-                    console.log(`[A2A] Loading MCP tools: ${subCfg.mcp_server_url}`);
-                    const mcpTools = await createMcpTools(subCfg.mcp_server_url);
-                    for (const mcpTool of mcpTools) {
-                        if (!subTools.some(t => t.name === mcpTool.name)) {
-                            subTools.push(mcpTool);
-                        }
-                    }
-                }
-                return new LlmAgent({
-                    name: subCfg.name,
-                    description: subCfg.description,
-                    model: resolveModelForRequest(subCfg.model),
-                    instruction: subCfg.instruction,
-                    tools: subTools.length > 0 ? subTools : undefined,
-                    outputSchema: subCfg.outputSchema,
-                    generateContentConfig: {
-                        ...subCfg.generateContentConfig,
-                        toolConfig: {
-                            ...subCfg.generateContentConfig?.toolConfig,
-                            includeServerSideToolInvocations: true
-                        }
-                    }
-                });
-            };
-            const compileGraph = async (configObj, overrideName, overrideDesc) => {
-                // PLAN-DISPATCH: the orchestrator gets NO subagent tools. ADK refuses
-                // to combine outputSchema with AgentTool delegation on one agent (see
-                // config/agents/critic.yaml), and the classifier needs the schema —
-                // code, not the model, performs the hand-off.
-                const compiledTools = isDispatchSyndicate(configObj)
-                    ? []
-                    : await Promise.all((configObj.subagents || []).map(async (subCfg) => new AgentTool({ agent: await compileSubagent(subCfg) })));
-                const orchestratorDirectTools = resolveTools(configObj.orchestrator.tools);
-                compiledTools.push(...orchestratorDirectTools);
-                return new LlmAgent({
-                    name: overrideName || configObj.orchestrator.name,
-                    description: overrideDesc || configObj.orchestrator.description,
-                    model: resolveModelForRequest(configObj.orchestrator.model),
-                    instruction: configObj.orchestrator.instruction,
-                    tools: compiledTools.length > 0 ? compiledTools : undefined,
-                    outputSchema: configObj.orchestrator.outputSchema,
-                    generateContentConfig: {
-                        ...configObj.orchestrator.generateContentConfig,
-                        toolConfig: {
-                            ...configObj.orchestrator.generateContentConfig?.toolConfig,
-                            includeServerSideToolInvocations: true
-                        }
-                    }
-                });
+            // Compile ADK nodes through the shared compiler (lib/compile.ts) — the
+            // observatory runs the same function, so the graph an eval measures is
+            // the graph this server serves. compileSubagent builds ONE runnable
+            // agent from a subagent entry; in DELEGATE mode compileGraph wraps it in
+            // an AgentTool, in PLAN-DISPATCH the same agent is run directly as the
+            // chosen route, so both methods dispatch to identical agents.
+            const compileOpts = {
+                resolveModel: resolveModelForRequest,
+                onUnknownTool: (name) => console.warn(`[A2A] WARNING: Unknown tool '${name}' — skipping.`),
+                log: (message) => console.log(`[A2A] ${message}`),
             };
+            const compileSubagent = (subCfg) => compileSubagentShared(subCfg, compileOpts);
+            const compileGraph = (configObj) => compileGraphShared(configObj, compileOpts);
             const ensureSession = async (sessionId) => {
                 const existing = await this.sessionService.getSession({
                     sessionId,
@@ -479,7 +462,8 @@ class SyndicateExecutor {
                         taskId,
                         contextId,
                         eventBus,
-                        trace: false, // one cheap classification — not worth a span
+                        trace: true, // one row per classification: misroutes are diagnosable from stored data
+                        stage: 'classify',
                         publishToolStatus: false, // a dispatch classifier holds no tools
                         sessionService: routerSessions
                     });
@@ -528,7 +512,9 @@ class SyndicateExecutor {
                     contextId,
                     eventBus,
                     trace: true,
+                    stage: 'dispatch',
                     publishToolStatus: true,
+                    route: resolution,
                     sessionService: new ProjectedSessionService(this.sessionService, routeCfg.name)
                 });
                 if (turn.error) {
@@ -558,6 +544,7 @@ class SyndicateExecutor {
                     contextId,
                     eventBus,
                     trace: true,
+                    stage: 'delegate',
                     publishToolStatus: true
                 });
                 if (turn.error) {
@@ -990,8 +977,31 @@ export async function startServer(syndicateName = 'syndicate.yaml') {
         console.log(`[A2A] Exposer server boot complete on port ${PORT}`);
     });
 }
-if (import.meta.url === `file://${process.argv[1]}`) {
-    // Running as a script
+// Run-as-main guard. Compare against the REALPATH of argv[1]: when invoked
+// through the npm bin (`npx melchizedek-serve`), argv[1] is the .bin symlink
+// while import.meta.url is the resolved file — a naive string compare never
+// matches and the server silently does nothing (the 0.9.0 bin bug).
+const invokedAsMain = (() => {
+    if (!process.argv[1])
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+    }
+    catch {
+        return import.meta.url === `file://${process.argv[1]}`;
+    }
+})();
+if (invokedAsMain) {
     const syndicateFile = process.argv[2] || 'syndicate.yaml';
-    startServer(syndicateFile).catch(console.error);
+    startServer(syndicateFile).catch((error) => {
+        if (error?.code === 'ENOENT' && !process.argv[2]) {
+            // Package consumers rarely have a syndicate.yaml — name the fix.
+            console.error('[A2A] No default syndicate.yaml in your agents directory.\n' +
+                '      Pass your syndicate: melchizedek-serve <name>.yaml\n' +
+                '      (agents directory: option --, MELCHIZEDEK_AGENTS_DIR, or <cwd>/config/agents)');
+            process.exit(1);
+        }
+        console.error(error);
+        process.exit(1);
+    });
 }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "melchizedek-agents",
-  "version": "0.9.0",
-  "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.",
+  "version": "0.9.3",
+  "description": "A multi-model, multi-agent orchestration framework on Google ADK \u2014 YAML-defined syndicates, Supabase session persistence, pgvector long-term memory. Companion repo to the lyceumagents.com curriculum.",
   "type": "module",
   "license": "MIT",
-  "//": "adk + genai are pinned exact in dev: newer genai minors change response part shapes and silently break the chat printer. Bump deliberately, verify a live run, then update the pin. adk itself is a PEER dependency — the consumer's app owns the ADK instance so the model registry is a singleton.",
+  "//": "adk + genai are pinned exact in dev: newer genai minors change response part shapes and silently break the chat printer. Bump deliberately, verify a live run, then update the pin. adk itself is a PEER dependency \u2014 the consumer's app owns the ADK instance so the model registry is a singleton.",
   "engines": {
     "node": ">=22.0.0"
   },
@@ -57,6 +57,7 @@
     "syndicate:librarian": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate librarian",
     "syndicate:scriptorium": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate scriptorium",
     "syndicate:cartographers": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate cartographers",
+    "syndicate:augustin": "node --disable-warning=DEP0040 --experimental-strip-types scripts/syndicate_chat.ts --syndicate augustin",
     "demo:models": "node --disable-warning=DEP0040 --experimental-strip-types scripts/demo_model_optionality.ts",
     "demo:direct": "node --disable-warning=DEP0040 --experimental-strip-types scripts/direct_call.ts",
     "mcp:demo": "node --disable-warning=DEP0040 --experimental-strip-types scripts/demo_mcp_server.ts",
@@ -66,7 +67,10 @@
     "start:a2a": "node --disable-warning=DEP0040 --experimental-strip-types scripts/a2a_server.ts",
     "test": "node --disable-warning=DEP0040 --experimental-strip-types --test tests/**/*.test.ts",
     "memory": "node --disable-warning=DEP0040 --experimental-strip-types scripts/memory_admin.ts",
-    "db:purge": "node --disable-warning=DEP0040 --experimental-strip-types scripts/purge_supabase.ts"
+    "db:purge": "node --disable-warning=DEP0040 --experimental-strip-types scripts/purge_supabase.ts",
+    "telemetry:stats": "node --disable-warning=DEP0040 --experimental-strip-types scripts/telemetry_admin.ts stats",
+    "telemetry:prune": "node --disable-warning=DEP0040 --experimental-strip-types scripts/telemetry_admin.ts prune",
+    "telemetry:replay": "node --disable-warning=DEP0040 --experimental-strip-types scripts/telemetry_admin.ts replay"
   },
   "peerDependencies": {
     "@google/adk": "^1.3.0"
@@ -77,6 +81,7 @@
     "@google/genai": "2.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.221.0",
     "@opentelemetry/resources": "^2.7.1",
     "@opentelemetry/sdk-trace-base": "^2.7.1",
     "@opentelemetry/sdk-trace-node": "^2.7.1",