Carry an approval's persistence choice through elicitation (#1976)

* fix(mcp): pause active timeout during elicitation

* Carry an approval's persistence choice through elicitation

Codex Computer Use offers `persist: ["session", "always"]` in the terms of
its "Allow Computer Use to use X?" prompt and remembers the app only when
the answer names one. Executor lost the offer on the way in — the terms
projection kept strings only — and the choice on the way out, because every
adapter rebuilt the reply from `action` and `content`. So each accept was a
one-time approval and the same app prompted on every call.

- `ElicitationResponse.meta.persist` carries the choice; the vocabulary is
  closed so no host can grant more than the prompt offered.
- `approvalTerms` keeps string lists, so the offered scopes reach the host.
- The MCP plugin, the app-server bridge, and the MCP host (native mode)
  pass `_meta` through in both directions.
- The model-mode `resume` tool takes `persist`; the pause output names the
  offered scopes and says a bare accept is one-time.
- The HTTP resume API takes `persist`, and the browser approval page offers
  the scopes in a select. Nothing is chosen automatically.

Fixes #1962

* Preserve approval lifetime through browser and cloud resume paths

* Test approval waits beyond the MCP active-work deadline

* Test queue timeout with a controlled clock

* Test queue timeout with a controlled clock

---------

Co-authored-by: mikemikimike <13286568797@163.com>
Co-authored-by: Rhys Sullivan <39114868+RhysSullivan@users.noreply.github.com>

Author: 3 people

.changeset/computer-use-remembered-approvals.md

@@ -0,0 +1,14 @@
+---
+"@executor-js/sdk": patch
+"@executor-js/execution": patch
+"@executor-js/plugin-mcp": patch
+"@executor-js/api": patch
+"@executor-js/react": patch
+"@executor-js/host-mcp": patch
+"@executor-js/cloudflare": patch
+"executor": patch
+---
+
+Carry an approval's persistence choice through elicitation, so Codex Computer Use stops asking to use the same app on every call.
+
+Computer Use offers `persist: ["session", "always"]` in the prompt's terms and remembers the app only when the answer names one. Executor dropped the offer on the way in (the terms projection kept strings only) and the choice on the way out (every adapter rebuilt the reply from `action` and `content`), so each accept was one-time. `ElicitationResponse` now has `meta.persist`; the MCP plugin, the app-server bridge, and the MCP host pass it through; the model-mode `resume` tool and the browser approval page let the approver pick from the offered scopes. Nothing is chosen automatically: a bare accept still approves once.

apps/cloud/src/auth/api.ts

@@ -115,6 +115,7 @@ const McpSessionExecutionParams = {
 const ResumeMcpExecutionBody = Schema.Struct({
   action: Schema.Literals(["accept", "decline", "cancel"]),
   content: Schema.optional(Schema.Unknown),
+  persist: Schema.optional(Schema.String),
 });
 
 const McpPausedExecutionResponse = Schema.Struct({

apps/cloud/src/auth/handlers.ts

@@ -704,6 +704,9 @@ export const CloudSessionAuthHandlers = HttpApiBuilder.group(
               {
                 action: payload.action,
                 content: payload.content as Record<string, unknown> | undefined,
+                ...(payload.action === "accept" && payload.persist !== undefined
+                  ? { meta: { persist: payload.persist } }
+                  : {}),
               },
             ),
           );

apps/cloud/src/routes/app/resume.$executionId.tsx

@@ -37,13 +37,17 @@ function CloudMcpResumeApproval(props: { executionId: string; mcpSessionId: stri
       executionId: string,
       action: "accept" | "decline" | "cancel",
       content?: Record<string, unknown>,
+      persist?: string,
     ) =>
       doResume({
         params: {
           mcpSessionId: props.mcpSessionId,
           executionId,
         },
-        payload: action === "accept" ? { action, content: content ?? {} } : { action },
+        payload:
+          action === "accept"
+            ? { action, content: content ?? {}, ...(persist === undefined ? {} : { persist }) }
+            : { action },
       }),
     [doResume, props.mcpSessionId],
   );

e2e/scenarios/mcp-approval-persistence.test.ts

@@ -0,0 +1,80 @@
+import { randomBytes } from "node:crypto";
+import { expect } from "@effect/vitest";
+import { Effect } from "effect";
+import { composePluginApi } from "@executor-js/api/server";
+import { mcpHttpPlugin } from "@executor-js/plugin-mcp/api";
+import { makeElicitationMcpServer, serveMcpServer } from "@executor-js/plugin-mcp/testing";
+import { AuthTemplateSlug, ConnectionName, IntegrationSlug } from "@executor-js/sdk/shared";
+
+import { scenario } from "../src/scenario";
+import { Api, Browser, Mcp, Target } from "../src/services";
+import { parseBrowserApproval } from "../src/surfaces/mcp";
+import { visit } from "../src/surfaces/browser";
+
+const api = composePluginApi([mcpHttpPlugin()] as const);
+
+scenario(
+  "MCP · browser approval preserves the chosen lifetime and defaults to once",
+  { timeout: 180_000 },
+  Effect.scoped(
+    Effect.gen(function* () {
+      const target = yield* Target;
+      const browser = yield* Browser;
+      const mcp = yield* Mcp;
+      const { client: makeClient } = yield* Api;
+      const identity = yield* target.newIdentity();
+      const client = yield* makeClient(api, identity);
+      const slug = IntegrationSlug.make(`approval_terms_${randomBytes(4).toString("hex")}`);
+      const server = yield* serveMcpServer(makeElicitationMcpServer);
+      yield* client.mcp.addServer({
+        payload: {
+          transport: "remote",
+          name: "Approval terms",
+          endpoint: server.url,
+          slug,
+          remoteTransport: "streamable-http",
+        },
+      });
+      yield* Effect.gen(function* () {
+        yield* client.connections.create({
+          payload: {
+            owner: "org",
+            name: ConnectionName.make("main"),
+            integration: slug,
+            template: AuthTemplateSlug.make("none"),
+            value: "",
+          },
+        });
+        const session = mcp.session(identity, { elicitationMode: "browser" });
+        yield* session.listTools();
+        for (const scope of ["session", "always", ""] as const) {
+          const paused = yield* session.call("execute", {
+            code: `return await tools.${slug}.org.main.remembered_echo({value:"browser"});`,
+          });
+          const approval = parseBrowserApproval(paused);
+          const [resumed] = yield* Effect.all(
+            [
+              session.awaitResume(approval.executionId),
+              browser.session(identity, async ({ page, step }) => {
+                await step(`Approve ${scope || "once"} through the console`, async () => {
+                  await visit(page, approval.approvalUrl);
+                  const choice = page.getByLabel("Remember this approval");
+                  await choice.waitFor();
+                  expect(await choice.inputValue(), "every approval starts as one-time").toBe("");
+                  if (scope !== "") await choice.selectOption(scope);
+                  await page.getByRole("button", { name: "Approve", exact: true }).click();
+                  await page.getByText("Approve sent").waitFor();
+                });
+              }),
+            ],
+            { concurrency: "unbounded" },
+          );
+          expect(resumed.ok).toBe(true);
+          expect(resumed.text, "the chosen lifetime reaches the upstream MCP server").toContain(
+            `approved:browser:${scope || "once"}`,
+          );
+        }
+      }).pipe(Effect.ensuring(client.mcp.removeServer({ params: { slug } }).pipe(Effect.orDie)));
+    }),
+  ),
+);

e2e/selfhost/mcp-elicitation-deadline.test.ts

@@ -1,6 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { expect } from "@effect/vitest";
-import { Effect } from "effect";
+import { Effect, Schema } from "effect";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { composePluginApi } from "@executor-js/api/server";
 import { mcpHttpPlugin } from "@executor-js/plugin-mcp/api";
@@ -11,9 +11,10 @@ import { scenario } from "../src/scenario";
 import { Api, Mcp, Target } from "../src/services";
 
 const api = composePluginApi([mcpHttpPlugin()] as const);
+const decodeExecutionId = Schema.decodeUnknownSync(Schema.String);
 
 scenario(
-  "MCP · a human can approve after the active-work deadline without losing the tool call",
+  "MCP · delayed approval preserves the chosen lifetime beyond the active-work deadline",
   { timeout: 180_000 },
   Effect.scoped(
     Effect.gen(function* () {
@@ -31,10 +32,15 @@ scenario(
               mode: "form",
               message: "Approve the delayed call?",
               requestedSchema: { type: "object", properties: {} },
+              _meta: { persist: ["session", "always"] },
             },
             { timeout: 150_000 },
           );
-          return { content: [{ type: "text", text: `decision:${reply.action}` }] };
+          return {
+            content: [
+              { type: "text", text: `decision:${reply.action}:${reply._meta?.persist ?? "once"}` },
+            ],
+          };
         });
         return upstream;
       });
@@ -66,9 +72,14 @@ scenario(
         // Cross the production 60-second active-work deadline. This is the
         // behavior under test: a human waiting must consume none of that budget.
         yield* Effect.sleep("65 seconds");
-        const completed = yield* session.approvePaused(paused.text);
+        const executionId = decodeExecutionId(/\bexecutionId:\s*(\S+)/.exec(paused.text)?.[1]);
+        const completed = yield* session.call("resume", {
+          executionId,
+          action: "accept",
+          persist: "session",
+        });
         expect(completed.ok).toBe(true);
-        expect(completed.text).toContain("decision:accept");
+        expect(completed.text).toContain("decision:accept:session");
       }).pipe(Effect.ensuring(client.mcp.removeServer({ params: { slug } }).pipe(Effect.orDie)));
     }),
   ),

e2e/vitest.config.ts

@@ -48,6 +48,7 @@ export default defineConfig({
       project("cloudflare", {
         include: [
           "scenarios/browser-approval.test.ts",
+          "scenarios/mcp-approval-persistence.test.ts",
           "scenarios/microsoft-graph-full.test.ts",
           "scenarios/toolkits-mcp.test.ts",
           "cloudflare/**/*.test.ts",

packages/core/api/src/executions/api.ts

@@ -44,6 +44,10 @@ const ExecuteResponse = Schema.Union([CompletedResult, PausedResult]);
 const ResumeRequest = Schema.Struct({
   action: Schema.Literals(["accept", "decline", "cancel"]),
   content: Schema.optional(Schema.Unknown),
+  /** How long an accepted approval lasts, when the paused interaction's
+   *  terms offer a choice (`interaction.meta.persist` lists the scopes).
+   *  Omitted, the approval is for this call only. */
+  persist: Schema.optional(Schema.String),
 });
 
 const ResumeResponse = Schema.Union([CompletedResult, PausedResult]);

packages/core/api/src/handlers/executions.ts

@@ -251,6 +251,7 @@ export const ExecutionsHandlers = HttpApiBuilder.group(ExecutorApi, "executions"
             engine.resume(path.executionId, {
               action: payload.action,
               content: payload.content as Record<string, unknown> | undefined,
+              ...(payload.persist === undefined ? {} : { meta: { persist: payload.persist } }),
             }),
           );
 

packages/core/execution/src/engine.test.ts

@@ -279,6 +279,34 @@ describe("formatPausedExecution approval terms", () => {
     });
   });
 
+  it("says how to answer when the terms leave the approval's lifetime to the caller", () => {
+    // Computer Use's app approval: a bare accept is one-time and the same
+    // prompt returns on the next call, so the caller has to be told the
+    // scopes on offer and how to pick one.
+    const result = formatPausedExecution(
+      paused(
+        FormElicitation.make({
+          message: 'Allow Computer Use to use "Finder"?',
+          requestedSchema: {},
+          meta: { persist: ["session", "always"], connector_name: "Computer Use" },
+        }),
+      ),
+    );
+
+    const interaction = result.structured["interaction"] as {
+      readonly meta?: unknown;
+      readonly instructions: string;
+    };
+    expect(interaction.meta).toEqual({
+      persist: ["session", "always"],
+      connector_name: "Computer Use",
+    });
+    expect(interaction.instructions).toContain(
+      'pass persist as one of "session", "always"; without it the approval is for this call only',
+    );
+    expect(result.text).toContain(interaction.instructions);
+  });
+
   it("says nothing about terms when the upstream attached none", () => {
     const result = formatPausedExecution(
       paused(FormElicitation.make({ message: "Proceed?", requestedSchema: {} })),