@isomorph.ai/app-sdk 1.8.0 → 1.9.0

package/README.md

@@ -200,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

@@ -441,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>> {
@@ -532,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

@@ -184,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) {
@@ -211,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.
@@ -222,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
@@ -638,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: {

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.8.0",
+  "version": "1.9.0",
   "type": "module",
   "repository": {
     "type": "git",