@howaboua/pi-codex-conversion 1.0.31-dev.4.26e07fb → 1.0.31-dev.5.36974a1

package/README.md

@@ -1,20 +1,31 @@
 # pi-codex-conversion
 
-Codex-oriented adapter for [Pi](https://github.com/badlogic/pi-mono).
+Codex-style tools 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:
+> [!NOTE]
+> Use the npm package for normal installs. Avoid `pi install git:...` unless you know you want the development checkout; see [Development checkout](#development-checkout).
 
-- swaps active tools to `exec_command`, `write_stdin`, `apply_patch`, `view_image`, plus native OpenAI Codex Responses `web_search` and `image_generation` on `openai-codex`
-- saves native Codex image-generation outputs into `.pi/openai-codex-images/` at the workspace/repo root and mirrors the newest image to `.pi/openai-codex-images/latest.png`
-- 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
-- renders `apply_patch` calls with Codex-style `Added` / `Edited` / `Deleted` diff blocks and Pi-style colored diff lines
-- targets modern Pi tool/rendering APIs and is aligned with Pi `0.74.x` / the `@earendil-works/*` package scope
+GPT/Codex models are strongest when the tool surface looks like the Codex CLI they were trained around: shell commands, resumable terminal sessions, and patch-based edits. This extension brings that workflow to Pi while keeping Pi's runtime, sessions, project context, skills, and UI.
 
-![Available tools](./available-tools.png)
+The point is to give the model tools it already knows how to use well: shell-first inspection, resumable command sessions, and large one-shot patch edits instead of piecemeal read/edit/write steps.
 
-> [!NOTE]
-> Native OpenAI Codex Responses web search activity is surfaced as merged foldable status messages. Pi still does not expose native web-search usage as true tool-call rows.
+## Install
+
+```bash
+pi install npm:@howaboua/pi-codex-conversion
+```
+
+## Development checkout
+
+The Git checkout is mostly for development and mirrors the maintainer workflow. If you run it directly, you may need to build the bundled `apply_patch` binary for your platform.
+
+Run the current checkout without installing globally:
+
+```bash
+pi --no-extensions --no-skills -e /path/to/pi-codex-conversion
+```
+
+![Available tools](./available-tools.png)
 
 ## Active tools in adapter mode
 
@@ -34,123 +45,32 @@ Notably:
 - 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
+## What changes in Pi
 
-- `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
+- Adapter mode activates automatically for OpenAI `gpt*` and `codex*` models, then restores the previous tool set when you switch away.
+- Pi's composed prompt is preserved; the extension only adds a small Codex-style tool-use nudge.
+- Shell activity is rendered with Codex-like labels such as `Ran`, `Explored`, `Read`, and background-terminal status.
+- `apply_patch` renders as Codex-style `Added` / `Edited` / `Deleted` blocks, including inline partial-failure state.
+- Native web search appears as a compact expandable summary after a turn, with queries and sources in the expanded view.
+- Generated images are saved under `.pi/openai-codex-images/` at the workspace/repo root, with the latest image mirrored to `latest.png`.
 
-## Checks
-
-```bash
-npm run typecheck
-npm test
-npm run check
-```
-
-## Examples
+## Command rendering 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`
-- for short or non-interactive commands, omitting `yield_time_ms` is preferred; tiny non-interactive waits are clamped upward to avoid unnecessary follow-up calls
-- `write_stdin({ session_id, chars: "" })` renders like `Waited for background terminal` and is meant for occasional polling, not tight repoll loops
-- `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
-- `web_search` is surfaced only on `openai-codex`, and the adapter rewrites it into the native OpenAI Responses `type: "web_search"` payload instead of executing a local function tool
-- `image_generation` is surfaced only on image-capable `openai-codex` models, and the adapter rewrites it into the native OpenAI Responses `type: "image_generation", output_format: "png"` payload instead of executing a local function tool
-- native `image_generation` outputs are saved under `.pi/openai-codex-images/` at the workspace/repo root, with the newest image mirrored to `.pi/openai-codex-images/latest.png`
-- when native web search is available, the adapter shows a one-time session notice and merged foldable search-activity messages instead of native tool-call rows
-- `apply_patch` partial failures stay inline in the patch row so successful and failed file entries can be seen together
+- `npm test` -> `Ran npm test`
+- `write_stdin({ session_id, chars: "" })` -> `Waited for background terminal`
+- `write_stdin({ session_id, chars: "y\n" })` -> `Interacted with background terminal`
 
 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
-```
-
-## Publishing
-
-This package is already configured for public npm publishes via:
-
-- `publishConfig.access = "public"`
-- `prepublishOnly` / `prepack` checks
-
-Useful commands:
-
-```bash
-npm run publish:dry-run
-npm run publish:dev
-npm run release:dev
-```
-
-What they do:
-
-- `npm run publish:dry-run` — inspect what would be published
-- `npm run publish:dev` — publish the current version under the `dev` dist-tag
-- `npm run release:dev` — bump the package to the next `-dev.N` prerelease and publish it under the `dev` dist-tag
-
-Typical flow:
-
-```bash
-npm login
-npm run publish:dry-run
-npm run release:dev
-```
-
-For modern npm auth, just run `npm login` and complete the browser flow when prompted.
-
-After publishing, install the dev build with:
-
-```bash
-pi install npm:@howaboua/pi-codex-conversion@dev
-```
-
-## 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
-- adds the current shell to the transformed prompt so quoting and escaping can match the runtime environment
-- 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
+## Details worth knowing
 
-- 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.
-- `web_search` is exposed only for the `openai-codex` provider and is forwarded as the native OpenAI Codex Responses web search tool.
-- `image_generation` is exposed only for image-capable `openai-codex` models and is forwarded as the native OpenAI Codex Responses image-generation tool.
-- generated images are written under `.pi/openai-codex-images/` at the workspace/repo root, and the latest image is mirrored to `.pi/openai-codex-images/latest.png`.
-- `apply_patch` paths stay restricted to the current working directory.
-- partial `apply_patch` failures stay in the original patch block and highlight the failed entry instead of adding a second warning row.
-- `exec_command` / `write_stdin` use a custom PTY-backed session manager via `node-pty` for interactive sessions.
-- tiny `exec_command` waits are clamped for non-interactive commands so short runs do not burn an avoidable follow-up tool call.
-- empty `write_stdin` polls are clamped to a meaningful minimum wait so long-running processes are not repolled too aggressively.
-- 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.
+- `exec_command` and `write_stdin` use a PTY-backed session manager for interactive commands and long-running processes.
+- `apply_patch` accepts absolute paths as-is and resolves relative paths against the current working directory.
+- Shell `apply_patch` is also available inside `exec_command`, but the dedicated `apply_patch` tool is preferred unless you are chaining edits with other shell steps.
+- Native `web_search` and `image_generation` are forwarded to OpenAI Codex Responses tools rather than executed as local function tools.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howaboua/pi-codex-conversion",
-  "version": "1.0.31-dev.4.26e07fb",
+  "version": "1.0.31-dev.5.36974a1",
   "description": "Codex-oriented tool and prompt adapter for pi coding agent",
   "type": "module",
   "repository": {
@@ -44,7 +44,7 @@
     "publish:dev": "npm publish --tag dev",
     "release:dev": "npm version prerelease --preid dev && npm publish --tag dev",
     "prepack": "npm run check",
-    "prepublishOnly": "npm run verify:apply-patch-binaries && npm run check",
+    "prepublishOnly": "npm run verify:apply-patch-binaries",
     "build:apply-patch": "node scripts/build-apply-patch-binary.mjs",
     "sync:apply-patch-source": "node scripts/sync-apply-patch-source.mjs",
     "verify:apply-patch-binaries": "node scripts/verify-apply-patch-binaries.mjs"

package/src/index.ts

@@ -165,8 +165,9 @@ function enableAdapter(pi: ExtensionAPI, ctx: ExtensionContext, state: AdapterSt
 	const toolNames = mergeAdapterTools(pi.getActiveTools(), 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();
+		// models restores the user's existing Pi tool configuration. Strip adapter
+		// tools in case a fresh session starts from persisted/mixed active tools.
+		state.previousToolNames = stripAdapterTools(pi.getActiveTools());
 		state.enabled = true;
 	}
 	pi.setActiveTools(toolNames);
@@ -210,7 +211,7 @@ export function mergeAdapterTools(activeTools: string[], adapterTools: string[])
 }
 
 export function restoreTools(previousTools: string[], activeTools: string[]): string[] {
-	const restored = [...previousTools];
+	const restored = stripAdapterTools(previousTools);
 	for (const toolName of activeTools) {
 		if (!ADAPTER_TOOL_NAMES.includes(toolName) && !restored.includes(toolName)) {
 			restored.push(toolName);
@@ -219,6 +220,10 @@ export function restoreTools(previousTools: string[], activeTools: string[]): st
 	return restored;
 }
 
+export function stripAdapterTools(toolNames: string[]): string[] {
+	return toolNames.filter((toolName) => !ADAPTER_TOOL_NAMES.includes(toolName));
+}
+
 function hasAdapterTools(activeTools: string[]): boolean {
 	return activeTools.some((toolName) => ADAPTER_TOOL_NAMES.includes(toolName));
 }

package/src/patch/paths.ts

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { dirname, isAbsolute, resolve } from "node:path";
 import { DiffError } from "./types.ts";
 
 export function normalizePatchPath({ path }: { path: string }): string {
@@ -8,20 +8,15 @@ export function normalizePatchPath({ path }: { path: string }): string {
 	return withoutAt.replace(/^['"]|['"]$/g, "");
 }
 
-// Relative patch paths stay anchored to ctx.cwd. Absolute patch paths are
-// accepted as-is so the adapter can match Codex-style path usage.
+// Match Codex apply_patch path handling: absolute patch paths are accepted
+// as-is, while relative paths are resolved against ctx.cwd.
 export function resolvePatchPath({ cwd, patchPath }: { cwd: string; patchPath: string }): string {
 	const normalized = normalizePatchPath({ path: patchPath });
 	if (!normalized) {
 		throw new DiffError("Patch path cannot be empty");
 	}
 
-	const absolutePath = isAbsolute(normalized) ? normalized : resolve(cwd, normalized);
-	const rel = relative(cwd, absolutePath);
-	if (!isAbsolute(normalized) && (rel.startsWith("..") || isAbsolute(rel))) {
-		throw new DiffError(`Path escapes working directory: ${normalized}`);
-	}
-	return absolutePath;
+	return isAbsolute(normalized) ? normalized : resolve(cwd, normalized);
 }
 
 export function openFileAtPath({ cwd, path }: { cwd: string; path: string }): string {

package/src/prompt/build-system-prompt.ts

@@ -5,15 +5,11 @@ export interface PromptSkill {
 }
 
 const CODEX_GUIDELINES = [
-	"Prefer a single `apply_patch` call that updates all related files together when one coherent patch will do.",
-	"When making coordinated edits across multiple files, include them in one `apply_patch` call instead of splitting them into separate patches.",
-	"When multiple tool calls are independent, emit them together so they can execute in parallel instead of serializing them.",
-	"Use `parallel` only when tool calls are independent and can safely run at the same time.",
-	"Use `write_stdin` when an exec session returns `session_id`, and continue until `exit_code` is present.",
-	"For short or non-interactive commands, prefer the default `exec_command` wait instead of a tiny `yield_time_ms` that forces an extra follow-up call.",
-	"When polling a running exec session with empty `chars`, wait meaningfully between polls and do not repeatedly poll by reflex.",
-	"Do not request `tty` unless interactive terminal behavior is required.",
-	"Native `image_generation` outputs are saved under `.pi/openai-codex-images/` and mirrored to `.pi/openai-codex-images/latest.png`. Use `view_image` only when pixel-level inspection is necessary.",
+	"Use `exec_command` for shell commands, file inspection, builds, and tests; prefer `rg` / `rg --files` for discovery and focused commands over truncation.",
+	"Use `apply_patch` for text-file changes, including creates/deletes/moves; group related multi-file edits into one patch.",
+	"Prefer the `apply_patch` tool; use shell `apply_patch` only when chaining edits with other shell steps.",
+	"Use `write_stdin` only for running `exec_command` sessions; poll sparingly.",
+	"Run independent tool calls in parallel when practical.",
 ];
 
 function insertBeforeTrailingContext(prompt: string, section: string): string {
@@ -88,9 +84,9 @@ function injectSkills(prompt: string, skills: PromptSkill[]): string {
 }
 
 function injectGuidelines(prompt: string): string {
-	const match = prompt.match(/(^Guidelines:\n)([\s\S]*?)(\n\n(?:Pi documentation:|# Project Context|# Skills|Current date:))/m);
+	const match = prompt.match(/(^Guidelines:\n)([\s\S]*?)(\n\n(?=Pi documentation\b|# Project Context|# Skills|Current date:))/m);
 	if (!match || match.index === undefined) {
-		const fallbackSection = `Codex mode guidelines:\n${CODEX_GUIDELINES.map((line) => `- ${line}`).join("\n")}`;
+		const fallbackSection = `Guidelines:\n${CODEX_GUIDELINES.map((line) => `- ${line}`).join("\n")}`;
 		return insertBeforeTrailingContext(prompt, fallbackSection);
 	}
 

package/src/tools/apply-patch-tool.ts

@@ -280,12 +280,8 @@ export function registerApplyPatchTool(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "apply_patch",
 		label: "apply_patch",
-		description: "Use `apply_patch` to edit files. Send the full patch in `input`.",
+		description: "Apply a patch to create, edit, delete, or move files.",
 		promptSnippet: "Edit files with a patch.",
-		promptGuidelines: [
-			"Prefer apply_patch for focused textual edits instead of rewriting whole files.",
-			"When one task needs coordinated edits across multiple files, send them in a single apply_patch call when one coherent patch will do.",
-		],
 		parameters: APPLY_PATCH_PARAMETERS,
 		prepareArguments: prepareApplyPatchArguments,
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {

package/src/tools/exec-command-tool.ts

@@ -8,16 +8,16 @@ import { formatUnifiedExecResult } from "./unified-exec-format.ts";
 
 const EXEC_COMMAND_PARAMETERS = Type.Object({
 	cmd: Type.String({ description: "Shell command to execute." }),
-	workdir: Type.Optional(Type.String({ description: "Optional working directory; defaults to the current turn cwd." })),
-	shell: Type.Optional(Type.String({ description: "Optional shell binary; defaults to the user's shell." })),
+	workdir: Type.Optional(Type.String({ description: "Defaults to current cwd." })),
+	shell: Type.Optional(Type.String({ description: "Defaults to the user's shell." })),
 	tty: Type.Optional(
 		Type.Boolean({
-			description: "Whether to allocate a TTY for the command. Defaults to false (plain pipes); set to true to open a PTY and access TTY process.",
+			description: "Allocate a TTY. Defaults to false.",
 		}),
 	),
-	yield_time_ms: Type.Optional(Type.Number({ description: "How long to wait in milliseconds for output before yielding." })),
-	max_output_tokens: Type.Optional(Type.Number({ description: "Maximum number of tokens to return. Excess output will be truncated." })),
-	login: Type.Optional(Type.Boolean({ description: "Whether to run the shell with -l/-i semantics. Defaults to true." })),
+	yield_time_ms: Type.Optional(Type.Number({ description: "Wait for output before yielding." })),
+	max_output_tokens: Type.Optional(Type.Number({ description: "Excess output will be truncated." })),
+	login: Type.Optional(Type.Boolean({ description: "Whether to run through a login-style shell so user PATH/toolchain setup is loaded. Defaults to true." })),
 });
 
 interface ExecCommandParams {
@@ -136,14 +136,8 @@ export function registerExecCommandTool(pi: ExtensionAPI, tracker: ExecCommandTr
 	pi.registerTool({
 		name: "exec_command",
 		label: "exec_command",
-		description: "Runs a command in a PTY, returning output or a session ID for ongoing interaction.",
+		description: "Runs a shell command, returning output or a session ID for ongoing interaction.",
 		promptSnippet: "Run a command.",
-		promptGuidelines: [
-			"Use exec_command for search, listing files, and local text-file reads.",
-			"Prefer rg or rg --files when possible.",
-			"For short or non-interactive commands, omit `yield_time_ms` so the default wait can avoid unnecessary follow-up calls.",
-			"Keep tty disabled unless the command truly needs interactive terminal behavior.",
-		],
 		parameters: EXEC_COMMAND_PARAMETERS,
 		prepareArguments: prepareExecCommandArguments,
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {

package/src/tools/image-generation-tool.ts

@@ -79,7 +79,7 @@ export function rewriteNativeImageGenerationTool(payload: unknown, model: Extens
 
 export function createImageGenerationTool(): ToolDefinition<typeof IMAGE_GENERATION_PARAMETERS> {
 	const description =
-		"Generate an image. Native openai-codex image_generation outputs are saved under `.pi/openai-codex-images/` and mirrored to `.pi/openai-codex-images/latest.png`. Use `view_image` only when pixel-level inspection is necessary.";
+		"Generate an image. Outputs are saved under `.pi/openai-codex-images/` and mirrored to `.pi/openai-codex-images/latest.png`.";
 	return {
 		name: "image_generation",
 		label: "image_generation",

package/src/tools/view-image-tool.ts

@@ -12,7 +12,7 @@ import { Text } from "@earendil-works/pi-tui";
 
 const VIEW_IMAGE_UNSUPPORTED_MESSAGE = "view_image is not allowed because you do not support image inputs";
 const DETAIL_DESCRIPTION =
-	"Optional detail override. The only supported value is `original`; omit this field for default resized behavior. Use `original` to preserve the file's original resolution instead of resizing to fit. This is important when high-fidelity image perception or precise localization is needed, especially for CUA agents.";
+	"Use `original` to preserve the file's original resolution; omit for default resized behavior.";
 
 interface ViewImageParams {
 	path: string;
@@ -37,7 +37,7 @@ type ViewImageParameters = ReturnType<typeof createViewImageParameters>;
 
 function createViewImageParameters(allowOriginalDetail: boolean) {
 	const properties: Record<string, TSchema> = {
-		path: Type.String({ description: "Local filesystem path to an image file" }),
+		path: Type.String({ description: "Local image file path." }),
 	};
 	if (allowOriginalDetail) {
 		properties.detail = Type.Optional(Type.String({ description: DETAIL_DESCRIPTION }));
@@ -143,10 +143,8 @@ export function createViewImageTool(options: CreateViewImageToolOptions = {}): T
 	return {
 		name: "view_image",
 		label: "view_image",
-		description:
-			"View a local image from the filesystem (only use if given a full filepath by the user, and the image isn't already attached to the thread context within <image ...> tags).",
+		description: "View a local image file.",
 		promptSnippet: "View a local image from the filesystem.",
-		promptGuidelines: ["Use view_image only for image files. Use exec_command for text-file inspection."],
 		parameters,
 		prepareArguments: prepareViewImageArguments,
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {

package/src/tools/write-stdin-tool.ts

@@ -6,10 +6,10 @@ import type { ExecSessionManager, UnifiedExecResult } from "./exec-session-manag
 import { formatUnifiedExecResult } from "./unified-exec-format.ts";
 
 const WRITE_STDIN_PARAMETERS = Type.Object({
-	session_id: Type.Number({ description: "Identifier of the running unified exec session." }),
-	chars: Type.Optional(Type.String({ description: "Bytes to write to stdin. May be empty to poll." })),
-	yield_time_ms: Type.Optional(Type.Number({ description: "How long to wait (in milliseconds) for output before yielding." })),
-	max_output_tokens: Type.Optional(Type.Number({ description: "Maximum number of tokens to return. Excess output will be truncated." })),
+	session_id: Type.Number({ description: "Running exec session ID." }),
+	chars: Type.Optional(Type.String({ description: "Bytes to write. Empty polls." })),
+	yield_time_ms: Type.Optional(Type.Number({ description: "Wait for output before yielding." })),
+	max_output_tokens: Type.Optional(Type.Number({ description: "Excess output will be truncated." })),
 });
 
 interface WriteStdinParams {
@@ -108,12 +108,8 @@ export function registerWriteStdinTool(pi: ExtensionAPI, sessions: ExecSessionMa
 	pi.registerTool({
 		name: "write_stdin",
 		label: "write_stdin",
-		description: "Writes characters to an existing unified exec session and returns recent output.",
+		description: "Writes to or polls a running exec session.",
 		promptSnippet: "Write to an exec session.",
-		promptGuidelines: [
-			"Use empty `chars` only to poll a running exec session.",
-			"When polling with empty `chars`, wait meaningfully between polls and do not repeatedly poll by reflex.",
-		],
 		parameters: WRITE_STDIN_PARAMETERS,
 		async execute(_toolCallId, params) {
 			const typed = parseWriteStdinParams(params);