pi-gortex 0.1.0

package/src/mcp-client.ts

@@ -0,0 +1,338 @@
+// MCP stdio client: newline-delimited JSON-RPC 2.0 over one `gortex mcp` child
+// per session.
+
+import type { BridgeChild, ProcessDeps } from "./runtime.ts";
+
+export const INIT_TIMEOUT_MS = 60_000;
+export const RPC_TIMEOUT_MS = 30_000;
+// tools/call cap: generous enough for long analyzers, finite so a wedged
+// daemon behind a still-alive child can't hang the agent turn forever.
+export const CALL_TIMEOUT_MS = 600_000;
+// A single JSON-RPC frame past this cap kills the child: the stream
+// can't be resynced mid-frame.
+export const MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+
+// Identity reported as MCP clientInfo, plus the wire formats this client can
+// decode: the daemon reads the capability and sends list-shaped results compact
+// without needing a client-name allowlist entry.
+export const CLIENT_NAME = "pi";
+export const CLIENT_VERSION = "1.0.0";
+export const WIRE_FORMATS: string[] = ["gcx"];
+export const PROTOCOL_VERSION = "2025-06-18";
+
+// Floor for the daemon. gortex v0.61.2 is where `gortex mcp` first served the
+// persistent bridge this client dials; older daemons expose a fixed tool facade
+// with nothing on the other end of the handshake.
+export const MIN_GORTEX_VERSION = "0.61.2";
+
+/**
+ * Dotted-numeric comparison, prerelease and build suffixes ignored, since the
+ * daemon reports "0.64.4" while its CLI prints "v0.64.4+2b5480bf". Unparseable
+ * segments count as 0, so a version this cannot read never trips the warning.
+ */
+export function isBelowVersion(actual: string, floor: string): boolean {
+  const parse = (v: string): number[] =>
+    v
+      .replace(/^v/, "")
+      .split(/[+-]/)[0]!
+      .split(".")
+      .map((part) => Number.parseInt(part, 10) || 0);
+  const a = parse(actual);
+  const b = parse(floor);
+  for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+    const delta = (a[i] ?? 0) - (b[i] ?? 0);
+    if (delta !== 0) return delta < 0;
+  }
+  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"]);
+
+export interface MCPStdioClientOptions {
+  bin: string;
+  toolsPreset: string;
+  deps: ProcessDeps;
+  env?: Record<string, string | undefined>;
+}
+
+interface PendingRequest {
+  resolve: (value: unknown) => void;
+  reject: (err: Error) => void;
+  timer?: ReturnType<typeof setTimeout>;
+}
+
+export interface ToolDescriptor {
+  name: string;
+  description?: string;
+  inputSchema?: unknown;
+}
+
+/**
+ * ensureDaemon brings the shared Gortex daemon up before the MCP child dials
+ * it. Idempotent, fire-and-forget (we don't block on the launcher's <=60s
+ * readiness poll), and never throws, since a missing binary or spawn failure
+ * must not take the extension down. The bridge's initialize retry absorbs the
+ * warm-up window.
+ */
+export function ensureDaemon(bin: string, deps: ProcessDeps): void {
+  try {
+    const child = deps.spawn(bin, ["daemon", "start", "--detach"], {
+      stdio: "ignore",
+      detached: true,
+    });
+    child.on("error", () => {}); // binary missing / spawn failure: swallow
+    // No teardown counterpart, by design: the daemon is shared, long-lived
+    // infrastructure that outlives the session.
+    child.unref?.();
+  } catch {
+    // never fatal
+  }
+}
+
+/** textFromResult joins the text parts of an MCP tools/call result. */
+export function textFromResult(result: unknown): string {
+  const content = (result as { content?: unknown })?.content;
+  const parts = Array.isArray(content) ? content : [];
+  return parts
+    .filter((c): c is { type: string; text: string } =>
+      Boolean(c) && (c as { type?: unknown }).type === "text" &&
+      typeof (c as { text?: unknown }).text === "string",
+    )
+    .map((c) => c.text)
+    .join("\n");
+}
+
+export class MCPStdioClient {
+  private child: BridgeChild | null = null;
+  private buffer = "";
+  private searchStart = 0;
+  private nextId = 1;
+  private pending = new Map<number, PendingRequest>();
+  private exited = true;
+  private respawnPromise: Promise<void> | null = null;
+
+  private readonly bin: string;
+  private readonly toolsPreset: string;
+  private readonly deps: ProcessDeps;
+  private readonly env: Record<string, string | undefined>;
+
+  // Fired on notifications/tools/list_changed (server-side promotion).
+  onToolsListChanged: (() => void) | null = null;
+
+  // Read off the handshake reply. Empty when the daemon withheld the field,
+  // which reads as "unknown" everywhere and never as a mismatch.
+  serverVersion = "";
+  negotiatedProtocol = "";
+
+  constructor(options: MCPStdioClientOptions) {
+    this.bin = options.bin;
+    this.toolsPreset = options.toolsPreset;
+    this.deps = options.deps;
+    this.env = options.env ?? process.env;
+  }
+
+  private childEnv(): Record<string, string | undefined> {
+    const env: Record<string, string | undefined> = { ...this.env };
+    const preset = this.toolsPreset.trim().toLowerCase();
+    // The daemon's own default surface already IS core/defer; only a
+    // recognised non-default preset needs the proxy-side narrowing.
+    if (!env.GORTEX_TOOLS && FORWARDED_PRESETS.has(preset)) {
+      env.GORTEX_TOOLS = preset;
+    }
+    // Never let a preset hide-block tools promoted later by tools_search.
+    if (env.GORTEX_TOOLS && !env.GORTEX_TOOLS_MODE) env.GORTEX_TOOLS_MODE = "defer";
+    return env;
+  }
+
+  private spawnChild(): void {
+    const child = this.deps.spawn(this.bin, ["mcp"], {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: this.childEnv(),
+    });
+    this.child = child;
+    this.buffer = "";
+    this.searchStart = 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
+    // to the terminal would corrupt Pi's TUI.
+    child.stderr?.on("data", () => {});
+    child.stdin?.on("error", () => {}); // EPIPE race: child may exit before stdin.write() finishes
+    child.on("error", () => this.markExited(new Error("gortex mcp spawn failed")));
+    child.on("exit", () => this.markExited(new Error("gortex mcp exited")));
+  }
+
+  private markExited(err: Error): void {
+    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);
+    }
+    this.pending.clear();
+  }
+
+  private onData(chunk: Buffer): void {
+    this.buffer += chunk.toString("utf8");
+    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);
+    }
+    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
+      }
+    }
+  }
+
+  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);
+      }
+      return;
+    }
+    if (frame && frame.method === "notifications/tools/list_changed") {
+      try {
+        this.onToolsListChanged?.();
+      } catch {
+        // best effort; never break the read loop.
+      }
+    }
+  }
+
+  private send(obj: Record<string, unknown>): void {
+    if (!this.child || this.exited) throw new Error("gortex mcp is not running");
+    this.child.stdin?.write(JSON.stringify(obj) + "\n");
+  }
+
+  // A single shared respawn: concurrent callers of request() against a
+  // dead child all await the same spawn+initialize, so a burst of tool
+  // calls can never fork multiple children.
+  private respawn(): Promise<void> {
+    if (!this.respawnPromise) {
+      this.respawnPromise = (async () => {
+        this.spawnChild();
+        await this.initialize();
+      })().finally(() => {
+        this.respawnPromise = null;
+      });
+    }
+    return this.respawnPromise;
+  }
+
+  async request(method: string, params: unknown, timeoutMs: number = RPC_TIMEOUT_MS): Promise<unknown> {
+    if (this.exited) await this.respawn();
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const entry: PendingRequest = { resolve, reject };
+      if (Number.isFinite(timeoutMs)) {
+        entry.timer = setTimeout(() => {
+          this.pending.delete(id);
+          reject(new Error(`${method} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+      }
+      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)));
+      }
+    });
+  }
+
+  private notify(method: string, params: unknown): void {
+    try {
+      this.send({ jsonrpc: "2.0", method, params });
+    } catch {
+      // notifications are best-effort.
+    }
+  }
+
+  private async initialize(): Promise<void> {
+    const result = (await this.request(
+      "initialize",
+      {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { experimental: { "gortex/wire": WIRE_FORMATS } },
+        clientInfo: { name: CLIENT_NAME, version: CLIENT_VERSION },
+      },
+      INIT_TIMEOUT_MS,
+    )) as { protocolVersion?: unknown; serverInfo?: { version?: unknown } } | null;
+    const version = result?.serverInfo?.version;
+    this.serverVersion = typeof version === "string" ? version : "";
+    this.negotiatedProtocol =
+      typeof result?.protocolVersion === "string" ? result.protocolVersion : "";
+    this.notify("notifications/initialized", {});
+  }
+
+  // start spawns the child and runs the MCP handshake, retrying once
+  // after a 1s backoff, since the daemon may still be warming up right
+  // after ensureDaemon() kicked it off.
+  async start(): Promise<void> {
+    this.spawnChild();
+    try {
+      await this.initialize();
+    } catch {
+      await new Promise((r) => setTimeout(r, 1_000));
+      if (this.exited) this.spawnChild();
+      await this.initialize();
+    }
+  }
+
+  async listTools(): Promise<ToolDescriptor[]> {
+    const res = (await this.request("tools/list", {})) as { tools?: unknown };
+    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);
+  }
+
+  stop(): void {
+    const child = this.child;
+    this.markExited(new Error("gortex mcp bridge stopped"));
+    try {
+      child?.kill();
+    } catch {
+      // already gone
+    }
+  }
+}

package/src/runtime.ts

@@ -0,0 +1,58 @@
+// The process seam: everything the extension does to the outside world goes
+// through `spawn` and `execFileSync`, injectable so the suite can drive the
+// bridge against a fake `gortex mcp` child. The types below describe only what
+// the bridge uses, so a double stays a small object.
+
+import { execFileSync as nodeExecFileSync, spawn as nodeSpawn } from "node:child_process";
+import type { SpawnOptions } from "node:child_process";
+
+export interface ChildStream {
+  on(event: string, listener: (chunk: unknown) => void): unknown;
+}
+
+export interface ChildStdin {
+  on(event: string, listener: (err: unknown) => void): unknown;
+  write(chunk: string): unknown;
+}
+
+/** The subset of ChildProcess the MCP bridge and the daemon launcher touch. */
+export interface BridgeChild {
+  stdout?: ChildStream;
+  stderr?: ChildStream;
+  stdin?: ChildStdin;
+  on(event: string, listener: (...args: unknown[]) => void): unknown;
+  kill(): unknown;
+  unref?(): unknown;
+}
+
+export interface SpawnOpts {
+  stdio?: "ignore" | ("pipe" | "ignore")[];
+  detached?: boolean;
+  env?: Record<string, string | undefined>;
+}
+
+export interface ExecFileSyncOpts {
+  input?: string;
+  encoding?: "utf8";
+  maxBuffer?: number;
+  timeout?: number;
+}
+
+export interface ProcessDeps {
+  spawn(command: string, args: string[], options?: SpawnOpts): BridgeChild;
+  execFileSync(command: string, args: string[], options?: ExecFileSyncOpts): string;
+}
+
+/**
+ * The real implementations. The two casts are the whole impedance mismatch
+ * between node's overloaded signatures and the narrow surface above; every
+ * consumer downstream stays strictly typed.
+ */
+export const nodeProcessDeps: ProcessDeps = {
+  spawn(command, args, options) {
+    return nodeSpawn(command, args, (options ?? {}) as SpawnOptions) as unknown as BridgeChild;
+  },
+  execFileSync(command, args, options) {
+    return String(nodeExecFileSync(command, args, { ...options, encoding: "utf8" }));
+  },
+};

package/src/state.ts

@@ -0,0 +1,56 @@
+// Module-level session state.
+//
+// Shared at module level on purpose: a new invocation's session_start stops the
+// previous invocation's bridge child, which works only while both invocations
+// see the same `client`. Move this into the factory closure and every `/new`
+// leaks a `gortex mcp` process.
+
+import type { MCPStdioClient } from "./mcp-client.ts";
+
+/** The session's live bridge, or null when the handshake failed. */
+let client: MCPStdioClient | null = null;
+
+/**
+ * Why the bridge is down this session (empty when it is up). Surfaced once
+ * through the orientation injection so the user learns that /reload retries
+ * the handshake.
+ */
+let bridgeError = "";
+
+/**
+ * How the daemon is out of step with this extension (empty when it is not).
+ * Surfaced once to the model alongside the orientation; the user learns about
+ * it through ctx.ui.notify at session_start, which never reaches the model.
+ */
+let versionWarning = "";
+
+/**
+ * Names the Gortex tools are registered under in Pi. Usually the bare daemon
+ * name, except for a few aliased to dodge Pi's built-ins (see piAliasName).
+ * Tracks the post-alias name.
+ */
+export const gortexToolNames = new Set<string>();
+
+export function getClient(): MCPStdioClient | null {
+  return client;
+}
+
+export function setClient(next: MCPStdioClient | null): void {
+  client = next;
+}
+
+export function getBridgeError(): string {
+  return bridgeError;
+}
+
+export function setBridgeError(message: string): void {
+  bridgeError = message;
+}
+
+export function getVersionWarning(): string {
+  return versionWarning;
+}
+
+export function setVersionWarning(message: string): void {
+  versionWarning = message;
+}

package/src/tools.ts

@@ -0,0 +1,180 @@
+// Tool registration: each tool the bridge lists becomes a native Pi tool whose
+// execute() forwards to tools/call.
+
+import { createRequire } from "node:module";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { textFromResult } from "./mcp-client.ts";
+import type { ToolDescriptor } from "./mcp-client.ts";
+import { getClient, gortexToolNames } from "./state.ts";
+import { toolNameMap } from "./hook.ts";
+
+// Pi's reserved built-in names (mirrors toolNameMap's keys). A bridge tool that
+// reuses one would silently replace the built-in, breaking Pi's own rendering
+// and anything hooked to it. Only "edit"/"read" collide today; guarding all
+// seven covers built-ins Pi adds later.
+const PI_RESERVED_TOOL_NAMES = new Set(Object.keys(toolNameMap));
+const PI_ALIAS_PREFIX = "gortex_";
+
+/**
+ * piAliasName is unchanged unless name collides with a built-in above, in
+ * which case it's registered under a `gortex_`-prefixed alias instead.
+ */
+export function piAliasName(name: string): string {
+  return PI_RESERVED_TOOL_NAMES.has(name) ? PI_ALIAS_PREFIX + name : name;
+}
+
+/** piAliasedDescription front-loads the rename into the tool's own description. */
+export function piAliasedDescription(bare: string, aliased: string, description: string): string {
+  if (bare === aliased) return description;
+  return (
+    `Gortex's \`${bare}\` tool, registered as \`${aliased}\` because Pi has a built-in ` +
+    `\`${bare}\`. Gortex guidance and denial messages that name \`${bare}\` mean this tool.` +
+    `\n\n${description}`
+  );
+}
+
+// Pi's own tool definitions are TypeBox-typed; the bridge's parameters are the
+// daemon's raw JSON Schema, passed through untouched. This is the one place
+// the two vocabularies meet.
+type RegisterableTool = Parameters<ExtensionAPI["registerTool"]>[0];
+
+interface BridgeToolDefinition {
+  name: string;
+  label: string;
+  description: string;
+  parameters: unknown;
+  execute(toolCallId: string, params: Record<string, unknown>): Promise<unknown>;
+  renderResult?: (result: unknown, options: { expanded?: boolean }) => unknown;
+}
+
+/**
+ * safeRegister registers under the alias name (piAliasName). registerTool is a
+ * map insert, so a repeat registration is harmless; the catch is for a late
+ * registration from a superseded session, which throws once Pi has invalidated
+ * that extension instance. Returns the name actually registered.
+ */
+export function safeRegister(pi: ExtensionAPI, def: BridgeToolDefinition): string {
+  def.name = piAliasName(def.name);
+  def.label = def.name;
+  try {
+    pi.registerTool(def as unknown as RegisterableTool);
+  } catch {
+    // already live this session, or this instance has been invalidated: the
+    // existing registration stands.
+  }
+  return def.name;
+}
+
+// Lazily resolved TUI Text component, used only to collapse a gortex tool's
+// result to nothing until the user expands it (ctrl+o). Resolved through
+// createRequire rather than a static import so a Pi packaging that can't
+// provide @earendil-works/pi-tui degrades to Pi's default renderer instead of
+// throwing at load and taking tool registration down with it.
+type TextComponent = new (text: string, x: number, y: number) => unknown;
+let TuiText: TextComponent | undefined;
+try {
+  const require = createRequire(import.meta.url);
+  TuiText = (require("@earendil-works/pi-tui") as { Text: TextComponent }).Text;
+} catch {
+  TuiText = undefined;
+}
+
+function resultText(result: unknown): string {
+  const structured = (result as { structuredContent?: unknown })?.structuredContent;
+  return textFromResult(result) || JSON.stringify(structured ?? result ?? {});
+}
+
+/**
+ * Registers one Gortex tool under its bare daemon name (or its alias).
+ * Idempotent: a name already registered is skipped. Adds the name to
+ * gortexToolNames so the read-discipline postures treat a call to it as a graph
+ * query.
+ *
+ * renderResult collapses the result to nothing until the user expands it with
+ * ctrl+o; Pi's fallback renderCall already shows the tool name.
+ */
+export function registerOneTool(pi: ExtensionAPI, desc: ToolDescriptor): void {
+  const name = desc.name;
+  if (!name) return;
+  if (gortexToolNames.has(piAliasName(name))) return;
+  const parameters =
+    desc.inputSchema && typeof desc.inputSchema === "object"
+      ? desc.inputSchema
+      : { type: "object", properties: {} };
+  const def: BridgeToolDefinition = {
+    name,
+    label: name,
+    description: piAliasedDescription(name, piAliasName(name), (desc.description || name).trim()),
+    parameters,
+    async execute(_id: string, params: Record<string, unknown>) {
+      const client = getClient();
+      if (!client) throw new Error(`gortex ${name}: MCP bridge is not connected`);
+      let result: unknown;
+      try {
+        result = await client.callTool(name, params ?? {});
+      } catch (err) {
+        throw new Error(`gortex ${name} failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      if (name === "tools_search") {
+        // The daemon just promoted the matches and fired list_changed;
+        // register them NOW (bypassing the debounce) so every tool the
+        // reply cites is already callable when the model reads it.
+        await syncTools(pi);
+      }
+      const text = resultText(result);
+      if ((result as { isError?: boolean })?.isError) throw new Error(text || `gortex ${name} failed`);
+      return { content: [{ type: "text", text }], details: {} };
+    },
+  };
+  if (TuiText) {
+    const Text = TuiText;
+    def.renderResult = (result: unknown, options: { expanded?: boolean }) => {
+      if (!options?.expanded) return new Text("", 0, 0);
+      return new Text(resultText(result), 0, 0);
+    };
+  }
+  gortexToolNames.add(safeRegister(pi, def));
+}
+
+/** Registers the daemon's eager tool surface, discovery tool included. */
+export async function registerGortexTools(pi: ExtensionAPI): Promise<void> {
+  const client = getClient();
+  if (!client) return;
+  for (const desc of await client.listTools()) {
+    if (!desc) continue;
+    registerOneTool(pi, desc);
+  }
+}
+
+/** Re-fetches the tool list after a list_changed and registers anything new. */
+export async function syncTools(pi: ExtensionAPI): Promise<void> {
+  try {
+    await registerGortexTools(pi);
+  } catch {
+    // transient; the next promotion or session retries.
+  }
+}
+
+// The daemon fires one list_changed per promoted tool, so a tools_search sweep
+// arrives as a burst; debounce to a single trailing re-fetch. (The tools_search
+// execute() path awaits syncTools directly, bypassing this timer.)
+const SYNC_DEBOUNCE_MS = 200;
+let syncTimer: ReturnType<typeof setTimeout> | null = null;
+
+export function scheduleSyncTools(pi: ExtensionAPI): void {
+  if (syncTimer) clearTimeout(syncTimer);
+  syncTimer = setTimeout(() => {
+    syncTimer = null;
+    void syncTools(pi);
+  }, SYNC_DEBOUNCE_MS);
+}
+
+/** Cancels a pending re-sync; a new session re-registers from scratch. */
+export function clearSyncTimer(): void {
+  if (syncTimer) {
+    clearTimeout(syncTimer);
+    syncTimer = null;
+  }
+}