@vertesia/tools-sdk 0.74.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2024 Composable
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/lib/cjs/ToolCollection.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolCollection = void 0;
+const http_exception_1 = require("hono/http-exception");
+const auth_js_1 = require("./auth.js");
+const ToolRegistry_js_1 = require("./ToolRegistry.js");
+/**
+ * Implements a tools colection endpoint
+ */
+class ToolCollection {
+    /**
+     * 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;
+    /**
+     * Optional title for UI display.
+     * If not provided the title will be generated form the kebab case name by replacing - with spaces and upper casing first letter in words.
+     */
+    title;
+    /**
+     * Optional icon for UI display
+     */
+    icon;
+    /**
+     * A short description
+     */
+    description;
+    /**
+     * The tool registry
+     */
+    tools;
+    constructor({ name, title, icon, description, tools }) {
+        this.name = name;
+        this.title = title || kebabCaseToTitle(name);
+        this.icon = icon;
+        this.description = description;
+        this.tools = new ToolRegistry_js_1.ToolRegistry(tools);
+    }
+    [Symbol.iterator]() {
+        let index = 0;
+        const tools = this.tools.getTools();
+        return {
+            next() {
+                if (index < tools.length) {
+                    return { value: tools[index++], done: false };
+                }
+                else {
+                    return { done: true, value: undefined };
+                }
+            }
+        };
+    }
+    map(callback) {
+        return this.tools.getTools().map(callback);
+    }
+    async execute(ctx) {
+        let payload;
+        try {
+            payload = await readPayload(ctx);
+            const session = await (0, auth_js_1.authorize)(ctx);
+            const r = await this.tools.runTool(payload, session);
+            return ctx.json({
+                ...r,
+                tool_use_id: payload.tool_use.id
+            });
+        }
+        catch (err) { // HTTPException ?
+            const status = err.status || 500;
+            return ctx.json({
+                tool_use_id: payload?.tool_use.id || "undefined",
+                error: err.message || "Error executing tool",
+                status
+            }, status);
+        }
+    }
+    getToolDefinitions() {
+        return this.tools.getDefinitions();
+    }
+}
+exports.ToolCollection = ToolCollection;
+async function readPayload(ctx) {
+    try {
+        return await ctx.req.json();
+    }
+    catch (err) {
+        throw new http_exception_1.HTTPException(500, {
+            message: "Failed to load execution request payload: " + err.message
+        });
+    }
+}
+function kebabCaseToTitle(name) {
+    return name.split('-').map(p => p[0].toUpperCase() + p.substring(1)).join(' ');
+}
+//# sourceMappingURL=ToolCollection.js.map

package/lib/cjs/ToolCollection.js.map

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

package/lib/cjs/ToolRegistry.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolNotFoundError = exports.ToolRegistry = void 0;
+const http_exception_1 = require("hono/http-exception");
+class ToolRegistry {
+    registry = {};
+    constructor(tools = []) {
+        for (const tool of tools) {
+            this.registry[tool.name] = tool;
+        }
+    }
+    getDefinitions() {
+        return Object.values(this.registry).map(tool => ({
+            name: tool.name,
+            description: tool.description,
+            input_schema: tool.input_schema
+        }));
+    }
+    getTool(name) {
+        const tool = this.registry[name];
+        if (tool === undefined) {
+            throw new ToolNotFoundError(name);
+        }
+        return tool;
+    }
+    getTools() {
+        return Object.values(this.registry);
+    }
+    registerTool(tool) {
+        this.registry[tool.name] = tool;
+    }
+    runTool(payload, context) {
+        return this.getTool(payload.tool_use.tool_name).run(payload, context);
+    }
+}
+exports.ToolRegistry = ToolRegistry;
+class ToolNotFoundError extends http_exception_1.HTTPException {
+    constructor(name) {
+        super(404, { message: "Tool function not found: " + name });
+        this.name = "ToolNotFoundError";
+    }
+}
+exports.ToolNotFoundError = ToolNotFoundError;
+//# sourceMappingURL=ToolRegistry.js.map

package/lib/cjs/ToolRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolRegistry.js","sourceRoot":"","sources":["../../src/ToolRegistry.ts"],"names":[],"mappings":";;;AAAA,wDAAoD;AAEpD,MAAa,YAAY;IAErB,QAAQ,GAA8B,EAAE,CAAC;IAEzC,YAAY,QAAqB,EAAE;QAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACvB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QACpC,CAAC;IACL,CAAC;IAED,cAAc;QACV,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC7C,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,YAAY,EAAE,IAAI,CAAC,YAAY;SAClC,CAAC,CAAC,CAAC;IACR,CAAC;IAED,OAAO,CAAsC,IAAY;QACrD,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;QAChC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACrB,MAAM,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,QAAQ;QACJ,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED,YAAY,CAAsC,IAAmB;QACjE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpC,CAAC;IAED,OAAO,CAAsC,OAAsC,EAAE,OAA6B;QAC9G,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1E,CAAC;CAEJ;AAtCD,oCAsCC;AAGD,MAAa,iBAAkB,SAAQ,8BAAa;IAChD,YAAY,IAAY;QACpB,KAAK,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,2BAA2B,GAAG,IAAI,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IACpC,CAAC;CACJ;AALD,8CAKC"}

package/lib/cjs/auth.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthSession = void 0;
+exports.getJwks = getJwks;
+exports.verifyToken = verifyToken;
+exports.authorize = authorize;
+const client_1 = require("@vertesia/client");
+const http_exception_1 = require("hono/http-exception");
+const jose_1 = require("jose");
+const cache = {};
+async function getJwks(url) {
+    if (!cache.url) {
+        console.log('JWKS cache miss for: ', url);
+        const jwks = await fetch(url).then(r => {
+            if (r.ok) {
+                return r.json();
+            }
+            throw new Error("Fetching jwks failed with code: " + r.status);
+        }).catch(err => {
+            throw new Error("Failed to fetch jwks: " + err.message);
+        });
+        cache.url = (0, jose_1.createLocalJWKSet)(jwks);
+    }
+    return cache.url;
+}
+async function verifyToken(token) {
+    const decodedJwt = (0, jose_1.decodeJwt)(token);
+    const { studio } = (0, client_1.decodeEndpoints)(decodedJwt.endpoints);
+    if (!studio) {
+        throw new Error("No studio endpoint found in JWT");
+    }
+    const jwks = await getJwks(`${studio}/.well-known/jwks`);
+    return await (0, jose_1.jwtVerify)(token, jwks);
+}
+async function authorize(ctx) {
+    const auth = ctx.req.header('Authorization');
+    if (!auth) {
+        throw new http_exception_1.HTTPException(401, {
+            message: `Missing Authorization header'`
+        });
+    }
+    const [scheme, value] = auth.trim().split(' ');
+    if (scheme.toLowerCase() !== 'bearer') {
+        throw new http_exception_1.HTTPException(401, {
+            message: `Authorization scheme ${scheme} is not supported`
+        });
+    }
+    if (!value) {
+        throw new http_exception_1.HTTPException(401, {
+            message: `Missing bearer token value`
+        });
+    }
+    try {
+        const { payload } = await verifyToken(value);
+        const session = new AuthSession(value, payload);
+        ctx.set("auth", session);
+        return session;
+    }
+    catch (err) {
+        throw new http_exception_1.HTTPException(401, {
+            message: err.message,
+            cause: err
+        });
+    }
+}
+class AuthSession {
+    token;
+    payload;
+    _client;
+    endpoints;
+    constructor(token, payload) {
+        this.token = token;
+        this.payload = payload;
+        this.endpoints = (0, client_1.decodeEndpoints)(payload.endpoints);
+    }
+    async getClient() {
+        if (!this._client) {
+            this._client = await client_1.VertesiaClient.fromAuthToken(this.token, this.payload);
+        }
+        return this._client;
+    }
+}
+exports.AuthSession = AuthSession;
+//# sourceMappingURL=auth.js.map

package/lib/cjs/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/auth.ts"],"names":[],"mappings":";;;AAQA,0BAcC;AAED,kCAQC;AAID,8BA6BC;AAjED,6CAAmE;AAGnE,wDAAoD;AACpD,+BAA+F;AAE/F,MAAM,KAAK,GAAoC,EAAE,CAAC;AAE3C,KAAK,UAAU,OAAO,CAAC,GAAW;IACrC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,GAAG,CAAC,uBAAuB,EAAE,GAAG,CAAC,CAAC;QAC1C,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;YACnC,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC;gBACP,OAAO,CAAC,CAAC,IAAI,EAA4B,CAAC;YAC9C,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,kCAAkC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;QACnE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;YACX,MAAM,IAAI,KAAK,CAAC,wBAAwB,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;QAC5D,CAAC,CAAC,CAAA;QACF,KAAK,CAAC,GAAG,GAAG,IAAA,wBAAiB,EAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC;AACrB,CAAC;AAEM,KAAK,UAAU,WAAW,CAAC,KAAa;IAC3C,MAAM,UAAU,GAAG,IAAA,gBAAS,EAAC,KAAK,CAAC,CAAC;IACpC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAA,wBAAe,EAAC,UAAU,CAAC,SAAgB,CAAC,CAAC;IAChE,IAAI,CAAC,MAAM,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACvD,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,MAAM,mBAAmB,CAAC,CAAC;IACzD,OAAO,MAAM,IAAA,gBAAS,EAAmB,KAAK,EAAE,IAAI,CAAC,CAAC;AAC1D,CAAC;AAIM,KAAK,UAAU,SAAS,CAAC,GAAY;IACxC,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IAC7C,IAAI,CAAC,IAAI,EAAE,CAAC;QACR,MAAM,IAAI,8BAAa,CAAC,GAAG,EAAE;YACzB,OAAO,EAAE,+BAA+B;SAC3C,CAAC,CAAC;IACP,CAAC;IACD,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/C,IAAI,MAAM,CAAC,WAAW,EAAE,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,8BAAa,CAAC,GAAG,EAAE;YACzB,OAAO,EAAE,wBAAwB,MAAM,mBAAmB;SAC7D,CAAC,CAAC;IACP,CAAC;IACD,IAAI,CAAC,KAAK,EAAE,CAAC;QACT,MAAM,IAAI,8BAAa,CAAC,GAAG,EAAE;YACzB,OAAO,EAAE,4BAA4B;SACxC,CAAC,CAAC;IACP,CAAC;IACD,IAAI,CAAC;QACD,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,WAAW,CAAC,KAAK,CAAC,CAAC;QAC7C,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAChD,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACzB,OAAO,OAAO,CAAC;IACnB,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAChB,MAAM,IAAI,8BAAa,CAAC,GAAG,EAAE;YACzB,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,KAAK,EAAE,GAAG;SACb,CAAC,CAAC;IACP,CAAC;AACL,CAAC;AAED,MAAa,WAAW;IAOD;IAAsB;IANzC,OAAO,CAA6B;IACpC,SAAS,CAGP;IAEF,YAAmB,KAAa,EAAS,OAAyB;QAA/C,UAAK,GAAL,KAAK,CAAQ;QAAS,YAAO,GAAP,OAAO,CAAkB;QAC9D,IAAI,CAAC,SAAS,GAAG,IAAA,wBAAe,EAAC,OAAO,CAAC,SAAS,CAEjD,CAAC;IACN,CAAC;IAED,KAAK,CAAC,SAAS;QACX,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAChB,IAAI,CAAC,OAAO,GAAG,MAAM,uBAAc,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAChF,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;CACJ;AAnBD,kCAmBC"}

package/lib/cjs/build/validate.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validate = validate;
+function validate() {
+    //TODO
+}
+//# sourceMappingURL=validate.js.map

package/lib/cjs/build/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../src/build/validate.ts"],"names":[],"mappings":";;AAAA,4BAEC;AAFD,SAAgB,QAAQ;IACpB,MAAM;AACV,CAAC"}

package/lib/cjs/index.js

@@ -0,0 +1,20 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ToolCollection.js"), exports);
+__exportStar(require("./ToolRegistry.js"), exports);
+__exportStar(require("./types.js"), exports);
+//# sourceMappingURL=index.js.map

package/lib/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,sDAAoC;AACpC,oDAAkC;AAClC,6CAA2B"}

package/lib/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/lib/cjs/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/lib/cjs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/lib/esm/ToolCollection.js

@@ -0,0 +1,92 @@
+import { HTTPException } from "hono/http-exception";
+import { authorize } from "./auth.js";
+import { ToolRegistry } from "./ToolRegistry.js";
+/**
+ * Implements a tools colection endpoint
+ */
+export class ToolCollection {
+    /**
+     * 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;
+    /**
+     * Optional title for UI display.
+     * If not provided the title will be generated form the kebab case name by replacing - with spaces and upper casing first letter in words.
+     */
+    title;
+    /**
+     * Optional icon for UI display
+     */
+    icon;
+    /**
+     * A short description
+     */
+    description;
+    /**
+     * The tool registry
+     */
+    tools;
+    constructor({ name, title, icon, description, tools }) {
+        this.name = name;
+        this.title = title || kebabCaseToTitle(name);
+        this.icon = icon;
+        this.description = description;
+        this.tools = new ToolRegistry(tools);
+    }
+    [Symbol.iterator]() {
+        let index = 0;
+        const tools = this.tools.getTools();
+        return {
+            next() {
+                if (index < tools.length) {
+                    return { value: tools[index++], done: false };
+                }
+                else {
+                    return { done: true, value: undefined };
+                }
+            }
+        };
+    }
+    map(callback) {
+        return this.tools.getTools().map(callback);
+    }
+    async execute(ctx) {
+        let payload;
+        try {
+            payload = await readPayload(ctx);
+            const session = await authorize(ctx);
+            const r = await this.tools.runTool(payload, session);
+            return ctx.json({
+                ...r,
+                tool_use_id: payload.tool_use.id
+            });
+        }
+        catch (err) { // HTTPException ?
+            const status = err.status || 500;
+            return ctx.json({
+                tool_use_id: payload?.tool_use.id || "undefined",
+                error: err.message || "Error executing tool",
+                status
+            }, status);
+        }
+    }
+    getToolDefinitions() {
+        return this.tools.getDefinitions();
+    }
+}
+async function readPayload(ctx) {
+    try {
+        return await ctx.req.json();
+    }
+    catch (err) {
+        throw new HTTPException(500, {
+            message: "Failed to load execution request payload: " + err.message
+        });
+    }
+}
+function kebabCaseToTitle(name) {
+    return name.split('-').map(p => p[0].toUpperCase() + p.substring(1)).join(' ');
+}
+//# sourceMappingURL=ToolCollection.js.map

package/lib/esm/ToolCollection.js.map

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

package/lib/esm/ToolRegistry.js

@@ -0,0 +1,39 @@
+import { HTTPException } from "hono/http-exception";
+export class ToolRegistry {
+    registry = {};
+    constructor(tools = []) {
+        for (const tool of tools) {
+            this.registry[tool.name] = tool;
+        }
+    }
+    getDefinitions() {
+        return Object.values(this.registry).map(tool => ({
+            name: tool.name,
+            description: tool.description,
+            input_schema: tool.input_schema
+        }));
+    }
+    getTool(name) {
+        const tool = this.registry[name];
+        if (tool === undefined) {
+            throw new ToolNotFoundError(name);
+        }
+        return tool;
+    }
+    getTools() {
+        return Object.values(this.registry);
+    }
+    registerTool(tool) {
+        this.registry[tool.name] = tool;
+    }
+    runTool(payload, context) {
+        return this.getTool(payload.tool_use.tool_name).run(payload, context);
+    }
+}
+export class ToolNotFoundError extends HTTPException {
+    constructor(name) {
+        super(404, { message: "Tool function not found: " + name });
+        this.name = "ToolNotFoundError";
+    }
+}
+//# sourceMappingURL=ToolRegistry.js.map

package/lib/esm/ToolRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolRegistry.js","sourceRoot":"","sources":["../../src/ToolRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,MAAM,OAAO,YAAY;IAErB,QAAQ,GAA8B,EAAE,CAAC;IAEzC,YAAY,QAAqB,EAAE;QAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACvB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QACpC,CAAC;IACL,CAAC;IAED,cAAc;QACV,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC7C,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,YAAY,EAAE,IAAI,CAAC,YAAY;SAClC,CAAC,CAAC,CAAC;IACR,CAAC;IAED,OAAO,CAAsC,IAAY;QACrD,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;QAChC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACrB,MAAM,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,QAAQ;QACJ,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED,YAAY,CAAsC,IAAmB;QACjE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpC,CAAC;IAED,OAAO,CAAsC,OAAsC,EAAE,OAA6B;QAC9G,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1E,CAAC;CAEJ;AAGD,MAAM,OAAO,iBAAkB,SAAQ,aAAa;IAChD,YAAY,IAAY;QACpB,KAAK,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,2BAA2B,GAAG,IAAI,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IACpC,CAAC;CACJ"}

package/lib/esm/auth.js

@@ -0,0 +1,77 @@
+import { decodeEndpoints, VertesiaClient } from "@vertesia/client";
+import { HTTPException } from "hono/http-exception";
+import { createLocalJWKSet, decodeJwt, jwtVerify } from "jose";
+const cache = {};
+export async function getJwks(url) {
+    if (!cache.url) {
+        console.log('JWKS cache miss for: ', url);
+        const jwks = await fetch(url).then(r => {
+            if (r.ok) {
+                return r.json();
+            }
+            throw new Error("Fetching jwks failed with code: " + r.status);
+        }).catch(err => {
+            throw new Error("Failed to fetch jwks: " + err.message);
+        });
+        cache.url = createLocalJWKSet(jwks);
+    }
+    return cache.url;
+}
+export async function verifyToken(token) {
+    const decodedJwt = decodeJwt(token);
+    const { studio } = decodeEndpoints(decodedJwt.endpoints);
+    if (!studio) {
+        throw new Error("No studio endpoint found in JWT");
+    }
+    const jwks = await getJwks(`${studio}/.well-known/jwks`);
+    return await jwtVerify(token, jwks);
+}
+export async function authorize(ctx) {
+    const auth = ctx.req.header('Authorization');
+    if (!auth) {
+        throw new HTTPException(401, {
+            message: `Missing Authorization header'`
+        });
+    }
+    const [scheme, value] = auth.trim().split(' ');
+    if (scheme.toLowerCase() !== 'bearer') {
+        throw new HTTPException(401, {
+            message: `Authorization scheme ${scheme} is not supported`
+        });
+    }
+    if (!value) {
+        throw new HTTPException(401, {
+            message: `Missing bearer token value`
+        });
+    }
+    try {
+        const { payload } = await verifyToken(value);
+        const session = new AuthSession(value, payload);
+        ctx.set("auth", session);
+        return session;
+    }
+    catch (err) {
+        throw new HTTPException(401, {
+            message: err.message,
+            cause: err
+        });
+    }
+}
+export class AuthSession {
+    token;
+    payload;
+    _client;
+    endpoints;
+    constructor(token, payload) {
+        this.token = token;
+        this.payload = payload;
+        this.endpoints = decodeEndpoints(payload.endpoints);
+    }
+    async getClient() {
+        if (!this._client) {
+            this._client = await VertesiaClient.fromAuthToken(this.token, this.payload);
+        }
+        return this._client;
+    }
+}
+//# sourceMappingURL=auth.js.map

package/lib/esm/auth.js.map

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

package/lib/esm/build/validate.js

@@ -0,0 +1,4 @@
+export function validate() {
+    //TODO
+}
+//# sourceMappingURL=validate.js.map

package/lib/esm/build/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../src/build/validate.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,QAAQ;IACpB,MAAM;AACV,CAAC"}

package/lib/esm/index.js

@@ -0,0 +1,4 @@
+export * from "./ToolCollection.js";
+export * from "./ToolRegistry.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/lib/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}

package/lib/esm/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/lib/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/lib/types/ToolCollection.d.ts

@@ -0,0 +1,73 @@
+import { Context } from "hono";
+import { ToolRegistry } from "./ToolRegistry.js";
+import type { Tool, ToolDefinition } from "./types.js";
+export interface ToolCollectionProperties {
+    /**
+     * 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;
+    /**
+     * The tools
+     */
+    tools: Tool<any>[];
+}
+/**
+ * Implements a tools colection endpoint
+ */
+export declare class ToolCollection implements Iterable<Tool<any>> {
+    /**
+     * 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 title will be generated form the kebab case name by replacing - with spaces and upper casing first letter in words.
+     */
+    title?: string;
+    /**
+     * Optional icon for UI display
+     */
+    icon?: string;
+    /**
+     * A short description
+     */
+    description: string;
+    /**
+     * The tool registry
+     */
+    tools: ToolRegistry;
+    constructor({ name, title, icon, description, tools }: ToolCollectionProperties);
+    [Symbol.iterator](): Iterator<Tool<any>>;
+    map<U>(callback: (tool: Tool<any>, index: number) => U): U[];
+    execute(ctx: Context): Promise<(Response & import("hono").TypedResponse<{
+        tool_use_id: string;
+        metadata?: {
+            [x: string]: any;
+        } | undefined;
+        content: string;
+        files?: string[] | undefined;
+    }, import("hono/utils/http-status").ContentfulStatusCode, "json">) | (Response & import("hono").TypedResponse<{
+        tool_use_id: string;
+        error: any;
+        status: any;
+    }, any, "json">)>;
+    getToolDefinitions(): ToolDefinition[];
+}
+//# sourceMappingURL=ToolCollection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ToolCollection.d.ts","sourceRoot":"","sources":["../../src/ToolCollection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAG/B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,IAAI,EAAE,cAAc,EAA2E,MAAM,YAAY,CAAC;AAEhI,MAAM,WAAW,wBAAwB;IACrC;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,cAAe,YAAW,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEtD;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,KAAK,EAAE,YAAY,CAAC;gBAER,EACR,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EACxC,EAAE,wBAAwB;IAQ3B,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAexC,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,CAAC,GAAG,CAAC,EAAE;IAItD,OAAO,CAAC,GAAG,EAAE,OAAO;;;;;;;;;;;;IAoB1B,kBAAkB,IAAI,cAAc,EAAE;CAIzC"}

package/lib/types/ToolRegistry.d.ts

@@ -0,0 +1,15 @@
+import { HTTPException } from "hono/http-exception";
+import { Tool, ToolDefinition, ToolExecutionContext, ToolExecutionPayload, ToolExecutionResult } from "./types.js";
+export declare class ToolRegistry {
+    registry: Record<string, Tool<any>>;
+    constructor(tools?: Tool<any>[]);
+    getDefinitions(): ToolDefinition[];
+    getTool<ParamsT extends Record<string, any>>(name: string): Tool<ParamsT>;
+    getTools(): Tool<any>[];
+    registerTool<ParamsT extends Record<string, any>>(tool: Tool<ParamsT>): void;
+    runTool<ParamsT extends Record<string, any>>(payload: ToolExecutionPayload<ParamsT>, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+}
+export declare class ToolNotFoundError extends HTTPException {
+    constructor(name: string);
+}
+//# sourceMappingURL=ToolRegistry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ToolRegistry.d.ts","sourceRoot":"","sources":["../../src/ToolRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACnH,qBAAa,YAAY;IAErB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAM;gBAE7B,KAAK,GAAE,IAAI,CAAC,GAAG,CAAC,EAAO;IAMnC,cAAc,IAAI,cAAc,EAAE;IAQlC,OAAO,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC;IAQzE,QAAQ;IAIR,YAAY,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI;IAI5E,OAAO,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAIpJ;AAGD,qBAAa,iBAAkB,SAAQ,aAAa;gBACpC,IAAI,EAAE,MAAM;CAI3B"}

package/lib/types/auth.d.ts

@@ -0,0 +1,20 @@
+import { VertesiaClient } from "@vertesia/client";
+import { AuthTokenPayload } from "@vertesia/common";
+import { Context } from "hono";
+import { JWTVerifyGetKey } from "jose";
+import { ToolExecutionContext } from "./types.js";
+export declare function getJwks(url: string): Promise<JWTVerifyGetKey>;
+export declare function verifyToken(token: string): Promise<import("jose").JWTVerifyResult<AuthTokenPayload> & import("jose").ResolvedKey>;
+export declare function authorize(ctx: Context): Promise<AuthSession>;
+export declare class AuthSession implements ToolExecutionContext {
+    token: string;
+    payload: AuthTokenPayload;
+    _client: VertesiaClient | undefined;
+    endpoints: {
+        studio: string;
+        store: string;
+    };
+    constructor(token: string, payload: AuthTokenPayload);
+    getClient(): Promise<VertesiaClient>;
+}
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAE/B,OAAO,EAA0D,eAAe,EAAE,MAAM,MAAM,CAAC;AAC/F,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGlD,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,4BAcxC;AAED,wBAAsB,WAAW,CAAC,KAAK,EAAE,MAAM,0FAQ9C;AAID,wBAAsB,SAAS,CAAC,GAAG,EAAE,OAAO,wBA6B3C;AAED,qBAAa,WAAY,YAAW,oBAAoB;IAOjC,KAAK,EAAE,MAAM;IAAS,OAAO,EAAE,gBAAgB;IANlE,OAAO,EAAE,cAAc,GAAG,SAAS,CAAC;IACpC,SAAS,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;KACjB,CAAC;gBAEiB,KAAK,EAAE,MAAM,EAAS,OAAO,EAAE,gBAAgB;IAM5D,SAAS;CAMlB"}

package/lib/types/build/validate.d.ts

@@ -0,0 +1,2 @@
+export declare function validate(): void;
+//# sourceMappingURL=validate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/build/validate.ts"],"names":[],"mappings":"AAAA,wBAAgB,QAAQ,SAEvB"}

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./ToolCollection.js";
+export * from "./ToolRegistry.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}

package/lib/types/types.d.ts

@@ -0,0 +1,70 @@
+import type { ToolDefinition, ToolUse } from "@llumiverse/common";
+import { VertesiaClient } from "@vertesia/client";
+import { AuthTokenPayload, ToolResult, ToolResultContent } from "@vertesia/common";
+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.
+     */
+    metadata?: 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?: Record<string, any>;
+}
+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>;
+}
+/**
+ * The interface that should be return when requesting a collection endpoint using a GET
+ */
+export interface ToolCollectionDefinition {
+    title: string;
+    description: string;
+    src: string;
+    tools: ToolDefinition[];
+}
+export type { ToolDefinition };
+//# 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":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEnF,MAAM,WAAW,oBAAoB;IACjC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,OAAO,EAAE,gBAAgB,CAAC;IAC1B;;;OAGG;IACH,SAAS,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC1D;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB,EAAE,UAAU;IAC1E;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,0BAA0B;IACvC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,oBAAoB,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IACrE,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3B;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAClC;AAED,MAAM,MAAM,MAAM,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAElK,MAAM,WAAW,IAAI,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAE,SAAQ,cAAc;IAC7E,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,YAAY,EAAE,cAAc,EAAE,CAAC"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@vertesia/tools-sdk",
+  "version": "0.74.0",
+  "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"
+  },
+  "devDependencies": {
+    "ts-dual-module": "^0.6.3",
+    "typescript": "^5.0.2",
+    "vitest": "^3.0.9"
+  },
+  "ts_dual_module": {
+    "outDir": "lib"
+  },
+  "peerDependencies": {
+    "hono": "^4.0.0"
+  },
+  "dependencies": {
+    "jose": "^6.0.11",
+    "@llumiverse/common": "0.22.0",
+    "@vertesia/client": "0.74.0",
+    "@vertesia/common": "0.74.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "build": "pnpm exec tsmod build",
+    "clean": "rimraf ./node_modules ./lib ./tsconfig.tsbuildinfo"
+  }
+}

package/src/ToolCollection.ts

@@ -0,0 +1,131 @@
+import { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { authorize } from "./auth.js";
+import { ToolRegistry } from "./ToolRegistry.js";
+import type { Tool, ToolDefinition, ToolExecutionPayload, ToolExecutionResponse, ToolExecutionResponseError } from "./types.js";
+
+export interface ToolCollectionProperties {
+    /**
+     * 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;
+
+    /**
+     * The tools
+     */
+    tools: Tool<any>[];
+}
+
+/**
+ * Implements a tools colection endpoint
+ */
+export class ToolCollection implements Iterable<Tool<any>> {
+
+    /**
+     * 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 title will be generated form the kebab case name by replacing - with spaces and upper casing first letter in words.
+     */
+    title?: string;
+    /**
+     * Optional icon for UI display
+     */
+    icon?: string;
+    /**
+     * A short description 
+     */
+    description: string;
+    /**
+     * The tool registry
+     */
+    tools: ToolRegistry;
+
+    constructor({
+        name, title, icon, description, tools
+    }: ToolCollectionProperties) {
+        this.name = name;
+        this.title = title || kebabCaseToTitle(name);
+        this.icon = icon;
+        this.description = description;
+        this.tools = new ToolRegistry(tools);
+    }
+
+    [Symbol.iterator](): Iterator<Tool<any>> {
+        let index = 0;
+        const tools = this.tools.getTools();
+
+        return {
+            next(): IteratorResult<Tool<any>> {
+                if (index < tools.length) {
+                    return { value: tools[index++], done: false };
+                } else {
+                    return { done: true, value: undefined };
+                }
+            }
+        };
+    }
+
+    map<U>(callback: (tool: Tool<any>, index: number) => U): U[] {
+        return this.tools.getTools().map(callback);
+    }
+
+    async execute(ctx: Context) {
+        let payload: ToolExecutionPayload<any> | undefined;
+        try {
+            payload = await readPayload(ctx);
+            const session = await authorize(ctx);
+            const r = await this.tools.runTool(payload, session);
+            return ctx.json({
+                ...r,
+                tool_use_id: payload.tool_use.id
+            } satisfies ToolExecutionResponse);
+        } catch (err: any) { // HTTPException ?
+            const status = err.status || 500;
+            return ctx.json({
+                tool_use_id: payload?.tool_use.id || "undefined",
+                error: err.message || "Error executing tool",
+                status
+            } satisfies ToolExecutionResponseError, status)
+        }
+    }
+
+    getToolDefinitions(): ToolDefinition[] {
+        return this.tools.getDefinitions();
+    }
+
+}
+
+
+async function readPayload(ctx: Context) {
+    try {
+        return await ctx.req.json() as ToolExecutionPayload<any>;
+    } catch (err: any) {
+        throw new HTTPException(500, {
+            message: "Failed to load execution request payload: " + err.message
+        });
+    }
+}
+
+function kebabCaseToTitle(name: string) {
+    return name.split('-').map(p => p[0].toUpperCase() + p.substring(1)).join(' ');
+}

package/src/ToolRegistry.ts

@@ -0,0 +1,49 @@
+import { HTTPException } from "hono/http-exception";
+import { Tool, ToolDefinition, ToolExecutionContext, ToolExecutionPayload, ToolExecutionResult } from "./types.js";
+export class ToolRegistry {
+
+    registry: Record<string, Tool<any>> = {};
+
+    constructor(tools: Tool<any>[] = []) {
+        for (const tool of tools) {
+            this.registry[tool.name] = tool;
+        }
+    }
+
+    getDefinitions(): ToolDefinition[] {
+        return Object.values(this.registry).map(tool => ({
+            name: tool.name,
+            description: tool.description,
+            input_schema: tool.input_schema
+        }));
+    }
+
+    getTool<ParamsT extends Record<string, any>>(name: string): Tool<ParamsT> {
+        const tool = this.registry[name]
+        if (tool === undefined) {
+            throw new ToolNotFoundError(name);
+        }
+        return tool;
+    }
+
+    getTools() {
+        return Object.values(this.registry);
+    }
+
+    registerTool<ParamsT extends Record<string, any>>(tool: Tool<ParamsT>): void {
+        this.registry[tool.name] = tool;
+    }
+
+    runTool<ParamsT extends Record<string, any>>(payload: ToolExecutionPayload<ParamsT>, context: ToolExecutionContext): Promise<ToolExecutionResult> {
+        return this.getTool(payload.tool_use.tool_name).run(payload, context);
+    }
+
+}
+
+
+export class ToolNotFoundError extends HTTPException {
+    constructor(name: string) {
+        super(404, { message: "Tool function not found: " + name });
+        this.name = "ToolNotFoundError";
+    }
+}

package/src/auth.ts

@@ -0,0 +1,87 @@
+import { decodeEndpoints, VertesiaClient } from "@vertesia/client";
+import { AuthTokenPayload } from "@vertesia/common";
+import { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { createLocalJWKSet, decodeJwt, JSONWebKeySet, jwtVerify, JWTVerifyGetKey } from "jose";
+import { ToolExecutionContext } from "./types.js";
+const cache: Record<string, JWTVerifyGetKey> = {};
+
+export async function getJwks(url: string) {
+    if (!cache.url) {
+        console.log('JWKS cache miss for: ', url);
+        const jwks = await fetch(url).then(r => {
+            if (r.ok) {
+                return r.json() as Promise<JSONWebKeySet>;
+            }
+            throw new Error("Fetching jwks failed with code: " + r.status);
+        }).catch(err => {
+            throw new Error("Failed to fetch jwks: " + err.message);
+        })
+        cache.url = createLocalJWKSet(jwks);
+    }
+    return cache.url;
+}
+
+export async function verifyToken(token: string) {
+    const decodedJwt = decodeJwt(token);
+    const { studio } = decodeEndpoints(decodedJwt.endpoints as any);
+    if (!studio) {
+        throw new Error("No studio endpoint found in JWT");
+    }
+    const jwks = await getJwks(`${studio}/.well-known/jwks`);
+    return await jwtVerify<AuthTokenPayload>(token, jwks);
+}
+
+
+
+export async function authorize(ctx: Context) {
+    const auth = ctx.req.header('Authorization');
+    if (!auth) {
+        throw new HTTPException(401, {
+            message: `Missing Authorization header'`
+        });
+    }
+    const [scheme, value] = auth.trim().split(' ');
+    if (scheme.toLowerCase() !== 'bearer') {
+        throw new HTTPException(401, {
+            message: `Authorization scheme ${scheme} is not supported`
+        });
+    }
+    if (!value) {
+        throw new HTTPException(401, {
+            message: `Missing bearer token value`
+        });
+    }
+    try {
+        const { payload } = await verifyToken(value);
+        const session = new AuthSession(value, payload);
+        ctx.set("auth", session);
+        return session;
+    } catch (err: any) {
+        throw new HTTPException(401, {
+            message: err.message,
+            cause: err
+        });
+    }
+}
+
+export class AuthSession implements ToolExecutionContext {
+    _client: VertesiaClient | undefined;
+    endpoints: {
+        studio: string;
+        store: string;
+    };
+
+    constructor(public token: string, public payload: AuthTokenPayload) {
+        this.endpoints = decodeEndpoints(payload.endpoints) as {
+            studio: string, store: string
+        };
+    }
+
+    async getClient() {
+        if (!this._client) {
+            this._client = await VertesiaClient.fromAuthToken(this.token, this.payload);
+        }
+        return this._client;
+    }
+}

package/src/build/validate.ts

@@ -0,0 +1,3 @@
+export function validate() {
+    //TODO
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./ToolCollection.js";
+export * from "./ToolRegistry.js";
+export * from "./types.js";

package/src/types.ts

@@ -0,0 +1,78 @@
+import type { ToolDefinition, ToolUse } from "@llumiverse/common";
+import { VertesiaClient } from "@vertesia/client";
+import { AuthTokenPayload, ToolResult, ToolResultContent } from "@vertesia/common";
+
+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.
+     */
+    metadata?: 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?: Record<string, any>,
+}
+
+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>;
+}
+
+/**
+ * The interface that should be return when requesting a collection endpoint using a GET 
+ */
+export interface ToolCollectionDefinition {
+    title: string;
+    description: string;
+    src: string;
+    tools: ToolDefinition[];
+}
+
+export type { ToolDefinition };