@vertesia/workflow 1.0.0-dev.20260305.083323Z → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/workflow",
-  "version": "1.0.0-dev.20260305.083323Z",
+  "version": "1.0.0",
   "type": "module",
   "description": "Vertesia workflow DSL",
   "main": "./lib/esm/index.js",
@@ -43,11 +43,11 @@
     "tmp": "^0.2.4",
     "tmp-promise": "^3.0.3",
     "yaml": "^2.6.0",
-    "@llumiverse/common": "1.0.0-dev.20260224.234313Z",
-    "@vertesia/api-fetch-client": "1.0.0-dev.20260305.083323Z",
-    "@vertesia/client": "1.0.0-dev.20260305.083323Z",
-    "@vertesia/common": "1.0.0-dev.20260305.083323Z",
-    "@vertesia/memory": "1.0.0-dev.20260305.083323Z"
+    "@llumiverse/common": "1.0.0",
+    "@vertesia/client": "1.0.0",
+    "@vertesia/api-fetch-client": "1.0.0",
+    "@vertesia/common": "1.0.0",
+    "@vertesia/memory": "1.0.0"
   },
   "ts_dual_module": {
     "outDir": "lib",

package/src/activities/chunkDocument.ts

@@ -157,9 +157,7 @@ export async function chunkDocument(payload: DSLActivityExecutionPayload<ChunkDo
         //delete previous parts
         if (document.parts && document.parts.length > 0) {
             log.info('Deleting previous parts for object ID: ' + objectId, { parts: document.parts });
-            await Promise.all(document.parts.map(async (partId) => {
-                await client.objects.delete(partId);
-            }));
+            await client.objects.delete(document.parts);
         }
 
         await client.objects.update(objectId, {

package/src/activities/executeInteraction.ts

@@ -202,6 +202,14 @@ export async function executeInteraction(payload: DSLActivityExecutionPayload<Ex
         log.error(`Failed to execute interaction ${interactionName}`, { error });
         if (error.statusCode === 429 && params.exit_on_resource_exhaustion) {
             throw new ResourceExhaustedError(error.statusCode, "Resource exhausted - rate limit exceeded");
+        } else if (is4xxNonRetryable(error.status) || is4xxNonRetryable(error.statusCode) || is4xxNonRetryable(error.code) || error.retryable === false) {
+            // 4xx HTTP errors (except 429 rate-limit) are permanent client errors (e.g. model not found, invalid request).
+            // Errors explicitly marked as non-retryable (e.g. LlumiverseError) also fall here.
+            // They will not be resolved by retrying.
+            throw ApplicationFailure.create({
+                message: `Interaction Execution failed ${interactionName}: ${error.message}`,
+                nonRetryable: true,
+            });
         } else if (error.message.includes("Failed to validate merged prompt schema")) {
             //issue with the input data, don't retry
             throw new ActivityParamInvalidError("prompt_data", payload.activity, error.message);
@@ -330,3 +338,12 @@ export async function executeInteractionFromActivity(
 
     return res;
 }
+
+/**
+ * Returns true for 4xx status codes that indicate permanent client errors.
+ * 429 (Too Many Requests) is excluded because it is retryable.
+ */
+function is4xxNonRetryable(code: number | undefined): boolean {
+    if (code === undefined || typeof code !== 'number') return false;
+    return code >= 400 && code < 500 && code !== 429;
+}

package/src/activities/executeRemoteActivity.test.ts

@@ -0,0 +1,140 @@
+import { MockActivityEnvironment } from "@temporalio/testing";
+import { ContentEventName, DSLActivityExecutionPayload } from "@vertesia/common";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { executeRemoteActivity, ExecuteRemoteActivityParams } from "./executeRemoteActivity.js";
+
+vi.stubGlobal("fetch", vi.fn());
+
+let testEnv: MockActivityEnvironment;
+const mockFetch = vi.mocked(fetch);
+
+beforeAll(async () => {
+    testEnv = new MockActivityEnvironment();
+});
+
+beforeEach(() => {
+    vi.clearAllMocks();
+});
+
+const createPayload = (
+    overrides: Partial<ExecuteRemoteActivityParams> = {},
+): DSLActivityExecutionPayload<ExecuteRemoteActivityParams> => {
+    const params: ExecuteRemoteActivityParams = {
+        url: "https://tool-server.test/api/activities/nlp",
+        activity_name: "analyze_sentiment",
+        params: { text: "Hello world" },
+        app_install_id: "install-123",
+        app_name: "nlp-app",
+        ...overrides,
+    };
+    return {
+        auth_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbW9jay10b2tlbi1zZXJ2ZXIiLCJzdWIiOiJ0ZXN0In0.sig",
+        account_id: "acc-123",
+        project_id: "proj-456",
+        params,
+        config: {
+            studio_url: "http://mock-studio",
+            store_url: "http://mock-store",
+        },
+        workflow_name: "TestWorkflow",
+        event: ContentEventName.create,
+        objectIds: [],
+        vars: {},
+        activity: { name: "executeRemoteActivity", params },
+    };
+};
+
+describe("executeRemoteActivity", () => {
+    it("posts correct payload and returns result on success", async () => {
+        mockFetch.mockResolvedValueOnce(
+            new Response(
+                JSON.stringify({ result: { score: 0.95 }, is_error: false }),
+                { status: 200, headers: { "Content-Type": "application/json" } },
+            ),
+        );
+
+        const result = await testEnv.run(executeRemoteActivity, createPayload());
+        expect(result).toEqual({ score: 0.95 });
+
+        expect(mockFetch).toHaveBeenCalledOnce();
+        const [url, opts] = mockFetch.mock.calls[0];
+        expect(url).toBe("https://tool-server.test/api/activities/nlp");
+        expect(opts?.method).toBe("POST");
+        expect(opts?.headers).toMatchObject({
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        });
+        // Verify the auth header is forwarded
+        expect((opts?.headers as Record<string, string>)["Authorization"]).toMatch(/^Bearer /);
+
+        // Verify the body structure
+        const body = JSON.parse(opts?.body as string);
+        expect(body.activity_name).toBe("analyze_sentiment");
+        expect(body.params).toEqual({ text: "Hello world" });
+        expect(body.metadata.app_install_id).toBe("install-123");
+        expect(body.metadata.endpoints).toEqual({ studio: "http://mock-studio", store: "http://mock-store" });
+        // auth_token should NOT be in the payload (it's in the Authorization header)
+        expect(body.auth_token).toBeUndefined();
+    });
+
+    it("throws on HTTP error (4xx/5xx)", async () => {
+        mockFetch.mockResolvedValueOnce(
+            new Response(
+                JSON.stringify({ error: "Activity not found", is_error: true }),
+                { status: 404, statusText: "Not Found" },
+            ),
+        );
+
+        await expect(testEnv.run(executeRemoteActivity, createPayload())).rejects.toThrow(
+            "Remote activity analyze_sentiment failed: Activity not found",
+        );
+    });
+
+    it("throws on network error (for Temporal retry)", async () => {
+        mockFetch.mockRejectedValueOnce(new Error("Connection refused"));
+
+        await expect(testEnv.run(executeRemoteActivity, createPayload())).rejects.toThrow(
+            /Failed to reach remote activity endpoint/,
+        );
+    });
+
+    it("throws on invalid JSON response", async () => {
+        mockFetch.mockResolvedValueOnce(
+            new Response("not json", { status: 200 }),
+        );
+
+        await expect(testEnv.run(executeRemoteActivity, createPayload())).rejects.toThrow(
+            /returned invalid JSON/,
+        );
+    });
+
+    it("throws when response indicates is_error", async () => {
+        mockFetch.mockResolvedValueOnce(
+            new Response(
+                JSON.stringify({ result: null, is_error: true, error: "Something went wrong" }),
+                { status: 200, headers: { "Content-Type": "application/json" } },
+            ),
+        );
+
+        await expect(testEnv.run(executeRemoteActivity, createPayload())).rejects.toThrow(
+            "Remote activity analyze_sentiment: Something went wrong",
+        );
+    });
+
+    it("forwards app_settings in metadata", async () => {
+        mockFetch.mockResolvedValueOnce(
+            new Response(
+                JSON.stringify({ result: "ok", is_error: false }),
+                { status: 200, headers: { "Content-Type": "application/json" } },
+            ),
+        );
+
+        await testEnv.run(
+            executeRemoteActivity,
+            createPayload({ app_settings: { api_key: "secret" } }),
+        );
+
+        const body = JSON.parse(mockFetch.mock.calls[0][1]?.body as string);
+        expect(body.metadata.app_settings).toEqual({ api_key: "secret" });
+    });
+});

package/src/activities/executeRemoteActivity.ts

@@ -0,0 +1,133 @@
+import { ApplicationFailure, log } from "@temporalio/activity";
+import {
+    DSLActivityExecutionPayload,
+    RemoteActivityExecutionPayload,
+    RemoteActivityExecutionResponse,
+} from "@vertesia/common";
+import { setupActivity } from "../dsl/setup/ActivityContext.js";
+
+/**
+ * Parameters for the executeRemoteActivity bridge activity.
+ */
+export interface ExecuteRemoteActivityParams {
+    /** URL of the remote activity endpoint on the tool server */
+    url: string;
+    /** The activity name (unprefixed, as known by the tool server) */
+    activity_name: string;
+    /** The resolved parameters for the activity */
+    params: Record<string, any>;
+    /** App installation ID */
+    app_install_id: string;
+    /** App name */
+    app_name: string;
+    /** App installation settings */
+    app_settings?: Record<string, any>;
+}
+
+/**
+ * Bridge activity that executes a remote activity on a tool server via HTTP POST.
+ *
+ * This activity is called by the DSL workflow engine when a step's name matches
+ * a remote activity (qualified as `app:<app_name>:<collection>:<activity>`). It POSTs a
+ * `RemoteActivityExecutionPayload` to the tool server and returns the result.
+ *
+ * Network errors throw retryable errors (so Temporal retries).
+ * Client errors (4xx) and activity-level errors throw non-retryable ApplicationFailure.
+ * Server errors (5xx) throw retryable errors.
+ */
+export async function executeRemoteActivity(
+    payload: DSLActivityExecutionPayload<ExecuteRemoteActivityParams>,
+): Promise<any> {
+    const ctx = await setupActivity<ExecuteRemoteActivityParams>(payload);
+    const { params, runId } = ctx;
+    const { url, activity_name, params: activityParams, app_install_id, app_settings } = params;
+
+    const executionPayload: RemoteActivityExecutionPayload = {
+        activity_name,
+        params: activityParams,
+        metadata: {
+            run_id: runId,
+            app_install_id,
+            app_settings,
+            endpoints: payload.config ? {
+                studio: payload.config.studio_url,
+                store: payload.config.store_url,
+            } : undefined,
+        },
+    };
+
+    let response: Response;
+    try {
+        response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "Authorization": `Bearer ${payload.auth_token}`,
+            },
+            body: JSON.stringify(executionPayload),
+        });
+    } catch (err: unknown) {
+        const message = err instanceof Error ? err.message : String(err);
+        log.warn("Failed to reach remote activity endpoint", {
+            error: message, activity: activity_name, endpoint: url, runId, app_install_id,
+        });
+        // Network-level failure — let Temporal retry
+        throw new Error(`Failed to reach remote activity endpoint (activity: ${activity_name}, endpoint: ${url}): ${message}`);
+    }
+
+    const responseText = await response.text();
+
+    if (!response.ok) {
+        let errorMessage = `HTTP ${response.status} ${response.statusText}`;
+        try {
+            const errorJson = JSON.parse(responseText) as RemoteActivityExecutionResponse;
+            if (errorJson.error) {
+                errorMessage = errorJson.error;
+            }
+        } catch {
+            // Not JSON — use the status line
+        }
+        log.warn("Remote activity returned HTTP error", {
+            activity: activity_name, endpoint: url, status: response.status, runId, app_install_id,
+            responsePreview: responseText.slice(0, 500),
+        });
+        const msg = `Remote activity ${activity_name} failed: ${errorMessage}`;
+        // 4xx errors are client/configuration errors — don't retry
+        if (response.status >= 400 && response.status < 500) {
+            throw ApplicationFailure.create({
+                message: msg,
+                nonRetryable: true,
+            });
+        }
+        // 5xx errors are server errors — let Temporal retry
+        throw new Error(msg);
+    }
+
+    let responseJson: RemoteActivityExecutionResponse;
+    try {
+        responseJson = JSON.parse(responseText);
+    } catch (err: unknown) {
+        const preview = responseText.length > 200 ? responseText.slice(0, 200) + '...' : responseText;
+        log.warn("Invalid JSON response from remote activity", {
+            activity: activity_name, endpoint: url, runId, app_install_id,
+            responsePreview: preview,
+        });
+        throw ApplicationFailure.create({
+            message: `Remote activity ${activity_name} returned invalid JSON: ${preview}`,
+            nonRetryable: true,
+        });
+    }
+
+    if (responseJson.is_error) {
+        log.warn("Remote activity returned error", {
+            activity: activity_name, endpoint: url, error: responseJson.error, runId, app_install_id,
+        });
+        throw ApplicationFailure.create({
+            message: `Remote activity ${activity_name}: ${responseJson.error}`,
+            nonRetryable: true,
+        });
+    }
+
+    return responseJson.result;
+}

package/src/activities/getObjectFromStore.ts

@@ -1,4 +1,5 @@
 import { ContentObject, DSLActivityExecutionPayload, DSLActivitySpec } from "@vertesia/common";
+import { DocumentNotFoundError } from "../errors.js";
 import { projectResult } from "../dsl/projections.js";
 import { setupActivity } from "../dsl/setup/ActivityContext.js";
 
@@ -19,7 +20,16 @@ export interface GetObject extends DSLActivitySpec<GetObjectParams> {
 export async function getObjectFromStore(payload: DSLActivityExecutionPayload<GetObjectParams>): Promise<ContentObject> {
     const { client, params, objectId } = await setupActivity<GetObjectParams>(payload);
 
-    const obj = await client.objects.retrieve(objectId, params.select);
+    let obj: ContentObject;
+    try {
+        obj = await client.objects.retrieve(objectId, params.select);
+    } catch (err: unknown) {
+        const status = err && typeof err === 'object' && 'status' in err ? (err as { status: number }).status : 0;
+        if (status >= 400 && status < 500 && status !== 429) {
+            throw new DocumentNotFoundError(`Object retrieval failed (${status}): ${objectId}`, [objectId]);
+        }
+        throw err;
+    }
 
     const projection = projectResult(payload, params, obj, obj);
 

package/src/activities/index-dsl.ts

@@ -1,9 +1,11 @@
 // Export here DSL activities
+export { executeRemoteActivity } from "./executeRemoteActivity.js";
+export { resolveRemoteActivities } from "./resolveRemoteActivities.js";
+export type { RemoteActivityInfo, RemoteActivityMap } from "./resolveRemoteActivities.js";
 export { createDocumentTypeFromInteractionRun } from "./advanced/createDocumentTypeFromInteractionRun.js";
 export { createOrUpdateDocumentFromInteractionRun } from "./advanced/createOrUpdateDocumentFromInteractionRun.js";
 export { updateDocumentFromInteractionRun } from "./advanced/updateDocumentFromInteractionRun.js";
 export { chunkDocument } from "./chunkDocument.js";
-export { copyParentArtifacts } from "./copyParentArtifacts.js";
 export { createPdfDocumentFromSource } from "./createDocumentFromOther.js";
 export { executeInteraction } from "./executeInteraction.js";
 export { extractDocumentText } from "./extractDocumentText.js";

package/src/activities/resolveRemoteActivities.test.ts

@@ -0,0 +1,220 @@
+import { MockActivityEnvironment } from "@temporalio/testing";
+import { ContentEventName, DSLActivityExecutionPayload } from "@vertesia/common";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { resolveRemoteActivities, ResolveRemoteActivitiesParams } from "./resolveRemoteActivities.js";
+
+vi.stubGlobal("fetch", vi.fn());
+
+// Mock getVertesiaClient
+const mockGetInstalledApps = vi.fn();
+vi.mock("../utils/client.js", () => ({
+    getVertesiaClient: vi.fn().mockReturnValue({
+        apps: {
+            getInstalledApps: (...args: any[]) => mockGetInstalledApps(...args),
+        },
+    }),
+}));
+
+let testEnv: MockActivityEnvironment;
+const mockFetch = vi.mocked(fetch);
+
+beforeAll(async () => {
+    testEnv = new MockActivityEnvironment();
+});
+
+beforeEach(() => {
+    vi.clearAllMocks();
+});
+
+const createPayload = (): DSLActivityExecutionPayload<ResolveRemoteActivitiesParams> => ({
+    auth_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbW9jay10b2tlbi1zZXJ2ZXIiLCJzdWIiOiJ0ZXN0In0.sig",
+    account_id: "acc-123",
+    project_id: "proj-456",
+    params: {},
+    config: {
+        studio_url: "http://mock-studio",
+        store_url: "http://mock-store",
+    },
+    workflow_name: "TestWorkflow",
+    event: ContentEventName.create,
+    objectIds: [],
+    vars: {},
+    activity: { name: "resolveRemoteActivities", params: {} },
+});
+
+describe("resolveRemoteActivities", () => {
+    it("returns empty map when no apps installed", async () => {
+        mockGetInstalledApps.mockResolvedValueOnce([]);
+
+        const result = await testEnv.run(resolveRemoteActivities, createPayload());
+        expect(result).toEqual({});
+        expect(mockGetInstalledApps).toHaveBeenCalledWith("tools");
+    });
+
+    it("returns qualified activity map from single app", async () => {
+        mockGetInstalledApps.mockResolvedValueOnce([{
+            id: "install-1",
+            manifest: {
+                name: "my-nlp-app",
+                endpoint: "https://nlp-server.test/api/package",
+            },
+            settings: { api_key: "test" },
+        }]);
+
+        mockFetch.mockResolvedValueOnce(
+            new Response(
+                JSON.stringify({
+                    activities: [
+                        { name: "analyze_sentiment", description: "Analyze sentiment", collection: "nlp" },
+                        { name: "extract_entities", description: "Extract entities", collection: "nlp" },
+                    ],
+                }),
+                { status: 200, headers: { "Content-Type": "application/json" } },
+            ),
+        );
+
+        const result = await testEnv.run(resolveRemoteActivities, createPayload());
+
+        expect(Object.keys(result)).toHaveLength(2);
+        expect(result["app:my-nlp-app:nlp:analyze_sentiment"]).toBeDefined();
+        expect(result["app:my-nlp-app:nlp:extract_entities"]).toBeDefined();
+
+        const entry = result["app:my-nlp-app:nlp:analyze_sentiment"];
+        expect(entry.activity_name).toBe("analyze_sentiment");
+        expect(entry.app_name).toBe("my-nlp-app");
+        expect(entry.app_install_id).toBe("install-1");
+        expect(entry.app_settings).toEqual({ api_key: "test" });
+        // URL should target the collection-specific endpoint
+        expect(entry.url).toBe("https://nlp-server.test/api/activities/nlp");
+    });
+
+    it("merges activities from multiple apps", async () => {
+        mockGetInstalledApps.mockResolvedValueOnce([
+            {
+                id: "install-1",
+                manifest: { name: "app-one", endpoint: "https://one.test/api/package" },
+            },
+            {
+                id: "install-2",
+                manifest: { name: "app-two", endpoint: "https://two.test/api/package" },
+            },
+        ]);
+
+        mockFetch
+            .mockResolvedValueOnce(
+                new Response(JSON.stringify({ activities: [{ name: "task_a", collection: "main" }] }), { status: 200 }),
+            )
+            .mockResolvedValueOnce(
+                new Response(JSON.stringify({ activities: [{ name: "task_b", collection: "main" }] }), { status: 200 }),
+            );
+
+        const result = await testEnv.run(resolveRemoteActivities, createPayload());
+
+        expect(Object.keys(result)).toHaveLength(2);
+        expect(result["app:app-one:main:task_a"]).toBeDefined();
+        expect(result["app:app-two:main:task_b"]).toBeDefined();
+    });
+
+    it("skips app with no activities", async () => {
+        mockGetInstalledApps.mockResolvedValueOnce([{
+            id: "install-1",
+            manifest: { name: "empty-app", endpoint: "https://empty.test/api/package" },
+        }]);
+
+        mockFetch.mockResolvedValueOnce(
+            new Response(JSON.stringify({ activities: [] }), { status: 200 }),
+        );
+
+        const result = await testEnv.run(resolveRemoteActivities, createPayload());
+        expect(result).toEqual({});
+    });
+
+    it("skips app with no endpoint", async () => {
+        mockGetInstalledApps.mockResolvedValueOnce([{
+            id: "install-1",
+            manifest: { name: "no-endpoint" },
+        }]);
+
+        const result = await testEnv.run(resolveRemoteActivities, createPayload());
+        expect(result).toEqual({});
+        expect(mockFetch).not.toHaveBeenCalled();
+    });
+
+    it("handles duplicate qualified names across apps (first wins)", async () => {
+        mockGetInstalledApps.mockResolvedValueOnce([
+            {
+                id: "install-1",
+                manifest: { name: "same-app", endpoint: "https://one.test/api/package" },
+            },
+            {
+                id: "install-2",
+                manifest: { name: "same-app", endpoint: "https://two.test/api/package" },
+            },
+        ]);
+
+        mockFetch
+            .mockResolvedValueOnce(
+                new Response(JSON.stringify({ activities: [{ name: "task", collection: "main" }] }), { status: 200 }),
+            )
+            .mockResolvedValueOnce(
+                new Response(JSON.stringify({ activities: [{ name: "task", collection: "main" }] }), { status: 200 }),
+            );
+
+        const result = await testEnv.run(resolveRemoteActivities, createPayload());
+        expect(Object.keys(result)).toHaveLength(1);
+        expect(result["app:same-app:main:task"].app_install_id).toBe("install-1");
+    });
+
+    it("continues with other apps when one fetch fails", async () => {
+        mockGetInstalledApps.mockResolvedValueOnce([
+            {
+                id: "install-1",
+                manifest: { name: "failing-app", endpoint: "https://fail.test/api/package" },
+            },
+            {
+                id: "install-2",
+                manifest: { name: "working-app", endpoint: "https://work.test/api/package" },
+            },
+        ]);
+
+        mockFetch
+            .mockRejectedValueOnce(new Error("Connection refused"))
+            .mockResolvedValueOnce(
+                new Response(JSON.stringify({ activities: [{ name: "task", collection: "main" }] }), { status: 200 }),
+            );
+
+        const result = await testEnv.run(resolveRemoteActivities, createPayload());
+        expect(Object.keys(result)).toHaveLength(1);
+        expect(result["app:working-app:main:task"]).toBeDefined();
+    });
+
+    it("returns empty map when getInstalledApps fails", async () => {
+        mockGetInstalledApps.mockRejectedValueOnce(new Error("API error"));
+
+        const result = await testEnv.run(resolveRemoteActivities, createPayload());
+        expect(result).toEqual({});
+    });
+
+    it("skips activities without collection", async () => {
+        mockGetInstalledApps.mockResolvedValueOnce([{
+            id: "install-1",
+            manifest: { name: "bad-app", endpoint: "https://bad.test/api/package" },
+        }]);
+
+        mockFetch.mockResolvedValueOnce(
+            new Response(
+                JSON.stringify({
+                    activities: [
+                        { name: "no_collection" },
+                        { name: "has_collection", collection: "main" },
+                    ],
+                }),
+                { status: 200 },
+            ),
+        );
+
+        const result = await testEnv.run(resolveRemoteActivities, createPayload()) as Record<string, unknown>;
+        expect(Object.keys(result)).toHaveLength(1);
+        expect(result["app:bad-app:main:has_collection"]).toBeDefined();
+    });
+});