@byokit/herdr 0.1.1 → 0.1.6

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## Unreleased
 
+## 0.1.6 (2026-09-30)
+
+- Depends on @byokit/relay 0.3.0.
+
+## 0.1.5 (2026-09-30)
+
+- Depends on @byokit/relay 0.2.2.
+- Depends on @byokit/link 0.4.0.
+
+- The test fake's `fake.stream` ends with one `fake.stream.done` line on the same ordered byte stream, so the
+  paused-terminal backpressure test asserts delivery causally instead of on a wall-clock wait.
+
+## 0.1.4 (2026-09-30)
+
+- Preserve seed-based notice opening with @byokit/seal 0.2.0.
+
+## 0.1.3
+
+- Depends on @byokit/reach 0.3.0.
+
+## 0.1.2 (2026-09-29)
+
+- FIX: `prompt` now reaches an agent that was already running when the app connected. Herdr marks only
+  the agents its own `agent.start` launched as interactive-ready, so an agent started by hand or by
+  another app was refused forever; and a snapshot read while an agent was still launching kept it
+  marked as launching, because Herdr never pushes the end of a launch. The kit no longer gates on
+  interactive-ready, and before refusing a prompt it re-reads the agent once from Herdr.
+- FIX: when Herdr itself refuses a prompt as not ready, `prompt` now fails with `agent-not-ready`
+  like the kit's own check, not with Herdr's raw `agent_not_ready` error.
+- The test fake leaves `launch_pending` and `interactive_ready` out when they are false, as Herdr v0.9.1 does.
+- Depends on @byokit/relay 0.2.1.
+
 ## 0.1.1 (2026-09-29)
 
 - SECURITY: (from @byokit/relay 0.2.0) Removing a phone now reliably stops its push notifications, even if the relay was down or restarting when you removed it. Before, `RelayClient.revoke` dropped the device's grant and sent one unsubscribe that was lost if the offline queue overflowed or the host stopped or restarted before the relay was back, so the relay kept the phone's push address. Now the unsubscribe is saved first and resent on every connection until the relay confirms it; `revoke()` resolves then. Pass a durable `store` to `RelayClient` so a pending unsubscribe survives a restart (the default is memory).

package/dist/agents.d.ts

@@ -4,4 +4,5 @@ export type Call = (method: string, params: Record<string, unknown>, timeoutMs?:
 export declare function createAgents(ctx: {
     call: Call;
     snapshot(): HerdrSnapshot;
+    reread(paneId: string): Promise<void>;
 }): Pick<HerdrKit, 'startAgent' | 'prompt' | 'sendKeys' | 'wait' | 'read' | 'agentKinds' | 'installedAgentKinds'>;

package/dist/agents.js

@@ -109,11 +109,18 @@ export function createAgents(ctx) {
         }
     }
     async function prompt(target, text, o) {
-        // The readiness gate reads the kit's own tree: a not-promptable agent is refused with no socket call.
-        const agent = agentOf(ctx.snapshot(), target.paneId);
-        if (agent === undefined || agent.launchPending === true || agent.interactiveReady === false
-            || !PROMPTABLE.includes(agent.status)) {
-            throw fail('agent-not-ready', 'That agent is not ready for a prompt yet.');
+        // The readiness gate reads the kit's own tree, re-read once before a refusal: `launch_pending`
+        // rides reads only, so a snapshot taken mid-launch goes stale. `interactive_ready` is not gated:
+        // Herdr sets it only for agents its own `agent.start` settled, and its `agent.prompt` accepts the
+        // rest. A refusal never sends `agent.prompt`.
+        const ready = () => {
+            const agent = agentOf(ctx.snapshot(), target.paneId);
+            return agent !== undefined && agent.launchPending !== true && PROMPTABLE.includes(agent.status);
+        };
+        if (!ready()) {
+            await ctx.reread(target.paneId);
+            if (!ready())
+                throw fail('agent-not-ready', 'That agent is not ready for a prompt yet.');
         }
         const wait = o?.wait === undefined ? undefined
             : { timeout_ms: o.wait.timeoutMs, ...(o.wait.until === undefined ? {} : { until: o.wait.until }) };
@@ -123,9 +130,14 @@ export function createAgents(ctx) {
                 ...(wait === undefined ? {} : { wait }) });
         }
         catch (error) {
-            if (error?.code === 'agent_blocked') {
+            const code = error?.code;
+            if (code === 'agent_blocked') {
                 throw fail('agent-blocked', 'That agent is blocked and needs an answer before a new prompt.');
             }
+            // Herdr's own gate (unknown agent kind, launch pending, not the pane's foreground process).
+            if (code === 'agent_not_ready') {
+                throw fail('agent-not-ready', 'That agent is not ready for a prompt yet.');
+            }
             throw error;
         }
         const body = isObj(receipt) ? receipt : undefined;

package/dist/kit.d.ts

@@ -23,7 +23,7 @@ export declare class HerdrKit {
     private watchError;
     private update;
     private bootstrap;
-    private catchUp;
+    private reread;
     /**
      * 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

package/dist/kit.js

@@ -131,7 +131,8 @@ export class HerdrKit {
     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.agents = createAgents({ call: this.callAny, snapshot: () => this.snapshot(),
+            reread: (paneId) => this.reread(paneId) });
         this.blockedList = new Blocked({ call: this.callAny });
     }
     get state() { return this.current; }
@@ -292,16 +293,18 @@ export class HerdrKit {
             this.statusStops.add(stop);
             const ready = stop.ready;
             if (ready)
-                statusAcks.push(ready.then((ok) => (ok === false ? undefined : this.catchUp(token, pane.id))));
+                statusAcks.push(ready.then((ok) => (ok === false ? undefined : this.reread(pane.id, token))));
         }
         void Promise.allSettled(statusAcks).then(() => { if (token === this.generation)
             resolveStatus(); });
         this.current = newer ? { phase: 'needs-update', why: 'version' } : { phase: 'ready' };
         this.o.onState?.(this.current);
     }
-    // A status change between the snapshot read and a watch's ack reached no socket: once the watch
-    // is live, re-read that agent. A push landing meanwhile is newer and wins (epoch guard).
-    async catchUp(token, paneId) {
+    // Re-read one agent and land its status, revision and launch flags: after a watch acks (a status
+    // change before the ack reached no socket) and before `prompt` refuses (`launch_pending` rides
+    // reads only, never a push). A push landing meanwhile is newer and wins status and revision (epoch
+    // guard); the launch flags still land, since no push carries them.
+    async reread(paneId, token = this.generation) {
         const epoch = this.statusEpoch.get(paneId);
         let made;
         try {
@@ -311,12 +314,21 @@ export class HerdrKit {
             return;
         }
         const agent = made?.agent;
-        if (token !== this.generation || this.statusEpoch.get(paneId) !== epoch ||
-            typeof agent?.agent_status !== 'string')
+        if (token !== this.generation || typeof agent?.agent_status !== 'string')
             return;
-        // Status and revision only: the read's other fields may be staler than a merged pane.updated.
+        // v0.9.1 leaves both flags out when false (`skip_serializing_if = is_false`): absent means false.
+        const flags = { launch_pending: agent.launch_pending === true, interactive_ready: agent.interactive_ready === true };
+        if (this.statusEpoch.get(paneId) !== epoch) {
+            const pane = findPane(this.tree, paneId);
+            if (pane?.agent !== undefined) {
+                pane.agent = mergeAgent(pane.agent, flags);
+                this.publish();
+            }
+            return;
+        }
+        // The read's other fields may be staler than a merged pane.updated.
         this.update({ type: 'pane_agent_status_changed', pane_id: paneId, agent_status: agent.agent_status,
-            ...(typeof agent.revision === 'number' ? { revision: agent.revision } : {}) });
+            ...(typeof agent.revision === 'number' ? { revision: agent.revision } : {}), ...flags });
     }
     /**
      * Connect and bootstrap. Non-fatal: a rejected `start()` (e.g. `failed/socket` while Herdr is

package/dist/notices.js

@@ -1,6 +1,6 @@
 // Sealed blocked-approval notices: the relay reads only a generic title, the phone opens the sealed body with its
 // own key (docs/runtime-kits.md 7.3). Portable: no Node import anywhere in it — `./device` re-exports `openNotice`.
-import { boxKeyPairFromSeed, openBox, sealBox } from '@byokit/seal';
+import { boxKeyPairFromSeed, openBoxFromSeed, sealBox } from '@byokit/seal';
 const ABC = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
 /** Base64url without padding, hand-rolled so this file stays portable (no Buffer, no atob). */
 export function encodeB64Url(bytes) {
@@ -68,7 +68,7 @@ export function openNotice(data, seed) {
     const bundle = decodeB64Url(data.sealed);
     if (bundle === null)
         return null;
-    const bytes = openBox(bundle, seed);
+    const bytes = openBoxFromSeed(bundle, seed);
     if (bytes === null)
         return null;
     let parsed;

package/dist/testing/fake-herdr/bin.js

@@ -88,19 +88,24 @@ async function runServer() {
 // resizes the session and answers one empty frame stamped with the new size; `terminal.release`
 // exits; `{"type":"fake.stream","count":n,"size":b,"progress":file}` streams n frames with full
 // `<i>:` plus b bytes as fast as the pipe takes them, recording the frames-written count in
-// `progress` after each write so a test can see how far a paused reader let the stream run.
+// `progress` after each write so a test can see how far a paused reader let the stream run, then
+// one `{"type":"fake.stream.done","count":n}` line on the same ordered byte stream: when a test sees
+// the marker, every stream frame is already past every frame handler, so the delivery verdict is
+// causal instead of a wall-clock wait (a stall then means a genuinely wedged child, not a slow one).
 function frame(paneId, full, extra = {}) {
     return `${JSON.stringify({ type: 'terminal.frame', pane_id: paneId, data: full, full, bytes: Buffer.byteLength(full), ...extra })}\n`;
 }
 async function stream(paneId, o) {
+    const count = o.count ?? 0;
     const pad = 'x'.repeat(o.size ?? 1024);
-    for (let i = 0; i < (o.count ?? 0); i += 1) {
+    for (let i = 0; i < count; i += 1) {
         const ok = process.stdout.write(frame(paneId, `${i}:${pad}`));
         if (o.progress)
             writeFileSync(o.progress, String(i + 1));
         if (!ok)
             await new Promise((resolve) => process.stdout.once('drain', resolve));
     }
+    process.stdout.write(`${JSON.stringify({ type: 'fake.stream.done', pane_id: paneId, count })}\n`);
 }
 function runTerminal(args) {
     // `herdr terminal session <control|observe> <pane> [--takeover] --cols <n> --rows <n>`.

package/dist/testing/fake-herdr/server.js

@@ -423,12 +423,12 @@ export async function startFakeHerdr(options) {
             }
             return { target: p.target, keys };
         },
-        'agent.list': () => ({ agents: live.agents.map((agent) => ({ ...agent })) }),
+        'agent.list': () => ({ agents: live.agents.map(agentWire) }),
         'agent.get': (p) => {
             const agent = live.agents.find((row) => row.pane_id === p.target);
             if (agent === undefined)
                 throw fail('agent_not_found', 'agent not found');
-            return { agent };
+            return { agent: agentWire(agent) };
         },
         'server.agent_manifests': () => ({ manifests: kinds.map((kind) => ({ agent: kind })) }),
         'plugin.list': (p) => {
@@ -607,10 +607,15 @@ export async function startFakeHerdr(options) {
     function agentOf(pane) {
         return live.agents.find((row) => row.pane_id === pane.pane_id);
     }
+    // v0.9.1 serializes `launch_pending`/`interactive_ready` only when true (`skip_serializing_if = is_false`).
+    function agentWire(agent) {
+        const { launch_pending, interactive_ready, ...rest } = agent;
+        return { ...rest, ...(launch_pending ? { launch_pending } : {}), ...(interactive_ready ? { interactive_ready } : {}) };
+    }
     function agentView(paneId) {
         const agent = live.agents.find((row) => row.pane_id === paneId);
         if (agent !== undefined)
-            return { agent: { ...agent } };
+            return { agent: agentWire(agent) };
         const pane = live.panes.find((row) => row.pane_id === paneId);
         return { agent: { pane_id: paneId, agent_status: pane?.agent_status ?? 'unknown', interactive_ready: true } };
     }
@@ -658,7 +663,7 @@ export async function startFakeHerdr(options) {
             workspaces: live.workspaces.map(workspaceView),
             tabs: live.tabs.map((tab) => ({ ...tab })),
             panes: live.panes.map(paneView),
-            agents: live.agents.map((agent) => ({ ...agent })),
+            agents: live.agents.map(agentWire),
             layouts: [],
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/herdr",
-  "version": "0.1.1",
+  "version": "0.1.6",
   "description": "Drive the Herdr on this computer — workspaces, tabs, panes, agents and blocked-approval answers — from an app, or hand it to a phone over @byokit/link.",
   "license": "Apache-2.0",
   "type": "module",
@@ -52,10 +52,10 @@
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
   },
   "dependencies": {
-    "@byokit/link": "0.3.2",
-    "@byokit/relay": "0.2.0",
-    "@byokit/reach": "0.2.0",
-    "@byokit/seal": "0.1.0",
+    "@byokit/link": "0.4.0",
+    "@byokit/relay": "0.3.0",
+    "@byokit/reach": "0.3.0",
+    "@byokit/seal": "0.2.0",
     "ws": "8.21.3"
   },
   "publishConfig": {