@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/hooks/match.d.ts

@@ -1,19 +1,4 @@
-/**
- * Hook predicate evaluator.
- *
- * Evaluates the optional `matches:` block on a hook manifest entry against
- * the runtime input passed by the agent CLI on a hook event. All declared
- * predicates AND together — the hook fires only if every one passes.
- *
- * Empty/missing matches => always passes (backward compat with hooks
- * authored before predicate support).
- *
- * Used at hook-fire time by either:
- *   (a) generated hook wrappers we install alongside the script, or
- *   (b) the script itself, by calling shouldFire() with parsed JSON input.
- */
 import type { HookMatches } from '../types.js';
-/** Runtime context passed to a hook by the agent CLI. */
 interface HookInput {
     hook_event_name?: string;
     prompt?: string;
@@ -21,17 +6,8 @@ interface HookInput {
     tool_args?: unknown;
     cwd?: string;
     permission_mode?: string;
-    /** Grok-style camelCase spelling of permission_mode. */
     permissionMode?: string;
 }
 export declare function isSafeHookRegex(source: string): boolean;
-/**
- * Decide whether a hook with the given match config should fire on this input.
- * Pure function — no side effects, no IO except git/cwd checks for predicates
- * that explicitly require them.
- *
- * Returns true if the hook should fire (all declared predicates pass), false
- * if it should be skipped.
- */
 export declare function shouldFire(matches: HookMatches | undefined, input: HookInput): boolean;
 export {};

package/dist/lib/hooks/match.js

@@ -1,17 +1,3 @@
-/**
- * Hook predicate evaluator.
- *
- * Evaluates the optional `matches:` block on a hook manifest entry against
- * the runtime input passed by the agent CLI on a hook event. All declared
- * predicates AND together — the hook fires only if every one passes.
- *
- * Empty/missing matches => always passes (backward compat with hooks
- * authored before predicate support).
- *
- * Used at hook-fire time by either:
- *   (a) generated hook wrappers we install alongside the script, or
- *   (b) the script itself, by calling shouldFire() with parsed JSON input.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { execSync } from 'child_process';
@@ -97,14 +83,6 @@ function compileHookRegex(source) {
         return null;
     }
 }
-/**
- * Decide whether a hook with the given match config should fire on this input.
- * Pure function — no side effects, no IO except git/cwd checks for predicates
- * that explicitly require them.
- *
- * Returns true if the hook should fire (all declared predicates pass), false
- * if it should be skipped.
- */
 export function shouldFire(matches, input) {
     if (!matches)
         return true;
@@ -134,9 +112,6 @@ export function shouldFire(matches, input) {
     if (matches.permission_mode !== undefined) {
         const allowed = arrayOf(matches.permission_mode);
         if (allowed.length > 0) {
-            // Fail-open on absence: only some harnesses (Claude Code) report the
-            // live mode. An input with no mode field passes; an explicit value not
-            // in the allowed list skips.
             const mode = input.permission_mode || input.permissionMode;
             if (mode && !allowed.includes(mode))
                 return false;
@@ -145,12 +120,6 @@ export function shouldFire(matches, input) {
     if (matches.permission_mode_not !== undefined) {
         const denied = arrayOf(matches.permission_mode_not);
         if (denied.length > 0) {
-            // The negative form exists because the positive one cannot express
-            // "everywhere except plan" without enumerating every other mode — and an
-            // enumeration silently stops firing the moment a harness adds or renames
-            // one, which for a guard means it quietly stops guarding. Naming the mode
-            // to skip keeps every unknown mode firing, so the failure direction is
-            // "ran unnecessarily", never "did not run".
             const mode = input.permission_mode || input.permissionMode;
             if (mode && denied.includes(mode))
                 return false;

package/dist/lib/hooks/profile.d.ts

@@ -10,23 +10,10 @@ export interface HookProfileRow {
     cacheStalePct: number;
     cacheMissPct: number;
     errorCount: number;
-    /**
-     * Fraction (0-1) of fires with a real crash exit (exit 1 / other nonzero
-     * except intentional PreToolUse deny code 2). Exit 2 is blockRate.
-     */
     errorRate?: number;
-    /**
-     * Count of intentional deny/block exits (PreToolUse exit 2). Deny-by-design
-     * guards (ask-user-question-guard, git-guard, plan-html-reminder) use this
-     * path — not a crash.
-     */
     blockCount: number;
-    /** Fraction (0-1) of fires with exit code 2 (intentional deny/block). */
     blockRate?: number;
-    /** Fraction (0-1) of fires that hit their configured timeout. */
     timeoutRate?: number;
-    /** Project key the row is scoped to (see project-key.ts) — set only when
-     *  a `--project` filter narrowed the underlying query. */
     project?: string;
 }
 interface RawFireEvent {
@@ -36,17 +23,9 @@ interface RawFireEvent {
     cache?: 'hit' | 'miss' | 'stale-prefetch' | string;
     exit?: number;
 }
-/**
- * Load every `hook.fire` event from the last `days` daily log files.
- * Lines that aren't JSON or aren't `hook.fire` events are silently skipped —
- * the events log is multiplexed (version.switch, secrets.get, …).
- */
 export declare function loadHookFireEvents(days?: number, logsDir?: string): RawFireEvent[];
-/** Aggregate fire events into a per-hook profile, sorted by p99 desc. */
 export declare function aggregateHookProfile(events: RawFireEvent[]): HookProfileRow[];
-/** Human-friendly duration: "42ms" / "1.2s" / "12s" / "2m". */
 export declare function formatMs(ms: number): string;
-/** Format a row's cache column: `hit:97% miss:3%` or `n/a` when nothing cached. */
 export declare function formatCacheColumn(row: HookProfileRow): string;
 export declare const DEFAULT_SLOW_HOOK_WARN_MS = 2000;
 export {};

package/dist/lib/hooks/profile.js

@@ -1,23 +1,7 @@
-/**
- * Hook profiling — reads `hook.fire` events from the daily JSONL logs that
- * generated shims (see `cache.ts`) emit on every invocation, and aggregates
- * per-hook timing + cache stats.
- *
- * Every hook gets a generated shim now (resolveHookCommand in hooks.ts) —
- * `cache:`, `matches:`, or a bare `matcher:` (e.g. git-guard/rm-guard) are all
- * enough to opt in. The only hooks NOT in this profile are ones with none of
- * the three, since a pure lifecycle hook with nothing to gate/cache/match runs
- * the raw script path with no timing wrapper at all.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getLogsDir } from '../state.js';
 import { percentile } from '../percentile.js';
-/**
- * Load every `hook.fire` event from the last `days` daily log files.
- * Lines that aren't JSON or aren't `hook.fire` events are silently skipped —
- * the events log is multiplexed (version.switch, secrets.get, …).
- */
 export function loadHookFireEvents(days = 7, logsDir = getLogsDir()) {
     if (!fs.existsSync(logsDir))
         return [];
@@ -54,7 +38,6 @@ export function loadHookFireEvents(days = 7, logsDir = getLogsDir()) {
     }
     return events;
 }
-/** Aggregate fire events into a per-hook profile, sorted by p99 desc. */
 export function aggregateHookProfile(events) {
     const byHook = new Map();
     for (const e of events) {
@@ -72,8 +55,6 @@ export function aggregateHookProfile(events) {
         const hits = evs.filter(e => e.cache === 'hit').length;
         const stale = evs.filter(e => e.cache === 'stale-prefetch').length;
         const misses = evs.filter(e => e.cache === 'miss').length;
-        // Exit classes (Claude/Codex PreToolUse convention): 0 allow, 2 deny/block,
-        // 1 / other nonzero = real error. Exit 2 is not a crash.
         const blocks = evs.filter(e => e.exit === 2).length;
         const errors = evs.filter(e => typeof e.exit === 'number' && e.exit !== 0 && e.exit !== 2).length;
         rows.push({
@@ -91,19 +72,11 @@ export function aggregateHookProfile(events) {
             blockCount: blocks,
             ...(errors > 0 ? { errorRate: Math.round((errors / n) * 1000) / 1000 } : {}),
             ...(blocks > 0 ? { blockRate: Math.round((blocks / n) * 1000) / 1000 } : {}),
-            // timeoutRate is not derivable here: the daily JSONL a shim writes only
-            // covers fires that reached their own trailing printf — an externally
-            // enforced timeout (the agent harness killing the process) never gets
-            // that far, so this log has no timeout signal at all. The warehouse
-            // path (asHookRows in commands/perf.ts) is the one that can see it,
-            // via the perf-spool `status:"timeout"` sample OpenCode's generated
-            // plugin writes directly (hooks.ts's recordTimeoutSample).
         });
     }
     rows.sort((a, b) => b.p99Ms - a.p99Ms);
     return rows;
 }
-/** Human-friendly duration: "42ms" / "1.2s" / "12s" / "2m". */
 export function formatMs(ms) {
     if (ms < 1000)
         return `${ms}ms`;
@@ -115,7 +88,6 @@ export function formatMs(ms) {
     const secs = Math.round((ms % 60_000) / 1000);
     return secs > 0 ? `${mins}m${secs}s` : `${mins}m`;
 }
-/** Format a row's cache column: `hit:97% miss:3%` or `n/a` when nothing cached. */
 export function formatCacheColumn(row) {
     if (row.cacheHitPct + row.cacheStalePct + row.cacheMissPct === 0)
         return 'n/a';

package/dist/lib/hosts/credential-transport.d.ts

@@ -1,8 +1,2 @@
-/** Refuse durable credential transfer until the destination SSH key is pinned. */
 export declare function assertCredentialTransportHostPinned(target: string, pinned?: boolean): void;
-/**
- * Resolve a `--device` value to an ssh target string for a credential-carrying
- * remote operation. Delegates to the same resolver `run --device` uses; on a
- * miss, treats the value as a raw ssh target and validates it.
- */
 export declare function resolveHostSshTarget(nameOrAlias: string): Promise<string>;

package/dist/lib/hosts/credential-transport.js

@@ -1,33 +1,16 @@
-/**
- * Credential transport policy for a fleet host (agents-owned, PHNX-3989).
- *
- * Whether a durable credential may leave this device for a given host is
- * agents fleet policy, not a secrets-engine concern: it hangs off the managed
- * `known_hosts` pin and the hosts/devices registry. The standalone `secrets`
- * CLI only carries the bundle once agents-cli has decided the destination is
- * trustworthy, so these guards live here and are passed INTO the transport,
- * never re-implemented on the engine side.
- */
 import { assertValidSshTarget } from '../ssh-exec.js';
 import { resolveHost } from './registry.js';
 import { sshTargetFor } from './types.js';
 import { isHostPinned } from '../devices/known-hosts.js';
-/** The host part of an ssh target (`user@host` -> `host`) for known_hosts matching. */
 function hostKeyLookupName(target) {
     return target.split('@').pop() ?? target;
 }
-/** Refuse durable credential transfer until the destination SSH key is pinned. */
 export function assertCredentialTransportHostPinned(target, pinned = isHostPinned(hostKeyLookupName(target))) {
     if (pinned)
         return;
     throw new Error(`Refusing to transfer provider credentials to '${target}' before its SSH host key is pinned. ` +
         `Connect once with 'agents ssh ${target}' and verify the host, then retry.`);
 }
-/**
- * Resolve a `--device` value to an ssh target string for a credential-carrying
- * remote operation. Delegates to the same resolver `run --device` uses; on a
- * miss, treats the value as a raw ssh target and validates it.
- */
 export async function resolveHostSshTarget(nameOrAlias) {
     const host = await resolveHost(nameOrAlias);
     if (host)

package/dist/lib/hosts/credentials.d.ts

@@ -1,21 +1,3 @@
-/**
- * Credential provisioning for `agents run --device --copy-creds`.
- *
- * `--copy-creds` USED TO copy each signed-in runtime's native login to a
- * persistent host — the Claude OAuth token (`.claude/.credentials.json`) plus
- * codex/grok/gemini `auth.json`-style files — so the box booted logged-in. Every
- * one of those is a **rotating, interactive OAuth / session credential**, and
- * copying it between devices is forbidden by the fleet-auth contract
- * (`docs/specifications.md` SING-1b, `docs/secrets.md`):
- * a shared refresh token rotates server-side on the next refresh and invalidates
- * every other copy — the "droid collapsed 10 boxes to 1 overnight" failure.
- *
- * So this module no longer serializes native logins at all. It REFUSES the
- * transfer and steers to the portable path — a long-lived, non-rotating provider
- * account (`agents accounts add` / `agents accounts sync`), whose bundle is
- * policy-`never` and safe to reuse on many devices. That sync rides its own
- * hardened SSH transport (RUSH-2527); it never touches this path.
- */
 import type { AgentId } from '../types.js';
 import type { DetectedRuntime } from '../crabbox/runtimes.js';
 export { isNativeOAuthRuntime, nativeOAuthTransferRefusal } from '../crabbox/runtimes.js';
@@ -24,25 +6,8 @@ export interface HostCredentials {
     detected: DetectedRuntime[];
     claudeCredentialsJson?: string | null;
 }
-/**
- * Build the setup/teardown scripts for a `--copy-creds` host run.
- *
- * Every runtime `--copy-creds` handles is a native OAuth / session login, so this
- * REFUSES rather than serialize one across the wire (SING-1b) — it throws with the
- * concrete `agents accounts` steer. The refusal happens BEFORE anything is
- * serialized, so a native credential can never reach a remote-write script. An
- * empty runtime set is a no-op (nothing to provision, nothing forbidden).
- */
 export declare function buildHostCredentialScript(opts: HostCredentials): {
     setup: string;
     teardown: string;
 };
-/**
- * Wrap a remote command with credential setup/teardown for a `--copy-creds` run.
- *
- * Delegates to {@link buildHostCredentialScript}, which now refuses to transfer a
- * native OAuth login — so a `--copy-creds` run against a signed-in native runtime
- * fails loudly here (before dispatch) with the `agents accounts sync` steer,
- * rather than shipping a rotating token to another device.
- */
 export declare function wrapHostCommandWithCredentials(innerCommand: string, opts: HostCredentials): string;

package/dist/lib/hosts/credentials.js

@@ -1,35 +1,5 @@
-/**
- * Credential provisioning for `agents run --device --copy-creds`.
- *
- * `--copy-creds` USED TO copy each signed-in runtime's native login to a
- * persistent host — the Claude OAuth token (`.claude/.credentials.json`) plus
- * codex/grok/gemini `auth.json`-style files — so the box booted logged-in. Every
- * one of those is a **rotating, interactive OAuth / session credential**, and
- * copying it between devices is forbidden by the fleet-auth contract
- * (`docs/specifications.md` SING-1b, `docs/secrets.md`):
- * a shared refresh token rotates server-side on the next refresh and invalidates
- * every other copy — the "droid collapsed 10 boxes to 1 overnight" failure.
- *
- * So this module no longer serializes native logins at all. It REFUSES the
- * transfer and steers to the portable path — a long-lived, non-rotating provider
- * account (`agents accounts add` / `agents accounts sync`), whose bundle is
- * policy-`never` and safe to reuse on many devices. That sync rides its own
- * hardened SSH transport (RUSH-2527); it never touches this path.
- */
 import { isNativeOAuthRuntime, nativeOAuthTransferRefusal } from '../crabbox/runtimes.js';
-// The native-OAuth predicate + refusal are canonical in `crabbox/runtimes.ts`
-// (next to `LEASE_RUNTIMES`), so `--copy-creds` here and `--lease` there refuse
-// against exactly the same set. Re-export for this module's existing consumers.
 export { isNativeOAuthRuntime, nativeOAuthTransferRefusal } from '../crabbox/runtimes.js';
-/**
- * Build the setup/teardown scripts for a `--copy-creds` host run.
- *
- * Every runtime `--copy-creds` handles is a native OAuth / session login, so this
- * REFUSES rather than serialize one across the wire (SING-1b) — it throws with the
- * concrete `agents accounts` steer. The refusal happens BEFORE anything is
- * serialized, so a native credential can never reach a remote-write script. An
- * empty runtime set is a no-op (nothing to provision, nothing forbidden).
- */
 export function buildHostCredentialScript(opts) {
     const native = opts.runtimes.filter(isNativeOAuthRuntime);
     if (native.length > 0) {
@@ -37,14 +7,6 @@ export function buildHostCredentialScript(opts) {
     }
     return { setup: '', teardown: '' };
 }
-/**
- * Wrap a remote command with credential setup/teardown for a `--copy-creds` run.
- *
- * Delegates to {@link buildHostCredentialScript}, which now refuses to transfer a
- * native OAuth login — so a `--copy-creds` run against a signed-in native runtime
- * fails loudly here (before dispatch) with the `agents accounts sync` steer,
- * rather than shipping a rotating token to another device.
- */
 export function wrapHostCommandWithCredentials(innerCommand, opts) {
     const { setup, teardown } = buildHostCredentialScript(opts);
     return [

package/dist/lib/hosts/dispatch.d.ts

@@ -4,52 +4,10 @@ import { type HostTask } from './tasks.js';
 import { type HostCredentials } from './credentials.js';
 import { deriveMirroredCwd, homeRemainder, remoteCdPrefix } from '../project-root.js';
 export { deriveMirroredCwd, homeRemainder, remoteCdPrefix };
-/**
- * Merge the resolved actor's provenance env UNDER a caller-supplied env, so every
- * remote `agents …` invocation forwards `AGENTS_ACTOR*` / `GIT_*` across the SSH
- * hop. Without it the remote re-resolves the actor from the ORIGINATING box's
- * `SSH_CONNECTION` (the wrong IP) and mis-credits the run to the shared machine or
- * `UNRESOLVED@<host>` (RUSH-2028). A caller-supplied value wins on any key
- * collision, mirroring `buildExecEnv`'s `...options.env` precedence (exec.ts).
- */
 export declare function withActorEnv(env?: Record<string, string>): Record<string, string>;
-/**
- * The shell-export prelude prepended to EVERY remote `agents run` dispatch —
- * actor provenance plus, for a `run auto` dispatch, the chain-hop guard
- * (RUN_AUTO_HOST_RESOLVED_ENV): this dispatch already IS the affinity pick, so
- * the remote CLI must not re-run host affinity and hop to a third host. The
- * guard MUST be a shell export (landing in the remote CLI's own process.env,
- * which `runAutoDefaultsToAffinity` reads) — a forwarded `--env` flag would
- * only reach the spawned agent's env and the remote `run auto` would re-pick.
- * Shared by the interactive (runInteractiveOnHost) and detached
- * (launchDetached) paths so both behave identically.
- *
- * `extra` carries the markers that are true of ONE path rather than both — the
- * interactive dispatch adds REMOTE_INTERACTIVE_ENV, which the remote CLI reads
- * to know its stdio is an ssh link (reconnect target, `--no-follow` pane
- * requirement). It goes through this builder rather than being concatenated on
- * at the call site so every remote env marker is exported the same way, in one
- * place.
- */
 export declare function remoteRunShellPrelude(agent: string, extra?: Record<string, string>): string;
-/**
- * The env every remote `agents run` dispatch carries across the SSH hop —
- * actor provenance, the `run auto` chain-hop guard, and the caller's path
- * markers. `remoteRunShellPrelude` renders it as POSIX exports; a Windows peer
- * gets the same record as `$env:` assignments in its PowerShell script.
- */
 export declare function remoteRunEnv(agent: string, extra?: Record<string, string>): Record<string, string>;
-/**
- * Launch a detached login-shell command in its own Unix session/process group.
- *
- * Node is already a hard requirement for a host that can run `agents`. Its
- * `detached: true` contract calls setsid(2) on Unix, unlike `nohup ... &` under
- * a non-interactive shell where the background wrapper can remain in the SSH
- * shell's process group. Returning the group leader PID makes `kill(-pid)` a
- * reliable whole-tree operation for both normal stops and rollback cleanup.
- */
 export declare function buildDetachedLaunchCommand(inner: string): string;
-/** Build the detached PowerShell launch protocol used by Windows SSH hosts. */
 export declare function buildWindowsDetachedLaunchCommand(opts: {
     forwardedArgs: string[];
     remoteCwd?: string;
@@ -60,183 +18,85 @@ export declare function buildWindowsDetachedLaunchCommand(opts: {
 }): string;
 export interface DispatchResult {
     task: HostTask;
-    /** Exit code when followed; undefined when detached (--no-follow). */
     exitCode?: number;
 }
-/** Terminate a detached dispatch that its caller could not persist locally. */
 export declare function terminateDispatchedTask(task: HostTask): void;
-/**
- * Build the remote shell used by {@link stopDispatchedTask}. Exported for
- * unit tests — the keep-log / no-clobber contract lives in this script.
- *
- * Protocol (printed to stdout for the local caller):
- * - `SIGNALED`  — process group was live; SIGTERM/KILL applied; wrote 143
- * - `ALREADY` + code — group gone; adopted existing `.exit` (never overwrite)
- * - `GONE` — group gone and no `.exit`; write 143 as the local stop outcome
- * Exit 1 if the group is still alive after TERM/KILL (can't stop it).
- */
 export declare function buildStopRemoteCommand(pid: number, remoteExit: string): string;
 export declare function buildWindowsStopRemoteCommand(pid: number, remoteExit: string): string;
-/**
- * Stop a running host task from the origin machine (`agents devices stop <id>`).
- *
- * Unlike {@link terminateDispatchedTask} (rollback cleanup after a failed
- * persist), this keeps the remote log so `agents logs <id>` still works,
- * writes a terminal `.exit` marker only when we actually stopped a live group
- * (or no code existed), and never clobbers a real completed-run exit code.
- */
 export declare function stopDispatchedTask(task: HostTask): HostTask;
 export interface DispatchOptions {
     agent: string;
     prompt: string;
-    /** Explicit agent version pin (e.g. "2.1.207") to forward as `agent@version`. */
     version?: string;
-    /** Run strategy (e.g. "balanced") — the remote picks among ITS signed-in accounts. */
     strategy?: string;
-    /** Named provider account — the remote resolves it against ITS signed-in versions. */
     account?: string;
     balanced?: boolean;
     fallback?: string;
     mode?: string;
     model?: string;
-    /** Reasoning effort — forwarded unless 'auto' (the remote default). */
     effort?: string;
-    /** `--env k=v` pairs, forwarded verbatim (the remote CLI parses them). */
     env?: string[];
-    /** `--add-dir` grants, already made remote-portable. */
     addDir?: string[];
-    /** Agent wall-clock cap, forwarded as `--timeout <duration>` for the REMOTE to enforce. */
     timeout?: string;
-    /** Loop family — the loop driver runs on the host. */
     loop?: boolean;
     maxIterations?: string;
     budget?: string;
     until?: string;
     interval?: string;
-    /** Remote emits ndjson into its log; the local follow streams it verbatim. */
     json?: boolean;
     verbose?: boolean;
-    /** Skip the budget-confirm prompt — a detached remote run can't answer one. */
     yes?: boolean;
-    /** Route through the Agent Client Protocol. */
     acp?: boolean;
-    /** False forwards --no-auto-secrets (workflow secrets resolve on the REMOTE keychain). */
     autoSecrets?: boolean;
-    /** Native-CLI passthrough (everything after `--`), appended last. */
     passthroughArgs?: string[];
     remoteCwd?: string;
-    /** `remoteCwd` was derived from the local cwd — mirror it, don't fail on it. */
     mirrorCwd?: boolean;
-    /**
-     * Force the remote run's NEW session to use this exact id (Claude only, via
-     * `agents run --session-id`). Captured on the task record so the run is
-     * resumable by id. Mutually exclusive with `resume`.
-     */
     sessionId?: string;
-    /**
-     * Durable `--name <slug>` handle, forwarded to the remote `agents run` and
-     * recorded on the local task so `agents logs <name>` / `agents devices ps` resolve it.
-     */
     name?: string;
-    /** Resume an existing session on the host by id (via `agents run --resume`). */
     resume?: string;
-    /**
-     * Forward `--emit-session-id` so the remote run prints its resolved session id
-     * as a stdout sentinel (hosts/session-marker.ts). The launcher parses that id
-     * out of the followed log and stamps it on the task — the join that maps a
-     * remote-created session back home for agents that don't take `--session-id`.
-     */
     emitSessionId?: boolean;
-    /** Stream progress and block until completion (default true). */
     follow?: boolean;
     timeoutMs?: number;
-    /** Copy runtime credentials to the host before the run and shred them after. */
     copyCreds?: HostCredentials;
 }
 export declare function buildRunForwardedArgs(opts: DispatchOptions): string[];
 export interface InteractiveDispatchOptions {
     agent: string;
-    /** Explicit agent version pin (e.g. "2.1.207") to forward as `agent@version`. */
     version?: string;
-    /** Preserve the trailing-# account picker so selection happens on the execution host. */
     accountPicker?: boolean;
-    /** Explicit run strategy (e.g. "balanced") to forward as `--strategy <strategy>`. */
     strategy?: string;
-    /** Named provider account to resolve on the remote host. */
     account?: string;
-    /** Optional prompt — forwarded only when the caller explicitly forced interactive mode. */
     prompt?: string;
     mode?: string;
     model?: string;
-    /** Reasoning effort to forward as `--effort <effort>`. */
     effort?: string;
-    /** Additional directories to grant, already made remote-portable. */
     addDir?: string[];
-    /** Stream events as JSON lines. */
     json?: boolean;
-    /** Show detailed execution logs. */
     verbose?: boolean;
-    /** Kill the agent after this duration, forwarded as `--timeout <duration>`. */
     timeout?: string;
-    /** Skip the interactive budget-confirm prompt. */
     yes?: boolean;
-    /** Route through the Agent Client Protocol. */
     acp?: boolean;
     remoteCwd?: string;
-    /** `remoteCwd` was derived from the local cwd — mirror it, don't fail on it. */
     mirrorCwd?: boolean;
     sessionId?: string;
     name?: string;
     resume?: string;
     passthroughArgs?: string[];
     raw?: boolean;
-    /** Forward `--interactive` to the remote so a prompt-bearing run still starts the TUI. */
     forceInteractive?: boolean;
-    /** `--env k=v` pairs, forwarded verbatim (the remote CLI parses them). */
     env?: string[];
     balanced?: boolean;
     fallback?: string;
-    /** Copy runtime credentials to the host before the run and shred them after. */
     copyCreds?: HostCredentials;
 }
-/**
- * Build the remote `agents run …` argv for an INTERACTIVE host dispatch. The
- * remote agent sees a TTY, so we omit `--quiet`; the remote CLI will launch its
- * normal interactive TUI / tmux wrapper. A prompt is only included when the
- * caller explicitly forced interactive mode (otherwise the remote CLI would
- * infer headless from the prompt).
- */
 export declare function buildInteractiveRunForwardedArgs(opts: InteractiveDispatchOptions): string[];
-/**
- * The remote command of an interactive host dispatch, by peer shell.
- *
- * A Windows peer's sshd hands the command to PowerShell, which cannot parse the
- * POSIX `export …; { cd … || cd "$HOME"; } && agents …` form (a `run --device
- * <windows box>` from a TTY died with `At line:1 char:420` at the `||`). That
- * peer gets the rendered PowerShell every other `--device` site uses — env,
- * mirrored cwd and argv inside one `-EncodedCommand` — the interactive analogue
- * of `buildWindowsDetachedLaunchCommand`.
- */
 export declare function buildInteractiveRemoteCommand(remoteShell: ReturnType<typeof remoteShellFor>, opts: InteractiveDispatchOptions): string;
-/**
- * Run an agent interactively on a host, forwarding the local TTY over SSH.
- * Returns the SSH exit code. The remote `agents` CLI is responsible for its own
- * tmux wrapping; the local machine is just the transport.
- */
 export declare function runInteractiveOnHost(host: Host, opts: InteractiveDispatchOptions): Promise<number>;
-/** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --device` path). */
 export declare function dispatchToHost(host: Host, opts: DispatchOptions): Promise<DispatchResult>;
 interface CommandDispatchOptions {
-    /** `agents …` args (command name first), already stripped of routing flags. */
     forwardedArgs: string[];
     remoteCwd?: string;
     follow?: boolean;
     timeoutMs?: number;
 }
-/**
- * Dispatch an arbitrary long-running `agents <command>` onto a host detached —
- * used for `teams start --watch --device`, whose supervisor must outlive the SSH
- * connection. Reachability is assumed (the caller has already resolved the host);
- * a launch failure surfaces the remote stderr.
- */
 export declare function dispatchAgentsCommand(host: Host, opts: CommandDispatchOptions): Promise<DispatchResult>;