@oh-my-pi/pi-utils 18.13.2 → 18.14.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [18.14.0] - 2026-10-29
+
+### Added
+
+- Added `logger.withContext(fields, fn)` to attach contextual fields to all records produced during a function and its asynchronous work, plus `logger.withoutContext(fn)` for work that should not inherit caller context.
+
+### Fixed
+
+- Fixed `untilAborted` so promises passed to an already-aborted signal are still observed, preventing later rejections from being reported as unhandled.
+
+## [18.13.3] - 2026-10-28
+
+### Changed
+
+- Updated Bun engine requirement to ≥1.4.4
+
 ## [18.13.2] - 2026-10-27
 
 ### Added

package/README.md

@@ -29,7 +29,7 @@ Import from the root barrel or per-module subpaths (`@oh-my-pi/pi-utils/<module>
 bun add @oh-my-pi/pi-utils
 ```
 
-Ships TypeScript source directly (no build step); requires Bun ≥ 1.3.14.
+Ships TypeScript source directly (no build step); requires Bun ≥ 1.4.4.
 
 ## References
 

package/dist/types/abortable.d.ts

@@ -16,7 +16,8 @@ export declare class AbortError extends Error {
 export declare function abortableSource<T>(stream: ReadableStream<T>, signal?: AbortSignal): AsyncGenerator<T>;
 /**
  * Runs a promise-returning function (`pr`). If the given AbortSignal is aborted before or during
- * execution, the promise is rejected with a standard error.
+ * execution, the promise is rejected with a standard error. A promise passed directly stays
+ * observed, so its later rejection is never unhandled.
  *
  * @param signal - Optional AbortSignal to cancel the operation
  * @param pr - Function returning a promise to run

package/dist/types/index.d.ts

@@ -10,7 +10,6 @@ export * from "./file-lock.js";
 export * from "./format.js";
 export * from "./frontmatter.js";
 export * from "./fs-error.js";
-export * from "./fs-open.js";
 export * from "./incoming-json.js";
 export * from "./json.js";
 export * from "./json-parse.js";

package/dist/types/logger.d.ts

@@ -11,6 +11,20 @@ export interface LogEvent {
 export type LogSink = (event: LogEvent) => void;
 /** Register an out-of-band log sink and return a disposer. */
 export declare function registerLogSink(sink: LogSink): () => void;
+/**
+ * Run `fn` with `context`'s fields on every record logged while it runs,
+ * including from the promises, timers and callbacks it starts. A nested call
+ * replaces the enclosing context, as a subagent's session replaces its
+ * parent's; a field passed to the log call itself wins. Fields are read as each
+ * record is written, so a getter stays current.
+ */
+export declare function withContext<T>(context: Readonly<Record<string, unknown>>, fn: () => T): T;
+/**
+ * Run `fn` outside any {@link withContext}: for process-wide work started on
+ * behalf of one caller, such as a shared server's read loop, whose later
+ * records belong to no single caller.
+ */
+export declare function withoutContext<T>(fn: () => T): T;
 /**
  * Write buffered file records to disk now. The file transport batches records
  * (one write per second or per 64 KiB) and writes `warn`/`error` records

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.13.2",
+	"version": "18.14.0",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"cli",
@@ -27,7 +27,6 @@
 		"README.md",
 		"CHANGELOG.md",
 		"LICENSE",
-		"THIRD-PARTY-NOTICES.txt",
 		"dist/types"
 	],
 	"type": "module",
@@ -57,12 +56,12 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.13.2"
+		"@oh-my-pi/pi-natives": "18.14.0"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"
 	},
 	"engines": {
-		"bun": ">=1.3.14"
+		"bun": ">=1.4.4"
 	}
 }

package/src/abortable.ts

@@ -60,7 +60,8 @@ export async function* abortableSource<T>(stream: ReadableStream<T>, signal?: Ab
 
 /**
  * Runs a promise-returning function (`pr`). If the given AbortSignal is aborted before or during
- * execution, the promise is rejected with a standard error.
+ * execution, the promise is rejected with a standard error. A promise passed directly stays
+ * observed, so its later rejection is never unhandled.
  *
  * @param signal - Optional AbortSignal to cancel the operation
  * @param pr - Function returning a promise to run
@@ -71,7 +72,10 @@ export function untilAborted<T>(
 	pr: Promise<T> | (() => Promise<T>),
 ): Promise<T> {
 	if (!signal) return typeof pr === "function" ? pr() : pr;
-	if (signal.aborted) return Promise.reject(new AbortError(signal));
+	if (signal.aborted) {
+		if (typeof pr !== "function") void pr.catch(() => {});
+		return Promise.reject(new AbortError(signal));
+	}
 
 	const { promise, resolve, reject } = Promise.withResolvers<T>();
 	const onAbort = () => reject(new AbortError(signal));

package/src/index.ts

@@ -10,7 +10,6 @@ export * from "./file-lock";
 export * from "./format";
 export * from "./frontmatter";
 export * from "./fs-error";
-export * from "./fs-open";
 export * from "./incoming-json";
 export * from "./json";
 export * from "./json-parse";

package/src/logger/rotating-file.ts

@@ -3,7 +3,6 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { localDay } from "../dirs";
-import { openCloexecSync } from "../fs-open";
 
 /** Write batching for {@link RotatingFileSink}. */
 export interface RotatingFileBatchOptions {
@@ -87,7 +86,7 @@ export class RotatingFileSink {
 
 	#openFd(filePath: string): void {
 		this.#closeFd();
-		this.#fd = openCloexecSync(filePath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND);
+		this.#fd = fs.openSync(filePath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND);
 		try {
 			this.#onRotate?.(filePath);
 		} catch {

package/src/logger.ts

@@ -7,11 +7,13 @@
  * transport so a process supervisor (pm2, journald, k8s) captures the logs.
  *
  * Each entry includes `process.pid` so concurrent omp instances stay
- * traceable. The file is created on the first record written. Records are
- * batched — one write per second or per 64 KiB — while `warn`/`error` records
- * are written at once together with everything buffered before them; exit,
- * fatal, and signal paths flush the rest. `OMP_LOG_LEVEL` optionally limits
- * the levels written to the file (default: all).
+ * traceable, and the fields of the enclosing {@link withContext} (a session's
+ * `sessionId`) so sessions sharing one process stay apart. The file is created
+ * on the first record written. Records are batched — one write per second or
+ * per 64 KiB — while `warn`/`error` records are written at once together with
+ * everything buffered before them; exit, fatal, and signal paths flush the
+ * rest. `OMP_LOG_LEVEL` optionally limits the levels written to the file
+ * (default: all).
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 import * as fs from "node:fs";
@@ -48,7 +50,18 @@ export function registerLogSink(sink: LogSink): () => void {
 
 function emitToSinks(level: LogLevel, message: string, context: Record<string, unknown> | undefined): void {
 	if (logSinks.size === 0) return;
-	const event: LogEvent = { level, message, context, timestamp: new Date() };
+	// The enclosing {@link withContext} fields reach sinks as they reach the file;
+	// call-site fields win, and a record outside any context keeps its own object.
+	const scoped = logContextStorage.getStore();
+	let merged = context;
+	if (scoped) {
+		try {
+			merged = { ...scoped, ...context };
+		} catch {
+			// A throwing getter must not turn a log call into a failure; sinks get the call's own fields.
+		}
+	}
+	const event: LogEvent = { level, message, context: merged, timestamp: new Date() };
 	for (const sink of logSinks) {
 		try {
 			sink(event);
@@ -251,6 +264,28 @@ function formatLocalTimestamp(date: Date): string {
 
 const FORMAT_TOKEN_PATTERN = /%[scdjifoO%]/;
 
+const logContextStorage = new AsyncLocalStorage<Readonly<Record<string, unknown>>>();
+
+/**
+ * Run `fn` with `context`'s fields on every record logged while it runs,
+ * including from the promises, timers and callbacks it starts. A nested call
+ * replaces the enclosing context, as a subagent's session replaces its
+ * parent's; a field passed to the log call itself wins. Fields are read as each
+ * record is written, so a getter stays current.
+ */
+export function withContext<T>(context: Readonly<Record<string, unknown>>, fn: () => T): T {
+	return logContextStorage.run(context, fn);
+}
+
+/**
+ * Run `fn` outside any {@link withContext}: for process-wide work started on
+ * behalf of one caller, such as a shared server's read loop, whose later
+ * records belong to no single caller.
+ */
+export function withoutContext<T>(fn: () => T): T {
+	return logContextStorage.exit(fn);
+}
+
 /** Serialize one log record: timestamp, level, pid, message, then context fields. */
 function formatLogRecord(
 	level: LogLevel,
@@ -266,6 +301,12 @@ function formatLogRecord(
 		pid: process.pid,
 		message: metadata?.message ? `${message} ${metadata.message}` : message,
 	};
+	const scoped = logContextStorage.getStore();
+	if (scoped) {
+		for (const key of Object.keys(scoped)) {
+			if (key !== "level" && key !== "timestamp" && key !== "message") entry[key] = scoped[key];
+		}
+	}
 	if (metadata) {
 		for (const key of Object.keys(metadata)) {
 			if (key !== "level" && key !== "timestamp" && key !== "message") entry[key] = metadata[key];