@agent-phonon/protocol 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-phonon contributors
+
+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,70 @@
+# @agent-phonon/protocol
+
+> agent-phonon 的**线协议**——phonon 设备与服务端之间的唯一契约。
+> zod schema + TS 类型 + 方法注册表的单一事实来源。对应设计：[`../../docs/design.md`](../../docs/design.md)。
+
+## 是什么
+
+任何想调度本机 agent 的服务端，都通过这套协议和 phonon 通信。本包用 **zod** 定义全部消息形状，既是运行时校验、又是编译期类型，还能导出 **JSON Schema** 给非 TS 的服务端（Python/Go…）消费。
+
+## 传输模型（design D2）
+
+单条 **WebSocket** 上双向跑 **JSON-RPC 2.0**，两端皆可作 requester：
+
+| 方向 | 方法 |
+|------|------|
+| **phonon → server** (`p2s`) | `connect.hello`、`discovery.changed`、`stream.event`、`hook.fired` |
+| **server → phonon** (`s2p`) | `discovery.list/get`、`session.*`、`hook.resolve` |
+
+## 方法一览（33 个）
+
+```
+connect.hello        握手：协议版本 + 设备身份 → 服务端回 tenant 绑定
+discovery.list/get   发现：本机有哪些 agent 可用、各自哪些模型（design §5）
+discovery.changed    可用性变化时 phonon 主动推
+session.create       建会话，必须绑定 agent + model（D15）
+session.send         发任务＝对话；结果走 stream.event 异步流式回
+session.inject       上下文注入
+session.compress     压缩双模 native | custom（D7）
+session.terminate    结束会话
+session.status/list   查会话（始终携带 agent 身份）
+stream.event         phonon 上推流式结果（按 verbosity 分档）
+hook.fired           到 hook 点抛事件，阻塞等服务端裁决（HITL，design §8）
+hook.resolve         服务端裁决：continue | inject | modify | abort
+```
+
+## 核心设计点
+
+- **session 必绑 agent**（D15）：`session.create` 的 `agent`(来自 discovery 的 agentId) + `model` 必填，全生命周期携带。
+- **verbosity 4 档**：`final | messages | tools | trace`，控制返回内容多少。
+- **HITL 甩锅服务端**（design §8）：phonon 只做 `hook.fired` → 阻塞等 `hook.resolve`，问不问真人由服务端决定。
+- **tenant 隔离错误码**：`errSessionNotInTenant` 等，挂在 JSON-RPC `error.data.appCode`。
+- **方法注册表** `METHODS`：声明每个方法的 direction/kind/params/result，core 与 client-sdk 共享同一份，机器可校验。
+
+## 用法
+
+```ts
+import { parseParams, parseResult, METHODS, StreamEvent } from "@agent-phonon/protocol";
+
+// 校验入参
+const p = parseParams("session.create", { agent: "openclaw", model: "claude-opus-4.8" });
+
+// 取类型
+type CreateParams = import("@agent-phonon/protocol").ParamsOf<"session.create">;
+
+// 校验流式事件
+const ev = StreamEvent.parse(incoming);
+```
+
+## 脚本
+
+```bash
+pnpm build         # tsc → dist/
+pnpm typecheck     # 仅类型检查
+pnpm test          # build + node --test（10 个契约测试）
+pnpm json-schema   # 导出 dist/json-schema/*.json（供非 TS 服务端）
+```
+
+## 状态
+
+🚧 **v0.0.1 草案** — 协议仍在和需求方对齐中，字段可能调整。未发布。

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @agent-phonon/protocol
+ *
+ * agent-phonon 的线协议——phonon 设备与服务端之间的唯一契约。
+ * zod schema + 类型 + 方法注册表的单一事实来源（design docs/design.md）。
+ */
+export * from "./schemas/common.js";
+export * from "./schemas/capabilities.js";
+export * from "./schemas/discovery.js";
+export * from "./schemas/session.js";
+export * from "./schemas/stream.js";
+export * from "./schemas/hook.js";
+export * from "./schemas/document.js";
+export * from "./schemas/interaction.js";
+export * from "./schemas/project.js";
+export * from "./schemas/skill.js";
+export * from "./schemas/policy.js";
+export * from "./schemas/connect.js";
+export * from "./schemas/device.js";
+export * from "./schemas/file.js";
+export * from "./schemas/env.js";
+export * from "./schemas/jsonrpc.js";
+export * from "./schemas/methods.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * @agent-phonon/protocol
+ *
+ * agent-phonon 的线协议——phonon 设备与服务端之间的唯一契约。
+ * zod schema + 类型 + 方法注册表的单一事实来源（design docs/design.md）。
+ */
+export * from "./schemas/common.js";
+export * from "./schemas/capabilities.js";
+export * from "./schemas/discovery.js";
+export * from "./schemas/session.js";
+export * from "./schemas/stream.js";
+export * from "./schemas/hook.js";
+export * from "./schemas/document.js";
+export * from "./schemas/interaction.js";
+export * from "./schemas/project.js";
+export * from "./schemas/skill.js";
+export * from "./schemas/policy.js";
+export * from "./schemas/connect.js";
+export * from "./schemas/device.js";
+export * from "./schemas/file.js";
+export * from "./schemas/env.js";
+export * from "./schemas/jsonrpc.js";
+export * from "./schemas/methods.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC"}