unbound-cli 1.12.0 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbound-cli",
-  "version": "1.12.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/chartRender.js

@@ -162,6 +162,17 @@ function reconstructRows(chart_option, chart_meta) {
     return { columns: [valueKey], rows: [{ [valueKey]: sanitizeLabel(flat.data[0]) }] };
   }
 
+  // 5) KPI as the builder actually emits it: series is [] and the number lives,
+  // already formatted, in a graphic text element. Nothing above can see it, so a
+  // single-number answer decoded to nothing and read as an empty result.
+  const graphicText = asArray(chart_option.graphic)
+    .map((g) => g?.style?.text)
+    .find((t) => typeof t === 'string' && t.trim());
+  if (graphicText) {
+    const valueKey = yKeys[0] || 'value';
+    return { columns: [valueKey], rows: [{ [valueKey]: sanitizeLabel(graphicText.trim()) }] };
+  }
+
   return { columns: [], rows: [] };
 }
 

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;
@@ -85,6 +87,8 @@ function safeWriteFile(target, data) {
   return resolved;
 }
 
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
 function buildBody(message, history, conversationId) {
   const body = {
     message,
@@ -116,9 +120,17 @@ 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,
+    // False when -c named a conversation the server found nothing for. A mistyped
+    // id is still well-formed, so without this the turn reads as a success that
+    // quietly lost the thread.
+    resumed: resp?.resumed === true,
     blocks: blocks.map((b) => {
       if (b.type === 'text') return { type: 'text', text: b.text };
       const result = b.result || {};
@@ -169,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 || {};
@@ -227,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.
@@ -243,27 +326,45 @@ 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) {
+  // 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',
+    );
   }
 }
 
-async function runOneShot({ message, json, outputPath }) {
-  const body = buildBody(message, [], null);
+async function runOneShot({ message, json, outputPath, conversationId }) {
+  const body = buildBody(message, [], 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;
@@ -279,21 +380,41 @@ async function runOneShot({ message, json, outputPath }) {
     if (outputPath) {
       try {
         const resolved = safeWriteFile(outputPath, serialized);
-        output.success(`Wrote ${resolved}`);
+        // With --json the transcript owns stdout. jq parses the whole stream, so a
+        // confirmation printed after it makes the output unparseable and exits 5 —
+        // while still emitting the right answer, which is worse than failing outright.
+        if (json) process.stderr.write(`Wrote ${resolved}\n`);
+        else output.success(`Wrote ${resolved}`);
       } catch (err) {
         output.error(sanitizeForTerminal(err.message));
         process.exitCode = 1;
         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));
@@ -301,7 +422,16 @@ async function runOneShot({ message, json, outputPath }) {
     return;
   }
 
-  renderResponse(resp);
+  warnIfNotResumed(conversationId, toJsonPayload(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 command = (resp?.blocks || []).length ? continueCommand(resp?.conversation_id) : null;
+  if (command) {
+    console.log('');
+    console.log(dim(continueHint(command)));
+  }
   if (resp?.success === false || !(resp?.blocks || []).length) process.exitCode = 1;
 }
 
@@ -400,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;
     }
 
@@ -426,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();
 
   }
 
@@ -448,6 +585,7 @@ function register(program) {
     .option('-m, --message <text>', 'Ask a single question and exit (no interactive session).')
     .option('--json', 'Write the raw JSON response to stdout. Use with -m.')
     .option('-o, --output <path>', 'Write the raw JSON response to a file. Refuses to overwrite. Use with -m.')
+    .option('-c, --continue <conversation_id>', 'Continue the conversation with this id. Use with -m.')
     .addHelpText('after', `
 EXAMPLES
   Start an interactive session:
@@ -458,9 +596,19 @@ EXAMPLES
 
   Write the JSON transcript to stdout (pipe to jq, a script, or a coding agent):
     $ unbound chat -m "cost by provider last 30 days" --json
-    $ unbound chat -m "cost by provider last 30 days" --json | jq '.blocks[].text'
+    $ unbound chat -m "cost by provider last 30 days" --json | jq -r '.blocks[] | select(.type=="text") | .text'
     $ unbound chat -m "cost by provider last 30 days" --json | jq '.blocks[] | select(.type=="chart") | .rows'
 
+  Continue a conversation across separate commands. Every one-shot reply prints
+  the id to continue with; --json carries it as conversation_id:
+    $ unbound chat -m "cost by provider last 7 days"
+      ... continue: unbound chat -m "..." -c <conversation_id>
+    $ unbound chat -m "now just the top 2" -c <conversation_id>
+
+  Scripted, taking the id from the JSON:
+    $ id=$(unbound chat -m "cost by provider last 7 days" --json | jq -r .conversation_id)
+    $ unbound chat -m "now just the top 2" -c "$id"
+
   Write it to a file:
     $ unbound chat -m "cost by provider last 30 days" -o cost.json
 
@@ -468,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, conversation_id, log_id, truncated, 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[]
@@ -482,17 +631,28 @@ OUTPUT FORMAT (--json and -o)
     { type: "chart", title, view_spec, chart_type, row_count, columns, rows }
       columns    string[]                   left-to-right column names
       rows       [{ <column>: value, ... }]  the data, already decoded
-      chart_type "bar" | "line" | "donut" | "pie" | "kpi" | "scatter" | "table"
+      chart_type "bar" | "line" | "area" | "stacked_bar" | "pie" | "donut"
+                 | "scatter" | "heatmap" | "kpi" | "table"
+      decode_failed  present and true only when the chart data could not be read,
+                     so empty rows from a broken payload are not mistaken for an
+                     empty answer
       view_spec  the query that produced it, for reuse or refinement
 
+  error carries the reason when success is false, and is null otherwise.
+
   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
-  0  success
-  1  no blocks returned, auth/role/network failure, or a write error
+  0  success, including a turn that ends by asking you a question
+  1  no blocks returned, auth/role/network failure, a message over 4000
+     characters, or a write error
 
 INTERACTIVE SESSION
   $ unbound chat                             start the session
@@ -507,8 +667,17 @@ INTERACTIVE SESSION
 
 NOTES
   * Requires Admin or Manager role in your organization. Run 'unbound status' to check.
-  * Conversation history is held in memory only; nothing is ever written to disk.
-  * Each -m invocation sends no history; keep each prompt self-contained.
+  * A question the assistant asks back is a normal reply, not an error: the turn
+    exits 0, and you answer it in the next one with -c.
+  * Each -m invocation is its own process and sends no history. -c carries the
+    conversation instead; the turns are read back from the server, and this
+    command still writes no history of its own to disk.
+  * resumed is false when -c named a conversation that was not found. The question
+    is still answered, just without the earlier context.
+  * A single turn can answer several things at once and will say what it could not
+    do. Splitting a broad request across turns with -c tends to give sharper
+    answers though. Messages are capped at 4000 characters.
+  * With --json the transcript owns stdout; everything else goes to stderr.
   * -o writes a new file with mode 0600 and refuses to overwrite existing files.
 `)
     .action(async (opts) => {
@@ -520,7 +689,8 @@ NOTES
         return;
       }
 
-      const oneShotFlagsGiven = opts.message !== undefined || !!opts.json || !!opts.output;
+      const oneShotFlagsGiven =
+        opts.message !== undefined || !!opts.json || !!opts.output || !!opts.continue;
       if (oneShotFlagsGiven) {
         const trimmed = typeof opts.message === 'string' ? opts.message.trim() : '';
         if (!trimmed) {
@@ -533,8 +703,18 @@ NOTES
           process.exitCode = 1;
           return;
         }
+        if (opts.continue !== undefined && !UUID_RE.test(String(opts.continue).trim())) {
+          output.error('`-c/--continue` needs the conversation_id from a previous reply.');
+          process.exitCode = 1;
+          return;
+        }
         try {
-          await runOneShot({ message: trimmed, json: !!opts.json, outputPath: opts.output });
+          await runOneShot({
+            message: trimmed,
+            json: !!opts.json,
+            outputPath: opts.output,
+            conversationId: opts.continue ? String(opts.continue).trim() : null,
+          });
         } catch (err) {
           output.error(friendlyChatError(err));
           process.exitCode = 1;
@@ -556,6 +736,6 @@ module.exports = {
   // Exposed for unit tests:
   _internals: {
     safeWriteFile, expandPath, normalizeAssistantTurn, friendlyChatError,
-    toJsonPayload, flattenBlocks, buildBody,
+    toJsonPayload, flattenBlocks, buildBody, converse,
   },
 };

package/test/chart-render.test.js

@@ -227,3 +227,24 @@ test('reconstructRows: table rows may be arrays aligned to columns', () => {
 test('reconstructRows: a malformed table falls through instead of throwing', () => {
   assert.deepEqual(chart.reconstructRows({ table: { columns: 'nope' } }, {}), { columns: [], rows: [] });
 });
+
+test('reconstructRows: a KPI decodes from the graphic text the builder puts it in', () => {
+  // KPI_TEMPLATE ships series: [] and writes the formatted number into a graphic
+  // element, so every branch keyed on series/dataset/xAxis missed it and a
+  // single-number answer rendered as "(no rows to render)".
+  const option = {
+    series: [],
+    graphic: [{ type: 'text', style: { text: '$372.81', fontSize: 48 } }],
+  };
+
+  const { columns, rows } = chart.reconstructRows(option, { chart_type: 'kpi', y: ['total_cost'] });
+
+  assert.deepEqual(columns, ['total_cost']);
+  assert.deepEqual(rows, [{ total_cost: '$372.81' }]);
+});
+
+test('reconstructRows: an empty graphic text is not mistaken for a value', () => {
+  const option = { series: [], graphic: [{ type: 'text', style: { text: '   ' } }] };
+
+  assert.deepEqual(chart.reconstructRows(option, { chart_type: 'kpi' }), { columns: [], rows: [] });
+});

package/test/chat-internals.test.js

@@ -256,3 +256,19 @@ test('toJsonPayload: an empty chart and an unreadable one are not the same block
   // A genuinely empty answer carries no such marker.
   assert.equal('decode_failed' in payload.blocks[1], false);
 });
+
+test('buildBody: a conversation id travels, and its absence is not a null field', () => {
+  const resumed = buildBody('now just the top 2', [], '00000000-0000-4000-8000-000000000000');
+  assert.equal(resumed.conversation_id, '00000000-0000-4000-8000-000000000000');
+  // One-shot sends no history — the server reads the turns back from the id alone.
+  assert.deepEqual(resumed.conversation_history, []);
+
+  assert.equal('conversation_id' in buildBody('first question', [], null), false);
+});
+
+test('toJsonPayload: resumed is only true when the server says it resumed', () => {
+  assert.equal(toJsonPayload({ blocks: [], resumed: true }).resumed, true);
+  // A mistyped id is well-formed, so silence here would read as success.
+  assert.equal(toJsonPayload({ blocks: [] }).resumed, false);
+  assert.equal(toJsonPayload({ blocks: [], resumed: 'yes' }).resumed, false);
+});

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

@@ -0,0 +1,174 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { Command } = require('commander');
+
+// `--json -o file` printed "Wrote <path>" to stdout, right after the transcript.
+// 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({ 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.postStream = postStream;
+  const auth = require('../src/auth');
+  auth.ensureLoggedIn = async () => {};
+  return require('../src/commands/chat');
+}
+
+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({ postStream: streamer() });
+  const out = [];
+  const err = [];
+  const realOut = process.stdout.write.bind(process.stdout);
+  const realErr = process.stderr.write.bind(process.stderr);
+  process.stdout.write = (chunk) => { out.push(String(chunk)); return true; };
+  process.stderr.write = (chunk) => { err.push(String(chunk)); return true; };
+  try {
+    const program = new Command();
+    program.exitOverride();
+    chat.register(program);
+    await program.parseAsync(['node', 'unbound', 'chat', ...args]);
+  } finally {
+    process.stdout.write = realOut;
+    process.stderr.write = realErr;
+  }
+  return { stdout: out.join(''), stderr: err.join('') };
+}
+
+function tmpPath() {
+  return path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'unbound-chat-')), 'out.json');
+}
+
+test('chat: --json with -o keeps stdout parseable as JSON', async () => {
+  const target = tmpPath();
+  const { stdout, stderr } = await runChat(['-m', 'anything', '--json', '-o', target]);
+
+  // 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, CID);
+
+  // The confirmation still happens, just not where a parser will trip on it.
+  assert.match(stderr, /Wrote /);
+  assert.ok(!stdout.includes('Wrote '), 'stdout must carry the transcript and nothing else');
+
+  assert.equal(JSON.parse(fs.readFileSync(target, 'utf8')).blocks.length, 1);
+});
+
+test('chat: -o without --json still confirms on stdout for a human', async () => {
+  const target = tmpPath();
+  const { stdout } = await runChat(['-m', 'anything', '-o', target]);
+
+  assert.match(stdout, /Wrote /);
+  assert.equal(JSON.parse(fs.readFileSync(target, 'utf8')).blocks.length, 1);
+});
+
+test('chat: --json puts the transcript on stdout and everything else on stderr', async () => {
+  const { stdout, stderr } = await runChat(['-m', 'anything', '--json']);
+
+  // 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:'), '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');
+});