opencode-auto-loop 0.1.1 → 0.1.3

package/commands/auto-loop.md

@@ -1,30 +1,25 @@
 ---
-description: Start Auto Loop - auto-continues until task completion
+description: "Start Auto Loop - auto-continues until task completion. Use: /auto-loop <task description>"
 ---
 
 # Auto Loop
 
-Start an iterative development loop that automatically continues until the task is complete.
+Parse `$ARGUMENTS` for the task description and an optional `--max <number>` flag.
 
-## Setup
+- If `$ARGUMENTS` contains `--max <number>`, extract that number as **maxIterations** and remove it from the task string.
+- Otherwise, use **maxIterations**: 25
 
-Create the state file in the project directory:
+Invoke the `auto-loop` tool with:
 
-```bash
-mkdir -p .opencode && cat > .opencode/auto-loop.local.md << 'EOF'
----
-active: true
-iteration: 0
-maxIterations: 100
----
-
-$ARGUMENTS
-EOF
-```
+- **task**: the extracted task description
+- **maxIterations**: the extracted or default value
 
-## Task
+Examples:
+- `/auto-loop Build a REST API` → task="Build a REST API", maxIterations=25
+- `/auto-loop Build a REST API --max 50` → task="Build a REST API", maxIterations=50
+- `/auto-loop --max 10 Fix all lint errors` → task="Fix all lint errors", maxIterations=10
 
-Now begin working on the task: **$ARGUMENTS**
+After the tool confirms the loop is active, **immediately begin working on the task**. Do not just acknowledge — start doing the work right away.
 
 ## Progress Tracking
 
@@ -38,15 +33,11 @@ Before going idle, you MUST output structured progress so the plugin knows where
 - [ ] What needs to be done next (in priority order)
 ```
 
-The plugin extracts these into the state file for the next iteration's continuation prompt.
-
 ## Completion
 
-When the task is FULLY completed, signal completion by outputting:
+When the task is FULLY completed, signal completion by outputting the promise-DONE XML tag on its own line:
 
-```
 <promise>DONE</promise>
-```
 
 **IMPORTANT:** ONLY output this when the task is COMPLETELY and VERIFIABLY finished. Do NOT output false promises to escape the loop.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-auto-loop",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Auto-continue for OpenCode",
   "main": "src/index.ts",
   "type": "module",
@@ -27,7 +27,7 @@
     "skills/"
   ],
   "dependencies": {
-    "@opencode-ai/plugin": "^0.15.31"
+    "@opencode-ai/plugin": "^1.2.27"
   },
   "engines": {
     "node": ">=18.0.0"

package/skills/auto-loop/SKILL.md

@@ -11,30 +11,19 @@ Start an iterative development loop that automatically continues until the task
 
 The Auto Loop creates a continuous feedback cycle for completing complex tasks:
 
-1. You work on the task until you go idle
-2. The plugin detects the idle state and checks for completion
-3. If not complete, it extracts your progress and prompts you to continue
-4. This repeats until you output the completion promise or max iterations reached
+1. You invoke the `auto-loop` tool, which creates the state file and starts the loop
+2. You work on the task until you go idle
+3. The plugin detects the idle state and checks for completion
+4. If not complete, it extracts your progress and prompts you to continue
+5. This repeats until you output the completion signal or max iterations reached
 
 Your previous work remains accessible through files, git history, and the state file's progress sections.
 
 ## Starting the Loop
 
-When you invoke this skill, create the state file in the project directory:
+**Always use the `auto-loop` tool** to start the loop. Do NOT create the state file manually. The tool handles state file creation, session tracking, and initialization.
 
-```bash
-mkdir -p .opencode && cat > .opencode/auto-loop.local.md << 'EOF'
----
-active: true
-iteration: 0
-maxIterations: 100
----
-
-[The user's task prompt goes here]
-EOF
-```
-
-Then inform the user and begin working on the task.
+After the tool confirms the loop is active, **immediately begin working on the task**. Do not just acknowledge — start doing the work.
 
 ## Progress Tracking - CRITICAL
 
@@ -61,9 +50,9 @@ Use this format in your final message of each iteration:
 - Order ## Next Steps by priority — the continuation will tell you to start from the top
 - The plugin extracts these sections and writes them into `auto-loop.local.md` for the next iteration
 
-## Completion Promise - CRITICAL RULES
+## Completion Signal - CRITICAL RULES
 
-When you have FULLY completed the task, signal completion by outputting:
+When you have FULLY completed the task, signal completion by outputting the promise-DONE XML tag on its own line:
 
 ```
 <promise>DONE</promise>
@@ -71,14 +60,14 @@ When you have FULLY completed the task, signal completion by outputting:
 
 **IMPORTANT CONSTRAINTS:**
 
-- ONLY output `<promise>DONE</promise>` when the task is COMPLETELY and VERIFIABLY finished
-- The statement MUST be completely and unequivocally TRUE
-- Do NOT output false promises to escape the loop, even if you think you're stuck
-- Do NOT lie even if you think you should exit for other reasons
+- ONLY output the completion signal when the task is COMPLETELY and VERIFIABLY finished
+- The completion tag MUST be on its own line (not inline with other text)
+- Do NOT mention or echo the completion tag in explanatory text — only output it as the actual signal
+- Do NOT output false completion signals to escape the loop, even if you think you're stuck
 - If you're blocked, explain the blocker and request help instead of falsely completing
 
 The loop can only be stopped by:
-1. Truthful completion promise
+1. Truthful completion signal
 2. Max iterations reached
 3. User running `/cancel-auto-loop`
 
@@ -97,7 +86,7 @@ The state file at `.opencode/auto-loop.local.md` uses YAML frontmatter with prog
 ---
 active: true
 iteration: 3
-maxIterations: 100
+maxIterations: 25
 sessionId: ses_abc123
 ---
 

package/src/index.ts

@@ -2,11 +2,10 @@ import { type Plugin, type PluginInput, tool } from "@opencode-ai/plugin";
 import {
   existsSync,
   readFileSync,
-  writeFileSync,
   mkdirSync,
-  unlinkSync,
   cpSync,
 } from "fs";
+import { readFile, writeFile, unlink, mkdir } from "fs/promises";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { homedir } from "os";
@@ -16,6 +15,7 @@ interface LoopState {
   active: boolean;
   iteration: number;
   maxIterations: number;
+  debounceMs: number;
   sessionId?: string;
   prompt?: string;
   completed?: string;
@@ -30,8 +30,9 @@ type OpencodeClient = PluginInput["client"];
 const SERVICE_NAME = "auto-loop";
 const STATE_FILENAME = "auto-loop.local.md";
 const OPENCODE_CONFIG_DIR = join(homedir(), ".config/opencode");
-const COMPLETION_TAG = /<promise>\s*DONE\s*<\/promise>/is;
-const DEBOUNCE_MS = 2000;
+const COMPLETION_TAG = /^\s*<promise>\s*DONE\s*<\/promise>\s*$/im;
+const DEFAULT_DEBOUNCE_MS = 2000;
+const DEFAULT_MAX_ITERATIONS = 25;
 
 // Get plugin root directory (ESM only — package is "type": "module")
 function getPluginRoot(): string {
@@ -104,13 +105,14 @@ function getStateFile(directory: string): string {
 // Parse markdown frontmatter state
 function parseState(content: string): LoopState {
   const match = content.match(/^---\n([\s\S]*?)\n---/);
-  if (!match) return { active: false, iteration: 0, maxIterations: 100 };
+  if (!match) return { active: false, iteration: 0, maxIterations: DEFAULT_MAX_ITERATIONS, debounceMs: DEFAULT_DEBOUNCE_MS };
 
   const frontmatter = match[1];
   const state: LoopState = {
     active: false,
     iteration: 0,
-    maxIterations: 100,
+    maxIterations: DEFAULT_MAX_ITERATIONS,
+    debounceMs: DEFAULT_DEBOUNCE_MS,
   };
 
   for (const line of frontmatter.split("\n")) {
@@ -118,7 +120,8 @@ function parseState(content: string): LoopState {
     const value = valueParts.join(":").trim();
     if (key === "active") state.active = value === "true";
     if (key === "iteration") state.iteration = parseInt(value) || 0;
-    if (key === "maxIterations") state.maxIterations = parseInt(value) || 100;
+    if (key === "maxIterations") state.maxIterations = parseInt(value) || DEFAULT_MAX_ITERATIONS;
+    if (key === "debounceMs") state.debounceMs = parseInt(value) || DEFAULT_DEBOUNCE_MS;
     if (key === "sessionId") state.sessionId = value || undefined;
   }
 
@@ -152,6 +155,7 @@ function serializeState(state: LoopState): string {
     `active: ${state.active}`,
     `iteration: ${state.iteration}`,
     `maxIterations: ${state.maxIterations}`,
+    `debounceMs: ${state.debounceMs}`,
   ];
   if (state.sessionId) lines.push(`sessionId: ${state.sessionId}`);
   lines.push("---");
@@ -162,41 +166,49 @@ function serializeState(state: LoopState): string {
 }
 
 // Read state from project directory
-function readState(directory: string): LoopState {
+async function readState(directory: string): Promise<LoopState> {
   const stateFile = getStateFile(directory);
-  if (existsSync(stateFile)) {
-    return parseState(readFileSync(stateFile, "utf-8"));
+  try {
+    const content = await readFile(stateFile, "utf-8");
+    return parseState(content);
+  } catch {
+    return { active: false, iteration: 0, maxIterations: DEFAULT_MAX_ITERATIONS, debounceMs: DEFAULT_DEBOUNCE_MS };
   }
-  return { active: false, iteration: 0, maxIterations: 100 };
 }
 
 // Write state to project directory
-function writeState(directory: string, state: LoopState, log: LogFn): void {
+async function writeState(directory: string, state: LoopState, log: LogFn): Promise<void> {
   try {
     const stateFile = getStateFile(directory);
-    mkdirSync(dirname(stateFile), { recursive: true });
-    writeFileSync(stateFile, serializeState(state));
+    await mkdir(dirname(stateFile), { recursive: true });
+    await writeFile(stateFile, serializeState(state));
   } catch (err) {
     log("error", `Failed to write state: ${err}`);
   }
 }
 
 // Clear state
-function clearState(directory: string, log: LogFn): void {
+async function clearState(directory: string, log: LogFn): Promise<void> {
   try {
     const stateFile = getStateFile(directory);
-    if (existsSync(stateFile)) unlinkSync(stateFile);
+    await unlink(stateFile);
   } catch (err) {
-    log("warn", `Failed to clear state: ${err}`);
+    // ENOENT is fine — file already gone
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+      log("warn", `Failed to clear state: ${err}`);
+    }
   }
 }
 
-// Strip markdown code fences before checking for completion tag
+// Strip markdown code fences and inline code before checking for completion tag
 function stripCodeFences(text: string): string {
-  return text.replace(/```[\s\S]*?```/g, "");
+  return text
+    .replace(/```[\s\S]*?```/g, "") // triple-backtick blocks
+    .replace(/`[^`]+`/g, "");       // inline backtick code
 }
 
-// Extract text from the last assistant message in a session
+// Extract text from the last assistant message in a session.
+// Fetches only the most recent messages to avoid pulling the entire history.
 async function getLastAssistantText(
   client: OpencodeClient,
   sessionId: string,
@@ -206,7 +218,7 @@ async function getLastAssistantText(
   try {
     const response = await client.session.messages({
       path: { id: sessionId },
-      query: { directory },
+      query: { directory, limit: 10 },
     });
 
     const messages = response.data ?? [];
@@ -348,6 +360,27 @@ Before going idle, list your progress using ## Completed and ## Next Steps secti
 Do NOT output false completion promises. If blocked, explain the blocker.`;
 }
 
+// Check if session is currently busy (not idle)
+async function isSessionBusy(
+  client: OpencodeClient,
+  sessionId: string,
+  log: LogFn
+): Promise<boolean> {
+  try {
+    const response = await client.session.status({});
+    const statuses = response.data ?? {};
+    const status = statuses[sessionId];
+    if (status && status.type !== "idle") {
+      log("debug", `Session ${sessionId} is ${status.type}, skipping continuation`);
+      return true;
+    }
+    return false;
+  } catch (err) {
+    log("warn", `Failed to check session status: ${err}`);
+    return false; // Assume not busy if we can't check
+  }
+}
+
 // Main plugin
 export const AutoLoopPlugin: Plugin = async (ctx) => {
   const directory = ctx.directory || process.cwd();
@@ -384,6 +417,11 @@ export const AutoLoopPlugin: Plugin = async (ctx) => {
 
   // Debounce tracking for idle events
   let lastContinuation = 0;
+  // Guard: prevent sending while a continuation is already in-flight.
+  // Set to true when we send promptAsync, cleared when we receive a
+  // session.idle or session.status(idle) event — NOT in the finally block,
+  // which fires too early (~50ms after the 204, while AI is still busy).
+  let continuationInFlight = false;
 
   return {
     tool: {
@@ -397,17 +435,27 @@ export const AutoLoopPlugin: Plugin = async (ctx) => {
           maxIterations: tool.schema
             .number()
             .optional()
-            .describe("Maximum iterations (default: 100)"),
+            .describe("Maximum iterations (default: 25)"),
+          debounceMs: tool.schema
+            .number()
+            .optional()
+            .describe("Debounce delay between iterations in ms (default: 2000)"),
         },
-        async execute({ task, maxIterations = 100 }, context) {
+        async execute({ task, maxIterations = DEFAULT_MAX_ITERATIONS, debounceMs = DEFAULT_DEBOUNCE_MS }, context) {
+          if (context.abort.aborted) return "Auto Loop start was cancelled.";
+
           const state: LoopState = {
             active: true,
             iteration: 0,
             maxIterations,
+            debounceMs,
             sessionId: context.sessionID,
             prompt: task,
           };
-          writeState(directory, state, log);
+          await writeState(directory, state, log);
+          // Reset guards so the first idle event is not blocked
+          continuationInFlight = false;
+          lastContinuation = 0;
 
           log("info", `Loop started for session ${context.sessionID}`);
           toast(`Auto Loop started (max ${maxIterations} iterations)`, "success");
@@ -416,7 +464,9 @@ export const AutoLoopPlugin: Plugin = async (ctx) => {
 
 Task: ${task}
 
-I will auto-continue until the task is complete. Before going idle each iteration, I will output structured progress:
+**Begin working on the task now.** The loop will auto-continue until you signal completion.
+
+Before going idle each iteration, output structured progress:
 
 \`\`\`
 ## Completed
@@ -426,7 +476,7 @@ I will auto-continue until the task is complete. Before going idle each iteratio
 - [ ] What remains (in priority order)
 \`\`\`
 
-When fully done, I will output \`<promise>DONE</promise>\` to signal completion.
+When the task is FULLY and VERIFIABLY complete, output the completion signal on its own line (the promise-DONE XML tag). Do NOT mention or echo the completion tag until you are truly done.
 
 Use /cancel-auto-loop to stop early.`;
         },
@@ -435,13 +485,15 @@ Use /cancel-auto-loop to stop early.`;
       "cancel-auto-loop": tool({
         description: "Cancel active Auto Loop",
         args: {},
-        async execute() {
-          const state = readState(directory);
+        async execute(_args, context) {
+          if (context.abort.aborted) return "Cancel was aborted.";
+          const state = await readState(directory);
           if (!state.active) {
             return "No active Auto Loop to cancel.";
           }
           const iterations = state.iteration;
-          clearState(directory, log);
+          await clearState(directory, log);
+          continuationInFlight = false;
 
           log("info", `Loop cancelled after ${iterations} iteration(s)`);
           toast(`Auto Loop cancelled after ${iterations} iteration(s)`, "warning");
@@ -458,10 +510,16 @@ Use /cancel-auto-loop to stop early.`;
 
 ## Available Commands
 
-- \`/auto-loop <task>\` - Start an auto-continuation loop
+- \`/auto-loop <task>\` - Start an auto-continuation loop (default: 25 iterations)
+- \`/auto-loop <task> --max <n>\` - Start with a custom iteration limit
 - \`/cancel-auto-loop\` - Stop an active loop
 - \`/auto-loop-help\` - Show this help
 
+## Examples
+
+- \`/auto-loop Build a REST API\` — runs up to 25 iterations
+- \`/auto-loop Fix all lint errors --max 10\` — runs up to 10 iterations
+
 ## How It Works
 
 1. Start with: /auto-loop "Build a REST API"
@@ -480,28 +538,37 @@ Located at: .opencode/auto-loop.local.md`;
     event: async ({ event }) => {
       // --- session.idle: core auto-continuation logic ---
       if (event.type === "session.idle") {
-        const now = Date.now();
-        if (now - lastContinuation < DEBOUNCE_MS) return;
-
         const sessionId = event.properties.sessionID;
-        const state = readState(directory);
+
+        // Session confirmed idle — safe to clear in-flight guard
+        continuationInFlight = false;
+
+        const state = await readState(directory);
 
         if (!state.active) return;
         if (!sessionId) return;
         if (state.sessionId && state.sessionId !== sessionId) return;
 
+        const now = Date.now();
+        if (now - lastContinuation < state.debounceMs) return;
+
+        // Double-check the session is truly idle before sending
+        if (await isSessionBusy(client, sessionId, log)) return;
+
         // Fetch last assistant message (used for completion check + progress extraction)
         const lastText = await getLastAssistantText(client, sessionId, directory, log);
 
-        if (lastText && checkCompletion(lastText)) {
-          clearState(directory, log);
+        // Skip completion check on iteration 0 (first idle after loop start)
+        // to avoid false positives from the tool's initial response text
+        if (state.iteration > 0 && lastText && checkCompletion(lastText)) {
+          await clearState(directory, log);
           log("info", `Loop completed at iteration ${state.iteration}`);
           toast(`Auto Loop completed after ${state.iteration} iteration(s)`, "success");
           return;
         }
 
         if (state.iteration >= state.maxIterations) {
-          clearState(directory, log);
+          await clearState(directory, log);
           log("warn", `Loop hit max iterations (${state.maxIterations})`);
           toast(`Auto Loop stopped — max iterations (${state.maxIterations}) reached`, "warning");
           return;
@@ -515,12 +582,10 @@ Located at: .opencode/auto-loop.local.md`;
           ...state,
           iteration: state.iteration + 1,
           sessionId,
-          // Update next steps if we found new ones, otherwise keep previous
           nextSteps: newNextSteps || state.nextSteps,
-          // Merge completed: append new completed items to existing
           completed: mergeCompleted(state.completed, newCompleted),
         };
-        writeState(directory, newState, log);
+        await writeState(directory, newState, log);
         lastContinuation = Date.now();
 
         // Build continuation prompt with progress context
@@ -540,7 +605,13 @@ Original task:
 ${state.prompt || "(no task specified)"}`;
 
         try {
-          await client.session.prompt({
+          // Use promptAsync (fire-and-forget) so the event handler returns
+          // immediately. This allows the next session.idle event to fire
+          // naturally when the AI finishes, enabling the loop to continue.
+          // The synchronous prompt() blocks until the AI response completes,
+          // which prevents subsequent idle events from being processed.
+          continuationInFlight = true;
+          await client.session.promptAsync({
             path: { id: sessionId },
             body: {
               parts: [{ type: "text", text: continuationPrompt }],
@@ -549,21 +620,31 @@ ${state.prompt || "(no task specified)"}`;
           log("info", `Sent continuation ${newState.iteration}/${newState.maxIterations}`);
           toast(`Auto Loop: iteration ${newState.iteration}/${newState.maxIterations}`);
         } catch (err) {
+          // On failure, clear the guard so the next idle event can retry
+          continuationInFlight = false;
           log("error", `Failed to send continuation prompt: ${err}`);
         }
       }
 
+      // --- session.status: clear in-flight guard when session returns to idle ---
+      if (event.type === "session.status") {
+        if (event.properties.status?.type === "idle") {
+          continuationInFlight = false;
+        }
+      }
+
       // --- session.compacted: re-inject loop context after compaction ---
       if (event.type === "session.compacted") {
         const sessionId = event.properties.sessionID;
-        const state = readState(directory);
+        const state = await readState(directory);
 
         if (!state.active) return;
         if (state.sessionId && state.sessionId !== sessionId) return;
 
         // After compaction, the AI loses loop context — send a reminder
+        // Use promptAsync so we don't block event processing
         try {
-          await client.session.prompt({
+          await client.session.promptAsync({
             path: { id: sessionId },
             body: {
               parts: [{ type: "text", text: buildLoopContextReminder(state) }],
@@ -578,7 +659,11 @@ ${state.prompt || "(no task specified)"}`;
       // --- session.error: pause the loop on error ---
       if (event.type === "session.error") {
         const sessionId = event.properties.sessionID;
-        const state = readState(directory);
+        // sessionID is optional in the SDK types — if missing, we can't
+        // reliably attribute the error to our session, so skip.
+        if (!sessionId) return;
+
+        const state = await readState(directory);
 
         if (
           state.active &&
@@ -586,20 +671,22 @@ ${state.prompt || "(no task specified)"}`;
         ) {
           log("warn", `Session error detected, pausing loop at iteration ${state.iteration}`);
           toast("Auto Loop paused — session error", "error");
+          continuationInFlight = false;
           // Mark inactive but keep state so user can inspect/resume
-          writeState(directory, { ...state, active: false }, log);
+          await writeState(directory, { ...state, active: false }, log);
         }
       }
 
       // --- session.deleted: clean up if it's our session ---
       if (event.type === "session.deleted") {
-        const state = readState(directory);
+        const state = await readState(directory);
         if (!state.active) return;
 
         const deletedSessionId = event.properties.info?.id;
         if (state.sessionId && deletedSessionId && state.sessionId !== deletedSessionId) return;
 
-        clearState(directory, log);
+        await clearState(directory, log);
+        continuationInFlight = false;
         log("info", "Session deleted, cleaning up loop state");
       }
     },