pi-codex-tools 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -6,6 +6,16 @@ This project follows the spirit of [Keep a Changelog](https://keepachangelog.com
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-08-04
+
+### Fixed
+
+- Guard `apply_patch` execution when the active model does not advertise grammar-tool support.
+- Require the Pi runtime grammar-tool contract and fail closed on unsupported filesystem platforms.
+- Preflight repeated file hunks sequentially without rejecting valid Codex patches.
+- Respect `enableInstallTelemetry: false` even when `PI_TELEMETRY` is enabled.
+- Document credential-containing target reads, telemetry controls, runtime requirements, and line-oriented compatibility.
+
 ## [0.1.0] - 2026-08-03
 
 ### Added

package/README.md

@@ -6,7 +6,7 @@ Give grammar-capable OpenAI/Codex models the Codex `apply_patch` tool in Pi with
 
 - **Raw `apply_patch`** — sends Codex's Lark grammar as an OpenAI custom tool, so patches are not JSON-wrapped.
 - **Capability-based activation** — requires `openai-codex-responses` or `openai-responses` plus `model.compat.supportsOpenAIGrammarTools === true`; model names alone are never enough.
-- **Safe local mutation** — patches are limited to 1 MiB, target files to 64 MiB, stay under Pi's current working directory, reject symlink escapes, use descriptor-anchored no-follow operations on Linux/macOS, fail closed elsewhere, preflight all hunks, and serialize writes with Pi's mutation queue.
+- **Safe local mutation** — patches are limited to 1 MiB, target files to 64 MiB, stay under Pi's current working directory, reject symlink escapes, use descriptor-anchored no-follow operations on Linux, fail closed elsewhere, preflight all hunks, and serialize writes with Pi's mutation queue.
 - **Model switching** — supported models replace Pi's `edit` and `write` tools with `apply_patch`; other active tools are preserved. Switching back restores only the file tools that were active before the switch.
 - **Sequential patch calls** — the extension marks patch execution sequential and disables provider-side parallel tool calls when the patch tool is active.
 
@@ -24,7 +24,7 @@ pi -e /path/to/pi-mono/packages/pi-codex-tools
 
 ## Scope decisions
 
-The current Codex source does not define separate `read_file` or `write_file` tools: file inspection is normally done through shell commands and file mutation through `apply_patch`. This package keeps Pi's bounded `read` and `bash` tools, and uses `apply_patch` in place of Pi's `edit` and `write` tools for supported models. Because Pi does not provide Codex's OS-level filesystem sandbox, `apply_patch` runs only on Linux/macOS and fails closed on unsupported platforms.
+The current Codex source does not define separate `read_file` or `write_file` tools: file inspection is normally done through shell commands and file mutation through `apply_patch`. This package keeps Pi's bounded `read` and `bash` tools, and uses `apply_patch` in place of Pi's `edit` and `write` tools for supported models. Because Pi does not provide Codex's OS-level filesystem sandbox, `apply_patch` runs only on Linux and fails closed on unsupported platforms. It also requires a Pi model runtime that advertises `compat.supportsOpenAIGrammarTools`; older runtimes leave the tool inactive.
 
 | Codex surface | Decision |
 | --- | --- |
@@ -48,6 +48,8 @@ These choices are based on the Codex tool specifications in `codex-rs/core/src/t
 
 These behaviors intentionally match Codex `apply_patch`.
 
+The provider contract is runtime-specific: use Pi 0.83.0 or newer for OpenAI grammar-tool support. For a manual smoke test, start Pi with this extension and a model that advertises `supportsOpenAIGrammarTools`, then verify that a file change appears as an `apply_patch` call and not as `edit`, `write`, or `bash`.
+
 ## Development
 
 ```bash
@@ -56,7 +58,7 @@ npm test -w packages/pi-codex-tools
 npm run -w packages/pi-codex-tools pack:dry-run
 ```
 
-Install/update telemetry can be disabled with `PI_OFFLINE=1` or `PI_TELEMETRY=0`.
+Install/update telemetry is disabled in CI and can be disabled with `PI_OFFLINE=1`, `PI_TELEMETRY=0` or `PI_TELEMETRY=false`, or Pi's `enableInstallTelemetry: false` setting. See [SECURITY.md](./SECURITY.md).
 
 ## License
 

package/SECURITY.md

@@ -19,8 +19,8 @@ Report privately through [GitHub Security Advisories](https://github.com/jvm/pi-
 
 Pi extensions execute with the same permissions as the local user running Pi. Review installed extensions and only install packages from sources you trust.
 
-`apply_patch` does not access the network or credentials. It validates paths beneath the current working directory, rejects symlink paths and symlinked parents, limits patch input to 1 MiB and target-file reads to 64 MiB, preflights file changes before writing, and uses root-anchored descriptor-based no-follow operations on Linux/macOS. It fails closed on unsupported platforms because Pi does not provide Codex's OS-level filesystem sandbox. A failure during a multi-file write can still leave earlier files changed; callers should use version control and review the resulting diff.
+`apply_patch` does not access the network or credential APIs. It can read credential-containing files when a patch targets them. It validates paths beneath the current working directory, rejects symlink paths and symlinked parents, limits patch input to 1 MiB and target-file reads to 64 MiB, preflights file changes before writing, and uses root-anchored descriptor-based no-follow operations on Linux. It fails closed on unsupported platforms because Pi does not provide Codex's OS-level filesystem sandbox. A failure during a multi-file write can still leave earlier files changed; callers should use version control and review the resulting diff.
 
 The package reads the current provider/model capability flags only to select tools. It does not log prompts, patches, file contents, credentials, auth headers, or provider responses.
 
-Install/update telemetry is best effort and can be disabled with `PI_OFFLINE=1`, `PI_TELEMETRY=0`, CI detection, or Pi's `enableInstallTelemetry: false` setting. It sends only package/version and runtime metadata through `@mocito/install-telemetry`.
+Install/update telemetry is best effort and can be disabled with `PI_OFFLINE=1`, `PI_TELEMETRY=0`, `PI_TELEMETRY=false`, CI detection, or Pi's `enableInstallTelemetry: false` setting. Through `@mocito/install-telemetry`, it sends the package name and version as HTTPS URL query parameters and adds `process.platform`, the runtime name/version, and `process.arch` to the `User-Agent`. These fields are not intended to identify a host, user, repository, or path; no prompts, patches, file contents, credentials, auth headers, or provider responses are sent.

package/extensions/index.ts

@@ -36,6 +36,9 @@ export default function piCodexTools(pi: ExtensionAPI): void {
     constrainedSampling: createOpenAILarkSampling(APPLY_PATCH_GRAMMAR),
     executionMode: "sequential",
     async execute(_toolCallId, rawParams, signal, _onUpdate, ctx) {
+      if (!supportsOpenAIGrammarTools(ctx.model)) {
+        throw new Error("apply_patch is only available for OpenAI models that advertise grammar-tool support.");
+      }
       const patch = (rawParams as { patch?: unknown }).patch;
       if (typeof patch !== "string") throw new Error("apply_patch requires raw patch text.");
       const result = await applyPatch(patch, { cwd: ctx.cwd, signal });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-codex-tools",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Codex-compatible apply_patch tooling for Pi's grammar-capable OpenAI models.",
   "type": "module",
   "license": "Apache-2.0",

package/src/apply-patch.ts

@@ -10,7 +10,7 @@ export const MAX_PATCH_HUNKS = 1_000;
 export const MAX_TARGET_FILE_BYTES = 64 * 1024 * 1024;
 
 const O_NOFOLLOW = constants.O_NOFOLLOW ?? 0;
-const SECURE_FD_DIRECTORY = process.platform === "linux" ? "/proc/self/fd" : process.platform === "darwin" ? "/dev/fd" : undefined;
+const SECURE_FD_DIRECTORY = process.platform === "linux" ? "/proc/self/fd" : undefined;
 const SECURE_FILESYSTEM_SUPPORTED = SECURE_FD_DIRECTORY !== undefined && O_NOFOLLOW !== 0;
 const SECURE_DIRECTORY_FLAGS = constants.O_RDONLY | O_NOFOLLOW | (constants.O_DIRECTORY ?? 0) | (constants.O_NONBLOCK ?? 0);
 const SECURE_READ_FLAGS = constants.O_RDONLY | O_NOFOLLOW | (constants.O_NONBLOCK ?? 0);
@@ -225,6 +225,7 @@ type PlannedOperation =
   | { kind: "update"; path: string; displayPath: string; moveTo?: string; moveDisplayPath?: string; chunkGroups: UpdateChunk[][]; content: string };
 
 type SafePath = { absolute: string; exists: boolean; isDirectory: boolean; isFile: boolean };
+type VirtualFile = Omit<SafePath, "absolute"> & { content?: string };
 
 export async function applyPatch(input: string, options: ApplyPatchOptions): Promise<ApplyPatchResult> {
   requireSecureFilesystem();
@@ -271,77 +272,108 @@ export async function applyPatch(input: string, options: ApplyPatchOptions): Pro
 
 async function planOperations(hunks: ApplyPatchHunk[], root: string, rootHandle: FileHandle, signal?: AbortSignal): Promise<PlannedOperation[]> {
   const operations: PlannedOperation[] = [];
-  const byPath = new Map<string, PlannedOperation>();
-  const occupied = new Set<string>();
+  const virtualFiles = new Map<string, VirtualFile>();
+
+  const getVirtualFile = async (rawPath: string): Promise<{ absolute: string; file: VirtualFile }> => {
+    const absolute = resolvePatchPath(rawPath, root);
+    const existing = virtualFiles.get(absolute);
+    if (existing) return { absolute, file: existing };
+    const safe = await safePath(rawPath, root, signal);
+    const file: VirtualFile = {
+      exists: safe.exists,
+      isDirectory: safe.isDirectory,
+      isFile: safe.isFile,
+    };
+    virtualFiles.set(absolute, file);
+    return { absolute, file };
+  };
+
+  const getVirtualContent = async (absolute: string, file: VirtualFile): Promise<string> => {
+    if (!file.exists || !file.isFile) throw new Error(`Cannot read non-file '${absolute}'.`);
+    if (file.content === undefined) file.content = await readSecureFile(rootHandle, root, absolute, signal);
+    return file.content;
+  };
 
   for (const hunk of hunks) {
     throwIfAborted(signal);
-    const source = await safePath(hunk.path, root, signal);
-    if (occupied.has(source.absolute) && !(hunk.kind === "update" && byPath.get(source.absolute)?.kind === "update")) {
-      throw new Error(`Patch addresses '${hunk.path}' more than once.`);
-    }
+    const source = await getVirtualFile(hunk.path);
 
     if (hunk.kind === "add") {
-      if (source.isDirectory || (source.exists && !source.isFile)) throw new Error(`Cannot add file over non-file '${hunk.path}'.`);
-      const operation: PlannedOperation = { kind: "add", path: source.absolute, displayPath: displayPath(root, source.absolute, hunk.path), content: hunk.content };
-      operations.push(operation);
-      byPath.set(source.absolute, operation);
-      occupied.add(source.absolute);
+      if (source.file.isDirectory || (source.file.exists && !source.file.isFile)) {
+        throw new Error(`Cannot add file over non-file '${hunk.path}'.`);
+      }
+      source.file.exists = true;
+      source.file.isDirectory = false;
+      source.file.isFile = true;
+      source.file.content = hunk.content;
+      operations.push({
+        kind: "add",
+        path: source.absolute,
+        displayPath: displayPath(root, source.absolute, hunk.path),
+        content: hunk.content,
+      });
       continue;
     }
 
     if (hunk.kind === "delete") {
-      if (!source.exists) throw new Error(`Cannot delete missing file '${hunk.path}'.`);
-      if (source.isDirectory || !source.isFile) throw new Error(`Cannot delete non-file '${hunk.path}'.`);
-      const operation: PlannedOperation = { kind: "delete", path: source.absolute, displayPath: displayPath(root, source.absolute, hunk.path) };
-      operations.push(operation);
-      byPath.set(source.absolute, operation);
-      occupied.add(source.absolute);
+      if (!source.file.exists) throw new Error(`Cannot delete missing file '${hunk.path}'.`);
+      if (source.file.isDirectory || !source.file.isFile) throw new Error(`Cannot delete non-file '${hunk.path}'.`);
+      operations.push({ kind: "delete", path: source.absolute, displayPath: displayPath(root, source.absolute, hunk.path) });
+      source.file.exists = false;
+      source.file.content = undefined;
       continue;
     }
 
-    if (!source.exists) throw new Error(`Cannot update missing file '${hunk.path}'.`);
-    if (source.isDirectory || !source.isFile) throw new Error(`Cannot update non-file '${hunk.path}'.`);
-    const original = await readSecureFile(rootHandle, root, source.absolute, signal);
-    const moveTo = hunk.moveTo ? (await safePath(hunk.moveTo, root, signal)).absolute : undefined;
+    if (!source.file.exists) throw new Error(`Cannot update missing file '${hunk.path}'.`);
+    if (source.file.isDirectory || !source.file.isFile) throw new Error(`Cannot update non-file '${hunk.path}'.`);
+    const original = await getVirtualContent(source.absolute, source.file);
+    const moveTo = hunk.moveTo ? resolvePatchPath(hunk.moveTo, root) : undefined;
     if (moveTo === source.absolute) throw new Error(`Cannot move '${hunk.path}' onto itself.`);
+
+    let destination: { absolute: string; file: VirtualFile } | undefined;
     if (moveTo) {
-      const destination = await safePath(hunk.moveTo!, root, signal);
-      if (destination.isDirectory || (destination.exists && !destination.isFile)) throw new Error(`Cannot move file over non-file '${hunk.moveTo}'.`);
-      if (occupied.has(moveTo)) throw new Error(`Patch addresses move destination '${hunk.moveTo}' more than once.`);
-      occupied.add(moveTo);
+      destination = await getVirtualFile(hunk.moveTo!);
+      if (destination.file.isDirectory || (destination.file.exists && !destination.file.isFile)) {
+        throw new Error(`Cannot move file over non-file '${hunk.moveTo}'.`);
+      }
     }
 
-    const existing = byPath.get(source.absolute);
-    if (existing?.kind === "update") {
-      if (existing.moveTo || moveTo) throw new Error(`A file can only be moved once in a patch: '${hunk.path}'.`);
-      existing.chunkGroups.push(hunk.chunks);
-      existing.content = existing.chunkGroups.reduce(
-        (content, chunks) => applyUpdateContent(content, chunks, hunk.path),
-        original,
-      );
+    const content = applyUpdateContent(original, hunk.chunks, hunk.path);
+    if (destination) {
+      operations.push({
+        kind: "update",
+        path: source.absolute,
+        displayPath: displayPath(root, source.absolute, hunk.path),
+        moveTo: moveTo!,
+        moveDisplayPath: displayPath(root, moveTo!, hunk.moveTo!),
+        chunkGroups: [[...hunk.chunks]],
+        content,
+      });
+      source.file.exists = false;
+      source.file.content = undefined;
+      destination.file.exists = true;
+      destination.file.isDirectory = false;
+      destination.file.isFile = true;
+      destination.file.content = content;
       continue;
     }
 
-    const operation: PlannedOperation = {
-      kind: "update",
-      path: source.absolute,
-      displayPath: displayPath(root, source.absolute, hunk.path),
-      moveTo,
-      moveDisplayPath: moveTo ? displayPath(root, moveTo, hunk.moveTo!) : undefined,
-      chunkGroups: [[...hunk.chunks]],
-      content: applyUpdateContent(original, hunk.chunks, hunk.path),
-    };
-    operations.push(operation);
-    byPath.set(source.absolute, operation);
-    occupied.add(source.absolute);
-  }
-
-  for (const operation of operations) {
-    if (operation.kind === "update" && operation.moveTo && byPath.has(operation.moveTo)) {
-      throw new Error(`Move destination '${operation.moveDisplayPath}' is also changed by this patch.`);
+    const previous = operations.at(-1);
+    if (previous?.kind === "update" && previous.path === source.absolute && !previous.moveTo) {
+      previous.content = content;
+      previous.chunkGroups.push([...hunk.chunks]);
+    } else {
+      operations.push({
+        kind: "update",
+        path: source.absolute,
+        displayPath: displayPath(root, source.absolute, hunk.path),
+        chunkGroups: [[...hunk.chunks]],
+        content,
+      });
     }
+    source.file.content = content;
   }
+
   return operations;
 }
 

package/src/install-telemetry.ts

@@ -44,14 +44,15 @@ function isPresentEnvFlag(value: string | undefined): boolean {
   return normalized !== "0" && normalized !== "false" && normalized !== "no";
 }
 
-function isInstallTelemetryEnabled(): boolean {
-  if (isTruthyEnvFlag(process.env.CI)) return false;
-  if (CI_ENVIRONMENT_VARIABLES.some((name) => isPresentEnvFlag(process.env[name]))) return false;
-  if (isTruthyEnvFlag(process.env.PI_OFFLINE)) return false;
-  if (process.env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(process.env.PI_TELEMETRY);
+export function isInstallTelemetryEnabled(env: NodeJS.ProcessEnv = process.env, settingsPath = join(getAgentDir(), "settings.json")): boolean {
+  if (isTruthyEnvFlag(env.CI)) return false;
+  if (CI_ENVIRONMENT_VARIABLES.some((name) => isPresentEnvFlag(env[name]))) return false;
+  if (isTruthyEnvFlag(env.PI_OFFLINE)) return false;
 
-  const settings = readJsonFile(join(getAgentDir(), "settings.json")) as SettingsDocument;
-  return settings.enableInstallTelemetry !== false;
+  const settings = readJsonFile(settingsPath) as SettingsDocument;
+  if (settings.enableInstallTelemetry === false) return false;
+  if (env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(env.PI_TELEMETRY);
+  return true;
 }
 
 function getPackageVersion(): string {