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

package/src/server/templates.ts

@@ -0,0 +1,80 @@
+// ================== Template Endpoints ==================
+
+import { RenderingTemplateDefinition, RenderingTemplateDefinitionRef } from "@vertesia/common";
+import { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { RenderingTemplateCollection } from "../RenderingTemplateCollection.js";
+import { ToolServerConfig } from "./types.js";
+
+function toRef(basePath: string, collectionName: string, { instructions: _, ...ref }: RenderingTemplateDefinition): RenderingTemplateDefinitionRef {
+    return { ...ref, path: `${basePath}/${collectionName}/${ref.name}` };
+}
+
+export function createTemplatesRoute(app: Hono, basePath: string, config: ToolServerConfig) {
+    const { templates = [] } = config;
+
+    // GET /api/templates - Returns all templates from all collections (without instructions)
+    app.get(basePath, (c) => {
+        const allTemplates = templates.flatMap(coll =>
+            coll.templates.map(t => toRef(basePath, coll.name, t))
+        );
+
+        return c.json({
+            title: 'All Templates',
+            description: 'All available templates across all collections',
+            templates: allTemplates,
+            collections: templates.map(t => ({
+                name: t.name,
+                title: t.title,
+                description: t.description,
+            })),
+        });
+    });
+
+    // Create template collection endpoints
+    for (const coll of templates) {
+        app.route(`${basePath}/${coll.name}`, createTemplateEndpoints(basePath, coll));
+    }
+
+    // GET /api/templates/:name - Direct access by "collection:name" id format
+    app.get(`${basePath}/:id`, async (c) => {
+        const id = c.req.param('id');
+        const parts = id.split(':');
+        if (parts.length !== 2) {
+            throw new HTTPException(400, {
+                message: "Invalid template id. Expected format 'collection:name'"
+            });
+        }
+        const collName = parts[0];
+        const templateName = parts[1];
+        const template = templates.find(t => t.name === collName)?.getTemplate(templateName);
+        if (template) {
+            return c.json(template);
+        }
+
+        throw new HTTPException(404, {
+            message: "No template found with id: " + id
+        });
+    });
+}
+
+function createTemplateEndpoints(basePath: string, coll: RenderingTemplateCollection): Hono {
+    const endpoint = new Hono();
+
+    endpoint.get('/', (c: Context) => {
+        return c.json(coll.templates.map(t => toRef(basePath, coll.name, t)));
+    });
+
+    endpoint.get('/:name', (c: Context) => {
+        const name = c.req.param('name');
+        const template = coll.templates.find(t => t.name === name);
+        if (!template) {
+            throw new HTTPException(404, {
+                message: "No template found with name: " + name
+            });
+        }
+        return c.json(template);
+    });
+
+    return endpoint;
+}

package/src/server/tools.ts

@@ -22,20 +22,11 @@ export function createToolsRoute(app: Hono, basePath: string, config: ToolServer
 
     app.get(basePath, (c) => {
         const url = new URL(c.req.url);
-        const defaultOnly = c.req.query('defaultOnly') === 'true';
-        const unlockedParam = c.req.query('unlocked');
-        const unlockedTools = unlockedParam ? unlockedParam.split(',').map(t => t.trim()).filter(Boolean) : [];
-
-        const filterOptions = defaultOnly ? { defaultOnly, unlockedTools } : undefined;
 
         const allTools: ToolDefinition[] = [];
-        let reserveToolCount = 0;
 
         for (const coll of tools) {
-            allTools.push(...coll.getToolDefinitions(filterOptions));
-            if (defaultOnly) {
-                reserveToolCount += coll.getReserveTools(unlockedTools).length;
-            }
+            allTools.push(...coll.getToolDefinitions());
         }
 
         return c.json({
@@ -43,7 +34,6 @@ export function createToolsRoute(app: Hono, basePath: string, config: ToolServer
             title: 'All Tools',
             description: 'All available tools across all collections',
             tools: allTools,
-            reserveToolCount: defaultOnly ? reserveToolCount : undefined,
             collections: tools.map(t => ({
                 name: t.name,
                 title: t.title,
@@ -97,27 +87,18 @@ function createToolEndpoints(coll: ToolCollection): Hono {
     //   - unlocked=tool1,tool2: Comma-separated list of unlocked tool names
     endpoint.get('/', (c) => {
         const importSourceUrl = c.req.query('import') != null;
-        const defaultOnly = c.req.query('defaultOnly') === 'true';
-        const unlockedParam = c.req.query('unlocked');
-        const unlockedTools = unlockedParam ? unlockedParam.split(',').map(t => t.trim()).filter(Boolean) : [];
 
-        const filterOptions = defaultOnly ? { defaultOnly, unlockedTools } : undefined;
         const url = new URL(c.req.url);
 
-        const response: ToolCollectionDefinition & { reserveToolCount?: number } = {
+        const response: ToolCollectionDefinition = {
             src: importSourceUrl
                 ? `${url.origin}/libs/vertesia-tools-${coll.name}.js`
                 : `${url.origin}${url.pathname}`,
             title: coll.title || coll.name,
             description: coll.description || '',
-            tools: coll.getToolDefinitions(filterOptions)
+            tools: coll.getToolDefinitions()
         };
 
-        // Include reserve count when filtering
-        if (defaultOnly) {
-            response.reserveToolCount = coll.getReserveTools(unlockedTools).length;
-        }
-
         return c.json(response);
     });
 

package/src/server/types.ts

@@ -1,10 +1,11 @@
 import { Context } from "hono";
 import { InteractionCollection } from "../InteractionCollection.js";
 import { SkillCollection } from "../SkillCollection.js";
+import { RenderingTemplateCollection } from "../RenderingTemplateCollection.js";
 import { ToolCollection } from "../ToolCollection.js";
 import { ToolExecutionPayload } from "../types.js";
 import { JSONSchema } from "@llumiverse/common";
-import { AppUIConfig } from "@vertesia/common";
+import { AppUIConfig, ProjectConfiguration } from "@vertesia/common";
 import { ContentTypesCollection } from "../ContentTypesCollection.js";
 
 /**
@@ -60,6 +61,10 @@ export interface ToolServerConfig {
      * Skill collections to expose
      */
     skills?: SkillCollection[];
+    /**
+     * Template collections to expose
+     */
+    templates?: RenderingTemplateCollection[];
     /**
      * MCP providers to expose
      */
@@ -83,5 +88,13 @@ export interface ToolServerConfig {
      * Hide UI app links on the index page (default: false)
      */
     hideUILinks?: boolean;
+
+    /**
+     * If a filter is provided, it will be called with the project configuration when requesting tool definitions, and can be used to filter which tools are returned based on the project configuration. 
+     * This allows for dynamic enabling/disabling of tools based on project settings.
+     * @param projectConfig 
+     * @returns 
+     */
+    toolFilter?: (projectConfig: ProjectConfiguration) => boolean;
 }
 

package/src/server/widgets.ts

@@ -1,11 +1,7 @@
+import { AppWidgetInfo } from "@vertesia/common";
 import { Hono } from "hono";
 import { ToolServerConfig } from "./types.js";
 
-export interface WidgetInfo {
-    collection: string;
-    skill: string;
-    url: string;
-}
 
 export function createWidgetsRoute(app: Hono, basePath: string, config: ToolServerConfig) {
 
@@ -15,7 +11,7 @@ export function createWidgetsRoute(app: Hono, basePath: string, config: ToolServ
     app.get(basePath, (c) => {
         const url = new URL(c.req.url);
 
-        const widgets: Record<string, WidgetInfo> = {};
+        const widgets: Record<string, AppWidgetInfo> = {};
         for (const coll of skills) {
             const collWidgets = coll.getWidgets();
             for (const widget of collWidgets) {

package/src/server.ts

@@ -9,9 +9,10 @@ import { createSkillsRoute } from "./server/skills.js";
 import { createToolsRoute } from "./server/tools.js";
 import { ToolContext, ToolServerConfig } from "./server/types.js";
 import { ToolExecutionPayload } from "./types.js";
+import { createTemplatesRoute } from "./server/templates.js";
 import { createWidgetsRoute } from "./server/widgets.js";
 import { createPackageRoute } from "./server/app-package.js";
-import { createContentTypesRoute } from "./server/conyent-types.js";
+import { createContentTypesRoute } from "./server/content-types.js";
 
 // Schema for tool execution payload
 const ToolExecutionPayloadSchema = z.object({
@@ -46,6 +47,7 @@ export function createToolServer(config: ToolServerConfig): Hono {
         tools = [],
         interactions = [],
         skills = [],
+        templates = [],
         mcpProviders = [],
         disableHtml = false,
     } = config;
@@ -95,6 +97,7 @@ export function createToolServer(config: ToolServerConfig): Hono {
             endpoints: {
                 tools: allToolEndpoints,
                 interactions: interactions.map(col => `${prefix}/interactions/${col.name}`),
+                templates: templates.map(col => `${prefix}/templates/${col.name}`),
                 mcp: mcpProviders.map(p => `${prefix}/mcp/${p.name}`),
             }
         });
@@ -106,6 +109,7 @@ export function createToolServer(config: ToolServerConfig): Hono {
     createSkillsRoute(app, `${prefix}/skills`, config);
     createWidgetsRoute(app, `${prefix}/widgets`, config);
     createInteractionsRoute(app, `${prefix}/interactions`, config);
+    createTemplatesRoute(app, `${prefix}/templates`, config);
     createContentTypesRoute(app, `${prefix}/types`, config);
     createMcpRoute(app, `${prefix}/mcp`, config);
 

package/src/site/templates.ts

@@ -1,9 +1,10 @@
 import type { InteractionCollection } from "../InteractionCollection.js";
 import { ToolServerConfig } from "../server/types.js";
 import type { SkillCollection } from "../SkillCollection.js";
+import type { RenderingTemplateCollection } from "../RenderingTemplateCollection.js";
 import type { ToolCollection } from "../ToolCollection.js";
 import type { ContentTypesCollection } from "../ContentTypesCollection.js";
-import type { ICollection, SkillDefinition, Tool } from "../types.js";
+import type { ICollection, SkillDefinition, RenderingTemplateDefinition, Tool } from "../types.js";
 import { join } from "../utils.js";
 import { baseStyles } from "./styles.js";
 
@@ -25,6 +26,15 @@ const skillIcon = /*html*/`
   <path d="M12 2L2 7l10 5 10-5-10-5zM2 17l10 5 10-5M2 12l10 5 10-5"/>
 </svg>`;
 
+const templateIcon = /*html*/`
+<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+  <path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/>
+  <polyline points="14 2 14 8 20 8"/>
+  <line x1="16" y1="13" x2="8" y2="13"/>
+  <line x1="16" y1="17" x2="8" y2="17"/>
+  <polyline points="10 9 9 9 8 9"/>
+</svg>`;
+
 /**
  * Extended styles for detail pages
  */
@@ -247,6 +257,19 @@ ${baseStyles}
     color: white;
 }
 
+.template-type-badge {
+    background: #f59e0b;
+    color: white;
+}
+
+.template-type-badge.document {
+    background: #f59e0b;
+}
+
+.template-type-badge.presentation {
+    background: #8b5cf6;
+}
+
 @media (prefers-color-scheme: dark) {
     .nav a {
         color: #9ca3af;
@@ -584,6 +607,140 @@ export function skillDetailCard(skill: SkillDefinition, collection: SkillCollect
 </div>`;
 }
 
+/**
+ * Render a template endpoint URL with copy button
+ */
+function renderTemplateUrl(template: RenderingTemplateDefinition, collectionName: string): string {
+    const templatePath = `/api/templates/${collectionName}/${template.name}`;
+    return /*html*/`<div class="script-item" style='display: flex; align-items: center; gap: 0.5rem; width:100%;justify-content: space-between;'><span class="script-name">${templatePath}</span>
+        <button class="copy-btn" onclick="navigator.clipboard.writeText(window.location.origin + '${templatePath}')" title="Copy endpoint URL">
+            ${copyIcon}
+        </button>
+    </div>`;
+}
+
+/**
+ * Render a tag list
+ */
+function tagList(tags: string[] | undefined): string {
+    if (!tags || tags.length === 0) return '';
+    return /*html*/`
+    <div class="detail-section">
+        <h4 class="detail-section-title">Tags</h4>
+        <div class="keyword-list">
+            ${tags.map(tag => `<span class="keyword-tag">${tag}</span>`).join('')}
+        </div>
+    </div>`;
+}
+
+/**
+ * Render an asset file list
+ */
+function assetList(assets: string[]): string {
+    if (assets.length === 0) return '';
+    return /*html*/`
+    <div class="detail-section">
+        <h4 class="detail-section-title">Assets</h4>
+        <div class="script-list">
+            ${assets.map(asset => /*html*/`
+            <div class="script-item">
+                ${fileIcon}
+                <span class="script-name">${asset}</span>
+            </div>
+            `).join('')}
+        </div>
+    </div>`;
+}
+
+/**
+ * Render an instructions preview section
+ */
+function instructionsPreview(instructions: string): string {
+    return /*html*/`
+    <div class="detail-section">
+        <h4 class="detail-section-title">Instructions Preview</h4>
+        <div class="instructions-preview">${escapeHtml(instructions.slice(0, 1000))}${instructions.length > 1000 ? '...' : ''}</div>
+    </div>`;
+}
+
+/**
+ * Render a detailed template card
+ */
+export function templateDetailCard(template: RenderingTemplateDefinition, collection: RenderingTemplateCollection): string {
+    return /*html*/`
+<div class="detail-card">
+    <div class="detail-header">
+        <div>
+            <h3 class="detail-title">${template.title || template.name}</h3>
+            <p class="detail-desc">${template.description || 'No description'}</p>
+            ${renderTemplateUrl(template, collection.name)}
+        </div>
+        <div class="detail-badges">
+            <span class="badge template-type-badge ${template.type}">${template.type}</span>
+        </div>
+    </div>
+    <div class="detail-body">
+        <div class="info-grid">
+            <div class="info-item">
+                <div class="info-label">Type</div>
+                <div class="info-value"><code>${template.type}</code></div>
+            </div>
+            <div class="info-item">
+                <div class="info-label">Assets</div>
+                <div class="info-value">${template.assets.length} file${template.assets.length !== 1 ? 's' : ''}</div>
+            </div>
+        </div>
+
+        ${tagList(template.tags)}
+        ${assetList(template.assets)}
+        ${instructionsPreview(template.instructions)}
+    </div>
+</div>`;
+}
+
+/**
+ * Render a template collection detail page
+ */
+export function templateCollectionPage(collection: RenderingTemplateCollection): string {
+    const templatesArray = Array.from(collection);
+    return /*html*/`
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${collection.title || collection.name} - Templates</title>
+    <style>${detailStyles}</style>
+</head>
+<body>
+    <nav class="nav">
+        <a href="/">${backArrow} Back to all collections</a>
+    </nav>
+
+    <div class="header">
+        <div class="header-icon">${collection.icon || templateIcon}</div>
+        <div>
+            <h1>${collection.title || collection.name}</h1>
+            <p style="color: #6b7280; margin: 0.25rem 0 0 0;">${collection.description || ''}</p>
+            <div class="endpoint-box">
+                <code>/api/templates/${collection.name}</code>
+                <button class="copy-btn" onclick="navigator.clipboard.writeText(window.location.origin + '/api/templates/${collection.name}')" title="Copy endpoint URL">
+                    ${copyIcon}
+                </button>
+            </div>
+        </div>
+    </div>
+
+    <h2>${templatesArray.length} Template${templatesArray.length !== 1 ? 's' : ''}</h2>
+
+    ${templatesArray.length > 0 ?
+            templatesArray.map(template => templateDetailCard(template, collection)).join('') :
+            '<div class="empty-state">No templates in this collection</div>'
+        }
+</body>
+</html>`;
+}
+
 /**
  * Escape HTML for safe rendering
  */
@@ -656,6 +813,8 @@ function copyPluginUrl(btn) {
  * Note: The fourth argument is backward compatible:
  * - If a string is passed, it is treated as the title.
  * - If an array is passed, it is treated as MCP providers and the fifth argument (if any) is the title.
+ * @deprecated Static templates were replaced by a React site. Do not use them anymore. 
+ * Will be removed.
  */
 export function indexPage(
     config: ToolServerConfig
@@ -665,6 +824,7 @@ export function indexPage(
         tools = [],
         interactions = [],
         skills = [],
+        templates = [],
         types = [],
         mcpProviders = [],
         hideUILinks = false,
@@ -698,6 +858,7 @@ export function indexPage(
                         ${skills.length ? /*html*/`<span><dot></dot> ${skills.length} skill collection${skills.length !== 1 ? 's' : ''}</span>` : ''}
                         ${interactions.length ? /*html*/`<span><dot></dot> ${interactions.length} interaction collection${interactions.length !== 1 ? 's' : ''}</span>` : ''}
                         ${types.length ? /*html*/`<span><dot></dot> ${types.length} content type collection${types.length !== 1 ? 's' : ''}</span>` : ''}
+                        ${templates.length ? /*html*/`<span><dot></dot> ${templates.length} template collection${templates.length !== 1 ? 's' : ''}</span>` : ''}
                         ${mcpProviders.length ? /*html*/`<span><dot></dot> ${mcpProviders.length} MCP provider${mcpProviders.length !== 1 ? 's' : ''}</span>` : ''}
                     </div>
                     ${hideUILinks ? '' : renderUILinks()}
@@ -725,7 +886,7 @@ export function indexPage(
                 type="search"
                 id="collection-search"
                 class="search-input"
-                placeholder="Search tools, skills, interactions, types..."
+                placeholder="Search tools, skills, interactions, types, templates..."
                 aria-label="Search collections"
                 autocomplete="off"
             />
@@ -794,6 +955,22 @@ export function indexPage(
         </section>
         ` : ''}
 
+        ${templates.length > 0 ? /*html*/`
+        <section data-section="templates">
+            <hr>
+            <div class="section-header">
+                <h2>Rendering Template Collections</h2>
+                <p class="section-subtitle">Document and presentation templates for content generation.</p>
+            </div>
+            <div class="card-grid">
+                ${templates.map((t: RenderingTemplateCollection) => {
+        const count = t.getTemplateDefinitions().length;
+        return collectionCard(t, 'templates', `${count} template${count !== 1 ? 's' : ''}`);
+    }).join('')}
+            </div>
+        </section>
+        ` : ''}
+
         ${mcpProviders.length > 0 ? /*html*/`
         <section data-section="mcp">
             <hr>

package/src/types.ts

@@ -1,6 +1,6 @@
 import type { ToolDefinition, ToolUse } from "@llumiverse/common";
 import { VertesiaClient } from "@vertesia/client";
-import { AgentToolDefinition, AuthTokenPayload, ToolExecutionMetadata, ToolResult, ToolResultContent } from "@vertesia/common";
+import { AgentToolDefinition, AuthTokenPayload, ProjectConfiguration, RenderingTemplateDefinition, ToolExecutionMetadata, ToolResult, ToolResultContent } from "@vertesia/common";
 
 export type { ToolExecutionMetadata };
 
@@ -87,6 +87,15 @@ export interface ToolExecutionPayload<ParamsT extends Record<string, any>> {
 
 export type ToolFn<ParamsT extends Record<string, any>> = (payload: ToolExecutionPayload<ParamsT>, context: ToolExecutionContext) => Promise<ToolExecutionResult>;
 
+export interface ToolUseContext {
+    project_id?: string,
+    account_id?: string,
+    project_name?: string,
+    project_ns?: string,
+    configuration?: ProjectConfiguration;
+    vars?: Record<string, any>;
+}
+
 export interface Tool<ParamsT extends Record<string, any>> extends ToolDefinition {
     run: ToolFn<ParamsT>;
     /**
@@ -95,6 +104,15 @@ export interface Tool<ParamsT extends Record<string, any>> extends ToolDefinitio
      * - false: Tool is only available when activated by a skill's related_tools
      */
     default?: boolean;
+
+    /**
+     * Optional filter to check if the tool is enabled for the given project configuration.
+     * This can be used to dynamically enable/disable tools based on project settings, environment variables, or any other logic.
+     * If no filter is provided, the tool will be enabled by default.
+     * @param payload 
+     * @returns 
+     */
+    isEnabled?: (payload: ToolUseContext) => boolean;
 }
 
 
@@ -127,8 +145,17 @@ export interface MCPConnectionDetails {
      * If an empty string no authentication will be done
      */
     token: string;
+    /**
+     * Optional additional HTTP headers to include with requests to the MCP server.
+     * Merged with the Authorization header derived from the token.
+     */
+    headers?: Record<string, string>;
 }
 
+// ================== Template Types ==================
+
+export type { RenderingTemplateDefinition };
+
 // ================== Skill Types ==================
 
 /**
@@ -234,6 +261,16 @@ export interface SkillDefinition {
      * The widget file must be located in the skill directory under the name {{widget-name}}.tsx.
      */
     widgets?: string[];
+
+    /**
+     * Optional filter to check if the tool is enabled for the given project configuration.
+     * This can be used to dynamically enable/disable tools based on project settings, environment variables, or any other logic.
+     * If no filter is provided, the tool will be enabled by default.
+     * @param payload 
+     * @returns 
+     */
+    isEnabled?: (payload: ToolUseContext) => boolean;
+
 }
 
 /**

package/src/utils.ts

@@ -1,3 +1,16 @@
+/**
+ * Convert a name to a URL-safe path segment.
+ * If the name contains spaces or underscores, convert to PascalCase.
+ * Otherwise return as-is. Any characters not in [a-zA-Z0-9$_\-@] are replaced with '-'.
+ */
+export function toPathName(name: string): string {
+    let result = name;
+    if (result.includes(' ') || result.includes('_')) {
+        result = result.split(/[\s_]+/).map(w => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+    }
+    return result.replace(/[^a-zA-Z0-9$_\-@]/g, '-');
+}
+
 export function kebabCaseToTitle(name: string) {
     return name.split('-').map(p => p[0].toUpperCase() + p.substring(1)).join(' ');
 }
@@ -20,4 +33,5 @@ export function join(left: string, right: string) {
     } else {
         return left + '/' + right;
     }
-}
+}
+