@isomorph.ai/app-sdk 1.22.0 → 1.24.0

package/README.md

@@ -456,6 +456,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.
 
-(1.22.0; data plane ADR 0065)
+`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.24.0; data plane ADR 0065)

package/dist/aws.d.ts

@@ -11,3 +11,8 @@ 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>;

package/dist/aws.js

@@ -32,3 +32,20 @@ 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}` : ''})`);
+    }
+}

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.24.0",
   "type": "module",
   "repository": {
     "type": "git",