pi-gortex 0.1.0

package/src/config.ts

@@ -0,0 +1,158 @@
+// Configuration resolution: environment, then a project sidecar, then a global
+// one, then defaults; first hit wins. The README documents the keys.
+//
+// A missing or malformed file is never fatal and falls through to the next
+// layer, because losing the graph tools over a stray comma would be a worse
+// failure than running with defaults.
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** The sidecar file's on-disk shape. `gortex init` is its writer. */
+export interface SidecarConfig {
+  /** Absolute path to the gortex binary. Default: resolved from PATH. */
+  bin?: string;
+  /** Hook posture: deny | enrich | consult-unlock | nudge. */
+  hook_mode?: string;
+  /** false mirrors `gortex init --no-hooks`: orientation only, no enforcement. */
+  enforce?: boolean;
+  /** Eager MCP tool preset: core | full | edit | nav | readonly. */
+  tools_preset?: string;
+}
+
+/** Everything the extension needs to run, fully resolved. */
+export interface GortexConfig {
+  /** Binary used for `daemon start`, `mcp` and `hook`. */
+  bin: string;
+  /** Full argv for the hook bridge, e.g. [bin, "hook", "--agent=pi", "--mode=enrich"]. */
+  hookArgv: string[];
+  /** Whether to wire read-discipline enforcement onto tool_call. */
+  enforce: boolean;
+  /** Eager tool preset; the daemon's default applies when this is core/full. */
+  toolsPreset: string;
+}
+
+/** Seams for tests; every one defaults to the real environment. */
+export interface ResolveConfigOptions {
+  env?: Record<string, string | undefined>;
+  cwd?: string;
+  /** Pi's agent directory. Default: $PI_CODING_AGENT_DIR, else ~/.pi/agent. */
+  agentDir?: string;
+  readFile?: (path: string) => string;
+}
+
+export const DEFAULT_BIN = "gortex";
+export const DEFAULT_TOOLS_PRESET = "core";
+
+/**
+ * Pi's agent directory, resolved the way Pi itself resolves it
+ * (config.ts::getAgentDir in @earendil-works/pi-coding-agent).
+ *
+ * Re-derived here because the extension keeps zero runtime dependencies, so it
+ * also loads as a bare directory extension with no node_modules beside it.
+ * Pi's types are imported as types only, and erased.
+ */
+export function defaultAgentDir(env: Record<string, string | undefined> = process.env): string {
+  const override = env.PI_CODING_AGENT_DIR;
+  if (override && override.trim() !== "") {
+    const path = override.trim();
+    if (path === "~") return homedir();
+    if (path.startsWith("~/")) return join(homedir(), path.slice(2));
+    return path;
+  }
+  return join(homedir(), ".pi", "agent");
+}
+
+/** Sidecar paths, nearest first. A project file wins over the global one. */
+export function sidecarPaths(cwd: string, agentDir: string): string[] {
+  return [join(cwd, ".pi", "gortex.json"), join(agentDir, "extensions", "gortex.json")];
+}
+
+function readSidecar(path: string, readFile: (p: string) => string): SidecarConfig {
+  let raw: string;
+  try {
+    raw = readFile(path);
+  } catch {
+    return {}; // absent is the common case
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return parsed !== null && typeof parsed === "object" ? (parsed as SidecarConfig) : {};
+  } catch {
+    // Malformed JSON falls through to the next layer. Nothing here can log
+    // without corrupting Pi's TUI.
+    return {};
+  }
+}
+
+/**
+ * Hook postures the Go side accepts. Anything unrecognised (including empty)
+ * collapses to "deny", which is also the hook's own default.
+ */
+export function normalizeMode(mode: string | undefined): string {
+  switch ((mode ?? "").trim().toLowerCase()) {
+    case "enrich":
+      return "enrich";
+    case "consult-unlock":
+      return "consult-unlock";
+    case "nudge":
+    case "adaptive-nudge":
+      return "nudge";
+    default:
+      return "deny";
+  }
+}
+
+/** Accepts the spellings a shell user reaches for; anything else is undefined. */
+export function parseBoolean(value: string | undefined): boolean | undefined {
+  switch ((value ?? "").trim().toLowerCase()) {
+    case "1":
+    case "true":
+    case "yes":
+    case "on":
+      return true;
+    case "0":
+    case "false":
+    case "no":
+    case "off":
+      return false;
+    default:
+      return undefined;
+  }
+}
+
+function firstString(...values: (string | undefined)[]): string | undefined {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim() !== "") return value.trim();
+  }
+  return undefined;
+}
+
+export function resolveConfig(opts: ResolveConfigOptions = {}): GortexConfig {
+  const env = opts.env ?? process.env;
+  const cwd = opts.cwd ?? process.cwd();
+  const agentDir = opts.agentDir ?? defaultAgentDir(env);
+  const readFile = opts.readFile ?? ((path: string) => readFileSync(path, "utf8"));
+
+  const [project, global] = sidecarPaths(cwd, agentDir).map((path) => readSidecar(path, readFile));
+
+  // `gortex` unqualified is resolved by spawn against PATH.
+  const bin = firstString(env.GORTEX_BIN, project?.bin, global?.bin) ?? DEFAULT_BIN;
+
+  const mode = normalizeMode(firstString(env.GORTEX_HOOK_MODE, project?.hook_mode, global?.hook_mode));
+  const hookArgv = [bin, "hook", "--agent=pi"];
+  // "deny" is the hook's own default, so it rides as an absent flag.
+  if (mode !== "deny") hookArgv.push(`--mode=${mode}`);
+
+  const enforce =
+    parseBoolean(env.GORTEX_ENFORCE) ??
+    (typeof project?.enforce === "boolean" ? project.enforce : undefined) ??
+    (typeof global?.enforce === "boolean" ? global.enforce : undefined) ??
+    true;
+
+  const toolsPreset =
+    firstString(env.GORTEX_TOOLS, project?.tools_preset, global?.tools_preset) ?? DEFAULT_TOOLS_PRESET;
+
+  return { bin, hookArgv, enforce, toolsPreset };
+}

package/src/hook.ts

@@ -0,0 +1,97 @@
+// The hook bridge: `gortex hook --agent=pi`. Pi has no hook configuration, so
+// each event is shelled out with an envelope on stdin and the decision read
+// back is applied.
+
+import type { ExecFileSyncOpts, ProcessDeps } from "./runtime.ts";
+
+/** The decision shape Go writes back (hooks.BridgeDecision). */
+export interface PiDecision {
+  block?: boolean;
+  reason?: string;
+  additional_context?: string;
+  orientation?: string;
+}
+
+/** The envelope the extension writes to the hook's stdin (hooks.BridgeEvent). */
+export interface PiEnvelope {
+  event: string;
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+  cwd?: string;
+  session_id?: string;
+  is_gortex_tool?: boolean;
+}
+
+const HOOK_EXEC_OPTS: ExecFileSyncOpts = {
+  encoding: "utf8",
+  maxBuffer: 16 * 1024 * 1024,
+  timeout: 5_000,
+};
+
+/**
+ * callHook sends a normalized event envelope to `gortex hook --agent=pi` and
+ * parses the PiDecision it writes back. Fail-open: any error returns an empty
+ * decision so the extension never blocks Pi's flow on a hook hiccup (daemon
+ * down, parse error, timeout).
+ */
+export function callHook(argv: string[], deps: ProcessDeps, envelope: PiEnvelope): PiDecision {
+  const [bin, ...args] = argv;
+  if (!bin) return {};
+  try {
+    const out = deps
+      .execFileSync(bin, args, { ...HOOK_EXEC_OPTS, input: JSON.stringify(envelope) })
+      .trim();
+    if (!out) return {};
+    return JSON.parse(out) as PiDecision;
+  } catch {
+    return {};
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tool-call normalization (Pi vocabulary -> canonical Claude-Code vocabulary)
+// ---------------------------------------------------------------------------
+//
+// The Go classifier switches on Claude-Code tool names and canonical input
+// keys ("file_path"/"pattern"/"command"), so the translation lives here.
+//
+// NOTE: Pi is pre-1.0. The built-in tool names mapped here are pinned to Pi's
+// documented API (packages/coding-agent/docs/extensions.md); if an upgrade
+// renames one, adjust this small map; the Go wire contract stays unchanged.
+export const toolNameMap: Record<string, string> = {
+  read: "Read",
+  grep: "Grep",
+  find: "Glob",
+  ls: "Glob",
+  bash: "Bash",
+  edit: "Edit",
+  write: "Write",
+};
+
+function firstString(obj: Record<string, unknown>, keys: string[]): string | undefined {
+  for (const k of keys) {
+    const v = obj[k];
+    if (typeof v === "string" && v !== "") return v;
+  }
+  return undefined;
+}
+
+export function normalizeToolCall(
+  piName: string,
+  piInput: Record<string, unknown>,
+): { tool_name: string; tool_input: Record<string, unknown> } {
+  const canonical = toolNameMap[piName.toLowerCase()] ?? piName;
+  const out: Record<string, unknown> = { ...piInput };
+
+  const path = firstString(piInput, ["file_path", "path", "file", "filepath", "absolute_path"]);
+  if (path !== undefined) out.file_path = path;
+
+  let pattern = firstString(piInput, ["pattern", "glob", "query", "regex", "name"]);
+  if (pattern === undefined && canonical === "Glob") pattern = path;
+  if (pattern !== undefined) out.pattern = pattern;
+
+  const command = firstString(piInput, ["command", "cmd", "script"]);
+  if (command !== undefined) out.command = command;
+
+  return { tool_name: canonical, tool_input: out };
+}

package/src/index.ts

@@ -0,0 +1,313 @@
+// The extension factory: the readiness barrier and the Pi lifecycle wiring for
+// both channels, graph tools over the MCP bridge and read discipline over the
+// hook bridge. See docs/architecture.md for the design.
+
+import type {
+  ContextEvent,
+  ExtensionAPI,
+  ExtensionContext,
+  ToolCallEvent,
+  ToolCallEventResult,
+} from "@earendil-works/pi-coding-agent";
+
+import { resolveConfig } from "./config.ts";
+import type { GortexConfig } from "./config.ts";
+import { callHook, normalizeToolCall } from "./hook.ts";
+import {
+  MCPStdioClient,
+  MIN_GORTEX_VERSION,
+  PROTOCOL_VERSION,
+  ensureDaemon,
+  isBelowVersion,
+} from "./mcp-client.ts";
+import { nodeProcessDeps } from "./runtime.ts";
+import type { ProcessDeps } from "./runtime.ts";
+import {
+  clearSyncTimer,
+  registerGortexTools,
+  scheduleSyncTools,
+} from "./tools.ts";
+import {
+  getBridgeError,
+  getClient,
+  getVersionWarning,
+  gortexToolNames,
+  setBridgeError,
+  setClient,
+  setVersionWarning,
+} from "./state.ts";
+
+export type { GortexConfig, SidecarConfig } from "./config.ts";
+
+/**
+ * How long before_agent_start waits for session_start to finish. Pi arms the
+ * editor's submit handler before session_start runs, at startup and across
+ * /reload and /new, so a fast prompt can reach the agent loop while
+ * registration is still pending. Capped so a wedged daemon costs the first turn
+ * seconds; start() alone can take ~2 min.
+ */
+export const READY_WAIT_MS = 15_000;
+
+/**
+ * Compares the daemon against what this extension is built for and, on a skew,
+ * tells both audiences: the user through Pi's warning channel (which never
+ * enters model context), the model through the orientation, so it knows a tool
+ * may misbehave. Advisory only: the session keeps every tool it registered,
+ * matching the fail-open posture in docs/architecture.md.
+ */
+function reportVersionSkew(
+  ctx: ExtensionContext | undefined,
+  serverVersion: string,
+  negotiatedProtocol: string,
+): void {
+  const stale = serverVersion !== "" && isBelowVersion(serverVersion, MIN_GORTEX_VERSION);
+  const protocolSkew = negotiatedProtocol !== "" && negotiatedProtocol !== PROTOCOL_VERSION;
+  if (!stale && !protocolSkew) return;
+
+  const installed = serverVersion === "" ? "an unreported version" : `gortex ${serverVersion}`;
+  const user = stale
+    ? `${installed} is older than ${MIN_GORTEX_VERSION}, which this extension needs. ` +
+      `Graph tools and read discipline may be missing or wrong. Run \`gortex upgrade\`.`
+    : `${installed} answered the handshake with MCP protocol ${negotiatedProtocol}, ` +
+      `not the ${PROTOCOL_VERSION} this extension speaks. Tool calls may fail. ` +
+      `Run \`gortex upgrade\`.`;
+
+  setVersionWarning(
+    stale
+      ? `[Gortex] the daemon is ${installed}, older than the ${MIN_GORTEX_VERSION} this ` +
+        `extension targets. A graph tool may be missing or behave unexpectedly. If one ` +
+        `does, tell the user to run \`gortex upgrade\`.`
+      : `[Gortex] the daemon negotiated MCP protocol ${negotiatedProtocol} instead of ` +
+        `${PROTOCOL_VERSION}. A graph tool call may fail. If one does, tell the user to ` +
+        `run \`gortex upgrade\`.`,
+  );
+
+  // A Pi build without a UI (print/JSON mode) or without notify must not take
+  // the session down over an advisory message.
+  try {
+    if (ctx?.hasUI) ctx.ui.notify(user, "warning");
+  } catch {
+    // the model still gets the orientation line above
+  }
+}
+
+/** Test seams. Pi itself calls the factory with the `pi` object alone. */
+export interface GortexExtensionOptions {
+  /** Pre-resolved configuration; resolveConfig() runs when this is absent. */
+  config?: GortexConfig;
+  /** Process seam for spawn/execFileSync. */
+  deps?: ProcessDeps;
+  /** Readiness cap override. */
+  readyWaitMs?: 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();
+  const deps = options.deps ?? nodeProcessDeps;
+  const readyWaitMs = options.readyWaitMs ?? READY_WAIT_MS;
+
+  // 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 = "";
+
+  // Settles when the current session_start handler is done: bridge up and
+  // tools registered, or the handshake failed. Never rejects.
+  //
+  // Armed at factory time, because every session builds a fresh instance before
+  // its session_start fires, so an instance can be asked for a turn before its
+  // own handler has run. Every path that constructs an instance goes on to emit
+  // session_start, so the wait ends.
+  let sessionReady!: Promise<void>;
+  let settleSessionReady: () => void = () => {};
+  let sessionReadyPending = false;
+
+  function armSessionReady(): void {
+    if (sessionReadyPending) return; // keep the promise parked waiters hold
+    sessionReadyPending = true;
+    sessionReady = new Promise<void>((resolve) => {
+      settleSessionReady = () => {
+        sessionReadyPending = false;
+        resolve();
+      };
+    });
+  }
+  armSessionReady();
+
+  // Resolves true when session_start finished, false when the cap expired
+  // first. The caller has to tell those apart, since a cap expiry leaves
+  // bridgeError empty.
+  function waitForSession(ms: number): Promise<boolean> {
+    const ready = sessionReady;
+    return new Promise<boolean>((resolve) => {
+      let settled = false;
+      const done = (ok: boolean) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(ok);
+      };
+      const timer = setTimeout(() => done(false), ms);
+      (timer as { unref?: () => void })?.unref?.();
+      ready.then(() => done(true), () => done(true));
+    });
+  }
+
+  // Pi resets the session's tool registry on every session_start, so
+  // (re)register here. Clear the name guard first, since it persists across
+  // sessions and would otherwise suppress re-registration. The previous
+  // session's bridge child (if any) is stopped before a fresh handshake.
+  pi.on("session_start", async (_event, ctx) => {
+    startupHookRan = false;
+    pendingOrientation = "";
+    setBridgeError("");
+    setVersionWarning("");
+    armSessionReady(); // no-op when a turn is already parked on this session
+    const settle = settleSessionReady; // this invocation's resolver
+    try {
+      await startSession(ctx);
+    } finally {
+      settle();
+    }
+  });
+
+  // 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> {
+    ensureDaemon(config.bin, deps);
+    gortexToolNames.clear();
+    clearSyncTimer();
+    const previous = getClient();
+    if (previous) {
+      previous.stop();
+      setClient(null);
+    }
+    const c = new MCPStdioClient({ bin: config.bin, toolsPreset: config.toolsPreset, deps });
+    // 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.
+    setClient(c);
+    try {
+      await c.start();
+      if (getClient() !== c) return; // superseded while handshaking
+      reportVersionSkew(ctx, c.serverVersion, c.negotiatedProtocol);
+      c.onToolsListChanged = () => {
+        scheduleSyncTools(pi);
+      };
+      await registerGortexTools(pi);
+    } catch (err) {
+      // daemon unreachable / binary missing / handshake or tools/list
+      // failure: no graph tools this session; /reload (or the next
+      // session_start) retries.
+      c.stop();
+      if (getClient() === c) {
+        setClient(null);
+        setBridgeError(err instanceof Error ? err.message : String(err));
+      }
+    }
+  }
+
+  // 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 () => {
+    if (startupHookRan) return;
+    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).
+    const ready = await waitForSession(readyWaitMs);
+    const decision = callHook(config.hookArgv, deps, {
+      event: "session_start",
+      cwd: piCwd(),
+    });
+    const parts: string[] = [];
+    const bridgeError = getBridgeError();
+    if (bridgeError) {
+      parts.push(
+        `[Gortex] graph tools are unavailable this session (${bridgeError}). ` +
+        `Tell the user to run /reload to retry the connection.`,
+      );
+      setBridgeError("");
+    } else if (!ready) {
+      // Cap expired mid-handshake: bridgeError is still empty, and this is the
+      // only turn that reports it: startupHookRan latches above, so a
+      // handshake that fails after the cap never reaches the branch above.
+      parts.push(
+        `[Gortex] graph tools were still registering when this turn began, so a tool ` +
+        `named below may not be callable yet. If one is missing, say so and tell the ` +
+        `user to retry, or to run /reload if it stays missing. Don't fall back to ` +
+        `native tools.`,
+      );
+    }
+    const versionWarning = getVersionWarning();
+    if (versionWarning) {
+      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.
+    }
+    return;
+  });
+
+  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 piName: string = (event as { toolName?: string })?.toolName ?? "";
+    const piInput: Record<string, unknown> = (event?.input as Record<string, unknown>) ?? {};
+    const isGortexTool = gortexToolNames.has(piName);
+
+    const norm = normalizeToolCall(piName, piInput);
+    const decision = callHook(config.hookArgv, deps, {
+      event: "tool_call",
+      tool_name: norm.tool_name,
+      tool_input: norm.tool_input,
+      cwd: ctx?.cwd ?? piCwd(),
+      session_id: (ctx as { sessionManager?: { sessionId?: string } })?.sessionManager?.sessionId ?? "",
+      is_gortex_tool: isGortexTool,
+    });
+
+    if (decision.block) {
+      return { block: true, reason: decision.reason ?? "[Gortex] blocked: prefer graph tools." };
+    }
+    if (decision.additional_context) {
+      // Soft guidance: surface it without blocking the call.
+      try {
+        pi.sendMessage(
+          { customType: "gortex", content: decision.additional_context, display: true },
+          { deliverAs: "steer" },
+        );
+      } catch {
+        // sendMessage shape can vary across Pi versions; never fatal.
+      }
+    }
+    return;
+  });
+}