@isomorph.ai/app-sdk 2.2.0 → 2.3.1

package/dist/aws.js

@@ -67,7 +67,11 @@ export async function runtimeCredentials(env = process.env, { fetch: fetcher = f
         throw new Error('the runtime has no AWS credentials (AWS_ACCESS_KEY_ID, or AWS_ROLE_ARN with AWS_WEB_IDENTITY_TOKEN_FILE)');
     if (webIdentity?.roleArn === roleArn && webIdentity.expiresAt - now() > 5 * 60_000)
         return webIdentity.credentials;
-    const region = env.AWS_REGION || env.AWS_DEFAULT_REGION || 'us-east-1';
+    // STS is called in the runtime's own region, which the runtime always has (Lambda and the kit chart set
+    // it). No default: a cell outside us-east-1 under a region-pinning policy must never fall back there.
+    const region = env.AWS_REGION || env.AWS_DEFAULT_REGION;
+    if (!region)
+        throw new Error('the runtime has no AWS region (AWS_REGION) for its STS exchange');
     // The token is read on each exchange: the kubelet rotates the file.
     const body = new URLSearchParams({ Action: 'AssumeRoleWithWebIdentity', Version: '2011-06-15', RoleArn: roleArn, RoleSessionName: env.AWS_ROLE_SESSION_NAME || 'isomorph-runtime', WebIdentityToken: (await readFile(tokenFile, 'utf8')).trim() });
     const response = await fetcher(`https://sts.${region}.amazonaws.com/`, { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: body.toString(), signal: AbortSignal.timeout(10_000) });

package/dist/computer-use-api.js

@@ -10,6 +10,8 @@ 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).');
+    // The computer use API is Harbour's own, in Harbour's region: this default names a Harbour-owned endpoint,
+    // not the cell's region, and stays until the call moves behind the app gateway (ADR 0078).
     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);

package/dist/index.d.ts

@@ -36,6 +36,23 @@ export interface IsomorphUser {
      */
     role: IsomorphUserRole;
     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.
+     */
+    kind?: 'person' | 'service';
+}
+/**
+ * `export const expose = { description, input }` on an action, beside
+ * `export const trusted = true`: the action may be called from outside the
+ * app by a service credential or an MCP client. `description` is read by
+ * people and agents; `input` is a JSON Schema object literal the platform
+ * validates the request body against. Literal only.
+ */
+export interface ActionExposure {
+    description: string;
+    input: Record<string, unknown>;
 }
 export interface IsomorphResult<T> {
     data: T;

package/dist/jobs.d.ts

@@ -1,3 +1,4 @@
+import type { ActionExposure } from './index.js';
 export declare const JOBS_DIR = "jobs";
 export interface EmailArrivalTrigger {
     type: 'email.arrived';
@@ -25,6 +26,8 @@ export interface JobDefinition {
     schedule?: string;
     trigger?: EventTrigger;
 }
+/** The action's `export const expose = { description, input }`, read without importing it: undefined when the module has none, does not parse, or declares anything but a literal object of that shape. */
+export declare function actionExposure(file: string): Promise<ActionExposure | undefined>;
 export declare function eventTrigger(value: unknown): EventTrigger;
 export interface JobContext {
     scheduledAt: string;

package/dist/jobs.js

@@ -8,25 +8,55 @@ export const JOBS_DIR = 'jobs';
 const LOGICAL_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
 export const FILE_MIME_TYPES = ['application/pdf', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 'image/png', 'image/jpeg'];
 export const providerFileId = (value) => typeof value === 'string' && /^[A-Za-z0-9!._,=-]{1,256}$/.test(value);
-function literalObject(node) {
+function literalObject(node, what = 'trigger') {
     const value = node;
     if (value?.type === 'Literal')
         return value.value;
     if (value?.type === 'ArrayExpression')
-        return value.elements.map(literalObject);
+        return value.elements.map(element => literalObject(element, what));
     if (value?.type !== 'ObjectExpression')
-        throw new Error('trigger must be a literal object');
+        throw new Error(`${what} must be a literal object`);
     const result = {};
     for (const property of value.properties ?? []) {
         if (property.type !== 'Property' || property.computed || property.kind !== 'init' || property.method)
-            throw new Error('trigger must be a literal object');
+            throw new Error(`${what} must be a literal object`);
         const key = property.key.name ?? property.key.value;
         if (typeof key !== 'string' || Object.hasOwn(result, key))
-            throw new Error('trigger contains an invalid or repeated field');
-        Object.defineProperty(result, key, { value: literalObject(property.value), enumerable: true });
+            throw new Error(`${what} contains an invalid or repeated field`);
+        Object.defineProperty(result, key, { value: literalObject(property.value, what), enumerable: true });
     }
     return result;
 }
+const plainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** The action's `export const expose = { description, input }`, read without importing it: undefined when the module has none, does not parse, or declares anything but a literal object of that shape. */
+export async function actionExposure(file) {
+    let statements;
+    try {
+        statements = parseModule(await readFile(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    for (const statement of statements) {
+        if (statement.type !== 'ExportNamedDeclaration' || statement.declaration?.type !== 'VariableDeclaration' || statement.declaration.kind !== 'const')
+            continue;
+        for (const declaration of statement.declaration.declarations) {
+            if (declaration.id.type !== 'Identifier' || declaration.id.name !== 'expose')
+                continue;
+            let value;
+            try {
+                value = literalObject(declaration.init, 'expose');
+            }
+            catch {
+                return undefined;
+            }
+            if (!plainObject(value) || Object.keys(value).some(key => key !== 'description' && key !== 'input') || typeof value.description !== 'string' || !plainObject(value.input))
+                return undefined;
+            return { description: value.description, input: value.input };
+        }
+    }
+    return undefined;
+}
 export function eventTrigger(value) {
     if (value?.type === 'file.created') {
         const t = value;

package/dist/runtime.d.ts

@@ -1,5 +1,5 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
-import { type IsomorphClient, type IsomorphUser, type JobRun, type JobRunSummary } from './index.js';
+import { type ActionExposure, 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';
@@ -37,6 +37,8 @@ export interface RuntimeInventory {
     actions: string[];
     /** The actions whose module says `export const trusted = true`: they act as the app on behalf of the caller. */
     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>;
     jobs: JobDefinition[];
 }
 /** Every `actions/<name>.ts` and `jobs/<name>.ts` the app carries, by logical name. */

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, discoverJobs, exportsTrue, invokeJob, loadHandler, JOBS_DIR } from './jobs.js';
+import { FILE_MIME_TYPES, providerFileId, actionExposure, discoverJobs, exportsTrue, invokeJob, loadHandler, JOBS_DIR } from './jobs.js';
 import { LocalGateway } from './local-gateway.js';
 export { JOBS_DIR } from './jobs.js';
 const actionIdentity = new AsyncLocalStorage();
@@ -118,8 +118,10 @@ export async function discover(root) {
     };
     const actions = (await list(ACTIONS_DIR)).filter((name) => !name.startsWith(RESERVED_PREFIX));
     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 jobs = await discoverJobs(root);
-    return { actions, trusted: actions.filter((_, index) => trusted[index]), jobs };
+    return { actions, trusted: actions.filter((_, index) => trusted[index]), exposed, jobs };
 }
 // ---- Cron ------------------------------------------------------------------
 /** One field of a five-field cron expression: numbers, `*`, lists, ranges and steps, no names. */
@@ -313,7 +315,7 @@ export class Runs {
 }
 export class Runtime {
     options;
-    inventory = { actions: [], trusted: [], jobs: [] };
+    inventory = { actions: [], trusted: [], exposed: {}, jobs: [] };
     localGateway;
     running = new Set();
     timers = [];
@@ -683,8 +685,13 @@ export class Runtime {
         const abort = () => controller.abort();
         response.once('close', abort);
         const directory = header(request, 'X-Harbour-Verified-Directory');
+        const userId = header(request, 'X-Harbour-Verified-User-ID');
         const user = {
-            id: header(request, 'X-Harbour-Verified-User-ID'),
+            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' } : {}),
             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')),
@@ -826,7 +833,7 @@ export class Runtime {
         const owner = context.user.id;
         switch (name) {
             case PING_ACTION: {
-                const answer = { ok: true, mode: this.options.mode, actions: this.inventory.actions, trusted: this.inventory.trusted, jobs: this.inventory.jobs.map((job) => job.name) };
+                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) };
                 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.2.0",
+  "version": "2.3.1",
   "type": "module",
   "repository": {
     "type": "git",