@runuai/host 0.4.2 → 0.4.3

package/lib/standard-image.ts

@@ -17,7 +17,9 @@
  */
 
 import { spawn } from "node:child_process";
-import { dirname, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 /** Pinned, host-wide constants (must match task-up.sh and the compose gen). */
@@ -57,6 +59,40 @@ export function standardRuntimes(): Array<{
   }));
 }
 
+/** Image label carrying the build-context content hash (rebuild trigger). */
+const CONTEXT_HASH_LABEL = "com.runuai.context-hash";
+
+/**
+ * Content-hash the build context (every file under images/standard, sorted
+ * by relative path). Null when the context can't be read — the caller then
+ * keeps whatever image exists.
+ */
+async function hashBuildContext(): Promise<string | null> {
+  try {
+    const root = standardImageDir();
+    const files: string[] = [];
+    const walk = async (dir: string, prefix: string): Promise<void> => {
+      for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) await walk(join(dir, entry.name), rel);
+        else files.push(rel);
+      }
+    };
+    await walk(root, "");
+    files.sort();
+    const hash = createHash("sha256");
+    for (const rel of files) {
+      hash.update(rel);
+      hash.update("\0");
+      hash.update(await readFile(join(root, rel)));
+      hash.update("\0");
+    }
+    return hash.digest("hex").slice(0, 32);
+  } catch {
+    return null;
+  }
+}
+
 /** Absolute path to the standard image build context. */
 function standardImageDir(): string {
   const here = dirname(fileURLToPath(import.meta.url));
@@ -177,6 +213,55 @@ async function ensureVolumeAgentClis(): Promise<void> {
   }
 }
 
+/**
+ * Upgrade the shared volume's agent CLIs to latest — once per HOST START, not
+ * per task. Per-task installs would add npm latency to every task-up, race
+ * concurrent starts on the shared volume, and give a broken vendor release a
+ * fleet-wide blast radius with no rollback; host restarts are the deliberate
+ * update moment (sessions respawn then anyway, and a bad release is one
+ * `UAI_AGENT_CLI_AUTOUPDATE=0` + manual pin away from contained). Running
+ * sessions keep their already-loaded process; new spawns pick up the new bin.
+ * Best-effort: an offline registry just logs and keeps the current versions.
+ */
+async function upgradeVolumeAgentClis(): Promise<void> {
+  if (process.env.UAI_AGENT_CLI_AUTOUPDATE === "0") {
+    console.log("[host-agent] agent CLI auto-update disabled (UAI_AGENT_CLI_AUTOUPDATE=0)");
+    return;
+  }
+  const pkgs = VOLUME_AGENT_CLIS.map((c) => `${c.pkg}@latest`).join(" ");
+  const bins = VOLUME_AGENT_CLIS.map((c) => c.bin);
+  // npm's in-place upgrade renames the old package dir, which fails with
+  // ENOTEMPTY while (or right after) live sessions held it open through the
+  // volume. Fallback: remove the scoped dirs and install fresh — safe at host
+  // start, when the previous sessions' execs are gone.
+  const scopeDirs = "/opt/asdf-data/installs/nodejs/*/lib/node_modules/@anthropic-ai /opt/asdf-data/installs/nodejs/*/lib/node_modules/@openai";
+  const upgrade = await run("docker", [
+    "run",
+    "--rm",
+    "-u",
+    "root",
+    "-w",
+    "/home/node",
+    "-v",
+    `${ASDF_DATA_VOLUME}:/opt/asdf-data`,
+    STANDARD_IMAGE_TAG,
+    "bash",
+    "-lc",
+    `npm install -g ${pkgs} >/dev/null 2>&1 || { rm -rf ${scopeDirs}; npm install -g ${pkgs} >/dev/null 2>&1; } && asdf reshim nodejs >/dev/null 2>&1; ` +
+      bins.map((b) => `printf '%s ' "$(${b} --version 2>/dev/null | head -1)"`).join("; "),
+  ]);
+  if (upgrade.code === 0) {
+    console.log(
+      `[host-agent] agent CLIs current on ${ASDF_DATA_VOLUME}: ${upgrade.stdout.trim()}`,
+    );
+  } else {
+    console.warn(
+      `[host-agent] agent CLI upgrade skipped (exit ${upgrade.code ?? "spawn"}) — ` +
+        `tasks keep the volume's current versions. ${upgrade.stderr.trim().slice(0, 200)}`,
+    );
+  }
+}
+
 /**
  * Ensure the standard image and the shared asdf data volume exist, and that the
  * agent CLIs are present inside the volume. Builds the image only when `docker
@@ -196,24 +281,51 @@ export async function ensureStandardImage(): Promise<void> {
     if (vol.code === null) return;
   }
 
-  // 2. Ensure the image is built.
+  // 2. Ensure the image is built AND current. "Present" is not enough — a
+  //    Dockerfile change used to no-op forever because we only built when
+  //    inspect failed (found live 2026-07-08: ADR-053's baked packages never
+  //    landed). The build context is content-hashed into an image label;
+  //    a mismatch triggers a rebuild (layer cache keeps it cheap).
   let imageReady = false;
-  const inspect = await run("docker", ["image", "inspect", STANDARD_IMAGE_TAG]);
-  if (inspect.code === 0) {
-    console.log(`[host-agent] standard image ${STANDARD_IMAGE_TAG} present`);
-    imageReady = true;
-  } else if (inspect.code === null) {
+  const contextHash = await hashBuildContext();
+  const inspect = await run("docker", [
+    "image",
+    "inspect",
+    "-f",
+    `{{index .Config.Labels "${CONTEXT_HASH_LABEL}"}}`,
+    STANDARD_IMAGE_TAG,
+  ]);
+  if (inspect.code === null) {
     console.warn(
       "[host-agent] docker unavailable; skipping standard image build. " +
         "Tasks will fail until docker is running.",
     );
     return;
+  }
+  const labeledHash = inspect.code === 0 ? inspect.stdout.trim() : null;
+  if (inspect.code === 0 && contextHash !== null && labeledHash === contextHash) {
+    console.log(`[host-agent] standard image ${STANDARD_IMAGE_TAG} current`);
+    imageReady = true;
+  } else if (inspect.code === 0 && contextHash === null) {
+    // Can't hash (packaged install without the context?) — keep the image.
+    console.log(`[host-agent] standard image ${STANDARD_IMAGE_TAG} present`);
+    imageReady = true;
   } else {
     const context = standardImageDir();
     console.log(
-      `[host-agent] building standard image ${STANDARD_IMAGE_TAG} from ${context}`,
+      inspect.code === 0
+        ? `[host-agent] standard image ${STANDARD_IMAGE_TAG} stale (context changed) — rebuilding from ${context}`
+        : `[host-agent] building standard image ${STANDARD_IMAGE_TAG} from ${context}`,
     );
-    const build = await run("docker", ["build", "-t", STANDARD_IMAGE_TAG, context]);
+    const build = await run("docker", [
+      "build",
+      "-t",
+      STANDARD_IMAGE_TAG,
+      ...(contextHash !== null
+        ? ["--label", `${CONTEXT_HASH_LABEL}=${contextHash}`]
+        : []),
+      context,
+    ]);
     if (build.code === 0) {
       console.log(`[host-agent] built standard image ${STANDARD_IMAGE_TAG}`);
       imageReady = true;
@@ -223,10 +335,15 @@ export async function ensureStandardImage(): Promise<void> {
           "continuing. Tasks needing the image will surface this error.\n" +
           build.stderr.trim(),
       );
+      // A stale-but-working image is better than none.
+      imageReady = labeledHash !== null;
     }
   }
 
   // 3. Reconcile the agent CLIs into the shared volume (it shadows the image's
   //    shims, so a stale volume can be missing one — the claude-127 bug).
-  if (imageReady) await ensureVolumeAgentClis();
+  if (imageReady) {
+    await ensureVolumeAgentClis();
+    await upgradeVolumeAgentClis();
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Uai host — runs ephemeral AI coding tasks in Docker on a machine you control.",
   "license": "MIT",
   "author": "Diogo Perillo <diogo.perillo@gmail.com>",

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 =
   | {