@isomorph.ai/app-sdk 1.46.0 → 2.0.1

package/README.md

@@ -407,7 +407,7 @@ const computerUse = createComputerUseTool({ runKey: ctx.runId ?? `my-job/${ctx.s
 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.
+- `session`: the name of an existing browser-session runtime secret. 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, 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) the browser may use; without it a task with no sign-in may use any website. A task with `secrets` and no `session` needs it: the websites the secrets may be typed into. A saved sign-in carries its own.
@@ -451,7 +451,7 @@ Keep that table protected by the app's user row rules. A trusted action must sti
 
 - `requestTakeover(reason, requiredInput?)` requests a pause; `requiredInput` is `human` (default) or `login`. It answers the pause (`taskId`, `pauseId`, `status`, `reason`, `requiredInput`; the same pause again if one exists). Poll `check()` until `waiting_for_input` gives the pause plus the optional login result; while the task is not waiting, `check()` answers its progress (`status`, `steps`, `lastStep`, `summary`, `finalUrl`, `waiting`, `message`).
 - `view(pauseId)` returns `{status:'ready', screenshot, url}`; while the task is still pausing, or once it resumed, the API answers 409 and the call throws. Reuse the existing sign-in screenshot UI: display the base64 PNG as an image, map clicks to image pixels, and forward keyboard/scroll events through app actions. Viewing does not itself resume the agent.
-- `input(pauseId, action)` sends the same `SignInAction` click/type/key/scroll commands used by `sendSignInInput` (`typeText` may be up to 4096 characters here) and answers what the computer did. The CUA accepts human input only while the task is paused; it blocks the helper and main agent from acting at the same time.
+- `input(pauseId, action)` sends `ComputerUseInputAction` click/type/key/scroll commands (`typeText` may be up to 4096 characters here) and answers what the computer did. The CUA accepts human input only while the task is paused; it blocks the helper and main agent from acting at the same time.
 - `completeLogin(pauseId, {allowedHosts, username, password})`, or `completeLogin(pauseId, {otp})`, queues the separate browser-action-only login agent on this computer. **Call only from private server code, never expose this method or credentials as model tool inputs, prompts, progress, logs or job input/results.** Poll `check()` for `login.status: success | needs_input | human_help_needed`, with `input:'otp'` when another code is needed, `reason` (`unverified_success`, `helper_gave_up`, `second_code_requested`, `helper_error:<type>`) when a person is needed, and the helper's short `evidence` (never a private value). Helper success leaves the main agent paused.
 - `resume(pauseId)` explicitly resumes and answers the pause with `status: 'resume_queued'`; it does not wait for completion. On Continue, call this from the authorized app action, then enqueue the app's continuation job. That job creates `createComputerUseTool({...jobOptions, runKey: originalRunKey, attach:true})`: it polls the same task without sending `/tasks` again. Keep the original saved-session and download options if needed. Stale/duplicate resumes fail with 409; do not silently retry with a new pause ID. If enqueue fails, retry attaching to the already resumed task, not another resume.
 - `cancel()` stops the task, including while waiting.
@@ -475,32 +475,16 @@ const answer = await signInWithOtp(computer, input.pauseId, { allowedHosts: ['ne
 - `readOtp(source, since)` reads a code on its own, for a page that asks for one outside a login.
 - The connection needs the app's grant for `phone.sms.list`, or `gmail.thread.list` + `gmail.message.read` (Outlook: `outlook.message.list` + `outlook.message.read`), and the portal account must be registered to that number or mailbox.
 
-`getSavedLogin(accountRef, website)` still returns `{status:'unavailable'}`; governance saved-login storage is not part of the SDK. These task helpers require the matching CUA handoff release; existing new-computer sign-in helpers below remain separate.
+`getSavedLogin(accountRef, website)` still returns `{status:'unavailable'}`; governance saved-login storage is not part of the SDK. These task helpers require the matching CUA handoff release; separate sign-in computer helpers are removed.
 
-## Browser sign-in for computer use
+## Removed separate sign-in computers
 
-A person signs in to a website once on a short-lived computer the app shows as screenshots; the app keeps the browser session as a runtime secret and passes its name to later computer use tasks as `session`. Each call is short, so these run from actions as well as jobs.
-
-```ts
-import { startSignIn, showSignIn, sendSignInInput, finishSignIn, cancelSignIn } from '@isomorph.ai/app-sdk/dist/computer-use-sign-in.js';
-// actions/connect-start.ts
-const handle = await startSignIn({ allowedHosts: ['vendorcentral.amazon.com'] });
-// actions/connect-page.ts: poll until ready, then show the screenshot
-const page = await showSignIn(handle); // { status: 'starting' } or { status: 'ready', screenshot, url }
-// actions/connect-input.ts: what the person did on the screenshot
-await sendSignInInput(handle, { op: 'click', x: 640, y: 400 });
-// actions/connect-finish.ts: once the person is signed in
-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. 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.
-- `cancelSignIn` stops the computer and keeps nothing.
-- Deleting the sign-in is `runtimeSecrets.delete(name)`. The app decides whose sign-in it is, when it has expired and when to delete it.
-
-(1.36.0; data plane ADR 0090)
+SDK 2.0 removes the separate sign-in module. The matching CUA release removes `/computers/*` API routes.
+Start a computer-use task. When it returns `waiting_for_input`, use the task
+handoff operations above. Pass private login input through `completeLogin`,
+or use `view` and `input` for human help. Explicitly resume the same task.
+Existing apps that imported the removed module must migrate; there is no alias
+that starts another computer. Existing saved-session input remains supported.
 
 ## Runtime secrets
 

package/dist/computer-use-handoff.d.ts

@@ -1,5 +1,18 @@
 import { type ComputerUseTransport } from './computer-use-api.js';
-import type { SignInAction } from './computer-use-sign-in.js';
+export type ComputerUseInputAction = {
+    op: 'click';
+    x: number;
+    y: number;
+} | {
+    op: 'typeText';
+    value: string;
+} | {
+    op: 'pressKey';
+    key: string;
+} | {
+    op: 'scroll';
+    direction: 'up' | 'down';
+};
 export interface ComputerUseMessage {
     type: 'progress' | 'handoff';
     text: string;
@@ -77,7 +90,7 @@ export interface ComputerUseHandoffOptions extends ComputerUseTransport {
 export declare function createComputerUseHandoff(options: ComputerUseHandoffOptions): {
     requestTakeover(reason: string, requiredInput?: "login" | "human"): Promise<ComputerUsePause>;
     view(pauseId: string): Promise<ComputerUsePage>;
-    input(pauseId: string, action: SignInAction): Promise<ComputerUseInputResult>;
+    input(pauseId: string, action: ComputerUseInputAction): Promise<ComputerUseInputResult>;
     completeLogin(pauseId: string, input: ComputerUseLoginInput): Promise<{
         status: "login_queued";
     }>;

package/dist/computer-use.d.ts

@@ -48,7 +48,7 @@ export type ComputerUseSecrets = Readonly<Record<string, string>>;
  */
 export type ComputerUseSignIn = {
     /**
-     * The runtime secret a sign-in was saved under (finishSignIn's `saveAs`): the task starts signed in,
+     * An existing browser-session runtime secret: the task starts signed in,
      * and the refreshed session is saved back to it when the task is done. Never supplied by the model.
      */
     session: string;

package/dist/runtime.d.ts

@@ -100,6 +100,8 @@ export interface RuntimeOptions {
     gatewayIdentity?: 'sts-session';
     /** The SQS queue an enqueue sends its run to (ISOMORPH_JOBS_QUEUE_URL); the queue loop is off when set. */
     queueUrl?: string;
+    /** How long a refused AI binding is remembered before the next handler asks the gateway again. */
+    aiRetryMs?: number;
 }
 export declare class Runtime {
     private readonly options;
@@ -109,6 +111,7 @@ export declare class Runtime {
     private readonly timers;
     private stopped;
     private aiBinding;
+    private aiRefusedUntil;
     private queueWorkers;
     private queueWake;
     private claimTail;
@@ -151,6 +154,14 @@ export declare class Runtime {
     private awaitDataPath;
     stop(): Promise<void>;
     private every;
+    /**
+     * Puts this version's AI binding in the environment before a handler runs;
+     * app code reads OPENAI_BASE_URL and OPENAI_API_KEY itself, so the fetch
+     * cannot wait for the first AI call. A binding the gateway refuses (a
+     * capability the company has no route for, a version it has not finished)
+     * does not stop the handler: the refusal is logged and remembered for
+     * aiRetryMs, and only the handler's AI calls fail (ADR 0096).
+     */
     private prepareAI;
     private refreshToken;
     private scheduleTick;

package/dist/runtime.js

@@ -87,6 +87,7 @@ const MAX_BODY_BYTES = 1 << 20;
 const LEASE_MS = 5 * 60_000;
 const QUEUE_WORKERS = 2;
 const QUEUE_POLL_MS = 2_000;
+const AI_RETRY_MS = 30_000;
 const TOKEN_REFRESH_MS = 60_000;
 // A gateway session lasts an hour. An action runs at most 300 s, so a request
 // takes a new one in the session's last 10 minutes; an Event Function
@@ -318,6 +319,7 @@ export class Runtime {
     timers = [];
     stopped = false;
     aiBinding;
+    aiRefusedUntil = 0;
     queueWorkers = 0;
     queueWake = 0;
     claimTail = Promise.resolve();
@@ -510,9 +512,17 @@ export class Runtime {
         };
         this.timers.push(setTimeout(loop, ms));
     }
+    /**
+     * Puts this version's AI binding in the environment before a handler runs;
+     * app code reads OPENAI_BASE_URL and OPENAI_API_KEY itself, so the fetch
+     * cannot wait for the first AI call. A binding the gateway refuses (a
+     * capability the company has no route for, a version it has not finished)
+     * does not stop the handler: the refusal is logged and remembered for
+     * aiRetryMs, and only the handler's AI calls fail (ADR 0096).
+     */
     async prepareAI() {
         const versionId = process.env.ISOMORPH_AI_VERSION_ID;
-        if (!versionId)
+        if (!versionId || Date.now() < this.aiRefusedUntil)
             return;
         this.aiBinding ??= (async () => {
             const token = process.env.ISOMORPH_WORKLOAD_TOKEN;
@@ -520,7 +530,7 @@ export class Runtime {
                 throw new Error('AI workload identity is unavailable.');
             const response = await fetch(`${this.options.gatewayUrl}/_harbour/internal/ai/connection`, { method: 'POST', headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' }, body: JSON.stringify({ versionId }), signal: AbortSignal.timeout(15_000) });
             if (!response.ok)
-                throw new Error('This app version has no active AI connection yet.');
+                throw new Error(`the gateway answered ${response.status} ${(await response.text()).slice(0, 200)}`);
             const result = await response.json();
             const binding = result.data;
             if (!binding?.key || !binding.gatewayBaseUrl || new URL(binding.gatewayBaseUrl).protocol !== 'https:')
@@ -533,7 +543,11 @@ export class Runtime {
                 process.env.ISOMORPH_AI_IMAGE_MODEL_ALIAS = binding.modelAliases.image;
             if (binding.modelAliases?.document)
                 process.env.ISOMORPH_AI_DOCUMENT_MODEL_ALIAS = binding.modelAliases.document;
-        })().catch(error => { this.aiBinding = undefined; throw error; });
+        })().catch((error) => {
+            this.aiBinding = undefined;
+            this.aiRefusedUntil = Date.now() + (this.options.aiRetryMs ?? AI_RETRY_MS);
+            this.log(`AI is not available to this app version (${versionId}): ${error instanceof Error ? error.message : String(error)}; its AI calls fail until the binding is`);
+        });
         await this.aiBinding;
     }
     async refreshToken(minValidityMs = SESSION_MIN_VALIDITY_MS) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isomorph.ai/app-sdk",
-  "version": "1.46.0",
+  "version": "2.0.1",
   "type": "module",
   "repository": {
     "type": "git",
@@ -16,7 +16,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\" && tsc -p tsconfig.json",
     "test": "npm run build && node --test test/*.test.mjs"
   },
   "devDependencies": {

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

@@ -1,42 +0,0 @@
-import { type ComputerUseTransport } from './computer-use-api.js';
-/** What the person did on the screenshot: the sign-in computer's input actions. */
-export type SignInAction = {
-    op: 'click';
-    x: number;
-    y: number;
-} | {
-    op: 'typeText';
-    value: string;
-} | {
-    op: 'pressKey';
-    key: string;
-} | {
-    op: 'scroll';
-    direction: 'up' | 'down';
-};
-/** The computer's screen: `starting` until its browser is up, then a base64 PNG and the page's address. */
-export type SignInPage = {
-    status: 'starting';
-} | {
-    status: 'ready';
-    screenshot: string;
-    url: string;
-};
-/**
- * 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>;
-/** Saves the signed-in browser session as the runtime secret `saveAs`, stops the computer and returns the page it was on. */
-export declare function finishSignIn(handle: string, { saveAs, ...transport }: {
-    saveAs: string;
-} & ComputerUseTransport): Promise<{
-    url: string;
-}>;
-/** Stops the computer and keeps nothing. */
-export declare function cancelSignIn(handle: string, transport?: ComputerUseTransport): Promise<void>;

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

@@ -1,59 +0,0 @@
-// Browser sign-in for computer use (data plane ADR 0090): a person signs in
-// to a website on a short-lived computer the app shows as screenshots, and the
-// app saves the browser session as one of its runtime secrets for later
-// computer use tasks. Each call is short, so these run in actions as well as
-// 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 {
-        computer = JSON.parse(Buffer.from(String(handle), 'base64url').toString('utf8'));
-    }
-    catch {
-        computer = undefined;
-    }
-    if (typeof computer?.computerId !== 'string' || typeof computer.endpoint !== 'string')
-        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. 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, ...(startUrl === undefined ? {} : { startUrl: startUrlOf(startUrl, hosts) }) });
-    return Buffer.from(JSON.stringify({ computerId, endpoint })).toString('base64url');
-}
-export async function showSignIn(handle, transport = {}) {
-    return computerUseApi(transport).post('/computers/page', computerOf(handle));
-}
-export async function sendSignInInput(handle, action, transport = {}) {
-    await computerUseApi(transport).post('/computers/input', { ...computerOf(handle), action });
-}
-/** Saves the signed-in browser session as the runtime secret `saveAs`, stops the computer and returns the page it was on. */
-export async function finishSignIn(handle, { saveAs, ...transport }) {
-    const computer = computerOf(handle);
-    runtimeSecretLocation(saveAs, transport.env);
-    const { session, url } = await computerUseApi(transport).post('/computers/finish', computer);
-    await runtimeSecrets.put(saveAs, JSON.stringify(session), transport);
-    return { url };
-}
-/** Stops the computer and keeps nothing. */
-export async function cancelSignIn(handle, transport = {}) {
-    await computerUseApi(transport).post('/computers/stop', computerOf(handle));
-}