@futurity/chat-protocol 0.0.1 → 0.1.0

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 +115 -0
  2. package/package.json +7 -3
package/README.md ADDED
@@ -0,0 +1,115 @@
1
+ # @futurity/chat-protocol
2
+
3
+ Framework-agnostic, browser-safe wire-format definitions for the Futurity chat WebSocket protocol. All schemas are defined with [Zod](https://zod.dev) v4.
4
+
5
+ Most integrators should use [`@futurity/chat-react`](https://www.npmjs.com/package/@futurity/chat-react) instead, which wraps this package with React hooks and a managed WebSocket connection. Use `@futurity/chat-protocol` directly if you're building a non-React client or need only the type definitions.
6
+
7
+ ## Installation
8
+
9
+ ```bash
10
+ npm install @futurity/chat-protocol zod
11
+ ```
12
+
13
+ `zod` is a peer dependency (^4.0.0).
14
+
15
+ ## What's Inside
16
+
17
+ ### Message Parts (`MessagePart`)
18
+
19
+ The `MessagePart` union describes every content block that can appear in a chat message's `parts` array:
20
+
21
+ | Type | Description |
22
+ |------|-------------|
23
+ | `text` | Plain text (with optional `state: "streaming" \| "done"`) |
24
+ | `reasoning` | Model reasoning/thinking content |
25
+ | `source-url` | URL citation |
26
+ | `source-document` | Document citation |
27
+ | `file` | Attached file (media type + URL) |
28
+ | `step-start` | Step boundary marker |
29
+ | `data-*` | Extensible data parts (status indicators, screenshots, sub-agent markers, etc.) |
30
+ | `tool-*` | Static tool invocations (keyed by tool name) |
31
+ | `dynamic-tool` | Dynamic tool invocations (tool name in `toolName` field) |
32
+
33
+ Tool invocations follow a lifecycle via the `state` discriminator: `input-streaming` -> `input-available` -> `approval-requested` -> `approval-responded` -> `output-available` / `output-error` / `output-denied`.
34
+
35
+ ```ts
36
+ import { Z_MessagePart, type MessagePart } from "@futurity/chat-protocol";
37
+
38
+ // Validate a part
39
+ const result = Z_MessagePart.safeParse(rawPart);
40
+
41
+ // Type-narrow when rendering
42
+ function renderPart(part: MessagePart) {
43
+ switch (part.type) {
44
+ case "text":
45
+ return part.text;
46
+ case "reasoning":
47
+ return part.text;
48
+ case "file":
49
+ return `${part.mediaType}: ${part.url}`;
50
+ // ...
51
+ }
52
+ }
53
+ ```
54
+
55
+ ### WebSocket Commands (Client -> Server)
56
+
57
+ | Type | Schema | Description |
58
+ |------|--------|-------------|
59
+ | `run` | `wsRunCommandSchema` | Send a user message |
60
+ | `get_chat` | `wsGetChatCommandSchema` | Request chat history |
61
+ | `cancel` | `wsCancelCommandSchema` | Cancel an active job |
62
+ | `clarify_response` | `wsClarifyResponseCommandSchema` | Respond to a clarification request |
63
+ | `inject_message` | `wsInjectMessageCommandSchema` | Inject text into an active stream |
64
+
65
+ ```ts
66
+ import type { WsClientCommand } from "@futurity/chat-protocol";
67
+
68
+ const cmd: WsClientCommand = {
69
+ type: "run",
70
+ data: {
71
+ id: chatId,
72
+ message: { id: msgId, role: "user", parts: [{ type: "text", text: "Hello" }] },
73
+ vaultItems: [],
74
+ timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
75
+ },
76
+ };
77
+ ```
78
+
79
+ ### WebSocket Messages (Server -> Client)
80
+
81
+ | Type | Schema | Description |
82
+ |------|--------|-------------|
83
+ | `ready` | `wsReadyMessageSchema` | Connection established |
84
+ | `run` | `wsRunMessageSchema` | Job started (returns `job_id` + `message_id`) |
85
+ | `stream` | `wsStreamMessageSchema` | Streaming delta (one message part) |
86
+ | `stream_resume` | `wsStreamResumeMessageSchema` | Accumulated parts after reconnect |
87
+ | `chat_history` | `wsChatHistoryMessageSchema` | Full chat history |
88
+ | `done` | `wsDoneMessageSchema` | Job complete |
89
+ | `cancel` | `wsCancelMessageSchema` | Cancel acknowledgment |
90
+ | `error` | `wsErrorMessageSchema` | Protocol error |
91
+ | `clarify_request` | `wsClarifyRequestMessageSchema` | Server asks clarifying questions |
92
+ | `inject_ack` | `wsInjectAckMessageSchema` | Inject acknowledged |
93
+ | `inject_split` | `wsInjectSplitMessageSchema` | Inject caused a message split |
94
+
95
+ ```ts
96
+ import { wsServerMessageSchema, type WsServerMessage } from "@futurity/chat-protocol";
97
+
98
+ // Validate incoming messages
99
+ const result = wsServerMessageSchema.safeParse(JSON.parse(event.data));
100
+ if (result.success) {
101
+ const msg: WsServerMessage = result.data;
102
+ switch (msg.type) {
103
+ case "stream":
104
+ // msg.delta is a MessagePart
105
+ break;
106
+ case "done":
107
+ // streaming complete
108
+ break;
109
+ }
110
+ }
111
+ ```
112
+
113
+ ## License
114
+
115
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@futurity/chat-protocol",
3
- "version": "0.0.1",
3
+ "version": "0.1.0",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "sideEffects": false,
@@ -12,11 +12,15 @@
12
12
  },
13
13
  "main": "./dist/index.js",
14
14
  "types": "./dist/index.d.ts",
15
- "files": ["dist", "src", "README.md"],
15
+ "files": [
16
+ "dist",
17
+ "src",
18
+ "README.md"
19
+ ],
16
20
  "scripts": {
17
21
  "build": "tsup",
18
22
  "check": "tsgo --noEmit",
19
- "prepublishOnly": "tsup"
23
+ "prepublishOnly": "bunx tsup"
20
24
  },
21
25
  "peerDependencies": {
22
26
  "zod": "^4.0.0"