pi-invisible-continue 0.3.2 → 0.3.4

package/README.md

@@ -4,7 +4,7 @@
 
 **Invisible session continuation for [pi](https://github.com/earendil-works/pi-coding-agent)**
 
-_Resume the agentic loop without the LLM seeing any new prompt at all._
+_Resume the agentic loop without the LLM seeing a new prompt._
 
 [![pi extension](https://img.shields.io/badge/pi-extension-blueviolet)](https://github.com/earendil-works/pi-coding-agent)
 [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
@@ -15,66 +15,66 @@ _Resume the agentic loop without the LLM seeing any new prompt at all._
 
 ## The Problem
 
-Every existing "continue" extension sends a **visible user message** to the LLM:
+Most “continue” extensions send user text to the LLM:
 
 | Package | What the LLM sees |
 |---------|-------------------|
-| `pi-continue` | `"Continue from the same-session pi-continue/v3 handoff Pi just saved..."` (full handoff doc) |
-| `pi-hodor` | `"continue"` (literal text) |
-| `pi-auto-continue` | `"continue"` (literal text) |
-| `pi-retry` | `"Continue"` on max-tokens, or hidden custom trigger on errors |
+| `pi-continue` | A full handoff document |
+| `pi-hodor` | `"continue"` |
+| `pi-auto-continue` | `"continue"` |
 
-Every one of those **changes the LLM's context** with new user text. That text influences the next response, sometimes in unintended ways — model changes course, re-reads things it already processed, or treats a bare `"continue"` as a new task.
-
----
+That text can influence the next response or be interpreted as a new task.
 
 ## The Solution
 
-`pi-invisible-continue` captures the internal `Agent` instance via a prototype monkey-patch on `Agent.prototype.prompt`. When `/continue` is invoked, it calls `agent.prompt([])` directly — starting a fresh agent loop with an **empty prompt array**. No message is injected into the context at all:
+`pi-invisible-continue` starts a normal Pi session turn with a hidden custom marker. A `context` hook removes that marker before provider serialization, so the LLM receives no new prompt text.
 
-- The agent loop restarts
-- The LLM receives **the exact same message list it had before**
-- No new text, no handoff, no pollution, no session artifact
-- Nothing in `convertToLlm`'s path — no filtering needed
+The continuation deliberately goes through `AgentSession`:
 
----
+- Pi’s session-level busy state remains accurate.
+- A concurrent prompt is queued through the native follow-up path rather than racing it.
+- Auto-retry, compaction, abort, and `agent_settled` behavior remain intact.
+- The marker is hidden from the TUI and filtered from every LLM request.
 
 ## How It Works
 
-```
-Extension loads
-  → Monkey-patches Agent.prototype.prompt to capture the Agent instance
-  → First real prompt stores the reference
-
-User types "/continue"
-  → agent.prompt([]) called directly
-  → runAgentLoop([], contextSnapshot, ...)
-  → prompts array is empty — no message emitted, no message pushed to context
-  → runLoop → streamAssistantResponse → convertToLlm(unmodified messages)
-  → LLM sees same messages as before → responds naturally
+`/continue` calls:
+
+```typescript
+pi.sendMessage(
+  {
+    customType: "pi-invisible-continue:resume",
+    content: [],
+    display: false,
+  },
+  {
+    triggerTurn: true,
+    deliverAs: "followUp",
+  },
+);
 ```
 
-### Why `agent.prompt([])` and not `agent.continue()`?
+Pi starts the turn immediately when idle or queues it when another turn is active. Before the provider request, the extension removes its custom marker from `event.messages`.
 
-`agent.continue()` has a guard that throws `Cannot continue from message role: assistant` when the last message is from the assistant — which it always is when the agent stops. `agent.prompt([])` starts a fresh loop from the current context snapshot without that restriction.
+### Why not `Agent.prompt([])`?
 
-### Trade-off: bypasses AgentSession
+Calling the low-level agent directly bypasses `AgentSession._runAgentPrompt()`. Pi can then report the session as idle while `Agent.activeRun` is already processing. A user prompt may be routed as a fresh prompt and fail with:
 
-`agent.prompt([])` is called on the `Agent` directly, bypassing `AgentSession._runAgentPrompt()`. This means auto-compaction is not triggered after a `/continue`. Auto-retry is not a concern — [pi-retry](https://github.com/monotykamary/pi-retry) covers that gap by listening for `agent_end` events and re-triggering the loop on errors. Since the agent still emits events through `AgentSession`'s subscriber, pi-retry's handlers fire normally even after an `agent.prompt([])` continuation.
+> Agent is already processing a prompt. Use steer() or followUp() to queue messages, or wait for completion.
 
----
+Using `sendMessage` keeps one authoritative lifecycle and avoids that split-brain busy state.
 
-## Usage
+### Session artifact
+
+The session journal contains one hidden custom entry per continuation. It has no display content and is removed before every provider call, but it is still bookkeeping in the saved session. This is the correctness trade-off until Pi exposes a public session-level resume API that adds no entry.
 
-Once loaded, use `/continue`:
+## Usage
 
 | Command | What it does |
 |---------|-------------|
-| `/continue` | Resume the loop invisibly. Waits for idle, then fires. |
-| `/continue status` | Show agent idle state, captured-agent status, and last assistant text (debug). |
-| `/continue help` | Show this reference. |
-
----
+| `/continue` | Start or queue an invisible continuation. |
+| `/continue status` | Show session idle state and the last assistant text. |
+| `/continue help` | Show the command reference. |
 
 ## Installation
 
@@ -88,7 +88,7 @@ Or install from GitHub:
 pi install https://github.com/monotykamary/pi-invisible-continue
 ```
 
-Or in `~/.pi/agent/settings.json`:
+Or add it to `~/.pi/agent/settings.json`:
 
 ```json
 {
@@ -98,36 +98,25 @@ Or in `~/.pi/agent/settings.json`:
 }
 ```
 
-Then `/reload` or restart pi.
+Then run `/reload` or restart Pi.
 
-For quick one-off tests:
+For a one-off test:
 
 ```bash
 pi -e ./continue.ts
 ```
 
----
-
-## Comparison with Other Packages
+## Comparison
 
 | Feature | pi-invisible-continue | pi-continue | pi-hodor | pi-auto-continue |
 |---------|----------------------|-------------|----------|-------------------|
-| LLM sees new user text | ❌ No | ✅ Handoff doc | ✅ "continue" | ✅ "continue" |
-| Session pollution | None | Full compaction entry + user message | 1 user message | 1 user message |
-| Mechanism | `agent.prompt([])` | `sendMessage` + handoff | `sendMessage` | `sendMessage` |
-| Auto-triggered | ❌ Manual only | ✅ On compaction | ✅ On error/length | ✅ On agent_end |
-| Retry integration | ❌ | ❌ | ✅ Error patterns | ❌ |
-| Complexity | Prototype patch + 1 call | 49 files, multi-stage | 2 files, config-driven | 1 file, loop-based |
-
----
-
-## About the Hack
-
-The extension uses the public `@earendil-works/pi-agent-core` package (which pi's extension loader resolves to the same module instance used internally) to import `Agent` and monkey-patch `Agent.prototype.prompt`. This captures the live `Agent` instance when pi first calls `agent.prompt()` during normal operation.
-
-Then `/continue` calls `agent.prompt([])` — an empty prompt array. The `runAgentLoop` function spreads the prompts into the context messages, so with an empty array, nothing is added. The loop starts from the unmodified context snapshot and the LLM continues naturally.
+| LLM sees new user text | No | Handoff doc | `"continue"` | `"continue"` |
+| Visible transcript entry | No | Yes | Yes | Yes |
+| Hidden session bookkeeping | One custom entry | Compaction + user entry | User entry | User entry |
+| Native session lifecycle | Yes | Yes | Yes | Yes |
+| Auto-triggered | No | On compaction | On error/length | On `agent_end` |
 
-This is the approach discussed in [pi issue #3721](https://github.com/earendil-works/pi/issues/3721) ("Feature request: Resume agentic loop without sending a message"). The upstream fix would be exposing `agent.continue()` (or a variant that works from `assistant` last-message) on `AgentSession`, but this extension achieves the same effect without waiting for a core change.
+The desired upstream primitive is a public `AgentSession.resume()` operation that preserves native lifecycle behavior without adding a marker. Until then, a filtered custom message is safer than bypassing the session.
 
 ## License
 

package/continue.ts

@@ -1,144 +1,43 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { Agent } from "@earendil-works/pi-agent-core";
 import {
   CONTINUE_COMMAND_DESCRIPTION,
+  INVISIBLE_CONTINUE_CUSTOM_TYPE,
   getLastAssistantMessageText,
+  isInvisibleContinueMarker,
 } from "./src/index.js";
 
 /**
- * pi-invisible-continue — resume the agentic loop without the LLM seeing any new prompt.
- *
- * Strategy:
- *   - Monkey-patch Agent.prototype.subscribe to capture the Agent instance
- *   - /continue calls agent.prompt([]) directly, starting a fresh agent loop
- *     with an empty prompt — no message is injected into context at all
- *   - The LLM receives the exact same message list it had before
- *   - No session JSONL artifact, no convertToLlm involvement, no filter needed
- *
- * This bypasses AgentSession._runAgentPrompt, so auto-compaction is not
- * triggered after a manual /continue. Auto-retry is not a concern — pi-retry
- * covers that gap via its agent_end handler, which still fires because the
- * agent's processEvents propagates to AgentSession's subscriber normally.
- *
- * Module resolution:
- *   The Agent class is imported from @earendil-works/pi-agent-core.
- *   This package does NOT list pi-agent-core as a devDependency — there is
- *   no local node_modules copy. When jiti loads this extension, its alias
- *   system rewrites the import specifier to pi's bundled copy, so the
- *   subscribe/continue patches apply to the SAME Agent class that
- *   AgentSession uses. Previously, a local node_modules/@earendil-works/pi-agent-core
- *   caused jiti to resolve the import to a different class — patching the
- *   wrong prototype and leaving _agent permanently null.
+ * Resume through AgentSession instead of calling Agent.prompt([]) directly.
+ * The hidden custom message starts or queues a canonical session turn, while
+ * the context hook removes it before provider serialization.
  */
+export default function invisibleContinueExtension(pi: ExtensionAPI) {
+  pi.on("context", (event) => {
+    const messages = event.messages.filter((message) => !isInvisibleContinueMarker(message));
+    if (messages.length !== event.messages.length) return { messages };
+  });
 
-// Capture the live Agent instance when AgentSession subscribes to it.
-// subscribe() is called during AgentSession construction — fires on both
-// fresh sessions and session resumes, unlike prompt().
-//
-// Chain the previous patch (if pi-retry or pi-vcc already patched it)
-// so all extensions can coexist.
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-let _agent: Agent | null = null;
-const _origSubscribe = Agent.prototype.subscribe as (this: Agent, ...args: any[]) => any;
-Agent.prototype.subscribe = function (this: Agent, ...args: any[]) {
-  _agent = this;
-  return _origSubscribe.apply(this, args);
-};
-
-// Mutex: only one invisible continue may be in-flight at a time.
-// Without this, concurrent /continue (or /continue during pi-retry/pi-vcc
-// auto-continuation) race through waitForIdle() and both call prompt([]),
-// producing "Agent is already processing".
-let _continueInProgress = false;
-
-// Timestamp of the last completed invisible continue.
-// Used to avoid double continuation when continue() unblocks after
-// triggerInvisibleContinue just ran.
-let _lastInvisibleContinueTime = 0;
-
-// Monkey-patch continue() so the session's built-in loop cooperates with
-// our mutex AND can convert the "Cannot continue from assistant" error
-// into a prompt([]) call when the agent was mid-task.
-// Without this, the session's continue() would throw when the last message
-// is an assistant (common after compaction), and the agent loop would die
-// leaving mid-task work unfinished.
-//
-// When continue() throws "Cannot continue from message role: assistant":
-// - stopReason "stop" → agent finished cleanly, don't continue
-// - stopReason "aborted" → user cancelled, don't continue
-// - stopReason "error" → pi-retry handles errors, don't race it
-// - stopReason "toolUse" or "length" → mid-task, fall back to prompt([])
-//
-// Chains the previous patch (pi-retry, pi-vcc) so all mutexes are respected.
-const _origContinue = Agent.prototype.continue;
-Agent.prototype.continue = function (this: Agent) {
-  const self = this;
-  return (async (): Promise<void> => {
-    while (_continueInProgress) {
-      await new Promise(r => setTimeout(r, 10));
-    }
-    try {
-      await _origContinue.call(self);
-    } catch (e: any) {
-      const msg = e?.message ?? '';
-      if (msg.includes('Cannot continue from message role') ||
-          msg.includes('Cannot continue from an assistant message')) {
-        // Check stopReason — only continue if the agent was mid-task
-        const lastMsg = self.state.messages[self.state.messages.length - 1];
-        if (lastMsg?.role === 'assistant' &&
-            lastMsg.stopReason !== 'stop' &&
-            lastMsg.stopReason !== 'aborted' &&
-            lastMsg.stopReason !== 'error') {
-          // Agent was mid-task — fall back to prompt([])
-          // Guard: if an invisible continue just completed, don't double-run
-          if (!_continueInProgress && Date.now() - _lastInvisibleContinueTime > 500) {
-            _continueInProgress = true;
-            try {
-              await self.prompt([]);
-            } catch {
-              // Agent already processing or other transient error
-            } finally {
-              _continueInProgress = false;
-            }
-          }
-        }
-        // For stop/aborted/error: return void, the session loop exits naturally
-        return;
-      }
-      if (msg.includes('Agent is already processing')) {
-        return;
-      }
-      throw e;
-    }
-  })();
-};
-
-export default function (pi: ExtensionAPI) {
   pi.registerCommand("continue", {
     description: CONTINUE_COMMAND_DESCRIPTION,
     handler: async (args, ctx) => {
-      await runContinueCommand(ctx, args);
+      runContinueCommand(pi, ctx, args);
     },
   });
-
-  pi.on("session_start", () => {
-    _continueInProgress = false;
-    _lastInvisibleContinueTime = 0;
-  });
 }
 
-async function runContinueCommand(
+function runContinueCommand(
+  pi: ExtensionAPI,
   ctx: ExtensionCommandContext,
   args: string,
-): Promise<void> {
-  if (args.trim().toLowerCase() === "status") {
+): void {
+  const subcommand = args.trim().toLowerCase();
+
+  if (subcommand === "status") {
     const last = getLastAssistantMessageText(ctx.sessionManager.getEntries());
-    const idle = ctx.isIdle();
     ctx.ui.notify(
       [
         "pi-invisible-continue status:",
-        `  Agent idle: ${idle ? "yes" : "no"}`,
-        `  Captured agent: ${_agent ? "yes" : "no"}`,
+        `  Agent idle: ${ctx.isIdle() ? "yes" : "no"}`,
         `  Last assistant: ${last ?? "(none)"}`.slice(0, 120),
       ].join("\n"),
       "info",
@@ -146,7 +45,7 @@ async function runContinueCommand(
     return;
   }
 
-  if (args.trim().toLowerCase() === "help") {
+  if (subcommand === "help") {
     ctx.ui.notify(
       [
         "pi-invisible-continue  /continue     Resume loop invisibly",
@@ -158,38 +57,16 @@ async function runContinueCommand(
     return;
   }
 
-  if (!_agent) {
-    ctx.ui.notify(
-      "pi-invisible-continue: Agent instance not captured. Internal error?",
-      "warning",
-    );
-    return;
-  }
-
-  if (!ctx.isIdle()) {
-    await ctx.waitForIdle();
-  }
-
-  // Guard: if pi-retry or pi-vcc already has an invisible continue in-flight,
-  // skip — their prompt([]) will resume the loop.
-  if (_continueInProgress) {
-    ctx.ui.notify(
-      "pi-invisible-continue: Another invisible continue is already in progress.",
-      "info",
-    );
-    return;
-  }
-  _continueInProgress = true;
-
-  try {
-    await _agent.waitForIdle();
-    try {
-      await _agent.prompt([]);
-    } catch {
-      // Agent is already processing — something else is driving.
-    }
-  } finally {
-    _continueInProgress = false;
-    _lastInvisibleContinueTime = Date.now();
-  }
+  pi.sendMessage(
+    {
+      customType: INVISIBLE_CONTINUE_CUSTOM_TYPE,
+      content: [],
+      display: false,
+      details: undefined,
+    },
+    {
+      triggerTurn: true,
+      deliverAs: "followUp",
+    },
+  );
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-invisible-continue",
-  "version": "0.3.2",
-  "description": "Invisible session continuation for pi \u2014 resume the agentic loop without sending ANY prompt the LLM can see",
+  "version": "0.3.4",
+  "description": "Invisible session continuation for pi — resume the agentic loop without sending ANY prompt the LLM can see",
   "type": "module",
   "author": "Tom X Nguyen",
   "license": "MIT",
@@ -30,16 +30,8 @@
     "src/",
     "README.md"
   ],
-  "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit",
-    "lint:dead": "knip --no-gitignore"
-  },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.79.1",
-    "@earendil-works/pi-coding-agent": "0.79.4",
+    "@earendil-works/pi-coding-agent": "^0.79.8",
     "@types/node": "25.9.1",
     "@vitest/coverage-v8": "4.1.7",
     "knip": "6.14.1",
@@ -55,5 +47,12 @@
     "brace-expansion": "5.0.6",
     "protobufjs": "8.4.0",
     "ws": "8.20.1"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint:dead": "knip --no-gitignore"
   }
-}
+}

package/src/index.ts

@@ -1,18 +1,19 @@
-/**
- * Shared constants and utilities for pi-invisible-continue.
- *
- * The extension is small enough that heavy shared logic is unnecessary.
- * The command description and a session introspection helper are the only exports.
- */
+/** Shared constants and utilities for pi-invisible-continue. */
 
-/** Description shown in the / commands list. */
 export const CONTINUE_COMMAND_DESCRIPTION =
   "Resume the agentic loop without sending a prompt the LLM can read";
 
-/**
- * Extract the text content of the last assistant message in the session.
- * Returns undefined if no assistant message exists.
- */
+export const INVISIBLE_CONTINUE_CUSTOM_TYPE = "pi-invisible-continue:resume";
+
+export function isInvisibleContinueMarker(message: unknown): boolean {
+  if (!message || typeof message !== "object") return false;
+  const candidate = message as { role?: unknown; customType?: unknown };
+  return (
+    candidate.role === "custom" &&
+    candidate.customType === INVISIBLE_CONTINUE_CUSTOM_TYPE
+  );
+}
+
 export function getLastAssistantMessageText(
   entries: ReadonlyArray<{ type: string; message?: { role?: string; content?: unknown } }>,
 ): string | undefined {
@@ -21,17 +22,17 @@ export function getLastAssistantMessageText(
     if (
       entry.type === "message" &&
       entry.message?.role === "assistant" &&
-      entry.message?.content
+      entry.message.content
     ) {
       const content = entry.message.content;
       if (typeof content === "string") return content;
       if (Array.isArray(content)) {
         const textBlocks = content.filter(
-          (block: any): block is { type: "text"; text: string } =>
-            typeof block === "object" &&
-            block !== null &&
-            block.type === "text" &&
-            typeof block.text === "string",
+          (block: unknown): block is { type: "text"; text: string } => {
+            if (!block || typeof block !== "object") return false;
+            const candidate = block as { type?: unknown; text?: unknown };
+            return candidate.type === "text" && typeof candidate.text === "string";
+          },
         );
         if (textBlocks.length === 0) return undefined;
         return textBlocks.map((block) => block.text).join("\n");