Ajax Davis d597a71eb4 feat: add dynamic tool loading system with Railway executor

Implements a complete dynamic tool loading system that allows the playground to discover and load tools from the TPMJS registry at runtime.

**Architecture:**
- Search tool package (@tpmjs/search-registry) - Searches registry for tools
- Search API endpoint (/api/tools/search) - Text-based search with scoring
- Pre-flight tool loading - Automatically searches and loads tools on every message
- Railway executor service (Deno) - Loads tools from esm.sh via HTTP imports
- Dynamic tool loader - Calls Railway to load and execute tools remotely

**Key Components:**

1. Railway Executor (apps/railway-executor/)
   - Deno-based service that natively supports HTTP imports
   - Endpoints: /load-and-describe, /execute-tool, /cache/stats, /cache/clear
   - Deploys to Railway with deno run --allow-net --allow-env server.ts

2. Search Tool Package (packages/tools/search-registry/)
   - AI SDK v6 tool for searching TPMJS registry
   - Uses jsonSchema + inputSchema pattern
   - Searches /api/tools/search endpoint

3. Search API (apps/web/src/app/api/tools/search/)
   - Text-based search with composite scoring
   - Scores: text relevance + quality boost + download boost
   - Returns tool metadata with importUrl for dynamic loading

4. Dynamic Tool Loader (apps/playground/src/lib/dynamic-tool-loader.ts)
   - Calls Railway service to load tools from esm.sh
   - Creates tool wrappers that execute remotely
   - Process-level module cache + per-conversation tracking

5. Pre-flight Loading (apps/playground/src/app/api/chat/route.ts)
   - Automatically searches for tools on every user message
   - Loads top 5 matching tools before agent processes request
   - Merges with static tools for seamless experience

**Technical Decisions:**
- Deno over Node.js: Native HTTP import support without flags
- Remote execution: Tools run in Railway sandbox, not Vercel
- Pre-flight loading: Better UX than two-turn search pattern
- Text search: BM25 had dependency issues, simple scoring works well

**Environment Variables:**
- RAILWAY_SERVICE_URL: https://endearing-commitment-production.up.railway.app

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

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

2025-12-04 08:25:53 +10:00

2.8 KiB

Raw Blame History

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

2.8 KiB Raw Blame History