pi-crew 0.9.53 → 0.9.55

package/src/ui/key-utils.ts

@@ -0,0 +1,42 @@
+/**
+ * key-utils.ts — Centralised key matching helpers.
+ *
+ * Pi 0.81+'s TUI input layer (`@earendil-works/pi-tui`) ships a `matchesKey()`
+ * helper that handles multiple terminal key encodings: legacy CSI escapes
+ * (`\x1b[A`), application cursor mode (`\x1bOA`), and Kitty keyboard protocol
+ * variants. Pi-crew components previously compared against raw escape bytes
+ * (`data === "\x1b[A"`), which silently failed on terminals that emit the
+ * alternate encodings. This module wraps `matchesKey` with a single
+ * `keyOf()` helper so overlay code reads naturally while picking up the
+ * terminal-aware match logic for free.
+ *
+ * Returns the canonical KeyId when matchesKey recognises it, otherwise the
+ * raw input string so callers can fall through to ASCII-letter shortcuts.
+ */
+import { type KeyId, matchesKey } from "@earendil-works/pi-tui";
+
+export type PiKeyName = KeyId | string;
+
+const COMMON_IDS: readonly KeyId[] = [
+	"up",
+	"down",
+	"left",
+	"right",
+	"enter",
+	"escape",
+	"tab",
+	"shift+tab",
+	"space",
+	"backspace",
+	"home",
+	"end",
+	"pageUp",
+	"pageDown",
+];
+
+export function keyOf(data: string): KeyId | string {
+	for (const id of COMMON_IDS) {
+		if (matchesKey(data, id)) return id;
+	}
+	return data;
+}

package/src/ui/keybinding-map.ts

@@ -0,0 +1,248 @@
+/**
+ * Dashboard keybinding map (L2 refactor: data-driven dispatch).
+ *
+ * Before L2 this module exposed `DASHBOARD_KEYS` (a data table) but dispatched
+ * via a 30-line `if (includes(...)) return "..."` chain — adding a key meant
+ * editing BOTH the table AND the dispatch, a DRY violation. L2 collapses the
+ * dispatch into a single `for (const b of BINDINGS)` loop driven by the
+ * `BINDINGS` table below. `DASHBOARD_KEYS` is retained as the raw key data so
+ * existing imports and the dead-but-intentional `KEY_RESERVED` set keep working.
+ *
+ * Recalibration vs. the original L2 plan: the plan also called for an
+ * `inTextInput` guard to prevent letter-key leaks into TUI text inputs.
+ * Verified during implementation that this is NOT needed — overlays are
+ * mutually exclusive and each has its own `handleInput`. `mailbox-compose-overlay.ts:111`
+ * captures every single-char key via `appendText(data)` and never delegates to
+ * `dashboardActionForKey`, so there is no leak path. Adding the guard would
+ * complicate the API (`run-dashboard.ts:485` has no text-input state to pass)
+ * for zero benefit. The input-guard half of L2 is therefore intentionally
+ * skipped; only the DRY/data-driven dispatch refactor landed.
+ *
+ * Origin pattern: deer-flow `frontend/src/components/workspace/command-palette.tsx:39-50`
+ * drives shortcuts from a single data array consumed by one loop in
+ * `use-global-shortcuts.ts:38-61`.
+ */
+
+import { type KeyId, matchesKey } from "@earendil-works/pi-tui";
+import { keyOf } from "./key-utils.ts";
+
+export const DASHBOARD_KEYS = {
+	close: ["q", "escape", "\u001b"],
+	select: ["enter", "s", "\r", "\n", "tab", "\t", " "],
+	help: ["?"],
+	root: {
+		summary: ["u"],
+		artifacts: ["a"],
+		api: ["i"],
+		agents: ["d"],
+		mailbox: ["m"],
+		events: ["e"],
+		output: ["o"],
+		transcript: ["v"],
+		liveConversation: ["V"],
+		reload: ["r"],
+		progressToggle: ["p"],
+	},
+	pane: {
+		agents: ["1"],
+		progress: ["2"],
+		mailbox: ["3"],
+		output: ["4"],
+		health: ["5"],
+		metrics: ["6"],
+	},
+	navigation: { up: ["k", "up"], down: ["j", "down"] },
+	mailbox: {
+		ack: ["A"],
+		nudge: ["N"],
+		compose: ["C"],
+		preview: ["P"],
+		ackAll: ["X"],
+		openDetail: ["\r", "\n"],
+	},
+	health: { recovery: ["R"], killStale: ["K"], diagnosticExport: ["D"] },
+	notification: { dismissAll: ["H"] },
+} as const;
+
+/**
+ * Pane identifiers that can scope a binding. `undefined` means the binding
+ * fires in every pane.
+ */
+export type ActivePane = "agents" | "progress" | "mailbox" | "output" | "health" | "metrics";
+
+/**
+ * A single keybinding: the keys that trigger it, the action it produces, and
+ * an optional pane restriction. The dispatch loop returns the FIRST matching
+ * binding, so table ORDER IS SIGNIFICANT and must mirror the old if-chain
+ * precedence (pane-specific overrides before their generic competitors).
+ */
+export interface KeyBinding {
+	readonly keys: readonly string[];
+	readonly action: DashboardKeyAction;
+	/** When set, the binding only fires when `activePane === pane`. */
+	readonly pane?: ActivePane;
+}
+
+export type DashboardKeyAction =
+	| "close"
+	| "help"
+	| "select"
+	| "summary"
+	| "artifacts"
+	| "api"
+	| "agents"
+	| "mailbox"
+	| "events"
+	| "output"
+	| "transcript"
+	| "live-conversation"
+	| "reload"
+	| "progressToggle"
+	| "pane-agents"
+	| "pane-progress"
+	| "pane-mailbox"
+	| "pane-output"
+	| "pane-health"
+	| "pane-metrics"
+	| "up"
+	| "down"
+	| "mailbox-detail"
+	| "health-recovery"
+	| "health-kill-stale"
+	| "health-diagnostic-export"
+	| "notifications-dismiss";
+
+/**
+ * The dispatch table. ORDER MATTERS — first match wins.
+ *
+ * Precedence notes (must match the pre-L2 if-chain exactly):
+ *   1. `close` always wins (q / Esc).
+ *   2. `mailbox-detail` (\r, \n) is pane-scoped to mailbox and MUST precede
+ *      `select` (which also binds \r, \n) so Enter opens the detail instead of
+ *      triggering select while in the mailbox pane.
+ *   3. `health-*` are pane-scoped to health.
+ *   4. `notifications-dismiss` (H) is global.
+ *   5. `select`, then the root actions, pane switches, and navigation.
+ *
+ * NOTE: mailbox action keys A/N/C/P/X (ack/nudge/compose/preview/ackAll) are
+ * intentionally NOT in this table. They live in `DASHBOARD_KEYS.mailbox` for
+ * reservation but are handled by the mailbox overlay's own `handleInput`,
+ * not by the dashboard dispatch. Adding them here would change behavior.
+ */
+const BINDINGS: readonly KeyBinding[] = [
+	{ keys: DASHBOARD_KEYS.close, action: "close" },
+	{ keys: DASHBOARD_KEYS.help, action: "help" },
+	{
+		keys: DASHBOARD_KEYS.mailbox.openDetail,
+		action: "mailbox-detail",
+		pane: "mailbox",
+	},
+	{
+		keys: DASHBOARD_KEYS.health.recovery,
+		action: "health-recovery",
+		pane: "health",
+	},
+	{
+		keys: DASHBOARD_KEYS.health.killStale,
+		action: "health-kill-stale",
+		pane: "health",
+	},
+	{
+		keys: DASHBOARD_KEYS.health.diagnosticExport,
+		action: "health-diagnostic-export",
+		pane: "health",
+	},
+	{
+		keys: DASHBOARD_KEYS.notification.dismissAll,
+		action: "notifications-dismiss",
+	},
+	{ keys: DASHBOARD_KEYS.select, action: "select" },
+	{ keys: DASHBOARD_KEYS.root.summary, action: "summary" },
+	{ keys: DASHBOARD_KEYS.root.artifacts, action: "artifacts" },
+	{ keys: DASHBOARD_KEYS.root.api, action: "api" },
+	{ keys: DASHBOARD_KEYS.root.agents, action: "agents" },
+	{ keys: DASHBOARD_KEYS.root.mailbox, action: "mailbox" },
+	{ keys: DASHBOARD_KEYS.root.events, action: "events" },
+	{ keys: DASHBOARD_KEYS.root.output, action: "output" },
+	{ keys: DASHBOARD_KEYS.root.transcript, action: "transcript" },
+	{ keys: DASHBOARD_KEYS.root.liveConversation, action: "live-conversation" },
+	{ keys: DASHBOARD_KEYS.root.reload, action: "reload" },
+	{ keys: DASHBOARD_KEYS.root.progressToggle, action: "progressToggle" },
+	{ keys: DASHBOARD_KEYS.pane.agents, action: "pane-agents" },
+	{ keys: DASHBOARD_KEYS.pane.progress, action: "pane-progress" },
+	{ keys: DASHBOARD_KEYS.pane.mailbox, action: "pane-mailbox" },
+	{ keys: DASHBOARD_KEYS.pane.output, action: "pane-output" },
+	{ keys: DASHBOARD_KEYS.pane.health, action: "pane-health" },
+	{ keys: DASHBOARD_KEYS.pane.metrics, action: "pane-metrics" },
+	{ keys: DASHBOARD_KEYS.navigation.up, action: "up" },
+	{ keys: DASHBOARD_KEYS.navigation.down, action: "down" },
+];
+
+/**
+ * Reserved keys — every key the dashboard claims, including mailbox/health
+ * action keys that are NOT dispatched here but are handled by their own
+ * overlays. Derived from `DASHBOARD_KEYS` (the full key set) rather than from
+ * `BINDINGS` (the dispatched subset) so overlay-handled keys stay reserved.
+ *
+ * @internal Consumed by `test/unit/keybinding-map.parity.test.ts` (asserts
+ * reserved-key membership) and the L2 dispatch smoke script. It is the
+ * canonical "keys the dashboard ecosystem owns" set — NOT dead code.
+ */
+const KEY_RESERVED = new Set<string>([
+	...DASHBOARD_KEYS.close,
+	...DASHBOARD_KEYS.select,
+	...DASHBOARD_KEYS.help,
+	...Object.values(DASHBOARD_KEYS.root).flat(),
+	...Object.values(DASHBOARD_KEYS.pane).flat(),
+	...Object.values(DASHBOARD_KEYS.navigation).flat(),
+	...Object.values(DASHBOARD_KEYS.mailbox).flat(),
+	...Object.values(DASHBOARD_KEYS.health).flat(),
+	...Object.values(DASHBOARD_KEYS.notification).flat(),
+]);
+
+export { KEY_RESERVED };
+
+/**
+ * Resolve a raw input `data` string to a dashboard action.
+ *
+ * Data-driven dispatch: iterates `BINDINGS` in order and returns the action of
+ * the first binding whose `keys` contain `data` and whose optional `pane`
+ * restriction matches `activePane`. Behavior is identical to the pre-L2
+ * if-chain (verified by `test/unit/keybinding-map.parity.test.ts`).
+ *
+ * @param data Raw key input (single char or escape sequence).
+ * @param activePane Currently focused pane; pane-scoped bindings only fire
+ *                   when this matches. `undefined` disables all pane-scoped
+ *                   bindings (matching the old behavior where omitting the
+ *                   arg skipped the `activePane === ...` branches).
+ */
+export function dashboardActionForKey(data: string, activePane?: ActivePane): DashboardKeyAction | undefined {
+	// Two-pass dispatch to preserve case-sensitivity for plain ASCII keys
+	// while still normalizing escape sequences via matchesKey().
+	//
+	// Background: pi-tui's matchesKey() is case-insensitive, so matchesKey("d",
+	// "D") === true. A single-pass loop that intermixes exact + matchesKey
+	// checks would let the pane-scoped health-diagnostic-export binding
+	// (candidate "D") win over the unscoped agents binding (candidate "d")
+	// when activePane === "health" — collapsing the d/D case distinction.
+	//
+	// Pass 1 — exact string match (case-sensitive). Handles literal ASCII
+	// keystrokes ('d', 'D', 'q', 'S', …) and preserves their distinct meanings.
+	for (const binding of BINDINGS) {
+		if (binding.pane !== undefined && binding.pane !== activePane) continue;
+		if (binding.keys.includes(data)) return binding.action;
+	}
+	// Pass 2 — terminal-aware match for escape sequences / canonical KeyIds.
+	// Only reached when no exact ASCII match exists (data is e.g. '\x1b[A',
+	// '\x1bOA', or an app-cursor-mode variant). Uses matchesKey() to normalize
+	// legacy CSI, app-cursor-mode, and Kitty-protocol variants uniformly.
+	const key = keyOf(data);
+	for (const binding of BINDINGS) {
+		if (binding.pane !== undefined && binding.pane !== activePane) continue;
+		for (const candidate of binding.keys) {
+			if (key === candidate) return binding.action;
+			if (matchesKey(data, candidate as KeyId)) return binding.action;
+		}
+	}
+	return undefined;
+}

package/src/ui/layout-primitives.ts

@@ -0,0 +1,106 @@
+import { pad, wrapHard } from "../utils/visual.ts";
+
+export interface RenderableComponent {
+	invalidate(): void;
+	render(width: number): string[];
+}
+
+export class Container implements RenderableComponent {
+	private children: RenderableComponent[] = [];
+
+	addChild(child: RenderableComponent): void {
+		this.children.push(child);
+	}
+
+	clear(): void {
+		this.children = [];
+	}
+
+	invalidate(): void {
+		for (const child of this.children) {
+			child.invalidate();
+		}
+	}
+
+	render(width: number): string[] {
+		const lines: string[] = [];
+		for (const child of this.children) {
+			lines.push(...child.render(width));
+		}
+		return lines;
+	}
+}
+
+export class Box extends Container {
+	private readonly paddingX: number;
+	private readonly paddingY: number;
+
+	constructor(paddingX = 0, paddingY = 0) {
+		super();
+		this.paddingX = paddingX;
+		this.paddingY = paddingY;
+	}
+
+	render(width: number): string[] {
+		const innerWidth = Math.max(1, width - this.paddingX * 2);
+		const rows = super.render(innerWidth);
+		const paddedRows: string[] = [];
+		const left = " ".repeat(this.paddingX);
+		const right = " ".repeat(this.paddingX);
+		for (const row of rows) {
+			paddedRows.push(pad(`${left}${row}${right}`, width));
+		}
+		const emptyRow = pad("", width);
+		if (this.paddingY <= 0) return paddedRows;
+		if (this.paddingY > 0) {
+			const topAndBottom = Array.from({ length: this.paddingY }, () => emptyRow);
+			return [...topAndBottom, ...paddedRows, ...topAndBottom];
+		}
+		return paddedRows;
+	}
+}
+
+export class Text implements RenderableComponent {
+	private text: string;
+	private cachedWidth = 0;
+	private cachedResult: string[] = [];
+
+	constructor(text = "") {
+		this.text = text;
+	}
+
+	setText(text: string): void {
+		if (text === this.text) return;
+		this.text = text;
+		this.invalidate();
+	}
+
+	invalidate(): void {
+		this.cachedWidth = 0;
+		this.cachedResult = [];
+	}
+
+	render(width: number): string[] {
+		if (this.cachedWidth === width) return this.cachedResult;
+		const wrapped = wrapHard(this.text, Math.max(1, width));
+		const lines = wrapped.length ? wrapped : [""];
+		this.cachedWidth = width;
+		this.cachedResult = lines.map((line) => pad(line, width));
+		return this.cachedResult;
+	}
+}
+
+export class Spacer implements RenderableComponent {
+	private readonly rows: number;
+
+	constructor(rows = 0) {
+		this.rows = rows;
+	}
+
+	render(width: number): string[] {
+		if (this.rows <= 0) return [];
+		return Array.from({ length: Math.max(0, this.rows) }, () => pad("", width));
+	}
+
+	invalidate(): void {}
+}

package/src/ui/live-conversation-overlay.ts

@@ -0,0 +1,183 @@
+/**
+ * live-conversation-overlay.ts — Live conversation overlay for viewing live-session agent output.
+ *
+ * R8: Subscribes to session events for real-time streaming updates.
+ * Falls back to polling LiveAgentHandle.activity when subscribe is unavailable.
+ */
+import type { LiveAgentHandle } from "../runtime/live-agent-manager.ts";
+import { pad, truncate } from "../utils/visual.ts";
+import { computeLiveDurationMs } from "./live-duration.ts";
+import { spinnerFrame } from "./spinner.ts";
+import { iconForStatus } from "./status-colors.ts";
+import type { CrewTheme } from "./theme-adapter.ts";
+
+const CHROME_LINES = 6;
+const MIN_VIEWPORT = 3;
+
+export class LiveConversationOverlay {
+	private scrollOffset = 0;
+	private autoScroll = true;
+	private closed = false;
+	private pollTimer: ReturnType<typeof setInterval> | undefined;
+	cachedLines: string[] = [];
+	// H-4 fix (code-review 2026-06-23): cap the in-memory line buffer to avoid
+	// unbounded growth (OOM) during long-running live sessions. Oldest lines are
+	// dropped first; scrollOffset is adjusted to keep the viewport stable.
+	static readonly MAX_CACHED_LINES = 5000;
+	private columns: number;
+	private rows: number;
+	private unsubscribe: (() => void) | undefined;
+
+	private handle: LiveAgentHandle;
+	private theme: CrewTheme;
+
+	constructor(handle: LiveAgentHandle, theme: CrewTheme, columns = 80, rows = 24) {
+		this.handle = handle;
+		this.theme = theme;
+		this.columns = columns;
+		this.rows = rows;
+		// R8: Subscribe to real session events if available
+		const session = handle.session as Record<string, unknown>;
+		if (typeof session.subscribe === "function") {
+			try {
+				this.unsubscribe = (session.subscribe as (cb: (event: unknown) => void) => () => void)((event) => {
+					if (this.closed) return;
+					const obj = event as Record<string, unknown>;
+					const text = typeof obj.text === "string" ? obj.text : typeof obj.content === "string" ? obj.content : "";
+					if (text.trim()) {
+						this.pushLine(text);
+						if (this.autoScroll) this.scrollOffset = Math.max(0, this.cachedLines.length - this.viewportHeight());
+					}
+				});
+			} catch {
+				/* ignore */
+			}
+		}
+		// Also poll for summary updates. Skip when the user has scrolled up
+		// (autoScroll === false): the summary refresh also bumps scrollOffset
+		// to the tail, which would yank the viewport out from under them.
+		this.pollTimer = setInterval(() => {
+			if (this.closed) return;
+			if (!this.autoScroll) return;
+			try {
+				this.refreshSummary();
+			} catch {
+				/* ignore */
+			}
+		}, 200);
+		this.pollTimer.unref();
+		try {
+			this.refreshSummary();
+		} catch {
+			/* ignore */
+		}
+	}
+
+	private pushLine(line: string): void {
+		this.cachedLines.push(line);
+		if (this.cachedLines.length > LiveConversationOverlay.MAX_CACHED_LINES) {
+			const drop = this.cachedLines.length - LiveConversationOverlay.MAX_CACHED_LINES;
+			this.cachedLines.splice(0, drop);
+			this.scrollOffset = Math.max(0, this.scrollOffset - drop);
+		}
+	}
+
+	private static readonly SUMMARY_PREFIX = "\u200B"; // zero-width space as summary sentinel
+
+	private refreshSummary(): void {
+		const act = this.handle.activity;
+		const summary = `${LiveConversationOverlay.SUMMARY_PREFIX}[${act.turnCount} turns · ${act.toolUses} tools · ${(computeLiveDurationMs(act) / 1000).toFixed(1)}s]`;
+		const lastLine = this.cachedLines[this.cachedLines.length - 1];
+		if (lastLine?.startsWith(LiveConversationOverlay.SUMMARY_PREFIX)) {
+			this.cachedLines[this.cachedLines.length - 1] = summary;
+		} else {
+			this.pushLine(summary);
+		}
+		if (this.autoScroll) this.scrollOffset = Math.max(0, this.cachedLines.length - this.viewportHeight());
+	}
+
+	private viewportHeight(): number {
+		return Math.max(MIN_VIEWPORT, this.rows - CHROME_LINES);
+	}
+
+	render(width?: number): string[] {
+		const w = width ?? this.columns;
+		if (w < 6) return [];
+		const th = this.theme;
+		const innerW = w - 4;
+		const row = (content: string) => th.fg("border", "│") + " " + pad(truncate(content, innerW), innerW) + " " + th.fg("border", "│");
+		const hrTop = th.fg("border", `╭${"─".repeat(w - 2)}╮`);
+		const hrBot = th.fg("border", `╰${"─".repeat(w - 2)}╯`);
+		const hrMid = row(th.fg("dim", "─".repeat(innerW)));
+
+		const lines: string[] = [];
+		lines.push(hrTop);
+
+		// Header
+		const statusIcon =
+			this.handle.status === "running"
+				? th.fg("accent", spinnerFrame(this.handle.taskId ?? this.handle.agentId))
+				: iconForStatus(this.handle.status);
+		const name = this.handle.agent ?? this.handle.taskId;
+		const act = this.handle.activity;
+		const elapsed = `${(computeLiveDurationMs(act) / 1000).toFixed(1)}s`;
+		const headerParts: string[] = [];
+		if (act.maxTurns != null) headerParts.push(`turn ${act.turnCount}/${act.maxTurns}`);
+		else if (act.turnCount > 0) headerParts.push(`turn ${act.turnCount}`);
+		if (act.toolUses > 0) headerParts.push(`${act.toolUses} tools`);
+		headerParts.push(elapsed);
+
+		// Context % + compaction
+		try {
+			const ctxPct = this.handle.session.getSessionStats?.()?.contextUsage?.percent;
+			if (ctxPct != null) {
+				const color = ctxPct >= 85 ? "error" : ctxPct >= 70 ? "warning" : "dim";
+				headerParts.push(th.fg(color, `${Math.round(ctxPct)}% ctx`));
+			}
+		} catch {
+			/* ignore */
+		}
+		if (act.compactionCount > 0) headerParts.push(th.fg("dim", `↻${act.compactionCount}`));
+		// Model name
+		if (this.handle.modelName) headerParts.push(th.fg("muted", this.handle.modelName));
+
+		const desc = this.handle.description ?? this.handle.role ?? "";
+		lines.push(
+			row(
+				`${statusIcon} ${th.fg("accent", name)}  ${th.fg("muted", desc)} ${th.fg("dim", "·")} ${th.fg("dim", headerParts.join(" · "))}`,
+			),
+		);
+		lines.push(hrMid);
+
+		// Content
+		const vh = this.viewportHeight();
+		const visible = this.cachedLines.slice(this.scrollOffset, this.scrollOffset + vh);
+		for (const line of visible) {
+			lines.push(row(th.fg("dim", line)));
+		}
+
+		// Footer
+		lines.push(hrMid);
+		const footerText = this.autoScroll
+			? "auto-scroll · esc/q close"
+			: `line ${this.scrollOffset + 1}/${this.cachedLines.length} · ↑/k ↓/j G/g · esc/q close`;
+		lines.push(row(th.fg("dim", footerText)));
+		lines.push(hrBot);
+		return lines;
+	}
+
+	close(): void {
+		if (this.closed) return;
+		this.closed = true;
+		this.unsubscribe?.();
+		this.unsubscribe = undefined;
+		if (this.pollTimer) {
+			clearInterval(this.pollTimer);
+			this.pollTimer = undefined;
+		}
+	}
+
+	dispose(): void {
+		this.close();
+	}
+}

package/src/ui/live-duration.ts

@@ -0,0 +1,55 @@
+/**
+ * Round 23 (BUG 1 fix): live-agent duration computation.
+ *
+ * The naive `(completedAtMs ?? Date.now()) - startedAtMs` produced giant
+ * NEGATIVE durations for every running live agent whenever startedAtMs was
+ * 0/undefined/out-of-range, or a race set completedAtMs < startedAtMs.
+ *
+ * This module consolidates the validated duration math (previously duplicated
+ * between widget-formatters.ts and agents-pane.ts) into one pure, fully
+ * testable function: it normalizes seconds-vs-ms, sanity-checks the start
+ * timestamp against the current time, and never returns a negative value.
+ */
+
+export interface LiveActivity {
+	startedAtMs?: number;
+	completedAtMs?: number;
+}
+
+/** Normalize a raw timestamp that may be seconds or milliseconds. */
+function toMs(v: number): number {
+	if (v <= 0) return 0;
+	// 1e9 < seconds < 1e10  → seconds, scale up
+	if (v > 1_000_000_000 && v < 10_000_000_000) return v * 1000;
+	// 1e10 < ms < 1e13      → already ms (>=10B seconds is 317+ years, implausible)
+	if (v > 10_000_000_000 && v < 10_000_000_000_000) return v;
+	return v;
+}
+
+/**
+ * Compute the live elapsed duration in milliseconds for an agent activity.
+ *
+ * - Never negative (clamped to >= 0).
+ * - Returns 0 if the start timestamp is missing or implausible.
+ * - Uses `completedAtMs` when present and sane; otherwise `nowMs` (running).
+ *
+ * @param activity the live agent activity handle
+ * @param nowMs    optional override for `Date.now()` (tests / determinism)
+ */
+export function computeLiveDurationMs(activity: LiveActivity, nowMs: number = Date.now()): number {
+	const rawStarted = activity.startedAtMs || 0;
+	const rawCompleted = activity.completedAtMs || 0;
+	const startedMs = toMs(rawStarted);
+	const completedMs = rawCompleted > 0 ? toMs(rawCompleted) : 0;
+	// A valid start is positive, not more than 1 minute in the future, and not
+	// more than ~1000 years in the past (guards against 0 / garbage / clock skew).
+	const isValidStarted = startedMs > 0 && startedMs < nowMs + 60_000 && startedMs > nowMs - 31_556_926_000_000;
+	const end = completedMs > 0 && completedMs < nowMs + 60_000 ? completedMs : nowMs;
+	const ms = end - (isValidStarted ? startedMs : nowMs);
+	return Number.isFinite(ms) && ms >= 0 ? ms : 0;
+}
+
+/** Format a live duration in seconds, e.g. `12.3s`. Returns `0.0s` for 0. */
+export function formatLiveDuration(activity: LiveActivity, nowMs: number = Date.now()): string {
+	return `${(computeLiveDurationMs(activity, nowMs) / 1000).toFixed(1)}s`;
+}