@weavecode/weave 0.1.2 → 0.1.4

package/node_modules/@weavecode/harness/dist/driver.d.ts

@@ -7,7 +7,7 @@ import type { FileAssetCategory } from './shared/file-specs.js';
  * 依赖硬约束：本包仅依赖 @weavecode/core（永不依赖 server/cli，防 statusline/i18n 成环）。
  */
 /** 可插拔能力槽——driver 声明持有哪些，注册表按能力检索。 */
-export type HarnessCapability = 'init' | 'events' | 'assets' | 'resume' | 'detect' | 'plugins' | 'pluginState' | 'messaging' | 'questions' | 'capture' | 'statusline';
+export type HarnessCapability = 'init' | 'events' | 'assets' | 'resume' | 'detect' | 'plugins' | 'pluginState' | 'messaging' | 'questions' | 'capture' | 'statusline' | 'logs' | 'config' | 'edits' | 'images' | 'narration' | 'commands' | 'provision' | 'liveness';
 /**
  * 采集集成的 user 档状态（tool-object-model §2.6 基石）。
  */
@@ -84,6 +84,61 @@ export interface EventSource {
     readonly events: readonly string[];
     normalize(report: unknown, projectId: number): unknown;
 }
+/**
+ * 一条从外部日志读出来的原始上报 + 它的真实时刻（历史回填不能印成插入时刻）。
+ * `report` 与 hook 上报同形，故 server 拿它走**同一个** `EventSource.normalize`。
+ */
+export interface LogRecord {
+    report: {
+        eventType: string;
+        sessionId?: string;
+        cwd?: string;
+        payload: unknown;
+    };
+    /** 事件真实时刻（ISO；日志行自带时间戳优先，缺失才用文件 mtime）。 */
+    at: string;
+}
+export interface LogPollOptions {
+    /** 游标 / 边读缓存落点（daemon 传 `<dataDir>/logs/<harness>`）。 */
+    stateDir: string;
+    /**
+     * 只采这些工作目录的会话（daemon 从 projects 表 + 项目 `.weave/config.yaml` 算出）。
+     * 命中即把**该目录原文**回填进 `report.cwd`——路径归一（大小写、分隔符、解析）
+     * 是日志源自己的事，调用方按原样等值匹配即可。
+     */
+    cwdWhitelist: readonly string[];
+    /** 单拍上限：到顶就返回，游标只推进到真读过的位置（下一拍续）。 */
+    maxRecords?: number;
+    maxBytes?: number;
+}
+/** 日志源健康（诊断面只读；「没数据」与「读不到」要分得开）。 */
+export interface LogHealth {
+    /** 宿主数据根（不存在 = 该 harness 没在本机用过）。 */
+    root: string | null;
+    /** 白名单内可读的日志文件数。 */
+    files: number;
+    /** 最近一次真读到新行的时刻（ISO）。 */
+    lastPollAt: string | null;
+    /** 最近一次错误（读不动 / 落盘失败）；正常为 null。 */
+    lastError: string | null;
+}
+/**
+ * 日志源槽：**拉取式**采集面。`events` 槽答「一份上报怎么归一」，前提是有人把
+ * 上报递进来（hook 脚本写 inbox 文件）；没有 push 面的 harness（codex 只把会话
+ * 写在自己的 rollout JSONL 里）需要第二个答案——这份数据从哪来。故本槽只负责
+ * 「读出新行」，归一化仍归同一个 harness 的 `events` 槽：server 不认识任何
+ * harness 的文件格式，harness 也不认识 projects 表。
+ *
+ * 契约：poll 幂等（游标落 `stateDir`，重启不重放）且守预算（到 maxRecords /
+ * maxBytes 即返回）；只挑白名单工作目录的会话，别的一行都不产出。
+ */
+export interface LogSource {
+    readonly harness: Harness;
+    poll(options: LogPollOptions): Promise<LogRecord[]>;
+    health(options: {
+        stateDir: string;
+    }): Promise<LogHealth>;
+}
 /**
  * 资产落盘表面查询（批 4a 补全）：「某 harness 的资产落哪 / 怎么分类」的知识
  * 从 server 六处散落收敛进本接口的实现（`claude/assets.ts` / `codex/assets.ts`），
@@ -96,18 +151,35 @@ export interface EventSource {
  * 类型住这里而非 server：它出现在 [[AssetSurface]] 的方法签名上，server 反向
  * import 会绕回来。
  */
-export interface McpServerConfig {
+export interface McpStdioConfig {
     command: string;
     args?: string[];
     env?: Record<string, string>;
 }
+/**
+ * Streamable HTTP 形态（daemon 托管的 MCP 用这一形）：`url` 即端点，
+ * `headers` 是客户端要带的头（本机令牌走它），`bearerTokenEnvVar` 只有 codex
+ * 支持（Bearer 必须来自环境变量，不许写死明文）。判别靠 `'command' in cfg`。
+ */
+export interface McpHttpConfig {
+    url: string;
+    /** 宿主自己的传输标签（claude 会写 `"type": "http"`），原样保留。 */
+    type?: string;
+    headers?: Record<string, string>;
+    bearerTokenEnvVar?: string;
+}
+export type McpServerConfig = McpStdioConfig | McpHttpConfig;
 export interface AssetSurface {
     /** 所属 harness——按序遍历多个 surface 时回指归属（`classifyAgent` 消费）。 */
     readonly harness: Harness;
     /** 某资产类别在指定 scope 的目标目录；无该表面则抛错（同 `fileAssetTargetDir` 语义）。 */
     targetDir(category: FileAssetCategory, scope: 'project' | 'user', projectPath: string, homedir: string): string;
-    /** 项目内 skills 目录（相对项目根，posix 分隔；`skillsDirFor` 消费）。 */
-    projectSkillsDir(): string;
+    /**
+     * 项目内 skills 根（相对项目根，posix 分隔）：[0] 为安装写入目标，其后为
+     * 只读的生态共用根（Codex 的 `.agents/skills`——它自己两处都读；installer/
+     * classifier 消费）。
+     */
+    projectSkillsRoots(): string[];
     /**
      * 全局 skills 根（绝对路径）：[0] 为安装写入目标，其后为只读遗留根
      * （Codex 的 deprecated `~/.codex/skills`；global-config 消费）。
@@ -171,9 +243,34 @@ export interface ResumeCommandSpec {
      * 「在默认终端打开会话」消费；缺省 = 该 harness 不支持交互式打开（501）。
      */
     openArgs?(sessionId: string): string[];
+    /**
+     * 交互式启动的固定旗标（置于 openArgs 之前）：只加在「终端里起交互会话」
+     * 这一侧（new-session / open-terminal），无头 `args` 不带。
+     */
+    launchArgs?: string[];
+    /**
+     * 编排边级提取的无头 fork 参数：从上游会话派生一个**一次性 fork 回合**提炼
+     * 信息（`['--resume', sessionId, '--fork-session', '--no-session-persistence',
+     * '--session-id', forkSessionId]` 形态），不动原会话、不留转录。缺省 = 该
+     * harness 无 fork 提取能力（codex 留位，调用方回落只读上游输出）。
+     * `forkSessionId` 由 server 预生成并登记合成会话（ingest 侧过滤），harness 只定键形。
+     */
+    extractArgs?(sessionId: string, forkSessionId: string): string[];
+    /**
+     * `bin` 的版本下限（semver）：低于它的宿主，weave 的会话功能不可信 → 起不了
+     * 新会话（UI 置灰并说明）。缺省 = 不设闸。
+     */
+    minVersion?: string;
+    /**
+     * 起会话后的引导注入文本（weave new-session spawn 成功后延时打进 pane 并提交）。
+     * 使命：懒建会话档案的宿主（codex 的 rollout 首条消息才落盘）靠一条**零模型调用**
+     * 的本地命令（如 `/rename <项目名>`）强制建档，会话行即刻进列表。缺省 = 该
+     * harness 无需引导（claude 启动即发 SessionStart）。
+     */
+    bootstrapText?(projectName: string): string;
 }
 /** 消息通道名——支持矩阵与原因文案的键。 */
-export type MessagingChannel = 'discovery' | 'prompt' | 'inject' | 'headless' | 'watch' | 'sideQuestion';
+export type MessagingChannel = 'discovery' | 'prompt' | 'inject' | 'headless' | 'watch' | 'sideQuestion' | 'pathRefs';
 /** 非抢占注入通道规格：注入可骑乘的事件（hook-handler 在这些事件上消化 outbox 行）。 */
 export interface InjectChannelSpec {
     rideEvents: readonly string[];
@@ -204,23 +301,73 @@ export interface PromptRelaySpec {
     } | null;
 }
 /**
- * 图片随 prompt 投递的对齐面：「一张图怎么被这个 harness 认出来」是 harness 表示法
- * （claude = 裸绝对路径，它自己的粘贴处理器按 `\.(png|jpe?g|gif|webp)$` 把路径转成
- * `[Image #N]` + 真 image block），server 只传语义参数（原文 + 落盘图的可读路径 /
- * 媒体类型 / 原文件名），怎么引用归这里。null = 该 harness 不支持收图。
+ * 附件类型：`image` = 宿主认得图（claude 的粘贴处理器按
+ * `\.(png|jpe?g|gif|webp)$` 把路径变成 `[Image #N]` 占位 + 真 image block）；
+ * `file` = 其它文件，**宿主没有附件形态**，提示词里只有一条路径，由模型自己读。
+ */
+export type AttachKind = 'image' | 'file';
+/**
+ * 附件随 prompt 投递的对齐面：「一个已落盘的文件怎么被这个 harness 认出来」是
+ * harness 表示法（claude = 裸绝对路径、一行一条），server 只传语义参数（原文 +
+ * 落盘件的可读路径 / 媒体类型 / 原文件名），怎么引用归这里。null = 该 harness
+ * 不接受任何附件。
  */
-export interface ImageAttachSpec {
+export interface AttachSpec {
+    /** 收哪些类型；`image` 缺席 = 图片入口不摆，`file` 缺席 = 文件入口不摆。 */
+    readonly kinds: readonly AttachKind[];
     /**
-     * 把「用户原文 + 已落盘图片」合成投递 prompt 文本。images 恒非空；text 可为空
-     * （纯图发送）。返回值走三条层投递，**用户原文不得被改写**（回执比对靠它做包含
-     * 匹配）——只允许追加引用形态。
+     * 把「用户原文 + 已落盘附件」合成投递 prompt 文本。files 恒非空；text 可为空
+     * （纯附件发送）。返回值走三条层投递，**用户原文不得被改写**（回执比对靠它做包含
+     * 匹配）——只允许追加引用形态。原文里已含某附件路径（web 占位胶囊的原地展开）
+     * 时该附件不再追加；删掉胶囊路径即从原文消失，追加自动恢复。
      */
-    composePrompt(text: string, images: readonly {
+    composePrompt(text: string, files: readonly {
         path: string;
         mediaType: string;
         name: string;
     }[]): string;
 }
+/** 一条项目内路径的类型（`PathRefSpec.kinds` 的取值）。 */
+export type PathRefKind = 'file' | 'dir';
+/** 引用的一段行区间：1 基、含两端（`start === end` 即单行）。 */
+export interface PathRefLines {
+    start: number;
+    end: number;
+}
+/**
+ * 路径引用面：「一条项目内路径怎么被这个 harness 认出来」是 harness 表示法
+ * （claude = `@<相对路径>` 的 mention 文法），server 只传路径与类型，web 只把
+ * 服务端回给的表达式**当不透明字符串**贴进输入框——两侧都不自拼。null = 该
+ * harness 没有这种引用文法（入口不渲染）。
+ */
+export interface PathRefSpec {
+    /** 该 harness 能引用什么。 */
+    readonly kinds: readonly PathRefKind[];
+    /** 认不认行区间（false = 选择器只给整文件/整目录引用，不摆设行号选择）。 */
+    readonly lines: boolean;
+    /** 贴进 prompt 的表达式；path 为项目相对路径（会话 cwd = 项目根）。 */
+    expression(input: {
+        path: string;
+        kind: PathRefKind;
+        lines?: PathRefLines;
+    }): string;
+    /**
+     * `expression` 的逆运算：从一段**现成文本**里认出引用表达式（粘贴回填 /
+     * 取回队列消息时把表达式还原成胶囊）。只认文法、不问存在——「这个路径真在
+     * 项目里吗」是调用方拿文件索引判的，不归文法。
+     */
+    recognize(text: string): RecognizedRef[];
+}
+/** `PathRefSpec.recognize` 认出的一处引用：`start`/`end` 是在原文里的下标区间。 */
+export interface RecognizedRef {
+    start: number;
+    end: number;
+    /** 原文那一段（调用方可以拿 `expression` 归一后替换）。 */
+    ref: string;
+    path: string;
+    kind: PathRefKind;
+    lines?: PathRefLines;
+}
 /**
  * 旁路会话（宿主 TUI 里的侧问，claude = `/btw`）规格：问一次不打断主回合的
  * 轻量提问。**宿主既不留转录也不发 prompt 事件**（claude 侧问查询 `skipTranscript`），
@@ -244,6 +391,38 @@ export interface SideQuestionSpec {
      * 普通子 agent 与 skill 子 agent 都有转录，skipTranscript 的 fork 才没有）。
      */
     answerOf(eventType: string, payload: unknown): string | null;
+    /**
+     * 读屏通道（codex = `/side`）：宿主的侧边会话 ephemeral——零落盘、零 hook
+     * 事件，回答只能从 pane 屏幕取。声明了它，server 走「开面板 → 发问句 →
+     * 轮询读屏 → 关面板」的同步路径；缺省 = 事件认领路径（claude）。
+     */
+    screen?: SideQuestionScreenSpec;
+    /** 发起侧问的前置条件说明（不满足时 409 文案直用）；缺省 = 无前置。 */
+    prerequisite?: string;
+}
+/** 读屏通道的 harness 侧文法（屏幕形态是版本耦合知识，判据全在这里）。 */
+export interface SideQuestionScreenSpec {
+    /** 开侧边面板的键序（如 `/side` + 提交键）。 */
+    openKeys: string;
+    /** 提交键（实测 CR 单发比连体稳——TUI 启动/切换面板时常吃掉连体的 CR）。 */
+    submitKey: string;
+    /** 关面板键（codex = ctrl+c）。 */
+    closeKey: string;
+    /**
+     * 屏幕上有没有开着的侧边面板（收尾键序的前置闸：面板已被用户关掉时，
+     * closeKey 会落进主线程语境——忙时弹中断确认菜单、闲时直接退出 TUI，
+     * 盲打比不收尾糟得多）。
+     */
+    panelOpen(screen: string): boolean;
+    /**
+     * 从屏幕文本提取回答。`before` = 问句发出前的屏幕快照（区分新旧内容）；
+     * `done` = 回合已落定（还在跑时 false，调用方继续轮询）；`answer` = null 且
+     * done = 判不出（如实落 timeout，不猜——屏幕文法随宿主版本变）。
+     */
+    extractAnswer(question: string, before: string, now: string): {
+        answer: string | null;
+        done: boolean;
+    };
 }
 /** 信封渲染入参。 */
 export interface MessageMeta {
@@ -313,6 +492,12 @@ export interface PlanSpec {
     /** 这次工具调用带的计划内容；与计划无关返回 null。 */
     draftOf(toolName: string | null, toolInput: unknown, toolResponse: unknown): PlanDraft | null;
 }
+/** 阻塞提问前模型写下的说明正文（转录里认）。 */
+export interface PreQuestionText {
+    /** 该条 assistant 消息的时刻（ISO UTC，转录 timestamp）。 */
+    at: string;
+    text: string;
+}
 /**
  * 阻塞式交互面（会话卡住等输入：AskUserQuestion / 计划确认 / 权限确认）：
  * 哪些工具会挂起、权限通知类型、问题面归一化与作答键序全归 harness——
@@ -346,12 +531,25 @@ export interface BlockingPromptSpec {
     /** 阻塞工具的 PreToolUse toolInput → 问题列表（含合成问题：计划确认的 toolInput 恒空）。 */
     parseQuestions(toolName: string, toolInput: unknown): BlockingQuestion[];
     /**
-     * 事件弹框（不是工具、也非权限提醒的对话框，如 claude 的「Switch model?」）：
-     * 事件到达且**对话框确实要弹**时返回问题面，否则 null。条件（弹不弹）是 harness
-     * 知识——宿主自己有一套触发判据，猜错就成幽灵问题（面板有问、终端无框，键序
-     * 会打进输入框）。落定沿用 permission 态口径（后续任何非 Notification 事件即了结）。
+     * 事件弹框（不是工具、也非权限提醒的对话框，如 claude 的「Switch model?」、
+     * codex 的审批框）：事件到达且**对话框确实要弹**时返回问题面，否则 null。条件
+     * （弹不弹）是 harness 知识——宿主自己有一套触发判据，猜错就成幽灵问题（面板
+     * 有问、终端无框，键序会打进输入框）。落定沿用 permission 态口径（后续任何非
+     * Notification 事件即了结）。载荷 = 归一化视图（toolName/toolInput 已提升到
+     * 顶层；raw 里的同名键被 compactRaw 折叠成引用，读工具面必须走顶层）。
      */
-    eventQuestion(eventType: string, raw: unknown): BlockingQuestion | null;
+    eventQuestion(eventType: string, payload: {
+        raw: unknown;
+        toolName: string | null;
+        toolInput: unknown;
+    }): BlockingQuestion | null;
+    /**
+     * 阻塞提问前模型写下的说明正文（转录尾部最后一条阻塞工具调用之前的 assistant
+     * 文本；claude 把一条 assistant 消息拆成相邻多行，正文与工具调用同 message.id）。
+     * 阻塞提问不发 Stop ⇒ hook 事件里没有这段话，转录是唯一来源。null = 没有
+     * （没在提问 / 提问前没写字）。
+     */
+    preQuestion?(transcriptPath: string | null): Promise<PreQuestionText | null>;
 }
 /**
  * 会话本地收件箱直投规格（层①-a，**harness 专属机制**：claude = inbox socket）。
@@ -371,6 +569,29 @@ export interface PromptInboxSpec {
         text: string;
     }): string;
 }
+/**
+ * 宿主自带的排队投递（codex queue）：消息写进目标会话自己的队列——活会话 <1s 注入、
+ * 没开的会话下次 resume 自动领走，且**在宿主眼里就是用户输入**（没有带外来源位）。
+ * 这层比终端击键更接近「用户本人发送」，故手动面也允许走它（层序见 MessageDeliverer）。
+ *
+ * `command` 一次给全 bin + argv：win32 的 `codex` 是 npm `.cmd` 垫片，CreateProcess
+ * 不认，必须由 harness 换成可直接 spawn 的入口（node + 包 bin）；用户正文只出现在
+ * argv 里、不经 shell 拼接。
+ */
+export interface QueuedPromptSpec {
+    command(sessionId: string, text: string): {
+        bin: string;
+        args: string[];
+    };
+    /** 单次超时（毫秒）——队列是一次性小操作，挂住即当失败回落下一层。 */
+    readonly timeoutMs?: number;
+}
+/**
+ * 会话 pane 定位 env 的信源。hook 旁路上报的 env 生在会话自己的进程树里才可信
+ * （claude）；hook 由宿主共享 daemon 代跑的 harness（codex）env 冻结在 daemon
+ * 启动地，系统性失真——改信 weave 起会话时的 spawn 回执起点（`launch`）。
+ */
+export type PaneEnvSource = 'hook' | 'launch';
 /**
  * 会话消息能力面（session-orchestration 批 1）：每 harness 一份声明式规格，
  * server 的 MessageDeliverer 按面裁决支持状态与编排控制；claude = 完整参考实现，
@@ -385,16 +606,22 @@ export interface MessagingSurface {
     readonly prompt: PromptRelaySpec | null;
     /** 会话本地收件箱直投（层①-a，毫秒级）；null = 该 harness 没有这类机制。 */
     readonly promptInbox: PromptInboxSpec | null;
+    /** 宿主自带的排队投递（宿主侧队列）；null = 该 harness 没有这类机制。 */
+    readonly queuedPrompt: QueuedPromptSpec | null;
     /** 非抢占注入通道（忙排）；null = 不支持。 */
     readonly inject: InjectChannelSpec | null;
     /** 无头强制回合通道（闲投）；null = 不支持。引用 resume 槽规格对象，不复制。 */
     readonly headless: ResumeCommandSpec | null;
     /** 空闲信号事件名（watch 触发源）；空数组 = 不支持空闲订阅。 */
     readonly idleSignals: readonly string[];
+    /** 会话 pane 定位 env 的信源（hook 旁路上报 vs weave 起会话的 spawn 回执起点）。 */
+    readonly paneEnvSource: PaneEnvSource;
     /** 注入信封渲染（缺省 = server 的 weave 统一信封）。 */
     renderEnvelope?(text: string, meta: MessageMeta): string;
-    /** 图片随 prompt 的对齐面；null = 该 harness 不支持收图（web 据此置灰附件钮）。 */
-    readonly imageAttach: ImageAttachSpec | null;
+    /** 附件随 prompt 的对齐面；null = 该 harness 不收附件（web 据此置灰附件钮）。 */
+    readonly attach: AttachSpec | null;
+    /** 项目内路径的引用文法；null = 该 harness 没有这种文法（web 据此不渲染入口）。 */
+    readonly pathRefs: PathRefSpec | null;
     /** 旁路会话（侧问）；null = 该 harness 没有这种机制（web 据此不渲染入口）。 */
     readonly sideQuestion: SideQuestionSpec | null;
     /** 不支持通道的语义原因（409 文案与 UI tooltip 直用）。 */
@@ -541,6 +768,307 @@ export interface StatuslineSurface {
 }
 /** 缓存里的块事实：与 `buildPreviewItems` 吃的 token 表同形。 */
 export type StatuslineFacts = Record<string, Record<string, string>>;
+/**
+ * 配置档位：host 读配置文件的四个落点。`global` 指宿主单独放「全局 config」键的
+ * 那个文件（claude = `~/.claude.json`，与 settings 文件不是一回事）。
+ */
+export type ConfigFileId = 'user' | 'project' | 'projectLocal' | 'global';
+/** 一个档位的落点；`profiles` = 该档支持本地多份配置（快照/切换）。 */
+export interface ConfigFileSpec {
+    id: ConfigFileId;
+    path(ctx: {
+        projectPath: string | null;
+        homedir: string;
+    }): string;
+    profiles: boolean;
+}
+/**
+ * 词表里的一条键。条目的**类型原文**（含枚举说明）来自官方文档，web 自己决定控件；
+ * `options` 只是从类型文案里认出来的候选值，认窄了不致命（前端始终留手填口）。
+ */
+export interface ConfigKeySpec {
+    key: string;
+    /** 文档主题（分组表头）。 */
+    group: string;
+    type: string;
+    options?: readonly string[];
+    /** 文档默认值原文（展示用，不是结构化值）。 */
+    default?: string;
+    description: string;
+    /** 该键在哪个文件生效；`managed` = 只在组织托管设置里认。 */
+    scope: 'any' | 'managed' | 'user' | 'project' | 'local' | 'global';
+    deprecated?: boolean;
+    /** 由「Fields for」表补出的子字段（文档没有独立条目）。 */
+    nested?: boolean;
+    /**
+     * 值的容器形状：`map` = 键名由用户起（模型名、技能名…，拼不成点号路径）、
+     * `array` = 有序列表。有它时 `fields` / `valueType` + `valueOptions` 描述**值**。
+     */
+    shape?: 'map' | 'array';
+    /** 值（map）/ 元素（array）是对象时，它有哪些字段。 */
+    fields?: readonly ConfigFieldSpec[];
+    /** 值（map）/ 元素（array）是标量时的类型与枚举；`fields` 非空则以字段为准。 */
+    valueType?: string;
+    valueOptions?: readonly string[];
+}
+/** 对象值的一个字段（`type` / `options` 与顶层键同文法，控件也同一套）。 */
+export interface ConfigFieldSpec {
+    name: string;
+    type: string;
+    options?: readonly string[];
+    description?: string;
+}
+/** 数组里的一条 weave 托管条目：`path` 是数组的点号路径，`entry` 是那条的当前值。 */
+export interface ConfigManagedEntry {
+    path: string;
+    entry: string;
+}
+/** `env` 块里可写的环境变量（值恒为字符串，`kind` 只决定输入控件）。 */
+export interface ConfigEnvVarSpec {
+    name: string;
+    description: string;
+    kind: 'string' | 'boolean' | 'number' | 'list' | 'enum' | 'path';
+    options?: readonly string[];
+}
+export interface ConfigCatalog {
+    groups: readonly string[];
+    keys: readonly ConfigKeySpec[];
+    envVars: readonly ConfigEnvVarSpec[];
+}
+/** 模型列表接口返回的一条（字段名归 harness，web 只认 id/name）。 */
+export interface ConfigModelOption {
+    id: string;
+    name?: string;
+    createdAt?: string;
+}
+/**
+ * 配置面：一个 harness 的配置文件**词表 + 读写**。
+ *
+ * 为什么整块归 harness：文件落点、键形、哪些键是 weave 自己写进去的（改了就断
+ * 采集/插件/statusline）、模型列表接口的文法，全是 harness 知识；server 只做
+ * 存储、深路径合并与 HTTP 传输，web 只渲染词表。
+ */
+export interface ConfigSurface {
+    readonly harness: Harness;
+    /** 该 harness 的配置文件档位（project 档在 `projectPath` 缺省时路径无意义）。 */
+    files(ctx: {
+        projectPath: string | null;
+        homedir: string;
+    }): ConfigFileSpec[];
+    /** 某档可见的词表（`global` 档只列本档生效的键）。 */
+    catalog(file: ConfigFileId): ConfigCatalog;
+    /** 读该档的配置；文件不存在 → 空对象。`global` 档只回本档可见的键。 */
+    read(file: ConfigFileId, ctx: {
+        projectPath: string | null;
+        homedir: string;
+    }): Promise<Record<string, unknown>>;
+    /** 整体写（原子）：`global` 档只把可见键并回文件，其余键原样保留。 */
+    write(file: ConfigFileId, ctx: {
+        projectPath: string | null;
+        homedir: string;
+    }, values: Record<string, unknown>): Promise<void>;
+    /**
+     * weave 写进去的键（按当前值判，如 statusLine 只有指向 weave 脚本时才算）：
+     * 表单里只读并指向对应面板——手改会把采集/插件/statusline 改坏。
+     */
+    managedKeys(values: Record<string, unknown>): readonly string[];
+    /**
+     * weave 写进数组里的条目（行级托管）：只有这些行只读，同一个数组里用户自己的行照常
+     * 增删——按「整个数组」判会把 30 条用户规则一起锁死。
+     */
+    managedEntries(values: Record<string, unknown>): readonly ConfigManagedEntry[];
+    /**
+     * 模型列表（HTTP 调宿主自己的 API）。`baseUrl` / 凭据缺省时由实现从配置里取；
+     * 传输在实现侧，server 只传语义参数。`homedir` 供实现解析配置里的相对路径
+     * （codex 的 `model_catalog_json` 相对 CODEX_HOME）。`file` 让实现知道当前
+     * 档位——项目档缺地址/凭据时可继承 user 档的 env（claude）。
+     */
+    models(input: {
+        values: Record<string, unknown>;
+        file?: ConfigFileId;
+        homedir?: string;
+        baseUrl?: string | null;
+        apiKey?: string | null;
+        authToken?: string | null;
+        timeoutMs?: number;
+    }): Promise<{
+        models: ConfigModelOption[];
+        baseUrl: string;
+        credential: string;
+    }>;
+    /** 活文件的表示格式（raw 视图的编辑语言；快照/漂移 diff 也按它渲染）。 */
+    readonly rawFormat: 'json' | 'toml';
+    /** 活文件原文 → 值对象（解析失败抛错，调用方给 400）。 */
+    parseRaw(text: string): Record<string, unknown>;
+    /** 值对象 → 活文件原文（write 落盘前的最后一跳，格式归 harness）。 */
+    serializeRaw(values: Record<string, unknown>): string;
+}
+/** 一处改动：改前 → 改后。宿主只给片段（claude 的 Edit 就是 old_string/new_string）就只摆片段。 */
+export interface EditHunk {
+    /** 改前的文本；整文件新写 = 空串（「新建」在汇总里也是一处改动，不能消失）。 */
+    before: string;
+    /** 改后的文本。 */
+    after: string;
+}
+/** 按时间序返回的一处改动（同一文件可以有多条，汇总归 server）。 */
+export interface FileEdit {
+    /** 文件绝对路径——相对项目的展示名由 server 算，宿主不拼。 */
+    path: string;
+    hunk: EditHunk;
+    /** 这处改动的时刻（ISO）；宿主没带 → null。 */
+    at: string | null;
+}
+/**
+ * 会话改动面（「这次对话把哪些文件改成了什么样」）：读哪、怎么认改文件的调用都是
+ * harness 知识（claude = 转录里的 Edit/Write/MultiEdit 工具调用），server 不解析
+ * 宿主格式，只按文件汇总后交前端渲染 diff。
+ */
+export interface EditsSurface {
+    /** 该会话的全部改动（时间序）；读不到（无转录 / 路径未知 / 半路出错）→ null（不猜）。 */
+    sessionEdits(req: {
+        sessionId: string;
+        /** 转录路径（server 的探针答，宿主不自己拼目录）；null = 不知道在哪。 */
+        transcriptPath: string | null;
+    }): Promise<FileEdit[] | null>;
+}
+/** 一张粘贴进宿主输入框的图（转录里的 image block 解出来的原始字节）。 */
+export interface PromptImage {
+    /** MIME（`image/png` 这类）；认不出的类型上游就该丢掉。 */
+    mediaType: string;
+    bytes: Uint8Array;
+}
+/** 转录里的一条 user 消息 + 它随附的图（时间序）。 */
+export interface PromptImageSet {
+    /** 该条消息的正文（宿主保留 `[Image #N]` 占位——匹配事件时按它归一比对）。 */
+    text: string;
+    /** 消息时刻（ISO）；宿主没带 → null。 */
+    at: string | null;
+    images: PromptImage[];
+}
+/**
+ * 入站图采集面：宿主输入框里粘的图**只活在转录**（hook 载荷只有 `[Image #N]` 占位），
+ * server 因此在这里问「这段对话里的图长什么样」，再自己落 uploads + 挂到开轮事件。
+ * 缺这个槽 = 该 harness 的入站图无处可取（对话里只剩占位记号）。
+ */
+export interface ImagesSurface {
+    /** 带图的那几条 user 消息（时间序）；读不到（无转录 / 路径未知 / 半路出错）→ null（不猜）。 */
+    sessionImages(req: {
+        sessionId: string;
+        /** 转录路径（server 的探针答，宿主不自己拼目录）；null = 不知道在哪。 */
+        transcriptPath: string | null;
+    }): Promise<PromptImageSet[] | null>;
+}
+/** 转录里的一段 assistant 正文（时间序）。 */
+export interface NarrationText {
+    /** 该条 assistant 消息的时刻（ISO UTC，转录 timestamp）；宿主没带 → null。 */
+    at: string | null;
+    text: string;
+}
+/**
+ * 旁白采集面：模型在一轮里的**全部** assistant 正文（时间序）。hook 域只有
+ * Stop 的 `last_assistant_message` 一个文本载体——一轮里多次输出（写工具后又
+ * 补一段收尾）只有最后一句能进对话气泡，前面的没有任何事件照会，转录是唯一
+ * 来源。缺这个槽 = 该 harness 的中间输出无处可取（对话里只有每轮收尾那句）。
+ */
+export interface NarrationSurface {
+    /** 全部 assistant 正文（时间序，含每轮收尾那句）；读不到 → null（不猜）。 */
+    sessionNarration(req: {
+        sessionId: string;
+        /** 转录路径（server 的探针答，宿主不自己拼目录）；null = 不知道在哪。 */
+        transcriptPath: string | null;
+    }): Promise<NarrationText[] | null>;
+    /**
+     * 行文法（增量监视用）：喂一行转录原文，吐该行认出的段（0 或 1 段）。
+     * 与 `sessionNarration` 共用同一份文法——全量读是「逐行 feed」，增量监视是
+     * 「只 feed 新增字节切出的行」。缺省 = 该 harness 不支持增量监视（web 退回
+     * 轮边界补采）。
+     */
+    lineParser?(line: string): NarrationText | null;
+}
+/**
+ * 聊天窗口 `/` 提示里的一条命令：内建命令来自宿主（版本快照，随升级复核），
+ * 其余按目录现扫（自定义命令 / skill / 插件 skill）。
+ */
+export interface HarnessCommand {
+    /** 不含触发符；插件/skill 命令带 `<plugin>:<skill>` 形态。 */
+    name: string;
+    /** 一句话说明（skill 取 SKILL.md frontmatter）。 */
+    description: string;
+    /** 参数提示（形如 `<model>` / `<file>`）；没有参数就省略。 */
+    argsHint?: string;
+    source: 'builtin' | 'command' | 'skill' | 'plugin';
+    /** 触发符：缺省 `/`；codex 的 skill 是 `$name`。前端按它展示与插胶囊。 */
+    sigil?: '/' | '$';
+}
+/** 转录里的一条命令执行记录（内建命令不发 hook 事件，只有转录记着）。 */
+export interface CommandExecution {
+    name: string;
+    args: string;
+    /** 执行时刻（ISO UTC）。 */
+    at: string;
+    /** 宿主回显的输出原文；命令没有输出就省略。 */
+    output?: string;
+}
+/**
+ * 命令面：聊天窗口 `/` 的候选清单 + 命令执行的返显。
+ * `executions` 答 null = 该 harness 的转录不记命令执行（前端如实说明，不空转）。
+ */
+export interface CommandsSurface {
+    readonly harness: Harness;
+    /** 该会话此刻可用的命令（项目级命令按项目路径现扫；`homedir` 缺省 = 本机家目录）。 */
+    list(req: {
+        projectPath: string;
+        homedir?: string;
+    }): Promise<HarnessCommand[]>;
+    /** 转录里的命令执行（时间序）；读不到（无转录 / 路径未知 / 半路出错）→ null（不猜）。 */
+    executions(transcriptPath: string | null): Promise<CommandExecution[] | null>;
+}
+/**
+ * 安装形态检查面（init 环境备置消费）：答「这台机器上该 harness 的多副面孔是否
+ * 互相打架」。有桌面端 + CLI 双形态的 harness（codex）在此声明冲突判据与修法；
+ * 单形态 harness（claude）不补槽——没有冲突可言，调用方按槽缺席跳过。
+ */
+export interface ProvisionCheck {
+    /** 桌面端（GUI app）是否在本机。 */
+    desktopApp: boolean;
+    /** 共享后台（daemon 包）是否在本机。 */
+    daemonPackage: boolean;
+    /** 检出的冲突（英文原文，i18n 由调用方包一层）。 */
+    warnings: readonly string[];
+    /** 每条冲突对应的官方修法命令。 */
+    hints: readonly string[];
+}
+export interface ProvisionSurface {
+    readonly harness: Harness;
+    check(bin: string): Promise<ProvisionCheck>;
+}
+/**
+ * 会话存活面：答「这个 harness 的会话进程还活着吗」。判据是 harness 专属知识
+ * （claude = `~/.claude/sessions/<pid>.json` 注册表 + kill 0；codex = thread-writer-locks
+ * 独占锁），server 不自拼。探测是异步批量（codex 的锁探针要 spawn PowerShell），
+ * 消费方要同步 map——由装配层缓存（见 server 的 liveness 装配助手）。
+ */
+export interface LivenessSurface {
+    readonly harness: Harness;
+    /**
+     * 批量探测给定会话的存活。只输出**判得动**的条目（判不动的会话不进 map，
+     * 上游把「查不到」当未知，不许误判死）；`ids` 缺省 = 全量。
+     */
+    alive(ids?: readonly string[]): Promise<Map<string, boolean>>;
+}
+/**
+ * 会话标题读写面：宿主侧**用户自定义名**（codex = thread name，落 session_index
+ * 与 sqlite threads.name）的读/写通道。读 = 宿主持久层 diff 采纳（TUI 改名反显
+ * 前端）；写 = 官方 RPC（thread/name/set，前端改名进宿主）。claude 不挂此槽——
+ * 它的名字通道是 hook session_title 双向管线，不经这里。
+ */
+export interface SessionTitleSurface {
+    readonly harness: Harness;
+    /** 宿主侧当前用户自定义名；无名/无文件返回 null（宿主清除名字时置空串 → null）。 */
+    sessionTitleOf(sessionId: string): Promise<string | null>;
+    /** 经官方通道写宿主侧名字；trim 后空串抛错，宿主拒绝/超时/协议不认识抛错。 */
+    setSessionTitle(sessionId: string, name: string): Promise<void>;
+}
 /** 单个 harness 的驱动：id/displayName 必填，能力槽按批次补齐。 */
 export interface HarnessDriver {
     id: Harness;
@@ -557,6 +1085,16 @@ export interface HarnessDriver {
     questions?: BlockingPromptSpec;
     capture?: CaptureSurface;
     statusline?: StatuslineSurface;
+    logs?: LogSource;
+    config?: ConfigSurface;
+    edits?: EditsSurface;
+    images?: ImagesSurface;
+    narration?: NarrationSurface;
+    commands?: CommandsSurface;
+    provision?: ProvisionSurface;
+    liveness?: LivenessSurface;
+    /** 不入 capabilities 清单——无 web 面，消费点仅 server 两处（dispatcher diff 采纳 / PATCH rename RPC）。 */
+    titles?: SessionTitleSurface;
 }
 /**
  * 能力槽注册表：先到先得（同 id 重复注册抛错，对齐插件先加载者胜）；