@enclave-vm/types 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 +71 -54
- package/encryption.d.ts +7 -3
- package/package.json +1 -1
- package/protocol.d.ts +10 -5
package/README.md
CHANGED
|
@@ -29,92 +29,109 @@ pnpm add @enclave-vm/types
|
|
|
29
29
|
## Quick Start
|
|
30
30
|
|
|
31
31
|
```typescript
|
|
32
|
-
import {
|
|
33
|
-
|
|
34
|
-
// Type-safe
|
|
35
|
-
function
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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
|
|
44
|
+
## Protocol
|
|
50
45
|
|
|
51
|
-
### Stream
|
|
46
|
+
### Stream Events
|
|
52
47
|
|
|
53
|
-
|
|
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 {
|
|
51
|
+
import { PROTOCOL_VERSION, type ToolCallEvent, type FinalEvent } from '@enclave-vm/types';
|
|
64
52
|
|
|
65
|
-
const toolCall:
|
|
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
|
-
|
|
68
|
-
|
|
69
|
-
|
|
58
|
+
payload: {
|
|
59
|
+
callId: 'c_9a55e2f6-4c57-1c1b-3f0e-0a8b5a3d2c11',
|
|
60
|
+
toolName: 'getUser',
|
|
61
|
+
args: { userId: 1 },
|
|
62
|
+
},
|
|
70
63
|
};
|
|
71
64
|
|
|
72
|
-
const
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
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
|
-
|
|
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 {
|
|
83
|
+
import {
|
|
84
|
+
generateSessionId,
|
|
85
|
+
generateCallId,
|
|
86
|
+
isSessionId,
|
|
87
|
+
SessionState,
|
|
88
|
+
DEFAULT_SESSION_LIMITS,
|
|
89
|
+
} from '@enclave-vm/types';
|
|
83
90
|
|
|
84
|
-
const
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
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
|
-
|
|
104
|
+
The types have corresponding Zod schemas for runtime validation:
|
|
95
105
|
|
|
96
106
|
```typescript
|
|
97
|
-
import {
|
|
107
|
+
import { StreamEventSchema, parseStreamEvent } from '@enclave-vm/types';
|
|
98
108
|
|
|
99
109
|
// Parse and validate
|
|
100
|
-
const
|
|
101
|
-
if (
|
|
102
|
-
//
|
|
103
|
-
|
|
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
|
|
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
|
|
112
|
-
|
|
|
113
|
-
| [@enclave-vm/stream](../
|
|
114
|
-
| [@enclave-vm/broker](../
|
|
115
|
-
| [@enclave-vm/client](../
|
|
116
|
-
| [@enclave-vm/react](../
|
|
117
|
-
| [@enclave-vm/runtime](../
|
|
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
|
-
*
|
|
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
|
-
*
|
|
92
|
-
*
|
|
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.
|
|
3
|
+
"version": "2.19.2",
|
|
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
|
-
*
|
|
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
|
|
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
|
-
*
|
|
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
|
-
*
|
|
169
|
+
* Not implemented: a tool result is always delivered to the script.
|
|
165
170
|
* @default true
|
|
166
171
|
*/
|
|
167
172
|
runtimeReadable?: boolean;
|