aegiscode 5.2.33 → 6.1.0

package/src/art.js

@@ -0,0 +1,235 @@
+'use strict';
+
+/**
+ * Welcome art — the aegiscodex-dev mark, adopted wholesale.
+ *
+ * The composition is copied from `aegiscodex-dev/src/art.js`, which took the
+ * glyph rows from the shipped Claude Code binary: a feather plume (░), a top hat
+ * (█ ▓ ▒), the spark face (▐▛███▜▌ / ▝▜█████▛▘ / ▘▘ ▝▝), plus a crescent moon and
+ * a diving whale for the second brain. Side-by-side when the terminal is wide
+ * enough, stacked when it isn't.
+ *
+ * Every row of a block is the same display width, so `center()` and
+ * `joinSideBySide()` stay exact. `test/cli-conformance.test.mjs` asserts both
+ * that property and that these rows still match aegiscodex-dev's source, so the
+ * mark can't drift.
+ */
+
+// The mascot face — exact glyphs from the binary (msS template).
+const FACE = [' ▐▛███▜▌', '▝▜█████▛▘', '  ▘▘ ▝▝'];
+
+// Top hat + feather plume, composed from the extracted row glyphs.
+const HAT = [
+  '  ✦         ░░░░░░░░░░      ✦',
+  '           ░░░░░░░░░░░░░░░░',
+  '                 █████▓▓░',
+  '                 ███▓░',
+  '                 ███▓░',
+  '                 ███▓░',
+  '               ░▓▓███▓▓░',
+  '          ▒▒░░▒▒     ▒ ▒▒',
+];
+
+// Plume + hat + face: the left half of the welcome mark.
+const MASCOT_ART = [
+  '        ✦               █████▓▓░',
+  '             ✦        ███▓░     ░░',
+  '         ░░░░         ███▓░',
+  '       ░░░░░░░░       ███▓░',
+  '     ░░░░░░░░░░░░     ███▓░',
+  '              ██▓░░      ▓',
+  '              ░▓▓███▓▓░',
+  ...FACE,
+];
+
+// Crescent moon in a starry night sky — lit rim (▓) with a faint earthshine
+// body (░). Rows are equal code-point length (13).
+const MOON = [
+  '  ✦   ▓▓▓  ✦ ',
+  '    ▓▓▓▓▓   ✦',
+  '  ▓▓▓▓▓▓▓▓▓ ✦',
+  '  ▓▓▓▓▓▓▓░░░ ',
+  '  ▓▓▓▓░░░░░░ ',
+  '    ░░░░░░   ',
+  '  ✦   ·   ·  ',
+];
+
+// The diving whale: spout (░), eye (██) on the rounded head, body (▒) sweeping
+// right to a small forked fluke (▓), water line (░) beneath. Rows are equal
+// code-point length (18).
+const WHALE = [
+  '   ✦   ░ ░ ░      ',
+  '    ✦ ░░░░░       ',
+  '     ▒▒▒▒▒▒▒▒▒▒▒▒ ',
+  '    ▒▒▒▒▒▒▒▒▒▒▒▒▒ ',
+  '  ██▒▒▒▒▒▒▒▒▒▒▒▒▓▓',
+  '  ██▒▒▒▒▒▒▒▒▒▒▒▒▓ ',
+  '   ▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ',
+  '    ░░░░░░░░░░░░  ',
+];
+
+// Moon above the whale — the right half of the mark, 2-col gutter. The moon is
+// padded with a trailing blank row so joinSideBySide keeps both blocks aligned.
+const MOON_WHALE = joinSideBySide([...MOON, ''], WHALE, 2);
+
+/** Full welcome mark: mascot + (moon + whale) side by side, bottom-aligned. */
+const WELCOME_ART = joinSideBySide(MASCOT_ART, MOON_WHALE, 2);
+
+/** Narrow-terminal fallback: mascot stacked above (moon + whale). */
+const WELCOME_ART_STACKED = stackVertical(MASCOT_ART, MOON_WHALE, 1);
+
+/** Welcome copy, in aegiscode-dev's frame: coral title over the mark. */
+const WELCOME_TITLE = 'Welcome to AEGIS Code';
+const WELCOME_BACK = 'Welcome back!';
+const TAGLINE = 'Cloud brain in your shell.';
+
+// ── Terminal portability ─────────────────────────────────────────────────────
+// The block-glyph palette and ✦ stars are single-width on Linux terminals, but
+// not everywhere: Windows fonts often lack the U+259B..U+259F face edges and
+// mangle █▓▒░ entirely; on macOS ✦ renders as a double-width emoji. Each pass
+// swaps offending code points 1:1 (same character count per row) so the width
+// maths stays exact and the mark keeps its shape.
+const ASCII_STENCIL = new Map([
+  ['█', '#'],
+  ['▓', '@'],
+  ['▒', '='],
+  ['░', '.'],
+  ['▐', '#'],
+  ['▛', '#'],
+  ['▜', '#'],
+  ['▌', '#'],
+  ['▝', '#'],
+  ['▘', '#'],
+  ['✦', '*'],
+  ['·', '.'],
+]);
+
+const DARWIN_STENCIL = new Map([
+  ['▐', '#'],
+  ['▛', '#'],
+  ['▜', '#'],
+  ['▌', '#'],
+  ['▝', '#'],
+  ['▘', '#'],
+  ['✦', '*'],
+]);
+
+/** One platform pass over an art block. */
+function portability(rows) {
+  if (process.platform === 'win32') {
+    return rows.map((r) => [...r].map((ch) => ASCII_STENCIL.get(ch) ?? ch).join(''));
+  }
+  if (process.platform === 'darwin') {
+    return rows.map((r) => [...r].map((ch) => DARWIN_STENCIL.get(ch) ?? ch).join(''));
+  }
+  return rows;
+}
+
+/** The mark that fits the current terminal: side-by-side when there's room. */
+function welcomeArtFor(cols) {
+  const wide = portability(WELCOME_ART);
+  const stacked = portability(WELCOME_ART_STACKED);
+  const W = Math.max(...wide.map((r) => [...r].length));
+  return cols >= W + 4 ? wide : stacked;
+}
+
+/**
+ * Split the mark into its two halves so each can carry its own theme ink.
+ * @returns {{rows: Array<[string,string]>, width: number, gutter: number}}
+ */
+function welcomeArtParts(cols) {
+  const mascot = portability(MASCOT_ART);
+  const moonWhale = portability(MOON_WHALE);
+  const L = Math.max(...mascot.map((r) => [...r].length));
+  const R = Math.max(...moonWhale.map((r) => [...r].length));
+  const wide = cols >= L + R + 2 + 4;
+  const gutter = wide ? 2 : 1;
+  if (wide) {
+    // The right half carries the moon *and* the whale. Using WHALE alone here —
+    // which the reference does, because it only wants the per-mascot ink split —
+    // would silently drop the crescent from the welcome screen this CLI renders.
+    const n = Math.max(mascot.length, moonWhale.length);
+    const rows = [];
+    for (let i = 0; i < n; i++) {
+      const li = i + (n - mascot.length);
+      const ri = i + (n - moonWhale.length);
+      rows.push([(mascot[li] ?? '').padEnd(L), (moonWhale[ri] ?? '').padEnd(R)]);
+    }
+    return { rows, width: L + gutter + R, gutter };
+  }
+  const w = Math.max(L, R);
+  const centerBlock = (rows) =>
+    rows.map((r) => ' '.repeat(Math.max(0, Math.floor((w - [...r].length) / 2))) + r);
+  return {
+    rows: [
+      ...centerBlock(mascot).map((c) => [c, '']),
+      ['', ''],
+      ...centerBlock(moonWhale).map((r) => ['', r]),
+    ],
+    width: w,
+    gutter,
+  };
+}
+
+/** Stack two art blocks vertically, each centred, separated by `gap` rows. */
+function stackVertical(top, bottom, gap = 1) {
+  const w = Math.max(...[...top, ...bottom].map((r) => [...r].length));
+  const centerBlock = (rows) =>
+    rows.map((r) => {
+      const pad = Math.max(0, Math.floor((w - [...r].length) / 2));
+      return ' '.repeat(pad) + r;
+    });
+  return [...centerBlock(top), ...Array(gap).fill(''), ...centerBlock(bottom)];
+}
+
+/** Join two art stacks row-aligned (bottom-aligned by default). */
+function joinSideBySide(left, right, gutter = 2, align = 'bottom') {
+  const L = Math.max(...left.map((r) => [...r].length));
+  const R = Math.max(...right.map((r) => [...r].length));
+  const n = Math.max(left.length, right.length);
+  return Array.from({ length: n }, (_, i) => {
+    const li = align === 'bottom' ? i + (n - left.length) : i;
+    const ri = align === 'bottom' ? i + (n - right.length) : i;
+    const l = (left[li] ?? '').padEnd(L);
+    const r = (right[ri] ?? '').padEnd(R);
+    return l + ' '.repeat(gutter) + r;
+  });
+}
+
+/** Centre every row of an art block inside `width` (left pad + right fill). */
+function center(rows, width) {
+  return rows.map((r) => {
+    const pad = Math.max(0, Math.floor((width - [...r].length) / 2));
+    return ' '.repeat(pad) + r + ' '.repeat(Math.max(0, width - [...r].length - pad));
+  });
+}
+
+/** Centre each row against the block's own max width (no trailing fill). */
+function padBoth(rows, width) {
+  const w = Math.max(...rows.map((r) => [...r].length));
+  return rows.map((r) => {
+    const pad = Math.floor((width - w) / 2);
+    return ' '.repeat(Math.max(0, pad)) + r;
+  });
+}
+
+module.exports = {
+  FACE,
+  HAT,
+  MASCOT_ART,
+  MOON,
+  WHALE,
+  MOON_WHALE,
+  WELCOME_ART,
+  WELCOME_ART_STACKED,
+  WELCOME_TITLE,
+  WELCOME_BACK,
+  TAGLINE,
+  portability,
+  welcomeArtFor,
+  welcomeArtParts,
+  stackVertical,
+  joinSideBySide,
+  center,
+  padBoth,
+};

package/src/commands.js

@@ -0,0 +1,263 @@
+'use strict';
+
+/**
+ * Slash commands — the CLI's face on the shared tool registry, using the
+ * command vocabulary of the sibling `aegiscodex-dev` client.
+ *
+ * Three kinds of entry live in one table:
+ *
+ *   (a) tool-backed  — names a tool from `mcp/tools.js` and carries a
+ *       `build(arg) -> object` that turns the typed argument into the tool's
+ *       JSON. `test/cli-tools.test.mjs` asserts both directions: no command
+ *       points at a tool that does not exist, and no tool in the registry is
+ *       unreachable from the prompt, so a new capability added to the registry
+ *       shows up here or fails the build.
+ *   (b) local        — no server call; handled in `app.js` by `cmd.local`.
+ *   (c) unavailable  — a `aegiscodex-dev` command whose capability this client
+ *       genuinely does not have (it needs a local agent loop, Claude Code auth,
+ *       or a repo tool). These carry an honest `why` and are *not* fakes:
+ *       `parseLine` returns `{ kind: 'unavailable' }` and `app.js` prints the
+ *       reason plus a working alternative.
+ *
+ * The names, aliases, categories and descriptions come from
+ * `aegiscodex-dev/src/registry.js` (`COMMANDS`, `CATEGORIES`). Where our
+ * capability differs from the reference's (e.g. `memory` here lists *cloud*
+ * memory, not the reference's local tier store) the description says what this
+ * client actually does rather than copying a sentence that would be untrue.
+ *
+ * Plain text (no leading `/`) is a prompt: it goes to the pooled brain.
+ */
+
+const COMMANDS = [
+  // ── AEGIS tool-backed family (aegiscodex-dev's `aegis` category) ──────────
+  {
+    name: 'aegis-ask',
+    aliases: ['ask'],
+    args: '<question>',
+    category: 'aegis',
+    desc: 'Ask ÆGIS pooled inference a question (auto-routed)',
+    tool: 'aegis_ask',
+    build: (arg) => ({ prompt: arg }),
+  },
+  {
+    // aegiscodex-dev splits this into `aegis-status` (local memory stats) and
+    // `status` (session status); this client has one account-status tool, so
+    // both spellings route to it — `status`/`st` as aliases.
+    name: 'aegis-status',
+    aliases: ['status', 'st'],
+    args: '',
+    category: 'aegis',
+    desc: 'Show account status — API key, plan, account and cloud memory',
+    tool: 'aegis_status',
+    build: () => ({}),
+  },
+  {
+    name: 'aegis-recall',
+    aliases: ['recall'],
+    args: '<topic>',
+    category: 'aegis',
+    desc: 'Recall cross-session memory about a topic',
+    tool: 'aegis_memory_search',
+    build: (arg) => ({ query: arg }),
+  },
+  {
+    name: 'aegis-remember',
+    aliases: ['remember'],
+    args: '<note>',
+    category: 'aegis',
+    desc: 'Save a note or decision to cross-session memory',
+    tool: 'aegis_memory_save',
+    build: (arg) => ({ content: arg }),
+  },
+  {
+    name: 'memory',
+    aliases: ['memories'],
+    args: '',
+    category: 'aegis',
+    desc: 'List the most recent AEGIS cloud-memory entries',
+    tool: 'aegis_memory_list',
+    build: () => ({}),
+  },
+  {
+    // No reference equivalent (the reference has no importer); the name follows
+    // the `/aegis-*` family. Keeps the `--confirm` dry-run semantics: without
+    // the flag the tool only reports what it found.
+    name: 'aegis-import',
+    aliases: ['import'],
+    args: '[--confirm]',
+    category: 'aegis',
+    desc: 'Import memory from other AI tools on this machine (dry run unless --confirm)',
+    tool: 'aegis_memory_import',
+    build: (arg) => ({ confirm: /--confirm\b/.test(arg) }),
+  },
+  {
+    // aegiscodex-dev's `model` switches the brain; this client pins a model id
+    // (local) and lists the pinnable ids with a tool. `models` is the list
+    // action — aegiscodex-dev's `/model list`, surfaced as its own command.
+    name: 'models',
+    aliases: ['model-list'],
+    args: '',
+    category: 'model',
+    desc: 'List the model ids you can pin with /model',
+    tool: 'aegis_list_models',
+    build: () => ({}),
+  },
+  {
+    // aegiscodex-dev has no BYOK surface; these are carried over from the
+    // registry's byok tools. `billing` below is the reference's name for the
+    // balance read the tool performs.
+    name: 'byok',
+    args: '',
+    category: 'auth',
+    desc: 'Show which providers have your own key configured',
+    tool: 'aegis_byok_status',
+    build: () => ({}),
+  },
+  {
+    name: 'byok-set',
+    args: '<provider>',
+    category: 'auth',
+    desc: 'Set YOUR provider key (prompted, never echoed, never in history)',
+    tool: 'aegis_byok_set',
+    secret: 'key',
+    build: (arg) => ({ provider: arg.trim() }),
+  },
+  {
+    name: 'byok-rm',
+    args: '<provider>',
+    category: 'auth',
+    desc: 'Remove a stored provider key',
+    tool: 'aegis_byok_set',
+    build: (arg) => ({ provider: arg.trim() }),
+  },
+  {
+    // aegiscodex-dev's `billing`; `balance` and `spend` stay routable for
+    // muscle memory. Not `cost` — that name is this client's local tally below.
+    name: 'billing',
+    aliases: ['balance', 'spend'],
+    args: '',
+    category: 'support',
+    desc: 'Show billing info — token-bank balance and recent spend',
+    tool: 'aegis_balance',
+    build: () => ({}),
+  },
+  {
+    // The escape hatch for any registry tool, including ones added later.
+    name: 'tool',
+    args: '<name> [json]',
+    category: 'aegis',
+    desc: 'Call any registry tool directly (escape hatch for new tools)',
+    generic: true,
+    build: (arg) => {
+      const sp = arg.indexOf(' ');
+      const name = (sp === -1 ? arg : arg.slice(0, sp)).trim();
+      const rest = sp === -1 ? '' : arg.slice(sp + 1).trim();
+      let args = {};
+      if (rest) {
+        try {
+          args = JSON.parse(rest);
+        } catch (err) {
+          throw new Error(`/tool: arguments must be JSON — ${err.message}`);
+        }
+      }
+      return { tool: name, args };
+    },
+  },
+
+  // ── local commands: no server call, handled by app.js ─────────────────────
+  {
+    name: 'model',
+    aliases: ['m'],
+    args: '[id]',
+    category: 'model',
+    desc: 'Switch AI model — pin an id (no argument shows the pin; `-` clears it)',
+    local: 'model',
+  },
+  { name: 'stream', args: '[on|off]', category: 'model', desc: 'Toggle streaming output', local: 'stream' },
+  { name: 'theme', aliases: ['t'], args: '[dark|light]', category: 'model', desc: 'Change the color theme', local: 'theme' },
+  { name: 'version', aliases: ['v'], args: '', category: 'session', desc: 'Show version', local: 'version' },
+  { name: 'cost', args: '', category: 'data', desc: 'Show the cost of the current session', local: 'cost' },
+  {
+    name: 'tokens',
+    aliases: ['tok'],
+    args: '',
+    category: 'data',
+    desc: 'Show token usage breakdown and estimated spend',
+    local: 'tokens',
+  },
+  { name: 'clear', aliases: ['cls'], args: '', category: 'session', desc: 'Start a new session with empty context', local: 'clear' },
+  { name: 'help', aliases: ['?', 'h'], args: '', category: 'support', desc: 'Show help', local: 'help' },
+  { name: 'exit', aliases: ['quit'], args: '', category: 'session', desc: 'Exit the CLI', local: 'exit' },
+
+  // ── unavailable: aegiscodex-dev vocabulary this client cannot honour ───────
+  // Not fakes — each names why it is absent and, where one exists, the nearest
+  // working command. `parseLine` surfaces these as `kind: 'unavailable'`.
+  { name: 'login', args: '', category: 'auth', desc: 'Sign in to Claude Code', unavailable: true, why: 'sign-in uses Claude Code auth, which this client does not have — it authenticates with your AEGIS key', alt: '/byok-set' },
+  { name: 'logout', args: '', category: 'auth', desc: 'Sign out', unavailable: true, why: 'there is no Claude Code sign-in here to end' },
+  { name: 'doctor', args: '', category: 'support', desc: 'Run diagnostic checks on this environment', unavailable: true, why: 'the diagnostic suite belongs to aegiscodex-dev, not this client', alt: '/status' },
+  { name: 'permissions', args: '[mode] [pattern]', category: 'model', desc: 'Set permissions for tool use', unavailable: true, why: 'tool-permission prompts require a local agent loop this client does not run' },
+  { name: 'mcp', args: '[sub]', category: 'model', desc: 'Show MCP server configuration', unavailable: true, why: 'this CLI is itself an MCP host, so it has no MCP servers to configure', alt: '/tool' },
+  { name: 'skills', aliases: ['sk'], args: '[name|refresh]', category: 'session', desc: 'List skills (SKILL.md in the standard skill dirs)', unavailable: true, why: 'skills run inside the agent loop, which this client does not host' },
+  { name: 'hooks', args: '[status|list]', category: 'model', desc: 'View hooks configuration status and configured hook list', unavailable: true, why: 'hooks are a local agent-loop feature this client does not run' },
+  { name: 'agents', aliases: ['sessions'], args: '[role] [task]', category: 'session', desc: 'Show the agents panel, or run a sub-agent role preset — /agents <role> <task>', unavailable: true, why: 'sub-agents need a local agent loop this client does not host' },
+  { name: 'resume', args: '', category: 'session', desc: 'Switch to a previous session', unavailable: true, why: 'this client keeps no session history to resume' },
+  { name: 'rewind', args: '[N]', category: 'session', desc: 'Revert the conversation to a checkpoint', unavailable: true, why: 'checkpoints belong to a session history this client does not keep' },
+  { name: 'compact', args: '', category: 'session', desc: 'Compact the conversation history', unavailable: true, why: 'there is no local transcript to compact' },
+  { name: 'init', args: '[file]', category: 'workspace', desc: 'Create a CLAUDE.md file in the project', unavailable: true, why: 'project scaffolding is a workspace feature this client does not have', alt: '/aegis-remember' },
+  { name: 'export', args: '[markdown|json] [file|clipboard]', category: 'data', desc: 'Export the current conversation to a file or clipboard', unavailable: true, why: 'this client keeps no transcript to export' },
+  { name: 'vim', args: '[on|off]', category: 'model', desc: 'Toggle vim keymap', unavailable: true, why: 'input is your terminal readline, which has no vim keymap' },
+  { name: 'yolo', args: '[on|off]', category: 'model', desc: 'Toggle YOLO mode — auto-approve all tool executions', unavailable: true, why: 'there is no tool-approval prompt here to auto-approve' },
+  { name: 'confirm', aliases: ['confirmations'], args: '[on|off]', category: 'model', desc: 'Toggle tool-call confirmation prompts', unavailable: true, why: 'there is no tool-approval prompt here to toggle' },
+];
+
+// ── Index + the one invariant a table like this must hold ────────────────────
+// A name or alias registered twice would silently shadow the earlier entry, so
+// the collision is a module-load error rather than a runtime surprise. (The
+// reference keeps `builtinNames()` for exactly this; its test asserts the same.)
+
+const BY_NAME = new Map();
+for (const c of COMMANDS) {
+  for (const n of [c.name, ...(c.aliases || [])]) {
+    if (BY_NAME.has(n)) {
+      throw new Error(`aegiscode: command name or alias /${n} is registered twice`);
+    }
+    BY_NAME.set(n, c);
+  }
+}
+
+function findCommand(name) {
+  return BY_NAME.get(String(name || '').toLowerCase()) || null;
+}
+
+/**
+ * Classify one input line.
+ * @returns {{kind:'empty'}
+ *   |{kind:'command',command:object,arg:string}
+ *   |{kind:'unavailable',command:object,arg:string}
+ *   |{kind:'unknown',name:string,text:string}
+ *   |{kind:'prompt',text:string}}
+ */
+function parseLine(line) {
+  const raw = String(line == null ? '' : line);
+  const trimmed = raw.trim();
+  if (!trimmed) return { kind: 'empty' };
+  if (trimmed[0] !== '/') return { kind: 'prompt', text: trimmed };
+  const sp = trimmed.indexOf(' ');
+  const name = (sp === -1 ? trimmed.slice(1) : trimmed.slice(1, sp)).trim();
+  const arg = sp === -1 ? '' : trimmed.slice(sp + 1).trim();
+  const command = findCommand(name);
+  if (!command) {
+    return { kind: 'unknown', name, text: trimmed };
+  }
+  if (command.unavailable) {
+    return { kind: 'unavailable', command, arg };
+  }
+  return { kind: 'command', command, arg };
+}
+
+/** Commands that map to a registry tool, for the coverage test. */
+function toolBackedCommands() {
+  return COMMANDS.filter((c) => c.tool);
+}
+
+module.exports = { COMMANDS, findCommand, parseLine, toolBackedCommands };

package/src/deps.js

@@ -0,0 +1,65 @@
+'use strict';
+
+/**
+ * Where the CLI finds the modules it shares with the rest of the repo.
+ *
+ * Two layouts must work:
+ *
+ *   in-repo   <repo>/cli/src/deps.js   -> <repo>/client/aegis.js, <repo>/mcp/tools.js
+ *   npm       <pkg>/src/deps.js        -> <pkg>/vendor/{client,mcp,desktop}/...
+ *
+ * The published package is staged by `scripts/predist.mjs` into `cli/vendor/`
+ * keeping the repo's own relative shape, so nothing here (or in the copied
+ * files) needs a path rewrite — `vendor/mcp/tools.js` requiring
+ * `../client/foreign-memory.js` resolves inside the vendor tree by construction.
+ *
+ * Resolution is by existence, and a missing module is a loud error rather than
+ * a silent fallback to a second copy: duplicate transports are how the two
+ * hosts would drift.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function roots() {
+  const srcDir = __dirname; // <root>/cli/src
+  const cliDir = path.join(srcDir, '..');
+  return [
+    path.join(srcDir, '..', '..'), // repo root (in-repo layout)
+    path.join(cliDir, 'vendor'), // staged tree (published layout)
+  ];
+}
+
+/** Resolve a repo-relative module path against whichever root has it. */
+function resolveShared(relPath) {
+  for (const root of roots()) {
+    const candidate = path.join(root, relPath);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  throw new Error(
+    `aegiscode: cannot find ${relPath}. Expected it beside cli/ (in the repo) or ` +
+      'under cli/vendor/ (installed package). Reinstall the package, or run ' +
+      '`node scripts/predist.mjs` from cli/ if this is a source checkout.'
+  );
+}
+
+const clientPath = resolveShared(path.join('client', 'aegis.js'));
+const toolsPath = resolveShared(path.join('mcp', 'tools.js'));
+// The desktop's pure usage module is the single source of truth for turning a
+// provider's usage object into a display number. The CLI reuses the same file
+// instead of re-implementing the mapping, so the terminal and the GUI can never
+// disagree about what a call consumed (test/cli-tools.test.mjs asserts the
+// function identity).
+const usagePath = resolveShared(path.join('desktop', 'renderer', 'usage.js'));
+
+const { createClient } = require(clientPath);
+const { createTools } = require(toolsPath);
+const { usageTokens } = require(usagePath);
+
+module.exports = {
+  createClient,
+  createTools,
+  usageTokens,
+  paths: { client: clientPath, tools: toolsPath, usage: usagePath },
+  roots,
+};

package/src/format.js

@@ -0,0 +1,54 @@
+'use strict';
+
+/**
+ * Number/text formatting for the CLI — one place, so the transcript, the status
+ * bar and the headless `--print` output always agree.
+ *
+ * The sub-cent rule mirrors the server-side ledger: AEGIS pooled calls settle
+ * around €0.0007, so a 2dp rendering shows a real charge as "€0.00" next to its
+ * token count and reads as free usage.
+ */
+
+/** Group digits: 1562 -> "1,562". */
+function fmtTokens(n) {
+  const v = Number(n);
+  if (!Number.isFinite(v) || v <= 0) return '0';
+  return Math.round(v)
+    .toString()
+    .replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
+
+/** € amount, 4dp below a cent (per-call spend) and 2dp above it (top-ups). */
+function fmtEur(n) {
+  const v = Number(n);
+  if (!Number.isFinite(v)) return '€?';
+  const abs = Math.abs(v);
+  return `€${abs < 0.01 ? abs.toFixed(4) : abs.toFixed(2)}`;
+}
+
+/** Signed € amount, from the user's side: -€0.0007 spent, +€5.00 added. */
+function fmtEurSigned(n) {
+  const v = Number(n);
+  if (!Number.isFinite(v)) return '€?';
+  return `${v < 0 ? '-' : '+'}${fmtEur(Math.abs(v))}`;
+}
+
+/** Compact duration: 850 -> "0.9s", 65000 -> "1m05s". */
+function fmtElapsed(ms) {
+  const s = Math.max(0, Number(ms) || 0) / 1000;
+  if (s < 10) return `${s.toFixed(1)}s`;
+  if (s < 60) return `${Math.round(s)}s`;
+  const m = Math.floor(s / 60);
+  const rest = Math.round(s - m * 60);
+  return `${m}m${String(rest).padStart(2, '0')}s`;
+}
+
+/** Mask an API key for display: never echo enough to be useful if leaked. */
+function maskKey(key) {
+  const s = String(key || '');
+  if (!s) return 'not set';
+  if (s.length <= 8) return '•'.repeat(s.length);
+  return `${s.slice(0, 6)}${'•'.repeat(4)}${s.slice(-4)}`;
+}
+
+module.exports = { fmtTokens, fmtEur, fmtEurSigned, fmtElapsed, maskKey };