agent-tempo 1.0.1

package/dist/http/ring-buffer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Fixed-capacity FIFO ring buffer for SSE replay (SSE-PROTOCOL.md §7.1).
+ *
+ * Holds at most `capacity` items. Past capacity, `push` evicts the
+ * oldest. Items are stored alongside a strictly-monotonic `seq`
+ * (provided by the caller, sourced from {@link SeqAllocator}) so
+ * replay can address ranges without scanning.
+ *
+ * **Default capacity**: 256 events per ensemble (§7.1). Power of two,
+ * ≤ 128 KiB worst case at ~500 B/event. Larger sizes don't materially
+ * widen the common-case reconnect window once §6 coalescing kicks in.
+ */
+/** Default per-ensemble buffer size — locked in by §7.1. */
+export declare const RING_BUFFER_CAPACITY = 256;
+export interface BufferedEvent<T> {
+    /** Strictly-monotonic seq value matching the wire `<bootEpoch>:<seq>`. */
+    seq: number;
+    payload: T;
+}
+export interface RingBuffer<T> {
+    /** Number of items currently held. */
+    readonly size: number;
+    /** Configured maximum size. */
+    readonly capacity: number;
+    /** `seq` of the oldest item, or `null` when empty. Monotone-increasing across the buffer's lifetime as evictions occur. */
+    readonly oldestSeq: number | null;
+    /** `seq` of the newest item, or `null` when empty. */
+    readonly newestSeq: number | null;
+    /** Append a new item. Evicts the oldest when at capacity. Throws on a non-monotonic seq (ring assumes the caller pulls from a SeqAllocator). */
+    push(item: BufferedEvent<T>): void;
+    /** Return every item with `seq >= fromSeq`, in original order. Empty array if none qualify. */
+    sliceFrom(fromSeq: number): BufferedEvent<T>[];
+    /** Snapshot of all items in order — escape hatch for tests + diagnostics. */
+    toArray(): BufferedEvent<T>[];
+}
+/**
+ * Build a ring buffer of the given capacity. Implementation uses a
+ * cyclic array — push is O(1), `sliceFrom` is O(n) where n is the
+ * number of returned items.
+ */
+export declare function createRingBuffer<T>(capacity?: number): RingBuffer<T>;

package/dist/http/ring-buffer.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Fixed-capacity FIFO ring buffer for SSE replay (SSE-PROTOCOL.md §7.1).
+ *
+ * Holds at most `capacity` items. Past capacity, `push` evicts the
+ * oldest. Items are stored alongside a strictly-monotonic `seq`
+ * (provided by the caller, sourced from {@link SeqAllocator}) so
+ * replay can address ranges without scanning.
+ *
+ * **Default capacity**: 256 events per ensemble (§7.1). Power of two,
+ * ≤ 128 KiB worst case at ~500 B/event. Larger sizes don't materially
+ * widen the common-case reconnect window once §6 coalescing kicks in.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RING_BUFFER_CAPACITY = void 0;
+exports.createRingBuffer = createRingBuffer;
+/** Default per-ensemble buffer size — locked in by §7.1. */
+exports.RING_BUFFER_CAPACITY = 256;
+/**
+ * Build a ring buffer of the given capacity. Implementation uses a
+ * cyclic array — push is O(1), `sliceFrom` is O(n) where n is the
+ * number of returned items.
+ */
+function createRingBuffer(capacity = exports.RING_BUFFER_CAPACITY) {
+    if (!Number.isInteger(capacity) || capacity < 1) {
+        throw new Error(`createRingBuffer: capacity must be a positive integer, got ${capacity}`);
+    }
+    const slots = new Array(capacity);
+    let head = 0; // index where the next push lands
+    let count = 0;
+    let lastSeq = null;
+    return {
+        get size() { return count; },
+        get capacity() { return capacity; },
+        get oldestSeq() {
+            if (count === 0)
+                return null;
+            const idx = (head - count + capacity) % capacity;
+            return slots[idx].seq;
+        },
+        get newestSeq() {
+            if (count === 0)
+                return null;
+            const idx = (head - 1 + capacity) % capacity;
+            return slots[idx].seq;
+        },
+        push(item) {
+            if (lastSeq !== null && item.seq <= lastSeq) {
+                throw new Error(`RingBuffer.push: non-monotonic seq ${item.seq} (last was ${lastSeq})`);
+            }
+            slots[head] = item;
+            head = (head + 1) % capacity;
+            if (count < capacity)
+                count++;
+            lastSeq = item.seq;
+        },
+        sliceFrom(fromSeq) {
+            const out = [];
+            if (count === 0)
+                return out;
+            const startIdx = (head - count + capacity) % capacity;
+            for (let i = 0; i < count; i++) {
+                const slot = slots[(startIdx + i) % capacity];
+                if (slot.seq >= fromSeq)
+                    out.push(slot);
+            }
+            return out;
+        },
+        toArray() {
+            const out = [];
+            if (count === 0)
+                return out;
+            const startIdx = (head - count + capacity) % capacity;
+            for (let i = 0; i < count; i++) {
+                out.push(slots[(startIdx + i) % capacity]);
+            }
+            return out;
+        },
+    };
+}

package/dist/http/server.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Daemon HTTP server — PR-1 of #94/#95.
+ *
+ * Hosts the read-only snapshot endpoints (`/v1/health`, `/v1/ensembles`,
+ * `/v1/state/:ensemble`, `/v1/hosts`) defined in `docs/SSE-PROTOCOL.md`.
+ * The SSE streaming endpoints (`/v1/events*`) are PR-2.
+ *
+ * Boot lifecycle:
+ *   1. Caller passes a {@link TempoClient}, namespace, and version to
+ *      {@link startHttpServer}.
+ *   2. Server binds to `127.0.0.1:8473` in production / `:8474` in dev mode
+ *      (defaults overridable via `AGENT_TEMPO_HTTP_BIND` /
+ *      `AGENT_TEMPO_DAEMON_PORT`; dev profile per ADR 0014 §5.1).
+ *   3. The bound port is written atomically to `~/.agent-tempo/daemon.port`.
+ *   4. Caller `await`s {@link HttpServerHandle.close} on shutdown — drains
+ *      in-flight requests, removes the port file, then resolves.
+ */
+import * as http from 'http';
+import type { TempoClient } from '../client/interface';
+import type { AggregateRunner } from './aggregate';
+import { type CorsConfig } from './cors';
+import { ConnectionCap } from './sse-handler';
+/** Default bind addr per SSE-PROTOCOL.md §1. */
+export declare const DEFAULT_BIND_ADDR = "127.0.0.1";
+/**
+ * Default port — `t-e-m-p-o` mnemonic for prod (8473), `+1` for dev (8474).
+ * ADR 0014 §5.1 flips this with the rest of the dev profile so prod and dev
+ * daemons can coexist on the same machine without binding the same port.
+ *
+ * Evaluated at module load time. The dev daemon child process inherits
+ * `AGENT_TEMPO_DEV_MODE=1` from its parent CLI (set by the
+ * `dev-mode-bootstrap` side-effect), so by the time this module loads,
+ * `isDevMode()` already returns the correct value.
+ */
+export declare const DEFAULT_PORT: number;
+export interface HttpServerOptions {
+    client: TempoClient;
+    namespace: string;
+    /**
+     * Shared task queue the daemon's workers poll. Surfaced verbatim on
+     * `GET /v1/health` so the dashboard's Settings → Connection panel
+     * reflects the runtime queue (#444).
+     */
+    taskQueue: string;
+    version: string;
+    /** Defaults to `process.env[ENV.HTTP_BIND] || '127.0.0.1'`. */
+    bindAddr?: string;
+    /**
+     * Defaults to `Number(process.env[ENV.DAEMON_PORT]) || DEFAULT_PORT` —
+     * where {@link DEFAULT_PORT} is `8473` in production and `8474` in dev
+     * mode (ADR 0014 §5.1). `0` → ephemeral.
+     */
+    port?: number;
+    /** Defaults to parsing `process.env[ENV.CORS_ORIGINS]`. */
+    allowedOrigins?: string[];
+    /**
+     * Override the port-file path. Tests pass an isolated temp path so they
+     * don't fight production daemons running on the same machine.
+     */
+    portFilePath?: string;
+    /**
+     * Inject the bearer token directly. Production callers pass `undefined`
+     * so the server reads/auto-generates from `~/.agent-tempo/config.json`.
+     */
+    httpToken?: string;
+    /**
+     * Test seam — lets unit tests stub `process.uptime`-style readings.
+     */
+    startedAtMs?: number;
+    /**
+     * Aggregate poll loop + per-ensemble buses. When provided, the
+     * server lights up `/v1/events/:ensemble` and `/v1/events` (PR-2).
+     * When absent, those routes return `503 streaming-not-implemented`
+     * (PR-1 behavior).
+     */
+    aggregate?: AggregateRunner;
+    /**
+     * Process-wide SSE connection cap. Defaults to
+     * `Number(process.env[ENV.SSE_MAX_CONNECTIONS]) || 100`. Set to a
+     * low value in tests to exercise the 503 path.
+     */
+    maxSseConnections?: number;
+}
+export interface HttpServerHandle {
+    /** The actual port the server is listening on (after `.listen()` resolves). */
+    readonly port: number;
+    /** The actual bind address. */
+    readonly bindAddr: string;
+    /**
+     * Subscriber count — always `0` in PR-1; PR-2 wires this to the live
+     * SSE subscriber set. Exposed for the `/v1/health` payload.
+     */
+    readonly subscriberCount: () => number;
+    /** Drain + close the listener. Removes the port file. */
+    close(): Promise<void>;
+}
+/**
+ * Start the HTTP server. Resolves once the listener is bound and the
+ * port file has been written.
+ */
+export declare function startHttpServer(opts: HttpServerOptions): Promise<HttpServerHandle>;
+interface HandleContext {
+    client: TempoClient;
+    namespace: string;
+    taskQueue: string;
+    version: string;
+    bindAddr: string;
+    corsConfig: CorsConfig;
+    httpToken: string | null;
+    startedAt: number;
+    subscriberCount: () => number;
+    /** Present when PR-2 streaming is wired; null on PR-1-only deployments. */
+    aggregate: AggregateRunner | null;
+    /** Process-wide SSE subscriber cap (§7.3). */
+    sseConnectionCap: ConnectionCap;
+}
+/**
+ * Top-level request dispatcher — exported for unit tests that want to
+ * exercise the handler without spinning up a real listener.
+ */
+export declare function handle(req: http.IncomingMessage, res: http.ServerResponse, ctx: HandleContext): Promise<void>;
+export {};