@isomorph.ai/app-sdk 1.44.0 → 1.46.0

package/README.md

@@ -410,12 +410,13 @@ Options the app passes, never the model:
 - `session`: the name of a runtime secret a sign-in was saved under (`finishSignIn`'s `saveAs`, below). The task starts signed in and can use only that sign-in's websites. When the task is `done` the refreshed session is saved back to the same secret. A missing one fails with `No saved sign-in named <name>.` Run one task per saved sign-in at a time: two tasks would both save back, and some websites sign out the older copy.
 - `secrets`: `{ name: value }`, at most 10, names `^[A-Za-z][A-Za-z0-9_-]{0,63}$`, values up to 4096 bytes. The computer types a value into a password field by its name, and only there: it refuses to type a secret into a visible field, since the model reads the page after every step. The model sees only the names. Never put a password or any other credential in the task text; pass it here and say "sign in with the `password` secret". A user ID, customer ID or email is not a secret: give it in the task text.
 - `maxQueueMs`: how long the task may wait for a free computer before the tool cancels it (20 minutes unless set).
-- `allowedHosts`: the websites (1 to 10 lower-case hostnames) a task with `secrets` and no `session` may use. A saved sign-in carries its own.
+- `allowedHosts`: the websites (1 to 10 lower-case hostnames) the browser may use; without it a task with no sign-in may use any website. A task with `secrets` and no `session` needs it: the websites the secrets may be typed into. A saved sign-in carries its own.
+- The sign-in options are one of three shapes, and the compiler refuses the others, so `isomorph check` (which runs tsc) catches them before a run: `session` (with or without `secrets`), `secrets` with `allowedHosts`, or no sign-in (with or without `allowedHosts`). `secrets` without a session or hosts has nowhere to be typed, and `session` with `allowedHosts` names websites twice. A wrong option at run time throws a `VALIDATION_FAILED` error, which the job runner fails at once rather than retrying.
 - `onDownload({ name, contentType, size, blob })`: called once for each file a `done` task downloaded, one at a time, before the tool returns (at most 10 files, 100 MiB each). Store the `blob` yourself; the CUA keeps the files for a day at most. Without it nothing is fetched. A link that does not answer 200 fails the tool. The model only sees `downloads: [{ name, size }]`.
 
 A task with `session` or `secrets` works the page through clicks and typing only. `connectionId` is gone: pass `session`.
 
-(1.25.0, 1.36.0, 1.37.0, 1.39.0; data plane ADR 0078, ADR 0090, ADR 0091, ADR 0092)
+(1.25.0, 1.36.0, 1.37.0, 1.39.0, 1.45.0; data plane ADR 0078, ADR 0090, ADR 0091, ADR 0092, ADR 2026-10-26 job runs)
 
 ## Help on the task's existing computer
 
@@ -516,8 +517,10 @@ await runtimeSecrets.delete(`supplier-key/${ctx.user.id}`);
 - Each is one Secrets Manager secret in the app's own cell, under `ISOMORPH_RUNTIME_SECRETS_PREFIX` (the app's secret path plus `runtime/`, in `ISOMORPH_RUNTIME_SECRETS_REGION`); Provision sets both. The calls are signed as the runtime's own role, which may use only this app's runtime secrets. Secrets the builder set stay read-only.
 - `delete` removes the secret with no recovery window. Secrets Manager finishes deleting it within seconds; until then `get` returns null, and a `put` of the same name waits for the deletion to finish (up to about 25 seconds) before saving.
 - Each one costs $0.40 a month while it exists.
+- Under `isomorph dev` there is no cell: the CLI sets `ISOMORPH_RUNTIME_SECRETS_DIR` and each secret is one private file (`0600`) in that folder, under `.isomorph/local/`. Computer use itself still needs the deployed app.
+- A bad name or value, or an app with neither setting, throws a `VALIDATION_FAILED` error before any call; the job runner fails such a run at once.
 
-(1.36.0, 1.36.1; data plane ADR 0090)
+(1.36.0, 1.36.1, 1.45.0; data plane ADR 0090)
 
 ## Running and rollout
 
@@ -639,6 +642,14 @@ On a serverless cell Harbour runs an app's server code as Lambda functions, from
 
 (1.24.0; data plane ADR 0065)
 
+### Job runs
+
+A queued run (`isomorph.jobs.enqueue`) is tried up to three times; a failure leaves the next attempt queued. A `VALIDATION_FAILED` error (an `IsomorphError` of that category, or any error whose `code` is `VALIDATION_FAILED`: a wrong computer use option, no runtime secrets here, a job's own input check) fails the run at the first attempt, with `error` prefixed `VALIDATION_FAILED:`.
+
+`isomorph.jobs.get(id)` and `cancel(id)` work on the signed-in person's own runs. `isomorph.jobs.list({ job?, limit? })` (reserved action `isomorph-jobs-list`) shows a builder every person's newest runs, one job's when named, at most 100 (20 unless set): `id, job, status, attempt, max_attempts, error, note, created_at, updated_at`, never a run's input or result. A member gets `FORBIDDEN`. In the browser, `GET /_harbour/jobs` on the app's API host is the same list as a plain page: the gateway asks `isomorph-jobs-list` for `text/html` (the newest 50), and the runtime answers the table or the same `FORBIDDEN`.
+
+(1.45.0; data plane ADR 2026-10-26 job runs)
+
 ### Email-arrival jobs
 
 On managed same-account serverless or Kubernetes hosting, an ordinary job can declare an inbox trigger instead of a schedule:

package/dist/computer-use-api.js

@@ -1,6 +1,7 @@
 // Harbour's computer use API (CUA) as the runtime's own role, signed with
 // SigV4 (ADR 0078): what the computer use tool and the sign-in helpers share.
 import { runtimeCredentials, signedJsonPost } from './aws.js';
+import { IsomorphError } from './index.js';
 export function refused(path, status, body) {
     const error = body?.error;
     return new Error(`The computer use API refused ${path} (${status}${typeof error === 'string' ? `: ${error}` : ''}).`);
@@ -27,7 +28,7 @@ const HOST = /^[a-z0-9](?:[a-z0-9.-]{0,251}[a-z0-9])?$/;
 /** The websites a sign-in or a task may use: 1 to 10 lower-case hostnames, copied. */
 export function allowedHostsOf(hosts) {
     if (!Array.isArray(hosts) || hosts.length < 1 || hosts.length > 10 || hosts.some(host => typeof host !== 'string' || !HOST.test(host))) {
-        throw new Error('Computer use needs 1 to 10 lower-case website hostnames in allowedHosts, such as vendorcentral.amazon.com.');
+        throw new IsomorphError('VALIDATION_FAILED', 'Computer use needs 1 to 10 lower-case website hostnames in allowedHosts, such as vendorcentral.amazon.com.');
     }
     return [...hosts];
 }

package/dist/computer-use-handoff-tool.d.ts

@@ -1,9 +1,9 @@
 import { type ComputerUseHandoffOptions, type ComputerUsePage, type ComputerUseWaiting } from './computer-use-handoff.js';
 import { type ComputerUseOptions } from './computer-use.js';
-export interface ComputerUseHandoffToolOptions extends ComputerUseHandoffOptions, ComputerUseOptions {
+export type ComputerUseHandoffToolOptions = ComputerUseHandoffOptions & ComputerUseOptions & {
     onInputRequired(input: ComputerUseWaiting, page: ComputerUsePage): Promise<void> | void;
     canResume(pauseId: string): Promise<boolean> | boolean;
-}
+};
 export declare function createComputerUseHandoffTools(options: ComputerUseHandoffToolOptions): {
     request_computer_input: ({
         deferLoading?: boolean;

package/dist/computer-use.d.ts

@@ -10,22 +10,9 @@ export interface ComputerUseDownload {
     size: number;
     blob: Blob;
 }
-export interface ComputerUseOptions {
+interface ComputerUseCommonOptions {
     /** App-authorized PDFs, at most five files and 2 MiB total. Never supplied by the model. */
     files?: readonly ComputerUseFile[];
-    /**
-     * The runtime secret a sign-in was saved under (finishSignIn's `saveAs`): the task starts signed in,
-     * and the refreshed session is saved back to it when the task is done. Never supplied by the model.
-     */
-    session?: string;
-    /** The websites a task with `secrets` and no `session` may use. */
-    allowedHosts?: readonly string[];
-    /**
-     * Values the computer types into a password field by name, at most 10; the model sees only the names.
-     * Never put a credential in the task text. A user ID, customer ID or email is not a secret: the
-     * computer refuses to type a secret into a visible field, so give those in the task text.
-     */
-    secrets?: Readonly<Record<string, string>>;
     /** The app's code gets each file the task downloaded, one at a time, when the task is done. Never seen by the model. */
     onDownload?(download: ComputerUseDownload): Promise<void> | void;
     /** The job's runId, or `<job name>/<scheduledAt>` for a scheduled job: one task record per job run. */
@@ -47,6 +34,38 @@ export interface ComputerUseOptions {
     pollIntervalMs?: number;
     now?: () => number;
 }
+/**
+ * Values the computer types into a password field by name, at most 10; the model sees only the names.
+ * Never put a credential in the task text. A user ID, customer ID or email is not a secret: the
+ * computer refuses to type a secret into a visible field, so give those in the task text.
+ */
+export type ComputerUseSecrets = Readonly<Record<string, string>>;
+/**
+ * How the task signs in, one of three shapes so the compiler refuses the others (`isomorph check` runs it):
+ * a saved `session`; `secrets` with the `allowedHosts` they may be typed into; or no sign-in, with or
+ * without `allowedHosts`. A session carries its own websites, so `session` with `allowedHosts` is refused,
+ * and `secrets` without `session` or `allowedHosts` has nowhere to be typed.
+ */
+export type ComputerUseSignIn = {
+    /**
+     * The runtime secret a sign-in was saved under (finishSignIn's `saveAs`): the task starts signed in,
+     * and the refreshed session is saved back to it when the task is done. Never supplied by the model.
+     */
+    session: string;
+    secrets?: ComputerUseSecrets;
+    allowedHosts?: never;
+} | {
+    secrets: ComputerUseSecrets;
+    /** The websites (1 to 10 lower-case hostnames) the browser may use and type the secrets into. */
+    allowedHosts: readonly string[];
+    session?: never;
+} | {
+    /** The websites (1 to 10 lower-case hostnames) the browser may use; none means any website. */
+    allowedHosts?: readonly string[];
+    secrets?: never;
+    session?: never;
+};
+export type ComputerUseOptions = ComputerUseCommonOptions & ComputerUseSignIn;
 export interface ComputerUseFinished {
     status: 'done' | 'failed';
     summary: string | null;
@@ -262,3 +281,4 @@ export declare function createComputerUseTool(options: ComputerUseOptions): ({
         task: string;
     }, ComputerUseResult, NoInfer<import("@ai-sdk/provider-utils").Context>>;
 });
+export {};

package/dist/computer-use.js

@@ -8,7 +8,10 @@ import { setTimeout as sleep } from 'node:timers/promises';
 import { jsonSchema, tool } from 'ai';
 import { allowedHostsOf, computerUseApi, refused } from './computer-use-api.js';
 import { runtimeSecretLocation, runtimeSecrets } from './secrets.js';
+import { IsomorphError } from './index.js';
 import { computerUseMessage, waitingInput } from './computer-use-handoff.js';
+// A wrong option is the app's code, not the computer: the job runner fails such a run without retrying it.
+const invalid = (message) => new IsomorphError('VALIDATION_FAILED', message);
 const HEARTBEAT_MS = 60_000;
 const DEFAULT_MAX_QUEUE_MS = 20 * 60_000;
 // Checks the API did not answer (a throttle, a 5xx, no connection) before the tool gives up: about a minute.
@@ -25,43 +28,41 @@ function queueNote(answer, waitedMs) {
 function secretsOf(secrets) {
     const entries = secrets && typeof secrets === 'object' && !Array.isArray(secrets) ? Object.entries(secrets) : [];
     if (entries.length < 1 || entries.length > 10)
-        throw new Error('Computer use secrets are 1 to 10 named values.');
+        throw invalid('Computer use secrets are 1 to 10 named values.');
     for (const [name, value] of entries) {
         if (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(name))
-            throw new Error(`${JSON.stringify(name)} is not a computer use secret name: up to 64 letters, digits, _ and -, starting with a letter.`);
+            throw invalid(`${JSON.stringify(name)} is not a computer use secret name: up to 64 letters, digits, _ and -, starting with a letter.`);
         if (typeof value !== 'string' || !value || Buffer.byteLength(value) > 4096)
-            throw new Error(`The computer use secret ${name} must be a non-empty string of at most 4096 bytes.`);
+            throw invalid(`The computer use secret ${name} must be a non-empty string of at most 4096 bytes.`);
     }
     return Object.fromEntries(entries);
 }
 export function createComputerUseTool(options) {
     if ('connectionId' in options)
-        throw new Error('connectionId is no longer supported; pass session, the runtime secret a sign-in was saved under.');
+        throw invalid('connectionId is no longer supported; pass session, the runtime secret a sign-in was saved under.');
     const files = options.files?.map(file => ({ ...file }));
     if (files) {
         const names = new Set();
         let total = 0;
         if (files.length > 5)
-            throw new Error("Computer use accepts at most five PDFs.");
+            throw invalid("Computer use accepts at most five PDFs.");
         for (const file of files) {
             if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,119}\.pdf$/.test(file.name) || names.has(file.name))
-                throw new Error("Computer use PDF names must be unique safe basenames.");
+                throw invalid("Computer use PDF names must be unique safe basenames.");
             if (file.contentType !== "application/pdf" || typeof file.dataBase64 !== "string" || file.dataBase64.length > Math.ceil(2 * 1024 * 1024 / 3) * 4)
-                throw new Error("Computer use needs base64 PDFs, at most 2 MiB total.");
+                throw invalid("Computer use needs base64 PDFs, at most 2 MiB total.");
             const bytes = Buffer.from(file.dataBase64, "base64");
             total += bytes.length;
             if (bytes.toString("base64") !== file.dataBase64 || bytes.subarray(0, 5).toString() !== "%PDF-" || total > 2 * 1024 * 1024)
-                throw new Error("Computer use needs PDFs, at most 2 MiB total.");
+                throw invalid("Computer use needs PDFs, at most 2 MiB total.");
             names.add(file.name);
         }
     }
     const { session } = options;
     if (session !== undefined && options.allowedHosts !== undefined)
-        throw new Error('Pass session or allowedHosts, not both: a saved sign-in carries its own websites.');
-    if (options.allowedHosts !== undefined && options.secrets === undefined)
-        throw new Error('allowedHosts is only for a task with secrets and no session.');
+        throw invalid('Pass session or allowedHosts, not both: a saved sign-in carries its own websites.');
     if (options.secrets !== undefined && session === undefined && options.allowedHosts === undefined)
-        throw new Error('A task with secrets needs session or allowedHosts: the websites the computer may type them into.');
+        throw invalid('A task with secrets needs session or allowedHosts: the websites the computer may type them into.');
     const allowedHosts = options.allowedHosts === undefined ? undefined : allowedHostsOf(options.allowedHosts);
     const secrets = options.secrets === undefined ? undefined : secretsOf(options.secrets);
     const transport = { env: options.env ?? process.env, fetch: options.fetch };
@@ -69,7 +70,7 @@ export function createComputerUseTool(options) {
         runtimeSecretLocation(session, transport.env);
     const api = computerUseApi(transport);
     if (!options.runKey)
-        throw new Error('createComputerUseTool needs the job run as runKey.');
+        throw invalid('createComputerUseTool needs the job run as runKey.');
     const now = options.now ?? Date.now;
     const savedSession = async (name) => {
         const stored = await runtimeSecrets.get(name, transport);

package/dist/index.d.ts

@@ -1788,6 +1788,8 @@ export interface JobRun {
     created_at: string;
     updated_at: string;
 }
+/** One row of `jobs.list`: a run's outcome without its input or result. */
+export type JobRunSummary = Pick<JobRun, 'id' | 'job' | 'status' | 'attempt' | 'max_attempts' | 'error' | 'note' | 'created_at' | 'updated_at'>;
 export type AiRole = 'system' | 'user' | 'assistant';
 export interface AiMessage {
     role: AiRole;
@@ -2054,6 +2056,11 @@ export declare function createClient(options?: ClientOptions): {
         }>;
         get: (id: string) => Promise<JobRun>;
         cancel: (id: string) => Promise<JobRun>;
+        /** A builder's view of the newest runs, every person's, one job's when named; at most 100. */
+        list: (options?: {
+            job?: string;
+            limit?: number;
+        }) => Promise<JobRunSummary[]>;
     };
     telemetry: {
         track: (name: string, properties?: Record<string, unknown>) => Promise<void>;

package/dist/index.js

@@ -817,6 +817,8 @@ export function createClient(options = {}) {
             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 }) }),
+            /** A builder's view of the newest runs, every person's, one job's when named; at most 100. */
+            list: (options = {}) => transport.json('/_harbour/actions/isomorph-jobs-list', { method: 'POST', body: JSON.stringify(options) }),
         },
         telemetry: {
             track: (name, properties = {}) => transport.json('/_harbour/telemetry', {

package/dist/runtime.d.ts

@@ -1,5 +1,5 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
-import { type IsomorphClient, type IsomorphUser, type JobRun } from './index.js';
+import { type IsomorphClient, type IsomorphUser, type JobRun, type JobRunSummary } from './index.js';
 import { type JobDefinition } from './jobs.js';
 import { type LocalGatewayOptions } from './local-gateway.js';
 export { JOBS_DIR, type JobContext } from './jobs.js';
@@ -10,6 +10,7 @@ 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 declare const LIST_RUNS_ACTION = "isomorph-jobs-list";
 export interface ActionContext {
     signal: AbortSignal;
     user: IsomorphUser;
@@ -59,6 +60,8 @@ export declare class Runs {
         id: string;
     }>;
     get(id: string, owner: string): Promise<JobRun | null>;
+    /** The newest runs of every person, for a builder: one job's when named. */
+    list(job: string | undefined, limit: number): Promise<JobRunSummary[]>;
     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>;

package/dist/runtime.js

@@ -81,6 +81,7 @@ 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';
+export const LIST_RUNS_ACTION = 'isomorph-jobs-list';
 const LOGICAL_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
 const MAX_BODY_BYTES = 1 << 20;
 const LEASE_MS = 5 * 60_000;
@@ -94,6 +95,10 @@ const TOKEN_REFRESH_MS = 60_000;
 const SESSION_MIN_VALIDITY_MS = 10 * 60_000;
 const JOB_SESSION_MIN_VALIDITY_MS = 15 * 60_000;
 const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_LIST_LIMIT = 20;
+const MAX_LIST_LIMIT = 100;
+const RUNS_PAGE_LIMIT = 50;
+const LIST_COLUMNS = 'id, job, status, attempt, max_attempts, error, note, created_at, updated_at';
 // 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.
 const DATA_PATH_WAIT_MS = 90_000;
@@ -167,6 +172,17 @@ function refuse(response, status, category, message, requestId) {
     answer(response, status, { error: { category, message } }, requestId);
 }
 const REFUSAL_STATUS = { AUTH_REQUIRED: 401, FORBIDDEN: 403, NOT_FOUND: 404, CONFLICT: 409, VALIDATION_FAILED: 400, RATE_LIMITED: 429, UNAVAILABLE: 503, INTERNAL: 500 };
+const escapeHtml = (value) => String(value ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+/** The builder's runs page: one plain table, no script, nothing a run's input or result could inject. */
+function runsPage(app, runs) {
+    const rows = runs.map((run) => `<tr><td><code>${escapeHtml(run.id)}</code></td><td>${escapeHtml(run.job)}</td><td>${escapeHtml(run.status)}</td><td>${run.attempt}/${run.max_attempts}</td><td>${escapeHtml(run.updated_at)}</td><td>${escapeHtml(run.note)}</td><td>${escapeHtml(run.error)}</td></tr>`).join('');
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Job runs: ${escapeHtml(app)}</title><style>body{font:14px system-ui,sans-serif;margin:24px}table{border-collapse:collapse}th,td{text-align:left;vertical-align:top;padding:4px 10px;border-bottom:1px solid #ddd}code{font-size:12px}</style></head><body><h1>Job runs of ${escapeHtml(app)}</h1><p>The newest ${runs.length} runs, every person's. A failed run shows its last error; a run that failed at once with <code>VALIDATION_FAILED</code> was the app's own code or setup.</p><table><thead><tr><th>Run</th><th>Job</th><th>Status</th><th>Attempt</th><th>Updated</th><th>Note</th><th>Error</th></tr></thead><tbody>${rows || '<tr><td colspan="7">No runs yet.</td></tr>'}</tbody></table></body></html>`;
+}
+/** True for an IsomorphError of that category, or any error carrying it as `code`; the job's module may hold its own SDK copy, so no instanceof. */
+function isValidationError(error) {
+    const { category, code } = (error ?? {});
+    return error instanceof Error && (category === 'VALIDATION_FAILED' || code === 'VALIDATION_FAILED');
+}
 /** An action's refusal for the browser: an IsomorphError, or any error carrying one of the SDK's categories as `code`. */
 function refusal(error) {
     if (error instanceof IsomorphError)
@@ -223,6 +239,14 @@ export class Runs {
         const { data } = await this.table().select('*').eq('id', id).eq('owner_subject', owner).maybeSingle();
         return data;
     }
+    /** The newest runs of every person, for a builder: one job's when named. */
+    async list(job, limit) {
+        let query = this.table().select(LIST_COLUMNS);
+        if (job)
+            query = query.eq('job', job);
+        const { data } = await query.order('created_at', { ascending: false }).limit(limit);
+        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') {
@@ -620,7 +644,11 @@ export class Runtime {
                 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) });
+                // A VALIDATION_FAILED error is the app's code or setup (a wrong computer use option, no runtime
+                // secrets here): the same again next time, so the run fails now with its attempts spent.
+                const invalid = isValidationError(error);
+                const message = error instanceof Error ? error.message : String(error);
+                await this.runs.finish(invalid ? { ...run, attempt: run.max_attempts } : run, { error: invalid ? `VALIDATION_FAILED: ${message}` : message });
             }
             return true;
         }
@@ -699,6 +727,13 @@ export class Runtime {
                 await this.acceptEventArrival(input);
                 return answer(response, 200, { data: { accepted: true } }, requestId);
             }
+            if (name === LIST_RUNS_ACTION && header(request, 'accept').toLowerCase().includes('text/html')) {
+                // The gateway's GET /_harbour/jobs: a builder's page of the newest runs, opened in the browser.
+                const runs = await this.reserved(name, { limit: RUNS_PAGE_LIMIT, ...(input && typeof input === 'object' ? input : {}) }, context);
+                response.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', ...(requestId ? { 'x-request-id': requestId } : {}) });
+                response.end(runsPage(app, runs));
+                return;
+            }
             if (name.startsWith(RESERVED_PREFIX))
                 return answer(response, 200, { data: await this.reserved(name, input, context) }, requestId);
             if (!this.inventory.actions.includes(name))
@@ -803,6 +838,14 @@ export class Runtime {
                     throw new IsomorphError('NOT_FOUND', 'no run of yours has that id', undefined, undefined, 404);
                 return run;
             }
+            case LIST_RUNS_ACTION: {
+                // Every person's runs, with each failure's error: a builder's view of the app, never a member's.
+                if (context.user.role !== 'builder')
+                    throw new IsomorphError('FORBIDDEN', 'only a builder of this app lists its runs', undefined, undefined, 403);
+                const job = typeof body.job === 'string' ? body.job : undefined;
+                const limit = typeof body.limit === 'number' && body.limit >= 1 ? Math.min(Math.floor(body.limit), MAX_LIST_LIMIT) : DEFAULT_LIST_LIMIT;
+                return this.runs.list(job, limit);
+            }
             default:
                 throw new IsomorphError('NOT_FOUND', `${name} is not an Isomorph runtime action`, undefined, undefined, 404);
         }

package/dist/secrets.d.ts

@@ -4,10 +4,15 @@ export interface RuntimeSecretsOptions {
     /** The waits before put tries again to create a secret whose deletion Secrets Manager is still finishing. */
     retryDelaysMs?: readonly number[];
 }
-/** Where a runtime secret lives; throws, before any call, for a bad name or an app without runtime secrets. */
+/**
+ * Where a runtime secret lives: a Secrets Manager secret in the app's cell, or a file under `isomorph dev`.
+ * Throws, before any call, for a bad name or an app without runtime secrets.
+ */
 export declare function runtimeSecretLocation(name: string, env?: NodeJS.ProcessEnv): {
     secretId: string;
     region: string;
+} | {
+    file: string;
 };
 export declare const runtimeSecrets: {
     /** Saves `value` under `name`, creating the secret the first time. */

package/dist/secrets.js

@@ -4,28 +4,65 @@
 // Secrets Manager secret under the app's own `<prefix><org>/<app>/runtime/`
 // path in its cell, which Provision names in ISOMORPH_RUNTIME_SECRETS_PREFIX.
 // The calls are signed as the runtime's own role, as the computer use tool's
-// are (ADR 0078); no AWS SDK client is added.
+// are (ADR 0078); no AWS SDK client is added. Under `isomorph dev` there is
+// no cell: the CLI names a folder in ISOMORPH_RUNTIME_SECRETS_DIR and each
+// secret is one private file there.
 import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { runtimeCredentials, signedJsonPost } from './aws.js';
+import { IsomorphError } from './index.js';
 const NAME = /^[A-Za-z0-9][A-Za-z0-9/_+=.@-]{0,199}$/;
 const MAX_VALUE_BYTES = 64 * 1024;
 // A deleted secret stays "marked for deletion" for some seconds: reads and writes are refused and its name
 // cannot be created again until Secrets Manager finishes deleting it.
 const DELETION_RETRY_DELAYS_MS = [1_000, 2_000, 4_000, 8_000, 10_000];
 const BEING_DELETED = /(marked|scheduled) for deletion/;
-/** Where a runtime secret lives; throws, before any call, for a bad name or an app without runtime secrets. */
+// A wrong name, value or environment is the app's code or setup, not the secret store: the job runner fails such a run without retrying it.
+const invalid = (message) => new IsomorphError('VALIDATION_FAILED', message);
+/**
+ * Where a runtime secret lives: a Secrets Manager secret in the app's cell, or a file under `isomorph dev`.
+ * Throws, before any call, for a bad name or an app without runtime secrets.
+ */
 export function runtimeSecretLocation(name, env = process.env) {
     if (typeof name !== 'string' || !NAME.test(name))
-        throw new Error(`${JSON.stringify(name)} is not a runtime secret name: up to 200 letters, digits and / _ + = . @ -, starting with a letter or digit.`);
+        throw invalid(`${JSON.stringify(name)} is not a runtime secret name: up to 200 letters, digits and / _ + = . @ -, starting with a letter or digit.`);
     const prefix = env.ISOMORPH_RUNTIME_SECRETS_PREFIX;
     const region = env.ISOMORPH_RUNTIME_SECRETS_REGION;
+    // The name may hold `/`; one flat file per name keeps the folder listable and a name from naming a path.
+    if (!prefix && env.ISOMORPH_RUNTIME_SECRETS_DIR)
+        return { file: join(env.ISOMORPH_RUNTIME_SECRETS_DIR, encodeURIComponent(name)) };
     if (!prefix || !region)
-        throw new Error('This app has no runtime secrets (ISOMORPH_RUNTIME_SECRETS_PREFIX and ISOMORPH_RUNTIME_SECRETS_REGION are not set).');
+        throw invalid('This app has no runtime secrets here: the deployed app has them in its cell (ISOMORPH_RUNTIME_SECRETS_PREFIX and ISOMORPH_RUNTIME_SECRETS_REGION), and isomorph dev keeps them in ISOMORPH_RUNTIME_SECRETS_DIR.');
     return { secretId: prefix + name, region };
 }
-function secretsManager(name, { env = process.env, fetch }) {
-    const { secretId, region } = runtimeSecretLocation(name, env);
+function checkValue(name, value) {
+    if (typeof value !== 'string' || Buffer.byteLength(value) > MAX_VALUE_BYTES)
+        throw invalid(`The runtime secret ${name} must be a string of at most 64 KB.`);
+}
+/** Under `isomorph dev`: one file per secret, readable by the builder only. */
+const localFiles = {
+    async put(file, value) {
+        await mkdir(join(file, '..'), { recursive: true, mode: 0o700 });
+        await writeFile(file, value, { mode: 0o600 });
+    },
+    async get(file) {
+        try {
+            return await readFile(file, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+    },
+    async delete(file) {
+        await rm(file, { force: true });
+    },
+};
+function secretsManager(name, { env = process.env, fetch }, location) {
+    const { secretId, region } = location;
     const transport = fetch ? { fetch } : {};
     const send = async (action, payload) => {
         const { status, body } = await signedJsonPost({ ...await runtimeCredentials(env, transport), region }, 'secretsmanager', `https://secretsmanager.${region}.amazonaws.com/`, payload, {
@@ -47,9 +84,11 @@ function secretsManager(name, { env = process.env, fetch }) {
 export const runtimeSecrets = {
     /** Saves `value` under `name`, creating the secret the first time. */
     async put(name, value, options = {}) {
-        const { secretId, send } = secretsManager(name, options);
-        if (typeof value !== 'string' || Buffer.byteLength(value) > MAX_VALUE_BYTES)
-            throw new Error(`The runtime secret ${name} must be a string of at most 64 KB.`);
+        const location = runtimeSecretLocation(name, options.env);
+        checkValue(name, value);
+        if ('file' in location)
+            return localFiles.put(location.file, value);
+        const { secretId, send } = secretsManager(name, options, location);
         // Secrets Manager wants each new version's idempotency token from a caller that is not an AWS SDK.
         const saved = await send('PutSecretValue', { SecretId: secretId, SecretString: value, ClientRequestToken: randomUUID() });
         if (saved.outcome === 'done')
@@ -66,7 +105,10 @@ export const runtimeSecrets = {
     },
     /** The value saved under `name`, or null when there is none or it is being deleted. */
     async get(name, options = {}) {
-        const { secretId, send } = secretsManager(name, options);
+        const location = runtimeSecretLocation(name, options.env);
+        if ('file' in location)
+            return localFiles.get(location.file);
+        const { secretId, send } = secretsManager(name, options, location);
         const read = await send('GetSecretValue', { SecretId: secretId });
         return read.outcome === 'done' ? read.body.SecretString ?? null : null;
     },
@@ -75,7 +117,10 @@ export const runtimeSecrets = {
      * deletion within seconds, and `put` waits for it before saving the same name again.
      */
     async delete(name, options = {}) {
-        const { secretId, send } = secretsManager(name, options);
+        const location = runtimeSecretLocation(name, options.env);
+        if ('file' in location)
+            return localFiles.delete(location.file);
+        const { secretId, send } = secretsManager(name, options, location);
         await send('DeleteSecret', { SecretId: secretId, ForceDeleteWithoutRecovery: true });
     },
 };

package/package.json

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