@adecore/agents 0.21.0 → 0.21.2

package/dist/usage/aggregate.js

@@ -28,6 +28,59 @@ function slotOf(format, timestampMs, resolution) {
 function emptyTotals() {
     return { ...EMPTY_TOTALS };
 }
+function foldBucket(buckets, slot, record, account, price, cost) {
+    const key = `${slot}\0${record.provider}\0${record.model}\0${account ?? ''}`;
+    let bucket = buckets.get(key);
+    if (bucket === undefined) {
+        bucket = {
+            slot,
+            provider: record.provider,
+            model: record.model,
+            account,
+            totals: emptyTotals(),
+            costUsd: 0,
+            priced: false,
+            cacheSavingsUsd: 0,
+            sessions: new Set()
+        };
+        buckets.set(key, bucket);
+    }
+    bucket.totals = addTotals(bucket.totals, record.totals);
+    bucket.costUsd += cost;
+    bucket.priced ||= price !== null;
+    bucket.cacheSavingsUsd += price === null ? 0 : cacheSavingsOf(record.totals, price);
+    if (record.sessionId !== '') {
+        bucket.sessions.add(record.sessionId);
+    }
+}
+function foldModel(models, record, account, lookup, cost) {
+    const key = `${record.provider}\0${record.model}\0${account ?? ''}`;
+    let model = models.get(key);
+    if (model === undefined) {
+        model = {
+            provider: record.provider,
+            model: record.model,
+            account,
+            totals: emptyTotals(),
+            costUsd: 0,
+            priced: false,
+            basis: lookup.basis,
+            pricedAs: lookup.pricedAs
+        };
+        models.set(key, model);
+    }
+    model.totals = addTotals(model.totals, record.totals);
+    model.costUsd += cost;
+    model.priced ||= lookup.price !== null;
+}
+function foldProject(project, record, cost) {
+    project.totals = addTotals(project.totals, record.totals);
+    project.costUsd += cost;
+    const share = project.byProvider.get(record.provider) ?? { costUsd: 0, tokens: 0 };
+    share.costUsd += cost;
+    share.tokens += totalTokensOf(record.totals);
+    project.byProvider.set(record.provider, share);
+}
 /* The account a record was made under, the default one under its CLI's kind. */
 export function accountOfRecord(record) {
     return record.account ?? record.provider;
@@ -41,8 +94,6 @@ export async function aggregate(records, payload, prices, known) {
     const format = slotFormatter(payload.timeZone, payload.resolution);
     const buckets = new Map();
     const models = new Map();
-    /* The basis of the first record of a model prices the whole row: a model has one price. */
-    const modelBasis = new Map();
     const projects = new Map();
     const sessions = new Set();
     const resolver = new ProjectResolver(known);
@@ -59,42 +110,13 @@ export async function aggregate(records, payload, prices, known) {
         if (day < payload.from || day > payload.to) {
             continue;
         }
-        const { price, basis, pricedAs } = prices.look(record.model);
-        const cost = price === null ? 0 : costOf(record.totals, price);
-        const bucketKey = `${slot}\0${record.provider}\0${record.model}\0${account ?? ''}`;
-        let bucket = buckets.get(bucketKey);
-        if (bucket === undefined) {
-            bucket = {
-                slot,
-                provider: record.provider,
-                model: record.model,
-                account,
-                totals: emptyTotals(),
-                costUsd: 0,
-                priced: false,
-                cacheSavingsUsd: 0,
-                sessions: new Set()
-            };
-            buckets.set(bucketKey, bucket);
-        }
-        bucket.totals = addTotals(bucket.totals, record.totals);
-        bucket.costUsd += cost;
-        bucket.priced ||= price !== null;
-        bucket.cacheSavingsUsd += price === null ? 0 : cacheSavingsOf(record.totals, price);
+        const lookup = prices.look(record.model);
+        const cost = lookup.price === null ? 0 : costOf(record.totals, lookup.price);
+        foldBucket(buckets, slot, record, account, lookup.price, cost);
+        foldModel(models, record, account, lookup, cost);
         if (record.sessionId !== '') {
-            bucket.sessions.add(record.sessionId);
             sessions.add(`${record.provider}\0${record.sessionId}`);
         }
-        const modelKey = `${record.provider}\0${record.model}\0${account ?? ''}`;
-        let model = models.get(modelKey);
-        if (model === undefined) {
-            model = { provider: record.provider, model: record.model, account, totals: emptyTotals(), costUsd: 0, priced: false };
-            models.set(modelKey, model);
-            modelBasis.set(modelKey, { basis, pricedAs });
-        }
-        model.totals = addTotals(model.totals, record.totals);
-        model.costUsd += cost;
-        model.priced ||= price !== null;
         let folder = folders.get(record.cwd);
         if (folder === undefined) {
             const resolved = await resolver.resolve(record.cwd);
@@ -104,13 +126,7 @@ export async function aggregate(records, payload, prices, known) {
                 projects.set(folder, { folder, name: resolved.name, projectId: resolved.projectId, byProvider: new Map(), totals: emptyTotals(), costUsd: 0 });
             }
         }
-        const project = projects.get(folder);
-        project.totals = addTotals(project.totals, record.totals);
-        project.costUsd += cost;
-        const share = project.byProvider.get(record.provider) ?? { costUsd: 0, tokens: 0 };
-        share.costUsd += cost;
-        share.tokens += totalTokensOf(record.totals);
-        project.byProvider.set(record.provider, share);
+        foldProject(projects.get(folder), record, cost);
     }
     return {
         buckets: [...buckets.values()]
@@ -128,15 +144,15 @@ export async function aggregate(records, payload, prices, known) {
             a.provider.localeCompare(b.provider) ||
             a.model.localeCompare(b.model) ||
             (a.account ?? '').localeCompare(b.account ?? '')),
-        models: [...models.entries()]
-            .map(([key, model]) => ({
+        models: [...models.values()]
+            .map((model) => ({
             provider: model.provider,
             model: model.model,
             ...(model.account === null ? {} : { account: model.account }),
             totals: model.totals,
             costUsd: model.priced ? model.costUsd : null,
-            priceBasis: modelBasis.get(key)?.basis ?? 'unknown',
-            pricedAs: modelBasis.get(key)?.pricedAs ?? null
+            priceBasis: model.basis,
+            pricedAs: model.pricedAs
         }))
             .sort((a, b) => (b.costUsd ?? -1) - (a.costUsd ?? -1)),
         projects: [...projects.values()]

package/dist/usage/exchange.js

@@ -1,7 +1,7 @@
 import { mkdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { isNotFound, writeAtomic } from '../fs.js';
 import { errorText } from '../error-text.js';
+import { isNotFound, writeAtomic } from '../fs.js';
 export const FRANKFURTER_URL = 'https://api.frankfurter.app/latest';
 /* The bank publishes one rate a day, so a rate a day old is the rate. */
 const TTL_MS = 24 * 60 * 60 * 1000;

package/dist/usage/limits/monitor.d.ts

@@ -1,8 +1,8 @@
 import type { UsageLimitsSnapshot, UsageProvider } from '@adecore/agent-contracts';
-import type { ProviderRegistry } from '../../providers/registry.ts';
+import type { CodexClientInfo } from '../../chat/codex-transport.ts';
 import type { AgentSink } from '../../events.ts';
+import type { ProviderRegistry } from '../../providers/registry.ts';
 import { type LimitsUpdate } from './normalize.ts';
-import type { CodexClientInfo } from '../../chat/codex-transport.ts';
 import { type ProbeResult } from './probe.ts';
 export type ProbeEnv = Record<string, string>;
 export interface LimitAccount {

package/dist/usage/limits/monitor.js

@@ -1,8 +1,8 @@
+import { ClientSinks } from '../../client-sinks.js';
+import { errorText } from '../../error-text.js';
 import { definedEnv } from '../../providers/accounts/launch.js';
 import { mergeWindows } from './normalize.js';
 import { probeClaude, probeCodex } from './probe.js';
-import { ClientSinks } from '../../client-sinks.js';
-import { errorText } from '../../error-text.js';
 /* Often enough that a bar is never far behind, rarely enough that two CLIs are not started all day. */
 const PROBE_INTERVAL_MS = 5 * 60_000;
 const MAX_BACKOFF_MS = 60 * 60_000;

package/dist/usage/limits/probe.js

@@ -1,8 +1,8 @@
 import { withTimeout } from '../../async.js';
 import { spawnChatProcess } from '../../chat/chat-process.js';
 import { CodexTransport, DEFAULT_CODEX_CLIENT } from '../../chat/codex-transport.js';
-import { readClaudeUsage, readCodexLimits } from './normalize.js';
 import { errorText } from '../../error-text.js';
+import { readClaudeUsage, readCodexLimits } from './normalize.js';
 /* A CLI that has not answered by now is not going to; the next pass tries again. */
 const PROBE_TIMEOUT_MS = 20_000;
 const CODEX_READ_TIMEOUT_MS = 3_000;

package/dist/usage/pricing.js

@@ -1,7 +1,7 @@
 import { mkdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { isNotFound, writeAtomic } from '../fs.js';
 import { errorText } from '../error-text.js';
+import { isNotFound, writeAtomic } from '../fs.js';
 import bundled from './prices-snapshot.json' with { type: 'json' };
 export const LITELLM_URL = 'https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json';
 /* A table a day old still prices everything anyone ran today, and nobody has to be online for it. */

package/dist/usage/roots.js

@@ -2,8 +2,7 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 /* Where in its config folder each CLI leaves its transcripts. */
 const TRANSCRIPTS = { claude: 'projects', codex: 'sessions' };
-/* Where each CLI leaves its transcripts. The same environment variables the hooks installer reads,
-   so the scanner and the installer never disagree about where a CLI keeps its things. */
+/* The transcripts of the default accounts, found through the variables the CLIs themselves read. */
 export function usageRoots(env = process.env) {
     const home = env.HOME ?? homedir();
     return [

package/dist/usage/scanner.js

@@ -1,12 +1,12 @@
 import { mkdir, open, readFile, readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { errorText } from '../error-text.js';
 import { isNotFound, writeAtomic } from '../fs.js';
 import { decodeIndex, encodeIndex } from './index-file.js';
 import { foldByKey } from './record.js';
 import { claudeMightCarryUsage, parseClaudeLine } from './readers/claude.js';
 import { cloneCodexState, codexMightCarryUsage, createCodexState, parseCodexLine } from './readers/codex.js';
 import { usageRoots } from './roots.js';
-import { errorText } from '../error-text.js';
 /* What a file holds from `from` to its end, as it is at the read. */
 async function readFrom(path, from) {
     const handle = await open(path, 'r');
@@ -53,11 +53,11 @@ async function listJsonl(dir, out = []) {
  * read again next time. The Codex state is snapshotted before that tail for the same reason.
  */
 function parseChunk(text, provider, from, state) {
-    let records = [];
     const end = text.lastIndexOf('\n');
     const whole = end === -1 ? '' : text.slice(0, end);
     const tail = text.slice(end + 1);
     const read = (chunk, codex) => {
+        const records = [];
         for (const raw of chunk.split('\n')) {
             const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
             if (line === '') {
@@ -79,14 +79,12 @@ function parseChunk(text, provider, from, state) {
                 }
             }
         }
+        return records;
     };
     const codex = provider === 'codex' ? (state ?? createCodexState()) : null;
-    read(whole, codex);
+    const counted = read(whole, codex);
     const committed = codex === null ? null : cloneCodexState(codex);
-    const counted = records;
-    records = [];
-    read(tail, codex);
-    return { records: counted, tail: records, offset: from + (end === -1 ? 0 : Buffer.byteLength(whole, 'utf8') + 1), codex: committed };
+    return { records: counted, tail: read(tail, codex), offset: from + (end === -1 ? 0 : Buffer.byteLength(whole, 'utf8') + 1), codex: committed };
 }
 /*
  * The account a record of a root belongs to, as a record keeps it (absent for the default account):
@@ -113,8 +111,8 @@ function withAccount(records, accountOf) {
     });
 }
 /*
- * Read appended transcript bytes incrementally, but restart after rewrites or truncation. Preserve
- * totals for deleted transcripts because their usage still happened.
+ * Reads only what a transcript appended since the last scan, and starts a file over once it was
+ * rewritten or cut. A deleted transcript keeps its totals, since its usage still happened.
  */
 export class UsageScanner {
     home;

package/dist/usage/usage-service.d.ts

@@ -1,8 +1,8 @@
 import type { UsageAccount, UsageSummaryPayload, UsageSummaryResult } from '@adecore/agent-contracts';
 import type { AgentSink } from '../events.ts';
 import type { KnownProject } from './projects.ts';
-import { type UsageScannerOptions } from './scanner.ts';
 import type { UsageRootPath } from './roots.ts';
+import { type UsageScannerOptions } from './scanner.ts';
 export interface UsageServiceOptions {
     home: string;
     allowPriceFetch?: boolean;
@@ -31,5 +31,4 @@ export declare class UsageService {
     stop(): void;
     private rescan;
     private runScan;
-    private emit;
 }

package/dist/usage/usage-service.js

@@ -1,9 +1,9 @@
+import { ClientSinks } from '../client-sinks.js';
+import { errorText } from '../error-text.js';
 import { accountOfRecord, aggregate } from './aggregate.js';
 import { ExchangeRates } from './exchange.js';
 import { PriceBook } from './pricing.js';
 import { UsageScanner } from './scanner.js';
-import { errorText } from '../error-text.js';
-import { ClientSinks } from '../client-sinks.js';
 /* A scan this fresh answers the question the page is asking, so nothing is opened for it. */
 const SCAN_TTL_MS = 60_000;
 /* The accounts of the machine, and after them any a record names that the machine no longer has, under its id. */
@@ -121,10 +121,7 @@ export class UsageService {
         }
         this.report = report;
         if (report.changedFiles > 0) {
-            this.emit({ event: 'usage.changed', payload: { scannedAt: report.at } });
+            this.sinks.emit({ event: 'usage.changed', payload: { scannedAt: report.at } });
         }
     }
-    emit(event) {
-        this.sinks.emit(event);
-    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/agents",
-  "version": "0.21.0",
+  "version": "0.21.2",
   "description": "Node-compatible agent chat hosts, providers, accounts, usage and durable task coordination.",
   "type": "module",
   "exports": {
@@ -20,8 +20,8 @@
     "test": "bun --conditions=source test"
   },
   "dependencies": {
-    "@adecore/agent-contracts": "0.21.0",
-    "@adecore/intelligent-ui": "0.21.0",
+    "@adecore/agent-contracts": "0.21.2",
+    "@adecore/intelligent-ui": "0.21.2",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/src/async.ts

@@ -1,9 +1,6 @@
-/* The two waits the host does: a pause it can be woken from, and a deadline on somebody else's promise. */
-
 /*
- * Resolves after `ms`, or at once when the signal is raised. An abort ends the wait rather than
- * failing it: every caller here is a loop that checks the signal itself on the next turn, and a
- * rejection would only be caught and thrown away.
+ * Resolves after `ms`, or at once when the signal is raised. An abort resolves instead of rejecting:
+ * every caller is a loop that checks the signal itself on its next turn.
  */
 export function wait(ms: number, signal?: AbortSignal): Promise<void> {
     return new Promise((resolve) => {
@@ -19,10 +16,7 @@ export function wait(ms: number, signal?: AbortSignal): Promise<void> {
     });
 }
 
-/*
- * The promise, or `message` when it takes longer than `ms`. The timer is cleared either way, so a
- * call that answers at once does not hold the process for the rest of its deadline.
- */
+/* The timer is cleared either way, so a call that answers at once does not hold the process until its deadline. */
 export function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => reject(new Error(message)), ms);

package/src/chat/chat-core.ts

@@ -27,7 +27,6 @@ import {
     type ModelSelection,
     type RuntimeMode
 } from '@adecore/agent-contracts';
-import { ChatUiQueries, type ChatUiHost } from './ui-queries.ts';
 import { ClientSinks } from '../client-sinks.ts';
 import { errorText } from '../error-text.ts';
 import type { AgentEvent, AgentSink } from '../events.ts';
@@ -38,6 +37,7 @@ import { SkillIndex } from '../skills.ts';
 import type { LimitsUpdate } from '../usage/limits/normalize.ts';
 import { usageRoots } from '../usage/roots.ts';
 import type { AttachmentStore } from './attachment-store.ts';
+import { commandLabel, isBackgroundWork, runsInBackground, type BackgroundWork } from './background-work.ts';
 import type { BookmarkStore } from './bookmark-store.ts';
 import { ChatLog, COMPACT_ABOVE_BYTES } from './chat-log.ts';
 import type { SpawnChatProcess } from './chat-process.ts';
@@ -58,8 +58,9 @@ import type { CodexClientInfo } from './codex-transport.ts';
 import { ComposerPreferences } from './composer-preferences.ts';
 import { DeltaCoalescer } from './delta-coalescer.ts';
 import { ChatError } from './errors.ts';
-import { commandLabel, isBackgroundWork, runsInBackground, type BackgroundWork } from './background-work.ts';
+import { readableAssistantText } from './readable-text.ts';
 import { SubagentReader, type SubagentReaderOptions } from './subagent-reader.ts';
+import { ChatUiQueries, type ChatUiHost } from './ui-queries.ts';
 import type { VisualInput, VisualStore } from './visual-store.ts';
 
 /* A turn that was running when the host went down, and the attempt that would take it up again. */
@@ -71,12 +72,12 @@ export interface InterruptedRun {
 
 type BookmarkableItem = Extract<ChatItem, { kind: 'user' | 'assistant' }>;
 
-/* A message a person or the agent wrote in the chat's own thread; a subagent's words belong to its row. */
 function withoutHidden(info: ChatInfo): ChatInfo {
     const { hidden: _hidden, ...rest } = info;
     return rest;
 }
 
+/* A message a person or the agent wrote in the chat's own thread; a subagent's words belong to its row. */
 function isBookmarkable(item: ChatItem): item is BookmarkableItem {
     return item.kind === 'user' || (item.kind === 'assistant' && (item.parentToolUseId ?? null) === null);
 }
@@ -84,7 +85,8 @@ function isBookmarkable(item: ChatItem): item is BookmarkableItem {
 /* The start of a message on one line; a message of only attachments is its file names. */
 function excerptOf(item: BookmarkableItem): string {
     const files = item.kind === 'user' ? (item.attachments ?? []).map((attachment) => attachment.name).join(', ') : '';
-    return (item.text.trim() === '' ? files : item.text).replace(/\s+/g, ' ').trim();
+    const text = item.kind === 'assistant' ? readableAssistantText(item) : item.text;
+    return (text.trim() === '' ? files : text).replace(/\s+/g, ' ').trim();
 }
 
 // One process worked on the turn and one more may take it up after a restart; a loop of resumes could redo a command forever.
@@ -102,6 +104,8 @@ const DEFAULT_RESUME_WORDS: ResumeWords = {
 
 export interface ChatCoreOptions {
     intelligentUi?: ChatUiHost;
+    // The info string that marks a UI fence in a reply, for a host that keeps a name of its own.
+    uiFenceLanguage?: string;
     providers: ProviderRegistry;
     // Where the threads are kept; without it a chat lives as long as the process.
     store?: ChatStore;
@@ -175,6 +179,7 @@ export class ChatCore {
     readonly claudeProjectsDir: string;
     readonly composerPreferences = new ComposerPreferences();
     private readonly uiQueries: ChatUiQueries | null;
+    private readonly uiFenceLanguage: string | undefined;
     private readonly checkpoints: TurnCheckpoints | null;
     private readonly instructions: string | null;
     private readonly skillIndex: SkillIndex;
@@ -188,7 +193,7 @@ export class ChatCore {
     // How big each record was the last time it went to disk, and the writes waiting for a big one.
     private readonly sizes = new Map<string, number>();
     private readonly waiting = new Map<string, ReturnType<typeof setTimeout>>();
-    // What the last record held that no event carries (preambles, the host's extras), as its JSON.
+    // What the last record held that no event carries (preambles, the host's extras, captured UI access), as its JSON.
     private readonly unlogged = new Map<string, string>();
     // The write in flight per chat, so the next one queues behind it instead of racing it.
     private readonly writes = new Map<string, Promise<void>>();
@@ -202,6 +207,7 @@ export class ChatCore {
 
     constructor(options: ChatCoreOptions) {
         this.uiQueries = options.intelligentUi ? new ChatUiQueries(options.intelligentUi) : null;
+        this.uiFenceLanguage = options.uiFenceLanguage;
         this.providers = options.providers;
         this.store = options.store ?? null;
         this.bookmarks = options.bookmarks ?? null;
@@ -398,9 +404,11 @@ export class ChatCore {
         const references = this.referencesFor(payload.chatId);
         const session = new ChatSession({
             info,
+            ...(this.uiFenceLanguage ? { uiFenceLanguage: this.uiFenceLanguage } : {}),
             ...(this.uiQueries ? { ui: { schemas: this.uiQueries.schemas, observe: (item, final) => this.uiQueries!.observe(session, item, final) } } : {}),
             items: stored?.items ?? [],
             preambles: stored?.preambles ?? [],
+            uiAccess: stored?.uiAccess ?? {},
             provider,
             command: this.commands[kind] ?? provider.command,
             ...(this.spawn ? { spawn: this.spawn } : {}),
@@ -735,7 +743,10 @@ export class ChatCore {
         return this.uiQueries.query(this.require(payload.chatId), payload);
     }
 
-    async choose(payload: ChatUiChoicePayload): Promise<{ queued: boolean; turnId: string }> {
+    async choose(payload: ChatUiChoicePayload, clientId: string): Promise<{ queued: boolean; turnId: string }> {
+        if (!this.attached.get(payload.chatId)?.has(clientId)) {
+            throw new ChatError('refused-query', 'Attach to the chat before answering its UI.');
+        }
         const session = this.require(payload.chatId);
         const queries = await this.uiQueries?.choiceValues(session, payload);
         const result = session.choose(payload, queries);
@@ -1022,7 +1033,15 @@ export class ChatCore {
             const log = this.logs.get(chatId);
             // Not folded here: an older write still in flight may land after this one, and the log is what covers for it.
             try {
-                this.store.writeSync(chatId, info, items, { seq: log?.seq ?? 0, resetSeq: log?.resetSeq ?? 0 }, session.preambles, this.recordExtras(chatId));
+                this.store.writeSync(
+                    chatId,
+                    info,
+                    items,
+                    { seq: log?.seq ?? 0, resetSeq: log?.resetSeq ?? 0 },
+                    session.preambles,
+                    this.recordExtras(chatId),
+                    session.uiAccessRecord
+                );
             } catch (e) {
                 console.error(`Chat record for ${chatId} failed:`, errorText(e));
             }
@@ -1181,7 +1200,8 @@ export class ChatCore {
             // A delta held back is already in the thread, so it gets its seq before the snapshot says where it ends.
             this.coalescers.get(chatId)?.flush();
             const extras = this.recordExtras(chatId);
-            const unlogged = JSON.stringify([session.preambles, extras]);
+            const uiAccess = session.uiAccessRecord;
+            const unlogged = JSON.stringify([session.preambles, extras, uiAccess]);
             const folds = fold || log.size > COMPACT_ABOVE_BYTES || !log.onDisk;
             // The log already holds every change to the thread, so the whole record is rewritten only to fold
             // the log, on a chat's first write, or for what no event carries.
@@ -1190,7 +1210,7 @@ export class ChatCore {
             }
             const { info, items } = session.thread.snapshot();
             const at = { seq: log.seq, resetSeq: log.resetSeq };
-            this.sizes.set(chatId, await this.store.write(chatId, info, items, at, session.preambles, extras));
+            this.sizes.set(chatId, await this.store.write(chatId, info, items, at, session.preambles, extras, uiAccess));
             this.unlogged.set(chatId, unlogged);
             // A chat killed while the write was out has no log left to fold.
             if (this.logs.get(chatId) === log && folds) {

package/src/chat/chat-log.ts

@@ -48,8 +48,8 @@ export interface ChatLogState {
 }
 
 /*
- * Number and synchronously append each broadcast event so disk, memory and snapshot boundaries keep
- * one order. Recent lines stay in memory for immediate `since` attachment.
+ * Numbers every broadcast event and appends it synchronously, so disk, memory and snapshot boundaries
+ * keep one order. Recent lines stay in memory to answer an attach with `since` at once.
  */
 export class ChatLog {
     private readonly path: string | null;