context-mode 1.0.111 → 1.0.113

package/build/adapters/pi/index.js

@@ -0,0 +1,173 @@
+/**
+ * adapters/pi — Pi coding agent platform adapter.
+ *
+ * Implements HookAdapter for Pi's MCP-only paradigm at the adapter layer.
+ *
+ * Pi hook specifics:
+ *   - NO JSON-stdio hooks. Pi exposes a JS-callback runtime API
+ *     (`pi.on("session_start", fn)`, `pi.on("tool_call", fn)`, …) which is
+ *     wired DIRECTLY by `src/adapters/pi/extension.ts`. The HookAdapter
+ *     contract here intentionally reports `mcp-only` and all-false
+ *     capabilities so harness paths that walk the JSON-stdio matrix do not
+ *     try to register stdio hooks for Pi.
+ *   - Config root: ~/.pi/
+ *   - Settings: ~/.pi/settings.json (kept lightweight — Pi does not
+ *     prescribe a canonical settings file, but several internal tools
+ *     write one; using settings.json keeps parity with Claude Code).
+ *   - Session dir: ~/.pi/context-mode/sessions/  (parallel to ~/.claude/,
+ *     ~/.omp/) — this is the data-isolation contract from issue #473.
+ *   - Instruction file: AGENTS.md (per configs/pi/AGENTS.md).
+ *
+ * Why a dedicated adapter is mandatory:
+ *   Before this adapter existed, `getAdapter("pi")` fell through to the
+ *   `default` arm of the switch in `src/adapters/detect.ts` and returned a
+ *   ClaudeCodeAdapter. Pi sessions therefore wrote DBs and event logs into
+ *   `~/.claude/context-mode/sessions/`, contaminating Claude Code state and
+ *   silently leaking Pi user data into the wrong storage root (issue #473
+ *   follow-up). The OMP adapter fixed the same class of bug for OMP; this
+ *   adapter closes the gap for Pi.
+ */
+import { readFileSync, writeFileSync, mkdirSync, } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { homedir } from "node:os";
+import { BaseAdapter } from "../base.js";
+// ─────────────────────────────────────────────────────────
+// Adapter implementation
+// ─────────────────────────────────────────────────────────
+export class PiAdapter extends BaseAdapter {
+    constructor() {
+        super([".pi"]);
+    }
+    name = "Pi";
+    paradigm = "mcp-only";
+    capabilities = {
+        preToolUse: false,
+        postToolUse: false,
+        preCompact: false,
+        sessionStart: false,
+        canModifyArgs: false,
+        canModifyOutput: false,
+        canInjectSessionContext: false,
+    };
+    // ── Input parsing ──────────────────────────────────────
+    // Pi does not feed the adapter via JSON-stdio. These methods exist to
+    // satisfy the HookAdapter contract and throw if the harness mistakenly
+    // routes a JSON-stdio event through the adapter.
+    parsePreToolUseInput(_raw) {
+        throw new Error("Pi does not support JSON-stdio hooks (wired via extension.ts)");
+    }
+    parsePostToolUseInput(_raw) {
+        throw new Error("Pi does not support JSON-stdio hooks (wired via extension.ts)");
+    }
+    parsePreCompactInput(_raw) {
+        throw new Error("Pi does not support JSON-stdio hooks (wired via extension.ts)");
+    }
+    parseSessionStartInput(_raw) {
+        throw new Error("Pi does not support JSON-stdio hooks (wired via extension.ts)");
+    }
+    // ── Response formatting ────────────────────────────────
+    // No JSON-stdio path — return undefined to satisfy the contract.
+    formatPreToolUseResponse(_response) {
+        return undefined;
+    }
+    formatPostToolUseResponse(_response) {
+        return undefined;
+    }
+    formatPreCompactResponse(_response) {
+        return undefined;
+    }
+    formatSessionStartResponse(_response) {
+        return undefined;
+    }
+    // ── Configuration ──────────────────────────────────────
+    getSettingsPath() {
+        return resolve(homedir(), ".pi", "settings.json");
+    }
+    getInstructionFiles() {
+        return ["AGENTS.md"];
+    }
+    generateHookConfig(_pluginRoot) {
+        return {};
+    }
+    readSettings() {
+        try {
+            const raw = readFileSync(this.getSettingsPath(), "utf-8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    writeSettings(settings) {
+        const settingsPath = this.getSettingsPath();
+        mkdirSync(dirname(settingsPath), { recursive: true });
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2), "utf-8");
+    }
+    // ── Diagnostics (doctor) ─────────────────────────────────
+    validateHooks(_pluginRoot) {
+        return [
+            {
+                check: "Hook support",
+                status: "pass",
+                message: "Pi hooks are wired via the context-mode Pi extension " +
+                    "(~/.pi/extensions/context-mode/), not via JSON-stdio.",
+            },
+        ];
+    }
+    checkPluginRegistration() {
+        // Pi registers extensions by directory presence; the version-sync
+        // script writes ~/.pi/extensions/context-mode/package.json. We treat
+        // that file as the registration signal.
+        const pkgPath = resolve(homedir(), ".pi", "extensions", "context-mode", "package.json");
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+            if (pkg?.name === "context-mode") {
+                return {
+                    check: "Pi extension registration",
+                    status: "pass",
+                    message: `context-mode extension installed at ${pkgPath}`,
+                };
+            }
+            return {
+                check: "Pi extension registration",
+                status: "warn",
+                message: `Unexpected package at ${pkgPath}`,
+            };
+        }
+        catch {
+            return {
+                check: "Pi extension registration",
+                status: "fail",
+                message: `context-mode not found at ${pkgPath}`,
+                fix: "Run: context-mode upgrade",
+            };
+        }
+    }
+    getInstalledVersion() {
+        try {
+            const pkgPath = resolve(homedir(), ".pi", "extensions", "context-mode", "package.json");
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+            return pkg.version ?? "unknown";
+        }
+        catch {
+            return "not installed";
+        }
+    }
+    // ── Upgrade ────────────────────────────────────────────
+    // Pi does NOT use settings.json hook entries. The extension is the
+    // integration point — there is nothing for the harness to register
+    // beyond copying the extension into ~/.pi/extensions/context-mode/.
+    configureAllHooks(_pluginRoot) {
+        return [];
+    }
+    setHookPermissions(_pluginRoot) {
+        return [];
+    }
+    updatePluginRegistry(_pluginRoot, _version) {
+        // Pi extension version is managed by scripts/version-sync.mjs writing
+        // to ~/.pi/extensions/context-mode/package.json. No-op here.
+    }
+    getRoutingInstructions() {
+        return "# context-mode\n\nUse context-mode MCP tools (ctx_execute, ctx_execute_file, ctx_batch_execute, ctx_fetch_and_index, ctx_search) instead of inline shell/HTTP calls for data-heavy operations.";
+    }
+}

package/build/adapters/pi/mcp-bridge.d.ts

@@ -0,0 +1,113 @@
+/**
+ * MCP-stdio bridge for the Pi Coding Agent extension.
+ *
+ * Pi 0.73.x has no native MCP support — its README is explicit:
+ *   > "No MCP. Build CLI tools with READMEs (see Skills), or build an
+ *   >  extension that adds MCP support."
+ *
+ * Without this bridge, the routing block tells the LLM to call
+ * `ctx_execute`, `ctx_search`, etc. — but those tools never enter Pi's
+ * tool list, so the LLM cannot reach them. context-mode then becomes a
+ * pure cost on Pi (~2.5K tokens of system-prompt overhead with 0
+ * actual ctx_* calls). Reported in mksglu/context-mode#426.
+ *
+ * The bridge spawns `server.bundle.mjs` as a long-lived child via stdio
+ * JSON-RPC, performs the MCP handshake, calls `tools/list` once, and
+ * registers each returned tool through `pi.registerTool({ … })`. Each
+ * tool's `execute()` forwards into the child via `tools/call` — same
+ * code path Claude Code, Gemini CLI, and the other adapters use, so
+ * Pi behavior matches the rest of the platform suite.
+ *
+ * No external dependencies — pure node:child_process + JSON line frames.
+ */
+export interface MCPTool {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+}
+export interface MCPCallResult {
+    content?: Array<{
+        type?: string;
+        text?: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * Minimal stdio JSON-RPC client targeting the context-mode MCP server.
+ *
+ * Implementation notes:
+ *   - One outstanding ID per request; results matched by `id` from the
+ *     returned envelope. Notifications (no id) are sent fire-and-forget.
+ *   - Buffer is split on `\n` because the MCP server writes one
+ *     newline-delimited JSON message per `console.log` / `stdout.write`
+ *     invocation — this is the standard MCP stdio transport framing.
+ *   - On child exit / error, every in-flight request is rejected so
+ *     callers do not hang forever.
+ */
+export declare class MCPStdioClient {
+    private readonly serverScript;
+    private readonly env;
+    private child;
+    private requestId;
+    private readonly pending;
+    private buffer;
+    private initialized;
+    private exited;
+    constructor(serverScript: string, env?: NodeJS.ProcessEnv);
+    /** Spawn the MCP child. Idempotent. */
+    start(): void;
+    private onExit;
+    private onData;
+    request<T = unknown>(method: string, params: unknown, timeoutMs?: number): Promise<T>;
+    notify(method: string, params: unknown): void;
+    initialize(): Promise<void>;
+    listTools(): Promise<MCPTool[]>;
+    callTool(name: string, args: unknown): Promise<MCPCallResult>;
+    shutdown(): void;
+}
+/**
+ * Subset of the Pi ExtensionAPI we touch. Typed structurally so we don't
+ * pull `@earendil-works/pi-coding-agent` as a build dependency — keeps
+ * the bundle size unchanged and matches the existing pi-extension.ts
+ * style (which also types `pi` as `any`).
+ */
+export interface PiToolRegistration {
+    name: string;
+    label: string;
+    description: string;
+    parameters: unknown;
+    execute: (toolCallId: string, params: Record<string, unknown>) => Promise<{
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+        details: Record<string, unknown>;
+        isError?: boolean;
+    }>;
+}
+export interface PiLikeAPI {
+    registerTool: (tool: PiToolRegistration) => void;
+}
+/** Result of bootstrapping the bridge. */
+export interface BridgeHandle {
+    /** Names of tools registered with Pi (for diagnostics / tests). */
+    tools: string[];
+    /** Idempotent shutdown — terminates the MCP child. */
+    shutdown: () => void;
+    /** Underlying client, exposed for tests / advanced callers. */
+    client: MCPStdioClient;
+}
+/**
+ * Spawn the MCP server and register each of its tools with Pi via
+ * `pi.registerTool()`. The same JSON Schema returned by `tools/list` is
+ * passed straight through as `parameters` — TypeBox emits JSON-Schema
+ * compatible objects, so any Pi runtime that validates JSON Schema
+ * accepts this shape (verified against pi 0.73.x).
+ *
+ * Errors during MCP `tools/call` are translated to a `throw` from the
+ * `execute()` callback — Pi's contract is "throw to mark the tool call
+ * failed", which lets the LLM see and adapt.
+ */
+export declare function bootstrapMCPTools(pi: PiLikeAPI, serverScript: string, options?: {
+    env?: NodeJS.ProcessEnv;
+}): Promise<BridgeHandle>;

package/build/adapters/pi/mcp-bridge.js

@@ -0,0 +1,251 @@
+/**
+ * MCP-stdio bridge for the Pi Coding Agent extension.
+ *
+ * Pi 0.73.x has no native MCP support — its README is explicit:
+ *   > "No MCP. Build CLI tools with READMEs (see Skills), or build an
+ *   >  extension that adds MCP support."
+ *
+ * Without this bridge, the routing block tells the LLM to call
+ * `ctx_execute`, `ctx_search`, etc. — but those tools never enter Pi's
+ * tool list, so the LLM cannot reach them. context-mode then becomes a
+ * pure cost on Pi (~2.5K tokens of system-prompt overhead with 0
+ * actual ctx_* calls). Reported in mksglu/context-mode#426.
+ *
+ * The bridge spawns `server.bundle.mjs` as a long-lived child via stdio
+ * JSON-RPC, performs the MCP handshake, calls `tools/list` once, and
+ * registers each returned tool through `pi.registerTool({ … })`. Each
+ * tool's `execute()` forwards into the child via `tools/call` — same
+ * code path Claude Code, Gemini CLI, and the other adapters use, so
+ * Pi behavior matches the rest of the platform suite.
+ *
+ * No external dependencies — pure node:child_process + JSON line frames.
+ */
+import { spawn } from "node:child_process";
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+// Tools/call may run shell commands or fetch URLs — wider window than
+// initialize/list, but still bounded so a hung server can't block Pi.
+const DEFAULT_CALL_TIMEOUT_MS = 120_000;
+/**
+ * Minimal stdio JSON-RPC client targeting the context-mode MCP server.
+ *
+ * Implementation notes:
+ *   - One outstanding ID per request; results matched by `id` from the
+ *     returned envelope. Notifications (no id) are sent fire-and-forget.
+ *   - Buffer is split on `\n` because the MCP server writes one
+ *     newline-delimited JSON message per `console.log` / `stdout.write`
+ *     invocation — this is the standard MCP stdio transport framing.
+ *   - On child exit / error, every in-flight request is rejected so
+ *     callers do not hang forever.
+ */
+export class MCPStdioClient {
+    serverScript;
+    env;
+    child = null;
+    requestId = 0;
+    pending = new Map();
+    buffer = "";
+    initialized = false;
+    exited = false;
+    constructor(serverScript, env = process.env) {
+        this.serverScript = serverScript;
+        this.env = env;
+    }
+    /** Spawn the MCP child. Idempotent. */
+    start() {
+        if (this.child)
+            return;
+        this.exited = false;
+        this.child = spawn(process.execPath, [this.serverScript], {
+            // Pipe stderr (#472 round-3): swallowing it via "ignore" hides
+            // server crash diagnostics — the user only saw "ctx_* tools will
+            // not be callable" with no clue WHY. Forwarding to process.stderr
+            // with a [mcp-bridge] prefix lets ops grep across session noise.
+            stdio: ["pipe", "pipe", "pipe"],
+            env: this.env,
+        });
+        this.child.stdout?.on("data", (chunk) => this.onData(chunk));
+        this.child.stderr?.on("data", (chunk) => {
+            const text = chunk.toString("utf-8");
+            // Preserve original line breaks; prefix every non-empty line so
+            // multi-line traces stay grep-friendly.
+            const prefixed = text
+                .split(/\r?\n/)
+                .map((line, i, arr) => i === arr.length - 1 && line === "" ? "" : `[mcp-bridge] ${line}`)
+                .join("\n");
+            process.stderr.write(prefixed);
+        });
+        this.child.on("exit", () => this.onExit());
+        this.child.on("error", () => this.onExit());
+    }
+    onExit() {
+        if (this.exited)
+            return;
+        this.exited = true;
+        const err = new Error("MCP server exited");
+        for (const [, p] of this.pending)
+            p.reject(err);
+        this.pending.clear();
+    }
+    onData(chunk) {
+        this.buffer += chunk.toString("utf-8");
+        let idx;
+        while ((idx = this.buffer.indexOf("\n")) >= 0) {
+            const line = this.buffer.slice(0, idx).trim();
+            this.buffer = this.buffer.slice(idx + 1);
+            if (!line)
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                continue; // skip non-JSON noise (e.g. stray log lines)
+            }
+            if (typeof msg.id !== "number" || !this.pending.has(msg.id))
+                continue;
+            const handler = this.pending.get(msg.id);
+            this.pending.delete(msg.id);
+            if (msg.error)
+                handler.reject(msg.error);
+            else
+                handler.resolve(msg.result);
+        }
+    }
+    request(method, params, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+        if (!this.child)
+            throw new Error("MCP client not started");
+        if (this.exited)
+            return Promise.reject(new Error("MCP server has exited"));
+        const id = ++this.requestId;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                if (!this.pending.has(id))
+                    return;
+                this.pending.delete(id);
+                reject(new Error(`MCP request timeout after ${timeoutMs}ms: ${method}`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: (v) => {
+                    clearTimeout(timer);
+                    resolve(v);
+                },
+                reject: (e) => {
+                    clearTimeout(timer);
+                    reject(e);
+                },
+            });
+            const frame = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+            this.child.stdin?.write(frame + "\n");
+        });
+    }
+    notify(method, params) {
+        if (!this.child)
+            return;
+        const frame = JSON.stringify({ jsonrpc: "2.0", method, params });
+        this.child.stdin?.write(frame + "\n");
+    }
+    async initialize() {
+        if (this.initialized)
+            return;
+        await this.request("initialize", {
+            protocolVersion: "2025-06-18",
+            capabilities: { tools: {} },
+            clientInfo: {
+                name: "pi-coding-agent-context-mode-bridge",
+                version: "1.0",
+            },
+        });
+        this.notify("notifications/initialized", {});
+        this.initialized = true;
+    }
+    async listTools() {
+        const result = await this.request("tools/list", {});
+        return Array.isArray(result.tools) ? result.tools : [];
+    }
+    async callTool(name, args) {
+        return this.request("tools/call", { name, arguments: args ?? {} }, DEFAULT_CALL_TIMEOUT_MS);
+    }
+    shutdown() {
+        if (!this.child)
+            return;
+        const child = this.child;
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            // best effort
+        }
+        // SIGKILL fallback (#472 round-3): a child that ignores SIGTERM
+        // (e.g. installed handler that swallows the signal, or stuck in
+        // an uninterruptible syscall) becomes a zombie because we null
+        // the handle immediately. Schedule a hard kill bounded at 5s; the
+        // .unref() prevents this timer from keeping the parent alive after
+        // legitimate work is done.
+        setTimeout(() => {
+            try {
+                if (child.exitCode === null && child.signalCode === null) {
+                    child.kill("SIGKILL");
+                }
+            }
+            catch {
+                // best effort
+            }
+        }, 5000).unref();
+        this.child = null;
+        this.initialized = false;
+        this.exited = true;
+    }
+}
+/**
+ * Spawn the MCP server and register each of its tools with Pi via
+ * `pi.registerTool()`. The same JSON Schema returned by `tools/list` is
+ * passed straight through as `parameters` — TypeBox emits JSON-Schema
+ * compatible objects, so any Pi runtime that validates JSON Schema
+ * accepts this shape (verified against pi 0.73.x).
+ *
+ * Errors during MCP `tools/call` are translated to a `throw` from the
+ * `execute()` callback — Pi's contract is "throw to mark the tool call
+ * failed", which lets the LLM see and adapt.
+ */
+export async function bootstrapMCPTools(pi, serverScript, options = {}) {
+    const client = new MCPStdioClient(serverScript, options.env);
+    client.start();
+    await client.initialize();
+    const tools = await client.listTools();
+    const registered = [];
+    for (const tool of tools) {
+        pi.registerTool({
+            name: tool.name,
+            label: tool.name,
+            description: tool.description ?? "",
+            // MCP tools/list returns JSON Schema; Pi validates against JSON
+            // Schema (TypeBox is just JSON Schema with extra Symbol metadata
+            // for type inference). Empty-object fallback keeps tools that
+            // declare no parameters callable.
+            parameters: tool.inputSchema ?? { type: "object", properties: {} },
+            async execute(_toolCallId, params) {
+                const result = await client.callTool(tool.name, params ?? {});
+                const text = (result.content ?? [])
+                    .filter((c) => c?.type === "text" && typeof c.text === "string")
+                    .map((c) => c.text)
+                    .join("\n");
+                if (result.isError) {
+                    // Throw is the Pi contract for "tool failed". The text body
+                    // becomes the error message visible to the LLM, so it sees
+                    // the same diagnostic the MCP server emitted.
+                    throw new Error(text || `${tool.name} returned an error`);
+                }
+                return {
+                    content: [{ type: "text", text }],
+                    details: {},
+                };
+            },
+        });
+        registered.push(tool.name);
+    }
+    return {
+        tools: registered,
+        shutdown: () => client.shutdown(),
+        client,
+    };
+}

package/build/adapters/types.d.ts

@@ -154,12 +154,17 @@ export interface HookAdapter {
     formatSessionStartResponse?(response: SessionStartResponse): unknown;
     /** Path to the platform's settings file (e.g., ~/.claude/settings.json). */
     getSettingsPath(): string;
-    /** Directory where session data is stored. */
+    /**
+     * Directory where session data is stored.
+     *
+     * NOTE — C2 narrowing (2026-05): this is the ONLY storage-path concern an
+     * adapter exposes. Per-project DB paths are derived by callers via
+     * `resolveSessionDbPath({ projectDir, sessionsDir: adapter.getSessionDir() })`
+     * (see `src/session/db.ts`). Per-project events.md paths follow the same
+     * `<sessionDir>/<hash><suffix>-events.md` shape and are computed inline at
+     * the small number of call sites that need them (server.ts, hooks).
+     */
     getSessionDir(): string;
-    /** Compute per-project session DB path. */
-    getSessionDBPath(projectDir: string): string;
-    /** Compute per-project session events file path. */
-    getSessionEventsPath(projectDir: string): string;
     /**
      * Platform config directory.
      *
@@ -239,7 +244,7 @@ export interface DiagnosticResult {
  */
 export declare function buildNodeCommand(scriptPath: string): string;
 /** Supported platform identifiers. */
-export type PlatformId = "claude-code" | "gemini-cli" | "opencode" | "kilo" | "openclaw" | "codex" | "vscode-copilot" | "jetbrains-copilot" | "cursor" | "antigravity" | "kiro" | "pi" | "zed" | "qwen-code" | "unknown";
+export type PlatformId = "claude-code" | "gemini-cli" | "opencode" | "kilo" | "openclaw" | "codex" | "vscode-copilot" | "jetbrains-copilot" | "cursor" | "antigravity" | "kiro" | "pi" | "omp" | "zed" | "qwen-code" | "unknown";
 /** Detection signal used to identify which platform is running. */
 export interface DetectionSignal {
     /** Platform identifier. */