@vertesia/tools-sdk 1.2.0 → 1.4.0-dev.20260615.042549Z

package/src/ToolRegistry.ts

@@ -1,15 +1,13 @@
-import { AgentToolDefinition } from "@vertesia/common";
-import { HTTPException } from "hono/http-exception";
-import { Tool, ToolExecutionContext, ToolExecutionPayload, ToolExecutionResult, ToolUseContext } from "./types.js";
-
+import type { AgentToolDefinition } from '@vertesia/common';
+import { HTTPException } from 'hono/http-exception';
+import type { Tool, ToolExecutionContext, ToolExecutionPayload, ToolExecutionResult, ToolUseContext } from './types.js';
 
 export class ToolRegistry {
-
     // The category name usinfg this registry
     category: string;
-    registry: Record<string, Tool<any>> = {};
+    registry: Record<string, Tool> = {};
 
-    constructor(category: string, tools: Tool<any>[] = []) {
+    constructor(category: string, tools: Tool[] = []) {
         this.category = category;
         for (const tool of tools) {
             this.registry[tool.name] = tool;
@@ -22,81 +20,53 @@ export class ToolRegistry {
      * @returns Filtered tool definitions
      */
     getDefinitions(context?: ToolUseContext): AgentToolDefinition[] {
-        const mapTool = (tool: Tool<any>): AgentToolDefinition => ({
+        const mapTool = (tool: Tool): AgentToolDefinition => ({
             url: `tools/${this.category}`,
             name: tool.name,
             description: tool.description,
             input_schema: tool.input_schema,
             category: this.category,
             default: tool.default,
+            ...(tool.annotations ? { annotations: tool.annotations } : {}),
+            ...(tool.requires_user_confirmation ? { requires_user_confirmation: true } : {}),
         });
         let tools = Object.values(this.registry);
         if (context) {
-            tools = tools.filter(tool => {
+            tools = tools.filter((tool) => {
                 return tool.isEnabled ? tool.isEnabled(context) : true;
             });
         }
         return tools.map(mapTool);
     }
 
-    getTool<ParamsT extends Record<string, any>>(name: string): Tool<ParamsT> {
-        const tool = this.registry[name]
+    getTool<ParamsT extends object>(name: string): Tool<ParamsT> {
+        const tool = this.registry[name];
         if (tool === undefined) {
             throw new ToolNotFoundError(name);
         }
-        return tool;
+        return tool as unknown as Tool<ParamsT>;
     }
 
     getTools() {
         return Object.values(this.registry);
     }
 
-    registerTool<ParamsT extends Record<string, any>>(tool: Tool<ParamsT>): void {
-        this.registry[tool.name] = tool;
+    registerTool<ParamsT extends object>(tool: Tool<ParamsT>): void {
+        this.registry[tool.name] = tool as unknown as Tool;
     }
 
-    runTool<ParamsT extends Record<string, any>>(payload: ToolExecutionPayload<ParamsT>, context: ToolExecutionContext): Promise<ToolExecutionResult> {
+    runTool<ParamsT extends object>(
+        payload: ToolExecutionPayload<ParamsT>,
+        context: ToolExecutionContext,
+    ): Promise<ToolExecutionResult> {
         const toolName = payload.tool_use.tool_name;
-        const toolUseId = payload.tool_use.id;
-        const runId = payload.metadata?.run_id;
-        console.log(`[ToolRegistry] Executing tool: ${toolName}`, {
-            toolUseId,
-            runId,
-            input: sanitizeInput(payload.tool_use.tool_input),
-        });
         return this.getTool(toolName).run(payload, context);
     }
-
 }
 
-
 export class ToolNotFoundError extends HTTPException {
     constructor(name: string) {
-        super(404, { message: "Tool function not found: " + name });
-        this.name = "ToolNotFoundError";
+        super(404, { message: `Tool function not found: ${name}` });
+        this.name = 'ToolNotFoundError';
     }
 }
-
-const SENSITIVE_KEYS = new Set([
-    'apikey', 'api_key', 'token', 'secret', 'password', 'credential', 'credentials',
-    'authorization', 'auth', 'key', 'private_key', 'access_token', 'refresh_token'
-]);
-
-function sanitizeInput(input: Record<string, any> | null | undefined): Record<string, any> | null {
-    if (!input) return null;
-
-    const sanitized: Record<string, any> = {};
-    for (const [key, value] of Object.entries(input)) {
-        const lowerKey = key.toLowerCase();
-        if (SENSITIVE_KEYS.has(lowerKey) || lowerKey.includes('key') || lowerKey.includes('token') || lowerKey.includes('secret')) {
-            sanitized[key] = '[REDACTED]';
-        } else if (typeof value === 'string' && value.length > 50) {
-            sanitized[key] = value.slice(0, 50) + '...';
-        } else if (typeof value === 'object' && value !== null) {
-            sanitized[key] = Array.isArray(value) ? `[Array(${value.length})]` : '[Object]';
-        } else {
-            sanitized[key] = value;
-        }
-    }
-    return sanitized;
-}

package/src/auth.ts

@@ -1,22 +1,25 @@
-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";
+import { decodeEndpoints, VertesiaClient } from '@vertesia/client';
+import type { AuthTokenPayload } from '@vertesia/common';
+import type { Context } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import { createLocalJWKSet, decodeJwt, type JSONWebKeySet, type JWTVerifyGetKey, jwtVerify } from 'jose';
+import type { 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);
-        })
+        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];
@@ -25,16 +28,15 @@ export async function getJwks(url: string) {
 export async function verifyToken(token: string) {
     const decodedJwt = decodeJwt(token);
     if (!decodedJwt.iss) {
-        throw new Error("No issuer URL found in JWT");
+        throw new Error('No issuer URL found in JWT');
     }
     if (!isAllowedIssuer(decodedJwt.iss)) {
-        throw new Error("Issuer is not allowed: " + decodedJwt.iss);
+        throw new Error(`Issuer is not allowed: ${decodedJwt.iss}`);
     }
     const jwks = await getJwks(`${decodedJwt.iss}/.well-known/jwks`);
     return await jwtVerify<AuthTokenPayload>(token, jwks);
 }
 
-
 export interface EndpointOverrides {
     studio?: string;
     store?: string;
@@ -51,31 +53,32 @@ export async function authorize(ctx: Context, endpointOverrides?: EndpointOverri
     const auth = ctx.req.header('Authorization');
     if (!auth) {
         throw new HTTPException(401, {
-            message: `Missing Authorization header`
+            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`
+            message: `Authorization scheme ${scheme} is not supported`,
         });
     }
     if (!value) {
         throw new HTTPException(401, {
-            message: `Missing bearer token value`
+            message: `Missing bearer token value`,
         });
     }
     try {
         const { payload } = await verifyToken(value);
         assertAllowedOrg(payload);
         const session = new AuthSession(value, payload, endpointOverrides, toolContext);
-        ctx.set("auth", session);
+        ctx.set('auth', session);
         return session;
-    } catch (err: any) {
+    } catch (err: unknown) {
         if (err instanceof HTTPException) throw err;
+        const message = err instanceof Error ? err.message : String(err);
         throw new HTTPException(401, {
-            message: err.message,
-            cause: err
+            message,
+            cause: err,
         });
     }
 }
@@ -93,7 +96,7 @@ export class AuthSession implements ToolExecutionContext {
         public token: string,
         public payload: AuthTokenPayload,
         endpointOverrides?: EndpointOverrides,
-        toolContext?: ToolContext
+        toolContext?: ToolContext,
     ) {
         const decoded = decodeEndpoints(payload.endpoints);
         // Use overrides from workflow config if provided, falling back to JWT endpoints
@@ -121,7 +124,7 @@ export class AuthSession implements ToolExecutionContext {
 }
 
 function isAllowedIssuer(iss: string) {
-    return iss.endsWith(".vertesia.io") || iss.endsWith(".becomposable.com");
+    return iss.endsWith('.vertesia.io') || iss.endsWith('.becomposable.com');
 }
 
 /**
@@ -133,7 +136,12 @@ function getAllowedOrgs(): Set<string> | null {
     if (_allowedOrgs === undefined) {
         const raw = process.env.VERTESIA_ALLOWED_ORGS;
         _allowedOrgs = raw
-            ? new Set(raw.split(',').map(s => s.trim()).filter(Boolean))
+            ? new Set(
+                  raw
+                      .split(',')
+                      .map((s) => s.trim())
+                      .filter(Boolean),
+              )
             : null;
     }
     return _allowedOrgs;

package/src/copy-assets.ts

@@ -10,8 +10,8 @@
  *   import { copyRuntimeAssets } from '@vertesia/tools-sdk';
  *   copyRuntimeAssets('./src', './dist');
  */
-import { existsSync, readdirSync, statSync, mkdirSync, copyFileSync } from "fs";
-import { dirname, join } from "path";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 
 /**
  * Recursively copy files matching a filter
@@ -50,11 +50,7 @@ export interface CopyAssetsOptions {
  * Copy runtime assets (skills, interactions) from src to dist
  */
 export function copyRuntimeAssets(options: CopyAssetsOptions = {}): void {
-    const {
-        srcDir = './src',
-        distDir = './dist',
-        verbose = true
-    } = options;
+    const { srcDir = './src', distDir = './dist', verbose = true } = options;
 
     if (verbose) {
         console.log('Copying runtime assets to dist...');
@@ -66,9 +62,7 @@ export function copyRuntimeAssets(options: CopyAssetsOptions = {}): void {
 
     if (existsSync(skillsSrc)) {
         copyFilesRecursive(skillsSrc, skillsDest, (filename) => {
-            return filename === 'SKILL.md' ||
-                   filename === 'SKILL.jst' ||
-                   filename.endsWith('.py');
+            return filename === 'SKILL.md' || filename === 'SKILL.jst' || filename.endsWith('.py');
         });
         if (verbose) {
             console.log('  ✓ Skills assets (SKILL.md, SKILL.jst, *.py)');
@@ -81,8 +75,7 @@ export function copyRuntimeAssets(options: CopyAssetsOptions = {}): void {
 
     if (existsSync(interactionsSrc)) {
         copyFilesRecursive(interactionsSrc, interactionsDest, (filename) => {
-            return filename === 'prompt.jst' ||
-                   filename === 'prompt.md';
+            return filename === 'prompt.jst' || filename === 'prompt.md';
         });
         if (verbose) {
             console.log('  ✓ Interaction assets (prompt.jst, prompt.md)');

package/src/index.ts

@@ -1,15 +1,15 @@
-export * from "./ActivityCollection.js";
-export { authorize, AuthSession } from "./auth.js";
-export * from "./ContentTypesCollection.js";
-export * from "./RenderingTemplateCollection.js";
-export { copyRuntimeAssets } from "./copy-assets.js";
-export * from "./InteractionCollection.js";
-export * from "./server.js";
-export * from "./server/types.js";
-export * from "./site/templates.js";
-export * from "./SkillCollection.js";
-export * from "./ToolCollection.js";
-export * from "./ToolRegistry.js";
-export * from "./types.js";
-
-
+export * from './ActivityCollection.js';
+export { AuthSession, authorize } from './auth.js';
+export * from './ContentTypesCollection.js';
+export { copyRuntimeAssets } from './copy-assets.js';
+export * from './InteractionCollection.js';
+export * from './RenderingTemplateCollection.js';
+export * from './SkillCollection.js';
+export type { BuildAppPackageOptions } from './server/app-package.js';
+export { buildAppPackage } from './server/app-package.js';
+export * from './server/types.js';
+export * from './server.js';
+export * from './site/templates.js';
+export * from './ToolCollection.js';
+export * from './ToolRegistry.js';
+export * from './types.js';

package/src/server/activities.test.ts

@@ -1,123 +1,126 @@
-import { Hono } from "hono";
-import { describe, expect, it, vi } from "vitest";
-import { ActivityCollection, ActivityDefinition } from "../ActivityCollection.js";
-import { createActivitiesRoute } from "./activities.js";
-import { ToolServerConfig } from "./types.js";
+import { Hono } from 'hono';
+import { describe, expect, it, vi } from 'vitest';
+import { ActivityCollection, type ActivityDefinition } from '../ActivityCollection.js';
+import { createActivitiesRoute } from './activities.js';
+import type { ToolServerConfig } from './types.js';
+
+/** Permissive recursive type for navigating JSON response bodies in tests. */
+type Tree = { readonly [key: string]: Tree };
 
 // Mock authorize to avoid JWT verification
-vi.mock("../auth.js", () => ({
-    authorize: vi.fn().mockResolvedValue({ token: "test-token" }),
+vi.mock('../auth.js', () => ({
+    authorize: vi.fn().mockResolvedValue({ token: 'test-token' }),
     AuthSession: vi.fn(),
 }));
 
 const mockActivity: ActivityDefinition = {
-    name: "analyze_sentiment",
-    title: "Analyze Sentiment",
-    description: "Analyzes text sentiment",
-    input_schema: { type: "object", properties: { text: { type: "string" } } },
+    name: 'analyze_sentiment',
+    title: 'Analyze Sentiment',
+    description: 'Analyzes text sentiment',
+    input_schema: { type: 'object', properties: { text: { type: 'string' } } },
     run: vi.fn().mockResolvedValue({ score: 0.95 }),
 };
 
 const mockActivity2: ActivityDefinition = {
-    name: "extract_entities",
-    description: "Extracts entities",
-    run: vi.fn().mockResolvedValue({ entities: ["foo"] }),
+    name: 'extract_entities',
+    description: 'Extracts entities',
+    run: vi.fn().mockResolvedValue({ entities: ['foo'] }),
 };
 
 function createApp(activities: ActivityCollection[] = []) {
     const app = new Hono();
     const config = { activities } as ToolServerConfig;
-    createActivitiesRoute(app, "/api/activities", config);
+    createActivitiesRoute(app, '/api/activities', config);
     return app;
 }
 
 function createTestCollections() {
     const coll1 = new ActivityCollection({
-        name: "nlp",
-        description: "NLP activities",
+        name: 'nlp',
+        description: 'NLP activities',
         activities: [mockActivity],
     });
     const coll2 = new ActivityCollection({
-        name: "extraction",
-        description: "Extraction activities",
+        name: 'extraction',
+        description: 'Extraction activities',
         activities: [mockActivity2],
     });
     return [coll1, coll2];
 }
 
-describe("Activities server routes", () => {
-    describe("GET /api/activities", () => {
-        it("returns all activity definitions across collections", async () => {
+describe('Activities server routes', () => {
+    describe('GET /api/activities', () => {
+        it('returns all activity definitions across collections', async () => {
             const app = createApp(createTestCollections());
-            const res = await app.request("/api/activities");
-            const body = await res.json() as any;
+            const res = await app.request('/api/activities');
+            const body = (await res.json()) as unknown as Tree;
 
             expect(res.status).toBe(200);
             expect(body.activities).toHaveLength(2);
-            expect(body.activities[0].name).toBe("analyze_sentiment");
-            expect(body.activities[1].name).toBe("extract_entities");
+            expect(body.activities[0].name).toBe('analyze_sentiment');
+            expect(body.activities[1].name).toBe('extract_entities');
             expect(body.collections).toHaveLength(2);
         });
 
-        it("returns empty when no collections configured", async () => {
+        it('returns empty when no collections configured', async () => {
             const app = createApp([]);
-            const res = await app.request("/api/activities");
-            const body = await res.json() as any;
+            const res = await app.request('/api/activities');
+            const body = (await res.json()) as unknown as Tree;
 
             expect(res.status).toBe(200);
             expect(body.activities).toHaveLength(0);
         });
     });
 
-    describe("GET /api/activities/{collection}", () => {
-        it("returns activities for a specific collection", async () => {
+    describe('GET /api/activities/{collection}', () => {
+        it('returns activities for a specific collection', async () => {
             const app = createApp(createTestCollections());
-            const res = await app.request("/api/activities/nlp");
-            const body = await res.json() as any;
+            const res = await app.request('/api/activities/nlp');
+            const body = (await res.json()) as unknown as Tree;
 
             expect(res.status).toBe(200);
-            expect(body.name).toBe("nlp");
+            expect(body.name).toBe('nlp');
             expect(body.activities).toHaveLength(1);
-            expect(body.activities[0].name).toBe("analyze_sentiment");
+            expect(body.activities[0].name).toBe('analyze_sentiment');
         });
     });
 
-    describe("POST /api/activities", () => {
-        it("executes activity by name", async () => {
+    describe('POST /api/activities', () => {
+        it('executes activity by name', async () => {
             const app = createApp(createTestCollections());
-            const res = await app.request("/api/activities", {
-                method: "POST",
+            const res = await app.request('/api/activities', {
+                method: 'POST',
                 headers: {
-                    "Content-Type": "application/json",
-                    "Authorization": "Bearer test-token",
+                    'Content-Type': 'application/json',
+                    Authorization: 'Bearer test-token',
                 },
                 body: JSON.stringify({
-                    activity_name: "analyze_sentiment",
-                    params: { text: "hello" },
+                    activity_name: 'analyze_sentiment',
+                    params: { text: 'hello' },
                     metadata: {
-                        workflow_name: "wf",
-                        account_id: "acc",
-                        project_id: "proj",
+                        workflow_name: 'wf',
+                        account_id: 'acc',
+                        project_id: 'proj',
                     },
                 }),
             });
 
             expect(res.status).toBe(200);
-            const body = await res.json() as any;
+            const body = (await res.json()) as unknown as Tree;
             expect(body.result).toEqual({ score: 0.95 });
             expect(body.is_error).toBe(false);
         });
 
-        it("returns 404 for unknown activity name", async () => {
+        it('returns 404 for unknown activity name', async () => {
             const app = createApp(createTestCollections());
-            const res = await app.request("/api/activities", {
-                method: "POST",
+            const res = await app.request('/api/activities', {
+                method: 'POST',
                 headers: {
-                    "Content-Type": "application/json",
-                    "Authorization": "Bearer test-token",
+                    'Content-Type': 'application/json',
+                    Authorization: 'Bearer test-token',
                 },
                 body: JSON.stringify({
-                    activity_name: "nonexistent",
+                    activity_name: 'nonexistent',
                     params: {},
                     metadata: {},
                 }),
@@ -126,13 +129,13 @@ describe("Activities server routes", () => {
             expect(res.status).toBe(404);
         });
 
-        it("returns 400 for missing activity_name", async () => {
+        it('returns 400 for missing activity_name', async () => {
             const app = createApp(createTestCollections());
-            const res = await app.request("/api/activities", {
-                method: "POST",
+            const res = await app.request('/api/activities', {
+                method: 'POST',
                 headers: {
-                    "Content-Type": "application/json",
-                    "Authorization": "Bearer test-token",
+                    'Content-Type': 'application/json',
+                    Authorization: 'Bearer test-token',
                 },
                 body: JSON.stringify({ params: {} }),
             });
@@ -141,25 +144,25 @@ describe("Activities server routes", () => {
         });
     });
 
-    describe("POST /api/activities/{collection}", () => {
-        it("routes to correct collection", async () => {
+    describe('POST /api/activities/{collection}', () => {
+        it('routes to correct collection', async () => {
             const app = createApp(createTestCollections());
-            const res = await app.request("/api/activities/extraction", {
-                method: "POST",
+            const res = await app.request('/api/activities/extraction', {
+                method: 'POST',
                 headers: {
-                    "Content-Type": "application/json",
-                    "Authorization": "Bearer test-token",
+                    'Content-Type': 'application/json',
+                    Authorization: 'Bearer test-token',
                 },
                 body: JSON.stringify({
-                    activity_name: "extract_entities",
+                    activity_name: 'extract_entities',
                     params: {},
                     metadata: {},
                 }),
             });
 
             expect(res.status).toBe(200);
-            const body = await res.json() as any;
-            expect(body.result).toEqual({ entities: ["foo"] });
+            const body = (await res.json()) as unknown as Tree;
+            expect(body.result).toEqual({ entities: ['foo'] });
         });
     });
 });

package/src/server/activities.ts

@@ -1,8 +1,8 @@
-import { RemoteActivityDefinition, RemoteActivityExecutionPayload } from "@vertesia/common";
-import { Context, Hono } from "hono";
-import { HTTPException } from "hono/http-exception";
-import { ActivityCollection } from "../ActivityCollection.js";
-import { ToolServerConfig } from "./types.js";
+import type { RemoteActivityDefinition, RemoteActivityExecutionPayload } from '@vertesia/common';
+import { type Context, Hono } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import type { ActivityCollection } from '../ActivityCollection.js';
+import type { ToolServerConfig } from './types.js';
 
 /**
  * Safely parse JSON from a request body. Throws HTTPException(400) on invalid JSON.
@@ -12,11 +12,15 @@ async function safeParseJson(c: Context): Promise<unknown> {
         return await c.req.json();
     } catch {
         throw new HTTPException(400, {
-            message: 'Invalid JSON in request body.'
+            message: 'Invalid JSON in request body.',
         });
     }
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return !!value && typeof value === 'object';
+}
+
 /**
  * Validates the structure of a RemoteActivityExecutionPayload.
  * Returns the parsed payload or throws HTTPException(400).
@@ -24,19 +28,19 @@ async function safeParseJson(c: Context): Promise<unknown> {
 function parseActivityPayload(body: unknown): RemoteActivityExecutionPayload {
     if (!body || typeof body !== 'object') {
         throw new HTTPException(400, {
-            message: 'Invalid or missing activity execution payload.'
+            message: 'Invalid or missing activity execution payload.',
         });
     }
-    const obj = body as Record<string, any>;
+    const obj = body as Record<string, unknown>;
     if (typeof obj.activity_name !== 'string' || !obj.activity_name) {
         throw new HTTPException(400, {
-            message: 'Missing required field: activity_name'
+            message: 'Missing required field: activity_name',
         });
     }
     return {
         activity_name: obj.activity_name,
-        params: obj.params || {},
-        metadata: obj.metadata || {},
+        params: isRecord(obj.params) ? obj.params : {},
+        metadata: isRecord(obj.metadata) ? obj.metadata : {},
     };
 }
 
@@ -61,7 +65,7 @@ export function createActivitiesRoute(app: Hono, basePath: string, config: ToolS
             title: 'All Activities',
             description: 'All available remote activities across all collections',
             activities: allActivities,
-            collections: activities.map(a => ({
+            collections: activities.map((a) => ({
                 name: a.name,
                 title: a.title,
                 description: a.description,
@@ -77,7 +81,7 @@ export function createActivitiesRoute(app: Hono, basePath: string, config: ToolS
         const collection = activityToCollection.get(payload.activity_name);
         if (!collection) {
             throw new HTTPException(404, {
-                message: `Activity not found: ${payload.activity_name}. Available: ${Array.from(activityToCollection.keys()).join(', ')}`
+                message: `Activity not found: ${payload.activity_name}. Available: ${Array.from(activityToCollection.keys()).join(', ')}`,
             });
         }