agent-tempo 1.0.1

package/dist/http/dashboard.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DASHBOARD_DIST = void 0;
+exports.handleDashboardStatic = handleDashboardStatic;
+exports.__setDashboardDistRootForTests = __setDashboardDistRootForTests;
+/**
+ * Static-asset handler for the packaged web dashboard (PR-1 of #340).
+ *
+ * Serves the prebuilt SPA at `/dashboard/*` from `dashboard/dist/`. Wiring
+ * lives in {@link ../http/server.ts}; this module is intentionally thin so
+ * the routing decisions (pre-auth carve-out vs post-auth dispatch) stay
+ * visible at the call site.
+ *
+ * **Contract**
+ *
+ * | Path                                | Behaviour                                                   |
+ * |-------------------------------------|-------------------------------------------------------------|
+ * | `/dashboard` or `/dashboard/`       | Serve `dashboard/dist/index.html`, `Cache-Control: no-cache` |
+ * | `/dashboard/<file-with-extension>`  | Serve the file with its MIME type, `immutable` cache; 404 if missing |
+ * | `/dashboard/<extensionless-route>`  | SPA fallback to `index.html` (React Router 7 client-side routing) |
+ * | `/dashboard/api/*`                  | 404 (reserved for daemon-side dashboard API; pair stub matched earlier) |
+ * | `/dashboard/<traversal>` (`..`)     | 404 — `assertSafePath` rejects anything outside `dashboard/dist` |
+ *
+ * **Cache headers** match the design doc (`docs/design/340-web-dashboard.md` §4.2):
+ * - `index.html` → `Cache-Control: no-cache` so dashboard updates ship immediately
+ * - hashed assets (`.js`, `.css`, fonts, images) → `Cache-Control: public, max-age=31536000, immutable`
+ *
+ * The pre-auth `GET /dashboard/api/pair/:token` carve-out (architect §4.1)
+ * is matched in `server.ts` before the bearer-auth gate; for PR-1 it returns
+ * 501 via {@link handlePairTokenStub}. PR-8 wires the real pair flow.
+ */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const safe_path_1 = require("../utils/safe-path");
+const responses_1 = require("./responses");
+/** Repo-relative path from the compiled `dist/` output — the production default. */
+exports.DASHBOARD_DIST = (0, path_1.resolve)(__dirname, '..', '..', 'dashboard', 'dist');
+/**
+ * Mutable dist root used by {@link handleDashboardStatic}. Tests reset
+ * this via the `__setDashboardDistRootForTests` hook below; production
+ * code never touches it.
+ */
+let activeDistRoot = exports.DASHBOARD_DIST;
+/** Long-cache header for hashed Vite output. */
+const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable';
+/** Short-cache header for `index.html` so SPA updates roll out immediately. */
+const HTML_CACHE = 'no-cache';
+const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'application/javascript; charset=utf-8',
+    '.mjs': 'application/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.map': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.txt': 'text/plain; charset=utf-8',
+};
+/** Extensions that count as "asset-shaped" — missing files 404 instead of SPA-falling-back. */
+const ASSET_EXTENSIONS = new Set(Object.keys(MIME));
+/**
+ * Serve a request under `/dashboard/*`. The caller in `server.ts` has
+ * already URL-parsed the request and gated by prefix, and passes the
+ * normalised `pathname` in to avoid a second parse on the hot path.
+ */
+function handleDashboardStatic(req, res, pathname) {
+    const distRoot = activeDistRoot;
+    // Strip the `/dashboard` prefix. `/dashboard` or `/dashboard/` ⇒ index.html.
+    const relative = pathname.slice('/dashboard'.length);
+    if (relative === '' || relative === '/') {
+        return serveIndexHtml(res, distRoot);
+    }
+    // `/dashboard/api/*` is reserved for daemon dashboard API endpoints. The
+    // pair-token carve-out is matched earlier in server.ts; anything else
+    // under `/api/` is a 404 — never SPA-fall-back, never serve a static
+    // file.
+    if (relative === '/api' || relative.startsWith('/api/')) {
+        return (0, responses_1.errorResponse)(res, 404, { error: 'not-found' });
+    }
+    // Resolve under `distRoot` and reject any path that escapes the root.
+    // The URL parser already normalised `..`, but `assertSafePath` is the
+    // canonical traversal guard used elsewhere in the codebase.
+    const candidate = (0, path_1.resolve)(distRoot, '.' + relative);
+    try {
+        (0, safe_path_1.assertSafePath)(candidate, [distRoot]);
+    }
+    catch {
+        return (0, responses_1.errorResponse)(res, 404, { error: 'not-found' });
+    }
+    const ext = (0, path_1.extname)(relative).toLowerCase();
+    const stat = safeStat(candidate);
+    if (stat?.isFile()) {
+        return streamFile(res, candidate, ext);
+    }
+    // No file at that path:
+    //   - asset-shaped (has a known extension) ⇒ real 404; never SPA-fall-back
+    //     for missing assets, otherwise a missing CSS file silently returns
+    //     index.html with content-type text/html and the browser logs MIME
+    //     errors.
+    //   - extensionless ⇒ SPA fallback to index.html so React Router 7 owns
+    //     client-side routing.
+    if (ext !== '' && ASSET_EXTENSIONS.has(ext)) {
+        return (0, responses_1.errorResponse)(res, 404, { error: 'not-found' });
+    }
+    return serveIndexHtml(res, distRoot);
+}
+function serveIndexHtml(res, distRoot) {
+    const indexPath = (0, path_1.join)(distRoot, 'index.html');
+    const stat = safeStat(indexPath);
+    if (!stat?.isFile()) {
+        return (0, responses_1.errorResponse)(res, 404, { error: 'dashboard-not-built' });
+    }
+    return streamFile(res, indexPath, '.html');
+}
+function streamFile(res, filePath, ext) {
+    const mime = MIME[ext] ?? 'application/octet-stream';
+    const cache = ext === '.html' ? HTML_CACHE : IMMUTABLE_CACHE;
+    res.writeHead(200, {
+        'Content-Type': mime,
+        'Cache-Control': cache,
+    });
+    const stream = (0, fs_1.createReadStream)(filePath);
+    stream.on('error', () => {
+        // Headers already written — best we can do is end the response.
+        try {
+            res.end();
+        }
+        catch { /* socket gone */ }
+    });
+    stream.pipe(res);
+}
+function safeStat(p) {
+    try {
+        return (0, fs_1.statSync)(p);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Test escape hatch — override the dist root used by
+ * {@link handleDashboardStatic}. Pass `null` to restore the production
+ * default.
+ *
+ * **Do not call from production code.** The double-underscore prefix
+ * marks this as a test-only hook (see ADR 0006). Used by
+ * `tests/http/dashboard-handler.test.ts` to point the handler at a
+ * fixture directory without modifying the real `dashboard/dist/`.
+ */
+function __setDashboardDistRootForTests(override) {
+    activeDistRoot = override ?? exports.DASHBOARD_DIST;
+}

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

@@ -0,0 +1,217 @@
+import { SeqAllocator, type EventIdTuple } from './event-id';
+import type { SseEventKind } from './event-types';
+/** Default heartbeat cadence — locked in by §6 / §8. */
+export declare const DEFAULT_HEARTBEAT_MS = 10000;
+/** Default heartbeat suppression window — §6. */
+export declare const DEFAULT_HEARTBEAT_SUPPRESS_MS = 8000;
+/** Ensemble-wide rate ceiling — §8. */
+export declare const DEFAULT_ENSEMBLE_RATE_LIMIT = 50;
+/** Chat-only rate ceiling — §8. */
+export declare const DEFAULT_CHAT_RATE_LIMIT = 100;
+/** Window over which both rate caps are evaluated. */
+export declare const RATE_LIMIT_WINDOW_MS = 1000;
+/** How long to suppress non-essential streams after `throttled` fires. */
+export declare const THROTTLE_SUPPRESS_MS = 1000;
+/**
+ * Internal wire shape for an event traveling the bus. The SSE handler
+ * formats this into the `id:` / `event:` / `data:` lines on the wire.
+ */
+export interface BusEvent {
+    eventId: string;
+    /** Tuple form of `eventId`, for ring-buffer indexing + comparison. */
+    tuple: EventIdTuple;
+    type: SseEventKind;
+    payload: unknown;
+    emittedAt: number;
+    /**
+     * `true` when the event lives in the ring (`Last-Event-ID` replay
+     * sees it). Heartbeats are connection-local and excluded per §7.1.
+     */
+    bufferable: boolean;
+}
+export interface SubscribeOpts {
+    /**
+     * Replay events with `seq > afterSeq` from the ring before live tail.
+     * Caller must have already verified epoch-match and that
+     * `afterSeq >= ringStart - 1` (otherwise the caller should drive a
+     * `gap` event).
+     */
+    afterSeq?: number;
+    /**
+     * Server-side topic filter. Setup events
+     * (`snapshot`, `gap`, `throttled`, `*.added`, `*.removed`,
+     * `*.created`, `*.destroyed`, `host_profile.changed`) always pass
+     * regardless of this filter.
+     */
+    topics?: ReadonlySet<TopicCategory>;
+}
+/** Maps to `?topics=...` query string per spec §6.1. */
+export type TopicCategory = 'phase' | 'chat' | 'flags' | 'schedules' | 'heartbeat';
+/** Maps a `SseEventKind` to its filterable topic, or null when essential. */
+export declare function topicOf(kind: SseEventKind): TopicCategory | 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.
+ */
+export declare class Subscription implements AsyncIterableIterator<BusEvent> {
+    readonly opts: SubscribeOpts;
+    private queue;
+    private resolveNext;
+    private closed;
+    /** Caller's hook — bus calls this on close so the parent can drop us from its set. */
+    onClose: (() => void) | null;
+    constructor(opts: SubscribeOpts);
+    /** Push an event onto the consumer queue. Bus → subscription. */
+    push(e: BusEvent): void;
+    next(): Promise<IteratorResult<BusEvent>>;
+    return(): Promise<IteratorResult<BusEvent>>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<BusEvent>;
+    close(): void;
+    /** True when `close()` has been called. */
+    get isClosed(): boolean;
+    /** Snapshot of unread items — exposed for tests + diagnostics only. */
+    get pending(): readonly BusEvent[];
+    private passesTopicFilter;
+}
+export interface EventBusOptions {
+    /** Free-form scope label for log lines (`'ensemble:demo'`, `'global'`). */
+    scope: string;
+    allocator: SeqAllocator;
+    /** Ring capacity. Defaults to {@link RING_BUFFER_CAPACITY}. */
+    bufferCapacity?: number;
+    /** Test seam — defaults to `Date.now`. */
+    now?: () => number;
+    /** Override §8 limits — used by tests; production keeps defaults. */
+    ensembleRateLimit?: number;
+    chatRateLimit?: number;
+    heartbeatMs?: number;
+    heartbeatSuppressMs?: number;
+}
+/**
+ * The bus interface — `EnsembleEventBus` and the global cluster bus
+ * share this surface. The aggregate poll loop is a strict consumer
+ * (only calls `emit`); the SSE handler reads `oldestSeq` /
+ * `replayFrom` / `subscribe`.
+ */
+export interface EventBus {
+    readonly scope: string;
+    readonly bootEpoch: number;
+    /** Ring's oldest seq, or `null` when empty. */
+    oldestSeq(): number | null;
+    /** Ring's newest seq, or `null` when empty. */
+    newestSeq(): number | null;
+    /** The next seq the allocator will use — useful for `lastEventId` math even when the ring is empty. */
+    nextSeq(): number;
+    /**
+     * Emit a typed event. Returns the assigned eventId, or `null` when
+     * the event was suppressed by §8 caps. Heartbeats with §6
+     * suppression also return `null`.
+     */
+    emit(type: SseEventKind, payload: unknown): {
+        eventId: string;
+    } | null;
+    /** Replay events with `seq > afterSeq` from the ring buffer. */
+    replayFrom(afterSeq: number): BusEvent[];
+    /** Open a new subscription. Caller drives snapshot/gap upstream. */
+    subscribe(opts?: SubscribeOpts): Subscription;
+    /**
+     * Tick the heartbeat — emits `heartbeat` only if the §6 suppression
+     * gate is open. Production schedules this on a timer; tests call it
+     * directly. Returns the heartbeat's eventId, or `null` if suppressed.
+     */
+    tickHeartbeat(): {
+        eventId: string;
+    } | null;
+    /** Drain subscribers and stop emitting. Idempotent. */
+    close(): void;
+    /** Live subscriber count — used by `/v1/health.subscriberCount`. */
+    subscriberCount(): number;
+}
+/** Concrete implementation. Same class powers per-ensemble + global buses. */
+export declare class EnsembleEventBus implements EventBus {
+    readonly scope: string;
+    readonly bootEpoch: number;
+    private readonly allocator;
+    private readonly ring;
+    private readonly now;
+    private readonly subs;
+    private readonly ensembleRateLimit;
+    private readonly chatRateLimit;
+    private readonly heartbeatMs;
+    private readonly heartbeatSuppressMs;
+    private closed;
+    /** Sliding window of recent emit timestamps for the ensemble-wide cap. */
+    private readonly recentEmits;
+    /** Sliding window of recent chat emit timestamps. */
+    private readonly recentChat;
+    /** Last time *any* non-heartbeat event was emitted — drives §6 heartbeat suppression. */
+    private lastNonHeartbeatAt;
+    /** When set, suppress `heartbeat` and `flags.changed` until this timestamp (post-`throttled` window). */
+    private nonEssentialSuppressUntil;
+    /** Last time `throttled` was emitted — at most once per `THROTTLE_SUPPRESS_MS` window. */
+    private lastThrottledAt;
+    /**
+     * `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.
+     */
+    private chatDropCount;
+    private chatCompressedTimer;
+    constructor(opts: EventBusOptions);
+    oldestSeq(): number | null;
+    newestSeq(): number | null;
+    nextSeq(): number;
+    subscriberCount(): number;
+    emit(type: SseEventKind, payload: unknown): {
+        eventId: string;
+    } | null;
+    /**
+     * 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.
+     */
+    private emitInternal;
+    /**
+     * 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.
+     */
+    private flushChatCompressed;
+    /** Test seam — force a deferred `chat.compressed` to flush synchronously. */
+    _flushChatCompressedForTest(): void;
+    replayFrom(afterSeq: number): BusEvent[];
+    subscribe(opts?: SubscribeOpts): Subscription;
+    tickHeartbeat(): {
+        eventId: string;
+    } | null;
+    close(): void;
+    /** Drop entries older than `now - RATE_LIMIT_WINDOW_MS` from a sliding window. */
+    private trimWindow;
+}
+/**
+ * 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.
+ */
+export declare function startHeartbeatTimer(bus: Pick<EventBus, 'tickHeartbeat'>, intervalMs?: number): () => void;