melchizedek-agents 0.9.3 → 0.9.5

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/lib/tools/inspectImageTool.js

@@ -20,7 +20,7 @@ import { FunctionTool } from '@google/adk';
 import { GoogleGenAI } from '@google/genai';
 import { readFileSync } from 'node:fs';
 import { resolve, extname, sep } from 'node:path';
-const VISION_MODEL = 'gemini-3.7-flash';
+const VISION_MODEL = 'gemini-3.8-flash';
 const INVENTORY_PROTOCOL = `You are a blind visual inventory agent. You know NOTHING about what this image was supposed to be, who requested it, or why. Enumerate ONLY what is actually present:
 
 1. SUBJECTS — every distinct subject and object, with EXACT counts.

package/dist/lib/wiki/agentRun.d.ts

@@ -11,7 +11,7 @@
  *   three call sites can't drift.
  *
  *   Model routing goes through lib/models/registry.ts, so the YAML-style
- *   model string ('gemini-3.7-flash', 'claude-*', 'ollama/*'…) picks the
+ *   model string ('gemini-3.8-flash', 'claude-*', 'ollama/*'…) picks the
  *   provider — wiki operations inherit the framework's full model
  *   optionality. A missing provider key degrades to a clear error string;
  *   nothing here throws for want of credentials.

package/dist/lib/wiki/agentRun.js

@@ -11,7 +11,7 @@
  *   three call sites can't drift.
  *
  *   Model routing goes through lib/models/registry.ts, so the YAML-style
- *   model string ('gemini-3.7-flash', 'claude-*', 'ollama/*'…) picks the
+ *   model string ('gemini-3.8-flash', 'claude-*', 'ollama/*'…) picks the
  *   provider — wiki operations inherit the framework's full model
  *   optionality. A missing provider key degrades to a clear error string;
  *   nothing here throws for want of credentials.

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>;