@oka-core/reason 0.2.14 → 0.2.16

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"}

package/dist/query-guard.js

@@ -0,0 +1,74 @@
+/**
+ * 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`.
+ */
+import { createSignal } from "./signal.js";
+// ─── Class ──────────────────────────────────────────────────────────
+export class QueryGuard {
+    state = "idle";
+    _generation = 0;
+    _changed = createSignal();
+    /** Try to reserve the guard for a new operation. Returns false if busy. */
+    reserve() {
+        if (this.state !== "idle")
+            return false;
+        this.state = "dispatching";
+        this._changed.emit();
+        return true;
+    }
+    /** Cancel a reservation (go back to idle). */
+    cancelReservation() {
+        if (this.state !== "dispatching")
+            return;
+        this.state = "idle";
+        this._changed.emit();
+    }
+    /** Transition from dispatching to running. Returns generation or null if not dispatching. */
+    tryStart() {
+        if (this.state !== "dispatching")
+            return null;
+        this.state = "running";
+        this._generation++;
+        this._changed.emit();
+        return this._generation;
+    }
+    /**
+     * End a running operation. Only succeeds if the generation matches
+     * (prevents stale cleanups). Returns true if the guard was released.
+     */
+    end(generation) {
+        if (this.state !== "running")
+            return false;
+        if (generation !== this._generation)
+            return false;
+        this.state = "idle";
+        this._changed.emit();
+        return true;
+    }
+    /** Force the guard back to idle regardless of state. */
+    forceEnd() {
+        this.state = "idle";
+        this._generation++;
+        this._changed.emit();
+    }
+    /** Whether the guard is in dispatching or running state. */
+    get isActive() {
+        return this.state !== "idle";
+    }
+    /** Current generation counter. */
+    get generation() {
+        return this._generation;
+    }
+    // ─── useSyncExternalStore compatibility ───────────────────────
+    subscribe = (listener) => {
+        return this._changed.subscribe(listener);
+    };
+    getSnapshot = () => {
+        return this.isActive;
+    };
+}

package/dist/retry.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Retry utility with exponential backoff and jitter.
+ *
+ * ZERO external dependencies — pure domain layer.
+ *
+ * Inspired by Claude Code's `withRetry.ts` pattern:
+ * - Exponential backoff with ±25% jitter
+ * - Foreground vs background retry profiles
+ * - AbortSignal-aware — bails immediately on abort
+ * - Delegates retryability decisions to `isRetryableError()`
+ */
+/** Retry profile: foreground has fewer retries, background is more patient. */
+export type RetrySource = "foreground" | "background";
+/** Configuration for retry behavior. */
+export interface RetryOptions {
+    /** Retry profile — controls default maxRetries. Default: 'foreground'. */
+    source?: RetrySource;
+    /** Maximum number of retry attempts. Foreground default: 3, background default: 10. */
+    maxRetries?: number;
+    /** Base delay in ms before first retry. Default: 500. */
+    baseDelayMs?: number;
+    /** Maximum delay cap in ms. Default: 8000. */
+    maxDelayMs?: number;
+    /** Abort signal — if aborted, throws immediately without retry. */
+    signal?: AbortSignal;
+    /** Custom predicate for retryable errors. Default: `isRetryableError` from ./errors.js. */
+    shouldRetry?: (error: unknown) => boolean;
+}
+/**
+ * Calculate delay for a given retry attempt with exponential backoff and jitter.
+ *
+ * Formula: `min(baseMs * 2^attempt, maxMs)` with ±25% random jitter.
+ *
+ * @param attempt - Zero-based attempt index (0 = first retry)
+ * @param baseMs - Base delay in milliseconds
+ * @param maxMs - Maximum delay cap in milliseconds
+ * @returns Delay in milliseconds with jitter applied
+ */
+export declare function calculateDelay(attempt: number, baseMs: number, maxMs: number): number;
+/**
+ * Execute an async function with automatic retries on transient failures.
+ *
+ * Uses exponential backoff with jitter, respects AbortSignal, and delegates
+ * retryability checks to `isRetryableError()` by default.
+ *
+ * @param fn - Async function to execute
+ * @param options - Retry configuration
+ * @returns The resolved value from `fn`
+ * @throws The last error if all retries are exhausted, or immediately on non-retryable/abort errors
+ *
+ * @example
+ * ```ts
+ * const result = await withRetry(() => client.search(query), {
+ *   source: 'foreground',
+ *   signal: controller.signal,
+ * });
+ * ```
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,+EAA+E;AAC/E,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,YAAY,CAAC;AAEtD,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,uFAAuF;IACvF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,2FAA2F;IAC3F,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CAC3C;AAID;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,MAAM,CAMR;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,CAAC,CAAC,CA2CZ"}

package/dist/retry.js

@@ -0,0 +1,89 @@
+/**
+ * Retry utility with exponential backoff and jitter.
+ *
+ * ZERO external dependencies — pure domain layer.
+ *
+ * Inspired by Claude Code's `withRetry.ts` pattern:
+ * - Exponential backoff with ±25% jitter
+ * - Foreground vs background retry profiles
+ * - AbortSignal-aware — bails immediately on abort
+ * - Delegates retryability decisions to `isRetryableError()`
+ */
+import { isAbortError, isRetryableError } from "./errors.js";
+import { sleep } from "./sleep.js";
+// ─── Delay Calculation ──────────────────────────────────────────────
+/**
+ * Calculate delay for a given retry attempt with exponential backoff and jitter.
+ *
+ * Formula: `min(baseMs * 2^attempt, maxMs)` with ±25% random jitter.
+ *
+ * @param attempt - Zero-based attempt index (0 = first retry)
+ * @param baseMs - Base delay in milliseconds
+ * @param maxMs - Maximum delay cap in milliseconds
+ * @returns Delay in milliseconds with jitter applied
+ */
+export function calculateDelay(attempt, baseMs, maxMs) {
+    const exponential = baseMs * Math.pow(2, attempt);
+    const capped = Math.min(exponential, maxMs);
+    // ±25% jitter: multiply by random value in [0.75, 1.25]
+    const jitter = 0.75 + Math.random() * 0.5;
+    return Math.round(capped * jitter);
+}
+// ─── Core Retry Function ────────────────────────────────────────────
+/**
+ * Execute an async function with automatic retries on transient failures.
+ *
+ * Uses exponential backoff with jitter, respects AbortSignal, and delegates
+ * retryability checks to `isRetryableError()` by default.
+ *
+ * @param fn - Async function to execute
+ * @param options - Retry configuration
+ * @returns The resolved value from `fn`
+ * @throws The last error if all retries are exhausted, or immediately on non-retryable/abort errors
+ *
+ * @example
+ * ```ts
+ * const result = await withRetry(() => client.search(query), {
+ *   source: 'foreground',
+ *   signal: controller.signal,
+ * });
+ * ```
+ */
+export async function withRetry(fn, options) {
+    const source = options?.source ?? "foreground";
+    const maxRetries = options?.maxRetries ?? (source === "background" ? 10 : 3);
+    const baseDelayMs = options?.baseDelayMs ?? 500;
+    const maxDelayMs = options?.maxDelayMs ?? 8000;
+    const signal = options?.signal;
+    const shouldRetry = options?.shouldRetry ?? isRetryableError;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        // Check abort before each attempt
+        if (signal?.aborted) {
+            throw signal.reason ?? new Error("Operation aborted");
+        }
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            // Never retry aborts
+            if (isAbortError(error)) {
+                throw error;
+            }
+            // Final attempt — no more retries
+            if (attempt >= maxRetries) {
+                break;
+            }
+            // Non-retryable error — throw immediately
+            if (!shouldRetry(error)) {
+                throw error;
+            }
+            // Wait with exponential backoff + jitter
+            const delay = calculateDelay(attempt, baseDelayMs, maxDelayMs);
+            await sleep(delay, signal);
+        }
+    }
+    throw lastError;
+}
+// sleep is imported from ./sleep.js

package/dist/schemas.d.ts

@@ -71,12 +71,12 @@ export declare const RecordObservationInput: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     file_patterns: string[];
     confidence: number;
-    category: "architecture" | "bug_pattern" | "convention" | "performance" | "security" | "workflow" | "dependency" | "code_quality" | "other";
+    category: "security" | "architecture" | "bug_pattern" | "convention" | "performance" | "workflow" | "dependency" | "code_quality" | "other";
     tags: string[];
     summary: string;
     details?: string | undefined;
 }, {
-    category: "architecture" | "bug_pattern" | "convention" | "performance" | "security" | "workflow" | "dependency" | "code_quality" | "other";
+    category: "security" | "architecture" | "bug_pattern" | "convention" | "performance" | "workflow" | "dependency" | "code_quality" | "other";
     summary: string;
     file_patterns?: string[] | undefined;
     confidence?: number | undefined;
@@ -114,13 +114,13 @@ export declare const ListLearningsInput: z.ZodObject<{
     limit: number;
     repo?: string | undefined;
     min_confidence?: number | undefined;
-    category?: "decision" | "architecture" | "bug_pattern" | "convention" | "performance" | "security" | "workflow" | "domain_knowledge" | undefined;
+    category?: "security" | "decision" | "architecture" | "bug_pattern" | "convention" | "performance" | "workflow" | "domain_knowledge" | undefined;
     status?: "active" | "reinforced" | "contradicted" | "obsolete" | undefined;
 }, {
     repo?: string | undefined;
     limit?: number | undefined;
     min_confidence?: number | undefined;
-    category?: "decision" | "architecture" | "bug_pattern" | "convention" | "performance" | "security" | "workflow" | "domain_knowledge" | undefined;
+    category?: "security" | "decision" | "architecture" | "bug_pattern" | "convention" | "performance" | "workflow" | "domain_knowledge" | undefined;
     status?: "active" | "reinforced" | "contradicted" | "obsolete" | undefined;
 }>;
 export type ListLearningsInput = z.infer<typeof ListLearningsInput>;
@@ -167,20 +167,20 @@ export declare const ReasoningEvent: z.ZodObject<{
     timestamp: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     repo: string;
+    timestamp: string;
     id: string;
     agent_id: string;
     event_type: string;
     payload: Record<string, unknown>;
     session_id: string;
-    timestamp: string;
 }, {
     repo: string;
+    timestamp: string;
     id: string;
     agent_id: string;
     event_type: string;
     payload: Record<string, unknown>;
     session_id: string;
-    timestamp: string;
 }>;
 export type ReasoningEvent = z.infer<typeof ReasoningEvent>;
 export declare const Learning: z.ZodObject<{

package/dist/secrets.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Secret detection scanner for content passing through the Oka Reason platform.
+ *
+ * ZERO external dependencies — pure domain layer.
+ *
+ * Inspired by Claude Code's `secretScanner.ts`. All patterns are high-confidence
+ * to minimise false positives. Regex compilation is lazy — patterns are compiled
+ * on first invocation and cached for the lifetime of the process.
+ *
+ * This module is pure detection. Callers decide whether to throw
+ * {@link SecretDetectedError}, redact, or log.
+ */
+import type { SecretDetectedError } from "./errors.js";
+export type { SecretDetectedError };
+/** A single secret match found in content. */
+export interface SecretMatch {
+    /** Human-readable name of the pattern that matched (e.g. "AWS Access Key"). */
+    patternName: string;
+    /** Start index of the match within the scanned string. */
+    startIndex: number;
+    /** End index (exclusive) of the match within the scanned string. */
+    endIndex: number;
+}
+/**
+ * Scan content for known secret patterns.
+ *
+ * Returns all matches found across every pattern. The same region of text
+ * may appear in multiple matches if it satisfies more than one pattern.
+ *
+ * @param content - The string to scan.
+ * @returns An array of {@link SecretMatch} objects (empty if clean).
+ */
+export declare function scanForSecrets(content: string): SecretMatch[];
+/**
+ * Fast-path check: does the content contain any secrets?
+ *
+ * Returns `true` on the first match without scanning the entire content
+ * against all patterns. Use this when you only need a boolean gate.
+ *
+ * @param content - The string to scan.
+ * @returns `true` if at least one secret pattern matches.
+ */
+export declare function containsSecrets(content: string): boolean;
+//# sourceMappingURL=secrets.d.ts.map

package/dist/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGvD,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAIpC,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAiFD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,CAmB7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAWxD"}

package/dist/secrets.js

@@ -0,0 +1,115 @@
+/**
+ * Secret detection scanner for content passing through the Oka Reason platform.
+ *
+ * ZERO external dependencies — pure domain layer.
+ *
+ * Inspired by Claude Code's `secretScanner.ts`. All patterns are high-confidence
+ * to minimise false positives. Regex compilation is lazy — patterns are compiled
+ * on first invocation and cached for the lifetime of the process.
+ *
+ * This module is pure detection. Callers decide whether to throw
+ * {@link SecretDetectedError}, redact, or log.
+ */
+/**
+ * Curated set of HIGH-CONFIDENCE secret patterns.
+ *
+ * Each entry uses a raw source string so that compilation can be deferred.
+ * Only patterns with very low false-positive rates are included.
+ */
+const PATTERN_DEFS = [
+    {
+        name: "AWS Access Key",
+        source: "AKIA[0-9A-Z]{16}",
+    },
+    {
+        name: "GCP API Key",
+        source: "AIza[\\w-]{35}",
+    },
+    {
+        name: "GitHub Token",
+        source: "gh[ps]_[A-Za-z0-9_]{36,}",
+    },
+    {
+        name: "Anthropic API Key",
+        source: "sk-ant-api03-[\\w-]{90,}",
+    },
+    {
+        name: "OpenAI API Key",
+        source: "sk-proj-[\\w-]{40,}",
+    },
+    {
+        name: "Slack Token",
+        source: "xox[bpors]-[\\w-]{10,}",
+    },
+    {
+        name: "npm Token",
+        source: "npm_[a-zA-Z0-9]{36}",
+    },
+    {
+        name: "Generic Long Hex Secret",
+        source: "(?:secret|key|token|password)\\s*[:=]\\s*[\"']?[0-9a-fA-F]{64,}",
+        flags: "i",
+    },
+    {
+        name: "Private Key Block",
+        source: "-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----",
+    },
+];
+let compiledPatterns = null;
+/** Compile patterns on first use and cache them. */
+function getPatterns() {
+    if (compiledPatterns !== null) {
+        return compiledPatterns;
+    }
+    compiledPatterns = PATTERN_DEFS.map((def) => ({
+        name: def.name,
+        regex: new RegExp(def.source, def.flags ? `g${def.flags}` : "g"),
+    }));
+    return compiledPatterns;
+}
+// ─── Public API ──────────────────────────────────────────────────────
+/**
+ * Scan content for known secret patterns.
+ *
+ * Returns all matches found across every pattern. The same region of text
+ * may appear in multiple matches if it satisfies more than one pattern.
+ *
+ * @param content - The string to scan.
+ * @returns An array of {@link SecretMatch} objects (empty if clean).
+ */
+export function scanForSecrets(content) {
+    const matches = [];
+    const patterns = getPatterns();
+    for (const { name, regex } of patterns) {
+        // Reset lastIndex for each scan (RegExp with `g` flag is stateful)
+        regex.lastIndex = 0;
+        let match;
+        while ((match = regex.exec(content)) !== null) {
+            matches.push({
+                patternName: name,
+                startIndex: match.index,
+                endIndex: match.index + match[0].length,
+            });
+        }
+    }
+    return matches;
+}
+/**
+ * Fast-path check: does the content contain any secrets?
+ *
+ * Returns `true` on the first match without scanning the entire content
+ * against all patterns. Use this when you only need a boolean gate.
+ *
+ * @param content - The string to scan.
+ * @returns `true` if at least one secret pattern matches.
+ */
+export function containsSecrets(content) {
+    const patterns = getPatterns();
+    for (const { regex } of patterns) {
+        regex.lastIndex = 0;
+        if (regex.test(content)) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/semantic-types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Zod preprocessors for model-generated tool inputs that quote
+ * booleans and numbers as strings.
+ *
+ * LLMs occasionally produce `"replace_all":"false"` instead of
+ * `"replace_all":false`. Standard z.coerce is too permissive
+ * (JS truthiness makes "false" → true). These preprocessors
+ * only coerce the exact string literals, rejecting everything else.
+ *
+ * Inspired by Claude Code's `src/utils/semanticBoolean.ts` and
+ * `src/utils/semanticNumber.ts`.
+ */
+import { z } from "zod";
+/**
+ * Boolean that also accepts the string literals "true" / "false".
+ *
+ * @example
+ * ```ts
+ * semanticBoolean()                           // → boolean
+ * semanticBoolean(z.boolean().optional())     // → boolean | undefined
+ * semanticBoolean(z.boolean().default(false)) // → boolean
+ * ```
+ */
+export declare function semanticBoolean<T extends z.ZodType>(inner?: T): z.ZodEffects<T, T["_output"], unknown>;
+/**
+ * Number that also accepts numeric string literals like "30", "-5", "3.14".
+ *
+ * Only strings matching `/^-?\d+(\.\d+)?$/` are coerced. Anything else
+ * passes through and is rejected by the inner schema.
+ *
+ * @example
+ * ```ts
+ * semanticNumber()                          // → number
+ * semanticNumber(z.number().optional())     // → number | undefined
+ * semanticNumber(z.number().default(0))     // → number
+ * ```
+ */
+export declare function semanticNumber<T extends z.ZodType>(inner?: T): z.ZodEffects<T, T["_output"], unknown>;
+//# sourceMappingURL=semantic-types.d.ts.map

package/dist/semantic-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-types.d.ts","sourceRoot":"","sources":["../src/semantic-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EACjD,KAAK,GAAE,CAA+B,0CAMvC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAChD,KAAK,GAAE,CAA8B,0CAStC"}

package/dist/semantic-types.js

@@ -0,0 +1,49 @@
+/**
+ * Zod preprocessors for model-generated tool inputs that quote
+ * booleans and numbers as strings.
+ *
+ * LLMs occasionally produce `"replace_all":"false"` instead of
+ * `"replace_all":false`. Standard z.coerce is too permissive
+ * (JS truthiness makes "false" → true). These preprocessors
+ * only coerce the exact string literals, rejecting everything else.
+ *
+ * Inspired by Claude Code's `src/utils/semanticBoolean.ts` and
+ * `src/utils/semanticNumber.ts`.
+ */
+import { z } from "zod";
+/**
+ * Boolean that also accepts the string literals "true" / "false".
+ *
+ * @example
+ * ```ts
+ * semanticBoolean()                           // → boolean
+ * semanticBoolean(z.boolean().optional())     // → boolean | undefined
+ * semanticBoolean(z.boolean().default(false)) // → boolean
+ * ```
+ */
+export function semanticBoolean(inner = z.boolean()) {
+    return z.preprocess((v) => (v === "true" ? true : v === "false" ? false : v), inner);
+}
+/**
+ * Number that also accepts numeric string literals like "30", "-5", "3.14".
+ *
+ * Only strings matching `/^-?\d+(\.\d+)?$/` are coerced. Anything else
+ * passes through and is rejected by the inner schema.
+ *
+ * @example
+ * ```ts
+ * semanticNumber()                          // → number
+ * semanticNumber(z.number().optional())     // → number | undefined
+ * semanticNumber(z.number().default(0))     // → number
+ * ```
+ */
+export function semanticNumber(inner = z.number()) {
+    return z.preprocess((v) => {
+        if (typeof v === "string" && /^-?\d+(\.\d+)?$/.test(v)) {
+            const n = Number(v);
+            if (Number.isFinite(n))
+                return n;
+        }
+        return v;
+    }, inner);
+}

package/dist/sequential.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Serialize concurrent async calls into FIFO sequential execution.
+ *
+ * Wraps an async function so concurrent callers queue behind the
+ * in-flight invocation instead of racing.
+ *
+ * Inspired by Claude Code's `src/utils/sequential.ts`.
+ */
+/**
+ * Create a sequential execution wrapper for an async function.
+ *
+ * @example
+ * ```ts
+ * const writeFile = sequential(fs.writeFile);
+ * // These execute one at a time, in order:
+ * writeFile("a.txt", "hello");
+ * writeFile("a.txt", "world");
+ * ```
+ */
+export declare function sequential<T extends unknown[], R>(fn: (...args: T) => Promise<R>): (...args: T) => Promise<R>;
+//# sourceMappingURL=sequential.d.ts.map

package/dist/sequential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequential.d.ts","sourceRoot":"","sources":["../src/sequential.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,EAC/C,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7B,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAiC5B"}

package/dist/sequential.js

@@ -0,0 +1,49 @@
+/**
+ * Serialize concurrent async calls into FIFO sequential execution.
+ *
+ * Wraps an async function so concurrent callers queue behind the
+ * in-flight invocation instead of racing.
+ *
+ * Inspired by Claude Code's `src/utils/sequential.ts`.
+ */
+/**
+ * Create a sequential execution wrapper for an async function.
+ *
+ * @example
+ * ```ts
+ * const writeFile = sequential(fs.writeFile);
+ * // These execute one at a time, in order:
+ * writeFile("a.txt", "hello");
+ * writeFile("a.txt", "world");
+ * ```
+ */
+export function sequential(fn) {
+    const queue = [];
+    let processing = false;
+    async function processQueue() {
+        if (processing || queue.length === 0)
+            return;
+        processing = true;
+        while (queue.length > 0) {
+            const { args, resolve, reject, context } = queue.shift();
+            try {
+                const result = await fn.apply(context, args);
+                resolve(result);
+            }
+            catch (error) {
+                reject(error);
+            }
+        }
+        processing = false;
+        // Check if new items were added while we were processing
+        if (queue.length > 0) {
+            void processQueue();
+        }
+    }
+    return function (...args) {
+        return new Promise((resolve, reject) => {
+            queue.push({ args, resolve, reject, context: this });
+            void processQueue();
+        });
+    };
+}