@isomorph.ai/app-sdk 2.5.0 → 2.6.1

package/README.md

@@ -365,6 +365,33 @@ The calls go to the local App Gateway beside the runtime (`ISOMORPH_TRUSTED_GATE
 
 (1.17.0; data plane ADR 0057)
 
+## Public actions
+
+One door with nobody signed in: a sign-up form, a feedback box, an inbound lead. An action that
+exports `access = "public"` beside `expose = { description, input }` runs for a caller with no
+sign-in as `public:<app>` (`ctx.user.kind === 'public'`, no email, no groups). It may only insert
+rows: a select, update, delete, file, integration, AI call, realtime, another action or a job
+enqueue inside it is refused with `PUBLIC_DENIED`. A public action cannot be trusted. The page
+calls it with `isomorph.actions.invokePublic(name, input)`: a plain POST with no cookie and no
+sign-in, answering the result or an `IsomorphError` with the gateway's category. The table it
+writes says so in its row rule (`WITH CHECK (current_setting('harbour.user_id', true) = 'public:<app>')`).
+
+```ts
+// actions/signup.ts
+export const access = "public";
+export const expose = { description: 'Sign a visitor up for the launch list', input: { type: 'object', properties: { email: { type: 'string' } }, required: ['email'] } };
+
+export default async function signup(input: { email: string }) {
+  await isomorph.data.from('launch_signups').insert({ email: input.email });
+  return { ok: true };
+}
+
+// page
+await isomorph.actions.invokePublic('signup', { email });
+```
+
+(2.6.0)
+
 ## Browser read tools
 
 Install optional peers `ai` and `playwright-core@1.58.2`. Locally run `npx playwright-core install chromium --only-shell`; V2 packages Chromium in the existing app image. An existing system executable can be supplied as executablePath.

package/dist/index.d.ts

@@ -38,10 +38,12 @@ export interface IsomorphUser {
     appUser?: unknown;
     /**
      * Who is calling: a `'person'` signed in through the browser or an MCP
-     * client, or a `'service'` holding a credential the company's IT issued,
-     * whose `id` and `name` are the credential's. Absent means a person.
+     * client, a `'service'` holding a credential the company's IT issued,
+     * whose `id` and `name` are the credential's, or `'public'`: nobody signed
+     * in, calling an action that exports `access = "public"` (`id` is
+     * `public:<app>`, no email, no groups). Absent means a person.
      */
-    kind?: 'person' | 'service';
+    kind?: 'person' | 'service' | 'public';
 }
 /**
  * `export const expose = { description, input }` on an action, beside
@@ -2066,6 +2068,13 @@ export declare function createClient(options?: ClientOptions): {
         invoke: <T = unknown, P = string>(name: string, input: unknown, options?: {
             onProgress?: (step: P) => void;
         }) => Promise<T>;
+        /**
+         * Call an action that exports `access = "public"` with no sign-in: a
+         * plain POST to `/_harbour/api/<name>` on the API host, no cookie, no
+         * credential, no sign-in redirect. The result is the action's, the
+         * error an `IsomorphError` with the gateway's category.
+         */
+        invokePublic: <T = unknown>(name: string, input: unknown) => Promise<T>;
     };
     jobs: {
         /** Select the owner's folder for a declared configurable file trigger. */

package/dist/index.js

@@ -819,6 +819,26 @@ export function createClient(options = {}) {
                 }
                 return transport.json(path, { method: 'POST', body: JSON.stringify(input) }, options.onProgress);
             },
+            /**
+             * Call an action that exports `access = "public"` with no sign-in: a
+             * plain POST to `/_harbour/api/<name>` on the API host, no cookie, no
+             * credential, no sign-in redirect. The result is the action's, the
+             * error an `IsomorphError` with the gateway's category.
+             */
+            invokePublic: async (name, input) => {
+                const response = await transport.fetch(`${transport.baseUrl}/_harbour/api/${encodeURIComponent(name)}`, {
+                    method: 'POST', credentials: 'omit', headers: { 'content-type': 'application/json' }, body: JSON.stringify(input ?? {}),
+                });
+                let body = {};
+                try {
+                    body = await response.json();
+                }
+                catch { /* not JSON: the status says what happened */ }
+                if (!response.ok || body.error) {
+                    throw new IsomorphError(body.error?.category ?? 'INTERNAL', body.error?.message ?? `the public action answered ${response.status}`, body.requestId, undefined, response.status);
+                }
+                return body.data;
+            },
         },
         jobs: {
             /** Select the owner's folder for a declared configurable file trigger. */

package/dist/jobs.d.ts

@@ -58,6 +58,8 @@ export interface JobContext {
 }
 /** Whether the module says `export const <name> = true`, read without importing it; a module that does not parse does not. */
 export declare function exportsTrue(file: string, name: string): Promise<boolean>;
+/** Whether the module says `export const <name> = <value>` with that one literal, read statically; nothing computed counts. */
+export declare function exportsLiteral(file: string, name: string, value: string | boolean): Promise<boolean>;
 export declare function discoverJobs(root: string): Promise<JobDefinition[]>;
 type Handler = (...args: unknown[]) => unknown;
 export declare function loadHandler(root: string, dir: string, name: string): Promise<Handler>;

package/dist/jobs.js

@@ -103,7 +103,11 @@ function parseModule(source) {
     return parse(stripTypeScriptTypes(source), { ecmaVersion: 'latest', sourceType: 'module' }).body;
 }
 /** Whether the module says `export const <name> = true`, read without importing it; a module that does not parse does not. */
-export async function exportsTrue(file, name) {
+export function exportsTrue(file, name) {
+    return exportsLiteral(file, name, true);
+}
+/** Whether the module says `export const <name> = <value>` with that one literal, read statically; nothing computed counts. */
+export async function exportsLiteral(file, name, value) {
     let statements;
     try {
         statements = parseModule(await readFile(file, 'utf8'));
@@ -114,7 +118,7 @@ export async function exportsTrue(file, name) {
     return statements.some(statement => statement.type === 'ExportNamedDeclaration'
         && statement.declaration?.type === 'VariableDeclaration' && statement.declaration.kind === 'const'
         && statement.declaration.declarations.some(declaration => declaration.id.type === 'Identifier' && declaration.id.name === name
-            && declaration.init?.type === 'Literal' && declaration.init.value === true));
+            && declaration.init?.type === 'Literal' && declaration.init.value === value));
 }
 export async function discoverJobs(root) {
     const directory = join(root, JOBS_DIR);

package/dist/runtime.d.ts

@@ -39,6 +39,8 @@ export interface RuntimeInventory {
     trusted: string[];
     /** The actions whose module says `export const expose = { description, input }`, by name: what the kit gate records as exposed (ADR 0100). */
     exposed: Record<string, ActionExposure>;
+    /** The actions whose module says `export const access = "public"`: the gateway runs them for callers with no sign-in (data plane ADR 0114). */
+    public: string[];
     jobs: JobDefinition[];
 }
 /** Every `actions/<name>.ts` and `jobs/<name>.ts` the app carries, by logical name. */
@@ -68,6 +70,8 @@ export declare class Runs {
     cancel(id: string, owner: string): Promise<JobRun | null>;
     /** Rows whose lease ran out go back to the queue while attempts remain, else fail; how many there were. */
     reclaim(now: Date, active?: ReadonlySet<string>): Promise<number>;
+    /** Deletes finished runs created before `before` (the queue index covers status and created_at); how many went. */
+    prune(before: Date): Promise<number>;
     /** 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>;
@@ -118,6 +122,7 @@ export declare class Runtime {
     private queueWorkers;
     private queueWake;
     private claimTail;
+    private pruneDue;
     private readonly activeRuns;
     private readonly runs;
     private session;
@@ -191,6 +196,8 @@ export declare class Runtime {
      * when the queue is empty or both execution slots are occupied.
      */
     work(): Promise<boolean>;
+    /** A failed prune is logged and tried again next day; it never stops the pass that carries it. */
+    private pruneRuns;
     private serve;
     private transaction;
     private loadFailures;

package/dist/runtime.js

@@ -68,7 +68,7 @@ import { pathToFileURL } from 'node:url';
 import { createClient, gatewayRequest, IsomorphError } from './index.js';
 import { userGroupsFromHeader } from './user-groups.js';
 import { userRole } from './user-role.js';
-import { FILE_MIME_TYPES, providerFileId, actionExposure, discoverJobs, exportsTrue, invokeJob, loadHandler, JOBS_DIR } from './jobs.js';
+import { FILE_MIME_TYPES, providerFileId, actionExposure, discoverJobs, exportsLiteral, exportsTrue, invokeJob, loadHandler, JOBS_DIR } from './jobs.js';
 import { WEBHOOK_ADAPTERS } from './webhook-adapters.js';
 import { LocalGateway } from './local-gateway.js';
 export { JOBS_DIR } from './jobs.js';
@@ -88,6 +88,12 @@ const MAX_BODY_BYTES = 1 << 20;
 const LEASE_MS = 5 * 60_000;
 const QUEUE_WORKERS = 2;
 const QUEUE_POLL_MS = 2_000;
+// A finished run's row (input, result, error) is kept this long, then the
+// queue loop deletes it: once per process start and once a day after that,
+// never on every pass. Nothing else ever removed a row (the outbox backlog
+// of 2026-10-26 was the same shape).
+const RUN_RETENTION_MS = 30 * 24 * 60 * 60_000;
+const PRUNE_EVERY_MS = 24 * 60 * 60_000;
 const AI_RETRY_MS = 30_000;
 const TOKEN_REFRESH_MS = 60_000;
 // A gateway session lasts an hour. An action runs at most 300 s, so a request
@@ -121,8 +127,9 @@ export async function discover(root) {
     const trusted = await Promise.all(actions.map((name) => exportsTrue(join(root, ACTIONS_DIR, `${name}.ts`), 'trusted')));
     const exposures = await Promise.all(actions.map((name) => actionExposure(join(root, ACTIONS_DIR, `${name}.ts`))));
     const exposed = Object.fromEntries(actions.flatMap((name, index) => exposures[index] ? [[name, exposures[index]]] : []));
+    const publicAccess = await Promise.all(actions.map((name) => exportsLiteral(join(root, ACTIONS_DIR, `${name}.ts`), 'access', 'public')));
     const jobs = await discoverJobs(root);
-    return { actions, trusted: actions.filter((_, index) => trusted[index]), exposed, jobs };
+    return { actions, trusted: actions.filter((_, index) => trusted[index]), exposed, public: actions.filter((_, index) => publicAccess[index]), jobs };
 }
 // ---- Cron ------------------------------------------------------------------
 /** One field of a five-field cron expression: numbers, `*`, lists, ranges and steps, no names. */
@@ -279,6 +286,11 @@ export class Runs {
         }
         return interrupted.length;
     }
+    /** Deletes finished runs created before `before` (the queue index covers status and created_at); how many went. */
+    async prune(before) {
+        const { data } = await this.table().delete().in('status', ['succeeded', 'failed', 'cancelled']).lt('created_at', before.toISOString()).select('id');
+        return data.length;
+    }
     /** Claims the oldest queued run by a conditional update; null when the queue is empty or another worker won. */
     async claim(now) {
         while (true) {
@@ -321,7 +333,7 @@ export class Runs {
 }
 export class Runtime {
     options;
-    inventory = { actions: [], trusted: [], exposed: {}, jobs: [] };
+    inventory = { actions: [], trusted: [], exposed: {}, public: [], jobs: [] };
     localGateway;
     running = new Set();
     timers = [];
@@ -331,6 +343,7 @@ export class Runtime {
     queueWorkers = 0;
     queueWake = 0;
     claimTail = Promise.resolve();
+    pruneDue = 0;
     activeRuns = new Set();
     runs;
     // Built on first use: the AWS signing modules load only on a serverless
@@ -670,6 +683,10 @@ export class Runtime {
             if (this.activeRuns.size >= QUEUE_WORKERS)
                 return false;
             const now = new Date();
+            if (now.getTime() >= this.pruneDue) {
+                this.pruneDue = now.getTime() + PRUNE_EVERY_MS;
+                await this.pruneRuns(now);
+            }
             reclaimed = await this.runs.reclaim(now, this.activeRuns);
             run = await this.runs.claim(now);
             if (run)
@@ -710,6 +727,17 @@ export class Runtime {
             this.activeRuns.delete(run.id);
         }
     }
+    /** A failed prune is logged and tried again next day; it never stops the pass that carries it. */
+    async pruneRuns(now) {
+        try {
+            const pruned = await this.runs.prune(new Date(now.getTime() - RUN_RETENTION_MS));
+            if (pruned > 0)
+                this.log(`pruned ${pruned} finished run(s) older than 30 days`);
+        }
+        catch (error) {
+            this.log(`pruning finished runs failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     async serve(request, response) {
         const requestId = header(request, 'x-request-id') || undefined;
         const name = decodeURIComponent((request.url ?? '/').split('?')[0].replace(/^\/+/, ''));
@@ -728,8 +756,10 @@ export class Runtime {
             id: userId,
             // A service credential's call arrives with the credential as the verified user
             // (`service:<clientId>`, ADR 0101); the action sees it as `kind: 'service'`, the
-            // shape `/_harbour/identity/current` already answers. Anything else is a person.
-            ...(userId.startsWith('service:') ? { kind: 'service' } : {}),
+            // shape `/_harbour/identity/current` already answers. A public action's caller
+            // arrives as `public:<app>` with no email and no groups (data plane ADR 0114).
+            // Anything else is a person.
+            ...(userId.startsWith('service:') ? { kind: 'service' } : userId.startsWith('public:') ? { kind: 'public' } : {}),
             email: header(request, 'X-Harbour-Verified-User-Email'),
             groups: userGroupsFromHeader(header(request, 'X-Harbour-Verified-User-Groups')),
             role: userRole(header(request, 'X-Harbour-Verified-User-Role')),
@@ -887,7 +917,7 @@ export class Runtime {
             case PING_ACTION: {
                 // `hooks` is what the local gateway's hooks entrance serves under `isomorph dev` (data plane ADR 0112).
                 const hooks = this.inventory.jobs.flatMap((job) => job.trigger?.type === 'webhook' ? [{ job: job.name, provider: job.trigger.provider }] : []);
-                const answer = { ok: true, mode: this.options.mode, actions: this.inventory.actions, trusted: this.inventory.trusted, exposed: this.inventory.exposed, jobs: this.inventory.jobs.map((job) => job.name), hooks };
+                const answer = { ok: true, mode: this.options.mode, actions: this.inventory.actions, trusted: this.inventory.trusted, exposed: this.inventory.exposed, public: this.inventory.public, jobs: this.inventory.jobs.map((job) => job.name), hooks };
                 return this.options.mode === 'gate' ? { ...answer, loadFailures: await this.loadFailures() } : answer;
             }
             case ENQUEUE_ACTION: {

package/package.json

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