pi-gortex 0.3.0 → 0.4.1

package/README.md

@@ -13,13 +13,16 @@ need instead of reading whole files around it, which is where the token
 savings come from. It is a single static binary with no dependency chain,
 and it covers 257 languages through tree-sitter.
 
-Pi has no MCP support by design, so this extension is the bridge.
+This extension connects the two. It hands `gortex mcp` to Pi's built-in MCP,
+or runs its own MCP client with `native_mcp` off. Read discipline goes through
+`gortex hook` on both.
 
 ## What it does
 
-- **Registers Gortex's graph tools as native Pi tools**, over a persistent
-  `gortex mcp` child per session. The deferred catalogue is reached through the
-  daemon's own `tools_search`, and promoted tools appear in Pi's registry.
+- **Registers Gortex's graph tools as native Pi tools**, through Pi's
+  built-in MCP or over the extension's own `gortex mcp` child per session. The
+  deferred catalogue is reached through the daemon's own `tools_search`, and
+  promoted tools appear in Pi's registry.
 - **Applies read discipline.** Pi's tool calls are forwarded to
   `gortex hook --agent=pi`, which answers block / soft guidance / nothing
   according to the posture you configured. Gortex owns that logic, so the
@@ -31,7 +34,7 @@ See [docs/architecture.md](docs/architecture.md) for how it works.
 
 ## Requirements
 
-- **Node 24+**, **Pi 0.85+**
+- **Node 24+**, **Pi 1.0+**
 - **The `gortex` binary** on `PATH`, **v0.61.2 or newer**. See
   [Gortex installation](https://github.com/zzet/gortex/blob/main/docs/installation.md).
   The extension starts the shared daemon itself and never blocks Pi's startup
@@ -57,16 +60,16 @@ the absolute path, or a single run with `pi -e /path/to/pi-gortex`.
 ## Configure
 
 Zero configuration required. Every value resolves at runtime, first hit wins:
-environment -> `<cwd>/.pi/gortex.json` -> `<agent dir>/extensions/gortex.json`
+environment -> `<session cwd>/.pi/gortex.json` -> `<agent dir>/extensions/gortex.json`
 (agent dir is `$PI_CODING_AGENT_DIR`, else `~/.pi/agent`) -> defaults.
 
 | Sidecar key    | Environment        | Default            | Meaning |
 |----------------|--------------------|--------------------|---------|
-| `bin`          | `GORTEX_BIN`       | `gortex` on `PATH` | Binary used for `daemon start`, `mcp` and `hook`. |
-| `hook_mode`    | `GORTEX_HOOK_MODE` | `deny`             | Posture: `deny`, `enrich`, `consult-unlock`, `nudge`. |
+| `bin`          | `GORTEX_BIN`       | `gortex` on `PATH` | The gortex binary. Read from the global sidecar only; a project file cannot set it. `~` expands, and a relative path resolves against the sidecar's directory (the launch directory for `GORTEX_BIN`). |
+| `hook_mode`    | `GORTEX_HOOK_MODE` | `deny`             | Posture: `deny`, `enrich`, `consult-unlock`, `nudge` (`adaptive-nudge` is an alias). |
 | `enforce`      | `GORTEX_ENFORCE`   | `true`             | `false` keeps the graph tools and the briefing, and wires no enforcement. |
-| `tools_preset` | `GORTEX_TOOLS`     | `core`             | Eager MCP surface. `core`/`full` use the daemon's default; `edit`/`nav`/`readonly` narrow it. |
-| `native_mcp`   | `GORTEX_NATIVE_MCP` | `true`            | On Pi 0.99+, register `gortex mcp` with Pi's built-in MCP. `false` keeps the extension's own client. |
+| `tools_preset` | `GORTEX_TOOLS`     | daemon's default   | Eager MCP surface: a Gortex preset (`core`, `full`, `agent`, `edit`, `nav`, `readonly`, `localization`), optionally followed by comma-separated tool names and `+tool`/`-tool` changes, e.g. `nav,+edit_file`. A value that does not open with a preset is ignored. |
+| `native_mcp`   | `GORTEX_NATIVE_MCP` | `true`            | Register `gortex mcp` with Pi's built-in MCP. `false` keeps the extension's own client. |
 
 ```json
 {
@@ -76,8 +79,8 @@ environment -> `<cwd>/.pi/gortex.json` -> `<agent dir>/extensions/gortex.json`
 }
 ```
 
-The extension reads its configuration when Pi loads it, so a change takes
-effect after `/reload`.
+The extension reads its configuration at every session start, from the
+directory the session runs in, so a change takes effect on `/reload` or `/new`.
 
 **Pi's own `mcp.json` wins.** With `native_mcp` on, the extension registers a
 server named `gortex`. A `gortex` entry in `~/.pi/agent/mcp.json` or

package/docs/architecture.md

@@ -68,15 +68,15 @@ implementation forwards the call down that channel.
   arrive in bursts, so the re-sync is debounced; a search call awaits its own
   re-sync directly, so every tool its reply names is callable by the time the
   model reads it.
-- **Framing.** Reads are incremental. The scan for a frame boundary resumes
-  where the previous chunk ended, so one large frame split across many chunks
-  does not re-scan a growing buffer each time. A frame past a generous size cap
-  kills the child, because a stream cannot be resynced mid-frame, and the next
-  call respawns it.
+- **Framing.** Frames are cut at the newline byte and decoded whole, so a
+  character split across chunks arrives intact. A frame past a generous byte
+  cap kills the child, because a stream cannot be resynced mid-frame, and the
+  next call respawns it.
 - **Timeouts.** Every request is bounded: a short cap for ordinary requests, a
   longer one for the handshake, the longest for tool calls. The last is generous
   enough for analyzers that legitimately run for minutes, and finite so a wedged
-  daemon cannot hang an agent turn forever.
+  daemon cannot hang an agent turn forever. A call dropped on timeout or on
+  Pi's abort tells the daemon to cancel it.
 
 ### Tool-name aliasing
 
@@ -88,6 +88,21 @@ built-ins Pi may grow later as well as today's collisions. Each aliased tool
 front-loads the rename into its own description, because Gortex's guidance and
 denial messages name the bare tool and the model has to map it.
 
+### Edit diffs
+
+The daemon reports an applied edit without its content, so the bridge reads the
+files a write names before and after the call and stores their diffs in the
+result's `details`, shaped like Pi's own edit details (see `src/diff.ts`). The
+model still reads only Gortex's reply.
+
+On Pi's built-in MCP the reads ride the `tool_call` and `tool_result` events.
+Pi prepares a whole parallel batch before running it, so no lock can span a
+call; a file two calls in flight write gets no diff instead.
+
+A wrong diff is worse than none, so where one could mislead or stall Pi (a
+shell command running alongside, or a change a line diff cannot show cheaply) a
+one-line note stands in for it.
+
 ## Channel 2: read discipline over the hook bridge
 
 Every tool call Pi is about to run is forwarded to Gortex's hook with a
@@ -100,7 +115,8 @@ keys. That translation lives on this side of the bridge, so the Go side keeps
 one vocabulary for every agent it serves.
 
 A call to a Gortex tool is flagged as a graph call and sent under the daemon's
-own tool name, which is what the postures key off. It skips the translation, so
+own tool name, which is what the postures key off. On Pi's built-in MCP that
+means the `mcp__gortex__` prefix is stripped. It skips the translation, so
 Gortex's `read` never passes for Pi's. On Pi's built-in MCP the same hook also
 sees each tool a codemode script calls.
 
@@ -109,11 +125,14 @@ behaviour identical across hosts.
 
 ## Orientation injection
 
-The session briefing rides a tail user message appended during context assembly.
-Carrying it in the system prompt would place it at the head of the conversation,
-where a change invalidates prefix prompt caching on every turn. The text is
-computed once per session and cleared only once it has been appended, so a
-context shape the extension cannot append to does not silently drop it.
+The session briefing is stored once in the session history as a hidden message,
+so every LLM call carries it. It stays out of the system prompt, because a
+change there invalidates prefix prompt caching.
+
+## Withdrawn tools
+
+Pi cannot unregister a tool, so one the daemon withdraws leaves Pi's active tool
+set instead.
 
 ## The readiness barrier
 
@@ -174,3 +193,21 @@ Every value resolves at runtime, layered from the environment down through a
 project file and a global one to defaults. See the table in the
 [README](../README.md#configure). Runtime resolution is what lets one artifact
 serve both the npm package and a directory install.
+
+Resolution runs on every `session_start`, against the session's own directory.
+A resumed session runs where it was created, which need not be where Pi was
+launched. So the native server is registered on `session_start` rather than
+when Pi loads the extension, and again only when the session's preset or
+channel differ, since Pi reconnects a re-registered server. Pi reads a
+registration made before its own `session_start` handler and connects one made
+after it. The extension's own `gortex mcp` is spawned in the session's
+directory, which is what the proxy scopes the graph to.
+
+A tool preset reaches `gortex mcp` only when it opens with a preset Gortex
+knows. Gortex reads anything else as a bare allow-list, so a typo would strand
+the session; it falls through to the next layer instead. The resolved value
+always overrides an inherited `GORTEX_TOOLS`.
+
+The project file sits in whatever repository the session runs in, so it cannot
+set `bin`. Otherwise a cloned repository could choose the executable the
+extension spawns. The binary comes from `GORTEX_BIN`, the global file or `PATH`.

package/docs/tests.md

@@ -88,15 +88,15 @@ point in the directory when the manifest resolves to nothing.
 ## Where the double stops
 
 The double models what the suites need and no more. Behaviour past that edge,
-such as promotion re-sync under real notification traffic, frame splitting, the
-frame size cap, a real model turn or a live daemon, is unverified here. A change
+such as promotion re-sync under real notification traffic, a real model turn or
+a live daemon, is unverified here. A change
 in that territory is verified by hand against a running Gortex, and the suite
 says as much rather than implying coverage it does not have.
 
 ## Pinning
 
-The Pi devDependency is pinned tight on purpose. Pi is pre-1.0 and its runner's
-method surface has been renamed without a changelog entry before, so a tight pin
+The Pi devDependency is pinned tight on purpose. Pi's runner's method surface
+has been renamed without a changelog entry before, so a tight pin
 turns that into a red build rather than a silently skipped suite. The runtime
 peer dependency stays wide.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gortex",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Gortex for Pi: high-performance code-intelligence engine for AI agents, based on graph. Exposes only the information the agent needs, cutting token usage up to 50x. 100% local.",
   "keywords": [
     "pi-package",
@@ -35,8 +35,8 @@
     "prepublishOnly": "npm run check"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "~1.0.2",
-    "@earendil-works/pi-tui": "^1.0.2",
+    "@earendil-works/pi-coding-agent": "1.0.2",
+    "@earendil-works/pi-tui": "1.0.2",
     "@types/node": "^24.19.1",
     "jiti": "^2.7.0",
     "typescript": "^7.0.2"

package/src/config.ts

@@ -7,17 +7,17 @@
 
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, isAbsolute, join, resolve } 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. */
+  /** The gortex binary. Global sidecar only; relative to the sidecar's directory. 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. */
+  /** Eager MCP tool preset (core | full | agent | edit | nav | readonly | localization) or a tool spec. */
   tools_preset?: string;
   /** false keeps the extension's own MCP client on a Pi that has built-in MCP. */
   native_mcp?: boolean;
@@ -31,7 +31,7 @@ export interface GortexConfig {
   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. */
+  /** GORTEX_TOOLS for `gortex mcp`; empty leaves the daemon's default surface. */
   toolsPreset: string;
   /** Whether to hand the tool channel to Pi's built-in MCP when Pi has one. */
   nativeMcp: boolean;
@@ -47,7 +47,15 @@ export interface ResolveConfigOptions {
 }
 
 export const DEFAULT_BIN = "gortex";
-export const DEFAULT_TOOLS_PRESET = "core";
+/** No preset: `gortex mcp` serves the daemon's default surface. */
+export const DEFAULT_TOOLS_PRESET = "";
+
+/** Expands a leading `~`, `~/` or `~\` to the home directory. */
+export function expandHome(path: string, home: string = homedir()): string {
+  if (path === "~") return home;
+  if (path.startsWith("~/") || path.startsWith("~\\")) return join(home, path.slice(2));
+  return path;
+}
 
 /**
  * Pi's agent directory, resolved the way Pi itself resolves it
@@ -59,15 +67,46 @@ export const DEFAULT_TOOLS_PRESET = "core";
  */
 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;
-  }
+  if (override && override.trim() !== "") return expandHome(override.trim());
   return join(homedir(), ".pi", "agent");
 }
 
+/**
+ * A `bin` setting as spawn needs it: `~` expanded, a relative path anchored at
+ * `baseDir`, a bare name left for PATH lookup.
+ */
+export function resolveBin(bin: string, baseDir: string): string {
+  const expanded = expandHome(bin);
+  if (!/[\\/]/.test(expanded) || isAbsolute(expanded)) return expanded;
+  return resolve(baseDir, expanded);
+}
+
+// Preset names and aliases Gortex accepts (internal/mcp/tool_presets.go).
+const KNOWN_PRESETS = new Set([
+  "full", "all",
+  "core", "default", "classic",
+  "agent", "coding-agent",
+  "facade-v1", "agent-v2", "compact", "facade",
+  "readonly", "read-only", "read_only",
+  "edit", "editor", "edit-harness",
+  "nav", "navigate", "explore",
+  "localization", "locate", "find",
+]);
+
+/**
+ * A tools_preset / GORTEX_TOOLS value Gortex should see, or undefined. Gortex
+ * reads a spec that does not open with a preset as a bare allow-list, so a
+ * typo (or `+tool` alone) would strip the session down to a tool or two. Only
+ * a spec opening with a known preset passes, optionally followed by
+ * comma-separated tool names and `+tool`/`-tool` changes.
+ */
+export function toolsSpec(value: string | undefined): string | undefined {
+  const tokens = (value ?? "").split(",").map((token) => token.trim()).filter(Boolean);
+  const preset = tokens[0]?.toLowerCase();
+  if (preset === undefined || !KNOWN_PRESETS.has(preset)) return undefined;
+  return [preset, ...tokens.slice(1)].join(",");
+}
+
 /** 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")];
@@ -139,29 +178,41 @@ export function resolveConfig(opts: ResolveConfigOptions = {}): GortexConfig {
   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 [projectPath, globalPath] = sidecarPaths(cwd, agentDir) as [string, string];
+  const project = readSidecar(projectPath, readFile);
+  const global = readSidecar(globalPath, readFile);
+
+  // A checked-out repository must never pick the executable, so the project
+  // sidecar has no say in `bin`. `gortex` unqualified is resolved against PATH.
+  const envBin = firstString(env.GORTEX_BIN);
+  const globalBin = firstString(global.bin);
+  const bin = envBin
+    ? resolveBin(envBin, process.cwd())
+    : globalBin
+      ? resolveBin(globalBin, dirname(globalPath))
+      : 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) ??
+    (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;
+    toolsSpec(env.GORTEX_TOOLS) ??
+    toolsSpec(firstString(project.tools_preset)) ??
+    toolsSpec(firstString(global.tools_preset)) ??
+    DEFAULT_TOOLS_PRESET;
 
   const nativeMcp =
     parseBoolean(env.GORTEX_NATIVE_MCP) ??
-    (typeof project?.native_mcp === "boolean" ? project.native_mcp : undefined) ??
-    (typeof global?.native_mcp === "boolean" ? global.native_mcp : undefined) ??
+    (typeof project.native_mcp === "boolean" ? project.native_mcp : undefined) ??
+    (typeof global.native_mcp === "boolean" ? global.native_mcp : undefined) ??
     true;
 
   return { bin, hookArgv, enforce, toolsPreset, nativeMcp };