History

Ajax Davis c2447e8467 fix(executor): move startTime declaration before try block The startTime variable was declared inside the try block but referenced in the catch block, causing 'startTime is not defined' errors when exceptions occurred before line 404 (e.g., during req.json() parsing). Moving the declaration before the try ensures it's in scope for the catch block's executionTimeMs calculation.		2025-12-12 05:53:47 +10:00
..
.gitignore	feat: add dynamic tool loading system with Railway executor	2025-12-04 08:25:53 +10:00
Dockerfile	fix: remove nonexistent deno.json from Dockerfile	2025-12-05 01:10:42 +10:00
package-lock.json	feat: add dynamic tool loading system with Railway executor	2025-12-04 08:25:53 +10:00
package.json	feat: add dynamic tool loading system with Railway executor	2025-12-04 08:25:53 +10:00
README.md	feat: add dynamic tool loading system with Railway executor	2025-12-04 08:25:53 +10:00
server.js	feat: add dynamic tool loading system with Railway executor	2025-12-04 08:25:53 +10:00
server.ts	fix(executor): move startTime declaration before try block	2025-12-12 05:53:47 +10:00

README.md

Railway Dynamic Tool Executor

Dynamic tool executor service that runs with --experimental-network-imports to support loading npm packages from esm.sh at runtime.

Features

🔥 Dynamic imports from esm.sh
💾 Module caching for fast repeated loads
🛡️ Validation of AI SDK tool structure
🚀 Remote execution of tools with parameters

Endpoints

`GET /health`

Health check and cache statistics

`POST /load-and-describe`

Load a tool from esm.sh and return its schema

Request:

{
  "packageName": "firecrawl-aisdk",
  "exportName": "webSearchTool",
  "version": "0.7.2",
  "importUrl": "https://esm.sh/firecrawl-aisdk@0.7.2"
}

Response:

{
  "success": true,
  "tool": {
    "exportName": "webSearchTool",
    "description": "Search the web using Firecrawl",
    "inputSchema": { ... }
  }
}

`POST /execute-tool`

Execute a tool with parameters

Request:

{
  "packageName": "firecrawl-aisdk",
  "exportName": "webSearchTool",
  "version": "0.7.2",
  "params": {
    "query": "latest AI news"
  }
}

Response:

{
  "success": true,
  "output": { ... },
  "executionTimeMs": 1234
}

`POST /cache/clear`

Clear the module cache

`GET /cache/stats`

Get cache statistics

Local Development

# Install dependencies
npm install

# Start server
npm start

# Server runs on http://localhost:3001

Railway Deployment

This service is designed to run on Railway.

Deploy Steps

Initialize Railway in this directory:

cd apps/railway-executor
railway init

Link to your Railway project:

railway link

Deploy:

railway up

Railway will automatically:
- Detect Node.js
- Run npm install
- Execute npm start (which includes --experimental-network-imports)

Environment Variables

No environment variables required for basic operation. Optional:

PORT - Server port (Railway sets this automatically)
NODE_ENV - Set to production in Railway

Testing

Test health endpoint:

curl http://localhost:3001/health

Test tool loading:

curl -X POST http://localhost:3001/load-and-describe \
  -H "Content-Type: application/json" \
  -d '{
    "packageName": "@tpmjs/hello",
    "exportName": "helloWorldTool",
    "version": "0.1.0"
  }'

Test tool execution:

curl -X POST http://localhost:3001/execute-tool \
  -H "Content-Type: application/json" \
  -d '{
    "packageName": "@tpmjs/hello",
    "exportName": "helloWorldTool",
    "version": "0.1.0",
    "params": {}
  }'

Integration with Playground

The playground app calls this service to load and execute tools dynamically.

Set in playground environment:

RAILWAY_SERVICE_URL=https://your-service.up.railway.app

Or use existing:

SANDBOX_EXECUTOR_URL=https://your-service.up.railway.app