@agent-phonon/protocol 0.2.0

package/src/schemas/methods.ts

@@ -0,0 +1,414 @@
+import { z } from "zod";
+import {
+  ConnectHelloParams,
+  ConnectWelcomeResult,
+} from "./connect.js";
+import {
+  DiscoveryListParams,
+  DiscoveryListResult,
+  DiscoveryGetParams,
+  DiscoveryGetResult,
+  DiscoveryChangedParams,
+} from "./discovery.js";
+import {
+  SessionCreateParams,
+  SessionCreateResult,
+  SessionSendParams,
+  SessionSendAck,
+  SessionInjectParams,
+  SessionInjectResult,
+  SessionCompressParams,
+  SessionCompressResult,
+  SessionSwitchModelParams,
+  SessionSwitchModelResult,
+  SessionInterruptParams,
+  SessionInterruptResult,
+  SessionTerminateParams,
+  SessionTerminateResult,
+  SessionStatusParams,
+  SessionStatusResult,
+  SessionListParams,
+  SessionListResult,
+} from "./session.js";
+import { StreamEvent, StreamAckParams } from "./stream.js";import {
+  HookFiredParams,
+  HookResolveParams,
+  HookResolveResult,
+} from "./hook.js";
+import { DocumentSendParams, DocumentSendResult, DocumentPrepareUploadParams, DocumentPrepareUploadResult } from "./document.js";
+import {
+  InteractionRequestParams,
+  InteractionRequestResult,
+  InteractionResponseParams,
+  InteractionCancelParams,
+  InteractionCancelResult,
+} from "./interaction.js";
+import {
+  ProjectCreateParams,
+  ProjectCreateResult,
+  ProjectListParams,
+  ProjectListResult,
+  ProjectGetParams,
+  ProjectGetResult,
+  ProjectRemoveParams,
+  ProjectRemoveResult,
+  WorktreeCreateParams,
+  WorktreeCreateResult,
+  WorktreeListParams,
+  WorktreeListResult,
+  WorktreeRemoveParams,
+  WorktreeRemoveResult,
+  GitDeleteBranchParams,
+  GitDeleteBranchResult,
+} from "./project.js";
+import {
+  SkillInstallParams,
+  SkillInstallResult,
+  SkillUninstallParams,
+  SkillUninstallResult,
+  SkillListParams,
+  SkillListResult,
+} from "./skill.js";
+import { DeviceInfoParams, DeviceInfoResult, DeviceResourcesParams, DeviceResourcesResult } from "./device.js";
+import {
+  FileReadParams,
+  FileReadResult,
+  FileWriteParams,
+  FileWriteResult,
+  FileListParams,
+  FileListResult,
+  FileStatParams,
+  FileStatResult,
+  FileMkdirParams,
+  FileMkdirResult,
+} from "./file.js";
+import { EnvSetParams, EnvSetResult, EnvListParams, EnvListResult, EnvDeleteParams, EnvDeleteResult } from "./env.js";
+
+/**
+ * 方法注册表（design 全协议的单一事实来源）。
+ *
+ * 每个方法声明：
+ *   - direction: 谁是 requester
+ *       s2p = server → phonon （服务端下发操作）
+ *       p2s = phonon → server （设备上报结果/事件/发现）
+ *   - kind: "request"（需响应）| "notification"（无响应）
+ *   - params / result 的 zod schema
+ *
+ * core 与 client-sdk 都 import 本表，确保两端对齐、可机器校验。
+ */
+
+const z_void = z.undefined();
+
+export const METHODS = {
+  // --- 握手（phonon 拨出后先发）---
+  "connect.hello": {
+    direction: "p2s",
+    kind: "request",
+    params: ConnectHelloParams,
+    result: ConnectWelcomeResult,
+  },
+
+  // --- 设备级信息与可观测（server 查询）---
+  "device.info": {
+    direction: "s2p",
+    kind: "request",
+    params: DeviceInfoParams,
+    result: DeviceInfoResult,
+  },
+  "device.resources": {
+    direction: "s2p",
+    kind: "request",
+    params: DeviceResourcesParams,
+    result: DeviceResourcesResult,
+  },
+
+  // --- 发现（server 查询；phonon 主动推变更）---
+  "discovery.list": {
+    direction: "s2p",
+    kind: "request",
+    params: DiscoveryListParams,
+    result: DiscoveryListResult,
+  },
+  "discovery.get": {
+    direction: "s2p",
+    kind: "request",
+    params: DiscoveryGetParams,
+    result: DiscoveryGetResult,
+  },
+  "discovery.changed": {
+    direction: "p2s",
+    kind: "notification",
+    params: DiscoveryChangedParams,
+    result: z_void,
+  },
+
+  // --- session 原语（server 下发）---
+  "session.create": {
+    direction: "s2p",
+    kind: "request",
+    params: SessionCreateParams,
+    result: SessionCreateResult,
+  },
+  "session.send": {
+    direction: "s2p",
+    kind: "request",
+    params: SessionSendParams,
+    result: SessionSendAck,
+  },
+  "session.inject": {
+    direction: "s2p",
+    kind: "request",
+    params: SessionInjectParams,
+    result: SessionInjectResult,
+  },
+  "session.compress": {
+    direction: "s2p",
+    kind: "request",
+    params: SessionCompressParams,
+    result: SessionCompressResult,
+  },
+  "session.switchModel": {
+    direction: "s2p",
+    kind: "request",
+    params: SessionSwitchModelParams,
+    result: SessionSwitchModelResult,
+  },
+  "session.interrupt": {
+    direction: "s2p",
+    kind: "request",
+    params: SessionInterruptParams,
+    result: SessionInterruptResult,
+  },
+  "session.terminate": {
+    direction: "s2p",
+    kind: "request",
+    params: SessionTerminateParams,
+    result: SessionTerminateResult,
+  },
+  "session.status": {
+    direction: "s2p",
+    kind: "request",
+    params: SessionStatusParams,
+    result: SessionStatusResult,
+  },
+  "session.list": {
+    direction: "s2p",
+    kind: "request",
+    params: SessionListParams,
+    result: SessionListResult,
+  },
+
+  // --- 流式结果（phonon 上推；无响应）---
+  "stream.event": {
+    direction: "p2s",
+    kind: "notification",
+    params: StreamEvent,
+    result: z_void,
+  },
+  // --- 流式 ack（server 确认 seq，phonon 据此清 outbox，P0-4）---
+  "stream.ack": {
+    direction: "s2p",
+    kind: "notification",
+    params: StreamAckParams,
+    result: z_void,
+  },
+
+  // --- hook / HITL ---
+  "hook.fired": {
+    direction: "p2s",
+    kind: "request", // phonon 发起、阻塞等 server 裁决
+    params: HookFiredParams,
+    result: HookResolveResult,
+  },
+  "hook.resolve": {
+    direction: "s2p",
+    kind: "request",
+    params: HookResolveParams,
+    result: HookResolveResult,
+  },
+
+  // --- 文档交换（agent emit 指令 → phonon 读本地文件 → 上传，平面③ / D20）---
+  "document.send": {
+    direction: "p2s",
+    kind: "request",
+    params: DocumentSendParams,
+    result: DocumentSendResult,
+  },
+  "document.prepare_upload": {
+    direction: "p2s",
+    kind: "request", // 大文件凭证上传（P1-6）
+    params: DocumentPrepareUploadParams,
+    result: DocumentPrepareUploadResult,
+  },
+
+  // --- 人机交互（表单/卡片，agent主动或HITL发起，平面③ / D21）---
+  "interaction.request": {
+    direction: "p2s",
+    kind: "request", // blocking 时阻塞等人回填
+    params: InteractionRequestParams,
+    result: InteractionRequestResult,
+  },
+  "interaction.response": {
+    direction: "s2p",
+    kind: "notification", // 异步/非阻塞回填走这条
+    params: InteractionResponseParams,
+    result: z_void,
+  },
+  "interaction.cancel": {
+    direction: "s2p",
+    kind: "request", // 主动取消一个 pending 交互（P1-5）
+    params: InteractionCancelParams,
+    result: InteractionCancelResult,
+  },
+
+  // --- 项目管理（目录 + Git；server 下发，D23）---
+  "project.create": {
+    direction: "s2p",
+    kind: "request",
+    params: ProjectCreateParams,
+    result: ProjectCreateResult,
+  },
+  "project.list": {
+    direction: "s2p",
+    kind: "request",
+    params: ProjectListParams,
+    result: ProjectListResult,
+  },
+  "project.get": {
+    direction: "s2p",
+    kind: "request",
+    params: ProjectGetParams,
+    result: ProjectGetResult,
+  },
+  "project.remove": {
+    direction: "s2p",
+    kind: "request",
+    params: ProjectRemoveParams,
+    result: ProjectRemoveResult,
+  },
+
+  // --- worktree / git 子能力（D25）---
+  "project.worktree.create": {
+    direction: "s2p",
+    kind: "request",
+    params: WorktreeCreateParams,
+    result: WorktreeCreateResult,
+  },
+  "project.worktree.list": {
+    direction: "s2p",
+    kind: "request",
+    params: WorktreeListParams,
+    result: WorktreeListResult,
+  },
+  "project.worktree.remove": {
+    direction: "s2p",
+    kind: "request",
+    params: WorktreeRemoveParams,
+    result: WorktreeRemoveResult,
+  },
+  "project.git.deleteBranch": {
+    direction: "s2p",
+    kind: "request",
+    params: GitDeleteBranchParams,
+    result: GitDeleteBranchResult,
+  },
+
+  // --- 受控工作区文件读写（server 下发，project/worktree scoped）---
+  "file.read": {
+    direction: "s2p",
+    kind: "request",
+    params: FileReadParams,
+    result: FileReadResult,
+  },
+  "file.write": {
+    direction: "s2p",
+    kind: "request",
+    params: FileWriteParams,
+    result: FileWriteResult,
+  },
+  "file.list": {
+    direction: "s2p",
+    kind: "request",
+    params: FileListParams,
+    result: FileListResult,
+  },
+  "file.stat": {
+    direction: "s2p",
+    kind: "request",
+    params: FileStatParams,
+    result: FileStatResult,
+  },
+  "file.mkdir": {
+    direction: "s2p",
+    kind: "request",
+    params: FileMkdirParams,
+    result: FileMkdirResult,
+  },
+
+  // --- 环境变量配置（skill/agent 运行环境，默认脱敏）---
+  "env.set": {
+    direction: "s2p",
+    kind: "request",
+    params: EnvSetParams,
+    result: EnvSetResult,
+  },
+  "env.list": {
+    direction: "s2p",
+    kind: "request",
+    params: EnvListParams,
+    result: EnvListResult,
+  },
+  "env.delete": {
+    direction: "s2p",
+    kind: "request",
+    params: EnvDeleteParams,
+    result: EnvDeleteResult,
+  },
+
+  // --- skill 管理（给 agent 装/卸 skill，global|project 两级，D24）---
+  "skill.install": {
+    direction: "s2p",
+    kind: "request",
+    params: SkillInstallParams,
+    result: SkillInstallResult,
+  },
+  "skill.uninstall": {
+    direction: "s2p",
+    kind: "request",
+    params: SkillUninstallParams,
+    result: SkillUninstallResult,
+  },
+  "skill.list": {
+    direction: "s2p",
+    kind: "request",
+    params: SkillListParams,
+    result: SkillListResult,
+  },
+} as const;
+
+export type MethodName = keyof typeof METHODS;
+export type MethodSpec = (typeof METHODS)[MethodName];
+
+/** 取某方法的 params 类型。 */
+export type ParamsOf<M extends MethodName> = z.infer<(typeof METHODS)[M]["params"]>;
+/** 取某方法的 result 类型。 */
+export type ResultOf<M extends MethodName> = z.infer<(typeof METHODS)[M]["result"]>;
+
+/** 运行时校验某方法的 params。 */
+export function parseParams<M extends MethodName>(
+  method: M,
+  data: unknown,
+): ParamsOf<M> {
+  return METHODS[method].params.parse(data) as ParamsOf<M>;
+}
+
+/** 运行时校验某方法的 result。 */
+export function parseResult<M extends MethodName>(
+  method: M,
+  data: unknown,
+): ResultOf<M> {
+  return METHODS[method].result.parse(data) as ResultOf<M>;
+}
+
+/** 全部方法名（运行时数组）。 */
+export const METHOD_NAMES = Object.keys(METHODS) as MethodName[];

package/src/schemas/policy.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { AgentId, ProjectId } from "./common.js";
+
+/**
+ * 本地安全策略（design D27 / review P0-1）。
+ *
+ * phonon 不做终端用户鉴权（那是服务端的事），但**必须有设备主人配置的本地授权边界**——
+ * 否则任意接入的 server 都能让本地 agent 读任意文件、装任意 skill、删 worktree。
+ *
+ * 这是「设备 policy」，不是「用户鉴权」。每个 tenant 一份，phonon 在执行前据此拦截。
+ * 这些是本地配置，不进 device→server 的线协议；放协议包是为了类型共享与校验。
+ */
+
+/** 单个 tenant 的本地授权边界。 */
+export const TenantPolicy = z.object({
+  /** 允许操作的项目根目录白名单（绝对路径）。document/project 路径必须落在其下。 */
+  allowedProjectRoots: z.array(z.string()).default([]),
+  /** 允许使用的 agent 白名单；空 = 不限制。 */
+  allowedAgents: z.array(AgentId).default([]),
+  /** 允许的方法白名单；空 = 全允许。用它可表达「只读租户」（只放查询类方法）。 */
+  allowedMethods: z.array(z.string()).default([]),
+  /** 是否允许全局 skill 安装（影响该 agent 所有项目，危险）。默认 false。 */
+  allowGlobalSkillInstall: z.boolean().default(false),
+  /** 是否允许从 url 安装 skill（供应链入口，危险）。默认 false。 */
+  allowUrlSkillInstall: z.boolean().default(false),
+  /** 是否允许物理删盘（project.remove deleteFiles / worktree force 等）。默认 false。 */
+  allowDeleteFiles: z.boolean().default(false),
+  /** document.send 是否允许发送项目/worktree 目录之外的文件。默认 false（project-scoped）。 */
+  allowExternalDocuments: z.boolean().default(false),
+  /** env.list reveal=true 是否允许返回环境变量明文。默认 false（只能脱敏查看）。 */
+  allowEnvReveal: z.boolean().default(false),
+  /** 单文件上传上限（字节）；超出走 prepare_upload 或拒绝。 */
+  maxUploadBytes: z.number().int().positive().optional(),
+  /** 敏感路径黑名单（即使在 allowedProjectRoots 内也拒绝，如 .ssh/.aws/.env）。 */
+  denyPathPatterns: z.array(z.string()).default([
+    "**/.ssh/**",
+    "**/.aws/**",
+    "**/.env",
+    "**/.git/config",
+    "**/id_rsa*",
+    "**/*.pem",
+    "**/openclaw.json",
+  ]),
+});
+export type TenantPolicy = z.infer<typeof TenantPolicy>;
+
+/** policy 默认值（最严格：白名单空、写操作全关）。 */
+export const DEFAULT_TENANT_POLICY: TenantPolicy = TenantPolicy.parse({});
+
+/**
+ * 校验一个绝对路径是否落在某项目根白名单内（不含 deny 匹配）。
+ * 真实 glob/deny 匹配由 core 实现；这里给协议层一个轻量前缀检查骨架。
+ */
+export function isPathUnderRoots(absPath: string, roots: readonly string[]): boolean {
+  if (roots.length === 0) return false;
+  const norm = absPath.replace(/\\/g, "/");
+  return roots.some((r) => {
+    const root = r.replace(/\\/g, "/").replace(/\/+$/, "");
+    return norm === root || norm.startsWith(root + "/");
+  });
+}
+
+/** policy 拒绝时的归一化结果（core 用，便于回 errPolicyDenied）。 */
+export const PolicyDecision = z.object({
+  allowed: z.boolean(),
+  /** 拒绝原因（如 "path_outside_project" / "url_skill_disabled" / "delete_not_allowed"）。 */
+  reason: z.string().optional(),
+  /** 关联 projectId（若适用）。 */
+  projectId: ProjectId.optional(),
+});
+export type PolicyDecision = z.infer<typeof PolicyDecision>;

package/src/schemas/project.ts

@@ -0,0 +1,185 @@
+import { z } from "zod";
+import { ProjectId, Timestamp } from "./common.js";
+
+/**
+ * 项目管理协议（design D23）。
+ *
+ * 一个项目 = 一个目录 + Git。所有 session 必须绑定一个项目（projectId）。
+ * 项目是磁盘上的客观目录，**设备级共享、不受 tenant 隔离**——不同 tenant 都能看到/用
+ * 同一项目，在其下各干各的；冲突风险用户自担。（隔离发生在会话/任务层，不在文件层。）
+ */
+
+/** 项目描述。 */
+export const ProjectDescriptor = z.object({
+  projectId: ProjectId,
+  /** 展示名。 */
+  name: z.string().min(1),
+  /** 项目目录的绝对路径（设备本地）。 */
+  path: z.string().min(1),
+  /** 是否已 git init。 */
+  git: z.boolean().default(true),
+  /** 当前分支（若有）。 */
+  branch: z.string().optional(),
+  /** 可选：远端 URL。 */
+  remote: z.string().optional(),
+  createdAt: Timestamp,
+});
+export type ProjectDescriptor = z.infer<typeof ProjectDescriptor>;
+
+// --- project.create ---
+export const ProjectCreateParams = z.object({
+  /** 可选：幂等键（P0-3）。 */
+  clientRequestId: z.string().optional(),
+  name: z.string().min(1),
+  /**
+   * 可选：指定目录路径。缺省由 phonon 在受控工作区下按 name 生成
+   * （避免服务端越权指定任意本地路径）。
+   */
+  path: z.string().optional(),
+  /** 是否 git init（默认 true，项目 = 目录 + Git）。 */
+  git: z.boolean().default(true),
+  /** 可选：初始化时设置的远端。 */
+  remote: z.string().optional(),
+});
+export type ProjectCreateParams = z.infer<typeof ProjectCreateParams>;
+
+export const ProjectCreateResult = z.object({
+  project: ProjectDescriptor,
+});
+export type ProjectCreateResult = z.infer<typeof ProjectCreateResult>;
+
+// --- project.list ---
+export const ProjectListParams = z.object({}).default({});
+export type ProjectListParams = z.infer<typeof ProjectListParams>;
+
+export const ProjectListResult = z.object({
+  projects: z.array(ProjectDescriptor),
+});
+export type ProjectListResult = z.infer<typeof ProjectListResult>;
+
+// --- project.get ---
+export const ProjectGetParams = z.object({ projectId: ProjectId });
+export type ProjectGetParams = z.infer<typeof ProjectGetParams>;
+
+export const ProjectGetResult = z.object({ project: ProjectDescriptor });
+export type ProjectGetResult = z.infer<typeof ProjectGetResult>;
+
+// --- project.remove ---
+export const ProjectRemoveParams = z.object({
+  projectId: ProjectId,
+  /**
+   * 是否删除物理目录。默认 false（仅从 phonon 解绑/注销，保留磁盘文件，防误删）。
+   * true 才真正删目录——危险操作，需 policy allowDeleteFiles。
+   */
+  deleteFiles: z.boolean().default(false),
+  /**
+   * 有 active session 绑定本项目时的处理（P1-7 / Minimax#5）：
+   * - reject（默认）：还有 active session → errProjectHasActiveSessions
+   * - cascade      ：级联 terminate 所有 active session 再移除
+   */
+  whenActiveSessions: z.enum(["reject", "cascade"]).default("reject"),
+});
+export type ProjectRemoveParams = z.infer<typeof ProjectRemoveParams>;
+
+export const ProjectRemoveResult = z.object({
+  projectId: ProjectId,
+  removed: z.literal(true),
+  filesDeleted: z.boolean(),
+  /** cascade 时被级联 terminate 的 session。 */
+  terminatedSessions: z.array(z.string()).optional(),
+});
+export type ProjectRemoveResult = z.infer<typeof ProjectRemoveResult>;
+
+// ===========================================================================
+// Git / worktree 子能力（D25）
+// worktree = 同一仓库的多个工作目录，天然适配「多 tenant/session 在同一项目各干各的」。
+// ===========================================================================
+
+/** worktree 描述。 */
+export const WorktreeDescriptor = z.object({
+  /** worktree 标识（phonon 生成）。 */
+  worktreeId: z.string().min(1),
+  projectId: ProjectId,
+  /** worktree 的工作目录路径。 */
+  path: z.string().min(1),
+  /** 该 worktree 检出的分支。 */
+  branch: z.string().min(1),
+  /** 是否是主工作区（项目本体目录）。 */
+  isPrimary: z.boolean().default(false),
+  createdAt: Timestamp.optional(),
+});
+export type WorktreeDescriptor = z.infer<typeof WorktreeDescriptor>;
+
+// --- project.worktree.create：基于某 branch 创建 worktree ---
+export const WorktreeCreateParams = z.object({
+  /** 可选：幂等键（P0-3）。 */
+  clientRequestId: z.string().optional(),
+  projectId: ProjectId,
+  /** 基于哪个已有 branch 创建（检出点）。 */
+  baseBranch: z.string().min(1),
+  /**
+   * 可选：新建并检出的分支名。缺省则直接检出 baseBranch
+   * （注：同一 branch 不能被两个 worktree 同时检出，所以多开并发时通常传 newBranch）。
+   */
+  newBranch: z.string().optional(),
+  /** 可选：指定 worktree 路径；缺省由 phonon 在受控区生成。 */
+  path: z.string().optional(),
+});
+export type WorktreeCreateParams = z.infer<typeof WorktreeCreateParams>;
+
+export const WorktreeCreateResult = z.object({
+  worktree: WorktreeDescriptor,
+});
+export type WorktreeCreateResult = z.infer<typeof WorktreeCreateResult>;
+
+// --- project.worktree.list ---
+export const WorktreeListParams = z.object({ projectId: ProjectId });
+export type WorktreeListParams = z.infer<typeof WorktreeListParams>;
+
+export const WorktreeListResult = z.object({
+  worktrees: z.array(WorktreeDescriptor),
+});
+export type WorktreeListResult = z.infer<typeof WorktreeListResult>;
+
+// --- project.worktree.remove：清理 worktree ---
+export const WorktreeRemoveParams = z.object({
+  projectId: ProjectId,
+  worktreeId: z.string().min(1),
+  /**
+   * 是否强制清理（P1-7）。默认 false：
+   * 有未提交变更 → errWorktreeHasChanges；还有 active/running session 绑定 → errWorktreeInUse。
+   * force=true 才允许硬删，但会连带影响返回 affectedSessions。
+   */
+  force: z.boolean().default(false),
+});
+export type WorktreeRemoveParams = z.infer<typeof WorktreeRemoveParams>;
+
+export const WorktreeRemoveResult = z.object({
+  worktreeId: z.string(),
+  removed: z.literal(true),
+  /** 被连带影响（被迫 terminate）的 session（force 硬删时）。 */
+  affectedSessions: z.array(z.string()).optional(),
+});
+export type WorktreeRemoveResult = z.infer<typeof WorktreeRemoveResult>;
+
+// --- project.git.deleteBranch：删除（已合并的）branch ---
+export const GitDeleteBranchParams = z.object({
+  projectId: ProjectId,
+  branch: z.string().min(1),
+  /**
+   * 是否强制删除（P1-7）。默认 false：
+   * 未合并 → errBranchNotMerged；仍被某 worktree 检出 → errBranchInUse。
+   * force=true 强删未合并（git branch -D），返回 affectedWorktrees。
+   */
+  force: z.boolean().default(false),
+});
+export type GitDeleteBranchParams = z.infer<typeof GitDeleteBranchParams>;
+
+export const GitDeleteBranchResult = z.object({
+  branch: z.string(),
+  deleted: z.literal(true),
+  wasMerged: z.boolean().optional(),
+  /** 被连带影响的 worktree（force 硬删时）。 */
+  affectedWorktrees: z.array(z.string()).optional(),
+});
+export type GitDeleteBranchResult = z.infer<typeof GitDeleteBranchResult>;