@anycon/protocol 0.1.0 → 0.2.0

package/dist/generated.d.ts

@@ -6,12 +6,21 @@ export type AgentStatus = ("ready" | "disabled" | "not_installed" | "not_authent
  */
 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。
  */
 export type Control = {
     client: ClientInfo;
     device_token?: string | null;
+    preview_token?: string | null;
     protocol_version: number;
     type: "auth";
 } | {
@@ -79,6 +88,10 @@ export type Control = {
 } | {
     device: string;
     type: "peer_offline";
+} | {
+    label: string;
+    peer: string;
+    type: "preview_peer";
 } | {
     seq: number;
     to: string;
@@ -100,6 +113,7 @@ export type Control = {
     type: "dropped";
 } | {
     retry_after_ms: number;
+    to?: string | null;
     type: "rate_limited";
 } | {
     quota: Quota;
@@ -223,6 +237,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";
 } | {
@@ -251,7 +270,18 @@ export type Event = {
     title: string;
     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";
@@ -300,6 +330,79 @@ 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";
@@ -316,6 +419,32 @@ export type SessionStatus = ("starting" | "running" | "waiting_permission" | "id
  * `Event::Git` 的动作。
  */
 export type GitAction = ("sync_up_to_date" | "sync_merged" | "sync_conflicts" | "sync_aborted") | "worktree_created" | "worktree_failed" | "worktree_removed" | "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。
  */
@@ -324,11 +453,34 @@ 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`。
  */
 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";
 /**
  * 项目从哪来。
  */
@@ -392,6 +544,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;
@@ -412,6 +568,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;
@@ -423,6 +580,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;
@@ -433,11 +591,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;
@@ -450,6 +612,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;
@@ -501,6 +683,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;
@@ -551,7 +734,8 @@ export interface AgentInfo {
 }
 export interface AgentCapabilities {
     /**
-     * 可接受的附件 mime，如 `image/png`。
+     * agent **原生**收的附件 mime，如 `image/png`。其它附件（非图片、这里没列出的图片格式）不受它限制：daemon 把它们落到
+     * 会话工作目录并在文字里附上路径（ADR-44）。
      */
     attachments?: string[];
     /**
@@ -652,7 +836,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 {
@@ -662,7 +846,7 @@ export interface AttachmentRef {
     mime: string;
     name: string;
     /**
-     * 图片像素宽高（daemon 读文件头得出；读不出来时省略）。客户端用来在下载前占好位置。
+     * 图片像素宽高（daemon 读文件头得出；读不出来、不是图片时省略）。客户端用来在下载前占好位置。
      */
     width?: number | null;
 }
@@ -700,11 +884,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;
     /**
@@ -786,6 +972,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;
@@ -886,6 +1113,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` 仍是
@@ -897,6 +1129,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 {
@@ -920,12 +1157,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 {
@@ -957,6 +1204,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;
@@ -989,6 +1245,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`。第一段是关联项目的名字时，其余部分相对那个目录解析，
@@ -1007,21 +1313,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 {
@@ -1057,6 +1392,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[];
 }
@@ -1145,6 +1486,10 @@ export interface NodeEnrollStatusResult {
  * `node.info` 结果。
  */
 export interface NodeInfo {
+    /**
+     * `capabilities.blobs` 为 true 时给出。
+     */
+    attachment_limits?: NodeAttachmentLimits | null;
     capabilities: NodeCapabilities;
     name: string;
     node_id: string;
@@ -1152,16 +1497,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 节点可能没有。
@@ -1172,6 +1550,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]`），客户端据此决定新建会话的初始选择和分支名预览。
  */
@@ -1185,6 +1581,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），
@@ -1246,6 +1668,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` 同时解除锁定、失败计数清零。
  */
@@ -1358,7 +1789,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 {
@@ -1380,13 +1975,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;
@@ -1460,6 +2060,10 @@ export interface SessionArchiveParams {
  */
 export interface SessionChanged {
     archived?: boolean;
+    /**
+     * 同 [`SessionSummary::background_tasks`]。
+     */
+    background_tasks?: number;
     /**
      * 会话被删除。
      */
@@ -1505,7 +2109,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[];
     /**
@@ -1667,6 +2272,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;
     /**
@@ -1716,26 +2326,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[];
     /**
@@ -1800,10 +2429,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;
 }
 /**
@@ -1900,6 +2533,10 @@ export interface RenamedProject {
 }
 export interface WorkspaceCloneParams {
     name?: string | null;
+    /**
+     * 克隆到哪个 workspace 根下，规则同 `WorkspaceCreateParams.root`。
+     */
+    root?: string | null;
     /**
      * 只允许 `https://`、`ssh://`、`git@host:path` 三种形式。
      */
@@ -1908,6 +2545,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`：把本机一个已有目录关联为项目。
@@ -1925,6 +2567,9 @@ export interface WorkspaceLinkParams {
 }
 export interface WorkspaceListResult {
     projects: Project[];
+    /**
+     * 主根（`node.info.workspace_roots` 里 `primary` 的那一项）。其余根下的项目看 `Project.root`。
+     */
     root: string;
 }
 export interface WorkspaceNameParams {