@isomorph.ai/app-sdk 1.36.3 → 1.38.0

package/README.md

@@ -393,7 +393,7 @@ A job's agent can hand one browser task, writes included, to the computer use se
 import { createComputerUseTool } from '@isomorph.ai/app-sdk/dist/computer-use.js';
 // Inside a job handler:
 const computerUse = createComputerUseTool({ runKey: ctx.runId ?? `my-job/${ctx.scheduledAt}`, progress: ctx.progress, cancelled: ctx.cancelled });
-// Add { computerUse } to generateText's tools. It returns { status: 'done' | 'failed', summary, finalUrl }.
+// Add { computerUse } to generateText's tools. It returns { status: 'done' | 'failed', summary, finalUrl, downloads }.
 ```
 
 - The tool calls the task API at `ISOMORPH_COMPUTER_USE_URL` (region `ISOMORPH_COMPUTER_USE_REGION`, default `us-east-1`); Provision sets both when the cell has the API. Each request is signed with SigV4 (`execute-api`) as the runtime's own role: the Lambda environment's credentials, or on a cluster pod its ServiceAccount role through STS `AssumeRoleWithWebIdentity`.
@@ -409,10 +409,11 @@ Options the app passes, never the model:
 - `session`: the name of a runtime secret a sign-in was saved under (`finishSignIn`'s `saveAs`, below). The task starts signed in and can use only that sign-in's websites. When the task is `done` the refreshed session is saved back to the same secret. A missing one fails with `No saved sign-in named <name>.` Run one task per saved sign-in at a time: two tasks would both save back, and some websites sign out the older copy.
 - `secrets`: `{ name: value }`, at most 10, names `^[A-Za-z][A-Za-z0-9_-]{0,63}$`, values up to 4096 bytes. The computer types a value into a password field by its name; the model sees only the names. Never put a password or any other credential in the task text; pass it here and say "sign in with the `password` secret".
 - `allowedHosts`: the websites (1 to 10 lower-case hostnames) a task with `secrets` and no `session` may use. A saved sign-in carries its own.
+- `onDownload({ name, contentType, size, blob })`: called once for each file a `done` task downloaded, one at a time, before the tool returns (at most 10 files, 100 MiB each). Store the `blob` yourself; the CUA keeps the files for a day at most. Without it nothing is fetched. A link that does not answer 200 fails the tool. The model only sees `downloads: [{ name, size }]`.
 
 A task with `session` or `secrets` works the page through clicks and typing only. `connectionId` is gone: pass `session`.
 
-(1.25.0, 1.36.0; data plane ADR 0078, ADR 0090)
+(1.25.0, 1.36.0, 1.37.0; data plane ADR 0078, ADR 0090, ADR 0091)
 
 ## Browser sign-in for computer use
 
@@ -626,3 +627,28 @@ subfolders, shortcuts and native Google documents are excluded. No historical ba
 Background read consent is required. Existing file-read size limits still apply. Provider
 subscriptions and real upload acceptance must be verified after deployment. Retries retain
 one durable job run; accounting/email side effects still need their own idempotency keys.
+
+
+### Selected MCP tools (server actions and jobs)
+
+Connect a compatible MCP server in Integrations, then select the app's tools with
+`isomorph integrations tools select`. This writes accepted descriptors into the
+existing `.isomorph/integrations.json`; `isomorph check` verifies literal usage.
+
+```ts
+const result = await isomorph.integrations.execute('finance', {
+  operation: 'mcp.tool.call', resource: 'server',
+  input: { tool: 'Invoices.Read', arguments: { id: invoiceId } },
+});
+const tools = await isomorph.integrations.tools('finance', {
+  tools: ['Invoices.Read', 'Invoices.Create'],
+  runId: persistedWorkflowId,
+});
+```
+
+Use the provider's exact selected tool names. The helper loads accepted schemas
+locally and returns AI SDK tools; it does not rediscover provider tools. For writes,
+keep the workflow run ID and tool-call ID stable across retries. Direct writes
+must supply their own persisted UUID `idempotencyKey`. A tool marked read-only
+does not require a key. An incomplete replay requires reconciliation, not a new
+write. Account consent and app permissions are enforced by the platform.

package/dist/computer-use.d.ts

@@ -3,6 +3,12 @@ export interface ComputerUseFile {
     contentType: "application/pdf";
     dataBase64: string;
 }
+export interface ComputerUseDownload {
+    name: string;
+    contentType: string;
+    size: number;
+    blob: Blob;
+}
 export interface ComputerUseOptions {
     /** App-authorized PDFs, at most five files and 2 MiB total. Never supplied by the model. */
     files?: readonly ComputerUseFile[];
@@ -18,6 +24,8 @@ export interface ComputerUseOptions {
      * Never put a credential in the task text.
      */
     secrets?: Readonly<Record<string, string>>;
+    /** The app's code gets each file the task downloaded, one at a time, when the task is done. Never seen by the model. */
+    onDownload?(download: ComputerUseDownload): Promise<void> | void;
     /** The job's runId, or `<job name>/<scheduledAt>` for a scheduled job: one task record per job run. */
     runKey: string;
     /** The job's progress: called on each new step and at least once a minute, which renews the job's lease. */
@@ -35,6 +43,11 @@ export interface ComputerUseResult {
     summary: string | null;
     /** The page the browser was on when the task ended; a sign-in page there means the saved sign-in has expired. */
     finalUrl: string | null;
+    /** The files the task downloaded; their bytes went to onDownload. */
+    downloads: {
+        name: string;
+        size: number;
+    }[];
 }
 export declare function createComputerUseTool(options: ComputerUseOptions): ({
     deferLoading?: boolean;

package/dist/computer-use.js

@@ -2,7 +2,8 @@
 // agent (CUA) and waits for its result. Calls go to the CUA's task API, signed
 // with SigV4 as the runtime's own role (ADR 0078). A saved sign-in is a runtime
 // secret: its session goes with the task and the refreshed one is saved back
-// to it (ADR 0090).
+// to it (ADR 0090). Files the task downloads go to the app's onDownload, never
+// to the model (ADR 0091).
 import { setTimeout as sleep } from 'node:timers/promises';
 import { jsonSchema, tool } from 'ai';
 import { allowedHostsOf, computerUseApi, refused } from './computer-use-api.js';
@@ -71,7 +72,7 @@ export function createComputerUseTool(options) {
         }
     };
     return tool({
-        description: 'Do one task in a web browser, such as filling in and submitting a form on a website. Describe the whole task in plain words, with the website address and any details it needs. Waits until the task ends and returns its status and a summary.',
+        description: 'Do one task in a web browser, such as filling in and submitting a form on a website. Describe the whole task in plain words, with the website address and any details it needs. Waits until the task ends and returns its status and a summary. Files the task downloads go to the app; the result lists their names.',
         inputSchema: jsonSchema({ type: 'object', properties: { task: { type: 'string', minLength: 1 } }, required: ['task'], additionalProperties: false }),
         execute: async ({ task }) => {
             await api.post('/tasks', {
@@ -101,7 +102,17 @@ export function createComputerUseTool(options) {
                     if (answer.status === 'done' || answer.status === 'failed') {
                         if (answer.status === 'done' && session !== undefined && answer.session)
                             await runtimeSecrets.put(session, JSON.stringify(answer.session), transport);
-                        return { status: answer.status, summary: answer.summary ?? null, finalUrl: answer.final_url ?? null };
+                        const downloads = answer.downloads ?? [];
+                        if (options.onDownload) {
+                            for (const { name, contentType, size, url } of downloads) {
+                                await options.progress(99, `Computer use download: ${name}`);
+                                const response = await (options.fetch ?? fetch)(url);
+                                if (response.status !== 200)
+                                    throw refused(`the download ${name}`, response.status, undefined);
+                                await options.onDownload({ name, contentType, size, blob: await response.blob() });
+                            }
+                        }
+                        return { status: answer.status, summary: answer.summary ?? null, finalUrl: answer.final_url ?? null, downloads: downloads.map(({ name, size }) => ({ name, size })) };
                     }
                     if (answer.steps > steps || now() - reported >= HEARTBEAT_MS) {
                         steps = Math.max(steps, answer.steps);

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import type { McpCallRequest, McpCallResult, McpToolsOptions } from './mcp-tools.js';
+export type { McpCallRequest, McpCallResult, McpToolDescriptor, McpSelectedTool, McpToolsOptions } from './mcp-tools.js';
 import { type IsomorphUserRole } from './user-role.js';
 export type { IsomorphUserRole } from './user-role.js';
 export type IsomorphErrorCategory = 'AUTH_REQUIRED' | 'FORBIDDEN' | 'NOT_FOUND' | 'CONFLICT' | 'VALIDATION_FAILED' | 'RATE_LIMITED' | 'UNAVAILABLE' | 'INTERNAL';
@@ -1232,7 +1234,7 @@ export type ZohoBooksRequest = {
         lineItems: BooksInvoiceLineInput[];
     };
 };
-export type IntegrationRequest = ZohoBooksRequest | ServiceRequest | SlackChannelHistoryRequest | SlackMessagePostRequest | SlackMessageUpdateRequest | SlackMessageDeleteRequest | SlackDmSendRequest | SlackUserLookupRequest | WarehouseViewReadRequest | WarehouseTableAppendRequest | PhoneSmsListRequest | PhoneNumberGetRequest | GmailThreadListRequest | GmailThreadReadRequest | GmailMessageReadRequest | GmailAttachmentReadRequest | GmailMessageSendRequest | BasecampProjectListRequest | BasecampTodolistListRequest | BasecampTodoListRequest | BasecampTodoCreateRequest | BasecampTodoCompleteRequest | BasecampMessageListRequest | BasecampMessagePostRequest | BasecampCommentListRequest | BasecampCommentPostRequest | BasecampCampfirePostRequest | BasecampPeopleListRequest | SharePointListListRequest | SharePointItemListRequest | SharePointItemCreateRequest | SharePointItemUpdateRequest | SharePointDriveListRequest | SharePointFileListRequest | SharePointFileSearchRequest | SharePointFileReadRequest | SharePointFileUploadRequest | CalendarCalendarListRequest | CalendarEventListRequest | CalendarEventReadRequest | CalendarEventCreateRequest | CalendarEventUpdateRequest | CalendarEventCancelRequest | DriveFileListRequest | DriveFileSearchRequest | DriveFileReadRequest | DriveFileUploadRequest | DriveFolderCreateRequest | DocsDocumentReadRequest | DocsDocumentCreateRequest | DocsDocumentAppendRequest | DocsTextReplaceRequest | SheetsSpreadsheetReadRequest | SheetsValuesReadRequest | SheetsValuesAppendRequest | SheetsValuesUpdateRequest | SheetsValuesClearRequest | SheetsSpreadsheetCreateRequest | OutlookMessageListRequest | OutlookMessageReadRequest | OutlookAttachmentReadRequest | OutlookMessageSendRequest | OutlookMessageReplyRequest | OutlookEventListRequest | OutlookEventReadRequest | OutlookEventCreateRequest | OutlookEventUpdateRequest | OutlookEventCancelRequest | OneDriveFileListRequest | OneDriveFileSearchRequest | OneDriveFileReadRequest | OneDriveFileUploadRequest | OneDriveFolderCreateRequest | ExcelWorksheetListRequest | ExcelRangeReadRequest | ExcelRangeUpdateRequest | ExcelTableListRequest | ExcelRowAddRequest | ExcelWorksheetAddRequest | TeamsMessageListRequest | TeamsMessagePostRequest | TeamsReplyPostRequest;
+export type IntegrationRequest = McpCallRequest | ZohoBooksRequest | ServiceRequest | SlackChannelHistoryRequest | SlackMessagePostRequest | SlackMessageUpdateRequest | SlackMessageDeleteRequest | SlackDmSendRequest | SlackUserLookupRequest | WarehouseViewReadRequest | WarehouseTableAppendRequest | PhoneSmsListRequest | PhoneNumberGetRequest | GmailThreadListRequest | GmailThreadReadRequest | GmailMessageReadRequest | GmailAttachmentReadRequest | GmailMessageSendRequest | BasecampProjectListRequest | BasecampTodolistListRequest | BasecampTodoListRequest | BasecampTodoCreateRequest | BasecampTodoCompleteRequest | BasecampMessageListRequest | BasecampMessagePostRequest | BasecampCommentListRequest | BasecampCommentPostRequest | BasecampCampfirePostRequest | BasecampPeopleListRequest | SharePointListListRequest | SharePointItemListRequest | SharePointItemCreateRequest | SharePointItemUpdateRequest | SharePointDriveListRequest | SharePointFileListRequest | SharePointFileSearchRequest | SharePointFileReadRequest | SharePointFileUploadRequest | CalendarCalendarListRequest | CalendarEventListRequest | CalendarEventReadRequest | CalendarEventCreateRequest | CalendarEventUpdateRequest | CalendarEventCancelRequest | DriveFileListRequest | DriveFileSearchRequest | DriveFileReadRequest | DriveFileUploadRequest | DriveFolderCreateRequest | DocsDocumentReadRequest | DocsDocumentCreateRequest | DocsDocumentAppendRequest | DocsTextReplaceRequest | SheetsSpreadsheetReadRequest | SheetsValuesReadRequest | SheetsValuesAppendRequest | SheetsValuesUpdateRequest | SheetsValuesClearRequest | SheetsSpreadsheetCreateRequest | OutlookMessageListRequest | OutlookMessageReadRequest | OutlookAttachmentReadRequest | OutlookMessageSendRequest | OutlookMessageReplyRequest | OutlookEventListRequest | OutlookEventReadRequest | OutlookEventCreateRequest | OutlookEventUpdateRequest | OutlookEventCancelRequest | OneDriveFileListRequest | OneDriveFileSearchRequest | OneDriveFileReadRequest | OneDriveFileUploadRequest | OneDriveFolderCreateRequest | ExcelWorksheetListRequest | ExcelRangeReadRequest | ExcelRangeUpdateRequest | ExcelTableListRequest | ExcelRowAddRequest | ExcelWorksheetAddRequest | TeamsMessageListRequest | TeamsMessagePostRequest | TeamsReplyPostRequest;
 export type IntegrationOperation = IntegrationRequest['operation'];
 export interface SlackMessage {
     id: string;
@@ -1726,7 +1728,7 @@ export interface TeamsMessagePostResult {
     id: string;
     webUrl: string;
 }
-export type IntegrationResult<R extends IntegrationRequest> = R extends {
+export type IntegrationResult<R extends IntegrationRequest> = R extends McpCallRequest ? McpCallResult : R extends {
     operation: 'zohobooks.contact.list';
 } ? {
     booksContacts: {
@@ -2057,6 +2059,15 @@ export declare function createClient(options?: ClientOptions): {
         page: (path?: string) => Promise<void>;
     };
     integrations: {
+        tools: (connection: string, options: McpToolsOptions) => Promise<Record<string, import("ai").Tool<Record<string, unknown>, {
+            content?: Array<Record<string, unknown>>;
+            structuredContent?: Record<string, unknown>;
+            isError?: boolean;
+            replay?: {
+                complete: boolean;
+                summary?: string;
+            };
+        }>>>;
         execute: <R extends IntegrationRequest>(connection: string, request: R) => Promise<IntegrationResult<R>>;
         connect: (connection: string) => Promise<IntegrationConnectResult>;
         disconnect: (connection: string) => Promise<IntegrationDisconnectResult>;

package/dist/index.js

@@ -459,6 +459,28 @@ export function createClient(options = {}) {
         return user;
     };
     const transport = new Transport(options, () => notifyIdentity(null));
+    const executeIntegration = (connection, request) => {
+        // The contract's per-operation rules, refused here before any request
+        // is made, with the platform's own sentence and the field named — so
+        // `isomorph check` (which runs retained journeys through this client)
+        // and the deployed app fail the same way at build time, not at runtime.
+        const checked = validateIntegrationExecuteInput(request.operation, request.input);
+        const problem = (request.operation === 'warehouse.table.append' ? warehouseAppendProblem(request) : undefined)
+            ?? (!checked.ok ? checked.problem
+                : request.operation === 'warehouse.view.read' ? warehouseReadProblem(request.input ?? {}) : undefined);
+        if (problem) {
+            return Promise.reject(new IsomorphError('VALIDATION_FAILED', problem.message, undefined, { code: 'INPUT_INVALID', field: problem.field }));
+        }
+        // Exactly the contract's fields go on the wire: metadata declares which
+        // operations accept `mode`; identity and stray fields are not sent.
+        // phone.number.get takes no input, but the contract keeps `input`
+        // required on the wire (ADR 0029), so an omitted one goes out as {}.
+        const { operation, resource, input: given, idempotencyKey, mode } = request;
+        const input = given === undefined && operation === 'phone.number.get' ? {} : given;
+        return transport.json('/_harbour/integrations/execute', {
+            method: 'POST', body: JSON.stringify({ connection, operation, ...(operation !== 'service.request' ? { resource } : {}), ...(input !== undefined ? { input } : {}), ...(idempotencyKey !== undefined ? { idempotencyKey } : {}), ...(IntegrationOperations[operation]?.declaredMode && mode !== undefined ? { mode } : {}) }),
+        });
+    };
     const socketFactory = options.websocket ?? ((url) => defaultSocketFactory(url, options.identity));
     const refreshIdentity = () => {
         if (refreshInFlight)
@@ -805,28 +827,11 @@ export function createClient(options = {}) {
             }),
         },
         integrations: {
-            execute: (connection, request) => {
-                // The contract's per-operation rules, refused here before any request
-                // is made, with the platform's own sentence and the field named — so
-                // `isomorph check` (which runs retained journeys through this client)
-                // and the deployed app fail the same way at build time, not at runtime.
-                const checked = validateIntegrationExecuteInput(request.operation, request.input);
-                const problem = (request.operation === 'warehouse.table.append' ? warehouseAppendProblem(request) : undefined)
-                    ?? (!checked.ok ? checked.problem
-                        : request.operation === 'warehouse.view.read' ? warehouseReadProblem(request.input ?? {}) : undefined);
-                if (problem) {
-                    return Promise.reject(new IsomorphError('VALIDATION_FAILED', problem.message, undefined, { code: 'INPUT_INVALID', field: problem.field }));
-                }
-                // Exactly the contract's fields go on the wire: metadata declares which
-                // operations accept `mode`; identity and stray fields are not sent.
-                // phone.number.get takes no input, but the contract keeps `input`
-                // required on the wire (ADR 0029), so an omitted one goes out as {}.
-                const { operation, resource, input: given, idempotencyKey, mode } = request;
-                const input = given === undefined && operation === 'phone.number.get' ? {} : given;
-                return transport.json('/_harbour/integrations/execute', {
-                    method: 'POST', body: JSON.stringify({ connection, operation, ...(operation !== 'service.request' ? { resource } : {}), ...(input !== undefined ? { input } : {}), ...(idempotencyKey !== undefined ? { idempotencyKey } : {}), ...(IntegrationOperations[operation]?.declaredMode && mode !== undefined ? { mode } : {}) }),
-                });
+            tools: async (connection, options) => {
+                const { createMcpTools } = await import('./mcp-tools.js');
+                return createMcpTools(connection, options, request => executeIntegration(connection, request));
             },
+            execute: executeIntegration,
             // In a browser the consent returns the person to this page (without its
             // fragment); governance accepts it only as a registered page of this app
             // (ADR 0030). Outside a browser there is no page, and none is sent.

package/dist/integration-execute-input-rules.d.ts

@@ -2556,6 +2556,21 @@ export declare const IntegrationExecuteInputRules: {
             };
         };
     };
+    readonly "mcp.tool.call": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly tool: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 1;
+                readonly maxLength: 128;
+            };
+            readonly arguments: {
+                readonly kind: "object";
+                readonly required: true;
+            };
+        };
+    };
 };
 export type IntegrationExecuteOperation = keyof typeof IntegrationExecuteInputRules;
 /** The upper bound of one integer input as a literal type: integrationExecuteInputMaximum('slack.channel.history', 'limit') is 15. */

package/dist/integration-execute-input-rules.js

@@ -792,6 +792,13 @@ export const IntegrationExecuteInputRules = {
             documentId: { kind: "string", required: true, minLength: 0, maxLength: 32, pattern: "^[0-9]{1,32}$" },
         },
     },
+    "mcp.tool.call": {
+        idempotencyKey: false,
+        fields: {
+            tool: { kind: "string", required: true, minLength: 1, maxLength: 128 },
+            arguments: { kind: "object", required: true },
+        },
+    },
 };
 /** The upper bound of one integer input as a literal type: integrationExecuteInputMaximum('slack.channel.history', 'limit') is 15. */
 export function integrationExecuteInputMaximum(operation, field) {

package/dist/integration-operations.d.ts

@@ -665,4 +665,12 @@ export declare const IntegrationOperations: {
         readonly declaredMode: false;
         readonly idempotencyKey: false;
     };
+    readonly "mcp.tool.call": {
+        readonly kind: "mcp";
+        readonly identities: readonly ["user"];
+        readonly readOnly: false;
+        readonly declaredMode: false;
+        readonly idempotencyKey: false;
+        readonly runtimeIdempotency: true;
+    };
 };

package/dist/integration-operations.js

@@ -860,5 +860,15 @@ export const IntegrationOperations = {
         "readOnly": true,
         "declaredMode": false,
         "idempotencyKey": false
+    },
+    "mcp.tool.call": {
+        "kind": "mcp",
+        "identities": [
+            "user"
+        ],
+        "readOnly": false,
+        "declaredMode": false,
+        "idempotencyKey": false,
+        "runtimeIdempotency": true
     }
 };

package/dist/mcp-tools.d.ts

@@ -0,0 +1,45 @@
+import type { Tool } from 'ai';
+export interface McpToolDescriptor {
+    name: string;
+    description?: string;
+    title?: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    annotations?: {
+        readOnlyHint?: boolean;
+        [key: string]: unknown;
+    };
+}
+export interface McpSelectedTool {
+    name: string;
+    contractHash: string;
+    descriptor: McpToolDescriptor;
+}
+export interface McpCallRequest {
+    operation: 'mcp.tool.call';
+    resource: 'server';
+    mode?: 'user';
+    input: {
+        tool: string;
+        arguments: Record<string, unknown>;
+    };
+    idempotencyKey?: string;
+}
+export interface McpCallResult {
+    mcp: {
+        content?: Array<Record<string, unknown>>;
+        structuredContent?: Record<string, unknown>;
+        isError?: boolean;
+        replay?: {
+            complete: boolean;
+            summary?: string;
+        };
+    };
+}
+export interface McpToolsOptions {
+    tools: readonly string[];
+    runId: string;
+}
+type Execute = (request: McpCallRequest) => Promise<McpCallResult>;
+export declare function createMcpTools(connection: string, options: McpToolsOptions, execute: Execute): Promise<Record<string, Tool<Record<string, unknown>, McpCallResult['mcp']>>>;
+export {};

package/dist/mcp-tools.js

@@ -0,0 +1,51 @@
+async function digest(parts) {
+    return new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify(parts))));
+}
+function hex(bytes) {
+    return Array.from(bytes, value => value.toString(16).padStart(2, '0')).join('');
+}
+async function invocationKey(runId, tool, callId) {
+    const bytes = (await digest([runId, tool, callId])).slice(0, 16);
+    bytes[6] = (bytes[6] & 15) | 128;
+    bytes[8] = (bytes[8] & 63) | 128;
+    const value = hex(bytes);
+    return `${value.slice(0, 8)}-${value.slice(8, 12)}-${value.slice(12, 16)}-${value.slice(16, 20)}-${value.slice(20)}`;
+}
+export async function createMcpTools(connection, options, execute) {
+    if (typeof window !== 'undefined' && typeof window.document !== 'undefined')
+        throw new Error('MCP agent tools run in actions or jobs.');
+    if (!options.runId || !Array.isArray(options.tools) || options.tools.length < 1 || options.tools.length > 64 || new Set(options.tools).size !== options.tools.length)
+        throw new Error('MCP tools need a durable runId and 1–64 unique selected tool names.');
+    const [{ readFile }, { resolve }, { jsonSchema }] = await Promise.all([import('node:fs/promises'), import('node:path'), import('ai')]);
+    const root = process.env.ISOMORPH_APP_ROOT || process.cwd();
+    const declaration = JSON.parse(await readFile(resolve(root, '.isomorph/integrations.json'), 'utf8'));
+    const source = declaration.connections[connection];
+    if (declaration.schema !== 'isomorph.app-integrations/2.0' || source?.kind !== 'mcp' || !source.mcp)
+        throw new Error('This MCP connection is not declared for the app. Run the integration selection and checks.');
+    const allowed = new Map(source.mcp.tools.map(tool => [tool.name, tool]));
+    const result = {};
+    for (const name of options.tools) {
+        const selected = allowed.get(name);
+        if (!selected || selected.descriptor.name !== name)
+            throw new Error(`MCP tool ${name} is not declared for this app.`);
+        const descriptor = selected.descriptor;
+        const alias = `mcp_${hex((await digest([connection, name])).slice(0, 20))}`;
+        result[alias] = {
+            description: descriptor.description ?? descriptor.title ?? name,
+            inputSchema: jsonSchema(descriptor.inputSchema),
+            execute: async (input, context) => {
+                const readOnly = descriptor.annotations?.readOnlyHint === true;
+                if (!readOnly && !context.toolCallId)
+                    throw new Error('MCP writes need a persisted toolCallId. Do not retry a write with a new invocation ID.');
+                const response = await execute({
+                    operation: 'mcp.tool.call', resource: 'server', mode: 'user', input: { tool: name, arguments: input },
+                    ...(!readOnly ? { idempotencyKey: await invocationKey(options.runId, name, context.toolCallId) } : {}),
+                });
+                if (response.mcp.replay?.complete === false)
+                    throw new Error('This MCP action already completed, but its result was not retained. Reconcile the provider record before continuing; do not repeat the action.');
+                return response.mcp;
+            },
+        };
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isomorph.ai/app-sdk",
-  "version": "1.36.3",
+  "version": "1.38.0",
   "type": "module",
   "repository": {
     "type": "git",