@kinqs/brainrouter-cli 0.3.4

package/dist/cli/commands/memory.js

@@ -0,0 +1,263 @@
+/**
+ * Memory-related slash commands. All cases here are leaf operations against
+ * the MCP memory tools (search, recall, briefing inspection, scenes,
+ * forget, handover, explain, trace, failed, verify, audit, export, import,
+ * persona, skill-hints, diagnostics, working canvas) plus the pipeline
+ * toggle / consolidation operation.
+ *
+ * They mostly delegate to printMcpCall / printMemoryCards and write nothing
+ * back to the workspace except /export (which writes the JSON envelope).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { callMcpTool } from '../../runtime/mcpUtils.js';
+import { extractMemories, renderMemoryCards } from '../../memory/formatters.js';
+import { consolidateMemories } from '../../memory/consolidation.js';
+import { readPreferences, writePreferences } from '../../state/preferencesStore.js';
+import { printMcpCall, printMemoryCards } from './_helpers.js';
+export async function tryHandleMemoryCommand(ctx) {
+    const { command, args, agent, mcpClient } = ctx;
+    switch (command) {
+        case '/memory': {
+            const query = args.join(' ').trim();
+            if (!query) {
+                console.log(chalk.red('\nUsage: /memory <query>\n'));
+                return true;
+            }
+            await printMemoryCards(mcpClient, 'memory_search', { query, sessionKey: agent.sessionKey }, `Memory search · "${query}"`);
+            return true;
+        }
+        case '/recall': {
+            const query = args.join(' ').trim();
+            if (!query) {
+                console.log(chalk.red('\nUsage: /recall <query>\n'));
+                return true;
+            }
+            await printMemoryCards(mcpClient, 'memory_recall', { sessionKey: agent.sessionKey, query }, `Cognitive recall · "${query}"`);
+            return true;
+        }
+        case '/briefing': {
+            const b = agent.getLastBriefing();
+            console.log(chalk.bold('\nLast Memory Briefing'));
+            if (b.sources.length === 0) {
+                console.log(chalk.yellow('  No briefing has been built yet. Start a turn or use /recall.'));
+            }
+            else {
+                console.log(`  Sources queried: ${chalk.cyan(b.sources.join(', '))}`);
+                console.log(`  Recalled record IDs (${b.recordIds.length}): ${chalk.gray(b.recordIds.slice(0, 10).join(', '))}${b.recordIds.length > 10 ? '…' : ''}`);
+            }
+            console.log();
+            return true;
+        }
+        case '/scenes': {
+            const res = await callMcpTool(mcpClient, 'memory_recall', { sessionKey: agent.sessionKey, query: 'list focus scenes' });
+            if (res.isError) {
+                console.log(chalk.red(`\nmemory_recall failed: ${res.text || '(no message)'}\n`));
+            }
+            else {
+                const persona = res.parsed?.appendSystemContext ?? '';
+                const sceneRe = /Recent focus scenes:\s*\n([\s\S]*?)(\n\n|<\/scene-navigation>)/;
+                const m = sceneRe.exec(persona);
+                console.log(chalk.bold('\nActive focus scenes'));
+                if (m) {
+                    for (const line of m[1].split('\n')) {
+                        const trimmed = line.replace(/^\s+/, '').replace(/^-\s*/, '').trim();
+                        if (trimmed)
+                            console.log(`  • ${chalk.cyan(trimmed)}`);
+                    }
+                }
+                else {
+                    console.log(chalk.yellow('  (no scenes returned — recall may be empty)'));
+                }
+                const cards = extractMemories(res.parsed);
+                if (cards.length > 0) {
+                    console.log();
+                    console.log(renderMemoryCards(cards, 'Related memories', 5));
+                }
+            }
+            return true;
+        }
+        case '/forget': {
+            const id = args[0];
+            if (!id) {
+                console.log(chalk.red('\nUsage: /forget <recordId>\n'));
+                return true;
+            }
+            await printMcpCall(mcpClient, 'memory_update', { recordId: id, status: 'archived' }, `Archive memory ${id}`);
+            return true;
+        }
+        case '/handover': {
+            // Generate a compact continuation note from current task memories so
+            // the next session can pick up. Uses memory_handover.
+            await printMcpCall(mcpClient, 'memory_handover', { sessionKey: agent.sessionKey }, 'Session handover note');
+            return true;
+        }
+        case '/explain': {
+            const query = args.join(' ').trim();
+            if (!query) {
+                console.log(chalk.red('\nUsage: /explain <query>\n'));
+                console.log(chalk.gray('  Re-runs recall in explain mode: shows FTS hits, vector hits, RRF scores, type/skill boosts, reranker, graph expansion.\n'));
+                return true;
+            }
+            await printMcpCall(mcpClient, 'memory_explain_recall', { sessionKey: agent.sessionKey, query }, `Recall explanation · "${query}"`);
+            return true;
+        }
+        case '/trace': {
+            const sub = args[0];
+            if (sub === 'save') {
+                const rest = args.slice(1).join(' ').trim();
+                if (!rest) {
+                    console.log(chalk.red('\nUsage: /trace save <description>\n'));
+                    return true;
+                }
+                await printMcpCall(mcpClient, 'memory_debug_trace_save', { content: rest }, 'Saved debug trace');
+                return true;
+            }
+            if (sub === 'search' || !sub) {
+                const query = args.slice(1).join(' ').trim();
+                if (sub !== 'search' && !query) {
+                    console.log(chalk.red('\nUsage: /trace save <description> | /trace search <query>\n'));
+                    return true;
+                }
+                await printMcpCall(mcpClient, 'memory_debug_trace_search', { query: query || '*' }, 'Prior debug traces');
+                return true;
+            }
+            console.log(chalk.red('\nUsage: /trace save <description> | /trace search <query>\n'));
+            return true;
+        }
+        case '/failed': {
+            const area = args.join(' ').trim();
+            await printMcpCall(mcpClient, 'memory_failed_attempts', area ? { area } : {}, `Past failed attempts${area ? ` · "${area}"` : ''}`);
+            return true;
+        }
+        case '/verify': {
+            const id = args[0];
+            if (!id) {
+                console.log(chalk.red('\nUsage: /verify <recordId> [status] [confidence]\n'));
+                return true;
+            }
+            const status = args[1] || 'verified';
+            const confidence = args[2] ? Number(args[2]) : 0.9;
+            await printMcpCall(mcpClient, 'memory_verify', { recordId: id, verificationStatus: status, confidence }, `Verify ${id}`);
+            return true;
+        }
+        case '/audit': {
+            await printMcpCall(mcpClient, 'memory_audit', { limit: 30 }, 'Recent memory audit log');
+            return true;
+        }
+        case '/export': {
+            const out = args[0] || `.brainrouter/cli/memory-export-${Date.now()}.json`;
+            const res = await callMcpTool(mcpClient, 'memory_export', {});
+            if (res.isError) {
+                console.log(chalk.red(`\nmemory_export failed: ${res.text}\n`));
+            }
+            else {
+                try {
+                    fs.writeFileSync(path.resolve(agent.workspaceRoot, out), res.text, 'utf8');
+                    console.log(chalk.green(`\n✓ Exported memory to ${out} (${res.text.length} chars)\n`));
+                }
+                catch (err) {
+                    console.log(chalk.red(`\nWrite failed: ${err.message}\n`));
+                }
+            }
+            return true;
+        }
+        case '/import': {
+            const src = args[0];
+            if (!src) {
+                console.log(chalk.red('\nUsage: /import <path-to-export.json>\n'));
+                return true;
+            }
+            let envelope;
+            try {
+                envelope = fs.readFileSync(path.resolve(agent.workspaceRoot, src), 'utf8');
+            }
+            catch (err) {
+                console.log(chalk.red(`\nRead failed: ${err.message}\n`));
+                return true;
+            }
+            await printMcpCall(mcpClient, 'memory_import', { envelope }, `Import from ${src}`);
+            return true;
+        }
+        case '/persona': {
+            const name = args.join(' ').trim();
+            if (!name) {
+                console.log(chalk.red('\nUsage: /persona <persona-name>\n'));
+                console.log(chalk.gray('  Example: /persona code-reviewer (see /skills for available personas)\n'));
+                return true;
+            }
+            await printMcpCall(mcpClient, 'get_persona', { name }, `Persona · ${name}`);
+            return true;
+        }
+        case '/skill-hints': {
+            const skill = args[0];
+            const hints = args.slice(1).join(' ').trim();
+            if (!skill || !hints) {
+                console.log(chalk.red('\nUsage: /skill-hints <skill-name> <hints>\n'));
+                return true;
+            }
+            await printMcpCall(mcpClient, 'memory_register_skill_hints', { skill, hints }, `Registered hints for ${skill}`);
+            return true;
+        }
+        case '/diagnostics': {
+            await printMcpCall(mcpClient, 'memory_diagnostics', {}, 'Memory diagnostics');
+            return true;
+        }
+        case '/working': {
+            const sub = args[0];
+            if (sub === 'reset') {
+                const confirm = args[1];
+                if (confirm !== 'confirm') {
+                    console.log(chalk.yellow('\n⚠ /working reset clears the working-memory canvas. Confirm with: /working reset confirm\n'));
+                    return true;
+                }
+                await printMcpCall(mcpClient, 'memory_working_reset', { sessionKey: agent.sessionKey, workspacePath: agent.workspaceRoot }, 'Working memory reset');
+                return true;
+            }
+            await printMcpCall(mcpClient, 'memory_working_context', { sessionKey: agent.sessionKey, workspacePath: agent.workspaceRoot }, 'Working memory canvas');
+            return true;
+        }
+        case '/memories': {
+            const sub = args[0];
+            if (!sub || sub === 'status') {
+                const prefs = readPreferences(agent.workspaceRoot);
+                console.log(chalk.bold('\nMemories pipeline'));
+                console.log(`  Enabled: ${prefs.memoriesEnabled ? chalk.green('on') : chalk.gray('off')}`);
+                console.log(chalk.gray('  Subcommands:'));
+                console.log(chalk.gray('    /memories on | off          — toggle the pipeline'));
+                console.log(chalk.gray('    /memories consolidate       — write user/feedback/project/reference files'));
+                console.log(chalk.gray('    /memories status            — show this view\n'));
+                return true;
+            }
+            if (sub === 'on' || sub === 'off') {
+                writePreferences(agent.workspaceRoot, { memoriesEnabled: sub === 'on' });
+                console.log(chalk.green(`\n✓ Memories pipeline ${sub === 'on' ? 'enabled' : 'disabled'}.\n`));
+                return true;
+            }
+            if (sub === 'consolidate') {
+                const spinner = ora(chalk.gray('Consolidating memories from MCP into filesystem artifacts...')).start();
+                try {
+                    const result = await consolidateMemories(mcpClient, agent.workspaceRoot, { sessionKey: agent.sessionKey });
+                    spinner.succeed(chalk.green(`Consolidated ${result.totalRecords} records.`));
+                    console.log(chalk.bold('\nPer-type counts:'));
+                    for (const [t, n] of Object.entries(result.perType)) {
+                        console.log(`  ${chalk.cyan(t.padEnd(10))} ${n}`);
+                    }
+                    console.log(chalk.bold('\nFiles written:'));
+                    for (const f of result.files)
+                        console.log(`  ${chalk.gray(f)}`);
+                    console.log();
+                }
+                catch (err) {
+                    spinner.fail(chalk.red(`Consolidation failed: ${err.message}\n`));
+                }
+                return true;
+            }
+            console.log(chalk.red(`\nUnknown /memories subcommand "${sub}". Try: status, on, off, consolidate.\n`));
+            return true;
+        }
+    }
+    return false;
+}

package/dist/cli/commands/obs.d.ts

@@ -0,0 +1,6 @@
+/**
+ * AUTO-EXTRACTED from cli/repl.ts as part of the slash-command split.
+ * Hand-tune imports if the compiler complains.
+ */
+import type { CommandContext } from './_context.js';
+export declare function tryHandleObsCommand(ctx: CommandContext): Promise<boolean>;

package/dist/cli/commands/obs.js

@@ -0,0 +1,208 @@
+/**
+ * AUTO-EXTRACTED from cli/repl.ts as part of the slash-command split.
+ * Hand-tune imports if the compiler complains.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { exec } from 'node:child_process';
+import chalk from 'chalk';
+import { listSessions } from '../../orchestration/orchestrator.js';
+import { readPreferences } from '../../state/preferencesStore.js';
+import { readTranscriptEntries } from '../../state/sessionStore.js';
+import { getCliStateFile } from '../../state/cliState.js';
+import { formatTranscriptContent } from './_helpers.js';
+export async function tryHandleObsCommand(ctx) {
+    const { command, args, agent, mcpClient, config, rl, repl } = ctx;
+    // 'ctx' alias to keep references to the old ReplContext name working
+    const replCtx = repl;
+    switch (command) {
+        case '/transcript':
+            {
+                const requestedSession = args.join(' ').trim();
+                const sessionKey = !requestedSession || requestedSession === 'main'
+                    ? agent.sessionKey
+                    : requestedSession;
+                const entries = readTranscriptEntries(agent.workspaceRoot, sessionKey, 20);
+                console.log(chalk.bold(`\nTranscript: ${sessionKey}`));
+                if (entries.length === 0) {
+                    console.log(chalk.yellow('  No transcript entries found.'));
+                }
+                else {
+                    for (const entry of entries) {
+                        const label = entry.name ? `${entry.role}:${entry.name}` : entry.role;
+                        const text = formatTranscriptContent(entry.content ?? entry.tool_calls ?? '');
+                        console.log(`${chalk.gray(entry.timestamp)} ${chalk.cyan(label)} ${chalk.gray(text)}`);
+                    }
+                }
+                console.log();
+                return true;
+            }
+        case '/watch':
+            {
+                const tracePath = process.env.BRAINROUTER_TRACE_LOG?.trim();
+                if (!tracePath) {
+                    console.log(chalk.yellow('\nLive tracing is off. Enable with:'));
+                    console.log(chalk.gray('  export BRAINROUTER_TRACE_LOG=' + path.join(agent.workspaceRoot, '.brainrouter/cli/trace.jsonl')));
+                    console.log(chalk.gray('  (restart the CLI so the change takes effect)\n'));
+                    console.log(chalk.gray('Without it, you can still see per-tool activity inline in this REPL,'));
+                    console.log(chalk.gray('and child-agent tool calls now surface as "role:id → tool" lines.'));
+                    console.log(chalk.gray('Use /agents and /agent <id> --full for the persisted child transcripts.\n'));
+                    return true;
+                }
+                if (!fs.existsSync(tracePath)) {
+                    console.log(chalk.yellow(`\nTrace file does not exist yet: ${tracePath}\nIt will appear after the first turn.\n`));
+                    return true;
+                }
+                console.log(chalk.bold(`\n📡 Tailing ${tracePath} — Ctrl+C to stop.\n`));
+                // Stream the last 30 lines + new appends as JSONL until the user
+                // interrupts with Ctrl+C. We use child_process tail because that's
+                // dramatically simpler than re-implementing inotify in Node.
+                const tail = exec(`tail -n 30 -f "${tracePath}"`);
+                const lineHandler = (chunk) => {
+                    const text = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+                    for (const raw of text.split('\n')) {
+                        if (!raw.trim())
+                            continue;
+                        try {
+                            const e = JSON.parse(raw);
+                            const attrs = e.attributes ?? {};
+                            const dur = typeof e.duration_ms === 'number' ? chalk.gray(` ${e.duration_ms}ms`) : '';
+                            const detail = Object.entries(attrs)
+                                .slice(0, 4)
+                                .map(([k, v]) => `${k}=${String(v).slice(0, 40)}`)
+                                .join(' ');
+                            console.log(`${chalk.gray(e.ts?.slice(11, 19) ?? '')} ${chalk.cyan(e.name)}${dur} ${chalk.gray(detail)}`);
+                        }
+                        catch { /* not JSON — print raw */
+                            console.log(chalk.gray(raw));
+                        }
+                    }
+                };
+                tail.stdout?.on('data', lineHandler);
+                tail.stderr?.on('data', (c) => process.stderr.write(c));
+                const onInterrupt = () => {
+                    try {
+                        tail.kill('SIGTERM');
+                    }
+                    catch { /* noop */ }
+                    console.log(chalk.gray('\nwatch ended.\n'));
+                    rl.off('SIGINT', onInterrupt);
+                    rl.prompt();
+                };
+                rl.once('SIGINT', onInterrupt);
+                // Resume the prompt only after the user interrupts; otherwise the
+                // tail stays attached.
+                return true;
+            }
+        case '/tokens':
+            {
+                const session = agent.sessionUsage;
+                const metrics = agent.memoryMetrics;
+                const children = listSessions(agent.workspaceRoot).filter((s) => s.usage);
+                const childPrompt = children.reduce((acc, c) => acc + (c.usage?.promptTokens ?? 0), 0);
+                const childCompletion = children.reduce((acc, c) => acc + (c.usage?.completionTokens ?? 0), 0);
+                const childCalls = children.reduce((acc, c) => acc + (c.usage?.calls ?? 0), 0);
+                // Memory savings estimate:
+                // - Each recalled record (avg ~200 chars ≈ 50 tokens) supplies cross-
+                //   session context that would otherwise require either a manual
+                //   user explanation, a re-read of files, or skill re-discovery.
+                //   Conservative multiplier of 5× to account for the "without memory
+                //   you would have read 3-5 files" replacement cost.
+                // - Offloaded child output bytes are subtracted from what the parent
+                //   would otherwise have had to carry in context.
+                const recallSavings = metrics.briefingTokensInjected * 5;
+                const offloadSavings = Math.round(metrics.offloadCharsAvoided / 4);
+                const totalSaved = recallSavings + offloadSavings;
+                const totalSpent = session.promptTokens + session.completionTokens + childPrompt + childCompletion;
+                console.log(chalk.bold('\nToken usage — this session'));
+                console.log(`  Parent: ${chalk.cyan(session.promptTokens.toLocaleString())}↑  ${chalk.cyan(session.completionTokens.toLocaleString())}↓  ${chalk.gray(`(${session.turns} turn${session.turns === 1 ? '' : 's'}, ${session.calls} LLM call${session.calls === 1 ? '' : 's'})`)}`);
+                if (children.length > 0) {
+                    console.log(`  Children (${children.length}): ${chalk.cyan(childPrompt.toLocaleString())}↑  ${chalk.cyan(childCompletion.toLocaleString())}↓  ${chalk.gray(`(${childCalls} LLM call${childCalls === 1 ? '' : 's'})`)}`);
+                    for (const c of children.slice(0, 5)) {
+                        const u = c.usage;
+                        console.log(chalk.gray(`    · ${c.id} (${c.role}): ${u.promptTokens.toLocaleString()}↑ ${u.completionTokens.toLocaleString()}↓`));
+                    }
+                    if (children.length > 5)
+                        console.log(chalk.gray(`    …and ${children.length - 5} more (see /agents)`));
+                }
+                console.log(`  Total this session: ${chalk.bold.cyan(totalSpent.toLocaleString())} tokens`);
+                console.log(chalk.bold('\nMemory savings (estimated)'));
+                console.log(`  Briefing tokens injected:  ${chalk.gray(metrics.briefingTokensInjected.toLocaleString())}  (${metrics.recallRecordsConsulted} records consulted)`);
+                console.log(`  Cross-session recall value: ~${chalk.green(recallSavings.toLocaleString())} tokens you'd otherwise spend re-reading files / re-explaining context`);
+                console.log(`  Offload bytes avoided:     ${chalk.gray(metrics.offloadCharsAvoided.toLocaleString())} chars (large child outputs that stayed out of parent context)`);
+                console.log(`  → Offload value:           ~${chalk.green(offloadSavings.toLocaleString())} tokens`);
+                console.log(`  ${chalk.bold('Total estimated savings:')}  ${chalk.bold.green('~' + totalSaved.toLocaleString())} tokens`);
+                if (totalSpent > 0) {
+                    const ratio = totalSaved / totalSpent;
+                    console.log(chalk.gray(`  Ratio: for every 1 token spent, memory saved ~${ratio.toFixed(2)} tokens of context.`));
+                }
+                console.log(chalk.gray('\n  (Estimates use a 5× multiplier on briefing tokens — a heuristic for "you would have needed to re-derive this from files/prompts otherwise". Treat as directional, not exact.)\n'));
+                return true;
+            }
+        case '/feedback':
+            {
+                // Personal CLI state lives under the user-global brainrouter home (per
+                // README's storage contract), NOT inside the workspace — writing
+                // feedback.jsonl into the project tree risks accidental commits and
+                // breaks the "workflows are the only thing written inside the project"
+                // guarantee. Route through getCliStateFile() so the path becomes
+                // ~/.brainrouter/workspaces/<encoded>/cli/feedback.jsonl.
+                const msg = args.join(' ').trim();
+                const file = getCliStateFile(agent.workspaceRoot, 'feedback.jsonl');
+                const entry = {
+                    ts: new Date().toISOString(),
+                    sessionKey: agent.sessionKey,
+                    model: agent.getModel(),
+                    accessMode: agent.getAccessMode(),
+                    message: msg || '(no message provided)',
+                };
+                fs.appendFileSync(file, JSON.stringify(entry) + '\n', 'utf8');
+                console.log(chalk.green(`\n✓ Feedback recorded at ${file}`));
+                console.log(chalk.gray('  This stays in your user-global brainrouter home — share by copying the file into a GitHub issue.\n'));
+                return true;
+            }
+        case '/rollout':
+            {
+                const { getSessionStateDir } = await import('../../state/cliState.js');
+                const sessionDir = getSessionStateDir(agent.workspaceRoot, agent.sessionKey);
+                console.log(chalk.bold('\nSession bucket'));
+                console.log(`  Session:   ${chalk.cyan(agent.sessionKey)}`);
+                console.log(`  Directory: ${chalk.blue(sessionDir)}`);
+                const interestingFiles = ['transcript.jsonl', 'goal.json', 'tasks.json'];
+                console.log(chalk.bold('\nFiles in bucket:'));
+                let printedAny = false;
+                for (const name of interestingFiles) {
+                    const full = path.join(sessionDir, name);
+                    if (fs.existsSync(full)) {
+                        const stat = fs.statSync(full);
+                        console.log(`  ${chalk.cyan(name.padEnd(18))} ${chalk.gray(`${stat.size} bytes · modified ${stat.mtime.toISOString()}`)}`);
+                        printedAny = true;
+                    }
+                }
+                if (!printedAny)
+                    console.log(chalk.gray('  (empty — files appear after you set a goal, update a plan, or run a turn)'));
+                console.log();
+                return true;
+            }
+        case '/debug-config':
+            {
+                console.log(chalk.bold('\nConfig layers (in order of precedence)'));
+                console.log(`  Workspace: ${chalk.cyan(agent.workspaceRoot)}`);
+                console.log(`  CLI state: ${chalk.cyan(path.join(agent.workspaceRoot, '.brainrouter/cli'))}`);
+                console.log(`  Profile:   ${chalk.cyan(config.activeServer)}`);
+                console.log(`  Server:    ${chalk.cyan(JSON.stringify(config.servers[config.activeServer], null, 2).split('\n').map((l) => '             ' + l).join('\n').trim())}`);
+                console.log(chalk.bold('\nEnvironment'));
+                const flags = ['BRAINROUTER_SANDBOX', 'BRAINROUTER_SANDBOX_READ_PATHS', 'BRAINROUTER_SANDBOX_WRITE_PATHS', 'BRAINROUTER_SANDBOX_NETWORK', 'BRAINROUTER_TRACE_LOG', 'BRAINROUTER_MAX_TOOL_LOOPS', 'BRAINROUTER_LLM_TIMEOUT_MS', 'BRAINROUTER_WORKSPACE'];
+                for (const f of flags) {
+                    const v = process.env[f];
+                    if (v)
+                        console.log(`  ${chalk.cyan(f)} = ${v}`);
+                }
+                console.log(chalk.bold('\nPreferences'));
+                console.log(chalk.gray(JSON.stringify(readPreferences(agent.workspaceRoot), null, 2)));
+                console.log();
+                return true;
+            }
+    }
+    return false;
+}

package/dist/cli/commands/orchestration.d.ts

@@ -0,0 +1,6 @@
+/**
+ * AUTO-EXTRACTED from cli/repl.ts as part of the slash-command split.
+ * Hand-tune imports if the compiler complains.
+ */
+import type { CommandContext } from './_context.js';
+export declare function tryHandleOrchestrationCommand(ctx: CommandContext): Promise<boolean>;