agent-tempo 1.0.1

package/dist/http/snapshot.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnsembleNotFoundError = exports.SNAPSHOT_CHAT_LIMIT = void 0;
+exports.toPlayerSummaryV1 = toPlayerSummaryV1;
+exports.buildEnsembleSnapshot = buildEnsembleSnapshot;
+const types_1 = require("../types");
+const event_types_1 = require("./event-types");
+/**
+ * Runtime type guard — `MaestroPlayerInfo.agentType` is intentionally typed
+ * as open `string` so a forked daemon advertising a never-shipped adapter
+ * (e.g. `'gemini'`) doesn't crash the projection at the type level. The
+ * guard narrows the open-string input to the closed wire union before it
+ * reaches `PlayerSummaryV1`. Anything not in `AGENT_TYPES` (the canonical
+ * source-of-truth list at `src/types.ts`) falls back to `'claude'` in the
+ * caller — same defensive default as pre-#535, just over a wider whitelist.
+ */
+function isWireAgentType(s) {
+    return types_1.AGENT_TYPES.includes(s);
+}
+/**
+ * Maximum chat messages embedded in the snapshot. Larger paging is left
+ * to the explicit `getEnsembleChat` query / `recall` tool — the snapshot
+ * is a steady-state view, not a paginator.
+ */
+exports.SNAPSHOT_CHAT_LIMIT = 50;
+/** Thrown when the ensemble doesn't exist; route handler maps to 404. */
+class EnsembleNotFoundError extends Error {
+    ensemble;
+    constructor(ensemble) {
+        super(`ensemble not found: ${ensemble}`);
+        this.ensemble = ensemble;
+        this.name = 'EnsembleNotFoundError';
+    }
+}
+exports.EnsembleNotFoundError = EnsembleNotFoundError;
+/**
+ * Fan-out helper — run all client queries in parallel and tolerate
+ * per-query failures (an empty array / `false` is the right fallback for
+ * every soft-failure case the existing TempoClient already returns).
+ */
+async function fanOut(queries) {
+    const keys = Object.keys(queries);
+    const results = await Promise.all(keys.map((key) => queries[key]().catch(() => undefined)));
+    const out = {};
+    keys.forEach((key, i) => {
+        out[key] = results[i];
+    });
+    return out;
+}
+/**
+ * Project a `MaestroPlayerInfo` into the wire-stable `PlayerSummaryV1`.
+ * Drops fields that aren't part of the v1 contract; passes `agentType`
+ * through verbatim — the wire union mirrors {@link AgentType} from
+ * `src/types.ts`, so every shipped adapter projects to its own label
+ * (#535). Pre-#535 the wire union was closed at `'claude' | 'copilot' |
+ * 'mock'` and headless adapters were coerced to `'claude'`, which made
+ * them indistinguishable from interactive Claude Code players in the
+ * dashboard. The union expansion is additive per the §6 stability rule
+ * in `event-types.ts` — no `/v1/` → `/v2/` bump.
+ *
+ * `wireMeta` is the session-level projection from
+ * `TempoClient.getPlayerWireMeta` (Issue #399 W2). Pass `null` (or omit)
+ * when the session workflow couldn't be queried — the projection then
+ * carries no `runId` / `messaging` / `lease` fields and the dashboard
+ * renders `—` placeholders.
+ *
+ * `activityCount` passes through from `MaestroPlayerInfo` (Q5.6).
+ * `MaestroPlayerInfo.lastActivityAt` maps to the wire field
+ * `PlayerSummaryV1.lastHeartbeatAt` — same data, rename happens at the
+ * wire boundary so consumers read one canonical name.
+ */
+function toPlayerSummaryV1(p, wireMeta = null) {
+    // `MaestroPlayerInfo.agentType` is intentionally open (`string`) so a
+    // forked daemon advertising a never-shipped adapter doesn't crash the
+    // type system here. `isWireAgentType` narrows it against `AGENT_TYPES`
+    // (the canonical source-of-truth list); anything outside falls back to
+    // `'claude'` — same defensive default as pre-#535, just enforced over
+    // a wider whitelist. The drift detector in `test/snapshot.test.ts`
+    // asserts the wire union mirrors `AgentType`, so a future shipped
+    // adapter missing from one of the two surfaces fails CI.
+    const agentType = isWireAgentType(p.agentType) ? p.agentType : 'claude';
+    return {
+        playerId: p.playerId,
+        ensemble: p.ensemble,
+        hostname: p.hostname,
+        isConductor: p.isConductor,
+        agentType,
+        ...(p.playerType !== undefined ? { playerType: p.playerType } : {}),
+        ...(p.phase !== undefined ? { phase: p.phase } : {}),
+        part: p.part ?? '',
+        workDir: p.workDir ?? '',
+        ...(p.gitBranch !== undefined ? { gitBranch: p.gitBranch } : {}),
+        // Issue #399 Q5.6 — pass-through from MaestroPlayerInfo.
+        ...(p.activityCount !== undefined ? { activityCount: p.activityCount } : {}),
+        // Wire-name rename: source `lastActivityAt` → contract `lastHeartbeatAt`
+        // (#389 R3.P1.4). Aggregate's phase-change diff reads the wire name.
+        ...(p.lastActivityAt !== undefined ? { lastHeartbeatAt: p.lastActivityAt } : {}),
+        // Issue #399 W2 — session-query fan-out merged in when reachable.
+        ...(wireMeta?.runId !== undefined ? { runId: wireMeta.runId } : {}),
+        ...(wireMeta?.messaging !== undefined ? { messaging: wireMeta.messaging } : {}),
+        ...(wireMeta?.lease !== undefined ? { lease: wireMeta.lease } : {}),
+    };
+}
+/**
+ * Build the `/v1/state/:ensemble` payload. Throws
+ * {@link EnsembleNotFoundError} when the requested ensemble has no live
+ * workflows; route handler turns that into a 404.
+ */
+async function buildEnsembleSnapshot(client, ensemble, opts = {}) {
+    // Existence gate — `listEnsembles` is fast (single workflow.list scan)
+    // and returns the canonical state classification (online/paused/offline).
+    const ensembles = await client.listEnsembles().catch(() => []);
+    const summary = ensembles.find((e) => e.name === ensemble);
+    if (!summary)
+        throw new EnsembleNotFoundError(ensemble);
+    // Fan-out the rest in parallel. Each soft-fails to a sane default — the
+    // PR-1 snapshot must NEVER 500 just because one downstream query glitched.
+    // Issue #399 DB1a adds `meta` (4 maestro queries) to the ensemble-level
+    // fan-out; per-player wire-meta is fanned out below once `players`
+    // resolves so we know which session ids to query.
+    const fanned = await fanOut({
+        players: () => client.getPlayers(ensemble),
+        chat: () => client.getEnsembleChat(ensemble, 0, exports.SNAPSHOT_CHAT_LIMIT),
+        schedules: () => client.getSchedules(ensemble),
+        paused: () => client.isMaestroPaused(ensemble),
+        held: () => client.isAnySessionHeld(ensemble),
+        hosts: () => client.listHosts(),
+        meta: () => client.getEnsembleMeta(ensemble),
+    });
+    // Issue #399 W2 — fan-out 3 session queries per player in parallel.
+    // For a 12-player ensemble that's 36 queries; running them concurrently
+    // keeps total snapshot latency bounded by the slowest single session
+    // query, not the sum. `getPlayerWireMeta` returns `null` when the
+    // session workflow can't be reached — `toPlayerSummaryV1` gracefully
+    // omits the wire-meta fields in that case.
+    const playerInfos = fanned.players ?? [];
+    const wireMetas = await Promise.all(playerInfos.map((p) => client.getPlayerWireMeta(ensemble, p.playerId).catch(() => null)));
+    const players = playerInfos.map((p, i) => toPlayerSummaryV1(p, wireMetas[i]));
+    const chat = fanned.chat ?? { messages: [], total: 0, hasMore: false, hasConductor: false };
+    const schedules = fanned.schedules ?? [];
+    const paused = fanned.paused === true;
+    const held = fanned.held === true;
+    const hostProfiles = {};
+    for (const h of fanned.hosts ?? []) {
+        if (h.profile)
+            hostProfiles[h.hostname] = h.profile;
+    }
+    // Issue #399 W1 — sentinel defaults when the maestro fan-out soft-failed
+    // entirely. `getEnsembleMeta` already soft-fails individual queries to
+    // their sentinels; this branch covers the outer `fanOut` swallow when
+    // the whole call rejected.
+    const meta = fanned.meta ?? {
+        description: '',
+        startedAt: '',
+        currentBpm: 0,
+        tempoSeries: [],
+    };
+    const capturedAt = (opts.now?.() ?? new Date()).toISOString();
+    return {
+        v: 1,
+        ensemble,
+        capturedAt,
+        lastEventId: event_types_1.PR1_SENTINEL_EVENT_ID,
+        state: summary.state ?? 'online',
+        hasConductor: summary.hasConductor,
+        flags: { paused, held },
+        players,
+        schedules,
+        chat: {
+            messages: chat.messages,
+            total: chat.total,
+            hasMore: chat.hasMore,
+        },
+        hostProfiles,
+        description: meta.description,
+        startedAt: meta.startedAt,
+        currentBpm: meta.currentBpm,
+        tempoSeries: meta.tempoSeries,
+    };
+}

package/dist/http/sse-handler.d.ts

@@ -0,0 +1,87 @@
+/**
+ * SSE handler — wires `EnsembleEventBus` to the HTTP socket.
+ *
+ * **Responsibilities**:
+ * - Frame `BusEvent` into SSE `id:` / `event:` / `data:` lines (§5).
+ * - Decide the §7.2 connection-flow branch:
+ *   - no `Last-Event-ID` → emit `snapshot` (per-ensemble only), then live tail
+ *   - epoch mismatch → emit `gap` with `reason: 'epoch-mismatch'`, live tail
+ *   - epoch match, `seq < ringStart` → emit `gap` with `reason: 'overflow'`, live tail
+ *   - epoch match, `seq >= ringStart` → replay `[seq+1 … newest]`, live tail
+ * - Per-connection 1 MiB write-buffer cap (§7.3) with destroy-on-overflow.
+ * - Process-wide connection cap (`AGENT_TEMPO_SSE_MAX_CONNECTIONS`,
+ *   default 100); over-cap → `503 Service Unavailable`, `Retry-After: 5`.
+ * - Cancellation: socket close drops the subscription within one
+ *   event-loop tick.
+ */
+import type { IncomingMessage, ServerResponse } from 'http';
+import type { TempoClient } from '../client/interface';
+import { EnsembleEventBus, type BusEvent, type EventBus, type Subscription, type TopicCategory } from './event-bus';
+/** Default per-process SSE connection cap. */
+export declare const DEFAULT_MAX_CONNECTIONS = 100;
+/** Per-connection write-buffer ceiling (§7.3). */
+export declare const PER_CONNECTION_BUFFER_LIMIT: number;
+/** Counts open SSE connections. Exported for `/v1/health.subscriberCount`. */
+export declare class ConnectionCap {
+    readonly limit: number;
+    private current;
+    constructor(limit?: number);
+    size(): number;
+    /**
+     * Try to take a slot. Returns `true` when the connection is
+     * accepted; `false` when over the cap.
+     */
+    acquire(): boolean;
+    release(): void;
+}
+/**
+ * SSE frame format (§5). Returns the byte buffer that goes on the wire.
+ *
+ * Multi-line payloads are split on `\n` so each becomes its own
+ * `data:` line per the WHATWG spec — but in practice the daemon
+ * always emits single-line JSON, so this branch is defensive.
+ */
+export declare function frameSseEvent(event: BusEvent): Buffer;
+/**
+ * Same on-the-wire shape as {@link frameSseEvent} but takes the wire
+ * fields directly — for callers (e.g. fixture mode) that don't have a
+ * full `BusEvent` to project from.
+ */
+export declare function frameSseEventData(eventId: string, type: string, payload: unknown): Buffer;
+/**
+ * Frame a synthetic event-id-less prelude — `: <comment>\n\n`. Used for
+ * the initial keepalive nudge some intermediaries need before the
+ * first real event.
+ */
+export declare function frameSseComment(comment: string): Buffer;
+/**
+ * Write the §1 SSE response headers and the initial keepalive comment.
+ * Shared by {@link handleSseRequest} and the fixture-mode handler so
+ * the wire-level handshake stays in one place.
+ */
+export declare function openSseResponse(res: ServerResponse, comment?: string): void;
+/** Parse `?topics=phase,chat,...` query string into a Set, or `undefined`. */
+export declare function parseTopicQuery(raw: string | string[] | undefined): Set<TopicCategory> | undefined;
+export interface HandleSseOptions {
+    client: TempoClient;
+    bus: EventBus;
+    /**
+     * `true` for `/v1/events/:ensemble` — emits `snapshot` on fresh
+     * connect. `false` for `/v1/events` global stream which has no
+     * snapshot semantics (§6 table).
+     */
+    emitSnapshot: boolean;
+    /** Ensemble name when `emitSnapshot` is true; ignored otherwise. */
+    ensemble?: string;
+    /** Process-wide connection cap. */
+    cap: ConnectionCap;
+    /** Test seam for the per-connection write buffer ceiling. */
+    bufferLimit?: number;
+}
+/**
+ * Handle an SSE request. Long-lived — resolves only when the client
+ * disconnects, the bus closes, or the per-connection buffer overflows.
+ */
+export declare function handleSseRequest(req: IncomingMessage, res: ServerResponse, opts: HandleSseOptions): Promise<void>;
+/** Type guard re-export to satisfy TS without circular refs. */
+export type { EnsembleEventBus, Subscription };

package/dist/http/sse-handler.js

@@ -0,0 +1,294 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionCap = exports.PER_CONNECTION_BUFFER_LIMIT = exports.DEFAULT_MAX_CONNECTIONS = void 0;
+exports.frameSseEvent = frameSseEvent;
+exports.frameSseEventData = frameSseEventData;
+exports.frameSseComment = frameSseComment;
+exports.openSseResponse = openSseResponse;
+exports.parseTopicQuery = parseTopicQuery;
+exports.handleSseRequest = handleSseRequest;
+const snapshot_1 = require("./snapshot");
+const event_id_1 = require("./event-id");
+/** Default per-process SSE connection cap. */
+exports.DEFAULT_MAX_CONNECTIONS = 100;
+/** Per-connection write-buffer ceiling (§7.3). */
+exports.PER_CONNECTION_BUFFER_LIMIT = 1 * 1024 * 1024;
+const log = (...args) => console.error('[agent-tempo:sse]', ...args);
+/** Counts open SSE connections. Exported for `/v1/health.subscriberCount`. */
+class ConnectionCap {
+    limit;
+    current = 0;
+    constructor(limit = exports.DEFAULT_MAX_CONNECTIONS) {
+        this.limit = limit;
+    }
+    size() { return this.current; }
+    /**
+     * Try to take a slot. Returns `true` when the connection is
+     * accepted; `false` when over the cap.
+     */
+    acquire() {
+        if (this.current >= this.limit)
+            return false;
+        this.current++;
+        return true;
+    }
+    release() {
+        if (this.current > 0)
+            this.current--;
+    }
+}
+exports.ConnectionCap = ConnectionCap;
+/**
+ * SSE frame format (§5). Returns the byte buffer that goes on the wire.
+ *
+ * Multi-line payloads are split on `\n` so each becomes its own
+ * `data:` line per the WHATWG spec — but in practice the daemon
+ * always emits single-line JSON, so this branch is defensive.
+ */
+function frameSseEvent(event) {
+    return frameSseEventData(event.eventId, event.type, event.payload);
+}
+/**
+ * Same on-the-wire shape as {@link frameSseEvent} but takes the wire
+ * fields directly — for callers (e.g. fixture mode) that don't have a
+ * full `BusEvent` to project from.
+ */
+function frameSseEventData(eventId, type, payload) {
+    const lines = [
+        `id: ${eventId}`,
+        `event: ${type}`,
+    ];
+    const data = JSON.stringify({ v: 1, eventId, payload });
+    // Single-line JSON — but defend against line breaks in payloads.
+    for (const piece of data.split('\n'))
+        lines.push(`data: ${piece}`);
+    return Buffer.from(lines.join('\n') + '\n\n', 'utf8');
+}
+/**
+ * Frame a synthetic event-id-less prelude — `: <comment>\n\n`. Used for
+ * the initial keepalive nudge some intermediaries need before the
+ * first real event.
+ */
+function frameSseComment(comment) {
+    return Buffer.from(`: ${comment}\n\n`, 'utf8');
+}
+/**
+ * Write the §1 SSE response headers and the initial keepalive comment.
+ * Shared by {@link handleSseRequest} and the fixture-mode handler so
+ * the wire-level handshake stays in one place.
+ */
+function openSseResponse(res, comment = 'agent-tempo SSE') {
+    res.writeHead(200, {
+        'Content-Type': 'text/event-stream; charset=utf-8',
+        'Cache-Control': 'no-store',
+        Connection: 'keep-alive',
+        'X-Accel-Buffering': 'no', // disable buffering on nginx + friends
+    });
+    res.flushHeaders?.();
+    res.write(frameSseComment(comment));
+}
+/** Parse `?topics=phase,chat,...` query string into a Set, or `undefined`. */
+function parseTopicQuery(raw) {
+    if (!raw)
+        return undefined;
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    const known = new Set(['phase', 'chat', 'flags', 'schedules', 'heartbeat']);
+    const out = new Set();
+    for (const tok of value.split(',').map((s) => s.trim()).filter(Boolean)) {
+        if (known.has(tok))
+            out.add(tok);
+    }
+    return out.size > 0 ? out : undefined;
+}
+/** Pull a single string from a possibly-array header. */
+function headerString(v) {
+    if (Array.isArray(v))
+        return v[0];
+    return v;
+}
+/**
+ * Handle an SSE request. Long-lived — resolves only when the client
+ * disconnects, the bus closes, or the per-connection buffer overflows.
+ */
+async function handleSseRequest(req, res, opts) {
+    // Connection cap.
+    if (!opts.cap.acquire()) {
+        res.writeHead(503, {
+            'Content-Type': 'application/json; charset=utf-8',
+            'Retry-After': '5',
+        });
+        res.end(JSON.stringify({ error: 'connection-cap-exceeded' }));
+        return;
+    }
+    // Always release the cap on exit.
+    let capReleased = false;
+    const releaseCap = () => {
+        if (!capReleased) {
+            capReleased = true;
+            opts.cap.release();
+        }
+    };
+    // Open SSE response (headers per §1 + initial keepalive comment).
+    openSseResponse(res);
+    // Determine §7.2 entry branch.
+    const lastEventIdRaw = headerString(req.headers['last-event-id']);
+    const requested = (0, event_id_1.parseEventId)(lastEventIdRaw);
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const topics = parseTopicQuery(url.searchParams.get('topics') ?? undefined);
+    // Subscribe — afterSeq is determined by branch decisions below. The
+    // bus's subscribe call replays `seq > afterSeq` events from the ring.
+    let afterSeq;
+    let preludeEvents = [];
+    if (requested) {
+        if (requested.epoch !== opts.bus.bootEpoch) {
+            // Epoch mismatch → gap.
+            preludeEvents.push(synthEvent(opts.bus, 'gap', {
+                from: lastEventIdRaw ?? '',
+                to: makeIdToken(opts.bus, opts.bus.nextSeq()),
+                reason: 'epoch-mismatch',
+            }));
+            // Don't replay — client will re-fetch /v1/state and reconnect.
+            afterSeq = undefined;
+        }
+        else {
+            const ringStart = opts.bus.oldestSeq();
+            if (ringStart === null || requested.seq + 1 < ringStart) {
+                // Overflow → gap. `ringStart === null` happens when the bus
+                // has emitted nothing yet — semantically "I have no events
+                // to replay you" rather than the strict overflow case
+                // (client predates the ring's oldest entry). The wire spec
+                // §6 only defines two `gap` reasons (`epoch-mismatch` and
+                // `overflow`), so we use `overflow` for both flavors. The
+                // recovery path is identical: re-fetch `/v1/state` and
+                // reconnect with the snapshot's `lastEventId`. PR #324
+                // review nit — flagged for a possible §6 spec extension
+                // (`reason: 'empty-ring'`) if a future PR-3 consumer can use
+                // the distinction; for now collapsing keeps the wire stable.
+                preludeEvents.push(synthEvent(opts.bus, 'gap', {
+                    from: lastEventIdRaw ?? '',
+                    to: makeIdToken(opts.bus, opts.bus.nextSeq()),
+                    reason: 'overflow',
+                }));
+                afterSeq = undefined;
+            }
+            else {
+                // Replay range — bus.subscribe will pull from the ring.
+                afterSeq = requested.seq;
+            }
+        }
+    }
+    else if (opts.emitSnapshot) {
+        // No Last-Event-ID + per-ensemble stream → emit snapshot.
+        if (!opts.ensemble) {
+            res.end();
+            releaseCap();
+            throw new Error('handleSseRequest: ensemble required when emitSnapshot=true');
+        }
+        try {
+            const snap = await (0, snapshot_1.buildEnsembleSnapshot)(opts.client, opts.ensemble);
+            preludeEvents.push(synthEvent(opts.bus, 'snapshot', snap));
+        }
+        catch (err) {
+            if (err instanceof snapshot_1.EnsembleNotFoundError) {
+                // The route handler validates ensemble existence before calling
+                // this, but the ensemble could go away between resolution and
+                // snapshot fetch — return a 404-equivalent SSE close with a
+                // helpful body comment.
+                res.write(frameSseComment(`ensemble-not-found ${opts.ensemble}`));
+                res.end();
+                releaseCap();
+                return;
+            }
+            log('snapshot fetch failed:', err instanceof Error ? err.message : err);
+            // Non-fatal — let the bus do the live tail; consumer is no worse off.
+        }
+    }
+    const sub = opts.bus.subscribe({ ...(afterSeq !== undefined ? { afterSeq } : {}), ...(topics ? { topics } : {}) });
+    let closed = false;
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        try {
+            sub.close();
+        }
+        catch { /* ignore */ }
+        try {
+            res.end();
+        }
+        catch { /* ignore */ }
+        releaseCap();
+    };
+    // Bind socket lifecycle. `req.on('close')` covers TCP drop + abort.
+    req.on('close', close);
+    res.on('close', close);
+    // Stream loop.
+    try {
+        // Prelude (snapshot / gap) goes first.
+        for (const ev of preludeEvents) {
+            if (closed)
+                return;
+            if (!writeOrDrop(res, ev, opts.bufferLimit ?? exports.PER_CONNECTION_BUFFER_LIMIT, close))
+                return;
+        }
+        for await (const ev of sub) {
+            if (closed)
+                return;
+            if (!writeOrDrop(res, ev, opts.bufferLimit ?? exports.PER_CONNECTION_BUFFER_LIMIT, close))
+                return;
+        }
+    }
+    finally {
+        close();
+    }
+}
+/** Per-event write with §7.3 backpressure. Returns `false` when the connection was destroyed. */
+function writeOrDrop(res, event, bufferLimit, close) {
+    const payload = frameSseEvent(event);
+    // Track per-socket buffered bytes via Node's `writableLength`.
+    const socket = res.socket;
+    if (socket && socket.writableLength + payload.length > bufferLimit) {
+        log('connection write buffer exceeded — dropping subscriber');
+        try {
+            socket.destroy();
+        }
+        catch { /* ignore */ }
+        close();
+        return false;
+    }
+    res.write(payload);
+    return true;
+}
+/**
+ * Build a synthetic `BusEvent` not allocated by the bus's `emit`
+ * pipeline — used only for the connection prelude (snapshot / gap)
+ * which is per-connection rather than per-bus. Allocates a sentinel
+ * `eventId` based on the bus's current `nextSeq` minus one so the
+ * client's local `Last-Event-ID` tracking stays internally
+ * consistent without polluting the ring.
+ *
+ * NOTE: the eventId on a synthetic event is for client-side ordering
+ * only — the daemon will never reuse this id from its allocator.
+ * Per §7.2 the snapshot/gap re-bridge means the client always
+ * follows up with a fresh `/v1/state/:ensemble` fetch on `gap` and
+ * normalizes its Last-Event-ID against the snapshot's `lastEventId`.
+ */
+function synthEvent(bus, type, payload) {
+    // Pick an id strictly less than the bus's next allocation so it
+    // sorts before any real event. Synthetic prelude events are an
+    // implementation detail of the per-connection wire and are never
+    // expected to be addressed via Last-Event-ID resume.
+    const seq = Math.max(0, bus.nextSeq() - 1);
+    const tuple = { epoch: bus.bootEpoch, seq };
+    return {
+        eventId: `${tuple.epoch}:${tuple.seq}`,
+        tuple,
+        type,
+        payload,
+        emittedAt: Date.now(),
+        bufferable: false,
+    };
+}
+function makeIdToken(bus, seq) {
+    return `${bus.bootEpoch}:${seq}`;
+}

package/dist/http/writes.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Daemon HTTP write surface — PR-7a of #340.
+ *
+ * Adds five POST routes under `/v1/ensembles/:ensemble/{cue, pause,
+ * play, release, recruit}`. Each handler is a thin shim over the
+ * existing {@link TempoClient} method the daemon already has in scope
+ * (the same `ctx.client` used for snapshots).
+ *
+ * **Why now**: PR-1 → PR-6 of the dashboard shipped a read-only
+ * surface; PR-7b wires the dashboard's disabled CTAs to real submit
+ * handlers. Those handlers need an HTTP write API — until now the
+ * daemon was GET-only by design. See the full background in
+ * `docs/SSE-PROTOCOL.md` § 11b.
+ *
+ * **Auth posture** matches the read side:
+ * - Loopback bind + no `Origin` header → no auth (TUI/CLI parity; the
+ *   TUI already writes via Temporal directly anyway, so loopback-no-auth
+ *   is equivalent risk).
+ * - Non-loopback bind OR cross-origin browser → bearer required.
+ *
+ * **Body validation** is strict — every field shape is checked before
+ * the handler reaches the Temporal layer. Bad bodies fast-fail with
+ * 400; the underlying Temporal calls aren't asked to validate things
+ * the HTTP layer can catch.
+ *
+ * **Error mapping**: `Error('No session found …')` → 404 not-found;
+ * any other thrown `Error` → 500 (logged at the dispatcher).
+ */
+import type { IncomingMessage, ServerResponse } from 'http';
+import type { TempoClient } from '../client/interface';
+import { WRITE_BODY_MAX } from './body';
+export { WRITE_BODY_MAX };
+/**
+ * Names of the write actions exposed under `/v1/ensembles/:ensemble/<action>`.
+ *
+ * Two semantic groups, kept in this order so the table reads top-to-bottom
+ * by surface intent:
+ * - **Ensemble-scoped** (cue / pause / play / release / recruit) — the
+ *   original PR-7a #340 surface; bodies don't carry `playerId`.
+ * - **Per-player destructive** (restart / destroy / detach / recall) —
+ *   added so the dashboard's PlayerDetail action row can wire to live
+ *   mutations. Bodies are uniform `{ playerId, reason? }` (plus per-action
+ *   extras); the ensemble lives in the URL.
+ */
+export declare const WRITE_ACTIONS: readonly ["cue", "pause", "play", "release", "recruit", "restart", "destroy", "detach", "recall"];
+export type WriteAction = (typeof WRITE_ACTIONS)[number];
+/** Type guard — narrows an arbitrary string to a known `WriteAction`. */
+export declare function isWriteAction(s: string): s is WriteAction;
+/**
+ * Top-level dispatch — called from `server.ts` when the URL matches
+ * `/v1/ensembles/:ensemble/<action>` with a known `<action>`. The
+ * caller has already bearer/CORS-gated the request; this function
+ * trusts the gates and focuses on body parsing + per-action routing.
+ */
+export declare function handleWriteRoute(req: IncomingMessage, res: ServerResponse, client: TempoClient, ensemble: string, action: WriteAction): Promise<void>;