@linxiraos/pi-utils 1.0.0

package/dist/types/postmortem.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Cleanup and postmortem handler utilities.
+ *
+ * This module provides a system for registering and running cleanup callbacks
+ * in response to process exit, signals, or fatal exceptions. It is intended to
+ * allow reliably releasing resources or shutting down subprocesses, files, sockets, etc.
+ */
+export declare enum Reason {
+    PRE_EXIT = "pre_exit",// Pre-exit phase (not used by default)
+    EXIT = "exit",// Normal process exit
+    SIGINT = "sigint",// Ctrl-C or SIGINT
+    SIGTERM = "sigterm",// SIGTERM
+    SIGHUP = "sighup",// SIGHUP
+    UNCAUGHT_EXCEPTION = "uncaught_exception",// Fatal exception
+    UNHANDLED_REJECTION = "unhandled_rejection",// Unhandled promise rejection
+    MANUAL = "manual"
+}
+/**
+ * Symbol stamped by the extension-load guard onto the throwing replacement it
+ * installs over `process.exit` / `process.reallyExit`, carrying the native
+ * primitive that replacement shadows.
+ *
+ * Host-owned shutdown ({@link exitProcess}) reads through it so a signal that
+ * lands while the guard is active still terminates the process (#6488), while
+ * a signal that lands after the guard has restored the native exit also
+ * terminates cleanly (#7393). `Symbol.for` so it survives duplicate module
+ * instances across bundles/realms.
+ */
+export declare const NATIVE_PROCESS_EXIT: unique symbol;
+/** User-facing command printed before fatal cleanup so interrupted work can be resumed. */
+export interface FatalRecoveryHint {
+    /** Stable label identifying the recoverable session or process. */
+    label: string;
+    /** Complete shell command the user can execute to resume the interrupted work. */
+    command: string;
+}
+type FatalRecoveryHintProvider = () => FatalRecoveryHint | undefined;
+/** Origin of an EPIPE raised by a process communication channel. */
+export type BrokenPipeSource = "ipc-send" | "stdio-write";
+/**
+ * Classify EPIPE errors from worker IPC and stdio without treating unrelated
+ * broken pipes as globally recoverable.
+ */
+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;
+/**
+ * Treat unhandled stdout EPIPE rejections as a graceful peer disconnect.
+ *
+ * Stdio protocol servers call this for their process lifetime so a closed
+ * client pipe runs registered cleanup callbacks instead of the fatal path.
+ * The returned callback removes the registration.
+ */
+export declare function registerStdioDisconnectHandling(): () => void;
+/**
+ * Mark an error as expected cleanup fallout so the global fatal handlers
+ * downgrade it to a log line instead of tearing down the process. Use for
+ * abort reasons fired by routine resource teardown (browser run end, tab
+ * close) whose rejections may surface on fire-and-forget promises with no
+ * consumer. Returns the same error for inline use at the `abort()` callsite.
+ */
+export declare function markExpectedCleanupError<T extends object>(reason: T): T;
+/**
+ * Whether `reason` (or any error in its `cause` chain) was marked via
+ * {@link markExpectedCleanupError}. Walks the chain because the unhandled
+ * reason is often a wrapper (`AbortError`) with the marked abort reason as
+ * its `cause`.
+ */
+export declare function isExpectedCleanupError(reason: unknown): boolean;
+/**
+ * Register an interceptor consulted before an unhandled rejection tears the
+ * process down. A consuming interceptor owns reporting and keeps the process alive.
+ */
+export declare function interceptUnhandledRejections(interceptor: (reason: unknown) => boolean): () => void;
+/**
+ * Register a synchronous recovery command to print when the process exits
+ * through an uncaught exception or unhandled rejection.
+ */
+export declare function registerFatalRecoveryHint(provider: FatalRecoveryHintProvider): () => void;
+/**
+ * Register a process cleanup callback, to be run on shutdown, signal, or fatal error.
+ *
+ * Returns a Callback instance that can be used to cancel (unregister) or manually clean up.
+ * If register is called after cleanup already began, invokes callback on a microtask.
+ */
+export declare function register(id: string, callback: (reason: Reason) => void | Promise<void>): () => void;
+/**
+ * Runs all cleanup callbacks without exiting.
+ * Use this in workers or when you need to clean up but continue execution.
+ */
+export declare function cleanup(): Promise<void>;
+/** Controls how manual process shutdown handles terminal output. */
+export interface QuitOptions {
+    /** Wait for buffered stdout before exiting; disable after the terminal has disconnected. */
+    drainStdout?: boolean;
+}
+/**
+ * Runs all cleanup callbacks and exits through the current `process.exit`.
+ *
+ * In main thread: waits for stdout drain unless disabled, then calls `process.exit()`.
+ * In workers: runs cleanup only (process.exit would kill entire process).
+ */
+export declare function quit(code?: number, options?: QuitOptions): Promise<void>;
+export {};

package/dist/types/process-name.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Set both the JS `process.title` and — on Linux — the kernel `comm` name.
+ *
+ * Never throws: `bun:ffi` unavailability or a failed syscall degrades silently
+ * to the `process.title`-only behavior, so it is safe to call at startup.
+ */
+export declare function setProcessName(name: string): void;

package/dist/types/procmgr.d.ts

@@ -0,0 +1,74 @@
+import type { Subprocess } from "bun";
+export interface ShellConfig {
+    shell: string;
+    args: string[];
+    env: Record<string, string>;
+    prefix: string | undefined;
+}
+/** Identifies the settings source users should edit when shell resolution fails. */
+export interface ShellConfigOptions {
+    /** File path or runtime layer that supplied the active shell setting. */
+    configSource?: string;
+}
+/**
+ * Check if a shell binary is executable.
+ */
+export declare function isExecutable(path: string): boolean;
+/**
+ * Get shell args for the resolved shell.
+ * cmd.exe takes `/c`; PowerShell (powershell.exe / pwsh) takes
+ * `-NoLogo -Command`, with `-NoProfile` when PI_BASH_NO_LOGIN /
+ * CLAUDE_BASH_NO_LOGIN is set (profile scripts are PowerShell's login-shell
+ * analog); POSIX shells take `-c`, with `-l` unless the same env is set.
+ *
+ * Exported for tests; `env` overrides the process env gate.
+ */
+export declare function getShellArgs(shell: string, env?: Record<string, string | undefined>): string[];
+/** Whether the shell is Windows cmd.exe (spawn paths must use `/c`, not `-c`). */
+export declare function isCmdShell(shell: string): boolean;
+/**
+ * Whether the shell is Windows PowerShell or PowerShell Core (pwsh). Spawn
+ * paths must use `-Command`: passing the POSIX `-l -c` pair makes PowerShell
+ * parse `-l` as the command and fail with `The term '-l' is not recognized`.
+ */
+export declare function isPowerShell(shell: string): boolean;
+/**
+ * Resolve a basic shell (bash or sh) as fallback.
+ */
+export declare function resolveBasicShell(): string | undefined;
+/**
+ * Resolve the external shell to advertise on Windows.
+ *
+ * A host bash is OPTIONAL: bash tool commands always execute in the embedded
+ * brush-core shell. The resolved binary only serves the spawn-a-shell paths
+ * (interactive PTY sessions, ACP client terminals, SHELL env), so this
+ * prefers a real Git Bash when one exists and otherwise falls back to
+ * cmd.exe — it never fails.
+ *
+ * Search order:
+ * 1. Git for Windows install roots (machine + per-user installers)
+ * 2. scoop installs — scoop's git manifest sets GIT_INSTALL_ROOT and shims
+ *    sh.exe/git.exe but never bash.exe, so PATH lookup alone misses it
+ * 3. bash.exe on PATH (Cygwin, MSYS2, ...)
+ * 4. sh.exe on PATH (Git for Windows' sh.exe is bash; prefer a sibling
+ *    bash.exe when present)
+ * 5. cmd.exe from ComSpec
+ *
+ * Exported for tests; `env` overrides Bun.env-based discovery.
+ */
+export declare function resolveWindowsShell(env?: Record<string, string | undefined>): string;
+/**
+ * Get shell configuration based on platform.
+ * Resolution order:
+ * 1. User-specified shellPath from the active settings source
+ * 2. On Windows: Git Bash / bash / sh discovery, then cmd.exe (see
+ *    {@link resolveWindowsShell}) — never fails
+ * 3. On Unix: $SHELL if bash/zsh, then fallback paths
+ * 4. Fallback: sh
+ */
+export declare function getShellConfig(customShellPath?: string, options?: ShellConfigOptions): ShellConfig;
+/**
+ * Check if a process is running.
+ */
+export declare function isPidRunning(pid: number | Subprocess): boolean;
+export declare function onProcessExit(proc: Subprocess | number, abortSignal?: AbortSignal): Promise<boolean>;

package/dist/types/prompt.d.ts

@@ -0,0 +1,18 @@
+import type { HelperDelegate, Template } from "./template.js";
+export type { HelperDelegate, HelperOptions, Template, TemplateDelegate } from "./template.js";
+export type PromptRenderPhase = "pre-render" | "post-render";
+export interface PromptFormatOptions {
+    renderPhase?: PromptRenderPhase;
+    replaceAsciiSymbols?: boolean;
+    normalizeRfc2119?: boolean;
+}
+export declare function format(content: string, options?: PromptFormatOptions): string;
+export interface TemplateContext extends Record<string, unknown> {
+    args?: string[];
+    ARGUMENTS?: string;
+    arguments?: string;
+}
+export declare function registerHelper(name: string, fn: HelperDelegate): void;
+export declare function registerPartial(name: string, fn: Template): void;
+export declare function compile(template: string): (context: TemplateContext) => string;
+export declare function render(template: string, context?: TemplateContext): string;

package/dist/types/ptree.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Process tree management utilities for Bun subprocesses.
+ *
+ * - Track managed child processes for cleanup on shutdown (postmortem).
+ * - Drain stdout/stderr to avoid subprocess pipe deadlocks.
+ * - Cross-platform tree kill for process groups (Windows taskkill, Unix -pid).
+ * - Convenience helpers: captureText / execText, AbortSignal, timeouts.
+ */
+import type { Spawn, Subprocess } from "bun";
+type InMask = "pipe" | "ignore" | Buffer | Uint8Array | null;
+/** A Bun subprocess with stdout/stderr always piped (stdin may vary). */
+type PipedSubprocess<In extends InMask = InMask> = Subprocess<In, "pipe", "pipe">;
+/**
+ * Base for all exceptions representing child process nonzero exit, killed, or
+ * cancellation.
+ */
+export declare abstract class Exception extends Error {
+    readonly exitCode: number;
+    readonly stderr: string;
+    constructor(message: string, exitCode: number, stderr: string);
+    abstract readonly aborted: boolean;
+}
+/** Exception for nonzero exit codes (not cancellation). */
+export declare class NonZeroExitError extends Exception {
+    static readonly MAX_TRACE: number;
+    constructor(exitCode: number, stderr: string);
+    get aborted(): boolean;
+}
+/** Exception for explicit process abortion (via signal). */
+export declare class AbortError extends Exception {
+    readonly reason: unknown;
+    constructor(reason: unknown, stderr: string);
+    get aborted(): boolean;
+}
+/** Exception for process timeout. */
+export declare class TimeoutError extends AbortError {
+    constructor(timeout: number, stderr: string);
+}
+/** Options for waiting for process exit and capturing output. */
+export interface WaitOptions {
+    allowNonZero?: boolean;
+    allowAbort?: boolean;
+    /** `full` requires upfront capture; `exec` enables it, while direct `spawn` callers pass `stderr: "full"`. */
+    stderr?: "full" | "buffer";
+}
+/** Result from wait and exec. */
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    ok: boolean;
+    exitError?: Exception;
+}
+/**
+ * ChildProcess wraps a managed subprocess, capturing stderr tail, providing
+ * cross-platform kill/detach logic plus AbortSignal integration.
+ *
+ * Stdout is exposed directly from the underlying Bun subprocess; consumers
+ * must read it (via text(), wait(), etc.) to prevent pipe deadlock.
+ * Stderr is eagerly drained into an internal buffer.
+ */
+export declare class ChildProcess<In extends InMask = InMask> {
+    #private;
+    readonly proc: PipedSubprocess<In>;
+    readonly exposeStderr: boolean;
+    constructor(proc: PipedSubprocess<In>, exposeStderr: boolean, retainFullStderr?: boolean);
+    get pid(): number;
+    get exited(): Promise<number>;
+    get exitCode(): number | null;
+    get exitReason(): Exception | undefined;
+    get killed(): boolean;
+    get stdin(): Bun.SpawnOptions.WritableToIO<In>;
+    /** Raw stdout stream. Must be consumed to prevent pipe deadlock. */
+    get stdout(): ReadableStream<Uint8Array<ArrayBuffer>>;
+    /** Optional stderr stream (only when requested in spawn options). */
+    get stderr(): ReadableStream<Uint8Array<ArrayBufferLike>> | undefined;
+    get exitedCleanly(): Promise<number>;
+    /** Returns the truncated stderr tail (last 32KB). */
+    peekStderr(): string;
+    nothrow(): this;
+    kill(reason?: Exception): void;
+    text(): Promise<string>;
+    blob(): Promise<Blob>;
+    json(): Promise<unknown>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    bytes(): Promise<Uint8Array>;
+    wait(opts?: WaitOptions): Promise<ExecResult>;
+    attachSignal(signal: AbortSignal): void;
+    attachTimeout(ms: number): void;
+    [Symbol.dispose](): void;
+}
+/** Options for child spawn. Always pipes stdout/stderr. */
+type ChildSpawnOptions<In extends InMask = InMask> = Omit<Spawn.SpawnOptions<In, "pipe", "pipe">, "stdout" | "stderr" | "detached"> & {
+    signal?: AbortSignal;
+    detached?: boolean;
+    /** Expose and retain complete stderr for a later `wait({ stderr: "full" })`. */
+    stderr?: "full" | null;
+};
+/** Spawn a child process with piped stdout/stderr. */
+export declare function spawn<In extends InMask = InMask>(cmd: string[], opts?: ChildSpawnOptions<In>): ChildProcess<In>;
+/** Options for exec. */
+export interface ExecOptions extends Omit<ChildSpawnOptions, "stderr" | "stdin">, WaitOptions {
+    input?: string | Buffer | Uint8Array;
+}
+/** Spawn, wait, and return captured output. */
+export declare function exec(cmd: string[], opts?: ExecOptions): Promise<ExecResult>;
+type SignalValue = AbortSignal | number | null | undefined;
+/** Combine AbortSignals and timeout values into a single signal. */
+export declare function combineSignals(...signals: SignalValue[]): AbortSignal | undefined;
+export {};

package/dist/types/readability/readability.d.ts

@@ -0,0 +1,9 @@
+/** Behavior-compatible reimplementation of @mozilla/readability's used surface. */
+import type { ReadabilityArticle, ReadabilityDocument, ReadabilityOptions } from "./types.js";
+/** Extracts the article body and metadata from a standards-shaped document. */
+export declare class Readability<T = string> {
+    #private;
+    constructor(document: ReadabilityDocument, options?: ReadabilityOptions<T>);
+    /** Runs extraction once; the supplied document is consumed and should not be reused. */
+    parse(): ReadabilityArticle<T> | null;
+}

package/dist/types/readability/readerable.d.ts

@@ -0,0 +1,10 @@
+/** Behavior-compatible reimplementation of @mozilla/readability's used surface. */
+import type { ReadabilityDocument, ReadabilityNode } from "./types.js";
+/** Options for the inexpensive readerability estimate. */
+export interface ReaderableOptions {
+    minContentLength?: number;
+    minScore?: number;
+    visibilityChecker?: (node: ReadabilityNode) => boolean;
+}
+/** Estimates whether a document contains enough prose for article extraction. */
+export declare function isProbablyReaderable(document: ReadabilityDocument, options?: ReaderableOptions | ((node: ReadabilityNode) => boolean)): boolean;

package/dist/types/readability/types.d.ts

@@ -0,0 +1,70 @@
+/** Behavior-compatible reimplementation of @mozilla/readability's used surface. */
+/** Minimal standards-shaped DOM node accepted by the readability extractor. */
+export interface ReadabilityNode {
+    readonly nodeType: number;
+    readonly nodeName: string;
+    readonly tagName?: string;
+    readonly ownerDocument?: ReadabilityDocument | null;
+    parentNode: ReadabilityNode | null;
+    readonly children?: ArrayLike<ReadabilityElement>;
+    readonly childNodes: ArrayLike<ReadabilityNode>;
+    readonly firstChild: ReadabilityNode | null;
+    readonly textContent: string | null;
+    appendChild(node: ReadabilityNode): ReadabilityNode;
+    cloneNode(deep?: boolean): ReadabilityNode;
+    remove(): void;
+}
+/** Minimal standards-shaped DOM element accepted by the readability extractor. */
+export interface ReadabilityElement extends ReadabilityNode {
+    readonly children: ArrayLike<ReadabilityElement>;
+    readonly tagName: string;
+    id: string;
+    className: string;
+    innerHTML: string;
+    readonly attributes: ArrayLike<{
+        readonly name: string;
+        readonly value: string;
+    }>;
+    getAttribute(name: string): string | null;
+    hasAttribute(name: string): boolean;
+    setAttribute(name: string, value: string): void;
+    removeAttribute(name: string): void;
+    getElementsByTagName(name: string): ArrayLike<ReadabilityElement>;
+    querySelector(selector: string): ReadabilityElement | null;
+    querySelectorAll(selector: string): ArrayLike<ReadabilityElement>;
+}
+/** Minimal standards-shaped document accepted by the readability extractor. */
+export interface ReadabilityDocument extends ReadabilityNode {
+    title: string;
+    readonly body: ReadabilityElement | null;
+    readonly documentElement: ReadabilityElement | null;
+    createElement(name: string): ReadabilityElement;
+    getElementsByTagName(name: string): ArrayLike<ReadabilityElement>;
+    querySelector(selector: string): ReadabilityElement | null;
+    querySelectorAll(selector: string): ArrayLike<ReadabilityElement>;
+}
+/** Configuration for article extraction. */
+export interface ReadabilityOptions<T = string> {
+    debug?: boolean;
+    maxElemsToParse?: number;
+    nbTopCandidates?: number;
+    charThreshold?: number;
+    classesToPreserve?: string[];
+    keepClasses?: boolean;
+    serializer?: (node: ReadabilityNode) => T;
+    disableJSONLD?: boolean;
+    allowedVideoRegex?: RegExp;
+}
+/** Extracted article and metadata. */
+export interface ReadabilityArticle<T = string> {
+    title: string | null | undefined;
+    content: T | null | undefined;
+    textContent: string | null | undefined;
+    length: number | null | undefined;
+    excerpt: string | null | undefined;
+    byline: string | null | undefined;
+    dir: string | null | undefined;
+    siteName: string | null | undefined;
+    lang: string | null | undefined;
+    publishedTime: string | null | undefined;
+}

package/dist/types/readability.d.ts

@@ -0,0 +1,4 @@
+/** Behavior-compatible reimplementation of @mozilla/readability's used surface. */
+export { Readability } from "./readability/readability.js";
+export { isProbablyReaderable, type ReaderableOptions } from "./readability/readerable.js";
+export type { ReadabilityArticle, ReadabilityDocument, ReadabilityElement, ReadabilityNode, ReadabilityOptions, } from "./readability/types.js";

package/dist/types/ring.d.ts

@@ -0,0 +1,93 @@
+/**
+ * A fixed-capacity circular buffer that supports efficient push/pop/shift/unshift operations.
+ * When the buffer is full, adding new items overwrites the oldest items (FIFO behavior).
+ *
+ * @template T The type of elements stored in the buffer.
+ */
+export declare class RingBuffer<T> {
+    #private;
+    readonly capacity: number;
+    /**
+     * Creates a new ring buffer with the specified capacity.
+     *
+     * @param capacity - The maximum number of elements the buffer can hold. Must be positive.
+     */
+    constructor(capacity: number);
+    /**
+     * The number of elements currently in the buffer.
+     */
+    get length(): number;
+    /**
+     * Whether the buffer is at full capacity.
+     */
+    get isFull(): boolean;
+    /**
+     * Whether the buffer is empty (contains no elements).
+     */
+    get isEmpty(): boolean;
+    /**
+     * Adds an item to the end of the buffer.
+     * If the buffer is full, the oldest item is overwritten and returned.
+     *
+     * @param item - The item to add.
+     * @returns The overwritten item if the buffer was full, otherwise `undefined`.
+     */
+    push(item: T): T | undefined;
+    /**
+     * Removes and returns the first (oldest) item from the buffer.
+     *
+     * @returns The removed item, or `undefined` if the buffer is empty.
+     */
+    shift(): T | undefined;
+    /**
+     * Removes and returns the last (newest) item from the buffer.
+     *
+     * @returns The removed item, or `undefined` if the buffer is empty.
+     */
+    pop(): T | undefined;
+    /**
+     * Adds an item to the beginning of the buffer.
+     * If the buffer is full, the newest item is overwritten and returned.
+     *
+     * @param item - The item to add.
+     * @returns The overwritten item if the buffer was full, otherwise `undefined`.
+     */
+    unshift(item: T): T | undefined;
+    /**
+     * Returns the element at the specified index without removing it.
+     * Supports negative indices (e.g., `-1` for the last element).
+     *
+     * @param index - The zero-based index, or negative index from the end.
+     * @returns The element at the index, or `undefined` if the index is out of bounds.
+     */
+    at(index: number): T | undefined;
+    /**
+     * Returns the first (oldest) element without removing it.
+     *
+     * @returns The first element, or `undefined` if the buffer is empty.
+     */
+    peek(): T | undefined;
+    /**
+     * Returns the last (newest) element without removing it.
+     *
+     * @returns The last element, or `undefined` if the buffer is empty.
+     */
+    peekBack(): T | undefined;
+    /**
+     * Removes all elements from the buffer, resetting it to an empty state.
+     */
+    clear(): void;
+    /**
+     * Returns an iterator that yields elements in logical order (oldest to newest).
+     * Allows the buffer to be used with `for...of` loops and spread syntax.
+     *
+     * @yields Elements in FIFO order.
+     */
+    [Symbol.iterator](): Iterator<T>;
+    /**
+     * Creates a new array containing all elements in logical order (oldest to newest).
+     *
+     * @returns A new array with all buffer elements.
+     */
+    toArray(): T[];
+}

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

@@ -0,0 +1,78 @@
+/**
+ * Walk a conditional `exports` target (string, array of fallbacks, or a
+ * condition object) and return the first relative path that matches a runtime
+ * condition in declaration order. Returns `null` when nothing applies (e.g.
+ * an `import`-only entry).
+ */
+export declare function selectConditionalTarget(target: unknown): string | null;
+/**
+ * Split a bare specifier into its package name and optional subpath, handling
+ * scoped packages (`@scope/name/sub` → `@scope/name` + `sub`).
+ */
+export declare function splitBareSpecifier(specifier: string): {
+    packageName: string;
+    subpath: string | undefined;
+};
+/**
+ * Resolve a bare specifier against an installed `node_modules` directory,
+ * honoring `exports` (CommonJS conditions), then `main`, then `index.js`.
+ * Returns an absolute file path, or `null` when the package/entry is absent.
+ */
+export declare function resolveRuntimeModule(runtimeNodeModules: string, specifier: string): string | null;
+export interface RuntimeResolverOptions {
+    /** Absolute path to the runtime cache's `node_modules`. */
+    runtimeNodeModules: string;
+    /** Bare specifier → absolute file path overrides (e.g. `sharp` → no-op stub). */
+    stubs?: Record<string, string>;
+}
+/**
+ * Patch `node:module`'s resolver (idempotently) so bare specifiers that the
+ * stock compiled-binary resolver cannot find fall back to the registered
+ * runtime caches. Stock resolution is tried first and kept for anything
+ * outside the registered roots (bundled imports, node builtins, host or
+ * extension trees). Multiple runtime roots may register; they are consulted
+ * in registration order. Returns an uninstaller that drops the registration
+ * and restores the stock resolver once no registrations remain.
+ *
+ * One stock "success" is distrusted: the compiled-binary resolver ignores
+ * `main`/`exports` for real-FS packages (Bun #1763), so a package shipping
+ * its TS source next to `dist/` (e.g. `@huggingface/hub`'s root `index.ts`)
+ * resolves to the wrong file. When the stock hit lands inside a registered
+ * runtime root, the manifest-aware resolution wins.
+ *
+ * KNOWN LIMITATION (Bun 1.3.14): while any JS override of
+ * `Module._resolveFilename` is installed, Bun routes `createRequire(...)`
+ * resolution through it with `parent === undefined` — the requester context is
+ * never passed, so relative requires from a `createRequire` require fail with
+ * "Cannot find module './x' from ''". The override cannot recover what it is
+ * never given. Keep this patch scoped to dedicated worker/runtime processes
+ * (tiny-inference, fastembed); never install it in the main agent process,
+ * where legacy-pi extensions rely on `createRequire` relative requires.
+ */
+export declare function installRuntimeModuleResolver({ runtimeNodeModules, stubs }: RuntimeResolverOptions): () => void;
+/** Pinned dependency set materialized into a runtime cache directory. */
+export interface RuntimeInstallSpec {
+    dependencies: Record<string, string>;
+    /** Version pins forced across the whole runtime tree (bun `overrides`), e.g. dislodging a transitive dep. */
+    overrides?: Record<string, string>;
+    /** Packages whose lifecycle scripts bun may run during the install. */
+    trustedDependencies?: string[];
+}
+export type RuntimeInstallPhase = "initiate" | "download" | "done";
+export interface EnsureRuntimeInstalledOptions {
+    /** Directory owning the runtime `package.json` + `node_modules`. */
+    runtimeDir: string;
+    install: RuntimeInstallSpec;
+    /** Package whose installed manifest marks the runtime complete; defaults to the first dependency. */
+    probePackage?: string;
+    /** Phase notifications (progress UI); not emitted when already installed. */
+    onPhase?: (phase: RuntimeInstallPhase) => void;
+    lockAttempts?: number;
+    lockSleepMs?: number;
+}
+export declare function writeRuntimeManifest(runtimeDir: string, install: RuntimeInstallSpec): Promise<void>;
+/**
+ * Materialize a pinned dependency set into `runtimeDir` (idempotent,
+ * cross-process safe via a lock directory). Returns `runtimeDir`.
+ */
+export declare function ensureRuntimeInstalled(options: EnsureRuntimeInstalledOptions): Promise<string>;

package/dist/types/sanitize-text.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Strip ANSI escape sequences, remove control characters / lone surrogates,
+ * and normalize line endings.
+ *
+ * Bun-native implementation of the former native `sanitizeText` (see
+ * `crates/pi-natives/src/text.rs::sanitize_text`). JavaScript strings are
+ * already UTF-16 code-unit arrays. `toWellFormed()` handles the uncommon
+ * malformed path; when it changes the input, replacement characters are
+ * dropped and the normalized result goes through the well-formed sanitizer.
+ *
+ * Fast path: well-formed input with no controls or ANSI returns the original
+ * string after the control probe.
+ */
+export declare function sanitizeText(text: string): string;
+/**
+ * Escape the three XML-significant characters (`&`, `<`, `>`) in text destined
+ * for an XML/markup element body. Allocation-conscious: returns the input
+ * unchanged (same reference) when nothing needs escaping. Quotes are left as-is
+ * — use it for element text, not attribute values.
+ */
+export declare function escapeXmlText(input: string): string;
+/**
+ * Escape XML-significant characters for an attribute VALUE: the three body
+ * characters (`&`, `<`, `>`) plus the double quote (`"` → `&quot;`) that would
+ * otherwise close the attribute. Allocation-conscious: returns the input
+ * unchanged (same reference) when nothing needs escaping. Use it for attribute
+ * values; {@link escapeXmlText} is for element bodies and leaves `"` intact.
+ */
+export declare function escapeXmlAttribute(input: string): string;

package/dist/types/snowflake.d.ts

@@ -0,0 +1,25 @@
+type Snowflake = string & {
+    readonly __brand: unique symbol;
+};
+declare namespace Snowflake {
+    const PATTERN: RegExp;
+    const EPOCH_TIMESTAMP = 1420070400000;
+    const MAX_SEQUENCE = 4194303;
+    function formatParts(dt: number, seq: number): Snowflake;
+    class Source {
+        #private;
+        constructor(sequence?: number);
+        get sequence(): number;
+        set sequence(v: number);
+        reset(): void;
+        generate(timestamp: number): Snowflake;
+    }
+    function next(timestamp?: number): Snowflake;
+    function valid(value: string): value is Snowflake;
+    function lowerbound(timelike: Date | number | Snowflake): Snowflake;
+    function upperbound(timelike: Date | number | Snowflake): Snowflake;
+    function getSequence(value: Snowflake): number;
+    function getTimestamp(value: Snowflake): number;
+    function getDate(value: Snowflake): Date;
+}
+export { Snowflake };

package/dist/types/stderr-guard.d.ts

@@ -0,0 +1,22 @@
+export interface SuppressTerminalStderrOptions {
+    /** Redirect target path; defaults to today's omp log file, then /dev/null. */
+    redirectPath?: string;
+    /** Bypass the macOS + same-terminal gate. Tests only. */
+    force?: boolean;
+}
+/**
+ * Redirect fd 2 away from the terminal while the TUI owns the viewport.
+ * Returns true when suppression is (already) active. No-op — returning
+ * false — off macOS, when stderr does not target the stdout terminal, or
+ * when the libc fd ops are unavailable.
+ */
+export declare function suppressTerminalStderr(options?: SuppressTerminalStderrOptions): boolean;
+/**
+ * Re-point fd 2 at the saved terminal stderr. Safe to call unconditionally:
+ * no-op when suppression is not active. Called at every terminal-ownership
+ * release and by the postmortem fatal handlers before they print, so crash
+ * reports reach the real terminal.
+ */
+export declare function restoreTerminalStderr(): void;
+/** Whether fd 2 is currently redirected away from the terminal. */
+export declare function isTerminalStderrSuppressed(): boolean;