@isomorph.ai/app-sdk 1.35.1 → 1.36.0

package/README.md

@@ -387,13 +387,13 @@ App code declares exact HTTPS pages and named click/fill selectors reviewed for
 
 ## Computer use tool
 
-A job's agent can hand one browser task, writes included, to Harbour's computer use agent. Use it only in `jobs/*.ts`. Install the optional peer `ai`.
+A job's agent can hand one browser task, writes included, to the computer use service. Use it only in `jobs/*.ts`. Install the optional peer `ai`.
 
 ```ts
 import { createComputerUseTool } from '@isomorph.ai/app-sdk/dist/computer-use.js';
 // Inside a job handler:
 const computerUse = createComputerUseTool({ runKey: ctx.runId ?? `my-job/${ctx.scheduledAt}`, progress: ctx.progress, cancelled: ctx.cancelled });
-// Add { computerUse } to generateText's tools. It returns { status: 'done' | 'failed', summary }.
+// Add { computerUse } to generateText's tools. It returns { status: 'done' | 'failed', summary, finalUrl }.
 ```
 
 - The tool calls the task API at `ISOMORPH_COMPUTER_USE_URL` (region `ISOMORPH_COMPUTER_USE_REGION`, default `us-east-1`); Provision sets both when the cell has the API. Each request is signed with SigV4 (`execute-api`) as the runtime's own role: the Lambda environment's credentials, or on a cluster pod its ServiceAccount role through STS `AssumeRoleWithWebIdentity`.
@@ -401,9 +401,61 @@ const computerUse = createComputerUseTool({ runKey: ctx.runId ?? `my-job/${ctx.s
 - It calls `progress(step count, note)` on every new step and at least once a minute, so the job's lease does not run out.
 - When `cancelled()` turns true it sends `POST /tasks/cancel` once and keeps checking until the task has `failed`.
 - One task record per `runKey`: a retried job run sends the same key and gets the queued, running or finished task back. Only a failed task starts a new attempt.
-- For a website account the owner has connected in the app, pass its opaque `connectionId` in the options. The SDK sends it only when starting the task, outside the model's tool arguments. The computer-use service verifies that the signed app role owns that connection; omit it for ordinary browser tasks.
+- `finalUrl` is the page the browser ended on. A website's sign-in page there means a saved sign-in has expired: ask the person to sign in again.
 
-(1.25.0; data plane ADR 0078)
+Options the app passes, never the model:
+
+- `files`: PDFs the task may upload, at most five and 2 MiB in all.
+- `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; 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".
+- `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.
+
+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; data plane ADR 0078, ADR 0090)
+
+## Browser sign-in for computer use
+
+A person signs in to a website once on a short-lived computer the app shows as screenshots; the app keeps the browser session as a runtime secret and passes its name to later computer use tasks as `session`. Each call is short, so these run from actions as well as jobs.
+
+```ts
+import { startSignIn, showSignIn, sendSignInInput, finishSignIn, cancelSignIn } from '@isomorph.ai/app-sdk/dist/computer-use-sign-in.js';
+// actions/connect-start.ts
+const handle = await startSignIn({ allowedHosts: ['vendorcentral.amazon.com'] });
+// actions/connect-page.ts: poll until ready, then show the screenshot
+const page = await showSignIn(handle); // { status: 'starting' } or { status: 'ready', screenshot, url }
+// actions/connect-input.ts: what the person did on the screenshot
+await sendSignInInput(handle, { op: 'click', x: 640, y: 400 });
+// actions/connect-finish.ts: once the person is signed in
+await finishSignIn(handle, { saveAs: `vendor-central/${ctx.user.id}` }); // { url }
+```
+
+- `startSignIn` starts a computer that may open only `allowedHosts` and returns an opaque handle for the calls that follow; the computer answers only this app's role and stops after 30 minutes.
+- `showSignIn` gives `{ status: 'starting' }` until the browser is up, then `{ status: 'ready', screenshot, url }`: a base64 PNG of the 1280×800 screen and the page's address.
+- `sendSignInInput` takes `{ op: 'click', x, y }` (screen pixels), `{ op: 'typeText', value }` (up to 512 characters), `{ op: 'pressKey', key }` (such as `Enter` or `Tab`) or `{ op: 'scroll', direction: 'up' | 'down' }`.
+- `finishSignIn` saves the session (cookies and site storage of the allowed websites, at most 60 KB) as the runtime secret `saveAs`, stops the computer and returns the page it was on. App code never holds the cookies.
+- `cancelSignIn` stops the computer and keeps nothing.
+- Deleting the sign-in is `runtimeSecrets.delete(name)`. The app decides whose sign-in it is, when it has expired and when to delete it.
+
+(1.36.0; data plane ADR 0090)
+
+## Runtime secrets
+
+An app can save its own secrets while it runs, such as a saved sign-in, an OAuth token a person granted or a key a person typed into the app's settings. They work in actions and jobs.
+
+```ts
+import { runtimeSecrets } from '@isomorph.ai/app-sdk/dist/secrets.js';
+await runtimeSecrets.put(`supplier-key/${ctx.user.id}`, key); // creates it the first time
+const key = await runtimeSecrets.get(`supplier-key/${ctx.user.id}`); // string, or null when there is none
+await runtimeSecrets.delete(`supplier-key/${ctx.user.id}`);
+```
+
+- Names match `^[A-Za-z0-9][A-Za-z0-9/_+=.@-]{0,199}$`; values are strings up to 64 KB.
+- 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 at once, with no recovery window, so the same name can be saved again straight away.
+- Each one costs $0.40 a month while it exists.
+
+(1.36.0; data plane ADR 0090)
 
 ## Running and rollout
 

package/dist/aws.d.ts

@@ -27,10 +27,14 @@ export declare function runtimeCredentials(env?: NodeJS.ProcessEnv, { fetch: fet
     fetch?: typeof fetch;
     now?: () => number;
 }): Promise<Credentials>;
-/** A JSON POST signed for `service` in `aws.region`, answered with its status and JSON body. */
-export declare function signedJsonPost(aws: AwsEnvironment, service: string, target: string, payload: unknown, { fetch: fetcher, signingDate }?: {
+/**
+ * A JSON POST signed for `service` in `aws.region`, answered with its status and JSON body. `headers`
+ * (lower-case names) are added to the signed request and may replace its `content-type`.
+ */
+export declare function signedJsonPost(aws: AwsEnvironment, service: string, target: string, payload: unknown, { fetch: fetcher, signingDate, headers: extra }?: {
     fetch?: typeof fetch;
     signingDate?: Date;
+    headers?: Record<string, string>;
 }): Promise<{
     status: number;
     body: unknown;

package/dist/aws.js

@@ -79,13 +79,16 @@ export async function runtimeCredentials(env = process.env, { fetch: fetcher = f
     webIdentity = { roleArn, credentials: { accessKeyId, secretAccessKey, sessionToken }, expiresAt: expiration };
     return webIdentity.credentials;
 }
-/** A JSON POST signed for `service` in `aws.region`, answered with its status and JSON body. */
-export async function signedJsonPost(aws, service, target, payload, { fetch: fetcher = fetch, signingDate = new Date() } = {}) {
+/**
+ * A JSON POST signed for `service` in `aws.region`, answered with its status and JSON body. `headers`
+ * (lower-case names) are added to the signed request and may replace its `content-type`.
+ */
+export async function signedJsonPost(aws, service, target, payload, { fetch: fetcher = fetch, signingDate = new Date(), headers: extra = {} } = {}) {
     const url = new URL(target);
     const body = JSON.stringify(payload);
     const request = new HttpRequest({
         method: 'POST', protocol: url.protocol, hostname: url.hostname, ...(url.port ? { port: Number(url.port) } : {}), path: url.pathname,
-        headers: { host: url.host, 'content-type': 'application/json' }, body,
+        headers: { host: url.host, 'content-type': 'application/json', ...extra }, body,
     });
     const { host: _host, ...headers } = (await signer(aws, service).sign(request, { signingDate })).headers;
     const response = await fetcher(url.href, { method: 'POST', headers, body, signal: AbortSignal.timeout(30_000) });

package/dist/computer-use-api.d.ts

@@ -0,0 +1,15 @@
+export interface ComputerUseTransport {
+    env?: NodeJS.ProcessEnv;
+    fetch?: typeof fetch;
+}
+export declare function refused(path: string, status: number, body: unknown): Error;
+export declare function computerUseApi({ env, fetch }?: ComputerUseTransport): {
+    call: (path: string, body: Record<string, unknown>) => Promise<{
+        status: number;
+        body: unknown;
+    }>;
+    /** A call the API must answer with 200; its body. */
+    post<T>(path: string, body: Record<string, unknown>): Promise<T>;
+};
+/** The websites a sign-in or a task may use: 1 to 10 lower-case hostnames, copied. */
+export declare function allowedHostsOf(hosts: unknown): string[];

package/dist/computer-use-api.js

@@ -0,0 +1,33 @@
+// 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';
+export function refused(path, status, body) {
+    const error = body?.error;
+    return new Error(`The computer use API refused ${path} (${status}${typeof error === 'string' ? `: ${error}` : ''}).`);
+}
+export function computerUseApi({ env = process.env, fetch } = {}) {
+    const base = env.ISOMORPH_COMPUTER_USE_URL?.replace(/\/+$/, '');
+    if (!base)
+        throw new Error('This app has no computer use API (ISOMORPH_COMPUTER_USE_URL is not set).');
+    const region = env.ISOMORPH_COMPUTER_USE_REGION || 'us-east-1';
+    const transport = fetch ? { fetch } : {};
+    const call = async (path, body) => signedJsonPost({ ...await runtimeCredentials(env, transport), region }, 'execute-api', `${base}${path}`, body, transport);
+    return {
+        call,
+        /** A call the API must answer with 200; its body. */
+        async post(path, body) {
+            const answer = await call(path, body);
+            if (answer.status !== 200)
+                throw refused(path, answer.status, answer.body);
+            return answer.body;
+        },
+    };
+}
+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.');
+    }
+    return [...hosts];
+}

package/dist/computer-use-sign-in.d.ts

@@ -0,0 +1,38 @@
+import { type ComputerUseTransport } from './computer-use-api.js';
+/** What the person did on the screenshot: the sign-in computer's input actions. */
+export type SignInAction = {
+    op: 'click';
+    x: number;
+    y: number;
+} | {
+    op: 'typeText';
+    value: string;
+} | {
+    op: 'pressKey';
+    key: string;
+} | {
+    op: 'scroll';
+    direction: 'up' | 'down';
+};
+/** The computer's screen: `starting` until its browser is up, then a base64 PNG and the page's address. */
+export type SignInPage = {
+    status: 'starting';
+} | {
+    status: 'ready';
+    screenshot: string;
+    url: string;
+};
+/** Starts a sign-in computer limited to `allowedHosts`; the handle names it in the calls that follow. */
+export declare function startSignIn({ allowedHosts, ...transport }: {
+    allowedHosts: readonly string[];
+} & ComputerUseTransport): Promise<string>;
+export declare function showSignIn(handle: string, transport?: ComputerUseTransport): Promise<SignInPage>;
+export declare function sendSignInInput(handle: string, action: SignInAction, transport?: ComputerUseTransport): Promise<void>;
+/** Saves the signed-in browser session as the runtime secret `saveAs`, stops the computer and returns the page it was on. */
+export declare function finishSignIn(handle: string, { saveAs, ...transport }: {
+    saveAs: string;
+} & ComputerUseTransport): Promise<{
+    url: string;
+}>;
+/** Stops the computer and keeps nothing. */
+export declare function cancelSignIn(handle: string, transport?: ComputerUseTransport): Promise<void>;

package/dist/computer-use-sign-in.js

@@ -0,0 +1,43 @@
+// Browser sign-in for computer use (data plane ADR 0090): a person signs in
+// to a website on a short-lived computer the app shows as screenshots, and the
+// app saves the browser session as one of its runtime secrets for later
+// computer use tasks. Each call is short, so these run in actions as well as
+// jobs. The computer answers only the app role that started it.
+import { allowedHostsOf, computerUseApi } from './computer-use-api.js';
+import { runtimeSecretLocation, runtimeSecrets } from './secrets.js';
+function computerOf(handle) {
+    let computer;
+    try {
+        computer = JSON.parse(Buffer.from(String(handle), 'base64url').toString('utf8'));
+    }
+    catch {
+        computer = undefined;
+    }
+    if (typeof computer?.computerId !== 'string' || typeof computer.endpoint !== 'string')
+        throw new Error('This is not a sign-in handle from startSignIn.');
+    return { computerId: computer.computerId, endpoint: computer.endpoint };
+}
+/** Starts a sign-in computer limited to `allowedHosts`; the handle names it in the calls that follow. */
+export async function startSignIn({ allowedHosts, ...transport }) {
+    const hosts = allowedHostsOf(allowedHosts);
+    const { computerId, endpoint } = await computerUseApi(transport).post('/computers/start', { allowedHosts: hosts });
+    return Buffer.from(JSON.stringify({ computerId, endpoint })).toString('base64url');
+}
+export async function showSignIn(handle, transport = {}) {
+    return computerUseApi(transport).post('/computers/page', computerOf(handle));
+}
+export async function sendSignInInput(handle, action, transport = {}) {
+    await computerUseApi(transport).post('/computers/input', { ...computerOf(handle), action });
+}
+/** Saves the signed-in browser session as the runtime secret `saveAs`, stops the computer and returns the page it was on. */
+export async function finishSignIn(handle, { saveAs, ...transport }) {
+    const computer = computerOf(handle);
+    runtimeSecretLocation(saveAs, transport.env);
+    const { session, url } = await computerUseApi(transport).post('/computers/finish', computer);
+    await runtimeSecrets.put(saveAs, JSON.stringify(session), transport);
+    return { url };
+}
+/** Stops the computer and keeps nothing. */
+export async function cancelSignIn(handle, transport = {}) {
+    await computerUseApi(transport).post('/computers/stop', computerOf(handle));
+}

package/dist/computer-use.d.ts

@@ -6,8 +6,18 @@ export interface ComputerUseFile {
 export interface ComputerUseOptions {
     /** App-authorized PDFs, at most five files and 2 MiB total. Never supplied by the model. */
     files?: readonly ComputerUseFile[];
-    /** Owner-authorized browser session reference. Never supplied by the model. */
-    connectionId?: string;
+    /**
+     * 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.
+     */
+    secrets?: Readonly<Record<string, string>>;
     /** The job's runId, or `<job name>/<scheduledAt>` for a scheduled job: one task record per job run. */
     runKey: string;
     /** The job's progress: called on each new step and at least once a minute, which renews the job's lease. */
@@ -23,6 +33,8 @@ export interface ComputerUseOptions {
 export interface ComputerUseResult {
     status: 'done' | 'failed';
     summary: string | null;
+    /** The page the browser was on when the task ended; a sign-in page there means the saved sign-in has expired. */
+    finalUrl: string | null;
 }
 export declare function createComputerUseTool(options: ComputerUseOptions): ({
     deferLoading?: boolean;

package/dist/computer-use.js

@@ -1,17 +1,30 @@
 // The computer use tool: hands one browser task to Harbour's computer use
 // agent (CUA) and waits for its result. Calls go to the CUA's task API, signed
-// with SigV4 as the runtime's own role (ADR 0078).
+// with SigV4 as the runtime's own role (ADR 0078). A saved sign-in is a runtime
+// secret: its session goes with the task and the refreshed one is saved back
+// to it (ADR 0090).
 import { setTimeout as sleep } from 'node:timers/promises';
 import { jsonSchema, tool } from 'ai';
-import { runtimeCredentials, signedJsonPost } from './aws.js';
+import { allowedHostsOf, computerUseApi, refused } from './computer-use-api.js';
+import { runtimeSecretLocation, runtimeSecrets } from './secrets.js';
 const HEARTBEAT_MS = 60_000;
 // Checks the API did not answer (a throttle, a 5xx, no connection) before the tool gives up: about a minute.
 const MAX_MISSED_CHECKS = 12;
-export function createComputerUseTool(options) {
-    const connectionId = options.connectionId;
-    if (connectionId !== undefined && (typeof connectionId !== 'string' || !/^[a-f0-9]{32}$/.test(connectionId))) {
-        throw new Error('Computer use needs a valid browser connection ID.');
+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.');
+    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.`);
+        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.`);
     }
+    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.');
     const files = options.files?.map(file => ({ ...file }));
     if (files) {
         const names = new Set();
@@ -30,27 +43,41 @@ export function createComputerUseTool(options) {
             names.add(file.name);
         }
     }
-    const env = options.env ?? process.env;
-    const base = env.ISOMORPH_COMPUTER_USE_URL?.replace(/\/+$/, '');
-    if (!base)
-        throw new Error('This app has no computer use API (ISOMORPH_COMPUTER_USE_URL is not set).');
+    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.');
+    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.');
+    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 };
+    if (session !== undefined)
+        runtimeSecretLocation(session, transport.env);
+    const api = computerUseApi(transport);
     if (!options.runKey)
         throw new Error('createComputerUseTool needs the job run as runKey.');
-    const region = env.ISOMORPH_COMPUTER_USE_REGION || 'us-east-1';
     const now = options.now ?? Date.now;
-    const transport = options.fetch ? { fetch: options.fetch } : {};
-    const call = async (path, body) => signedJsonPost({ ...await runtimeCredentials(env, transport), region }, 'execute-api', `${base}${path}`, body, transport);
-    const refused = (path, status, body) => {
-        const error = body?.error;
-        return new Error(`The computer use API refused ${path} (${status}${typeof error === 'string' ? `: ${error}` : ''}).`);
+    const savedSession = async (name) => {
+        const stored = await runtimeSecrets.get(name, transport);
+        if (stored === null)
+            throw new Error(`No saved sign-in named ${name}.`);
+        try {
+            return JSON.parse(stored);
+        }
+        catch {
+            throw new Error(`The saved sign-in named ${name} is not a browser session.`);
+        }
     };
     return tool({
         description: 'Do one task in a web browser, such as filling in and submitting a form on a website. Describe the whole task in plain words, with the website address and any details it needs. Waits until the task ends and returns its status and a summary.',
         inputSchema: jsonSchema({ type: 'object', properties: { task: { type: 'string', minLength: 1 } }, required: ['task'], additionalProperties: false }),
         execute: async ({ task }) => {
-            const started = await call('/tasks', { run_key: options.runKey, task, ...(files?.length ? { files } : {}), ...(connectionId ? { connectionId } : {}) });
-            if (started.status !== 200)
-                throw refused('/tasks', started.status, started.body);
+            await api.post('/tasks', {
+                run_key: options.runKey, task, ...(files?.length ? { files } : {}), ...(session === undefined ? {} : { session: await savedSession(session) }),
+                ...(allowedHosts ? { allowedHosts } : {}), ...(secrets ? { secrets } : {}),
+            });
             await options.progress(0, 'Computer use task started.');
             let reported = now();
             let steps = 0;
@@ -58,14 +85,12 @@ export function createComputerUseTool(options) {
             let missed = 0;
             for (;;) {
                 if (!cancelSent && await options.cancelled()) {
-                    const cancel = await call('/tasks/cancel', { run_key: options.runKey });
-                    if (cancel.status !== 200)
-                        throw refused('/tasks/cancel', cancel.status, cancel.body);
+                    await api.post('/tasks/cancel', { run_key: options.runKey });
                     cancelSent = true;
                 }
                 let check;
                 try {
-                    check = await call('/tasks/check', { run_key: options.runKey });
+                    check = await api.call('/tasks/check', { run_key: options.runKey });
                 }
                 catch {
                     check = undefined;
@@ -73,8 +98,11 @@ export function createComputerUseTool(options) {
                 if (check?.status === 200) {
                     missed = 0;
                     const answer = check.body;
-                    if (answer.status === 'done' || answer.status === 'failed')
-                        return { status: answer.status, summary: answer.summary ?? null };
+                    if (answer.status === 'done' || answer.status === 'failed') {
+                        if (answer.status === 'done' && session !== undefined && answer.session)
+                            await runtimeSecrets.put(session, JSON.stringify(answer.session), transport);
+                        return { status: answer.status, summary: answer.summary ?? null, finalUrl: answer.final_url ?? null };
+                    }
                     if (answer.steps > steps || now() - reported >= HEARTBEAT_MS) {
                         steps = Math.max(steps, answer.steps);
                         await options.progress(Math.min(steps, 99), answer.last_step ? `Computer use step ${steps}: ${answer.last_step}` : `Computer use task ${answer.status}.`);

package/dist/secrets.d.ts

@@ -0,0 +1,17 @@
+export interface RuntimeSecretsOptions {
+    env?: NodeJS.ProcessEnv;
+    fetch?: typeof fetch;
+}
+/** Where a runtime secret lives; 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;
+};
+export declare const runtimeSecrets: {
+    /** Saves `value` under `name`, creating the secret the first time. */
+    put(name: string, value: string, options?: RuntimeSecretsOptions): Promise<void>;
+    /** The value saved under `name`, or null when there is none. */
+    get(name: string, options?: RuntimeSecretsOptions): Promise<string | null>;
+    /** Deletes the secret at once, so the same name can be saved again straight away; a missing one is already deleted. */
+    delete(name: string, options?: RuntimeSecretsOptions): Promise<void>;
+};

package/dist/secrets.js

@@ -0,0 +1,62 @@
+// App runtime secrets (data plane ADR 0090): secrets an app saves, reads and
+// deletes while it runs, such as a saved browser sign-in, an OAuth token a
+// user granted or a key a user typed into the app's settings. Each is one
+// 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.
+import { randomUUID } from 'node:crypto';
+import { runtimeCredentials, signedJsonPost } from './aws.js';
+const NAME = /^[A-Za-z0-9][A-Za-z0-9/_+=.@-]{0,199}$/;
+const MAX_VALUE_BYTES = 64 * 1024;
+/** Where a runtime secret lives; 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.`);
+    const prefix = env.ISOMORPH_RUNTIME_SECRETS_PREFIX;
+    const region = env.ISOMORPH_RUNTIME_SECRETS_REGION;
+    if (!prefix || !region)
+        throw new Error('This app has no runtime secrets (ISOMORPH_RUNTIME_SECRETS_PREFIX and ISOMORPH_RUNTIME_SECRETS_REGION are not set).');
+    return { secretId: prefix + name, region };
+}
+function secretsManager(name, { env = process.env, fetch }) {
+    const { secretId, region } = runtimeSecretLocation(name, env);
+    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, {
+            ...transport, headers: { 'content-type': 'application/x-amz-json-1.1', 'x-amz-target': `secretsmanager.${action}` },
+        });
+        if (status === 200)
+            return { missing: false, body };
+        const answer = body;
+        const type = typeof answer?.__type === 'string' ? answer.__type.replace(/^.*#/, '').replace(/:.*$/, '') : '';
+        if (type === 'ResourceNotFoundException')
+            return { missing: true, body };
+        const message = answer?.message ?? answer?.Message;
+        throw new Error(`Secrets Manager refused ${action} on the runtime secret ${name} (${status}${type ? ` ${type}` : ''}${typeof message === 'string' ? `: ${message}` : ''}).`);
+    };
+    return { secretId, send };
+}
+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.`);
+        // 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.missing)
+            await send('CreateSecret', { Name: secretId, SecretString: value, ClientRequestToken: randomUUID() });
+    },
+    /** The value saved under `name`, or null when there is none. */
+    async get(name, options = {}) {
+        const { secretId, send } = secretsManager(name, options);
+        const read = await send('GetSecretValue', { SecretId: secretId });
+        return read.missing ? null : read.body.SecretString ?? null;
+    },
+    /** Deletes the secret at once, so the same name can be saved again straight away; a missing one is already deleted. */
+    async delete(name, options = {}) {
+        const { secretId, send } = secretsManager(name, options);
+        await send('DeleteSecret', { SecretId: secretId, ForceDeleteWithoutRecovery: true });
+    },
+};

package/package.json

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