@vertesia/tools-sdk 0.24.0-dev.202601221707

package/src/ToolRegistry.ts

@@ -0,0 +1,135 @@
+import { HTTPException } from "hono/http-exception";
+import { Tool, ToolDefinitionWithDefault, ToolExecutionContext, ToolExecutionPayload, ToolExecutionResult } 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 {
+
+    registry: Record<string, Tool<any>> = {};
+
+    constructor(tools: Tool<any>[] = []) {
+        for (const tool of tools) {
+            this.registry[tool.name] = tool;
+        }
+    }
+
+    /**
+     * Get tool definitions with optional filtering.
+     * @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,
+            }));
+    }
+
+    getTool<ParamsT extends Record<string, any>>(name: string): Tool<ParamsT> {
+        const tool = this.registry[name]
+        if (tool === undefined) {
+            throw new ToolNotFoundError(name);
+        }
+        return tool;
+    }
+
+    getTools() {
+        return Object.values(this.registry);
+    }
+
+    registerTool<ParamsT extends Record<string, any>>(tool: Tool<ParamsT>): void {
+        this.registry[tool.name] = tool;
+    }
+
+    runTool<ParamsT extends Record<string, any>>(payload: ToolExecutionPayload<ParamsT>, context: ToolExecutionContext): Promise<ToolExecutionResult> {
+        const toolName = payload.tool_use.tool_name;
+        const toolUseId = payload.tool_use.id;
+        const runId = payload.metadata?.run_id;
+        console.log(`[ToolRegistry] Executing tool: ${toolName}`, {
+            toolUseId,
+            runId,
+            input: sanitizeInput(payload.tool_use.tool_input),
+        });
+        return this.getTool(toolName).run(payload, context);
+    }
+
+}
+
+
+export class ToolNotFoundError extends HTTPException {
+    constructor(name: string) {
+        super(404, { message: "Tool function not found: " + name });
+        this.name = "ToolNotFoundError";
+    }
+}
+
+const SENSITIVE_KEYS = new Set([
+    'apikey', 'api_key', 'token', 'secret', 'password', 'credential', 'credentials',
+    'authorization', 'auth', 'key', 'private_key', 'access_token', 'refresh_token'
+]);
+
+function sanitizeInput(input: Record<string, any> | null | undefined): Record<string, any> | null {
+    if (!input) return null;
+
+    const sanitized: Record<string, any> = {};
+    for (const [key, value] of Object.entries(input)) {
+        const lowerKey = key.toLowerCase();
+        if (SENSITIVE_KEYS.has(lowerKey) || lowerKey.includes('key') || lowerKey.includes('token') || lowerKey.includes('secret')) {
+            sanitized[key] = '[REDACTED]';
+        } else if (typeof value === 'string' && value.length > 50) {
+            sanitized[key] = value.slice(0, 50) + '...';
+        } else if (typeof value === 'object' && value !== null) {
+            sanitized[key] = Array.isArray(value) ? `[Array(${value.length})]` : '[Object]';
+        } else {
+            sanitized[key] = value;
+        }
+    }
+    return sanitized;
+}

package/src/auth.ts

@@ -0,0 +1,123 @@
+import { decodeEndpoints, VertesiaClient } from "@vertesia/client";
+import { AuthTokenPayload } from "@vertesia/common";
+import { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { createLocalJWKSet, decodeJwt, JSONWebKeySet, jwtVerify, JWTVerifyGetKey } from "jose";
+import { ToolExecutionContext } from "./types.js";
+const cache: Record<string, JWTVerifyGetKey> = {};
+
+export async function getJwks(url: string) {
+    if (!cache.url) {
+        console.log('JWKS cache miss for: ', url);
+        const jwks = await fetch(url).then(r => {
+            if (r.ok) {
+                return r.json() as Promise<JSONWebKeySet>;
+            }
+            throw new Error("Fetching jwks failed with code: " + r.status);
+        }).catch(err => {
+            throw new Error("Failed to fetch jwks: " + err.message);
+        })
+        cache.url = createLocalJWKSet(jwks);
+    }
+    return cache.url;
+}
+
+export async function verifyToken(token: string) {
+    const decodedJwt = decodeJwt(token);
+    if (!decodedJwt.iss) {
+        throw new Error("No issuer URL found in JWT");
+    }
+    if (!isAllowedIssuer(decodedJwt.iss)) {
+        throw new Error("Issuer is not allowed: " + decodedJwt.iss);
+    }
+    const jwks = await getJwks(`${decodedJwt.iss}/.well-known/jwks`);
+    return await jwtVerify<AuthTokenPayload>(token, jwks);
+}
+
+
+export interface EndpointOverrides {
+    studio?: string;
+    store?: string;
+    token?: string;
+}
+
+export interface ToolContext {
+    toolName?: string;
+    toolUseId?: string;
+    runId?: string;
+}
+
+export async function authorize(ctx: Context, endpointOverrides?: EndpointOverrides, toolContext?: ToolContext) {
+    const auth = ctx.req.header('Authorization');
+    if (!auth) {
+        throw new HTTPException(401, {
+            message: `Missing Authorization header`
+        });
+    }
+    const [scheme, value] = auth.trim().split(' ');
+    if (scheme.toLowerCase() !== 'bearer') {
+        throw new HTTPException(401, {
+            message: `Authorization scheme ${scheme} is not supported`
+        });
+    }
+    if (!value) {
+        throw new HTTPException(401, {
+            message: `Missing bearer token value`
+        });
+    }
+    try {
+        const { payload } = await verifyToken(value);
+        const session = new AuthSession(value, payload, endpointOverrides, toolContext);
+        ctx.set("auth", session);
+        return session;
+    } catch (err: any) {
+        throw new HTTPException(401, {
+            message: err.message,
+            cause: err
+        });
+    }
+}
+
+export class AuthSession implements ToolExecutionContext {
+    _client: VertesiaClient | undefined;
+    endpoints: {
+        studio: string;
+        store: string;
+        token: string;
+    };
+    toolContext?: ToolContext;
+
+    constructor(
+        public token: string,
+        public payload: AuthTokenPayload,
+        endpointOverrides?: EndpointOverrides,
+        toolContext?: ToolContext
+    ) {
+        const decoded = decodeEndpoints(payload.endpoints);
+        // Use overrides from workflow config if provided, falling back to JWT endpoints
+        this.endpoints = {
+            studio: endpointOverrides?.studio || decoded.studio,
+            store: endpointOverrides?.store || decoded.store,
+            token: endpointOverrides?.token || decoded.token || payload.iss,
+        };
+        this.toolContext = toolContext;
+    }
+
+    async getClient() {
+        if (!this._client) {
+            const toolInfo = this.toolContext?.toolName ? ` for ${this.toolContext.toolName}` : '';
+            console.log(`[VertesiaClient] Initializing client${toolInfo}`, {
+                tool: this.toolContext?.toolName,
+                toolUseId: this.toolContext?.toolUseId,
+                runId: this.toolContext?.runId,
+                endpoints: this.endpoints,
+            });
+            this._client = await VertesiaClient.fromAuthToken(this.token, this.payload, this.endpoints);
+        }
+        return this._client;
+    }
+}
+
+function isAllowedIssuer(iss: string) {
+    return iss.endsWith(".vertesia.io") || iss.endsWith(".becomposable.com");
+}

package/src/build/validate.ts

@@ -0,0 +1,3 @@
+export function validate() {
+    //TODO
+}

package/src/copy-assets.ts

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * Copy runtime assets (skill files, prompt files, scripts) to dist folder
+ * These files are read from disk at runtime and need to be deployed with the app
+ *
+ * Usage:
+ *   npx tools-sdk-copy-assets [srcDir] [distDir]
+ *
+ * Or import and call directly:
+ *   import { copyRuntimeAssets } from '@vertesia/tools-sdk';
+ *   copyRuntimeAssets('./src', './dist');
+ */
+import { existsSync, readdirSync, statSync, mkdirSync, copyFileSync } from "fs";
+import { dirname, join } from "path";
+
+/**
+ * Recursively copy files matching a filter
+ */
+function copyFilesRecursive(src: string, dest: string, fileFilter: (filename: string) => boolean): void {
+    if (!existsSync(src)) return;
+
+    const entries = readdirSync(src);
+
+    for (const entry of entries) {
+        const srcPath = join(src, entry);
+        const destPath = join(dest, entry);
+        const stat = statSync(srcPath);
+
+        if (stat.isDirectory()) {
+            // Recurse into directories
+            copyFilesRecursive(srcPath, destPath, fileFilter);
+        } else if (fileFilter(entry)) {
+            // Copy matching files
+            mkdirSync(dirname(destPath), { recursive: true });
+            copyFileSync(srcPath, destPath);
+        }
+    }
+}
+
+export interface CopyAssetsOptions {
+    /** Source directory (default: './src') */
+    srcDir?: string;
+    /** Destination directory (default: './dist') */
+    distDir?: string;
+    /** Whether to log progress (default: true) */
+    verbose?: boolean;
+}
+
+/**
+ * Copy runtime assets (skills, interactions) from src to dist
+ */
+export function copyRuntimeAssets(options: CopyAssetsOptions = {}): void {
+    const {
+        srcDir = './src',
+        distDir = './dist',
+        verbose = true
+    } = options;
+
+    if (verbose) {
+        console.log('Copying runtime assets to dist...');
+    }
+
+    // Copy skill files (SKILL.md, SKILL.jst, *.py)
+    const skillsSrc = join(srcDir, 'skills');
+    const skillsDest = join(distDir, 'skills');
+
+    if (existsSync(skillsSrc)) {
+        copyFilesRecursive(skillsSrc, skillsDest, (filename) => {
+            return filename === 'SKILL.md' ||
+                   filename === 'SKILL.jst' ||
+                   filename.endsWith('.py');
+        });
+        if (verbose) {
+            console.log('  ✓ Skills assets (SKILL.md, SKILL.jst, *.py)');
+        }
+    }
+
+    // Copy interaction prompt files (prompt.jst, prompt.md)
+    const interactionsSrc = join(srcDir, 'interactions');
+    const interactionsDest = join(distDir, 'interactions');
+
+    if (existsSync(interactionsSrc)) {
+        copyFilesRecursive(interactionsSrc, interactionsDest, (filename) => {
+            return filename === 'prompt.jst' ||
+                   filename === 'prompt.md';
+        });
+        if (verbose) {
+            console.log('  ✓ Interaction assets (prompt.jst, prompt.md)');
+        }
+    }
+
+    if (verbose) {
+        console.log('Runtime assets copied successfully!');
+    }
+}
+
+// CLI entry point
+if (typeof process !== 'undefined' && process.argv[1]?.includes('copy-assets')) {
+    const args = process.argv.slice(2);
+    const srcDir = args[0] || './src';
+    const distDir = args[1] || './dist';
+
+    copyRuntimeAssets({ srcDir, distDir });
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export { authorize, AuthSession } from "./auth.js";
+export { copyRuntimeAssets } from "./copy-assets.js";
+export * from "./InteractionCollection.js";
+export * from "./server.js";
+export * from "./server/types.js";
+export * from "./site/templates.js";
+export * from "./SkillCollection.js";
+export * from "./ToolCollection.js";
+export * from "./ToolRegistry.js";
+export * from "./types.js";
+
+

package/src/server/interactions.ts

@@ -0,0 +1,79 @@
+// ================== Interaction Endpoints ==================
+
+import { CatalogInteractionRef } from "@vertesia/common";
+import { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { authorize } from "../auth.js";
+import { InteractionCollection } from "../InteractionCollection.js";
+import { ToolServerConfig } from "./types.js";
+
+export function createInteractionsRoute(app: Hono, basePath: string, config: ToolServerConfig) {
+    const { interactions = [] } = config;
+
+    // GET /api/interactions - Returns all interactions from all collections
+    app.get(basePath, (c) => {
+        const allInteractions: CatalogInteractionRef[] = [];
+
+        for (const coll of interactions) {
+            for (const inter of coll.interactions) {
+                allInteractions.push({
+                    type: "app",
+                    id: inter.name,
+                    name: inter.name,
+                    title: inter.title || inter.name,
+                    description: inter.description,
+                    tags: inter.tags || [],
+                });
+            }
+        }
+
+        return c.json({
+            title: 'All Interactions',
+            description: 'All available interactions across all collections',
+            interactions: allInteractions,
+            collections: interactions.map(i => ({
+                name: i.name,
+                title: i.title,
+                description: i.description,
+            })),
+        });
+    });
+
+    // Create interaction collection endpoints
+    for (const coll of interactions) {
+        app.route(`${basePath}/${coll.name}`, createInteractionEndpoints(coll));
+    }
+
+}
+
+
+
+
+function createInteractionEndpoints(coll: InteractionCollection): Hono {
+    const endpoint = new Hono();
+
+    endpoint.get('/', (c: Context) => {
+        return c.json(coll.interactions.map(inter => ({
+            type: "app",
+            id: inter.name,
+            name: inter.name,
+            title: inter.title || inter.name,
+            description: inter.description,
+            tags: inter.tags || [],
+        } satisfies CatalogInteractionRef)));
+    });
+
+    endpoint.get('/:name', async (c: Context) => {
+        await authorize(c);
+        const name = c.req.param('name');
+        const inter = coll.getInteractionByName(name);
+        if (!inter) {
+            throw new HTTPException(404, {
+                message: "No interaction found with name: " + name
+            });
+        }
+        return c.json(inter);
+    });
+
+    return endpoint;
+}

package/src/server/mcp.ts

@@ -0,0 +1,51 @@
+// ================== MCP Endpoints ==================
+
+import { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { authorize } from "../auth.js";
+import { ToolServerConfig } from "../index.js";
+import { MCPProviderConfig } from "./types.js";
+
+
+
+export function createMcpRoute(app: Hono, basePath: string, config: ToolServerConfig) {
+    const { mcpProviders = [] } = config;
+    // Create MCP provider endpoints
+    if (mcpProviders.length > 0) {
+        app.route(basePath, createMCPEndpoints(mcpProviders));
+    }
+
+}
+
+function createMCPEndpoints(providers: MCPProviderConfig[]): Hono {
+    const endpoint = new Hono();
+
+    for (const p of providers) {
+        endpoint.post(`/${p.name}`, async (c: Context) => {
+            const session = await authorize(c);
+            const config = await readJsonBody(c);
+            const info = await p.createMCPConnection(session, config);
+            return c.json(info);
+        });
+
+        endpoint.get(`/${p.name}`, (c: Context) => c.json({
+            name: p.name,
+            description: p.description,
+        }));
+    }
+
+    return endpoint;
+}
+
+async function readJsonBody(ctx: Context): Promise<Record<string, any>> {
+    try {
+        const text = await ctx.req.text();
+        const jsonContent = text?.trim() || '';
+        if (!jsonContent) return {};
+        return JSON.parse(jsonContent) as Record<string, any>;
+    } catch (err: any) {
+        throw new HTTPException(400, {
+            message: "Failed to parse JSON body: " + err.message
+        });
+    }
+}

package/src/server/site.ts

@@ -0,0 +1,46 @@
+import { Hono } from "hono";
+import {
+    indexPage,
+    interactionCollectionPage,
+    skillCollectionPage,
+    toolCollectionPage
+} from "../site/templates.js";
+import { ToolServerConfig } from "./types.js";
+
+
+export function createSiteRoute(app: Hono, basePath: string, config: ToolServerConfig) {
+    const {
+        title = 'Tools Server',
+        tools = [],
+        interactions = [],
+        skills = [],
+        mcpProviders = [],
+    } = config;
+
+    // Index page
+    app.get(`${basePath}/`, (c) => {
+        return c.html(indexPage(tools, skills, interactions, mcpProviders, title));
+    });
+
+    // Tool collection pages
+    for (const coll of tools) {
+        app.get(`${basePath}/tools/${coll.name}`, (c) => {
+            return c.html(toolCollectionPage(coll));
+        });
+    }
+
+    // Skill collection pages
+    for (const coll of skills) {
+        app.get(`${basePath}/skills/${coll.name}`, (c) => {
+            return c.html(skillCollectionPage(coll));
+        });
+    }
+
+    // Interaction collection pages
+    for (const coll of interactions) {
+        app.get(`${basePath}/interactions/${coll.name}`, (c) => {
+            return c.html(interactionCollectionPage(coll));
+        });
+    }
+
+}

package/src/server/skills.ts

@@ -0,0 +1,133 @@
+// ================== Skill Endpoints ==================
+
+import { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { SkillCollection } from "../SkillCollection.js";
+import { SkillDefinition, ToolCollectionDefinition, ToolDefinition } from "../types.js";
+import { makeScriptUrl } from "../utils.js";
+import { ToolContext, ToolServerConfig } from "./types.js";
+
+export function createSkillsRoute(app: Hono, basePath: string, config: ToolServerConfig) {
+    const { skills = [] } = config;
+
+    // Build a map of skill name -> collection for routing
+    const skillToCollection = new Map<string, SkillCollection>();
+    for (const coll of skills) {
+        for (const skill of coll.getSkillDefinitions()) {
+            skillToCollection.set(skill.name, coll);
+            // Also map the learn_ prefixed name
+            skillToCollection.set(`learn_${skill.name}`, coll);
+        }
+    }
+
+    // GET /api/skills - Returns all skills from all collections
+    app.get(basePath, (c) => {
+        const url = new URL(c.req.url);
+        const allSkills: ToolDefinition[] = [];
+
+        for (const coll of skills) {
+            allSkills.push(...coll.getToolDefinitions());
+        }
+
+        return c.json({
+            src: `${url.origin}${url.pathname}`,
+            title: 'All Skills',
+            description: 'All available skills across all collections',
+            tools: allSkills,
+            collections: skills.map(s => ({
+                name: s.name,
+                title: s.title,
+                description: s.description,
+            })),
+        } satisfies ToolCollectionDefinition & { collections: any[] });
+    });
+
+    // POST /api/skills - 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 skill execution payload. Expected { tool_use: { id, tool_name, tool_input? }, metadata? }'
+            });
+        }
+
+        const toolName = ctx.payload.tool_use.tool_name;
+
+        // Find the collection for this skill
+        const collection = skillToCollection.get(toolName);
+        if (!collection) {
+            // Extract skill name for better error message
+            const skillName = toolName.startsWith('learn_') ? toolName.slice(6) : toolName;
+            throw new HTTPException(404, {
+                message: `Skill not found: ${skillName}. Available skills: ${Array.from(skillToCollection.keys()).filter(k => !k.startsWith('learn_')).join(', ')}`
+            });
+        }
+
+        // Delegate to the collection's execute method with pre-parsed payload
+        return collection.execute(c, ctx.payload);
+    });
+
+    // Create skill collection endpoints (exposed as tools)
+    for (const coll of skills) {
+        app.route(`${basePath}/${coll.name}`, createSkillEndpoints(coll));
+    }
+
+}
+
+function createSkillEndpoints(coll: SkillCollection): Hono {
+    const endpoint = new Hono();
+
+    // List skills as tool definitions (tool collection format)
+    // This allows skills to be used exactly like tools
+    endpoint.get('/', (c: Context) => {
+        const url = new URL(c.req.url);
+        return c.json({
+            src: `${url.origin}${url.pathname}`,
+            title: coll.title || coll.name,
+            description: coll.description || '',
+            tools: coll.getToolDefinitions()
+        } satisfies ToolCollectionDefinition);
+    });
+
+    // Get scripts for a specific skill
+    // Returns all scripts bundled with the skill
+    endpoint.get('/:name/scripts', (c: Context) => {
+        const name = c.req.param('name');
+        const skillName = name.startsWith('learn_') ? name.slice(6) : name;
+        const skill = coll.getSkill(skillName);
+        if (!skill) {
+            throw new HTTPException(404, {
+                message: `Skill not found: ${skillName}`
+            });
+        }
+        const url = new URL(c.req.url);
+        return c.json({
+            skill_name: skill.name,
+            scripts: skill.scripts ? skill.scripts.map(s => makeScriptUrl(url.origin, s)) : []
+        });
+    });
+
+
+    // Get a specific skill by name
+    endpoint.get('/:name', (c: Context) => {
+        const name = c.req.param('name');
+        // Handle both "learn_name" and "name" formats
+        const skillName = name.startsWith('learn_') ? name.slice(6) : name;
+        const skill = coll.getSkill(skillName);
+        if (!skill) {
+            throw new HTTPException(404, {
+                message: `Skill not found: ${skillName}`
+            });
+        }
+        return c.json(skill satisfies SkillDefinition);
+    });
+
+    // Execute skill (standard tool execution format)
+    endpoint.post('/', (c: Context) => {
+        return coll.execute(c);
+    });
+
+    return endpoint;
+}