@isomorph.ai/app-sdk 1.21.1 → 1.24.0

package/README.md

@@ -453,3 +453,13 @@ await isomorph.actions.invoke('research', input, { onProgress: (step) => setStep
 Without `onProgress` the call is unchanged and `ctx.progress` does nothing. At
 most 256 steps of up to 1 KiB each reach the page; further steps are dropped.
 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, 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.24.0; data plane ADR 0065)

package/dist/aws.d.ts

@@ -0,0 +1,18 @@
+export interface AwsEnvironment {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+    region: string;
+}
+export declare function awsEnvironment(env?: NodeJS.ProcessEnv): AwsEnvironment;
+/**
+ * A presigned GET of STS GetCallerIdentity on the region's dual-stack
+ * endpoint. Host is the only signed header: the gateway forwards the query
+ * 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

@@ -0,0 +1,51 @@
+// 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.
+import { Sha256 } from '@aws-crypto/sha256-js';
+import { HttpRequest } from '@smithy/protocol-http';
+import { SignatureV4 } from '@smithy/signature-v4';
+export function awsEnvironment(env = process.env) {
+    const accessKeyId = env.AWS_ACCESS_KEY_ID;
+    const secretAccessKey = env.AWS_SECRET_ACCESS_KEY;
+    const region = env.AWS_REGION || env.AWS_DEFAULT_REGION;
+    if (!accessKeyId || !secretAccessKey)
+        throw new Error('the function has no AWS credentials in its environment (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)');
+    if (!region)
+        throw new Error('the function has no AWS region in its environment (AWS_REGION)');
+    return { accessKeyId, secretAccessKey, ...(env.AWS_SESSION_TOKEN ? { sessionToken: env.AWS_SESSION_TOKEN } : {}), region };
+}
+function signer(aws, service) {
+    return new SignatureV4({ service, region: aws.region, sha256: Sha256, credentials: { accessKeyId: aws.accessKeyId, secretAccessKey: aws.secretAccessKey, ...(aws.sessionToken ? { sessionToken: aws.sessionToken } : {}) } });
+}
+/**
+ * A presigned GET of STS GetCallerIdentity on the region's dual-stack
+ * endpoint. Host is the only signed header: the gateway forwards the query
+ * alone (ADR 0068), so a signature over any other header could never verify.
+ */
+export async function presignCallerIdentity(aws, signingDate = new Date()) {
+    const hostname = `sts.${aws.region}.api.aws`;
+    const request = new HttpRequest({ method: 'GET', protocol: 'https:', hostname, path: '/', query: { Action: 'GetCallerIdentity', Version: '2011-06-15' }, headers: { host: hostname } });
+    const signed = await signer(aws, 'sts').presign(request, { expiresIn: 300, signingDate });
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(signed.query ?? {}))
+        if (typeof value === 'string')
+            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/gateway-session.d.ts

@@ -0,0 +1,22 @@
+export declare const SESSION_PATH = "/_harbour/internal/session";
+export interface GatewaySessionOptions {
+    gatewayUrl: string;
+    env?: NodeJS.ProcessEnv;
+    fetch?: typeof fetch;
+    /** The pauses between attempts the gateway or STS did not answer; the tests shorten them. */
+    retryDelaysMs?: number[];
+    now?: () => number;
+}
+export declare class GatewaySession {
+    private readonly options;
+    private current;
+    private pending;
+    constructor(options: GatewaySessionOptions);
+    /**
+     * The cached token while it stays valid for at least `minValidityMs`, else a
+     * new one. Concurrent callers share one exchange.
+     */
+    token(minValidityMs: number): Promise<string>;
+    private now;
+    private exchange;
+}

package/dist/gateway-session.js

@@ -0,0 +1,65 @@
+// The runtime's gateway identity on a serverless cell, where there is no
+// projected ServiceAccount token to read (ISOMORPH_GATEWAY_IDENTITY=sts-session,
+// ADR 0065). The runtime proves its function role with a presigned STS
+// GetCallerIdentity and the gateway answers with a one-hour bearer for the app
+// whose declaration names that role (the gateway's ADR 0068).
+import { setTimeout as sleep } from 'node:timers/promises';
+import { awsEnvironment, presignCallerIdentity } from './aws.js';
+export const SESSION_PATH = '/_harbour/internal/session';
+// The gateway answers 503 when STS did not, with no Retry-After; an ALB in
+// front answers 502 or 504 while the gateway task restarts.
+const RETRY_STATUSES = new Set([502, 503, 504]);
+const RETRY_DELAYS_MS = [250, 500, 1_000, 2_000, 4_000];
+export class GatewaySession {
+    options;
+    current;
+    pending;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * The cached token while it stays valid for at least `minValidityMs`, else a
+     * new one. Concurrent callers share one exchange.
+     */
+    async token(minValidityMs) {
+        if (this.current && this.current.expiresAt - this.now() >= minValidityMs)
+            return this.current.token;
+        this.pending ??= this.exchange().finally(() => { this.pending = undefined; });
+        return this.pending;
+    }
+    now() { return (this.options.now ?? Date.now)(); }
+    async exchange() {
+        const delays = this.options.retryDelaysMs ?? RETRY_DELAYS_MS;
+        let refusedOnce = false;
+        for (let attempt = 0;; attempt += 1) {
+            // Presigned per attempt: the gateway refuses one signed more than five minutes ago.
+            const presignedUrl = await presignCallerIdentity(awsEnvironment(this.options.env));
+            let response;
+            let failure;
+            try {
+                response = await (this.options.fetch ?? fetch)(`${this.options.gatewayUrl}${SESSION_PATH}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ presignedUrl }), signal: AbortSignal.timeout(10_000) });
+                failure = `the gateway answered ${response.status}`;
+            }
+            catch (error) {
+                failure = `the gateway did not answer: ${error instanceof Error ? error.message : String(error)}`;
+            }
+            if (response?.ok) {
+                const body = await response.json();
+                const expiresAt = typeof body.data?.expiresAt === 'string' ? Date.parse(body.data.expiresAt) : NaN;
+                if (typeof body.data?.token !== 'string' || !body.data.token || Number.isNaN(expiresAt))
+                    throw new Error('the gateway session answer has no token and expiry');
+                this.current = { token: body.data.token, expiresAt };
+                return this.current.token;
+            }
+            // A refusal gets one more exchange with a new presign; the second is final.
+            if (response?.status === 401 && !refusedOnce) {
+                refusedOnce = true;
+                continue;
+            }
+            const retryable = response === undefined || RETRY_STATUSES.has(response.status);
+            if (!retryable || attempt >= delays.length)
+                throw new Error(`the gateway session was not issued: ${failure}`);
+            await sleep(delays[attempt]);
+        }
+    }
+}

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

@@ -85,6 +85,10 @@ export interface RuntimeOptions {
     queuePollMs?: number;
     /** Set when the runtime itself runs the App Gateway for its trusted actions (the Lambda option). */
     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;
@@ -97,12 +101,23 @@ export declare class Runtime {
     private queueLive;
     private queueWake;
     private readonly runs;
+    private session;
     private readonly log;
     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
@@ -143,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

@@ -49,6 +49,13 @@
 //                                 runs without waiting on the data path. Set by
 //                                 Provision; the table exists otherwise
 //   ISOMORPH_APP_ROOT             the app root (default: the working directory)
+//   ISOMORPH_GATEWAY_IDENTITY=sts-session
+//                                 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';
@@ -77,6 +84,12 @@ const MAX_BODY_BYTES = 1 << 20;
 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; 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;
 // A CronJob pod may start while the app's database is still waking: --run-job
 // waits this long for the gateway's data path, probing every retry interval.
@@ -248,6 +261,9 @@ export class Runtime {
     queueLive = false;
     queueWake = false;
     runs;
+    // Built on first use: the AWS signing modules load only on a serverless
+    // cell, so a cluster runtime never imports them.
+    session;
     log;
     server = createServer((request, response) => { void this.serve(request, response); });
     constructor(options) {
@@ -257,7 +273,12 @@ export class Runtime {
     }
     async start() {
         this.inventory = await discover(this.options.root);
-        await this.refreshToken();
+        // A Web Function must listen within 10 s of starting, so the session is
+        // only begun here; the first request that needs it waits for it.
+        if (this.options.gatewayIdentity)
+            void this.refreshToken().catch((error) => this.log(`gateway session: ${error instanceof Error ? error.message : String(error)}`));
+        else
+            await this.refreshToken();
         if (this.options.localGateway && this.inventory.trusted.length > 0) {
             this.localGateway = new LocalGateway({ ...this.options.localGateway, log: this.log });
             await this.localGateway.start();
@@ -276,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
@@ -328,7 +372,7 @@ export class Runtime {
      */
     async runJobOnce(name, now = new Date()) {
         this.inventory = await discover(this.options.root);
-        await this.refreshToken();
+        await this.refreshToken(JOB_SESSION_MIN_VALIDITY_MS);
         if (!this.inventory.jobs.some((job) => job.name === name)) {
             this.log(`this app has no ${JOBS_DIR}/${name}.ts`);
             return false;
@@ -401,7 +445,12 @@ export class Runtime {
         })().catch(error => { this.aiBinding = undefined; throw error; });
         await this.aiBinding;
     }
-    async refreshToken() {
+    async refreshToken(minValidityMs = SESSION_MIN_VALIDITY_MS) {
+        if (this.options.gatewayIdentity) {
+            this.session ??= import('./gateway-session.js').then(({ GatewaySession }) => new GatewaySession({ gatewayUrl: this.options.gatewayUrl }));
+            process.env.ISOMORPH_WORKLOAD_TOKEN = await (await this.session).token(minValidityMs);
+            return;
+        }
         if (!this.options.tokenFile)
             return;
         const token = (await readFile(this.options.tokenFile, 'utf8')).trim();
@@ -553,6 +602,12 @@ export class Runtime {
                 return refuse(response, 400, 'VALIDATION_FAILED', 'the request body is not JSON', requestId);
             }
         }
+        // Only the runtime's own calls, a trusted action's and the AI binding
+        // send the bearer; an action acting as its caller does not wait for it.
+        // Without a session such a call fails with AUTH_REQUIRED, which the builder reads.
+        const sendsBearer = name.startsWith(RESERVED_PREFIX) ? name !== PING_ACTION : this.inventory.trusted.includes(name) || Boolean(process.env.ISOMORPH_AI_VERSION_ID);
+        if (this.options.gatewayIdentity && sendsBearer)
+            await this.refreshToken().catch((error) => this.log(`gateway session: ${error instanceof Error ? error.message : String(error)}`));
         try {
             if (name.startsWith(RESERVED_PREFIX))
                 return answer(response, 200, { data: await this.reserved(name, input, context) }, requestId);
@@ -634,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: {
@@ -663,6 +724,8 @@ export function optionsFromEnvironment(env = process.env) {
         mode: env.ISOMORPH_RUNTIME_MODE === 'gate' ? 'gate' : env.ISOMORPH_JOBS_SCHEDULER === 'platform' ? 'actions' : 'full',
         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(/\/$/, '') } }
             : {}),
@@ -679,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');
@@ -718,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.21.1",
+  "version": "1.24.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -38,6 +38,9 @@
     }
   },
   "dependencies": {
+    "@aws-crypto/sha256-js": "5.2.0",
+    "@smithy/protocol-http": "5.6.2",
+    "@smithy/signature-v4": "5.7.4",
     "acorn": "8.18.0"
   }
 }