@isomorph.ai/app-sdk 1.38.0 → 1.39.0

package/README.md

@@ -400,6 +400,7 @@ const computerUse = createComputerUseTool({ runKey: ctx.runId ?? `my-job/${ctx.s
 - It starts the task with `POST /tasks`, then checks `POST /tasks/check` every 5 s until the task is `done` or `failed`.
 - It calls `progress(step count, note)` on every new step and at least once a minute, so the job's lease does not run out.
 - When `cancelled()` turns true it sends `POST /tasks/cancel` once and keeps checking until the task has `failed`.
+- While the task is `queued` and the CUA reports `waiting` (no computer is free), the progress note says so with the minutes waited. After `maxQueueMs` (20 minutes unless set) the tool cancels the task and returns `failed` with `No computer was free within N minutes; the task was cancelled before it started.`
 - One task record per `runKey`: a retried job run sends the same key and gets the queued, running or finished task back. Only a failed task starts a new attempt.
 - `finalUrl` is the page the browser ended on. A website's sign-in page there means a saved sign-in has expired: ask the person to sign in again.
 
@@ -407,13 +408,14 @@ Options the app passes, never the model:
 
 - `files`: PDFs the task may upload, at most five and 2 MiB in all.
 - `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".
+- `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, and only there: it refuses to type a secret into a visible field, since the model reads the page after every step. 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". A user ID, customer ID or email is not a secret: give it in the task text.
+- `maxQueueMs`: how long the task may wait for a free computer before the tool cancels it (20 minutes unless set).
 - `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, 1.37.0; data plane ADR 0078, ADR 0090, ADR 0091)
+(1.25.0, 1.36.0, 1.37.0, 1.39.0; data plane ADR 0078, ADR 0090, ADR 0091, ADR 0092)
 
 ## Browser sign-in for computer use
 
@@ -431,7 +433,7 @@ await sendSignInInput(handle, { op: 'click', x: 640, y: 400 });
 await finishSignIn(handle, { saveAs: `vendor-central/${ctx.user.id}` }); // { url }
 ```
 
-- `startSignIn` starts a computer that may open only `allowedHosts` and returns an opaque handle for the calls that follow; the computer answers only this app's role and stops after 30 minutes.
+- `startSignIn` starts a computer that may open only `allowedHosts` and returns an opaque handle for the calls that follow; the computer answers only this app's role and stops after 30 minutes. It opens `startUrl`, an HTTPS page on one of those websites, or the first website's front page: an account on `accounts.zoho.in` lists that host first or passes it as `startUrl`.
 - `showSignIn` gives `{ status: 'starting' }` until the browser is up, then `{ status: 'ready', screenshot, url }`: a base64 PNG of the 1280×800 screen and the page's address.
 - `sendSignInInput` takes `{ op: 'click', x, y }` (screen pixels), `{ op: 'typeText', value }` (up to 512 characters), `{ op: 'pressKey', key }` (such as `Enter` or `Tab`) or `{ op: 'scroll', direction: 'up' | 'down' }`.
 - `finishSignIn` saves the session (cookies and site storage of the allowed websites, at most 60 KB) as the runtime secret `saveAs`, stops the computer and returns the page it was on. App code never holds the cookies.

package/dist/computer-use-sign-in.d.ts

@@ -22,9 +22,13 @@ export type SignInPage = {
     screenshot: string;
     url: string;
 };
-/** Starts a sign-in computer limited to `allowedHosts`; the handle names it in the calls that follow. */
-export declare function startSignIn({ allowedHosts, ...transport }: {
+/**
+ * Starts a sign-in computer limited to `allowedHosts`; the handle names it in the calls that follow. The
+ * computer opens `startUrl`, an HTTPS page on one of those websites, or the first website's front page.
+ */
+export declare function startSignIn({ allowedHosts, startUrl, ...transport }: {
     allowedHosts: readonly string[];
+    startUrl?: string;
 } & ComputerUseTransport): Promise<string>;
 export declare function showSignIn(handle: string, transport?: ComputerUseTransport): Promise<SignInPage>;
 export declare function sendSignInInput(handle: string, action: SignInAction, transport?: ComputerUseTransport): Promise<void>;

package/dist/computer-use-sign-in.js

@@ -5,6 +5,19 @@
 // jobs. The computer answers only the app role that started it.
 import { allowedHostsOf, computerUseApi } from './computer-use-api.js';
 import { runtimeSecretLocation, runtimeSecrets } from './secrets.js';
+function startUrlOf(startUrl, hosts) {
+    let url;
+    try {
+        url = new URL(String(startUrl));
+    }
+    catch {
+        url = undefined;
+    }
+    if (typeof startUrl !== 'string' || !url || url.protocol !== 'https:' || url.username || url.password || !hosts.includes(url.hostname)) {
+        throw new Error('startUrl must be an HTTPS address on one of the allowedHosts.');
+    }
+    return startUrl;
+}
 function computerOf(handle) {
     let computer;
     try {
@@ -17,10 +30,13 @@ function computerOf(handle) {
         throw new Error('This is not a sign-in handle from startSignIn.');
     return { computerId: computer.computerId, endpoint: computer.endpoint };
 }
-/** Starts a sign-in computer limited to `allowedHosts`; the handle names it in the calls that follow. */
-export async function startSignIn({ allowedHosts, ...transport }) {
+/**
+ * Starts a sign-in computer limited to `allowedHosts`; the handle names it in the calls that follow. The
+ * computer opens `startUrl`, an HTTPS page on one of those websites, or the first website's front page.
+ */
+export async function startSignIn({ allowedHosts, startUrl, ...transport }) {
     const hosts = allowedHostsOf(allowedHosts);
-    const { computerId, endpoint } = await computerUseApi(transport).post('/computers/start', { allowedHosts: hosts });
+    const { computerId, endpoint } = await computerUseApi(transport).post('/computers/start', { allowedHosts: hosts, ...(startUrl === undefined ? {} : { startUrl: startUrlOf(startUrl, hosts) }) });
     return Buffer.from(JSON.stringify({ computerId, endpoint })).toString('base64url');
 }
 export async function showSignIn(handle, transport = {}) {

package/dist/computer-use.d.ts

@@ -21,7 +21,8 @@ export interface ComputerUseOptions {
     allowedHosts?: readonly string[];
     /**
      * Values the computer types into a password field by name, at most 10; the model sees only the names.
-     * Never put a credential in the task text.
+     * Never put a credential in the task text. A user ID, customer ID or email is not a secret: the
+     * computer refuses to type a secret into a visible field, so give those 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. */
@@ -34,6 +35,11 @@ export interface ComputerUseOptions {
     cancelled(): Promise<boolean> | boolean;
     env?: NodeJS.ProcessEnv;
     fetch?: typeof fetch;
+    /**
+     * How long the task may wait for a free computer before the tool cancels it and returns `failed`;
+     * 20 minutes unless set. The wait is reported through `progress` while it lasts.
+     */
+    maxQueueMs?: number;
     /** The pause between checks; the tests shorten it. */
     pollIntervalMs?: number;
     now?: () => number;

package/dist/computer-use.js

@@ -9,8 +9,18 @@ import { jsonSchema, tool } from 'ai';
 import { allowedHostsOf, computerUseApi, refused } from './computer-use-api.js';
 import { runtimeSecretLocation, runtimeSecrets } from './secrets.js';
 const HEARTBEAT_MS = 60_000;
+const DEFAULT_MAX_QUEUE_MS = 20 * 60_000;
 // Checks the API did not answer (a throttle, a 5xx, no connection) before the tool gives up: about a minute.
 const MAX_MISSED_CHECKS = 12;
+/** The progress note of a task that has not started: the wait and its reason when the CUA names one. */
+function queueNote(answer, waitedMs) {
+    if (answer.status !== 'queued' || !answer.waiting)
+        return `Computer use task ${answer.status}.`;
+    const minutes = Math.max(1, Math.round(waitedMs / 60_000));
+    return answer.waiting.reason === 'capacity'
+        ? `Computer use task queued: no computer is free yet (${minutes} min).`
+        : `Computer use task queued: ${answer.waiting.reason} (${minutes} min).`;
+}
 function secretsOf(secrets) {
     const entries = secrets && typeof secrets === 'object' && !Array.isArray(secrets) ? Object.entries(secrets) : [];
     if (entries.length < 1 || entries.length > 10)
@@ -80,9 +90,12 @@ export function createComputerUseTool(options) {
                 ...(allowedHosts ? { allowedHosts } : {}), ...(secrets ? { secrets } : {}),
             });
             await options.progress(0, 'Computer use task started.');
+            const queuedAt = now();
+            const maxQueueMs = options.maxQueueMs ?? DEFAULT_MAX_QUEUE_MS;
             let reported = now();
             let steps = 0;
             let cancelSent = false;
+            let queueExpired = false;
             let missed = 0;
             for (;;) {
                 if (!cancelSent && await options.cancelled()) {
@@ -100,6 +113,9 @@ export function createComputerUseTool(options) {
                     missed = 0;
                     const answer = check.body;
                     if (answer.status === 'done' || answer.status === 'failed') {
+                        if (queueExpired && answer.status === 'failed') {
+                            return { status: 'failed', summary: `No computer was free within ${Math.round(maxQueueMs / 60_000)} minutes; the task was cancelled before it started.`, finalUrl: null, downloads: [] };
+                        }
                         if (answer.status === 'done' && session !== undefined && answer.session)
                             await runtimeSecrets.put(session, JSON.stringify(answer.session), transport);
                         const downloads = answer.downloads ?? [];
@@ -114,9 +130,14 @@ export function createComputerUseTool(options) {
                         }
                         return { status: answer.status, summary: answer.summary ?? null, finalUrl: answer.final_url ?? null, downloads: downloads.map(({ name, size }) => ({ name, size })) };
                     }
+                    if (answer.status === 'queued' && !cancelSent && now() - queuedAt >= maxQueueMs) {
+                        await api.post('/tasks/cancel', { run_key: options.runKey });
+                        cancelSent = true;
+                        queueExpired = true;
+                    }
                     if (answer.steps > steps || now() - reported >= HEARTBEAT_MS) {
                         steps = Math.max(steps, answer.steps);
-                        await options.progress(Math.min(steps, 99), answer.last_step ? `Computer use step ${steps}: ${answer.last_step}` : `Computer use task ${answer.status}.`);
+                        await options.progress(Math.min(steps, 99), answer.last_step ? `Computer use step ${steps}: ${answer.last_step}` : queueNote(answer, now() - queuedAt));
                         reported = now();
                     }
                 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { McpCallRequest, McpCallResult, McpToolsOptions } from './mcp-tools.js';
-export type { McpCallRequest, McpCallResult, McpToolDescriptor, McpSelectedTool, McpToolsOptions } from './mcp-tools.js';
+export type { McpCallRequest, McpCallResult, McpToolDescriptor, McpSelectedTool, McpToolsOptions, McpAgentTool } 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';
@@ -2059,15 +2059,7 @@ 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;
-            };
-        }>>>;
+        tools: (connection: string, options: McpToolsOptions) => Promise<Record<string, import("./mcp-tools.js").McpAgentTool>>;
         execute: <R extends IntegrationRequest>(connection: string, request: R) => Promise<IntegrationResult<R>>;
         connect: (connection: string) => Promise<IntegrationConnectResult>;
         disconnect: (connection: string) => Promise<IntegrationDisconnectResult>;

package/dist/mcp-tools.d.ts

@@ -1,4 +1,3 @@
-import type { Tool } from 'ai';
 export interface McpToolDescriptor {
     name: string;
     description?: string;
@@ -40,6 +39,15 @@ export interface McpToolsOptions {
     tools: readonly string[];
     runId: string;
 }
+/** The schema object belongs to the optional AI SDK and carries its private brand.
+ * Keep that implementation type out of ordinary clients' declaration graph. */
+export interface McpAgentTool {
+    description?: string;
+    inputSchema: any;
+    execute(input: Record<string, unknown>, context: {
+        toolCallId: string;
+    }): Promise<McpCallResult['mcp']>;
+}
 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 declare function createMcpTools(connection: string, options: McpToolsOptions, execute: Execute): Promise<Record<string, McpAgentTool>>;
 export {};

package/package.json

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