minimal-agent 0.1.9 → 0.3.0

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

@@ -0,0 +1,260 @@
+import { mkdir, appendFile, writeFile, unlink, rmdir } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export var Phase;
+(function (Phase) {
+    Phase["PLAN"] = "plan";
+    Phase["BUILD"] = "build";
+    Phase["VERIFY"] = "verify";
+    Phase["HEAL"] = "heal";
+    Phase["DONE"] = "done";
+})(Phase || (Phase = {}));
+const VALID_PHASES = new Set(Object.values(Phase));
+const PHASE_TRANSITIONS = {
+    [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, to) {
+    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 {
+    dir;
+    constructor(workspaceDir, sessionTag) {
+        const suffix = sessionTag ? `-${sessionTag}` : '';
+        this.dir = join(workspaceDir, `.minimal-agent${suffix}`);
+    }
+    async reset() {
+        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, criteria) {
+        await mkdir(this.dir, { recursive: true });
+        const files = {
+            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() {
+        try {
+            return readFileSync(join(this.dir, 'goal.md'), 'utf8').trim();
+        }
+        catch {
+            return '';
+        }
+    }
+    get completionCriteria() {
+        try {
+            const raw = readFileSync(join(this.dir, 'completion.md'), 'utf8').trim();
+            return JSON.parse(raw);
+        }
+        catch {
+            return [];
+        }
+    }
+    get currentPhase() {
+        try {
+            const raw = readFileSync(join(this.dir, 'phase.md'), 'utf8').trim();
+            if (VALID_PHASES.has(raw)) {
+                return raw;
+            }
+        }
+        catch {
+        }
+        return Phase.PLAN;
+    }
+    /**
+     * 切换阶段。`reason` 是给人看的日志文本，不参与校验。
+     * 校验只看 from→to 是否在 PHASE_TRANSITIONS 表里有路径（任意 event 通向 to 即合法）。
+     * 想绕开 FSM 用 forceSetPhase。
+     */
+    async setPhase(phase, reason) {
+        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, reason) {
+        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) {
+        const timestamp = new Date().toLocaleTimeString('en-US', { hour12: false });
+        await appendFile(join(this.dir, 'progress.md'), `[${timestamp}] ${line}\n`);
+    }
+    tailProgress(n) {
+        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) {
+        await appendFile(join(this.dir, 'learnings.md'), `- ${lesson}\n`);
+    }
+    get learnings() {
+        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, options, chosen, reasoning) {
+        const entry = {
+            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, k = 3) {
+        try {
+            const content = readFileSync(join(this.dir, 'decisions.md'), 'utf8');
+            const lines = content.trim().split('\n').filter(Boolean);
+            const entries = [];
+            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 = 5) {
+        try {
+            const content = readFileSync(join(this.dir, 'decisions.md'), 'utf8');
+            const lines = content.trim().split('\n').filter(Boolean);
+            const entries = [];
+            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) {
+        const sections = [];
+        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() {
+        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 {
+        }
+    }
+    _similarity(a, b) {
+        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/sentinels.js

@@ -0,0 +1,21 @@
+/**
+ * ============================================================
+ *  plugins/ralph-wiggum/src/sentinels.ts —— LLM 输出哨兵正则
+ * ------------------------------------------------------------
+ *  Ralph 通过"输出特定标签"与 driver 交流：
+ *    <promise>DONE</promise> / <promise>COMPLETE</promise> / <promise>GOAL_COMPLETE</promise>
+ *      → 表示当前轮 LLM 认为目标完成，driver 进入验证门
+ *    <PROMISE>NEED_REPLAN</PROMISE>
+ *      → 表示当前方案不可行，driver 强转回 PLAN 阶段
+ *
+ *  哨兵集中在这里方便审计与扩展；正则全部 case-insensitive。
+ * ============================================================
+ */
+const COMPLETE_RE = /<promise>(?:COMPLETE|DONE|GOAL_COMPLETE)<\/promise>/i;
+const NEED_REPLAN_RE = /<PROMISE>NEED_REPLAN<\/PROMISE>/i;
+export function hasCompleteSentinel(text) {
+    return COMPLETE_RE.test(text);
+}
+export function hasNeedReplanSentinel(text) {
+    return NEED_REPLAN_RE.test(text);
+}

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

@@ -0,0 +1,104 @@
+/**
+ * ============================================================
+ *  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';
+async function loadStopHookConfig(pluginRoot) {
+    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 = [];
+        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, transcriptText) {
+    // 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, pluginRoot, transcriptText) {
+    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) => {
+            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.js

@@ -0,0 +1,202 @@
+/**
+ * ============================================================
+ *  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';
+function parseVerifyArg(arg) {
+    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) {
+    const checks = [];
+    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;
+}
+function runShell(command, timeout) {
+    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) => {
+            stdout += d.toString();
+        });
+        child.stderr.on('data', (d) => {
+            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, timeout) {
+    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) {
+    const exists = existsSync(file);
+    return {
+        check: { type: 'file_exists', file },
+        passed: exists,
+        output: exists ? '文件存在' : `文件不存在: ${file}`,
+    };
+}
+export function verifyFileContains(file, pattern) {
+    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) {
+    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) {
+    if (checks.length === 0) {
+        return { passed: true, details: [], summary: '无验证项' };
+    }
+    const results = [];
+    for (const check of checks) {
+        let result;
+        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.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;
+    if (allPassed) {
+        summary = `✅ 全部通过 (${results.length}/${results.length})`;
+    }
+    else {
+        summary = `❌ 验证未通过: ${failedNames.join(', ')}`;
+    }
+    return { passed: allPassed, details: results, summary };
+}
+function formatCheckName(check) {
+    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;
+    }
+}

package/plugins/workflow-runner/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "workflow-runner",
+  "version": "0.1.0",
+  "description": "YAML workflow DAG executor for minimal-agent. Provides /workflow and /workflows commands."
+}

package/plugins/workflow-runner/commands/workflow.md

@@ -0,0 +1,15 @@
+---
+description: 运行 YAML 工作流（DAG 执行器），用 --input k=v 传参
+argument-hint: <name> [--input key=value ...]
+---
+
+# /workflow
+
+本命令由 workflow-runner 插件接管（plugin.ts.runCommand），不会把 prompt 喂给 LLM。
+直接调用插件内置的 YAML DAG 执行器，按 steps 顺序运行 tool / llm / assert / branch / loop 等节点。
+
+用法示例：
+
+  /workflow hello-workflow --input name=alice --input lang=zh
+
+输入 /workflows 查看可用工作流列表。

package/plugins/workflow-runner/commands/workflows.md

@@ -0,0 +1,8 @@
+---
+description: 列出当前 cwd 与插件包内可用的 YAML 工作流
+---
+
+# /workflows
+
+由 workflow-runner 插件接管（plugin.ts.runCommand），扫描 cwd/workflows/ 与
+plugin 自带 examples/ 下的 *.yaml，把名称 + 一行描述列出来。

package/plugins/workflow-runner/plugin.js

@@ -0,0 +1,36 @@
+/**
+ * ============================================================
+ *  plugins/workflow-runner/plugin.ts
+ * ------------------------------------------------------------
+ *  workflow-runner 插件入口。接管 /workflow 与 /workflows 两个命令的执行：
+ *  不走声明式 markdown→LLM 通道，而是直接调插件内置的 YAML DAG 执行器。
+ *
+ *  执行器与全部依赖都住在本插件目录 ./src/，外部 src/ 一行不改。
+ *  插件只通过 src/plugin-sdk.ts 取框架运行时（runQuery / chat / executeTool 等）。
+ *
+ *  契约：default export 一个 PluginApi 对象。框架 pluginLoader 会按 pluginRoot
+ *  缓存这次 import，所以 cold start 后 dynamic import 只跑一次。
+ * ============================================================
+ */
+import { runWorkflowFromCommand, runWorkflowsList } from './src/index.js';
+const api = {
+    async *runCommand(commandName, args, ctx) {
+        if (commandName === 'workflows') {
+            yield* runWorkflowsList();
+            return;
+        }
+        if (commandName === 'workflow') {
+            yield* runWorkflowFromCommand(args, {
+                provider: ctx.provider,
+                history: ctx.history,
+                signal: ctx.signal,
+            });
+            return;
+        }
+        yield {
+            type: 'error',
+            error: `workflow-runner: 未知命令 /${commandName}`,
+        };
+    },
+};
+export default api;