@@ -45,6 +68,39 @@ export const SetupMcpPage = () => {
Paste this into your MCP client config.
+
+
+ Advanced
+
+ v
+
+
+
+
+
+
Resume approvals
+
+ Select how tool approvals are handled for this MCP connection.
+
+
+
setElicitationMode(event.target.value as McpElicitationMode)}
+ aria-label="Elicitation mode"
+ className="min-w-44"
+ >
+ Browser approval
+ Model resume tool
+ Native elicitation
+
+
+
or
diff --git a/apps/local/src/serve.test.ts b/apps/local/src/serve.test.ts
index 2f364c42f..9aa471ec0 100644
--- a/apps/local/src/serve.test.ts
+++ b/apps/local/src/serve.test.ts
@@ -20,6 +20,7 @@ const startTestServer = async (): Promise
=> {
},
mcp: {
handleRequest: async () => new Response("ok"),
+ handleApprovalRequest: async () => new Response("ok"),
close: async () => {},
},
},
@@ -78,6 +79,7 @@ describe("startServer network bind auth", () => {
},
mcp: {
handleRequest: async () => new Response("ok"),
+ handleApprovalRequest: async () => new Response("ok"),
close: async () => {},
},
},
@@ -98,6 +100,7 @@ describe("startServer network bind auth", () => {
},
mcp: {
handleRequest: async () => new Response("ok"),
+ handleApprovalRequest: async () => new Response("ok"),
close: async () => {},
},
},
diff --git a/apps/local/src/serve.ts b/apps/local/src/serve.ts
index 187a3b12d..11aa5e3bd 100644
--- a/apps/local/src/serve.ts
+++ b/apps/local/src/serve.ts
@@ -168,6 +168,10 @@ export async function startServer(opts: StartServerOptions = {}): Promise ({
+ id: "browser-resume-test" as const,
+ storage: () => ({}),
+ staticSources: () => [
+ {
+ id: "api",
+ kind: "in-memory",
+ name: "API",
+ tools: [
+ {
+ name: "singleApproval",
+ description: "Elicit exactly once and return the user's response.",
+ inputSchema: EmptyInputSchema,
+ handler: ({ elicit }) =>
+ Effect.gen(function* () {
+ const response = yield* elicit(
+ FormElicitation.make({
+ message: "Approve browser-resume test call",
+ requestedSchema: {
+ type: "object",
+ properties: {
+ note: { type: "string", title: "Approval note" },
+ },
+ required: ["note"],
+ },
+ }),
+ );
+ return { ok: true, response };
+ }),
+ },
+ ],
+ },
+ ],
+}));
+
+const makeExecutor = async (tmpDir: string): Promise => {
+ const plugins = [approvalPlugin()] as const;
+ const sqlite = await createSqliteFumaDb({
+ tables: collectTables(plugins),
+ namespace: "executor_local_browser_resume_test",
+ path: join(tmpDir, "data.db"),
+ });
+ const scope = Scope.make({
+ id: ScopeId.make(`test-${randomBytes(4).toString("hex")}`),
+ name: "test",
+ createdAt: new Date(),
+ });
+ const executor = await Effect.runPromise(
+ createExecutor({
+ scopes: [scope],
+ db: sqlite.db,
+ plugins,
+ onElicitation: "accept-all",
+ }),
+ );
+
+ const close = executor.close;
+ return {
+ ...executor,
+ close: () =>
+ Effect.gen(function* () {
+ yield* close();
+ yield* Effect.promise(() => sqlite.close());
+ }),
+ };
+};
+
+const makeMcpFetch = (executor: Executor) => {
+ const engine = createExecutionEngine({ executor, codeExecutor: makeQuickJsExecutor() });
+ const mcp = createMcpRequestHandler({ engine });
+
+ const fetchImpl: typeof globalThis.fetch = Object.assign(
+ (input: RequestInfo | URL, init?: RequestInit) => {
+ const request = input instanceof Request ? input : new Request(input, init);
+ const url = new URL(request.url);
+ if (url.pathname.startsWith("/mcp")) return mcp.handleRequest(request);
+ if (url.pathname.startsWith("/api/mcp-sessions/")) {
+ return mcp.handleApprovalRequest(request);
+ }
+ return Promise.resolve(new Response("Not found", { status: 404 }));
+ },
+ { preconnect: globalThis.fetch.preconnect },
+ );
+
+ return { fetch: fetchImpl, dispose: mcp.close };
+};
+
+const readStructuredRecord = (value: unknown): Record => {
+ expect(typeof value).toBe("object");
+ expect(value).not.toBeNull();
+ return value as Record;
+};
+
+const readApproval = (structured: unknown): { readonly executionId: string; readonly url: URL } => {
+ const record = readStructuredRecord(structured);
+ expect(record.status).toBe("user_approval_required");
+ expect(record).not.toHaveProperty("interaction");
+ expect(typeof record.executionId).toBe("string");
+ expect(typeof record.approvalUrl).toBe("string");
+ const { executionId, approvalUrl } = record as {
+ readonly executionId: string;
+ readonly approvalUrl: string;
+ };
+ return {
+ executionId,
+ url: new URL(approvalUrl),
+ };
+};
+
+const readResultArray = (structured: unknown): ReadonlyArray => {
+ const record = readStructuredRecord(structured);
+ expect(record.status).toBe("completed");
+ expect(Array.isArray(record.result)).toBe(true);
+ return record.result as ReadonlyArray;
+};
+
+describe("local MCP browser approval resume", () => {
+ it("continues multiple elicitations from one MCP execute call through the HTTP API path", async () => {
+ const tmpDir = mkdtempSync(join(tmpdir(), "executor-local-browser-resume-"));
+ const executor = await makeExecutor(tmpDir);
+ const { fetch, dispose } = makeMcpFetch(executor);
+ const mcpClient = new Client(
+ { name: "browser-resume-test-client", version: "1.0.0" },
+ { capabilities: {} },
+ );
+ const transport = new StreamableHTTPClientTransport(new URL("/mcp", TEST_BASE_URL), { fetch });
+
+ await mcpClient.connect(transport);
+
+ // oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: test owns MCP transports, web handler, and executor lifecycle
+ try {
+ const first = await mcpClient.callTool({
+ name: "execute",
+ arguments: {
+ code: `
+ return await Promise.all([
+ tools.api.singleApproval({}),
+ tools.api.singleApproval({}),
+ tools.api.singleApproval({})
+ ]);
+ `,
+ },
+ });
+
+ expect(first.isError).toBeFalsy();
+ const firstApproval = readApproval(first.structuredContent);
+
+ const second = await approveInBrowserThenResume(fetch, mcpClient, firstApproval);
+ const secondApproval = readApproval(second.structuredContent);
+ expect(secondApproval.executionId).not.toBe(firstApproval.executionId);
+
+ const third = await approveInBrowserThenResume(fetch, mcpClient, secondApproval);
+ const thirdApproval = readApproval(third.structuredContent);
+ expect(thirdApproval.executionId).not.toBe(firstApproval.executionId);
+ expect(thirdApproval.executionId).not.toBe(secondApproval.executionId);
+
+ const completed = await approveInBrowserThenResume(fetch, mcpClient, thirdApproval);
+ const result = readResultArray(completed.structuredContent);
+ expect(result).toHaveLength(3);
+ expect(result).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ data: expect.objectContaining({
+ response: expect.objectContaining({
+ action: "accept",
+ content: expect.objectContaining({ note: expect.stringContaining("approved-") }),
+ }),
+ }),
+ }),
+ ]),
+ );
+ } finally {
+ await mcpClient.close();
+ await Effect.runPromise(Effect.ignore(Effect.tryPromise(() => dispose())));
+ await Effect.runPromise(
+ Effect.ignore(Effect.tryPromise(() => Effect.runPromise(executor.close()))),
+ );
+ rmSync(tmpDir, { recursive: true, force: true });
+ }
+ }, 10_000);
+});
+
+const approveInBrowserThenResume = async (
+ fetch: typeof globalThis.fetch,
+ client: Client,
+ approval: { readonly executionId: string; readonly url: URL },
+) => {
+ const sessionId = approval.url.searchParams.get("mcp_session_id");
+ expect(sessionId).not.toBeNull();
+
+ const approvalResponse = await fetch(
+ new URL(
+ `/api/mcp-sessions/${encodeURIComponent(sessionId!)}/executions/${encodeURIComponent(approval.executionId)}/resume`,
+ TEST_BASE_URL,
+ ),
+ {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify({
+ action: "accept",
+ content: { note: `approved-${approval.executionId}` },
+ }),
+ },
+ );
+ expect(approvalResponse.status).toBe(200);
+
+ return await client.callTool({
+ name: "resume",
+ arguments: { executionId: approval.executionId },
+ });
+};
diff --git a/apps/local/src/server/mcp.ts b/apps/local/src/server/mcp.ts
index b17c800bb..000f05508 100644
--- a/apps/local/src/server/mcp.ts
+++ b/apps/local/src/server/mcp.ts
@@ -1,9 +1,10 @@
-import { Effect } from "effect";
+import { Effect, Option, Schema } from "effect";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
import { createExecutorMcpServer, type ExecutorMcpServerConfig } from "@executor-js/host-mcp";
+import type { ResumeResponse } from "@executor-js/execution";
import { startIntegrationsRefresh } from "./integrations";
@@ -13,6 +14,7 @@ import { startIntegrationsRefresh } from "./integrations";
export type McpRequestHandler = {
readonly handleRequest: (request: Request) => Promise;
+ readonly handleApprovalRequest: (request: Request) => Promise;
readonly close: () => Promise;
};
@@ -28,6 +30,35 @@ const formatBoundaryError = (error: unknown): unknown => {
return error;
};
+type McpElicitationMode = "browser" | "model" | "native";
+
+const MCP_ELICITATION_MODES = new Set(["browser", "model", "native"]);
+const ResumeResponsePayload = Schema.Struct({
+ action: Schema.Literals(["accept", "decline", "cancel"]),
+ content: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+});
+const decodeResumeResponsePayload = Schema.decodeUnknownOption(ResumeResponsePayload);
+
+const readElicitationMode = (request: Request): McpElicitationMode => {
+ const url = new URL(request.url);
+ const mode = url.searchParams.get("elicitation_mode");
+ if (mode && MCP_ELICITATION_MODES.has(mode as McpElicitationMode)) {
+ return mode as McpElicitationMode;
+ }
+
+ return "browser";
+};
+
+const approvalUrlForRequest = (
+ request: Request,
+ executionId: string,
+ sessionId: string | null,
+): string => {
+ const url = new URL(`/resume/${encodeURIComponent(executionId)}`, request.url);
+ if (sessionId) url.searchParams.set("mcp_session_id", sessionId);
+ return url.toString();
+};
+
const ignoreClose = (close: (() => Promise) | undefined): Promise =>
close
? Effect.runPromise(
@@ -40,15 +71,57 @@ const ignoreClose = (close: (() => Promise) | undefined): Promise =>
)
: Promise.resolve();
+const approvalRequestPattern = /^\/api\/mcp-sessions\/([^/?#]+)\/executions\/([^/?#]+)\/resume$/;
+
+const json = (value: unknown, status = 200): Response =>
+ new Response(JSON.stringify(value), {
+ status,
+ headers: { "content-type": "application/json" },
+ });
+
+const readResumeResponse = (request: Request): Promise =>
+ Effect.runPromise(
+ Effect.tryPromise({
+ try: () => request.json(),
+ catch: () => null,
+ }).pipe(
+ Effect.map((raw) =>
+ raw === null ? null : Option.getOrNull(decodeResumeResponsePayload(raw)),
+ ),
+ ),
+ );
+
+const resumeApprovalResult = (executionId: string, response: ResumeResponse) => {
+ const textByAction = {
+ accept: "I've approved it",
+ decline: "I've denied it",
+ cancel: "I've canceled it",
+ } satisfies Record;
+ const statusByAction = {
+ accept: "approved",
+ decline: "denied",
+ cancel: "canceled",
+ } satisfies Record;
+
+ return {
+ status: "completed",
+ text: textByAction[response.action],
+ structured: { status: statusByAction[response.action], executionId },
+ isError: false,
+ };
+};
+
export const createMcpRequestHandler = (config: ExecutorMcpServerConfig): McpRequestHandler => {
const transports = new Map();
const servers = new Map();
+ const approvalResponses = new Map>();
const dispose = async (id: string, opts: { transport?: boolean; server?: boolean } = {}) => {
const t = transports.get(id);
const s = servers.get(id);
transports.delete(id);
servers.delete(id);
+ approvalResponses.delete(id);
if (opts.transport) await ignoreClose(t ? () => t.close() : undefined);
if (opts.server) await ignoreClose(s ? () => s.close() : undefined);
};
@@ -64,10 +137,12 @@ export const createMcpRequestHandler = (config: ExecutorMcpServerConfig): McpReq
}
let created: McpServer | undefined;
+ let createdSessionId: string | null = null;
const transport = new WebStandardStreamableHTTPServerTransport({
sessionIdGenerator: () => crypto.randomUUID(),
enableJsonResponse: true,
onsessioninitialized: (sid) => {
+ createdSessionId = sid;
transports.set(sid, transport);
if (created) servers.set(sid, created);
},
@@ -81,7 +156,30 @@ export const createMcpRequestHandler = (config: ExecutorMcpServerConfig): McpReq
// oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: MCP SDK handler must return JSON-RPC errors from thrown Promise APIs
try {
- created = await Effect.runPromise(createExecutorMcpServer(config));
+ const elicitationMode = readElicitationMode(request);
+ created = await Effect.runPromise(
+ createExecutorMcpServer({
+ ...config,
+ browserApprovalStore: {
+ takeResponse: (executionId) =>
+ Effect.sync(() => {
+ if (!createdSessionId) return null;
+ const sessionApprovals = approvalResponses.get(createdSessionId);
+ const response = sessionApprovals?.get(executionId) ?? null;
+ sessionApprovals?.delete(executionId);
+ return response;
+ }),
+ },
+ elicitationMode:
+ elicitationMode === "browser"
+ ? {
+ mode: "browser" as const,
+ approvalUrl: (executionId) =>
+ approvalUrlForRequest(request, executionId, createdSessionId),
+ }
+ : { mode: elicitationMode },
+ }),
+ );
await created.connect(transport);
const response = await transport.handleRequest(request);
@@ -102,6 +200,27 @@ export const createMcpRequestHandler = (config: ExecutorMcpServerConfig): McpReq
}
},
+ handleApprovalRequest: async (request) => {
+ const url = new URL(request.url);
+ const match = approvalRequestPattern.exec(url.pathname);
+ if (!match) return json({ error: "Not found" }, 404);
+ if (request.method !== "POST") return json({ error: "Method not allowed" }, 405);
+
+ const sessionId = decodeURIComponent(match[1]);
+ const executionId = decodeURIComponent(match[2]);
+ if (!servers.has(sessionId)) return json({ error: "MCP session not found" }, 404);
+
+ const response = await readResumeResponse(request);
+ if (!response) return json({ error: "Invalid approval response" }, 400);
+
+ const sessionApprovals =
+ approvalResponses.get(sessionId) ?? new Map();
+ sessionApprovals.set(executionId, response);
+ approvalResponses.set(sessionId, sessionApprovals);
+
+ return json(resumeApprovalResult(executionId, response));
+ },
+
close: async () => {
const ids = new Set([...transports.keys(), ...servers.keys()]);
await Promise.all([...ids].map((id) => dispose(id, { transport: true, server: true })));
diff --git a/packages/app/src/routeTree.gen.ts b/packages/app/src/routeTree.gen.ts
index d238fcfda..706fc9d11 100644
--- a/packages/app/src/routeTree.gen.ts
+++ b/packages/app/src/routeTree.gen.ts
@@ -15,6 +15,7 @@ import { Route as PoliciesRouteImport } from './routes/policies'
import { Route as ConnectionsRouteImport } from './routes/connections'
import { Route as IndexRouteImport } from './routes/index'
import { Route as SourcesNamespaceRouteImport } from './routes/sources.$namespace'
+import { Route as ResumeExecutionIdRouteImport } from './routes/resume.$executionId'
import { Route as SourcesAddPluginKeyRouteImport } from './routes/sources.add.$pluginKey'
import { Route as PluginsPluginIdSplatRouteImport } from './routes/plugins.$pluginId.$'
@@ -48,6 +49,11 @@ const SourcesNamespaceRoute = SourcesNamespaceRouteImport.update({
path: '/sources/$namespace',
getParentRoute: () => rootRouteImport,
} as any)
+const ResumeExecutionIdRoute = ResumeExecutionIdRouteImport.update({
+ id: '/resume/$executionId',
+ path: '/resume/$executionId',
+ getParentRoute: () => rootRouteImport,
+} as any)
const SourcesAddPluginKeyRoute = SourcesAddPluginKeyRouteImport.update({
id: '/sources/add/$pluginKey',
path: '/sources/add/$pluginKey',
@@ -65,6 +71,7 @@ export interface FileRoutesByFullPath {
'/policies': typeof PoliciesRoute
'/secrets': typeof SecretsRoute
'/tools': typeof ToolsRoute
+ '/resume/$executionId': typeof ResumeExecutionIdRoute
'/sources/$namespace': typeof SourcesNamespaceRoute
'/plugins/$pluginId/$': typeof PluginsPluginIdSplatRoute
'/sources/add/$pluginKey': typeof SourcesAddPluginKeyRoute
@@ -75,6 +82,7 @@ export interface FileRoutesByTo {
'/policies': typeof PoliciesRoute
'/secrets': typeof SecretsRoute
'/tools': typeof ToolsRoute
+ '/resume/$executionId': typeof ResumeExecutionIdRoute
'/sources/$namespace': typeof SourcesNamespaceRoute
'/plugins/$pluginId/$': typeof PluginsPluginIdSplatRoute
'/sources/add/$pluginKey': typeof SourcesAddPluginKeyRoute
@@ -86,6 +94,7 @@ export interface FileRoutesById {
'/policies': typeof PoliciesRoute
'/secrets': typeof SecretsRoute
'/tools': typeof ToolsRoute
+ '/resume/$executionId': typeof ResumeExecutionIdRoute
'/sources/$namespace': typeof SourcesNamespaceRoute
'/plugins/$pluginId/$': typeof PluginsPluginIdSplatRoute
'/sources/add/$pluginKey': typeof SourcesAddPluginKeyRoute
@@ -98,6 +107,7 @@ export interface FileRouteTypes {
| '/policies'
| '/secrets'
| '/tools'
+ | '/resume/$executionId'
| '/sources/$namespace'
| '/plugins/$pluginId/$'
| '/sources/add/$pluginKey'
@@ -108,6 +118,7 @@ export interface FileRouteTypes {
| '/policies'
| '/secrets'
| '/tools'
+ | '/resume/$executionId'
| '/sources/$namespace'
| '/plugins/$pluginId/$'
| '/sources/add/$pluginKey'
@@ -118,6 +129,7 @@ export interface FileRouteTypes {
| '/policies'
| '/secrets'
| '/tools'
+ | '/resume/$executionId'
| '/sources/$namespace'
| '/plugins/$pluginId/$'
| '/sources/add/$pluginKey'
@@ -129,6 +141,7 @@ export interface RootRouteChildren {
PoliciesRoute: typeof PoliciesRoute
SecretsRoute: typeof SecretsRoute
ToolsRoute: typeof ToolsRoute
+ ResumeExecutionIdRoute: typeof ResumeExecutionIdRoute
SourcesNamespaceRoute: typeof SourcesNamespaceRoute
PluginsPluginIdSplatRoute: typeof PluginsPluginIdSplatRoute
SourcesAddPluginKeyRoute: typeof SourcesAddPluginKeyRoute
@@ -178,6 +191,13 @@ declare module '@tanstack/react-router' {
preLoaderRoute: typeof SourcesNamespaceRouteImport
parentRoute: typeof rootRouteImport
}
+ '/resume/$executionId': {
+ id: '/resume/$executionId'
+ path: '/resume/$executionId'
+ fullPath: '/resume/$executionId'
+ preLoaderRoute: typeof ResumeExecutionIdRouteImport
+ parentRoute: typeof rootRouteImport
+ }
'/sources/add/$pluginKey': {
id: '/sources/add/$pluginKey'
path: '/sources/add/$pluginKey'
@@ -201,6 +221,7 @@ const rootRouteChildren: RootRouteChildren = {
PoliciesRoute: PoliciesRoute,
SecretsRoute: SecretsRoute,
ToolsRoute: ToolsRoute,
+ ResumeExecutionIdRoute: ResumeExecutionIdRoute,
SourcesNamespaceRoute: SourcesNamespaceRoute,
PluginsPluginIdSplatRoute: PluginsPluginIdSplatRoute,
SourcesAddPluginKeyRoute: SourcesAddPluginKeyRoute,
diff --git a/packages/app/src/routes/resume.$executionId.tsx b/packages/app/src/routes/resume.$executionId.tsx
new file mode 100644
index 000000000..32a84347b
--- /dev/null
+++ b/packages/app/src/routes/resume.$executionId.tsx
@@ -0,0 +1,117 @@
+import { useCallback } from "react";
+import { useAtomSet, useAtomValue } from "@effect/atom-react";
+import { Data, Effect, Option, Schema } from "effect";
+import * as Atom from "effect/unstable/reactivity/Atom";
+import { createFileRoute } from "@tanstack/react-router";
+import {
+ ResumeApprovalPage,
+ ResumeApprovalPageView,
+} from "@executor-js/react/pages/resume-approval";
+import { pausedExecutionAtom } from "@executor-js/react/api/atoms";
+import type { ElicitationAction } from "@executor-js/react/components/elicitation-approval";
+
+const SearchParams = Schema.toStandardSchemaV1(
+ Schema.Struct({
+ mcp_session_id: Schema.optional(Schema.String),
+ }),
+);
+const LocalMcpResumeCompleted = Schema.Struct({
+ status: Schema.Literal("completed"),
+ text: Schema.String,
+ structured: Schema.Unknown,
+ isError: Schema.Boolean,
+});
+const LocalMcpResumePaused = Schema.Struct({
+ status: Schema.Literal("paused"),
+ text: Schema.String,
+ structured: Schema.Unknown,
+});
+const LocalMcpResumeResult = Schema.Union([LocalMcpResumeCompleted, LocalMcpResumePaused]);
+const decodeLocalMcpResumeResult = Schema.decodeUnknownOption(LocalMcpResumeResult);
+
+class LocalMcpResumeError extends Data.TaggedError("LocalMcpResumeError")<{
+ readonly message: string;
+}> {}
+
+type LocalMcpResumeInput = {
+ readonly mcpSessionId: string;
+ readonly executionId: string;
+ readonly action: ElicitationAction;
+ readonly content?: Record;
+};
+
+const resumeLocalMcpExecution = Atom.fn()((input) =>
+ Effect.gen(function* () {
+ const response = yield* Effect.tryPromise({
+ try: () =>
+ fetch(
+ `/api/mcp-sessions/${encodeURIComponent(input.mcpSessionId)}/executions/${encodeURIComponent(input.executionId)}/resume`,
+ {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify(
+ input.action === "accept"
+ ? { action: input.action, content: input.content ?? {} }
+ : { action: input.action },
+ ),
+ },
+ ),
+ catch: () => new LocalMcpResumeError({ message: "Failed to submit approval." }),
+ });
+
+ if (!response.ok) {
+ const body = yield* Effect.tryPromise({
+ try: () => response.text(),
+ catch: () => "",
+ }).pipe(Effect.orElseSucceed(() => ""));
+ return yield* new LocalMcpResumeError({
+ message: body || `Approval request failed (${response.status}).`,
+ });
+ }
+
+ const body = yield* Effect.tryPromise({
+ try: () => response.json(),
+ catch: () => new LocalMcpResumeError({ message: "Approval response was not valid JSON." }),
+ });
+ const result = decodeLocalMcpResumeResult(body);
+ if (Option.isNone(result)) {
+ return yield* new LocalMcpResumeError({
+ message: "Approval response had an unexpected shape.",
+ });
+ }
+ return result.value;
+ }),
+);
+
+export const Route = createFileRoute("/resume/$executionId")({
+ validateSearch: SearchParams,
+ component: RouteComponent,
+});
+
+function RouteComponent() {
+ const { executionId } = Route.useParams();
+ const { mcp_session_id: mcpSessionId } = Route.useSearch();
+ if (mcpSessionId) {
+ return ;
+ }
+ return ;
+}
+
+function LocalMcpResumeApproval(props: { executionId: string; mcpSessionId: string }) {
+ const paused = useAtomValue(pausedExecutionAtom(props.executionId));
+ const doResume = useAtomSet(resumeLocalMcpExecution, { mode: "promiseExit" });
+ const resume = useCallback(
+ (executionId: string, action: ElicitationAction, content?: Record) =>
+ doResume({ mcpSessionId: props.mcpSessionId, executionId, action, content }),
+ [doResume, props.mcpSessionId],
+ );
+
+ return (
+
+ );
+}
diff --git a/packages/core/api/src/executions/api.ts b/packages/core/api/src/executions/api.ts
index 81bcac944..ad6eb4067 100644
--- a/packages/core/api/src/executions/api.ts
+++ b/packages/core/api/src/executions/api.ts
@@ -31,10 +31,11 @@ const ResumeRequest = Schema.Struct({
content: Schema.optional(Schema.Unknown),
});
-const ResumeResponse = Schema.Struct({
+const ResumeResponse = Schema.Union([CompletedResult, PausedResult]);
+
+const PausedExecutionInfo = Schema.Struct({
text: Schema.String,
structured: Schema.Unknown,
- isError: Schema.Boolean,
});
const ExecutionNotFoundError = Schema.TaggedStruct("ExecutionNotFoundError", {
@@ -52,6 +53,13 @@ const ExecutionParams = { executionId: Schema.String };
// ---------------------------------------------------------------------------
export const ExecutionsApi = HttpApiGroup.make("executions")
+ .add(
+ HttpApiEndpoint.get("getPaused", "/executions/:executionId", {
+ params: ExecutionParams,
+ success: PausedExecutionInfo,
+ error: [InternalError, ExecutionNotFoundError],
+ }),
+ )
.add(
HttpApiEndpoint.post("execute", "/executions", {
payload: ExecuteRequest,
diff --git a/packages/core/api/src/handlers/executions.ts b/packages/core/api/src/handlers/executions.ts
index b6ed076e9..86e1c17ac 100644
--- a/packages/core/api/src/handlers/executions.ts
+++ b/packages/core/api/src/handlers/executions.ts
@@ -1,13 +1,35 @@
import { HttpApiBuilder } from "effect/unstable/httpapi";
import { Effect } from "effect";
+import { Schema } from "effect";
import { ExecutorApi } from "../api";
import { formatExecuteResult, formatPausedExecution } from "@executor-js/execution";
import { ExecutionEngineService } from "../services";
import { capture, captureEngineError } from "@executor-js/api";
+class ExecutionNotFoundError extends Schema.TaggedErrorClass()(
+ "ExecutionNotFoundError",
+ {
+ executionId: Schema.String,
+ },
+) {}
+
export const ExecutionsHandlers = HttpApiBuilder.group(ExecutorApi, "executions", (handlers) =>
handlers
+ .handle("getPaused", ({ params: path }) =>
+ capture(
+ Effect.gen(function* () {
+ const engine = yield* ExecutionEngineService;
+ const paused = yield* captureEngineError(engine.getPausedExecution(path.executionId));
+
+ if (!paused) {
+ return yield* new ExecutionNotFoundError({ executionId: path.executionId });
+ }
+
+ return formatPausedExecution(paused);
+ }),
+ ),
+ )
.handle("execute", ({ payload }) =>
capture(
Effect.gen(function* () {
@@ -45,15 +67,13 @@ export const ExecutionsHandlers = HttpApiBuilder.group(ExecutorApi, "executions"
);
if (!result) {
- return yield* Effect.fail({
- _tag: "ExecutionNotFoundError" as const,
- executionId: path.executionId,
- });
+ return yield* new ExecutionNotFoundError({ executionId: path.executionId });
}
if (result.status === "completed") {
const formatted = formatExecuteResult(result.result);
return {
+ status: "completed" as const,
text: formatted.text,
structured: formatted.structured,
isError: formatted.isError,
@@ -62,9 +82,9 @@ export const ExecutionsHandlers = HttpApiBuilder.group(ExecutorApi, "executions"
const formatted = formatPausedExecution(result.execution);
return {
+ status: "paused" as const,
text: formatted.text,
structured: formatted.structured,
- isError: false,
};
}),
),
diff --git a/packages/core/execution/src/engine.ts b/packages/core/execution/src/engine.ts
index 793a1ded4..769cda661 100644
--- a/packages/core/execution/src/engine.ts
+++ b/packages/core/execution/src/engine.ts
@@ -1,4 +1,4 @@
-import { Deferred, Effect, Fiber, Predicate, Ref } from "effect";
+import { Deferred, Effect, Fiber, Predicate, Queue } from "effect";
import type * as Cause from "effect/Cause";
import type {
@@ -42,7 +42,7 @@ export type PausedExecution = {
type InternalPausedExecution = PausedExecution & {
readonly response: Deferred.Deferred;
readonly fiber: Fiber.Fiber;
- readonly pauseSignalRef: Ref.Ref>>;
+ readonly pauseQueue: Queue.Queue>;
};
export type ResumeResponse = {
@@ -129,6 +129,8 @@ export const formatPausedExecution = (
interaction: {
kind: isUrlElicitation ? "url" : "form",
message: req.message,
+ toolId: String(paused.elicitationContext.toolId),
+ args: paused.elicitationContext.args,
...(isUrlElicitation ? { url: req.url } : {}),
...(isFormElicitation ? { requestedSchema: req.requestedSchema } : {}),
},
@@ -334,6 +336,12 @@ export type ExecutionEngine
response: ResumeResponse,
) => Effect.Effect;
+ /**
+ * Inspect a paused execution without resuming it. Returns null if the id is
+ * unknown or has already been resumed.
+ */
+ readonly getPausedExecution: (executionId: string) => Effect.Effect;
+
/**
* Get the dynamic tool description (workflow + namespaces).
*/
@@ -348,7 +356,7 @@ export const createExecutionEngine = ,
- pauseSignal: Deferred.Deferred>,
+ pauseQueue: Queue.Queue>,
): Effect.Effect =>
Effect.raceFirst(
Fiber.join(fiber).pipe(
Effect.map((result): ExecutionResult => ({ status: "completed", result })),
),
- Deferred.await(pauseSignal).pipe(
+ Queue.take(pauseQueue).pipe(
Effect.map((paused): ExecutionResult => ({ status: "paused", execution: paused })),
),
);
@@ -385,10 +393,9 @@ export const createExecutionEngine = >());
+ // Queue preserves pauses that arrive before the previous approval has
+ // returned to the caller, which can happen with concurrent tool calls.
+ const pauseQueue = yield* Queue.unbounded>();
// Will be set once the fiber is forked.
let fiber: Fiber.Fiber;
@@ -403,12 +410,11 @@ export const createExecutionEngine = >();
- yield* Ref.set(paused.pauseSignalRef, nextSignal);
-
yield* Deferred.succeed(paused.response, {
action: response.action as typeof ElicitationResponse.Type.action,
content: response.content,
});
- return (yield* awaitCompletionOrPause(paused.fiber, nextSignal)) as ExecutionResult;
+ return (yield* awaitCompletionOrPause(paused.fiber, paused.pauseQueue)) as ExecutionResult;
});
/**
@@ -475,6 +474,8 @@ export const createExecutionEngine =
+ Effect.sync(() => pausedExecutions.get(executionId) ?? null),
getDescription: buildExecuteDescription(executor),
};
};
diff --git a/packages/core/execution/src/promise.ts b/packages/core/execution/src/promise.ts
index 453ed1a9f..d3dd385d2 100644
--- a/packages/core/execution/src/promise.ts
+++ b/packages/core/execution/src/promise.ts
@@ -47,6 +47,7 @@ export type ExecutionEngine = {
executionId: string,
response: ResumeResponse,
) => Promise;
+ readonly getPausedExecution: (executionId: string) => Promise;
readonly getDescription: () => Promise;
};
@@ -162,6 +163,7 @@ export const toPromiseExecutionEngine = (
),
executeWithPause: (code) => Effect.runPromise(engine.executeWithPause(code)),
resume: (executionId, response) => Effect.runPromise(engine.resume(executionId, response)),
+ getPausedExecution: (executionId) => Effect.runPromise(engine.getPausedExecution(executionId)),
getDescription: () => Effect.runPromise(engine.getDescription),
});
diff --git a/packages/core/execution/src/tool-invoker.test.ts b/packages/core/execution/src/tool-invoker.test.ts
index dca052997..0f79a80ee 100644
--- a/packages/core/execution/src/tool-invoker.test.ts
+++ b/packages/core/execution/src/tool-invoker.test.ts
@@ -808,6 +808,56 @@ describe("pause/resume with multiple elicitations", () => {
{ timeout: 10000 },
);
+ it.effect(
+ "resume drains concurrent elicitations that were queued before the first approval",
+ () =>
+ Effect.gen(function* () {
+ const executor = yield* makeElicitingExecutor();
+ const engine = createExecutionEngine({ executor, codeExecutor });
+
+ const code = `
+ return await Promise.all([
+ tools.api.singleApproval({}),
+ tools.api.singleApproval({}),
+ tools.api.singleApproval({})
+ ]);
+ `;
+
+ const outcome1 = yield* engine.executeWithPause(code);
+ expect(outcome1.status).toBe("paused");
+ const paused1 = outcome1 as Extract;
+
+ const outcome2 = yield* Effect.race(
+ engine
+ .resume(paused1.execution.id, { action: "accept" })
+ .pipe(Effect.map((outcome) => ({ kind: "resumed" as const, outcome }))),
+ Effect.sleep("2 seconds").pipe(Effect.as({ kind: "hung" as const })),
+ );
+
+ expect(outcome2.kind).toBe("resumed");
+ if (outcome2.kind !== "resumed") return;
+ expect(outcome2.outcome?.status).toBe("paused");
+ const paused2 = outcome2.outcome as Extract<
+ NonNullable,
+ { status: "paused" }
+ >;
+
+ const outcome3 = yield* engine.resume(paused2.execution.id, { action: "accept" });
+ expect(outcome3?.status).toBe("paused");
+ const paused3 = outcome3 as Extract, { status: "paused" }>;
+
+ const outcome4 = yield* engine.resume(paused3.execution.id, { action: "accept" });
+ expect(outcome4?.status).toBe("completed");
+ const completed = outcome4 as Extract<
+ NonNullable,
+ { status: "completed" }
+ >;
+ expect(completed.result.error).toBeUndefined();
+ expect(completed.result.result).toHaveLength(3);
+ }),
+ { timeout: 10000 },
+ );
+
// Regression: use separate top-level runPromise calls to match HTTP/CLI
// pause/resume, and a single-elicit tool so no later pause can mask a dead
// sandbox fiber.
diff --git a/packages/hosts/mcp/src/server.test.ts b/packages/hosts/mcp/src/server.test.ts
index 606487659..8814352a8 100644
--- a/packages/hosts/mcp/src/server.test.ts
+++ b/packages/hosts/mcp/src/server.test.ts
@@ -9,7 +9,7 @@ import type * as Cause from "effect/Cause";
import { FormElicitation, ToolId, UrlElicitation } from "@executor-js/sdk";
import type { ExecutionEngine, ExecutionResult } from "@executor-js/execution";
-import { createExecutorMcpServer } from "./server";
+import { createExecutorMcpServer, type ExecutorMcpServerConfig } from "./server";
// ---------------------------------------------------------------------------
// Helpers
@@ -30,6 +30,7 @@ const makeStubEngine = (overrides: {
overrides.executeWithPause ??
(() => Effect.succeed({ status: "completed", result: { result: "default" } })),
resume: overrides.resume ?? (() => Effect.succeed(null)),
+ getPausedExecution: () => Effect.succeed(null),
getDescription: Effect.succeed(overrides.description ?? "test executor"),
});
@@ -38,8 +39,9 @@ const withClient = async (
engine: ExecutionEngine,
capabilities: ClientCapabilities,
fn: (client: Client) => Promise,
+ config?: Pick, "debug" | "elicitationMode" | "browserApprovalStore">,
) => {
- const mcpServer = await Effect.runPromise(createExecutorMcpServer({ engine }));
+ const mcpServer = await Effect.runPromise(createExecutorMcpServer({ engine, ...config }));
const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
const client = new Client({ name: "test-client", version: "1.0.0" }, { capabilities });
await mcpServer.connect(serverTransport);
@@ -53,6 +55,12 @@ const withClient = async (
}
};
+const withNativeClient = async (
+ engine: ExecutionEngine,
+ capabilities: ClientCapabilities,
+ fn: (client: Client) => Promise,
+) => withClient(engine, capabilities, fn, { elicitationMode: { mode: "native" } });
+
const ELICITATION_CAPS: ClientCapabilities = {
elicitation: { form: {}, url: {} },
};
@@ -97,16 +105,16 @@ const makeElicitingEngine = (
});
// ---------------------------------------------------------------------------
-// Client WITH elicitation support (managed / inline path)
+// Explicit native elicitation mode
// ---------------------------------------------------------------------------
-describe("MCP host server — client with elicitation", () => {
+describe("MCP host server — native elicitation mode", () => {
it("execute tool calls engine.execute and returns result", async () => {
const engine = makeStubEngine({
execute: (code) => Effect.succeed({ result: `ran: ${code}` }),
});
- await withClient(engine, ELICITATION_CAPS, async (client) => {
+ await withNativeClient(engine, ELICITATION_CAPS, async (client) => {
const result = await client.callTool({
name: "execute",
arguments: { code: "1+1" },
@@ -121,7 +129,7 @@ describe("MCP host server — client with elicitation", () => {
execute: () => Effect.fail(new TestExecutionError({ message: "Unexpected token ':'" })),
});
- await withClient(engine, ELICITATION_CAPS, async (client) => {
+ await withNativeClient(engine, ELICITATION_CAPS, async (client) => {
const result = await client.callTool({
name: "execute",
arguments: { code: "const x: any = 1;" },
@@ -141,7 +149,7 @@ describe("MCP host server — client with elicitation", () => {
execute: () => Effect.die(new Error("secret internal detail")),
});
- await withClient(engine, ELICITATION_CAPS, async (client) => {
+ await withNativeClient(engine, ELICITATION_CAPS, async (client) => {
const result = await client.callTool({
name: "execute",
arguments: { code: "run" },
@@ -172,7 +180,7 @@ describe("MCP host server — client with elicitation", () => {
(r) => (r.action === "accept" && r.content?.approved ? "approved" : "denied"),
);
- await withClient(engine, ELICITATION_CAPS, async (client) => {
+ await withNativeClient(engine, ELICITATION_CAPS, async (client) => {
client.setRequestHandler(ElicitRequestSchema, async () => ({
action: "accept" as const,
content: { approved: true },
@@ -192,7 +200,7 @@ describe("MCP host server — client with elicitation", () => {
(r) => `action:${r.action}`,
);
- await withClient(engine, ELICITATION_CAPS, async (client) => {
+ await withNativeClient(engine, ELICITATION_CAPS, async (client) => {
client.setRequestHandler(ElicitRequestSchema, async () => ({
action: "decline" as const,
content: {},
@@ -206,13 +214,68 @@ describe("MCP host server — client with elicitation", () => {
});
});
+ it("browser approval mode does not auto-switch to native elicitation", async () => {
+ let approvalUrlCalled = false;
+ let executeCalled = false;
+ const engine = makeStubEngine({
+ execute: () =>
+ Effect.sync(() => {
+ executeCalled = true;
+ return { result: "should-not-run" };
+ }),
+ executeWithPause: () =>
+ Effect.sync(() => {
+ return makePausedResult(
+ "exec_browser_1",
+ FormElicitation.make({ message: "Paused", requestedSchema: {} }),
+ );
+ }),
+ });
+
+ await withClient(
+ engine,
+ ELICITATION_CAPS,
+ async (client) => {
+ client.setRequestHandler(ElicitRequestSchema, async () => ({
+ action: "accept" as const,
+ content: {},
+ }));
+
+ const { tools } = await client.listTools();
+ expect(tools.map((t) => t.name)).toContain("resume");
+
+ const result = await client.callTool({
+ name: "execute",
+ arguments: { code: "needs-inline-approval" },
+ });
+ expect(result.structuredContent).toMatchObject({
+ status: "user_approval_required",
+ executionId: "exec_browser_1",
+ approvalUrl: "https://executor.test/resume/exec_browser_1",
+ });
+ expect(result.structuredContent).not.toHaveProperty("interaction");
+ expect(executeCalled).toBe(false);
+ expect(approvalUrlCalled).toBe(true);
+ },
+ {
+ elicitationMode: {
+ mode: "browser",
+ approvalUrl: (executionId) => {
+ approvalUrlCalled = true;
+ return `https://executor.test/resume/${executionId}`;
+ },
+ },
+ },
+ );
+ });
+
it("empty form schema gets wrapped with minimal valid schema", async () => {
let receivedSchema: unknown;
const engine = makeElicitingEngine(
FormElicitation.make({ message: "Just approve", requestedSchema: {} }),
);
- await withClient(engine, ELICITATION_CAPS, async (client) => {
+ await withNativeClient(engine, ELICITATION_CAPS, async (client) => {
client.setRequestHandler(ElicitRequestSchema, async (request) => {
const params = request.params;
if ("requestedSchema" in params) {
@@ -239,7 +302,7 @@ describe("MCP host server — client with elicitation", () => {
}),
);
- await withClient(engine, ELICITATION_CAPS, async (client) => {
+ await withNativeClient(engine, ELICITATION_CAPS, async (client) => {
client.setRequestHandler(ElicitRequestSchema, async (request) => {
receivedParams = request.params as Record;
return { action: "accept" as const, content: {} };
@@ -266,7 +329,7 @@ describe("MCP host server — client with elicitation", () => {
}),
});
- await withClient(engine, ELICITATION_CAPS, async (client) => {
+ await withNativeClient(engine, ELICITATION_CAPS, async (client) => {
const result = await client.callTool({
name: "execute",
arguments: { code: "bad" },
@@ -276,8 +339,8 @@ describe("MCP host server — client with elicitation", () => {
});
});
- it("resume tool is hidden when client supports elicitation", async () => {
- await withClient(makeStubEngine({}), ELICITATION_CAPS, async (client) => {
+ it("resume tool is hidden in native elicitation mode", async () => {
+ await withNativeClient(makeStubEngine({}), ELICITATION_CAPS, async (client) => {
const { tools } = await client.listTools();
const names = tools.map((t) => t.name);
expect(names).toContain("execute");
@@ -287,29 +350,29 @@ describe("MCP host server — client with elicitation", () => {
});
// ---------------------------------------------------------------------------
-// Client with form-only elicitation (uses managed elicitation)
+// Client with form-only elicitation in native mode
// ---------------------------------------------------------------------------
-describe("MCP host server — client with form-only elicitation", () => {
- it("resume tool is hidden when client supports form elicitation", async () => {
- await withClient(makeStubEngine({}), FORM_ONLY_CAPS, async (client) => {
+describe("MCP host server — native form-only elicitation", () => {
+ it("resume tool is hidden in native mode", async () => {
+ await withNativeClient(makeStubEngine({}), FORM_ONLY_CAPS, async (client) => {
const { tools } = await client.listTools();
expect(tools.map((t) => t.name)).toContain("execute");
expect(tools.map((t) => t.name)).not.toContain("resume");
});
});
- it("uses managed elicitation path when client supports form", async () => {
+ it("uses native elicitation path when client supports form", async () => {
const engine = makeStubEngine({
- execute: (code) => Effect.succeed({ result: `managed: ${code}` }),
+ execute: (code) => Effect.succeed({ result: `native: ${code}` }),
});
- await withClient(engine, FORM_ONLY_CAPS, async (client) => {
+ await withNativeClient(engine, FORM_ONLY_CAPS, async (client) => {
const result = await client.callTool({
name: "execute",
arguments: { code: "test" },
});
- expect(result.content).toEqual([{ type: "text", text: "managed: test" }]);
+ expect(result.content).toEqual([{ type: "text", text: "native: test" }]);
});
});
@@ -323,7 +386,7 @@ describe("MCP host server — client with form-only elicitation", () => {
}),
);
- await withClient(engine, FORM_ONLY_CAPS, async (client) => {
+ await withNativeClient(engine, FORM_ONLY_CAPS, async (client) => {
client.setRequestHandler(ElicitRequestSchema, async (request) => {
receivedMessage =
typeof request.params.message === "string" ? request.params.message : undefined;
@@ -374,7 +437,92 @@ describe("MCP host server — client without elicitation (pause/resume)", () =>
});
});
- it("paused execution returns interaction metadata with executionId", async () => {
+ it("resume tool requires user approval by default", async () => {
+ let resumeCalled = false;
+ const engine = makeStubEngine({
+ resume: () =>
+ Effect.sync(() => {
+ resumeCalled = true;
+ return { status: "completed", result: { result: "should-not-run" } };
+ }),
+ });
+
+ await withClient(
+ engine,
+ NO_CAPS,
+ async (client) => {
+ const result = await client.callTool({
+ name: "resume",
+ arguments: { executionId: "exec_1" },
+ });
+
+ expect(resumeCalled).toBe(false);
+ expect(result.isError).toBeFalsy();
+ expect(textOf(result)).toContain("User approval required");
+ expect(textOf(result)).toContain("https://executor.test/resume/exec_1");
+ expect(result.structuredContent).toMatchObject({
+ status: "user_approval_required",
+ executionId: "exec_1",
+ approvalUrl: "https://executor.test/resume/exec_1",
+ });
+ },
+ {
+ elicitationMode: {
+ mode: "browser",
+ approvalUrl: (executionId) => `https://executor.test/resume/${executionId}`,
+ },
+ },
+ );
+ });
+
+ it("browser approval mode consumes a user-approved response and returns the resumed result", async () => {
+ const approved = new Map }>();
+ const engine = makeStubEngine({
+ resume: (executionId, response) =>
+ Effect.succeed(
+ executionId === "exec_1" && response.action === "accept"
+ ? { status: "completed", result: { result: "resumed-after-browser" } }
+ : null,
+ ),
+ });
+
+ await withClient(
+ engine,
+ NO_CAPS,
+ async (client) => {
+ const waiting = await client.callTool({
+ name: "resume",
+ arguments: { executionId: "exec_1" },
+ });
+ expect(waiting.structuredContent).toMatchObject({
+ status: "user_approval_required",
+ executionId: "exec_1",
+ });
+
+ approved.set("exec_1", { action: "accept", content: {} });
+ const resumed = await client.callTool({
+ name: "resume",
+ arguments: { executionId: "exec_1" },
+ });
+ expect(resumed.content).toEqual([{ type: "text", text: "resumed-after-browser" }]);
+ expect(resumed.structuredContent).toMatchObject({
+ status: "completed",
+ result: "resumed-after-browser",
+ });
+ },
+ {
+ elicitationMode: {
+ mode: "browser",
+ approvalUrl: (executionId) => `https://executor.test/resume/${executionId}`,
+ },
+ browserApprovalStore: {
+ takeResponse: (executionId) => Effect.succeed(approved.get(executionId) ?? null),
+ },
+ },
+ );
+ });
+
+ it("model resume mode paused execution returns interaction metadata with executionId", async () => {
const engine = makeStubEngine({
executeWithPause: () =>
Effect.succeed(
@@ -391,22 +539,27 @@ describe("MCP host server — client without elicitation (pause/resume)", () =>
),
});
- await withClient(engine, NO_CAPS, async (client) => {
- const result = await client.callTool({
- name: "execute",
- arguments: { code: "pause-me" },
- });
- expect(textOf(result)).toContain("exec_42");
- expect(textOf(result)).toContain("Need approval");
- expect(result.isError).toBeFalsy();
-
- const structured = result.structuredContent as Record;
- expect(structured?.executionId).toBe("exec_42");
- expect(structured?.status).toBe("waiting_for_interaction");
- });
+ await withClient(
+ engine,
+ NO_CAPS,
+ async (client) => {
+ const result = await client.callTool({
+ name: "execute",
+ arguments: { code: "pause-me" },
+ });
+ expect(textOf(result)).toContain("exec_42");
+ expect(textOf(result)).toContain("Need approval");
+ expect(result.isError).toBeFalsy();
+
+ const structured = result.structuredContent as Record;
+ expect(structured?.executionId).toBe("exec_42");
+ expect(structured?.status).toBe("waiting_for_interaction");
+ },
+ { elicitationMode: { mode: "model" } },
+ );
});
- it("resume tool completes a paused execution", async () => {
+ it("resume tool completes a paused execution when model resume is explicitly enabled", async () => {
const engine = makeStubEngine({
resume: (executionId, response) =>
Effect.succeed(
@@ -416,14 +569,19 @@ describe("MCP host server — client without elicitation (pause/resume)", () =>
),
});
- await withClient(engine, NO_CAPS, async (client) => {
- const result = await client.callTool({
- name: "resume",
- arguments: { executionId: "exec_1", action: "accept", content: "{}" },
- });
- expect(result.content).toEqual([{ type: "text", text: "resumed-ok" }]);
- expect(result.isError).toBeFalsy();
- });
+ await withClient(
+ engine,
+ NO_CAPS,
+ async (client) => {
+ const result = await client.callTool({
+ name: "resume",
+ arguments: { executionId: "exec_1", action: "accept", content: "{}" },
+ });
+ expect(result.content).toEqual([{ type: "text", text: "resumed-ok" }]);
+ expect(result.isError).toBeFalsy();
+ },
+ { elicitationMode: { mode: "model" } },
+ );
});
it("resume tool passes parsed content to engine", async () => {
@@ -436,17 +594,22 @@ describe("MCP host server — client without elicitation (pause/resume)", () =>
}),
});
- await withClient(engine, NO_CAPS, async (client) => {
- await client.callTool({
- name: "resume",
- arguments: {
- executionId: "exec_1",
- action: "accept",
- content: JSON.stringify({ approved: true, name: "test" }),
- },
- });
- expect(receivedContent).toEqual({ approved: true, name: "test" });
- });
+ await withClient(
+ engine,
+ NO_CAPS,
+ async (client) => {
+ await client.callTool({
+ name: "resume",
+ arguments: {
+ executionId: "exec_1",
+ action: "accept",
+ content: JSON.stringify({ approved: true, name: "test" }),
+ },
+ });
+ expect(receivedContent).toEqual({ approved: true, name: "test" });
+ },
+ { elicitationMode: { mode: "model" } },
+ );
});
it("resume with empty content passes undefined", async () => {
@@ -459,33 +622,43 @@ describe("MCP host server — client without elicitation (pause/resume)", () =>
}),
});
- await withClient(engine, NO_CAPS, async (client) => {
- await client.callTool({
- name: "resume",
- arguments: { executionId: "exec_1", action: "accept", content: "{}" },
- });
- expect(receivedContent).toBeUndefined();
- });
+ await withClient(
+ engine,
+ NO_CAPS,
+ async (client) => {
+ await client.callTool({
+ name: "resume",
+ arguments: { executionId: "exec_1", action: "accept", content: "{}" },
+ });
+ expect(receivedContent).toBeUndefined();
+ },
+ { elicitationMode: { mode: "model" } },
+ );
});
it("resume with unknown executionId returns error", async () => {
const engine = makeStubEngine({ resume: () => Effect.succeed(null) });
- await withClient(engine, NO_CAPS, async (client) => {
- const result = await client.callTool({
- name: "resume",
- arguments: {
- executionId: "does-not-exist",
- action: "accept",
- content: "{}",
- },
- });
- expect(result.isError).toBe(true);
- expect(textOf(result)).toContain("does-not-exist");
- });
+ await withClient(
+ engine,
+ NO_CAPS,
+ async (client) => {
+ const result = await client.callTool({
+ name: "resume",
+ arguments: {
+ executionId: "does-not-exist",
+ action: "accept",
+ content: "{}",
+ },
+ });
+ expect(result.isError).toBe(true);
+ expect(textOf(result)).toContain("does-not-exist");
+ },
+ { elicitationMode: { mode: "model" } },
+ );
});
- it("paused UrlElicitation includes url and kind in structured output", async () => {
+ it("model resume mode paused UrlElicitation includes url and kind in structured output", async () => {
const engine = makeStubEngine({
executeWithPause: () =>
Effect.succeed(
@@ -500,19 +673,24 @@ describe("MCP host server — client without elicitation (pause/resume)", () =>
),
});
- await withClient(engine, NO_CAPS, async (client) => {
- const result = await client.callTool({
- name: "execute",
- arguments: { code: "oauth" },
- });
- expect(textOf(result)).toContain("https://auth.example.com/callback");
- expect(textOf(result)).toContain("exec_99");
-
- const structured = result.structuredContent as Record;
- const interaction = structured?.interaction as Record;
- expect(interaction?.kind).toBe("url");
- expect(interaction?.url).toBe("https://auth.example.com/callback");
- });
+ await withClient(
+ engine,
+ NO_CAPS,
+ async (client) => {
+ const result = await client.callTool({
+ name: "execute",
+ arguments: { code: "oauth" },
+ });
+ expect(textOf(result)).toContain("https://auth.example.com/callback");
+ expect(textOf(result)).toContain("exec_99");
+
+ const structured = result.structuredContent as Record;
+ const interaction = structured?.interaction as Record;
+ expect(interaction?.kind).toBe("url");
+ expect(interaction?.url).toBe("https://auth.example.com/callback");
+ },
+ { elicitationMode: { mode: "model" } },
+ );
});
});
@@ -533,7 +711,7 @@ describe("MCP host server — elicitation error handling", () => {
(r) => `fallback:${r.action}`,
);
- await withClient(engine, ELICITATION_CAPS, async (client) => {
+ await withNativeClient(engine, ELICITATION_CAPS, async (client) => {
client.setRequestHandler(ElicitRequestSchema, async () => {
// oxlint-disable-next-line executor/no-try-catch-or-throw, executor/no-error-constructor -- boundary: MCP client request handler rejects to exercise server fallback
throw new Error("client cannot handle this");
@@ -568,30 +746,40 @@ describe("MCP host server — resume content parsing", () => {
it("array JSON is rejected (not passed as content)", async () => {
const { engine, getContent } = makeResumeEngine();
- await withClient(engine, NO_CAPS, async (client) => {
- await client.callTool({
- name: "resume",
- arguments: { executionId: "exec_1", action: "accept", content: "[1,2,3]" },
- });
- expect(getContent()).toBeUndefined();
- });
+ await withClient(
+ engine,
+ NO_CAPS,
+ async (client) => {
+ await client.callTool({
+ name: "resume",
+ arguments: { executionId: "exec_1", action: "accept", content: "[1,2,3]" },
+ });
+ expect(getContent()).toBeUndefined();
+ },
+ { elicitationMode: { mode: "model" } },
+ );
});
it("invalid JSON is handled gracefully (not thrown)", async () => {
const { engine, getContent } = makeResumeEngine();
- await withClient(engine, NO_CAPS, async (client) => {
- const result = await client.callTool({
- name: "resume",
- arguments: {
- executionId: "exec_1",
- action: "accept",
- content: "not-valid-json",
- },
- });
- expect(getContent()).toBeUndefined();
- expect(result.isError).toBeFalsy();
- });
+ await withClient(
+ engine,
+ NO_CAPS,
+ async (client) => {
+ const result = await client.callTool({
+ name: "resume",
+ arguments: {
+ executionId: "exec_1",
+ action: "accept",
+ content: "not-valid-json",
+ },
+ });
+ expect(getContent()).toBeUndefined();
+ expect(result.isError).toBeFalsy();
+ },
+ { elicitationMode: { mode: "model" } },
+ );
});
});
@@ -634,7 +822,7 @@ describe("MCP host server — multiple elicitations", () => {
}),
});
- await withClient(engine, ELICITATION_CAPS, async (client) => {
+ await withNativeClient(engine, ELICITATION_CAPS, async (client) => {
let callCount = 0;
client.setRequestHandler(ElicitRequestSchema, async () => {
callCount++;
diff --git a/packages/hosts/mcp/src/server.ts b/packages/hosts/mcp/src/server.ts
index 5b6342e8d..7f69add75 100644
--- a/packages/hosts/mcp/src/server.ts
+++ b/packages/hosts/mcp/src/server.ts
@@ -7,7 +7,7 @@ import type {
JsonSchemaValidator,
} from "@modelcontextprotocol/sdk/validation/types.js";
import { Validator } from "@cfworker/json-schema";
-import { z } from "zod/v4";
+import * as z from "zod/v4";
import type {
ElicitationResponse,
@@ -22,6 +22,7 @@ import {
formatPausedExecution,
type ExecutionEngine,
type ExecutionEngineConfig,
+ type ResumeResponse,
} from "@executor-js/execution";
// ---------------------------------------------------------------------------
@@ -70,6 +71,23 @@ type SharedMcpServerConfig = {
* Enable verbose MCP capability / elicitation debug logging.
*/
readonly debug?: boolean;
+ /**
+ * Controls how elicitation is handled for this MCP connection. The secure
+ * default is browser approval: `execute` pauses, and `resume` returns a URL
+ * for the signed-in user instead of letting the model answer directly.
+ */
+ readonly elicitationMode?:
+ | {
+ readonly mode: "browser";
+ readonly approvalUrl: (executionId: string) => string;
+ }
+ | {
+ readonly mode: "model";
+ }
+ | {
+ readonly mode: "native";
+ };
+ readonly browserApprovalStore?: BrowserApprovalStore;
};
export type ExecutorMcpServerConfig =
@@ -78,6 +96,10 @@ export type ExecutorMcpServerConfig & SharedMcpServerConfig & { readonly stateless: true })
| ({ readonly engine: ExecutionEngine; readonly stateless: true } & SharedMcpServerConfig);
+export type BrowserApprovalStore = {
+ readonly takeResponse: (executionId: string) => Effect.Effect;
+};
+
// ---------------------------------------------------------------------------
// Elicitation bridge
// ---------------------------------------------------------------------------
@@ -95,13 +117,9 @@ const readDebugDefault = (): boolean => {
return value === "1" || value === "true";
};
-const supportsManagedElicitation = (server: McpServer): boolean =>
- getElicitationSupport(server).form;
-
const capabilitySnapshot = (server: McpServer) => ({
clientCapabilities: server.server.getClientCapabilities() ?? null,
elicitationSupport: getElicitationSupport(server),
- managedElicitation: supportsManagedElicitation(server),
});
type ElicitInputParams =
@@ -270,6 +288,33 @@ const newCorrelationId = (): string =>
.toString(16)
.padStart(8, "0");
+const defaultResumeApprovalUrl = (executionId: string): string =>
+ `/resume/${encodeURIComponent(executionId)}`;
+
+const formatResumeApprovalRequired = (input: {
+ readonly executionId: string;
+ readonly approvalUrl: string;
+}): McpToolResult => ({
+ content: [
+ {
+ type: "text",
+ text: [
+ "User approval required.",
+ "",
+ "Tell the user to open this URL while signed in and approve or decline the paused interaction:",
+ input.approvalUrl,
+ "",
+ "Do not choose accept, decline, cancel, or response content on the user's behalf.",
+ ].join("\n"),
+ },
+ ],
+ structuredContent: {
+ status: "user_approval_required",
+ executionId: input.executionId,
+ approvalUrl: input.approvalUrl,
+ },
+});
+
const toMcpFailureResult = (cause: Cause.Cause): McpToolResult => {
const correlationId = newCorrelationId();
// oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: best-effort defect logging must tolerate non-serializable causes
@@ -325,6 +370,12 @@ export const createExecutorMcpServer = (
console.error(`[executor:mcp] ${event}`, data);
}
};
+ const elicitationMode =
+ config.elicitationMode ??
+ ({
+ mode: "browser",
+ approvalUrl: defaultResumeApprovalUrl,
+ } as const);
const resolveParentSpan = (): Tracer.AnySpan | undefined => {
const ps = config.parentSpan;
@@ -355,12 +406,12 @@ export const createExecutorMcpServer = (
const executeCode = (code: string): Effect.Effect =>
Effect.gen(function* () {
debugLog("execute.call", {
- managedElicitation: supportsManagedElicitation(server),
+ elicitationMode: elicitationMode.mode,
elicitationSupport: getElicitationSupport(server),
clientCapabilities: server.server.getClientCapabilities() ?? null,
codeLength: code.length,
});
- if (supportsManagedElicitation(server)) {
+ if (elicitationMode.mode === "native") {
const result = yield* engine.execute(code, {
onElicitation: makeMcpElicitationHandler(server, debugLog),
});
@@ -377,7 +428,9 @@ export const createExecutorMcpServer = (
});
return outcome.status === "completed"
? toMcpResult(formatExecuteResult(outcome.result))
- : toMcpPausedResult(formatPausedExecution(outcome.execution));
+ : elicitationMode.mode === "browser"
+ ? yield* requireUserResumeApproval(outcome.execution.id)
+ : toMcpPausedResult(formatPausedExecution(outcome.execution));
}).pipe(
Effect.withSpan("mcp.host.tool.execute", {
attributes: {
@@ -429,9 +482,60 @@ export const createExecutorMcpServer = (
}),
);
+ const requireUserResumeApproval = (executionId: string): Effect.Effect =>
+ Effect.sync(() => {
+ const approvalUrl =
+ elicitationMode.mode === "browser"
+ ? elicitationMode.approvalUrl(executionId)
+ : defaultResumeApprovalUrl(executionId);
+ debugLog("resume.user_approval_required", {
+ executionId,
+ approvalUrl,
+ clientCapabilities: server.server.getClientCapabilities() ?? null,
+ });
+ return formatResumeApprovalRequired({ executionId, approvalUrl });
+ }).pipe(
+ Effect.withSpan("mcp.host.tool.resume.user_approval_required", {
+ attributes: {
+ "mcp.tool.name": "resume",
+ "mcp.execute.execution_id": executionId,
+ },
+ }),
+ );
+
+ const takeBrowserApprovalResponse = (
+ executionId: string,
+ ): Effect.Effect => {
+ return config.browserApprovalStore?.takeResponse(executionId) ?? Effect.succeed(null);
+ };
+
+ const resumeAfterBrowserApproval = (executionId: string): Effect.Effect =>
+ Effect.gen(function* () {
+ const response = yield* takeBrowserApprovalResponse(executionId);
+ if (!response) return yield* requireUserResumeApproval(executionId);
+
+ const outcome = yield* engine.resume(executionId, response);
+ if (!outcome) {
+ return {
+ content: [{ type: "text" as const, text: `No paused execution: ${executionId}` }],
+ isError: true,
+ } satisfies McpToolResult;
+ }
+ return outcome.status === "completed"
+ ? toMcpResult(formatExecuteResult(outcome.result))
+ : yield* requireUserResumeApproval(outcome.execution.id);
+ }).pipe(
+ Effect.withSpan("mcp.host.tool.resume.browser_approval", {
+ attributes: {
+ "mcp.tool.name": "resume",
+ "mcp.execute.execution_id": executionId,
+ },
+ }),
+ );
+
// --- tools ---
- const executeTool = yield* Effect.sync(() =>
+ yield* Effect.sync(() =>
server.registerTool(
"execute",
{
@@ -446,61 +550,70 @@ export const createExecutorMcpServer = (
}),
);
- const resumeTool = yield* Effect.sync(() =>
- server.registerTool(
+ yield* Effect.sync(() => {
+ if (elicitationMode.mode === "native") {
+ return undefined;
+ }
+
+ if (elicitationMode.mode === "model") {
+ return server.registerTool(
+ "resume",
+ {
+ description: [
+ "Resume a paused execution using the executionId returned by execute.",
+ "This connection explicitly allows model-side resume via elicitation_mode=model.",
+ ].join("\n"),
+ inputSchema: {
+ executionId: z.string().describe("The execution ID from the paused result"),
+ action: z
+ .enum(["accept", "decline", "cancel"])
+ .describe("How to respond to the interaction"),
+ content: z
+ .string()
+ .describe("Optional JSON-encoded response content for form elicitations")
+ .default("{}"),
+ },
+ },
+ ({ executionId, action, content: rawContent }) =>
+ runToolEffect(resumeExecution(executionId, action, parseJsonContent(rawContent))),
+ );
+ }
+
+ return server.registerTool(
"resume",
{
description: [
- "Resume a paused execution using the executionId returned by execute.",
- "Never call this without user approval unless they explicitly state otherwise.",
+ "Request user approval to resume a paused execution.",
+ "Call this with the executionId returned by execute. If the user has not approved in the browser yet, tell them to open the returned approval URL. If they have approved, this returns the resumed execution result.",
+ "This connection does not allow the model to choose accept, decline, cancel, or content.",
].join("\n"),
inputSchema: {
executionId: z.string().describe("The execution ID from the paused result"),
- action: z
- .enum(["accept", "decline", "cancel"])
- .describe("How to respond to the interaction"),
- content: z
- .string()
- .describe("Optional JSON-encoded response content for form elicitations")
- .default("{}"),
},
},
- ({ executionId, action, content: rawContent }) =>
- runToolEffect(resumeExecution(executionId, action, parseJsonContent(rawContent))),
- ),
- ).pipe(
+ ({ executionId }) => runToolEffect(resumeAfterBrowserApproval(executionId)),
+ );
+ }).pipe(
Effect.withSpan("mcp.host.register_tool", {
attributes: { "mcp.tool.name": "resume" },
}),
);
- // --- capability-based tool visibility ---
-
- const syncToolAvailability = () => {
- executeTool.enable();
- if (supportsManagedElicitation(server)) {
- resumeTool.disable();
- } else {
- resumeTool.enable();
- }
+ yield* Effect.sync(() => {
console.error(
- "[executor] MCP capability snapshot",
+ "[executor] MCP session mode",
JSON.stringify({
...capabilitySnapshot(server),
- resumeEnabled: !supportsManagedElicitation(server),
+ elicitationMode: elicitationMode.mode,
+ resumeEnabled: elicitationMode.mode !== "native",
}),
);
debugLog("tool.visibility", {
clientCapabilities: server.server.getClientCapabilities() ?? null,
elicitationSupport: getElicitationSupport(server),
- managedElicitation: supportsManagedElicitation(server),
- resumeEnabled: !supportsManagedElicitation(server),
+ elicitationMode: elicitationMode.mode,
+ resumeEnabled: elicitationMode.mode !== "native",
});
- };
-
- yield* Effect.sync(() => {
- syncToolAvailability();
- server.server.oninitialized = syncToolAvailability;
}).pipe(Effect.withSpan("mcp.host.sync_tool_availability"));
return server;
diff --git a/packages/react/src/api/atoms.tsx b/packages/react/src/api/atoms.tsx
index cdac4b18d..352226055 100644
--- a/packages/react/src/api/atoms.tsx
+++ b/packages/react/src/api/atoms.tsx
@@ -112,6 +112,12 @@ export const policiesAtom = (scopeId: ScopeId) =>
reactivityKeys: [ReactivityKey.policies],
});
+export const pausedExecutionAtom = (executionId: string) =>
+ ExecutorApiClient.query("executions", "getPaused", {
+ params: { executionId },
+ timeToLive: "5 seconds",
+ });
+
// ---------------------------------------------------------------------------
// Mutation atoms — reactivityKeys must be passed at call site (effect-atom
// does not accept them at definition time). See `reactivity-keys.tsx` for the
@@ -152,6 +158,8 @@ export const updatePolicy = ExecutorApiClient.mutation("policies", "update");
export const removePolicy = ExecutorApiClient.mutation("policies", "remove");
+export const resumeExecution = ExecutorApiClient.mutation("executions", "resume");
+
// ---------------------------------------------------------------------------
// Sources — optimistic surface.
// ---------------------------------------------------------------------------
diff --git a/packages/react/src/components/elicitation-approval.tsx b/packages/react/src/components/elicitation-approval.tsx
new file mode 100644
index 000000000..8459f8782
--- /dev/null
+++ b/packages/react/src/components/elicitation-approval.tsx
@@ -0,0 +1,480 @@
+import { useEffect, useMemo, useState, type ReactNode } from "react";
+import { Match, Option } from "effect";
+
+import { Checkbox } from "./checkbox";
+import { Input } from "./input";
+import { Label } from "./label";
+import { NativeSelect, NativeSelectOption } from "./native-select";
+import { Textarea } from "./textarea";
+
+export type ElicitationAction = "accept" | "decline" | "cancel";
+export type ElicitationFieldValue = string | number | boolean | string[];
+
+type ElicitationSchemaField = {
+ readonly name: string;
+ readonly schema: Record;
+ readonly required: boolean;
+};
+
+type ElicitationFormSchema = {
+ readonly fields: readonly ElicitationSchemaField[];
+};
+
+type SelectOption = {
+ readonly value: string;
+ readonly label: string;
+};
+
+export type ElicitationApprovalState = {
+ readonly hasFields: boolean;
+ readonly content: () => Record | null;
+ readonly fields: ReactNode;
+};
+
+const isRecord = (value: unknown): value is Record =>
+ typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isStringArray = (value: unknown): value is string[] =>
+ Array.isArray(value) && value.every((item) => typeof item === "string");
+
+const toOptionalString = (value: unknown): string | undefined =>
+ typeof value === "string" && value.length > 0 ? value : undefined;
+
+const fieldLabel = (field: ElicitationSchemaField): string =>
+ toOptionalString(field.schema.title) ?? field.name;
+
+const fieldDescription = (field: ElicitationSchemaField): string | undefined =>
+ toOptionalString(field.schema.description);
+
+const enumOptions = (schema: Record): readonly SelectOption[] => {
+ const oneOf = schema.oneOf;
+ if (Array.isArray(oneOf)) {
+ return oneOf.flatMap((item): SelectOption[] => {
+ if (!isRecord(item) || typeof item.const !== "string") return [];
+ return [{ value: item.const, label: toOptionalString(item.title) ?? item.const }];
+ });
+ }
+
+ const values = schema.enum;
+ if (!isStringArray(values)) return [];
+ const labels = isStringArray(schema.enumNames) ? schema.enumNames : values;
+ return values.map((value, index) => ({ value, label: labels[index] ?? value }));
+};
+
+const multiSelectOptions = (schema: Record): readonly SelectOption[] => {
+ const items = schema.items;
+ if (!isRecord(items)) return [];
+
+ const anyOf = items.anyOf;
+ if (Array.isArray(anyOf)) {
+ return anyOf.flatMap((item): SelectOption[] => {
+ if (!isRecord(item) || typeof item.const !== "string") return [];
+ return [{ value: item.const, label: toOptionalString(item.title) ?? item.const }];
+ });
+ }
+
+ const values = items.enum;
+ if (!isStringArray(values)) return [];
+ const labels = isStringArray(items.enumNames) ? items.enumNames : values;
+ return values.map((value, index) => ({ value, label: labels[index] ?? value }));
+};
+
+const parseElicitationFormSchema = (value: unknown): ElicitationFormSchema | null => {
+ if (!isRecord(value) || !isRecord(value.properties)) return null;
+ const required = isStringArray(value.required) ? value.required : [];
+ const fields = Object.entries(value.properties).flatMap(
+ ([name, schema]): ElicitationSchemaField[] =>
+ isRecord(schema) ? [{ name, schema, required: required.includes(name) }] : [],
+ );
+ return fields.length > 0 ? { fields } : null;
+};
+
+const initialFieldValue = (field: ElicitationSchemaField): ElicitationFieldValue | undefined => {
+ const value = field.schema.default;
+ if (value === undefined) return undefined;
+ const matched = Match.value(field.schema.type).pipe(
+ Match.when("boolean", () => value === true),
+ Match.when(
+ (type: unknown) => type === "number" || type === "integer",
+ () => {
+ const numberValue = typeof value === "number" ? value : Number(value);
+ return Number.isFinite(numberValue) ? numberValue : undefined;
+ },
+ ),
+ Match.when("array", () => (isStringArray(value) ? value : undefined)),
+ Match.option,
+ );
+ return Option.getOrElse(matched, () => (typeof value === "string" ? value : String(value)));
+};
+
+const initialFormValues = (
+ formSchema: ElicitationFormSchema | null,
+): Record => {
+ const values: Record = {};
+ for (const field of formSchema?.fields ?? []) {
+ const value = initialFieldValue(field);
+ if (value !== undefined) values[field.name] = value;
+ }
+ return values;
+};
+
+const isEmptyFormValue = (value: ElicitationFieldValue | undefined): boolean =>
+ value === undefined || value === "" || (Array.isArray(value) && value.length === 0);
+
+const numericConstraint = (
+ schema: Record,
+ key: "minimum" | "maximum",
+): number | undefined => (typeof schema[key] === "number" ? schema[key] : undefined);
+
+const lengthConstraint = (
+ schema: Record,
+ key: "minLength" | "maxLength" | "minItems" | "maxItems",
+): number | undefined => (typeof schema[key] === "number" ? schema[key] : undefined);
+
+const validateEmail = (value: string): boolean => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+
+const validateUrl = (value: string): boolean => {
+ try {
+ void new URL(value);
+ return true;
+ } catch {
+ return false;
+ }
+};
+
+const validateFieldValue = (
+ field: ElicitationSchemaField,
+ value: ElicitationFieldValue | undefined,
+): { readonly value?: ElicitationFieldValue; readonly error?: string } => {
+ if (isEmptyFormValue(value)) {
+ return field.required ? { error: "This field is required." } : {};
+ }
+
+ if (field.schema.type === "boolean") {
+ return typeof value === "boolean" ? { value } : { error: "Choose true or false." };
+ }
+
+ if (field.schema.type === "number" || field.schema.type === "integer") {
+ const numberValue = typeof value === "number" ? value : Number(value);
+ const typeLabel = field.schema.type === "integer" ? "an integer" : "a number";
+ if (!Number.isFinite(numberValue)) return { error: `Must be ${typeLabel}.` };
+ if (field.schema.type === "integer" && !Number.isInteger(numberValue)) {
+ return { error: "Must be an integer." };
+ }
+ const minimum = numericConstraint(field.schema, "minimum");
+ const maximum = numericConstraint(field.schema, "maximum");
+ if (minimum !== undefined && numberValue < minimum) return { error: `Must be >= ${minimum}.` };
+ if (maximum !== undefined && numberValue > maximum) return { error: `Must be <= ${maximum}.` };
+ return { value: numberValue };
+ }
+
+ if (field.schema.type === "array") {
+ const selected = Array.isArray(value) ? value : [];
+ const options = multiSelectOptions(field.schema);
+ const allowed = new Set(options.map((option) => option.value));
+ if (!selected.every((item) => allowed.has(item))) return { error: "Choose a valid option." };
+ const minItems = lengthConstraint(field.schema, "minItems");
+ const maxItems = lengthConstraint(field.schema, "maxItems");
+ if (minItems !== undefined && selected.length < minItems) {
+ return { error: `Choose at least ${minItems} option${minItems === 1 ? "" : "s"}.` };
+ }
+ if (maxItems !== undefined && selected.length > maxItems) {
+ return { error: `Choose at most ${maxItems} option${maxItems === 1 ? "" : "s"}.` };
+ }
+ return { value: selected };
+ }
+
+ const stringValue = String(value);
+ const options = enumOptions(field.schema);
+ if (options.length > 0 && !options.some((option) => option.value === stringValue)) {
+ return { error: "Choose a valid option." };
+ }
+ const minLength = lengthConstraint(field.schema, "minLength");
+ const maxLength = lengthConstraint(field.schema, "maxLength");
+ if (minLength !== undefined && stringValue.length < minLength) {
+ return { error: `Must be at least ${minLength} character${minLength === 1 ? "" : "s"}.` };
+ }
+ if (maxLength !== undefined && stringValue.length > maxLength) {
+ return { error: `Must be at most ${maxLength} character${maxLength === 1 ? "" : "s"}.` };
+ }
+ if (field.schema.format === "email" && !validateEmail(stringValue)) {
+ return { error: "Must be a valid email address." };
+ }
+ if (field.schema.format === "uri" && !validateUrl(stringValue)) {
+ return { error: "Must be a valid URL." };
+ }
+ return { value: stringValue };
+};
+
+const buildElicitationContent = (
+ formSchema: ElicitationFormSchema | null,
+ formValues: Record,
+): { readonly content: Record; readonly errors: Record } => {
+ if (!formSchema) return { content: {}, errors: {} };
+
+ const content: Record = {};
+ const errors: Record = {};
+ for (const field of formSchema.fields) {
+ const result = validateFieldValue(field, formValues[field.name]);
+ if (result.error) {
+ errors[field.name] = result.error;
+ continue;
+ }
+ if (result.value !== undefined) content[field.name] = result.value;
+ }
+ return { content, errors };
+};
+
+export function useElicitationApproval(schema: unknown): ElicitationApprovalState {
+ const formSchema = useMemo(() => parseElicitationFormSchema(schema), [schema]);
+ const [formValues, setFormValues] = useState>(() =>
+ initialFormValues(formSchema),
+ );
+ const [fieldErrors, setFieldErrors] = useState>({});
+
+ useEffect(() => {
+ setFormValues(initialFormValues(formSchema));
+ setFieldErrors({});
+ }, [formSchema]);
+
+ const setFieldValue = (name: string, value: ElicitationFieldValue | undefined) => {
+ setFormValues((prev) => {
+ const next = { ...prev };
+ if (value === undefined) {
+ delete next[name];
+ } else {
+ next[name] = value;
+ }
+ return next;
+ });
+ setFieldErrors((prev) => {
+ if (!prev[name]) return prev;
+ const next = { ...prev };
+ delete next[name];
+ return next;
+ });
+ };
+
+ return {
+ hasFields: Boolean(formSchema),
+ content: () => {
+ const result = buildElicitationContent(formSchema, formValues);
+ setFieldErrors(result.errors);
+ return Object.keys(result.errors).length > 0 ? null : result.content;
+ },
+ fields: formSchema ? (
+
+ ) : null,
+ };
+}
+
+function ElicitationApprovalFields({
+ formSchema,
+ formValues,
+ fieldErrors,
+ onChange,
+}: {
+ formSchema: ElicitationFormSchema;
+ formValues: Record;
+ fieldErrors: Record;
+ onChange: (name: string, value: ElicitationFieldValue | undefined) => void;
+}) {
+ return (
+
+
+
Additional details
+
+ These values will be sent with approval.
+
+
+ {formSchema.fields.map((field) => (
+
onChange(field.name, value)}
+ />
+ ))}
+
+
+
+ {description && (
+
+ {description}
+
+ )}
+ {error && (
+
+ {error}
+
+ )}
+
+ {multiOptions.map((option) => {
+ const checked = selected.includes(option.value);
+ return (
+
+ );
+ })}
+
+ );
+ }
+
+ if (field.schema.type === "boolean") {
+ return (
+
+ );
+ }
+
+ if (field.schema.type === "number" || field.schema.type === "integer") {
+ return (
+ onChange(event.target.value)}
+ aria-describedby={ariaDescribedBy}
+ aria-invalid={invalid}
+ />
+ );
+ }
+
+ const isLongText = typeof field.schema.maxLength === "number" && field.schema.maxLength > 160;
+ if (field.schema.type === "string" && isLongText && field.schema.format === undefined) {
+ return (
+