@isomorph.ai/app-sdk 1.4.2 → 1.5.0

package/dist/browser.js

@@ -0,0 +1,135 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+import { chromium } from 'playwright-core';
+import { jsonSchema, tool } from 'ai';
+let active = false;
+export function publicIPv4(address) {
+    if (isIP(address) !== 4)
+        return false;
+    const [a, b, c] = address.split('.').map(Number);
+    return !(a === 0 || a === 10 || a === 127 || a >= 224 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && [0, 168].includes(b) || a === 100 && b >= 64 && b <= 127 || a === 198 && ([18, 19].includes(b) || b === 51 && c === 100) || a === 203 && b === 0 && c === 113);
+}
+/** App-reviewed read workflows only; control names and selectors never come from the model. */
+export async function createBrowserTools(workflow) {
+    if (active)
+        throw new Error('A browser run is already active.');
+    if (!workflow.pages.length)
+        throw new Error('Declare a read-only page.');
+    const pages = workflow.pages.map(value => {
+        const url = new URL(value);
+        if (url.protocol !== 'https:' || url.username || url.password || url.port && url.port !== '443')
+            throw new Error('Browser pages require HTTPS without credentials or custom ports.');
+        return url;
+    });
+    const allowed = new Set(pages.map(url => url.origin + url.pathname));
+    const hosts = [...new Set(pages.map(url => url.hostname))];
+    active = true;
+    let browser;
+    let home;
+    let timer;
+    let closed = false;
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        clearTimeout(timer);
+        workflow.signal?.removeEventListener('abort', abort);
+        try {
+            await browser?.close();
+        }
+        finally {
+            if (home)
+                await rm(home, { recursive: true, force: true });
+            active = false;
+        }
+    };
+    const abort = () => { void close(); };
+    try {
+        if (workflow.signal?.aborted)
+            throw new Error('Browser run cancelled.');
+        const rules = [];
+        for (const host of hosts) {
+            const addresses = await lookup(host, { all: true, family: 4 });
+            if (!addresses.length || addresses.some(entry => !publicIPv4(entry.address)))
+                throw new Error('Browser destination is not public.');
+            rules.push(`MAP ${host} ${addresses[0].address}`);
+        }
+        home = await mkdtemp(join(tmpdir(), 'isomorph-browser-'));
+        const executablePath = workflow.executablePath ?? process.env.HARBOUR_PUPPETEER_EXECUTABLE_PATH;
+        browser = await chromium.launch({ headless: true, chromiumSandbox: true, ...(executablePath ? { executablePath } : {}), args: [`--host-resolver-rules=${rules.join(',')},MAP * ~NOTFOUND`, '--no-proxy-server', '--disable-quic', '--force-webrtc-ip-handling-policy=disable_non_proxied_udp'], env: { PATH: process.env.PATH ?? '', HOME: home, TMPDIR: process.env.TMPDIR ?? '/tmp' } });
+        const context = await browser.newContext({ acceptDownloads: false, serviceWorkers: 'block' });
+        await context.route('**/*', async (route) => {
+            const request = route.request();
+            const url = new URL(request.url());
+            if (!['GET', 'HEAD'].includes(request.method()) || url.protocol !== 'https:' || url.port && url.port !== '443' || !hosts.includes(url.hostname) || request.isNavigationRequest() && !allowed.has(url.origin + url.pathname))
+                return route.abort('blockedbyclient');
+            return route.continue();
+        });
+        await context.routeWebSocket('**/*', socket => socket.close());
+        const page = await context.newPage();
+        context.on('page', popup => { if (popup !== page)
+            void popup.close(); });
+        page.setDefaultTimeout(10_000);
+        timer = setTimeout(abort, 5 * 60_000);
+        timer.unref();
+        workflow.signal?.addEventListener('abort', abort, { once: true });
+        if (workflow.signal?.aborted) {
+            await close();
+            throw new Error('Browser run cancelled.');
+        }
+        let actions = 0;
+        const run = async (operation) => {
+            if (closed || workflow.signal?.aborted)
+                throw new Error('Browser session is closed.');
+            if (++actions > 50) {
+                await close();
+                throw new Error('Browser action limit reached.');
+            }
+            try {
+                return await operation();
+            }
+            catch (error) {
+                await close();
+                throw error;
+            }
+        };
+        const empty = jsonSchema({ type: 'object', properties: {}, additionalProperties: false });
+        return { close, tools: {
+                browserNavigate: tool({ description: 'Open an approved read-only page.', inputSchema: jsonSchema({ type: 'object', properties: { url: { type: 'string' } }, required: ['url'], additionalProperties: false }), execute: ({ url }) => run(async () => {
+                        const target = new URL(url);
+                        if (target.username || target.password || !allowed.has(target.origin + target.pathname))
+                            throw new Error('Page is outside this workflow.');
+                        await page.goto(target.href, { waitUntil: 'domcontentloaded' });
+                        return { url: page.url() };
+                    }) }),
+                browserObserve: tool({ description: 'Read page text and permitted controls.', inputSchema: empty, execute: () => run(async () => {
+                        const text = await page.locator('body').innerText();
+                        return { url: page.url(), text: text.slice(0, 16_000), truncated: text.length > 16_000, controls: Object.keys(workflow.controls ?? {}) };
+                    }) }),
+                browserControl: tool({ description: 'Use an app-reviewed read-only control.', inputSchema: jsonSchema({ type: 'object', properties: { name: { type: 'string' }, value: { type: 'string', maxLength: 2000 } }, required: ['name'], additionalProperties: false }), execute: ({ name, value }) => run(async () => {
+                        const control = workflow.controls?.[name];
+                        if (!control || control.page !== new URL(page.url()).origin + new URL(page.url()).pathname)
+                            throw new Error('Control is not approved on this page.');
+                        const element = page.locator(control.selector);
+                        if (await element.count() !== 1)
+                            throw new Error('Control is missing or ambiguous.');
+                        if (control.action === 'fill')
+                            await element.fill(value ?? '');
+                        else
+                            await element.click();
+                        return { url: page.url() };
+                    }) }),
+                browserScroll: tool({ description: 'Scroll down.', inputSchema: empty, execute: () => run(async () => { await page.mouse.wheel(0, 600); return { scrolled: true }; }) }),
+                browserScreenshot: tool({ description: 'Capture the viewport.', inputSchema: empty, execute: () => run(async () => { const bytes = await page.screenshot({ type: 'png' }); if (bytes.length > 2 * 1024 * 1024)
+                        throw new Error('Screenshot exceeds 2 MiB.'); return { mediaType: 'image/png', base64: bytes.toString('base64') }; }) }),
+                browserClose: tool({ description: 'Close the browser.', inputSchema: empty, execute: async () => { await close(); return { closed: true }; } }),
+            } };
+    }
+    catch (error) {
+        await close();
+        throw error;
+    }
+}

package/dist/index.js

@@ -64,6 +64,13 @@ function mergeHeaders(...layers) {
 function runnerIdentityHeaders(identity) {
     if (typeof location !== 'undefined')
         return {};
+    const resolver = globalThis[Symbol.for('isomorph.actionIdentity')];
+    const actionToken = resolver?.();
+    if (actionToken !== undefined) {
+        if (!actionToken)
+            throw new IsomorphError('AUTH_REQUIRED', 'The action has no invoking-user identity.');
+        return { 'x-harbour-identity-context': actionToken };
+    }
     const environment = globalThis.process?.env;
     const name = environment?.ISOMORPH_IDENTITY_CONTEXT_HEADER;
     const token = identity === 'second-user' ? environment?.ISOMORPH_IDENTITY_CONTEXT_SECOND_USER : environment?.ISOMORPH_IDENTITY_CONTEXT;

package/dist/runtime.d.ts

@@ -9,6 +9,7 @@ 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 {
+    signal: AbortSignal;
     user: {
         id: string;
         email: string;
@@ -72,6 +73,8 @@ export interface RuntimeOptions {
     gatewayUrl: string;
     mode: RuntimeMode;
     tokenFile?: string;
+    /** False when the app has no runs table (ISOMORPH_JOB_RUNS=none): nothing reads or works it. */
+    jobRuns?: boolean;
     log?: (line: string) => void;
     /** The pause between queue passes while work is found; the tests shorten it. */
     queuePollMs?: number;
@@ -82,6 +85,7 @@ export declare class Runtime {
     private readonly running;
     private readonly timers;
     private stopped;
+    private aiBinding;
     private queueLive;
     private queueWake;
     private readonly runs;
@@ -89,7 +93,7 @@ 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, an app with jobs, a gateway to reach. */
+    /** Whether this process works the queue at all: not the gate, a runs table, an app with jobs, a gateway to reach. */
     private worksQueue;
     /**
      * Starts the queue loop unless it is already live. The first pass runs at
@@ -110,6 +114,7 @@ export declare class Runtime {
     private awaitDataPath;
     stop(): Promise<void>;
     private every;
+    private prepareAI;
     private refreshToken;
     private scheduleTick;
     /** One scheduled run; true when the handler returned, false when it threw or the last tick's run is still going. */

package/dist/runtime.js

@@ -44,13 +44,21 @@
 //                                 in-process scheduler. Set by Provision on the
 //                                 hosted kit-runtime; `isomorph dev` leaves it
 //                                 unset and keeps cron in-process
+//   ISOMORPH_JOB_RUNS=none        the app has no runs table (it never calls
+//                                 isomorph.jobs): no queue loop, and --run-job
+//                                 runs without waiting on the data path. Set by
+//                                 Provision; the table exists otherwise
 //   ISOMORPH_APP_ROOT             the app root (default: the working directory)
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { createServer } from 'node:http';
 import { readFile, readdir, stat } from 'node:fs/promises';
 import { register } from 'node:module';
 import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createClient, IsomorphError } from './index.js';
+const actionIdentity = new AsyncLocalStorage();
+const identityKey = Symbol.for('isomorph.actionIdentity');
+globalThis[identityKey] = () => actionIdentity.getStore();
 export const ACTIONS_DIR = 'actions';
 export const JOBS_DIR = 'jobs';
 export const RUNS_TABLE = 'isomorph_job_runs';
@@ -227,6 +235,7 @@ export class Runtime {
     running = new Set();
     timers = [];
     stopped = false;
+    aiBinding;
     // The queue loop is live while a pass runs or its next pass is timed; a
     // wake that arrives mid-pass is remembered so the pass after it looks again.
     queueLive = false;
@@ -256,9 +265,9 @@ export class Runtime {
         this.wakeQueue();
         return port;
     }
-    /** Whether this process works the queue at all: not the gate, an app with jobs, a gateway to reach. */
+    /** Whether this process works the queue at all: not the gate, a runs table, an app with jobs, a gateway to reach. */
     worksQueue() {
-        return this.options.mode !== 'gate' && this.inventory.jobs.length > 0 && Boolean(this.options.gatewayUrl);
+        return this.options.mode !== 'gate' && this.options.jobRuns !== false && this.inventory.jobs.length > 0 && Boolean(this.options.gatewayUrl);
     }
     /**
      * Starts the queue loop unless it is already live. The first pass runs at
@@ -313,7 +322,7 @@ export class Runtime {
             this.log(`this app has no ${JOBS_DIR}/${name}.ts`);
             return false;
         }
-        if (this.options.gatewayUrl && !(await this.awaitDataPath()))
+        if (this.options.gatewayUrl && this.options.jobRuns !== false && !(await this.awaitDataPath()))
             return false;
         return this.runScheduled(name, new Date(Math.floor(now.getTime() / 60_000) * 60_000));
     }
@@ -356,6 +365,30 @@ export class Runtime {
         };
         this.timers.push(setTimeout(loop, ms));
     }
+    async prepareAI() {
+        const versionId = process.env.ISOMORPH_AI_VERSION_ID;
+        if (!versionId)
+            return;
+        this.aiBinding ??= (async () => {
+            const token = process.env.ISOMORPH_WORKLOAD_TOKEN;
+            if (!token)
+                throw new Error('AI workload identity is unavailable.');
+            const response = await fetch(`${this.options.gatewayUrl}/_harbour/internal/ai/connection`, { method: 'POST', headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' }, body: JSON.stringify({ versionId }), signal: AbortSignal.timeout(15_000) });
+            if (!response.ok)
+                throw new Error('This app version has no active AI connection yet.');
+            const result = await response.json();
+            const binding = result.data;
+            if (!binding?.key || !binding.gatewayBaseUrl || new URL(binding.gatewayBaseUrl).protocol !== 'https:')
+                throw new Error('Invalid AI runtime binding.');
+            process.env.OPENAI_BASE_URL = binding.gatewayBaseUrl;
+            process.env.OPENAI_API_KEY = binding.key;
+            if (binding.modelAliases?.generation)
+                process.env.ISOMORPH_AI_GENERATION_MODEL_ALIAS = binding.modelAliases.generation;
+            if (binding.modelAliases?.image)
+                process.env.ISOMORPH_AI_IMAGE_MODEL_ALIAS = binding.modelAliases.image;
+        })().catch(error => { this.aiBinding = undefined; throw error; });
+        await this.aiBinding;
+    }
     async refreshToken() {
         if (!this.options.tokenFile)
             return;
@@ -459,7 +492,10 @@ export class Runtime {
         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 controller = new AbortController();
+        const abort = () => controller.abort();
+        response.once('close', abort);
+        const context = { signal: controller.signal, 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);
@@ -477,8 +513,9 @@ export class Runtime {
                 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);
+            await this.prepareAI();
             const handler = await loadHandler(this.options.root, ACTIONS_DIR, name);
-            const result = await handler(input, context);
+            const result = await actionIdentity.run(header(request, 'X-Harbour-Identity-Context'), () => handler(input, context));
             return answer(response, 200, { data: result === undefined ? null : result }, requestId);
         }
         catch (error) {
@@ -487,6 +524,10 @@ export class Runtime {
             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);
         }
+        finally {
+            response.removeListener('close', abort);
+            controller.abort();
+        }
     }
     async reserved(name, input, context) {
         const body = (input && typeof input === 'object' ? input : {});
@@ -529,6 +570,7 @@ export function optionsFromEnvironment(env = process.env) {
         gatewayUrl: (env.ISOMORPH_GATEWAY_URL || env.HARBOUR_GATEWAY_URL || '').replace(/\/$/, ''),
         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',
     };
 }
 /** The job named by `--run-job <name>` or `--run-job=<name>`; undefined when the runtime is a server. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isomorph.ai/app-sdk",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -20,7 +20,21 @@
     "test": "npm run build && node --test test/*.test.mjs"
   },
   "devDependencies": {
-    "typescript": "5.9.2",
-    "@types/node": "24.7.0"
+    "@types/node": "24.7.0",
+    "ai": "7.0.118",
+    "playwright-core": "1.58.2",
+    "typescript": "5.9.2"
+  },
+  "peerDependencies": {
+    "ai": "^7.0.118",
+    "playwright-core": "^1.58.2"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    },
+    "playwright-core": {
+      "optional": true
+    }
   }
 }