@epoch-agent/runtime 0.2.0 → 0.3.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { GoalRoundResult, Goal, GoalWrite, GoalClear, Workspace, TrustDecision, ProjectContext, RecentWorkspace, TrustGate, RecentWorkspaces, PermissionManager, SessionManager, FtsHealth, FtsReclaim, AgentLoop, PluginCommandDir, InstallPreview, PluginRecord, PluginSourceType, PluginCounts, MarketplaceEntry, ScheduleRegistrar, HeadlessPolicy, CreateScheduleInput, ScheduleIssue, RegisterOutcome, UpdateScheduleInput, needsAllowlist, HookSourceStatus, ConfigOrigins, SkillDirSpec, ProviderRouter, AgentProvider, GoalService, MemoryManager, SkillSystem, SkillLearner, HookManager, ContextCompressor, TrackerDB, TrustManager, ModelPricing, LayerOutcome, ManagedPolicy, PluginArtifacts, CheckpointSummary, RewindPreview, RewindOutcome, ToolRevealState, CodeSandbox, ISkillSystem, ToolRegistry, QuestionAskFn, ResponseFormat, ProviderWarning, SettingValue, SettingLayer, SettingStep, SettingWriteTarget, SessionReferences, IsolationReport, RoleMergeNotice, SkillMeta, SkillIndexResidency, SkillImportResult, SkillImportPreview, SkillImportDone, ShadowFinding, BaseOrigin, PermissionAuditScope, PermissionAuditSnapshot, CachedApproval, ToolGate, SettingWriteLayer, SettingApply, SettingWriteFailure, PluginPathRef } from '@epoch-agent/core';
+import { GoalRoundResult, Goal, GoalWrite, GoalClear, Workspace, TrustDecision, ProjectContext, RecentWorkspace, TrustGate, RecentWorkspaces, PermissionManager, SessionManager, FtsHealth, FtsReclaim, AgentLoop, PluginCommandDir, InstallPreview, PluginRecord, PluginSourceType, PluginCounts, MarketplaceEntry, ScheduleRegistrar, HeadlessPolicy, CreateScheduleInput, ScheduleIssue, RegisterOutcome, UpdateScheduleInput, needsAllowlist, HookSourceStatus, ConfigOrigins, SkillDirSpec, ProviderRouter, AgentProvider, GoalService, MemoryManager, SkillSystem, SkillLearner, HookManager, ContextCompressor, TrackerDB, TrustManager, ModelPricing, LayerOutcome, ManagedPolicy, PluginArtifacts, ComplianceEngine, CheckpointSummary, RewindPreview, RewindOutcome, ToolRevealState, CodeSandbox, ISkillSystem, ToolRegistry, QuestionAskFn, ResponseFormat, ProviderWarning, SettingValue, SettingLayer, SettingStep, SettingWriteTarget, SettingValueKind, SessionReferences, IsolationReport, RoleMergeNotice, SkillMeta, SkillIndexResidency, SkillImportResult, SkillImportPreview, SkillImportDone, ShadowFinding, BaseOrigin, PermissionAuditScope, PermissionAuditSnapshot, CachedApproval, ToolGate, SettingWriteLayer, SettingApply, SettingWriteFailure, PluginPathRef } from '@epoch-agent/core';
 export { DEFAULT_GOAL_MAX_ROUNDS, MAX_GOAL_MAX_ROUNDS, MAX_OBJECTIVE_CHARS, MAX_REASON_CHARS, SANDBOX_COVERS, SANDBOX_EXCLUDES, SCHEDULE_DEFAULTS, SCHEDULE_DEFAULT_ALLOWLIST, nextRunAt, readRecording, skillIndexDescription } from '@epoch-agent/core';
 import { McpServerConfig, McpServerStatus, McpServerSource, McpTransport, McpAuthStatus } from '@epoch-agent/plugin-mcp';
 export { McpAuthState, McpAuthStatus, McpServerConfig } from '@epoch-agent/plugin-mcp';
@@ -2204,6 +2204,14 @@ interface ProviderOption {
     envVar: string | null;
     /** 这台机器上这把 key 配好了没有。**不需要 key 的那家恒 `true`** */
     hasKey: boolean;
+    /**
+     * 那把 key 长什么样 —— **脱敏后的**（`maskApiKey`）。没配 / 不需要时是 `null`。
+     *
+     * ⚠️ 这一格是**唯一**一处让解出来的 key 沾到外面的地方，而它沾出去的是
+     * 一个不可逆的展示串。判据（以及「为什么一个布尔不够」）在网线那一份
+     * `WireProviderOption.keyHint` 上。
+     */
+    keyHint: string | null;
 }
 /** 探一家的结果。和网线那一份 `WireModelSuggestions` 逐字同形 */
 interface ModelSuggestions {
@@ -2218,13 +2226,25 @@ interface DiscoverOptions {
     /** 绕开磁盘缓存重新探。同 `epoch model --refresh` */
     refresh?: boolean;
 }
+/** {@link ModelCatalogControl.setKey} 写完之后，那把 key 落到哪儿了 */
+interface ProviderKeyWritten {
+    /** 写进的那个环境变量名。回声一遍 —— 调用方手里只有 provider 类型 */
+    envVar: string;
+    /** `keychain` / `dpapi` / `libsecret` / `plaintext`。**必须回显给用户** */
+    backend: string;
+    encrypted: boolean;
+    /** 明文降级时那个 `.env` 在哪儿；进了加密后端就是 `null` */
+    envPath: string | null;
+    /** 脱敏后的那把 key。⚠️ **不是原文**，判据同 {@link ProviderOption.keyHint} */
+    keyHint: string;
+}
 /**
- * 宿主看得见的那一面 —— **只有两个动词**。
+ * 宿主看得见的那一面 —— **两个问句加一个写**。
  *
  * `clearModelCache` 刻意不单独露出来：它唯一的正当用法就是「清掉再探一次」，
  * 而那两步之间任何一次早退都会留下一个**被清空却没有重填**的缓存，
  * 下一次探不通时用户看到的是「一个模型都没有」而不是上次那份。
- * 所以它被并进 {@link discover} 的 `refresh` 里，两步绑死。
+ * 所以它被并进 {@link discover} 的 `refresh`（以及 {@link setKey} 的收尾）里，两步绑死。
  * 同 `WorkspaceControl` 刻意不露 `seed()`、`McpControl` 只有 `reconnect()`。
  */
 interface ModelCatalogControl {
@@ -2242,6 +2262,33 @@ interface ModelCatalogControl {
      * 探这一家有哪些模型。**从不抛，也从不回 null** —— 见 {@link ModelSuggestions.status}。
      */
     discover(provider: ProviderType, opts?: DiscoverOptions): Promise<ModelSuggestions>;
+    /**
+     * 给这一家配一把 key（2026-08-31）。落点由 `SecretStore` 的降级链决定，
+     * 结果回声在 {@link ProviderKeyWritten} 上。
+     *
+     * ## ⚠️ 这一个和上面两个不同档：它**会抛**
+     *
+     * 上面两个是问句，问不到有一档「探不到」可落；这一个是**写**，
+     * 而一次没落地的写没有「另一档结果」—— 静默吞掉等于告诉用户「配好了」
+     * 而其实没有。两种抛法：
+     *
+     * - 这家**不要 key**（Ollama，`apiKeyEnv === null`）。这不是运行期故障，
+     *   是调用方问错了问题 —— 收窄口上不该存在一个「配了也没用」的动作，
+     *   所以它在这儿就断，不往下走到 store。
+     * - `SecretStore` 那一发自己失败（钥匙串拒绝、磁盘满）。原样抛出去。
+     *
+     * ## 写完**顺手清掉这一家的模型缓存**，两步绑死
+     *
+     * 探测结果落盘缓存 24 小时。不清的话，用户刚配完 key 再探一次，
+     * 拿到的还是没 key 那会儿回退出来的**静态目录** —— 而
+     * `cli/src/commands/model.ts` 的文件头逐字记着那个后果：
+     * 「后果不是『少几个模型』而是**列表完全不对**」。
+     * 这一步不给调用方选，同 `discover` 的 `refresh` 不给单独的 `clear`。
+     *
+     * ⚠️ 「让本进程立刻看得见这把 key」那一步**不在这儿**，在 infra 的
+     * `writeProviderSecret()` 里 —— `epoch model` 和这条路要的是同一件事。
+     */
+    setKey(provider: ProviderType, apiKey: string): Promise<ProviderKeyWritten>;
 }
 interface ModelCatalogOptions {
     /** 数据目录。缓存文件和凭据解析都按它分命名空间 */
@@ -2751,10 +2798,24 @@ interface RoleWriteControl {
  */
 type LevelChangeResult = {
     ok: true;
+    /**
+     * 「记住这一档」那一半的结局（2026-08-31）。**只在没记住时有值** ——
+     * 记住了、或者这一发压根没要求记（`remember: false`）时是 `undefined`。
+     *
+     * ⚠️ 它**不影响 `ok`**：档位已经换成了。两件事分开报的判据在
+     * {@link RememberDefaultLevel} 上。
+     */
+    notRemembered?: RememberFailure;
 } | {
     ok: false;
     reason: 'managed-bypass-disabled';
 };
+/** 没记住的成因。**码不是句子**，逐字对应 `WirePermissionRememberFailure`（判据在那儿） */
+type RememberFailure = {
+    reason: 'no-user-config' | 'unwritable' | 'io' | 'env-pinned';
+    /** 本来要写的那个文件；说不出路径的那一档整个不带 */
+    path?: string;
+};
 /**
  * Plan 模式的出口（方案 35）。
  *
@@ -2819,7 +2880,7 @@ interface SessionPermissions {
         bypassDisabled: boolean;
     };
     /**
-     * 切到某一档。**这是改权限档位的唯一入口**，三件事必须在这一次调用里
+     * 切到某一档。**这是改权限档位的唯一入口**，四件事必须在这一次调用里
      * 一起发生，顺序也是判据：
      *
      * 1. **托管挡 bypass**（方案 22 §2.6）。挡下时级别一个字不动，回 `ok:false`；
@@ -2827,11 +2888,20 @@ interface SessionPermissions {
      * 3. **`plan.forget()`**：用户接管了方向盘，plan 模式记着的「进入前那一档」
      *    当场作废。⚠️ 是 `forget()` 不是 `leave()`：后者会把级别**恢复**成进入前
      *    那一档，正好覆盖掉用户这一下刚选的那个。
+     * 4. **`opts.remember` 为真时把它记成新会话的起点**（2026-08-31）。
+     *    排在第 3 步之后不是随手排的：记的是「用户此刻要的那一档」，
+     *    而第 1 步可能已经把这一发整个否掉了。
      *
      * 判定住在这一处而不是每个宿主抄一份 —— 抄一份的具体代价是**第三步会被漏掉**，
      * 而那件事只在「plan 模式 + 中途换档 + 批准计划」三件事凑齐时才看得见。
+     *
+     * @param opts.remember 这一发**算不算用户显式挑的**。必填，判据全文在
+     *   {@link DefaultLevelSlot} 那张三行表上 —— 一句话：定时任务的
+     *   `def.permission` 走的是同一个方法，而它绝不能改用户的默认档。
      */
-    setLevel: (level: PermissionLevel) => LevelChangeResult;
+    setLevel: (level: PermissionLevel, opts: {
+        remember: boolean;
+    }) => LevelChangeResult;
 }
 
 /**
@@ -3021,7 +3091,9 @@ interface ExecutorRuntime {
     } | null;
     permission: PermissionManager | null;
     permissions: {
-        setLevel: (level: ScheduleDefinition['permission']) => LevelChangeResult;
+        setLevel: (level: ScheduleDefinition['permission'], opts: {
+            remember: boolean;
+        }) => LevelChangeResult;
         rules: () => ReadonlyArray<{
             bucket: 'allow' | 'ask' | 'deny';
             rule: string;
@@ -3316,6 +3388,16 @@ interface Services {
      *
      * ⚠️ 它是**起点**不是现状：`permission.getLevel()` 才是「此刻是哪一档」，
      * 而那一格从这一轮起一个会话一份。
+     *
+     * ⚠️ **2026-08-31：它是「起点的初值」，不再是起点本身。**
+     * 起点从这一轮起会动（用户显式挑一档就跟着走），那一格是
+     * `session-guard.ts` 的 `DefaultLevelSlot`，`build.ts` 用这个字段给它开局。
+     * 上面那句「新建的会话从这一档起步」因此要读成「**第一个**新建的会话」——
+     * 用户换过档之后，起点是他挑的那一档。
+     *
+     * 那句「不继承别的会话此刻那一档」**一个字都没变**：改起点的是「用户挑」这个
+     * 动作，不是别的会话的现状（plan 模式和定时任务都改得动某个会话此刻那一档，
+     * 而起点一个字不动 —— 三行表在 `DefaultLevelSlot` 上）。
      */
     permissionLevel: PermissionLevel;
     contextEngine: ContextCompressor | null;
@@ -3400,6 +3482,17 @@ interface Services {
      * 在这儿接等于把「MCP 从哪儿来」分成两处答。
      */
     plugins: PluginArtifacts;
+    /**
+     * 内容合规闸门（core 的 `compliance/`）。
+     *
+     * **关掉时是 `null` 而不是一个「什么都不拦」的引擎**：`AgentConfig.compliance`
+     * 缺席那条路上，模型输出一个字都不多走一层（判据在 `ComplianceEngine`
+     * 的文件头 —— 不开这个功能的用户不该为它付任何代价）。
+     *
+     * 装配层每一处 `new AgentLoop` 都要把它填进去，子 agent 那条也要。
+     * 会红的门禁在 `runtime/__tests__/compliance-wiring.test.ts`。
+     */
+    compliance: ComplianceEngine | null;
     /** 需要在退出时执行的清理动作，后进先出 */
     cleanups: Array<() => void>;
 }
@@ -4297,22 +4390,34 @@ declare function applyMcpConfig(mcp: McpApplySource, sync: ToolSync, opts: {
  * 一个已有字节都不用碰：逗号长在**新**那一段上。所以新加的排在文件最前面，
  * 那是这条判据的结果，不是随手定的顺序。
  *
- * ## 扫描器只认三样东西，**不做 `JSON.parse`**
- *
- * 字符串（含转义）、`//` 行注释、`/* *\/` 块注释 —— 够定位 `servers` 那个对象的
- * `{`，也够把它已有的成员名数出来（撞名要用）。
+ * ## 扫描器搬走了，判据没变
  *
- * ⚠️ **写口扛得住注释，而读口今天扛不住**（`parseMcpConfig` 走的是硬 `JSON.parse`）。
- * 两件事都是真的，别把它们并成一句：写口的职责是「别毁掉他的文件」，不是「替读口
- * 再校验一遍」。让 `mcp.json` 支持注释是**另一次决定**（它改的是「哪些配置算合法」，
- * 落点在 plugin-mcp），这一轮不接 —— 但这一轮**绝不能**因为读口读不了就把那几行
- * 注释顺手抹掉。
+ * 那一段（`skipTrivia` / `readString` / `skipValue` / `walkObject` / `locate` /
+ * `indentOf`）2026-09-02 搬进了 [mcp-json-scan.ts](./mcp-json-scan.ts)，因为
+ * 有了第二、第三个调用方（就地**替换**和**删除**，见下）。判据全文跟着一起搬，
+ * 别在这儿读一个摘要就动手。
  *
  * ## 看不懂就一个字节都不写
  *
- * 我们对这个文件只有**一次插入**的权利。猜错一次的代价是把他手写的配置弄坏，
- * 而他知道这件事的时刻是「MCP 全没了」的那一天。所以扫描器走不到收尾的 `}`
- * 就整段拒绝，并把「哪儿看不懂」说出来。
+ * 猜错一次的代价是把他手写的配置弄坏，而他知道这件事的时刻是「MCP 全没了」的
+ * 那一天。所以扫描器走不到收尾的 `}` 就整段拒绝，并把「哪儿看不懂」说出来。
+ *
+ * ## 📮 2026-09-02：「我们对这个文件只有**一次插入**的权利」这句话翻了
+ *
+ * 上面那一节原来的开头就是这句话，它是本文件所有判据的总纲。**这一轮把它推翻
+ * 了**，而推翻它的理由不是「插入不够用」，是**模型手上那条路没有第二个选项**：
+ *
+ * `mcp_update` / `mcp_remove` 那两个工具（[mcp-tools.ts](./mcp-tools.ts)）要么
+ * 走就地改写，要么走「读原文 → 整份写回」。而后者意味着**把整份 `mcp.json` 交进
+ * 模型的上下文** —— 里面装着他每一台 server 的 `env` 密钥（判据在
+ * `writeMcpConfigFile` 那句「新建的那一档给 0600，因为这个文件天生装着 token」）。
+ * 一条为了保住排版而存在的判据，不该以「顺带把密钥全交出去」为代价来维持。
+ *
+ * ⚠️ **所以变的是「几次」，不是「什么」。** 就地替换和删除照旧是**定位 + 拼接
+ * 文本**，`parse → serialize` 那一步在这一族里仍然不存在，上面那三节
+ * （round-trip 更毒 / 只做追加不成立 / 另存一处不成立）一个字都没过期。
+ * 删除是这一族里**唯一**会动到用户已经写下的字节的动作（那个逗号），
+ * 它的边界逐条写在 [mcp-config-edit.ts](./mcp-config-edit.ts) 文件头。
  */
 
 /**
@@ -4363,6 +4468,11 @@ type McpWriteFailure = {
     reason: 'unwritable';
     detail: string;
 };
+/** 插进文本之后的产物，或者为什么没插 */
+type McpSpliceOutcome = {
+    ok: true;
+    text: string;
+} | McpWriteFailure;
 /** 落盘之后的结局。`configPath` 要发到界面上 —— 用户接下来多半想去改那个文件 */
 type McpWriteOutcome = {
     ok: true;
@@ -4396,6 +4506,116 @@ declare function writeMcpServer(input: McpAddInput, opts?: {
     taken?: Iterable<string>;
 }): McpWriteOutcome;
 
+/**
+ * `~/.epoch/mcp.json` 的**就地替换与删除**（2026-09-02）—— 隔壁
+ * [mcp-config-write.ts](./mcp-config-write.ts) 那条插入路的另外两个动作。
+ *
+ * ## 它为什么存在：模型手上那条路没有第二个选项
+ *
+ * 判据全文在那个文件头的「📮 2026-09-02」那一节，一句话：`mcp_update` /
+ * `mcp_remove` 要么走就地改写，要么走「把整份原文交进模型的上下文再整份写回」，
+ * 而那份原文里装着用户**每一台** server 的 `env` 密钥。一条为了保住排版而存在
+ * 的判据，不该以「顺带把密钥全交出去」为代价来维持。
+ *
+ * ⚠️ **变的是「几次」，不是「什么」。** 这里照旧是**定位 + 拼接文本**，
+ * `parse → serialize` 那一步在这一族里仍然不存在 —— 注释、空行、字段顺序、
+ * snake_case 键名、未知键，凡是不在被改那一台身上的，一个字节都不动。
+ *
+ * ## ⚠️ 一、删除是这一族里唯一会动到**用户已经写下的字节**的动作
+ *
+ * 插入之所以能做到零改动，是因为逗号长在**新**那一段上（那个文件头第 39 行那一
+ * 节）。删除做不到：被删的那台前面或后面那个逗号是**他写的**，而留着它就是一份
+ * 坏 JSON。所以这一条边界必须明写：
+ *
+ * **我们只动那一个逗号，以及只装着空白的那一行。** 具体说：
+ *
+ * | 现场                                   | 动了什么                                     |
+ * | -------------------------------------- | -------------------------------------------- |
+ * | 它后面紧跟一个逗号（中间只有空白）     | 连那个逗号一起删                             |
+ * | 它是最后一个成员，前面有一个逗号       | 连**前面**那个逗号一起删                     |
+ * | 删完那一行只剩空白                     | 整行连换行一起删（不留一行空缩进）           |
+ * | 删完那一行还剩别的东西（注释、另一台） | **只删它自己那一段**，那一行剩下什么留什么   |
+ *
+ * ⚠️ **「中间只有空白」是硬条件，别放宽成 `skipTrivia`。** 那个函数会跳过注释，
+ * 于是
+ *
+ * ```jsonc
+ * "a": { … }
+ * // 这台先不用
+ * ,
+ * ```
+ *
+ * 里那条注释会落在删除区间里 —— 一次静默的注释丢失，而用户看不出是谁干的。
+ * 判据同插入那条「绝不能因为读口读不了就把那几行注释顺手抹掉」。
+ *
+ * 剩下一档**明说不管**：逗号后面同一行上挂着的行尾注释（`"a": {…}, // 关于 a`）。
+ * 删掉 `a` 之后那条注释会孤零零留在原处。留着它是刻意的 —— 判它「属于 a」要
+ * 猜，而猜错就是删掉用户写的一句话。**一条孤儿注释是噪音，删错一句话是损失。**
+ *
+ * ## ⚠️ 二、替换**不改名字**
+ *
+ * `replaceServerText` 拿 `input.name` 去找那一台，然后把它整段换成新渲染的一段
+ * —— 键名前后一样。改名是「删一台 + 加一台」两个动作，不是这一个：一台 server
+ * 的名字会原样变成工具名的一部分（`mcp__<name>__<工具>`），把改名藏在「更新」
+ * 底下的表现是模型以为自己改了一格配置，而实际上它手上那一批工具全部换了名字。
+ *
+ * ## 三、替换沿用**原文那一台的缩进**，不按 `indent.repeat(2)` 拼
+ *
+ * 判据在 `renderEntry` 的 `pad` 参数上：替换是接在原文已有的缩进后面写的。
+ * 按固定层数拼出来的收尾 `}` 会跑到一个和它上下文对不齐的列上，而那是一次
+ * **看得见的**排版破坏 —— 恰恰是这一族判据要防的那种。
+ */
+
+/**
+ * 「这个名字在文件里没有」单独一档。
+ *
+ * 不并进 `McpWriteFailure` 的 `invalid-name`：那一档说的是「这个名字不合法」
+ * （换个名字），这一档说的是「合法，但文件里没有这一台」（去列一遍，或者改用
+ * 添加）。两者的下一步完全不同，而模型只能照回执里那句话选下一步。
+ */
+type McpEditFailure = McpWriteFailure | {
+    ok: false;
+    reason: 'not-found';
+    detail: string;
+};
+/** 落盘之后的结局。`configPath` 要发到回执上 —— 用户接下来多半想去看那个文件 */
+type McpEditOutcome = {
+    ok: true;
+    configPath: string;
+} | McpEditFailure;
+/**
+ * 把一台**换成**新的一段，其余字节一个不动。
+ *
+ * 纯函数（文本进、文本出），没有 fs —— 「注释和顺序没被抹掉」那条断言才断得住。
+ */
+declare function replaceServerText(raw: string, input: McpAddInput): McpSpliceOutcome;
+/**
+ * 把一台**删掉**，其余字节一个不动（除了那一个逗号，判据在文件头第一节）。
+ *
+ * 纯函数（文本进、文本出）。
+ */
+declare function removeServerText(raw: string, name: string): McpSpliceOutcome;
+/**
+ * 改一台已有 server 的配置。**名字不变**，判据在文件头第二节。
+ *
+ * 成员名单**一个字都不该变**（连顺序）—— 那条断言是「替换切歪了」的唯一报警。
+ */
+declare function updateMcpServer(input: McpAddInput, opts?: {
+    homeDir?: string;
+    lang?: Lang;
+}): McpEditOutcome;
+/**
+ * 删掉一台 server。
+ *
+ * ⚠️ **删掉最后一台是一个合法动作** —— 一份 `{"servers": {}}` 是完全正常的
+ * `mcp.json`（绝大多数机器上就是这样）。拿「改完还有没有 server」当校验条件
+ * 会把这一档挡掉，所以这里的校验是**名单少掉点名那一个**，不是「名单非空」。
+ */
+declare function removeMcpServer(name: string, opts?: {
+    homeDir?: string;
+    lang?: Lang;
+}): McpEditOutcome;
+
 /**
  * 工具装配 —— 插件 + 内置工具 + MCP 外部工具，全部进同一个 ToolRegistry。
  *
@@ -4531,6 +4751,28 @@ type McpAddOutcome = {
     status: McpServerStatus;
     configPath: string;
 } | McpWriteFailure;
+/**
+ * 一次「改」的结局（2026-09-02）。形状**和 {@link McpAddOutcome} 一样**，
+ * 因为这两件事在界面 / 回执上要说的话一样（配置落在哪儿 + 这台此刻连上没）。
+ *
+ * 失败那一侧多一档 `not-found`（`McpEditFailure`）—— 判据在那个类型上：
+ * 「这个名字不合法」和「合法但文件里没这一台」的下一步完全不同。
+ */
+type McpUpdateOutcome = {
+    ok: true;
+    status: McpServerStatus;
+    configPath: string;
+} | McpEditFailure;
+/**
+ * 一次「删」的结局（2026-09-02）。
+ *
+ * ⚠️ **没有 `status`**，那不是漏了：这台 server 在这个进程里已经不存在了，
+ * 交一份状态出去就是交一份必然过期的东西。回执要说的只有「从哪个文件里删掉的」。
+ */
+type McpRemoveOutcome = {
+    ok: true;
+    configPath: string;
+} | McpEditFailure;
 /**
  * 宿主看得见的那一面 —— **重连，加上「添加」**（后者 2026-08-18 补的）。
  *
@@ -4582,6 +4824,34 @@ interface McpControl {
      * 不是「能不能添加」。别拿这个方法倒推出一个 `setEnabled`。
      */
     add(input: McpAddInput): Promise<McpAddOutcome>;
+    /**
+     * 改一台已有 server（2026-09-02）：就地换掉 `mcp.json` 里那一段，再按新配置
+     * 把它重连一次。
+     *
+     * ## ⚠️ 它和 {@link applyConfig} 不是同一个动作，别把它实现成那个的单台版
+     *
+     * `applyConfig` 的宾语是**整份文件**：该断的断、该连的连，包括用户此刻在
+     * 编辑器里刚存下的别的改动。这一条的宾语是**你点名的那一台** —— 别的 server
+     * 一个字节都不碰，哪怕文件里有别人刚写下的待生效改动。
+     *
+     * 那条差别对模型侧那个工具是硬要求：一次 `mcp_update` 顺带把用户还没打算生效
+     * 的三台一起重连了，屏幕上说的却是「改了一台」。
+     *
+     * ## ⚠️ 名字改不了，那是形状不是限制
+     *
+     * `input.name` 是**查询键**，不是新名字。改名等于换掉这台 server 暴露的
+     * 每一个工具名（`mcp__<name>__<工具>`），判据全文在
+     * [mcp-config-edit.ts](./mcp-config-edit.ts) 文件头第二节。
+     */
+    update(input: McpAddInput): Promise<McpUpdateOutcome>;
+    /**
+     * 删掉一台 server（2026-09-02）：从 `mcp.json` 里去掉那一段，在这个进程里
+     * 断开它，并把它那批工具从注册表里摘掉。**不可撤销。**
+     *
+     * ⚠️ 只删得掉 `mcp.json` 里那批（`source === 'user'`）。宿主注入的和插件带来
+     * 的两批天生不在这份文件里 —— 判据同 {@link applyConfig} 那条 ⚠️。
+     */
+    remove(name: string): Promise<McpRemoveOutcome>;
     /** 读一遍 `~/.epoch/mcp.json` 的**原文**（2026-08-18）。什么都不改 */
     readConfig(): McpConfigReadOutcome;
     /**
@@ -4939,6 +5209,18 @@ declare function utilityBudgetKey(input: {
  *    而且**只回文本**：二进制探测在前 8KB 上做（判据同 `file_read` 那一条），
  *    不让一个 100MB 的 mp4 为了确认自己是二进制而整个进内存。
  *
+ * ## ⚠️ 2026-09-02：这一格**多了第二个消费方**，而它才是它今天最要紧的用途
+ *
+ * Web UI 的「输出里的路径可点 → 站内查看」走的就是这三个方法
+ * （`GET /api/sessions/:id/file-stat` / `/file` / `/file-bytes`）。
+ * `web/src/inspector/preview.tsx` 的文件头当年拒过这件事，理由是「一个 REST
+ * 端点不走工具执行器，用户写的 `deny file_read(.env*)` 拦不到它」——
+ * **那条理由说的是别处，不是这儿**：上面第 3 条正是为它准备的。
+ *
+ * 所以这一格从今天起是一条**用户也走的路**，而不只是 `@` 补全的后台。
+ * 往上面加方法时判据没变：**任何一个新方法都必须过同一道 `file_read` 闸**，
+ * 少一个，浏览器就能看到模型看不到的东西 —— 而那正是当年拒绝那条端点的理由本身。
+ *
  * ## 这一份是**镜像**，不是「把 core 的类型导出来」
  *
  * 三个函数和 core 的 `WorkspaceFiles` / `resolveInWorkspace` / `readOne` 逐个
@@ -4973,9 +5255,9 @@ interface FileCandidatesResult {
 /**
  * 装配时要递进来的 core 那一份。
  *
- * 写成**两个函数**而不是一个对象：这一格只要这两样，而它俩今天都住在 core 的
- * 两个不同文件里 —— 合成一个对象的话，宿主将来想自己供一份（比如内存文件树）
- * 就得把两个不相关的东西绑在一起。
+ * 写成**三个函数**而不是一个对象：这一格只要这几样，而它们今天住在 core 的
+ * 三个不同文件里 —— 合成一个对象的话，宿主将来想自己供一份（比如内存文件树）
+ * 就得把几个不相关的东西绑在一起。
  */
 interface WorkspaceFilesDeps {
     listFiles(root: string): {
@@ -4983,6 +5265,17 @@ interface WorkspaceFilesDeps {
         truncated: boolean;
     };
     resolveInWorkspace(root: string, userPath: string): string | null;
+    /**
+     * 三平台「交给系统默认应用」的命令表（core 的 `systemOpenArgv`）。
+     *
+     * 递进来而不是 import：判据同上面两个 —— 这个文件一行都不 import core，
+     * 于是它能拿假依赖直接单测。**用例里那份假的正是这一格最要紧的用处**：
+     * 真的去 `spawn` 一个 `open` 会在跑用例的那台机器上弹出窗口。
+     */
+    systemOpenArgv(abs: string): {
+        command: string;
+        args: string[];
+    };
 }
 /**
  * 读一次文件的结果。
@@ -5002,7 +5295,58 @@ type FileReadOutcome = {
     bytes?: number;
 };
 /**
- * `EpochRuntime.workspaceFiles` 在服务端眼里的样子 —— **三个方法，一个不多**。
+ * 看一眼一个文件是什么的结果（{@link WorkspaceFilesView.statFile}）。
+ *
+ * **码比 {@link FileReadOutcome} 多两档**，因为这一格答的问题不同：`readFile`
+ * 只需要回答「拿不拿得到正文」，而这一格是「路径可点」那条路的判据 ——
+ * 「这儿本来就没东西」（`missing`）和「这是个目录」（`not-a-file`）在界面上是
+ * 两句不同的话，糊成一个 `unreadable` 的代价是用户永远不知道自己是不是打错了路径。
+ *
+ * ⚠️ **`denied` 照旧一个码盖住两件事**（跑出工作区 / 权限不放行），
+ * 判据逐字同 `FileReadOutcome`：分开说等于承认「这个路径存在，只是你没权限」。
+ */
+type FileStatOutcome = {
+    ok: true;
+    /** 归一化之后的**工作区相对路径**（分隔符统一成 `/`）。调用方拿它去 `readFile` */
+    rel: string;
+    /** 绝对真路径（`realpath` 之后）。给 `createReadStream` 用，见 `statFile` 的 JSDoc */
+    absPath: string;
+    bytes: number;
+    mtimeMs: number;
+    /** 前 8KB 里有没有裸 NUL。判据同 `readFile` 那一处 */
+    kind: 'text' | 'binary';
+} | {
+    ok: false;
+    reason: 'denied' | 'missing' | 'not-a-file' | 'unreadable';
+};
+/**
+ * 这个路径的扩展名在白名单里吗。
+ *
+ * 导出是因为**服务端要拿它算 `WireFileStatOk.openable` 那一格** —— 那一格决定
+ * 界面上画不画那个按钮，而「画一个点了没反应的按钮比不画更糟」（决定 20 ①）。
+ * ⚠️ 它**只答扩展名这一问**：还在不在工作区里、权限放不放行、是不是同一台机器，
+ * 各有各的闸，别拿它一个当结论。
+ */
+declare function isSystemOpenable(path: string): boolean;
+/**
+ * 「用什么命令把这个工作区文件交给系统默认应用」的结果。
+ *
+ * **它不含副作用** —— 真正的 `spawn` 在调用方（服务端）。理由同 core 那一侧
+ * `artifactLaunchArgv` / `openArtifact` 的分法：argv 是能在三个平台上被用例
+ * 逐字钉住的东西，而 `spawn` 不是（真跑一次会在跑用例那台机器上弹出窗口）。
+ */
+type FileOpenPlan = {
+    ok: true;
+    command: string;
+    args: readonly string[];
+    absPath: string;
+} | {
+    ok: false;
+    reason: 'denied' | 'missing' | 'not-a-file' | 'unreadable' | 'extension-not-allowed';
+};
+/**
+ * `EpochRuntime.workspaceFiles` 在服务端眼里的样子 —— **三个方法，一个不多**：
+ * 列候选（`@` 面板）、读正文（`@` 提及 + 站内查看）、看一眼是什么（路径可点）。
  *
  * ⚠️ 每一次调用都收 `root`，**不许在门面上存一个「当前工作区」**：这个门面是
  * **进程级**的（像 `permission`），而工作区**一个会话绑一个**（决定 18）。存根的话，
@@ -5035,11 +5379,47 @@ interface WorkspaceFilesView {
      * 这一格不替调用方算（它不知道这条消息已经用掉多少预算）。
      */
     readFile(path: string, root: string): FileReadOutcome;
+    /**
+     * 「这个路径今天还在不在、是什么、画得出来吗」—— **不读正文**。
+     *
+     * Web UI 那条「路径可点」的路（`GET /api/sessions/:id/file-stat`）一发要问一批
+     * 路径，而它们里面完全可能有一个 100MB 的 mp4：为了确认它存在就把它读进内存，
+     * 是这一格和 {@link readFile} 分成两个方法的**全部理由**。
+     *
+     * 三处和 `readFile` 不一样，逐条都有理由：
+     *
+     * 1. **收得下绝对路径**（先按 `root` 归一化成相对路径再进闸）。`@` 那条路
+     *    刻意拒绝绝对路径（`resolveInWorkspace` 的第一道），因为那是用户手打的；
+     *    而这一格收的是**模型正文里印出来的路径**，那儿绝大多数是绝对路径。
+     *    归一化之后跑不回工作区里的，照样是 `denied`。
+     * 2. **多一道 `realpath` 复查**。`resolveInWorkspace` 只做字符串上的边界判定，
+     *    看不见符号链接 —— 而工作区里完全可以躺着一个指向 `~/.ssh/id_rsa` 的链接
+     *    （判据同 `server/src/assets.ts` 那四道闸的第 3 道）。
+     * 3. **二进制探测只 `read` 前 8KB**（`readFile` 是整个读完再看前 8KB）。
+     *
+     * `absPath` 回给调用方是为了**字节那条路**（`file-bytes` 要 `createReadStream`）：
+     * 闸在这一格，流在服务端 —— 服务端拿到它就等于拿到了一张通行证，
+     * 所以这个字段只在 `ok` 那一档存在。
+     */
+    statFile(path: string, root: string): FileStatOutcome;
+    /**
+     * 「这个文件能不能交给系统默认应用，用什么命令」—— **不 spawn**。
+     *
+     * 闸是 {@link statFile} 那一整套（边界 → `file_read` 权限 → `realpath` 复查 →
+     * 必须是普通文件），**外加一道扩展名白名单**（{@link isSystemOpenable}）。
+     * 也就是说：**模型读不到的文件，用户也点不开** —— 这条路没有给浏览器开小灶。
+     *
+     * ⚠️ 这一格答不了、也不该答的那一问是「浏览器和服务在不在同一台机器上」。
+     * 那是服务端的事实（`--host 0.0.0.0` / SSH），判据在
+     * `server/src/workspace/native-pick.ts`。**调用方必须先过那道闸再来问这一格**，
+     * 否则框会弹在别人屏幕上。
+     */
+    planSystemOpen(path: string, root: string): FileOpenPlan;
 }
 /**
  * 建那个收窄面。
  *
- * @param deps       core 递来的两样（装配那一行从 `@epoch-agent/core` import）。
+ * @param deps       core 递来的那几样（装配那一行从 `@epoch-agent/core` import）。
  * @param permission 权限管理器；**可为 null** —— 那时的语义同 core 那条路的
  *                   判据：权限模块没起来，模型调 `file_read` 照样读得到，
  *                   `@` 单方面收紧只会让两条路给出不一致的答案。
@@ -5459,19 +5839,31 @@ interface MemoryControl {
     }>;
 }
 /**
- * 技能的**导入**口（方案 42 §六，2026-08-18）—— 只有两个动作，都收路径。
+ * 技能那一栏的**写口**（方案 42 §六，2026-08-18；2026-09-01 加上删除）——
+ * 三个动作：预览、导入、删除。前两个收的是路径，第三个收的是技能名。
  *
  * ## 为什么不是把 `SkillSystem` 转出去
  *
  * 同 `MemoryControl` 那条判据，但这一条更硬：`SkillSystem` 上有 `create` /
  * `edit` / `patch` / `delete` / `writeFile` / `removeFile` 六个写方法，还有
- * `view()`（**会 `matchCount++`**，喂着模型看得见哪些技能那本账）和
- * `maintain()`（会**自动删**低效技能）。把它整个交出去，等于让网线那一侧
- * 够得着「删掉用户的技能」和「污染评分」这两件事 —— 而这一轮要的只是「多一份」。
+ * `view()`（**会 `matchCount++`**，喂着模型看得见哪些技能那本账）。把它整个
+ * 交出去，等于让网线那一侧够得着「改写用户的技能」和「污染评分」这两件事。
  *
- * 收窄成这两个方法之后，server 那个包**写不出**别的动作：那不是靠 review 盯住
+ * 收窄成这三个方法之后，server 那个包**写不出**别的动作：那不是靠 review 盯住
  * 的，是编译期的事（同 `McpControl` 只露 `reconnect` 那一条）。
  *
+ * ## ⚠️ 2026-09-01 这一格从两个动作变成三个，判据记在这儿
+ *
+ * 上一版这段话里写着「这一轮要的只是『多一份』」，于是删除被刻意挡在外面。
+ * 那句话今天不成立了：能力页上导得进来、**却没有任何一条路把它拿掉** ——
+ * 用户唯一的出路是自己去 `~/.epoch/skills/` 里 `rm -r`，而那一栏底下那句
+ * 「不想要它，把那个目录挪走」正是在教他这么干。**一个只能进不能出的写口
+ * 不是「更安全」，它只是把不可撤销的那一半推给了用户的终端。**
+ *
+ * 放进来的是 {@link SkillControl.remove} 一个，`create` / `edit` / `patch` /
+ * `writeFile` / `removeFile` / `view` 一个都没跟着进来 —— 那几个是「替用户
+ * 写内容」，和「把用户自己装的那份拿掉」不是一件事。
+ *
  * ## ⚠️ 这两个动作都**不收字节，只收一条服务端本机路径**
  *
  * 这是这一条路上的安全性质本体，不是实现细节。判据全文在 core 的
@@ -5502,7 +5894,43 @@ interface SkillControl {
      *             一个字都不受它影响
      */
     import: (source: string, token: string, lang?: Lang) => Promise<SkillImportResult<SkillImportDone>>;
+    /**
+     * 删掉一个**用户级**技能（2026-09-01）—— 整个目录，递归删，**不可撤销**。
+     *
+     * ⚠️ **它收的是技能名，不是路径**，而那是这个动作上的闸门：宿主说得出
+     * 「删掉叫 alpha 的那个技能」，说不出「删掉 `/etc/…`」。落点由
+     * `SkillSystem` 自己查（它只认自己扫出来的那张表），这一层一个路径都不接。
+     *
+     * ⚠️ **项目 / 插件 / 宿主三档删不掉**，真闸门在 core 的 `requireWritable()`。
+     * 这里额外先查一次 `list()` 只是为了给出 `readonly` 这个**原因码**（好让界面
+     * 说得出下一步），不是第二道闸 —— 别把这里的判断当成安全边界。
+     *
+     * @param lang 回执那句话（含 core 那三句 `readonly_*` 原话）用哪个语言说。
+     *             ⚠️ 同 {@link SkillControl.import}：**它只影响回给这一次请求的话**，
+     *             盘上删掉什么一个字都不受它影响
+     */
+    remove: (name: string, lang?: Lang) => Promise<SkillRemoveResult>;
 }
+/** 删不成的四档。判据（每一档对哪个下一步）在 protocol 的 `WireSkillRemoveFailure` 上 */
+type SkillRemoveFailure = 'missing' | 'not-found' | 'readonly' | 'failed';
+/**
+ * 删一次的结局。
+ *
+ * 成了那一支带 {@link SkillRemoveDone.path} —— **不可撤销的动作，回执得说得出
+ * 销毁的是盘上哪一处**（判据在 protocol 的 `WireSkillRemoveResponse.path` 上）。
+ */
+interface SkillRemoveDone {
+    name: string;
+    /** 刚刚被递归删掉的那个目录（`<技能目录>/<分类>/<名字>`） */
+    path: string;
+}
+type SkillRemoveResult = ({
+    ok: true;
+} & SkillRemoveDone) | {
+    ok: false;
+    reason: SkillRemoveFailure;
+    detail: string;
+};
 /**
  * 一条会话在列表里的样子。
  *
@@ -5739,11 +6167,17 @@ interface PermissionsControl {
      * `config.permission`，一个纯展示值，改它没有任何意义也没有任何危害 ——
      * 而宿主在那一档下本来就不该画出口（web 那侧靠 `editable: false`）。
      *
+     * @param opts.remember 这一发**算不算用户显式挑的**（2026-08-31）。必填，
+     *   判据和那张三行表在 `session-guard.ts` 的 `DefaultLevelSlot` 上。
+     *   ⚠️ 这个包自己就有一个该传 `false` 的调用点（`schedule/executor.ts` 拿
+     *   `def.permission` 起一轮定时任务）—— 那是这个参数存在的直接理由。
      * @returns 换成了没有。**不回「换成了哪一档」** —— 那个问 `level()`，
      *   一次调用只答一个问题（判据同 `server/src/plan-mode.ts` 那句「状态回读，
-     *   不用上一步的返回值拼」）。
+     *   不用上一步的返回值拼」）。「记住了没有」是另一件事，跟在 `ok:true` 那一支上。
      */
-    setLevel: (level: PermissionLevel) => LevelChangeResult;
+    setLevel: (level: PermissionLevel, opts: {
+        remember: boolean;
+    }) => LevelChangeResult;
     /**
      * 工具表 × 判定三轴 —— 「这个工具现在能不能调，是谁在挡它」（方案 43 §七）。
      *
@@ -5817,10 +6251,23 @@ interface EffectiveSetting {
      * 空数组 = 一层都写不了，宿主据此一个写控件都不画。三种成因和整个判据在 core 的
      * `settingWriteTargets()` 上。
      *
-     * ⚠️ 它和 `overridable` **今天恰好同真同假，但不是一件事** —— 前者说的是
-     * 「③④⑤∞ 能不能覆盖这个键」，这一个说的是「宿主能不能替用户写它」。
+     * ⚠️ 它和 `overridable` **不是一件事，而且从 2026-08-31 起真的分叉了**
+     * （在那之前它们恰好同真同假）：前者说的是「**别人的仓库**能不能覆盖这个键」，
+     * 这一个说的是「宿主能不能替用户改他自己的用户级配置」。
+     * 于是 `budget.*` / `compression.*` 这些行 `overridable: false`、`chain: []`、
+     * 却有一个只含 ② 用户级的 `writes`。判据在 core 的 `config/write.ts` 第二节。
      */
     writes: readonly SettingWriteTarget[];
+    /**
+     * 宿主该给这一行画哪种输入控件。**`writes` 非空时必有，空时必无。**
+     *
+     * 真源是 core 的 `settingValueKind()`（从值域 schema 上认）。宿主自己按
+     * 「这一行现在的值是什么类型」去猜是**不行的** —— `budget.*` 四行没有默认值，
+     * 屏幕上是「未设置」、链条上也是空的，猜出来一律是字符串。
+     */
+    valueKind?: SettingValueKind;
+    /** 这一行只有这几个值可选（枚举）。不是枚举时**整个不带这个键** */
+    choices?: readonly string[];
 }
 /** {@link SettingsControl.write} 的入参。`key` / `layer` 都由这一层再验一遍 */
 interface SettingWriteInput {
@@ -6398,16 +6845,23 @@ interface EpochRuntime {
      */
     skillIndexResidency(role: string | null): ReadonlyMap<string, SkillIndexResidency>;
     /**
-     * 从**本机目录**导入技能（方案 42 §六，2026-08-18）。**不可为 null** ——
+     * 往技能目录里写的那一格（方案 42 §六，2026-08-18）：从**本机目录**导入，
+     * 以及（2026-09-01 起）删掉一条用户级技能。**不可为 null** ——
      * 技能系统没起来时它照样在，只是每次都回 `missing`，而那是一句真话
      * （同 `mcp` 那条「一个 server 都没配也照样在」）。
      *
      * ⚠️ 收的是**路径**不是字节，判据在 {@link SkillControl} 上。
+     *
+     * ⚠️ **2026-09-01 从 `skillImport` 改名成 `skillWrite`**（跟着 `roleWrite`
+     * 那一格的叫法）。改名不是整理：那天这一格多了一个 `remove`，而一个叫
+     * `skillImport` 的字段上挂着「递归删目录」是这一层最不该有的假话 ——
+     * 读到它的人会以为自己在看一个只进不出的口子。叫 `skills` 不行，
+     * 那个名字已经被「列出来」那一格占了（{@link skills}）。
      */
-    skillImport: SkillControl;
+    skillWrite: SkillControl;
     /**
      * 建一个用户级身份（2026-08-18）——「新建一个身份」那条路。**不可为 null**：
-     * 底下只有一次文件写，没有起不来的可能（同 `skillImport` 那条）。
+     * 底下只有一次文件写，没有起不来的可能（同 `skillWrite` 那条）。
      *
      * ⚠️ **闸门不在这一格上。** 「一个可能不在本机的浏览器能不能往 system prompt
      * 里写一段任意文字」判成**回环绑定才给写**，落点是 `server/src/role-add.ts`
@@ -6435,7 +6889,7 @@ interface EpochRuntime {
      * [plugin-control.ts](./plugin-control.ts) 的文件头第二节。
      *
      * ⚠️ 这条路**只收 `<市场>/<插件>`，收不了一条路径** —— 那是这一轮的安全性质
-     * 本体（比 {@link skillImport} 那道闸更紧），判据在那个文件头第四节。
+     * 本体（比 {@link skillWrite} 那道闸更紧），判据在那个文件头第四节。
      */
     plugins: PluginControl | null;
     /**
@@ -7132,4 +7586,132 @@ declare function probeMcpServer(name: string, opts?: McpAdminOptions): Promise<{
     needsLogin: boolean;
 }>;
 
-export { type AgentEventBus, type AgentEventSubscriber, AgentRoleError, AgentSession, type AgentSessionOptions, type ApplyHostPresetOptions, ApprovalRelay, type ApprovalRevokeResult, type ApproveFn, type BindWorkspaceFailure, type BindWorkspaceResult, type BuildRuntimeOptions, type BuildToolsInput, type CommandControl, type CommandWiring, type DiscoverOptions, type EffectiveSetting, type EpochRuntime, type ExecutorRuntime, type FileCandidatesResult, type FileReadOutcome, type FireResult, type FireScheduleOptions, type GoalControl, HOST_CAPABILITIES_MODULE, HOST_MARKETPLACE_MODULE, HOST_PRESET_MODULE, type HistoryMessage, type HookStatus, type HostAgentRole, type HostCapabilities, type HostCapabilityWiring, type HostMarketplaces, type HostPreset, type HostPresetProvider, type HostPresetWorkspace, type HostSkillDir, type LevelChangeResult, type McpAddInput, type McpAddOutcome, type McpAdminOptions, type McpApplyAction, type McpApplyChange, type McpApplyOutcome, type McpApplySource, type McpConfigIssue, type McpConfigReadOutcome, type McpConfigSaveOutcome, type McpConfigSnapshot, type McpControl, type McpListResult, type McpLoginCliOptions, type McpReconnectOutcome, type McpServerBatch, type McpServerOverview, type McpWriteOutcome, type ModelCatalogControl, type ModelCatalogOptions, type ModelControl, type ModelSuggestions, type ModelTurnScope, type PermissionsControl, type PlanControl, type PluginActionOutcome, type PluginControl, type PluginInstallOutcome, type PluginListEntry, type PluginPreviewOutcome, type PluginRefusal, type PluginRefuseReason, type PluginSearchHit, type PolicyDirStatus, type PolicyStatus, type ProviderOption, QuestionRelay, type RelayClock, type RoleAddInput, type RoleAddOutcome, type RoleControl, type RoleTurnScope, type RoleWriteControl, type RunOptions, SCHEDULE_EXIT_CODES, type ScheduleCapability, type ScheduleControl, type ScheduleControlOptions, type ScheduleSaveResult, type SerializableAgentEvent, type SerializableApprovalRequest, type SerializableQuestionRequest, type SerializedEvent, type ServiceOptions, type Services, type SessionControl, type SessionDeletion, type SessionFileChange, type SessionHit, SessionStore, type SessionSummary, type SessionWorkspace, SessionWorkspaces, type SessionWorkspacesOptions, type SettingWriteDone, type SettingWriteInput, type SettingWriteRefused, type SettingWriteReport, type SettingsControl, type StoredMessage, type TurnDetail, type TurnStep, type UserActionResult, type UserActions, type UtilityControl, type UtilityGenerateInput, type UtilityGenerateResult, type WireWorkspaceInput, type WorkspaceBindingState, type WorkspaceControl, type WorkspaceFilesDeps, type WorkspaceFilesView, applyHostPreset, applyMcpConfig, buildModelCatalogControl, buildRuntime, buildServices, buildWorkspaceFilesControl, collectFileChanges, createScheduleControl, createUserActions, ensureSecretsReady, exitCodeFor, fireSchedule, listMcpServers, mcpConfigRevision, mcpLogin, mcpLogout, probeMcpServer, providerLabel, readMcpConfigFile, registerAskQuestion, registerLocalTools, registerMcpTools, serializeStream, splitDirList, toSerializable, utilityBudgetKey, wireCommands, wireHostCapabilities, wirePluginMcpServers, wireWorkspace, withModelScope, withRoleScope, withToolScope, writeMcpConfigFile, writeMcpServer };
+/**
+ * `mcp_list` / `mcp_add` / `mcp_update` / `mcp_remove` —— 模型**管 MCP 自己**
+ * 的那四条路（2026-09-02）。
+ *
+ * ## 在此之前这一格是空的，而不是「没做完」
+ *
+ * MCP 的管理面一直只有人侧那三条：CLI（`epoch mcp`）、HTTP（`POST /api/mcp`、
+ * `GET`/`PUT /api/mcp/config`、`POST /api/mcp/config/apply`）、Web 能力页。
+ * [docs/TOOLS.md](../../../docs/TOOLS.md) 那张总表里 MCP 那一格写的是「MCP
+ * server **暴露出来的**工具」—— 一个管 MCP 自己的工具都没有。
+ *
+ * 模型想加一台的唯一出路是拿 `terminal` 去写 `~/.epoch/mcp.json`，而那条路有
+ * 两处会骗人：写完不生效（落盘和生效是分开的两步），以及它绕过了名字校验和
+ * 撞名检查（判据在 `isWritableName` 和 `addServer` 上）。
+ *
+ * ## ⚠️ 一、为什么这四个归 `command` 而不是 `file_write`
+ *
+ * **写一台 stdio server 进 `mcp.json` 就是配一条以后会被 `spawn` 的命令行。**
+ * 归 `file_write` 的表现很具体：`PermissionManager.ruleMatches` 是按**类别**
+ * 授权的（规则到不了工具名这一级，判据在 `operation-type.ts` 的
+ * `COMMAND_TOOLS` 上），于是一条 `allow: mcp_add` 顺带放行的是任意进程启动。
+ *
+ * ⚠️ 而且这一族比 `terminal` 还多一条性质：**它的引信是延迟的**。写下去的那台
+ * 在下一次 `epoch` 启动时（**任何**宿主，CLI / TUI / Web）被连上并起进程，
+ * 而那时屏幕上不会有任何东西指回这一次工具调用。
+ *
+ * `mcp_list` 是这四个里唯一的例外，归 `file_read`：它读的是**进程内**那张状态
+ * 表，一个字节都不写。归 `file_read` 还有第二个作用 —— `plan` 级别下也列得出
+ * 来（同会话检索那四个的判据：调研阶段恰恰最该先看清手上有什么）。
+ *
+ * ### ⚠️ 写那三个**不进** `NON_SHELL_COMMAND_TOOLS`，那是判断不是漏登记
+ *
+ * 那张表（`core/src/permission/operation-type.ts`）摘掉的是 `checkObfuscation()`
+ * ——一层**只对真 shell 命令成立**的语法启发式。按那个文件上写的判据问一句
+ * 「这个工具的 `detail` 会被交给某个 shell 吗」，这三个的答案是**不会**
+ * （MCP stdio 走的是 `spawn`，不过 shell），所以它们**够格**进那张表。
+ *
+ * 这一轮仍然不进，理由是代价不对称：不进的坏处是一个带 `(` 的 URL 在 Windows 上
+ * 会多弹一次确认框、且理由那句话说得不准（`run_code` / `delegate_task` 当年就是
+ * 因为这个才进表的）；而进表的坏处是对一段**即将被 spawn 的命令行**少跑一层
+ * 检查。前者是一次多余的确认，后者是一层真的没了 —— 在没有实测到误报之前，
+ * 往严的那边偏。⚠️ **真碰到误报再进表，别照着「够格」就登记。**
+ *
+ * ## ⚠️ 二、`mcp.json` 的**原文一个字节都不交出去**
+ *
+ * 这一条是这几个工具的形状本体，不是实现细节。`McpControl` 上现成就有
+ * `readConfig()` / `writeConfig()`（浏览器里那个文本编辑器走的就是它们），
+ * 拿它们包两个工具是最省事的做法，**而这里刻意不那么做**：
+ *
+ * 那份文件里装着用户**每一台** server 的 `env` 密钥（判据在
+ * `writeMcpConfigFile` 那句「新建的那一档给 0600，因为这个文件天生装着 token」）。
+ * 一个「读配置」工具等于让模型每次改一台之前先把全部密钥读进上下文 —— 而上下文
+ * 会进日志、进会话库、进下一轮请求体。
+ *
+ * 所以这一族收的全是**结构化输入**（名字 + 那几格），改哪一台就只碰那一台；
+ * 就地替换 / 删除那两条路因此才必须存在（判据在
+ * [mcp-config-edit.ts](./mcp-config-edit.ts) 文件头第一句）。
+ *
+ * ⚠️ **`mcp_list` 也不回 `env`，也不回 `command` / `url`。** 它回的是
+ * `McpServerStatus` 那几格（名字 / 来源 / 连上没 / 几个工具 / 错在哪）——
+ * 那是「下一步该做什么」需要的全部，而 `command` 那一格是密钥最爱藏的地方
+ * 之一（`npx -y foo --token=…`）。
+ *
+ * ## 三、这四个工具住在 runtime 而不是 core
+ *
+ * 它们要的是 `McpControl`，而那是装配层的东西（`registerMcpTools` 的产物）。
+ * core 那边的 `tools/builtin/` 收的是「core 自身服务的薄封装」（判据在那个目录
+ * 的 `index.ts` 文件头），把 `McpControl` 提成 core 的公开 API 只为了让工具住
+ * 进去，是把插件契约撑宽来换一个目录位置。
+ *
+ * ⚠️ 根 `__tests__/tool-registration.test.ts` 扫的是**每个包的 `src`**，
+ * 所以住在这儿照样被那道门禁盯着（`operation` + `operation-type.ts` 的白名单
+ * + `docs/TOOLS.md` 三处同构）。
+ *
+ * ## 四、错误话术为什么是英文
+ *
+ * 判据逐字同 [skill-view.ts](../../core/src/tools/builtin/skill-view.ts) 第七节。
+ * ⚠️ 但**下一层给的 `detail` 原样转发**（`mcp_write.*` 那几句走 `t()`、
+ * `EACCES` 那半截是 Node 的原文）—— 判据同 `McpReconnectOutcome.detail` 那条
+ * 「原样转发底层那句话，这一层不另写一句」。
+ */
+
+/**
+ * 四个工具名。**这是同构位置的真源** —— 另外两处认它们：
+ * `core/src/permission/operation-type.ts`（`mcp_list` 进 `PROCESS_TABLE_TOOLS`，
+ * 另外三个进 `COMMAND_TOOLS`）、`docs/TOOLS.md` 顶上那张表。
+ *
+ * ⚠️ **下面 `name:` 那几格写的是字面量，不是这些常量，别「顺手」统一** ——
+ * 判据全文在 core 的 `SKILL_VIEW_TOOL` 的 JSDoc 上。
+ */
+declare const MCP_LIST_TOOL = "mcp_list";
+declare const MCP_ADD_TOOL = "mcp_add";
+declare const MCP_UPDATE_TOOL = "mcp_update";
+declare const MCP_REMOVE_TOOL = "mcp_remove";
+/**
+ * 这四个工具要装配层的哪两样。
+ *
+ * ⚠️ **`readConfig` / `writeConfig` 不在这里，那是刻意的** —— 完整判据在文件头
+ * 第二节。`McpControl` 上有那两个方法，把类型放宽成整个 `McpControl` 之前先把
+ * 那一节读完。
+ */
+interface McpToolDeps {
+    control: Pick<McpControl, 'add' | 'update' | 'remove'>;
+    /**
+     * 进程里此刻那张状态表。**函数而不是快照** —— 判据同 `McpWiring.status`：
+     * MCP 会掉线重连，而这个工具存在的唯一理由就是回答「**现在**连上没有」。
+     *
+     * ⚠️ 收的是 `McpServerStatus` 而**不是** `mcp-admin.ts` 的 `McpServerOverview`
+     * —— 后者上面挂着整份 `McpServerConfig`（含 `env` 里的令牌），而这一族的形状
+     * 本体就是「原文一个字节都不交出去」（文件头第二节）。
+     */
+    servers: () => readonly McpServerStatus[];
+}
+/**
+ * 建那四个 MCP 管理工具。
+ *
+ * ⚠️ **注册时机比 `skill_*` 那四个晚一格**：它们要 `McpControl`，而那是
+ * `registerMcpTools()` 的产物，跑在 `registerLocalTools()` **之后**。所以接线
+ * 点在 [build.ts](./build.ts) 里那一行 `registerMcpTools` 的后面，不在
+ * `registerLocalTools` 里 —— 判据同 `wireToolRefresh` 那条「订晚一点」。
+ *
+ * **控制面在就全部注册，不管当下配了几台。** 一台都没配的进程正是 `mcp_add`
+ * 最要紧的现场（判据在 `registerMcpTools` 里 `live()` 上那段 ⚠️：那一支照样
+ * 交出活的控制面）。按「启动那一刻有没有 server」决定注册与否，等于让这条路
+ * 在唯一需要它的那一档下不存在。
+ */
+declare function createMcpTools(deps: McpToolDeps): EpochTool[];
+
+export { type AgentEventBus, type AgentEventSubscriber, AgentRoleError, AgentSession, type AgentSessionOptions, type ApplyHostPresetOptions, ApprovalRelay, type ApprovalRevokeResult, type ApproveFn, type BindWorkspaceFailure, type BindWorkspaceResult, type BuildRuntimeOptions, type BuildToolsInput, type CommandControl, type CommandWiring, type DiscoverOptions, type EffectiveSetting, type EpochRuntime, type ExecutorRuntime, type FileCandidatesResult, type FileOpenPlan, type FileReadOutcome, type FileStatOutcome, type FireResult, type FireScheduleOptions, type GoalControl, HOST_CAPABILITIES_MODULE, HOST_MARKETPLACE_MODULE, HOST_PRESET_MODULE, type HistoryMessage, type HookStatus, type HostAgentRole, type HostCapabilities, type HostCapabilityWiring, type HostMarketplaces, type HostPreset, type HostPresetProvider, type HostPresetWorkspace, type HostSkillDir, type LevelChangeResult, MCP_ADD_TOOL, MCP_LIST_TOOL, MCP_REMOVE_TOOL, MCP_UPDATE_TOOL, type McpAddInput, type McpAddOutcome, type McpAdminOptions, type McpApplyAction, type McpApplyChange, type McpApplyOutcome, type McpApplySource, type McpConfigIssue, type McpConfigReadOutcome, type McpConfigSaveOutcome, type McpConfigSnapshot, type McpControl, type McpEditFailure, type McpEditOutcome, type McpListResult, type McpLoginCliOptions, type McpReconnectOutcome, type McpRemoveOutcome, type McpServerBatch, type McpServerOverview, type McpToolDeps, type McpUpdateOutcome, type McpWriteOutcome, type ModelCatalogControl, type ModelCatalogOptions, type ModelControl, type ModelSuggestions, type ModelTurnScope, type PermissionsControl, type PlanControl, type PluginActionOutcome, type PluginControl, type PluginInstallOutcome, type PluginListEntry, type PluginPreviewOutcome, type PluginRefusal, type PluginRefuseReason, type PluginSearchHit, type PolicyDirStatus, type PolicyStatus, type ProviderKeyWritten, type ProviderOption, QuestionRelay, type RelayClock, type RoleAddInput, type RoleAddOutcome, type RoleControl, type RoleTurnScope, type RoleWriteControl, type RunOptions, SCHEDULE_EXIT_CODES, type ScheduleCapability, type ScheduleControl, type ScheduleControlOptions, type ScheduleSaveResult, type SerializableAgentEvent, type SerializableApprovalRequest, type SerializableQuestionRequest, type SerializedEvent, type ServiceOptions, type Services, type SessionControl, type SessionDeletion, type SessionFileChange, type SessionHit, SessionStore, type SessionSummary, type SessionWorkspace, SessionWorkspaces, type SessionWorkspacesOptions, type SettingWriteDone, type SettingWriteInput, type SettingWriteRefused, type SettingWriteReport, type SettingsControl, type StoredMessage, type TurnDetail, type TurnStep, type UserActionResult, type UserActions, type UtilityControl, type UtilityGenerateInput, type UtilityGenerateResult, type WireWorkspaceInput, type WorkspaceBindingState, type WorkspaceControl, type WorkspaceFilesDeps, type WorkspaceFilesView, applyHostPreset, applyMcpConfig, buildModelCatalogControl, buildRuntime, buildServices, buildWorkspaceFilesControl, collectFileChanges, createMcpTools, createScheduleControl, createUserActions, ensureSecretsReady, exitCodeFor, fireSchedule, isSystemOpenable, listMcpServers, mcpConfigRevision, mcpLogin, mcpLogout, probeMcpServer, providerLabel, readMcpConfigFile, registerAskQuestion, registerLocalTools, registerMcpTools, removeMcpServer, removeServerText, replaceServerText, serializeStream, splitDirList, toSerializable, updateMcpServer, utilityBudgetKey, wireCommands, wireHostCapabilities, wirePluginMcpServers, wireWorkspace, withModelScope, withRoleScope, withToolScope, writeMcpConfigFile, writeMcpServer };