@isomorph.ai/app-sdk 2.1.0 → 2.3.0

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

@@ -91,14 +91,17 @@ export interface ComputerUseLiveConnection {
     };
     viewerPath: string;
 }
+export type ComputerUseTakeover = ComputerUsePause & {
+    connection?: ComputerUseLiveConnection;
+};
 export interface ComputerUseHandoffOptions extends ComputerUseTransport {
     runKey: string;
     authorize(): Promise<boolean> | boolean;
 }
 export declare function createComputerUseHandoff(options: ComputerUseHandoffOptions): {
-    requestTakeover(reason: string, requiredInput?: "login" | "human"): Promise<ComputerUsePause>;
+    requestTakeover(reason: string, requiredInput?: "login" | "human", pauseId?: string): Promise<ComputerUseTakeover>;
     view(pauseId: string): Promise<ComputerUsePage>;
-    live(pauseId: string): Promise<ComputerUseLiveConnection>;
+    live(_pauseId?: string): Promise<ComputerUseLiveConnection>;
     input(pauseId: string, action: ComputerUseInputAction): Promise<ComputerUseInputResult>;
     completeLogin(pauseId: string, input: ComputerUseLoginInput): Promise<{
         status: "login_queued";

package/dist/computer-use-handoff.js

@@ -32,7 +32,7 @@ export function waitingInput(answer) {
 }
 export function createComputerUseHandoff(options) {
     if (typeof options.runKey !== 'string' || !options.runKey || typeof options.authorize !== 'function')
-        throw new Error('Computer use handoff needs runKey and an authorize check for the current user.');
+        throw new Error('Computer use handoff needs runKey and an authorize check for the current app task.');
     const api = computerUseApi(options);
     const post = async (path, body = {}, privateInput = false) => {
         if (await options.authorize() !== true)
@@ -61,10 +61,10 @@ export function createComputerUseHandoff(options) {
         return { pauseId };
     };
     return {
-        requestTakeover(reason, requiredInput = 'human') {
+        requestTakeover(reason, requiredInput = 'human', pauseId) {
             if (!reason.trim() || !['login', 'human'].includes(requiredInput))
                 throw new Error('Takeover needs a reason and login or human input.');
-            return post('/tasks/takeover', { reason, requiredInput }).then(pauseOf);
+            return post('/tasks/takeover', { reason, requiredInput, ...(pauseId ? paused(pauseId) : {}) }).then(answer => ({ ...pauseOf(answer), ...(answer.connection ? { connection: answer.connection } : {}) }));
         },
         // The API answers 409 while the task is still pausing or after it resumed; `ready` is the only 200.
         async view(pauseId) {
@@ -73,8 +73,8 @@ export function createComputerUseHandoff(options) {
                 throw new Error('The computer use API returned an incomplete screen.');
             return { status: 'ready', screenshot: page.screenshot, url: page.url };
         },
-        live(pauseId) {
-            return post('/tasks/live', paused(pauseId));
+        live(_pauseId) {
+            return post('/tasks/live');
         },
         input(pauseId, action) {
             return post('/tasks/input', { ...paused(pauseId), action });

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;
@@ -2018,7 +2035,9 @@ export declare function createClient(options?: ClientOptions): {
         watch: <T = Record<string, unknown>>(build: () => QueryBuilder<T, any>, onResult: (result: WatchResult) => void, options?: WatchOptions) => (() => void);
     };
     computerView: {
-        url(action: string, taskId: string): string;
+        url(action: string, taskId: string, options?: {
+            mode?: "watch" | "control";
+        }): string;
     };
     files: {
         createUpload: (input: {

package/dist/index.js

@@ -774,10 +774,13 @@ export function createClient(options = {}) {
             },
         },
         computerView: {
-            url(action, taskId) {
+            url(action, taskId, options = {}) {
                 if (!/^[A-Za-z][A-Za-z0-9_-]{0,127}$/.test(action) || !/^[A-Za-z0-9_-]{1,128}$/.test(taskId))
                     throw new IsomorphError('VALIDATION_FAILED', 'Computer view needs an action and task ID.');
-                return `${transport.baseUrl}/_harbour/computer-view/${encodeURIComponent(action)}/${encodeURIComponent(taskId)}/`;
+                const mode = options.mode ?? 'watch';
+                if (!['watch', 'control'].includes(mode))
+                    throw new IsomorphError('VALIDATION_FAILED', 'Computer view needs watch or control mode.');
+                return `${transport.baseUrl}/_harbour/computer-view/${encodeURIComponent(action)}/${encodeURIComponent(taskId)}/${mode}/`;
             },
         },
         files: {

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 = [];
@@ -826,7 +828,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.1.0",
+  "version": "2.3.0",
   "type": "module",
   "repository": {
     "type": "git",