minimal-agent 0.1.8 → 0.1.9

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

@@ -0,0 +1,203 @@
+#!/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

package/skills/config/SKILL.md

@@ -38,7 +38,26 @@ Read({ file_path: "~/.minimal-agent/config.json" })
 | `apiKey` | ✅ | API key（敏感信息） |
 | `model` | ✅ | 模型 id，如 `MiniMax-M2.7` |
 | `provider` | ⬜ | 显示名（仅用于状态栏），默认 `env` |
-| `contextWindow` | ⬜ | 模型上下文窗口（token 数），默认 `128000` |
+| `contextWindow` | ⬜ | 模型上下文窗口（token 数），**推荐值见下方速查表**（按 provider+model 推断） |
+| `tavilyApiKey` | ⬜ | Tavily key（WebSearch 工具用）；可留空跳过，免费 key 申请见 https://tavily.com/ |
+
+### Provider 默认值速查表（contextWindow）
+
+权威值见 `src/cli/configWizard.tsx::PRESETS`；本表是它的镜像，发现不一致以代码为准。
+
+| Provider | Model | 推荐 contextWindow |
+|---|---|---|
+| minimax | MiniMax-M2.7 / MiniMax-M1 / abab6.5s-chat | 204800 |
+| deepseek | deepseek-chat / deepseek-reasoner | 128000 |
+| openai | gpt-4o / gpt-4o-mini | 128000 |
+| moonshot | moonshot-v1-8k | 8000 |
+| moonshot | moonshot-v1-32k | 32000 |
+| moonshot | moonshot-v1-128k | 128000 |
+| 其它 / custom | — | 128000 |
+
+⚠️ 询问 `contextWindow` 时，**先按上表给出推荐值并明确告诉用户**（例：「按你选的 `MiniMax-M2.7`，推荐 `contextWindow = 204800`，直接回车采纳」）。**不要让用户裸填 token 数**；用户主要关心 `baseURL` / `apiKey` / `model`，contextWindow 应优先按 provider+model 推断。
+
+如果用户改了 model 但没改 contextWindow，**主动重新计算推荐值**并提示；用户旧 contextWindow 与新 model 不匹配时（如把 model 从 `moonshot-v1-8k` 改成 `moonshot-v1-128k`），明确建议同步更新。
 
 **对话格式示例**（每次只问一个字段，等用户答完再问下一个）：
 
@@ -62,6 +81,7 @@ Write({
     model: <...>,
     provider: <...>,
     contextWindow: <...>,
+    tavilyApiKey: <... or 省略字段>,
     savedAt: Date.now()
   }, null, 2)
 })
@@ -69,6 +89,12 @@ Write({
 
 字段 `savedAt` 必须是当前的 unix 毫秒时间戳。
 
+`tavilyApiKey` 字段策略：
+- 用户没有 Tavily key → **从写入的 JSON 里删掉这个字段**（不要写空串，readSavedConfig 会拒空串）。
+- 用户提供了 key → 写入字符串。
+- 用户没主动改这个字段 → **保留旧值**（不要为了"格式整洁"删除）。
+- 写入后启动注入：下次启动 minimal-agent 时 `applyToolKeysToEnv()`（`src/config.ts`）会把它注入 `process.env.TAVILY_API_KEY`，WebSearch 工具就能用了。
+
 ### Step 4: 提示重启
 
 写入成功后，输出（中文）：