@enclave-vm/broker 2.19.1 → 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 CHANGED
@@ -6,196 +6,245 @@
6
6
 
7
7
  > Tool broker and session management for the EnclaveJS streaming runtime
8
8
 
9
- The @enclave-vm/broker package provides server-side components for managing EnclaveJS sessions, routing tool calls, and handling the streaming protocol. It acts as the middleware between clients and the secure execution environment.
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
- ## Features
11
+ ## What it provides
12
12
 
13
- - **Session Management**: Create, manage, and clean up execution sessions
14
- - **Tool Routing**: Route tool calls to appropriate handlers with pattern matching
15
- - **Access Control**: Fine-grained tool permissions using glob patterns
16
- - **Rate Limiting**: Configurable rate limits per session
17
- - **State Management**: Track session state and tool call history
18
- - **Middleware Support**: Extensible middleware pipeline for tool calls
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 Start
27
+ ## Quick start
31
28
 
32
29
  ```typescript
33
- import { Broker, createSession } from '@enclave-vm/broker';
34
-
35
- // Create a broker with tool handlers
36
- const broker = new Broker({
37
- tools: {
38
- 'users:get': async (args) => {
39
- return { id: args.id, name: 'Alice' };
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
- // Create a session
51
- const session = await broker.createSession({
52
- allowedTools: ['users:*'], // Glob pattern for allowed tools
53
- timeout: 30000,
54
- maxToolCalls: 100,
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
- // Handle incoming messages
58
- session.on('tool_call', async (call) => {
59
- const result = await broker.executeToolCall(session.id, call);
60
- session.send({ type: 'tool_result', id: call.id, data: result });
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
- ## Session Management
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
- ```typescript
67
- import { SessionManager } from '@enclave-vm/broker';
70
+ ## Serving sessions over HTTP
68
71
 
69
- const manager = new SessionManager({
70
- maxConcurrentSessions: 100,
71
- sessionTimeout: 60000, // 1 minute
72
- cleanupInterval: 10000, // 10 seconds
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
- // Create session
76
- const session = await manager.create({
77
- userId: 'user_123',
78
- metadata: { source: 'api' },
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
- // Get session
82
- const retrieved = manager.get(session.id);
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
- // List active sessions
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
- // Destroy session
88
- await manager.destroy(session.id);
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
- ## Tool Routing
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
- Route tool calls with pattern matching:
122
+ ## Security
94
123
 
95
- ```typescript
96
- import { ToolRouter } from '@enclave-vm/broker';
124
+ ### Who may see a session
97
125
 
98
- const router = new ToolRouter();
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
- // Register tools with glob patterns
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
- router.register('api:external:*', {
110
- handler: async (name, args) => {
111
- return await externalApi.call(name, args);
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
- ## Access Control
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
- ```typescript
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
- // Check access
136
- const canAccess = access.check('admin:delete', { role: 'user' }); // false
137
- const canRead = access.check('user:profile:read', {}); // true
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
- ## Middleware
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
- Add middleware for cross-cutting concerns:
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 { Broker } from '@enclave-vm/broker';
146
-
147
- const broker = new Broker({
148
- middleware: [
149
- // Logging middleware
150
- async (call, next) => {
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
- ## Rate Limiting
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
- ```typescript
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
- const limiter = new RateLimiter({
177
- global: { maxCalls: 1000, windowMs: 60000 },
178
- perSession: { maxCalls: 100, windowMs: 60000 },
179
- perTool: {
180
- 'expensive:*': { maxCalls: 10, windowMs: 60000 },
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
- // Check rate limit before execution
185
- if (!limiter.allow(sessionId, toolName)) {
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
- ## Related Packages
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 | Description |
193
- | ------------------------------------------- | --------------------------------- |
194
- | [@enclave-vm/types](../enclavejs-types) | Type definitions and Zod schemas |
195
- | [@enclave-vm/stream](../enclavejs-stream) | Streaming protocol implementation |
196
- | [@enclave-vm/core](../enclave-vm) | Secure execution environment |
197
- | [@enclave-vm/client](../enclavejs-client) | Browser/Node.js client SDK |
198
- | [@enclave-vm/runtime](../enclavejs-runtime) | Standalone runtime worker |
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
 
@@ -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 emitted events
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
+ }