atabey-shared 0.1.1-beta → 0.1.2

package/dist/modules/concurrency/job-queue.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Job Queue — concurrency-limited async work dispatcher backed by SQLite database persistence.
+ *
+ * Prevents unbounded parallel LLM / agent work from ballooning memory
+ * or starving the main event loop. Job lifecycles (pending, running, completed, failed)
+ * are recorded in the database when initialized, providing persistence and auditability.
+ */
+export type JobStatus = "pending" | "running" | "completed" | "failed";
+export interface JobRecord {
+    id: number;
+    queue_name: string;
+    payload: string;
+    status: JobStatus;
+    retries: number;
+    max_retries: number;
+    error_message?: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface EnqueueOptions {
+    /** Optional JSON-serializable payload or description of the task */
+    payload?: unknown;
+    /** Max retries before permanent failure (default: 3) */
+    maxRetries?: number;
+}
+export interface JobQueueOptions {
+    /** Max concurrent running jobs. Default: os.cpus().length (min 1, max 16). */
+    maxConcurrency?: number;
+    /** Optional name for diagnostics and DB tracking. */
+    name?: string;
+    /** Called when a job fails (after the promise rejects to the caller). */
+    onError?: (error: unknown, jobId: number) => void;
+}
+export interface JobQueueStats {
+    name: string;
+    maxConcurrency: number;
+    running: number;
+    pending: number;
+    completed: number;
+    failed: number;
+}
+export declare class JobQueue {
+    private readonly maxConcurrency;
+    private readonly name;
+    private readonly onError?;
+    private readonly pending;
+    private running;
+    private nextId;
+    private completed;
+    private failed;
+    private closed;
+    constructor(options?: JobQueueOptions);
+    /**
+     * Enqueue an async job. Resolves/rejects with the job result.
+     * Back-pressures via wait in the queue — does not spawn unbounded work.
+     * If SQLite is initialized, records job creation in the database.
+     */
+    enqueue<T>(fn: () => Promise<T>, options?: EnqueueOptions): Promise<T>;
+    /** Retrieve a job record from the database by ID. */
+    getJobRecord(id: number): JobRecord | null;
+    /** Retrieve job records from the database for this queue. */
+    getQueueRecords(status?: JobStatus, limit?: number): JobRecord[];
+    /** Current queue diagnostics. */
+    getStats(): JobQueueStats;
+    /** Reject pending jobs and stop accepting new ones. In-flight jobs finish. */
+    close(reason?: string): void;
+    /** Wait until running + pending reach zero (or timeout). */
+    drain(timeoutMs?: number): Promise<void>;
+    private pump;
+    private execute;
+}
+/** Backward compatibility alias */
+export { JobQueue as InMemoryJobQueue };
+export declare function getAgentJobQueue(options?: JobQueueOptions): JobQueue;
+/** Test helper — reset singleton. */
+export declare function resetAgentJobQueue(): void;

package/dist/modules/concurrency/job-queue.js

@@ -0,0 +1,200 @@
+/**
+ * Job Queue — concurrency-limited async work dispatcher backed by SQLite database persistence.
+ *
+ * Prevents unbounded parallel LLM / agent work from ballooning memory
+ * or starving the main event loop. Job lifecycles (pending, running, completed, failed)
+ * are recorded in the database when initialized, providing persistence and auditability.
+ */
+import os from "os";
+import { databaseHolder } from "../storage/database.js";
+export class JobQueue {
+    maxConcurrency;
+    name;
+    onError;
+    pending = [];
+    running = 0;
+    nextId = 1;
+    completed = 0;
+    failed = 0;
+    closed = false;
+    constructor(options = {}) {
+        const cpus = Math.max(1, os.cpus()?.length || 1);
+        const requested = options.maxConcurrency ?? cpus;
+        this.maxConcurrency = Math.max(1, Math.min(requested, 16));
+        this.name = options.name ?? "default";
+        this.onError = options.onError;
+    }
+    /**
+     * Enqueue an async job. Resolves/rejects with the job result.
+     * Back-pressures via wait in the queue — does not spawn unbounded work.
+     * If SQLite is initialized, records job creation in the database.
+     */
+    enqueue(fn, options) {
+        if (this.closed) {
+            return Promise.reject(new Error(`[JobQueue:${this.name}] Queue is closed; cannot accept new jobs.`));
+        }
+        let dbId;
+        if (databaseHolder.hasDB()) {
+            try {
+                const db = databaseHolder.getDB();
+                const payloadStr = typeof options?.payload === "string"
+                    ? options.payload
+                    : JSON.stringify(options?.payload ?? null);
+                const res = db.prepare(`INSERT INTO job_queue (queue_name, payload, status, retries, max_retries, created_at, updated_at)
+                     VALUES (?, ?, 'pending', 0, ?, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)`).run(this.name, payloadStr, options?.maxRetries ?? 3);
+                dbId = Number(res.lastInsertRowid);
+            }
+            catch {
+                // Table might not exist yet if running pre-migration
+            }
+        }
+        return new Promise((resolve, reject) => {
+            const item = {
+                id: this.nextId++,
+                dbId,
+                run: fn,
+                resolve,
+                reject,
+            };
+            this.pending.push(item);
+            this.pump();
+        });
+    }
+    /** Retrieve a job record from the database by ID. */
+    getJobRecord(id) {
+        if (!databaseHolder.hasDB())
+            return null;
+        try {
+            const db = databaseHolder.getDB();
+            return db.prepare("SELECT * FROM job_queue WHERE id = ?").get(id) || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Retrieve job records from the database for this queue. */
+    getQueueRecords(status, limit = 50) {
+        if (!databaseHolder.hasDB())
+            return [];
+        try {
+            const db = databaseHolder.getDB();
+            if (status) {
+                return db.prepare("SELECT * FROM job_queue WHERE queue_name = ? AND status = ? ORDER BY id DESC LIMIT ?").all(this.name, status, limit);
+            }
+            return db.prepare("SELECT * FROM job_queue WHERE queue_name = ? ORDER BY id DESC LIMIT ?").all(this.name, limit);
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Current queue diagnostics. */
+    getStats() {
+        return {
+            name: this.name,
+            maxConcurrency: this.maxConcurrency,
+            running: this.running,
+            pending: this.pending.length,
+            completed: this.completed,
+            failed: this.failed,
+        };
+    }
+    /** Reject pending jobs and stop accepting new ones. In-flight jobs finish. */
+    close(reason = "Queue closed") {
+        this.closed = true;
+        while (this.pending.length > 0) {
+            const item = this.pending.shift();
+            item?.reject(new Error(`[JobQueue:${this.name}] ${reason}`));
+        }
+    }
+    /** Wait until running + pending reach zero (or timeout). */
+    async drain(timeoutMs = 30_000) {
+        const start = Date.now();
+        while (this.running > 0 || this.pending.length > 0) {
+            if (Date.now() - start > timeoutMs) {
+                throw new Error(`[JobQueue:${this.name}] drain timed out after ${timeoutMs}ms`);
+            }
+            await new Promise((r) => setTimeout(r, 10));
+        }
+    }
+    pump() {
+        while (this.running < this.maxConcurrency && this.pending.length > 0) {
+            const item = this.pending.shift();
+            if (!item)
+                break;
+            this.running++;
+            void this.execute(item);
+        }
+    }
+    async execute(item) {
+        if (item.dbId && databaseHolder.hasDB()) {
+            try {
+                const db = databaseHolder.getDB();
+                db.prepare("UPDATE job_queue SET status = 'running', updated_at = CURRENT_TIMESTAMP WHERE id = ?").run(item.dbId);
+            }
+            catch {
+                // Ignore DB error during execution transition
+            }
+        }
+        try {
+            const result = await item.run();
+            this.completed++;
+            if (item.dbId && databaseHolder.hasDB()) {
+                try {
+                    const db = databaseHolder.getDB();
+                    db.prepare("UPDATE job_queue SET status = 'completed', updated_at = CURRENT_TIMESTAMP WHERE id = ?").run(item.dbId);
+                }
+                catch {
+                    // Ignore DB error
+                }
+            }
+            item.resolve(result);
+        }
+        catch (error) {
+            this.failed++;
+            if (item.dbId && databaseHolder.hasDB()) {
+                try {
+                    const db = databaseHolder.getDB();
+                    const errMsg = error instanceof Error ? error.message : String(error);
+                    db.prepare("UPDATE job_queue SET status = 'failed', error_message = ?, retries = retries + 1, updated_at = CURRENT_TIMESTAMP WHERE id = ?").run(errMsg, item.dbId);
+                }
+                catch {
+                    // Ignore DB error
+                }
+            }
+            try {
+                this.onError?.(error, item.id);
+            }
+            catch {
+                // ignore listener errors
+            }
+            item.reject(error);
+        }
+        finally {
+            this.running--;
+            this.pump();
+        }
+    }
+}
+/** Backward compatibility alias */
+export { JobQueue as InMemoryJobQueue };
+/** Shared singleton for agent orchestration (lazy). */
+let agentJobQueue = null;
+export function getAgentJobQueue(options) {
+    if (!agentJobQueue) {
+        const fromEnv = process.env.ATABEY_JOB_CONCURRENCY
+            ? parseInt(process.env.ATABEY_JOB_CONCURRENCY, 10)
+            : undefined;
+        agentJobQueue = new JobQueue({
+            name: "agent",
+            maxConcurrency: options?.maxConcurrency ?? (Number.isFinite(fromEnv) ? fromEnv : undefined),
+            onError: options?.onError,
+        });
+    }
+    return agentJobQueue;
+}
+/** Test helper — reset singleton. */
+export function resetAgentJobQueue() {
+    agentJobQueue?.close("reset");
+    agentJobQueue = null;
+}
+//# sourceMappingURL=job-queue.js.map

package/dist/modules/concurrency/job-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-queue.js","sourceRoot":"","sources":["../../../src/modules/concurrency/job-queue.ts"],"names":[],"mappings":"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"}

package/dist/modules/concurrency/lock.d.ts

@@ -0,0 +1,82 @@
+/**
+ * [LOCK] Multi-user Distributed Lock Mechanism
+ *
+ * Git-based lock system. Enables team members to work on the same
+ * files/resources without conflicts.
+ *
+ * Usage:
+ *   const lock = new DistributedLock("database/schema.sql");
+ *   if (lock.acquire("user-123", 60000)) {
+ *     // Apply changes
+ *     lock.release("user-123");
+ *   }
+ */
+export type LockStatus = "LOCKED" | "AVAILABLE" | "STALE" | "EXPIRED";
+export interface LockInfo {
+    resource: string;
+    ownerId: string;
+    ownerName: string;
+    acquiredAt: string;
+    expiresAt: string;
+    reason: string;
+    traceId?: string;
+}
+export declare class DistributedLock {
+    private static TABLE;
+    /**
+     * Initialize the locks table (run once at startup).
+     */
+    static initialize(): void;
+    /**
+     * Attempts to acquire a lock on a resource.
+     *
+     * @param resource - Lock resource name (e.g., "apps/backend/src/types/user.ts")
+     * @param ownerId - Unique owner identifier (e.g., "yusuf", "ci-bot-01")
+     * @param options - Optional parameters
+     * @returns true if lock acquired, false if already locked
+     */
+    static acquire(resource: string, ownerId: string, options?: {
+        ownerName?: string;
+        ttlMs?: number;
+        reason?: string;
+        traceId?: string;
+        force?: boolean;
+    }): boolean;
+    /**
+     * Releases a lock. Only the lock owner can release.
+     *
+     * @param resource - Lock resource name
+     * @param ownerId - Owner identifier for verification
+     * @returns true if released successfully
+     */
+    static release(resource: string, ownerId: string): boolean;
+    /**
+     * Checks if a resource is locked.
+     */
+    static isLocked(resource: string): boolean;
+    /**
+     * Gets lock information for a resource.
+     */
+    static getLock(resource: string): LockInfo | null;
+    /**
+     * Lists all active locks.
+     */
+    static listActiveLocks(): LockInfo[];
+    /**
+     * Lists all locks owned by a specific owner.
+     */
+    static listOwnerLocks(ownerId: string): LockInfo[];
+    /**
+     * Releases all locks owned by a specific owner (e.g., on disconnect).
+     */
+    static releaseAllByOwner(ownerId: string): number;
+    /**
+     * Releases all expired/stale locks.
+     */
+    private static releaseStaleLocks;
+    /**
+     * Generates a unique owner ID for the current user/machine.
+     * Uses git config user.name or hostname as fallback.
+     */
+    static getLocalOwnerId(): string;
+}

package/dist/modules/concurrency/lock.js

@@ -0,0 +1,159 @@
+/**
+ * [LOCK] Multi-user Distributed Lock Mechanism
+ *
+ * Git-based lock system. Enables team members to work on the same
+ * files/resources without conflicts.
+ *
+ * Usage:
+ *   const lock = new DistributedLock("database/schema.sql");
+ *   if (lock.acquire("user-123", 60000)) {
+ *     // Apply changes
+ *     lock.release("user-123");
+ *   }
+ */
+import { execSync } from "child_process";
+import os from "os";
+import { databaseHolder } from "../storage/database.js";
+export class DistributedLock {
+    static TABLE = "distributed_locks";
+    /**
+     * Initialize the locks table (run once at startup).
+     */
+    static initialize() {
+        const db = databaseHolder.getDB();
+        db.exec(`
+            CREATE TABLE IF NOT EXISTS ${this.TABLE} (
+                resource TEXT PRIMARY KEY,
+                ownerId TEXT NOT NULL,
+                ownerName TEXT NOT NULL,
+                acquiredAt TEXT NOT NULL,
+                expiresAt TEXT NOT NULL,
+                reason TEXT,
+                traceId TEXT
+            )
+        `);
+    }
+    /**
+     * Attempts to acquire a lock on a resource.
+     *
+     * @param resource - Lock resource name (e.g., "apps/backend/src/types/user.ts")
+     * @param ownerId - Unique owner identifier (e.g., "yusuf", "ci-bot-01")
+     * @param options - Optional parameters
+     * @returns true if lock acquired, false if already locked
+     */
+    static acquire(resource, ownerId, options = {}) {
+        const db = databaseHolder.getDB();
+        const now = new Date();
+        const expiresAt = new Date(now.getTime() + (options.ttlMs || 60000)).toISOString();
+        const ownerName = options.ownerName || ownerId;
+        const reason = options.reason || "No reason provided";
+        // Clean up stale locks first
+        this.releaseStaleLocks();
+        // If force=true, override existing lock directly using INSERT OR REPLACE
+        if (options.force) {
+            db.prepare(`
+                INSERT OR REPLACE INTO ${this.TABLE} (resource, ownerId, ownerName, acquiredAt, expiresAt, reason, traceId)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+            `).run(resource, ownerId, ownerName, now.toISOString(), expiresAt, reason, options.traceId || null);
+            return true;
+        }
+        // Acquire new lock atomically using INSERT OR IGNORE.
+        // If the resource is already locked, changes will be 0.
+        const result = db.prepare(`
+            INSERT OR IGNORE INTO ${this.TABLE} (resource, ownerId, ownerName, acquiredAt, expiresAt, reason, traceId)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+        `).run(resource, ownerId, ownerName, now.toISOString(), expiresAt, reason, options.traceId || null);
+        return result.changes > 0;
+    }
+    /**
+     * Releases a lock. Only the lock owner can release.
+     *
+     * @param resource - Lock resource name
+     * @param ownerId - Owner identifier for verification
+     * @returns true if released successfully
+     */
+    static release(resource, ownerId) {
+        const db = databaseHolder.getDB();
+        const result = db.prepare(`DELETE FROM ${this.TABLE} WHERE resource = ? AND ownerId = ?`).run(resource, ownerId);
+        return result.changes > 0;
+    }
+    /**
+     * Checks if a resource is locked.
+     */
+    static isLocked(resource) {
+        const db = databaseHolder.getDB();
+        const nowIso = new Date().toISOString();
+        const lock = db.prepare(`SELECT * FROM ${this.TABLE} WHERE resource = ? AND expiresAt > ?`).get(resource, nowIso);
+        return !!lock;
+    }
+    /**
+     * Gets lock information for a resource.
+     */
+    static getLock(resource) {
+        const db = databaseHolder.getDB();
+        this.releaseStaleLocks();
+        const lock = db.prepare(`SELECT * FROM ${this.TABLE} WHERE resource = ?`).get(resource);
+        return lock || null;
+    }
+    /**
+     * Lists all active locks.
+     */
+    static listActiveLocks() {
+        const db = databaseHolder.getDB();
+        this.releaseStaleLocks();
+        const nowIso = new Date().toISOString();
+        return db.prepare(`SELECT * FROM ${this.TABLE} WHERE expiresAt > ? ORDER BY acquiredAt DESC`).all(nowIso);
+    }
+    /**
+     * Lists all locks owned by a specific owner.
+     */
+    static listOwnerLocks(ownerId) {
+        const db = databaseHolder.getDB();
+        return db.prepare(`SELECT * FROM ${this.TABLE} WHERE ownerId = ? ORDER BY acquiredAt DESC`).all(ownerId);
+    }
+    /**
+     * Releases all locks owned by a specific owner (e.g., on disconnect).
+     */
+    static releaseAllByOwner(ownerId) {
+        const db = databaseHolder.getDB();
+        const result = db.prepare(`DELETE FROM ${this.TABLE} WHERE ownerId = ?`).run(ownerId);
+        return result.changes;
+    }
+    /**
+     * Releases all expired/stale locks.
+     */
+    static releaseStaleLocks() {
+        const db = databaseHolder.getDB();
+        const nowIso = new Date().toISOString();
+        const result = db.prepare(`DELETE FROM ${this.TABLE} WHERE expiresAt < ?`).run(nowIso);
+        return result.changes;
+    }
+    /**
+     * Generates a unique owner ID for the current user/machine.
+     * Uses git config user.name or hostname as fallback.
+     */
+    static getLocalOwnerId() {
+        // Try git config
+        try {
+            const name = execSync("git config user.name", { encoding: "utf8" }).trim();
+            if (name)
+                return name;
+        }
+        catch {
+            // Fallback
+        }
+        // Try environment
+        if (process.env.USER)
+            return process.env.USER;
+        if (process.env.USERNAME)
+            return process.env.USERNAME;
+        // Fallback to hostname
+        try {
+            return os.hostname();
+        }
+        catch {
+            return "unknown-user";
+        }
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/modules/concurrency/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../../src/modules/concurrency/lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAcxD,MAAM,OAAO,eAAe;IAChB,MAAM,CAAC,KAAK,GAAG,mBAAmB,CAAC;IAE3C;;OAEG;IACI,MAAM,CAAC,UAAU;QACpB,MAAM,EAAE,GAAG,cAAc,CAAC,KAAK,EAAE,CAAC;QAClC,EAAE,CAAC,IAAI,CAAC;yCACyB,IAAI,CAAC,KAAK;;;;;;;;;SAS1C,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;OAOG;IACI,MAAM,CAAC,OAAO,CACjB,QAAgB,EAChB,OAAe,EACf,UAMI,EAAE;QAEN,MAAM,EAAE,GAAG,cAAc,CAAC,KAAK,EAAE,CAAC;QAClC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QACnF,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC;QAC/C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,oBAAoB,CAAC;QAEtD,6BAA6B;QAC7B,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAEzB,yEAAyE;QACzE,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAChB,EAAE,CAAC,OAAO,CAAC;yCACkB,IAAI,CAAC,KAAK;;aAEtC,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC;YACpG,OAAO,IAAI,CAAC;QAChB,CAAC;QAED,sDAAsD;QACtD,wDAAwD;QACxD,MAAM,MAAM,GAAG,EAAE,CAAC,OAAO,CAAC;oCACE,IAAI,CAAC,KAAK;;SAErC,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC;QAEpG,OAAO,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,OAAO,CAAC,QAAgB,EAAE,OAAe;QACnD,MAAM,EAAE,GAAG,cAAc,CAAC,KAAK,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,EAAE,CAAC,OAAO,CACrB,eAAe,IAAI,CAAC,KAAK,qCAAqC,CACjE,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAEzB,OAAO,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,QAAQ,CAAC,QAAgB;QACnC,MAAM,EAAE,GAAG,cAAc,CAAC,KAAK,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CACnB,iBAAiB,IAAI,CAAC,KAAK,uCAAuC,CACrE,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAyB,CAAC;QAEhD,OAAO,CAAC,CAAC,IAAI,CAAC;IAClB,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,OAAO,CAAC,QAAgB;QAClC,MAAM,EAAE,GAAG,cAAc,CAAC,KAAK,EAAE,CAAC;QAClC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CACnB,iBAAiB,IAAI,CAAC,KAAK,qBAAqB,CACnD,CAAC,GAAG,CAAC,QAAQ,CAAyB,CAAC;QAExC,OAAO,IAAI,IAAI,IAAI,CAAC;IACxB,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,eAAe;QACzB,MAAM,EAAE,GAAG,cAAc,CAAC,KAAK,EAAE,CAAC;QAClC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACxC,OAAO,EAAE,CAAC,OAAO,CACb,iBAAiB,IAAI,CAAC,KAAK,+CAA+C,CAC7E,CAAC,GAAG,CAAC,MAAM,CAAe,CAAC;IAChC,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,cAAc,CAAC,OAAe;QACxC,MAAM,EAAE,GAAG,cAAc,CAAC,KAAK,EAAE,CAAC;QAClC,OAAO,EAAE,CAAC,OAAO,CACb,iBAAiB,IAAI,CAAC,KAAK,6CAA6C,CAC3E,CAAC,GAAG,CAAC,OAAO,CAAe,CAAC;IACjC,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,iBAAiB,CAAC,OAAe;QAC3C,MAAM,EAAE,GAAG,cAAc,CAAC,KAAK,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,EAAE,CAAC,OAAO,CACrB,eAAe,IAAI,CAAC,KAAK,oBAAoB,CAChD,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAEf,OAAO,MAAM,CAAC,OAAO,CAAC;IAC1B,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,iBAAiB;QAC5B,MAAM,EAAE,GAAG,cAAc,CAAC,KAAK,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACxC,MAAM,MAAM,GAAG,EAAE,CAAC,OAAO,CACrB,eAAe,IAAI,CAAC,KAAK,sBAAsB,CAClD,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAEd,OAAO,MAAM,CAAC,OAAO,CAAC;IAC1B,CAAC;IAED;;;OAGG;IACI,MAAM,CAAC,eAAe;QACzB,iBAAiB;QACjB,IAAI,CAAC;YACD,MAAM,IAAI,GAAG,QAAQ,CAAC,sBAAsB,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YAC3E,IAAI,IAAI;gBAAE,OAAO,IAAI,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACL,WAAW;QACf,CAAC;QAED,kBAAkB;QAClB,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI;YAAE,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;QAC9C,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ;YAAE,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;QAEtD,uBAAuB;QACvB,IAAI,CAAC;YACD,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC;QACzB,CAAC;QAAC,MAAM,CAAC;YACL,OAAO,cAAc,CAAC;QAC1B,CAAC;IACL,CAAC"}

package/dist/modules/concurrency/resilience.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Polly-style resilience primitives — no external deps.
+ *
+ * - withRetry: exponential backoff + jitter for transient failures
+ * - CircuitBreaker: closed → open → half-open state machine
+ * - withResilience: compose retry + circuit breaker
+ *
+ * Typical use: LLM provider rate limits, timeouts, 5xx, network blips.
+ */
+export type CircuitState = "closed" | "open" | "half-open";
+export interface RetryOptions {
+    /** Max attempts including the first try. Default: 3 */
+    maxAttempts?: number;
+    /** Initial delay in ms. Default: 100 */
+    baseDelayMs?: number;
+    /** Cap on delay in ms. Default: 10_000 */
+    maxDelayMs?: number;
+    /** Exponential factor. Default: 2 */
+    factor?: number;
+    /** Add random jitter [0, delay). Default: true */
+    jitter?: boolean;
+    /** Return true to retry this error. Default: retry all */
+    retryIf?: (error: unknown, attempt: number) => boolean;
+    /** Optional hook before each sleep */
+    onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
+    /** Optional abort signal */
+    signal?: AbortSignal;
+}
+export interface CircuitBreakerOptions {
+    /** Failures in closed state before opening. Default: 5 */
+    failureThreshold?: number;
+    /** Successes in half-open before closing. Default: 2 */
+    successThreshold?: number;
+    /** Time to wait in open before half-open probe. Default: 30_000 */
+    openMs?: number;
+    /** Optional name for error messages */
+    name?: string;
+}
+export declare class CircuitOpenError extends Error {
+    readonly circuit: string;
+    readonly retryAfterMs: number;
+    constructor(circuit: string, retryAfterMs: number);
+}
+export declare class CircuitBreaker {
+    private state;
+    private failures;
+    private successes;
+    private openedAt;
+    private readonly failureThreshold;
+    private readonly successThreshold;
+    private readonly openMs;
+    private readonly name;
+    constructor(options?: CircuitBreakerOptions);
+    getState(): CircuitState;
+    getStats(): {
+        state: CircuitState;
+        failures: number;
+        successes: number;
+        name: string;
+    };
+    /** Manual reset (e.g. after operator intervention). */
+    reset(): void;
+    exec<T>(fn: () => Promise<T>): Promise<T>;
+    private maybeTransitionToHalfOpen;
+    private onSuccess;
+    private onFailure;
+    private trip;
+}
+export declare function computeBackoffDelay(attempt: number, options?: Pick<RetryOptions, "baseDelayMs" | "maxDelayMs" | "factor" | "jitter">): number;
+export declare function withRetry<T>(fn: (attempt: number) => Promise<T>, options?: RetryOptions): Promise<T>;
+export interface ResilienceOptions {
+    retry?: RetryOptions;
+    circuitBreaker?: CircuitBreaker;
+    /** If true, CircuitOpenError is not retried (default true). */
+    skipRetryOnOpenCircuit?: boolean;
+}
+/**
+ * Execute `fn` through optional circuit breaker + retry with exponential backoff.
+ */
+export declare function withResilience<T>(fn: (attempt: number) => Promise<T>, options?: ResilienceOptions): Promise<T>;
+/** Heuristic: retry rate limits, timeouts, and common transient network errors. */
+export declare function isTransientError(error: unknown): boolean;
+export declare function getCircuitBreaker(name: string, options?: CircuitBreakerOptions): CircuitBreaker;
+export declare function resetAllCircuitBreakers(): void;