@anycon/protocol 0.1.0 → 0.2.0

package/src/generated.ts

@@ -10,6 +10,14 @@ export type AgentStatus =
  */
 export type LinkBlock = "hidden" | "sensitive" | "workspace" | "data_dir" | "filesystem_root";
 export type DeviceKind = "daemon" | "web" | "cli" | "sdk";
+/**
+ * 一项配置能不能被远程客户端改（ADR-43）。
+ */
+export type ConfigEditable = "any" | "tighten_only" | "no";
+/**
+ * 配置值的类型，客户端据此选控件。
+ */
+export type ConfigValueKind = "bool" | "int" | "duration" | "enum" | "text";
 /**
  * 控制消息集合。方向见注释：D = 设备，H = hub。
  */
@@ -17,6 +25,7 @@ export type Control =
   | {
       client: ClientInfo;
       device_token?: string | null;
+      preview_token?: string | null;
       protocol_version: number;
       type: "auth";
     }
@@ -102,6 +111,11 @@ export type Control =
       device: string;
       type: "peer_offline";
     }
+  | {
+      label: string;
+      peer: string;
+      type: "preview_peer";
+    }
   | {
       seq: number;
       to: string;
@@ -128,6 +142,7 @@ export type Control =
     }
   | {
       retry_after_ms: number;
+      to?: string | null;
       type: "rate_limited";
     }
   | {
@@ -286,6 +301,11 @@ export type Event =
       id: string;
       input?: unknown;
       name: string;
+      /**
+       * 子 agent 内部的调用：启动这个子 agent 的那次调用（`category = subagent`）的 `id`。
+       * 子 agent 再启动子 agent 时一层层指上去；主 agent 自己的调用不带。
+       */
+      parent_id?: string | null;
       title: string;
       type: "tool_call";
     }
@@ -320,7 +340,18 @@ export type Event =
       type: "permission";
     }
   | {
+      /**
+       * 设备答复时带的 `answers`（kind = question：`{ [question_id]: 字符串或字符串数组 }`），原样记下，
+       * 客户端据此在历史里显示问题和回答。daemon 自己答复的（超时、取消、自动拒绝）没有。
+       */
+      answers?: {
+        [k: string]: unknown;
+      } | null;
       by_device: string;
+      /**
+       * 设备答复时附的话（拒绝的理由、跳过问题时的说明）。daemon 自己答复的没有。
+       */
+      message?: string | null;
       option_id?: string | null;
       request_id: string;
       type: "permission_resolved";
@@ -375,6 +406,82 @@ export type Event =
       message: string;
       recoverable: boolean;
       type: "error";
+    }
+  | {
+      /**
+       * workflow 里的各个 agent，按 `index` 升序；非 workflow 为空。
+       */
+      agents?: TaskAgent[];
+      /**
+       * agent 给任务的 id（Claude Code 的 `task_id`；Codex 子 agent 的 thread id）。会话内唯一。
+       */
+      id: string;
+      kind: TaskKind;
+      /**
+       * 任务最近一次调用的工具名。
+       */
+      last_tool?: string | null;
+      /**
+       * workflow 的阶段，按 `index` 升序；非 workflow 为空。
+       */
+      phases?: TaskPhase[];
+      status: TaskStatus;
+      /**
+       * agent 给的进度 / 结果摘要。
+       */
+      summary?: string | null;
+      /**
+       * workflow 的名字 / 任务描述。
+       */
+      title: string;
+      /**
+       * 启动这个任务的 `tool_call` 的 `id`（Claude Code 的 `tool_use_id`；Codex 的 collab agent 调用 item id）。
+       * 客户端据此把进度挂在那个工具块上；对不上时单独成块。
+       */
+      tool_id?: string | null;
+      type: "task";
+      usage?: TaskUsage | null;
+    }
+  | {
+      code: string;
+      level: NoticeLevel;
+      /**
+       * agent 给的原文（通常是英文），可能是空串。`command_output` 里是本地命令的输出，可能多行。
+       */
+      message: string;
+      /**
+       * `code = model_fallback`：原来的模型。
+       */
+      model_from?: string | null;
+      /**
+       * `code = model_fallback`：实际使用的模型。
+       */
+      model_to?: string | null;
+      /**
+       * `code = rate_limit`：限额恢复的时间。
+       */
+      resets_at_ms?: number | null;
+      type: "notice";
+    }
+  | {
+      /**
+       * `retrying`：这是第几次重试（从 1 开始）。
+       */
+      attempt?: number | null;
+      /**
+       * `retrying`：距下一次重试的毫秒数。
+       */
+      delay_ms?: number | null;
+      /**
+       * `retrying`：最多重试几次。
+       */
+      max_attempts?: number | null;
+      /**
+       * `retrying`：触发重试的错误摘要，如 `529 overloaded_error`。
+       */
+      reason?: string | null;
+      state: ActivityState;
+      type: "activity";
     };
 export type ToolCategory = "shell" | "file_edit" | "file_read" | "search" | "web" | "subagent" | "mcp" | "other";
 export type EditKind = "edit" | "write" | "delete" | "move";
@@ -399,6 +506,32 @@ export type GitAction =
   | "worktree_kept"
   | "worktree_restored"
   | "worktree_missing";
+/**
+ * workflow 里一个 agent 的状态。
+ */
+export type TaskAgentState = ("running" | "done" | "failed") | "queued" | "skipped";
+/**
+ * `Event::Task` 的任务种类。
+ */
+export type TaskKind = "other" | "workflow" | "subagent" | "shell";
+/**
+ * `Event::Task` 的任务状态。`Running` 以外的三个是收尾状态（终态）：Claude Code 的任务进入终态后不会再变；
+ * Codex 的子 agent 是一个可以再收到输入的 thread，`Completed` 之后收到新输入、开始新 turn 就会回到 `Running`。
+ * 所以终态只说明「这一刻不在跑」，不保证同一个 `id` 以后不会再有快照；客户端始终以最新的一条为准。
+ */
+export type TaskStatus = ("running" | "completed" | "failed") | "cancelled";
+/**
+ * `Event::Notice` 的级别。
+ */
+export type NoticeLevel = "info" | "warning";
+/**
+ * `Event::Activity` 的状态。
+ */
+export type ActivityState = "none" | "retrying" | "compacting";
+/**
+ * `fs.read` 返回内容的方式。
+ */
+export type FsReadEncoding = "text" | "base64";
 /**
  * 信封种类。hub 对每种的处理见 docs/protocol.md § 3。
  */
@@ -407,6 +540,10 @@ export type Kind = "handshake" | "data" | "notify" | "control";
  * 节点配置 `worktree.default` 的取值，也是 `SessionWorkspace` 的两种模式。
  */
 export type SessionWorkspaceMode = "local" | "worktree";
+/**
+ * 日志级别，`node.logs` 的最低级别过滤。
+ */
+export type NodeLogLevel = "trace" | "debug" | "info" | "warn" | "error";
 /**
  * `node.security_event.kind`。
  */
@@ -414,6 +551,27 @@ export type SecurityEventKind =
   "device_enrolled" | "password_failures" | "password_locked" | "password_changed" | "settings_changed";
 export type NotifyCategory =
   ("permission_requested" | "turn_finished" | "error" | "session_idle") | "enroll_requested" | "security";
+/**
+ * 隧道里响应体的编码。`gzip`：`DATA` 帧拼起来是 gzip 流，预览页要先解压；`headers` 里已经去掉
+ * `content-encoding` / `content-length`。
+ */
+export type PreviewBodyEncoding = "identity" | "gzip";
+/**
+ * 端口探测是否可用。`unavailable`：这台机器上没有可用的探测手段（如没有 `lsof`），只能预览配置里允许的端口。
+ */
+export type PreviewDetection = "ok" | "unavailable";
+export type PreviewGoawayCode = "expired" | "closed" | "revoked" | "disabled" | "port_not_allowed" | "shutdown";
+/**
+ * 这个端口为什么允许预览（spec/daemon.md § 19.3）。
+ */
+export type PreviewPortSource = "session" | "workspace" | "config";
+/**
+ * daemon 拒绝隧道握手的原因（握手回复 `0x01` 后面的 UTF-8 串）。这一条不受 Noise 保护，只能当提示用。
+ */
+export type PreviewRejectReason =
+  ("expired" | "port_not_allowed" | "disabled" | "malformed") | "unknown_ticket" | "label_mismatch" | "busy";
+export type PreviewResetCode =
+  "internal" | "refused" | "timeout" | "too_large" | "cancelled" | "flow_control" | "protocol" | "limit";
 /**
  * 项目从哪来。
  */
@@ -481,6 +639,10 @@ export interface ProtocolSchema {
   blob_put_chunk_params: BlobPutChunkParams;
   browse_entry: BrowseEntry;
   client_info: ClientInfo;
+  config_change: ConfigChange;
+  config_editable: ConfigEditable;
+  config_item: ConfigItem;
+  config_value_kind: ConfigValueKind;
   control: Control;
   diff_against: DiffAgainst;
   diff_file: DiffFile;
@@ -501,6 +663,7 @@ export interface ProtocolSchema {
   event: Event;
   fs_list_params: FsListParams;
   fs_list_result: FsListResult;
+  fs_read_encoding: FsReadEncoding;
   fs_read_params: FsReadParams;
   fs_read_result: FsReadResult;
   git_action: GitAction;
@@ -512,6 +675,7 @@ export interface ProtocolSchema {
   link_block: LinkBlock;
   node_audit_params: NodeAuditParams;
   node_audit_result: NodeAuditResult;
+  node_config_result: NodeConfigResult;
   node_devices_result: NodeDevicesResult;
   node_doctor_result: NodeDoctorResult;
   node_enroll_approve_params: NodeEnrollApproveParams;
@@ -522,11 +686,15 @@ export interface ProtocolSchema {
   node_enroll_resolved: NodeEnrollResolved;
   node_enroll_status_result: NodeEnrollStatusResult;
   node_info: NodeInfo;
+  node_log_level: NodeLogLevel;
+  node_logs_params: NodeLogsParams;
+  node_logs_result: NodeLogsResult;
   node_pair_begin_params: NodePairBeginParams;
   node_pair_begin_result: NodePairBeginResult;
   node_revoke_device_params: NodeRevokeDeviceParams;
   node_security_event: NodeSecurityEvent;
   node_set_agent_defaults_params: NodeSetAgentDefaultsParams;
+  node_set_config_params: NodeSetConfigParams;
   node_set_enroll_enabled_params: NodeSetEnrollEnabledParams;
   node_set_enroll_password_params: NodeSetEnrollPasswordParams;
   node_stats: NodeStats;
@@ -539,6 +707,26 @@ export interface ProtocolSchema {
   permission_request: PermissionRequest;
   permission_resolved: PermissionResolved;
   permission_respond_params: PermissionRespondParams;
+  preview_body_encoding: PreviewBodyEncoding;
+  preview_close_params: PreviewCloseParams;
+  preview_detection: PreviewDetection;
+  preview_goaway: PreviewGoaway;
+  preview_goaway_code: PreviewGoawayCode;
+  preview_hello: PreviewHello;
+  preview_info: PreviewInfo;
+  preview_launch: PreviewLaunch;
+  preview_list_result: PreviewListResult;
+  preview_open_params: PreviewOpenParams;
+  preview_open_result: PreviewOpenResult;
+  preview_port: PreviewPort;
+  preview_port_source: PreviewPortSource;
+  preview_ports_params: PreviewPortsParams;
+  preview_ports_result: PreviewPortsResult;
+  preview_reject_reason: PreviewRejectReason;
+  preview_request_head: PreviewRequestHead;
+  preview_reset: PreviewReset;
+  preview_reset_code: PreviewResetCode;
+  preview_response_head: PreviewResponseHead;
   project: Project;
   project_kind: ProjectKind;
   pull_request_info: PullRequestInfo;
@@ -590,6 +778,7 @@ export interface ProtocolSchema {
   workspace_name_params: WorkspaceNameParams;
   workspace_remove_worktree_params: WorkspaceRemoveWorktreeParams;
   workspace_rename_params: WorkspaceRenameParams;
+  workspace_root_info: WorkspaceRootInfo;
   workspace_trash_id_params: WorkspaceTrashIdParams;
   workspace_trash_list_result: WorkspaceTrashListResult;
   workspace_worktrees_params: WorkspaceWorktreesParams;
@@ -640,7 +829,8 @@ export interface AgentInfo {
 }
 export interface AgentCapabilities {
   /**
-   * 可接受的附件 mime，如 `image/png`。
+   * agent **原生**收的附件 mime，如 `image/png`。其它附件（非图片、这里没列出的图片格式）不受它限制：daemon 把它们落到
+   * 会话工作目录并在文字里附上路径（ADR-44）。
    */
   attachments?: string[];
   /**
@@ -741,7 +931,7 @@ export interface AgentListResult {
   not_modified?: boolean;
 }
 /**
- * 消息里的一个附件（ADR-35）：指向 daemon 上已经传完的 blob。客户端从 `blob.put_end` 拿到它、原样放进
+ * 消息里的一个附件（ADR-35、ADR-44）：指向 daemon 上已经传完的 blob（图片或任意文件）。客户端从 `blob.put_end` 拿到它、原样放进
  * `session.send` / `session.create`；daemon 以自己记录的元数据为准写进 `user_message` 事件。
  */
 export interface AttachmentRef {
@@ -751,7 +941,7 @@ export interface AttachmentRef {
   mime: string;
   name: string;
   /**
-   * 图片像素宽高（daemon 读文件头得出；读不出来时省略）。客户端用来在下载前占好位置。
+   * 图片像素宽高（daemon 读文件头得出；读不出来、不是图片时省略）。客户端用来在下载前占好位置。
    */
   width?: number | null;
 }
@@ -789,11 +979,13 @@ export interface BlobIdParams {
  */
 export interface BlobPutBeginParams {
   /**
-   * 只接受 `image/png` `image/jpeg` `image/gif` `image/webp`，其它 → `unsupported`。
+   * 任意 `type/subtype`：不合法或空的按 `application/octet-stream` 记录（不报错），大小写和 `;` 之后的参数规整掉。
+   * 声明为 `image/png` `image/jpeg` `image/gif` `image/webp` 的才校验文件头、读宽高。
    */
   mime: string;
   /**
-   * 展示用的文件名（1–255 字节，不能含 `/` `\` 和控制字符）。daemon 不用它拼路径。
+   * 展示用的文件名（1–255 字节，不能含 `/` `\` 和控制字符）。非图片的存储扩展名取自它（清洗过），落到工作目录时也用它
+   * 作文件名；daemon 不用它拼出别的路径。
    */
   name: string;
   /**
@@ -875,6 +1067,47 @@ export interface ClientInfo {
    */
   version: string;
 }
+/**
+ * `node.set_config` 的一项改动。
+ */
+export interface ConfigChange {
+  key: string;
+  /**
+   * 新值，JSON 类型要和该键的 `kind` 一致（布尔、整数、字符串）。
+   */
+  value: unknown;
+}
+/**
+ * `node.get_config` 的一项：一个可以远程查看的配置键。
+ */
+export interface ConfigItem {
+  editable: ConfigEditable;
+  /**
+   * 被 `ANYCON_*` 环境变量覆盖（`log.level` 还包括 `ANYCON_LOG` / `RUST_LOG`）。为真时 `editable` 一定是 `no`。
+   */
+  env_override?: boolean;
+  /**
+   * 点分隔的键，和 `config.toml` 一致（`sessions.max_concurrent`）。
+   */
+  key: string;
+  kind: ConfigValueKind;
+  /**
+   * 取值上限：`int` 是数值，`duration` 是毫秒，`text` 是字符数。
+   */
+  max?: number | null;
+  /**
+   * 取值下限：`int` 是数值，`duration` 是毫秒，`text` 不用。
+   */
+  min?: number | null;
+  /**
+   * `kind = enum` 时允许的取值。
+   */
+  options?: string[];
+  /**
+   * 当前生效的值（默认值 → 文件 → 环境变量合并后的结果）：布尔、整数或字符串，类型见 `kind`。
+   */
+  value: unknown;
+}
 export interface Quota {
   connections: number;
   connections_max?: number | null;
@@ -974,6 +1207,11 @@ export interface ToolCallDetail {
   url?: string | null;
 }
 export interface ToolResultDetail {
+  /**
+   * 调用已经返回，但它启动的工作还在后台跑（后台子 agent）。结束时同一个 `id` 会再来一条
+   * `tool_result`（不带这个标记），取代这一条。
+   */
+  background?: boolean | null;
   exit_code?: number | null;
   /**
    * 这次调用的流式 `tool_output_delta` 累计超过上限、后续 delta 没有转发；最终 `output` 仍是
@@ -985,6 +1223,11 @@ export interface ToolResultDetail {
    * daemon 对 `output` 做头尾截断时丢掉的字节数（spec/daemon.md § 12）；没截断就缺省。
    */
   output_truncated_bytes?: number | null;
+  /**
+   * 子 agent 结束时 agent 报的它一共用掉的 token（`category = subagent`；agent 不报就缺省）。
+   * 主 agent 的 `turn_done.usage` 不含这部分。
+   */
+  total_tokens?: number | null;
   unified_diff?: string | null;
 }
 export interface PlanEntry {
@@ -1008,12 +1251,22 @@ export interface PermissionDetail {
    * kind = tool
    */
   tool?: ToolPermissionDetail | null;
+  /**
+   * kind = other：要用户在浏览器里打开的链接（MCP server 的 URL 模式 elicitation）。只会是 `http` / `https`；
+   * 客户端只对这两种协议提供「打开」入口，并且显示完整 URL。
+   */
+  url?: string | null;
 }
 export interface Question {
   choices?: QuestionChoice[];
   free_text?: boolean;
   id: string;
   multi?: boolean;
+  /**
+   * 可以不答：客户端允许留空提交，答复里就没有这一题的答案。默认 `false`（必答），
+   * 所以 AskUserQuestion 这类每题都要答的行为不变；MCP elicitation 表单里 schema 没列进 `required` 的字段是 `true`。
+   */
+  optional?: boolean;
   text: string;
 }
 export interface QuestionChoice {
@@ -1045,6 +1298,15 @@ export interface PermissionOption {
 export interface Usage {
   cache_read_tokens?: number | null;
   cache_write_tokens?: number | null;
+  /**
+   * turn 结束时上下文已经占用的 token：最近一次模型请求的输入 + 缓存读写。和 `input_tokens` 等
+   * 累计用量不同，它是「此刻窗口里有多少」，客户端拿它和 `context_window` 算占用比例。agent 不报就缺省。
+   */
+  context_tokens?: number | null;
+  /**
+   * 模型的上下文窗口大小（token）。agent 不报就缺省。
+   */
+  context_window?: number | null;
   cost_usd?: number | null;
   duration_ms: number;
   input_tokens?: number | null;
@@ -1077,6 +1339,56 @@ export interface SessionSettings {
    */
   thinking?: string | null;
 }
+/**
+ * workflow 里的一个 agent。
+ */
+export interface TaskAgent {
+  /**
+   * 第几次尝试（重试过才有）。
+   */
+  attempt?: number | null;
+  /**
+   * 结果来自缓存，没有真的运行。
+   */
+  cached?: boolean | null;
+  duration_ms?: number | null;
+  /**
+   * `state = failed` 时的错误信息。
+   */
+  error?: string | null;
+  /**
+   * 在 workflow 里的序号，同一个任务内唯一。
+   */
+  index: number;
+  label: string;
+  /**
+   * 最近一次调用的工具名。
+   */
+  last_tool?: string | null;
+  model?: string | null;
+  /**
+   * 所属阶段的 `TaskPhase.index`。
+   */
+  phase_index?: number | null;
+  state: TaskAgentState;
+  tokens?: number | null;
+  tool_calls?: number | null;
+}
+/**
+ * workflow 的一个阶段。
+ */
+export interface TaskPhase {
+  index: number;
+  title: string;
+}
+/**
+ * 任务的用量。每个字段 agent 不报就缺省。
+ */
+export interface TaskUsage {
+  duration_ms?: number | null;
+  tool_calls?: number | null;
+  total_tokens?: number | null;
+}
 export interface FsListParams {
   /**
    * `<项目名>/<项目内的相对路径>`，如 `my-app/src`。第一段是关联项目的名字时，其余部分相对那个目录解析，
@@ -1095,21 +1407,50 @@ export interface FsEntry {
 }
 export interface FsReadParams {
   /**
-   * 默认 1 MiB，上限 10 MiB。
+   * 缺省 `text`。
+   */
+  encoding?: FsReadEncoding & string;
+  /**
+   * 读多少**原始字节**。`encoding = text`：默认 1 MiB，上限 10 MiB。`encoding = base64`：一次最多一块（512 KiB，和
+   * `blob.get` 一样），缺省就是一块，超过的按一块算（不报错）；`0` 只回大小、不带数据。
    */
   max_bytes?: number | null;
+  /**
+   * 从文件的第几个字节读起，缺省 0。只有 `encoding = base64` 能用：大文件按块一块一块读，一个响应不会长时间占住设备到 daemon
+   * 那条有序的传输。`text` 模式下 `offset > 0` 是 `invalid`。
+   */
+  offset?: number;
   /**
    * 解析规则同 `FsListParams.path`。
    */
   path: string;
 }
 export interface FsReadResult {
+  /**
+   * `text` 模式：文件是二进制（不返回内容）。`base64` 模式：按**这一块**的内容判断（前 8 KiB 里有 NUL、或不是合法的
+   * UTF-8），只有 `offset = 0` 的那一块说明整个文件；从中间读起的块可能从半个字符开始，客户端不要依赖它。
+   */
   binary: boolean;
+  /**
+   * 文件的总字节数（不是读到的）。分块读的时候每一块都带着它：总数变了说明文件在读的过程中被改写过。
+   */
   bytes: number;
   /**
-   * UTF-8 文本；二进制文件 `text` 为空且 `binary = true`。
+   * `encoding = base64` 时读到的字节（至多一块；`offset` 在文件末尾或之后时为空串）；`text` 模式没有这个字段。
+   */
+  data_base64?: string | null;
+  /**
+   * `encoding = base64` 时 `data_base64` 从文件的第几个字节开始（原样回显请求的 `offset`）；`text` 模式没有这个字段。
+   * 不认识 `offset` 的旧 daemon 不会带它，客户端据此知道分块读不能用。
+   */
+  offset?: number | null;
+  /**
+   * UTF-8 文本；二进制文件 `text` 为空且 `binary = true`。`encoding = base64` 时恒为空。
    */
   text: string;
+  /**
+   * 文件在读到的这一段**之后**还有内容（`offset + 读到的字节数 < bytes`）。
+   */
   truncated: boolean;
 }
 export interface JobCancelParams {
@@ -1145,6 +1486,12 @@ export interface AuditEntry {
   target?: string | null;
   ts_ms: number;
 }
+/**
+ * `node.get_config` / `node.set_config` 的结果：白名单里的全部配置项（顺序固定，按段分组）。
+ */
+export interface NodeConfigResult {
+  items: ConfigItem[];
+}
 export interface NodeDevicesResult {
   devices: PeerDevice[];
 }
@@ -1233,6 +1580,10 @@ export interface NodeEnrollStatusResult {
  * `node.info` 结果。
  */
 export interface NodeInfo {
+  /**
+   * `capabilities.blobs` 为 true 时给出。
+   */
+  attachment_limits?: NodeAttachmentLimits | null;
   capabilities: NodeCapabilities;
   name: string;
   node_id: string;
@@ -1240,16 +1591,49 @@ export interface NodeInfo {
   protocol_version: number;
   started_at_ms: number;
   version: string;
+  /**
+   * 主根。多个根时看 `workspace_roots`。
+   */
   workspace_root?: string | null;
+  /**
+   * 所有 workspace 根，主根在最前，额外根按配置顺序。老版本的 daemon 不给，客户端当作只有 `workspace_root` 一个。
+   */
+  workspace_roots?: WorkspaceRootInfo[];
   /**
    * `capabilities.worktree` 为 true 时给出。
    */
   worktree?: NodeWorktreeSettings | null;
 }
+/**
+ * 附件的上限（`node.info`），客户端据此在上传之前就拒绝明显超限的文件。
+ */
+export interface NodeAttachmentLimits {
+  /**
+   * 单个附件的字节上限（`sessions.max_attachment_bytes`，热加载；这里是 `node.info` 被调用那一刻的值）。
+   */
+  max_bytes: number;
+  /**
+   * 一条消息的附件字节合计上限。
+   */
+  max_message_bytes: number;
+  /**
+   * 一条消息至多带几个附件。
+   */
+  max_per_message: number;
+}
 export interface NodeCapabilities {
   audit: boolean;
   blobs: boolean;
+  /**
+   * daemon 能把任意类型的文件交给任何会话的 agent（非图片、agent 不原生收的图片落到会话工作目录，ADR-44）。
+   * 为 false（旧 daemon）时客户端只能上传图片。
+   */
+  file_attachments?: boolean;
   fs: boolean;
+  /**
+   * 支持 dev server 预览（`preview.*`，ADR-39），且节点配置 `preview.enabled = true`。
+   */
+  preview?: boolean;
   search: boolean;
   /**
    * 有 workspace（文件夹即项目）。SDK 节点可能没有。
@@ -1260,6 +1644,24 @@ export interface NodeCapabilities {
    */
   worktree?: boolean;
 }
+/**
+ * 一个 workspace 根（ADR-45）。每个根下的一级子文件夹都是项目。
+ */
+export interface WorkspaceRootInfo {
+  /**
+   * 现在能用：daemon 启动时它是一个存在的目录，并且现在还在。不可用的根下的项目不出现在列表里，也不能在上面新建 / 克隆；
+   * 配置只在启动时读，修好（挂上外接盘）之后要重启 daemon。
+   */
+  available: boolean;
+  /**
+   * canonical 绝对路径（根不可用时是展开后的配置值）。`workspace.create` / `clone` 的 `root` 取这里的值。
+   */
+  path: string;
+  /**
+   * 主根：放 `.scratch/`，不指定 `root` 时新项目建在这里。恰好有一个。
+   */
+  primary: boolean;
+}
 /**
  * 节点的 worktree 配置（`config.toml` 的 `[worktree]`），客户端据此决定新建会话的初始选择和分支名预览。
  */
@@ -1273,6 +1675,32 @@ export interface NodeWorktreeSettings {
    */
   default_mode: SessionWorkspaceMode;
 }
+/**
+ * `node.logs` 参数。
+ */
+export interface NodeLogsParams {
+  /**
+   * 最低级别：只返回这个级别及更高级别的行。缺省 = 不过滤。
+   */
+  level?: NodeLogLevel | null;
+  /**
+   * 最多返回多少行，缺省 200，最大 1000（超出按 1000）。
+   */
+  lines?: number | null;
+}
+/**
+ * `node.logs` 结果。
+ */
+export interface NodeLogsResult {
+  /**
+   * 日志行，旧的在前、新的在后；每行最多 2 KiB（超出的截断，行尾加 `…`）。
+   */
+  lines: string[];
+  /**
+   * 还有更早的行没有返回（行数到了上限，或扫描的日志量到了上限）。
+   */
+  truncated: boolean;
+}
 export interface NodePairBeginParams {
   /**
    * `true`（缺省）= 16 位短码（约 79 bit；链接、二维码、默认都是它）；`false` = 8 位（约 40 bit），
@@ -1334,6 +1762,15 @@ export interface NodeSetAgentDefaultsParams {
   } | null;
   thinking?: string | null;
 }
+/**
+ * `node.set_config` 参数。所有改动先校验，任何一项不合法就一项都不写。
+ *
+ * 错误：键不在白名单、被环境变量覆盖、想放宽只能收紧的键 → `forbidden`（`data.field` 是键，`data.reason` 是
+ * `not_editable` / `env_override` / `tighten_only`）；值的类型或取值不合法、键重复、`changes` 为空 → `invalid`（`data.field` 是键）。
+ */
+export interface NodeSetConfigParams {
+  changes: ConfigChange[];
+}
 /**
  * `node.set_enroll_enabled` 参数：写 `[enroll]` 配置。`password: true` 同时解除锁定、失败计数清零。
  */
@@ -1446,7 +1883,171 @@ export interface PermissionRespondParams {
   request_id: string;
 }
 /**
- * 一个项目 = workspace 根目录下的一个一级子文件夹，或一个关联的本机目录（`kind = linked`）。
+ * `preview.close` 参数：作废这个 label 的全部票据，断开它的全部隧道。
+ */
+export interface PreviewCloseParams {
+  label: string;
+}
+/**
+ * 隧道 `GOAWAY` 帧的载荷（msgpack，只有 daemon 发，stream 0）：daemon 要关掉这条隧道，之后不再处理它的帧。
+ */
+export interface PreviewGoaway {
+  code: PreviewGoawayCode;
+  message?: string | null;
+}
+/**
+ * 隧道握手第二条消息（daemon → 预览页）的 payload，JSON。到这一条预览页才确认对端持有票据、是钉住的 daemon。
+ */
+export interface PreviewHello {
+  expires_at_ms: number;
+  port: number;
+  session_id?: string | null;
+}
+/**
+ * `preview.list` 的一项：一张未过期的票据。
+ */
+export interface PreviewInfo {
+  created_at_ms: number;
+  /**
+   * 签发这张票据的设备。
+   */
+  created_by: string;
+  created_by_name: string;
+  expires_at_ms: number;
+  label: string;
+  port: number;
+  session_id?: string | null;
+  ticket_id: string;
+  /**
+   * 此刻用这张票据建立的隧道数。
+   */
+  tunnels: number;
+}
+/**
+ * 预览页的启动参数。Web UI 把它序列化成 JSON、再 base64url（无填充），放进
+ * `<预览 origin>/__anycon/enter#<…>` 的 fragment（浏览器不会把 fragment 发给 hub）。引导页读出后存进预览 origin 的
+ * IndexedDB，立即从地址栏抹掉。
+ */
+export interface PreviewLaunch {
+  /**
+   * 票据和令牌里较早的那个过期时间。
+   */
+  expires_at_ms: number;
+  label: string;
+  /**
+   * daemon 的设备 id。
+   */
+  node: string;
+  /**
+   * daemon 的 Noise 静态公钥，64 个小写 hex。预览页用它做 NK 握手（钉住 daemon）。
+   */
+  node_public: string;
+  /**
+   * 打开后先导航到的路径（以 `/` 开头，可带查询串）。
+   */
+  path: string;
+  port: number;
+  psk: string;
+  ticket_id: string;
+  /**
+   * hub 签发的预览令牌（`POST /api/preview/tokens`），预览连接凭它向 hub 认证。
+   */
+  token: string;
+  /**
+   * 格式版本，目前是 1。
+   */
+  v: number;
+}
+export interface PreviewListResult {
+  previews: PreviewInfo[];
+}
+/**
+ * `preview.open` 参数：为本机 `port` 签发一张预览票据。
+ */
+export interface PreviewOpenParams {
+  port: number;
+  /**
+   * 从哪个会话发起（只用于界面展示和审计；端口是否允许不看它，见 spec/daemon.md § 19.3）。
+   */
+  session_id?: string | null;
+}
+/**
+ * `preview.open` 结果。`psk` 是票据的密钥，只交给预览页（放进 [`PreviewLaunch`]），不要写日志、不要发给 hub。
+ */
+export interface PreviewOpenResult {
+  expires_at_ms: number;
+  /**
+   * 这个端口固定的预览 label（26 位小写 base32），预览 origin 是 `<label>.<预览域名>`。
+   */
+  label: string;
+  port: number;
+  /**
+   * 票据密钥，64 个小写 hex（32 字节），Noise PSK。
+   */
+  psk: string;
+  session_id?: string | null;
+  /**
+   * 票据 id，32 个小写 hex（16 字节）。
+   */
+  ticket_id: string;
+}
+export interface PreviewPort {
+  pid?: number | null;
+  port: number;
+  /**
+   * 进程名（可执行文件名，不含参数）。
+   */
+  process?: string | null;
+  session_id?: string | null;
+  source: PreviewPortSource;
+}
+/**
+ * `preview.ports` 参数。带 `session_id` 只列这个会话的端口（外加配置里允许的端口）。
+ */
+export interface PreviewPortsParams {
+  session_id?: string | null;
+}
+export interface PreviewPortsResult {
+  detection: PreviewDetection;
+  ports: PreviewPort[];
+}
+/**
+ * 隧道 `REQUEST` 帧的载荷（msgpack，字段名为键）。
+ */
+export interface PreviewRequestHead {
+  /**
+   * 请求头，按原顺序，名字小写。`cookie` 来自预览页自己的 cookie jar；daemon 转发前改写哪些头见
+   * spec/daemon.md § 19.5。
+   */
+  headers: [string, string][];
+  method: string;
+  /**
+   * 以 `/` 开头，可带查询串；不含 scheme 和主机。
+   */
+  path: string;
+  /**
+   * `true`：这是一个 WebSocket 升级请求（`method` 为 `GET`，子协议在 `sec-websocket-protocol` 头里）。
+   */
+  websocket?: boolean;
+}
+/**
+ * 隧道 `RESET` 帧的载荷（msgpack）：终止这个 stream 的两个方向。
+ */
+export interface PreviewReset {
+  code: PreviewResetCode;
+  message?: string | null;
+}
+/**
+ * 隧道 `RESPONSE` 帧的载荷（msgpack）。WebSocket 流里 `status = 101` 表示升级成功，其他状态码表示被拒，
+ * 后面跟普通响应体。
+ */
+export interface PreviewResponseHead {
+  encoding?: PreviewBodyEncoding & string;
+  headers: [string, string][];
+  status: number;
+}
+/**
+ * 一个项目 = 某个 workspace 根目录下的一个一级子文件夹，或一个关联的本机目录（`kind = linked`）。
  * 元数据全部推导；只有「关联了哪些目录」存在 daemon 的库里。
  */
 export interface Project {
@@ -1468,13 +2069,18 @@ export interface Project {
   missing?: boolean;
   modified_at_ms: number;
   /**
-   * 项目名。根目录下的项目和关联的项目共用一个命名空间，客户端的所有操作都用它。
+   * 项目名。所有 workspace 根下的项目和关联的项目共用一个命名空间，客户端的所有操作都用它。
    */
   name: string;
   /**
    * 绝对路径，仅展示用。
    */
   path: string;
+  /**
+   * 文件夹项目所在的 workspace 根（canonical 绝对路径，等于 `node.info.workspace_roots` 里的某一项的 `path`）；
+   * 关联项目没有。老版本的 daemon 不给，客户端当作主根。
+   */
+  root?: string | null;
 }
 export interface GitMeta {
   branch?: string | null;
@@ -1548,6 +2154,10 @@ export interface SessionArchiveParams {
  */
 export interface SessionChanged {
   archived?: boolean;
+  /**
+   * 同 [`SessionSummary::background_tasks`]。
+   */
+  background_tasks?: number;
   /**
    * 会话被删除。
    */
@@ -1593,7 +2203,8 @@ export interface SessionWorktree {
 export interface SessionCreateParams {
   agent: string;
   /**
-   * 第一条消息的附件（`blob.put_end` 的结果）。agent 的 `capabilities.attachments` 不含其 mime → `unsupported`。
+   * 第一条消息的附件（`blob.put_end` 的结果）。agent 原生收的 mime（`capabilities.attachments`）交给 adapter，
+   * 其余落到会话工作目录、路径写在交给 agent 的文字里（ADR-44）。
    */
   attachments?: AttachmentRef[];
   /**
@@ -1755,6 +2366,11 @@ export interface SessionSummary {
    */
   agent_session_id?: string | null;
   archived?: boolean;
+  /**
+   * agent 进程里还在跑的后台任务数（Claude Code 的后台 subagent、后台命令）。主 turn 结束后它们可能还在干活，
+   * 期间 daemon 不按 `idle_timeout` 回收进程（docs/spec/daemon.md § 7.3）。只反映 daemon 内存里的当前状态，不进事件流。
+   */
+  background_tasks?: number;
   created_at_ms: number;
   id: string;
   /**
@@ -1804,26 +2420,45 @@ export interface SessionRenameParams {
   title: string;
 }
 export interface SessionSearchParams {
+  /**
+   * 最多返回几条命中，默认 20，上限 200。
+   */
   limit?: number | null;
+  /**
+   * 只搜这个项目里的会话。
+   */
   project?: string | null;
+  /**
+   * 空白分隔的若干个词，每个词按前缀匹配、都要出现在同一段文字里；不能为空（`invalid`）。
+   */
   query: string;
 }
 export interface SessionSearchResult {
   hits: SearchHit[];
 }
 export interface SearchHit {
+  /**
+   * 命中的那段文字开始处的事件 seq：用户消息就是 `user_message` 的 seq；assistant 文字是那一段第一个 `text_delta` 的 seq
+   * （长文字每 32 KiB 切一段索引，所以同一条回复可以有几个不同的 seq）。
+   */
   seq: number;
   session_id: string;
   /**
-   * 带 `<mark>` 的片段。
+   * 命中处的片段。除了包住命中词的字面 `<mark>` / `</mark>`，里面没有 HTML：会话文字里原有的
+   * `<` `>` `&` 已转义成 `&lt;` `&gt;` `&amp;`，客户端按 `<mark>` 切开后把这三个实体还原成字符、
+   * 当纯文本显示即可，不要当 HTML 解析。
    */
   snippet: string;
+  /**
+   * 会话当前的标题。
+   */
   title: string;
   ts_ms: number;
 }
 export interface SessionSendParams {
   /**
-   * `blob.put_end` 的结果，每条至多 20 个。agent 的 `capabilities.attachments` 不含其 mime → `unsupported`。
+   * `blob.put_end` 的结果，每条至多 20 个。agent 原生收的 mime（`capabilities.attachments`）交给 adapter，
+   * 其余落到会话工作目录、路径写在交给 agent 的文字里（ADR-44）。
    */
   attachments?: AttachmentRef[];
   /**
@@ -1888,10 +2523,14 @@ export interface SessionSyncBaseResult {
 export interface TrashEntry {
   bytes: number;
   /**
-   * `.trash/` 下的目录名，如 `my-app-20261011T120000Z`。
+   * `.trash/` 下的目录名，如 `my-app-20261011T120000Z`。每个根有自己的 `.trash/`，id 在所有根之间唯一。
    */
   id: string;
   original_name: string;
+  /**
+   * 条目所在（也是 `restore` 还原到）的 workspace 根。老版本的 daemon 不给，客户端当作主根。
+   */
+  root?: string | null;
   trashed_at_ms: number;
 }
 /**
@@ -1988,6 +2627,10 @@ export interface RenamedProject {
 }
 export interface WorkspaceCloneParams {
   name?: string | null;
+  /**
+   * 克隆到哪个 workspace 根下，规则同 `WorkspaceCreateParams.root`。
+   */
+  root?: string | null;
   /**
    * 只允许 `https://`、`ssh://`、`git@host:path` 三种形式。
    */
@@ -1996,6 +2639,11 @@ export interface WorkspaceCloneParams {
 export interface WorkspaceCreateParams {
   git_init?: boolean;
   name: string;
+  /**
+   * 在哪个 workspace 根下新建。必须是 `node.info.workspace_roots` 里的某一项的 `path`；缺省 = 主根；
+   * 不在列表里 → `invalid`，在列表里但现在不可用（`available = false`）→ `not_found`。
+   */
+  root?: string | null;
 }
 /**
  * `workspace.link`：把本机一个已有目录关联为项目。
@@ -2013,6 +2661,9 @@ export interface WorkspaceLinkParams {
 }
 export interface WorkspaceListResult {
   projects: Project[];
+  /**
+   * 主根（`node.info.workspace_roots` 里 `primary` 的那一项）。其余根下的项目看 `Project.root`。
+   */
   root: string;
 }
 export interface WorkspaceNameParams {