@nemus-cli/nemus 0.3.0 → 0.3.2

package/dist/utils/reflect.js

@@ -34,10 +34,11 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.REFLECT_SCHEMA = void 0;
+exports.isCorrectionPrompt = isCorrectionPrompt;
 exports.distillTranscript = distillTranscript;
+exports.classifyAgentsMd = classifyAgentsMd;
 exports.findLatestTranscriptFile = findLatestTranscriptFile;
 exports.gatherReflectionCorpus = gatherReflectionCorpus;
-exports.buildJudgePrompt = buildJudgePrompt;
 exports.parseReflectionReport = parseReflectionReport;
 const fs = __importStar(require("fs/promises"));
 const path = __importStar(require("path"));
@@ -45,10 +46,24 @@ const workspace_meta_1 = require("./workspace-meta");
 const agent_config_1 = require("./agent-config");
 const claude_sessions_1 = require("./claude-sessions");
 // --------------------------------------------------------- transcript distill
-const MAX_PROMPTS = 25;
-const MAX_ERRORS = 25;
-const PROMPT_CHARS = 600;
-const ERROR_CHARS = 300;
+// Kept deliberately lean: the judge runs on the user's own (often local, slow)
+// agent, and a 10-workspace corpus at full verbosity produced a ~200KB prompt
+// that timed pi out. These bounds capture the pattern of a session at a
+// fraction of the tokens (~halving the prompt), so the judge actually finishes.
+const MAX_PROMPTS = 12;
+const MAX_ERRORS = 15;
+const MAX_RESTEER = 6;
+const PROMPT_CHARS = 400;
+const ERROR_CHARS = 200;
+const RESTEER_CHARS = 240;
+// A conservative “the user corrected / redirected the agent” cue. Soft signal:
+// used to count re-steers and to capture the verbatim message for the judge.
+const CORRECTION_RE = /\b(no|nope|wrong|incorrect|revert|undo|instead|actually|you (missed|forgot|broke|didn'?t)|that'?s? (wrong|not right|incorrect)|not what|don'?t)\b/i;
+/** Whether a single user prompt reads like a correction/redirect. Exported +
+ *  shared with the analyzer so the two never diverge. */
+function isCorrectionPrompt(prompt) {
+    return CORRECTION_RE.test(prompt ?? '');
+}
 /** Flatten a message `content` (string or content-block array) to plain text. */
 function contentToText(content) {
     if (typeof content === 'string')
@@ -86,6 +101,7 @@ function isToolFailure(flag, text) {
  */
 function distillTranscript(raw, meta) {
     const userPrompts = [];
+    const reSteerSamples = [];
     const errors = [];
     const tools = new Set();
     let turns = 0;
@@ -139,13 +155,57 @@ function distillTranscript(raw, meta) {
             const isToolResultOnly = Array.isArray(content) && content.length > 0 && content.every((b) => b?.type === 'tool_result');
             if (!isToolResultOnly) {
                 const text = contentToText(content).trim();
-                if (text && !text.startsWith('<') && userPrompts.length < MAX_PROMPTS) {
-                    userPrompts.push(text.slice(0, PROMPT_CHARS));
+                if (text && !text.startsWith('<')) {
+                    if (userPrompts.length < MAX_PROMPTS)
+                        userPrompts.push(text.slice(0, PROMPT_CHARS));
+                    // Capture corrections verbatim (bounded) — the sharpest coaching signal.
+                    if (reSteerSamples.length < MAX_RESTEER && isCorrectionPrompt(text)) {
+                        reSteerSamples.push(text.slice(0, RESTEER_CHARS));
+                    }
                 }
             }
         }
     }
-    return { sessionId: meta.sessionId, agentType: meta.agentType, turns, userPrompts, errors, tools: [...tools] };
+    return { sessionId: meta.sessionId, agentType: meta.agentType, turns, userPrompts, reSteerSamples, errors, tools: [...tools] };
+}
+// ------------------------------------------------------- context classification
+// Lines that are structural/boilerplate rather than real, custom guidance.
+const BOILERPLATE_MARKERS = [
+    'ws-rules:',
+    'this workspace was created with',
+    'workspace manager',
+    'saved context',
+    'add your own notes here',
+    'common workflows',
+];
+/**
+ * Classify an AGENTS.md/CLAUDE.md by how much *real* guidance it carries, so the
+ * judge can tell “no context” from “has a file but it's the generated template.”
+ * Heuristic + pure.
+ *
+ * Deliberately **newline-independent**: it measures the volume of non-boilerplate
+ * prose (word count) plus heading count via a whitespace-tolerant regex, rather
+ * than splitting on lines. A line-anchored version would misclassify any excerpt
+ * whose newlines were collapsed to spaces upstream (a real bug class caught in a
+ * sibling implementation) — here even a fully single-lined file classifies the
+ * same as its multi-line original.
+ */
+function classifyAgentsMd(content) {
+    if (!content || !content.trim())
+        return 'missing';
+    let s = content.replace(/\r\n/g, '\n').toLowerCase();
+    s = s.replace(/```[\s\S]*?```/g, ' '); // drop fenced code
+    s = s.replace(/<!--[\s\S]*?-->/g, ' '); // drop HTML comments
+    for (const m of BOILERPLATE_MARKERS)
+        s = s.split(m).join(' '); // drop generated boilerplate (markers are lowercase)
+    // Headings: a `#` run at start OR after any whitespace (so a collapsed,
+    // single-line excerpt still counts them), followed by a space.
+    const headings = (s.match(/(?:^|\s)#{1,6}\s/g) || []).length;
+    // Remaining non-boilerplate words (markdown punctuation stripped).
+    const words = s.replace(/[#|>*_`~-]/g, ' ').split(/\s+/).filter((w) => w.length > 1).length;
+    if (words < 40)
+        return 'boilerplate';
+    return headings >= 2 || words >= 60 ? 'substantive' : 'boilerplate';
 }
 // --------------------------------------------------------- corpus gathering
 /** Locate the most recent `.jsonl` transcript for a workspace under an agent. */
@@ -220,26 +280,34 @@ async function listAvailableSkills() {
     }
     return [...names].sort();
 }
+/** Which context files exist at the workspace root, plus how substantive the
+ *  primary one is (missing/boilerplate/substantive). One read per present file. */
 async function contextFilesFor(workspacePath) {
     const present = [];
+    let quality = 'missing';
     for (const name of (0, agent_config_1.getAllKnownContextFileNames)()) {
         try {
-            await fs.access(path.join(workspacePath, name));
+            const content = await fs.readFile(path.join(workspacePath, name), 'utf-8');
             present.push(name);
+            // Classify the first present file, then keep the best classification seen.
+            const c = classifyAgentsMd(content);
+            if (quality === 'missing' || (quality === 'boilerplate' && c === 'substantive'))
+                quality = c;
         }
         catch {
-            /* not present */
+            /* not present / unreadable */
         }
     }
-    return present;
+    return { files: present, quality };
 }
 /**
  * Build the corpus the judge reasons over: the `limit` most **recently active**
  * workspaces (by their latest agent session, not creation date — a retrospective
  * is about recent *work*), each with its repos, context files, and distilled
- * session, plus the globally-available skills.
+ * session, plus the globally-available skills. `onProgress` (optional) fires
+ * once per workspace as it finishes, for a live progress display.
  */
-async function gatherReflectionCorpus(limit) {
+async function gatherReflectionCorpus(limit, onProgress) {
     const [sessions, workspaces, availableSkills] = await Promise.all([
         (0, claude_sessions_1.getWorkspaceSessions)(), // already sorted by last-active, one per workspace
         (0, workspace_meta_1.listWorkspaces)(false),
@@ -248,15 +316,20 @@ async function gatherReflectionCorpus(limit) {
     const metaByName = new Map(workspaces.map((w) => [w.name, w]));
     const recent = sessions.slice(0, limit);
     const digests = [];
-    for (const s of recent) {
+    for (let index = 0; index < recent.length; index++) {
+        const s = recent[index];
         const meta = metaByName.get(s.workspaceName);
-        digests.push({
+        const context = await contextFilesFor(s.workspacePath);
+        const digest = {
             name: s.workspaceName,
             repoCount: meta?.metadata?.repositories?.length ?? 0,
             repos: (meta?.metadata?.repositories ?? []).map((r) => r.name),
-            contextFiles: await contextFilesFor(s.workspacePath),
+            contextFiles: context.files,
+            contextQuality: context.quality,
             session: await readDigestForSession(s),
-        });
+        };
+        digests.push(digest);
+        onProgress?.({ index, total: recent.length, digest });
     }
     return { generatedAt: new Date().toISOString(), availableSkills, workspaces: digests };
 }
@@ -284,37 +357,8 @@ exports.REFLECT_SCHEMA = JSON.stringify({
     },
     required: ['summary', 'recommendations'],
 });
-/**
- * Build the LLM-as-a-judge prompt. The judge sees distilled recent sessions and
- * is asked to recommend concrete improvements to the user's SETUP (skills,
- * AGENTS.md/context rules, connectivity/tests, prompt habits, workflow) — not to
- * redo the tasks. Output is strict JSON matching REFLECT_SCHEMA.
- */
-function buildJudgePrompt(corpus) {
-    const lines = [];
-    lines.push('You are an expert reviewer ("LLM as a judge") analyzing an engineer\'s recent AI coding-agent sessions.', 'Goal: recommend concrete improvements to their SETUP so the agent works better next time —', 'which skills to add and WHERE, which AGENTS.md/context rules are missing, missing connectivity/', 'smoke tests, and prompt habits to change. Judge the setup, do NOT redo the tasks.', '', 'Base every recommendation on evidence in the sessions below (repeated failures, retries, vague', 'prompts, missing context). Prefer a few high-signal, actionable items over many generic ones.', 'When you suggest a skill or an AGENTS.md rule, include a short concrete `example` snippet.', '', `Globally installed skills (don't re-suggest these; suggest genuinely missing ones): ${corpus.availableSkills.join(', ') || '(none)'}`, '', `Recent workspaces (${corpus.workspaces.length}):`);
-    for (const ws of corpus.workspaces) {
-        lines.push(`\n## ${ws.name}`);
-        lines.push(`repos: ${ws.repos.join(', ') || '(none)'} | context files: ${ws.contextFiles.join(', ') || 'NONE'}`);
-        if (!ws.session) {
-            lines.push('session: (no recent agent session found)');
-            continue;
-        }
-        lines.push(`session: ${ws.session.turns} turns, tools used: ${ws.session.tools.join(', ') || '(none)'}`);
-        if (ws.session.userPrompts.length) {
-            lines.push('user prompts:');
-            for (const p of ws.session.userPrompts)
-                lines.push(`  - ${p.replace(/\n/g, ' ')}`);
-        }
-        if (ws.session.errors.length) {
-            lines.push('errors/failures observed:');
-            for (const e of ws.session.errors)
-                lines.push(`  - ${e.replace(/\n/g, ' ')}`);
-        }
-    }
-    lines.push('', 'Respond with ONLY a JSON object of this shape (no prose, no markdown fence):', '{"summary": string, "recommendations": [{"kind":"skill|context|test|prompt|connectivity|workflow|other",', '"title": string, "detail": string, "target": string(optional workspace/repo/path),', '"priority":"high|medium|low", "example": string(optional snippet)}]}');
-    return lines.join('\n');
-}
+// The judge prompt is now built from pre-computed FACTS (see reflect-analyze.ts
+// `buildAnalysisPrompt`), not raw transcripts, so the LLM call stays small/fast.
 // ----------------------------------------------------------- response parse
 const KINDS = ['skill', 'context', 'test', 'prompt', 'connectivity', 'workflow', 'other'];
 const PRIORITIES = ['high', 'medium', 'low'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nemus-cli/nemus",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "workspaces": [
     "packages/*"
   ],

package/src/cli/ai-prompt.ts

@@ -140,6 +140,10 @@ function runExtraction(cmd: string, fullArgs: string[], fallbackArgs?: string[])
   const exec = (args: string[]) =>
     execFileSync(cmd, args, {
       encoding: 'utf-8',
+      // `input: ''` closes the child's stdin (EOF) so a stdin-reading agent (pi)
+      // can't block this synchronous call forever in a headless/piped context
+      // — the same hang the async judge hit, guarded here for `nemus -- "…"`.
+      input: '',
       timeout: EXTRACTION_TIMEOUT_MS,
       maxBuffer: 10 * 1024 * 1024,
     });

package/src/commands/reflect.ts

@@ -4,13 +4,14 @@ import { outputJson, outputJsonError } from '../utils/output';
 import { colorize } from '../utils/colors';
 import {
   gatherReflectionCorpus,
-  buildJudgePrompt,
   parseReflectionReport,
   REFLECT_SCHEMA,
   ReflectionReport,
+  ReflectProgress,
   Recommendation,
 } from '../utils/reflect';
-import { runAgentJson } from '../utils/agent-judge';
+import { analyzeCorpus, buildAnalysisPrompt } from '../utils/reflect-analyze';
+import { runAgentJsonAsync } from '../utils/agent-judge';
 
 export function registerReflectCommand(parent: Command) {
   parent
@@ -18,6 +19,8 @@ export function registerReflectCommand(parent: Command) {
     .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('--model <model>', 'Judge model override (agent-native pattern/id)')
+    .option('--thinking <level>', 'Judge thinking level for pi: off|minimal|low|medium|high|xhigh|max')
     .option('--json', 'Output the report as JSON')
     .option('--dry-run', 'Print the assembled corpus + judge prompt without calling the agent')
     .action(async (opts) => {
@@ -25,21 +28,25 @@ export function registerReflectCommand(parent: Command) {
     });
 }
 
-async function handleReflect(opts: { limit?: string; json?: boolean; dryRun?: boolean }) {
+async function handleReflect(opts: { limit?: string; model?: string; thinking?: string; json?: boolean; dryRun?: boolean }) {
   const limit = Math.max(1, Number.parseInt(opts.limit ?? '10', 10) || 10);
   try {
-    if (!opts.json && !opts.dryRun) {
+    const showProgress = !opts.json && !opts.dryRun;
+    if (showProgress) {
       logStep(`Analyzing your ${colorize(String(limit), 'cyan')} most recent workspaces…`);
-      logInfo('Reading sessions and distilling prompts + failures…');
     }
 
-    const corpus = await gatherReflectionCorpus(limit);
+    const corpus = await gatherReflectionCorpus(limit, showProgress ? printProgress : undefined);
     const withSessions = corpus.workspaces.filter((w) => w.session).length;
-    const prompt = buildJudgePrompt(corpus);
+    // A script does the heavy analysis (clustering failures, counting tools,
+    // spotting correction loops); the LLM only ever sees these compact facts,
+    // so the judge call stays small + fast regardless of workspace count.
+    const analysis = analyzeCorpus(corpus);
+    const prompt = buildAnalysisPrompt(analysis);
 
     if (opts.dryRun) {
-      // No LLM call — surface exactly what the judge would see.
-      if (opts.json) outputJson({ corpus, prompt });
+      // No LLM call — surface the computed facts + exactly what the judge sees.
+      if (opts.json) outputJson({ analysis, prompt });
       else {
         process.stdout.write(prompt + '\n');
       }
@@ -53,8 +60,21 @@ async function handleReflect(opts: { limit?: string; json?: boolean; dryRun?: bo
       process.exit(1);
     }
 
-    if (!opts.json) logInfo(`Judging ${withSessions} session(s) with your configured agent…`);
-    const parsed = runAgentJson(prompt, { schema: REFLECT_SCHEMA });
+    // 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 model = opts.model ?? process.env.NEMUS_JUDGE_MODEL ?? undefined;
+    const thinking = opts.thinking ?? process.env.NEMUS_JUDGE_THINKING ?? undefined;
+    const stopSpinner = opts.json
+      ? () => {}
+      : startSpinner(`Judging ${withSessions} session(s) with your configured agent (this can take a minute)…`);
+    let parsed: unknown;
+    try {
+      parsed = await runAgentJsonAsync(prompt, { schema: REFLECT_SCHEMA, timeoutMs, model, thinking });
+    } finally {
+      stopSpinner();
+    }
     const report = parseReflectionReport(parsed);
 
     if (opts.json) {
@@ -83,6 +103,46 @@ const KIND_LABEL: Record<Recommendation['kind'], string> = {
   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: string): () => void {
+  if (!process.stderr.isTTY) {
+    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${colorize(frames[(i = (i + 1) % frames.length)], 'cyan')} ${text} ${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: ReflectProgress): void {
+  const n = colorize(`${p.index + 1}/${p.total}`, 'dim');
+  const d = p.digest.session;
+  if (!d) {
+    process.stderr.write(`  ${colorize('·', 'dim')} ${n} ${p.digest.name} ${colorize('— no session', 'dim')}\n`);
+    return;
+  }
+  const failures = `${d.errors.length} ${d.errors.length === 1 ? 'failure' : 'failures'}`;
+  const stats = colorize(`${d.turns} turns · ${d.userPrompts.length} prompts · ${failures}`, 'dim');
+  process.stderr.write(`  ${colorize('✓', 'green')} ${n} ${p.digest.name}  ${stats}\n`);
+}
+
 function priorityBadge(p: Recommendation['priority']): string {
   if (p === 'high') return colorize('● high', 'red');
   if (p === 'medium') return colorize('● med', 'yellow');

package/src/utils/agent-judge.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { parseAgentJson, runAgentRaw } from './agent-judge';
+import { parseAgentJson, runAgentRaw, runAgentRawAsync, agentAttempts, spawnCollect } from './agent-judge';
 
 describe('parseAgentJson', () => {
   it('unwraps the common agent envelopes and shapes', () => {
@@ -16,6 +16,75 @@ describe('parseAgentJson', () => {
   });
 });
 
+describe('spawnCollect (stdin-hang regression)', () => {
+  it('gives the child stdin EOF so a stdin-reading process does NOT hang', async () => {
+    // `cat` with no args reads stdin to EOF. If stdin were an open pipe (the old
+    // execFile default) this would block until the timeout and reject; with
+    // stdin ignored it gets immediate EOF and exits 0 fast. 2s timeout << any hang.
+    const out = await spawnCollect('cat', [], { timeout: 2000, maxBuffer: 1 << 20 });
+    expect(out).toBe('');
+  });
+
+  it('captures stdout and rejects on non-zero exit', async () => {
+    await expect(spawnCollect('node', ['-e', 'process.stdout.write("hi")'], { timeout: 5000, maxBuffer: 1 << 20 })).resolves.toBe('hi');
+    await expect(spawnCollect('node', ['-e', 'process.exit(3)'], { timeout: 5000, maxBuffer: 1 << 20 })).rejects.toThrow(/exit 3/);
+  });
+});
+
+describe('agentAttempts', () => {
+  it('claude: preferred (schema + lean flags) then a plain fallback', () => {
+    const a = agentAttempts('claude', 'P', { schema: '{"type":"object"}' });
+    expect(a[0]).toEqual({ cmd: 'claude', args: expect.arrayContaining(['-p', 'P', '--output-format', 'json', '--json-schema', '{"type":"object"}']) });
+    expect(a[1]).toEqual({ cmd: 'claude', args: ['-p', 'P'] });
+  });
+  it('pi: lean then plain; opencode: single run', () => {
+    const pi = agentAttempts('pi', 'P');
+    expect(pi[0].args).toEqual(expect.arrayContaining(['--no-tools', '--no-skills', '-p', 'P']));
+    expect(pi[1]).toEqual({ cmd: 'pi', args: ['-p', 'P'] });
+    expect(agentAttempts('opencode', 'P')).toEqual([{ cmd: 'opencode', args: ['run', 'P'] }]);
+  });
+  it('threads --model (all) + --thinking (pi only); fallback keeps model, drops --thinking', () => {
+    const pi = agentAttempts('pi', 'P', { model: 'haiku', thinking: 'low' });
+    expect(pi[0].args).toEqual(expect.arrayContaining(['--model', 'haiku', '--thinking', 'low', '-p', 'P']));
+    // Safety net: model stays (stable flag), --thinking is dropped so an old pi
+    // that rejects --thinking still has a working fallback.
+    expect(pi[1].args).toEqual(['--model', 'haiku', '-p', 'P']);
+    expect(pi[1].args).not.toContain('--thinking');
+    const cl = agentAttempts('claude', 'P', { model: 'sonnet' });
+    expect(cl[0].args).toEqual(expect.arrayContaining(['--model', 'sonnet']));
+    expect(cl[0].args).not.toContain('--thinking'); // thinking is pi-only
+    expect(agentAttempts('opencode', 'P', { model: 'gpt' })[0].args).toEqual(['run', 'P', '--model', 'gpt']);
+  });
+});
+
+describe('runAgentRaw thinking default', () => {
+  it('applies the low-thinking default for pi', () => {
+    let seen: string[] = [];
+    runAgentRaw('P', { agentType: 'pi', exec: (cmd, args) => ((seen = [cmd, ...args]), 'ok') });
+    expect(seen).toEqual(expect.arrayContaining(['--thinking', 'low']));
+  });
+});
+
+describe('runAgentRawAsync', () => {
+  it('runs the preferred attempt and returns stdout', async () => {
+    const calls: string[][] = [];
+    const execAsync = async (cmd: string, args: string[]) => {
+      calls.push([cmd, ...args]);
+      return '{"ok":true}';
+    };
+    const out = await runAgentRawAsync('P', { agentType: 'pi', execAsync });
+    expect(out).toBe('{"ok":true}');
+    expect(calls).toHaveLength(1); // first attempt succeeded, no fallback
+  });
+
+  it('turns a timeout into an actionable error', async () => {
+    const execAsync = async () => {
+      throw Object.assign(new Error('spawn pi ETIMEDOUT'), { code: 'ETIMEDOUT', killed: true });
+    };
+    await expect(runAgentRawAsync('P', { agentType: 'pi', execAsync })).rejects.toThrow(/timed out.*NEMUS_JUDGE_TIMEOUT_MS/s);
+  });
+});
+
 describe('runAgentRaw', () => {
   it('claude: passes the schema + lean flags, falls back on a rejected flag', () => {
     const calls: string[][] = [];