@oh-my-pi/pi-utils 18.0.6 → 18.0.7

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [18.0.7] - 2026-08-26
+
+### Added
+
+- Added `math-delimiters`, the LaTeX span/block delimiter grammar (`mathStartIndex`, `mathOpenerAt`, `mathSpanAt`, `mathBlockAt`) shared by every Markdown renderer: pandoc's anti-currency rules for `$…$`, own-line display blocks, and delimiters matched by backslash parity, so an escaped `\$x$` stays literal and a TeX row break cannot end a span early.
+- Added `RequestError.sessionBusy(message, data)` to represent ACP session-busy errors (`-32003`) through the shared JSON-RPC transport.
+- Exported `getComposerCacheDir` for resolving the per-project Composer cache directory, including support for `XDG_CACHE_HOME`.
+
+### Fixed
+
+- Fixed OMP sessions unexpectedly exiting during socket cleanup or optional-worker communication on Bun.
+
 ## [18.0.6] - 2026-08-26
 
 ### Added

package/README.md

@@ -17,6 +17,7 @@ Shared utilities for [oh-my-pi](https://github.com/can1357/oh-my-pi) packages. Z
 | `fs-error` | Errno guards (`isEnoent` and friends) |
 | `env` / `worker-host` | Environment plumbing and side-effect-free worker-host entry contract (`workerHostEntry`) |
 | `abortable` / `async` | AbortSignal-aware stream/promise helpers |
+| `math-delimiters` | LaTeX span/block delimiter grammar (offsets only) shared by the TUI and collab-web renderers |
 | `peek-file` | Read the first N bytes of a file with pooled buffers |
 | `frontmatter`, `glob`, `mime`, `temp`, `format`, `color`, `snowflake`, `tab-spacing`, `path-tree`, `sanitize-text` | Smaller single-purpose helpers |
 

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

@@ -55,6 +55,13 @@ export declare class RequestError extends Error {
     static authRequired(data?: unknown, additionalMessage?: string): RequestError;
     /** Creates a resource-not-found error. */
     static resourceNotFound(uri?: string): RequestError;
+    /**
+     * Creates a session-busy error: the agent/session is already processing, so the
+     * request can be retried once idle (steer/follow-up/wait) instead of treating it
+     * as a fault. `message` carries the caller's user-facing wording; `data` should
+     * keep the stable discriminator shape (`reason: "session_busy"`).
+     */
+    static sessionBusy(message: string, data?: unknown): RequestError;
     /** Converts this error into a JSON-RPC result. */
     toResult(): {
         error: ErrorResponse;

package/dist/types/dirs.d.ts

@@ -228,6 +228,8 @@ export declare function getModelDbPath(agentDir?: string): string;
 export declare function getTinyModelsCacheDir(agentDir?: string): string;
 /** Get the document conversion cache directory (~/.omp/agent/cache/document-conversions; XDG default: $XDG_CACHE_HOME/omp/cache/document-conversions). */
 export declare function getDocumentConversionCacheDir(agentDir?: string): string;
+/** Get the per-project composer speculative cache directory (~/.omp/agent/cache/composer; XDG default: $XDG_CACHE_HOME/omp/cache/composer). */
+export declare function getComposerCacheDir(agentDir?: string): string;
 /** Get the sessions directory (~/.omp/agent/sessions). */
 export declare function getSessionsDir(agentDir?: string): string;
 /** Get the content-addressed blob store directory (~/.omp/agent/blobs). */
@@ -274,6 +276,13 @@ export declare function getProjectPluginOverridesPath(cwd?: string): string;
 export declare function getMCPConfigPath(scope: "user" | "project", cwd?: string): string;
 /** Get the SSH config file path. */
 export declare function getSSHConfigPath(scope: "user" | "project", cwd?: string): string;
+/**
+ * Application label for usage attribution (`OMP_APP_NAME`), defaulting to
+ * `omp`. Embedders that drive omp programmatically (robomp, CI bots, …) set
+ * the env var so broker-side per-client burn tracking can answer "what did
+ * app X use" instead of folding everything into one install-wide bucket.
+ */
+export declare function getAppName(): string;
 /**
  * Persistent per-install UUID stored at `~/.omp/install-id`.
  *

package/dist/types/index.d.ts

@@ -14,6 +14,7 @@ export * from "./json.js";
 export * from "./json-parse.js";
 export * as logger from "./logger.js";
 export * from "./loop-phase.js";
+export * from "./math-delimiters.js";
 export * from "./mermaid-ascii.js";
 export * from "./mime.js";
 export * from "./path.js";

package/dist/types/math-delimiters.d.ts

@@ -0,0 +1,45 @@
+/**
+ * LaTeX delimiter grammar for agent-authored Markdown: where does a math span
+ * begin and end, in source offsets. Carries no rendering policy — what to do
+ * with an unclosed opener, whether a body is typesettable, and how it is
+ * displayed belong to the renderer (Unicode in the TUI, KaTeX in collab web).
+ */
+/** Opening delimiter. Each closer (`$`, `$$`, `\)`, `\]`) is as wide as its opener. */
+export type MathOpener = "$" | "$$" | "\\(" | "\\[";
+/** A closed math span found in the source. */
+export interface MathSpan {
+    opener: MathOpener;
+    /** True for the display forms `$$…$$` and `\[…\]`. */
+    display: boolean;
+    /** Offset one past the closing delimiter. */
+    end: number;
+    /** Source between the delimiters, verbatim. */
+    body: string;
+}
+/** An own-line display block: opener and closer each alone on their line. */
+export interface MathBlock {
+    /** Both delimiter lines, the body, and the trailing newline. */
+    raw: string;
+    body: string;
+}
+/**
+ * Leftmost offset at or after `from` where an opener could begin. A scan hint,
+ * not a decision: whether that candidate is really math — escaped, currency,
+ * unclosed — is decided by {@link mathSpanAt}.
+ */
+export declare function mathStartIndex(source: string, from?: number): number | undefined;
+/** Math opener at `at`, or `undefined` when no delimiter starts there. */
+export declare function mathOpenerAt(source: string, at: number): MathOpener | undefined;
+/**
+ * The span opened at `at`, or `undefined` when the run is not math — including
+ * an opener the source escaped, so `\$x$` and `\\(x\)` are literal text.
+ *
+ * `from` bounds how far back the escape scan may look. Leave it at 0 when
+ * reading raw source. Pass the offset your own walk resumed at if you have
+ * already consumed the escapes behind it, as `renderMathInText` does: after it
+ * emits the `\\` of `\\\(x\)`, the `\(` that follows is a real opener even
+ * though a backslash precedes it.
+ */
+export declare function mathSpanAt(source: string, at: number, from?: number): MathSpan | undefined;
+/** The own-line display block starting at offset 0, or `undefined`. */
+export declare function mathBlockAt(source: string): MathBlock | undefined;

package/dist/types/postmortem.d.ts

@@ -44,6 +44,19 @@ export type BrokenPipeSource = "ipc-send" | "stdio-write";
 export declare function classifyBrokenPipe(err: Error): BrokenPipeSource | undefined;
 /** Whether an EPIPE came from an IPC `send()` to an optional worker. */
 export declare function isIpcSendEpipe(err: Error): boolean;
+/**
+ * Whether an uncaught error is Bun's asynchronous `ERR_SOCKET_CLOSED` thrown
+ * from inside `node:net` internals with no application frames on the stack.
+ *
+ * Bun ≥1.4 can fire the close callback of an already-closed `node:net` socket
+ * on a fresh stack; the throw bypasses every callsite try/catch and surfaces
+ * here as a process-level uncaughtException. Closing an already-closed socket
+ * is inherently a no-op — the socket owner's own `error`/`close` handlers
+ * still drive recovery — so tearing the session down for it is pure loss.
+ * Only frameless internal stacks qualify: an `ERR_SOCKET_CLOSED` raised
+ * through application code keeps the fatal path.
+ */
+export declare function isInternalSocketClosedError(err: unknown): boolean;
 /**
  * Detect Bun's advanced-serialization (structured-clone) IPC decode failure.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.0.6",
+	"version": "18.0.7",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://omp.sh",
 	"author": "Stencil Labs, Inc.",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.0.6"
+		"@oh-my-pi/pi-natives": "18.0.7"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/acp/transport.ts

@@ -77,6 +77,15 @@ export class RequestError extends Error {
 			uri === undefined ? undefined : { uri },
 		);
 	}
+	/**
+	 * Creates a session-busy error: the agent/session is already processing, so the
+	 * request can be retried once idle (steer/follow-up/wait) instead of treating it
+	 * as a fault. `message` carries the caller's user-facing wording; `data` should
+	 * keep the stable discriminator shape (`reason: "session_busy"`).
+	 */
+	static sessionBusy(message: string, data?: unknown): RequestError {
+		return new RequestError(-32003, message, data);
+	}
 	/** Converts this error into a JSON-RPC result. */
 	toResult(): { error: ErrorResponse } {
 		return { error: this.toErrorResponse() };

package/src/dirs.ts

@@ -791,6 +791,10 @@ export function getTinyModelsCacheDir(agentDir?: string): string {
 export function getDocumentConversionCacheDir(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, path.join("cache", "document-conversions"), "cache");
 }
+/** Get the per-project composer speculative cache directory (~/.omp/agent/cache/composer; XDG default: $XDG_CACHE_HOME/omp/cache/composer). */
+export function getComposerCacheDir(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, path.join("cache", "composer"), "cache");
+}
 
 /** Get the sessions directory (~/.omp/agent/sessions). */
 export function getSessionsDir(agentDir?: string): string {
@@ -955,6 +959,17 @@ export function getSSHConfigPath(scope: "user" | "project", cwd: string = getPro
 let cachedInstallId: string | null = null;
 
 const INSTALL_ID_FILE = "install-id";
+/**
+ * Application label for usage attribution (`OMP_APP_NAME`), defaulting to
+ * `omp`. Embedders that drive omp programmatically (robomp, CI bots, …) set
+ * the env var so broker-side per-client burn tracking can answer "what did
+ * app X use" instead of folding everything into one install-wide bucket.
+ */
+export function getAppName(): string {
+	const value = process.env.OMP_APP_NAME?.trim();
+	return value ? value : "omp";
+}
+
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 /**

package/src/index.ts

@@ -14,6 +14,7 @@ export * from "./json";
 export * from "./json-parse";
 export * as logger from "./logger";
 export * from "./loop-phase";
+export * from "./math-delimiters";
 export * from "./mermaid-ascii";
 export * from "./mime";
 export * from "./path";

package/src/math-delimiters.ts

@@ -0,0 +1,143 @@
+/**
+ * LaTeX delimiter grammar for agent-authored Markdown: where does a math span
+ * begin and end, in source offsets. Carries no rendering policy — what to do
+ * with an unclosed opener, whether a body is typesettable, and how it is
+ * displayed belong to the renderer (Unicode in the TUI, KaTeX in collab web).
+ */
+
+/** Opening delimiter. Each closer (`$`, `$$`, `\)`, `\]`) is as wide as its opener. */
+export type MathOpener = "$" | "$$" | "\\(" | "\\[";
+
+/** A closed math span found in the source. */
+export interface MathSpan {
+	opener: MathOpener;
+	/** True for the display forms `$$…$$` and `\[…\]`. */
+	display: boolean;
+	/** Offset one past the closing delimiter. */
+	end: number;
+	/** Source between the delimiters, verbatim. */
+	body: string;
+}
+
+/** An own-line display block: opener and closer each alone on their line. */
+export interface MathBlock {
+	/** Both delimiter lines, the body, and the trailing newline. */
+	raw: string;
+	body: string;
+}
+
+// Display math blocks: opening `$$` / `\[` and closing `$$` / `\]` each alone on
+// their own line (≤3 leading spaces). Matched at the block level — before
+// paragraph/list parsing — so a multi-line equation (e.g. a matrix with `\\`
+// row breaks) survives as one unit and blank lines inside the block don't split
+// it. The own-line requirement leaves inline `$$…$$` inside prose to the span
+// grammar below. `\r?\n` at each line boundary keeps the grammar CRLF-safe for
+// direct callers; marked-fed renderers already normalize line endings first.
+const MATH_BLOCK_DOLLAR = /^ {0,3}\$\$[ \t]*\r?\n([\s\S]+?)\r?\n {0,3}\$\$[ \t]*(?:\r?\n|$)/;
+const MATH_BLOCK_BRACKET = /^ {0,3}\\\[[ \t]*\r?\n([\s\S]+?)\r?\n {0,3}\\\][ \t]*(?:\r?\n|$)/;
+
+/**
+ * Leftmost offset at or after `from` where an opener could begin. A scan hint,
+ * not a decision: whether that candidate is really math — escaped, currency,
+ * unclosed — is decided by {@link mathSpanAt}.
+ */
+// Three indexOf scans instead of a `/\$|\\\(|\\\[/` alternation — marked calls
+// this on the remaining source at every inline position, where the alternation
+// showed up in CPU profiles (part of a ~4.3% start() tail).
+export function mathStartIndex(source: string, from = 0): number | undefined {
+	let best = source.indexOf("$", from);
+	const paren = source.indexOf("\\(", from);
+	if (paren !== -1 && (best === -1 || paren < best)) best = paren;
+	const bracket = source.indexOf("\\[", from);
+	if (bracket !== -1 && (best === -1 || bracket < best)) best = bracket;
+	return best === -1 ? undefined : best;
+}
+
+/** Math opener at `at`, or `undefined` when no delimiter starts there. */
+export function mathOpenerAt(source: string, at: number): MathOpener | undefined {
+	const first = source.charCodeAt(at);
+	if (first === 0x24 /* $ */) return source.charCodeAt(at + 1) === 0x24 ? "$$" : "$";
+	if (first !== 0x5c /* \ */) return undefined;
+	const second = source.charCodeAt(at + 1);
+	if (second === 0x28 /* ( */) return "\\(";
+	if (second === 0x5b /* [ */) return "\\[";
+	return undefined;
+}
+
+/**
+ * The span opened at `at`, or `undefined` when the run is not math — including
+ * an opener the source escaped, so `\$x$` and `\\(x\)` are literal text.
+ *
+ * `from` bounds how far back the escape scan may look. Leave it at 0 when
+ * reading raw source. Pass the offset your own walk resumed at if you have
+ * already consumed the escapes behind it, as `renderMathInText` does: after it
+ * emits the `\\` of `\\\(x\)`, the `\(` that follows is a real opener even
+ * though a backslash precedes it.
+ */
+export function mathSpanAt(source: string, at: number, from = 0): MathSpan | undefined {
+	const opener = mathOpenerAt(source, at);
+	if (opener === undefined || escapedAt(source, at, from)) return undefined;
+	const bodyStart = at + opener.length;
+	const closeAt = opener === "$" ? dollarCloserIndex(source, at) : closerIndex(source, opener, bodyStart);
+	if (closeAt === -1) return undefined;
+	const body = source.slice(bodyStart, closeAt);
+	// `dollarCloserIndex` already rejects an all-space `$…$`; `$$ $$` needs the
+	// same guard here, while `\(\)` and `\[\]` are unambiguous enough to keep.
+	if (opener === "$$" && body.trim() === "") return undefined;
+	return { opener, display: opener === "$$" || opener === "\\[", end: closeAt + opener.length, body };
+}
+
+/** The own-line display block starting at offset 0, or `undefined`. */
+export function mathBlockAt(source: string): MathBlock | undefined {
+	const match = MATH_BLOCK_DOLLAR.exec(source) ?? MATH_BLOCK_BRACKET.exec(source);
+	if (!match || match[1].trim() === "") return undefined;
+	return { raw: match[0], body: match[1] };
+}
+
+/**
+ * Offset of the `$$` / `\)` / `\]` that closes a span, or -1. In `\(a \\) b\)`
+ * the `\\` is a TeX row break, so that `)` is body text and the span closes at
+ * the final `\)`.
+ */
+function closerIndex(source: string, opener: MathOpener, from: number): number {
+	// Dollar closers equal their openers; the bracket forms flip the bracket.
+	const closer = opener === "\\(" ? "\\)" : opener === "\\[" ? "\\]" : opener;
+	for (let at = source.indexOf(closer, from); at !== -1; at = source.indexOf(closer, at + 1)) {
+		if (!escapedAt(source, at, from)) return at;
+	}
+	return -1;
+}
+
+/** An odd run of backslashes back to `from` escapes the delimiter at `index`. */
+function escapedAt(source: string, index: number, from: number): boolean {
+	let backslashes = 0;
+	for (let at = index - 1; at >= from && source.charCodeAt(at) === 0x5c /* \ */; at--) backslashes++;
+	return backslashes % 2 === 1;
+}
+
+/**
+ * Offset of the `$` that closes an inline span opened at `open`, or -1. Pandoc's
+ * anti-currency heuristics: the opener must not be followed by whitespace, the
+ * closer must not be preceded by whitespace nor followed by a digit, `\$` is a
+ * literal dollar, and the span may not cross a newline — so "$5 and $10" is
+ * prose, not math.
+ */
+function dollarCloserIndex(source: string, open: number): number {
+	const after = source[open + 1];
+	if (after === undefined || after === " " || after === "\t" || after === "\n" || after === "$") return -1;
+	for (let at = open + 1; at < source.length; at++) {
+		const char = source[at];
+		if (char === "\\") {
+			at++;
+			continue;
+		}
+		if (char === "\n") return -1;
+		if (char !== "$") continue;
+		const before = source[at - 1];
+		if (before === " " || before === "\t") return -1;
+		const next = source[at + 1];
+		if (next !== undefined && next >= "0" && next <= "9") continue; // currency: keep scanning
+		return source.slice(open + 1, at).trim().length > 0 ? at : -1;
+	}
+	return -1;
+}

package/src/postmortem.ts

@@ -146,6 +146,33 @@ export function isIpcSendEpipe(err: Error): boolean {
 	return classifyBrokenPipe(err) === "ipc-send";
 }
 
+/**
+ * Whether an uncaught error is Bun's asynchronous `ERR_SOCKET_CLOSED` thrown
+ * from inside `node:net` internals with no application frames on the stack.
+ *
+ * Bun ≥1.4 can fire the close callback of an already-closed `node:net` socket
+ * on a fresh stack; the throw bypasses every callsite try/catch and surfaces
+ * here as a process-level uncaughtException. Closing an already-closed socket
+ * is inherently a no-op — the socket owner's own `error`/`close` handlers
+ * still drive recovery — so tearing the session down for it is pure loss.
+ * Only frameless internal stacks qualify: an `ERR_SOCKET_CLOSED` raised
+ * through application code keeps the fatal path.
+ */
+export function isInternalSocketClosedError(err: unknown): boolean {
+	if (!(err instanceof Error) || !("code" in err) || err.code !== "ERR_SOCKET_CLOSED") return false;
+	const frames = (err.stack ?? "").split("\n").slice(1);
+	if (frames.length === 0) return false;
+	let hasNetFrame = false;
+	const internal = frames.every(frame => {
+		const trimmed = frame.trim();
+		if (trimmed === "" || trimmed === "at unknown" || trimmed === "at native") return true;
+		if (!/\(node:[^)]*\)$/.test(trimmed) && !/^at node:/.test(trimmed)) return false;
+		hasNetFrame ||= trimmed.includes("node:net:");
+		return true;
+	});
+	return internal && hasNetFrame;
+}
+
 /**
  * Detect Bun's advanced-serialization (structured-clone) IPC decode failure.
  *
@@ -338,9 +365,17 @@ if (isMainThread) {
 			const url = inspector.url();
 			process.stderr.write(`Inspector opened: ${url}\n`);
 		})
-		.on("uncaughtException", async err => {
-			if (isExpectedCleanupError(err)) {
-				logger.warn("Ignoring expected cleanup exception", { err });
+		.on("uncaughtException", async thrown => {
+			if (isExpectedCleanupError(thrown)) {
+				logger.warn("Ignoring expected cleanup exception", { err: thrown });
+				return;
+			}
+			const err = thrown instanceof Error ? thrown : new Error(String(thrown));
+			// Bun can surface a worker IPC send race through uncaughtException
+			// instead of unhandledRejection. Apply the same optional-worker
+			// containment in either global error channel.
+			if (isIpcSendEpipe(err)) {
+				logger.warn("Ignoring EPIPE from worker IPC send; optional subsystem will self-recover", { err });
 				return;
 			}
 			// A malformed advanced-serialization frame from a worker subprocess
@@ -357,6 +392,12 @@ if (isMainThread) {
 				faultWorkerIpcChannels(err);
 				return;
 			}
+			if (isInternalSocketClosedError(err)) {
+				logger.warn("Ignoring async ERR_SOCKET_CLOSED from node:net internals; socket owner recovers itself", {
+					err,
+				});
+				return;
+			}
 			await exitAfterFatal("Uncaught Exception", "Uncaught exception", err, Reason.UNCAUGHT_EXCEPTION);
 		})
 		.on("unhandledRejection", async reason => {