unbound-cli 1.13.0 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbound-cli",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "CLI tool for Unbound - AI Gateway management",
   "main": "src/index.js",
   "bin": {

package/src/api.js

@@ -114,6 +114,126 @@ function request(method, path, { body, query, apiKey, baseUrl, timeoutMs } = {})
   });
 }
 
+// One SSE frame -> {event, data}. Data lines are joined per the spec: the server
+// sends single-line JSON, but a frame split across lines must not lose its tail.
+function parseSseFrame(frame) {
+  let event = 'message';
+  const data = [];
+  for (const line of frame.split('\n')) {
+    if (line.startsWith('event:')) event = line.slice(6).trim();
+    else if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, ''));
+  }
+  if (!data.length) return null;
+  return { event, data: JSON.parse(data.join('\n')) };
+}
+
+/**
+ * POST that reads a text/event-stream reply, calling onEvent(name, data) per
+ * frame as it arrives.
+ *
+ * timeoutMs bounds SILENCE, not the whole response — Node's socket timeout
+ * resets on every byte. That is the property a long stream needs.
+ *
+ * Resolves null once the stream ends. A server that answers with JSON instead
+ * resolves with that parsed body, so callers work against either.
+ */
+function postStream(path, { body, timeoutMs, onEvent } = {}) {
+  const key = config.getApiKey();
+  if (!key) {
+    return Promise.reject(new Error('Not logged in. Run `unbound login` first.'));
+  }
+
+  const url = new URL(path, config.getBaseUrl());
+  const payload = JSON.stringify(body || {});
+  const headers = {
+    'Authorization': `Bearer ${key}`,
+    'User-Agent': USER_AGENT,
+    'Accept': 'text/event-stream',
+    'Content-Type': 'application/json',
+    'Content-Length': Buffer.byteLength(payload),
+  };
+  const transport = url.protocol === 'https:' ? https : http;
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (fn, value) => { if (!settled) { settled = true; fn(value); } };
+
+    const req = transport.request(url, { method: 'POST', headers }, (res) => {
+      const ok = res.statusCode >= 200 && res.statusCode < 300;
+      const isStream = String(res.headers['content-type'] || '').includes('text/event-stream');
+
+      if (!ok || !isStream) {
+        const chunks = [];
+        res.on('data', (chunk) => chunks.push(chunk));
+        res.on('end', () => {
+          const raw = Buffer.concat(chunks).toString();
+          let parsed;
+          try { parsed = JSON.parse(raw); } catch { parsed = raw; }
+          if (ok) finish(resolve, parsed);
+          else finish(reject, new ApiError(res.statusCode, parsed));
+        });
+        return;
+      }
+
+      res.setEncoding('utf8');
+      let buffer = '';
+      let heldCr = false;
+
+      // SSE line endings may be CR, LF or CRLF, and only LF is searched for
+      // below — so normalise all three rather than stripping CR, which would
+      // collapse a CR-only stream into one unbroken line and dispatch nothing.
+      // A CRLF split across two chunks would read as two endings and cut a frame
+      // in half, so a trailing CR waits for the chunk after it.
+      const feed = (chunk, last) => {
+        let text = (heldCr ? '\r' : '') + chunk;
+        heldCr = !last && text.endsWith('\r');
+        if (heldCr) text = text.slice(0, -1);
+        buffer += text.replace(/\r\n?/g, '\n');
+
+        let boundary = buffer.indexOf('\n\n');
+        while (boundary !== -1) {
+          const frame = buffer.slice(0, boundary);
+          buffer = buffer.slice(boundary + 2);
+          let parsed;
+          try {
+            parsed = parseSseFrame(frame);
+          } catch (err) {
+            req.destroy();
+            finish(reject, new Error(
+              `Unreadable reply from ${url.host}: ${String(err.message).slice(0, 200)}`));
+            return false;
+          }
+          if (parsed && onEvent) onEvent(parsed.event, parsed.data);
+          boundary = buffer.indexOf('\n\n');
+        }
+        return true;
+      };
+
+      res.on('data', (chunk) => feed(chunk, false));
+      res.on('end', () => {
+        // A held CR is the last byte of the stream, so nothing follows it to say
+        // whether it was CRLF. Release it, or a CR-terminated final frame is
+        // never dispatched and the whole turn reads as a dropped connection.
+        if (feed('', true)) finish(resolve, null);
+      });
+      // Headers are already out by now, so a proxy or peer giving up can only
+      // cut the socket — it cannot turn into a status code.
+      res.on('error', (err) => finish(reject, new Error(
+        `The connection to ${url.host} dropped before the reply finished (${err.code || err.message}).`)));
+    });
+
+    const effectiveTimeout = Number.isInteger(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_TIMEOUT_MS;
+    req.setTimeout(effectiveTimeout, () => {
+      req.destroy();
+      finish(reject, new Error(`${url.host} went quiet for ${Math.round(effectiveTimeout / 1000)}s. Please try again.`));
+    });
+
+    req.on('error', (err) => finish(reject, new Error(`Network error: ${err.message}`)));
+    req.write(payload);
+    req.end();
+  });
+}
+
 // Plain unauthenticated GET to an arbitrary URL. Returns the raw response body
 // as a UTF-8 string. Callers that want JSON must do JSON.parse() themselves.
 // Used by `unbound oacb` to fetch baseline JSONs and hook scripts from GitHub.
@@ -168,6 +288,7 @@ module.exports = {
   ApiError,
   get: (path, opts) => request('GET', path, opts),
   post: (path, opts) => request('POST', path, opts),
+  postStream,
   put: (path, opts) => request('PUT', path, opts),
   del: (path, opts) => request('DELETE', path, opts),
   getRaw,

package/src/commands/chat.js

@@ -22,7 +22,9 @@ const chart = require('../chartRender');
 const { sanitizeForTerminal } = chart;
 
 const ENDPOINT = '/api/v1/query_builder/agent/converse/';
-// Above the server's own 300s cap, so a turn is never abandoned while it works.
+// Silence, not total time — the turn streams, so this bounds the gap between
+// frames. A step is one model call plus its queries, capped server-side well
+// under this.
 const REQUEST_TIMEOUT_MS = 300000;
 const HISTORY_CAP = 20;
 const MAX_MESSAGE_LEN = 4000;
@@ -118,6 +120,10 @@ function toJsonPayload(resp) {
     // Without it a --json consumer gets exit 1 and no reason.
     error: resp?.error ?? null,
     conversation_id: resp?.conversation_id ?? null,
+    // The command to run next, spelled out. A model reading this transcript can
+    // act on it without being told how to assemble one from conversation_id.
+    // Null when the turn produced nothing, because there is nothing to continue.
+    continue_command: blocks.length ? continueCommand(resp?.conversation_id) : null,
     log_id: resp?.log_id ?? null,
     // Ran out of budget mid-answer; the blocks already here are real.
     truncated: resp?.truncated === true,
@@ -175,9 +181,58 @@ function friendlyChatError(err) {
   if (err?.statusCode === 401) return 'Not authenticated. Run `unbound login` and try again.';
   if (err?.statusCode === 403) return 'Chat requires Admin or Manager role. Run `unbound status` to check yours.';
   if (err?.statusCode === 429) return 'Rate limited. Please wait a moment and try again.';
+  if (err?.statusCode === 504) return 'The turn took too long and the connection was closed. Try narrowing the question.';
   return sanitizeForTerminal(err?.message || 'Request failed.');
 }
 
+/**
+ * Run one turn, handing each block to `onBlock` as it lands.
+ *
+ * Streamed because the proxy in front of the API drops a connection that goes
+ * 60s without a byte, and a turn can run for minutes — so this is what keeps a
+ * long request alive, not just what makes it render sooner.
+ *
+ * Returns the shape the non-streaming endpoint returns, so callers below do not
+ * care which one answered.
+ */
+async function converse(body, onBlock) {
+  const blocks = [];
+  let tail = null;
+  let failure = null;
+
+  let unstreamed;
+  try {
+    unstreamed = await api.postStream(ENDPOINT, {
+      body: { ...body, stream: true },
+      timeoutMs: REQUEST_TIMEOUT_MS,
+      onEvent: (event, data) => {
+        if (event === 'block' && data) {
+          blocks.push(data);
+          if (onBlock) onBlock(data);
+        } else if (event === 'done') {
+          tail = data;
+        } else if (event === 'error') {
+          failure = data;
+        }
+      },
+    });
+  } catch (err) {
+    // The socket can still fail while tearing down after the closing frame. The
+    // turn reported itself finished, and in the terminal its charts are already
+    // printed — discarding it here would contradict what is on screen.
+    if (!tail && !failure) throw err;
+  }
+
+  if (unstreamed) return unstreamed;
+  // Blocks are kept on a mid-stream failure: they were built, and in the terminal
+  // they have already been printed.
+  if (failure) return { success: false, error: failure.error, blocks };
+  if (!tail) {
+    throw new Error('The connection dropped before the reply finished. Ask again, or narrow the question.');
+  }
+  return { success: true, blocks, ...tail };
+}
+
 /** Print one chart: its title, a one-line summary, then a body or a table. */
 function renderChartBlock(block) {
   const result = block.result || {};
@@ -233,6 +288,28 @@ function renderChartBlock(block) {
   }
 }
 
+function renderBlock(block) {
+  if (block?.type === 'text') {
+    if (block.text) console.log(cyan('\u25cf ') + sanitizeForTerminal(block.text));
+  } else if (block?.type === 'chart') {
+    renderChartBlock(block);
+  }
+}
+
+/**
+ * What belongs after the blocks. Called on its own when they were printed as
+ * they streamed, so this is all that is still owed.
+ */
+function renderTail(resp) {
+  if (resp?.success === false) {
+    output.error(sanitizeForTerminal(resp?.error || 'The request could not be processed.'));
+  }
+  if (resp?.truncated) {
+    console.log('');
+    output.warn('That is as far as it got in one turn. Ask for the rest to continue.');
+  }
+}
+
 /**
  * Print the turn in the order the agent produced it — prose where it wrote
  * prose, a chart where it ran one. A turn can hold several of each.
@@ -249,22 +326,30 @@ function renderResponse(resp) {
     return;
   }
 
-  for (const block of blocks) {
-    if (block?.type === 'text') {
-      if (block.text) console.log(cyan('\u25cf ') + sanitizeForTerminal(block.text));
-    } else if (block?.type === 'chart') {
-      renderChartBlock(block);
-    }
-  }
+  for (const block of blocks) renderBlock(block);
+  renderTail(resp);
+}
 
-  if (resp?.truncated) {
-    console.log('');
-    output.warn('That is as far as it got in one turn. Ask for the rest to continue.');
-  }
+// Null unless the id is a canonical UUID. This string is meant to be run — by a
+// person pasting it or by a model acting on the payload — and it is assembled
+// from a response field, which is not a trusted source of command text. The same
+// shape is already required of `-c`; requiring it in both directions is what
+// keeps a hostile or broken backend from getting a shell metacharacter in here.
+function continueCommand(conversationId) {
+  const id = String(conversationId ?? '');
+  return UUID_RE.test(id) ? `unbound chat -m "..." -c ${id}` : null;
+}
+
+// The same line either way, so what a --json run prints is what a plain run
+// prints — a command to run, not an id to assemble one from.
+function continueHint(command) {
+  return `  continue: ${command}`;
 }
 
 function warnIfNotResumed(conversationId, payload) {
-  if (conversationId && !payload.resumed) {
+  // Only on a turn that ran. A failed turn carries no `resumed` at all, so saying
+  // the conversation was missing sends them after a problem they do not have.
+  if (conversationId && payload.success && !payload.resumed) {
     process.stderr.write(
       `Nothing to continue for ${conversationId} — answering without it. `
       + 'Check the conversation_id from the previous reply.\n',
@@ -278,19 +363,14 @@ async function runOneShot({ message, json, outputPath, conversationId }) {
   if (json || outputPath) {
     let resp;
     try {
-      resp = await api.post(ENDPOINT, { body, timeoutMs: REQUEST_TIMEOUT_MS });
+      // No per-block callback: stdout carries the transcript and nothing else.
+      resp = await converse(body);
     } catch (err) {
       output.error(friendlyChatError(err));
       process.exitCode = 1;
       return;
     }
     const payload = toJsonPayload(resp);
-    warnIfNotResumed(conversationId, payload);
-    // On stderr: stdout is the transcript, and a reader piping it to jq must not
-    // find this in the stream. It is still on screen for whoever ran the command.
-    if (payload.conversation_id && payload.blocks.length) {
-      process.stderr.write(`continue with: -c ${sanitizeForTerminal(String(payload.conversation_id))}\n`);
-    }
     const serialized = JSON.stringify(payload, null, 2) + '\n';
     // Write to stdout first (when requested) so a downstream `-o` write failure
     // doesn't eat the response when both flags are combined.
@@ -311,14 +391,30 @@ async function runOneShot({ message, json, outputPath, conversationId }) {
         return;
       }
     }
+    // Last, after the transcript has finished printing. A turn can be hundreds of
+    // kilobytes of JSON, so anything written before it has scrolled out of reach
+    // by the time the command ends — which is where someone is looking for it.
+    warnIfNotResumed(conversationId, payload);
+    // stderr, and only to a terminal: stdout is the transcript and a reader piping
+    // it to jq must not find this in the stream, while a captured stderr is a log
+    // rather than something a person is reading. A script takes the command off
+    // `continue_command` in the payload instead.
+    if (payload.continue_command && process.stderr.isTTY) {
+      process.stderr.write(continueHint(payload.continue_command) + '\n');
+    }
     if (!payload.success || !payload.blocks.length) process.exitCode = 1;
     return;
   }
 
   const spin = output.spinner('Thinking...');
   let resp;
+  let printed = 0;
   try {
-    resp = await api.post(ENDPOINT, { body, timeoutMs: REQUEST_TIMEOUT_MS });
+    resp = await converse(body, (block) => {
+      if (!printed) spin.stop();
+      printed += 1;
+      renderBlock(block);
+    });
     spin.stop();
   } catch (err) {
     spin.fail(friendlyChatError(err));
@@ -327,13 +423,14 @@ async function runOneShot({ message, json, outputPath, conversationId }) {
   }
 
   warnIfNotResumed(conversationId, toJsonPayload(resp));
-  renderResponse(resp);
+  // A server that answered without streaming printed nothing along the way.
+  if (printed) renderTail(resp); else renderResponse(resp);
   // Without this the id only exists in --json, so continuing a conversation from
   // the terminal would mean asking the same question again just to read it back.
-  const id = resp?.conversation_id;
-  if (id && (resp?.blocks || []).length) {
+  const command = (resp?.blocks || []).length ? continueCommand(resp?.conversation_id) : null;
+  if (command) {
     console.log('');
-    console.log(dim(`  continue: unbound chat -m "..." -c ${sanitizeForTerminal(String(id))}`));
+    console.log(dim(continueHint(command)));
   }
   if (resp?.success === false || !(resp?.blocks || []).length) process.exitCode = 1;
 }
@@ -433,20 +530,27 @@ async function runRepl() {
 
     const spin = output.spinner('Thinking...');
     let resp;
+    let printed = 0;
     try {
-      resp = await api.post(ENDPOINT, { body, timeoutMs: REQUEST_TIMEOUT_MS });
+      resp = await converse(body, (block) => {
+        if (!printed) spin.stop();
+        printed += 1;
+        renderBlock(block);
+      });
       spin.stop();
     } catch (err) {
       spin.fail(friendlyChatError(err));
       if (err?.statusCode === 401 || err?.statusCode === 403) break;
       continue;
     }
+    // A server that answered without streaming printed nothing along the way.
+    const render = () => { if (printed) renderTail(resp); else renderResponse(resp); };
 
     // No answer means no turn: recording the question would send the assistant
     // something it never replied to. The id stays so the server's rows group.
     if (resp?.conversation_id) state.conversationId = resp.conversation_id;
     if (resp?.success === false || !(resp?.blocks || []).length) {
-      renderResponse(resp);
+      render();
       continue;
     }
 
@@ -459,14 +563,14 @@ async function runRepl() {
     // would leave the question in history with no answer beside it, and the next
     // request would send the model two user turns in a row.
     if (!assistantTurn?.content) {
-      renderResponse(resp);
+      render();
       continue;
     }
     pushHistory(state.history, { role: 'user', content: msg, timestamp: nowIso() });
     pushHistory(state.history, assistantTurn);
     state.lastPayload = toJsonPayload(resp);
 
-    renderResponse(resp);
+    render();
 
   }
 
@@ -512,7 +616,8 @@ EXAMPLES
     $ unbound chat -m "cost by provider last 30 days" --json -o cost.json | jq '.blocks | length'
 
 OUTPUT FORMAT (--json and -o)
-  { success, error, conversation_id, log_id, truncated, resumed, blocks[] }
+  { success, error, conversation_id, continue_command, log_id, truncated,
+    resumed, blocks[] }
 
   A turn is an ordered transcript. The agent answers one thing at a time, so a
   single question can return several charts with prose between them, and blocks[]
@@ -538,6 +643,10 @@ OUTPUT FORMAT (--json and -o)
   truncated: true means the agent ran out of budget partway. The blocks present
   are real and complete; ask a follow-up for the rest.
 
+  continue_command is the next command spelled out, for a reader that should act
+  on it rather than assemble one from conversation_id. Null when the turn
+  produced nothing.
+
   log_id identifies the stored turn, for feedback and for support to trace.
 
 EXIT CODES
@@ -627,6 +736,6 @@ module.exports = {
   // Exposed for unit tests:
   _internals: {
     safeWriteFile, expandPath, normalizeAssistantTurn, friendlyChatError,
-    toJsonPayload, flattenBlocks, buildBody,
+    toJsonPayload, flattenBlocks, buildBody, converse,
   },
 };

package/test/chat-json-stdout.test.js

@@ -9,26 +9,32 @@ const { Command } = require('commander');
 // jq parses the whole stream, so it emitted the right answer AND exited 5 — a
 // failure that looks like a success until something checks $?.
 
-function freshChat({ post }) {
+function freshChat({ postStream }) {
   for (const m of ['../src/commands/chat', '../src/api', '../src/auth', '../src/output', '../src/chartRender']) {
     delete require.cache[require.resolve(m)];
   }
   const api = require('../src/api');
-  api.post = post;
+  api.postStream = postStream;
   const auth = require('../src/auth');
   auth.ensureLoggedIn = async () => {};
   return require('../src/commands/chat');
 }
 
-const REPLY = {
-  success: true,
-  conversation_id: 'c-1',
-  log_id: 'l-1',
-  blocks: [{ type: 'text', text: 'Here you go.' }],
-};
+const CID = '11111111-2222-4333-8444-555555555555';
+const BLOCKS = [{ type: 'text', text: 'Here you go.' }];
+const DONE = { conversation_id: CID, log_id: 'l-1' };
+
+// Replay a turn the way the server sends it: a frame per block, then `done`.
+function streamer(blocks = BLOCKS, done = DONE) {
+  return async (_path, { onEvent }) => {
+    for (const block of blocks) onEvent('block', block);
+    onEvent('done', done);
+    return null;
+  };
+}
 
 async function runChat(args) {
-  const chat = freshChat({ post: async () => REPLY });
+  const chat = freshChat({ postStream: streamer() });
   const out = [];
   const err = [];
   const realOut = process.stdout.write.bind(process.stdout);
@@ -58,7 +64,7 @@ test('chat: --json with -o keeps stdout parseable as JSON', async () => {
   // The whole stream, not just a prefix — this is what jq consumes.
   const parsed = JSON.parse(stdout);
   assert.equal(parsed.blocks.length, 1);
-  assert.equal(parsed.conversation_id, 'c-1');
+  assert.equal(parsed.conversation_id, CID);
 
   // The confirmation still happens, just not where a parser will trip on it.
   assert.match(stderr, /Wrote /);
@@ -80,6 +86,89 @@ test('chat: --json puts the transcript on stdout and everything else on stderr',
 
   // stdout is what a reader pipes to jq, so it has to parse whole.
   assert.equal(JSON.parse(stdout).blocks.length, 1);
-  assert.ok(!stdout.includes('continue with'), 'the hint must not reach stdout');
-  assert.match(stderr, /continue with: -c c-1/);
+  assert.ok(!stdout.includes('continue:'), 'the hint must not reach stdout');
+  // Captured here, so not a terminal — the hint is for a person, and a script
+  // takes the id off conversation_id instead.
+  assert.ok(!stderr.includes('continue:'), 'the hint is TTY-only');
+});
+
+test('chat: --json prints the continue hint when stderr is a terminal', async () => {
+  const realIsTTY = Object.getOwnPropertyDescriptor(process.stderr, 'isTTY');
+  Object.defineProperty(process.stderr, 'isTTY', { value: true, configurable: true });
+  try {
+    const { stdout, stderr } = await runChat(['-m', 'anything', '--json']);
+    assert.equal(JSON.parse(stdout).blocks.length, 1);
+    assert.ok(stderr.includes(`continue: unbound chat -m "..." -c ${CID}`));
+  } finally {
+    if (realIsTTY) Object.defineProperty(process.stderr, 'isTTY', realIsTTY);
+    else delete process.stderr.isTTY;
+  }
+});
+
+test('chat: --json carries the next command, not just the id', async () => {
+  const { stdout } = await runChat(['-m', 'anything', '--json']);
+  const payload = JSON.parse(stdout);
+
+  assert.equal(payload.continue_command, `unbound chat -m "..." -c ${CID}`);
+  assert.equal(payload.conversation_id, CID);
+});
+
+test('chat: a turn with no blocks has nothing to continue', async () => {
+  const chat = freshChat({ postStream: streamer([], { conversation_id: CID }) });
+  const payload = chat._internals.toJsonPayload({ success: true, conversation_id: CID, blocks: [] });
+
+  assert.equal(payload.continue_command, null);
+});
+
+test('chat: a conversation_id that is not a uuid yields no command to run', async () => {
+  const chat = freshChat({ postStream: streamer() });
+  const hostile = chat._internals.toJsonPayload({
+    success: true,
+    conversation_id: 'c-1; rm -rf ~',
+    blocks: [{ type: 'text', text: 'hi' }],
+  });
+
+  // The field exists to be executed, so it is null rather than a command
+  // carrying whatever the response happened to contain.
+  assert.equal(hostile.continue_command, null);
+  assert.equal(hostile.conversation_id, 'c-1; rm -rf ~');
+
+  const real = chat._internals.toJsonPayload({
+    success: true,
+    conversation_id: '1555aaca-769c-4b8c-84c5-049397392195',
+    blocks: [{ type: 'text', text: 'hi' }],
+  });
+  assert.equal(real.continue_command,
+    'unbound chat -m "..." -c 1555aaca-769c-4b8c-84c5-049397392195');
+});
+
+test('chat: the continue hint comes after the transcript, not before it', async () => {
+  // A real turn is hundreds of kilobytes. Printed first, the hint scrolls out of
+  // reach before the command ends, which is the same as not printing it.
+  const realIsTTY = Object.getOwnPropertyDescriptor(process.stderr, 'isTTY');
+  Object.defineProperty(process.stderr, 'isTTY', { value: true, configurable: true });
+
+  const chat = freshChat({ postStream: streamer() });
+  const order = [];
+  const realOut = process.stdout.write.bind(process.stdout);
+  const realErr = process.stderr.write.bind(process.stderr);
+  process.stdout.write = (chunk) => { order.push(['stdout', String(chunk)]); return true; };
+  process.stderr.write = (chunk) => { order.push(['stderr', String(chunk)]); return true; };
+  try {
+    const program = new Command();
+    program.exitOverride();
+    chat.register(program);
+    await program.parseAsync(['node', 'unbound', 'chat', '-m', 'anything', '--json']);
+  } finally {
+    process.stdout.write = realOut;
+    process.stderr.write = realErr;
+    if (realIsTTY) Object.defineProperty(process.stderr, 'isTTY', realIsTTY);
+    else delete process.stderr.isTTY;
+  }
+
+  const transcript = order.findIndex(([s, text]) => s === 'stdout' && text.includes('"blocks"'));
+  const hint = order.findIndex(([, text]) => text.includes('continue:'));
+  assert.ok(transcript !== -1, 'the transcript was written');
+  assert.ok(hint !== -1, 'the hint was written');
+  assert.ok(hint > transcript, `hint at ${hint} must come after the transcript at ${transcript}`);
 });

package/test/chat-stream.test.js

@@ -0,0 +1,255 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const http = require('http');
+
+// A turn can run for minutes, and the proxy in front of the API closes a
+// connection that goes 60s without a byte. A buffered POST sends nothing until
+// the turn ends, so every long question died at 60s with the answer already
+// built server-side. These cover the streamed path that replaces it.
+
+function freshModules() {
+  for (const m of ['../src/commands/chat', '../src/api', '../src/config', '../src/auth', '../src/output', '../src/chartRender']) {
+    delete require.cache[require.resolve(m)];
+  }
+}
+
+// Serve `handler` on a loopback port and point the api module at it.
+async function withServer(handler, run) {
+  const server = http.createServer(handler);
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const port = server.address().port;
+  freshModules();
+  const config = require('../src/config');
+  config.getBaseUrl = () => `http://127.0.0.1:${port}`;
+  config.getApiKey = () => 'test-key';
+  const api = require('../src/api');
+  try {
+    return await run(api);
+  } finally {
+    server.close();
+  }
+}
+
+function sse(event, data) {
+  return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+
+test('postStream: reassembles frames split across chunk boundaries', async () => {
+  const frames = sse('block', { type: 'text', text: 'one' })
+    + sse('block', { type: 'chart', title: 'two' })
+    + sse('done', { conversation_id: 'c-1' });
+
+  // Cut mid-JSON, then between the two newlines that terminate a frame — the
+  // two ways a real socket splits a 400 KB chart block. The awaits are what
+  // force separate 'data' events; without them Node coalesces the writes.
+  const midJson = 20;
+  const midSeparator = frames.indexOf('\n\n') + 1;
+  assert.ok(midJson < midSeparator);
+
+  const events = await withServer(async (req, res) => {
+    res.writeHead(200, { 'Content-Type': 'text/event-stream' });
+    for (const part of [frames.slice(0, midJson), frames.slice(midJson, midSeparator), frames.slice(midSeparator)]) {
+      res.write(part);
+      await new Promise((r) => setTimeout(r, 5));
+    }
+    res.end();
+  }, async (api) => {
+    const seen = [];
+    const fallback = await api.postStream('/x', {
+      body: {}, onEvent: (event, data) => seen.push([event, data]),
+    });
+    assert.equal(fallback, null, 'a streamed reply resolves null');
+    return seen;
+  });
+
+  assert.deepEqual(events.map((e) => e[0]), ['block', 'block', 'done']);
+  assert.equal(events[0][1].text, 'one');
+  assert.equal(events[1][1].title, 'two');
+  assert.equal(events[2][1].conversation_id, 'c-1');
+});
+
+test('postStream: a server that answers with JSON resolves that body instead', async () => {
+  const resp = await withServer((req, res) => {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ success: true, blocks: [{ type: 'text', text: 'buffered' }] }));
+  }, async (api) => {
+    let called = 0;
+    const out = await api.postStream('/x', { body: {}, onEvent: () => { called += 1; } });
+    assert.equal(called, 0, 'no frames to hand back');
+    return out;
+  });
+
+  assert.equal(resp.blocks[0].text, 'buffered');
+});
+
+test('postStream: a socket cut mid-stream is reported, not read as a finished turn', async () => {
+  await withServer(async (req, res) => {
+    res.writeHead(200, { 'Content-Type': 'text/event-stream' });
+    res.write(sse('block', { type: 'text', text: 'partial' }));
+    await new Promise((r) => setTimeout(r, 5));
+    // What a proxy does when it gives up: headers are out, so it can only cut.
+    res.socket.destroy();
+  }, async (api) => {
+    const seen = [];
+    await assert.rejects(
+      () => api.postStream('/x', { body: {}, onEvent: (e) => seen.push(e) }),
+      /dropped before the reply finished/,
+    );
+    assert.deepEqual(seen, ['block'], 'what arrived before the cut still counts');
+  });
+});
+
+test('postStream: a non-2xx reply rejects with the status', async () => {
+  await withServer((req, res) => {
+    res.writeHead(403, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'nope' }));
+  }, async (api) => {
+    await assert.rejects(
+      () => api.postStream('/x', { body: {} }),
+      (err) => err.statusCode === 403 && err.message === 'nope',
+    );
+  });
+});
+
+function chatWithStream(postStream) {
+  freshModules();
+  const api = require('../src/api');
+  api.postStream = postStream;
+  return require('../src/commands/chat')._internals.converse;
+}
+
+test('converse: assembles blocks and done into the non-streaming shape', async () => {
+  const converse = chatWithStream(async (_p, { onEvent }) => {
+    onEvent('block', { type: 'text', text: 'hi' });
+    onEvent('done', { conversation_id: 'c-1', log_id: 'l-1', truncated: false, resumed: true });
+    return null;
+  });
+
+  const resp = await converse({ message: 'q' });
+  assert.equal(resp.success, true);
+  assert.equal(resp.blocks.length, 1);
+  assert.equal(resp.conversation_id, 'c-1');
+  assert.equal(resp.resumed, true);
+});
+
+test('converse: sets stream on the request', async () => {
+  let sent = null;
+  const converse = chatWithStream(async (_p, { body, onEvent }) => {
+    sent = body;
+    onEvent('done', { conversation_id: 'c-1' });
+    return null;
+  });
+
+  await converse({ message: 'q', conversation_id: 'c-1' });
+  assert.equal(sent.stream, true);
+  assert.equal(sent.message, 'q');
+  assert.equal(sent.conversation_id, 'c-1');
+});
+
+test('converse: an error event keeps the blocks already streamed', async () => {
+  const converse = chatWithStream(async (_p, { onEvent }) => {
+    onEvent('block', { type: 'text', text: 'built this much' });
+    onEvent('error', { error: 'The assistant is unavailable right now.' });
+    return null;
+  });
+
+  const resp = await converse({ message: 'q' });
+  assert.equal(resp.success, false);
+  assert.equal(resp.error, 'The assistant is unavailable right now.');
+  // They are on screen already — reporting an empty turn would contradict that.
+  assert.equal(resp.blocks.length, 1);
+});
+
+test('converse: a stream that ends without done is reported, not passed off as complete', async () => {
+  const converse = chatWithStream(async (_p, { onEvent }) => {
+    onEvent('block', { type: 'text', text: 'partial' });
+    return null;
+  });
+
+  await assert.rejects(() => converse({ message: 'q' }), /connection dropped/);
+});
+
+test('converse: a server that did not stream is returned untouched', async () => {
+  const buffered = { success: true, blocks: [{ type: 'text', text: 'old server' }], conversation_id: 'c-9' };
+  const converse = chatWithStream(async () => buffered);
+
+  assert.deepEqual(await converse({ message: 'q' }), buffered);
+});
+
+test('postStream: CRLF-delimited frames are read, not silently skipped', async () => {
+  const frames = 'event: block\r\ndata: {"type":"text","text":"crlf"}\r\n\r\n'
+    + 'event: done\r\ndata: {"conversation_id":"c-1"}\r\n\r\n';
+
+  const events = await withServer((req, res) => {
+    res.writeHead(200, { 'Content-Type': 'text/event-stream' });
+    res.end(frames);
+  }, async (api) => {
+    const seen = [];
+    await api.postStream('/x', { body: {}, onEvent: (e, d) => seen.push([e, d]) });
+    return seen;
+  });
+
+  assert.deepEqual(events.map((e) => e[0]), ['block', 'done']);
+  assert.equal(events[0][1].text, 'crlf');
+});
+
+test('converse: a socket that fails after the closing frame keeps the turn', async () => {
+  const converse = chatWithStream(async (_p, { onEvent }) => {
+    onEvent('block', { type: 'text', text: 'built' });
+    onEvent('done', { conversation_id: 'c-1', resumed: true });
+    // Teardown failure, after the turn already reported itself finished.
+    throw new Error('The connection to example dropped before the reply finished (ECONNRESET).');
+  });
+
+  const resp = await converse({ message: 'q' });
+  assert.equal(resp.success, true);
+  assert.equal(resp.blocks.length, 1);
+  assert.equal(resp.conversation_id, 'c-1');
+});
+
+test('converse: a socket that fails with no closing frame still reports the drop', async () => {
+  const converse = chatWithStream(async (_p, { onEvent }) => {
+    onEvent('block', { type: 'text', text: 'partial' });
+    throw new Error('The connection to example dropped before the reply finished (ECONNRESET).');
+  });
+
+  await assert.rejects(() => converse({ message: 'q' }), /dropped before the reply finished/);
+});
+
+test('postStream: CR-only frames are read, not collapsed into one line', async () => {
+  const frames = 'event: block\rdata: {"type":"text","text":"cr"}\r\r'
+    + 'event: done\rdata: {"conversation_id":"c-1"}\r\r';
+
+  const events = await withServer((req, res) => {
+    res.writeHead(200, { 'Content-Type': 'text/event-stream' });
+    res.end(frames);
+  }, async (api) => {
+    const seen = [];
+    await api.postStream('/x', { body: {}, onEvent: (e, d) => seen.push([e, d]) });
+    return seen;
+  });
+
+  assert.deepEqual(events.map((e) => e[0]), ['block', 'done']);
+  assert.equal(events[0][1].text, 'cr');
+});
+
+test('postStream: a CRLF split across two chunks does not cut a frame in half', async () => {
+  const frame = 'event: block\r\ndata: {"type":"text","text":"split"}\r\n\r\n';
+  const cut = frame.indexOf('\r\n') + 1; // between the CR and the LF
+
+  const events = await withServer(async (req, res) => {
+    res.writeHead(200, { 'Content-Type': 'text/event-stream' });
+    res.write(frame.slice(0, cut));
+    await new Promise((r) => setTimeout(r, 5));
+    res.end(frame.slice(cut));
+  }, async (api) => {
+    const seen = [];
+    await api.postStream('/x', { body: {}, onEvent: (e, d) => seen.push([e, d]) });
+    return seen;
+  });
+
+  // Naively normalising CR to LF turns the split ending into a frame boundary,
+  // and the block is silently dropped as a frame with no data.
+  assert.deepEqual(events.map((e) => e[0]), ['block']);
+  assert.equal(events[0][1].text, 'split');
+});