@vertesia/tools-sdk 1.0.0-dev.20260305.083323Z → 1.0.0-dev.20260331.091034Z

package/src/ActivityCollection.test.ts

@@ -0,0 +1,161 @@
+import { RemoteActivityExecutionPayload } from "@vertesia/common";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { ActivityCollection, ActivityDefinition } from "./ActivityCollection.js";
+
+vi.mock("./auth.js", () => ({
+    authorize: vi.fn().mockResolvedValue({ token: "test-token" }),
+}));
+
+const mockActivity: ActivityDefinition = {
+    name: "analyze_sentiment",
+    title: "Analyze Sentiment",
+    description: "Analyzes text sentiment",
+    input_schema: {
+        type: "object",
+        properties: { text: { type: "string" } },
+        required: ["text"],
+    },
+    output_schema: {
+        type: "object",
+        properties: { score: { type: "number" } },
+    },
+    run: vi.fn().mockResolvedValue({ score: 0.95 }),
+};
+
+const mockFailingActivity: ActivityDefinition = {
+    name: "fail_always",
+    description: "Always fails",
+    run: vi.fn().mockRejectedValue(new Error("Intentional failure")),
+};
+
+function createCollection(activities: ActivityDefinition[] = [mockActivity]) {
+    return new ActivityCollection({
+        name: "test-collection",
+        title: "Test Collection",
+        description: "A test collection",
+        activities,
+    });
+}
+
+beforeEach(() => {
+    vi.clearAllMocks();
+});
+
+describe("ActivityCollection", () => {
+    describe("getActivityDefinitions", () => {
+        it("returns correct metadata for all registered activities", () => {
+            const coll = createCollection([mockActivity, mockFailingActivity]);
+            const defs = coll.getActivityDefinitions();
+
+            expect(defs).toHaveLength(2);
+            expect(defs[0]).toEqual({
+                name: "analyze_sentiment",
+                title: "Analyze Sentiment",
+                description: "Analyzes text sentiment",
+                input_schema: mockActivity.input_schema,
+                output_schema: mockActivity.output_schema,
+            });
+            expect(defs[1]).toEqual({
+                name: "fail_always",
+                title: undefined,
+                description: "Always fails",
+                input_schema: undefined,
+                output_schema: undefined,
+            });
+        });
+
+        it("returns empty array when no activities registered", () => {
+            const coll = createCollection([]);
+            expect(coll.getActivityDefinitions()).toEqual([]);
+        });
+    });
+
+    describe("getActivity", () => {
+        it("returns the activity by name", () => {
+            const coll = createCollection();
+            const activity = coll.getActivity("analyze_sentiment");
+            expect(activity.name).toBe("analyze_sentiment");
+            expect(activity.run).toBeDefined();
+        });
+
+        it("throws 404 for unknown activity name", () => {
+            const coll = createCollection();
+            expect(() => coll.getActivity("nonexistent")).toThrow();
+        });
+    });
+
+    describe("iterator", () => {
+        it("iterates over all activities", () => {
+            const coll = createCollection([mockActivity, mockFailingActivity]);
+            const names = [...coll].map(a => a.name);
+            expect(names).toEqual(["analyze_sentiment", "fail_always"]);
+        });
+    });
+
+    describe("execute", () => {
+        const createMockContext = () => {
+            const jsonFn = vi.fn().mockReturnThis();
+            return {
+                json: jsonFn,
+                req: {
+                    header: vi.fn().mockReturnValue("Bearer test-token"),
+                    url: "http://localhost/api/activities",
+                },
+                set: vi.fn(),
+            } as any;
+        };
+
+        const payload: RemoteActivityExecutionPayload = {
+            activity_name: "analyze_sentiment",
+            params: { text: "Hello world" },
+            metadata: {
+                app_install_id: "install-1",
+            },
+        };
+
+        it("calls the correct activity handler and returns result", async () => {
+            const coll = createCollection();
+            const ctx = createMockContext();
+
+            await coll.execute(ctx, payload);
+
+            expect(mockActivity.run).toHaveBeenCalledWith(
+                payload,
+                expect.objectContaining({ token: "test-token" }),
+            );
+            expect(ctx.json).toHaveBeenCalledWith({
+                result: { score: 0.95 },
+                is_error: false,
+            });
+        });
+
+        it("returns is_error with message when activity throws", async () => {
+            const coll = createCollection([mockFailingActivity]);
+            const ctx = createMockContext();
+
+            const failPayload: RemoteActivityExecutionPayload = {
+                ...payload,
+                activity_name: "fail_always",
+            };
+
+            await coll.execute(ctx, failPayload);
+
+            expect(ctx.json).toHaveBeenCalledWith(
+                { result: null, is_error: true, error: "Intentional failure" },
+                500,
+            );
+        });
+
+        it("throws 404 when activity_name is not found", async () => {
+            const coll = createCollection();
+            const ctx = createMockContext();
+
+            const unknownPayload: RemoteActivityExecutionPayload = {
+                ...payload,
+                activity_name: "nonexistent",
+            };
+
+            await expect(coll.execute(ctx, unknownPayload)).rejects.toThrow();
+        });
+    });
+});

package/src/ActivityCollection.ts

@@ -0,0 +1,136 @@
+import { RemoteActivityDefinition, RemoteActivityExecutionPayload, RemoteActivityExecutionResponse } from "@vertesia/common";
+import { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { authorize } from "./auth.js";
+import { CollectionProperties, ICollection, ToolExecutionContext } from "./types.js";
+import { kebabCaseToTitle } from "./utils.js";
+
+/**
+ * Context provided to activity handlers during execution.
+ * Same interface as ToolExecutionContext: includes token, decoded payload, and getClient().
+ */
+export type ActivityExecutionContext = ToolExecutionContext;
+
+/**
+ * Function signature for a remote activity handler.
+ */
+export type ActivityFn<ParamsT extends Record<string, any> = Record<string, any>> = (
+    payload: RemoteActivityExecutionPayload<ParamsT>,
+    context: ActivityExecutionContext
+) => Promise<any>;
+
+/**
+ * An activity definition within an ActivityCollection.
+ */
+export interface ActivityDefinition<ParamsT extends Record<string, any> = Record<string, any>> {
+    /** Activity name (snake_case) */
+    name: string;
+    /** Display title */
+    title?: string;
+    /** Description of what the activity does */
+    description?: string;
+    /** JSON Schema for the activity input parameters */
+    input_schema?: Record<string, any>;
+    /** JSON Schema for the activity output */
+    output_schema?: Record<string, any>;
+    /** The activity handler function */
+    run: ActivityFn<ParamsT>;
+}
+
+export interface ActivityCollectionProperties extends CollectionProperties {
+    activities: ActivityDefinition[];
+}
+
+/**
+ * A collection of remote activities exposed by a tool server for DSL workflows.
+ * Follows the same collection pattern as ToolCollection and SkillCollection.
+ */
+export class ActivityCollection implements ICollection<ActivityDefinition> {
+    name: string;
+    title?: string;
+    icon?: string;
+    description?: string;
+    private registry: Record<string, ActivityDefinition> = {};
+
+    constructor({ name, title, icon, description, activities }: ActivityCollectionProperties) {
+        this.name = name;
+        this.title = title || kebabCaseToTitle(name);
+        this.icon = icon;
+        this.description = description;
+        for (const activity of activities) {
+            this.registry[activity.name] = activity;
+        }
+    }
+
+    [Symbol.iterator](): Iterator<ActivityDefinition> {
+        let index = 0;
+        const activities = Object.values(this.registry);
+        return {
+            next(): IteratorResult<ActivityDefinition> {
+                if (index < activities.length) {
+                    return { value: activities[index++], done: false };
+                }
+                return { done: true, value: undefined };
+            }
+        };
+    }
+
+    /**
+     * Get activity definitions for discovery (metadata only, no run function).
+     */
+    getActivityDefinitions(): RemoteActivityDefinition[] {
+        return Object.values(this.registry).map(activity => ({
+            name: activity.name,
+            title: activity.title,
+            description: activity.description,
+            input_schema: activity.input_schema,
+            output_schema: activity.output_schema,
+        }));
+    }
+
+    getActivity(name: string): ActivityDefinition {
+        const activity = this.registry[name];
+        if (!activity) {
+            throw new HTTPException(404, {
+                message: `Activity not found: ${name}. Available: ${Object.keys(this.registry).join(', ')}`
+            });
+        }
+        return activity;
+    }
+
+    /**
+     * Execute an activity from an HTTP POST request.
+     */
+    async execute(ctx: Context, payload: RemoteActivityExecutionPayload): Promise<Response> {
+        const activityName = payload.activity_name;
+
+        console.debug(`[ActivityCollection] Activity call received: ${activityName}`, {
+            collection: this.name,
+            metadata: payload.metadata,
+        });
+
+        const activity = this.getActivity(activityName);
+
+        const context = await authorize(ctx, payload.metadata?.endpoints);
+
+        try {
+            const result = await activity.run(payload, context);
+            return ctx.json({
+                result,
+                is_error: false,
+            } satisfies RemoteActivityExecutionResponse);
+        } catch (err: unknown) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[ActivityCollection] Activity execution failed: ${activityName}`, {
+                collection: this.name,
+                metadata: payload.metadata,
+                error: message,
+            });
+            return ctx.json({
+                result: null,
+                is_error: true,
+                error: message,
+            } satisfies RemoteActivityExecutionResponse, 500);
+        }
+    }
+}

package/src/auth.ts

@@ -7,7 +7,7 @@ import { ToolExecutionContext } from "./types.js";
 const cache: Record<string, JWTVerifyGetKey> = {};
 
 export async function getJwks(url: string) {
-    if (!cache.url) {
+    if (!cache[url]) {
         console.log('JWKS cache miss for: ', url);
         const jwks = await fetch(url).then(r => {
             if (r.ok) {
@@ -17,9 +17,9 @@ export async function getJwks(url: string) {
         }).catch(err => {
             throw new Error("Failed to fetch jwks: " + err.message);
         })
-        cache.url = createLocalJWKSet(jwks);
+        cache[url] = createLocalJWKSet(jwks);
     }
-    return cache.url;
+    return cache[url];
 }
 
 export async function verifyToken(token: string) {

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from "./ActivityCollection.js";
 export { authorize, AuthSession } from "./auth.js";
 export * from "./ContentTypesCollection.js";
 export * from "./RenderingTemplateCollection.js";

package/src/server/activities.test.ts

@@ -0,0 +1,165 @@
+import { Hono } from "hono";
+import { describe, expect, it, vi } from "vitest";
+import { ActivityCollection, ActivityDefinition } from "../ActivityCollection.js";
+import { createActivitiesRoute } from "./activities.js";
+import { ToolServerConfig } from "./types.js";
+
+// Mock authorize to avoid JWT verification
+vi.mock("../auth.js", () => ({
+    authorize: vi.fn().mockResolvedValue({ token: "test-token" }),
+    AuthSession: vi.fn(),
+}));
+
+const mockActivity: ActivityDefinition = {
+    name: "analyze_sentiment",
+    title: "Analyze Sentiment",
+    description: "Analyzes text sentiment",
+    input_schema: { type: "object", properties: { text: { type: "string" } } },
+    run: vi.fn().mockResolvedValue({ score: 0.95 }),
+};
+
+const mockActivity2: ActivityDefinition = {
+    name: "extract_entities",
+    description: "Extracts entities",
+    run: vi.fn().mockResolvedValue({ entities: ["foo"] }),
+};
+
+function createApp(activities: ActivityCollection[] = []) {
+    const app = new Hono();
+    const config = { activities } as ToolServerConfig;
+    createActivitiesRoute(app, "/api/activities", config);
+    return app;
+}
+
+function createTestCollections() {
+    const coll1 = new ActivityCollection({
+        name: "nlp",
+        description: "NLP activities",
+        activities: [mockActivity],
+    });
+    const coll2 = new ActivityCollection({
+        name: "extraction",
+        description: "Extraction activities",
+        activities: [mockActivity2],
+    });
+    return [coll1, coll2];
+}
+
+describe("Activities server routes", () => {
+    describe("GET /api/activities", () => {
+        it("returns all activity definitions across collections", async () => {
+            const app = createApp(createTestCollections());
+            const res = await app.request("/api/activities");
+            const body = await res.json() as any;
+
+            expect(res.status).toBe(200);
+            expect(body.activities).toHaveLength(2);
+            expect(body.activities[0].name).toBe("analyze_sentiment");
+            expect(body.activities[1].name).toBe("extract_entities");
+            expect(body.collections).toHaveLength(2);
+        });
+
+        it("returns empty when no collections configured", async () => {
+            const app = createApp([]);
+            const res = await app.request("/api/activities");
+            const body = await res.json() as any;
+
+            expect(res.status).toBe(200);
+            expect(body.activities).toHaveLength(0);
+        });
+    });
+
+    describe("GET /api/activities/{collection}", () => {
+        it("returns activities for a specific collection", async () => {
+            const app = createApp(createTestCollections());
+            const res = await app.request("/api/activities/nlp");
+            const body = await res.json() as any;
+
+            expect(res.status).toBe(200);
+            expect(body.name).toBe("nlp");
+            expect(body.activities).toHaveLength(1);
+            expect(body.activities[0].name).toBe("analyze_sentiment");
+        });
+    });
+
+    describe("POST /api/activities", () => {
+        it("executes activity by name", async () => {
+            const app = createApp(createTestCollections());
+            const res = await app.request("/api/activities", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Authorization": "Bearer test-token",
+                },
+                body: JSON.stringify({
+                    activity_name: "analyze_sentiment",
+                    params: { text: "hello" },
+                    metadata: {
+                        workflow_name: "wf",
+                        account_id: "acc",
+                        project_id: "proj",
+                    },
+                }),
+            });
+
+            expect(res.status).toBe(200);
+            const body = await res.json() as any;
+            expect(body.result).toEqual({ score: 0.95 });
+            expect(body.is_error).toBe(false);
+        });
+
+        it("returns 404 for unknown activity name", async () => {
+            const app = createApp(createTestCollections());
+            const res = await app.request("/api/activities", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Authorization": "Bearer test-token",
+                },
+                body: JSON.stringify({
+                    activity_name: "nonexistent",
+                    params: {},
+                    metadata: {},
+                }),
+            });
+
+            expect(res.status).toBe(404);
+        });
+
+        it("returns 400 for missing activity_name", async () => {
+            const app = createApp(createTestCollections());
+            const res = await app.request("/api/activities", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Authorization": "Bearer test-token",
+                },
+                body: JSON.stringify({ params: {} }),
+            });
+
+            expect(res.status).toBe(400);
+        });
+    });
+
+    describe("POST /api/activities/{collection}", () => {
+        it("routes to correct collection", async () => {
+            const app = createApp(createTestCollections());
+            const res = await app.request("/api/activities/extraction", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "Authorization": "Bearer test-token",
+                },
+                body: JSON.stringify({
+                    activity_name: "extract_entities",
+                    params: {},
+                    metadata: {},
+                }),
+            });
+
+            expect(res.status).toBe(200);
+            const body = await res.json() as any;
+            expect(body.result).toEqual({ entities: ["foo"] });
+        });
+    });
+});

package/src/server/activities.ts

@@ -0,0 +1,114 @@
+import { RemoteActivityDefinition, RemoteActivityExecutionPayload } from "@vertesia/common";
+import { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { ActivityCollection } from "../ActivityCollection.js";
+import { ToolServerConfig } from "./types.js";
+
+/**
+ * Safely parse JSON from a request body. Throws HTTPException(400) on invalid JSON.
+ */
+async function safeParseJson(c: Context): Promise<unknown> {
+    try {
+        return await c.req.json();
+    } catch {
+        throw new HTTPException(400, {
+            message: 'Invalid JSON in request body.'
+        });
+    }
+}
+
+/**
+ * Validates the structure of a RemoteActivityExecutionPayload.
+ * Returns the parsed payload or throws HTTPException(400).
+ */
+function parseActivityPayload(body: unknown): RemoteActivityExecutionPayload {
+    if (!body || typeof body !== 'object') {
+        throw new HTTPException(400, {
+            message: 'Invalid or missing activity execution payload.'
+        });
+    }
+    const obj = body as Record<string, any>;
+    if (typeof obj.activity_name !== 'string' || !obj.activity_name) {
+        throw new HTTPException(400, {
+            message: 'Missing required field: activity_name'
+        });
+    }
+    return {
+        activity_name: obj.activity_name,
+        params: obj.params || {},
+        metadata: obj.metadata || {},
+    };
+}
+
+export function createActivitiesRoute(app: Hono, basePath: string, config: ToolServerConfig) {
+    const { activities = [] } = config;
+
+    // Build a map of activity name -> collection for routing
+    const activityToCollection = new Map<string, ActivityCollection>();
+    for (const coll of activities) {
+        for (const def of coll.getActivityDefinitions()) {
+            activityToCollection.set(def.name, coll);
+        }
+    }
+
+    // GET /api/activities - List all activities across all collections
+    app.get(basePath, (c) => {
+        const allActivities: RemoteActivityDefinition[] = [];
+        for (const coll of activities) {
+            allActivities.push(...coll.getActivityDefinitions());
+        }
+        return c.json({
+            title: 'All Activities',
+            description: 'All available remote activities across all collections',
+            activities: allActivities,
+            collections: activities.map(a => ({
+                name: a.name,
+                title: a.title,
+                description: a.description,
+            })),
+        });
+    });
+
+    // POST /api/activities - Execute an activity by name (routes to correct collection)
+    app.post(basePath, async (c) => {
+        const body = await safeParseJson(c);
+        const payload = parseActivityPayload(body);
+
+        const collection = activityToCollection.get(payload.activity_name);
+        if (!collection) {
+            throw new HTTPException(404, {
+                message: `Activity not found: ${payload.activity_name}. Available: ${Array.from(activityToCollection.keys()).join(', ')}`
+            });
+        }
+
+        return collection.execute(c, payload);
+    });
+
+    // Per-collection endpoints
+    for (const coll of activities) {
+        app.route(`${basePath}/${coll.name}`, createActivityEndpoints(coll));
+    }
+}
+
+function createActivityEndpoints(coll: ActivityCollection): Hono {
+    const endpoint = new Hono();
+
+    // GET /api/activities/{collection} - List activities in this collection
+    endpoint.get('/', (c) => {
+        return c.json({
+            name: coll.name,
+            title: coll.title,
+            description: coll.description,
+            activities: coll.getActivityDefinitions(),
+        });
+    });
+
+    // POST /api/activities/{collection} - Execute activity in this collection
+    endpoint.post('/', async (c: Context) => {
+        const body = await safeParseJson(c);
+        const payload = parseActivityPayload(body);
+        return coll.execute(c, payload);
+    });
+
+    return endpoint;
+}

package/src/server/app-package.ts

@@ -1,4 +1,4 @@
-import { AppPackage, AppPackageScope, AppWidgetInfo, CatalogInteractionRef, InCodeTypeDefinition } from "@vertesia/common";
+import { AppPackage, AppPackageScope, AppWidgetInfo, CatalogInteractionRef, InCodeTypeDefinition, RemoteActivityDefinition } from "@vertesia/common";
 import { Context, Hono } from "hono";
 import { ToolUseContext } from "../types.js";
 import { ToolServerConfig } from "./types.js";
@@ -103,6 +103,15 @@ const builders: Record<Exclude<AppPackageScope, 'all'>, (pkg: AppPackage, config
             pkg.settings_schema = { ...config.settings };
         }
     },
+    async activities(pkg: AppPackage, config: ToolServerConfig) {
+        const allActivities: RemoteActivityDefinition[] = [];
+        for (const coll of config.activities || []) {
+            for (const def of coll.getActivityDefinitions()) {
+                allActivities.push({ ...def, collection: coll.name });
+            }
+        }
+        pkg.activities = allActivities;
+    },
 }
 
 
@@ -120,6 +129,7 @@ async function handlePackageRequest(c: Context, config: ToolServerConfig) {
         await builders.widgets(pkg, config, c);
         await builders.ui(pkg, config, c);
         await builders.settings(pkg, config, c);
+        await builders.activities(pkg, config, c);
     } else {
         if (scopes.has('tools')) {
             await builders.tools(pkg, config, c);
@@ -140,7 +150,10 @@ async function handlePackageRequest(c: Context, config: ToolServerConfig) {
             await builders.ui(pkg, config, c);
         }
         if (scopes.has('settings')) {
-            builders.settings(pkg, config, c);
+            await builders.settings(pkg, config, c);
+        }
+        if (scopes.has('activities')) {
+            await builders.activities(pkg, config, c);
         }
     }