melchizedek-agents 0.9.2 → 0.9.4

package/dist/scripts/a2a_server.js

@@ -10,19 +10,46 @@ 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();
 const A2A_APP_NAME = 'melchizedek-a2a';
 /** X-User-Id must be short and filesystem/key-safe; anything else is rejected. */
 const SITE_USER_ID_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+/** X-Surface-* values obey the same charset rule, for the same reason. */
+const SURFACE_VALUE_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+const SURFACE_HEADERS = [
+    ['x-surface', 'name'],
+    ['x-surface-guild', 'guild'],
+    ['x-surface-channel', 'channel'],
+    ['x-surface-user', 'user'],
+];
+/**
+ * Root-span attributes for the caller's surface. Absent headers produce no
+ * attributes at all, so a caller that names nothing writes NULLs rather than
+ * a row full of 'unknown' — an unnamed surface and a surface named 'unknown'
+ * are different facts and the ledger should not conflate them.
+ */
+function surfaceAttributes(ctx) {
+    const s = ctx?.surface;
+    if (!s)
+        return {};
+    const attrs = { 'surface.name': s.name };
+    if (s.guild)
+        attrs['surface.guild'] = s.guild;
+    if (s.channel)
+        attrs['surface.channel'] = s.channel;
+    if (s.user)
+        attrs['surface.user'] = s.user;
+    return attrs;
+}
 /**
  * Memory/session silo derivation.
  * Base silo: a hash of the caller's API key (one bucket per credential).
@@ -105,16 +132,50 @@ function publishWorking(eventBus, taskId, contextId, text) {
         final: false
     });
 }
+/** One human-readable line naming WHY a turn failed, for the failed task's
+ *  status message — the text the Discord surface renders verbatim. Provider
+ *  errors sometimes arrive as a raw JSON blob (Gemini ApiError:
+ *  `{"error":{"code":503,"message":"...","status":"UNAVAILABLE"}}`), so the
+ *  inner message is dug out before falling back to the string itself. An
+ *  empty message keeps the old pointer at the server logs. */
+export function describeTurnError(error) {
+    let msg = (error.message ?? '').trim();
+    if (msg.startsWith('{')) {
+        try {
+            const parsed = JSON.parse(msg);
+            const inner = parsed?.error?.message ?? parsed?.message;
+            if (typeof inner === 'string' && inner.trim())
+                msg = inner.trim();
+        }
+        catch { /* not JSON — use as-is */ }
+    }
+    if (!msg)
+        return 'see server logs for details.';
+    return msg.length > 300 ? `${msg.slice(0, 297)}...` : msg;
+}
 // ── Native ADK AgentExecutor Bridge ───────────────────────────────────────
 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
@@ -138,16 +199,37 @@ 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(),
+                attributes: surfaceAttributes(requestContextStorage.getStore()),
+                onEnd: () => ({
+                    'syndicate.relay_fallback': params.stage === 'delegate' && relayFallbackFired(),
+                }),
             });
         }
-        let combinedText = '';
-        let lastToolResultText = '';
-        const invokedToolNames = new Set();
         let lastTokenTotal = 0;
         let lastThinkingTokens = 0;
         let error;
@@ -309,71 +391,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,
@@ -481,7 +511,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
                     });
@@ -530,11 +561,13 @@ class SyndicateExecutor {
                     contextId,
                     eventBus,
                     trace: true,
+                    stage: 'dispatch',
                     publishToolStatus: true,
+                    route: resolution,
                     sessionService: new ProjectedSessionService(this.sessionService, routeCfg.name)
                 });
                 if (turn.error) {
-                    failTask(`Error: [${turn.error.code}] ${resolution.route} failed to answer. See server logs for details.`);
+                    failTask(`Error: [${turn.error.code}] ${resolution.route} failed to answer — ${describeTurnError(turn.error)}`);
                     return;
                 }
                 tokenInfo = turn.tokenInfo;
@@ -560,10 +593,11 @@ class SyndicateExecutor {
                     contextId,
                     eventBus,
                     trace: true,
+                    stage: 'delegate',
                     publishToolStatus: true
                 });
                 if (turn.error) {
-                    failTask(`Error: [${turn.error.code}] The agent run failed. See server logs for details.`);
+                    failTask(`Error: [${turn.error.code}] The agent run failed — ${describeTurnError(turn.error)}`);
                     return;
                 }
                 tokenInfo = turn.tokenInfo;
@@ -809,7 +843,30 @@ export async function startServer(syndicateName = 'syndicate.yaml') {
             }
             siteUserId = rawUserId;
         }
-        requestContextStorage.run({ apiKey, provider, siteUserId }, () => {
+        // X-Surface-* (optional): where this request came from, for telemetry
+        // only. Same validation as X-User-Id, and a bad value is refused rather
+        // than dropped — a silently ignored header makes a dashboard lie about
+        // coverage. `X-Surface` is required for the others to mean anything.
+        let surface;
+        for (const [header, field] of SURFACE_HEADERS) {
+            const raw = req.headers[header];
+            if (raw === undefined || raw === '')
+                continue;
+            if (!SURFACE_VALUE_PATTERN.test(raw)) {
+                res.status(400).json({ error: `Invalid ${header}: must match [A-Za-z0-9._-]{1,64}` });
+                return;
+            }
+            if (field === 'name') {
+                surface = { name: raw };
+                continue;
+            }
+            if (!surface) {
+                res.status(400).json({ error: `${header} requires X-Surface to name the surface` });
+                return;
+            }
+            surface[field] = raw;
+        }
+        requestContextStorage.run({ apiKey, provider, siteUserId, surface }, () => {
             next();
         });
     });

package/dist/scripts/syndicate_chat.js

@@ -5,7 +5,7 @@ import { join } from 'node:path';
 import { loadSyndicate, parseCliBindings } from "../lib/loadSyndicate.js";
 import { traceAgentRun } from "../lib/observability/tracer.js";
 // ADK Imports
-import { LlmAgent, Runner, InMemorySessionService, getFunctionCalls, getFunctionResponses, AgentTool, setLogLevel, LogLevel } from '@google/adk';
+import { LlmAgent, Runner, InMemorySessionService, getFunctionCalls, getFunctionResponses, AgentTool, setLogLevel, LogLevel, StreamingMode } from '@google/adk';
 import { randomUUID } from 'node:crypto';
 // Tool resolution (shared registry) + MCP factory
 import { resolveTools as resolveNamedTools } from "../lib/toolRegistry.js";
@@ -94,6 +94,12 @@ function banner(config, persistence, bindings = {}, sessionId) {
 }
 async function main() {
     loadEnv(import.meta.url);
+    // Interactive chat is for reading the agent, not its telemetry: the
+    // [OTEL_SPAN_JSON] lines are off here unless OTEL_CONSOLE_SPANS is set
+    // (in .env, which loadEnv() has just read, or in the shell). Spans still
+    // reach the in-process listeners and the Supabase sink either way.
+    if (process.env.OTEL_CONSOLE_SPANS === undefined)
+        process.env.OTEL_CONSOLE_SPANS = 'false';
     // ── Register LLM providers ───────────────────────────────────────────────
     // WHY: Must run AFTER loadEnv() so that API keys from .env are available.
     // One call registers every adapter whose credentials exist (Ollama needs
@@ -119,14 +125,17 @@ async function main() {
             break;
         }
     }
-    // Define syndicate variable bindings
-    const bindings = {
-        headline_count: 3,
-        current_date: new Date().toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' })
-    };
-    // Merge CLI overrides on top (--bind/--bindings flags win)
-    const cliBindings = parseCliBindings(argv);
-    const mergedBindings = { ...bindings, ...cliBindings };
+    // ONLY what the caller actually asked for on the command line.
+    //
+    // WHY nothing is seeded here: loadSyndicate merges these OVER a syndicate's
+    // own `variables:` block, so a hardcoded default is not a fallback — it is
+    // an override applied to every syndicate. `headline_count: 3` used to ride
+    // along into unrelated agents (a Tutor turn announced it in the banner and
+    // recorded it in syndicate.bindings telemetry) while silently beating the
+    // 5 that syndicate.yaml declares for itself. Universal tokens belong to
+    // defaultBindings() in lib/loadSyndicate.ts, which the loader applies UNDER
+    // the YAML — that is where current_date lives, timezone-pinned.
+    const mergedBindings = parseCliBindings(argv);
     // Load the syndicate definition
     const config = loadSyndicate(syndicateFile, {
         bindings: mergedBindings,
@@ -162,6 +171,9 @@ async function main() {
     // people) — otherwise every CLI session shares the 'local-user' bucket.
     const SESSION_USER_ID = process.env.MELCHIZEDEK_USER_ID?.trim() || 'local-user';
     const SESSION_ID = randomUUID();
+    // Live token-by-token output. Off gives one block per turn — useful when
+    // piping a transcript, or for an agent whose reply is structured JSON.
+    const STREAM_REPLIES = process.env.CHAT_STREAMING !== 'false';
     // ── Detect persistence mode ──────────────────────────────────────────────
     const persistence = detectPersistenceConfig(config.memory_system);
     // ── Tool resolver ─────────────────────────────────────────────────────────
@@ -327,7 +339,13 @@ async function main() {
             let stream = runner.runAsync({
                 userId: SESSION_USER_ID,
                 sessionId: SESSION_ID,
-                newMessage: { role: 'user', parts: [{ text: trimmed }] }
+                newMessage: { role: 'user', parts: [{ text: trimmed }] },
+                // SSE makes the adapters emit display-only partials as tokens
+                // land, so thinking and the reply appear as they are produced
+                // rather than in one block when the call returns.
+                runConfig: {
+                    streamingMode: STREAM_REPLIES ? StreamingMode.SSE : StreamingMode.NONE
+                }
             });
             stream = traceAgentRun(stream, {
                 syndicateName: config.syndicate_name || 'melchizedek-syndicate',
@@ -335,7 +353,13 @@ async function main() {
                 input: trimmed
             });
             let currentMode = 'none';
+            // Under SSE the reply arrives as partials and is then REPEATED whole
+            // on the final event — the one ADK persists to session history. Show
+            // the partials, skip the repeat. With streaming off nothing is
+            // partial, so this stays false and every event prints as before.
+            let streamedText = false;
             for await (const event of stream) {
+                const isPartial = event.partial === true;
                 const calls = getFunctionCalls(event);
                 if (calls && calls.length > 0) {
                     for (const call of calls) {
@@ -371,6 +395,8 @@ async function main() {
                             process.stdout.write(c.dim + part.text + c.reset);
                         }
                         else if (part.text) {
+                            if (!isPartial && streamedText)
+                                continue;
                             if (currentMode === 'thinking') {
                                 console.log(`\n\n${c.magenta}${c.bold}${event.author}${c.reset} › `);
                                 currentMode = 'text';
@@ -380,6 +406,8 @@ async function main() {
                                 currentMode = 'text';
                             }
                             process.stdout.write(part.text);
+                            if (isPartial)
+                                streamedText = true;
                         }
                         else if (part.inlineData) {
                             // WHY: Image generation models return binary data as base64-encoded
@@ -396,6 +424,9 @@ async function main() {
                         }
                     }
                 }
+                // A complete event ends the turn; the next one starts fresh.
+                if (!isPartial)
+                    streamedText = false;
             }
             console.log('\n');
         }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "melchizedek-agents",
-  "version": "0.9.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.",
+  "version": "0.9.4",
+  "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"
   },
@@ -67,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"
@@ -78,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",