@skrr-ai/cli 0.1.25 → 0.1.26

package/dist/lib/dedicated-machines.js

@@ -1,20 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEDICATED_LEASE_ACTIONS = void 0;
+exports.DEDICATED_FILE_MAX_BYTES = exports.DEDICATED_FILE_CHUNK_BYTES = exports.DEDICATED_EXEC_MAX_TIMEOUT_MS = exports.DEDICATED_MACHINE_PRODUCT = exports.DEDICATED_LEASE_ACTIONS = void 0;
 exports.dedicatedRuntimeCreateInput = dedicatedRuntimeCreateInput;
+exports.isDedicatedRepositoryRef = isDedicatedRepositoryRef;
 exports.createDedicatedRuntime = createDedicatedRuntime;
 exports.listDedicatedRuntimes = listDedicatedRuntimes;
 exports.getDedicatedRuntime = getDedicatedRuntime;
 exports.performDedicatedLeaseAction = performDedicatedLeaseAction;
 exports.growDedicatedRuntime = growDedicatedRuntime;
+exports.setDedicatedRuntimeSpendingLimit = setDedicatedRuntimeSpendingLimit;
 exports.closeDedicatedRuntimeIncidentHold = closeDedicatedRuntimeIncidentHold;
 exports.destroyDedicatedRuntime = destroyDedicatedRuntime;
+exports.execDedicatedRuntime = execDedicatedRuntime;
+exports.readDedicatedRuntimeFileChunk = readDedicatedRuntimeFileChunk;
+exports.writeDedicatedRuntimeFileChunk = writeDedicatedRuntimeFileChunk;
+exports.parseDedicatedCopyEndpoints = parseDedicatedCopyEndpoints;
 exports.dedicatedLeaseId = dedicatedLeaseId;
 exports.dedicatedLeaseState = dedicatedLeaseState;
 exports.dedicatedLeaseDisplayName = dedicatedLeaseDisplayName;
+exports.formatUsdCents = formatUsdCents;
+exports.dedicatedSpendSummary = dedicatedSpendSummary;
+exports.describeDedicatedLease = describeDedicatedLease;
+exports.dedicatedLeaseHarnesses = dedicatedLeaseHarnesses;
+exports.dedicatedTerminalHarness = dedicatedTerminalHarness;
+exports.selectDedicatedAttachHarness = selectDedicatedAttachHarness;
+exports.dedicatedCatalogFromProducts = dedicatedCatalogFromProducts;
+exports.dedicatedRuntimeApiErrorCode = dedicatedRuntimeApiErrorCode;
 exports.formatDedicatedRuntimeApiError = formatDedicatedRuntimeApiError;
 const api_fetch_1 = require("./api-fetch");
-const harnesses_1 = require("./harnesses");
 exports.DEDICATED_LEASE_ACTIONS = [
     'start',
     'stop',
@@ -22,6 +35,7 @@ exports.DEDICATED_LEASE_ACTIONS = [
     'snapshot',
     'health-check',
 ];
+exports.DEDICATED_MACHINE_PRODUCT = 'dedicated-machine';
 /**
  * Flags in, request body out — and the point of it being a function is the
  * OMISSION.
@@ -36,6 +50,7 @@ exports.DEDICATED_LEASE_ACTIONS = [
  * means the same bug was invisible in them.
  */
 function dedicatedRuntimeCreateInput(input) {
+    const repositoryRef = input.repositoryRef?.trim();
     return {
         requestId: input.requestId,
         displayName: input.displayName,
@@ -47,45 +62,74 @@ function dedicatedRuntimeCreateInput(input) {
         ...(input.backupProfile
             ? { backupProfile: input.backupProfile }
             : {}),
+        ...(repositoryRef ? { repositoryRef } : {}),
         ...(input.workspaceId ? { workspaceId: input.workspaceId } : {}),
     };
 }
+/**
+ * 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.
+ */
+function isDedicatedRepositoryRef(value) {
+    return /^(?:https?:\/\/)?(?:github\.com\/)?[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?(?:\.git)?$/i.test(value.trim());
+}
+// Takes the finished path rather than composing one from a suffix, so the route
+// each call reaches is a literal at the call site. `cli/src/__tests__/helpers/
+// api-surface.ts` reads coverage out of the source, and a path assembled inside a
+// builder is invisible to it: exec, files/read and files/write were all reported
+// unreachable by domain-api-parity while being perfectly reachable, which is the
+// reading that trains people to allowlist things that are fine. Same shape as
+// `withQuery` on the `request.*` side.
+function withDedicatedScope(path, scope) {
+    if (!scope.workspaceId)
+        return path;
+    const separator = path.includes('?') ? '&' : '?';
+    return `${path}${separator}workspaceId=${encodeURIComponent(scope.workspaceId)}`;
+}
 async function createDedicatedRuntime(input) {
     const { requestId, workspaceId, ...body } = input;
-    if (workspaceId) {
-        return (0, api_fetch_1.apiFetch)(`/api/machines/dedicated?workspaceId=${encodeURIComponent(workspaceId)}`, {
-            method: 'POST',
-            body,
-            headers: { 'Idempotency-Key': requestId },
-        });
-    }
-    return (0, api_fetch_1.apiFetch)('/api/machines/dedicated', {
-        method: 'POST',
-        body,
-        headers: { 'Idempotency-Key': requestId },
-    });
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope('/api/machines/dedicated', { workspaceId }), { method: 'POST', body, headers: { 'Idempotency-Key': requestId } });
 }
 async function listDedicatedRuntimes(options = {}) {
-    return (0, harnesses_1.listHarnessLeases)({
-        ...options,
-        machineProduct: 'dedicated-machine',
-    });
+    const query = new URLSearchParams();
+    if (options.limit)
+        query.set('limit', String(options.limit));
+    if (options.state)
+        query.set('state', options.state);
+    query.set('machineProduct', exports.DEDICATED_MACHINE_PRODUCT);
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/leases?${query.toString()}`, options));
 }
-async function getDedicatedRuntime(leaseId) {
-    return (0, harnesses_1.getHarnessLease)(leaseId);
+async function getDedicatedRuntime(leaseId, scope = {}) {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/leases/${encodeURIComponent(leaseId)}`, scope));
 }
-async function performDedicatedLeaseAction(leaseId, action) {
-    return (0, harnesses_1.performHarnessLeaseAction)(leaseId, action);
+async function performDedicatedLeaseAction(leaseId, action, scope = {}) {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/leases/${encodeURIComponent(leaseId)}/actions/${encodeURIComponent(action)}`, scope), { method: 'POST' });
 }
 async function growDedicatedRuntime(leaseId, storageGb, options = {}) {
-    return (0, api_fetch_1.apiFetch)(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/storage`, {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/storage`, options), {
         method: 'POST',
         body: { storageGb },
         ...(options.requestId ? { headers: { 'Idempotency-Key': options.requestId } } : {}),
     });
 }
+/**
+ * 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.
+ */
+async function setDedicatedRuntimeSpendingLimit(leaseId, spendingLimitCents, scope = {}) {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/leases/${encodeURIComponent(leaseId)}/billing`, scope), { method: 'PATCH', body: { spendingLimitCents } });
+}
 async function closeDedicatedRuntimeIncidentHold(leaseId, options = {}) {
-    return (0, api_fetch_1.apiFetch)(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/incident-hold/close`, {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/incident-hold/close`, options), {
         method: 'POST',
         body: {},
         ...(options.requestId ? { headers: { 'Idempotency-Key': options.requestId } } : {}),
@@ -95,7 +139,57 @@ async function destroyDedicatedRuntime(leaseId, options = {}) {
     const query = options.retentionIntent
         ? `?retentionIntent=${encodeURIComponent(options.retentionIntent)}`
         : '';
-    return (0, api_fetch_1.apiFetch)(`/api/machines/leases/${encodeURIComponent(leaseId)}${query}`, { method: 'DELETE' });
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/leases/${encodeURIComponent(leaseId)}${query}`, options), { method: 'DELETE' });
+}
+/** The server's ceiling for one exec; documented beside the route. */
+exports.DEDICATED_EXEC_MAX_TIMEOUT_MS = 10 * 60 * 1000;
+/**
+ * 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.
+ */
+async function execDedicatedRuntime(leaseId, input, scope = {}) {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/exec`, scope), {
+        method: 'POST',
+        body: {
+            command: input.command,
+            ...(input.cwd ? { cwd: input.cwd } : {}),
+            ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
+        },
+    });
+}
+/** Mirrors the daemon's bounds (daemon/src/tools/file-transfer.ts). */
+exports.DEDICATED_FILE_CHUNK_BYTES = 512 * 1024;
+exports.DEDICATED_FILE_MAX_BYTES = 64 * 1024 * 1024;
+async function readDedicatedRuntimeFileChunk(leaseId, input, scope = {}) {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/files/read`, scope), { method: 'POST', body: input });
+}
+async function writeDedicatedRuntimeFileChunk(leaseId, input, scope = {}) {
+    return (0, api_fetch_1.apiFetch)(withDedicatedScope(`/api/machines/dedicated/${encodeURIComponent(leaseId)}/files/write`, scope), { method: 'POST', body: input });
+}
+const REMOTE_ENDPOINT = /^(rtl_[A-Za-z0-9_-]{1,80}):(.+)$/;
+/**
+ * `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.
+ */
+function parseDedicatedCopyEndpoints(source, destination) {
+    const src = REMOTE_ENDPOINT.exec(source);
+    const dst = REMOTE_ENDPOINT.exec(destination);
+    if (src && dst) {
+        throw new Error('Copy between two machines is not supported; one side must be a local path.');
+    }
+    if (!src && !dst) {
+        throw new Error('One side must name the machine, as <lease-id>:<path>.');
+    }
+    if (src) {
+        return { direction: 'download', leaseId: src[1], remotePath: src[2], localPath: destination };
+    }
+    return { direction: 'upload', localPath: source, leaseId: dst[1], remotePath: dst[2] };
 }
 function dedicatedLeaseId(lease) {
     return String(lease?.id ?? '');
@@ -106,6 +200,224 @@ function dedicatedLeaseState(lease) {
 function dedicatedLeaseDisplayName(lease) {
     return lease?.displayName ? String(lease.displayName) : '-';
 }
+/** `$12.34` — cents are what the API speaks; dollars are what a person reads. */
+function formatUsdCents(cents) {
+    if (typeof cents !== 'number' || !Number.isFinite(cents))
+        return '-';
+    const sign = cents < 0 ? '-' : '';
+    return `${sign}$${(Math.abs(cents) / 100).toFixed(2)}`;
+}
+/** `this month $1.23 of $500.00 cap`, or why that sentence cannot be written. */
+function dedicatedSpendSummary(lease) {
+    const billing = lease.billing;
+    if (!billing)
+        return '-';
+    const cap = billing.monthlySpendLimitCents ?? billing.spendingLimitCents;
+    if (billing.spendStatusUnavailable) {
+        return `spend unavailable right now · cap ${formatUsdCents(cap)}`;
+    }
+    const spent = billing.currentMonthSpendCents;
+    const projected = billing.projectedCurrentMonthSpendCents;
+    const parts = [`${formatUsdCents(spent)} this month of ${formatUsdCents(cap)} cap`];
+    if (typeof projected === 'number' && projected !== spent) {
+        parts.push(`projected ${formatUsdCents(projected)}`);
+    }
+    if (billing.spendingLimitExceeded) {
+        parts.push('OVER CAP — compute is stopped, files are kept');
+    }
+    return parts.join(' · ');
+}
+/**
+ * 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.
+ */
+function describeDedicatedLease(lease, harnesses = []) {
+    const lines = [dedicatedLeaseDisplayName(lease)];
+    const row = (label, value) => {
+        if (value === undefined || value === null || value === '')
+            return;
+        lines.push(`  ${label.padEnd(13)}${value}`);
+    };
+    row('id', dedicatedLeaseId(lease));
+    row('state', lease.stateReason
+        ? `${dedicatedLeaseState(lease)} (${lease.stateReason})`
+        : dedicatedLeaseState(lease));
+    const resources = lease.resources || {};
+    const size = [
+        resources.sizePreset,
+        resources.cpu ? `${resources.cpu} vCPU` : '',
+        resources.memoryGb ? `${resources.memoryGb} GiB RAM` : '',
+        resources.regionClass,
+    ]
+        .filter(Boolean)
+        .join(' · ');
+    row('size', size);
+    const storage = lease.storage || {};
+    const disk = [
+        resources.storageGb ? `${resources.storageGb} GiB` : '',
+        storage.retentionClass ? `retention ${storage.retentionClass}` : '',
+        storage.backupProfile ? `backup ${storage.backupProfile}` : '',
+    ]
+        .filter(Boolean)
+        .join(' · ');
+    row('workspace', disk);
+    row('last backup', storage.lastBackupAt);
+    const image = [resources.imageVersion || lease.daemon?.imageVersion].filter(Boolean).join('');
+    row('image', image);
+    if (lease.daemon?.version || lease.daemon?.lastHeartbeatAt) {
+        row('daemon', [
+            lease.daemon.version ? `skrrd ${lease.daemon.version}` : '',
+            lease.daemon.lastHeartbeatAt ? `heartbeat ${lease.daemon.lastHeartbeatAt}` : '',
+        ]
+            .filter(Boolean)
+            .join(' · '));
+    }
+    const health = lease.health;
+    if (health && typeof health.assignable === 'boolean') {
+        row('health', health.assignable
+            ? 'can take work'
+            : `not assignable${health.reasons?.length ? `: ${[...new Set(health.reasons)].join(', ')}` : ''}`);
+    }
+    row('spend', lease.billing ? dedicatedSpendSummary(lease) : undefined);
+    if (storage.deleteAfter || storage.unpaidSince) {
+        row('deletion', [
+            storage.unpaidSince ? `unpaid since ${storage.unpaidSince}` : '',
+            storage.deletionNoticeAt ? `notice ${storage.deletionNoticeAt}` : '',
+            storage.deleteAfter ? `workspace deleted after ${storage.deleteAfter}` : '',
+        ]
+            .filter(Boolean)
+            .join(' · '));
+    }
+    const hold = lease.recovery?.incidentHold;
+    if (hold?.status === 'open') {
+        row('incident', `hold open since ${hold.heldAt || '?'} — the failed source volume is billed until \`incident-close\``);
+    }
+    const engines = dedicatedLeaseHarnesses(lease, harnesses);
+    if (engines.length > 0) {
+        row('engines', engines.map((harness) => `${harness.provider} (${harness.status || 'unknown'})`).join(', '));
+    }
+    // What the PRODUCT supports, not what this state allows: an archived lease
+    // still lists `start`. Labelled so nobody scripts against it as the latter.
+    const capabilities = Object.entries(lease.lifecycleCapabilities || {})
+        .filter(([, allowed]) => allowed)
+        .map(([name]) => name);
+    row('supports', capabilities.join(', '));
+    row('support ref', lease.supportReference);
+    return lines;
+}
+/**
+ * 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.
+ */
+function dedicatedLeaseHarnesses(lease, harnesses) {
+    const seenAt = (harness) => Date.parse(harness.lastSeenAt || '') || 0;
+    return harnesses
+        .filter((harness) => {
+        const metadata = harness.metadata || {};
+        return (metadata.machineProduct === exports.DEDICATED_MACHINE_PRODUCT &&
+            metadata.machineLeaseId === lease.id);
+    })
+        .sort((a, b) => seenAt(b) - seenAt(a));
+}
+/**
+ * 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.
+ */
+function dedicatedTerminalHarness(lease, harnesses) {
+    return (dedicatedLeaseHarnesses(lease, harnesses).find((harness) => harness.status === 'online' &&
+        Boolean(harness.daemonId) &&
+        (harness.harnessLocation === undefined || harness.harnessLocation === 'local')) || 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.
+ */
+function selectDedicatedAttachHarness(lease, harnesses, engine) {
+    const rows = dedicatedLeaseHarnesses(lease, harnesses);
+    if (rows.length === 0) {
+        return {
+            error: `No harness is registered for ${lease.id} yet. A machine's daemon registers one when it ` +
+                'first connects; start the machine, wait for it to be ready, and try again.',
+        };
+    }
+    const providers = [...new Set(rows.map((row) => row.provider))];
+    if (engine) {
+        const match = rows.find((row) => row.provider === engine);
+        if (!match) {
+            return {
+                error: `${lease.id} has no "${engine}" engine. Registered: ${providers.join(', ')}.`,
+            };
+        }
+        return { harness: match };
+    }
+    if (providers.length > 1) {
+        return {
+            error: `${lease.id} runs more than one engine (${providers.join(', ')}); the one you attach is ` +
+                'the one the agent works under. Pass --engine <name>.',
+        };
+    }
+    return { harness: rows[0] };
+}
+/**
+ * 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.
+ */
+function dedicatedCatalogFromProducts(payload) {
+    const products = Array.isArray(payload)
+        ? payload
+        : (payload?.products ?? []);
+    const product = products.find((row) => row?.machineProduct === exports.DEDICATED_MACHINE_PRODUCT || row?.id === exports.DEDICATED_MACHINE_PRODUCT);
+    if (!product)
+        return null;
+    const configuration = (product.configuration || {});
+    const billing = (product.billing || {});
+    const presentation = (billing.presentation || {});
+    const sizeCatalog = Array.isArray(configuration.sizePresetCatalog)
+        ? configuration.sizePresetCatalog
+        : (Array.isArray(configuration.sizePresets) ? configuration.sizePresets : []).map((id) => ({ id }));
+    const availability = typeof product.availability === 'string'
+        ? product.availability
+        : String(product.availability?.status || 'unknown');
+    return {
+        availability,
+        ...(typeof product.disabledReason === 'string' && product.disabledReason
+            ? { disabledReason: product.disabledReason }
+            : {}),
+        sizes: sizeCatalog,
+        regionClasses: configuration.regionClasses || [],
+        ...(configuration.storage
+            ? { storage: configuration.storage }
+            : {}),
+        retentionClasses: configuration.retentionClasses || [],
+        backupProfiles: configuration.backupProfiles || [],
+        defaultMonthlySpendingLimitCents: billing.defaultMonthlySpendingLimitCents,
+        maxUserMonthlySpendingLimitCents: billing.maxUserMonthlySpendingLimitCents,
+        priceLines: Array.isArray(presentation.priceLines)
+            ? presentation.priceLines
+            : [],
+        ...(typeof presentation.headline === 'string' ? { headline: presentation.headline } : {}),
+    };
+}
 /**
  * Dedicated Runtime commands are unusually likely to meet a server that has
  * never heard of them.
@@ -140,6 +452,50 @@ function describeMissingEndpoint(err) {
         'the deployment — `skrr context` names the server it is talking to, and `skrr machines ' +
         'dedicated list` will still work if the feature is deployed at all.');
 }
+/**
+ * A lease that is not found is usually a SCOPE question, not a typo.
+ *
+ * Every lease lookup is `(owner, workspace)`: with a workspace selected the
+ * server searches only that workspace's leases, and without one only personal
+ * leases. So `not found` for an id the caller just created most often means the
+ * active workspace differs from the one the machine was created in.
+ */
+function describeLeaseNotFound(err) {
+    if (err.status !== 404)
+        return null;
+    try {
+        const parsed = JSON.parse(err.body || '');
+        if (parsed.code || parsed.error !== 'Machine lease not found')
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return ('Machine lease not found. Leases are looked up within one scope: your personal machines, or ' +
+        'the workspace you name. If you created it with --workspace, pass the same --workspace here; ' +
+        '`skrr machines dedicated list` shows what this scope can see.');
+}
+/**
+ * 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.
+ */
+function dedicatedRuntimeApiErrorCode(err) {
+    if (!(err instanceof api_fetch_1.ApiFetchError)) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(err.body || '');
+        if (typeof parsed.code === 'string' && parsed.code) {
+            return parsed.code;
+        }
+    }
+    catch {
+        // Unparseable body: no product code.
+    }
+    return err.status ? `HTTP_${err.status}` : undefined;
+}
 function formatDedicatedRuntimeApiError(err) {
     if (!(err instanceof api_fetch_1.ApiFetchError) || !err.body) {
         return null;
@@ -147,6 +503,10 @@ function formatDedicatedRuntimeApiError(err) {
     if (err.status === 401) {
         return null;
     }
+    const notFound = describeLeaseNotFound(err);
+    if (notFound) {
+        return notFound;
+    }
     const missingEndpoint = describeMissingEndpoint(err);
     if (missingEndpoint) {
         return missingEndpoint;

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

@@ -0,0 +1,89 @@
+import { io, type Socket } from 'socket.io-client';
+/**
+ * A real pseudo-terminal on a Dedicated Runtime, from a local terminal.
+ *
+ * This is the same lane the web lease card's "Open terminal" drives — the
+ * human terminal vocabulary (`HARNESS_TERMINAL_EVENTS`) relayed by `EngineTerminal/handlers.js` to the
+ * daemon's `TerminalSessionManager`, which runs an interactive login bash as
+ * `skrr-workload` through the PTY relay. Nothing here is a second way in: the
+ * relay admits a Dedicated Runtime terminal only when agent dispatch to that
+ * lease would be admitted (current generation, running, healthy volume).
+ *
+ * It is deliberately NOT a loop over `exec`. `exec` is one command with no TTY;
+ * a shell built from it would look like a shell and behave like none — no job
+ * control, no prompts, no state between lines. This is the honest version.
+ */
+/** Ctrl-] — telnet's escape. Ctrl-C and Ctrl-D belong to the remote shell. */
+export declare const TERMINAL_DETACH_BYTE = 29;
+/** How long the machine has to answer a start before the CLI gives up. */
+export declare const TERMINAL_START_TIMEOUT_MS = 30000;
+/**
+ * When to type an initial command: once the shell has printed something and
+ * then gone quiet, or after a fallback — the same heuristic the web terminal
+ * uses for its Sign in menu, because both are waiting on the same login bash.
+ */
+export declare const TERMINAL_READY_QUIET_MS = 300;
+export declare const TERMINAL_READY_FALLBACK_MS = 2500;
+export interface TerminalOutputFrame {
+    sessionId?: string;
+    daemonId?: string;
+    type?: 'stdout' | 'stderr' | 'exit' | 'error' | 'info';
+    data?: string;
+    dataBase64?: string;
+    encoding?: 'utf8' | 'base64';
+    exitCode?: number | null;
+    signal?: string | null;
+}
+export interface TerminalStartAck {
+    sessionId?: string;
+    daemonId?: string;
+    ok?: boolean;
+    error?: string;
+    code?: string;
+}
+/** Bytes of one output frame, without splitting a UTF-8 or ANSI sequence. */
+export declare function decodeTerminalFrame(frame: TerminalOutputFrame): Buffer;
+/**
+ * Types `command` once, when the shell looks ready.
+ *
+ * Returned as an object with injectable timers so the readiness rule is tested
+ * without a PTY. `onOutput` re-arms the quiet timer; the fallback fires
+ * regardless, because a shell with a silent prompt must not wait forever.
+ */
+export declare function createInitialCommandTyper(options: {
+    command: string;
+    send: (data: string) => void;
+    quietMs?: number;
+    fallbackMs?: number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}): {
+    start(): void;
+    onOutput(): void;
+    cancel(): void;
+    readonly typed: boolean;
+};
+export declare class DedicatedTerminalError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/** A start refusal in words that say what to do, keyed by the relay's codes. */
+export declare function describeTerminalStartRefusal(ack: TerminalStartAck): string;
+export interface DedicatedTerminalOptions {
+    baseURL: string;
+    token: string;
+    runtimeId: string;
+    daemonId: string;
+    cwd?: string;
+    initialCommand?: string;
+    input: NodeJS.ReadStream;
+    output: NodeJS.WriteStream;
+    errorOutput: NodeJS.WritableStream;
+    /** Injected for tests. */
+    connect?: (url: string, opts: Parameters<typeof io>[1]) => Socket;
+}
+/**
+ * Run one interactive session to completion. Resolves with the exit code the
+ * CLI should exit with: the shell's own, 0 for a detach, 1 for a lost session.
+ */
+export declare function runDedicatedTerminal(options: DedicatedTerminalOptions): Promise<number>;