@controlvector/cv-agent 1.9.2 → 1.10.0

package/dist/utils/event-queue.d.ts

@@ -0,0 +1,66 @@
+/**
+ * EventQueue: persistent, ordered, at-least-once delivery of task events to CV-Hub.
+ *
+ * Background: cv-agent previously posted `output` / `output_final` events with
+ * fire-and-forget `.catch(() => {})`. Any transient network blip or server
+ * rejection silently dropped output, leaving the planner blind to what the
+ * executor actually produced.
+ *
+ * This queue:
+ *   - enqueues events in memory, drains them serially via the provided poster
+ *   - retries failures with bounded exponential backoff (1s, 2s, 4s, ...)
+ *   - spills pending events to disk every flush so a crash doesn't lose them
+ *   - reloads the on-disk spill on construction (next-run pickup)
+ *   - exposes flush() + close() so callers can drain on shutdown
+ *
+ * Events are tagged with a monotonic sequence_number assigned by the queue —
+ * the server uses it to reconstruct ordering deterministically even under
+ * same-millisecond bursts.
+ */
+export type QueuedEvent = {
+    event_type: string;
+    content: Record<string, unknown> | string;
+    needs_response?: boolean;
+    sequence_number: number;
+};
+export type EventPoster = (event: QueuedEvent) => Promise<void>;
+type Options = {
+    spillPath: string;
+    poster: EventPoster;
+    maxRetries?: number;
+    baseDelayMs?: number;
+    onError?: (err: Error, event: QueuedEvent, attempt: number) => void;
+};
+export declare class EventQueue {
+    private buffer;
+    private sequence;
+    private drainPromise;
+    private closed;
+    private spillDirty;
+    private readonly spillPath;
+    private readonly poster;
+    private readonly maxRetries;
+    private readonly baseDelayMs;
+    private readonly onError?;
+    constructor(opts: Options);
+    /** Load any events that were spilled to disk by a previous run. */
+    loadSpill(): Promise<void>;
+    /** Assign the next sequence number. Callers that want to stamp manually can read this. */
+    nextSequence(): number;
+    /** Enqueue an event. Returns the assigned sequence_number. */
+    enqueue(event: Omit<QueuedEvent, 'sequence_number'> & {
+        sequence_number?: number;
+    }): number;
+    /** Drain the buffer, retrying transient failures. Serial — concurrent calls share the same promise. */
+    private drain;
+    private drainInternal;
+    /** Flush: drain remaining events, then persist anything still pending to disk. */
+    flush(): Promise<void>;
+    /** Mark the queue closed and flush. Safe to call multiple times. */
+    close(): Promise<void>;
+    /** Number of events still pending delivery. */
+    size(): number;
+    private writeSpill;
+}
+export {};
+//# sourceMappingURL=event-queue.d.ts.map

package/dist/utils/event-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-queue.d.ts","sourceRoot":"","sources":["../../src/utils/event-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,MAAM,MAAM,WAAW,GAAG;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;IAC1C,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEhE,KAAK,OAAO,GAAG;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACrE,CAAC;AAEF,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAA4D;gBAEzE,IAAI,EAAE,OAAO;IAQzB,mEAAmE;IAC7D,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBhC,0FAA0F;IAC1F,YAAY,IAAI,MAAM;IAItB,8DAA8D;IAC9D,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,iBAAiB,CAAC,GAAG;QAAE,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM;IAa3F,uGAAuG;IACvG,OAAO,CAAC,KAAK;YAQC,aAAa;IAiC3B,kFAAkF;IAC5E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,oEAAoE;IAC9D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,+CAA+C;IAC/C,IAAI,IAAI,MAAM;YAIA,UAAU;CAczB"}

package/dist/utils/event-queue.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * EventQueue: persistent, ordered, at-least-once delivery of task events to CV-Hub.
+ *
+ * Background: cv-agent previously posted `output` / `output_final` events with
+ * fire-and-forget `.catch(() => {})`. Any transient network blip or server
+ * rejection silently dropped output, leaving the planner blind to what the
+ * executor actually produced.
+ *
+ * This queue:
+ *   - enqueues events in memory, drains them serially via the provided poster
+ *   - retries failures with bounded exponential backoff (1s, 2s, 4s, ...)
+ *   - spills pending events to disk every flush so a crash doesn't lose them
+ *   - reloads the on-disk spill on construction (next-run pickup)
+ *   - exposes flush() + close() so callers can drain on shutdown
+ *
+ * Events are tagged with a monotonic sequence_number assigned by the queue —
+ * the server uses it to reconstruct ordering deterministically even under
+ * same-millisecond bursts.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventQueue = void 0;
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+class EventQueue {
+    buffer = [];
+    sequence = 0;
+    drainPromise = null;
+    closed = false;
+    spillDirty = false;
+    spillPath;
+    poster;
+    maxRetries;
+    baseDelayMs;
+    onError;
+    constructor(opts) {
+        this.spillPath = opts.spillPath;
+        this.poster = opts.poster;
+        this.maxRetries = opts.maxRetries ?? 5;
+        this.baseDelayMs = opts.baseDelayMs ?? 1000;
+        this.onError = opts.onError;
+    }
+    /** Load any events that were spilled to disk by a previous run. */
+    async loadSpill() {
+        try {
+            const raw = await node_fs_1.promises.readFile(this.spillPath, 'utf8');
+            const lines = raw.split('\n').filter((l) => l.trim().length > 0);
+            for (const line of lines) {
+                const ev = JSON.parse(line);
+                this.buffer.push(ev);
+                if (ev.sequence_number >= this.sequence) {
+                    this.sequence = ev.sequence_number + 1;
+                }
+            }
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+    }
+    /** Assign the next sequence number. Callers that want to stamp manually can read this. */
+    nextSequence() {
+        return this.sequence++;
+    }
+    /** Enqueue an event. Returns the assigned sequence_number. */
+    enqueue(event) {
+        if (this.closed) {
+            throw new Error('EventQueue is closed');
+        }
+        const seq = event.sequence_number ?? this.nextSequence();
+        if (seq >= this.sequence)
+            this.sequence = seq + 1;
+        this.buffer.push({ ...event, sequence_number: seq });
+        this.spillDirty = true;
+        // Drain in the background — don't block the caller.
+        this.drain().catch(() => { });
+        return seq;
+    }
+    /** Drain the buffer, retrying transient failures. Serial — concurrent calls share the same promise. */
+    drain() {
+        if (this.drainPromise)
+            return this.drainPromise;
+        this.drainPromise = this.drainInternal().finally(() => {
+            this.drainPromise = null;
+        });
+        return this.drainPromise;
+    }
+    async drainInternal() {
+        try {
+            while (this.buffer.length > 0) {
+                const ev = this.buffer[0];
+                let delivered = false;
+                for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+                    try {
+                        await this.poster(ev);
+                        delivered = true;
+                        break;
+                    }
+                    catch (err) {
+                        this.onError?.(err instanceof Error ? err : new Error(String(err)), ev, attempt);
+                        if (attempt < this.maxRetries - 1) {
+                            await sleep(this.baseDelayMs * Math.pow(2, attempt));
+                        }
+                    }
+                }
+                if (delivered) {
+                    this.buffer.shift();
+                    this.spillDirty = true;
+                }
+                else {
+                    // Out of retries — leave on buffer so flush() can persist it,
+                    // and stop draining to avoid hot-looping on a dead server.
+                    break;
+                }
+            }
+        }
+        finally {
+            if (this.spillDirty) {
+                await this.writeSpill().catch(() => { });
+            }
+        }
+    }
+    /** Flush: drain remaining events, then persist anything still pending to disk. */
+    async flush() {
+        await this.drain();
+        await this.writeSpill();
+    }
+    /** Mark the queue closed and flush. Safe to call multiple times. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await this.flush();
+    }
+    /** Number of events still pending delivery. */
+    size() {
+        return this.buffer.length;
+    }
+    async writeSpill() {
+        try {
+            if (this.buffer.length === 0) {
+                await node_fs_1.promises.rm(this.spillPath, { force: true });
+            }
+            else {
+                await node_fs_1.promises.mkdir(path.dirname(this.spillPath), { recursive: true });
+                const body = this.buffer.map((e) => JSON.stringify(e)).join('\n') + '\n';
+                await node_fs_1.promises.writeFile(this.spillPath, body, 'utf8');
+            }
+            this.spillDirty = false;
+        }
+        catch {
+            // Spill errors are non-fatal — we still have events in memory.
+        }
+    }
+}
+exports.EventQueue = EventQueue;
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+//# sourceMappingURL=event-queue.js.map

package/dist/utils/event-queue.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@controlvector/cv-agent",
-  "version": "1.9.2",
+  "version": "1.10.0",
   "description": "Standalone agent daemon for CV-Hub — bridges Claude Code with CV-Hub task dispatch",
   "bin": {
     "cva": "./dist/bundle.cjs"