unbound-cli 1.11.1 → 1.13.0

package/package.json

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

package/src/api.js

@@ -57,11 +57,15 @@ function request(method, path, { body, query, apiKey, baseUrl, timeoutMs } = {})
     'Accept': 'application/json',
   };
 
-  if (body) {
+  const payload = body ? JSON.stringify(body) : null;
+
+  if (payload !== null) {
     headers['Content-Type'] = 'application/json';
+    // Without this Node falls back to Transfer-Encoding: chunked, and Django's
+    // runserver (wsgiref) reads CONTENT_LENGTH only — so a chunked body arrives
+    // empty and every POST looks like it was sent with no fields at all.
+    headers['Content-Length'] = Buffer.byteLength(payload);
   }
-
-  const payload = body ? JSON.stringify(body) : null;
   const transport = url.protocol === 'https:' ? https : http;
 
   return new Promise((resolve, reject) => {

package/src/chartRender.js

@@ -82,6 +82,22 @@ function reconstructRows(chart_option, chart_meta) {
     return sanitizeForTerminal(v);
   };
 
+  // 0) table charts — the builder emits {columns, rows} under `table` rather than
+  // an axis/series pair, so this shape has no overlap with the ones below. Without
+  // it every table (any result with too many series or dimensions to plot) decodes
+  // to nothing and renders as "(no rows to render)".
+  const table = chart_option.table;
+  if (table && Array.isArray(table.columns) && Array.isArray(table.rows)) {
+    const columns = table.columns.map((c) => sanitizeForTerminal(String(c)));
+    const rows = table.rows.slice(0, MAX_RECONSTRUCT_ROWS).map((r) => (
+      Object.fromEntries(columns.map((k, i) => {
+        const raw = Array.isArray(r) ? r[i] : r?.[table.columns[i]];
+        return [k, sanitizeLabel(raw)];
+      }))
+    ));
+    return { columns, rows };
+  }
+
   // 1) dataset.source — preferred when present
   const source = chart_option.dataset?.source;
   if (Array.isArray(source) && source.length > 0) {
@@ -146,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

@@ -1,8 +1,13 @@
 /**
  * `unbound chat` — interactive session or one-shot wrapper around
- * POST /api/v1/query_builder/chat/. Conversation history lives in memory
- * only; nothing is written to disk. In one-shot mode (-m), `--json` writes
- * the response to stdout and `-o <path>` writes it to a file.
+ * POST /api/v1/query_builder/agent/converse/. Conversation history lives in
+ * memory only; nothing is written to disk. In one-shot mode (-m), `--json`
+ * writes the response to stdout and `-o <path>` writes it to a file.
+ *
+ * A turn is an ordered transcript: the agent interleaves prose and charts, and
+ * both the terminal rendering and the JSON preserve that order. The JSON carries
+ * decoded rows rather than the chart option the wire format uses, so whatever
+ * consumes it — usually a coding agent — gets tabular data it can work with.
  */
 
 const fs = require('fs');
@@ -16,9 +21,10 @@ const { ensureLoggedIn } = require('../auth');
 const chart = require('../chartRender');
 const { sanitizeForTerminal } = chart;
 
-const ENDPOINT = '/api/v1/query_builder/chat/';
+const ENDPOINT = '/api/v1/query_builder/agent/converse/';
+// Above the server's own 300s cap, so a turn is never abandoned while it works.
+const REQUEST_TIMEOUT_MS = 300000;
 const HISTORY_CAP = 20;
-const RECENT_RESULTS_CAP = 5;
 const MAX_MESSAGE_LEN = 4000;
 const MAX_TURN_CONTENT_LEN = 8000;
 const ALLOWED_ROLES = new Set(['user', 'assistant']);
@@ -79,24 +85,70 @@ function safeWriteFile(target, data) {
   return resolved;
 }
 
-function buildBody(message, history, recent) {
-  return {
+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,
     conversation_history: history.slice(-HISTORY_CAP),
-    recent_results: recent.slice(-RECENT_RESULTS_CAP),
   };
+  if (conversationId) body.conversation_id = conversationId;
+  return body;
 }
 
-function pushRecent(recent, query, result) {
-  recent.push({
-    query,
-    view_spec: result.view_spec,
-    result_summary: {
-      row_count: result.row_count,
-      chart_type: result.chart_meta?.chart_type,
-    },
-  });
-  while (recent.length > RECENT_RESULTS_CAP) recent.shift();
+// The model gets the words, not the tables. Same flattening the web client uses.
+function flattenBlocks(blocks) {
+  return (blocks || [])
+    .map((b) => (b.type === 'text' ? b.text : `[chart: ${b.title}]`))
+    .filter(Boolean)
+    .join('\n\n');
+}
+
+/**
+ * The transcript, in order, with charts decoded to rows.
+ *
+ * This is the CLI's JSON contract. The wire format carries an ECharts option
+ * because the browser renders one; nothing downstream of `--json` wants that, so
+ * charts are reduced to view_spec + columns + rows.
+ */
+function toJsonPayload(resp) {
+  const blocks = Array.isArray(resp?.blocks) ? resp.blocks : [];
+  return {
+    success: resp?.success !== false,
+    // Without it a --json consumer gets exit 1 and no reason.
+    error: resp?.error ?? null,
+    conversation_id: 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 || {};
+      let columns = [];
+      let rows = [];
+      let decoded = true;
+      try {
+        ({ columns, rows } = chart.reconstructRows(result.chart_option, result.chart_meta));
+      } catch {
+        decoded = false;
+      }
+      return {
+        type: 'chart',
+        title: b.title,
+        view_spec: result.view_spec ?? null,
+        chart_type: result.chart_meta?.chart_type ?? null,
+        row_count: result.row_count ?? rows.length,
+        columns,
+        rows,
+        // Empty rows because it would not decode, not because the answer was empty.
+        ...(decoded ? {} : { decode_failed: true }),
+      };
+    }),
+  };
 }
 
 function pushHistory(history, turn) {
@@ -126,51 +178,31 @@ function friendlyChatError(err) {
   return sanitizeForTerminal(err?.message || 'Request failed.');
 }
 
-function renderSuggestionsForHuman(suggestions) {
-  if (!suggestions?.length) return;
+/** Print one chart: its title, a one-line summary, then a body or a table. */
+function renderChartBlock(block) {
+  const result = block.result || {};
   console.log('');
-  output.info('Suggested follow-ups (rerun `unbound chat -m "<your question>"` with one of these):');
-  suggestions.forEach((s, i) => {
-    const label = sanitizeForTerminal(s.label || `Suggestion ${i + 1}`);
-    const query = sanitizeForTerminal(s.query || '');
-    const desc = sanitizeForTerminal(s.description || '');
-    console.log(`  ${i + 1}. ${bold(label)}`);
-    if (query) console.log(`     ${query}`);
-    if (desc) console.log(`     ${dim(desc)}`);
-  });
-}
+  console.log(bold('  ' + sanitizeForTerminal(block.title || 'Result')));
+  console.log(dim('  ' + sanitizeForTerminal(chart.summarizeChart(result.chart_meta, result.row_count))));
 
-/**
- * Print the assistant message + (if a chart) a one-line summary and a chart
- * body. Suggestions are NOT printed here — caller decides (REPL picker vs
- * one-shot numbered list).
- */
-function renderResponse(resp) {
-  const intent = resp?.intent;
-  const message = sanitizeForTerminal(resp?.message || '');
-
-  if (intent === 'invalid') {
-    output.error(message || 'The request could not be processed.');
-    return;
+  let columns = [];
+  let rows = [];
+  let decoded = true;
+  try {
+    ({ columns, rows } = chart.reconstructRows(result.chart_option, result.chart_meta));
+  } catch {
+    decoded = false;
   }
-
-  if (intent === 'conversational' || !resp.result) {
-    if (message) console.log(cyan('\u25cf ') + message);
+  // Not the same as a chart with no rows, and must not read like one.
+  if (!decoded) {
+    console.log(dim('  (could not read this chart — --json still carries its spec)'));
     return;
   }
-
-  if (message) console.log(cyan('\u25cf ') + message);
-  const result = resp.result;
-  const summary = sanitizeForTerminal(chart.summarizeChart(result.chart_meta, result.row_count));
-  console.log(dim('  ' + summary));
-
-  const { columns, rows } = chart.reconstructRows(result.chart_option, result.chart_meta);
   if (!rows.length) {
     console.log(dim('  (no rows to render)'));
     return;
   }
 
-  console.log('');
   const cap = chart.MAX_RENDER_ROWS;
   const renderRows = rows.slice(0, cap);
   const chartType = result.chart_meta?.chart_type;
@@ -201,19 +233,65 @@ function renderResponse(resp) {
   }
 }
 
-async function runOneShot({ message, json, outputPath }) {
-  const body = buildBody(message, [], []);
+/**
+ * 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.
+ */
+function renderResponse(resp) {
+  if (resp?.success === false) {
+    output.error(sanitizeForTerminal(resp?.error || 'The request could not be processed.'));
+    return;
+  }
+
+  const blocks = Array.isArray(resp?.blocks) ? resp.blocks : [];
+  if (!blocks.length) {
+    output.warn('The assistant returned nothing. Try rephrasing the question.');
+    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);
+    }
+  }
+
+  if (resp?.truncated) {
+    console.log('');
+    output.warn('That is as far as it got in one turn. Ask for the rest to continue.');
+  }
+}
+
+function warnIfNotResumed(conversationId, payload) {
+  if (conversationId && !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, conversationId }) {
+  const body = buildBody(message, [], conversationId);
 
   if (json || outputPath) {
     let resp;
     try {
-      resp = await api.post(ENDPOINT, { body });
+      resp = await api.post(ENDPOINT, { body, timeoutMs: REQUEST_TIMEOUT_MS });
     } catch (err) {
       output.error(friendlyChatError(err));
       process.exitCode = 1;
       return;
     }
-    const serialized = JSON.stringify(resp, null, 2) + '\n';
+    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.
     if (json) {
@@ -222,21 +300,25 @@ 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;
       }
     }
-    if (resp?.intent === 'invalid') process.exitCode = 1;
+    if (!payload.success || !payload.blocks.length) process.exitCode = 1;
     return;
   }
 
   const spin = output.spinner('Thinking...');
   let resp;
   try {
-    resp = await api.post(ENDPOINT, { body });
+    resp = await api.post(ENDPOINT, { body, timeoutMs: REQUEST_TIMEOUT_MS });
     spin.stop();
   } catch (err) {
     spin.fail(friendlyChatError(err));
@@ -244,9 +326,16 @@ async function runOneShot({ message, json, outputPath }) {
     return;
   }
 
+  warnIfNotResumed(conversationId, toJsonPayload(resp));
   renderResponse(resp);
-  renderSuggestionsForHuman(resp?.suggestions);
-  if (resp?.intent === 'invalid') process.exitCode = 1;
+  // 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) {
+    console.log('');
+    console.log(dim(`  continue: unbound chat -m "..." -c ${sanitizeForTerminal(String(id))}`));
+  }
+  if (resp?.success === false || !(resp?.blocks || []).length) process.exitCode = 1;
 }
 
 function printBanner() {
@@ -281,19 +370,19 @@ function handleSlash(line, state) {
       return 'continue';
     case '/clear':
       state.history.length = 0;
-      state.recent.length = 0;
-      state.lastResult = null;
+      state.conversationId = null;
+      state.lastPayload = null;
       output.success('Conversation cleared.');
       return 'continue';
     case '/json':
-      if (state.lastResult) console.log(JSON.stringify(state.lastResult, null, 2));
+      if (state.lastPayload) console.log(JSON.stringify(state.lastPayload, null, 2));
       else console.log(dim('(no result yet)'));
       return 'continue';
     case '/export': {
-      if (!state.lastResult) { output.error('No result to export yet. Ask a question first.'); return 'continue'; }
+      if (!state.lastPayload) { output.error('No result to export yet. Ask a question first.'); return 'continue'; }
       if (!argStr) { output.error('Usage: /export <path>'); return 'continue'; }
       try {
-        const resolved = safeWriteFile(argStr, JSON.stringify(state.lastResult, null, 2) + '\n');
+        const resolved = safeWriteFile(argStr, JSON.stringify(state.lastPayload, null, 2) + '\n');
         output.success(`Wrote ${resolved}`);
       } catch (err) {
         output.error(sanitizeForTerminal(err.message));
@@ -306,8 +395,8 @@ function handleSlash(line, state) {
   }
 }
 
-async function runRepl({ noSuggestions }) {
-  const state = { history: [], recent: [], lastResult: null };
+async function runRepl() {
+  const state = { history: [], conversationId: null, lastPayload: null };
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   let closed = false;
   const setClosed = () => { closed = true; };
@@ -315,20 +404,13 @@ async function runRepl({ noSuggestions }) {
   rl.on('close', setClosed);
 
   printBanner();
-  let pending = null;
 
   while (!closed) {
     let msg;
-    if (pending) {
-      msg = pending;
-      pending = null;
-      console.log(`${bold('chat>')} ${dim('(picked) ') + sanitizeForTerminal(msg)}`);
-    } else {
-      try {
-        msg = await rl.question(`${bold('chat>')} `);
-      } catch {
-        break;
-      }
+    try {
+      msg = await rl.question(`${bold('chat>')} `);
+    } catch {
+      break;
     }
     if (closed) break;
     msg = (msg || '').trim();
@@ -347,12 +429,12 @@ async function runRepl({ noSuggestions }) {
     // Build the request body BEFORE pushing the current turn into history —
     // otherwise `message` and the last entry of `conversation_history` would
     // both contain the same user text, making the backend process it twice.
-    const body = buildBody(msg, state.history, state.recent);
+    const body = buildBody(msg, state.history, state.conversationId);
 
     const spin = output.spinner('Thinking...');
     let resp;
     try {
-      resp = await api.post(ENDPOINT, { body });
+      resp = await api.post(ENDPOINT, { body, timeoutMs: REQUEST_TIMEOUT_MS });
       spin.stop();
     } catch (err) {
       spin.fail(friendlyChatError(err));
@@ -360,44 +442,32 @@ async function runRepl({ noSuggestions }) {
       continue;
     }
 
-    // Record the user turn only after a successful round-trip so history stays
-    // consistent with the server view.
-    pushHistory(state.history, { role: 'user', content: msg, timestamp: nowIso() });
+    // 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);
+      continue;
+    }
 
-    const assistantTurn = normalizeAssistantTurn(resp?.turn);
-    if (assistantTurn) pushHistory(state.history, assistantTurn);
-    if (resp?.result) {
-      pushRecent(state.recent, msg, resp.result);
-      state.lastResult = resp.result;
+    const assistantTurn = normalizeAssistantTurn({
+      role: 'assistant',
+      content: flattenBlocks(resp?.blocks),
+      timestamp: nowIso(),
+    });
+    // The pair goes in together or not at all. A reply that flattens to nothing
+    // 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);
+      continue;
     }
+    pushHistory(state.history, { role: 'user', content: msg, timestamp: nowIso() });
+    pushHistory(state.history, assistantTurn);
+    state.lastPayload = toJsonPayload(resp);
 
     renderResponse(resp);
 
-    const suggestions = Array.isArray(resp?.suggestions) ? resp.suggestions : [];
-    if (suggestions.length && !noSuggestions && process.stdin.isTTY && process.stdout.isTTY) {
-      const pickOptions = [
-        ...suggestions.map((s, i) => ({
-          label: sanitizeForTerminal(s.label || `Suggestion ${i + 1}`)
-            + (s.description ? ' ' + dim('— ' + sanitizeForTerminal(s.description)) : ''),
-          value: sanitizeForTerminal(s.query || ''),
-        })).filter((o) => o.value),
-        { label: dim('(type your own)'), value: null },
-        { label: dim('(exit)'), value: '__exit__' },
-      ];
-      let pick;
-      try {
-        rl.pause();
-        pick = await output.select('Follow up?', pickOptions);
-      } catch {
-        pick = null;
-      } finally {
-        rl.resume();
-      }
-      if (pick === '__exit__') break;
-      if (pick) pending = pick;
-    } else if (suggestions.length && (!process.stdin.isTTY || !process.stdout.isTTY)) {
-      renderSuggestionsForHuman(suggestions);
-    }
   }
 
   rl.close();
@@ -411,64 +481,72 @@ 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('--no-suggestions', 'Skip the follow-up picker after each turn (interactive session only).')
+    .option('-c, --continue <conversation_id>', 'Continue the conversation with this id. Use with -m.')
     .addHelpText('after', `
 EXAMPLES
   Start an interactive session:
     $ unbound chat
 
-  Ask a single question and render a chart in the terminal:
+  Ask a single question and render it in the terminal:
     $ unbound chat -m "show cost by provider for the last 30 days"
 
-  Write the raw JSON response to stdout (pipe to jq, a script, or another tool):
+  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 '.intent'
-    $ unbound chat -m "cost by provider last 30 days" --json | jq '.result.chart_option'
+    $ 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'
 
-  Write the raw JSON response to a file:
+  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
 
   Combine --json and -o to pipe and archive at the same time:
-    $ unbound chat -m "cost by provider last 30 days" --json -o cost.json | jq '.intent'
+    $ unbound chat -m "cost by provider last 30 days" --json -o cost.json | jq '.blocks | length'
 
 OUTPUT FORMAT (--json and -o)
-  { message, intent, result?, suggestions?, turn }
-
-  intent: "sql_visualise" | "conversational" | "invalid"
-    sql_visualise  — a chart was generated; 'result' is populated.
-    conversational — the model wants clarification; pick a suggestions[i].query and re-run.
-    invalid        — the prompt could not be answered; exit code is 1.
-
-  result (only when intent == "sql_visualise"):
-    columns      string[]             left-to-right column names
-    row_count    number               total rows in the answer
-    chart_meta   { chart_type, x, y } chart_type is one of:
-                                        "bar" | "line" | "donut" | "pie"
-                                      | "kpi" | "scatter" | "table"
-    chart_option ECharts config with the data embedded.
-
-  suggestions (may be present with any intent):
-    [{ label, query, description }]
-    Each entry's 'query' is the exact text for a follow-up '-m "<query>"' call.
-
-  turn: { role, content, timestamp } — the assistant's turn record.
-
-DATA EXTRACTION (rows are embedded in chart_option; no separate rows field)
-  bar, line        chart_option.xAxis.data         (category labels, ordered)
-                   chart_option.series[i].data     (values, parallel to xAxis.data)
-  donut, pie       chart_option.series[0].data     ([{name, value}, ...])
-  scatter          chart_option.series[0].data     ([[x, y], ...])
-                   or chart_option.dataset.source
-  table            chart_option.dataset.source     (first row is the header)
-  kpi              chart_option.series[0].data[0]  (a single number; no axes)
+  { success, error, conversation_id, 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[]
+  preserves that order.
+
+  blocks[i] is one of:
+
+    { type: "text", text }
+      What the agent wrote at this point in the answer.
+
+    { 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" | "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.
+
+  log_id identifies the stored turn, for feedback and for support to trace.
 
 EXIT CODES
-  0  success
-  1  intent=="invalid", 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
-  $ unbound chat --no-suggestions            skip the follow-up picker
 
   Commands (type inside the session):
     /help              show these commands
@@ -480,8 +558,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) => {
@@ -493,7 +580,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) {
@@ -506,8 +594,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;
@@ -516,7 +614,7 @@ NOTES
       }
 
       try {
-        await runRepl({ noSuggestions: opts.suggestions === false });
+        await runRepl();
       } catch (err) {
         output.error(friendlyChatError(err));
         process.exitCode = 1;
@@ -527,5 +625,8 @@ NOTES
 module.exports = {
   register,
   // Exposed for unit tests:
-  _internals: { safeWriteFile, expandPath, normalizeAssistantTurn, friendlyChatError },
+  _internals: {
+    safeWriteFile, expandPath, normalizeAssistantTurn, friendlyChatError,
+    toJsonPayload, flattenBlocks, buildBody,
+  },
 };

package/test/chart-render.test.js

@@ -203,3 +203,48 @@ test('formatNumber: integer thousands separator, decimal capped', () => {
   assert.equal(chart.formatNumber(12.3456), '12.35');
   assert.equal(chart.formatNumber(0), '0');
 });
+
+test('reconstructRows: decodes a table chart_option', () => {
+  const { columns, rows } = chart.reconstructRows(
+    { table: { columns: ['AI Model', 'Requests'], rows: [{ 'AI Model': 'gpt-4o', Requests: 172 }] } },
+    { chart_type: 'table' },
+  );
+
+  assert.deepEqual(columns, ['AI Model', 'Requests']);
+  assert.deepEqual(rows, [{ 'AI Model': 'gpt-4o', Requests: 172 }]);
+});
+
+test('reconstructRows: table rows may be arrays aligned to columns', () => {
+  const { columns, rows } = chart.reconstructRows(
+    { table: { columns: ['a', 'b'], rows: [['x', 1], ['y', 2]] } },
+    { chart_type: 'table' },
+  );
+
+  assert.deepEqual(columns, ['a', 'b']);
+  assert.deepEqual(rows, [{ a: 'x', b: 1 }, { a: 'y', b: 2 }]);
+});
+
+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

@@ -142,3 +142,133 @@ test('friendlyChatError: sanitizes ANSI from backend error messages', () => {
   const msg = friendlyChatError({ statusCode: 500, message: '\x1b]0;title\x07boom\x1b[31m' });
   assert.equal(msg, 'boom');
 });
+
+// --- agent transcript mapping -------------------------------------------------
+
+const { toJsonPayload, flattenBlocks, buildBody } = chat._internals;
+
+// One chart, shaped the way the agent endpoint returns it: a bar chart whose
+// rows live inside the ECharts option rather than in a rows field.
+function chartBlock(title) {
+  return {
+    type: 'chart',
+    title,
+    result: {
+      view_spec: { base_table: 'gateway_metrics_summary' },
+      row_count: 2,
+      chart_meta: { chart_type: 'bar', x: 'dimension', y: ['metric_value'], column_labels: {} },
+      chart_option: {
+        xAxis: { data: ['openai', 'anthropic'] },
+        series: [{ name: 'metric_value', data: [10, 20] }],
+      },
+    },
+  };
+}
+
+test('toJsonPayload: keeps prose and charts in the order the agent produced them', () => {
+  const payload = toJsonPayload({
+    success: true,
+    conversation_id: 'c1',
+    log_id: 'l1',
+    blocks: [
+      { type: 'text', text: 'Here is spend.' },
+      chartBlock('Cost by provider'),
+      { type: 'text', text: 'Note the gap.' },
+    ],
+  });
+
+  assert.deepEqual(payload.blocks.map((b) => b.type), ['text', 'chart', 'text']);
+  assert.equal(payload.conversation_id, 'c1');
+  assert.equal(payload.log_id, 'l1');
+  assert.equal(payload.truncated, false);
+});
+
+test('toJsonPayload: decodes chart rows so consumers never parse an ECharts option', () => {
+  const payload = toJsonPayload({ blocks: [chartBlock('Cost by provider')] });
+  const chartOut = payload.blocks[0];
+
+  assert.equal(chartOut.title, 'Cost by provider');
+  assert.equal(chartOut.chart_type, 'bar');
+  assert.equal(chartOut.row_count, 2);
+  assert.ok(chartOut.columns.length >= 2, 'columns should be populated');
+  assert.equal(chartOut.rows.length, 2);
+  assert.deepEqual(chartOut.view_spec, { base_table: 'gateway_metrics_summary' });
+  // The wire format is an implementation detail of the browser renderer.
+  assert.equal(chartOut.chart_option, undefined);
+});
+
+test('toJsonPayload: an undecodable chart still appears, with its spec intact', () => {
+  const payload = toJsonPayload({
+    blocks: [{ type: 'chart', title: 'Broken', result: { view_spec: { a: 1 }, row_count: 7 } }],
+  });
+
+  assert.equal(payload.blocks.length, 1);
+  assert.equal(payload.blocks[0].row_count, 7);
+  assert.deepEqual(payload.blocks[0].view_spec, { a: 1 });
+  assert.deepEqual(payload.blocks[0].rows, []);
+});
+
+test('toJsonPayload: surfaces truncation and failure rather than hiding them', () => {
+  assert.equal(toJsonPayload({ blocks: [], truncated: true }).truncated, true);
+  assert.equal(toJsonPayload({ success: false, error: 'nope' }).success, false);
+  assert.deepEqual(toJsonPayload(null).blocks, []);
+  assert.deepEqual(toJsonPayload({ blocks: 'not-an-array' }).blocks, []);
+});
+
+test('flattenBlocks: a chart becomes its title, so history carries words only', () => {
+  const flat = flattenBlocks([
+    { type: 'text', text: 'First.' },
+    { type: 'chart', title: 'Cost by provider' },
+    { type: 'text', text: 'Second.' },
+  ]);
+
+  assert.equal(flat, 'First.\n\n[chart: Cost by provider]\n\nSecond.');
+  assert.equal(flattenBlocks(undefined), '');
+});
+
+test('buildBody: omits conversation_id on the first turn, sends it after', () => {
+  assert.equal('conversation_id' in buildBody('hi', [], null), false);
+  assert.equal(buildBody('hi', [], 'c9').conversation_id, 'c9');
+});
+
+test('toJsonPayload: carries the failure reason, not just the failure', () => {
+  const payload = toJsonPayload({ success: false, error: 'The assistant is unavailable right now.' });
+
+  assert.equal(payload.success, false);
+  // Without this a --json consumer gets an exit code and nothing to act on.
+  assert.equal(payload.error, 'The assistant is unavailable right now.');
+  assert.equal(toJsonPayload({ blocks: [] }).error, null);
+});
+
+test('toJsonPayload: an empty chart and an unreadable one are not the same block', () => {
+  const unreadable = { get table() { throw new TypeError('unreadable'); } };
+  const payload = toJsonPayload({
+    blocks: [
+      { type: 'chart', title: 'Broken', result: { chart_option: unreadable, view_spec: { a: 1 }, row_count: 7 } },
+      { type: 'chart', title: 'Empty', result: { chart_option: {}, view_spec: { b: 2 }, row_count: 0 } },
+    ],
+  });
+
+  assert.equal(payload.blocks[0].decode_failed, true);
+  assert.deepEqual(payload.blocks[0].rows, []);
+  // The spec survives, so the caller still knows what was asked.
+  assert.deepEqual(payload.blocks[0].view_spec, { a: 1 });
+  // 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,85 @@
+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({ post }) {
+  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;
+  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.' }],
+};
+
+async function runChat(args) {
+  const chat = freshChat({ post: async () => REPLY });
+  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, 'c-1');
+
+  // 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 with'), 'the hint must not reach stdout');
+  assert.match(stderr, /continue with: -c c-1/);
+});