quoxcli 0.0.0-stage → 0.3.1

package/lib/quoxon/slash/compact.js

@@ -0,0 +1,90 @@
+/**
+ * /compact: POST /api/v1/conversations/:id/compact asks the server to summarise the conversation (keeping
+ * decisions); the summary becomes the head of the conversation for later turns. This module only words the
+ * result and the refusals; nothing is summarised on the client.
+ */
+export const SUMMARY_LINES = 6;
+
+/** 18400 -> "18.4k", 950 -> "950". */
+export function kTokens(n) {
+  if (n == null || n === '') return '?';
+  const v = Number(n);
+  if (!Number.isFinite(v)) return '?';
+  if (v < 1000) return String(Math.round(v));
+  return `${(v / 1000).toFixed(1).replace(/\.0$/, '')}k`;
+}
+
+/** The result -> { head, tone, summaryLines, more, notes[] }. */
+export function compactResult(r, { max = SUMMARY_LINES } = {}) {
+  const lines = String(r?.summary || '').split('\n').map(l => l.replace(/\s+$/, '')).filter((l, i, a) => l || (i > 0 && a[i - 1]));
+  const n = Number(r?.turns_compacted) || 0;
+  const head = r?.unchanged
+    ? `Nothing new to compact; the summary is already up to date (${kTokens(r?.tokens_after)} tokens).`
+    : `Compacted ${n} turn${n === 1 ? '' : 's'}: ${kTokens(r?.tokens_before)} -> ${kTokens(r?.tokens_after)} tokens`;
+  const notes = [];
+  if (!r?.unchanged && Number(r?.tokens_after) > Number(r?.tokens_before)) notes.push('The summary is longer than what it replaced: this conversation was too short to gain from compacting.');
+  if (r?.provider || r?.model) notes.push(`Summarised by ${[r.provider, r.model].filter(Boolean).join(' ')}.`);
+  if (Array.isArray(r?.tool_activity) && r.tool_activity.some(t => t?.tools?.length)) notes.push('/compact show lists the tool activity recorded in those turns, the basis for any action the summary names.');
+  if (r?.cli_session_reset) notes.push('The Claude CLI session behind this conversation was reset, so it starts from the summary.');
+  return { head, tone: r?.unchanged ? undefined : 'ok', summaryLines: lines.slice(0, max), more: Math.max(0, lines.length - max), allLines: lines, notes, basisLines: toolBasisLines(r?.tool_activity) };
+}
+
+/**
+ * The server's recorded tool activity per compacted turn -> lines. Read from the stored turns, never
+ * from the model, so any action the summary names can be checked here. No row is "none recorded",
+ * not "none ran": only some paths record tool activity.
+ */
+export function toolBasisLines(activity) {
+  if (!Array.isArray(activity)) return ['The server sent no tool activity record for this compaction.'];
+  if (!activity.length) return ['No turns were compacted, so there is no tool activity.'];
+  return activity.map((t) => {
+    const tools = (Array.isArray(t?.tools) ? t.tools : []).map(x => `${x?.name || '?'} ${x?.status || '?'}`);
+    if (Number(t?.more) > 0) tools.push(`and ${Number(t.more)} more`);
+    return `turn ${t?.turn ?? '?'}: ${tools.length ? tools.join(', ') : 'no tools recorded'}`;
+  });
+}
+
+/** /compact show: the whole summary, then the recorded tool activity it was made from. */
+export function compactShowLines(v) {
+  const basis = Array.isArray(v?.basisLines) ? v.basisLines : toolBasisLines(undefined);
+  return [
+    { kind: 'plain', text: `Summary (${v.allLines.length} lines)` },
+    ...v.allLines.map(t => ({ kind: 'dim', text: t || ' ' })),
+    { kind: 'plain', text: 'Recorded tool activity (from the stored turns, not the model)' },
+    ...basis.map(t => ({ kind: 'dim', text: t })),
+  ];
+}
+
+/** A refused or failed compaction -> one honest line. */
+export function compactError(e) {
+  const code = e?.code || e?.body?.error || null;
+  const msg = e?.body?.message || null;
+  if (e?.status === 409) {
+    if (code === 'turn_running') return 'A turn is still running in this conversation. Compact after it finishes.';
+    if (code === 'compact_in_progress') return 'A compaction of this conversation is already running.';
+    if (code === 'transcripts_disabled') return msg || 'Transcript storage is off for this org, so no summary can be stored.';
+    return msg || 'The server refused to compact right now (409).';
+  }
+  if (e?.status === 403 && code === 'ai_consent_required') return 'Compacting sends this conversation to your AI provider, and you have not given AI processing consent. /consent grant gives it (Settings > Privacy in the dashboard does too).';
+  if (e?.status === 403) return 'Not allowed to compact this conversation (403).';
+  if (e?.status === 404) return 'The server has no stored turns for this conversation (expired after 7 days, or nothing sent yet).';
+  if (e?.status === 502) return 'The model call failed; nothing was changed. Try /compact again.';
+  if (e?.status === 503 && code === 'no_provider') return 'No AI provider is configured for this org, so nothing can summarise it. /connect openai';
+  if (e?.status === 500 && code === 'summary_not_stored') return 'The summary was made but could not be stored; nothing was changed.';
+  if (e?.status === 404 || e?.status === 405) return 'This server cannot compact conversations yet.';
+  return `compact failed: ${e?.status ? `HTTP ${e.status} ` : ''}${e?.message || 'failed'}`.trim();
+}
+
+/** GET .../context -> the /context rows' facts. */
+export function contextFacts(c) {
+  if (!c || typeof c !== 'object') return null;
+  const t = c.tokens || {};
+  const how = t.source === 'cli_session_usage' ? 'from the CLI session usage' : t.source === 'chars_div_4' ? 'estimated from stored text (chars / 4)' : t.source ? `source ${t.source}` : 'source not given';
+  return {
+    tokens: t.estimate,
+    tokensText: `${kTokens(t.estimate)} tokens${t.context_window ? ` of ${kTokens(t.context_window)}` : ''}, ${how}`,
+    turns: c.turns,
+    turnsText: c.turns == null ? null : c.summary_present ? `${c.turns} turn${c.turns === 1 ? '' : 's'} since the summary` : `${c.turns} stored turn${c.turns === 1 ? '' : 's'}`,
+    summaryText: c.summary_present ? `yes, ${c.compacted_turns ?? '?'} turns folded in${c.summary_at ? ` (${String(c.summary_at).slice(0, 16).replace('T', ' ')} UTC)` : ''}` : 'none yet (/compact)'
+  };
+}

package/lib/quoxon/slash/confirm.js

@@ -0,0 +1,30 @@
+/**
+ * One preview card, one y/n. Shared by /watch, /automate and /crystallize: a direct human ask is already the
+ * authorization, so the preview is the only confirmation. The answer is the next composer line (same pattern as the
+ * /approve "y/N" grant); a slash command typed instead drops the preview and runs normally.
+ */
+import { askText } from '../ask.js';
+export function createConfirm({ say, ttlMs = 120000, now = () => Date.now() }) {
+  let p = null;
+  return {
+    pending: () => Boolean(p),
+    /** y/N/c: a chat about the ask keeps it open with a fresh window. */
+    touch() { if (p) p.at = now(); },
+    ask(lines, onYes, { prompt = 'Go ahead?' } = {}) {
+      p = { onYes, at: now() };
+      for (const l of lines) (Array.isArray(l) ? say(l[0], l[1]) : say(l));
+      say(askText(String(prompt).replace(/\s*y\/n$/i, '')), 'ask'); // QUOXON-ASK: one shape
+    },
+    /** -> true when this line was the answer (consumed); false when the caller should treat it as an ordinary line. */
+    answer(text) {
+      if (!p) return false;
+      const q = p; p = null;
+      const t = String(text || '').trim();
+      if (t.startsWith('/')) return false;
+      if (now() - q.at > ttlMs) { say('That preview expired, so nothing was created. Run the command again.', 'dim'); return true; }
+      if (/^y(es)?$/i.test(t)) { Promise.resolve(q.onYes()).catch((e) => say(`Failed: ${e?.message || e}`, 'warn')); return true; }
+      say('Cancelled; nothing was created.', 'dim');
+      return true;
+    }
+  };
+}

package/lib/quoxon/slash/crystallize.js

@@ -0,0 +1,69 @@
+/**
+ * /crystallize [what]: turn what was just accomplished into a permanent reusable skill (rules, tools, tests).
+ * Real: one drafting model call (draft.js), a dry-run through the skill firewall for the preview, and creation in
+ * the QSKL store (POST /api/quox-skills). /crystal (is a workflow eligible to become a Crystal) is a different check.
+ */
+import { draftJson, transcriptText } from './draft.js';
+
+const why = (e) => `${e?.status ? `HTTP ${e.status}: ` : ''}${e?.message || 'failed'}`;
+const NAME_RE = /^[a-z0-9][a-z0-9-]{1,60}$/;
+
+export const crystallizePrompt = (context) => [
+  'Turn what was just accomplished in the conversation below into a reusable skill. Reply with ONE JSON object and nothing else. Use no tools.',
+  'Shape: {"name":"kebab-case-name","category":str,"description":"one sentence","rules":[str,...],"tools":[tool name,...],',
+  ' "tests":[{"name":str,"input":str,"expect":str}]}.',
+  'Rules are the steps and guardrails to repeat next time. Never include secrets, keys, hostnames or personal data. Tools are only ones actually used above.',
+  '', '--- conversation ---', context, '--- end ---'
+].join('\n');
+
+/** -> { body (POST /api/quox-skills), card[] } or { error } */
+export function buildSkill(d, { orgId, author }) {
+  const name = String(d?.name || '').trim().toLowerCase();
+  if (!NAME_RE.test(name)) return { error: 'the draft has no valid kebab-case name' };
+  const rules = (Array.isArray(d.rules) ? d.rules : []).map((r) => String(r).trim()).filter(Boolean);
+  if (!rules.length) return { error: 'the draft has no rules' };
+  const description = String(d.description || '').trim();
+  if (!description) return { error: 'the draft has no description' };
+  const tools = (Array.isArray(d.tools) ? d.tools : []).map((t) => String(t).trim()).filter(Boolean);
+  const tests = {};
+  for (const [i, t] of (Array.isArray(d.tests) ? d.tests : []).entries()) {
+    if (t && (t.input || t.expect)) tests[String(t.name || `case-${i + 1}`)] = { input: String(t.input || ''), expect: String(t.expect || '') };
+  }
+  const bodyMd = [`# ${name}`, '', description, '', '## Rules', ...rules.map((r, i) => `${i + 1}. ${r}`),
+    ...(tools.length ? ['', '## Tools', ...tools.map((t) => `- ${t}`)] : [])].join('\n');
+  const body = { orgId, scopeId: null, name, category: String(d.category || 'general'), description, bodyMd, author: author || 'quoxon', requiredTools: tools, tests, tags: ['crystallized'] };
+  const card = [
+    ['Skill draft (nothing is saved until you answer):', 'accent'],
+    `  Name       ${name}`,
+    `  About      ${description}`,
+    `  Rules      ${rules.length}   first: ${rules[0]}`,
+    `  Tools      ${tools.length ? tools.join(', ') : 'none'}`,
+    `  Tests      ${Object.keys(tests).length}${Object.keys(tests).length ? '   ' + Object.keys(tests).join(', ') : ''}`
+  ];
+  return { body, card, name };
+}
+
+export function createCrystallizeCmd({ api, say, confirm, getState, getFields }) {
+  return {
+    async handle(arg) {
+      if (!api.skillCreate) return say('Skills are not available in this mode.', 'warn');
+      const ctx = [transcriptText(getState()), String(arg || '').trim() ? `Focus: ${String(arg).trim()}` : ''].filter(Boolean).join('\n');
+      if (!ctx) return say('Nothing to crystallize yet. Do the task with Quox first, or say what: /crystallize how we rotate the API key.');
+      say('Drafting the skill…', 'dim');
+      let d;
+      try { d = await draftJson({ api, prompt: crystallizePrompt(ctx), fields: getFields() }); }
+      catch (e) { return say(`Could not draft a skill: ${e.message}. Nothing was saved.`, 'warn'); }
+      const b = buildSkill(d, { orgId: api.orgId?.(), author: api.userId?.() });
+      if (b.error) return say(`Could not draft a usable skill: ${b.error}. Nothing was saved.`, 'warn');
+      try { await api.skillCreate(b.body, { dryRun: true }); } // the server's skill firewall, before the card
+      catch (e) { return say(`The skill was not saved: ${why(e)}`, 'warn'); }
+      b.card.push('  Firewall   passed the server dry run');
+      confirm.ask(b.card, async () => {
+        try { await api.skillCreate(b.body); } catch (e) { return say(`Could not save the skill: ${why(e)}`, 'warn'); }
+        say(`✔ Saved skill ${b.name}.`, 'ok');
+        say(`  See it: /skills ${b.name}`);
+      }, { prompt: 'Save this skill?' });
+      return undefined;
+    }
+  };
+}

package/lib/quoxon/slash/dashboard.js

@@ -0,0 +1,136 @@
+/**
+ * /dashboard [page] and `quox dashboard [page]`: a one-time sign-in link to the web dashboard.
+ *
+ * The link comes from POST /api/auth/login-link (10 minutes, single use, bound to this user and org) and is
+ * joined to the active profile's dashboard URL. It is a credential: callers print it on the visible line only,
+ * never into the dev transcript or any history. Opened in the default browser when running locally; never over
+ * SSH (the browser would open on the wrong machine), where it is only printed.
+ *
+ * `next` asks the consume route to land on the page after sign-in. A server that does not know `next` lands
+ * on the dashboard home instead; nothing breaks.
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+
+/** Page name -> real route in src/config/routeRegistry.js (approvals = the HITL /inbox, inbox = InboxQ mail). */
+export const PAGES = {
+  sessions: '/sessions',
+  approvals: '/inbox',
+  agents: '/agents',
+  lucid: '/lucid',
+  inbox: '/inboxq',
+  seo: '/quoxseo',
+  settings: '/settings'
+};
+
+export function resolvePage(arg) {
+  const name = String(arg ?? '').trim().toLowerCase();
+  if (!name) return { ok: true, page: null, path: '/' };
+  if (Object.hasOwn(PAGES, name)) return { ok: true, page: name, path: PAGES[name] };
+  return { ok: false, error: `Unknown page "${name}". Pages: ${Object.keys(PAGES).join(', ')}.` };
+}
+
+export const isRemoteSession = (env = process.env) => Boolean(env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY);
+
+export function openerFor(platform = process.platform) {
+  if (platform === 'linux') return { cmd: 'xdg-open', args: [] };
+  if (platform === 'darwin') return { cmd: 'open', args: [] };
+  if (platform === 'win32') return { cmd: 'rundll32', args: ['url.dll,FileProtocolHandler'] }; // no shell, so & in the URL is safe
+  return null;
+}
+
+/** -> { opened: true } | { opened: false, reason: 'ssh' | 'no-opener' | 'failed' }. Never throws, never uses a shell. */
+export function openInBrowser(url, { env = process.env, platform = process.platform, spawn = nodeSpawn } = {}) {
+  if (isRemoteSession(env)) return Promise.resolve({ opened: false, reason: 'ssh' });
+  const op = openerFor(platform);
+  if (!op) return Promise.resolve({ opened: false, reason: 'no-opener' });
+  return new Promise((resolve) => {
+    let done = false;
+    const fin = (r) => { if (!done) { done = true; resolve(r); } };
+    try {
+      const child = spawn(op.cmd, [...op.args, url], { stdio: 'ignore', detached: true });
+      child.on('error', () => fin({ opened: false, reason: 'failed' }));
+      child.unref?.();
+      setTimeout(() => fin({ opened: true }), 150); // an error (opener missing) arrives well inside this
+    } catch { fin({ opened: false, reason: 'failed' }); }
+  });
+}
+
+const missing = (e) => e?.status === 404 || e?.status === 405 || e?.status === 501;
+const join = (base, path) => new URL(path, base).href;
+const isLoopbackUrl = (u) => /^(localhost|127\.\d+\.\d+\.\d+|\[::1\]|0\.0\.0\.0)$/i.test(new URL(u).hostname);
+
+/**
+ * mint: async () -> { path, expires_at, ttl_seconds } (POST /api/auth/login-link).
+ * -> { kind: 'link' | 'plain' | 'error', url, plainUrl, page, remote, opened, openFailed, ttlSeconds, expiresAt, error }
+ */
+export async function runDashboard({ page, mint, baseUrl, env = process.env, open = (u) => openInBrowser(u, { env }) } = {}) {
+  const p = resolvePage(page);
+  if (!p.ok) return { kind: 'error', error: p.error };
+  const remote = isRemoteSession(env);
+  let plainUrl = null;
+  try { plainUrl = join(baseUrl, p.path); } catch { /* no profile URL: the server may still give one */ }
+  const base = { page: p.page, plainUrl, remote };
+  const noUrl = 'This profile has no dashboard URL. Set one with: quox config set url <https://host:3000>';
+  let r;
+  try { r = await mint(); } catch (e) {
+    if (missing(e)) return plainUrl ? { ...base, kind: 'plain', url: plainUrl } : { kind: 'error', error: noUrl };
+    const why = e?.status ? `${e.message || 'refused'} (HTTP ${e.status})` : (e?.message || 'failed');
+    return { ...base, kind: 'error', url: plainUrl, error: `Could not create a sign-in link: ${why}` };
+  }
+  if (!r?.path || !/^\/api\/auth\/login-link\/consume\?t=[\w-]+$/.test(r.path)) {
+    return { ...base, kind: 'error', url: plainUrl, error: 'Could not create a sign-in link: unexpected answer from the auth service.' };
+  }
+  // The server knows the public address of the instance; the profile URL may be localhost on this box.
+  let origin = null;
+  if (typeof r.url === 'string') {
+    try {
+      const u = new URL(r.url);
+      if (/^https?:$/.test(u.protocol) && r.url === u.origin + r.path) origin = u.origin;
+    } catch { /* ignore a malformed server url */ }
+  }
+  let linkBase = origin || baseUrl;
+  let local = false;
+  if (!origin) {
+    try { local = isLoopbackUrl(join(baseUrl, '/')); } catch { /* handled below */ }
+  }
+  let link;
+  try { link = join(linkBase, r.path); } catch { return { kind: 'error', error: noUrl }; }
+  const url = link + (p.page ? `&next=${encodeURIComponent(p.path)}` : '');
+  if (origin) base.plainUrl = join(origin, p.path);
+  const out = { ...base, kind: 'link', url, localOnly: local, ttlSeconds: r.ttl_seconds ?? 600, expiresAt: r.expires_at, opened: false };
+  if (!remote) {
+    const o = await open(url).catch(() => ({ opened: false, reason: 'failed' }));
+    out.opened = Boolean(o?.opened);
+    out.openFailed = !o?.opened;
+  }
+  return out;
+}
+
+const osc8 = (url, text) => `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\`;
+
+/** Result -> [{ text, tone }] for the visible lines. The link line is the only place the credential is printed. */
+export function dashboardLines(r, { hyperlinks = false } = {}) {
+  const where = r.page ? `the ${r.page} page` : 'the dashboard';
+  if (r.kind === 'error') {
+    return [
+      { text: r.error, tone: 'warn' },
+      ...(r.url ? [{ text: `The dashboard is at ${r.url} (you will need to sign in).`, tone: 'dim' }] : [])
+    ];
+  }
+  if (r.kind === 'plain') {
+    return [
+      { text: `This server does not offer one-time sign-in links (an older server). Open ${where} here and sign in:`, tone: 'warn' },
+      { text: r.url }
+    ];
+  }
+  const mins = Math.round((r.ttlSeconds || 600) / 60);
+  return [
+    { text: r.opened ? `Opened ${where} in your browser, already signed in.` : `Sign-in link for ${where}:` },
+    ...(hyperlinks ? [{ text: osc8(r.url, `Open ${where} (signed in)`) }] : []),
+    { text: r.url },
+    { text: `Valid for ${mins} minutes, works once, tied to your account. Anyone holding it can sign in as you until then.`, tone: 'dim' },
+    ...(r.localOnly ? [{ text: 'This address only works on this machine; set the app URL with `quox server config app-url <url>` or in Settings > General > App URL.', tone: 'dim' }] : []),
+    ...(r.remote ? [{ text: 'Over SSH, so it was not opened here: open it in a browser on your own machine.', tone: 'dim' }] : []),
+    ...(r.openFailed ? [{ text: 'Could not open a browser from here: use the link above.', tone: 'warn' }] : [])
+  ];
+}

package/lib/quoxon/slash/draft.js

@@ -0,0 +1,54 @@
+/**
+ * One drafting model call for /automate and /crystallize, through the same governed turn path as chat (api.stream)
+ * but in its own throwaway conversation, so it never lands in the visible transcript. The model is told to answer
+ * with JSON only and use no tools; an approval request or error aborts the draft. The JSON is validated by the
+ * caller before any card is shown.
+ */
+import { textGate } from '../events.js';
+
+const newId = () => `QXN_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+
+/** The visible conversation as plain text for the drafting prompt (last `max` chars). */
+export function transcriptText(state, max = 12000) {
+  const out = [];
+  for (const it of [...(state?.history || []), ...(state?.blocks || [])]) {
+    if (it.kind === 'user' && !it.echo && it.text && !it.text.startsWith('/')) out.push(`User: ${it.text}`);
+    else if (it.kind === 'text' && it.text) out.push(`Quox: ${it.text}`);
+    else if (it.kind === 'tool' && it.tool) out.push(`Tool used: ${[it.tool, it.target].filter(Boolean).join(' ')}`);
+  }
+  const t = out.join('\n');
+  return t.length > max ? t.slice(t.length - max) : t;
+}
+
+/** First JSON object in a model reply (plain, fenced, or surrounded by prose), or null. */
+export function extractJson(text) {
+  const s = String(text || '');
+  const fence = s.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const cand = fence ? fence[1] : s;
+  const a = cand.indexOf('{'), b = cand.lastIndexOf('}');
+  if (a < 0 || b <= a) return null;
+  try { const v = JSON.parse(cand.slice(a, b + 1)); return v && typeof v === 'object' && !Array.isArray(v) ? v : null; } catch { return null; }
+}
+
+/** -> parsed object, or throws Error(reason). `fields` = streamFields(model choice). */
+export async function draftJson({ api, prompt, fields = {}, timeoutMs = 90000 }) {
+  if (!api.stream) throw new Error('no model connection in this mode');
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  let text = '', gate = null;
+  try {
+    for await (const ev of api.stream({ turnId: newId(), message: prompt, agent: 'quox', ...fields }, ctrl.signal)) {
+      if (ev.type === 'error') throw new Error(String(ev.error || 'the model call failed'));
+      if (ev.type === 'approval.requested') throw new Error('the model tried to use a tool instead of drafting');
+      const g = textGate(gate, ev); gate = g.st;
+      if (g.append) text += ev.content;
+      if (ev.type === 'turn.finished' || ev.type === 'done') break;
+    }
+  } catch (e) {
+    if (ctrl.signal.aborted) throw new Error('the model took too long');
+    throw e;
+  } finally { clearTimeout(timer); }
+  const j = extractJson(text);
+  if (!j) throw new Error('the model did not return a usable draft');
+  return j;
+}

package/lib/quoxon/slash/hatWalk.js

@@ -0,0 +1,206 @@
+/**
+ * CUSTOM-HATS (owner 2026-10-17): /hat new | edit <hat> | delete <hat> in the quox window. One small step machine:
+ * every question is either a y/N/c card (askText, the same shape as every other ask) or a one-line text capture
+ * (a name, a pick by number or name, a list of agents). Esc, or any other slash command, ends the walk and
+ * nothing is sent. Nothing reaches the server until the final summary card is answered y.
+ * The definition maths is shared with `quox hat create|edit` (core/customHats.js); this file has no I/O of its own
+ * beyond the api it is given.
+ */
+import { buildCustomDefinition, applyHatEdits } from '../../core/customHats.js';
+import { matchHat, hatChoices } from '../hatSwitch.js';
+import { askText } from '../ask.js';
+
+export const slugify = (name) => String(name ?? '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+const isCustom = (hat) => hat?.template_key == null;
+const nameOf = (hat) => hat?.name || hat?.key || 'hat';
+const joinNice = (xs) => xs.join(', ');
+
+/** "1, 3 sec" -> picks resolved against rows [{ id }] -> { ids, unknown } (numbers are 1-based positions). */
+export function pickAgents(line, rows) {
+  const ids = []; const unknown = [];
+  for (const raw of String(line ?? '').split(/[\s,]+/).map(s => s.trim()).filter(Boolean)) {
+    let id = null;
+    if (/^\d+$/.test(raw)) id = rows[Number(raw) - 1]?.id ?? null;
+    else id = rows.find(r => r.id.toLowerCase() === raw.toLowerCase())?.id ?? null;
+    if (!id) unknown.push(raw); else if (!ids.includes(id)) ids.push(id);
+  }
+  return { ids, unknown };
+}
+
+export function createHatWalk({ api, say, bump = () => {} }) {
+  let W = null; // the walk in progress, or null
+
+  const ask = (question, reason = '') => { const st = { at: Date.now() }; W.card = st; W.wait = { ...W.wait, kind: 'yn' }; say(askText(question, { reason }), 'ask'); return st; };
+  const yn = (question, on, reason) => { W.wait = { kind: 'yn', on }; ask(question, reason); bump(); };
+  const text = (prompt, on) => { W.wait = { kind: 'text', on }; W.card = null; say(prompt); bump(); };
+  const end = () => { W = null; bump(); };
+  const fail = (what, e) => { say(`${what}: ${e?.message || 'the server refused'}.`, 'warn'); end(); };
+
+  async function loadAgents() {
+    if (W.agents) return W.agents;
+    try {
+      const rows = await api.agents();
+      W.agents = (Array.isArray(rows) ? rows : []).map(a => ({ id: String(a.agent_id ?? a.id ?? ''), name: a.name || a.agent_id || a.id })).filter(a => a.id);
+    } catch { W.agents = null; }
+    return W.agents;
+  }
+  const agentLabel = (id) => { const a = W.agents?.find(x => x.id === id); return a && a.name && a.name !== id ? `${id} (${a.name})` : id; };
+
+  // Shared tail: keep cards for each current specialist, then "Add agents?". done(kept, added).
+  async function agentSteps(current, done) {
+    await loadAgents();
+    const kept = []; const queue = [...current];
+    const nextKeep = () => {
+      if (!queue.length) return askAdd();
+      const id = queue.shift();
+      yn(`Keep ${agentLabel(id)}?`, (yes) => { if (yes) kept.push(id); nextKeep(); }, 'This hat lists it as a specialist');
+    };
+    const askAdd = () => yn('Add agents?', async (yes) => {
+      if (!yes) return done(kept, []);
+      if (!W.agents?.length) { say('Could not list the org agents, so none were added.', 'warn'); return done(kept, []); }
+      const rows = W.agents.filter(a => !kept.includes(a.id));
+      if (!rows.length) { say('Every agent in this org is already in the hat.'); return done(kept, []); }
+      rows.forEach((a, i) => say(`  ${i + 1}. ${a.id}${a.name && a.name !== a.id ? `  ${a.name}` : ''}`));
+      const pick = () => text('Which agents? Numbers and/or ids, separated by commas or spaces.', (line) => {
+        const { ids, unknown } = pickAgents(line, rows);
+        if (unknown.length) { say(`Not in the list above: ${unknown.join(', ')}.`, 'warn'); return pick(); }
+        if (!ids.length) { say('No agent picked.', 'warn'); return pick(); }
+        done(kept, ids);
+      });
+      pick();
+    });
+    nextKeep();
+  }
+
+  async function startNew() {
+    let hats;
+    try { hats = await api.hats(); } catch (e) { return fail("Couldn't list hats", e); }
+    W = { mode: 'new', hats };
+    const askName = () => text('What should the new hat be called?', (line) => {
+      const name = line.trim(); const key = slugify(name);
+      if (key.length < 2 || key.length > 41) { say('A hat name needs 2 to 41 letters or digits. Try another.', 'warn'); return askName(); }
+      if (hats.some(h => h.key === key)) { say(`A hat with the key "${key}" already exists. Try another name.`, 'warn'); return askName(); }
+      W.name = name; W.key = key; askBase();
+    });
+    const askBase = () => yn('Start from an empty hat?', (yes) => {
+      if (yes) { W.base = null; return agents(); }
+      hats.forEach((h, i) => say(`  ${i + 1}. ${nameOf(h)}  ${h.key}`));
+      const pick = () => text('Which hat should it start from? A number or a name.', (line) => {
+        const t = line.trim();
+        const m = /^\d+$/.test(t) ? { hat: hats[Number(t) - 1] } : matchHat(t, hats);
+        if (m.ambiguous) { say(`"${t}" matches more than one hat: ${hatChoices(m.ambiguous)}. Be more specific.`, 'warn'); return pick(); }
+        if (!m.hat) { say(`No hat matches "${t}".`, 'warn'); return pick(); }
+        W.base = m.hat; agents();
+      });
+      pick();
+    });
+    const agents = () => agentSteps(W.base?.definition?.agents?.specialists || [], (kept, added) => {
+      const list = [...kept, ...added];
+      let built;
+      try { built = buildCustomDefinition({ base: W.base?.definition || null, name: W.name, agents: list }); } catch (e) { return fail('Could not build the hat', e); }
+      yn(`Create the ${W.name} hat with ${list.length ? joinNice(list) : 'no agents'}? It offers only its own tools and agents.`, async (yes) => {
+        if (!yes) { say('Nothing created.', 'dim'); return end(); }
+        const { key, name } = W;
+        try {
+          const r = await api.createHat({ key, name, definition: built.definition, visibility: 'org' });
+          say(`Hat ${name} created (rev ${r?.hat?.current_revision ?? 1}). It is in your hat list now, ready to wear.`, 'ok');
+          for (const w of Array.isArray(r?.warnings) ? r.warnings : []) say(`Note: ${typeof w === 'string' ? w : w?.message || JSON.stringify(w)}`, 'warn');
+        } catch (e) { say(`Hat not created: ${e?.message || 'the server refused'}.`, 'warn'); }
+        end();
+      });
+    });
+    askName();
+  }
+
+  async function findCustom(arg, verb) {
+    let hats;
+    try { hats = await api.hats(); } catch (e) { say(`Couldn't list hats: ${e?.message || 'failed'}.`, 'warn'); return null; }
+    const mine = hats.filter(isCustom);
+    if (!arg) { say(`Which hat? ${mine.length ? `Your own hats: ${hatChoices(mine)}.` : 'You have no hats of your own yet. /hat new makes one.'}`, 'warn'); return null; }
+    const m = matchHat(arg, hats);
+    if (m.ambiguous) { say(`"${arg}" matches more than one hat: ${hatChoices(m.ambiguous)}. Be more specific.`, 'warn'); return null; }
+    if (!m.hat) { say(`No hat matches "${arg}". Your own hats: ${hatChoices(mine) || 'none yet'}.`, 'warn'); return null; }
+    if (!isCustom(m.hat)) {
+      say(verb === 'edit'
+        ? `${nameOf(m.hat)} is a built-in hat, so it is not edited here. It can be reset, or used as a starting point with /hat new.`
+        : `${nameOf(m.hat)} is a built-in hat and cannot be deleted. It can be reset, or used as a starting point with /hat new.`, 'warn');
+      return null;
+    }
+    return m.hat;
+  }
+
+  async function startEdit(arg) {
+    const hat = await findCustom(arg, 'edit'); if (!hat) return;
+    W = { mode: 'edit', hat };
+    const def = hat.definition || {};
+    agentSteps(def.agents?.specialists || [], (kept, added) => {
+      const current = def.agents?.specialists || [];
+      const removeAgents = current.filter(a => !kept.includes(a));
+      const rename = () => yn('Rename it?', (yes) => {
+        if (!yes) return summary(null);
+        const ask2 = () => text('What is the new name?', (line) => { const n = line.trim(); if (!n) { say('A name cannot be empty.', 'warn'); return ask2(); } summary(n); });
+        ask2();
+      });
+      const summary = (newName) => {
+        let ed;
+        try { ed = applyHatEdits(def, { addAgents: added, removeAgents }); } catch (e) { return fail('Could not apply the edit', e); }
+        const changes = [...ed.changes];
+        if (newName && newName !== hat.name) changes.push(`name ${newName}`); else newName = null;
+        if (!changes.length) { say(`Nothing changed on the ${nameOf(hat)} hat. Nothing was sent.`); return end(); }
+        yn(`Update the ${nameOf(hat)} hat: ${changes.join('; ')}?`, async (yes) => {
+          if (!yes) { say('Nothing changed.', 'dim'); return end(); }
+          try {
+            const r = await api.updateHat(hat.id, { definition: ed.definition, ...(newName ? { name: newName } : {}), change_reason: 'Edited from the quox window' });
+            say(`Hat ${newName || nameOf(hat)} updated (rev ${r?.hat?.current_revision ?? 'next'}).`, 'ok');
+            for (const w of Array.isArray(r?.warnings) ? r.warnings : []) say(`Note: ${typeof w === 'string' ? w : w?.message || JSON.stringify(w)}`, 'warn');
+          } catch (e) { say(`Hat not updated: ${e?.message || 'the server refused'}.`, 'warn'); }
+          end();
+        });
+      };
+      rename();
+    });
+  }
+
+  async function startDelete(arg) {
+    const hat = await findCustom(arg, 'delete'); if (!hat) return;
+    W = { mode: 'delete', hat };
+    yn(`Delete the ${nameOf(hat)} hat? Conversations wearing it go back to the default hat.`, async (yes) => {
+      if (!yes) { say('Nothing deleted.', 'dim'); return end(); }
+      try {
+        const r = await api.deleteHat(hat.id);
+        const d = r?.deleted || {};
+        say(`Hat ${nameOf(hat)} deleted. Conversations moved off it: ${d.bindings_cleared ?? 0}. Personal choices cleared: ${d.user_prefs_cleared ?? 0}.`, 'ok');
+      } catch (e) { say(`Hat not deleted: ${e?.message || 'the server refused'}.`, 'warn'); }
+      end();
+    }, 'It cannot be undone');
+  }
+
+  return {
+    active: () => Boolean(W),
+    /** the y/N/c card currently on screen (for the ask machinery), or null */
+    card: () => (W?.wait?.kind === 'yn' ? W.card : null),
+    start(kind, arg = '') {
+      if (W) { say('A hat walk is already open. Esc cancels it.', 'warn'); return; }
+      if (kind === 'new') return startNew();
+      if (kind === 'edit') return startEdit(arg);
+      return startDelete(arg);
+    },
+    /** One typed line. true = consumed. A slash command ends the walk and is left to run. */
+    answer(line) {
+      if (!W?.wait) return false;
+      const t = String(line ?? '').trim();
+      if (t.startsWith('/')) { W = null; say('Hat walk ended. Nothing was sent.', 'dim'); bump(); return false; }
+      const w = W.wait;
+      if (w.kind === 'yn') {
+        const yes = /^y(es)?$/i.test(t);
+        if (!yes && t && !/^no?$/i.test(t)) return false; // c or free text: the card's normal chat behaviour
+        W.wait = null; Promise.resolve(w.on(yes)).catch((e) => fail('Hat walk failed', e));
+        return true;
+      }
+      if (!t) return true;
+      W.wait = null; Promise.resolve(w.on(t)).catch((e) => fail('Hat walk failed', e));
+      return true;
+    },
+    cancel() { if (!W) return false; W = null; say('Hat walk cancelled. Nothing was sent.', 'dim'); bump(); return true; },
+  };
+}