fix: clarify preset and resume guidance

Author: RhysSullivan

notes/source-setup-sdk-flow.md

@@ -0,0 +1,12 @@
+# Source setup orchestration
+
+The web source-add flow currently owns a lot of business logic that agents have
+to rediscover through low-level tools: preset lookup, URL-to-endpoint mapping,
+endpoint probing, OAuth strategy choice, connection id generation, browser
+handoff, credential binding, and final source registration.
+
+Longer term, consider moving this into an SDK-level source setup service so the
+frontend and agent tools share the same state machine. The frontend would render
+steps from the service, while agent tools would return the same state with
+model-facing `instructions` fields. Keep low-level plugin tools as escape
+hatches, but make common preset flows first-class.

packages/core/execution/src/engine.ts

@@ -107,19 +107,31 @@ export const formatPausedExecution = (
   const lines: string[] = [`Execution paused: ${req.message}`];
   const isUrlElicitation = Predicate.isTagged(req, "UrlElicitation");
   const isFormElicitation = Predicate.isTagged(req, "FormElicitation");
+  const requestedSchema = isFormElicitation ? req.requestedSchema : undefined;
+  const hasRequestedSchema =
+    requestedSchema !== undefined && Object.keys(requestedSchema).length > 0;
+  const instructions = isUrlElicitation
+    ? `The user needs to open this URL in a browser and complete the flow. After the user finishes, call the resume tool with executionId "${paused.id}" and action "accept".`
+    : hasRequestedSchema
+      ? `Ask the user for values matching requestedSchema. Then call the resume tool with executionId "${paused.id}", action "accept", and content matching requestedSchema. If the user declines, call resume with action "decline" or "cancel".`
+      : `This is a model-side confirmation gate; there is no browser form to open. Ask the user whether to approve the paused tool call. If the user approves, call the resume tool with executionId "${paused.id}" and action "accept". If the user declines, call resume with action "decline" or "cancel".`;
 
   if (isUrlElicitation) {
     lines.push(`\nOpen this URL in a browser:\n${req.url}`);
-    lines.push("\nAfter the browser flow, resume with the executionId below:");
+    lines.push('\nAfter the browser flow, call the resume tool with action "accept".');
+  } else if (hasRequestedSchema) {
+    lines.push(
+      "\nAsk the user for a response matching the requested schema, then call the resume tool.",
+    );
+    lines.push(`\nRequested schema:\n${JSON.stringify(requestedSchema, null, 2)}`);
   } else {
-    lines.push("\nResume with the executionId below and a response matching the requested schema:");
-    const schema = req.requestedSchema;
-    if (schema && Object.keys(schema).length > 0) {
-      lines.push(`\nRequested schema:\n${JSON.stringify(schema, null, 2)}`);
-    }
+    lines.push(
+      '\nThis is a model-side confirmation gate; no browser form is waiting. Ask the user whether to approve, then call the resume tool with action "accept", "decline", or "cancel".',
+    );
   }
 
   lines.push(`\nexecutionId: ${paused.id}`);
+  lines.push(`\ninstructions: ${instructions}`);
 
   return {
     text: lines.join("\n"),
@@ -129,6 +141,7 @@ export const formatPausedExecution = (
       interaction: {
         kind: isUrlElicitation ? "url" : "form",
         message: req.message,
+        instructions,
         toolId: String(paused.elicitationContext.toolId),
         args: paused.elicitationContext.args,
         ...(isUrlElicitation ? { url: req.url } : {}),

packages/core/sdk/src/client.ts

@@ -96,6 +96,9 @@ export interface SourcePreset {
   /** URL passed as `initialUrl` to the add form. Omit for presets that
    *  don't use a URL (e.g. stdio MCP presets). */
   readonly url?: string;
+  /** Endpoint passed to agent-facing probe/add tools when their schema
+   *  uses `endpoint` instead of `url`. */
+  readonly endpoint?: string;
   /** Optional icon URL (favicon, logo). */
   readonly icon?: string;
   /** Shown in the top-level grid on the sources page when true. */

packages/core/sdk/src/core-tools.ts

@@ -122,6 +122,7 @@ const SourcePresetOutput = Schema.Struct({
   name: Schema.String,
   summary: Schema.String,
   url: Schema.optional(Schema.String),
+  endpoint: Schema.optional(Schema.String),
   icon: Schema.optional(Schema.String),
   featured: Schema.optional(Schema.Boolean),
   transport: Schema.optional(Schema.Literals(["remote", "stdio"])),
@@ -642,7 +643,7 @@ export const coreToolsPlugin = definePlugin((options: CoreToolsPluginOptions = {
         tool({
           name: "sources.presets",
           description:
-            "List the same popular source presets shown in Executor web's Connect dialog. Use this before asking the user what to connect; filter with `query` for names like GitHub, Stripe, Axiom, Google Calendar, Linear, or OpenAI. Use the returned `pluginId`, `url`, and optional stdio command to choose the matching add flow (`openapi.previewSpec`/`openapi.addSource`, `graphql.addSource`, `mcp.probeEndpoint`/`mcp.addSource`, or `googleDiscovery.probeDiscovery`/`googleDiscovery.addSource`).",
+            "List the same popular source presets shown in Executor web's Connect dialog. Use this before asking the user what to connect; filter with `query` for names like GitHub, Stripe, Axiom, Google Calendar, Linear, or OpenAI. For MCP and GraphQL presets, pass `endpoint` to the probe/add tools. For OpenAPI and Google Discovery presets, pass `url` to the preview/probe and add tools. For stdio MCP presets, use the returned command/args/env.",
           inputSchema: SourcesPresetsInputStd,
           outputSchema: SourcesPresetsOutputStd,
           execute: (input, { ctx }) =>

packages/core/sdk/src/plugin.ts

@@ -448,6 +448,7 @@ export interface SourcePreset {
   readonly name: string;
   readonly summary: string;
   readonly url?: string;
+  readonly endpoint?: string;
   readonly icon?: string;
   readonly featured?: boolean;
   readonly transport?: "remote" | "stdio";

packages/hosts/mcp/src/server.test.ts

@@ -559,6 +559,35 @@ describe("MCP host server — client without elicitation (pause/resume)", () =>
       const structured = result.structuredContent as Record<string, unknown>;
       expect(structured?.executionId).toBe("exec_42");
       expect(structured?.status).toBe("waiting_for_interaction");
+      const interaction = structured.interaction as Record<string, unknown>;
+      expect(interaction.instructions).toContain(
+        "Ask the user for values matching requestedSchema",
+      );
+    });
+  });
+
+  it("default model resume mode explains empty form schemas as model-side confirmation", async () => {
+    const engine = makeStubEngine({
+      executeWithPause: () =>
+        Effect.succeed(
+          makePausedResult(
+            "exec_confirm",
+            FormElicitation.make({ message: "Confirm source add", requestedSchema: {} }),
+          ),
+        ),
+    });
+
+    await withClient(engine, NO_CAPS, async (client) => {
+      const result = await client.callTool({
+        name: "execute",
+        arguments: { code: "confirm-me" },
+      });
+
+      expect(textOf(result)).toContain("no browser form is waiting");
+      const structured = result.structuredContent as Record<string, unknown>;
+      const interaction = structured.interaction as Record<string, unknown>;
+      expect(interaction.instructions).toContain("model-side confirmation gate");
+      expect(interaction.instructions).toContain('action "accept"');
     });
   });
 

packages/plugins/graphql/src/sdk/presets.ts

@@ -3,6 +3,7 @@ export interface GraphqlPreset {
   readonly name: string;
   readonly summary: string;
   readonly url: string;
+  readonly endpoint: string;
   readonly icon?: string;
   readonly featured?: boolean;
 }
@@ -13,6 +14,7 @@ export const graphqlPresets: readonly GraphqlPreset[] = [
     name: "GitHub GraphQL",
     summary: "Repos, issues, PRs, and users via GitHub's GraphQL API.",
     url: "https://api.github.com/graphql",
+    endpoint: "https://api.github.com/graphql",
     icon: "https://github.com/favicon.ico",
     featured: true,
   },
@@ -21,6 +23,7 @@ export const graphqlPresets: readonly GraphqlPreset[] = [
     name: "GitLab",
     summary: "Projects, merge requests, pipelines, and users.",
     url: "https://gitlab.com/api/graphql",
+    endpoint: "https://gitlab.com/api/graphql",
     icon: "https://gitlab.com/favicon.ico",
     featured: true,
   },
@@ -29,6 +32,7 @@ export const graphqlPresets: readonly GraphqlPreset[] = [
     name: "Linear",
     summary: "Issues, projects, teams, and cycles.",
     url: "https://api.linear.app/graphql",
+    endpoint: "https://api.linear.app/graphql",
     icon: "https://linear.app/favicon.ico",
     featured: true,
   },
@@ -37,13 +41,15 @@ export const graphqlPresets: readonly GraphqlPreset[] = [
     name: "Monday.com",
     summary: "Boards, items, columns, and workspace automation.",
     url: "https://api.monday.com/v2",
+    endpoint: "https://api.monday.com/v2",
     icon: "https://monday.com/favicon.ico",
   },
   {
     id: "anilist",
     name: "AniList",
     summary: "Anime and manga database — no auth required.",
     url: "https://graphql.anilist.co",
+    endpoint: "https://graphql.anilist.co",
     icon: "https://anilist.co/img/icons/favicon-32x32.png",
   },
 ];

packages/plugins/mcp/src/sdk/presets.ts

@@ -3,6 +3,7 @@ export interface McpRemotePreset {
   readonly name: string;
   readonly summary: string;
   readonly url: string;
+  readonly endpoint: string;
   readonly icon?: string;
   readonly featured?: boolean;
   readonly transport?: undefined;
@@ -28,6 +29,7 @@ export const mcpPresets: readonly McpPreset[] = [
     name: "DeepWiki",
     summary: "Search and read documentation from any GitHub repo.",
     url: "https://mcp.deepwiki.com/mcp",
+    endpoint: "https://mcp.deepwiki.com/mcp",
     icon: "https://deepwiki.com/favicon.ico",
     featured: true,
   },
@@ -36,6 +38,7 @@ export const mcpPresets: readonly McpPreset[] = [
     name: "Context7",
     summary: "Up-to-date docs and code examples for any library.",
     url: "https://mcp.context7.com/mcp",
+    endpoint: "https://mcp.context7.com/mcp",
     icon: "https://context7.com/favicon.ico",
     featured: true,
   },
@@ -44,6 +47,7 @@ export const mcpPresets: readonly McpPreset[] = [
     name: "Browserbase",
     summary: "Cloud browser sessions for web scraping and automation.",
     url: "https://mcp.browserbase.com/mcp",
+    endpoint: "https://mcp.browserbase.com/mcp",
     icon: "https://www.browserbase.com/favicon.ico",
     featured: true,
   },
@@ -52,6 +56,7 @@ export const mcpPresets: readonly McpPreset[] = [
     name: "Firecrawl",
     summary: "Crawl and scrape websites into structured data.",
     url: "https://mcp.firecrawl.dev/mcp",
+    endpoint: "https://mcp.firecrawl.dev/mcp",
     icon: "https://www.firecrawl.dev/favicon.ico",
     featured: true,
   },
@@ -60,6 +65,7 @@ export const mcpPresets: readonly McpPreset[] = [
     name: "Neon",
     summary: "Serverless Postgres — branches, queries, and management.",
     url: "https://mcp.neon.tech/mcp",
+    endpoint: "https://mcp.neon.tech/mcp",
     icon: "https://neon.tech/favicon/favicon.ico",
     featured: true,
   },
@@ -68,6 +74,7 @@ export const mcpPresets: readonly McpPreset[] = [
     name: "Axiom",
     summary: "Query, analyze, and monitor your logs and event data.",
     url: "https://mcp.axiom.co/mcp",
+    endpoint: "https://mcp.axiom.co/mcp",
     icon: "https://axiom.co/favicon.ico",
     featured: true,
   },
@@ -76,6 +83,7 @@ export const mcpPresets: readonly McpPreset[] = [
     name: "Stripe",
     summary: "Manage payments, subscriptions, and billing via MCP.",
     url: "https://mcp.stripe.com",
+    endpoint: "https://mcp.stripe.com",
     icon: "https://stripe.com/favicon.ico",
     featured: true,
   },
@@ -84,6 +92,7 @@ export const mcpPresets: readonly McpPreset[] = [
     name: "Linear",
     summary: "Issues, projects, teams, and cycles via MCP.",
     url: "https://mcp.linear.app/mcp",
+    endpoint: "https://mcp.linear.app/mcp",
     icon: "https://linear.app/favicon.ico",
     featured: true,
   },
@@ -92,6 +101,7 @@ export const mcpPresets: readonly McpPreset[] = [
     name: "Notion",
     summary: "Databases, pages, blocks, and search via MCP.",
     url: "https://mcp.notion.com/mcp",
+    endpoint: "https://mcp.notion.com/mcp",
     icon: "https://www.notion.com/front-static/favicon.ico",
     featured: true,
   },
@@ -100,13 +110,15 @@ export const mcpPresets: readonly McpPreset[] = [
     name: "Sentry",
     summary: "Error monitoring, issues, and performance data.",
     url: "https://mcp.sentry.dev/mcp",
+    endpoint: "https://mcp.sentry.dev/mcp",
     icon: "https://sentry-brand.storage.googleapis.com/sentry-glyph-black.png",
   },
   {
     id: "cloudflare",
     name: "Cloudflare",
     summary: "Workers, KV, D1, R2, and DNS management via MCP.",
     url: "https://mcp.cloudflare.com/mcp",
+    endpoint: "https://mcp.cloudflare.com/mcp",
     icon: "https://cloudflare.com/favicon.ico",
   },
   {