@vertesia/create-plugin 0.79.3 → 0.79.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/create-plugin",
-  "version": "0.79.3",
+  "version": "0.79.4",
   "description": "Initialize a Vertesia plugin package",
   "type": "module",
   "bin": {
@@ -27,11 +27,23 @@
   "devDependencies": {
     "@types/hasbin": "^1.2.2",
     "@types/node": "^22.5.0",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "hono": "^4.10.3",
+    "@hono/node-server": "^1.19.5",
+    "@llumiverse/common": "0.22.3",
+    "@vertesia/common": "0.79.4",
+    "@vertesia/tools-sdk": "0.79.4",
+    "@vertesia/client": "0.79.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vertesia/composableai.git",
+    "directory": "packages/create-plugin"
   },
   "scripts": {
     "eslint": "eslint './src/**/*.{jsx,js,tsx,ts}'",
-    "build": "rm -rf ./lib ./tsconfig.tsbuildinfo && tsc --build",
+    "build": "rm -rf ./lib ./tsconfig.tsbuildinfo && pnpm run typecheck:templates && tsc --build",
+    "typecheck:templates": "tsc --noEmit --project templates/tool/tsconfig.json",
     "clean": "rimraf ./node_modules ./lib ./tsconfig.tsbuildinfo"
   }
 }

package/templates/tool/.env.example

@@ -0,0 +1,6 @@
+# Environment variables for your tool collections
+
+# Add any API keys or configuration here
+# Example:
+# OPENAI_API_KEY=your-api-key-here
+# WEATHER_API_KEY=your-weather-api-key

package/templates/tool/.vscode/launch.json

@@ -21,4 +21,4 @@
             }
         }
     ]
-}
+}

package/templates/tool/README.md

@@ -1,31 +1,190 @@
-# Vertesia tools plugin
+# Tool Collections
 
-This plugin is exposing tools to vertesia. The tools as exposed on an external webs erver providing two endpoints:
-1. `GET /` - show tool descriptions
-2. `POST /` - execute a tool given an execution payload.
+This project contains custom tool collections for Vertesia.
 
-Note that when deployed on vercel the endpoints are:
+## Project Structure
 
-1. `GET /api`
-2. `POST /api`
+```txt
+src/
+├── collections/           # Tool collections
+│   ├── example/          # Example collection
+│   │   ├── icon.svg.ts   # Collection icon
+│   │   ├── index.ts      # Collection definition
+│   │   └── weather/      # Weather tool
+│   │       ├── manifest.ts     # Tool schema/metadata
+│   │       └── WeatherTool.ts  # Tool implementation
+│   └── index.ts          # Export all collections
+├── server.ts             # Hono server with collection endpoints
+└── index.ts              # Main exports
+```
+
+## Development
+
+Start the development server:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+The server will be available at `http://localhost:5174/api`
+
+### API Endpoints
 
-The payload used when executing a tool must conform to the following interface:
+- `GET /api` - List all collections
+- `GET /api/{collection}` - Get collection metadata and tool definitions
+- `POST /api/{collection}` - Execute a tool in the collection
 
-```ts
-interface ToolExecutionPayload<ParamsT extends Record<string, any>> {
-    context: {
-        serverUrl: string,
-        storeUrl: string,
-        apikey: string
+### Testing the API
+
+Get the example collection tools:
+
+```bash
+curl http://localhost:5174/api/example
+```
+
+Execute the weather tool:
+
+```bash
+curl -X POST http://localhost:5174/api/example \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -d '{
+  "tool_use": {
+    "id": "test-123",
+    "tool_name": "weather",
+    "tool_input": {
+      "location": "New York, NY"
     }
-    vars: Record<string, any>,
-    tool_input: ParamsT,
-    tool_name: string,
+  }
+}'
+```
+
+## Creating New Tools
+
+### 1. Create a new tool in an existing collection
+
+1. Create a new directory under `src/collections/example/` (e.g., `my-tool/`)
+2. Create `manifest.ts` with your tool's schema
+3. Create `MyTool.ts` with the implementation
+4. Add the tool to `src/collections/example/index.ts`
+
+### 2. Create a new collection
+
+1. Create a new directory under `src/collections/` (e.g., `my-collection/`)
+2. Create `icon.svg.ts` with an SVG icon
+3. Create `index.ts` to define the collection
+4. Add your tools in subdirectories
+5. Export the collection in `src/collections/index.ts`
+
+## Authentication
+
+Tools receive authentication context through the `ToolExecutionContext` parameter:
+
+```typescript
+export async function myTool(
+    payload: ToolExecutionPayload<MyToolParams>,
+    context: ToolExecutionContext
+) {
+    // Access the decoded JWT token
+    const userId = context.payload.sub;
+    
+    // Get a Vertesia client instance
+    const client = await context.getClient();
+    
+    // Your tool logic here
+    return {
+        is_error: false,
+        content: "Tool result"
+    };
 }
 ```
 
-To launch the tools server you can start the vite dev server using `pnpm dev`.
+## Building for Production
+
+Build the project:
+
+```bash
+pnpm build
+```
+
+This creates an optimized build in the `dist/` directory.
+
+## Deployment
+
+Your Agent Tool Server can be deployed to various platforms. The server is built with Hono, which supports multiple runtimes including Node.js, Vercel Edge Functions, Cloudflare Workers, AWS Lambda, and more.
+
+For detailed guides on deploying to different platforms, visit the [Hono documentation](https://hono.dev/docs/). The documentation provides comprehensive examples for various deployment targets and runtimes.
+
+### Deploying to Vercel (Example)
+
+This section demonstrates deploying to Vercel as an example, since Vercel offers a generous free tier and simple deployment process. The project includes `api/index.ts` which serves as the entry point for Vercel deployment using the Hono Vercel adapter. Vercel automatically detects and configures the Edge Function.
+
+#### Setup
+
+Install the Vercel CLI globally:
+
+```bash
+npm i -g vercel
+```
+
+#### Deployment Steps
+
+1. **Login to Vercel**:
+
+    ```bash
+    vercel login
+    ```
+
+2. **Deploy to preview**:
+
+    ```bash
+    vercel
+    ```
+
+    This will create a preview deployment and provide you with a URL to test your tool server.
+
+3. **Deploy to production**:
+
+    ```bash
+    vercel --prod
+    ```
+
+Your tool server will be available at `https://your-project.vercel.app/api`
+
+For more information, visit the [Vercel CLI documentation](https://vercel.com/docs/cli).
+
+#### Verify Your Deployment
+
+Test that your server is responding correctly:
+
+```bash
+curl https://your-project.vercel.app/api
+```
+
+You should see a JSON response with the API information and available endpoints.
+
+#### Configure Your Tool Server in Vertesia
+
+After deploying to Vercel, update your app manifest to point to the deployed URL using the vertesia CLI:
+
+```bash
+vertesia apps update <appId> --manifest '{
+  "name": "my-app",
+  "title": "My App",
+  "description": "A sample app",
+  "publisher": "your-org",
+  "private": true,
+  "status": "beta",
+  "tool_collections": [
+    "https://your-app.vercel.app/api/example"
+  ],
+}'
+```
+
+Replace `appId` by the actual ID and `https://your-app.vercel.app` with your actual Vercel deployment URL.
 
-If you want to **debug** and add breakpoints in the code you must run the vite dev server from VSCode by running the `Debug Tools Server` launch configuration.
+## Learn More
 
-Vercel deployment is supported by wrapping the `hono` server using a vercel adapter.
+- [Vertesia Documentation](https://docs.vertesiahq.com)
+- [Tool SDK Reference](https://github.com/vertesia/composableai/tree/main/packages/tools-sdk)

package/templates/tool/gitignore

@@ -0,0 +1,26 @@
+# Dependencies
+
+node_modules/
+
+# Build output
+
+dist/
+lib/
+\*.tsbuildinfo
+
+# Environment
+
+.env
+.env.local
+
+# IDE
+
+.vscode/
+.idea/
+_.swp
+_.swo
+
+# OS
+
+.DS_Store
+Thumbs.db

package/templates/tool/rollup.config.js

@@ -0,0 +1,30 @@
+import commonjs from '@rollup/plugin-commonjs';
+import json from '@rollup/plugin-json';
+import resolve from '@rollup/plugin-node-resolve';
+
+export default {
+    input: './dist/server.js',
+    output: {
+        file: './dist/bundle.js',
+        format: 'es',
+        sourcemap: false
+    },
+    plugins: [
+        resolve({
+            preferBuiltins: true,
+            exportConditions: ['node']
+        }),
+        commonjs(),
+        json()
+    ],
+    external: [
+        // Keep these as external dependencies
+        'hono',
+        'jose',
+        'dotenv',
+        '@vertesia/client',
+        '@vertesia/common',
+        '@vertesia/tools-sdk',
+        '@hono/node-server'
+    ]
+};

package/templates/tool/src/collections/example/icon.svg.ts

@@ -0,0 +1,6 @@
+// Simple SVG icon for the collection
+// You can replace this with your own icon
+export const icon = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <circle cx="12" cy="12" r="10"/>
+  <path d="M12 6v6l4 2"/>
+</svg>`;

package/templates/tool/src/collections/example/index.ts

@@ -0,0 +1,14 @@
+import { ToolCollection } from "@vertesia/tools-sdk";
+import { icon } from "./icon.svg.js";
+import { WeatherTool } from "./weather/WeatherTool.js";
+
+export const ExampleCollection = new ToolCollection({
+    name: "example",
+    title: "Example Tools",
+    description: "A collection of example tools to get you started",
+    icon,
+    tools: [
+        WeatherTool
+        // Add more tools here
+    ]
+});

package/templates/tool/src/collections/example/weather/WeatherTool.ts

@@ -0,0 +1,32 @@
+import type { Tool, ToolExecutionPayload, ToolExecutionContext } from "@vertesia/tools-sdk";
+import manifest from "./manifest.js";
+import { ToolResultContent } from "@vertesia/common";
+
+interface WeatherToolParams {
+    location: string;
+}
+
+// Tool implementation function
+export async function weather(
+    payload: ToolExecutionPayload<WeatherToolParams>,
+    context: ToolExecutionContext
+) {
+    const { location } = payload.tool_use.tool_input!;
+
+    console.log(`Caller: ${context.payload.user_id}`);
+    
+    // Simulate fetching weather data
+    // In a real implementation, you would call a weather API here
+    // You can use context.getClient() to access Vertesia services if needed
+    
+    return {
+        is_error: false,
+        content: `The current weather in ${location} is sunny with a temperature of 75°F.`
+    } satisfies ToolResultContent;
+}
+
+// Export the complete tool with manifest and implementation
+export const WeatherTool = {
+    ...manifest,
+    run: weather
+} satisfies Tool<WeatherToolParams>;

package/templates/tool/src/collections/example/weather/manifest.ts

@@ -0,0 +1,16 @@
+import { ToolDefinition } from "@vertesia/tools-sdk";
+
+export default {
+    name: "weather",
+    description: "Get the current weather for a given location.",
+    input_schema: {
+        type: "object",
+        properties: {
+            location: {
+                type: "string",
+                description: "The location to get the weather for, e.g., 'New York, NY'."
+            }
+        },
+        required: ["location"]
+    },
+} satisfies ToolDefinition;

package/templates/tool/src/collections/index.ts

@@ -0,0 +1,7 @@
+import { ExampleCollection } from "./example/index.js";
+
+// Export all your tool collections here
+export const collections = [
+    ExampleCollection
+    // Add more collections as you create them
+];

package/templates/tool/src/index.ts

@@ -1,6 +1,5 @@
-import { ToolRegistry } from '@vertesia/agent-sdk';
-import { WeatherTool } from "./tools/WeatherTool.js";
+// Export collections for use in other modules or for programmatic access
+export { collections } from "./collections/index.js";
 
-export const registry = new ToolRegistry([
-    WeatherTool
-]);
+// Export server as default for deployment
+export { default } from "./server.js";

package/templates/tool/src/server.ts

@@ -1,19 +1,73 @@
-import { Hono } from 'hono';
-import { registry } from "./index.js";
-import { cors } from 'hono/cors'
-
-const app = new Hono();
-app.get("/", cors({ origin: '*', allowMethods: ['GET'] }))
-app.post('/', async (c) => {
-    const data = await c.req.json();
-    const r = await registry.execute(data)
-    return c.json({
-        response: r
+import { ToolCollection, ToolCollectionDefinition } from "@vertesia/tools-sdk";
+import { Context, Hono } from "hono";
+import { cors } from "hono/cors";
+import { collections } from "./collections/index.js";
+import { HTTPException } from "hono/http-exception";
+
+function createServer(collections: ToolCollection[], prefix = '/api') {
+    prefix = prefix.trim();
+    const app = new Hono();
+
+    // Add CORS middleware globally
+    app.use('*', cors({ origin: '*', allowMethods: ['GET', 'POST', 'OPTIONS'] }));
+
+    // Add base API route
+    app.get(prefix, (c) => {
+        return c.json({
+            message: 'Tool Collections API',
+            version: '1.0.0',
+            endpoints: {
+                collections: collections.map(col => `${prefix}/${col.name}`)
+            }
+        });
+    });
+
+    // Create endpoints for tool collections
+    for (const col of collections) {
+        app.route(`${prefix}/${col.name}`, createCollectionEndpoints(col));
+    }
+
+    // Global error handler
+    app.onError((err, c) => {
+        if (err instanceof HTTPException) {
+            return c.json({
+                error: err.message,
+            }, err.status);
+        }
+        console.error('Uncaught Error:', err);
+        return c.json({
+            error: 'Internal Server Error',
+        }, 500)
     })
-})
 
-app.get('/', (c) => {
-    return c.json(registry.getDefinitions())
-});
+    return app;
+}
+
+const server = createServer(collections);
+
+export default server;
+
+/**
+ * Create endpoints for a tool collection
+ */
+function createCollectionEndpoints(coll: ToolCollection) {
+    const endpoint = new Hono();
+
+    // POST endpoint to execute tools
+    endpoint.post('/', (c: Context) => {
+        return coll.execute(c);
+    });
+
+    // GET endpoint to retrieve collection metadata and tool definitions
+    endpoint.get('/', (c) => {
+        const url = new URL(c.req.url);
+        return c.json({
+            src: `${url.origin}${url.pathname}`,
+            title: coll.title || coll.name,
+            description: coll.description,
+            tools: coll.getToolDefinitions()
+        } satisfies ToolCollectionDefinition);
+    });
 
-export default app;
+    return endpoint;
+}

package/templates/tool/tsconfig.json

@@ -1,14 +1,24 @@
 {
     "compilerOptions": {
-        "target": "ES2020",
+        "target": "ES2022",
         "module": "ESNext",
-        "moduleResolution": "node",
+        "moduleResolution": "Bundler",
         "esModuleInterop": true,
         "strict": true,
         "skipLibCheck": true,
+        "resolveJsonModule": true,
+        "allowSyntheticDefaultImports": true,
+        "forceConsistentCasingInFileNames": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "noImplicitReturns": true,
         "outDir": "dist"
     },
     "include": [
-        "src"
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist"
     ]
-}
+}

package/templates/tool/vercel.json

@@ -1,7 +1,8 @@
 {
-    "functions": {
-        "api/index.ts": {
-            "runtime": "edge"
-        }
+  "rewrites": [
+    {
+      "source": "/api/:path*",
+      "destination": "/api"
     }
-}
+  ]
+}

package/templates/tool/vite.config.js

@@ -1,10 +1,48 @@
-import { defineConfig } from 'vite';
 import devServer from '@hono/vite-dev-server';
+import { defineConfig, loadEnv } from 'vite';
 
-export default defineConfig({
-    plugins: [
-        devServer({
-            entry: 'src/server.ts', // Adjust the path to your server entry file
-        }),
-    ],
-});
+export default defineConfig(({ mode }) => {
+    // Load env files
+    const env = loadEnv(mode, process.cwd(), '');
+
+    // Dev config
+    if (mode === 'development') {
+        return {
+            base: '/api',
+            plugins: [
+                devServer({
+                    entry: './src/server.ts',
+                }),
+            ],
+        }
+    }
+
+    // Build config
+    return {
+        build: {
+            minify: false,
+            lib: {
+                entry: {
+                    server: './src/server.ts',
+                },
+                formats: ['es']
+            },
+            rollupOptions: {
+                external: (id) => {
+                    // Keep relative imports as part of the bundle
+                    if (id.startsWith('.') || id.startsWith('/')) {
+                        return false;
+                    }
+                    // Externalize all node modules and absolute imports
+                    return true;
+                },
+                output: {
+                    preserveModules: true,
+                    preserveModulesRoot: 'src',
+                    entryFileNames: '[name].js'
+                }
+            },
+            outDir: 'dist'
+        },
+    }
+});