@isomorph.ai/app-sdk 1.22.0 → 1.25.0

package/README.md

@@ -370,6 +370,25 @@ try {
 
 App code declares exact HTTPS pages and named click/fill selectors reviewed for reads. Tools provide navigate, observe, control, scroll, screenshot and close. Observations are untrusted webpage content. One isolated page per run, one active run per process, 50 actions, five minutes, ten-second operations, bounded text/screenshots. Private destinations, undeclared navigation, downloads, popups, WebSockets, service workers and non-GET/HEAD requests are blocked. GET-only filtering cannot infer website business semantics: never declare URLs/controls that perform external writes. Chromium's sandbox remains enabled; unsupported sandbox environments fail clearly.
 
+## Computer use tool
+
+A job's agent can hand one browser task, writes included, to Harbour's computer use agent. Use it only in `jobs/*.ts`. Install the optional peer `ai`.
+
+```ts
+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 }.
+```
+
+- 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`.
+- 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`.
+- 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.
+
+(1.25.0; data plane ADR 0078)
+
 ## Running and rollout
 
 `isomorph dev` uses canned server-model fixtures. `dev --real` supplies an approved development connection to the action process. Hosted actions resolve their exact ACTIVE version key. The current V2 PLAN is published after LIVE; before key activation, an AI action fails and later actions retry. LIVE alone is not AI acceptance.
@@ -456,6 +475,10 @@ The action still has the 300 s action budget. (Unreleased)
 
 ## Running on Lambda
 
-On a serverless cell Harbour runs an app's server code as Lambda functions; nothing in the app changes. `ISOMORPH_GATEWAY_IDENTITY=sts-session` replaces `HARBOUR_WORKLOAD_TOKEN_FILE`: the runtime's bearer for the gateway is a one-hour session it gets by posting a presigned STS `GetCallerIdentity`, signed with the function's credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_REGION`), to `<gateway>/_harbour/internal/session`. A cluster runtime leaves it unset.
+On a serverless cell Harbour runs an app's server code as Lambda functions, from a `runtime.zip` Kit Build makes; nothing in the app changes. The Web Function starts `dist/lambda-entry.js` (the zip's `index.js` is `import "@isomorph.ai/app-sdk/dist/lambda-entry.js"`), which serves actions on the port in `AWS_LAMBDA_HTTP_ENDPOINT` and stops on SIGTERM. The Event Function's handler is `node_modules/@isomorph.ai/app-sdk/dist/lambda-events-entry.handler`: `{"job": "<name>"}` runs that job once, as `--run-job <name>` does, and SQS records work queued runs until none are left.
+
+`ISOMORPH_GATEWAY_IDENTITY=sts-session` replaces `HARBOUR_WORKLOAD_TOKEN_FILE`: the runtime's bearer for the gateway is a one-hour session it gets by posting a presigned STS `GetCallerIdentity`, signed with the function's credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_REGION`), to `<gateway>/_harbour/internal/session`. A cluster runtime leaves it unset.
+
+`ISOMORPH_JOBS_QUEUE_URL`: `isomorph.jobs.enqueue` writes the run, then sends one message to this SQS queue; the runtime never works the queue itself.
 
-(1.22.0; data plane ADR 0065)
+(1.24.0; data plane ADR 0065)

package/dist/aws.d.ts

@@ -11,3 +11,28 @@ export declare function awsEnvironment(env?: NodeJS.ProcessEnv): AwsEnvironment;
  * alone (ADR 0068), so a signature over any other header could never verify.
  */
 export declare function presignCallerIdentity(aws: AwsEnvironment, signingDate?: Date): Promise<string>;
+/** SendMessage to a queue, over the JSON protocol at the queue URL's own host. */
+export declare function sendQueueMessage(aws: AwsEnvironment, queueUrl: string, body: string, { fetch: fetcher, signingDate }?: {
+    fetch?: typeof fetch;
+    signingDate?: Date;
+}): Promise<void>;
+type Credentials = Omit<AwsEnvironment, 'region'>;
+/**
+ * The runtime role's credentials: the Lambda environment's, or on a cluster
+ * pod the ServiceAccount role's (IRSA: AWS_ROLE_ARN and the projected token
+ * in AWS_WEB_IDENTITY_TOKEN_FILE), exchanged with STS
+ * AssumeRoleWithWebIdentity and kept until five minutes before they expire.
+ */
+export declare function runtimeCredentials(env?: NodeJS.ProcessEnv, { fetch: fetcher, now }?: {
+    fetch?: typeof fetch;
+    now?: () => number;
+}): Promise<Credentials>;
+/** A JSON POST signed for `service` in `aws.region`, answered with its status and JSON body. */
+export declare function signedJsonPost(aws: AwsEnvironment, service: string, target: string, payload: unknown, { fetch: fetcher, signingDate }?: {
+    fetch?: typeof fetch;
+    signingDate?: Date;
+}): Promise<{
+    status: number;
+    body: unknown;
+}>;
+export {};

package/dist/aws.js

@@ -1,6 +1,8 @@
-// The AWS calls a serverless runtime makes with its function role, signed
-// here rather than through an AWS SDK client (ADR 0065). Credentials and the
-// region come from the Lambda environment on every call.
+// The AWS calls a runtime makes with its own role, signed here rather than
+// through an AWS SDK client (ADR 0065). On a serverless cell the credentials
+// and the region come from the Lambda environment on every call; on a cluster
+// pod, from the ServiceAccount's role (runtimeCredentials).
+import { readFile } from 'node:fs/promises';
 import { Sha256 } from '@aws-crypto/sha256-js';
 import { HttpRequest } from '@smithy/protocol-http';
 import { SignatureV4 } from '@smithy/signature-v4';
@@ -32,3 +34,60 @@ export async function presignCallerIdentity(aws, signingDate = new Date()) {
             query.set(key, value);
     return `https://${hostname}/?${query.toString()}`;
 }
+/** SendMessage to a queue, over the JSON protocol at the queue URL's own host. */
+export async function sendQueueMessage(aws, queueUrl, body, { fetch: fetcher = fetch, signingDate = new Date() } = {}) {
+    const url = new URL(queueUrl);
+    const payload = JSON.stringify({ QueueUrl: queueUrl, MessageBody: body });
+    const request = new HttpRequest({
+        method: 'POST', protocol: url.protocol, hostname: url.hostname, ...(url.port ? { port: Number(url.port) } : {}), path: '/',
+        headers: { host: url.host, 'content-type': 'application/x-amz-json-1.0', 'x-amz-target': 'AmazonSQS.SendMessage' },
+        body: payload,
+    });
+    // fetch sets Host itself, from the same URL.
+    const { host: _host, ...headers } = (await signer(aws, 'sqs').sign(request, { signingDate })).headers;
+    const response = await fetcher(`${url.protocol}//${url.host}/`, { method: 'POST', headers, body: payload, signal: AbortSignal.timeout(10_000) });
+    if (!response.ok) {
+        const answer = await response.json().catch(() => undefined);
+        throw new Error(`SQS refused the message (${response.status}${answer?.__type ? ` ${answer.__type}` : ''}${answer?.message ? `: ${answer.message}` : ''})`);
+    }
+}
+let webIdentity;
+/**
+ * The runtime role's credentials: the Lambda environment's, or on a cluster
+ * pod the ServiceAccount role's (IRSA: AWS_ROLE_ARN and the projected token
+ * in AWS_WEB_IDENTITY_TOKEN_FILE), exchanged with STS
+ * AssumeRoleWithWebIdentity and kept until five minutes before they expire.
+ */
+export async function runtimeCredentials(env = process.env, { fetch: fetcher = fetch, now = Date.now } = {}) {
+    if (env.AWS_ACCESS_KEY_ID && env.AWS_SECRET_ACCESS_KEY)
+        return { accessKeyId: env.AWS_ACCESS_KEY_ID, secretAccessKey: env.AWS_SECRET_ACCESS_KEY, ...(env.AWS_SESSION_TOKEN ? { sessionToken: env.AWS_SESSION_TOKEN } : {}) };
+    const roleArn = env.AWS_ROLE_ARN;
+    const tokenFile = env.AWS_WEB_IDENTITY_TOKEN_FILE;
+    if (!roleArn || !tokenFile)
+        throw new Error('the runtime has no AWS credentials (AWS_ACCESS_KEY_ID, or AWS_ROLE_ARN with AWS_WEB_IDENTITY_TOKEN_FILE)');
+    if (webIdentity?.roleArn === roleArn && webIdentity.expiresAt - now() > 5 * 60_000)
+        return webIdentity.credentials;
+    const region = env.AWS_REGION || env.AWS_DEFAULT_REGION || 'us-east-1';
+    // The token is read on each exchange: the kubelet rotates the file.
+    const body = new URLSearchParams({ Action: 'AssumeRoleWithWebIdentity', Version: '2011-06-15', RoleArn: roleArn, RoleSessionName: env.AWS_ROLE_SESSION_NAME || 'isomorph-runtime', WebIdentityToken: (await readFile(tokenFile, 'utf8')).trim() });
+    const response = await fetcher(`https://sts.${region}.amazonaws.com/`, { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: body.toString(), signal: AbortSignal.timeout(10_000) });
+    const answer = await response.text();
+    const field = (name) => answer.match(new RegExp(`<${name}>([^<]+)</${name}>`))?.[1];
+    const accessKeyId = field('AccessKeyId'), secretAccessKey = field('SecretAccessKey'), sessionToken = field('SessionToken'), expiration = Date.parse(field('Expiration') ?? '');
+    if (!response.ok || !accessKeyId || !secretAccessKey || !sessionToken || Number.isNaN(expiration))
+        throw new Error(`STS did not issue the runtime role's credentials (${response.status}${field('Code') ? ` ${field('Code')}` : ''})`);
+    webIdentity = { roleArn, credentials: { accessKeyId, secretAccessKey, sessionToken }, expiresAt: expiration };
+    return webIdentity.credentials;
+}
+/** A JSON POST signed for `service` in `aws.region`, answered with its status and JSON body. */
+export async function signedJsonPost(aws, service, target, payload, { fetch: fetcher = fetch, signingDate = new Date() } = {}) {
+    const url = new URL(target);
+    const body = JSON.stringify(payload);
+    const request = new HttpRequest({
+        method: 'POST', protocol: url.protocol, hostname: url.hostname, ...(url.port ? { port: Number(url.port) } : {}), path: url.pathname,
+        headers: { host: url.host, 'content-type': 'application/json' }, body,
+    });
+    const { host: _host, ...headers } = (await signer(aws, service).sign(request, { signingDate })).headers;
+    const response = await fetcher(url.href, { method: 'POST', headers, body, signal: AbortSignal.timeout(30_000) });
+    return { status: response.status, body: await response.json().catch(() => undefined) };
+}

package/dist/computer-use.d.ts

@@ -0,0 +1,220 @@
+export interface ComputerUseOptions {
+    /** 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. */
+    progress(percent: number, note?: string): Promise<void> | void;
+    /** The job's cancelled(): when true the tool cancels the task and waits until the CUA stops. */
+    cancelled(): Promise<boolean> | boolean;
+    env?: NodeJS.ProcessEnv;
+    fetch?: typeof fetch;
+    /** The pause between checks; the tests shorten it. */
+    pollIntervalMs?: number;
+    now?: () => number;
+}
+export interface ComputerUseResult {
+    status: 'done' | 'failed';
+    summary: string | null;
+}
+export declare function createComputerUseTool(options: ComputerUseOptions): ({
+    deferLoading?: boolean;
+    title?: string;
+    providerOptions?: import("@ai-sdk/provider-utils").ProviderOptions;
+    metadata?: import("@ai-sdk/provider").JSONObject;
+    inputSchema: import("ai").FlexibleSchema<{
+        task: string;
+    }>;
+    contextSchema?: import("ai").FlexibleSchema<import("@ai-sdk/provider-utils").Context> | undefined;
+    needsApproval?: boolean | import("@ai-sdk/provider-utils").ToolNeedsApprovalFunction<{
+        task: string;
+    }, NoInfer<import("@ai-sdk/provider-utils").Context>> | undefined;
+    onInputStart?: ((options: import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    onInputDelta?: ((options: {
+        inputTextDelta: string;
+    } & import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    onInputAvailable?: ((options: {
+        input: {
+            task: string;
+        };
+    } & import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    toModelOutput?: ((options: {
+        toolCallId: string;
+        input: {
+            task: string;
+        };
+        output: NoInfer<ComputerUseResult>;
+    }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
+} & {
+    outputSchema?: import("ai").FlexibleSchema<ComputerUseResult> | undefined;
+    execute: import("ai").ToolExecuteFunction<{
+        task: string;
+    }, ComputerUseResult, NoInfer<import("@ai-sdk/provider-utils").Context>>;
+} & {
+    description?: string | ((options: {
+        context: NoInfer<import("@ai-sdk/provider-utils").Context>;
+        experimental_sandbox?: import("ai").Experimental_SandboxSession;
+    }) => string) | undefined;
+    strict?: boolean;
+    inputExamples?: {
+        input: NoInfer<{
+            task: string;
+        }>;
+    }[] | undefined;
+    id?: never;
+    isProviderExecuted?: never;
+    args?: never;
+    supportsDeferredResults?: never;
+} & {
+    type?: undefined | "function";
+} & {
+    execute: import("ai").ToolExecuteFunction<{
+        task: string;
+    }, ComputerUseResult, NoInfer<import("@ai-sdk/provider-utils").Context>>;
+}) | ({
+    deferLoading?: boolean;
+    title?: string;
+    providerOptions?: import("@ai-sdk/provider-utils").ProviderOptions;
+    metadata?: import("@ai-sdk/provider").JSONObject;
+    inputSchema: import("ai").FlexibleSchema<{
+        task: string;
+    }>;
+    contextSchema?: import("ai").FlexibleSchema<import("@ai-sdk/provider-utils").Context> | undefined;
+    needsApproval?: boolean | import("@ai-sdk/provider-utils").ToolNeedsApprovalFunction<{
+        task: string;
+    }, NoInfer<import("@ai-sdk/provider-utils").Context>> | undefined;
+    onInputStart?: ((options: import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    onInputDelta?: ((options: {
+        inputTextDelta: string;
+    } & import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    onInputAvailable?: ((options: {
+        input: {
+            task: string;
+        };
+    } & import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    toModelOutput?: ((options: {
+        toolCallId: string;
+        input: {
+            task: string;
+        };
+        output: NoInfer<ComputerUseResult>;
+    }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
+} & {
+    outputSchema?: import("ai").FlexibleSchema<ComputerUseResult> | undefined;
+    execute: import("ai").ToolExecuteFunction<{
+        task: string;
+    }, ComputerUseResult, NoInfer<import("@ai-sdk/provider-utils").Context>>;
+} & {
+    description?: string | ((options: {
+        context: NoInfer<import("@ai-sdk/provider-utils").Context>;
+        experimental_sandbox?: import("ai").Experimental_SandboxSession;
+    }) => string) | undefined;
+    strict?: boolean;
+    inputExamples?: {
+        input: NoInfer<{
+            task: string;
+        }>;
+    }[] | undefined;
+    id?: never;
+    isProviderExecuted?: never;
+    args?: never;
+    supportsDeferredResults?: never;
+} & {
+    type: "dynamic";
+} & {
+    execute: import("ai").ToolExecuteFunction<{
+        task: string;
+    }, ComputerUseResult, NoInfer<import("@ai-sdk/provider-utils").Context>>;
+}) | ({
+    deferLoading?: boolean;
+    title?: string;
+    providerOptions?: import("@ai-sdk/provider-utils").ProviderOptions;
+    metadata?: import("@ai-sdk/provider").JSONObject;
+    inputSchema: import("ai").FlexibleSchema<{
+        task: string;
+    }>;
+    contextSchema?: import("ai").FlexibleSchema<import("@ai-sdk/provider-utils").Context> | undefined;
+    needsApproval?: boolean | import("@ai-sdk/provider-utils").ToolNeedsApprovalFunction<{
+        task: string;
+    }, NoInfer<import("@ai-sdk/provider-utils").Context>> | undefined;
+    onInputStart?: ((options: import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    onInputDelta?: ((options: {
+        inputTextDelta: string;
+    } & import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    onInputAvailable?: ((options: {
+        input: {
+            task: string;
+        };
+    } & import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    toModelOutput?: ((options: {
+        toolCallId: string;
+        input: {
+            task: string;
+        };
+        output: NoInfer<ComputerUseResult>;
+    }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
+} & {
+    outputSchema?: import("ai").FlexibleSchema<ComputerUseResult> | undefined;
+    execute: import("ai").ToolExecuteFunction<{
+        task: string;
+    }, ComputerUseResult, NoInfer<import("@ai-sdk/provider-utils").Context>>;
+} & {
+    type: "provider";
+    id: `${string}.${string}`;
+    args: Record<string, unknown>;
+    description?: never;
+    strict?: never;
+    inputExamples?: never;
+} & {
+    isProviderExecuted: false;
+    supportsDeferredResults?: never;
+} & {
+    execute: import("ai").ToolExecuteFunction<{
+        task: string;
+    }, ComputerUseResult, NoInfer<import("@ai-sdk/provider-utils").Context>>;
+}) | ({
+    deferLoading?: boolean;
+    title?: string;
+    providerOptions?: import("@ai-sdk/provider-utils").ProviderOptions;
+    metadata?: import("@ai-sdk/provider").JSONObject;
+    inputSchema: import("ai").FlexibleSchema<{
+        task: string;
+    }>;
+    contextSchema?: import("ai").FlexibleSchema<import("@ai-sdk/provider-utils").Context> | undefined;
+    needsApproval?: boolean | import("@ai-sdk/provider-utils").ToolNeedsApprovalFunction<{
+        task: string;
+    }, NoInfer<import("@ai-sdk/provider-utils").Context>> | undefined;
+    onInputStart?: ((options: import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    onInputDelta?: ((options: {
+        inputTextDelta: string;
+    } & import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    onInputAvailable?: ((options: {
+        input: {
+            task: string;
+        };
+    } & import("ai").ToolExecutionOptions<NoInfer<import("@ai-sdk/provider-utils").Context>>) => void | PromiseLike<void>) | undefined;
+    toModelOutput?: ((options: {
+        toolCallId: string;
+        input: {
+            task: string;
+        };
+        output: NoInfer<ComputerUseResult>;
+    }) => import("@ai-sdk/provider-utils").ToolResultOutput | PromiseLike<import("@ai-sdk/provider-utils").ToolResultOutput>) | undefined;
+} & {
+    outputSchema?: import("ai").FlexibleSchema<ComputerUseResult> | undefined;
+    execute: import("ai").ToolExecuteFunction<{
+        task: string;
+    }, ComputerUseResult, NoInfer<import("@ai-sdk/provider-utils").Context>>;
+} & {
+    type: "provider";
+    id: `${string}.${string}`;
+    args: Record<string, unknown>;
+    description?: never;
+    strict?: never;
+    inputExamples?: never;
+} & {
+    isProviderExecuted: true;
+    supportsDeferredResults?: boolean;
+} & {
+    execute: import("ai").ToolExecuteFunction<{
+        task: string;
+    }, ComputerUseResult, NoInfer<import("@ai-sdk/provider-utils").Context>>;
+});

package/dist/computer-use.js

@@ -0,0 +1,72 @@
+// The computer use tool: hands one browser task to Harbour's computer use
+// 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).
+import { setTimeout as sleep } from 'node:timers/promises';
+import { jsonSchema, tool } from 'ai';
+import { runtimeCredentials, signedJsonPost } from './aws.js';
+const HEARTBEAT_MS = 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;
+export function createComputerUseTool(options) {
+    const env = options.env ?? process.env;
+    const base = env.ISOMORPH_COMPUTER_USE_URL?.replace(/\/+$/, '');
+    if (!base)
+        throw new Error('This app has no computer use API (ISOMORPH_COMPUTER_USE_URL is not set).');
+    if (!options.runKey)
+        throw new Error('createComputerUseTool needs the job run as runKey.');
+    const region = env.ISOMORPH_COMPUTER_USE_REGION || 'us-east-1';
+    const now = options.now ?? Date.now;
+    const transport = options.fetch ? { fetch: options.fetch } : {};
+    const call = async (path, body) => signedJsonPost({ ...await runtimeCredentials(env, transport), region }, 'execute-api', `${base}${path}`, body, transport);
+    const refused = (path, status, body) => {
+        const error = body?.error;
+        return new Error(`The computer use API refused ${path} (${status}${typeof error === 'string' ? `: ${error}` : ''}).`);
+    };
+    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.',
+        inputSchema: jsonSchema({ type: 'object', properties: { task: { type: 'string', minLength: 1 } }, required: ['task'], additionalProperties: false }),
+        execute: async ({ task }) => {
+            const started = await call('/tasks', { run_key: options.runKey, task });
+            if (started.status !== 200)
+                throw refused('/tasks', started.status, started.body);
+            await options.progress(0, 'Computer use task started.');
+            let reported = now();
+            let steps = 0;
+            let cancelSent = false;
+            let missed = 0;
+            for (;;) {
+                if (!cancelSent && await options.cancelled()) {
+                    const cancel = await call('/tasks/cancel', { run_key: options.runKey });
+                    if (cancel.status !== 200)
+                        throw refused('/tasks/cancel', cancel.status, cancel.body);
+                    cancelSent = true;
+                }
+                let check;
+                try {
+                    check = await call('/tasks/check', { run_key: options.runKey });
+                }
+                catch {
+                    check = undefined;
+                }
+                if (check?.status === 200) {
+                    missed = 0;
+                    const answer = check.body;
+                    if (answer.status === 'done' || answer.status === 'failed')
+                        return { status: answer.status, summary: answer.summary ?? null };
+                    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}.`);
+                        reported = now();
+                    }
+                }
+                else if (check && check.status !== 429 && check.status < 500) {
+                    throw refused('/tasks/check', check.status, check.body);
+                }
+                else if (++missed > MAX_MISSED_CHECKS) {
+                    throw new Error('The computer use API stopped answering.');
+                }
+                await sleep(options.pollIntervalMs ?? 5_000);
+            }
+        },
+    });
+}

package/dist/lambda-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lambda-entry.js

@@ -0,0 +1,10 @@
+// The kit runtime as a Lambda Web Function (ADR 0065). The app's runtime.zip
+// has a one-line index.js, `import "@isomorph.ai/app-sdk/dist/lambda-entry.js"`,
+// and the function starts it: the runtime serves on the port Lambda names in
+// AWS_LAMBDA_HTTP_ENDPOINT (host:port) and stops on SIGTERM, as it does in a pod.
+import { main } from './runtime.js';
+const endpoint = process.env.AWS_LAMBDA_HTTP_ENDPOINT;
+if (endpoint && !process.env.PORT)
+    process.env.PORT = endpoint.slice(endpoint.lastIndexOf(':') + 1);
+// Lambda's own arguments are not the runtime's: this entry always serves.
+await main([]);

package/dist/lambda-events-entry.d.ts

@@ -0,0 +1 @@
+export declare function handler(event: unknown): Promise<void>;

package/dist/lambda-events-entry.js

@@ -0,0 +1,30 @@
+// The kit runtime as the cell's Event Function (ADR 0065): the same runtime.zip
+// with the handler node_modules/@isomorph.ai/app-sdk/dist/lambda-events-entry.handler.
+// One function per app serves both kinds of event:
+//
+//   {"job": "<name>"}   a Scheduler schedule's input: one scheduled run of
+//                       jobs/<name>.ts, exactly as `--run-job <name>` runs it
+//   {"Records": [...]}  SQS messages from an enqueue: the queue is worked
+//                       until a pass finds nothing
+//
+// An invocation that did not do its work throws, so Lambda counts the error
+// and SQS delivers the message again.
+import { register } from 'node:module';
+import { processOptions, Runtime } from './runtime.js';
+register('./runtime-hooks.js', import.meta.url);
+let runtime;
+function eventRuntime() {
+    runtime ??= new Runtime(processOptions());
+    return runtime;
+}
+export async function handler(event) {
+    const { job, Records: records } = (event && typeof event === 'object' ? event : {});
+    if (typeof job === 'string' && job) {
+        if (!(await eventRuntime().runJobOnce(job)))
+            throw new Error(`jobs/${job}.ts did not run to completion; the log above names why`);
+        return;
+    }
+    if (Array.isArray(records))
+        return eventRuntime().drainQueue();
+    throw new Error('the event is neither a scheduled job ({"job": "<name>"}) nor queue messages');
+}

package/dist/runtime.d.ts

@@ -87,6 +87,8 @@ export interface RuntimeOptions {
     localGateway?: Omit<LocalGatewayOptions, 'log'>;
     /** 'sts-session' when the workload's bearer is a gateway session for the function role (ISOMORPH_GATEWAY_IDENTITY). */
     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;
 }
 export declare class Runtime {
     private readonly options;
@@ -104,8 +106,18 @@ export declare class Runtime {
     readonly server: import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
     constructor(options: RuntimeOptions);
     start(): Promise<number>;
-    /** Whether this process works the queue at all: not the gate, a runs table, an app with jobs, a gateway to reach. */
+    /** Whether this process works the queue at all: not the gate, no queue elsewhere, and there is a queue. */
     private worksQueue;
+    /** A runs table, an app with jobs, a gateway to reach. */
+    private hasQueue;
+    /**
+     * The Event Function's answer to a queue message: wait for the data path,
+     * then work passes until one finds nothing. A message stands for "the queue
+     * has work", not for its run: a pass claims the oldest run, and a failed
+     * run's retry needs a pass after it. A pass that throws fails the
+     * invocation, so SQS delivers the message again.
+     */
+    drainQueue(): Promise<void>;
     /**
      * Starts the queue loop unless it is already live. The first pass runs at
      * once; each further pass follows QUEUE_POLL_MS after one that found work
@@ -146,3 +158,7 @@ export declare class Runtime {
 export declare function optionsFromEnvironment(env?: NodeJS.ProcessEnv): RuntimeOptions;
 /** The job named by `--run-job <name>` or `--run-job=<name>`; undefined when the runtime is a server. */
 export declare function runJobFromArguments(argv?: string[]): string | undefined;
+/** The options of a runtime process; the app's own SDK calls go to the gateway the runtime was given. */
+export declare function processOptions(): RuntimeOptions;
+/** The runtime as a process: this module's main, and the Web Function's (lambda-entry.ts). */
+export declare function main(argv?: string[]): Promise<void>;

package/dist/runtime.js

@@ -53,6 +53,9 @@
 //                                 the workload's bearer is a gateway session the
 //                                 runtime obtains with its function role (a
 //                                 serverless cell, ADR 0065), not a token file
+//   ISOMORPH_JOBS_QUEUE_URL       an enqueue sends the run to this SQS queue and
+//                                 the queue loop never runs here: the cell's
+//                                 Event Function works it (lambda-events-entry.ts)
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { createServer } from 'node:http';
 import { readFile, readdir, stat } from 'node:fs/promises';
@@ -82,8 +85,9 @@ const LEASE_MS = 5 * 60_000;
 const QUEUE_POLL_MS = 2_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; a scheduled run may take
-// up to 900 s on Lambda and takes one in the last 15.
+// takes a new one in the session's last 10 minutes; an Event Function
+// invocation (a scheduled run, a queue drain) may take up to 900 s and takes
+// one in the last 15.
 const SESSION_MIN_VALIDITY_MS = 10 * 60_000;
 const JOB_SESSION_MIN_VALIDITY_MS = 15 * 60_000;
 const DEFAULT_MAX_ATTEMPTS = 3;
@@ -293,9 +297,32 @@ export class Runtime {
         this.wakeQueue();
         return port;
     }
-    /** Whether this process works the queue at all: not the gate, a runs table, an app with jobs, a gateway to reach. */
+    /** Whether this process works the queue at all: not the gate, no queue elsewhere, and there is a queue. */
     worksQueue() {
-        return this.options.mode !== 'gate' && this.options.jobRuns !== false && this.inventory.jobs.length > 0 && Boolean(this.options.gatewayUrl);
+        return this.options.mode !== 'gate' && !this.options.queueUrl && this.hasQueue();
+    }
+    /** A runs table, an app with jobs, a gateway to reach. */
+    hasQueue() {
+        return this.options.jobRuns !== false && this.inventory.jobs.length > 0 && Boolean(this.options.gatewayUrl);
+    }
+    /**
+     * The Event Function's answer to a queue message: wait for the data path,
+     * then work passes until one finds nothing. A message stands for "the queue
+     * has work", not for its run: a pass claims the oldest run, and a failed
+     * run's retry needs a pass after it. A pass that throws fails the
+     * invocation, so SQS delivers the message again.
+     */
+    async drainQueue() {
+        this.inventory = await discover(this.options.root);
+        await this.refreshToken(JOB_SESSION_MIN_VALIDITY_MS);
+        if (!this.hasQueue()) {
+            this.log('a queue message arrived but this app has no runs to work');
+            return;
+        }
+        if (!(await this.awaitDataPath()))
+            throw new Error('the data path did not answer; the message is retried');
+        while (!this.stopped && await this.work())
+            await new Promise((wake) => setTimeout(wake, this.options.queuePollMs ?? QUEUE_POLL_MS));
     }
     /**
      * Starts the queue loop unless it is already live. The first pass runs at
@@ -662,7 +689,13 @@ export class Runtime {
                 if (!owner)
                     throw new IsomorphError('AUTH_REQUIRED', 'a run is started by a signed-in person', undefined, undefined, 401);
                 const queued = await this.runs.enqueue(job, body.input, owner);
-                this.wakeQueue();
+                // Awaited before the enqueue answers: a Web Function may be frozen as soon as it has replied.
+                if (this.options.queueUrl) {
+                    const { awsEnvironment, sendQueueMessage } = await import('./aws.js');
+                    await sendQueueMessage(awsEnvironment(), this.options.queueUrl, JSON.stringify({ runId: queued.id }));
+                }
+                else
+                    this.wakeQueue();
                 return queued;
             }
             case GET_RUN_ACTION: {
@@ -692,6 +725,7 @@ export function optionsFromEnvironment(env = process.env) {
         tokenFile: env.HARBOUR_WORKLOAD_TOKEN_FILE || undefined,
         jobRuns: env.ISOMORPH_JOB_RUNS !== 'none',
         ...(env.ISOMORPH_GATEWAY_IDENTITY === 'sts-session' ? { gatewayIdentity: 'sts-session' } : {}),
+        ...(env.ISOMORPH_JOBS_QUEUE_URL ? { queueUrl: env.ISOMORPH_JOBS_QUEUE_URL } : {}),
         ...(env.ISOMORPH_LOCAL_GATEWAY_BINARY && env.ISOMORPH_LOCAL_GATEWAY_CONFIG_FILE
             ? { localGateway: { binary: env.ISOMORPH_LOCAL_GATEWAY_BINARY, configFile: env.ISOMORPH_LOCAL_GATEWAY_CONFIG_FILE, url: (env.ISOMORPH_LOCAL_GATEWAY_URL || '').replace(/\/$/, '') } }
             : {}),
@@ -708,33 +742,26 @@ export function runJobFromArguments(argv = process.argv.slice(2)) {
     }
     return undefined;
 }
-// Node resolves this module's URL through any symlink in its path, while
-// process.argv[1] is the path the starter typed. On macOS /tmp and /var are
-// symlinks, so a gate or `isomorph dev` started from an app root under them
-// handed a path whose URL never matched, and the runtime loaded as a library
-// and exited 0 without a word (the gate reported "exited before it
-// answered", 2026-10-06). Compare the real path, as Node did.
-const entryPath = process.argv[1] ? (() => { try {
-    return realpathSync(process.argv[1]);
+/** The options of a runtime process; the app's own SDK calls go to the gateway the runtime was given. */
+export function processOptions() {
+    const options = optionsFromEnvironment();
+    if (options.gatewayUrl && !process.env.ISOMORPH_GATEWAY_URL)
+        process.env.ISOMORPH_GATEWAY_URL = options.gatewayUrl;
+    return options;
 }
-catch {
-    return process.argv[1];
-} })() : '';
-const entry = entryPath ? pathToFileURL(entryPath).href : '';
-if (import.meta.url === entry) {
+/** The runtime as a process: this module's main, and the Web Function's (lambda-entry.ts). */
+export async function main(argv = process.argv.slice(2)) {
     // Extensionless relative imports in the app's server code resolve to
     // their .ts files (runtime-hooks.ts); registered before any app module
     // is imported.
     register('./runtime-hooks.js', import.meta.url);
-    const options = optionsFromEnvironment();
-    if (options.gatewayUrl && !process.env.ISOMORPH_GATEWAY_URL)
-        process.env.ISOMORPH_GATEWAY_URL = options.gatewayUrl;
+    const options = processOptions();
     if (!(await stat(options.root).catch(() => undefined))?.isDirectory()) {
         console.error(`isomorph runtime: ${options.root} is not a directory`);
         process.exit(2);
     }
     const runtime = new Runtime(options);
-    const job = runJobFromArguments();
+    const job = runJobFromArguments(argv);
     if (job !== undefined) {
         if (!job) {
             console.error('isomorph runtime: --run-job needs a job name');
@@ -747,3 +774,18 @@ if (import.meta.url === entry) {
     process.on('SIGINT', shutdown);
     await runtime.start();
 }
+// Node resolves this module's URL through any symlink in its path, while
+// process.argv[1] is the path the starter typed. On macOS /tmp and /var are
+// symlinks, so a gate or `isomorph dev` started from an app root under them
+// handed a path whose URL never matched, and the runtime loaded as a library
+// and exited 0 without a word (the gate reported "exited before it
+// answered", 2026-10-06). Compare the real path, as Node did.
+const entryPath = process.argv[1] ? (() => { try {
+    return realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })() : '';
+const entry = entryPath ? pathToFileURL(entryPath).href : '';
+if (import.meta.url === entry)
+    await main();

package/package.json

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