@skrr-ai/cli 0.1.25 → 0.1.27

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

@@ -1,9 +1,74 @@
-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;
+        /** A workspace deletion and its recovery window (D12). */
+        deletion?: DedicatedLeaseDeletion;
+    } & Record<string, unknown>;
+    recovery?: {
+        incidentHold?: {
+            status?: string;
+            reason?: string;
+            heldAt?: string;
+            closedAt?: string;
+        };
+        /** Set on a machine created by restoring a deleted one. */
+        restoredFromLeaseId?: string;
+    };
+}
+/**
+ * A deleted workspace: restorable into a new machine until `recoverableUntil`,
+ * then every copy is deleted and `completedAt` records it.
+ */
+export interface DedicatedLeaseDeletion {
+    status?: 'recoverable' | 'purging' | 'completed';
+    requestedAt?: string | null;
+    recoverableUntil?: string | null;
+    restorable?: boolean;
+    restoredToLeaseId?: string | null;
+    completedAt?: string | null;
+}
 export interface CreateDedicatedRuntimeInput extends DedicatedRuntimeScope {
     requestId: string;
     displayName: string;
@@ -16,7 +81,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 +105,287 @@ 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>;
+/**
+ * Restore a deleted Dedicated Runtime into a NEW machine, from the final recovery
+ * point its deletion kept. Only inside the deletion's recovery window, and once
+ * per deletion; the response's `lease` is the new machine. The cap defaults to
+ * the deleted machine's.
+ */
+export declare function restoreDeletedDedicatedRuntime(leaseId: string, options?: {
+    displayName?: string;
+    monthlySpendingLimitCents?: number;
+    requestId?: string;
+} & 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;
+    /**
+     * Present when a started command's stored outcome kept only the tail: the
+     * number of bytes the machine returned, of which `stdout` is the last part.
+     */
+    outputBytes?: number;
+}
+/** The server's ceiling for one exec; documented beside the route. */
+export declare const DEDICATED_EXEC_MAX_TIMEOUT_MS: number;
+/** The server's default when a command names no timeout. */
+export declare const DEDICATED_EXEC_DEFAULT_TIMEOUT_MS: number;
+/**
+ * Run one command on the machine as the workload user, in ONE request.
+ *
+ * The synchronous route, kept for servers that predate `executions`. It holds
+ * the request open while the command runs, so behind CloudFront a command that
+ * runs past ~60 s is cut off at the edge while it keeps running (OSK-8705).
+ * `runDedicatedExec` (dedicated-exec.ts) starts and observes instead, and falls
+ * back to this only when the server has no `executions` route.
+ *
+ * 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>;
+export type DedicatedRuntimeExecutionState = 'running' | 'completed' | 'failed' | 'unknown';
+/** A started command, as `GET .../executions/:id` reports it. */
+export interface DedicatedRuntimeExecution {
+    id: string;
+    state: DedicatedRuntimeExecutionState;
+    startedAt: string;
+    timeoutMs: number;
+    completedAt?: string;
+    /** `completed`: exactly what the synchronous exec route returns. */
+    result?: DedicatedRuntimeExecResult;
+    /** `failed` / `unknown`: the status and body the synchronous route would have answered with. */
+    error?: {
+        status?: number;
+        code?: string;
+        error?: string;
+        message?: string;
+    } & Record<string, unknown>;
+}
+export interface DedicatedRuntimeExecutionResponse {
+    execution: DedicatedRuntimeExecution;
+    replayed?: boolean;
+}
+/**
+ * Start one command. `requestId` is the idempotency key: the same id, for the
+ * same command on the same lease, returns the execution it already started —
+ * so a retry after a lost response never runs the command twice.
+ */
+export declare function startDedicatedRuntimeExecution(leaseId: string, input: DedicatedRuntimeExecInput, options: {
+    requestId: string;
+    signal?: AbortSignal;
+} & DedicatedRuntimeScope): Promise<DedicatedRuntimeExecutionResponse>;
+/** Read a started command, letting the server hold the answer up to `waitMs` for it to end. */
+export declare function observeDedicatedRuntimeExecution(leaseId: string, executionId: string, options: {
+    waitMs: number;
+    signal?: AbortSignal;
+} & DedicatedRuntimeScope): Promise<DedicatedRuntimeExecutionResponse>;
+/** 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.
+ */
+/** One line saying what a deletion still allows. */
+export declare function describeDedicatedDeletion(deletion: DedicatedLeaseDeletion, leaseId?: string): string;
+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 lease of the machine this process is running on, from the harness rows.
+ *
+ * Nothing in a workload process's environment names its lease — the daemon's
+ * environment (lease, generation, credentials) sits on the other side of the uid
+ * split by design. The CLI hand-off descriptor the daemon publishes to the
+ * workload group does carry the daemon's id, and every harness row that daemon
+ * registered carries `metadata.machineLeaseId`. Joining the two answers "which
+ * machine am I" with no new daemon surface.
+ */
+export declare function dedicatedLeaseIdForDaemon(daemonId: string | undefined | null, harnesses: readonly Harness[]): string | null;
+/**
+ * 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 {};