@runuai/host 0.4.2 → 0.5.0

package/runner/runner.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * uai session runner (ADR-061) — runs INSIDE the task container and owns an
+ * agent CLI process, so the CLI's lifetime is decoupled from the host
+ * process. The host talks to it only through files on the task-workspace
+ * bind mount (no sockets/FIFOs — they don't cross the macOS↔VM boundary):
+ *
+ *   <sessionDir>/inbox.jsonl   host appends; runner tails → CLI stdin
+ *   <sessionDir>/outbox.jsonl  CLI stdout lines verbatim + __uai meta lines
+ *   <sessionDir>/heartbeat     rewritten every HEARTBEAT_MS (host checks mtime)
+ *   <sessionDir>/runner.json   pid, protocol, argv, startedAt
+ *
+ * Meta lines are `{"__uai":"spawn"|"exit", ...}`; the host filters them out
+ * before handing lines to the protocol adapters. Control lines the host
+ * appends to the inbox use the same shape (`{"__uai":"stop"}`); everything
+ * else in the inbox goes to the CLI's stdin untouched.
+ *
+ * Plain Node ≥18, dependency-free, ESM. Testable outside docker: point it
+ * at a tmp dir and any line-oriented fake CLI.
+ *
+ * Usage: node runner.mjs <sessionDir> -- <command> [args...]
+ */
+
+import { spawn } from "node:child_process";
+import { appendFileSync, mkdirSync, openSync, readSync, fstatSync, closeSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import process from "node:process";
+
+const PROTOCOL = 1;
+const POLL_MS = 50;
+const HEARTBEAT_MS = 5_000;
+const STDERR_CAP = 8 * 1024;
+const STOP_GRACE_MS = 5_000;
+
+// ---- argv ------------------------------------------------------------------
+
+const sep = process.argv.indexOf("--");
+const sessionDir = process.argv[2];
+if (!sessionDir || sep < 0 || sep + 1 >= process.argv.length) {
+  process.stderr.write("usage: runner.mjs <sessionDir> -- <command> [args...]\n");
+  process.exit(2);
+}
+const command = process.argv[sep + 1];
+const args = process.argv.slice(sep + 2);
+
+mkdirSync(sessionDir, { recursive: true });
+const inboxPath = join(sessionDir, "inbox.jsonl");
+const outboxPath = join(sessionDir, "outbox.jsonl");
+const heartbeatPath = join(sessionDir, "heartbeat");
+const runnerJsonPath = join(sessionDir, "runner.json");
+
+// Single append point — appendFileSync with O_APPEND keeps lines atomic for
+// the sizes we write; the runner is the outbox's only writer.
+function outbox(line) {
+  appendFileSync(outboxPath, line.endsWith("\n") ? line : `${line}\n`);
+}
+function meta(kind, extra = {}) {
+  outbox(JSON.stringify({ __uai: kind, ts: Date.now(), ...extra }));
+}
+
+// ---- the CLI ---------------------------------------------------------------
+
+// The runner is launched through the container's asdf `node` shim, which
+// exports its resolved version (ASDF_NODEJS_VERSION et al.) into our env.
+// Passing that through would pin the CLI's own asdf shim to the WORKSPACE's
+// node version — "No claude executable found for nodejs X" when the agent
+// CLIs are installed under a different one. Strip ASDF_* so the CLI shim
+// resolves exactly as a direct `docker exec <cli>` would.
+const cliEnv = { ...process.env };
+for (const key of Object.keys(cliEnv)) {
+  if (key.startsWith("ASDF_")) delete cliEnv[key];
+}
+
+const child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"], env: cliEnv });
+
+writeFileSync(
+  runnerJsonPath,
+  JSON.stringify({
+    protocol: PROTOCOL,
+    runnerPid: process.pid,
+    cliPid: child.pid ?? null,
+    command,
+    args,
+    startedAt: Date.now(),
+  }),
+);
+meta("spawn", { protocol: PROTOCOL, runnerPid: process.pid, cliPid: child.pid ?? null });
+
+let stderrTail = "";
+child.stderr?.setEncoding("utf8");
+child.stderr?.on("data", (chunk) => {
+  stderrTail = (stderrTail + chunk).slice(-STDERR_CAP);
+});
+
+// CLI stdout → outbox, complete lines only (partial line buffered).
+let stdoutBuf = "";
+child.stdout?.setEncoding("utf8");
+child.stdout?.on("data", (chunk) => {
+  stdoutBuf += chunk;
+  for (;;) {
+    const nl = stdoutBuf.indexOf("\n");
+    if (nl < 0) break;
+    const line = stdoutBuf.slice(0, nl);
+    stdoutBuf = stdoutBuf.slice(nl + 1);
+    if (line.trim().length > 0) outbox(line);
+  }
+});
+
+let exiting = false;
+child.on("exit", (code, signal) => {
+  if (exiting) return;
+  exiting = true;
+  if (stdoutBuf.trim().length > 0) outbox(stdoutBuf); // flush the partial tail
+  meta("exit", { code, signal: signal ?? null, stderrTail });
+  process.exit(0);
+});
+child.on("error", (err) => {
+  if (exiting) return;
+  exiting = true;
+  meta("exit", { code: null, signal: null, stderrTail: String(err?.message ?? err) });
+  process.exit(0);
+});
+
+// ---- inbox tail → CLI stdin --------------------------------------------------
+
+let inboxOffset = 0; // fresh session dir per spawn — always start at 0
+let inboxBuf = "";
+
+function stopCli() {
+  if (exiting) return;
+  try {
+    child.kill("SIGTERM");
+  } catch {
+    /* already gone */
+  }
+  setTimeout(() => {
+    try {
+      child.kill("SIGKILL");
+    } catch {
+      /* already gone */
+    }
+  }, STOP_GRACE_MS).unref();
+}
+
+function handleInboxLine(line) {
+  if (line.trim().length === 0) return;
+  if (line.startsWith('{"__uai"')) {
+    try {
+      const ctl = JSON.parse(line);
+      if (ctl.__uai === "stop") stopCli();
+    } catch {
+      /* malformed control — ignore */
+    }
+    return;
+  }
+  try {
+    child.stdin?.write(`${line}\n`);
+  } catch {
+    /* EPIPE after CLI death — the exit meta already tells the host */
+  }
+}
+
+function pollInbox() {
+  let fd;
+  try {
+    fd = openSync(inboxPath, "r");
+  } catch {
+    return; // inbox not created yet
+  }
+  try {
+    const size = fstatSync(fd).size;
+    if (size > inboxOffset) {
+      const len = size - inboxOffset;
+      const buf = Buffer.alloc(len);
+      const read = readSync(fd, buf, 0, len, inboxOffset);
+      inboxOffset += read;
+      inboxBuf += buf.toString("utf8", 0, read);
+      for (;;) {
+        const nl = inboxBuf.indexOf("\n");
+        if (nl < 0) break;
+        const line = inboxBuf.slice(0, nl);
+        inboxBuf = inboxBuf.slice(nl + 1);
+        handleInboxLine(line);
+      }
+    }
+  } finally {
+    closeSync(fd);
+  }
+}
+
+setInterval(pollInbox, POLL_MS);
+
+// ---- heartbeat ---------------------------------------------------------------
+
+function beat() {
+  try {
+    writeFileSync(heartbeatPath, `${process.pid} ${Date.now()}\n`);
+  } catch {
+    /* disk hiccup — next beat retries */
+  }
+}
+beat();
+setInterval(beat, HEARTBEAT_MS);
+
+// The runner dies only with its CLI (or on stop/SIGTERM) — never because a
+// host-side consumer went away. That is the entire point (ADR-061).
+process.on("SIGTERM", stopCli);
+process.on("SIGINT", stopCli);

package/scripts/agent/task-up.sh

@@ -34,6 +34,8 @@ setup_err_trap
 # Pinned constants (all clusters must agree — see ADR-022).
 STANDARD_IMAGE="uai-standard:dev"
 ASDF_VOLUME="uai-asdf-data"
+# ADR-053: host-wide Playwright browser cache (Chromium downloads once).
+PW_VOLUME="uai-playwright"
 DERIVED_IMAGE="uai-task-${task_id}"
 
 # -----------------------------------------------------------------------------
@@ -308,6 +310,9 @@ fi
       "$projects_root" "$vol_pid" "$projects_root" "$vol_pid"
   done < <(jq -c '.[]' <<<"$projects_json")
   printf '      - "%s:/opt/asdf-data"\n' "$ASDF_VOLUME"
+  # ADR-053: host-wide Playwright browser cache. Always mounted (harmless
+  # when browser testing is off); Chromium downloads once per HOST.
+  printf '      - "%s:/opt/pw-browsers"\n' "$PW_VOLUME"
   printf '    ports:\n'
   # code-server (the Editor tunnel) is the only auto-published port. Preview
   # ports are NOT published at task-up (ADR-043 Stage 2: opt-in previews) —
@@ -324,6 +329,8 @@ fi
   # claude and the code-server terminal's interactive claude authenticate.
   printf '      %s: "${%s:-}"\n' \
     "CLAUDE_CODE_OAUTH_TOKEN" "CLAUDE_CODE_OAUTH_TOKEN"
+  # ADR-053: point Playwright at the shared browser cache volume.
+  printf '      PLAYWRIGHT_BROWSERS_PATH: "/opt/pw-browsers"\n'
   # No GH_TOKEN/GITHUB_TOKEN in the container env (ADR-027). `gh` prefers such
   # an env var over its stored credentials, which blocks the per-user
   # `gh auth login --with-token` the host runs (and would re-attribute every PR
@@ -361,6 +368,8 @@ fi
   printf 'volumes:\n'
   printf '  %s:\n' "$ASDF_VOLUME"
   printf '    external: true\n'
+  printf '  %s:\n' "$PW_VOLUME"
+  printf '    external: true\n'
 } > "$task_uai_dir/docker-compose.yml"
 
 if [ "$has_derived" = "1" ]; then
@@ -381,6 +390,7 @@ fi
 # The shared asdf cache volume is host-wide and declared external — make
 # sure it exists before compose references it. Idempotent.
 docker volume create "$ASDF_VOLUME" >/dev/null 2>&1 || true
+docker volume create "$PW_VOLUME" >/dev/null 2>&1 || true
 
 step "COMPOSE_UP_FAILED" "docker compose up -d"
 if [ "$has_derived" = "1" ]; then

package/src/index.ts

@@ -7,6 +7,7 @@ import { readAttachment, writeAttachment } from "../lib/attachments";
 import { appendTranscript as writeTranscript } from "../lib/transcript";
 import { buildTaskDiff } from "../lib/task-diff";
 import {
+  getHostTask,
   recordHostEvent,
   recordTaskDown,
   recordTaskError,
@@ -14,6 +15,9 @@ import {
   recordTaskStarting,
   recordTaskUpResult,
 } from "../lib/runtime-state";
+import { clearTaskGatewayAcl } from "../lib/mcp-gateway";
+import { parsePreviewPortRuntimes } from "../lib/preview-ports";
+import { ensurePreviewSidecar } from "../lib/preview-sidecar";
 import {
   HostErrorCode,
   type CommandContext,
@@ -145,7 +149,21 @@ export const hostCommands: HostCommands = {
 
   async taskStatus(ctx, taskId) {
     logCommand(ctx, "taskStatus", taskId);
-    return wrapAgent(ctx, "taskStatus", () => agent.taskStatus(taskId));
+    const result = await wrapAgent(ctx, "taskStatus", () =>
+      agent.taskStatus(taskId),
+    );
+    // ADR-051: attach the published preview ports from the host DB so the
+    // cloud can backfill its mirror on reconcile (tasks launched before the
+    // cloud started recording them at task-up).
+    if (result.ok) {
+      const ports = parsePreviewPortRuntimes(
+        getHostTask(taskId)?.previewPorts,
+      );
+      if (ports.length > 0) {
+        return { ...result, value: { ...result.value, previewPorts: ports } };
+      }
+    }
+    return result;
   },
 
   async channelEnsure(ctx, input) {
@@ -163,6 +181,8 @@ export const hostCommands: HostCommands = {
     logCommand(ctx, "channelTeardown", taskId);
     try {
       await getOrchestrator().closeChannel(taskId);
+      // ADR-057: the task's gateway routes die with the channel.
+      clearTaskGatewayAcl(taskId);
       return ok(undefined);
     } catch (err) {
       return failFromUnknown(err);
@@ -186,6 +206,37 @@ export const hostCommands: HostCommands = {
     }
   },
 
+  async previewEnsure(ctx, taskId, name, containerPort) {
+    logCommand(ctx, "previewEnsure", taskId, name);
+    try {
+      const task = getHostTask(taskId);
+      if (!task) {
+        return {
+          ok: false as const,
+          code: HostErrorCode.TaskNotFound,
+          message: `no such task: ${taskId}`,
+        };
+      }
+      // Task-up published port (preview enabled at launch) wins.
+      const declared = parsePreviewPortRuntimes(task.previewPorts).find(
+        (port) => port.name === name,
+      );
+      if (declared) return ok({ hostPort: declared.hostPort });
+      // Else start (or find) the node-proxy sidecar NOW — the same one the
+      // tunnel lazy-starts on first access — and hand back its host port.
+      if (!task.composeProject) return ok({ hostPort: null });
+      const hostPort = await ensurePreviewSidecar({
+        taskId,
+        composeProject: task.composeProject,
+        name,
+        containerPort,
+      });
+      return ok({ hostPort });
+    } catch (err) {
+      return failFromUnknown(err);
+    }
+  },
+
   async channelResolvePermission(ctx, taskId, agentId, requestId, decision) {
     logCommand(ctx, "channelResolvePermission", taskId, agentId, requestId);
     try {

package/src/main.ts

@@ -41,6 +41,8 @@ import {
   listProjectEnvKeys,
   setProjectEnvVar,
 } from "../lib/host-env";
+import { handleMcpOp } from "../lib/mcp-connections";
+import { startMcpGateway } from "../lib/mcp-gateway";
 import {
   packageVersion,
   serviceLogPath,
@@ -68,6 +70,7 @@ import { hostCommands, hostEvents } from "./index";
 import {
   HostErrorCode,
   type CloudToHost,
+  type McpOp,
   type CommandContext,
   type ChannelEnsureInput,
   type HostCapabilities,
@@ -147,6 +150,8 @@ connect();
 // Local browser UI (ADR-028) — same single process, alongside the WSS client.
 // Best-effort: a UI bind failure must not take the host service down.
 void startLocalUi();
+// ADR-057: the MCP gateway task containers reach via host.docker.internal.
+startMcpGateway();
 
 async function startLocalUi(): Promise<void> {
   try {
@@ -172,6 +177,7 @@ async function startLocalUi(): Promise<void> {
 /** Build the current host capability advertisement (ADR-021). */
 function buildCapabilities(): HostCapabilities {
   return {
+    version: packageVersion(),
     agentKinds: agentKindCapabilities(),
     runtimes: standardRuntimes(),
     githubUsers: connectedUserIds(),
@@ -331,6 +337,22 @@ function connect(): void {
         }
         break;
       }
+      case "mcp.op": {
+        // Async network work (discovery, DCR, exchange) — ack when done.
+        void handleMcpOp(frame.op)
+          .then((ack) =>
+            send(socket, { kind: "mcp.ack", opId: frame.opId, ok: true, ...ack }),
+          )
+          .catch((err: unknown) =>
+            send(socket, {
+              kind: "mcp.ack",
+              opId: frame.opId,
+              ok: false,
+              error: err instanceof Error ? err.message : "mcp op failed",
+            }),
+          );
+        break;
+      }
       case "env.var.list":
       case "env.var.set":
       case "env.var.delete": {
@@ -866,9 +888,24 @@ function dispatchCommand(
         expectString(args, 1),
         expectString(args, 2),
       );
+    case "previewEnsure":
+      return hostCommands.previewEnsure(
+        ctx,
+        expectString(args, 0),
+        expectString(args, 1),
+        expectNumberArg(args, 2),
+      );
   }
 }
 
+function expectNumberArg(args: unknown[], index: number): number {
+  const value = args[index];
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`invalid command args: expected number at ${index}`);
+  }
+  return value;
+}
+
 function parseCloudFrame(data: RawData): CloudToHost | null {
   let parsed: unknown;
   try {
@@ -1003,10 +1040,41 @@ function parseCloudFrame(data: RawData): CloudToHost | null {
       key: frame.key,
     };
   }
+  if (
+    frame.kind === "mcp.op" &&
+    typeof frame.opId === "string" &&
+    isMcpOp(frame.op)
+  ) {
+    return { kind: "mcp.op", opId: frame.opId, op: frame.op };
+  }
   console.warn("[host-agent] dropping unknown frame");
   return null;
 }
 
+/** ADR-057 op payload guard (parseCloudFrame whitelists every frame kind —
+ *  a new frame that skips this is silently dropped and acks time out). */
+function isMcpOp(op: unknown): op is McpOp {
+  if (!op || typeof op !== "object") return false;
+  const o = op as Record<string, unknown>;
+  const optStr = (v: unknown): boolean => v === undefined || typeof v === "string";
+  if (
+    o.kind === "probe" &&
+    typeof o.connectionId === "string" &&
+    typeof o.userId === "string" &&
+    typeof o.url === "string"
+  ) {
+    return [o.state, o.redirectUri, o.headerName, o.headerValue, o.clientId, o.clientSecret].every(optStr);
+  }
+  if (
+    o.kind === "oauth.complete" &&
+    typeof o.connectionId === "string" &&
+    typeof o.code === "string"
+  ) {
+    return true;
+  }
+  return o.kind === "disconnect" && typeof o.connectionId === "string";
+}
+
 function isReqLine(value: unknown): value is {
   method: string;
   url: string;
@@ -1057,6 +1125,7 @@ function isHostCommand(command: string): command is keyof HostCommands {
     "attachmentRead",
     "channelInterrupt",
     "appendTranscript",
+    "previewEnsure",
   ].includes(command);
 }
 
@@ -1232,6 +1301,39 @@ function expectChannelEnsureInput(
   if (typeof input.globalContext === "string") {
     out.globalContext = input.globalContext;
   }
+  // ADR-053: browser testing flag (optional; tolerant of absence).
+  if (input.browserTesting === true) out.browserTesting = true;
+  // ADR-049: humans in the chat (optional; tolerant of absence for older
+  // clouds). Malformed entries are dropped, not fatal.
+  if (Array.isArray(input.humans)) {
+    const humans = input.humans.flatMap((entry) => {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) return [];
+      const row = entry as Record<string, unknown>;
+      if (typeof row.handle !== "string" || typeof row.name !== "string") {
+        return [];
+      }
+      return [
+        {
+          handle: row.handle,
+          name: row.name,
+          isOwner: row.isOwner === true,
+        },
+      ];
+    });
+    if (humans.length > 0) out.humans = humans;
+  }
+  // ADR-057: the owner's MCP connections (optional; tolerant of absence).
+  // NOTE this validator is the THIRD whitelist a new field must pass, after
+  // parseCloudFrame/parseHostFrame — skipping it silently drops the field.
+  if (Array.isArray(input.mcpConnections)) {
+    const connections = input.mcpConnections.flatMap((entry) => {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) return [];
+      const row = entry as Record<string, unknown>;
+      if (typeof row.id !== "string" || typeof row.slug !== "string") return [];
+      return [{ id: row.id, slug: row.slug }];
+    });
+    if (connections.length > 0) out.mcpConnections = connections;
+  }
   return out;
 }
 

package/src/protocol.ts

@@ -67,6 +67,9 @@ export interface TaskAgent {
  * changes. The cloud caches it per hostId to drive the task-creation pickers.
  */
 export interface HostCapabilities {
+  /** The host-agent package version — the cloud UI shows it on the host page
+   *  and flags when npm has a newer release. Optional (older hosts omit it). */
+  version?: string;
   agentKinds: Array<{
     kind: string;
     label: string;
@@ -102,6 +105,10 @@ export interface TaskStatusResult {
   composeRunning: boolean;
   containers: string[];
   worktreePresent: boolean;
+  /** ADR-051: the task's published preview host ports (from the host DB), so
+   *  the cloud can backfill/refresh its mirror on reconcile. Optional for
+   *  wire back-compat with older hosts. */
+  previewPorts?: Array<{ name: string; hostPort: number }>;
 }
 
 export interface CloneRepoInput {
@@ -176,9 +183,26 @@ export interface TaskDiffInput {
   projects: Array<{ id: string; slug: string }>;
 }
 
+/** A human in the task chat (ADR-049) — owner or invited collaborator. */
+export interface ChannelHuman {
+  /** Per-task mention handle (`@diogo`), unique vs agent ids. */
+  handle: string;
+  name: string;
+  isOwner: boolean;
+}
+
 export interface ChannelEnsureInput {
   taskId: string;
   agents: TaskAgent[];
+  /** ADR-049: the humans in the chat. Optional for wire back-compat; absent
+   *  or single-entry behaves exactly like the pre-ADR-049 single-human task. */
+  humans?: ChannelHuman[];
+  /** ADR-053: any joined project opted into browser testing — the host wires
+   *  the Playwright MCP browser at session start. */
+  browserTesting?: boolean;
+  /** ADR-057: the owner's usable MCP connections (policy "on", connected,
+   *  remote). The host writes gateway-URL MCP configs at session start. */
+  mcpConnections?: Array<{ id: string; slug: string }>;
   globalContext?: string;
   projects: Array<{ slug: string; defaultPrompt: string }>;
   branch: string;
@@ -266,6 +290,19 @@ export interface HostCommands {
     requestId: string,
     decision: PermissionDecision,
   ): Promise<HostCommandResult<void>>;
+  /**
+   * ADR-051: make a preview reachable NOW and return its 127.0.0.1 host
+   * port — the task-up published port when one exists, else the lazy
+   * node-proxy sidecar's published port (started here instead of waiting
+   * for the first tunnel access). Backs the local URL in the preview menu.
+   * `hostPort: null` when the task isn't running / can't be exposed.
+   */
+  previewEnsure(
+    ctx: CommandContext,
+    taskId: string,
+    name: string,
+    containerPort: number,
+  ): Promise<HostCommandResult<{ hostPort: number | null }>>;
   cloneRepo(
     ctx: CommandContext,
     input: CloneRepoInput,
@@ -375,7 +412,38 @@ export type CloudToHost =
       key: string;
       value: string;
     }
-  | { kind: "env.var.delete"; opId: string; projectId: string; key: string };
+  | { kind: "env.var.delete"; opId: string; projectId: string; key: string }
+  // User-authed MCP connections (ADR-057). Ops run entirely host-side —
+  // discovery, DCR, PKCE, token exchange, encrypted storage. Secrets in a
+  // probe (headerValue, clientSecret) are write-only; nothing secret ever
+  // rides an ack. `opId` correlates request↔ack.
+  | { kind: "mcp.op"; opId: string; op: McpOp };
+
+/** One MCP-connection operation (ADR-057), executed by the host. */
+export type McpOp =
+  // Probe `url` (MCP initialize). No auth → connected. 401 → walk the OAuth
+  // discovery chain (RFC 9728 → 8414 → 7591), prepare PKCE, and ack
+  // `auth_required` + authorizeUrl (built with the cloud-minted `state`).
+  // A static-header connection passes headerName/Value instead and skips
+  // discovery. clientId/Secret are the manual fallback when the
+  // authorization server lacks DCR.
+  | {
+      kind: "probe";
+      connectionId: string;
+      userId: string;
+      url: string;
+      state?: string;
+      redirectUri?: string;
+      headerName?: string;
+      headerValue?: string;
+      clientId?: string;
+      clientSecret?: string;
+    }
+  // The vendor redirected back: exchange `code` with the PKCE verifier the
+  // host kept for this connection.
+  | { kind: "oauth.complete"; connectionId: string; code: string }
+  // Delete the connection's secrets. Gateway routes 401 immediately after.
+  | { kind: "disconnect"; connectionId: string };
 
 export type HostToCloud =
   | { kind: "auth"; token: string; hostId: string }
@@ -409,7 +477,19 @@ export type HostToCloud =
   // KEY NAMES only — values never cross the bridge (secret-blind, ADR-015).
   // `opId` correlates to the request.
   | { kind: "env.var.ack"; opId: string; ok: true; keys: string[] }
-  | { kind: "env.var.ack"; opId: string; ok: false; error: string };
+  | { kind: "env.var.ack"; opId: string; ok: false; error: string }
+  // Ack for mcp.op (ADR-057). `connected` = usable now; `auth_required` =
+  // open authorizeUrl in the user's browser and wait for the callback;
+  // `disconnected` = secrets gone. No secret material ever crosses back.
+  | {
+      kind: "mcp.ack";
+      opId: string;
+      ok: true;
+      status: "connected" | "auth_required" | "disconnected";
+      authorizeUrl?: string;
+      scopes?: string[];
+    }
+  | { kind: "mcp.ack"; opId: string; ok: false; error: string };
 
 export type HostEvent =
   | {