@isomorph.ai/app-sdk 1.7.0 → 1.9.0

package/README.md

@@ -36,6 +36,93 @@ Replace the connection/resource with the app's existing approved integration. To
 
 For images call `generateImage({model: gateway.image(process.env.ISOMORPH_AI_IMAGE_MODEL_ALIAS!), prompt: 'A blue notebook'})`. Editing uses `prompt: {text: 'Make it red', images: [inputBytes]}` only when `isomorph ai models` advertises edit. Reuse app files upload/signed reads for authorized input and output storage; respect existing transfer/action limits and never return credentials.
 
+## Company integrations
+
+`isomorph.integrations.execute(connection, request)` is one method over a closed
+set of operations; the operation fixes whose identity it runs under, and the
+contract's bounds are checked in the client before any request is sent (the
+same sentence the platform answers with). The connection, operation, resource
+and `mode` are literals in the call: the kit gate derives
+`.isomorph/integrations.json` from them. `isomorph dev` without `--real`
+answers every operation from a local fixture.
+
+Slack. A history, post, edit or delete runs as the app or as the signed-in
+person (`mode`, the one IT approved for the app); a DM and a user lookup run
+as the app only, against the fixed `workspace` resource. A post or DM needs a
+fresh UUID per explicit Send press.
+
+```ts
+// A thread reply in Slack mrkdwn
+const page = await isomorph.integrations.execute('company-slack', {
+  operation: 'slack.channel.history', resource: 'team-updates', input: { limit: 100 },
+});
+await isomorph.integrations.execute('company-slack', {
+  operation: 'slack.message.post', resource: 'team-updates',
+  input: { text: '*Done* — see <https://example.com/report|the report>', format: 'mrkdwn', threadId: page.messages[0].id },
+  idempotencyKey: crypto.randomUUID(), mode: 'app',
+});
+
+// Paged history: hasMore and nextCursor say when and how to read the next (older) page
+const older = await isomorph.integrations.execute('company-slack', {
+  operation: 'slack.channel.history', resource: 'team-updates', input: { limit: 100, cursor: page.nextCursor },
+});
+
+// Edit or delete a message the app posted (its ts is the messageId)
+const posted = await isomorph.integrations.execute('company-slack', {
+  operation: 'slack.message.post', resource: 'team-updates', input: { text: 'Deploy starting' }, idempotencyKey: crypto.randomUUID(), mode: 'app',
+});
+await isomorph.integrations.execute('company-slack', {
+  operation: 'slack.message.update', resource: 'team-updates', input: { messageId: posted.messageId, text: 'Deploy finished' }, mode: 'app',
+});
+await isomorph.integrations.execute('company-slack', {
+  operation: 'slack.message.delete', resource: 'team-updates', input: { messageId: posted.messageId }, mode: 'app',
+});
+
+// A direct message by email (1 to 8 people; several open one group DM) and a user lookup
+await isomorph.integrations.execute('company-slack', {
+  operation: 'slack.dm.send', resource: 'workspace', input: { to: ['jane@example.com'], text: 'Your review is due today.' },
+  idempotencyKey: crypto.randomUUID(),
+});
+const { userId } = await isomorph.integrations.execute('company-slack', {
+  operation: 'slack.user.lookup', resource: 'workspace', input: { email: 'jane@example.com' },
+});
+```
+
+Gmail runs as the signed-in person after their consent, on the fixed `inbox`
+resource.
+
+```ts
+// Search, then read a whole thread
+const found = await isomorph.integrations.execute('company-gmail', {
+  operation: 'gmail.thread.list', resource: 'inbox', input: { q: 'from:jane newer_than:7d', limit: 50 },
+});
+const thread = await isomorph.integrations.execute('company-gmail', {
+  operation: 'gmail.thread.read', resource: 'inbox', input: { threadId: found.threads[0].id },
+});
+// found.nextPageToken, when hasMore, is the next read's pageToken
+
+// An attachment: a message or thread read names them (id, filename, mimeType, size); this fetches the bytes
+const file = thread.emails[0].attachments?.[0];
+if (file) {
+  const { dataBase64 } = await isomorph.integrations.execute('company-gmail', {
+    operation: 'gmail.attachment.read', resource: 'inbox', input: { messageId: thread.emails[0].id, attachmentId: file.id },
+  });
+}
+
+// An HTML send: text stays the plain-text alternative; up to 5 attachments of 2 MiB each
+await isomorph.integrations.execute('company-gmail', {
+  operation: 'gmail.message.send', resource: 'inbox',
+  input: {
+    to: ['jane@example.com'], subject: 'Weekly report', text: 'The report is attached.',
+    html: '<p>The report is <b>attached</b>.</p>',
+    attachments: [{ filename: 'report.csv', contentType: 'text/csv', dataBase64: csvBase64 }],
+  },
+  idempotencyKey: crypto.randomUUID(),
+});
+```
+
+(1.8.0; contracts 0.71.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.
@@ -113,3 +200,25 @@ export default async function approve(input: { id: string }, ctx: { user: { grou
 ```
 
 (1.6.0)
+
+## Live progress from an action
+
+An action reports steps with `ctx.progress(step)` (a string or a small JSON
+object); a page that passes `onProgress` gets each one as it happens, then the
+result or the error exactly as a plain `invoke` gives it. No table, no polling.
+
+```ts
+// actions/research.ts
+export default async function research(input: { url: string }, ctx: { progress(step: string): void }) {
+  ctx.progress(`Opened ${input.url}`);
+  // ...
+  return result;
+}
+
+// page
+await isomorph.actions.invoke('research', input, { onProgress: (step) => setSteps((steps) => [...steps, step]) });
+```
+
+Without `onProgress` the call is unchanged and `ctx.progress` does nothing. At
+most 256 steps of up to 1 KiB each reach the page; further steps are dropped.
+The action still has the 300 s action budget. (Unreleased)

package/dist/index.d.ts

@@ -24,30 +24,94 @@ export interface IsomorphResult<T> {
     data: T;
     count?: number;
 }
+/** How Slack renders a message's `text`: plain text, or Slack mrkdwn (`*bold*`, `<url|label>`, `<@U123>`); plain when absent. */
+export type SlackTextFormat = 'plain' | 'mrkdwn';
+/**
+ * Which of the modes IT approved for this app a declared-mode Slack operation runs under: `app` (the company's
+ * Slack app, under the IT-approved per-app name and footer) or `user` (the signed-in person, after their consent).
+ * Leave it out when the app is approved for one mode; an app approved for both must say (MODE_REQUIRED), and a
+ * mode IT has not approved is refused with MODE_NOT_GRANTED — never served under the other mode.
+ */
+export type SlackIdentityMode = 'app' | 'user';
+/** Reads a channel's newest messages as the signed-in person (or as the app, when declared so); pages backwards with `cursor`. */
 export interface SlackChannelHistoryRequest {
     operation: 'slack.channel.history';
     resource: string;
     input?: {
-        /** How many newest messages to read: an integer from 1 to 15 (the platform's ceiling); default 15. */
+        /** How many messages to read: an integer from 1 to 100 (the platform's ceiling); default 15. */
         limit?: number;
+        /** The `nextCursor` of the previous page; leave it out to read the newest page. */
+        cursor?: string;
+        /** Only messages after this Slack ts (a message id). */
+        oldest?: string;
+        /** Only messages before this Slack ts (a message id). */
+        latest?: string;
     };
+    mode?: SlackIdentityMode;
 }
+/** Posts one message to a channel, as the app or as the signed-in person; `threadId` makes it a thread reply. */
 export interface SlackMessagePostRequest {
     operation: 'slack.message.post';
     resource: string;
     input: {
-        /** Plain text, 1 to 4000 characters. Posted as the app (under the IT-approved per-app name) or as the signed-in person (their consent), the same text either way. */
+        /** The body, 1 to 4000 characters; plain text unless `format` is `mrkdwn`. Posted as the app (under the IT-approved per-app name) or as the signed-in person (their consent), the same text either way. */
         text: string;
+        /** The Slack ts of the message this one replies to (a history message id), so the post lands in that thread. */
+        threadId?: string;
+        format?: SlackTextFormat;
     };
     /** A fresh UUID per explicit Send press, reused only to retry that press. */
     idempotencyKey: string;
-    /**
-     * Which of the modes IT approved for this app the post runs under: `app` (the company's Slack app, under the
-     * IT-approved per-app name and footer) or `user` (the signed-in person, after their consent). Leave it out when
-     * the app is approved for one mode; an app approved for both must say (MODE_REQUIRED), and a mode IT has not
-     * approved is refused with MODE_NOT_GRANTED — never served under the other mode.
-     */
-    mode?: 'app' | 'user';
+    mode?: SlackIdentityMode;
+}
+/** Edits a message the app (or the signed-in person, in user mode) posted; the whole `text` is replaced. */
+export interface SlackMessageUpdateRequest {
+    operation: 'slack.message.update';
+    resource: string;
+    input: {
+        /** The Slack ts a post or history result named as `messageId`. */
+        messageId: string;
+        /** The new body, 1 to 4000 characters. */
+        text: string;
+        format?: SlackTextFormat;
+    };
+    mode?: SlackIdentityMode;
+}
+/** Deletes a message the app (or the signed-in person, in user mode) posted. */
+export interface SlackMessageDeleteRequest {
+    operation: 'slack.message.delete';
+    resource: string;
+    input: {
+        /** The Slack ts a post or history result named as `messageId`. */
+        messageId: string;
+    };
+    mode?: SlackIdentityMode;
+}
+/**
+ * Sends a direct message as the company's Slack app to workspace members named by email (always app mode; the
+ * resource is the fixed `workspace` alias). Several recipients open one group DM.
+ */
+export interface SlackDmSendRequest {
+    operation: 'slack.dm.send';
+    resource: string;
+    input: {
+        /** 1 to 8 email addresses of workspace members, no repeats. */
+        to: string[];
+        /** The body, 1 to 4000 characters. */
+        text: string;
+        format?: SlackTextFormat;
+    };
+    /** A fresh UUID per explicit Send press, reused only to retry that press. */
+    idempotencyKey: string;
+}
+/** Resolves a workspace member's email to their Slack user id, as the app (the resource is the fixed `workspace` alias). */
+export interface SlackUserLookupRequest {
+    operation: 'slack.user.lookup';
+    resource: string;
+    input: {
+        /** The member's email address. */
+        email: string;
+    };
 }
 /**
  * One condition on a warehouse read; a read's conditions are AND-ed. `isNull`/`isNotNull` take no value, `in`/`notIn`
@@ -93,12 +157,28 @@ export interface WarehouseViewReadRequest {
         limit?: number;
     };
 }
-/** Gmail runs as the signed-in person after their consent. Resources are approved mailbox aliases. */
+/** Gmail runs as the signed-in person after their consent. Resources are approved mailbox aliases (`inbox`). */
 export interface GmailThreadListRequest {
     operation: 'gmail.thread.list';
     resource: string;
     input?: {
+        /** Newest matching threads, 1 to 50; default 15. */
         limit?: number;
+        /** A Gmail search query in the search-box syntax, e.g. `from:jane newer_than:7d`, 1 to 256 characters. */
+        q?: string;
+        /** 1 to 5 labels a thread must carry (all of them); `['INBOX']` when absent. */
+        labelIds?: string[];
+        /** The `nextPageToken` of the previous page; leave it out to read the first page. */
+        pageToken?: string;
+    };
+}
+/** Reads every message of one thread, oldest first, as the signed-in person. */
+export interface GmailThreadReadRequest {
+    operation: 'gmail.thread.read';
+    resource: string;
+    input: {
+        /** The thread id a `gmail.thread.list` result named. */
+        threadId: string;
     };
 }
 export interface GmailMessageReadRequest {
@@ -108,24 +188,47 @@ export interface GmailMessageReadRequest {
         messageId: string;
     };
 }
+/** Reads one attachment's bytes (at most 2 MiB) as the signed-in person; the ids come from a message or thread read. */
+export interface GmailAttachmentReadRequest {
+    operation: 'gmail.attachment.read';
+    resource: string;
+    input: {
+        messageId: string;
+        /** The `id` of an entry in the message's `attachments`. */
+        attachmentId: string;
+    };
+}
+/** One file to attach to a send, carried inline as base64: at most 2 MiB of bytes (2,796,203 base64 characters). */
+export interface GmailAttachmentInput {
+    /** The name the recipient sees, 1 to 255 characters. */
+    filename: string;
+    /** The MIME type, e.g. `application/pdf`. */
+    contentType: string;
+    /** The file bytes, standard base64. */
+    dataBase64: string;
+}
 export interface GmailMessageSendRequest {
     operation: 'gmail.message.send';
     resource: string;
     input: {
-        /** 1 to 50 email addresses per recipient list. */
+        /** 1 to 50 email addresses per recipient list (at most 50 across to, cc and bcc). */
         to: string[];
         cc?: string[];
         bcc?: string[];
         /** 1 to 256 characters. */
         subject: string;
-        /** Plain text, 1 to 4000 characters. Attachments and HTML are not supported. */
+        /** Plain text, 1 to 4000 characters; the plain-text alternative when `html` is sent too. */
         text: string;
+        /** An HTML body sent beside `text`, at most 64 KiB. */
+        html?: string;
+        /** 1 to 5 files, each at most 2 MiB. */
+        attachments?: GmailAttachmentInput[];
         replyToMessageId?: string;
     };
     /** A fresh UUID per authorized Send action, reused only to retry that action. */
     idempotencyKey: string;
 }
-export type IntegrationRequest = SlackChannelHistoryRequest | SlackMessagePostRequest | WarehouseViewReadRequest | GmailThreadListRequest | GmailMessageReadRequest | GmailMessageSendRequest;
+export type IntegrationRequest = SlackChannelHistoryRequest | SlackMessagePostRequest | SlackMessageUpdateRequest | SlackMessageDeleteRequest | SlackDmSendRequest | SlackUserLookupRequest | WarehouseViewReadRequest | GmailThreadListRequest | GmailThreadReadRequest | GmailMessageReadRequest | GmailAttachmentReadRequest | GmailMessageSendRequest;
 export type IntegrationOperation = IntegrationRequest['operation'];
 export interface SlackMessage {
     id: string;
@@ -140,10 +243,23 @@ export interface SlackMessage {
 export interface SlackChannelHistoryResult {
     messages: SlackMessage[];
     hasMore: boolean;
+    /** The cursor of the next (older) page, present only when `hasMore`; pass it as the next read's `cursor`. */
+    nextCursor?: string;
 }
+/** The Slack ts of the message posted, edited or deleted. */
 export interface SlackMessagePostResult {
     messageId: string;
 }
+export interface SlackDmSendResult {
+    messageId: string;
+    /** The DM channel the message went to. */
+    channelId: string;
+}
+export interface SlackUserLookupResult {
+    userId: string;
+    /** The member's display name, or real name when they set none; may be empty. */
+    displayName: string;
+}
 export interface WarehouseViewReadResult {
     rows: Array<Record<string, unknown>>;
     /** True when more rows matched than `limit`: the rows are incomplete, so never total or average them in code. */
@@ -160,6 +276,16 @@ export interface GmailThreadSummary {
 export interface GmailThreadListResult {
     threads: GmailThreadSummary[];
     hasMore: boolean;
+    /** The token of the next page, present only when `hasMore`; pass it as the next read's `pageToken`. */
+    nextPageToken?: string;
+}
+/** One attachment of a message, named without its bytes; `gmail.attachment.read` fetches them by `id`. */
+export interface GmailAttachment {
+    id: string;
+    filename: string;
+    mimeType: string;
+    /** Bytes. */
+    size: number;
 }
 export interface GmailMessageReadResult {
     id: string;
@@ -168,14 +294,27 @@ export interface GmailMessageReadResult {
     from: string;
     to: string;
     date: string;
+    /** The plain text with HTML stripped, cut at 16 KiB with `truncated` set. */
     text: string;
     truncated: boolean;
+    attachments?: GmailAttachment[];
+}
+/** Every message of the thread, oldest first, each in the `gmail.message.read` shape. */
+export interface GmailThreadReadResult {
+    id: string;
+    emails: GmailMessageReadResult[];
+}
+export interface GmailAttachmentReadResult {
+    filename: string;
+    mimeType: string;
+    size: number;
+    dataBase64: string;
 }
 export interface GmailMessageSendResult {
     messageId: string;
     threadId: string;
 }
-export type IntegrationResult<R extends IntegrationRequest> = R extends SlackChannelHistoryRequest ? SlackChannelHistoryResult : R extends SlackMessagePostRequest ? SlackMessagePostResult : R extends WarehouseViewReadRequest ? WarehouseViewReadResult : R extends GmailThreadListRequest ? GmailThreadListResult : R extends GmailMessageReadRequest ? GmailMessageReadResult : R extends GmailMessageSendRequest ? GmailMessageSendResult : never;
+export type IntegrationResult<R extends IntegrationRequest> = R extends SlackChannelHistoryRequest ? SlackChannelHistoryResult : R extends SlackMessagePostRequest | SlackMessageUpdateRequest | SlackMessageDeleteRequest ? SlackMessagePostResult : R extends SlackDmSendRequest ? SlackDmSendResult : R extends SlackUserLookupRequest ? SlackUserLookupResult : R extends WarehouseViewReadRequest ? WarehouseViewReadResult : R extends GmailThreadListRequest ? GmailThreadListResult : R extends GmailThreadReadRequest ? GmailThreadReadResult : R extends GmailMessageReadRequest ? GmailMessageReadResult : R extends GmailAttachmentReadRequest ? GmailAttachmentReadResult : R extends GmailMessageSendRequest ? GmailMessageSendResult : never;
 export type IntegrationConnectResult = {
     status: 'connected';
     accountLabel: string;
@@ -302,7 +441,7 @@ declare class Transport {
     private readonly identity;
     renewal: IdentityRenewal | undefined;
     constructor(options: ClientOptions, onUnauthorized?: (() => void) | undefined);
-    json<T>(path: string, init?: RequestInit): Promise<T>;
+    json<T>(path: string, init?: RequestInit, onProgress?: (step: never) => void): Promise<T>;
     private request;
 }
 export declare class QueryBuilder<T = Record<string, unknown>, Result = T[]> implements PromiseLike<IsomorphResult<Result>> {
@@ -393,7 +532,10 @@ export declare function createClient(options?: ClientOptions): {
         channel: (name: string) => RealtimeChannelBuilder;
     };
     actions: {
-        invoke: <T = unknown>(name: string, input: unknown) => Promise<T>;
+        /** `onProgress` receives each `ctx.progress(step)` the action reports while it runs. */
+        invoke: <T = unknown, P = string>(name: string, input: unknown, options?: {
+            onProgress?: (step: P) => void;
+        }) => Promise<T>;
     };
     jobs: {
         enqueue: (name: string, input?: unknown) => Promise<{

package/dist/index.js

@@ -28,6 +28,13 @@ function warehouseReadProblem({ columns, aggregates }) {
         return { field: 'columns', message: 'columns may use "*" only as the sole entry' };
     return undefined;
 }
+// The operations whose request carries a `mode`, and the only ones it is sent
+// for (every other operation's mode is fixed, and the platform refuses the
+// field there). The key type is derived from the union, so adding or removing
+// `mode` on a request without changing this table does not compile.
+const declaredModeOperations = {
+    'slack.channel.history': true, 'slack.message.post': true, 'slack.message.update': true, 'slack.message.delete': true,
+};
 /** The AI reason code carried by an error, when it is a governed-AI refusal. */
 export function aiErrorCode(error) {
     const code = error instanceof IsomorphError ? error.details?.code : undefined;
@@ -177,18 +184,21 @@ class Transport {
         this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
         this.identity = options.identity;
     }
-    json(path, init = {}) {
-        return this.request(path, init, renewableOnUnauthorized(path) || (this.separateApiHost && path === IDENTITY_PATH));
+    json(path, init = {}, onProgress) {
+        return this.request(path, init, renewableOnUnauthorized(path) || (this.separateApiHost && path === IDENTITY_PATH), onProgress);
     }
-    async request(path, init, renewOnUnauthorized) {
+    async request(path, init, renewOnUnauthorized, onProgress) {
         const sentAt = this.renewal?.renewals() ?? 0;
         // (headers with an undefined value are removed so a multipart body can
         // clear the JSON default and let the browser set its own boundary)
         const response = await this.fetch(`${this.baseUrl}${path}`, {
             credentials: 'same-origin',
             ...init,
-            headers: mergeHeaders({ 'content-type': 'application/json' }, runnerIdentityHeaders(this.identity), init.headers),
+            headers: mergeHeaders({ 'content-type': 'application/json' }, runnerIdentityHeaders(this.identity), init.headers, onProgress ? { accept: PROGRESS_MEDIA_TYPE } : undefined),
         });
+        if (onProgress && response.ok && response.body && response.headers.get('content-type')?.startsWith(PROGRESS_MEDIA_TYPE)) {
+            return readProgress(response, onProgress);
+        }
         const body = await response.json().catch(() => undefined);
         if (!response.ok) {
             if (response.status === 401) {
@@ -204,7 +214,7 @@ class Transport {
                     if (renewed && path === IDENTITY_PATH)
                         return renewed;
                     if (renewed !== false)
-                        return this.request(path, init, false);
+                        return this.request(path, init, false, onProgress);
                 }
                 // Not before the resend: a page listening to identity.onChange would
                 // otherwise see the user flicker to null while the edge was healing.
@@ -215,6 +225,44 @@ class Transport {
         return (body && Object.prototype.hasOwnProperty.call(body, 'data') ? body.data : body);
     }
 }
+// An action invoked with onProgress asks for its progress stream: one JSON
+// line per ctx.progress step, then the answer — `{data}` or `{error, status}`,
+// the refusal a plain call would have thrown. A runtime that does not stream
+// answers plain JSON and the call reads it as before.
+const PROGRESS_MEDIA_TYPE = 'application/x-ndjson';
+async function readProgress(response, onProgress) {
+    const requestId = response.headers.get('x-request-id') ?? undefined;
+    const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+    let pending = '';
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            const lines = (pending + (value ?? '')).split('\n');
+            pending = done ? '' : lines.pop();
+            for (const line of lines.filter((text) => text.trim())) {
+                let event;
+                try {
+                    event = JSON.parse(line);
+                }
+                catch {
+                    throw new IsomorphError('INTERNAL', 'The action answered with an unreadable progress line.', requestId);
+                }
+                if ('progress' in event) {
+                    onProgress(event.progress);
+                    continue;
+                }
+                if (event.error)
+                    throw new IsomorphError(event.error.category ?? 'INTERNAL', event.error.message ?? 'The action failed.', requestId, event.error.details, event.status);
+                return event.data;
+            }
+            if (done)
+                throw new IsomorphError('UNAVAILABLE', 'The action stopped before it answered.', requestId);
+        }
+    }
+    finally {
+        void reader.cancel().catch(() => undefined);
+    }
+}
 function applicationBaseUrl() {
     if (typeof location === 'undefined') {
         // No browser: this module is running under the retained-check runner in
@@ -631,24 +679,24 @@ export function createClient(options = {}) {
             channel: (name) => new RealtimeChannelBuilder(name, connectRealtime),
         },
         actions: {
-            invoke: (name, input) => {
+            /** `onProgress` receives each `ctx.progress(step)` the action reports while it runs. */
+            invoke: (name, input, options = {}) => {
+                const path = `/_harbour/actions/${encodeURIComponent(name)}`;
                 // supabase-js accepts FormData/Blob bodies and sends them as
                 // multipart; JSON.stringify(FormData) silently becomes "{}", which
                 // turned a verbatim-ported multipart action into a guaranteed 500.
                 // Pass binary bodies through and let the browser set the boundary.
                 if (typeof FormData !== 'undefined' && input instanceof FormData) {
-                    return transport.json(`/_harbour/actions/${encodeURIComponent(name)}`, {
+                    return transport.json(path, {
                         method: 'POST', body: input, headers: { 'content-type': undefined },
-                    });
+                    }, options.onProgress);
                 }
                 if (typeof Blob !== 'undefined' && input instanceof Blob) {
-                    return transport.json(`/_harbour/actions/${encodeURIComponent(name)}`, {
+                    return transport.json(path, {
                         method: 'POST', body: input, headers: { 'content-type': input.type || 'application/octet-stream' },
-                    });
+                    }, options.onProgress);
                 }
-                return transport.json(`/_harbour/actions/${encodeURIComponent(name)}`, {
-                    method: 'POST', body: JSON.stringify(input),
-                });
+                return transport.json(path, { method: 'POST', body: JSON.stringify(input) }, options.onProgress);
             },
         },
         jobs: {
@@ -676,12 +724,11 @@ export function createClient(options = {}) {
                 if (problem) {
                     return Promise.reject(new IsomorphError('VALIDATION_FAILED', problem.message, undefined, { code: 'INPUT_INVALID', field: problem.field }));
                 }
-                // Exactly the contract's fields go on the wire: `mode` is one of them
-                // for a Slack post only (which approved mode it runs under); an
-                // `identity` or any other stray field is not sent.
+                // Exactly the contract's fields go on the wire: `mode` only for the
+                // declaredModeOperations; an `identity` or any other stray field is not sent.
                 const { operation, resource, input, idempotencyKey, mode } = request;
                 return transport.json('/_harbour/integrations/execute', {
-                    method: 'POST', body: JSON.stringify({ connection, operation, resource, ...(input !== undefined ? { input } : {}), ...(idempotencyKey !== undefined ? { idempotencyKey } : {}), ...(operation === 'slack.message.post' && mode !== undefined ? { mode } : {}) }),
+                    method: 'POST', body: JSON.stringify({ connection, operation, resource, ...(input !== undefined ? { input } : {}), ...(idempotencyKey !== undefined ? { idempotencyKey } : {}), ...(operation in declaredModeOperations && mode !== undefined ? { mode } : {}) }),
                 });
             },
             // In a browser the consent returns the person to this page (without its

package/dist/integration-execute-input-rules.d.ts

@@ -28,6 +28,7 @@ export type IntegrationExecuteInputFieldRule = {
         maxLength?: number;
         pattern?: string;
     };
+    default?: readonly string[];
 } | {
     kind: 'enum';
     required: boolean;
@@ -64,9 +65,27 @@ export declare const IntegrationExecuteInputRules: {
                 readonly kind: "integer";
                 readonly required: false;
                 readonly minimum: 1;
-                readonly maximum: 15;
+                readonly maximum: 100;
                 readonly default: 15;
             };
+            readonly cursor: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 1;
+                readonly maxLength: 256;
+            };
+            readonly oldest: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 1;
+                readonly maxLength: 64;
+            };
+            readonly latest: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 1;
+                readonly maxLength: 64;
+            };
         };
     };
     readonly "slack.message.post": {
@@ -78,6 +97,93 @@ export declare const IntegrationExecuteInputRules: {
                 readonly minLength: 1;
                 readonly maxLength: 4000;
             };
+            readonly threadId: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9._-]{1,64}$";
+            };
+            readonly format: {
+                readonly kind: "enum";
+                readonly required: false;
+                readonly values: readonly ["plain", "mrkdwn"];
+                readonly default: "plain";
+            };
+        };
+    };
+    readonly "slack.message.update": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly messageId: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9._-]{1,64}$";
+            };
+            readonly text: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 1;
+                readonly maxLength: 4000;
+            };
+            readonly format: {
+                readonly kind: "enum";
+                readonly required: false;
+                readonly values: readonly ["plain", "mrkdwn"];
+                readonly default: "plain";
+            };
+        };
+    };
+    readonly "slack.message.delete": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly messageId: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9._-]{1,64}$";
+            };
+        };
+    };
+    readonly "slack.dm.send": {
+        readonly idempotencyKey: true;
+        readonly fields: {
+            readonly to: {
+                readonly kind: "string[]";
+                readonly required: true;
+                readonly minItems: 1;
+                readonly maxItems: 8;
+                readonly uniqueItems: true;
+                readonly item: {
+                    readonly minLength: 3;
+                    readonly maxLength: 254;
+                    readonly pattern: "^[^\\s@<>,;\"]+@[^\\s@<>,;\"]+\\.[^\\s@<>,;\"]+$";
+                };
+            };
+            readonly text: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 1;
+                readonly maxLength: 4000;
+            };
+            readonly format: {
+                readonly kind: "enum";
+                readonly required: false;
+                readonly values: readonly ["plain", "mrkdwn"];
+                readonly default: "plain";
+            };
+        };
+    };
+    readonly "slack.user.lookup": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly email: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 3;
+                readonly maxLength: 254;
+                readonly pattern: "^[^\\s@<>,;\"]+@[^\\s@<>,;\"]+\\.[^\\s@<>,;\"]+$";
+            };
         };
     };
     readonly "gmail.thread.list": {
@@ -87,9 +193,44 @@ export declare const IntegrationExecuteInputRules: {
                 readonly kind: "integer";
                 readonly required: false;
                 readonly minimum: 1;
-                readonly maximum: 15;
+                readonly maximum: 50;
                 readonly default: 15;
             };
+            readonly q: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 1;
+                readonly maxLength: 256;
+            };
+            readonly labelIds: {
+                readonly kind: "string[]";
+                readonly required: false;
+                readonly minItems: 1;
+                readonly maxItems: 5;
+                readonly uniqueItems: true;
+                readonly item: {
+                    readonly minLength: 1;
+                    readonly maxLength: 64;
+                };
+                readonly default: readonly ["INBOX"];
+            };
+            readonly pageToken: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 1;
+                readonly maxLength: 256;
+            };
+        };
+    };
+    readonly "gmail.thread.read": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly threadId: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9._-]{1,64}$";
+            };
         };
     };
     readonly "gmail.message.read": {
@@ -99,7 +240,7 @@ export declare const IntegrationExecuteInputRules: {
                 readonly kind: "string";
                 readonly required: true;
                 readonly minLength: 0;
-                readonly pattern: "^[A-Za-z0-9_-]{1,64}$";
+                readonly pattern: "^[A-Za-z0-9._-]{1,64}$";
             };
         };
     };
@@ -154,6 +295,38 @@ export declare const IntegrationExecuteInputRules: {
                 readonly minLength: 1;
                 readonly maxLength: 4000;
             };
+            readonly html: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 1;
+                readonly maxLength: 65536;
+            };
+            readonly attachments: {
+                readonly kind: "object[]";
+                readonly required: false;
+                readonly minItems: 1;
+                readonly maxItems: 5;
+                readonly fields: {
+                    readonly filename: {
+                        readonly kind: "string";
+                        readonly required: true;
+                        readonly minLength: 1;
+                        readonly maxLength: 255;
+                    };
+                    readonly contentType: {
+                        readonly kind: "string";
+                        readonly required: true;
+                        readonly minLength: 1;
+                        readonly maxLength: 128;
+                    };
+                    readonly dataBase64: {
+                        readonly kind: "string";
+                        readonly required: true;
+                        readonly minLength: 1;
+                        readonly maxLength: 2796203;
+                    };
+                };
+            };
             readonly replyToMessageId: {
                 readonly kind: "string";
                 readonly required: false;
@@ -162,6 +335,23 @@ export declare const IntegrationExecuteInputRules: {
             };
         };
     };
+    readonly "gmail.attachment.read": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly messageId: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9._-]{1,64}$";
+            };
+            readonly attachmentId: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 1;
+                readonly maxLength: 512;
+            };
+        };
+    };
     readonly "warehouse.view.read": {
         readonly idempotencyKey: false;
         readonly fields: {

package/dist/integration-execute-input-rules.js

@@ -4,25 +4,67 @@ export const IntegrationExecuteInputRules = {
     "slack.channel.history": {
         idempotencyKey: false,
         fields: {
-            limit: { kind: "integer", required: false, minimum: 1, maximum: 15, default: 15 },
+            limit: { kind: "integer", required: false, minimum: 1, maximum: 100, default: 15 },
+            cursor: { kind: "string", required: false, minLength: 1, maxLength: 256 },
+            oldest: { kind: "string", required: false, minLength: 1, maxLength: 64 },
+            latest: { kind: "string", required: false, minLength: 1, maxLength: 64 },
         },
     },
     "slack.message.post": {
         idempotencyKey: true,
         fields: {
             text: { kind: "string", required: true, minLength: 1, maxLength: 4000 },
+            threadId: { kind: "string", required: false, minLength: 0, pattern: "^[A-Za-z0-9._-]{1,64}$" },
+            format: { kind: "enum", required: false, values: ["plain", "mrkdwn"], default: "plain" },
+        },
+    },
+    "slack.message.update": {
+        idempotencyKey: false,
+        fields: {
+            messageId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9._-]{1,64}$" },
+            text: { kind: "string", required: true, minLength: 1, maxLength: 4000 },
+            format: { kind: "enum", required: false, values: ["plain", "mrkdwn"], default: "plain" },
+        },
+    },
+    "slack.message.delete": {
+        idempotencyKey: false,
+        fields: {
+            messageId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9._-]{1,64}$" },
+        },
+    },
+    "slack.dm.send": {
+        idempotencyKey: true,
+        fields: {
+            to: { kind: "string[]", required: true, minItems: 1, maxItems: 8, uniqueItems: true, item: { minLength: 3, maxLength: 254, pattern: "^[^\\s@<>,;\"]+@[^\\s@<>,;\"]+\\.[^\\s@<>,;\"]+$" } },
+            text: { kind: "string", required: true, minLength: 1, maxLength: 4000 },
+            format: { kind: "enum", required: false, values: ["plain", "mrkdwn"], default: "plain" },
+        },
+    },
+    "slack.user.lookup": {
+        idempotencyKey: false,
+        fields: {
+            email: { kind: "string", required: true, minLength: 3, maxLength: 254, pattern: "^[^\\s@<>,;\"]+@[^\\s@<>,;\"]+\\.[^\\s@<>,;\"]+$" },
         },
     },
     "gmail.thread.list": {
         idempotencyKey: false,
         fields: {
-            limit: { kind: "integer", required: false, minimum: 1, maximum: 15, default: 15 },
+            limit: { kind: "integer", required: false, minimum: 1, maximum: 50, default: 15 },
+            q: { kind: "string", required: false, minLength: 1, maxLength: 256 },
+            labelIds: { kind: "string[]", required: false, minItems: 1, maxItems: 5, uniqueItems: true, item: { minLength: 1, maxLength: 64 }, default: ["INBOX"] },
+            pageToken: { kind: "string", required: false, minLength: 1, maxLength: 256 },
+        },
+    },
+    "gmail.thread.read": {
+        idempotencyKey: false,
+        fields: {
+            threadId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9._-]{1,64}$" },
         },
     },
     "gmail.message.read": {
         idempotencyKey: false,
         fields: {
-            messageId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9_-]{1,64}$" },
+            messageId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9._-]{1,64}$" },
         },
     },
     "gmail.message.send": {
@@ -33,9 +75,22 @@ export const IntegrationExecuteInputRules = {
             bcc: { kind: "string[]", required: false, minItems: 1, maxItems: 50, uniqueItems: true, item: { minLength: 3, maxLength: 254, pattern: "^[^\\s@<>,;\"]+@[^\\s@<>,;\"]+\\.[^\\s@<>,;\"]+$" } },
             subject: { kind: "string", required: true, minLength: 1, maxLength: 256 },
             text: { kind: "string", required: true, minLength: 1, maxLength: 4000 },
+            html: { kind: "string", required: false, minLength: 1, maxLength: 65536 },
+            attachments: { kind: "object[]", required: false, minItems: 1, maxItems: 5, fields: {
+                    filename: { kind: "string", required: true, minLength: 1, maxLength: 255 },
+                    contentType: { kind: "string", required: true, minLength: 1, maxLength: 128 },
+                    dataBase64: { kind: "string", required: true, minLength: 1, maxLength: 2796203 },
+                } },
             replyToMessageId: { kind: "string", required: false, minLength: 0, pattern: "^[A-Za-z0-9_-]{1,64}$" },
         },
     },
+    "gmail.attachment.read": {
+        idempotencyKey: false,
+        fields: {
+            messageId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9._-]{1,64}$" },
+            attachmentId: { kind: "string", required: true, minLength: 1, maxLength: 512 },
+        },
+    },
     "warehouse.view.read": {
         idempotencyKey: false,
         fields: {
@@ -105,6 +160,8 @@ function checkFields(operation, prefix, fields, given, nullIsAbsent) {
                 return refuse(path, `${path} is required for ${operation}`);
             if ((field.kind === 'integer' || field.kind === 'enum') && field.default !== undefined)
                 out[name] = field.default;
+            if (field.kind === 'string[]' && field.default !== undefined)
+                out[name] = [...field.default];
             continue;
         }
         const checked = checkField(operation, path, name, field, value);

package/dist/runtime.d.ts

@@ -14,6 +14,12 @@ export interface ActionContext {
     tenant: string;
     app: string;
     requestId: string;
+    /**
+     * Reports a step to a page that invoked the action with `onProgress`; a
+     * no-op otherwise. A string or a small JSON object; after 256 steps, or a
+     * step over 1 KiB, further calls are dropped.
+     */
+    progress(step: string | Record<string, unknown>): void;
 }
 export interface JobContext {
     scheduledAt: string;

package/dist/runtime.js

@@ -81,6 +81,12 @@ const DEFAULT_MAX_ATTEMPTS = 3;
 // waits this long for the gateway's data path, probing every retry interval.
 const DATA_PATH_WAIT_MS = 90_000;
 const DATA_PATH_RETRY_MS = 3_000;
+// An action's progress stream: asked for with this Accept, one JSON line per
+// ctx.progress call, then the answer as the last line. Bounded so a loop
+// cannot flood the page or crowd the result out of the gateway's 4 MiB cap.
+const PROGRESS_MEDIA_TYPE = 'application/x-ndjson';
+const MAX_PROGRESS_EVENTS = 256;
+const MAX_PROGRESS_LINE_BYTES = 1 << 10;
 /** Every `actions/<name>.ts` and `jobs/<name>.ts` the app carries, by logical name. */
 export async function discover(root) {
     const list = async (dir) => {
@@ -147,7 +153,14 @@ function loadHandler(root, dir, name) {
     return loading;
 }
 // ---- HTTP helpers ------------------------------------------------------------
+// Once an action has streamed progress the status line is gone, so its
+// answer — result or refusal — is the stream's last line, the refusal
+// carrying the status it would have had.
 function answer(response, status, body, requestId) {
+    if (response.headersSent) {
+        response.end(`${JSON.stringify(status >= 400 ? { ...body, status } : body)}\n`);
+        return;
+    }
     const encoded = JSON.stringify(body);
     response.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(encoded), ...(requestId ? { 'x-request-id': requestId } : {}) });
     response.end(encoded);
@@ -432,6 +445,7 @@ export class Runtime {
         }
         this.running.add(key);
         try {
+            await this.prepareAI();
             const handler = await loadHandler(this.options.root, JOBS_DIR, name);
             await handler({ scheduledAt: at.toISOString(), progress: async () => undefined, cancelled: async () => false });
             this.log(`jobs/${name}.ts ran for ${at.toISOString()}`);
@@ -466,6 +480,7 @@ export class Runtime {
                 return true;
             }
             try {
+                await this.prepareAI();
                 const handler = await loadHandler(this.options.root, JOBS_DIR, run.job);
                 const result = await handler({
                     scheduledAt: now.toISOString(), runId: run.id, input: run.input,
@@ -501,7 +516,29 @@ export class Runtime {
             email: header(request, 'X-Harbour-Verified-User-Email'),
             groups: userGroupsFromHeader(header(request, 'X-Harbour-Verified-User-Groups')),
         };
-        const context = { signal: controller.signal, user, tenant, app, requestId: requestId ?? '' };
+        const streams = header(request, 'accept').toLowerCase().includes(PROGRESS_MEDIA_TYPE);
+        let steps = 0;
+        const progress = (step) => {
+            if (!streams || steps >= MAX_PROGRESS_EVENTS || response.writableEnded)
+                return;
+            let encoded;
+            try {
+                encoded = JSON.stringify(step);
+            }
+            catch {
+                return;
+            }
+            if (encoded === undefined)
+                return;
+            const line = `{"progress":${encoded}}\n`;
+            if (Buffer.byteLength(line) > MAX_PROGRESS_LINE_BYTES)
+                return;
+            steps += 1;
+            if (!response.headersSent)
+                response.writeHead(200, { 'content-type': PROGRESS_MEDIA_TYPE, ...(requestId ? { 'x-request-id': requestId } : {}) });
+            response.write(line);
+        };
+        const context = { signal: controller.signal, user, tenant, app, requestId: requestId ?? '', progress };
         const raw = await readBody(request);
         if (raw === undefined)
             return refuse(response, 413, 'VALIDATION_FAILED', 'the request body is larger than 1 MiB', requestId);

package/package.json

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