minimal-agent 0.2.0 → 0.3.1

package/plugins/ralph-wiggum/src/goalState.ts

@@ -1,310 +0,0 @@
-import { mkdir, appendFile, writeFile, unlink, rmdir } from 'node:fs/promises';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import type { Check } from './verificationGate.ts';
-
-export enum Phase {
-  PLAN = 'plan',
-  BUILD = 'build',
-  VERIFY = 'verify',
-  HEAL = 'heal',
-  DONE = 'done',
-}
-
-const VALID_PHASES = new Set<string>(Object.values(Phase));
-
-interface DecisionEntry {
-  iteration: number;
-  phase: Phase;
-  contextSummary: string;
-  options: string[];
-  chosen: string;
-  reasoning: string;
-  outcome?: string;
-}
-
-interface DecisionContext {
-  iteration: number;
-  phase: Phase;
-  summary: string;
-}
-
-const PHASE_TRANSITIONS: Record<Phase, Record<string, Phase>> = {
-  [Phase.PLAN]: {
-    plan_complete: Phase.BUILD,
-    stuck: Phase.PLAN,
-  },
-  [Phase.BUILD]: {
-    task_complete: Phase.VERIFY,
-    need_replan: Phase.PLAN,
-    tests_failing: Phase.HEAL,
-  },
-  [Phase.VERIFY]: {
-    all_pass: Phase.BUILD,
-    failures: Phase.HEAL,
-    goal_complete: Phase.DONE,
-  },
-  [Phase.HEAL]: {
-    fixed: Phase.VERIFY,
-    cannot_fix_locally: Phase.PLAN,
-  },
-  [Phase.DONE]: {},
-};
-
-function isLegalTransition(from: Phase, to: Phase): boolean {
-  if (from === to) return true;
-  const allowed = PHASE_TRANSITIONS[from];
-  if (!allowed) return false;
-  return Object.values(allowed).includes(to);
-}
-
-const LEARNINGS_TAIL_LINES = 20;
-
-export class GoalState {
-  readonly dir: string;
-
-  constructor(workspaceDir: string, sessionTag?: string) {
-    const suffix = sessionTag ? `-${sessionTag}` : '';
-    this.dir = join(workspaceDir, `.minimal-agent${suffix}`);
-  }
-
-  async reset(): Promise<void> {
-    const files = ['goal.md', 'completion.md', 'phase.md', 'progress.md', 'learnings.md', 'decisions.md'];
-    for (const f of files) {
-      try {
-        await unlink(join(this.dir, f));
-      } catch {
-      }
-    }
-  }
-
-  async init(goal: string, criteria: Check[]): Promise<void> {
-    await mkdir(this.dir, { recursive: true });
-
-    const files: Record<string, string> = {
-      goal: `# 不可变目标 (IMMUTABLE GOAL)\n\n${goal}\n`,
-      completion: JSON.stringify(criteria, null, 2),
-      phase: Phase.PLAN,
-      progress: '',
-      learnings: '',
-      decisions: '',
-    };
-
-    for (const [name, content] of Object.entries(files)) {
-      const path = join(this.dir, `${name}.md`);
-      if (!existsSync(path)) {
-        await writeFile(path, content);
-      }
-    }
-  }
-
-  get goal(): string {
-    try {
-      return readFileSync(join(this.dir, 'goal.md'), 'utf8').trim();
-    } catch {
-      return '';
-    }
-  }
-
-  get completionCriteria(): Check[] {
-    try {
-      const raw = readFileSync(join(this.dir, 'completion.md'), 'utf8').trim();
-      return JSON.parse(raw) as Check[];
-    } catch {
-      return [];
-    }
-  }
-
-  get currentPhase(): Phase {
-    try {
-      const raw = readFileSync(join(this.dir, 'phase.md'), 'utf8').trim();
-      if (VALID_PHASES.has(raw)) {
-        return raw as Phase;
-      }
-    } catch {
-    }
-    return Phase.PLAN;
-  }
-
-  /**
-   * 切换阶段。`reason` 是给人看的日志文本，不参与校验。
-   * 校验只看 from→to 是否在 PHASE_TRANSITIONS 表里有路径（任意 event 通向 to 即合法）。
-   * 想绕开 FSM 用 forceSetPhase。
-   */
-  async setPhase(phase: Phase, reason: string): Promise<void> {
-    if (!VALID_PHASES.has(phase)) {
-      throw new Error(`Invalid phase: ${phase}`);
-    }
-
-    const current = this.currentPhase;
-    if (!isLegalTransition(current, phase)) {
-      throw new Error(
-        `非法阶段切换: ${current} → ${phase}。该目标阶段不在 PHASE_TRANSITIONS[${current}] 的可达集合内，需要走 forceSetPhase。`,
-      );
-    }
-
-    await writeFile(join(this.dir, 'phase.md'), phase);
-    await this.appendProgress(`PHASE → ${phase}: ${reason}`);
-  }
-
-  async forceSetPhase(phase: Phase, reason: string): Promise<void> {
-    if (!VALID_PHASES.has(phase)) {
-      throw new Error(`Invalid phase: ${phase}`);
-    }
-    await writeFile(join(this.dir, 'phase.md'), phase);
-    await this.appendProgress(`PHASE → ${phase}: ${reason}`);
-  }
-
-  async appendProgress(line: string): Promise<void> {
-    const timestamp = new Date().toLocaleTimeString('en-US', { hour12: false });
-    await appendFile(join(this.dir, 'progress.md'), `[${timestamp}] ${line}\n`);
-  }
-
-  tailProgress(n: number): string {
-    try {
-      const content = readFileSync(join(this.dir, 'progress.md'), 'utf8');
-      const lines = content.trim().split('\n').filter(Boolean);
-      return lines.slice(-n).join('\n');
-    } catch {
-      return '';
-    }
-  }
-
-  async appendLearning(lesson: string): Promise<void> {
-    await appendFile(join(this.dir, 'learnings.md'), `- ${lesson}\n`);
-  }
-
-  get learnings(): string {
-    try {
-      const raw = readFileSync(join(this.dir, 'learnings.md'), 'utf8').trim();
-      if (!raw) return '';
-      const lines = raw.split('\n').filter(Boolean);
-      return lines.slice(-LEARNINGS_TAIL_LINES).join('\n');
-    } catch {
-      return '';
-    }
-  }
-
-  async recordDecision(
-    ctx: DecisionContext,
-    options: string[],
-    chosen: string,
-    reasoning: string,
-  ): Promise<void> {
-    const entry: DecisionEntry = {
-      iteration: ctx.iteration,
-      phase: ctx.phase,
-      contextSummary: ctx.summary,
-      options,
-      chosen,
-      reasoning,
-    };
-
-    const line = JSON.stringify(entry);
-    await appendFile(join(this.dir, 'decisions.md'), `${line}\n`);
-  }
-
-  findSimilarDecisions(ctx: DecisionContext, k: number = 3): DecisionEntry[] {
-    try {
-      const content = readFileSync(join(this.dir, 'decisions.md'), 'utf8');
-      const lines = content.trim().split('\n').filter(Boolean);
-
-      const entries: DecisionEntry[] = [];
-      for (const line of lines) {
-        try {
-          entries.push(JSON.parse(line));
-        } catch {
-        }
-      }
-
-      const scored = entries
-        .map((entry) => ({
-          entry,
-          score: this._similarity(entry.contextSummary, ctx.summary),
-        }))
-        .sort((a, b) => b.score - a.score);
-
-      return scored.slice(0, k).filter((s) => s.score > 0.3).map((s) => s.entry);
-    } catch {
-      return [];
-    }
-  }
-
-  summarizeDecisions(maxEntries: number = 5): string {
-    try {
-      const content = readFileSync(join(this.dir, 'decisions.md'), 'utf8');
-      const lines = content.trim().split('\n').filter(Boolean);
-
-      const entries: DecisionEntry[] = [];
-      for (const line of lines.slice(-maxEntries * 2)) {
-        try {
-          entries.push(JSON.parse(line));
-        } catch {
-        }
-      }
-
-      return entries
-        .slice(-maxEntries)
-        .map(
-          (e) =>
-            `迭代 ${e.iteration}（${e.phase}）: 在 [${e.options.join(', ')}] 中选择了 **${e.chosen}**，原因：${e.reasoning.slice(0, 80)}`,
-        )
-        .join('\n');
-    } catch {
-      return '(无决策记录)';
-    }
-  }
-
-  composeContext(iteration: number): string {
-    const sections: string[] = [];
-
-    sections.push(`# 不可变目标 (IMMUTABLE GOAL)\n${this.goal}\n⚠️ 注意：你不能修改或扩大上述目标。如果你认为目标本身有问题，请输出 <PROMISE>NEED_GOAL_REVISION</PROMISE> 并停止。`);
-
-    sections.push(`# 当前阶段: ${this.currentPhase.toUpperCase()}`);
-
-    const lrn = this.learnings;
-    if (lrn) {
-      sections.push(`# 关键教训（必须遵守，避免重复踩坑）\n${lrn}`);
-    }
-
-    const decisions = this.summarizeDecisions(3);
-    if (decisions !== '(无决策记录)') {
-      sections.push(`# 历史关键决策（请参考，避免重复试错）\n${decisions}`);
-    }
-
-    const recentProgress = this.tailProgress(10);
-    if (recentProgress) {
-      sections.push(`# 最近进度\n${recentProgress}`);
-    }
-
-    sections.push(`---\n\n# 本轮任务 (迭代 ${iteration})`);
-
-    return sections.join('\n\n---\n\n');
-  }
-
-  async cleanup(): Promise<void> {
-    const files = ['goal.md', 'completion.md', 'phase.md', 'progress.md', 'learnings.md', 'decisions.md'];
-    for (const f of files) {
-      try {
-        await unlink(join(this.dir, f));
-      } catch {
-      }
-    }
-    try {
-      await rmdir(this.dir);
-    } catch {
-    }
-  }
-
-  private _similarity(a: string, b: string): number {
-    if (!a || !b) return 0;
-    const wordsA = new Set(a.toLowerCase().split(/\s+/));
-    const wordsB = new Set(b.toLowerCase().split(/\s+/));
-    let intersection = 0;
-    for (const word of wordsA) {
-      if (wordsB.has(word)) intersection++;
-    }
-    const union = new Set([...wordsA, ...wordsB]).size;
-    return union > 0 ? intersection / union : 0;
-  }
-}

package/plugins/ralph-wiggum/src/stopHookRunner.ts

@@ -1,136 +0,0 @@
-/**
- * ============================================================
- *  plugins/ralph-wiggum/src/stopHookRunner.ts
- * ------------------------------------------------------------
- *  ralph-wiggum 私用的 stop-hook 执行器。读 hooks/hooks.json 里 Stop 事件
- *  的命令清单，stdin 传 transcript 文本，stdout 收 JSON 决策。
- *
- *  在 minimal-agent 里 stop-hook 是"咨询式"信号：
- *    - 返回 block → driver 把 reason 注入下一轮 prompt
- *    - pass / 错误 / Windows 缺 bash → 不影响循环继续
- *
- *  与框架级 hookEngine 的关系：hookEngine 服务于 UserPromptSubmit /
- *  PreToolUse / PostToolUse 等框架事件；ralph 的 Stop 是插件领域内
- *  特有的循环-反馈机制，故而独立执行，不污染框架 hookTable。
- * ============================================================
- */
-
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { spawn } from 'node:child_process';
-
-export interface StopHookResult {
-  decision: 'block' | 'pass';
-  reason?: string;
-  systemMessage?: string;
-}
-
-interface HookConfig {
-  type: string;
-  command: string;
-}
-
-async function loadStopHookConfig(pluginRoot: string): Promise<HookConfig[]> {
-  const hooksJsonPath = join(pluginRoot, 'hooks', 'hooks.json');
-
-  try {
-    const raw = await readFile(hooksJsonPath, 'utf8');
-    const parsed = JSON.parse(raw);
-    const stopEntries = parsed?.hooks?.Stop;
-    if (!Array.isArray(stopEntries)) return [];
-
-    const commands: HookConfig[] = [];
-    for (const entry of stopEntries) {
-      const hooks = entry.hooks;
-      if (Array.isArray(hooks)) {
-        for (const h of hooks) {
-          if (h.type === 'command' && h.command) {
-            commands.push(h);
-          }
-        }
-      }
-    }
-    return commands;
-  } catch {
-    return [];
-  }
-}
-
-export async function executeStopHook(
-  pluginRoot: string,
-  transcriptText: string,
-): Promise<StopHookResult> {
-  // Windows 上 bash 通常缺失，hook 链路降级为 pass（咨询式信号不影响循环）
-  if (process.platform === 'win32') {
-    return { decision: 'pass' };
-  }
-
-  const hookConfigs = await loadStopHookConfig(pluginRoot);
-  for (const hookConfig of hookConfigs) {
-    const result = await runSingleStopHook(hookConfig, pluginRoot, transcriptText);
-    if (result.decision === 'block') {
-      return result;
-    }
-  }
-  return { decision: 'pass' };
-}
-
-function runSingleStopHook(
-  hookConfig: HookConfig,
-  pluginRoot: string,
-  transcriptText: string,
-): Promise<StopHookResult> {
-  const resolvedCommand = hookConfig.command.replaceAll(
-    '${CLAUDE_PLUGIN_ROOT}',
-    pluginRoot,
-  );
-
-  return new Promise((resolve) => {
-    const child = spawn('bash', [resolvedCommand], {
-      env: {
-        ...process.env,
-        CLAUDE_PLUGIN_ROOT: pluginRoot,
-      },
-    });
-
-    let stdout = '';
-
-    child.stdout.on('data', (data: Buffer) => {
-      stdout += data.toString();
-    });
-
-    child.on('error', () => {
-      resolve({ decision: 'pass' });
-    });
-
-    child.on('close', (code) => {
-      if (code !== 0) {
-        resolve({ decision: 'pass' });
-        return;
-      }
-      const trimmed = stdout.trim();
-      if (!trimmed) {
-        resolve({ decision: 'pass' });
-        return;
-      }
-      try {
-        const parsed = JSON.parse(trimmed);
-        if (parsed.decision === 'block') {
-          resolve({
-            decision: 'block',
-            reason: typeof parsed.reason === 'string' ? parsed.reason : undefined,
-            systemMessage:
-              typeof parsed.systemMessage === 'string' ? parsed.systemMessage : undefined,
-          });
-          return;
-        }
-        resolve({ decision: 'pass' });
-      } catch {
-        resolve({ decision: 'pass' });
-      }
-    });
-
-    child.stdin.write(transcriptText);
-    child.stdin.end();
-  });
-}

package/plugins/ralph-wiggum/src/verificationGate.ts

@@ -1,252 +0,0 @@
-/**
- * ============================================================
- *  src/plugins/verificationGate.ts —— ralph-loop 的"完成验证门"
- * ------------------------------------------------------------
- *  Agent 输出 <promise>DONE</promise> 哨兵后，pluginRunner 跑这里的
- *  checks。全部通过才真正退出循环；任一未通过则回 BUILD 继续干。
- *
- *  支持四种 check：
- *    - shell:<cmd>                跨平台 spawn（Windows 走 cmd /c, 其余 bash -c）
- *    - file_exists:<path>         fs.existsSync
- *    - file_contains:<file>:<re>  正则匹配文件内容
- *    - test_count:<min>           跑 `bun test`，从 stdout 解析 "N pass"
- *
- *  工作目录隔离：所有相对路径以 getWorkingDir() 为锚，子进程 cwd 也用它，
- *  确保并行 session 不会互相串台。
- * ============================================================
- */
-
-import { existsSync, readFileSync } from 'node:fs';
-import { spawn } from 'node:child_process';
-
-export interface Check {
-  type: 'shell' | 'file_contains' | 'file_exists' | 'test_count';
-  command?: string;
-  file?: string;
-  pattern?: string;
-  minCount?: number;
-  timeout?: number;
-}
-
-export interface CheckResult {
-  check: Check;
-  passed: boolean;
-  output: string;
-}
-
-export interface VerifyResult {
-  passed: boolean;
-  details: CheckResult[];
-  summary: string;
-}
-
-function parseVerifyArg(arg: string): Check | null {
-  const colonIdx = arg.indexOf(':');
-  if (colonIdx < 0) return null;
-
-  const type = arg.slice(0, colonIdx).trim().toLowerCase();
-  const value = arg.slice(colonIdx + 1).trim();
-
-  switch (type) {
-    case 'shell':
-      return { type: 'shell', command: value, timeout: 30_000 };
-    case 'file_exists':
-      return { type: 'file_exists', file: value };
-    case 'file_contains': {
-      const sep = value.indexOf(':');
-      if (sep < 0) return null;
-      return {
-        type: 'file_contains',
-        file: value.slice(0, sep),
-        pattern: value.slice(sep + 1),
-      };
-    }
-    case 'test_count': {
-      const count = parseInt(value, 10);
-      if (isNaN(count) || count < 0) return null;
-      return { type: 'test_count', minCount: count };
-    }
-    default:
-      return null;
-  }
-}
-
-export function parseVerifyArgs(args: string): Check[] {
-  const checks: Check[] = [];
-  const regex = /--verify\s+("[^"]*"|\S+)/gi;
-  let match;
-
-  while ((match = regex.exec(args)) !== null) {
-    const raw = match[1].replace(/^"|"$/g, '');
-    const check = parseVerifyArg(raw);
-    if (check) checks.push(check);
-  }
-
-  return checks;
-}
-
-interface ShellRunResult {
-  exitCode: number | null;
-  stdout: string;
-  stderr: string;
-  errored: boolean;
-}
-
-function runShell(command: string, timeout: number): Promise<ShellRunResult> {
-  return new Promise((resolve) => {
-    const isWin = process.platform === 'win32';
-    // 不显式传 cwd —— 继承 process.cwd()，main.tsx 已 chdir 到 workingDir，
-    // 而测试里直接用 process.cwd()，避免依赖 mock 的 getWorkingDir 造成串台
-    const child = isWin
-      ? spawn('cmd', ['/c', command], { timeout, env: process.env })
-      : spawn('bash', ['-c', command], { timeout, env: process.env });
-
-    let stdout = '';
-    let stderr = '';
-
-    child.stdout.on('data', (d: Buffer) => {
-      stdout += d.toString();
-    });
-    child.stderr.on('data', (d: Buffer) => {
-      stderr += d.toString();
-    });
-
-    child.on('error', () => {
-      resolve({ exitCode: null, stdout, stderr, errored: true });
-    });
-
-    child.on('close', (code) => {
-      resolve({ exitCode: code, stdout, stderr, errored: false });
-    });
-  });
-}
-
-export async function verifyShell(command: string, timeout: number): Promise<CheckResult> {
-  const r = await runShell(command, timeout);
-  if (r.errored) {
-    return {
-      check: { type: 'shell', command },
-      passed: false,
-      output: `执行失败`,
-    };
-  }
-  return {
-    check: { type: 'shell', command },
-    passed: r.exitCode === 0,
-    output: r.stdout.trim() || r.stderr.trim() || `exit code ${r.exitCode}`,
-  };
-}
-
-export function verifyFileExists(file: string): CheckResult {
-  const exists = existsSync(file);
-  return {
-    check: { type: 'file_exists', file },
-    passed: exists,
-    output: exists ? '文件存在' : `文件不存在: ${file}`,
-  };
-}
-
-export function verifyFileContains(file: string, pattern: string): CheckResult {
-  try {
-    const content = readFileSync(file, 'utf8');
-    const regex = new RegExp(pattern);
-    const matched = regex.test(content);
-
-    return {
-      check: { type: 'file_contains', file, pattern },
-      passed: matched,
-      output: matched ? `文件包含 "${pattern}"` : `文件不包含 "${pattern}"`,
-    };
-  } catch {
-    return {
-      check: { type: 'file_contains', file, pattern },
-      passed: false,
-      output: `无法读取文件: ${file}`,
-    };
-  }
-}
-
-async function verifyTestCount(minCount: number): Promise<CheckResult> {
-  const r = await runShell(`bun test`, 60_000);
-  // bun test 把进度打在 stderr，最终统计也常在 stderr，所以合并解析
-  const combined = `${r.stdout}\n${r.stderr}`;
-  if (r.errored) {
-    return {
-      check: { type: 'test_count', minCount },
-      passed: false,
-      output: '无法执行 bun test',
-    };
-  }
-
-  const matches = [...combined.matchAll(/(\d+)\s+pass/gi)];
-  const count = matches.length > 0 ? parseInt(matches[matches.length - 1][1], 10) : 0;
-  const passed = count >= minCount;
-
-  return {
-    check: { type: 'test_count', minCount },
-    passed,
-    output: `${count} pass (需要 >=${minCount})`,
-  };
-}
-
-export async function runVerification(checks: Check[]): Promise<VerifyResult> {
-  if (checks.length === 0) {
-    return { passed: true, details: [], summary: '无验证项' };
-  }
-
-  const results: CheckResult[] = [];
-
-  for (const check of checks) {
-    let result: CheckResult;
-
-    switch (check.type) {
-      case 'shell':
-        result = await verifyShell(check.command ?? '', check.timeout ?? 30_000);
-        break;
-      case 'file_exists':
-        result = verifyFileExists(check.file ?? '');
-        break;
-      case 'file_contains':
-        result = verifyFileContains(check.file ?? '', check.pattern ?? '');
-        break;
-      case 'test_count':
-        result = await verifyTestCount(check.minCount ?? 0);
-        break;
-      default:
-        result = {
-          check,
-          passed: false,
-          output: `未知验证类型: ${(check as { type: string }).type}`,
-        };
-    }
-
-    results.push(result);
-  }
-
-  const allPassed = results.every((r) => r.passed);
-  const failedNames = results.filter((r) => !r.passed).map((r) => formatCheckName(r.check));
-
-  let summary: string;
-  if (allPassed) {
-    summary = `✅ 全部通过 (${results.length}/${results.length})`;
-  } else {
-    summary = `❌ 验证未通过: ${failedNames.join(', ')}`;
-  }
-
-  return { passed: allPassed, details: results, summary };
-}
-
-function formatCheckName(check: Check): string {
-  switch (check.type) {
-    case 'shell':
-      return `shell(${(check.command ?? '').slice(0, 40)})`;
-    case 'file_exists':
-      return `exists(${check.file})`;
-    case 'file_contains':
-      return `contains(${check.file}:${check.pattern})`;
-    case 'test_count':
-      return `tests(>=${check.minCount})`;
-    default:
-      return check.type;
-  }
-}