@slock-ai/computer 0.0.14 → 0.0.16-alpha.0

package/dist/lib/index.d.ts

@@ -1,3 +1,71 @@
+type DaemonState = {
+    running: true;
+    pid: number;
+} | {
+    running: false;
+};
+type ServerHealth = "ok" | "degraded" | "offline";
+interface ServerStatusRow {
+    serverId: string;
+    serverSlug: string | null;
+    serverMachineId: string;
+    serverUrl: string;
+    attachedAt: string | null;
+    daemonLogPath: string;
+    daemon: DaemonState;
+    /** v6 §11 health enum surfaced in `status` table (PR-H §3.3). */
+    health: ServerHealth;
+}
+interface ComputerStatusReport {
+    slockHome: string;
+    loggedIn: boolean;
+    userId: string | null;
+    loginServerUrl: string | null;
+    userSessionError: string | null;
+    service: DaemonState & {
+        logPath: string;
+    };
+    servers: ServerStatusRow[];
+}
+
+interface RunnerListItem {
+    agentId: string;
+    name: string;
+    status: string;
+    model: string;
+    runtime: string;
+}
+
+/**
+ * Per-runner lifecycle states (§3.2). One state at a time per runner.
+ *
+ *   starting  — spawned, not yet reporting ready
+ *   running   — healthy, reporting heartbeats
+ *   degraded  — alive but not satisfying health invariants (e.g. crash
+ *               budget near breach, see §1/§2)
+ *   crashed   — observed exit / fatal signal
+ *   stopped   — intentional stop (operator-driven via `runners stop` or
+ *               service shutdown)
+ */
+declare const RUNNER_STATE_VALUES: readonly ["starting", "running", "degraded", "crashed", "stopped"];
+type RunnerState = (typeof RUNNER_STATE_VALUES)[number];
+declare function isRunnerState(value: unknown): value is RunnerState;
+/**
+ * Service (service) lifecycle states (§3.2). Mirrors runner shape but
+ * narrower — the service is a singleton per install root.
+ *
+ *   starting  — pidfile written, socket not yet listening
+ *   running   — socket listening, heartbeat active
+ *   degraded  — service alive but one or more invariants violated
+ *               (e.g. SERVICE_DEGRADED §7.3 crash-budget breach)
+ *   stopping  — graceful shutdown in flight (SERVICE_SHUTTING_DOWN
+ *               §7.3 emitted to clients)
+ *   stopped   — pidfile cleared, socket closed
+ */
+declare const SERVICE_STATE_VALUES: readonly ["starting", "running", "degraded", "stopping", "stopped"];
+type ServiceState = (typeof SERVICE_STATE_VALUES)[number];
+declare function isServiceState(value: unknown): value is ServiceState;
+
 /**
  * IPC error code family — the seed that `ServiceClient.request` and
  * `ServiceClient.events` propagate. Forward-only post v9-sign: additions
@@ -7,7 +75,7 @@
  * lands in a follow-up reconcile commit that also unifies the codes
  * currently emitted via `ComputerServiceError` across services/*.
  */
-declare const IPC_ERROR_CODES: readonly ["IPC_FRAME_TOO_LARGE", "IPC_PROTOCOL_VERSION_UNSUPPORTED", "IPC_HEARTBEAT_TIMEOUT", "IPC_MALFORMED_FRAME", "IPC_REQUEST_TIMEOUT", "IPC_REQUEST_CANCELED", "IPC_CLIENT_CLOSED"];
+declare const IPC_ERROR_CODES: readonly ["IPC_FRAME_TOO_LARGE", "IPC_PROTOCOL_VERSION_UNSUPPORTED", "IPC_PROTOCOL_HANDSHAKE_FAILED", "IPC_HEARTBEAT_TIMEOUT", "IPC_MALFORMED_FRAME", "IPC_REQUEST_TIMEOUT", "IPC_REQUEST_CANCELED", "IPC_CLIENT_CLOSED"];
 type IpcErrorCode = (typeof IPC_ERROR_CODES)[number];
 /**
  * Runtime narrow guard — exposed so consumers can pattern-match without
@@ -31,41 +99,47 @@ interface RequestOptions {
  * Typed RPC table — keys are kebab-case wire literals (§5.5), values are
  * per-method `{ params, result }` pairs. The v9 sign-lock seed listed
  * here is the §3.2 6-method floor; new methods are additive minor bumps
- * (extending this map). Param/result payload shapes are intentionally
- * `unknown` in this seed — they are pinned in the follow-up commit that
- * lands the state-reader surface (`readServiceStatus` / `readRunnerStatus`
- * / `listRunners`) alongside the IPC handler signatures.
+ * (extending this map).
+ *
+ * State-reader results (`service-status` / `runner-status` /
+ * `list-runners`) are pinned to the lib reader return types — the
+ * D-stage §4 IPC handlers in PR-impl-2 satisfy the wire surface by
+ * delegating to those readers (mechanical `satisfies`).
+ *
+ * Mutation results (`upgrade-start` / `reset-service` / `reset-runner`)
+ * remain `unknown` here — they pin alongside the PR-impl-3 §X migration /
+ * verb pipeline that owns the corresponding handlers.
  */
 interface RequestMethodMap {
     "service-status": {
         params: void;
-        result: unknown;
+        result: ServiceStatusResult;
     };
     "runner-status": {
         params: {
             serverId: string;
         };
-        result: unknown;
+        result: RunnerStatusResult;
     };
     "list-runners": {
         params: void;
-        result: unknown;
+        result: ListRunnersResult;
     };
     "upgrade-start": {
         params: {
-            target?: string;
+            targetVersion?: string;
         };
-        result: unknown;
+        result: UpgradeStartResult;
     };
     "reset-service": {
         params: void;
-        result: unknown;
+        result: ResetServiceResult;
     };
     "reset-runner": {
         params: {
             serverId: string;
         };
-        result: unknown;
+        result: ResetRunnerResult;
     };
 }
 /**
@@ -148,34 +222,264 @@ interface ConnectServiceOptions {
 type ConnectService = (installRoot: string, options?: ConnectServiceOptions) => Promise<ServiceClient>;
 
 /**
- * Per-runner lifecycle states (§3.2). One state at a time per runner.
+ * Canonical lib-side name for the `service-status` reader result, aligned
+ * with the wire method literal. Identical shape to `ComputerStatusReport`
+ * (re-exported above for callers that prefer the historical internal
+ * name).
  *
- *   starting  — spawned, not yet reporting ready
- *   running   — healthy, reporting heartbeats
- *   degraded  — alive but not satisfying health invariants (e.g. crash
- *               budget near breach, see §1/§2)
- *   crashed   — observed exit / fatal signal
- *   stopped   — intentional stop (operator-driven via `runners stop` or
- *               supervisor shutdown)
+ * SECRET-FREE INVARIANT: the report carries server attachment IDENTITY
+ * and pid/liveness derived from filesystem state but NEVER the user
+ * access token or any `sk_computer_*` credential (status.ts §3.3.1
+ * redline, enforced by `status.test.ts` token-leak guards).
  */
-declare const RUNNER_STATE_VALUES: readonly ["starting", "running", "degraded", "crashed", "stopped"];
-type RunnerState = (typeof RUNNER_STATE_VALUES)[number];
-declare function isRunnerState(value: unknown): value is RunnerState;
+type ServiceStatusResult = ComputerStatusReport;
 /**
- * Service (supervisor) lifecycle states (§3.2). Mirrors runner shape but
- * narrower — the service is a singleton per install root.
+ * Per-server block in `ListRunnersResult.servers[]`. The discriminator
+ * preserves the underlying `RunnersClient.list()` outcome so a single
+ * server's `unauthorized` / `error` does NOT mask another server's data.
+ */
+type RunnerListPerServer = {
+    serverId: string;
+    serverSlug: string | null;
+    status: "ok";
+    whitelist: string[];
+    runners: RunnerListItem[];
+} | {
+    serverId: string;
+    serverSlug: string | null;
+    status: "unauthorized";
+} | {
+    serverId: string;
+    serverSlug: string | null;
+    status: "error";
+    code: string;
+};
+/**
+ * Aggregate result of `listRunners(installRoot, opts?)`. When `opts.serverId`
+ * is omitted, `servers[]` contains one block per attached server (zero
+ * blocks if the Computer has no attachments). When `opts.serverId` is set,
+ * `servers[]` contains exactly that server's block, or the call throws
+ * `StateReaderError("NOT_ATTACHED")` if the id is not attached.
+ */
+interface ListRunnersResult {
+    servers: RunnerListPerServer[];
+}
+/**
+ * Result of `readRunnerStatus(installRoot, serverId)` — per-server state
+ * row plus the runners running on it. Unauthorized / error discriminate
+ * the runners-API outcome while still surfacing the `server` row so the
+ * caller has the daemon state context.
+ */
+type RunnerStatusResult = {
+    status: "ok";
+    server: ServerStatusRow;
+    whitelist: string[];
+    runners: RunnerListItem[];
+} | {
+    status: "unauthorized";
+    server: ServerStatusRow;
+} | {
+    status: "error";
+    server: ServerStatusRow;
+    code: string;
+};
+/**
+ * State-reader error closed set. Library boundary errors only — does NOT
+ * include the CLI ambient-rule errors (`NO_ATTACHMENT` / `AMBIGUOUS_SERVER`)
+ * which are v4 §6 ergonomics handled by the CLI wrapper, not the lib
+ * primitive.
+ */
+declare const STATE_READER_ERROR_CODES: readonly ["NOT_ATTACHED", "INVALID_ATTACHMENT"];
+type StateReaderErrorCode = (typeof STATE_READER_ERROR_CODES)[number];
+/**
+ * Library-side error envelope thrown by state-readers. Lib readers
+ * NEVER call `fail()` / `process.exit` — CLI wrappers translate this to
+ * `fail(code, message)` at the boundary; D-stage IPC handlers map it to
+ * an IPC error frame.
+ */
+declare class StateReaderError extends Error {
+    readonly code: StateReaderErrorCode;
+    constructor(code: StateReaderErrorCode, message: string);
+}
+
+/**
+ * Result of `reset-service` (`slock-computer reset --service`). Clears
+ * the service-level `crashHistory` and transitions service state
+ * `degraded → running`. MUST NOT kill runners (§1.3).
  *
- *   starting  — pidfile written, socket not yet listening
- *   running   — socket listening, heartbeat active
- *   degraded  — service alive but one or more invariants violated
- *               (e.g. SERVICE_DEGRADED §7.3 crash-budget breach)
- *   stopping  — graceful shutdown in flight (SERVICE_SHUTTING_DOWN
- *               §7.3 emitted to clients)
- *   stopped   — pidfile cleared, socket closed
+ * `previousState` reports the state observed prior to the reset write —
+ * for callers that want to log/surface "was already running" vs
+ * "recovered from degraded". `clearedCrashCount` counts the entries
+ * removed from `service.state.json::crashHistory`.
  */
-declare const SERVICE_STATE_VALUES: readonly ["starting", "running", "degraded", "stopping", "stopped"];
-type ServiceState = (typeof SERVICE_STATE_VALUES)[number];
-declare function isServiceState(value: unknown): value is ServiceState;
+interface ResetServiceResult {
+    status: "ok";
+    previousState: ServiceState;
+    clearedCrashCount: number;
+}
+/**
+ * Result of `reset-runner` (`slock-computer reset --runner <slug>`).
+ * Clears the per-runner `crashHistory` and transitions runner state
+ * `degraded → running`. MUST NOT respawn or kill the runner process
+ * (§2.4).
+ *
+ * `status: "not-found"` is returned when the resolved `serverId` does
+ * not correspond to an attached server (the CLI ambient `--server` slug
+ * resolver returns its own error before the handler is invoked; this
+ * branch defends the IPC path where the caller passes a serverId
+ * directly).
+ */
+type ResetRunnerResult = {
+    status: "ok";
+    serverId: string;
+    previousState: RunnerState;
+    clearedCrashCount: number;
+} | {
+    status: "not-found";
+    serverId: string;
+};
+/**
+ * Result of `upgrade-start` (§12 phase pipeline trigger). The same
+ * pipeline is funneled by manual CLI / auto scheduler / IPC; this
+ * result describes the trigger outcome only — the per-phase events
+ * stream over `ServiceEvent` (`upgrade-log-appended` kind).
+ *
+ * `status: "already-running"` is returned when an upgrade is already
+ * in flight; `upgradeId` then refers to the in-flight upgrade so the
+ * caller can attach to its event stream instead of starting a new one.
+ */
+interface UpgradeStartResult {
+    status: "started" | "already-running";
+    upgradeId: string;
+    targetVersion: string;
+}
+/**
+ * Identity record for a legacy `@slock-ai/daemon` machine candidate that
+ * `detectLegacyMigration` discovered locally on this Computer install
+ * root. The shape is identity-only — it never carries credentials.
+ *
+ * `machineId` is the legacy daemon's lock-id (`machine-<sha256(apiKey)
+ * [0..15]>`). It is stable across legacy daemon restarts but changes if
+ * the user rotates the api key. The id is what the user would see in
+ * `<installRoot>/machines/` directory listings, and is what
+ * `AdoptLegacyService.migrate()` uses to find the lock owner file
+ * during migration.
+ *
+ * `machineName` is the host display name observed in the legacy
+ * daemon's `daemon.lock/owner.json` (typically `os.hostname()` at
+ * legacy daemon spawn time). Best-effort, may be undefined for stale
+ * lock files.
+ *
+ * `serverUrl` is the API server the legacy daemon was attached to.
+ * Used by the migrate prompt to surface "you are about to migrate
+ * machine X attached to <server>" before the user accepts.
+ */
+interface LegacyMachineCandidate {
+    machineId: string;
+    machineName?: string;
+    serverUrl?: string;
+}
+/**
+ * §X migration detection result — the discriminated union returned by
+ * `detectLegacyMigration(installRoot, loggedInUserId)`.
+ *
+ * Per RFC §X.2:
+ *   - `match`: exactly one local legacy daemon machine. The setup flow
+ *     SHOULD prompt the user to migrate before falling back to fresh
+ *     setup. Migration itself is delegated to `AdoptLegacyService.
+ *     migrate()` (preserved as internal helper per §X.6 — 11 typed
+ *     errors / 4 events / Result discriminator byte-identical).
+ *   - `no-match`: zero local legacy daemon machines. Fresh setup
+ *     proceeds without any migrate prompt.
+ *   - `ambiguous`: two or more local legacy daemon machines. Per §X.2
+ *     "no auto-listed-pick fallback" — fresh setup proceeds without
+ *     any migrate prompt; the user is expected to start the legacy
+ *     daemon they want migrated first to disambiguate.
+ *
+ * Fingerprint discipline (best-effort non-authoritative — Hao
+ * `msg=4d170194`): the candidate set is computed from local
+ * `<installRoot>/machines/machine-*` directory state. It identifies
+ * "this host has legacy daemon installs" — it does NOT prove ownership.
+ * Final adoption still walks the existing
+ * `AdoptLegacyService.migrate()` credential validation path; a match
+ * is a prompt-gate, not a trust-gate.
+ */
+/**
+ * Closed set of `MigrationDetection.kind` discriminator values. Mirrors
+ * the `IPC_ERROR_CODES` / `RUNNER_STATE_VALUES` `as const` tuple pattern
+ * so consumers can pattern-match exhaustively and so a future §7.4 CI
+ * gate can verify the runtime kind against the type union without an
+ * `as` cast (state-machine-modeling discipline — correlated/mutex
+ * properties land as a closed-set state-enum).
+ */
+declare const MIGRATION_DETECTION_KINDS: readonly ["match", "no-match", "ambiguous"];
+type MigrationDetectionKind = (typeof MIGRATION_DETECTION_KINDS)[number];
+/** Runtime narrow guard for `MigrationDetection.kind`. */
+declare function isMigrationDetectionKind(value: unknown): value is MigrationDetectionKind;
+type MigrationDetection = {
+    kind: "match";
+    machineId: string;
+    machineName?: string;
+    serverUrl?: string;
+} | {
+    kind: "no-match";
+} | {
+    kind: "ambiguous";
+    candidates: LegacyMachineCandidate[];
+};
+
+/**
+ * Detect whether `installRoot` already contains legacy
+ * `@slock-ai/daemon` machine state that could be migrated to a
+ * Computer attachment under the logged-in user.
+ *
+ * Returns a discriminated `MigrationDetection`:
+ *   - `match` (exactly one candidate) — caller SHOULD prompt the user
+ *     to migrate before fresh setup (§X.2 step 3).
+ *   - `no-match` (zero candidates) — caller proceeds with fresh
+ *     setup, NO prompt (§X.2 step 5).
+ *   - `ambiguous` (two-or-more candidates) — caller proceeds with
+ *     fresh setup, NO prompt (§X.2 step 5; "no auto-listed-pick
+ *     fallback").
+ *
+ * Lib-pure: no env reads, no terminal IO, no process.exit. Filesystem
+ * errors are swallowed and treated as "no evidence" (per the doc-
+ * block above).
+ *
+ * @param installRoot The Slock home (`SLOCK_HOME`) to scan. Resolved
+ *   by the CLI wrapper via `resolveSlockHome`.
+ * @param loggedInUserId Reserved for the server-roster intersection
+ *   (forward-compat per §X.2 step 1). v0 does not consume this value;
+ *   accept the typed argument so consumers of this function can
+ *   already pass it.
+ */
+declare function detectLegacyMigration(installRoot: string, loggedInUserId: string): Promise<MigrationDetection>;
+
+/**
+ * Read the Computer-level aggregate status from `installRoot`. Identical
+ * shape to `buildStatusReport(installRoot)` — exposed under the
+ * wire-aligned name `readServiceStatus` for IPC `service-status` parity.
+ */
+declare function readServiceStatus(installRoot: string): Promise<ServiceStatusResult>;
+/**
+ * Read a single attached server's daemon state row plus the runners
+ * currently running on it. Throws `StateReaderError("NOT_ATTACHED")` if
+ * `serverId` is not in the attached set, or `"INVALID_ATTACHMENT"` if
+ * the runner.state.json under that id is unreadable.
+ */
+declare function readRunnerStatus(installRoot: string, serverId: string): Promise<RunnerStatusResult>;
+/**
+ * List runners across attached servers. With no `serverId` filter,
+ * returns one block per attached server (zero if no attachments). With
+ * a `serverId` filter, returns exactly that server's block or throws
+ * `StateReaderError("NOT_ATTACHED")`.
+ *
+ * Per-server discriminator preserves `unauthorized` / `error` outcomes
+ * so consumers can pattern-match without losing context.
+ */
+declare function listRunners(installRoot: string, opts?: {
+    serverId?: string;
+}): Promise<ListRunnersResult>;
 
 type UpgradeTrigger = "cli" | "web" | "tray";
 /**
@@ -247,4 +551,4 @@ interface UpgradeLogEntryErr {
  */
 declare function assertUpgradeLogEntry(entry: UpgradeLogEntry): void;
 
-export { type ConnectService, type ConnectServiceOptions, IPC_ERROR_CODES, type IpcErrorCode, RUNNER_STATE_VALUES, type RequestMethodMap, type RequestOptions, type RunnerState, SERVICE_STATE_VALUES, type ServiceClient, ServiceClientError, type ServiceEvent, type ServiceState, UPGRADE_ERROR_CODES, type UpgradeBundle, type UpgradeErrorCode, type UpgradeLogEntry, type UpgradeLogEntryErr, type UpgradeLogEntryOk, type UpgradeTrigger, assertUpgradeLogEntry, isIpcErrorCode, isRunnerState, isServiceState };
+export { type ComputerStatusReport, type ConnectService, type ConnectServiceOptions, type DaemonState, IPC_ERROR_CODES, type IpcErrorCode, type LegacyMachineCandidate, type ListRunnersResult, MIGRATION_DETECTION_KINDS, type MigrationDetection, type MigrationDetectionKind, RUNNER_STATE_VALUES, type RequestMethodMap, type RequestOptions, type ResetRunnerResult, type ResetServiceResult, type RunnerListItem as RunnerInfo, type RunnerListPerServer, type RunnerState, type RunnerStatusResult, SERVICE_STATE_VALUES, STATE_READER_ERROR_CODES, type ServerHealth, type ServerStatusRow, type ServiceClient, ServiceClientError, type ServiceEvent, type ServiceState, type ServiceStatusResult, StateReaderError, type StateReaderErrorCode, UPGRADE_ERROR_CODES, type UpgradeBundle, type UpgradeErrorCode, type UpgradeLogEntry, type UpgradeLogEntryErr, type UpgradeLogEntryOk, type UpgradeStartResult, type UpgradeTrigger, assertUpgradeLogEntry, detectLegacyMigration, isIpcErrorCode, isMigrationDetectionKind, isRunnerState, isServiceState, listRunners, readRunnerStatus, readServiceStatus };