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

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [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

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/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.3",
+	"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,7 +56,7 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.13.3"
+		"@oh-my-pi/pi-natives": "18.14.0"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

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/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];