@oh-my-pi/pi-coding-agent 17.3.5 → 17.3.7

package/src/extensibility/extensions/runner.ts

@@ -19,6 +19,7 @@ import type { MemoryRuntimeContext } from "../../memory-backend";
 import { type Theme, theme } from "../../modes/theme/theme";
 import type { AsyncJobSnapshot } from "../../session/agent-session";
 import type { SessionManager } from "../../session/session-manager";
+import { addFileDeleteFallback, addFileWriteFallback } from "../../tools/file-write-fallback";
 import type { BranchHandler, NavigateTreeHandler, NewSessionHandler } from "../session-handler-types";
 import { ManagedTimers } from "./managed-timers";
 import { createExtensionModelQuery } from "./model-api";
@@ -375,10 +376,12 @@ export type SwitchSessionHandler = (sessionPath: string) => Promise<{ cancelled:
 export type ShutdownHandler = () => void;
 
 /**
- * Emit `session_shutdown` and clear timers owned by an extension runner.
+ * Emit `session_shutdown`, dispose file-write-fallback registrations, and clear
+ * timers owned by an extension runner.
  *
- * Returns whether any shutdown handlers were present. Timer cleanup runs even
- * when a handler fails so extension background work cannot outlive its host.
+ * Returns whether any shutdown handlers were present. Fallback disposal and timer
+ * cleanup run even when a handler fails so extension background work — and a
+ * fallback bound to this session's context — cannot outlive its host.
  */
 export async function emitSessionShutdownEvent(extensionRunner: ExtensionRunner | undefined): Promise<boolean> {
 	if (!extensionRunner) return false;
@@ -389,6 +392,7 @@ export async function emitSessionShutdownEvent(extensionRunner: ExtensionRunner
 		});
 		return true;
 	} finally {
+		extensionRunner.disposeFileFallbacks();
 		extensionRunner.clearManagedTimers();
 	}
 }
@@ -486,6 +490,23 @@ export class ExtensionRunner {
 	#managedTimers = new ManagedTimers((event, error, stack) =>
 		this.emitError({ extensionPath: "<timer>", event, error, stack }),
 	);
+	/**
+	 * Disposers for the trampolines installed via {@link addFileWriteFallback} and
+	 * {@link addFileDeleteFallback} — one per extension per seam it registered for.
+	 * Installed during {@link initialize} (after the UI/runtime context is live, so
+	 * the bound handler sees a working `ctx.ui`) and drained by
+	 * {@link disposeFileFallbacks} on session shutdown so a handler from a
+	 * torn-down session can never fire for a later one sharing the same process.
+	 *
+	 * Each trampoline re-reads its extension's handler list at call time rather than
+	 * closing over a snapshot, matching how `ext.handlers` is re-read on every emit,
+	 * so an extension that already had a handler for that seam at `initialize` picks
+	 * up later additions to it. A seam the extension registered NOTHING for gets no
+	 * trampoline at all, which keeps the registry empty for a host with no fallbacks;
+	 * the cost is that a first registration for that seam after `initialize` never
+	 * takes effect, which is why the API documents load-time registration.
+	 */
+	#fileFallbackDisposers: Array<() => void> = [];
 	/**
 	 * Dedup markers for `tool_call` emission, keyed `${toolCallId}:${toolName}`.
 	 * The agent loop emits `tool_call` at arg-prep time (before scheduling and
@@ -609,6 +630,18 @@ export class ExtensionRunner {
 		return this.sessionManager.getCwd();
 	}
 
+	/**
+	 * Stable id of the session this runner serves. Read through `sessionManager`
+	 * for the same reason as {@link cwd}: it is this session's own, never a
+	 * process-global, so a subagent runner reports itself and not its parent.
+	 *
+	 * Used to attribute a denied file write or delete to the session that issued
+	 * it, since the fallback registry those handlers live in is process-wide.
+	 */
+	get sessionId(): string {
+		return this.sessionManager.getSessionId();
+	}
+
 	initialize(
 		actions: ExtensionActions,
 		contextActions: ExtensionContextActions,
@@ -666,6 +699,75 @@ export class ExtensionRunner {
 		this.#mode = mode;
 		this.#initialized = true;
 
+		// Re-initialize (e.g. a mode switch rewiring UI/runtime actions) must not
+		// accumulate duplicate global registrations — drop the prior generation before
+		// installing this one's trampolines.
+		this.disposeFileFallbacks();
+		for (const ext of this.extensions) {
+			// Nothing registered by this extension means no trampoline, so a host with
+			// no fallback-registering extension leaves the seam genuinely empty and
+			// `hasFileWriteFallback()`/`hasFileDeleteFallback()` false — the invariant
+			// the whole feature rests on. Each seam is checked separately, so an
+			// extension that only brokers writes never appears in the delete registry.
+			if (ext.fileWriteFallbackHandlers.length === 0 && ext.fileDeleteFallbackHandlers.length === 0) continue;
+			// One trampoline per extension per seam, not per handler: the list is walked
+			// at mutation time so a handler this extension adds later still takes effect,
+			// and `createContext()` takes no extension argument, so within one invocation
+			// a single context is all any of this extension's handlers would have
+			// received anyway.
+			//
+			// The context is built PER INVOCATION rather than captured here, matching
+			// every other dispatch site. `createContext()` materializes `cwd` and
+			// `hasUI` as values, so a trampoline holding one context for the life of the
+			// session would keep handing handlers the workspace this runner initialized
+			// in — wrong the moment `SessionManager.moveTo()` relocates the session
+			// (`/move`), and a handler that scopes or prompts against `ctx.cwd` would
+			// then allow the old workspace and deny the new one. A denied mutation is a
+			// rare path, so the extra object costs nothing that matters.
+			//
+			// Isolation is per HANDLER, not per extension. The registry only sees one
+			// trampoline per extension, so a throw escaping this loop would advance the
+			// registry to the NEXT extension and skip every later handler this one
+			// registered — breaking both the documented "a throwing handler is skipped"
+			// contract and registration order for a backup-handler setup.
+			if (ext.fileWriteFallbackHandlers.length > 0) {
+				this.#fileFallbackDisposers.push(
+					addFileWriteFallback(async req => {
+						const ctx = this.createContext();
+						for (const handler of ext.fileWriteFallbackHandlers) {
+							try {
+								if (await handler(req, ctx)) return true;
+							} catch (error) {
+								logger.warn("Extension file write fallback handler threw; trying next handler", {
+									extension: ext.path,
+									error: error instanceof Error ? error.message : String(error),
+								});
+							}
+						}
+						return false;
+					}),
+				);
+			}
+			if (ext.fileDeleteFallbackHandlers.length > 0) {
+				this.#fileFallbackDisposers.push(
+					addFileDeleteFallback(async req => {
+						const ctx = this.createContext();
+						for (const handler of ext.fileDeleteFallbackHandlers) {
+							try {
+								if (await handler(req, ctx)) return true;
+							} catch (error) {
+								logger.warn("Extension file delete fallback handler threw; trying next handler", {
+									extension: ext.path,
+									error: error instanceof Error ? error.message : String(error),
+								});
+							}
+						}
+						return false;
+					}),
+				);
+			}
+		}
+
 		// Drain events buffered by emitCredentialDisabled() before initialize ran. The
 		// spread adds the `type` discriminator — `event` is the pi-ai shape (no `type`).
 		// Deferred by one microtask so callers that register an onError listener
@@ -1098,6 +1200,16 @@ export class ExtensionRunner {
 		this.#managedTimers.clearAll();
 	}
 
+	/**
+	 * Remove every file write and delete fallback this runner installed into the
+	 * process-wide registries. Called on session shutdown (and before reinstalling
+	 * on a re-{@link initialize}) so a handler bound to a torn-down session's
+	 * context can never fire for another session sharing this process.
+	 */
+	disposeFileFallbacks(): void {
+		for (const dispose of this.#fileFallbackDisposers.splice(0)) dispose();
+	}
+
 	createCommandContext(): ExtensionCommandContext {
 		return {
 			...this.createContext(),

package/src/extensibility/extensions/types.ts

@@ -76,6 +76,7 @@ import type {
 	WriteToolInput,
 } from "../../tools";
 import type { ApprovalMode } from "../../tools/approval";
+import type { FileDeleteFallbackHandler, FileWriteFallbackHandler } from "../../tools/file-write-fallback";
 import type { EventBus } from "../../utils/event-bus";
 import type {
 	AgentEndEvent,
@@ -1256,6 +1257,63 @@ export interface ExtensionAPI {
 	/** Register a tool that the LLM can call. */
 	registerTool<TParams extends TSchema = TSchema, TDetails = unknown>(tool: ToolDefinition<TParams, TDetails>): void;
 
+	/**
+	 * Register a fallback writer consulted when a native `write`/`edit` byte-write is
+	 * denied with a permission error (`EPERM`/`EACCES`/`EROFS`). Every other write
+	 * error is unaffected. Handlers run in registration order; the first one to
+	 * resolve `true` counts as the bytes being durably on disk, and the native tool
+	 * continues as if its own write had succeeded — including recording its file
+	 * snapshot under the real destination path, so a later hashline `edit` on that
+	 * path keeps working. Intended for a host embedding the agent inside a sandbox
+	 * that denies direct filesystem writes but exposes a privileged write channel.
+	 *
+	 * A denial that `Bun.write` masks as `ENOENT` — a write into a directory the host
+	 * may not create — also diverts here, with `req.dst`'s parent absent and the
+	 * handler responsible for creating it.
+	 *
+	 * `req.dst` is symlink-RESOLVED: the path the failed write itself acted on, not
+	 * the one the tool was given. A link anywhere in a lexical path redirects the
+	 * bytes while still passing a prefix allowlist, so treat `req.dst` as
+	 * authoritative. A destination that cannot be resolved is never brokered.
+	 *
+	 * Call this during extension load, like the other `register*` methods: handlers
+	 * are installed when the runner initializes, so an extension that has registered
+	 * none by then is skipped and a first registration made later never takes effect.
+	 *
+	 * The underlying registry is process-wide, so a handler may be consulted for a
+	 * denied write from any session in the process, not only its own.
+	 * `req.sessionId` names the session that issued the write and
+	 * `ctx.sessionManager.getSessionId()` names the handler's own; compare them
+	 * before prompting, because `ctx.ui` belongs to the latter. See
+	 * `docs/extensions.md`.
+	 */
+	registerFileWriteFallback(handler: FileWriteFallbackHandler): void;
+
+	/**
+	 * Register a fallback deleter consulted when a native `edit`/`apply_patch` unlink is
+	 * denied with a permission error (`EPERM`/`EACCES`/`EROFS`). Covers `edit`'s `REM`,
+	 * the source side of a hashline `MV`, and `apply_patch`'s delete op. Return `true`
+	 * once `dst` is gone from disk.
+	 *
+	 * A handler MUST remove `dst` with a plain unlink and MUST NOT fall back to a
+	 * recursive removal. `unlink` on a directory reports `EPERM` on Darwin, so the seam
+	 * checks the target before diverting — but when the target's own metadata is behind
+	 * the same boundary that denied the unlink, which is the common sandbox case, that
+	 * check cannot be resolved and `dst` may be a directory. `req.confirmedFile` says
+	 * which situation the handler is in.
+	 *
+	 * `req.dst` resolves every component ABOVE the last, for the same reason the
+	 * write seam resolves all of them; the last is left alone because `unlink`
+	 * removes a link rather than its target, so `req.dst` may name a link.
+	 *
+	 * Separate from {@link registerFileWriteFallback} on purpose. A write handler
+	 * brokers `req.content` to `req.dst`, so a delete request reaching it with no
+	 * content invites brokering an empty write and truncating the file instead of
+	 * removing it. Registering for deletes is therefore an explicit opt-in, and the
+	 * same load-time and process-wide notes above apply.
+	 */
+	registerFileDeleteFallback(handler: FileDeleteFallbackHandler): void;
+
 	// =========================================================================
 	// Command, Shortcut, Flag Registration
 	// =========================================================================
@@ -1632,6 +1690,8 @@ export interface Extension {
 	tools: Map<string, RegisteredTool<any, any>>;
 	toolRegistrationListeners?: Set<ToolRegistrationListener>;
 	assistantThinkingRenderers: AssistantThinkingRenderer[];
+	fileWriteFallbackHandlers: FileWriteFallbackHandler[];
+	fileDeleteFallbackHandlers: FileDeleteFallbackHandler[];
 	messageRenderers: Map<string, MessageRenderer>;
 	commands: Map<string, RegisteredCommand>;
 	flags: Map<string, ExtensionFlag>;

package/src/extensibility/extensions/wrapper.ts

@@ -14,6 +14,7 @@ import type { Settings } from "../../config/settings";
 import type { Theme } from "../../modes/theme/theme";
 import { type ApprovalMode, formatApprovalPrompt, resolveApproval, truncateForPrompt } from "../../tools/approval";
 import { defaultLoadModeForToolName } from "../../tools/essential-tools";
+import { withFileMutationSession } from "../../tools/file-write-fallback";
 import { normalizeToolEventInput, resolveToolEventInput } from "../tool-event-input";
 import { applyToolProxy } from "../tool-proxy";
 import type { ExtensionRunner } from "./runner";
@@ -349,7 +350,15 @@ export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetail
 		let executionError: Error | undefined;
 
 		try {
-			result = await this.tool.execute(toolCallId, effectiveParams, signal, onUpdate, context);
+			// A denied file write or delete inside this tool can be brokered to an
+			// extension handler, and that registry is PROCESS-WIDE — so the session is
+			// named here, the one place where every tool's execution and the runner
+			// that owns the handlers are both in scope (`sdk.ts` wraps the whole tool
+			// registry with this class whenever a runner exists). Inert with no
+			// fallback registered: no scope is entered.
+			result = await withFileMutationSession(this.runner.sessionId, () =>
+				this.tool.execute(toolCallId, effectiveParams, signal, onUpdate, context),
+			);
 		} catch (err) {
 			executionError = err instanceof Error ? err : new Error(String(err));
 			result = {

package/src/lsp/writethrough.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import { isEnoent, logger, once, untilAborted } from "@oh-my-pi/pi-utils";
 import type { BunFile } from "bun";
+import { isPermissionDeniedError, writeFileWithFallback } from "../tools/file-write-fallback";
 import { FileChangeType, notifyWorkspaceWatchedFiles } from "./client";
 import { getServersForFile } from "./config";
 import {
@@ -66,11 +67,7 @@ export async function writethroughNoop(
 	_batch?: LspWritethroughBatchRequest,
 	_getDeferred?: (dst: string) => WritethroughDeferredHandle | undefined,
 ): Promise<FileDiagnosticsResult | undefined> {
-	if (file) {
-		await file.write(content);
-	} else {
-		await Bun.write(dst, content);
-	}
+	await writeFileWithFallback(dst, content, file);
 	return undefined;
 }
 
@@ -78,6 +75,12 @@ interface PendingWritethrough {
 	dst: string;
 	file?: BunFile;
 	changeType: FileChangeType;
+	/**
+	 * The bytes this entry committed. The flush prefers a fresh read of `dst` so
+	 * post-processing sees whatever else in the batch touched the file, and falls
+	 * back to these when that read is denied.
+	 */
+	content: string;
 }
 
 interface RunLspWritethroughOptions {
@@ -288,7 +291,7 @@ async function runLspWritethrough(
 	const contentAlreadyWritten = runOptions?.contentAlreadyWritten ?? false;
 
 	let finalContent = content;
-	const writeContent = async (value: string) => (file ? file.write(value) : Bun.write(dst, value));
+	const writeContent = async (value: string) => writeFileWithFallback(dst, value, file);
 	const getWritePromise = once(() =>
 		contentAlreadyWritten && finalContent === content ? Promise.resolve() : writeContent(finalContent),
 	);
@@ -458,9 +461,16 @@ async function flushWritethroughBatch(
 		try {
 			content = await fs.promises.readFile(entry.dst, "utf8");
 		} catch (error) {
-			if (!isEnoent(error)) throw error;
-			bundle?.finalize(undefined);
-			continue;
+			if (isEnoent(error)) {
+				bundle?.finalize(undefined);
+				continue;
+			}
+			// A brokered write lands bytes this process may not be able to read
+			// back: a sandbox that denies the write commonly denies the read too.
+			// Failing here would fail a flush whose every write succeeded, so the
+			// content this entry committed stands in for the unreadable file.
+			if (!isPermissionDeniedError(error)) throw error;
+			content = entry.content;
 		}
 		const deferredInner =
 			bundle &&
@@ -552,7 +562,7 @@ export function createLspWritethrough(cwd: string, options?: WritethroughOptions
 		}
 
 		const state = getOrCreateWritethroughBatch(batch.id, resolvedOptions);
-		state.entries.set(dst, { dst, file, changeType });
+		state.entries.set(dst, { dst, file, changeType, content });
 		if (!batch.flush) return undefined;
 
 		writethroughBatches.delete(batch.id);

package/src/slash-commands/builtin-session.ts

@@ -336,7 +336,7 @@ export const BUILTIN_SESSION_SLASH_COMMANDS: ReadonlyArray<SlashCommandSpec> = [
 	{
 		name: "stats",
 		description: "Launch the local stats dashboard",
-		inlineHint: "[--port <port>]",
+		inlineHint: "[--port <port>] [--host <host>]",
 		allowArgs: true,
 		handle: async (command, runtime) => {
 			const parsed = parseStatsDashboardArgs(command.args);

package/src/slash-commands/helpers/stats-dashboard.ts

@@ -11,6 +11,7 @@ interface StatsDashboardServer {
 
 export interface StatsDashboardArgs {
 	port: number;
+	host: string;
 }
 
 export interface StatsDashboardLaunchResult {
@@ -20,7 +21,7 @@ export interface StatsDashboardLaunchResult {
 
 let activeStatsServer: StatsDashboardServer | undefined;
 
-const STATS_DASHBOARD_USAGE = "Usage: /stats [--port <port>]";
+const STATS_DASHBOARD_USAGE = "Usage: /stats [--port <port>] [--host <host>]";
 
 function parsePort(value: string | undefined): number | string {
 	if (!value) return `Missing port. ${STATS_DASHBOARD_USAGE}`;
@@ -33,6 +34,7 @@ function parsePort(value: string | undefined): number | string {
 export function parseStatsDashboardArgs(args: string): StatsDashboardArgs | { error: string } {
 	const tokens = args.split(/\s+/).filter(Boolean);
 	let port = DEFAULT_STATS_DASHBOARD_PORT;
+	let host = "127.0.0.1";
 
 	for (let i = 0; i < tokens.length; i++) {
 		const token = tokens[i];
@@ -48,28 +50,40 @@ export function parseStatsDashboardArgs(args: string): StatsDashboardArgs | { er
 			port = parsed;
 			continue;
 		}
+		if (token === "--host") {
+			const value = tokens[++i];
+			if (!value) return { error: `Missing host. ${STATS_DASHBOARD_USAGE}` };
+			host = value;
+			continue;
+		}
+		if (token.startsWith("--host=")) {
+			const value = token.slice("--host=".length);
+			if (!value) return { error: `Missing host. ${STATS_DASHBOARD_USAGE}` };
+			host = value;
+			continue;
+		}
 		return { error: `Unknown option: ${token}. ${STATS_DASHBOARD_USAGE}` };
 	}
 
-	return { port };
+	return { port, host };
 }
 
 export async function launchStatsDashboard(args: StatsDashboardArgs): Promise<StatsDashboardLaunchResult> {
 	const { processed, files } = await stats.syncAllSessions();
 	const total = await stats.getTotalMessageCount();
-	let requestedPortIgnored = false;
+	let requestedAddressIgnored = false;
 
 	if (!activeStatsServer) {
-		activeStatsServer = await stats.startServer(args.port);
-	} else if (args.port !== activeStatsServer.port) {
-		requestedPortIgnored = true;
+		activeStatsServer = await stats.startServer(args.port, args.host);
+	} else if (args.port !== activeStatsServer.port || args.host !== activeStatsServer.hostname) {
+		requestedAddressIgnored = true;
 	}
 
-	const url = `http://${activeStatsServer.hostname}:${activeStatsServer.port}`;
+	const url = stats.formatStatsDashboardUrl(activeStatsServer.hostname, activeStatsServer.port);
 	openUtils.openPath(url);
 
-	const serverLine = requestedPortIgnored
-		? `Dashboard already running at: ${url} (requested port ${args.port} ignored)`
+	const serverLine = requestedAddressIgnored
+		? `Dashboard already running at: ${url} (requested ${args.host}:${args.port} ignored)`
 		: `Dashboard available at: ${url}`;
 
 	return {