pi-managed-axi 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# pi-agent-reach-axi
+
+User-managed output capture and recovery for Pi.
+
+AXI adds a small, controlled path for running reviewed read-only integrations and for keeping large shell-tool results available after Pi compacts them.
+
+## How it works
+
+AXI has two separate paths:
+
+- **AXI tools** expose exactly `axi_help`, `axi_run`, and `axi_read`. `axi_run` is fail-closed. It runs only reviewed read-only contracts: `agent-reach/doctor`, `opencli/hackernews/search`, and `opencli/hackernews/read`.
+- **The result hook** watches Pi's `tool_result` events. It handles only simple Bash or PowerShell commands for tools the user selected. Selection allows capture and presentation only. It does not authorize, block, or execute commands.
+
+For large managed results, AXI stores raw stdout, raw stderr, and formatted output in private temporary files. Pi receives a bounded preview and a session-scoped result ID. Call `axi_read` to page any stream by UTF-8 byte offset.
+
+If AXI cannot validate or read Pi's spill file, it leaves the native result unchanged. The default managed-tool selection is empty.
+
+## Configure capture
+
+Run this in interactive Pi:
+
+```text
+/axi settings
+```
+
+The settings overlay scans a fixed list of known command names without running them. It lists commands found on `PATH`, supports fuzzy search, and saves selections to `pi-managed-axi.json` under `PI_CODING_AGENT_DIR` or `~/.pi/agent`.
+
+Use `Space` to toggle, `Enter` or `Ctrl+S` to save, and `Esc` to close or discard. AXI does not install, authenticate, update, or configure tools. Shell operators, wrappers, and unknown executables remain native.
+
+## Use the AXI tools
+
+```text
+axi_help
+axi_run {"command":"opencli/hackernews/search","args":{"query":"sqlite","limit":3}}
+axi_read {"result":"...","stream":"formatted","offset":0,"limit":8192}
+```
+
+Agent Reach and OpenCLI must already be installed. AXI does not provide global capture for every command.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "pi-managed-axi",
+  "version": "0.1.0",
+  "description": "User-managed output capture and recovery for Pi",
+  "files": ["src", "README.md"],
+  "type": "module",
+  "keywords": ["pi-package", "axi", "toon"],
+  "license": "MIT",
+  "engines": { "node": ">=22.19.0" },
+  "scripts": {
+    "test": "node --experimental-strip-types --test test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "pack:check": "npm pack --dry-run"
+  },
+  "dependencies": { "@toon-format/toon": "^4.1.1" },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "pi": { "extensions": ["./src/index.ts"] },
+  "exports": { "./core": "./src/core.ts" },
+  "devDependencies": { "@types/node": "^22.0.0", "typescript": "^5.7.0" }
+}

package/src/backends/agent-reach.ts

@@ -0,0 +1,24 @@
+import type { ProcessResult } from "../runner.ts";
+import { runProcess } from "../runner.ts";
+import type { AxiBackend, CommandSpec } from "../core.ts";
+
+export function createAgentReachBackend(run: (request: { executable: string; argv: string[]; timeoutMs?: number; signal?: AbortSignal }) => Promise<ProcessResult> = runProcess): AxiBackend {
+  const command: CommandSpec = {
+    id: "agent-reach/doctor",
+    description: "Diagnose Agent Reach backends",
+    access: "read",
+    format: "json",
+    args: [],
+    executable: "agent-reach",
+    buildArgv: (args) => {
+      if (Object.keys(args).length) throw new Error("agent-reach/doctor accepts no arguments");
+      return ["doctor", "--json"];
+    },
+  };
+  return {
+    id: "agent-reach",
+    description: "Agent Reach health report",
+    async discover() { return [command]; },
+    async execute(request) { return run({ ...request, executable: "agent-reach", argv: command.buildArgv({}) }); },
+  };
+}

package/src/backends/opencli.ts

@@ -0,0 +1,121 @@
+import type { ProcessResult } from "../runner.ts";
+import { runProcess } from "../runner.ts";
+import type { AxiBackend, ArgumentSpec, CommandSpec } from "../core.ts";
+
+type RawArg = { name?: unknown; type?: unknown; required?: unknown; valueRequired?: unknown; positional?: unknown; choices?: unknown; default?: unknown; help?: unknown; minimum?: unknown; maximum?: unknown };
+type RawCommand = { command?: unknown; description?: unknown; access?: unknown; strategy?: unknown; browser?: unknown; args?: unknown };
+
+const REVIEWED: Record<string, { args: ArgumentSpec[] }> = {
+  "hackernews/search": { args: [
+    { name: "query", type: "string", required: true, positional: true, valueRequired: false },
+    { name: "limit", type: "integer", positional: false, valueRequired: false, default: 20 },
+    { name: "sort", type: "string", positional: false, valueRequired: false, choices: ["relevance", "date"], default: "relevance" },
+  ] },
+  "hackernews/read": { args: [
+    { name: "id", type: "string", required: true, positional: true, valueRequired: false },
+    { name: "limit", type: "integer", positional: false, valueRequired: false, default: 25 },
+    { name: "depth", type: "integer", positional: false, valueRequired: false, default: 2 },
+    { name: "replies", type: "integer", positional: false, valueRequired: false, default: 5 },
+    { name: "max-length", type: "integer", positional: false, valueRequired: false, default: 2000 },
+  ] },
+};
+
+function validToken(value: unknown): value is string { return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(value); }
+function sameContract(actual: ArgumentSpec[], expected: ArgumentSpec[]) {
+  const shape = (items: ArgumentSpec[]) => items.map(({ name, type, required, positional, valueRequired, choices, default: defaultValue, minimum, maximum }) => ({ name, type, required: Boolean(required), positional: Boolean(positional), valueRequired: valueRequired !== false, choices: choices ?? [], default: defaultValue === undefined ? null : defaultValue, minimum: minimum === undefined ? null : minimum, maximum: maximum === undefined ? null : maximum }));
+  return JSON.stringify(shape(actual)) === JSON.stringify(shape(expected));
+}
+
+export function normalizeOpenCliCommand(raw: RawCommand | null): CommandSpec | undefined {
+  if (!raw || typeof raw !== "object" || typeof raw.command !== "string" || !raw.command.includes("/")) return undefined;
+  const [site, name] = raw.command.split("/");
+  if (!validToken(site) || !validToken(name) || typeof raw.description !== "string" || raw.access !== "read" || raw.strategy !== "public" || raw.browser !== false || !Array.isArray(raw.args)) return undefined;
+  const args: ArgumentSpec[] = [];
+  for (const item of raw.args as RawArg[]) {
+    if (!item || !validToken(item.name) || typeof item.type !== "string") return undefined;
+    if ([item.required, item.valueRequired, item.positional].some((value) => value !== undefined && typeof value !== "boolean")) return undefined;
+    const type = item.type === "str" || item.type === "string" ? "string" : item.type === "bool" || item.type === "boolean" ? "boolean" : item.type === "int" ? "integer" : item.type === "number" ? "number" : undefined;
+    if (!type || (item.choices !== undefined && !Array.isArray(item.choices))) return undefined;
+    const choices = (item.choices ?? []).filter((value): value is string | number | boolean => ["string", "number", "boolean"].includes(typeof value));
+    if ((item.choices ?? []).length !== choices.length) return undefined;
+    if (item.minimum !== undefined && (typeof item.minimum !== "number" || !Number.isFinite(item.minimum))) return undefined;
+    if (item.maximum !== undefined && (typeof item.maximum !== "number" || !Number.isFinite(item.maximum))) return undefined;
+    const defaultValue = item.default === null ? undefined : item.default;
+    const spec: ArgumentSpec = { name: item.name, type, required: item.required === true, positional: item.positional === true, valueRequired: item.valueRequired !== false, choices, description: typeof item.help === "string" ? item.help : undefined, minimum: item.minimum as number | undefined, maximum: item.maximum as number | undefined, default: defaultValue };
+    try { if (defaultValue !== undefined) validateArgument(spec, defaultValue); } catch { return undefined; }
+    args.push(spec);
+  }
+  const reviewed = REVIEWED[raw.command];
+  if (!reviewed || !sameContract(args, reviewed.args)) return undefined;
+  return { id: `opencli/${raw.command}`, description: raw.description, access: "read", format: "json", args, executable: "opencli", buildArgv: (values) => compileArgs({ id: `opencli/${raw.command}`, description: raw.description as string, access: "read", format: "json", args, executable: "opencli", buildArgv: () => [] }, values) };
+}
+
+export function validateArgument(spec: ArgumentSpec, value: unknown) {
+  if (typeof value === "string" && value.includes("\0")) throw new Error(`argument ${spec.name} contains NUL`);
+  const valid = spec.type === "string" ? typeof value === "string" : spec.type === "boolean" ? typeof value === "boolean" : spec.type === "integer" ? typeof value === "number" && Number.isSafeInteger(value) : typeof value === "number" && Number.isFinite(value);
+  if (!valid) throw new Error(`argument ${spec.name} must be ${spec.type}`);
+  if (typeof value === "number" && (spec.minimum !== undefined && value < spec.minimum || spec.maximum !== undefined && value > spec.maximum)) throw new Error(`argument ${spec.name} is out of range`);
+  if (spec.choices?.length && !spec.choices.some((choice) => choice === value)) throw new Error(`argument ${spec.name} must be one of the allowed choices`);
+}
+
+function formatArgValue(value: unknown): string {
+  return typeof value === "number" && Object.is(value, -0) ? "-0" : String(value);
+}
+
+export function compileArgs(command: CommandSpec, values: Record<string, unknown>): string[] {
+  const known = new Set(command.args.map((arg) => arg.name));
+  for (const key of Object.keys(values)) if (!known.has(key)) throw new Error(`unknown argument: ${key}`);
+  const resolved: Record<string, unknown> = {};
+  for (const spec of command.args) {
+    if (!Object.hasOwn(values, spec.name)) {
+      if (spec.required) throw new Error(`missing required argument: ${spec.name}`);
+      continue;
+    }
+    const value = values[spec.name];
+    validateArgument(spec, value);
+    resolved[spec.name] = value;
+  }
+  const positionals = command.args.filter((arg) => arg.positional);
+  let missing = false;
+  for (const spec of positionals) {
+    if (!Object.hasOwn(resolved, spec.name)) missing = true;
+    else if (missing) throw new Error("cannot represent a positional argument gap");
+  }
+  const options = command.args.filter((arg) => !arg.positional && Object.hasOwn(resolved, arg.name)).map((arg) => `--${arg.name}=${formatArgValue(resolved[arg.name])}`);
+  const positionalValues = positionals.filter((arg) => Object.hasOwn(resolved, arg.name)).map((arg) => formatArgValue(resolved[arg.name]));
+  return [command.id.slice("opencli/".length).split("/"), "--format=json", ...options, ...(positionalValues.length ? ["--", ...positionalValues] : [])].flat();
+}
+
+export function createOpenCliBackend(options: { run?: (request: { executable: string; argv: string[]; timeoutMs?: number; signal?: AbortSignal }) => Promise<ProcessResult> } = {}): AxiBackend {
+  const run = options.run ?? runProcess;
+  let report = { excluded: 0, write: 0, unreviewed: 0, changedContract: 0, unsupportedSchema: 0 };
+  return {
+    id: "opencli",
+    description: "Reviewed read-only OpenCLI commands",
+    async discover(signal) {
+      const result = await run({ executable: "opencli", argv: ["list", "--format=json"], timeoutMs: 15_000, signal });
+      if (result.reason && result.reason !== "exit" || result.code !== 0) throw new Error(`OpenCLI discovery failed: ${result.error ?? result.code ?? result.reason}`);
+      let raw: unknown;
+      try { raw = JSON.parse(result.stdout); } catch { throw new Error("OpenCLI discovery returned invalid JSON"); }
+      if (!Array.isArray(raw)) throw new Error("OpenCLI discovery returned an invalid catalog");
+      const commands: CommandSpec[] = [];
+      let excluded = 0, write = 0, unreviewed = 0, changedContract = 0, unsupportedSchema = 0;
+      for (const item of raw) {
+        if (!item || typeof item !== "object") { excluded++; continue; }
+        const rawCommand = item as RawCommand;
+        const candidate = normalizeOpenCliCommand(rawCommand);
+        if (candidate) { commands.push(candidate); continue; }
+        excluded++;
+        if (rawCommand?.access !== "read") { write++; continue; }
+        const commandId = typeof rawCommand?.command === "string" ? rawCommand.command : "";
+        if (!Object.hasOwn(REVIEWED, commandId)) { unreviewed++; continue; }
+        if (!Array.isArray(rawCommand?.args) || (rawCommand.args as RawArg[]).some((arg) => !arg || typeof arg.name !== "string" || typeof arg.type !== "string" || !["str", "string", "bool", "boolean", "int", "number"].includes(arg.type))) unsupportedSchema++;
+        else changedContract++;
+      }
+      report = { excluded, write, unreviewed, changedContract, unsupportedSchema };
+      return commands;
+    },
+    getReport() { return report; },
+    async execute(request) { return run(request); },
+  };
+}

package/src/core.ts

@@ -0,0 +1,132 @@
+import { Type } from "typebox";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { formatCapture, truncateUtf8 } from "./format.ts";
+import { processError, runProcess, type ProcessResult } from "./runner.ts";
+import { findResult, readResultPage, saveResult, type ResultReference, type ResultStream } from "./results.ts";
+
+export type ArgumentType = "string" | "boolean" | "integer" | "number";
+export interface ArgumentSpec { name: string; type: ArgumentType; required?: boolean; positional?: boolean; valueRequired?: boolean; choices?: Array<string | number | boolean>; default?: unknown; description?: string; minimum?: number; maximum?: number; }
+export interface CommandSpec { id: string; description: string; access: string; format: "json" | "text"; args: ArgumentSpec[]; executable: string; buildArgv: (args: Record<string, unknown>) => string[]; }
+export interface AxiExecutionRequest { executable: string; argv: string[]; signal?: AbortSignal; timeoutMs?: number; }
+export interface AxiBackend { id: string; description: string; discover: (signal?: AbortSignal) => Promise<CommandSpec[]>; execute?: (request: AxiExecutionRequest) => Promise<ProcessResult>; getReport?: () => unknown; }
+
+function text(text: string) { return { content: [{ type: "text" as const, text }], details: undefined }; }
+function details(reference: ResultReference, command: CommandSpec, result: ProcessResult, previewComplete: boolean) { return { result: reference.id, command: command.id, format: command.format, exitCode: result.code, captureComplete: result.captureComplete, previewComplete, bytes: reference.bytes, artifacts: { stdout: reference.stdoutPath, stderr: reference.stderrPath, formatted: reference.formattedPath } }; }
+function commandExample(command: CommandSpec) {
+  const args = Object.fromEntries(command.args.map((arg) => [arg.name, arg.default ?? arg.choices?.[0] ?? (arg.type === "string" ? "example" : arg.type === "boolean" ? false : 1)]));
+  return JSON.stringify({ command: command.id, args });
+}
+
+export function registerAxiTools(pi: ExtensionAPI, backends: AxiBackend[]) {
+  const backendMap = new Map(backends.map((backend) => [backend.id, backend]));
+  const cache = new Map<string, { generation: number; promise: Promise<CommandSpec[]> }>();
+  const reset = () => cache.clear();
+  const discover = (backend: AxiBackend, refresh = false, signal?: AbortSignal) => {
+    const old = cache.get(backend.id);
+    if (refresh) cache.delete(backend.id);
+    const current = refresh ? undefined : cache.get(backend.id);
+    if (current) return current;
+    const record = { generation: (old?.generation ?? 0) + 1, promise: Promise.resolve([] as CommandSpec[]) };
+    record.promise = backend.discover(signal).then((commands) => { if (cache.get(backend.id) === record) return commands; throw new Error("discovery was superseded"); }).catch((error) => { if (cache.get(backend.id) === record) cache.delete(backend.id); throw error; });
+    cache.set(backend.id, record);
+    return record;
+  };
+  const findCommand = async (id: string, signal?: AbortSignal) => {
+    const slash = id.indexOf("/");
+    if (slash < 1) throw new Error(`unknown AXI command: ${id}`);
+    const backend = backendMap.get(id.slice(0, slash));
+    if (!backend) throw new Error(`unknown AXI backend: ${id.slice(0, slash)}`);
+    const record = discover(backend, false, signal);
+    const commands = await record.promise;
+    if (cache.get(backend.id) !== record) throw new Error("command discovery changed before execution");
+    const command = commands.find((candidate) => candidate.id === id);
+    if (!command) throw new Error(`unknown or unavailable AXI command: ${id}`);
+    return { backend, command, record };
+  };
+
+  pi.registerTool({
+    name: "axi_help", label: "AXI help", description: "List trusted read-only AXI commands and argument schemas.",
+    parameters: Type.Object({ backend: Type.Optional(Type.String()), command: Type.Optional(Type.String()), refresh: Type.Optional(Type.Boolean()) }),
+    async execute(_id: string, params: { backend?: string; command?: string; refresh?: boolean }, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: ExtensionContext) {
+      if (params.refresh && !params.backend && !params.command) throw new Error("refresh requires a backend or command");
+      if (!params.backend && !params.command) return text(JSON.stringify({ backends: [...backendMap.values()].map((backend) => ({ id: backend.id, description: backend.description })) }));
+      let backendIds = params.backend ? [params.backend] : [params.command!.slice(0, params.command!.indexOf("/"))];
+      if (params.command && !params.command.includes("/")) throw new Error(`invalid AXI command: ${params.command}`);
+      if (params.backend && params.command && !params.command.startsWith(`${params.backend}/`)) throw new Error("backend and command do not agree");
+      const output: Record<string, unknown> = { backends: [] };
+      const listed: unknown[] = [];
+      for (const id of backendIds) {
+        const backend = backendMap.get(id);
+        if (!backend) throw new Error(`unknown AXI backend: ${id}`);
+        const record = discover(backend, Boolean(params.refresh), signal);
+        const commands = await record.promise;
+        const selected = params.command ? commands.filter((command) => command.id === params.command) : commands;
+        if (params.command && selected.length === 0) throw new Error(`unknown or unavailable AXI command: ${params.command}`);
+        listed.push({ id, description: backend.description, commands: selected.map((command) => ({ id: command.id, description: command.description, access: command.access, format: command.format, args: command.args, example: commandExample(command) })), report: backend.getReport?.() });
+      }
+      output.backends = listed;
+      const catalog = JSON.stringify(output);
+      if (Buffer.byteLength(catalog) <= 12 * 1024 && catalog.split("\n").length <= 200) return text(catalog);
+      const reference = await saveResult({ command: `axi-help/${backendIds.join(",")}`, format: "text", stdout: catalog, stderr: "", formatted: catalog, captureComplete: true, append: (value) => pi.appendEntry("axi-result", value) });
+      const footer = `\n\n[result=${reference.id} previewComplete=false; call axi_read with {"result":"${reference.id}"}]`;
+      return { ...text(`${truncateUtf8(catalog, 12 * 1024 - Buffer.byteLength(footer), 197)}${footer}`), details: { result: reference.id, format: "text", bytes: reference.bytes, captureComplete: true, previewComplete: false } };
+    },
+  });
+
+  pi.registerTool({
+    name: "axi_run", label: "AXI run", description: "Run one trusted read-only AXI command and save its complete output.",
+    parameters: Type.Object({ command: Type.String(), args: Type.Optional(Type.Record(Type.String(), Type.Unknown())) }),
+    async execute(_id: string, params: { command: string; args?: Record<string, unknown> }, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: ExtensionContext) {
+      const { backend, command } = await findCommand(params.command, signal);
+      if (command.access !== "read") throw new Error(`AXI command is not read-only: ${command.id}`);
+      const argv = command.buildArgv(params.args ?? {});
+      const result = await (backend.execute ?? runProcess)({ executable: command.executable, argv, signal, timeoutMs: 60_000 });
+      const formatted = formatCapture(result.stdout, result.stderr, command.format);
+      const previewBody = `command=${command.id}\nformat=${command.format}\nexitCode=${result.code ?? "unknown"}\ncaptureComplete=${result.captureComplete}\n\n${formatted.full}`;
+      let reference: ResultReference | undefined;
+      try {
+        reference = await saveResult({ command: command.id, format: command.format, stdout: result.stdout, stderr: result.stderr, formatted: formatted.full, captureComplete: result.captureComplete, append: (value) => pi.appendEntry("axi-result", value) });
+      } catch (error) {
+        const incomplete = result.captureComplete ? "" : " missing output cannot be recovered from the saved prefix";
+        const failure = truncateUtf8(`${previewBody}\n\n[error] ${error instanceof Error ? error.message : String(error)}${incomplete}\n[recovery unavailable; previewComplete=false]`, 12 * 1024, 197, "preview truncated; recovery unavailable");
+        throw new Error(failure);
+      }
+      let footer = `\n\n[result=${reference.id} captureComplete=${result.captureComplete} previewComplete=false]`;
+      let previewComplete = Buffer.byteLength(previewBody + footer) <= 12 * 1024 && (previewBody + footer).split("\n").length <= 200;
+      footer = `\n\n[result=${reference.id} captureComplete=${result.captureComplete} previewComplete=${previewComplete}]`;
+      previewComplete = Buffer.byteLength(previewBody + footer) <= 12 * 1024 && (previewBody + footer).split("\n").length <= 200;
+      if (!previewComplete) footer = `\n\n[result=${reference.id} captureComplete=${result.captureComplete} previewComplete=false]`;
+      const preview = previewComplete ? previewBody : truncateUtf8(previewBody, 12 * 1024 - Buffer.byteLength(footer), 197);
+      const resultText = `${preview}${footer}`;
+      const resultDetails = details(reference, command, result, previewComplete);
+      if (result.code !== 0 || (result.reason !== undefined && result.reason !== "exit")) {
+        const incomplete = result.captureComplete ? "" : " missing output cannot be recovered from the saved prefix";
+        const failureFooter = `\n\n[error=${processError(result)}${incomplete} result=${reference.id} captureComplete=${result.captureComplete} previewComplete=false; call axi_read with {"result":"${reference.id}"} to recover saved output]`;
+        const failurePreview = truncateUtf8(previewBody, 12 * 1024 - Buffer.byteLength(failureFooter), 197);
+        throw new Error(`${failurePreview}${failureFooter}`);
+      }
+      return { ...text(resultText), details: resultDetails };
+    },
+  });
+
+  pi.registerTool({
+    name: "axi_read", label: "AXI read", description: "Read pages from a saved AXI result.",
+    parameters: Type.Object({ result: Type.String(), stream: Type.Optional(Type.Union([Type.Literal("stdout"), Type.Literal("stderr"), Type.Literal("formatted")])), offset: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 4, maximum: 32 * 1024 })) }),
+    async execute(_id: string, params: { result: string; stream?: ResultStream; offset?: number; limit?: number }, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: ExtensionContext) {
+      const reference = findResult(ctx.sessionManager.getEntries(), params.result);
+      if (!reference) throw new Error("result is not available in this session");
+      const stream = params.stream ?? "formatted";
+      const page = await readResultPage(reference, stream, { offset: params.offset, limit: params.limit });
+      const { text: _pageText, ...pageDetails } = page;
+      Object.assign(pageDetails, { format: reference.format, captureComplete: reference.captureComplete });
+      const marker = `[axi_read result=${reference.id} stream=${stream} format=${reference.format} offset=${page.offset} bytes=${page.bytes} totalBytes=${page.totalBytes} nextOffset=${page.nextOffset ?? "null"} eof=${page.eof} captureComplete=${reference.captureComplete}]`;
+      return { ...text(page.text + marker), details: pageDetails };
+    },
+  });
+
+  pi.on("session_start", () => reset());
+  pi.on("session_shutdown", () => reset());
+}
+
+export { findResult, readResultPage, saveResult } from "./results.ts";
+export { registerAxiHook, compactAxiToolResult } from "./hook.ts";

package/src/format.ts

@@ -0,0 +1,79 @@
+import { encode } from "@toon-format/toon";
+
+export type OutputFormat = "json" | "text";
+
+export interface FormatResult {
+  full: string;
+  preview: string;
+  warning?: string;
+  format: OutputFormat;
+}
+
+function numericSafeJson(raw: string): unknown {
+  let lost = false;
+  const reviver = (_key: string, value: unknown, context?: { source?: string }) => {
+    if (typeof value === "number") {
+      const source = context?.source;
+      if (!source || !Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value)) || String(value) !== source) lost = true;
+    }
+    return value;
+  };
+  const value = JSON.parse(raw, reviver as (key: string, value: unknown) => unknown);
+  if (lost) throw new Error("JSON number changed during parsing");
+  return value;
+}
+
+function encodeJson(raw: string): { text: string; warning?: string } {
+  try {
+    return { text: encode(numericSafeJson(raw)) };
+  } catch (error) {
+    return {
+      text: raw,
+      warning: `TOON formatting skipped: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+export function truncateUtf8(text: string, maxBytes: number, maxLines = 200, notice = "preview truncated") {
+  const source = Buffer.from(text, "utf8");
+  if (source.length <= maxBytes && (text.match(/\n/g)?.length ?? 0) + 1 <= maxLines) return text;
+  const suffix = `\n[${notice}]`;
+  const suffixBytes = Buffer.byteLength(suffix);
+  let end = Math.max(0, maxBytes - suffixBytes);
+  end = Math.min(end, source.length);
+  while (end > 0) {
+    try {
+      const candidate = new TextDecoder("utf-8", { fatal: true }).decode(source.subarray(0, end));
+      const lines = candidate.split("\n");
+      if (lines.length > maxLines) {
+        end = Buffer.byteLength(lines.slice(0, maxLines).join("\n"));
+        continue;
+      }
+      return candidate + suffix;
+    } catch {
+      end--;
+    }
+  }
+  return suffix.slice(0, maxBytes);
+}
+
+export function formatCapture(stdout: string, stderr: string, format: OutputFormat, options: { previewBytes?: number; previewLines?: number } = {}): FormatResult {
+  let full = stdout;
+  let warning: string | undefined;
+  if (format === "json") {
+    if (!stdout.trim()) {
+      full = encode({ stdout: "" });
+    } else {
+      const encoded = encodeJson(stdout);
+      full = encoded.text;
+      warning = encoded.warning;
+    }
+  }
+  if (stderr) {
+    const label = `\n\n[stderr]\n${stderr}`;
+    full += label;
+  }
+  if (warning) full = `${full}\n\n[warning] ${warning}`;
+  const preview = truncateUtf8(full, options.previewBytes ?? 12 * 1024, options.previewLines ?? 200);
+  return { full, preview, warning, format };
+}

package/src/hook.ts

@@ -0,0 +1,155 @@
+import type { ExtensionAPI, ToolResultEvent } from "@earendil-works/pi-coding-agent";
+import { isBashToolResult, isPowerShellToolResult } from "@earendil-works/pi-coding-agent";
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, resolve } from "node:path";
+import { formatCapture, truncateUtf8 } from "./format.ts";
+import { saveResult, type ResultReference } from "./results.ts";
+import { createManagedToolPolicy, type ManagedToolPolicy } from "./managed-tools.ts";
+
+const PREVIEW_BYTES = 12 * 1024;
+const PREVIEW_LINES = 200;
+const FOOTER_SLACK = 128;
+const MAX_CAPTURE_BYTES = 64 * 1024 * 1024;
+
+interface AxiHookDetails {
+  truncation?: { truncated?: boolean };
+  fullOutputPath?: string;
+  [key: string]: unknown;
+}
+
+interface ToolResultEventResult { content?: Array<{ type: "text"; text: string }>; details?: unknown; isError?: boolean; }
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function tailUtf8(text: string, maxBytes: number): string {
+  const bytes = Buffer.from(text, "utf8");
+  let start = Math.max(0, bytes.length - maxBytes);
+  while (start < bytes.length && (bytes[start] & 0xc0) === 0x80) start++;
+  return new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(start));
+}
+
+function validSpillPath(path: string): boolean {
+  const root = resolve(tmpdir());
+  const resolved = resolve(path);
+  return dirname(resolved) === root && /^pi-(?:bash|powershell)-[0-9a-f]{16}\.log$/i.test(basename(resolved));
+}
+
+function shellCommand(event: ToolResultEvent): string | undefined {
+  if (!isBashToolResult(event) && !isPowerShellToolResult(event)) return undefined;
+  return typeof event.input.command === "string" ? event.input.command : undefined;
+}
+
+function isTarget(event: ToolResultEvent, policy: ManagedToolPolicy): boolean {
+  const command = shellCommand(event);
+  return command !== undefined && policy.isManagedCommand(command);
+}
+
+async function capture(event: ToolResultEvent): Promise<{ stdout: string; stderr: string; captureComplete: boolean } | undefined> {
+  const details = record(event.details) as AxiHookDetails | undefined;
+  const incomplete = details?.truncation?.truncated === true;
+  const nativeText = event.content[0]?.type === "text" ? event.content[0].text : "";
+  const hasSpillPath = details !== undefined && Object.hasOwn(details, "fullOutputPath");
+  if (hasSpillPath && (typeof details?.fullOutputPath !== "string" || !validSpillPath(details.fullOutputPath))) return undefined;
+  // A native error can omit its spill path from details, but a supplied path still
+  // contains useful output. Keep the thrown diagnostic as the recoverable stderr.
+  if (event.isError && typeof details?.fullOutputPath !== "string") return undefined;
+  if ((isBashToolResult(event) || isPowerShellToolResult(event)) && typeof details?.fullOutputPath === "string") {
+    let file: Awaited<ReturnType<typeof open>> | undefined;
+    try {
+      file = await open(details.fullOutputPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+      const stat = await file.stat();
+      if (!stat.isFile() || stat.size === 0 || stat.size > MAX_CAPTURE_BYTES) return undefined;
+      const chunks: Buffer[] = [];
+      let position = 0;
+      while (position < stat.size) {
+        const length = Math.min(64 * 1024, stat.size - position);
+        const buffer = Buffer.allocUnsafe(length);
+        const read = await file.read(buffer, 0, length, position);
+        if (read.bytesRead !== length) return undefined;
+        chunks.push(buffer);
+        position += read.bytesRead;
+      }
+      const after = await file.stat();
+      if (after.size !== stat.size) return undefined;
+      return {
+        stdout: new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)),
+        stderr: event.isError ? nativeText : "",
+        captureComplete: true,
+      };
+    } catch {
+      return undefined;
+    } finally {
+      await file?.close().catch(() => undefined);
+    }
+  }
+  if (incomplete) return undefined;
+  return { stdout: nativeText, stderr: "", captureComplete: true };
+}
+
+function chooseFormat(stdout: string, stderr: string): { full: string; format: "json" | "text" } {
+  if (!stdout.trim()) return { full: formatCapture(stdout, stderr, "text").full, format: "text" };
+  const json = formatCapture(stdout, stderr, "json");
+  if (!json.warning && Buffer.byteLength(json.full) < Buffer.byteLength(stdout)) return { full: json.full, format: "json" };
+  return { full: formatCapture(stdout, stderr, "text").full, format: "text" };
+}
+
+function hookDetails(original: unknown, reference: ResultReference, previewComplete: boolean) {
+  return {
+    ...(record(original) ?? {}),
+    axi: {
+      result: reference.id,
+      stream: "formatted" as const,
+      bytes: reference.bytes,
+      captureComplete: reference.captureComplete,
+      previewComplete,
+    },
+  };
+}
+
+export async function compactAxiToolResult(event: ToolResultEvent, append: (reference: ResultReference) => void, policy: ManagedToolPolicy = createManagedToolPolicy()): Promise<ToolResultEventResult | undefined> {
+  if (!isTarget(event, policy) || event.content.length !== 1 || event.content[0]?.type !== "text") return undefined;
+  const captured = await capture(event);
+  if (!captured) return undefined;
+  const { stdout, stderr, captureComplete } = captured;
+  const chosen = chooseFormat(stdout, stderr);
+  const preview = truncateUtf8(chosen.full, PREVIEW_BYTES, PREVIEW_LINES);
+  const changed = !captureComplete || chosen.full !== stdout || preview !== chosen.full;
+  if (!changed) return undefined;
+  if (captureComplete && preview === chosen.full && Buffer.byteLength(stdout) - Buffer.byteLength(chosen.full) < FOOTER_SLACK) return undefined;
+
+  let reference: ResultReference;
+  try {
+    reference = await saveResult({
+      command: event.toolName,
+      format: chosen.format,
+      stdout,
+      stderr,
+      formatted: chosen.full,
+      captureComplete,
+      append,
+    });
+  } catch {
+    return undefined;
+  }
+  const errorSummary = event.isError && stderr ? JSON.stringify(tailUtf8(stderr, 512)) : undefined;
+  const footerBase = (previewComplete: boolean) =>
+    `\n\n[axi result=${reference.id} captureComplete=${captureComplete} previewComplete=${previewComplete}${errorSummary ? ` error=${errorSummary}` : ""}; call axi_read with {"result":"${reference.id}","stream":"formatted"}]`;
+  const fits = Buffer.byteLength(chosen.full + footerBase(true)) <= PREVIEW_BYTES && (chosen.full + footerBase(true)).split("\n").length <= PREVIEW_LINES;
+  const footer = footerBase(fits);
+  const body = fits ? chosen.full : truncateUtf8(chosen.full, PREVIEW_BYTES - Buffer.byteLength(footer), PREVIEW_LINES - 5);
+  const text = body + footer;
+  const previewComplete = fits && Buffer.byteLength(text) <= PREVIEW_BYTES && text.split("\n").length <= PREVIEW_LINES;
+  return {
+    content: [{ type: "text", text }],
+    details: hookDetails(event.details, reference, previewComplete),
+    isError: event.isError,
+  };
+}
+
+export function registerAxiHook(pi: ExtensionAPI, policy: ManagedToolPolicy = createManagedToolPolicy()): void {
+  pi.on("tool_result", async (event, _ctx) => compactAxiToolResult(event, (reference) => pi.appendEntry("axi-result", reference), policy));
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerAxiTools } from "./core.ts";
+import { registerAxiHook } from "./hook.ts";
+import { createAgentReachBackend } from "./backends/agent-reach.ts";
+import { createOpenCliBackend } from "./backends/opencli.ts";
+import { createManagedToolPolicy, loadManagedSettings } from "./managed-tools.ts";
+import { registerAxiSettings } from "./settings.ts";
+
+export default async function (pi: ExtensionAPI) {
+  const policy = createManagedToolPolicy(await loadManagedSettings());
+  registerAxiHook(pi, policy);
+  registerAxiSettings(pi, policy);
+  registerAxiTools(pi, [createAgentReachBackend(), createOpenCliBackend()]);
+}

package/src/managed-tools.ts

@@ -0,0 +1,135 @@
+import { constants } from "node:fs";
+import { access, chmod, mkdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+// Built-ins plus original command names from the community AXI catalog at github.com/kunchenguid/axi#community.
+export const MANAGED_TOOL_CANDIDATES = [
+  "agent-reach", "opencli", "curl", "mcporter", "gh", "bili", "yt-dlp", "python", "python3",
+  "jj", "npm", "sqlite", "slack", "gws", "harvest", "specops",
+  "gitsheets", "metabase", "otter", "notion", "clickup", "databricks",
+  "aws", "docker", "doctl", "dynamodb", "pg", "mongodb", "elasticsearch",
+  "kubernetes", "redis", "celery", "cyber-mux", "oracle", "glab", "reactive",
+  "obsidian", "comfy-cloud", "mobbin", "calendly", "remarkable", "ado",
+  "supabase", "homebrew", "pypi", "cargo", "forgejo", "mastra", "axi",
+  "jira", "confluence", "az", "mssql", "superbee", "figma", "trello",
+  "railway", "netlify", "vercel", "cloudflare", "coolify", "porkbun",
+  "wrangler", "chezmoi", "mem", "fal", "canva", "ha",
+] as const;
+
+const CANDIDATE_NAMES = new Set<string>(MANAGED_TOOL_CANDIDATES);
+
+export interface ManagedSettings {
+  managedTools: string[];
+}
+
+export interface DetectedTool {
+  name: string;
+  path: string;
+  detected: boolean;
+  managed: boolean;
+}
+
+export interface ManagedToolPolicy {
+  getManagedTools(): string[];
+  setManagedTools(names: Iterable<string>): void;
+  isManagedCommand(command: string): boolean;
+}
+
+function normalize(names: Iterable<string>): string[] {
+  return [...new Set([...names].filter((name) => CANDIDATE_NAMES.has(name)))];
+}
+
+export function commandParts(command: string): string[] | undefined {
+  const trimmed = command.trim();
+  if (!trimmed || ["|", "&", ";", "`", "$", "(", ")", "<", ">", "\n", "\r", "\0"].some((token) => trimmed.includes(token))) return undefined;
+  const parts = trimmed.split(/\s+/);
+  let first = 0;
+  while (/^[A-Za-z_][A-Za-z0-9_]*=/.test(parts[first] ?? "")) first++;
+  return parts.slice(first);
+}
+
+function executableName(command: string): string | undefined {
+  const parts = commandParts(command);
+  const executable = parts?.[0];
+  return executable?.split(/[\\/]/).pop()?.replace(/\.exe$/i, "").toLowerCase();
+}
+
+export function isManagedCommand(command: string, settings: ManagedSettings | ManagedToolPolicy): boolean {
+  const name = executableName(command);
+  if (!name) return false;
+  const managed = "getManagedTools" in settings ? settings.getManagedTools() : settings.managedTools;
+  return managed.includes(name);
+}
+
+export function createManagedToolPolicy(settings: ManagedSettings = { managedTools: [] }): ManagedToolPolicy {
+  let managedTools = normalize(settings.managedTools);
+  return {
+    getManagedTools: () => [...managedTools],
+    setManagedTools(names) { managedTools = normalize(names); },
+    isManagedCommand(command) { return isManagedCommand(command, { managedTools }); },
+  };
+}
+
+function settingsDirectory(env: NodeJS.ProcessEnv = process.env): string {
+  const configured = env.PI_CODING_AGENT_DIR;
+  if (!configured) return join(homedir(), ".pi", "agent");
+  if (configured === "~") return homedir();
+  if (configured.startsWith("~/") || configured.startsWith("~\\")) return join(homedir(), configured.slice(2));
+  return configured;
+}
+
+export function managedSettingsPath(env: NodeJS.ProcessEnv = process.env): string {
+  return join(settingsDirectory(env), "pi-managed-axi.json");
+}
+
+export async function loadManagedSettings(env: NodeJS.ProcessEnv = process.env): Promise<ManagedSettings> {
+  try {
+    const value: unknown = JSON.parse(await readFile(managedSettingsPath(env), "utf8"));
+    if (!value || typeof value !== "object" || !Array.isArray((value as { managedTools?: unknown }).managedTools)) return { managedTools: [] };
+    return { managedTools: normalize((value as { managedTools: unknown[] }).managedTools.filter((name): name is string => typeof name === "string")) };
+  } catch {
+    return { managedTools: [] };
+  }
+}
+
+export async function saveManagedSettings(settings: ManagedSettings, env: NodeJS.ProcessEnv = process.env): Promise<void> {
+  const path = managedSettingsPath(env);
+  const directory = settingsDirectory(env);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  await chmod(directory, 0o700);
+  const temporary = join(directory, ".pi-managed-axi-" + randomUUID() + ".tmp");
+  try {
+    await writeFile(temporary, JSON.stringify({ managedTools: normalize(settings.managedTools) }, null, 2) + "\n", { encoding: "utf8", mode: 0o600, flag: "wx" });
+    await chmod(temporary, 0o600);
+    await rename(temporary, path);
+    await chmod(path, 0o600);
+  } finally {
+    await unlink(temporary).catch(() => undefined);
+  }
+}
+
+async function findOnPath(name: string, env: NodeJS.ProcessEnv): Promise<string | undefined> {
+  for (const directory of (env.PATH ?? "").split(delimiter).filter(Boolean)) {
+    const candidates = process.platform === "win32" ? [name, ...(env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";").map((extension) => name + extension)] : [name];
+    for (const candidate of candidates) {
+      const path = join(directory, candidate);
+      try {
+        await access(path, constants.X_OK);
+        if ((await stat(path)).isFile()) return path;
+      } catch { /* continue */ }
+    }
+  }
+  return undefined;
+}
+
+export async function discoverManagedTools(env: NodeJS.ProcessEnv = process.env): Promise<DetectedTool[]> {
+  const tools: DetectedTool[] = [];
+  const settings = await loadManagedSettings(env);
+  for (const name of MANAGED_TOOL_CANDIDATES) {
+    const path = await findOnPath(name, env);
+    if (path) tools.push({ name, path, detected: true, managed: settings.managedTools.includes(name) });
+  }
+  return tools;
+}

package/src/results.ts

@@ -0,0 +1,164 @@
+import { chmod, mkdtemp, open, writeFile, lstat } from "node:fs/promises";
+import { constants } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join, relative, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+
+export type ResultStream = "stdout" | "stderr" | "formatted";
+
+export interface ResultReference {
+  id: string;
+  command: string;
+  format: "json" | "text";
+  stdoutPath: string;
+  stderrPath: string;
+  formattedPath: string;
+  bytes: { stdout: number; stderr: number; formatted: number };
+  captureComplete: boolean;
+}
+
+export interface Page {
+  text: string;
+  offset: number;
+  bytes: number;
+  totalBytes: number;
+  nextOffset: number | null;
+  eof: boolean;
+}
+
+export function readPage(data: Buffer, options: { offset?: number; limit?: number; maxLines?: number } = {}): Page {
+  const offset = options.offset ?? 0;
+  const limit = options.limit ?? 8192;
+  const maxLines = options.maxLines ?? 200;
+  if (!Number.isSafeInteger(offset) || offset < 0 || offset > data.length) throw new Error("invalid byte offset");
+  if (!Number.isSafeInteger(limit) || limit < 4 || limit > 32 * 1024) throw new Error("limit must be between 4 and 32768 bytes");
+  if (offset < data.length && (data[offset] & 0xc0) === 0x80) throw new Error("offset is inside a UTF-8 character");
+  let end = Math.min(data.length, offset + limit);
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  while (end > offset) {
+    try {
+      const text = decoder.decode(data.subarray(offset, end));
+      const newlinePositions: number[] = [];
+      for (let i = 0; i < text.length; i++) if (text.charCodeAt(i) === 10) newlinePositions.push(i);
+      const lineCount = text.endsWith("\n") ? newlinePositions.length : newlinePositions.length + 1;
+      if (lineCount > maxLines) {
+        const chars = newlinePositions[maxLines - 1] + 1;
+        end = offset + Buffer.byteLength(text.slice(0, chars));
+        continue;
+      }
+      const bytes = end - offset;
+      return { text, offset, bytes, totalBytes: data.length, nextOffset: end < data.length ? end : null, eof: end >= data.length };
+    } catch {
+      end--;
+    }
+  }
+  if (offset < data.length) throw new Error("artifact contains invalid UTF-8");
+  return { text: "", offset, bytes: 0, totalBytes: data.length, nextOffset: null, eof: true };
+}
+
+function safePath(path: string, root: string, expectedName: string) {
+  const temp = resolve(tmpdir());
+  const directory = resolve(root);
+  const resolved = resolve(path);
+  const relativeTemp = relative(temp, directory);
+  if (!relativeTemp || relativeTemp.startsWith("..") || !basename(directory).startsWith("axi-result-") || resolved !== join(directory, expectedName)) throw new Error("result expired or missing");
+  return resolved;
+}
+
+async function writePrivate(path: string, content: string) {
+  await writeFile(path, content, { encoding: "utf8", mode: 0o600, flag: "wx" });
+  await chmod(path, 0o600);
+}
+
+export async function saveResult(input: {
+  command: string;
+  format: "json" | "text";
+  stdout: string;
+  stderr: string;
+  formatted: string;
+  captureComplete: boolean;
+  append: (reference: ResultReference) => void;
+}): Promise<ResultReference> {
+  const directory = await mkdtemp(join(tmpdir(), "axi-result-"));
+  await chmod(directory, 0o700);
+  const id = randomUUID();
+  const reference: ResultReference = {
+    id,
+    command: input.command,
+    format: input.format,
+    stdoutPath: join(directory, "stdout"),
+    stderrPath: join(directory, "stderr"),
+    formattedPath: join(directory, "formatted"),
+    bytes: { stdout: Buffer.byteLength(input.stdout), stderr: Buffer.byteLength(input.stderr), formatted: Buffer.byteLength(input.formatted) },
+    captureComplete: input.captureComplete,
+  };
+  try {
+    await Promise.all([
+      writePrivate(reference.stdoutPath, input.stdout),
+      writePrivate(reference.stderrPath, input.stderr),
+      writePrivate(reference.formattedPath, input.formatted),
+    ]);
+    input.append(reference);
+    return reference;
+  } catch (error) {
+    throw new Error(`could not save AXI result: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function isReference(value: unknown): value is ResultReference {
+  if (!value || typeof value !== "object") return false;
+  const reference = value as Partial<ResultReference>;
+  const bytes = reference.bytes;
+  return typeof reference.id === "string" && /^[-0-9a-f]{36}$/.test(reference.id)
+    && typeof reference.command === "string" && (reference.format === "json" || reference.format === "text")
+    && typeof reference.stdoutPath === "string" && typeof reference.stderrPath === "string" && typeof reference.formattedPath === "string"
+    && !!bytes && ["stdout", "stderr", "formatted"].every((key) => Number.isSafeInteger(bytes[key as keyof typeof bytes]) && bytes[key as keyof typeof bytes] >= 0)
+    && typeof reference.captureComplete === "boolean";
+}
+
+export function findResult(entries: unknown[], id: string): ResultReference | undefined {
+  // ponytail: linear session-entry scan; add an index only if lookup cost is measurable.
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object") continue;
+    const item = entry as { type?: string; customType?: string; data?: unknown };
+    if (item.type !== "custom" || item.customType !== "axi-result") continue;
+    if (isReference(item.data) && item.data.id === id) return item.data;
+  }
+  return undefined;
+}
+
+export async function readResultPage(reference: ResultReference, stream: ResultStream, options: { offset?: number; limit?: number } = {}): Promise<Page> {
+  const paths = { stdout: reference.stdoutPath, stderr: reference.stderrPath, formatted: reference.formattedPath };
+  const path = paths[stream];
+  if (!reference.id || !/^[-0-9a-f]{36}$/.test(reference.id) || !Object.values(paths).every((item) => typeof item === "string")) throw new Error("result expired or missing");
+  const directories = Object.values(paths).map((item) => resolve(item, ".."));
+  if (new Set(directories).size !== 1) throw new Error("result expired or missing");
+  const safe = safePath(path, directories[0], stream);
+  const directoryStat = await lstat(directories[0]).catch(() => undefined);
+  const stat = await lstat(safe).catch(() => undefined);
+  if (!directoryStat || !directoryStat.isDirectory() || directoryStat.isSymbolicLink() || !stat || !stat.isFile() || stat.isSymbolicLink()) throw new Error("result expired or missing");
+  const handle = await open(safe, constants.O_RDONLY | constants.O_NOFOLLOW).catch(() => undefined);
+  if (!handle) throw new Error("result expired or missing");
+  try {
+    const initial = await handle.stat();
+    const totalBytes = initial.size;
+    const expectedBytes = reference.bytes[stream];
+    if (!initial.isFile() || totalBytes !== expectedBytes || totalBytes > 64 * 1024 * 1024) throw new Error("result expired or missing");
+    const offset = options.offset ?? 0;
+    if (!Number.isSafeInteger(offset) || offset < 0 || offset > totalBytes) throw new Error("invalid byte offset");
+    const length = Math.min(options.limit ?? 8192, totalBytes - offset);
+    const data = Buffer.alloc(length);
+    let position = 0;
+    while (position < length) {
+      const read = await handle.read(data, position, length - position, offset + position);
+      if (read.bytesRead === 0) throw new Error("result expired or missing");
+      position += read.bytesRead;
+    }
+    const final = await handle.stat();
+    if (final.size !== totalBytes) throw new Error("result expired or missing");
+    if (length > 0 && (data[0] & 0xc0) === 0x80) throw new Error("offset is inside a UTF-8 character");
+    const page = readPage(data, { ...options, offset: 0 });
+    return { ...page, offset, totalBytes, nextOffset: offset + page.bytes < totalBytes ? offset + page.bytes : null, eof: offset + page.bytes >= totalBytes };
+  }
+  finally { await handle.close(); }
+}

package/src/runner.ts

@@ -0,0 +1,80 @@
+import { execFile, type ExecFileException } from "node:child_process";
+
+export interface ProcessRequest {
+  executable: string;
+  argv: string[];
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  maxBuffer?: number;
+}
+
+export interface ProcessResult {
+  stdout: string;
+  stderr: string;
+  code: number | null;
+  captureComplete: boolean;
+  reason?: "exit" | "spawn" | "timeout" | "cancelled" | "overflow";
+  error?: string;
+}
+
+export function runProcess(request: ProcessRequest): Promise<ProcessResult> {
+  const timeoutMs = request.timeoutMs ?? 60_000;
+  // ponytail: 16 MiB per stream; use file streaming only when a real command needs more.
+  const maxBuffer = request.maxBuffer ?? 16 * 1024 * 1024;
+  return new Promise((resolve) => {
+    let done = false;
+    let timedOut = false;
+    let cancelled = Boolean(request.signal?.aborted);
+    let timer: NodeJS.Timeout | undefined;
+    const child = execFile(
+      request.executable,
+      request.argv,
+      {
+        shell: false,
+        encoding: "utf8",
+        timeout: 0,
+        killSignal: "SIGKILL",
+        maxBuffer,
+        signal: request.signal,
+      },
+      (error: ExecFileException | null, stdout, stderr) => {
+        done = true;
+        if (timer) clearTimeout(timer);
+        const err = error as (ExecFileException & { code?: string | number }) | null;
+        const overflow = err?.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER";
+        const reason = overflow ? "overflow" : timedOut ? "timeout" : cancelled || err?.name === "AbortError" || err?.code === "ABORT_ERR" ? "cancelled" : err ? (typeof err.code === "string" ? "spawn" : "exit") : "exit";
+        const code = typeof err?.code === "number" ? err.code : err && !overflow && reason === "exit" ? null : err ? null : 0;
+        resolve({
+          stdout: String(stdout ?? ""),
+          stderr: String(stderr ?? ""),
+          code,
+          captureComplete: !overflow && !timedOut && !cancelled && reason !== "spawn",
+          reason,
+          error: err?.message,
+        });
+      },
+    );
+    child.stdin?.end();
+    timer = setTimeout(() => {
+      if (done) return;
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, timeoutMs);
+    if (request.signal) {
+      const cancel = () => {
+        cancelled = true;
+        child.kill("SIGKILL");
+      };
+      if (request.signal.aborted) cancel();
+      else request.signal.addEventListener("abort", cancel, { once: true });
+    }
+  });
+}
+
+export function processError(result: ProcessResult): string {
+  if (result.reason === "spawn") return `executable unavailable: ${result.error ?? "spawn failed"}`;
+  if (result.reason === "timeout") return "command timed out";
+  if (result.reason === "cancelled") return "command cancelled";
+  if (result.reason === "overflow") return "command output exceeded the 16 MiB capture limit";
+  return result.code === null ? "command failed" : `command exited with code ${result.code}`;
+}

package/src/settings.ts

@@ -0,0 +1,322 @@
+import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { discoverManagedTools, saveManagedSettings, type DetectedTool, type ManagedToolPolicy } from "./managed-tools.ts";
+
+type Done = (result?: string[]) => void;
+
+function pad(text: string, width: number): string {
+  const clipped = truncateToWidth(text, Math.max(1, width), "…");
+  return clipped + " ".repeat(Math.max(0, width - visibleWidth(clipped)));
+}
+
+function frame(lines: string[], width: number, theme: Theme, title: string): string[] {
+  const inner = Math.max(1, width - 2);
+  const border = (value: string) => theme.fg("borderAccent", value);
+  const titleText = ` ${truncateToWidth(title, Math.max(1, inner - 6), "…")} `;
+  const titleWidth = visibleWidth(titleText);
+  const top = `${border("╭──")}${theme.fg("accent", theme.bold(titleText))}${border("─".repeat(Math.max(1, inner - 2 - titleWidth)))}${border("╮")}`;
+  const body = lines.map((line) => `${border("│")} ${pad(line, inner - 2)} ${border("│")}`);
+  return [top, ...body, `${border("╰")}${border("─".repeat(inner))}${border("╯")}`];
+}
+
+function fuzzyMatch(query: string, value: string): boolean {
+  let cursor = 0;
+  for (const character of query) {
+    cursor = value.indexOf(character, cursor);
+    if (cursor < 0) return false;
+    cursor += 1;
+  }
+  return true;
+}
+
+function hint(theme: Theme, key: string, label: string): string {
+  return `${theme.fg("accent", key)} ${theme.fg("dim", label)}`;
+}
+
+/**
+ * The old selector remains a small reusable checkbox component. The command
+ * uses ManagedToolSettingsOverlay below for the full settings experience.
+ */
+export class ManagedToolSelector {
+  private index = 0;
+  private readonly selected: Set<string>;
+  private readonly tools: DetectedTool[];
+  private readonly done: Done;
+  constructor(tools: DetectedTool[], selected: Iterable<string>, done: Done) {
+    this.tools = tools;
+    this.done = done;
+    this.selected = new Set(selected);
+  }
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.up)) this.index = Math.max(0, this.index - 1);
+    else if (matchesKey(data, Key.down)) this.index = Math.min(this.tools.length - 1, this.index + 1);
+    else if (data === " ") {
+      const name = this.tools[this.index]?.name;
+      if (name) this.selected.has(name) ? this.selected.delete(name) : this.selected.add(name);
+    } else if (matchesKey(data, Key.enter)) {
+      this.done([...this.selected]);
+    } else if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) this.done();
+  }
+  invalidate(): void {}
+  render(width: number): string[] {
+    const lines = ["", " AXI managed tools", "", "Space toggles • Enter saves • Esc cancels", ""];
+    for (const [index, tool] of this.tools.entries()) {
+      const cursor = index === this.index ? "▌" : " ";
+      const value = this.selected.has(tool.name) ? "[✓] on" : "[ ] off";
+      lines.push(`${cursor} ${tool.name} — ${value}  (${tool.path})`);
+    }
+    return lines.map((line) => line.length > width ? line.slice(0, width) : line);
+  }
+}
+
+export class ManagedToolSettingsOverlay {
+  private index = 0;
+  private search = "";
+  private confirming = false;
+  private confirmIndex = 0;
+  private saving = false;
+  private readonly selected: Set<string>;
+  private readonly initial: Set<string>;
+  private readonly tools: DetectedTool[];
+  private readonly done: Done;
+  private readonly tui: { requestRender?: () => void };
+  private readonly theme: Theme;
+  private readonly onSave?: (names: string[]) => void | Promise<void>;
+  private readonly onError?: (error: unknown) => void;
+
+  constructor(
+    tools: DetectedTool[],
+    selected: Iterable<string>,
+    done: Done,
+    tui: { requestRender?: () => void },
+    theme: Theme,
+    onSave?: (names: string[]) => void | Promise<void>,
+    onError?: (error: unknown) => void,
+  ) {
+    this.tools = tools;
+    this.initial = new Set(selected);
+    this.selected = new Set(selected);
+    this.done = done;
+    this.tui = tui;
+    this.theme = theme;
+    this.onSave = onSave;
+    this.onError = onError;
+  }
+
+  private visibleTools(): DetectedTool[] {
+    const query = this.search.trim().toLowerCase();
+    if (!query) return this.tools;
+    return this.tools.filter((tool) => fuzzyMatch(query, `${tool.name} ${tool.path}`.toLowerCase()));
+  }
+
+  private dirty(): boolean {
+    return this.selected.size !== this.initial.size || [...this.selected].some((name) => !this.initial.has(name));
+  }
+
+  private requestRender(): void {
+    this.tui.requestRender?.();
+  }
+
+  private async save(): Promise<void> {
+    if (this.saving) return;
+    const names = [...this.selected];
+    if (!this.onSave) {
+      this.done(names);
+      return;
+    }
+    this.saving = true;
+    this.requestRender();
+    try {
+      if (this.onSave) await this.onSave(names);
+      this.done(names);
+    } catch (error) {
+      this.saving = false;
+      this.onError?.(error);
+      this.requestRender();
+    }
+  }
+
+  private close(): void {
+    if (this.dirty()) {
+      this.confirming = true;
+      this.confirmIndex = 1;
+      this.requestRender();
+    } else {
+      this.done();
+    }
+  }
+
+  private toggle(): void {
+    const tool = this.visibleTools()[this.index];
+    if (!tool) return;
+    if (!tool.detected) {
+      if (this.selected.delete(tool.name)) this.requestRender();
+      return;
+    }
+    this.selected.has(tool.name) ? this.selected.delete(tool.name) : this.selected.add(tool.name);
+    this.requestRender();
+  }
+
+  handleInput(data: string): void {
+    if (this.saving) return;
+    if (this.confirming) {
+      if (matchesKey(data, Key.up) || matchesKey(data, Key.left) || matchesKey(data, Key.down) || matchesKey(data, Key.right)) {
+        this.confirmIndex = this.confirmIndex === 0 ? 1 : 0;
+        this.requestRender();
+      } else if (matchesKey(data, Key.enter) || data === " ") {
+        if (this.confirmIndex === 0) this.done();
+        else {
+          this.confirming = false;
+          this.requestRender();
+        }
+      } else if (data === "y" || data === "Y") this.done();
+      else if (data === "n" || data === "N" || matchesKey(data, Key.escape)) {
+        this.confirming = false;
+        this.requestRender();
+      }
+      return;
+    }
+
+    if (matchesKey(data, Key.up)) {
+      this.index = Math.max(0, this.index - 1);
+    } else if (matchesKey(data, Key.down)) {
+      this.index = Math.min(Math.max(0, this.visibleTools().length - 1), this.index + 1);
+    } else if (data === " ") {
+      this.toggle();
+      return;
+    } else if (matchesKey(data, Key.enter) || matchesKey(data, Key.ctrl("s"))) {
+      void this.save();
+      return;
+    } else if (matchesKey(data, Key.escape)) {
+      if (this.search) {
+        this.search = "";
+        this.index = 0;
+        this.requestRender();
+      } else this.close();
+      return;
+    } else if (matchesKey(data, Key.ctrl("c"))) {
+      this.close();
+      return;
+    } else if (matchesKey(data, Key.backspace) || matchesKey(data, Key.ctrl("h"))) {
+      this.search = this.search.slice(0, -1);
+      this.index = 0;
+    } else if (matchesKey(data, Key.ctrl("w"))) {
+      this.search = this.search.trimEnd().replace(/\\S+\\s*$/, "");
+      this.index = 0;
+    } else if (matchesKey(data, Key.ctrl("u"))) {
+      this.search = "";
+      this.index = 0;
+    } else if (data.length === 1 && data >= " " && data !== "\x7f") {
+      this.search += data;
+      this.index = 0;
+    }
+    this.requestRender();
+  }
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const contentWidth = Math.max(1, width - 4);
+    const visible = this.visibleTools();
+    const selectedCount = this.selected.size;
+    const lines: string[] = [
+      this.theme.fg("muted", "Select tools whose complete output AXI may capture."),
+      this.theme.fg("dim", "Nothing runs or installs. Changes apply after save."),
+      "",
+      this.theme.bg("toolPendingBg", pad(` > ${this.search || "type to filter tools"}`, contentWidth)),
+      "",
+    ];
+
+    if (visible.length === 0) {
+      lines.push(this.theme.fg("muted", "No matching tools."));
+    } else {
+      const valueWidth = 8;
+      const labelWidth = Math.max(1, contentWidth - valueWidth - 4);
+      const maxRows = 10;
+      const start = Math.min(Math.max(0, this.index - maxRows + 1), Math.max(0, visible.length - maxRows));
+      const rows = visible.slice(start, start + maxRows);
+      if (start > 0) lines.push(this.theme.fg("dim", "  ↑ more tools"));
+      for (const [offset, tool] of rows.entries()) {
+        const row = start + offset;
+        const focused = row === this.index;
+        const enabled = this.selected.has(tool.name);
+        const pointer = focused ? this.theme.fg("accent", "▌") : " ";
+        const name = focused ? this.theme.fg("text", tool.name) : this.theme.fg("muted", tool.name);
+        const value = !tool.detected
+          ? `[${this.theme.fg("warning", "✓")}] ${this.theme.fg("warning", "saved")}`
+          : enabled
+            ? `[${this.theme.fg(focused ? "accent" : "success", "✓")}] ${this.theme.fg(focused ? "accent" : "success", "on")}`
+            : `[${this.theme.fg(focused ? "accent" : "muted", " ")}] ${this.theme.fg(focused ? "accent" : "muted", "off")}`;
+        const line = `${pointer} ${pad(name, labelWidth)} ${value}`;
+        const detail = this.theme.fg("dim", `  ${tool.detected ? tool.path : "not detected on PATH · Space removes saved tool"}`);
+        lines.push(focused ? this.theme.bg("selectedBg", pad(line, contentWidth)) : line);
+        lines.push(focused ? this.theme.bg("selectedBg", pad(detail, contentWidth)) : detail);
+      }
+      if (start + rows.length < visible.length) lines.push(this.theme.fg("dim", "  ↓ more tools"));
+    }
+
+    lines.push("", this.theme.fg("dim", `${selectedCount} selected`));
+    if (this.saving) {
+      lines.push("", this.theme.fg("accent", "Saving settings…"));
+    } else if (this.confirming) {
+      lines.push("", this.theme.fg("warning", "Discard unsaved changes?"));
+      lines.push(`${this.confirmIndex === 0 ? "▶" : " "} Discard    ${this.confirmIndex === 1 ? "▶" : " "} Cancel`);
+      lines.push(hint(this.theme, "↑↓", "choose") + "  " + hint(this.theme, "enter", "confirm"));
+    } else {
+      lines.push("", [hint(this.theme, "↑↓", "move"), hint(this.theme, "space", "toggle"), hint(this.theme, "enter", "save"), hint(this.theme, "esc", this.dirty() ? "discard" : "close")].join(this.theme.fg("dim", " · ")));
+      if (this.search) lines.push(hint(this.theme, "ctrl+u", "clear search"));
+    }
+    return frame(lines.map((line) => truncateToWidth(line, contentWidth, "…")), width, this.theme, `AXI settings${this.dirty() ? " • unsaved" : ""}`);
+  }
+}
+
+export function registerAxiSettings(pi: ExtensionAPI, policy: ManagedToolPolicy, env: NodeJS.ProcessEnv = process.env): void {
+  const prefixMatch = (value: string, prefix: string): boolean => value.toLowerCase().startsWith(prefix.toLowerCase());
+  const subcommands = [{ value: "settings", label: "Open AXI managed tool settings" }];
+
+  pi.registerCommand("axi", {
+    description: "Configure which detected tools AXI manages. Subcommand: [settings] open settings",
+    getArgumentCompletions: (prefix: string) => subcommands.filter((item) =>
+      !prefix || prefixMatch(item.value, prefix) ||
+      (item.value === "settings" && (prefixMatch("st", prefix) || prefixMatch("configure", prefix))),
+    ),
+    handler: async (args, ctx) => {
+      const trimmed = args.trim();
+      if (trimmed !== "settings" && trimmed !== "configure") {
+        ctx.ui.notify("Usage: /axi settings", "error");
+        return;
+      }
+      if (ctx.mode !== "tui") {
+        ctx.ui.notify("/axi settings requires interactive mode", "error");
+        return;
+      }
+      const tools = await discoverManagedTools(env);
+      const detected = new Set(tools.map((tool) => tool.name));
+      for (const name of policy.getManagedTools()) {
+        if (!detected.has(name)) tools.push({ name, path: "not detected on PATH", detected: false, managed: true });
+      }
+      if (tools.length === 0) {
+        ctx.ui.notify("No allowlisted tools were detected on PATH", "info");
+        return;
+      }
+      const selected = await ctx.ui.custom<string[] | undefined>(
+        (tui, theme, _kb, done) => new ManagedToolSettingsOverlay(
+          tools,
+          policy.getManagedTools(),
+          done,
+          tui,
+          theme,
+        ),
+        { overlay: true, overlayOptions: { width: "72%", minWidth: 58, maxHeight: "85%", anchor: "center", margin: 2 } },
+      );
+      if (!selected) return;
+      try {
+        await saveManagedSettings({ managedTools: selected }, env);
+        policy.setManagedTools(selected);
+        ctx.ui.notify(`AXI now manages: ${selected.length ? selected.join(", ") : "none"}`, "info");
+      } catch (error) {
+        ctx.ui.notify(`Could not save AXI settings: ${error instanceof Error ? error.message : String(error)}`, "error");
+      }
+    },
+  });
+}