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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/tools-sdk",
-  "version": "0.81.1",
+  "version": "1.0.0-dev.20260203.130115Z",
   "description": "Tools SDK - utilities for building remote tools",
   "type": "module",
   "types": "./lib/types/index.d.ts",
@@ -18,22 +18,23 @@
     "tools-sdk-copy-assets": "./lib/esm/copy-assets.js"
   },
   "devDependencies": {
-    "@types/node": "^24.10.1",
+    "@types/node": "^22.19.2",
     "ts-dual-module": "^0.6.3",
-    "typescript": "^5.0.2",
-    "vitest": "^3.0.9"
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
   },
   "ts_dual_module": {
     "outDir": "lib"
   },
   "peerDependencies": {
-    "hono": "^4.10.0"
+    "hono": "^4.11.7"
   },
   "dependencies": {
     "jose": "^6.0.11",
-    "@llumiverse/common": "0.24.0",
-    "@vertesia/common": "0.81.1",
-    "@vertesia/client": "0.81.1"
+    "zod": "^4.3.5",
+    "@llumiverse/common": "1.0.0-dev.20260202.145450Z",
+    "@vertesia/common": "1.0.0-dev.20260203.130115Z",
+    "@vertesia/client": "1.0.0-dev.20260203.130115Z"
   },
   "repository": {
     "type": "git",

package/src/ContentTypesCollection.ts

@@ -0,0 +1,51 @@
+import { InCodeTypeDefinition } from "@vertesia/common";
+import { CollectionProperties, ICollection } from "./types.js";
+import { kebabCaseToTitle } from "./utils.js";
+
+export interface ContentTypesCollectionProps extends CollectionProperties {
+    types: InCodeTypeDefinition[];
+}
+export class ContentTypesCollection implements ICollection<InCodeTypeDefinition> {
+    types: InCodeTypeDefinition[];
+    name: string;
+    title?: string;
+    icon?: string;
+    description?: string;
+    constructor({
+        name, title, icon, description, types
+    }: ContentTypesCollectionProps) {
+        this.name = name;
+        this.title = title || kebabCaseToTitle(name);
+        this.icon = icon;
+        this.description = description;
+        this.types = types;
+    }
+
+    getContentTypes() {
+        return this.types;
+    }
+
+    [Symbol.iterator](): Iterator<InCodeTypeDefinition> {
+        let index = 0;
+        const types = this.types;
+
+        return {
+            next(): IteratorResult<InCodeTypeDefinition> {
+                if (index < types.length) {
+                    return { value: types[index++], done: false };
+                } else {
+                    return { done: true, value: undefined };
+                }
+            }
+        };
+    }
+
+    map<U>(callback: (type: InCodeTypeDefinition, index: number) => U): U[] {
+        return this.types.map(callback);
+    }
+
+    getTypeByName(name: string): InCodeTypeDefinition | undefined {
+        return this.types.find(type => type.name === name);
+    }
+
+}

package/src/InteractionCollection.ts

@@ -1,8 +1,5 @@
-import { readdirSync, statSync, existsSync, readFileSync } from "fs";
-import { join } from "path";
-import { pathToFileURL } from "url";
 import { InteractionSpec } from "@vertesia/common";
-import { ICollection, CollectionProperties } from "./types.js";
+import { CollectionProperties, ICollection } from "./types.js";
 import { kebabCaseToTitle } from "./utils.js";
 
 export interface InteractionCollectionProps extends CollectionProperties {
@@ -23,9 +20,6 @@ export class InteractionCollection implements ICollection<InteractionSpec> {
         this.description = description;
         this.interactions = interactions;
     }
-    addInteraction(interaction: any) {
-        this.interactions.push(interaction);
-    }
 
     getInteractions() {
         return this.interactions;
@@ -54,90 +48,3 @@ export class InteractionCollection implements ICollection<InteractionSpec> {
         return this.interactions.find(interaction => interaction.name === name);
     }
 }
-
-/**
- * Load all interactions from a directory.
- * Scans for subdirectories containing index.ts/index.js files.
- *
- * Directory structure:
- * ```
- * interactions/
- *   nagare/
- *     extract-fund-actuals/
- *       index.ts       # exports default InteractionSpec
- *       prompt.jst     # prompt template (read via readPromptFile helper)
- *     parse-fund-document/
- *       index.ts
- *       prompt.md
- * ```
- *
- * @param interactionsDir - Path to the interactions collection directory
- * @returns Promise resolving to array of InteractionSpec objects
- */
-export async function loadInteractionsFromDirectory(interactionsDir: string): Promise<InteractionSpec[]> {
-    const interactions: InteractionSpec[] = [];
-
-    if (!existsSync(interactionsDir)) {
-        console.warn(`Interactions directory not found: ${interactionsDir}`);
-        return interactions;
-    }
-
-    let entries: string[];
-    try {
-        entries = readdirSync(interactionsDir);
-    } catch {
-        console.warn(`Could not read interactions directory: ${interactionsDir}`);
-        return interactions;
-    }
-
-    for (const entry of entries) {
-        // Skip hidden files and index files
-        if (entry.startsWith('.')) continue;
-        if (entry === 'index.ts' || entry === 'index.js') continue;
-
-        const entryPath = join(interactionsDir, entry);
-
-        try {
-            const stat = statSync(entryPath);
-            if (!stat.isDirectory()) continue;
-
-            // Look for index.ts or index.js in the subdirectory
-            const indexTs = join(entryPath, 'index.ts');
-            const indexJs = join(entryPath, 'index.js');
-            const indexPath = existsSync(indexTs) ? indexTs : existsSync(indexJs) ? indexJs : null;
-
-            if (!indexPath) {
-                continue; // No index file, skip
-            }
-
-            // Dynamic import
-            const fileUrl = pathToFileURL(indexPath).href;
-            const module = await import(fileUrl);
-
-            const interaction = module.default || module.interaction;
-
-            if (interaction && typeof interaction.name === 'string') {
-                interactions.push(interaction);
-            } else {
-                console.warn(`No valid InteractionSpec export found in ${entry}/index`);
-            }
-        } catch (err) {
-            console.warn(`Error loading interaction from ${entry}:`, err);
-        }
-    }
-
-    return interactions;
-}
-
-/**
- * Helper to read a prompt file from the same directory as the interaction.
- * Use this in interaction index.ts files to load prompt templates.
- *
- * @param dirname - Pass __dirname or dirname(fileURLToPath(import.meta.url))
- * @param filename - Prompt filename (e.g., 'prompt.jst' or 'prompt.md')
- * @returns File contents as string
- */
-export function readPromptFile(dirname: string, filename: string): string {
-    const filePath = join(dirname, filename);
-    return readFileSync(filePath, 'utf-8');
-}

package/src/SkillCollection.ts

@@ -1,8 +1,9 @@
-import { readdirSync, statSync, existsSync, readFileSync } from "fs";
-import { join } from "path";
 import { ToolDefinition } from "@llumiverse/common";
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
 import { Context } from "hono";
 import { HTTPException } from "hono/http-exception";
+import { join } from "path";
+import { ToolContext } from "./server/types.js";
 import type {
     CollectionProperties,
     ICollection,
@@ -14,6 +15,7 @@ import type {
     ToolExecutionResult,
 } from "./types.js";
 import { kebabCaseToTitle } from "./utils.js";
+import { AgentToolDefinition } from "@vertesia/common";
 
 export interface SkillCollectionProperties extends CollectionProperties {
     /**
@@ -83,8 +85,9 @@ export class SkillCollection implements ICollection<SkillDefinition> {
      * Get skills exposed as tool definitions.
      * This allows skills to appear alongside regular tools.
      * When called, they return rendered instructions.
+     * Includes related_tools for dynamic tool discovery.
      */
-    getToolDefinitions(): ToolDefinition[] {
+    getToolDefinitions(): AgentToolDefinition[] {
         const defaultSchema: ToolDefinition['input_schema'] = {
             type: 'object',
             properties: {
@@ -95,11 +98,21 @@ export class SkillCollection implements ICollection<SkillDefinition> {
             }
         };
 
-        return Array.from(this.skills.values()).map(skill => ({
-            name: `skill_${skill.name}`,
-            description: `[Skill] ${skill.description}. Returns contextual instructions for this task.`,
-            input_schema: skill.input_schema || defaultSchema
-        }));
+        return Array.from(this.skills.values()).map(skill => {
+            // Build description with related tools info if available
+            let description = `[Skill] ${skill.description}. Returns contextual instructions for this task.`;
+            if (skill.related_tools && skill.related_tools.length > 0) {
+                description += ` Unlocks tools: ${skill.related_tools.join(', ')}.`;
+            }
+
+            return {
+                name: `learn_${skill.name}`,
+                description,
+                input_schema: skill.input_schema || defaultSchema,
+                related_tools: skill.related_tools,
+                category: this.name,
+            };
+        });
     }
 
     /**
@@ -114,24 +127,65 @@ export class SkillCollection implements ICollection<SkillDefinition> {
         };
     }
 
+    getWidgets(): {
+        name: string;
+        skill: string;
+    }[] {
+        const out: {
+            name: string;
+            skill: string;
+        }[] = [];
+        for (const skill of this.skills.values()) {
+            if (skill.widgets) {
+                for (const widget of skill.widgets) {
+                    out.push({
+                        name: widget,
+                        skill: skill.name,
+                    });
+                }
+            }
+        }
+        return Array.from(out);
+    }
+
     /**
      * Execute a skill - accepts standard tool execution payload.
      * Returns rendered instructions in tool result format.
+     *
+     * @param ctx - Hono context
+     * @param preParsedPayload - Optional pre-parsed payload (used when routing from root endpoint)
      */
-    async execute(ctx: Context): Promise<Response> {
-        let payload: ToolExecutionPayload<Record<string, any>> | undefined;
+    async execute(ctx: Context, preParsedPayload?: ToolExecutionPayload<Record<string, any>>): Promise<Response> {
+        const toolCtx = ctx as ToolContext;
+        let payload: ToolExecutionPayload<Record<string, any>> | undefined = preParsedPayload;
         try {
-            payload = await ctx.req.json() as ToolExecutionPayload<Record<string, any>>;
+            if (!payload) {
+                // Check if body was already parsed and validated by middleware
+                if (toolCtx.payload) {
+                    payload = toolCtx.payload;
+                } else {
+                    throw new HTTPException(400, {
+                        message: 'Invalid or missing skill execution payload. Expected { tool_use: { id, tool_name, tool_input? }, metadata? }'
+                    });
+                }
+            }
+
             const toolName = payload.tool_use.tool_name;
 
-            // Extract skill name from tool name (remove "skill_" prefix if present)
-            const skillName = toolName.startsWith('skill_')
-                ? toolName.slice(6)
+            // Extract skill name from tool name (remove "learn_" prefix if present)
+            const skillName = toolName.startsWith('learn_')
+                ? toolName.replace('learn_', '')
                 : toolName;
 
             const skill = this.skills.get(skillName);
 
             if (!skill) {
+                console.warn("[SkillCollection] Skill not found", {
+                    collection: this.name,
+                    requestedSkill: skillName,
+                    toolName,
+                    availableSkills: Array.from(this.skills.keys()),
+                });
                 throw new HTTPException(404, {
                     message: `Skill not found: ${skillName}`
                 });
@@ -155,8 +209,23 @@ export class SkillCollection implements ICollection<SkillDefinition> {
             } satisfies ToolExecutionResult & { tool_use_id: string });
         } catch (err: any) {
             const status = err.status || 500;
+            const toolName = payload?.tool_use?.tool_name;
+            const toolUseId = payload?.tool_use?.id;
+
+            if (status >= 500) {
+                console.error("[SkillCollection] Skill execution failed", {
+                    collection: this.name,
+                    skill: toolName,
+                    toolUseId,
+                    error: err.message,
+                    status,
+                    toolInput: payload?.tool_use?.tool_input,
+                    stack: err.stack,
+                });
+            }
+
             return ctx.json({
-                tool_use_id: payload?.tool_use?.id || "unknown",
+                tool_use_id: toolUseId || "unknown",
                 is_error: true,
                 content: err.message || "Error executing skill",
             }, status);
@@ -198,6 +267,8 @@ interface SkillFrontmatter {
     language?: string;
     packages?: string[];
     system_packages?: string[];
+    widgets?: string[];
+    scripts?: string[];
 }
 
 /**
@@ -247,6 +318,8 @@ export function parseSkillFile(
         description: frontmatter.description,
         instructions,
         content_type: contentType,
+        widgets: frontmatter.widgets || undefined,
+        scripts: frontmatter.scripts || undefined,
     };
 
     // Build context triggers

package/src/ToolCollection.ts

@@ -4,9 +4,11 @@ import { pathToFileURL } from "url";
 import { Context } from "hono";
 import { HTTPException } from "hono/http-exception";
 import { authorize } from "./auth.js";
-import { ToolRegistry } from "./ToolRegistry.js";
-import type { CollectionProperties, ICollection, Tool, ToolDefinition, ToolExecutionPayload, ToolExecutionResponse, ToolExecutionResponseError } from "./types.js";
+import { ToolFilterOptions, ToolRegistry } from "./ToolRegistry.js";
+import { ToolContext } from "./server/types.js";
+import type { CollectionProperties, ICollection, Tool, ToolExecutionPayload, ToolExecutionResponse, ToolExecutionResponseError } from "./types.js";
 import { kebabCaseToTitle } from "./utils.js";
+import { AgentToolDefinition } from "@vertesia/common";
 
 export interface ToolCollectionProperties extends CollectionProperties {
     /**
@@ -51,7 +53,8 @@ export class ToolCollection implements ICollection<Tool<any>> {
         this.title = title || kebabCaseToTitle(name);
         this.icon = icon;
         this.description = description;
-        this.tools = new ToolRegistry(tools);
+        // we add the collection name info
+        this.tools = new ToolRegistry(name, tools);
     }
 
     [Symbol.iterator](): Iterator<Tool<any>> {
@@ -73,11 +76,26 @@ export class ToolCollection implements ICollection<Tool<any>> {
         return this.tools.getTools().map(callback);
     }
 
-    async execute(ctx: Context): Promise<Response> {
-        let payload: ToolExecutionPayload<any> | undefined;
+    async execute(ctx: Context, preParsedPayload?: ToolExecutionPayload<any>): Promise<Response> {
+        let payload: ToolExecutionPayload<any> | undefined = preParsedPayload;
         try {
-            payload = await readPayload(ctx);
-            const session = await authorize(ctx);
+            if (!payload) {
+                payload = await readPayload(ctx);
+            }
+            const toolName = payload.tool_use?.tool_name;
+            const toolUseId = payload.tool_use?.id;
+            const endpointOverrides = payload.metadata?.endpoints;
+
+            const runId = payload.metadata?.run_id;
+
+            console.log(`[ToolCollection] Tool call received: ${toolName}`, {
+                collection: this.name,
+                toolUseId,
+                runId,
+                hasEndpointOverrides: !!endpointOverrides,
+            });
+
+            const session = await authorize(ctx, endpointOverrides, { toolName, toolUseId, runId });
             const r = await this.tools.runTool(payload, session);
             return ctx.json({
                 ...r,
@@ -85,29 +103,59 @@ export class ToolCollection implements ICollection<Tool<any>> {
             } satisfies ToolExecutionResponse);
         } catch (err: any) { // HTTPException ?
             const status = err.status || 500;
+            const toolName = payload?.tool_use?.tool_name;
+            const toolUseId = payload?.tool_use?.id;
+
+            console.error("[ToolCollection] Tool execution failed", {
+                collection: this.name,
+                tool: toolName,
+                toolUseId,
+                error: err.message,
+                status,
+                stack: err.stack,
+            });
+
             return ctx.json({
-                tool_use_id: payload?.tool_use.id || "undefined",
+                tool_use_id: toolUseId || "undefined",
                 error: err.message || "Error executing tool",
                 status
             } satisfies ToolExecutionResponseError, status)
         }
     }
 
-    getToolDefinitions(): ToolDefinition[] {
-        return this.tools.getDefinitions();
+    /**
+     * Get tool definitions with optional filtering.
+     * @param options - Filtering options for default/unlocked tools
+     * @returns Filtered tool definitions
+     */
+    getToolDefinitions(options?: ToolFilterOptions): AgentToolDefinition[] {
+        return this.tools.getDefinitions(options);
+    }
+
+    /**
+     * 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[] {
+        return this.tools.getReserveTools(unlockedTools);
     }
 
 }
 
 
-async function readPayload(ctx: Context) {
-    try {
-        return await ctx.req.json() as ToolExecutionPayload<any>;
-    } catch (err: any) {
-        throw new HTTPException(500, {
-            message: "Failed to load execution request payload: " + err.message
-        });
+function readPayload(ctx: Context): ToolExecutionPayload<any> {
+    const toolCtx = ctx as ToolContext;
+
+    // Check if body was already parsed and validated by middleware
+    if (toolCtx.payload) {
+        return toolCtx.payload;
     }
+
+    // If no payload, middleware couldn't parse/validate - return error
+    throw new HTTPException(400, {
+        message: 'Invalid or missing tool execution payload. Expected { tool_use: { id, tool_name, tool_input? }, metadata? }'
+    });
 }
 
 /**

package/src/ToolRegistry.ts

@@ -1,21 +1,81 @@
+import { AgentToolDefinition } from "@vertesia/common";
 import { HTTPException } from "hono/http-exception";
-import { Tool, ToolDefinition, ToolExecutionContext, ToolExecutionPayload, ToolExecutionResult } from "./types.js";
+import { Tool, 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 {
 
+    // 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;
         }
     }
 
-    getDefinitions(): ToolDefinition[] {
-        return Object.values(this.registry).map(tool => ({
-            name: tool.name,
-            description: tool.description,
-            input_schema: tool.input_schema
-        }));
+    /**
+     * Get tool definitions with optional filtering.
+     * @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,
+            }));
     }
 
     getTool<ParamsT extends Record<string, any>>(name: string): Tool<ParamsT> {
@@ -35,7 +95,15 @@ export class ToolRegistry {
     }
 
     runTool<ParamsT extends Record<string, any>>(payload: ToolExecutionPayload<ParamsT>, context: ToolExecutionContext): Promise<ToolExecutionResult> {
-        return this.getTool(payload.tool_use.tool_name).run(payload, context);
+        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);
     }
 
 }
@@ -46,4 +114,28 @@ export class ToolNotFoundError extends HTTPException {
         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;
 }