@signal9/era-ui 4.6.0 → 4.7.0

package/dist/ai/swarm/swarm-tree.svelte

@@ -0,0 +1,201 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { cn } from '../../utils/index.js';
+	import Node from './swarm-node.svelte';
+	import { buildSwarmTree, type SwarmAgent, type SwarmNode } from './swarm.js';
+
+	let {
+		ref = $bindable(null),
+		agents = [],
+		expandable,
+		detail,
+		meta,
+		empty,
+		onToggle,
+		class: className,
+		...restProps
+	}: Omit<HTMLAttributes<HTMLDivElement>, 'children'> & {
+		ref?: HTMLDivElement | null;
+		/** The swarm's agents, flat. The tree is built from each one's `parentId`. */
+		agents?: SwarmAgent[];
+		/**
+		 * Which rows can expand beyond their children. Defaults to "every row,
+		 * once a detail snippet exists" — pass a predicate when the detail is empty
+		 * for some agents, so those rows don't get a chevron that opens nothing.
+		 */
+		expandable?: (agent: SwarmAgent) => boolean;
+		/** Expanded body for a row — artifacts, a transcript, tool output. */
+		detail?: Snippet<[SwarmAgent]>;
+		/** Trailing row content, rendered before the elapsed readout. */
+		meta?: Snippet<[SwarmAgent]>;
+		/** Replaces the built-in "no agents yet" line. */
+		empty?: Snippet;
+		/** Fired when a row expands or collapses, with that agent. */
+		onToggle?: (agent: SwarmAgent, open: boolean) => void;
+	} = $props();
+
+	const tree = $derived(buildSwarmTree(agents));
+
+	/** One answer for the row, the keyboard walk, and the chevron — they must agree. */
+	const nodeExpandable = (node: SwarmNode) =>
+		node.children.length > 0 || (detail != null && (expandable?.(node.agent) ?? true));
+
+	// Rows default to OPEN and remember only what the user closed. A swarm streams
+	// in — an agent that appears three seconds from now has no entry here, and
+	// defaulting to open is what makes it visible the moment it lands instead of
+	// hiding new work inside a collapsed parent.
+	let closed = $state<Record<string, boolean>>({});
+	const isOpen = (id: string) => !closed[id];
+
+	function setOpen(agent: SwarmAgent, open: boolean) {
+		closed = { ...closed, [agent.id]: !open };
+		onToggle?.(agent, open);
+	}
+
+	/**
+	 * The visible rows, in the order the eye reads them — which is exactly the
+	 * order the arrow keys have to move through, so navigation is derived from
+	 * the same walk that renders rather than from the DOM.
+	 */
+	type Row = { id: string; parentId: string | null; expandable: boolean; open: boolean };
+	const rows = $derived.by(() => {
+		const out: Row[] = [];
+		const walk = (nodes: SwarmNode[], parentId: string | null) => {
+			for (const node of nodes) {
+				const canExpand = nodeExpandable(node);
+				const open = isOpen(node.agent.id);
+				out.push({ id: node.agent.id, parentId, expandable: canExpand, open });
+				if (canExpand && open) walk(node.children, node.agent.id);
+			}
+		};
+		walk(tree, null);
+		return out;
+	});
+
+	// Roving tabindex: exactly one row is in the tab order, and Tab out of the
+	// tree returns to it. Falls back to the first row so a freshly rendered tree
+	// is reachable at all.
+	let activeId = $state<string | null>(null);
+	const focusedId = $derived(
+		activeId && rows.some((row) => row.id === activeId) ? activeId : (rows[0]?.id ?? null)
+	);
+
+	function focusRow(id: string | undefined | null) {
+		if (!id || !ref) return;
+		activeId = id;
+		ref.querySelector<HTMLElement>(`[data-agent-id="${CSS.escape(id)}"]`)?.focus();
+	}
+
+	/** Focus follows the DOM, so clicking a row (or one of its buttons) roves too. */
+	function onfocusin(event: FocusEvent) {
+		const el = (event.target as HTMLElement | null)?.closest?.('[data-agent-id]');
+		const id = el?.getAttribute('data-agent-id');
+		if (id) activeId = id;
+	}
+
+	/**
+	 * WAI-ARIA tree navigation. Enter and Space are deliberately absent — they
+	 * activate the row, which the node itself owns (it is the thing that knows
+	 * whether there is an `onOpen` to run).
+	 */
+	function onkeydown(event: KeyboardEvent) {
+		const index = rows.findIndex((row) => row.id === focusedId);
+		const current = index >= 0 ? rows[index] : undefined;
+
+		switch (event.key) {
+			case 'ArrowDown':
+				event.preventDefault();
+				focusRow(rows[Math.min(index + 1, rows.length - 1)]?.id);
+				break;
+			case 'ArrowUp':
+				event.preventDefault();
+				focusRow(rows[Math.max(index - 1, 0)]?.id);
+				break;
+			case 'ArrowRight':
+				// Collapsed: open it. Open: step into the branch it just revealed.
+				if (!current) break;
+				event.preventDefault();
+				if (current.expandable && !current.open) {
+					const agent = agents.find((a) => a.id === current.id);
+					if (agent) setOpen(agent, true);
+				} else if (rows[index + 1]?.parentId === current.id) {
+					focusRow(rows[index + 1].id);
+				}
+				break;
+			case 'ArrowLeft':
+				// Open: close it. Closed (or a leaf): climb to the parent.
+				if (!current) break;
+				event.preventDefault();
+				if (current.expandable && current.open) {
+					const agent = agents.find((a) => a.id === current.id);
+					if (agent) setOpen(agent, false);
+				} else {
+					focusRow(current.parentId);
+				}
+				break;
+			case 'Home':
+				event.preventDefault();
+				focusRow(rows[0]?.id);
+				break;
+			case 'End':
+				event.preventDefault();
+				focusRow(rows.at(-1)?.id);
+				break;
+		}
+	}
+</script>
+
+<!-- The delegation tree. `@container` scopes the responsive rules inside to the
+     TREE's width rather than the viewport's: the same swarm renders inside a
+     narrow chat message and in a full-width console, and only the component can
+     know which one it is in. -->
+<div
+	bind:this={ref}
+	role="tree"
+	aria-label="Swarm agents"
+	{onkeydown}
+	{onfocusin}
+	class={cn('@container min-w-0 py-(--era-gap)', className)}
+	{...restProps}
+>
+	{#if rows.length === 0}
+		<div class="px-(--era-inset-md) py-(--era-gap) text-body text-muted">
+			{#if empty}{@render empty()}{:else}No agents yet.{/if}
+		</div>
+	{:else}
+		{#each tree as node (node.agent.id)}
+			{@render nodeView(node, 1)}
+		{/each}
+	{/if}
+</div>
+
+<!-- The recursion lives in a snippet rather than in the node component: the tree
+     owns expansion and focus for the whole forest (it is the only thing that
+     knows the visible order), and a self-recursing node would have to hand every
+     level a copy of that state. -->
+{#snippet nodeView(node: SwarmNode, level: number)}
+	<!-- A leaf gets NO children snippet, rather than one that renders nothing:
+	     the node reads the snippet's presence to decide whether it is expandable,
+	     so an always-passed empty group would put a dead chevron on every leaf. -->
+	{@const props = {
+		agent: node.agent,
+		level,
+		expandable: nodeExpandable(node),
+		detail,
+		meta,
+		open: isOpen(node.agent.id),
+		active: focusedId === node.agent.id,
+		tabindex: focusedId === node.agent.id ? 0 : -1,
+		onToggle: (open: boolean) => setOpen(node.agent, open)
+	}}
+	{#if node.children.length > 0}
+		<Node {...props}>
+			{#each node.children as child (child.agent.id)}
+				{@render nodeView(child, level + 1)}
+			{/each}
+		</Node>
+	{:else}
+		<Node {...props} />
+	{/if}
+{/snippet}

package/dist/ai/swarm/swarm-tree.svelte.d.ts

@@ -0,0 +1,25 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type SwarmAgent } from './swarm.js';
+type $$ComponentProps = Omit<HTMLAttributes<HTMLDivElement>, 'children'> & {
+    ref?: HTMLDivElement | null;
+    /** The swarm's agents, flat. The tree is built from each one's `parentId`. */
+    agents?: SwarmAgent[];
+    /**
+     * Which rows can expand beyond their children. Defaults to "every row,
+     * once a detail snippet exists" — pass a predicate when the detail is empty
+     * for some agents, so those rows don't get a chevron that opens nothing.
+     */
+    expandable?: (agent: SwarmAgent) => boolean;
+    /** Expanded body for a row — artifacts, a transcript, tool output. */
+    detail?: Snippet<[SwarmAgent]>;
+    /** Trailing row content, rendered before the elapsed readout. */
+    meta?: Snippet<[SwarmAgent]>;
+    /** Replaces the built-in "no agents yet" line. */
+    empty?: Snippet;
+    /** Fired when a row expands or collapses, with that agent. */
+    onToggle?: (agent: SwarmAgent, open: boolean) => void;
+};
+declare const SwarmTree: import("svelte").Component<$$ComponentProps, {}, "ref">;
+type SwarmTree = ReturnType<typeof SwarmTree>;
+export default SwarmTree;

package/dist/ai/swarm/swarm.d.ts

@@ -0,0 +1,218 @@
+/**
+ * The swarm model — the shape of a multi-agent run, and the projection logic
+ * the UI needs, with no transport attached.
+ *
+ * A swarm is one orchestrated effort: a root agent that decomposes a task,
+ * workers it delegates to, optional reviewers, and fan-in gates (barriers)
+ * where parallel branches rejoin before the work is merged into artifacts.
+ * Every real implementation streams that state as an append-only event log with
+ * a monotonic sequence number, because an hour-long run WILL outlive a socket.
+ *
+ * era ships the projection half of that contract and nothing else. The host
+ * owns the transport (oRPC, SSE, WebSocket, polling — era does not care) and
+ * feeds `SwarmController` snapshots and events; the controller owns the one
+ * invariant that makes reconnection tractable:
+ *
+ *   the view is a pure function of (snapshot at seq S, every event with seq > S)
+ *
+ * which turns "resume a live view" into a watermark comparison instead of a
+ * state-transfer negotiation. Take a snapshot, subscribe from its seq, and a
+ * dropped socket, a server restart and a browser refresh all re-enter through
+ * the same door.
+ *
+ * This module is the pure half — shapes and projections, no runes, no clock.
+ * `SwarmController` (swarm.svelte.ts) is the live half, and it is optional: a
+ * host that already holds swarm state in its own store calls these functions
+ * directly and never constructs one.
+ */
+/**
+ * What an agent was spawned to be.
+ *
+ * `orchestrator` plans and delegates (usually the root), `worker` does a
+ * delegated subtask, `reviewer` and `verifier` check other agents' output
+ * (review reads, verification re-runs), `aggregator` merges a branch's results
+ * into one artifact.
+ */
+export type SwarmRole = 'orchestrator' | 'worker' | 'reviewer' | 'verifier' | 'aggregator';
+/**
+ * An agent's lifecycle.
+ *
+ * The two waiting states are deliberately distinct, and collapsing them hides
+ * the thing you open a swarm console to diagnose: `queued` is waiting for a
+ * slot (bounded parallelism), `blocked` is waiting on someone else (a barrier
+ * or an unfinished dependency). One clears itself; the other may never.
+ */
+export type SwarmAgentStatus = 'blocked' | 'queued' | 'running' | 'done' | 'failed' | 'cancelled';
+/** The plan's own lifecycle — `active` until every branch has landed. */
+export type SwarmPlanStatus = 'active' | 'done' | 'failed' | 'cancelled';
+/** A fan-in gate: `open` while any member is still working. */
+export type SwarmBarrierStatus = 'open' | 'done' | 'failed' | 'cancelled';
+/**
+ * The stream's health, which is NOT the swarm's health — a swarm can be running
+ * perfectly while your connection to it is dead. Surfaced separately (see
+ * `Swarm.Footer`) for exactly that reason.
+ */
+export type SwarmConnection = 'idle' | 'loading' | 'live' | 'reconnecting' | 'error';
+/** The VM an agent executes in, when it has one. */
+export interface SwarmSandbox {
+    /** Provider id, shown on hover. */
+    id?: string;
+    status: 'running' | 'paused' | 'terminated';
+}
+/** One agent in the swarm. */
+export interface SwarmAgent {
+    id: string;
+    /** Who delegated this agent. Absent (or unknown) makes it a root. */
+    parentId?: string | null;
+    role?: SwarmRole;
+    /** What it was asked to do — the row's primary line. */
+    task: string;
+    status: SwarmAgentStatus;
+    /** Specialization, when the role alone is too coarse: "api", "docs", "perf". */
+    label?: string;
+    /** The plan's stable key for this task ("t3"), rendered as a tag. */
+    key?: string;
+    /** One-line outcome, shown under the task once the agent lands. */
+    result?: string;
+    /** Fan-in gate this agent reports into. */
+    barrierId?: string | null;
+    /**
+     * The agent's own transcript, when it has one. This GATES the open
+     * affordance: a row or card shows the open button only when the host has both
+     * an `onOpen` handler and an agent with somewhere to go.
+     */
+    conversationId?: string;
+    /**
+     * The agent's VM.
+     *
+     * `null` means "known to have none"; `undefined` in an EVENT means "not
+     * reported" and leaves the last known value alone (see `mergeAgent`) —
+     * sandbox lifecycle is usually not journaled as swarm events, so a value
+     * carried on every agent update would be stale by construction.
+     */
+    sandbox?: SwarmSandbox | null;
+    /** Epoch ms. `startedAt` + `endedAt` drive the elapsed readout. */
+    startedAt?: number;
+    endedAt?: number;
+}
+/** The decomposition the root agent committed to. */
+export interface SwarmPlan {
+    id?: string;
+    title: string;
+    status?: SwarmPlanStatus;
+}
+/** A fan-in gate: the point where parallel branches rejoin. */
+export interface SwarmBarrier {
+    id: string;
+    /** Short stable key ("research"), for the tag beside the title. */
+    key?: string;
+    title: string;
+    /** Omit to let `summarizeBarrier` derive it from the members. */
+    status?: SwarmBarrierStatus;
+}
+/** A summarized output: a merged finding, a report, a deliverable. */
+export interface SwarmArtifact {
+    id: string;
+    /** Which agent produced it. */
+    agentId?: string;
+    /** Set when the artifact is a barrier's merged summary. */
+    barrierId?: string | null;
+    /** Free-form producer tag ("report", "diff", "barrier_summary"). */
+    kind: string;
+    title?: string;
+    summary: string;
+    /** Epoch ms. */
+    createdAt?: number;
+}
+/** One agent plus its subtree, as `buildSwarmTree` returns it. */
+export interface SwarmNode {
+    agent: SwarmAgent;
+    /** Distance from the root, computed from the tree — never trusted from data. */
+    depth: number;
+    children: SwarmNode[];
+}
+/** Aggregate agent counts, as `summarizeSwarm` returns them. */
+export interface SwarmCounts {
+    total: number;
+    blocked: number;
+    queued: number;
+    running: number;
+    done: number;
+    failed: number;
+    cancelled: number;
+    /** blocked + queued + running — everything that has not landed yet. */
+    active: number;
+    /** Agents holding a VM that is not terminated. */
+    sandboxes: number;
+}
+/**
+ * Build the delegation forest from a flat agent list.
+ *
+ * Roots are agents with no parent AND agents whose parent is not in the list,
+ * so a filtered view (one branch, a search result) still renders as a tree
+ * instead of vanishing. Sibling order is the input order — the caller sorts.
+ *
+ * Cycle-safe: a parent chain that loops (which only a buggy producer can emit)
+ * drops the repeat instead of recursing forever.
+ */
+export declare function buildSwarmTree(agents: SwarmAgent[]): SwarmNode[];
+/** Walk a forest depth-first, parents before children (visible tree order). */
+export declare function flattenSwarmTree(nodes: SwarmNode[]): SwarmNode[];
+/** Count agents by status, plus live VMs. Pure — safe to call in a `$derived`. */
+export declare function summarizeSwarm(agents: SwarmAgent[]): SwarmCounts;
+/**
+ * A barrier's progress, derived from its members.
+ *
+ * The gate is only as done as the branch under it, so `status` is computed from
+ * the members unless the barrier carries an explicit one: any member still
+ * working keeps it `open`, a failure fails it, a cancellation cancels it. A
+ * barrier with no members yet reads `open` with a zero total, which is exactly
+ * what a just-declared gate is.
+ */
+export declare function summarizeBarrier(barrier: SwarmBarrier, agents: SwarmAgent[]): {
+    done: number;
+    failed: number;
+    total: number;
+    status: SwarmBarrierStatus;
+};
+/**
+ * How long an agent has been working, in ms — `null` when it never started.
+ *
+ * `now` is an argument rather than a `Date.now()` call so the same inputs always
+ * render the same output (testable, SSR-safe, and a host that ticks a clock in
+ * `$state` gets a live counter for free).
+ */
+export declare function swarmElapsed(agent: SwarmAgent, now: number): number | null;
+/**
+ * How long ago something happened, as a console reads it: `now`, `4m`, `2h`,
+ * `3d`. Same clock rule as everything else here — `now` is an argument.
+ */
+export declare function formatSwarmAge(at: number, now: number): string;
+/** Compact elapsed readout: `840ms`, `4.2s`, `3m 07s`, `1h 04m`. */
+export declare function formatSwarmDuration(ms: number): string;
+/**
+ * One record from the swarm's event log.
+ *
+ * `seq` is the whole resumption contract: monotonic per swarm, and the client's
+ * watermark is the last one APPLIED — never the number of records held. Those
+ * differ the moment an event updates an agent already in the map, which is most
+ * events, and confusing the two silently re-requests or skips history.
+ */
+export interface SwarmEvent {
+    seq: number;
+    /** Free-form producer label ("agent.completed"), passed through untouched. */
+    kind?: string;
+    agent?: SwarmAgent;
+    plan?: SwarmPlan;
+    barrier?: SwarmBarrier;
+    artifact?: SwarmArtifact;
+}
+/** A point-in-time view of the whole swarm, as the host's snapshot API returns it. */
+export interface SwarmSnapshot {
+    /** The seq this snapshot is current as of — subscribe from here. */
+    seq?: number;
+    plan?: SwarmPlan | null;
+    agents?: SwarmAgent[];
+    barriers?: SwarmBarrier[];
+    artifacts?: SwarmArtifact[];
+}

package/dist/ai/swarm/swarm.js

@@ -0,0 +1,187 @@
+/**
+ * The swarm model — the shape of a multi-agent run, and the projection logic
+ * the UI needs, with no transport attached.
+ *
+ * A swarm is one orchestrated effort: a root agent that decomposes a task,
+ * workers it delegates to, optional reviewers, and fan-in gates (barriers)
+ * where parallel branches rejoin before the work is merged into artifacts.
+ * Every real implementation streams that state as an append-only event log with
+ * a monotonic sequence number, because an hour-long run WILL outlive a socket.
+ *
+ * era ships the projection half of that contract and nothing else. The host
+ * owns the transport (oRPC, SSE, WebSocket, polling — era does not care) and
+ * feeds `SwarmController` snapshots and events; the controller owns the one
+ * invariant that makes reconnection tractable:
+ *
+ *   the view is a pure function of (snapshot at seq S, every event with seq > S)
+ *
+ * which turns "resume a live view" into a watermark comparison instead of a
+ * state-transfer negotiation. Take a snapshot, subscribe from its seq, and a
+ * dropped socket, a server restart and a browser refresh all re-enter through
+ * the same door.
+ *
+ * This module is the pure half — shapes and projections, no runes, no clock.
+ * `SwarmController` (swarm.svelte.ts) is the live half, and it is optional: a
+ * host that already holds swarm state in its own store calls these functions
+ * directly and never constructs one.
+ */
+/**
+ * Build the delegation forest from a flat agent list.
+ *
+ * Roots are agents with no parent AND agents whose parent is not in the list,
+ * so a filtered view (one branch, a search result) still renders as a tree
+ * instead of vanishing. Sibling order is the input order — the caller sorts.
+ *
+ * Cycle-safe: a parent chain that loops (which only a buggy producer can emit)
+ * drops the repeat instead of recursing forever.
+ */
+export function buildSwarmTree(agents) {
+    const nodes = new Map();
+    for (const agent of agents)
+        nodes.set(agent.id, { agent, depth: 0, children: [] });
+    const roots = [];
+    for (const agent of agents) {
+        const node = nodes.get(agent.id);
+        const parent = agent.parentId ? nodes.get(agent.parentId) : undefined;
+        if (parent && parent !== node)
+            parent.children.push(node);
+        else
+            roots.push(node);
+    }
+    // Depth from the structure, and the visited set is what makes a cyclic chain
+    // terminate: a node reached twice is already placed, so it is not descended
+    // into again.
+    const seen = new Set();
+    const assign = (node, depth) => {
+        if (seen.has(node.agent.id))
+            return;
+        seen.add(node.agent.id);
+        node.depth = depth;
+        for (const child of node.children)
+            assign(child, depth + 1);
+    };
+    for (const root of roots)
+        assign(root, 0);
+    // A cycle leaves its members unreachable from any root — surface them as
+    // roots rather than dropping agents the caller can see in the list.
+    for (const agent of agents) {
+        if (seen.has(agent.id))
+            continue;
+        const node = nodes.get(agent.id);
+        roots.push(node);
+        assign(node, 0);
+    }
+    return roots;
+}
+/** Walk a forest depth-first, parents before children (visible tree order). */
+export function flattenSwarmTree(nodes) {
+    const out = [];
+    const walk = (list) => {
+        for (const node of list) {
+            out.push(node);
+            walk(node.children);
+        }
+    };
+    walk(nodes);
+    return out;
+}
+/** Count agents by status, plus live VMs. Pure — safe to call in a `$derived`. */
+export function summarizeSwarm(agents) {
+    const counts = {
+        total: agents.length,
+        blocked: 0,
+        queued: 0,
+        running: 0,
+        done: 0,
+        failed: 0,
+        cancelled: 0,
+        active: 0,
+        sandboxes: 0
+    };
+    for (const agent of agents) {
+        counts[agent.status]++;
+        if (agent.status === 'blocked' || agent.status === 'queued' || agent.status === 'running') {
+            counts.active++;
+        }
+        if (agent.sandbox && agent.sandbox.status !== 'terminated')
+            counts.sandboxes++;
+    }
+    return counts;
+}
+/**
+ * A barrier's progress, derived from its members.
+ *
+ * The gate is only as done as the branch under it, so `status` is computed from
+ * the members unless the barrier carries an explicit one: any member still
+ * working keeps it `open`, a failure fails it, a cancellation cancels it. A
+ * barrier with no members yet reads `open` with a zero total, which is exactly
+ * what a just-declared gate is.
+ */
+export function summarizeBarrier(barrier, agents) {
+    let done = 0;
+    let failed = 0;
+    let total = 0;
+    let open = false;
+    let cancelled = false;
+    for (const agent of agents) {
+        if (agent.barrierId !== barrier.id)
+            continue;
+        total++;
+        if (agent.status === 'done')
+            done++;
+        else if (agent.status === 'failed')
+            failed++;
+        else if (agent.status === 'cancelled')
+            cancelled = true;
+        else
+            open = true;
+    }
+    const derived = open
+        ? 'open'
+        : failed > 0
+            ? 'failed'
+            : cancelled
+                ? 'cancelled'
+                : 'done';
+    return { done, failed, total, status: barrier.status ?? (total === 0 ? 'open' : derived) };
+}
+/**
+ * How long an agent has been working, in ms — `null` when it never started.
+ *
+ * `now` is an argument rather than a `Date.now()` call so the same inputs always
+ * render the same output (testable, SSR-safe, and a host that ticks a clock in
+ * `$state` gets a live counter for free).
+ */
+export function swarmElapsed(agent, now) {
+    if (agent.startedAt == null)
+        return null;
+    return Math.max(0, (agent.endedAt ?? now) - agent.startedAt);
+}
+/**
+ * How long ago something happened, as a console reads it: `now`, `4m`, `2h`,
+ * `3d`. Same clock rule as everything else here — `now` is an argument.
+ */
+export function formatSwarmAge(at, now) {
+    const seconds = Math.max(0, Math.floor((now - at) / 1000));
+    if (seconds < 60)
+        return 'now';
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h`;
+    return `${Math.floor(hours / 24)}d`;
+}
+/** Compact elapsed readout: `840ms`, `4.2s`, `3m 07s`, `1h 04m`. */
+export function formatSwarmDuration(ms) {
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    const seconds = ms / 1000;
+    if (seconds < 60)
+        return `${seconds.toFixed(1)}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ${String(Math.floor(seconds % 60)).padStart(2, '0')}s`;
+    return `${Math.floor(minutes / 60)}h ${String(minutes % 60).padStart(2, '0')}m`;
+}

package/dist/ai/swarm/swarm.svelte.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The live half of the swarm model: one reconnectable, reactive view of a run.
+ *
+ * The shapes and the pure projections live next door in `swarm.ts` — everything
+ * here is state, so this is the only file in the family that needs runes (and
+ * the only one a host has to construct). See that module for the model itself
+ * and for why the sequence number is the whole resumption contract.
+ */
+import { type SwarmAgent, type SwarmArtifact, type SwarmBarrier, type SwarmConnection, type SwarmEvent, type SwarmPlan, type SwarmSnapshot } from './swarm.js';
+/**
+ * A reconnectable view of one swarm.
+ *
+ * Backend-free by design: the host does the fetching and the socket handling and
+ * hands the results here. A typical wiring is
+ *
+ * ```ts
+ * const swarm = new SwarmController();
+ * swarm.connection = 'loading';
+ * swarm.snapshot(await api.swarmSnapshot(id));       // sets the watermark
+ * swarm.connection = 'live';
+ * for await (const event of api.swarmStream(id, swarm.seq)) swarm.apply(event);
+ * ```
+ *
+ * and the retry path is the same three lines — re-snapshot (never rewinding the
+ * watermark), then subscribe from `seq` again. Everything the components need
+ * (`tree`, `counts`) is derived, so nothing has to be recomputed by hand.
+ */
+export declare class SwarmController {
+    #private;
+    agents: SwarmAgent[];
+    plan: SwarmPlan | null;
+    barriers: SwarmBarrier[];
+    artifacts: SwarmArtifact[];
+    /** Stream health, for `Swarm.Footer`. The host sets it; nothing here does. */
+    connection: SwarmConnection;
+    /** Last transport error, shown beside the watermark. */
+    error: string | null;
+    /** The watermark: the last APPLIED event seq, and the resume point. */
+    seq: number;
+    constructor(snapshot?: SwarmSnapshot);
+    readonly tree: import("./swarm.js").SwarmNode[];
+    readonly counts: import("./swarm.js").SwarmCounts;
+    /**
+     * Merge a snapshot in.
+     *
+     * The watermark only ever moves FORWARD: a refresh taken while live events
+     * are already flowing is older than the view it is refreshing, and rewinding
+     * to its seq would replay every event since.
+     */
+    snapshot(snapshot: SwarmSnapshot): void;
+    /**
+     * Apply one event. Returns false when it was already applied — a backfill
+     * that overlaps what the snapshot already covered is a no-op, not a
+     * double-apply, which is what lets the resume path be careless about overlap.
+     */
+    apply(event: SwarmEvent): boolean;
+    /** Drop everything — switching to a different swarm, not reconnecting to this one. */
+    reset(): void;
+}