@runuai/host 0.8.44 → 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/lib/tunnel-registry.ts

@@ -0,0 +1,104 @@
+/**
+ * Tunnel upstreams, plus the frames that arrive before an upstream exists.
+ *
+ * `tunnel.open` is handled ASYNCHRONOUSLY on the host: resolving a target can
+ * await the task lifecycle lock and, for an ad-hoc preview, `docker run` of a
+ * sidecar (ADR-043). The frames that follow it — `tunnel.data`,
+ * `tunnel.requestEnd`, `tunnel.close` — are handled synchronously off the same
+ * WebSocket, and the cloud emits `requestEnd` for a bodyless GET on the tick
+ * after `open`. So they routinely land while the open is still resolving.
+ *
+ * Looking the tunnel up with `tunnels.get(id)?.` silently dropped them, and a
+ * dropped `requestEnd` is unrecoverable rather than merely late. The HTTP open
+ * deliberately leaves its `ClientRequest` unended so request bodies can stream,
+ * and node writes no header until `write`/`end` — so the upstream socket
+ * CONNECTS and then receives nothing at all. On the wire that reads as an
+ * established TCP connection carrying zero bytes, an upstream that never saw a
+ * request, and a flat 30s `504 host did not respond in time` from the cloud's
+ * ack deadline: four symptoms that each point somewhere different, none of them
+ * at the open that never finished.
+ *
+ * So ops for an opening tunnel are QUEUED and replayed on `register`. The
+ * queue is bounded by the request itself — the cloud stops sending once its
+ * ack deadline fires — and is dropped by `abandon` when an open fails, so a
+ * tunnel that never opens leaves nothing behind.
+ */
+
+export interface TunnelUpstream {
+  write(chunk: Buffer): boolean;
+  end(): void;
+  destroy(): void;
+}
+
+type TunnelOp = (upstream: TunnelUpstream) => void;
+
+export class TunnelRegistry {
+  private readonly open = new Map<string, TunnelUpstream>();
+  /** tunnelId -> ops that arrived while its `tunnel.open` was still resolving. */
+  private readonly opening = new Map<string, TunnelOp[]>();
+
+  /**
+   * Mark a tunnel as opening. MUST be called synchronously when `tunnel.open`
+   * is received — before the first `await` of target resolution — or the frames
+   * that follow have nothing to queue against and are dropped, which is the
+   * whole bug this class exists for.
+   */
+  markOpening(tunnelId: string): void {
+    this.opening.set(tunnelId, []);
+  }
+
+  /** Target resolved: publish the upstream and replay what arrived meanwhile. */
+  register(tunnelId: string, upstream: TunnelUpstream): void {
+    this.open.set(tunnelId, upstream);
+    const queued = this.opening.get(tunnelId);
+    this.opening.delete(tunnelId);
+    if (!queued) return;
+    for (const op of queued) op(upstream);
+  }
+
+  /** Open failed (no target, or it errored) — nothing will ever service these. */
+  abandon(tunnelId: string): void {
+    this.opening.delete(tunnelId);
+  }
+
+  get(tunnelId: string): TunnelUpstream | undefined {
+    return this.open.get(tunnelId);
+  }
+
+  delete(tunnelId: string): void {
+    this.open.delete(tunnelId);
+  }
+
+  /**
+   * Run `op` against the upstream now, or queue it if the tunnel is still
+   * opening. A tunnel this registry has never heard of is dropped, exactly as
+   * the old `?.` did — that is a frame for a tunnel already torn down, not a
+   * race.
+   */
+  apply(tunnelId: string, op: TunnelOp): void {
+    const upstream = this.open.get(tunnelId);
+    if (upstream) {
+      op(upstream);
+      return;
+    }
+    this.opening.get(tunnelId)?.push(op);
+  }
+
+  /**
+   * Tear the tunnel down now, or as soon as it opens. Queued ops are discarded
+   * rather than replayed first: they exist to be written to an upstream that is
+   * about to be destroyed, and a `write` after `destroy` is at best wasted and
+   * at worst an unhandled error on a socket nobody is listening to any more.
+   */
+  abort(tunnelId: string): void {
+    const upstream = this.open.get(tunnelId);
+    this.open.delete(tunnelId);
+    if (upstream) {
+      upstream.destroy();
+      return;
+    }
+    if (this.opening.has(tunnelId)) {
+      this.opening.set(tunnelId, [(u) => u.destroy()]);
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.8.44",
+  "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/main.ts

@@ -59,6 +59,7 @@ import {
   ensurePreviewSidecar,
   invalidatePreviewSidecar,
 } from "../lib/preview-sidecar";
+import { TunnelRegistry } from "../lib/tunnel-registry";
 import { newId } from "../lib/ulid";
 import {
   capabilities as agentKindCapabilities,
@@ -126,13 +127,7 @@ let reconnectAttempt = 0;
 let inFlight = 0;
 let shutdownRequested = false;
 let pendingBinaryTunnelId: string | null = null;
-const tunnels = new Map<string, TunnelUpstream>();
-
-interface TunnelUpstream {
-  write(chunk: Buffer): boolean;
-  end(): void;
-  destroy(): void;
-}
+const tunnels = new TunnelRegistry();
 
 interface PausableSource {
   pause(): unknown;
@@ -301,7 +296,8 @@ function connect(): void {
       const tunnelId = pendingBinaryTunnelId;
       pendingBinaryTunnelId = null;
       if (!tunnelId) return;
-      tunnels.get(tunnelId)?.write(rawDataToBuffer(data));
+      const chunk = rawDataToBuffer(data);
+      tunnels.apply(tunnelId, (upstream) => upstream.write(chunk));
       return;
     }
 
@@ -315,6 +311,10 @@ function connect(): void {
         void handleCommand(socket, frame);
         break;
       case "tunnel.open":
+        // Synchronously, BEFORE handleTunnelOpen's first await: the frames that
+        // follow this one (a bodyless GET's `requestEnd` arrives on the next
+        // tick) need somewhere to queue while the target resolves.
+        tunnels.markOpening(frame.tunnelId);
         void handleTunnelOpen(socket, frame);
         break;
       case "tunnel.data":
@@ -322,7 +322,10 @@ function connect(): void {
         break;
       case "tunnel.requestEnd":
         // Request body complete → finish the upstream request so it can reply.
-        tunnels.get(frame.tunnelId)?.end();
+        // Queued if the open is still resolving: node flushes no request header
+        // until `end`, so losing this strands the upstream on a connected
+        // socket that never receives a byte.
+        tunnels.apply(frame.tunnelId, (upstream) => upstream.end());
         break;
       case "tunnel.close":
         closeTunnel(socket, frame.tunnelId, frame.reason);
@@ -497,6 +500,8 @@ async function handleTunnelOpen(
 ): Promise<void> {
   const target = await resolveTunnelTarget(frame);
   if (!target) {
+    // Nothing will ever service what queued behind this open.
+    tunnels.abandon(frame.tunnelId);
     send(wsSocket, {
       kind: "tunnel.ack",
       tunnelId: frame.tunnelId,
@@ -555,7 +560,9 @@ function handleHttpTunnelOpen(
     },
   );
 
-  tunnels.set(frame.tunnelId, upstream);
+  // Registering replays anything that arrived while the target resolved — for a
+  // bodyless GET that is the `requestEnd` this request cannot reply without.
+  tunnels.register(frame.tunnelId, upstream);
 
   upstream.on("error", (err) => {
     tunnels.delete(frame.tunnelId);
@@ -595,7 +602,6 @@ function handleRawTunnelOpen(
   target: UpstreamAddr,
 ): void {
   const upstream = new Socket();
-  tunnels.set(frame.tunnelId, upstream);
 
   let acked = false;
   let responseBuffer = Buffer.alloc(0);
@@ -660,6 +666,11 @@ function handleRawTunnelOpen(
   });
 
   upstream.connect(target.port, target.host);
+  // AFTER `connect`, not before: replaying a queued write onto a socket that
+  // has not started connecting errors, while node buffers writes made once it
+  // is connecting. An upgrade's own request goes out from the `connect`
+  // handler, so only client frames that overtook the open replay here.
+  tunnels.register(frame.tunnelId, upstream);
 }
 
 function closeTunnel(
@@ -667,9 +678,9 @@ function closeTunnel(
   tunnelId: string,
   reason: string | undefined,
 ): void {
-  const upstream = tunnels.get(tunnelId);
-  tunnels.delete(tunnelId);
-  upstream?.destroy();
+  // `abort`, not get+delete: a client that gives up while the target is still
+  // resolving would otherwise leave the tunnel to open onto nobody.
+  tunnels.abort(tunnelId);
   send(wsSocket, { kind: "tunnel.close", tunnelId, reason });
 }
 

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>;