aegis-desktop 0.4.0 → 0.4.2

package/README.md

@@ -1,8 +1,49 @@
 # AEGIS Desktop
 
-Electron host — see the repo root [README.md](../README.md) for the full
-build/architecture reference. This file covers day-to-day usage details that
-don't belong in the top-level doc.
+A standalone Electron chat app over the [AEGIS](https://aegiscloud.org) API,
+with an **agentic tool loop**: the model can read, write, and edit files,
+list directories, glob, grep, run shell commands in a persistent session, and
+delegate whole sub-tasks to subagents. It does **not** require Claude Code.
+
+```bash
+npm install -g aegis-desktop
+aegis
+```
+
+## Model classes
+
+Pick any of four transports from the model-class picker, switchable
+mid-conversation with context intact:
+
+| Class | Transport | Key held in |
+|---|---|---|
+| **Aegis Cloud** | `aegiscloud.org` — one entry, **Nexus**; the pool auto-routes across whichever providers are live | main process |
+| **Ollama** | local `ollama` daemon | no key needed |
+| **Custom OpenAI-compatible** (LM Studio, OpenRouter, vLLM, …) | direct from the desktop app | main process — never sent to the renderer |
+| **Anthropic-compatible** (Claude, or any Messages-format gateway) | direct from the desktop app | main process |
+
+Get a free AEGIS key at **https://aegiscloud.org**, or use your own
+Ollama/OpenAI-compatible/Anthropic-compatible endpoint — no AEGIS account
+needed for those.
+
+## Tools available to the model
+
+| Tool | What it does |
+|---|---|
+| `readFile` · `writeFile` · `editFile` | File access scoped to the working directory |
+| `listDir` · `glob` · `grep` | Navigate and search a tree |
+| `exec` | Run commands in a persistent shell session |
+| `task` | Delegate a self-contained sub-task to a subagent |
+
+Before `exec`, `writeFile`, or `editFile` runs, a diff/approval card asks you
+to confirm — approve once, approve for the rest of the conversation, or deny.
+Flip **Settings → "Confirm before running tools"** off if you'd rather the
+agent run mutating tool calls without asking; it's on by default.
+
+Conversations persist locally and sync to AEGIS cloud memory via a pending
+queue that flushes on each "Sync now" or heartbeat retry. The **remember**
+button on any assistant reply pins that message to cross-machine memory —
+queued locally if you're offline.
 
 ## Keyboard shortcuts
 
@@ -45,6 +86,15 @@ accelerator is already claimed by another application, registration fails
 gracefully: a warning is logged to the main process console and the
 Quick Launcher card shows the reason instead of the app crashing or hanging.
 
+## Deep links
+
+The app registers an `aegis://` protocol handler:
+
+| Link | What it does |
+|---|---|
+| `aegis://open?session=<id>` | Resumes a saved session |
+| `aegis://new?prompt=<text>` | Starts a fresh chat with that prompt pre-filled |
+
 ## Run from source
 
 ```bash
@@ -53,9 +103,35 @@ npm install
 npm start
 ```
 
+## Build a distributable
+
+```bash
+npm run dist        # packaged app (AppImage / MSI+NSIS / dmg)
+npm run dist:dir    # unpacked dir, for quick testing
+```
+
 ## Checks
 
 ```bash
-npm run check          # node --check every main-process + renderer file
+npm run check                    # node --check every main-process + renderer file
 node ../test/desktop-shell.mjs   # headless IPC smoke test (no Electron binary needed)
 ```
+
+## Structure
+
+```
+main.js              Electron main process — window + IPC shell only
+preload.js           Context-isolated IPC bridge exposed to the renderer
+renderer/            UI (vanilla JS, no framework)
+lib/local/           Model classes, providers, agentic tool loop, prompt
+lib/sync/            Local session/memory persistence + sync queue
+vendor/aegis.js      The AEGIS transport client (thin — no engine logic)
+bin/aegis.js         `aegis` CLI entry point for the global npm install
+```
+
+This directory is part of the [aegiscode-plugin](../README.md) monorepo,
+which also ships a Claude Code plugin and the shared `client/aegis.js`
+transport over the same AEGIS backend — see the repo root for that fuller
+architecture picture. A read-only mirror of just this directory (for
+browsing or `git clone`) lives at
+[aegiscloud/aegiscode-desktop](https://github.com/aegiscloud/aegiscode-desktop).

package/lib/local/engine.js

@@ -123,23 +123,47 @@ function normalizeCatalog(models) {
 }
 
 /**
- * The Aegis Cloud catalog (`/api/v1/models`) also lists internal routing
- * aliases — per-provider variants like `openai-gpt4o-mini`/`anthropic-haiku`,
- * and six pooled-brain tier ids (`{aegis,nexus}-brain[-smart|-neo]`) that all
- * run the same worker pool on the same backend model. None of those are a
- * human's model choice; picking between them put six near-duplicate "brain"
- * entries in the desktop dropdown. Surface only the four platform models the
- * user actually selects between, plus one collapsed "Nexus" entry standing
- * in for whichever brain tier the pool advertises.
+ * The Aegis Cloud catalog (`/api/v1/models`) lists every backend the pool can
+ * reach: per-provider ids (`openai`, `anthropic`, `groq`, `gemini`, ...) and
+ * six pooled-brain tier ids (`{aegis,nexus}-brain[-smart|-neo]`) that all run
+ * the same worker pool on the same backend model. None of that is a human's
+ * model choice — which providers currently hold a valid key is an ops detail
+ * (today: deepseek/anthropic/groq; openai and gemini drift in and out), and
+ * surfacing it invites picking a provider that happens to be dead right now.
+ * The pool already auto-routes across whichever providers are live, so the
+ * desktop dropdown offers exactly one entry for the "aegis" class: the
+ * collapsed "Nexus" brain — never the raw provider list.
  */
-const AEGIS_PLATFORM_MODELS = Object.freeze(['openai', 'anthropic', 'groq', 'gemini']);
-const NEXUS_BRAIN_ID = 'aegis-brain';
-const NEXUS_LABEL = 'Nexus (Aegis brain)';
+const NEXUS_BRAIN_IDS = Object.freeze(['nexus-brain', 'aegis-brain']);
+const NEXUS_LABEL = 'Nexus';
+
+/**
+ * Pick the one entry standing in for the pooled brain. The server serves
+ * `nexus-brain` as the canonical tier (`hidden: false`, no `alias_of`) and
+ * marks every other spelling — `aegis-brain` and the `-smart`/`-neo` tiers —
+ * as `hidden: true, alias_of: "nexus-brain"`. Prefer the canonical id so the
+ * request travels on the name the server owns; fall back to the alias, then to
+ * any tier whose `alias_of` names the brain, so a renamed or trimmed catalog
+ * still resolves to something selectable instead of silently emptying the
+ * dropdown (the previous fixed-id lookup returned [] if `aegis-brain` was ever
+ * retired, leaving the class with no model to choose).
+ */
+function selectBrainEntry(models) {
+  return (
+    models.find((m) => NEXUS_BRAIN_IDS.includes(m.id) && !m.hidden && m.alias_of === undefined)
+    || models.find((m) => NEXUS_BRAIN_IDS.includes(m.id))
+    || models.find((m) => m.alias_of && NEXUS_BRAIN_IDS.includes(m.alias_of))
+    || null
+  );
+}
 
 function filterAegisCatalog(models) {
-  const platform = models.filter((m) => AEGIS_PLATFORM_MODELS.includes(m.id));
-  const nexus = models.find((m) => m.id === NEXUS_BRAIN_ID);
-  return nexus ? [...platform, { ...nexus, label: NEXUS_LABEL }] : platform;
+  const nexus = selectBrainEntry(models);
+  if (!nexus) return [];
+  // Drop the alias bookkeeping: this entry *is* the selection, so the renderer
+  // must never treat it as a hidden alias and filter it back out.
+  const { hidden, alias_of, ...rest } = nexus;
+  return [{ ...rest, label: NEXUS_LABEL }];
 }
 
 // ── Agent-loop helpers ──────────────────────────────────────────────────────
@@ -497,6 +521,12 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
         mode: opts.mode,
         maxTokens: opts.maxTokens,
         stream: true,
+        // The pooled (Nexus) brain is streamed, and an OpenAI-compatible SSE
+        // stream reports no token usage unless asked. Without this the Aegis
+        // Cloud class — the desktop's default — was the one class that answered
+        // with text but never a token count, so a pooled turn's spend was
+        // invisible here while the same model through the MCP path reported it.
+        includeUsage: true,
         onStream: opts.onDelta,
         // Extended-reasoning trace (the fan-out's worker findings). Its own
         // channel so it never counts as answer text — see vendor/aegis.js.
@@ -658,6 +688,41 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
       let truncationRetried = false;
       let synthesisDone = false;
 
+      // Token accounting for the whole TURN, not just its last round. An
+      // agentic turn makes one provider call per tool round, and returning only
+      // the final round's `usage` (what this did) reported a fraction of what
+      // was actually spent — the tool phase's tokens simply disappeared. Every
+      // dispatch is summed, including the truncation retry and the synthesis
+      // re-dispatch: both are real, separately billed provider calls.
+      const turnUsage = { calls: 0 };
+      const USAGE_FIELDS = ['input_tokens', 'output_tokens', 'prompt_tokens', 'completion_tokens', 'total_tokens'];
+      const addUsage = (res) => {
+        const u = res && res.usage;
+        if (!u || typeof u !== 'object') return;
+        turnUsage.calls += 1;
+        for (const key of USAGE_FIELDS) {
+          if (typeof u[key] === 'number' && Number.isFinite(u[key])) {
+            turnUsage[key] = (turnUsage[key] || 0) + u[key];
+          }
+        }
+        // A provider that reports only the split (Anthropic-compatible) has no
+        // total to sum, so derive one or the renderer has nothing to print.
+        if (typeof u.total_tokens !== 'number') {
+          const derived =
+            (u.prompt_tokens ?? u.input_tokens ?? 0) + (u.completion_tokens ?? u.output_tokens ?? 0);
+          if (derived) turnUsage.total_tokens = (turnUsage.total_tokens || 0) + derived;
+        }
+      };
+      // The turn's totals win over any single round's, so the attached usage is
+      // never the last round wearing the whole turn's label.
+      const withTurnUsage = (res) => {
+        if (!res || typeof res !== 'object' || !turnUsage.calls) return res;
+        // Built from the accumulator alone: every field already present in a
+        // round's usage was summed into it, so merging the last round back in
+        // could only reintroduce a partial number under a whole-turn label.
+        return { ...res, usage: { ...turnUsage } };
+      };
+
       // Round 1's shorthand prompt was sent as `prompt`, not as a message, so
       // any follow-up dispatch in this turn must fold it into the history
       // first or the model would be shown a nudge with no question above it.
@@ -683,6 +748,7 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
           if (!retriable) throw e;
           res = await dispatch(cls, { ...opts, tools: [] });
         }
+        addUsage(res);
 
         // Budget exhausted before the answer was written. Doubling it costs
         // one request and converts a dead turn into a real one; a second
@@ -698,11 +764,12 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
         if (!truncationRetried && !assistantText(res) && isTruncated(res)) {
           truncationRetried = true;
           res = await dispatch(cls, { ...opts, maxTokens: doubledBudget(opts.maxTokens) });
+          addUsage(res);
         }
 
         const calls = toolSchemas.length ? extractToolCalls(res) : [];
         if (!calls.length) {
-          if (assistantText(res) || synthesisDone || !toolsEnabled) return res;
+          if (assistantText(res) || synthesisDone || !toolsEnabled) return withTurnUsage(res);
           // The model stopped without calling a tool and without saying
           // anything. Force the summary out of the context it already holds
           // instead of handing the renderer a blank completion. Skipped when
@@ -712,6 +779,7 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
           foldPromptIntoHistory();
           history.push({ role: 'user', content: EMPTY_TURN_NUDGE });
           res = await dispatch(cls, { ...opts, messages: history, prompt: '', tools: [] });
+          addUsage(res);
           if (!assistantText(res)) {
             throw emptyTurnError({
               cls,
@@ -720,7 +788,7 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
               finishReason: finishReasonOf(res),
             });
           }
-          return res;
+          return withTurnUsage(res);
         }
 
         foldPromptIntoHistory();
@@ -743,6 +811,8 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
                 cls, model, maxTokens, mode: payload && payload.mode, parentSignal: signal, depth, rootSessionId, rootOnDelta,
               })
             : await gatedExecuteTool(call, { toolCtx, rootSessionId, rootOnDelta, signal });
+          // A subagent's spend rides back on its tool result (see runSubagent).
+          if (result && result.usage) addUsage({ usage: result.usage });
           if (onDelta) onDelta({ delta: '', tool: { name: call.name, args: call.args, ok: result.ok } });
           history.push({
             role: 'tool',
@@ -798,9 +868,15 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
         () => {}
       );
       const text = assistantText(res);
+      // The subagent's tokens were billed to the same account as the parent
+      // turn, so its usage travels back on the tool result and is summed into
+      // the parent's total. Attached even on the no-output branch: a subagent
+      // that burned a full context and said nothing is precisely the spend the
+      // user most needs to see.
+      const spent = res && res.usage ? { usage: res.usage } : {};
       return text
-        ? { ok: true, output: text }
-        : { ok: false, error: `subagent (${label}) produced no output` };
+        ? { ok: true, output: text, ...spent }
+        : { ok: false, error: `subagent (${label}) produced no output`, ...spent };
     } catch (e) {
       return { ok: false, error: `subagent (${label}) failed: ${e && e.message ? e.message : e}` };
     } finally {

package/lib/local/providers.js

@@ -380,6 +380,48 @@ async function openaiCompatible({
   return result;
 }
 
+/**
+ * Normalise an Anthropic usage object into the one shape every caller reads.
+ *
+ * Anthropic reports tokens split across TWO events and in TWO pieces:
+ *   - `message_start` carries the prompt side (`input_tokens`, plus
+ *     `cache_creation_input_tokens` / `cache_read_input_tokens`);
+ *   - `message_delta` carries ONLY the cumulative `output_tokens`.
+ * Nothing in the wire format is called `total_tokens`, which is the single
+ * field the renderer prints — so every Anthropic-compatible model reported no
+ * token count at all while OpenAI-compatible ones showed one.
+ *
+ * Returns `null` for an empty/absent usage so the caller can omit the field
+ * rather than advertise a fake `0`.
+ */
+function normalizeAnthropicUsage(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const num = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0);
+  const input = num(raw.input_tokens);
+  const output = num(raw.output_tokens);
+  const cacheRead = num(raw.cache_read_input_tokens);
+  const cacheCreate = num(raw.cache_creation_input_tokens);
+  // Cached prompt tokens are still prompt tokens: OpenAI counts them inside
+  // `prompt_tokens` (exposing the subset as prompt_tokens_details.cached), so
+  // folding them in keeps the two wire formats' numbers comparable — and a
+  // turn that reads a big cached prefix must not look free.
+  const prompt = input + cacheRead + cacheCreate;
+  if (!prompt && !output) return null;
+  const usage = {
+    // Anthropic's own names first, so a caller reading native blocks keeps both
+    // halves of the split it used to get (it previously got only output_tokens).
+    input_tokens: input,
+    output_tokens: output,
+    // OpenAI spellings, read by the renderer and every other transport here.
+    prompt_tokens: prompt,
+    completion_tokens: output,
+    total_tokens: prompt + output,
+  };
+  if (cacheRead) usage.cache_read_input_tokens = cacheRead;
+  if (cacheCreate) usage.cache_creation_input_tokens = cacheCreate;
+  return usage;
+}
+
 /** Anthropic Messages streaming chat (x-api-key + anthropic-version). */
 async function anthropicMessages({
   baseURL,
@@ -423,8 +465,11 @@ async function anthropicMessages({
 
   let fullText = '';
   let resultModel = modelId;
-  let usage = null;
   let stopReason = null;
+  // Accumulated, never replaced: the prompt half arrives on `message_start` and
+  // the output half on `message_delta`, so assignment (which is what this used
+  // to do) left whichever event came last owning the whole object.
+  const usageAcc = {};
   const toolBlocks = new Map(); // content-block index → {id, name, args}
 
   await requestStream({
@@ -446,7 +491,7 @@ async function anthropicMessages({
       }
       if (json.type === 'message_start' && json.message) {
         if (json.message.model) resultModel = json.message.model;
-        if (json.message.usage) usage = json.message.usage;
+        if (json.message.usage) Object.assign(usageAcc, json.message.usage);
       }
       // A tool_use block opens here; its arguments arrive as
       // input_json_delta fragments below (the text deltas we already parsed
@@ -474,13 +519,30 @@ async function anthropicMessages({
         }
       }
       if (json.type === 'message_delta') {
-        if (json.usage) usage = json.usage;
+        // `message_delta.usage` is PARTIAL — `output_tokens` only — so it is
+        // merged onto what `message_start` already reported, not assigned over
+        // it. Assigning it wholesale is what made prompt tokens vanish from
+        // every Anthropic-compatible call's accounting.
+        if (json.usage) {
+          for (const [k, v] of Object.entries(json.usage)) {
+            if (k === 'output_tokens') continue;
+            // Only take a field this event carries a real value for. Some
+            // Anthropic-compatible gateways echo the whole usage object here
+            // with a zeroed prompt side, and letting a bogus 0 overwrite the
+            // count message_start already reported is the same data loss in a
+            // different costume.
+            if (usageAcc[k] == null || (typeof v === 'number' && v > 0)) usageAcc[k] = v;
+          }
+          if (typeof json.usage.output_tokens === 'number') {
+            usageAcc.output_tokens = json.usage.output_tokens;
+          }
+        }
         if (json.delta && json.delta.stop_reason) stopReason = json.delta.stop_reason;
       }
       // Non-streaming fallback: a full Anthropic Message with content blocks.
       if (Array.isArray(json.content)) {
         if (json.model) resultModel = json.model;
-        if (json.usage) usage = json.usage;
+        if (json.usage) Object.assign(usageAcc, json.usage);
         if (json.stop_reason) stopReason = json.stop_reason;
         json.content.forEach((block, i) => {
           if (block && block.type === 'text' && block.text && !fullText) {
@@ -501,6 +563,7 @@ async function anthropicMessages({
 
   const toolCalls = finalizeToolCalls(toolBlocks);
   const result = { model: resultModel, choices: [{ message: { content: fullText } }] };
+  const usage = normalizeAnthropicUsage(usageAcc);
   if (usage) result.usage = usage;
   if (stopReason) result.stop_reason = stopReason;
   if (toolCalls.length) {

package/main.js

@@ -1432,11 +1432,6 @@ function bootstrap() {
     pushToMain: pushQuickLauncherResult,
   });
   registerQuickLauncherIpc(ipcMain, quickLauncherDispatch);
-  // Apply whatever was last saved (or the default) right away: ship the
-  // shortcut only when app.isPackaged || the settings flag is on — see
-  // shouldEnableGlobalShortcut — so a plain `electron .` dev run never grabs
-  // a systemwide hotkey unless the developer opted in from Settings.
-  quickLauncherDispatch.setConfig(settings.quickLauncherConfig());
 
   // A held global shortcut outlives this app if not released — every quit
   // path (explicit quit, window-all-closed on non-mac, OS shutdown) must
@@ -1572,6 +1567,12 @@ function bootstrap() {
     // key was saved in-app (safeStorage is usable only after app ready).
     const persistedKey = settings.aegisRawKey();
     if (persistedKey) aegis.setApiKey(persistedKey);
+    // Apply whatever was last saved (or the default): ship the shortcut only
+    // when app.isPackaged || the settings flag is on — see
+    // shouldEnableGlobalShortcut — so a plain `electron .` dev run never
+    // grabs a systemwide hotkey unless the developer opted in from Settings.
+    // Must run after 'ready' — globalShortcut throws before then.
+    quickLauncherDispatch.setConfig(settings.quickLauncherConfig());
     const win = createWindow();
     updateManager.start();
     // Cold-launch deep link (Linux/Windows argv, or a pre-ready macOS

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aegis-desktop",
   "productName": "AEGIS Desktop",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Thin Electron host for AEGIS — a local chat UI over the shared client/aegis.js transport. Ships transport + UI only; engine logic stays server-side.",
   "author": {
     "name": "AEGIS Code",
@@ -29,7 +29,7 @@
     "icon": "node scripts/generate-icon.mjs",
     "dist": "npm run predist && electron-builder",
     "dist:dir": "npm run predist && electron-builder --dir",
-    "check": "node --check main.js && node --check preload.js && node --check renderer/app.js && node --check renderer/quick.js && node --check renderer/max-tokens.js && node --check renderer/markdown.js && node --check renderer/vendor/aegis-highlight.js && node --check scripts/predist.mjs && node --check scripts/generate-icon.mjs && node --check lib/local/context.js && node --check lib/local/providers.js && node --check lib/local/ollama.js && node --check lib/local/engine.js && node --check lib/local/tools.js && node --check lib/local/prompt.js && node --check lib/local/shell.js && node --check lib/local/agents.js && node --check lib/settings.js && node --check lib/sync/sessions.js && node --check lib/sync/memory-queue.js && node --check lib/window-state.js && node --check lib/deep-link.js && node --check lib/quick-launcher.js && node --check bin/aegis.js",
+    "check": "node --check main.js && node --check preload.js && node --check renderer/app.js && node --check renderer/quick.js && node --check renderer/max-tokens.js && node --check renderer/usage.js && node --check renderer/stream-policy.js && node --check renderer/transcript-view.js && node --check renderer/markdown.js && node --check renderer/vendor/aegis-highlight.js && node --check scripts/predist.mjs && node --check scripts/generate-icon.mjs && node --check lib/local/context.js && node --check lib/local/providers.js && node --check lib/local/ollama.js && node --check lib/local/engine.js && node --check lib/local/tools.js && node --check lib/local/prompt.js && node --check lib/local/shell.js && node --check lib/local/agents.js && node --check lib/settings.js && node --check lib/sync/sessions.js && node --check lib/sync/memory-queue.js && node --check lib/window-state.js && node --check lib/deep-link.js && node --check lib/quick-launcher.js && node --check bin/aegis.js",
     "test:shell": "node ../test/desktop-shell.mjs",
     "test:model": "node ../test/model-dispatch.mjs",
     "test:max-tokens": "node ../test/max-tokens.test.mjs",
@@ -38,7 +38,10 @@
     "test:engine": "node ../test/local-engine.test.mjs",
     "test:highlight": "node ../test/aegis-highlight.test.mjs",
     "test:markdown": "node ../test/markdown.test.mjs",
-    "test:deep-link": "node test/deep-link.test.mjs"
+    "test:deep-link": "node test/deep-link.test.mjs",
+    "test:stream-policy": "node ../test/stream-policy.test.mjs",
+    "test:renderer-dom": "node ../test/renderer-dom.test.mjs",
+    "test:renderer-wiring": "node ../test/renderer-wiring.test.mjs"
   },
   "dependencies": {
     "electron": "^33.0.0",

package/renderer/app.js

@@ -13,9 +13,10 @@
  * selection, routed in the main process. If this file grows engine logic it is
  * wrong.
  *
- * `maxTokensCeiling`/`FLAT_CEILING` come from max-tokens.js, a sibling
- * classic script loaded before this one (see index.html) so the per-model
- * ceiling math stays unit-testable without window.aegis/window.models.
+ * `maxTokensCeiling`/`FLAT_CEILING` come from max-tokens.js and `usageTokens`
+ * from usage.js, sibling classic scripts loaded before this one (see
+ * index.html) so the per-model ceiling math and the token-usage → displayed
+ * number mapping stay unit-testable without window.aegis/window.models.
  */
 
 // Everything below runs inside an IIFE. preload.js's contextBridge.exposeInMainWorld
@@ -249,6 +250,79 @@ function abortBranches() {
   activeBranches.clear();
 }
 
+// ----------------------------------------------------------------- streaming
+// Two problems share a root: a running turn owns the transcript. It scrolls
+// the view on every chunk and repaints on every chunk, so the user can neither
+// read earlier turns nor stay responsive enough to hit "stop". Both are fixed
+// by giving the reader a veto over the scroll and batching the paints.
+//
+// The decisions *and* their DOM listeners live in transcript-view.js (a
+// sibling classic script loaded before this one), so the behaviours this path
+// exists to guarantee — follow only at the tail, one paint per frame, Escape
+// interrupts — are asserted against real code in test/renderer-dom.test.mjs
+// instead of only as pure math in stream-policy.js.
+
+/**
+ * Set when the user asks the running turn to stop. The abort comes back as a
+ * rejected IPC call, which does not preserve `err.name`, so this flag — not an
+ * AbortError check — is what distinguishes a stop the user asked for from a
+ * genuine failure.
+ */
+let userStopped = false;
+
+/**
+ * Transcript policy, created by init(): the reader's scroll veto, the
+ * frame-coalesced painter, and the Escape→stop listener all live in it. Built
+ * in init() rather than here because #messages does not exist until the body
+ * has parsed.
+ */
+let transcript = null;
+
+/**
+ * Auto-scroll only while the reader is still at the tail — the rule itself is
+ * `shouldFollow` in transcript-view.js. Null-safe: a boot that failed early
+ * must not turn into a second error on the first paint.
+ */
+function stickToBottom(opts) {
+  if (!transcript) return false;
+  return transcript.follow(opts);
+}
+
+/** One paint per frame, off the latest cumulative text — see transcript-view.js. */
+function rafPainter(paint) {
+  // Every caller runs after boot; painting directly is the safe degradation.
+  return transcript ? transcript.paint(paint) : paint;
+}
+
+/**
+ * Stop the turn running right now. The transport already honours the abort all
+ * the way down (engine.cancel -> AbortController -> the cloud client's fetch),
+ * so this only has to reach it — the button in the bubble and Escape are two
+ * doors onto the same call.
+ */
+function stopPendingTurn() {
+  if (!pendingSessionId) return false;
+  // Recorded before the abort lands: `send()`'s catch reads it to tell a
+  // deliberate stop from a real error.
+  userStopped = true;
+  try {
+    models.cancel(pendingSessionId);
+  } catch {
+    /* a dead controller is not an error */
+  }
+  // The abort is not instantaneous. Marking the button is all the feedback that
+  // survives the trip: `setBusy(false)` deletes the entire pending bubble on
+  // the way out, so anything written into it would vanish a moment later.
+  if (pendingEl) {
+    const btn = pendingEl.querySelector('.cancel-btn');
+    if (btn) {
+      btn.disabled = true;
+      btn.textContent = 'stopping…';
+    }
+  }
+  return true;
+}
+
 function exploreEnabled() {
   const box = els.exploreToggle;
   return Boolean(box && box.checked);
@@ -1196,7 +1270,10 @@ function addMessage(role, text, meta, sessionId, toolLog) {
   }
 
   els.messages.appendChild(row);
-  els.messages.scrollTop = els.messages.scrollHeight;
+  // Follows only when the reader is still at the tail — see stickToBottom.
+  // A discrete new message must not drag the view away from someone reading
+  // history; the send path forces the follow explicitly instead.
+  stickToBottom();
   return row;
 }
 
@@ -1355,9 +1432,8 @@ async function spawnPath(card, spec) {
     const bits = [spec.path.title];
     if (data && data.model) bits.push(data.model);
     else if (spec.model) bits.push(spec.model);
-    if (data && data.usage && data.usage.total_tokens != null) {
-      bits.push(`${data.usage.total_tokens} tokens`);
-    }
+    const flowTokens = usageTokens(data && data.usage);
+    if (flowTokens != null) bits.push(`${flowTokens} tokens`);
     meta.textContent = bits.join(' · ');
   } catch (err) {
     const message = err && err.message ? err.message : String(err);
@@ -1440,9 +1516,9 @@ function setBusy(busy, { cancellable } = {}) {
       cancelBtn.type = 'button';
       cancelBtn.className = 'cancel-btn';
       cancelBtn.textContent = 'cancel';
-      cancelBtn.addEventListener('click', () => {
-        if (pendingSessionId) models.cancel(pendingSessionId);
-      });
+      // One path for both doors: the button and Escape must produce identical
+      // feedback, including the salvage `send()` performs.
+      cancelBtn.addEventListener('click', () => stopPendingTurn());
       pendingEl.appendChild(cancelBtn);
     }
   } else if (pendingEl) {
@@ -2166,6 +2242,9 @@ async function send() {
   }
 
   els.prompt.value = '';
+  // Clear the stop flag a previous turn may have left set, so a stale `true`
+  // can never make an unrelated failure look like a deliberate stop.
+  userStopped = false;
   addMessage('user', prompt);
 
   const ceiling = applyMaxTokensClamp(model);
@@ -2190,6 +2269,9 @@ async function send() {
   threadMessages.push({ role: 'user', content: prompt });
 
   setBusy(true, { cancellable: true });
+  // Sending is an explicit act, so it always returns the view to the tail.
+  // This is the single moment the auto-scroll overrides the reader's scroll.
+  stickToBottom({ force: true });
 
   // Persist the user turn locally (best-effort — never blocks chat).
   try {
@@ -2201,24 +2283,38 @@ async function send() {
   let streamedText = '';
   let reasoningText = '';
   const toolLog = [];
+
+  // Text arrives in dozens of small chunks per second; painting each one is
+  // what made the window feel locked up. One paint per frame, off the latest
+  // cumulative text.
+  const paintStream = rafPainter(() => {
+    if (!pendingEl) return;
+    pendingEl.classList.remove('pending');
+    if (reasoningText) {
+      const rEl = ensureReasoningEl(pendingEl);
+      if (rEl.textContent !== reasoningText) rEl.textContent = reasoningText;
+    }
+    const bodyEl = pendingEl.querySelector('.body');
+    if (bodyEl && bodyEl.textContent !== streamedText) bodyEl.textContent = streamedText;
+    stickToBottom();
+  });
+
   const onDelta = (chunk) => {
     // Extended-reasoning trace from a pooled brain turn: the fan-out's worker
     // findings, streamed before the synthesis pass writes the answer. Shown so
     // "work autonomously" doesn't look idle for the whole worker phase.
     if (chunk && typeof chunk.reasoning === 'string' && chunk.reasoning) {
       reasoningText += chunk.reasoning;
-      if (pendingEl) {
-        pendingEl.classList.remove('pending');
-        ensureReasoningEl(pendingEl).textContent = reasoningText;
-        els.messages.scrollTop = els.messages.scrollHeight;
-      }
+      paintStream();
       return;
     }
     if (chunk && chunk.approval) {
       if (pendingEl) {
         pendingEl.classList.remove('pending');
         renderApprovalCard(pendingEl, chunk.approval, '.body');
-        els.messages.scrollTop = els.messages.scrollHeight;
+        // Forced on purpose: the turn is blocked until this is answered, so
+        // the card has to be brought into view even if the reader scrolled up.
+        stickToBottom({ force: true });
       }
       return;
     }
@@ -2227,7 +2323,7 @@ async function send() {
       if (pendingEl) {
         pendingEl.classList.remove('pending');
         appendToolActivity(pendingEl, chunk.tool, 'tool-activity', '.body');
-        els.messages.scrollTop = els.messages.scrollHeight;
+        stickToBottom();
       }
       return;
     }
@@ -2235,11 +2331,7 @@ async function send() {
       chunk && (typeof chunk.delta === 'string' ? chunk.delta : chunk.content);
     if (!delta) return;
     streamedText += delta;
-    if (!pendingEl) return;
-    pendingEl.classList.remove('pending');
-    const bodyEl = pendingEl.querySelector('.body');
-    if (bodyEl) bodyEl.textContent = streamedText;
-    els.messages.scrollTop = els.messages.scrollHeight;
+    paintStream();
   };
 
   try {
@@ -2261,9 +2353,8 @@ async function send() {
     else if (model) bits.push(`model: ${model}`);
     bits.push(classLabel(cls));
     if (autonomous) bits.push(`autonomous (${effort}, ${workers || 3}w)`);
-    if (data && data.usage && data.usage.total_tokens != null) {
-      bits.push(`tokens: ${data.usage.total_tokens}`);
-    }
+    const turnTokens = usageTokens(data && data.usage);
+    if (turnTokens != null) bits.push(`tokens: ${turnTokens}`);
     addMessage('assistant', text, bits.join(' · ') || undefined, sessionId, toolLog);
 
     try {
@@ -2279,11 +2370,27 @@ async function send() {
       addFlowLane({ prompt, cls, model, maxTokens, parentSessionId: sessionId });
     }
   } catch (err) {
-    addMessage(
-      'assistant',
-      `Error: ${err && err.message ? err.message : err}`,
-      'request failed'
-    );
+    // A stop is not a failure. The transport rethrows on abort — the SSE read
+    // rejects and the loop re-raises — so the naive path here would discard
+    // everything already streamed and answer with a red "aborted" error,
+    // destroying the partial reply at the exact moment the user asked to keep
+    // it. Salvage the partial turn and label it honestly instead.
+    if (isCancellation(err, { userStopped })) {
+      const text = streamedText || reasoningText || '(stopped before any output)';
+      threadMessages.push({ role: 'assistant', content: text });
+      addMessage('assistant', text, 'stopped by you', sessionId, toolLog);
+      try {
+        await sync.append(sessionId, { role: 'assistant', content: text });
+      } catch {
+        /* persistence is non-fatal */
+      }
+    } else {
+      addMessage(
+        'assistant',
+        `Error: ${err && err.message ? err.message : err}`,
+        'request failed'
+      );
+    }
   } finally {
     setBusy(false);
     pendingSessionId = null;
@@ -2452,8 +2559,37 @@ async function init() {
       renderMemoryOverlay();
     });
   }
-  document.addEventListener('keydown', (e) => {
-    if (e.key === 'Escape' && overlayOpen()) closeMemoryOverlay();
+  // The transcript's scroll/paint/Escape policy. Both listeners are registered
+  // inside transcript-view.js so the behaviours they enforce are the ones
+  // test/renderer-dom.test.mjs drives: the passive `scroll` listener is the
+  // reader's veto over the streaming auto-scroll (without it the transcript
+  // stays pinned to the tail no matter how far up you read while a model is
+  // working), and the `keydown` listener is Escape-as-interrupt (the keyboard
+  // twin of the cancel button, for the window that is too busy to aim at it).
+  transcript = createTranscriptView({
+    messages: els.messages,
+    requestFrame: (fn) => requestAnimationFrame(fn),
+  });
+  transcript.attachScrollVeto();
+  // Read-only diagnostic surface for the headless smoke run
+  // (test/electron-smoke.mjs). Everything in this file lives inside the IIFE,
+  // so an injected script cannot otherwise see the scroll veto — the Phase 9
+  // harness read `transcript.isScrolledUp()` directly and silently got `null`,
+  // which made its veto assertion unfalsifiable. Exposes state only: no
+  // setters, nothing that can drive the UI. Frozen so a stray write in a test
+  // cannot fake a passing run.
+  window.__aegisSmoke = Object.freeze({
+    isScrolledUp: () => transcript.isScrolledUp(),
+    metrics: () => transcript.metrics(),
+  });
+  bindEscapeInterrupt({
+    doc: document,
+    // The memory overlay wins: while it is open, Escape closes it rather than
+    // reaching past it to cancel a turn the user may not be looking at.
+    isOverlayOpen: overlayOpen,
+    onOverlayEscape: closeMemoryOverlay,
+    hasPendingTurn: () => !!pendingSessionId,
+    stopTurn: stopPendingTurn,
   });
 
   // Auto-update banner: `?`-guarded like the memory inspector above, since

package/renderer/index.html

@@ -329,6 +329,9 @@
   </div>
 
   <script src="max-tokens.js"></script>
+  <script src="usage.js"></script>
+  <script src="stream-policy.js"></script>
+  <script src="transcript-view.js"></script>
   <script src="vendor/marked.umd.js"></script>
   <script src="vendor/purify.min.js"></script>
   <script src="vendor/aegis-highlight.js"></script>

package/renderer/stream-policy.js

@@ -0,0 +1,88 @@
+'use strict';
+
+/**
+ * Pure decisions behind a live streaming turn: whether the transcript is
+ * allowed to follow the stream, and whether a rejection means the user asked
+ * to stop. Kept out of app.js — like max-tokens.js — so both rules are
+ * unit-testable from plain Node without a DOM or window.aegis. app.js only
+ * calls into this.
+ *
+ * Both rules exist because a running turn used to own the transcript: it
+ * re-pinned the view on every chunk (so earlier turns could not be read) and
+ * it reported a deliberate stop as a failure (so interrupting lost the answer
+ * already on screen).
+ */
+
+/** Distance from the bottom still counted as "following the stream". */
+const STICK_SLOP_PX = 48;
+
+/**
+ * Is the view at (or effectively at) the tail? A few pixels of slack absorbs
+ * sub-pixel layout and a scrollbar that appears mid-stream; without it the
+ * follow silently stops a fraction short.
+ */
+function nearBottom(metrics, slop) {
+  const m = metrics || {};
+  const budget = Number.isFinite(slop) ? slop : STICK_SLOP_PX;
+  const scrollHeight = Number(m.scrollHeight) || 0;
+  const scrollTop = Number(m.scrollTop) || 0;
+  const clientHeight = Number(m.clientHeight) || 0;
+  return scrollHeight - scrollTop - clientHeight <= budget;
+}
+
+/**
+ * May the transcript be scrolled to the bottom right now? `force` is for the
+ * cases where the view genuinely must move (the user just sent, or a card is
+ * blocking the turn); otherwise the reader's explicit scroll-away wins.
+ *
+ * The flag is checked before the measurement on purpose: a mid-stream reflow
+ * can momentarily measure as "at the bottom" while the reader is nowhere near
+ * it, which is exactly the case where re-pinning feels like a hijack.
+ */
+function shouldFollow(metrics, opts) {
+  const o = opts || {};
+  if (o.force) return true;
+  if (o.userScrolledUp) return false;
+  return nearBottom(metrics, o.slop);
+}
+
+/**
+ * Signatures of a real abort, as each layer spells it: Chromium's fetch
+ * ("The user aborted a request."), undici/Node ("This operation was aborted"),
+ * and an AbortSignal's own reason ("signal is aborted without reason").
+ *
+ * Deliberately NOT a bare /abort/i. A dropped socket surfaces as
+ * "ECONNABORTED: connection aborted by peer" or "socket hang up", which
+ * contains the same word but is a genuine transport failure — matching it
+ * would relabel a real error as a deliberate stop and strand the user with a
+ * silently truncated answer.
+ */
+const ABORT_SIGNATURES = [
+  /AbortError/,
+  /\boperation was aborted\b/i,
+  /\buser aborted\b/i,
+  /\brequest\s+aborted\b/i,
+  /\bsignal is aborted\b/i,
+  /\baborted without reason\b/i,
+];
+
+/**
+ * Did the user ask for this turn to stop? The abort travels back over IPC,
+ * which rebuilds the Error object and drops `name`/`code` — the renderer only
+ * sees a wrapped message. So the caller's own flag is the primary signal, and
+ * the signatures above are a backstop for an abort this renderer did not
+ * initiate.
+ */
+function isCancellation(err, opts) {
+  const o = opts || {};
+  if (o.userStopped) return true;
+  if (!err) return false;
+  if (err.name === 'AbortError' || err.code === 'ABORT_ERR') return true;
+  const msg = typeof err === 'string' ? err : err.message;
+  if (typeof msg !== 'string') return false;
+  return ABORT_SIGNATURES.some((re) => re.test(msg));
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { nearBottom, shouldFollow, isCancellation, STICK_SLOP_PX };
+}

package/renderer/transcript-view.js

@@ -0,0 +1,176 @@
+'use strict';
+
+/**
+ * The DOM-touching half of the transcript policy (plan Phase 8), extracted
+ * from app.js so the two symptoms this work exists to prevent can be asserted
+ * *behaviourally* — not just as pure math in stream-policy.js:
+ *
+ *   - the transcript snapping to the bottom while you read → `follow()` asks
+ *     stream-policy's `shouldFollow()` and the reader's own scroll sets the
+ *     veto through `attachScrollVeto()`;
+ *   - Escape failing to interrupt → `bindEscapeInterrupt()` is the one place
+ *     the keyboard listener is registered.
+ *
+ * Why extract instead of testing app.js itself: app.js boots only under the
+ * Electron host (`window.aegis`/`window.models`) and builds a 2000-line UI, so
+ * a test that drives it would assert on a mock of everything. Everything here
+ * touches exactly four DOM surfaces — three numbers on the transcript element
+ * (scrollHeight/scrollTop/clientHeight), one passive `scroll` listener, one
+ * `keydown` listener on the document, and `requestAnimationFrame` — so
+ * test/renderer-dom.test.mjs drives the real file with a 60-line fake DOM and
+ * no third-party dependency. app.js only calls into this.
+ *
+ * Loaded as a classic script (index.html) *before* app.js, and requireable
+ * from Node like max-tokens.js/stream-policy.js.
+ */
+
+// The decisions stay in stream-policy.js — one definition of "at the tail" and
+// of "the reader has the veto". Classic script: resolve the globals declared by
+// the sibling script tag; CommonJS: resolve the module. Eager, so a missing
+// stream-policy.js script tag fails at load instead of on the first paint.
+const policy =
+  typeof module !== 'undefined' && module.exports
+    ? require('./stream-policy.js')
+    : { nearBottom: nearBottom, shouldFollow: shouldFollow };
+
+/**
+ * Coalescing paint + follow-the-tail state for the one transcript element.
+ *
+ * `messages` is the transcript (`#messages`); `requestFrame` defaults to the
+ * window's `requestAnimationFrame` and is injectable so a test can flush
+ * frames deterministically.
+ */
+function createTranscriptView(deps) {
+  const d = deps || {};
+  const messages = d.messages;
+  const requestFrame =
+    typeof d.requestFrame === 'function'
+      ? d.requestFrame
+      : typeof requestAnimationFrame === 'function'
+        ? requestAnimationFrame
+        : (fn) => fn();
+
+  /** Set while the reader has deliberately scrolled away from the tail. */
+  let scrolledUp = false;
+
+  /** Current transcript scroll metrics, or null when there is no transcript. */
+  function metrics() {
+    if (!messages) return null;
+    return {
+      scrollHeight: messages.scrollHeight,
+      scrollTop: messages.scrollTop,
+      clientHeight: messages.clientHeight,
+    };
+  }
+
+  /**
+   * The reader's veto over the streaming auto-scroll. This is the passive
+   * `scroll` listener: without it `scrolledUp` can never become true, leaving
+   * the transcript pinned to the tail no matter how far up you read while a
+   * model is working. Fires on every scroll frame, so it only records position.
+   */
+  function noteScroll() {
+    scrolledUp = !policy.nearBottom(metrics());
+    return scrolledUp;
+  }
+
+  function attachScrollVeto(el) {
+    const target = el || messages;
+    if (!target || typeof target.addEventListener !== 'function') return false;
+    target.addEventListener('scroll', noteScroll, { passive: true });
+    return true;
+  }
+
+  /**
+   * Follow the tail only while the reader is still there (was
+   * `stickToBottom`). A streaming turn must never yank the view back down once
+   * someone has scrolled up to read — that was why the transcript felt
+   * unscrollable while a model was working. `force` is for the cases where the
+   * view genuinely must follow: a message the user just sent, or a card they
+   * just opened. Returns whether the view moved.
+   */
+  function follow(opts) {
+    if (!messages) return false;
+    if (!policy.shouldFollow(metrics(), { force: opts && opts.force, userScrolledUp: scrolledUp })) {
+      return false;
+    }
+    if (opts && opts.force) scrolledUp = false;
+    messages.scrollTop = messages.scrollHeight;
+    return true;
+  }
+
+  /**
+   * Coalesce high-frequency stream updates to one paint per frame (was
+   * `rafPainter`). A cloud brain fan-out emits dozens of chunks a second, and
+   * each repaint read scrollHeight (forcing a synchronous layout) — that
+   * thrash is what made the window feel frozen mid-turn. Only the latest
+   * payload is painted; dropped frames are invisible because the text is
+   * cumulative. The returned function is idempotent within a frame.
+   */
+  function paint(fn) {
+    let queued = false;
+    return function schedule() {
+      if (queued) return;
+      queued = true;
+      requestFrame(() => {
+        queued = false;
+        fn();
+      });
+    };
+  }
+
+  return {
+    metrics: metrics,
+    noteScroll: noteScroll,
+    attachScrollVeto: attachScrollVeto,
+    follow: follow,
+    paint: paint,
+    isScrolledUp: () => scrolledUp,
+  };
+}
+
+/**
+ * Escape → the running turn's interrupt (the keyboard twin of the cancel
+ * button, for the window that is too busy to aim at it).
+ *
+ * Deliberately the only `keydown` registration: the memory overlay wins while
+ * it is open — Escape closes it rather than reaching past it to cancel a turn
+ * the user may not be looking at — and Escape does nothing at all when no turn
+ * is pending, so the key never becomes a surprise.
+ *
+ * Returns the handler plus an `unbind()` for symmetry with the listener it
+ * owns; the return value is also what lets a test call the decision directly.
+ */
+function bindEscapeInterrupt(deps) {
+  const d = deps || {};
+
+  function handle(e) {
+    if (!e || e.key !== 'Escape') return false;
+    if (typeof d.isOverlayOpen === 'function' && d.isOverlayOpen()) {
+      if (typeof d.onOverlayEscape === 'function') d.onOverlayEscape();
+      return false;
+    }
+    if (typeof d.hasPendingTurn === 'function' && !d.hasPendingTurn()) return false;
+    if (typeof d.stopTurn !== 'function') return false;
+    if (typeof e.preventDefault === 'function') e.preventDefault();
+    d.stopTurn();
+    return true;
+  }
+
+  if (d.doc && typeof d.doc.addEventListener === 'function') {
+    d.doc.addEventListener('keydown', handle);
+  }
+
+  return {
+    handle: handle,
+    unbind: () => {
+      if (d.doc && typeof d.doc.removeEventListener === 'function') {
+        d.doc.removeEventListener('keydown', handle);
+      }
+    },
+  };
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { createTranscriptView, bindEscapeInterrupt };
+}

package/renderer/usage.js

@@ -0,0 +1,42 @@
+'use strict';
+
+/**
+ * Pure token-usage → display-number mapping.
+ *
+ * Standalone from app.js (same reason as max-tokens.js/stream-policy.js): it is
+ * requireable from a plain Node test without window.aegis. app.js only calls
+ * into it.
+ *
+ * Why this exists at all: the two wire formats spell the same quantity
+ * differently, and the renderer used to read exactly one of the spellings.
+ *
+ *   OpenAI-compatible       { prompt_tokens, completion_tokens, total_tokens }
+ *   Anthropic-compatible    { input_tokens,  output_tokens }        ← no total
+ *
+ * Reading only `total_tokens` — the field OpenAI happens to provide — meant
+ * every Anthropic-compatible model rendered with no token count at all, while
+ * the call was silently being billed. Accepting both spellings, and deriving
+ * the total when the provider doesn't state one, is what makes the spend
+ * visible regardless of which endpoint answered.
+ */
+
+/**
+ * Number of tokens to show for a completed turn, or `null` when the provider
+ * reported none (an unknown count must render as nothing, never as `0`).
+ *
+ * @param {{total_tokens?: number, prompt_tokens?: number, completion_tokens?: number,
+ *          input_tokens?: number, output_tokens?: number}|null|undefined} usage
+ * @returns {number|null}
+ */
+function usageTokens(usage) {
+  if (!usage || typeof usage !== 'object') return null;
+  if (typeof usage.total_tokens === 'number') return usage.total_tokens;
+  const input = usage.input_tokens ?? usage.prompt_tokens;
+  const output = usage.output_tokens ?? usage.completion_tokens;
+  if (typeof input !== 'number' && typeof output !== 'number') return null;
+  return (input || 0) + (output || 0);
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { usageTokens };
+}

package/vendor/aegis.js

@@ -290,6 +290,7 @@ function createClient(opts = {}) {
     onStream,
     onReasoning,
     idleTimeoutMs,
+    includeUsage,
     signal,
     extra,
   } = {}) {
@@ -307,9 +308,22 @@ function createClient(opts = {}) {
     if (!stream || typeof onStream !== 'function') {
       return apiPost('/api/v1/chat/completions', { ...body, stream: false });
     }
+    // An OpenAI-compatible SSE response carries no `usage` unless the caller
+    // asks for it (`stream_options.include_usage`). Without this the streamed
+    // AEGIS pool call — the only path the desktop uses for the Nexus brain —
+    // resolved with no usage at all, so a pooled turn could report its text but
+    // never what it spent, while the same model through the non-streaming MCP
+    // path reported both. Only the streaming request sets it: `stream_options`
+    // is invalid alongside `stream:false`, so the non-stream branch above and
+    // every non-stream fallback must stay clean.
+    if (includeUsage) body.stream_options = { include_usage: true };
     return postStream('/api/v1/chat/completions', body, authHeaders(), onStream, signal, {
       onReasoning,
       idleTimeoutMs,
+      // A server that predates `stream_options` 400s the whole request; the
+      // stream is worth more than the token count, so retry on the wire without
+      // the hint before sacrificing streaming for the non-stream fallback.
+      retryWithoutStreamOptions: Boolean(includeUsage),
     });
   }
 
@@ -370,23 +384,49 @@ function createClient(opts = {}) {
    * This keeps streaming purely additive for hosts that opt in.
    */
   async function postStream(path, body, headers, onStream, signal, streamOpts) {
-    const { onReasoning, idleTimeoutMs } = streamOpts || {};
-    let res;
-    try {
-      res = await fetch(`${apiBase}${path}`, {
+    const { onReasoning, idleTimeoutMs, retryWithoutStreamOptions } = streamOpts || {};
+    const request = (payload) =>
+      fetch(`${apiBase}${path}`, {
         method: 'POST',
         headers,
-        body: JSON.stringify({ ...body, stream: true }),
+        body: JSON.stringify({ ...payload, stream: true }),
         signal,
       });
+    let res;
+    try {
+      res = await request(body);
     } catch (err) {
       throw err; // network-level failure; nothing to fall back to
     }
 
+    // Ask for the token count, but never at the cost of the stream: a server
+    // that predates `stream_options` rejects the request outright, so drop that
+    // one hint and put it back on the wire before falling back to a non-stream
+    // response (which would answer in one lump and end the live paint).
+    if (!res.ok && retryWithoutStreamOptions && body.stream_options) {
+      try {
+        if (res.body) await res.body.cancel();
+      } catch {
+        /* the failed response is being discarded anyway */
+      }
+      const cleanBody = { ...body };
+      delete cleanBody.stream_options;
+      body = cleanBody;
+      try {
+        res = await request(body);
+      } catch (err) {
+        throw err;
+      }
+    }
+
     if (!res.ok) {
       // The endpoint may not accept `stream: true`. Retry once without it so
-      // the caller gets the normal structured JSON (result or error).
-      const data = await apiPost(path, { ...body, stream: false }, headers);
+      // the caller gets the normal structured JSON (result or error). Strip
+      // `stream_options` too — it is only legal with `stream: true`, so leaving
+      // it on would turn this graceful fallback into a second rejection.
+      const cleanBody = { ...body };
+      delete cleanBody.stream_options;
+      const data = await apiPost(path, { ...cleanBody, stream: false }, headers);
       const fullText = textOf(data);
       if (fullText) onStream({ delta: fullText });
       return data;