framein 0.0.4 → 0.0.5

package/dist/shell.js

@@ -1,127 +1,127 @@
-// Optional interactive `framein` lobby (ADR-0010, layer 4). A zero-dep readline *switchboard*: run framein
-// verbs inline, switch the lead agent, and hand the terminal to a lead's NATIVE TUI via stdio:'inherit'
-// (framein pauses while the lead drives, resumes on exit). Simultaneous overlay of framein + a live TUI
-// would require node-pty (a native dep) — deferred/optional, never bundled (ADR-0010). This module is the
-// PURE line router (fully unit-tested); the I/O loop (readline + spawn) is the thin wrapper in cli.ts.
-import { AGENTS } from './types.js';
-import { isAgent } from './roles.js';
-/** Split a lobby line into tokens, honoring "double" and 'single' quotes (quotes stripped) so multi-word
- *  values like `start "add Google login"` survive as one token instead of leaking literal quotes. */
-export function tokenizeLine(line) {
-    const tokens = [];
-    const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
-    let m;
-    while ((m = re.exec(line)) !== null)
-        tokens.push(m[1] ?? m[2] ?? m[3]);
-    return tokens;
-}
-/** Map one input line to an action. Pure: no I/O, no agent launch — the loop performs the effect. */
-export function routeShellLine(line, state) {
-    const trimmed = line.trim();
-    if (!trimmed)
-        return { kind: 'noop' };
-    const tokens = tokenizeLine(trimmed);
-    const head = tokens[0].toLowerCase();
-    const rest = tokens.slice(1);
-    if (head === 'exit' || head === 'quit' || head === '/exit' || head === '/quit')
-        return { kind: 'exit' };
-    if (head === 'help' || head === '/help' || head === '?')
-        return { kind: 'help' };
-    if (head === '/lead') {
-        if (rest.length === 0)
-            return { kind: 'pickLead' }; // bare /lead → interactive picker (TTY); printed fallback otherwise
-        const agent = rest[0].toLowerCase();
-        if (!isAgent(agent))
-            return { kind: 'error', message: `Unknown agent '${rest[0]}'. Valid: ${AGENTS.join(', ')}` };
-        return { kind: 'setLead', agent };
-    }
-    if (head === '/go') {
-        const prompt = rest.join(' ').trim();
-        return { kind: 'launchLead', agent: state.lead, prompt: prompt || undefined };
-    }
-    if (head === '/trust')
-        return { kind: 'toggleTrust' }; // arm/disarm permission-bypass for the next /go (time-boxed)
-    // A bare agent name (optionally with a prompt) switches to + launches that agent's native TUI.
-    if (isAgent(head)) {
-        const prompt = rest.join(' ').trim();
-        return { kind: 'launchLead', agent: head, prompt: prompt || undefined };
-    }
-    // Otherwise it's a framein command — `/verify` and `verify` both reach the engine.
-    const verb = head.startsWith('/') ? head.slice(1) : head;
-    if (verb === 'lobby' || verb === 'shell')
-        return { kind: 'error', message: 'Already in the lobby.' };
-    return { kind: 'engine', args: [verb, ...rest] };
-}
-/** Rows for the context card shown right before handing the terminal to a lead's native TUI (`/go`).
- *  Pure: the loop reads these from the store and renders them, so the user carries intent INTO the
- *  native UI. We surface state here; we never screen-scrape the TUI itself (ADR-0009). */
-export function handoffCardRows(info) {
-    const rows = [['lead', info.lead]];
-    if (info.reviewer)
-        rows.push(['reviewer', info.reviewer]);
-    rows.push(['task', info.goal && info.goal.trim() ? info.goal : 'no active contract']);
-    if (info.lastGreen)
-        rows.push(['last green', info.lastGreen]);
-    if (info.blocker)
-        rows.push(['blocker', info.blocker]);
-    return rows;
-}
-export function renderShellHelp() {
-    return [
-        'framein lobby — your switchboard for AI coding. The leading / is optional. Every verb is',
-        'deterministic and LOCAL: you don’t need an agent to run one (the agent just decides when to).',
-        '',
-        '  Lobby-only — choose who drives & hand off (these live in the lobby, not inside agents):',
-        '    /lead                switch the lead agent (↑↓ · type to filter · enter)',
-        '    /go [task]           hand the terminal to the lead — work there, exit (Ctrl-D) to return',
-        '    /trust               arm/disarm permission-bypass for /go (off by default · 30m)',
-        '    /exit                leave the lobby (or Ctrl-D on an empty line)',
-        `    ${AGENTS.join(' · ')}   shortcut: jump straight into that agent (e.g. \`codex fix the bug\`)`,
-        '',
-        '  framein verbs — run here, inside your agent (/fr:verify · $fr-verify), or as `framein <verb>`:',
-        '    start <goal>         define what “done” means — the Task Contract',
-        '    verify               run build/test, check validation against the contract',
-        '    ship                 deployment-readiness gate (blocks if not ready)',
-        '    risk                 blast-radius of the current change',
-        '    rescue               stuck in a fix-loop? show the loop + safe options',
-        '    challenge · decide   have another model argue a proposal, then you rule',
-        '    task · capsule       show/amend the contract · carry state across a model switch',
-        '    status               project · contract · state',
-        '',
-        '  Also in the lobby / terminal (not wrapped into agents): init · stats · explain',
-        '',
-        'Tip: type / to browse (filters as you type · ↑↓ to pick · ⏎ runs) · full list: framein --help · manual: docs/MANUAL.md',
-    ].join('\n');
-}
-/** Verbs offered by lobby Tab-completion (a friendly subset of the full CLI surface). */
-export const LOBBY_VERBS = ['init', 'start', 'verify', 'ship', 'rescue', 'status', 'stats', 'explain', 'risk', 'task', 'checkpoint', 'capsule'];
-const LOBBY_COMMANDS = [...LOBBY_VERBS, ...LOBBY_VERBS.map((v) => `/${v}`), '/lead', '/go', '/trust', '/help', 'exit', 'quit'];
-/** readline completer for the lobby line editor (pure). Completes agent names after `/lead `, otherwise
- *  the first token against the verb / slash-command list. Returns [matches, fragmentBeingCompleted]. */
-export function lobbyCompleter(line) {
-    const lead = line.match(/^\/lead\s+(\S*)$/i);
-    if (lead) {
-        const frag = lead[1];
-        const hits = AGENTS.filter((a) => a.startsWith(frag.toLowerCase()));
-        return [hits.length ? hits : AGENTS.slice(), frag];
-    }
-    const hits = LOBBY_COMMANDS.filter((c) => c.startsWith(line));
-    return [hits, line];
-}
-/** Commands shown in the lobby's live `/` palette (the inline menu opened by typing `/`). All slash-
- *  prefixed for consistency; the leading `/` is what surfaces the menu. Curated to what's actually
- *  useful FROM the lobby — the deterministic checks ("local, no agent" → they run without an LLM) plus
- *  the switchboard verbs. The real coding happens after /go, inside the lead's own UI. (palette.ts) */
-export const LOBBY_PALETTE = [
-    { cmd: '/go', desc: 'hand the terminal to the lead agent — where the coding happens' },
-    { cmd: '/lead', desc: 'switch the lead agent (claude · codex · gemini)' },
-    { cmd: '/trust', desc: 'arm/disarm permission-bypass for /go (time-boxed)' },
-    { cmd: '/status', desc: 'project · contract · state (local, no agent)' },
-    { cmd: '/verify', desc: 'run build/test, check validation vs the contract (local, no agent)' },
-    { cmd: '/ship', desc: 'deployment-readiness check (local, no agent)' },
-    { cmd: '/risk', desc: 'blast-radius of the current changes (local, no agent)' },
-    { cmd: '/rescue', desc: 'stuck? detect the loop + get options (local, no agent)' },
-    { cmd: '/init', desc: 'set up framein in this folder' },
-    { cmd: '/help', desc: 'all commands' },
-    { cmd: '/exit', desc: 'leave the lobby' },
-];
+// Optional interactive `framein` lobby (ADR-0010, layer 4). A zero-dep readline *switchboard*: run framein
+// verbs inline, switch the lead agent, and hand the terminal to a lead's NATIVE TUI via stdio:'inherit'
+// (framein pauses while the lead drives, resumes on exit). Simultaneous overlay of framein + a live TUI
+// would require node-pty (a native dep) — deferred/optional, never bundled (ADR-0010). This module is the
+// PURE line router (fully unit-tested); the I/O loop (readline + spawn) is the thin wrapper in cli.ts.
+import { AGENTS } from './types.js';
+import { isAgent } from './roles.js';
+/** Split a lobby line into tokens, honoring "double" and 'single' quotes (quotes stripped) so multi-word
+ *  values like `start "add Google login"` survive as one token instead of leaking literal quotes. */
+export function tokenizeLine(line) {
+    const tokens = [];
+    const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+    let m;
+    while ((m = re.exec(line)) !== null)
+        tokens.push(m[1] ?? m[2] ?? m[3]);
+    return tokens;
+}
+/** Map one input line to an action. Pure: no I/O, no agent launch — the loop performs the effect. */
+export function routeShellLine(line, state) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return { kind: 'noop' };
+    const tokens = tokenizeLine(trimmed);
+    const head = tokens[0].toLowerCase();
+    const rest = tokens.slice(1);
+    if (head === 'exit' || head === 'quit' || head === '/exit' || head === '/quit')
+        return { kind: 'exit' };
+    if (head === 'help' || head === '/help' || head === '?')
+        return { kind: 'help' };
+    if (head === '/lead') {
+        if (rest.length === 0)
+            return { kind: 'pickLead' }; // bare /lead → interactive picker (TTY); printed fallback otherwise
+        const agent = rest[0].toLowerCase();
+        if (!isAgent(agent))
+            return { kind: 'error', message: `Unknown agent '${rest[0]}'. Valid: ${AGENTS.join(', ')}` };
+        return { kind: 'setLead', agent };
+    }
+    if (head === '/go') {
+        const prompt = rest.join(' ').trim();
+        return { kind: 'launchLead', agent: state.lead, prompt: prompt || undefined };
+    }
+    if (head === '/trust')
+        return { kind: 'toggleTrust' }; // arm/disarm permission-bypass for the next /go (time-boxed)
+    // A bare agent name (optionally with a prompt) switches to + launches that agent's native TUI.
+    if (isAgent(head)) {
+        const prompt = rest.join(' ').trim();
+        return { kind: 'launchLead', agent: head, prompt: prompt || undefined };
+    }
+    // Otherwise it's a framein command — `/verify` and `verify` both reach the engine.
+    const verb = head.startsWith('/') ? head.slice(1) : head;
+    if (verb === 'lobby' || verb === 'shell')
+        return { kind: 'error', message: 'Already in the lobby.' };
+    return { kind: 'engine', args: [verb, ...rest] };
+}
+/** Rows for the context card shown right before handing the terminal to a lead's native TUI (`/go`).
+ *  Pure: the loop reads these from the store and renders them, so the user carries intent INTO the
+ *  native UI. We surface state here; we never screen-scrape the TUI itself (ADR-0009). */
+export function handoffCardRows(info) {
+    const rows = [['lead', info.lead]];
+    if (info.reviewer)
+        rows.push(['reviewer', info.reviewer]);
+    rows.push(['task', info.goal && info.goal.trim() ? info.goal : 'no active contract']);
+    if (info.lastGreen)
+        rows.push(['last green', info.lastGreen]);
+    if (info.blocker)
+        rows.push(['blocker', info.blocker]);
+    return rows;
+}
+export function renderShellHelp() {
+    return [
+        'framein lobby — your switchboard for AI coding. The leading / is optional. Every verb is',
+        'deterministic and LOCAL: you don’t need an agent to run one (the agent just decides when to).',
+        '',
+        '  Lobby-only — choose who drives & hand off (these live in the lobby, not inside agents):',
+        '    /lead                switch the lead agent (↑↓ · type to filter · enter)',
+        '    /go [task]           hand the terminal to the lead — work there, exit (Ctrl-D) to return',
+        '    /trust               arm/disarm permission-bypass for /go (off by default · 30m)',
+        '    /exit                leave the lobby (or Ctrl-D on an empty line)',
+        `    ${AGENTS.join(' · ')}   shortcut: jump straight into that agent (e.g. \`codex fix the bug\`)`,
+        '',
+        '  framein verbs — run here, inside your agent (/fr:verify · $fr-verify), or as `framein <verb>`:',
+        '    start <goal>         define what “done” means — the Task Contract',
+        '    verify               run build/test, check validation against the contract',
+        '    ship                 deployment-readiness gate (blocks if not ready)',
+        '    risk                 blast-radius of the current change',
+        '    rescue               stuck in a fix-loop? show the loop + safe options',
+        '    challenge · decide   have another model argue a proposal, then you rule',
+        '    task · capsule       show/amend the contract · carry state across a model switch',
+        '    status               project · contract · state',
+        '',
+        '  Also in the lobby / terminal (not wrapped into agents): init · stats · explain',
+        '',
+        'Tip: type / to browse (filters as you type · ↑↓ to pick · ⏎ runs) · full list: framein --help · manual: docs/MANUAL.md',
+    ].join('\n');
+}
+/** Verbs offered by lobby Tab-completion (a friendly subset of the full CLI surface). */
+export const LOBBY_VERBS = ['init', 'start', 'verify', 'ship', 'rescue', 'status', 'stats', 'explain', 'risk', 'task', 'checkpoint', 'capsule'];
+const LOBBY_COMMANDS = [...LOBBY_VERBS, ...LOBBY_VERBS.map((v) => `/${v}`), '/lead', '/go', '/trust', '/help', 'exit', 'quit'];
+/** readline completer for the lobby line editor (pure). Completes agent names after `/lead `, otherwise
+ *  the first token against the verb / slash-command list. Returns [matches, fragmentBeingCompleted]. */
+export function lobbyCompleter(line) {
+    const lead = line.match(/^\/lead\s+(\S*)$/i);
+    if (lead) {
+        const frag = lead[1];
+        const hits = AGENTS.filter((a) => a.startsWith(frag.toLowerCase()));
+        return [hits.length ? hits : AGENTS.slice(), frag];
+    }
+    const hits = LOBBY_COMMANDS.filter((c) => c.startsWith(line));
+    return [hits, line];
+}
+/** Commands shown in the lobby's live `/` palette (the inline menu opened by typing `/`). All slash-
+ *  prefixed for consistency; the leading `/` is what surfaces the menu. Curated to what's actually
+ *  useful FROM the lobby — the deterministic checks ("local, no agent" → they run without an LLM) plus
+ *  the switchboard verbs. The real coding happens after /go, inside the lead's own UI. (palette.ts) */
+export const LOBBY_PALETTE = [
+    { cmd: '/go', desc: 'hand the terminal to the lead agent — where the coding happens' },
+    { cmd: '/lead', desc: 'switch the lead agent (claude · codex · gemini)' },
+    { cmd: '/trust', desc: 'arm/disarm permission-bypass for /go (time-boxed)' },
+    { cmd: '/status', desc: 'project · contract · state (local, no agent)' },
+    { cmd: '/verify', desc: 'run build/test, check validation vs the contract (local, no agent)' },
+    { cmd: '/ship', desc: 'deployment-readiness check (local, no agent)' },
+    { cmd: '/risk', desc: 'blast-radius of the current changes (local, no agent)' },
+    { cmd: '/rescue', desc: 'stuck? detect the loop + get options (local, no agent)' },
+    { cmd: '/init', desc: 'set up framein in this folder' },
+    { cmd: '/help', desc: 'all commands' },
+    { cmd: '/exit', desc: 'leave the lobby' },
+];

package/dist/stats.js

@@ -1,74 +1,74 @@
-// Repo-local Routing (F-LOOP-7, ADR-0008): route by THIS repo's actual results, not generic model
-// reputation, and — crucially — EXPLAIN the choice rather than auto-deciding silently (trust comes
-// from "why", not magic). Pure: derive per-agent stats from the ledger, then score + explain via
-// roles.scoreAgent. Accumulating richer signals (first-try pass rate, human reverts) comes later.
-import { AGENTS } from './types.js';
-import { scoreAgent, DEFAULT_ROLE_PRIORITY } from './roles.js';
-import { PLAIN } from './ui/theme.js';
-const isAgentName = (s) => AGENTS.includes(s);
-/** The trailing token of a ledger target is the agent: "reviewer:codex" -> codex, "codex" -> codex. */
-function agentOf(target) {
-    const tail = target.split(':').pop() ?? '';
-    return isAgentName(tail) ? tail : undefined;
-}
-export function computeRepoStats(ledger) {
-    const stats = {};
-    const ensure = (a) => (stats[a] ??= { delegations: 0, failures: 0, quotaHits: 0 });
-    for (const e of ledger) {
-        const a = agentOf(e.target);
-        if (!a)
-            continue;
-        if (e.kind === 'delegated')
-            ensure(a).delegations++;
-        else if (e.kind === 'delegate-fail') {
-            const s = ensure(a);
-            s.delegations++;
-            s.failures++;
-        }
-        else if (e.kind === 'quota')
-            ensure(a).quotaHits++;
-    }
-    return stats;
-}
-function routeReasons(st) {
-    if (!st || st.delegations === 0)
-        return ['no local track record yet (using role defaults)'];
-    const success = st.delegations - st.failures;
-    const reasons = [`+ ${Math.round((success / st.delegations) * 100)}% delegation success in this repo (${success}/${st.delegations})`];
-    if (st.failures)
-        reasons.push(`- ${st.failures} failure${st.failures > 1 ? 's' : ''}`);
-    reasons.push(st.quotaHits ? `- ${st.quotaHits} quota hit${st.quotaHits > 1 ? 's' : ''}` : '+ no quota issues');
-    return reasons;
-}
-export function explainRoute(role, ctx, stats) {
-    const priority = (ctx.rolePriority ?? DEFAULT_ROLE_PRIORITY)[role] ?? [...AGENTS];
-    const scored = priority
-        .map((agent) => ({ agent, score: scoreAgent(agent, { ...ctx, role, repoStats: stats }) }))
-        .filter((s) => Number.isFinite(s.score))
-        .sort((a, b) => b.score - a.score);
-    const best = scored[0];
-    const second = scored[1];
-    let alternative;
-    if (best && second) {
-        const total = best.score + second.score;
-        alternative = { agent: second.agent, confidence: total > 0 ? Number((second.score / total).toFixed(2)) : 0 };
-    }
-    return { role, agent: best?.agent ?? null, reasons: best ? routeReasons(stats[best.agent]) : ['no eligible agent'], alternative };
-}
-export function renderRouteExplain(e, ui = PLAIN) {
-    const lines = [e.agent ? `Selected ${ui.tone(e.agent, 'brand')} as ${e.role}.` : `No eligible agent for ${e.role}.`, ui.tone('Why:', 'muted')];
-    for (const r of e.reasons)
-        lines.push(`  ${r}`);
-    if (e.alternative)
-        lines.push(ui.tone(`Alternative: ${e.alternative.agent}, confidence ${e.alternative.confidence}`, 'muted'));
-    return lines.join('\n');
-}
-export function renderStats(stats, ui = PLAIN) {
-    const entries = Object.entries(stats);
-    if (entries.length === 0)
-        return 'No repo-local stats yet. Delegations (`framein ask --run`) accumulate them.';
-    const lines = [ui.tone('Repo-local agent stats (from the ledger):', 'muted')];
-    for (const [a, st] of entries)
-        lines.push(`  ${ui.tone(a, 'brand')}: ${st.delegations} delegations, ${st.failures} failed, ${st.quotaHits} quota`);
-    return lines.join('\n');
-}
+// Repo-local Routing (F-LOOP-7, ADR-0008): route by THIS repo's actual results, not generic model
+// reputation, and — crucially — EXPLAIN the choice rather than auto-deciding silently (trust comes
+// from "why", not magic). Pure: derive per-agent stats from the ledger, then score + explain via
+// roles.scoreAgent. Accumulating richer signals (first-try pass rate, human reverts) comes later.
+import { AGENTS } from './types.js';
+import { scoreAgent, DEFAULT_ROLE_PRIORITY } from './roles.js';
+import { PLAIN } from './ui/theme.js';
+const isAgentName = (s) => AGENTS.includes(s);
+/** The trailing token of a ledger target is the agent: "reviewer:codex" -> codex, "codex" -> codex. */
+function agentOf(target) {
+    const tail = target.split(':').pop() ?? '';
+    return isAgentName(tail) ? tail : undefined;
+}
+export function computeRepoStats(ledger) {
+    const stats = {};
+    const ensure = (a) => (stats[a] ??= { delegations: 0, failures: 0, quotaHits: 0 });
+    for (const e of ledger) {
+        const a = agentOf(e.target);
+        if (!a)
+            continue;
+        if (e.kind === 'delegated')
+            ensure(a).delegations++;
+        else if (e.kind === 'delegate-fail') {
+            const s = ensure(a);
+            s.delegations++;
+            s.failures++;
+        }
+        else if (e.kind === 'quota')
+            ensure(a).quotaHits++;
+    }
+    return stats;
+}
+function routeReasons(st) {
+    if (!st || st.delegations === 0)
+        return ['no local track record yet (using role defaults)'];
+    const success = st.delegations - st.failures;
+    const reasons = [`+ ${Math.round((success / st.delegations) * 100)}% delegation success in this repo (${success}/${st.delegations})`];
+    if (st.failures)
+        reasons.push(`- ${st.failures} failure${st.failures > 1 ? 's' : ''}`);
+    reasons.push(st.quotaHits ? `- ${st.quotaHits} quota hit${st.quotaHits > 1 ? 's' : ''}` : '+ no quota issues');
+    return reasons;
+}
+export function explainRoute(role, ctx, stats) {
+    const priority = (ctx.rolePriority ?? DEFAULT_ROLE_PRIORITY)[role] ?? [...AGENTS];
+    const scored = priority
+        .map((agent) => ({ agent, score: scoreAgent(agent, { ...ctx, role, repoStats: stats }) }))
+        .filter((s) => Number.isFinite(s.score))
+        .sort((a, b) => b.score - a.score);
+    const best = scored[0];
+    const second = scored[1];
+    let alternative;
+    if (best && second) {
+        const total = best.score + second.score;
+        alternative = { agent: second.agent, confidence: total > 0 ? Number((second.score / total).toFixed(2)) : 0 };
+    }
+    return { role, agent: best?.agent ?? null, reasons: best ? routeReasons(stats[best.agent]) : ['no eligible agent'], alternative };
+}
+export function renderRouteExplain(e, ui = PLAIN) {
+    const lines = [e.agent ? `Selected ${ui.tone(e.agent, 'brand')} as ${e.role}.` : `No eligible agent for ${e.role}.`, ui.tone('Why:', 'muted')];
+    for (const r of e.reasons)
+        lines.push(`  ${r}`);
+    if (e.alternative)
+        lines.push(ui.tone(`Alternative: ${e.alternative.agent}, confidence ${e.alternative.confidence}`, 'muted'));
+    return lines.join('\n');
+}
+export function renderStats(stats, ui = PLAIN) {
+    const entries = Object.entries(stats);
+    if (entries.length === 0)
+        return 'No repo-local stats yet. Delegations (`framein ask --run`) accumulate them.';
+    const lines = [ui.tone('Repo-local agent stats (from the ledger):', 'muted')];
+    for (const [a, st] of entries)
+        lines.push(`  ${ui.tone(a, 'brand')}: ${st.delegations} delegations, ${st.failures} failed, ${st.quotaHits} quota`);
+    return lines.join('\n');
+}