minimal-agent 0.1.8 → 0.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "minimal-agent",
-  "version": "0.1.8",
-  "description": "最小化 Agent 系统 —— 单对话 + 10 工具 + MultiEdit + Pre-read Guard + 自动压缩 + OpenAI 兼容 + Ink TUI",
+  "version": "0.2.0",
+  "description": "最小化 Agent 系统 —— 单对话 + 10 工具 + 插件系统 + workflow DSL + 自动压缩 + OpenAI 兼容 + Ink TUI（学习/教学用）",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Bill Wang <leiwang0359@gmail.com>",
   "repository": {
@@ -37,6 +37,8 @@
     "dist",
     "vendor/ripgrep",
     "skills",
+    "plugins",
+    "workflows",
     "README.md",
     "LICENSE"
   ],
@@ -53,6 +55,7 @@
     "ink": "^5.0.1",
     "react": "^18.3.1",
     "turndown": "^7.2.4",
+    "yaml": "^2.9.0",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.25.2"
   },

package/plugins/HOW-TO-WRITE-A-PLUGIN.md

@@ -0,0 +1,186 @@
+# How to Write a minimal-agent Plugin
+
+minimal-agent 的插件系统遵循 **drop-in** 原则：把目录扔进 `plugins/`，命令立即可用，**`src/` 一行不改**。
+
+## 两种契约
+
+### 1. 纯声明式（Anthropic 兼容，零 TS）
+
+最小可用插件 = 一个 frontmatter 模板。框架替你拼 prompt 喂给 LLM。
+
+```
+plugins/hello-bot/
+├── .claude-plugin/
+│   └── plugin.json
+└── commands/
+    └── hi.md
+```
+
+**`.claude-plugin/plugin.json`**
+
+```json
+{
+  "name": "hello-bot",
+  "version": "0.1.0",
+  "description": "Greets the user"
+}
+```
+
+**`commands/hi.md`**
+
+```markdown
+---
+description: "Greet the user"
+argument-hint: "<name>"
+---
+
+你好 $ARGUMENTS！欢迎使用 minimal-agent。
+```
+
+**效果**：用户输入 `/hi 世界` → LLM 收到 `你好 世界！欢迎使用 minimal-agent。\n\n用户参数: 世界`。
+
+支持的占位符：
+- `$ARGUMENTS` / `${ARGUMENTS}` —— 用户在命令名后的全部文本
+- `${CLAUDE_PLUGIN_ROOT}` —— 该插件目录的绝对路径（用于引用插件资源）
+
+### 2. 声明式 + `plugin.ts`（富插件）
+
+当模板不够（要跑循环 / 做 TS 校验 / 启动子进程 / 状态机），加一个 `plugin.ts`：
+
+```
+plugins/echo-bot/
+├── .claude-plugin/plugin.json
+├── commands/echo.md         # 仍要存在！frontmatter 用于 listAvailableCommands
+└── plugin.ts                # PluginApi default export
+```
+
+**`plugin.ts`**
+
+```typescript
+import {
+  runQuery,
+  type PluginApi,
+  type LoopEvent,
+} from '../../src/plugin-sdk.ts';
+
+const api: PluginApi = {
+  async *runCommand(commandName, args, ctx): AsyncGenerator<LoopEvent> {
+    if (commandName === 'echo') {
+      // 直接 yield 自定义事件
+      yield { type: 'text', delta: `你输入了：${args}` };
+      yield { type: 'turn_done' };
+      return;
+    }
+
+    // 或者改写 prompt 后丢给 LLM
+    yield* runQuery(`请把以下内容重复 3 遍：${args}`, {
+      provider: ctx.provider,
+      history: ctx.history,
+      signal: ctx.signal,
+    });
+  },
+};
+
+export default api;
+```
+
+**框架行为**：命中 `/echo abc` 时，`pluginRunner` 优先调用 `runCommand('echo', 'abc', ctx)`，不再走声明式 fallback。你完全接管事件流。
+
+## `plugin-sdk.ts` 暴露的全部 API
+
+**唯一稳定 import 路径**：`from '../../src/plugin-sdk.ts'`（相对你的 `plugin.ts`）。
+
+| 名称 | 类型 | 用途 |
+|------|------|------|
+| `runQuery(input, opts)` | function | 标准 T-A-O-R 循环，AsyncGenerator |
+| `chat(messages, provider, opts)` | function | 单次非流式 LLM 调用 |
+| `executeTool(name, argsJson, ctx)` | function | 框架级工具调用入口 |
+| `getToolByName(name)` | function | 取 Tool 定义 |
+| `ALL_TOOLS` | const | 所有内置工具数组 |
+| `getWorkingDir()` | function | 当前锁定的工作目录 |
+| `getResourceSearchPaths(name, importMetaUrl)` | function | 双源资源路径（cwd + packageRoot） |
+| `triggerHook(event, payload)` | function | 触发框架级 hook |
+| `createSessionState()` | function | 新建 SessionState |
+| `Message` / `Provider` / `LoopEvent` / `LlmStreamEvent` | type | 协议类型 |
+| `Tool` / `ToolCall` / `ToolResult` | type | 工具协议类型 |
+| `PluginApi` / `PluginContext` | type | 你的 plugin.ts 契约 |
+| `ResourceName` / `HookEventName` / `HookDecision` / `SessionState` | type | 杂项 |
+
+**不要**绕开 `plugin-sdk.ts` 直接 import `src/loop.ts` / `src/llm/client.ts` 等内部路径 —— 那些路径不是稳定 API，框架重构时会破坏你的插件。
+
+## `PluginContext`
+
+`runCommand` 收到的 ctx：
+
+```typescript
+interface PluginContext {
+  provider: Provider;          // 当前 LLM provider 配置
+  history: Message[];          // 对话历史（你可以读 / 修改 / 替换）
+  signal?: AbortSignal;        // 用户 ESC / Ctrl+C 时触发
+  sessionState?: SessionState; // 可选共享 session 状态
+  maxTurns?: number;           // 工具循环最大轮数（runQuery 透传用）
+}
+```
+
+## 事件 (`LoopEvent`)
+
+你的 `runCommand` 必须 yield `LoopEvent`，UI 据此渲染。常用的有：
+
+| type | 字段 | 用途 |
+|------|------|------|
+| `text` | `delta: string` | 流式文本片段 |
+| `assistant_message` | (无) | 一次完整 assistant 消息已 push 进 history |
+| `tool_start` | `toolName`, `argsPreview` | 工具开始执行 |
+| `tool_end` | (无) | 工具结束 |
+| `turn_done` | (无) | 整轮交互结束 |
+| `interrupted` | (无) | 用户中断 |
+| `error` | `error: string` | 红色错误提示 |
+| `plugin_progress` | `pluginId`, `current`, `max?`, `message?` | 循环进度条（替代旧的 plugin_start / plugin_iteration） |
+
+通常做法：复杂插件直接 `yield* runQuery(...)` 透传所有事件，自己额外 yield `plugin_progress` 做进度展示。
+
+## 工作目录与持久化
+
+- 状态写到 `getWorkingDir()/.minimal-agent-<your-plugin-id>/` 下，避免污染主 context 目录
+- `/new` 命令会自动清这些 `.minimal-agent*` 目录，你不用管 cleanup
+- 跨平台：Windows 没 bash，hooks/*.sh 静默跳过；其它 .ts 代码完全平台无关
+
+## 命令默认值
+
+框架**不再**注入命令默认参数（旧版 `COMMAND_DEFAULTS` 已删除）。如果你的命令需要默认值（如 `--max-iterations 50`），自己在 `plugin.ts` 里解析 args 时兜底。这样默认值的语义属于插件契约，不属于框架。
+
+## 测试
+
+- 把测试放在 `plugins/<id>/test/*.test.ts`
+- `bunfig.toml` 的 `[test].root = ["./test", "./plugins"]` 让 `bun test` 自动发现
+- 测试里 mock LLM / 工具时，用 `mock.module('../../../src/loop.ts', ...)` 等绝对到 src 的相对路径
+
+## 参考实现
+
+- **声明式 + plugin.ts 简单例**：`plugins/workflow-runner/plugin.ts`（~25 行接管 `/workflow` 与 `/workflows`）
+- **重型循环例**：`plugins/ralph-wiggum/plugin.ts`（~270 行 do-while loop + FSM + sentinel + verification + stop-hook）
+
+## Transcript 与 Hook：当前状态
+
+框架提供了两套基础设施 —— 都**就绪、有测试、可独立调用**，但**主循环 `src/loop.ts` 不自动触发**：
+
+| 模块 | 暴露 | 当前主循环触发？ |
+|------|------|------|
+| `src/plugins/transcript.ts` | `initTranscript / appendUserMessage / appendAssistantMessage / appendToolResult` | 否 |
+| `src/plugins/hookEngine.ts` | `loadHooks / triggerHook('UserPromptSubmit' \| 'PreToolUse' \| 'PostToolUse' \| 'SessionStart' \| 'SessionEnd', payload)` | 否 |
+
+**插件如何使用**：
+- 想写自己的 JSONL transcript → 在 `runCommand` 内 `import { initTranscript, appendUserMessage } from '../../src/plugin-sdk.ts'` 自己调
+- 想响应 hook 事件 → 在 `runCommand` 内 `triggerHook('PreToolUse', { tool_name, ... })` 自己调；ralph-wiggum 走的就是这条路（vendored stop-hook 执行器在 `plugins/ralph-wiggum/src/stopHookRunner.ts`）
+
+**为什么不在主循环自动触发**：当前没有 Anthropic 风格 `hooks/*.sh` 的真实用例驱动；自动触发会改主循环热路径但不解决实际问题。等真有跨插件的全局 hook 需求时再接也不迟。届时只需在 `src/loop.ts` 的 user/assistant/tool 三处 push 点加 `appendXxx` 与 `triggerHook` 调用即可，**不影响插件契约**。
+
+## 不支持的 Anthropic 字段
+
+minimal-agent 的插件契约是 Anthropic 上游的**子集**。当前未实现的字段：
+
+- `mcp-servers/` —— MCP 服务器配置
+- `agents/` —— 子 agent 定义
+- `skills/` 在插件目录下 —— minimal-agent 的 skill 系统是独立顶层目录
+
+未实现字段在 plugin.json 中存在不会报错，但被忽略。

package/plugins/ralph-wiggum/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "ralph-wiggum",
+  "version": "1.0.0",
+  "description": "Implementation of the Ralph Wiggum technique - continuous self-referential AI loops for interactive iterative development. Run Claude in a while-true loop with the same prompt until task completion.",
+  "author": {
+    "name": "Daisy Hollman",
+    "email": "daisy@anthropic.com"
+  }
+}

package/plugins/ralph-wiggum/README.md

@@ -0,0 +1,179 @@
+# Ralph Wiggum Plugin
+
+Implementation of the Ralph Wiggum technique for iterative, self-referential AI development loops in Minimal Agent.
+
+## What is Ralph?
+
+Ralph is a development methodology based on continuous AI agent loops. As Geoffrey Huntley describes it: **"Ralph is a Bash loop"** - a simple `while true` that repeatedly feeds an AI agent a prompt file, allowing it to iteratively improve its work until completion.
+
+The technique is named after Ralph Wiggum from The Simpsons, embodying the philosophy of persistent iteration despite setbacks.
+
+### Core Concept
+
+This plugin implements Ralph using a **Stop hook** that intercepts Minimal Agent's exit attempts:
+
+```bash
+# You run ONCE:
+/ralph-loop "Your task description" --completion-promise "DONE"
+
+# Then Claude Code automatically:
+# 1. Works on the task
+# 2. Tries to exit
+# 3. Stop hook blocks exit
+# 4. Stop hook feeds the SAME prompt back
+# 5. Repeat until completion
+```
+
+The loop happens **inside your current session** - you don't need external bash loops. The Stop hook in `hooks/stop-hook.sh` creates the self-referential feedback loop by blocking normal session exit.
+
+This creates a **self-referential feedback loop** where:
+- The prompt never changes between iterations
+- Claude's previous work persists in files
+- Each iteration sees modified files and git history
+- Claude autonomously improves by reading its own past work in files
+
+## Quick Start
+
+```bash
+/ralph-loop "Build a REST API for todos. Requirements: CRUD operations, input validation, tests. Output <promise>COMPLETE</promise> when done." --completion-promise "COMPLETE" --max-iterations 50
+```
+
+Claude will:
+- Implement the API iteratively
+- Run tests and see failures
+- Fix bugs based on test output
+- Iterate until all requirements met
+- Output the completion promise when done
+
+## Commands
+
+### /ralph-loop
+
+Start a Ralph loop in your current session.
+
+**Usage:**
+```bash
+/ralph-loop "<prompt>" --max-iterations <n> --completion-promise "<text>"
+```
+
+**Options:**
+- `--max-iterations <n>` - Stop after N iterations (default: unlimited)
+- `--completion-promise <text>` - Phrase that signals completion
+
+### /cancel-ralph
+
+Cancel the active Ralph loop.
+
+**Usage:**
+```bash
+/cancel-ralph
+```
+
+## Prompt Writing Best Practices
+
+### 1. Clear Completion Criteria
+
+❌ Bad: "Build a todo API and make it good."
+
+✅ Good:
+```markdown
+Build a REST API for todos.
+
+When complete:
+- All CRUD endpoints working
+- Input validation in place
+- Tests passing (coverage > 80%)
+- README with API docs
+- Output: <promise>COMPLETE</promise>
+```
+
+### 2. Incremental Goals
+
+❌ Bad: "Create a complete e-commerce platform."
+
+✅ Good:
+```markdown
+Phase 1: User authentication (JWT, tests)
+Phase 2: Product catalog (list/search, tests)
+Phase 3: Shopping cart (add/remove, tests)
+
+Output <promise>COMPLETE</promise> when all phases done.
+```
+
+### 3. Self-Correction
+
+❌ Bad: "Write code for feature X."
+
+✅ Good:
+```markdown
+Implement feature X following TDD:
+1. Write failing tests
+2. Implement feature
+3. Run tests
+4. If any fail, debug and fix
+5. Refactor if needed
+6. Repeat until all green
+7. Output: <promise>COMPLETE</promise>
+```
+
+### 4. Escape Hatches
+
+Always use `--max-iterations` as a safety net to prevent infinite loops on impossible tasks:
+
+```bash
+# Recommended: Always set a reasonable iteration limit
+/ralph-loop "Try to implement feature X" --max-iterations 20
+
+# In your prompt, include what to do if stuck:
+# "After 15 iterations, if not complete:
+#  - Document what's blocking progress
+#  - List what was attempted
+#  - Suggest alternative approaches"
+```
+
+**Note**: The `--completion-promise` uses exact string matching, so you cannot use it for multiple completion conditions (like "SUCCESS" vs "BLOCKED"). Always rely on `--max-iterations` as your primary safety mechanism.
+
+## Philosophy
+
+Ralph embodies several key principles:
+
+### 1. Iteration > Perfection
+Don't aim for perfect on first try. Let the loop refine the work.
+
+### 2. Failures Are Data
+"Deterministically bad" means failures are predictable and informative. Use them to tune prompts.
+
+### 3. Operator Skill Matters
+Success depends on writing good prompts, not just having a good model.
+
+### 4. Persistence Wins
+Keep trying until success. The loop handles retry logic automatically.
+
+## When to Use Ralph
+
+**Good for:**
+- Well-defined tasks with clear success criteria
+- Tasks requiring iteration and refinement (e.g., getting tests to pass)
+- Greenfield projects where you can walk away
+- Tasks with automatic verification (tests, linters)
+
+**Not good for:**
+- Tasks requiring human judgment or design decisions
+- One-shot operations
+- Tasks with unclear success criteria
+- Production debugging (use targeted debugging instead)
+
+## Real-World Results
+
+- Successfully generated 6 repositories overnight in Y Combinator hackathon testing
+- One $50k contract completed for $297 in API costs
+- Created entire programming language ("cursed") over 3 months using this approach
+
+## Learn More
+
+- Original technique: https://ghuntley.com/ralph/
+- Ralph Orchestrator: https://github.com/mikeyobrien/ralph-orchestrator
+
+## For Help
+
+Run `/help` in Claude Code for detailed command reference and examples.

package/plugins/ralph-wiggum/commands/cancel-ralph.md

@@ -0,0 +1,18 @@
+---
+description: "Cancel active Ralph Wiggum loop"
+allowed-tools: ["Bash(test -f .minimal-agent/ralph-loop.local.md:*)", "Bash(rm .minimal-agent/ralph-loop.local.md)", "Read(.minimal-agent/ralph-loop.local.md)"]
+hide-from-slash-command-tool: "true"
+---
+
+# Cancel Ralph
+
+To cancel the Ralph loop:
+
+1. Check if `.minimal-agent/ralph-loop.local.md` exists using Bash: `test -f .minimal-agent/ralph-loop.local.md && echo "EXISTS" || echo "NOT_FOUND"`
+
+2. **If NOT_FOUND**: Say "No active Ralph loop found."
+
+3. **If EXISTS**:
+   - Read `.minimal-agent/ralph-loop.local.md` to get the current iteration number from the `iteration:` field
+   - Remove the file using Bash: `rm .minimal-agent/ralph-loop.local.md`
+   - Report: "Cancelled Ralph loop (was at iteration N)" where N is the iteration value

package/plugins/ralph-wiggum/commands/help.md

@@ -0,0 +1,126 @@
+---
+description: "Explain Ralph Wiggum technique and available commands"
+---
+
+# Ralph Wiggum Plugin Help
+
+Please explain the following to the user:
+
+## What is the Ralph Wiggum Technique?
+
+The Ralph Wiggum technique is an iterative development methodology based on continuous AI loops, pioneered by Geoffrey Huntley.
+
+**Core concept:**
+```bash
+while :; do
+  cat PROMPT.md | claude-code --continue
+done
+```
+
+The same prompt is fed to Claude repeatedly. The "self-referential" aspect comes from Claude seeing its own previous work in the files and git history, not from feeding output back as input.
+
+**Each iteration:**
+1. Claude receives the SAME prompt
+2. Works on the task, modifying files
+3. Tries to exit
+4. Stop hook intercepts and feeds the same prompt again
+5. Claude sees its previous work in the files
+6. Iteratively improves until completion
+
+The technique is described as "deterministically bad in an undeterministic world" - failures are predictable, enabling systematic improvement through prompt tuning.
+
+## Available Commands
+
+### /ralph-loop <PROMPT> [OPTIONS]
+
+Start a Ralph loop in your current session.
+
+**Usage:**
+```
+/ralph-loop "Refactor the cache layer" --max-iterations 20
+/ralph-loop "Add tests" --completion-promise "TESTS COMPLETE"
+```
+
+**Options:**
+- `--max-iterations <n>` - Max iterations before auto-stop
+- `--completion-promise <text>` - Promise phrase to signal completion
+
+**How it works:**
+1. Creates `.claude/.ralph-loop.local.md` state file
+2. You work on the task
+3. When you try to exit, stop hook intercepts
+4. Same prompt fed back
+5. You see your previous work
+6. Continues until promise detected or max iterations
+
+---
+
+### /cancel-ralph
+
+Cancel an active Ralph loop (removes the loop state file).
+
+**Usage:**
+```
+/cancel-ralph
+```
+
+**How it works:**
+- Checks for active loop state file
+- Removes `.claude/.ralph-loop.local.md`
+- Reports cancellation with iteration count
+
+---
+
+## Key Concepts
+
+### Completion Promises
+
+To signal completion, Claude must output a `<promise>` tag:
+
+```
+<promise>TASK COMPLETE</promise>
+```
+
+The stop hook looks for this specific tag. Without it (or `--max-iterations`), Ralph runs infinitely.
+
+### Self-Reference Mechanism
+
+The "loop" doesn't mean Claude talks to itself. It means:
+- Same prompt repeated
+- Claude's work persists in files
+- Each iteration sees previous attempts
+- Builds incrementally toward goal
+
+## Example
+
+### Interactive Bug Fix
+
+```
+/ralph-loop "Fix the token refresh logic in auth.ts. Output <promise>FIXED</promise> when all tests pass." --completion-promise "FIXED" --max-iterations 10
+```
+
+You'll see Ralph:
+- Attempt fixes
+- Run tests
+- See failures
+- Iterate on solution
+- In your current session
+
+## When to Use Ralph
+
+**Good for:**
+- Well-defined tasks with clear success criteria
+- Tasks requiring iteration and refinement
+- Iterative development with self-correction
+- Greenfield projects
+
+**Not good for:**
+- Tasks requiring human judgment or design decisions
+- One-shot operations
+- Tasks with unclear success criteria
+- Debugging production issues (use targeted debugging instead)
+
+## Learn More
+
+- Original technique: https://ghuntley.com/ralph/
+- Ralph Orchestrator: https://github.com/mikeyobrien/ralph-orchestrator

package/plugins/ralph-wiggum/commands/ralph-loop.md

@@ -0,0 +1,59 @@
+---
+description: "Start Ralph Wiggum loop in current session"
+argument-hint: "PROMPT [--max-iterations N] [--completion-promise TEXT]"
+allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh:*)"]
+hide-from-slash-command-tool: "true"
+---
+
+# Ralph Loop Command
+
+<!--
+  minimal-agent 注意：以下 ```! ``` 块是 Claude Code 专有的 shell-on-command
+  语法，minimal-agent **不会执行**它。GoalState 的初始化（goal.md / phase.md
+  / completion.md 等）由本插件的 plugin.ts 在进循环前自动完成，
+  不需要 setup 脚本。该块保留在这里只是为了与原版 Claude Code 兼容。
+-->
+
+Execute the setup script to initialize the Ralph loop:
+
+```!
+"${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh" $ARGUMENTS
+```
+
+Please work on the task. When you try to exit, the Ralph loop will feed the SAME PROMPT back to you for the next iteration. You'll see your previous work in files and git history, allowing you to iterate and improve.
+
+CRITICAL RULE: If a completion promise is set, you may ONLY output it when the statement is completely and unequivocally TRUE. Do not output false promises to escape the loop, even if you think you're stuck or should exit for other reasons. The loop is designed to continue until genuine completion.
+
+---
+
+## 本插件管理的状态文件
+
+`.minimal-agent-ralph-wiggum/` 目录下的所有文件（goal.md / phase.md / completion.md /
+progress.md / learnings.md / decisions.md）**由本插件自动创建并维护**，你不需要主动
+读写它们。每轮迭代开始时，插件会把当前目标、阶段、最近进度、关键决策、教训自动拼接到
+你的 prompt 头部（freshContext），你**专注按头部信息行动**即可。
+
+## 阶段工作流
+
+循环会自动管理阶段转换（PLAN → BUILD → VERIFY → HEAL → DONE），但你应主动配合当前阶段：
+
+- **PLAN 阶段**：分析任务、拆解步骤、识别风险
+- **BUILD 阶段**：按计划实现代码，每次聚焦一个子任务
+- **VERIFY 阶段**：运行测试、检查输出、验证功能
+- **HEAL 阶段**：定位问题根因、修复 bug、避免回归
+
+## 完成哨兵
+
+当且仅当任务真正完成时，输出：
+```
+<promise>DONE</promise>
+```
+
+如果发现方案根本不可行需要重新规划：
+```
+<PROMISE>NEED_REPLAN</PROMISE>
+```
+
+## 踩坑记录
+
+如果在工作中发现任何值得记录的教训（坑、陷阱、最佳实践），请明确说明，系统会自动记录到 `.minimal-agent/learnings.md` 供后续迭代参考。

package/plugins/ralph-wiggum/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "description": "Ralph Wiggum plugin stop hook for self-referential loops",
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/stop-hook.sh"
+          }
+        ]
+      }
+    ]
+  }
+}