minimal-agent 0.2.0 → 0.3.0

package/plugins/ralph-wiggum/plugin.ts

@@ -1,275 +0,0 @@
-/**
- * ============================================================
- *  plugins/ralph-wiggum/plugin.ts —— ralph-wiggum 真·插件入口
- * ------------------------------------------------------------
- *  把原 src/plugins/pluginRunner.ts 的 do-while 循环驱动整段搬来。
- *  对外通过 PluginApi.runCommand 暴露 /ralph-loop。
- *
- *  循环契约：
- *    - 每轮把 history 重置成进入循环前的快照（fresh context）
- *    - 用 GoalState.composeContext() 拼 PLAN/BUILD/VERIFY/HEAL 阶段信息
- *    - 跑 runQuery
- *    - 检测 <promise>DONE</promise> → runVerification → 通过则退出
- *    - 检测 <PROMISE>NEED_REPLAN</PROMISE> → forceSetPhase(PLAN)
- *    - executeStopHook 是咨询式：block 才把 reason 注入下一轮，pass 不退出
- *
- *  终止（独占）：sentinel + verify 通过 / 达 max-iterations / abort / 安全天花板
- *
- *  Windows 上 hooks/stop-hook.sh 不可用，但循环不依赖 hook，功能完整，
- *  只是 hook 的咨询通道失效。
- * ============================================================
- */
-
-import { fileURLToPath } from 'node:url';
-import { dirname } from 'node:path';
-
-import {
-  runQuery,
-  getWorkingDir,
-  type PluginApi,
-  type PluginContext,
-  type LoopEvent,
-  type Message,
-} from '../../src/plugin-sdk.ts';
-
-import { GoalState, Phase } from './src/goalState.ts';
-import { parseVerifyArgs, runVerification } from './src/verificationGate.ts';
-import {
-  hasCompleteSentinel,
-  hasNeedReplanSentinel,
-} from './src/sentinels.ts';
-import { executeStopHook } from './src/stopHookRunner.ts';
-
-const PLUGIN_NAME = 'ralph-wiggum';
-const DEFAULT_MAX_ITERATIONS = 50;
-const SAFETY_CEILING = 200;
-
-const PLUGIN_ROOT = dirname(fileURLToPath(import.meta.url));
-
-function extractMaxIterations(args: string): number | undefined {
-  const match = args.match(/--max-iterations\s+(\d+)/i);
-  return match ? parseInt(match[1], 10) : undefined;
-}
-
-async function* runRalphLoop(
-  args: string,
-  ctx: PluginContext,
-): AsyncGenerator<LoopEvent, void, void> {
-  const { provider, history, signal } = ctx;
-
-  const maxIter = Math.min(
-    extractMaxIterations(args) ?? DEFAULT_MAX_ITERATIONS,
-    SAFETY_CEILING,
-  );
-
-  // 没有 args（用户只敲 /ralph-loop）→ 留个最小 goal placeholder，避免 GoalState.init 拒空串
-  const userGoal = args.trim() || '(未提供目标)';
-
-  yield {
-    type: 'plugin_progress',
-    pluginId: PLUGIN_NAME,
-    current: 0,
-    max: maxIter,
-    message: 'Ralph Wiggum copy-task loop 启动',
-  };
-
-  const checks = parseVerifyArgs(args);
-
-  // sessionTag = 插件名 → 多插件可并发不打架，/new 也能扫到清掉
-  const goalState = new GoalState(getWorkingDir(), PLUGIN_NAME);
-  await goalState.reset();
-  await goalState.init(userGoal, checks);
-  await goalState.appendProgress(
-    `=== Loop 启动 === 目标: ${userGoal.slice(0, 120)}...`,
-  );
-
-  // 进循环前快照 history —— 每轮 runQuery 前用它重置，保证 fresh context
-  const baseHistory = history.slice();
-
-  let iterationCount = 0;
-  let consecutiveFailures = 0;
-  let currentInput = userGoal;
-  let finalAssistantMsg: Message | null = null;
-
-  try {
-    do {
-      iterationCount++;
-      if (iterationCount > maxIter) {
-        await goalState.forceSetPhase(Phase.DONE, `达到迭代上限 ${maxIter}`);
-        await goalState.appendLearning(
-          `[迭代上限] 循环在 ${iterationCount - 1} 轮后强制终止，可能目标过大或陷入死循环`,
-        );
-        yield {
-          type: 'error',
-          error: `Loop 已达迭代上限 ${maxIter}，自动停止`,
-        };
-        return;
-      }
-
-      if (signal?.aborted) {
-        yield { type: 'interrupted' };
-        return;
-      }
-
-      yield {
-        type: 'plugin_progress',
-        pluginId: PLUGIN_NAME,
-        current: iterationCount,
-        max: maxIter,
-      };
-
-      // fresh context：清空 history，重置为入循环前的快照
-      history.length = 0;
-      history.push(...baseHistory);
-
-      const freshContext = goalState.composeContext(iterationCount);
-      const enhancedInput = `${freshContext}\n\n${currentInput}`;
-
-      yield* runQuery(enhancedInput, {
-        provider,
-        history,
-        signal,
-        maxTurns: ctx.maxTurns,
-        sessionState: ctx.sessionState,
-      });
-
-      if (signal?.aborted) {
-        yield { type: 'interrupted' };
-        return;
-      }
-
-      // 从本轮 history 抓最后一个 assistant 消息（runQuery 已 push 进去）
-      const lastAssistantIdx = (() => {
-        for (let i = history.length - 1; i >= 0; i--) {
-          if (history[i].role === 'assistant') return i;
-        }
-        return -1;
-      })();
-      finalAssistantMsg =
-        lastAssistantIdx >= 0 ? history[lastAssistantIdx] : null;
-      const lastAssistantText = finalAssistantMsg
-        ? typeof finalAssistantMsg.content === 'string'
-          ? finalAssistantMsg.content
-          : JSON.stringify(finalAssistantMsg.content)
-        : '';
-
-      if (hasCompleteSentinel(lastAssistantText)) {
-        // 哨兵：可能来自任意阶段（包括 iter 1 的 PLAN），用 force 跳到 VERIFY
-        await goalState.forceSetPhase(Phase.VERIFY, '检测到完成哨兵，进入验证');
-        await goalState.appendProgress(
-          `迭代 ${iterationCount}: 检测到完成哨兵，运行验证门...`,
-        );
-
-        if (checks.length > 0) {
-          const vResult = await runVerification(checks);
-
-          if (!vResult.passed) {
-            consecutiveFailures++;
-            await goalState.appendLearning(
-              `[迭代 ${iterationCount}] 声称完成但验证未通过: ${vResult.summary}`,
-            );
-            yield {
-              type: 'error',
-              error: `⚠️ 验证未通过: ${vResult.summary}。继续尝试...`,
-            };
-
-            if (consecutiveFailures >= 3) {
-              await goalState.forceSetPhase(
-                Phase.HEAL,
-                `连续 ${consecutiveFailures} 次验证失败`,
-              );
-            } else {
-              await goalState.setPhase(Phase.BUILD, '验证未通过，返回构建');
-            }
-            continue;
-          }
-
-          await goalState.appendProgress(`✅ 验证通过: ${vResult.summary}`);
-        }
-
-        await goalState.setPhase(Phase.DONE, 'goal complete & verified');
-        yield {
-          type: 'plugin_iteration',
-          pluginName: PLUGIN_NAME,
-          current: iterationCount,
-          max: maxIter,
-        };
-        return;
-      }
-
-      if (hasNeedReplanSentinel(lastAssistantText)) {
-        await goalState.forceSetPhase(Phase.PLAN, 'agent 请求重新规划');
-        await goalState.appendLearning(
-          '[NEED_REPLAN] Agent 认为当前方案不可行，需要重新规划',
-        );
-        await goalState.appendProgress(
-          'Agent 请求 NEED_REPLAN，回 PLAN 阶段',
-        );
-        consecutiveFailures = 0;
-        continue;
-      }
-
-      // PLAN 阶段跑过一轮还没哨兵，认为规划已完成，自动推进 BUILD
-      if (goalState.currentPhase === Phase.PLAN && iterationCount >= 2) {
-        await goalState.setPhase(Phase.BUILD, '规划阶段已完成，进入构建');
-      }
-
-      // Stop-hook 咨询式调用：block 才把 reason 注入下一轮 prompt
-      // pass / 报错都不再终止循环；终止由 sentinel/maxIter/abort/NEED_REPLAN 独占
-      const hookResult = await executeStopHook(PLUGIN_ROOT, lastAssistantText);
-
-      if (hookResult.decision === 'block' && hookResult.reason) {
-        currentInput = hookResult.reason;
-        consecutiveFailures = 0;
-        await goalState.recordDecision(
-          {
-            iteration: iterationCount,
-            phase: goalState.currentPhase,
-            summary: 'stop-hook 反馈',
-          },
-          ['继续循环', '终止'],
-          '继续循环',
-          hookResult.reason.slice(0, 200),
-        );
-        if (hookResult.systemMessage) {
-          baseHistory.push({
-            role: 'user',
-            content: `[Plugin Stop Hook] ${hookResult.systemMessage}`,
-          });
-        }
-        await goalState.appendProgress(
-          `迭代 ${iterationCount}: Stop hook block，注入反馈继续`,
-        );
-      } else {
-        await goalState.appendProgress(
-          `迭代 ${iterationCount}: 无哨兵 / hook pass，继续下一轮`,
-        );
-      }
-    } while (true);
-  } finally {
-    // 收尾：把循环里临时累积的 history 还原成 baseHistory + 最后一轮 assistant
-    // 这样 TUI 上看到的就是"一次问答"，而不是 N 轮重复
-    history.length = 0;
-    history.push(...baseHistory);
-    if (finalAssistantMsg) {
-      history.push(finalAssistantMsg);
-    }
-    await goalState.cleanup();
-  }
-}
-
-const api: PluginApi = {
-  async *runCommand(commandName, args, ctx) {
-    if (commandName === 'ralph-loop') {
-      yield* runRalphLoop(args, ctx);
-      return;
-    }
-    // 其它命令（help / cancel-ralph）→ 不接管，让框架走声明式 fallback
-    yield {
-      type: 'error',
-      error: `ralph-wiggum: 命令 /${commandName} 未由 plugin.ts 接管`,
-    };
-  },
-};
-
-export default api;

package/plugins/ralph-wiggum/scripts/setup-ralph-loop.sh

@@ -1,203 +0,0 @@
-#!/bin/bash
-
-# Ralph Loop Setup Script
-# Creates state file for in-session Ralph loop
-
-set -euo pipefail
-
-# Parse arguments
-PROMPT_PARTS=()
-MAX_ITERATIONS=0
-COMPLETION_PROMISE="null"
-
-# Parse options and positional arguments
-while [[ $# -gt 0 ]]; do
-  case $1 in
-    -h|--help)
-      cat << 'HELP_EOF'
-Ralph Loop - Interactive self-referential development loop
-
-USAGE:
-  /ralph-loop [PROMPT...] [OPTIONS]
-
-ARGUMENTS:
-  PROMPT...    Initial prompt to start the loop (can be multiple words without quotes)
-
-OPTIONS:
-  --max-iterations <n>           Maximum iterations before auto-stop (default: unlimited)
-  --completion-promise '<text>'  Promise phrase (USE QUOTES for multi-word)
-  -h, --help                     Show this help message
-
-DESCRIPTION:
-  Starts a Ralph Wiggum loop in your CURRENT session. The stop hook prevents
-  exit and feeds your output back as input until completion or iteration limit.
-
-  To signal completion, you must output: <promise>YOUR_PHRASE</promise>
-
-  Use this for:
-  - Interactive iteration where you want to see progress
-  - Tasks requiring self-correction and refinement
-  - Learning how Ralph works
-
-EXAMPLES:
-  /ralph-loop Build a todo API --completion-promise 'DONE' --max-iterations 20
-  /ralph-loop --max-iterations 10 Fix the auth bug
-  /ralph-loop Refactor cache layer  (runs forever)
-  /ralph-loop --completion-promise 'TASK COMPLETE' Create a REST API
-
-STOPPING:
-  Only by reaching --max-iterations or detecting --completion-promise
-  No manual stop - Ralph runs infinitely by default!
-
-MONITORING:
-  # View current iteration:
-  grep '^iteration:' .minimal-agent/ralph-loop.local.md
-
-  # View full state:
-  head -10 .minimal-agent/ralph-loop.local.md
-HELP_EOF
-      exit 0
-      ;;
-    --max-iterations)
-      if [[ -z "${2:-}" ]]; then
-        echo "❌ Error: --max-iterations requires a number argument" >&2
-        echo "" >&2
-        echo "   Valid examples:" >&2
-        echo "     --max-iterations 10" >&2
-        echo "     --max-iterations 50" >&2
-        echo "     --max-iterations 0  (unlimited)" >&2
-        echo "" >&2
-        echo "   You provided: --max-iterations (with no number)" >&2
-        exit 1
-      fi
-      if ! [[ "$2" =~ ^[0-9]+$ ]]; then
-        echo "❌ Error: --max-iterations must be a positive integer or 0, got: $2" >&2
-        echo "" >&2
-        echo "   Valid examples:" >&2
-        echo "     --max-iterations 10" >&2
-        echo "     --max-iterations 50" >&2
-        echo "     --max-iterations 0  (unlimited)" >&2
-        echo "" >&2
-        echo "   Invalid: decimals (10.5), negative numbers (-5), text" >&2
-        exit 1
-      fi
-      MAX_ITERATIONS="$2"
-      shift 2
-      ;;
-    --completion-promise)
-      if [[ -z "${2:-}" ]]; then
-        echo "❌ Error: --completion-promise requires a text argument" >&2
-        echo "" >&2
-        echo "   Valid examples:" >&2
-        echo "     --completion-promise 'DONE'" >&2
-        echo "     --completion-promise 'TASK COMPLETE'" >&2
-        echo "     --completion-promise 'All tests passing'" >&2
-        echo "" >&2
-        echo "   You provided: --completion-promise (with no text)" >&2
-        echo "" >&2
-        echo "   Note: Multi-word promises must be quoted!" >&2
-        exit 1
-      fi
-      COMPLETION_PROMISE="$2"
-      shift 2
-      ;;
-    *)
-      # Non-option argument - collect all as prompt parts
-      PROMPT_PARTS+=("$1")
-      shift
-      ;;
-  esac
-done
-
-# Join all prompt parts with spaces
-PROMPT="${PROMPT_PARTS[*]}"
-
-# Validate prompt is non-empty
-if [[ -z "$PROMPT" ]]; then
-  echo "❌ Error: No prompt provided" >&2
-  echo "" >&2
-  echo "   Ralph needs a task description to work on." >&2
-  echo "" >&2
-  echo "   Examples:" >&2
-  echo "     /ralph-loop Build a REST API for todos" >&2
-  echo "     /ralph-loop Fix the auth bug --max-iterations 20" >&2
-  echo "     /ralph-loop --completion-promise 'DONE' Refactor code" >&2
-  echo "" >&2
-  echo "   For all options: /ralph-loop --help" >&2
-  exit 1
-fi
-
-# Create state file for stop hook (markdown with YAML frontmatter)
-mkdir -p .minimal-agent
-
-# Quote completion promise for YAML if it contains special chars or is not null
-if [[ -n "$COMPLETION_PROMISE" ]] && [[ "$COMPLETION_PROMISE" != "null" ]]; then
-  COMPLETION_PROMISE_YAML="\"$COMPLETION_PROMISE\""
-else
-  COMPLETION_PROMISE_YAML="null"
-fi
-
-cat > .minimal-agent/ralph-loop.local.md <<EOF
----
-active: true
-iteration: 1
-max_iterations: $MAX_ITERATIONS
-completion_promise: $COMPLETION_PROMISE_YAML
-started_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
----
-
-$PROMPT
-EOF
-
-# Output setup message
-cat <<EOF
-🔄 Ralph loop activated in this session!
-
-Iteration: 1
-Max iterations: $(if [[ $MAX_ITERATIONS -gt 0 ]]; then echo $MAX_ITERATIONS; else echo "unlimited"; fi)
-Completion promise: $(if [[ "$COMPLETION_PROMISE" != "null" ]]; then echo "${COMPLETION_PROMISE//\"/} (ONLY output when TRUE - do not lie!)"; else echo "none (runs forever)"; fi)
-
-The stop hook is now active. When you try to exit, the SAME PROMPT will be
-fed back to you. You'll see your previous work in files, creating a
-self-referential loop where you iteratively improve on the same task.
-
-To monitor: head -10 .minimal-agent/ralph-loop.local.md
-
-⚠️  WARNING: This loop cannot be stopped manually! It will run infinitely
-    unless you set --max-iterations or --completion-promise.
-
-🔄
-EOF
-
-# Output the initial prompt if provided
-if [[ -n "$PROMPT" ]]; then
-  echo ""
-  echo "$PROMPT"
-fi
-
-# Display completion promise requirements if set
-if [[ "$COMPLETION_PROMISE" != "null" ]]; then
-  echo ""
-  echo "═══════════════════════════════════════════════════════════"
-  echo "CRITICAL - Ralph Loop Completion Promise"
-  echo "═══════════════════════════════════════════════════════════"
-  echo ""
-  echo "To complete this loop, output this EXACT text:"
-  echo "  <promise>$COMPLETION_PROMISE</promise>"
-  echo ""
-  echo "STRICT REQUIREMENTS (DO NOT VIOLATE):"
-  echo "  ✓ Use <promise> XML tags EXACTLY as shown above"
-  echo "  ✓ The statement MUST be completely and unequivocally TRUE"
-  echo "  ✓ Do NOT output false statements to exit the loop"
-  echo "  ✓ Do NOT lie even if you think you should exit"
-  echo ""
-  echo "IMPORTANT - Do not circumvent the loop:"
-  echo "  Even if you believe you're stuck, the task is impossible,"
-  echo "  or you've been running too long - you MUST NOT output a"
-  echo "  false promise statement. The loop is designed to continue"
-  echo "  until the promise is GENUINELY TRUE. Trust the process."
-  echo ""
-  echo "  If the loop should stop, the promise statement will become"
-  echo "  true naturally. Do not force it by lying."
-  echo "═══════════════════════════════════════════════════════════"
-fi