@oh-my-pi/pi-utils 18.12.5 → 18.12.6

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [18.12.6] - 2026-10-21
+
+### Added
+
+- Added `RpcConnection.requestCancellable()` and `Client.requestPermission(params, { signal })`; client connections abort a handler and answer `-32800` when the peer sends `$/cancel_request`, while agent connections keep running the request and return its real result ([#15885](https://github.com/can1357/oh-my-pi/pull/15885) by [@marcintustin](https://github.com/marcintustin))
+
 ## [18.12.4] - 2026-10-20
 
 ### Breaking Changes

package/dist/types/acp/connection.d.ts

@@ -7,7 +7,15 @@ export interface CreateTerminalResponse {
 }
 /** Client callbacks handled by a client-side connection. */
 export interface Client {
-    requestPermission(params: RequestPermissionRequest): MaybePromise<RequestPermissionResponse>;
+    /**
+     * Serve a permission elicit. `options.signal` aborts when the agent
+     * cancels the request (`$/cancel_request`) — e.g. user steering superseded
+     * the dialog — so a held handler can end instead of stranding the
+     * connection's clean-EOF drain.
+     */
+    requestPermission(params: RequestPermissionRequest, options?: {
+        signal?: AbortSignal;
+    }): MaybePromise<RequestPermissionResponse>;
     sessionUpdate(params: SessionNotification): MaybePromise<void>;
     readTextFile?(params: ReadTextFileRequest): MaybePromise<ReadTextFileResponse>;
     writeTextFile?(params: WriteTextFileRequest): MaybePromise<WriteTextFileResponse | void>;
@@ -45,6 +53,15 @@ export declare class AgentSideConnection {
     sessionUpdate(params: SessionNotification): Promise<void>;
     /** Requests permission from the client. */
     requestPermission(params: RequestPermissionRequest): Promise<RequestPermissionResponse>;
+    /**
+     * Requests permission from the client, returning a handle that cancels the
+     * pending wire request (`$/cancel_request`) — used when user steering
+     * supersedes an open permission dialog instead of waiting behind it.
+     */
+    requestPermissionWithCancel(params: RequestPermissionRequest): {
+        promise: Promise<RequestPermissionResponse>;
+        cancel(): void;
+    };
     /** Reads a client-side text file. */
     readTextFile(params: ReadTextFileRequest): Promise<ReadTextFileResponse>;
     /** Writes a client-side text file. */

package/dist/types/acp/transport.d.ts

@@ -69,17 +69,41 @@ export declare class RequestError extends Error {
     /** Converts this error into a JSON-RPC error payload. */
     toErrorResponse(): ErrorResponse;
 }
-type Dispatcher = (method: string, params: unknown, notification: boolean) => MaybePromise<unknown>;
+type Dispatcher = (method: string, params: unknown, notification: boolean, 
+/** Abort signal for an inbound *request*: fires when the peer cancels it via `$/cancel_request`. */
+signal?: AbortSignal) => MaybePromise<unknown>;
+/** Options for {@link RpcConnection}. */
+export interface RpcConnectionOptions {
+    /**
+     * The dispatcher honors the abort signal it receives for inbound requests.
+     * Only then does a peer `$/cancel_request` abort the handler and answer the
+     * request `-32800` immediately; otherwise the handler runs to completion and
+     * its real result is the response, since answering "cancelled" while the
+     * work keeps going would hide its outcome from the peer.
+     */
+    honorsInboundCancellation?: boolean;
+}
 /** Correlated bidirectional JSON-RPC connection. */
 export declare class RpcConnection {
     #private;
-    constructor(stream: Stream, dispatcher: Dispatcher);
+    constructor(stream: Stream, dispatcher: Dispatcher, options?: RpcConnectionOptions);
     /** Signal aborted when the stream closes. */
     get signal(): AbortSignal;
     /** Promise resolved when the stream closes. */
     get closed(): Promise<void>;
     /** Sends a correlated JSON-RPC request. */
     request<Response>(method: string, params?: unknown): Promise<Response>;
+    /**
+     * Sends a JSON-RPC request whose pending entry can be cancelled locally:
+     * `cancel()` rejects the promise with a request-cancelled error, notifies
+     * the peer via `$/cancel_request`, and drops the pending entry so a late
+     * response is ignored. Used for agent→client requests a mid-turn event can
+     * supersede (e.g. a permission elicit cancelled when user steering arrives).
+     */
+    requestCancellable<Response>(method: string, params?: unknown): {
+        promise: Promise<Response>;
+        cancel(): void;
+    };
     /** Sends a JSON-RPC notification. */
     notify(method: string, params?: unknown): Promise<void>;
     /** Closes the connection and rejects outstanding requests. */

package/dist/types/fs-open.d.ts

@@ -2,7 +2,8 @@
  * `fs.openSync` with close-on-exec, matching Node's default.
  *
  * libuv adds `O_CLOEXEC` inside `uv__fs_open`, so on Node every `fs` descriptor
- * dies at `exec`. Bun's `fs.open*` does not, and descriptors it returns survive
+ * dies at `exec`. Bun's `fs.open*` did not before 1.4.3 (still allowed by the
+ * `bun@>=1.4` pin), and descriptors it returns survive
  * into any child spawned through a path that does not close strays itself — the
  * bash tool's shell `fork`/`exec`s user commands and hands them the lot. Use
  * this for every descriptor kept open past such a spawn (session transcripts,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.12.5",
+	"version": "18.12.6",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"cli",
@@ -57,7 +57,7 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.12.5"
+		"@oh-my-pi/pi-natives": "18.12.6"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/acp/connection.ts

@@ -47,7 +47,16 @@ export interface CreateTerminalResponse {
 }
 /** Client callbacks handled by a client-side connection. */
 export interface Client {
-	requestPermission(params: RequestPermissionRequest): MaybePromise<RequestPermissionResponse>;
+	/**
+	 * Serve a permission elicit. `options.signal` aborts when the agent
+	 * cancels the request (`$/cancel_request`) — e.g. user steering superseded
+	 * the dialog — so a held handler can end instead of stranding the
+	 * connection's clean-EOF drain.
+	 */
+	requestPermission(
+		params: RequestPermissionRequest,
+		options?: { signal?: AbortSignal },
+	): MaybePromise<RequestPermissionResponse>;
 	sessionUpdate(params: SessionNotification): MaybePromise<void>;
 	readTextFile?(params: ReadTextFileRequest): MaybePromise<ReadTextFileResponse>;
 	writeTextFile?(params: WriteTextFileRequest): MaybePromise<WriteTextFileResponse | void>;
@@ -90,6 +99,17 @@ export class AgentSideConnection {
 	requestPermission(params: RequestPermissionRequest): Promise<RequestPermissionResponse> {
 		return this.#connection.request("session/request_permission", params);
 	}
+	/**
+	 * Requests permission from the client, returning a handle that cancels the
+	 * pending wire request (`$/cancel_request`) — used when user steering
+	 * supersedes an open permission dialog instead of waiting behind it.
+	 */
+	requestPermissionWithCancel(params: RequestPermissionRequest): {
+		promise: Promise<RequestPermissionResponse>;
+		cancel(): void;
+	} {
+		return this.#connection.requestCancellable<RequestPermissionResponse>("session/request_permission", params);
+	}
 	/** Reads a client-side text file. */
 	readTextFile(params: ReadTextFileRequest): Promise<ReadTextFileResponse> {
 		return this.#connection.request("fs/read_text_file", params);
@@ -168,10 +188,18 @@ export class ClientSideConnection {
 	#connection: RpcConnection;
 
 	constructor(toClient: (connection: ClientSideConnection) => Client, stream: Stream) {
-		this.#connection = new RpcConnection(stream, async (method, params, notification) => {
-			if (!client) throw RequestError.internalError(undefined, "Client is not initialized");
-			return dispatchClient(client, method, params, notification);
-		});
+		// Client handlers receive the cancel signal (`requestPermission`'s
+		// `options.signal`), so a peer `$/cancel_request` may answer `-32800`
+		// at once. The agent side keeps the default: its handlers ignore the
+		// signal, and `session/cancel` is ACP's cancellation path for prompts.
+		this.#connection = new RpcConnection(
+			stream,
+			async (method, params, notification, signal) => {
+				if (!client) throw RequestError.internalError(undefined, "Client is not initialized");
+				return dispatchClient(client, method, params, notification, signal);
+			},
+			{ honorsInboundCancellation: true },
+		);
 		const client = toClient(this);
 	}
 	/** Signal aborted when the transport closes. */
@@ -272,10 +300,11 @@ async function dispatchClient(
 	method: string,
 	params: unknown,
 	notification: boolean,
+	signal?: AbortSignal,
 ): Promise<unknown> {
 	switch (method) {
 		case "session/request_permission":
-			return client.requestPermission(params as RequestPermissionRequest);
+			return client.requestPermission(params as RequestPermissionRequest, { signal });
 		case "session/update":
 			return client.sessionUpdate(params as SessionNotification);
 		case "fs/read_text_file":
@@ -322,6 +351,9 @@ async function dispatchClient(
 				params as CompleteElicitationNotification,
 			);
 		default:
+			// The transport already aborted the matching inbound handler;
+			// like the agent side, the notification itself carries no work.
+			if (method === "$/cancel_request") return;
 			if (notification && client.extNotification)
 				return client.extNotification(method, params as Record<string, unknown>);
 			if (!notification && client.extMethod) return client.extMethod(method, params as Record<string, unknown>);

package/src/acp/transport.ts

@@ -105,9 +105,27 @@ function createStandardError(
 	return new RequestError(code, additionalMessage ? `${message}: ${additionalMessage}` : message, data);
 }
 
-type Dispatcher = (method: string, params: unknown, notification: boolean) => MaybePromise<unknown>;
+type Dispatcher = (
+	method: string,
+	params: unknown,
+	notification: boolean,
+	/** Abort signal for an inbound *request*: fires when the peer cancels it via `$/cancel_request`. */
+	signal?: AbortSignal,
+) => MaybePromise<unknown>;
 type Pending = { resolve(value: unknown): void; reject(reason: unknown): void };
 
+/** Options for {@link RpcConnection}. */
+export interface RpcConnectionOptions {
+	/**
+	 * The dispatcher honors the abort signal it receives for inbound requests.
+	 * Only then does a peer `$/cancel_request` abort the handler and answer the
+	 * request `-32800` immediately; otherwise the handler runs to completion and
+	 * its real result is the response, since answering "cancelled" while the
+	 * work keeps going would hide its outcome from the peer.
+	 */
+	honorsInboundCancellation?: boolean;
+}
+
 /** Bound on clean-EOF inbound drain so `closed` cannot hang if a handler never settles. */
 const INBOUND_DRAIN_TIMEOUT_MS = 30_000;
 
@@ -117,15 +135,18 @@ export class RpcConnection {
 	#pending = new Map<JsonRpcId, Pending>();
 	#inbound = new Set<Promise<void>>();
 	#openInboundIds = new Set<JsonRpcId>();
+	/** Abort controller per inbound request, fired by a peer `$/cancel_request` (opt-in). */
+	#inboundCancellers: Map<JsonRpcId, AbortController> | undefined;
 	#writable: WritableStream<AnyMessage>;
 	#writeTail: Promise<void> = Promise.resolve();
 	#abort = new AbortController();
 	#closed = Promise.withResolvers<void>();
 	#dispatcher: Dispatcher;
 
-	constructor(stream: Stream, dispatcher: Dispatcher) {
+	constructor(stream: Stream, dispatcher: Dispatcher, options?: RpcConnectionOptions) {
 		this.#writable = stream.writable;
 		this.#dispatcher = dispatcher;
+		this.#inboundCancellers = options?.honorsInboundCancellation ? new Map() : undefined;
 		void this.#read(stream.readable);
 	}
 
@@ -141,6 +162,48 @@ export class RpcConnection {
 	/** Sends a correlated JSON-RPC request. */
 	request<Response>(method: string, params?: unknown): Promise<Response> {
 		if (this.signal.aborted) return Promise.reject(new Error("Connection closed"));
+		return this.#beginRequest(method, params).deferred.promise as Promise<Response>;
+	}
+
+	/**
+	 * Sends a JSON-RPC request whose pending entry can be cancelled locally:
+	 * `cancel()` rejects the promise with a request-cancelled error, notifies
+	 * the peer via `$/cancel_request`, and drops the pending entry so a late
+	 * response is ignored. Used for agent→client requests a mid-turn event can
+	 * supersede (e.g. a permission elicit cancelled when user steering arrives).
+	 */
+	requestCancellable<Response>(
+		method: string,
+		params?: unknown,
+	): {
+		promise: Promise<Response>;
+		cancel(): void;
+	} {
+		if (this.signal.aborted) {
+			return {
+				promise: Promise.reject(new Error("Connection closed")),
+				cancel: () => {},
+			};
+		}
+		const { id, deferred } = this.#beginRequest(method, params);
+		return {
+			promise: deferred.promise as Promise<Response>,
+			cancel: () => {
+				if (!this.#pending.delete(id)) return;
+				deferred.reject(RequestError.requestCancelled({ requestId: id, method }));
+				void this.notify("$/cancel_request", { requestId: id }).catch(() => undefined);
+			},
+		};
+	}
+
+	/** Shared request plumbing: allocate an id, register the pending entry, write the frame. */
+	#beginRequest(
+		method: string,
+		params: unknown,
+	): {
+		id: number;
+		deferred: { promise: Promise<unknown>; resolve: (value?: unknown) => void; reject: (reason?: unknown) => void };
+	} {
 		const id = this.#nextId++;
 		const deferred = Promise.withResolvers<unknown>();
 		this.#pending.set(id, deferred);
@@ -148,7 +211,7 @@ export class RpcConnection {
 			this.#pending.delete(id);
 			deferred.reject(error);
 		});
-		return deferred.promise as Promise<Response>;
+		return { id, deferred };
 	}
 
 	/** Sends a JSON-RPC notification. */
@@ -235,6 +298,18 @@ export class RpcConnection {
 		}
 		if (!("method" in message)) return;
 		if (!("id" in message)) {
+			// ACP v1 names the cancelled request `requestId`. A cancelled
+			// inbound request must still be answered (spec: result or
+			// `-32800`): the handler is aborted and the error response is
+			// written here, so a late-settling handler lands in `#respond`'s
+			// closed-id no-op instead of answering a request the peer gave
+			// up on.
+			if (message.method === "$/cancel_request" && this.#inboundCancellers) {
+				this.#cancelInbound(
+					this.#inboundCancellers,
+					(message.params as { requestId?: JsonRpcId } | undefined)?.requestId,
+				);
+			}
 			try {
 				await this.#dispatcher(message.method, message.params, true);
 			} catch {
@@ -242,8 +317,11 @@ export class RpcConnection {
 			}
 			return;
 		}
+		const cancellers = this.#inboundCancellers;
+		const canceller = cancellers ? new AbortController() : undefined;
+		if (canceller) cancellers?.set(message.id, canceller);
 		try {
-			const result = await this.#dispatcher(message.method, message.params, false);
+			const result = await this.#dispatcher(message.method, message.params, false, canceller?.signal);
 			await this.#respond(message.id, { result: result ?? {} });
 		} catch (error) {
 			const protocolError =
@@ -251,6 +329,25 @@ export class RpcConnection {
 					? error
 					: RequestError.internalError({ details: error instanceof Error ? error.message : String(error) });
 			await this.#respond(message.id, { error: protocolError.toErrorResponse() });
+		} finally {
+			cancellers?.delete(message.id);
 		}
 	}
+
+	#cancelInbound(cancellers: Map<JsonRpcId, AbortController>, id: JsonRpcId | undefined): void {
+		if (id === undefined) return;
+		const canceller = cancellers.get(id);
+		if (canceller) {
+			cancellers.delete(id);
+			canceller.abort(RequestError.requestCancelled({ requestId: id }));
+		}
+		// Spec: a cancelled request still gets a response. Answer `-32800`
+		// here — synchronously with the notification — so the peer is never
+		// left waiting on a handler that may never settle. `#respond` closes
+		// the id, so a late handler result (a handler that ignored its abort
+		// signal) lands in the closed-id no-op instead of answering twice.
+		void this.#respond(id, { error: RequestError.requestCancelled({ requestId: id }).toErrorResponse() }).catch(
+			() => undefined,
+		);
+	}
 }

package/src/fs-open.ts

@@ -15,7 +15,8 @@ const O_CLOEXEC = process.platform === "linux" ? 0o2000000 : process.platform ==
  * `fs.openSync` with close-on-exec, matching Node's default.
  *
  * libuv adds `O_CLOEXEC` inside `uv__fs_open`, so on Node every `fs` descriptor
- * dies at `exec`. Bun's `fs.open*` does not, and descriptors it returns survive
+ * dies at `exec`. Bun's `fs.open*` did not before 1.4.3 (still allowed by the
+ * `bun@>=1.4` pin), and descriptors it returns survive
  * into any child spawned through a path that does not close strays itself — the
  * bash tool's shell `fork`/`exec`s user commands and hands them the lot. Use
  * this for every descriptor kept open past such a spawn (session transcripts,