@minato-aqukin/autodl-cli 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,948 @@
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from 'ssh2';
+import { Writable } from 'node:stream';
+
+interface StoredConfig {
+    token?: string;
+    baseUrl?: string;
+    lang?: "zh" | "en";
+    defaults?: {
+        gpu?: string;
+        image?: string;
+        regions?: string[];
+        ttl?: string;
+        minBalanceYuan?: number;
+    };
+}
+declare function readConfig(): StoredConfig;
+/** Write config with 0600 so a shared machine can't read the token. */
+declare function writeConfig(config: StoredConfig): void;
+declare function updateConfig(patch: Partial<StoredConfig>): StoredConfig;
+interface TokenResolution {
+    token: string;
+    source: "flag" | "env" | "config";
+}
+/**
+ * Token precedence: explicit flag > AUTODL_TOKEN > config file.
+ * Throws a AUTH_MISSING error (exit 3) with setup instructions when nothing is found.
+ */
+declare function resolveToken(explicit?: string): TokenResolution;
+
+/**
+ * Error taxonomy for AutoDL-cli.
+ *
+ * Every failure that reaches the CLI surface maps to exactly one exit code so that
+ * agents can branch on the result without parsing prose. The codes are part of the
+ * public contract — changing one is a breaking change.
+ */
+declare const ExitCode: {
+    readonly OK: 0;
+    readonly GENERIC: 1;
+    readonly USAGE: 2;
+    readonly AUTH: 3;
+    readonly NOT_FOUND: 4;
+    readonly BUDGET: 5;
+    readonly NO_STOCK: 6;
+    readonly TIMEOUT: 7;
+    readonly SSH: 8;
+};
+type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];
+/** Machine-readable error codes surfaced in `--json` output. */
+type ErrorCode = "GENERIC" | "USAGE" | "AUTH_MISSING" | "AUTH_INVALID" | "NOT_FOUND" | "INSUFFICIENT_BALANCE" | "GUARD_BLOCKED" | "NO_STOCK" | "TIMEOUT" | "SSH_FAILED" | "API_ERROR" | "NETWORK";
+interface AutoDLErrorOptions {
+    code?: ErrorCode;
+    exitCode?: ExitCode;
+    /** Actionable next step shown to humans and handed to agents verbatim. */
+    hint?: string;
+    /** AutoDL's own `request_id`, invaluable when asking support about a failure. */
+    requestId?: string;
+    cause?: unknown;
+    details?: Record<string, unknown>;
+}
+declare class AutoDLError extends Error {
+    readonly code: ErrorCode;
+    readonly exitCode: ExitCode;
+    readonly hint?: string;
+    readonly requestId?: string;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, options?: AutoDLErrorOptions);
+    toJSON(): {
+        code: ErrorCode;
+        message: string;
+        hint?: string;
+        requestId?: string;
+    };
+}
+declare class AuthError extends AutoDLError {
+    constructor(message: string, options?: AutoDLErrorOptions);
+}
+declare class NotFoundError extends AutoDLError {
+    constructor(message: string, options?: AutoDLErrorOptions);
+}
+declare class UsageError extends AutoDLError {
+    constructor(message: string, options?: AutoDLErrorOptions);
+}
+declare class BudgetError extends AutoDLError {
+    constructor(message: string, options?: AutoDLErrorOptions);
+}
+declare class NoStockError extends AutoDLError {
+    constructor(message: string, options?: AutoDLErrorOptions);
+}
+declare class TimeoutError extends AutoDLError {
+    constructor(message: string, options?: AutoDLErrorOptions);
+}
+declare class SSHError extends AutoDLError {
+    constructor(message: string, options?: AutoDLErrorOptions);
+}
+/** Coerce anything thrown into an AutoDLError so the CLI always has an exit code. */
+declare function toAutoDLError(err: unknown): AutoDLError;
+
+declare const DEFAULT_BASE_URL = "https://api.autodl.com";
+interface ClientOptions {
+    token: string;
+    baseUrl?: string;
+    /** Per-request timeout in ms. */
+    timeoutMs?: number;
+    /** Retry attempts for transient failures (network, 429, 5xx). */
+    maxRetries?: number;
+    /** Base delay for exponential backoff. Lowered in tests to keep the suite fast. */
+    retryBaseDelayMs?: number;
+    /** Called with sanitised request/response summaries when --verbose is on. */
+    onDebug?: (message: string) => void;
+    fetchImpl?: typeof fetch;
+}
+interface RequestOptions {
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    path: string;
+    body?: Record<string, unknown>;
+    /** Override the retry budget for a single call (e.g. 0 for non-idempotent creates). */
+    maxRetries?: number;
+    timeoutMs?: number;
+}
+/** Never let a token reach a log line intact. */
+declare function redactToken(token: string): string;
+declare class AutoDLClient {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly retryBaseDelayMs;
+    private readonly onDebug;
+    private readonly fetchImpl;
+    constructor(options: ClientOptions);
+    get maskedToken(): string;
+    get<T>(path: string, body?: Record<string, unknown>, extra?: Partial<RequestOptions>): Promise<T>;
+    post<T>(path: string, body?: Record<string, unknown>, extra?: Partial<RequestOptions>): Promise<T>;
+    put<T>(path: string, body?: Record<string, unknown>, extra?: Partial<RequestOptions>): Promise<T>;
+    delete<T>(path: string, body?: Record<string, unknown>, extra?: Partial<RequestOptions>): Promise<T>;
+    request<T>(options: RequestOptions): Promise<T>;
+    private debug;
+    private attempt;
+    private fetchJson;
+    /** GET with a JSON body — legal HTTP/1.1, but fetch refuses, so drop to node:https. */
+    private rawGetWithBody;
+    private readEnvelope;
+}
+
+/**
+ * Minimal message catalogue. AutoDL's user base is overwhelmingly Chinese-speaking,
+ * so zh is the default; `--lang en` / `AUTODL_LANG=en` switches.
+ */
+type Lang = "zh" | "en";
+
+interface GlobalOptions {
+    token?: string;
+    baseUrl?: string;
+    json?: boolean;
+    color?: boolean;
+    verbose?: boolean;
+    lang?: string;
+    /**
+     * Whether to run the opportunistic TTL sweep. Commander's `--no-sweep` sets this to
+     * `false` (it does NOT produce a `noSweep` key), so the check below tests for an
+     * explicit `false` rather than for truthiness of a negated name.
+     */
+    sweep?: boolean;
+}
+interface Context {
+    client: AutoDLClient;
+    lang: Lang;
+}
+/**
+ * Build the client every command shares.
+ *
+ * Kept separate from the commander wiring so the MCP server can construct an identical
+ * context — the two entry points must never drift in how they resolve tokens, honour
+ * env vars, or apply guards.
+ */
+declare function createContext(options?: GlobalOptions): Context;
+
+/**
+ * Static reference data.
+ *
+ * AutoDL's open API exposes no catalogue or stock endpoint for Pro instances, so the
+ * GPU specs, region codes and public base images have to be baked in. They can drift
+ * when the platform changes — `autodl gpus` / `regions` / `images --base` print this
+ * table, and the README asks users to open an issue when something is stale.
+ *
+ * Sources: https://www.autodl.com/docs/instance_pro_api/ and /docs/esd_api_doc/
+ * Last verified: 2026-08.
+ */
+interface GpuSpec {
+    /** Value for `gpu_spec_uuid` in the create payload. */
+    id: string;
+    /** Name as shown in the AutoDL console. */
+    displayName: string;
+    /** AutoDL's own tiering: 通用型 vs 性能型. */
+    tier: "general" | "performance";
+    vramGb: number;
+    /** Convenience aliases so `--gpu 4090` resolves without the exact spec id. */
+    aliases: string[];
+    /**
+     * The name this GPU goes by in the stock endpoint, which uses a different naming
+     * scheme from `gpu_spec_uuid`. Verified against live data: westDC3 returns both
+     * `vGPU-48GB` and `vGPU-48GB-350W`, matching the `v-48g` / `v-48g-350w` split
+     * exactly, which is what makes this mapping safe to hardcode.
+     */
+    stockName: string;
+}
+declare const GPU_SPECS: readonly GpuSpec[];
+/**
+ * A region in the `data_center_list` / `gpu_stock` namespace.
+ *
+ * AutoDL uses a *different* namespace in instance responses — an instance in 北京B区
+ * reports `region_sign: "bj-B2"`, not `beijingDC2`. Never feed an instance's reported
+ * region back into these APIs; see `assertStockRegion`.
+ *
+ * Names verified against the official elastic-deployment API docs, 2026-08.
+ */
+interface Region {
+    /** Value for `data_center_list` entries. */
+    id: string;
+    displayName: string;
+    aliases: string[];
+    /**
+     * Whether Pro instance creation accepts this region in `data_center_list`.
+     *
+     * Only two do. Every other region is elastic-deployment only and makes
+     * `instance/pro/create` fail with `RequestParameterIsWrong`. Verified empirically
+     * against the live API on 2026-08-23 by probing all eleven.
+     */
+    proCreate: boolean;
+}
+declare const REGIONS: readonly Region[];
+interface BaseImage {
+    uuid: string;
+    framework: string;
+    /** Full image tag as AutoDL names it. */
+    tag: string;
+    cuda: string;
+    python: string;
+}
+declare const BASE_IMAGES: readonly BaseImage[];
+/** The image `autodl create` picks when the user doesn't name one. */
+declare const DEFAULT_BASE_IMAGE = "base-image-l2t43iu6uk";
+/** Resolve a user-supplied GPU string to a spec id, accepting display names and aliases. */
+declare function resolveGpuSpec(input: string): GpuSpec | undefined;
+declare function resolveRegion(input: string): Region | undefined;
+/**
+ * Guard the stock endpoint against a region id from the wrong namespace.
+ *
+ * `gpu_stock` answers an unknown region with `{"code":"Success","data":[]}` — a typo and
+ * a genuinely sold-out region are indistinguishable in the response. Without this check
+ * `--region bj-B2` would silently report "no stock" forever.
+ */
+declare function assertStockRegion(input: string): Region;
+declare function findBaseImage(input: string): BaseImage | undefined;
+/** `11.8` / `118` / `11` -> the integer form AutoDL's `cuda_v_from` expects. */
+declare function parseCudaVersion(input: string | number): number;
+/** Inverse of parseCudaVersion, for display: `118` -> `11.8`. */
+declare function formatCudaVersion(value: number): string;
+
+/**
+ * Parse a human duration like `30m`, `2h`, `1.5h`, `90` (bare = minutes).
+ * Used by `--ttl`, `--timeout` and the idle guard.
+ */
+declare function parseDuration(input: string, { bareUnit }?: {
+    bareUnit?: string | undefined;
+}): number;
+/** Seconds -> compact human string, e.g. `2h30m`. */
+declare function formatDuration(seconds: number): string;
+
+declare const instanceStatusSchema: z.ZodEnum<["creating", "starting", "running", "shutting_down", "shutdown", "releasing", "released", "failed"]>;
+type InstanceStatus = z.infer<typeof instanceStatusSchema> | (string & {});
+/** Public, stable shape returned by `autodl ls --json`. Breaking changes need a major. */
+interface Instance {
+    uuid: string;
+    name: string | null;
+    status: InstanceStatus;
+    subStatus: string | null;
+    machineId: string | null;
+    regionSign: string | null;
+    regionName: string | null;
+    chargeType: string | null;
+    startMode: string | null;
+    gpuSpec: string | null;
+    gpuNum: number;
+    createdAt: string | null;
+    startedAt: string | null;
+    stoppedAt: string | null;
+    expiredAt: string | null;
+    timedShutdownAt: string | null;
+}
+declare function normalizeInstance(raw: unknown): Instance;
+interface ServiceEndpoint {
+    port: number;
+    domain: string;
+    protocol: string | null;
+}
+/** Public shape for `autodl info --json`. `rootPassword` is sensitive — see redaction. */
+interface InstanceSnapshot {
+    regionSign: string | null;
+    gpuAlias: string | null;
+    chipCorp: string | null;
+    cpuArch: string | null;
+    /** Pay-as-you-go rate in yuan per hour. */
+    priceYuanPerHour: number;
+    originalPriceYuanPerHour: number;
+    ssh: {
+        command: string | null;
+        host: string | null;
+        port: number | null;
+        user: "root";
+        password: string | null;
+    };
+    jupyter: {
+        token: string | null;
+        domain: string | null;
+    };
+    services: ServiceEndpoint[];
+    disk: {
+        systemInitBytes: number;
+        systemExpandBytes: number;
+    };
+    usage: {
+        cpuPercent: number | null;
+        memPercent: number | null;
+        memUsedBytes: number | null;
+        memLimitBytes: number | null;
+        rootFsUsedBytes: number | null;
+        rootFsTotalBytes: number | null;
+        dataDiskUsedBytes: number | null;
+        dataDiskTotalBytes: number | null;
+    };
+}
+declare function normalizeSnapshot(raw: unknown): InstanceSnapshot;
+interface Balance {
+    /** Spendable balance in yuan. */
+    balanceYuan: number;
+    /** Lifetime spend in yuan. */
+    accumulatedYuan: number;
+    /** Voucher balance in yuan. */
+    voucherYuan: number;
+}
+declare function normalizeBalance(raw: unknown): Balance;
+interface PrivateImage {
+    imageUuid: string;
+    name: string;
+    status: string | null;
+    sizeBytes: number;
+    createdAt: string | null;
+}
+interface Pagination {
+    pageIndex: number;
+    pageSize: number;
+    maxPage: number;
+    total: number;
+}
+/** Strip secrets before printing a snapshot to a shared surface (logs, MCP previews). */
+declare function redactSnapshot(snapshot: InstanceSnapshot): InstanceSnapshot;
+
+/** Wallet balance, lifetime spend and voucher balance — the only account endpoint AutoDL exposes. */
+declare function getBalance(client: AutoDLClient): Promise<Balance>;
+/**
+ * Mount or unmount the exclusive NFS / file storage for a region.
+ * `mountable` is AutoDL's own 1 / -1 convention.
+ */
+declare function setNfsMount(client: AutoDLClient, dataCenter: string, mount: boolean): Promise<void>;
+
+/** Snapshot a running instance into a reusable private image. */
+declare function saveImage(client: AutoDLClient, instanceUuid: string, imageName: string): Promise<string>;
+declare function listPrivateImages(client: AutoDLClient, options?: {
+    pageIndex?: number;
+    pageSize?: number;
+}): Promise<{
+    images: PrivateImage[];
+    pagination: Pagination;
+}>;
+
+interface CreateInstanceInput {
+    /** `gpu_spec_uuid`, e.g. `pro6000-p`. Resolve aliases before calling. */
+    gpuSpec: string;
+    /** 1-4, enforced by AutoDL. */
+    gpuNum: number;
+    imageUuid: string;
+    /** Integer CUDA floor, e.g. 118 for CUDA >= 11.8. */
+    cudaFrom: number;
+    /** 0-500 GB of extra system disk, fixed at creation time. */
+    expandSystemDiskGb?: number;
+    /** Region preference list; AutoDL picks the first with capacity. */
+    regions?: string[];
+    name?: string;
+    /** Shell command run after boot. Also how the TTL guard arms itself. */
+    startCommand?: string;
+}
+/** Create a pay-as-you-go Pro instance. Returns the new instance uuid. */
+declare function createInstance(client: AutoDLClient, input: CreateInstanceInput): Promise<string>;
+interface ListInstancesOptions {
+    pageIndex?: number;
+    pageSize?: number;
+}
+declare function listInstancesPage(client: AutoDLClient, options?: ListInstancesOptions): Promise<{
+    instances: Instance[];
+    pagination: Pagination;
+}>;
+/** Walk every page so callers never have to think about pagination. */
+declare function listAllInstances(client: AutoDLClient): Promise<Instance[]>;
+declare function getInstanceStatus(client: AutoDLClient, uuid: string): Promise<string>;
+declare function getInstanceSnapshot(client: AutoDLClient, uuid: string): Promise<InstanceSnapshot>;
+/** Find one instance in the list endpoint (there is no per-instance GET). */
+declare function findInstance(client: AutoDLClient, uuid: string): Promise<Instance>;
+interface PowerOnOptions {
+    /**
+     * `payload` is fixed to "gpu" because nothing else works — for now.
+     *
+     * AutoDL documents it as "gpu：有卡开机, 暂不支持API以无卡模式开机": *not yet*
+     * supported, not never. Probed live 2026-08-24 on a shut-down instance: "cpu",
+     * "no_gpu", "nogpu", "cpu_only", "cpu-only" and "none" each returned
+     * `不支持的启动模式`, and an empty string was accepted but came back with
+     * `start_mode: "gpu"` — a default, not a CPU mode.
+     *
+     * When AutoDL enables it, the change is small: add `mode?: "gpu" | "<their value>"`
+     * to PowerOnOptions, thread it into the payload below, and surface it as
+     * `autodl start --no-gpu` plus a `mode` field on the MCP power-on tool.
+     *
+     * Re-checking costs nothing: from any already shut-down instance, a power_on with a
+     * rejected payload is refused without booting anything.
+     */
+    startCommand?: string;
+}
+declare function powerOnInstance(client: AutoDLClient, uuid: string, options?: PowerOnOptions): Promise<void>;
+declare function powerOffInstance(client: AutoDLClient, uuid: string): Promise<void>;
+/** AutoDL requires the instance to be shut down first; this is irreversible. */
+declare function releaseInstance(client: AutoDLClient, uuid: string): Promise<void>;
+
+/**
+ * GPU stock, the only capacity-visibility endpoint AutoDL exposes.
+ *
+ * Officially titled "获取弹性部署GPU库存" — it belongs to the elastic-deployment product
+ * line, not to Pro container instances. The returned names include Pro-only variants
+ * (`vGPU-48GB-350W`, `RTX PRO 6000`, `H800`), which strongly suggests a shared physical
+ * pool, but AutoDL makes no guarantee that "ESD has stock" means "creating a Pro
+ * instance will succeed". Callers must treat this as advisory ranking, never as a gate.
+ */
+interface GpuStockEntry {
+    /** Stock-namespace GPU name, e.g. `RTX PRO 6000`. See `GpuSpec.stockName`. */
+    gpuName: string;
+    idle: number;
+    total: number;
+    /** Present in live responses though absent from the published docs. */
+    chipCorp: string | null;
+    cpuArch: string | null;
+}
+interface StockQuery {
+    /** Region id in the `data_center_list` namespace, e.g. `beijingDC2`. */
+    regionSign: string;
+    /** Restrict to these stock-namespace GPU names. */
+    gpuNames?: string[];
+    cudaFrom?: number;
+    cudaTo?: number;
+    cpuNumFrom?: number;
+    cpuNumTo?: number;
+    memorySizeFrom?: number;
+    memorySizeTo?: number;
+    /** Price bounds in yuan per hour; converted to AutoDL's milliyuan on the way out. */
+    priceFromYuan?: number;
+    priceToYuan?: number;
+}
+declare function getRegionGpuStock(client: AutoDLClient, query: StockQuery): Promise<GpuStockEntry[]>;
+
+/**
+ * AutoDL expresses every monetary value in "milliyuan" (毫元) — integer thousandths
+ * of a CNY. We normalise to plain yuan at the edge of `core/` so nothing above this
+ * layer ever has to remember the factor.
+ */
+/** Milliyuan integer -> yuan number, rounded to fen (2dp) to avoid float noise. */
+declare function milliToYuan(milli: number | null | undefined): number;
+/** Yuan -> milliyuan integer, for request payloads that take price bounds. */
+declare function yuanToMilli(yuan: number): number;
+/** Human display, e.g. `¥1.97`. */
+declare function formatYuan(yuan: number): string;
+/** Human display for a per-hour rate, e.g. `¥1.97/时`. */
+declare function formatRate(yuanPerHour: number, unit?: string): string;
+/**
+ * Estimate cost for a duration at a per-hour rate. AutoDL bills per second with a
+ * ¥0.01 floor, so this mirrors that rather than rounding up to whole hours.
+ */
+declare function estimateCost(yuanPerHour: number, seconds: number): number;
+
+/**
+ * Parsing and safe assembly of code-hosting URLs.
+ *
+ * The token handling here is the security-sensitive part: a credential embedded in a
+ * clone URL must never reach a log line, an error message, `--json` output, or the
+ * remote's stored git config. Everything that builds a URL with a token also provides
+ * a redacted twin for display.
+ */
+interface ParsedRepo {
+    /** Host as given, e.g. `github.com`. */
+    host: string;
+    /** `owner/name` path, without a trailing `.git`. */
+    path: string;
+    /** Last path segment — the default directory name. */
+    name: string;
+    /** Normalised https clone URL, never containing credentials. */
+    cloneUrl: string;
+    /** True when AutoDL's academic proxy covers this host. */
+    needsAcceleration: boolean;
+}
+/**
+ * Accept the forms people actually paste: https URLs, `git@host:owner/repo.git`,
+ * and bare `owner/repo` (assumed GitHub, matching how most tools behave).
+ */
+declare function parseRepo(input: string): ParsedRepo;
+/**
+ * Clone URL with a token embedded, plus the redacted form to show instead.
+ *
+ * Callers must use `display` for every user-visible surface — the raw URL is only ever
+ * allowed inside the command string sent over SSH.
+ */
+declare function withCredentials(repo: ParsedRepo, token?: string): {
+    url: string;
+    display: string;
+};
+/** Strip any embedded credential from arbitrary text before it is displayed or stored. */
+declare function redactCredentials(text: string): string;
+/** Resolve a git token from the flag, then the usual environment variables. */
+declare function resolveGitToken(explicit?: string): string | undefined;
+
+/**
+ * Turn raw per-region stock into a ranked list of places to try.
+ *
+ * The stock endpoint belongs to elastic deployment, so a positive number is evidence
+ * rather than a promise — measured 2026-08-23, it reported 140 idle RTX 4090D in a
+ * region where Pro creation answered "暂无库存". Everything here is ordering advice
+ * only; nothing refuses to create because a region looks empty.
+ */
+interface RegionStock {
+    regionId: string;
+    regionName: string;
+    idle: number;
+    total: number;
+}
+interface StockSnapshot {
+    regionId: string;
+    regionName: string;
+    entries: GpuStockEntry[];
+}
+/** Query several regions at once; one region failing must not sink the rest. */
+declare function getStockByRegion(client: AutoDLClient, options?: {
+    regions?: string[];
+    gpuNames?: string[];
+}): Promise<{
+    snapshots: StockSnapshot[];
+    failures: {
+        regionId: string;
+        reason: string;
+    }[];
+}>;
+/**
+ * Regions that currently have the given GPU free, best first.
+ *
+ * Returns regions with `idle === 0` too (at the end), so callers can tell "queried and
+ * everything is busy" apart from "the query failed" — those are different situations
+ * and only one of them warrants a warning.
+ */
+declare function findRegionsWithStock(client: AutoDLClient, spec: GpuSpec, options?: {
+    regions?: string[];
+}): Promise<{
+    ranked: RegionStock[];
+    failures: {
+        regionId: string;
+        reason: string;
+    }[];
+}>;
+/** Look up a spec by its stock-namespace name (inverse of `GpuSpec.stockName`). */
+declare function specForStockName(gpuName: string): GpuSpec | undefined;
+interface RegionChoice {
+    /** Value for `data_center_list`; empty means "let AutoDL schedule anywhere". */
+    regions: string[];
+    ranked: RegionStock[];
+    /** True when stock was consulted and every candidate region reported zero idle. */
+    allBusy: boolean;
+}
+/**
+ * Decide what to put in `data_center_list`.
+ *
+ * Deliberately does NOT narrow an unconstrained request. Two live findings drove this:
+ *
+ *  - Pro creation accepts only westDC3 and beijingDC2; the other nine regions are
+ *    elastic-deployment only and hard-fail with `RequestParameterIsWrong`.
+ *  - Stock numbers come from the elastic-deployment pool and do not track Pro
+ *    availability. Measured 2026-08-23: stock reported 140 idle RTX 4090D in westDC3
+ *    while Pro creation there answered "暂无库存" — and the same request with no region
+ *    constraint succeeded, landing in beijingDC2.
+ *
+ * So an empty list (let AutoDL schedule) beats any list we could infer. When the user
+ * does name regions we keep their choice, ordering by stock and warning if it looks
+ * empty — a weak signal, but the only one available.
+ */
+declare function chooseRegions(client: AutoDLClient, spec: GpuSpec, requested?: string[]): Promise<RegionChoice>;
+
+interface WaitOptions {
+    /** Give up after this many ms. */
+    timeoutMs?: number;
+    /** Gap between status polls. */
+    intervalMs?: number;
+    /** Progress callback, e.g. to drive a spinner. */
+    onPoll?: (status: string, elapsedMs: number) => void;
+    signal?: AbortSignal;
+}
+/**
+ * Poll `instance/pro/status` until it reaches one of `targets`.
+ *
+ * Used before every SSH attempt: AutoDL reassigns the SSH port and root password on
+ * each power cycle, and the snapshot is only trustworthy once the instance is running.
+ */
+declare function waitForStatus(client: AutoDLClient, uuid: string, targets: string[], options?: WaitOptions): Promise<string>;
+declare const waitForRunning: (client: AutoDLClient, uuid: string, options?: WaitOptions) => Promise<string>;
+declare const waitForShutdown: (client: AutoDLClient, uuid: string, options?: WaitOptions) => Promise<string>;
+
+declare function resolveMinBalance(explicit?: number): number;
+/**
+ * Refuse to create an instance when the wallet is nearly empty.
+ *
+ * AutoDL doesn't reclaim instances the moment the balance hits zero — it keeps them
+ * around to protect data — so a low balance turns into a stuck, unusable instance
+ * rather than a clean failure. Better to stop before renting.
+ */
+declare function assertBudget(client: AutoDLClient, minYuan?: number): Promise<number>;
+
+/**
+ * Idle detection.
+ *
+ * The TTL guard handles "this job should never run longer than N hours". This handles
+ * the other half: a job that finished (or crashed) an hour ago while the meter kept
+ * running. We sample GPU utilisation over SSH and power off after a sustained lull.
+ */
+interface IdleOptions {
+    /** Utilisation percentage at or below which a sample counts as idle. */
+    thresholdPercent?: number;
+    /** Consecutive idle samples required before shutting down. */
+    samples?: number;
+    /** Seconds between samples. */
+    intervalSeconds?: number;
+    /** Report but don't actually power off. */
+    dryRun?: boolean;
+    signal?: AbortSignal;
+    onSample?: (utilisation: number, consecutiveIdle: number) => void;
+}
+interface IdleResult {
+    stopped: boolean;
+    samplesTaken: number;
+    lastUtilisation: number | null;
+    reason: "idle" | "aborted" | "dry-run";
+}
+/** Average utilisation across all GPUs, or null when nvidia-smi gave us nothing usable. */
+declare function parseUtilisation(stdout: string): number | null;
+/**
+ * Watch an instance and power it off once the GPU has been quiet long enough.
+ * Blocks until it shuts the instance down or the signal aborts.
+ */
+declare function watchIdle(client: AutoDLClient, uuid: string, options?: IdleOptions): Promise<IdleResult>;
+
+/**
+ * Shell snippet that arms the in-instance timer.
+ *
+ * Deliberately quote-free: it is embedded in AutoDL's `start_command` field, and we
+ * can't see how that string is re-parsed on their side. A subshell with `&&` expresses
+ * "wait then shut down" without a single quote character.
+ */
+declare function buildTTLSnippet(seconds: number): string;
+/** Compose the boot command: arm the timer first, then run whatever the user asked for. */
+declare function composeStartCommand(ttlSeconds: number | undefined, userCommand: string | undefined): string | undefined;
+/**
+ * Arm (or re-arm) the timer on an already-running instance over SSH.
+ * Used by `autodl start --ttl`, where there is no create payload to piggyback on.
+ */
+declare function armTTLOverSSH(client: AutoDLClient, uuid: string, seconds: number): Promise<boolean>;
+/** Cancel a previously armed in-instance timer. */
+declare function disarmTTLOverSSH(client: AutoDLClient, uuid: string): Promise<boolean>;
+interface RecordTTLInput {
+    uuid: string;
+    name?: string;
+    ttlSeconds: number;
+    inInstanceTimer: boolean;
+}
+/** Add the instance to the local ledger so the sweep can catch it later. */
+declare function recordTTL(input: RecordTTLInput): void;
+interface SweepResult {
+    stopped: string[];
+    alreadyStopped: string[];
+    failed: {
+        uuid: string;
+        reason: string;
+    }[];
+}
+/**
+ * Power off any tracked instance past its TTL.
+ *
+ * Runs opportunistically before every command, so an agent that forgot to clean up
+ * gets caught the next time anything touches the CLI. Failures here are reported but
+ * never abort the command the user actually asked for.
+ */
+declare function sweepExpired(client: AutoDLClient): Promise<SweepResult>;
+
+declare function buildServer(context: Context): McpServer;
+/** Start the stdio MCP server. Blocks until the transport closes. */
+declare function startMcpServer(options?: {
+    token?: string;
+    baseUrl?: string;
+}): Promise<void>;
+
+interface SSHCredentials {
+    uuid: string;
+    host: string;
+    port: number;
+    user: "root";
+    password: string;
+}
+interface CredentialOptions {
+    /** Power the instance on (and wait) when it isn't running. */
+    autoStart?: boolean;
+    /** How long to wait for `running` when auto-starting. */
+    waitTimeoutMs?: number;
+    /** Gap between status polls while waiting. */
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Fetch live SSH credentials for an instance.
+ *
+ * AutoDL may reassign `ssh_port` and `root_password` on any power cycle — the instance
+ * can be rescheduled onto a different machine. It does not always happen (a real
+ * stop/start was observed keeping both identical), which is exactly why caching is
+ * unsafe: the stale value works often enough to hide the bug. Nothing in this codebase
+ * may cache credentials across calls — always come back through here.
+ */
+declare function getCredentials(client: AutoDLClient, uuid: string, options?: CredentialOptions): Promise<SSHCredentials>;
+interface ConnectOptions extends CredentialOptions {
+    /** Socket-level connect timeout. */
+    connectTimeoutMs?: number;
+    keepaliveIntervalMs?: number;
+    /** Connection attempts before giving up. Each one re-reads the credentials. */
+    connectAttempts?: number;
+}
+/**
+ * The single funnel for every SSH operation.
+ *
+ * Each attempt re-reads the credentials, which covers both ways a connection can fail:
+ * the port may have been reassigned since the snapshot was taken, and sshd may simply
+ * not be up yet on a freshly booted instance. The first is fixed by the refresh, the
+ * second only by waiting — so attempts are spaced out rather than fired back to back.
+ */
+declare function withSSH<T>(client: AutoDLClient, uuid: string, fn: (conn: Client, creds: SSHCredentials) => Promise<T>, options?: ConnectOptions): Promise<T>;
+
+/**
+ * Interactive login hands off to the system `ssh` binary rather than ssh2: the user
+ * gets their own terminal handling, agent forwarding, ProxyJump, ~/.ssh/config, etc.
+ */
+declare function connectInteractive(client: AutoDLClient, uuid: string, options?: CredentialOptions & {
+    extraArgs?: string[];
+}): Promise<number>;
+/** The connection details, for printing or for feeding another tool. */
+declare function formatSSHCommand(creds: SSHCredentials): string;
+
+interface ExecResult {
+    /** Remote process exit code. `null` when the process was killed by a signal. */
+    exitCode: number | null;
+    signal: string | null;
+    stdout: string;
+    stderr: string;
+}
+interface ExecOptions extends ConnectOptions {
+    /** Mirror remote output to these streams as it arrives. */
+    stdout?: Writable;
+    stderr?: Writable;
+    /** Capture output into the result. Off for huge jobs to bound memory. */
+    capture?: boolean;
+    /** Kill the remote command after this many ms. */
+    timeoutMs?: number;
+    /** Working directory on the remote host. */
+    cwd?: string;
+    /** Extra environment variables exported before the command runs. */
+    env?: Record<string, string>;
+    /** Request a PTY — needed for programs that check isatty (e.g. progress bars). */
+    pty?: boolean;
+    /**
+     * Run through a login shell (default true).
+     *
+     * AutoDL images put python/pip/conda in `/root/miniconda3/bin`, which reaches PATH
+     * only via the login profile. A non-interactive `ssh host "cmd"` gets a bare PATH —
+     * `.bashrc` bails out at the standard "If not running interactively, don't do
+     * anything" guard — so `pip install` there fails with exit 127. A login shell matches
+     * what the user sees when they `autodl ssh` in by hand.
+     */
+    loginShell?: boolean;
+}
+/** Run one command over an already-open connection. */
+declare function execOnConnection(conn: Client, command: string, options?: ExecOptions): Promise<ExecResult>;
+/** Connect (refreshing credentials as needed) and run a single command. */
+declare function execCommand(client: AutoDLClient, uuid: string, command: string, options?: ExecOptions): Promise<ExecResult>;
+
+interface TransferProgress {
+    file: string;
+    index: number;
+    total: number;
+    bytes: number;
+}
+interface TransferOptions extends ConnectOptions {
+    /** Glob-ish ignore patterns; `.autodlignore` then `.gitignore` are used by default. */
+    ignore?: string[];
+    onProgress?: (progress: TransferProgress) => void;
+    /** Skip reading ignore files from disk (used by tests and explicit single-file copies). */
+    noIgnoreFiles?: boolean;
+}
+interface TransferSummary {
+    files: number;
+    bytes: number;
+}
+/** Upload a local file or directory to the instance. */
+declare function push(client: AutoDLClient, uuid: string, localPath: string, remotePath: string, options?: TransferOptions): Promise<TransferSummary>;
+/** Download a remote file or directory from the instance. */
+declare function pull(client: AutoDLClient, uuid: string, remotePath: string, localPath: string, options?: TransferOptions): Promise<TransferSummary>;
+
+declare const VERSION: string;
+
+/**
+ * Deploy a hosted git project onto an AutoDL instance.
+ *
+ * The defining difference from `runWorkflow`: this **stops** the instance at the end
+ * rather than releasing it. A stopped container instance keeps its disks, so the next
+ * deploy can power the same box back on and `git pull` instead of rebuilding from
+ * scratch. Releasing would throw all of that away.
+ */
+interface DeployOptions {
+    repo: string;
+    branch?: string;
+    /** Reuse an existing instance instead of creating one. */
+    instanceUuid?: string;
+    gpu?: string;
+    gpuNum?: number;
+    image?: string;
+    regions?: string[];
+    diskGb?: number;
+    name?: string;
+    /** Remote checkout directory. Defaults to /root/autodl-tmp/<repo>. */
+    dir?: string;
+    /** Overrides dependency auto-detection. */
+    setup?: string;
+    noSetup?: boolean;
+    /** Command that runs the project once dependencies are in place. */
+    start?: string;
+    /** Background the start command and return immediately. */
+    detach?: boolean;
+    gitToken?: string;
+    /** Disable `source /etc/network_turbo` even for accelerated hosts. */
+    noAcceleration?: boolean;
+    ttlSeconds: number;
+    onFinish?: "poweroff" | "release" | "keep";
+    commandTimeoutMs?: number;
+    minBalanceYuan?: number;
+    stockCheck?: boolean;
+    env?: Record<string, string>;
+    signal?: AbortSignal;
+}
+interface DeployResult {
+    instanceUuid: string;
+    /** True when this call created the instance rather than reusing one. */
+    created: boolean;
+    repo: {
+        host: string;
+        path: string;
+        name: string;
+        branch: string | null;
+    };
+    dir: string;
+    setupCommand: string | null;
+    startCommand: string | null;
+    detached: boolean;
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    /** How to reach a detached service. */
+    access: {
+        publicUrls: string[];
+        tunnelHint: string | null;
+        logHint: string | null;
+    };
+    finalAction: "poweroff" | "release" | "keep";
+    durationMs: number;
+}
+declare function deployWorkflow(client: AutoDLClient, options: DeployOptions): Promise<DeployResult>;
+
+interface RunOptions {
+    command: string;
+    gpu: string;
+    gpuNum?: number;
+    image?: string;
+    cudaFrom?: string | number;
+    regions?: string[];
+    diskGb?: number;
+    name?: string;
+    ttlSeconds: number;
+    /** Local directory uploaded before the command runs. */
+    sync?: string;
+    /** Remote working directory; also the sync destination. */
+    workdir?: string;
+    /** Remote path copied back after the command finishes. */
+    pullFrom?: string;
+    /** Local destination for `pullFrom`. */
+    pullTo?: string;
+    /** What to do with the instance afterwards. */
+    onFinish?: "poweroff" | "release" | "keep";
+    /** Kill the remote command after this many ms. */
+    commandTimeoutMs?: number;
+    minBalanceYuan?: number;
+    env?: Record<string, string>;
+    /** Set false to skip the pre-create stock lookup. */
+    stockCheck?: boolean;
+    signal?: AbortSignal;
+}
+interface RunResult {
+    instanceUuid: string;
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    uploaded: {
+        files: number;
+        bytes: number;
+    } | null;
+    downloaded: {
+        files: number;
+        bytes: number;
+    } | null;
+    finalAction: "poweroff" | "release" | "keep";
+    durationMs: number;
+}
+/**
+ * The single verb an agent reaches for: rent a box, put code on it, run something,
+ * bring the results back, and give the box back.
+ *
+ * Every exit path — success, remote failure, Ctrl-C, a thrown error — routes through
+ * the same cleanup, because the one unacceptable outcome is leaving a GPU powered on.
+ */
+declare function runWorkflow(client: AutoDLClient, options: RunOptions): Promise<RunResult>;
+
+export { AuthError, AutoDLClient, AutoDLError, BASE_IMAGES, type Balance, type BaseImage, BudgetError, type ClientOptions, type Context, type CreateInstanceInput, DEFAULT_BASE_IMAGE, DEFAULT_BASE_URL, type DeployOptions, type DeployResult, type ErrorCode, type ExecOptions, type ExecResult, ExitCode, GPU_SPECS, type GlobalOptions, type GpuSpec, type GpuStockEntry, type IdleOptions, type IdleResult, type Instance, type InstanceSnapshot, type InstanceStatus, NoStockError, NotFoundError, type Pagination, type ParsedRepo, type PrivateImage, REGIONS, type Region, type RegionChoice, type RegionStock, type RunOptions, type RunResult, type SSHCredentials, SSHError, type ServiceEndpoint, type StockQuery, type StockSnapshot, type StoredConfig, TimeoutError, type TransferOptions, type TransferSummary, UsageError, VERSION, type WaitOptions, armTTLOverSSH, assertBudget, assertStockRegion, buildServer, buildTTLSnippet, chooseRegions, composeStartCommand, connectInteractive, createContext, createInstance, deployWorkflow, disarmTTLOverSSH, estimateCost, execCommand, execOnConnection, findBaseImage, findInstance, findRegionsWithStock, formatCudaVersion, formatDuration, formatRate, formatSSHCommand, formatYuan, getBalance, getCredentials, getInstanceSnapshot, getInstanceStatus, getRegionGpuStock, getStockByRegion, listAllInstances, listInstancesPage, listPrivateImages, milliToYuan, normalizeBalance, normalizeInstance, normalizeSnapshot, parseCudaVersion, parseDuration, parseRepo, parseUtilisation, powerOffInstance, powerOnInstance, pull, push, readConfig, recordTTL, redactCredentials, redactSnapshot, redactToken, releaseInstance, resolveGitToken, resolveGpuSpec, resolveMinBalance, resolveRegion, resolveToken, runWorkflow, saveImage, setNfsMount, specForStockName, startMcpServer, sweepExpired, toAutoDLError, updateConfig, waitForRunning, waitForShutdown, waitForStatus, watchIdle, withCredentials, withSSH, writeConfig, yuanToMilli };