melchizedek-agents 0.9.3 → 0.9.5

package/dist/scripts/a2a_server.js

@@ -23,6 +23,33 @@ 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,6 +132,27 @@ 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;
@@ -176,6 +224,7 @@ class SyndicateExecutor {
                 taskId,
                 stage: params.stage,
                 configHash: this.configHashFor(),
+                attributes: surfaceAttributes(requestContextStorage.getStore()),
                 onEnd: () => ({
                     'syndicate.relay_fallback': params.stage === 'delegate' && relayFallbackFired(),
                 }),
@@ -518,7 +567,7 @@ class SyndicateExecutor {
                     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;
@@ -548,7 +597,7 @@ class SyndicateExecutor {
                     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;
@@ -794,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,6 +1,6 @@
 {
   "name": "melchizedek-agents",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "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",