@epoch-agent/protocol

契约层。跨包边界上的类型与常量，没有任何实现。

• ✅ 做：定义跨包共用的类型 / 常量（工具、事件、权限、插件、Hook、配置、线协议）， 以及纯粹作用在这些类型上的口径函数（contentToText / promptTokens 这种）—— 它们跟着类型走，不跟着某个包走，而且 tui 只依赖 protocol， 放别处它就够不着，只能自己抄一份
• ❌ 不做：领域逻辑、任何 I/O、任何状态
• 依赖：无。零 runtime 依赖，谁都可以依赖它

判断一个类型该不该放这里：是否被两个以上的包共用。只有 core 和它的直接下游用到的 （比如 SessionManager 的输入输出类型）不放这里，留在实现包。

文件

第三方要接这套 wire 自己做前端：这几个文件就是契约，直接 import type， 别照着文档抄（文档会过期，类型不会）。接法见 docs/EMBEDDING.md §10。

⚠️ wire-security.ts 和 wire-permission.ts 别按「都带 permission」并起来。 前者是安全中心那一屏的载荷，全是读，答的是「规矩是什么」（规则表、遮蔽 发现、托管锁、信任、策略、审计流水）；后者是输入框框外那一行上那一格， 有写，答的是「这个会话现在是哪一档、改不改得动」。 两者的耦合是真的（WirePermissionState.level 就是 WirePermissionStatus.level 那一格，WireBlockedLevel 是 WireManagedLock.bypassDisabled 的投影）， 所以后者 import type 了前者那两个 —— 判据写在它的文件头， 拆文件不等于解耦。

设置那一份（wire-settings.ts）

它发的不是值，是值加上它赢在哪一层（epoch 的设置有六层来源，见 docs/SETTINGS.md）—— 只显示「当前值」的设置界面会在 「用户改了一个开关、被上面某一层压回去」时撒谎。

⚠️ 这份契约里最要紧的一个字段是 WireSettingWrite.futile，而它在读响应上： 写进的层压不过当前赢的那一层时，那个改动写了等于没写，而这一句必须在用户按下 保存之前说出来。做成写响应的一个字段就迟了 —— 那时它只是一句事后通知。

WireSettingApply 是另一条容易接错的：写完这个进程不会重读配置，所以落盘 之后 GET 回来的值一个字都不会变。别乐观更新那一行 —— 那会显示一个这台机器上 哪儿都不存在的状态。

改这里要注意

wire.ts 的信封有两个出口：epoch web 的 SSE 和 epoch --output-format stream-json 的 stdout NDJSON。共用是刻意的 —— fixtures/wire/*.json 那几份录像因此能同时当两边的夹具，seq 的语义也只有一份。 headless-wire.ts 只加了两个生命周期事件，信封本身一个字段没动。

wire.ts / wire-rest.ts 是 server 和 web 共用的同一份形状： 假服务端（web/dev/fake-server.ts）的每个响应体都挂 satisfies Wire*Response， 所以字段名漂了两边一起编译不过。这是故意的——之前假服务端自己编了一套形状， 于是「先对假服务端验前端」这条验收顺序失去了意义。

events.ts 的 AgentEvent 加成员时，view 的 reducer 要跟着处理， 否则 TUI 和 Web 会静默丢事件。先想清楚谁发 —— diff 那一条在这个联合里 声明了、消费了、渲染了整整一轮，中间一个发射方都没有（判据写在它的 JSDoc 上）。

run-start（2026-08-15）是这个联合最新的一条，由 core 在第一次模型请求之前、 预算闸门之后发，一次 run() 最多一条。它带的 estimatedTokens 是 运行前估算，界面上必须挂「估算」字样 —— 2026-08-15 换了真分词器 （o200k_base）之后偏差小了，但它仍然是发之前算的，真值只有 provider 回的 usage 说了算。判据全文在 provider/tokenizer.ts 的文件头末尾。

agent-role.ts 的 AgentRoleScope 分「子 agent」和「会话」两档，引擎拿它只 挑 system prompt 的身份行；工具收窄、轮次预算、prompt 追加段两档完全一样。 逐条挑专家（方案 57，2026-08-17）没有第三档：session 那句身份行是 「这一次以「x」的身份工作」，「这一次」在逐条语境下正好是对的 —— 两者在模型读到的 字节上没有区别。网线上那一格是 WireSendMessageRequest.role（缺席 = 用这段会话的 角色，认不出来是 400 unknown-role），完整判据在 AgentRoleScope 的文件注释里。

WireSessionSummary.workspace 是三档判别联合（bound / none / unknown， 2026-08-19），不是一个可空引用 —— 这是一次破坏性 wire 变更（同 {binding} 那次：同一个 monorepo 里 packages/web 是唯一消费方，同批改）。换掉它的理由和 {workspace: … | null} → {binding} 那次逐字同源：那个 null 一个值扛了 「明确不使用工作区」和「这个进程说不出它在哪儿干过活」两件事，而侧栏把这一行 归到哪一组，正好取决于这两者的差别。三档的取值优先级（内存绑定 → live → 库里落着的那次决定 → unknown）在 server 的 sessions/summary.ts， 这边不抄第二份。⚠️ 同一个类型上另外三格（pendingSince / turnStartedAt / lastFinish）照旧是可空的、也照旧只有 Hub 手里那些会话才有 —— 它们是运行时活性，进程一退就真的不存在；workspace 能落盘是因为它是 用户的一次决定。

TokenUsage 的五个 token 字段有两种不同的包含关系（缓存两项与 inputTokens 不重叠、reasoningTokens 含在 outputTokens 里），口径表就写在 events.ts 上。 要「一共多少 token」或「提示词多大」，用 usage.ts 的两个函数， 别自己把字段加一遍 —— 漏掉缓存那两项的症状是上下文占用显示成个位数百分比， 而且只在开了 prompt caching 的 provider 上才出现。

同一个文件里还有**「快满了」那条线**（2026-08-16）： compressionThresholdTokens(contextLength, threshold) 和 isContextNearlyFull(prompt, contextLength, threshold)。它们住在这儿的理由和上面 那两个逐字相同 —— 两个必然的消费方，必须给出同一个数：引擎那边是 ContextCompressor.shouldCompress()（真的触发压缩的那一处），界面那边是设置页 「记忆与上下文」里那句「压缩在 64,000 token 时开始」。各写一遍的症状极难查： 界面说「还早」，下一轮却压了。

⚠️ 它只是那条线，不是「会不会压」的完整答案 —— 压缩器上还有冷却期和熔断， 两者都只会让压缩更晚发生。所以界面拿它画的是「到线了」，不是「下一轮一定压」。