@enclave-vm/types 2.20.0 → 2.20.1
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 +84 -59
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,49 +1,45 @@
|
|
|
1
1
|
# @enclave-vm/types
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
[](LICENSE)
|
|
5
|
-
[](https://www.typescriptlang.org/)
|
|
6
|
-
|
|
7
|
-
> Type definitions and Zod schemas for the EnclaveJS streaming runtime protocol
|
|
8
|
-
|
|
9
|
-
The @enclave-vm/types package provides TypeScript type definitions and runtime validation schemas for the EnclaveJS streaming protocol. It serves as the foundation for type-safe communication between EnclaveJS components.
|
|
3
|
+
TypeScript types, Zod schemas and small helpers for the EnclaveJS streaming protocol, for code that produces or consumes session events.
|
|
10
4
|
|
|
11
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/@enclave-vm/types)
|
|
6
|
+
[](https://github.com/agentfront/enclave/blob/main/LICENSE)
|
|
12
7
|
|
|
13
|
-
-
|
|
14
|
-
- **Zod Schemas**: Runtime validation for all protocol messages
|
|
15
|
-
- **Protocol Types**: Complete type definitions for streaming messages
|
|
16
|
-
- **Session Types**: Types for session management and state
|
|
17
|
-
- **Tool Types**: Type definitions for tool calls and responses
|
|
8
|
+
This package is the base of the streaming packages: [`@enclave-vm/stream`](https://www.npmjs.com/package/@enclave-vm/stream) re-exports all of it, and [`@enclave-vm/broker`](https://www.npmjs.com/package/@enclave-vm/broker), [`@enclave-vm/client`](https://www.npmjs.com/package/@enclave-vm/client) and [`@enclave-vm/runtime`](https://www.npmjs.com/package/@enclave-vm/runtime) build on it. Its only dependency is `zod`.
|
|
18
9
|
|
|
19
|
-
##
|
|
10
|
+
## Install
|
|
20
11
|
|
|
21
12
|
```bash
|
|
22
13
|
npm install @enclave-vm/types
|
|
23
|
-
# or
|
|
24
|
-
yarn add @enclave-vm/types
|
|
25
|
-
# or
|
|
26
|
-
pnpm add @enclave-vm/types
|
|
27
14
|
```
|
|
28
15
|
|
|
29
|
-
## Quick
|
|
16
|
+
## Quick start
|
|
30
17
|
|
|
31
18
|
```typescript
|
|
32
|
-
import { isToolCallEvent, isFinalEvent, type StreamEvent } from '@enclave-vm/types';
|
|
19
|
+
import { parseStreamEvent, isToolCallEvent, isFinalEvent, type StreamEvent } from '@enclave-vm/types';
|
|
33
20
|
|
|
34
|
-
|
|
35
|
-
function handleEvent(event: StreamEvent) {
|
|
21
|
+
function handleEvent(event: StreamEvent): void {
|
|
36
22
|
if (isToolCallEvent(event)) {
|
|
37
|
-
console.log(`Tool: ${event.payload.toolName},
|
|
23
|
+
console.log(`Tool: ${event.payload.toolName}, args:`, event.payload.args);
|
|
38
24
|
} else if (isFinalEvent(event)) {
|
|
39
25
|
console.log(event.payload.ok ? 'Result:' : 'Error:', event.payload.result ?? event.payload.error);
|
|
40
26
|
}
|
|
41
27
|
}
|
|
42
|
-
```
|
|
43
28
|
|
|
44
|
-
|
|
29
|
+
// Validate data that came from the network before using it
|
|
30
|
+
const untrusted: unknown = JSON.parse(
|
|
31
|
+
'{"protocolVersion":2,"sessionId":"s_1","seq":1,"type":"stdout","payload":{"chunk":"Hello"}}',
|
|
32
|
+
);
|
|
33
|
+
const parsed = parseStreamEvent(untrusted); // StreamEventSchema.safeParse(untrusted)
|
|
34
|
+
if (parsed.success) {
|
|
35
|
+
// The schemas type ids as `string`, the interfaces as `s_${string}`: hence the cast
|
|
36
|
+
handleEvent(parsed.data as StreamEvent);
|
|
37
|
+
} else {
|
|
38
|
+
console.error('Invalid event:', parsed.error);
|
|
39
|
+
}
|
|
40
|
+
```
|
|
45
41
|
|
|
46
|
-
|
|
42
|
+
## Stream events
|
|
47
43
|
|
|
48
44
|
Every event has `protocolVersion`, `sessionId`, a sequence number `seq`, a `type` and a `payload`:
|
|
49
45
|
|
|
@@ -75,9 +71,26 @@ const final: FinalEvent = {
|
|
|
75
71
|
};
|
|
76
72
|
```
|
|
77
73
|
|
|
78
|
-
|
|
74
|
+
Each event type has a TypeScript type, a Zod schema and a type guard:
|
|
75
|
+
|
|
76
|
+
| `type` | Type | Schema | Guard |
|
|
77
|
+
| --------------------- | ------------------------ | ------------------------------ | -------------------------- |
|
|
78
|
+
| `session_init` | `SessionInitEvent` | `SessionInitEventSchema` | `isSessionInitEvent` |
|
|
79
|
+
| `stdout` | `StdoutEvent` | `StdoutEventSchema` | `isStdoutEvent` |
|
|
80
|
+
| `log` | `LogEvent` | `LogEventSchema` | `isLogEvent` |
|
|
81
|
+
| `tool_call` | `ToolCallEvent` | `ToolCallEventSchema` | `isToolCallEvent` |
|
|
82
|
+
| `tool_result_applied` | `ToolResultAppliedEvent` | `ToolResultAppliedEventSchema` | `isToolResultAppliedEvent` |
|
|
83
|
+
| `final` | `FinalEvent` | `FinalEventSchema` | `isFinalEvent` |
|
|
84
|
+
| `heartbeat` | `HeartbeatEvent` | `HeartbeatEventSchema` | `isHeartbeatEvent` |
|
|
85
|
+
| `error` | `ErrorEvent` | `ErrorEventSchema` | `isErrorEvent` |
|
|
86
|
+
| `partial_result` | `PartialResultEvent` | `PartialResultEventSchema` | `isPartialResultEvent` |
|
|
87
|
+
| `tool_progress` | `ToolProgressEvent` | `ToolProgressEventSchema` | `isToolProgressEvent` |
|
|
88
|
+
| `deadline_exceeded` | `DeadlineExceededEvent` | `DeadlineExceededEventSchema` | `isDeadlineExceededEvent` |
|
|
89
|
+
| `catalog_changed` | `CatalogChangedEvent` | `CatalogChangedEventSchema` | `isCatalogChangedEvent` |
|
|
90
|
+
|
|
91
|
+
The last four were added in protocol version 2. `StreamEvent` and `StreamEventSchema` are the union of all of them. `EventType` holds the type names as constants, including `Encrypted` (`'enc'`) for the encrypted envelope described below.
|
|
79
92
|
|
|
80
|
-
|
|
93
|
+
## Identifiers, session state and limits
|
|
81
94
|
|
|
82
95
|
```typescript
|
|
83
96
|
import {
|
|
@@ -88,51 +101,63 @@ import {
|
|
|
88
101
|
DEFAULT_SESSION_LIMITS,
|
|
89
102
|
} from '@enclave-vm/types';
|
|
90
103
|
|
|
91
|
-
const sessionId = generateSessionId(); // 's_' followed by
|
|
92
|
-
const callId = generateCallId(); // 'c_' followed by
|
|
104
|
+
const sessionId = generateSessionId(); // 's_' followed by crypto.randomUUID()
|
|
105
|
+
const callId = generateCallId(); // 'c_' followed by crypto.randomUUID()
|
|
93
106
|
|
|
94
|
-
isSessionId(sessionId); // true
|
|
107
|
+
isSessionId(sessionId); // true: checks the 's_' prefix only
|
|
95
108
|
|
|
96
109
|
SessionState.Running; // 'running'
|
|
97
110
|
// 'starting' | 'running' | 'waiting_for_tool' | 'completed' | 'cancelled' | 'failed'
|
|
98
|
-
|
|
99
|
-
DEFAULT_SESSION_LIMITS.maxToolCalls; // 50
|
|
100
111
|
```
|
|
101
112
|
|
|
102
|
-
|
|
113
|
+
`generateRefId`, `isCallId`, `isRefId`, `createRefToken` and `isRefToken` work the same way for call ids and `ref_` reference ids.
|
|
103
114
|
|
|
104
|
-
|
|
115
|
+
`SessionLimits` describes the limits of a session. `DEFAULT_SESSION_LIMITS` holds the defaults that `@enclave-vm/broker` applies:
|
|
105
116
|
|
|
106
|
-
|
|
107
|
-
|
|
117
|
+
| Field | Default | Meaning |
|
|
118
|
+
| --------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
119
|
+
| `sessionTtlMs` | `60000` | How long a session lives |
|
|
120
|
+
| `maxToolCalls` | `50` | Tool calls per session |
|
|
121
|
+
| `maxStdoutBytes` | `262144` | Output bytes (the broker emits no `stdout` events and does not use it) |
|
|
122
|
+
| `maxToolResultBytes` | `5242880` | Size of one tool result |
|
|
123
|
+
| `toolTimeoutMs` | `30000` | How long the script may run (the name is historical; the broker passes it to the sandbox as its `timeout`) |
|
|
124
|
+
| `heartbeatIntervalMs` | `15000` | Interval of `heartbeat` events |
|
|
125
|
+
| `deadlineMs` | `0` (no deadline) | Deadline for the whole session |
|
|
126
|
+
| `perToolDeadlineMs` | `30000` | Time one tool call may take |
|
|
127
|
+
| `cancelOnFirstError` | `false` | Whether the first failed tool call cancels the session |
|
|
108
128
|
|
|
109
|
-
|
|
110
|
-
const parsed = StreamEventSchema.safeParse(untrustedData);
|
|
111
|
-
if (parsed.success) {
|
|
112
|
-
// parsed.data is typed as StreamEvent
|
|
113
|
-
handleEvent(parsed.data);
|
|
114
|
-
} else {
|
|
115
|
-
console.error('Invalid event:', parsed.error);
|
|
116
|
-
}
|
|
129
|
+
`ToolConfig` has four fields. Only `timeout` has an effect; `retryable`, `maxRetries` and `runtimeReadable` are part of the protocol design and no package acts on them.
|
|
117
130
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
131
|
+
## Other definitions
|
|
132
|
+
|
|
133
|
+
- **Runtime channel messages**: `ToolResultSubmitMessage`, `CancelMessage` and `RuntimeChannelMessage`, with schemas and `parseRuntimeChannelMessage`.
|
|
134
|
+
- **Event filters**: `EventFilterConfig`, `FilterRule`, `ContentPattern`, `FilterMode`, `PatternType` and `DEFAULT_ALWAYS_ALLOW` (`['session_init', 'final']`). `@enclave-vm/broker` implements filters from these definitions.
|
|
135
|
+
- **Validation helpers**: `parseStreamEvent`, `parseEncryptedEnvelope`, `parseRuntimeChannelMessage`, `parseCreateSessionRequest` and `parseStreamEventOrEncrypted`. Each returns the result of Zod's `safeParse`.
|
|
136
|
+
- **Create-session request**: `CreateSessionRequestSchema` (`protocolVersion`, `code`, `limits`, `encryption`). The `POST /sessions` route of `@enclave-vm/broker` does not use this schema; it accepts a different body (`code`, `sessionId`, `config`, `filter`), described in the broker's README.
|
|
137
|
+
|
|
138
|
+
## Security notes
|
|
139
|
+
|
|
140
|
+
The package defines types for an encrypted envelope and a key exchange (`EncryptedEnvelope`, `ClientHello`, `ServerHello`, `EncryptionRequest`, and constants such as `AES_GCM_NONCE_SIZE`). They are only definitions. No client or broker in this repository encrypts a session, and the key exchange they describe is not authenticated. Sessions are plain JSON, protected only by the transport.
|
|
141
|
+
|
|
142
|
+
The type guards (`isToolCallEvent` and the others) check the `type` field only. To check data you received, use a schema or a `parse*` helper.
|
|
121
143
|
|
|
122
|
-
##
|
|
144
|
+
## Related packages
|
|
123
145
|
|
|
124
|
-
|
|
146
|
+
| Package | Role |
|
|
147
|
+
| ------------------------------------------------------------------------ | ------------------------------------------------------ |
|
|
148
|
+
| [@enclave-vm/stream](https://www.npmjs.com/package/@enclave-vm/stream) | NDJSON, reconnection helpers, encryption primitives |
|
|
149
|
+
| [@enclave-vm/broker](https://www.npmjs.com/package/@enclave-vm/broker) | Tool broker, sessions and HTTP routes |
|
|
150
|
+
| [@enclave-vm/client](https://www.npmjs.com/package/@enclave-vm/client) | Browser and Node.js client for a broker |
|
|
151
|
+
| [@enclave-vm/react](https://www.npmjs.com/package/@enclave-vm/react) | React provider and hooks on top of the client |
|
|
152
|
+
| [@enclave-vm/runtime](https://www.npmjs.com/package/@enclave-vm/runtime) | Runtime worker building blocks (does not execute code) |
|
|
125
153
|
|
|
126
|
-
##
|
|
154
|
+
## Documentation
|
|
127
155
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
| [@enclave-vm/client](../client) | Browser/Node.js client SDK |
|
|
133
|
-
| [@enclave-vm/react](../react) | React hooks and components |
|
|
134
|
-
| [@enclave-vm/runtime](../runtime) | Runtime worker building blocks (not a runnable service) |
|
|
156
|
+
- Documentation: https://agentfront.dev/docs/guides/enclave
|
|
157
|
+
- Repository: https://github.com/agentfront/enclave
|
|
158
|
+
- Architecture: https://github.com/agentfront/enclave/blob/main/README-ARCHITECTURE.md
|
|
159
|
+
- Security policy: https://github.com/agentfront/enclave/blob/main/SECURITY.md
|
|
135
160
|
|
|
136
161
|
## License
|
|
137
162
|
|
|
138
|
-
Apache-2.0
|
|
163
|
+
Apache-2.0. See [LICENSE](https://github.com/agentfront/enclave/blob/main/LICENSE).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@enclave-vm/types",
|
|
3
|
-
"version": "2.20.
|
|
3
|
+
"version": "2.20.1",
|
|
4
4
|
"description": "Type definitions and Zod schemas for the EnclaveJS streaming runtime protocol",
|
|
5
5
|
"author": "AgentFront <info@agentfront.dev>",
|
|
6
6
|
"homepage": "https://github.com/agentfront/enclave",
|