@zeroclover/pi-rtk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# pi-rtk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Routes the shell commands Pi runs through [RTK](https://github.com/rtk-ai/rtk), so that `git status`, `cargo test`, `rg`, `ls` and the other commands RTK knows return compact, token-efficient output. Before each command runs, pi-rtk asks `rtk rewrite` for RTK's equivalent and substitutes it (`git status` → `rtk git status`). RTK's rule set decides what is rewritten; pi-rtk decides where and when it is safe.
+
+pi-rtk replaces the single-file hook that `rtk init --agent pi` installs. It covers Pi's `bash` tool and the `exec_command` tool of [pi-unified-exec](https://www.npmjs.com/package/pi-unified-exec) and compatible exec plugins, including calls made from codemode scripts. Other exec tools can be added in a configuration file. pi-rtk also:
+
+- blocks commands that RTK denies with a reason, and never runs a deny message as a command;
+- never rewrites PTY sessions or commands for a non-POSIX shell;
+- leaves the command unchanged whenever rtk is missing, slow, or failing;
+- stops calling a broken rtk for the rest of the session.
+
+## Install
+
+Releases are published to npm as `@zeroclover/pi-rtk`, versioned independently of the other packages in this repository. Each release is tagged `@zeroclover/pi-rtk@<version>`, and its notes are the matching section of the package's `CHANGELOG.md`.
+
+```bash
+pi install npm:@zeroclover/pi-rtk             # install a published version for the user
+pi -e ./packages/pi-rtk                       # try a repository checkout for one session
+pi install /absolute/path/to/packages/pi-rtk  # install a repository checkout for the user
+```
+
+Requires `rtk` 0.25.0 or newer on `PATH`. Without it, pi-rtk warns once and commands run unchanged.
+
+**Coming from `rtk init --agent pi`:** remove `~/.pi/agent/extensions/rtk.ts`, or run `rtk init -g --agent pi --uninstall`. Keeping both does no harm, because pi-rtk skips commands that already start with `rtk`, but the old hook only sees `bash`. The model-facing RTK instructions (`RTK.md`) from `rtk init` are separate, and pi-rtk does not change them.
+
+## Provides
+
+| Kind | Name | Description |
+|---|---|---|
+| event | `tool_call` | Rewrites the command of every tool that has an adapter, whether the model or a codemode script calls it. |
+| command | `/rtk` | Shows the state, the rtk version, every adapter (marked `[not registered]` when no such tool is loaded), the session counts of rewritten, unchanged, skipped, blocked, and failed calls, and the last failure. |
+| command | `/rtk off` / `/rtk on` | Stops or resumes rewriting for this session. `on` also ends a suspension and checks rtk again. Every new session starts on. |
+| status | `rtk` | `RTK off` (`/rtk off` or `RTK_DISABLED=1`), else `RTK unavailable`, else `RTK suspended` while commands are not being rewritten; empty otherwise. |
+
+Any other argument to `/rtk` prints the usage.
+
+## How a command is handled
+
+1. The tool has no adapter, rewriting is off (`/rtk off`, `RTK_DISABLED=1`), or rewriting is suspended: the command runs unchanged.
+2. Skip rules leave the command unchanged without running rtk. They apply when:
+   - the command is blank or already starts with `rtk`;
+   - the call asks for a PTY (`tty: true`), because RTK filters output, which breaks interactive programs;
+   - the `shell` is not bash, sh, zsh, dash, or ksh (for example `pwsh`, `cmd`, `fish`, `nu`), is `false`, or is another non-string value (`true` means the tool's default shell, like an omitted one);
+   - on Windows, the tool has a shell field but the call names no shell, because the tool's default there can be PowerShell (pi-unified-exec without Git Bash);
+   - the working directory does not exist.
+3. `rtk rewrite <command>` runs without a shell, in the call's working directory, with a 2 s timeout. The command is passed as a single argument after `--`, so one that starts with `-` is never taken for an rtk option.
+
+| rtk result | Effect |
+|---|---|
+| exit 0 or 3 with a different command | The tool runs the rewrite. Exit 3 only defers permission to the host, and Pi has no permission rules to apply. |
+| exit 0 or 3 with empty or identical output, or exit 1 | The command runs unchanged (no RTK equivalent). |
+| exit 2 with a message | The call is blocked with `rtk: <message>`. |
+| exit 2 without a message | The command runs unchanged. RTK defers to the host's own deny rules. |
+| timeout, crash, signal, start failure, other exit code | The command runs unchanged and the call counts as a failure. |
+
+A cancelled call (Escape) stops rtk and is not counted as a failure.
+
+## When rtk is missing or failing
+
+- At session start pi-rtk runs `rtk --version` (unless `RTK_DISABLED=1`). If rtk is missing, too old, or fails, it warns once, shows `RTK unavailable`, and runs commands unchanged at no cost. The next call with an adapter, 30 s or more after the last check, checks again, so installing rtk during a session is picked up without `/rtk on`.
+- Three consecutive failures suspend rewriting for the session. pi-rtk warns once with the last failure and shows `RTK suspended`. This keeps a hung rtk from adding 2 s to every command. Any normal answer from rtk resets the count. `/rtk on` or a new session ends the suspension.
+- An internal error in pi-rtk never blocks a command. The command runs unchanged and a warning is shown.
+
+## Configuration
+
+`<agent-dir>/pi-rtk.json` (by default `~/.pi/agent/pi-rtk.json`) is read at session start, and changes apply after `/reload` or in a new session. Without the file, pi-rtk uses its built-in adapters:
+
+| Tool | Command field | Shell field | PTY field | Working-directory field |
+|---|---|---|---|---|
+| `bash` (Pi, and plugins that replace it under the same name) | `command` | – | – | – |
+| `exec_command` (pi-unified-exec, @chensl/pi-unified-exec, pi-exec-command, @howaboua/pi-codex-conversion) | `cmd` | `shell` | `tty` | `workdir` |
+
+The `tools` object adds an adapter for another tool, replaces a built-in one, or removes one with `false`:
+
+```json
+{
+	"tools": {
+		"bg_run": { "commandField": "command" },
+		"bash_bg": { "commandField": "command" },
+		"bash": false
+	}
+}
+```
+
+| Adapter key | Required | Meaning |
+|---|---|---|
+| `commandField` | yes | Input field that holds the shell command. A call without a string in this field is left alone. |
+| `shellField` | no | Input field that names the shell. Only bash, sh, zsh, dash, and ksh are rewritten; `false` (no shell), and on Windows a call that names no shell, are never rewritten. |
+| `ttyField` | no | Boolean input field; `true` (a PTY session) is never rewritten. |
+| `cwdField` | no | Input field with the working directory, resolved against the session directory. |
+
+`bg_run` is the tool of pi-background-tasks and `bash_bg` the tool of pi-bg-shell; both run `command` through a POSIX shell without a PTY. Use `"bash": false` when your `bash` tool is not a POSIX shell (for example @code-fixer-23/pi-bash-tooljack-nu, which runs Nushell). Do not add tools that send keystrokes to a running process (`write_stdin`, `terminal_send`), tools whose every call runs in a PTY (pi-smart-terminal's `terminal_exec`), or tools that run commands remotely: an adapter cannot mark them, so their commands would be rewritten. Each problem produces one warning at session start. An entry with an unknown key or an invalid field is ignored as a whole, so a typo can never drop the shell or PTY guard of a built-in adapter. Invalid JSON means the built-in adapters.
+
+`RTK_DISABLED=1` in Pi's environment turns rewriting off; this is RTK's own switch. pi-rtk then never runs rtk, not even `rtk --version`, and `/rtk` reports `off (RTK_DISABLED=1)`.
+
+## Not covered
+
+- Your own `!` and `!!` commands run exactly as typed. Rewriting them would require taking over Pi's `user_bash` execution, and that would bypass sandbox and remote-shell extensions.
+- Permission extensions also handle `tool_call`, in extension load order. One that runs after pi-rtk sees the rewritten command (`rtk git push`), so a rule anchored at the original program (`^git push`) does not match it. Load pi-rtk after such extensions, or write rules that accept an `rtk ` prefix.
+- Output compaction and token statistics belong to RTK. `rtk gain` shows the savings, and `rtk recall <hash>` restores elided output.

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@zeroclover/pi-rtk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Routes shell commands from Pi's bash tool and third-party exec tools through RTK for compact, token-efficient output",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZeroClover/pi-extensions.git",
+    "directory": "packages/pi-rtk"
+  },
+  "homepage": "https://github.com/ZeroClover/pi-extensions/tree/master/packages/pi-rtk#readme",
+  "bugs": {
+    "url": "https://github.com/ZeroClover/pi-extensions/issues"
+  },
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "rtk"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
 }

package/src/adapters.ts

@@ -0,0 +1,67 @@
+import { isAbsolute, resolve } from "node:path";
+
+/** Where a shell-running tool keeps its command and the inputs that decide whether RTK may rewrite it. */
+export interface ToolAdapter {
+	/** Input field holding the shell command string. */
+	commandField: string;
+	/** Input field naming the shell binary, or `false` for no shell; other than a POSIX shell is never rewritten. */
+	shellField?: string;
+	/** Boolean input field requesting a PTY; interactive sessions are never rewritten. */
+	ttyField?: string;
+	/** Input field holding the working directory, resolved against the session cwd. */
+	cwdField?: string;
+}
+
+/**
+ * Pi's built-in `bash` tool and pi-unified-exec's `exec_command`. Tools whose input does not match
+ * an adapter (for example another extension's `exec_command` with different fields) are left alone.
+ */
+export const BUILTIN_ADAPTERS: Readonly<Record<string, ToolAdapter>> = {
+	bash: { commandField: "command" },
+	exec_command: { commandField: "cmd", shellField: "shell", ttyField: "tty", cwdField: "workdir" },
+};
+
+/** Shells whose `-c` syntax RTK's rewrites are written for. */
+const POSIX_SHELLS = new Set(["bash", "sh", "zsh", "dash", "ksh"]);
+
+export type SkipReason = "no-command" | "already-rtk" | "non-posix-shell" | "tty";
+
+export type Target = { kind: "target"; command: string; cwd: string } | { kind: "skip"; reason: SkipReason };
+
+function shellName(shell: string): string {
+	const base = shell.split(/[\\/]/).pop() ?? shell;
+	return base.replace(/\.exe$/i, "").toLowerCase();
+}
+
+/** Decides from a tool call's input whether its command may go through `rtk rewrite`, and in which directory. */
+export function resolveTarget(
+	adapter: ToolAdapter,
+	input: Record<string, unknown>,
+	sessionCwd: string,
+	platform: NodeJS.Platform = process.platform,
+): Target {
+	const command = input[adapter.commandField];
+	if (typeof command !== "string" || command.trim() === "") return { kind: "skip", reason: "no-command" };
+	if (/^\s*rtk(\s|$)/.test(command)) return { kind: "skip", reason: "already-rtk" };
+	if (adapter.ttyField !== undefined && input[adapter.ttyField] === true) return { kind: "skip", reason: "tty" };
+	if (adapter.shellField !== undefined) {
+		const shell = input[adapter.shellField];
+		// `shell: false` means the tool runs the command without a shell, where RTK's rewrites do not parse.
+		if (shell === false) return { kind: "skip", reason: "non-posix-shell" };
+		// `true` asks for the tool's default shell, like an omitted field; any other non-string value is unknown.
+		if (shell !== undefined && shell !== true && typeof shell !== "string")
+			return { kind: "skip", reason: "non-posix-shell" };
+		if (typeof shell === "string" && shell.trim() !== "") {
+			if (!POSIX_SHELLS.has(shellName(shell.trim()))) return { kind: "skip", reason: "non-posix-shell" };
+		} else if (platform === "win32") {
+			// Exec tools choose their own default shell on Windows, which can be PowerShell (pi-unified-exec without Git Bash).
+			return { kind: "skip", reason: "non-posix-shell" };
+		}
+	}
+	let cwd = sessionCwd;
+	if (adapter.cwdField !== undefined) {
+		const dir = input[adapter.cwdField];
+		if (typeof dir === "string" && dir.trim() !== "") cwd = isAbsolute(dir) ? dir : resolve(sessionCwd, dir);
+	}
+	return { kind: "target", command, cwd };
+}

package/src/command.ts

@@ -0,0 +1,58 @@
+import type { ToolAdapter } from "./adapters.ts";
+import type { RtkController } from "./controller.ts";
+
+export const RTK_USAGE = "Usage: /rtk [on|off] (no argument shows the state)";
+
+export type RtkAction = { kind: "status" } | { kind: "on" } | { kind: "off" } | { kind: "usage" };
+
+export function parseRtkArgs(args: string): RtkAction {
+	switch (args.trim().toLowerCase()) {
+		case "":
+			return { kind: "status" };
+		case "on":
+			return { kind: "on" };
+		case "off":
+			return { kind: "off" };
+		default:
+			return { kind: "usage" };
+	}
+}
+
+/** What `/rtk on` reports after the restart; undefined when the availability check has already warned. */
+export function onNotice(controller: RtkController): { message: string; level: "info" | "warning" } | undefined {
+	if (controller.disabledByEnv) {
+		return {
+			message: "pi-rtk: on for this session, but RTK_DISABLED=1 in Pi's environment keeps rewriting off",
+			level: "warning",
+		};
+	}
+	if (!controller.availability.ok) return undefined;
+	return { message: "pi-rtk: on for this session", level: "info" };
+}
+
+function describeAdapter(name: string, adapter: ToolAdapter, registered: ReadonlySet<string>): string {
+	const fields = [`command: ${adapter.commandField}`];
+	if (adapter.shellField !== undefined) fields.push(`shell: ${adapter.shellField}`);
+	if (adapter.ttyField !== undefined) fields.push(`tty: ${adapter.ttyField}`);
+	if (adapter.cwdField !== undefined) fields.push(`cwd: ${adapter.cwdField}`);
+	return `${name} (${fields.join(", ")})${registered.has(name) ? "" : " [not registered]"}`;
+}
+
+/** The `/rtk` status report; `registered` holds the names of the tools registered in this session. */
+export function formatStatus(controller: RtkController, registered: ReadonlySet<string>): string {
+	const { availability, counts } = controller;
+	let state = "on";
+	if (controller.disabledByEnv) state = "off (RTK_DISABLED=1)";
+	else if (!controller.enabled) state = "off (/rtk off)";
+	else if (!availability.ok) state = "unavailable";
+	else if (controller.suspended !== undefined) state = `suspended: ${controller.suspended}`;
+	const adapters = [...controller.adapters].map(([name, adapter]) => describeAdapter(name, adapter, registered));
+	const lines = [
+		`state: ${state}`,
+		`rtk: ${availability.ok ? availability.version : controller.disabledByEnv ? "not checked (RTK_DISABLED=1)" : availability.reason}`,
+		`tools: ${adapters.length === 0 ? "none" : adapters.join("; ")}`,
+		`this session: ${counts.rewritten} rewritten, ${counts.unchanged} unchanged, ${counts.skipped} skipped, ${counts.blocked} blocked, ${counts.failed} failed`,
+	];
+	if (controller.lastFailure !== undefined) lines.push(`last failure: ${controller.lastFailure}`);
+	return ["pi-rtk", ...lines.map((line) => `  ${line}`)].join("\n");
+}

package/src/config.ts

@@ -0,0 +1,107 @@
+import { readFile } from "node:fs/promises";
+import { BUILTIN_ADAPTERS, type ToolAdapter } from "./adapters.ts";
+
+export const CONFIG_FILE_NAME = "pi-rtk.json";
+
+const ADAPTER_KEYS = ["commandField", "shellField", "ttyField", "cwdField"] as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function parseAdapter(
+	value: Record<string, unknown>,
+	path: string,
+	warn: (message: string) => void,
+): ToolAdapter | undefined {
+	// All or nothing: a partly valid adapter could lose its shell or PTY guard and rewrite what it must not.
+	let valid = true;
+	for (const key of Object.keys(value)) {
+		if ((ADAPTER_KEYS as readonly string[]).includes(key)) continue;
+		warn(`${path}.${key}: unknown setting; entry ignored`);
+		valid = false;
+	}
+	const fields: Partial<Record<(typeof ADAPTER_KEYS)[number], string>> = {};
+	for (const key of ADAPTER_KEYS) {
+		const field = value[key];
+		if (field === undefined) continue;
+		if (typeof field === "string" && field !== "") {
+			fields[key] = field;
+		} else {
+			warn(`${path}.${key}: expected a non-empty input field name; entry ignored`);
+			valid = false;
+		}
+	}
+	const { commandField, ...rest } = fields;
+	if (!("commandField" in value)) {
+		warn(`${path}: commandField is required; entry ignored`);
+		valid = false;
+	}
+	return valid && commandField !== undefined ? { commandField, ...rest } : undefined;
+}
+
+/**
+ * Parses the configuration file content into the adapter table: the built-in adapters, with each `tools` entry
+ * adding a tool, replacing a built-in adapter, or (`false`) removing one. Every problem produces one warning and
+ * leaves the affected entry at its built-in state. `text` is undefined when the file does not exist.
+ */
+export function parseConfig(
+	text: string | undefined,
+	source: string,
+): { adapters: Map<string, ToolAdapter>; warnings: string[] } {
+	const adapters = new Map(Object.entries(BUILTIN_ADAPTERS));
+	const warnings: string[] = [];
+	const warn = (message: string): void => {
+		warnings.push(`pi-rtk: ${source}: ${message}`);
+	};
+	if (text === undefined) return { adapters, warnings };
+	let json: unknown;
+	try {
+		json = JSON.parse(text);
+	} catch (error) {
+		warn(`invalid JSON (${errorMessage(error)}); using the built-in tools`);
+		return { adapters, warnings };
+	}
+	if (!isRecord(json)) {
+		warn("expected a JSON object; using the built-in tools");
+		return { adapters, warnings };
+	}
+	for (const key of Object.keys(json)) if (key !== "tools") warn(`${key}: unknown setting ignored`);
+
+	const { tools } = json;
+	if (tools === undefined) return { adapters, warnings };
+	if (!isRecord(tools)) {
+		warn("tools: expected an object mapping tool names to adapters or false; using the built-in tools");
+		return { adapters, warnings };
+	}
+	for (const [name, value] of Object.entries(tools)) {
+		if (value === false) {
+			adapters.delete(name);
+		} else if (isRecord(value)) {
+			const adapter = parseAdapter(value, `tools.${name}`, warn);
+			if (adapter) adapters.set(name, adapter);
+		} else {
+			warn(`tools.${name}: expected an adapter object or false; ignored`);
+		}
+	}
+	return { adapters, warnings };
+}
+
+/** Reads and parses the file at `path`; a missing file yields the built-in tools without a warning. */
+export async function loadConfig(path: string): Promise<{ adapters: Map<string, ToolAdapter>; warnings: string[] }> {
+	let text: string | undefined;
+	try {
+		text = await readFile(path, "utf8");
+	} catch (error) {
+		if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+			const result = parseConfig(undefined, path);
+			result.warnings.push(`pi-rtk: cannot read ${path}: ${errorMessage(error)}; using the built-in tools`);
+			return result;
+		}
+	}
+	return parseConfig(text, path);
+}

package/src/controller.ts

@@ -0,0 +1,213 @@
+import { stat } from "node:fs/promises";
+import { resolveTarget, type ToolAdapter } from "./adapters.ts";
+import { firstLine, interpretRewrite, runFailure } from "./outcome.ts";
+import type { Run } from "./run.ts";
+
+export interface Reporter {
+	notify(message: string, level: "info" | "warning"): void;
+	setStatus(text: string | undefined): void;
+}
+
+export const STATUS_KEY = "rtk";
+export const RTK_BIN = "rtk";
+export const TIMEOUT_MS = 2000;
+/** Consecutive rtk failures (timeouts, crashes, a vanished binary) that suspend rewriting for the session. */
+export const MAX_CONSECUTIVE_FAILURES = 3;
+/** How long an unavailable rtk is trusted before the next tool call checks again. */
+export const RECHECK_MS = 30_000;
+/** `rtk rewrite` first shipped in 0.25.0 (rtk CHANGELOG, #241). */
+const MIN_VERSION: readonly [number, number, number] = [0, 25, 0];
+
+export type Availability = { ok: true; version: string } | { ok: false; reason: string };
+
+export interface Counts {
+	rewritten: number;
+	unchanged: number;
+	skipped: number;
+	blocked: number;
+	failed: number;
+}
+
+function emptyCounts(): Counts {
+	return { rewritten: 0, unchanged: 0, skipped: 0, blocked: 0, failed: 0 };
+}
+
+/** Reads `rtk X.Y.Z` and checks it against the minimum; output without a version is accepted as is. */
+export function checkVersion(output: string): Availability {
+	const match = /(\d+)\.(\d+)\.(\d+)/.exec(output);
+	if (!match) return { ok: true, version: output.trim() || "unknown" };
+	const version = [Number(match[1]), Number(match[2]), Number(match[3])];
+	const text = version.join(".");
+	for (let i = 0; i < MIN_VERSION.length; i++) {
+		const have = version[i] ?? 0;
+		const need = MIN_VERSION[i] ?? 0;
+		if (have > need) break;
+		if (have < need) return { ok: false, reason: `rtk ${text} is too old (need ${MIN_VERSION.join(".")} or newer)` };
+	}
+	return { ok: true, version: text };
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+	try {
+		return (await stat(path)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+export interface ControllerOptions {
+	run: Run;
+	/** Reads an environment variable of Pi's process. */
+	getEnv?: (name: string) => string | undefined;
+	now?: () => number;
+}
+
+export class RtkController {
+	adapters = new Map<string, ToolAdapter>();
+	availability: Availability = { ok: false, reason: "not checked yet" };
+	/** False after `/rtk off`; every session starts on. */
+	enabled = true;
+	/** Why rewriting stopped after repeated rtk failures, until `/rtk on` or the next session. */
+	suspended: string | undefined;
+	lastFailure: string | undefined;
+	counts = emptyCounts();
+	private consecutiveFailures = 0;
+	private checkedAt = 0;
+	private readonly run: Run;
+	private readonly getEnv: (name: string) => string | undefined;
+	private readonly now: () => number;
+
+	constructor(options: ControllerOptions) {
+		this.run = options.run;
+		this.getEnv = options.getEnv ?? ((name) => process.env[name]);
+		this.now = options.now ?? Date.now;
+	}
+
+	/** True when `RTK_DISABLED=1` is set in Pi's environment, RTK's own off switch. */
+	get disabledByEnv(): boolean {
+		return this.getEnv("RTK_DISABLED") === "1";
+	}
+
+	/** Resets the per-session state and checks for a usable rtk binary. */
+	async start(adapters: Map<string, ToolAdapter>, reporter: Reporter): Promise<void> {
+		this.adapters = adapters;
+		this.enabled = true;
+		this.counts = emptyCounts();
+		await this.restart(reporter);
+	}
+
+	/** Clears a suspension and checks rtk again; used by `/rtk on` and at session start. */
+	async restart(reporter: Reporter): Promise<void> {
+		this.suspended = undefined;
+		this.lastFailure = undefined;
+		this.consecutiveFailures = 0;
+		// RTK's own switch is fixed for the process: nothing will run rtk, so there is nothing to check or warn about.
+		if (this.disabledByEnv) {
+			reporter.setStatus(this.statusText());
+			return;
+		}
+		await this.check(reporter, true);
+	}
+
+	setEnabled(enabled: boolean, reporter: Reporter): void {
+		this.enabled = enabled;
+		reporter.setStatus(this.statusText());
+	}
+
+	/** Footer text while commands are not being rewritten; undefined while RTK is active. */
+	statusText(): string | undefined {
+		if (!this.enabled || this.disabledByEnv) return "RTK off";
+		if (!this.availability.ok) return "RTK unavailable";
+		if (this.suspended !== undefined) return "RTK suspended";
+		return undefined;
+	}
+
+	private async check(reporter: Reporter, announce: boolean): Promise<void> {
+		const wasOk = this.availability.ok;
+		// Set before the probe so that parallel tool calls do not each start a recheck.
+		this.checkedAt = this.now();
+		this.availability = await this.probe();
+		if (!this.availability.ok && (announce || wasOk)) {
+			reporter.notify(`pi-rtk: commands run unchanged: ${this.availability.reason}`, "warning");
+		}
+		reporter.setStatus(this.statusText());
+	}
+
+	private async probe(): Promise<Availability> {
+		const run = await this.run(RTK_BIN, ["--version"], { timeoutMs: TIMEOUT_MS });
+		const failure = runFailure("rtk --version", run);
+		if (failure !== undefined) return { ok: false, reason: `${failure} (is rtk installed and on PATH?)` };
+		if (run.code !== 0) {
+			const detail = firstLine(run.stderr);
+			return { ok: false, reason: `rtk --version exited with code ${run.code}${detail === "" ? "" : `: ${detail}`}` };
+		}
+		return checkVersion(run.stdout);
+	}
+
+	/**
+	 * Rewrites the command in `input` in place when the tool has an adapter and RTK has an equivalent. Returns a
+	 * block when RTK denies the command with a message; every other problem leaves the command unchanged.
+	 */
+	async handleToolCall(
+		toolName: string,
+		input: Record<string, unknown>,
+		cwd: string,
+		signal: AbortSignal | undefined,
+		reporter: Reporter,
+	): Promise<{ block: true; reason: string } | undefined> {
+		const adapter = this.adapters.get(toolName);
+		if (!adapter || !this.enabled || this.suspended !== undefined || this.disabledByEnv) return undefined;
+		if (!this.availability.ok) {
+			if (this.now() - this.checkedAt < RECHECK_MS) return undefined;
+			await this.check(reporter, false);
+			if (!this.availability.ok) return undefined;
+		}
+		const target = resolveTarget(adapter, input, cwd);
+		// A missing working directory is the tool's error to report, not rtk's.
+		if (target.kind === "skip" || !(await isDirectory(target.cwd))) {
+			this.counts.skipped++;
+			return undefined;
+		}
+
+		// `--` keeps a command such as `-h` from being parsed as an rtk option, whose help text would become the rewrite.
+		const run = await this.run(RTK_BIN, ["rewrite", "--", target.command], {
+			cwd: target.cwd,
+			timeoutMs: TIMEOUT_MS,
+			...(signal ? { signal } : {}),
+		});
+		// The tool call is being cancelled; that is not a fault of rtk.
+		if (signal?.aborted) return undefined;
+
+		const outcome = interpretRewrite(target.command, run);
+		if (outcome.kind === "failure") {
+			this.recordFailure(outcome.reason, reporter);
+			return undefined;
+		}
+		this.consecutiveFailures = 0;
+		switch (outcome.kind) {
+			case "rewrite":
+				input[adapter.commandField] = outcome.command;
+				this.counts.rewritten++;
+				return undefined;
+			case "unchanged":
+				this.counts.unchanged++;
+				return undefined;
+			case "block":
+				this.counts.blocked++;
+				return { block: true, reason: `rtk: ${outcome.reason}` };
+		}
+	}
+
+	private recordFailure(reason: string, reporter: Reporter): void {
+		this.counts.failed++;
+		this.lastFailure = reason;
+		this.consecutiveFailures++;
+		if (this.consecutiveFailures < MAX_CONSECUTIVE_FAILURES || this.suspended !== undefined) return;
+		this.suspended = `${MAX_CONSECUTIVE_FAILURES} consecutive rtk failures, last: ${reason}`;
+		reporter.notify(
+			`pi-rtk: suspended for this session after ${this.suspended}; commands run unchanged. /rtk on retries.`,
+			"warning",
+		);
+		reporter.setStatus(this.statusText());
+	}
+}

package/src/index.ts

@@ -0,0 +1,67 @@
+import { join } from "node:path";
+import { type ExtensionAPI, type ExtensionContext, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { formatStatus, onNotice, parseRtkArgs, RTK_USAGE } from "./command.ts";
+import { CONFIG_FILE_NAME, loadConfig } from "./config.ts";
+import { type Reporter, RtkController, STATUS_KEY } from "./controller.ts";
+import { runFile } from "./run.ts";
+
+function reporterFor(ctx: ExtensionContext): Reporter {
+	return {
+		notify: (message, level) => ctx.ui.notify(message, level),
+		setStatus: (text) => ctx.ui.setStatus(STATUS_KEY, text),
+	};
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+export default function (pi: ExtensionAPI): void {
+	const controller = new RtkController({ run: runFile });
+
+	pi.on("session_start", async (_event, ctx) => {
+		const reporter = reporterFor(ctx);
+		const { adapters, warnings } = await loadConfig(join(getAgentDir(), CONFIG_FILE_NAME));
+		for (const warning of warnings) reporter.notify(warning, "warning");
+		await controller.start(adapters, reporter);
+	});
+
+	pi.on("tool_call", async (event, ctx) => {
+		try {
+			return await controller.handleToolCall(event.toolName, event.input, ctx.cwd, ctx.signal, reporterFor(ctx));
+		} catch (error) {
+			// A throwing tool_call handler blocks the tool; a rewrite problem must never stop a command.
+			ctx.ui.notify(`pi-rtk: command left unchanged after an internal error: ${errorMessage(error)}`, "warning");
+			return undefined;
+		}
+	});
+
+	pi.registerCommand("rtk", {
+		description: "Show pi-rtk's state, or turn RTK rewriting on or off for this session",
+		handler: async (args, ctx) => {
+			const reporter = reporterFor(ctx);
+			const action = parseRtkArgs(args);
+			switch (action.kind) {
+				case "status": {
+					const registered = new Set(pi.getAllTools().map((tool) => tool.name));
+					reporter.notify(formatStatus(controller, registered), "info");
+					return;
+				}
+				case "on": {
+					controller.setEnabled(true, reporter);
+					await controller.restart(reporter);
+					const notice = onNotice(controller);
+					if (notice) reporter.notify(notice.message, notice.level);
+					return;
+				}
+				case "off":
+					controller.setEnabled(false, reporter);
+					reporter.notify("pi-rtk: off for this session", "info");
+					return;
+				case "usage":
+					reporter.notify(RTK_USAGE, "warning");
+					return;
+			}
+		},
+	});
+}