@agent-phonon/protocol 0.2.0

package/dist/schemas/stream.js

@@ -0,0 +1,133 @@
+import { z } from "zod";
+import { SessionId, Timestamp } from "./common.js";
+/**
+ * 流式事件（design §4 / §6 / 订阅模型）——phonon → server 异步推送。
+ *
+ * 关键：session 不只是「请求-响应」，还是一条**可订阅的持续输出流**。
+ * 输出分两种来源（origin）：
+ *   - solicited  ：某次 session.send 触发的响应（用 send 返回的 turnId）。
+ *   - unsolicited：agent 自发输出（OpenClaw 的 cron/定时/心跳），无 send 触发；
+ *                  turnId 由 phonon 生成，source 标明冲泡来源。
+ *
+ * “create 即订阅”：server 拥有的 session 的**所有** stream.event（含自发）都自动
+ * 推给该 tenant 连接，无需显式 subscribe。Codex 一次性 session 流到 result final 就停；
+ * OpenClaw 持久 session 即使不 send 也会持续往上冒。
+ *
+ * 不同事件对应不同 verbosity 档位：
+ *   final    → 只会收到 result
+ *   messages → message + result
+ *   tools    → message + tool_call + tool_result + result
+ *   trace    → 以上 + thinking + token delta
+ */
+/** 输出来源：请求触发 vs agent 自发。 */
+export const StreamOrigin = z.enum(["solicited", "unsolicited"]);
+/** 事件种类。 */
+export const StreamEventType = z.enum([
+    "message", // 一条完整/增量消息文本
+    "thinking", // 思考过程（trace 档）
+    "tool_call", // agent 发起工具调用
+    "tool_result", // 工具返回
+    "token", // 增量 token（流式打字机，trace/可选）
+    "result", // 本轮最终结果（终止事件）
+    "error", // 本轮出错（终止事件）
+]);
+const StreamEventBase = z.object({
+    sessionId: SessionId,
+    /**
+     * 本轮关联 id。solicited 事件用 send 返回的 turnId；
+     * unsolicited（自发）事件由 phonon 生成，server 从事件中首次见到。
+     */
+    turnId: z.string(),
+    /** 输出来源：默认 solicited；agent 自发为 unsolicited。 */
+    origin: StreamOrigin.default("solicited"),
+    /** unsolicited 时的冲泡来源标签，如 "cron" / "scheduled" / "heartbeat"。 */
+    source: z.string().optional(),
+    /** 单调递增序号（按 session），保证调用方可排序/去重。 */
+    seq: z.number().int().nonnegative(),
+    at: Timestamp,
+});
+export const StreamMessageEvent = StreamEventBase.extend({
+    type: z.literal("message"),
+    role: z.enum(["assistant", "user", "system"]).default("assistant"),
+    text: z.string(),
+    /** 是否为增量分片（true 表示需要与同 turn 的后续 message 拼接）。 */
+    delta: z.boolean().default(false),
+});
+export const StreamThinkingEvent = StreamEventBase.extend({
+    type: z.literal("thinking"),
+    text: z.string(),
+    delta: z.boolean().default(false),
+});
+export const StreamToolCallEvent = StreamEventBase.extend({
+    type: z.literal("tool_call"),
+    toolName: z.string(),
+    /** 工具入参（原样透传，结构由 agent/工具决定）。 */
+    args: z.unknown().optional(),
+    /** 工具调用 id，用于和 tool_result 配对。 */
+    toolCallId: z.string().optional(),
+});
+export const StreamToolResultEvent = StreamEventBase.extend({
+    type: z.literal("tool_result"),
+    toolName: z.string(),
+    toolCallId: z.string().optional(),
+    ok: z.boolean(),
+    /** 工具输出（可能被截断，取决于 verbosity/大小限制）。 */
+    output: z.unknown().optional(),
+});
+export const StreamTokenEvent = StreamEventBase.extend({
+    type: z.literal("token"),
+    text: z.string(),
+});
+export const StreamResultEvent = StreamEventBase.extend({
+    type: z.literal("result"),
+    /** 本轮最终文本结果。 */
+    text: z.string(),
+    /** 可选 usage 统计。 */
+    usage: z
+        .object({
+        inputTokens: z.number().int().nonnegative().optional(),
+        outputTokens: z.number().int().nonnegative().optional(),
+    })
+        .optional(),
+    /**
+     * 本轮终态（P0-2）——每个 turn 必须有明确终态，服务端状态机才不会悬空：
+     * completed   正常完成
+     * interrupted 被 session.interrupt 打断
+     * aborted     被 hook abort / 主动中止
+     * failed      出错终止（详情另见 error 事件）
+     * timeout     超时
+     */
+    status: z.enum(["completed", "interrupted", "aborted", "failed", "timeout"]).default("completed"),
+    /** 标记本轮结束。 */
+    final: z.literal(true),
+});
+export const StreamErrorEvent = StreamEventBase.extend({
+    type: z.literal("error"),
+    message: z.string(),
+    /** 可选应用错误码（与 common.PhononErrorCode 对齐）。 */
+    appCode: z.string().optional(),
+    /** 终态（与 result.status 对齐，错误场景通常 failed/aborted/timeout）。 */
+    status: z.enum(["failed", "aborted", "timeout", "interrupted"]).default("failed"),
+    final: z.literal(true),
+});
+// ---------------------------------------------------------------------------
+// stream.ack —— server → phonon，确认已收到 seq <= lastSeq（P0-4）
+// 让 phonon 能清理 outbox / 控制背压；可按 session 粒度或全局。
+// ---------------------------------------------------------------------------
+export const StreamAckParams = z.object({
+    /** 按 session 确认；缺省表示该连接全局。 */
+    sessionId: SessionId.optional(),
+    /** 已收到的最大连续 seq（含）；phonon 可清理 <= 此值的 outbox。 */
+    lastSeq: z.number().int().nonnegative(),
+});
+/** 流式事件联合体（phonon → server，方法名 stream.event）。 */
+export const StreamEvent = z.discriminatedUnion("type", [
+    StreamMessageEvent,
+    StreamThinkingEvent,
+    StreamToolCallEvent,
+    StreamToolResultEvent,
+    StreamTokenEvent,
+    StreamResultEvent,
+    StreamErrorEvent,
+]);
+//# sourceMappingURL=stream.js.map

package/dist/schemas/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/schemas/stream.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@agent-phonon/protocol",
+  "version": "0.2.0",
+  "description": "Wire protocol (zod schemas + types) for agent-phonon — the single source of truth contract between phonon devices and servers.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!dist/__tests__/**",
+    "!src/__tests__/**",
+    "!**/*.test.ts",
+    "!**/*.test.js",
+    "!**/*.test.d.ts"
+  ],
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "22",
+    "typescript": "^5.6.3",
+    "zod-to-json-schema": "^3.23.5"
+  },
+  "author": "agent-phonon contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hackerphysics/agent-phonon.git",
+    "directory": "packages/protocol"
+  },
+  "homepage": "https://github.com/hackerphysics/agent-phonon#readme",
+  "bugs": {
+    "url": "https://github.com/hackerphysics/agent-phonon/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm build && node --test dist/__tests__/*.test.js",
+    "json-schema": "pnpm build && node scripts/gen-json-schema.mjs"
+  }
+}

package/src/index.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";

package/src/schemas/capabilities.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+
+/**
+ * Hook 类型 — 归一化的拦截点（design §8）。
+ * adapter 负责把各家原生 hook 点（Codex hooks / Claude Code PreToolUse /
+ * OpenClaw 审批…）映射成这些归一化类型。
+ */
+export const HookType = z.enum([
+  "pre_tool", // 工具调用前
+  "post_tool", // 工具调用后
+  "pre_command", // 执行 shell/命令前（rm/git push 等危险操作）
+  "pre_file_write", // 写文件前
+  "pre_network", // 发起网络/外部请求前
+  "session_start", // 会话开始
+  "session_end", // 会话结束
+  "notification", // agent 主动通知（无需裁决，纯告知）
+]);
+export type HookType = z.infer<typeof HookType>;
+
+/**
+ * Adapter 能力声明（design §7）。
+ * adapter 不假装统一，而是声明自己原生支持什么，phonon core 据此补齐缺口。
+ * 这份能力随 discovery 一起暴露给服务端，服务端先知能力再决定怎么用。
+ */
+export const AgentCapabilities = z.object({
+  /** 原生 session / resume（无则由 core 用注册表模拟）。 */
+  nativeSession: z.boolean(),
+  /** 原生上下文压缩（决定 session.compress mode=native 是否可用）。 */
+  nativeCompression: z.boolean(),
+  /** 原生上下文注入。 */
+  contextInjection: z.boolean(),
+  /**
+   * 是否会**主动/非请求触发地输出**（design 订阅模型）。
+   * OpenClaw 这类有 cron/心跳/定时任务，同一 session 内会不定期自发冲泡 → true；
+   * Codex 这类一次性，流到结果就结束 → false。
+   * server 据此判断哪些 session 需要长期保持监听。
+   */
+  proactiveOutput: z.boolean(),
+  /** 是否支持同会话中途切换模型（design D16）。 */
+  modelSwitch: z.boolean(),
+  /** 是否支持打断正在进行的 turn（session.interrupt / whenBusy=interrupt，D18）。 */
+  interrupt: z.boolean(),
+  /** 是否支持中途插入输入（下一次 tool call 边界，whenBusy=inject，D18）。 */
+  injectMidTurn: z.boolean(),
+  /** 是否支持给该 agent 安装/卸载 skill（skill.* 接口，D24）。 */
+  skillManagement: z.boolean(),
+  /** 原生支持的 hook 点（其余由 core 尽力补齐或不支持）。 */
+  hooks: z.array(HookType),
+  /** 是否支持流式输出。 */
+  streaming: z.boolean(),
+  /**
+   * 可选调度限制（P2-13）：server 据此做调度/背压。
+   */
+  limits: z
+    .object({
+      maxConcurrentSessions: z.number().int().positive().optional(),
+      maxContextTokens: z.number().int().positive().optional(),
+      maxMessageBytes: z.number().int().positive().optional(),
+    })
+    .optional(),
+});
+export type AgentCapabilities = z.infer<typeof AgentCapabilities>;

package/src/schemas/common.ts

@@ -0,0 +1,119 @@
+import { z } from "zod";
+
+/**
+ * agent-phonon wire protocol — shared primitives.
+ *
+ * 设计参考 docs/design.md。本文件定义全协议复用的基础类型：
+ * 协议版本、各类 ID、verbosity、错误码。
+ */
+
+/** 协议语义版本。device 与 server 握手时比对（见 connect.hello）。 */
+export const PROTOCOL_VERSION = "0.1.0" as const;
+
+// ---------------------------------------------------------------------------
+// ID 原语（全部是不透明字符串，调用方不应解析其结构）
+// ---------------------------------------------------------------------------
+
+/** phonon 侧全局唯一的 session id（归属某一 tenant）。 */
+export const SessionId = z.string().min(1).brand<"SessionId">();
+export type SessionId = z.infer<typeof SessionId>;
+
+/** discovery 返回的 agent 标识，也是 session.create 的 `agent` 入参。 */
+export const AgentId = z.string().min(1).brand<"AgentId">();
+export type AgentId = z.infer<typeof AgentId>;
+
+/** 项目标识（项目 = 目录 + Git）。所有 session 必须绑定一个项目。 */
+export const ProjectId = z.string().min(1).brand<"ProjectId">();
+export type ProjectId = z.infer<typeof ProjectId>;
+
+/** 本地配置赋予的稳定租户 id（= 一条服务端连接，见 design D13）。 */
+export const TenantId = z.string().min(1).brand<"TenantId">();
+export type TenantId = z.infer<typeof TenantId>;
+
+/** 设备自身标识（一台设备一个，用于服务端区分多设备，但 phonon 不感知其他设备）。 */
+export const DeviceId = z.string().min(1).brand<"DeviceId">();
+export type DeviceId = z.infer<typeof DeviceId>;
+
+// ---------------------------------------------------------------------------
+// Verbosity — 控制 session 返回内容的多少（design §4）
+// ---------------------------------------------------------------------------
+
+/**
+ * 4 档详细度，create 时设定、send 可覆盖：
+ * - final    : 仅最终结果
+ * - messages : 每轮消息
+ * - tools    : 含工具调用
+ * - trace    : 全量（含思考）
+ */
+export const Verbosity = z.enum(["final", "messages", "tools", "trace"]);
+export type Verbosity = z.infer<typeof Verbosity>;
+
+// ---------------------------------------------------------------------------
+// 错误码 — JSON-RPC error.data.code 用（design 中提到的归一化错误）
+// ---------------------------------------------------------------------------
+
+/**
+ * 应用级错误码（区别于 JSON-RPC 传输级 code）。
+ * 放在 JSON-RPC error 对象的 `data.appCode` 字段，便于调用方稳定判别。
+ */
+export const PhononErrorCode = z.enum([
+  // 协议/握手
+  "errProtocolMismatch", // device 与 server 协议版本不兼容
+  "errUnauthorized", // device key 无效（注：终端用户鉴权在 server，不在此）
+  // 租户隔离（design §6 / D13）
+  "errSessionNotInTenant", // 跨租户访问 session
+  "errTenantQuotaExceeded", // 触达 per-tenant 配额
+  "errDeviceQuotaExceeded", // 触达全局配额
+  // 发现 / agent 绑定（design §5 / D14 / D15）
+  "errAgentUnavailable", // 目标 agent 不存在或不可用
+  "errModelUnavailable", // 模型不在该 agent 的可用列表内
+  // session 生命周期
+  "errSessionNotFound",
+  "errSessionTerminated", // 操作了已结束的 session
+  "errSessionBusy", // session 正忙（如上一轮未结束）
+  // 能力
+  "errCapabilityUnsupported", // adapter 不支持该操作（如 native 压缩缺失）
+  // hook / HITL
+  "errHookResolveInvalid", // hook.resolve 的裁决非法
+  "errHookTimeout", // 等待服务端裁决超时
+  // 项目 / skill（D23-D26）
+  "errProjectNotFound",
+  "errProjectExists", // 同名/同路径项目已存在
+  "errProjectHasActiveSessions", // 项目下还有 active session（remove 拦）
+  "errSkillNotFound",
+  "errSkillScopeInvalid", // scope=project 但缺 projectId 等
+  "errSkillInstallFailed",
+  // git / worktree（D25）
+  "errWorktreeNotFound",
+  "errWorktreeHasChanges", // 未提交变更，非 force 不清
+  "errWorktreeInUse", // worktree 还有 active session
+  "errBranchNotMerged", // 分支未合并，非 force 不删
+  "errBranchInUse", // 分支仍被某 worktree 检出
+  // 文档 / 上传（D20）
+  "errDocumentTooLarge", // 超 maxUploadBytes
+  "errDocumentPathDenied", // 路径不在项目范围 / 命中 deny
+  // 本地 policy（D27）
+  "errPolicyDenied", // 被设备本地安全策略拦截
+  // 幂等
+  "errDuplicateRequest", // clientRequestId 重复（已处理过）
+  // 通用
+  "errInvalidParams",
+  "errInternal",
+]);
+export type PhononErrorCode = z.infer<typeof PhononErrorCode>;
+
+/** 统一附在 JSON-RPC error.data 上的结构。 */
+export const PhononErrorData = z.object({
+  appCode: PhononErrorCode,
+  /** 可选的人类可读补充（不用于程序判别）。 */
+  detail: z.string().optional(),
+  /** 可选：相关 session/agent/tenant，便于服务端定位。 */
+  sessionId: SessionId.optional(),
+  agentId: AgentId.optional(),
+  tenantId: TenantId.optional(),
+});
+export type PhononErrorData = z.infer<typeof PhononErrorData>;
+
+/** ISO-8601 时间戳字符串（统一用字符串，避免时区/精度歧义）。 */
+export const Timestamp = z.string().datetime({ offset: true });
+export type Timestamp = z.infer<typeof Timestamp>;

package/src/schemas/connect.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { DeviceId, TenantId, Timestamp } from "./common.js";
+
+/**
+ * 连接握手（design §6）。
+ *
+ * phonon 拨出连接后，首先发 connect.hello 表明：协议版本、设备身份。
+ * device key 的鉴权由传输层/服务端处理（如 WS header / 首帧），不在业务 params 里明文带。
+ * server 回 connect.welcome 确认，并可下发 tenant 绑定与服务端能力。
+ */
+
+export const ConnectHelloParams = z.object({
+  /** 本端协议版本（= PROTOCOL_VERSION）。 */
+  protocolVersion: z.string(),
+  /** 设备标识（服务端用于区分多设备）。 */
+  deviceId: DeviceId,
+  /** phonon 实现版本（软件版本，便于服务端兼容处理）。 */
+  phononVersion: z.string().optional(),
+  /** 本端声明支持的可选特性开关，便于前向兼容。 */
+  features: z.array(z.string()).default([]),
+  /** 设备鉴权（可选）：server 据此验证设备身份。也可走传输层 header。 */
+  auth: z.object({ deviceKey: z.string() }).optional(),
+  /**
+   * 重连时携带（P0-4）：phonon 本地 outbox 中每个 session 尚未被 ack 的起始 seq，
+   * 让 server 知道哪些要补发 / 从哪重放。首次连接可省略。
+   */
+  resumeFrom: z
+    .array(z.object({ sessionId: z.string(), fromSeq: z.number().int().nonnegative() }))
+    .optional(),
+  at: Timestamp,
+});
+export type ConnectHelloParams = z.infer<typeof ConnectHelloParams>;
+
+export const ConnectWelcomeResult = z.object({
+  /** 服务端协议版本。 */
+  protocolVersion: z.string(),
+  /** 服务端为本连接分配/确认的租户身份（= 一条服务端连接，design D13）。 */
+  tenantId: TenantId,
+  /** 服务端声明支持的可选特性。 */
+  features: z.array(z.string()).default([]),
+  /**
+   * 重连时服务端告知「我各 session 最后收到的 seq」（P0-4），
+   * phonon 据此从 outbox 精确补发（> lastSeq 的），避免重复/遗漏。
+   */
+  ackedSeqs: z
+    .array(z.object({ sessionId: z.string(), lastSeq: z.number().int().nonnegative() }))
+    .optional(),
+  at: Timestamp,
+});
+export type ConnectWelcomeResult = z.infer<typeof ConnectWelcomeResult>;

package/src/schemas/device.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+
+/**
+ * 设备级信息与可观测协议。
+ *
+ * device.info：相对静态的 OS/机器信息，用于服务端按需调度。
+ * device.resources：运行时资源快照，用于 debug，不做资源调度或限制。
+ */
+
+export const DeviceInfoParams = z.object({}).default({});
+export type DeviceInfoParams = z.infer<typeof DeviceInfoParams>;
+
+export const DeviceInfoResult = z.object({
+  at: z.string().datetime({ offset: true }),
+  hostname: z.string(),
+  os: z.object({
+    platform: z.enum(["aix", "darwin", "freebsd", "linux", "openbsd", "sunos", "win32", "cygwin", "netbsd"]).or(z.string()),
+    type: z.string(),
+    release: z.string(),
+    arch: z.string(),
+  }),
+  runtime: z.object({
+    node: z.string().optional(),
+  }).optional(),
+  /** 便于 server 做粗粒度任务路由：ios-development/windows-desktop-development/nvidia-gpu 等。 */
+  capabilities: z.array(z.string()).default([]),
+});
+export type DeviceInfoResult = z.infer<typeof DeviceInfoResult>;
+
+export const DeviceResourcesParams = z.object({}).default({});
+export type DeviceResourcesParams = z.infer<typeof DeviceResourcesParams>;
+
+export const DeviceResourcesResult = z.object({
+  at: z.string().datetime({ offset: true }),
+  cpu: z.object({
+    loadavg: z.array(z.number()).length(3).optional(),
+    cores: z.number().int().positive().optional(),
+    usagePercent: z.number().min(0).max(100).optional(),
+  }).optional(),
+  memory: z.object({
+    totalBytes: z.number().nonnegative(),
+    freeBytes: z.number().nonnegative(),
+    usedBytes: z.number().nonnegative(),
+    usagePercent: z.number().min(0).max(100).optional(),
+  }),
+  disk: z.object({
+    path: z.string(),
+    totalBytes: z.number().nonnegative().optional(),
+    freeBytes: z.number().nonnegative().optional(),
+    usedBytes: z.number().nonnegative().optional(),
+    usagePercent: z.number().min(0).max(100).optional(),
+  }).optional(),
+  gpu: z.array(z.object({
+    name: z.string().optional(),
+    memoryTotalBytes: z.number().nonnegative().optional(),
+    memoryUsedBytes: z.number().nonnegative().optional(),
+    utilizationPercent: z.number().min(0).max(100).optional(),
+  })).optional(),
+  process: z.object({
+    pid: z.number().int().positive(),
+    uptimeSeconds: z.number().nonnegative(),
+    rssBytes: z.number().nonnegative().optional(),
+    heapUsedBytes: z.number().nonnegative().optional(),
+    heapTotalBytes: z.number().nonnegative().optional(),
+  }).optional(),
+});
+export type DeviceResourcesResult = z.infer<typeof DeviceResourcesResult>;

package/src/schemas/discovery.ts

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import { AgentId, Timestamp } from "./common.js";
+import { AgentCapabilities } from "./capabilities.js";
+
+/**
+ * Agent / 模型发现（design §5 / D14）。
+ *
+ * 发现 = 内部扫描机制（非协议）+ 对外暴露接口（属协议）。本文件只定义
+ * **对外接口**的数据形状：服务端借此感知「这台设备上哪些 agent 可用、
+ * 各自哪些模型可用」。
+ */
+
+/** 单个模型的可用性描述。 */
+export const ModelInfo = z.object({
+  /** 模型 id，session.create 的 `model` 入参取自这里。 */
+  id: z.string().min(1),
+  /** 展示名（可选）。 */
+  displayName: z.string().optional(),
+  /** 上下文窗口（token，若已知）。注意：以 phonon 实测/配置为准，不盲信后端返回。 */
+  contextWindow: z.number().int().positive().optional(),
+  /** 该模型当前是否可用（如鉴权过期会变 false）。 */
+  available: z.boolean().default(true),
+});
+export type ModelInfo = z.infer<typeof ModelInfo>;
+
+/** 单个 agent 的发现条目。 */
+export const AgentDescriptor = z.object({
+  agentId: AgentId,
+  /** 展示名，如 "Claude Code" / "OpenClaw"。 */
+  displayName: z.string().min(1),
+  /** 适配器内部名，如 "openclaw" / "claude-code"。 */
+  adapter: z.string().min(1),
+  /** 整体是否可用（已安装 + 可执行 + 凭证就绪）。 */
+  available: z.boolean(),
+  /** 不可用时的原因（如 "not_installed" / "not_logged_in" / "no_credentials"）。 */
+  unavailableReason: z.string().optional(),
+  /** agent 自身版本（若可探测）。 */
+  version: z.string().optional(),
+  /** 可用模型列表。 */
+  models: z.array(ModelInfo),
+  /** 能力声明（随 discovery 暴露，见 §7）。 */
+  capabilities: AgentCapabilities,
+  /** 最近一次扫描时间。 */
+  scannedAt: Timestamp.optional(),
+});
+export type AgentDescriptor = z.infer<typeof AgentDescriptor>;
+
+// --- discovery.list ---
+export const DiscoveryListParams = z.object({
+  /** 可选：只看可用的。 */
+  availableOnly: z.boolean().optional(),
+});
+export type DiscoveryListParams = z.infer<typeof DiscoveryListParams>;
+
+export const DiscoveryListResult = z.object({
+  agents: z.array(AgentDescriptor),
+});
+export type DiscoveryListResult = z.infer<typeof DiscoveryListResult>;
+
+// --- discovery.get ---
+export const DiscoveryGetParams = z.object({
+  agentId: AgentId,
+});
+export type DiscoveryGetParams = z.infer<typeof DiscoveryGetParams>;
+
+export const DiscoveryGetResult = z.object({
+  agent: AgentDescriptor,
+});
+export type DiscoveryGetResult = z.infer<typeof DiscoveryGetResult>;
+
+// --- discovery.changed (phonon -> server 主动推送，notification) ---
+export const DiscoveryChangedParams = z.object({
+  /** 变更类型：agent 上/下线、模型增减、能力变化。 */
+  kind: z.enum(["agent_added", "agent_removed", "agent_updated", "models_changed"]),
+  agentId: AgentId,
+  /** 变更后的完整快照（可选，便于服务端直接更新缓存）。 */
+  snapshot: AgentDescriptor.optional(),
+  at: Timestamp,
+});
+export type DiscoveryChangedParams = z.infer<typeof DiscoveryChangedParams>;