@saccolabs/pi-claude-cli 0.4.0

package/src/provider.ts

@@ -0,0 +1,358 @@
+/**
+ * Provider orchestration for bridging pi requests to the Claude CLI subprocess.
+ *
+ * streamViaCli is the core function that:
+ * 1. Builds the prompt from conversation context
+ * 2. Spawns a Claude CLI subprocess with correct flags
+ * 3. Writes the user message to stdin as NDJSON
+ * 4. Reads stdout line-by-line, parsing NDJSON
+ * 5. Routes stream events through the event bridge to pi's stream
+ * 6. Handles result/error messages and cleans up the subprocess
+ * 7. Implements break-early: kills subprocess at message_stop when
+ *    built-in or custom-tools MCP tool_use blocks are seen
+ * 8. Hardened lifecycle: inactivity timeout, subprocess exit handler,
+ *    streamEnded guard, abort via SIGKILL, process registry
+ */
+
+import { createInterface } from "node:readline";
+import {
+  type AssistantMessageEventStream,
+  createAssistantMessageEventStream,
+  type Model,
+  type SimpleStreamOptions,
+} from "@earendil-works/pi-ai";
+import {
+  buildPrompt,
+  buildSystemPrompt,
+  buildResumePrompt,
+} from "./prompt-builder.js";
+import {
+  spawnClaude,
+  writeUserMessage,
+  cleanupProcess,
+  captureStderr,
+  forceKillProcess,
+  registerProcess,
+  cleanupSystemPromptFile,
+} from "./process-manager.js";
+import { parseLine } from "./stream-parser.js";
+import { createEventBridge } from "./event-bridge.js";
+import { handleControlRequest } from "./control-handler.js";
+import { mapThinkingEffort } from "./thinking-config.js";
+import { isPiKnownClaudeTool } from "./tool-mapping.js";
+/** Inactivity timeout: kill subprocess if no stdout for 180 seconds (3 minutes). */
+const INACTIVITY_TIMEOUT_MS = 180_000;
+
+/** Extended stream options: pi's SimpleStreamOptions plus optional cwd and mcpConfigPath */
+type StreamViaCLiOptions = SimpleStreamOptions & {
+  cwd?: string;
+  mcpConfigPath?: string;
+};
+
+/**
+ * Stream a response from Claude CLI as an AssistantMessageEventStream.
+ *
+ * Orchestrates the full subprocess lifecycle: spawn, write prompt, parse NDJSON,
+ * bridge events, handle result, and clean up. Implements break-early pattern:
+ * at message_stop, if any built-in or custom-tools MCP tool was seen, kills
+ * the subprocess before Claude CLI can auto-execute the tools.
+ *
+ * Hardened with: inactivity timeout (180s), subprocess exit handler with stderr
+ * surfacing, streamEnded guard against double errors, abort via SIGKILL, and
+ * process registry integration for teardown cleanup.
+ *
+ * @param model - The model to use (from pi's model catalog)
+ * @param context - The conversation context with messages and system prompt
+ * @param options - Optional cwd, abort signal, reasoning level, thinking budgets, and mcpConfigPath
+ * @returns An AssistantMessageEventStream that receives bridged events
+ */
+export function streamViaCli(
+  model: Model<any>,
+  context: { messages: any[]; systemPrompt?: string },
+  options?: StreamViaCLiOptions,
+): AssistantMessageEventStream {
+  const stream = createAssistantMessageEventStream();
+
+  (async () => {
+    let proc: ReturnType<typeof spawnClaude> | undefined;
+    let abortHandler: (() => void) | undefined;
+
+    try {
+      const cwd = options?.cwd ?? process.cwd();
+
+      // Resume only when this conversation already contains a prior assistant
+      // turn produced by pi-claude-cli (which means a CLI session has been
+      // established under this session id). Otherwise — e.g. when the user
+      // just switched to pi-claude-cli from another provider mid session, or
+      // when this is the first turn — start a fresh CLI session via
+      // --session-id. Using --resume against an unknown id fails silently
+      // with "No conversation found with session ID" and produces an empty
+      // assistant message.
+      const hasPriorCliTurn = (context.messages as any[]).some(
+        (m) =>
+          m?.role === "assistant" &&
+          (m?.provider === "pi-claude-cli" || m?.api === "pi-claude-cli"),
+      );
+      const resumeSessionId =
+        options?.sessionId && hasPriorCliTurn ? options.sessionId : undefined;
+
+      // Build prompt: if resuming, only send the latest user turn;
+      // otherwise build the full flattened conversation history
+      const prompt = resumeSessionId
+        ? buildResumePrompt(context)
+        : buildPrompt(context);
+      const systemPrompt = resumeSessionId
+        ? undefined
+        : buildSystemPrompt(context, cwd);
+
+      // Compute effort level from reasoning options
+      const effort = mapThinkingEffort(
+        options?.reasoning,
+        model.id,
+        options?.thinkingBudgets,
+      );
+
+      // Spawn subprocess
+      proc = spawnClaude(model.id, systemPrompt || undefined, {
+        cwd,
+        signal: options?.signal,
+        effort,
+        mcpConfigPath: options?.mcpConfigPath,
+        resumeSessionId,
+        newSessionId: !resumeSessionId ? options?.sessionId : undefined,
+      });
+      const getStderr = captureStderr(proc);
+
+      // Register in global process registry for teardown cleanup
+      registerProcess(proc);
+
+      // Write user message to subprocess stdin
+      writeUserMessage(proc, prompt);
+
+      // Create event bridge (before endStreamWithError so bridge is in scope)
+      const bridge = createEventBridge(stream, model);
+
+      // Guard against double stream.end() and double error events.
+      // First error path wins; subsequent ones are no-ops.
+      let streamEnded = false;
+
+      /**
+       * End the stream with an error, using a "done" event instead of "error".
+       *
+       * Why "done" not "error": AssistantMessageEventStream.extractResult()
+       * returns event.error (a string) for error events, but agent-loop.js
+       * then calls message.content.filter() on the result, crashing because
+       * a string has no .content property. By pushing "done" with a valid
+       * AssistantMessage (content:[]), pi gets a well-formed object.
+       */
+      function endStreamWithError(errMsg: string) {
+        if (streamEnded || broken) return;
+        streamEnded = true;
+        const output = bridge.getOutput();
+        const errorMessage = {
+          ...output,
+          content: output.content?.length
+            ? output.content
+            : [{ type: "text" as const, text: `Error: ${errMsg}` }],
+          stopReason: "stop" as const,
+        };
+        stream.push({
+          type: "done",
+          reason: "stop",
+          message: errorMessage,
+        } as any);
+        stream.end();
+      }
+
+      // Inactivity timeout: kill subprocess if no stdout for INACTIVITY_TIMEOUT_MS
+      let inactivityTimer: ReturnType<typeof setTimeout> | undefined;
+
+      function resetInactivityTimer() {
+        if (inactivityTimer !== undefined) clearTimeout(inactivityTimer);
+        inactivityTimer = setTimeout(() => {
+          forceKillProcess(proc!);
+          endStreamWithError(
+            `Claude CLI subprocess timed out: no output for ${INACTIVITY_TIMEOUT_MS / 1000} seconds`,
+          );
+        }, INACTIVITY_TIMEOUT_MS);
+      }
+
+      // Set up abort signal handler -- uses SIGKILL for immediate force-kill
+      if (options?.signal) {
+        abortHandler = () => {
+          if (proc) {
+            forceKillProcess(proc);
+          }
+        };
+
+        if (options.signal.aborted) {
+          abortHandler();
+          return;
+        }
+        options.signal.addEventListener("abort", abortHandler, { once: true });
+      }
+
+      // Track tool_use blocks for break-early decision at message_stop
+      let sawBuiltInOrCustomTool = false;
+      // Guard against buffered readline lines firing after rl.close()
+      let broken = false;
+
+      // Set up readline for line-by-line NDJSON parsing
+      const rl = createInterface({
+        input: proc.stdout!,
+        crlfDelay: Infinity,
+        terminal: false,
+      });
+
+      // Handle process error -- use endStreamWithError for guard
+      proc.on("error", (err: Error) => {
+        if (broken) return; // Break-early killed the process intentionally
+        const stderr = getStderr();
+        endStreamWithError(stderr || err.message);
+      });
+
+      // Handle subprocess close -- surface crashes with stderr and exit code
+      proc.on("close", (code: number | null, _signal: string | null) => {
+        clearTimeout(inactivityTimer);
+        if (broken) return; // Break-early kill, expected
+        if (code !== 0 && code !== null) {
+          const stderr = getStderr();
+          const message = stderr
+            ? `Claude CLI exited with code ${code}: ${stderr.trim()}`
+            : `Claude CLI exited unexpectedly with code ${code}`;
+          endStreamWithError(message);
+        }
+      });
+
+      // Start inactivity timer after writing user message
+      resetInactivityTimer();
+
+      // Process NDJSON lines from stdout using event-based callback
+      // NOTE: Using 'line' event instead of `for await` because the async
+      // iterator batches lines, breaking real-time streaming to pi.
+      rl.on("line", (line: string) => {
+        if (broken) return; // Guard: ignore buffered lines after break-early
+
+        // Reset inactivity timer on each line of output
+        resetInactivityTimer();
+
+        const msg = parseLine(line);
+        if (!msg) return;
+
+        if (msg.type === "stream_event") {
+          // Only forward top-level events to pi's event bridge.
+          // Sub-agent events (parent_tool_use_id !== null) are internal to the CLI.
+          const isTopLevel = !(msg as any).parent_tool_use_id;
+          if (isTopLevel) {
+            bridge.handleEvent(msg.event);
+          }
+
+          // Track tool_use blocks for break-early decision (top-level only)
+          if (
+            isTopLevel &&
+            msg.event.type === "content_block_start" &&
+            msg.event.content_block?.type === "tool_use"
+          ) {
+            const toolName = msg.event.content_block.name;
+            if (toolName && isPiKnownClaudeTool(toolName)) {
+              // Built-in tool (Read/Write/etc.) OR custom MCP tool (mcp__custom-tools__*)
+              // Internal Claude Code tools (ToolSearch, Task, etc.) are excluded
+              sawBuiltInOrCustomTool = true;
+            }
+          }
+
+          // Break-early at message_stop: kill subprocess before CLI auto-executes tools
+          // Only on top-level message_stop — sub-agent message_stop is internal
+          if (
+            isTopLevel &&
+            msg.event.type === "message_stop" &&
+            sawBuiltInOrCustomTool
+          ) {
+            broken = true; // Set guard BEFORE rl.close() to prevent buffered lines
+            clearTimeout(inactivityTimer);
+            // Pi will execute these tools. Kill subprocess to prevent CLI from executing them.
+            forceKillProcess(proc!);
+            rl.close();
+            return; // Don't process further -- done event already pushed by event bridge
+          }
+        } else if (msg.type === "control_request") {
+          handleControlRequest(msg, proc!.stdin!);
+        } else if (msg.type === "result") {
+          // Surface every non-success result as an error so silent failures
+          // (e.g. subtype "error_during_execution" from --resume against an
+          // unknown session id, or any future error variant) don't get
+          // swallowed into an empty assistant message.
+          const r: any = msg as any;
+          const isError =
+            r.subtype !== "success" ||
+            r.is_error === true ||
+            typeof r.error === "string" ||
+            (Array.isArray(r.errors) && r.errors.length > 0);
+          if (isError) {
+            const errMsg =
+              r.error ??
+              (Array.isArray(r.errors) && r.errors.length > 0
+                ? r.errors.join("; ")
+                : `Claude CLI returned ${r.subtype ?? "non-success result"}`);
+            endStreamWithError(errMsg);
+          }
+          // For both success and error: clean up the subprocess
+          clearTimeout(inactivityTimer);
+          cleanupProcess(proc!);
+          rl.close();
+        }
+      });
+
+      // Wait for readline to close (result received or process ended)
+      await new Promise<void>((resolve) => {
+        rl.on("close", resolve);
+      });
+
+      // 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.
+      if (!streamEnded) {
+        const output = bridge.getOutput();
+
+        // If stopReason is toolUse but there are no pi-known tool calls in content,
+        // it means only user MCP tools were called (filtered by event bridge).
+        // Override to "stop" so pi doesn't try to execute non-existent tools.
+        const piToolCalls = (output.content || []).filter(
+          (c: any) => c.type === "toolCall",
+        );
+        const effectiveReason =
+          output.stopReason === "toolUse" && piToolCalls.length === 0
+            ? "stop"
+            : output.stopReason;
+
+        streamEnded = true;
+        stream.push({
+          type: "done",
+          reason:
+            effectiveReason === "toolUse"
+              ? "toolUse"
+              : effectiveReason === "length"
+                ? "length"
+                : "stop",
+          message: { ...output, stopReason: effectiveReason },
+        });
+        stream.end();
+      }
+    } catch (err: any) {
+      stream.push({
+        type: "error",
+        reason: "error",
+        error: err.message ?? "Unexpected error in streamViaCli",
+      } as any);
+      stream.end();
+    } finally {
+      // Clean up abort listener
+      if (options?.signal && abortHandler) {
+        options.signal.removeEventListener("abort", abortHandler);
+      }
+      cleanupSystemPromptFile();
+    }
+  })();
+
+  return stream;
+}

package/src/stream-parser.ts

@@ -0,0 +1,37 @@
+import type { NdjsonMessage } from "./types";
+
+/**
+ * Parse a single NDJSON line from Claude CLI stdout into a typed message.
+ *
+ * This function is deliberately resilient -- it never throws. Debug noise,
+ * empty lines, and malformed JSON all return null so the streaming pipeline
+ * can safely skip them and continue processing.
+ */
+export function parseLine(line: string): NdjsonMessage | null {
+  const trimmed = line.trim();
+
+  // Skip empty lines
+  if (!trimmed) {
+    return null;
+  }
+
+  // Skip non-JSON lines (debug output like "[SandboxDebug] ...")
+  if (!trimmed.startsWith("{")) {
+    return null;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    console.error("Failed to parse NDJSON line:", trimmed);
+    return null;
+  }
+
+  // Validate that the parsed result is a non-null object (not array, not primitive)
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return null;
+  }
+
+  return parsed as NdjsonMessage;
+}

package/src/thinking-config.ts

@@ -0,0 +1,87 @@
+/**
+ * Thinking effort configuration for mapping pi's ThinkingLevel to Claude CLI --effort flags.
+ *
+ * Maps pi's reasoning levels (minimal/low/medium/high/xhigh/max) to the CLI's effort
+ * levels (low/medium/high/xhigh/max). Opus models keep the elevated mapping where
+ * medium becomes high and high becomes max; all other models pass through 1:1.
+ *
+ * IMPORTANT: The CLI does NOT support --thinking-budget. Only --effort is supported.
+ */
+
+import type { ThinkingLevel, ThinkingBudgets } from "@earendil-works/pi-ai";
+
+/** CLI effort levels accepted by the --effort flag */
+export type CliEffortLevel = "low" | "medium" | "high" | "xhigh" | "max";
+
+/**
+ * Standard model mapping: pi ThinkingLevel -> CLI effort.
+ * The CLI accepts the full ladder (low/medium/high/xhigh/max) for current
+ * models (verified with claude-fable-5 and claude-sonnet-5 on claude CLI
+ * 2.x), so levels pass through 1:1 instead of capping at high.
+ */
+const STANDARD_EFFORT_MAP: Record<ThinkingLevel, CliEffortLevel> = {
+  minimal: "low",
+  low: "low",
+  medium: "medium",
+  high: "high",
+  xhigh: "xhigh",
+  max: "max",
+};
+
+/**
+ * Opus model mapping: shifted up for elevated reasoning.
+ * Opus models get max capability at high/xhigh/max levels.
+ */
+const OPUS_EFFORT_MAP: Record<ThinkingLevel, CliEffortLevel> = {
+  minimal: "low",
+  low: "low",
+  medium: "high", // shifted: standard high
+  high: "max", // shifted: maximum capability
+  xhigh: "max", // Opus gets max
+  max: "max",
+};
+
+/**
+ * Detect whether a model ID refers to an Opus model.
+ * Uses includes('opus') for forward-compatibility with future Opus versions.
+ *
+ * @param modelId - The model identifier string
+ * @returns true if the model is an Opus variant
+ */
+export function isOpusModel(modelId: string): boolean {
+  return modelId.includes("opus");
+}
+
+/**
+ * Map pi's ThinkingLevel to a CLI effort string.
+ *
+ * When reasoning is undefined, returns undefined so the --effort flag is omitted
+ * entirely, letting the CLI use its default behavior. When thinkingBudgets are
+ * provided, a console.warn is logged because the CLI only supports effort levels,
+ * not token budgets.
+ *
+ * @param reasoning - Pi's thinking level (undefined = omit flag)
+ * @param modelId - Model ID for Opus detection
+ * @param thinkingBudgets - Custom budgets (logged as unsupported, not applied)
+ * @returns CLI effort level string, or undefined if flag should be omitted
+ */
+export function mapThinkingEffort(
+  reasoning?: ThinkingLevel,
+  modelId?: string,
+  thinkingBudgets?: ThinkingBudgets,
+): CliEffortLevel | undefined {
+  if (reasoning === undefined) {
+    return undefined; // omit --effort flag entirely
+  }
+
+  if (thinkingBudgets && Object.keys(thinkingBudgets).length > 0) {
+    console.warn(
+      "[pi-claude-cli] Custom thinkingBudgets are not supported with CLI subprocess. " +
+        "The CLI uses --effort levels instead of token budgets. Budgets will be ignored.",
+    );
+  }
+
+  const isOpus = modelId ? isOpusModel(modelId) : false;
+  const map = isOpus ? OPUS_EFFORT_MAP : STANDARD_EFFORT_MAP;
+  return map[reasoning];
+}

package/src/tool-mapping.ts

@@ -0,0 +1,147 @@
+/**
+ * Single-source-of-truth tool mapping table for bidirectional translation
+ * between Claude CLI tool names/arguments and pi tool names/arguments.
+ *
+ * All lookup tables are derived from the TOOL_MAPPINGS array.
+ * Unknown tools and arguments pass through unchanged.
+ */
+
+/**
+ * A mapping entry for a single tool.
+ * `args` maps Claude argument names to pi argument names (only renamed args).
+ */
+export interface ToolMapping {
+  claude: string;
+  pi: string;
+  args: Record<string, string>;
+}
+
+/**
+ * The canonical tool mapping table. All other lookup structures are derived from this.
+ */
+export const TOOL_MAPPINGS: ToolMapping[] = [
+  { claude: "Read", pi: "read", args: { file_path: "path" } },
+  { claude: "Write", pi: "write", args: { file_path: "path" } },
+  {
+    claude: "Edit",
+    pi: "edit",
+    args: { file_path: "path", old_string: "oldText", new_string: "newText" },
+  },
+  { claude: "Bash", pi: "bash", args: {} },
+  { claude: "Grep", pi: "grep", args: { head_limit: "limit" } },
+  { claude: "Glob", pi: "find", args: {} },
+];
+
+/** Prefix for custom pi tools exposed via MCP. */
+export const CUSTOM_TOOLS_MCP_PREFIX = "mcp__custom-tools__";
+
+/** Set of built-in pi tool names derived from TOOL_MAPPINGS for O(1) lookup. */
+const BUILT_IN_PI_NAMES = new Set(TOOL_MAPPINGS.map((m) => m.pi));
+
+/**
+ * Check if a pi tool name is a custom tool (not one of the 6 built-in tools).
+ * Used by prompt builder to decide whether to add MCP prefix in history replay.
+ */
+export function isCustomToolName(piName: string): boolean {
+  return !BUILT_IN_PI_NAMES.has(piName);
+}
+
+/**
+ * Check if a Claude tool name maps to a pi-known tool.
+ * Returns true for built-in tools (Read, Write, etc.) and custom MCP tools (mcp__custom-tools__*).
+ * Returns false for internal Claude Code tools (ToolSearch, Task, Agent, etc.) that pi cannot execute.
+ * Used by event bridge to filter out internal tool calls.
+ */
+export function isPiKnownClaudeTool(claudeName: string): boolean {
+  if (claudeName.startsWith(CUSTOM_TOOLS_MCP_PREFIX)) return true;
+  return claudeName.toLowerCase() in CLAUDE_TO_PI_NAME;
+}
+
+// Derived lookup maps
+
+/** Lowercase Claude name -> pi name */
+const CLAUDE_TO_PI_NAME: Record<string, string> = {};
+/** Pi name -> PascalCase Claude name */
+const PI_TO_CLAUDE_NAME: Record<string, string> = {};
+/** Lowercase Claude name -> { claudeArgName: piArgName } */
+const CLAUDE_TO_PI_ARGS: Record<string, Record<string, string>> = {};
+/** Pi name -> { piArgName: claudeArgName } */
+const PI_TO_CLAUDE_ARGS: Record<string, Record<string, string>> = {};
+
+for (const m of TOOL_MAPPINGS) {
+  CLAUDE_TO_PI_NAME[m.claude.toLowerCase()] = m.pi;
+  PI_TO_CLAUDE_NAME[m.pi] = m.claude;
+  CLAUDE_TO_PI_ARGS[m.claude.toLowerCase()] = m.args;
+
+  // Build reverse arg map
+  const reverseArgs: Record<string, string> = {};
+  for (const [from, to] of Object.entries(m.args)) {
+    reverseArgs[to] = from;
+  }
+  PI_TO_CLAUDE_ARGS[m.pi] = reverseArgs;
+}
+
+// Handle glob/find asymmetry: pi's "glob" also maps back to Claude's "Glob"
+PI_TO_CLAUDE_NAME["glob"] = "Glob";
+
+/**
+ * Map a Claude tool name to the corresponding pi tool name.
+ * Strips the mcp__custom-tools__ prefix for custom tools first,
+ * then falls back to case-insensitive built-in lookup.
+ * Unknown tool names pass through unchanged.
+ */
+export function mapClaudeToolNameToPi(claudeName: string): string {
+  // Strip custom-tools MCP prefix first (e.g., "mcp__custom-tools__deploy" -> "deploy")
+  if (claudeName.startsWith(CUSTOM_TOOLS_MCP_PREFIX)) {
+    return claudeName.slice(CUSTOM_TOOLS_MCP_PREFIX.length);
+  }
+  // Standard built-in tool mapping (case-insensitive)
+  return CLAUDE_TO_PI_NAME[claudeName.toLowerCase()] ?? claudeName;
+}
+
+/**
+ * Map a pi tool name to the corresponding Claude tool name.
+ * Direct lookup. Unknown tool names pass through unchanged.
+ */
+export function mapPiToolNameToClaude(piName: string): string {
+  return PI_TO_CLAUDE_NAME[piName] ?? piName;
+}
+
+/**
+ * Translate Claude tool arguments to pi format.
+ * Only known renamed arguments are translated; all others pass through unchanged.
+ * This prevents dropping unknown/extra arguments (Pitfall 5).
+ */
+export function translateClaudeArgsToPi(
+  claudeToolName: string,
+  args: Record<string, unknown>,
+): Record<string, unknown> {
+  const renames = CLAUDE_TO_PI_ARGS[claudeToolName.toLowerCase()];
+  if (!renames || Object.keys(renames).length === 0) return args;
+
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(args)) {
+    const newKey = renames[key] ?? key;
+    result[newKey] = value;
+  }
+  return result;
+}
+
+/**
+ * Translate pi tool arguments to Claude format.
+ * Only known renamed arguments are translated; all others pass through unchanged.
+ */
+export function translatePiArgsToClaude(
+  piToolName: string,
+  args: Record<string, unknown>,
+): Record<string, unknown> {
+  const renames = PI_TO_CLAUDE_ARGS[piToolName];
+  if (!renames || Object.keys(renames).length === 0) return args;
+
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(args)) {
+    const newKey = renames[key] ?? key;
+    result[newKey] = value;
+  }
+  return result;
+}