@vertesia/tools-sdk 1.3.0 → 1.4.0-dev.20260615.042549Z

package/src/RenderingTemplateCollection.ts

@@ -1,51 +1,49 @@
-import { CollectionProperties, ICollection, RenderingTemplateDefinition } from "./types.js";
-import { kebabCaseToTitle } from "./utils.js";
-
-export interface RenderingTemplateCollectionProps extends CollectionProperties {
-    templates: RenderingTemplateDefinition[];
-}
-
-export class RenderingTemplateCollection implements ICollection<RenderingTemplateDefinition> {
-    templates: RenderingTemplateDefinition[];
-    name: string;
-    title?: string;
-    icon?: string;
-    description?: string;
-
-    constructor({
-        name, title, icon, description, templates
-    }: RenderingTemplateCollectionProps) {
-        this.name = name;
-        this.title = title || kebabCaseToTitle(name);
-        this.icon = icon;
-        this.description = description;
-        this.templates = templates;
-    }
-
-    getTemplateDefinitions() {
-        return this.templates;
-    }
-
-    getTemplate(name: string): RenderingTemplateDefinition | undefined {
-        return this.templates.find(t => t.name === name);
-    }
-
-    [Symbol.iterator](): Iterator<RenderingTemplateDefinition> {
-        let index = 0;
-        const templates = this.templates;
-
-        return {
-            next(): IteratorResult<RenderingTemplateDefinition> {
-                if (index < templates.length) {
-                    return { value: templates[index++], done: false };
-                } else {
-                    return { done: true, value: undefined };
-                }
-            }
-        };
-    }
-
-    map<U>(callback: (template: RenderingTemplateDefinition, index: number) => U): U[] {
-        return this.templates.map(callback);
-    }
-}
+import type { CollectionProperties, ICollection, RenderingTemplateDefinition } from './types.js';
+import { kebabCaseToTitle } from './utils.js';
+
+export interface RenderingTemplateCollectionProps extends CollectionProperties {
+    templates: RenderingTemplateDefinition[];
+}
+
+export class RenderingTemplateCollection implements ICollection<RenderingTemplateDefinition> {
+    templates: RenderingTemplateDefinition[];
+    name: string;
+    title?: string;
+    icon?: string;
+    description?: string;
+
+    constructor({ name, title, icon, description, templates }: RenderingTemplateCollectionProps) {
+        this.name = name;
+        this.title = title || kebabCaseToTitle(name);
+        this.icon = icon;
+        this.description = description;
+        this.templates = templates;
+    }
+
+    getTemplateDefinitions() {
+        return this.templates;
+    }
+
+    getTemplate(name: string): RenderingTemplateDefinition | undefined {
+        return this.templates.find((t) => t.name === name);
+    }
+
+    [Symbol.iterator](): Iterator<RenderingTemplateDefinition> {
+        let index = 0;
+        const templates = this.templates;
+
+        return {
+            next(): IteratorResult<RenderingTemplateDefinition> {
+                if (index < templates.length) {
+                    return { value: templates[index++], done: false };
+                } else {
+                    return { done: true, value: undefined };
+                }
+            },
+        };
+    }
+
+    map<U>(callback: (template: RenderingTemplateDefinition, index: number) => U): U[] {
+        return this.templates.map(callback);
+    }
+}

package/src/SkillCollection.ts

@@ -1,9 +1,10 @@
-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 { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ToolDefinition } from '@llumiverse/common';
+import type { AgentToolDefinition } from '@vertesia/common';
+import type { Context } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import type { ToolContext } from './server/types.js';
 import type {
     CollectionProperties,
     ICollection,
@@ -14,9 +15,8 @@ import type {
     ToolExecutionPayload,
     ToolExecutionResult,
     ToolUseContext,
-} from "./types.js";
-import { kebabCaseToTitle } from "./utils.js";
-import { AgentToolDefinition } from "@vertesia/common";
+} from './types.js';
+import { kebabCaseToTitle } from './utils.js';
 
 export interface SkillCollectionProperties extends CollectionProperties {
     /**
@@ -57,7 +57,7 @@ export class SkillCollection implements ICollection<SkillDefinition> {
         this.title = title || kebabCaseToTitle(name);
         this.icon = icon;
         this.description = description;
-        this.skills = new Map(skills.map(s => [s.name, s]));
+        this.skills = new Map(skills.map((s) => [s.name, s]));
     }
 
     [Symbol.iterator](): Iterator<SkillDefinition> {
@@ -86,31 +86,31 @@ 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.
+     * Includes tools for dynamic tool discovery.
      */
     getToolDefinitions(filterContext?: ToolUseContext): AgentToolDefinition[] {
         const defaultSchema: ToolDefinition['input_schema'] = {
             type: 'object',
             properties: {
                 context: {
-                    type: "string",
-                    description: "Additional context or specific requirements for this task"
-                }
-            }
+                    type: 'string',
+                    description: 'Additional context or specific requirements for this task',
+                },
+            },
         };
 
         let skills = Array.from(this.skills.values());
         if (filterContext) {
-            skills = skills.filter(skill => {
+            skills = skills.filter((skill) => {
                 return skill.isEnabled ? skill.isEnabled(filterContext) : true;
             });
         }
 
-        return skills.map(skill => {
+        return skills.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(', ')}.`;
+            if (skill.tools && skill.tools.length > 0) {
+                description += ` Unlocks tools: ${skill.tools.join(', ')}.`;
             }
 
             return {
@@ -118,7 +118,7 @@ export class SkillCollection implements ICollection<SkillDefinition> {
                 name: `learn_${skill.name}`,
                 description,
                 input_schema: skill.input_schema || defaultSchema,
-                related_tools: skill.related_tools,
+                tools: skill.tools,
                 category: this.name,
             };
         });
@@ -132,7 +132,7 @@ export class SkillCollection implements ICollection<SkillDefinition> {
             title: this.title || this.name,
             description: this.description || `Skills: ${this.name}`,
             src: `${baseUrl}/api/skills/${this.name}`,
-            tools: this.getToolDefinitions()
+            tools: this.getToolDefinitions(),
         };
     }
 
@@ -164,43 +164,41 @@ export class SkillCollection implements ICollection<SkillDefinition> {
      * @param ctx - Hono context
      * @param preParsedPayload - Optional pre-parsed payload (used when routing from root endpoint)
      */
-    async execute(ctx: Context, preParsedPayload?: ToolExecutionPayload<Record<string, any>>): Promise<Response> {
+    async execute(ctx: Context, preParsedPayload?: ToolExecutionPayload): Promise<Response> {
         const toolCtx = ctx as ToolContext;
-        let payload: ToolExecutionPayload<Record<string, any>> | undefined = preParsedPayload;
+        const payload = preParsedPayload ?? toolCtx.payload;
         try {
             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? }'
-                    });
-                }
+                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 "learn_" prefix if present)
-            const skillName = toolName.startsWith('learn_')
-                ? toolName.replace('learn_', '')
-                : toolName;
+            const skillName = toolName.startsWith('learn_') ? toolName.replace('learn_', '') : toolName;
 
             const skill = this.skills.get(skillName);
 
             if (!skill) {
-                console.warn("[SkillCollection] Skill not found", {
+                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}`
+                    message: `Skill not found: ${skillName}`,
                 });
             }
 
-            const data = payload.tool_use.tool_input || {};
+            const input = payload.tool_use.tool_input;
+            const data =
+                typeof input === 'object' && input !== null && !Array.isArray(input)
+                    ? (input as Record<string, unknown>)
+                    : {};
             const result = await this.renderSkill(skill, data);
 
             // TODO: If skill.execution is set, run via Daytona
@@ -214,46 +212,48 @@ export class SkillCollection implements ICollection<SkillDefinition> {
                     skill_name: skill.name,
                     content_type: skill.content_type,
                     execution: skill.execution,
-                }
+                },
             } satisfies ToolExecutionResult & { tool_use_id: string });
-        } catch (err: any) {
-            const status = err.status || 500;
+        } catch (err: unknown) {
+            const status = err instanceof HTTPException ? err.status : 500;
+            const message = err instanceof Error ? err.message : 'Error executing skill';
+            const stack = err instanceof Error ? err.stack : undefined;
             const toolName = payload?.tool_use?.tool_name;
             const toolUseId = payload?.tool_use?.id;
 
             if (status >= 500) {
-                console.error("[SkillCollection] Skill execution failed", {
+                console.error('[SkillCollection] Skill execution failed', {
                     collection: this.name,
                     skill: toolName,
                     toolUseId,
-                    error: err.message,
+                    error: message,
                     status,
                     toolInput: payload?.tool_use?.tool_input,
-                    stack: err.stack,
+                    stack,
                 });
             }
 
-            return ctx.json({
-                tool_use_id: toolUseId || "unknown",
-                is_error: true,
-                content: err.message || "Error executing skill",
-            }, status);
+            return ctx.json(
+                {
+                    tool_use_id: toolUseId || 'unknown',
+                    is_error: true,
+                    content: message,
+                },
+                status,
+            );
         }
     }
 
     /**
      * Render skill instructions (static or dynamic)
      */
-    private async renderSkill(
-        skill: SkillDefinition,
-        _data: Record<string, unknown>
-    ): Promise<SkillExecutionResult> {
+    private async renderSkill(skill: SkillDefinition, _data: Record<string, unknown>): Promise<SkillExecutionResult> {
         const instructions = skill.instructions;
 
         if (skill.content_type === 'jst') {
             // JST templates are not currently supported
             throw new HTTPException(501, {
-                message: `JST templates are not currently supported. Use 'md' content type instead.`
+                message: `JST templates are not currently supported. Use 'md' content type instead.`,
             });
         }
 
@@ -267,9 +267,9 @@ export class SkillCollection implements ICollection<SkillDefinition> {
 // ================== Skill Parser ==================
 
 interface SkillFrontmatter {
-    name: string;
+    name?: string;
     title?: string;
-    description: string;
+    description?: string;
     keywords?: string[];
     tools?: string[];
     data_patterns?: string[];
@@ -299,15 +299,12 @@ interface SkillFrontmatter {
  * Your markdown/jst content here...
  * ```
  */
-export function parseSkillFile(
-    content: string,
-    contentType: SkillContentType
-): SkillDefinition {
+export function parseSkillFile(content: string, contentType: SkillContentType): SkillDefinition {
     // Parse YAML frontmatter
     const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
 
     if (!frontmatterMatch) {
-        throw new Error("Invalid skill file: missing YAML frontmatter");
+        throw new Error('Invalid skill file: missing YAML frontmatter');
     }
 
     const [, yamlContent, body] = frontmatterMatch;
@@ -357,7 +354,7 @@ export function parseSkillFile(
 
     // Related tools from frontmatter
     if (frontmatter.tools) {
-        skill.related_tools = frontmatter.tools;
+        skill.tools = frontmatter.tools;
     }
 
     return skill;
@@ -367,7 +364,7 @@ export function parseSkillFile(
  * Simple YAML frontmatter parser (handles basic key: value and arrays)
  */
 function parseYamlFrontmatter(yaml: string): SkillFrontmatter {
-    const result: Record<string, any> = {};
+    const result: Record<string, unknown> = {};
     const lines = yaml.split('\n');
 
     for (const line of lines) {
@@ -382,19 +379,41 @@ function parseYamlFrontmatter(yaml: string): SkillFrontmatter {
 
         // Handle array syntax: [item1, item2]
         if (value.startsWith('[') && value.endsWith(']')) {
-            const items = value.slice(1, -1).split(',').map(s => s.trim());
-            result[key] = items.filter(s => s.length > 0);
+            const items = value
+                .slice(1, -1)
+                .split(',')
+                .map((s) => s.trim());
+            result[key] = items.filter((s) => s.length > 0);
         } else {
             // Remove quotes if present
-            if ((value.startsWith('"') && value.endsWith('"')) ||
-                (value.startsWith("'") && value.endsWith("'"))) {
+            if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
                 value = value.slice(1, -1);
             }
             result[key] = value;
         }
     }
 
-    return result as SkillFrontmatter;
+    return {
+        name: asString(result.name),
+        title: asString(result.title),
+        description: asString(result.description),
+        keywords: asStringArray(result.keywords),
+        tools: asStringArray(result.tools),
+        data_patterns: asStringArray(result.data_patterns),
+        language: asString(result.language),
+        packages: asStringArray(result.packages),
+        system_packages: asStringArray(result.system_packages),
+        widgets: asStringArray(result.widgets),
+        scripts: asStringArray(result.scripts),
+    };
+}
+
+function asString(value: unknown): string | undefined {
+    return typeof value === 'string' ? value : undefined;
+}
+
+function asStringArray(value: unknown): string[] | undefined {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string') ? value : undefined;
 }
 
 /**
@@ -402,7 +421,7 @@ function parseYamlFrontmatter(yaml: string): SkillFrontmatter {
  */
 export async function loadSkillFromFile(
     filePath: string,
-    fs: { readFile: (path: string, encoding: string) => Promise<string> }
+    fs: { readFile: (path: string, encoding: string) => Promise<string> },
 ): Promise<SkillDefinition> {
     const content = await fs.readFile(filePath, 'utf-8');
     const contentType: SkillContentType = filePath.endsWith('.jst') ? 'jst' : 'md';
@@ -445,17 +464,17 @@ export function loadSkillsFromDirectory(dirPath: string): SkillDefinition[] {
             if (!stat.isDirectory()) continue;
 
             // Look for SKILL.md or SKILL.jst
-            const mdPath = join(entryPath, "SKILL.md");
-            const jstPath = join(entryPath, "SKILL.jst");
+            const mdPath = join(entryPath, 'SKILL.md');
+            const jstPath = join(entryPath, 'SKILL.jst');
 
             let content: string | undefined;
             let contentType: SkillContentType = 'md';
 
             if (existsSync(mdPath)) {
-                content = readFileSync(mdPath, "utf-8");
+                content = readFileSync(mdPath, 'utf-8');
                 contentType = 'md';
             } else if (existsSync(jstPath)) {
-                content = readFileSync(jstPath, "utf-8");
+                content = readFileSync(jstPath, 'utf-8');
                 contentType = 'jst';
             }
 

package/src/ToolCollection.ts

@@ -1,27 +1,34 @@
-import { AgentToolDefinition } from "@vertesia/common";
-import { existsSync, readdirSync, statSync } from "fs";
-import { Context } from "hono";
-import { HTTPException } from "hono/http-exception";
-import { join } from "path";
-import { pathToFileURL } from "url";
-import { authorize } from "./auth.js";
-import { ToolContext } from "./server/types.js";
-import { ToolRegistry } from "./ToolRegistry.js";
-import type { CollectionProperties, ICollection, Tool, ToolExecutionPayload, ToolExecutionResponse, ToolExecutionResponseError, ToolUseContext } from "./types.js";
-import { kebabCaseToTitle } from "./utils.js";
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { AgentToolDefinition } from '@vertesia/common';
+import type { Context } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import { authorize } from './auth.js';
+import type { ToolContext } from './server/types.js';
+import { ToolRegistry } from './ToolRegistry.js';
+import type {
+    CollectionProperties,
+    ICollection,
+    Tool,
+    ToolExecutionPayload,
+    ToolExecutionResponse,
+    ToolExecutionResponseError,
+    ToolUseContext,
+} from './types.js';
+import { kebabCaseToTitle } from './utils.js';
 
 export interface ToolCollectionProperties extends CollectionProperties {
     /**
      * The tools
      */
-    tools: Tool<any>[];
+    tools: Tool[];
 }
 
 /**
  * Implements a tools collection endpoint
  */
-export class ToolCollection implements ICollection<Tool<any>> {
-
+export class ToolCollection implements ICollection<Tool> {
     /**
      * A kebab case collection name. Must only contains alphanumeric and dash characters,
      * The name can be used to generate the path where the collection is exposed.
@@ -29,7 +36,7 @@ export class ToolCollection implements ICollection<Tool<any>> {
      */
     name: string;
     /**
-     * Optional title for UI display. 
+     * Optional title for UI display.
      * If not provided the title will be generated form the kebab case name by replacing - with spaces and upper casing first letter in words.
      */
     title?: string;
@@ -38,7 +45,7 @@ export class ToolCollection implements ICollection<Tool<any>> {
      */
     icon?: string;
     /**
-     * A short description 
+     * A short description
      */
     description?: string;
     /**
@@ -46,9 +53,7 @@ export class ToolCollection implements ICollection<Tool<any>> {
      */
     tools: ToolRegistry;
 
-    constructor({
-        name, title, icon, description, tools
-    }: ToolCollectionProperties) {
+    constructor({ name, title, icon, description, tools }: ToolCollectionProperties) {
         this.name = name;
         this.title = title || kebabCaseToTitle(name);
         this.icon = icon;
@@ -57,27 +62,27 @@ export class ToolCollection implements ICollection<Tool<any>> {
         this.tools = new ToolRegistry(name, tools);
     }
 
-    [Symbol.iterator](): Iterator<Tool<any>> {
+    [Symbol.iterator](): Iterator<Tool> {
         let index = 0;
         const tools = this.tools.getTools();
 
         return {
-            next(): IteratorResult<Tool<any>> {
+            next(): IteratorResult<Tool> {
                 if (index < tools.length) {
                     return { value: tools[index++], done: false };
                 } else {
                     return { done: true, value: undefined };
                 }
-            }
+            },
         };
     }
 
-    map<U>(callback: (tool: Tool<any>, index: number) => U): U[] {
+    map<U>(callback: (tool: Tool, index: number) => U): U[] {
         return this.tools.getTools().map(callback);
     }
 
-    async execute(ctx: Context, preParsedPayload?: ToolExecutionPayload<any>): Promise<Response> {
-        let payload: ToolExecutionPayload<any> | undefined = preParsedPayload;
+    async execute(ctx: Context, preParsedPayload?: ToolExecutionPayload): Promise<Response> {
+        let payload: ToolExecutionPayload | undefined = preParsedPayload;
         try {
             if (!payload) {
                 payload = await readPayload(ctx);
@@ -99,27 +104,33 @@ export class ToolCollection implements ICollection<Tool<any>> {
             const r = await this.tools.runTool(payload, session);
             return ctx.json({
                 ...r,
-                tool_use_id: payload.tool_use.id
+                tool_use_id: payload.tool_use.id,
             } satisfies ToolExecutionResponse);
-        } catch (err: any) { // HTTPException ?
-            const status = err.status || 500;
+        } catch (err: unknown) {
+            // HTTPException ?
+            const status = err instanceof HTTPException ? err.status : 500;
+            const message = err instanceof Error ? err.message : 'Error executing tool';
+            const stack = err instanceof Error ? err.stack : undefined;
             const toolName = payload?.tool_use?.tool_name;
             const toolUseId = payload?.tool_use?.id;
 
-            console.error("[ToolCollection] Tool execution failed", {
+            console.error('[ToolCollection] Tool execution failed', {
                 collection: this.name,
                 tool: toolName,
                 toolUseId,
-                error: err.message,
+                error: message,
                 status,
-                stack: err.stack,
+                stack,
             });
 
-            return ctx.json({
-                tool_use_id: toolUseId || "undefined",
-                error: err.message || "Error executing tool",
-                status
-            } satisfies ToolExecutionResponseError, status)
+            return ctx.json(
+                {
+                    tool_use_id: toolUseId || 'undefined',
+                    error: message,
+                    status,
+                } satisfies ToolExecutionResponseError,
+                status,
+            );
         }
     }
 
@@ -131,11 +142,9 @@ export class ToolCollection implements ICollection<Tool<any>> {
     getToolDefinitions(context?: ToolUseContext): AgentToolDefinition[] {
         return this.tools.getDefinitions(context);
     }
-
 }
 
-
-function readPayload(ctx: Context): ToolExecutionPayload<any> {
+function readPayload(ctx: Context): ToolExecutionPayload {
     const toolCtx = ctx as ToolContext;
 
     // Check if body was already parsed and validated by middleware
@@ -145,7 +154,8 @@ function readPayload(ctx: Context): ToolExecutionPayload<any> {
 
     // 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? }'
+        message:
+            'Invalid or missing tool execution payload. Expected { tool_use: { id, tool_name, tool_input? }, metadata? }',
     });
 }
 
@@ -166,8 +176,8 @@ function readPayload(ctx: Context): ToolExecutionPayload<any> {
  * @param toolsDir - Path to the tools directory (e.g., /path/to/collection/tools)
  * @returns Promise resolving to array of Tool objects
  */
-export async function loadToolsFromDirectory(toolsDir: string): Promise<Tool<any>[]> {
-    const tools: Tool<any>[] = [];
+export async function loadToolsFromDirectory(toolsDir: string): Promise<Tool[]> {
+    const tools: Tool[] = [];
 
     if (!existsSync(toolsDir)) {
         console.warn(`Tools directory not found: ${toolsDir}`);
@@ -213,4 +223,3 @@ export async function loadToolsFromDirectory(toolsDir: string): Promise<Tool<any
 
     return tools;
 }
-