@supertools-ai/core 0.1.4 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +214 -127
- package/dist/constants.d.ts +6 -0
- package/dist/constants.d.ts.map +1 -0
- package/dist/executor.d.ts +7 -4
- package/dist/executor.d.ts.map +1 -1
- package/dist/index.d.ts +4 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +595 -299
- package/dist/mcp/host-server.d.ts +69 -0
- package/dist/mcp/host-server.d.ts.map +1 -0
- package/dist/mcp/index.d.ts +11 -0
- package/dist/mcp/index.d.ts.map +1 -0
- package/dist/mcp/prompts.d.ts +13 -0
- package/dist/mcp/prompts.d.ts.map +1 -0
- package/dist/mcp/types.d.ts +156 -0
- package/dist/mcp/types.d.ts.map +1 -0
- package/dist/mcp/zod-to-mcp.d.ts +23 -0
- package/dist/mcp/zod-to-mcp.d.ts.map +1 -0
- package/dist/providers/anthropic.d.ts.map +1 -1
- package/dist/relay/client.d.ts +2 -0
- package/dist/relay/client.d.ts.map +1 -1
- package/dist/supertools.d.ts +3 -3
- package/dist/tool.d.ts +1 -0
- package/dist/tool.d.ts.map +1 -1
- package/dist/types.d.ts +0 -2
- package/dist/types.d.ts.map +1 -1
- package/package.json +1 -1
- package/dist/prompts.d.ts +0 -7
- package/dist/prompts.d.ts.map +0 -1
package/README.md
CHANGED
|
@@ -50,112 +50,269 @@ User Request → LLM generates code → Sandbox executes → Result
|
|
|
50
50
|
bun add @supertools-ai/core @anthropic-ai/sdk e2b
|
|
51
51
|
```
|
|
52
52
|
|
|
53
|
-
Create a `.env` file with your API keys:
|
|
54
53
|
```bash
|
|
55
|
-
|
|
56
|
-
|
|
54
|
+
# .env
|
|
55
|
+
ANTHROPIC_API_KEY=your-key # console.anthropic.com
|
|
56
|
+
E2B_API_KEY=your-key # e2b.dev
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
|
|
59
|
+
### 1. Define a tool
|
|
60
60
|
|
|
61
61
|
```typescript
|
|
62
|
-
import {
|
|
63
|
-
import { Sandbox } from 'e2b';
|
|
64
|
-
import Anthropic from '@anthropic-ai/sdk';
|
|
62
|
+
import { defineTool, z } from '@supertools-ai/core';
|
|
65
63
|
|
|
66
|
-
// Sample data
|
|
67
64
|
const orders = [
|
|
68
65
|
{ id: 1, customer: 'Alice', total: 150, status: 'completed' },
|
|
69
66
|
{ id: 2, customer: 'Bob', total: 75, status: 'pending' },
|
|
70
|
-
{ id: 3, customer: 'Alice', total: 200, status: 'completed' },
|
|
71
|
-
{ id: 4, customer: 'Charlie', total: 50, status: 'completed' },
|
|
72
67
|
];
|
|
73
68
|
|
|
74
|
-
// Define tools with Zod schemas
|
|
75
69
|
const getOrders = defineTool({
|
|
76
70
|
name: 'getOrders',
|
|
77
71
|
description: 'Get orders, optionally filtered by status',
|
|
78
72
|
parameters: z.object({
|
|
79
73
|
status: z.enum(['pending', 'completed']).optional(),
|
|
80
74
|
}),
|
|
81
|
-
returns: z.array(z.object({
|
|
82
|
-
id: z.number(),
|
|
83
|
-
customer: z.string(),
|
|
84
|
-
total: z.number(),
|
|
85
|
-
status: z.string(),
|
|
86
|
-
})),
|
|
87
75
|
execute: async ({ status }) =>
|
|
88
76
|
status ? orders.filter(o => o.status === status) : orders,
|
|
89
77
|
});
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
### 2. Wrap your client
|
|
81
|
+
|
|
82
|
+
```typescript
|
|
83
|
+
import { supertools, SANDBOX_TEMPLATE } from '@supertools-ai/core';
|
|
84
|
+
import { Sandbox } from 'e2b';
|
|
85
|
+
import Anthropic from '@anthropic-ai/sdk';
|
|
86
|
+
|
|
87
|
+
const sandbox = await Sandbox.create(SANDBOX_TEMPLATE);
|
|
90
88
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
89
|
+
const client = supertools(new Anthropic(), {
|
|
90
|
+
tools: [getOrders],
|
|
91
|
+
sandbox,
|
|
92
|
+
onEvent: (e) => {
|
|
93
|
+
if (e.type === 'result') console.log('Result:', e.data);
|
|
94
|
+
},
|
|
95
95
|
});
|
|
96
|
+
```
|
|
96
97
|
|
|
97
|
-
|
|
98
|
-
const client = supertools(new Anthropic(), {
|
|
99
|
-
tools: [getOrders],
|
|
100
|
-
sandbox,
|
|
101
|
-
onEvent: (e) => {
|
|
102
|
-
if (e.type === 'tool_call') console.log(`→ ${e.tool}()`);
|
|
103
|
-
if (e.type === 'result') console.log('Result:', e.data);
|
|
104
|
-
},
|
|
105
|
-
});
|
|
98
|
+
### 3. Use it like normal
|
|
106
99
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
}
|
|
115
|
-
}
|
|
116
|
-
|
|
117
|
-
|
|
100
|
+
```typescript
|
|
101
|
+
await client.messages.create({
|
|
102
|
+
model: 'claude-sonnet-4-5',
|
|
103
|
+
max_tokens: 1024,
|
|
104
|
+
messages: [{
|
|
105
|
+
role: 'user',
|
|
106
|
+
content: 'Get completed orders and calculate total revenue',
|
|
107
|
+
}],
|
|
108
|
+
});
|
|
109
|
+
|
|
110
|
+
await sandbox.kill(); // Clean up when done
|
|
118
111
|
```
|
|
119
112
|
|
|
120
|
-
**What happens:** The LLM writes code that calls `getOrders()`,
|
|
113
|
+
**What happens:** The LLM writes code that calls `getOrders()`, filters results, and calculates the sum — all in one API call.
|
|
121
114
|
|
|
122
115
|
## How It Works
|
|
123
116
|
|
|
124
117
|
When you ask: *"Query sales for all 50 states, find top 5, email a report"*
|
|
125
118
|
|
|
126
|
-
|
|
119
|
+
### Traditional Tool Calling
|
|
120
|
+
|
|
121
|
+
The LLM calls tools one by one, each requiring an API round-trip:
|
|
122
|
+
|
|
123
|
+
```
|
|
124
|
+
User: "Query sales for all 50 states..."
|
|
125
|
+
↓
|
|
126
|
+
LLM → tool_use: query_database({state: 'AL'}) → API call #1
|
|
127
|
+
↓ result goes back to LLM context
|
|
128
|
+
LLM → tool_use: query_database({state: 'AK'}) → API call #2
|
|
129
|
+
↓ result goes back to LLM context
|
|
130
|
+
... 48 more API calls, all results accumulating in context ...
|
|
131
|
+
↓
|
|
132
|
+
LLM → tool_use: send_email({...}) → API call #51
|
|
133
|
+
↓
|
|
134
|
+
LLM: "Done! Here's your report..." → API call #52
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
**Problems:** 52 API calls, all 50 query results in LLM context (expensive), slow.
|
|
138
|
+
|
|
139
|
+
### With Supertools
|
|
140
|
+
|
|
141
|
+
The LLM generates code once, which runs in a sandbox:
|
|
142
|
+
|
|
143
|
+
```
|
|
144
|
+
User: "Query sales for all 50 states..."
|
|
145
|
+
↓
|
|
146
|
+
LLM generates JavaScript → API call #1
|
|
147
|
+
↓
|
|
148
|
+
Sandbox executes code:
|
|
149
|
+
├── query_database('AL') ─┐
|
|
150
|
+
├── query_database('AK') ├── WebSocket (fast, parallel)
|
|
151
|
+
├── ... 48 more ... │
|
|
152
|
+
├── send_email() ─┘
|
|
153
|
+
└── return { topStates, reportSent }
|
|
154
|
+
↓
|
|
155
|
+
Result returned to your app → Done!
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
**The generated code:**
|
|
127
159
|
|
|
128
160
|
```javascript
|
|
129
|
-
// All 50 queries execute without LLM round-trips
|
|
130
161
|
const states = ['AL', 'AK', 'AZ', /* ... all 50 */];
|
|
131
162
|
const results = {};
|
|
132
163
|
|
|
133
164
|
for (const state of states) {
|
|
134
|
-
|
|
135
|
-
const data = await query_database({
|
|
165
|
+
const data = await mcp.call('host.query_database', {
|
|
136
166
|
sql: `SELECT SUM(revenue) FROM sales WHERE state = '${state}'`
|
|
137
167
|
});
|
|
138
168
|
results[state] = data[0].sum;
|
|
139
169
|
}
|
|
140
170
|
|
|
141
|
-
// Process data locally (no tokens consumed)
|
|
142
171
|
const top5 = Object.entries(results)
|
|
143
172
|
.sort((a, b) => b[1] - a[1])
|
|
144
173
|
.slice(0, 5);
|
|
145
174
|
|
|
146
|
-
|
|
147
|
-
const report = top5.map(([state, rev]) => `${state}: $${rev.toLocaleString()}`).join('\n');
|
|
148
|
-
await send_email({
|
|
175
|
+
await mcp.call('host.send_email', {
|
|
149
176
|
to: 'ceo@company.com',
|
|
150
177
|
subject: 'Top 5 States Report',
|
|
151
|
-
body:
|
|
178
|
+
body: top5.map(([state, rev]) => `${state}: $${rev}`).join('\n')
|
|
152
179
|
});
|
|
153
180
|
|
|
154
|
-
// Return the result as JSON
|
|
155
181
|
return { topStates: top5, reportSent: true };
|
|
156
182
|
```
|
|
157
183
|
|
|
158
|
-
**Result:**
|
|
184
|
+
**Result:** 1 API call, 51 tool executions via WebSocket, data processing in sandbox (free), only final result returned.
|
|
185
|
+
|
|
186
|
+
## Architecture
|
|
187
|
+
|
|
188
|
+
```
|
|
189
|
+
┌───────────────────────────────────────────────────────────────────┐
|
|
190
|
+
│ Your Application │
|
|
191
|
+
│ │
|
|
192
|
+
│ const client = supertools(new Anthropic(), { tools, sandbox }); │
|
|
193
|
+
│ const response = await client.messages.create({...}); │
|
|
194
|
+
└─────────────────────────────────┬─────────────────────────────────┘
|
|
195
|
+
│
|
|
196
|
+
▼
|
|
197
|
+
┌────────────────────────────┐
|
|
198
|
+
│ Supertools Wrapper │
|
|
199
|
+
│ (intercepts SDK calls) │
|
|
200
|
+
└──────────────┬─────────────┘
|
|
201
|
+
│ LLM generates JavaScript
|
|
202
|
+
▼
|
|
203
|
+
┌───────────────────────────────────────────────────────────────────┐
|
|
204
|
+
│ E2B Cloud Sandbox │
|
|
205
|
+
│ ┌─────────────────────────────────────────────────────────────┐ │
|
|
206
|
+
│ │ Generated Code │ │
|
|
207
|
+
│ │ │ │
|
|
208
|
+
│ │ const [orders, users] = await Promise.all([ │ │
|
|
209
|
+
│ │ mcp.call('host.get_orders', {}), │ │
|
|
210
|
+
│ │ mcp.call('host.get_users', {}) │ │
|
|
211
|
+
│ │ ]); │ │
|
|
212
|
+
│ │ return { orders, users }; │ │
|
|
213
|
+
│ │ │ │
|
|
214
|
+
│ └────────────────────────────┬────────────────────────────────┘ │
|
|
215
|
+
│ │ tool calls via WebSocket │
|
|
216
|
+
│ ┌────────────────────────────▼────────────────────────────────┐ │
|
|
217
|
+
│ │ Relay Server (Bun) │ │
|
|
218
|
+
│ │ WebSocket bridge to host │ │
|
|
219
|
+
│ └────────────────────────────┬────────────────────────────────┘ │
|
|
220
|
+
└───────────────────────────────┼───────────────────────────────────┘
|
|
221
|
+
│ WebSocket (authenticated)
|
|
222
|
+
▼
|
|
223
|
+
┌────────────────────────────┐
|
|
224
|
+
│ Relay Client │
|
|
225
|
+
│ (runs on your host) │
|
|
226
|
+
└──────────────┬─────────────┘
|
|
227
|
+
│
|
|
228
|
+
▼
|
|
229
|
+
┌────────────────────────────┐
|
|
230
|
+
│ Your Tools │
|
|
231
|
+
│ get_orders, get_users │
|
|
232
|
+
│ (execute locally) │
|
|
233
|
+
└────────────────────────────┘
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
**Step by step:**
|
|
237
|
+
|
|
238
|
+
1. You wrap your SDK client with `supertools()`
|
|
239
|
+
2. When you call `client.messages.create()`, supertools intercepts it
|
|
240
|
+
3. The LLM generates JavaScript code that uses `mcp.call()` for tools
|
|
241
|
+
4. Code runs in an isolated E2B sandbox (secure, no host access)
|
|
242
|
+
5. Tool calls relay back to your machine via WebSocket
|
|
243
|
+
6. Your tools execute locally with full access to your systems
|
|
244
|
+
7. Results flow back to the sandbox, code continues executing
|
|
245
|
+
8. Final output returns in the expected SDK response format
|
|
246
|
+
|
|
247
|
+
**Security:**
|
|
248
|
+
|
|
249
|
+
- LLM-generated code runs in isolated cloud containers
|
|
250
|
+
- Your tools run locally — the sandbox never has direct access
|
|
251
|
+
- WebSocket authenticated with cryptographically secure tokens
|
|
252
|
+
- Tokens are single-use and expire with the sandbox
|
|
253
|
+
|
|
254
|
+
> **Note:** The Relay Server runs inside the pre-built `SANDBOX_TEMPLATE`. The Relay Client is included in `@supertools-ai/core` and runs on your host.
|
|
255
|
+
|
|
256
|
+
## MCP Under the Hood
|
|
257
|
+
|
|
258
|
+
Supertools uses the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) internally as a unified interface for tool communication. Here's why and how:
|
|
259
|
+
|
|
260
|
+
### Why MCP?
|
|
261
|
+
|
|
262
|
+
MCP provides a standardized way to expose tools to LLMs. Instead of inventing a custom protocol, Supertools converts your Zod-defined tools into MCP format:
|
|
263
|
+
|
|
264
|
+
```
|
|
265
|
+
Your Tool (Zod) → MCP Tool Definition → LLM sees it → Generates mcp.call()
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
### How tools are exposed
|
|
269
|
+
|
|
270
|
+
When you define a tool with `defineTool()`, it gets converted to MCP format with:
|
|
271
|
+
- **Name**: `host.your_tool_name` (prefixed with server name)
|
|
272
|
+
- **Description**: Your tool's description
|
|
273
|
+
- **Input schema**: JSON Schema derived from your Zod parameters
|
|
274
|
+
- **Output schema**: JSON Schema from your `returns` Zod schema (if provided)
|
|
275
|
+
|
|
276
|
+
The LLM then generates code using the `mcp.call()` pattern:
|
|
277
|
+
|
|
278
|
+
```javascript
|
|
279
|
+
// Your tool: getOrders
|
|
280
|
+
// Becomes: mcp.call('host.get_orders', { status: 'completed' })
|
|
281
|
+
|
|
282
|
+
const [orders, users] = await Promise.all([
|
|
283
|
+
mcp.call('host.get_orders', { status: 'completed' }),
|
|
284
|
+
mcp.call('host.get_users', {})
|
|
285
|
+
]);
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
### Host vs Local tools
|
|
289
|
+
|
|
290
|
+
Tools can run in two places:
|
|
291
|
+
|
|
292
|
+
| Type | Prefix | Where it runs | Use case |
|
|
293
|
+
|------|--------|---------------|----------|
|
|
294
|
+
| **Host** | `host.` | Your machine | DB queries, API calls, secrets |
|
|
295
|
+
| **Local** | `local.` | In sandbox | Pure computation, data transforms |
|
|
296
|
+
|
|
297
|
+
```typescript
|
|
298
|
+
// Host tool - runs on your machine (default)
|
|
299
|
+
const queryDb = defineTool({
|
|
300
|
+
name: 'queryDb',
|
|
301
|
+
execute: async ({ sql }) => db.query(sql), // Has access to your DB
|
|
302
|
+
});
|
|
303
|
+
|
|
304
|
+
// Local tool - runs in sandbox (no network round-trip)
|
|
305
|
+
const calculateStats = defineTool({
|
|
306
|
+
name: 'calculateStats',
|
|
307
|
+
local: true, // ← This makes it local
|
|
308
|
+
execute: async ({ values }) => ({
|
|
309
|
+
sum: values.reduce((a, b) => a + b, 0),
|
|
310
|
+
mean: values.reduce((a, b) => a + b, 0) / values.length,
|
|
311
|
+
}),
|
|
312
|
+
});
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
Local tools are faster because they don't need a WebSocket round-trip back to your host. Use them for pure computation when all data is already in the sandbox.
|
|
159
316
|
|
|
160
317
|
## Why Supertools?
|
|
161
318
|
|
|
@@ -179,11 +336,11 @@ The benchmark compares three approaches on the same model (Claude Sonnet 4.5):
|
|
|
179
336
|
Wrap any supported LLM SDK client with programmatic tool calling.
|
|
180
337
|
|
|
181
338
|
```typescript
|
|
182
|
-
import { supertools, defineTool, z } from '@supertools-ai/core';
|
|
339
|
+
import { supertools, defineTool, z, SANDBOX_TEMPLATE } from '@supertools-ai/core';
|
|
183
340
|
import { Sandbox } from 'e2b';
|
|
184
341
|
import Anthropic from '@anthropic-ai/sdk';
|
|
185
342
|
|
|
186
|
-
const sandbox = await Sandbox.create(
|
|
343
|
+
const sandbox = await Sandbox.create(SANDBOX_TEMPLATE);
|
|
187
344
|
const client = supertools(new Anthropic(), {
|
|
188
345
|
// Required
|
|
189
346
|
tools: [defineTool({ name, description, parameters, execute })],
|
|
@@ -259,7 +416,7 @@ const calculateStats = defineTool({
|
|
|
259
416
|
For more control, use the executor directly:
|
|
260
417
|
|
|
261
418
|
```typescript
|
|
262
|
-
import { createExecutor, defineTool } from '@supertools-ai/core';
|
|
419
|
+
import { createExecutor, defineTool, SANDBOX_TEMPLATE } from '@supertools-ai/core';
|
|
263
420
|
import { Sandbox } from 'e2b';
|
|
264
421
|
|
|
265
422
|
// Create your own LLM adapter
|
|
@@ -270,7 +427,7 @@ const myAdapter = {
|
|
|
270
427
|
},
|
|
271
428
|
};
|
|
272
429
|
|
|
273
|
-
const sandbox = await Sandbox.create(
|
|
430
|
+
const sandbox = await Sandbox.create(SANDBOX_TEMPLATE);
|
|
274
431
|
const executor = createExecutor({
|
|
275
432
|
llm: myAdapter,
|
|
276
433
|
tools: [/* your tools */],
|
|
@@ -282,76 +439,6 @@ console.log(result.code); // Generated JavaScript
|
|
|
282
439
|
console.log(result.result.output); // stdout from execution
|
|
283
440
|
```
|
|
284
441
|
|
|
285
|
-
## Architecture
|
|
286
|
-
|
|
287
|
-
```
|
|
288
|
-
┌───────────────────────────────────────────────────────────────────┐
|
|
289
|
-
│ Your Application │
|
|
290
|
-
│ │
|
|
291
|
-
│ const client = supertools(new Anthropic(), { tools, sandbox }); │
|
|
292
|
-
│ const response = await client.messages.create({...}); │
|
|
293
|
-
└─────────────────────────────────┬─────────────────────────────────┘
|
|
294
|
-
│
|
|
295
|
-
▼
|
|
296
|
-
┌────────────────────────────┐
|
|
297
|
-
│ Supertools Wrapper │
|
|
298
|
-
│ (intercepts SDK calls) │
|
|
299
|
-
└──────────────┬─────────────┘
|
|
300
|
-
│ generates JavaScript
|
|
301
|
-
▼
|
|
302
|
-
┌───────────────────────────────────────────────────────────────────┐
|
|
303
|
-
│ E2B Cloud Sandbox │
|
|
304
|
-
│ ┌─────────────────────────────────────────────────────────────┐ │
|
|
305
|
-
│ │ Generated Code │ │
|
|
306
|
-
│ │ │ │
|
|
307
|
-
│ │ for (const r of regions) { │ │
|
|
308
|
-
│ │ const data = await query_db({ region: r }); │ │
|
|
309
|
-
│ │ results.push(data); │ │
|
|
310
|
-
│ │ } │ │
|
|
311
|
-
│ │ await send_email({ to: 'ceo', body: summary }); │ │
|
|
312
|
-
│ │ return { regions: results, emailSent: true }; │ │
|
|
313
|
-
│ │ │ │
|
|
314
|
-
│ └────────────────────────────┬────────────────────────────────┘ │
|
|
315
|
-
│ │ tool calls via WebSocket │
|
|
316
|
-
│ ┌────────────────────────────▼────────────────────────────────┐ │
|
|
317
|
-
│ │ Relay Server (Bun) │ │
|
|
318
|
-
│ │ WebSocket bridge to host │ │
|
|
319
|
-
│ └────────────────────────────┬────────────────────────────────┘ │
|
|
320
|
-
└───────────────────────────────┼───────────────────────────────────┘
|
|
321
|
-
│ WebSocket (authenticated)
|
|
322
|
-
▼
|
|
323
|
-
┌────────────────────────────┐
|
|
324
|
-
│ Relay Client │
|
|
325
|
-
│ (runs on your host) │
|
|
326
|
-
└──────────────┬─────────────┘
|
|
327
|
-
│
|
|
328
|
-
▼
|
|
329
|
-
┌────────────────────────────┐
|
|
330
|
-
│ Your Tools │
|
|
331
|
-
│ query_db, send_email │
|
|
332
|
-
│ (execute locally) │
|
|
333
|
-
└────────────────────────────┘
|
|
334
|
-
```
|
|
335
|
-
|
|
336
|
-
**How it works:**
|
|
337
|
-
|
|
338
|
-
1. You wrap your SDK client with `supertools()`
|
|
339
|
-
2. When you call `client.messages.create()`, supertools intercepts it
|
|
340
|
-
3. The LLM generates JavaScript code that calls your tools
|
|
341
|
-
4. Code runs in an isolated E2B sandbox (secure, no host access)
|
|
342
|
-
5. Tool calls are relayed back to your machine via WebSocket
|
|
343
|
-
6. Your tools execute locally with full access to your systems
|
|
344
|
-
7. Results flow back to the sandbox, code continues executing
|
|
345
|
-
8. Final output returns in the expected SDK response format
|
|
346
|
-
|
|
347
|
-
> **Note:** The Relay Server runs inside the pre-built `supertools-bun-014` E2B template. The Relay Client is included in the `@supertools-ai/core` package and runs on your host.
|
|
348
|
-
|
|
349
|
-
**Security:**
|
|
350
|
-
- LLM-generated code runs in isolated cloud containers
|
|
351
|
-
- Your tools run locally — the sandbox never has direct access
|
|
352
|
-
- WebSocket authenticated with cryptographically secure tokens
|
|
353
|
-
- Tokens are single-use and expire with the sandbox
|
|
354
|
-
|
|
355
442
|
## When to Use
|
|
356
443
|
|
|
357
444
|
**Use Supertools when:**
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,uBAAuB,CAAC"}
|
package/dist/executor.d.ts
CHANGED
|
@@ -2,32 +2,35 @@
|
|
|
2
2
|
* Programmatic Executor
|
|
3
3
|
*
|
|
4
4
|
* Orchestrates the complete flow:
|
|
5
|
-
* 1. LLM generates JavaScript code
|
|
5
|
+
* 1. LLM generates JavaScript code using MCP tool definitions
|
|
6
6
|
* 2. Code executes in secure E2B Bun sandbox
|
|
7
|
-
* 3. Tool calls relay back to host via
|
|
7
|
+
* 3. Tool calls relay back to host via MCP router
|
|
8
8
|
* 4. Results return to user
|
|
9
9
|
*/
|
|
10
10
|
import type { NormalizedTool } from './tool';
|
|
11
11
|
import type { ExecutorConfig, ExecutionResult, ProgrammaticResult, LLMAdapter } from './types';
|
|
12
|
+
import { type McpTool } from './mcp';
|
|
12
13
|
export interface CreateExecutorOptions extends ExecutorConfig {
|
|
13
14
|
readonly llm: LLMAdapter;
|
|
14
15
|
}
|
|
15
16
|
export declare function createExecutor(options: CreateExecutorOptions): ProgrammaticExecutor;
|
|
16
17
|
export declare class ProgrammaticExecutor {
|
|
17
|
-
private readonly originalTools;
|
|
18
18
|
private readonly normalizedTools;
|
|
19
|
+
private readonly mcpTools;
|
|
19
20
|
private readonly toolsMap;
|
|
20
21
|
private readonly llm;
|
|
21
22
|
private readonly sandbox;
|
|
22
|
-
private readonly instructions?;
|
|
23
23
|
private readonly debug;
|
|
24
24
|
private readonly onEvent?;
|
|
25
|
+
private readonly systemPrompt;
|
|
26
|
+
private readonly localToolsCache;
|
|
25
27
|
constructor(options: CreateExecutorOptions);
|
|
26
28
|
private emit;
|
|
27
29
|
run(userRequest: string): Promise<ProgrammaticResult>;
|
|
28
30
|
executeCode(code: string): Promise<ExecutionResult>;
|
|
29
31
|
private executeCodeWithRelay;
|
|
30
32
|
getTools(): readonly NormalizedTool[];
|
|
33
|
+
getMcpTools(): readonly McpTool[];
|
|
31
34
|
getToolDocumentation(): string;
|
|
32
35
|
private generateCode;
|
|
33
36
|
private connectRelay;
|
package/dist/executor.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;
|
|
1
|
+
{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAE7C,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,kBAAkB,EAAE,UAAU,EAAkB,MAAM,SAAS,CAAC;AAC/G,OAAO,EAAoD,KAAK,OAAO,EAAE,MAAM,OAAO,CAAC;AAEvF,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;CAC1B;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,oBAAoB,CAEnF;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAmB;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAY;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IACvD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;gBAE7C,OAAO,EAAE,qBAAqB;IAgB1C,OAAO,CAAC,IAAI;IAIN,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAgDrD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;YAW3C,oBAAoB;IA2ClC,QAAQ,IAAI,SAAS,cAAc,EAAE;IAIrC,WAAW,IAAI,SAAS,OAAO,EAAE;IAIjC,oBAAoB,IAAI,MAAM;YAIhB,YAAY;YA6BZ,YAAY;YA2BZ,OAAO;IAcrB,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,SAAS;CAMlB"}
|
package/dist/index.d.ts
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
*
|
|
7
7
|
* @example
|
|
8
8
|
* ```ts
|
|
9
|
-
* import { supertools, defineTool, z } from '@supertools-ai/core';
|
|
9
|
+
* import { supertools, defineTool, z, SANDBOX_TEMPLATE } from '@supertools-ai/core';
|
|
10
10
|
* import { Sandbox } from 'e2b';
|
|
11
11
|
* import Anthropic from '@anthropic-ai/sdk';
|
|
12
12
|
*
|
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
* });
|
|
21
21
|
*
|
|
22
22
|
* // Create sandbox and wrap your SDK client
|
|
23
|
-
* const sandbox = await Sandbox.create(
|
|
23
|
+
* const sandbox = await Sandbox.create(SANDBOX_TEMPLATE);
|
|
24
24
|
* const client = supertools(new Anthropic(), { tools: [queryDb], sandbox });
|
|
25
25
|
*
|
|
26
26
|
* // Use exactly like normal - tools execute automatically
|
|
@@ -33,6 +33,7 @@
|
|
|
33
33
|
*
|
|
34
34
|
* @packageDocumentation
|
|
35
35
|
*/
|
|
36
|
+
export { SANDBOX_TEMPLATE } from './constants';
|
|
36
37
|
export { supertools, detectProvider } from './supertools';
|
|
37
38
|
export type { SupertoolsConfig, SupportedProvider } from './supertools';
|
|
38
39
|
export { defineTool, z } from './tool';
|
|
@@ -41,8 +42,8 @@ export { createExecutor, ProgrammaticExecutor } from './executor';
|
|
|
41
42
|
export type { CreateExecutorOptions } from './executor';
|
|
42
43
|
export type { ToolCollection, ExecutionResult, GeneratedCode, ProgrammaticResult, ToolCallRequest, ToolCallResponse, LLMAdapter, ExecutorConfig, ExecutionEvent, } from './types';
|
|
43
44
|
export { OPTError, CodeGenerationError, ExecutionError, ToolError, RelayConnectionError, RelayTimeoutError, SandboxError, ConfigurationError, } from './utils/errors';
|
|
44
|
-
export { buildSystemPrompt, extractCode } from './prompts';
|
|
45
45
|
export { generateTypeHints } from './utils/type-hints';
|
|
46
46
|
export { normalizeTools, isTool } from './tool';
|
|
47
47
|
export type { NormalizedTool, NormalizedParameter } from './tool';
|
|
48
|
+
export { zodToolToMcp, zodToolsToMcp, buildMcpSystemPrompt, extractCode, HostMcpServer, createHostMcpServer, type McpTool, type McpServerConfig, type McpToolCallRequest, type McpToolCallResult, type ZodToMcpOptions, type HostMcpServerConfig, type McpEvent, } from './mcp';
|
|
48
49
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC1D,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGxE,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AACvC,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAGnD,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClE,YAAY,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGxD,YAAY,EACV,cAAc,EACd,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,cAAc,GACf,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,QAAQ,EACR,mBAAmB,EACnB,cAAc,EACd,SAAS,EACT,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,iBAAiB,EAAE,
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC1D,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGxE,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AACvC,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAGnD,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClE,YAAY,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGxD,YAAY,EACV,cAAc,EACd,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,cAAc,GACf,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,QAAQ,EACR,mBAAmB,EACnB,cAAc,EACd,SAAS,EACT,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChD,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAGlE,OAAO,EACL,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,mBAAmB,EACnB,KAAK,OAAO,EACZ,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,QAAQ,GACd,MAAM,OAAO,CAAC"}
|