@byokit/herdr 0.5.0 → 0.7.1

package/dist/agents.js

@@ -3,11 +3,13 @@
 // 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, openSync, readSync, closeSync } from 'node:fs';
+import { accessSync, constants as fsConstants, openSync, readSync, closeSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { delimiter, join } from 'node:path';
+import { delimiter, isAbsolute, join } from 'node:path';
 import { words } from "./words.js";
+import { accountKind } from "./kinds.js";
 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;
 // `agent.start` lands while the fresh pane is still at its shell prompt: the server answers
@@ -62,19 +64,37 @@ export function createAgents(ctx) {
             catch { /* a listener never breaks a start */ }
             emitStart(e);
         };
-        // Install pre-check: a shim or nothing on PATH means Herdr installs on first start, so the
-        // app hears `installing` before the long start instead of watching a blank pane.
         let installExpected = false;
-        try {
-            installExpected = agentInstallState(o.kind, o.installProbe).state === 'installs-on-first-start';
-        }
-        catch {
-            installExpected = false;
-        }
-        if (installExpected)
-            emit({ phase: 'installing', kind: o.kind, message: words('agent.installing', { agent: o.kind }) });
         let stage = 'placement';
         try {
+            if (o.kind === 'muse') {
+                const replacement = o.env && typeof o.env.env === 'object' && Array.isArray(o.env.unset)
+                    ? o.env : undefined;
+                const existingPane = 'pane' in o.place && o.worktree === undefined;
+                // An ordinary env overlay cannot replace an existing shell's environment.
+                if (existingPane && !replacement && Object.keys(o.env ?? {}).length > 0) {
+                    throw fail('env_mismatch', 'This pane needs to be opened again to use that sign-in.');
+                }
+                const effective = replacement?.env ?? (existingPane ? undefined
+                    : { ...ctx.launchEnv?.(), ...o.env });
+                // No controller/global extras and no probe override when the effective PATH is known.
+                // Existing unobserved panes remain unknown; the exact RPC pass-through remains available.
+                const path = effective?.PATH?.split(delimiter).filter(isAbsolute);
+                const probe = path === undefined ? (existingPane ? undefined : o.installProbe) : { path };
+                if (probe && agentInstallState('muse', probe).state === 'missing') {
+                    throw fail('agent_not_installed', words('agent.notInstalled'));
+                }
+            }
+            else {
+                try {
+                    installExpected = agentInstallState(o.kind, o.installProbe).state === 'installs-on-first-start';
+                }
+                catch {
+                    installExpected = false;
+                }
+            }
+            if (installExpected)
+                emit({ phase: 'installing', kind: o.kind, message: words('agent.installing', { agent: o.kind }) });
             const ref = await startAgentInner(o, () => { stage = 'start'; });
             emit({ phase: 'ready', kind: o.kind, ref });
             return ref;
@@ -82,6 +102,8 @@ export function createAgents(ctx) {
         catch (error) {
             const reason = classifyStartFailure(error, { installExpected, stage });
             emit({ phase: 'launchFailed', kind: o.kind, reason, message: launchFailureWords(reason, o.kind) });
+            if (codeOf(error) === 'agent_not_installed')
+                throw error;
             if (o.env && typeof o.env.env === 'object')
                 throw fail(codeOf(error) === 'env_mismatch' ? 'env_mismatch' : 'start_failed', words('agent.notReady'));
             throw error;
@@ -94,7 +116,12 @@ export function createAgents(ctx) {
             throw fail('env_mismatch', 'This pane needs to be opened again to use that sign-in.');
         }
         const timeout = o.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-        const env = o.env === undefined || launch ? {} : { env: o.env };
+        // A pane HOME alone keeps the server's XDG dirs, so a sign-in would land outside it: confine them too.
+        const home = launch ? undefined : o.env?.HOME;
+        const env = o.env === undefined || launch ? {} : { env: home === undefined ? o.env : {
+                XDG_CONFIG_HOME: join(home, '.config'), XDG_DATA_HOME: join(home, '.local', 'share'),
+                XDG_STATE_HOME: join(home, '.local', 'state'), XDG_CACHE_HOME: join(home, '.cache'), ...o.env
+            } };
         let paneId;
         let created = false;
         if (o.worktree !== undefined) {
@@ -247,7 +274,7 @@ export function createAgents(ctx) {
         return kinds.filter((kind) => resolveAgentBinary(kind, o).path !== undefined);
     }
     async function agentStatus(kinds, o) {
-        const path = o?.path ?? agentProbePath();
+        const path = o?.path ?? ctx.launchEnv?.()?.PATH?.split(delimiter) ?? agentProbePath();
         const run = o?.run ?? runStatusCommand;
         const timeoutMs = o?.timeoutMs ?? STATUS_TIMEOUT_MS;
         const probe = { path, ...(o?.aliases === undefined ? {} : { aliases: o.aliases }),
@@ -255,18 +282,27 @@ export function createAgents(ctx) {
         return Promise.all(kinds.map(async (kind) => {
             const install = agentInstallState(kind, probe);
             const binary = o?.aliases?.[kind]?.[0] ?? kind;
-            const installHint = kind === 'pi' ? PI_INSTALL_HINT : `Install the ${binary} command, then check again.`;
-            // A shim or nothing on PATH means Herdr installs on first start: not installed, with the
-            // readiness words instead of a missing-install error (pi included — a real pi binary is
-            // the only case that reads installed).
+            const installHint = kind === 'muse' ? `Install Muse explicitly from ${MUSE_INSTALL_URL} into the private launch environment.`
+                : kind === 'pi' ? PI_INSTALL_HINT : `Install the ${binary} command, then check again.`;
+            // Muse missing/launcher-only stays missing; legacy kinds retain their shim readiness.
+            // Install state never proves account or catalog readiness.
             if (install.state !== 'installed')
                 return { kind, installed: false, installState: install.state, signedIn: 'unknown', installHint };
             const statusProbe = STATUS_PROBES[kind];
-            if (statusProbe === undefined)
+            const variable = accountKind(kind)?.folderVar;
+            const folder = o?.folders?.[kind];
+            if (statusProbe === undefined || variable === undefined || !folder || !isAbsolute(folder) || /[\r\n\0]/.test(folder))
                 return { kind, installed: true, installState: 'installed', signedIn: 'unknown', installHint };
             let answer;
+            // A folder override alone is not isolation: the CLI can fall back to HOME,
+            // XDG or platform stores. Supply a clean env and confine every home to this account.
+            const env = { ...o?.env, PATH: path.join(delimiter), HOME: folder, USERPROFILE: folder,
+                XDG_CONFIG_HOME: join(folder, '.config'), XDG_STATE_HOME: join(folder, '.local', 'state'),
+                XDG_DATA_HOME: join(folder, '.local', 'share'), XDG_CACHE_HOME: join(folder, '.cache'),
+                APPDATA: join(folder, 'AppData', 'Roaming'), LOCALAPPDATA: join(folder, 'AppData', 'Local'),
+                [variable]: folder };
             try {
-                answer = await run(statusProbe.command, statusProbe.args, { ...(statusProbe.stdin === undefined ? {} : { stdin: statusProbe.stdin }), timeoutMs });
+                answer = await run(install.path, statusProbe.args, { ...(statusProbe.stdin === undefined ? {} : { stdin: statusProbe.stdin }), timeoutMs, env });
             }
             catch {
                 answer = undefined;
@@ -329,14 +365,27 @@ export function isAutoInstallShim(file, readFile = readHead) {
     }
     return head !== undefined && head.startsWith('#!') && head.includes('mise');
 }
-// Per-kind install readiness sharing the B5 probe path: `installed` for a real runnable binary,
-// `installs-on-first-start` for an auto-install launcher/shim or nothing on PATH (Herdr fetches
-// the agent on first start). `missing` stays for callers that probe kinds Herdr never installs.
+// Muse has no absent-CLI auto-installer in stock Herdr. Its official launcher needs the
+// selected native release too. Other kinds retain their legacy shim classification.
 export function agentInstallState(kind, o) {
     const path = o?.path ?? agentProbePath();
     const found = resolveAgentBinary(kind, { path, ...(o?.aliases === undefined ? {} : { aliases: o.aliases }) });
     if (found.path === undefined)
-        return { kind, state: 'installs-on-first-start' };
+        return { kind, state: kind === 'muse' ? 'missing' : 'installs-on-first-start' };
+    if (kind === 'muse') {
+        try {
+            if (!statSync(found.path).isFile())
+                return { kind, state: 'missing', path: found.path };
+        }
+        catch {
+            return { kind, state: 'missing', path: found.path };
+        }
+        const head = (o?.readFile ?? readHead)(found.path);
+        if (head?.startsWith('#!') && (head.includes('mise') || (head.includes('MUSE_CHANNEL') && !museNative(found.path)))) {
+            return { kind, state: 'missing', path: found.path };
+        }
+        return { kind, state: 'installed', path: found.path };
+    }
     const shim = isAutoInstallShim(found.path, o?.readFile);
     return shim ? { kind, state: 'installs-on-first-start', path: found.path }
         : { kind, state: 'installed', path: found.path };
@@ -346,6 +395,8 @@ export function agentInstallState(kind, o) {
 // finished, a placement that made no pane, or any other rejected start.
 export function classifyStartFailure(error, o) {
     const code = codeOf(error);
+    if (code === 'agent_not_installed')
+        return 'not-installed';
     if (code !== undefined && START_RETRYABLE.has(code))
         return 'pane-busy';
     if (o?.stage === 'placement')
@@ -355,6 +406,8 @@ export function classifyStartFailure(error, o) {
     return 'start-rejected';
 }
 function launchFailureWords(reason, kind) {
+    if (reason === 'not-installed')
+        return words('agent.notInstalled');
     if (reason === 'pane-busy')
         return words('agent.notReady');
     if (reason === 'install-failed')
@@ -396,7 +449,7 @@ const STATUS_PROBES = {
             }
             if (!isRecord(status))
                 return 'unknown';
-            return status.loggedIn === true ? 'yes' : 'no';
+            return status.loggedIn === true ? 'yes' : status.loggedIn === false ? 'no' : 'unknown';
         } },
     // 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
@@ -413,7 +466,10 @@ const STATUS_PROBES = {
                     continue;
                 }
                 if (isRecord(message) && message.id === 2) {
-                    return isRecord(message.result) && isRecord(message.result.account) ? 'yes' : 'no';
+                    if (!isRecord(message.result))
+                        return 'unknown';
+                    return isRecord(message.result.account) ? 'yes'
+                        : message.result.account === null || !Object.hasOwn(message.result, 'account') ? 'no' : 'unknown';
                 }
             }
             return 'unknown';
@@ -422,8 +478,12 @@ const STATUS_PROBES = {
 // 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) {
+    // Public direct calls without an explicit isolated HOME are not allowed to read a login.
+    if (!o?.env?.HOME || !isAbsolute(o.env.HOME) || /[\r\n\0]/.test(o.env.HOME))
+        return undefined;
     return new Promise((resolve) => {
         let done = false;
+        let timer;
         const finish = (value) => {
             if (done)
                 return;
@@ -433,14 +493,14 @@ export async function runStatusCommand(command, args, o) {
         };
         let child;
         try {
-            child = spawn(command, args, { stdio: ['pipe', 'pipe', 'ignore'], timeout: o?.timeoutMs ?? STATUS_TIMEOUT_MS });
+            child = spawn(command, args, { env: o.env, 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);
+        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;

package/dist/index.d.ts

@@ -1,5 +1,8 @@
+export { installMuse, museReadiness, MUSE_INSTALL_URL } from './muse.ts';
+export type { InstallMuseOptions, MuseReadiness, MuseInstallReceipt, MuseInstallResult } from './muse.ts';
 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 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, Move, MoveToAccount, MoveToAccountResult, MoveResult, OpenSignInTab, PromptReceipt, StartAgent, TerminalSession, AgentTurnEnd, AgentTurnOptions, AgentTurnFiles, AgentTurnResult, AgentTurnResultPolicy, } from './types.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

@@ -1,6 +1,8 @@
 // `@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 { installMuse, museReadiness, MUSE_INSTALL_URL } from "./muse.js";
 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";

package/dist/kinds.d.ts

@@ -0,0 +1,20 @@
+/** Pinned capability data, not login readiness or native move qualification. */
+export type AccountKind = {
+    kind: string;
+    aliases: string[];
+    aliasPattern?: string;
+    folderVar?: string;
+    resume: boolean;
+    sessionKinds: ('id' | 'path')[];
+    resumeArgs?: string[];
+    loginLabel: string;
+    billing: 'unknown';
+    offer: 'explicit';
+    upstream: {
+        version: string;
+        revision: string;
+        source: string;
+    };
+};
+export declare function accountKinds(): AccountKind[];
+export declare function accountKind(kind: string): AccountKind | undefined;

package/dist/kinds.js

@@ -0,0 +1,6 @@
+import table from './kinds.json' with { type: 'json' };
+export function accountKinds() { return structuredClone(table); }
+export function accountKind(kind) {
+    return accountKinds().find((row) => row.kind === kind || row.aliases.includes(kind)
+        || (row.aliasPattern !== undefined && new RegExp(row.aliasPattern).test(kind)));
+}