@linxiraos/pi-utils 1.1.9 → 1.1.11

package/dist/types/json-parse.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Lightweight string-level repair of the escape/control-char hazards that make
+ * otherwise-valid JSON fail `JSON.parse`: raw control characters inside strings
+ * are escaped, and invalid `\x` escapes have their backslash escaped. Returns the
+ * input unchanged when no repair is needed. Pure string→string; does not parse.
+ */
+export declare function repairJson(json: string): string;
+/**
+ * Final-parse a JSON value, repairing the common LLM malformations
+ * ({@link RelaxedJson}). Tries strict `JSON.parse` first (fast path, exact JSON
+ * semantics), then the relaxed parser. Throws when the input is unrepairable,
+ * truncated, or carries trailing garbage — so callers can skip a bad tool call
+ * rather than execute a half-formed one.
+ */
+export declare function parseJsonWithRepair<T>(json: string): T;
+/**
+ * Parse possibly-incomplete JSON during streaming. Always returns a value, never
+ * throws: `{}` for empty/whitespace/unrecoverable buffers, and an auto-closed
+ * best-effort object for truncated ones.
+ */
+export declare function parseStreamingJson<T = Record<string, unknown>>(partialJson: string | undefined): T;
+/**
+ * Default minimum byte growth before `parseStreamingJsonThrottled` will
+ * re-parse a streaming tool-call argument buffer. Acts as the floor of the
+ * geometric gate — see {@link parseStreamingJsonThrottled}.
+ */
+export declare const STREAMING_JSON_PARSE_MIN_GROWTH = 256;
+/**
+ * Throttled variant of {@link parseStreamingJson} for the per-delta hot path.
+ *
+ * Tool calls arrive as a long sequence of small deltas — calling
+ * `parseStreamingJson(buffer)` on every delta re-parses the entire buffer
+ * each time, giving O(N²) work in the total buffer length. A fixed re-parse
+ * floor alone does NOT fix this: with `minGrowthBytes` constant, a buffer of
+ * length N is parsed N/minGrowthBytes times at an average cost of N/2, which
+ * is still O(N²) (the constant just shrinks). Long `write` payloads — where
+ * the buffer is the whole file — made this the dominant main-thread stall
+ * during streaming.
+ *
+ * Instead the gate scales geometrically: once the buffer is large, a re-parse
+ * requires growth proportional to the current length (`len / 32`, floored at
+ * `minGrowthBytes`). Parse points then form a geometric progression, so a
+ * buffer of length N is parsed O(log N) times for O(N log N) total work,
+ * while small buffers keep the snappy fixed-cadence updates.
+ *
+ * Each provider tracks the last parsed length on its tool-call block, so the
+ * final `toolcall_end` parse (which providers already perform unconditionally)
+ * is the authoritative full parse — the throttle only delays mid-stream UI
+ * updates, by at most ~3% of the accumulated content for large buffers.
+ *
+ * @returns the parsed object plus the new `parsedLen` to persist; or `null`
+ *          when the buffer has not grown enough to warrant a re-parse.
+ */
+export declare function parseStreamingJsonThrottled<T = Record<string, unknown>>(partialJson: string | undefined, lastParsedLen: number, minGrowthBytes?: number): {
+    value: T;
+    parsedLen: number;
+} | null;
+/**
+ * Classification of a streaming buffer against strict JSON (RFC 8259):
+ * - `"complete"`: exactly one whole JSON value (plus surrounding whitespace).
+ * - `"prefix"`: a proper prefix of some valid JSON value — more bytes can
+ *   still complete it.
+ * - `"invalid"`: no suffix can ever make it valid strict JSON (e.g. a raw
+ *   control character inside a string, or a second top-level value).
+ */
+export type JsonPrefixState = "complete" | "prefix" | "invalid";
+/**
+ * Classify `text` as a strict-JSON value, prefix, or dead end.
+ *
+ * Providers use this to disambiguate identifierless streaming tool-call
+ * deltas: a chunk starting with `{` is a *new* sibling call only if the
+ * current call's argument buffer cannot absorb it — the buffer is already a
+ * complete value, already unsalvageable (lossy hosts abandon buffers
+ * mid-string, leaving raw control characters strict JSON forbids), or the
+ * concatenation would break it. Unlike {@link parseStreamingJson} this is
+ * deliberately strict: forgiving repair would mask exactly the corruption
+ * signals the caller needs.
+ *
+ * A top-level number at end-of-input classifies as `"complete"` even though
+ * more digits could extend it; tool-argument buffers are always objects, so
+ * the ambiguity is immaterial here.
+ */
+export declare function classifyJsonPrefix(text: string): JsonPrefixState;

package/dist/types/json.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Try to parse JSON, returning null on failure.
+ */
+export declare function tryParseJson<T = unknown>(content: string): T | null;
+/**
+ * Serialize JSON while preserving bigint precision as decimal strings.
+ *
+ * Tool arguments normally arrive from JSON providers, but extension hooks and
+ * host integrations can supply JavaScript bigint values. Native
+ * `JSON.stringify` throws for those values, which makes otherwise valid agent
+ * history impossible to persist, replay, or compact. A decimal string is the
+ * only lossless JSON representation.
+ */
+export declare function stringifyJson(value: unknown, space?: string | number): string | undefined;
+/**
+ * Deterministically serialize JSON-shaped data by sorting object keys at every
+ * depth while preserving array order. Throws for values JSON cannot represent
+ * as a top-level value instead of returning an easy-to-misuse undefined.
+ */
+export declare function stableStringifyJson(value: unknown): string;

package/dist/types/logger/rotating-file.d.ts

@@ -0,0 +1,18 @@
+/** Configuration for a process-local rotating file sink. */
+export interface RotatingFileOptions {
+    readonly directory: string;
+    readonly filenamePrefix: string;
+    readonly filenameSuffix: string;
+    readonly auditFile: string;
+    readonly maxBytes: number;
+    readonly maxFiles: number;
+}
+/** Synchronous append sink with local-day and size rotation plus bounded retention. */
+export declare class RotatingFileSink {
+    #private;
+    constructor(options: RotatingFileOptions);
+    /** Append one already-formatted log record. */
+    write(line: string): void;
+    /** Stop accepting records. Synchronous writes require no drain phase. */
+    close(): void;
+}

package/dist/types/logger.d.ts

@@ -0,0 +1,96 @@
+/** Severity names accepted by the centralized logger. */
+export type LogLevel = "error" | "warn" | "info" | "debug";
+/** Structured log event forwarded to out-of-band sinks such as OpenTelemetry. */
+export interface LogEvent {
+    readonly level: LogLevel;
+    readonly message: string;
+    readonly context: Record<string, unknown> | undefined;
+    readonly timestamp: Date;
+}
+/** Receives each structured log event after the local transport path runs. */
+export type LogSink = (event: LogEvent) => void;
+/** Register an out-of-band log sink and return a disposer. */
+export declare function registerLogSink(sink: LogSink): () => void;
+/**
+ * Replace the active log transports. Pass `console: true, file: false` for
+ * long-running services (the auth broker, etc.) that want their structured
+ * logs piped into a process supervisor instead of the rotating file.
+ */
+export declare function setTransports(opts: {
+    console?: boolean;
+    file?: boolean | string;
+}): void;
+/**
+ * Log an error message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export declare function error(message: string, context?: Record<string, unknown>): void;
+/**
+ * Log a warning message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export declare function warn(message: string, context?: Record<string, unknown>): void;
+/**
+ * Log an informational message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export declare function info(message: string, context?: Record<string, unknown>): void;
+/**
+ * Log a debug message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export declare function debug(message: string, context?: Record<string, unknown>): void;
+/**
+ * Streaming startup markers, enabled by `PI_DEBUG_STARTUP`. Unlike the
+ * PI_TIMING tree (printed only after startup completes), these write one
+ * synchronous stderr line as each phase begins/ends, so a hard hang still
+ * shows the last phase that started. `fs.writeSync(2)` is used deliberately:
+ * it cannot be reordered or buffered past a synchronous block of the event
+ * loop (dlopen, sync fs on a dead mount, spawnSync).
+ */
+export declare function startupMarker(text: string): void;
+export declare function timingModeIncludes(option: "full" | "x"): boolean;
+export declare function shouldExitAfterTimings(): boolean;
+/**
+ * Print collected timings as an indented tree.
+ * Each span shows wall duration; parents with children also show "(self)" for unattributed time.
+ * Sibling spans are sorted by start time. Spans whose intervals overlap with siblings ran in parallel.
+ */
+export declare function printTimings(): void;
+/**
+ * Begin recording startup timings under a new root span.
+ * Idempotent: a second call while already recording is a no-op, so an explicit
+ * starter (main.ts) and any future early starter can coexist.
+ */
+export declare function startTiming(): void;
+/**
+ * Record an externally-measured span as a leaf child of the active span (or root
+ * when no span is active). Used by {@link spliceModuleLoadBuffer} to fold
+ * preload-captured module windows into the tree.
+ */
+export declare function recordModuleLoadSpan(path: string, start: number, durationMs: number, bodyMs?: number, imports?: string[]): void;
+/**
+ * End timing window and clear buffers.
+ */
+export declare function endTiming(): void;
+/**
+ * Ops of the currently-open span chain (root → deepest), following the most
+ * recently started unfinished child at each level. Lets a startup watchdog
+ * name the phase a stalled startup is stuck in.
+ */
+export declare function openSpanPath(): string[];
+/**
+ * Time a span. Three forms:
+ *   time(op)                    — point event (zero-duration breadcrumb)
+ *   time(op, fn, ...args)        — wrap fn in a span; returns fn's return value (sync or Promise)
+ *
+ * Spans nest hierarchically via AsyncLocalStorage: a child started inside another span's fn
+ * (even across awaits) becomes that span's child. Parallel children are recorded as siblings
+ * with overlapping intervals.
+ */
+export declare function time(op: string): void;
+export declare function time<T, A extends unknown[]>(op: string, fn: (...args: A) => T, ...args: A): T;

package/dist/types/loop-phase.d.ts

@@ -0,0 +1,10 @@
+export declare function pushLoopPhase(label: string): void;
+export declare function popLoopPhase(): void;
+export declare function currentLoopPhase(): string | undefined;
+/**
+ * Phase to blame for a just-detected loop block: the live top phase if one is
+ * still held, else the most recent phase pushed since the last call. Clears the
+ * recent slot so a block in a later, phase-less interval is not misattributed
+ * to a phase that already finished.
+ */
+export declare function takeRecentLoopPhase(): string | undefined;

package/dist/types/lru.d.ts

@@ -0,0 +1,46 @@
+/** Behavior-compatible reimplementation of lru-cache's used surface. */
+/** Why an entry left the cache. */
+export type DisposeReason = "evict" | "set" | "delete" | "expire";
+/** Options supported by {@link LRUCache}. */
+export interface LRUCacheOptions<K, V> {
+    /** Maximum number of retained entries. */
+    max?: number;
+    /** Maximum aggregate calculated size. */
+    maxSize?: number;
+    /** Maximum calculated size of one entry. */
+    maxEntrySize?: number;
+    /** Calculates an entry's size. */
+    sizeCalculation?: (value: V, key: K) => number;
+    /** Entry lifetime in milliseconds; zero disables expiry. */
+    ttl?: number;
+    /** Refreshes an entry's lifetime when it is read. */
+    updateAgeOnGet?: boolean;
+    /** Called synchronously before an entry is removed. */
+    dispose?: (value: V, key: K, reason: DisposeReason) => void;
+}
+/** A bounded least-recently-used cache with optional size and lifetime limits. */
+export declare class LRUCache<K, V> {
+    #private;
+    /** Creates an empty cache. */
+    constructor(options: LRUCacheOptions<K, V>);
+    /** Number of entries, including stale entries not yet removed by `get`. */
+    get size(): number;
+    /** Aggregate calculated size of retained entries. */
+    get calculatedSize(): number;
+    /** Stores a value and makes it most recently used. */
+    set(key: K, value: V | undefined): this;
+    /** Returns a value and makes a fresh entry most recently used. */
+    get(key: K): V | undefined;
+    /** Reports whether a fresh value is present without changing recency. */
+    has(key: K): boolean;
+    /** Returns a fresh value without changing recency or removing stale data. */
+    peek(key: K): V | undefined;
+    /** Removes a value, returning whether one was present. */
+    delete(key: K): boolean;
+    /** Removes every value from least to most recently used. */
+    clear(): void;
+    /** Iterates fresh keys from most to least recently used. */
+    keys(): Generator<K, void, unknown>;
+    /** Iterates fresh values from most to least recently used. */
+    values(): Generator<V, void, unknown>;
+}