@vertesia/tools-sdk 0.24.0-dev.202601221707

package/lib/types/site/styles.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Shared CSS styles for the tools server HTML pages
+ */
+export declare const baseStyles = "\n:root {\n    color-scheme: light dark;\n}\n\nbody {\n    font-family: system-ui, -apple-system, sans-serif;\n    margin: 0;\n    padding: 2.5rem 1.75rem;\n    background:\n        radial-gradient(circle at 0 0, rgba(56, 189, 248, 0.10), transparent 55%),\n        radial-gradient(circle at 100% 0, rgba(129, 140, 248, 0.12), transparent 55%),\n        #f9fafb;\n    color: #0f172a;\n    line-height: 1.5;\n}\n\n.page {\n    max-width: 1120px;\n    margin: 0 auto;\n}\n\n.hero {\n    display: flex;\n    justify-content: space-between;\n    align-items: flex-start;\n    gap: 2.25rem;\n    padding: 1.75rem 2rem;\n    margin-bottom: 2.5rem;\n    border-radius: 1.25rem;\n    background: linear-gradient(135deg, #ffffff, #f3f4ff);\n    border: 1px solid #e5e7eb;\n    box-shadow:\n        0 18px 40px rgba(15, 23, 42, 0.08),\n        0 0 0 1px rgba(248, 250, 252, 0.8);\n}\n\n.hero-main {\n    display: flex;\n    gap: 1.5rem;\n    align-items: center;\n}\n\n.hero-logo {\n    display: flex;\n    align-items: center;\n    justify-content: center;\n    width: 56px;\n    height: 56px;\n    border-radius: 999px;\n    background: radial-gradient(circle at 30% 0, #38bdf8, #6366f1);\n    box-shadow:\n        0 0 0 1px rgba(15, 23, 42, 0.85),\n        0 12px 30px rgba(37, 99, 235, 0.6);\n}\n\n.hero-logo-initial {\n    font-size: 1.1rem;\n    font-weight: 650;\n    letter-spacing: 0.08em;\n    text-transform: uppercase;\n    color: #eff6ff;\n}\n\n.hero-logo img {\n    display: block;\n    max-width: 80%;\n    max-height: 60%;\n}\n\n.logo-dark {\n    display: none;\n}\n\n.hero-meta {\n    display: flex;\n    flex-direction: column;\n    gap: 0.5rem;\n}\n\n.hero-eyebrow {\n    font-size: 0.75rem;\n    letter-spacing: 0.12em;\n    text-transform: uppercase;\n    color: #6b7280;\n}\n\n.hero-title {\n    font-size: 1.9rem;\n    font-weight: 650;\n    letter-spacing: -0.03em;\n    color: #0f172a;\n    margin: 0;\n}\n\n.hero-tagline {\n    font-size: 0.95rem;\n    color: #4b5563;\n    margin: 0.1rem 0 0 0;\n}\n\n.hero-summary {\n    display: flex;\n    flex-wrap: wrap;\n    gap: 0.5rem;\n    margin-top: 0.75rem;\n    font-size: 0.8rem;\n    color: #6b7280;\n}\n\n.hero-summary span {\n    display: inline-flex;\n    align-items: center;\n    gap: 0.35rem;\n    padding: 0.15rem 0.55rem;\n    border-radius: 999px;\n    background: #f9fafb;\n    border: 1px solid #e5e7eb;\n}\n\n.hero-summary dot {\n    width: 6px;\n    height: 6px;\n    border-radius: 999px;\n    display: inline-block;\n    background: #22c55e;\n}\n\n.search-bar {\n    display: flex;\n    flex-direction: column;\n    gap: 0.4rem;\n    margin: 0 0 1.75rem 0;\n}\n\n.search-input {\n    max-width: 360px;\n    padding: 0.55rem 0.75rem;\n    border-radius: 999px;\n    border: 1px solid #e5e7eb;\n    background: #ffffff;\n    color: #111827;\n    font-size: 0.9rem;\n    font-family: inherit;\n    box-shadow: 0 4px 10px rgba(15, 23, 42, 0.04);\n}\n\n.search-input::placeholder {\n    color: #9ca3af;\n}\n\n.search-input:focus {\n    outline: none;\n    border-color: #60a5fa;\n    box-shadow:\n        0 0 0 1px rgba(59, 130, 246, 0.4),\n        0 6px 18px rgba(37, 99, 235, 0.18);\n}\n\n.search-hint {\n    font-size: 0.75rem;\n    color: #9ca3af;\n}\n\n.search-empty {\n    margin-top: 1rem;\n    font-size: 0.85rem;\n    color: #9ca3af;\n}\n\n.hero-panel {\n    min-width: 220px;\n    max-width: 260px;\n    padding: 1.25rem 1.4rem;\n    border-radius: 1rem;\n    background: radial-gradient(circle at 0 0, rgba(59, 130, 246, 0.10), transparent 70%),\n        #eff6ff;\n    border: 1px solid #bfdbfe;\n    box-shadow: 0 16px 34px rgba(15, 23, 42, 0.10);\n    font-size: 0.8rem;\n}\n\n.hero-panel-label {\n    font-size: 0.7rem;\n    letter-spacing: 0.13em;\n    text-transform: uppercase;\n    color: #1d4ed8;\n    margin-bottom: 0.5rem;\n}\n\n.hero-panel-endpoint {\n    display: inline-flex;\n    align-items: center;\n    padding: 0.3rem 0.6rem;\n    border-radius: 0.5rem;\n    background: #f9fafb;\n    border: 1px solid #e5e7eb;\n    font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, \"Liberation Mono\", \"Courier New\", monospace;\n    font-size: 0.82rem;\n    color: #111827;\n}\n\n.hero-panel-hint {\n    margin-top: 0.6rem;\n    color: #6b7280;\n    line-height: 1.4;\n}\n\n.hero-panel-hint strong {\n    color: #111827;\n}\n\nh1, h2 {\n    margin: 0 0 1rem 0;\n    color: #0f172a;\n}\n\nh1 { font-size: 1.875rem; }\nh2 {\n    font-size: 1.4rem;\n    margin-top: 2rem;\n    letter-spacing: 0.03em;\n    text-transform: uppercase;\n    color: #6b7280;\n}\n\na {\n    color: #2563eb;\n    text-decoration: none;\n}\na:hover {\n    text-decoration: underline;\n}\n\nhr {\n    border: none;\n    border-top: 1px solid #e5e7eb;\n    margin: 2rem 0;\n}\n\n.card-grid {\n    display: grid;\n    grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));\n    gap: 1.5rem;\n}\n\n.card {\n    background: radial-gradient(circle at 0 0, rgba(56, 189, 248, 0.12), transparent 75%),\n        #ffffff;\n    padding: 1.25rem 1.35rem;\n    border-radius: 14px;\n    box-shadow:\n        0 14px 30px rgba(15, 23, 42, 0.06),\n        0 0 0 1px rgba(248, 250, 252, 0.9);\n    border: 1px solid #e5e7eb;\n    transition: transform 0.15s, box-shadow 0.15s;\n    text-decoration: none;\n    color: inherit;\n    display: block;\n}\n\n.card:hover {\n    transform: translateY(-3px);\n    box-shadow:\n        0 18px 40px rgba(15, 23, 42, 0.10),\n        0 0 0 1px rgba(59, 130, 246, 0.6);\n}\n\n.card-icon {\n    width: 48px;\n    height: 48px;\n    margin-bottom: 0.75rem;\n}\n\n.card-icon svg {\n    width: 100%;\n    height: 100%;\n}\n\n.card-title {\n    font-weight: 600;\n    font-size: 1.1rem;\n    margin-bottom: 0.25rem;\n    color: #0f172a;\n}\n\n.card-desc {\n    font-size: 0.925rem;\n    color: #6b7280;\n}\n\n.card-meta {\n    margin-top: 0.45rem;\n    font-size: 0.75rem;\n    text-transform: uppercase;\n    letter-spacing: 0.08em;\n    color: #9ca3af;\n}\n\n.item-list {\n    display: flex;\n    flex-direction: column;\n    gap: 1rem;\n}\n\n.item-card {\n    background: #ffffff;\n    padding: 1rem 1.25rem;\n    border-radius: 10px;\n    border-left: 4px solid #6366f1;\n    box-shadow:\n        0 10px 24px rgba(15, 23, 42, 0.06),\n        0 0 0 1px rgba(248, 250, 252, 0.9);\n}\n\n.item-card.skill {\n    border-left-color: #10b981;\n}\n\n.item-card.interaction {\n    border-left-color: #f59e0b;\n}\n\n.item-name {\n    font-weight: 600;\n    font-size: 1.05rem;\n}\n\n.item-desc {\n    font-size: 0.9rem;\n    color: #6b7280;\n    margin-top: 0.25rem;\n}\n\n.item-meta {\n    font-size: 0.8rem;\n    color: #9ca3af;\n    margin-top: 0.5rem;\n}\n\n.item-schema {\n    margin-top: 0.75rem;\n    font-size: 0.8rem;\n    font-family: ui-monospace, monospace;\n    background: #f3f4f6;\n    padding: 0.75rem;\n    border-radius: 6px;\n    overflow-x: auto;\n    white-space: pre-wrap;\n    color: #374151;\n}\n\n.header {\n    display: flex;\n    align-items: center;\n    gap: 1rem;\n    margin-bottom: 1.5rem;\n}\n\n.header-icon {\n    width: 64px;\n    height: 64px;\n}\n\n.header-icon svg {\n    width: 100%;\n    height: 100%;\n}\n\n.section-header {\n    display: flex;\n    align-items: baseline;\n    justify-content: space-between;\n    gap: 1rem;\n    margin-bottom: 0.75rem;\n}\n\n.section-subtitle {\n    font-size: 0.8rem;\n    color: #6b7280;\n}\n\n.endpoint-url {\n    font-size: 0.85rem;\n    color: #6b7280;\n    margin-top: 0.25rem;\n}\n\n.endpoint-url code {\n    background: #f3f4f6;\n    padding: 0.125rem 0.375rem;\n    border-radius: 4px;\n    font-family: ui-monospace, monospace;\n}\n\n.badge {\n    display: inline-block;\n    font-size: 0.75rem;\n    padding: 0.125rem 0.5rem;\n    border-radius: 9999px;\n    background: #f9fafb;\n    color: #374151;\n    border: 1px solid #e5e7eb;\n    margin-right: 0.25rem;\n}\n\n.badge.python { background: #fef3c7; color: #92400e; border-color: #facc15; }\n.badge.typescript { background: #dbeafe; color: #1e40af; border-color: #60a5fa; }\n.badge.javascript { background: #fef9c3; color: #854d0e; border-color: #facc15; }\n\n@media (max-width: 768px) {\n    body {\n        padding: 1.75rem 1.25rem;\n    }\n\n    .hero {\n        flex-direction: column;\n        padding: 1.5rem 1.35rem;\n    }\n\n    .hero-panel {\n        max-width: 100%;\n        width: 100%;\n    }\n}\n\n@media (prefers-color-scheme: dark) {\n    body {\n        background:\n            radial-gradient(circle at 0 0, rgba(56, 189, 248, 0.18), transparent 55%),\n            radial-gradient(circle at 100% 0, rgba(129, 140, 248, 0.25), transparent 55%),\n            #020617;\n        color: #e5e7eb;\n    }\n\n    .hero {\n        background: linear-gradient(135deg, rgba(15, 23, 42, 0.98), rgba(15, 23, 42, 0.92));\n        border: 1px solid rgba(148, 163, 184, 0.45);\n        box-shadow:\n            0 24px 60px rgba(15, 23, 42, 0.85),\n            0 0 0 1px rgba(15, 23, 42, 0.75);\n    }\n\n    .hero-eyebrow {\n        color: #9ca3af;\n    }\n\n    .hero-title {\n        color: #f9fafb;\n    }\n\n    .hero-tagline {\n        color: #cbd5f5;\n    }\n\n    .hero-summary {\n        color: #9ca3af;\n    }\n\n    .hero-summary span {\n        background: rgba(15, 23, 42, 0.95);\n        border-color: rgba(148, 163, 184, 0.45);\n    }\n\n    .hero-panel {\n        background: radial-gradient(circle at 0 0, rgba(56, 189, 248, 0.16), transparent 70%),\n            rgba(15, 23, 42, 0.96);\n        border: 1px solid rgba(59, 130, 246, 0.6);\n        box-shadow: 0 20px 40px rgba(15, 23, 42, 0.85);\n    }\n\n    .hero-panel-label {\n        color: #93c5fd;\n    }\n\n    .hero-panel-endpoint {\n        background: rgba(15, 23, 42, 0.98);\n        border-color: rgba(148, 163, 184, 0.6);\n        color: #e5e7eb;\n    }\n\n    .hero-panel-hint {\n        color: #9ca3af;\n    }\n\n    .hero-panel-hint strong {\n        color: #e5e7eb;\n    }\n\n    .search-input {\n        background: rgba(15, 23, 42, 0.96);\n        border-color: rgba(55, 65, 81, 0.9);\n        color: #e5e7eb;\n        box-shadow:\n            0 6px 16px rgba(15, 23, 42, 0.9),\n            0 0 0 1px rgba(15, 23, 42, 0.9);\n    }\n\n    .search-input::placeholder {\n        color: #6b7280;\n    }\n\n    .search-input:focus {\n        border-color: #60a5fa;\n        box-shadow:\n            0 0 0 1px rgba(59, 130, 246, 0.7),\n            0 10px 26px rgba(30, 64, 175, 0.7);\n    }\n\n    .search-hint,\n    .search-empty {\n        color: #9ca3af;\n    }\n\n    h1, h2 {\n        color: #e5e7eb;\n    }\n\n    h2 {\n        color: #9ca3af;\n    }\n\n    a {\n        color: #60a5fa;\n    }\n\n    hr {\n        border-top-color: rgba(148, 163, 184, 0.4);\n    }\n\n    .card {\n        background: radial-gradient(circle at 0 0, rgba(56, 189, 248, 0.12), transparent 75%),\n            rgba(15, 23, 42, 0.9);\n        box-shadow:\n            0 14px 30px rgba(15, 23, 42, 0.8),\n            0 0 0 1px rgba(15, 23, 42, 0.85);\n        border-color: rgba(148, 163, 184, 0.5);\n    }\n\n    .card:hover {\n        box-shadow:\n            0 18px 40px rgba(15, 23, 42, 0.9),\n            0 0 0 1px rgba(59, 130, 246, 0.8);\n    }\n\n    .card-title {\n        color: #e5e7eb;\n    }\n\n    .card-desc {\n        color: #9ca3af;\n    }\n\n    .card-meta {\n        color: #6b7280;\n    }\n\n    .item-card {\n        background: rgba(15, 23, 42, 0.9);\n        box-shadow:\n            0 10px 24px rgba(15, 23, 42, 0.9),\n            0 0 0 1px rgba(15, 23, 42, 0.9);\n    }\n\n    .item-desc,\n    .item-meta {\n        color: #9ca3af;\n    }\n\n    .item-schema {\n        background: rgba(15, 23, 42, 0.95);\n        color: #e5e7eb;\n    }\n\n    .endpoint-url {\n        color: #9ca3af;\n    }\n\n    .endpoint-url code {\n        background: rgba(15, 23, 42, 0.95);\n    }\n\n    .badge {\n        background: rgba(15, 23, 42, 0.96);\n        color: #e5e7eb;\n        border-color: rgba(148, 163, 184, 0.6);\n    }\n\n    .badge.python {\n        background: rgba(252, 211, 77, 0.12);\n        color: #facc15;\n        border-color: rgba(250, 204, 21, 0.5);\n    }\n\n    .badge.typescript {\n        background: rgba(59, 130, 246, 0.12);\n        color: #93c5fd;\n        border-color: rgba(59, 130, 246, 0.7);\n    }\n\n    .badge.javascript {\n        background: rgba(251, 191, 36, 0.12);\n        color: #fbbf24;\n        border-color: rgba(251, 191, 36, 0.55);\n    }\n\n    .logo-light {\n        display: none;\n    }\n    .logo-dark {\n        display: block;\n    }\n}\n";
+//# sourceMappingURL=styles.d.ts.map

package/lib/types/site/styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../../../src/site/styles.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,UAAU,uuYAqmBtB,CAAC"}

package/lib/types/site/templates.d.ts

@@ -0,0 +1,54 @@
+import type { InteractionCollection } from "../InteractionCollection.js";
+import type { SkillCollection } from "../SkillCollection.js";
+import type { ToolCollection } from "../ToolCollection.js";
+import type { ICollection, SkillDefinition, Tool } from "../types.js";
+type MCPProviderMeta = {
+    name: string;
+    description?: string;
+};
+/**
+ * Render a collection card for the index page
+ */
+export declare function collectionCard(collection: ICollection, pathPrefix: string, meta?: string): string;
+/**
+ * Render a tool card (simple version for lists)
+ */
+export declare function toolCard(tool: Tool<Record<string, unknown>>): string;
+/**
+ * Render an MCP provider card
+ */
+export declare function mcpProviderCard(provider: MCPProviderMeta): string;
+/**
+ * Render a detailed tool card
+ */
+export declare function toolDetailCard(tool: Tool<Record<string, unknown>>, collectionName: string): string;
+/**
+ * Render a skill card (simple version for lists)
+ */
+export declare function skillCard(skill: SkillDefinition): string;
+/**
+ * Render a detailed skill card
+ */
+export declare function skillDetailCard(skill: SkillDefinition, collection: SkillCollection): string;
+/**
+ * Render the main index page
+ *
+ * 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.
+ */
+export declare function indexPage(tools: ToolCollection[], skills: SkillCollection[], interactions: InteractionCollection[], mcpProvidersOrTitle?: MCPProviderMeta[] | string, titleParam?: string): string;
+/**
+ * Render a tool collection detail page
+ */
+export declare function toolCollectionPage(collection: ToolCollection): string;
+/**
+ * Render a skill collection detail page
+ */
+export declare function skillCollectionPage(collection: SkillCollection): string;
+/**
+ * Render an interaction collection detail page
+ */
+export declare function interactionCollectionPage(collection: InteractionCollection): string;
+export {};
+//# sourceMappingURL=templates.d.ts.map

package/lib/types/site/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/site/templates.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAItE,KAAK,eAAe,GAAG;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAiZF;;GAEG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAQjG;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,MAAM,CASpE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAMjE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CA0DlG;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAWxD;AAsBD;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,eAAe,GAAG,MAAM,CAsF3F;AA2BD;;;;;;GAMG;AACH,wBAAgB,SAAS,CACrB,KAAK,EAAE,cAAc,EAAE,EACvB,MAAM,EAAE,eAAe,EAAE,EACzB,YAAY,EAAE,qBAAqB,EAAE,EACrC,mBAAmB,CAAC,EAAE,eAAe,EAAE,GAAG,MAAM,EAChD,UAAU,CAAC,EAAE,MAAM,GACpB,MAAM,CAiLR;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,cAAc,GAAG,MAAM,CAsCrE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,eAAe,GAAG,MAAM,CAsCvE;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,qBAAqB,GAAG,MAAM,CAgDnF"}

package/lib/types/types.d.ts

@@ -0,0 +1,280 @@
+import type { ToolDefinition, ToolUse } from "@llumiverse/common";
+import { VertesiaClient } from "@vertesia/client";
+import { AuthTokenPayload, ToolExecutionMetadata, ToolResult, ToolResultContent } from "@vertesia/common";
+export type { ToolExecutionMetadata };
+export type ICollection<T = any> = CollectionProperties & Iterable<T>;
+export interface CollectionProperties {
+    /**
+     * 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.
+     * Example: my-collection
+     */
+    name: string;
+    /**
+     * Optional title for UI display.
+     * If not provided the pascal case version of the name will be used
+     */
+    title?: string;
+    /**
+     * Optional icon for UI display
+     */
+    icon?: string;
+    /**
+     * A short description
+     */
+    description?: string;
+}
+export interface ToolExecutionContext {
+    /**
+     * The raw JWT token to the tool execution request
+     */
+    token: string;
+    /**
+     * The decoded JWT token
+     */
+    payload: AuthTokenPayload;
+    /**
+     * Vertesia client factory using the current auth token.
+     * @returns a vertesia client instance
+     */
+    getClient: () => Promise<VertesiaClient>;
+}
+export interface ToolExecutionResult extends ToolResultContent {
+    /**
+     * Medata can be used to return more info on the tool execution like stats or user messages.
+     */
+    meta?: Record<string, any>;
+}
+export interface ToolExecutionResponse extends ToolExecutionResult, ToolResult {
+    /**
+     * The tool use id of the tool use request. For traceability.
+     */
+    tool_use_id: string;
+}
+export interface ToolExecutionResponseError {
+    /**
+     * The tool use id of the tool use request. For traceability.
+     */
+    tool_use_id: string;
+    /**
+     * The http status code
+     */
+    status: number;
+    /**
+     * the error message
+     */
+    error: string;
+    /**
+     * Additional context information
+     */
+    data?: Record<string, any>;
+}
+export interface ToolExecutionPayload<ParamsT extends Record<string, any>> {
+    tool_use: ToolUse<ParamsT>;
+    /**
+     * Optional metadata related to the current execution request
+     */
+    metadata?: ToolExecutionMetadata;
+}
+export type ToolFn<ParamsT extends Record<string, any>> = (payload: ToolExecutionPayload<ParamsT>, context: ToolExecutionContext) => Promise<ToolExecutionResult>;
+export interface Tool<ParamsT extends Record<string, any>> extends ToolDefinition {
+    run: ToolFn<ParamsT>;
+    /**
+     * Whether this tool is available by default.
+     * - true/undefined: Tool is always available to agents
+     * - false: Tool is only available when activated by a skill's related_tools
+     */
+    default?: boolean;
+}
+/**
+ * Tool definition with optional activation control for agent exposure.
+ */
+export interface ToolDefinitionWithDefault extends ToolDefinition {
+    /**
+     * Whether this tool is available by default.
+     * - true/undefined: Tool is always available to agents
+     * - false: Tool is only available when activated by a skill's related_tools
+     */
+    default?: boolean;
+    /**
+     * For skill tools (learn_*): list of related tool names that become available
+     * when this skill is called. Used for dynamic tool discovery.
+     */
+    related_tools?: string[];
+}
+/**
+ * The interface that should be returned when requesting a collection endpoint using a GET
+ */
+export interface ToolCollectionDefinition {
+    title: string;
+    description: string;
+    src: string;
+    tools: ToolDefinitionWithDefault[];
+}
+export type { ToolDefinition };
+/**
+ * The details of a connection to a MCP server - including the server URL and an authentication token
+ */
+export interface MCPConnectionDetails {
+    /**
+     * The mcp server name. It will be used to prefix tool names.
+     */
+    name: string;
+    /**
+     * The target mcp server URL
+     */
+    url: string;
+    /**
+     * The bearer authentication token to use when connecting to the mcp server.
+     * If an empty string no authentication will be done
+     */
+    token: string;
+}
+/**
+ * Content type for skill instructions
+ */
+export type SkillContentType = 'md' | 'jst';
+/**
+ * Context triggers for auto-injection of skills
+ */
+export interface SkillContextTriggers {
+    /**
+     * Keywords in user input that should trigger this skill
+     */
+    keywords?: string[];
+    /**
+     * If these tools are being used, suggest this skill
+     */
+    tool_names?: string[];
+    /**
+     * Regex patterns to match against input data
+     */
+    data_patterns?: string[];
+}
+/**
+ * Execution configuration for skills that need code execution
+ */
+export interface SkillExecution {
+    /**
+     * The programming language for execution
+     */
+    language: string;
+    /**
+     * Required packages to install
+     */
+    packages?: string[];
+    /**
+     * System-level packages to install (e.g., apt-get packages)
+     */
+    system_packages?: string[];
+    /**
+     * Code template to execute
+     */
+    template?: string;
+}
+/**
+ * Skill definition - parsed from SKILL.md or SKILL.jst
+ */
+export interface SkillDefinition {
+    /**
+     * Unique skill name (kebab-case)
+     */
+    name: string;
+    /**
+     * Display title
+     */
+    title?: string;
+    /**
+     * Short description for discovery
+     */
+    description: string;
+    /**
+     * The skill instructions (markdown or JST template)
+     */
+    instructions: string;
+    /**
+     * Content type: 'md' for static markdown, 'jst' for dynamic templates
+     */
+    content_type: SkillContentType;
+    /**
+     * JSON Schema for skill input parameters.
+     * Used when skill is exposed as a tool.
+     */
+    input_schema?: {
+        type: 'object';
+        properties?: Record<string, any>;
+        required?: string[];
+    };
+    /**
+     * Context triggers for auto-injection
+     */
+    context_triggers?: SkillContextTriggers;
+    /**
+     * Execution configuration for code-based skills
+     */
+    execution?: SkillExecution;
+    /**
+     * Related tools that work well with this skill
+     */
+    related_tools?: string[];
+    /**
+     * Scripts bundled with this skill (synced to sandbox when skill is used)
+     */
+    scripts?: string[];
+    /**
+     * The name of the widgets provided by this skill (if any)
+     * The name will be used to load the widget dynamically from the agent chat
+     * and must match the code block language returned by the LLM (e.g., ```my-widget)
+     * which will be rendered using the widget.
+     * The widget file must be located in the skill directory under the name {{widget-name}}.tsx.
+     */
+    widgets?: string[];
+}
+/**
+ * Skill execution payload
+ */
+export interface SkillExecutionPayload {
+    /**
+     * The skill name to execute
+     */
+    skill_name: string;
+    /**
+     * Data context for JST template rendering
+     */
+    data?: Record<string, any>;
+    /**
+     * Whether to execute the code template (if present)
+     */
+    execute?: boolean;
+}
+/**
+ * Skill execution result
+ */
+export interface SkillExecutionResult {
+    /**
+     * The skill name
+     */
+    name: string;
+    /**
+     * Rendered instructions
+     */
+    instructions: string;
+    /**
+     * Execution output (if execute=true and skill has code template)
+     */
+    execution_result?: {
+        output: string;
+        files?: string[];
+        is_error: boolean;
+    };
+}
+/**
+ * Skill collection definition - returned by GET endpoint
+ */
+export interface SkillCollectionDefinition {
+    name: string;
+    title: string;
+    description: string;
+    skills: SkillDefinition[];
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.d.ts.map

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

package/lib/types/utils.d.ts

@@ -0,0 +1,4 @@
+export declare function kebabCaseToTitle(name: string): string;
+export declare function makeScriptUrl(origin: string, script: string): string;
+export declare function join(left: string, right: string): string;
+//# sourceMappingURL=utils.d.ts.map

package/lib/types/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,UAE5C;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,UAE3D;AAED,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,UAc/C"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@vertesia/tools-sdk",
+  "version": "0.24.0-dev.202601221707",
+  "description": "Tools SDK - utilities for building remote tools",
+  "type": "module",
+  "types": "./lib/types/index.d.ts",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "license": "Apache-2.0",
+  "exports": {
+    "types": "./lib/types/index.d.ts",
+    "import": "./lib/esm/index.js",
+    "require": "./lib/cjs/index.js"
+  },
+  "bin": {
+    "tools-sdk-copy-assets": "./lib/esm/copy-assets.js"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.2",
+    "ts-dual-module": "^0.6.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "ts_dual_module": {
+    "outDir": "lib"
+  },
+  "peerDependencies": {
+    "hono": "^4.11.4"
+  },
+  "dependencies": {
+    "jose": "^6.0.11",
+    "zod": "^4.3.5",
+    "@llumiverse/common": "0.24.0-dev.202601221707",
+    "@vertesia/common": "0.24.0-dev.202601221707",
+    "@vertesia/client": "0.24.0-dev.202601221707"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vertesia/composableai.git",
+    "directory": "packages/tools-sdk"
+  },
+  "keywords": [
+    "vertesia",
+    "tools",
+    "sdk",
+    "llm",
+    "ai",
+    "agents",
+    "typescript"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "build": "pnpm exec tsmod build",
+    "clean": "rimraf ./node_modules ./lib ./tsconfig.tsbuildinfo"
+  }
+}

package/src/InteractionCollection.ts

@@ -0,0 +1,143 @@
+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";
+
+export interface InteractionCollectionProps extends CollectionProperties {
+    interactions: InteractionSpec[];
+}
+export class InteractionCollection implements ICollection<InteractionSpec> {
+    interactions: InteractionSpec[];
+    name: string;
+    title?: string;
+    icon?: string;
+    description?: string;
+    constructor({
+        name, title, icon, description, interactions
+    }: InteractionCollectionProps) {
+        this.name = name;
+        this.title = title || kebabCaseToTitle(name);
+        this.icon = icon;
+        this.description = description;
+        this.interactions = interactions;
+    }
+    addInteraction(interaction: any) {
+        this.interactions.push(interaction);
+    }
+
+    getInteractions() {
+        return this.interactions;
+    }
+
+    [Symbol.iterator](): Iterator<InteractionSpec> {
+        let index = 0;
+        const interactions = this.interactions;
+
+        return {
+            next(): IteratorResult<InteractionSpec> {
+                if (index < interactions.length) {
+                    return { value: interactions[index++], done: false };
+                } else {
+                    return { done: true, value: undefined };
+                }
+            }
+        };
+    }
+
+    map<U>(callback: (interaction: InteractionSpec, index: number) => U): U[] {
+        return this.interactions.map(callback);
+    }
+
+    getInteractionByName(name: string): InteractionSpec | undefined {
+        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');
+}