@oka-core/reason 0.2.15 → 0.2.16

package/dist/jsonl.js

@@ -0,0 +1,60 @@
+/**
+ * JSONL parsing and safe JSON utilities.
+ *
+ * Inspired by Claude Code's `src/utils/json.ts` (generic parts only).
+ */
+import { createLRU } from "./memo.js";
+const parseCache = createLRU(50);
+/**
+ * Parse JSON safely, returning `null` on failure.
+ * Results are LRU-memoized (50 entries max, keys ≤ 8KB).
+ */
+export function safeParseJSON(json) {
+    if (!json)
+        return null;
+    // Skip cache for large strings
+    if (json.length > 8192) {
+        try {
+            return JSON.parse(json);
+        }
+        catch {
+            return null;
+        }
+    }
+    const cached = parseCache.peek(json);
+    if (cached) {
+        return cached.ok ? cached.value : null;
+    }
+    try {
+        const value = JSON.parse(json);
+        parseCache.set(json, { ok: true, value });
+        return value;
+    }
+    catch {
+        parseCache.set(json, { ok: false });
+        return null;
+    }
+}
+// ─── JSONL ──────────────────────────────────────────────────────────
+/**
+ * Parse a JSONL string into an array of typed values.
+ * Skips blank lines and silently drops malformed lines.
+ */
+export function parseJSONL(data) {
+    if (!data)
+        return [];
+    const results = [];
+    const lines = data.split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        try {
+            results.push(JSON.parse(trimmed));
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return results;
+}

package/dist/lazy-schema.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns a memoized factory function that constructs the value on first call.
+ * Used to defer Zod schema construction from module init time to first access.
+ */
+export declare function lazySchema<T>(factory: () => T): () => T;
+//# sourceMappingURL=lazy-schema.d.ts.map

package/dist/lazy-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-schema.d.ts","sourceRoot":"","sources":["../src/lazy-schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,CAGvD"}

package/dist/lazy-schema.js

@@ -0,0 +1,8 @@
+/**
+ * Returns a memoized factory function that constructs the value on first call.
+ * Used to defer Zod schema construction from module init time to first access.
+ */
+export function lazySchema(factory) {
+    let cached;
+    return () => (cached ??= factory());
+}

package/dist/memo.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Memoization toolkit — zero external dependencies.
+ *
+ * Three strategies:
+ * 1. memoizeWithTTL  — synchronous TTL cache with stale-while-revalidate
+ * 2. memoizeAsync    — async TTL cache with in-flight deduplication
+ * 3. createLRU       — bounded LRU cache backed by Map insertion order
+ */
+/**
+ * Creates a synchronous TTL-cached wrapper around `fn`.
+ *
+ * - First call computes and caches the value.
+ * - Subsequent calls within `ttlMs` return the cached value.
+ * - After TTL expires the stale value is returned immediately while a
+ *   background refresh is scheduled via `queueMicrotask`.
+ * - `clear()` invalidates the cache and increments a generation counter so
+ *   any in-flight refresh from a previous generation is silently discarded.
+ */
+export declare function memoizeWithTTL<T>(fn: () => T, ttlMs: number): {
+    get(): T;
+    clear(): void;
+};
+/**
+ * Creates an async TTL-cached wrapper around `fn`.
+ *
+ * - Concurrent callers with the same cache key share a single in-flight
+ *   Promise (deduplication).
+ * - On error the cache entry **and** in-flight entry are removed so the next
+ *   call retries (self-correcting).
+ * - `keyFn` defaults to `JSON.stringify(args)`.
+ */
+export declare function memoizeAsync<Args extends unknown[], T>(fn: (...args: Args) => Promise<T>, options: {
+    ttlMs: number;
+    keyFn?: (...args: Args) => string;
+    /** When set, uses a bounded LRU cache instead of an unbounded Map. */
+    maxEntries?: number;
+}): (...args: Args) => Promise<T>;
+/** Bounded least-recently-used cache. */
+export interface LRUCache<K, V> {
+    /** Get value and promote key to most-recently-used. */
+    get(key: K): V | undefined;
+    /** Insert or update a key-value pair. Evicts LRU entry on overflow. */
+    set(key: K, value: V): void;
+    /** Get value without promoting the key. */
+    peek(key: K): V | undefined;
+    /** Check existence without promoting. */
+    has(key: K): boolean;
+    /** Delete a single entry. Returns `true` if the key existed. */
+    delete(key: K): boolean;
+    /** Remove all entries. */
+    clear(): void;
+    /** Current number of entries. */
+    readonly size: number;
+}
+/**
+ * Creates a bounded LRU cache.
+ *
+ * Uses a `Map` whose insertion order is preserved by the JS spec.
+ * On access (`get` / `set`) the entry is deleted and re-inserted to promote
+ * it to the most-recently-used position. When capacity is exceeded the first
+ * key (least recently used) is evicted.
+ */
+export declare function createLRU<K, V>(capacity: number): LRUCache<K, V>;
+//# sourceMappingURL=memo.d.ts.map

package/dist/memo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memo.d.ts","sourceRoot":"","sources":["../src/memo.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,EAAE,EAAE,MAAM,CAAC,EACX,KAAK,EAAE,MAAM,GACZ;IAAE,GAAG,IAAI,CAAC,CAAC;IAAC,KAAK,IAAI,IAAI,CAAA;CAAE,CAkD7B;AAWD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,SAAS,OAAO,EAAE,EAAE,CAAC,EACpD,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EACjC,OAAO,EAAE;IACP,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC;IAClC,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACA,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,CA0C/B;AAMD,yCAAyC;AACzC,MAAM,WAAW,QAAQ,CAAC,CAAC,EAAE,CAAC;IAC5B,uDAAuD;IACvD,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAC3B,uEAAuE;IACvE,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAC5B,2CAA2C;IAC3C,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAC5B,yCAAyC;IACzC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC;IACrB,gEAAgE;IAChE,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC;IACxB,0BAA0B;IAC1B,KAAK,IAAI,IAAI,CAAC;IACd,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAmDhE"}

package/dist/memo.js

@@ -0,0 +1,162 @@
+/**
+ * Memoization toolkit — zero external dependencies.
+ *
+ * Three strategies:
+ * 1. memoizeWithTTL  — synchronous TTL cache with stale-while-revalidate
+ * 2. memoizeAsync    — async TTL cache with in-flight deduplication
+ * 3. createLRU       — bounded LRU cache backed by Map insertion order
+ */
+// ---------------------------------------------------------------------------
+// 1. Synchronous TTL with stale-while-revalidate
+// ---------------------------------------------------------------------------
+/**
+ * Creates a synchronous TTL-cached wrapper around `fn`.
+ *
+ * - First call computes and caches the value.
+ * - Subsequent calls within `ttlMs` return the cached value.
+ * - After TTL expires the stale value is returned immediately while a
+ *   background refresh is scheduled via `queueMicrotask`.
+ * - `clear()` invalidates the cache and increments a generation counter so
+ *   any in-flight refresh from a previous generation is silently discarded.
+ */
+export function memoizeWithTTL(fn, ttlMs) {
+    let cached;
+    let cachedAt = 0;
+    let hasValue = false;
+    let generation = 0;
+    let refreshScheduled = false;
+    function refresh(gen) {
+        refreshScheduled = true;
+        queueMicrotask(() => {
+            if (gen !== generation) {
+                refreshScheduled = false;
+                return;
+            }
+            try {
+                cached = fn();
+                cachedAt = Date.now();
+                hasValue = true;
+            }
+            finally {
+                refreshScheduled = false;
+            }
+        });
+    }
+    return {
+        get() {
+            const now = Date.now();
+            if (!hasValue) {
+                cached = fn();
+                cachedAt = now;
+                hasValue = true;
+                return cached;
+            }
+            if (now - cachedAt > ttlMs && !refreshScheduled) {
+                refresh(generation);
+            }
+            return cached;
+        },
+        clear() {
+            generation++;
+            cached = undefined;
+            cachedAt = 0;
+            hasValue = false;
+            refreshScheduled = false;
+        },
+    };
+}
+/**
+ * Creates an async TTL-cached wrapper around `fn`.
+ *
+ * - Concurrent callers with the same cache key share a single in-flight
+ *   Promise (deduplication).
+ * - On error the cache entry **and** in-flight entry are removed so the next
+ *   call retries (self-correcting).
+ * - `keyFn` defaults to `JSON.stringify(args)`.
+ */
+export function memoizeAsync(fn, options) {
+    const { ttlMs, keyFn = (...args) => JSON.stringify(args) } = options;
+    const cache = options.maxEntries
+        ? createLRU(options.maxEntries)
+        : new Map();
+    const inFlight = new Map();
+    return (...args) => {
+        const key = keyFn(...args);
+        // Return cached if fresh
+        const entry = cache.get(key);
+        if (entry && Date.now() < entry.expiresAt) {
+            return Promise.resolve(entry.value);
+        }
+        // Deduplicate concurrent calls
+        const existing = inFlight.get(key);
+        if (existing) {
+            return existing;
+        }
+        const promise = fn(...args)
+            .then((value) => {
+            cache.set(key, { value, expiresAt: Date.now() + ttlMs });
+            inFlight.delete(key);
+            return value;
+        })
+            .catch((err) => {
+            cache.delete(key);
+            inFlight.delete(key);
+            throw err;
+        });
+        inFlight.set(key, promise);
+        return promise;
+    };
+}
+/**
+ * Creates a bounded LRU cache.
+ *
+ * Uses a `Map` whose insertion order is preserved by the JS spec.
+ * On access (`get` / `set`) the entry is deleted and re-inserted to promote
+ * it to the most-recently-used position. When capacity is exceeded the first
+ * key (least recently used) is evicted.
+ */
+export function createLRU(capacity) {
+    if (capacity < 1) {
+        throw new RangeError("LRU capacity must be >= 1");
+    }
+    const map = new Map();
+    return {
+        get(key) {
+            const value = map.get(key);
+            if (value === undefined && !map.has(key)) {
+                return undefined;
+            }
+            // Promote: delete + re-insert
+            map.delete(key);
+            map.set(key, value);
+            return value;
+        },
+        set(key, value) {
+            // If key exists, delete first so re-insert promotes it
+            if (map.has(key)) {
+                map.delete(key);
+            }
+            else if (map.size >= capacity) {
+                // Evict LRU (first key)
+                const first = map.keys().next().value;
+                map.delete(first);
+            }
+            map.set(key, value);
+        },
+        peek(key) {
+            return map.get(key);
+        },
+        has(key) {
+            return map.has(key);
+        },
+        delete(key) {
+            return map.delete(key);
+        },
+        clear() {
+            map.clear();
+        },
+        get size() {
+            return map.size;
+        },
+    };
+}

package/dist/pkce.d.ts

@@ -0,0 +1,13 @@
+/**
+ * PKCE (Proof Key for Code Exchange) primitives for OAuth 2.0 flows.
+ *
+ * Generates cryptographically secure code verifiers, challenges (S256),
+ * and state tokens using base64url encoding per RFC 7636.
+ */
+/** Generate a 32-byte random code verifier (base64url). */
+export declare function generateCodeVerifier(): string;
+/** Compute S256 code challenge from a verifier. */
+export declare function generateCodeChallenge(verifier: string): string;
+/** Generate a 32-byte random state token (base64url). */
+export declare function generateState(): string;
+//# sourceMappingURL=pkce.d.ts.map

package/dist/pkce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../src/pkce.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,2DAA2D;AAC3D,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED,mDAAmD;AACnD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI9D;AAED,yDAAyD;AACzD,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}

package/dist/pkce.js

@@ -0,0 +1,28 @@
+/**
+ * PKCE (Proof Key for Code Exchange) primitives for OAuth 2.0 flows.
+ *
+ * Generates cryptographically secure code verifiers, challenges (S256),
+ * and state tokens using base64url encoding per RFC 7636.
+ */
+import { createHash, randomBytes } from "node:crypto";
+function base64URLEncode(buffer) {
+    return buffer
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=/g, "");
+}
+/** Generate a 32-byte random code verifier (base64url). */
+export function generateCodeVerifier() {
+    return base64URLEncode(randomBytes(32));
+}
+/** Compute S256 code challenge from a verifier. */
+export function generateCodeChallenge(verifier) {
+    const hash = createHash("sha256");
+    hash.update(verifier);
+    return base64URLEncode(hash.digest());
+}
+/** Generate a 32-byte random state token (base64url). */
+export function generateState() {
+    return base64URLEncode(randomBytes(32));
+}

package/dist/priority-queue.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Generic priority queue with filtered dequeue — depends on signal.ts.
+ *
+ * Lower priority number = higher priority (dequeued first).
+ * Subscribe/getSnapshot for external store compatibility.
+ *
+ * Inspired by Claude Code's `src/utils/messageQueueManager.ts` (generified).
+ */
+export declare class PriorityQueue<T> {
+    private entries;
+    private snapshot;
+    private changed;
+    private updateSnapshot;
+    /** Enqueue an item with a given priority (lower = higher priority). */
+    enqueue(item: T, priority: number): void;
+    /**
+     * Dequeue the highest-priority item (lowest priority number).
+     * Optionally filter to only consider items matching the predicate.
+     * Returns undefined if queue is empty or no match.
+     */
+    dequeue(filter?: (item: T) => boolean): T | undefined;
+    /**
+     * Peek at the highest-priority item without removing it.
+     * Optionally filter to only consider matching items.
+     */
+    peek(filter?: (item: T) => boolean): T | undefined;
+    /** Remove and return all items matching the predicate. */
+    dequeueAllMatching(predicate: (item: T) => boolean): T[];
+    /** Remove all items. */
+    clear(): void;
+    /** Current queue size. */
+    get size(): number;
+    subscribe: (listener: () => void) => (() => void);
+    getSnapshot: () => readonly T[];
+}
+//# sourceMappingURL=priority-queue.d.ts.map

package/dist/priority-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"priority-queue.d.ts","sourceRoot":"","sources":["../src/priority-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAaH,qBAAa,aAAa,CAAC,CAAC;IAC1B,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,QAAQ,CAAoB;IACpC,OAAO,CAAC,OAAO,CAAkB;IAEjC,OAAO,CAAC,cAAc;IAKtB,uEAAuE;IACvE,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAKxC;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,CAAC,GAAG,SAAS;IAsBrD;;;OAGG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,CAAC,GAAG,SAAS;IAalD,0DAA0D;IAC1D,kBAAkB,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,CAAC,EAAE;IAgBxD,wBAAwB;IACxB,KAAK,IAAI,IAAI;IAMb,0BAA0B;IAC1B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAID,SAAS,GAAI,UAAU,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CAE9C;IAEF,WAAW,QAAO,SAAS,CAAC,EAAE,CAE5B;CACH"}

package/dist/priority-queue.js

@@ -0,0 +1,97 @@
+/**
+ * Generic priority queue with filtered dequeue — depends on signal.ts.
+ *
+ * Lower priority number = higher priority (dequeued first).
+ * Subscribe/getSnapshot for external store compatibility.
+ *
+ * Inspired by Claude Code's `src/utils/messageQueueManager.ts` (generified).
+ */
+import { createSignal } from "./signal.js";
+// ─── Class ──────────────────────────────────────────────────────────
+export class PriorityQueue {
+    entries = [];
+    snapshot = [];
+    changed = createSignal();
+    updateSnapshot() {
+        this.snapshot = Object.freeze(this.entries.map((e) => e.item));
+        this.changed.emit();
+    }
+    /** Enqueue an item with a given priority (lower = higher priority). */
+    enqueue(item, priority) {
+        this.entries.push({ item, priority });
+        this.updateSnapshot();
+    }
+    /**
+     * Dequeue the highest-priority item (lowest priority number).
+     * Optionally filter to only consider items matching the predicate.
+     * Returns undefined if queue is empty or no match.
+     */
+    dequeue(filter) {
+        if (this.entries.length === 0)
+            return undefined;
+        let bestIdx = -1;
+        let bestPriority = Infinity;
+        for (let i = 0; i < this.entries.length; i++) {
+            const entry = this.entries[i];
+            if (filter && !filter(entry.item))
+                continue;
+            if (entry.priority < bestPriority) {
+                bestPriority = entry.priority;
+                bestIdx = i;
+            }
+        }
+        if (bestIdx === -1)
+            return undefined;
+        const removed = this.entries.splice(bestIdx, 1)[0];
+        this.updateSnapshot();
+        return removed.item;
+    }
+    /**
+     * Peek at the highest-priority item without removing it.
+     * Optionally filter to only consider matching items.
+     */
+    peek(filter) {
+        let best;
+        for (const entry of this.entries) {
+            if (filter && !filter(entry.item))
+                continue;
+            if (!best || entry.priority < best.priority) {
+                best = entry;
+            }
+        }
+        return best?.item;
+    }
+    /** Remove and return all items matching the predicate. */
+    dequeueAllMatching(predicate) {
+        const matched = [];
+        this.entries = this.entries.filter((entry) => {
+            if (predicate(entry.item)) {
+                matched.push(entry.item);
+                return false;
+            }
+            return true;
+        });
+        if (matched.length > 0) {
+            this.updateSnapshot();
+        }
+        return matched;
+    }
+    /** Remove all items. */
+    clear() {
+        if (this.entries.length === 0)
+            return;
+        this.entries = [];
+        this.updateSnapshot();
+    }
+    /** Current queue size. */
+    get size() {
+        return this.entries.length;
+    }
+    // ─── useSyncExternalStore compatibility ───────────────────────
+    subscribe = (listener) => {
+        return this.changed.subscribe(listener);
+    };
+    getSnapshot = () => {
+        return this.snapshot;
+    };
+}

package/dist/process-utils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Process I/O utilities — EPIPE handling, guarded writes, stdin detection.
+ *
+ * Inspired by Claude Code's `src/utils/process.ts`.
+ */
+/** Register EPIPE handlers on stdout/stderr to prevent memory leaks on broken pipes. */
+export declare function registerProcessOutputErrorHandlers(): void;
+/** Write to stdout, skipping if stream is destroyed. */
+export declare function writeToStdout(data: string): void;
+/** Write to stderr, skipping if stream is destroyed. */
+export declare function writeToStderr(data: string): void;
+/** Write error to stderr and exit with code 1. */
+export declare function exitWithError(message: string): never;
+/**
+ * Peek for incoming data on a stdin-like stream.
+ * Returns `true` on timeout (no data), `false` if stream ends.
+ * First data chunk cancels the timeout — after that, waits for end.
+ */
+export declare function peekForStdinData(stream: NodeJS.EventEmitter, ms: number): Promise<boolean>;
+//# sourceMappingURL=process-utils.d.ts.map

package/dist/process-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-utils.d.ts","sourceRoot":"","sources":["../src/process-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH,wFAAwF;AACxF,wBAAgB,kCAAkC,IAAI,IAAI,CAGzD;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAIhD;AAED,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAIhD;AAED,kDAAkD;AAClD,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAGpD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,CAAC,YAAY,EAC3B,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,OAAO,CAAC,CAclB"}

package/dist/process-utils.js

@@ -0,0 +1,54 @@
+/**
+ * Process I/O utilities — EPIPE handling, guarded writes, stdin detection.
+ *
+ * Inspired by Claude Code's `src/utils/process.ts`.
+ */
+function handleEPIPE(stream) {
+    return (err) => {
+        if (err.code === "EPIPE") {
+            stream.destroy();
+        }
+    };
+}
+/** Register EPIPE handlers on stdout/stderr to prevent memory leaks on broken pipes. */
+export function registerProcessOutputErrorHandlers() {
+    process.stdout.on("error", handleEPIPE(process.stdout));
+    process.stderr.on("error", handleEPIPE(process.stderr));
+}
+/** Write to stdout, skipping if stream is destroyed. */
+export function writeToStdout(data) {
+    if (!process.stdout.destroyed) {
+        process.stdout.write(data);
+    }
+}
+/** Write to stderr, skipping if stream is destroyed. */
+export function writeToStderr(data) {
+    if (!process.stderr.destroyed) {
+        process.stderr.write(data);
+    }
+}
+/** Write error to stderr and exit with code 1. */
+export function exitWithError(message) {
+    console.error(message);
+    process.exit(1);
+}
+/**
+ * Peek for incoming data on a stdin-like stream.
+ * Returns `true` on timeout (no data), `false` if stream ends.
+ * First data chunk cancels the timeout — after that, waits for end.
+ */
+export function peekForStdinData(stream, ms) {
+    return new Promise((resolve) => {
+        const done = (timedOut) => {
+            clearTimeout(peek);
+            stream.off("end", onEnd);
+            stream.off("data", onFirstData);
+            resolve(timedOut);
+        };
+        const onEnd = () => done(false);
+        const onFirstData = () => clearTimeout(peek);
+        const peek = setTimeout(done, ms, true);
+        stream.once("end", onEnd);
+        stream.once("data", onFirstData);
+    });
+}

package/dist/query-guard.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Concurrency state machine — prevents re-entrant async operations.
+ *
+ * Tracks a 3-state lifecycle: idle → dispatching → running → idle.
+ * A generation counter ensures stale finally-blocks from cancelled
+ * queries don't corrupt cleanup.
+ *
+ * Inspired by Claude Code's `src/utils/QueryGuard.ts`.
+ */
+export declare class QueryGuard {
+    private state;
+    private _generation;
+    private _changed;
+    /** Try to reserve the guard for a new operation. Returns false if busy. */
+    reserve(): boolean;
+    /** Cancel a reservation (go back to idle). */
+    cancelReservation(): void;
+    /** Transition from dispatching to running. Returns generation or null if not dispatching. */
+    tryStart(): number | null;
+    /**
+     * End a running operation. Only succeeds if the generation matches
+     * (prevents stale cleanups). Returns true if the guard was released.
+     */
+    end(generation: number): boolean;
+    /** Force the guard back to idle regardless of state. */
+    forceEnd(): void;
+    /** Whether the guard is in dispatching or running state. */
+    get isActive(): boolean;
+    /** Current generation counter. */
+    get generation(): number;
+    subscribe: (listener: () => void) => (() => void);
+    getSnapshot: () => boolean;
+}
+//# sourceMappingURL=query-guard.d.ts.map

package/dist/query-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-guard.d.ts","sourceRoot":"","sources":["../src/query-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,QAAQ,CAAkB;IAElC,2EAA2E;IAC3E,OAAO,IAAI,OAAO;IAOlB,8CAA8C;IAC9C,iBAAiB,IAAI,IAAI;IAMzB,6FAA6F;IAC7F,QAAQ,IAAI,MAAM,GAAG,IAAI;IAQzB;;;OAGG;IACH,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAQhC,wDAAwD;IACxD,QAAQ,IAAI,IAAI;IAMhB,4DAA4D;IAC5D,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,kCAAkC;IAClC,IAAI,UAAU,IAAI,MAAM,CAEvB;IAID,SAAS,GAAI,UAAU,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CAE9C;IAEF,WAAW,QAAO,OAAO,CAEvB;CACH"}