@epoch-agent/runtime

组装层（composition root）。把 core 的服务 + 五个 plugin 装配成一个 可跑的 agent。嵌入方要装的就是这个包，不是 core。

• ✅ 做：buildRuntime() 装配、AgentSession（审批桥 / 历史累积 / 持久化）、 会话回放、MCP 运维门面、插件的宿主控制面（已装列表 / 本地安装 / 落包 / 更新 / 卸）、 telemetry 接线、进程级事件观测口（EpochRuntime.events：所有会话产出的每一帧 AgentEvent，判据在 events.ts 文件头）、 子任务那一轮的按步落盘（delegate-recorder.ts： delegate_task 派出去的活从开跑就逐步写进会话库 —— 跑到一半时 GET /messages 已经读得到已经跑过的那些步，不必等它收工）
• ❌ 不做：领域逻辑（在 core）、命令解析（在 cli）、 渲染（在 tui / web）、插件的热加载（装完要重建 runtime， 判据在 plugin-control.ts 文件头第二节）、 事件的缓冲 / 补帧 / 跨进程（观测口只在本进程内、不排队不发号； wire 那一层在 server 的 hub）
• 依赖：protocol + infra + core + plugin-file / plugin-terminal / plugin-web / plugin-mcp / plugin-lsp

最小用法——宿主不用关心阻塞审批、历史拼接、落盘：

import { buildRuntime } from '@epoch-agent/runtime';

const runtime = await buildRuntime({ workDir: process.cwd() });
for await (const event of runtime.session.run('把 README 里过时的命令改掉')) {
  // event 是 protocol 的 AgentEvent
}

完整接法（含 Electron 跨进程审批）见 docs/EMBEDDING.md。

导出

文件

设置分层在这儿落地

loadConfig() 只解析到用户级（~/.epoch/config.yaml）。项目级 <项目根>/.epoch/settings.json / settings.local.json 要先判完工作区信任才敢读， 而信任判定就发生在 buildServices() 里 —— 所以合并点只能在这儿， 夹在 buildTrust() 之后、new ProviderRouter(config) 之前（router 一构造就把 config.model 定死了）。分层的规则、优先级和信任闸门的不对称写在 docs/SETTINGS.md。

对宿主来说只有一句话要记：

装完之后用 services.config，不要再用你传进去的那份。 model / maxTurns / permissions 都可能已经被项目级或 --settings 覆盖过了。buildRuntime() 已经 这么做了，rt.config 就是合并后那份。

合并把来源拍平了，而「这个值是谁定的」正是用户查配置问题时的第一个问题。所以 rt.settings 把它反查回来：每一项带上它赢在哪一层，permissions / model / maxTurns 三个能被项目级覆盖的键另带一条六层链（低 → 高，标出哪一层赢了、 被压住的层各自是什么值）。① 内置默认和 ② 用户级那一刀由 getConfigOrigins() 切 —— 分不出的话，一个用户从没配过的键会被标成「② 用户级」，而那是个假答案。

写那一半 2026-08-15 补上了（rt.settings.write()）：一次写一个键、只写 ② 用户级和 ④ 项目本地、回执带 apply: 'restart'。三件保存语义的判据全文在 core 的 config/write.ts 文件头。

⚠️ rows() 和 write() 都收一个可选的 sessionId，而那不是一个可选的 精细化。多会话之后 ③④ 跟着工作区走，而工作区一个会话绑一个（决定 18）—— 写目标文件（.epoch/settings.local.json 在哪个仓库）和信任判定（被拒绝时 ④ 里 的标量整份作废）必须来自同一个工作区。只改其中一个的表现是「拿 A 工作区的 信任判定去决定往 B 工作区写」，而那在任何一屏上都看不出来。所以两样由同一个 函数（makeSettingsScope）一次取齐 —— 不给 sessionId 就是引导会话那一份， 单会话宿主的行为逐字不变。

停着的会话（这个进程手里没有绑定的那种）2026-10-15 起也算得出：宿主把会话库里 记着的工作区决定作为第二个参数递进来（rows(id, persisted) / write({ …, persisted })），runtime 按 bind() 那套规范化（项目根 + 信任判定） 算 ③④，不建绑定。说不出按哪个目录算的（没记过决定 / 记着的目录没了） covers(id, persisted) 答 false，这时 rows() / write() 抛， 不再落回引导会话那一份 —— 落回去就是「铅笔写进另一个项目」。宿主先问 covers()。

第 ①.5 层（插件）也在这儿落地：buildServices() 一进门就 loadPlugins()， 把已装插件的命令目录 / 角色 / 技能目录 / hooks.json / settings.json / mcp.json 收进 services.plugins，再分别喂给命令表、角色注册表、SkillSystem、hook 来源和 resolveSettings。⚠️ mcpPaths 那一样不在 services.ts 里接 —— 读那份文件要用 plugin-mcp 的解析器，所以它和 MCP 装配的其余部分一起留在 tools.ts / plugin-mcp-servers.ts 那一侧（build.ts 里 registerMcpTools(...) 那一行）。插件那一层只有 permissions.deny 会被采纳， 不过工作区信任闸门（它不来自仓库）—— 见 docs/PLUGINS.md。

buildRuntime({ settingsPath }) 对应第 ⑤ 层；不给时回退到 EPOCH_SETTINGS 环境变量 —— CLI 的 --settings <file> 走的正是这条路，因为无参进 TUI 时 TUI 是另一个进程，只有环境变量带得过去。这一层不过信任闸门：它是用户在 命令行上显式给的路径，不是仓库里躺着的文件。这份文件不是合法 JSON 时抛 SettingsFileError 拒绝启动（其余层坏了只记一条 issue），理由见 core README。

addDir / agent 是同一个形状：不给时分别回退到 EPOCH_ADD_DIR （按 path.delimiter 分隔，用 splitDirList() 拆）和 EPOCH_AGENT。 加新参数时按「TUI 那条路带不带得过去」判要不要落一个环境变量。

第 ∞ 层（企业托管）也在这儿落地，三处：services.managedPolicy 是读出来的结论 （永远非 null，没有托管文件时是三个开关全 false）；allowManagedHooksOnly 打开时用户级和项目级 hook 都不加载（loadHookSources() 整个跳过，压过项目信任）； disableBypassPermissionsMode 打开且 permission 落在「审批轴 = never」那一档（今天的 auto；老配置写的 bypass 会在解析处映射成它）时抛 ManagedPolicyError 拒绝启动 —— 这一步排在任何资源分配之前，否则每次拒绝都会漏一串 SQLite 连接 （cleanups 要等 buildServices 正常返回才交得出去）。

buildRuntime({ managedSettingsPath }) 只给用例和嵌入宿主。它没有对应的 环境变量或命令行参数，理由见根 README：有的话一句 EPOCH_MANAGED= 就能把 IT 下发的策略整份关掉。

一个进程里开多个会话（方案 30 §6.3）

rt.session 是引导会话；再开一个走 rt.sessionFactory.create({ workspace })。 单会话宿主（CLI / TUI）手里只有前者，那正是它留着的理由。

把一段盘上还在、这个进程手里没有的会话接回来（2026-08-19）

rt.sessionFactory.revive({ sessionId, decision: { state: 'bound', root } });

内部就是 create() 那条路上同一段 assemble()，两段处置也原样复用： 绑不上就整个不建、装不起来就把这一次加的那一笔绑定放下（不留幽灵 id）。 hub.register() 归调用方 —— 这一层不知道 Hub 的存在。

⚠️ 历史不从外面递进来，虽然方案原稿是 revive(sessionId, history, decision)： 模型看的那种历史是 core 的类型而服务端不许 import core，而且 assemble() 已经给 这个会话建了一份 SessionStore —— 从外面再开一个就是第二个真源。所以历史在装配 之后用 AgentSession.reloadHistory() 接上，那也是 /resume 走的同一个方法。

⚠️ 角色接不回来：sessions 表没有角色那一列，所以一段用 explore 建的会话 复活之后跑的是这个进程的 --agent。如实记着，这是一笔债不是一个判断。

⚠️ decision 由调用方从库里读出来给，这一层不猜。 没有决定可循时回 { ok: false, reason: 'no-decision' }，而不是回落到「就绑进程启动目录」—— 那会把一段「明确不使用工作区」的会话悄悄绑进服务进程的 cwd （会话库 v7 那两列的由来，判据全文在 ReviveSessionOutcome 上）。

⚠️ 和 CLI 的 /resume 是两件事，别合并。 /resume 是「把另一段对话接上 这个引擎」，所以 build.ts 那行 workspaces.seed() 让它跑在这个进程的工作区 里；revive() 是「把那段会话本身装起来」，跑在它自己当初选的地盘上。 两处 JSDoc 互指。

这个会话用哪个专家跑（2026-08-15）

rt.sessionFactory.create({ workspace, reuse: false, role: 'explore' });

⚠️ explore 这类名字 2026-11-05 起不再内置（general / explore / review 三条从内核删了）：要这么写，得自己落一份 ~/.epoch/agents/explore.md 或项目级的 .epoch/agents/explore.md，否则 create() 抛 AgentRoleError。

在这之前角色只有两条来路：delegate_task 派出去的子 loop，和 --agent <role> （进程级，所有会话共用一个）。这一条补的是会话级那一档 —— 装配层在 assemble() 里对它走一次角色收窄，和 --agent 完全同一条路。

2026-08-17：那一次收窄换成了一个槽（方案 57 §3.2 的 createRoleScope）。 会话级角色是槽的默认值，行为逐字不变；变的是形状 —— 工具表和身份行 从此读同一个变量，所以「工具按 explore 收窄了、prompt 里写着 build」 这种状态不存在。槽的 enter() 目前没有调用方，逐条专家的接线还没落地。

三件要知道的事：

• 认不出这个名字就是拒绝（{ ok: false, reason: 'unknown-role', detail }）， 不静默降级成不分角色。判据照 --agent 的 AgentRoleError：用户显式点了一个 专家，给他跑一个能力范围不同的 agent 是最坏的结果
• 不给这个字段时回落到 --agent，也就是这个字段出现之前的行为
• reuse: true 复用回来的会话不换角色。 角色同时决定 system prompt 的身份行 和工具表，而 system prompt 是 prompt cache 的前缀 —— 中途换掉等于让同一段历史里 前后两轮的身份声明互相打架。要另一个专家就是另一个会话（reuse: false）

顶层会话那份角色带着 scope: 'session'（protocol 的 AgentRoleScope）， 于是它拿到的身份行是「这一次以「x」的身份工作」而不是子 agent 那句 「由主智能体派来完成一个独立子任务」—— 后者对顶层会话从 --agent 落地那天起 就是一句假话。

作用域怎么分（完整那张表在 session-factory.ts 的文件头，这儿只列结论）：

• 一个进程一份：provider / SQLite / 记忆 / 技能 / hook / ToolRegistry + MCP / BudgetStore / 工作区绑定表
• 一个会话一份：AgentSession + 它的审批桥、AgentLoop（workDir 与 projectContext 跟着绑定的工作区走）、CheckpointManager、SessionStore

⚠️ 「跟着绑定的工作区走」是每轮现读，不是装配那一刻的快照（迟绑， 2026-08-20）。assemble() 递给 AgentLoop 的是 AgentConfig.site —— 一个问绑定表的函数。快照那一版的病是：侧栏「新建会话」开出来的会话 （unbound，方案 55 PR-1）在底栏 picker 里挑完目录之后，界面上那一格换了、 引擎照旧在服务进程的启动目录里干活。判据全文在 session-factory.ts 的 assemble 和 core 的 AgentSiteRef 上。

⚠️ 「一个会话一份」的东西，取数也得按会话取。 LiveSession.checkpoints （2026-08-15 加）就是这条：EpochRuntime.checkpoints 是引导会话那一份， 拿它去答别的会话的表现是列表恒空、回退恒被拒 —— 而这个进程正握着对方的 CheckpointManager。web 上那三条回退端点在这个字段之前逐字就是这么错的 （方案 30 §9.5）。同理 settings.rows(sessionId) 收 id、 workspaces.of(sessionId) 收 id。

⚠️ 模型 / 权限档 / plan 模式三样 2026-08-16 也收窄成了会话级（方案 30 §十四）：

⚠️ rt.utility（一次性补全）刻意不在上面那张表里：它挂的就是引导会话那一份 router，没有「别的会话那一份」 —— 它答的是「这个进程默认用什么」，而不是 「窗口 2 现在在用什么」。于是第二个会话换过模型之后，utility 跟的仍然是引导 会话那个选择。这条代价和 getUtilityInfo()（「没配 utility 就跟着主模型走」在 多会话下确切的意思是「跟着引导会话走」）是同一条，判据在 src/utility.ts 的文件头。要打别的就显式给 model。

引导会话那三份就是进程那三份本体，不是副本 —— 所以 TUI 的 /model / /permission、CLI 的 --model 行为一个字节没变，而「两份要同步」这件事在这个 形状下说不出口。三样各自的落法和判据在 src/session-model.ts / src/session-guard.ts / core/src/permission/shared.ts 的文件头。

⚠️ 分家的只有档位那一个字段：规则表、审批缓存、审计流水、沙箱隔离、 额外根、headless 白名单全进程共用同一份引用（PermissionManager.scoped()）。 它们是关于用户和这台机器的事实，跟着会话走反而会说假话。

⚠️ 一样这一轮仍然没有收窄，是已知限制：--add-dir 的额外根是进程级的。 新绑的工作区没有额外根，但 PermissionManager.getExtraRoots() 仍然报引导会话 那一份。它的理由 2026-08-16 换了一个：档位分家之后它技术上随时能搬到会话 那一格，但「新会话该不该继承 --add-dir 的地盘」是一次产品判断，不是接线问题。

并发跑两轮时预算和用量不用额外处理：BudgetGuard 每轮新建且带 sessionId，BudgetStore 按 sessionId 分格且是同步读-改-写。所以 rt.usageScope 那两个口径在多会话下逐字仍然成立。

导入技能：收路径，不收字节（方案 42 §六）

EpochRuntime.skillWrite 转出去的是三个函数，不是 SkillSystem —— 后者上有六个写方法、一个会 matchCount++ 的 view()、还有一个会自动删 低效技能的 maintain()。交出去等于让网线那一侧够得着「污染那本喂给模型的评分」 和「一口气自动淘汰一批」。收窄之后 @epoch-agent/server 那个包写不出 别的动作 —— 那不是靠 review 盯住的，是编译期的事（同 McpControl 只露 reconnect）。

⚠️ 2026-09-01 这一格从 skillImport 改名成 skillWrite，因为那天它多了 一个 remove：一个叫 skillImport 的字段上挂着「递归删目录」是这一层最不该有的 假话。而多出来的那一个是逐条点名删（remove(name)），和上面说的 maintain() 那种「自动淘汰一批」仍然是两件事 —— 后者照旧不出这个包。

⚠️ 两个动作都只收一条服务端本机路径。 判据全文在 core 的 skill/import.ts 文件头，一句话：用户级技能目录连信任闸门都没有， 往它里面落一份文件 = 让那段文字无条件进往后每一轮的 system prompt； 而 epoch web --host 0.0.0.0 那一档下，浏览器可能不在用户自己那台机器上。

哪天真要做上传，不是在这儿加一个 bytes 参数 —— 那会把上面那条性质 一声不吭地删掉。回去读那个文件头最后一节。

嵌入宿主要注意：这条路的落点永远是 SkillSystem 自己那个用户级目录， 调用方给不了。让宿主传一个目录进来，它就成了「往任意目录写文件」的口子。

改 mcp.json：两条路，主语不同（2026-08-18；2026-09-02 加了两个动作）

这一层有两条写 ~/.epoch/mcp.json 的路，而它们不许互相取代：

mcp-config-write.ts 的文件头逐字判掉了「读进来 → 改 → 整份写回」：我们读进来的 不是原文（parseMcpConfig 吐的是归一化之后的结构），整份写回会把 connect_timeout 改写成 connectTimeout、把用户没写的 streamable 物化成一行、把未知键删掉 —— 那是改写他配置的语义。

那条判据只管第一行。第二行上根本没有 parse → serialize 这一步：字节进、字节出， 所以注释 / 空行 / 键序 / snake_case 键名 / 未知键全都原样活着。⚠️ 别把它读成 「那条判据过期了」，也别拿它去简化第一行。

📮 2026-09-02：第一行从「只插入」变成三个动作

mcp-config-write.ts 的文件头原来有一句总纲：「我们对这个文件只有一次插入的 权利」。这一轮把它推翻了，而理由不是「插入不够用」，是模型手上那条路没有第二 个选项：mcp_update / mcp_remove 那两个工具（docs/TOOLS.md） 要么走就地改写，要么走第二行那条「读原文 → 整份写回」，而后者意味着把整份 mcp.json 交进模型的上下文 —— 里面装着他每一台 server 的 env 密钥。 一条为了保住排版而存在的判据，不该以「顺带把密钥全交出去」为代价来维持。

⚠️ 变的是「几次」，不是「什么」。 替换和删除照旧是定位 + 拼接文本，上面那段 「整份写回会改写他配置的语义」一个字都没过期。删除是这一族里唯一会动到用户已经 写下的字节的动作 —— 被删那台前面或后面那个逗号是他写的，而留着它就是一份坏 JSON。 边界（只动那一个逗号、只动只剩空白的那一行、行尾注释一律留着不猜归属）逐条写在 mcp-config-edit.ts 文件头第一节。

三件这一层管、上面那层管不了的事：

1. 指纹防覆盖。这份文件另一个编辑器一直开着（用户的 vim、还有 writeMcpServer 自己）。读的时候发一个内容哈希，写的时候拿它和此刻盘上那份比，对不上整段 拒绝。⚠️ 是内容哈希不是 mtime：后者在「写回同样的内容」和「同一毫秒两次写」 两档下都会骗人；
2. 换行符跟着盘上那份走。浏览器的 <textarea> 只会吐 \n，而 CRLF 的 mcp.json 在 Windows 上是常态（Windows 是支持平台）—— 不转回去的话，用户在 自己的编辑器 / git diff 里看到的是整个文件都变了；
3. 权限位。已经在的那份沿用它自己的（用户可能刻意收成 0600），新建的那份给 0600 而不是 0644 —— 这个文件天生装着 env 里的明文 token。

applyConfig()：「改完 mcp.json 要重启」那句话的出路

reconnect() 走的是已经建好的那个 client，它手里那份配置是启动时读的 —— 所以那一下治的是「对面重启过 / 网线抖了一下」，不是「我刚改了配置」。 applyConfig() 才是后者：读盘 → 和进程里那几台 diff → 该断的断、该连的连、 没变的一个字节不动 → 按台换工具表（走 ToolSync 那条同一条队）。

• ⚠️ 只动 source === 'user' 那批。 宿主注入的和插件带来的两批在这份文件里 天生缺席，把它们算进「盘上没了 = 该断开」等于用户存一次自己的文件就把宿主 ship 的那几台全断了 —— 而那批他一点办法都没有；
• ⚠️ 「读出来一台都没有、而且带诊断」整段拒绝（最常见的成因是把 servers 写成 了 mcpServers）：照着应用会把用户所有 MCP 全断掉。而「0 台且没有诊断」 （"servers": {}）是照办的 —— 那是一句清楚的「我要清空」；
• 它为此给 plugin-mcp 的 McpRegistry 补了两个方法（disconnect(name) / configOf(name)）：在那之前「让一台 server 在这个进程里消失」做不到， 只有 disconnectAll()。

建 / 删一个身份：这一层不带闸门，那是刻意的（2026-08-18 建、2026-09-16 删）

EpochRuntime.roleWrite 收窄到两个动词 add() / remove()，形状和上面两条 同源：宿主（@epoch-agent/server）于是写不出「改一个身份」。

它做两件只有装配层做得了的事，落盘那一半在 core 的 agent-role/create.ts 和它的兄弟 agent-role/remove.ts：

1. 查的是合并之后那张角色表，不只是那个目录。建那一侧漏了这一道不是「多一个 重名」：两条同名定义会互相收窄（mergeRoles 的同名语义是工具取交集、 prompt / description 整份替换），而屏幕上只画得出一份。删那一侧靠它答 「这一行是哪一层来的」—— core 只看得见一个目录，一个删不掉的项目级 / 插件 身份在它那儿长得像「找不到」，而屏幕上那一行明明在；
2. 写完重载角色表。EpochRuntime.agentRoles 是装配那一刻加载出来的那张表 （普通属性，不是 getter —— 和 skills / mcpServers 那两个不一样）， 不重载的话这个进程要到下次启动才认得这次改动。⚠️ 删那一侧还多靠它一件事： 重载之后再查一次表，才答得出 takenOverBy（删掉的要是一个同名覆盖， 下层那一份会浮上来 —— 那一行不会从能力页上消失）。

⚠️ 落点靠读口解析出来的 name 找，不是拿名字拼路径（removeRoleFile）： frontmatter 里的 name 优先于文件名，所以 my-helper.md 里写 name: reviewer 是合法的。join(dir, name + '.md') 在那种现场要么删不掉一份界面上明明列着的身份， 要么删掉另一个身份，而两种错法都不报错。

⚠️ 那道「回环绑定才给写」的闸门不在这一层，在 @epoch-agent/server。 判据是：lanExposed 说的是「那个 HTTP 服务绑在哪儿」，而直接拿 EpochRuntime 用的嵌入宿主压根没有一个 HTTP 绑定 —— 它自己就是那台机器上的进程，不是网线 另一头。所以宿主调 roleWrite.add() 不吃那道闸，那是对的。 完整判据（以及「照收 / 借工作区信任 / 只写项目级」那三档为什么不选）在 protocol/src/wire-agent-role.ts 的文件头。

⚠️ 反过来说：嵌入宿主自己开一条 HTTP 路把它转出去的时候，那道闸得自己立一遍。 server 那一份长这样：ctx.lanExposed 为真 → 403，而且在读请求体之前。

⚠️ 删那一条吃的是同一道闸，而理由和 POST /api/skills/remove 刻意相反： 技能删除不吃闸，判据是「导入那条也不吃」（只给删加闸 = 那一档下技能变成 「只能加不能删」）；身份这边建那一侧本来就要回环，所以删也要回环才不制造 那个反面。全文在 protocol/src/wire-agent-role.ts 文件头第六节。

⚠️ 落盘失败：不拦对话，但必须有声音（2026-09-20）

有过一次真实报障：「我打开一个新对话框，给他下达指令后，他完成了指令，但整个沟通 记录一下子跳掉了。」重启之后那段会话也不在了。根因是 SessionStore.ensure() 把 写不进去读成了已经存在，接着无条件 known.add() —— 一次偶发的写失败被 放大成这段会话终身不再尝试建那一行；没有父行，messages.session_id 那条外键 让每一条消息都撞约束，整段对话一个字节都不落盘。而屏幕靠 SSE 直播，一切看着正常， 直到一次重拉把空历史盖上去。

改这一层的落盘路径之前，三条规矩：

• ensure() 失败时不许 known.add。 那个集合只进不出、且是第一道短路， 往里加一个建不出来的 id 就是把偶发失败变成永久失败。create 抛了要去 问库（SessionManager.has()），「在了」才算已存在；
• catch 里不许是空的。 16 处写 / 读路径统一走 swallow()（写 error、 读 warn）。规矩本身不变（照旧不拦对话、照旧回 false / null），变的是 一个「对话没了」的工单能在日志里对到一行。有一条扫源码的 AST 门禁守着 第 17 处（__tests__/session-store-silent-catch.test.ts）；
• 返回值不许掉在地上。 beginTurn / appendSteps / appendSteer 都回 boolean，AgentSession 拿到 false 时发一帧 not-persisted 的 notice， 一轮最多一帧（磁盘满时一次多工具调用会踩十几次落盘，逐个报就是刷屏）。 ⚠️ 收尾那两处在 run() 的 finally 里，只记日志不发帧 —— 那一段一个 yield 都不能有（在 finally 里 yield 会吞掉正在传播的异常）。

⚠️ 那 17 句日志文案是中文且不走 i18n —— 收件人是看日志的人，翻了反而难搜。 scripts/i18n-scan.mjs 的文件级白名单里有一条对应的豁免，判据逐字同 infra/src/sqlite.ts。往这个文件里加界面文案时别顺着那条豁免走。

几个容易踩的点

会话历史的自动压缩在这一层，不在引擎里（2026-09-10）。引擎那几道压的是 「一次 run 的局部 messages」，run 一结束就扔了；而下一条用户消息重新送上去的是 AgentSession.history —— 在这一笔之前，那一份只有 /compact 和 resume() 换得掉，于是每条消息都把整段原始历史重付一遍（累计 token 随轮数平方涨）， 最后撞窗口，而撞上之后每条消息都报错。现在 AgentSession 在跑之前按软线判一次、 压完写回历史。三点：

• 判据吃的是上一发实测提示词（onTurnUsage 免费给的，含缓存命中那部分）， 只有刚起进程 / 刚 resume 那一次回落到把历史分词一遍；
• 开关和阈值走 compressionOptions(config)，和引擎那几道同一个入口 —— 用户关掉压缩就是三道全关；
• 嵌入宿主不给 autoCompact 那一格 = 一次都不压（行为和改造前逐字相同）。 自己 new AgentSession() 的宿主要这道闸就得自己传窗口，判据在 AgentSessionOptions.autoCompact 上。

定时任务在嵌入形态下必须由宿主说「怎么唤起我」。 buildRuntime({ scheduleRunner }) 不给时 runtime.schedules.create({ register: true }) 会拒绝注册并回一个 no-host-runner，而不是拿 process.execPath + argv[1] 去拼 —— 在 Electron 里 那两个值是「Electron 的 exe + 宿主的 main.js」，注册进去等于到点了弹主窗口。 任务照样存得下、fire() 照样跑得了（宿主自己掐点），只是界面上必须说清 「关掉应用就不跑」。全文在 schedule/control.ts 的文件头和 EMBEDDING.md §9.5。

dispose() 返回 Promise，能 await 就 await。 它关 SQLite、销毁沙箱、 杀 MCP 子进程、停定时器，还要收掉 terminal({ background: true }) 起的后台进程和 PTY 会话 —— 最后这项要先查整棵进程树（pgrep / taskkill）再 SIGTERM → SIGKILL， 只能异步。同步那批全部跑在第一个 await 之前，所以不 await 的老代码行为不变， 只是后台进程变成尽力而为。幂等，重复调用是空操作。

后台任务表按会话分，所以那两个口子的第一个参数是会话 id（2026-08-15）。 传的必须是活的那个 —— session.sessionId，不是装配时拍下来的 rt.sessionId： /resume 会把前者换掉，拿后者去问，resume 之后数的是一个已经不存在的会话。 单会话宿主（CLI / TUI）写成 rt.session?.sessionId ?? rt.sessionId 就对了。 收窄的完整判据在 plugin-terminal 的 src/background.ts 文件头。

⚠️ 这条建议在 2026-08-17 之前是反的。 那时 rt.sessions.resume() 里 「把任务搬到新 id 名下」那一步恒为空操作，于是 resume 之后拿活的 id 去问 反而一条都数不到。同一处也让 rt.sessionFactory.get(刚 resume 过去的 id) 恒为 null。两样都修了，判据在 src/build.ts 的 buildSessionControl。

装配是显式手写的，不用 DI 容器。 十几个模块的依赖关系读一遍就完，引入容器只会把 「谁依赖谁」藏进配置里。

每个模块独立 try/catch（safeInit）。 少一个能力也比整个 agent 起不来好，失败原因 进 diagnostics 交宿主呈现——epoch doctor 打的就是这些。

审批那个 race 不是可以省的。 审批请求发生在两个事件之间（AgentLoop 在工具执行前 阻塞等答复）。只在收到事件时才排空审批队列的话，双方互等——死锁。所以必须显式 race 「下一个事件」和「有新审批请求」。

要展示「信任了没」就读 rt.trusted，别自己 new TrustManager().check()。 两者只在 trust.enabled: false 时分叉，而那一档恰好是最容易说反话的：闸门整个不启用， 装配走的是信任那一支（项目指令、角色、自定义命令全加载了），而信任表里可能一条记录都没有 ——宿主自己查会得出「没有决定过」，跟运行时的真实行为不是一回事。

默认值是信任，所以宿主通常不需要碰 rt.trust。 它现在是「拒绝名单」的读写口： 要给用户一个「不要加载这个目录」的开关，就调 record(dir, 'untrusted', scope)； 撤销拒绝则是 record(dir, 'trusted', scope)（或 revoke）。三条边界：

• record() 不带闸门，它就是那个决定本身 —— 宿主必须先真的问过用户。 判据是宿主主进程和 CLI 同一档，都是可信代码；浏览器不是（那条路刻意关着， 也不会开：让一张网页决定「哪个目录的文件能当指令读」是这个仓库最贵的开关）
• 它不是权限开关。 信任管「文件算不算指令」，权限管「操作要不要问用户」—— 两套机制刻意正交，被拒绝的目录里 agent 照样能跑 bash
• 它不是工作区绑定的前置。 绑一个被拒绝的目录是合法的，只是指令文件不加载

trust 为 null 只有一种情况：信任记录整份读不出来（那时按默认信任放行并留一条 warn）。 trust.enabled: false 不是那种情况 —— 闸门关了不等于没有记录这回事。

要预置模型 / MCP / 已知工作区，用 hostPreset，别自己写我们的文件 （方案 54 §六）。以前宿主只能逐个手写 models.json / config.yaml / mcp.json / workspaces.json，而那几份的格式一份都没对外承诺过。四条语义（在 host-preset.ts 的文件头，改之前先读那一段）：

• 不是新的一层 —— 等于「替你写第 ① 层那份文件」，⑤ / ∞ 照旧压得过它
• 缺失才写，不覆盖，按键判。所以每次启动传同一份是对的用法
• apiKey 给了 secretStore 就不落盘，进你注入的那个存储（否则落 <homeDir>/.env）
• 写了什么全在诊断里（module === 'HostPreset'）。「配了但没生效」是这类东西 唯一的失败模式，而它在此之前完全静默

⚠️ 2.0.0 换过一次形状：provider: { type, baseUrl, apiKey } + model: '<provider>/<model>' 是老写法，删了。今天是 models: [{ id, provider, model, baseUrl?, apiKey?, … }] + model: '@<id>'（外加可选的 label，当设置页里那一组的组名）。文件里已有的老值算「缺失」， 所以照旧每次启动传同一份能把它改过来。

⚠️ 2026-10-15 又收窄一次（还没发版）：宿主条目。

• preset.models 物化出来的每一条都打 host: true —— 只读（界面上没有编辑 / 删除， 走 API 也回 entry-host-readonly），而且每次启动刷新成宿主给的形状：只读条目没有 「抹掉用户改动」这回事。同 id 的老装机条目内容相同就收编打标（升级那批，只此一次）， 用户改过的不动（语义 2）；
• 端点在条目上（hostPreset.models[].baseUrl）：没有「进程级统一端点」这回事， EPOCH_BASE_URL 和它落成的 config.gateway 同一天整个删了（设着只报一条诊断）。 用户自己加的条目走自己的端点、自己的 key。宿主那一侧的义务只有一条： fetch 桥只按自己那个网关 origin 注入凭据（判据在 __tests__/entry-route-pinned.test.ts，断言的是出站 URL）。

它不预置信任 —— 那是一个决定不是一份配置，走 rt.trust（上一段）。

要把你自己 ship 的专家 / 技能 / MCP server / 进程内工具塞进能力清单，用 hostCapabilities，别去写用户的 ~/.epoch/agents/ 或 mcp.json （方案 44 §2.1、方案 59 §四）。它和上面那个 hostPreset 不是一件事： 那一个装配前写用户的文件（缺失才写、用户改得动），这一个是这一程的运行期事实， 一个字节都不落盘，用户在自己的目录里找不到它，也没有地方能删掉它。

buildRuntime({
  hostCapabilities: {
    namespace: 'acme',
    roles: [{ name: 'triage', description: '分拣工单，只读', tools: ['file_read'] }],
    skillDirs: [join(app.getAppPath(), 'resources', 'skills')], // 必须绝对路径
    mcpServers: [{ name: 'deploy', transport: 'http', url: 'http://127.0.0.1:3456/mcp' }],
    tools: [listJobsTool], // `EpochTool` 本体，name: 'list_jobs'
  },
});
// → 专家 `acme:triage`、技能 `acme:<分类>/<名字>`、server `acme__deploy`
//   （工具是 `mcp__acme__deploy__<工具>`）、进程内工具 `acme__list_jobs`，
//   四样都标着「宿主」来源

六条性质（全文在 host-capabilities.ts 的文件头）：

• 命名空间是强制的：前缀由装配层按 namespace 拼，宿主在 name 里自己写前缀 会被判成非法名字。不这么做的话，一个叫 general 的注入会顶掉内置那条， 而 delegate_task 不带 role 时取的就是它
• ⚠️ 分隔符分两种：角色 / 技能是 <namespace>:，MCP server 和工具是 <namespace>__ —— 后两样都会原样进工具名，而 provider 硬拒带 : 的工具名 （实测）。判据在 plugin-mcp 的 McpServerStatus.source 上。 ⚠️ 字符集也分两种：工具名允许 _（list_jobs 是对的），server 名不允许 —— 前者是名字的末段，后者夹在两个 __ 中间
• source 宿主写不出来：HostAgentRole 上没有那个字段，McpServerConfig 和 EpochTool 上也没有，装配层填死 'host'
• 坏的那一条只跳过它自己，各留一条诊断（module === 'HostCapabilities'）。 唯一整份作废的是 namespace 本身坏掉 —— 那时没有前缀
• 注入是装配时一次性的，但注入进去的东西生命周期照旧：技能照样被 SkillLearner 影响（只是那个目录只读），server 照样掉线重连、照样能在能力页上按「重连」。 ⚠️ 工具那一格上「一次性」最硬：注册表没有「换掉某一个工具」的路
• ⚠️ 注入的工具照样过审批闸门，而这不是我们答应的一件事：闸门在 ToolExecutor 上，它不看来源。免不免确认由 annotations / operation 决定， 和内置 / 插件 / MCP 工具走同一套。连带一件白拿的：execute(args, ctx) 的 ctx.sessionId 是真正在跑的那个会话（绕一圈 MCP 的话这个值到不了宿主手上）

注入的 server 装配时就真连，并和用户 mcp.json 那批共用同一份 MCP_CONNECT_BUDGET_MS（不是两份相加）。真连是因为第一轮发给 provider 的那份 工具 schema 数组是按那一刻的注册表拼的（2026-08-26 之前这句话的凭据是 ## 可用工具 那段散文清单，那一段删了，结论没变）；共用一份是因为那个预算存在的 全部理由就是「启动不能被一台连不上的 server 拖住」。和用户那批重名时用户赢。

要 artifact 的路径就读 rt.artifactsRoot。 它和 rt.homeDir 是这次装配的事实， 不是配置里的一个字段。2026-08-15 之前 artifact 的写路径不认 homeDir （读那侧一直认），后果是宿主传了 homeDir 就产物 404 而全链路 200 —— 在宿主侧 join(homeDir, 'artifacts') 拼一遍，就是给同一个目录第二个说法。

rt.sessions.delete() 连带删产物、也连带收掉这个会话的后台作业 （产物 2026-08-20，方案 47 PR-4；作业 2026-10-29）。在这之前它只删检查点， 而 core 的 SessionManager.delete() 上写着「产物由装配层跟着一起清」 —— 一句从头到尾没兑现过的话。宿主这边要知道三件：

• SessionDeletion 多了一格 artifactsRemoved，和 checkpointsRemoved 一样 与 deleted 分开报：附属物删不掉不会让整次删除变成失败（对话已经没了， 回一个错只会让用户再点一次然后收到 404）。别把三格 and 起来当成功判据 —— 该说的是「删了，但那个目录还在」，而用户下一步要知道是哪个目录
• 那一格还没进 WireDeleteSessionResponse（epoch web 那条 REST 路只透传， 所以它会随 JSON 出门，但契约上没有它）。走 REST 的宿主要读它，得先加那一格
• 这个会话名下的作业会被停掉（stopSessionJobs()，逐个调产出方给的 stop 再忘掉那一格）。所以 delete() 可能比你想的慢：那几个 stop 要等进程树 真收完才 resolve。想先给界面一个回执、后台再收，就在宿主那侧做 —— 别在这里 加超时：超时之后调用方照样得往下走，那个进程就变成一个谁都够不着的孤儿

rt.sessions.import()：把别处的一整段会话原样搬进本机库（2026-09-20， 给「一个账号多台机器」那类同步 / 迁移用）。

它不是「带历史的新建」，三条硬约束：

• 不跑智能体、不切当前会话、不发任何事件 —— 纯写库，屏幕上不该有反应。 宿主要让用户看见它，得自己再 list() 一次
• id 和每条消息的 timestamp 由调用方给，库不拿挂钟顶替。会话的最后活动 跟着来源走（insertMessage 那句 MAX()），一段两年前的对话导进来还是两年前
• 撞 id 就拒（{ ok: false, reason: 'exists' }），不悄悄合并也不覆盖。 两边都是用户的数据，这一层没有判断谁该赢的依据 —— 那个判断是调用方的事

消息 id 一定会重发（messages.id 是全库一条序列，跨机必撞），回执里的 idMap 把来源的号接到本机的号上，调用方拿它接自己的水位线。整段会话 + 全部消息 在一个事务里落地，中途抛了一行不留。

⚠️ 附件 / artifact 的字节不跟着走。parts 里的图片是绝对路径，导进来之后在 这台机器上多半不存在，读回来会退化成「图片已不可用」占位。搬字节是另一件事。 另外两样有意没搬：estimatedCostUsd（priced_call_count 分得出「0 块钱」和 「不知道」，抄一个数过来会把后者变成前者）和压缩状态。

配套的两样，都是给增量同步用的：

• rt.sessions.list(limit, { archived, updatedSince })。archived 是三态： 不给 = 只列没归档的，true = 只列归档的，'any' = 两边都列。 ⚠️ 'any' 之前「两边都要」这句话没有任何写法能表达（false 和不给是同一个 意思），只能问两次再自己归并 —— 而两次查询之间 limit 各算各的。 updatedSince 只列最后活动严格晚于它的（ms）：严格 > 会漏掉同毫秒的行， 所以水位线要往回退一点再传
• rt.sessions.setPinned(id, pinned)，外加 SessionSummary 上的 pinned / parentId 两格。⚠️ 加读必须同时加写：在 setPinned 之前 pinned 只有 create() 写下的那个 false，单独暴露出去会是一个永远是 false 的字段 （那也是 SessionDB.pruneCandidates 里「置顶的不参与保留期清理」那条豁免 一次都没生效过的原因）。⚠️ 置顶不算活动，不推动 updatedAt

没有对应的 REST 路（POST /api/sessions/import 不存在）。要它的宿主是把 buildRuntime() 和 createWebServer() 放在同一个进程里那种，手上直接有 rt.sessions；开一条写库的 REST 口子要自己那一套鉴权设计，不是这一版的事。

开发

pnpm --filter @epoch-agent/runtime test

@opentelemetry/* 是可选 peer：不装也能跑，telemetry/otel.ts 探测不到就退化成 NOOP_TELEMETRY。

两个探针在 scripts/ 下，都是跑真实出网请求体的（本地拦截端点 + 假 model 条目）， 不是断言我们调了什么函数：

cd packages/runtime
pnpm exec tsx scripts/probe-tool-tokens.mts
pnpm exec tsx scripts/probe-anthropic-cache.mts