@saccolabs/pi-claude-cli 0.4.1 → 0.4.3

package/README.md

@@ -49,6 +49,38 @@ Requires the `claude` binary on your login-shell PATH (`npm install -g @anthropi
 - Cross-platform subprocess management (Windows, macOS, Linux)
 - Inactivity timeout and process registry for cleanup
 
+## Architecture
+
+`docs/ARCHITECTURE.md` covers the turn lifecycle, the three-way tool split,
+the two-ledger session model, error recovery, and the CLI compatibility
+notes (including the 2.x control-protocol shape).
+
+## What your Claude environment contributes
+
+Each turn runs a real `claude -p` subprocess in your workspace, so your
+Claude Code environment participates through three doors:
+
+1. **Bridged tools** — the six built-ins (Read/Write/Edit/Bash/Grep/Glob)
+   and pi custom tools become pi tool calls; pi executes them.
+2. **CLI-side execution** — your personal/project MCP servers, WebSearch,
+   and sub-agents run _inside_ the CLI between cycles. They appear in the
+   transcript as one-line markers (`[Claude Code · WebSearch {…}]`) and
+   bill your plan.
+3. **Prompt-level osmosis** — the CLI auto-loads project CLAUDE.md and
+   memory, your hooks fire, and skills can load twice (natively via
+   claude, and again via pi's own `~/.claude/skills` support).
+
+### Hermetic mode
+
+Set `PI_CLAUDE_CLI_HERMETIC=1` to keep that environment out of pi turns:
+the subprocess runs with `--strict-mcp-config` (only this extension's
+schema-only custom-tools server loads) and an empty `--setting-sources`
+(no user/project/local settings — hooks, auto-memory, permission
+allowlists). Model access and your subscription login are unaffected.
+
+Related knobs: `PI_CLAUDE_CLI_TIMEOUT_MS` overrides the 300s inactivity
+timeout (CLI-side tools can be silent on stdout for minutes).
+
 ## License
 
 MIT

package/index.ts

@@ -15,6 +15,7 @@ import {
   killAllProcesses,
 } from "./src/process-manager.js";
 import { getCustomToolDefs, writeMcpConfig } from "./src/mcp-config.js";
+import { rewriteOverflowMessage } from "./src/overflow.js";
 
 // Kill all active Claude subprocesses on process exit to prevent orphans
 process.on("exit", killAllProcesses);
@@ -120,6 +121,13 @@ export default function (pi: ExtensionAPI) {
       PROVIDER_ID,
     );
 
+    // Overflow recovery: rewrite provider-scoped context-limit errors to
+    // the prefix pi's auto-compaction recognizes (see src/overflow.ts).
+
+    (pi.on as any)("message_end", (event: any, ctx: any) => {
+      return rewriteOverflowMessage(event?.message ?? {}, ctx?.model?.provider);
+    });
+
     pi.registerProvider(PROVIDER_ID, {
       baseUrl: "pi-claude-cli",
       apiKey: "unused",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saccolabs/pi-claude-cli",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Pi coding agent extension that routes LLM calls through the Claude Code CLI",
   "main": "index.ts",
   "keywords": [

package/src/overflow.ts

@@ -0,0 +1,63 @@
+/**
+ * Context-overflow error normalization (issue #4).
+ *
+ * When a request exceeds the model's context window, pi can recover by
+ * compacting the conversation and retrying — but only if it recognizes the
+ * failure. Detection runs on the finalized assistant message: pi checks
+ * `errorMessage` against its known overflow patterns, and the generic
+ * fallback it always recognizes is a `context_length_exceeded` prefix
+ * (see pi's custom-provider docs, "Context Overflow Errors").
+ *
+ * The Claude CLI surfaces the Anthropic API's error text verbatim, which pi
+ * does not recognize. This module rewrites ONLY provider-scoped, clearly
+ * overflow-shaped errors; rate limits and transient failures must never be
+ * rewritten (that would trigger compaction instead of pi's retry/backoff).
+ */
+
+/**
+ * Anthropic API overflow phrasings, matched conservatively:
+ * - "prompt is too long: 214315 tokens > 200000 maximum"
+ * - "input length and `max_tokens` exceed context limit: ..."
+ */
+const OVERFLOW_PATTERNS: RegExp[] = [
+  /prompt is too long/i,
+  /input length and .?max_tokens.? exceed context limit/i,
+];
+
+export const OVERFLOW_PREFIX = "context_length_exceeded";
+
+/** True when the error text is an overflow pi should recover from. */
+export function isOverflowError(errorMessage: string): boolean {
+  if (errorMessage.includes(OVERFLOW_PREFIX)) return false; // already rewritten
+  return OVERFLOW_PATTERNS.some((pattern) => pattern.test(errorMessage));
+}
+
+/**
+ * `message_end` handler body: returns the rewritten assistant message when
+ * this provider produced a recognizable overflow error, undefined otherwise
+ * (pi keeps the message unchanged).
+ */
+export function rewriteOverflowMessage(
+  message: {
+    role?: string;
+    provider?: string;
+    stopReason?: string;
+    errorMessage?: string;
+  },
+  ctxProvider?: string,
+): { message: Record<string, unknown> } | undefined {
+  if (message.role !== "assistant") return undefined;
+  if (message.stopReason !== "error") return undefined;
+  if (message.provider !== "pi-claude-cli" && ctxProvider !== "pi-claude-cli")
+    return undefined;
+
+  const errorMessage = message.errorMessage ?? "";
+  if (!isOverflowError(errorMessage)) return undefined;
+
+  return {
+    message: {
+      ...message,
+      errorMessage: `${OVERFLOW_PREFIX}: ${errorMessage}`,
+    },
+  };
+}

package/src/process-manager.ts

@@ -21,6 +21,12 @@ import type { ChildProcess } from "node:child_process";
  * @param options - Optional cwd, AbortSignal, and effort level
  * @returns The spawned ChildProcess with piped stdin/stdout/stderr
  */
+/** Truthy PI_CLAUDE_CLI_HERMETIC opts in to hermetic mode (see README). */
+function isHermetic(): boolean {
+  const value = (process.env.PI_CLAUDE_CLI_HERMETIC ?? "").toLowerCase();
+  return value === "1" || value === "true" || value === "yes";
+}
+
 export function spawnClaude(
   modelId: string,
   systemPrompt?: string,
@@ -47,6 +53,16 @@ export function spawnClaude(
     "stdio",
   ];
 
+  // Hermetic mode: keep the user's Claude Code environment out of pi turns.
+  // --strict-mcp-config loads ONLY the servers from --mcp-config (our
+  // schema-only custom-tools server survives; personal/project MCP servers
+  // do not), and an empty --setting-sources skips user/project/local
+  // settings — hooks, CLAUDE.md auto-memory, permission allowlists.
+  // Both flags verified accepted on claude 2.1.237.
+  if (isHermetic()) {
+    args.push("--strict-mcp-config", "--setting-sources", "");
+  }
+
   if (options?.resumeSessionId) {
     // Resume an existing session — CLI loads prior conversation from disk
     args.push("--resume", options.resumeSessionId);

package/src/provider.ts

@@ -81,9 +81,20 @@ export function streamViaCli(
 ): AssistantMessageEventStream {
   const stream = createAssistantMessageEventStream();
 
-  (async () => {
+  /**
+   * One subprocess attempt. Returns "resume-miss" (without touching the
+   * stream) when a --resume pointed at a CLI session that does not exist —
+   * forks copy pi history into a NEW session id, so the prior-provider-turn
+   * heuristic says resume while the CLI cache is keyed to the old id (#2).
+   * The driver below retries once with a full-history replay, which also
+   * re-registers the CLI cache under the current session id.
+   */
+  async function runOnce(
+    forceFullReplay: boolean,
+  ): Promise<"ok" | "resume-miss"> {
     let proc: ReturnType<typeof spawnClaude> | undefined;
     let abortHandler: (() => void) | undefined;
+    let resumeMiss = false;
 
     try {
       const cwd = options?.cwd ?? process.cwd();
@@ -102,7 +113,9 @@ export function streamViaCli(
           (m?.provider === "pi-claude-cli" || m?.api === "pi-claude-cli"),
       );
       const resumeSessionId =
-        options?.sessionId && hasPriorCliTurn ? options.sessionId : undefined;
+        !forceFullReplay && options?.sessionId && hasPriorCliTurn
+          ? options.sessionId
+          : undefined;
 
       // Build prompt: if resuming, only send the latest user turn;
       // otherwise build the full flattened conversation history
@@ -195,7 +208,7 @@ export function streamViaCli(
 
         if (options.signal.aborted) {
           abortHandler();
-          return;
+          return "ok";
         }
         options.signal.addEventListener("abort", abortHandler, { once: true });
       }
@@ -308,7 +321,18 @@ export function streamViaCli(
               (Array.isArray(r.errors) && r.errors.length > 0
                 ? r.errors.join("; ")
                 : `Claude CLI returned ${r.subtype ?? "non-success result"}`);
-            endStreamWithError(errMsg);
+            if (
+              resumeSessionId &&
+              /No conversation found with session ID/i.test(errMsg)
+            ) {
+              // Recoverable: the driver replays full history once. The CLI
+              // also exits non-zero after this result — silence this
+              // attempt's close/error handlers so the retry owns the stream.
+              resumeMiss = true;
+              broken = true;
+            } else {
+              endStreamWithError(errMsg);
+            }
           }
           if (!isError) {
             // Authoritative episode usage + final-answer safety net.
@@ -326,6 +350,8 @@ export function streamViaCli(
         rl.on("close", resolve);
       });
 
+      if (resumeMiss) return "resume-miss";
+
       // Push done event after readline closes (async). Pushing synchronously
       // inside handleMessageStop prevents pi from executing tools.
       // Guard with streamEnded to avoid pushing done after an error was already pushed.
@@ -356,6 +382,24 @@ export function streamViaCli(
         });
         stream.end();
       }
+      return "ok";
+    } finally {
+      // Clean up this attempt's abort listener
+      if (options?.signal && abortHandler) {
+        options.signal.removeEventListener("abort", abortHandler);
+      }
+    }
+  }
+
+  (async () => {
+    try {
+      const outcome = await runOnce(false);
+      if (outcome === "resume-miss") {
+        console.error(
+          "[pi-claude-cli] CLI session missing for --resume — replaying full history under the current session id",
+        );
+        await runOnce(true);
+      }
     } catch (err: any) {
       stream.push({
         type: "error",
@@ -364,10 +408,6 @@ export function streamViaCli(
       } as any);
       stream.end();
     } finally {
-      // Clean up abort listener
-      if (options?.signal && abortHandler) {
-        options.signal.removeEventListener("abort", abortHandler);
-      }
       cleanupSystemPromptFile();
     }
   })();