@vertesia/tools-sdk 0.80.0-dev.20251121 → 0.80.0

package/src/InteractionCollection.ts

@@ -1,3 +1,6 @@
+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 { kebabCaseToTitle } from "./utils.js";
@@ -51,3 +54,90 @@ 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

@@ -0,0 +1,389 @@
+import { readdirSync, statSync, existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { ToolDefinition } from "@llumiverse/common";
+import { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+import type {
+    CollectionProperties,
+    ICollection,
+    SkillContentType,
+    SkillDefinition,
+    SkillExecutionResult,
+    ToolCollectionDefinition,
+    ToolExecutionPayload,
+    ToolExecutionResult,
+} from "./types.js";
+import { kebabCaseToTitle } from "./utils.js";
+
+export interface SkillCollectionProperties extends CollectionProperties {
+    /**
+     * The skills in this collection
+     */
+    skills: SkillDefinition[];
+}
+
+/**
+ * Implements a skills collection endpoint.
+ * Skills provide contextual instructions to agents.
+ * They can be static (markdown) or dynamic (JST templates).
+ */
+export class SkillCollection implements ICollection<SkillDefinition> {
+    /**
+     * A kebab case collection name
+     */
+    name: string;
+    /**
+     * Optional title for UI display
+     */
+    title?: string;
+    /**
+     * Optional icon for UI display
+     */
+    icon?: string;
+    /**
+     * A short description
+     */
+    description?: string;
+    /**
+     * The skills in this collection
+     */
+    private skills: Map<string, SkillDefinition>;
+
+    constructor({ name, title, icon, description, skills }: SkillCollectionProperties) {
+        this.name = name;
+        this.title = title || kebabCaseToTitle(name);
+        this.icon = icon;
+        this.description = description;
+        this.skills = new Map(skills.map(s => [s.name, s]));
+    }
+
+    [Symbol.iterator](): Iterator<SkillDefinition> {
+        return this.skills.values();
+    }
+
+    map<U>(callback: (skill: SkillDefinition, index: number) => U): U[] {
+        return Array.from(this.skills.values()).map(callback);
+    }
+
+    /**
+     * Get a skill by name
+     */
+    getSkill(name: string): SkillDefinition | undefined {
+        return this.skills.get(name);
+    }
+
+    /**
+     * Get all skill definitions
+     */
+    getSkillDefinitions(): SkillDefinition[] {
+        return Array.from(this.skills.values());
+    }
+
+    /**
+     * Get skills exposed as tool definitions.
+     * This allows skills to appear alongside regular tools.
+     * When called, they return rendered instructions.
+     */
+    getToolDefinitions(): ToolDefinition[] {
+        const defaultSchema: ToolDefinition['input_schema'] = {
+            type: 'object',
+            properties: {
+                context: {
+                    type: "string",
+                    description: "Additional context or specific requirements for this task"
+                }
+            }
+        };
+
+        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
+        }));
+    }
+
+    /**
+     * Get as a tool collection definition (for listing alongside tools)
+     */
+    getAsToolCollection(baseUrl: string): ToolCollectionDefinition {
+        return {
+            title: this.title || this.name,
+            description: this.description || `Skills: ${this.name}`,
+            src: `${baseUrl}/api/skills/${this.name}`,
+            tools: this.getToolDefinitions()
+        };
+    }
+
+    /**
+     * Execute a skill - accepts standard tool execution payload.
+     * Returns rendered instructions in tool result format.
+     */
+    async execute(ctx: Context): Promise<Response> {
+        let payload: ToolExecutionPayload<Record<string, any>> | undefined;
+        try {
+            payload = await ctx.req.json() as ToolExecutionPayload<Record<string, any>>;
+            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)
+                : toolName;
+
+            const skill = this.skills.get(skillName);
+
+            if (!skill) {
+                throw new HTTPException(404, {
+                    message: `Skill not found: ${skillName}`
+                });
+            }
+
+            const data = payload.tool_use.tool_input || {};
+            const result = await this.renderSkill(skill, data);
+
+            // TODO: If skill.execution is set, run via Daytona
+
+            // Return in tool result format
+            return ctx.json({
+                tool_use_id: payload.tool_use.id,
+                is_error: false,
+                content: result.instructions,
+                meta: {
+                    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;
+            return ctx.json({
+                tool_use_id: payload?.tool_use?.id || "unknown",
+                is_error: true,
+                content: err.message || "Error executing skill",
+            }, status);
+        }
+    }
+
+    /**
+     * Render skill instructions (static or dynamic)
+     */
+    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.`
+            });
+        }
+
+        return {
+            name: skill.name,
+            instructions,
+        };
+    }
+}
+
+// ================== Skill Parser ==================
+
+interface SkillFrontmatter {
+    name: string;
+    title?: string;
+    description: string;
+    keywords?: string[];
+    tools?: string[];
+    data_patterns?: string[];
+    language?: string;
+    packages?: string[];
+    system_packages?: string[];
+}
+
+/**
+ * Parse a SKILL.md or SKILL.jst file content into a SkillDefinition.
+ *
+ * Format:
+ * ```
+ * ---
+ * name: skill-name
+ * description: Short description
+ * keywords: [keyword1, keyword2]
+ * tools: [tool1, tool2]
+ * language: python
+ * packages: [numpy, pandas]
+ * ---
+ *
+ * # Instructions
+ *
+ * Your markdown/jst content here...
+ * ```
+ */
+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");
+    }
+
+    const [, yamlContent, body] = frontmatterMatch;
+    const frontmatter = parseYamlFrontmatter(yamlContent);
+    const instructions = body.trim();
+
+    if (!frontmatter.name) {
+        throw new Error("Skill file missing required 'name' field");
+    }
+    if (!frontmatter.description) {
+        throw new Error("Skill file missing required 'description' field");
+    }
+
+    const skill: SkillDefinition = {
+        name: frontmatter.name,
+        title: frontmatter.title,
+        description: frontmatter.description,
+        instructions,
+        content_type: contentType,
+    };
+
+    // Build context triggers
+    if (frontmatter.keywords || frontmatter.tools || frontmatter.data_patterns) {
+        skill.context_triggers = {
+            keywords: frontmatter.keywords,
+            tool_names: frontmatter.tools,
+            data_patterns: frontmatter.data_patterns,
+        };
+    }
+
+    // Build execution config
+    if (frontmatter.language) {
+        skill.execution = {
+            language: frontmatter.language,
+            packages: frontmatter.packages,
+            system_packages: frontmatter.system_packages,
+        };
+
+        // Extract code template from instructions if present
+        const codeBlockMatch = instructions.match(/```(?:python|javascript|typescript|js|ts|py)\n([\s\S]*?)```/);
+        if (codeBlockMatch) {
+            skill.execution.template = codeBlockMatch[1].trim();
+        }
+    }
+
+    // Related tools from frontmatter
+    if (frontmatter.tools) {
+        skill.related_tools = frontmatter.tools;
+    }
+
+    return skill;
+}
+
+/**
+ * Simple YAML frontmatter parser (handles basic key: value and arrays)
+ */
+function parseYamlFrontmatter(yaml: string): SkillFrontmatter {
+    const result: Record<string, any> = {};
+    const lines = yaml.split('\n');
+
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) continue;
+
+        const colonIndex = trimmed.indexOf(':');
+        if (colonIndex === -1) continue;
+
+        const key = trimmed.slice(0, colonIndex).trim();
+        let value = trimmed.slice(colonIndex + 1).trim();
+
+        // 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);
+        } else {
+            // Remove quotes if present
+            if ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'"))) {
+                value = value.slice(1, -1);
+            }
+            result[key] = value;
+        }
+    }
+
+    return result as SkillFrontmatter;
+}
+
+/**
+ * Helper to load skill from file path (for Node.js usage)
+ */
+export async function loadSkillFromFile(
+    filePath: 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';
+    return parseSkillFile(content, contentType);
+}
+
+/**
+ * Load all skills from a directory.
+ * Scans for subdirectories containing SKILL.md files.
+ *
+ * Directory structure:
+ * ```
+ * skills/
+ *   nagare/
+ *     fund-onboarding/
+ *       SKILL.md
+ *     monte-carlo/
+ *       SKILL.md
+ * ```
+ *
+ * @param dirPath - Path to the skills collection directory
+ * @returns Array of parsed skill definitions
+ */
+export function loadSkillsFromDirectory(dirPath: string): SkillDefinition[] {
+    const skills: SkillDefinition[] = [];
+
+    let entries: string[];
+    try {
+        entries = readdirSync(dirPath);
+    } catch {
+        console.warn(`Could not read skills directory: ${dirPath}`);
+        return skills;
+    }
+
+    for (const entry of entries) {
+        const entryPath = join(dirPath, entry);
+
+        try {
+            const stat = statSync(entryPath);
+            if (!stat.isDirectory()) continue;
+
+            // Look for SKILL.md or 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");
+                contentType = 'md';
+            } else if (existsSync(jstPath)) {
+                content = readFileSync(jstPath, "utf-8");
+                contentType = 'jst';
+            }
+
+            if (content) {
+                skills.push(parseSkillFile(content, contentType));
+            }
+        } catch (err) {
+            console.warn(`Error loading skill from ${entryPath}:`, err);
+        }
+    }
+
+    return skills;
+}

package/src/ToolCollection.ts

@@ -1,3 +1,6 @@
+import { readdirSync, statSync, existsSync } from "fs";
+import { join } from "path";
+import { pathToFileURL } from "url";
 import { Context } from "hono";
 import { HTTPException } from "hono/http-exception";
 import { authorize } from "./auth.js";
@@ -107,3 +110,68 @@ async function readPayload(ctx: Context) {
     }
 }
 
+/**
+ * Load all tools from a directory.
+ * Scans for .js files and imports tools that match naming convention.
+ *
+ * Directory structure:
+ * ```
+ * collection/
+ *   tools/
+ *     SearchFundsTool.js    # exports SearchFundsTool
+ *     GetFundDetailsTool.js # exports GetFundDetailsTool
+ * ```
+ *
+ * Naming convention: File should export a Tool with name matching *Tool pattern.
+ *
+ * @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>[] = [];
+
+    if (!existsSync(toolsDir)) {
+        console.warn(`Tools directory not found: ${toolsDir}`);
+        return tools;
+    }
+
+    let entries: string[];
+    try {
+        entries = readdirSync(toolsDir);
+    } catch {
+        console.warn(`Could not read tools directory: ${toolsDir}`);
+        return tools;
+    }
+
+    for (const entry of entries) {
+        // Only process .js and .ts files that end with Tool
+        if (!entry.endsWith('Tool.js') && !entry.endsWith('Tool.ts')) continue;
+        if (entry.endsWith('.d.ts')) continue;
+
+        const entryPath = join(toolsDir, entry);
+
+        try {
+            const stat = statSync(entryPath);
+            if (!stat.isFile()) continue;
+
+            // Dynamic import - need file:// URL for ESM
+            const fileUrl = pathToFileURL(entryPath).href;
+            const module = await import(fileUrl);
+
+            // Find exported Tool (named export matching filename or any Tool export)
+            const baseName = entry.replace(/\.(js|ts)$/, '');
+            const tool = module[baseName] || module.default;
+
+            if (tool && typeof tool.name === 'string' && typeof tool.run === 'function') {
+                tools.push(tool);
+            } else {
+                console.warn(`No valid Tool export found in ${entry}`);
+            }
+        } catch (err) {
+            console.warn(`Error loading tool from ${entry}:`, err);
+        }
+    }
+
+    return tools;
+}
+

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

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