agent-tempo 1.0.1

package/dist/http/event-bus.js

@@ -0,0 +1,365 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnsembleEventBus = exports.Subscription = exports.THROTTLE_SUPPRESS_MS = exports.RATE_LIMIT_WINDOW_MS = exports.DEFAULT_CHAT_RATE_LIMIT = exports.DEFAULT_ENSEMBLE_RATE_LIMIT = exports.DEFAULT_HEARTBEAT_SUPPRESS_MS = exports.DEFAULT_HEARTBEAT_MS = void 0;
+exports.topicOf = topicOf;
+exports.startHeartbeatTimer = startHeartbeatTimer;
+/**
+ * `EnsembleEventBus` — fan-out + ring buffer + replay engine that backs
+ * the `/v1/events/:ensemble` SSE endpoint (SSE-PROTOCOL.md §6, §7, §8).
+ *
+ * **Responsibilities**:
+ * - Allocate `<bootEpoch>:<seq>` ids via {@link SeqAllocator}.
+ * - Buffer the most recent N events for `Last-Event-ID` replay.
+ * - Fan out to every live subscriber, with a per-subscription queue
+ *   so a slow consumer doesn't backpressure faster ones.
+ * - Enforce wire-level rate caps (§8): ensemble-wide 50 ev/s ceiling
+ *   produces a `throttled` event and pauses non-essential streams
+ *   (`heartbeat`, `flags.changed`) for 1 s; chat 100 msg/s collapses
+ *   to a single `chat.compressed`.
+ * - Heartbeat: emit `heartbeat` every `heartbeatMs` (default 10 s) on
+ *   the bus, suppressed if any other event has been emitted in the
+ *   last `heartbeatSuppressMs` (default 8 s).
+ *
+ * **NOT in this module**:
+ * - Coalescing (phase debounce, schedule SHA-256 diff, flag diff,
+ *   host-profile hash compare) — those live in `aggregate.ts` and
+ *   feed clean events to the bus.
+ * - SSE framing / `Last-Event-ID` parsing — `sse-handler.ts` owns
+ *   that and consults the bus for replay slices.
+ */
+const ring_buffer_1 = require("./ring-buffer");
+/** Default heartbeat cadence — locked in by §6 / §8. */
+exports.DEFAULT_HEARTBEAT_MS = 10_000;
+/** Default heartbeat suppression window — §6. */
+exports.DEFAULT_HEARTBEAT_SUPPRESS_MS = 8_000;
+/** Ensemble-wide rate ceiling — §8. */
+exports.DEFAULT_ENSEMBLE_RATE_LIMIT = 50;
+/** Chat-only rate ceiling — §8. */
+exports.DEFAULT_CHAT_RATE_LIMIT = 100;
+/** Window over which both rate caps are evaluated. */
+exports.RATE_LIMIT_WINDOW_MS = 1_000;
+/** How long to suppress non-essential streams after `throttled` fires. */
+exports.THROTTLE_SUPPRESS_MS = 1_000;
+/** Event types that are essential — never dropped under throttling. */
+const ESSENTIAL_TYPES = new Set([
+    'snapshot',
+    'gap',
+    'throttled',
+    'chat.compressed',
+    'ensemble.created',
+    'ensemble.destroyed',
+    'player.added',
+    'player.removed',
+    'player.phase_changed',
+    'chat.appended',
+    'schedules.changed',
+    'host_profile.changed',
+]);
+/** Event types the bus suppresses for `THROTTLE_SUPPRESS_MS` after a `throttled` fires. */
+const NON_ESSENTIAL_AFTER_THROTTLE = new Set([
+    'heartbeat',
+    'flags.changed',
+]);
+/** Maps a `SseEventKind` to its filterable topic, or null when essential. */
+function topicOf(kind) {
+    switch (kind) {
+        case 'player.phase_changed': return 'phase';
+        case 'chat.appended':
+        case 'chat.compressed': return 'chat';
+        case 'flags.changed': return 'flags';
+        case 'schedules.changed': return 'schedules';
+        case 'heartbeat': return 'heartbeat';
+        default: return null;
+    }
+}
+/**
+ * One open SSE connection's view of the bus. Async iterator yields
+ * events in the order the bus emitted them. `close()` is idempotent
+ * and must be called when the underlying socket goes away.
+ */
+class Subscription {
+    opts;
+    queue = [];
+    resolveNext = null;
+    closed = false;
+    /** Caller's hook — bus calls this on close so the parent can drop us from its set. */
+    onClose = null;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Push an event onto the consumer queue. Bus → subscription. */
+    push(e) {
+        if (this.closed)
+            return;
+        if (!this.passesTopicFilter(e))
+            return;
+        if (this.resolveNext) {
+            const r = this.resolveNext;
+            this.resolveNext = null;
+            r({ value: e, done: false });
+        }
+        else {
+            this.queue.push(e);
+        }
+    }
+    next() {
+        if (this.closed && this.queue.length === 0) {
+            return Promise.resolve({ value: undefined, done: true });
+        }
+        if (this.queue.length > 0) {
+            return Promise.resolve({ value: this.queue.shift(), done: false });
+        }
+        return new Promise((resolve) => {
+            this.resolveNext = resolve;
+        });
+    }
+    async return() {
+        this.close();
+        return { value: undefined, done: true };
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.resolveNext) {
+            const r = this.resolveNext;
+            this.resolveNext = null;
+            r({ value: undefined, done: true });
+        }
+        if (this.onClose) {
+            const fn = this.onClose;
+            this.onClose = null;
+            try {
+                fn();
+            }
+            catch { /* ignore — bus internal */ }
+        }
+    }
+    /** True when `close()` has been called. */
+    get isClosed() { return this.closed; }
+    /** Snapshot of unread items — exposed for tests + diagnostics only. */
+    get pending() { return this.queue; }
+    passesTopicFilter(e) {
+        if (!this.opts.topics)
+            return true;
+        const cat = topicOf(e.type);
+        if (cat === null)
+            return true; // essential / always-emit
+        return this.opts.topics.has(cat);
+    }
+}
+exports.Subscription = Subscription;
+/** Concrete implementation. Same class powers per-ensemble + global buses. */
+class EnsembleEventBus {
+    scope;
+    bootEpoch;
+    allocator;
+    ring;
+    now;
+    subs = new Set();
+    ensembleRateLimit;
+    chatRateLimit;
+    heartbeatMs;
+    heartbeatSuppressMs;
+    closed = false;
+    /** Sliding window of recent emit timestamps for the ensemble-wide cap. */
+    recentEmits = [];
+    /** Sliding window of recent chat emit timestamps. */
+    recentChat = [];
+    /** Last time *any* non-heartbeat event was emitted — drives §6 heartbeat suppression. */
+    lastNonHeartbeatAt = 0;
+    /** When set, suppress `heartbeat` and `flags.changed` until this timestamp (post-`throttled` window). */
+    nonEssentialSuppressUntil = 0;
+    /** Last time `throttled` was emitted — at most once per `THROTTLE_SUPPRESS_MS` window. */
+    lastThrottledAt = 0;
+    /**
+     * `chat.compressed` deferred-emission state (PR #324 review followup).
+     *
+     * **Why deferred**: §6 says "excess collapses into a single
+     * `chat.compressed` event" — singular. If we emitted on the first
+     * drop, the `dropped` field would always read `1` even when 50+
+     * messages got dropped in the same burst. Misleading metadata —
+     * eng-4's PR-3 wrapper might surface the count as "N messages
+     * dropped" or use it for retry logic.
+     *
+     * **Resolution**: track every drop in `chatDropCount`; on first
+     * drop schedule a `chat.compressed` emission `RATE_LIMIT_WINDOW_MS`
+     * later. Subsequent drops in the same burst just increment the
+     * counter — no second timer, no second event. When the timer
+     * fires, emit `chat.compressed { dropped: <total>, since: <iso> }`
+     * and reset. A 150-message burst at rate 1/s now yields one
+     * `chat.compressed { dropped: 149 }` event, matching the spec
+     * intent.
+     *
+     * Note: "compression event fired" (timer ran, message went on the
+     * wire) is separate from "drop count accumulated" (drops have
+     * happened but the timer is still pending). Tests differentiate
+     * the two by advancing the fake timer and re-draining.
+     */
+    chatDropCount = 0;
+    chatCompressedTimer = null;
+    constructor(opts) {
+        this.scope = opts.scope;
+        this.allocator = opts.allocator;
+        this.bootEpoch = opts.allocator.bootEpoch;
+        this.ring = (0, ring_buffer_1.createRingBuffer)(opts.bufferCapacity ?? ring_buffer_1.RING_BUFFER_CAPACITY);
+        this.now = opts.now ?? Date.now;
+        this.ensembleRateLimit = opts.ensembleRateLimit ?? exports.DEFAULT_ENSEMBLE_RATE_LIMIT;
+        this.chatRateLimit = opts.chatRateLimit ?? exports.DEFAULT_CHAT_RATE_LIMIT;
+        this.heartbeatMs = opts.heartbeatMs ?? exports.DEFAULT_HEARTBEAT_MS;
+        this.heartbeatSuppressMs = opts.heartbeatSuppressMs ?? exports.DEFAULT_HEARTBEAT_SUPPRESS_MS;
+    }
+    oldestSeq() { return this.ring.oldestSeq; }
+    newestSeq() { return this.ring.newestSeq; }
+    nextSeq() { return this.allocator.peekNextSeq(); }
+    subscriberCount() { return this.subs.size; }
+    emit(type, payload) {
+        if (this.closed)
+            return null;
+        const now = this.now();
+        // Heartbeat path: respect §6 suppression — skip when any other
+        // event was emitted within the last `heartbeatSuppressMs`.
+        if (type === 'heartbeat') {
+            if (now - this.lastNonHeartbeatAt < this.heartbeatSuppressMs)
+                return null;
+            if (now < this.nonEssentialSuppressUntil)
+                return null;
+        }
+        // §8 chat 100/s cap — collapse excess to a single `chat.compressed`.
+        if (type === 'chat.appended') {
+            this.trimWindow(this.recentChat, now);
+            if (this.recentChat.length >= this.chatRateLimit) {
+                this.chatDropCount++;
+                if (!this.chatCompressedTimer) {
+                    // Defer emission so a single `chat.compressed` can carry the
+                    // total burst count, not just the first drop. See the
+                    // `chatDropCount` field comment for the contract.
+                    this.chatCompressedTimer = setTimeout(() => this.flushChatCompressed(), exports.RATE_LIMIT_WINDOW_MS);
+                    if (typeof this.chatCompressedTimer.unref === 'function') {
+                        this.chatCompressedTimer.unref();
+                    }
+                }
+                return null;
+            }
+            this.recentChat.push(now);
+        }
+        // §8 ensemble-wide 50/s cap — emit `throttled` once + suppress
+        // non-essential streams for 1 s.
+        if (NON_ESSENTIAL_AFTER_THROTTLE.has(type) && now < this.nonEssentialSuppressUntil) {
+            return null;
+        }
+        this.trimWindow(this.recentEmits, now);
+        if (!ESSENTIAL_TYPES.has(type) && this.recentEmits.length >= this.ensembleRateLimit) {
+            // Drop this non-essential event and emit `throttled` (capped per window).
+            if (now - this.lastThrottledAt >= exports.THROTTLE_SUPPRESS_MS) {
+                this.lastThrottledAt = now;
+                this.nonEssentialSuppressUntil = now + exports.THROTTLE_SUPPRESS_MS;
+                const since = new Date(now - exports.RATE_LIMIT_WINDOW_MS).toISOString();
+                this.emitInternal('throttled', { droppedSince: since, count: 1 }, now);
+            }
+            return null;
+        }
+        this.recentEmits.push(now);
+        return this.emitInternal(type, payload, now);
+    }
+    /**
+     * Internal emit — bypasses the §8 gates so the bus can self-emit
+     * `throttled` and `chat.compressed` while the gate is denying their
+     * trigger. Caller has already updated the rate-limit windows.
+     */
+    emitInternal(type, payload, now) {
+        const { eventId, tuple } = this.allocator.next();
+        const bufferable = type !== 'heartbeat'; // §7.1 — heartbeats are not replayed.
+        const event = { eventId, tuple, type, payload, emittedAt: now, bufferable };
+        if (bufferable)
+            this.ring.push({ seq: tuple.seq, payload: event });
+        if (type !== 'heartbeat')
+            this.lastNonHeartbeatAt = now;
+        for (const sub of this.subs)
+            sub.push(event);
+        return { eventId };
+    }
+    /**
+     * Emit the deferred `chat.compressed` event with the accumulated
+     * drop count, then reset. Called by the `setTimeout` scheduled in
+     * the chat-rate-cap path; tests may invoke it directly to bypass
+     * `vi.advanceTimersByTime` plumbing.
+     */
+    flushChatCompressed() {
+        this.chatCompressedTimer = null;
+        if (this.chatDropCount === 0)
+            return;
+        const dropped = this.chatDropCount;
+        this.chatDropCount = 0;
+        const now = this.now();
+        this.emitInternal('chat.compressed', {
+            dropped,
+            since: new Date(now - exports.RATE_LIMIT_WINDOW_MS).toISOString(),
+        }, now);
+    }
+    /** Test seam — force a deferred `chat.compressed` to flush synchronously. */
+    _flushChatCompressedForTest() {
+        if (this.chatCompressedTimer) {
+            clearTimeout(this.chatCompressedTimer);
+            this.chatCompressedTimer = null;
+        }
+        this.flushChatCompressed();
+    }
+    replayFrom(afterSeq) {
+        return this.ring.sliceFrom(afterSeq + 1).map((b) => b.payload);
+    }
+    subscribe(opts = {}) {
+        const sub = new Subscription(opts);
+        if (this.closed) {
+            // New subscriber on a closed bus — yield no events, just close.
+            sub.close();
+            return sub;
+        }
+        if (typeof opts.afterSeq === 'number') {
+            const replay = this.replayFrom(opts.afterSeq);
+            for (const e of replay)
+                sub.push(e);
+        }
+        sub.onClose = () => { this.subs.delete(sub); };
+        this.subs.add(sub);
+        return sub;
+    }
+    tickHeartbeat() {
+        return this.emit('heartbeat', { at: new Date(this.now()).toISOString() });
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.chatCompressedTimer) {
+            clearTimeout(this.chatCompressedTimer);
+            this.chatCompressedTimer = null;
+        }
+        for (const sub of [...this.subs])
+            sub.close();
+        this.subs.clear();
+    }
+    /** Drop entries older than `now - RATE_LIMIT_WINDOW_MS` from a sliding window. */
+    trimWindow(window, now) {
+        const cutoff = now - exports.RATE_LIMIT_WINDOW_MS;
+        while (window.length > 0 && window[0] < cutoff)
+            window.shift();
+    }
+}
+exports.EnsembleEventBus = EnsembleEventBus;
+/**
+ * Drive the heartbeat on a real timer. Returns a stop function. Call
+ * sites pass the bus's own `tickHeartbeat` so test wiring can stay
+ * synchronous.
+ */
+function startHeartbeatTimer(bus, intervalMs = exports.DEFAULT_HEARTBEAT_MS) {
+    const handle = setInterval(() => { bus.tickHeartbeat(); }, intervalMs);
+    // Don't keep the daemon alive solely on the heartbeat — workers + HTTP
+    // listener are the durable long-running references.
+    if (typeof handle.unref === 'function')
+        handle.unref();
+    return () => clearInterval(handle);
+}

package/dist/http/event-id.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `<bootEpoch>:<seq>` event-id allocator (SSE-PROTOCOL.md §5).
+ *
+ * **Format**: `"<bootEpoch>:<seq>"`. Two decimal-ASCII parts separated by
+ * a single `:`. `bootEpoch` is the daemon process boot time as Unix
+ * epoch milliseconds, frozen for the process lifetime. `seq` is a
+ * uint64 monotonic counter (starting at `0`) owned by a specific bus.
+ *
+ * **Why**: a daemon restart must NOT silently lose the snapshot bridge.
+ * Without an epoch prefix, a client reconnecting with `Last-Event-ID:
+ * 1234` after a daemon restart would be `seq > ringStart=0` and the
+ * server would try to replay events that don't exist. The two-stage
+ * gate (epoch first → `gap epoch-mismatch`, then seq → `gap overflow`)
+ * fixes that.
+ *
+ * **Scope**: `bootEpoch` is process-global. `seq` is per-bus —
+ * `EnsembleEventBus` owns one counter per ensemble; the global bus
+ * owns its own. Both v2 upgrade paths in ADR 0004 preserve this
+ * contract through the `EnsembleEventBus` interface.
+ */
+/** Parsed `(epoch, seq)` tuple. */
+export interface EventIdTuple {
+    epoch: number;
+    seq: number;
+}
+/**
+ * Format an `(epoch, seq)` tuple to the wire token. Both components
+ * MUST be non-negative integers; callers should never reach for
+ * floating-point arithmetic on these values.
+ */
+export declare function formatEventId(epoch: number, seq: number): string;
+/**
+ * Parse a wire token back into a tuple. Returns `null` for malformed
+ * input — caller treats that the same as an `epoch-mismatch` gap (the
+ * client is from a previous daemon process / a corrupt header / etc.).
+ *
+ * Permissive on whitespace because some HTTP intermediaries normalize
+ * `Last-Event-ID`; rejects anything outside `[0-9]:[0-9]`.
+ */
+export declare function parseEventId(token: string | undefined | null): EventIdTuple | null;
+/**
+ * Compare two event-id tuples lexicographically — epoch first, then seq.
+ * Returns negative / zero / positive following the standard
+ * comparator convention.
+ */
+export declare function compareEventIds(a: EventIdTuple, b: EventIdTuple): number;
+/**
+ * Allocates `seq` values for one bus. Each call to {@link next} returns
+ * the next monotonic id token bound to the configured `bootEpoch`.
+ *
+ * `bootEpoch` is supplied by the caller — the daemon constructs one
+ * value (`Date.now()`) and threads it through every bus instance so
+ * every event in the same process lifetime shares the prefix.
+ *
+ * **Overflow**: `seq` is a JavaScript `number`, safe up to
+ * `Number.MAX_SAFE_INTEGER` (2^53 − 1). At a sustained 1 event/ms
+ * that's ~285,000 years before wrap, so practically unreachable.
+ * If a single bus ever did approach this limit, the bus would need
+ * to `continueAsNew`-style re-bootstrap with a fresh `bootEpoch` —
+ * documented here so the assumption is on the record rather than
+ * implicit in the type.
+ */
+export declare class SeqAllocator {
+    readonly bootEpoch: number;
+    private nextSeq;
+    constructor(bootEpoch: number);
+    /** Allocate the next `(epoch, seq)` and return the formatted token. */
+    next(): {
+        eventId: string;
+        tuple: EventIdTuple;
+    };
+    /**
+     * The seq the next allocation will use — useful for ring buffer
+     * `ringStart` math without having to peek into a buffer.
+     */
+    peekNextSeq(): number;
+}

package/dist/http/event-id.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * `<bootEpoch>:<seq>` event-id allocator (SSE-PROTOCOL.md §5).
+ *
+ * **Format**: `"<bootEpoch>:<seq>"`. Two decimal-ASCII parts separated by
+ * a single `:`. `bootEpoch` is the daemon process boot time as Unix
+ * epoch milliseconds, frozen for the process lifetime. `seq` is a
+ * uint64 monotonic counter (starting at `0`) owned by a specific bus.
+ *
+ * **Why**: a daemon restart must NOT silently lose the snapshot bridge.
+ * Without an epoch prefix, a client reconnecting with `Last-Event-ID:
+ * 1234` after a daemon restart would be `seq > ringStart=0` and the
+ * server would try to replay events that don't exist. The two-stage
+ * gate (epoch first → `gap epoch-mismatch`, then seq → `gap overflow`)
+ * fixes that.
+ *
+ * **Scope**: `bootEpoch` is process-global. `seq` is per-bus —
+ * `EnsembleEventBus` owns one counter per ensemble; the global bus
+ * owns its own. Both v2 upgrade paths in ADR 0004 preserve this
+ * contract through the `EnsembleEventBus` interface.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SeqAllocator = void 0;
+exports.formatEventId = formatEventId;
+exports.parseEventId = parseEventId;
+exports.compareEventIds = compareEventIds;
+/**
+ * Format an `(epoch, seq)` tuple to the wire token. Both components
+ * MUST be non-negative integers; callers should never reach for
+ * floating-point arithmetic on these values.
+ */
+function formatEventId(epoch, seq) {
+    if (!Number.isInteger(epoch) || epoch < 0) {
+        throw new Error(`formatEventId: invalid epoch ${epoch}`);
+    }
+    if (!Number.isInteger(seq) || seq < 0) {
+        throw new Error(`formatEventId: invalid seq ${seq}`);
+    }
+    return `${epoch}:${seq}`;
+}
+/**
+ * Parse a wire token back into a tuple. Returns `null` for malformed
+ * input — caller treats that the same as an `epoch-mismatch` gap (the
+ * client is from a previous daemon process / a corrupt header / etc.).
+ *
+ * Permissive on whitespace because some HTTP intermediaries normalize
+ * `Last-Event-ID`; rejects anything outside `[0-9]:[0-9]`.
+ */
+function parseEventId(token) {
+    if (token == null)
+        return null;
+    const trimmed = token.trim();
+    const m = /^(\d+):(\d+)$/.exec(trimmed);
+    if (!m)
+        return null;
+    const epoch = Number(m[1]);
+    const seq = Number(m[2]);
+    if (!Number.isFinite(epoch) || !Number.isFinite(seq))
+        return null;
+    if (!Number.isInteger(epoch) || !Number.isInteger(seq))
+        return null;
+    return { epoch, seq };
+}
+/**
+ * Compare two event-id tuples lexicographically — epoch first, then seq.
+ * Returns negative / zero / positive following the standard
+ * comparator convention.
+ */
+function compareEventIds(a, b) {
+    if (a.epoch !== b.epoch)
+        return a.epoch < b.epoch ? -1 : 1;
+    if (a.seq !== b.seq)
+        return a.seq < b.seq ? -1 : 1;
+    return 0;
+}
+/**
+ * Allocates `seq` values for one bus. Each call to {@link next} returns
+ * the next monotonic id token bound to the configured `bootEpoch`.
+ *
+ * `bootEpoch` is supplied by the caller — the daemon constructs one
+ * value (`Date.now()`) and threads it through every bus instance so
+ * every event in the same process lifetime shares the prefix.
+ *
+ * **Overflow**: `seq` is a JavaScript `number`, safe up to
+ * `Number.MAX_SAFE_INTEGER` (2^53 − 1). At a sustained 1 event/ms
+ * that's ~285,000 years before wrap, so practically unreachable.
+ * If a single bus ever did approach this limit, the bus would need
+ * to `continueAsNew`-style re-bootstrap with a fresh `bootEpoch` —
+ * documented here so the assumption is on the record rather than
+ * implicit in the type.
+ */
+class SeqAllocator {
+    bootEpoch;
+    nextSeq = 0;
+    constructor(bootEpoch) {
+        this.bootEpoch = bootEpoch;
+        if (!Number.isInteger(bootEpoch) || bootEpoch < 0) {
+            throw new Error(`SeqAllocator: invalid bootEpoch ${bootEpoch}`);
+        }
+    }
+    /** Allocate the next `(epoch, seq)` and return the formatted token. */
+    next() {
+        const seq = this.nextSeq++;
+        return {
+            eventId: formatEventId(this.bootEpoch, seq),
+            tuple: { epoch: this.bootEpoch, seq },
+        };
+    }
+    /**
+     * The seq the next allocation will use — useful for ring buffer
+     * `ringStart` math without having to peek into a buffer.
+     */
+    peekNextSeq() {
+        return this.nextSeq;
+    }
+}
+exports.SeqAllocator = SeqAllocator;