agent-tempo 1.0.1

package/dist/http/server.js

@@ -0,0 +1,459 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PORT = exports.DEFAULT_BIND_ADDR = void 0;
+exports.startHttpServer = startHttpServer;
+exports.handle = handle;
+/**
+ * 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.
+ */
+const http = __importStar(require("http"));
+const config_1 = require("../config");
+const auth_1 = require("./auth");
+const cors_1 = require("./cors");
+const dashboard_1 = require("./dashboard");
+const dashboard_pair_1 = require("./dashboard-pair");
+const fixtures_1 = require("./fixtures");
+const writes_1 = require("./writes");
+const catalog_1 = require("./catalog");
+const port_file_1 = require("./port-file");
+const responses_1 = require("./responses");
+const snapshot_1 = require("./snapshot");
+const sse_handler_1 = require("./sse-handler");
+const log = (...args) => console.error(`[agent-tempo:http ${new Date().toISOString()}]`, ...args);
+/** Default bind addr per SSE-PROTOCOL.md §1. */
+exports.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.
+ */
+exports.DEFAULT_PORT = (0, config_1.isDevMode)() ? config_1.DEV_DAEMON_PORT : config_1.PROD_DAEMON_PORT;
+/**
+ * Start the HTTP server. Resolves once the listener is bound and the
+ * port file has been written.
+ */
+async function startHttpServer(opts) {
+    const bindAddr = opts.bindAddr ?? process.env[config_1.ENV.HTTP_BIND] ?? exports.DEFAULT_BIND_ADDR;
+    const portEnv = process.env[config_1.ENV.DAEMON_PORT];
+    const port = opts.port ?? (portEnv != null && portEnv !== '' ? Number(portEnv) : exports.DEFAULT_PORT);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error(`Invalid HTTP port: ${port}`);
+    }
+    const allowedOrigins = opts.allowedOrigins ?? (0, cors_1.parseCorsOrigins)(process.env[config_1.ENV.CORS_ORIGINS]);
+    const corsConfig = { allowedOrigins };
+    // Bearer token resolution: if bind addr is non-loopback, force token
+    // generation now so the daemon doesn't crash mid-request when the first
+    // bearer-required call shows up.
+    const bindIsLoopback = (0, auth_1.isLoopbackBindAddr)(bindAddr);
+    const httpToken = opts.httpToken ?? (0, auth_1.loadOrGenerateHttpToken)({ bearerRequired: !bindIsLoopback });
+    if (!bindIsLoopback && !httpToken) {
+        throw new Error('Bearer token required for non-loopback bind but none configured. ' +
+            'Set httpToken in ~/.agent-tempo/config.json or unset AGENT_TEMPO_HTTP_BIND.');
+    }
+    const startedAt = opts.startedAtMs ?? Date.now();
+    // §7.3 process-wide cap. Defaults to 100 per spec; env var override.
+    const capLimitEnv = process.env[config_1.ENV.SSE_MAX_CONNECTIONS];
+    const capLimit = opts.maxSseConnections ??
+        (capLimitEnv != null && capLimitEnv !== '' ? Number(capLimitEnv) : sse_handler_1.DEFAULT_MAX_CONNECTIONS);
+    if (!Number.isInteger(capLimit) || capLimit < 1) {
+        throw new Error(`Invalid SSE max connections: ${capLimit}`);
+    }
+    const sseConnectionCap = new sse_handler_1.ConnectionCap(capLimit);
+    // Subscriber count = aggregate's live SSE subscribers. Falls back to
+    // 0 when no aggregate (PR-1 server, no SSE).
+    const subscriberCount = () => opts.aggregate ? opts.aggregate.totalSubscriberCount() : 0;
+    const server = http.createServer((req, res) => handle(req, res, {
+        client: opts.client,
+        namespace: opts.namespace,
+        taskQueue: opts.taskQueue,
+        version: opts.version,
+        bindAddr,
+        corsConfig,
+        httpToken,
+        startedAt,
+        subscriberCount,
+        aggregate: opts.aggregate ?? null,
+        sseConnectionCap,
+    }).catch((err) => {
+        log('unhandled handler error:', err instanceof Error ? err.message : err);
+        if (!res.headersSent) {
+            try {
+                (0, responses_1.errorResponse)(res, 500, { error: 'internal-error' });
+            }
+            catch { /* socket already closed */ }
+        }
+        else {
+            try {
+                res.end();
+            }
+            catch { /* ignore */ }
+        }
+    }));
+    // Defensive: per-connection timeout so a wedged client can't hold a
+    // socket indefinitely on the daemon. Snapshot endpoints respond fast;
+    // PR-2 will need a much longer / disabled timeout for SSE streams.
+    server.requestTimeout = 30_000;
+    server.headersTimeout = 35_000;
+    // TCP keepalive — matches §1 contract.
+    server.keepAliveTimeout = 60_000;
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, bindAddr, () => {
+            server.removeListener('error', reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    const boundPort = typeof address === 'object' && address ? address.port : port;
+    // Port file → atomic write so a racing reader never sees a half-written
+    // value. Skip write if the caller asked for ephemeral binding without a
+    // port-file override (tests).
+    const portFilePath = opts.portFilePath ?? port_file_1.DAEMON_PORT_PATH;
+    try {
+        await (0, port_file_1.writePortFileAtomic)(portFilePath, boundPort);
+        log(`listening on http://${bindAddr}:${boundPort} (port file: ${portFilePath})`);
+    }
+    catch (err) {
+        log('failed to write port file (non-fatal):', err instanceof Error ? err.message : err);
+    }
+    // Track open sockets so `close()` can force-close them after a graceful
+    // window — Node's `server.close()` only stops accepting new connections.
+    const sockets = new Set();
+    server.on('connection', (socket) => {
+        sockets.add(socket);
+        socket.on('close', () => sockets.delete(socket));
+    });
+    return {
+        port: boundPort,
+        bindAddr,
+        subscriberCount,
+        async close() {
+            // Stop accepting new connections immediately, then give live sockets
+            // a 5 s window to drain before destroying them.
+            const closing = new Promise((resolve) => {
+                server.close(() => resolve());
+            });
+            const drainDeadline = setTimeout(() => {
+                for (const s of sockets)
+                    s.destroy();
+            }, 5_000);
+            drainDeadline.unref();
+            try {
+                await closing;
+            }
+            finally {
+                clearTimeout(drainDeadline);
+            }
+            (0, port_file_1.removePortFile)(portFilePath);
+            log('server closed');
+        },
+    };
+}
+/**
+ * Top-level request dispatcher — exported for unit tests that want to
+ * exercise the handler without spinning up a real listener.
+ */
+async function handle(req, res, ctx) {
+    const method = (req.method ?? 'GET').toUpperCase();
+    const url = new URL(req.url ?? '/', `http://${ctx.bindAddr}`);
+    const pathname = url.pathname;
+    // CORS preflight short-circuit. Always answer OPTIONS — even in
+    // loopback mode — with `204 No Content` and the static headers, so
+    // browsers performing a preflight against a loopback dashboard get a
+    // clean answer.
+    if (method === 'OPTIONS') {
+        return handleOptions(req, res, ctx);
+    }
+    // Health is always reachable, never authenticated, never CORS-gated.
+    if (method === 'GET' && pathname === '/v1/health') {
+        return handleHealth(res, ctx);
+    }
+    // Pre-auth carve-out for the cross-device pairing-token consume endpoint
+    // (see docs/design/340-web-dashboard.md §4.1). The token IS the auth —
+    // single-use, 5-min TTL, opaque base64url. Real pair flow lands here
+    // in PR-8 of #340.
+    //
+    // Regex is intentionally tight — `[^/]+` rejects extra path segments and
+    // (after URL-parser normalisation) traversal attempts; both fall through
+    // to the post-auth `/dashboard/api/*` 404.
+    const pairConsumeMatch = pathname.match(/^\/dashboard\/api\/pair\/([^/]+)$/);
+    if (method === 'GET' && pairConsumeMatch) {
+        return (0, dashboard_pair_1.handlePairConsume)(req, res, pairConsumeMatch[1]);
+    }
+    // Authentication gate.
+    const originHeader = headerString(req.headers.origin);
+    const reqBearer = (0, auth_1.bearerRequired)(ctx.bindAddr, originHeader);
+    if (reqBearer) {
+        const provided = (0, auth_1.extractBearerToken)(headerString(req.headers.authorization));
+        if (!provided || !ctx.httpToken || !(0, auth_1.tokensMatch)(provided, ctx.httpToken)) {
+            writeCorsHeaders(res, originHeader, ctx, reqBearer);
+            return (0, responses_1.errorResponse)(res, 401, { error: 'unauthorized' });
+        }
+    }
+    // CORS allowlist check (only enforced in bearer mode).
+    const cors = (0, cors_1.evaluateOrigin)(originHeader, ctx.corsConfig, reqBearer);
+    if (!cors.allowed) {
+        return (0, responses_1.errorResponse)(res, 403, { error: 'origin-not-allowed' });
+    }
+    if (cors.echo) {
+        res.setHeader('Access-Control-Allow-Origin', cors.echo);
+        res.setHeader('Vary', 'Origin');
+    }
+    // Write surface (PR-7a of #340) — POST `/v1/ensembles/:ensemble/<action>`
+    // Match BEFORE the GET-only method gate; everything else (POST to a
+    // read endpoint, GET to a write endpoint) flows into the 405 fallback
+    // below with the right `Allow` header.
+    const writeMatch = pathname.match(/^\/v1\/ensembles\/([^/]+)\/([^/]+)$/);
+    if (writeMatch) {
+        const ensemble = decodeURIComponent(writeMatch[1]);
+        const action = writeMatch[2];
+        if ((0, writes_1.isWriteAction)(action)) {
+            if (method !== 'POST') {
+                return (0, responses_1.errorResponse)(res, 405, { error: 'method-not-allowed' }, { Allow: 'POST, OPTIONS' });
+            }
+            return (0, writes_1.handleWriteRoute)(req, res, ctx.client, ensemble, action);
+        }
+        // Unknown action under /v1/ensembles/:e/<x> → 404 (don't 405; the
+        // path simply isn't a known endpoint).
+        return (0, responses_1.errorResponse)(res, 404, { error: 'not-found' });
+    }
+    // Create-ensemble route (issue #400) — POST `/v1/ensembles`. Sits
+    // alongside the writeMatch above so it's reached before the GET-only
+    // gate; the GET on the same path (list ensembles) is handled below.
+    if (pathname === '/v1/ensembles' && method === 'POST') {
+        return (0, catalog_1.handleCreateEnsemble)(req, res, ctx.client);
+    }
+    // POST `/dashboard/api/pair` — mint a pairing for cross-device QR (PR-8
+    // of #340). Sits AFTER the bearer-auth gate so the operator on the host
+    // proves authority before issuing a token; the token's GET-side consume
+    // is the carve-out above the auth gate.
+    if (method === 'POST' && pathname === '/dashboard/api/pair') {
+        const provided = (0, auth_1.extractBearerToken)(headerString(req.headers.authorization));
+        return (0, dashboard_pair_1.handlePairCreate)(req, res, provided);
+    }
+    // Method gate — read endpoints are GET-only. Both POST paths above
+    // (PR-7a writes, PR-8 pair-mint) handle their own method matching;
+    // everything else falls through here.
+    if (method !== 'GET') {
+        return (0, responses_1.errorResponse)(res, 405, { error: 'method-not-allowed' }, { Allow: 'GET, OPTIONS' });
+    }
+    // Static dashboard SPA (PR-1 of #340). Sits behind the bearer-auth gate
+    // so non-loopback binds (LAN, Tailscale) require the same bearer the
+    // `/v1/*` API uses. The pre-auth pair-token carve-out above is the
+    // single exception that bootstraps cross-device pairing.
+    if (pathname === '/dashboard' || pathname.startsWith('/dashboard/')) {
+        return (0, dashboard_1.handleDashboardStatic)(req, res, pathname);
+    }
+    if (pathname === '/v1/ensembles') {
+        return handleListEnsembles(res, ctx);
+    }
+    if (pathname === '/v1/hosts') {
+        return handleHosts(res, ctx);
+    }
+    // Catalog reads (issue #400) — `listAgentTypes` / `listLineups`
+    // touch local fs only, no Temporal calls; cheap to serve per-request.
+    if (pathname === '/v1/agent-types') {
+        return (0, catalog_1.handleListAgentTypes)(res);
+    }
+    if (pathname === '/v1/lineups') {
+        return (0, catalog_1.handleListLineups)(res);
+    }
+    // /v1/state/:ensemble — single capture group.
+    const stateMatch = pathname.match(/^\/v1\/state\/([^/]+)$/);
+    if (stateMatch) {
+        const ensemble = decodeURIComponent(stateMatch[1]);
+        // Fixture mode (PR-3 of #340) — `?fixture=<name>` short-circuits the
+        // live snapshot with canned data. Sits behind the bearer-auth gate.
+        const fixtureName = url.searchParams.get('fixture');
+        if (fixtureName) {
+            return (0, fixtures_1.handleFixtureSnapshot)(res, fixtureName);
+        }
+        return handleState(res, ctx, ensemble);
+    }
+    // /v1/events* (SSE). Dispatch to the SSE handler when an aggregate
+    // is wired; otherwise stay on the PR-1 503 placeholder so the route
+    // signals "feature exists, not yet wired" rather than "ensemble
+    // doesn't exist".
+    if (pathname === '/v1/events') {
+        if (!ctx.aggregate) {
+            return (0, responses_1.errorResponse)(res, 503, { error: 'streaming-not-implemented' }, { 'Retry-After': '60' });
+        }
+        return (0, sse_handler_1.handleSseRequest)(req, res, {
+            client: ctx.client,
+            bus: ctx.aggregate.globalBus(),
+            emitSnapshot: false,
+            cap: ctx.sseConnectionCap,
+        });
+    }
+    const evtMatch = pathname.match(/^\/v1\/events\/([^/]+)$/);
+    if (evtMatch) {
+        const ensemble = decodeURIComponent(evtMatch[1]);
+        // Fixture mode (PR-3 of #340) — `?fixture=<name>` short-circuits both
+        // the existence check and the aggregate poll loop with a canned event
+        // sequence. Sits behind the bearer-auth gate.
+        const fixtureName = url.searchParams.get('fixture');
+        if (fixtureName) {
+            return (0, fixtures_1.handleFixtureSse)(req, res, fixtureName);
+        }
+        if (!ctx.aggregate) {
+            return (0, responses_1.errorResponse)(res, 503, { error: 'streaming-not-implemented' }, { 'Retry-After': '60' });
+        }
+        // Validate existence before opening the SSE stream — clean 404 when
+        // the ensemble was never live, instead of an empty stream.
+        const list = await ctx.client.listEnsembles().catch(() => []);
+        if (!list.find((e) => e.name === ensemble)) {
+            return (0, responses_1.errorResponse)(res, 404, { error: 'ensemble-not-found', ensemble });
+        }
+        const bus = ctx.aggregate.getOrCreateEnsembleBus(ensemble);
+        return (0, sse_handler_1.handleSseRequest)(req, res, {
+            client: ctx.client,
+            bus,
+            emitSnapshot: true,
+            ensemble,
+            cap: ctx.sseConnectionCap,
+        });
+    }
+    return (0, responses_1.errorResponse)(res, 404, { error: 'not-found' });
+}
+/** Pull a single string from a possibly-array header. */
+function headerString(v) {
+    if (Array.isArray(v))
+        return v[0];
+    return v;
+}
+/**
+ * Apply CORS response headers when bearer mode is active. Used by
+ * paths that bypass the main route flow (e.g. 401 short-circuit) so
+ * the browser still sees a CORS-compliant response.
+ */
+function writeCorsHeaders(res, originHeader, ctx, bearerActive) {
+    if (!bearerActive)
+        return;
+    const cors = (0, cors_1.evaluateOrigin)(originHeader, ctx.corsConfig, bearerActive);
+    if (cors.echo) {
+        res.setHeader('Access-Control-Allow-Origin', cors.echo);
+        res.setHeader('Vary', 'Origin');
+    }
+}
+function handleOptions(req, res, ctx) {
+    const originHeader = headerString(req.headers.origin);
+    const bearerActive = (0, auth_1.bearerRequired)(ctx.bindAddr, originHeader);
+    const cors = (0, cors_1.evaluateOrigin)(originHeader, ctx.corsConfig, bearerActive);
+    // Origin rejected → 403, no ACAO header (browser will block fetch).
+    if (!cors.allowed) {
+        res.writeHead(403, { 'Content-Type': 'text/plain; charset=utf-8' });
+        res.end('CORS: origin not allowed');
+        return;
+    }
+    const headers = { ...(0, cors_1.corsResponseHeaders)() };
+    if (cors.echo)
+        headers['Access-Control-Allow-Origin'] = cors.echo;
+    res.writeHead(204, headers);
+    res.end();
+}
+function handleHealth(res, ctx) {
+    // #336 — sample process memory at request time. `process.memoryUsage()`
+    // is synchronous + cheap (~microseconds), safe inside a request handler.
+    const mem = process.memoryUsage();
+    const body = {
+        ok: true,
+        namespace: ctx.namespace,
+        taskQueue: ctx.taskQueue,
+        version: ctx.version,
+        uptimeMs: Math.max(0, Date.now() - ctx.startedAt),
+        ensembleCount: 0, // populated below
+        subscriberCount: ctx.subscriberCount(),
+        memory: {
+            rss: mem.rss,
+            heapTotal: mem.heapTotal,
+            heapUsed: mem.heapUsed,
+            external: mem.external,
+            arrayBuffers: mem.arrayBuffers,
+        },
+    };
+    // Best-effort ensemble count — soft-fail to 0 rather than 500ing on a
+    // healthcheck. `/v1/health` MUST stay reachable even when Temporal is
+    // wedged; supervisord depends on it.
+    ctx.client
+        .listEnsembles()
+        .then((list) => {
+        body.ensembleCount = list.length;
+        (0, responses_1.jsonResponse)(res, 200, body);
+    })
+        .catch(() => {
+        (0, responses_1.jsonResponse)(res, 200, body);
+    });
+}
+async function handleListEnsembles(res, ctx) {
+    const list = await ctx.client.listEnsembles();
+    (0, responses_1.jsonResponse)(res, 200, list);
+}
+async function handleHosts(res, ctx) {
+    // The 3 s cache lives inside `listHosts`; we don't add another layer.
+    const hosts = await ctx.client.listHosts();
+    (0, responses_1.jsonResponse)(res, 200, hosts);
+}
+async function handleState(res, ctx, ensemble) {
+    try {
+        const snapshot = await (0, snapshot_1.buildEnsembleSnapshot)(ctx.client, ensemble);
+        (0, responses_1.jsonResponse)(res, 200, snapshot);
+    }
+    catch (err) {
+        if (err instanceof snapshot_1.EnsembleNotFoundError) {
+            return (0, responses_1.errorResponse)(res, 404, { error: 'ensemble-not-found', ensemble });
+        }
+        throw err;
+    }
+}

package/dist/http/snapshot.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Snapshot builder for `/v1/state/:ensemble`.
+ *
+ * **PR-1 strategy**: project the existing TempoClient queries through HTTP
+ * without an aggregate. PR-2 will replace this with a 750 ms aggregate
+ * poll loop that diffs and emits events; the snapshot endpoint stays
+ * stable across that swap because the projection lives in the client
+ * surface, not the SSE infrastructure.
+ *
+ * **Ensemble existence gate**: `listEnsembles()` is the one query that
+ * cleanly distinguishes "ensemble doesn't exist" from "ensemble exists
+ * but is empty". Calling it first lets us return `404 ensemble-not-found`
+ * (SSE-PROTOCOL.md §9) before we fan out the rest of the queries.
+ *
+ * **Atomicity** (§4.3 contract): in PR-1 the snapshot reflects whatever
+ * Temporal queries returned at the time of fan-out. The `lastEventId` is
+ * the sentinel `"0:0"` — PR-2 subscribers passing it back will hit
+ * `epoch-mismatch` and re-fetch, which is the right behavior since the
+ * PR-1 snapshot has no provable atomicity against an event log that
+ * doesn't yet exist.
+ */
+import type { TempoClient } from '../client/interface';
+import type { MaestroPlayerInfo } from '../types';
+import { type EnsembleStateV1, type PlayerSummaryV1 } from './event-types';
+/**
+ * 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.
+ */
+export declare const SNAPSHOT_CHAT_LIMIT = 50;
+/** Thrown when the ensemble doesn't exist; route handler maps to 404. */
+export declare class EnsembleNotFoundError extends Error {
+    readonly ensemble: string;
+    constructor(ensemble: string);
+}
+/**
+ * Per-player wire-extension fields layered on top of `toPlayerSummaryV1`.
+ * Issue #399 W2 — `getPlayerWireMeta` fans out 3 session queries; the
+ * resulting object is merged into the projection here. `null` (session
+ * unreachable) drops the whole wire-meta block rather than emitting
+ * half-populated fields.
+ */
+export interface PlayerWireMeta {
+    runId?: string;
+    messaging?: {
+        received: number;
+        sent: number;
+        outbox: string;
+    };
+    lease?: {
+        expiresAt: number | null;
+        leaseMs: number | null;
+    };
+}
+/**
+ * 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.
+ */
+export declare function toPlayerSummaryV1(p: MaestroPlayerInfo, wireMeta?: PlayerWireMeta | null): PlayerSummaryV1;
+/**
+ * Build the `/v1/state/:ensemble` payload. Throws
+ * {@link EnsembleNotFoundError} when the requested ensemble has no live
+ * workflows; route handler turns that into a 404.
+ */
+export declare function buildEnsembleSnapshot(client: TempoClient, ensemble: string, opts?: {
+    now?: () => Date;
+}): Promise<EnsembleStateV1>;