@howaboua/pi-codex-conversion 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Umberto B.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# pi-codex-conversion
+
+Codex-oriented adapter for [Pi](https://github.com/badlogic/pi-mono).
+
+This package replaces Pi's default Codex/GPT experience with a narrower Codex-like surface while staying close to Pi's own runtime and prompt construction:
+
+- swaps active tools to `exec_command`, `write_stdin`, `apply_patch`, and `view_image`
+- preserves Pi's composed system prompt and applies a narrow Codex-oriented delta on top
+- renders exec activity with Codex-style command and background-terminal labels
+
+![Available tools](./available-tools.png)
+
+## Active tools in adapter mode
+
+When the adapter is active, the LLM sees these tools:
+
+- `exec_command` — shell execution with Codex-style `cmd` parameters and resumable sessions
+- `write_stdin` — continue or poll a running exec session
+- `apply_patch` — patch tool
+- `view_image` — image-only wrapper around Pi's native image reading, enabled only for image-capable models
+
+Notably:
+
+- there is **no** dedicated `read`, `edit`, or `write` tool in adapter mode
+- local text-file inspection should happen through `exec_command`
+- file creation and edits should default to `apply_patch`
+- Pi may still expose additional runtime tools such as `parallel`; the prompt is written to tolerate that instead of assuming a fixed four-tool universe
+
+## Layout
+
+- `src/index.ts` — extension entrypoint, model gating, tool-set swapping, prompt transformation
+- `src/adapter/` — model detection and active-tool constants
+- `src/tools/` — Pi tool wrappers, exec session management, and execution rendering
+- `src/shell/` — shell tokenization, parsing, and exploration summaries
+- `src/patch/` — patch parsing, path policy, and execution
+- `src/prompt/` — Codex delta transformer over Pi's composed prompt
+- `tests/` — deterministic unit tests
+
+## Checks
+
+```bash
+npm run typecheck
+npm test
+npm run check
+```
+
+## Examples
+
+- `rg -n foo src` -> `Explored / Search foo in src`
+- `rg --files src | head -n 50` -> `Explored / List src`
+- `cat README.md` -> `Explored / Read README.md`
+- `exec_command({ cmd: "npm test", yield_time_ms: 1000 })` may return `session_id`, then continue with `write_stdin`
+- `write_stdin({ session_id, chars: "" })` renders like `Waited for background terminal`
+- `write_stdin({ session_id, chars: "y\\n" })` renders like `Interacted with background terminal`
+- `view_image({ path: "/absolute/path/to/screenshot.png" })` is available on image-capable models
+
+Raw command output is still available by expanding the tool result.
+
+## Install
+
+```bash
+pi install npm:@howaboua/pi-codex-conversion
+```
+
+Local development:
+
+```bash
+pi install ./pi-codex-conversion
+```
+
+Alternative Git install:
+
+```bash
+pi install git:github.com/IgorWarzocha/pi-codex-conversion
+```
+
+## Prompt behavior
+
+The adapter does not build a standalone replacement prompt anymore. Instead it:
+
+- keeps Pi's tool descriptions, Pi docs section, AGENTS/project context, skills inventory, and date/cwd when Pi already surfaced them
+- rewrites the top-level role framing to Codex-style wording
+- adds a small Codex delta to the existing `Guidelines` section
+
+That keeps the prompt much closer to `pi-mono` while still steering the model toward Codex-style tool use.
+
+## Notes
+
+- Adapter mode activates automatically for OpenAI `gpt*` and `codex*` models.
+- When you switch away from those models, Pi restores the previous active tool set.
+- `view_image` resolves paths against the active session cwd and only exposes `detail: "original"` for Codex-family image-capable models.
+- `apply_patch` paths stay restricted to the current working directory.
+- `exec_command` / `write_stdin` use a custom PTY-backed session manager via `node-pty` for interactive sessions.
+- PTY output handling applies basic terminal rewrite semantics (`\r`, `\b`, erase-in-line, and common escape cleanup) so interactive redraws replay sensibly.
+- Skills inventory is reintroduced in a Codex-style section when Pi's composed prompt already exposed the underlying Pi skills inventory.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@howaboua/pi-codex-conversion",
+  "version": "1.0.0",
+  "description": "Codex-oriented tool and prompt adapter for pi coding agent",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IgorWarzocha/pi-codex-conversion.git"
+  },
+  "homepage": "https://github.com/IgorWarzocha/pi-codex-conversion#readme",
+  "bugs": {
+    "url": "https://github.com/IgorWarzocha/pi-codex-conversion/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "extension",
+    "codex",
+    "adapter",
+    "apply-patch"
+  ],
+  "license": "MIT",
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "files": [
+    "src/**/*.ts",
+    "src/**/*.md",
+    "available-tools.png",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "tsx --test tests/**/*.test.ts",
+    "check": "npm run typecheck && npm run test",
+    "prepack": "npm run check",
+    "prepublishOnly": "npm run check"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "node-pty": "^1.1.0"
+  }
+}

package/src/adapter/codex-model.ts

@@ -0,0 +1,22 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+export interface CodexLikeModelDescriptor {
+	provider: string;
+	api: string;
+	id: string;
+}
+
+// Keep model detection intentionally conservative. The adapter replaces the
+// system prompt and tool surface, so false positives are worse than misses.
+export function isCodexLikeModel(model: Partial<CodexLikeModelDescriptor> | null | undefined): boolean {
+	if (!model) return false;
+
+	const provider = (model.provider ?? "").toLowerCase();
+	const api = (model.api ?? "").toLowerCase();
+	const id = (model.id ?? "").toLowerCase();
+	return provider.includes("codex") || api.includes("codex") || id.includes("codex") || (provider.includes("openai") && id.includes("gpt"));
+}
+
+export function isCodexLikeContext(ctx: ExtensionContext): boolean {
+	return isCodexLikeModel(ctx.model);
+}

package/src/adapter/tool-set.ts

@@ -0,0 +1,7 @@
+export const STATUS_KEY = "codex-adapter";
+export const STATUS_TEXT = "\u001b[38;2;0;76;255mCodex adapter\u001b[0m";
+
+export const DEFAULT_TOOL_NAMES = ["read", "bash", "edit", "write"];
+
+export const CORE_ADAPTER_TOOL_NAMES = ["exec_command", "write_stdin", "apply_patch"];
+export const VIEW_IMAGE_TOOL_NAME = "view_image";

package/src/index.ts

@@ -0,0 +1,112 @@
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { CORE_ADAPTER_TOOL_NAMES, DEFAULT_TOOL_NAMES, STATUS_KEY, STATUS_TEXT, VIEW_IMAGE_TOOL_NAME } from "./adapter/tool-set.ts";
+import { registerApplyPatchTool } from "./tools/apply-patch-tool.ts";
+import { isCodexLikeContext } from "./adapter/codex-model.ts";
+import { createExecCommandTracker } from "./tools/exec-command-state.ts";
+import { registerExecCommandTool } from "./tools/exec-command-tool.ts";
+import { createExecSessionManager } from "./tools/exec-session-manager.ts";
+import { buildCodexSystemPrompt, extractPiPromptSkills, type PromptSkill } from "./prompt/build-system-prompt.ts";
+import { registerViewImageTool, supportsOriginalImageDetail } from "./tools/view-image-tool.ts";
+import { registerWriteStdinTool } from "./tools/write-stdin-tool.ts";
+
+interface AdapterState {
+	enabled: boolean;
+	previousToolNames?: string[];
+	promptSkills: PromptSkill[];
+}
+
+function getCommandArg(args: unknown): string | undefined {
+	if (!args || typeof args !== "object" || !("cmd" in args) || typeof args.cmd !== "string") {
+		return undefined;
+	}
+	return args.cmd;
+}
+
+export default function codexConversion(pi: ExtensionAPI) {
+	const tracker = createExecCommandTracker();
+	const state: AdapterState = { enabled: false, promptSkills: [] };
+	const sessions = createExecSessionManager();
+
+	registerApplyPatchTool(pi);
+	registerExecCommandTool(pi, tracker, sessions);
+	registerWriteStdinTool(pi, sessions);
+
+	sessions.onSessionExit((_sessionId, command) => {
+		tracker.recordCommandFinished(command);
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		syncAdapter(pi, ctx, state);
+	});
+
+	pi.on("model_select", async (_event, ctx) => {
+		syncAdapter(pi, ctx, state);
+	});
+
+	pi.on("tool_execution_start", async (event) => {
+		if (event.toolName !== "exec_command") return;
+		const command = getCommandArg(event.args);
+		if (!command) return;
+		tracker.recordStart(event.toolCallId, command);
+	});
+
+	pi.on("tool_execution_end", async (event) => {
+		if (event.toolName !== "exec_command") return;
+		tracker.recordEnd(event.toolCallId);
+	});
+
+	pi.on("session_shutdown", async () => {
+		sessions.shutdown();
+	});
+
+	pi.on("before_agent_start", async (event, ctx) => {
+		if (!isCodexLikeContext(ctx)) {
+			return undefined;
+		}
+		return { systemPrompt: buildCodexSystemPrompt(event.systemPrompt, { skills: state.promptSkills }) };
+	});
+}
+
+function syncAdapter(pi: ExtensionAPI, ctx: ExtensionContext, state: AdapterState): void {
+	state.promptSkills = extractPiPromptSkills(ctx.getSystemPrompt());
+
+	registerViewImageTool(pi, { allowOriginalDetail: supportsOriginalImageDetail(ctx.model) });
+
+	if (isCodexLikeContext(ctx)) {
+		enableAdapter(pi, ctx, state);
+	} else {
+		disableAdapter(pi, ctx, state);
+	}
+}
+
+function enableAdapter(pi: ExtensionAPI, ctx: ExtensionContext, state: AdapterState): void {
+	const toolNames = getAdapterToolNames(ctx);
+	if (!state.enabled) {
+		// Preserve the previous active set once so switching away from Codex-like
+		// models restores the user's existing Pi tool configuration.
+		state.previousToolNames = pi.getActiveTools();
+		state.enabled = true;
+	}
+	pi.setActiveTools(toolNames);
+	setStatus(ctx, true);
+}
+
+function disableAdapter(pi: ExtensionAPI, ctx: ExtensionContext, state: AdapterState): void {
+	if (state.enabled) {
+		pi.setActiveTools(state.previousToolNames && state.previousToolNames.length > 0 ? state.previousToolNames : DEFAULT_TOOL_NAMES);
+		state.enabled = false;
+	}
+	setStatus(ctx, false);
+}
+
+function setStatus(ctx: ExtensionContext, enabled: boolean): void {
+	if (!ctx.hasUI) return;
+	ctx.ui.setStatus(STATUS_KEY, enabled ? STATUS_TEXT : undefined);
+}
+
+function getAdapterToolNames(ctx: ExtensionContext): string[] {
+	if (Array.isArray(ctx.model?.input) && ctx.model.input.includes("image")) {
+		return [...CORE_ADAPTER_TOOL_NAMES, VIEW_IMAGE_TOOL_NAME];
+	}
+	return [...CORE_ADAPTER_TOOL_NAMES];
+}

package/src/patch/core.ts

@@ -0,0 +1,220 @@
+import { mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parsePatchActions, parseUpdateFile } from "./parser.ts";
+import { openFileAtPath, pathExists, removeFileAtPath, resolvePatchPath, writeFileAtPath } from "./paths.ts";
+import { DiffError, type ExecutePatchResult, type ParsedPatchAction, type ParserState, type PatchAction } from "./types.ts";
+
+function splitFileLines(text: string): string[] {
+	const lines = text.split("\n");
+	if (lines.at(-1) === "") {
+		lines.pop();
+	}
+	return lines;
+}
+
+function getUpdatedFile({ text, action, path }: { text: string; action: PatchAction; path: string }): string {
+	if (action.type !== "update") {
+		throw new DiffError(`Invalid action type for update: ${action.type}`);
+	}
+
+	const origLines = splitFileLines(text);
+	const destLines: string[] = [];
+	let origIndex = 0;
+	let destIndex = 0;
+
+	for (const chunk of action.chunks) {
+		if (chunk.origIndex > origLines.length) {
+			throw new DiffError(`_get_updated_file: ${path}: chunk.orig_index ${chunk.origIndex} > len(lines) ${origLines.length}`);
+		}
+		if (origIndex > chunk.origIndex) {
+			throw new DiffError(`_get_updated_file: ${path}: orig_index ${origIndex} > chunk.orig_index ${chunk.origIndex}`);
+		}
+
+		destLines.push(...origLines.slice(origIndex, chunk.origIndex));
+		const delta = chunk.origIndex - origIndex;
+		origIndex += delta;
+		destIndex += delta;
+
+		for (const line of chunk.delLines) {
+			if (origLines[origIndex] !== line) {
+				throw new DiffError(`_get_updated_file: ${path}: Expected ${line} but got ${origLines[origIndex]} at line ${origIndex + 1}`);
+			}
+			origIndex += 1;
+		}
+
+		if (chunk.insLines.length > 0) {
+			destLines.push(...chunk.insLines);
+			destIndex += chunk.insLines.length;
+		}
+	}
+
+	destLines.push(...origLines.slice(origIndex));
+	const tailDelta = origLines.length - origIndex;
+	origIndex += tailDelta;
+	destIndex += tailDelta;
+
+	if (origIndex !== origLines.length) {
+		throw new DiffError(`Unexpected final orig_index for ${path}`);
+	}
+	if (destIndex !== destLines.length) {
+		throw new DiffError(`Unexpected final dest_index for ${path}`);
+	}
+
+	if (destLines.length === 0) {
+		return "";
+	}
+
+	return `${destLines.join("\n")}\n`;
+}
+
+function resolveUpdateAction({ path, text, lines }: { path: string; text: string; lines: string[] }): { action: PatchAction; fuzz: number } {
+	const state: ParserState = {
+		lines,
+		index: 0,
+		fuzz: 0,
+	};
+	const action = parseUpdateFile({ state, text, path });
+	if (action.chunks.length === 0) {
+		throw new DiffError(`Invalid patch hunk on line 2: Update file hunk for path '${path}' is empty`);
+	}
+	return { action, fuzz: state.fuzz };
+}
+
+function applyMove({
+	cwd,
+	path,
+	movePath,
+	content,
+	changedFiles,
+	createdFiles,
+	deletedFiles,
+	movedFiles,
+}: {
+	cwd: string;
+	path: string;
+	movePath: string;
+	content: string;
+	changedFiles: Set<string>;
+	createdFiles: Set<string>;
+	deletedFiles: Set<string>;
+	movedFiles: Set<string>;
+}): void {
+	const fromAbsolutePath = resolvePatchPath({ cwd, patchPath: path });
+	const toAbsolutePath = resolvePatchPath({ cwd, patchPath: movePath });
+	const destinationExisted = pathExists({ cwd, path: movePath });
+
+	mkdirSync(dirname(toAbsolutePath), { recursive: true });
+	writeFileSync(toAbsolutePath, content, "utf8");
+	if (fromAbsolutePath !== toAbsolutePath) {
+		unlinkSync(fromAbsolutePath);
+	}
+
+	changedFiles.add(path);
+	changedFiles.add(movePath);
+	movedFiles.add(`${path} -> ${movePath}`);
+	if (!destinationExisted) {
+		createdFiles.add(movePath);
+	}
+	if (fromAbsolutePath !== toAbsolutePath) {
+		deletedFiles.add(path);
+	}
+}
+
+function applyAction({
+	cwd,
+	action,
+	changedFiles,
+	createdFiles,
+	deletedFiles,
+	movedFiles,
+}: {
+	cwd: string;
+	action: ParsedPatchAction;
+	changedFiles: Set<string>;
+	createdFiles: Set<string>;
+	deletedFiles: Set<string>;
+	movedFiles: Set<string>;
+}): number {
+	if (action.type === "delete") {
+		removeFileAtPath({ cwd, path: action.path });
+		changedFiles.add(action.path);
+		deletedFiles.add(action.path);
+		return 0;
+	}
+
+	if (action.type === "add") {
+		const { created } = writeFileAtPath({
+			cwd,
+			path: action.path,
+			content: action.newFile ?? "",
+		});
+		changedFiles.add(action.path);
+		if (created) {
+			createdFiles.add(action.path);
+		}
+		return 0;
+	}
+
+	if (!action.lines) {
+		throw new DiffError(`Update File Error: Missing patch lines for ${action.path}`);
+	}
+
+	const originalText = openFileAtPath({ cwd, path: action.path });
+	const { action: resolvedAction, fuzz } = resolveUpdateAction({
+		path: action.path,
+		text: originalText,
+		lines: action.lines,
+	});
+	resolvedAction.movePath = action.movePath;
+	const newContent = getUpdatedFile({ text: originalText, action: resolvedAction, path: action.path });
+
+	if (action.movePath) {
+		applyMove({
+			cwd,
+			path: action.path,
+			movePath: action.movePath,
+			content: newContent,
+			changedFiles,
+			createdFiles,
+			deletedFiles,
+			movedFiles,
+		});
+		return fuzz;
+	}
+
+	writeFileAtPath({ cwd, path: action.path, content: newContent });
+	changedFiles.add(action.path);
+	return fuzz;
+}
+
+export function executePatch({ cwd, patchText }: { cwd: string; patchText: string }): ExecutePatchResult {
+	if (!patchText.startsWith("*** Begin Patch")) {
+		throw new DiffError("Patch must start with '*** Begin Patch'");
+	}
+
+	const actions = parsePatchActions({ text: patchText });
+	const changedFiles = new Set<string>();
+	const createdFiles = new Set<string>();
+	const deletedFiles = new Set<string>();
+	const movedFiles = new Set<string>();
+	let fuzz = 0;
+
+	for (const action of actions) {
+		fuzz += applyAction({
+			cwd,
+			action,
+			changedFiles,
+			createdFiles,
+			deletedFiles,
+			movedFiles,
+		});
+	}
+
+	return {
+		changedFiles: [...changedFiles],
+		createdFiles: [...createdFiles],
+		deletedFiles: [...deletedFiles],
+		movedFiles: [...movedFiles],
+		fuzz,
+	};
+}