@botcord/daemon 0.2.75 → 0.2.76

package/src/__tests__/doctor.test.ts

@@ -98,6 +98,18 @@ describe("probeChannel", () => {
     expect(result.hubMessage).toContain("503");
   });
 
+  it("treats HTTP 404 as reachable because the probe only needs the Hub host", async () => {
+    const credsPath = "/creds/ag_123.json";
+    const result = await probeChannel(ch, {
+      credentialsPath: () => credsPath,
+      fileReader: fileReader({ [credsPath]: okCreds }),
+      fetcher: fetcher({ ok: false, status: 404 }),
+      timeoutMs: 1000,
+    });
+    expect(result.hubOk).toBe(true);
+    expect(result.hubMessage).toContain("404");
+  });
+
   it("probeChannels returns an entry per input channel", async () => {
     const credsPath = "/creds/ag_123.json";
     const results = await probeChannels({
@@ -200,6 +212,28 @@ describe("renderDoctor", () => {
     expect(out).toContain("✓");
   });
 
+  it("renders optional runtime auth check results", () => {
+    const out = renderDoctor({
+      runtimes: [
+        {
+          id: "claude-code",
+          displayName: "Claude Code",
+          binary: "claude",
+          supportsRun: true,
+          result: { available: true, version: "1.0.0", path: "/usr/bin/claude" },
+          auth: {
+            checked: true,
+            ok: false,
+            message: "Failed to authenticate. API Error: 403 Request not allowed",
+          },
+        },
+      ],
+      channels: [],
+    });
+    expect(out).toContain("auth failed");
+    expect(out).toContain("Failed to authenticate");
+  });
+
   it("shows 'No channels configured.' when the channel list is empty", () => {
     const out = renderDoctor({
       runtimes: [

package/src/__tests__/runtime-discovery.test.ts

@@ -28,6 +28,7 @@ vi.mock("../adapters/runtimes.js", async () => {
 });
 
 const {
+  attachRuntimeHealth,
   collectRuntimeSnapshot,
   collectRuntimeSnapshotAsync,
   clearRuntimeProbeCache,
@@ -366,4 +367,93 @@ describe("pushRuntimeSnapshot (first-connect push)", () => {
     expect(ok).toBe(false);
     expect(send).toHaveBeenCalledOnce();
   });
+
+  it("attaches live runtime circuit breaker health to the pushed runtime entry", () => {
+    setRuntimes([
+      {
+        id: "claude-code",
+        displayName: "Claude Code",
+        binary: "claude",
+        supportsRun: true,
+        result: { available: true },
+      },
+    ]);
+    const send = vi.fn(() => true);
+    const ok = pushRuntimeSnapshot(
+      { send },
+      {
+        channels: {},
+        turns: {},
+        runtimeCircuitBreakers: {
+          "claude-code:botcord:ag_1:rm_oc_a:": {
+            key: "claude-code:botcord:ag_1:rm_oc_a:",
+            runtime: "claude-code",
+            channel: "botcord",
+            accountId: "ag_1",
+            conversationId: "rm_oc_a",
+            threadId: null,
+            failures: 3,
+            openedAt: 1000,
+            blockedUntil: 2000,
+            lastFailureAt: 1500,
+            lastError: "Failed to authenticate",
+          },
+        },
+      },
+    );
+    expect(ok).toBe(true);
+    const frame = send.mock.calls[0]![0] as {
+      params: { runtimes: Array<{ id: string; health?: { circuitBreakers?: unknown[] } }> };
+    };
+    expect(frame.params.runtimes[0].health?.circuitBreakers).toEqual([
+      expect.objectContaining({
+        conversationId: "rm_oc_a",
+        failures: 3,
+        lastError: "Failed to authenticate",
+      }),
+    ]);
+  });
+});
+
+describe("attachRuntimeHealth", () => {
+  it("groups live circuit breakers onto matching runtime entries", () => {
+    const snap = {
+      runtimes: [
+        { id: "claude-code", available: true },
+        { id: "codex", available: true },
+      ],
+      probedAt: 1000,
+    };
+    const out = attachRuntimeHealth(snap, {
+      channels: {},
+      turns: {},
+      runtimeCircuitBreakers: {
+        "claude-code:botcord:ag_1:rm_oc_a:": {
+          key: "claude-code:botcord:ag_1:rm_oc_a:",
+          runtime: "claude-code",
+          channel: "botcord",
+          accountId: "ag_1",
+          conversationId: "rm_oc_a",
+          threadId: null,
+          failures: 3,
+          openedAt: 1000,
+          blockedUntil: 2000,
+          lastFailureAt: 1500,
+          lastError: "Failed to authenticate",
+        },
+      },
+    });
+    expect(out.runtimes[0]).toMatchObject({
+      id: "claude-code",
+      health: {
+        circuitBreakers: [
+          {
+            conversationId: "rm_oc_a",
+            lastError: "Failed to authenticate",
+          },
+        ],
+      },
+    });
+    expect(out.runtimes[1]).toEqual({ id: "codex", available: true });
+  });
 });

package/src/__tests__/status-render.test.ts

@@ -8,6 +8,7 @@ function snapshot(
   return {
     channels: overrides.channels ?? {},
     turns: overrides.turns ?? {},
+    runtimeCircuitBreakers: overrides.runtimeCircuitBreakers,
   };
 }
 
@@ -69,6 +70,7 @@ describe("renderStatus", () => {
     expect(out).toContain("rm_oc_abc");
     expect(out).toContain("claude-code");
     expect(out).toMatch(/12s ago/);
+    expect(out).toContain("Runtime circuit breakers:");
     expect(out).not.toContain("⚠ stale");
   });
 
@@ -134,4 +136,36 @@ describe("renderStatus", () => {
     expect(out).toContain("Channels:");
     expect(out).toContain("(none)");
   });
+
+  it("renders open runtime auth circuit breakers", () => {
+    const now = 1_700_000_000_000;
+    const out = renderStatus(
+      {
+        pid: 1,
+        alive: true,
+        snapshot: snapshot({
+          runtimeCircuitBreakers: {
+            "claude-code:botcord:ag_1:rm_oc_a:": {
+              key: "claude-code:botcord:ag_1:rm_oc_a:",
+              runtime: "claude-code",
+              channel: "botcord",
+              accountId: "ag_1",
+              conversationId: "rm_oc_a",
+              failures: 3,
+              openedAt: now - 1000,
+              blockedUntil: now + 60_000,
+              lastFailureAt: now - 1000,
+              lastError: "Failed to authenticate",
+            },
+          },
+        }),
+        snapshotAgeMs: 100,
+      },
+      now,
+    );
+    expect(out).toContain("Runtime circuit breakers:");
+    expect(out).toContain("claude-code");
+    expect(out).toContain("rm_oc_a");
+    expect(out).toContain("Failed to authenticate");
+  });
 });

package/src/cloud-auth.ts

@@ -0,0 +1,78 @@
+/**
+ * Cloud-daemon auth manager.
+ *
+ * Implements the subset of `UserAuthManager` surface that `ControlChannel`
+ * uses (`current`, `ensureAccessToken`) so the same channel implementation
+ * can be reused for `/cloud/daemon/ws`. Unlike the user variant there is
+ * no refresh token: the Hub-managed E2B provider rotates the access token
+ * by relaunching the daemon. When the embedded JWT expires, the WS server
+ * closes with 4401 and `ControlChannel.onClose` writes the auth-expired
+ * flag — at which point the provider would resume the sandbox with a
+ * fresh token.
+ *
+ * Plan §6.4: `auth-expired.flag` is still written so any external monitor
+ * watching the sandbox filesystem can detect the situation; the cloud
+ * provider doesn't read this file directly today (it relies on
+ * `daemon_instances.last_seen_at` going stale instead).
+ *
+ * Field names match `UserAuthRecord` for drop-in compatibility with
+ * `ControlChannel.start()` which reads `auth.current.{userId,hubUrl,label}`.
+ */
+import type { UserAuthRecord, UserAuthManager } from "./user-auth.js";
+import type { CloudModeConfig } from "./cloud-mode.js";
+
+/**
+ * Minimal `UserAuthManager`-shaped wrapper backed by the cloud-mode env
+ * vars. Static-typed against `UserAuthManager` so `ControlChannel` accepts
+ * it without an interface change.
+ */
+export class CloudAuthManager {
+  private record: UserAuthRecord;
+
+  constructor(cfg: CloudModeConfig) {
+    this.record = {
+      version: 1,
+      // The cloud daemon row is owned by a single user — but we don't get
+      // the user id in the env (the JWT carries it server-side). Surface
+      // the cloud daemon instance id as a stable "who am I" string for
+      // logs; the Hub already knows the binding.
+      userId: cfg.cloudDaemonInstanceId,
+      daemonInstanceId: cfg.daemonInstanceId,
+      hubUrl: cfg.hubUrl,
+      accessToken: cfg.accessToken,
+      // No refresh token in cloud mode. Stored as an empty string to keep
+      // the type intact; `ensureAccessToken` never reaches the refresh path
+      // because `expiresAt` is set to a date far in the future (the Hub
+      // closes the WS with 4401 when the embedded JWT expires).
+      refreshToken: "",
+      expiresAt: Number.MAX_SAFE_INTEGER,
+      loggedInAt: new Date().toISOString(),
+      label: `cloud:${cfg.cloudDaemonInstanceId}`,
+    };
+  }
+
+  get current(): UserAuthRecord {
+    return this.record;
+  }
+
+  /**
+   * Cloud-mode access token never refreshes locally — it's baked into the
+   * JWT the provider injected at sandbox start. The provider rotates by
+   * relaunching the daemon, not by talking to a refresh endpoint.
+   */
+  async ensureAccessToken(): Promise<string> {
+    return this.record.accessToken;
+  }
+}
+
+/**
+ * Hand the cloud auth wrapper out as a `UserAuthManager` so `ControlChannel`
+ * (which only consults `current` and `ensureAccessToken`) accepts it.
+ *
+ * Cast-only — no runtime translation needed because `CloudAuthManager`
+ * implements the same shape. Kept as a single helper so the cast is
+ * documented in one place.
+ */
+export function asUserAuthManager(mgr: CloudAuthManager): UserAuthManager {
+  return mgr as unknown as UserAuthManager;
+}

package/src/cloud-daemon.ts

@@ -0,0 +1,338 @@
+/**
+ * Cloud-daemon mode runtime entrypoint.
+ *
+ * Equivalent to {@link startDaemon} for cloud-mode operation: skips local
+ * user-auth, skips local on-disk credentials, dials
+ * `${HUB_URL}/cloud/daemon/ws` with the env-injected JWT, and reuses the
+ * existing provisioner so `provision_agent` / `revoke_agent` frames work
+ * the same way they do for local daemons.
+ *
+ * See ``docs/cloud-agent-technical-design.md`` §4 + §6.
+ */
+import { shouldWake, type AttentionPolicy } from "@botcord/protocol-core";
+import {
+  Gateway,
+  resolveTranscriptEnabled,
+  type ChannelAdapter,
+  type GatewayChannelConfig,
+  type GatewayInboundMessage,
+  type GatewayLogger,
+  type GatewayRuntimeSnapshot,
+} from "./gateway/index.js";
+import { ActivityTracker } from "./activity-tracker.js";
+import type { DaemonConfig } from "./config.js";
+import { SESSIONS_PATH, SNAPSHOT_PATH } from "./config.js";
+import { ControlChannel } from "./control-channel.js";
+import { toGatewayConfig } from "./daemon-config-map.js";
+import { log as daemonLog } from "./log.js";
+import { createProvisioner } from "./provision.js";
+import { createDaemonChannel, pushRuntimeSnapshot } from "./daemon.js";
+import { SnapshotWriter } from "./snapshot-writer.js";
+import { createDaemonSystemContextBuilder } from "./system-context.js";
+import { readWorkingMemorySnapshot } from "./working-memory.js";
+import { createRoomStaticContextBuilder } from "./room-context.js";
+import { createRoomContextFetcher } from "./room-context-fetcher.js";
+import { composeBotCordUserTurn } from "./turn-text.js";
+import { PolicyResolver, type DaemonAttentionPolicy } from "./gateway/policy-resolver.js";
+import { scanMention } from "./mention-scan.js";
+import { createActivityRecorder } from "./daemon.js";
+import { CloudAuthManager, asUserAuthManager } from "./cloud-auth.js";
+import type { CloudModeConfig } from "./cloud-mode.js";
+import { buildCloudRunSettleHook } from "./cloud-settle.js";
+import type { InstalledAgentInfo, OnAgentInstalledHook } from "./provision.js";
+
+// Cloud daemons follow the same cadence as local — keeps dashboard
+// "runtimes last detected" behavior identical across both kinds.
+const DEFAULT_TURN_TIMEOUT_MS = 30 * 60 * 1000;
+const DEFAULT_SNAPSHOT_INTERVAL_MS = 5_000;
+
+function resolveSnapshotIntervalMs(): number {
+  const raw = process.env.BOTCORD_DAEMON_SNAPSHOT_INTERVAL_MS;
+  if (!raw) return DEFAULT_SNAPSHOT_INTERVAL_MS;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_SNAPSHOT_INTERVAL_MS;
+  return n;
+}
+
+/** Options accepted by {@link startCloudDaemon}. */
+export interface CloudDaemonRuntimeOptions {
+  /** Resolved env-driven cloud config (see {@link loadCloudModeConfig}). */
+  cloudConfig: CloudModeConfig;
+  /**
+   * Empty/initial DaemonConfig. Cloud daemons start with zero agents and
+   * grow exclusively via `provision_agent` frames over the cloud control
+   * plane — `agents[]` / `routes[]` arrays are seeded empty.
+   */
+  config: DaemonConfig;
+  configPath: string;
+  sessionStorePath?: string;
+  snapshotPath?: string;
+  snapshotIntervalMs?: number;
+  log?: GatewayLogger;
+  /** Test hook — override the control-channel cstr. */
+  controlChannelFactory?: typeof ControlChannel;
+  /** Skip control channel entirely; for tests that exercise the gateway only. */
+  disableControlChannel?: boolean;
+  /**
+   * Test hook — inject a pre-built provisioner. Default uses
+   * `createProvisioner({ gateway, policyResolver, onAgentInstalled })`.
+   */
+  provisionerFactory?: typeof createProvisioner;
+}
+
+/** Handle returned by {@link startCloudDaemon}. */
+export interface CloudDaemonHandle {
+  stop: (reason?: string) => Promise<void>;
+  snapshot: () => GatewayRuntimeSnapshot;
+}
+
+function buildLogger(opt: GatewayLogger | undefined): GatewayLogger {
+  if (opt) return opt;
+  return {
+    info: (msg, meta) => daemonLog.info(msg, meta),
+    warn: (msg, meta) => daemonLog.warn(msg, meta),
+    error: (msg, meta) => daemonLog.error(msg, meta),
+    debug: (msg, meta) => daemonLog.debug(msg, meta),
+  };
+}
+
+/**
+ * Boot the cloud daemon. The gateway starts with zero channels; every
+ * provisioned agent arrives via `provision_agent`, which calls into the
+ * shared `provision.ts` flow exactly like a local daemon does. The only
+ * difference is the control-channel auth, endpoint path, and the absence
+ * of a local user-auth file.
+ */
+export async function startCloudDaemon(
+  opts: CloudDaemonRuntimeOptions,
+): Promise<CloudDaemonHandle> {
+  const logger = buildLogger(opts.log);
+  const cloudCfg = opts.cloudConfig;
+
+  logger.info("cloud daemon starting", {
+    cloudDaemonInstanceId: cloudCfg.cloudDaemonInstanceId,
+    daemonInstanceId: cloudCfg.daemonInstanceId,
+    hubUrl: cloudCfg.hubUrl,
+  });
+
+  // ActivityTracker / policy resolver / per-agent caches — same as local
+  // daemon, but the caches start empty because no agents are bound at
+  // boot. `onAgentInstalled` populates them whenever provision_agent
+  // lands.
+  const activityTracker = new ActivityTracker();
+  const credentialPathByAgentId = new Map<string, string>();
+  const hubUrlByAgentId = new Map<string, string>();
+  const displayNameByAgent = new Map<string, string>();
+  // Seed each per-agent hub URL with the cloud-mode value so that even
+  // before the first credential file is written the room-context fetcher
+  // has somewhere sensible to point.
+  const fallbackHubUrl = cloudCfg.hubUrl;
+  const resolveHubUrl = (accountId: string): string | undefined =>
+    hubUrlByAgentId.get(accountId) ?? fallbackHubUrl;
+
+  // Same gateway-config translation as local — empty `agents` produces an
+  // empty `channels[]` initially, which is fine.
+  const gwConfig = toGatewayConfig(opts.config, { agentIds: [], agentRuntimes: {} });
+
+  const roomContextFetcher = createRoomContextFetcher({
+    credentialPathByAgentId,
+    hubBaseUrl: cloudCfg.hubUrl,
+    log: logger,
+  });
+  const roomContextBuilder = createRoomStaticContextBuilder({
+    fetchRoomInfo: roomContextFetcher,
+    log: logger,
+  });
+
+  type PerAgentBuilder = (
+    msg: GatewayInboundMessage,
+  ) => Promise<string | undefined> | string | undefined;
+  const scBuilders = new Map<string, PerAgentBuilder>();
+  const buildSystemContext = (
+    message: GatewayInboundMessage,
+  ): Promise<string | undefined> | string | undefined => {
+    const b = scBuilders.get(message.accountId);
+    return b ? b(message) : undefined;
+  };
+  const buildMemoryContext = (message: GatewayInboundMessage) =>
+    readWorkingMemorySnapshot(message.accountId);
+
+  const recordActivity = createActivityRecorder({ activityTracker });
+  const onInbound = (msg: GatewayInboundMessage): void => {
+    recordActivity(msg);
+  };
+
+  // Settle ``cloud_run`` envelopes against the Hub usage ledger once the
+  // runtime turn finishes. Pure adapter from the dispatcher's hook shape
+  // to the settle helper's input shape — the actual HTTP call lives in
+  // :func:`buildCloudRunSettleHook` so it's unit-testable.
+  const settleHook = buildCloudRunSettleHook({
+    hubUrl: cloudCfg.hubUrl,
+    accessToken: cloudCfg.accessToken,
+    log: logger,
+  });
+  const onTurnComplete = async (event: {
+    message: GatewayInboundMessage;
+    result?: import("./gateway/types.js").RuntimeRunResult;
+    wallTimeMs: number;
+    error?: unknown;
+  }): Promise<void> => {
+    const envelope = (event.message.raw as { envelope?: unknown } | undefined)
+      ?.envelope as
+      | {
+          type?: string;
+          payload?: { cloud_run?: { run_id?: unknown } | null } | null;
+        }
+      | undefined;
+    const runId = envelope?.payload?.cloud_run?.run_id;
+    await settleHook({
+      envelopeType: envelope?.type,
+      runId: typeof runId === "string" ? runId : undefined,
+      wallTimeMs: event.wallTimeMs,
+      tokens: {
+        ...(event.result?.inputCacheHitTokens !== undefined
+          ? { inputCacheHitTokens: event.result.inputCacheHitTokens }
+          : {}),
+        ...(event.result?.inputCacheMissTokens !== undefined
+          ? { inputCacheMissTokens: event.result.inputCacheMissTokens }
+          : {}),
+        ...(event.result?.outputTokens !== undefined
+          ? { outputTokens: event.result.outputTokens }
+          : {}),
+      },
+      messageId: event.message.id,
+    });
+  };
+
+  const policyResolver = new PolicyResolver({
+    fetchGlobal: async (_agentId: string) => undefined,
+  });
+
+  const attentionGate = async (msg: GatewayInboundMessage): Promise<boolean> => {
+    const policy: DaemonAttentionPolicy = await policyResolver.resolve(
+      msg.accountId,
+      msg.conversation.id,
+    );
+    if (policy.mode === "allowed_senders") {
+      return (policy.allowedSenderIds ?? []).includes(msg.sender.id);
+    }
+    const localMention = scanMention(msg.text, {
+      agentId: msg.accountId,
+      displayName: displayNameByAgent.get(msg.accountId),
+    });
+    return shouldWake(policy as AttentionPolicy, {
+      mentioned: msg.mentioned === true || localMention,
+      text: msg.text,
+    });
+  };
+
+  const onAgentInstalled: OnAgentInstalledHook = (info: InstalledAgentInfo) => {
+    credentialPathByAgentId.set(info.agentId, info.credentialsFile);
+    if (info.hubUrl) hubUrlByAgentId.set(info.agentId, info.hubUrl);
+    if (info.displayName) displayNameByAgent.set(info.agentId, info.displayName);
+    if (!scBuilders.has(info.agentId)) {
+      scBuilders.set(
+        info.agentId,
+        createDaemonSystemContextBuilder({
+          agentId: info.agentId,
+          activityTracker,
+          roomContextBuilder,
+          // Cloud daemons run isolated — no loop-risk guard wired in PR1;
+          // the runtime adapter's wall-time budget enforces the equivalent.
+          loopRiskBuilder: () => null,
+        }),
+      );
+    }
+  };
+
+  const gateway = new Gateway({
+    config: gwConfig,
+    sessionStorePath: opts.sessionStorePath ?? SESSIONS_PATH,
+    createChannel: (chCfg: GatewayChannelConfig): ChannelAdapter => {
+      return createDaemonChannel(chCfg, {
+        credentialPathByAgentId,
+        hubBaseUrl: cloudCfg.hubUrl,
+      });
+    },
+    log: logger,
+    turnTimeoutMs: DEFAULT_TURN_TIMEOUT_MS,
+    buildSystemContext,
+    buildMemoryContext,
+    onInbound,
+    onTurnComplete,
+    composeUserTurn: composeBotCordUserTurn,
+    attentionGate,
+    resolveHubUrl,
+    transcriptEnabled: resolveTranscriptEnabled(
+      process.env.BOTCORD_TRANSCRIPT,
+      opts.config.transcript?.enabled,
+    ),
+  });
+
+  await gateway.start();
+  logger.info("cloud daemon gateway started (zero agents at boot)");
+
+  let controlChannel: ControlChannel | null = null;
+  if (!opts.disableControlChannel) {
+    const auth = asUserAuthManager(new CloudAuthManager(cloudCfg));
+    const provisionerFactory = opts.provisionerFactory ?? createProvisioner;
+    const provisioner = provisionerFactory({
+      gateway,
+      policyResolver,
+      onAgentInstalled,
+    });
+    const ControlChannelCtor = opts.controlChannelFactory ?? ControlChannel;
+    controlChannel = new ControlChannelCtor({
+      auth,
+      // The cloud WS endpoint differs from the local daemon WS — same
+      // frame schema, different bearer-token kind on the Hub side.
+      path: "/cloud/daemon/ws",
+      handle: async (frame) => provisioner(frame),
+      label: `cloud:${cloudCfg.cloudDaemonInstanceId}`,
+    });
+    try {
+      await controlChannel.start();
+      // Same `runtime_snapshot` push as local — keeps the dashboard's
+      // "what's installed" view accurate the moment the daemon comes up.
+      const pushed = pushRuntimeSnapshot(controlChannel);
+      logger.info("cloud control-channel started; runtime_snapshot pushed", {
+        ok: pushed,
+      });
+    } catch (err) {
+      logger.warn("cloud control-channel start failed; daemon will retry", {
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  const snapshotWriter = new SnapshotWriter({
+    path: opts.snapshotPath ?? SNAPSHOT_PATH,
+    intervalMs: opts.snapshotIntervalMs ?? resolveSnapshotIntervalMs(),
+    snapshot: () => gateway.snapshot(),
+    log: logger,
+  });
+  snapshotWriter.start();
+
+  let stopping: Promise<void> | null = null;
+  const stop = (reason?: string): Promise<void> => {
+    if (stopping) return stopping;
+    logger.info("cloud daemon stopping", { reason: reason ?? null });
+    snapshotWriter.stop();
+    snapshotWriter.writeFinal();
+    const controlStopP = controlChannel
+      ? controlChannel.stop().catch(() => undefined)
+      : Promise.resolve();
+    stopping = Promise.all([controlStopP, gateway.stop(reason)]).then(
+      () => undefined,
+    ).finally(() => {
+      snapshotWriter.remove();
+      logger.info("cloud daemon stopped", { reason: reason ?? null });
+    });
+    return stopping;
+  };
+
+  return {
+    stop,
+    snapshot: () => gateway.snapshot(),
+  };
+}

package/src/cloud-mode.ts

@@ -0,0 +1,70 @@
+/**
+ * Cloud-daemon mode detection + env-driven configuration.
+ *
+ * A "cloud daemon" is a `botcord-daemon` process running inside a Hub-managed
+ * E2B sandbox. It is configured exclusively through environment variables
+ * (no on-disk `user-auth.json`) and connects to `/cloud/daemon/ws` with a
+ * `cloud-daemon-access` JWT instead of the device-code-issued user token.
+ *
+ * The Hub-side provider that launches the daemon is
+ * `backend/hub/services/cloud_daemon_provider_e2b.py` — keep the env-var
+ * names below in sync with `_build_env` there.
+ *
+ * See ``docs/cloud-agent-technical-design.md`` §3-4.
+ */
+
+/** Names of the environment variables the cloud provider injects. */
+export const CLOUD_ENV_VARS = {
+  HUB_URL: "BOTCORD_HUB_URL",
+  CLOUD_DAEMON_INSTANCE_ID: "BOTCORD_CLOUD_DAEMON_INSTANCE_ID",
+  DAEMON_INSTANCE_ID: "BOTCORD_DAEMON_INSTANCE_ID",
+  ACCESS_TOKEN: "BOTCORD_CLOUD_DAEMON_ACCESS_TOKEN",
+} as const;
+
+/** Resolved cloud-mode configuration. All fields are required when present. */
+export interface CloudModeConfig {
+  hubUrl: string;
+  cloudDaemonInstanceId: string;
+  daemonInstanceId: string;
+  accessToken: string;
+}
+
+/**
+ * Detection signal — true when `BOTCORD_CLOUD_DAEMON_ACCESS_TOKEN` is set.
+ *
+ * The access-token presence is the canonical mode switch (matches the
+ * provider contract — the token is the one piece the sandbox can't forge).
+ * Other env vars may be set during development without flipping mode.
+ */
+export function isCloudMode(env: NodeJS.ProcessEnv = process.env): boolean {
+  const token = env[CLOUD_ENV_VARS.ACCESS_TOKEN];
+  return typeof token === "string" && token.length > 0;
+}
+
+/**
+ * Resolve the cloud-mode configuration from env vars. Throws when a required
+ * variable is missing — the daemon must fail fast instead of falling through
+ * to the local-mode codepath with partial cloud config.
+ *
+ * `BOTCORD_DAEMON_INSTANCE_ID` is allowed to fall back to the cloud daemon
+ * id when omitted in tests, but in production the provider always sets it.
+ */
+export function loadCloudModeConfig(
+  env: NodeJS.ProcessEnv = process.env,
+): CloudModeConfig {
+  const requireString = (name: string): string => {
+    const v = env[name];
+    if (typeof v !== "string" || v.length === 0) {
+      throw new Error(
+        `cloud-daemon mode: required env var "${name}" is missing or empty`,
+      );
+    }
+    return v;
+  };
+  return {
+    hubUrl: requireString(CLOUD_ENV_VARS.HUB_URL),
+    cloudDaemonInstanceId: requireString(CLOUD_ENV_VARS.CLOUD_DAEMON_INSTANCE_ID),
+    daemonInstanceId: requireString(CLOUD_ENV_VARS.DAEMON_INSTANCE_ID),
+    accessToken: requireString(CLOUD_ENV_VARS.ACCESS_TOKEN),
+  };
+}