@byokit/herdr 0.7.2 → 0.7.3

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.7.3 (2026-10-11)
+
+- Dependency update: pins @byokit/discover 0.7.0.
+
+- `@byokit/herdr` exports `isPromptable(agent)`, the single readiness gate `prompt` already used, and adds
+  `kit.waitPromptable(target, { timeoutMs })`: it waits until a just-started agent can take a prompt instead of the
+  host polling `prompt` and catching `agent-not-ready`. It resolves once the kit's snapshot is promptable, rejects
+  `agent-not-ready` at the deadline, and rejects `pane-unavailable` when the pane closes mid-wait.
+- The README's rename note and examples now point at `@byokit/pair` (the phone hand-off host) and the
+  example screenshots were re-captured from today's herdr-kit phone page. Docs only; no typed surface changed.
+- Dependency update: depend on `@byokit/pair` 0.9.0 instead of its deprecated `@byokit/link` shim.
+
 ## 0.7.2 (2026-10-09)
 
 - Dependency update: pins @byokit/relay 0.6.0.

package/README.md

@@ -8,13 +8,16 @@
 
 <p align="center"><strong>Drive the Herdr already on this computer from an app, or from a phone.</strong><br/>
 Workspaces, tabs, panes, coding agents and blocked-approval answers, from a Node app or handed to a phone over
-<a href="../link"><code>@byokit/link</code></a>. Each agent inside Herdr keeps its own subscription login; the kit
+<a href="../pair"><code>@byokit/pair</code></a>. Each agent inside Herdr keeps its own subscription login; the kit
 never sees a credential.</p>
 
+<p align="center"><sub>This kit depends on <a href="../pair"><code>@byokit/pair</code></a>, and its examples
+import from there.</sub></p>
+
 <p align="center">
-  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/3-agent.png" width="240" alt="Phone page titled Agents, Connected to Kitchen computer and Connected to Herdr: two pi agents marked Ready for you, and under Talk to it the agent's screen reading '> Add a --json flag to export', 'Read src/cli/export.ts', 'Edited src/cli/export.ts +18 -3' and 'export --json now prints JSON.' above a Message box, a Send button and Sent." />
-  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/4-question.png" width="240" alt="Phone page with Questions for you at the top: pi, Waiting for your answer., the question 'Allow this? (y/n)' and buttons Enter, y, n and Esc; below, the second pi agent marked Waiting for your answer." />
-  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/5-answered.png" width="240" alt="Phone page after the answer: no Questions for you section, both pi agents marked Ready for you, and the agent's screen ending in 'Allow this? (y/n)', 'y' and 'npm test: 42 passing'" />
+  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/3-agent.png" width="240" alt="Phone page titled Agents, Connected to Kitchen computer - same Wi-Fi.: two Pi agents marked Ready for you, and under Talk to it the agent's screen reading '> Add a --json flag to export', 'Read src/cli/export.ts', 'Edited src/cli/export.ts +18 -3' and 'export --json now prints JSON.' above a Message box, a Send button and Waiting for the reply below." />
+  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/4-question.png" width="240" alt="Phone page with Questions for you at the top: Pi, Waiting for your answer., the question 'Allow this? (y/n)' and buttons Allow, Deny and Skip; below, the second Pi agent marked Waiting for your answer." />
+  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/5-answered.png" width="240" alt="Phone page after the answer: no Questions for you section, both Pi agents marked Ready for you, and the agent's screen ending in 'Allow this? (y/n)', 'y' and 'npm test: 42 passing'" />
 </p>
 <p align="center"><sub>The <a href="../../examples/herdr-kit">herdr-kit example</a>'s phone page: an agent at work, its
 question, answered. Captured by the example's e2e in a phone-sized headless Chromium, against the kit's stand-in
@@ -90,7 +93,7 @@ Waiting for your answer. | Allow this? (y/n)
 idle
 ```
 
-To hand Herdr to a phone, spread `herdrLink` into a `@byokit/link` host and serve it; the phone calls the same
+To hand Herdr to a phone, spread `herdrLink` into a `@byokit/pair` host and serve it; the phone calls the same
 things through `herdrDevice`:
 
 ```ts
@@ -106,8 +109,8 @@ const own = new HerdrKit({ mode: 'own', bin, stateDir: './.state' });
 ```ts
 import { HerdrKit } from '@byokit/herdr';
 import { herdrLink, serve } from '@byokit/herdr/link';
-import { Host, type Grant } from '@byokit/link';
-import { hostKeyFile } from '@byokit/link/node';
+import { Host, type Grant } from '@byokit/pair';
+import { hostKeyFile } from '@byokit/pair/node';
 
 const kit = new HerdrKit({ mode: 'own', bin: '/usr/local/bin/herdr', stateDir: './.state' });
 const grants: Grant[] = [];
@@ -128,7 +131,7 @@ kit.start().catch(() => {});        // non-fatal: retry later while Herdr is dow
 ```
 
 ```ts
-import type { DeviceLink } from '@byokit/link';
+import type { DeviceLink } from '@byokit/pair';
 import { agentWords, herdrDevice } from '@byokit/herdr/device';
 
 declare const link: DeviceLink;     // from pairing (pairWithCode / pairWithOffer)
@@ -153,8 +156,8 @@ kit does not have yet, and [Two ways in](#two-ways-in) plus
 
 | Export | What it does |
 |---|---|
-| `HerdrKit` (`@byokit/herdr`) | The host-side kit, in `adopt` or `own` mode: `start`/`stop`, `state`, `snapshot`/`onChange`, `startAgent`, `openSignInTab`, `move`, `moveToAccount`, `onStartAgent`, `prompt`, `sendKeys`, `wait`, `read`, `blocked`/`onBlocked`/`answer`, `closePane`/`closeTab`/`closeWorkspace`, `agentKinds`, `installedAgentKinds`, `agentStatus`, `agentInstallState`, `terminal`, `onEvent`, `statusWatchReady`, and the pass-throughs `call`, `subscribe` and `cli` |
-| `agentStatus`, `agentInstallState`, `agentProbePath`, `extraPathDirs`, `runStatusCommand`, `isAutoInstallShim`, `resolveAgentBinary` (`@byokit/herdr`) | Onboarding readiness: per-kind install + CLI sign-in without a Herdr connection (see below) |
+| `HerdrKit` (`@byokit/herdr`) | The host-side kit, in `adopt` or `own` mode: `start`/`stop`, `state`, `snapshot`/`onChange`, `startAgent`, `openSignInTab`, `move`, `moveToAccount`, `onStartAgent`, `prompt`, `waitPromptable`, `sendKeys`, `wait`, `read`, `blocked`/`onBlocked`/`answer`, `closePane`/`closeTab`/`closeWorkspace`, `agentKinds`, `installedAgentKinds`, `agentStatus`, `agentInstallState`, `terminal`, `onEvent`, `statusWatchReady`, and the pass-throughs `call`, `subscribe` and `cli` |
+| `isPromptable`, `agentStatus`, `agentInstallState`, `agentProbePath`, `extraPathDirs`, `runStatusCommand`, `isAutoInstallShim`, `resolveAgentBinary` (`@byokit/herdr`) | `isPromptable(agent)` is the readiness rule `prompt` and `waitPromptable` share; the rest is onboarding readiness: per-kind install + CLI sign-in without a Herdr connection (see below) |
 | `HERDR_VERSION`, `HERDR_PROTOCOL` | The pinned Herdr release (`0.9.1`) and the protocol the kit speaks (`22`) |
 | `words`, `agentWords`, `stateWords`, `WORDS` | Plain sentences for agent statuses and kit states |
 | `herdrLink` (`@byokit/herdr/link`) | The host side of the `hd.*` link ops, spread into `Host.open`; scopes each grant to its workspaces and can push sealed approval notices through a relay |
@@ -174,6 +177,12 @@ null), `agentSession` is absent; callers can fall back to their existing checks.
 Types (`HerdrKitOptions`, `HerdrState`, `StartAgent`, `PromptReceipt`, `BlockedAgent`, `HerdrSnapshot`,
 `HerdrMethod`/`HerdrParams`/`HerdrResult`, `HerdrEventName`/`HerdrEventOf`, ...) come from the main entry.
 
+A just-started agent is not promptable until its launch settles. Instead of polling `prompt` and catching
+`agent-not-ready`, wait once: `await kit.waitPromptable(agent, { timeoutMs: 30_000 })` resolves the moment the
+kit's snapshot is promptable — the same gate (`isPromptable`: not `launch_pending` and status idle/working/blocked/done)
+`prompt` itself uses. At the deadline it rejects with code `agent-not-ready`; a pane that closes while waiting rejects
+with code `pane-unavailable`, so the wait never hangs.
+
 ## Account-specific sign-ins and moves
 
 The host supplies account folders and shares conversation history as needed. The kit never reads or copies

package/dist/agents.d.ts

@@ -1,13 +1,14 @@
 import type { HerdrKit } from './kit.ts';
-import type { AgentInstallProbe, AgentInstallState, AgentLaunchFailureReason, AgentStartEvent, HerdrSnapshot } from './types.ts';
+import type { AgentInstallProbe, AgentInstallState, AgentLaunchFailureReason, AgentStartEvent, HerdrSnapshot, HerdrSnapshotAgent } from './types.ts';
 export type Call = (method: string, params: Record<string, unknown>, timeoutMs?: number) => Promise<unknown>;
+export declare function isPromptable(agent: HerdrSnapshotAgent | undefined): boolean;
 export declare function createAgents(ctx: {
     call: Call;
     snapshot(): HerdrSnapshot;
     reread(paneId: string): Promise<void>;
     emitStart?(e: AgentStartEvent): void;
     launchEnv?(): Record<string, string> | undefined;
-}): Pick<HerdrKit, 'startAgent' | 'prompt' | 'sendKeys' | 'wait' | 'read' | 'agentKinds' | 'installedAgentKinds' | 'agentStatus'>;
+}): Pick<HerdrKit, 'startAgent' | 'prompt' | 'waitPromptable' | 'sendKeys' | 'wait' | 'read' | 'agentKinds' | 'installedAgentKinds' | 'agentStatus'>;
 export declare function resolveAgentBinary(kind: string, o: {
     path: string[];
     aliases?: Record<string, string[]>;

package/dist/agents.js

@@ -12,6 +12,7 @@ import { prepareLaunchEnv } from "./launch-env.js";
 import { museNative, MUSE_INSTALL_URL } from "./muse.js";
 const PROMPTABLE = ['idle', 'working', 'blocked', 'done'];
 const DEFAULT_TIMEOUT_MS = 60_000;
+const WAIT_PROMPTABLE_POLL_MS = 50;
 // `agent.start` lands while the fresh pane is still at its shell prompt: the server answers
 // `agent_pane_busy`/`agent_pane_unavailable` until the pane is ready. The kit retries those for a
 // bounded 5 s, then rolls the pane it created back with `pane.close` like any other start failure.
@@ -36,6 +37,12 @@ function agentOf(snapshot, paneId) {
             }
     return undefined;
 }
+// The one readiness gate (6.4): an agent record is promptable when it exists, is not mid-launch and
+// its status is one Herdr accepts a prompt in. `prompt` refuses with `agent-not-ready` and
+// `waitPromptable` waits, both through this single rule.
+export function isPromptable(agent) {
+    return agent !== undefined && agent.launchPending !== true && PROMPTABLE.includes(agent.status);
+}
 // `agent.start` requires a name matching /^[a-z][a-z0-9_-]{0,31}$/; derive one from the kind when absent.
 function agentName(o) {
     const slug = (o.name ?? o.kind).toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^[-_0-9]+/, '').slice(0, 32);
@@ -205,10 +212,7 @@ export function createAgents(ctx) {
         // 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);
-        };
+        const ready = () => isPromptable(agentOf(ctx.snapshot(), target.paneId));
         if (!ready()) {
             await ctx.reread(target.paneId);
             if (!ready())
@@ -249,6 +253,35 @@ export function createAgents(ctx) {
         return { paneId: a.pane_id, terminalId: a.terminal_id, revision: a.revision, status: a.agent_status,
             ...(agentSession === undefined ? {} : { agentSession }) };
     }
+    // Wait until a just-started agent can take a prompt, instead of the host polling `prompt` and
+    // catching `agent-not-ready`. Resolves on the kit's own snapshot once `isPromptable` holds; the
+    // snapshot is re-read each pass because `launch_pending` rides `agent.get` reads only. A pane that
+    // closed while waiting rejects `pane-unavailable` (confirmed by an `agent_not_found` read); the
+    // deadline rejects `agent-not-ready`. Either way the wait never hangs.
+    async function waitPromptable(target, o) {
+        const deadline = Date.now() + o.timeoutMs;
+        const agent = () => agentOf(ctx.snapshot(), target.paneId);
+        for (;;) {
+            if (isPromptable(agent()))
+                return;
+            if (agent() === undefined) {
+                try {
+                    await call('agent.get', { target: target.paneId });
+                }
+                catch (error) {
+                    if (codeOf(error) === 'agent_not_found')
+                        throw fail('pane-unavailable', 'That pane is no longer available.');
+                    throw error;
+                }
+            }
+            if (Date.now() >= deadline)
+                throw fail('agent-not-ready', 'That agent is not ready for a prompt yet.');
+            await ctx.reread(target.paneId);
+            if (isPromptable(agent()))
+                return;
+            await sleep(WAIT_PROMPTABLE_POLL_MS);
+        }
+    }
     async function wait(target, o) {
         const made = await call('agent.wait', { target: target.paneId,
             ...(o.until === undefined ? {} : { until: o.until }), timeout_ms: o.timeoutMs });
@@ -312,7 +345,7 @@ export function createAgents(ctx) {
                 ...(signedIn === 'yes' ? {} : { signInHint: SIGNIN_HINTS[kind] ?? `Sign in to ${kind} on this computer, then check again.` }) };
         }));
     }
-    return { startAgent, prompt, sendKeys, wait, read, agentKinds, installedAgentKinds, agentStatus };
+    return { startAgent, prompt, waitPromptable, sendKeys, wait, read, agentKinds, installedAgentKinds, agentStatus };
 }
 // One source of truth for install detection (B5's probe plus the shim layer below): the first
 // executable file named for the kind across the probe path, with its absolute path.

package/dist/device.d.ts

@@ -1,4 +1,4 @@
-import type { DeviceLink } from '@byokit/link';
+import type { DeviceLink } from '@byokit/pair';
 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. */

package/dist/index.d.ts

@@ -4,5 +4,5 @@ export { HERDR_VERSION, HERDR_PROTOCOL } from './constants.ts';
 export { accountKinds, accountKind, type AccountKind } from './kinds.ts';
 export { HerdrKit } from './kit.ts';
 export { agentWords, stateWords, words, WORDS, type WordKey } from './words.ts';
-export { agentProbePath, extraPathDirs, runStatusCommand, agentInstallState, isAutoInstallShim, resolveAgentBinary, classifyStartFailure } from './agents.ts';
+export { agentProbePath, extraPathDirs, runStatusCommand, agentInstallState, isAutoInstallShim, resolveAgentBinary, classifyStartFailure, isPromptable } from './agents.ts';
 export type { AgentCliSignIn, AgentInstallProbe, AgentInstallState, AgentLaunchFailureReason, AgentReadiness, AgentStartEvent, AgentStatusOptions, AgentStatusRunner, AgentRef, AgentStatus, BlockedAgent, HerdrEvent, HerdrEventName, HerdrEventOf, HerdrKitOptions, HerdrMethod, HerdrMethods, HerdrParams, HerdrProtocolRange, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, HerdrSubscribeStop, HerdrTransport, BusyHandoff, Move, MoveToAccount, MoveToAccountResult, MoveResult, OpenSignInTab, PromptReceipt, StartAgent, TerminalSession, AgentTurnEnd, AgentTurnOptions, AgentTurnFiles, AgentTurnResult, AgentTurnResultPolicy, } from './types.ts';

package/dist/index.js

@@ -5,4 +5,4 @@ export { HERDR_VERSION, HERDR_PROTOCOL } from "./constants.js";
 export { accountKinds, accountKind } from "./kinds.js";
 export { HerdrKit } from "./kit.js";
 export { agentWords, stateWords, words, WORDS } from "./words.js";
-export { agentProbePath, extraPathDirs, runStatusCommand, agentInstallState, isAutoInstallShim, resolveAgentBinary, classifyStartFailure } from "./agents.js";
+export { agentProbePath, extraPathDirs, runStatusCommand, agentInstallState, isAutoInstallShim, resolveAgentBinary, classifyStartFailure, isPromptable } from "./agents.js";

package/dist/kit.d.ts

@@ -81,6 +81,9 @@ export declare class HerdrKit {
             timeoutMs: number;
         };
     }): Promise<PromptReceipt>;
+    waitPromptable(target: AgentRef, o: {
+        timeoutMs: number;
+    }): Promise<void>;
     runTurn<T = unknown>(target: AgentRef, o: AgentTurnOptions<T>): Promise<AgentTurnEnd<T>>;
     onTurnEnd(fn: (end: AgentTurnEnd) => void): () => void;
     sendKeys(target: AgentRef, keys: string[]): Promise<void>;

package/dist/kit.js

@@ -462,6 +462,7 @@ export class HerdrKit {
         return () => { this.startListeners.delete(fn); };
     }
     prompt(target, text, o) { return this.agents.prompt(target, text, o); }
+    waitPromptable(target, o) { return this.agents.waitPromptable(target, o); }
     runTurn(target, o) { return this.turns.runTurn(target, o); }
     onTurnEnd(fn) { return this.turns.onTurnEnd(fn); }
     sendKeys(target, keys) { return this.agents.sendKeys(target, keys); }

package/dist/link.d.ts

@@ -1,5 +1,5 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
-import { type Grant, type Host, type HostOptions } from '@byokit/link';
+import { type Grant, type Host, type HostOptions } from '@byokit/pair';
 import { type ServeIngress, type Via } from '@byokit/discover';
 import type { RelayClient } from '@byokit/relay';
 import type { HerdrKit } from './kit.ts';

package/dist/link.js

@@ -1,4 +1,4 @@
-// Host-side link adapter: the hd.* ops over @byokit/link, and the serve() wiring (duplicated per kit by design,
+// Host-side link adapter: the hd.* ops over @byokit/pair, and the serve() wiring (duplicated per kit by design,
 // D3) — built in H7 (docs/runtime-kits.md 7.1-7.3).
 //
 // Permission shape: `allow` lets every request through and `handle`/`stream` refuse with the `link.notAllowed`
@@ -6,7 +6,7 @@
 // generic `view-only`/`not-allowed` words instead).
 import { createServer } from 'node:http';
 import { WebSocketServer } from 'ws';
-import { PublicLinkError, } from '@byokit/link';
+import { PublicLinkError, } from '@byokit/pair';
 import { reach } from '@byokit/discover';
 import { stateWords, words } from "./words.js";
 import { decodeB64Url, sealNotice } from "./notices.js";

package/dist/testing/contract.js

@@ -390,6 +390,36 @@ export function herdrContract(make, options) {
             await kit.closeWorkspace(w2);
         });
     });
+    test('contract: waitPromptable waits through a launch-pending agent and resolves', async () => {
+        await bench(async ({ kit, fake }) => {
+            if (!fake)
+                return;
+            const paneId = 'w1:p2';
+            const agent = fake.world.agents.find((row) => row.pane_id === paneId);
+            assert.ok(agent, 'the fake seeds w1:p2');
+            agent.launch_pending = true;
+            await kit.start();
+            // A still-pending launch is not promptable: the deadline rejects agent-not-ready.
+            await assert.rejects(kit.waitPromptable({ paneId }, { timeoutMs: 120 }), (e) => e.code === 'agent-not-ready', 'a launch that stays pending rejects with agent-not-ready');
+            // Flip the fake ready: the next read clears launch_pending and the wait resolves.
+            const waiting = kit.waitPromptable({ paneId }, { timeoutMs: 2000 });
+            agent.launch_pending = false;
+            await waiting;
+            assert.equal(agentStatusOf(kit.snapshot(), paneId).status, 'idle');
+        });
+    });
+    test('contract: waitPromptable rejects pane-unavailable when the pane closes mid-wait', async () => {
+        await bench(async ({ kit, fake }) => {
+            if (!fake)
+                return;
+            const paneId = 'w1:p2';
+            fake.world.agents.find((row) => row.pane_id === paneId).launch_pending = true;
+            await kit.start();
+            const waiting = kit.waitPromptable({ paneId }, { timeoutMs: 2000 });
+            await kit.closePane(paneId);
+            await assert.rejects(waiting, (e) => e.code === 'pane-unavailable', 'a pane closed while waiting rejects pane-unavailable instead of hanging');
+        });
+    });
     test('contract: the cli answers --version and the terminal echoes', async () => {
         await bench(async ({ kit }) => {
             await kit.start();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@byokit/herdr",
-  "version": "0.7.2",
-  "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.",
+  "version": "0.7.3",
+  "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/pair.",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {
@@ -52,9 +52,9 @@
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
   },
   "dependencies": {
-    "@byokit/link": "0.8.0",
+    "@byokit/pair": "0.9.0",
     "@byokit/relay": "0.6.0",
-    "@byokit/discover": "0.6.0",
+    "@byokit/discover": "0.7.0",
     "@byokit/seal": "0.3.0",
     "ws": "8.22.0"
   },