unbound-cli 0.5.1 → 0.6.0

package/.github/workflows/test.yml

@@ -0,0 +1,25 @@
+name: Tests
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test

package/LOCAL_DEV.md

@@ -61,6 +61,10 @@ node src/index.js setup claude-code --gateway --backend-url http://localhost:800
 # Default bundle
 node src/index.js setup --all --backend-url http://localhost:8000 --frontend-url http://localhost:3000
 
+# With --api-key, the CLI verifies the key against its own base URL before running the setup scripts,
+# so you must ALSO set UNBOUND_API_URL (or `config set-url`) or auth will hit prod and fail with 401.
+UNBOUND_API_URL=http://localhost:8000 node src/index.js setup --all --api-key <key> --backend-url http://localhost:8000 --frontend-url http://localhost:3000
+
 # Multiple explicit tools
 node src/index.js setup cursor claude-code-gateway --backend-url http://localhost:8000 --frontend-url http://localhost:3000
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbound-cli",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "CLI tool for Unbound - AI Gateway management",
   "main": "src/index.js",
   "bin": {
@@ -10,7 +10,7 @@
   "scripts": {
     "start": "node src/index.js",
     "lint": "eslint src/",
-    "test": "node --test test/"
+    "test": "node --test test/*.test.js"
   },
   "keywords": [
     "unbound",

package/src/chartRender.js

@@ -0,0 +1,284 @@
+/**
+ * Render ECharts-style chart specs as ASCII for the terminal, and reconstruct
+ * tabular rows from a chart_option payload (the backend never returns rows
+ * separately — they live inside chart_option as xAxis.data + series[].data,
+ * series[].data of {name,value}, or dataset.source).
+ *
+ * Pure functions so they can be unit-tested without TTY mocking.
+ */
+
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = {
+  cyan: (s) => useColor ? `\x1b[36m${s}\x1b[0m` : s,
+  green: (s) => useColor ? `\x1b[32m${s}\x1b[0m` : s,
+  yellow: (s) => useColor ? `\x1b[33m${s}\x1b[0m` : s,
+  red: (s) => useColor ? `\x1b[31m${s}\x1b[0m` : s,
+  dim: (s) => useColor ? `\x1b[2m${s}\x1b[0m` : s,
+  bold: (s) => useColor ? `\x1b[1m${s}\x1b[0m` : s,
+};
+const SERIES_COLORS = [c.cyan, c.green, c.yellow, c.red];
+const MAX_RENDER_ROWS = 20;
+// Upper bound on how many data points we'll materialize from a chart_option,
+// regardless of what the backend returns. Guards against OOM from pathological
+// or hostile payloads. MAX_RENDER_ROWS is a subset of this for display only.
+const MAX_RECONSTRUCT_ROWS = 10000;
+
+// Strip terminal control sequences and C0/C1 control characters from backend-
+// sourced strings before printing. Prevents a hostile/compromised backend from
+// hijacking the user's terminal via ANSI CSI, OSC (title, clipboard, hyperlinks),
+// DCS, APC, or PM sequences. Callers should pipe every backend-origin string
+// through this before echoing.
+function sanitizeForTerminal(value) {
+  if (value === null || value === undefined) return '';
+  let s = typeof value === 'string' ? value : String(value);
+  // Strip OSC (\x1b]...\x07 or \x1b]...\x1b\\), DCS/APC/PM/SOS (\x1bP|X|_|^...\x1b\\).
+  s = s.replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '');
+  s = s.replace(/\x1b[PX_^][^\x1b]*\x1b\\/g, '');
+  // Strip CSI and other ESC-prefixed sequences.
+  s = s.replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '');
+  s = s.replace(/\x1b[@-Z\\-_]/g, '');
+  // Strip 8-bit C1 control bytes (\x80-\x9f) — in 8-bit terminals \x9b means
+  // CSI, \x9d means OSC, \x90 means DCS, etc. Modern UTF-8 terminals mostly
+  // ignore these, but strip them so the sanitizer's guarantee is complete.
+  s = s.replace(/[\x80-\x9f]/g, '');
+  // Strip remaining C0 control chars except tab (\t); drop backspace, CR, LF,
+  // vertical tab, form feed, and the rest. Newlines in assistant messages are
+  // converted to spaces to preserve flow without breaking line-based layout.
+  s = s.replace(/[\r\n]+/g, ' ');
+  s = s.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '');
+  return s;
+}
+
+function asArray(x) {
+  if (x === undefined || x === null) return [];
+  return Array.isArray(x) ? x : [x];
+}
+
+function pickXAxisData(chart_option) {
+  const axes = asArray(chart_option?.xAxis);
+  for (const a of axes) {
+    if (Array.isArray(a?.data)) return a.data;
+  }
+  return null;
+}
+
+function formatNumber(v) {
+  if (typeof v !== 'number' || !isFinite(v)) return String(v ?? '');
+  if (Number.isInteger(v)) return v.toLocaleString('en-US');
+  return v.toLocaleString('en-US', { maximumFractionDigits: 2 });
+}
+
+/**
+ * Reconstruct {columns, rows} from a chart_option + chart_meta.
+ * Defensive — returns {columns: [], rows: []} if nothing usable.
+ */
+function reconstructRows(chart_option, chart_meta) {
+  if (!chart_option || typeof chart_option !== 'object') {
+    return { columns: [], rows: [] };
+  }
+
+  const sanitizeLabel = (v) => {
+    if (typeof v === 'number' || typeof v === 'boolean') return v;
+    return sanitizeForTerminal(v);
+  };
+
+  // 1) dataset.source — preferred when present
+  const source = chart_option.dataset?.source;
+  if (Array.isArray(source) && source.length > 0) {
+    const cappedSource = source.slice(0, MAX_RECONSTRUCT_ROWS + 1);
+    if (Array.isArray(cappedSource[0])) {
+      const [header, ...body] = cappedSource;
+      const columns = header.map((h) => sanitizeForTerminal(String(h)));
+      const rows = body.map((r) => Object.fromEntries(columns.map((k, i) => [k, sanitizeLabel(r[i])])));
+      return { columns, rows };
+    }
+    if (typeof cappedSource[0] === 'object' && cappedSource[0] !== null) {
+      const columns = Object.keys(cappedSource[0]).map((k) => sanitizeForTerminal(k));
+      // Object-shape has no header row so re-cap to MAX_RECONSTRUCT_ROWS.
+      const rows = cappedSource.slice(0, MAX_RECONSTRUCT_ROWS)
+        .map((r) => Object.fromEntries(columns.map((k) => [k, sanitizeLabel(r[k])])));
+      return { columns, rows };
+    }
+  }
+
+  const series = asArray(chart_option.series).filter(Boolean);
+  const xData = pickXAxisData(chart_option);
+  const xKey = sanitizeForTerminal(chart_meta?.x || 'category');
+  const yKeys = asArray(chart_meta?.y).map((y) => sanitizeForTerminal(String(y)));
+
+  // 2) Pie / donut — series[0].data is [{name, value}, ...]
+  const pieSeries = series.find((s) => Array.isArray(s.data) && s.data.length > 0
+    && typeof s.data[0] === 'object' && s.data[0] !== null
+    && 'value' in s.data[0]);
+  if (pieSeries && !xData) {
+    const valueKey = yKeys[0] || 'value';
+    const nameKey = xKey || 'name';
+    const columns = [nameKey, valueKey];
+    const cappedPie = pieSeries.data.slice(0, MAX_RECONSTRUCT_ROWS);
+    const rows = cappedPie.map((d) => ({
+      [nameKey]: sanitizeLabel(d.name ?? ''),
+      [valueKey]: d.value,
+    }));
+    return { columns, rows };
+  }
+
+  // 3) Cartesian — xAxis.data + parallel series[i].data arrays
+  if (xData && series.length > 0) {
+    const seriesNames = series.map((s, i) => sanitizeForTerminal(s.name || yKeys[i] || `series_${i + 1}`));
+    const columns = [xKey, ...seriesNames];
+    const cappedX = xData.slice(0, MAX_RECONSTRUCT_ROWS);
+    const rows = cappedX.map((label, i) => {
+      const row = { [xKey]: sanitizeLabel(label) };
+      series.forEach((s, j) => {
+        const v = Array.isArray(s.data) ? s.data[i] : undefined;
+        row[seriesNames[j]] = (v && typeof v === 'object' && 'value' in v) ? v.value : v;
+      });
+      return row;
+    });
+    return { columns, rows };
+  }
+
+  // 4) KPI / single number — series[0].data[0]
+  const flat = series.find((s) => Array.isArray(s.data) && s.data.length === 1
+    && (typeof s.data[0] === 'number' || typeof s.data[0] === 'string'));
+  if (flat) {
+    const valueKey = yKeys[0] || sanitizeForTerminal(flat.name || 'value');
+    return { columns: [valueKey], rows: [{ [valueKey]: sanitizeLabel(flat.data[0]) }] };
+  }
+
+  return { columns: [], rows: [] };
+}
+
+/**
+ * One-line summary, e.g. "Bar chart, x=provider, y=cost, 4 rows".
+ */
+function summarizeChart(chart_meta, row_count) {
+  const t = chart_meta?.chart_type ? String(chart_meta.chart_type) : 'unknown';
+  const cap = t.charAt(0).toUpperCase() + t.slice(1);
+  const parts = [`${cap} chart`];
+  if (chart_meta?.x) parts.push(`x=${chart_meta.x}`);
+  const ys = asArray(chart_meta?.y);
+  if (ys.length) parts.push(`y=${ys.join('+')}`);
+  if (typeof row_count === 'number') parts.push(`${row_count} row${row_count === 1 ? '' : 's'}`);
+  return parts.join(', ');
+}
+
+/**
+ * Render an ASCII bar chart for the given rows. Single-series only (use
+ * renderGroupedBarChart for multi-series). Returns the rendered string;
+ * caller decides where to print.
+ *
+ * @param {Array<object>} rows
+ * @param {string} xKey
+ * @param {string} yKey
+ * @param {{width?: number, color?: (s:string)=>string}} [opts]
+ */
+function renderBarChart(rows, xKey, yKey, opts = {}) {
+  if (!rows?.length) return '';
+  const width = clampWidth(opts.width);
+  const color = opts.color || c.cyan;
+
+  const labels = rows.map((r) => String(r[xKey] ?? ''));
+  const values = rows.map((r) => Number(r[yKey] ?? 0));
+  const max = Math.max(...values.map((v) => isFinite(v) ? Math.abs(v) : 0));
+
+  const labelWidth = Math.min(24, Math.max(...labels.map((l) => l.length), 1));
+  const truncatedLabels = labels.map((l) => l.length > labelWidth ? l.slice(0, labelWidth - 1) + '\u2026' : l);
+  const valueStrs = values.map(formatNumber);
+  const valueWidth = Math.max(...valueStrs.map((s) => s.length), 1);
+  // Line layout: "  " + label(W) + "  " + bar + "  " + value(W) = 6 padding chars + label + bar + value.
+  const barArea = Math.max(4, width - labelWidth - valueWidth - 6);
+
+  const lines = [];
+  for (let i = 0; i < rows.length; i++) {
+    const v = values[i];
+    const len = max > 0 && isFinite(v) ? Math.max(1, Math.round(Math.abs(v) / max * barArea)) : 0;
+    const bar = '\u2588'.repeat(len);
+    lines.push(
+      `  ${c.dim(truncatedLabels[i].padEnd(labelWidth))}  ${color(bar)}${' '.repeat(barArea - len)}  ${c.bold(valueStrs[i])}`
+    );
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Render a multi-series grouped bar chart by stacking series under each label.
+ */
+function renderGroupedBarChart(rows, xKey, yKeys, opts = {}) {
+  if (!rows?.length || !yKeys?.length) return '';
+  if (yKeys.length === 1) return renderBarChart(rows, xKey, yKeys[0], opts);
+
+  const width = clampWidth(opts.width);
+  const labels = rows.map((r) => String(r[xKey] ?? ''));
+  const labelWidth = Math.min(24, Math.max(...labels.map((l) => l.length), 1));
+  const allValues = rows.flatMap((r) => yKeys.map((k) => Number(r[k] ?? 0)));
+  const max = Math.max(...allValues.map((v) => isFinite(v) ? Math.abs(v) : 0));
+
+  // Build per-series strings to compute valueWidth uniformly.
+  const valueWidth = Math.max(
+    ...rows.flatMap((r) => yKeys.map((k) => formatNumber(Number(r[k] ?? 0)).length)),
+    1
+  );
+  const seriesLabelWidth = Math.max(...yKeys.map((k) => k.length), 1);
+  // Per-series line: "    " + seriesLabel(W) + "  " + bar + "  " + value(W) = 8 padding chars + label + bar + value.
+  const barArea = Math.max(4, width - seriesLabelWidth - valueWidth - 8);
+
+  const legend = '  ' + c.dim('Legend: ') + yKeys.map((k, i) => SERIES_COLORS[i % SERIES_COLORS.length]('\u2588') + ' ' + k).join('  ');
+  const blocks = [legend];
+  for (let i = 0; i < rows.length; i++) {
+    const truncated = labels[i].length > labelWidth ? labels[i].slice(0, labelWidth - 1) + '\u2026' : labels[i];
+    blocks.push('  ' + c.bold(truncated));
+    for (let j = 0; j < yKeys.length; j++) {
+      const v = Number(rows[i][yKeys[j]] ?? 0);
+      const len = max > 0 && isFinite(v) ? Math.max(1, Math.round(Math.abs(v) / max * barArea)) : 0;
+      const color = SERIES_COLORS[j % SERIES_COLORS.length];
+      blocks.push(
+        `    ${c.dim(yKeys[j].padEnd(seriesLabelWidth))}  ${color('\u2588'.repeat(len))}${' '.repeat(barArea - len)}  ${c.bold(formatNumber(v).padStart(valueWidth))}`
+      );
+    }
+  }
+  return blocks.join('\n');
+}
+
+/**
+ * One-line braille sparkline for a numeric series.
+ */
+function renderSparkline(values, opts = {}) {
+  const nums = values.filter((v) => typeof v === 'number' && isFinite(v));
+  if (nums.length < 2) return '';
+  const width = Math.min(opts.width || clampWidth(), nums.length);
+  const min = Math.min(...nums);
+  const max = Math.max(...nums);
+  const span = max - min || 1;
+  // Sample/bucket if more values than width.
+  const buckets = [];
+  for (let i = 0; i < width; i++) {
+    const start = Math.floor(i * nums.length / width);
+    const end = Math.max(start + 1, Math.floor((i + 1) * nums.length / width));
+    const slice = nums.slice(start, end);
+    buckets.push(slice.reduce((a, b) => a + b, 0) / slice.length);
+  }
+  const chars = ['\u2581', '\u2582', '\u2583', '\u2584', '\u2585', '\u2586', '\u2587', '\u2588'];
+  const rendered = buckets.map((v) => {
+    const idx = Math.round((v - min) / span * (chars.length - 1));
+    return chars[Math.max(0, Math.min(chars.length - 1, idx))];
+  }).join('');
+  return `  ${c.dim(formatNumber(min))} ${c.cyan(rendered)} ${c.dim(formatNumber(max))}`;
+}
+
+function clampWidth(w) {
+  const cols = w ?? process.stdout.columns ?? 80;
+  return Math.max(40, Math.min(cols, 120));
+}
+
+module.exports = {
+  reconstructRows,
+  renderBarChart,
+  renderGroupedBarChart,
+  renderSparkline,
+  summarizeChart,
+  formatNumber,
+  sanitizeForTerminal,
+  MAX_RENDER_ROWS,
+  MAX_RECONSTRUCT_ROWS,
+};

package/src/commands/chat.js

@@ -0,0 +1,531 @@
+/**
+ * `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.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const readline = require('readline/promises');
+
+const api = require('../api');
+const output = require('../output');
+const { ensureLoggedIn } = require('../auth');
+const chart = require('../chartRender');
+const { sanitizeForTerminal } = chart;
+
+const ENDPOINT = '/api/v1/query_builder/chat/';
+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']);
+
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const dim = (s) => useColor ? `\x1b[2m${s}\x1b[0m` : s;
+const bold = (s) => useColor ? `\x1b[1m${s}\x1b[0m` : s;
+const cyan = (s) => useColor ? `\x1b[36m${s}\x1b[0m` : s;
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+// Expand a leading `~/` to the user's home directory. Does NOT expand `~user/`
+// (uncommon, not worth parsing). Returns an absolute path.
+function expandPath(p) {
+  if (typeof p !== 'string') return p;
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/') || p.startsWith('~\\')) {
+    return path.join(os.homedir(), p.slice(2));
+  }
+  return path.resolve(p);
+}
+
+// Write `data` to `target` without following symlinks and without overwriting
+// an existing file. Creates the file with mode 0o600 so org analytics don't
+// leak on multi-user hosts. Returns the resolved absolute path on success.
+function safeWriteFile(target, data) {
+  if (target === undefined || target === null || target === '') {
+    throw new Error('Output path is empty.');
+  }
+  if (typeof target !== 'string') {
+    throw new Error('Output path must be a string.');
+  }
+  if (target.includes('\0')) {
+    throw new Error('Output path contains an invalid character (NUL).');
+  }
+  const resolved = expandPath(target);
+  try {
+    const stat = fs.lstatSync(resolved);
+    if (stat.isDirectory()) {
+      throw new Error(`Refusing to write: '${resolved}' is a directory.`);
+    }
+    throw new Error(`Refusing to overwrite existing file: '${resolved}'. Choose a new path or remove it first.`);
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  const fd = fs.openSync(
+    resolved,
+    fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW,
+    0o600,
+  );
+  try {
+    fs.writeFileSync(fd, data);
+  } finally {
+    fs.closeSync(fd);
+  }
+  return resolved;
+}
+
+function buildBody(message, history, recent) {
+  return {
+    message,
+    conversation_history: history.slice(-HISTORY_CAP),
+    recent_results: recent.slice(-RECENT_RESULTS_CAP),
+  };
+}
+
+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();
+}
+
+function pushHistory(history, turn) {
+  history.push(turn);
+  while (history.length > HISTORY_CAP) history.shift();
+}
+
+// Turn text/field from a backend response is untrusted — normalize it before
+// pushing into conversation_history (which we echo on the wire next turn and
+// may print inside /json). Reject unknown roles to prevent a hostile backend
+// from injecting fake `system` turns that amplify prompt-injection attacks.
+function normalizeAssistantTurn(turn) {
+  if (!turn || typeof turn !== 'object') return null;
+  const role = typeof turn.role === 'string' ? turn.role.toLowerCase() : '';
+  if (!ALLOWED_ROLES.has(role)) return null;
+  const content = typeof turn.content === 'string' ? turn.content.slice(0, MAX_TURN_CONTENT_LEN) : '';
+  const timestamp = typeof turn.timestamp === 'string' ? turn.timestamp : nowIso();
+  return { role, content, timestamp };
+}
+
+// Map an error from a chat-endpoint call into a human-readable hint. Keep
+// backend-supplied strings out of the shell line so copy-pastes stay safe.
+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 whoami` to check yours.';
+  if (err?.statusCode === 429) return 'Rate limited. Please wait a moment and try again.';
+  return sanitizeForTerminal(err?.message || 'Request failed.');
+}
+
+function renderSuggestionsForHuman(suggestions) {
+  if (!suggestions?.length) return;
+  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)}`);
+  });
+}
+
+/**
+ * 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;
+  }
+
+  if (intent === 'conversational' || !resp.result) {
+    if (message) console.log(cyan('\u25cf ') + message);
+    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;
+  const cols = process.stdout.columns || 80;
+  const tableCols = columns.map((k) => ({ key: k, header: k }));
+
+  if (cols < 40) {
+    output.table(renderRows, tableCols);
+  } else if (chartType === 'bar' && columns.length >= 2) {
+    const xKey = columns[0];
+    const yKeys = columns.slice(1);
+    const body = yKeys.length === 1
+      ? chart.renderBarChart(renderRows, xKey, yKeys[0])
+      : chart.renderGroupedBarChart(renderRows, xKey, yKeys);
+    if (body) console.log(body); else output.table(renderRows, tableCols);
+  } else if (chartType === 'line' && columns.length >= 2) {
+    const yKey = columns[1];
+    const series = renderRows.map((r) => Number(r[yKey] ?? 0));
+    const spark = chart.renderSparkline(series);
+    if (spark) console.log(spark);
+    output.table(renderRows, tableCols);
+  } else {
+    output.table(renderRows, tableCols);
+  }
+
+  if (rows.length > cap) {
+    console.log(dim(`  \u2026 ${rows.length - cap} more row${rows.length - cap === 1 ? '' : 's'} hidden. Use --json or -o for full data.`));
+  }
+}
+
+async function runOneShot({ message, json, outputPath }) {
+  const body = buildBody(message, [], []);
+
+  if (json || outputPath) {
+    let resp;
+    try {
+      resp = await api.post(ENDPOINT, { body });
+    } catch (err) {
+      output.error(friendlyChatError(err));
+      process.exitCode = 1;
+      return;
+    }
+    const serialized = JSON.stringify(resp, 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) {
+      process.stdout.write(serialized);
+    }
+    if (outputPath) {
+      try {
+        const resolved = safeWriteFile(outputPath, serialized);
+        output.success(`Wrote ${resolved}`);
+      } catch (err) {
+        output.error(sanitizeForTerminal(err.message));
+        process.exitCode = 1;
+        return;
+      }
+    }
+    if (resp?.intent === 'invalid') process.exitCode = 1;
+    return;
+  }
+
+  const spin = output.spinner('Thinking...');
+  let resp;
+  try {
+    resp = await api.post(ENDPOINT, { body });
+    spin.stop();
+  } catch (err) {
+    spin.fail(friendlyChatError(err));
+    process.exitCode = 1;
+    return;
+  }
+
+  renderResponse(resp);
+  renderSuggestionsForHuman(resp?.suggestions);
+  if (resp?.intent === 'invalid') process.exitCode = 1;
+}
+
+function printBanner() {
+  console.log(bold('unbound chat') + dim('  — ask questions about your usage data'));
+  console.log(dim('Type a question, or /help for commands. /exit (or Ctrl+C) to quit.'));
+  console.log('');
+}
+
+function printReplHelp() {
+  const lines = [
+    '  /help              show this help',
+    '  /json              print the last result as JSON to stdout',
+    '  /export <path>     write the last result to a new JSON file',
+    '                     (refuses to overwrite; supports ~/ expansion; mode 0600)',
+    '  /clear             reset the conversation in memory',
+    '  /exit              quit (Ctrl+C also works)',
+  ];
+  console.log(lines.join('\n'));
+}
+
+function handleSlash(line, state) {
+  const trimmed = line.trim();
+  const spaceIdx = trimmed.search(/\s/);
+  const cmd = spaceIdx === -1 ? trimmed : trimmed.slice(0, spaceIdx);
+  const argStr = spaceIdx === -1 ? '' : trimmed.slice(spaceIdx + 1).trim();
+  switch (cmd) {
+    case '/exit':
+    case '/quit':
+      return 'exit';
+    case '/help':
+      printReplHelp();
+      return 'continue';
+    case '/clear':
+      state.history.length = 0;
+      state.recent.length = 0;
+      state.lastResult = null;
+      output.success('Conversation cleared.');
+      return 'continue';
+    case '/json':
+      if (state.lastResult) console.log(JSON.stringify(state.lastResult, 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 (!argStr) { output.error('Usage: /export <path>'); return 'continue'; }
+      try {
+        const resolved = safeWriteFile(argStr, JSON.stringify(state.lastResult, null, 2) + '\n');
+        output.success(`Wrote ${resolved}`);
+      } catch (err) {
+        output.error(sanitizeForTerminal(err.message));
+      }
+      return 'continue';
+    }
+    default:
+      output.warn(`Unknown command: ${sanitizeForTerminal(cmd)}. Type /help for the list.`);
+      return 'continue';
+  }
+}
+
+async function runRepl({ noSuggestions }) {
+  const state = { history: [], recent: [], lastResult: null };
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  let closed = false;
+  const setClosed = () => { closed = true; };
+  rl.on('SIGINT', () => { closed = true; rl.close(); });
+  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;
+      }
+    }
+    if (closed) break;
+    msg = (msg || '').trim();
+    if (!msg) continue;
+    if (msg.length > MAX_MESSAGE_LEN) {
+      output.warn(`Message truncated to ${MAX_MESSAGE_LEN} characters.`);
+      msg = msg.slice(0, MAX_MESSAGE_LEN);
+    }
+
+    if (msg.startsWith('/')) {
+      const action = handleSlash(msg, state);
+      if (action === 'exit') break;
+      continue;
+    }
+
+    // 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 spin = output.spinner('Thinking...');
+    let resp;
+    try {
+      resp = await api.post(ENDPOINT, { body });
+      spin.stop();
+    } catch (err) {
+      spin.fail(friendlyChatError(err));
+      if (err?.statusCode === 401 || err?.statusCode === 403) break;
+      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() });
+
+    const assistantTurn = normalizeAssistantTurn(resp?.turn);
+    if (assistantTurn) pushHistory(state.history, assistantTurn);
+    if (resp?.result) {
+      pushRecent(state.recent, msg, resp.result);
+      state.lastResult = resp.result;
+    }
+
+    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();
+  console.log('');
+}
+
+function register(program) {
+  program
+    .command('chat')
+    .description('Chat with your usage data. Opens an interactive session by default; use -m for one-shot.')
+    .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).')
+    .addHelpText('after', `
+EXAMPLES
+  Start an interactive session:
+    $ unbound chat
+
+  Ask a single question and render a chart 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):
+    $ 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'
+
+  Write the raw JSON response 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'
+
+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)
+
+EXIT CODES
+  0  success
+  1  intent=="invalid", auth/role/network failure, 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
+    /json              print the last result as JSON
+    /export <path>     write the last result to a file (refuses to overwrite;
+                       supports ~/ expansion; file mode is 0600)
+    /clear             reset the conversation in memory
+    /exit              quit (Ctrl+C also works)
+
+NOTES
+  * Requires Admin or Manager role in your organization. Run 'unbound whoami' 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.
+  * -o writes a new file with mode 0600 and refuses to overwrite existing files.
+`)
+    .action(async (opts) => {
+      try {
+        await ensureLoggedIn();
+      } catch (err) {
+        if (!err.displayed) output.error(sanitizeForTerminal(err.message));
+        process.exitCode = 1;
+        return;
+      }
+
+      const oneShotFlagsGiven = opts.message !== undefined || !!opts.json || !!opts.output;
+      if (oneShotFlagsGiven) {
+        const trimmed = typeof opts.message === 'string' ? opts.message.trim() : '';
+        if (!trimmed) {
+          output.error('`-m/--message` requires a non-empty message. For interactive chat, run `unbound chat` with no flags.');
+          process.exitCode = 1;
+          return;
+        }
+        if (trimmed.length > MAX_MESSAGE_LEN) {
+          output.error(`Message too long (max ${MAX_MESSAGE_LEN} characters).`);
+          process.exitCode = 1;
+          return;
+        }
+        try {
+          await runOneShot({ message: trimmed, json: !!opts.json, outputPath: opts.output });
+        } catch (err) {
+          output.error(friendlyChatError(err));
+          process.exitCode = 1;
+        }
+        return;
+      }
+
+      try {
+        await runRepl({ noSuggestions: opts.suggestions === false });
+      } catch (err) {
+        output.error(friendlyChatError(err));
+        process.exitCode = 1;
+      }
+    });
+}
+
+module.exports = {
+  register,
+  // Exposed for unit tests:
+  _internals: { safeWriteFile, expandPath, normalizeAssistantTurn, friendlyChatError },
+};

package/src/index.js

@@ -115,6 +115,14 @@ TOOL CONNECTIONS
   $ unbound tools connect <type>           Connect a new tool
   $ unbound tools approved                 List approved tool types
 
+CHAT (Admin/Manager)
+  $ unbound chat                           Interactive REPL (multi-turn, in-memory history)
+  $ unbound chat -m "show cost by provider for the last 30 days"
+                                           One-shot: render a chart in the terminal
+  $ unbound chat -m "..." --json           One-shot: write the raw JSON response to stdout
+  $ unbound chat -m "..." -o report.json   One-shot: write the raw JSON response to a file
+  See "unbound chat --help" for the response shape and REPL slash commands.
+
 CONFIGURATION
   $ unbound config show                    Show all settings
 
@@ -138,6 +146,7 @@ require('./commands/tools').register(program);
 require('./commands/setup').register(program);
 require('./commands/discover').register(program);
 require('./commands/onboard').register(program);
+require('./commands/chat').register(program);
 
 // config command for managing CLI settings
 const configCmd = program

package/test/chart-render.test.js

@@ -0,0 +1,205 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const chart = require('../src/chartRender');
+
+const stripAnsi = (s) => s.replace(/\x1b\[[0-9;]*m/g, '');
+
+test('reconstructRows: bar chart with single series', () => {
+  const chart_option = {
+    xAxis: { type: 'category', data: ['A', 'B', 'C'] },
+    yAxis: { type: 'value' },
+    series: [{ name: 'cost', type: 'bar', data: [10, 20, 30] }],
+  };
+  const chart_meta = { chart_type: 'bar', x: 'department', y: ['cost'] };
+  const { columns, rows } = chart.reconstructRows(chart_option, chart_meta);
+  assert.deepEqual(columns, ['department', 'cost']);
+  assert.deepEqual(rows, [
+    { department: 'A', cost: 10 },
+    { department: 'B', cost: 20 },
+    { department: 'C', cost: 30 },
+  ]);
+});
+
+test('reconstructRows: multi-series bar chart', () => {
+  const chart_option = {
+    xAxis: { data: ['A', 'B'] },
+    series: [
+      { name: 'opus', data: [10, 20] },
+      { name: 'sonnet', data: [5, 15] },
+    ],
+  };
+  const chart_meta = { chart_type: 'bar', x: 'department', y: ['opus', 'sonnet'] };
+  const { columns, rows } = chart.reconstructRows(chart_option, chart_meta);
+  assert.deepEqual(columns, ['department', 'opus', 'sonnet']);
+  assert.deepEqual(rows, [
+    { department: 'A', opus: 10, sonnet: 5 },
+    { department: 'B', opus: 20, sonnet: 15 },
+  ]);
+});
+
+test('reconstructRows: donut/pie with {name,value} data', () => {
+  const chart_option = {
+    series: [{
+      type: 'pie',
+      data: [
+        { name: 'Engineering', value: 100 },
+        { name: 'Sales', value: 50 },
+      ],
+    }],
+  };
+  const chart_meta = { chart_type: 'donut', x: 'department', y: ['cost'] };
+  const { columns, rows } = chart.reconstructRows(chart_option, chart_meta);
+  assert.deepEqual(columns, ['department', 'cost']);
+  assert.deepEqual(rows, [
+    { department: 'Engineering', cost: 100 },
+    { department: 'Sales', cost: 50 },
+  ]);
+});
+
+test('reconstructRows: dataset.source with header row (array of arrays)', () => {
+  const chart_option = {
+    dataset: {
+      source: [
+        ['provider', 'cost'],
+        ['anthropic', 1234],
+        ['openai', 567],
+      ],
+    },
+  };
+  const { columns, rows } = chart.reconstructRows(chart_option, { chart_type: 'table' });
+  assert.deepEqual(columns, ['provider', 'cost']);
+  assert.deepEqual(rows, [
+    { provider: 'anthropic', cost: 1234 },
+    { provider: 'openai', cost: 567 },
+  ]);
+});
+
+test('reconstructRows: dataset.source as array of objects', () => {
+  const chart_option = {
+    dataset: {
+      source: [
+        { provider: 'anthropic', cost: 1234 },
+        { provider: 'openai', cost: 567 },
+      ],
+    },
+  };
+  const { columns, rows } = chart.reconstructRows(chart_option, { chart_type: 'table' });
+  assert.deepEqual(columns, ['provider', 'cost']);
+  assert.equal(rows.length, 2);
+});
+
+test('reconstructRows: missing chart_option returns empty', () => {
+  assert.deepEqual(chart.reconstructRows(null, null), { columns: [], rows: [] });
+  assert.deepEqual(chart.reconstructRows(undefined, {}), { columns: [], rows: [] });
+  assert.deepEqual(chart.reconstructRows({}, {}), { columns: [], rows: [] });
+});
+
+test('reconstructRows: strips ANSI / control chars from backend-provided labels', () => {
+  const chart_option = {
+    xAxis: { data: ['\x1b]0;pwned\x07Anthropic', 'Open\nAI'] },
+    series: [{ name: 'cost', data: [100, 200] }],
+  };
+  const { rows, columns } = chart.reconstructRows(chart_option, { chart_type: 'bar', x: 'provider', y: ['cost'] });
+  assert.deepEqual(columns, ['provider', 'cost']);
+  assert.equal(rows[0].provider, 'Anthropic');
+  assert.equal(rows[1].provider, 'Open AI');
+});
+
+test('reconstructRows: dataset.source array-of-objects is capped at MAX_RECONSTRUCT_ROWS', () => {
+  const source = Array.from({ length: chart.MAX_RECONSTRUCT_ROWS + 10 }, (_, i) => ({ k: i, v: i * 2 }));
+  const { rows } = chart.reconstructRows({ dataset: { source } }, { chart_type: 'table' });
+  assert.equal(rows.length, chart.MAX_RECONSTRUCT_ROWS);
+});
+
+test('reconstructRows: caps allocation at MAX_RECONSTRUCT_ROWS', () => {
+  const huge = Array.from({ length: chart.MAX_RECONSTRUCT_ROWS + 5000 }, (_, i) => `row${i}`);
+  const hugeVals = huge.map((_, i) => i);
+  const chart_option = {
+    xAxis: { data: huge },
+    series: [{ name: 'v', data: hugeVals }],
+  };
+  const { rows } = chart.reconstructRows(chart_option, { chart_type: 'bar', x: 'p', y: ['v'] });
+  assert.equal(rows.length, chart.MAX_RECONSTRUCT_ROWS);
+});
+
+test('summarizeChart: bar with single y', () => {
+  const s = stripAnsi(chart.summarizeChart({ chart_type: 'bar', x: 'provider', y: ['cost'] }, 4));
+  assert.equal(s, 'Bar chart, x=provider, y=cost, 4 rows');
+});
+
+test('summarizeChart: handles singular row + multi y', () => {
+  const s = stripAnsi(chart.summarizeChart({ chart_type: 'line', x: 'date', y: ['cost', 'tokens'] }, 1));
+  assert.equal(s, 'Line chart, x=date, y=cost+tokens, 1 row');
+});
+
+test('summarizeChart: missing meta degrades gracefully', () => {
+  assert.equal(chart.summarizeChart({}, 0), 'Unknown chart, 0 rows');
+  assert.equal(chart.summarizeChart(null), 'Unknown chart');
+});
+
+test('renderBarChart: lines respect requested width', () => {
+  const rows = [
+    { dept: 'Engineering', cost: 30000 },
+    { dept: 'Sales', cost: 10000 },
+    { dept: 'Marketing', cost: 5000 },
+  ];
+  const out = chart.renderBarChart(rows, 'dept', 'cost', { width: 80 });
+  assert.ok(out.length > 0);
+  for (const line of out.split('\n')) {
+    assert.ok(stripAnsi(line).length <= 80, `line too long: ${stripAnsi(line)}`);
+  }
+});
+
+test('renderBarChart: empty rows returns empty string', () => {
+  assert.equal(chart.renderBarChart([], 'x', 'y'), '');
+  assert.equal(chart.renderBarChart(null, 'x', 'y'), '');
+});
+
+test('renderBarChart: scales the largest value to the full bar area', () => {
+  const rows = [{ x: 'A', y: 100 }, { x: 'B', y: 50 }];
+  const out = stripAnsi(chart.renderBarChart(rows, 'x', 'y', { width: 60 }));
+  const lines = out.split('\n');
+  const blocksA = (lines[0].match(/\u2588/g) || []).length;
+  const blocksB = (lines[1].match(/\u2588/g) || []).length;
+  assert.ok(blocksA > blocksB, 'larger value should produce more blocks');
+  assert.equal(blocksB, Math.max(1, Math.round(blocksA * 50 / 100)));
+});
+
+test('renderBarChart: all-zero values do not crash and produce empty bars', () => {
+  const rows = [{ x: 'A', y: 0 }, { x: 'B', y: 0 }];
+  const out = stripAnsi(chart.renderBarChart(rows, 'x', 'y', { width: 80 }));
+  assert.ok(out.length > 0);
+  assert.equal((out.match(/\u2588/g) || []).length, 0);
+});
+
+test('renderGroupedBarChart: emits a legend and one row per series per label', () => {
+  const rows = [
+    { dept: 'Eng', opus: 100, sonnet: 50 },
+    { dept: 'Sales', opus: 20, sonnet: 80 },
+  ];
+  const out = stripAnsi(chart.renderGroupedBarChart(rows, 'dept', ['opus', 'sonnet'], { width: 80 }));
+  assert.match(out, /Legend:/);
+  assert.match(out, /opus/);
+  assert.match(out, /sonnet/);
+  assert.match(out, /Eng/);
+  assert.match(out, /Sales/);
+});
+
+test('renderSparkline: returns a single-line braille bar between min and max', () => {
+  const out = stripAnsi(chart.renderSparkline([1, 2, 3, 4, 5, 4, 3], { width: 20 }));
+  assert.ok(out.includes('1'));
+  assert.ok(out.includes('5'));
+  assert.equal(out.split('\n').length, 1);
+});
+
+test('renderSparkline: too few points returns empty string', () => {
+  assert.equal(chart.renderSparkline([1]), '');
+  assert.equal(chart.renderSparkline([]), '');
+});
+
+test('formatNumber: integer thousands separator, decimal capped', () => {
+  assert.equal(chart.formatNumber(1234567), '1,234,567');
+  assert.equal(chart.formatNumber(12.3456), '12.35');
+  assert.equal(chart.formatNumber(0), '0');
+});

package/test/chat-internals.test.js

@@ -0,0 +1,144 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const chat = require('../src/commands/chat');
+const { sanitizeForTerminal } = require('../src/chartRender');
+
+const { safeWriteFile, expandPath, normalizeAssistantTurn, friendlyChatError } = chat._internals;
+
+function tmpFile(name) {
+  return path.join(os.tmpdir(), `unbound-cli-test-${process.pid}-${Date.now()}-${name}`);
+}
+
+test('sanitizeForTerminal: strips CSI, OSC, clipboard, title, hyperlink sequences', () => {
+  assert.equal(sanitizeForTerminal('\x1b[31mred\x1b[0m'), 'red');
+  assert.equal(sanitizeForTerminal('\x1b]0;PWNED\x07hi'), 'hi');
+  assert.equal(sanitizeForTerminal('\x1b]52;c;Y3VybHxzaA==\x07ok'), 'ok');
+  assert.equal(sanitizeForTerminal('\x1b]8;;https://evil/\x07click\x1b]8;;\x07'), 'click');
+  assert.equal(sanitizeForTerminal('a\x1bPdata\x1b\\b'), 'ab');
+  assert.equal(sanitizeForTerminal('plain text'), 'plain text');
+});
+
+test('sanitizeForTerminal: strips 8-bit C1 control bytes', () => {
+  // \x9b = 8-bit CSI, \x9d = 8-bit OSC, \x90 = 8-bit DCS. Stripping the
+  // trigger byte neutralizes the sequence; residual parameter text is
+  // harmless without the preceding control byte.
+  const a = sanitizeForTerminal('\x9b31mhello\x9b0m');
+  assert.ok(!/[\x80-\x9f]/.test(a), 'should not contain any C1 bytes');
+  assert.ok(a.includes('hello'));
+  const b = sanitizeForTerminal('a\x9dtitle\x07b');
+  assert.ok(!/[\x80-\x9f]/.test(b));
+  for (let code = 0x80; code <= 0x9f; code++) {
+    assert.equal(sanitizeForTerminal(String.fromCharCode(code)), '');
+  }
+});
+
+test('sanitizeForTerminal: removes control chars but preserves tab; collapses newlines', () => {
+  assert.equal(sanitizeForTerminal('a\x00b\x07c\x7fd'), 'abcd');
+  assert.equal(sanitizeForTerminal('line1\nline2\r\nline3'), 'line1 line2 line3');
+  assert.equal(sanitizeForTerminal('tab\there'), 'tab\there');
+});
+
+test('sanitizeForTerminal: handles non-string inputs safely', () => {
+  assert.equal(sanitizeForTerminal(null), '');
+  assert.equal(sanitizeForTerminal(undefined), '');
+  assert.equal(sanitizeForTerminal(42), '42');
+  assert.equal(sanitizeForTerminal({ a: 1 }), '[object Object]');
+});
+
+test('expandPath: expands leading ~/ to homedir, passes through absolute paths', () => {
+  assert.equal(expandPath('~'), os.homedir());
+  assert.equal(expandPath('~/foo/bar'), path.join(os.homedir(), 'foo/bar'));
+  assert.equal(expandPath('/etc/passwd'), '/etc/passwd');
+});
+
+test('safeWriteFile: happy path writes a new file with mode 0600', () => {
+  const target = tmpFile('happy.json');
+  try {
+    const resolved = safeWriteFile(target, '{"ok":true}\n');
+    assert.equal(resolved, path.resolve(target));
+    assert.equal(fs.readFileSync(target, 'utf8'), '{"ok":true}\n');
+    const stat = fs.statSync(target);
+    assert.equal(stat.mode & 0o777, 0o600);
+  } finally {
+    try { fs.unlinkSync(target); } catch { /* ignore */ }
+  }
+});
+
+test('safeWriteFile: refuses to overwrite existing file', () => {
+  const target = tmpFile('noclobber.json');
+  try {
+    fs.writeFileSync(target, 'original');
+    assert.throws(() => safeWriteFile(target, 'hijacked'), /Refusing to overwrite/);
+    assert.equal(fs.readFileSync(target, 'utf8'), 'original');
+  } finally {
+    try { fs.unlinkSync(target); } catch { /* ignore */ }
+  }
+});
+
+test('safeWriteFile: refuses to follow a symlink', () => {
+  const realTarget = tmpFile('real.txt');
+  const linkTarget = tmpFile('link.json');
+  try {
+    fs.writeFileSync(realTarget, 'original');
+    try {
+      fs.symlinkSync(realTarget, linkTarget);
+    } catch (err) {
+      if (err.code === 'EPERM') return;   // symlink creation not permitted; skip
+      throw err;
+    }
+    assert.throws(() => safeWriteFile(linkTarget, 'hijacked'));
+    assert.equal(fs.readFileSync(realTarget, 'utf8'), 'original');
+  } finally {
+    try { fs.unlinkSync(linkTarget); } catch { /* ignore */ }
+    try { fs.unlinkSync(realTarget); } catch { /* ignore */ }
+  }
+});
+
+test('safeWriteFile: rejects empty, non-string, NUL-containing paths', () => {
+  assert.throws(() => safeWriteFile('', 'x'), /empty/i);
+  assert.throws(() => safeWriteFile(null, 'x'), /empty/i);
+  assert.throws(() => safeWriteFile(42, 'x'), /string/i);
+  assert.throws(() => safeWriteFile('foo\0bar', 'x'), /NUL/);
+});
+
+test('safeWriteFile: rejects writing to a directory', () => {
+  assert.throws(() => safeWriteFile(os.tmpdir(), 'x'), /directory/);
+});
+
+test('normalizeAssistantTurn: accepts user/assistant roles, rejects others', () => {
+  assert.deepEqual(
+    normalizeAssistantTurn({ role: 'assistant', content: 'hi', timestamp: 't' }),
+    { role: 'assistant', content: 'hi', timestamp: 't' },
+  );
+  assert.deepEqual(
+    normalizeAssistantTurn({ role: 'USER', content: 'hi', timestamp: 't' }),
+    { role: 'user', content: 'hi', timestamp: 't' },
+  );
+  assert.equal(normalizeAssistantTurn({ role: 'system', content: 'pwn' }), null);
+  assert.equal(normalizeAssistantTurn({ role: 'tool', content: 'x' }), null);
+  assert.equal(normalizeAssistantTurn(null), null);
+  assert.equal(normalizeAssistantTurn({}), null);
+});
+
+test('normalizeAssistantTurn: caps content length', () => {
+  const big = 'x'.repeat(20000);
+  const turn = normalizeAssistantTurn({ role: 'assistant', content: big });
+  assert.ok(turn.content.length <= 8000);
+});
+
+test('friendlyChatError: maps status codes to role-specific guidance', () => {
+  assert.match(friendlyChatError({ statusCode: 403 }), /Admin or Manager/);
+  assert.match(friendlyChatError({ statusCode: 401 }), /login/);
+  assert.match(friendlyChatError({ statusCode: 429 }), /Rate limited/);
+  assert.equal(friendlyChatError({ statusCode: 500, message: 'boom' }), 'boom');
+  assert.equal(friendlyChatError({ message: 'no status' }), 'no status');
+});
+
+test('friendlyChatError: sanitizes ANSI from backend error messages', () => {
+  const msg = friendlyChatError({ statusCode: 500, message: '\x1b]0;title\x07boom\x1b[31m' });
+  assert.equal(msg, 'boom');
+});