quoxcli 0.3.1 → 0.4.0

package/lib/commands/actions.js

@@ -5,39 +5,52 @@
  * Tracker answers could not be checked against CLI truth. These verbs call the
  * SAME governed tool the Action Tracker UI and the agent use (POST
  * /api/v1/tools/execute, tool_name action_list), so chat, UI and CLI read one
- * source. Writes (add/move/update/delete) stay in chat and the UI for now.
+ * source. `add` and `done` write through the collector route the dashboard
+ * uses (POST/PATCH /api/v1/actions) as the logged-in user, via core/actionItems.js,
+ * the same core the Quox TUI /todo uses. Move/update/delete stay in chat and the UI.
  */
 
-import { formatOutput, formatDetail } from '../core/output.js';
+import { formatOutput, formatDetail, printSuccess } from '../core/output.js';
 import { QuoxError } from '../core/errors.js';
+import { confirmDestructive } from '../core/confirm.js';
 import { executeGovernedTool } from './tool.js';
+import { addActionItem, completeActionItem, moveActionItem, deleteActionItem, STATUS_COLUMNS, PRIORITIES } from '../core/actionItems.js';
 
 const STATUSES = ['todo', 'doing', 'done', 'all'];
+const MAX_PAGES = 50;
 
 async function listItems(ctx, { status = 'all', limit = 100, scope } = {}) {
   if (!STATUSES.includes(status)) {
     throw new QuoxError(`--status must be one of ${STATUSES.join(', ')}`);
   }
-  const input = { status, limit: Math.min(Math.max(Number(limit) || 20, 1), 100) };
-  if (scope) input.scope_id = scope;
-  const data = await executeGovernedTool(ctx, 'action_list', input);
-  const result = data && data.result !== undefined ? data.result : data;
-  if (!result || result.success === false) {
-    throw new QuoxError(`action_list failed: ${(result && (result.error || result.message)) || 'no result'}`);
+  const pageSize = Math.min(Math.max(Number(limit) || 20, 1), 100);
+  // Page through everything: a silent cap at one page hid 4 of 24 items (owner, 2026-10-20).
+  const all = [];
+  for (let page = 1; page <= MAX_PAGES; page++) {
+    const input = { status, limit: pageSize };
+    if (scope) input.scope_id = scope;
+    if (page > 1) input.page = page;
+    const data = await executeGovernedTool(ctx, 'action_list', input);
+    const result = data && data.result !== undefined ? data.result : data;
+    if (!result || result.success === false) {
+      throw new QuoxError(`action_list failed: ${(result && (result.error || result.message)) || 'no result'}`);
+    }
+    all.push(...(Array.isArray(result.items) ? result.items : []));
+    if (!result.hasMore) return all;
   }
-  return Array.isArray(result.items) ? result.items : [];
+  throw new QuoxError(`More than ${MAX_PAGES * pageSize} items; narrow with --status or --scope.`);
 }
 
 export function registerActionsCommands(program, ctx) {
   const actions = program
     .command('actions')
-    .description('Action Tracker items (read-only; add and move items in chat or the dashboard)');
+    .description('Action Tracker items: list, get, add, done, move, delete (edit in chat or the dashboard)');
 
   actions
     .command('list')
     .description('List action items')
     .option('--status <status>', 'todo, doing, done or all', 'all')
-    .option('--limit <n>', 'max items (1-100)', '100')
+    .option('--limit <n>', 'page size (1-100); every page is listed', '100')
     .option('--scope <scopeId>', 'only items in this team/department/division scope')
     .action(async (options) => {
       const items = await listItems({ ...ctx, program }, options);
@@ -58,4 +71,61 @@ export function registerActionsCommands(program, ctx) {
       if (!item) throw new QuoxError(`No action item ${id} among the latest 100 items.`);
       formatDetail(item);
     });
+
+  actions
+    .command('add')
+    .description('Add an Action Tracker item (todo) as the logged-in user')
+    .argument('<text...>', 'what needs doing')
+    .option('--due <date>', 'YYYY-MM-DD, today or tomorrow')
+    .option('--priority <priority>', `one of ${PRIORITIES.join(', ')}`)
+    .option('--description <text>', 'longer notes')
+    .action(async (words, options) => {
+      ctx.auth.requireAuth();
+      const item = await addActionItem(ctx.client, { title: words, due: options.due, priority: options.priority, description: options.description });
+      if (program.opts().output === 'json') return formatDetail(item);
+      printSuccess(`Added action item ${item.id}: ${item.title}${item.due_date ? ` (due ${String(item.due_date).slice(0, 10)})` : ''}`);
+      return undefined;
+    });
+
+  actions
+    .command('done')
+    .description('Mark an Action Tracker item done')
+    .argument('<id>', 'action item id (from `quox actions list`)')
+    .action(async (id) => {
+      ctx.auth.requireAuth();
+      const item = await completeActionItem(ctx.client, id);
+      if (program.opts().output === 'json') return formatDetail(item);
+      printSuccess(`Marked done ${item.id}: ${item.title}`);
+      return undefined;
+    });
+
+  actions
+    .command('move')
+    .description('Move an Action Tracker item to todo, doing or done')
+    .argument('<id>', 'action item id (from `quox actions list`)')
+    .argument('<status>', STATUS_COLUMNS.join(', '))
+    .action(async (id, status) => {
+      ctx.auth.requireAuth();
+      const item = await moveActionItem(ctx.client, id, status);
+      if (program.opts().output === 'json') return formatDetail(item);
+      printSuccess(`Moved ${item.id} to ${item.status}: ${item.title}`);
+      return undefined;
+    });
+
+  actions
+    .command('delete')
+    .description('Delete one of your Action Tracker items (asks first; --yes skips, required without a terminal)')
+    .argument('<id>', 'action item id (from `quox actions list`)')
+    .option('-y, --yes', 'do not ask')
+    .action(async (id, options) => {
+      ctx.auth.requireAuth();
+      if (!(await confirmDestructive(program, { force: options.yes === true }, `Delete action item ${id}?`))) {
+        console.log('Not deleted.');
+        return undefined;
+      }
+      const r = await deleteActionItem(ctx.client, id);
+      if (program.opts().output === 'json') return formatDetail(r);
+      printSuccess(`Deleted ${r.id}${r.title ? `: ${r.title}` : ''}`);
+      return undefined;
+    });
 }

package/lib/commands/agent.js

@@ -8,6 +8,7 @@ import { resolveOrgId } from './helpers.js';
 import { resolveEndpoint } from '../api/endpoints.js';
 import { QuoxApiError } from '../core/errors.js';
 import { loadBundledAssistantsRoster } from '../core/agentAlias.js';
+import { AGENT_FAMILY_IDS } from '../core/agentFamilies.js';
 import { registerAgentAttachCommands } from './agentAttach.js';
 
 // quox#1169: the prompt, domains and parent a user gives their own agent. Auth reads
@@ -64,6 +65,7 @@ export function registerAgentCommands(program, ctx) {
     .option('--level <level>', 'filter by level (0-4)')
     .option('--source <source>', 'registry | org | all', 'all')
     .option('--plugin <id>', 'only agents that require this plugin')
+    .option('--family <id>', `only agents in this family (${AGENT_FAMILY_IDS.join(', ')})`)
     .option('--search <text>', 'substring match on id, name or description')
     .action(async (options) => {
       auth.requireAuth();
@@ -71,6 +73,9 @@ export function registerAgentCommands(program, ctx) {
       if (!['registry', 'org', 'all'].includes(source)) {
         throw new Error(`--source must be registry, org or all (got "${options.source}")`);
       }
+      if (options.family !== undefined && !AGENT_FAMILY_IDS.includes(options.family)) {
+        throw new Error(`unknown family "${options.family}". Valid families: ${AGENT_FAMILY_IDS.join(', ')}`);
+      }
       const notes = [];
 
       // Registered specialists (server roster; bundled roster if the server lacks the route).
@@ -84,7 +89,7 @@ export function registerAgentCommands(program, ctx) {
         } catch (err) {
           notes.push(`note: server registry unavailable (${err.message}); showing the bundled roster, which may be out of date.`);
           registry = loadBundledAssistantsRoster().map(r => ({
-            agent_id: r.id, name: r.name || r.id, level: null, requires_plugin: null, tool_count: null, source: 'registry',
+            agent_id: r.id, name: r.name || r.id, level: null, requires_plugin: null, family: r.family || null, tool_count: null, source: 'registry',
           }));
         }
       }
@@ -113,7 +118,7 @@ export function registerAgentCommands(program, ctx) {
         const key = o.agent_id || o.id;
         const reg = merged.get(key);
         merged.set(key, reg
-          ? { ...reg, ...o, requires_plugin: reg.requires_plugin, description: reg.description ?? o.description, tool_count: o.tool_count ?? reg.tool_count, source: 'org+registry' }
+          ? { ...reg, ...o, requires_plugin: reg.requires_plugin, family: reg.family ?? null, description: reg.description ?? o.description, tool_count: o.tool_count ?? reg.tool_count, source: 'org+registry' }
           : o);
       }
 
@@ -121,6 +126,7 @@ export function registerAgentCommands(program, ctx) {
       if (options.level !== undefined) all = all.filter(r => String(r.level) === String(options.level));
       if (options.status) all = all.filter(r => r.status === options.status);
       if (options.plugin) all = all.filter(r => r.requires_plugin === options.plugin);
+      if (options.family) all = all.filter(r => r.family === options.family);
       if (options.search) {
         const q = options.search.toLowerCase();
         all = all.filter(r => [r.agent_id, r.name, r.description].some(v => String(v ?? '').toLowerCase().includes(q)));
@@ -130,10 +136,11 @@ export function registerAgentCommands(program, ctx) {
       for (const n of notes) console.error(n);
       const dash = (v) => (v === null || v === undefined || v === '' ? '-' : v);
       formatOutput({
-        columns: ['agent_id', 'name', 'source', 'level', 'state', 'tool_count'],
-        headers: ['Agent ID', 'Name', 'Source', 'Level', 'Status/Plugin', 'Tools'],
+        columns: ['agent_id', 'name', 'family', 'source', 'level', 'state', 'tool_count'],
+        headers: ['Agent ID', 'Name', 'Family', 'Source', 'Level', 'Status/Plugin', 'Tools'],
         rows: all.map(r => ({
           ...r,
+          family: dash(r.family),
           level: dash(r.level),
           state: r.status ? r.status : (r.requires_plugin ? `plugin:${r.requires_plugin}` : '-'),
           tool_count: dash(r.tool_count),

package/lib/commands/agentAttach.js

@@ -435,6 +435,38 @@ export function execResultFailed(data) {
   return negative(data.success) || negative(data.ok);
 }
 
+/**
+ * A governed tool that was held for a human returns { success:false, pending:true, approvalId }. That is not a
+ * failure: the approval is filed and waiting. Returns the approval id, or null when the result is not pending.
+ */
+export function execResultPending(data) {
+  if (!data || typeof data !== 'object') return null;
+  const src = data.pending === true ? data : (data.result && typeof data.result === 'object' && data.result.pending === true ? data.result : null);
+  if (!src) return null;
+  return src.approvalId || src.approval_id || (src._approval && src._approval.id) || 'unknown';
+}
+
+/**
+ * A governed tool held by the policy layer answers HTTP 403 with {pending:true, approvalId}: the approval IS filed.
+ * Returns that body when an API error carries one (so the caller renders awaiting approval), else null.
+ */
+export function pendingBodyOfError(err) {
+  const body = err && err.body && typeof err.body === 'object' ? err.body : null;
+  return body && execResultPending(body) ? body : null;
+}
+
+/**
+ * Is this 401/403 really about the attach token? 401 is an unauthenticated bearer. A 403 counts only when the server
+ * says so (attach/lease/token in its code or message); any other 403 is the server's own refusal and is shown verbatim.
+ */
+export function isAttachTokenError(err) {
+  const status = err && err.status;
+  if (status === 401) return true;
+  if (status !== 403) return false;
+  const text = [err && err.code, err && err.body && err.body.error, err && err.body && err.body.error_code, err && err.message].filter(Boolean).join(' ');
+  return /attach|lease|token/i.test(text);
+}
+
 /** The first human-readable error string a failed tool result carries, or a default. */
 function execResultError(data) {
   return (data && (data.error || data.error_code || data.reason || data.message)) || 'tool reported failure';
@@ -1343,13 +1375,17 @@ export function registerAgentAttachCommands(agent, ctx, program) {
         });
       } catch (err) {
         const status = err instanceof QuoxApiError ? err.status : 'network error';
-        if (err instanceof QuoxApiError && (err.status === 401 || err.status === 403)) {
+        const held = err instanceof QuoxApiError ? pendingBodyOfError(err) : null;
+        if (held) {
+          data = held; // the policy layer filed an approval: that is a result, not an error
+        } else if (err instanceof QuoxApiError && isAttachTokenError(err)) {
           throw new Error(
             `POST ${ep.path} failed (${status}): the attach token for "${agentId}" is no longer valid `
             + `(expired or revoked lease). Re-attach with \`quox agent attach ${agentId}\`.`
           );
+        } else {
+          throw new Error(`POST ${ep.path} failed (${status}): ${err.message}`);
         }
-        throw new Error(`POST ${ep.path} failed (${status}): ${err.message}`);
       }
 
       // finding (autonomous loop): the glyph must reflect the TOOL result, not
@@ -1358,14 +1394,17 @@ export function registerAgentAttachCommands(agent, ctx, program) {
       // agent read failures as passes ([error-body-is-not-data] at the CLI
       // surface). Set a non-zero exit code too so a scripted / feedback-loop
       // caller can't mistake it for a pass.
-      const toolOk = !execResultFailed(data);
+      const pendingId = execResultPending(data);
+      const toolOk = pendingId ? true : !execResultFailed(data);
       // Skip the announce line under --json/-o json: a scripted caller parses
       // stdout as a single JSON document, and the glyph line would break that.
       if (program.opts().output !== 'json') {
-        printEvent(line('quox', `exec ${options.tool}`, {
-          result: toolOk ? agentId : `${agentId} · ${execResultError(data)}`,
-          status: toolOk ? 'ok' : 'fail',
-        }));
+        printEvent(line('quox', `exec ${options.tool}`, pendingId
+          ? { result: `${agentId} · awaiting approval ${pendingId}`, status: 'busy' }
+          : {
+            result: toolOk ? agentId : `${agentId} · ${execResultError(data)}`,
+            status: toolOk ? 'ok' : 'fail',
+          }));
       }
       formatDetail(data, { format: program.opts().output, title: `Tool result: ${options.tool}` });
       if (!toolOk) process.exitCode = 1;

package/lib/commands/approvals.js

@@ -34,6 +34,11 @@ export function registerApprovalsCommands(program, ctx) {
       }
       console.log(`Approval ${data.approval_id}  tool: ${data.tool}  status: ${data.status}`
         + (data.executed_at ? `  executed: ${data.executed_at}` : ''));
+      if (data.decided_by) {
+        const who = data.decided_by.name || data.decided_by.id;
+        const via = data.decided_via && data.decided_via.channel ? ` via ${data.decided_via.channel}` : '';
+        console.log(`decided by ${who} (${data.decided_by.actor_type || 'user'})${via} at ${data.decided_at || 'unknown time'}`);
+      }
       if (data.result === null || data.result === undefined) {
         if (data.status === 'pending') console.log('Still pending: a human has not decided yet.');
         else if (data.status === 'resuming') console.log('Approved, executing. Re-run shortly.');

package/lib/commands/ask.js

@@ -96,6 +96,7 @@ export function registerAskCommands(program, { client, auth }) {
     .option('--paths <files...>', 'every test file the commit edits (absolute, worktree or repo-relative: all are normalised)')
     .option('--justify <text>', 'why it is safe, in plain words (required)')
     .option('--why <text>', 'detail: the findings, before and after lines')
+    .option('--recommend <y|n>', 'your advice for the card: y or n (shown as the recommendation)')
     .option('--session <name>', 'which session is asking (default: $QUOX_SESSION)')
     .option('--slot <name>', 'your slot')
     .option('--expires <dur>', 'how long it stays open')
@@ -105,6 +106,7 @@ export function registerAskCommands(program, { client, auth }) {
       // commander lets the parent `ask` swallow flags it shares with this verb (--justify, --why, --session...), so merge both
       const options = { ...ask.opts(), ...Object.fromEntries(Object.entries(subOptions).filter(([, v]) => v !== undefined)) };
       if (!String(options.justify || '').trim()) { err('say why it is safe: --justify "<plain words>"'); process.exitCode = 2; return; }
+      if (!options.recommend) err('tip: add --recommend y|n so the card shows your advice');
       const raw = [].concat(options.paths || []).flatMap((x) => String(x).split(',')).map((x) => x.trim()).filter(Boolean);
       let root;
       try { root = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim(); } catch { root = process.cwd(); }
@@ -114,7 +116,7 @@ export function registerAskCommands(program, { client, auth }) {
       // 2026-10-19: the server truncates long titles, and the attestation names only paths found in title+body,
       // so a 7-file ask covered 3. Every path also goes in the body.
       const files = `Files (${paths.length}):\n${paths.map((p) => `- ${p}`).join('\n')}`;
-      await fileAsk({ ...options, title: `Approve test edits: ${paths.join(' ')}`, why: options.why ? `${files}\n\n${options.why}` : files, yn: true, highRisk: true, justify: options.justify });
+      await fileAsk({ ...options, title: `Approve test edits: ${paths.join(' ')}`, why: options.why ? `${files}\n\n${options.why}` : files, yn: true, highRisk: true, justify: options.justify, recommend: options.recommend });
     });
 
   ask

package/lib/commands/blog.js

@@ -0,0 +1,110 @@
+/**
+ * `quox blog draft submit|list|show|mark-published` (BLOG-DRAFT).
+ *
+ * Submit saves the draft as a NotesQ note in the blog-drafts collection and files a hand-off to
+ * the blog publisher (a line in the publisher's slot plus an inbox item). It NEVER publishes:
+ * publishing is the publisher's governed pipeline after the owner's yes. `mark-published` is the
+ * publisher-side verb that records the URL and tells the originating conversation/objective.
+ */
+
+import { readFileSync } from 'fs';
+import { formatOutput, formatDetail, printSuccess, printInfo } from '../core/output.js';
+import { line as glyphLine, printEvent } from '../core/quoxglyph.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+const isJson = (program) => program.opts().output === 'json';
+const printJson = (d) => console.log(JSON.stringify(d, null, 2));
+
+async function readBody(options, ctx) {
+  if (options.file) return readFileSync(options.file, 'utf-8');
+  if (options.stdin) {
+    const input = ctx.stdin || process.stdin;
+    let buf = '';
+    for await (const chunk of input) buf += chunk;
+    return buf;
+  }
+  return null;
+}
+
+export function registerBlogCommands(program, ctx) {
+  const { client, auth } = ctx;
+  const blog = program.command('blog').description('Blog: hand drafts to the blog publisher (never publishes)');
+  const draft = blog.command('draft').description('Blog drafts: saved as revisioned NotesQ notes in the blog-drafts collection');
+
+  draft
+    .command('submit')
+    .description('Save a draft and hand it to the blog publisher (slot + inbox). Does NOT publish.')
+    .requiredOption('--title <title>', 'post title')
+    .option('--file <path>', 'read the post markdown from a file')
+    .option('--stdin', 'read the post markdown from stdin')
+    .option('--hero <image>', 'hero image path or URL')
+    .option('--tag <tag...>', 'tag (repeatable)')
+    .option('--conversation <id>', 'originating conversation id (so its publication is reported back)')
+    .option('--objective <id>', 'originating objective id')
+    .action(async (options) => {
+      auth.requireAuth();
+      const markdown = await readBody(options, ctx);
+      if (markdown === null) throw new Error('give the post body with --file <path> or --stdin');
+      if (!markdown.trim()) throw new Error('the draft body is empty; nothing to submit');
+      const body = { title: options.title, markdown };
+      if (options.hero) body.hero = options.hero;
+      if (options.tag && options.tag.length) body.tags = options.tag;
+      if (options.conversation) body.conversation_id = options.conversation;
+      if (options.objective) body.objective_id = options.objective;
+      const ep = resolveEndpoint('blog.drafts.submit');
+      const data = await client.post(ep.path, { service: ep.service, body });
+      if (isJson(program)) return printJson(data);
+      printEvent(glyphLine('quox', `blog draft submit "${options.title}"`, `note ${data.note_id}`));
+      printSuccess(`Draft saved as note ${data.note_id} and handed to the publisher slot ${data.slot} (hand-off ${data.handoff_id}).`);
+      if (data.link) console.log(`link: ${data.link}`);
+      printInfo('Not published: nothing goes live until the publisher publishes after the owner approves.');
+    });
+
+  draft
+    .command('list')
+    .description('List blog drafts')
+    .option('--status <status>', 'draft | published')
+    .action(async (options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('blog.drafts.list');
+      const data = await client.get(ep.path, { service: ep.service, query: options.status ? { status: options.status } : {} });
+      if (isJson(program)) return printJson(data);
+      const rows = (data.drafts || []).map((d) => ({ id: d.id, title: d.title, status: d.status, url: d.url || '', updated: d.updated || '' }));
+      if (!rows.length) return printInfo('No blog drafts.');
+      formatOutput({ columns: ['id', 'title', 'status', 'url', 'updated'], rows });
+    });
+
+  draft
+    .command('show')
+    .description('Show one blog draft (body and hand-off facts)')
+    .argument('<id>', 'draft (note) id')
+    .action(async (id) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('blog.drafts.get', { id });
+      const data = await client.get(ep.path, { service: ep.service });
+      if (isJson(program)) return printJson(data);
+      const d = data.draft || {};
+      const { markdown, ...facts } = d;
+      formatDetail(facts);
+      console.log('');
+      console.log(markdown || '');
+    });
+
+  draft
+    .command('mark-published')
+    .description('Publisher side: record the published URL and tell the originating conversation/objective')
+    .argument('<id>', 'draft (note) id')
+    .requiredOption('--url <url>', 'the published https URL')
+    .action(async (id, options) => {
+      auth.requireAuth();
+      if (!/^https:\/\//i.test(options.url)) throw new Error('--url must be an https URL');
+      const ep = resolveEndpoint('blog.drafts.published', { id });
+      const data = await client.post(ep.path, { service: ep.service, body: { url: options.url } });
+      if (isJson(program)) return printJson(data);
+      printSuccess(data.already ? `Draft ${id} was already marked published at ${data.url}.` : `Draft ${id} marked published at ${data.url}.`);
+      if (data.notified) {
+        const n = data.notified;
+        printInfo(`Told: ${[n.conversation_id && `conversation ${n.conversation_id}`, n.objective_id && `objective ${n.objective_id}`, n.inbox_item_id && `inbox ${n.inbox_item_id}`].filter(Boolean).join(', ') || 'inbox only'}.`);
+      }
+    });
+}