@byokit/herdr 0.1.0-next.dbe7142 → 0.1.0

package/dist/device.d.ts

@@ -1,15 +1,44 @@
 import type { DeviceLink } from '@byokit/link';
-import type { AgentRef, BlockedAgent, HerdrSnapshot, HerdrState, PromptReceipt, StartAgent } from './types.ts';
+import type { AgentRef, AgentStatus, BlockedAgent, HerdrEventName, HerdrEventOf, HerdrMethod, HerdrParams, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, PromptReceipt, StartAgent } from './types.ts';
+export type { HerdrEventName, HerdrEventOf, HerdrEvents, HerdrMethod, HerdrMethods, HerdrParams, HerdrResult, HerdrSubscription, } from './types.ts';
+/** One `hd.events` frame (7.2); `raw` carries a line that was not JSON. */
+export type HerdrLinkEvent = {
+    type: 'snapshot';
+    snapshot: HerdrSnapshot;
+} | {
+    type: 'blocked';
+    change: 'added' | 'resolved';
+    blocked: BlockedAgent;
+} | {
+    type: 'raw';
+    line: string;
+};
+/** A terminal over the link (7.2): Herdr's NDJSON frames both ways. */
+export type DeviceTerminal = {
+    ready: Promise<void>;
+    exited: Promise<{
+        reason: string | null;
+    }>;
+    onFrame(fn: (line: string) => void): () => void;
+    send(line: string): void;
+    close(): void;
+};
 export { openNotice } from './notices.ts';
+export { agentWords, stateWords, words, WORDS, type WordKey } from './words.ts';
 export declare function herdrDevice(link: DeviceLink): {
     state(): Promise<{
         state: HerdrState;
         words: string;
     }>;
     tree(): Promise<HerdrSnapshot>;
+    agentKinds(): Promise<string[]>;
     startAgent(o: StartAgent): Promise<AgentRef>;
     prompt(paneId: string, text: string): Promise<PromptReceipt>;
     keys(paneId: string, keys: string[]): Promise<void>;
+    wait(paneId: string, o: {
+        until?: AgentStatus[];
+        timeoutMs: number;
+    }): Promise<AgentStatus>;
     read(paneId: string, o?: {
         source?: 'visible' | 'recent' | 'recent_unwrapped' | 'detection';
         lines?: number;
@@ -24,17 +53,14 @@ export declare function herdrDevice(link: DeviceLink): {
         tab?: string;
         workspace?: string;
     }): Promise<void>;
-    events(): AsyncIterable<unknown>;
+    events(): AsyncIterable<HerdrLinkEvent>;
+    subscribe<E extends HerdrEventName>(subs: HerdrSubscription<E>[], on: (e: HerdrEventOf<E>) => void, onError?: (message: string) => void): () => void;
     registerNotices(seed: Uint8Array): Promise<void>;
     openNotice(data: Record<string, unknown>, seed: Uint8Array): BlockedAgent | null;
-    call(method: string, params?: unknown): Promise<unknown>;
+    call<M extends HerdrMethod>(method: M, params: HerdrParams<M>): Promise<HerdrResult<M>>;
     terminal(paneId: string, o: {
         mode: 'control' | 'observe';
         cols: number;
         rows: number;
-    }): {
-        onFrame(fn: (line: string) => void): () => void;
-        send(line: string): void;
-        close(): void;
-    };
+    }): DeviceTerminal;
 };

package/dist/device.js

@@ -1,4 +1,5 @@
 export { openNotice } from "./notices.js";
+export { agentWords, stateWords, words, WORDS } from "./words.js";
 import { boxPublicKeyB64, openNotice } from "./notices.js";
 const decodeLines = () => {
     const text = new TextDecoder();
@@ -18,42 +19,73 @@ const decodeLines = () => {
         },
     };
 };
-/** A link stream as newline-delimited JSON frames; unparsed lines surface as `{ type: 'raw', line }`. */
-async function* streamFrames(link, op, args) {
-    const s = await link.stream(op, args);
-    const ready = [];
-    let wake;
-    let ended = false;
-    const lines = decodeLines();
-    const emit = (frame) => {
-        ready.push(frame);
-        wake?.();
-        wake = undefined;
-    };
-    s.onData = (chunk) => {
-        for (const line of lines.push(chunk)) {
-            try {
-                emit(JSON.parse(line));
-            }
-            catch {
-                emit({ type: 'raw', line });
-            }
-        }
-    };
-    s.onEnd = () => {
-        for (const line of lines.flush())
-            emit({ type: 'raw', line });
-        ended = true;
-        wake?.();
-        wake = undefined;
+/**
+ * A link stream as newline-delimited JSON frames; unparsed lines surface as `{ type: 'raw', line }`. A plain
+ * iterator rather than an async generator: `return()` (a `break`, or a view that stops watching) ends the link
+ * stream even while a `next()` waits for the next frame, which a generator parked at an await cannot do.
+ */
+function streamFrames(link, op, args) {
+    return {
+        [Symbol.asyncIterator]() {
+            const ready = [];
+            const lines = decodeLines();
+            let s;
+            let opening;
+            let failed;
+            let ended = false;
+            let closed = false;
+            let wake;
+            const rouse = () => { wake?.(); wake = undefined; };
+            const emit = (frame) => { ready.push(frame); rouse(); };
+            const open = () => opening ??= link.stream(op, args).then((opened) => {
+                if (closed) {
+                    opened.end();
+                    return;
+                }
+                s = opened;
+                opened.onData = (chunk) => {
+                    for (const line of lines.push(chunk)) {
+                        try {
+                            emit(JSON.parse(line));
+                        }
+                        catch {
+                            emit({ type: 'raw', line });
+                        }
+                    }
+                };
+                opened.onEnd = () => {
+                    for (const line of lines.flush())
+                        emit({ type: 'raw', line });
+                    ended = true;
+                    rouse();
+                };
+            }, (error) => { failed = { error }; rouse(); });
+            return {
+                async next() {
+                    void open();
+                    for (;;) {
+                        if (closed)
+                            return { value: undefined, done: true };
+                        if (ready.length > 0)
+                            return { value: ready.shift(), done: false };
+                        if (failed)
+                            throw failed.error;
+                        if (ended)
+                            return { value: undefined, done: true };
+                        await new Promise((resolve) => { wake = resolve; });
+                    }
+                },
+                async return() {
+                    if (!closed) {
+                        closed = true;
+                        s?.end();
+                        rouse();
+                    }
+                    return { value: undefined, done: true };
+                },
+            };
+        },
     };
-    for (;;) {
-        while (ready.length > 0)
-            yield ready.shift();
-        if (ended)
-            return;
-        await new Promise((resolve) => { wake = resolve; });
-    }
 }
 const terminalHandle = (opening) => {
     const listeners = new Set();
@@ -61,8 +93,29 @@ const terminalHandle = (opening) => {
     let s;
     const queued = [];
     let dead = false;
-    // The frozen H7 signature returns the handle synchronously; the stream opens underneath and
-    // sends made before it opens queue until then (frames cannot arrive before the open anyway).
+    let framed = false;
+    let markReady;
+    let failReady;
+    let markExited;
+    const ready = new Promise((resolve, reject) => { markReady = resolve; failReady = reject; });
+    const exited = new Promise((resolve) => { markExited = resolve; });
+    ready.catch(() => { }); // an app that never awaits ready must not see an unhandled rejection
+    const deliver = (line) => {
+        if (!framed) {
+            framed = true;
+            markReady();
+        }
+        for (const fn of listeners)
+            fn(line);
+    };
+    const finish = (reason) => {
+        dead = true;
+        if (!framed)
+            failReady(new Error(reason ?? 'herdr: the terminal ended before its first frame'));
+        markExited({ reason });
+    };
+    // The handle returns synchronously; the stream opens underneath and sends made before it opens
+    // queue until then (frames cannot arrive before the open anyway).
     opening.then((opened) => {
         if (dead) {
             opened.end();
@@ -70,32 +123,79 @@ const terminalHandle = (opening) => {
         }
         s = opened;
         opened.onData = (chunk) => {
-            for (const line of lines.push(chunk)) {
-                for (const fn of listeners)
-                    fn(line);
-            }
+            for (const line of lines.push(chunk))
+                deliver(line);
         };
-        opened.onEnd = () => {
-            for (const line of lines.flush()) {
-                for (const fn of listeners)
-                    fn(line);
-            }
+        opened.onEnd = (error) => {
+            for (const line of lines.flush())
+                deliver(line);
+            finish(error ?? null);
         };
         for (const line of queued.splice(0))
             void opened.write(`${line}\n`).catch(() => { });
-    }, () => { dead = true; });
+    }, (e) => { finish(e instanceof Error ? e.message : 'failed'); });
     return {
+        ready,
+        exited,
         onFrame: (fn) => {
             listeners.add(fn);
             return () => { listeners.delete(fn); };
         },
         send: (line) => {
-            if (s !== undefined)
+            if (s !== undefined && !dead)
                 void s.write(`${line}\n`).catch(() => { });
             else if (!dead)
                 queued.push(line);
         },
-        close: () => { dead = true; s?.end(); },
+        close: () => {
+            if (dead)
+                return;
+            s?.end();
+            finish(null);
+        },
+    };
+};
+/** `hd.subscribe`: one parsed frame per Herdr event; a host end with words reaches `onError`. */
+const subscription = (opening, on, onError) => {
+    const lines = decodeLines();
+    let s;
+    let stopped = false;
+    const deliver = (line) => {
+        let frame;
+        try {
+            frame = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (!stopped)
+            on(frame);
+    };
+    opening.then((opened) => {
+        if (stopped) {
+            opened.end();
+            return;
+        }
+        s = opened;
+        opened.onData = (chunk) => { for (const line of lines.push(chunk))
+            deliver(line); };
+        opened.onEnd = (error) => {
+            for (const line of lines.flush())
+                deliver(line);
+            if (!stopped && error !== undefined)
+                onError?.(error);
+            stopped = true;
+        };
+    }, (e) => {
+        if (!stopped)
+            onError?.(e instanceof Error ? e.message : 'failed');
+        stopped = true;
+    });
+    return () => {
+        if (stopped)
+            return;
+        stopped = true;
+        s?.end();
     };
 };
 export function herdrDevice(link) {
@@ -104,11 +204,13 @@ export function herdrDevice(link) {
     return {
         state: () => link.request('hd.state', {}),
         tree: () => link.request('hd.tree', {}),
+        agentKinds: () => link.request('hd.kinds', {}),
         startAgent: (o) => link.request('hd.agent.start', o),
         prompt: (paneId, text) => link.request('hd.prompt', { paneId, text }),
         keys: async (paneId, keys) => {
             await link.request('hd.keys', { paneId, keys });
         },
+        wait: (paneId, o) => link.request('hd.wait', { paneId, ...o }),
         read: (paneId, o) => link.request('hd.read', { paneId, ...o }),
         blocked: () => link.request('hd.blocked', {}),
         answer: async (paneId, keys, revision) => {
@@ -118,6 +220,7 @@ export function herdrDevice(link) {
             await link.request('hd.close', o);
         },
         events: () => streamFrames(link, 'hd.events', {}),
+        subscribe: (subs, on, onError) => subscription(link.stream('hd.subscribe', { subs }), on, onError),
         registerNotices: async (seed) => {
             await link.request('hd.notices.register', { boxPublicKey: boxPublicKeyB64(seed) });
         },

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 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';
+export { agentWords, stateWords, words, WORDS, type WordKey } from './words.ts';
+export type { AgentRef, AgentStatus, BlockedAgent, HerdrEvent, HerdrEventName, HerdrEventOf, HerdrKitOptions, HerdrMethod, HerdrMethods, HerdrParams, HerdrProtocolRange, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, HerdrTransport, PromptReceipt, StartAgent, TerminalSession, } from './types.ts';

package/dist/index.js

@@ -2,3 +2,4 @@
 // 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";
+export { agentWords, stateWords, words, WORDS } from "./words.js";

package/dist/kit.d.ts

@@ -1,13 +1,17 @@
-import type { AgentRef, AgentStatus, BlockedAgent, HerdrEventName, HerdrEventOf, HerdrKitOptions, HerdrMethod, HerdrParams, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, PromptReceipt, StartAgent, TerminalSession } from './types.ts';
+import type { AgentRef, AgentStatus, BlockedAgent, HerdrEvent, 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 rawListeners;
+    private statusReadyPromise;
+    private statusReadyResolve?;
     private stops;
     private statusStops;
     private generation;
+    private statusEpoch;
     private readonly o;
     private readonly callAny;
     private readonly agents;
@@ -15,14 +19,20 @@ export declare class HerdrKit {
     constructor(o: HerdrKitOptions);
     get state(): HerdrState;
     private publish;
+    private emitRaw;
     private update;
     private bootstrap;
+    /**
+     * Connect and bootstrap. Non-fatal: a rejected `start()` (e.g. `failed/socket` while Herdr is
+     * down) leaves the kit stopped, and `start()` may be called again afterwards — the host comes up
+     * while Herdr is down by retrying `start()` in a backoff loop until it reaches `ready`.
+     */
     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;
+    subscribe<E extends HerdrEventName>(subs: HerdrSubscription<E>[], on: (e: HerdrEventOf<E>) => void, onError?: (code: string, message: string) => void): () => void;
     cli(args: string[], o?: {
         timeoutMs?: number;
     }): Promise<{
@@ -38,6 +48,21 @@ export declare class HerdrKit {
     }): TerminalSession;
     snapshot(): HerdrSnapshot;
     onChange(fn: (s: HerdrSnapshot) => void): () => void;
+    /**
+     * Raw event tap (K3): delivers every event arriving on the kit's own batch and per-pane
+     * status sockets, with wire payloads intact (`pane.moved.previous_pane_id`, `workspace.*`).
+     * Fires on arrival — before the snapshot update/refresh for that event — so a listener sees
+     * the frame even when it triggers a re-bootstrap. Buffered replays never re-fire. Sockets
+     * opened via `subscribe()` are NOT tapped; `onEvent` itself opens no socket.
+     */
+    onEvent(fn: (e: HerdrEvent) => void): () => void;
+    /**
+     * Ready signal for the status-watch set (K3): resolves when the latest bootstrap's per-pane
+     * `pane.agent_status_changed` subscriptions have acked (immediately when no pane needs one).
+     * Await after `start()` — and after any reconnect-driven re-bootstrap — before relying on
+     * status events instead of opening a second watch.
+     */
+    statusWatchReady(): Promise<void>;
     startAgent(o: StartAgent): Promise<AgentRef>;
     prompt(target: AgentRef, text: string, o?: {
         wait?: {
@@ -69,5 +94,6 @@ export declare class HerdrKit {
     agentKinds(): Promise<string[]>;
     installedAgentKinds(kinds: readonly string[], o: {
         path: string[];
+        aliases?: Record<string, string[]>;
     }): string[];
 }