@byokit/ui 0.0.0-stage → 0.6.0

package/dist/approvals.js

@@ -0,0 +1,63 @@
+// What is waiting for a person's yes: the approvals list kept current from the kit's event stream, each dropped when
+// it is answered anywhere or runs out of time. Framework-free; typed structurally against `@byokit/openclaw/device`.
+import { retrying, store } from "./follow.js";
+export function approvalsStep(list, a) {
+    if ('type' in a) {
+        if (a.type === 'set')
+            return a.list;
+        const live = list.filter((x) => x.expires > a.now);
+        return live.length === list.length ? list : live;
+    }
+    if (a.event !== 'approval' || !a.approval)
+        return list;
+    const { id } = a.approval;
+    const rest = list.filter((x) => x.id !== id);
+    if (a.change === 'resolved')
+        return rest.length === list.length ? list : rest;
+    if (a.change !== 'added')
+        return list;
+    const at = list.findIndex((x) => x.id === id);
+    return at < 0 ? [...list, a.approval] : list.map((x, i) => (i === at ? a.approval : x));
+}
+/** The question for one approval, in the kit's own sentence (`@byokit/openclaw/device`'s `words` fits). */
+export const approvalWords = (a, words, helper) => words('approval.ask', { helper, summary: a.summary });
+/**
+ * The approvals still waiting, live: listed once the event stream is open (so nothing falls between the two), then
+ * added and resolved from its frames, and each dropped as it expires. Opened again after the link comes back.
+ */
+export function approvalsStore(source, { retryMs = 2000, now = Date.now } = {}) {
+    const made = store([], (set) => {
+        let list = made.get();
+        let timer;
+        const apply = (a) => {
+            list = approvalsStep(approvalsStep(list, a), { type: 'tick', now: now() });
+            clearTimeout(timer);
+            if (list.length > 0) {
+                const next = Math.min(...list.map((x) => x.expires)) - now();
+                timer = setTimeout(() => apply({ type: 'tick', now: now() }), Math.min(Math.max(next, 0), 2 ** 31 - 1));
+            }
+            set(list);
+        };
+        apply({ type: 'tick', now: now() }); // what was kept since the last watcher left may have expired meanwhile
+        const stop = retrying(async (live) => {
+            const it = source.events()[Symbol.asyncIterator]();
+            live.hold(it);
+            try {
+                const first = it.next(); // opens the stream before the list is read
+                first.catch(() => { });
+                const listed = await source.approvals();
+                if (live.stopped())
+                    return;
+                apply({ type: 'set', list: listed });
+                live.ok();
+                for (let r = await first; !r.done && !live.stopped(); r = await it.next())
+                    apply(r.value);
+            }
+            finally {
+                void it.return?.();
+            }
+        }, retryMs);
+        return () => { stop(); clearTimeout(timer); };
+    });
+    return made;
+}

package/dist/browser.d.ts

@@ -0,0 +1,101 @@
+import { type Store } from './follow.ts';
+import type { FollowOptions } from './approvals.ts';
+/** One sign-in request as the OpenClaw kit reports it (`NeedSignIn`). */
+export type SignInRequest = {
+    id: string;
+    gen: number;
+    member: string;
+    origin: string;
+    site: string;
+    secure: boolean;
+    firstTime: boolean;
+    agentNote?: string;
+    hints: string[];
+    choices: {
+        kind: 'takeover' | 'not-now' | 'cancel';
+    }[];
+    state: 'waiting' | 'held' | 'checking' | 'parked' | 'settled';
+    settled?: {
+        state: 'verified' | 'entered-unverified' | 'cancelled' | 'expired' | 'failed';
+        reason?: string;
+        resume?: {
+            state: 'pending' | 'accepted' | 'submitted' | 'indeterminate' | 'failed';
+        };
+    };
+    expires: number;
+};
+export type SignInAction = 'takeover' | 'notNow' | 'cancel' | 'done' | 'reopen' | 'retry';
+export type SignInWordKey = 'signin.waiting' | 'signin.private' | 'signin.checking' | 'signin.parked' | 'signin.verified' | 'signin.noVerifier' | 'signin.stillSignedOut' | 'signin.expired' | 'signin.cancelled' | 'signin.runReplaced' | 'signin.superseded' | 'signin.originMismatch' | 'signin.browserGone' | 'signin.resumeFailed' | 'signin.resumeUnknown' | 'signin.insecureRemote';
+export type SignInVars = {
+    site: string;
+    name: string;
+    origin: string;
+};
+export type SignInSheet = {
+    id: string;
+    gen: number;
+    /** `signin.title` with `site`. */
+    site: string;
+    /** The address the person is signing in on, shown in full; it states the address bar, never that a site is safe. */
+    origin: string;
+    secure: boolean;
+    /** First time on this site: `signin.confirmSite`, and the person types or picks the site before taking over. */
+    confirmSite: boolean;
+    /** The helper's own words, to show only as a quote (`signin.agentNote`), never as a title or button. */
+    note?: string;
+    hints: string[];
+    /** The one sentence under the title. */
+    line: {
+        key: SignInWordKey;
+        vars: SignInVars;
+    };
+    /** Buttons, in order. Empty while someone else signs in or the check runs. */
+    actions: SignInAction[];
+    /** The chip in the chat: `entered` ("Sign-in details entered"), `verified` ("Signed in to {site}"). */
+    chip?: 'entered' | 'verified';
+    /** Still waiting on the person: every outcome but a verified sign-in the helper went on from. */
+    needsYou: boolean;
+};
+/**
+ * What to draw for one request. `holder` is whether this device holds the takeover lease; `name` is the helper's
+ * name for the sentences.
+ */
+export declare function signInSheetView(r: SignInRequest, { name, holder }: {
+    name: string;
+    holder?: boolean;
+}): SignInSheet;
+/** A frame of the kit's event stream; only `byokit.browser` sign-in pings matter here. */
+export type BrowserFrame = {
+    event: string;
+    payload?: unknown;
+};
+/** What `signInsStore` needs from a device client: the kit's device client fits once its browser ops land (O22). */
+export type SignInsSource = {
+    signIns(): Promise<SignInRequest[]>;
+    events(): AsyncIterable<BrowserFrame>;
+};
+/**
+ * The member's sign-in requests, live: listed once the event stream is open (so no ping falls between the two), and
+ * listed again on every sign-in ping, which carries no origin or URL. Opened again after the link comes back.
+ */
+export declare function signInsStore(source: SignInsSource, { retryMs }?: Pick<FollowOptions, 'retryMs'>): Store<SignInRequest[]>;
+/** One live view's state as the kit reports it (`LiveViewState`), as far as drawing it needs. */
+export type LiveState = {
+    phase: 'connecting' | 'live' | 'reconnecting' | 'private' | 'ended' | 'failed';
+    mode: 'observe' | 'control';
+    origin?: string;
+    offOrigin?: boolean;
+};
+export type LivePanel = {
+    /** Draw frames; otherwise keep the last one dimmed under `line`, or a blank panel. */
+    showFrames: boolean;
+    /** Input goes to the page only while this is true: in control, live, and not paused on an unexpected address. */
+    input: boolean;
+    /** `confirmOrigin` button: the page moved to `origin`, which the person hasn't confirmed for this sign-in. */
+    confirmOrigin?: string;
+    line?: {
+        key: 'live.reconnecting' | 'signin.private' | 'signin.offOrigin';
+    };
+};
+/** What to draw for one live view. Watching never asks the helper anything. */
+export declare function livePanelView(s: LiveState): LivePanel;

package/dist/browser.js

@@ -0,0 +1,97 @@
+// The browser sign-in sheet and live view as a person sees them: which sentence to show, which buttons to offer, and
+// the chip under the chat. Framework-free; typed structurally against `@byokit/openclaw`'s `NeedSignIn` and
+// `LiveViewState` (spec 5.17), so nothing here imports a kit. Sentences are the kit's word keys plus their values,
+// for the kit's own `words` to say. Nothing here ever holds what the person types.
+import { retrying, store } from "./follow.js";
+const settledLine = (s) => {
+    switch (s.state) {
+        case 'verified':
+            return s.resume?.state === 'failed' ? 'signin.resumeFailed'
+                : s.resume?.state === 'indeterminate' ? 'signin.resumeUnknown' : 'signin.verified';
+        case 'entered-unverified': return s.reason === 'still-signed-out' ? 'signin.stillSignedOut' : 'signin.noVerifier';
+        case 'cancelled':
+            return s.reason === 'run-replaced' ? 'signin.runReplaced' : s.reason === 'superseded' ? 'signin.superseded' : 'signin.cancelled';
+        case 'expired': return 'signin.expired';
+        case 'failed': return s.reason === 'origin-mismatch' ? 'signin.originMismatch' : 'signin.browserGone';
+    }
+};
+/**
+ * What to draw for one request. `holder` is whether this device holds the takeover lease; `name` is the helper's
+ * name for the sentences.
+ */
+export function signInSheetView(r, { name, holder = false }) {
+    const vars = { site: r.site, name, origin: r.origin };
+    const can = (k) => r.choices.some((c) => c.kind === k);
+    const base = {
+        id: r.id, gen: r.gen, site: r.site, origin: r.origin, secure: r.secure, hints: r.hints,
+        confirmSite: r.firstTime && r.state === 'waiting', ...(r.agentNote ? { note: r.agentNote } : {}),
+    };
+    const line = (key) => ({ key, vars });
+    switch (r.state) {
+        case 'waiting': {
+            const actions = [];
+            if (can('takeover'))
+                actions.push('takeover');
+            if (can('not-now'))
+                actions.push('notNow');
+            return { ...base, line: line(r.secure ? 'signin.waiting' : 'signin.insecureRemote'), actions, needsYou: true };
+        }
+        case 'held':
+            return holder
+                ? { ...base, line: line('signin.waiting'), actions: ['done', 'notNow', 'cancel'], needsYou: true }
+                : { ...base, line: line('signin.private'), actions: [], needsYou: true };
+        case 'checking': return { ...base, line: line('signin.checking'), actions: [], chip: 'entered', needsYou: true };
+        case 'parked': return { ...base, line: line('signin.parked'), actions: ['reopen'], needsYou: true };
+        case 'settled': {
+            const s = r.settled ?? { state: 'failed' };
+            const key = settledLine(s);
+            const verified = s.state === 'verified';
+            const chip = verified ? 'verified' : s.state === 'entered-unverified' ? 'entered' : undefined;
+            return {
+                ...base, line: line(key), actions: verified ? [] : ['retry'], ...(chip ? { chip } : {}),
+                needsYou: key !== 'signin.verified',
+            };
+        }
+    }
+}
+const ping = (f) => f.event === 'byokit.browser' && f.payload?.kind === 'signin';
+/**
+ * The member's sign-in requests, live: listed once the event stream is open (so no ping falls between the two), and
+ * listed again on every sign-in ping, which carries no origin or URL. Opened again after the link comes back.
+ */
+export function signInsStore(source, { retryMs = 2000 } = {}) {
+    return store([], (set) => retrying(async (live) => {
+        const it = source.events()[Symbol.asyncIterator]();
+        live.hold(it);
+        try {
+            const first = it.next();
+            first.catch(() => { });
+            set(await source.signIns());
+            if (live.stopped())
+                return;
+            live.ok();
+            for (let r = await first; !r.done && !live.stopped(); r = await it.next()) {
+                if (ping(r.value))
+                    set(await source.signIns());
+            }
+        }
+        finally {
+            void it.return?.();
+        }
+    }, retryMs));
+}
+/** What to draw for one live view. Watching never asks the helper anything. */
+export function livePanelView(s) {
+    switch (s.phase) {
+        case 'live':
+            if (s.mode === 'control' && s.offOrigin) {
+                return { showFrames: true, input: false, line: { key: 'signin.offOrigin' }, ...(s.origin ? { confirmOrigin: s.origin } : {}) };
+            }
+            return { showFrames: true, input: s.mode === 'control' };
+        case 'connecting':
+        case 'reconnecting': return { showFrames: false, input: false, line: { key: 'live.reconnecting' } };
+        case 'private': return { showFrames: false, input: false, line: { key: 'signin.private' } };
+        case 'ended':
+        case 'failed': return { showFrames: false, input: false };
+    }
+}

package/dist/connect.d.ts

@@ -0,0 +1,92 @@
+import WORDS from './words.json';
+import { keyView, type KeyAction, type KeyState } from './key.ts';
+import type { UseSignIn } from './useSignIn.ts';
+export type Billing = 'subscription' | 'api' | 'local' | 'free' | 'unknown';
+export type Via = 'browser' | 'code' | 'paste' | 'key' | 'session' | 'setup_token' | 'cli' | 'plan_key' | 'cloud' | 'local' | 'endpoint';
+export type Readiness = 'ready' | 'needs_binary' | 'needs_plugin' | 'needs_host' | 'needs_client' | 'unsupported_platform' | 'no_upstream_flow';
+/** One route as any kit's `routes()` lists it, restated structurally (D3): `@byokit/accounts` and
+ *  `@byokit/openclaw` route views fit as they are. Only these fields are read, so nothing else (a credential
+ *  included) can reach the view. */
+export type ConnectRoute = {
+    /** openclaw's is optional; a row without one is keyed `<provider>:<via>`. */
+    id?: string;
+    provider: string;
+    name?: string;
+    company?: string;
+    via: Via;
+    billing: Billing;
+    /** accounts: `'default' | 'explicit'`; openclaw: `offerPolicy` plus its legacy ready-only boolean `offer`. */
+    offer?: 'default' | 'explicit' | boolean;
+    offerPolicy?: 'default' | 'explicit';
+    /** openclaw: `services` marks speech, search, media and other non-chat rows. */
+    group?: 'models' | 'services';
+    upstream?: {
+        surface: 'accounts' | 'openclaw' | 'herdr';
+    };
+    readiness: Readiness;
+};
+export type ConnectGroupId = 'plans' | 'perUse' | 'local' | 'server' | 'cloud' | 'other' | 'services';
+/** What choosing a row leads to: a sign-in sheet (`useSignIn`), a key card (`keyView`), the app's own setup form
+ *  (cloud account, local model, server address and its billing), or the reason it cannot be used here. */
+export type ConnectDoes = 'signin' | 'key' | 'setup' | 'unavailable';
+export type ConnectRow = {
+    /** Unique across kits: `<surface>/<id>`. */
+    key: string;
+    id: string;
+    provider: string;
+    surface?: 'accounts' | 'openclaw' | 'herdr';
+    name: string;
+    company: string;
+    via: Via;
+    billing: Billing;
+    group: ConnectGroupId;
+    /** Offered by default: a ready subscription row. Never true for any other billing. */
+    offered: boolean;
+    ready: boolean;
+    readiness: Readiness;
+    does: ConnectDoes;
+    /** Plain words: how it is paid for, how you sign in, and whether it works here. */
+    billingWords: string;
+    method: string;
+    status: string;
+};
+export type ConnectGroup = {
+    id: ConnectGroupId;
+    title: string;
+    note: string;
+    rows: ConnectRow[];
+};
+export type ConnectStep = {
+    at: 'list';
+} | {
+    at: 'route';
+    key: string;
+    entry: KeyState;
+};
+export type ConnectAction = {
+    type: 'pick';
+    key: string;
+} | {
+    type: 'back';
+} | KeyAction;
+export type ConnectView = {
+    groups: ConnectGroup[];
+    /** The picked row and, for a key route, its key card. Undefined on the list or when the row is gone. */
+    chosen?: {
+        row: ConnectRow;
+        key?: ReturnType<typeof keyView>;
+    };
+};
+export type ConnectWords = typeof WORDS;
+export declare function connectStep(step: ConnectStep, action: ConnectAction): ConnectStep;
+/** Every route, grouped in a fixed order (empty groups left out), rows in the kits' own order. */
+export declare function connectView(routes: readonly ConnectRoute[], step?: ConnectStep, words?: ConnectWords): ConnectView;
+/** What the app does for the picked row, given that row; credentials go straight from the app to its kit. */
+export type UseConnectSignIn = Omit<UseSignIn, 'read' | 'start' | 'cancel'> & {
+    read: (row: ConnectRow) => ReturnType<UseSignIn['read']>;
+    start?: (row: ConnectRow, body?: Parameters<NonNullable<UseSignIn['start']>>[0]) => Promise<unknown>;
+    cancel: (row: ConnectRow) => Promise<unknown>;
+};
+/** `useSignIn`'s options for the chosen sign-in row, or undefined for any other step. Draw the sheet as its own
+ *  component keyed by `chosen.row.key` so a new pick starts with fresh sign-in state. */
+export declare function signInFor(view: ConnectView, o: UseConnectSignIn): UseSignIn | undefined;

package/dist/connect.js

@@ -0,0 +1,74 @@
+// "Connect an AI account" as headless view state: every route the kits list (D18), grouped by how the person pays,
+// with plain words for the billing, the method and whether it works here. Plans come first and are the only rows
+// offered by default; every other row is listed and used only when the person picks it. Nothing here names a
+// provider: groups and words come from each row's billing, method and readiness alone. Framework-free.
+import WORDS from './words.json' with { type: 'json' };
+import { keyStep, keyView } from "./key.js";
+const ORDER = ['plans', 'perUse', 'local', 'server', 'cloud', 'other', 'services'];
+const SIGNIN = ['browser', 'code', 'paste', 'session', 'cli'];
+const KEY = ['key', 'plan_key', 'setup_token'];
+const fill = (s, r) => s.replace(/\{(name|company)\}/g, (_, k) => r[k]);
+/** Cloud, server and local methods are always explicit and go to their own groups; then billing decides: only a
+ *  subscription row named default is a plan, so an API, free or unknown row never lands in Plans whatever its
+ *  `offer` says. */
+function groupOf(r) {
+    if (r.group === 'services')
+        return 'services';
+    if (r.via === 'cloud')
+        return 'cloud';
+    if (r.via === 'endpoint')
+        return 'server';
+    if (r.via === 'local')
+        return 'local';
+    const byDefault = r.offer === 'default' || r.offerPolicy === 'default' || r.offer === true;
+    if (r.billing === 'subscription' && byDefault)
+        return 'plans';
+    if (r.billing === 'local')
+        return 'local';
+    if (r.billing === 'api')
+        return 'perUse';
+    return 'other';
+}
+function rowOf(r, w) {
+    const name = r.name || r.provider, company = r.company || name, id = r.id ?? `${r.provider}:${r.via}`;
+    const group = groupOf(r);
+    const ready = r.readiness === 'ready';
+    const billing = r.via === 'endpoint' ? w['billing.server'] : r.via === 'local' ? w['billing.local'] : w[`billing.${r.billing}`];
+    return {
+        key: `${r.upstream?.surface ?? ''}/${id}`, id, provider: r.provider,
+        ...(r.upstream ? { surface: r.upstream.surface } : {}),
+        name, company, via: r.via, billing: r.billing, group,
+        offered: group === 'plans' && ready, ready, readiness: r.readiness,
+        does: !ready ? 'unavailable' : SIGNIN.includes(r.via) ? 'signin' : KEY.includes(r.via) ? 'key' : 'setup',
+        billingWords: fill(billing, { name, company }), method: w[`via.${r.via}`], status: w[`ready.${r.readiness}`],
+    };
+}
+export function connectStep(step, action) {
+    if (action.type === 'pick')
+        return { at: 'route', key: action.key, entry: 'entry' };
+    if (action.type === 'back')
+        return { at: 'list' };
+    return step.at === 'route' ? { ...step, entry: keyStep(step.entry, action) } : step;
+}
+/** Every route, grouped in a fixed order (empty groups left out), rows in the kits' own order. */
+export function connectView(routes, step = { at: 'list' }, words = WORDS) {
+    const rows = routes.map((r) => rowOf(r, words));
+    const groups = ORDER.map((id) => ({ id, title: words[`connect.${id}`], note: words[`connect.${id}.note`], rows: rows.filter((r) => r.group === id) }))
+        .filter((g) => g.rows.length);
+    const row = step.at === 'route' ? rows.find((r) => r.key === step.key) : undefined;
+    if (!row || step.at !== 'route')
+        return { groups };
+    if (row.does !== 'key')
+        return { groups, chosen: { row } };
+    const label = words[row.group === 'plans' ? 'key.label.plan' : row.billing === 'api' ? 'key.label.perUse' : 'key.label.other'];
+    return { groups, chosen: { row, key: keyView(step.entry, (k) => (k === 'key.label' ? label : words[k])) } };
+}
+/** `useSignIn`'s options for the chosen sign-in row, or undefined for any other step. Draw the sheet as its own
+ *  component keyed by `chosen.row.key` so a new pick starts with fresh sign-in state. */
+export function signInFor(view, o) {
+    const row = view.chosen?.row;
+    if (row?.does !== 'signin')
+        return undefined;
+    const { read, start, cancel, ...rest } = o;
+    return { ...rest, read: () => read(row), cancel: () => cancel(row), ...(start ? { start: (body) => start(row, body) } : {}) };
+}

package/dist/follow.d.ts

@@ -0,0 +1,17 @@
+export type Stop = () => void;
+/** A view any UI can draw from: the current state, and a way to hear each change (the returned function stops). */
+export type Store<T> = {
+    get(): T;
+    subscribe(fn: (state: T) => void): () => void;
+};
+type Live = {
+    hold(it: AsyncIterator<unknown>): void;
+    stopped(): boolean;
+    ok(): void;
+};
+export declare function retrying(attempt: (live: Live) => Promise<void>, retryMs: number): Stop;
+/** A store that follows its source only while someone listens: the first listener starts it, the last one stops it. */
+export declare function store<T>(initial: T, follow: (set: (state: T) => void) => Stop): Store<T> & {
+    set(state: T): void;
+};
+export {};

package/dist/follow.js

@@ -0,0 +1,72 @@
+// Keeping a live view going over a link: a view's event stream ends whenever the link drops or the host restarts, so
+// it opens again after a pause until the view stops or the pairing is gone for good. Framework-free.
+// Only a removed pairing never comes back; a stopped or refused link comes back with its `retry()`.
+const final = (e) => typeof e === 'object' && e !== null && e.code === 'removed';
+// ponytail: the pause doubles from 250 ms up to `retryMs` while tries fail, and starts short again once one works;
+// the link paces its own reconnects, so a stream only reopens into a link that is either back (it works, soon after
+// the link does) or still away (it fails at once, cheaply).
+export function retrying(attempt, retryMs) {
+    let stopped = false;
+    let pause = 0;
+    let current;
+    let timer;
+    let wake;
+    const live = {
+        hold: (it) => { current = it; if (stopped)
+            void it.return?.(); },
+        stopped: () => stopped,
+        ok: () => { pause = 0; },
+    };
+    void (async () => {
+        while (!stopped) {
+            try {
+                await attempt(live);
+            }
+            catch (e) {
+                if (final(e))
+                    return;
+            }
+            current = undefined;
+            if (stopped)
+                return;
+            pause = Math.min(pause ? pause * 2 : 250, retryMs);
+            await new Promise((resolve) => { wake = resolve; timer = setTimeout(resolve, pause); });
+        }
+    })();
+    return () => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearTimeout(timer);
+        wake?.();
+        void current?.return?.();
+    };
+}
+/** A store that follows its source only while someone listens: the first listener starts it, the last one stops it. */
+export function store(initial, follow) {
+    let state = initial;
+    let stop;
+    const listeners = new Set();
+    const set = (next) => {
+        if (next === state)
+            return;
+        state = next;
+        for (const fn of [...listeners])
+            fn(state);
+    };
+    return {
+        get: () => state,
+        set,
+        subscribe: (fn) => {
+            listeners.add(fn);
+            stop ??= follow(set);
+            return () => {
+                if (!listeners.delete(fn) || listeners.size > 0)
+                    return;
+                const s = stop;
+                stop = undefined;
+                s?.();
+            };
+        },
+    };
+}

package/dist/herdr.d.ts

@@ -0,0 +1,103 @@
+import { type Store } from './follow.ts';
+export type AgentStatus = 'idle' | 'working' | 'blocked' | 'done' | 'unknown';
+export type HerdrAgent = {
+    kind?: string;
+    name?: string;
+    status: AgentStatus;
+    revision: number;
+    launchPending?: boolean;
+    interactiveReady?: boolean;
+};
+/** The tree as the Herdr kit reports it. */
+export type HerdrTree = {
+    connected: boolean;
+    workspaces: {
+        id: string;
+        label: string;
+        tabs: {
+            id: string;
+            label: string;
+            panes: {
+                id: string;
+                cwd?: string;
+                agent?: HerdrAgent;
+            }[];
+        }[];
+    }[];
+};
+/** An agent waiting for an answer, as the Herdr kit reports it; `revision` goes back with the answer. */
+export type BlockedAgent = {
+    paneId: string;
+    workspaceId: string;
+    tabId: string;
+    kind?: string;
+    revision: number;
+    prompt: string;
+    since: number;
+};
+/** One `hd.events` frame. */
+export type HerdrFrame = {
+    type: 'snapshot';
+    snapshot: HerdrTree;
+} | {
+    type: 'blocked';
+    change: 'added' | 'resolved';
+    blocked: BlockedAgent;
+} | {
+    type: 'raw';
+    line: string;
+};
+export type HerdrAction = HerdrFrame | {
+    type: 'listed';
+    blocked: BlockedAgent[];
+};
+/** `tree` is null until the computer first says what it has. */
+export type HerdrState = {
+    tree: HerdrTree | null;
+    blocked: BlockedAgent[];
+};
+export declare const HERDR_EMPTY: HerdrState;
+export declare function herdrStep(s: HerdrState, a: HerdrAction): HerdrState;
+/** An agent as a list row: its status is what the kit's `agentWords` takes ('starting' while it launches). */
+export type AgentRow = {
+    paneId: string;
+    name: string;
+    kind?: string;
+    status: AgentStatus | 'starting';
+    agent: HerdrAgent;
+};
+/** The agents grouped by where they run ("project · tab"), tabs without an agent left out. `project` is the
+ *  folder's own name alone, for rows that name the agent without the tab's internal label. */
+export declare function herdrTreeView(tree: HerdrTree | null): {
+    workspaceId: string;
+    tabId: string;
+    project: string;
+    where: string;
+    agents: AgentRow[];
+}[];
+/** The agent in one pane, if that pane has one. */
+export declare function agentIn(tree: HerdrTree | null, paneId: string | undefined): AgentRow | undefined;
+/** The waiting agents, each with the name to show for it. */
+export declare const blockedView: (s: HerdrState) => {
+    name: string;
+    paneId: string;
+    workspaceId: string;
+    tabId: string;
+    kind?: string;
+    revision: number;
+    prompt: string;
+    since: number;
+}[];
+/** What `herdrStore` needs from a device client: `herdrDevice(link)` fits. */
+export type HerdrSource = {
+    blocked(): Promise<BlockedAgent[]>;
+    events(): AsyncIterable<HerdrFrame>;
+};
+/**
+ * The tree and the waiting agents, live from one `hd.events` stream per device however many views watch it: the
+ * tree from its frames, the waiting list read once the stream is open and then kept by its frames. Opened again
+ * after the link comes back.
+ */
+export declare function herdrStore(source: HerdrSource, { retryMs }?: {
+    retryMs?: number;
+}): Store<HerdrState>;