@av-pi-studio/protocol 0.0.3 → 0.0.4
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 +98 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# `@av-pi-studio/protocol`
|
|
2
|
+
|
|
3
|
+
Shared wire schemas, binary frame codecs, and capability flags for Pi-Studio. This package is the
|
|
4
|
+
**single source of truth for everything that crosses the WebSocket** between the daemon and any
|
|
5
|
+
client (CLI, web, mobile, desktop).
|
|
6
|
+
|
|
7
|
+
It is a **zero-runtime-workspace-dependency** library — the only external dependency is `zod` —
|
|
8
|
+
so it can be imported by browser and React Native clients as freely as by the Node.js daemon.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm install @av-pi-studio/protocol
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## What's in here
|
|
19
|
+
|
|
20
|
+
- **JSON wire schemas** (`messages.ts`) — every message type that can appear on the WebSocket,
|
|
21
|
+
as [Zod](https://zod.dev) schemas plus their inferred TypeScript types: the `hello`/`status`
|
|
22
|
+
handshake, RPC requests/responses, broadcasts (`agent_update`, `agent_stream`, …), and the
|
|
23
|
+
top-level envelope union that wraps them all.
|
|
24
|
+
- **Binary frame codecs** (`binary-frames/`) — encode/decode functions for the two binary wire
|
|
25
|
+
formats: terminal I/O (`[opcode][slot][payload]`) and chunked file transfer. Both use
|
|
26
|
+
`Uint8Array`, never `Buffer`, so they run unchanged in a browser.
|
|
27
|
+
- **Client capability flags** (`client-capabilities.ts`) — `CLIENT_CAPS` (what a client can
|
|
28
|
+
advertise in `hello.capabilities`) and `SERVER_FEATURES` (what the daemon advertises in
|
|
29
|
+
`server_info.features`), plus a `supports()` helper.
|
|
30
|
+
- **Endpoint parsing** (`endpoint.ts`) — turns a daemon target string (`host:port`, `ws://…`,
|
|
31
|
+
`relay://…`) into a structured `EndpointDescriptor`.
|
|
32
|
+
- **Provider manifest types** (`provider-manifest.ts`) — UI-facing scaffolding for describing
|
|
33
|
+
providers/modes (labels, color tiers, capability flags).
|
|
34
|
+
|
|
35
|
+
## Usage
|
|
36
|
+
|
|
37
|
+
```ts
|
|
38
|
+
import {
|
|
39
|
+
helloSchema,
|
|
40
|
+
agentStreamEventSchema,
|
|
41
|
+
encodeTerminalFrame,
|
|
42
|
+
decodeTerminalFrame,
|
|
43
|
+
parseEndpoint,
|
|
44
|
+
rpcName,
|
|
45
|
+
} from "@av-pi-studio/protocol";
|
|
46
|
+
|
|
47
|
+
// Validate + parse an inbound message
|
|
48
|
+
const hello = helloSchema.parse(rawJson);
|
|
49
|
+
|
|
50
|
+
// Build a canonical dotted RPC name
|
|
51
|
+
const name = rpcName("agent", "permission", "respond", "request");
|
|
52
|
+
// → "agent.permission.respond.request"
|
|
53
|
+
|
|
54
|
+
// Parse a daemon connection target
|
|
55
|
+
const endpoint = parseEndpoint("workstation.local:6767");
|
|
56
|
+
// → { kind: "direct", host: "workstation.local", port: 6767, ssl: false, raw: "…" }
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Every exported schema has a paired TypeScript type (`XSchema` / `X`), inferred with `z.infer<>` —
|
|
60
|
+
import whichever you need.
|
|
61
|
+
|
|
62
|
+
## Design rules
|
|
63
|
+
|
|
64
|
+
These are enforced by convention and by the package's own tests, not by tooling:
|
|
65
|
+
|
|
66
|
+
- **Append-only.** Fields are only ever added, and only as optional. Nothing is ever removed,
|
|
67
|
+
narrowed, or given a new discriminant value. This is what lets an older daemon load data
|
|
68
|
+
written by a newer one (and vice versa) without a migration step.
|
|
69
|
+
- **Schema passthrough.** Most schemas use Zod's `.passthrough()`, so unknown fields from a newer
|
|
70
|
+
protocol version survive a round-trip through an older decoder instead of being stripped or
|
|
71
|
+
rejected.
|
|
72
|
+
- **Zero workspace imports.** This package never imports from another `@av-pi-studio/*` package —
|
|
73
|
+
it has to stay usable standalone by any future client, including ones that don't otherwise
|
|
74
|
+
depend on the rest of the monorepo.
|
|
75
|
+
- **Cross-platform binary codecs.** The binary frame encode/decode functions only use
|
|
76
|
+
`Uint8Array` — no Node-only APIs — so they work identically in Node, the browser, and React
|
|
77
|
+
Native.
|
|
78
|
+
- **Dotted RPC names.** New RPCs are named via `rpcName(domain, sub, op, dir)` →
|
|
79
|
+
`"domain.provider.operation.direction"` (e.g. `agent.permission.respond.request`). Legacy flat
|
|
80
|
+
names are still accepted on the wire via aliases, but never generated by new code.
|
|
81
|
+
|
|
82
|
+
## Adding a new wire message type
|
|
83
|
+
|
|
84
|
+
1. Define the Zod schema (and its inferred type) in `messages.ts` or a new sibling file.
|
|
85
|
+
2. Add it to the `sessionMessageSchema` discriminated union.
|
|
86
|
+
3. Export it from `index.ts`.
|
|
87
|
+
4. Add a round-trip test (`messages.envelopes.test.ts` or a new `*.test.ts`).
|
|
88
|
+
5. Register the corresponding handler in the daemon's `HandlerRegistry`
|
|
89
|
+
(`@av-pi-studio/server`).
|
|
90
|
+
|
|
91
|
+
## Development
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
npm run build # tsc -b
|
|
95
|
+
npm test -- --project packages/protocol
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Tests are Vitest and live alongside their source files as `*.test.ts`.
|