@vertesia/tools-sdk 1.2.0 → 1.4.0-dev.20260615.042549Z

package/src/server/app-package.test.ts

@@ -0,0 +1,140 @@
+import { PromptRole } from '@llumiverse/common';
+import { PROCESS_DEFINITION_FORMAT_VERSION, TemplateType } from '@vertesia/common';
+import { describe, expect, it } from 'vitest';
+import { ContentTypesCollection } from '../ContentTypesCollection.js';
+import { InteractionCollection } from '../InteractionCollection.js';
+import { buildAppPackage } from './app-package.js';
+import type { ToolServerConfig } from './types.js';
+
+describe('buildAppPackage', () => {
+    it('builds the same package artifact inventory used by the package route', async () => {
+        const config = {
+            interactions: [
+                new InteractionCollection({
+                    name: 'claims',
+                    interactions: [
+                        {
+                            name: 'review',
+                            title: 'Review Claim',
+                            prompts: [
+                                {
+                                    role: PromptRole.user,
+                                    content: '{{user_prompt}}',
+                                    content_type: TemplateType.handlebars,
+                                },
+                            ],
+                        },
+                    ],
+                }),
+            ],
+            types: [
+                new ContentTypesCollection({
+                    name: 'claims',
+                    types: [
+                        {
+                            name: 'claim',
+                            object_schema: {
+                                type: 'object',
+                                properties: {
+                                    status: { type: 'string' },
+                                },
+                            },
+                        },
+                    ],
+                }),
+            ],
+            processes: [
+                {
+                    id: 'claims:intake',
+                    name: 'Claims Intake',
+                    definition: {
+                        format_version: PROCESS_DEFINITION_FORMAT_VERSION,
+                        process: 'claims_intake',
+                        initial: 'done',
+                        context: {
+                            schema: {
+                                type: 'object',
+                                additionalProperties: true,
+                            },
+                            initial: {},
+                        },
+                        nodes: {
+                            done: { type: 'final', title: 'Done' },
+                        },
+                    },
+                },
+            ],
+            dashboards: [
+                {
+                    id: 'claims:ops',
+                    title: 'Claims Ops',
+                    spec: {},
+                },
+            ],
+            uiConfig: {
+                src: '/lib/plugin.js',
+                available_in: ['app_portal'],
+            },
+        } satisfies ToolServerConfig;
+
+        const pkg = await buildAppPackage(config, {
+            origin: 'https://apps.example.test',
+            scope: 'all',
+        });
+
+        expect(pkg.interactions?.map((interaction) => interaction.id)).toEqual(['claims:review']);
+        expect(pkg.types?.map((type) => type.id)).toEqual(['claim']);
+        expect(pkg.processes?.map((process) => process.id)).toEqual(['claims:intake']);
+        expect(pkg.dashboards?.map((dashboard) => dashboard.id)).toEqual(['claims:ops']);
+        expect(pkg.ui?.src).toBe('https://apps.example.test/lib/plugin.js');
+    });
+
+    it('honors package scopes', async () => {
+        const config = {
+            interactions: [
+                new InteractionCollection({
+                    name: 'claims',
+                    interactions: [{ name: 'review', prompts: [] }],
+                }),
+            ],
+            types: [
+                new ContentTypesCollection({
+                    name: 'claims',
+                    types: [{ name: 'claim' }],
+                }),
+            ],
+        } satisfies ToolServerConfig;
+
+        const pkg = await buildAppPackage(config, { scope: 'types' });
+
+        expect(pkg.types?.map((type) => type.id)).toEqual(['claim']);
+        expect(pkg.interactions).toBeUndefined();
+    });
+});
+
+describe('buildAppPackage type identity', () => {
+    it('exposes the bare type name as the public id (collections are code organization only)', async () => {
+        const config = {
+            types: [
+                new ContentTypesCollection({ name: 'claims', types: [{ name: 'claim' }] }),
+                new ContentTypesCollection({ name: 'audit', types: [{ name: 'audit_event' }] }),
+            ],
+        } satisfies ToolServerConfig;
+
+        const pkg = await buildAppPackage(config, { scope: 'types' });
+        expect(pkg.types?.map((type) => type.id)).toEqual(['claim', 'audit_event']);
+    });
+
+    it('fails the package build when a type name is duplicated across collections', async () => {
+        const config = {
+            types: [
+                new ContentTypesCollection({ name: 'claims', types: [{ name: 'claim' }] }),
+                new ContentTypesCollection({ name: 'legacy', types: [{ name: 'claim' }] }),
+            ],
+        } satisfies ToolServerConfig;
+
+        await expect(buildAppPackage(config, { scope: 'types' })).rejects.toThrow(
+            /Duplicate content type name 'claim'/,
+        );
+    });
+});

package/src/server/app-package.ts

@@ -1,32 +1,45 @@
-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";
+import type {
+    AppDashboardDefinition,
+    AppPackage,
+    AppPackageScope,
+    AppWidgetInfo,
+    CatalogInteractionRef,
+    InCodeProcessDefinition,
+    InCodeTypeDefinition,
+    RemoteActivityDefinition,
+} from '@vertesia/common';
+import type { Context, Hono } from 'hono';
+import type { ToolUseContext } from '../types.js';
+import type { ToolServerConfig } from './types.js';
 
 function getRequestPayload<T>(c: Context): Promise<T | undefined> {
-    return c.req.method === "POST" ? c.req.json<T>() : Promise.resolve(undefined);
+    return c.req.method === 'POST' ? c.req.json<T>() : Promise.resolve(undefined);
 }
 
-const builders: Record<Exclude<AppPackageScope, 'all'>, (pkg: AppPackage, config: ToolServerConfig, c: Context) => Promise<void>> = {
-    async tools(pkg: AppPackage, config: ToolServerConfig, c: Context) {
+export interface BuildAppPackageOptions {
+    scope?: AppPackageScope | AppPackageScope[] | string;
+    origin?: string;
+    toolUseContext?: ToolUseContext;
+}
+
+type AppPackageBuilder = (pkg: AppPackage, config: ToolServerConfig, options: BuildAppPackageOptions) => Promise<void>;
+
+const builders: Record<Exclude<AppPackageScope, 'all'>, AppPackageBuilder> = {
+    async tools(pkg: AppPackage, config: ToolServerConfig, options: BuildAppPackageOptions) {
         const { tools: toolCollections = [], skills: skillCollections = [] } = config;
 
-        const filterContext = await getRequestPayload<ToolUseContext>(c);
+        const filterContext = options.toolUseContext;
 
         // Aggregate all tools from all collections
-        const allTools = toolCollections.flatMap(collection =>
-            collection.getToolDefinitions(filterContext)
-        );
+        const allTools = toolCollections.flatMap((collection) => collection.getToolDefinitions(filterContext));
 
         // same for skills
-        const allSkills = skillCollections.flatMap(collection =>
-            collection.getToolDefinitions(filterContext)
-        );
+        const allSkills = skillCollections.flatMap((collection) => collection.getToolDefinitions(filterContext));
 
         // Deduplicate by tool name (skills listed first take priority)
         const seen = new Set<string>();
         const combined = allSkills.concat(allTools);
-        pkg.tools = combined.filter(tool => {
+        pkg.tools = combined.filter((tool) => {
             if (seen.has(tool.name)) {
                 console.warn(`[app-package] Duplicate tool name "${tool.name}", skipping`);
                 return false;
@@ -37,11 +50,11 @@ const builders: Record<Exclude<AppPackageScope, 'all'>, (pkg: AppPackage, config
     },
     async interactions(pkg: AppPackage, config: ToolServerConfig) {
         const allInteractions: CatalogInteractionRef[] = [];
-        for (const coll of (config.interactions || [])) {
+        for (const coll of config.interactions || []) {
             for (const inter of coll.interactions) {
                 allInteractions.push({
-                    type: "app",
-                    id: coll.name + ":" + inter.name,
+                    type: 'app',
+                    id: `${coll.name}:${inter.name}`,
                     name: inter.name,
                     title: inter.title || inter.name,
                     description: inter.description,
@@ -52,26 +65,56 @@ const builders: Record<Exclude<AppPackageScope, 'all'>, (pkg: AppPackage, config
         pkg.interactions = allInteractions;
     },
     async types(pkg: AppPackage, config: ToolServerConfig) {
+        // A type's public id is its BARE name: stored objects reference it as the portable
+        // `app:<app>:<type>` string, so the in-code collection (a code-organization grouping,
+        // unlike tool/skill collections which are semantic) must NOT leak into the id.
+        // Names must therefore be unique across collections — fail the package build otherwise.
         const allTypes: InCodeTypeDefinition[] = [];
+        const seen = new Map<string, string>();
         for (const coll of config.types || []) {
             for (const type of coll.types) {
-                allTypes.push({
-                    ...type,
-                    id: coll.name + ":" + type.name
-                });
+                const existing = seen.get(type.name);
+                if (existing) {
+                    throw new Error(
+                        `Duplicate content type name '${type.name}' (collections '${existing}' and '${coll.name}'). ` +
+                            `Type names must be unique across collections so the portable 'app:<app>:${type.name}' ref resolves.`,
+                    );
+                }
+                seen.set(type.name, coll.name);
+                allTypes.push({ ...type, id: type.name });
             }
         }
         pkg.types = allTypes;
     },
+    async processes(pkg: AppPackage, config: ToolServerConfig) {
+        const allProcesses: InCodeProcessDefinition[] = [];
+        for (const process of config.processes || []) {
+            allProcesses.push(process);
+        }
+        pkg.processes = allProcesses;
+    },
     async templates(pkg: AppPackage, config: ToolServerConfig) {
         const basePath = `${config.prefix || '/api'}/templates`;
-        pkg.templates = (config.templates || []).flatMap(coll =>
+        pkg.templates = (config.templates || []).flatMap((coll) =>
             coll.templates.map(({ instructions: _, ...ref }) => ({
                 ...ref,
                 path: `${basePath}/${coll.name}/${ref.name}`,
-            }))
+            })),
         );
     },
+    async dashboards(pkg: AppPackage, config: ToolServerConfig) {
+        const seen = new Set<string>();
+        const dashboards: AppDashboardDefinition[] = [];
+        for (const dashboard of config.dashboards || []) {
+            if (seen.has(dashboard.id)) {
+                console.warn(`[app-package] Duplicate dashboard id "${dashboard.id}", skipping`);
+                continue;
+            }
+            seen.add(dashboard.id);
+            dashboards.push(dashboard);
+        }
+        pkg.dashboards = dashboards;
+    },
     async widgets(pkg: AppPackage, config: ToolServerConfig) {
         const { skills: skillCollections = [] } = config;
         const widgets: Record<string, AppWidgetInfo> = {};
@@ -81,20 +124,20 @@ const builders: Record<Exclude<AppPackageScope, 'all'>, (pkg: AppPackage, config
                     widgets[skill.name] = {
                         skill: skill.name,
                         collection: coll.name,
-                        url: `/widgets/${skill.widgets[0]}.js`
+                        url: `/widgets/${skill.widgets[0]}.js`,
                     } satisfies AppWidgetInfo;
                 }
             }
         }
         pkg.widgets = widgets;
     },
-    async ui(pkg: AppPackage, config: ToolServerConfig, c: Context) {
+    async ui(pkg: AppPackage, config: ToolServerConfig, options: BuildAppPackageOptions) {
         if (config.uiConfig) {
             pkg.ui = { ...config.uiConfig };
-            const origin = new URL(c.req.url).origin;
+            const origin = options.origin || 'http://localhost';
             pkg.ui.src = new URL(pkg.ui.src, origin).toString();
             if (!pkg.ui.isolation) {
-                pkg.ui.isolation = "shadow";
+                pkg.ui.isolation = 'shadow';
             }
         }
     },
@@ -112,56 +155,77 @@ const builders: Record<Exclude<AppPackageScope, 'all'>, (pkg: AppPackage, config
         }
         pkg.activities = allActivities;
     },
-}
+};
 
+function normalizeScopes(scope: BuildAppPackageOptions['scope']): Set<AppPackageScope> {
+    const values = Array.isArray(scope) ? scope : typeof scope === 'string' ? scope.split(',') : [scope || 'all'];
+    return new Set(values.filter(Boolean) as AppPackageScope[]);
+}
 
-async function handlePackageRequest(c: Context, config: ToolServerConfig) {
-    const scope = c.req.query('scope') || 'all';
+export async function buildAppPackage(
+    config: ToolServerConfig,
+    options: BuildAppPackageOptions = {},
+): Promise<AppPackage> {
     const pkg: AppPackage = {};
 
-    const scopes = new Set<AppPackageScope>(scope.split(',') as AppPackageScope[]);
-    // TODO build pkg based on the query param scope
+    const scopes = normalizeScopes(options.scope);
     if (scopes.has('all')) {
-        await builders.tools(pkg, config, c);
-        await builders.interactions(pkg, config, c);
-        await builders.types(pkg, config, c);
-        await builders.templates(pkg, config, c);
-        await builders.widgets(pkg, config, c);
-        await builders.ui(pkg, config, c);
-        await builders.settings(pkg, config, c);
-        await builders.activities(pkg, config, c);
+        await builders.tools(pkg, config, options);
+        await builders.interactions(pkg, config, options);
+        await builders.types(pkg, config, options);
+        await builders.processes(pkg, config, options);
+        await builders.templates(pkg, config, options);
+        await builders.dashboards(pkg, config, options);
+        await builders.widgets(pkg, config, options);
+        await builders.ui(pkg, config, options);
+        await builders.settings(pkg, config, options);
+        await builders.activities(pkg, config, options);
     } else {
         if (scopes.has('tools')) {
-            await builders.tools(pkg, config, c);
+            await builders.tools(pkg, config, options);
         }
         if (scopes.has('interactions')) {
-            await builders.interactions(pkg, config, c);
+            await builders.interactions(pkg, config, options);
         }
         if (scopes.has('types')) {
-            await builders.types(pkg, config, c);
+            await builders.types(pkg, config, options);
+        }
+        if (scopes.has('processes')) {
+            await builders.processes(pkg, config, options);
         }
         if (scopes.has('templates')) {
-            await builders.templates(pkg, config, c);
+            await builders.templates(pkg, config, options);
+        }
+        if (scopes.has('dashboards')) {
+            await builders.dashboards(pkg, config, options);
         }
         if (scopes.has('widgets')) {
-            await builders.widgets(pkg, config, c);
+            await builders.widgets(pkg, config, options);
         }
         if (scopes.has('ui')) {
-            await builders.ui(pkg, config, c);
+            await builders.ui(pkg, config, options);
         }
         if (scopes.has('settings')) {
-            await builders.settings(pkg, config, c);
+            await builders.settings(pkg, config, options);
         }
         if (scopes.has('activities')) {
-            await builders.activities(pkg, config, c);
+            await builders.activities(pkg, config, options);
         }
     }
 
+    return pkg;
+}
+
+async function handlePackageRequest(c: Context, config: ToolServerConfig) {
+    const pkg = await buildAppPackage(config, {
+        scope: c.req.query('scope') || 'all',
+        origin: new URL(c.req.url).origin,
+        toolUseContext: await getRequestPayload<ToolUseContext>(c),
+    });
     return c.json(pkg);
 }
 
 export function createPackageRoute(app: Hono, basePath: string, config: ToolServerConfig) {
-
     app.get(basePath, (c: Context) => {
         return handlePackageRequest(c, config);
     });
@@ -169,5 +233,4 @@ export function createPackageRoute(app: Hono, basePath: string, config: ToolServ
     app.post(basePath, (c: Context) => {
         return handlePackageRequest(c, config);
     });
-
-}
+}

package/src/server/content-types.test.ts

@@ -0,0 +1,64 @@
+import { Hono } from 'hono';
+import { describe, expect, it } from 'vitest';
+import { ContentTypesCollection } from '../ContentTypesCollection.js';
+import { createContentTypesRoute } from './content-types.js';
+import type { ToolServerConfig } from './types.js';
+
+function makeApp(config: ToolServerConfig): Hono {
+    const app = new Hono();
+    createContentTypesRoute(app, '/api/types', config);
+    return app;
+}
+
+const config = {
+    types: [
+        new ContentTypesCollection({
+            name: 'contracts',
+            types: [{ name: 'contract' }, { name: 'review_note' }],
+        }),
+        new ContentTypesCollection({
+            name: 'audit',
+            types: [{ name: 'audit_event' }],
+        }),
+    ],
+} satisfies ToolServerConfig;
+
+describe('content types route', () => {
+    it('lists all types with bare ids (collection is not part of the type identity)', async () => {
+        const res = await makeApp(config).request('/api/types');
+        expect(res.status).toBe(200);
+        const body = (await res.json()) as { types: Array<{ id: string }> };
+        expect(body.types.map((t) => t.id)).toEqual(['contract', 'review_note', 'audit_event']);
+    });
+
+    it('resolves the canonical bare type name (the app:<app>:<type> ref convention)', async () => {
+        const res = await makeApp(config).request('/api/types/contract');
+        expect(res.status).toBe(200);
+        const body = (await res.json()) as { id: string; name: string };
+        expect(body.id).toBe('contract');
+        expect(body.name).toBe('contract');
+    });
+
+    it('still resolves the legacy collection:type alias, returning the bare id', async () => {
+        const res = await makeApp(config).request('/api/types/contracts:contract');
+        expect(res.status).toBe(200);
+        const body = (await res.json()) as { id: string };
+        expect(body.id).toBe('contract');
+    });
+
+    it('409s on an ambiguous bare name so the collision is loud, not silent', async () => {
+        const ambiguous = {
+            types: [
+                new ContentTypesCollection({ name: 'a', types: [{ name: 'note' }] }),
+                new ContentTypesCollection({ name: 'b', types: [{ name: 'note' }] }),
+            ],
+        } satisfies ToolServerConfig;
+        const res = await makeApp(ambiguous).request('/api/types/note');
+        expect(res.status).toBe(409);
+    });
+
+    it('404s for an unknown type name', async () => {
+        const res = await makeApp(config).request('/api/types/nope');
+        expect(res.status).toBe(404);
+    });
+});

package/src/server/content-types.ts

@@ -1,22 +1,24 @@
 // ================== Content Type Endpoints ==================
 
-import { InCodeTypeDefinition } from "@vertesia/common";
-import { Context, Hono } from "hono";
-import { HTTPException } from "hono/http-exception";
-import { ContentTypesCollection } from "../ContentTypesCollection.js";
-import { ToolServerConfig } from "./types.js";
-import { toPathName } from "../utils.js";
+import type { InCodeTypeDefinition } from '@vertesia/common';
+import { type Context, Hono } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import type { ContentTypesCollection } from '../ContentTypesCollection.js';
+import { toPathName } from '../utils.js';
+import type { ToolServerConfig } from './types.js';
 
 export function createContentTypesRoute(app: Hono, basePath: string, config: ToolServerConfig) {
     const { types = [] } = config;
 
-    // GET /api/types - Returns all interactions from all collections
+    // GET /api/types - Returns all content types from all collections.
+    // A type's public id is its declared BARE name, verbatim (`app:<app>:<type>` once
+    // app-prefixed): collections organize code, they are not part of the type identity.
     app.get(basePath, (c) => {
         const allTypes: InCodeTypeDefinition[] = [];
 
         for (const coll of types) {
             for (const type of coll.types) {
-                allTypes.push({ ...type, id: coll.name + ":" + toPathName(type.name) });
+                allTypes.push({ ...type, id: type.name });
             }
         }
 
@@ -24,7 +26,7 @@ export function createContentTypesRoute(app: Hono, basePath: string, config: Too
             title: 'All Content Types',
             description: 'All available content types across all collections',
             types: allTypes,
-            collections: types.map(i => ({
+            collections: types.map((i) => ({
                 name: i.name,
                 title: i.title,
                 description: i.description,
@@ -37,53 +39,79 @@ export function createContentTypesRoute(app: Hono, basePath: string, config: Too
         app.route(`${basePath}/${coll.name}`, createContentTypeEndpoints(coll));
     }
 
-    // GET /api/types/:name - Direct access to content type
+    // GET /api/types/:name - Direct access to content type.
+    // Canonical form is the BARE type name (`<type>`), matching the portable
+    // `app:<app>:<type>` ref convention used by objects.create/search — the
+    // collection is an in-code grouping, not part of the type's public id.
+    // `<collection>:<type>` is also accepted as a backward-compatible alias.
     app.get(`${basePath}/:name`, async (c) => {
         const name = c.req.param('name');
         const parts = name.split(':');
+        if (parts.length === 1) {
+            // Match the declared name verbatim; fall back to the toPathName variant for
+            // leniency with legacy refs that used the path-mangled form.
+            const matches = types.flatMap((coll) =>
+                coll.types
+                    .filter((t) => t.name === name || toPathName(t.name) === name)
+                    .map((t) => ({ coll, type: t })),
+            );
+            if (matches.length === 1) {
+                return c.json({ ...matches[0].type, id: matches[0].type.name });
+            }
+            if (matches.length > 1) {
+                const colls = matches.map((m) => m.coll.name).join(', ');
+                throw new HTTPException(409, {
+                    message:
+                        `Ambiguous content type name '${name}': defined in collections ${colls}. ` +
+                        'Type names must be unique across collections so the portable ' +
+                        `'app:<app>:${name}' ref resolves; rename one of them, or address it as '<collection>:<type>'.`,
+                });
+            }
+            throw new HTTPException(404, {
+                message: `No content type found with name: ${name}`,
+            });
+        }
         if (parts.length !== 2) {
             throw new HTTPException(400, {
-                message: "Invalid content type name. Expected format 'collection:type'"
+                message: "Invalid content type name. Expected '<type>' or 'collection:type'",
             });
         }
         const collName = parts[0];
-        const typeName = toPathName(parts[1]);
-        const ctype = types.find(t => t.name === collName)?.getTypeByName(typeName);
+        const typeName = parts[1];
+        const ctype = types
+            .find((t) => t.name === collName)
+            ?.types.find((t) => t.name === typeName || toPathName(t.name) === toPathName(typeName));
         if (ctype) {
-            return c.json({ ...ctype, id: collName + ":" + typeName });
+            // Alias lookup still returns the canonical bare id.
+            return c.json({ ...ctype, id: ctype.name });
         }
 
         throw new HTTPException(404, {
-            message: "No content type found with name: " + name
+            message: `No content type found with name: ${name}`,
         });
     });
-
 }
 
-
-
-
 function createContentTypeEndpoints(coll: ContentTypesCollection): Hono {
     const endpoint = new Hono();
 
     endpoint.get('/', (c: Context) => {
-        return c.json(coll.types.map(t => ({ ...t, id: coll.name + ":" + toPathName(t.name) })));
+        return c.json(coll.types.map((t) => ({ ...t, id: t.name })));
     });
 
     endpoint.get('/:name', (c: Context) => {
         const name = c.req.param('name');
-        const ctype = coll.types.find(t => toPathName(t.name) === name);
+        const ctype = coll.types.find((t) => t.name === name || toPathName(t.name) === name);
         if (!ctype) {
             throw new HTTPException(404, {
-                message: "No content type found with name: " + name
+                message: `No content type found with name: ${name}`,
             });
         }
         return c.json({
             ...ctype,
-            id: coll.name + ":" + toPathName(ctype.name)
+            id: ctype.name,
         });
     });
 
-
     return endpoint;
-}
+}

package/src/server/dashboards.ts

@@ -0,0 +1,31 @@
+import type { AppDashboardDefinition } from '@vertesia/common';
+import type { Hono } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import type { ToolServerConfig } from './types.js';
+
+export function createDashboardsRoute(app: Hono, basePath: string, config: ToolServerConfig) {
+    const { dashboards = [] } = config;
+
+    app.get(basePath, (c) => {
+        return c.json({
+            title: 'All Dashboards',
+            description: 'All available dashboard definitions',
+            dashboards,
+        });
+    });
+
+    app.get(`${basePath}/:id`, (c) => {
+        const id = c.req.param('id');
+        const dashboard = findDashboard(dashboards, id);
+        if (!dashboard) {
+            throw new HTTPException(404, {
+                message: `No dashboard found with id: ${id}`,
+            });
+        }
+        return c.json(dashboard);
+    });
+}
+
+function findDashboard(dashboards: AppDashboardDefinition[], id: string): AppDashboardDefinition | undefined {
+    return dashboards.find((dashboard) => dashboard.id === id || dashboard.name === id || dashboard.title === id);
+}