@enclave-vm/types 2.20.0-rc.1 → 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.
Files changed (2) hide show
  1. package/README.md +84 -59
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,49 +1,45 @@
1
1
  # @enclave-vm/types
2
2
 
3
- [![npm version](https://img.shields.io/npm/v/@enclave-vm/types.svg)](https://www.npmjs.com/package/@enclave-vm/types)
4
- [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
5
- [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](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
- ## Features
5
+ [![npm version](https://img.shields.io/npm/v/@enclave-vm/types.svg)](https://www.npmjs.com/package/@enclave-vm/types)
6
+ [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/agentfront/enclave/blob/main/LICENSE)
12
7
 
13
- - **TypeScript-First**: Full TypeScript support with strict typing
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
- ## Installation
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 Start
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
- // Type-safe event handling
35
- function handleEvent(event: StreamEvent) {
21
+ function handleEvent(event: StreamEvent): void {
36
22
  if (isToolCallEvent(event)) {
37
- console.log(`Tool: ${event.payload.toolName}, Args:`, event.payload.args);
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
- ## Protocol
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
- ### Stream Events
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
- The event types are `session_init`, `stdout`, `log`, `tool_call`, `tool_result_applied`, `final`, `heartbeat`, `error`, and since protocol version 2 `partial_result`, `tool_progress`, `deadline_exceeded` and `catalog_changed`. Each has a type (`ToolCallEvent`), a schema (`ToolCallEventSchema`) and a type guard (`isToolCallEvent`).
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
- ### Identifiers and Session State
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 a UUID
92
- const callId = generateCallId(); // 'c_' followed by a UUID
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
- ## Zod Schemas
113
+ `generateRefId`, `isCallId`, `isRefId`, `createRefToken` and `isRefToken` work the same way for call ids and `ref_` reference ids.
103
114
 
104
- The types have corresponding Zod schemas for runtime validation:
115
+ `SessionLimits` describes the limits of a session. `DEFAULT_SESSION_LIMITS` holds the defaults that `@enclave-vm/broker` applies:
105
116
 
106
- ```typescript
107
- import { StreamEventSchema, parseStreamEvent } from '@enclave-vm/types';
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
- // Parse and validate
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
- // The same, as a helper
119
- const result = parseStreamEvent(untrustedData);
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
- ## What the Package Does Not Do
144
+ ## Related packages
123
145
 
124
- The package defines types for an encrypted envelope and a key exchange (`EncryptedEnvelope`, `ClientHello`, `ServerHello`). They are definitions: no client or broker of this repository encrypts a session, and the key exchange they describe is not authenticated. Sessions are plain JSON protected by the transport.
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
- ## Related Packages
154
+ ## Documentation
127
155
 
128
- | Package | Description |
129
- | --------------------------------- | ------------------------------------------------------- |
130
- | [@enclave-vm/stream](../stream) | Streaming protocol implementation |
131
- | [@enclave-vm/broker](../broker) | Tool broker and session management |
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.0-rc.1",
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",