melchizedek-agents 0.9.3 → 0.9.4

package/AGENT_SETUP.md

@@ -81,7 +81,7 @@ After the agent reports back:
 Keyless, if you installed Ollama:
 
 ```bash
-npm run syndicate:tutor       # one open-weight agent: paste material, be taught
+npm run syndicate:tutor       # one open-weight agent: name a topic or paste material, be taught
 npm run syndicate:council     # advocate/skeptic council, all local
 ```
 
@@ -179,7 +179,7 @@ Deploying the server itself (Heroku, Fly, a VPS) needs `PUBLIC_URL` set
 — at which point the server refuses to start without the bearer secret,
 by design. Run `db/hardening.sql` before real user data arrives, and
 read the deployment notes in `lib/memory/README.md` end to end. The
-patient in module 2.05's specimen would expect no less of you.
+patient in module 2.02's specimen would expect no less of you.
 
 ## 5. When your agents outgrow the clone
 

package/DOCUMENTATION.md

@@ -331,8 +331,10 @@ Anthropic extended thinking (thinking + tool use on the same Claude
 agent is not supported yet).
 
 Every model request also emits an `llm.request` OpenTelemetry span
-(provider, model, input/output/thinking tokens, latency) printed as an
-`[OTEL_SPAN_JSON]` line; set `TELEMETRY_SUPABASE=true` to persist
+(provider, model, input/output/thinking tokens, latency). Scripts print it
+as an `[OTEL_SPAN_JSON]` line; `melchizedek-chat` and the `syndicate:*`
+scripts keep those lines off unless `OTEL_CONSOLE_SPANS=true`. Set
+`TELEMETRY_SUPABASE=true` to persist
 spans to the `adk_telemetry` table (run `db/telemetry.sql`, then
 re-run `db/hardening.sql` — schema below):
 

package/QUICKSTART.md

@@ -180,8 +180,9 @@ const config = loadSyndicate('mine.yaml');    // reads <your-repo>/config/agents
 
 - Read a syndicate the way the course does: start with
   `config/agents/examples/tutor.yaml` and map its instruction blocks —
-  identity, doctrine, communication laws, boundaries — then see the
-  same anatomy grown to full size in `patient_advocate.yaml`.
+  identity, communication style, task, examples — then see the
+  anatomy grown to full size, with doctrines and boundaries, in
+  `patient_advocate.yaml`.
 - The interactive curriculum walks every pattern in this repo:
   [lyceumagents.com/curriculum](https://lyceumagents.com/curriculum/).
 - Author your own syndicate: everything in `config/agents/examples/` is

package/README.md

@@ -5,7 +5,7 @@ Agent Development Kit — where the entire shape of an agent system is one
 readable file.**
 
 Melchizedek runs hierarchical agent graphs called *Syndicates*: an
-orchestrator, its subagents, their tools, models, and communication laws,
+orchestrator, its subagents, their tools, models, and communication styles,
 all declared in a single YAML document you can read, diff, and teach
 from. The engine (`lib/`) knows no syndicate by name — `config/agents/`
 is where YOUR syndicates go, and the ones shipped in
@@ -95,17 +95,17 @@ worked specimen for a curriculum module:
 | Syndicate | Pattern | Course module |
 |---|---|---|
 | `tutor.yaml` — Tutor | one open-weight agent, no keys; the instruction block anatomy | [1.02 · running your own model](https://lyceumagents.com/curriculum/your-own-model/) |
-| `council.yaml` — Council | first orchestration, fully local: advocate/skeptic council | [2.03 · workflows & voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
-| `critic.yaml` — Critic Review | Drafter → Critic confidence loop; quality as a parsed field | [2.02 · testing & refinement](https://lyceumagents.com/curriculum/testing-and-refinement/) |
-| `delegation.yaml` — Router | triage to specialists; descriptions as the routing API | [2.03 · workflows & voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
-| `hierarchical.yaml` — Decomposer | split one goal, delegate parts, merge | [2.03 · workflows & voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
-| `style_council.yaml` — Style Council | identical knowledge, three engineered voices | [2.03 · workflows & voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
-| `syndicate.yaml` — Global Synthesis Council | orchestrator + research subagent; grounding as architecture | [2.04 · the protocol](https://lyceumagents.com/curriculum/melchizedek-protocol/) |
-| `ares.yaml` — Knowledge Keeper | long-term memory pipeline, exercised | [2.05 · memory systems](https://lyceumagents.com/curriculum/memory-systems/) |
-| `patient_advocate.yaml` — Patient Advocate | memory doctrine: preload + recall, trends, the silent record | [2.05 · memory systems](https://lyceumagents.com/curriculum/memory-systems/) |
-| `librarian.yaml` — Lyceum Librarian | MCP: tools discovered at runtime; the agent fetches and modifies catalog data | [2.06 · MCP](https://lyceumagents.com/curriculum/mcp-extending-reach/) |
-| `image_production.yaml` — Image Production | spec-first generation + blind inventory / spec audit | [2.07 · multi-modal agents](https://lyceumagents.com/curriculum/multimodal-agents/) |
-| `augustin.yaml` — Augustin | multi-agent, multi-modal fact-checking: X sweep + web verification under a tool-free arbiter | [2.08 · the fact-checking arbiter](https://lyceumagents.com/curriculum/fact-checking-agent/) |
+| `council.yaml` — Council | first orchestration, fully local: advocate/skeptic council | [1.05 · workflows & voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
+| `critic.yaml` — Critic Review | Drafter → Critic confidence loop; quality as a parsed field | [1.04 · testing & refinement](https://lyceumagents.com/curriculum/testing-and-refinement/) |
+| `delegation.yaml` — Router | triage to specialists; descriptions as the routing API | [1.05 · workflows & voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
+| `hierarchical.yaml` — Decomposer | split one goal, delegate parts, merge | [1.05 · workflows & voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
+| `style_council.yaml` — Style Council | identical knowledge, three engineered voices | [1.05 · workflows & voice](https://lyceumagents.com/curriculum/workflows-and-voice/) |
+| `syndicate.yaml` — Global Synthesis Council | orchestrator + research subagent; grounding as architecture | [2.01 · the protocol](https://lyceumagents.com/curriculum/melchizedek-protocol/) |
+| `ares.yaml` — Knowledge Keeper | long-term memory pipeline, exercised | [2.02 · memory systems](https://lyceumagents.com/curriculum/memory-systems/) |
+| `patient_advocate.yaml` — Patient Advocate | memory doctrine: preload + recall, trends, the silent record | [2.02 · memory systems](https://lyceumagents.com/curriculum/memory-systems/) |
+| `librarian.yaml` — Lyceum Librarian | MCP: tools discovered at runtime; the agent fetches and modifies catalog data | [2.03 · MCP](https://lyceumagents.com/curriculum/mcp-extending-reach/) |
+| `image_production.yaml` — Image Production | spec-first generation + blind inventory / spec audit | [2.04 · multi-modal agents](https://lyceumagents.com/curriculum/multimodal-agents/) |
+| `augustin.yaml` — Augustin | multi-agent, multi-modal fact-checking: X sweep + web verification under a tool-free arbiter | [2.05 · the fact-checking arbiter](https://lyceumagents.com/curriculum/fact-checking-agent/) |
 | `claude.yaml` — Claude Chat | minimal single-agent config; the multi-model adapter in one file | — |
 | `model_zoo.yaml` — Model Zoo | one lightweight agent per provider (Qwen/Claude/Grok/GPT/Gemini); model optionality proven by `npm run demo:models` | — |
 | `scriptorium.yaml` — The Scriptorium | agents over the shipped knowledge bundle: query with citations, author through a validated save gate | — |
@@ -131,7 +131,7 @@ your own.
   corrections supersede old records, which are kept as linked history.
 - **Native tools** — web search, image generation, and a blind
   image-inventory tool whose file-path-only signature makes expectation
-  bias structurally impossible (see module 2.07).
+  bias structurally impossible (see module 2.04).
 - **A2A service mode** — serve any syndicate as a JSON-RPC
   agent-to-agent endpoint with bearer auth and rate limiting
   (`npm run start:a2a`).

package/config/agents/examples/cartographers.yaml

@@ -62,11 +62,11 @@ orchestrator:
         - Never record a relation the Surveyor did not propose with evidence, and never repair a rejection by inventing a different claim — send it back to the Surveyor to re-read.
       </tool_doctrine>
 
-      <communication_laws>
+      <communication_style>
         Report relations the way they read: "&lt;source&gt; constrains &lt;target&gt; — because '&lt;quotation&gt;'".
         Say plainly when a proposal was rejected and why the gate rejected it. A refused edge is the system working.
         Be concrete: node ids, relation names, document paths. No speculation about what the graph might contain.
-      </communication_laws>
+      </communication_style>
 
       <strict_constraints>
         - Structural relations are DERIVED, never asserted. If a visitor asks you to record who calls a tool or which model an agent runs on, say that the build already knows it and point at wiki_graph.

package/config/agents/examples/council.yaml

@@ -2,7 +2,7 @@
 # Council — basic orchestration on open weights
 # ============================================================
 #
-# WHY: The curriculum's first multi-agent specimen (module 2.03).
+# WHY: The curriculum's first multi-agent specimen (module 1.05).
 # Three agents, zero tools, zero keys — every model is a local
 # ollama/qwen3:8b (lib/models/ollamaLlm.ts), so the user's first
 # orchestration runs entirely on their own machine.

package/config/agents/examples/librarian.yaml

@@ -46,10 +46,10 @@ orchestrator:
         - For requests that change the catalog (borrowing, annotating), state what you are about to change, delegate the change, then confirm what the Librarian reports back — including any refusal.
       </tool_doctrine>
 
-      <communication_laws>
+      <communication_style>
         Answer first, provenance second: give the patron the fact, then name the scroll or catalog entry it came from.
         Keep responses short and concrete — titles, authors, statuses, dates. A librarian points; they do not lecture.
-      </communication_laws>
+      </communication_style>
 
       <strict_constraints>
         - Never claim a write succeeded without the Librarian's confirmation of the new state.

package/config/agents/examples/patient_advocate.yaml

@@ -49,14 +49,14 @@ orchestrator:
         - Track TRENDS, not just values: a creatinine of 1.4 mg/dL means one thing alone and another thing as the third rise in a row.
       </memory_doctrine>
 
-      <communication_laws>
+      <communication_style>
         LEAD WITH SUBSTANCE: The direct answer or the most critical safety information goes in the very first sentence. Never open with filler — no "That's a great question", no "I'm sorry to hear that", no restating what the user just told you.
         SCANNABLE LAYOUTS: Use bold headers, short bulleted lists, and blockquotes for critical warnings so the user can read you instantly while standing in a hospital room. Dense, structured, skimmable.
         SPECIFICS OVER GENERALITIES: Concrete data, physiological timelines, precise anatomy. Define every medical term contextually inline the first time it appears — "hypokalemia (low potassium)" — then use it freely.
         ACTIONABLE SCRIPTS: Whenever a medical decision, complication, or communication gap arises, provide an exact, word-for-word script the user can say to the attending doctor or nurse to firmly and respectfully advocate for proper care. Format scripts as blockquotes.
         RED FLAGS VS NORMAL: When discussing symptoms or recovery, explicitly separate "normal / expected" from "emergency red flags" that mean push the call button, call the doctor tonight, or go to the ER. Never leave the user guessing which bucket they are in.
         INTERACTIVE COACHING: End every response with exactly one highly relevant follow-up question or observation that moves the strategy forward. Proactively flag systemic hurdles — weekend staffing gaps, shift changes, discharge pressure, results that post to the portal before anyone calls — and coach the user on navigating them.
-      </communication_laws>
+      </communication_style>
 
       <research_doctrine>
         Delegate to your MedScribe subagent for anything that must be current or sourced: treatment guidelines, drug information and interactions, typical recovery timelines, what a test measures, emerging research. Anchor searches to {{current_date}}.

package/config/agents/examples/scriptorium.yaml

@@ -51,10 +51,10 @@ orchestrator:
         - For writes: state what you are about to have recorded, delegate, then confirm what the Illuminator reports back — including a rejection by the save gate.
       </tool_doctrine>
 
-      <communication_laws>
+      <communication_style>
         Answer first, provenance second: give the visitor the substance, then the bundle paths it came from.
         Keep responses concrete — paths, titles, statuses, dates. A scriptorium points at pages; it does not orate.
-      </communication_laws>
+      </communication_style>
 
       <strict_constraints>
         - Never claim a document was written or changed without the Illuminator's confirmation naming the path.

package/config/agents/examples/style_council.yaml

@@ -3,9 +3,9 @@
 # ============================================================
 #
 # WHY: A teaching syndicate built for lyceumagents.com curriculum
-# module 2.03 (Agent workflows & conversation styles). One router
-# conducts three stylists with IDENTICAL knowledge and different
-# communication laws. Ask the same question of all three and the
+# module 1.05 (Agent workflows & conversation styles). One router
+# conducts three stylists with IDENTICAL knowledge and a different
+# communication style. Ask the same question of all three and the
 # answers differ only in register — proving that an agent's voice
 # is authored in its instruction, not emergent from the model.
 #

package/config/agents/examples/tutor.yaml

@@ -2,23 +2,30 @@
 # Tutor — the open-weight single agent
 # ============================================================
 #
-# WHY: The curriculum's first specimen (Part 1, module 1.02). One
+# WHY: The curriculum's first specimen (Part 1, module 1.03). One
 # agent, no subagents, no tools, no API key — the model is an
 # open-weight qwen3:8b served locally by Ollama, so the whole
 # system runs on the user's own machine (lib/models/ollamaLlm.ts).
 #
-# The persona is a tutor in the plainest sense: it teaches the
-# material the user supplies by questioning, not lecturing.
-# Its purpose is deliberately narrow, and that narrowness is the
-# lesson: a general model becomes an instrument when a prompt
-# commits it to one purpose.
+# The persona is a tutor in the plainest sense: it teaches
+# whatever the user brings, a topic named in a sentence or
+# material pasted into the conversation, by questioning rather
+# than lecturing. Pasted material, when there is any, is ground
+# truth; without it the Tutor teaches from what is well
+# established and says when it is unsure. Its purpose is
+# deliberately narrow, and that narrowness is the lesson: a
+# general model becomes an instrument when a prompt commits it
+# to one purpose, and the prompt shapes HOW it teaches, not
+# whether it may.
 #
-# The instruction demonstrates the block anatomy taught in the
-# curriculum: <system_identity>, <grounding_doctrine>,
-# <communication_laws>, <safety_boundaries>. More capable agents
-# add more blocks (see patient_advocate.yaml: a memory system
-# brings a <memory_doctrine>, a research subagent brings a
-# <research_doctrine>). Blocks follow capabilities.
+# The instruction is written in four blocks, the shape the
+# curriculum teaches first: <system_identity> (who the agent is
+# and its one purpose), <communication_style> (how it speaks,
+# as countable rules), <execution_framework> (a procedure it runs on
+# every turn: read, evaluate the user's state, adapt), and <examples> (one
+# worked exchange per state, so the model has a concrete target
+# for each branch of the framework). Later specimens grow more blocks
+# as they gain capabilities (see patient_advocate.yaml).
 #
 # Run it:  npm run syndicate:tutor   (requires only Ollama +
 #          `ollama pull qwen3:8b` — no keys, no database)
@@ -33,31 +40,54 @@ orchestrator:
   instruction: |
     <prompt_instructions>
       <system_identity>
-        You are the Tutor — a teacher who leads by questioning, not lecturing; understanding is reached, not received.
-        The user brings you material they are trying to master — an article, lecture notes, documentation, a contract, a textbook passage — pasted directly into the conversation.
-        Your single purpose: walk the user through the material they supplied until they genuinely understand it. You are not a general assistant; requests outside teaching the supplied material get redirected to it.
+        You are the Tutor. You teach whatever the user brings: a topic named in a sentence, or material pasted into the conversation, whether an article, lecture notes, documentation, a contract, or a textbook passage. You lead by questioning rather than lecturing, so that understanding is reached instead of received. You are not a general assistant; you teach, and a request to do something else is turned back into a lesson. When the user has pasted material, it is your ground truth: when you bring in something it does not say, label it "beyond your text:", and when it is silent on something, say so plainly rather than inventing a quote, a page reference, or a figure. When there is no material, teach from what is well established about the topic, and when you are not sure of a figure, a date, a name, or a quotation, say you are not sure rather than supplying one.
       </system_identity>
 
-      <grounding_doctrine>
-        The pasted material is your ground truth for every substantive claim.
-        - Before teaching, confirm what material you have: name its topic in one line so the user can catch a mispaste.
-        - Ground every explanation in the supplied text. When you bring in outside context to aid understanding, label it: "beyond your text:".
-        - If the material is silent on something the user asks, say "your material doesn't cover this" — then answer from general knowledge only if the user wants it, still labeled.
-        - Never invent quotes, page references, or figures that are not in the material.
-      </grounding_doctrine>
+      <communication_style>
+        Plain, warm, and brief. One idea per turn, never a lecture and never a numbered plan. Define every technical term inline the first time it appears, as in "amortization (paying a debt down on a schedule)", then use it freely. Never name your own rules, number your steps, or label the parts of a reply; the user reads teaching, not the scaffolding behind it. End every reply with exactly one short question that walks the material one step further, and let that question be the only question mark in the reply.
+      </communication_style>
 
-      <communication_laws>
-        ASK BEFORE TELLING: open each new topic with one question that draws out what the user already makes of the relevant passage — then stop and wait.
-        WALKING PACE: one idea or one question per turn, never a lecture. Depth beats coverage.
-        PLAIN TERMS FIRST: define every technical term inline the first time it appears — "amortization (paying a debt down on a schedule)" — then use it freely.
-        EARNED ANSWERS: questions are the path, not a wall. After the user has made two honest attempts, state the idea plainly and point to where their material says it.
-        SOCRATIC CLOSE: end every response with exactly one short question that walks the material one step further.
-      </communication_laws>
+      <execution_framework>
+        On the first turn, decide first which of two cases the message is, and stay in that case:
+        PASTED MATERIAL: the message contains text to be taught from, such as a passage, notes, or an article, whatever the user says about it. Do three things and nothing else: name the material's topic in one line, subject only and never what it concludes, so a mispaste is caught at once; ask one question that draws out what the user already makes of the passage; and stop. Never state the key idea, the main takeaway, or the conclusion of pasted material in that first turn, even when the user asks for it directly. A request to be told the answer before any attempt is not frustration; it is where the teaching starts, and it gets a question, not the answer.
+        TOPIC ONLY: the message names a subject and contains no material. Do three things and nothing else: give one plain sentence that says what the subject is, a definition and no more; ask one question that draws out what the user already pictures about it; and stop. Do not ask for material, and do not cover the topic.
 
-      <safety_boundaries>
-        - You teach the material; you do not act on it. For decisions with real stakes (medical, legal, financial), teach what the text says and direct the user to the professional who can advise on it.
-        - When you are uncertain, say so plainly. A confident wrong answer teaches a falsehood with authority — the worst failure a tutor has.
-      </safety_boundaries>
+        On every later turn, in this order:
+        1. Read the user's latest message. Read the earlier history only as far as you need it, most recent turns first.
+        2. Decide which one of three states the user is in:
+           MISUNDERSTANDING: their reading conflicts with what the material says, or, with no material, with what is established about the topic.
+           CORRECT: their reading matches it.
+           FRUSTRATION: they are stuck, annoyed, or asking to be told the answer.
+        3. Adapt your reply to that state:
+           On a misunderstanding, do not correct it outright. Point to the sentence in the material that bears on it, or, with no material, state the one fact that bears on it, and ask one question that lets the user find the gap themselves.
+           On a correct reading, say so in one line, then ask one question that moves one step deeper into the material.
+           On frustration, acknowledge it in one line, then hand over the tools for the answer: quote the passage that holds it and name the idea inside it, or, with no material, state the idea in one or two plain sentences. After the user has made two honest attempts at a point, state the idea plainly and point to where their material says it.
+        Guardrails: never give more than one idea per turn; never answer the question you just asked; never summarize the whole material or the whole topic unprompted; with pasted material, never state a conclusion the user has not reached until they have made two honest attempts at it. For material with real stakes (medical, legal, financial), teach what the text says and direct the user to the professional who can advise on it.
+      </execution_framework>
+
+      <examples>
+        Material: a paragraph explaining that compound interest is interest computed on both the principal and the interest already accrued. User: "Here is my passage. Teach me the key idea in it."
+        State: first turn, pasted material.
+        Tutor: "Your passage is about compound interest. Before I say anything about it, what do you make of the phrase 'interest already accrued'?"
+
+        No material. User: "teach me about inflation"
+        State: first turn, topic only.
+        Tutor: "Inflation is a general rise in prices across an economy over time, so the same money buys a little less than it did before. Before we go further, what do you think makes prices rise in the first place?"
+
+        Material: a paragraph explaining that compound interest is interest computed on both the principal and the interest already accrued.
+
+        User: "So compound interest just means a higher rate than simple interest."
+        State: misunderstanding.
+        Tutor: "Look again at the phrase 'interest already accrued' in your passage. If the rate never changed, what is it about the second year's calculation that makes the total grow faster than the first year's?"
+
+        User: "Oh, the second year's interest is computed on a bigger amount, because last year's interest got added in."
+        State: correct.
+        Tutor: "Exactly, and that is the whole mechanism. Your passage mentions the compounding period, so what would change if interest were added monthly instead of yearly?"
+
+        User: "I've tried twice and I still don't get it. Just tell me."
+        State: frustration.
+        Tutor: "That is a fair ask after two tries, so here it is plainly: your passage says interest is computed on the principal plus the interest already accrued, which means each period's interest is calculated on a slightly larger base than the last. Reading that sentence now, which word tells you the base is growing?"
+      </examples>
     </prompt_instructions>
   generateContentConfig:
     temperature: 0.6

package/dist/lib/models/claudeLlm.js

@@ -102,7 +102,7 @@ export class ClaudeLlm extends BaseLlm {
      * llm.request OpenTelemetry span (provider/model/tokens/latency).
      */
     async *generateContentAsync(llmRequest, stream = false) {
-        yield* traceLlmGeneration({ provider: 'anthropic', model: this.model }, this.generateInner(llmRequest, stream));
+        yield* traceLlmGeneration({ provider: 'anthropic', model: this.model, llmRequest }, this.generateInner(llmRequest, stream));
     }
     async *generateInner(llmRequest, stream) {
         const apiKey = this.apiKey || process.env.ANTHROPIC_API_KEY;
@@ -254,9 +254,15 @@ export class ClaudeLlm extends BaseLlm {
                         }
                     }
                 }
-                // Final message: tool_use blocks, thinking stash, and token usage.
+                // Final message: full text, tool_use blocks, thinking stash, usage.
+                //
+                // WHY includeText is true even though the text was just streamed:
+                // ADK's runner persists only NON-partial events, so a final without
+                // text would render the reply on screen and lose it from session
+                // history — the next turn would have no record the model answered.
+                // Printers drop text on a turnComplete event they already streamed.
                 const final = await streamResponse.finalMessage();
-                yield this.finalResponse(final, /*includeText=*/ false);
+                yield this.finalResponse(final, /*includeText=*/ true);
             }
             else {
                 // Non-streaming path

package/dist/lib/models/gptLlm.js

@@ -243,7 +243,7 @@ export class GptLlm extends BaseLlm {
     }
     // ── Generation ─────────────────────────────────────────────────────────────
     async *generateContentAsync(llmRequest, stream = false) {
-        yield* traceLlmGeneration({ provider: this.providerId(), model: this.model }, this.generateInner(llmRequest, stream));
+        yield* traceLlmGeneration({ provider: this.providerId(), model: this.model, llmRequest }, this.generateInner(llmRequest, stream));
     }
     async *generateInner(llmRequest, stream) {
         const apiKey = this.apiKey || this.apiKeyFromEnv();

package/dist/lib/models/ollamaLlm.js

@@ -109,7 +109,7 @@ export class OllamaLlm extends OpenAiCompatibleLlm {
     httpError(status, detail) {
         return {
             errorCode: 'OLLAMA_HTTP_ERROR',
-            errorMessage: `Ollama returned ${status}: ${detail.slice(0, 400)}. Is the model pulled? Try: ollama pull ${this.wireModelName()}`,
+            errorMessage: `Ollama returned ${status}: ${detail.slice(0, 4000)}. Is the model pulled? Try: ollama pull ${this.wireModelName()}`,
         };
     }
     unreachable(message) {

package/dist/lib/models/openAiCompatibleLlm.d.ts

@@ -66,6 +66,33 @@ export declare function splitThinkBlocks(text: string): {
     reasoning: string;
     answer: string;
 };
+/**
+ * Incremental counterpart to splitThinkBlocks, for the SSE path.
+ *
+ * WHY a state machine rather than the regex: on a stream the closing
+ * `</think>` has usually NOT arrived yet, so the regex matches nothing and
+ * the whole scratchpad would be printed as the reply. A tag can also be
+ * split mid-delta ("<thi" + "nk>"), so any tail that could still grow into
+ * a tag is held back instead of being emitted as answer text.
+ *
+ * Providers that report reasoning in a discrete field (Ollama's
+ * `delta.reasoning`, others' `reasoning_content`) never open a think block
+ * and pass straight through this untouched.
+ */
+export declare class ThinkStreamSplitter {
+    private inThink;
+    private held;
+    /** Routes one content delta into reasoning/answer text. */
+    push(chunk: string): {
+        reasoning: string;
+        answer: string;
+    };
+    /** Releases the held tail; the stream ended, so it was never a tag. */
+    flush(): {
+        reasoning: string;
+        answer: string;
+    };
+}
 export declare abstract class OpenAiCompatibleLlm extends BaseLlm {
     private webSearchWarned;
     /** Provider id for telemetry, e.g. 'ollama', 'xai'. */
@@ -79,6 +106,11 @@ export declare abstract class OpenAiCompatibleLlm extends BaseLlm {
     /** Provider-specific request body fields (merged last). */
     /** Whether the endpoint accepts response_format json_schema (strict). */
     protected supportsJsonSchemaFormat(): boolean;
+    /**
+     * Whether the endpoint honors stream_options.include_usage. Without it an
+     * SSE turn reports no token counts at all; Ollama and xAI both support it.
+     */
+    protected supportsStreamUsage(): boolean;
     protected extraBodyFields(_llmRequest: LlmRequest): Record<string, unknown>;
     /**
      * Body fields enabling the provider's NATIVE web search, or null when the
@@ -107,6 +139,21 @@ export declare abstract class OpenAiCompatibleLlm extends BaseLlm {
     protected unreachable(message: string): LlmResponse;
     generateContentAsync(llmRequest: LlmRequest, stream?: boolean): AsyncGenerator<LlmResponse, void>;
     private generateInner;
+    /**
+     * SSE path: display-only partials as the tokens land, then ONE final
+     * non-partial response carrying the complete text, tool calls and usage.
+     *
+     * WHY the final repeats text already streamed: ADK's runner persists only
+     * non-partial events (`if (!event.partial) appendEvent(...)`), so a final
+     * without text would show the reply on screen and lose it from session
+     * history. Printers therefore skip text on a turnComplete event whose
+     * partials they already rendered — see scripts/syndicate_chat.ts.
+     *
+     * Thinking is deliberately NOT carried on the final: the scratchpad is
+     * display-only and stays out of history, which is what keeps it from
+     * being replayed to the model on the next turn.
+     */
+    private streamResponse;
     /** ADK Contents (Google GenAI format) → OpenAI-compatible chat messages. */
     protected buildMessages(llmRequest: LlmRequest): OpenAiMessage[];
     /** ADK toolsDict → OpenAI function-tool definitions (lowercase schemas). */

package/dist/lib/models/openAiCompatibleLlm.js

@@ -42,6 +42,101 @@ export function splitThinkBlocks(text) {
         .trimStart();
     return { reasoning: blocks.join('\n\n'), answer };
 }
+const OPEN_THINK = '<think>';
+const CLOSE_THINK = '</think>';
+/** Length of the longest suffix of `s` that is a proper prefix of `tag`. */
+function partialTagSuffix(s, tag) {
+    const max = Math.min(s.length, tag.length - 1);
+    for (let n = max; n > 0; n--) {
+        if (s.endsWith(tag.slice(0, n)))
+            return n;
+    }
+    return 0;
+}
+/**
+ * Incremental counterpart to splitThinkBlocks, for the SSE path.
+ *
+ * WHY a state machine rather than the regex: on a stream the closing
+ * `</think>` has usually NOT arrived yet, so the regex matches nothing and
+ * the whole scratchpad would be printed as the reply. A tag can also be
+ * split mid-delta ("<thi" + "nk>"), so any tail that could still grow into
+ * a tag is held back instead of being emitted as answer text.
+ *
+ * Providers that report reasoning in a discrete field (Ollama's
+ * `delta.reasoning`, others' `reasoning_content`) never open a think block
+ * and pass straight through this untouched.
+ */
+export class ThinkStreamSplitter {
+    inThink = false;
+    held = '';
+    /** Routes one content delta into reasoning/answer text. */
+    push(chunk) {
+        let buf = this.held + chunk;
+        let reasoning = '';
+        let answer = '';
+        for (;;) {
+            const tag = this.inThink ? CLOSE_THINK : OPEN_THINK;
+            const at = buf.indexOf(tag);
+            if (at === -1)
+                break;
+            if (this.inThink)
+                reasoning += buf.slice(0, at);
+            else
+                answer += buf.slice(0, at);
+            buf = buf.slice(at + tag.length);
+            this.inThink = !this.inThink;
+        }
+        // Hold back only what could still become the tag we're watching for.
+        const pending = this.inThink ? CLOSE_THINK : OPEN_THINK;
+        const keep = partialTagSuffix(buf, pending);
+        this.held = keep > 0 ? buf.slice(buf.length - keep) : '';
+        const emit = keep > 0 ? buf.slice(0, buf.length - keep) : buf;
+        if (this.inThink)
+            reasoning += emit;
+        else
+            answer += emit;
+        return { reasoning, answer };
+    }
+    /** Releases the held tail; the stream ended, so it was never a tag. */
+    flush() {
+        const rest = this.held;
+        this.held = '';
+        return this.inThink
+            ? { reasoning: rest, answer: '' }
+            : { reasoning: '', answer: rest };
+    }
+}
+/** Yields parsed `data:` payloads from an SSE response body. */
+async function* sseChunks(res) {
+    const reader = res.body?.getReader?.();
+    if (!reader)
+        return;
+    const decoder = new TextDecoder();
+    let buf = '';
+    for (;;) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        buf += decoder.decode(value, { stream: true });
+        let nl;
+        while ((nl = buf.indexOf('\n')) !== -1) {
+            const line = buf.slice(0, nl).trim();
+            buf = buf.slice(nl + 1);
+            // Blank separators and ":" keep-alive comments carry no payload.
+            if (!line.startsWith('data:'))
+                continue;
+            const payload = line.slice('data:'.length).trim();
+            if (payload === '[DONE]')
+                return;
+            try {
+                yield JSON.parse(payload);
+            }
+            catch {
+                /* a chunk that isn't valid JSON is not worth killing the turn for */
+            }
+        }
+    }
+}
 // ── OpenAiCompatibleLlm ──────────────────────────────────────────────────────
 export class OpenAiCompatibleLlm extends BaseLlm {
     webSearchWarned = false;
@@ -54,6 +149,13 @@ export class OpenAiCompatibleLlm extends BaseLlm {
     supportsJsonSchemaFormat() {
         return true;
     }
+    /**
+     * Whether the endpoint honors stream_options.include_usage. Without it an
+     * SSE turn reports no token counts at all; Ollama and xAI both support it.
+     */
+    supportsStreamUsage() {
+        return true;
+    }
     extraBodyFields(_llmRequest) {
         return {};
     }
@@ -86,7 +188,7 @@ export class OpenAiCompatibleLlm extends BaseLlm {
     httpError(status, detail) {
         return {
             errorCode: `${this.providerId().toUpperCase()}_HTTP_ERROR`,
-            errorMessage: `${this.providerId()} returned ${status}: ${detail.slice(0, 400)}`,
+            errorMessage: `${this.providerId()} returned ${status}: ${detail.slice(0, 4000)}`,
         };
     }
     /** Error response when the endpoint can't be reached at all. */
@@ -98,9 +200,9 @@ export class OpenAiCompatibleLlm extends BaseLlm {
     }
     // ── Generation ─────────────────────────────────────────────────────────────
     async *generateContentAsync(llmRequest, stream = false) {
-        yield* traceLlmGeneration({ provider: this.providerId(), model: this.model }, this.generateInner(llmRequest, stream));
+        yield* traceLlmGeneration({ provider: this.providerId(), model: this.model, llmRequest }, this.generateInner(llmRequest, stream));
     }
-    async *generateInner(llmRequest, _stream) {
+    async *generateInner(llmRequest, stream) {
         const missing = this.missingRequirement();
         if (missing) {
             yield missing;
@@ -112,12 +214,24 @@ export class OpenAiCompatibleLlm extends BaseLlm {
         const body = {
             model: this.wireModelName(),
             messages,
-            stream: false,
+            stream,
+            // SSE reports token usage only if asked, in a final choices-less chunk.
+            ...(stream && this.supportsStreamUsage()
+                ? { stream_options: { include_usage: true } }
+                : {}),
             ...(cfg.temperature !== undefined ? { temperature: cfg.temperature } : {}),
             ...(cfg.topP !== undefined ? { top_p: cfg.topP } : {}),
             ...(cfg.maxOutputTokens !== undefined
                 ? { max_tokens: cfg.maxOutputTokens }
                 : {}),
+            // Reasoning budget. Qwen3-family models think before answering, and on
+            // a constraint-dense prompt they can spend the whole budget doing it
+            // and return an empty turn. Ollama's OpenAI-compatible endpoint honors
+            // `reasoning_effort` and IGNORES the native `think` field, so this is
+            // the only lever on this path. Opt-in per agent; omitted = unchanged.
+            ...(cfg.reasoningEffort !== undefined
+                ? { reasoning_effort: cfg.reasoningEffort }
+                : {}),
             ...(openAiTools.length > 0 ? { tools: openAiTools } : {}),
             // Structured output: an ADK outputSchema becomes a strict json_schema
             // response_format where the endpoint supports it (xAI does; Ollama's
@@ -157,6 +271,10 @@ export class OpenAiCompatibleLlm extends BaseLlm {
                 yield this.httpError(res.status, detail);
                 return;
             }
+            if (stream) {
+                yield* this.streamResponse(res);
+                return;
+            }
             const data = await res.json();
             const message = data.choices?.[0]?.message ?? {};
             const usageMetadata = mapUsage(data.usage);
@@ -201,6 +319,103 @@ export class OpenAiCompatibleLlm extends BaseLlm {
             yield this.unreachable(msg);
         }
     }
+    /**
+     * SSE path: display-only partials as the tokens land, then ONE final
+     * non-partial response carrying the complete text, tool calls and usage.
+     *
+     * WHY the final repeats text already streamed: ADK's runner persists only
+     * non-partial events (`if (!event.partial) appendEvent(...)`), so a final
+     * without text would show the reply on screen and lose it from session
+     * history. Printers therefore skip text on a turnComplete event whose
+     * partials they already rendered — see scripts/syndicate_chat.ts.
+     *
+     * Thinking is deliberately NOT carried on the final: the scratchpad is
+     * display-only and stays out of history, which is what keeps it from
+     * being replayed to the model on the next turn.
+     */
+    async *streamResponse(res) {
+        const splitter = new ThinkStreamSplitter();
+        const toolCalls = new Map();
+        let answer = '';
+        let answerStarted = false;
+        let usage;
+        const partial = (text, thought) => ({
+            content: {
+                role: 'model',
+                parts: [thought ? { text, thought: true } : { text }],
+            },
+            partial: true,
+        });
+        // The scratchpad is usually trailed by blank lines; the reply must not
+        // open with them, but only the FIRST answer text may be trimmed.
+        const openAnswer = (text) => answerStarted ? text : text.trimStart();
+        for await (const chunk of sseChunks(res)) {
+            if (chunk.usage)
+                usage = chunk.usage;
+            const delta = chunk.choices?.[0]?.delta;
+            if (!delta)
+                continue;
+            // Reasoning as a discrete field (Ollama `reasoning`, others
+            // `reasoning_content`) — already separated, no tag parsing needed.
+            const fieldReasoning = delta.reasoning ?? delta.reasoning_content ?? '';
+            if (fieldReasoning)
+                yield partial(fieldReasoning, true);
+            if (typeof delta.content === 'string' && delta.content) {
+                const split = splitter.push(delta.content);
+                if (split.reasoning)
+                    yield partial(split.reasoning, true);
+                if (split.answer) {
+                    const text = openAnswer(split.answer);
+                    if (text) {
+                        answerStarted = true;
+                        answer += text;
+                        yield partial(text, false);
+                    }
+                }
+            }
+            // Tool arguments arrive as fragments keyed by index, not whole.
+            for (const call of delta.tool_calls ?? []) {
+                const index = call.index ?? 0;
+                const acc = toolCalls.get(index) ?? { args: '' };
+                if (call.id)
+                    acc.id = call.id;
+                if (call.function?.name)
+                    acc.name = call.function.name;
+                if (call.function?.arguments)
+                    acc.args += call.function.arguments;
+                toolCalls.set(index, acc);
+            }
+        }
+        const tail = splitter.flush();
+        if (tail.reasoning)
+            yield partial(tail.reasoning, true);
+        if (tail.answer) {
+            const text = openAnswer(tail.answer);
+            if (text) {
+                answer += text;
+                yield partial(text, false);
+            }
+        }
+        const parts = [];
+        if (answer)
+            parts.push({ text: answer });
+        for (const [, acc] of [...toolCalls.entries()].sort((a, b) => a[0] - b[0])) {
+            let args = {};
+            try {
+                args = JSON.parse(acc.args || '{}');
+            }
+            catch {
+                args = { raw: acc.args };
+            }
+            parts.push({ functionCall: { name: acc.name, args, id: acc.id } });
+        }
+        const usageMetadata = mapUsage(usage);
+        yield {
+            content: { role: 'model', parts },
+            turnComplete: true,
+            ...(usageMetadata ? { usageMetadata } : {}),
+        };
+    }
     // ── Translation helpers ────────────────────────────────────────────────────
     /** ADK Contents (Google GenAI format) → OpenAI-compatible chat messages. */
     buildMessages(llmRequest) {

package/dist/lib/models/registry.js

@@ -40,7 +40,7 @@ export class TracedGemini extends Gemini {
     // built-in Gemini entries instead of adding shadowed duplicates.
     static supportedModels = Gemini.supportedModels;
     async *generateContentAsync(llmRequest, stream) {
-        yield* traceLlmGeneration({ provider: 'gemini', model: this.model }, this.tagAndGenerate(llmRequest, stream));
+        yield* traceLlmGeneration({ provider: 'gemini', model: this.model, llmRequest }, this.tagAndGenerate(llmRequest, stream));
     }
     /** Tags the llm.request span (web_search = Gemini grounding), then
      *  delegates to ADK's Gemini. Runs inside the span context. */

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

@@ -65,6 +65,11 @@ export interface TurnRow {
     user_id: string | null;
     task_id: string | null;
     invocation_id: string | null;
+    /** Where the turn came from, when the caller named it (X-Surface-* headers). */
+    surface: string | null;
+    surface_guild: string | null;
+    surface_channel: string | null;
+    surface_user: string | null;
     syndicate: string;
     stage: string;
     agent: string | null;

package/dist/lib/observability/supabaseSpanExporter.js

@@ -105,7 +105,14 @@ export function isRootSpan(span) {
     return span.name.startsWith(ROOT_PREFIX);
 }
 export function isPayloadSpan(span) {
-    return span.name === 'call_llm' && scopeName(span) === ADK_SCOPE;
+    if (span.name === 'call_llm' && scopeName(span) === ADK_SCOPE)
+        return true;
+    // Errored calls: ADK's call_llm span is unreliable on error (its end() is
+    // skipped when the consumer stops at the error event, and traceCallLlm
+    // never ran for a thrown error), so traceLlmGeneration attaches the
+    // request + error body to its own llm.request span instead — but only on
+    // error, so clean turns never produce a second payload row.
+    return span.name === 'llm.request' && !!attrsOf(span)['llm.payload.response'];
 }
 /** `syndicate.input` is JSON.stringify of either a string or A2A parts. */
 export function parseInputText(raw) {
@@ -197,6 +204,10 @@ export function toTurnRow(span) {
         user_id: str(attrs, 'user.id'),
         task_id: str(attrs, 'a2a.task_id'),
         invocation_id: str(attrs, 'adk.invocation_id'),
+        surface: str(attrs, 'surface.name'),
+        surface_guild: str(attrs, 'surface.guild'),
+        surface_channel: str(attrs, 'surface.channel'),
+        surface_user: str(attrs, 'surface.user'),
         syndicate: syndicateOf(span) ?? 'unknown',
         stage: str(attrs, 'syndicate.stage') ?? 'delegate',
         agent: str(attrs, 'syndicate.agent'),
@@ -242,8 +253,8 @@ export function turnFacts(span) {
 /** Map an ADK call_llm span into an adk_payloads row. */
 export function toPayloadRow(span, reason, ttlDays, turn) {
     const attrs = attrsOf(span);
-    const request = str(attrs, 'gcp.vertex.agent.llm_request') ?? '';
-    const response = str(attrs, 'gcp.vertex.agent.llm_response') ?? '';
+    const request = str(attrs, 'gcp.vertex.agent.llm_request') ?? str(attrs, 'llm.payload.request') ?? '';
+    const response = str(attrs, 'gcp.vertex.agent.llm_response') ?? str(attrs, 'llm.payload.response') ?? '';
     const started = span.startTime[0] * 1000 + span.startTime[1] / 1e6;
     return {
         ts: new Date(started).toISOString(),

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

@@ -97,6 +97,14 @@ export interface LlmCallMeta {
     provider: string;
     /** The model id as declared in the agent YAML (e.g. 'ollama/qwen3:8b'). */
     model: string;
+    /**
+     * The full LlmRequest, attached to the span ONLY when the call errors.
+     * ADK's own call_llm payload capture is lost on error — the consumer stops
+     * pulling after the error event, so that span's end() (not in a finally)
+     * never runs and the exporter never sees it. This span always ends, so an
+     * errored call keeps its request + error body in adk_payloads regardless.
+     */
+    llmRequest?: unknown;
 }
 /**
  * Wraps one adapter `generateContentAsync` invocation in an `llm.request`

package/dist/lib/observability/tracer.js

@@ -68,6 +68,13 @@ export function onSpanEnd(listener) {
 // 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';
+// OTEL_CONSOLE_SPANS=false silences the [OTEL_SPAN_JSON] lines entirely.
+// The in-process listeners below still fire and the Supabase sink still
+// records, so this costs no telemetry — it only unclutters a chat session.
+// Read at export time rather than module load, so an entry point can set
+// its own default in main() (syndicate_chat.ts defaults to silent) after
+// loadEnv() has run and before the first span ends.
+const printConsoleSpans = () => process.env.OTEL_CONSOLE_SPANS !== 'false';
 function spanScopeName(span) {
     const s = span;
     return s.instrumentationScope?.name ?? s.instrumentationLibrary?.name ?? '';
@@ -83,6 +90,8 @@ class JsonConsoleExporter {
                     /* a listener bug must not break the export pipeline */
                 }
             }
+            if (!printConsoleSpans())
+                continue;
             if (!PRINT_ALL_SPANS && spanScopeName(span) === ADK_SCOPE)
                 continue;
             // Create a clean JSON representation of the span
@@ -101,7 +110,7 @@ class JsonConsoleExporter {
                 })),
                 status: span.status,
             };
-            // Print to stdout with a specific prefix so test_local.py can easily extract it
+            // Print to stdout with a fixed prefix so a wrapper can extract spans from a transcript
             console.log(`[OTEL_SPAN_JSON] ${JSON.stringify(jsonSpan)}`);
         }
         resultCallback({ code: ExportResultCode.SUCCESS });
@@ -367,7 +376,10 @@ export async function* traceAgentRun(stream, metadata) {
             if (event.content && event.content.parts) {
                 for (const part of event.content.parts) {
                     const p = part;
-                    if (p.text && !p.thought) {
+                    // Under SSE the reply streams as partials and is then repeated
+                    // whole on the final event. Count it once, from the final, or
+                    // syndicate.output records every answer twice.
+                    if (p.text && !p.thought && !ev.partial) {
                         outputText += p.text;
                         if (ev.author)
                             respondingAgent = String(ev.author);
@@ -409,7 +421,7 @@ export async function* traceAgentRun(stream, metadata) {
             span.setAttribute('syndicate.agent', respondingAgent);
         if (errorCode) {
             span.setAttribute('syndicate.error.code', errorCode);
-            span.setAttribute('syndicate.error.message', errorMessage.slice(0, 2000));
+            span.setAttribute('syndicate.error.message', errorMessage.slice(0, 4000));
         }
         turnContexts.delete(span.spanContext().traceId);
         const stats = takeTraceStats(span.spanContext().traceId);
@@ -432,6 +444,37 @@ export async function* traceAgentRun(stream, metadata) {
     }
 }
 const THINKING_EVENT_MAX_CHARS = 600;
+const ERROR_PAYLOAD_MAX_CHARS = 200_000;
+const ERROR_MESSAGE_MAX_CHARS = 4_000;
+/** JSON.stringify that never throws and never exceeds the cap. */
+function safePayloadJson(value) {
+    let json;
+    try {
+        json = JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        json = String(value);
+    }
+    return json.length > ERROR_PAYLOAD_MAX_CHARS
+        ? json.slice(0, ERROR_PAYLOAD_MAX_CHARS)
+        : json;
+}
+/**
+ * Providers throw errors whose message IS the API's JSON error body
+ * (Gemini: {"error":{"code":503,"message":...,"status":...}}). Pull the
+ * numeric code out so llm.error_code reads "503", not "THROWN".
+ */
+function refineErrorCode(code, message) {
+    try {
+        const parsed = JSON.parse(message);
+        if (parsed?.error?.code)
+            return String(parsed.error.code);
+    }
+    catch {
+        /* not a JSON body — keep the code we have */
+    }
+    return code;
+}
 /**
  * Wraps one adapter `generateContentAsync` invocation in an `llm.request`
  * span — one span per model call, for EVERY provider. Records provider,
@@ -472,6 +515,9 @@ export async function* traceLlmGeneration(meta, inner) {
     let outputTokens = 0;
     let thinkingTokens = 0;
     let thinkingPreview = '';
+    let errorCode = '';
+    let errorMessage = '';
+    let errorResponse;
     const ctx = trace.setSpan(context.active(), span);
     try {
         while (true) {
@@ -486,7 +532,9 @@ export async function* traceLlmGeneration(meta, inner) {
                 thinkingTokens = resp.usageMetadata.thoughtsTokenCount ?? thinkingTokens;
             }
             if (resp.errorCode) {
-                span.setAttribute('llm.error_code', resp.errorCode);
+                errorCode = String(resp.errorCode);
+                errorMessage = String(resp.errorMessage ?? '');
+                errorResponse = resp;
             }
             for (const part of resp.content?.parts ?? []) {
                 const p = part;
@@ -499,12 +547,27 @@ export async function* traceLlmGeneration(meta, inner) {
     }
     catch (error) {
         span.recordException(error);
+        // Gemini (and any adapter that throws instead of yielding an error
+        // response) lands here; the message is often the raw API error body.
+        errorMessage = error instanceof Error ? error.message : String(error);
+        errorCode = refineErrorCode(errorCode || 'THROWN', errorMessage);
+        errorResponse = { errorCode, errorMessage };
         throw error;
     }
     finally {
         if (thinkingPreview) {
             span.addEvent('llm.thinking', { 'thinking.preview': thinkingPreview });
         }
+        if (errorCode) {
+            span.setAttribute('llm.error_code', errorCode);
+            span.setAttribute('llm.error_message', errorMessage.slice(0, ERROR_MESSAGE_MAX_CHARS));
+            // Make this span a payload candidate (see supabaseSpanExporter's
+            // isPayloadSpan): the request as sent and the error as received.
+            if (meta.llmRequest !== undefined) {
+                span.setAttribute('llm.payload.request', safePayloadJson(meta.llmRequest));
+            }
+            span.setAttribute('llm.payload.response', safePayloadJson(errorResponse ?? { errorCode, errorMessage }));
+        }
         span.setAttribute('llm.tokens.input', inputTokens);
         span.setAttribute('llm.tokens.output', outputTokens);
         span.setAttribute('llm.tokens.thinking', thinkingTokens);

package/dist/scripts/a2a_server.d.ts

@@ -1,2 +1,12 @@
 #!/usr/bin/env node
+/** 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 declare function describeTurnError(error: {
+    code: string;
+    message: string;
+}): string;
 export declare function startServer(syndicateName?: string): Promise<void>;

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.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",