pi-tool-repair 0.1.0 → 0.1.2

package/README.md

@@ -40,6 +40,12 @@ Reverse-engineered from [Command Code](https://commandcode.ai/)'s tool parsing p
 pi install https://github.com/monotykamary/pi-tool-repair
 ```
 
+**With npm**:
+
+```bash
+npm install pi-tool-repair
+```
+
 **Manual** — add to `~/.pi/agent/settings.json`:
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-tool-repair",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Validate-then-repair extension for pi — fixes common LLM tool-call mistakes (null fields, stringified arrays, wrong field names, anchor bleed) before tools execute",
   "type": "module",
   "author": "Tom X Nguyen",

package/src/grammar-repair.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 export const GRAMMAR_NAMES = [
   "dsml",
@@ -109,7 +109,7 @@ export function loadGrammarRepairConfig(path = defaultConfigPath()): GrammarRepa
 }
 
 export function defaultConfigPath(): string {
-  return join(homedir(), ".pi", "agent", "extensions", "pi-tool-repair.json");
+  return join(getAgentDir(), "extensions", "pi-tool-repair.json");
 }
 
 export function normalizeGrammarRepairConfig(raw: Partial<GrammarRepairConfig> = {}): GrammarRepairConfig {

package/src/index.ts

@@ -296,6 +296,42 @@ export function wrapRootStringAsObject(
   };
 }
 
+// ─── Phase 1.5: Phantom toolUse normalization ───────────────────────────────
+//
+// Some providers (notably vLLM-backed endpoints like z.ai and Lilac) intermittently
+// emit finish_reason: "tool_calls" without any delta.tool_calls chunks. Pi maps this
+// to stopReason: "toolUse" with zero toolCall blocks — a broken state where the
+// agent loop thinks it should execute tools but has nothing to run, causing an
+// "abrupt stop". Detect and normalize to stopReason: "stop" so the agent exits
+// cleanly.
+
+export interface PhantomToolUseResult {
+  changed: boolean;
+  message: MinimalAssistantMessage;
+}
+
+export function normalizePhantomToolUse(
+  message: MinimalAssistantMessage,
+): PhantomToolUseResult {
+  if (message.role !== "assistant") return { changed: false, message };
+  if (message.stopReason !== "toolUse") return { changed: false, message };
+
+  const content = message.content;
+  const hasToolCalls = Array.isArray(content) &&
+    content.some((block) => typeof block === "object" && block !== null && !Array.isArray(block) && (block as Record<string, unknown>).type === "toolCall");
+
+  if (hasToolCalls) return { changed: false, message };
+
+  return {
+    changed: true,
+    message: {
+      ...message,
+      stopReason: "error",
+      errorMessage: "stream ended before tool_calls were received (vLLM phantom tool_use)",
+    },
+  };
+}
+
 // ─── Deep clone ───────────────────────────────────────────────────────────────
 
 export function deepClone(value: unknown): unknown {

package/tool-repair.ts

@@ -14,6 +14,12 @@
  *     - Strip leaked XML/sentinel tool-call grammars from assistant text/thinking
  *     - Recover complete, known-tool calls into pi toolCall blocks
  *
+ *   Phase 1.5: Phantom toolUse normalization (message_end hook, always-on)
+ *     - Detect stopReason: "toolUse" with zero toolCall blocks
+ *     - Convert to a retryable error to trigger pi's auto-retry mechanism
+ *     - Guards against vLLM streaming bugs where finish_reason: "tool_calls"
+ *       is emitted without any delta.tool_calls chunks
+ *
  *   Phase 2: Validate-then-repair (tool_call hook)
  *     - Validate input against the tool's schema
  *     - On failure, walk the validator's issue list and apply targeted repairs
@@ -35,6 +41,7 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
+  DEFAULT_CONFIG,
   hasAnchorBleedBug,
   sanitizeSchemaAnchors,
   stripAnchorBleedInPlace,
@@ -45,16 +52,39 @@ import {
   BUILTIN_SCHEMAS,
   loadGrammarRepairConfig,
   repairAssistantMessageGrammarLeaks,
+  normalizePhantomToolUse,
   type MinimalAssistantMessage,
 } from "./src/index.js";
 
+// Safely access ctx.model without throwing on stale contexts.
+// After session replacement (newSession/fork/switchSession/reload), the
+// extension runner invalidates stale contexts and ctx.model throws.
+// When that happens, the request belongs to a dead session — bail out.
+function safeGetModel(ctx: { model?: any }): any | undefined {
+  try {
+    return ctx.model;
+  } catch {
+    return undefined;
+  }
+}
+
+// Safely call pi.getActiveTools() without throwing on stale contexts.
+function safeGetActiveTools(pi: ExtensionAPI): string[] {
+  try {
+    return pi.getActiveTools();
+  } catch {
+    return [];
+  }
+}
+
 export default function (pi: ExtensionAPI) {
   const grammarRepairConfig = loadGrammarRepairConfig();
 
   // Phase 0: Schema poisoning defense (before_provider_request)
   // Strip regex anchors from JSON Schema patterns for models where they leak
   pi.on("before_provider_request", (event, ctx) => {
-    if (!hasAnchorBleedBug(ctx.model)) return;
+    const model = safeGetModel(ctx);
+    if (!model || !hasAnchorBleedBug(model)) return;
 
     const payload = event.payload as Record<string, unknown>;
     if (!payload || typeof payload !== "object") return;
@@ -89,16 +119,64 @@ export default function (pi: ExtensionAPI) {
     }
   });
 
-  // Phase 1: Grammar leak repair (message_end)
-  // Promote leaked XML/sentinel tool-call grammars from assistant text/thinking
-  // into pi toolCall blocks. Disabled by default and configured via
+  // Phase 1 + 1.5: Grammar leak repair + phantom toolUse normalization (message_end)
+  //
+  // Phase 1.5 (always-on): Detect stopReason: "toolUse" with zero toolCall blocks
+  // and convert to a retryable error (stopReason: "error"). This triggers pi's
+  // built-in auto-retry mechanism so the agent re-prompts automatically. This
+  // guards against vLLM streaming bugs where finish_reason: "tool_calls" is emitted
+  // without any delta.tool_calls chunks.
+  //
+  // Phase 1 (opt-in): Promote leaked XML/sentinel tool-call grammars from
+  // assistant text/thinking into pi toolCall blocks. Configured via
   // ~/.pi/agent/extensions/pi-tool-repair.json.
   pi.on("message_end", (event) => {
-    if (!grammarRepairConfig.enabled) return;
     if (event.message.role !== "assistant") return;
 
+    // Phase 1.5: Phantom toolUse normalization (always-on)
+    const currentMessage = event.message as unknown as MinimalAssistantMessage;
+    const phantomResult = normalizePhantomToolUse(currentMessage);
+
+    if (phantomResult.changed) {
+      if (DEFAULT_CONFIG.debug) {
+        process.stderr.write(
+          `[pi-tool-repair] phantom-tooluse: converted stopReason from "toolUse" to retryable error (no toolCall blocks)\n`,
+        );
+      }
+
+      // If grammar repair is also enabled, run it on the normalized message so
+      // it can still recover leaked tool calls from the text content. If grammar
+      // repair recovers calls, it will set stopReason back to "toolUse".
+      if (grammarRepairConfig.enabled) {
+        const knownTools = new Set(
+          safeGetActiveTools(pi)
+            .filter((name): name is string => typeof name === "string" && name.length > 0),
+        );
+        const grammarResult = repairAssistantMessageGrammarLeaks(
+          phantomResult.message,
+          grammarRepairConfig,
+          knownTools,
+        );
+        if (grammarResult.changed) {
+          if (grammarRepairConfig.debug) {
+            const calls = grammarResult.recoveredCalls.map((call) => `${call.grammar}:${call.name}`).join(",") || "none";
+            process.stderr.write(
+              `[pi-tool-repair] grammar-repair mode=${grammarRepairConfig.mode} ` +
+              `stripped=${grammarResult.strippedRanges} recovered=${calls}\n`,
+            );
+          }
+          return { message: grammarResult.message as any };
+        }
+      }
+
+      return { message: phantomResult.message as any };
+    }
+
+    // Phase 1: Grammar leak repair (opt-in)
+    if (!grammarRepairConfig.enabled) return;
+
     const knownTools = new Set(
-      pi.getActiveTools()
+      safeGetActiveTools(pi)
         .filter((name): name is string => typeof name === "string" && name.length > 0),
     );
 
@@ -126,8 +204,10 @@ export default function (pi: ExtensionAPI) {
     const toolName = event.toolName;
     const input = (event as any).input;
 
+    const model = safeGetModel(ctx);
+
     // Defense-in-depth: strip anchor-bleed from generated values
-    if (hasAnchorBleedBug(ctx.model)) {
+    if (model && hasAnchorBleedBug(model)) {
       if (input && typeof input === "object") {
         stripAnchorBleedInPlace(input);
       }