Ajax Davis bc36d366bc feat: add hot-swappable executor support for collections and agents

- Add executor configuration to Collection and Agent models in Prisma schema
- Create ExecutorConfigPanel component for selecting default or custom executors
- Add executor resolution logic with cascade (Agent → Collection → System Default)
- Create /api/executors/verify endpoint to test custom executor connectivity
- Add executor documentation page at /docs/executors with API specification
- Create deployable Vercel executor template in templates/vercel-executor/
- Update MCP handlers and agent tool execution to use configurable executors
- Add executor types and schemas to @tpmjs/types package

Users can now deploy their own executor instances and configure collections
or agents to use custom executors instead of the TPMJS default executor.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

2026-01-09 00:19:22 +10:00

2.9 KiB

Raw Blame History

TPMJS Executor Template

Deploy your own executor for running TPMJS tools on Vercel.

One-Click Deploy

What is an Executor?

An executor is a service that runs TPMJS tools. By default, TPMJS uses a shared executor, but you can deploy your own for:

Full control: Run tools on your own infrastructure
Custom environment: Inject your own environment variables and secrets
Privacy: Keep tool execution data on your own servers
Performance: Deploy in regions closest to your users

API Endpoints

POST /api/execute-tool

Execute a TPMJS tool.

Request:

{
  "packageName": "@tpmjs/hello",
  "name": "helloWorld",
  "version": "latest",
  "params": { "name": "World" },
  "env": { "MY_SECRET": "value" }
}

Response:

{
  "success": true,
  "output": "Hello, World!",
  "executionTimeMs": 123
}

GET /api/health

Check executor health status.

Response:

{
  "status": "ok",
  "version": "1.0.0",
  "info": {
    "runtime": "vercel-serverless",
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

Configuration

Environment Variables

Variable	Required	Description
`EXECUTOR_API_KEY`	No	API key for authentication. If set, requests must include `Authorization: Bearer <key>` header.

Setting Up API Key Authentication

Go to your Vercel project settings
Add an environment variable: EXECUTOR_API_KEY with a secure random value
When configuring your executor in TPMJS, enter this key in the "API Key" field

How It Works

TPMJS sends a request to your executor with package name, tool name, and parameters
The executor dynamically imports the package from esm.sh
The tool's execute() function is called with the provided parameters
The result is returned to TPMJS

Local Development

# Install dependencies
npm install

# Run development server
npm run dev

# Test the health endpoint
curl http://localhost:3000/api/health

# Test tool execution
curl -X POST http://localhost:3000/api/execute-tool \
  -H "Content-Type: application/json" \
  -d '{"packageName":"@anthropic-ai/tpmjs-hello","name":"helloWorld","params":{"name":"Test"}}'

Security Considerations

Always set EXECUTOR_API_KEY in production to prevent unauthorized access
The executor runs tools in a serverless environment with limited capabilities
Environment variables injected via env are available only during execution
Tools are imported from esm.sh, a trusted CDN for npm packages

2.9 KiB Raw Blame History