@nemus-cli/nemus 0.2.13 → 0.3.1

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- **`reflect` now shows live progress and no longer looks hung.** The judge call
+  ran synchronously (`execFileSync`), which blocked the event loop, and a
+  10-workspace run could hit the 180s cap and die with a raw
+  `spawnSync pi ETIMEDOUT`. Now: (1) the gather phase prints a **per-workspace
+  line** as each session is read (`✓ 1/3 my-workspace  635 turns · 12 prompts ·
+  13 failures`); (2) the judge runs **async** behind a live spinner with elapsed
+  seconds; (3) the timeout is raised to 300s, overridable via
+  `NEMUS_JUDGE_TIMEOUT_MS`, and a timeout now yields an **actionable** message
+  ("try a smaller --limit, a faster agent, or raise the cap"); (4) the judge
+  prompt is leaner (fewer prompts/errors per session) so a local model actually
+  finishes.
+
+## [0.3.0] - 2026-08-27
+
+### Added
+
+- **`nemus reflect` (alias `retro`) — LLM-as-a-judge retrospective.** Analyzes
+  your most recent workspaces (default 10) by reading their agent session
+  transcripts, distilling the human prompts + tool failures + tools used, and
+  asking your own configured agent (claude/pi/opencode — no API key of ours) to
+  recommend concrete setup improvements: which **skills** to add and where,
+  missing **AGENTS.md/context** rules, missing **connectivity/smoke tests**, and
+  **prompt/workflow** habits to change — each with a priority and a concrete
+  example snippet. Reads both Claude and pi transcript formats. Flags:
+  `--limit <n>`, `--json` (structured report, same `{ok:false,error}` failure
+  contract as the other JSON commands), and `--dry-run` (print the assembled
+  corpus + judge prompt without calling the agent). Idea courtesy of
+  **@lightpriest** — thank you for the great suggestion!
+
 ## [0.2.13] - 2026-08-27
 
 ### Added

package/README.md

@@ -280,6 +280,23 @@ nemus snapshot save ws        # (ss) capture exact branches/commits/dirty state
 nemus snapshot restore <id>   # (sr)
 ```
 
+### Reflect — improve your setup over time
+
+```bash
+nemus reflect                 # (retro) analyze your last 10 workspaces' sessions
+nemus reflect --limit 5       # narrow the window
+nemus reflect --json          # structured report for tooling
+nemus reflect --dry-run       # show what the judge sees, without calling the agent
+```
+
+`reflect` reads your recent agent **session transcripts** (Claude + pi), distills
+the prompts you sent, the failures the agent hit, and the tools it used, then asks
+**your own configured agent** (LLM-as-a-judge — no extra API key) to recommend
+concrete improvements: which **skills** to add and where, missing
+**AGENTS.md/context** rules, missing **connectivity/smoke tests**, and
+**prompt/workflow** habits — each with a priority and an example snippet. It's a
+fast retrospective on *how you drive the agent*, so next time works better.
+
 ### AI assistant
 
 ```bash

package/dist/cli/ai-prompt.js

@@ -41,6 +41,7 @@ exports.extractIntent = extractIntent;
 exports.run = run;
 exports.main = main;
 const child_process_1 = require("child_process");
+const agent_judge_1 = require("../utils/agent-judge");
 const util_1 = require("util");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -267,35 +268,22 @@ async function extractIntent(prompt) {
         ];
         result = runExtraction('pi', [...piLean, ...piCore], piCore);
     }
-    // Strip markdown code fences if present (Pi may wrap JSON in ```json...```)
-    let jsonStr = result.trim();
-    const fenceMatch = jsonStr.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
-    if (fenceMatch) {
-        jsonStr = fenceMatch[1].trim();
-    }
-    const parsed = JSON.parse(jsonStr);
-    // Handle different output formats:
-    // - Claude: { structured_output: {...} } or { result: "..." }
-    // - Pi: may return the object directly or wrap it
+    // Unwrap the agent's reply (code fences + the structured_output / result-string
+    // / result-object / bare-object envelopes) with the shared parser, so this and
+    // the reflect judge can't drift when a new agent shape is learned. The
+    // extraction-specific INVOCATION (lean flags + tailored timeout/auth errors)
+    // deliberately stays here — those messages are part of the `nemus --` UX.
     let intent;
-    if (parsed.structured_output) {
-        intent = parsed.structured_output;
-    }
-    else if (typeof parsed.result === 'string' && parsed.result) {
-        try {
-            intent = JSON.parse(parsed.result);
-        }
-        catch { /* ignore */ }
-    }
-    else if (typeof parsed.result === 'object' && parsed.result !== null) {
-        intent = parsed.result;
+    try {
+        const parsed = (0, agent_judge_1.parseAgentJson)(result);
+        if (parsed && typeof parsed === 'object')
+            intent = parsed;
     }
-    else if (parsed.workspaceName || parsed.repos || parsed.remainingIntent !== undefined) {
-        // Pi may return the extracted object directly
-        intent = parsed;
+    catch {
+        throw new Error(`Could not extract intent from agent response: ${result.slice(0, 200)}`);
     }
     if (!intent) {
-        throw new Error(`Could not extract intent from agent response. Parsed: ${JSON.stringify(parsed).slice(0, 200)}`);
+        throw new Error(`Could not extract intent from agent response: ${result.slice(0, 200)}`);
     }
     // Coerce/validate field types so malformed model output can't crash the
     // downstream .trim()/sanitize path (a stringly-typed workspaceName or a

package/dist/commands/reflect.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerReflectCommand = registerReflectCommand;
+const logger_1 = require("../utils/logger");
+const output_1 = require("../utils/output");
+const colors_1 = require("../utils/colors");
+const reflect_1 = require("../utils/reflect");
+const agent_judge_1 = require("../utils/agent-judge");
+function registerReflectCommand(parent) {
+    parent
+        .command('reflect')
+        .alias('retro')
+        .description('Analyze your recent workspace sessions and suggest skill/prompt/context improvements (LLM-as-a-judge)')
+        .option('-n, --limit <n>', 'How many recent workspaces to analyze', '10')
+        .option('--json', 'Output the report as JSON')
+        .option('--dry-run', 'Print the assembled corpus + judge prompt without calling the agent')
+        .action(async (opts) => {
+        await handleReflect(opts);
+    });
+}
+async function handleReflect(opts) {
+    const limit = Math.max(1, Number.parseInt(opts.limit ?? '10', 10) || 10);
+    try {
+        const showProgress = !opts.json && !opts.dryRun;
+        if (showProgress) {
+            (0, logger_1.logStep)(`Analyzing your ${(0, colors_1.colorize)(String(limit), 'cyan')} most recent workspaces…`);
+        }
+        const corpus = await (0, reflect_1.gatherReflectionCorpus)(limit, showProgress ? printProgress : undefined);
+        const withSessions = corpus.workspaces.filter((w) => w.session).length;
+        const prompt = (0, reflect_1.buildJudgePrompt)(corpus);
+        if (opts.dryRun) {
+            // No LLM call — surface exactly what the judge would see.
+            if (opts.json)
+                (0, output_1.outputJson)({ corpus, prompt });
+            else {
+                process.stdout.write(prompt + '\n');
+            }
+            return;
+        }
+        if (withSessions === 0) {
+            const msg = 'No recent agent sessions found to analyze (need Claude/pi session transcripts).';
+            if (opts.json)
+                (0, output_1.outputJsonError)(msg);
+            else
+                (0, logger_1.logError)(msg);
+            process.exit(1);
+        }
+        // The judge shells the user's own agent and can take minutes; run it async
+        // (non-blocking) so a live spinner shows it's alive, not hung. Timeout is
+        // overridable for slow local models.
+        const timeoutMs = Number.parseInt(process.env.NEMUS_JUDGE_TIMEOUT_MS ?? '', 10) || undefined;
+        const stopSpinner = opts.json
+            ? () => { }
+            : startSpinner(`Judging ${withSessions} session(s) with your configured agent (this can take a minute)…`);
+        let parsed;
+        try {
+            parsed = await (0, agent_judge_1.runAgentJsonAsync)(prompt, { schema: reflect_1.REFLECT_SCHEMA, timeoutMs });
+        }
+        finally {
+            stopSpinner();
+        }
+        const report = (0, reflect_1.parseReflectionReport)(parsed);
+        if (opts.json) {
+            (0, output_1.outputJson)({ analyzed: withSessions, workspaces: corpus.workspaces.length, ...report });
+            return;
+        }
+        printReport(report, corpus.workspaces.length, withSessions);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : 'reflect failed';
+        if (opts.json)
+            (0, output_1.outputJsonError)(msg);
+        else {
+            (0, logger_1.logError)('Failed to analyze sessions');
+            (0, logger_1.logError)(msg);
+        }
+        process.exit(1);
+    }
+}
+const KIND_LABEL = {
+    skill: 'Skill',
+    context: 'Context/AGENTS.md',
+    test: 'Test',
+    prompt: 'Prompt',
+    connectivity: 'Connectivity',
+    workflow: 'Workflow',
+    other: 'Other',
+};
+/**
+ * A minimal stderr spinner with elapsed seconds. Returns a stop() that clears
+ * the line. No-op (single log line) when stderr isn't a TTY (piped/CI), so it
+ * never pollutes captured output. Kept local + tiny — no new dependency.
+ */
+function startSpinner(text) {
+    if (!process.stderr.isTTY) {
+        (0, logger_1.logInfo)(text);
+        return () => { };
+    }
+    const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    const start = Date.now();
+    let i = 0;
+    const render = () => {
+        const secs = Math.floor((Date.now() - start) / 1000);
+        process.stderr.write(`\r${(0, colors_1.colorize)(frames[(i = (i + 1) % frames.length)], 'cyan')} ${text} ${(0, colors_1.colorize)(`(${secs}s)`, 'dim')}`);
+    };
+    render();
+    const timer = setInterval(render, 100);
+    timer.unref?.(); // never keep the process alive on our account
+    return () => {
+        clearInterval(timer);
+        process.stderr.write('\r' + ' '.repeat(text.length + 24) + '\r');
+    };
+}
+/** Live per-workspace line during the gather phase (to stderr — stdout stays
+ *  reserved for the report / JSON). */
+function printProgress(p) {
+    const n = (0, colors_1.colorize)(`${p.index + 1}/${p.total}`, 'dim');
+    const d = p.digest.session;
+    if (!d) {
+        process.stderr.write(`  ${(0, colors_1.colorize)('·', 'dim')} ${n} ${p.digest.name} ${(0, colors_1.colorize)('— no session', 'dim')}\n`);
+        return;
+    }
+    const failures = `${d.errors.length} ${d.errors.length === 1 ? 'failure' : 'failures'}`;
+    const stats = (0, colors_1.colorize)(`${d.turns} turns · ${d.userPrompts.length} prompts · ${failures}`, 'dim');
+    process.stderr.write(`  ${(0, colors_1.colorize)('✓', 'green')} ${n} ${p.digest.name}  ${stats}\n`);
+}
+function priorityBadge(p) {
+    if (p === 'high')
+        return (0, colors_1.colorize)('● high', 'red');
+    if (p === 'medium')
+        return (0, colors_1.colorize)('● med', 'yellow');
+    return (0, colors_1.colorize)('● low', 'gray');
+}
+function printReport(report, workspaces, analyzed) {
+    console.log('');
+    console.log((0, colors_1.colorize)('  Reflection', 'bright') + (0, colors_1.colorize)(`  (${analyzed} sessions across ${workspaces} workspaces)`, 'dim'));
+    console.log((0, colors_1.colorize)('  ' + '─'.repeat(56), 'dim'));
+    if (report.summary) {
+        console.log('\n  ' + report.summary.replace(/\n/g, '\n  '));
+    }
+    if (report.recommendations.length === 0) {
+        console.log('\n  ' + (0, colors_1.colorize)('No specific recommendations — looks solid.', 'green') + '\n');
+        return;
+    }
+    // High priority first.
+    const order = { high: 0, medium: 1, low: 2 };
+    const recs = [...report.recommendations].sort((a, b) => order[a.priority] - order[b.priority]);
+    console.log('');
+    for (const r of recs) {
+        const target = r.target ? (0, colors_1.colorize)(`  [${r.target}]`, 'cyan') : '';
+        console.log(`  ${priorityBadge(r.priority)}  ${(0, colors_1.colorize)(KIND_LABEL[r.kind], 'bright')}  ${r.title}${target}`);
+        if (r.detail)
+            console.log(`      ${r.detail.replace(/\n/g, '\n      ')}`);
+        if (r.example) {
+            console.log((0, colors_1.colorize)('      example:', 'dim'));
+            console.log((0, colors_1.colorize)(r.example.replace(/^/gm, '        '), 'dim'));
+        }
+        console.log('');
+    }
+}

package/dist/program.js

@@ -89,6 +89,7 @@ const save_context_1 = require("./commands/save-context");
 const migrate_1 = require("./commands/migrate");
 const report_bug_1 = require("./commands/report-bug");
 const completion_1 = require("./commands/completion");
+const reflect_1 = require("./commands/reflect");
 (0, create_1.registerCreateCommand)(exports.program);
 (0, list_1.registerListCommand)(exports.program);
 (0, update_1.registerUpdateCommand)(exports.program);
@@ -113,6 +114,7 @@ const completion_1 = require("./commands/completion");
 (0, migrate_1.registerMigrateCommand)(exports.program);
 (0, report_bug_1.registerReportBugCommand)(exports.program);
 (0, completion_1.registerCompletionCommand)(exports.program);
+(0, reflect_1.registerReflectCommand)(exports.program);
 // Register TUI (delegates to existing Ink/React implementation)
 exports.program
     .command('tui')

package/dist/utils/agent-judge.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentAttempts = agentAttempts;
+exports.runAgentRaw = runAgentRaw;
+exports.runAgentRawAsync = runAgentRawAsync;
+exports.runAgentJson = runAgentJson;
+exports.runAgentJsonAsync = runAgentJsonAsync;
+exports.parseAgentJson = parseAgentJson;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const agent_config_1 = require("./agent-config");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+/**
+ * The ordered invocation attempts for an agent (preferred → fallback), as pure
+ * data so both the sync and async runners share ONE flag ladder (and it's
+ * unit-testable without spawning anything).
+ */
+function agentAttempts(agentType, prompt, schema) {
+    if (agentType === 'claude') {
+        const preferred = ['-p', prompt, '--output-format', 'json', '--bare', '--strict-mcp-config', '--disable-slash-commands'];
+        if (schema)
+            preferred.push('--json-schema', schema);
+        // Older claude may reject the newer flags — fall back to the plainest form.
+        return [{ cmd: 'claude', args: preferred }, { cmd: 'claude', args: ['-p', prompt] }];
+    }
+    if (agentType === 'opencode') {
+        return [{ cmd: 'opencode', args: ['run', prompt] }];
+    }
+    // pi (and any other): run as lean as possible so a bloated env can't hang it.
+    const piLean = ['--no-extensions', '--no-skills', '--no-prompt-templates', '--no-context-files', '--no-tools', '--no-session'];
+    return [{ cmd: 'pi', args: [...piLean, '-p', prompt] }, { cmd: 'pi', args: ['-p', prompt] }];
+}
+function wrapJudgeError(err, agentType) {
+    // A timeout is the common failure (big prompt + slow local model), so make it
+    // actionable instead of surfacing a raw `spawn … ETIMEDOUT`.
+    if (err?.killed || err?.code === 'ETIMEDOUT' || err?.signal === 'SIGTERM' || /ETIMEDOUT/.test(String(err?.message ?? ''))) {
+        return new Error(`agent judge (${agentType}) timed out. Try a smaller --limit, a faster agent, or raise the cap with NEMUS_JUDGE_TIMEOUT_MS.`);
+    }
+    const detail = (err?.stderr || err?.stdout || err?.message || 'unknown error').toString().trim().slice(0, 500);
+    return new Error(`agent judge failed (${agentType}): ${detail}`);
+}
+const DEFAULT_TIMEOUT_MS = 300000; // judging N transcripts is heavier than extraction; a big prompt + slow model can run minutes
+const DEFAULT_MAX_BUFFER = 32 * 1024 * 1024;
+/**
+ * Invoke the agent with `prompt` and return the raw stdout. Throws a clear error
+ * on timeout / non-zero exit. Kept separate from parsing so callers can inspect
+ * raw output (e.g. `--dry-run`, debugging).
+ */
+function runAgentRaw(prompt, opts = {}) {
+    const agentType = opts.agentType ?? (0, agent_config_1.getPrimaryAgent)().type;
+    const timeout = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxBuffer = opts.maxBuffer ?? DEFAULT_MAX_BUFFER;
+    const exec = opts.exec ??
+        ((cmd, args, o) => (0, child_process_1.execFileSync)(cmd, args, { encoding: 'utf-8', timeout: o.timeout, maxBuffer: o.maxBuffer }));
+    const attempts = agentAttempts(agentType, prompt, opts.schema);
+    let lastErr;
+    for (const a of attempts) {
+        try {
+            return exec(a.cmd, a.args, { timeout, maxBuffer });
+        }
+        catch (err) {
+            lastErr = err; // try the next (fallback) form
+        }
+    }
+    throw wrapJudgeError(lastErr, agentType);
+}
+/**
+ * Non-blocking twin of {@link runAgentRaw}. Uses `execFile` (async) so the
+ * caller's event loop stays free — letting a spinner/progress UI animate while
+ * the judge (which can take minutes) runs. Prefer this in interactive commands.
+ */
+async function runAgentRawAsync(prompt, opts = {}) {
+    const agentType = opts.agentType ?? (0, agent_config_1.getPrimaryAgent)().type;
+    const timeout = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxBuffer = opts.maxBuffer ?? DEFAULT_MAX_BUFFER;
+    const exec = opts.execAsync ??
+        (async (cmd, args, o) => (await execFileAsync(cmd, args, { encoding: 'utf-8', timeout: o.timeout, maxBuffer: o.maxBuffer })).stdout.toString());
+    const attempts = agentAttempts(agentType, prompt, opts.schema);
+    let lastErr;
+    for (const a of attempts) {
+        try {
+            return await exec(a.cmd, a.args, { timeout, maxBuffer });
+        }
+        catch (err) {
+            lastErr = err; // try the next (fallback) form
+        }
+    }
+    throw wrapJudgeError(lastErr, agentType);
+}
+/**
+ * Run the agent and parse its reply as JSON, tolerating the shapes different
+ * agents emit: `{ structured_output }`, `{ result: "<json>" }`, a ```json fence,
+ * or a bare object. Returns `unknown`; callers validate/normalize their shape.
+ */
+function runAgentJson(prompt, opts = {}) {
+    const raw = runAgentRaw(prompt, opts);
+    return parseAgentJson(raw);
+}
+/** Non-blocking twin of {@link runAgentJson}. */
+async function runAgentJsonAsync(prompt, opts = {}) {
+    const raw = await runAgentRawAsync(prompt, opts);
+    return parseAgentJson(raw);
+}
+/** Extract a JSON object from an agent's raw stdout. Exported for tests. */
+function parseAgentJson(raw) {
+    let text = raw.trim();
+    const fence = text.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+    if (fence)
+        text = fence[1].trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        // Last resort: grab the outermost {...} span.
+        const span = text.match(/\{[\s\S]*\}/);
+        if (!span)
+            throw new Error('agent did not return JSON');
+        parsed = JSON.parse(span[0]);
+    }
+    // Unwrap the common agent envelopes.
+    if (parsed && typeof parsed === 'object') {
+        if (parsed.structured_output && typeof parsed.structured_output === 'object')
+            return parsed.structured_output;
+        if (typeof parsed.result === 'string') {
+            try {
+                return JSON.parse(parsed.result);
+            }
+            catch {
+                /* fall through — result was plain text, return the envelope */
+            }
+        }
+        if (parsed.result && typeof parsed.result === 'object')
+            return parsed.result;
+    }
+    return parsed;
+}