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

package/src/ToolRegistry.ts

@@ -1,22 +1,7 @@
 import { AgentToolDefinition } from "@vertesia/common";
 import { HTTPException } from "hono/http-exception";
-import { Tool, 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 {
 
@@ -36,46 +21,22 @@ export class ToolRegistry {
      * @param options - Filtering options
      * @returns Filtered tool definitions
      */
-    getDefinitions(options?: ToolFilterOptions): AgentToolDefinition[] {
-        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,
-                category: this.category,
-                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[] = []): AgentToolDefinition[] {
-        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,
-                category: this.category,
-                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/server/app-package.ts

@@ -1,25 +1,41 @@
-import { AppPackage, AppPackageScope, CatalogInteractionRef, InCodeTypeDefinition } from "@vertesia/common";
+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) => void> = {
-    tools(pkg: AppPackage, config: ToolServerConfig) {
+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()
+            collection.getToolDefinitions(filterContext)
         );
 
         // same for skills
         const allSkills = skillCollections.flatMap(collection =>
-            collection.getToolDefinitions()
+            collection.getToolDefinitions(filterContext)
         );
 
-        pkg.tools = allSkills.concat(allTools);
+        // 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;
+        });
     },
-    interactions(pkg: AppPackage, config: ToolServerConfig) {
+    async interactions(pkg: AppPackage, config: ToolServerConfig) {
         const allInteractions: CatalogInteractionRef[] = [];
         for (const coll of (config.interactions || [])) {
             for (const inter of coll.interactions) {
@@ -35,16 +51,35 @@ const builders: Record<Exclude<AppPackageScope, 'all'>, (pkg: AppPackage, config
         }
         pkg.interactions = allInteractions;
     },
-    types(pkg: AppPackage, config: ToolServerConfig) {
+    async types(pkg: AppPackage, config: ToolServerConfig) {
         const allTypes: InCodeTypeDefinition[] = [];
         for (const coll of config.types || []) {
             for (const type of coll.types) {
-                allTypes.push(type);
+                allTypes.push({
+                    ...type,
+                    id: coll.name + ":" + type.name
+                });
             }
         }
         pkg.types = allTypes;
     },
-    ui(pkg: AppPackage, config: ToolServerConfig, c: Context) {
+    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;
@@ -54,7 +89,7 @@ const builders: Record<Exclude<AppPackageScope, 'all'>, (pkg: AppPackage, config
             }
         }
     },
-    settings(pkg: AppPackage, config: ToolServerConfig) {
+    async settings(pkg: AppPackage, config: ToolServerConfig) {
         if (config.settings) {
             pkg.settings_schema = { ...config.settings };
         }
@@ -62,41 +97,51 @@ const builders: Record<Exclude<AppPackageScope, 'all'>, (pkg: AppPackage, config
 }
 
 
-export function createPackageRoute(app: Hono, basePath: string, config: ToolServerConfig) {
-    const { interactions = [], tools: toolCollections = [], mcpProviders = [] } = config;
-
-    app.get(basePath, (c: Context) => {
-        const scope = c.req.query('scope') || 'all';
-        const pkg: AppPackage = {};
-        interactions; toolCollections; mcpProviders;
+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')) {
-            builders.tools(pkg, config, c);
-            builders.interactions(pkg, config, c);
-            builders.types(pkg, config, c);
-            builders.ui(pkg, config, c);
+    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);
-        } else {
-            if (scopes.has('tools')) {
-                builders.tools(pkg, config, c);
-            }
-            if (scopes.has('interactions')) {
-                builders.interactions(pkg, config, c);
-            }
-            if (scopes.has('types')) {
-                builders.types(pkg, config, c);
-            }
-            if (scopes.has('ui')) {
-                builders.ui(pkg, config, c);
-            }
-            if (scopes.has('settings')) {
-                builders.settings(pkg, config, c);
-            }
         }
+    }
 
-        return c.json(pkg);
-    });
+    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/{conyent-types.ts → content-types.ts}

@@ -2,9 +2,10 @@
 
 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 { HTTPException } from "hono/http-exception";
+import { toPathName } from "../utils.js";
 
 export function createContentTypesRoute(app: Hono, basePath: string, config: ToolServerConfig) {
     const { types = [] } = config;
@@ -15,7 +16,7 @@ export function createContentTypesRoute(app: Hono, basePath: string, config: Too
 
         for (const coll of types) {
             for (const type of coll.types) {
-                allTypes.push(type);
+                allTypes.push({ ...type, id: coll.name + ":" + toPathName(type.name) });
             }
         }
 
@@ -39,17 +40,21 @@ export function createContentTypesRoute(app: Hono, basePath: string, config: Too
     // GET /api/types/:name - Direct access to content type
     app.get(`${basePath}/:name`, async (c) => {
         const name = c.req.param('name');
-
-        // Search across all collections for the interaction
-        for (const coll of types) {
-            const inter = coll.getTypeByName(name);
-            if (inter) {
-                return c.json(inter);
-            }
+        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 interaction found with name: " + name
+            message: "No content type found with name: " + name
         });
     });
 
@@ -62,9 +67,22 @@ function createContentTypeEndpoints(coll: ContentTypesCollection): Hono {
     const endpoint = new Hono();
 
     endpoint.get('/', (c: Context) => {
-        return c.json(coll.types);
+        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

@@ -49,12 +49,17 @@ export function createInteractionsRoute(app: Hono, basePath: string, config: Too
         await authorize(c);
         const name = c.req.param('name');
 
-        // Search across all collections for the interaction
-        for (const coll of interactions) {
-            const inter = coll.getInteractionByName(name);
-            if (inter) {
-                return c.json(inter);
-            }
+        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, {

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

@@ -4,7 +4,7 @@ import { SkillCollection } from "../SkillCollection.js";
 import { ToolCollection } from "../ToolCollection.js";
 import { ToolExecutionPayload } from "../types.js";
 import { JSONSchema } from "@llumiverse/common";
-import { AppUIConfig } from "@vertesia/common";
+import { AppUIConfig, ProjectConfiguration } from "@vertesia/common";
 import { ContentTypesCollection } from "../ContentTypesCollection.js";
 
 /**
@@ -83,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

@@ -11,7 +11,7 @@ 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/conyent-types.js";
+import { createContentTypesRoute } from "./server/content-types.js";
 
 // Schema for tool execution payload
 const ToolExecutionPayloadSchema = z.object({

package/src/types.ts

@@ -1,6 +1,6 @@
 import type { ToolDefinition, ToolUse } from "@llumiverse/common";
 import { VertesiaClient } from "@vertesia/client";
-import { AgentToolDefinition, AuthTokenPayload, ToolExecutionMetadata, ToolResult, ToolResultContent } from "@vertesia/common";
+import { AgentToolDefinition, AuthTokenPayload, ProjectConfiguration, ToolExecutionMetadata, ToolResult, ToolResultContent } from "@vertesia/common";
 
 export type { ToolExecutionMetadata };
 
@@ -87,6 +87,15 @@ export interface ToolExecutionPayload<ParamsT extends Record<string, any>> {
 
 export type ToolFn<ParamsT extends Record<string, any>> = (payload: ToolExecutionPayload<ParamsT>, context: ToolExecutionContext) => Promise<ToolExecutionResult>;
 
+export interface ToolUseContext {
+    project_id?: string,
+    account_id?: string,
+    project_name?: string,
+    project_ns?: string,
+    configuration?: ProjectConfiguration;
+    vars?: Record<string, any>;
+}
+
 export interface Tool<ParamsT extends Record<string, any>> extends ToolDefinition {
     run: ToolFn<ParamsT>;
     /**
@@ -95,6 +104,15 @@ export interface Tool<ParamsT extends Record<string, any>> extends ToolDefinitio
      * - false: Tool is only available when activated by a skill's related_tools
      */
     default?: boolean;
+
+    /**
+     * Optional filter to check if the tool is enabled for the given project configuration.
+     * This can be used to dynamically enable/disable tools based on project settings, environment variables, or any other logic.
+     * If no filter is provided, the tool will be enabled by default.
+     * @param payload 
+     * @returns 
+     */
+    isEnabled?: (payload: ToolUseContext) => boolean;
 }
 
 
@@ -127,6 +145,11 @@ export interface MCPConnectionDetails {
      * If an empty string no authentication will be done
      */
     token: string;
+    /**
+     * Optional additional HTTP headers to include with requests to the MCP server.
+     * Merged with the Authorization header derived from the token.
+     */
+    headers?: Record<string, string>;
 }
 
 // ================== Skill Types ==================
@@ -234,6 +257,16 @@ export interface SkillDefinition {
      * The widget file must be located in the skill directory under the name {{widget-name}}.tsx.
      */
     widgets?: string[];
+
+    /**
+     * Optional filter to check if the tool is enabled for the given project configuration.
+     * This can be used to dynamically enable/disable tools based on project settings, environment variables, or any other logic.
+     * If no filter is provided, the tool will be enabled by default.
+     * @param payload 
+     * @returns 
+     */
+    isEnabled?: (payload: ToolUseContext) => boolean;
+
 }
 
 /**

package/src/utils.ts

@@ -1,3 +1,16 @@
+/**
+ * Convert a name to a URL-safe path segment.
+ * If the name contains spaces or underscores, convert to PascalCase.
+ * Otherwise return as-is. Any characters not in [a-zA-Z0-9$_\-@] are replaced with '-'.
+ */
+export function toPathName(name: string): string {
+    let result = name;
+    if (result.includes(' ') || result.includes('_')) {
+        result = result.split(/[\s_]+/).map(w => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+    }
+    return result.replace(/[^a-zA-Z0-9$_\-@]/g, '-');
+}
+
 export function kebabCaseToTitle(name: string) {
     return name.split('-').map(p => p[0].toUpperCase() + p.substring(1)).join(' ');
 }
@@ -20,4 +33,5 @@ export function join(left: string, right: string) {
     } else {
         return left + '/' + right;
     }
-}
+}
+