@byokit/herdr 0.1.10 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.2.0 (2026-09-30)
+
+- `HerdrKit.agentStatus(kinds)` (B5): per-kind onboarding readiness — installed plus CLI
+  sign-in (`yes`/`no`/`unknown`) from each CLI's own non-secret status command (`claude auth
+  status`, Codex `app-server` `account/read`; `unknown` where a CLI has none), install and
+  sign-in hint words, and the extra install dirs (mise shims, `~/.local/bin`, Homebrew) moved
+  in from muxr's PATH probe. Pi reads `installed: false` with `installs on first start`. The
+  command runner is injectable for tests; credential files are never read.
+
 ## 0.1.10 (2026-09-30)
 
 - Dependency update: pins @byokit/relay 0.4.2.

package/README.md

@@ -149,7 +149,8 @@ persistent grant store, and the phone page above.
 
 | Export | What it does |
 |---|---|
-| `HerdrKit` (`@byokit/herdr`) | The host-side kit, in `adopt` or `own` mode: `start`/`stop`, `state`, `snapshot`/`onChange`, `startAgent`, `prompt`, `sendKeys`, `wait`, `read`, `blocked`/`onBlocked`/`answer`, `closePane`/`closeTab`/`closeWorkspace`, `agentKinds`, `installedAgentKinds`, `terminal`, `onEvent`, `statusWatchReady`, and the pass-throughs `call`, `subscribe` and `cli` |
+| `HerdrKit` (`@byokit/herdr`) | The host-side kit, in `adopt` or `own` mode: `start`/`stop`, `state`, `snapshot`/`onChange`, `startAgent`, `prompt`, `sendKeys`, `wait`, `read`, `blocked`/`onBlocked`/`answer`, `closePane`/`closeTab`/`closeWorkspace`, `agentKinds`, `installedAgentKinds`, `agentStatus`, `terminal`, `onEvent`, `statusWatchReady`, and the pass-throughs `call`, `subscribe` and `cli` |
+| `agentStatus`, `agentProbePath`, `extraPathDirs`, `runStatusCommand` (`@byokit/herdr`) | 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 |
@@ -168,6 +169,50 @@ Types (`HerdrKitOptions`, `HerdrState`, `StartAgent`, `PromptReceipt`, `BlockedA
 - `own` runs the Herdr binary the app names, in an app-owned state directory.
 
 Helpers cover the common paths (start an agent, deliver a prompt with a receipt, watch blocked agents, exact closes).
+
+## Agent readiness
+
+`kit.agentStatus(kinds)` reports, per kind, whether the agent's CLI is installed and whether
+it is signed in — the onboarding agents-and-pickers check. It needs no Herdr connection: it
+probes the local machine. Install detection reuses `installedAgentKinds` over the host PATH plus
+the extra install dirs a service PATH omits (`extraPathDirs`: `~/.local/bin`, the mise shims,
+`~/.npm-global/bin`, Homebrew and the system dirs — the set muxr probed before this kit did).
+Sign-in comes only from each CLI's own documented non-secret status command, with a 10 s timeout;
+a kind whose CLI has none, or whose command gives no answer, reads `unknown`. Credential files
+are never opened, read or statted — only the signed-in boolean is kept. Herdr auto-installs Pi
+via mise on first start, so `pi` always reads `installed: false` with `installs on first start`
+rather than a missing-install error.
+
+```ts
+import { HerdrKit } from '@byokit/herdr';
+
+const kit = new HerdrKit({ mode: 'adopt', bin: 'herdr', socketPath: '/tmp/herdr.sock' });
+// Local probe only — the kit need not be started.
+console.log(await kit.agentStatus(['pi', 'claude', 'codex']));
+```
+
+```text
+[
+  { kind: 'pi', installed: false, signedIn: 'unknown', installHint: 'installs on first start' },
+  { kind: 'claude', installed: true, signedIn: 'yes',
+    installHint: 'Install the claude command, then check again.' },
+  { kind: 'codex', installed: true, signedIn: 'no',
+    installHint: 'Install the codex command, then check again.',
+    signInHint: 'On this computer run `codex`, sign in, then come back.' },
+]
+```
+
+| Kind | Status command | Why this one |
+|---|---|---|
+| `claude` | `claude auth status` (JSON `loggedIn`) | The CLI's own documented status; a signed-out CLI still prints its JSON, so only an empty answer reads `unknown`. |
+| `codex` | `codex app-server` with a pipelined `initialize` + `account/read` round | Codex exposes sign-in only over its app-server protocol; a record `account` in the second answer means signed in. |
+| `pi` | none (Herdr installs it via mise) | No probe: always `installed: false`, `installs on first start`. |
+| any other kind | none | No documented non-secret status command, so `unknown` until the kit covers it. |
+
+Options: `{ path, aliases }` as in `installedAgentKinds`; `{ run }` injects the command runner
+(`(command, args, { stdin, timeoutMs }) => Promise<{ stdout } | undefined>`, so tests use fakes);
+`{ timeoutMs }` bounds each probe. `signInHint` rides kinds the kit knows how to check whenever they
+are not signed in; `installHint` always rides along.
 `call` and `subscribe` are typed pass-throughs to the complete socket API, and `cli()` reaches the full CLI.
 
 `start()` is non-fatal: if Herdr is down it rejects (state `failed`, e.g. `failed/socket`) and may be called again

package/dist/agents.d.ts

@@ -5,4 +5,12 @@ export declare function createAgents(ctx: {
     call: Call;
     snapshot(): HerdrSnapshot;
     reread(paneId: string): Promise<void>;
-}): Pick<HerdrKit, 'startAgent' | 'prompt' | 'sendKeys' | 'wait' | 'read' | 'agentKinds' | 'installedAgentKinds'>;
+}): Pick<HerdrKit, 'startAgent' | 'prompt' | 'sendKeys' | 'wait' | 'read' | 'agentKinds' | 'installedAgentKinds' | 'agentStatus'>;
+export declare function extraPathDirs(home?: string): string[];
+export declare function agentProbePath(path?: string[], home?: string): string[];
+export declare function runStatusCommand(command: string, args: string[], o?: {
+    stdin?: string;
+    timeoutMs?: number;
+}): Promise<{
+    stdout: string;
+} | undefined>;

package/dist/agents.js

@@ -2,8 +2,10 @@
 // Exact param spellings come from the generated v0.9.1 table (6.7); where muxr and the schema
 // disagree the schema wins. `pane.split` takes `target_pane_id` (muxr agrees), and `agent.start`
 // has no `env` param — a start's env belongs to the placement create/split call (src/generated/methods.ts).
+import { spawn } from 'node:child_process';
 import { accessSync, constants as fsConstants } from 'node:fs';
-import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
 const PROMPTABLE = ['idle', 'working', 'blocked', 'done'];
 const DEFAULT_TIMEOUT_MS = 60_000;
 // `agent.start` lands while the fresh pane is still at its shell prompt: the server answers
@@ -190,5 +192,144 @@ export function createAgents(ctx) {
         }
         return installed;
     }
-    return { startAgent, prompt, sendKeys, wait, read, agentKinds, installedAgentKinds };
+    // B5: the extra install dirs muxr's `executableOnPath` probes past PATH (a GUI daemon's
+    // inherited PATH omits them), moved into the kit so the host probe is trusted.
+    function installedSet(kinds, o) {
+        return new Set(installedAgentKinds(kinds.filter((k) => k !== 'pi'), o));
+    }
+    async function agentStatus(kinds, o) {
+        const path = o?.path ?? agentProbePath();
+        const run = o?.run ?? runStatusCommand;
+        const timeoutMs = o?.timeoutMs ?? STATUS_TIMEOUT_MS;
+        const installed = installedSet(kinds, { path, ...(o?.aliases === undefined ? {} : { aliases: o.aliases }) });
+        return Promise.all(kinds.map(async (kind) => {
+            // Herdr auto-installs Pi via mise on first start, so PATH presence is not the signal:
+            // Pi always reads not-installed with the readiness words instead of a missing-install error.
+            if (kind === 'pi')
+                return { kind, installed: false, signedIn: 'unknown', installHint: PI_INSTALL_HINT };
+            const binary = o?.aliases?.[kind]?.[0] ?? kind;
+            const installHint = `Install the ${binary} command, then check again.`;
+            if (!installed.has(kind))
+                return { kind, installed: false, signedIn: 'unknown', installHint };
+            const probe = STATUS_PROBES[kind];
+            if (probe === undefined)
+                return { kind, installed: true, signedIn: 'unknown', installHint };
+            let answer;
+            try {
+                answer = await run(probe.command, probe.args, { ...(probe.stdin === undefined ? {} : { stdin: probe.stdin }), timeoutMs });
+            }
+            catch {
+                answer = undefined;
+            }
+            const signedIn = answer === undefined ? 'unknown' : probe.parse(answer.stdout);
+            return { kind, installed: true, signedIn, installHint,
+                ...(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 };
+}
+// Extra install dirs muxr's `executableOnPath`
+// (`apps/host/src/agent/infrastructure/herdrSessionSource.ts`) probes past PATH: user-install
+// dirs a service or GUI daemon's inherited PATH omits — mise shims (Herdr installs Pi through
+// mise), `~/.local/bin`, npm-global, Homebrew and the system dirs.
+export function extraPathDirs(home = homedir()) {
+    return [join(home, '.local', 'bin'), join(home, '.local', 'share', 'mise', 'shims'),
+        join(home, '.npm-global', 'bin'), '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin'];
+}
+// The full install probe: the host's own PATH plus the extra dirs, de-duplicated.
+export function agentProbePath(path = (process.env.PATH ?? '').split(delimiter), home = homedir()) {
+    return [...new Set([...path, ...extraPathDirs(home)])].filter((dir) => dir !== '');
+}
+const STATUS_TIMEOUT_MS = 10_000;
+const PI_INSTALL_HINT = 'installs on first start';
+const SIGNIN_HINTS = {
+    claude: 'On this computer run `claude`, sign in, then come back.',
+    codex: 'On this computer run `codex`, sign in, then come back.',
+};
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+// Per-kind CLI status commands (see the README table for why each one). Every probe asks the
+// CLI itself and keeps only the signed-in boolean — email, plan and everything secret stays out.
+// A kind with no documented non-secret status command has no entry and reads 'unknown'.
+const STATUS_PROBES = {
+    // `claude auth status` prints JSON with `loggedIn` (muxr's planIdentity reads the same);
+    // a signed-out CLI still prints its JSON, so only an empty answer means 'unknown'.
+    claude: { command: 'claude', args: ['auth', 'status'], parse: (stdout) => {
+            let status;
+            try {
+                status = JSON.parse(stdout);
+            }
+            catch {
+                return 'unknown';
+            }
+            if (!isRecord(status))
+                return 'unknown';
+            return status.loggedIn === true ? 'yes' : 'no';
+        } },
+    // Codex exposes sign-in only over its app-server protocol, so the probe pipes a pipelined
+    // `initialize` + `account/read` round (same method muxr's planIdentity uses) and reads the
+    // second answer: a record `account` means signed in, its absence means signed out.
+    codex: { command: 'codex', args: ['app-server'],
+        stdin: '{"id":1,"method":"initialize","params":{"clientInfo":{"name":"byokit","version":"1"}}}\n{"id":2,"method":"account/read","params":{}}\n',
+        parse: (stdout) => {
+            for (const line of stdout.split('\n')) {
+                let message;
+                try {
+                    message = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (isRecord(message) && message.id === 2) {
+                    return isRecord(message.result) && isRecord(message.result.account) ? 'yes' : 'no';
+                }
+            }
+            return 'unknown';
+        } },
+};
+// Default runner: one bounded spawn per probe, stdin piped when the protocol needs it (codex).
+// Failures (missing binary, timeout, non-empty stderr, empty stdout) read as no answer — never throw.
+export async function runStatusCommand(command, args, o) {
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = (value) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            resolve(value);
+        };
+        let child;
+        try {
+            child = spawn(command, args, { stdio: ['pipe', 'pipe', 'ignore'], timeout: o?.timeoutMs ?? STATUS_TIMEOUT_MS });
+        }
+        catch {
+            finish(undefined);
+            return;
+        }
+        let out = '';
+        const timer = setTimeout(() => { child.kill('SIGKILL'); finish(undefined); }, (o?.timeoutMs ?? STATUS_TIMEOUT_MS) + 500);
+        child.on('error', () => finish(undefined));
+        const stdout = child.stdout;
+        const stdin = child.stdin;
+        if (stdout === null || stdin === null) {
+            finish(undefined);
+            return;
+        }
+        stdout.setEncoding('utf8');
+        stdout.on('data', (chunk) => {
+            out += chunk;
+            if (out.length > 64 * 1024) {
+                child.kill('SIGKILL');
+                finish(undefined);
+            }
+        });
+        child.on('close', () => finish(out.trim() === '' ? undefined : { stdout: out.slice(0, 64 * 1024) }));
+        stdin.on('error', () => { });
+        try {
+            if (o?.stdin !== undefined)
+                stdin.write(o.stdin);
+            stdin.end();
+        }
+        catch { /* a dead stdin settles through close/error */ }
+    });
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { HERDR_VERSION, HERDR_PROTOCOL } from './constants.ts';
 export { HerdrKit } from './kit.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, HerdrSubscribeStop, HerdrTransport, PromptReceipt, StartAgent, TerminalSession, } from './types.ts';
+export { agentProbePath, extraPathDirs, runStatusCommand } from './agents.ts';
+export type { AgentCliSignIn, AgentReadiness, AgentStatusOptions, AgentStatusRunner, AgentRef, AgentStatus, BlockedAgent, HerdrEvent, HerdrEventName, HerdrEventOf, HerdrKitOptions, HerdrMethod, HerdrMethods, HerdrParams, HerdrProtocolRange, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, HerdrSubscribeStop, HerdrTransport, PromptReceipt, StartAgent, TerminalSession, } from './types.ts';

package/dist/index.js

@@ -3,3 +3,4 @@
 export { HERDR_VERSION, HERDR_PROTOCOL } from "./constants.js";
 export { HerdrKit } from "./kit.js";
 export { agentWords, stateWords, words, WORDS } from "./words.js";
+export { agentProbePath, extraPathDirs, runStatusCommand } from "./agents.js";

package/dist/kit.d.ts

@@ -1,4 +1,4 @@
-import type { AgentRef, AgentStatus, BlockedAgent, HerdrEvent, HerdrEventName, HerdrEventOf, HerdrKitOptions, HerdrMethod, HerdrParams, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, HerdrSubscribeStop, PromptReceipt, StartAgent, TerminalSession } from './types.ts';
+import type { AgentReadiness, AgentStatusOptions, AgentRef, AgentStatus, BlockedAgent, HerdrEvent, HerdrEventName, HerdrEventOf, HerdrKitOptions, HerdrMethod, HerdrParams, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, HerdrSubscribeStop, PromptReceipt, StartAgent, TerminalSession } from './types.ts';
 export declare class HerdrKit {
     private readonly supervisor;
     private transport?;
@@ -98,4 +98,5 @@ export declare class HerdrKit {
         path: string[];
         aliases?: Record<string, string[]>;
     }): string[];
+    agentStatus(kinds: readonly string[], o?: AgentStatusOptions): Promise<AgentReadiness[]>;
 }

package/dist/kit.js

@@ -450,4 +450,7 @@ export class HerdrKit {
     closeWorkspace(workspaceId) { return closeWorkspace(this.callAny, workspaceId); }
     agentKinds() { return this.agents.agentKinds(); }
     installedAgentKinds(kinds, o) { return this.agents.installedAgentKinds(kinds, o); }
+    // Onboarding readiness (B5): a local PATH probe plus each installed CLI's own status
+    // command — no Herdr connection needed, credential files never read.
+    agentStatus(kinds, o) { return this.agents.agentStatus(kinds, o); }
 }

package/dist/types.d.ts

@@ -47,6 +47,26 @@ export type HerdrEvent = {
 export type { HerdrMethods, HerdrMethod, HerdrParams, HerdrResult } from './generated/methods.ts';
 export type { HerdrEvents, HerdrEventName, HerdrEventOf, HerdrSubscription } from './generated/events.ts';
 export type AgentStatus = 'idle' | 'working' | 'blocked' | 'done' | 'unknown';
+export type AgentCliSignIn = 'yes' | 'no' | 'unknown';
+export type AgentReadiness = {
+    kind: string;
+    installed: boolean;
+    signedIn: AgentCliSignIn;
+    installHint: string;
+    signInHint?: string;
+};
+export type AgentStatusRunner = (command: string, args: string[], o?: {
+    stdin?: string;
+    timeoutMs?: number;
+}) => Promise<{
+    stdout: string;
+} | undefined>;
+export type AgentStatusOptions = {
+    path?: string[];
+    aliases?: Record<string, string[]>;
+    run?: AgentStatusRunner;
+    timeoutMs?: number;
+};
 export type AgentRef = {
     paneId: string;
     name?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/herdr",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "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",