@linxiraos/pi-utils 1.0.0

package/dist/types/dom/core.d.ts

@@ -0,0 +1,431 @@
+/** Behavior-compatible reimplementation of linkedom's used surface. */
+/** DOM node type constants. */
+export declare const enum NodeType {
+    ELEMENT = 1,
+    ATTRIBUTE = 2,
+    TEXT = 3,
+    COMMENT = 8,
+    DOCUMENT = 9,
+    DOCUMENT_FRAGMENT = 11
+}
+interface EventInit {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+}
+interface CustomEventInit<T> extends EventInit {
+    detail?: T;
+}
+interface ElementCreationOptions {
+    is?: string;
+}
+type FrameRequestCallback = (time: number) => void;
+/** Minimal browser event implementation. */
+export declare class Event {
+    #private;
+    type: string;
+    bubbles: boolean;
+    cancelable: boolean;
+    target: EventTarget | null;
+    currentTarget: EventTarget | null;
+    defaultPrevented: boolean;
+    constructor(type: string, init?: EventInit);
+    /** Initialize an event created through Document.createEvent. */
+    initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void;
+    /** Cancel this event when it is cancelable. */
+    preventDefault(): void;
+    /** Stop bubbling this event. */
+    stopPropagation(): void;
+    /** Whether propagation has been stopped. */
+    get propagationStopped(): boolean;
+}
+/** Browser custom event carrying a detail value. */
+export declare class CustomEvent<T = unknown> extends Event {
+    readonly detail: T | undefined;
+    constructor(type: string, init?: CustomEventInit<T>);
+}
+type EventListener = ((event: Event) => void) | {
+    handleEvent(event: Event): void;
+};
+/** Minimal event-target implementation used by DOM nodes and window. */
+export declare class EventTarget {
+    #private;
+    /** Register an event listener. */
+    addEventListener(type: string, listener: EventListener | null): void;
+    /** Remove an event listener. */
+    removeEventListener(type: string, listener: EventListener | null): void;
+    /** Dispatch an event to listeners and optionally through node ancestors. */
+    dispatchEvent(event: Event): boolean;
+}
+/** Base class for the implemented DOM tree. */
+export declare class Node extends EventTarget {
+    static readonly ELEMENT_NODE = NodeType.ELEMENT;
+    static readonly ATTRIBUTE_NODE = NodeType.ATTRIBUTE;
+    static readonly TEXT_NODE = NodeType.TEXT;
+    static readonly COMMENT_NODE = NodeType.COMMENT;
+    static readonly DOCUMENT_NODE = NodeType.DOCUMENT;
+    static readonly DOCUMENT_FRAGMENT_NODE = NodeType.DOCUMENT_FRAGMENT;
+    readonly nodeType: number;
+    readonly nodeName: string;
+    parentNode: Node | null;
+    ownerDocument: Document | null;
+    childNodes: Node[];
+    constructor(nodeType: number, nodeName: string, ownerDocument?: Document | null);
+    /** First child node, if present. */
+    get firstChild(): Node | null;
+    /** Last child node, if present. */
+    get lastChild(): Node | null;
+    /** Previous node with the same parent. */
+    get previousSibling(): Node | null;
+    /** Next node with the same parent. */
+    get nextSibling(): Node | null;
+    /** Connectedness to a document. */
+    get isConnected(): boolean;
+    /** Node value for character-data nodes. */
+    get nodeValue(): string | null;
+    set nodeValue(_value: string | null);
+    /** Text contained by this node. */
+    get textContent(): string | null;
+    set textContent(value: string | null);
+    /** Parent element, excluding document and fragments. */
+    get parentElement(): Element | null;
+    /** Append a node, moving it from its old parent. */
+    appendChild<T extends Node>(child: T): T;
+    /** Insert a node before a current child, or append for null. */
+    insertBefore<T extends Node>(child: T, reference: Node | null): T;
+    /** Replace a current child with another node. */
+    replaceChild<T extends Node>(child: Node, previous: T): T;
+    /** Remove a current child. */
+    removeChild<T extends Node>(child: T): T;
+    /** Replace all children with nodes or strings. */
+    replaceChildren(...children: Array<Node | string>): void;
+    /** Append nodes or strings. */
+    append(...children: Array<Node | string>): void;
+    /** Prepend nodes or strings. */
+    prepend(...children: Array<Node | string>): void;
+    /** Remove this node from its parent. */
+    remove(): void;
+    /** Replace this node in its parent. */
+    replaceWith(...nodes: Array<Node | string>): void;
+    /** Whether this node contains another node. */
+    contains(other: Node | null): boolean;
+    /** Clone this node, optionally including descendants. */
+    cloneNode(deep?: boolean): Node;
+    /** Compare tree position sufficiently for document-order consumers. */
+    compareDocumentPosition(other: Node): number;
+    setOwnerDocument(document: Document): void;
+    documentForCreation(): Document;
+}
+/** Text node. */
+export declare class Text extends Node {
+    data: string;
+    serializeRaw: boolean;
+    constructor(data: string, ownerDocument?: Document | null, serializeRaw?: boolean);
+    /** Number of UTF-16 code units. */
+    get length(): number;
+    get nodeValue(): string;
+    set nodeValue(value: string | null);
+    get textContent(): string;
+    set textContent(value: string | null);
+    /** Split this text node at an offset. */
+    splitText(offset: number): Text;
+    cloneNode(): Text;
+}
+/** Comment node. */
+export declare class Comment extends Text {
+    constructor(data: string, ownerDocument?: Document | null);
+    cloneNode(): Comment;
+}
+/** DOM attribute value object. */
+export declare class Attr extends Node {
+    readonly name: string;
+    value: string;
+    readonly namespaceURI: string | null;
+    constructor(name: string, value: string, ownerDocument?: Document | null, namespaceURI?: string | null);
+    get nodeValue(): string;
+    set nodeValue(value: string | null);
+    get textContent(): string;
+    set textContent(value: string | null);
+    cloneNode(): Attr;
+}
+/** Array-like attribute collection. */
+export declare class NamedNodeMap extends Array<Attr> {
+    /** Find an attribute case-insensitively. */
+    getNamedItem(name: string): Attr | null;
+    /** Set an attribute object and return the prior one. */
+    setNamedItem(attr: Attr): Attr | null;
+    /** Remove and return a named attribute. */
+    removeNamedItem(name: string): Attr;
+}
+/** Token-list view over an element class attribute. */
+export declare class DOMTokenList implements Iterable<string> {
+    #private;
+    constructor(element: Element);
+    /** Token count. */
+    get length(): number;
+    /** String representation. */
+    get value(): string;
+    set value(value: string);
+    /** Add class tokens. */
+    add(...tokens: string[]): void;
+    /** Remove class tokens. */
+    remove(...tokens: string[]): void;
+    /** Whether a class token exists. */
+    contains(token: string): boolean;
+    /** Toggle a class token. */
+    toggle(token: string, force?: boolean): boolean;
+    /** Replace one class token with another. */
+    replace(previous: string, next: string): boolean;
+    /** Token at an index. */
+    item(index: number): string | null;
+    [Symbol.iterator](): Iterator<string>;
+    toString(): string;
+}
+/** Mutable inline style declaration. */
+export declare class CSSStyleDeclaration {
+    #private;
+    /** Serialized declarations. */
+    get cssText(): string;
+    set cssText(value: string);
+    /** Read a CSS property. */
+    getPropertyValue(name: string): string;
+    /** Set a CSS property. */
+    setProperty(name: string, value: string | null, _priority?: string): void;
+    /** Remove and return a CSS property. */
+    removeProperty(name: string): string;
+}
+/** DOM element with attributes, selectors, and HTML serialization. */
+export declare class Element extends Node {
+    readonly localName: string;
+    readonly tagName: string;
+    readonly namespaceURI: string | null;
+    readonly qualifiedName: string;
+    readonly attributes: NamedNodeMap;
+    readonly classList: DOMTokenList;
+    readonly style: CSSStyleDeclaration;
+    constructor(tagName: string, ownerDocument?: Document | null, namespaceURI?: string | null);
+    /** Element children. */
+    get children(): Element[];
+    /** First element child. */
+    get firstElementChild(): Element | null;
+    /** Last element child. */
+    get lastElementChild(): Element | null;
+    /** Previous sibling that is an element. */
+    get previousElementSibling(): Element | null;
+    /** Next sibling that is an element. */
+    get nextElementSibling(): Element | null;
+    /** Attribute-backed element id. */
+    get id(): string;
+    set id(value: string);
+    /** Attribute-backed class string. */
+    get className(): string;
+    set className(value: string);
+    /** Data attributes exposed as camel-cased properties. */
+    get dataset(): Record<string, string>;
+    /** Linkedom-compatible legacy text property (only specialized elements define a value). */
+    get text(): string | undefined;
+    /** HTML contained inside this element. */
+    get innerHTML(): string;
+    set innerHTML(value: string);
+    /** Serialized element and descendants. */
+    get outerHTML(): string;
+    set outerHTML(value: string);
+    /** Read an attribute. */
+    getAttribute(name: string): string | null;
+    /** Read an attribute object. */
+    getAttributeNode(name: string): Attr | null;
+    /** Whether an attribute exists. */
+    hasAttribute(name: string): boolean;
+    /** Set an attribute. */
+    setAttribute(name: string, value: string): void;
+    /** Set a namespaced attribute. */
+    setAttributeNS(_namespace: string | null, name: string, value: string): void;
+    /** Remove an attribute. */
+    removeAttribute(name: string): void;
+    /** Find the first descendant matching a selector. */
+    querySelector(selector: string): Element | null;
+    /** Find all descendants matching a selector. */
+    querySelectorAll(selector: string): Element[];
+    /** Whether this element matches a selector. */
+    matches(selector: string): boolean;
+    /** Find the nearest matching ancestor including this element. */
+    closest(selector: string): Element | null;
+    /** Descendant elements with a tag name. */
+    getElementsByTagName(tagName: string): Element[];
+    /** Descendant elements containing all requested class tokens. */
+    getElementsByClassName(classNames: string): Element[];
+    /**
+     * Return a zero-sized rectangle because this parser DOM has no layout.
+     * Browser-side scripts only use this method's standard shape.
+     */
+    getBoundingClientRect(): {
+        x: number;
+        y: number;
+        bottom: number;
+        height: number;
+        left: number;
+        right: number;
+        top: number;
+        width: number;
+    };
+    /** Focus this element in its owner document. */
+    focus(): void;
+    /** Clear focus from this element. */
+    blur(): void;
+    /** Trigger a synthetic click event. */
+    click(): void;
+    cloneNode(deep?: boolean): Element;
+}
+/** HTML element implementation. */
+export declare class HTMLElement extends Element {
+    value: string;
+    checked: boolean;
+    selected: boolean;
+    disabled: boolean;
+    multiple: boolean;
+    defaultValue: string;
+    defaultChecked: boolean;
+    /** Reflected title attribute. */
+    get title(): string;
+    set title(value: string);
+    /** Reflected href attribute. */
+    get href(): string;
+    set href(value: string);
+    /** Reflected input type. */
+    get type(): string;
+    set type(value: string);
+    /** Reflected name. */
+    get name(): string;
+    set name(value: string);
+}
+/** HTML meta element with a reflected content attribute. */
+export declare class HTMLMetaElement extends HTMLElement {
+    /** Reflected metadata content. */
+    get content(): string;
+    set content(value: string);
+}
+/** SVG element marker used by React feature checks. */
+export declare class SVGElement extends Element {
+}
+/** Iframe element marker used by React selection restoration. */
+export declare class HTMLIFrameElement extends HTMLElement {
+}
+/** Document fragment. */
+export declare class DocumentFragment extends Node {
+    constructor(ownerDocument?: Document | null);
+    /** Element children. */
+    get children(): Element[];
+    /** First element child. */
+    get firstElementChild(): Element | null;
+    /** Last element child. */
+    get lastElementChild(): Element | null;
+    /** First matching descendant. */
+    querySelector(selector: string): Element | null;
+    /** All matching descendants. */
+    querySelectorAll(selector: string): Element[];
+    cloneNode(deep?: boolean): DocumentFragment;
+}
+/** HTML template whose parsed descendants live in a document fragment. */
+export declare class HTMLTemplateElement extends HTMLElement {
+    readonly content: DocumentFragment;
+    constructor(tagName: string, ownerDocument?: Document | null, namespaceURI?: string | null);
+    get innerHTML(): string;
+    set innerHTML(value: string);
+    get textContent(): string;
+    set textContent(value: string | null);
+    appendChild<T extends Node>(child: T): T;
+    insertBefore<T extends Node>(child: T, reference: Node | null): T;
+    replaceChild<T extends Node>(child: Node, previous: T): T;
+    removeChild<T extends Node>(child: T): T;
+    cloneNode(deep?: boolean): HTMLTemplateElement;
+}
+/** Minimal HTML document. */
+export declare class Document extends Node {
+    defaultView: DOMWindow | null;
+    URL: string;
+    activeElement: Element | null;
+    constructor();
+    /** Root element of the document. */
+    get documentElement(): Element | null;
+    /** Element children. */
+    get children(): Element[];
+    /** HTML body, or a detached empty body when absent like linkedom. */
+    get body(): HTMLElement;
+    /** HTML head, or a detached empty head when absent. */
+    get head(): HTMLElement;
+    /** Document title text. */
+    get title(): string;
+    set title(value: string);
+    get textContent(): null;
+    set textContent(_value: string | null);
+    /** Create an HTML element. */
+    createElement(tagName: string, _options?: ElementCreationOptions): HTMLElement;
+    /** Create a namespaced element. */
+    createElementNS(namespace: string | null, tagName: string): Element;
+    /** Create a text node. */
+    createTextNode(data: string): Text;
+    /** Create a comment. */
+    createComment(data: string): Comment;
+    /** Create an attribute. */
+    createAttribute(name: string): Attr;
+    /** Create a document fragment. */
+    createDocumentFragment(): DocumentFragment;
+    /** Find the first element by id. */
+    getElementById(id: string): HTMLElement | null;
+    /** Find the first matching descendant. */
+    querySelector(selector: string): Element | null;
+    /** Find all matching descendants. */
+    querySelectorAll(selector: string): Element[];
+    /** Descendant elements with a tag name. */
+    getElementsByTagName(tagName: string): Element[];
+    /** Descendant elements containing all class tokens. */
+    getElementsByClassName(classNames: string): Element[];
+    /** Adopt a node into this document. */
+    adoptNode<T extends Node>(node: T): T;
+    /** Import a cloned node into this document. */
+    importNode<T extends Node>(node: T, deep?: boolean): T;
+    /** Legacy event factory used by libraries. */
+    createEvent(_kind: string): Event;
+    cloneNode(deep?: boolean): Document;
+}
+/** Window shape returned by parseHTML. */
+export declare class DOMWindow extends EventTarget {
+    readonly document: Document;
+    readonly Node: typeof Node;
+    readonly Element: typeof Element;
+    readonly HTMLElement: typeof HTMLElement;
+    readonly HTMLIFrameElement: typeof HTMLIFrameElement;
+    readonly SVGElement: typeof SVGElement;
+    readonly Text: typeof Text;
+    readonly Comment: typeof Comment;
+    readonly Document: typeof Document;
+    readonly DocumentFragment: typeof DocumentFragment;
+    readonly Event: typeof Event;
+    readonly CustomEvent: typeof CustomEvent;
+    readonly navigator: {
+        userAgent: string;
+        platform: string;
+    };
+    readonly location: {
+        href: string;
+    };
+    readonly window: DOMWindow;
+    readonly self: DOMWindow;
+    readonly top: DOMWindow;
+    readonly parent: DOMWindow;
+    constructor(document: Document);
+    /** Browser-compatible computed style placeholder. */
+    getComputedStyle(element: Element): CSSStyleDeclaration;
+    /** Schedule an animation callback. */
+    requestAnimationFrame(callback: FrameRequestCallback): number;
+    /** Cancel an animation callback. */
+    cancelAnimationFrame(handle: number): void;
+    /** Empty selection object. */
+    getSelection(): {
+        rangeCount: number;
+        removeAllRanges(): void;
+    };
+}
+/** Serialize a DOM node as HTML. */
+export declare function serializeNode(node: Node): string;
+export {};

package/dist/types/dom/parser.d.ts

@@ -0,0 +1,7 @@
+import { Document, type DocumentFragment } from "./core.js";
+/** Decode common named entities and all valid numeric character references. */
+export declare function decodeEntities(value: string): string;
+/** Parse markup into a document fragment. */
+export declare function parseFragment(html: string, document: Document, contextTag?: string): DocumentFragment;
+/** Parse markup directly into a document. */
+export declare function parseDocument(html: string): Document;

package/dist/types/dom/selector.d.ts

@@ -0,0 +1,5 @@
+import { type Document, type DocumentFragment, Element } from "./core.js";
+/** Whether an element matches a CSS selector list. */
+export declare function matchesSelector(element: Element, selector: string): boolean;
+/** Query descendants of a node in document order. */
+export declare function querySelectorAllFrom(root: Document | DocumentFragment | Element, selector: string, includeRoot: boolean): Element[];

package/dist/types/dom.d.ts

@@ -0,0 +1,5 @@
+/** Behavior-compatible reimplementation of linkedom's used surface. */
+import { DOMWindow } from "./dom/core.js";
+export { Attr, Comment, CSSStyleDeclaration, CustomEvent, DOMTokenList, DOMWindow, Document, DocumentFragment, Element, Event, EventTarget, HTMLElement, HTMLIFrameElement, HTMLMetaElement, HTMLTemplateElement, NamedNodeMap, Node, NodeType, SVGElement, serializeNode, Text, } from "./dom/core.js";
+/** Parse HTML or XML-like markup into a lightweight window and document. */
+export declare function parseHTML(html: string): DOMWindow;

package/dist/types/env.d.ts

@@ -0,0 +1,124 @@
+export * from "./worker-host.js";
+/**
+ * Strict shell-identifier shape. Used for dotenv keys we accept into
+ * `Bun.env` — those should be referenceable as `$NAME` from POSIX shells,
+ * so we reject anything outside `[A-Za-z_][A-Za-z0-9_]*`.
+ */
+export declare function isValidEnvName(name: string): boolean;
+/**
+ * The only names that are genuinely unsafe to forward to a native `execve`
+ * spawn: empty, containing `=` (would corrupt the `KEY=VALUE` framing) or
+ * NUL (terminates the C string mid-entry). Windows ships standard variables
+ * whose names contain parentheses (e.g. `ProgramFiles(x86)`, `CommonProgramFiles(x86)`)
+ * — those MUST survive the scrub so downstream resolvers (Git Bash discovery
+ * in `procmgr.ts`, etc.) can still read them.
+ */
+export declare function isSafeEnvName(name: string): boolean;
+export declare function isSafeEnvValue(value: string): boolean;
+export declare function isMacosMallocStackLoggingEnvName(name: string): boolean;
+export declare function filterProcessEnv(env: Record<string, string | undefined>): Record<string, string>;
+/** Filters process env for child shells without launch-cwd dotenv values. */
+export declare function filterChildShellEnv(env: Record<string, string | undefined>, cwd?: string): Record<string, string>;
+/**
+ * Parses a .env file synchronously into key-value string pairs using
+ * {@link parseEnvLine} for Bun-compatible line semantics, then mirrors valid
+ * `OMP_` variables to their `PI_` aliases.
+ */
+export declare function parseEnvFile(filePath: string): Record<string, string>;
+/**
+ * Intentional re-export of Bun.env.
+ *
+ * All users should import this env module (import { $env } from "@linxiraos/pi-utils")
+ * before using environment variables. This ensures that .env files have been loaded and
+ * overrides (project, home) have been applied, so $env always reflects the correct values.
+ */
+export declare const $env: Record<string, string>;
+/**
+ * Resolve the first environment variable value from the given keys.
+ * @param keys - The keys to resolve.
+ * @returns The first environment variable value, or undefined if no value is found.
+ */
+export declare function $pickenv(...keys: string[]): string | undefined;
+/**
+ * Read an environment variable by its EXACT, case-sensitive name.
+ *
+ * `process.env` / `Bun.env` lookups are case-insensitive on Windows (Node backs
+ * them with `uv_os_getenv`, Bun with a `CaseInsensitiveASCIIStringArrayHashMap`),
+ * so a lowercase literal like `public` silently resolves to a differently-cased
+ * system variable — Windows ships `PUBLIC=C:\Users\Public`. Enumerated keys are
+ * the only signal that preserves the real casing, so this trusts the lookup only
+ * when a key with identical casing is actually present. On POSIX (case-sensitive
+ * env) it is equivalent to a direct lookup.
+ *
+ * Use this instead of `process.env[name] ?? literal` wherever `name` may be a
+ * user-supplied literal (e.g. a stored API key) rather than a genuine env-var
+ * reference — otherwise the literal gets hijacked by a same-named system var.
+ *
+ * @param name - Environment variable name to look up.
+ * @param env - Environment source; defaults to `process.env`.
+ */
+export declare function $envExact(name: string, env?: Record<string, string | undefined>): string | undefined;
+/**
+ * Parses a positive decimal integer from `$env[name]`.
+ * 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
+ * title changes, and emergency restore. Defaults to {@link isBunTestRuntime} so
+ * `bun test` launched inside a real TTY never paints the TUI, leaks probe
+ * queries, or hijacks the developer's stdin; production runtimes stay
+ * interactive.
+ *
+ * Terminal-contract tests that must exercise the real I/O path opt out with
+ * `setTerminalHeadless(false)` and restore it afterwards.
+ */
+export declare function isTerminalHeadless(): boolean;
+/**
+ * Override the {@link isTerminalHeadless} default and return the previous value
+ * so callers can restore exact prior state (`const prev = setTerminalHeadless(false); … setTerminalHeadless(prev);`).
+ */
+export declare function setTerminalHeadless(headless: boolean): boolean;
+/**
+ * True when this process runs an interactive coding-agent host — the only
+ * context where the operator can browse the Agent Hub and focus a live
+ * subagent's session (`SessionFocusController`), so a subagent's session title
+ * can become operator-visible. Off by default (print/RPC/ACP/eval/SDK/`bun
+ * test` never render a focusable session tree); the interactive entrypoint
+ * flips it on with {@link setInteractiveHost}.
+ */
+export declare function isInteractiveHost(): boolean;
+/**
+ * Set the interactive-host flag and return the previous value so callers can
+ * restore exact prior state. See {@link isInteractiveHost}.
+ */
+export declare function setInteractiveHost(interactive: boolean): boolean;
+/**
+ * SQLite `busy_timeout` for the session-critical databases (agent.db,
+ * history.db, stats.db).
+ *
+ * Interactive hosts tolerate a longer synchronous wait on lock contention
+ * (SQLITE_BUSY during WAL recovery/checkpoint — see oh-my-pi#2421): the
+ * operator sees a brief freeze and the statement eventually completes.
+ * Headless hosts (print/RPC/ACP/eval/SDK) run a protocol on the same thread —
+ * a multi-second synchronous busy-wait freezes their event loop and stalls
+ * every in-flight frame with no liveness signal, so they use a short timeout
+ * and rely on the existing asynchronous open/retry paths to recover from
+ * contention instead of blocking.
+ */
+export declare function getDbBusyTimeoutMs(): number;
+/**
+ * True when this code is running inside a `bun build --compile` standalone
+ * binary. Detects via the embedded virtual-filesystem path markers
+ * (`$bunfs`, `~BUN`, or its URL-encoded form `%7EBUN`) in `import.meta.url`,
+ * which Bun rewrites for every module bundled into the executable. The
+ * `PI_COMPILED` env var (set by the build script's `--define`) is checked
+ * first for cheap fast-path detection.
+ */
+export declare function isCompiledBinary(): boolean;
+/** Parse a boolean-ish env value ("1", "yes", "on", …); `def` when unset/empty. */
+export declare function parseFlag(value: string | undefined, def?: boolean): boolean;
+export declare function $flag(name: string, def?: boolean): boolean;

package/dist/types/fetch-retry.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Server-suggested retry delay extraction. Merges the patterns historically used
+ * by the OpenAI Codex and Google Gemini retry helpers.
+ *
+ * Header sources (checked in order):
+ *  - `retry-after-ms` (milliseconds)
+ *  - `Retry-After` (numeric seconds, or HTTP date)
+ *  - `x-ratelimit-reset-ms` (delta ms, or Unix epoch ms/s for large values)
+ *  - `x-ratelimit-reset` (Unix epoch seconds)
+ *  - `x-ratelimit-reset-after` (seconds)
+ *
+ * Body patterns:
+ *  - `Your quota will reset after 18h31m10s` / `10m15s` / `39s`
+ *  - `Please retry in 250ms` / `Please retry in 12s`
+ *  - `"retryDelay": "34.074824224s"` (JSON error detail field)
+ *  - `try again in 250ms` / `try again in 12s` / `try again in 5 min` / `try again in ~158 min`
+ *
+ * Returns `undefined` if no signal is found.
+ */
+export declare function extractRetryHint(source: Response | Headers | null | undefined, body?: string): number | undefined;
+export interface FetchWithRetryOptions extends RequestInit {
+    /** Total fetch attempts (initial + retries). Default `5`. */
+    maxAttempts?: number;
+    /**
+     * Per-delay cap. Server-provided `Retry-After` hints exceeding this return
+     * the current response immediately — caller deals with the `!response.ok`.
+     * Default `60_000`.
+     */
+    maxDelayMs?: number;
+    /**
+     * Fallback delay schedule when no server hint is present. Number, array
+     * (indexed by attempt, clamped to last), or function. Default exponential
+     * `500ms * 2 ** attempt` capped at `maxDelayMs`.
+     */
+    defaultDelayMs?: number | readonly number[] | ((attempt: number) => number);
+    /**
+     * Optional per-attempt overlay merged into the base `RequestInit` each try.
+     * Headers from the overlay shallow-merge over the base. Useful for auth
+     * token refresh or user-agent rotation.
+     */
+    prepareInit?: (attempt: number) => RequestInit | Promise<RequestInit>;
+    /**
+     * Optional `fetch` implementation override. Defaults to `globalThis.fetch`.
+     * Useful for routing requests through a proxy, instrumented transport, or
+     * mock during tests.
+     */
+    fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+    /**
+     * Optional retry gate for HTTP responses whose status is retryable. Receives a
+     * cloned body string so callers can fail fast on deterministic provider
+     * failures that happen to use a 5xx status.
+     */
+    shouldRetryResponse?: (response: Response, bodyText: string, attempt: number) => boolean | Promise<boolean>;
+    /**
+     * Bun extension forwarded verbatim to the underlying `fetch` call. `false`
+     * disables Bun's native ~300s pre-response timeout (callers that own a
+     * configurable first-event/idle watchdog or an external `AbortSignal`
+     * supply this so the runtime ceiling cannot pre-empt them); a positive
+     * number sets a custom ceiling in ms. Bare browser/Node fetch ignores it.
+     */
+    timeout?: number | false;
+}
+/**
+ * Fetch with bounded retries and sensible defaults. Retries on any
+ * `isRetryableStatus` (5xx, 408, 429) and on transient network errors. Server
+ * `Retry-After`/quota hints are honoured up to `maxDelayMs`; a hint that exceeds
+ * the cap returns the current response so the caller can fail fast. Aborts on
+ * `init.signal` propagate as `"Request was aborted"`.
+ *
+ * The caller is responsible for inspecting `!response.ok` once the call returns.
+ */
+export declare function fetchWithRetry(url: string | URL | ((attempt: number) => string | URL), options?: FetchWithRetryOptions): Promise<Response>;
+/**
+ * Inspect an arbitrary error value (or its `cause` chain, up to depth 2) for an
+ * HTTP status code. Reads `status`, `statusCode`, and `response.status` fields,
+ * coerces string values, and falls back to scanning the error message for
+ * common patterns like `Error: 401`, `error (429)`, or `HTTP 503`.
+ */
+export declare function extractHttpStatusFromError(error: unknown): number | undefined;
+/**
+ * `true` if the given HTTP status code is one we treat as transient: 408
+ * (Request Timeout), 429 (Too Many Requests), or any 5xx (server error).
+ */
+export declare function isRetryableStatus(status: number): boolean;
+/**
+ * `true` if the message describes an unexpected socket closure — Bun and some
+ * proxies surface these for any HTTP/2 stream reset.
+ */
+export declare function isUnexpectedSocketCloseMessage(message: string): boolean;
+/**
+ * Identify errors that should be retried: aborts/timeouts in the error name or
+ * message, retryable HTTP statuses (see `isRetryableStatus`), unexpected socket
+ * closes, and the standard transient phrases. 4xx statuses other than 408/429
+ * and validation-shaped messages short-circuit to `false`.
+ */
+export declare function isRetryableError(error: unknown): boolean;