quoxcli 0.2.0 → 0.4.0

package/lib/commands/hat.js

@@ -1,18 +1,23 @@
 /**
- * QuoxHat commands (QUOXHAT #721 b): READ-ONLY views of the org's hats.
+ * QuoxHat commands (QUOXHAT #721 b; CUSTOM-HATS 2026-10-17).
  *
  *   quox hat list
  *   quox hat show <id|key> [--rev <n>]
- *   quox hat reset <id|key> --yes      (audited reset-to-template)
+ *   quox hat reset <id|key> --yes      (audited reset-to-template, built-ins)
+ *   quox hat upgrade <id|key> [--dry-run|--yes]  (3-way merge of an org-edited built-in onto the current template)
+ *   quox hat create <key> --name "<Name>" [--from <hat>] [--agents a,b] [--tools x,y] [--mode m] [--offer o]
+ *   quox hat edit <hat> [--name N] [--add-agents|--remove-agents|--agents] [--add-tools|--remove-tools|--tools] [--mode m]
+ *   quox hat delete <hat> --yes        (custom hats only)
+ *   quox hat use <hat> --conversation <id> [--yes]
  *
- * Shows what each hat presents (explicit tools, bundles, connector families),
- * its authorization mode, revision, template status and the org's enforcement
- * and selection mode. Editing hat definitions is deliberately NOT here: edits
- * go through the dashboard (Settings, QuoxHat Modes) where they are validated
- * and audited. The one write is `reset`, which returns an org-edited built-in
- * to its current template through the same audited route the dashboard uses.
+ * Custom hats (owner 2026-10-17): users who build their own agents organise them under their own
+ * hats, so a turn under "security" carries only the security agents, not every agent in the org.
+ * create/edit/delete act on CUSTOM hats only; a built-in is reset to its template, or copied with --from.
+ * Everything is server-side, org-scoped, revisioned and audited (services/auth/routes/quoxhat.js);
+ * who may create or change an org hat is the existing hat-edit permission (org manage-settings),
+ * a private hat (--private) only its owner. This file never decides permission itself.
  *
- * Backend: services/auth/routes/quoxhat.js (see cli/lib/api/endpoints/quoxhat.js).
+ * Backend: services/auth/routes/quoxhat.js (see cli/lib/api/endpoints/hat.js).
  */
 
 import chalk from 'chalk';
@@ -38,6 +43,12 @@ export function templateLabel(hat) {
   const latestAuthor = Array.isArray(hat.revisions) && hat.revisions[0] ? hat.revisions[0].created_by : null;
   const customised = typeof latestAuthor === 'string' && !latestAuthor.startsWith('template:');
   if (latest && cur && cur < latest) return `v${cur} (template v${latest} available)`;
+  // Merge-upgrade: the last applied 3-way merge (org edits carried onto the new template).
+  const u = hat.last_upgrade;
+  if (u && u.to_template_version === cur) {
+    const k = Number(u.org_changes_kept) || 0;
+    return `v${cur}, upgraded from v${u.from_template_version}, ${k} org change${k === 1 ? '' : 's'} kept`;
+  }
   return customised ? `v${cur || '?'} (edited)` : `v${cur || '?'}`;
 }
 
@@ -59,6 +70,56 @@ export function findHat(hats, ref) {
   return (hats || []).find(h => h.id === r) || (hats || []).find(h => h.key === r) || null;
 }
 
+
+export { DELEGATION_TOOLS, HAT_MODES, HAT_OFFERS, parseList, memberTools, applyMode, buildCustomDefinition, applyHatEdits } from '../core/customHats.js';
+import { parseList, memberTools, buildCustomDefinition, applyHatEdits } from '../core/customHats.js';
+
+/** Which of `ids` no registered or org agent matches. checked=false when neither list could be read. */
+export async function findUnknownAgents(client, orgId, ids) {
+  if (!ids.length) return { unknown: [], checked: true };
+  const known = new Set();
+  let read = 0;
+  try {
+    const ep = resolveEndpoint('v1.agents.registry');
+    const d = await client.get(ep.path, { service: ep.service });
+    if (Array.isArray(d?.agents)) { read++; for (const a of d.agents) if (a?.agent_id) known.add(String(a.agent_id).toLowerCase()); }
+  } catch { /* named below */ }
+  try {
+    const ep = resolveEndpoint('agents.list', { orgId });
+    const d = await client.get(ep.path, { service: ep.service });
+    const rows = Array.isArray(d?.agents) ? d.agents : (Array.isArray(d) ? d : null);
+    if (rows) { read++; for (const a of rows) { const id = a?.agent_id || a?.agentId; if (id) known.add(String(id).toLowerCase()); } }
+  } catch { /* named below */ }
+  if (!read) return { unknown: [], checked: false };
+  return { unknown: ids.filter(id => !known.has(id)), checked: true };
+}
+
+function isBuiltin(h) { return !!h?.template_key; }
+
+const fmtItem = (e) => (e.item !== undefined ? `${e.path}: ${e.item}` : e.path);
+
+/** Human preview of a merge upgrade (exported for reuse by other surfaces). */
+export function renderUpgradePreview(key, p) {
+  const out = [];
+  out.push(chalk.bold(`Hat ${key}: template v${p.from_template_version} -> v${p.to_template_version}`) + chalk.dim(`  (from rev ${p.from_revision})`));
+  out.push(`Tools added:    ${(p.tools_added || []).join(', ') || 'none'}`);
+  out.push(`Tools removed:  ${(p.tools_removed || []).join(', ') || 'none'}`);
+  const changed = (p.template_changed || []).map(c => c.path);
+  if (changed.length) out.push(`Template changed: ${changed.join(', ')}`);
+  out.push(chalk.bold(`Org changes kept (${(p.org_changes || []).length}):`));
+  for (const c of p.org_changes || []) out.push(`  ${c.change.padEnd(7)} ${fmtItem(c)}`);
+  if (!(p.org_changes || []).length) out.push('  none');
+  out.push(chalk.bold(`Conflicts, org choice kept (${(p.conflicts || []).length}):`));
+  for (const c of p.conflicts || []) out.push(`  ${c.path}${c.reason ? ` (${c.reason})` : ''}`);
+  if (!(p.conflicts || []).length) out.push('  none');
+  out.push(chalk.bold(`Held, would widen authorization (${(p.held || []).length}):`));
+  for (const c of p.held || []) out.push(`  ${c.path} ${(c.fields || []).join(', ')}`);
+  if (!(p.held || []).length) out.push('  none');
+  out.push(`Valid:          ${p.valid ? 'yes' : `NO: ${(p.errors || []).join('; ')}`}`);
+  out.push(`Digest:         ${p.from_digest || '-'} -> ${p.digest}`);
+  return out;
+}
+
 export function registerHatCommands(program, ctx) {
   const { client, auth } = ctx;
 
@@ -154,6 +215,8 @@ export function registerHatCommands(program, ctx) {
       out.push(`Enforcement:  ${enforcement} (org)`);
       out.push(`Transitions:  confirm=${def.transitions?.confirm || 'none'} privileged=${def.transitions?.privileged ? 'yes' : 'no'}`);
       out.push(`Agents:       orchestrator=${def.agents?.orchestrator || '-'} specialists=${(def.agents?.specialists || []).join(', ') || 'none'}`);
+      out.push(`Offer:        ${def.tools?.offer === 'members' ? 'members (an orchestrator turn is offered only this hat\'s tools)' : 'authorized (hat tools first, then the rest of the grant)'}`);
+      out.push(`Kind:         ${h.template_key ? 'built-in' : 'custom'}${h.visibility === 'private' ? ' (private)' : ''}`);
       out.push(`Budgets:      initial_tool_target=${def.budgets?.initial_tool_target ?? '-'} max_manifest=${def.budgets?.max_manifest ?? '-'}`);
       out.push('');
       const explicit = def.tools?.explicit || [];
@@ -202,4 +265,186 @@ export function registerHatCommands(program, ctx) {
       if (program.opts().output === 'json') { console.log(JSON.stringify({ hat: h }, null, 2)); return; }
       console.log(`  Ⓠ QUOX │ hat ${h.key} reset to template │ rev ${h.current_revision} · ${templateLabel(h)} ✔`);
     });
+  // ── hat upgrade ─────────────────────────────────────────────────────────────
+  hat
+    .command('upgrade <hat>')
+    .description('Carry an org-edited built-in hat onto the current template (3-way merge: org changes kept, conflicts keep the org choice, widening authz changes held); previews unless --yes')
+    .option('--dry-run', 'preview the merge only (writes nothing); the default without --yes')
+    .option('--yes', 'apply the previewed merge as a new system-authored revision (audited)')
+    .action(async (ref, options) => {
+      auth.requireAuth();
+      if (options.dryRun && options.yes) throw new Error('Pass either --dry-run (preview) or --yes (apply), not both.');
+      const orgId = resolveOrgId(auth, program);
+      const list = await fetchList(client, orgId);
+      const found = findHat(list?.hats, ref);
+      if (!found) {
+        const keys = (list?.hats || []).map(h => h.key).join(', ') || 'none';
+        throw new Error(`No hat '${ref}' in this org. Available: ${keys}`);
+      }
+      const pep = resolveEndpoint('hat.upgrade.preview', { orgId, hatId: found.id });
+      let data;
+      try {
+        data = await client.get(pep.path, { service: pep.service });
+      } catch (err) {
+        const code = err?.response?.data?.error || err?.data?.error || err?.body?.error;
+        if (code === 'up_to_date') { console.log(`  Ⓠ QUOX │ hat ${found.key} upgrade │ already on template v${found.template_version} ✔`); return; }
+        throw err;
+      }
+      const p = data?.preview;
+      if (!p) throw new Error(`Upgrade preview for '${ref}' returned nothing`);
+      const json = program.opts().output === 'json';
+
+      if (!options.yes) {
+        if (json) { console.log(JSON.stringify({ preview: p, applied: false }, null, 2)); return; }
+        console.log(renderUpgradePreview(found.key, p).join('\n'));
+        console.log('');
+        console.log(`  dry run: nothing written. Apply with: quox hat upgrade ${found.key} --yes`);
+        return;
+      }
+      if (!p.valid) throw new Error(`The merged hat does not validate: ${(p.errors || []).join('; ')}`);
+      const aep = resolveEndpoint('hat.upgrade', { orgId, hatId: found.id });
+      const res = await client.post(aep.path, { service: aep.service, body: { expected_revision: p.from_revision } });
+      const h = res?.hat;
+      if (!h) throw new Error(`Upgrade of '${ref}' returned no hat`);
+      if (json) { console.log(JSON.stringify({ hat: h, preview: res.preview || p, applied: true }, null, 2)); return; }
+      console.log(`  Ⓠ QUOX │ hat ${h.key} upgraded │ rev ${h.current_revision} · ${templateLabel(h)} ✔`);
+    });
+
+  // ── hat create (custom) ───────────────────────────────────────────────────────
+  hat
+    .command('create <key>')
+    .description('Create a custom hat: the agents and tools it lists are the only ones a turn under it carries')
+    .requiredOption('--name <name>', 'display name, e.g. "Security"')
+    .option('--from <hat>', 'start from a copy of this hat (key or id)')
+    .option('--agents <ids>', 'comma-separated agent ids this hat puts in scope (registered or your own agents)')
+    .option('--tools <names>', 'comma-separated tool names the orchestrator is offered under this hat')
+    .option('--mode <mode>', 'permissive (default: each agent keeps its own grant) or restrictive (only the listed tools are authorized, for every agent under the hat)')
+    .option('--offer <offer>', 'members (default: offer only this hat\'s tools) or authorized')
+    .option('--purpose <text>', 'one line: what this hat is for')
+    .option('--private', 'a private hat only you can see and wear (needs no org settings permission)')
+    .option('--reason <text>', 'why (kept in the revision history)')
+    .action(async (key, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const k = String(key || '').trim().toLowerCase();
+      if (!/^[a-z0-9][a-z0-9-]{1,40}$/.test(k)) throw new Error(`Hat key '${key}' must be a lowercase slug (a-z, 0-9, hyphen), 2-41 characters.`);
+      const list = await fetchList(client, orgId);
+      const hats = list?.hats || [];
+      if (findHat(hats, k)) throw new Error(`A hat with key '${k}' already exists in this org. Use quox hat edit ${k}.`);
+      let base = null;
+      if (options.from) {
+        const from = findHat(hats, options.from);
+        if (!from) throw new Error(`No hat '${options.from}' to copy. Available: ${hats.map(h => h.key).join(', ') || 'none'}`);
+        base = from.definition;
+      }
+      const agents = options.agents !== undefined ? parseList(options.agents) : undefined;
+      const tools = options.tools !== undefined ? parseList(options.tools) : undefined;
+      const { definition, autoAdded } = buildCustomDefinition({ base, name: options.name, purpose: options.purpose, agents, tools, mode: options.mode, offer: options.offer });
+      const named = definition.agents.specialists;
+      const check = await findUnknownAgents(client, orgId, named);
+      if (check.unknown.length) throw new Error(`Unknown agent(s): ${check.unknown.join(', ')}. See quox agent list.`);
+      const ep = resolveEndpoint('hat.create', { orgId });
+      const data = await client.post(ep.path, { service: ep.service, body: { key: k, name: String(options.name).trim(), definition, visibility: options.private ? 'private' : 'org' } });
+      const h = data?.hat;
+      if (!h) throw new Error(`Create of '${k}' returned no hat`);
+      if (program.opts().output === 'json') { console.log(JSON.stringify({ hat: h, warnings: data.warnings || [], auto_added_tools: autoAdded }, null, 2)); return; }
+      const d = h.definition || definition;
+      console.log(`  Ⓠ QUOX │ hat ${h.key} created │ rev ${h.current_revision} · agents ${(d.agents?.specialists || []).join(', ') || 'none'} · ${memberTools(d).length} tool(s) · offer ${d.tools?.offer || 'authorized'} · ${authzMode(d)} ✔`);
+      if (autoAdded.length) printInfo(`Added ${autoAdded.join(', ')} so the orchestrator can reach the hat's agents.`);
+      if (!check.checked) printInfo('Agent ids were not checked: the agent lists could not be read.');
+      if (d.authz?.mode === 'restrictive') printInfo('Restrictive: every agent working under this hat, its own agents included when delegated to, may only run the tools listed here.');
+      for (const w of data.warnings || []) printInfo(`warning: ${w}`);
+      printInfo(`Wear it: /hat ${h.key} in quox, or quox hat use ${h.key} --conversation <id>.`);
+    });
+
+  // ── hat edit (custom) ─────────────────────────────────────────────────────────
+  hat
+    .command('edit <hat>')
+    .description('Change a custom hat: add or remove agents and tools, rename, mode (appends an audited revision)')
+    .option('--name <name>', 'rename the hat')
+    .option('--purpose <text>', 'new one-line purpose')
+    .option('--agents <ids>', 'replace the agent list')
+    .option('--add-agents <ids>', 'comma-separated agents to add')
+    .option('--remove-agents <ids>', 'comma-separated agents to remove')
+    .option('--tools <names>', 'replace the explicit tool list')
+    .option('--add-tools <names>', 'comma-separated tools to add')
+    .option('--remove-tools <names>', 'comma-separated tools to remove')
+    .option('--mode <mode>', 'permissive or restrictive')
+    .option('--offer <offer>', 'members or authorized')
+    .option('--reason <text>', 'why (kept in the revision history)')
+    .action(async (ref, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const list = await fetchList(client, orgId);
+      const found = findHat(list?.hats, ref);
+      if (!found) throw new Error(`No hat '${ref}' in this org. Available: ${(list?.hats || []).map(h => h.key).join(', ') || 'none'}`);
+      if (isBuiltin(found)) throw new Error(`'${found.key}' is a built-in hat: quox hat edit changes custom hats only. Reset it with quox hat reset ${found.key} --yes, or make your own from it: quox hat create <key> --name "<Name>" --from ${found.key}.`);
+      const opts = {
+        agents: options.agents !== undefined ? parseList(options.agents) : undefined,
+        addAgents: parseList(options.addAgents),
+        removeAgents: parseList(options.removeAgents),
+        tools: options.tools !== undefined ? parseList(options.tools) : undefined,
+        addTools: parseList(options.addTools),
+        removeTools: parseList(options.removeTools),
+        mode: options.mode,
+        offer: options.offer,
+        purpose: options.purpose,
+      };
+      const { definition, changes } = applyHatEdits(found.definition, opts);
+      const rename = options.name !== undefined && String(options.name).trim() !== found.name ? String(options.name).trim() : undefined;
+      if (rename !== undefined) changes.unshift(`name "${found.name}" -> "${rename}"`);
+      if (!changes.length) throw new Error(`Nothing to change on '${found.key}'.`);
+      const newAgents = [...(opts.agents || []), ...opts.addAgents];
+      const check = await findUnknownAgents(client, orgId, newAgents);
+      if (check.unknown.length) throw new Error(`Unknown agent(s): ${check.unknown.join(', ')}. See quox agent list.`);
+      const ep = resolveEndpoint('hat.update', { orgId, hatId: found.id });
+      const data = await client.put(ep.path, { service: ep.service, body: { definition, ...(rename !== undefined ? { name: rename } : {}), change_reason: options.reason || changes.join('; ') } });
+      const h = data?.hat;
+      if (!h) throw new Error(`Edit of '${found.key}' returned no hat`);
+      if (program.opts().output === 'json') { console.log(JSON.stringify({ hat: h, changes, warnings: data.warnings || [] }, null, 2)); return; }
+      console.log(`  Ⓠ QUOX │ hat ${h.key} edited │ rev ${h.current_revision} · ${changes.join(' · ')} ✔`);
+      for (const w of data.warnings || []) printInfo(`warning: ${w}`);
+    });
+
+  // ── hat delete (custom) ───────────────────────────────────────────────────────
+  hat
+    .command('delete <hat>')
+    .description('Delete a custom hat (built-ins cannot be deleted; reset them instead). Audited.')
+    .option('--yes', 'confirm: conversations wearing it fall back to the default hat')
+    .action(async (ref, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const list = await fetchList(client, orgId);
+      const found = findHat(list?.hats, ref);
+      if (!found) throw new Error(`No hat '${ref}' in this org. Available: ${(list?.hats || []).map(h => h.key).join(', ') || 'none'}`);
+      if (isBuiltin(found)) throw new Error(`'${found.key}' is a built-in hat and cannot be deleted. quox hat reset ${found.key} --yes returns it to its template.`);
+      if (!options.yes) throw new Error(`Deleting '${found.key}' moves every conversation wearing it back to the default hat. Re-run with --yes to confirm.`);
+      const ep = resolveEndpoint('hat.delete', { orgId, hatId: found.id });
+      const data = await client.delete(ep.path, { service: ep.service });
+      const d = data?.deleted;
+      if (!d) throw new Error(`Delete of '${found.key}' returned no confirmation`);
+      if (program.opts().output === 'json') { console.log(JSON.stringify({ deleted: d }, null, 2)); return; }
+      console.log(`  Ⓠ QUOX │ hat ${d.key} deleted │ was rev ${d.revision} · ${d.bindings_cleared} conversation(s) moved to the default · ${d.user_prefs_cleared} preference(s) cleared ✔`);
+    });
+
+  // ── hat use ───────────────────────────────────────────────────────────────────
+  hat
+    .command('use <hat>')
+    .description('Wear a hat in one conversation (the same audited switch as /hat <name> in quox)')
+    .requiredOption('--conversation <id>', 'the conversation to switch')
+    .option('--yes', 'confirm a privileged hat')
+    .action(async (ref, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const list = await fetchList(client, orgId);
+      const found = findHat(list?.hats, ref);
+      if (!found) throw new Error(`No hat '${ref}' in this org. Available: ${(list?.hats || []).map(h => h.key).join(', ') || 'none'}`);
+      if (found.definition?.transitions?.privileged && !options.yes) throw new Error(`'${found.key}' is a privileged hat. Re-run with --yes to wear it.`);
+      const ep = resolveEndpoint('hat.bind', { orgId, conversationId: options.conversation });
+      const data = await client.put(ep.path, { service: ep.service, body: { hat_id: found.id } });
+      const b = data?.binding;
+      if (!b) throw new Error(`Switch to '${found.key}' returned no binding`);
+      if (program.opts().output === 'json') { console.log(JSON.stringify({ binding: b, hat: { id: found.id, key: found.key } }, null, 2)); return; }
+      console.log(`  Ⓠ QUOX │ conversation ${options.conversation} now wears ${found.key} │ rev ${b.revision} · seq ${b.seq} ✔`);
+    });
 }

package/lib/commands/helpers.js

@@ -2,7 +2,7 @@
  * Shared helpers for command modules
  */
 
-import { QuoxValidationError } from '../core/errors.js';
+import { QuoxValidationError, QuoxNetworkError } from '../core/errors.js';
 
 /**
  * Resolve the active org ID from --org flag or stored auth.
@@ -77,3 +77,20 @@ export function buildListQuery(options) {
   if (options.sort) query.sort = options.sort;
   return query;
 }
+
+/**
+ * Run a request; if it times out, rethrow with what timed out and how to narrow
+ * it (still a QuoxNetworkError, so the exit code stays 7). A bare
+ * "Request timed out after 30000ms" does not tell the operator which call hung
+ * or what to try (quox#806, quox#807).
+ */
+export async function withTimeoutHint(what, hint, fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    if (err instanceof QuoxNetworkError && /timed out/i.test(err.message || '')) {
+      throw new QuoxNetworkError(`${what} timed out (${err.message}). ${hint}`, err);
+    }
+    throw err;
+  }
+}

package/lib/commands/hyperion.js

@@ -0,0 +1,58 @@
+/**
+ * `quox hyperion`: everything HYPERION (the governed Proxmox operator, agent id atlas) is doing in one place.
+ * Collector route GET /api/v1/proxmox/activity (org-scoped, read only).
+ *
+ *   quox hyperion [status] [--json]   VMs and who holds them, node load, pool counts, last 5 ops
+ *   quox hyperion deck                live full-screen view, refreshes every 10s (q quits, r refreshes)
+ */
+import { line as glyphLine, printEvent } from '../core/quoxglyph.js';
+import { fetchActivity, statusLines, summaryText } from '../core/hyperion.js';
+
+export function registerHyperionCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const hy = program
+    .command('hyperion')
+    .description('HYPERION activity: which VMs exist, who holds each and why, node load and recent operations')
+    .option('--json', 'print the full JSON response');
+
+  const wantJson = (cmd) => {
+    const o = cmd.optsWithGlobals ? cmd.optsWithGlobals() : cmd.opts();
+    return Boolean(o.json) || program.opts().output === 'json';
+  };
+
+  // An error body is not data: report the status and stop.
+  async function show(cmd) {
+    auth.requireAuth();
+    let data;
+    try {
+      data = await fetchActivity(client);
+    } catch (err) {
+      const status = err && (err.status || err.statusCode);
+      if (!status) throw err;
+      console.error(`HYPERION request failed: HTTP ${status}${err.message ? ` ${err.message}` : ''}`);
+      process.exitCode = 1;
+      return;
+    }
+    if (wantJson(cmd)) { console.log(JSON.stringify(data, null, 2)); return; }
+    printEvent(glyphLine('hyperion', 'activity', { result: summaryText(data) }));
+    console.log(statusLines(data).join('\n'));
+  }
+
+  hy.action(async (_o, cmd) => show(cmd));
+
+  hy
+    .command('status')
+    .description('Same as bare `quox hyperion`')
+    .option('--json', 'print the full JSON response')
+    .action(async (_o, cmd) => show(cmd));
+
+  hy
+    .command('deck')
+    .description('Live full-screen HYPERION deck (refreshes every 10s; r refreshes, q quits)')
+    .action(async () => {
+      auth.requireAuth();
+      const { launchHyperionDeck } = await import('../hyperion/deck.js');
+      await launchHyperionDeck({ activity: () => fetchActivity(client) });
+    });
+}

package/lib/commands/image.js

@@ -0,0 +1,68 @@
+/**
+ * quox image generate "<prompt>" [--out file] [--provider gemini|openai] [--aspect-ratio 16:9] [--count n]
+ *
+ * CLI verb first for image generation. It runs the SAME governed tool the chat uses (gemini_image_generate via
+ * POST /api/v1/tools/execute), so the provider fallback, the receipt/witnessing and the plain all-fail message are
+ * the collector's, not re-implemented here. Providers tried: Gemini, then OpenAI, using only what the org already
+ * connected (`quox provider list`). Nothing here adds a provider or a key.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { printSuccess } from '../core/output.js';
+import { executeGovernedTool } from './tool.js';
+
+const EXT = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp' };
+
+export function registerImageCommands(program, ctx) {
+  const { client, auth } = ctx;
+  const image = program.command('image').description('Generate images with the providers your org has connected');
+
+  image
+    .command('generate')
+    .description('Generate an image from a prompt (tries Gemini, then OpenAI; says which made it)')
+    .argument('<prompt>', 'what to draw')
+    .option('--out <file>', 'where to save the image (default ./quox-image-<time>.png)')
+    .option('--provider <name>', 'use only this provider: gemini or openai (no fall-through)')
+    .option('--aspect-ratio <ratio>', 'e.g. 16:9 for a hero, 1:1 for social, 9:16 for stories')
+    .option('--count <n>', 'how many images (1-4)', '1')
+    .action(async (prompt, options) => {
+      const input = { prompt };
+      if (options.provider) input.provider = options.provider;
+      if (options.aspectRatio) input.aspect_ratio = options.aspectRatio;
+      const n = Number(options.count);
+      if (n > 1) input.number_of_images = Math.min(n, 4);
+
+      const data = await executeGovernedTool({ client, auth, program }, 'gemini_image_generate', input, { reason: 'quox image generate' });
+      const r = (data && data.result && typeof data.result === 'object') ? data.result : (data || {});
+      const failed = (data && data.success === false) || r.success === false;
+
+      if (program.opts().output === 'json') {
+        // Never dump base64 into a terminal or a pipe: report where the files went.
+        const out = failed ? r : { ...r, images: undefined };
+        if (!failed) out.files = saveImages(r.images, options.out);
+        console.log(JSON.stringify({ ...out, ...(failed && !r.error && data.error ? { error: data.error } : {}) }, null, 2));
+        if (failed) process.exitCode = 1;
+        return;
+      }
+      if (failed) {
+        console.error(r.error || data.error || 'Image generation failed.');
+        process.exitCode = 1;
+        return;
+      }
+      const files = saveImages(r.images, options.out);
+      printSuccess(`Made by ${r.provider_used || 'gemini'}${r.model_used ? ` (${r.model_used})` : ''}: ${files.join(', ')}`);
+      if (r.note) console.log(r.note);
+    });
+}
+
+function saveImages(images, out) {
+  const list = Array.isArray(images) ? images : [];
+  const stamp = Date.now();
+  return list.map((img, i) => {
+    const ext = EXT[img.mime_type] || 'png';
+    let file = out || `quox-image-${stamp}.${ext}`;
+    if (list.length > 1) { const p = path.parse(file); file = path.join(p.dir, `${p.name}-${i + 1}${p.ext || `.${ext}`}`); }
+    fs.writeFileSync(file, Buffer.from(img.base64, 'base64'));
+    return file;
+  });
+}

package/lib/commands/inbox.js

@@ -5,39 +5,52 @@
 import { formatOutput, formatDetail, printSuccess } from '../core/output.js';
 import { resolveOrgId } from './helpers.js';
 import { resolveEndpoint } from '../api/endpoints.js';
+import { attachWalkthrough } from './walkthrough.js';
 import { getApprovalContext, formatApprovalContext, approvalListColumns } from '../core/approvalContext.js';
+import { QuoxUserError } from '../core/errors.js';
+import { resolutionFromItem, alreadyResolvedError } from '../core/inboxResolution.js';
+import chalk from 'chalk';
 
 export function registerInboxCommands(program, ctx) {
   const { client, auth } = ctx;
 
-  // An agent hands back a tool approvalId (tool_approvals.approval_id), which is
-  // stored on the inbox card as aee_correlation_id, not its item id. No server
-  // lookup-by-correlation route exists, so on a 404 we scan the org's approval
-  // cards (all statuses) client-side. Falls back to the id as given.
+  // An agent hands back a tool approvalId (tool_approvals.approval_id), stored on the card as
+  // aee_correlation_id. The server now resolves it on GET and respond (CLI-ERRORS); this client-side
+  // scan stays as the fallback for an older server. A failed scan is reported, never read as "no card".
+  async function findByApprovalId(orgId, id) {
+    const list = resolveEndpoint('inbox.list', { orgId });
+    const data = await client.get(list.path, { service: list.service, query: { status: 'all', kind: 'approval', limit: 200 } });
+    const items = (data && (data.items || data)) || [];
+    const hit = Array.isArray(items) && items.find((it) => it.aee_correlation_id === id || (it.payload && it.payload.approval_id === id));
+    return hit ? hit.id : null;
+  }
+
+  function notFound(id, cause) {
+    const err = new QuoxUserError(`No inbox item or approval with id ${id} in this org, open or resolved.`, {
+      next: "if it came from another org, switch with `quox org switch <org>`; `quox inbox list --status all` lists this org's items.",
+      exitCode: 5, code: 'not_found', status: 404, body: cause?.body,
+    });
+    return err;
+  }
+
   async function resolveItemId(orgId, id) {
     const direct = resolveEndpoint('inbox.get', { orgId, itemId: id });
     try {
-      await client.get(direct.path, { service: direct.service });
-      return id;
+      const data = await client.get(direct.path, { service: direct.service });
+      // the server resolves an approvalId to its card; post to the card's own id
+      return (data && data.item && data.item.id) || id;
     } catch (err) {
       if (!err || err.status !== 404) throw err;
-      const list = resolveEndpoint('inbox.list', { orgId });
-      let data;
-      try {
-        data = await client.get(list.path, { service: list.service, query: { status: 'all', kind: 'approval', limit: 200 } });
-      } catch { data = null; }
-      const items = (data && (data.items || data)) || [];
-      const hit = Array.isArray(items) && items.find((it) => it.aee_correlation_id === id || (it.payload && it.payload.approval_id === id));
-      if (hit) return hit.id;
-      err.message += `\nHint: ${id} is not an inbox item id, and no approval card in your recent approvals carries it as an approvalId. `
-        + 'Try `quox inbox list --status all` to find the card.';
-      throw err;
+      const hit = await findByApprovalId(orgId, id);
+      if (hit) return hit;
+      throw notFound(id, err);
     }
   }
 
   const inbox = program
     .command('inbox')
     .description('Manage inbox and approval requests');
+  attachWalkthrough(inbox, ctx, program);
 
   inbox
     .command('list')
@@ -102,14 +115,52 @@ export function registerInboxCommands(program, ctx) {
     .action(async (givenId, options) => {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
-      const itemId = await resolveItemId(orgId, givenId);
-      await client.post(resolveEndpoint('inbox.respond', { orgId, itemId }).path, {
-        service: resolveEndpoint('inbox.respond', { orgId, itemId }).service,
-        body: { action: options.action, comment: options.comment },
-      });
-      printSuccess(`Item ${options.action}ed.`);
+      const format = program.opts().output;
+      const post = (itemId) => {
+        const ep = resolveEndpoint('inbox.respond', { orgId, itemId });
+        return client.post(ep.path, { service: ep.service, body: { action: options.action, comment: options.comment } });
+      };
+      // Resolve an approvalId to its card (server-side on a current server, else the client scan). When
+      // this profile cannot see the card, still ask the server: it knows WHY (an agent login, another
+      // org, already decided) and says so, where "not found" would hide it.
+      let itemId = givenId;
+      try { itemId = await resolveItemId(orgId, givenId); } catch (err) { if (err?.code !== 'not_found') throw err; }
+      let result;
+      try {
+        result = await post(itemId);
+      } catch (err) {
+        if (err?.status === 404) throw notFound(givenId, err);
+        if (!result) {
+          const resolution = await alreadyResolvedFrom(err, orgId, itemId, options.action);
+          if (!resolution) throw err;
+          if (!resolution.matches) throw alreadyResolvedError(resolution, err);
+          if (format === 'json') console.log(JSON.stringify({ success: true, already_resolved: true, ...resolution }));
+          else if (format !== 'quiet') console.log(chalk.green(`✔ ${resolution.message}`));
+          return;
+        }
+      }
+      if (result?.item?.status === 'expired') {
+        throw new QuoxUserError(result.message || 'This approval had expired, so nothing ran.', {
+          next: 're-run the original command to ask for a fresh approval.', exitCode: 1, code: 'approval_expired',
+        });
+      }
+      const PAST = { approve: 'approved', reject: 'rejected', deny: 'denied', defer: 'deferred', resolve: 'resolved', answer: 'answered' };
+      printSuccess(`Item ${PAST[options.action] || `${options.action} recorded`}.`);
     });
 
+  // A respond on a closed card: the server's structured answer, else (older server) read the card.
+  async function alreadyResolvedFrom(err, orgId, givenId, action) {
+    if (!err || err.status !== 400) return null;
+    const body = err.body || {};
+    if (body.code === 'already_resolved' && body.resolution) return { ...body.resolution, message: body.message };
+    if (!/not open for response/i.test(`${body.error || ''} ${err.message || ''}`)) return null;
+    try {
+      const ep = resolveEndpoint('inbox.get', { orgId, itemId: givenId });
+      const data = await client.get(ep.path, { service: ep.service });
+      return resolutionFromItem(data.item || data, action);
+    } catch { return null; }
+  }
+
   inbox
     .command('stats')
     .description('Show inbox statistics')