@phnx-labs/agents-cli 1.20.32 → 1.20.33

package/dist/lib/agent-spec/index.js

@@ -0,0 +1,35 @@
+// Public API for the agent-spec engine. Commands import from here and get the
+// production provider bound automatically; tests import the pure `./resolve.js`
+// core directly and inject a fake provider.
+//
+// One vocabulary, one resolver, reused by every subcommand that accepts
+// `<agent>[@<qualifier>]`. Built for the hot path: exact / @pinned / bare specs
+// resolve with no directory enumeration; only @latest/@oldest/@all enumerate,
+// via the mtime-cached provider.
+import { defaultVersionProvider } from './provider.js';
+import * as core from './resolve.js';
+export * from './types.js';
+export * from './primitives.js';
+/** Shared `--help` epilog so every agent-spec command documents the same grammar. */
+export const AGENT_SPEC_HELP = 'Agent spec: <agent>[@<qualifier>]. Qualifiers: ' +
+    '@latest (highest installed), @oldest (lowest installed), ' +
+    '@pinned / @default (your configured default — synonyms), ' +
+    '@all (every installed version), or an exact @x.y.z. ' +
+    'Bare <agent> uses the resolved default (project pin → global default). ' +
+    'Comma-separate to combine: claude@all,codex@latest.';
+/** Resolve a spec (single or comma-list) into concrete installed targets. */
+export function resolveAgentTargets(spec, opts = {}) {
+    return core.resolveAgentTargets(spec, defaultVersionProvider, opts);
+}
+/** Resolve a spec that must name exactly one installed version. */
+export function resolveSingleAgentTarget(spec, opts = {}) {
+    return core.resolveSingleAgentTarget(spec, defaultVersionProvider, opts);
+}
+/** Resolve a read/list command's version filter (undefined → all, @default → the default, else concrete). */
+export function resolveVersionFilter(agent, qualifier, opts = {}) {
+    return core.resolveVersionFilter(agent, qualifier, defaultVersionProvider, opts);
+}
+/** Concrete version filter for list/display commands (undefined → show all, @default → the default version). */
+export function resolveListFilter(agent, qualifier, opts = {}) {
+    return core.resolveListFilter(agent, qualifier, defaultVersionProvider, opts);
+}

package/dist/lib/agent-spec/primitives.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The only shape a version string may take before it reaches an exec/shim/path
+ * boundary. Accepts the literal `latest` or a 1–64 char run of `[A-Za-z0-9._+-]`
+ * with no `..` traversal. This is THE validation gate — every resolver funnels
+ * exact-version tokens through it.
+ */
+export declare const VERSION_RE: RegExp;
+/** Canonical qualifier set, in help/display order. `pinned` ≡ `default`. */
+export declare const AGENT_QUALIFIERS: readonly ["latest", "oldest", "pinned", "default", "all"];
+export type AgentQualifier = (typeof AGENT_QUALIFIERS)[number];
+/**
+ * Record-filter-only qualifiers. `any` means "no version constraint" for
+ * historical-record queries (sessions/teams resume) — accepted by the filter
+ * path but intentionally kept out of the display vocabulary.
+ */
+export declare const RECORD_ONLY_QUALIFIERS: readonly ["any"];
+/**
+ * Ordering for version strings (ascending).
+ *   1. numeric segment comparison (semver-ish: `2.1.187` > `2.1.143`)
+ *   2. tie → trailing `-N` build suffix, numerically (`2026.2.19-2` > `2026.2.19`)
+ *   3. still tied → 0 (legacy behavior: `1.0` == `1.0.0`, non-numeric tails == 0)
+ *
+ * Deliberately NOT a full semver comparator: OpenClaw's `-N` is a rebuild marker
+ * (higher = newer); a semver comparator would invert it. The `-N` tiebreak is the
+ * only addition over the historical numeric-only compare, so suffix-free versions
+ * (claude/codex semver) are unaffected.
+ */
+export declare function compareVersions(a: string, b: string): number;

package/dist/lib/agent-spec/primitives.js

@@ -0,0 +1,57 @@
+// Pure version primitives for the agent-spec engine — zero dependencies, so the
+// whole module (and versions.ts, which re-uses these) stays trivially testable.
+/**
+ * The only shape a version string may take before it reaches an exec/shim/path
+ * boundary. Accepts the literal `latest` or a 1–64 char run of `[A-Za-z0-9._+-]`
+ * with no `..` traversal. This is THE validation gate — every resolver funnels
+ * exact-version tokens through it.
+ */
+export const VERSION_RE = /^(?:latest|(?!.*\.\.)[A-Za-z0-9._+-]{1,64})$/;
+/** Canonical qualifier set, in help/display order. `pinned` ≡ `default`. */
+export const AGENT_QUALIFIERS = ['latest', 'oldest', 'pinned', 'default', 'all'];
+/**
+ * Record-filter-only qualifiers. `any` means "no version constraint" for
+ * historical-record queries (sessions/teams resume) — accepted by the filter
+ * path but intentionally kept out of the display vocabulary.
+ */
+export const RECORD_ONLY_QUALIFIERS = ['any'];
+/** Split a version into numeric `.`-segments (non-numeric tail → 0), e.g. `2026.2.19-2` → [2026,2,19]. */
+function numericParts(v) {
+    return v.split('.').map((n) => parseInt(n, 10) || 0);
+}
+/**
+ * Trailing `-<digits>` build suffix as a number (0 when absent). OpenClaw ships
+ * same-day rebuilds as `2026.2.19-2` where a higher `-N` is NEWER — the opposite
+ * of a semver pre-release. Used only to break exact numeric ties, so semver-style
+ * versions (which carry no `-N`) are unaffected.
+ */
+function buildSuffix(v) {
+    const m = /-(\d+)$/.exec(v);
+    return m ? parseInt(m[1], 10) : 0;
+}
+/**
+ * Ordering for version strings (ascending).
+ *   1. numeric segment comparison (semver-ish: `2.1.187` > `2.1.143`)
+ *   2. tie → trailing `-N` build suffix, numerically (`2026.2.19-2` > `2026.2.19`)
+ *   3. still tied → 0 (legacy behavior: `1.0` == `1.0.0`, non-numeric tails == 0)
+ *
+ * Deliberately NOT a full semver comparator: OpenClaw's `-N` is a rebuild marker
+ * (higher = newer); a semver comparator would invert it. The `-N` tiebreak is the
+ * only addition over the historical numeric-only compare, so suffix-free versions
+ * (claude/codex semver) are unaffected.
+ */
+export function compareVersions(a, b) {
+    const na = numericParts(a);
+    const nb = numericParts(b);
+    for (let i = 0; i < Math.max(na.length, nb.length); i++) {
+        const av = na[i] || 0;
+        const bv = nb[i] || 0;
+        if (av !== bv)
+            return av - bv;
+    }
+    const sa = buildSuffix(a);
+    const sb = buildSuffix(b);
+    if (sa !== sb)
+        return sa - sb;
+    return 0;
+}

package/dist/lib/agent-spec/provider.d.ts

@@ -0,0 +1,2 @@
+import type { VersionProvider } from './types.js';
+export declare const defaultVersionProvider: VersionProvider;

package/dist/lib/agent-spec/provider.js

@@ -0,0 +1,9 @@
+// The production VersionProvider: the only fs/meta-coupled file in the engine.
+// Everything else in this module is pure and testable without it.
+import { listInstalledVersions, getGlobalDefault, getProjectVersion, isVersionInstalled, } from '../versions.js';
+export const defaultVersionProvider = {
+    listInstalled: (agent) => listInstalledVersions(agent),
+    getProjectVersion: (agent, cwd) => getProjectVersion(agent, cwd),
+    getGlobalDefault: (agent) => getGlobalDefault(agent),
+    isInstalled: (agent, version) => isVersionInstalled(agent, version),
+};

package/dist/lib/agent-spec/resolve.d.ts

@@ -0,0 +1,33 @@
+import type { AgentId } from '../types.js';
+import { type AgentTarget, type VersionProvider, type VersionSource, type ResolveOptions, type VersionFilter } from './types.js';
+/**
+ * Resolve an agent spec (single or comma-list) into concrete installed targets.
+ * `@latest`/`@oldest`/`@all` range over installed versions.
+ */
+export declare function resolveAgentTargets(spec: string, provider: VersionProvider, opts?: ResolveOptions): AgentTarget[];
+/**
+ * Single-target commands (`run`, `sync`, `inspect`): resolve a spec that must
+ * name exactly one installed version. Rejects `@all` / multi-target specs.
+ */
+export declare function resolveSingleAgentTarget(spec: string, provider: VersionProvider, opts?: ResolveOptions): {
+    agent: AgentId;
+    version: string;
+    source: VersionSource;
+};
+/**
+ * Read/list commands: resolve a qualifier into a version filter.
+ *   undefined / '' / @any → no filter (show all installed versions)
+ *   @default / @pinned    → the literal 'default' sentinel (show the configured default)
+ *   @latest/@oldest/x.y.z → a concrete version (throws if not installed)
+ * Uniform `@default` handling fixes the prior rules-vs-view inconsistency.
+ */
+export declare function resolveVersionFilter(agent: AgentId, qualifier: string | undefined | null, provider: VersionProvider, opts?: ResolveOptions): VersionFilter;
+/**
+ * Concrete version filter for list/display commands whose downstream code
+ * filters by an exact version string (not the `'default'` sentinel `view` uses).
+ *   undefined / '' / @any → undefined  (no filter → show all installed)
+ *   @default / @pinned    → the configured default version, or undefined if none
+ *                           is set (falls back to show-all rather than erroring)
+ *   @latest/@oldest/x.y.z → a concrete version (throws AgentSpecError if bad)
+ */
+export declare function resolveListFilter(agent: AgentId, qualifier: string | undefined | null, provider: VersionProvider, opts?: ResolveOptions): string | undefined;

package/dist/lib/agent-spec/resolve.js

@@ -0,0 +1,174 @@
+// Pure agent-spec resolution — the engine core. Takes a VersionProvider instead
+// of touching the filesystem, so every branch is unit-testable with in-memory
+// fixtures. Domain = installed versions (`add`/install use a separate npm path).
+// Never calls process.exit; throws AgentSpecError on bad input.
+import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError } from '../agents.js';
+import { VERSION_RE } from './primitives.js';
+import { AgentSpecError, } from './types.js';
+/**
+ * Resolve an agent spec (single or comma-list) into concrete installed targets.
+ * `@latest`/`@oldest`/`@all` range over installed versions.
+ */
+export function resolveAgentTargets(spec, provider, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const available = opts.availableAgents ?? ALL_AGENT_IDS;
+    const onAmbiguous = opts.onAmbiguous ?? 'error';
+    const rawEntries = spec.split(',').map((s) => s.trim()).filter(Boolean);
+    if (rawEntries.length === 0) {
+        throw new AgentSpecError('Empty agent spec.', 'empty');
+    }
+    // Expand the bare literal `all` (or `all@all`) into every available agent that
+    // has ≥1 installed version. Lenient: agents with nothing installed are skipped.
+    const entries = [];
+    for (const e of rawEntries) {
+        if (e === 'all' || e === 'all@all') {
+            for (const a of available) {
+                if (provider.listInstalled(a).length > 0)
+                    entries.push(`${a}@all`);
+            }
+        }
+        else {
+            entries.push(e);
+        }
+    }
+    const out = [];
+    const seen = new Set();
+    const push = (agent, version, source) => {
+        const key = `${agent}@${version ?? ''}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            out.push({ agent, version, source });
+        }
+    };
+    for (const entry of entries) {
+        const at = entry.indexOf('@');
+        const agentToken = (at === -1 ? entry : entry.slice(0, at)).trim();
+        const qualifier = at === -1 ? null : entry.slice(at + 1).trim();
+        if (!agentToken)
+            continue;
+        if (at !== -1 && !qualifier) {
+            throw new AgentSpecError(`Missing version in '${entry}'. Use ${agentToken}@x.y.z, @latest, @oldest, @pinned, @default, or @all.`, 'missing-version');
+        }
+        const agent = resolveAgentName(agentToken);
+        if (!agent || !available.includes(agent)) {
+            throw new AgentSpecError(formatAgentError(agentToken, [...available]), 'unknown-agent');
+        }
+        const name = AGENTS[agent].name;
+        // ----- bare: project pin → global default → sole/ambiguous installed -----
+        if (qualifier === null) {
+            const proj = provider.getProjectVersion(agent, cwd);
+            if (proj) {
+                push(agent, proj, 'project-pin');
+                continue;
+            }
+            const glob = provider.getGlobalDefault(agent);
+            if (glob) {
+                push(agent, glob, 'global-default');
+                continue;
+            }
+            const installed = provider.listInstalled(agent);
+            if (installed.length === 0) {
+                push(agent, null, 'none');
+                continue;
+            }
+            if (installed.length === 1) {
+                push(agent, installed[0], 'sole-installed');
+                continue;
+            }
+            if (onAmbiguous === 'newest') {
+                push(agent, installed[installed.length - 1], 'newest-installed');
+                continue;
+            }
+            throw new AgentSpecError(`No default version set for ${name}. Specify one (${agent}@<version>) or set it: agents use ${agent}@<version>.`, 'no-default', agent, installed);
+        }
+        // ----- @pinned / @default: the configured global default -----
+        if (qualifier === 'pinned' || qualifier === 'default') {
+            const def = provider.getGlobalDefault(agent);
+            if (!def) {
+                throw new AgentSpecError(`No default version set for ${name}. Run: agents use ${agent}@<version>`, 'no-default', agent, provider.listInstalled(agent));
+            }
+            push(agent, def, 'global-default(@pinned)');
+            continue;
+        }
+        // ----- @all: every installed version -----
+        if (qualifier === 'all') {
+            const installed = provider.listInstalled(agent);
+            if (installed.length === 0) {
+                throw new AgentSpecError(`No managed versions are installed for ${name}. Run: agents add ${agent}@latest`, 'none-installed', agent);
+            }
+            for (const v of installed)
+                push(agent, v, 'explicit');
+            continue;
+        }
+        // ----- @latest / @oldest: ends of the installed range -----
+        if (qualifier === 'latest' || qualifier === 'oldest') {
+            const installed = provider.listInstalled(agent);
+            if (installed.length === 0) {
+                throw new AgentSpecError(`No managed versions are installed for ${name}. Run: agents add ${agent}@latest`, 'none-installed', agent);
+            }
+            const isOldest = qualifier === 'oldest';
+            push(agent, isOldest ? installed[0] : installed[installed.length - 1], isOldest ? 'alias-oldest' : 'alias-latest');
+            continue;
+        }
+        // ----- exact version: validate then existence-check (no enumeration) -----
+        if (!VERSION_RE.test(qualifier)) {
+            throw new AgentSpecError(`Invalid version '${qualifier}' for ${name}. Allowed: latest or [A-Za-z0-9._+-]{1,64}.`, 'invalid-version', agent);
+        }
+        if (!provider.isInstalled(agent, qualifier)) {
+            const installed = provider.listInstalled(agent);
+            const hint = installed.length ? ` Installed: ${installed.join(', ')}.` : '';
+            throw new AgentSpecError(`${name}@${qualifier} is not installed.${hint} Install it: agents add ${agent}@${qualifier}`, 'not-installed', agent, installed);
+        }
+        push(agent, qualifier, 'explicit');
+    }
+    return out;
+}
+/**
+ * Single-target commands (`run`, `sync`, `inspect`): resolve a spec that must
+ * name exactly one installed version. Rejects `@all` / multi-target specs.
+ */
+export function resolveSingleAgentTarget(spec, provider, opts = {}) {
+    const targets = resolveAgentTargets(spec, provider, opts);
+    if (targets.length !== 1) {
+        throw new AgentSpecError(`'${spec}' resolves to ${targets.length} targets; this command needs exactly one.`, 'multi-not-allowed');
+    }
+    const t = targets[0];
+    if (t.version === null) {
+        throw new AgentSpecError(`No installed version for ${AGENTS[t.agent].name}. Run: agents add ${t.agent}@latest`, 'none-installed', t.agent);
+    }
+    return { agent: t.agent, version: t.version, source: t.source };
+}
+/**
+ * Read/list commands: resolve a qualifier into a version filter.
+ *   undefined / '' / @any → no filter (show all installed versions)
+ *   @default / @pinned    → the literal 'default' sentinel (show the configured default)
+ *   @latest/@oldest/x.y.z → a concrete version (throws if not installed)
+ * Uniform `@default` handling fixes the prior rules-vs-view inconsistency.
+ */
+export function resolveVersionFilter(agent, qualifier, provider, opts = {}) {
+    const q = qualifier?.trim();
+    if (!q)
+        return { version: null, source: 'all-versions' };
+    if (q === 'default' || q === 'pinned')
+        return { version: 'default', source: 'default' };
+    if (q === 'any')
+        return { version: null, source: 'all-versions' };
+    const { version, source } = resolveSingleAgentTarget(`${agent}@${q}`, provider, { ...opts, availableAgents: [agent] });
+    return { version, source };
+}
+/**
+ * Concrete version filter for list/display commands whose downstream code
+ * filters by an exact version string (not the `'default'` sentinel `view` uses).
+ *   undefined / '' / @any → undefined  (no filter → show all installed)
+ *   @default / @pinned    → the configured default version, or undefined if none
+ *                           is set (falls back to show-all rather than erroring)
+ *   @latest/@oldest/x.y.z → a concrete version (throws AgentSpecError if bad)
+ */
+export function resolveListFilter(agent, qualifier, provider, opts = {}) {
+    const q = qualifier?.trim();
+    if (!q || q === 'any')
+        return undefined;
+    if (q === 'default' || q === 'pinned')
+        return provider.getGlobalDefault(agent) ?? undefined;
+    return resolveSingleAgentTarget(`${agent}@${q}`, provider, { ...opts, availableAgents: [agent] }).version;
+}

package/dist/lib/agent-spec/types.d.ts

@@ -0,0 +1,57 @@
+import type { AgentId } from '../types.js';
+/** How a resolved version was arrived at — for provenance, display, and error rendering. */
+export type VersionSource = 'explicit' | 'project-pin' | 'global-default' | 'global-default(@pinned)' | 'sole-installed' | 'newest-installed' | 'alias-latest' | 'alias-oldest' | 'none';
+export interface AgentTarget {
+    agent: AgentId;
+    /** Resolved exact version, or null when the agent has no installed versions yet. */
+    version: string | null;
+    source: VersionSource;
+}
+export type AgentSpecErrorCode = 'empty' | 'unknown-agent' | 'missing-version' | 'invalid-version' | 'not-installed' | 'no-default' | 'none-installed' | 'multi-not-allowed';
+/**
+ * Thrown on any bad spec — never `process.exit`, so the engine is safe on the
+ * hot path and in library contexts. `code` + `installed` let callers render a
+ * consistent message (e.g. the "No default … Specify one:" version list) without
+ * string-matching.
+ */
+export declare class AgentSpecError extends Error {
+    readonly code: AgentSpecErrorCode;
+    readonly agent?: AgentId | undefined;
+    readonly installed?: string[] | undefined;
+    constructor(message: string, code: AgentSpecErrorCode, agent?: AgentId | undefined, installed?: string[] | undefined);
+}
+/**
+ * The filesystem/meta seam. The pure resolver takes this instead of importing
+ * versions.ts, so it is fully unit-testable with in-memory fixtures — no $HOME,
+ * no subprocess. `provider.ts` supplies the production adapter.
+ */
+export interface VersionProvider {
+    /** Installed versions, sorted ascending by `compareVersions`. */
+    listInstalled(agent: AgentId): string[];
+    /** Version pinned by a project-root agents.yaml, or null. */
+    getProjectVersion(agent: AgentId, cwd: string): string | null;
+    /** The configured global default version, or null. */
+    getGlobalDefault(agent: AgentId): string | null;
+    /** Whether an exact version is installed. */
+    isInstalled(agent: AgentId, version: string): boolean;
+}
+export interface ResolveOptions {
+    /** Project dir for a bare spec's project pin. Defaults to process.cwd(). */
+    cwd?: string;
+    /** Restrict which agents a spec may name (e.g. only mcp-capable). Defaults to all. */
+    availableAgents?: readonly AgentId[];
+    /**
+     * Bare spec, >1 installed, no pin/default:
+     *   'error'  (default) → throw AgentSpecError{code:'no-default'} — safe for
+     *                        state-mutating commands (sync/use).
+     *   'newest'          → pick the newest installed (source:'newest-installed');
+     *                        callers should note it. For execution verbs (run/exec).
+     */
+    onAmbiguous?: 'error' | 'newest';
+}
+/** A read/list command's version filter. `null` = show all; `'default'` = show the configured default. */
+export type FilterVersion = string | null | 'default';
+export interface VersionFilter {
+    version: FilterVersion;
+    source: VersionSource | 'all-versions' | 'default';
+}

package/dist/lib/agent-spec/types.js

@@ -0,0 +1,18 @@
+/**
+ * Thrown on any bad spec — never `process.exit`, so the engine is safe on the
+ * hot path and in library contexts. `code` + `installed` let callers render a
+ * consistent message (e.g. the "No default … Specify one:" version list) without
+ * string-matching.
+ */
+export class AgentSpecError extends Error {
+    code;
+    agent;
+    installed;
+    constructor(message, code, agent, installed) {
+        super(message);
+        this.code = code;
+        this.agent = agent;
+        this.installed = installed;
+        this.name = 'AgentSpecError';
+    }
+}

package/dist/lib/crabbox/cli.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Typed wrapper over the external `crabbox` binary (github.com/openclaw/crabbox).
+ *
+ * crabbox leases ephemeral cloud boxes (Hetzner/DO/EC2/…), syncs the dirty
+ * checkout, and runs commands on them. We use it as the transport for
+ * `agents run --lease`: warm a box → run the agent on it via `crabbox run` →
+ * stop it. crabbox owns the SSH connection, so agents-cli never needs a direct
+ * ssh target (unlike the `agents hosts` model).
+ *
+ * crabbox talks to its cloud provider's API for list/status/warmup/stop, which
+ * needs a provider token (e.g. HCLOUD_TOKEN) in the environment. We inject it
+ * from a secrets bundle when one is configured (see `crabboxEnv`).
+ */
+/** A crabbox machine as reported by `crabbox list --json`. */
+export interface CrabboxBox {
+    /** Provider machine name, e.g. `crabbox-blue-hermit-1039689b`. */
+    name: string;
+    /** Provider run state, e.g. `running`. */
+    status: string;
+    /** Friendly slug used with `--id`, e.g. `blue-hermit`. */
+    slug: string;
+    /** Lease id, e.g. `cbx_9968746bb15c`. */
+    lease: string;
+    /** crabbox bootstrap state; `ready` once the box is usable. */
+    state: string;
+    /** Public IPv4, when the provider exposes one. */
+    ip?: string;
+    profile?: string;
+    class?: string;
+    /** True when running + bootstrap-complete. */
+    ready: boolean;
+}
+export interface CrabboxOptions {
+    /**
+     * Name of a secrets bundle whose env (e.g. `HCLOUD_TOKEN`) crabbox needs to
+     * reach its cloud provider. Resolved via agents-cli's own keychain-backed
+     * secrets. When unset, crabbox runs with the ambient environment / its own
+     * `crabbox login` credentials.
+     */
+    secretsBundle?: string;
+}
+/** Locate the crabbox binary, or throw an actionable error. */
+export declare function findCrabbox(): string;
+/** Build the child env for crabbox, injecting a secrets bundle when configured. */
+export declare function crabboxEnv(opts: CrabboxOptions): NodeJS.ProcessEnv;
+/** All crabbox machines the broker knows about. */
+export declare function crabboxList(opts?: CrabboxOptions): CrabboxBox[];
+/** Find one box by slug, or null. */
+export declare function crabboxFind(slug: string, opts?: CrabboxOptions): CrabboxBox | null;
+export interface WarmupOptions extends CrabboxOptions {
+    class?: string;
+    profile?: string;
+    /** Provision web code-server capability on the box. */
+    code?: boolean;
+    /** Cloud backend override (crabbox provider id, e.g. hetzner/aws/do). */
+    provider?: string;
+}
+/**
+ * Lease a box and block until it is ready. Returns the leased box.
+ *
+ * We diff `crabbox list` before/after so we reliably identify the box this call
+ * created even if warmup's stdout format changes — the new lease id is the one
+ * that wasn't present before.
+ */
+export declare function crabboxWarmup(opts?: WarmupOptions): CrabboxBox;
+/**
+ * Poll until the box reports ready, or throw after timeoutMs.
+ * `sleep` is injectable so tests don't wall-clock wait.
+ */
+export declare function crabboxWaitReady(slug: string, opts?: CrabboxOptions & {
+    timeoutMs?: number;
+    intervalMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<CrabboxBox>;
+export interface CrabboxRunOptions extends CrabboxOptions {
+    /** Called with each chunk of combined stdout/stderr as it streams. */
+    onData?: (chunk: string) => void;
+    /** Force a full remote resync before running. */
+    fullResync?: boolean;
+}
+/**
+ * Run `remoteCmd` on the leased box via `crabbox run` (crabbox syncs the dirty
+ * checkout and owns the SSH). Streams combined output; resolves with the remote
+ * exit code (or null if crabbox itself failed to dispatch).
+ */
+export declare function crabboxRun(slug: string, remoteCmd: string, opts?: CrabboxRunOptions): Promise<number | null>;
+/**
+ * Upload `script` to the box via `crabbox run --script-stdin` and run it.
+ *
+ * The script body travels over stdin and is written to a file on the box before
+ * execution — it never appears in argv / `ps` / shell history, which is why this
+ * is the transport for credential provisioning (the token contents live only in
+ * the uploaded script, then the file is removed by the script itself).
+ * Streams combined output; resolves with the remote exit code (null on dispatch failure).
+ */
+export declare function crabboxRunScript(slug: string, script: string, opts?: CrabboxRunOptions): Promise<number | null>;
+/** Release the lease / delete the box. Best-effort; never throws. */
+export declare function crabboxStop(slug: string, opts?: CrabboxOptions): boolean;