pi-gortex 0.3.0 → 0.4.1

package/src/index.ts

@@ -3,7 +3,7 @@
 // hook bridge. See docs/architecture.md for the design.
 
 import type {
-  ContextEvent,
+  BeforeAgentStartEventResult,
   ExtensionAPI,
   ExtensionContext,
   ToolCallEvent,
@@ -11,7 +11,8 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 
 import { resolveConfig } from "./config.ts";
-import type { GortexConfig } from "./config.ts";
+import type { GortexConfig, ResolveConfigOptions } from "./config.ts";
+import { watchNativeEdits } from "./diff.ts";
 import { callHook, normalizeToolCall } from "./hook.ts";
 import {
   MCPStdioClient,
@@ -32,6 +33,7 @@ import {
   supportsNativeMcp,
   waitForNativeTools,
 } from "./native.ts";
+import { nativeRenderers } from "./render.ts";
 import { nodeProcessDeps } from "./runtime.ts";
 import type { ProcessDeps } from "./runtime.ts";
 import {
@@ -47,6 +49,7 @@ import {
   setBridgeError,
   setClient,
   setVersionWarning,
+  withdrawnToolNames,
 } from "./state.ts";
 
 export type { GortexConfig, SidecarConfig } from "./config.ts";
@@ -109,24 +112,62 @@ function notifyUser(ctx: ExtensionContext | undefined, message: string): void {
   }
 }
 
+/** Marks the messages this extension stores in the session. */
+const GORTEX_MESSAGE_TYPE = "gortex";
+
+interface GortexMessageDetails {
+  /** Whether the content includes the session briefing, not only warnings. */
+  briefing: boolean;
+}
+
+/** Kept out of the transcript; Pi still sends it to the model. */
+function gortexMessage(content: string, briefing: boolean): BeforeAgentStartEventResult {
+  const details: GortexMessageDetails = { briefing };
+  return { message: { customType: GORTEX_MESSAGE_TYPE, content, display: false, details } };
+}
+
+/**
+ * Whether a briefing already sits in what the model sees: after a resume or
+ * /reload, or when compaction kept it. Answers false when Pi can't tell.
+ */
+function briefingInContext(ctx: ExtensionContext | undefined): boolean {
+  try {
+    return (ctx?.sessionManager.buildContextEntries() ?? []).some(
+      (entry) =>
+        entry.type === "custom_message" &&
+        entry.customType === GORTEX_MESSAGE_TYPE &&
+        (entry.details as GortexMessageDetails | undefined)?.briefing === true,
+    );
+  } catch {
+    return false;
+  }
+}
+
 /** Test seams. Pi itself calls the factory with the `pi` object alone. */
 export interface GortexExtensionOptions {
-  /** Pre-resolved configuration; resolveConfig() runs when this is absent. */
+  /** Fixed configuration; resolveConfig() runs per session when this is absent. */
   config?: GortexConfig;
+  /** resolveConfig() seams; `cwd` stands in for the process cwd until a session supplies one. */
+  resolve?: ResolveConfigOptions;
   /** Process seam for spawn/execFileSync. */
   deps?: ProcessDeps;
   /** Readiness cap override. */
   readyWaitMs?: number;
   /** Override for the wait on Pi's built-in MCP connecting the gortex server. */
   nativeReadyWaitMs?: number;
+  /** tools/call timeout override for the extension's own client. */
+  callTimeoutMs?: number;
+  /** Frame size cap override for the extension's own client. */
+  maxFrameBytes?: number;
 }
 
 export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensionOptions = {}): void {
-  const config = options.config ?? resolveConfig();
-  // Pi 0.85's ExtensionAPI declares no `cwd`, so the hook envelope reads it
-  // defensively and falls back to the process cwd. A Pi version that grows the
-  // field is picked up when it exists.
-  const piCwd = (): string => (pi as { cwd?: string })?.cwd ?? process.cwd();
+  // Resolved again on every session_start from ctx.cwd, the directory the
+  // session runs in. The factory has no session, so this first resolution only
+  // serves a turn that outruns session_start.
+  const configFor = (cwd?: string): GortexConfig =>
+    options.config ?? resolveConfig({ ...options.resolve, cwd: cwd ?? options.resolve?.cwd });
+  let config = configFor();
   const deps = options.deps ?? nodeProcessDeps;
   const readyWaitMs = options.readyWaitMs ?? READY_WAIT_MS;
   const nativeReadyWaitMs = options.nativeReadyWaitMs ?? NATIVE_READY_WAIT_MS;
@@ -135,20 +176,35 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
   // (which starts the daemon itself), registers the tools and renders them.
   // A binary that does not resolve, or a registration Pi refuses, falls back to
   // the extension's own client, which reports its failure to the model.
+  // Registered on session_start only, once the session's config is known: Pi
+  // reads a registration made before its own session_start handler, and
+  // connects one made after it.
   let nativeRefusal = "";
-  let native = ((): boolean => {
-    if (!config.nativeMcp || !supportsNativeMcp(pi) || !binaryResolves(config.bin)) return false;
+  let native = false;
+  let registered: GortexConfig | null = null;
+  function registerNative(connector: boolean): void {
+    if (native) unregisterNativeServer(pi);
+    native = false;
+    registered = config;
+    nativeRefusal = "";
+    if (!connector || !config.nativeMcp || !supportsNativeMcp(pi) || !binaryResolves(config.bin)) return;
     nativeRefusal = registerNativeServer(pi, config);
-    return nativeRefusal === "";
-  })();
+    native = nativeRefusal === "";
+  }
+
+  // Re-registering an unchanged server would make Pi reconnect it.
+  const channelChanged = (): boolean =>
+    registered === null ||
+    registered.nativeMcp !== config.nativeMcp ||
+    registered.toolsPreset !== config.toolsPreset;
 
   // Latched for the whole session once the first turn has run the
   // session_start hook, whether or not it produced anything to inject.
   let startupHookRan = false;
-  // Orientation awaiting injection into the next LLM call, computed once per
-  // session. The `context` hook appends it as a tail user message, because a
-  // systemPrompt change sits at messages[0] and invalidates prefix caching.
-  let pendingOrientation = "";
+  // This session's briefing, kept so a compaction that summarises it away can
+  // send it again on the next turn.
+  let briefing = "";
+  let briefingCompacted = false;
 
   // Settles when the current session_start handler is done: bridge up and
   // tools registered, or the handshake failed. Never rejects.
@@ -198,7 +254,8 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
   // session's bridge child (if any) is stopped before a fresh handshake.
   pi.on("session_start", async (_event, ctx) => {
     startupHookRan = false;
-    pendingOrientation = "";
+    briefing = "";
+    briefingCompacted = false;
     setBridgeError("");
     setVersionWarning("");
     armSessionReady(); // no-op when a turn is already parked on this session
@@ -224,7 +281,10 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
   // startSession holds the body of session_start so the readiness promise
   // above settles on every exit path, early returns included.
   async function startSession(ctx?: ExtensionContext): Promise<void> {
-    if (native && !mcpConnectorLoaded(pi)) {
+    config = configFor(ctx?.cwd);
+    const connector = mcpConnectorLoaded(pi);
+    if (channelChanged()) registerNative(connector);
+    if (native && !connector) {
       unregisterNativeServer(pi);
       native = false;
     }
@@ -232,8 +292,16 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
     if (nativeRefusal) notifyUser(ctx, `Pi refused the gortex MCP server (${nativeRefusal}), so the extension runs its own client.`);
     ensureDaemon(config.bin, deps);
     gortexToolNames.clear();
+    withdrawnToolNames.clear();
     stopBridge();
-    const c = new MCPStdioClient({ bin: config.bin, toolsPreset: config.toolsPreset, deps });
+    const c = new MCPStdioClient({
+      bin: config.bin,
+      toolsPreset: config.toolsPreset,
+      cwd: ctx?.cwd,
+      deps,
+      callTimeoutMs: options.callTimeoutMs,
+      maxFrameBytes: options.maxFrameBytes,
+    });
     // Claim the slot before the first await: an overlapping
     // session_start (rapid /new or /reload) then sees and stops THIS
     // bridge instead of leaking its child mid-handshake.
@@ -258,10 +326,20 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
     }
   }
 
-  // Fires before the agent loop's first LLM call. It can't mutate messages
-  // itself, so it just parks the orientation for the `context` hook.
-  pi.on("before_agent_start", async (_event, ctx) => {
-    if (startupHookRan) return;
+  pi.on("session_compact", () => {
+    briefingCompacted = true;
+  });
+
+  // Fires before the agent loop's first LLM call. The returned message is
+  // stored in the session after the prompt, so every later LLM call carries it
+  // and the system prompt, which prefix caching keys on, stays untouched.
+  pi.on("before_agent_start", async (_event, ctx): Promise<BeforeAgentStartEventResult | void> => {
+    if (startupHookRan) {
+      if (!briefingCompacted) return;
+      briefingCompacted = false;
+      if (!briefing || briefingInContext(ctx)) return;
+      return gortexMessage(briefing, true);
+    }
     startupHookRan = true; // before the first await, so a second turn can't race in
     // Pi awaits each listener, so this holds the turn until the tools are
     // registered and bridgeError reflects the handshake (or the cap expires).
@@ -270,7 +348,7 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
     const ready = native ? await waitForNativeTools(pi, nativeReadyWaitMs) : sessionDone;
     const decision = callHook(config.hookArgv, deps, {
       event: "session_start",
-      cwd: ctx?.cwd ?? piCwd(),
+      cwd: ctx?.cwd ?? process.cwd(),
     });
     // Pi's MCP keeps the handshake to itself, so the version comes from the briefing.
     if (native && decision.orientation) {
@@ -300,30 +378,15 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
       parts.push(versionWarning);
       setVersionWarning("");
     }
-    if (decision.orientation) parts.push(decision.orientation);
-    if (parts.length > 0) pendingOrientation = parts.join("\n\n");
-    return;
-  });
-
-  // Fires before each LLM call with a mutable message array. Appends the
-  // parked orientation once, clearing it only after the push lands so the
-  // orientation survives a context shape this hook can't append to.
-  // Pi exports ContextEvent but not its result type, so it is spelled out here.
-  pi.on("context", (event: ContextEvent): { messages?: ContextEvent["messages"] } | void => {
-    if (!pendingOrientation) return;
-    try {
-      const messages = (event as { messages?: unknown })?.messages;
-      if (Array.isArray(messages)) {
-        // Pi's AgentMessage also carries a `timestamp`; only the two fields
-        // Pi reads for a tail user turn are pushed.
-        messages.push({ role: "user", content: pendingOrientation } as ContextEvent["messages"][number]);
-        pendingOrientation = "";
-        return { messages: messages as ContextEvent["messages"] };
-      }
-    } catch {
-      // best effort; never break context assembly.
+    let briefed = false;
+    if (decision.orientation) {
+      briefing = decision.orientation;
+      // A resumed or reloaded session already holds it.
+      briefed = !briefingInContext(ctx);
+      if (briefed) parts.push(decision.orientation);
     }
-    return;
+    if (parts.length === 0) return;
+    return gortexMessage(parts.join("\n\n"), briefed);
   });
 
   // Never let the bridge child outlive the session.
@@ -331,10 +394,8 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
     stopBridge();
   });
 
-  if (!config.enforce) return;
-
   // Enforcement: every non-Gortex tool call is checked against the Go hook.
-  pi.on("tool_call", async (event: ToolCallEvent, ctx: ExtensionContext): Promise<ToolCallEventResult | void> => {
+  const enforceReadDiscipline = async (event: ToolCallEvent, ctx: ExtensionContext): Promise<ToolCallEventResult | void> => {
     const piName: string = (event as { toolName?: string })?.toolName ?? "";
     const piInput: Record<string, unknown> = (event?.input as Record<string, unknown>) ?? {};
     const isGortexTool = native ? isNativeGortexTool(piName) : gortexToolNames.has(piName);
@@ -347,7 +408,7 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
       event: "tool_call",
       tool_name: norm.tool_name,
       tool_input: norm.tool_input,
-      cwd: ctx?.cwd ?? piCwd(),
+      cwd: ctx?.cwd ?? process.cwd(),
       session_id: (ctx as { sessionManager?: { sessionId?: string } })?.sessionManager?.sessionId ?? "",
       is_gortex_tool: isGortexTool,
     });
@@ -367,5 +428,19 @@ export default function gortexExtension(pi: ExtensionAPI, options: GortexExtensi
       }
     }
     return;
-  });
+  };
+  // Registered unconditionally, since a session's own sidecar can turn enforcement on.
+  pi.on("tool_call", (event, ctx) => (config.enforce ? enforceReadDiscipline(event, ctx) : undefined));
+
+  // After enforcement, so a blocked call is never snapshotted. Shell calls are
+  // tracked on both channels; edits are snapshotted on Pi's built-in MCP only.
+  watchNativeEdits(pi, () => native);
+  if (supportsNativeMcp(pi)) {
+    // Pi < 1.0.1 has no tool renderers; the diffs are still stored.
+    try {
+      (pi as Partial<Pick<ExtensionAPI, "registerToolRenderer">>).registerToolRenderer?.(nativeRenderers);
+    } catch {
+      // drawing diffs is optional
+    }
+  }
 }

package/src/mcp-client.ts

@@ -46,36 +46,30 @@ export function isBelowVersion(actual: string, floor: string): boolean {
   return false;
 }
 
-// Presets the proxy has to be told about. The daemon's own default surface
-// already IS core/defer, so those pass nothing. Anything unrecognised (a typo,
-// a stale sidecar value) is NOT forwarded: server-side it would parse as a
-// one-tool allow-list and silently filter every promoted tool out of the
-// session. Fail open to the daemon's default surface instead.
-const FORWARDED_PRESETS = new Set(["edit", "nav", "readonly"]);
-
 /**
- * The variables `gortex mcp` needs on top of `env` to serve `toolsPreset`.
- * The daemon's own default surface already IS core/defer; only a recognised
- * non-default preset needs the proxy-side narrowing.
+ * The variables `gortex mcp` needs on top of `env` to serve `toolsPreset`, the
+ * spec resolveConfig validated (it already folds in the user's GORTEX_TOOLS).
+ * Both are always set, so an inherited value resolveConfig rejected never
+ * reaches the child; empty leaves the daemon's default surface.
  */
 export function presetEnv(
   toolsPreset: string,
   env: Record<string, string | undefined>,
 ): Record<string, string> {
-  const out: Record<string, string> = {};
-  const preset = toolsPreset.trim().toLowerCase();
-  const tools = env.GORTEX_TOOLS || (FORWARDED_PRESETS.has(preset) ? preset : "");
-  if (tools && !env.GORTEX_TOOLS) out.GORTEX_TOOLS = tools;
+  if (toolsPreset === "") return { GORTEX_TOOLS: "", GORTEX_TOOLS_MODE: "" };
   // Never let a preset hide-block tools promoted later by tools_search.
-  if (tools && !env.GORTEX_TOOLS_MODE) out.GORTEX_TOOLS_MODE = "defer";
-  return out;
+  return { GORTEX_TOOLS: toolsPreset, GORTEX_TOOLS_MODE: env.GORTEX_TOOLS_MODE?.trim() || "defer" };
 }
 
 export interface MCPStdioClientOptions {
   bin: string;
   toolsPreset: string;
+  /** The session's directory, which `gortex mcp` scopes the graph to. Default: the process cwd. */
+  cwd?: string;
   deps: ProcessDeps;
   env?: Record<string, string | undefined>;
+  callTimeoutMs?: number;
+  maxFrameBytes?: number;
 }
 
 interface PendingRequest {
@@ -84,6 +78,25 @@ interface PendingRequest {
   timer?: ReturnType<typeof setTimeout>;
 }
 
+/** A JSON-RPC error reply, with the server's code and data kept for the model. */
+export class JsonRpcError extends Error {
+  readonly code: number | undefined;
+  readonly data: unknown;
+
+  constructor(error: { code?: unknown; message?: unknown; data?: unknown }) {
+    const code = typeof error.code === "number" ? error.code : undefined;
+    let message = typeof error.message === "string" && error.message ? error.message : "JSON-RPC error";
+    if (code !== undefined) message += ` (${code})`;
+    if (error.data !== undefined) {
+      message += `: ${typeof error.data === "string" ? error.data : JSON.stringify(error.data)}`;
+    }
+    super(message);
+    this.name = "JsonRpcError";
+    this.code = code;
+    this.data = error.data;
+  }
+}
+
 export interface ToolDescriptor {
   name: string;
   description?: string;
@@ -102,6 +115,7 @@ export function ensureDaemon(bin: string, deps: ProcessDeps): void {
     const child = deps.spawn(bin, ["daemon", "start", "--detach"], {
       stdio: "ignore",
       detached: true,
+      windowsHide: true,
     });
     child.on("error", () => {}); // binary missing / spawn failure: swallow
     // No teardown counterpart, by design: the daemon is shared, long-lived
@@ -127,8 +141,10 @@ export function textFromResult(result: unknown): string {
 
 export class MCPStdioClient {
   private child: BridgeChild | null = null;
-  private buffer = "";
-  private searchStart = 0;
+  // Raw bytes of the frame still being read. Frames are cut at the 0x0A byte
+  // and decoded whole, so a character split across chunks survives.
+  private chunks: Buffer[] = [];
+  private bufferedBytes = 0;
   private nextId = 1;
   private pending = new Map<number, PendingRequest>();
   private exited = true;
@@ -136,8 +152,11 @@ export class MCPStdioClient {
 
   private readonly bin: string;
   private readonly toolsPreset: string;
+  private readonly cwd: string | undefined;
   private readonly deps: ProcessDeps;
   private readonly env: Record<string, string | undefined>;
+  private readonly callTimeoutMs: number;
+  private readonly maxFrameBytes: number;
 
   // Fired on notifications/tools/list_changed (server-side promotion).
   onToolsListChanged: (() => void) | null = null;
@@ -150,8 +169,11 @@ export class MCPStdioClient {
   constructor(options: MCPStdioClientOptions) {
     this.bin = options.bin;
     this.toolsPreset = options.toolsPreset;
+    this.cwd = options.cwd;
     this.deps = options.deps;
     this.env = options.env ?? process.env;
+    this.callTimeoutMs = options.callTimeoutMs ?? CALL_TIMEOUT_MS;
+    this.maxFrameBytes = options.maxFrameBytes ?? MAX_BUFFER_BYTES;
   }
 
   private childEnv(): Record<string, string | undefined> {
@@ -161,11 +183,13 @@ export class MCPStdioClient {
   private spawnChild(): void {
     const child = this.deps.spawn(this.bin, ["mcp"], {
       stdio: ["pipe", "pipe", "pipe"],
+      cwd: this.cwd,
       env: this.childEnv(),
+      windowsHide: true,
     });
     this.child = child;
-    this.buffer = "";
-    this.searchStart = 0;
+    this.chunks = [];
+    this.bufferedBytes = 0;
     this.exited = false;
     child.stdout?.on("data", (chunk: unknown) => this.onData(chunk as Buffer));
     // Consume stderr so the child never blocks on a full pipe; routing it
@@ -185,68 +209,93 @@ export class MCPStdioClient {
     if (this.exited && this.pending.size === 0) return;
     this.exited = true;
     this.child = null;
-    for (const [, p] of this.pending) {
-      if (p.timer) clearTimeout(p.timer);
-      p.reject(err);
-    }
+    const pending = [...this.pending.values()];
     this.pending.clear();
+    for (const p of pending) p.reject(err);
   }
 
   private onData(chunk: Buffer): void {
-    this.buffer += chunk.toString("utf8");
+    let start = 0;
     let nl: number;
-    // Resume the newline scan where the previous chunk left off, so a
-    // large frame split across many chunks does not re-scan the whole
-    // growing buffer from index 0 on every data event.
-    while ((nl = this.buffer.indexOf("\n", this.searchStart)) >= 0) {
-      const line = this.buffer.slice(0, nl).trim();
-      this.buffer = this.buffer.slice(nl + 1);
-      this.searchStart = 0;
-      if (!line) continue;
-      let msg: unknown;
-      try {
-        msg = JSON.parse(line);
-      } catch {
-        continue; // non-JSON noise, ignore
-      }
-      this.dispatch(msg);
+    while ((nl = chunk.indexOf(0x0a, start)) >= 0) {
+      if (this.bufferedBytes + nl - start > this.maxFrameBytes) return this.overflow();
+      const tail = chunk.subarray(start, nl);
+      const frame = this.chunks.length > 0 ? Buffer.concat([...this.chunks, tail]) : tail;
+      this.chunks = [];
+      this.bufferedBytes = 0;
+      start = nl + 1;
+      this.onFrame(frame.toString("utf8").trim());
     }
-    this.searchStart = this.buffer.length;
-    if (this.buffer.length > MAX_BUFFER_BYTES) {
-      // One frame past the cap is fatal for this child (no way to
-      // resync mid-frame): pending requests reject, the next call
-      // respawns a fresh child.
-      this.buffer = "";
-      this.searchStart = 0;
-      const child = this.child;
-      this.markExited(new Error(`gortex mcp frame exceeded ${MAX_BUFFER_BYTES} bytes`));
-      try {
-        child?.kill();
-      } catch {
-        // already gone
-      }
+    if (start >= chunk.length) return;
+    this.chunks.push(start === 0 ? chunk : chunk.subarray(start));
+    this.bufferedBytes += chunk.length - start;
+    if (this.bufferedBytes > this.maxFrameBytes) this.overflow();
+  }
+
+  // One frame past the cap is fatal for this child (no way to resync
+  // mid-frame): pending requests reject, the next call respawns a fresh child.
+  private overflow(): void {
+    this.chunks = [];
+    this.bufferedBytes = 0;
+    const child = this.child;
+    this.markExited(new Error(`gortex mcp frame exceeded ${this.maxFrameBytes} bytes`));
+    try {
+      child?.kill();
+    } catch {
+      // already gone
     }
   }
 
-  private dispatch(msg: unknown): void {
-    const frame = msg as { id?: unknown; error?: { code?: number; message?: string }; result?: unknown; method?: unknown };
-    if (frame && typeof frame.id === "number" && this.pending.has(frame.id)) {
-      const p = this.pending.get(frame.id)!;
-      this.pending.delete(frame.id);
-      if (p.timer) clearTimeout(p.timer);
-      if (frame.error) {
-        p.reject(new Error(frame.error.message || `JSON-RPC error ${frame.error.code}`));
-      } else {
-        p.resolve(frame.result);
+  private onFrame(line: string): void {
+    if (!line) return;
+    let msg: unknown;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return; // non-JSON noise, ignore
+    }
+    if (msg && typeof msg === "object") this.dispatch(msg as Record<string, unknown>);
+  }
+
+  private dispatch(frame: Record<string, unknown>): void {
+    const { id, method } = frame;
+    if (typeof method === "string") {
+      if (typeof id === "number" || typeof id === "string") this.answerServerRequest(id, method);
+      else if (method === "notifications/tools/list_changed") {
+        try {
+          this.onToolsListChanged?.();
+        } catch {
+          // best effort; never break the read loop.
+        }
       }
       return;
     }
-    if (frame && frame.method === "notifications/tools/list_changed") {
-      try {
-        this.onToolsListChanged?.();
-      } catch {
-        // best effort; never break the read loop.
-      }
+    const error = frame.error as Record<string, unknown> | undefined;
+    if (id === null && error) {
+      // The server could not tell which request this answers, so none of
+      // them will get a reply.
+      const pending = [...this.pending.values()];
+      this.pending.clear();
+      for (const p of pending) p.reject(new JsonRpcError(error));
+      return;
+    }
+    if (typeof id !== "number") return;
+    const p = this.pending.get(id);
+    if (!p) return;
+    this.pending.delete(id);
+    if (error) p.reject(new JsonRpcError(error));
+    else p.resolve(frame.result);
+  }
+
+  private answerServerRequest(id: number | string, method: string): void {
+    const reply =
+      method === "ping"
+        ? { jsonrpc: "2.0", id, result: {} }
+        : { jsonrpc: "2.0", id, error: { code: -32601, message: `Method not found: ${method}` } };
+    try {
+      this.send(reply);
+    } catch {
+      // the child is gone; nothing is waiting on the answer.
     }
   }
 
@@ -270,24 +319,54 @@ export class MCPStdioClient {
     return this.respawnPromise;
   }
 
-  async request(method: string, params: unknown, timeoutMs: number = RPC_TIMEOUT_MS): Promise<unknown> {
+  /**
+   * Sends one request. On abort or timeout the call is dropped and the server
+   * is sent notifications/cancelled, so a late reply is ignored.
+   */
+  async request(
+    method: string,
+    params: unknown,
+    timeoutMs: number = RPC_TIMEOUT_MS,
+    signal?: AbortSignal,
+  ): Promise<unknown> {
+    const aborted = () => new Error(`${method} aborted`);
+    if (signal?.aborted) throw aborted();
     if (this.exited) await this.respawn();
+    if (signal?.aborted) throw aborted();
     const id = this.nextId++;
     return new Promise((resolve, reject) => {
-      const entry: PendingRequest = { resolve, reject };
+      const onAbort = () => abandon(aborted());
+      const settled = () => {
+        if (entry.timer) clearTimeout(entry.timer);
+        signal?.removeEventListener("abort", onAbort);
+      };
+      const entry: PendingRequest = {
+        resolve: (value) => {
+          settled();
+          resolve(value);
+        },
+        reject: (err) => {
+          settled();
+          reject(err);
+        },
+      };
+      const abandon = (err: Error) => {
+        if (this.pending.get(id) !== entry) return;
+        this.pending.delete(id);
+        entry.reject(err);
+        // The MCP spec forbids cancelling initialize.
+        if (method !== "initialize") this.notify("notifications/cancelled", { requestId: id, reason: err.message });
+      };
       if (Number.isFinite(timeoutMs)) {
-        entry.timer = setTimeout(() => {
-          this.pending.delete(id);
-          reject(new Error(`${method} timed out after ${timeoutMs}ms`));
-        }, timeoutMs);
+        entry.timer = setTimeout(() => abandon(new Error(`${method} timed out after ${timeoutMs}ms`)), timeoutMs);
       }
+      signal?.addEventListener("abort", onAbort, { once: true });
       this.pending.set(id, entry);
       try {
         this.send({ jsonrpc: "2.0", id, method, params });
       } catch (err) {
         this.pending.delete(id);
-        if (entry.timer) clearTimeout(entry.timer);
-        reject(err instanceof Error ? err : new Error(String(err)));
+        entry.reject(err instanceof Error ? err : new Error(String(err)));
       }
     });
   }
@@ -336,8 +415,8 @@ export class MCPStdioClient {
     return Array.isArray(res?.tools) ? (res.tools as ToolDescriptor[]) : [];
   }
 
-  async callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
-    return this.request("tools/call", { name, arguments: args ?? {} }, CALL_TIMEOUT_MS);
+  async callTool(name: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<unknown> {
+    return this.request("tools/call", { name, arguments: args ?? {} }, this.callTimeoutMs, signal);
   }
 
   stop(): void {

package/src/native.ts

@@ -18,7 +18,7 @@ const SERVER_DESCRIPTION =
   "Gortex code graph of the indexed repositories: symbol search, source reads, usages, " +
   "call chains, change impact and graph-aware edits.";
 
-// Pi 0.87 declares none of the MCP members, so they are read structurally.
+// Read structurally, since a Pi before 0.99 has none of these members.
 type NativeMcpApi = Pick<ExtensionAPI, "registerMcpServer" | "unregisterMcpServer" | "getAllTools" | "getCommands">;
 
 export function supportsNativeMcp(pi: ExtensionAPI): boolean {