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

package/README.md

@@ -0,0 +1,122 @@
+# @vertesia/tools-sdk
+
+SDK for building remote tools, interactions, and skills that integrate with the Vertesia platform. Built on top of [Hono](https://hono.dev/) for lightweight, high-performance HTTP servers.
+
+## Installation
+
+```bash
+npm install @vertesia/tools-sdk hono
+# or
+pnpm add @vertesia/tools-sdk hono
+```
+
+## Quick Start
+
+```typescript
+import { createToolServer, ToolCollection } from "@vertesia/tools-sdk";
+
+// Define a tool collection
+const myTools = new ToolCollection({
+  name: "my-tools",
+  description: "My custom tools",
+  tools: [
+    {
+      name: "hello",
+      description: "Says hello",
+      parameters: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Name to greet" },
+        },
+        required: ["name"],
+      },
+      execute: async ({ name }) => {
+        return { message: `Hello, ${name}!` };
+      },
+    },
+  ],
+});
+
+// Create the server
+const server = createToolServer({
+  title: "My Tools Server",
+  tools: [myTools],
+});
+
+export default server;
+```
+
+## Features
+
+### Tool Collections
+
+Define collections of tools that can be called remotely:
+
+```typescript
+import { ToolCollection } from "@vertesia/tools-sdk";
+
+const tools = new ToolCollection({
+  name: "utilities",
+  description: "Utility tools",
+  tools: [/* tool definitions */],
+});
+```
+
+### Skill Collections
+
+Define skills that can be executed by agents:
+
+```typescript
+import { SkillCollection } from "@vertesia/tools-sdk";
+
+const skills = new SkillCollection({
+  name: "my-skills",
+  description: "Custom skills",
+  skills: [/* skill definitions */],
+});
+```
+
+### Interaction Collections
+
+Expose interactions for execution:
+
+```typescript
+import { InteractionCollection } from "@vertesia/tools-sdk";
+
+const interactions = new InteractionCollection({
+  name: "my-interactions",
+  interactions: [/* interaction refs */],
+});
+```
+
+### Server Configuration
+
+```typescript
+const server = createToolServer({
+  title: "My Server",           // HTML page title
+  prefix: "/api",               // API route prefix (default: '/api')
+  tools: [toolCollection],      // Tool collections
+  skills: [skillCollection],    // Skill collections
+  interactions: [interactionCollection], // Interaction collections
+  disableHtml: false,           // Disable HTML documentation pages
+});
+```
+
+### Authentication
+
+The SDK includes built-in JWT authentication:
+
+```typescript
+import { authorize } from "@vertesia/tools-sdk";
+
+// In your route handler
+const session = await authorize(request);
+```
+
+## API Reference
+
+For detailed API documentation, visit [docs.vertesiahq.com](https://docs.vertesiahq.com).
+
+## License
+
+Apache-2.0

package/lib/cjs/InteractionCollection.js

@@ -1,6 +1,44 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InteractionCollection = void 0;
+exports.loadInteractionsFromDirectory = loadInteractionsFromDirectory;
+exports.readPromptFile = readPromptFile;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const url_1 = require("url");
 const utils_js_1 = require("./utils.js");
 class InteractionCollection {
     interactions;
@@ -43,4 +81,84 @@ class InteractionCollection {
     }
 }
 exports.InteractionCollection = InteractionCollection;
+/**
+ * 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
+ */
+async function loadInteractionsFromDirectory(interactionsDir) {
+    const interactions = [];
+    if (!(0, fs_1.existsSync)(interactionsDir)) {
+        console.warn(`Interactions directory not found: ${interactionsDir}`);
+        return interactions;
+    }
+    let entries;
+    try {
+        entries = (0, fs_1.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 = (0, path_1.join)(interactionsDir, entry);
+        try {
+            const stat = (0, fs_1.statSync)(entryPath);
+            if (!stat.isDirectory())
+                continue;
+            // Look for index.ts or index.js in the subdirectory
+            const indexTs = (0, path_1.join)(entryPath, 'index.ts');
+            const indexJs = (0, path_1.join)(entryPath, 'index.js');
+            const indexPath = (0, fs_1.existsSync)(indexTs) ? indexTs : (0, fs_1.existsSync)(indexJs) ? indexJs : null;
+            if (!indexPath) {
+                continue; // No index file, skip
+            }
+            // Dynamic import
+            const fileUrl = (0, url_1.pathToFileURL)(indexPath).href;
+            const module = await Promise.resolve(`${fileUrl}`).then(s => __importStar(require(s)));
+            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
+ */
+function readPromptFile(dirname, filename) {
+    const filePath = (0, path_1.join)(dirname, filename);
+    return (0, fs_1.readFileSync)(filePath, 'utf-8');
+}
 //# sourceMappingURL=InteractionCollection.js.map

package/lib/cjs/InteractionCollection.js.map

@@ -1 +1 @@
-{"version":3,"file":"InteractionCollection.js","sourceRoot":"","sources":["../../src/InteractionCollection.ts"],"names":[],"mappings":";;;AAEA,yCAA8C;AAK9C,MAAa,qBAAqB;IAC9B,YAAY,CAAoB;IAChC,IAAI,CAAS;IACb,KAAK,CAAU;IACf,IAAI,CAAU;IACd,WAAW,CAAU;IACrB,YAAY,EACR,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,YAAY,EACnB;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,KAAK,IAAI,IAAA,2BAAgB,EAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACrC,CAAC;IACD,cAAc,CAAC,WAAgB;QAC3B,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACxC,CAAC;IAED,eAAe;QACX,OAAO,IAAI,CAAC,YAAY,CAAC;IAC7B,CAAC;IAED,CAAC,MAAM,CAAC,QAAQ,CAAC;QACb,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QAEvC,OAAO;YACH,IAAI;gBACA,IAAI,KAAK,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC;oBAC9B,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;gBACzD,CAAC;qBAAM,CAAC;oBACJ,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;gBAC5C,CAAC;YACL,CAAC;SACJ,CAAC;IACN,CAAC;IAED,GAAG,CAAI,QAA4D;QAC/D,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED,oBAAoB,CAAC,IAAY;QAC7B,OAAO,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,WAAW,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAC5E,CAAC;CACJ;AA7CD,sDA6CC"}
+{"version":3,"file":"InteractionCollection.js","sourceRoot":"","sources":["../../src/InteractionCollection.ts"],"names":[],"mappings":"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"}

package/lib/cjs/SkillCollection.js

@@ -0,0 +1,318 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkillCollection = void 0;
+exports.parseSkillFile = parseSkillFile;
+exports.loadSkillFromFile = loadSkillFromFile;
+exports.loadSkillsFromDirectory = loadSkillsFromDirectory;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const http_exception_1 = require("hono/http-exception");
+const utils_js_1 = require("./utils.js");
+/**
+ * Implements a skills collection endpoint.
+ * Skills provide contextual instructions to agents.
+ * They can be static (markdown) or dynamic (JST templates).
+ */
+class SkillCollection {
+    /**
+     * A kebab case collection name
+     */
+    name;
+    /**
+     * Optional title for UI display
+     */
+    title;
+    /**
+     * Optional icon for UI display
+     */
+    icon;
+    /**
+     * A short description
+     */
+    description;
+    /**
+     * The skills in this collection
+     */
+    skills;
+    constructor({ name, title, icon, description, skills }) {
+        this.name = name;
+        this.title = title || (0, utils_js_1.kebabCaseToTitle)(name);
+        this.icon = icon;
+        this.description = description;
+        this.skills = new Map(skills.map(s => [s.name, s]));
+    }
+    [Symbol.iterator]() {
+        return this.skills.values();
+    }
+    map(callback) {
+        return Array.from(this.skills.values()).map(callback);
+    }
+    /**
+     * Get a skill by name
+     */
+    getSkill(name) {
+        return this.skills.get(name);
+    }
+    /**
+     * Get all skill definitions
+     */
+    getSkillDefinitions() {
+        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() {
+        const defaultSchema = {
+            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) {
+        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) {
+        let payload;
+        try {
+            payload = await ctx.req.json();
+            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 http_exception_1.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,
+                }
+            });
+        }
+        catch (err) {
+            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)
+     */
+    async renderSkill(skill, _data) {
+        const instructions = skill.instructions;
+        if (skill.content_type === 'jst') {
+            // JST templates are not currently supported
+            throw new http_exception_1.HTTPException(501, {
+                message: `JST templates are not currently supported. Use 'md' content type instead.`
+            });
+        }
+        return {
+            name: skill.name,
+            instructions,
+        };
+    }
+}
+exports.SkillCollection = SkillCollection;
+/**
+ * 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...
+ * ```
+ */
+function parseSkillFile(content, contentType) {
+    // 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 = {
+        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) {
+    const result = {};
+    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;
+}
+/**
+ * Helper to load skill from file path (for Node.js usage)
+ */
+async function loadSkillFromFile(filePath, fs) {
+    const content = await fs.readFile(filePath, 'utf-8');
+    const contentType = 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
+ */
+function loadSkillsFromDirectory(dirPath) {
+    const skills = [];
+    let entries;
+    try {
+        entries = (0, fs_1.readdirSync)(dirPath);
+    }
+    catch {
+        console.warn(`Could not read skills directory: ${dirPath}`);
+        return skills;
+    }
+    for (const entry of entries) {
+        const entryPath = (0, path_1.join)(dirPath, entry);
+        try {
+            const stat = (0, fs_1.statSync)(entryPath);
+            if (!stat.isDirectory())
+                continue;
+            // Look for SKILL.md or SKILL.jst
+            const mdPath = (0, path_1.join)(entryPath, "SKILL.md");
+            const jstPath = (0, path_1.join)(entryPath, "SKILL.jst");
+            let content;
+            let contentType = 'md';
+            if ((0, fs_1.existsSync)(mdPath)) {
+                content = (0, fs_1.readFileSync)(mdPath, "utf-8");
+                contentType = 'md';
+            }
+            else if ((0, fs_1.existsSync)(jstPath)) {
+                content = (0, fs_1.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;
+}
+//# sourceMappingURL=SkillCollection.js.map

package/lib/cjs/SkillCollection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SkillCollection.js","sourceRoot":"","sources":["../../src/SkillCollection.ts"],"names":[],"mappings":"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"}