@skrr-ai/cli 0.1.24 → 0.1.26

package/dist/lib/dedicated-lease-command.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DedicatedLeaseCommand = exports.dedicatedWaitFlags = void 0;
+const core_1 = require("@oclif/core");
+const base_command_1 = require("../base-command");
+const dedicated_machines_1 = require("./dedicated-machines");
+const dedicated_terminal_1 = require("./dedicated-terminal");
+const harnesses_1 = require("./harnesses");
+const dedicated_wait_1 = require("./dedicated-wait");
+const hosted_machines_1 = require("./hosted-machines");
+/**
+ * Lifecycle calls answer 202 with the lease already in its transitional state.
+ * `--wait` watches it to the END of the operation, which for snapshot and grow
+ * is a field, not a state (see `dedicated-wait.ts`).
+ */
+exports.dedicatedWaitFlags = {
+    wait: core_1.Flags.boolean({
+        description: 'Wait until the operation has finished. Exits 124 if --timeout passes first; the operation keeps running.',
+    }),
+    timeout: core_1.Flags.string({
+        description: `How long --wait watches, such as 10m (default ${dedicated_wait_1.DEDICATED_WAIT_DEFAULT_TIMEOUT_MS / 60000}m)`,
+        dependsOn: ['wait'],
+    }),
+    interval: core_1.Flags.integer({
+        description: `Seconds between checks while waiting (default ${dedicated_wait_1.DEDICATED_WAIT_DEFAULT_INTERVAL_MS / 1000})`,
+        dependsOn: ['wait'],
+        min: 1,
+    }),
+};
+const TERMINAL_READY_STATES = new Set(['ready', 'active', 'idle']);
+class DedicatedLeaseCommand extends base_command_1.BaseCommand {
+    /**
+     * `--workspace` is a BaseCommand flag every command already accepts (it sets
+     * `X-Workspace-Id` for the whole invocation). It is also passed as the scope
+     * query, the way `create`, `exec` and `cp` always have, so the scope a request
+     * was made in is visible in the request itself.
+     */
+    scopeFrom(flags) {
+        return flags.workspace ? { workspaceId: flags.workspace } : {};
+    }
+    /**
+     * Open an interactive terminal on a lease's machine and run it to the end,
+     * exiting with the shell's own code.
+     *
+     * Every refusal is decided BEFORE the socket opens where it can be — a stopped
+     * machine, a daemon that is not connected, stdin that is not a terminal — so
+     * the caller gets a sentence that says what to do instead of a start that
+     * hangs and times out.
+     */
+    async openDedicatedTerminal(leaseId, flags, initialCommand) {
+        if (!process.stdin.isTTY || !process.stdout.isTTY) {
+            this.error('An interactive terminal needs a terminal on both ends. For scripts use `skrr machines dedicated exec`; an agent on the machine uses its terminal_* tools.', { exit: 2 });
+        }
+        const response = await this.callDedicated(() => (0, dedicated_machines_1.getDedicatedRuntime)(leaseId, this.scopeFrom(flags)));
+        const lease = response?.lease;
+        if (!lease)
+            this.error('Dedicated Runtime lease not found.', { exit: 1 });
+        const state = (0, dedicated_machines_1.dedicatedLeaseState)(lease);
+        if (!TERMINAL_READY_STATES.has(state)) {
+            this.error(state === 'stopped'
+                ? `${leaseId} is stopped. Start it first: \`${this.config.bin} machines dedicated start ${leaseId} --wait\`.`
+                : `${leaseId} is ${state}; a terminal opens once it is ready.`, { exit: 1 });
+        }
+        const listed = await this.callDedicated(() => (0, harnesses_1.listHarnesses)());
+        const harness = (0, dedicated_machines_1.dedicatedTerminalHarness)(lease, listed?.harnesses ?? []);
+        if (!harness?.daemonId) {
+            this.error(`${leaseId} is ${state}, but its daemon is not connected yet. Wait a moment, or run \`${this.config.bin} machines dedicated health-check ${leaseId}\`.`, { exit: 1 });
+        }
+        process.stderr.write(`Connected to ${(0, dedicated_machines_1.dedicatedLeaseDisplayName)(lease)} (${leaseId}) as skrr-workload. Ctrl-] closes the terminal.\n`);
+        let code;
+        try {
+            code = await (0, dedicated_terminal_1.runDedicatedTerminal)({
+                baseURL: this.cliConfig.baseURL,
+                token: this.resolvedCredential.token,
+                runtimeId: harness._id,
+                daemonId: harness.daemonId,
+                ...(flags.cwd ? { cwd: flags.cwd } : {}),
+                ...(initialCommand ? { initialCommand } : {}),
+                input: process.stdin,
+                output: process.stdout,
+                errorOutput: process.stderr,
+            });
+        }
+        catch (err) {
+            if (err instanceof dedicated_terminal_1.DedicatedTerminalError)
+                this.error(err.message, { exit: 1 });
+            throw err;
+        }
+        if (code !== 0)
+            this.exit(code);
+    }
+    /** Run an API call, turning a refusal into the server's own sentence. */
+    async callDedicated(fn) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            const message = (0, dedicated_machines_1.formatDedicatedRuntimeApiError)(err);
+            if (message)
+                this.error(message, { exit: 1, code: (0, dedicated_machines_1.dedicatedRuntimeApiErrorCode)(err) });
+            this.handleApiError(err);
+        }
+    }
+    /**
+     * Print the lease an action returned, or wait for its operation to finish
+     * first when `--wait` was passed.
+     */
+    async reportLeaseAction(response, flags, goal, verb) {
+        let lease = response?.lease;
+        const id = (0, dedicated_machines_1.dedicatedLeaseId)(lease);
+        if (flags.wait && goal && id) {
+            let timeoutMs;
+            try {
+                timeoutMs = (0, hosted_machines_1.parseDurationMs)(flags.timeout, '--timeout');
+            }
+            catch (err) {
+                this.error(err.message, { exit: 2 });
+            }
+            if (!flags.json)
+                this.log(`${verb} ${id}: ${(0, dedicated_machines_1.dedicatedLeaseState)(lease)}`);
+            try {
+                lease = await (0, dedicated_wait_1.waitForDedicatedLease)(id, goal, {
+                    ...this.scopeFrom(flags),
+                    initial: lease,
+                    intervalMs: flags.interval ? flags.interval * 1000 : undefined,
+                    timeoutMs,
+                    // Progress is about the wait, not the result: stderr, so a caller
+                    // reading `--json` from stdout gets exactly one document.
+                    onProgress: (progress) => process.stderr.write(`  … ${progress}\n`),
+                });
+            }
+            catch (err) {
+                if (err instanceof dedicated_wait_1.DedicatedWaitTimeoutError) {
+                    process.stderr.write(`${err.message}\n`);
+                    this.exit(dedicated_wait_1.DEDICATED_WAIT_TIMEOUT_EXIT);
+                }
+                if (err instanceof dedicated_wait_1.DedicatedWaitFailedError) {
+                    if (flags.json && err.lease)
+                        this.log(JSON.stringify({ lease: err.lease }, null, 2));
+                    this.error(err.message, { exit: 1 });
+                }
+                const message = (0, dedicated_machines_1.formatDedicatedRuntimeApiError)(err);
+                if (message)
+                    this.error(message, { exit: 1, code: (0, dedicated_machines_1.dedicatedRuntimeApiErrorCode)(err) });
+                this.handleApiError(err);
+            }
+        }
+        if (flags.json) {
+            this.log(JSON.stringify({ ...(response || {}), lease }, null, 2));
+            return;
+        }
+        this.log(`Dedicated Runtime ${id || 'unknown'} ${(0, dedicated_machines_1.dedicatedLeaseState)(lease)}.`);
+        if (!flags.wait && goal && id) {
+            this.log(`The operation continues in the background. Watch it with \`${this.config.bin} machines dedicated show ${id}\`, or pass --wait.`);
+        }
+    }
+}
+exports.DedicatedLeaseCommand = DedicatedLeaseCommand;

package/dist/lib/dedicated-machines.d.ts

@@ -1,9 +1,58 @@
-import { type HarnessLease } from './harnesses';
+import type { Harness, HarnessLease } from './harnesses';
 export type DedicatedLeaseAction = 'start' | 'stop' | 'restart' | 'snapshot' | 'health-check';
 export declare const DEDICATED_LEASE_ACTIONS: DedicatedLeaseAction[];
+export declare const DEDICATED_MACHINE_PRODUCT = "dedicated-machine";
 export interface DedicatedRuntimeScope {
     workspaceId?: string;
 }
+/**
+ * One Dedicated Runtime lease, as `toPublicMachineLeasePayload` emits it.
+ *
+ * Only fields the server actually sends belong here — the shared `HarnessLease`
+ * once declared three fields nobody ever sent, and optional properties made that
+ * compile while the columns stayed empty. Provider ids (instance, volume, AMI)
+ * are deliberately absent from the payload and therefore from this type.
+ */
+export interface DedicatedLease extends Omit<HarnessLease, 'storage'> {
+    supportReference?: string;
+    lifecycleCapabilities?: Record<string, boolean>;
+    executionCapabilities?: Record<string, boolean>;
+    resources?: {
+        cpu?: number;
+        memoryGb?: number;
+        storageGb?: number;
+        architecture?: string;
+        os?: string;
+        imagePreset?: string;
+        imageVersion?: string;
+        sizePreset?: string;
+        regionClass?: string;
+    };
+    daemon?: {
+        version?: string;
+        imageVersion?: string;
+        lastHeartbeatAt?: string;
+        registeredAt?: string;
+    };
+    storage?: {
+        retentionClass?: string;
+        backupProfile?: string;
+        lastBackupAt?: string;
+        lastRestoreTestAt?: string;
+        lastRestoreTestStatus?: string;
+        unpaidSince?: string;
+        deletionNoticeAt?: string;
+        deleteAfter?: string;
+    } & Record<string, unknown>;
+    recovery?: {
+        incidentHold?: {
+            status?: string;
+            reason?: string;
+            heldAt?: string;
+            closedAt?: string;
+        };
+    };
+}
 export interface CreateDedicatedRuntimeInput extends DedicatedRuntimeScope {
     requestId: string;
     displayName: string;
@@ -16,7 +65,7 @@ export interface CreateDedicatedRuntimeInput extends DedicatedRuntimeScope {
     repositoryRef?: string;
 }
 export interface DedicatedRuntimeResponse {
-    lease?: HarnessLease;
+    lease?: DedicatedLease;
 }
 /**
  * Flags in, request body out — and the point of it being a function is the
@@ -40,27 +89,214 @@ export declare function dedicatedRuntimeCreateInput(input: {
     storageGb?: number;
     retentionClass?: string;
     backupProfile?: string;
+    repositoryRef?: string;
     workspaceId?: string;
 }): CreateDedicatedRuntimeInput;
+/**
+ * The shapes the server's repository parser accepts: `owner/repo`,
+ * `github.com/owner/repo`, or an https URL to it, optionally ending in `.git`.
+ *
+ * This is a typo catcher, not the authority. The server re-parses the value and
+ * decides whether the owner's GitHub App installation covers it; checking the
+ * shape here only turns "create failed" into "that is not a repository" before a
+ * billable request is sent.
+ */
+export declare function isDedicatedRepositoryRef(value: string): boolean;
 export declare function createDedicatedRuntime(input: CreateDedicatedRuntimeInput): Promise<DedicatedRuntimeResponse>;
 export declare function listDedicatedRuntimes(options?: {
     limit?: number;
     state?: string;
-}): Promise<{
-    leases?: HarnessLease[];
+} & DedicatedRuntimeScope): Promise<{
+    leases?: DedicatedLease[];
 }>;
-export declare function getDedicatedRuntime(leaseId: string): Promise<DedicatedRuntimeResponse>;
-export declare function performDedicatedLeaseAction(leaseId: string, action: DedicatedLeaseAction): Promise<DedicatedRuntimeResponse>;
+export declare function getDedicatedRuntime(leaseId: string, scope?: DedicatedRuntimeScope): Promise<DedicatedRuntimeResponse>;
+export declare function performDedicatedLeaseAction(leaseId: string, action: DedicatedLeaseAction, scope?: DedicatedRuntimeScope): Promise<DedicatedRuntimeResponse>;
 export declare function growDedicatedRuntime(leaseId: string, storageGb: number, options?: {
     requestId?: string;
-}): Promise<DedicatedRuntimeResponse>;
+} & DedicatedRuntimeScope): Promise<DedicatedRuntimeResponse>;
+/**
+ * Change the monthly spending cap of one lease.
+ *
+ * The route accepts `spendingLimitCents` and nothing else: who pays is decided
+ * at create and there is no API that moves it. A cap below what the month has
+ * already spent (or is projected to) is refused rather than stopping the machine
+ * on the next reconciler pass.
+ */
+export declare function setDedicatedRuntimeSpendingLimit(leaseId: string, spendingLimitCents: number, scope?: DedicatedRuntimeScope): Promise<DedicatedRuntimeResponse>;
 export declare function closeDedicatedRuntimeIncidentHold(leaseId: string, options?: {
     requestId?: string;
-}): Promise<DedicatedRuntimeResponse>;
+} & DedicatedRuntimeScope): Promise<DedicatedRuntimeResponse>;
 export declare function destroyDedicatedRuntime(leaseId: string, options?: {
     retentionIntent?: 'retain' | 'purge';
-}): Promise<DedicatedRuntimeResponse>;
-export declare function dedicatedLeaseId(lease: HarnessLease | undefined | null): string;
-export declare function dedicatedLeaseState(lease: HarnessLease | undefined | null): string;
-export declare function dedicatedLeaseDisplayName(lease: HarnessLease | undefined | null): string;
+} & DedicatedRuntimeScope): Promise<DedicatedRuntimeResponse>;
+export interface DedicatedRuntimeExecInput {
+    command: string;
+    cwd?: string;
+    timeoutMs?: number;
+}
+export interface DedicatedRuntimeExecResult {
+    /** stdout and stderr, merged in the order the machine produced them, capped at 1 MB. */
+    stdout: string;
+    /** null when the command was killed at its deadline. */
+    exitCode: number | null;
+    timedOut: boolean;
+    truncated: boolean;
+    durationMs: number;
+}
+/** The server's ceiling for one exec; documented beside the route. */
+export declare const DEDICATED_EXEC_MAX_TIMEOUT_MS: number;
+/**
+ * Run one command on the machine as the workload user.
+ *
+ * Not idempotent and not retried: `apiFetch` gives each call a fresh
+ * idempotency key, which is the rule for an unfenced write — running the same
+ * command twice is two intents even when the text is identical.
+ */
+export declare function execDedicatedRuntime(leaseId: string, input: DedicatedRuntimeExecInput, scope?: DedicatedRuntimeScope): Promise<DedicatedRuntimeExecResult>;
+/** Mirrors the daemon's bounds (daemon/src/tools/file-transfer.ts). */
+export declare const DEDICATED_FILE_CHUNK_BYTES: number;
+export declare const DEDICATED_FILE_MAX_BYTES: number;
+export interface DedicatedFileChunk {
+    path: string;
+    size: number;
+    mtimeMs: number;
+    offset: number;
+    bytesRead: number;
+    dataBase64: string;
+    eof: boolean;
+}
+export interface DedicatedFileWriteResult {
+    path: string;
+    transferId: string;
+    staged: number;
+    committed: boolean;
+    aborted?: boolean;
+}
+export declare function readDedicatedRuntimeFileChunk(leaseId: string, input: {
+    path: string;
+    offset: number;
+    length: number;
+}, scope?: DedicatedRuntimeScope): Promise<DedicatedFileChunk>;
+export declare function writeDedicatedRuntimeFileChunk(leaseId: string, input: {
+    path: string;
+    transferId: string;
+    offset: number;
+    dataBase64?: string;
+    final?: boolean;
+    abort?: boolean;
+    totalSize?: number;
+}, scope?: DedicatedRuntimeScope): Promise<DedicatedFileWriteResult>;
+export type DedicatedCopyPlan = {
+    direction: 'upload';
+    localPath: string;
+    leaseId: string;
+    remotePath: string;
+} | {
+    direction: 'download';
+    leaseId: string;
+    remotePath: string;
+    localPath: string;
+};
+/**
+ * `cp <src> <dst>` where exactly one side is `<lease-id>:<path>`.
+ *
+ * The remote side is recognised by the lease id prefix rather than by "has a
+ * colon", so a Windows path (`C:\\build\\out.zip`) or a local file whose name
+ * contains a colon is never mistaken for a machine.
+ */
+export declare function parseDedicatedCopyEndpoints(source: string, destination: string): DedicatedCopyPlan;
+export declare function dedicatedLeaseId(lease: DedicatedLease | HarnessLease | undefined | null): string;
+export declare function dedicatedLeaseState(lease: DedicatedLease | HarnessLease | undefined | null): string;
+export declare function dedicatedLeaseDisplayName(lease: DedicatedLease | HarnessLease | undefined | null): string;
+/** `$12.34` — cents are what the API speaks; dollars are what a person reads. */
+export declare function formatUsdCents(cents: number | null | undefined): string;
+/** `this month $1.23 of $500.00 cap`, or why that sentence cannot be written. */
+export declare function dedicatedSpendSummary(lease: DedicatedLease): string;
+/**
+ * The human rendering of `machines dedicated show`, as lines.
+ *
+ * Pure so it can be pinned without a server. Every field is optional because a
+ * lease that is still `requested` has no resources, daemon or spend yet, and a
+ * missing value is omitted rather than printed as a column of dashes.
+ */
+export declare function describeDedicatedLease(lease: DedicatedLease, harnesses?: readonly Harness[]): string[];
+/**
+ * Every harness row a Dedicated Runtime lease's daemon registered, freshest
+ * first.
+ *
+ * A lease payload names no daemon (provider and daemon ids are deliberately
+ * absent), so the join goes the other way: each row a guest daemon registers
+ * carries `metadata.machineLeaseId` and `metadata.machineProduct`. One daemon
+ * writes one row PER ENGINE it announces (claude, codex, sky-code, or `oversky`
+ * when it announces none), all sharing the daemon id.
+ */
+export declare function dedicatedLeaseHarnesses(lease: Pick<DedicatedLease, 'id'>, harnesses: readonly Harness[]): Harness[];
+/**
+ * The row an interactive terminal opens on: online, local, with a daemon.
+ *
+ * Any engine row reaches the same shell — they share the daemon — so the
+ * freshest one wins. The terminal relay's own access check refuses a row that
+ * is not local or has no daemon, so offering one here would only move the
+ * refusal later.
+ */
+export declare function dedicatedTerminalHarness(lease: Pick<DedicatedLease, 'id'>, harnesses: readonly Harness[]): Harness | null;
+/**
+ * The harness row an agent should be attached to, for `attach`.
+ *
+ * Choosing a row also chooses the ENGINE the agent's turns run under, so an
+ * ambiguous choice is refused with the options named rather than guessed. A
+ * row need not be online to be attached — a stopped machine keeps its rows —
+ * but the error says so when it is not.
+ */
+export declare function selectDedicatedAttachHarness(lease: Pick<DedicatedLease, 'id'>, harnesses: readonly Harness[], engine?: string): {
+    harness: Harness;
+} | {
+    error: string;
+};
+interface CatalogSize {
+    id?: string;
+    label?: string;
+    vcpus?: number;
+    memoryGiB?: number;
+    accelerator?: string;
+}
+interface CatalogPriceLine {
+    label?: string;
+    display?: string;
+    amountCents?: number | null;
+    cadence?: string;
+}
+export interface DedicatedCatalog {
+    availability: string;
+    disabledReason?: string;
+    sizes: CatalogSize[];
+    regionClasses: string[];
+    storage?: {
+        minGb?: number;
+        defaultGb?: number;
+        maxGb?: number;
+    };
+    retentionClasses: string[];
+    backupProfiles: string[];
+    defaultMonthlySpendingLimitCents?: number | null;
+    maxUserMonthlySpendingLimitCents?: number | null;
+    priceLines: CatalogPriceLine[];
+    headline?: string;
+}
+/**
+ * The Dedicated Runtime row of `GET /api/machines/products`, reduced to what a
+ * caller needs to choose `create` flags.
+ *
+ * `--size-preset` has no client-side list of values on purpose — presets are
+ * gated by server flags — so this is where a caller learns which ones exist.
+ */
+export declare function dedicatedCatalogFromProducts(payload: unknown): DedicatedCatalog | null;
+/**
+ * The product refusal code the server sent (`DEDICATED_RUNTIME_NOT_ASSIGNABLE`,
+ * …), for `this.error(message, { code })`. Without it a `--json` caller got the
+ * generic `CLI_ERROR` and could only branch on prose (OSK-8685). Falls back to
+ * `HTTP_<status>`, the same code `handleApiError` uses for a body with none.
+ */
+export declare function dedicatedRuntimeApiErrorCode(err: unknown): string | undefined;
 export declare function formatDedicatedRuntimeApiError(err: unknown): string | null;
+export {};