@runuai/host 0.8.45 → 0.9.0

package/README.md

@@ -18,7 +18,11 @@ One process does two things:
 ## Requirements
 
 - **Docker** (running) — tasks are containers.
-- **Node ≥ 20.**
+- **Node 22, 24, 25 or 26; Node 24 LTS recommended.** Those are the majors the
+  pinned SQLite dependency ships a prebuilt binary for. Tested release majors
+  are 22, 24 and 26; Node 25 warns and continues when the binding loads.
+  Anything else — including Node 20, 21 and 23 — has to compile from source
+  and fails on a machine without a C++ toolchain.
 
 ## Install & enroll
 

package/bin/uai-host.mjs

@@ -5,10 +5,125 @@
  * The host ships TypeScript source and runs it through tsx — no build step —
  * so every runtime path (drizzle migrations, scripts/agent/*.sh, the
  * images/standard build context) resolves off its source file exactly as in
- * dev. This shim registers tsx's ESM loader, then hands off to src/cli.ts.
- * argv passes straight through: src/cli.ts reads process.argv.slice(2).
+ * dev. This shim verifies that the native SQLite dependency can load,
+ * registers tsx's ESM loader, then hands off to src/cli.ts. argv passes
+ * straight through: src/cli.ts reads process.argv.slice(2).
  */
-import { register } from "tsx/esm/api";
 
-register();
-await import(new URL("../src/cli.ts", import.meta.url).href);
+// A builtin — importing it here loads nothing of the app and no tsx.
+import { stripVTControlCharacters } from "node:util";
+
+const minimumNodeMajor = 20;
+const testedNodeMajors = new Set([22, 24, 26]);
+const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "", 10);
+
+/**
+ * The commands that BOOT the agent, and so genuinely need the native module.
+ *
+ * Everything else — `logs`, `status`, `open`, `stop`, `uninstall`, `setup`,
+ * `--help` — only inspects or dismantles an install, and all of them were
+ * verified to run with the module unloadable. Failing them on a broken probe
+ * takes away the diagnostic path (`logs`) and the recovery path (`stop`,
+ * `uninstall`) from precisely the user the probe exists to help: they are told
+ * to reinstall, and cannot remove the wedged service first.
+ *
+ * `start`/`restart`/`install` don't open the database in THIS process — they
+ * hand off to launchd/systemd — but they all end in a running agent, so
+ * failing fast here beats a crash-looping service the user then has to chase
+ * through the log.
+ */
+const commandsNeedingNativeSqlite = new Set([
+  "run",
+  "start",
+  "restart",
+  "install",
+]);
+
+/**
+ * Of those, the ones whose `--dry-run` prints a plan and boots nothing.
+ *
+ * `run` is deliberately absent: it ignores the flag and boots regardless, so
+ * exempting on the flag alone would wave through the one command that really
+ * does need the module.
+ */
+const dryRunnableCommands = new Set(["start", "restart", "install"]);
+
+/** Whether this invocation will actually end in a running agent. */
+function needsNativeSqlite(argv) {
+  const command = argv[2] ?? "";
+  if (!commandsNeedingNativeSqlite.has(command)) return false;
+  return !(dryRunnableCommands.has(command) && argv.includes("--dry-run"));
+}
+
+function errorSummary(error) {
+  // Native loader errors can carry ANSI colour, which lands as escape noise in
+  // a log file or a non-TTY pipe. Strip it before picking the line to show.
+  const message = stripVTControlCharacters(
+    error instanceof Error ? error.message : String(error),
+  );
+  const firstLine = message
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find(Boolean);
+  if (!firstLine) return "unknown error";
+  return firstLine.length > 240 ? `${firstLine.slice(0, 237)}...` : firstLine;
+}
+
+function nativeRecoveryAdvice() {
+  return process.versions.electron
+    ? "Update or reinstall the Uai Host desktop app and retry."
+    : "Reinstall @runuai/host; if that still fails, switch to Node.js 24 LTS and reinstall.";
+}
+
+async function probeNativeSqlite() {
+  try {
+    const { default: Database } = await import("better-sqlite3");
+    const database = new Database(":memory:");
+    database.close();
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+
+async function main() {
+  if (!Number.isInteger(nodeMajor) || nodeMajor < minimumNodeMajor) {
+    console.error(
+      `uai-host requires Node.js 20 or newer; found v${process.versions.node}. Install Node.js 24 LTS and retry.`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const sqliteProbe = await probeNativeSqlite();
+  if (!sqliteProbe.ok) {
+    const detail =
+      `uai-host could not load its native SQLite module on Node.js v${process.versions.node}. ` +
+      `${nativeRecoveryAdvice()} Cause: ${errorSummary(sqliteProbe.error)}`;
+    if (needsNativeSqlite(process.argv)) {
+      console.error(detail);
+      process.exitCode = 1;
+      return;
+    }
+    // Still say it — a broken module IS why their service is down — but let
+    // the command through so they can read the log and uninstall.
+    console.warn(`${detail} Continuing — this command does not need it.`);
+  }
+
+  // Only when the probe actually succeeded — otherwise this contradicts the
+  // warning just printed, telling the user SQLite loaded right after saying it
+  // could not.
+  if (sqliteProbe.ok && !testedNodeMajors.has(nodeMajor)) {
+    console.warn(
+      `uai-host has not been tested on Node.js v${process.versions.node}; continuing because native SQLite loaded. Node.js 24 LTS is recommended.`,
+    );
+  }
+
+  // Keep this import behind the native probe: the preflight must run in plain
+  // Node before tsx (and the TypeScript application graph) is loaded.
+  const { register } = await import("tsx/esm/api");
+  register();
+  await import(new URL("../src/cli.ts", import.meta.url).href);
+}
+
+await main();

package/lib/agents/mode.ts

@@ -0,0 +1,57 @@
+/**
+ * Which agent adapters this host runs — `UAI_AGENTS`.
+ *
+ * REAL IS THE DEFAULT. It did not used to be: the check was
+ * `UAI_AGENTS === "real" ? real : mock`, so every value except that one
+ * literal — including unset — silently selected the echo mock. That was a
+ * sane default while the adapters were unproven and the only hosts were the
+ * author's, but it shipped to npm unchanged. A user installs `@runuai/host`,
+ * enrolls, starts a task, and the host looks perfectly healthy while every
+ * agent echoes canned text. Nothing in the logs or `uai-host status` said so.
+ *
+ * The desktop app never hit it because it hardcodes `UAI_AGENTS: "real"`
+ * (apps/host-desktop/src/agent-path.ts) — the npm path had no equivalent, so
+ * the bug was invisible to exactly the people who could reproduce it.
+ *
+ * So: a host runs real agents unless it is explicitly told not to. `mock` is
+ * the opt-in for tests and for dev boxes with no Docker, and an unrecognised
+ * value resolves to `real` with a warning rather than quietly downgrading —
+ * a typo must never cost someone a day of echoed output again.
+ */
+
+export type AgentMode = "real" | "mock";
+
+/** Values that select the in-process echo mock. */
+const MOCK_VALUES = new Set(["mock", "fake", "echo"]);
+/** Values that select the real Claude/Codex adapters (the default). */
+const REAL_VALUES = new Set(["real", "prod", "production"]);
+
+export interface AgentModeResolution {
+  mode: AgentMode;
+  /** Set when the raw value was neither recognised nor empty. */
+  warning?: string;
+}
+
+/**
+ * Resolve `UAI_AGENTS` to a mode. Pure and case/whitespace insensitive so a
+ * stray `UAI_AGENTS=Mock ` from a hand-edited .env.local behaves as written.
+ */
+export function resolveAgentMode(
+  raw: string | undefined = process.env.UAI_AGENTS,
+): AgentModeResolution {
+  const value = (raw ?? "").trim().toLowerCase();
+  if (value === "") return { mode: "real" };
+  if (MOCK_VALUES.has(value)) return { mode: "mock" };
+  if (REAL_VALUES.has(value)) return { mode: "real" };
+  return {
+    mode: "real",
+    warning:
+      `unrecognised UAI_AGENTS=${JSON.stringify(raw)} — running REAL agents. ` +
+      `Use "mock" for the echo agent, or unset it.`,
+  };
+}
+
+/** The mode this process is running in. */
+export function agentMode(): AgentMode {
+  return resolveAgentMode().mode;
+}

package/lib/mcp-connections.ts

@@ -98,6 +98,51 @@ async function mcpInitialize(
   });
 }
 
+/** Collapse whitespace and cap length — this text lands in the connect dialog. */
+function oneLine(s: string, max = 300): string {
+  const flat = s.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+/**
+ * The vendor's own explanation for a failed response, so the connect dialog
+ * can show it instead of a bare status code. Vendors bury it in one of a few
+ * shapes — RFC 6750's `error_description`, a bare `error`/`message`, or a
+ * GraphQL-style `errors[]` — so try each, then fall back to the raw body.
+ * Never throws: a missing or unparseable body just means no reason to add.
+ */
+async function failureReason(res: Response): Promise<string | null> {
+  const text = await res.text().catch(() => "");
+  if (!text.trim()) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return oneLine(text);
+  }
+  const body = (parsed ?? {}) as Record<string, unknown>;
+  const errors = body.errors;
+  const first = Array.isArray(errors)
+    ? (errors[0] as Record<string, unknown> | undefined)
+    : undefined;
+  // `error` is a string in some payloads and an object wrapping `message` in
+  // others — New Relic alone returns both shapes plus `errors[]`, depending
+  // on which of its tiers answers. Prefer the descriptive fields; the bare
+  // `error` string ("unauthorized") is the last resort.
+  const nested =
+    typeof body.error === "object" && body.error !== null
+      ? (body.error as Record<string, unknown>)
+      : undefined;
+  const reason = [
+    body.error_description,
+    body.message,
+    first?.message,
+    nested?.message,
+    body.error,
+  ].find((c): c is string => typeof c === "string" && c.trim().length > 0);
+  return oneLine(reason ?? text);
+}
+
 // --- OAuth discovery (RFC 9728 → RFC 8414) -----------------------------------
 
 /** Candidate well-known URLs, path-aware per spec, root fallback last. */
@@ -249,9 +294,25 @@ async function probe(op: Extract<McpOp, { kind: "probe" }>): Promise<McpAck> {
     const header = { headerName: op.headerName, headerValue: op.headerValue };
     const res = await mcpInitialize(op.url, header);
     if (res.status === 401 || res.status === 403) {
-      throw new Error(`the server rejected the token (${res.status})`);
+      // 401 and 403 send you to different fixes, so don't collapse them into
+      // one "rejected" message. 401 is a credential the server did not
+      // recognise — re-check the key. 403 is one it DID recognise and then
+      // refused: the key is fine, but its user lacks permission or the
+      // account is not entitled to this server. Telling someone to re-paste
+      // a working key is the expensive failure here.
+      const lead =
+        res.status === 401
+          ? "the server rejected the token (401)"
+          : "the token was accepted but this server refused the request " +
+            "(403) — the key is likely valid but lacks permission for it";
+      const why = await failureReason(res);
+      throw new Error(why ? `${lead}: ${why}` : lead);
+    }
+    if (!res.ok) {
+      const why = await failureReason(res);
+      const lead = `unexpected response (${res.status})`;
+      throw new Error(why ? `${lead}: ${why}` : lead);
     }
-    if (!res.ok) throw new Error(`unexpected response (${res.status})`);
     db.insert(schema.mcpConnections)
       .values({
         id: op.connectionId,

package/lib/orchestrator.ts

@@ -25,6 +25,7 @@ import { inArray } from "drizzle-orm";
 import { getDb, schema } from "./db";
 import { mockAgentFactory } from "./agents/mock";
 import { realAgentFactory } from "./agents/factory";
+import { resolveAgentMode } from "./agents/mode";
 import {
   type AgentEvent,
   type AgentSession,
@@ -2636,11 +2637,20 @@ const globalForOrchestrator = globalThis as unknown as {
 
 export function getOrchestrator(): Orchestrator {
   if (!globalForOrchestrator.__uaiOrchestrator) {
-    // `UAI_AGENTS=real` drives the real Claude/Codex CLIs inside the
-    // task containers; anything else uses the mock (no Docker / no CLI
-    // needed — the default until the adapters are verified on a host).
-    const factory =
-      process.env.UAI_AGENTS === "real" ? realAgentFactory : mockAgentFactory;
+    // Real Claude/Codex CLIs inside the task containers unless `UAI_AGENTS`
+    // explicitly asks for the echo mock (see ./agents/mode). Mock is loud —
+    // a host that answers every prompt with canned text has to say so, or it
+    // reads as a working host producing nonsense.
+    const { mode, warning } = resolveAgentMode();
+    if (warning) console.warn(`[host-agent] ${warning}`);
+    if (mode === "mock") {
+      console.warn(
+        "[host-agent] ⚠ MOCK AGENTS — every agent echoes canned text and no " +
+          "real CLI runs. Unset UAI_AGENTS (or set it to `real`) for a host " +
+          "that does actual work.",
+      );
+    }
+    const factory = mode === "real" ? realAgentFactory : mockAgentFactory;
     globalForOrchestrator.__uaiOrchestrator = new Orchestrator(factory);
   }
   if (!globalForOrchestrator.__uaiRecoverRan) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.8.45",
+  "version": "0.9.0",
   "description": "Uai host — runs ephemeral AI coding tasks in Docker on a machine you control.",
   "license": "MIT",
   "author": "Diogo Perillo <diogo.perillo@gmail.com>",
@@ -28,7 +28,7 @@
     "uai-host": "./bin/uai-host.mjs"
   },
   "engines": {
-    "node": ">=20"
+    "node": "22.x || >=24 <27"
   },
   "publishConfig": {
     "access": "public"
@@ -67,7 +67,7 @@
   },
   "dependencies": {
     "@sentry/node": "^10.66.0",
-    "better-sqlite3": "^11.3.0",
+    "better-sqlite3": "12.11.1",
     "dotenv": "^16.4.5",
     "drizzle-orm": "^0.36.0",
     "tsx": "^4.19.2",

package/src/cli.ts

@@ -134,6 +134,13 @@ async function cmdStatus(): Promise<void> {
   );
   if (cloud.lastError) console.log(`           ${dim("last error: " + cloud.lastError)}`);
   console.log(`  service  ${dim(`pid ${status.pid} · up ${fmtDuration(status.uptime * 1000)}`)}`);
+  // Only worth a line when it's the surprising answer. A mock host looks
+  // identical to a real one everywhere else — connected, tasks running, output
+  // streaming — so this is the only place it can be caught before the work is.
+  if (status.agentMode === "mock") {
+    console.log(`  agents   ${yellow("mock")} ${dim("— echo only, no real CLI runs")}`);
+    console.log(`           ${dim("unset UAI_AGENTS in " + envLocalPath() + ", then: uai-host restart")}`);
+  }
   console.log(`  ui       ${dim(`http://127.0.0.1:${port}`)}`);
   console.log(`  log      ${dim(status.logPath)}`);
   console.log(`  tasks    ${tasks.tasks.length === 0 ? dim("none") : tasks.tasks.length}`);

package/src/ui/server.ts

@@ -23,6 +23,7 @@ import { join } from "node:path";
 import { desc, isNull } from "drizzle-orm";
 import type { ZodType } from "zod";
 
+import { agentMode } from "../../lib/agents/mode";
 import { schema, type Db } from "../../lib/db";
 import { parsePreviewPortRuntimes } from "../../lib/preview-ports";
 import { getCloudState } from "../../lib/cloud-state";
@@ -186,6 +187,7 @@ async function handle(
           cloudUrl: opts.cloudUrl,
           hostName: hostname(),
           hostId: opts.hostId,
+          agentMode: agentMode(),
         });
       case "/api/cloud":
         return sendJson(res, CloudResponse, getCloudState());

package/src/ui/types.ts

@@ -17,6 +17,11 @@ export const StatusResponse = z.object({
   cloudUrl: z.string(), // UAI_CLOUD_URL
   hostName: z.string(), // os.hostname()
   hostId: z.string(), // UAI_HOST_ID
+  // Which agent adapters this host runs (UAI_AGENTS). Optional: a newer CLI
+  // can query a service that is still on the pre-upgrade build, which had no
+  // such field — `npm i -g` swaps the CLI before `uai-host restart` swaps the
+  // service, so that window is normal, not exotic.
+  agentMode: z.enum(["real", "mock"]).optional(),
 });
 export type StatusResponse = z.infer<typeof StatusResponse>;