unbound-cli 1.13.0 → 1.15.0

package/src/commands/chat.js

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

package/src/commands/download.js

@@ -0,0 +1,245 @@
+const config = require('../config');
+const output = require('../output');
+const downloads = require('../lib/downloads');
+
+const { KINDS, MAX_EXPORT_ROWS, RETENTION_HOURS } = downloads;
+
+function requireLogin() {
+  if (!config.isLoggedIn()) {
+    throw new Error('Not logged in. Run `unbound login` first.');
+  }
+}
+
+const KIND_LIST = Object.entries(KINDS)
+  .map(([kind, meta]) => `  ${kind.padEnd(23)} ${meta.summary}`)
+  .join('\n');
+
+const AGENT_HELP = `
+AGENTS / SCRIPTING
+  A CSV export is prepared by a background worker, so it is three steps. This
+  command does all three and blocks until the file is on disk:
+
+    1. POST   starts a job and returns its ID
+    2. GET    polls the job until it is completed
+    3. GET    signs a short-lived URL and streams the file down
+
+  Exit code is 0 on success and 1 on any error. Diagnostics go to stderr, so
+  stdout carries only the CSV and is safe to pipe.
+
+  Check before you commit — this counts rows without starting anything:
+
+    $ unbound download start logs-export --check --last 7d --json
+    {"row_count":18204,"limit":25000,"exceeds_limit":false,"exact":true}
+
+  A selection over ${MAX_EXPORT_ROWS.toLocaleString()} rows is refused up front with the real count, so
+  narrow the range and retry rather than paging.
+
+  If you stop waiting, the job keeps running. Fetch it within ${RETENTION_HOURS} hours:
+
+    $ unbound download get <job-id> -o out.csv
+
+  Only 3 exports may be preparing at once per organization; a 4th returns an
+  error telling you to wait. Do not poll by re-running the export.
+`;
+
+const FILTER_HELP = `
+TIME RANGE
+  Omit it and the server applies its own default window. --start/--end may be at
+  most 90 days apart, and cannot start earlier than 90 days ago.
+
+FILTERS
+  Repeat --filter with the same key to pass a list; each is sent as its own
+  value, which is how the server reads list filters:
+
+    --filter tool_types=CLAUDE_CODE --filter tool_types=CURSOR
+
+  An unknown filter KEY is silently ignored, so a typo widens the export rather
+  than failing — 'tool_type=CURSOR' returns every tool. An invalid VALUE for a
+  known key IS rejected, with the supported values listed. Run --check first and
+  confirm the count moved.
+`;
+
+/** `--last 7d` / `--last 24h` -> an absolute window the server understands. */
+function resolveLast(value) {
+  const match = String(value).trim().match(/^(\d+)\s*([dh])$/i);
+  if (!match) {
+    throw new Error(`Invalid --last "${value}". Use a number followed by d or h, e.g. 7d or 24h.`);
+  }
+  const amount = Number(match[1]);
+  if (amount < 1) throw new Error('--last must be at least 1.');
+  const hours = match[2].toLowerCase() === 'd' ? amount * 24 : amount;
+  const end = new Date();
+  const start = new Date(end.getTime() - hours * 3600 * 1000);
+  return { start, end };
+}
+
+function buildQueryString(opts) {
+  const params = new URLSearchParams();
+
+  if (opts.last && (opts.start || opts.end)) {
+    throw new Error('Use --last or --start/--end, not both.');
+  }
+  if (Boolean(opts.start) !== Boolean(opts.end)) {
+    throw new Error('--start and --end must be used together.');
+  }
+
+  if (opts.last) {
+    const { start, end } = resolveLast(opts.last);
+    params.set('start_date', start.toISOString());
+    params.set('end_date', end.toISOString());
+  } else if (opts.start) {
+    params.set('start_date', opts.start);
+    params.set('end_date', opts.end);
+  }
+
+  if (opts.search) params.set('search', opts.search);
+
+  // Repeated keys are appended, not replaced: every list filter on the server
+  // reads getlist(), so collapsing duplicates would silently drop all but one.
+  for (const entry of opts.filter || []) {
+    const index = String(entry).indexOf('=');
+    if (index <= 0) {
+      throw new Error(`Invalid --filter "${entry}". Use key=value, e.g. --filter tool_types=CURSOR.`);
+    }
+    params.append(entry.slice(0, index).trim(), entry.slice(index + 1));
+  }
+
+  return params.toString();
+}
+
+async function runDownload(kind, opts) {
+  const query = buildQueryString(opts);
+
+  if (opts.check) {
+    const result = await downloads.checkCount(kind, query);
+    if (opts.json) {
+      output.json(result);
+      return;
+    }
+    const rows = Number(result.row_count);
+    if (!Number.isFinite(rows)) {
+      output.info('This export does not report a row count up front.');
+      return;
+    }
+    if (result.exceeds_limit) {
+      output.warn(
+        `${rows.toLocaleString()} rows, over the ${Number(result.limit).toLocaleString()}-row limit. ` +
+        'Narrow the range or add filters before exporting.'
+      );
+      return;
+    }
+    output.info(`${rows.toLocaleString()} row(s) would be exported.`);
+    return;
+  }
+
+  if (opts.wait === false) {
+    const job = await downloads.startJob(kind, query);
+    if (opts.json) {
+      output.json(job);
+      return;
+    }
+    output.success(`Export started. ${downloads.fetchHint(job.id)}`);
+    return;
+  }
+
+  await downloads.runExport(kind, query, { output: opts.output });
+}
+
+function register(program) {
+  // A group with no arguments and no options of its own. Commander binds a
+  // repeated flag on the parent, so `-o` declared on both here and on `get`
+  // would leave the subcommand's value undefined and silently write to stdout.
+  const group = program
+    .command('download')
+    .description('Export org data as CSV (Logs, Tasks, Users, Tool Use).')
+    .addHelpText('after', `
+KINDS
+${KIND_LIST}
+
+Examples:
+  $ unbound download kinds
+  $ unbound download start logs-export --last 7d
+  $ unbound download start logs-export --check --last 90d --json
+  $ unbound download get 4f2a1c9e-1b2c-4d5e-8f90-a1b2c3d4e5f6
+
+Admin role required. Exports are kept for ${RETENTION_HOURS} hours.
+`);
+
+  group
+    .command('kinds')
+    .description('List what can be exported, and the filters each kind accepts.')
+    .option('--json', 'Machine-readable output')
+    .action((opts) => {
+      if (opts.json) {
+        output.json(Object.entries(KINDS).map(([kind, meta]) => ({ kind, ...meta })));
+        return;
+      }
+      for (const [kind, meta] of Object.entries(KINDS)) {
+        console.log(`${kind}\n  ${meta.summary}\n  filters: ${meta.filters.join(', ')}\n`);
+      }
+    });
+
+  const command = group
+    .command('start <kind>')
+    .description('Start an export and wait for the file.')
+    .option('--last <window>', 'Relative range, e.g. 7d or 24h')
+    .option('--start <date>', 'Range start, YYYY-MM-DD (use with --end)')
+    .option('--end <date>', 'Range end, YYYY-MM-DD (use with --start)')
+    .option('--search <text>', 'Free-text filter (logs kinds only)')
+    .option('--filter <key=value>', 'Server-side filter, repeatable', (value, previous) => (previous || []).concat(value))
+    .option('-o, --output <file>', 'Write to a file instead of the server-chosen name')
+    .option('--check', 'Print how many rows would be exported, then exit')
+    .option('--json', 'Machine-readable output')
+    .option('--no-wait', 'Start the export and print its job ID instead of waiting')
+    .addHelpText('after', `
+KINDS
+${KIND_LIST}
+
+Examples:
+  $ unbound download start logs-export --last 7d
+  $ unbound download start logs-export --last 24h --filter tool_types=CLAUDE_CODE -o today.csv
+  $ unbound download start logs-tasks-export --start 2026-07-01 --end 2026-07-31
+  $ unbound download start users-export --last 30d
+  $ unbound download start analytics-export --filter dataset=terminal-runs --last 7d
+  $ unbound download start logs-export --check --last 90d --json
+
+Admin role required. Exports are kept for ${RETENTION_HOURS} hours.
+${FILTER_HELP}${AGENT_HELP}`)
+    .action(async (kind, opts) => {
+      try {
+        requireLogin();
+        await runDownload(kind, opts);
+      } catch (err) {
+        output.error(downloads.describeError(err, `${kind} export`));
+        process.exitCode = 1;
+      }
+    });
+
+  group
+    .command('get <job-id>')
+    .description('Download an export that was already started, by its job ID.')
+    .option('-o, --output <file>', 'Write to a file instead of the server-chosen name')
+    .addHelpText('after', `
+Exports run in the background. If you interrupted the wait, or used --no-wait,
+this fetches the finished file. If the job is still running, it waits for it.
+
+Exports are kept for ${RETENTION_HOURS} hours.
+
+Examples:
+  $ unbound download get 4f2a1c9e-1b2c-4d5e-8f90-a1b2c3d4e5f6
+  $ unbound download get 4f2a1c9e-1b2c-4d5e-8f90-a1b2c3d4e5f6 -o july.csv
+`)
+    .action(async (jobId, opts) => {
+      try {
+        requireLogin();
+        await downloads.fetchExisting(jobId, { output: opts.output });
+      } catch (err) {
+        output.error(downloads.describeError(err, 'export', { byJobId: true }));
+        process.exitCode = 1;
+      }
+    });
+
+  return command;
+}
+
+module.exports = { register, buildQueryString, resolveLast };

package/src/index.js

@@ -155,6 +155,18 @@ TOOL CONNECTIONS
   $ unbound tools connect <type>           Connect a new tool
   $ unbound tools approved                 List approved tool types
 
+ANALYTICS (Admin/Manager; CSV export is Admin-only)
+  $ unbound analytics tool-use terminal     Terminal commands agents ran
+  $ unbound analytics tool-use mcp-servers  MCP servers seen (find --server values here)
+  $ unbound analytics tool-use mcp-actions --server Notion
+                                           MCP tool calls for one service
+  $ unbound analytics tool-use unsanctioned Blocked/warned unsanctioned MCP usage
+
+  Every dataset takes --format table|json|csv, -o <file>, --limit/--offset,
+  --time-window or --start/--end, and filters (--tool --user --risk --policy).
+  csv exports every matching row, not just the page.
+  See "unbound analytics tool-use --help" for the JSON contract used by agents.
+
 CHAT (Admin/Manager)
   $ unbound chat                           Interactive REPL (multi-turn, in-memory history)
   $ unbound chat -m "show cost by provider for the last 30 days"
@@ -196,6 +208,8 @@ require('./commands/policy').register(program);
 require('./commands/users').register(program);
 require('./commands/user-groups').register(program);
 require('./commands/tools').register(program);
+require('./commands/analytics').register(program);
+require('./commands/download').register(program);
 require('./commands/setup').register(program);
 require('./commands/discover').register(program);
 require('./commands/onboard').register(program);