@moondeck/station 0.0.1 → 1.0.1

package/src/runtime-bootstrap.ts

@@ -0,0 +1,165 @@
+/** ADR-106 boot wiring kept side-effect free and directly testable. */
+
+import {
+  appleContainerRuntimeBinding,
+  containerRuntimeMachineIdentity,
+  rejectContainerRuntimeSelection,
+  reprobeContainerRuntimeMachineIdentity,
+  setAppleContainerRuntime,
+  setAppleContainerSelectionGuard,
+  type AppleRuntimeBinding,
+} from "../lib/container-runtime";
+import {
+  resolveBundledRuntimeFromEnvironment,
+  type ResolvedBundledRuntime,
+} from "../lib/managed-runtime";
+import {
+  adoptLegacyTaskEnvironments,
+  hostTaskEnvironmentsAllowMachineSelection,
+  hostTaskEnvironmentsMatchMachine,
+  setAppleContainerBinding,
+  type HostMachineIdentity,
+  type LegacyTaskEnvironmentAdoptionVerdict,
+  type TaskEnvironmentBackendVerdict,
+} from "../lib/task-environment";
+
+export interface RuntimeBootstrapDeps {
+  readonly resolveRuntime?: () => Promise<ResolvedBundledRuntime | null>;
+  readonly registerRuntime?: (binding: AppleRuntimeBinding | null) => void;
+  readonly registerSelectionGuard?: (
+    guard: ((endpoint: string) => boolean | Promise<boolean>) | null,
+  ) => void;
+  readonly allowMachineSelection?: (machine: {
+    backend: "apple-container";
+    endpoint: string;
+  }) => TaskEnvironmentBackendVerdict;
+}
+
+/**
+ * Register the bundled Apple container toolchain from the active signed
+ * generation, if one exists (ADR-106). Registration is fail-closed: seams are
+ * cleared first so a thrown validation cannot leave a stale binding, and the
+ * selection guard keeps `auto` off the bundled runtime while durable task
+ * rows still belong to another backend. An unmanaged checkout, Linux archive,
+ * or rolling v1 generation registers nothing; there is deliberately no PATH
+ * or inferred-layout fallback.
+ */
+export async function configureBundledContainerRuntime(
+  deps: RuntimeBootstrapDeps = {},
+): Promise<ResolvedBundledRuntime | null> {
+  const registerRuntime = deps.registerRuntime ?? setAppleContainerRuntime;
+  const registerGuard =
+    deps.registerSelectionGuard ?? setAppleContainerSelectionGuard;
+  registerRuntime(null);
+  registerGuard(null);
+
+  const bundled = await (
+    deps.resolveRuntime ?? resolveBundledRuntimeFromEnvironment
+  )();
+  if (bundled === null) return null;
+
+  const allowSelection =
+    deps.allowMachineSelection ?? hostTaskEnvironmentsAllowMachineSelection;
+  registerGuard(
+    (endpoint) =>
+      allowSelection({ backend: "apple-container", endpoint }).ok,
+  );
+  registerRuntime({
+    containerCliPath: bundled.containerCliPath,
+    kernelPath: bundled.kernelPath,
+  });
+  return bundled;
+}
+
+export interface RuntimeCompatibilityDeps {
+  readonly machineIdentity?: () => HostMachineIdentity | null;
+  readonly matchMachine?: (
+    machine: HostMachineIdentity,
+  ) => TaskEnvironmentBackendVerdict;
+  readonly adoptLegacy?: (
+    machine: HostMachineIdentity,
+  ) => Promise<LegacyTaskEnvironmentAdoptionVerdict>;
+  readonly reprobeRuntime?: () => Promise<HostMachineIdentity | null>;
+  readonly rejectSelection?: (message: string, action?: string) => void;
+}
+
+/**
+ * Final database-backed fence before maintenance/recovery touches a selected
+ * daemon. A missing exact endpoint and every malformed/newer/mismatched task
+ * locator are quarantines, never retry hints against the current machine.
+ */
+export async function selectedRuntimeMatchesPersistedTaskEnvironments(
+  deps: RuntimeCompatibilityDeps = {},
+): Promise<boolean> {
+  const reject = deps.rejectSelection ?? rejectContainerRuntimeSelection;
+  const machine = (
+    deps.machineIdentity ?? containerRuntimeMachineIdentity
+  )();
+  if (machine === null) {
+    reject(
+      "The selected container runtime has no durable local machine identity.",
+    );
+    return false;
+  }
+  const reprobe =
+    deps.reprobeRuntime ?? reprobeContainerRuntimeMachineIdentity;
+  const liveMachine = await reprobe();
+  if (
+    liveMachine === null ||
+    liveMachine.backend !== machine.backend ||
+    liveMachine.endpoint !== machine.endpoint ||
+    liveMachine.engineId !== machine.engineId
+  ) {
+    reject(
+      "The selected container runtime daemon identity changed during validation.",
+    );
+    return false;
+  }
+  // Legacy compose rows can only ever be adopted by a Docker daemon; any
+  // other active backend makes the candidate check inside adoption fail
+  // closed with its repair guidance, so the machine is narrowed lazily.
+  // Bind (or unbind) the Apple provider to the proven identity before any
+  // maintenance can reconstruct a task environment. The binding carries the
+  // exact machine the fence just re-probed, so provider reconstruction and
+  // this admission decision can never disagree about identity.
+  if (deps.machineIdentity === undefined) {
+    const binding = appleContainerRuntimeBinding();
+    if (machine.backend === "apple-container" && binding !== null) {
+      const appleMachine = {
+        backend: "apple-container" as const,
+        endpoint: machine.endpoint,
+        engineId: machine.engineId,
+      };
+      setAppleContainerBinding({
+        containerCliPath: () => binding.containerCliPath,
+        machineIdentity: () => appleMachine,
+      });
+    } else {
+      setAppleContainerBinding(null);
+    }
+  }
+
+  const adoption = await (
+    deps.adoptLegacy ??
+    ((selected: HostMachineIdentity) =>
+      adoptLegacyTaskEnvironments(selected, {
+        reprobeMachine: reprobe,
+      }))
+  )(machine);
+  if (!adoption.ok) {
+    reject(
+      "Moondeck Station could not safely adopt persisted legacy task resources" +
+        (adoption.detail ? `: ${adoption.detail}` : "."),
+    );
+    return false;
+  }
+  const verdict = (
+    deps.matchMachine ?? hostTaskEnvironmentsMatchMachine
+  )(machine);
+  if (verdict.ok) return true;
+  reject(
+    "The selected container runtime does not match persisted task environments" +
+      (verdict.detail ? `: ${verdict.detail}` : "."),
+  );
+  return false;
+}

package/src/station-identity.ts

@@ -0,0 +1,96 @@
+/**
+ * Every name a Moondeck Station puts on a machine, and the names the frozen
+ * `@runuai/host` used for the same things (Moondeck migration plan §4).
+ *
+ * A station is a fresh install beside, then instead of, the old host: it
+ * never reads, writes or stops anything under a legacy name, except in
+ * `moondeck-station uninstall-legacy` and the refuse-if-old-running check,
+ * which use LEGACY_HOST and nothing else does. Two hosts sharing one of these
+ * names would stop each other's service or delete each other's runtime.
+ *
+ * Not renamed, on purpose: `UAI_*` environment names (plan §2), the token
+ * prefixes, the wire protocol, and the runtime archive's internal layout
+ * (`current/bin/uai-host`, `agent/bin/uai-host.mjs`), which the archive
+ * verifiers pin and which only ever sit under the station's own runtime root.
+ */
+
+export interface HostIdentity {
+  /** npm package name. */
+  readonly packageName: string;
+  /** The command on PATH (npm bin and the managed shim in ~/.local/bin). */
+  readonly command: string;
+  /** The managed runtime's recovery command, also shimmed into ~/.local/bin. */
+  readonly recoveryCommand: string;
+  /** `~/<this>`: `.env.local`, the data dir and task workspaces. */
+  readonly homeDirName: string;
+  /** `~/<this>`: the managed runtime root, and the prefix of its lock files. */
+  readonly runtimeDirName: string;
+  /** launchd LaunchAgent label (macOS). */
+  readonly launchdLabel: string;
+  /** launchd LaunchDaemon label of the root-owned `tune` helper (macOS). */
+  readonly tuneDaemonLabel: string;
+  /** systemd user unit (Linux). */
+  readonly systemdUnit: string;
+  /** Folder under ~/Library/Logs (macOS) and %LOCALAPPDATA% (Windows). */
+  readonly logDirName: string;
+  /** Service log file name inside it. */
+  readonly logFileName: string;
+  /** Human name in service descriptions. */
+  readonly displayName: string;
+}
+
+export const STATION: HostIdentity = Object.freeze({
+  packageName: "@moondeck/station",
+  command: "moondeck-station",
+  recoveryCommand: "moondeck-station-recover",
+  homeDirName: ".moondeck",
+  runtimeDirName: ".moondeck-station",
+  launchdLabel: "io.moondeck.station",
+  tuneDaemonLabel: "io.moondeck.tune",
+  systemdUnit: "moondeck-station.service",
+  logDirName: "Moondeck",
+  logFileName: "station.log",
+  displayName: "Moondeck Station",
+});
+
+/** The frozen `@runuai/host` (0.9.x). Read only by uninstall-legacy and the old-host check. */
+export const LEGACY_HOST: HostIdentity = Object.freeze({
+  packageName: "@runuai/host",
+  command: "uai-host",
+  recoveryCommand: "uai-host-recover",
+  homeDirName: ".uai",
+  runtimeDirName: ".uai-host",
+  launchdLabel: "com.runuai.host",
+  tuneDaemonLabel: "com.runuai.tune",
+  systemdUnit: "uai-host.service",
+  logDirName: "Uai",
+  logFileName: "host.log",
+  displayName: "Uai host",
+});
+
+/**
+ * Where a station connects and calls when nothing else is configured. Both
+ * hosts must serve and be verified before station 1.0 ships (plan §3.1).
+ */
+export const STATION_DEFAULT_CLOUD_URL = "wss://app.moondeck.io/host";
+export const STATION_DEFAULT_GATEWAY_URL = "https://inference.moondeck.io";
+export const STATION_INSTALLER_URL = "https://app.moondeck.io/install";
+
+/**
+ * What a station's task containers have (Moondeck plan §5 row 7), and so what
+ * the cloud tells their agents once the station advertises
+ * AGENT_CLI_MOONDECK_PROTOCOL_FEATURE. Must equal the cloud's
+ * STATION_AGENT_CLI (lib/agent-cli-profile.ts, #708). The frozen host has
+ * `.uai/`, `uai.json` and the `uai-ask` fence; a station has none of them.
+ * `UAI_*` environment names and the `uai/<taskId>/<name>` branch namespace
+ * stay on both.
+ */
+export const STATION_AGENT_CLI = Object.freeze({
+  command: "moondeck",
+  stateDir: ".moondeck",
+  cliPath: "/workspace/.moondeck/cli.mjs",
+  configFile: "moondeck.json",
+  askFence: "moondeck-ask",
+  productName: "Moondeck",
+});
+

package/src/task-env-names.ts

@@ -0,0 +1,28 @@
+import { ENGINE_ENV_CREDENTIAL_KEYS } from "./cloud-credentials";
+
+const RESERVED_TASK_ENV_EXACT = new Set([
+  "GH_TOKEN", "GITHUB_TOKEN", "GH_CONFIG_DIR", "GH_HOST",
+  "GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR", "GIT_OBJECT_DIRECTORY",
+  "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_INDEX_FILE", "GIT_EXEC_PATH",
+  "GIT_ASKPASS", "SSH_ASKPASS", "GIT_SSH", "GIT_SSH_COMMAND",
+  "HOME", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_CACHE_HOME",
+  "PATH", "LD_PRELOAD", "LD_AUDIT", "LD_LIBRARY_PATH", "NODE_OPTIONS",
+  "NODE_PATH", "SHELL", "SHELLOPTS", "BASHOPTS", "PS4", "BASH_ENV", "ENV",
+  "NODE_EXTRA_CA_CERTS", "SSL_CERT_FILE", "REQUESTS_CA_BUNDLE",
+  "__CURSOR_SANDBOX_ENV_RESTORE", "GROK_LOGIN_ENV",
+  // Every name an env-token engine's account may set (ADR-154's contract):
+  // a project value never stands in for an engine's credential.
+  ...Object.values(ENGINE_ENV_CREDENTIAL_KEYS).flat(),
+  "PLAYWRIGHT_BROWSERS_PATH",
+]);
+const RESERVED_TASK_ENV_NPM = /^npm_config_(prefix|cache|logs[_-]dir|umask)$/i;
+/** Toolchain prefixes, in any case, as task-up.sh matches them. */
+const RESERVED_TASK_ENV_TOOLCHAIN = /^(asdf|corepack)_/i;
+
+export function isReservedTaskEnvName(name: string): boolean {
+  if (RESERVED_TASK_ENV_EXACT.has(name)) return true;
+  if (name.startsWith("GIT_CONFIG") || RESERVED_TASK_ENV_TOOLCHAIN.test(name)) return true;
+  if (name.startsWith("UAI_")) return true;
+  if (name.startsWith("__UAI_ENV_")) return true;
+  return RESERVED_TASK_ENV_NPM.test(name);
+}

package/src/task-secrets.ts

@@ -0,0 +1,75 @@
+/** ADR-161 §5: value-free task-secret wire contract. No I/O. */
+export const TASK_SECRETS_FEATURE = "task-secrets-v1";
+export const MAX_TASK_SECRETS = 20;
+export const TASK_SECRET_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+export const TASK_SECRET_STAGING_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export interface TaskSecretManifestEntry {
+  credentialId: string;
+  name: string;
+  stagingId: string;
+  generation: number;
+  parameter: string;
+  version: number;
+  mode: "proxied" | "delivered";
+  domains: string[];
+  placeholder: { prefix: string; totalLength: number } | null;
+  sessionId: string;
+}
+export interface TaskSecretStagingPut {
+  kind: "task.secret.staging.put";
+  opId: string;
+  orgId: string;
+  taskId: string;
+  name: string;
+  stagingId: string;
+  value: string;
+}
+export interface TaskSecretStagingAck {
+  kind: "task.secret.staging.ack";
+  opId: string;
+  stagingId: string;
+  ok: boolean;
+}
+const ID = /^[A-Za-z0-9_-]{1,128}$/;
+export function isTaskSecretStagingPut(value: unknown): value is TaskSecretStagingPut {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const o = value as Record<string, unknown>;
+  return Object.keys(o).length === 7 && o.kind === "task.secret.staging.put" &&
+    [o.opId, o.orgId, o.taskId].every(v => typeof v === "string" && ID.test(v)) &&
+    typeof o.name === "string" && TASK_SECRET_NAME.test(o.name) &&
+    typeof o.stagingId === "string" && TASK_SECRET_STAGING_ID.test(o.stagingId) &&
+    typeof o.value === "string" && o.value.length > 0 && !o.value.includes("\0") &&
+    new TextEncoder().encode(JSON.stringify({ v: 1, kind: "task-secret", orgId: o.orgId, taskId: o.taskId, name: o.name, stagingId: o.stagingId, value: o.value })).byteLength <= 4096;
+}
+export function isTaskSecretStagingAck(value: unknown): value is TaskSecretStagingAck {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const o = value as Record<string, unknown>;
+  return Object.keys(o).length === 4 && o.kind === "task.secret.staging.ack" && typeof o.opId === "string" && ID.test(o.opId) &&
+    typeof o.stagingId === "string" && TASK_SECRET_STAGING_ID.test(o.stagingId) && typeof o.ok === "boolean";
+}
+export interface TaskSecretMaterial {
+  class: "task-secret";
+  location: { orgId: string; taskId: string; name: string; stagingId: string };
+  value: string;
+}
+/** Compare every envelope identity; no provider text is included in errors. */
+export function parseTaskSecretMaterial(raw: string, expected: TaskSecretMaterial["location"]): TaskSecretMaterial | null {
+  try {
+    if (new TextEncoder().encode(raw).byteLength > 4096) return null;
+    const o = JSON.parse(raw) as Record<string, unknown>;
+    if (!o || Object.keys(o).length !== 7 || o.v !== 1 || o.kind !== "task-secret" ||
+      o.orgId !== expected.orgId || o.taskId !== expected.taskId || o.name !== expected.name || o.stagingId !== expected.stagingId ||
+      typeof o.value !== "string" || !o.value.length || o.value.includes("\0")) return null;
+    return { class: "task-secret", location: { ...expected }, value: o.value };
+  } catch { return null; }
+}
+
+/** Sent only after the lease's consumers have opened on the exact new view. */
+export interface TaskSecretApplied { kind: "task.secret.applied"; taskId: string; runEpoch: number; manifestRevision: number; manifestDigest: string }
+export function isTaskSecretApplied(value: unknown): value is TaskSecretApplied {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const o = value as Record<string, unknown>;
+  return Object.keys(o).length === 5 && o.kind === "task.secret.applied" && typeof o.taskId === "string" && ID.test(o.taskId) &&
+    typeof o.runEpoch === "number" && Number.isSafeInteger(o.runEpoch) && o.runEpoch > 0 &&
+    typeof o.manifestRevision === "number" && Number.isSafeInteger(o.manifestRevision) && o.manifestRevision > 0 && typeof o.manifestDigest === "string" && /^[0-9a-f]{64}$/.test(o.manifestDigest);
+}

package/src/tunnel-dial.ts

@@ -0,0 +1,102 @@
+/**
+ * Connect-phase timeout for tunnel upstream dials to a memoised address.
+ *
+ * An ADR-121 machine task's `{host, port}` comes from a 45 s memo
+ * (`machine-tunnel-route.ts`) that is dropped when a dial fails. A machine
+ * stopped or terminated while its address is memoised does not refuse the
+ * dial — it black-holes it: no SYN answer, so neither `connect` nor `error`
+ * fires until the kernel gives up on retransmits (~75 s macOS, ~127 s Linux).
+ * The memo's failure-driven invalidation never runs in that window and the
+ * pane or editor hangs on every open. An in-region machine answers a SYN in
+ * milliseconds, the cloud waits 30 s for the ack (`TUNNEL_ACK_TIMEOUT_MS`)
+ * and the forward hop 45 s for the head, so a 10 s connect bound is generous
+ * to a live machine and well inside what the caller will still accept.
+ *
+ * Only the connect phase is timed: the deadline is armed while the socket is
+ * `connecting` and disarmed by `connect` (or by the dial failing on its own).
+ * It is NOT an idle timeout — a quiet VNC/SSE/code-server stream after the
+ * handshake must live forever (see the tunnel rules in docs/agent-notes.md).
+ * A timeout destroys the socket with an error carrying `code = "ETIMEDOUT"`
+ * and `syscall = "connect"`, so the dial path's existing `'error'` handler
+ * runs unchanged: it acks the cloud with the same 502 shape as any other
+ * dial failure and invalidates the machine route memo.
+ */
+
+export interface DialTarget {
+  readonly host: string;
+  readonly port: number;
+}
+
+/** The slice of `net.Socket` the timeout needs; tests pass a fake. */
+export interface DialSocket {
+  /** True from `connect()` until the handshake completes. False on a socket
+   * handed over already connected (an agent's reused keep-alive socket, an
+   * ADR-106 pre-established apple route) — those are never armed. */
+  readonly connecting: boolean;
+  once(event: "connect" | "error" | "close", listener: () => void): unknown;
+  destroy(error?: Error): unknown;
+}
+
+export interface DialTimers {
+  setTimeout(callback: () => void, delayMs: number): NodeJS.Timeout;
+  clearTimeout(timer: NodeJS.Timeout): void;
+}
+
+export const CONNECT_TIMEOUT_ERROR_CODE = "ETIMEDOUT" as const;
+
+export interface ConnectTimeoutError extends Error {
+  readonly code: typeof CONNECT_TIMEOUT_ERROR_CODE;
+  readonly syscall: "connect";
+  readonly address: string;
+  readonly port: number;
+}
+
+export function connectTimeoutError(
+  target: DialTarget,
+  timeoutMs: number,
+): ConnectTimeoutError {
+  return Object.assign(
+    new Error(
+      `connect ETIMEDOUT ${target.host}:${target.port} (no answer within ${timeoutMs} ms)`,
+    ),
+    {
+      code: CONNECT_TIMEOUT_ERROR_CODE,
+      syscall: "connect" as const,
+      address: target.host,
+      port: target.port,
+    },
+  );
+}
+
+export function isConnectTimeoutError(error: unknown): error is ConnectTimeoutError {
+  return (
+    error instanceof Error &&
+    (error as Partial<ConnectTimeoutError>).code === CONNECT_TIMEOUT_ERROR_CODE &&
+    (error as Partial<ConnectTimeoutError>).syscall === "connect"
+  );
+}
+
+/**
+ * Arm a connect deadline on a socket that has started (or is about to be
+ * handed a started) connect. Returns whether a deadline was armed — false for
+ * a socket that is already connected, which has nothing to time.
+ */
+export function armConnectTimeout(
+  socket: DialSocket,
+  target: DialTarget,
+  timeoutMs: number,
+  timers: DialTimers = { setTimeout, clearTimeout },
+): boolean {
+  if (!socket.connecting) return false;
+  const deadline = timers.setTimeout(() => {
+    socket.destroy(connectTimeoutError(target, timeoutMs));
+  }, timeoutMs);
+  deadline.unref?.();
+  const disarm = (): void => {
+    timers.clearTimeout(deadline);
+  };
+  socket.once("connect", disarm);
+  socket.once("error", disarm);
+  socket.once("close", disarm);
+  return true;
+}