@isomorph.ai/app-sdk 1.2.1 → 1.3.0

package/dist/index.d.ts

@@ -144,6 +144,24 @@ export type IntegrationConnectResult = {
 export interface IntegrationDisconnectResult {
     status: 'disconnected';
 }
+export type JobRunStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+export interface JobRun {
+    id: string;
+    job: string;
+    status: JobRunStatus;
+    attempt: number;
+    max_attempts: number;
+    progress: number;
+    note: string | null;
+    input: unknown;
+    result: unknown;
+    error: string | null;
+    owner_subject: string;
+    cancel_requested: boolean;
+    lease_until: string | null;
+    created_at: string;
+    updated_at: string;
+}
 export type AiRole = 'system' | 'user' | 'assistant';
 export interface AiMessage {
     role: AiRole;
@@ -334,6 +352,13 @@ export declare function createClient(options?: ClientOptions): {
     actions: {
         invoke: <T = unknown>(name: string, input: unknown) => Promise<T>;
     };
+    jobs: {
+        enqueue: (name: string, input?: unknown) => Promise<{
+            id: string;
+        }>;
+        get: (id: string) => Promise<JobRun>;
+        cancel: (id: string) => Promise<JobRun>;
+    };
     telemetry: {
         track: (name: string, properties?: Record<string, unknown>) => Promise<void>;
         page: (path?: string) => Promise<void>;

package/dist/index.js

@@ -535,6 +535,11 @@ export function createClient(options = {}) {
                 });
             },
         },
+        jobs: {
+            enqueue: (name, input) => transport.json('/_harbour/actions/isomorph-jobs-enqueue', { method: 'POST', body: JSON.stringify({ name, input: input ?? null }) }),
+            get: (id) => transport.json('/_harbour/actions/isomorph-jobs-get', { method: 'POST', body: JSON.stringify({ id }) }),
+            cancel: (id) => transport.json('/_harbour/actions/isomorph-jobs-cancel', { method: 'POST', body: JSON.stringify({ id }) }),
+        },
         telemetry: {
             track: (name, properties = {}) => transport.json('/_harbour/telemetry', {
                 method: 'POST', body: JSON.stringify({ name, properties }),

package/dist/runtime.d.ts

@@ -0,0 +1,89 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import { type IsomorphClient, type JobRun } from './index.js';
+export declare const ACTIONS_DIR = "actions";
+export declare const JOBS_DIR = "jobs";
+export declare const RUNS_TABLE = "isomorph_job_runs";
+export declare const RESERVED_PREFIX = "isomorph-";
+export declare const PING_ACTION = "isomorph-ping";
+export declare const ENQUEUE_ACTION = "isomorph-jobs-enqueue";
+export declare const GET_RUN_ACTION = "isomorph-jobs-get";
+export declare const CANCEL_RUN_ACTION = "isomorph-jobs-cancel";
+export interface ActionContext {
+    user: {
+        id: string;
+        email: string;
+    };
+    tenant: string;
+    app: string;
+    requestId: string;
+}
+export interface JobContext {
+    scheduledAt: string;
+    runId?: string;
+    input?: unknown;
+    progress(percent: number, note?: string): Promise<void>;
+    cancelled(): Promise<boolean>;
+}
+export interface RuntimeInventory {
+    actions: string[];
+    jobs: {
+        name: string;
+        schedule?: string;
+    }[];
+}
+/** Every `actions/<name>.ts` and `jobs/<name>.ts` the app carries, by logical name. */
+export declare function discover(root: string): Promise<RuntimeInventory>;
+/** Whether a five-field UTC cron expression names the given minute. Sunday is 0 and 7. */
+export declare function cronMatches(expression: string, at: Date): boolean;
+export declare class Runs {
+    private readonly client;
+    constructor(client: IsomorphClient);
+    private table;
+    enqueue(job: string, input: unknown, owner: string): Promise<{
+        id: string;
+    }>;
+    get(id: string, owner: string): Promise<JobRun | null>;
+    cancel(id: string, owner: string): Promise<JobRun | null>;
+    /** Rows whose lease ran out go back to the queue while attempts remain, else fail. */
+    reclaim(now: Date): Promise<void>;
+    /** Claims the oldest queued run by a conditional update; null when the queue is empty or another worker won. */
+    claim(now: Date): Promise<JobRun | null>;
+    progress(id: string, percent: number, note?: string): Promise<void>;
+    cancelRequested(id: string): Promise<boolean>;
+    finish(run: JobRun, outcome: {
+        result?: unknown;
+        error?: string;
+        cancelled?: boolean;
+    }): Promise<void>;
+}
+export interface RuntimeOptions {
+    root: string;
+    port: number;
+    gatewayUrl: string;
+    mode: 'full' | 'gate';
+    tokenFile?: string;
+    log?: (line: string) => void;
+}
+export declare class Runtime {
+    private readonly options;
+    private inventory;
+    private readonly running;
+    private readonly timers;
+    private stopped;
+    private readonly runs;
+    private readonly log;
+    readonly server: import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
+    constructor(options: RuntimeOptions);
+    start(): Promise<number>;
+    stop(): Promise<void>;
+    private every;
+    private refreshToken;
+    private scheduleTick;
+    private runScheduled;
+    /** One pass of the queue loop: reclaim expired leases, claim one run, run it. */
+    work(): Promise<void>;
+    private serve;
+    private reserved;
+}
+/** The runtime's settings from the environment; exported for the entry point and its test. */
+export declare function optionsFromEnvironment(env?: NodeJS.ProcessEnv): RuntimeOptions;

package/dist/runtime.js

@@ -0,0 +1,414 @@
+// The kit runtime: the one server-side process of a kit app. It serves the
+// app's `actions/<name>.ts` on the gateway's action route, runs `jobs/<name>.ts`
+// on their cron in-process, and works the app's queued runs. The same file
+// runs everywhere — the hosted pod, `isomorph dev` and the gate — started as
+//
+//   node --experimental-strip-types node_modules/@isomorph.ai/app-sdk/dist/runtime.js
+//
+// from the app root, so Node itself strips the app's TypeScript, exactly as
+// the V1 job runner and `isomorph jobs run` do. Nothing here reaches a
+// database or a company system directly: every read and write goes through
+// the App Gateway as the workload identity, the same door the browser uses.
+//
+// Environment:
+//   PORT                          the action server's port (default 8080)
+//   ISOMORPH_GATEWAY_URL          the gateway the SDK calls; HARBOUR_GATEWAY_URL
+//                                 is the container-side spelling
+//   ISOMORPH_WORKLOAD_TOKEN       the workload's bearer; HARBOUR_WORKLOAD_TOKEN_FILE
+//                                 names a projected token file re-read every minute
+//   ISOMORPH_RUNTIME_MODE=gate    serve actions only: no scheduler, no queue loop
+//   ISOMORPH_APP_ROOT             the app root (default: the working directory)
+import { createServer } from 'node:http';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createClient, IsomorphError } from './index.js';
+export const ACTIONS_DIR = 'actions';
+export const JOBS_DIR = 'jobs';
+export const RUNS_TABLE = 'isomorph_job_runs';
+export const RESERVED_PREFIX = 'isomorph-';
+export const PING_ACTION = 'isomorph-ping';
+export const ENQUEUE_ACTION = 'isomorph-jobs-enqueue';
+export const GET_RUN_ACTION = 'isomorph-jobs-get';
+export const CANCEL_RUN_ACTION = 'isomorph-jobs-cancel';
+const LOGICAL_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+// \x60 is the backtick: the brand guard counts template literals by
+// backticks, and a bare one inside this regex unbalanced its scan.
+const SCHEDULE_DECLARATION = /^export\s+const\s+schedule\s*=\s*["'\x60]([^"'\x60\n]+)["'\x60]/m;
+const MAX_BODY_BYTES = 1 << 20;
+const LEASE_MS = 5 * 60_000;
+const QUEUE_POLL_MS = 2_000;
+const TOKEN_REFRESH_MS = 60_000;
+const DEFAULT_MAX_ATTEMPTS = 3;
+/** Every `actions/<name>.ts` and `jobs/<name>.ts` the app carries, by logical name. */
+export async function discover(root) {
+    const list = async (dir) => {
+        const entries = await readdir(join(root, dir), { withFileTypes: true }).catch(() => []);
+        return entries.filter((entry) => entry.isFile() && entry.name.endsWith('.ts')).map((entry) => entry.name.slice(0, -3)).filter((name) => LOGICAL_NAME.test(name)).sort();
+    };
+    const actions = (await list(ACTIONS_DIR)).filter((name) => !name.startsWith(RESERVED_PREFIX));
+    const jobs = [];
+    for (const name of await list(JOBS_DIR)) {
+        const body = await readFile(join(root, JOBS_DIR, `${name}.ts`), 'utf8');
+        const match = SCHEDULE_DECLARATION.exec(body);
+        jobs.push(match ? { name, schedule: match[1].trim() } : { name });
+    }
+    return { actions, jobs };
+}
+// ---- Cron ------------------------------------------------------------------
+/** One field of a five-field cron expression: numbers, `*`, lists, ranges and steps, no names. */
+function fieldMatches(field, value, min, max) {
+    return field.split(',').some((part) => {
+        const [range, stepText] = part.split('/');
+        const step = stepText === undefined ? 1 : Number(stepText);
+        if (!Number.isInteger(step) || step < 1)
+            throw new Error(`invalid cron step in ${part}`);
+        let from = min;
+        let to = max;
+        if (range !== '*') {
+            const [a, b] = range.split('-').map(Number);
+            if (!Number.isInteger(a) || (b !== undefined && !Number.isInteger(b)))
+                throw new Error(`invalid cron field ${part}`);
+            from = a;
+            to = b === undefined ? (stepText === undefined ? a : max) : b;
+        }
+        if (from < min || to > max || from > to)
+            throw new Error(`cron field ${part} is out of range ${min}-${max}`);
+        return value >= from && value <= to && (value - from) % step === 0;
+    });
+}
+/** Whether a five-field UTC cron expression names the given minute. Sunday is 0 and 7. */
+export function cronMatches(expression, at) {
+    const fields = expression.trim().split(/\s+/);
+    if (fields.length !== 5)
+        throw new Error(`a schedule has five fields, not ${fields.length}: ${expression}`);
+    const [minute, hour, day, month, weekday] = fields;
+    const sunday = at.getUTCDay() === 0;
+    return fieldMatches(minute, at.getUTCMinutes(), 0, 59)
+        && fieldMatches(hour, at.getUTCHours(), 0, 23)
+        && fieldMatches(day, at.getUTCDate(), 1, 31)
+        && fieldMatches(month, at.getUTCMonth() + 1, 1, 12)
+        && (fieldMatches(weekday, at.getUTCDay(), 0, 7) || (sunday && fieldMatches(weekday, 7, 0, 7)));
+}
+const modules = new Map();
+function loadHandler(root, dir, name) {
+    const key = `${dir}/${name}`;
+    let loading = modules.get(key);
+    if (!loading) {
+        loading = import(pathToFileURL(join(root, dir, `${name}.ts`)).href).then((module) => {
+            if (typeof module.default !== 'function')
+                throw new Error(`${key}.ts has no default handler`);
+            return module.default;
+        });
+        loading.catch(() => modules.delete(key));
+        modules.set(key, loading);
+    }
+    return loading;
+}
+// ---- HTTP helpers ------------------------------------------------------------
+function answer(response, status, body, requestId) {
+    const encoded = JSON.stringify(body);
+    response.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(encoded), ...(requestId ? { 'x-request-id': requestId } : {}) });
+    response.end(encoded);
+}
+function refuse(response, status, category, message, requestId) {
+    answer(response, status, { error: { category, message } }, requestId);
+}
+async function readBody(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES)
+            return undefined;
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+}
+function header(request, name) {
+    const value = request.headers[name.toLowerCase()];
+    return (Array.isArray(value) ? value[0] : value) ?? '';
+}
+// ---- Runs (through the gateway, as the workload) ------------------------------
+export class Runs {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    table() { return this.client.data.from(RUNS_TABLE); }
+    async enqueue(job, input, owner) {
+        const { data } = await this.table().insert({ job, input: input ?? null, status: 'queued', attempt: 0, max_attempts: DEFAULT_MAX_ATTEMPTS, progress: 0, owner_subject: owner, cancel_requested: false }).select('id').single();
+        return { id: data.id };
+    }
+    async get(id, owner) {
+        const { data } = await this.table().select('*').eq('id', id).eq('owner_subject', owner).maybeSingle();
+        return data;
+    }
+    async cancel(id, owner) {
+        const { data } = await this.table().update({ cancel_requested: true, updated_at: new Date().toISOString() }).eq('id', id).eq('owner_subject', owner).select('*').maybeSingle();
+        if (data && data.status === 'queued') {
+            const { data: cancelled } = await this.table().update({ status: 'cancelled', updated_at: new Date().toISOString() }).eq('id', id).eq('status', 'queued').select('*').maybeSingle();
+            return cancelled ?? data;
+        }
+        return data;
+    }
+    /** Rows whose lease ran out go back to the queue while attempts remain, else fail. */
+    async reclaim(now) {
+        const { data: expired } = await this.table().select('*').eq('status', 'running').lt('lease_until', now.toISOString()).limit(20);
+        for (const run of expired) {
+            const exhausted = run.attempt >= run.max_attempts;
+            await this.table().update({ status: exhausted ? 'failed' : 'queued', error: exhausted ? 'the worker was interrupted and no attempts remain' : run.error, lease_until: null, updated_at: now.toISOString() }).eq('id', run.id).eq('status', 'running');
+        }
+    }
+    /** Claims the oldest queued run by a conditional update; null when the queue is empty or another worker won. */
+    async claim(now) {
+        const { data: queued } = await this.table().select('id, attempt').eq('status', 'queued').order('created_at').limit(1);
+        const next = queued[0];
+        if (!next)
+            return null;
+        const { data } = await this.table().update({ status: 'running', attempt: next.attempt + 1, lease_until: new Date(now.getTime() + LEASE_MS).toISOString(), updated_at: now.toISOString() }).eq('id', next.id).eq('status', 'queued').select('*').maybeSingle();
+        return data;
+    }
+    async progress(id, percent, note) {
+        await this.table().update({ progress: Math.max(0, Math.min(100, Math.round(percent))), ...(note === undefined ? {} : { note }), lease_until: new Date(Date.now() + LEASE_MS).toISOString(), updated_at: new Date().toISOString() }).eq('id', id);
+    }
+    async cancelRequested(id) {
+        const { data } = await this.table().select('cancel_requested').eq('id', id).maybeSingle();
+        return Boolean(data?.cancel_requested);
+    }
+    async finish(run, outcome) {
+        const retry = outcome.error !== undefined && !outcome.cancelled && run.attempt < run.max_attempts;
+        const status = outcome.cancelled ? 'cancelled' : outcome.error === undefined ? 'succeeded' : retry ? 'queued' : 'failed';
+        await this.table().update({ status, result: outcome.result ?? null, error: outcome.error ?? null, progress: status === 'succeeded' ? 100 : run.progress, lease_until: null, updated_at: new Date().toISOString() }).eq('id', run.id).eq('status', 'running');
+    }
+}
+export class Runtime {
+    options;
+    inventory = { actions: [], jobs: [] };
+    running = new Set();
+    timers = [];
+    stopped = false;
+    runs;
+    log;
+    server = createServer((request, response) => { void this.serve(request, response); });
+    constructor(options) {
+        this.options = options;
+        this.log = options.log ?? ((line) => console.error(`isomorph runtime: ${line}`));
+        this.runs = new Runs(createClient({ baseUrl: options.gatewayUrl || 'http://127.0.0.1:0' }));
+    }
+    async start() {
+        this.inventory = await discover(this.options.root);
+        await this.refreshToken();
+        await new Promise((done, fail) => {
+            this.server.once('error', fail);
+            this.server.listen(this.options.port, '0.0.0.0', () => done());
+        });
+        const address = this.server.address();
+        const port = typeof address === 'object' && address ? address.port : this.options.port;
+        this.log(`serving ${this.inventory.actions.length} action(s) and ${this.inventory.jobs.length} job(s) on port ${port} (${this.options.mode})`);
+        if (this.options.tokenFile)
+            this.every(TOKEN_REFRESH_MS, () => this.refreshToken());
+        if (this.options.mode === 'full') {
+            if (this.inventory.jobs.some((job) => job.schedule))
+                this.scheduleTick();
+            if (this.inventory.jobs.length > 0 && this.options.gatewayUrl)
+                this.every(QUEUE_POLL_MS, () => this.work());
+        }
+        return port;
+    }
+    async stop() {
+        this.stopped = true;
+        for (const timer of this.timers)
+            clearTimeout(timer);
+        await new Promise((done) => this.server.close(() => done()));
+    }
+    every(ms, task) {
+        const loop = () => {
+            if (this.stopped)
+                return;
+            Promise.resolve().then(task).catch((error) => this.log(`${error instanceof Error ? error.message : String(error)}`)).finally(() => {
+                if (!this.stopped)
+                    this.timers.push(setTimeout(loop, ms));
+            });
+        };
+        this.timers.push(setTimeout(loop, ms));
+    }
+    async refreshToken() {
+        if (!this.options.tokenFile)
+            return;
+        const token = (await readFile(this.options.tokenFile, 'utf8')).trim();
+        if (token)
+            process.env.ISOMORPH_WORKLOAD_TOKEN = token;
+    }
+    // The scheduler ticks at the top of every minute and runs each job whose
+    // cron names that minute; a job still running from its last tick is
+    // skipped, the V1 CronJob's Forbid policy.
+    scheduleTick() {
+        const now = Date.now();
+        const next = Math.floor(now / 60_000) * 60_000 + 60_000;
+        this.timers.push(setTimeout(() => {
+            if (this.stopped)
+                return;
+            const at = new Date(Math.round(Date.now() / 60_000) * 60_000);
+            for (const job of this.inventory.jobs) {
+                if (!job.schedule)
+                    continue;
+                let due = false;
+                try {
+                    due = cronMatches(job.schedule, at);
+                }
+                catch (error) {
+                    this.log(`jobs/${job.name}.ts: ${error.message}`);
+                }
+                if (due)
+                    void this.runScheduled(job.name, at);
+            }
+            this.scheduleTick();
+        }, Math.max(0, next - now)));
+    }
+    async runScheduled(name, at) {
+        const key = `schedule:${name}`;
+        if (this.running.has(key)) {
+            this.log(`jobs/${name}.ts is still running; the ${at.toISOString()} tick is skipped`);
+            return;
+        }
+        this.running.add(key);
+        try {
+            const handler = await loadHandler(this.options.root, JOBS_DIR, name);
+            await handler({ scheduledAt: at.toISOString(), progress: async () => undefined, cancelled: async () => false });
+            this.log(`jobs/${name}.ts ran for ${at.toISOString()}`);
+        }
+        catch (error) {
+            this.log(`jobs/${name}.ts failed for ${at.toISOString()}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            this.running.delete(key);
+        }
+    }
+    /** One pass of the queue loop: reclaim expired leases, claim one run, run it. */
+    async work() {
+        if (this.running.has('queue'))
+            return;
+        this.running.add('queue');
+        try {
+            const now = new Date();
+            await this.runs.reclaim(now);
+            const run = await this.runs.claim(now);
+            if (!run)
+                return;
+            if (!this.inventory.jobs.some((job) => job.name === run.job)) {
+                await this.runs.finish({ ...run, attempt: run.max_attempts }, { error: `no jobs/${run.job}.ts in this app` });
+                return;
+            }
+            try {
+                const handler = await loadHandler(this.options.root, JOBS_DIR, run.job);
+                const result = await handler({
+                    scheduledAt: now.toISOString(), runId: run.id, input: run.input,
+                    progress: (percent, note) => this.runs.progress(run.id, percent, note),
+                    cancelled: () => this.runs.cancelRequested(run.id),
+                });
+                const cancelled = await this.runs.cancelRequested(run.id);
+                await this.runs.finish(run, cancelled ? { cancelled: true } : { result: result === undefined ? null : result });
+            }
+            catch (error) {
+                await this.runs.finish(run, { error: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        finally {
+            this.running.delete('queue');
+        }
+    }
+    async serve(request, response) {
+        const requestId = header(request, 'x-request-id') || undefined;
+        const name = decodeURIComponent((request.url ?? '/').split('?')[0].replace(/^\/+/, ''));
+        if (request.method !== 'POST')
+            return refuse(response, 405, 'VALIDATION_FAILED', 'actions are invoked with POST', requestId);
+        const tenant = header(request, 'X-Harbour-Verified-Tenant');
+        const app = header(request, 'X-Harbour-Verified-App');
+        if (!tenant || !app)
+            return refuse(response, 401, 'AUTH_REQUIRED', 'the request did not come through the Isomorph gateway', requestId);
+        const context = { user: { id: header(request, 'X-Harbour-Verified-User-ID'), email: header(request, 'X-Harbour-Verified-User-Email') }, tenant, app, requestId: requestId ?? '' };
+        const raw = await readBody(request);
+        if (raw === undefined)
+            return refuse(response, 413, 'VALIDATION_FAILED', 'the request body is larger than 1 MiB', requestId);
+        let input = undefined;
+        if (raw.length > 0) {
+            try {
+                input = JSON.parse(raw.toString('utf8'));
+            }
+            catch {
+                return refuse(response, 400, 'VALIDATION_FAILED', 'the request body is not JSON', requestId);
+            }
+        }
+        try {
+            if (name.startsWith(RESERVED_PREFIX))
+                return answer(response, 200, { data: await this.reserved(name, input, context) }, requestId);
+            if (!this.inventory.actions.includes(name))
+                return refuse(response, 404, 'NOT_FOUND', `this app has no ${ACTIONS_DIR}/${name}.ts`, requestId);
+            const handler = await loadHandler(this.options.root, ACTIONS_DIR, name);
+            const result = await handler(input, context);
+            return answer(response, 200, { data: result === undefined ? null : result }, requestId);
+        }
+        catch (error) {
+            if (error instanceof IsomorphError)
+                return refuse(response, error.status ?? 400, error.category, error.message, requestId);
+            this.log(`${name}: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
+            return refuse(response, 500, 'INTERNAL', `the action ${name} failed; its log names the cause`, requestId);
+        }
+    }
+    async reserved(name, input, context) {
+        const body = (input && typeof input === 'object' ? input : {});
+        const owner = context.user.id;
+        switch (name) {
+            case PING_ACTION:
+                return { ok: true, mode: this.options.mode, actions: this.inventory.actions, jobs: this.inventory.jobs.map((job) => job.name) };
+            case ENQUEUE_ACTION: {
+                const job = typeof body.name === 'string' ? body.name : '';
+                if (!this.inventory.jobs.some((entry) => entry.name === job))
+                    throw new IsomorphError('VALIDATION_FAILED', `this app has no ${JOBS_DIR}/${job || '<name>'}.ts`, undefined, undefined, 400);
+                if (!owner)
+                    throw new IsomorphError('AUTH_REQUIRED', 'a run is started by a signed-in person', undefined, undefined, 401);
+                return this.runs.enqueue(job, body.input, owner);
+            }
+            case GET_RUN_ACTION: {
+                const run = typeof body.id === 'string' ? await this.runs.get(body.id, owner) : null;
+                if (!run)
+                    throw new IsomorphError('NOT_FOUND', 'no run of yours has that id', undefined, undefined, 404);
+                return run;
+            }
+            case CANCEL_RUN_ACTION: {
+                const run = typeof body.id === 'string' ? await this.runs.cancel(body.id, owner) : null;
+                if (!run)
+                    throw new IsomorphError('NOT_FOUND', 'no run of yours has that id', undefined, undefined, 404);
+                return run;
+            }
+            default:
+                throw new IsomorphError('NOT_FOUND', `${name} is not an Isomorph runtime action`, undefined, undefined, 404);
+        }
+    }
+}
+/** The runtime's settings from the environment; exported for the entry point and its test. */
+export function optionsFromEnvironment(env = process.env) {
+    return {
+        root: resolve(env.ISOMORPH_APP_ROOT || process.cwd()),
+        port: Number(env.PORT || 8080),
+        gatewayUrl: (env.ISOMORPH_GATEWAY_URL || env.HARBOUR_GATEWAY_URL || '').replace(/\/$/, ''),
+        mode: env.ISOMORPH_RUNTIME_MODE === 'gate' ? 'gate' : 'full',
+        tokenFile: env.HARBOUR_WORKLOAD_TOKEN_FILE || undefined,
+    };
+}
+const entry = process.argv[1] ? pathToFileURL(process.argv[1]).href : '';
+if (import.meta.url === entry) {
+    const options = optionsFromEnvironment();
+    if (options.gatewayUrl && !process.env.ISOMORPH_GATEWAY_URL)
+        process.env.ISOMORPH_GATEWAY_URL = options.gatewayUrl;
+    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 shutdown = () => { void runtime.stop().then(() => process.exit(0)); };
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+    await runtime.start();
+}

package/package.json

@@ -1,15 +1,26 @@
 {
   "name": "@isomorph.ai/app-sdk",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Fourier-Labs-AI/harbour-deployment-data-plane.git",
+    "directory": "packages/app-sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "npm run build && node --test test/*.test.mjs"
   },
   "devDependencies": {
-    "typescript": "5.9.2"
+    "typescript": "5.9.2",
+    "@types/node": "24.7.0"
   }
 }