e2e: browser-approval scenarios on cloud + browser-mode MCP surface

Adds the first end-to-end coverage of a human approving/declining a
gated MCP action in the rendered console approval page — the leg unit
tests structurally cannot reach.

- MCP surface: a session can run in elicitation_mode=browser, exposes
  awaitResume (the no-action long-poll resume), and parseBrowserApproval
  pulls the {executionId, approvalUrl} out of a paused result.
- Surface fix: give each MCP session a unique mcporter server name.
  mcporter caches OAuth tokens per server name, so the old constant name
  let a later session reuse an earlier identity's token (wrong org). A
  decline scenario was the first identity-sensitive flow to expose it.
- cloud/browser-approval.test.ts: approve runs the gated tool to
  completion; decline blocks it. Moves to scenarios/ once self-host and
  Cloudflare gain the feature.

Author: RhysSullivan

e2e/cloud/browser-approval.test.ts

@@ -0,0 +1,153 @@
+// Browser approval of a gated MCP action, end to end through the real console.
+//
+// A `require_approval` policy turns a built-in tool into an action that pauses
+// for a human. The MCP session runs in `elicitation_mode=browser`, so the gated
+// `execute` does not let the model resume inline — it pauses and hands back an
+// `approvalUrl`. A real browser (signed in as the same identity) opens that
+// console page and clicks Approve / Decline; meanwhile `resume` long-polls for
+// the decision. Approve lets the tool run and return its result; Decline blocks
+// it. This is the leg unit tests structurally cannot cover: a human clicking the
+// button in the rendered ResumeApprovalPage.
+//
+// The policy is removed in an `ensuring` finalizer — a leaked require_approval
+// gate on a shared built-in tool would pause unrelated scenarios.
+//
+// Lives under cloud/ for now because cloud is the only host wired for browser
+// approval; it moves to scenarios/ (cross-target) as self-host and Cloudflare
+// gain the feature.
+import { expect } from "@effect/vitest";
+import { Effect } from "effect";
+import { composePluginApi } from "@executor-js/api/server";
+
+import { scenario } from "../src/scenario";
+import { Api, Browser, Mcp, Target } from "../src/services";
+import { type McpBrowserApproval, parseBrowserApproval } from "../src/surfaces/mcp";
+import type { BrowserSurface } from "../src/surfaces/browser";
+import type { Identity } from "../src/target";
+
+const coreApi = composePluginApi([] as const);
+
+// Gating a built-in read tool keeps the scenario hermetic — no external server
+// to host a destructive tool. The gate, not the tool, is what's under test: any
+// action the engine pauses on flows through the same approval path.
+const GATE_TOOL = "executor.coreTools.policies.list";
+
+// The gated call returns the policy listing, which includes the policy we just
+// created — so the created policy's id appears in the result iff the tool
+// actually ran (i.e. the human approved).
+const GATED_CODE = `
+const result = await tools.executor.coreTools.policies.list({});
+return JSON.stringify(result);
+`;
+
+/** Open the console approval page as `identity` and click Approve or Decline. */
+const decideInBrowser = (
+  browser: BrowserSurface,
+  identity: Identity,
+  approval: McpBrowserApproval,
+  decision: "Approve" | "Decline",
+): Effect.Effect<void> =>
+  browser.session(identity, async ({ page, step }) => {
+    await step(
+      `Open the approval page and ${decision.toLowerCase()} the paused action`,
+      async () => {
+        await page.goto(approval.approvalUrl, { waitUntil: "networkidle" });
+        await page.getByRole("button", { name: decision }).click();
+        // The page confirms the decision was recorded ("Approve sent" / "Decline sent").
+        await page.getByText(`${decision} sent`).waitFor();
+      },
+    );
+  });
+
+scenario(
+  "MCP · a gated action approved in the browser runs to completion",
+  { timeout: 180_000 },
+  Effect.gen(function* () {
+    const target = yield* Target;
+    const api = yield* Api;
+    const browser = yield* Browser;
+    const mcp = yield* Mcp;
+    const identity = yield* target.newIdentity();
+    const client = yield* api.client(coreApi, identity);
+
+    const policy = yield* client.policies.create({
+      payload: { owner: "org", pattern: GATE_TOOL, action: "require_approval" },
+    });
+
+    yield* Effect.gen(function* () {
+      const session = mcp.session(identity, { elicitationMode: "browser" });
+      const tools = yield* session.listTools();
+      expect(tools).toContain("execute");
+
+      const paused = yield* session.call("execute", { code: GATED_CODE });
+      const approval = parseBrowserApproval(paused);
+      expect(approval.approvalUrl, "approval URL targets the resume page").toContain(
+        `/resume/${approval.executionId}`,
+      );
+
+      // `resume` blocks for the human's decision; approve it in the browser
+      // concurrently, then the resumed call returns the gated tool's result.
+      const [resumed] = yield* Effect.all(
+        [
+          session.awaitResume(approval.executionId),
+          decideInBrowser(browser, identity, approval, "Approve"),
+        ],
+        { concurrency: "unbounded" },
+      );
+
+      expect(resumed.ok, "the approved execution completed without error").toBe(true);
+      expect(resumed.text, "the gated tool ran and returned the policy listing").toContain(
+        policy.id,
+      );
+    }).pipe(
+      Effect.ensuring(
+        client.policies
+          .remove({ params: { policyId: policy.id }, payload: { owner: "org" } })
+          .pipe(Effect.ignore),
+      ),
+    );
+  }),
+);
+
+scenario(
+  "MCP · a gated action declined in the browser is blocked",
+  { timeout: 180_000 },
+  Effect.gen(function* () {
+    const target = yield* Target;
+    const api = yield* Api;
+    const browser = yield* Browser;
+    const mcp = yield* Mcp;
+    const identity = yield* target.newIdentity();
+    const client = yield* api.client(coreApi, identity);
+
+    const policy = yield* client.policies.create({
+      payload: { owner: "org", pattern: GATE_TOOL, action: "require_approval" },
+    });
+
+    yield* Effect.gen(function* () {
+      const session = mcp.session(identity, { elicitationMode: "browser" });
+      yield* session.listTools();
+
+      const paused = yield* session.call("execute", { code: GATED_CODE });
+      const approval = parseBrowserApproval(paused);
+
+      const [resumed] = yield* Effect.all(
+        [
+          session.awaitResume(approval.executionId),
+          decideInBrowser(browser, identity, approval, "Decline"),
+        ],
+        { concurrency: "unbounded" },
+      );
+
+      // The decision propagated (resume returned rather than hanging) and the
+      // gated tool never ran — its output (the policy id) is absent.
+      expect(resumed.text, "the gated tool did not run after a decline").not.toContain(policy.id);
+    }).pipe(
+      Effect.ensuring(
+        client.policies
+          .remove({ params: { policyId: policy.id }, payload: { owner: "org" } })
+          .pipe(Effect.ignore),
+      ),
+    );
+  }),
+);

e2e/src/surfaces/mcp.ts

@@ -94,6 +94,42 @@ export interface McpCallResult {
   readonly ok: boolean;
 }
 
+/** How a connection surfaces a paused (approval-gated) execution. `browser` is
+ *  what the browser-approval scenarios drive: the pause yields an `approvalUrl`
+ *  for a human to open instead of letting the model resume inline. */
+export type McpElicitationMode = "browser" | "model" | "native";
+
+/** The paused-execution handle a `browser`-mode call returns: the id to resume
+ *  and the console URL a human opens to approve or decline it. */
+export interface McpBrowserApproval {
+  readonly executionId: string;
+  readonly approvalUrl: string;
+}
+
+/**
+ * Pull the `{ executionId, approvalUrl }` out of a `browser`-mode paused result.
+ * Throws if the call did not pause for approval (so a missing gate fails loudly
+ * rather than silently skipping the browser leg).
+ */
+export const parseBrowserApproval = (result: McpCallResult): McpBrowserApproval => {
+  const structured = (result.raw as { structuredContent?: unknown })?.structuredContent;
+  const record = (structured ?? {}) as {
+    status?: unknown;
+    executionId?: unknown;
+    approvalUrl?: unknown;
+  };
+  if (
+    record.status !== "user_approval_required" ||
+    typeof record.executionId !== "string" ||
+    typeof record.approvalUrl !== "string"
+  ) {
+    throw new Error(
+      `expected a browser approval-required result, got: ${JSON.stringify(structured)}`,
+    );
+  }
+  return { executionId: record.executionId, approvalUrl: record.approvalUrl };
+};
+
 export interface McpSession {
   readonly listTools: () => Effect.Effect<ReadonlyArray<string>>;
   readonly call: (name: string, args?: Record<string, unknown>) => Effect.Effect<McpCallResult>;
@@ -102,12 +138,21 @@ export interface McpSession {
     text: string,
     content?: Record<string, unknown>,
   ) => Effect.Effect<McpCallResult>;
+  /**
+   * Call `resume` with only an executionId — the browser-mode contract, where
+   * `resume` long-polls until a human records a decision through the console.
+   * Run this concurrently with the browser leg that approves/declines.
+   */
+  readonly awaitResume: (executionId: string) => Effect.Effect<McpCallResult>;
 }
 
 export interface McpSurface {
   /** The target's MCP endpoint — yield this surface to depend on it existing. */
   readonly url: string;
-  readonly session: (identity: Identity) => McpSession;
+  readonly session: (
+    identity: Identity,
+    options?: { readonly elicitationMode?: McpElicitationMode },
+  ) => McpSession;
   /**
    * Mint a real MCP bearer headlessly: protected-resource discovery →
    * authorization-server discovery → dynamic client registration → authorize
@@ -206,9 +251,20 @@ const mintBearerFlow = async (target: Target, email: string): Promise<string> =>
 export const makeMcpSurface = (target: Target, runDir?: string): McpSurface => ({
   url: target.mcpUrl,
   mintBearer: (email) => Effect.promise(() => mintBearerFlow(target, email)),
-  session: (identity) => {
+  session: (identity, options) => {
     if (runDir) installTraceparentFetch(target.mcpUrl, runDir);
-    const serverName = target.name;
+    // mcporter caches OAuth tokens (and the DCR client) per server NAME, so a
+    // constant name would let a later session reuse an earlier identity's token
+    // — landing in the wrong org. A unique name per session keeps each
+    // identity's OAuth isolated. The traceparent ledger keys off the URL, not
+    // this name, so it is unaffected.
+    const serverName = `${target.name}-${randomUUID().slice(0, 8)}`;
+    // `browser` mode is selected per the ecosystem convention — an
+    // `?elicitation_mode=` query on the MCP endpoint — so a paused execution
+    // yields an approvalUrl instead of letting the model resume inline.
+    const sessionUrl = options?.elicitationMode
+      ? `${target.mcpUrl}?elicitation_mode=${options.elicitationMode}`
+      : target.mcpUrl;
     let runtimePromise: Promise<Runtime> | undefined;
     let connected = false;
 
@@ -224,7 +280,7 @@ export const makeMcpSurface = (target: Target, runDir?: string): McpSurface => (
         writeFileSync(
           join(dir, "mcporter.json"),
           JSON.stringify({
-            mcpServers: { [serverName]: { url: target.mcpUrl } },
+            mcpServers: { [serverName]: { url: sessionUrl } },
           }),
         );
         runtimePromise = createRuntime({
@@ -265,6 +321,9 @@ export const makeMcpSurface = (target: Target, runDir?: string): McpSurface => (
             content: JSON.stringify(content),
           });
         }),
+      // No action argument: in browser mode `resume` blocks until the human's
+      // decision arrives via the console, then returns the resumed result.
+      awaitResume: (executionId) => call("resume", { executionId }),
     };
   },
 });