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

package/src/server/tools.ts

@@ -0,0 +1,128 @@
+import { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { ToolCollection } from "../ToolCollection.js";
+import { ToolCollectionDefinition, ToolDefinition } from "../types.js";
+import { ToolContext, ToolServerConfig } from "./types.js";
+
+export function createToolsRoute(app: Hono, basePath: string, config: ToolServerConfig) {
+    const { tools = [] } = config;
+
+    // Build a map of tool name -> collection for routing
+    const toolToCollection = new Map<string, ToolCollection>();
+    for (const coll of tools) {
+        for (const toolDef of coll.getToolDefinitions()) {
+            toolToCollection.set(toolDef.name, coll);
+        }
+    }
+
+    // GET /api/tools - Returns all tools from all collections
+    // Query params:
+    //   - defaultOnly=true: Only return tools with default !== false
+    //   - unlocked=tool1,tool2: Comma-separated list of unlocked tool names
+
+    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;
+            }
+        }
+
+        return c.json({
+            src: `${url.origin}${url.pathname}`,
+            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,
+                description: t.description,
+            })),
+        } satisfies ToolCollectionDefinition & { collections: any[]; reserveToolCount?: number });
+    });
+
+    // POST /api/tools - Route to the correct collection based on tool_name
+    app.post(basePath, async (c) => {
+        const ctx = c as unknown as ToolContext;
+
+        // Payload is already parsed and validated by middleware
+        if (!ctx.payload) {
+            throw new HTTPException(400, {
+                message: 'Invalid or missing tool execution payload. Expected { tool_use: { id, tool_name, tool_input? }, metadata? }'
+            });
+        }
+
+        const toolName = ctx.payload.tool_use.tool_name;
+
+        // Find the collection for this tool
+        const collection = toolToCollection.get(toolName);
+        if (!collection) {
+            throw new HTTPException(404, {
+                message: `Tool not found: ${toolName}. Available tools: ${Array.from(toolToCollection.keys()).join(', ')}`
+            });
+        }
+
+        // Delegate to the collection's execute method with pre-parsed payload
+        return collection.execute(c, ctx.payload);
+    });
+
+    // Create tool collection endpoints
+    for (const coll of tools) {
+        app.route(`${basePath}/${coll.name}`, createToolEndpoints(coll));
+    }
+}
+
+function createToolEndpoints(coll: ToolCollection): Hono {
+    const endpoint = new Hono();
+
+    endpoint.post('/', (c: Context) => {
+        return coll.execute(c);
+    });
+
+    // GET /api/tools/{collection}
+    // Query params:
+    //   - import: Return import source URL instead of API URL
+    //   - defaultOnly=true: Only return tools with default !== false
+    //   - 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 } = {
+            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)
+        };
+
+        // Include reserve count when filtering
+        if (defaultOnly) {
+            response.reserveToolCount = coll.getReserveTools(unlockedTools).length;
+        }
+
+        return c.json(response);
+    });
+
+    return endpoint;
+}
+
+
+

package/src/server/types.ts

@@ -0,0 +1,87 @@
+import { Context } from "hono";
+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 } from "@vertesia/common";
+import { ContentTypesCollection } from "../ContentTypesCollection.js";
+
+/**
+ * Extended context with parsed payload for tool/skill execution
+ */
+export interface ToolContext extends Context {
+    /** The parsed request payload */
+    payload?: ToolExecutionPayload<any>;
+    /** The tool_use.id from the payload */
+    toolUseId?: string;
+    /** The tool_use.tool_name from the payload */
+    toolName?: string;
+}
+
+/**
+ * MCP Provider interface for server configuration
+ */
+export interface MCPProviderConfig {
+    name: string;
+    description?: string;
+    createMCPConnection: (session: any, config: Record<string, any>) => Promise<{
+        name: string;
+        url: string;
+        token: string;
+    }>;
+}
+
+/**
+ * Server configuration options
+ */
+export interface ToolServerConfig {
+    /**
+     * Server title for HTML pages (default: 'Tools Server')
+     */
+    title?: string;
+    /**
+     * API prefix (default: '/api')
+     */
+    prefix?: string;
+    /**
+     * Tool collections to expose
+     */
+    tools?: ToolCollection[];
+    /**
+     * Interaction collections to expose
+     */
+    interactions?: InteractionCollection[];
+    /**
+     * Content type collections to expose
+     */
+    types?: ContentTypesCollection[];
+    /**
+     * Skill collections to expose
+     */
+    skills?: SkillCollection[];
+    /**
+     * 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)
+     */
+    disableHtml?: boolean;
+    /**
+     * Hide UI app links on the index page (default: false)
+     */
+    hideUILinks?: boolean;
+}
+

package/src/server/widgets.ts

@@ -0,0 +1,38 @@
+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) {
+
+    const { skills = [] } = config;
+
+    // GET /api/widgets - Returns all widgets from all skill collections
+    app.get(basePath, (c) => {
+        const url = new URL(c.req.url);
+
+        const widgets: Record<string, WidgetInfo> = {};
+        for (const coll of skills) {
+            const collWidgets = coll.getWidgets();
+            for (const widget of collWidgets) {
+                widgets[widget.name] = {
+                    collection: coll.name,
+                    skill: widget.skill,
+                    url: `${url.origin}/widgets/${widget.name}.js`,
+                }
+            }
+        }
+
+        return c.json({
+            title: 'All Widgets',
+            description: 'All available widgets across all skill collections',
+            widgets,
+        });
+
+    });
+
+}