@pat-lewczuk/cezar 0.1.3 → 0.1.4

package/dist/core/ui-events.d.ts

@@ -0,0 +1,294 @@
+/**
+ * Normalized agent-event protocol v2 — the shared vocabulary every runner
+ * emits ALONGSIDE the v1 `AgentEvent` stream (never replacing it; mixed
+ * NDJSON files stay valid — old recordings must keep replaying).
+ *
+ * Contract sources (authoritative, in this order):
+ *  - `.ai/analysis/cockpit-ui-redesign/agent-event-protocols.md` §7 (schema)
+ *    and §7.1 (per-backend mapping tables);
+ *  - the spec `.ai/specs/2026-07-14-cockpit-ui-redesign.md`
+ *    §"Normalized agent-event protocol v2".
+ *
+ * Design rules baked in:
+ *  1. Item-lifecycle model (Codex/ACP style): one stable `id` per item with
+ *     started/delta/updated/completed phases — two of the three backends are
+ *     natively item-shaped and claude maps trivially.
+ *  2. ACP vocabulary wherever a choice is arbitrary (tool status/kind, plan
+ *     entries, diff shape, stop reasons) for ecosystem alignment.
+ *  3. Every v1 `AgentEvent` stays derivable from this stream, so consumers
+ *     can migrate one panel at a time.
+ *
+ * This module is pure vocabulary: no runtime imports, no runner coupling.
+ * Step 2.4 mirrors it into `web/app/src/protocol/`.
+ */
+/** The backend that produced a session — mirrors `RunnerId` in
+ *  `agent-runner.ts` (kept structurally identical; a type-level test
+ *  guards against drift so this module stays dependency-free). */
+export type UiBackend = 'claude' | 'codex' | 'opencode';
+/**
+ * Tool lifecycle status (ACP: pending/in_progress/completed/failed).
+ * `running` ≡ ACP `in_progress` (opencode's word — reads better in code);
+ * `declined` covers codex approval declines and claude `permission_denials`.
+ *
+ * Per backend: claude has no pending phase (`tool_use` arrives already
+ * running); codex maps `inProgress→running`, `completed/failed/declined`
+ * verbatim; opencode maps `pending/running` verbatim and `error→failed`.
+ */
+export type ToolStatus = 'pending' | 'running' | 'completed' | 'failed' | 'declined';
+/**
+ * Icon/verb hint for a tool item — a superset of ACP's ToolKind.
+ * `task` = subagent spawn (claude Task / opencode subtask / codex review).
+ */
+export type ToolKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'think' | 'fetch' | 'task' | 'plan' | 'other';
+/**
+ * Why a turn (or the session) stopped.
+ *
+ * Per backend: claude `result` subtype success→`end_turn`,
+ * error_max_turns→`max_tokens`, error_during_execution→`error`; codex
+ * turn/completed→`end_turn`, turn/failed→`error`, interrupt→`cancelled`;
+ * opencode `session.idle`→`end_turn` (or `error` when a session.error
+ * preceded it).
+ */
+export type StopReason = 'end_turn' | 'max_tokens' | 'refusal' | 'cancelled' | 'timeout' | 'error';
+/** Status of one plan/todo entry (claude TodoWrite uses these words verbatim;
+ *  codex todoList and opencode todowrite map 1:1). */
+export type PlanStatus = 'pending' | 'in_progress' | 'completed';
+/** One entry of the session plan — full-replacement semantics (ACP style). */
+export interface PlanEntry {
+    content: string;
+    status: PlanStatus;
+    priority?: 'high' | 'medium' | 'low';
+    /** Present-continuous label shown while the entry is in progress
+     *  (claude TodoWrite's `activeForm`). */
+    activeForm?: string;
+}
+/**
+ * Raw token counts — never pre-weighted (cost weighting is a presentation
+ * concern, not a wire concern).
+ *
+ * Per backend: claude `result.usage` (+ `total_cost_usd` as `costUsd` on the
+ * carrying event); codex `thread/tokenUsage/updated` (no USD); opencode
+ * `message.updated` info.tokens/cost and `step-finish` parts.
+ */
+export interface TokenUsage {
+    input: number;
+    output: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    reasoning?: number;
+    /** The backend's own total when given, else the sum of the parts. */
+    total: number;
+    /** Model context-window size when known — feeds the fill gauge. */
+    contextWindow?: number;
+}
+/**
+ * One file change carried by an edit-tool item.
+ * claude `Edit`/`Write` input → `oldText`/`newText`; codex
+ * `fileChange.changes[]` → `unified`; opencode `patch` parts → `unified`.
+ * `oldText: null` means the file is newly created.
+ */
+export interface FileDiff {
+    path: string;
+    oldText: string | null;
+    newText?: string;
+    unified?: string;
+}
+/** A file location a tool touched (feeds "jump to file" affordances). */
+export interface ToolLocation {
+    path: string;
+    line?: number;
+}
+/** A choice offered by a permission request (ACP option kinds). */
+export type PermissionOptionKind = 'allow_once' | 'allow_always' | 'reject_once' | 'reject_always';
+export interface PermissionOption {
+    id: string;
+    label: string;
+    kind: PermissionOptionKind;
+}
+/**
+ * A chat message.
+ * claude: `assistant` `text` blocks (whole-block, or true deltas via
+ * `--include-partial-messages`); codex: `agentMessage` items (`phase` from
+ * the item's own phase field); opencode: text parts of a message.
+ */
+export interface UiMessageItem {
+    kind: 'message';
+    id: string;
+    role: 'assistant' | 'user';
+    text: string;
+    phase?: 'commentary' | 'final';
+    parentItemId?: string;
+}
+/**
+ * Extended thinking / reasoning summary.
+ * claude: `thinking` blocks; codex: `reasoning` items (+ textDelta);
+ * opencode: `reasoning` parts.
+ */
+export interface UiReasoningItem {
+    kind: 'reasoning';
+    id: string;
+    text: string;
+    parentItemId?: string;
+}
+/**
+ * One tool invocation with its full lifecycle.
+ * claude: `tool_use` (started, status `running`) + `tool_result`
+ * (completed/failed; `permission_denials` → `declined`); codex: typed items
+ * (`commandExecution`→execute with `exitCode`, `fileChange`→edit with
+ * `diffs`, `mcpToolCall`→other, `webSearch`→fetch); opencode: tool parts
+ * (state pending/running/completed/error, `patch` parts → `diffs`).
+ *
+ * `parentItemId` nests subagent work under its spawning task item —
+ * claude `parent_tool_use_id`, opencode `subtask` parts, codex review items.
+ */
+export interface UiToolItem {
+    kind: 'tool';
+    id: string;
+    /** The backend's tool name / item type (e.g. `Bash`, `commandExecution`). */
+    name: string;
+    /** ACP-style icon/verb hint — see `toolDisplay()` in `tool-display.ts`. */
+    toolKind: ToolKind;
+    /** Human line, computed once in the protocol layer: "Ran npm test". */
+    title: string;
+    status: ToolStatus;
+    /** Raw input — may arrive incrementally. */
+    input?: unknown;
+    output?: string;
+    error?: string;
+    diffs?: FileDiff[];
+    locations?: ToolLocation[];
+    /** commandExecution / bash exit code, when the backend reports one. */
+    exitCode?: number;
+    parentItemId?: string;
+}
+export type UiItem = UiMessageItem | UiReasoningItem | UiToolItem;
+/**
+ * Session opened.
+ * claude: `system/init` (model, tools, cwd); codex: `thread/started` or the
+ * `thread/start` result; opencode: `POST /session` response.
+ */
+export interface UiSessionStartedEvent {
+    type: 'session.started';
+    sessionId: string;
+    backend: UiBackend;
+    model?: string;
+    cwd?: string;
+    tools?: string[];
+}
+/** Session over (replaces v1 `done` / fatal `error`). */
+export interface UiSessionEndedEvent {
+    type: 'session.ended';
+    reason: StopReason;
+    message?: string;
+}
+/** v1 `note` + `error` unified — severity explicit instead of implied. */
+export interface UiSessionErrorEvent {
+    type: 'session.error';
+    message: string;
+    fatal: boolean;
+}
+/**
+ * A turn began.
+ * claude: on each stdin user message; codex: `turn/started`;
+ * opencode: on each prompt POST.
+ */
+export interface UiTurnStartedEvent {
+    type: 'turn.started';
+    turnId: string;
+}
+/**
+ * A turn finished.
+ * claude: `result` (usage + `total_cost_usd`); codex: `turn/completed` /
+ * `turn/failed`; opencode: `session.idle`.
+ */
+export interface UiTurnCompletedEvent {
+    type: 'turn.completed';
+    turnId: string;
+    stopReason: StopReason;
+    usage?: TokenUsage;
+    costUsd?: number;
+}
+/** An item entered the stream (tools usually with status pending/running). */
+export interface UiItemStartedEvent {
+    type: 'item.started';
+    item: UiItem;
+}
+/**
+ * Streaming append to one field of a live item.
+ * claude: partial-message text deltas; codex: `item/agentMessage/delta`
+ * (`text`), `item/reasoning/textDelta` (`reasoning`),
+ * `item/commandExecution/outputDelta` (`output` — live terminal); opencode:
+ * text/reasoning part cursor deltas, running-state metadata for `output`.
+ * claude has no live command output — the tool card fills on completion
+ * (per-capability degradation, never per-backend).
+ */
+export interface UiItemDeltaEvent {
+    type: 'item.delta';
+    itemId: string;
+    field: 'text' | 'reasoning' | 'output';
+    delta: string;
+}
+/** Status flips and streamed-content snapshots (codex `item/updated`,
+ *  opencode part-state flips such as pending→running). */
+export interface UiItemUpdatedEvent {
+    type: 'item.updated';
+    item: UiItem;
+}
+/** Final snapshot of an item — safe to persist (snapshots, not deltas). */
+export interface UiItemCompletedEvent {
+    type: 'item.completed';
+    item: UiItem;
+}
+/**
+ * Full-replacement plan snapshot (ACP semantics).
+ * claude: `TodoWrite` tool input; codex: `todoList`/`plan` items;
+ * opencode: `todowrite` tool — identical semantics across all three.
+ */
+export interface UiPlanUpdatedEvent {
+    type: 'plan.updated';
+    entries: PlanEntry[];
+}
+/**
+ * RESERVED — wired when auto-approve becomes optional. Types only for now.
+ * claude: `control_request can_use_tool`; codex: the per-item
+ * `requestApproval` JSON-RPC requests; opencode: `permission.updated`.
+ */
+export interface UiPermissionRequestedEvent {
+    type: 'permission.requested';
+    requestId: string;
+    itemId?: string;
+    title: string;
+    options: PermissionOption[];
+}
+/** RESERVED — the counterpart resolution (see `permission.requested`). */
+export interface UiPermissionResolvedEvent {
+    type: 'permission.resolved';
+    requestId: string;
+    optionId: string;
+}
+/**
+ * Cumulative-for-session raw telemetry.
+ * claude: `result.usage` + `total_cost_usd`; codex:
+ * `thread/tokenUsage/updated` (cost stays absent); opencode:
+ * `message.updated` tokens/cost + `step-finish` increments.
+ */
+export interface UiUsageUpdatedEvent {
+    type: 'usage.updated';
+    usage: TokenUsage;
+    costUsd?: number;
+}
+/**
+ * An image emitted mid-stream (kept from v1) — raw base64 on the wire here;
+ * the run manager persists it and re-emits a URL. claude: image blocks in
+ * `tool_result` (with `itemId` linking back to the tool item).
+ */
+export interface UiImageEvent {
+    type: 'image';
+    itemId?: string;
+    mediaType: string;
+    data: string;
+}
+export type UiEvent = UiSessionStartedEvent | UiSessionEndedEvent | UiSessionErrorEvent | UiTurnStartedEvent | UiTurnCompletedEvent | UiItemStartedEvent | UiItemDeltaEvent | UiItemUpdatedEvent | UiItemCompletedEvent | UiPlanUpdatedEvent | UiPermissionRequestedEvent | UiPermissionResolvedEvent | UiUsageUpdatedEvent | UiImageEvent;
+/** Every v2 event discriminator — `satisfies Record<UiEventType, …>` maps
+ *  downstream keep new event types honest at compile time. */
+export type UiEventType = UiEvent['type'];

package/dist/core/ui-events.js

@@ -0,0 +1,25 @@
+/**
+ * Normalized agent-event protocol v2 — the shared vocabulary every runner
+ * emits ALONGSIDE the v1 `AgentEvent` stream (never replacing it; mixed
+ * NDJSON files stay valid — old recordings must keep replaying).
+ *
+ * Contract sources (authoritative, in this order):
+ *  - `.ai/analysis/cockpit-ui-redesign/agent-event-protocols.md` §7 (schema)
+ *    and §7.1 (per-backend mapping tables);
+ *  - the spec `.ai/specs/2026-07-14-cockpit-ui-redesign.md`
+ *    §"Normalized agent-event protocol v2".
+ *
+ * Design rules baked in:
+ *  1. Item-lifecycle model (Codex/ACP style): one stable `id` per item with
+ *     started/delta/updated/completed phases — two of the three backends are
+ *     natively item-shaped and claude maps trivially.
+ *  2. ACP vocabulary wherever a choice is arbitrary (tool status/kind, plan
+ *     entries, diff shape, stop reasons) for ecosystem alignment.
+ *  3. Every v1 `AgentEvent` stays derivable from this stream, so consumers
+ *     can migrate one panel at a time.
+ *
+ * This module is pure vocabulary: no runtime imports, no runner coupling.
+ * Step 2.4 mirrors it into `web/app/src/protocol/`.
+ */
+export {};
+//# sourceMappingURL=ui-events.js.map

package/dist/core/ui-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-events.js","sourceRoot":"","sources":["../../src/core/ui-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}

package/dist/pack-check.d.ts

@@ -0,0 +1,17 @@
+/** Tarball bundle check — the pure half of `scripts/check-pack.mjs`.
+ *
+ *  Phase R1 of the cockpit redesign shipped an npm tarball with no UI in it
+ *  (`files` listed the sources, not the Vite build). This module pins that bug
+ *  class: given the file list `npm pack --dry-run --json` reports, decide
+ *  whether the package would ship a working cockpit. Kept dependency-free and
+ *  side-effect-free so the decision is unit-testable; the script owns the
+ *  `npm pack` invocation and the exit code.
+ */
+/** Human-readable problems with a would-be tarball; empty array = publishable.
+ *
+ *  Requirements (spec `.ai/specs/2026-07-14-cockpit-ui-redesign.md`, Serving):
+ *  - `web/dist/index.html` — the built shell every GET serves.
+ *  - at least one `web/dist/assets/*` file — the hashed JS/CSS bundles; an
+ *    index.html alone renders a blank page.
+ */
+export declare function findPackGaps(packedFiles: readonly string[]): string[];

package/dist/pack-check.js

@@ -0,0 +1,27 @@
+/** Tarball bundle check — the pure half of `scripts/check-pack.mjs`.
+ *
+ *  Phase R1 of the cockpit redesign shipped an npm tarball with no UI in it
+ *  (`files` listed the sources, not the Vite build). This module pins that bug
+ *  class: given the file list `npm pack --dry-run --json` reports, decide
+ *  whether the package would ship a working cockpit. Kept dependency-free and
+ *  side-effect-free so the decision is unit-testable; the script owns the
+ *  `npm pack` invocation and the exit code.
+ */
+/** Human-readable problems with a would-be tarball; empty array = publishable.
+ *
+ *  Requirements (spec `.ai/specs/2026-07-14-cockpit-ui-redesign.md`, Serving):
+ *  - `web/dist/index.html` — the built shell every GET serves.
+ *  - at least one `web/dist/assets/*` file — the hashed JS/CSS bundles; an
+ *    index.html alone renders a blank page.
+ */
+export function findPackGaps(packedFiles) {
+    const gaps = [];
+    if (!packedFiles.includes('web/dist/index.html')) {
+        gaps.push('web/dist/index.html is missing — the tarball would ship no UI shell (run `npm run build:web`)');
+    }
+    if (!packedFiles.some((f) => f.startsWith('web/dist/assets/') && f.length > 'web/dist/assets/'.length)) {
+        gaps.push('no web/dist/assets/* bundle in the tarball — the shell would load with no JS/CSS');
+    }
+    return gaps;
+}
+//# sourceMappingURL=pack-check.js.map

package/dist/pack-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack-check.js","sourceRoot":"","sources":["../src/pack-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,WAA8B;IACzD,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC;QACjD,IAAI,CAAC,IAAI,CAAC,+FAA+F,CAAC,CAAC;IAC7G,CAAC;IACD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;QACvG,IAAI,CAAC,IAAI,CAAC,kFAAkF,CAAC,CAAC;IAChG,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/runs/title-summary.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Auto-summary titles (#389): derive a short display title for a run from the
+ * text of an agent turn. Pure by design — the RunManager calls this on
+ * turn-end and stores the first informative answer as `RunRecord.titleSummary`.
+ *
+ * Honest absence beats a garbage title: when the turn text yields nothing
+ * better than the raw task's first line (too short, markdown noise only,
+ * or a verbatim echo of the task), the answer is `undefined` and the UI
+ * keeps showing the raw `title`.
+ */
+/**
+ * Derive a display title from an agent turn's text, or `undefined` when the
+ * text yields nothing more informative than the task itself.
+ */
+export declare function deriveTitleSummary(text: string, task: string): string | undefined;

package/dist/runs/title-summary.js

@@ -0,0 +1,84 @@
+/**
+ * Auto-summary titles (#389): derive a short display title for a run from the
+ * text of an agent turn. Pure by design — the RunManager calls this on
+ * turn-end and stores the first informative answer as `RunRecord.titleSummary`.
+ *
+ * Honest absence beats a garbage title: when the turn text yields nothing
+ * better than the raw task's first line (too short, markdown noise only,
+ * or a verbatim echo of the task), the answer is `undefined` and the UI
+ * keeps showing the raw `title`.
+ */
+/** Display cap, in code points — matches `makeTitle`'s 80-char convention. */
+const MAX_LEN = 80;
+/** A summary shorter than this many words says nothing — skip it. */
+const MIN_WORDS = 4;
+/** Conversational lead-ins that carry no information about the task. Applied
+ *  repeatedly, so "Sure! I'll go ahead and fix …" strips down to "fix …". */
+const FLUFF_RES = [
+    /^(?:sure|okay|ok|alright|great|certainly|understood|got it|sounds good|of course)[,.!:]*\s+/i,
+    /^(?:i(?:'|’)?ll|i will|i(?:'|’)?m going to|i(?:'|’)?m about to|let me|let(?:'|’)?s|first,?|now,?)\s+/i,
+    /^(?:go ahead and|start by|begin by)\s+/i,
+];
+/** Strip inline markdown emphasis/code from one line. */
+function stripInlineMarkdown(line) {
+    return line
+        .replace(/^#{1,6}\s+/, '') // heading marker
+        .replace(/^(?:[-*+]|\d+[.)])\s+/, '') // list marker
+        .replace(/^>\s+/, '') // blockquote marker
+        .replace(/\*\*([^*]+)\*\*/g, '$1')
+        .replace(/__([^_]+)__/g, '$1')
+        .replace(/\*([^*]+)\*/g, '$1')
+        .replace(/(^|[\s(])_([^_]+)_(?=[\s).,;:!?]|$)/g, '$1$2') // word-bound _emphasis_, not snake_case
+        .replace(/`([^`]*)`/g, '$1')
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1') // [text](url) → text
+        .trim();
+}
+/**
+ * First sentence of `s`. Sentence end = `.`/`!`/`?` followed by whitespace or
+ * end of string — so dots inside paths (`src/store.ts`) don't cut it short.
+ */
+function firstSentence(s) {
+    const match = /^(.*?[.!?])(?:\s|$)/.exec(s);
+    return (match?.[1] ?? s).replace(/[.!?]+$/, '').trim();
+}
+/**
+ * Derive a display title from an agent turn's text, or `undefined` when the
+ * text yields nothing more informative than the task itself.
+ */
+export function deriveTitleSummary(text, task) {
+    // Fenced code blocks are never titles — drop them (incl. an unclosed one).
+    const withoutFences = text.replace(/```[\s\S]*?(?:```|$)/g, '\n');
+    const line = withoutFences
+        .split('\n')
+        .map((l) => stripInlineMarkdown(l))
+        .find((l) => l.length > 0);
+    if (!line)
+        return undefined;
+    // Fluff first, sentence second: "Sure! I'll fix …" — the fluff IS the
+    // first sentence, so stripping after extraction would keep only "Sure".
+    let s = line;
+    for (let stripped = true; stripped;) {
+        stripped = false;
+        for (const re of FLUFF_RES) {
+            const next = s.replace(re, '');
+            if (next !== s) {
+                s = next;
+                stripped = true;
+            }
+        }
+    }
+    s = firstSentence(s.trim());
+    // Cap by code points, not UTF-16 units — no split surrogate pairs.
+    const chars = [...s];
+    if (chars.length > MAX_LEN)
+        s = `${chars.slice(0, MAX_LEN - 1).join('').trimEnd()}…`;
+    // Informative? More than a few words, and not an echo of the task.
+    if (s.split(/\s+/).filter(Boolean).length < MIN_WORDS)
+        return undefined;
+    const taskFirstLine = (task.trim().split('\n')[0] ?? '').trim().toLowerCase();
+    if (s.toLowerCase() === taskFirstLine)
+        return undefined;
+    const first = [...s][0] ?? '';
+    return first.toUpperCase() + s.slice(first.length);
+}
+//# sourceMappingURL=title-summary.js.map

package/dist/runs/title-summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"title-summary.js","sourceRoot":"","sources":["../../src/runs/title-summary.ts"],"names":[],"mappings":"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"}

package/dist/runs/ui-event-sink.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Protocol-v2 persistence + fan-out policy for one agent session — the
+ * RunManager feeds every `UiEvent` a runner emits (`SessionOptions.onUiEvent`)
+ * through one sink instance and the sink decides, per the spec's performance
+ * guardrails (§"Normalized agent-event protocol v2" and
+ * `.ai/analysis/cockpit-ui-redesign/protocol-rationale-and-performance.md` §5):
+ *
+ *  - `item.delta` is COALESCED per item (~40 ms flush) onto the live wire
+ *    only — raw deltas NEVER hit the NDJSON file; replay needs no delta
+ *    reduction because every item's final state rides `item.completed`.
+ *  - Everything else persists as snapshots via `persist()` (the store stamps
+ *    `seq`/`ts`, and `appendEvent` already fans persisted lines out live, so
+ *    a persisted event is never double-emitted here).
+ *  - `item.updated` hits disk only on a meaningful change (status flip, new
+ *    diffs/title/…) — streamed-content-only growth goes to the live wire
+ *    ephemerally, mirroring what the deltas already carry.
+ *  - `usage.updated` is cumulative per session: persisted only when the
+ *    total (or cost) actually moved, mirroring v1's token-usage cadence.
+ *
+ * Output errors are swallowed: v2 is additive and best-effort — a persist
+ * failure (e.g. the run was deleted mid-flush) must never disturb the v1
+ * stream or crash a timer callback.
+ */
+import type { StopReason, UiEvent } from '../core/ui-events.js';
+/** Spec guardrail: coalesce `item.delta` at ~30–50 ms boundaries. */
+export declare const DELTA_FLUSH_MS = 40;
+/**
+ * v2 lines share the NDJSON file and the store's event bus with v1, but ride
+ * a DIFFERENT SSE event name (`ui-event` vs `run-event`) so the legacy UI —
+ * which knew only `run-event` and JSON-dumped unknown types into the
+ * transcript; retired in R7, but the name split stays as wire shape — never
+ * saw them. The discriminator is the dotted namespace:
+ * every v2 type on the wire is dotted (`item.started`, `turn.completed`, …)
+ * and no v1 type is. v2's only undotted type, `image`, never reaches the
+ * store: the sink drops it in favor of the v1 image pipeline (which persists
+ * the file and re-emits a URL instead of raw base64).
+ */
+export declare function isV2WireEventType(type: string): boolean;
+/** A loose event as the store consumes it (the sink adds no seq/ts — the
+ *  store stamps those). */
+type WireEvent = {
+    type: string;
+    [key: string]: unknown;
+};
+export interface UiEventSinkOutput {
+    /** Append to the run's NDJSON file (which also fans out live). */
+    persist(event: WireEvent): void;
+    /** Fan out live only — never written to disk (coalesced deltas). */
+    emitLive(event: WireEvent): void;
+}
+export declare class UiEventSink {
+    private readonly out;
+    private readonly flushMs;
+    /** Pending delta text per open item, per streamed field (insertion order
+     *  preserved so a flush replays fields in first-arrival order). */
+    private readonly buffers;
+    private readonly timers;
+    /** Last persisted non-streamed shape per item — the `item.updated`
+     *  meaningful-change filter. */
+    private readonly shapes;
+    private lastUsage;
+    private ended;
+    constructor(out: UiEventSinkOutput, flushMs?: number);
+    /** Fold one runner-emitted v2 event into the persist/live outputs. */
+    handle(event: UiEvent): void;
+    /**
+     * Session close, called by the RunManager exactly once when the v1 session
+     * settles: flush everything, then persist v2 `session.error` (fatal) when
+     * the session failed, and `session.ended` — the v2 counterparts of v1's
+     * `done`/`error`, which the mappers deliberately left to the RunManager.
+     */
+    sessionEnded(reason: StopReason, errorMessage?: string): void;
+    /** Flush every open coalescer now (turn end, session settle). */
+    flushAll(): void;
+    private bufferDelta;
+    /** Emit one merged `item.delta` per buffered field of the item, live only. */
+    private flushItem;
+    private persist;
+    private emitLive;
+}
+export {};