toolroll 0.9.46 → 0.9.48

package/dist/flow-live.js

@@ -2,9 +2,9 @@
  * The live canvas (v88): a flow open in several browsers stays the same in
  * all of them, and each shows who else has it open.
  *
- * - A change nudge. While anyone has a flow open, one cheap query a second
- *   reads the flow's fingerprint (its revision, cards, moves, comments,
- *   watchers, step runs and triggers); when it changes, every open page
+ * - A change nudge. When the live bus says the workspace was written
+ *   (live-bus.ts), one small read checks the flow's fingerprint (its revision, cards, moves, comments,
+ *   watchers, step runs, linked task progress and triggers); when it changed, every open page
  *   hears "change" and reads the flow again the usual way. The nudge
  *   carries no card data: what a page shows is always what its own read
  *   returned, under its own checks.
@@ -13,37 +13,91 @@
  *   name. It lives in memory only and goes when the page closes or hides.
  *
  * Streams are refresh hints only: nothing here writes, and a page that
- * can't keep one open falls back to reading every few seconds.
+ * can't keep one open falls back to reading every few seconds. With nothing
+ * written, an open flow costs no reads; a 30-second check heals a miss.
  */
 import { createHash } from "node:crypto";
-const TICK_MS = 1_000;
-const CHECK_EVERY = 15;
-const HEARTBEAT_EVERY = 15;
-const PRESENCE_SETTLE_MS = 150;
-/** What changes when anything on the canvas changes: one row, one read, kept short and opaque. */
-export function flowFingerprint(store, flow) {
-    const row = store.handle.prepare(`SELECT f.state || '|' || f.revision || '|' || f.updated_at || '|' || coalesce(f.owner, '') AS head,
+import { createLiveRooms } from "./live-bus.js";
+// Statements belong to their database, without keeping closed Stores alive.
+const fingerprintStatements = new WeakMap();
+function fingerprintStatement(store) {
+    const cached = fingerprintStatements.get(store.handle);
+    if (cached !== undefined)
+        return cached;
+    // Match Store.taskFamilyOf/taskFamilyProjection: built-in tasks, same-repo
+    // edges, a revision brief bound to the parent's run, and at most 63 edges.
+    // Walk up only from active cards, then down from their proven roots. A
+    // missing/invalid/cyclic/over-depth ancestry leaves the linked task alone.
+    const statement = store.handle.prepare(`WITH RECURSIVE linked AS MATERIALIZED (
+      SELECT DISTINCT tr.id AS ref_id, tr.external_id AS id, tr.repo, tr.revision_of, tr.revision_brief_artifact
+      FROM flow_card c JOIN task_ref tr ON tr.external_id = c.task AND tr.backend = 'built-in'
+      JOIN task t ON t.id = tr.external_id
+      WHERE c.flow = $flow AND c.state = 'active' AND tr.repo IS NOT NULL
+    ), ancestors(linked_ref, ref_id, id, repo, revision_of, revision_brief_artifact, depth) AS (
+      SELECT ref_id, ref_id, id, repo, revision_of, revision_brief_artifact, 0 FROM linked
+      UNION ALL
+      SELECT child.linked_ref, parent.id, parent.external_id, parent.repo, parent.revision_of, parent.revision_brief_artifact, child.depth + 1
+      FROM ancestors child
+      JOIN task_ref parent ON parent.backend = 'built-in' AND parent.external_id = child.revision_of AND parent.repo IS child.repo
+      JOIN task t ON t.id = parent.external_id
+      JOIN artifact brief ON brief.id = child.revision_brief_artifact AND brief.kind = 'revision-brief'
+      JOIN run source_run ON source_run.id = brief.run AND source_run.task_ref = parent.id
+      WHERE child.depth < 63
+    ), roots AS MATERIALIZED (
+      SELECT DISTINCT ref_id, id, repo FROM ancestors WHERE revision_of IS NULL
+    ), descendants(ref_id, id, repo, depth) AS (
+      SELECT ref_id, id, repo, 0 FROM roots
+      UNION ALL
+      SELECT child.id, child.external_id, child.repo, parent.depth + 1 FROM descendants parent
+      JOIN task_ref child ON child.backend = 'built-in' AND child.revision_of = parent.id AND child.repo IS parent.repo
+      JOIN task t ON t.id = child.external_id
+      JOIN artifact brief ON brief.id = child.revision_brief_artifact AND brief.kind = 'revision-brief'
+      JOIN run source_run ON source_run.id = brief.run AND source_run.task_ref = parent.ref_id
+      WHERE parent.depth < 63
+    ), members AS (
+      SELECT ref_id FROM descendants
+      UNION
+      SELECT ref_id FROM linked WHERE NOT EXISTS (
+        SELECT 1 FROM ancestors WHERE linked_ref = linked.ref_id AND revision_of IS NULL
+      )
+    ) SELECT f.state || '|' || f.revision || '|' || f.updated_at || '|' || coalesce(f.owner, '') AS head,
     (SELECT count(*) || ':' || coalesce(max(updated_at), '') FROM flow_card WHERE flow = f.id) AS cards,
     (SELECT coalesce(max(e.id), 0) FROM flow_event e JOIN flow_card c ON c.id = e.card WHERE c.flow = f.id) AS moves,
     (SELECT coalesce(max(m.id), 0) FROM flow_comment m JOIN flow_card c ON c.id = m.card WHERE c.flow = f.id) AS comments,
     (SELECT count(*) || ':' || coalesce(max(w.added_at), '') FROM flow_card_watcher w JOIN flow_card c ON c.id = w.card WHERE c.flow = f.id) AS watchers,
     (SELECT count(*) || ':' || coalesce(sum(r.attempts), 0) || ':' || coalesce(max(coalesce(r.finished_at, r.started_at)), '') || ':' || coalesce(sum(r.state = 'running'), 0)
        FROM flow_step_run r JOIN flow_card c ON c.id = r.card WHERE c.flow = f.id) AS runs,
-    (SELECT count(*) || ':' || coalesce(max(updated_at), '') || ':' || coalesce(max(last_at), '') || ':' || coalesce(sum(failures), 0) FROM flow_trigger WHERE flow = f.id) AS triggers
-    FROM flow f WHERE f.id = ?`).get(flow);
+    (SELECT count(*) || ':' || coalesce(max(updated_at), '') || ':' || coalesce(max(last_at), '') || ':' || coalesce(sum(failures), 0) FROM flow_trigger WHERE flow = f.id) AS triggers,
+    (SELECT json_group_array(json_array(tr.id, t.id, t.state, t.updated_at, tr.plan,
+       s.digest, s.approved_digest, s.approved_at,
+       (SELECT max(p.id) FROM run_checkpoint p WHERE p.task_ref = tr.id),
+       (SELECT q.lease_id FROM claim q WHERE q.task_ref = tr.id AND q.released_at IS NULL AND q.expires_at > $now ORDER BY q.lease_generation DESC LIMIT 1),
+       (SELECT json_group_array(json_array(r.id, r.outcome, r.finished_at, r.reason,
+          (SELECT json_array(k.status, k.exit_code, k.updated_at) FROM run_check k WHERE k.run = r.id)) ORDER BY r.id) FROM run r WHERE r.task_ref = tr.id),
+       (SELECT json_group_array(json_array(d.id, d.state, d.question, d.answered_at) ORDER BY d.id) FROM decision d JOIN run r ON r.id = d.run WHERE r.task_ref = tr.id),
+       (SELECT json_group_array(json_array(h.id, h.reason) ORDER BY h.id) FROM hold h WHERE h.task_ref = tr.id AND (h.until IS NULL OR h.until > $now)),
+       (SELECT max(a.id) FROM action_ledger a WHERE a.task_id = t.id)) ORDER BY tr.id)
+     FROM task_ref tr JOIN task t ON t.id = tr.external_id
+     LEFT JOIN task_scope s ON s.task_id = t.id
+     WHERE tr.id IN (SELECT ref_id FROM members)) AS tasks
+    FROM flow f WHERE f.id = $flow`);
+    fingerprintStatements.set(store.handle, statement);
+    return statement;
+}
+/** What changes when anything on the canvas changes: metadata only, kept short and opaque. */
+export function flowFingerprint(store, flow, now = new Date()) {
+    // A revision can progress while its card still links to the original task,
+    // including a build in another project. The page read admits the viewer;
+    // this stream only carries a hash. No evidence files or logs are read.
+    const row = fingerprintStatement(store).get({ $flow: flow, $now: now.toISOString() });
     return row === undefined ? null : createHash("sha256").update(Object.values(row).map(String).join("|")).digest("hex").slice(0, 16);
 }
-export function createFlowRooms(fingerprint, tickMs = TICK_MS) {
-    const rooms = new Map();
-    const write = (viewer, event, data) => {
-        if (viewer.response.writableEnded || viewer.response.destroyed)
-            return;
-        viewer.response.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
-    };
+/** Rooms keyed by flow. With a bus, a write reaches every open page at once; without one, only the safety net. */
+export function createFlowRooms(fingerprint, options = {}) {
     /** Everyone on the flow but you, one line per person however many pages they have open. */
-    const others = (room, me) => {
+    const others = (viewers, me) => {
         const people = new Map();
-        for (const one of room.viewers) {
+        for (const one of viewers) {
             if (one.name === me)
                 continue;
             const seen = people.get(one.name) ?? { name: one.name, cards: [], editing: false };
@@ -54,97 +108,5 @@ export function createFlowRooms(fingerprint, tickMs = TICK_MS) {
         }
         return [...people.values()].sort((a, b) => a.name.localeCompare(b.name));
     };
-    const announce = (room) => {
-        // A page that moves from one card to the next leaves and joins at once: say it once, after it settles.
-        if (room.settling !== null)
-            clearTimeout(room.settling);
-        room.settling = setTimeout(() => {
-            room.settling = null;
-            for (const viewer of room.viewers)
-                write(viewer, "here", { people: others(room, viewer.name) });
-        }, PRESENCE_SETTLE_MS);
-        room.settling.unref();
-    };
-    const leave = (flow, viewer) => {
-        const room = rooms.get(flow);
-        if (room === undefined || !room.viewers.delete(viewer))
-            return;
-        if (!viewer.response.writableEnded)
-            viewer.response.end();
-        if (room.viewers.size > 0) {
-            announce(room);
-            return;
-        }
-        if (room.timer !== null)
-            clearInterval(room.timer);
-        if (room.settling !== null)
-            clearTimeout(room.settling);
-        rooms.delete(flow);
-    };
-    const tick = (flow, room) => {
-        room.ticks += 1;
-        if (room.ticks % CHECK_EVERY === 0) {
-            // A signed-out or narrowed account stops hearing about the flow.
-            for (const viewer of [...room.viewers])
-                if (!viewer.valid()) {
-                    write(viewer, "gone", {});
-                    leave(flow, viewer);
-                }
-            if (!rooms.has(flow))
-                return;
-        }
-        let now;
-        try {
-            now = fingerprint(flow);
-        }
-        catch {
-            return; /* a busy database: the next tick reads again */
-        }
-        if (now === null) {
-            for (const viewer of [...room.viewers]) {
-                write(viewer, "gone", {});
-                leave(flow, viewer);
-            }
-            return;
-        }
-        if (now !== room.last) {
-            room.last = now;
-            for (const viewer of room.viewers)
-                write(viewer, "change", { at: now });
-        }
-        else if (room.ticks % HEARTBEAT_EVERY === 0) {
-            for (const viewer of room.viewers)
-                if (!viewer.response.writableEnded)
-                    viewer.response.write(": keep-alive\n\n");
-        }
-    };
-    return {
-        join(flow, viewer) {
-            let room = rooms.get(flow);
-            if (room === undefined) {
-                let last = null;
-                try {
-                    last = fingerprint(flow);
-                }
-                catch { /* the first tick reads it */ }
-                room = { viewers: new Set(), last, timer: null, ticks: 0, settling: null };
-                const created = room;
-                room.timer = setInterval(() => tick(flow, created), tickMs);
-                room.timer.unref();
-                rooms.set(flow, room);
-            }
-            room.viewers.add(viewer);
-            write(viewer, "change", { at: room.last });
-            write(viewer, "here", { people: others(room, viewer.name) });
-            announce(room);
-            const gone = () => leave(flow, viewer);
-            viewer.response.once("close", gone);
-        },
-        close() {
-            for (const [flow, room] of [...rooms])
-                for (const viewer of [...room.viewers])
-                    leave(flow, viewer);
-        },
-        size: () => [...rooms.values()].reduce((sum, room) => sum + room.viewers.size, 0),
-    };
+    return createLiveRooms(fingerprint, others, options);
 }

package/dist/flows-ui.js

@@ -14,6 +14,8 @@ import { mailboxReady } from "./mailbox.js";
 import { labelOf, nameOf } from "./teammate-admin.js";
 import { callWords, receiptWords } from "./teammate-tools.js";
 import { undoFor } from "./teammate-week.js";
+import { flowCardTaskLine } from "./flow-card-task.js";
+import { readFlowSecrets } from "./flow-secrets.js";
 const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 const projectName = (repo) => repo.split(/[\\/]/).filter(Boolean).pop() ?? repo;
 export const FLOWS_CSS = `.flows{max-width:880px;min-width:0}.flows .card{padding:16px 18px;margin:12px 0}.flows .flow-row{display:flex;justify-content:space-between;align-items:baseline;gap:12px;flex-wrap:wrap}.flows .flow-row h2{font-size:1.05rem;margin:0}.flows .flow-counts{font-size:.85rem;color:var(--so-muted)}.flows form{display:grid;gap:10px;margin:0}.flows label{display:grid;gap:6px}.flows input,.flows select{box-sizing:border-box;width:100%;max-width:100%}.flows button{justify-self:start;min-height:44px}.flows .flow-fallback ol{padding-left:20px}.flows summary{cursor:pointer;min-height:44px;display:flex;align-items:center;font-weight:600}.flows .flow-buttons{display:flex;flex-wrap:wrap;align-items:center;gap:8px;margin:10px 0 0}.flows .flow-import{margin-top:18px;padding-top:14px;border-top:1px solid var(--so-line)}.flows .flow-import h3{font-size:.95rem;margin:0}.flows .flow-terms{list-style:none;padding:0;margin:8px 0 16px;display:grid;gap:10px}.flows .flow-terms li{white-space:pre-line;overflow-wrap:anywhere}.flows .flow-terms pre{white-space:pre-wrap;overflow-wrap:anywhere;font-size:.8rem;margin:6px 0 0}.flows .flow-import-preview h2{font-size:1rem;margin:20px 0 4px}.flows .flow-untrusted{font-weight:600}.flows button.primary{background:var(--primary);color:var(--primary-foreground);border-color:var(--primary)}.flows fieldset{border:0;padding:0;margin:0;display:grid;gap:10px;min-width:0}.flows legend{font-weight:600;padding:0;margin-bottom:6px}.flows textarea[hidden]{display:none}.flows button.secondary{background:transparent;color:var(--foreground);border:1px solid var(--border)}@media(max-width:600px){.flows input,.flows select{font-size:16px}}@media(max-width:760px){.flows .card{padding:10px 12px;margin:8px 0;position:relative}.flows .flow-row{row-gap:2px}.flows .flow-row h2 a::after{content:"";position:absolute;inset:0;border-radius:inherit}.flows .flow-counts{line-height:1.35}}`;
@@ -84,9 +86,19 @@ export function flowView(store, flow, viewer, selectedCard, setup = { dir: null,
     const sortZones = new Set(stages.filter(one => one.kind === "sort").map(one => one.id));
     const decisions = sortZones.size === 0 ? new Map() : store.flowSortDecisions(flow.id);
     const mates = new Map(store.teammates([flow.repo]).map(one => [one.id, one]));
+    const taskSecrets = new Map();
+    const secretsFor = (repo) => {
+        if (!taskSecrets.has(repo))
+            taskSecrets.set(repo, Object.values(readFlowSecrets(setup.dir, repo)));
+        return taskSecrets.get(repo);
+    };
+    const now = new Date();
     const cards = store.flowCards(flow.id, true).filter(card => card.state === "active" || Date.now() - Date.parse(card.updatedAt) < 7 * 86_400_000).map((card) => {
         const stage = stages.find(one => one.id === card.stage);
         const task = card.task ?? card.primaryTask;
+        // Build zones may file into another project; the flow alone does not admit its task's detail.
+        const taskRepo = card.task === null ? null : store.lookupRef(card.task)?.repo ?? null;
+        const canReadTask = taskRepo !== null && (taskRepo === flow.repo || (setup.repos.includes(taskRepo) && store.accountCanAccess(viewer.name, taskRepo)));
         const discussion = store.flowComments(card.id);
         const watchers = store.flowCardWatchers(card.id);
         const decider = stage?.kind === "approval" ? deciderOf(stage, flow) : null;
@@ -136,7 +148,9 @@ export function flowView(store, flow, viewer, selectedCard, setup = { dir: null,
             ...(content.items === undefined ? {} : { items: content.items.map((item, index) => ({ number: index + 1, title: item.title, lines: whyLines(item.why), source: item.source, url: item.url,
                     image: item.shot === null || content.shots === null ? null : { src: `/r/${content.shots.run}/evidence/${item.shot}`, caption: itemCaption(index + 1, item) } })) }) });
         return {
-            id: card.id, title: card.title, description: card.description, stage: card.stage, state: card.state, waiting: card.waiting,
+            id: card.id, title: card.title, description: card.description, stage: card.stage, state: card.state,
+            waiting: card.state === "active" && card.task !== null && (stage?.kind === "task" || stage?.kind === "report")
+                ? canReadTask ? flowCardTaskLine(store, card.task, taskRepo, now, secretsFor(taskRepo)) : "Task unavailable" : card.waiting,
             task: task === null ? null : { id: task, href: `/t/${encodeURIComponent(task)}` },
             createdBy: card.createdBy, updatedAt: card.updatedAt,
             canDecide,

package/dist/health-cli.d.ts

@@ -0,0 +1,3 @@
+import { type TeamCliOptions } from './team-cli.js';
+/** Read the running server, never a fresh CLI process's empty counters or the local database. */
+export declare function runHealthCommand(argv: readonly string[], write: (line: string) => void, options?: TeamCliOptions): Promise<number>;

package/dist/health-cli.js

@@ -0,0 +1,79 @@
+import { bearerOf, centralProfile } from './team-cli.js';
+import { envelopeJson } from './envelope.js';
+import { healthSnapshotSchema } from './contracts/health.js';
+/** Read the running server, never a fresh CLI process's empty counters or the local database. */
+export async function runHealthCommand(argv, write, options = {}) {
+    const json = argv.includes('--json');
+    const fail = (message, reason = 'unavailable', code = 1) => {
+        write(json ? envelopeJson({ command: 'health', ok: false, reason, message }) : message);
+        return code;
+    };
+    if (argv.includes('--help')) {
+        write('toolroll health [--profile <name>] [--json]\nRecent latency, event-loop delay, write waits and live streams from the connected server. An instance operator must sign in with toolroll connect first.');
+        return 0;
+    }
+    let profileName;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--json')
+            continue;
+        if (argv[i] === '--profile' && profileName === undefined && argv[i + 1] && !argv[i + 1].startsWith('-')) {
+            profileName = argv[++i];
+            continue;
+        }
+        return fail('Use toolroll health [--profile <name>] [--json].', 'usage', 2);
+    }
+    try {
+        const profile = centralProfile(options, profileName);
+        if (!profile)
+            return fail('Connect to the server first with toolroll connect, then run toolroll health.', 'not-connected', 2);
+        const timeout = AbortSignal.timeout(30_000);
+        const response = await (options.fetch ?? fetch)(`${profile.origin}/health`, {
+            redirect: 'manual', credentials: 'omit', signal: options.signal ? AbortSignal.any([options.signal, timeout]) : timeout,
+            headers: { authorization: bearerOf(profile), accept: json ? 'application/json' : 'text/plain' },
+        });
+        if (response.status !== 200) {
+            await response.body?.cancel();
+            return fail(response.status === 401 || response.status === 403 || response.status === 302
+                ? 'Sign in as an instance operator to read server health.'
+                : response.status === 404 ? 'This server does not provide performance health yet. Update the server.' : 'Server health is unavailable. Try again shortly.');
+        }
+        // A health response is bounded by the fixed route vocabulary. Refuse unrelated HTML and oversized replies.
+        const reader = response.body?.getReader();
+        if (!reader)
+            return fail('The server returned no health measurements.');
+        const chunks = [];
+        let size = 0;
+        try {
+            for (;;) {
+                const part = await reader.read();
+                if (part.done)
+                    break;
+                size += part.value.byteLength;
+                if (size > 128 * 1024) {
+                    await reader.cancel();
+                    return fail('The server returned an unexpected health response.');
+                }
+                chunks.push(part.value);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const text = new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks));
+        if (json) {
+            const parsed = healthSnapshotSchema.safeParse(JSON.parse(text));
+            if (!parsed.success)
+                return fail('The server returned an unexpected health response.');
+            write(envelopeJson({ command: 'health', ok: true, health: parsed.data }));
+        }
+        else {
+            if (!response.headers.get('content-type')?.startsWith('text/plain') || !text.startsWith('Server health'))
+                return fail('The server returned an unexpected health response.');
+            write(text.trimEnd());
+        }
+        return 0;
+    }
+    catch {
+        return fail('Could not read server health. Check the saved connection and server availability.');
+    }
+}

package/dist/live-bus.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Live views push on write. Nothing here polls once a second.
+ *
+ * - The bus. The database's own revision triggers (workspace-revision.ts)
+ *   move one counter on every meaningful write. After each in-process
+ *   transact() COMMIT, and whenever another process (the worker, the CLI)
+ *   writes the database's write-ahead log, the revision is read once; when
+ *   it moved, every subscriber hears `{ revision }`. A rolled-back or quiet
+ *   write moves nothing and says nothing. A page left open with nothing
+ *   being written costs no database work at all.
+ * - The rooms. Each open task or flow is a room keyed by what it shows.
+ *   When the bus speaks, a room rechecks every viewer's access (a signed-out
+ *   or narrowed account is dropped), takes its fingerprint once, and only if
+ *   that moved tells its pages `change` with the fingerprint and revision —
+ *   an invalidation, never content. The page reads itself again under its
+ *   own checks, so redaction stays the page's.
+ * - The safety net. Every room also checks itself about every 30 s, so a
+ *   missed signal heals, and sends a keep-alive between.
+ * - Back-pressure. Each page's stream is bounded: a page that falls behind
+ *   gets one `reload` and ends so its EventSource can reconnect.
+ *
+ * Transport seam: a future WebSocket (live cursors) subscribes to the same
+ * LiveBus beside these SSE rooms; nothing in the Store or the triggers changes.
+ */
+import { type FSWatcher } from "node:fs";
+import type { ServerResponse } from "node:http";
+import type { Store } from "./store.js";
+export type LiveChange = {
+    revision: string;
+};
+export type LiveBus = {
+    subscribe: (listener: (change: LiveChange) => void) => () => void;
+    publish: (change: LiveChange) => void;
+    /** The last revision heard, if any. */
+    revision: () => string | null;
+    listeners: () => number;
+};
+export declare function createLiveBus(): LiveBus;
+export type WorkspaceFollower = {
+    close: () => void; /** Read the revision now (tests, and a commit signal). */
+    check: () => void;
+};
+/**
+ * Publish the workspace revision when it moves: after this process commits,
+ * and when the database's write-ahead log changes under another process.
+ * Signals in one turn of the event loop coalesce into one read.
+ */
+export declare function followWorkspace(store: Store, current: () => string, bus: LiveBus, options?: {
+    file?: string | null;
+    watchFile?: (path: string, listener: () => void) => FSWatcher | null;
+}): WorkspaceFollower;
+/** About every 30 s a room checks itself; a keep-alive goes between. */
+export declare const SAFETY_NET_MS = 30000;
+export declare const KEEP_ALIVE_MS = 15000;
+/** What a page's stream may hold unsent before it is "behind". */
+export declare const STREAM_LIMIT_BYTES: number;
+/** One page's stream, bounded. Overflow is terminal, even below Node's drain threshold. */
+export declare class LiveStream {
+    readonly response: ServerResponse;
+    private readonly limit;
+    private readonly onOverflow;
+    private ended;
+    constructor(response: ServerResponse, limit?: number, onOverflow?: () => void);
+    get open(): boolean;
+    private overflow;
+    private write;
+    send(event: string, data: unknown): void;
+    keepAlive(): void;
+}
+export type LiveViewer = {
+    name: string;
+    response: ServerResponse;
+    valid: () => boolean;
+};
+export type LiveRooms<K, V extends LiveViewer> = {
+    /** Keep this page's stream on the room until it closes; the first events say where it stands and who's here. */
+    join: (key: K, viewer: V) => void;
+    /** Every stream, ended (the server is closing). */
+    close: () => void;
+    size: () => number;
+};
+export type LiveRoomOptions = {
+    bus?: LiveBus | null;
+    safetyNetMs?: number;
+    keepAliveMs?: number;
+    limitBytes?: number;
+};
+/** Rooms of open pages that hear the bus. `presence` says who else is here, as each page should see it. */
+export declare function createLiveRooms<K, V extends LiveViewer>(fingerprint: (key: K) => string | null, presence: (viewers: readonly V[], me: string) => unknown, options?: LiveRoomOptions): LiveRooms<K, V>;