@vertesia/tools-sdk 1.0.0-dev.20260128.144200 → 1.0.0-dev.20260225.024852Z

package/src/ToolRegistry.ts

@@ -1,27 +1,16 @@
+import { AgentToolDefinition } from "@vertesia/common";
 import { HTTPException } from "hono/http-exception";
-import { Tool, ToolDefinitionWithDefault, ToolExecutionContext, ToolExecutionPayload, ToolExecutionResult } from "./types.js";
+import { Tool, ToolExecutionContext, ToolExecutionPayload, ToolExecutionResult, ToolUseContext } from "./types.js";
 
-/**
- * Options for filtering tool definitions
- */
-export interface ToolFilterOptions {
-    /**
-     * If true, only return tools that are available by default (default !== false).
-     * If false or undefined, return all tools.
-     */
-    defaultOnly?: boolean;
-    /**
-     * List of tool names that are unlocked (available even if default: false).
-     * These tools will be included even when defaultOnly is true.
-     */
-    unlockedTools?: string[];
-}
 
 export class ToolRegistry {
 
+    // The category name usinfg this registry
+    category: string;
     registry: Record<string, Tool<any>> = {};
 
-    constructor(tools: Tool<any>[] = []) {
+    constructor(category: string, tools: Tool<any>[] = []) {
+        this.category = category;
         for (const tool of tools) {
             this.registry[tool.name] = tool;
         }
@@ -32,44 +21,22 @@ export class ToolRegistry {
      * @param options - Filtering options
      * @returns Filtered tool definitions
      */
-    getDefinitions(options?: ToolFilterOptions): ToolDefinitionWithDefault[] {
-        const { defaultOnly, unlockedTools = [] } = options || {};
-        const unlockedSet = new Set(unlockedTools);
-
-        return Object.values(this.registry)
-            .filter(tool => {
-                // If not filtering by default, include all tools
-                if (!defaultOnly) return true;
-
-                // Include if tool is default (default !== false) or is in unlocked list
-                const isDefault = tool.default !== false;
-                const isUnlocked = unlockedSet.has(tool.name);
-                return isDefault || isUnlocked;
-            })
-            .map(tool => ({
-                name: tool.name,
-                description: tool.description,
-                input_schema: tool.input_schema,
-                default: tool.default,
-            }));
-    }
-
-    /**
-     * Get tools that are in reserve (default: false and not unlocked).
-     * @param unlockedTools - List of tool names that are unlocked
-     * @returns Tool definitions for reserve tools
-     */
-    getReserveTools(unlockedTools: string[] = []): ToolDefinitionWithDefault[] {
-        const unlockedSet = new Set(unlockedTools);
-
-        return Object.values(this.registry)
-            .filter(tool => tool.default === false && !unlockedSet.has(tool.name))
-            .map(tool => ({
-                name: tool.name,
-                description: tool.description,
-                input_schema: tool.input_schema,
-                default: tool.default,
-            }));
+    getDefinitions(context?: ToolUseContext): AgentToolDefinition[] {
+        const mapTool = (tool: Tool<any>): AgentToolDefinition => ({
+            url: `tools/${this.category}`,
+            name: tool.name,
+            description: tool.description,
+            input_schema: tool.input_schema,
+            category: this.category,
+            default: tool.default,
+        });
+        let tools = Object.values(this.registry);
+        if (context) {
+            tools = tools.filter(tool => {
+                return tool.isEnabled ? tool.isEnabled(context) : true;
+            });
+        }
+        return tools.map(mapTool);
     }
 
     getTool<ParamsT extends Record<string, any>>(name: string): Tool<ParamsT> {

package/src/index.ts

@@ -1,4 +1,5 @@
 export { authorize, AuthSession } from "./auth.js";
+export * from "./ContentTypesCollection.js";
 export { copyRuntimeAssets } from "./copy-assets.js";
 export * from "./InteractionCollection.js";
 export * from "./server.js";

package/src/server/app-package.ts

@@ -0,0 +1,147 @@
+import { AppPackage, AppPackageScope, AppWidgetInfo, CatalogInteractionRef, InCodeTypeDefinition } from "@vertesia/common";
+import { Context, Hono } from "hono";
+import { ToolUseContext } from "../types.js";
+import { ToolServerConfig } from "./types.js";
+
+function getRequestPayload<T>(c: Context): Promise<T | 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) {
+        const { tools: toolCollections = [], skills: skillCollections = [] } = config;
+
+        const filterContext = await getRequestPayload<ToolUseContext>(c);
+
+        // Aggregate all tools from all collections
+        const allTools = toolCollections.flatMap(collection =>
+            collection.getToolDefinitions(filterContext)
+        );
+
+        // same for skills
+        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 => {
+            if (seen.has(tool.name)) {
+                console.warn(`[app-package] Duplicate tool name "${tool.name}", skipping`);
+                return false;
+            }
+            seen.add(tool.name);
+            return true;
+        });
+    },
+    async interactions(pkg: AppPackage, config: ToolServerConfig) {
+        const allInteractions: CatalogInteractionRef[] = [];
+        for (const coll of (config.interactions || [])) {
+            for (const inter of coll.interactions) {
+                allInteractions.push({
+                    type: "app",
+                    id: coll.name + ":" + inter.name,
+                    name: inter.name,
+                    title: inter.title || inter.name,
+                    description: inter.description,
+                    tags: inter.tags || [],
+                });
+            }
+        }
+        pkg.interactions = allInteractions;
+    },
+    async types(pkg: AppPackage, config: ToolServerConfig) {
+        const allTypes: InCodeTypeDefinition[] = [];
+        for (const coll of config.types || []) {
+            for (const type of coll.types) {
+                allTypes.push({
+                    ...type,
+                    id: coll.name + ":" + type.name
+                });
+            }
+        }
+        pkg.types = allTypes;
+    },
+    async widgets(pkg: AppPackage, config: ToolServerConfig) {
+        const { skills: skillCollections = [] } = config;
+        const widgets: Record<string, AppWidgetInfo> = {};
+        for (const coll of skillCollections) {
+            for (const skill of coll.getSkillDefinitions()) {
+                if (skill.widgets && skill.widgets.length > 0) {
+                    widgets[skill.name] = {
+                        skill: skill.name,
+                        collection: coll.name,
+                        url: `/widgets/${skill.widgets[0]}.js`
+                    } satisfies AppWidgetInfo;
+                }
+            }
+        }
+        pkg.widgets = widgets;
+    },
+    async ui(pkg: AppPackage, config: ToolServerConfig, c: Context) {
+        if (config.uiConfig) {
+            pkg.ui = { ...config.uiConfig };
+            const origin = new URL(c.req.url).origin;
+            pkg.ui.src = new URL(pkg.ui.src, origin).toString();
+            if (!pkg.ui.isolation) {
+                pkg.ui.isolation = "shadow";
+            }
+        }
+    },
+    async settings(pkg: AppPackage, config: ToolServerConfig) {
+        if (config.settings) {
+            pkg.settings_schema = { ...config.settings };
+        }
+    },
+}
+
+
+async function handlePackageRequest(c: Context, config: ToolServerConfig) {
+    const scope = c.req.query('scope') || 'all';
+    const pkg: AppPackage = {};
+
+    const scopes = new Set<AppPackageScope>(scope.split(',') as AppPackageScope[]);
+    // TODO build pkg based on the query param 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.widgets(pkg, config, c);
+        await builders.ui(pkg, config, c);
+        await builders.settings(pkg, config, c);
+    } else {
+        if (scopes.has('tools')) {
+            await builders.tools(pkg, config, c);
+        }
+        if (scopes.has('interactions')) {
+            await builders.interactions(pkg, config, c);
+        }
+        if (scopes.has('types')) {
+            await builders.types(pkg, config, c);
+        }
+        if (scopes.has('widgets')) {
+            await builders.widgets(pkg, config, c);
+        }
+        if (scopes.has('ui')) {
+            await builders.ui(pkg, config, c);
+        }
+        if (scopes.has('settings')) {
+            builders.settings(pkg, config, c);
+        }
+    }
+
+    return c.json(pkg);
+}
+
+export function createPackageRoute(app: Hono, basePath: string, config: ToolServerConfig) {
+
+    app.get(basePath, (c: Context) => {
+        return handlePackageRequest(c, config);
+    });
+
+    app.post(basePath, (c: Context) => {
+        return handlePackageRequest(c, config);
+    });
+
+}

package/src/server/content-types.ts

@@ -0,0 +1,89 @@
+// ================== 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";
+
+export function createContentTypesRoute(app: Hono, basePath: string, config: ToolServerConfig) {
+    const { types = [] } = config;
+
+    // GET /api/types - Returns all interactions from all collections
+    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) });
+            }
+        }
+
+        return c.json({
+            title: 'All Content Types',
+            description: 'All available content types across all collections',
+            types: allTypes,
+            collections: types.map(i => ({
+                name: i.name,
+                title: i.title,
+                description: i.description,
+            })),
+        });
+    });
+
+    // Create interaction collection endpoints
+    for (const coll of types) {
+        app.route(`${basePath}/${coll.name}`, createContentTypeEndpoints(coll));
+    }
+
+    // GET /api/types/:name - Direct access to content type
+    app.get(`${basePath}/:name`, async (c) => {
+        const name = c.req.param('name');
+        const parts = name.split(':');
+        if (parts.length !== 2) {
+            throw new HTTPException(400, {
+                message: "Invalid content type name. Expected format 'collection:type'"
+            });
+        }
+        const collName = parts[0];
+        const typeName = toPathName(parts[1]);
+        const ctype = types.find(t => t.name === collName)?.getTypeByName(typeName);
+        if (ctype) {
+            return c.json({ ...ctype, id: collName + ":" + typeName });
+        }
+
+        throw new HTTPException(404, {
+            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) })));
+    });
+
+    endpoint.get('/:name', (c: Context) => {
+        const name = c.req.param('name');
+        const ctype = coll.types.find(t => toPathName(t.name) === name);
+        if (!ctype) {
+            throw new HTTPException(404, {
+                message: "No content type found with name: " + name
+            });
+        }
+        return c.json({
+            ...ctype,
+            id: coll.name + ":" + toPathName(ctype.name)
+        });
+    });
+
+
+    return endpoint;
+}

package/src/server/interactions.ts

@@ -18,7 +18,7 @@ export function createInteractionsRoute(app: Hono, basePath: string, config: Too
             for (const inter of coll.interactions) {
                 allInteractions.push({
                     type: "app",
-                    id: inter.name,
+                    id: coll.name + ":" + inter.name,
                     name: inter.name,
                     title: inter.title || inter.name,
                     description: inter.description,
@@ -44,6 +44,29 @@ export function createInteractionsRoute(app: Hono, basePath: string, config: Too
         app.route(`${basePath}/${coll.name}`, createInteractionEndpoints(coll));
     }
 
+    // GET /api/interactions/:name - Direct access to interaction by name (searches all collections)
+    app.get(`${basePath}/:name`, async (c) => {
+        await authorize(c);
+        const name = c.req.param('name');
+
+        const parts = name.split(':');
+        if (parts.length !== 2) {
+            throw new HTTPException(400, {
+                message: "Invalid interaction name. Expected format 'collection:interaction'"
+            });
+        }
+        const collName = parts[0];
+        const interName = parts[1];
+        const inter = interactions.find(t => t.name === collName)?.getInteractionByName(interName);
+        if (inter) {
+            return c.json({ ...inter, id: collName + ":" + interName });
+        }
+
+        throw new HTTPException(404, {
+            message: "No interaction found with name: " + name
+        });
+    });
+
 }
 
 
@@ -55,7 +78,7 @@ function createInteractionEndpoints(coll: InteractionCollection): Hono {
     endpoint.get('/', (c: Context) => {
         return c.json(coll.interactions.map(inter => ({
             type: "app",
-            id: inter.name,
+            id: coll.name + ":" + inter.name,
             name: inter.name,
             title: inter.title || inter.name,
             description: inter.description,
@@ -72,7 +95,10 @@ function createInteractionEndpoints(coll: InteractionCollection): Hono {
                 message: "No interaction found with name: " + name
             });
         }
-        return c.json(inter);
+        return c.json({
+            ...inter,
+            id: coll.name + ":" + inter.name,
+        });
     });
 
     return endpoint;

package/src/server/site.ts

@@ -1,5 +1,6 @@
 import { Hono } from "hono";
 import {
+    contentTypeCollectionPage,
     indexPage,
     interactionCollectionPage,
     skillCollectionPage,
@@ -12,6 +13,7 @@ export function createSiteRoute(app: Hono, basePath: string, config: ToolServerC
     const {
         tools = [],
         interactions = [],
+        types = [],
         skills = [],
     } = config;
 
@@ -41,4 +43,11 @@ export function createSiteRoute(app: Hono, basePath: string, config: ToolServerC
         });
     }
 
+    // Content type collection pages
+    for (const coll of types) {
+        app.get(`${basePath}/types/${coll.name}`, (c) => {
+            return c.html(contentTypeCollectionPage(coll));
+        });
+    }
+
 }

package/src/server/tools.ts

@@ -22,20 +22,11 @@ export function createToolsRoute(app: Hono, basePath: string, config: ToolServer
 
     app.get(basePath, (c) => {
         const url = new URL(c.req.url);
-        const defaultOnly = c.req.query('defaultOnly') === 'true';
-        const unlockedParam = c.req.query('unlocked');
-        const unlockedTools = unlockedParam ? unlockedParam.split(',').map(t => t.trim()).filter(Boolean) : [];
-
-        const filterOptions = defaultOnly ? { defaultOnly, unlockedTools } : undefined;
 
         const allTools: ToolDefinition[] = [];
-        let reserveToolCount = 0;
 
         for (const coll of tools) {
-            allTools.push(...coll.getToolDefinitions(filterOptions));
-            if (defaultOnly) {
-                reserveToolCount += coll.getReserveTools(unlockedTools).length;
-            }
+            allTools.push(...coll.getToolDefinitions());
         }
 
         return c.json({
@@ -43,7 +34,6 @@ export function createToolsRoute(app: Hono, basePath: string, config: ToolServer
             title: 'All Tools',
             description: 'All available tools across all collections',
             tools: allTools,
-            reserveToolCount: defaultOnly ? reserveToolCount : undefined,
             collections: tools.map(t => ({
                 name: t.name,
                 title: t.title,
@@ -97,27 +87,18 @@ function createToolEndpoints(coll: ToolCollection): Hono {
     //   - unlocked=tool1,tool2: Comma-separated list of unlocked tool names
     endpoint.get('/', (c) => {
         const importSourceUrl = c.req.query('import') != null;
-        const defaultOnly = c.req.query('defaultOnly') === 'true';
-        const unlockedParam = c.req.query('unlocked');
-        const unlockedTools = unlockedParam ? unlockedParam.split(',').map(t => t.trim()).filter(Boolean) : [];
 
-        const filterOptions = defaultOnly ? { defaultOnly, unlockedTools } : undefined;
         const url = new URL(c.req.url);
 
-        const response: ToolCollectionDefinition & { reserveToolCount?: number } = {
+        const response: ToolCollectionDefinition = {
             src: importSourceUrl
                 ? `${url.origin}/libs/vertesia-tools-${coll.name}.js`
                 : `${url.origin}${url.pathname}`,
             title: coll.title || coll.name,
             description: coll.description || '',
-            tools: coll.getToolDefinitions(filterOptions)
+            tools: coll.getToolDefinitions()
         };
 
-        // Include reserve count when filtering
-        if (defaultOnly) {
-            response.reserveToolCount = coll.getReserveTools(unlockedTools).length;
-        }
-
         return c.json(response);
     });
 

package/src/server/types.ts

@@ -3,6 +3,9 @@ import { InteractionCollection } from "../InteractionCollection.js";
 import { SkillCollection } from "../SkillCollection.js";
 import { ToolCollection } from "../ToolCollection.js";
 import { ToolExecutionPayload } from "../types.js";
+import { JSONSchema } from "@llumiverse/common";
+import { AppUIConfig, ProjectConfiguration } from "@vertesia/common";
+import { ContentTypesCollection } from "../ContentTypesCollection.js";
 
 /**
  * Extended context with parsed payload for tool/skill execution
@@ -49,6 +52,10 @@ export interface ToolServerConfig {
      * Interaction collections to expose
      */
     interactions?: InteractionCollection[];
+    /**
+     * Content type collections to expose
+     */
+    types?: ContentTypesCollection[];
     /**
      * Skill collections to expose
      */
@@ -57,6 +64,17 @@ export interface ToolServerConfig {
      * MCP providers to expose
      */
     mcpProviders?: MCPProviderConfig[];
+
+    /**
+     * A JSON schema defining settings for the application using this server
+     */
+    settings?: JSONSchema;
+
+    /**
+     * The UI configuration for the application using this server
+     */
+    uiConfig?: AppUIConfig;
+
     /**
      * Disable HTML pages (default: false)
      */
@@ -65,5 +83,13 @@ export interface ToolServerConfig {
      * Hide UI app links on the index page (default: false)
      */
     hideUILinks?: boolean;
+
+    /**
+     * If a filter is provided, it will be called with the project configuration when requesting tool definitions, and can be used to filter which tools are returned based on the project configuration. 
+     * This allows for dynamic enabling/disabling of tools based on project settings.
+     * @param projectConfig 
+     * @returns 
+     */
+    toolFilter?: (projectConfig: ProjectConfiguration) => boolean;
 }
 

package/src/server/widgets.ts

@@ -1,11 +1,7 @@
+import { AppWidgetInfo } from "@vertesia/common";
 import { Hono } from "hono";
 import { ToolServerConfig } from "./types.js";
 
-export interface WidgetInfo {
-    collection: string;
-    skill: string;
-    url: string;
-}
 
 export function createWidgetsRoute(app: Hono, basePath: string, config: ToolServerConfig) {
 
@@ -15,7 +11,7 @@ export function createWidgetsRoute(app: Hono, basePath: string, config: ToolServ
     app.get(basePath, (c) => {
         const url = new URL(c.req.url);
 
-        const widgets: Record<string, WidgetInfo> = {};
+        const widgets: Record<string, AppWidgetInfo> = {};
         for (const coll of skills) {
             const collWidgets = coll.getWidgets();
             for (const widget of collWidgets) {

package/src/server.ts

@@ -10,6 +10,8 @@ import { createToolsRoute } from "./server/tools.js";
 import { ToolContext, ToolServerConfig } from "./server/types.js";
 import { ToolExecutionPayload } from "./types.js";
 import { createWidgetsRoute } from "./server/widgets.js";
+import { createPackageRoute } from "./server/app-package.js";
+import { createContentTypesRoute } from "./server/content-types.js";
 
 // Schema for tool execution payload
 const ToolExecutionPayloadSchema = z.object({
@@ -98,10 +100,13 @@ export function createToolServer(config: ToolServerConfig): Hono {
         });
     });
 
+
+    createPackageRoute(app, `${prefix}/package`, config);
     createToolsRoute(app, `${prefix}/tools`, config);
     createSkillsRoute(app, `${prefix}/skills`, config);
     createWidgetsRoute(app, `${prefix}/widgets`, config);
     createInteractionsRoute(app, `${prefix}/interactions`, config);
+    createContentTypesRoute(app, `${prefix}/types`, config);
     createMcpRoute(app, `${prefix}/mcp`, config);
 
 

package/src/site/styles.ts

@@ -396,6 +396,43 @@ hr {
     font-family: ui-monospace, monospace;
 }
 
+.endpoint-box {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    background: #f3f4f6;
+    padding: 0.75rem 1rem;
+    border-radius: 8px;
+    margin-top: 0.5rem;
+}
+
+.endpoint-box code {
+    flex: 1;
+    font-family: ui-monospace, monospace;
+    font-size: 0.875rem;
+    color: #1f2937;
+}
+
+.copy-btn {
+    background: #e5e7eb;
+    border: none;
+    padding: 0.5rem;
+    border-radius: 6px;
+    cursor: pointer;
+    color: #6b7280;
+    transition: all 0.15s;
+}
+
+.copy-btn:hover {
+    background: #d1d5db;
+    color: #374151;
+}
+
+.copy-btn svg {
+    width: 16px;
+    height: 16px;
+}
+
 .badge {
     display: inline-block;
     font-size: 0.75rem;
@@ -583,6 +620,24 @@ hr {
         background: rgba(15, 23, 42, 0.95);
     }
 
+    .endpoint-box {
+        background: rgba(31, 41, 55, 0.95);
+    }
+
+    .endpoint-box code {
+        color: #e5e7eb;
+    }
+
+    .copy-btn {
+        background: rgba(55, 65, 81, 0.95);
+        color: #e5e7eb;
+    }
+
+    .copy-btn:hover {
+        background: rgba(75, 85, 99, 0.98);
+        color: #f9fafb;
+    }
+
     .badge {
         background: rgba(15, 23, 42, 0.96);
         color: #e5e7eb;