@prohost/cli 0.13.3 → 0.15.0

package/dist/agent/runtime_status.js

@@ -38,6 +38,34 @@ export const STATUS_INTERVAL_MS = 5 * 60_000;
  * the frame that carried a change.
  */
 export const MIN_FRAME_SPACING_MS = 31_000;
+/**
+ * Inside that window the server still accepts a frame whose capabilities
+ * changed, one per 5 s (`MIN_CAPABILITY_CHANGE_INTERVAL_SECONDS`), and a strict
+ * narrowing (a capability dropped, nothing added) one per second
+ * (`MIN_CAPABILITY_NARROWING_INTERVAL_SECONDS`). A capability can be a switch
+ * the server enforces (`remote_terminal`). Margin on both.
+ */
+export const MIN_CAPABILITY_CHANGE_SPACING_MS = 6_000;
+export const MIN_CAPABILITY_NARROWING_SPACING_MS = 1_500;
+/**
+ * The server drops a status frame over 8 KB (`MAX_FRAME_BYTES`). The opened
+ * folders are the one part of it that can grow that far, so they are cut,
+ * oldest first, until the frame fits under this, with margin.
+ */
+export const MAX_STATUS_FRAME_BYTES = 8_000;
+/**
+ * The budget once the server lists {@link CODE_HOST_FOLDERS_FEATURE} in `auth_ok.features`: it
+ * takes frames up to 64 KiB, so all 50 folders fit. Margin under the cap.
+ */
+export const MAX_LARGE_STATUS_FRAME_BYTES = 63 * 1024;
+/**
+ * A server listing this feature takes a status frame up to 64 KiB, and one whose
+ * `code_host_repos` / `code_host_folders` / `code_host_home` changed inside its spacing window
+ * (a 5 s floor) — the opened folders reach phones within seconds of `folders add`.
+ */
+export const CODE_HOST_FOLDERS_FEATURE = 'code_host_folders';
+/** The early code-host frame's spacing: the server's 5 s floor, with margin. */
+export const MIN_CODE_HOST_CHANGE_SPACING_MS = 6_000;
 /** Ask the agent CLI for fresh numbers when the last ones are this old. */
 export const QUOTA_REFRESH_AFTER_MS = 15 * 60_000;
 /** Ceiling on one idle quota probe. */
@@ -117,8 +145,10 @@ export function fromClaudeRateLimitInfo(info) {
  * Windows from a `get_usage` control response (0–100, ISO strings).
  *
  * A window with a usage but a `null` reset is kept, with `resets_at: null` —
- * that is how an idle account's 5-hour window reads, and dropping it is what
- * left paired agents showing a weekly window and nothing else (B3).
+ * that is how an idle account's 5-hour window reads. Reporting stays complete:
+ * dropping it here, with the list replaced whole by each source, erased a known
+ * 5-hour window (B3). Whether to show an idle one is the server's call (it
+ * doesn't: `shared.ai_usage.windows.visible_windows`).
  *
  * Per-model weekly windows come from `rate_limits.limits[]` rows of kind
  * `weekly_scoped` (classified on `kind`, as the schema asks, never on a
@@ -160,6 +190,8 @@ export function fromClaudeGetUsage(usage) {
 const CLAUDE_PLANS = {
     pro: 'Claude Pro',
     max: 'Claude Max',
+    // Inferred from the others; not seen in a real `get_usage` response yet.
+    ultra: 'Claude Ultra',
     team: 'Claude Team',
     enterprise: 'Claude Enterprise',
 };
@@ -472,6 +504,10 @@ function asOf(window, nowMs) {
         return window;
     return { ...window, used_percent: 0, resets_at: null };
 }
+/** This machine's hostname up to its first dot (`studio-001.local` is `studio-001`), or `undefined`. */
+export function shortHostname(raw = os.hostname()) {
+    return raw.trim().split('.')[0] || undefined;
+}
 /** Left out when there is nothing to declare, so an older server sees the frame it knows. */
 function capabilitiesField(capabilities) {
     return capabilities && capabilities.length > 0 ? { capabilities } : {};
@@ -498,6 +534,16 @@ export class RuntimeStatusReporter {
     quotaObservedAt;
     send;
     lastSentAt;
+    /** The capabilities the last frame carried, and when a changed set last went out at once. */
+    lastSentCapabilities;
+    lastCapabilityChangeAt;
+    lastCapabilityNarrowingAt;
+    /** The code-host fields the last frame carried, and when a changed set last went out early. */
+    lastSentCodeHost;
+    lastCodeHostChangeAt;
+    cancelCodeHostPending;
+    /** The server lists {@link CODE_HOST_FOLDERS_FEATURE}: 64 KiB frames, early code-host frames. */
+    codeHostServer = false;
     cancelPending;
     cancelTick;
     refreshing;
@@ -555,6 +601,32 @@ export class RuntimeStatusReporter {
         if (!options.quiet && JSON.stringify(before) !== JSON.stringify(snapshot))
             this.sendSoon();
     }
+    /**
+     * What the harness declares changed (the remote-terminal switch): sent at
+     * once, since the server lets a changed capability set through its spacing
+     * window and stops sending what this machine now refuses; and again in the
+     * next spaced slot, for a server that predates that.
+     */
+    capabilitiesChanged() {
+        if (!this.send)
+            return;
+        const now = this.now();
+        const current = this.capabilitiesList();
+        const previous = this.lastSentCapabilities ? JSON.parse(this.lastSentCapabilities) : [];
+        const changed = JSON.stringify(current) !== this.lastSentCapabilities;
+        // A strict narrowing (remote off: one dropped, none added) has its own short floor, as on the server.
+        const narrowed = current.length < previous.length && current.every((cap) => previous.includes(cap));
+        const since = narrowed ? this.lastCapabilityNarrowingAt : this.lastCapabilityChangeAt;
+        const spacing = narrowed ? MIN_CAPABILITY_NARROWING_SPACING_MS : MIN_CAPABILITY_CHANGE_SPACING_MS;
+        if (this.lastSentAt !== undefined && changed && (since === undefined || now - since >= spacing)) {
+            if (narrowed)
+                this.lastCapabilityNarrowingAt = now;
+            else
+                this.lastCapabilityChangeAt = now;
+            this.flush();
+        }
+        this.sendSoon();
+    }
     /**
      * The account choice changed (an operator picked one in ProhostAI): re-read
      * accounts and capacity on the next tick rather than in fifteen minutes.
@@ -573,12 +645,45 @@ export class RuntimeStatusReporter {
         return this.state.model;
     }
     /** Start reporting on a socket that advertised the feature. */
-    attach(send) {
+    attach(send, server = {}) {
         this.detach();
         this.send = send;
         this.lastSentAt = undefined;
+        this.lastSentCodeHost = undefined;
+        this.lastCodeHostChangeAt = undefined;
+        this.codeHostServer = server.codeHostFolders === true;
         void this.tick();
     }
+    /**
+     * What this Mac offers Code threads changed (its opened folders, say, after `folders add`). A
+     * server listing {@link CODE_HOST_FOLDERS_FEATURE} takes such a frame early, at most every
+     * {@link MIN_CODE_HOST_CHANGE_SPACING_MS}; an older one gets it in the next spaced slot.
+     */
+    codeHostChanged() {
+        if (!this.send)
+            return;
+        if (!this.codeHostServer || this.lastSentAt === undefined) {
+            this.sendSoon();
+            return;
+        }
+        if (this.codeHostKey(this.frame()) === this.lastSentCodeHost)
+            return;
+        const wait = this.lastCodeHostChangeAt === undefined ? 0 : this.lastCodeHostChangeAt + MIN_CODE_HOST_CHANGE_SPACING_MS - this.now();
+        if (wait <= 0) {
+            this.lastCodeHostChangeAt = this.now();
+            this.flush();
+            return;
+        }
+        if (this.cancelCodeHostPending)
+            return;
+        this.cancelCodeHostPending = this.schedule(() => {
+            this.cancelCodeHostPending = undefined;
+            this.codeHostChanged();
+        }, wait);
+    }
+    codeHostKey(frame) {
+        return JSON.stringify([frame.code_host_repos, frame.code_host_folders, frame.code_host_home]);
+    }
     /** Stop reporting — the socket is gone. */
     detach() {
         this.send = undefined;
@@ -586,12 +691,14 @@ export class RuntimeStatusReporter {
         this.cancelPending = undefined;
         this.cancelTick?.();
         this.cancelTick = undefined;
+        this.cancelCodeHostPending?.();
+        this.cancelCodeHostPending = undefined;
     }
     /** The frame as it would be sent now. */
     frame() {
         const nowMs = this.now();
         const windows = (this.state.quota_windows ?? []).map((w) => asOf(w, nowMs));
-        return {
+        const frame = {
             type: 'runtime_status',
             runtime: this.options.runtime,
             runtime_version: this.state.runtime_version ?? null,
@@ -605,7 +712,59 @@ export class RuntimeStatusReporter {
             // Never a list the registry has moved on from — the server would delete
             // what it leaves out. Left out, nothing is deleted; the next tick re-reads it.
             ...(this.accounts?.all && !this.accountsMoved() ? { machine_accounts: this.accounts.all } : {}),
+            ...this.hostField(),
+            ...this.hostnameField(),
+            ...this.codeHostReposField(),
         };
+        return this.withCodeHostFolders(frame);
+    }
+    /**
+     * `frame` with the opened folders, as many as fit (newest kept): under {@link MAX_STATUS_FRAME_BYTES},
+     * or {@link MAX_LARGE_STATUS_FRAME_BYTES} for a server that takes large frames.
+     */
+    withCodeHostFolders(frame) {
+        let report;
+        try {
+            report = this.options.codeHostFolders?.();
+        }
+        catch {
+            return frame;
+        }
+        if (!report)
+            return frame;
+        const folders = report.folders.slice(0, 50);
+        const withFolders = () => ({ ...frame, code_host_folders: folders, code_host_home: report.home });
+        const budget = this.codeHostServer ? MAX_LARGE_STATUS_FRAME_BYTES : MAX_STATUS_FRAME_BYTES;
+        while (folders.length > 0 && Buffer.byteLength(JSON.stringify(withFolders()), 'utf8') > budget)
+            folders.pop();
+        return withFolders();
+    }
+    codeHostReposField() {
+        try {
+            const repos = this.options.codeHostRepos?.();
+            return repos ? { code_host_repos: repos } : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    hostnameField() {
+        try {
+            const hostname = (this.options.hostname ?? shortHostname)();
+            return hostname ? { hostname } : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    hostField() {
+        try {
+            const host = this.options.host?.();
+            return host ? { host } : {};
+        }
+        catch {
+            return {};
+        }
     }
     /**
      * Whether the machine's registry no longer holds exactly the accounts the
@@ -702,12 +861,21 @@ export class RuntimeStatusReporter {
             this.flush();
         }, wait);
     }
+    capabilitiesList() {
+        return [...(this.options.capabilities?.() ?? [])].sort();
+    }
+    capabilitiesKey() {
+        return JSON.stringify(this.capabilitiesList());
+    }
     flush() {
         if (!this.send)
             return;
         try {
-            this.send(this.frame());
+            const frame = this.frame();
+            this.send(frame);
             this.lastSentAt = this.now();
+            this.lastSentCapabilities = this.capabilitiesKey();
+            this.lastSentCodeHost = this.codeHostKey(frame);
         }
         catch (err) {
             this.options.log?.(`runtime status not sent: ${err instanceof Error ? err.message : String(err)}`);

package/dist/agent/worktrees.d.ts

@@ -38,6 +38,8 @@ export interface RunCheckout {
     path: string;
     /** The operator's checkout it was made from — the one the agent must leave alone. */
     source: string;
+    /** Made by this call (`git worktree add`), not an existing one kept from an earlier run. */
+    created?: boolean;
 }
 export interface CheckoutFailure {
     source: string;

package/dist/agent/worktrees.js

@@ -180,8 +180,9 @@ export class WorktreeManager {
                 const name = path.basename(source);
                 const target = path.join(dir, name);
                 let failure;
+                const existed = isCheckout(target);
                 try {
-                    failure = isCheckout(target) ? await this.reuse(source, target) : await this.add(source, target);
+                    failure = existed ? await this.reuse(source, target) : await this.add(source, target);
                 }
                 catch (err) {
                     failure = err instanceof Error ? err.message : String(err);
@@ -189,7 +190,7 @@ export class WorktreeManager {
                 if (failure)
                     prepared.failures.push({ source, reason: failure });
                 else
-                    prepared.checkouts.push({ name, path: target, source });
+                    prepared.checkouts.push({ name, path: target, source, created: !existed });
             }
             // Housekeeping for other conversations must not cost this one its run.
             await this.pruneIfDue(dir).catch((err) => {

package/dist/codehost/activity.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Whether an agent this Mac hosts is mid-turn, for the desktop app's "Keep this
+ * Mac awake while an agent is working".
+ *
+ * Two layers, both under `$PROHOST_HOME/code-host/`:
+ *
+ * - `turns/<terminalId>` — one marker per terminal whose agent is working: made
+ *   when a turn starts (Claude Code's `UserPromptSubmit` hook; a goal the host
+ *   starts an agent with; a reply it types), removed when the turn ends (Claude
+ *   Code's `Stop` hook, Codex's `agent-turn-complete`) or is interrupted from an
+ *   attached viewer (Esc / Ctrl+C). The hooks run in their own processes, so
+ *   the marker is a file, not daemon state.
+ * - `activity.json` — what the desktop app reads (0600, written atomically):
+ *
+ *       { "v": 1, "busy": true, "updatedAt": "<ISO>" }
+ *
+ *   The daemon writes it on its settings poll: when `busy` changes, and at
+ *   least every {@link ACTIVITY_REFRESH_MS} either way. It is removed when the
+ *   host stops or hosting is turned off. **A reader treats an `updatedAt`
+ *   older than {@link ACTIVITY_STALE_MS} as not busy**: a daemon that died
+ *   never keeps the Mac awake.
+ *
+ * A marker counts only for a terminal the host still has, and only for
+ * {@link MAX_TURN_MS}: an agent that exited mid-turn without its end hook (a
+ * crash, two Ctrl+C typed straight into tmux) never holds the Mac awake for
+ * good.
+ */
+export declare const ACTIVITY_VERSION = 1;
+/** The daemon rewrites `activity.json` at least this often, busy or not. */
+export declare const ACTIVITY_REFRESH_MS = 30000;
+/** A reader treats an `updatedAt` older than this as not busy (documented for the desktop app). */
+export declare const ACTIVITY_STALE_MS: number;
+/** A turn marker older than this no longer counts as working. */
+export declare const MAX_TURN_MS: number;
+export interface Activity {
+    v: 1;
+    busy: boolean;
+    updatedAt: string;
+}
+export declare function activityPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * Mark `terminalId`'s agent as mid-turn (`working`) or not. Never throws: a
+ * marker that can't be written only costs keep-awake, never a hook or a reply.
+ */
+export declare function markTurn(terminalId: string | undefined, working: boolean, env?: NodeJS.ProcessEnv): void;
+/**
+ * Whether any of `live` (the terminals the host has) is mid-turn now. A marker
+ * of a terminal not in `live` doesn't count (its window may be gone, or the
+ * host's list only momentarily empty) and is kept; only markers past
+ * {@link MAX_TURN_MS} are removed. Never throws.
+ */
+export declare function anyTurnWorking(live: Iterable<string>, env?: NodeJS.ProcessEnv, now?: number): boolean;
+/** The daemon's side: writes `activity.json` on its poll, and removes it when hosting stops. */
+export declare class ActivityReporter {
+    private readonly env;
+    private readonly now;
+    private lastBusy;
+    private lastWriteAt;
+    constructor(env: NodeJS.ProcessEnv, now?: () => number);
+    /** Re-read the markers for `live` and write the file when it changed or is due. Never throws. */
+    tick(live: Iterable<string>): void;
+    /** Hosting stopped: nothing says this Mac is busy any more. */
+    clear(): void;
+}

package/dist/codehost/activity.js

@@ -0,0 +1,135 @@
+/**
+ * Whether an agent this Mac hosts is mid-turn, for the desktop app's "Keep this
+ * Mac awake while an agent is working".
+ *
+ * Two layers, both under `$PROHOST_HOME/code-host/`:
+ *
+ * - `turns/<terminalId>` — one marker per terminal whose agent is working: made
+ *   when a turn starts (Claude Code's `UserPromptSubmit` hook; a goal the host
+ *   starts an agent with; a reply it types), removed when the turn ends (Claude
+ *   Code's `Stop` hook, Codex's `agent-turn-complete`) or is interrupted from an
+ *   attached viewer (Esc / Ctrl+C). The hooks run in their own processes, so
+ *   the marker is a file, not daemon state.
+ * - `activity.json` — what the desktop app reads (0600, written atomically):
+ *
+ *       { "v": 1, "busy": true, "updatedAt": "<ISO>" }
+ *
+ *   The daemon writes it on its settings poll: when `busy` changes, and at
+ *   least every {@link ACTIVITY_REFRESH_MS} either way. It is removed when the
+ *   host stops or hosting is turned off. **A reader treats an `updatedAt`
+ *   older than {@link ACTIVITY_STALE_MS} as not busy**: a daemon that died
+ *   never keeps the Mac awake.
+ *
+ * A marker counts only for a terminal the host still has, and only for
+ * {@link MAX_TURN_MS}: an agent that exited mid-turn without its end hook (a
+ * crash, two Ctrl+C typed straight into tmux) never holds the Mac awake for
+ * good.
+ */
+import { readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { codeHostDir, ensurePrivateDir, writePrivateJson } from './settings.js';
+import { isValidId } from './tmux.js';
+export const ACTIVITY_VERSION = 1;
+/** The daemon rewrites `activity.json` at least this often, busy or not. */
+export const ACTIVITY_REFRESH_MS = 30_000;
+/** A reader treats an `updatedAt` older than this as not busy (documented for the desktop app). */
+export const ACTIVITY_STALE_MS = 3 * 60_000;
+/** A turn marker older than this no longer counts as working. */
+export const MAX_TURN_MS = 6 * 3_600_000;
+export function activityPath(env = process.env) {
+    return path.join(codeHostDir(env), 'activity.json');
+}
+function turnsDir(env) {
+    return path.join(codeHostDir(env), 'turns');
+}
+/**
+ * Mark `terminalId`'s agent as mid-turn (`working`) or not. Never throws: a
+ * marker that can't be written only costs keep-awake, never a hook or a reply.
+ */
+export function markTurn(terminalId, working, env = process.env) {
+    // Only a valid id names a path: nothing from a hook's environment walks out of the dir.
+    if (!isValidId(terminalId))
+        return;
+    const file = path.join(turnsDir(env), terminalId);
+    try {
+        if (working) {
+            ensurePrivateDir(turnsDir(env));
+            writeFileSync(file, '', { mode: 0o600 });
+        }
+        else {
+            rmSync(file, { force: true });
+        }
+    }
+    catch {
+        /* keep-awake only */
+    }
+}
+/**
+ * Whether any of `live` (the terminals the host has) is mid-turn now. A marker
+ * of a terminal not in `live` doesn't count (its window may be gone, or the
+ * host's list only momentarily empty) and is kept; only markers past
+ * {@link MAX_TURN_MS} are removed. Never throws.
+ */
+export function anyTurnWorking(live, env = process.env, now = Date.now()) {
+    const known = new Set(live);
+    let names;
+    try {
+        names = readdirSync(turnsDir(env));
+    }
+    catch {
+        return false;
+    }
+    let working = false;
+    for (const name of names) {
+        const file = path.join(turnsDir(env), name);
+        try {
+            const fresh = now - statSync(file).mtimeMs < MAX_TURN_MS;
+            if (!fresh)
+                rmSync(file, { force: true });
+            else if (known.has(name))
+                working = true;
+        }
+        catch {
+            /* removed meanwhile (its turn ended), or not ours to remove: never fails the poll */
+        }
+    }
+    return working;
+}
+/** The daemon's side: writes `activity.json` on its poll, and removes it when hosting stops. */
+export class ActivityReporter {
+    env;
+    now;
+    lastBusy;
+    lastWriteAt = 0;
+    constructor(env, now = Date.now) {
+        this.env = env;
+        this.now = now;
+    }
+    /** Re-read the markers for `live` and write the file when it changed or is due. Never throws. */
+    tick(live) {
+        const now = this.now();
+        const busy = anyTurnWorking(live, this.env, now);
+        if (busy === this.lastBusy && now - this.lastWriteAt < ACTIVITY_REFRESH_MS)
+            return;
+        try {
+            const activity = { v: ACTIVITY_VERSION, busy, updatedAt: new Date(now).toISOString() };
+            writePrivateJson(activityPath(this.env), activity);
+            this.lastBusy = busy;
+            this.lastWriteAt = now;
+        }
+        catch {
+            /* tried again on the next poll */
+        }
+    }
+    /** Hosting stopped: nothing says this Mac is busy any more. */
+    clear() {
+        this.lastBusy = undefined;
+        this.lastWriteAt = 0;
+        try {
+            rmSync(activityPath(this.env), { force: true });
+        }
+        catch {
+            /* a stale file reads as not busy once it ages (ACTIVITY_STALE_MS) */
+        }
+    }
+}

package/dist/codehost/agents.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Which coding agents this Mac can run in a Code thread: the ones whose binary resolves on the
+ * daemon's `PATH` (what its tmux server, and so every thread window, inherits).
+ *
+ * Declared on every status frame as `code_thread_agent_<agent>` beside `code_threads_v2`, so the
+ * server offers a phone or the web only the agents that will start here, whatever runtime the
+ * pairing itself reports (a `--host-only` daemon reports `custom`). Re-checked per frame: a few
+ * `stat`s over `PATH`, so installing Codex shows up within one status interval.
+ */
+export type InstalledAgent = 'claude_code' | 'codex';
+/** The command a thread window runs for each agent (see `agentCommandLine`). */
+export declare const AGENT_BINARIES: Readonly<Record<InstalledAgent, string>>;
+/**
+ * `code_thread_agent_<agent>`. Underscores, not a colon: the server takes a capability only as
+ * `^[a-z0-9_]+$` (`shared/agents/runtime_status.py`), and one it can't read rejects the whole frame.
+ */
+export declare const CODE_THREAD_AGENT_CAPABILITY_PREFIX = "code_thread_agent_";
+/**
+ * Declared beside the per-agent capabilities whatever they are: "this CLI says which agents it
+ * runs", so none declared with it means none installed, not an older CLI that says nothing.
+ */
+export declare const CODE_THREAD_AGENTS_CAPABILITY = "code_thread_agents";
+export type IsExecutable = (file: string) => boolean;
+/** Whether `binary` resolves to an executable file in one of `env.PATH`'s directories. */
+export declare function resolvesOnPath(binary: string, env?: NodeJS.ProcessEnv, isExecutable?: IsExecutable): boolean;
+/** The agents whose binary resolves on `env.PATH`, in the order clients list them. */
+export declare function installedAgents(env?: NodeJS.ProcessEnv, isExecutable?: IsExecutable): InstalledAgent[];
+/** {@link CODE_THREAD_AGENTS_CAPABILITY}, then `code_thread_agent_<agent>` for each of `agents`. */
+export declare function agentCapabilities(agents: readonly InstalledAgent[]): string[];
+/** Why a start for `agent` is refused on a Mac without its binary: the thread shows it as the failure. */
+export declare function missingAgentReason(agent: InstalledAgent): string;

package/dist/codehost/agents.js

@@ -0,0 +1,57 @@
+/**
+ * Which coding agents this Mac can run in a Code thread: the ones whose binary resolves on the
+ * daemon's `PATH` (what its tmux server, and so every thread window, inherits).
+ *
+ * Declared on every status frame as `code_thread_agent_<agent>` beside `code_threads_v2`, so the
+ * server offers a phone or the web only the agents that will start here, whatever runtime the
+ * pairing itself reports (a `--host-only` daemon reports `custom`). Re-checked per frame: a few
+ * `stat`s over `PATH`, so installing Codex shows up within one status interval.
+ */
+import { accessSync, constants, statSync } from 'node:fs';
+import path from 'node:path';
+/** The command a thread window runs for each agent (see `agentCommandLine`). */
+export const AGENT_BINARIES = { claude_code: 'claude', codex: 'codex' };
+/**
+ * `code_thread_agent_<agent>`. Underscores, not a colon: the server takes a capability only as
+ * `^[a-z0-9_]+$` (`shared/agents/runtime_status.py`), and one it can't read rejects the whole frame.
+ */
+export const CODE_THREAD_AGENT_CAPABILITY_PREFIX = 'code_thread_agent_';
+/**
+ * Declared beside the per-agent capabilities whatever they are: "this CLI says which agents it
+ * runs", so none declared with it means none installed, not an older CLI that says nothing.
+ */
+export const CODE_THREAD_AGENTS_CAPABILITY = 'code_thread_agents';
+const AGENT_LABELS = { claude_code: 'Claude Code', codex: 'Codex' };
+function defaultIsExecutable(file) {
+    try {
+        if (!statSync(file).isFile())
+            return false;
+        accessSync(file, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether `binary` resolves to an executable file in one of `env.PATH`'s directories. */
+export function resolvesOnPath(binary, env = process.env, isExecutable = defaultIsExecutable) {
+    for (const dir of (env.PATH ?? '').split(path.delimiter)) {
+        // An empty entry is the current directory, which is no place a daemon finds an agent.
+        if (dir && path.isAbsolute(dir) && isExecutable(path.join(dir, binary)))
+            return true;
+    }
+    return false;
+}
+/** The agents whose binary resolves on `env.PATH`, in the order clients list them. */
+export function installedAgents(env = process.env, isExecutable = defaultIsExecutable) {
+    return Object.keys(AGENT_BINARIES).filter((agent) => resolvesOnPath(AGENT_BINARIES[agent], env, isExecutable));
+}
+/** {@link CODE_THREAD_AGENTS_CAPABILITY}, then `code_thread_agent_<agent>` for each of `agents`. */
+export function agentCapabilities(agents) {
+    return [CODE_THREAD_AGENTS_CAPABILITY, ...agents.map((agent) => `${CODE_THREAD_AGENT_CAPABILITY_PREFIX}${agent}`)];
+}
+/** Why a start for `agent` is refused on a Mac without its binary: the thread shows it as the failure. */
+export function missingAgentReason(agent) {
+    return (`${AGENT_LABELS[agent]} isn't installed on this Mac (no \`${AGENT_BINARIES[agent]}\` on the PATH Prohost runs with). ` +
+        'Install it there, or start the thread with another agent.');
+}