@byokit/herdr 0.1.0-next.dbe7142

package/dist/generated/methods.js

@@ -0,0 +1,3 @@
+// Generated by scripts/gen-types.ts from schema/herdr-api-0.9.1.json (docs/runtime-kits.md 6.7) — do not edit.
+// Method table: request params and response result per socket method.
+export {};

package/dist/generated/report.json

@@ -0,0 +1,50 @@
+{
+    "herdr": "0.9.1",
+    "protocol": 22,
+    "schemaVersion": 1,
+    "methods": 103,
+    "events": 27,
+    "missing": [],
+    "unmatched": [
+        {
+            "method": "agent.focus",
+            "why": "result type not determined by the snapshot (naming rules, docs and lab probe)"
+        },
+        {
+            "method": "agent.read",
+            "why": "result type not determined by the snapshot (naming rules, docs and lab probe)"
+        },
+        {
+            "method": "agent.send_keys",
+            "why": "result type not determined by the snapshot (naming rules, docs and lab probe)"
+        },
+        {
+            "method": "command.invoke",
+            "why": "result type not determined by the snapshot (naming rules, docs and lab probe)"
+        },
+        {
+            "method": "pane.graphics.set",
+            "why": "result type not determined by the snapshot (naming rules, docs and lab probe)"
+        },
+        {
+            "method": "popup.close",
+            "why": "result type not determined by the snapshot (naming rules, docs and lab probe)"
+        },
+        {
+            "method": "product_announcement.dismiss",
+            "why": "result type not determined by the snapshot (naming rules, docs and lab probe)"
+        },
+        {
+            "method": "release_notes.dismiss",
+            "why": "result type not determined by the snapshot (naming rules, docs and lab probe)"
+        },
+        {
+            "method": "server.live_handoff",
+            "why": "result type not determined by the snapshot (naming rules, docs and lab probe)"
+        },
+        {
+            "method": "server.stop",
+            "why": "result type not determined by the snapshot (naming rules, docs and lab probe)"
+        }
+    ]
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { HERDR_VERSION, HERDR_PROTOCOL } from './constants.ts';
+export { HerdrKit } from './kit.ts';
+export type { AgentRef, AgentStatus, BlockedAgent, HerdrEvent, HerdrEventName, HerdrEventOf, HerdrKitOptions, HerdrMethod, HerdrMethods, HerdrParams, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, HerdrTransport, PromptReceipt, StartAgent, TerminalSession, } from './types.ts';

package/dist/index.js

@@ -0,0 +1,4 @@
+// `@byokit/herdr` — the Herdr runtime kit (Node host side). The phone and browser side lives in `./device`, the
+// host-side link adapter in `./link`; the fake Herdr and contract suite arrive with H6 in `./testing`.
+export { HERDR_VERSION, HERDR_PROTOCOL } from "./constants.js";
+export { HerdrKit } from "./kit.js";

package/dist/kit.d.ts

@@ -0,0 +1,73 @@
+import type { AgentRef, AgentStatus, BlockedAgent, HerdrEventName, HerdrEventOf, HerdrKitOptions, HerdrMethod, HerdrParams, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, PromptReceipt, StartAgent, TerminalSession } from './types.ts';
+export declare class HerdrKit {
+    private readonly supervisor;
+    private transport?;
+    private current;
+    private tree;
+    private listeners;
+    private stops;
+    private statusStops;
+    private generation;
+    private readonly o;
+    private readonly callAny;
+    private readonly agents;
+    private readonly blockedList;
+    constructor(o: HerdrKitOptions);
+    get state(): HerdrState;
+    private publish;
+    private update;
+    private bootstrap;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    call<M extends HerdrMethod>(method: M, params: HerdrParams<M>, o?: {
+        timeoutMs?: number;
+    }): Promise<HerdrResult<M>>;
+    subscribe<E extends HerdrEventName>(subs: HerdrSubscription<E>[], on: (e: HerdrEventOf<E>) => void): () => void;
+    cli(args: string[], o?: {
+        timeoutMs?: number;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number | null;
+        timedOut: boolean;
+    }>;
+    terminal(paneId: string, o: {
+        mode: 'control' | 'observe';
+        cols: number;
+        rows: number;
+    }): TerminalSession;
+    snapshot(): HerdrSnapshot;
+    onChange(fn: (s: HerdrSnapshot) => void): () => void;
+    startAgent(o: StartAgent): Promise<AgentRef>;
+    prompt(target: AgentRef, text: string, o?: {
+        wait?: {
+            until?: AgentStatus[];
+            timeoutMs: number;
+        };
+    }): Promise<PromptReceipt>;
+    sendKeys(target: AgentRef, keys: string[]): Promise<void>;
+    wait(target: AgentRef, o: {
+        until?: AgentStatus[];
+        timeoutMs: number;
+    }): Promise<AgentStatus>;
+    read(paneId: string, o?: {
+        source?: 'visible' | 'recent' | 'recent_unwrapped' | 'detection';
+        lines?: number;
+        ansi?: boolean;
+    }): Promise<{
+        text: string;
+        truncated: boolean;
+    }>;
+    blocked(): BlockedAgent[];
+    onBlocked(fn: (b: BlockedAgent, change: 'added' | 'resolved') => void): () => void;
+    answer(paneId: string, keys: string[], o: {
+        revision: number;
+    }): Promise<void>;
+    closePane(paneId: string): Promise<void>;
+    closeTab(tabId: string): Promise<void>;
+    closeWorkspace(workspaceId: string): Promise<void>;
+    agentKinds(): Promise<string[]>;
+    installedAgentKinds(kinds: readonly string[], o: {
+        path: string[];
+    }): string[];
+}

package/dist/kit.js

@@ -0,0 +1,209 @@
+import { createAgents } from "./agents.js";
+import { Blocked } from "./approvals.js";
+import { runCli } from "./cli.js";
+import { openTerminal } from "./terminal.js";
+import { HERDR_PROTOCOL } from "./constants.js";
+import { closePane, closeTab, closeWorkspace } from "./close.js";
+import { Supervisor } from "./supervise.js";
+const kinds = ['pane.agent_detected', 'pane.created', 'pane.closed', 'pane.moved', 'pane.exited', 'pane.updated',
+    'workspace.created', 'workspace.closed', 'workspace.renamed', 'workspace.updated', 'tab.created', 'tab.closed', 'tab.renamed'];
+const empty = () => ({ connected: false, workspaces: [] });
+export class HerdrKit {
+    supervisor;
+    transport;
+    current = { phase: 'stopped' };
+    tree = empty();
+    listeners = new Set();
+    stops = new Set();
+    statusStops = new Set();
+    generation = 0;
+    o;
+    callAny = (method, params, timeoutMs) => this.call(method, params, timeoutMs === undefined ? undefined : { timeoutMs });
+    agents;
+    blockedList;
+    constructor(o) {
+        this.o = o;
+        this.supervisor = new Supervisor(o, (s) => { this.current = s; o.onState?.(s); });
+        this.agents = createAgents({ call: this.callAny, snapshot: () => this.snapshot() });
+        this.blockedList = new Blocked({ call: this.callAny });
+    }
+    get state() { return this.current; }
+    publish() { for (const fn of this.listeners)
+        fn(this.snapshot()); }
+    update(e) {
+        const raw = e;
+        const paneId = (raw.pane_id ?? raw.pane?.pane_id);
+        let owner;
+        let pane;
+        for (const w of this.tree.workspaces) {
+            for (const t of w.tabs) {
+                const found = t.panes.find((p) => p.id === paneId);
+                if (found !== undefined) {
+                    pane = found;
+                    owner = { workspaceId: w.id, tabId: t.id };
+                }
+            }
+        }
+        if (pane !== undefined && owner !== undefined &&
+            (e.type === 'pane.agent_status_changed' || e.type === 'pane.agent_detected' || e.type === 'pane.updated')) {
+            const a = raw.agent ?? raw.pane ?? raw;
+            pane.agent = { status: 'unknown', revision: 0, ...pane.agent,
+                ...(a.agent !== undefined ? { kind: a.agent } : {}),
+                ...(a.agent_status !== undefined ? { status: a.agent_status } : {}),
+                ...(a.revision !== undefined ? { revision: a.revision } : {}),
+                ...(a.launch_pending !== undefined ? { launchPending: a.launch_pending } : {}),
+                ...(a.interactive_ready !== undefined ? { interactiveReady: a.interactive_ready } : {}),
+            };
+            this.blockedList.update(paneId, pane.agent, owner);
+        }
+        if (e.type === 'pane.closed') {
+            this.blockedList.update(paneId, undefined, owner ?? { workspaceId: '', tabId: '' });
+            for (const tab of this.tree.workspaces.flatMap((w) => w.tabs))
+                tab.panes = tab.panes.filter((p) => p.id !== paneId);
+        }
+        if (e.type === 'tab.closed')
+            for (const w of this.tree.workspaces)
+                w.tabs = w.tabs.filter((t) => t.id !== raw.tab_id);
+        if (e.type === 'workspace.closed')
+            this.tree.workspaces = this.tree.workspaces.filter((w) => w.id !== raw.workspace_id);
+        this.publish();
+    }
+    async bootstrap(token, buffered) {
+        const result = await this.transport.call('session.snapshot', {});
+        if (token !== this.generation)
+            return;
+        const snap = result.snapshot;
+        if ((snap.protocol !== undefined && snap.protocol !== HERDR_PROTOCOL) ||
+            (result.protocol !== undefined && result.protocol !== HERDR_PROTOCOL)) {
+            this.current = { phase: 'needs-update', why: 'version' };
+            this.o.onState?.(this.current);
+            throw new Error('herdr: snapshot protocol mismatch');
+        }
+        const workspaces = snap.workspaces.map((w) => ({
+            id: w.workspace_id, label: w.label,
+            tabs: snap.tabs.filter((t) => t.workspace_id === w.workspace_id).map((t) => ({
+                id: t.tab_id, label: t.label,
+                panes: snap.panes.filter((p) => p.tab_id === t.tab_id).map((p) => {
+                    const a = snap.agents.find((a) => a.pane_id === p.pane_id);
+                    return { id: p.pane_id, cwd: p.cwd, ...(a ? { agent: {
+                                kind: a.agent, name: a.name,
+                                status: (a.agent_status ?? 'unknown'), revision: (a.revision ?? 0),
+                                launchPending: a.launch_pending, interactiveReady: a.interactive_ready,
+                            } } : {}) };
+                }),
+            })),
+        }));
+        for (const stop of this.statusStops) {
+            stop();
+            this.stops.delete(stop);
+        }
+        this.statusStops.clear();
+        this.tree = { connected: true, workspaces };
+        for (const event of buffered.splice(0))
+            this.update(event);
+        // Agents already blocked in the snapshot join the list; entries whose pane is gone resolve.
+        for (const entry of this.blockedList.list()) {
+            const still = this.tree.workspaces.some((w) => w.tabs.some((t) => t.panes.some((p) => p.id === entry.paneId)));
+            if (!still)
+                this.blockedList.update(entry.paneId, undefined, entry);
+        }
+        for (const w of this.tree.workspaces)
+            for (const t of w.tabs)
+                for (const p of t.panes) {
+                    if (p.agent?.status === 'blocked')
+                        this.blockedList.update(p.id, p.agent, { workspaceId: w.id, tabId: t.id });
+                }
+        this.publish();
+        for (const pane of this.tree.workspaces.flatMap((w) => w.tabs).flatMap((t) => t.panes)) {
+            if (!pane.agent)
+                continue;
+            const stop = this.transport.subscribe([{ type: 'pane.agent_status_changed', pane_id: pane.id }], (e) => this.update(e), () => { });
+            this.stops.add(stop);
+            this.statusStops.add(stop);
+        }
+        this.current = { phase: 'ready' };
+        this.o.onState?.(this.current);
+    }
+    async start() {
+        const token = ++this.generation;
+        this.transport = await this.supervisor.start();
+        const buffered = [];
+        let booting = true;
+        const refresh = () => {
+            if (token !== this.generation || booting)
+                return;
+            booting = true;
+            void this.bootstrap(token, buffered).then(() => { booting = false; }).catch(() => { booting = false; });
+        };
+        const stop = this.transport.subscribe(kinds.map((type) => ({ type })), (e) => {
+            if (booting)
+                buffered.push(e);
+            else if (e.type === 'pane.agent_detected' || /^(pane|tab|workspace)\.(created|closed|moved|renamed)$/.test(e.type)) {
+                buffered.push(e);
+                refresh();
+            }
+            else
+                this.update(e);
+        }, () => { });
+        this.stops.add(stop);
+        const control = stop;
+        control.onDisconnect?.(() => {
+            if (token !== this.generation)
+                return;
+            this.current = { phase: 'reconnecting' };
+            this.o.onState?.(this.current);
+            this.tree.connected = false;
+            this.publish();
+        });
+        control.onReconnect?.(refresh);
+        if (await control.ready === false)
+            throw new Error('herdr: event subscription rejected');
+        await this.bootstrap(token, buffered);
+        booting = false;
+    }
+    async stop() {
+        ++this.generation;
+        for (const entry of this.blockedList.list())
+            this.blockedList.update(entry.paneId, undefined, entry);
+        for (const stop of this.stops)
+            stop();
+        this.stops.clear();
+        this.statusStops.clear();
+        await this.supervisor.stop();
+        this.transport = undefined;
+        this.tree = empty();
+        this.publish();
+    }
+    call(method, params, o) {
+        if (!this.transport)
+            return Promise.reject(new Error('herdr: not connected'));
+        const values = params;
+        const wait = values.wait;
+        const timeout = o?.timeoutMs ?? (method === 'agent.wait' && typeof values.timeout_ms === 'number'
+            ? values.timeout_ms + 5000 : method === 'agent.prompt' && typeof wait?.timeout_ms === 'number'
+            ? wait.timeout_ms + 5000 : undefined);
+        return this.transport.call(method, values, timeout);
+    }
+    subscribe(subs, on) {
+        if (!this.transport)
+            throw new Error('herdr: not connected');
+        return this.transport.subscribe(subs, on, () => { });
+    }
+    cli(args, o) { return runCli(this.o.bin, this.supervisor.env(), args, o?.timeoutMs); }
+    terminal(paneId, o) { return openTerminal(this.o.bin, this.supervisor.env(), paneId, o); }
+    snapshot() { return structuredClone(this.tree); }
+    onChange(fn) { this.listeners.add(fn); return () => { this.listeners.delete(fn); }; }
+    startAgent(o) { return this.agents.startAgent(o); }
+    prompt(target, text, o) { return this.agents.prompt(target, text, o); }
+    sendKeys(target, keys) { return this.agents.sendKeys(target, keys); }
+    wait(target, o) { return this.agents.wait(target, o); }
+    read(paneId, o) { return this.agents.read(paneId, o); }
+    blocked() { return this.blockedList.list(); }
+    onBlocked(fn) { return this.blockedList.on(fn); }
+    answer(paneId, keys, o) { return this.blockedList.answer(paneId, keys, o); }
+    closePane(paneId) { return closePane(this.callAny, paneId); }
+    closeTab(tabId) { return closeTab(this.callAny, tabId); }
+    closeWorkspace(workspaceId) { return closeWorkspace(this.callAny, workspaceId); }
+    agentKinds() { return this.agents.agentKinds(); }
+    installedAgentKinds(kinds, o) { return this.agents.installedAgentKinds(kinds, o); }
+}

package/dist/link.d.ts

@@ -0,0 +1,24 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import { type Grant, type Host, type HostOptions } from '@byokit/link';
+import { type ServeIngress, type Via } from '@byokit/reach';
+import type { RelayClient } from '@byokit/relay';
+import type { HerdrKit } from './kit.ts';
+export type HerdrScope = {
+    workspaces: 'all' | string[];
+};
+export declare function herdrLink(kit: HerdrKit, o: {
+    scopeOf: (grant: Grant) => HerdrScope;
+    passThrough?: (method: string, grant: Grant) => boolean;
+    relay?: RelayClient;
+}): Pick<HostOptions, 'handle' | 'stream' | 'allow'>;
+export declare function serve(o: {
+    host: Host;
+    port: number;
+    via?: Via;
+    previous?: ServeIngress;
+    http?: (req: IncomingMessage, res: ServerResponse) => void;
+}): Promise<{
+    urls: string[];
+    ingress?: ServeIngress;
+    close(): Promise<void>;
+}>;