knowledge-interaction-surfaces-hono-server-api-and-streaming

Module Structure

Server 是 Web 与自动化客户端的协议适配层：它拥有活动 run、Runtime residency、SSE 订阅者和 Web Browser Session，但 durable transcript 与任务事实仍由 Session 服务持有。

Directory Layout

• packages/cli/src/server/server.ts — Hono 装配、认证/CORS、静态资源和网络生命周期
• packages/cli/src/server/routes/session.ts — Session、run、消息、交互和 SSE 主控制器
• packages/cli/src/server/routes/task.ts — 顶层任务提交、重试、diff 与交付 API
• packages/cli/src/server/routes/events.ts — 跨 Session 的看板安全全局事件流
• packages/cli/src/server/routes/terminal.ts — Bun/Node WebSocket PTY 适配
• packages/cli/src/server/routes/ — 配置、Provider、MCP、插件、Hooks 等管理 API
• packages/cli/src/server/OrderedSseEgress.ts — replay/live 原子切换与有界写入
• packages/cli/src/server/sessionRef.ts — Session 复合身份规范化
• packages/cli/src/server/WebBrowserSessionRegistry.ts — Web 专用 Browser Runtime 所有权

Key Entry Points

• BladeServer.listenAsync() in packages/cli/src/server/server.ts — 启动 Bun 或 Node 服务
• createSessionRouteController() in packages/cli/src/server/routes/session.ts — 创建路由与 Runtime 管理器
• dispatchTask() on SessionRouteController — Web、定时任务共用的任务派发入口
• OrderedSseEgress.finishInitialization() in packages/cli/src/server/OrderedSseEgress.ts — replay 到 live 的切换点
• resolveSessionRef() in packages/cli/src/server/routes/session.ts — 解析精确 Session 所属工作区

Gotchas

• sessionId 不是 Server 内的完整身份；路由、活动 run、Runtime、锁和 Browser Registry 必须使用规范化的 projectPath + sessionId，同名多工作区且未给路径时应返回 409 而不是猜测 (packages/cli/src/server/sessionRef.ts, packages/cli/src/server/routes/session.ts)
• Session SSE 初始化必须先订阅 Bus 并缓冲 live，再写 connected、按 JSONL seq 回放、去重排序后切到 live；先回放再订阅会产生不可修复的事件空窗 (packages/cli/src/server/routes/session.ts, packages/cli/src/server/OrderedSseEgress.ts, git:121ea8fc)
• 只有 committed event 能携带 SSE id；ephemeral delta 在 replay 窗口直接丢弃，不能推进 Last-Event-ID (packages/cli/src/server/bus.ts, packages/cli/src/server/OrderedSseEgress.ts)
• EventSource 首次连接不能自定义 Last-Event-ID header，因此 Server 同时接受 lastEventId query；删除 query 支持会破坏页面刷新后的 durable resume (packages/cli/src/server/routes/session.ts)
• Session SSE 与 /events 全局 SSE 不可互换：全局流只投影白名单化的看板字段，明确排除 prompt 和私有执行细节 (packages/cli/src/server/routes/events.ts)
• 慢 SSE subscriber 的 overflow、写超时或 sequence regression 只终止该 subscriber，不能取消 server-owned Agent run 或影响其他订阅者 (packages/cli/src/server/OrderedSseEgress.ts, docs/reference/surface-egress.md)
• 活动 run 收到新 message 时走 durable steering/follow-up，不启动第二个 run；同时切换模型、权限、reasoning、tier、verbosity、style 或 output schema会返回冲突 (packages/cli/src/server/routes/session.ts)
• pending permission 既可能在内存 run 中，也可能只剩磁盘交互记录；响应路由必须先匹配精确 run，再通过 SessionInteractionService.respondAndRecover() 冷恢复 (packages/cli/src/server/routes/permission.ts, packages/cli/src/server/routes/session.ts)
• API 未设置 BLADE_SERVER_PASSWORD 时整体无认证；启用 Basic Auth 后根页面与静态资源仍公开，只有 API 路径受保护 (packages/cli/src/server/server.ts, packages/cli/src/commands/serve.ts)
• CORS 默认只放行 localhost、127.0.0.1 和 Tauri origin，额外来源必须通过 --cors；监听 0.0.0.0 不会自动放宽 CORS (packages/cli/src/server/server.ts, packages/cli/src/cli/network.ts)
• Node 与 Bun 的 PTY/WebSocket 适配不同，但最后一个终端 subscriber 断开时都会杀掉 PTY；Terminal 面板重连不会保留无人订阅的进程 (packages/cli/src/server/routes/terminal.ts)
• 删除 Session 时还要释放 Web Browser Runtime、活动 review/run、Runtime residency 和任务 worktree；只删 transcript 会留下进程与浏览器资源 (packages/cli/src/server/routes/session.ts, packages/cli/src/server/WebBrowserSessionRegistry.ts)