@usenexus/cli 0.0.2 → 0.1.0

package/server/server.mjs

@@ -0,0 +1,279 @@
+// The local server: 127.0.0.1 only, a random port, a per-launch token,
+// and a strict Host + Origin check, so no other site or local page can
+// drive the person's Claude Code through it.
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { createHub } from './hub.mjs';
+import { createProvider, PERMISSION_MODES } from './provider.mjs';
+import { txFromMessage, newTxContext } from './normalize.mjs';
+import { beatsFromMessage, newBeatContext, MAIN } from '../shared/beats.mjs';
+import { preflight } from './preflight.mjs';
+import * as repoMod from './repo.mjs';
+import * as gh from './gh.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const PKG = path.resolve(HERE, '..');
+const MAX_BODY = 1024 * 1024;
+
+export const ADOPT_PASTE = [
+  'Clone https://github.com/daretodave/nexus.git to',
+  "../nexus (or use ./.nexus if submoduled) if you haven't",
+  'already, then read and follow ../nexus/prompts/adopt.md',
+  'exactly, in order. Do not skip steps or invent scope beyond',
+  'what it says.',
+].join('\n');
+
+const TYPES = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.svg': 'image/svg+xml', '.json': 'application/json', '.woff2': 'font/woff2', '.png': 'image/png', '.ico': 'image/x-icon' };
+
+function readPrompt(name) {
+  for (const dir of [path.join(PKG, 'prompts'), path.resolve(PKG, '..', '..', 'prompts')]) {
+    const f = path.join(dir, name);
+    if (fs.existsSync(f)) return fs.readFileSync(f, 'utf8');
+  }
+  return '';
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.repo            the adopter repo (cwd for sessions)
+ * @param {number} [o.port=0]        0 = any free port
+ * @param {string} [o.token]         defaults to a fresh random token
+ * @param {object|function} [o.provider]  inject a provider, or a factory given the hooks (tests)
+ * @param {boolean} [o.pollRuns=true]
+ */
+export async function startServer({ repo, port = 0, token = crypto.randomBytes(24).toString('base64url'), provider: injected, pollRuns = true, dist = path.join(PKG, 'dist') } = {}) {
+  const hub = createHub();
+  const asks = new Map();
+  const permissions = new Map();
+  let txCtx = newTxContext();
+  let beatCtx = newBeatContext();
+  let prefs = await repoMod.readPrefs(repo);
+  let busy = false;
+
+  const publishAsks = () => hub.set('asks', [...asks.values()].map((a) => a.view));
+  const publishPerms = () => hub.set('permissions', [...permissions.values()].map((a) => a.view));
+
+  const onMessage = (msg) => {
+    for (const item of txFromMessage(msg, txCtx)) hub.tx(item);
+    for (const b of beatsFromMessage(msg, beatCtx)) hub.beat(b);
+    if (msg.type === 'result') {
+      busy = false;
+      hub.setStatus({ state: 'idle', cost: msg.total_cost_usd ?? null, session: msg.session_id || null });
+    }
+  };
+
+  const onAsk = ({ id, agent, questions, signal }) => new Promise((resolve) => {
+    const view = { id, agent, questions, at: Date.now() };
+    asks.set(id, { view, resolve });
+    // The SDK's agentID is a subagent's own id, not the tool_use id the stage
+    // draws it under, so stage beats attach questions to the session orb.
+    hub.beat({ k: 'oversight', p: 'ask', id, agent: MAIN });
+    publishAsks();
+    signal?.addEventListener('abort', () => {
+      if (!asks.has(id)) return;
+      asks.delete(id);
+      hub.beat({ k: 'oversight', p: 'answer', id });
+      publishAsks();
+      resolve(null);
+    });
+  });
+
+  const onPermission = ({ id, agent, tool, input, suggestions, reason, signal }) => new Promise((resolve) => {
+    const view = { id, agent, tool, summary: JSON.stringify(input).slice(0, 400), reason: reason || null, canAlways: !!(suggestions && suggestions.length) };
+    permissions.set(id, { view, resolve });
+    if (!agent || agent === MAIN) hub.beat({ k: 'agent', p: 'wait', id: MAIN });
+    publishPerms();
+    signal?.addEventListener('abort', () => {
+      if (!permissions.delete(id)) return;
+      publishPerms();
+      resolve({ allow: false });
+    });
+  });
+
+  const hooks = {
+    repo,
+    onMessage,
+    onAsk,
+    onPermission,
+    onStatus: (s) => { if (s.state === 'idle') busy = false; hub.setStatus(s); },
+    permissionMode: () => prefs.permissionMode,
+  };
+  const provider = typeof injected === 'function' ? injected(hooks) : injected || await createProvider(hooks);
+  hub.setStatus({ state: 'idle', provider: provider.kind });
+
+  const server = http.createServer((req, res) => {
+    handle(req, res).catch((e) => send(res, 500, { error: String(e && e.message ? e.message : e) }));
+  });
+  await new Promise((r) => server.listen(port, '127.0.0.1', r));
+  const actual = server.address().port;
+  const origins = new Set([`http://127.0.0.1:${actual}`, `http://localhost:${actual}`]);
+  const hosts = new Set([`127.0.0.1:${actual}`, `localhost:${actual}`]);
+
+  function guard(req, url) {
+    if (!hosts.has(req.headers.host || '')) return 'bad host';
+    const origin = req.headers.origin;
+    if (origin && !origins.has(origin)) return 'bad origin';
+    if (req.method !== 'GET' && !origin) return 'missing origin';
+    const given = req.headers['x-nexus-token'] || url.searchParams.get('t') || '';
+    const a = Buffer.from(String(given));
+    const b = Buffer.from(token);
+    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return 'bad token';
+    return null;
+  }
+
+  async function body(req) {
+    if (!/^application\/json\b/.test(req.headers['content-type'] || '')) throw Object.assign(new Error('json only'), { status: 415 });
+    let size = 0;
+    const chunks = [];
+    for await (const c of req) {
+      size += c.length;
+      if (size > MAX_BODY) throw Object.assign(new Error('too large'), { status: 413 });
+      chunks.push(c);
+    }
+    try { return JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'); } catch { throw Object.assign(new Error('bad json'), { status: 400 }); }
+  }
+
+  // A send while a turn is under way is a tug (steering mid-run); the
+  // session itself stays open between turns, so "active" is not "busy".
+  function sendPrompt(text) {
+    const running = busy;
+    busy = true;
+    hub.tx({ kind: 'user', text });
+    if (running) hub.beat({ k: 'oversight', p: 'tug', agent: MAIN });
+    else hub.beat({ k: 'agent', p: 'start', id: MAIN, label: 'session' });
+    provider.send(text);
+  }
+
+  async function handle(req, res) {
+    const url = new URL(req.url, 'http://127.0.0.1');
+    if (!url.pathname.startsWith('/api/')) return serveStatic(req, res, url);
+    const bad = guard(req, url);
+    if (bad) return send(res, 403, { error: bad });
+    const route = `${req.method} ${url.pathname}`;
+    try {
+      switch (route) {
+        case 'GET /api/events': return hub.attach(req, res);
+        case 'GET /api/state': return send(res, 200, { info: await repoMod.repoInfo(repo), prefs, commands: repoMod.listCommands(repo), provider: provider.kind, permissionModes: PERMISSION_MODES });
+        case 'GET /api/preflight': return send(res, 200, await preflight(repo));
+        case 'GET /api/prompts': return send(res, 200, { paste: ADOPT_PASTE, adopt: readPrompt('adopt.md'), pitch: readPrompt('pitch.md') });
+        case 'POST /api/prefs': { const b = await body(req); if (b.permissionMode && !PERMISSION_MODES.includes(b.permissionMode)) delete b.permissionMode; prefs = await repoMod.writePrefs(repo, b); return send(res, 200, prefs); }
+        case 'POST /api/owner': { const b = await body(req); return send(res, 200, { owner: await repoMod.setOwner(repo, !!b.on) }); }
+        case 'POST /api/send': {
+          const b = await body(req);
+          const text = String(b.text || '').trim();
+          if (!text) return send(res, 400, { error: 'empty prompt' });
+          sendPrompt(text);
+          return send(res, 200, { ok: true });
+        }
+        case 'POST /api/adopt': await body(req); sendPrompt(ADOPT_PASTE); return send(res, 200, { ok: true });
+        case 'POST /api/interrupt': await body(req); await provider.interrupt(); return send(res, 200, { ok: true });
+        case 'POST /api/stop': await body(req); await provider.stop(); return send(res, 200, { ok: true });
+        case 'POST /api/fresh': {
+          await body(req);
+          await provider.fresh();
+          txCtx = newTxContext();
+          beatCtx = newBeatContext();
+          hub.reset();
+          return send(res, 200, { ok: true });
+        }
+        case 'GET /api/oversight': return send(res, 200, { live: [...asks.values()].map((a) => a.view), durable: repoMod.durableQuestions(repo) });
+        case 'POST /api/oversight/answer': {
+          const b = await body(req);
+          const rows = (Array.isArray(b.answers) ? b.answers : []).filter((a) => a && a.file && a.answer && String(a.answer).trim());
+          if (!rows.length) return send(res, 400, { error: 'no answers' });
+          sendPrompt(repoMod.answersPrompt(rows.map((a) => ({ file: String(a.file), line: Number(a.line) || 0, text: String(a.text || ''), answer: String(a.answer) })), repoMod.isOwner(repo)));
+          return send(res, 200, { ok: true });
+        }
+        case 'GET /api/claims': return send(res, 200, await repoMod.claims(repo));
+        case 'POST /api/claims/release': { const b = await body(req); return send(res, 200, await repoMod.releaseClaim(repo, String(b.id || ''))); }
+        case 'GET /api/progress': return send(res, 200, await repoMod.progress(repo, url.searchParams.get('spec')));
+        case 'GET /api/actions': return send(res, 200, await gh.actionsSetup(repo));
+        case 'POST /api/actions/workflow': { const b = await body(req); return send(res, 200, await gh.setWorkflow(repo, b.id, !!b.enabled)); }
+        case 'GET /api/runs': return send(res, 200, await gh.listRuns(repo));
+      }
+      const ask = /^POST \/api\/ask\/([\w-]+)$/.exec(route);
+      if (ask) {
+        const b = await body(req);
+        const entry = asks.get(ask[1]);
+        if (!entry) return send(res, 404, { error: 'no such question (already answered or expired)' });
+        asks.delete(ask[1]);
+        hub.beat({ k: 'oversight', p: 'answer', id: ask[1] });
+        publishAsks();
+        const answers = b.answers && typeof b.answers === 'object' ? Object.fromEntries(Object.entries(b.answers).map(([k, v]) => [String(k), String(v)])) : null;
+        entry.resolve(answers);
+        return send(res, 200, { ok: true });
+      }
+      const perm = /^POST \/api\/permission\/([\w-]+)$/.exec(route);
+      if (perm) {
+        const b = await body(req);
+        const entry = permissions.get(perm[1]);
+        if (!entry) return send(res, 404, { error: 'no such request' });
+        permissions.delete(perm[1]);
+        publishPerms();
+        entry.resolve({ allow: !!b.allow, always: !!b.always });
+        return send(res, 200, { ok: true });
+      }
+      return send(res, 404, { error: 'not found' });
+    } catch (e) {
+      return send(res, e.status || 500, { error: String(e.message || e) });
+    }
+  }
+
+  function serveStatic(req, res, url) {
+    if (req.method !== 'GET' && req.method !== 'HEAD') return send(res, 405, { error: 'method' });
+    if (!hosts.has(req.headers.host || '')) return send(res, 403, { error: 'bad host' });
+    let rel;
+    try { rel = decodeURIComponent(url.pathname); } catch { return send(res, 400, { error: 'bad path' }); }
+    if (rel === '/' || !path.extname(rel)) rel = '/index.html';
+    const file = path.resolve(dist, `.${rel}`);
+    if (!file.startsWith(path.resolve(dist) + path.sep)) return send(res, 403, { error: 'path' });
+    if (!fs.existsSync(file)) {
+      if (rel === '/index.html') {
+        res.writeHead(200, { 'content-type': TYPES['.html'] });
+        return res.end('<!doctype html><meta charset="utf-8"><title>nexus</title><p>The UI is not built. Run <code>npm run build</code> in packages/cli.</p>');
+      }
+      return send(res, 404, { error: 'not found' });
+    }
+    res.writeHead(200, {
+      'content-type': TYPES[path.extname(file)] || 'application/octet-stream',
+      'cache-control': rel === '/index.html' ? 'no-store' : 'public, max-age=31536000, immutable',
+      'x-content-type-options': 'nosniff',
+      'referrer-policy': 'no-referrer',
+      ...(rel === '/index.html' ? { 'content-security-policy': "default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'none'" } : {}),
+    });
+    fs.createReadStream(file).pipe(res);
+  }
+
+  // Live Actions runs -> loop beats, only while a tab is watching.
+  const seenRuns = new Map();
+  let ghBroken = 0;
+  const poll = pollRuns ? setInterval(async () => {
+    if (!hub.clients || Date.now() < ghBroken) return;
+    const r = await gh.listRuns(repo);
+    if (!r.ok) { ghBroken = Date.now() + 60000; return; }
+    hub.set('runs', r.runs);
+    for (const b of gh.runBeats(r.runs, seenRuns)) hub.beat(b);
+  }, gh.POLL_MS) : null;
+
+  return {
+    url: `http://127.0.0.1:${actual}/?t=${encodeURIComponent(token)}`,
+    port: actual,
+    token,
+    hub,
+    async close() {
+      if (poll) clearInterval(poll);
+      await provider.stop?.();
+      hub.close();
+      await new Promise((r) => server.close(r));
+    },
+  };
+}
+
+function send(res, status, data) {
+  if (res.headersSent) return res.end();
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+  res.end(JSON.stringify(data));
+}

package/server/sh.mjs

@@ -0,0 +1,47 @@
+// One way to run a local program: no shell interpolation of user text,
+// a timeout, and a result object instead of a throw.
+import { spawn } from 'node:child_process';
+
+const WIN = process.platform === 'win32';
+
+// On Windows, npm-installed CLIs are .cmd shims that need a shell. Every
+// argument passed through here is either a constant or validated by the
+// caller (SAFE_ARG), so quoting is not a user-controlled surface.
+export const SAFE_ARG = /^[\w@./:=,+{}-]*$/;
+
+export function run(cmd, args = [], { cwd, timeout = 20000, input } = {}) {
+  return new Promise((resolve) => {
+    for (const a of args) {
+      if (WIN && !SAFE_ARG.test(a)) return resolve({ ok: false, code: -1, stdout: '', stderr: `refused unsafe argument: ${a}` });
+    }
+    let child;
+    try {
+      // Joined by hand on Windows: every argument passed SAFE_ARG above.
+      child = WIN
+        ? spawn([cmd, ...args].join(' '), { cwd, shell: true, windowsHide: true, env: process.env })
+        : spawn(cmd, args, { cwd, windowsHide: true, env: process.env });
+    } catch (e) {
+      return resolve({ ok: false, code: -1, stdout: '', stderr: String(e.message || e), missing: true });
+    }
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => { child.kill(); stderr += `\ntimed out after ${timeout} ms`; }, timeout);
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', (d) => { stderr += d; });
+    child.on('error', (e) => {
+      clearTimeout(timer);
+      resolve({ ok: false, code: -1, stdout, stderr: String(e.message || e), missing: e.code === 'ENOENT' });
+    });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      const missing = code === 127 || (WIN && code === 1 && /is not recognized/.test(stderr));
+      resolve({ ok: code === 0, code, stdout, stderr, missing });
+    });
+    if (input != null) child.stdin.end(input);
+    else child.stdin.end();
+  });
+}
+
+export function json(text) {
+  try { return JSON.parse(text); } catch { return null; }
+}

package/shared/beats.mjs

@@ -0,0 +1,190 @@
+// Beats: the only things that move the agent stage.
+//
+// A beat is a small structured fact ("agent X started", "chunk 12.3
+// reached the gate"). The stage never reads transcript words; it reduces
+// beats. The reducer is pure (no clock, no DOM, no randomness), so a page
+// opened mid-run, a refresh, and a page that watched from the start all
+// reach the same state by replaying the same beats.
+//
+// Kinds and phases:
+//   chunk      claim | build | gate | archive        { id }
+//   agent      start | tool | wait | end            { id, parent?, label?, tool?, ok? }
+//   loop       dispatch | run | conclude            { id, name?, conclusion? }
+//   oversight  ask | answer | tug                   { id?, agent?, text? }
+
+export const LANES = 5;
+export const MAIN = 'main';
+
+export const KINDS = {
+  chunk: ['claim', 'build', 'gate', 'archive'],
+  agent: ['start', 'tool', 'wait', 'end'],
+  loop: ['dispatch', 'run', 'conclude'],
+  oversight: ['ask', 'answer', 'tug'],
+};
+
+export function isBeat(b) {
+  return !!b && typeof b === 'object' && Array.isArray(KINDS[b.k]) && KINDS[b.k].includes(b.p);
+}
+
+export function initialState() {
+  return {
+    seq: 0,
+    agents: {},
+    order: [],
+    chunks: {},
+    chunkOrder: [],
+    current: null,
+    loops: {},
+    loopOrder: [],
+    asks: {},
+    tugs: 0,
+    lastTug: null,
+  };
+}
+
+function ensureAgent(s, id, parent) {
+  if (s.agents[id]) return s.agents[id];
+  const children = s.order.filter((a) => a !== MAIN).length;
+  const a = {
+    id,
+    parent: id === MAIN ? null : parent || MAIN,
+    label: id === MAIN ? 'session' : '',
+    state: 'running',
+    tool: null,
+    tools: 0,
+    slot: id === MAIN ? 0 : (children % LANES) + 1,
+    ok: null,
+  };
+  s.agents[id] = a;
+  s.order.push(id);
+  return a;
+}
+
+/** Reduce one beat. Returns a new state; the input is not mutated. */
+export function reduce(prev, beat) {
+  if (!isBeat(beat)) return prev;
+  const s = structuredCloneLite(prev);
+  s.seq += 1;
+  switch (beat.k) {
+    case 'agent': {
+      const id = beat.id || MAIN;
+      if (id !== MAIN && !s.agents[MAIN]) ensureAgent(s, MAIN);
+      const a = ensureAgent(s, id, beat.parent);
+      if (beat.label) a.label = String(beat.label).slice(0, 80);
+      if (beat.p === 'start') { a.state = 'running'; a.ok = null; }
+      if (beat.p === 'tool') { a.state = 'running'; a.tool = beat.tool || null; a.tools += 1; }
+      if (beat.p === 'wait') a.state = 'waiting';
+      if (beat.p === 'end') { a.state = beat.ok === false ? 'failed' : 'done'; a.ok = beat.ok !== false; a.tool = null; }
+      break;
+    }
+    case 'chunk': {
+      if (!beat.id) break;
+      if (!s.chunks[beat.id]) { s.chunks[beat.id] = { id: beat.id, stage: beat.p }; s.chunkOrder.push(beat.id); }
+      s.chunks[beat.id].stage = beat.p;
+      s.current = beat.p === 'archive' ? (s.current === beat.id ? null : s.current) : beat.id;
+      break;
+    }
+    case 'loop': {
+      if (!beat.id) break;
+      if (!s.loops[beat.id]) { s.loops[beat.id] = { id: beat.id, name: beat.name || '', status: beat.p, conclusion: null }; s.loopOrder.push(beat.id); }
+      const l = s.loops[beat.id];
+      l.status = beat.p;
+      if (beat.name) l.name = beat.name;
+      if (beat.p === 'conclude') l.conclusion = beat.conclusion || 'unknown';
+      break;
+    }
+    case 'oversight': {
+      if (beat.p === 'ask' && beat.id) {
+        s.asks[beat.id] = { id: beat.id, agent: beat.agent || MAIN, open: true };
+        const a = s.agents[beat.agent || MAIN];
+        if (a) a.state = 'waiting';
+      }
+      if (beat.p === 'answer' && beat.id && s.asks[beat.id]) {
+        s.asks[beat.id].open = false;
+        const a = s.agents[s.asks[beat.id].agent];
+        if (a && a.state === 'waiting') a.state = 'running';
+      }
+      if (beat.p === 'tug') { s.tugs += 1; s.lastTug = { n: s.tugs, agent: beat.agent || MAIN }; }
+      break;
+    }
+  }
+  return s;
+}
+
+export function replay(beats, from = initialState()) {
+  let s = from;
+  for (const b of beats) s = reduce(s, b);
+  return s;
+}
+
+export function openAsks(s) {
+  return Object.values(s.asks).filter((a) => a.open);
+}
+
+// JSON-shaped state only, so a JSON round trip is an exact clone.
+function structuredCloneLite(s) {
+  return JSON.parse(JSON.stringify(s));
+}
+
+// --- beats from an agent message stream ------------------------------------
+// Maps one SDK / stream-json message to zero or more beats. `ctx` carries the
+// tool_use ids that spawned subagents, so their results end the right node.
+// Structured fields only: tool names, tool inputs, parent_tool_use_id.
+
+const SPAWN_TOOLS = new Set(['Task', 'Agent']);
+const CLAIM_RE = /claims(?:\.mjs)?\s+claim\s+([0-9]+(?:\.[0-9a-z]+)?)/i;
+const GATE_RE = /(verify\.mjs|check\.mjs|npm run (?:check|verify|test)|pnpm (?:verify|check))/i;
+const PENDING_RE = /plan[\\/]pending[\\/]([0-9]+(?:\.[0-9a-z]+)?)\.md/i;
+
+export function newBeatContext() {
+  return { spawns: {}, chunk: null };
+}
+
+export function beatsFromMessage(msg, ctx) {
+  const out = [];
+  if (!msg || typeof msg !== 'object') return out;
+  const parent = msg.parent_tool_use_id || null;
+  if (msg.type === 'system' && msg.subtype === 'init') out.push({ k: 'agent', p: 'start', id: MAIN, label: 'session' });
+  if (msg.type === 'system' && msg.subtype === 'task_started' && msg.tool_use_id && !ctx.spawns[msg.tool_use_id]) {
+    ctx.spawns[msg.tool_use_id] = true;
+    out.push({ k: 'agent', p: 'start', id: msg.tool_use_id, parent: MAIN, label: msg.description || msg.subagent_type || 'task' });
+  }
+  if (msg.type === 'system' && msg.subtype === 'task_notification' && msg.tool_use_id) {
+    out.push({ k: 'agent', p: 'end', id: msg.tool_use_id, ok: msg.status === 'completed' });
+  }
+  if (msg.type === 'assistant' && msg.message && Array.isArray(msg.message.content)) {
+    for (const block of msg.message.content) {
+      if (block.type !== 'tool_use') continue;
+      const input = block.input || {};
+      if (SPAWN_TOOLS.has(block.name)) {
+        if (!ctx.spawns[block.id]) {
+          ctx.spawns[block.id] = true;
+          out.push({ k: 'agent', p: 'start', id: block.id, parent: parent || MAIN, label: input.description || input.subagent_type || 'subagent' });
+          if (ctx.chunk) out.push({ k: 'chunk', p: 'build', id: ctx.chunk });
+        }
+        continue;
+      }
+      out.push({ k: 'agent', p: 'tool', id: parent || MAIN, tool: block.name });
+      const cmd = typeof input.command === 'string' ? input.command : '';
+      const file = typeof input.file_path === 'string' ? input.file_path : '';
+      const claim = CLAIM_RE.exec(cmd);
+      if (claim) { ctx.chunk = claim[1]; out.push({ k: 'chunk', p: 'claim', id: claim[1] }); }
+      else if (ctx.chunk && GATE_RE.test(cmd)) out.push({ k: 'chunk', p: 'gate', id: ctx.chunk });
+      const pending = PENDING_RE.exec(file) || PENDING_RE.exec(cmd);
+      if (pending && /^(Write|Edit)$/.test(block.name)) {
+        out.push({ k: 'chunk', p: 'archive', id: pending[1] });
+        if (ctx.chunk === pending[1]) ctx.chunk = null;
+      }
+    }
+  }
+  if (msg.type === 'user' && msg.message && Array.isArray(msg.message.content)) {
+    for (const block of msg.message.content) {
+      if (block && block.type === 'tool_result' && ctx.spawns[block.tool_use_id] === true) {
+        ctx.spawns[block.tool_use_id] = 'ended';
+        out.push({ k: 'agent', p: 'end', id: block.tool_use_id, ok: !block.is_error });
+      }
+    }
+  }
+  if (msg.type === 'result') out.push({ k: 'agent', p: 'end', id: MAIN, ok: !msg.is_error });
+  return out;
+}

package/shared/route.mjs

@@ -0,0 +1,60 @@
+// Composer routing: what free text becomes before it reaches the session.
+//
+//   "/anything ..."           runs as typed (a slash command)
+//   "fix this bug please"     /bug <text>    reproduce, fix if small, else plot asap
+//   "add dark mode export"    /plot <text>   research, spec, chunk, slot in line
+//   "why is the gate red?"    asked inline   a plain question, answered in place
+//
+// The UI shows the route before sending and lets the person override it.
+
+export const ROUTES = ['ask', 'bug', 'plot', 'slash'];
+
+/** GUI-only aliases: the name on the button, the command it runs. */
+export const ALIASES = { '/explode': '/messy' };
+
+const QUESTION_START = /^(what|why|how|where|when|who|which|is|are|was|were|can|could|does|do|did|should|would|will|has|have|explain|tell me)\b/i;
+const BUG_WORDS = /\b(bug|bugs|broken|breaks|crash(?:es|ed|ing)?|error|errors|exception|fails?|failing|failed|regression|doesn'?t work|does not work|not working|wrong|fix|fixes|glitch)\b/i;
+
+export function classify(text) {
+  const t = String(text || '').trim();
+  if (!t) return null;
+  if (t.startsWith('/')) return 'slash';
+  if (BUG_WORDS.test(t) && !/\?$/.test(t)) return 'bug';
+  if (/\?$/.test(t) || QUESTION_START.test(t)) return BUG_WORDS.test(t) && /\b(fix|please)\b/i.test(t) ? 'bug' : 'ask';
+  return 'plot';
+}
+
+/** The prompt actually sent for `text` under `route` (default: classify(text)). */
+export function toPrompt(text, route = classify(text), flags = {}) {
+  const t = String(text || '').trim();
+  if (!t || !route) return '';
+  let out;
+  if (route === 'slash') {
+    const [head, ...rest] = t.split(/\s+/);
+    const cmd = ALIASES[head.toLowerCase()] || head;
+    out = [cmd, ...rest].join(' ');
+  } else if (route === 'bug') out = `/bug ${t}`;
+  else if (route === 'plot') out = `/plot ${t}`;
+  else out = t;
+  return withRunFlags(out, flags);
+}
+
+/**
+ * "Delegate to sub-agents" / "Use workflows": overrides for /next and
+ * /heads-down. Neither checked leaves the size default (S/M agent, L workflow).
+ */
+export function withRunFlags(prompt, { agents = false, workflows = false } = {}) {
+  if (!/^\/(next|heads-down)\b/.test(prompt)) return prompt;
+  if (/--(agents|workflow)\b/.test(prompt)) return prompt;
+  if (workflows) return `${prompt} --workflow`;
+  if (agents) return `${prompt} --agents`;
+  return prompt;
+}
+
+/** Slash completions for a draft: commands whose name starts with the typed word. */
+export function complete(draft, commands) {
+  const m = /^\/([\w:-]*)$/.exec(String(draft || ''));
+  if (!m) return [];
+  const want = m[1].toLowerCase();
+  return commands.filter((c) => c.name.toLowerCase().startsWith(want)).slice(0, 8);
+}