opencode-auto-resume 1.1.11 → 1.1.13

package/README.md

@@ -12,6 +12,8 @@ LLM sessions fail in predictable ways. This plugin monitors all sessions and aut
 
 The stream goes silent but the session stays "busy". The UI shows a blinking cursor with no progress. If no events arrive for 48 seconds (`chunkTimeoutMs` + `gracePeriodMs`), the plugin sends `"continue"` with exponential backoff. After 3 failed attempts it gives up.
 
+The `busyStallStrategy` option controls this path: `"continue"` (default), `"abort"` (abort-first), or `"off"` — see [Recovery model](#recovery-model) for what a busy prompt can and cannot do while the runner is live.
+
 The plugin extracts the **agent, model, and provider** from the last session message, so it resumes with the exact same configuration the user was using (build, sisyphus, prometheus, etc.).
 
 _Motivated by:_
@@ -40,7 +42,7 @@ _Motivated by:_
 
 The model generates the same broken output repeatedly. Each `continue` just picks up the broken generation. If a session needs 3+ continues within 10 minutes, the plugin aborts the request and sends `"continue"` fresh, forcing a clean restart.
 
-A separate **tool-call loop detector** also catches the model calling the same tool 3+ consecutive times (or repeating patterns of length 2-5 occurring at least three times). When detected, it emits `TOOL_LOOP_RECOVERY_PROMPT` to break the loop instead of blindly continuing.
+A separate **tool-call loop detector** also catches the model calling the same tool 3+ consecutive times (or repeating patterns of length 2-5 occurring at least three times). When detected, it emits `TOOL_LOOP_RECOVERY_PROMPT` (at most twice per session) to break the loop instead of blindly continuing.
 
 _Motivated by:_
 - [#22142](https://github.com/anomalyco/opencode/issues/22142) — Repetitive tool-call loops with alibaba-coding-plan-cn/qwen3.6-plus
@@ -53,7 +55,7 @@ _Motivated by:_
 
 ### Orphan parent
 
-A subagent finishes but the parent session stays stuck as "busy" forever. The plugin detects when `busyCount` drops from >1 to 1, waits 15 seconds (`subagentWaitMs`), then aborts and resumes the parent.
+A subagent finishes but the parent session stays stuck as "busy" forever. The plugin detects when `busyCount` drops from >1 to 1, waits `subagentWaitMs` + `gracePeriodMs` (18s default), probes the subagent (recovering a crashed child first if possible), then aborts and resumes the parent.
 
 _Motivated by:_
 - [#35066](https://github.com/anomalyco/opencode/issues/35066) — notify parent when subagent sessions finish
@@ -88,7 +90,7 @@ The AI provider's streaming response can fail mid-stream (connection reset, time
 1. **Detection**: `session.error` is classified via `isStreamingFailure()` against the configured error names and message patterns
 2. **State transition**: the session's `pendingRecovery` flag is armed with the error name (`pendingRecoveryReason`) and timestamp (`pendingRecoveryAt`)
 3. **Recovery attempt**: once the session is idle and the backoff delay has elapsed, the timer loop sends a recovery prompt
-4. **Watchdog**: if the session is still not busy 3 seconds after the prompt, the recovery is retried (up to `maxRecoveryRetries`) with exponential backoff
+4. **Watchdog**: if the session is still not busy `toolTextCheckDelayMs` (3s default) after the prompt, the recovery is retried (up to `maxRecoveryRetries`) with exponential backoff
 5. **Escalation**: when retries are exhausted, the plugin aborts the session and resumes it (`abort+resume`); `gaveUp` is set if that also fails
 
 #### Configuration
@@ -128,8 +130,8 @@ See [Recovery Flow Documentation](docs/architecture/recovery-flow.md) for the fu
 5. Session goes idle; timer loop waits until the backoff delay has elapsed
 6. Recovery prompt sent (recoveryAttempts=1)
 7. Success → session busy → recovery flags cleared
-   Still not busy after 3s → watchdog retry (attempt 2/2)
-   Still not busy after 3s → maxRecoveryRetries reached → abort + resume
+   Still not busy after `toolTextCheckDelayMs` (3s default) → watchdog retry (attempt 2/2)
+   Still not busy → maxRecoveryRetries reached → abort + resume
    Abort+continue fails → gaveUp
 ```
 
@@ -148,9 +150,15 @@ _Motivated by:_
 
 ---
 
+### Silent dead-stream recovery
+
+The model stream can die after emitting only reasoning — no text part, no tool call — finalizing with `finish: "unknown"`. OpenCode treats the message as completed and the session goes idle, so no error or stall path triggers. On idle, if the **newest** assistant message has a finish reason, zero text parts, and at least `silentDeadStreamMinTokens` output tokens, the plugin sends a recovery prompt. Only the newest assistant message is evaluated — a delivered text answer means normal completion, and older tool-call steps are never misread as dead streams. Recovery is also skipped if the session has gone busy/retry again before the prompt is sent (race guard).
+
+---
+
 ### Active-tool safety guard
 
-Before **any** abort, the plugin calls `checkSessionHasActiveTool()` to verify the session isn't mid-tool-execution. If a tool is running, the abort is skipped. This prevents the plugin from killing a long-running build, test suite, or command — even when it looks like a stall.
+Before **any** abort, two guards run in order: the primary deterministic in-flight counter maintained by the `tool.execute.before`/`tool.execute.after` hooks (`hasInflightTools()`), then a polled `checkSessionHasActiveTool()` fallback for sessions discovered without hooks. If a tool is running, the abort is skipped. This prevents the plugin from killing a long-running build, test suite, or command — even when it looks like a stall.
 
 _Motivated by:_
 - [#26063](https://github.com/anomalyco/opencode/issues/26063) — Tool execution aborted/terminated
@@ -172,7 +180,9 @@ _Motivated by:_
 
 ### ESC cancel respected
 
-User presses ESC to cancel a request. The plugin detects `MessageAbortedError` and marks all busy sessions as cancelled, never resuming them. The grace period (`gracePeriodMs`) also lets late ESC/status events arrive before any action.
+User presses ESC to cancel a request. The plugin detects `MessageAbortedError` and marks sessions as cancelled — regardless of their tracked status, so a late status flip to idle before the error cannot miss the latch — and never resumes them. Aborts initiated by the plugin itself (`pluginAbortInFlight`) are excluded, so recovery aborts are not mistaken for ESC. The grace period (`gracePeriodMs`) also lets late ESC/status events arrive before any action.
+
+The back-off lifts as soon as the user sends a new prompt in that session (`chat.message` hook): a fresh user message starts a new round of work, so auto-resume re-arms. The plugin's own recovery prompts do not re-arm it. The same applies to the `task_complete` latch.
 
 _Motivated by:_
 - [#28453](https://github.com/anomalyco/opencode/issues/28453) — ACP session/cancel emits agent_error for MessageAbortedError before cancelled result
@@ -185,6 +195,8 @@ _Motivated by:_
 
 The agent can call the built-in `task_complete` tool to signal that all work is done. When invoked, the plugin stops sending any further `"continue"` prompts, clears all pending timers, and marks the session as complete. This replaces fragile text-based heuristics (emoji patterns, language detection) with a deterministic signal.
 
+If `task_complete` is called while open todos remain, the call is rejected (up to `maxRetries` times) with a message asking the agent to finish the remaining work first.
+
 ---
 
 ### 🎉 emoji completion
@@ -199,9 +211,15 @@ When the assistant prints phrases like "Ready to continue with task" or "Proceed
 
 ---
 
+### Action-intent nudge
+
+When the assistant ends a line with `:` ("Next, I will edit the file:") — announcing intent without acting — the plugin sends `actionIntentPrompt` after a short delay, nudging the model to execute. Disable with `resumeOnActionIntent: false`. Detection is skipped while a session is younger than `warmupMs`.
+
+---
+
 ### Done-claim verification
 
-If the assistant claims the task is done ("task done", "finished", "all complete") but open todos remain, the plugin sends `DONE_WITHOUT_WORK_PROMPT` asking the agent to verify and finish remaining work. This uses the real `todo.updated` event state — not regex on the message text.
+If the assistant claims the task is done ("task done", "finished", "all complete") but open todos remain, the plugin sends `DONE_WITHOUT_WORK_PROMPT` asking the agent to verify and finish remaining work. If it claims done with **no** open todos but the response contains no description of the work, the plugin sends `DONE_WITHOUT_DETAILS_PROMPT` — an imperative prompt demanding a concrete report (files changed, commands run, results). Both use the real `todo.updated` event state — not regex on the message text.
 
 ---
 
@@ -233,6 +251,32 @@ _Motivated by:_
 
 ---
 
+## Recovery model
+
+All recovery paths fall into three families. Which family fires determines what the prompt can actually do.
+
+### 1. Idle-boundary nudges (safe)
+
+Fire only after OpenCode reports the session **idle** — the runner has exited. The prompt starts a new run.
+
+Paths: todo nudges, tool-call-as-text recovery, thinking-tool recovery, action-intent nudge, ready-to-continue, done-claim verification, streaming-failure recovery, silent dead-stream recovery.
+
+### 2. Busy-silence continue (stream stall)
+
+Fires when the session still reports **busy** but no events arrived for `chunkTimeoutMs` + `gracePeriodMs`. Controlled by `busyStallStrategy`:
+
+- `"continue"` (default) — sends a prompt while busy. This only helps when the busy status is **stale** (the runner already exited but the status was never updated); the prompt then starts a new run.
+- `"abort"` — aborts first (`session.abort()`), then sends the prompt. Required to unblock a runner that is genuinely stuck (hung provider stream). Subject to the same active-tool guards as every abort: never fires while a tool is in-flight.
+- `"off"` — disables busy-silence recovery entirely; stalls are then handled only by idle-boundary recovery (if the session ever goes idle) or manually.
+
+**Why `"continue"` cannot unblock a live runner:** in OpenCode ≥ 1.18, `session.prompt()` while the runner is `Running` joins the existing run — the message is admitted to the session inbox and promoted at the next provider-turn boundary. A hung stream never reaches that boundary, so the parked message cannot unblock it; if the run later exits, the message may surface as an unwanted extra turn (token cost, race risk). True transport stalls need abort-first.
+
+### 3. Abort-first recovery
+
+Aborts the active run, then continues. The only family that can unblock a live runner.
+
+Paths: orphan parent, subagent stuck (parent side), hallucination loop, streaming-failure escalation. All aborts pass the active-tool guards first, and plugin-initiated aborts are marked so they are not mistaken for user ESC (`session.error` → `MessageAbortedError` race).
+
 ## Architecture
 
 ```
@@ -242,6 +286,8 @@ Any SSE Event
 
 session.status events:
   ├─ busy → reset timer, clear retry counters
+  ├─ retry → touch session
+  ├─ interrupted → user cancel: back off until the next user message
   └─ idle → schedule tool-text check (3s delay)
               └─ fetch messages → scan for XML / thinking-tool patterns
                   ├─ found → send recovery prompt (with backoff)
@@ -257,12 +303,16 @@ Timer loop (every 5s):
     ├─ orphan watch active? → wait or abort+continue
     ├─ busyCount > 1? → skip (subagent running)
     ├─ active tool running? → skip (never abort tools)
-    └─ idle > 48s? → hallucination loop? abort : continue with backoff
+    └─ idle > 48s? → busyStallStrategy:
+         off → skip · abort → abort+continue
+         else → hallucination loop? abort : continue with backoff
 
 Periodic (every 60s): session.list() to discover missed sessions
 Periodic: cleanup idle sessions older than 10min or >50 entries
 ```
 
+Events consumed: `session.status`, `session.created`, `session.updated`, `session.idle`, `session.interrupted`, `session.error`, `todo.updated`, `command.executed`; hooks: `chat.message`, `tool.execute.before`/`after`, `command.execute.before`.
+
 ## Installation
 
 ### Opencode
@@ -319,6 +369,19 @@ With options:
 | `streamingFailureErrorNames` | `["ProviderError","APIError","StreamError","ConnectionError","TimeoutError"]` | Error names that classify as streaming failures (exact match) |
 | `streamingFailureMessagePatterns` | `["streaming response failed","stream.*fail","connection.*reset","connection.*closed"]` | Regex patterns (case-insensitive) in error messages indicating streaming failure |
 | `maxRecoveryRetries` | `2` | Max streaming-failure recovery attempts before abort+resume escalation |
+| `toolTextCheckDelayMs` | `3000` | Delay before scanning an idle session for tool-as-text; also the recovery watchdog delay |
+| `minActivityGapMs` | `1000` | Skip recovery if the session was active within this gap |
+| `warmupMs` | `15000` | Action-intent detection disabled while a session is younger than this |
+| `debug` | `false` | Enable `[debug]` console diagnostics |
+| `resumeOnActionIntent` | `true` | Enable action-intent (`:`-terminated line) nudges |
+| `continuePrompt` | `"continue"` | Prompt text for stall/streaming/dead-stream recovery |
+| `actionIntentPrompt` | same as `continuePrompt` | Prompt sent on action-intent detection |
+| `toolTextRecoveryPrompt` | `TOOL_TEXT_RECOVERY_PROMPT` | Override the tool-call-as-text recovery prompt |
+| `thinkingToolRecoveryPrompt` | `THINKING_TOOL_RECOVERY_PROMPT` | Override the thinking-tool recovery prompt |
+| `doneWithoutWorkPrompt` | `DONE_WITHOUT_WORK_PROMPT` | Override the done-claim-with-open-todos prompt |
+| `doneWithoutDetailsPrompt` | `DONE_WITHOUT_DETAILS_PROMPT` | Override the done-claim-with-no-todos report prompt |
+| `silentDeadStreamMinTokens` | `200` | Min output tokens to treat a textless `finish:"unknown"` message as a dead stream |
+| `busyStallStrategy` | `"continue"` | Busy-stall response: `"continue"`, `"abort"` (abort-first), or `"off"` (disabled) |
 
 Message patterns are matched case-insensitively. Error names use exact match.
 
@@ -326,7 +389,6 @@ Message patterns are matched case-insensitively. Error names use exact match.
 
 | Constant | Value | Description |
 |---|---|---|
-| `TOOL_TEXT_CHECK_DELAY_MS` | `3000` | Delay before scanning idle session for tool-as-text |
 | `ABORT_CONTINUE_DELAY_MS` | `2000` | Delay between abort and continue |
 | `MAX_IDLE_SESSIONS` | `50` | Idle session map cap before cleanup |
 | `IDLE_CLEANUP_MS` | `600000` | Idle session age before cleanup (10 min) |

package/dist/index.js

@@ -12523,7 +12523,7 @@ function getLastSilentDeadStream(messages) {
       return t.type === "text" && typeof t.text === "string" && t.text.length > 0;
     });
     if (hasText)
-      continue;
+      return null;
     const tokens = msg.tokens;
     const tInfo = info?.tokens;
     const output = (tokens?.output ?? 0) + (tInfo?.output ?? 0);
@@ -12598,6 +12598,8 @@ var AutoResumePlugin = async (ctx, options) => {
   const doneWithoutWorkPrompt = options?.doneWithoutWorkPrompt ?? DONE_WITHOUT_WORK_PROMPT;
   const doneWithoutDetailsPrompt = options?.doneWithoutDetailsPrompt ?? DONE_WITHOUT_DETAILS_PROMPT;
   const silentDeadStreamMinTokens = options?.silentDeadStreamMinTokens ?? DEFAULT_SILENT_DEAD_STREAM_MIN_TOKENS;
+  const rawBusyStallStrategy = options?.busyStallStrategy ?? "continue";
+  const busyStallStrategy = rawBusyStallStrategy === "abort" || rawBusyStallStrategy === "off" ? rawBusyStallStrategy : "continue";
   const dbg = (...args) => {
     if (debug)
       console.log("[debug]", ...args);
@@ -13757,6 +13759,10 @@ var AutoResumePlugin = async (ctx, options) => {
           }
           const idle = now - w.lastActivityAt;
           if (idle >= chunkTimeoutMs + gracePeriodMs) {
+            if (busyStallStrategy === "off") {
+              dbg(`Stream stall on ${short(sid)} ignored (busyStallStrategy=off)`);
+              continue;
+            }
             if (hasInflightTools(w)) {
               await log("debug", `Session ${short(sid)} has ${w.pendingTools} tool(s) in-flight, skipping stall recovery`);
               w.lastSubagentCheckAt = now;
@@ -13766,7 +13772,12 @@ var AutoResumePlugin = async (ctx, options) => {
                 await log("debug", `Session ${short(sid)} has active tool call, skipping stall recovery`);
                 w.lastSubagentCheckAt = now;
               } else if (w.resumeAttempts < maxRetries) {
-                tryResume(sid, w, "Stream stall");
+                if (busyStallStrategy === "abort") {
+                  await log("info", `Stream stall on ${short(sid)} (busyStallStrategy=abort): aborting before continue`);
+                  tryAbortAndResume(sid, w);
+                } else {
+                  tryResume(sid, w, "Stream stall");
+                }
               } else if (!w.gaveUp) {
                 w.gaveUp = true;
                 dbg(`State transition on ${short(sid)}: gaveUp=false -> true`);
@@ -13918,11 +13929,22 @@ var AutoResumePlugin = async (ctx, options) => {
               try {
                 const dead = getLastSilentDeadStream(await getSessionMessages(sid));
                 if (dead && dead.outputTokens >= silentDeadStreamMinTokens) {
-                  w.pendingRecovery = true;
-                  w.pendingRecoveryReason = `silent-${dead.finish}`;
-                  w.pendingRecoveryAt = Date.now();
-                  await log("info", `${short(sid)} - silent dead stream: finish=${dead.finish}, ${dead.outputTokens} output tokens, no text parts; resuming`);
-                  await tryResume(sid, w, `Silent dead stream (${dead.finish})`, continuePrompt);
+                  let busyAgain = false;
+                  try {
+                    const liveStatus = (await getSessionStatusMap())[sid];
+                    busyAgain = liveStatus === "busy" || liveStatus === "retry";
+                  } catch (e) {
+                    dbg(`session.idle sid=${short(sid)}: silent-dead-stream status check failed: ${e instanceof Error ? e.message : String(e)}`);
+                  }
+                  if (busyAgain) {
+                    dbg(`session.idle sid=${short(sid)}: silent-dead-stream recovery skipped, session is busy/retry again`);
+                  } else {
+                    w.pendingRecovery = true;
+                    w.pendingRecoveryReason = `silent-${dead.finish}`;
+                    w.pendingRecoveryAt = Date.now();
+                    await log("info", `${short(sid)} - silent dead stream: finish=${dead.finish}, ${dead.outputTokens} output tokens, no text parts; resuming`);
+                    await tryResume(sid, w, `Silent dead stream (${dead.finish})`, continuePrompt);
+                  }
                 }
               } catch (e) {
                 const errMsg = e instanceof Error ? e.message : String(e);
@@ -14194,6 +14216,20 @@ var AutoResumePlugin = async (ctx, options) => {
     tool: {
       task_complete: taskCompleteTool
     },
+    "chat.message": async (input) => {
+      const sid = input?.sessionID;
+      if (!sid)
+        return;
+      const w = ensureWatch(sid);
+      w.lastActivityAt = Date.now();
+      if (w.continuing)
+        return;
+      if (w.userCancelled || w.completionSignaled) {
+        w.userCancelled = false;
+        w.completionSignaled = false;
+        await log("info", `${short(sid)} - new user message, re-arming auto-resume`);
+      }
+    },
     "tool.execute.before": async (input) => {
       if (!input?.sessionID)
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-auto-resume",
-  "version": "1.1.11",
+  "version": "1.1.13",
   "description": "OpenCode plugin that automatically resumes stalled LLM sessions when thinking/streaming freezes mid-generation.",
   "keywords": [
     "opencode",