chapterhouse 0.3.8 → 0.3.10

package/dist/copilot/task-event-log.js

@@ -0,0 +1,139 @@
+/**
+ * Per-task in-memory event ring buffer — #116.
+ *
+ * Maintains a `Map<taskId, RingBuffer<TaskEvent>>` in the daemon process,
+ * capped at 500 events per task. Subscribes to the process-wide
+ * `squadEventBus` for `session:tool_call` events so the ring buffer stays
+ * in sync without the caller needing to wire anything extra.
+ *
+ * Consumers:
+ *  1. `GET /api/workers/:taskId/events` — REST hydration on page-load / SSE reconnect.
+ *     The ring buffer is checked first (fast path, in-memory); SQLite is the fallback
+ *     for completed tasks whose ring buffer has been cleared.
+ *  2. Per-task SSE subscribers — `subscribeTaskLog` delivers events as they arrive
+ *     so the SSE frame fires immediately (no SQLite round-trip).
+ *
+ * Lifecycle:
+ *  - `initTaskEventLog()` must be called once from `initOrchestrator()`.
+ *    It returns an unsub function; call it on shutdown / test teardown.
+ *  - `clearTaskLog(taskId)` should be called when a task is destroyed so the
+ *    Map doesn't grow unbounded.
+ *
+ * @module copilot/task-event-log
+ */
+import { squadEventBus } from "./squad-event-bus.js";
+import { RingBuffer } from "./ring-buffer.js";
+// ---------------------------------------------------------------------------
+// Ring buffer — re-export so existing imports stay compatible
+// ---------------------------------------------------------------------------
+export { RingBuffer };
+export const RING_BUFFER_CAPACITY = 500;
+// ---------------------------------------------------------------------------
+// Singleton state
+// ---------------------------------------------------------------------------
+const taskBuffers = new Map();
+const taskListeners = new Map();
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function getOrCreateBuffer(taskId) {
+    let buf = taskBuffers.get(taskId);
+    if (!buf) {
+        buf = new RingBuffer(RING_BUFFER_CAPACITY);
+        taskBuffers.set(taskId, buf);
+    }
+    return buf;
+}
+function notifyListeners(taskId, event) {
+    const listeners = taskListeners.get(taskId);
+    if (!listeners)
+        return;
+    for (const fn of listeners) {
+        try {
+            fn(event);
+        }
+        catch { /* non-fatal */ }
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Subscribe to the squadEventBus and maintain the ring buffer.
+ * Call once from initOrchestrator(). Returns an unsub / cleanup function.
+ */
+export function initTaskEventLog() {
+    const unsubToolCall = squadEventBus.subscribe("session:tool_call", (event) => {
+        const taskId = event.sessionId;
+        if (!taskId)
+            return;
+        const p = event.payload;
+        const taskEvent = {
+            id: 0, // not a DB row — id is meaningless for ring-buffer entries
+            taskId,
+            seq: p._seq ?? 0,
+            ts: p._ts ?? Date.now(),
+            kind: p._kind === "tool_complete" ? "tool_complete" : "tool_start",
+            toolName: p.toolName ?? null,
+            summary: p._summary ?? null,
+        };
+        const buf = getOrCreateBuffer(taskId);
+        buf.push(taskEvent);
+        notifyListeners(taskId, taskEvent);
+    });
+    const unsubDestroyed = squadEventBus.subscribe("session:destroyed", (event) => {
+        if (event.sessionId)
+            clearTaskLog(event.sessionId);
+    });
+    return () => {
+        unsubToolCall();
+        unsubDestroyed();
+    };
+}
+/**
+ * Return all ring-buffered events for a task, optionally filtered to seq > afterSeq.
+ * Returns an empty array if the task has no buffer (task unknown or already cleared).
+ */
+export function getTaskLogEvents(taskId, afterSeq = 0) {
+    const buf = taskBuffers.get(taskId);
+    if (!buf)
+        return [];
+    const all = buf.getAll();
+    return afterSeq === 0 ? all : all.filter((e) => e.seq > afterSeq);
+}
+/**
+ * Subscribe to live events for a specific task.
+ * Listener is called synchronously when a new event arrives (from the bus subscriber above).
+ * Returns an unsubscribe function.
+ */
+export function subscribeTaskLog(taskId, listener) {
+    let listeners = taskListeners.get(taskId);
+    if (!listeners) {
+        listeners = new Set();
+        taskListeners.set(taskId, listeners);
+    }
+    listeners.add(listener);
+    return () => {
+        const ls = taskListeners.get(taskId);
+        if (ls) {
+            ls.delete(listener);
+            if (ls.size === 0)
+                taskListeners.delete(taskId);
+        }
+    };
+}
+/**
+ * Remove the ring buffer and any listeners for a task.
+ * Called automatically when `session:destroyed` fires; also callable manually.
+ */
+export function clearTaskLog(taskId) {
+    taskBuffers.delete(taskId);
+    taskListeners.delete(taskId);
+}
+/**
+ * Number of tasks currently tracked. Useful for testing and diagnostics.
+ */
+export function taskLogSize() {
+    return taskBuffers.size;
+}
+//# sourceMappingURL=task-event-log.js.map

package/dist/copilot/task-event-log.test.js

@@ -0,0 +1,275 @@
+/**
+ * Unit tests for src/copilot/task-event-log.ts — #116
+ *
+ * Covers:
+ *  1. RingBuffer capacity and eviction
+ *  2. RingBuffer getAll returns a copy
+ *  3. Ring buffer singleton: bus events populate the buffer
+ *  4. getTaskLogEvents returns [] for unknown taskId
+ *  5. getTaskLogEvents filters by afterSeq
+ *  6. subscribeTaskLog delivers events as they arrive
+ *  7. subscribeTaskLog unsub stops delivery
+ *  8. clearTaskLog removes buffer and listeners
+ *  9. session:destroyed auto-clears the ring buffer
+ * 10. Multiple tasks tracked independently
+ * 11. RING_BUFFER_CAPACITY constant: 500 items, evicts oldest
+ *
+ * Uses node:test (same pattern as hooks.test.ts, agents.squad.test.ts) so the
+ * daemon's `npm test` runner (node --test) picks these up from dist/.
+ */
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { EventBus } from "@bradygaster/squad-sdk/runtime/event-bus";
+import { RingBuffer, RING_BUFFER_CAPACITY, } from "./task-event-log.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeToolCallEvent(opts) {
+    return {
+        type: "session:tool_call",
+        sessionId: opts.sessionId,
+        payload: {
+            toolName: opts.toolName ?? "bash",
+            toolArgs: {},
+            _kind: opts.kind ?? "tool_start",
+            _seq: opts.seq ?? 1,
+            _ts: opts.ts ?? Date.now(),
+            _summary: opts.summary ?? null,
+        },
+        timestamp: new Date(),
+    };
+}
+function makeDestroyedEvent(sessionId) {
+    return {
+        type: "session:destroyed",
+        sessionId,
+        agentName: "test-agent",
+        payload: { agentName: "test-agent", reason: "complete" },
+        timestamp: new Date(),
+    };
+}
+/**
+ * Builds an isolated task-event-log wired to a fresh EventBus so tests don't
+ * share state through the process-level squadEventBus singleton.
+ */
+function buildIsolatedLog(bus) {
+    const CAPACITY = RING_BUFFER_CAPACITY;
+    const buffers = new Map();
+    const listeners = new Map();
+    function getOrCreate(taskId) {
+        let b = buffers.get(taskId);
+        if (!b) {
+            b = new RingBuffer(CAPACITY);
+            buffers.set(taskId, b);
+        }
+        return b;
+    }
+    function notify(taskId, event) {
+        const ls = listeners.get(taskId);
+        if (!ls)
+            return;
+        for (const fn of ls) {
+            try {
+                fn(event);
+            }
+            catch { /* non-fatal */ }
+        }
+    }
+    const unsubToolCall = bus.subscribe("session:tool_call", (event) => {
+        const taskId = event.sessionId;
+        if (!taskId)
+            return;
+        const p = event.payload;
+        const ev = {
+            id: 0, taskId,
+            seq: p._seq ?? 0,
+            ts: p._ts ?? Date.now(),
+            kind: p._kind === "tool_complete" ? "tool_complete" : "tool_start",
+            toolName: p.toolName ?? null,
+            summary: p._summary ?? null,
+        };
+        getOrCreate(taskId).push(ev);
+        notify(taskId, ev);
+    });
+    const unsubDestroyed = bus.subscribe("session:destroyed", (event) => {
+        if (event.sessionId) {
+            buffers.delete(event.sessionId);
+            listeners.delete(event.sessionId);
+        }
+    });
+    return {
+        getEvents: (taskId, afterSeq = 0) => {
+            const buf = buffers.get(taskId);
+            if (!buf)
+                return [];
+            const all = buf.getAll();
+            return afterSeq === 0 ? all : all.filter((e) => e.seq > afterSeq);
+        },
+        subscribe: (taskId, fn) => {
+            let ls = listeners.get(taskId);
+            if (!ls) {
+                ls = new Set();
+                listeners.set(taskId, ls);
+            }
+            ls.add(fn);
+            return () => {
+                const lss = listeners.get(taskId);
+                if (lss) {
+                    lss.delete(fn);
+                    if (lss.size === 0)
+                        listeners.delete(taskId);
+                }
+            };
+        },
+        clear: (taskId) => {
+            buffers.delete(taskId);
+            listeners.delete(taskId);
+        },
+        size: () => buffers.size,
+        shutdown: () => { unsubToolCall(); unsubDestroyed(); },
+    };
+}
+// ---------------------------------------------------------------------------
+// RingBuffer — pure class tests
+// ---------------------------------------------------------------------------
+describe("RingBuffer", () => {
+    it("starts empty", () => {
+        const buf = new RingBuffer(3);
+        assert.equal(buf.size, 0);
+        assert.deepEqual(buf.getAll(), []);
+    });
+    it("pushes items up to capacity", () => {
+        const buf = new RingBuffer(3);
+        buf.push(1);
+        buf.push(2);
+        buf.push(3);
+        assert.equal(buf.size, 3);
+        assert.deepEqual(buf.getAll(), [1, 2, 3]);
+    });
+    it("evicts oldest item when capacity is exceeded", () => {
+        const buf = new RingBuffer(3);
+        buf.push(1);
+        buf.push(2);
+        buf.push(3);
+        buf.push(4);
+        assert.equal(buf.size, 3);
+        assert.deepEqual(buf.getAll(), [2, 3, 4]);
+    });
+    it("evicts multiple oldest for many pushes", () => {
+        const buf = new RingBuffer(3);
+        for (let i = 1; i <= 10; i++)
+            buf.push(i);
+        assert.equal(buf.size, 3);
+        assert.deepEqual(buf.getAll(), [8, 9, 10]);
+    });
+    it("getAll returns a copy, not the internal array", () => {
+        const buf = new RingBuffer(3);
+        buf.push(1);
+        const snapshot = buf.getAll();
+        buf.push(2);
+        assert.deepEqual(snapshot, [1]);
+    });
+    it("capacity constant is 500", () => {
+        const buf = new RingBuffer(RING_BUFFER_CAPACITY);
+        assert.equal(buf.capacity, 500);
+    });
+    it("throws RangeError for capacity < 1", () => {
+        assert.throws(() => new RingBuffer(0), { name: "RangeError" });
+    });
+    it("501 pushes: only last 500 remain, oldest evicted", () => {
+        const buf = new RingBuffer(RING_BUFFER_CAPACITY);
+        for (let i = 1; i <= 501; i++)
+            buf.push(i);
+        assert.equal(buf.size, 500);
+        assert.equal(buf.getAll()[0], 2); // 1 was evicted
+        assert.equal(buf.getAll()[499], 501); // newest retained
+    });
+});
+// ---------------------------------------------------------------------------
+// Task event log (bus-wired) tests
+// ---------------------------------------------------------------------------
+describe("task event log — bus-wired", () => {
+    let bus;
+    let log;
+    beforeEach(() => {
+        bus = new EventBus();
+        log = buildIsolatedLog(bus);
+    });
+    afterEach(() => {
+        log.shutdown();
+    });
+    it("returns [] for an unknown taskId", () => {
+        assert.deepEqual(log.getEvents("no-such-task"), []);
+    });
+    it("populates ring buffer on session:tool_call bus event", async () => {
+        await bus.emit(makeToolCallEvent({ sessionId: "task-001", kind: "tool_start", seq: 1, toolName: "view" }));
+        const events = log.getEvents("task-001");
+        assert.equal(events.length, 1);
+        assert.equal(events[0].kind, "tool_start");
+        assert.equal(events[0].toolName, "view");
+        assert.equal(events[0].taskId, "task-001");
+        assert.equal(events[0].seq, 1);
+    });
+    it("accumulates multiple events in order", async () => {
+        await bus.emit(makeToolCallEvent({ sessionId: "task-002", kind: "tool_start", seq: 1, toolName: "bash" }));
+        await bus.emit(makeToolCallEvent({ sessionId: "task-002", kind: "tool_complete", seq: 2, summary: "ok" }));
+        await bus.emit(makeToolCallEvent({ sessionId: "task-002", kind: "tool_start", seq: 3, toolName: "view" }));
+        const events = log.getEvents("task-002");
+        assert.equal(events.length, 3);
+        assert.equal(events[0].seq, 1);
+        assert.equal(events[2].seq, 3);
+        assert.equal(events[1].kind, "tool_complete");
+    });
+    it("getEvents filters by afterSeq", async () => {
+        await bus.emit(makeToolCallEvent({ sessionId: "task-003", seq: 1 }));
+        await bus.emit(makeToolCallEvent({ sessionId: "task-003", seq: 2 }));
+        await bus.emit(makeToolCallEvent({ sessionId: "task-003", seq: 3 }));
+        assert.equal(log.getEvents("task-003", 1).length, 2);
+        assert.equal(log.getEvents("task-003", 2).length, 1);
+        assert.equal(log.getEvents("task-003", 3).length, 0);
+    });
+    it("subscribe delivers events as they arrive", async () => {
+        const received = [];
+        log.subscribe("task-004", (e) => received.push(e.toolName ?? "?"));
+        await bus.emit(makeToolCallEvent({ sessionId: "task-004", toolName: "bash" }));
+        await bus.emit(makeToolCallEvent({ sessionId: "task-004", toolName: "view" }));
+        assert.deepEqual(received, ["bash", "view"]);
+    });
+    it("subscribe unsub stops delivery", async () => {
+        const received = [];
+        const unsub = log.subscribe("task-005", (e) => received.push(e.toolName ?? "?"));
+        await bus.emit(makeToolCallEvent({ sessionId: "task-005", toolName: "bash" }));
+        unsub();
+        await bus.emit(makeToolCallEvent({ sessionId: "task-005", toolName: "view" }));
+        assert.equal(received.length, 1);
+        assert.equal(received[0], "bash");
+    });
+    it("clearTaskLog removes buffer and listeners", async () => {
+        await bus.emit(makeToolCallEvent({ sessionId: "task-006", seq: 1 }));
+        assert.equal(log.getEvents("task-006").length, 1);
+        log.clear("task-006");
+        assert.equal(log.getEvents("task-006").length, 0);
+    });
+    it("session:destroyed auto-clears ring buffer", async () => {
+        await bus.emit(makeToolCallEvent({ sessionId: "task-007", seq: 1 }));
+        await bus.emit(makeToolCallEvent({ sessionId: "task-007", seq: 2 }));
+        assert.equal(log.getEvents("task-007").length, 2);
+        await bus.emit(makeDestroyedEvent("task-007"));
+        assert.equal(log.getEvents("task-007").length, 0);
+    });
+    it("tracks multiple tasks independently", async () => {
+        await bus.emit(makeToolCallEvent({ sessionId: "task-A", seq: 1, toolName: "bash" }));
+        await bus.emit(makeToolCallEvent({ sessionId: "task-B", seq: 1, toolName: "view" }));
+        await bus.emit(makeToolCallEvent({ sessionId: "task-A", seq: 2, toolName: "edit" }));
+        assert.equal(log.getEvents("task-A").length, 2);
+        assert.equal(log.getEvents("task-B").length, 1);
+        assert.equal(log.getEvents("task-A")[0].toolName, "bash");
+        assert.equal(log.getEvents("task-B")[0].toolName, "view");
+        assert.equal(log.size(), 2);
+    });
+    it("events for wrong taskId are not visible to other tasks", async () => {
+        await bus.emit(makeToolCallEvent({ sessionId: "task-X", seq: 1 }));
+        assert.equal(log.getEvents("task-Y").length, 0);
+    });
+});
+//# sourceMappingURL=task-event-log.test.js.map