@enclave-vm/types 2.19.1 → 2.20.0-rc.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 CHANGED
@@ -29,92 +29,109 @@ pnpm add @enclave-vm/types
29
29
  ## Quick Start
30
30
 
31
31
  ```typescript
32
- import { StreamMessage, ToolCallMessage, ToolResultMessage, SessionState } from '@enclave-vm/types';
33
-
34
- // Type-safe message handling
35
- function handleMessage(message: StreamMessage) {
36
- switch (message.type) {
37
- case 'tool_call':
38
- const toolCall = message as ToolCallMessage;
39
- console.log(`Tool: ${toolCall.name}, Args:`, toolCall.args);
40
- break;
41
- case 'tool_result':
42
- const result = message as ToolResultMessage;
43
- console.log(`Result:`, result.data);
44
- break;
32
+ import { isToolCallEvent, isFinalEvent, type StreamEvent } from '@enclave-vm/types';
33
+
34
+ // Type-safe event handling
35
+ function handleEvent(event: StreamEvent) {
36
+ if (isToolCallEvent(event)) {
37
+ console.log(`Tool: ${event.payload.toolName}, Args:`, event.payload.args);
38
+ } else if (isFinalEvent(event)) {
39
+ console.log(event.payload.ok ? 'Result:' : 'Error:', event.payload.result ?? event.payload.error);
45
40
  }
46
41
  }
47
42
  ```
48
43
 
49
- ## Protocol Messages
44
+ ## Protocol
50
45
 
51
- ### Stream Messages
46
+ ### Stream Events
52
47
 
53
- ```typescript
54
- import { StreamMessageSchema, StreamMessage } from '@enclave-vm/types';
55
-
56
- // Validate incoming messages
57
- const message = StreamMessageSchema.parse(rawMessage);
58
- ```
59
-
60
- ### Tool Calls
48
+ Every event has `protocolVersion`, `sessionId`, a sequence number `seq`, a `type` and a `payload`:
61
49
 
62
50
  ```typescript
63
- import { ToolCallMessage, ToolResultMessage } from '@enclave-vm/types';
51
+ import { PROTOCOL_VERSION, type ToolCallEvent, type FinalEvent } from '@enclave-vm/types';
64
52
 
65
- const toolCall: ToolCallMessage = {
53
+ const toolCall: ToolCallEvent = {
54
+ protocolVersion: PROTOCOL_VERSION, // 2
55
+ sessionId: 's_3f0e2f6e-1c1b-4c57-9a55-0a8b5a3d2c11',
56
+ seq: 2,
66
57
  type: 'tool_call',
67
- id: 'call_123',
68
- name: 'getUser',
69
- args: { userId: 1 },
58
+ payload: {
59
+ callId: 'c_9a55e2f6-4c57-1c1b-3f0e-0a8b5a3d2c11',
60
+ toolName: 'getUser',
61
+ args: { userId: 1 },
62
+ },
70
63
  };
71
64
 
72
- const toolResult: ToolResultMessage = {
73
- type: 'tool_result',
74
- id: 'call_123',
75
- data: { name: 'Alice', email: 'alice@example.com' },
65
+ const final: FinalEvent = {
66
+ protocolVersion: PROTOCOL_VERSION,
67
+ sessionId: 's_3f0e2f6e-1c1b-4c57-9a55-0a8b5a3d2c11',
68
+ seq: 4,
69
+ type: 'final',
70
+ payload: {
71
+ ok: true,
72
+ result: { name: 'Alice' },
73
+ stats: { durationMs: 120, toolCallCount: 1, stdoutBytes: 0 },
74
+ },
76
75
  };
77
76
  ```
78
77
 
79
- ### Session State
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`).
79
+
80
+ ### Identifiers and Session State
80
81
 
81
82
  ```typescript
82
- import { SessionState, SessionStatus } from '@enclave-vm/types';
83
+ import {
84
+ generateSessionId,
85
+ generateCallId,
86
+ isSessionId,
87
+ SessionState,
88
+ DEFAULT_SESSION_LIMITS,
89
+ } from '@enclave-vm/types';
83
90
 
84
- const session: SessionState = {
85
- id: 'session_abc',
86
- status: 'running',
87
- createdAt: new Date(),
88
- toolCallCount: 5,
89
- };
91
+ const sessionId = generateSessionId(); // 's_' followed by a UUID
92
+ const callId = generateCallId(); // 'c_' followed by a UUID
93
+
94
+ isSessionId(sessionId); // true
95
+
96
+ SessionState.Running; // 'running'
97
+ // 'starting' | 'running' | 'waiting_for_tool' | 'completed' | 'cancelled' | 'failed'
98
+
99
+ DEFAULT_SESSION_LIMITS.maxToolCalls; // 50
90
100
  ```
91
101
 
92
102
  ## Zod Schemas
93
103
 
94
- All types have corresponding Zod schemas for runtime validation:
104
+ The types have corresponding Zod schemas for runtime validation:
95
105
 
96
106
  ```typescript
97
- import { StreamMessageSchema, ToolCallMessageSchema, SessionStateSchema } from '@enclave-vm/types';
107
+ import { StreamEventSchema, parseStreamEvent } from '@enclave-vm/types';
98
108
 
99
109
  // Parse and validate
100
- const message = StreamMessageSchema.safeParse(untrustedData);
101
- if (message.success) {
102
- // message.data is typed correctly
103
- handleMessage(message.data);
110
+ const parsed = StreamEventSchema.safeParse(untrustedData);
111
+ if (parsed.success) {
112
+ // parsed.data is typed as StreamEvent
113
+ handleEvent(parsed.data);
104
114
  } else {
105
- console.error('Invalid message:', message.error);
115
+ console.error('Invalid event:', parsed.error);
106
116
  }
117
+
118
+ // The same, as a helper
119
+ const result = parseStreamEvent(untrustedData);
107
120
  ```
108
121
 
122
+ ## What the Package Does Not Do
123
+
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.
125
+
109
126
  ## Related Packages
110
127
 
111
- | Package | Description |
112
- | ------------------------------------------- | ---------------------------------- |
113
- | [@enclave-vm/stream](../enclavejs-stream) | Streaming protocol implementation |
114
- | [@enclave-vm/broker](../enclavejs-broker) | Tool broker and session management |
115
- | [@enclave-vm/client](../enclavejs-client) | Browser/Node.js client SDK |
116
- | [@enclave-vm/react](../enclavejs-react) | React hooks and components |
117
- | [@enclave-vm/runtime](../enclavejs-runtime) | Standalone runtime worker |
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) |
118
135
 
119
136
  ## License
120
137
 
package/encryption.d.ts CHANGED
@@ -2,7 +2,10 @@
2
2
  * @enclave-vm/types - Encryption types
3
3
  *
4
4
  * Types for per-hop encryption using ECDH + AES-GCM.
5
- * Encryption is optional but recommended to prevent intermediaries from reading payloads.
5
+ *
6
+ * These are the message shapes only. `@enclave-vm/stream` has the primitives that produce and
7
+ * read them; the client and the broker of this repository do not use them, so a session
8
+ * between the two is protected by its transport (TLS) alone.
6
9
  */
7
10
  import type { ProtocolVersion, SessionId } from './protocol.js';
8
11
  import type { EventType } from './events.js';
@@ -88,8 +91,9 @@ export interface ServerHello {
88
91
  /** Key ID for the derived session key */
89
92
  keyId: string;
90
93
  /**
91
- * Signature over the handshake transcript (base64 encoded).
92
- * Allows client to verify server identity if server has a pinned key.
94
+ * Reserved for a signature over the handshake transcript (base64 encoded).
95
+ * Nothing in this repository creates or verifies it: the key exchange of
96
+ * `@enclave-vm/stream` is not authenticated.
93
97
  */
94
98
  signatureB64?: string;
95
99
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@enclave-vm/types",
3
- "version": "2.19.1",
3
+ "version": "2.20.0-rc.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",
package/protocol.d.ts CHANGED
@@ -90,7 +90,9 @@ export interface SessionLimits {
90
90
  */
91
91
  maxToolResultBytes?: number;
92
92
  /**
93
- * Individual tool execution timeout in milliseconds.
93
+ * How long the session's script may run, in milliseconds: the broker passes it to the enclave
94
+ * as its `timeout`. The name is historical; the time one tool call may take is
95
+ * `perToolDeadlineMs` and the tool's own `ToolConfig.timeout`.
94
96
  * @default 30000 (30 seconds)
95
97
  */
96
98
  toolTimeoutMs?: number;
@@ -141,27 +143,30 @@ export declare const SessionState: {
141
143
  };
142
144
  export type SessionState = (typeof SessionState)[keyof typeof SessionState];
143
145
  /**
144
- * Tool configuration for timeout and retry behavior.
146
+ * Tool configuration. Only `timeout` has an effect; the other fields are part of the protocol's
147
+ * design and no package acts on them yet.
145
148
  */
146
149
  export interface ToolConfig {
147
150
  /**
148
- * Tool execution timeout in milliseconds.
149
- * Overrides session-level toolTimeoutMs.
151
+ * Tool execution timeout in milliseconds. The broker applies the lower of this and the
152
+ * session's `perToolDeadlineMs`.
150
153
  */
151
154
  timeout?: number;
152
155
  /**
153
156
  * Whether the tool can be retried on failure.
157
+ * Not implemented: no package retries a tool call.
154
158
  * @default false
155
159
  */
156
160
  retryable?: boolean;
157
161
  /**
158
162
  * Maximum number of retries if retryable is true.
163
+ * Not implemented (see `retryable`).
159
164
  * @default 3
160
165
  */
161
166
  maxRetries?: number;
162
167
  /**
163
168
  * Whether the tool result can be read by runtime code.
164
- * If false, result is always stored as a reference.
169
+ * Not implemented: a tool result is always delivered to the script.
165
170
  * @default true
166
171
  */
167
172
  runtimeReadable?: boolean;