unbound-cli 1.12.0 → 1.13.0

package/package.json

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

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

@@ -85,6 +85,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,
@@ -119,6 +121,10 @@ function toJsonPayload(resp) {
     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 || {};
@@ -257,8 +263,17 @@ function renderResponse(resp) {
   }
 }
 
-async function runOneShot({ message, json, outputPath }) {
-  const body = buildBody(message, [], null);
+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;
@@ -270,6 +285,12 @@ async function runOneShot({ message, json, outputPath }) {
       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.
@@ -279,7 +300,11 @@ 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;
@@ -301,7 +326,15 @@ async function runOneShot({ message, json, outputPath }) {
     return;
   }
 
+  warnIfNotResumed(conversationId, toJsonPayload(resp));
   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) {
+    console.log('');
+    console.log(dim(`  continue: unbound chat -m "..." -c ${sanitizeForTerminal(String(id))}`));
+  }
   if (resp?.success === false || !(resp?.blocks || []).length) process.exitCode = 1;
 }
 
@@ -448,6 +481,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 +492,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 +512,7 @@ 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, 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 +526,24 @@ 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.
 
   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 +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) => {
@@ -520,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) {
@@ -533,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;

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,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/);
+});