@linxiraos/pi-utils 1.4.0 → 1.4.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [1.4.2] - 2026-10-24
+
+- Added `ZETA_WEB_PORT` (43141), `ZETA_GATEWAY_PORT` (43143) and `ZETA_STATS_PORT` (43147) as the single source for Zeta's local service defaults
+
+## [1.4.1] - 2026-10-23
+
+- Version alignment with the 1.4.1 release line (no behavioral changes).
+
 ## [1.4.0] - 2026-10-21
 
 - Version line moves to 1.4.0 with the rest of the suite; no user-visible change in this package.

package/README.md

@@ -6,7 +6,7 @@ Shared utilities for [omp](https://github.com/can1357/oh-my-pi) packages. Zero c
 
 | Module                                                                                                             | Purpose                                                                                      |
 | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
-| `logger`                                                                                                           | Centralized logger writing to `~/.zeta/logs/` with rotation (TUI-safe — never stdout)         |
+| `logger`                                                                                                           | Centralized logger writing to `~/.zeta/logs/` (`bun test`: temp dir), rotating, never stdout  |
 | `prompt`                                                                                                           | Handlebars-based prompt templating and formatting helpers                                    |
 | `dirs`                                                                                                             | Path helpers for zetacode config directories (`~/.zeta`, XDG-aware on Linux)                       |
 | `stream`                                                                                                           | `readStream` / `readLines` helpers over `ReadableStream`                                     |

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/ar/codecs/gzip.d.ts

@@ -1,6 +1,9 @@
+import { type ByteSource } from "../source.js";
 /** gzip magic: 0x1f 0x8b. */
 export declare function isGzip(bytes: Uint8Array): boolean;
 /** Decompress one gzip stream, bounded so a gzip bomb cannot inflate without limit. */
 export declare function gzipDecompress(bytes: Uint8Array, maxOutput: number): Promise<Uint8Array>;
+/** Decompress a gzip source as a stream of chunks, bounded to `maxOutput` bytes, for output too large to hold at once. */
+export declare function gzipDecompressStream(source: ByteSource, maxOutput: number): AsyncGenerator<Uint8Array>;
 /** Compress bytes as one gzip stream (tar.gz writing). */
 export declare function gzipCompress(bytes: Uint8Array): Promise<Uint8Array>;

package/dist/types/ar/codecs/zstd.d.ts

@@ -1,6 +1,9 @@
+import { type ByteSource } from "../source.js";
 /** zstd frame magic: 28 b5 2f fd. */
 export declare function isZstd(bytes: Uint8Array): boolean;
 /** Decompress one zstd frame, bounded to `maxOutput` bytes. */
 export declare function zstdDecompress(bytes: Uint8Array, maxOutput: number): Promise<Uint8Array>;
+/** Decompress a zstd source as a stream of chunks, bounded to `maxOutput` bytes, for output too large to hold at once. */
+export declare function zstdDecompressStream(source: ByteSource, maxOutput: number): AsyncGenerator<Uint8Array>;
 /** Compress bytes as one zstd frame (tar.zst writing). */
 export declare function zstdCompress(bytes: Uint8Array): Promise<Uint8Array>;

package/dist/types/ar/limits.d.ts

@@ -9,6 +9,8 @@ export interface ArchiveLimits {
     maxEntries: number;
     /** Max bytes for any archive fully materialized in memory (tar buffers, solid/decompressed streams). */
     maxInMemorySize: number;
+    /** Max decompressed bytes in one pass over a compressed tar too large for `maxInMemorySize`. */
+    maxStreamSize: number;
     /** Max bytes for archive metadata (ZIP central directory, ASAR JSON header, RAR/7z header areas). */
     maxIndexSize: number;
     /** Max declared bytes for a single extracted member. */

package/dist/types/ar/source.d.ts

@@ -1,3 +1,4 @@
+import { type Transform } from "node:stream";
 /**
  * A byte window into an archive — file-backed (lazy, ranged reads) or
  * in-memory. Format readers index through this so ZIP/ASAR/RAR payloads are
@@ -17,6 +18,14 @@ export declare function memoryByteSource(buffer: Uint8Array): ByteSource;
 export declare function fileByteSource(filePath: string): ByteSource;
 /** Materialize an entire {@link ByteSource}; use only under a limits check. */
 export declare function readAllBytes(source: ByteSource): Promise<Uint8Array>;
+/** Chunk size for streamed decompression, on both the compressed and the decompressed side. */
+export declare const STREAM_CHUNK_SIZE: number;
+/**
+ * Decompress a {@link ByteSource} through `decoder` chunk by chunk, so neither
+ * the compressed nor the decompressed stream is ever held whole. Output past
+ * `maxOutput` bytes fails, so a decompression bomb cannot run without bound.
+ */
+export declare function decodeByteSource(source: ByteSource, decoder: Transform, maxOutput: number): AsyncGenerator<Uint8Array>;
 /** Options for {@link httpByteSource}. */
 export interface HttpByteSourceOptions {
     /** Extra request headers (e.g. authorization). */

package/dist/types/ar/tar.d.ts

@@ -1,6 +1,11 @@
 import type { ArchiveIndexEntry, FormatReader, FormatReadOptions } from "./types.js";
-/** Index an already-decompressed tar buffer with bounded GNU, ustar, and PAX handling. */
-export declare function readTarEntriesFromBuffer(buffer: Uint8Array, options: FormatReadOptions): ArchiveIndexEntry[];
+/** Index an already-decompressed tar buffer; members are views into it. */
+export declare function readTarEntriesFromBuffer(buffer: Uint8Array, options: FormatReadOptions): Promise<ArchiveIndexEntry[]>;
+/**
+ * Index a decompressed tar stream that is too large to hold in memory: one
+ * pass over `open()` walks the headers, and member reads open it again.
+ */
+export declare function readTarEntriesFromStream(open: () => AsyncIterable<Uint8Array>, options: FormatReadOptions): Promise<ArchiveIndexEntry[]>;
 /** Read and index a tar source after one bounded whole-stream read. */
 export declare const readTar: FormatReader;
 /** Detect a tar header, including legacy pre-ustar archives, by its checksum. */

package/dist/types/dirs.d.ts

@@ -49,7 +49,14 @@ export declare function normalizeProfileName(profile: string | undefined): strin
 export declare function resolveProfileEnv(zeta: string | undefined): string | undefined;
 /** Profile-independent config root (~/.zeta), shared by every zeta profile. */
 export declare function getBaseConfigRoot(): string;
-export declare function resolveEquivalentPath(inputPath: string): string;
+export interface EquivalentPathOptions {
+    /**
+     * Resolve a path that does not exist yet through its deepest existing ancestor, keeping the
+     * missing suffix, so a symlinked parent canonicalizes the same before and after the path appears.
+     */
+    throughMissing?: boolean;
+}
+export declare function resolveEquivalentPath(inputPath: string, options?: EquivalentPathOptions): string;
 export declare function normalizePathForComparison(inputPath: string): string;
 /**
  * Compare paths already normalized by {@link normalizePathForComparison}.

package/dist/types/env.d.ts

@@ -1,3 +1,4 @@
+export * from "./test-runtime.js";
 export * from "./worker-host.js";
 /**
  * Strict shell-identifier shape. Used for dotenv keys we accept into
@@ -81,8 +82,6 @@ export declare function $envExact(name: string, env?: Record<string, string | un
  * Empty, invalid, NaN, zero, or negative values return `defaultValue`.
  */
 export declare function $envpos(name: string, defaultValue: number): number;
-/** True when the process is an explicitly marked test child or Bun is running a test entrypoint. */
-export declare function isBunTestRuntime(): boolean;
 /**
  * True when real-terminal side effects must be suppressed: stdout escape/frame
  * writes, stdin raw-mode + resume, CSI/OSC capability probes, SIGWINCH, window

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/dist/types/index.d.ts

@@ -22,6 +22,7 @@ export * from "./mermaid-ascii.js";
 export * from "./mime.js";
 export * from "./path.js";
 export * from "./path-tree.js";
+export * from "./ports.js";
 export * from "./peek-file.js";
 export * as postmortem from "./postmortem.js";
 export * from "./process-name.js";

package/dist/types/ports.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Default loopback ports for Zeta's local services.
+ *
+ * OMP installs on the same machine use 30141/30142/3847, and common developer
+ * tools squat on 3000/8080/8787/3847. Zeta therefore owns a dedicated block:
+ * three uncommon ports, at least two apart, so a side-by-side OMP install and
+ * unrelated services cannot take the gateway or the stats dashboard away.
+ *
+ * Every default in the repository derives from these constants. The standalone
+ * Electron shell (`desktop/src/main.ts`, not a Bun workspace package) carries
+ * literals that must match; its serve-discovery test asserts the values.
+ */
+export declare const ZETA_WEB_PORT = 43141;
+export declare const ZETA_GATEWAY_PORT = 43143;
+export declare const ZETA_STATS_PORT = 43147;

package/dist/types/test-runtime.d.ts

@@ -0,0 +1,2 @@
+/** True when the process is an explicitly marked test child or Bun is running a test entrypoint. */
+export declare function isBunTestRuntime(): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@linxiraos/pi-utils",
-	"version": "1.4.0",
+	"version": "1.4.2",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"utilities",
@@ -54,7 +54,7 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@linxiraos/pi-natives": "1.4.0"
+		"@linxiraos/pi-natives": "1.4.2"
 	},
 	"devDependencies": {
 		"@types/bun": "1.4.3"

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/ar/codecs/gzip.ts

@@ -1,6 +1,7 @@
 import { promisify } from "node:util";
 import * as zlib from "node:zlib";
 import { ArchiveError } from "../error";
+import { type ByteSource, decodeByteSource, STREAM_CHUNK_SIZE } from "../source";
 
 const gzipAsync = promisify(zlib.gzip);
 const gunzipAsync = promisify(zlib.gunzip);
@@ -19,6 +20,11 @@ export async function gzipDecompress(bytes: Uint8Array, maxOutput: number): Prom
 	}
 }
 
+/** Decompress a gzip source as a stream of chunks, bounded to `maxOutput` bytes, for output too large to hold at once. */
+export function gzipDecompressStream(source: ByteSource, maxOutput: number): AsyncGenerator<Uint8Array> {
+	return decodeByteSource(source, zlib.createGunzip({ chunkSize: STREAM_CHUNK_SIZE }), maxOutput);
+}
+
 /** Compress bytes as one gzip stream (tar.gz writing). */
 export function gzipCompress(bytes: Uint8Array): Promise<Uint8Array> {
 	return gzipAsync(bytes);

package/src/ar/codecs/zstd.ts

@@ -1,6 +1,7 @@
 import { promisify } from "node:util";
 import * as zlib from "node:zlib";
 import { ArchiveError } from "../error";
+import { type ByteSource, decodeByteSource, STREAM_CHUNK_SIZE } from "../source";
 
 const zstdCompressAsync = promisify(zlib.zstdCompress);
 const zstdDecompressAsync = promisify(zlib.zstdDecompress);
@@ -19,6 +20,11 @@ export async function zstdDecompress(bytes: Uint8Array, maxOutput: number): Prom
 	}
 }
 
+/** Decompress a zstd source as a stream of chunks, bounded to `maxOutput` bytes, for output too large to hold at once. */
+export function zstdDecompressStream(source: ByteSource, maxOutput: number): AsyncGenerator<Uint8Array> {
+	return decodeByteSource(source, zlib.createZstdDecompress({ chunkSize: STREAM_CHUNK_SIZE }), maxOutput);
+}
+
 /** Compress bytes as one zstd frame (tar.zst writing). */
 export function zstdCompress(bytes: Uint8Array): Promise<Uint8Array> {
 	return zstdCompressAsync(bytes);

package/src/ar/deb.ts

@@ -135,7 +135,7 @@ async function readDebImpl(source: ByteSource, options: FormatReadOptions): Prom
 		}
 		const compressed = await readOuterMember(outerEntry);
 		const tarBytes = await decompressDebTar(compressed, tar.compression, options);
-		const innerEntries = readTarEntriesFromBuffer(tarBytes, options);
+		const innerEntries = await readTarEntriesFromBuffer(tarBytes, options);
 		for (const innerEntry of innerEntries) {
 			upsertArchiveEntry(result, tar.kind === "control" ? prefixControlEntry(innerEntry) : innerEntry);
 		}

package/src/ar/limits.ts

@@ -13,6 +13,8 @@ export interface ArchiveLimits {
 	maxEntries: number;
 	/** Max bytes for any archive fully materialized in memory (tar buffers, solid/decompressed streams). */
 	maxInMemorySize: number;
+	/** Max decompressed bytes in one pass over a compressed tar too large for `maxInMemorySize`. */
+	maxStreamSize: number;
 	/** Max bytes for archive metadata (ZIP central directory, ASAR JSON header, RAR/7z header areas). */
 	maxIndexSize: number;
 	/** Max declared bytes for a single extracted member. */
@@ -26,6 +28,7 @@ export interface ArchiveLimits {
 export const DEFAULT_ARCHIVE_LIMITS: ArchiveLimits = {
 	maxEntries: 1_000_000,
 	maxInMemorySize: 256 * 1024 * 1024,
+	maxStreamSize: 4 * 1024 * 1024 * 1024,
 	maxIndexSize: 64 * 1024 * 1024,
 	maxMemberSize: 64 * 1024 * 1024,
 	maxPathBytes: 4096,