@ai-matrx/desktop-protocol 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 0.1.0
+
+First release — the Matrx 2 phone slice, lane A.
+
+- Protocol v1 schemas (zod 4), promoted from the accepted draft: the SPEC §4 envelope, the §5 error
+  model plus `PROTOCOL_VERSION_UNSUPPORTED`, `PROTOCOL_ERROR`, `UNKNOWN_OPERATION`,
+  `DEVICE_OFFLINE`, `PAYLOAD_TOO_LARGE` and a typed `reason`, and every `cap.op` of `sysinfo`,
+  `fs`, `exec` and `session`, with the `OPS` / `EVENTS` registries.
+- `./frame` — zod-free 16-byte frame codec (`encodeFrame`, `decodeFrame`, `stampCid`, `readCid`).
+- `./client` — `createDesktopClient`: hello, typed requests, credit-gated streams and STDIN,
+  transparent reattach with `since_seq`, heartbeat, relay reauth; reconnect via
+  `@ai-matrx/realtime`'s `createBackoff`.
+- `./react` — `DesktopClientProvider`, `useDesktopConnection`, `useDesktopRequest`,
+  `useDesktopEvent`.
+- Generated twins: `generated/desktop-protocol.schema.json` and
+  `aidream/_generated/desktop_protocol.py` (Pydantic, `StrictModel` base, `OPS`/`EVENTS`,
+  `validate_wire`), held identical by `pnpm generate --check`.
+
+Defects found in the draft and fixed here (not preserved):
+
+- **Case 19** — Pydantic accepted an explicit `null` on an optional, non-nullable field that zod
+  refuses. Fixed by the generated `StrictModel` base.
+- **`DeviceId`** was `z.uuid()`, which generated `Annotated[UUID, Field(pattern=…)]` — a model
+  Pydantic can never validate, so `Welcome` and `SysinfoGetResult` were unusable in Python. Now a
+  plain uuid pattern; `generate` refuses `format` + `pattern` on one node.
+- **Integral floats** — `2.0` is the integer 2 to zod (JSON.parse) but not to strict Pydantic.
+  `validate_wire` mirrors JavaScript.
+- `.meta({ id })` wrote zod's process-global registry at import time; names now come from
+  `NAMED_SCHEMAS` into a private registry, and the lint bans `.meta`/`.describe`.
+
+### Consumer action
+
+None — new package.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Matrix Engine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# `@ai-matrx/desktop-protocol`
+
+**The one wire contract between Matrx 2 (the desktop app) and everything that drives it** — the
+phone console, the web app, the extension and the server. One zod source; a generated JSON Schema
+and Pydantic twin that CI keeps byte-identical (SPEC P11: contracts are generated, never written
+twice).
+
+```bash
+pnpm add @ai-matrx/desktop-protocol
+```
+
+| Entry | What it is |
+|---|---|
+| `@ai-matrx/desktop-protocol` | Schemas for the envelope and every `cap.op`, `OPS` / `EVENTS` registries, `ErrorCode`, close codes, `DesktopProtocolError`. Every schema name is also its inferred type. |
+| `@ai-matrx/desktop-protocol/frame` | The 16-byte binary frame codec. Zod-free (the relay Worker's hot path). |
+| `@ai-matrx/desktop-protocol/client` | `createDesktopClient` — reconnecting client with typed requests, credit-gated streams, transparent terminal reattach, heartbeat and relay reauth. |
+| `@ai-matrx/desktop-protocol/react` | `DesktopClientProvider`, `useDesktopConnection`, `useDesktopRequest`, `useDesktopEvent`. |
+
+## Client
+
+```ts
+import { createDesktopClient } from "@ai-matrx/desktop-protocol/client";
+
+const client = createDesktopClient({
+  url: `wss://relay.matrxserver.com/v1/devices/${deviceId}/connect`,
+  // Re-read on every reconnect; tokens ride the subprotocol, never the URL.
+  protocols: async () => ["matrx.v1", `bearer.${await getAccessToken()}`],
+  getToken: getAccessToken, // answers relay.auth_expiring without dropping the socket
+  clientType: "web",
+  clientVersion: "1.0.0",
+});
+
+const listing = await client.request("fs.list", { path: "/Users/me" }); // typed by op name
+
+const term = client.stream("exec.pty.start", { cols: 80, rows: 24 }, {
+  onData: (bytes) => new Promise((done) => xterm.write(bytes, done)), // credit follows consumption
+  onSnapshot: (bytes) => {
+    xterm.reset();
+    xterm.write(bytes);
+  },
+});
+term.write("ls\n");
+```
+
+- **Backpressure:** credit for a stream is granted only after `onData` returns (or its promise
+  settles), so a slow phone never makes the relay or the Mac buffer without bound.
+- **Reattach:** a resource stream (terminal, watch) survives a dropped socket. On reconnect the
+  client sends `session.attach` with `since_seq` = the last frame your `onData` consumed; the core
+  replays the gap or sends `gap` + a screen snapshot. The same `DesktopStream` keeps working.
+- **Errors** are `DesktopProtocolError` with `code`, `retryable` and `data.reason` — branch on
+  those, never on messages. A dropped socket rejects unary work with `DEVICE_OFFLINE` (retryable).
+- **Terminal closes** (`4010` revoked, `4003` forbidden, `4004` not found, `4009` replaced, `4426`
+  upgrade) end the client for good; everything else reconnects with the shared
+  `@ai-matrx/realtime` backoff (stability reset + jitter).
+- Background problems (malformed messages, sequence gaps, heartbeat death, reconnect alarm) go to
+  `onDiagnostic` — loud by default (`console.warn`).
+
+## React
+
+```tsx
+<DesktopClientProvider client={client}>
+  <Files />
+</DesktopClientProvider>
+
+function Files() {
+  const { status } = useDesktopConnection();
+  const { data, error, loading, refetch } = useDesktopRequest("fs.list", { path: "/Users/me" });
+  useDesktopEvent("fs.changed", () => void refetch());
+}
+```
+
+## Python (aidream)
+
+```python
+from aidream._generated.desktop_protocol import OPS, FsListParams, validate_wire
+
+params = validate_wire(FsListParams, raw_json)  # same verdict as zod, always
+```
+
+`validate_wire` is the one Python entry point: strict (no `"2"` → 2) and JavaScript-faithful
+(`2.0` is the integer 2). `OPS` maps every op to its params/result models, kind and errors.
+
+## Changing the protocol
+
+Edit `src/schema/*.ts`, then `pnpm generate` and commit all three files. Rules (enforced by
+`pnpm lint` and by `generate`): `z.strictObject` only; no `.refine`/`.transform`/`z.coerce`/
+`.meta`; never optional and nullable at once; a new named schema goes into `NAMED_SCHEMAS`; add a
+parity case to `corpus/parity-corpus.json` for any new wire shape.
+
+MIT © AI Matrix Engine