@enclave-vm/broker 2.19.0 → 2.19.2
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 +188 -139
- package/broker-session.d.ts +31 -2
- package/broker.d.ts +15 -1
- package/errors.d.ts +24 -0
- package/esm/index.mjs +1790 -664
- package/event-filter.d.ts +80 -24
- package/http/express-adapter.d.ts +7 -12
- package/http/request-validation.d.ts +84 -0
- package/http/session-handler.d.ts +98 -2
- package/http/types.d.ts +18 -1
- package/index.d.ts +4 -1
- package/index.js +1800 -665
- package/limits.d.ts +32 -0
- package/openapi/http-utils.d.ts +43 -0
- package/openapi/openapi-source.d.ts +29 -1
- package/openapi/openapi-spec-poller.d.ts +2 -0
- package/openapi/openapi-tool-loader.d.ts +22 -0
- package/package.json +5 -5
- package/session-history.d.ts +68 -0
- package/session-manager.d.ts +9 -1
package/README.md
CHANGED
|
@@ -6,196 +6,245 @@
|
|
|
6
6
|
|
|
7
7
|
> Tool broker and session management for the EnclaveJS streaming runtime
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
`@enclave-vm/broker` runs scripts in an [`@enclave-vm/core`](../core) sandbox on a server, gives them the tools you register, and streams what happens as events. It can serve sessions over HTTP for [`@enclave-vm/client`](../client).
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## What it provides
|
|
12
12
|
|
|
13
|
-
- **
|
|
14
|
-
- **
|
|
15
|
-
- **
|
|
16
|
-
- **
|
|
17
|
-
- **
|
|
18
|
-
|
|
13
|
+
- **A tool registry**: tools with a Zod schema for their arguments, and secrets that only tool handlers see.
|
|
14
|
+
- **Sessions**: one sandbox per session, with limits (tool calls, lifetime, deadline, per-tool timeout) and a stream of events (`session_init`, `tool_call`, `tool_progress`, `tool_result_applied`, `partial_result`, `heartbeat`, `final`, ...).
|
|
15
|
+
- **HTTP routes** for creating, reading, replaying and ending sessions, with an adapter for Express.
|
|
16
|
+
- **Event filters** that decide which events a client is sent.
|
|
17
|
+
- **Tools from an OpenAPI specification**, kept up to date by polling.
|
|
18
|
+
|
|
19
|
+
It does not provide authentication, rate limiting or transport encryption. Authentication is yours to put in front of the routes; the routes can then bind every session to its caller (see [Who may see a session](#who-may-see-a-session)).
|
|
19
20
|
|
|
20
21
|
## Installation
|
|
21
22
|
|
|
22
23
|
```bash
|
|
23
24
|
npm install @enclave-vm/broker
|
|
24
|
-
# or
|
|
25
|
-
yarn add @enclave-vm/broker
|
|
26
|
-
# or
|
|
27
|
-
pnpm add @enclave-vm/broker
|
|
28
25
|
```
|
|
29
26
|
|
|
30
|
-
## Quick
|
|
27
|
+
## Quick start
|
|
31
28
|
|
|
32
29
|
```typescript
|
|
33
|
-
import {
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
const broker =
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
'users:list': async () => {
|
|
42
|
-
return [
|
|
43
|
-
{ id: 1, name: 'Alice' },
|
|
44
|
-
{ id: 2, name: 'Bob' },
|
|
45
|
-
];
|
|
46
|
-
},
|
|
47
|
-
},
|
|
30
|
+
import { createBroker } from '@enclave-vm/broker';
|
|
31
|
+
import { z } from 'zod';
|
|
32
|
+
|
|
33
|
+
const broker = createBroker({
|
|
34
|
+
// Options of the sandbox go under `enclave`
|
|
35
|
+
enclave: { securityLevel: 'SECURE' },
|
|
36
|
+
// Limits of every session
|
|
37
|
+
limits: { maxToolCalls: 20, sessionTtlMs: 60_000 },
|
|
48
38
|
});
|
|
49
39
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
40
|
+
broker.secret('API_KEY', process.env.API_KEY!);
|
|
41
|
+
|
|
42
|
+
broker.tool('getUser', {
|
|
43
|
+
description: 'Look a user up by id',
|
|
44
|
+
argsSchema: z.object({ id: z.string() }),
|
|
45
|
+
secrets: ['API_KEY'],
|
|
46
|
+
handler: async ({ id }, { secrets, signal }) => {
|
|
47
|
+
const response = await fetch(`https://api.example.com/users/${encodeURIComponent(id)}`, {
|
|
48
|
+
headers: { Authorization: `Bearer ${secrets.API_KEY}` },
|
|
49
|
+
signal,
|
|
50
|
+
});
|
|
51
|
+
return response.json();
|
|
52
|
+
},
|
|
55
53
|
});
|
|
56
54
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
const
|
|
60
|
-
|
|
61
|
-
|
|
55
|
+
const result = await broker.execute(
|
|
56
|
+
`
|
|
57
|
+
const user = await callTool('getUser', { id: '42' });
|
|
58
|
+
return user.name;
|
|
59
|
+
`,
|
|
60
|
+
{ onEvent: (event) => console.log(event.type) },
|
|
61
|
+
);
|
|
62
|
+
|
|
63
|
+
if (result.success) console.log(result.value);
|
|
64
|
+
|
|
65
|
+
await broker.dispose();
|
|
62
66
|
```
|
|
63
67
|
|
|
64
|
-
|
|
68
|
+
`createBroker` reads `sessions`, `enclave`, `limits` and `history`. A key it does not know is ignored and reported with a warning: a sandbox option such as `securityLevel` has no effect at the top level.
|
|
65
69
|
|
|
66
|
-
|
|
67
|
-
import { SessionManager } from '@enclave-vm/broker';
|
|
70
|
+
## Serving sessions over HTTP
|
|
68
71
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
72
|
+
```typescript
|
|
73
|
+
import express from 'express';
|
|
74
|
+
import { createBroker, createSessionHandler, registerExpressRoutes } from '@enclave-vm/broker';
|
|
75
|
+
|
|
76
|
+
const broker = createBroker();
|
|
77
|
+
const handler = createSessionHandler({
|
|
78
|
+
broker,
|
|
79
|
+
// Who is calling? See "Who may see a session".
|
|
80
|
+
identify: (request) => (request.raw as { user?: { id: string } }).user?.id,
|
|
81
|
+
allowedOrigins: ['https://app.example.com'],
|
|
73
82
|
});
|
|
74
83
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
84
|
+
const app = express();
|
|
85
|
+
app.use(express.json({ limit: '1mb' }));
|
|
86
|
+
app.use(authenticate); // your authentication, before the routes
|
|
87
|
+
registerExpressRoutes(app, handler);
|
|
88
|
+
app.listen(3000);
|
|
89
|
+
```
|
|
80
90
|
|
|
81
|
-
|
|
82
|
-
|
|
91
|
+
| Route | What it does |
|
|
92
|
+
| ---------------------------------- | ----------------------------------------------------------------------------------------- |
|
|
93
|
+
| `POST /sessions` | Creates a session, runs `code`, answers with the events as NDJSON until the `final` event |
|
|
94
|
+
| `GET /sessions` | Lists sessions (`sessionList: false` switches it off) |
|
|
95
|
+
| `GET /sessions/:sessionId` | State of one session |
|
|
96
|
+
| `GET /sessions/:sessionId/stream` | Replays the kept events from `?fromSeq=N` on and follows the session until it ends |
|
|
97
|
+
| `DELETE /sessions/:sessionId` | Ends a session |
|
|
98
|
+
| `POST /sessions/:sessionId/cancel` | The same; this is the `cancelUrl` a session announces in its `session_init` event |
|
|
99
|
+
|
|
100
|
+
For another framework, call `handler.getRoutes()` and adapt its request and response to `BrokerRequest` and `BrokerResponse`. `createExpressRouter` is deprecated: it registers no route.
|
|
101
|
+
|
|
102
|
+
### The request body of `POST /sessions`
|
|
103
|
+
|
|
104
|
+
```jsonc
|
|
105
|
+
{
|
|
106
|
+
"code": "return 1;",
|
|
107
|
+
"sessionId": "s_...", // optional; generated when left out
|
|
108
|
+
"config": { "maxExecutionMs": 30000, "maxToolCalls": 10, "heartbeatIntervalMs": 15000 }, // optional
|
|
109
|
+
"filter": { "mode": "exclude", "rules": [{ "types": { "types": ["heartbeat"] } }] }, // optional
|
|
110
|
+
}
|
|
111
|
+
```
|
|
83
112
|
|
|
84
|
-
|
|
85
|
-
const sessions = manager.list({ userId: 'user_123' });
|
|
113
|
+
The body is validated as a whole, and a request that does not pass is answered with `400` before a session exists:
|
|
86
114
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
115
|
+
- `config` values are positive integers. A request can **lower** `maxToolCalls` and `maxExecutionMs` (the session's lifetime) and can never raise them above the broker's `limits` (or the package defaults when you set none). `heartbeatIntervalMs` is kept between 1 second and 5 minutes.
|
|
116
|
+
- `sessionId` is `s_` followed by 1 to 128 characters of `A-Z a-z 0-9 . _ : ~ -`. An id that is in use is answered with `409 SESSION_EXISTS`.
|
|
117
|
+
- `filter` is checked against fixed bounds (16 rules, 32 patterns, 256 characters per pattern); see [Event filters](#event-filters).
|
|
118
|
+
- A request with `encryption.mode: "required"` is refused: this broker does not encrypt sessions.
|
|
90
119
|
|
|
91
|
-
|
|
120
|
+
Other answers: `401 UNAUTHORIZED` (no caller identity), `404 NOT_FOUND`, `410 EVENTS_GONE`, `429 TOO_MANY_STREAMS`, `503 MAX_SESSIONS_REACHED`, `500 SESSION_CREATE_ERROR`. An error answer holds a `code` and a fixed `message`.
|
|
92
121
|
|
|
93
|
-
|
|
122
|
+
## Security
|
|
94
123
|
|
|
95
|
-
|
|
96
|
-
import { ToolRouter } from '@enclave-vm/broker';
|
|
124
|
+
### Who may see a session
|
|
97
125
|
|
|
98
|
-
|
|
126
|
+
**Without an `identify` hook the routes do not tell callers apart.** Whoever can reach them can list every session, read its state, replay its events (tool arguments and the final result included) and end it. That is acceptable only where every caller is trusted alike, for example a broker that a single backend talks to. Authentication in front of the routes does not change it: an authenticated caller still reaches the sessions of every other caller.
|
|
99
127
|
|
|
100
|
-
|
|
101
|
-
router.register('db:*', {
|
|
102
|
-
handler: async (name, args) => {
|
|
103
|
-
const operation = name.split(':')[1];
|
|
104
|
-
return await database[operation](args);
|
|
105
|
-
},
|
|
106
|
-
rateLimit: { maxCalls: 100, windowMs: 60000 },
|
|
107
|
-
});
|
|
128
|
+
With `identify`, every session belongs to the caller that created it:
|
|
108
129
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
130
|
+
```typescript
|
|
131
|
+
const handler = createSessionHandler({
|
|
132
|
+
broker,
|
|
133
|
+
identify: (request) => {
|
|
134
|
+
// `request.raw` is the framework's request object, `request.headers` the headers.
|
|
135
|
+
const user = (request.raw as { user?: { id: string } }).user;
|
|
136
|
+
return user?.id; // a stable, non-empty string per caller; nothing when there is none
|
|
112
137
|
},
|
|
113
|
-
requiresAuth: true,
|
|
114
138
|
});
|
|
115
|
-
|
|
116
|
-
// Execute tool call
|
|
117
|
-
const result = await router.execute('db:query', { sql: 'SELECT * FROM users' });
|
|
118
139
|
```
|
|
119
140
|
|
|
120
|
-
|
|
141
|
+
- `GET /sessions` lists the caller's own sessions.
|
|
142
|
+
- Reading, replaying and ending a session is answered only for its owner. Another caller gets `404`, the answer of an id that does not exist.
|
|
143
|
+
- A request for which the hook returns nothing, or throws, is answered with `401`.
|
|
144
|
+
- A session created in process (`broker.createSession()`) has no owner and is not reachable over the routes, unless you pass `owner`.
|
|
121
145
|
|
|
122
|
-
|
|
123
|
-
import { AccessController } from '@enclave-vm/broker';
|
|
124
|
-
|
|
125
|
-
const access = new AccessController({
|
|
126
|
-
defaultPolicy: 'deny',
|
|
127
|
-
rules: [
|
|
128
|
-
{ pattern: 'public:*', allow: true },
|
|
129
|
-
{ pattern: 'admin:*', allow: false, unless: { role: 'admin' } },
|
|
130
|
-
{ pattern: 'user:*:read', allow: true },
|
|
131
|
-
{ pattern: 'user:*:write', allow: false, unless: { owner: true } },
|
|
132
|
-
],
|
|
133
|
-
});
|
|
146
|
+
The hook identifies; it does not authenticate. Verify the credential in your own middleware, or in the hook itself.
|
|
134
147
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
148
|
+
It separates sessions, not data: a tool handler receives its arguments and a context with the id of its session, not the caller. A tool that reads data restricted per caller applies that restriction itself, with the owner of its session (`broker.getSession(context.sessionId as SessionId)?.owner`, the caller the hook returned), or leaves it to the data store.
|
|
149
|
+
|
|
150
|
+
### Cross-origin requests
|
|
151
|
+
|
|
152
|
+
CORS headers are on by default with `Access-Control-Allow-Origin: *`, so a page of any origin can call a broker its visitor's browser can reach, including one on `localhost` or an internal network. Set `allowedOrigins` to the origins of your application, or `cors: false`, for anything that is not a public demo.
|
|
139
153
|
|
|
140
|
-
|
|
154
|
+
A cross-origin page may send `Content-Type`, `Accept`, `Last-Event-ID` and `Authorization`. If your clients send another header (an API-key header through the client's `headers` option, say), name it in `allowedHeaders`: a browser does not send a header the preflight answer does not list.
|
|
141
155
|
|
|
142
|
-
|
|
156
|
+
The routes answer the preflight (`OPTIONS`) themselves, and a browser sends it without the credential: authentication in front of the routes has to let `OPTIONS` requests through to them.
|
|
157
|
+
|
|
158
|
+
### Limits
|
|
159
|
+
|
|
160
|
+
`limits` (see `SessionLimits` in `@enclave-vm/types`) bound every session of a broker. A session created in process may name its own value for a limit; a session created over HTTP may only lower `maxToolCalls` and the lifetime.
|
|
161
|
+
|
|
162
|
+
| Limit | Default | What it bounds |
|
|
163
|
+
| --------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
|
|
164
|
+
| `maxToolCalls` | 50 | Tool calls of one session |
|
|
165
|
+
| `toolTimeoutMs` | 30000 | The run time of the script (it is passed to the sandbox as its timeout) |
|
|
166
|
+
| `perToolDeadlineMs` | 30000 | One tool call: the handler's `signal` is aborted. A tool's own `config.timeout` applies when it is lower |
|
|
167
|
+
| `deadlineMs` | 0 (none) | The whole session, counted from its creation |
|
|
168
|
+
| `sessionTtlMs` | 60000 | How long a session stays registered; a session past it is cancelled at the next cleanup |
|
|
169
|
+
| `maxToolResultBytes` | 5 MB | A tool result, as serialized JSON; a larger one fails the call with `TOOL_RESULT_TOO_LARGE` |
|
|
170
|
+
| `heartbeatIntervalMs` | 15000 | Interval of `heartbeat` events |
|
|
171
|
+
| `cancelOnFirstError` | false | Whether the first failed tool call cancels the session |
|
|
172
|
+
|
|
173
|
+
`maxStdoutBytes` is not used: the broker emits no `stdout` events.
|
|
174
|
+
|
|
175
|
+
`sessions.maxSessions` (default 100) bounds the registered sessions. A finished session stays registered, so that it can be replayed, until the next cleanup (`sessions.cleanupIntervalMs`, default 60 s).
|
|
176
|
+
|
|
177
|
+
What a session keeps and writes is bounded as well:
|
|
178
|
+
|
|
179
|
+
- `history: { maxEvents, maxBytes }` (default 10,000 events and 4 MB) bounds the events a session keeps for a replay. When a bound is reached the oldest events are dropped, and a replay that would start below the kept events is answered with `410 EVENTS_GONE`.
|
|
180
|
+
- `maxStreamsPerSession` (handler option, default 8) bounds the streams one session has open; a further one is answered with `429`.
|
|
181
|
+
- `maxBufferedBytes` (handler option, default 8 MB): a reader that falls behind by more is disconnected, and when it is the creator of the session, the session is cancelled. A custom adapter takes part by implementing `bufferedBytes()` and `destroy()` on its `BrokerResponse`.
|
|
182
|
+
|
|
183
|
+
### What cancelling does, and what one script can hold
|
|
184
|
+
|
|
185
|
+
A session runs in the broker's own process and thread. A script that computes without calling a tool holds the thread, and with it every other session, until it ends or reaches `toolTimeoutMs`. Cancelling a session (`DELETE`, a caller that disconnects, `deadlineMs`, `session.cancel()`) aborts the tool call in flight and refuses every later one; it does not interrupt a script that is computing. Keep `toolTimeoutMs` low, and run the broker in a process of its own (or give the sandbox the worker-pool adapter through `enclave`) when you serve callers you do not trust.
|
|
186
|
+
|
|
187
|
+
### Event filters
|
|
188
|
+
|
|
189
|
+
A filter decides which events a client is sent: by type, or by content with `exact`, `prefix`, `regex` and `glob` patterns.
|
|
143
190
|
|
|
144
191
|
```typescript
|
|
145
|
-
import {
|
|
146
|
-
|
|
147
|
-
const
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
console.log(`Tool call: ${call.name}`);
|
|
152
|
-
const start = Date.now();
|
|
153
|
-
const result = await next(call);
|
|
154
|
-
console.log(`Completed in ${Date.now() - start}ms`);
|
|
155
|
-
return result;
|
|
156
|
-
},
|
|
157
|
-
// Validation middleware
|
|
158
|
-
async (call, next) => {
|
|
159
|
-
if (!isValidArgs(call.name, call.args)) {
|
|
160
|
-
throw new Error('Invalid arguments');
|
|
161
|
-
}
|
|
162
|
-
return next(call);
|
|
163
|
-
},
|
|
164
|
-
],
|
|
165
|
-
tools: {
|
|
166
|
-
// ... tool handlers
|
|
192
|
+
import { createEventFilter } from '@enclave-vm/broker';
|
|
193
|
+
|
|
194
|
+
const filter = createEventFilter({
|
|
195
|
+
config: {
|
|
196
|
+
mode: 'exclude',
|
|
197
|
+
rules: [{ types: { types: ['heartbeat', 'tool_progress'] } }],
|
|
167
198
|
},
|
|
168
199
|
});
|
|
200
|
+
|
|
201
|
+
session.onEvent((event) => {
|
|
202
|
+
if (filter.shouldSend(event)) send(event);
|
|
203
|
+
});
|
|
169
204
|
```
|
|
170
205
|
|
|
171
|
-
|
|
206
|
+
- Evaluating one event takes a bounded time: regular expressions and globs run under `regexTimeoutMs` (100 ms by default). `budgetMs` bounds all evaluations of one filter together.
|
|
207
|
+
- An event a filter could not evaluate (a pattern that does not compile, an evaluation that ran out of time) is **not sent**, in either mode.
|
|
208
|
+
- In exclude mode a glob is matched as text: `*` also matches `/` and a leading dot. In include mode a glob follows path rules, as before.
|
|
209
|
+
- A filter that arrives in a request is validated, gets at most 100 ms per event and 500 ms per stream, and its globs are matched without brace and extglob expansion.
|
|
172
210
|
|
|
173
|
-
|
|
174
|
-
import { RateLimiter } from '@enclave-vm/broker';
|
|
211
|
+
A filter is a convenience for the client. **It is not a confidentiality control**: data a client must not see has to stay out of the events, that is, out of tool arguments and results.
|
|
175
212
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
213
|
+
### Tools from OpenAPI
|
|
214
|
+
|
|
215
|
+
```typescript
|
|
216
|
+
const source = broker.openapi({
|
|
217
|
+
name: 'users',
|
|
218
|
+
url: 'https://api.example.com/openapi.json',
|
|
219
|
+
baseUrl: 'https://api.example.com',
|
|
220
|
+
auth: { type: 'bearer', token: process.env.API_TOKEN! },
|
|
221
|
+
intervalMs: 60_000,
|
|
182
222
|
});
|
|
183
223
|
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
throw new Error('Rate limit exceeded');
|
|
187
|
-
}
|
|
224
|
+
source.on('error', (error) => console.error('users API:', error.message));
|
|
225
|
+
await source.start();
|
|
188
226
|
```
|
|
189
227
|
|
|
190
|
-
|
|
228
|
+
- A failure while polling is reported with the `error` event when it has a listener, and in `source.getStats()` (`pollHealth`, `lastError`) either way. The tools of the last specification that was applied stay registered. Tools are replaced in one step, and a source never replaces a tool it does not manage.
|
|
229
|
+
- A path parameter fills its own segment of the path: a value that would leave the segment empty or turn it into `.` or `..` fails the call.
|
|
230
|
+
- The credential (`auth`) and `loaderOptions.headers` go to the origin of `baseUrl` only. They are not sent with the request for the specification when it is on another origin (use `headers` of the source for what the specification host needs), and a redirect to another origin is followed without them. A header parameter of the specification cannot replace them.
|
|
231
|
+
- Upstream responses are read up to `loaderOptions.maxResponseBytes` (10 MB), specifications up to `maxSpecBytes` (32 MB), and fetching a specification is bounded by `fetchTimeoutMs`.
|
|
232
|
+
|
|
233
|
+
A script decides the arguments of a generated tool, so whatever an operation of the upstream does with its arguments is within reach of a script. Generate tools only for the operations a script may call (`loaderOptions.includeOperations`, `loaderOptions.excludeOperations`).
|
|
234
|
+
|
|
235
|
+
### Secrets and tool arguments
|
|
236
|
+
|
|
237
|
+
Secrets are resolved per tool and handed to the handler only; they are not part of any event. Tool arguments and the result of the script are part of the events: do not put a secret into them, and do not return one from a tool.
|
|
238
|
+
|
|
239
|
+
## Related packages
|
|
191
240
|
|
|
192
|
-
| Package
|
|
193
|
-
|
|
|
194
|
-
| [@enclave-vm/
|
|
195
|
-
| [@enclave-vm/
|
|
196
|
-
| [@enclave-vm/
|
|
197
|
-
| [@enclave-vm/
|
|
198
|
-
| [@enclave-vm/runtime](../
|
|
241
|
+
| Package | Description |
|
|
242
|
+
| --------------------------------- | ------------------------------------------------------------- |
|
|
243
|
+
| [@enclave-vm/core](../core) | The sandbox |
|
|
244
|
+
| [@enclave-vm/types](../types) | Protocol types and Zod schemas |
|
|
245
|
+
| [@enclave-vm/client](../client) | Browser and Node.js client |
|
|
246
|
+
| [@enclave-vm/stream](../stream) | NDJSON and reconnection helpers |
|
|
247
|
+
| [@enclave-vm/runtime](../runtime) | Runtime worker building blocks (does not execute scripts yet) |
|
|
199
248
|
|
|
200
249
|
## License
|
|
201
250
|
|
package/broker-session.d.ts
CHANGED
|
@@ -9,6 +9,7 @@ import type { SessionId, StreamEvent, SessionLimits, ErrorPayload } from '@encla
|
|
|
9
9
|
import { SessionEmitter } from '@enclave-vm/core';
|
|
10
10
|
import type { SessionStateValue, SessionFinalResult, CreateEnclaveOptions, ExecutionStats } from '@enclave-vm/core';
|
|
11
11
|
import type { ToolRegistry } from './tool-registry';
|
|
12
|
+
import type { SessionHistoryLimits } from './session-history';
|
|
12
13
|
/**
|
|
13
14
|
* Broker session configuration
|
|
14
15
|
*/
|
|
@@ -18,7 +19,8 @@ export interface BrokerSessionConfig {
|
|
|
18
19
|
*/
|
|
19
20
|
sessionId?: SessionId;
|
|
20
21
|
/**
|
|
21
|
-
* Session resource limits
|
|
22
|
+
* Session resource limits. A field that is not given keeps the value of the broker's
|
|
23
|
+
* configuration, or the package default.
|
|
22
24
|
*/
|
|
23
25
|
limits?: Partial<SessionLimits>;
|
|
24
26
|
/**
|
|
@@ -30,6 +32,18 @@ export interface BrokerSessionConfig {
|
|
|
30
32
|
* @default 15000
|
|
31
33
|
*/
|
|
32
34
|
heartbeatIntervalMs?: number;
|
|
35
|
+
/**
|
|
36
|
+
* Bounds of the events the session keeps for a replay. When a bound is reached the oldest
|
|
37
|
+
* events are dropped.
|
|
38
|
+
* @default { maxEvents: 10000, maxBytes: 4194304 }
|
|
39
|
+
*/
|
|
40
|
+
history?: SessionHistoryLimits;
|
|
41
|
+
/**
|
|
42
|
+
* The caller this session belongs to. The HTTP routes set it from their `identify` hook and
|
|
43
|
+
* answer for a session only to its owner. A session created in process has no owner unless
|
|
44
|
+
* one is given here, and is then not reachable over routes that identify their callers.
|
|
45
|
+
*/
|
|
46
|
+
owner?: string;
|
|
33
47
|
}
|
|
34
48
|
/**
|
|
35
49
|
* Broker Session
|
|
@@ -41,11 +55,16 @@ export declare class BrokerSession {
|
|
|
41
55
|
readonly sessionId: SessionId;
|
|
42
56
|
readonly createdAt: number;
|
|
43
57
|
readonly expiresAt: number;
|
|
58
|
+
/**
|
|
59
|
+
* The caller this session belongs to, if any.
|
|
60
|
+
*/
|
|
61
|
+
readonly owner?: string;
|
|
44
62
|
private readonly emitter;
|
|
45
63
|
private readonly toolRegistry;
|
|
46
64
|
private readonly enclave;
|
|
47
65
|
private readonly abortController;
|
|
48
66
|
private readonly limits;
|
|
67
|
+
private readonly checkResultSize;
|
|
49
68
|
private _state;
|
|
50
69
|
private executionPromise;
|
|
51
70
|
private toolCallCount;
|
|
@@ -72,9 +91,15 @@ export declare class BrokerSession {
|
|
|
72
91
|
*/
|
|
73
92
|
onEvent(handler: (event: StreamEvent) => void): () => void;
|
|
74
93
|
/**
|
|
75
|
-
* Get all
|
|
94
|
+
* Get the events the session keeps: all of them, or the most recent ones once a bound of
|
|
95
|
+
* the history was reached (see `firstReplayableSeq`)
|
|
76
96
|
*/
|
|
77
97
|
getEvents(): StreamEvent[];
|
|
98
|
+
/**
|
|
99
|
+
* The lowest sequence number from which every event is still kept. It is 1 until the history
|
|
100
|
+
* reaches a bound; from then on, events below it cannot be replayed.
|
|
101
|
+
*/
|
|
102
|
+
get firstReplayableSeq(): number;
|
|
78
103
|
/**
|
|
79
104
|
* Execute code in this session
|
|
80
105
|
*
|
|
@@ -102,6 +127,10 @@ export declare class BrokerSession {
|
|
|
102
127
|
* Execute a tool call directly
|
|
103
128
|
*/
|
|
104
129
|
private executeTool;
|
|
130
|
+
/**
|
|
131
|
+
* Whether a tool result is within `limits.maxToolResultBytes`, measured as serialized JSON.
|
|
132
|
+
*/
|
|
133
|
+
private resultWithinLimit;
|
|
105
134
|
/**
|
|
106
135
|
* Create a custom event with proper base fields and unique sequence number.
|
|
107
136
|
*/
|
package/broker.d.ts
CHANGED
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
* @packageDocumentation
|
|
7
7
|
*/
|
|
8
8
|
import type { SessionId, StreamEvent, SessionLimits } from '@enclave-vm/types';
|
|
9
|
+
import type { SessionHistoryLimits } from './session-history';
|
|
9
10
|
import type { CreateEnclaveOptions, SessionFinalResult } from '@enclave-vm/core';
|
|
10
11
|
import type { ToolDefinition } from './tool-registry';
|
|
11
12
|
import type { SessionManagerConfig, SessionInfo } from './session-manager';
|
|
@@ -26,9 +27,16 @@ export interface BrokerConfig {
|
|
|
26
27
|
*/
|
|
27
28
|
enclave?: CreateEnclaveOptions;
|
|
28
29
|
/**
|
|
29
|
-
* Default session limits
|
|
30
|
+
* Default session limits. They bound every session of this broker: a session created in
|
|
31
|
+
* process may name its own value for a limit, a session created over the HTTP routes may only
|
|
32
|
+
* lower one.
|
|
30
33
|
*/
|
|
31
34
|
limits?: Partial<SessionLimits>;
|
|
35
|
+
/**
|
|
36
|
+
* Bounds of the events each session keeps for a replay.
|
|
37
|
+
* @default { maxEvents: 10000, maxBytes: 4194304 }
|
|
38
|
+
*/
|
|
39
|
+
history?: SessionHistoryLimits;
|
|
32
40
|
}
|
|
33
41
|
/**
|
|
34
42
|
* Quick execution options
|
|
@@ -77,8 +85,14 @@ export declare class Broker {
|
|
|
77
85
|
private readonly sessionManager;
|
|
78
86
|
private readonly config;
|
|
79
87
|
private readonly openApiSources;
|
|
88
|
+
private readonly defaultLimits;
|
|
80
89
|
private disposed;
|
|
81
90
|
constructor(config?: BrokerConfig);
|
|
91
|
+
/**
|
|
92
|
+
* The limits of a session that names none: the broker's configuration over the package
|
|
93
|
+
* defaults. The HTTP routes use them as the ceiling of what a request may ask for.
|
|
94
|
+
*/
|
|
95
|
+
get sessionLimits(): Readonly<Required<SessionLimits>>;
|
|
82
96
|
/**
|
|
83
97
|
* Register a tool with the broker
|
|
84
98
|
*
|
package/errors.d.ts
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Broker errors
|
|
3
|
+
*
|
|
4
|
+
* @packageDocumentation
|
|
5
|
+
*/
|
|
6
|
+
/**
|
|
7
|
+
* Codes of the errors the broker raises itself.
|
|
8
|
+
*/
|
|
9
|
+
export declare const BrokerErrorCode: {
|
|
10
|
+
/** The session id is not a usable id */
|
|
11
|
+
readonly InvalidSessionId: "INVALID_SESSION_ID";
|
|
12
|
+
/** A session with this id is registered */
|
|
13
|
+
readonly SessionExists: "SESSION_EXISTS";
|
|
14
|
+
/** The broker holds as many sessions as `maxSessions` allows */
|
|
15
|
+
readonly MaxSessionsReached: "MAX_SESSIONS_REACHED";
|
|
16
|
+
};
|
|
17
|
+
export type BrokerErrorCode = (typeof BrokerErrorCode)[keyof typeof BrokerErrorCode];
|
|
18
|
+
/**
|
|
19
|
+
* An error with a machine-readable code.
|
|
20
|
+
*/
|
|
21
|
+
export declare class BrokerError extends Error {
|
|
22
|
+
readonly code: BrokerErrorCode;
|
|
23
|
+
constructor(code: BrokerErrorCode, message: string);
|
|
24
|
+
}
|