@skrr-ai/cli 0.1.8

package/dist/lib/harnesses.d.ts

@@ -0,0 +1,138 @@
+import type { QuotaAccountSummary, QuotaHistory } from '@skrr-ai/data-provider';
+/**
+ * The machine fleet — an ENGINE is one place work can execute.
+ *
+ * ## The word
+ *
+ * Web (`client/src/components/Harnesses/`, `wireToEngine`) and mobile
+ * (`mobile/react-native/src/types/Harness.ts`) both independently landed on
+ * "Harness" for these rows. The CLI was the odd one out, and only half-heartedly:
+ * `skrr harnesses list` reached this surface while every one of its siblings
+ * talked to hosted sandbox sessions. This module is the CLI catching up.
+ *
+ * `/api/harnesses` stays as the wire path. Renaming an HTTP surface reaches four
+ * clients and a database; the vocabulary decision does not depend on it, and the
+ * two layers are allowed to differ as long as the difference is written down —
+ * mobile's own type file already says "(endpoint name unchanged)".
+ *
+ * See `docs/architecture/harness-harness-sandbox-vocabulary-2026-08-16.md`.
+ *
+ * ## An Harness is a PAIR, not a machine
+ *
+ * `upsertHarness` keys a row on `{owner, runtimeKey, provider}` where
+ * `runtimeKey = rk1:<stableDaemonId>:<profile>`. So an harness is
+ * `(daemon-profile, harness)` — and registration is
+ * `for (const provider of providers) upsertHarness({provider})`, which means a
+ * laptop with Claude Code, Codex and Gemini installed is THREE harnesses, all
+ * named `… — Frank's MacBook Pro`.
+ *
+ * That is why the topic is not called `machine`: one machine is several
+ * harnesses. `machine` is the right word one level down (`machineUuid`), and
+ * `harness` one level up in the pair. Four levels, only the last of which is a
+ * row — see the vocabulary record.
+ *
+ * ## Inline path literals
+ *
+ * `domain-api-parity` resolves a command to an endpoint by reading these
+ * strings. A helper that assembles the URL is opaque to it, so those endpoints
+ * read as unreachable and get allow-listed — a check going green on an
+ * assertion it never made.
+ */
+export interface Harness {
+    _id: string;
+    provider: string;
+    name?: string;
+    status?: string;
+    harnessLocation?: 'local' | 'cloud';
+    daemonId?: string;
+    machineUuid?: string;
+    model?: string;
+    version?: number;
+    claudeEngine?: 'cli' | 'sdk';
+    lastSeenAt?: string;
+}
+export interface HarnessLease {
+    id?: string;
+    leaseId?: string;
+    productId?: string;
+    state?: string;
+    runtimeId?: string;
+    workspaceId?: string | null;
+    createdAt?: string;
+    expiresAt?: string;
+}
+/** `pause | resume | destroy | terminate | health-check` (MachineLeaseService). */
+export declare const HARNESS_LEASE_ACTIONS: string[];
+/** `user` (the default) or `workspace`. */
+export type HarnessDefaultScope = 'user' | 'workspace';
+export declare function listHarnesses(filters?: {
+    status?: string;
+    provider?: string;
+}): Promise<{
+    harnesses?: Harness[];
+}>;
+export declare function getHarness(id: string): Promise<{
+    harness?: Harness;
+}>;
+export declare function getHarnessModels(id: string): Promise<unknown>;
+export declare function listHarnessProducts(): Promise<unknown>;
+export declare function getHarnessUsage(id: string): Promise<unknown>;
+/** The rollup across every harness. The web calls this key `fleetUsage`. */
+export declare function getAllHarnessUsage(): Promise<unknown>;
+export type { QuotaAccountSummary, QuotaHistory };
+/** The CLI subscription accounts this user's daemons have reported readings for. */
+export declare function listQuotaAccounts(): Promise<{
+    accounts: QuotaAccountSummary[];
+}>;
+/**
+ * One account's reading series plus the spend buckets over the same horizon.
+ *
+ * The two arrive apart and are deliberately NOT reconciled — see the route.
+ * A caller that adds them together is asserting something neither source says.
+ */
+export declare function getQuotaHistory(params?: {
+    provider?: 'claude' | 'codex';
+    externalAccountId?: string;
+    sinceDays?: number;
+}): Promise<QuotaHistory>;
+/**
+ * `PATCH /:id` is OPTIMISTICALLY LOCKED: it wants the `expectedVersion` the
+ * caller read, and answers 409 with the current state when they disagree. So an
+ * edit is a read-then-write, and the read has to be part of this function —
+ * making the caller pass a version it did not fetch is how two terminals
+ * silently overwrite each other's rename.
+ */
+export declare function updateHarness(id: string, patch: Record<string, unknown>): Promise<{
+    harness?: Harness;
+}>;
+export declare function forgetHarness(id: string): Promise<unknown>;
+/**
+ * A per-USER display name. Distinct from `updateHarness({name})`, which renames
+ * the harness for everyone it is shared with — this only changes what YOU see,
+ * which is why it lives on a collection route rather than under `/:id`.
+ */
+export declare function setHarnessAlias(id: string, name: string | null): Promise<unknown>;
+export declare function setDefaultHarness(id: string, scope?: HarnessDefaultScope): Promise<unknown>;
+export declare function mintInstallToken(installIntent: string): Promise<unknown>;
+export declare function startHarnessPing(id: string): Promise<{
+    pingId?: string;
+    status?: string;
+}>;
+export declare function readHarnessPing(id: string, pingId: string): Promise<{
+    status?: string;
+    latencyMs?: number;
+    error?: string;
+}>;
+export declare function listHarnessLeases(): Promise<{
+    leases?: HarnessLease[];
+}>;
+export declare function getHarnessLease(leaseId: string): Promise<{
+    lease?: HarnessLease;
+}>;
+export declare function releaseHarnessLease(leaseId: string): Promise<unknown>;
+export declare function performHarnessLeaseAction(leaseId: string, action: string): Promise<{
+    lease?: HarnessLease;
+}>;
+export declare function setHarnessLeaseBilling(leaseId: string, body: Record<string, unknown>): Promise<{
+    lease?: HarnessLease;
+}>;

package/dist/lib/harnesses.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HARNESS_LEASE_ACTIONS = void 0;
+exports.listHarnesses = listHarnesses;
+exports.getHarness = getHarness;
+exports.getHarnessModels = getHarnessModels;
+exports.listHarnessProducts = listHarnessProducts;
+exports.getHarnessUsage = getHarnessUsage;
+exports.getAllHarnessUsage = getAllHarnessUsage;
+exports.listQuotaAccounts = listQuotaAccounts;
+exports.getQuotaHistory = getQuotaHistory;
+exports.updateHarness = updateHarness;
+exports.forgetHarness = forgetHarness;
+exports.setHarnessAlias = setHarnessAlias;
+exports.setDefaultHarness = setDefaultHarness;
+exports.mintInstallToken = mintInstallToken;
+exports.startHarnessPing = startHarnessPing;
+exports.readHarnessPing = readHarnessPing;
+exports.listHarnessLeases = listHarnessLeases;
+exports.getHarnessLease = getHarnessLease;
+exports.releaseHarnessLease = releaseHarnessLease;
+exports.performHarnessLeaseAction = performHarnessLeaseAction;
+exports.setHarnessLeaseBilling = setHarnessLeaseBilling;
+const api_fetch_1 = require("./api-fetch");
+/** `pause | resume | destroy | terminate | health-check` (MachineLeaseService). */
+exports.HARNESS_LEASE_ACTIONS = ['pause', 'resume', 'destroy', 'terminate', 'health-check'];
+// ── Fleet reads ────────────────────────────────────────────────────────────
+async function listHarnesses(filters = {}) {
+    const params = new URLSearchParams();
+    if (filters.status)
+        params.set('status', filters.status);
+    if (filters.provider)
+        params.set('provider', filters.provider);
+    const query = params.toString();
+    // Two branches rather than one interpolated template. `domain-api-parity`
+    // reads these literals with a regex that stops at the first backtick, so a
+    // nested `${query ? `?${query}` : ''}` captures as `/api/harnesses${query ? `
+    // and the endpoint reads as unreachable — the check going blind on the very
+    // call that covers `GET /`.
+    if (!query) {
+        return (0, api_fetch_1.apiFetch)('/api/harnesses');
+    }
+    return (0, api_fetch_1.apiFetch)(`/api/harnesses?${query}`);
+}
+async function getHarness(id) {
+    return (0, api_fetch_1.apiFetch)(`/api/harnesses/${encodeURIComponent(id)}`);
+}
+async function getHarnessModels(id) {
+    return (0, api_fetch_1.apiFetch)(`/api/harnesses/${encodeURIComponent(id)}/models`);
+}
+async function listHarnessProducts() {
+    return (0, api_fetch_1.apiFetch)('/api/machines/products');
+}
+/*
+ * `scope=all` on both reads.
+ *
+ * Without it the API defaults to `personalOnly`, which counts only harnesses
+ * carrying no workspace tag — so `skrr harnesses usage` quietly under-reported
+ * anyone whose machines are lent to a workspace. The question this command
+ * asks is "what did MY machines cost", the same question `harnesses list`
+ * answers when it lists them, and that list is owner-scoped (OSK-4873).
+ */
+async function getHarnessUsage(id) {
+    return (0, api_fetch_1.apiFetch)(`/api/harnesses/${encodeURIComponent(id)}/usage` + '?scope=all');
+}
+/** The rollup across every harness. The web calls this key `fleetUsage`. */
+async function getAllHarnessUsage() {
+    // Query appended OUTSIDE the path literal: the CLI↔API parity check extracts
+    // route paths from these literals, and a `?` inside one makes the endpoint
+    // read as unreachable.
+    const ownerWide = '?scope=all';
+    return (0, api_fetch_1.apiFetch)('/api/harnesses/usage/aggregate' + ownerWide);
+}
+/** The CLI subscription accounts this user's daemons have reported readings for. */
+async function listQuotaAccounts() {
+    return (0, api_fetch_1.apiFetch)('/api/harnesses/quota/accounts');
+}
+/**
+ * One account's reading series plus the spend buckets over the same horizon.
+ *
+ * The two arrive apart and are deliberately NOT reconciled — see the route.
+ * A caller that adds them together is asserting something neither source says.
+ */
+async function getQuotaHistory(params = {}) {
+    const query = new URLSearchParams({ provider: params.provider ?? 'claude' });
+    if (params.externalAccountId) {
+        query.set('externalAccountId', params.externalAccountId);
+    }
+    if (params.sinceDays) {
+        query.set('sinceDays', String(params.sinceDays));
+    }
+    // The query is appended OUTSIDE the path literal on purpose. `domain-api-parity`
+    // reads these strings and rewrites every `${...}` to `:param`, so an
+    // interpolated query turns `/quota/history` into `/quota/history?:param` and
+    // the endpoint reads as unreachable — a real endpoint reported as a hole.
+    const suffix = query.toString();
+    return (0, api_fetch_1.apiFetch)('/api/harnesses/quota/history' + (suffix ? `?${suffix}` : ''));
+}
+// ── Fleet writes ───────────────────────────────────────────────────────────
+/**
+ * `PATCH /:id` is OPTIMISTICALLY LOCKED: it wants the `expectedVersion` the
+ * caller read, and answers 409 with the current state when they disagree. So an
+ * edit is a read-then-write, and the read has to be part of this function —
+ * making the caller pass a version it did not fetch is how two terminals
+ * silently overwrite each other's rename.
+ */
+async function updateHarness(id, patch) {
+    const current = await getHarness(id);
+    const expectedVersion = current?.harness?.version;
+    if (typeof expectedVersion !== 'number') {
+        throw new Error(`Harness ${id} did not report a version; refusing to write without a base.`);
+    }
+    return (0, api_fetch_1.apiFetch)(`/api/harnesses/${encodeURIComponent(id)}`, {
+        method: 'PATCH',
+        body: { patch, expectedVersion },
+    });
+}
+async function forgetHarness(id) {
+    return (0, api_fetch_1.apiFetch)(`/api/harnesses/${encodeURIComponent(id)}`, { method: 'DELETE' });
+}
+/**
+ * A per-USER display name. Distinct from `updateHarness({name})`, which renames
+ * the harness for everyone it is shared with — this only changes what YOU see,
+ * which is why it lives on a collection route rather than under `/:id`.
+ */
+async function setHarnessAlias(id, name) {
+    return (0, api_fetch_1.apiFetch)('/api/harnesses/aliases', {
+        method: 'PATCH',
+        body: { id, name },
+    });
+}
+async function setDefaultHarness(id, scope = 'user') {
+    return (0, api_fetch_1.apiFetch)(`/api/harnesses/${encodeURIComponent(id)}/set-default`, {
+        method: 'POST',
+        body: { scope },
+    });
+}
+async function mintInstallToken(installIntent) {
+    return (0, api_fetch_1.apiFetch)('/api/harnesses/install-token', {
+        method: 'POST',
+        body: { installIntent },
+    });
+}
+// ── Ping ───────────────────────────────────────────────────────────────────
+async function startHarnessPing(id) {
+    return (0, api_fetch_1.apiFetch)(`/api/harnesses/${encodeURIComponent(id)}/ping`, { method: 'POST' });
+}
+async function readHarnessPing(id, pingId) {
+    return (0, api_fetch_1.apiFetch)(`/api/harnesses/${encodeURIComponent(id)}/ping/${encodeURIComponent(pingId)}`);
+}
+// ── Leases (hosted billing plane) ──────────────────────────────────────────
+async function listHarnessLeases() {
+    return (0, api_fetch_1.apiFetch)('/api/machines/leases');
+}
+async function getHarnessLease(leaseId) {
+    return (0, api_fetch_1.apiFetch)(`/api/machines/leases/${encodeURIComponent(leaseId)}`);
+}
+async function releaseHarnessLease(leaseId) {
+    return (0, api_fetch_1.apiFetch)(`/api/machines/leases/${encodeURIComponent(leaseId)}`, {
+        method: 'DELETE',
+    });
+}
+async function performHarnessLeaseAction(leaseId, action) {
+    return (0, api_fetch_1.apiFetch)(`/api/machines/leases/${encodeURIComponent(leaseId)}/actions/${encodeURIComponent(action)}`, { method: 'POST' });
+}
+async function setHarnessLeaseBilling(leaseId, body) {
+    return (0, api_fetch_1.apiFetch)(`/api/machines/leases/${encodeURIComponent(leaseId)}/billing`, { method: 'PATCH', body });
+}

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

@@ -0,0 +1,178 @@
+export interface HostedMachineRepo {
+    installationId?: number;
+    repoFullName?: string;
+    baseBranch?: string | null;
+    checkoutPath?: string | null;
+    installStatus?: string;
+    headSha?: string | null;
+    clonedAt?: string | null;
+    error?: string | null;
+}
+export interface HostedMachineSession {
+    id?: string;
+    _id?: string;
+    name?: string | null;
+    status?: string;
+    machineProduct?: string;
+    machineProductLabel?: string;
+    machineLeaseId?: string | null;
+    agentId?: string | null;
+    conversationId?: string | null;
+    environmentId?: string | null;
+    previewUrl?: string | null;
+    previewPort?: number | null;
+    egressPolicy?: string | null;
+    repos?: HostedMachineRepo[];
+    idleTimeoutMs?: number | null;
+    lastActiveAt?: string | null;
+    pausedAt?: string | null;
+    retentionExpiresAt?: string | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    error?: {
+        class?: string;
+        message?: string;
+    } | string | null;
+    [key: string]: unknown;
+}
+export interface HostedMachineResponse {
+    session?: HostedMachineSession;
+}
+export interface HostedMachineListResponse {
+    data?: HostedMachineSession[];
+}
+/** Bounded default for `machines hosted list --json`; full session histories belong to
+ * an explicit detail request, not an agent's ordinary inventory read. */
+export interface HostedMachineListJson {
+    object: 'list';
+    data: Array<{
+        id: string;
+        status: string;
+        name: string;
+        machineProduct?: string;
+        machineLeaseId?: string;
+        agentId?: string;
+        previewUrl?: string;
+        repos: string;
+        error?: string;
+        provisioningPhase?: string;
+        lastActiveAt?: string;
+        pausedAt?: string;
+        retentionExpiresAt?: string;
+    }>;
+}
+export declare function curateHostedMachineList(response: HostedMachineListResponse): HostedMachineListJson;
+export interface HostedMachineExecResponse {
+    success: boolean;
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number;
+    executionTime?: number;
+    previewUrl?: string | null;
+    session?: HostedMachineSession;
+}
+/**
+ * The curated `machines hosted exec --json` shape (OSK-4870).
+ *
+ * The raw execute response inlines the whole Mongo session document — owner,
+ * idempotency fingerprint, compute-hold and price-book internals — none of
+ * which a caller scripting `exec` asked for, and several of which are internal
+ * identifiers. A caller wants the result of the command it ran, not the row
+ * that billed it, so we project only that plus the session's public id/status.
+ */
+export interface HostedMachineExecJson {
+    success: boolean;
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    executionTime?: number;
+    previewUrl?: string;
+    session?: {
+        id: string;
+        status: string;
+    };
+}
+export declare function curateHostedMachineExecResult(response: HostedMachineExecResponse): HostedMachineExecJson;
+export interface HostedMachineScope {
+    workspaceId?: string;
+}
+export interface StartHostedMachineInput extends HostedMachineScope {
+    agentId?: string;
+    conversationId?: string;
+    environmentId?: string;
+    name?: string;
+    egressPolicy?: 'isolated' | 'allowlist' | 'open';
+    egressAllowHosts?: string[];
+    idleTimeoutMs?: number;
+    spendingLimitCents?: number;
+    clientRequestId: string;
+}
+export interface AttachHostedMachineRepoInput {
+    installationId: number;
+    repoFullName: string;
+    baseBranch?: string;
+    setupScript?: string;
+}
+export interface HostedMachineExecInput {
+    command: string;
+    language?: 'shell' | 'python' | 'node';
+    cwd?: string;
+    timeoutMs?: number;
+}
+export declare function hostedMachineId(session: HostedMachineSession | undefined | null): string;
+export declare function hostedMachineStatus(session: HostedMachineSession | undefined | null): string;
+export declare function hostedMachineDisplayName(session: HostedMachineSession | undefined | null): string;
+export declare function hostedMachineRepoSummary(session: HostedMachineSession | undefined | null): string;
+export declare function hostedMachineErrorSummary(session: HostedMachineSession | undefined | null): string;
+/** Stable, user-facing snapshot for long provisioning waits. */
+export declare function hostedMachineProgressSummary(session: HostedMachineSession | undefined | null): string;
+export declare function isHostedMachineReady(session: HostedMachineSession | undefined | null): boolean;
+export declare function isHostedMachineTerminal(session: HostedMachineSession | undefined | null): boolean;
+export declare function parseDurationMs(value: string | undefined, flagName: string): number | undefined;
+export declare function sleep(ms: number): Promise<void>;
+export declare function formatHostedMachineApiError(err: unknown): string | null;
+export declare function startHostedMachine(input: StartHostedMachineInput): Promise<HostedMachineResponse>;
+export declare function listHostedMachines(scope?: HostedMachineScope & {
+    limit?: number;
+}): Promise<HostedMachineListResponse>;
+export declare function getHostedMachine(id: string, scope?: HostedMachineScope): Promise<HostedMachineResponse>;
+export declare function attachHostedMachineRepo(id: string, input: AttachHostedMachineRepoInput, scope?: HostedMachineScope): Promise<HostedMachineResponse>;
+export declare function pauseHostedMachine(id: string, scope?: HostedMachineScope): Promise<HostedMachineResponse>;
+export declare function resumeHostedMachine(id: string, scope?: HostedMachineScope): Promise<HostedMachineResponse>;
+export declare function destroyHostedMachine(id: string, scope?: HostedMachineScope): Promise<HostedMachineResponse>;
+export declare function execHostedMachine(id: string, input: HostedMachineExecInput, scope?: HostedMachineScope): Promise<HostedMachineExecResponse>;
+/**
+ * The CLI gave up watching. The RUNTIME did not give up.
+ *
+ * These are different events and the old message conflated them: "Timed out
+ * waiting for Hosted Machine <id> to become ready." reads as "this failed", so
+ * the natural next move is to start another one — while the first is still
+ * `provisioning`, still holding a machine lease, and still billing. The server
+ * keeps working on it until LONGRUN_SANDBOX_PROVISION_TIMEOUT_MS (15 min by
+ * default) and only then ages the row out to `failed`; this command's own
+ * --timeout defaults to 10 minutes, so the two clocks never agreed and nothing
+ * said which one the reader was on (dogfood OSK-4675).
+ */
+export declare class HostedMachineReadyTimeoutError extends Error {
+    readonly sessionId: string;
+    readonly lastProgress: string;
+    constructor(sessionId: string, lastProgress: string);
+}
+export declare function waitForHostedMachineReady(id: string, options: HostedMachineScope & {
+    intervalMs: number;
+    timeoutMs?: number;
+    onSnapshot?: (session: HostedMachineSession) => void;
+}): Promise<HostedMachineSession>;
+/**
+ * Human-readable age of an engine's last heartbeat, e.g. `9d`, `4h`, `12m`.
+ *
+ * Exists because "offline" alone is not actionable: a machine that went quiet
+ * two minutes ago during a daemon restart and one that has been dead for nine
+ * days are the same word but completely different problems (OSK-2396, where an
+ * agent sat pinned to a nine-day-dead machine whose display name was identical
+ * to the live one next to it). The age is what tells them apart at a glance.
+ *
+ * Returns null for anything unparseable or in the future, so callers can omit
+ * the clause entirely rather than print a misleading `0m`.
+ */
+export declare function offlineForLabel(lastSeenAt: string, now?: number): string | null;