@chanlerdev/scorel 0.0.1

package/docs/spec/relay.md

@@ -0,0 +1,391 @@
+# Relay Proxy And Hosted Entry
+
+> 上游：`architecture.md`、`decisions/007-relay-proxy-and-entry-routing.md`、`spec/client.md`、`spec/daemon.md`
+> 主题：Hosted WebUI / GUI / CLI Entry 通过 Relay 连接用户 Device-level Host。
+
+---
+
+## 0. 定位
+
+Relay 是 **authenticated proxy + authorization registry**。
+
+Relay 只解决两件事：
+
+1. 让 Entry 和 Host 在公网不可直连时通过一个稳定服务相遇。
+2. 记录哪些 Entry 被允许通过 Relay 控制哪些 Device。
+
+Relay 不是 hosted daemon，也不是新的后端领域层。Project、Session、Runtime、tool execution、JSONL、replay 和 resync authority 仍然只属于 Host。
+
+---
+
+## 1. 角色
+
+```text
+Entry / WebUI / GUI / CLI
+  -> Relay
+    -> Host / Daemon
+      -> Project / Session / Runtime / JSONL
+```
+
+| 角色 | 职责 |
+|---|---|
+| Entry | 用户操作入口。持有稳定 `clientId`，通过 direct WS 或 Relay 连接 Host。 |
+| Relay | 聚合授权关系和在线路由。只转发 daemon wire payload，不解释 Scorel 业务语义。 |
+| Host / Daemon | Device-level Host。拥有 Project Registry、Session JSONL、Runtime、工具和事件流。 |
+
+术语说明：
+
+- `deviceId`：被控制的 Host / Daemon Device 身份。
+- `clientId`：控制 Host 的 Entry 身份。Relay 讨论中也可称为 `entryId`，但协议和 JSONL 继续使用现有 `clientId` 字段。
+
+---
+
+## 2. 不变量
+
+1. Relay 不存 Project Registry。
+2. Relay 不存 Session JSONL。
+3. Relay 不存 prompt、tool result、provider response 或 runtime diagnostics。
+4. Relay 不做 replay、resync、context build 或 Runtime 调度。
+5. Relay durable state 只包含 identity metadata 和授权关系。
+6. Relay transient state 只包含 pair session、presence、socket route。
+7. Host 仍然是唯一 Session writer。
+8. `user_message.clientId` 表示发起该用户动作的 Entry。
+9. Direct WS 和 Relay 只替换 transport，不改变 Device -> Project -> Session 层级。
+
+---
+
+## 3. Relay 状态
+
+### 3.1 Durable Store
+
+Relay 可以持久化：
+
+```typescript
+type RelayDeviceRecord = {
+  deviceId: DeviceId;
+  devicePublicKey?: string;
+  label?: string;
+  createdAt: number;
+  updatedAt: number;
+};
+
+type RelayClientRecord = {
+  clientId: ClientId;
+  clientPublicKey?: string;
+  label?: string;
+  createdAt: number;
+  updatedAt: number;
+};
+
+type RelayBindingRecord = {
+  deviceId: DeviceId;
+  clientId: ClientId;
+  createdAt: number;
+  revokedAt?: number;
+};
+```
+
+V1 可以先把 public key 字段作为 identity contract 预留；具体签名和 key lifecycle 由后续实现 spec 收口。
+
+### 3.2 Transient State
+
+Relay 内存态：
+
+```typescript
+type RelayPresence = {
+  devices: Map<DeviceId, HostSocket>;
+  clients: Map<ClientId, EntrySocket[]>;
+};
+
+type PairSession = {
+  pairCode: string;
+  clientId: ClientId;
+  expiresAt: number;
+};
+```
+
+Pair session 是短期、一次性状态。Relay 重启后允许丢失。
+
+### 3.3 Forbidden State
+
+Relay 不得持久化或缓存：
+
+- Project / Project Registry
+- Session summary / transcript / JSONL
+- prompt / tool result / provider response
+- Runtime state / context / diagnostics
+- resync event cache / replay state
+
+---
+
+## 4. 配对
+
+V1 使用 Entry-initiated pairing：
+
+```text
+Entry
+  -> Relay: create_pair_session(clientId)
+  <- Relay: pairCode
+
+User
+  -> Host: scorel pair <pairCode>
+
+Host
+  -> Relay: redeem_pair(pairCode, deviceId)
+  -> Relay persists binding { deviceId, clientId }
+```
+
+配对语义：
+
+- 用户在本机运行 `scorel pair <code>` 是授权动作；默认连接官方 Relay，自部署时用 `--relay <url>` 覆盖。
+- Pair code 只用于创建 `deviceId -> clientId` 授权关系。
+- Pair code 不是长期 secret。
+- Pair code 过期或被使用后必须失效。
+
+Host 可以在本地保存 authorized client allowlist。Relay binding 负责路由前置检查；Host allowlist 负责最终准入检查。V1 可以先由 Relay binding 承担准入，但正式 spec 应保留 Host-side allowlist 的长期方向。
+
+---
+
+## 5. 连接与路由
+
+Relay 连接有两条物理 WebSocket：
+
+```text
+Entry  -> Relay
+Host   -> Relay
+```
+
+Entry 连 Host 不需要再建立第三条网络连接。Relay 只在已有 socket 上做逻辑路由：
+
+```text
+Entry socket + deviceId -> Relay -> Host socket
+```
+
+### 5.1 Presence
+
+Host relay mode：
+
+```text
+Host
+  -> load device identity
+  -> connect Relay
+  -> announce deviceId
+  -> Relay marks deviceId online
+```
+
+Entry / hosted WebUI：
+
+```text
+Entry
+  -> load stable clientId
+  -> connect Relay
+  -> announce clientId
+  -> Relay marks clientId online
+```
+
+Presence 只表示在线，不代表授权。
+
+### 5.2 Routing Frame
+
+Entry 发往 Relay：
+
+```typescript
+type RelayClientPayload =
+  | ({ type: "connect" } & ConnectParams)
+  | ClientMessage;
+
+type EntryToRelayFrame = {
+  deviceId: DeviceId;
+  payload: RelayClientPayload;
+};
+```
+
+Relay 检查：
+
+```text
+binding exists for (deviceId, clientId)
+deviceId is online
+```
+
+Relay 发往 Host：
+
+```typescript
+type RelayToHostFrame = {
+  clientId: ClientId;
+  payload: RelayClientPayload;
+};
+```
+
+Host 发回 Relay：
+
+```typescript
+type HostToRelayFrame = {
+  clientId: ClientId;
+  payload: DaemonMessage;
+};
+```
+
+Relay 再把 payload 发回对应 Entry socket。
+
+`RelayClientPayload` 包含现有 daemon `connect` handshake 和 `ClientMessage`。Relay 只做外层路由和授权，不解释业务 payload。`clientId` 是现有 daemon wire / JSONL 字段。它在 Relay 语境中就是 Entry identity。不要为 V1 额外引入 `entryId` 或 `routeId` 字段，除非实现证明现有 `clientId` 无法覆盖多 tab / 多连接的 return path。
+
+---
+
+## 6. DaemonClient 语义
+
+Relay 是 transport adapter：
+
+```typescript
+const transport = new RelayTransport({
+  relayUrl,
+  deviceId,
+  clientId,
+});
+
+const client = new DaemonClient(transport, options);
+await client.connect(sessionId);
+```
+
+Direct WS 与 Relay 的差异只在 transport 层：
+
+```text
+Direct:
+  DaemonClient -> WsTransport -> Host
+
+Relay:
+  DaemonClient -> RelayTransport -> Relay -> Host relay adapter -> Host
+```
+
+进入 Host 后，仍然是现有 Host API：
+
+- `listProjects`
+- `listSessions`
+- `createSession`
+- `sendMessage`
+- `rewriteQueue`
+- `cancel`
+- `subscribeEvents`
+- `resyncEvents`
+
+Host 不应复制一套 Relay-only Project、Session 或 Runtime 逻辑。
+
+---
+
+## 7. WebUI 多设备模型
+
+Hosted WebUI 可以添加很多 Device。每个 Device 可以有多个 connector：
+
+```typescript
+type WebUiDevice = {
+  id: string;
+  remoteIdentity?: {
+    deviceId: DeviceId;
+  };
+  connectors: DeviceConnector[];
+};
+
+type DeviceConnector =
+  | { kind: "direct_ws"; url: string; token: string }
+  | { kind: "relay"; relayUrl: string; deviceId: DeviceId; clientId: ClientId };
+```
+
+规则：
+
+- Device 是业务身份，connector 是可达路径。
+- 同一 `deviceId` 通过 direct WS 和 Relay 都可达时，WebUI 应合并为一个 Device。
+- `deviceId + projectId + sessionId` 是缓存 scope，不是 URL 或 connector。
+- Relay 可以返回授权 Device 列表和在线状态；Project / Session 列表仍然必须通过 Host API 获取。
+
+连接选择：
+
+1. direct local WS healthy 时优先直连。
+2. direct 不可用且 Relay presence 在线时使用 Relay。
+3. 都不可用时显示离线缓存。
+
+---
+
+## 8. 重连与恢复
+
+Relay 不做 Session replay。
+
+断线恢复：
+
+```text
+Entry reconnects Relay
+Host reconnects Relay
+Entry sends existing DaemonClient.connect/resync through Relay
+Host answers from JSONL / live buffer
+```
+
+恢复锚点仍然是 Host 语义：
+
+- `persistentLastSeq`
+- `streamLastSeq`
+
+Relay 重启会丢失 presence 和 pair sessions，但 durable bindings 可以保留。Relay 重启不影响 Host JSONL authority。
+
+---
+
+## 9. 不做什么
+
+- 不实现 hosted execution。
+- 不要求 V1 必须有用户账号。
+- 不把 Relay 变成 Project / Session 后端。
+- 不让 Relay 解释 daemon wire payload。
+- 不在 Relay 中实现 replay / resync / context build。
+- 不在本 spec 定义细粒度 ACL。
+- 不在本 spec 实现 desktop GUI、SSH bootstrap 或 HTTP API。
+
+---
+
+## 10. 目录结构
+
+Relay service 是可部署产品入口，默认放在 `apps/relay`，不是新的领域包。
+
+```text
+apps/
+  relay/
+    package.json
+    src/
+      index.ts          # process entrypoint
+      server.ts         # WebSocket / HTTP server bootstrap
+      store.ts          # durable device/client/binding store adapter
+      pairing.ts        # short-lived pair sessions
+      presence.ts       # online device/client socket registry
+      routing.ts        # deviceId/clientId authorization check and proxy routing
+      diagnostics.ts    # relay-side logs without user payload
+
+packages/
+  protocol/
+    src/relay.ts        # Relay frame and record types
+  client/
+    src/relay-transport.ts
+  daemon/
+    src/relay/
+      host-client.ts    # Host outbound Relay connection
+      pair.ts           # scorel pair support helpers
+
+apps/
+  cli/
+    src/relay-cli.ts    # scorel pair support
+    src/relay-server-cli.ts # scorel relay serve
+  webui/
+    ...                 # direct connector + relay connector UI
+```
+
+分工规则：
+
+- `apps/relay`：只包含 deployable Relay service 和它的 runtime wiring。
+- `packages/protocol`：放 Relay frame、record、request/response 类型；保持 browser-safe、零 Node 依赖。
+- `packages/client`：放 `RelayTransport`，实现现有 `DaemonTransport` contract。
+- `packages/daemon`：放 Host outbound Relay adapter；它把 Relay frame 转回现有 Host handler。
+- `apps/cli`：只放命令入口，例如 `scorel pair <code>`、`scorel host serve`、`scorel relay serve`。
+- `apps/webui`：只放 connector UI、Device registry 和 `RelayTransport` 使用逻辑。
+
+不要创建顶层 `relay/` 目录。当前 workspace 只约定 `apps/*` 和 `packages/*`；顶层目录会绕开现有 monorepo 边界。
+
+不要默认创建 `packages/relay`。只有当 Relay server 逻辑需要被多个 deployable app 复用时，才把纯库部分提取为 `packages/relay-server` 或类似名字；V1 先把服务私有逻辑留在 `apps/relay/src`，避免过早抽象。
+
+---
+
+*Relay 的产品价值是让多 Entry 和多 Device 通过一个稳定服务形成授权连接图；Scorel 的业务真相仍然在 Device-level Host。*

package/docs/spec/runtime.md

@@ -0,0 +1,251 @@
+# ScorelRuntime — 执行引擎
+
+> 上游：`architecture.md`、`spec/events.md`
+> 主题：ScorelRuntime 是纯执行引擎，接收 context 输入，产出 RawRuntimeEvent 流。不持有状态，不负责持久化。
+
+---
+
+## 1. 设计目标
+
+Runtime 只做一件事：**给定 context，驱动 LLM + 工具循环，产出事件流**。
+
+不管：
+- 持久化（Daemon 通过 RuntimeBridge 负责）
+- 状态管理（SessionTree 负责）
+- 并发控制（SessionLane 负责）
+- 事件分发（EventBroadcaster 负责）
+
+这种分离让 Runtime 可测试、可复用、职责单一。
+
+---
+
+## 2. 核心变化（相对早期设计）
+
+| 之前 | 之后 |
+|------|------|
+| Runtime 管理 message history | Runtime 接收 context 作为输入 |
+| Runtime 负责持久化 | Daemon 负责持久化（通过 RuntimeBridge） |
+| Runtime 输出 ScorelEvent | Runtime 输出 RawRuntimeEvent（无 seq/id） |
+| Runtime 有 `prompt()` / `loadMessages()` | Runtime 只有 `executeTurn(context)` |
+
+---
+
+## 3. 接口
+
+```typescript
+interface ScorelRuntime {
+  /**
+   * 执行一轮。接收预构建的 context，返回 raw event generator。
+   * 内部处理工具循环直到 turn 结束。
+   */
+  executeTurn(
+    context: ScorelMessage[],
+    systemPrompt: string | undefined,
+    options: RuntimeTurnOptions
+  ): AsyncGenerator<RawRuntimeEvent, void, undefined>;
+
+  cancel(): void;
+  readonly running: boolean;
+
+  // 工具注册
+  registerTool(tool: ToolDefinition): void;
+  unregisterTool(name: string): void;
+}
+```
+
+---
+
+## 4. RawRuntimeEvent（内部，不导出给消费者）
+
+```typescript
+type RawRuntimeEvent =
+  | { type: "message_start"; role: "assistant" }
+  | { type: "text_delta"; delta: string }
+  | { type: "thinking_delta"; delta: string; blockIndex: number }
+  | { type: "tool_call_delta"; toolCallId: string; toolName?: string; delta: string }
+  | { type: "message_end"; message: AssistantMessage }
+  | { type: "tool_execution_start"; toolCallId: string; toolName: string; args: unknown }
+  | { type: "tool_execution_update"; toolCallId: string; partial: unknown }
+  | { type: "tool_execution_end"; toolCallId: string; toolName: string; result: ToolResultBlock; durationMs: number }
+  | { type: "turn_start" }
+  | { type: "turn_end"; usage?: Usage; stopReason?: string }
+  | { type: "error"; error: Error };
+```
+
+RuntimeBridge 负责将 RawRuntimeEvent 转换为统一的 ScorelEvent（分配 id、seq、parentId）。
+
+---
+
+## 5. Persist 策略：有内容就 persist
+
+**规则：只要已生成文本 > 0，无论中断原因都 persist partial。**
+
+| 场景 | 行为 |
+|---|---|
+| LLM 正常完成 | persist，stopReason: "end_turn" |
+| API 错误（有文本） | persist partial，stopReason: "error" |
+| 用户 Cancel（有文本） | persist partial，stopReason: "cancelled" |
+| 用户 Cancel（无文本） | 不 persist，broadcast message_cancelled (transient) |
+| Daemon 崩溃 | 丢失进行中消息（初期可接受） |
+
+Partial message 的 `partial: true` 标记告诉 UI 展示中断状态。buildContext 时当正常 assistant message 使用。
+
+---
+
+## 6. 每步完成立刻 persist
+
+不等整个 turn 结束。Agent loop 中每一步完成就写 JSONL：
+
+```
+user message          → 立刻 persist (进入 executeTurn 前)
+assistant message_end → 立刻 persist
+tool_result 完成      → 立刻 persist
+```
+
+这保证任何时刻断线，JSONL 都包含到该步骤为止的完整状态。
+
+---
+
+## 7. Tool Result：per-tool-call 逐条 persist，串行链
+
+一条 assistant message 含多个 tool_use 时，每个工具结果独立 persist 为一条 message event，串行排列（不分叉）：
+
+```
+e04: assistant (tool_use[read_a] + tool_use[read_b])   parentId: e03
+e05: tool_result (for read_a)                          parentId: e04
+e06: tool_result (for read_b)                          parentId: e05
+```
+
+pi-ai 的 `transformMessages` 负责跨 provider 格式转换。用户级 rewind 只暴露到 user message 粒度——rewind 到 e04 之前 = e04/e05/e06 全部不在 context 中。
+
+---
+
+## 8. Cancel 时补 error tool_result
+
+LLM 生成了 tool_use 但工具未执行/被中断时，必须补一条 error tool_result 避免 unmatched tool call：
+
+| Cancel 时机 | 行为 |
+|---|---|
+| 工具正在执行 | 等当前工具原子完成 → persist 正常 result → 不发起下轮 LLM |
+| 工具还没开始 | persist error tool_result: `{ isError: true, content: "Cancelled by user" }` |
+| Assistant message partial（tool_use JSON 截断） | 只保留 text 部分 persist，不含不完整 tool_use → 不需要补 tool_result |
+
+---
+
+## 9. Steer + FollowUp 双队列
+
+借鉴 pi-mono agent-loop 模式：
+
+| Queue | 消费时机 | 用途 |
+|---|---|---|
+| steeringQueue | 每次 tool 完成后、下次 LLM 调用前 | 中途插话（"别改了"） |
+| followUpQueue | end_turn + steeringQueue 空 | 追加任务（"顺便跑 tests"） |
+
+Loop 逻辑：
+```
+while (true):
+  LLM call → response
+  if tool_use → execute tools → drain steeringQueue → continue
+  if end_turn → drain steeringQueue
+    → if empty → drain followUpQueue
+      → has messages → inject as user message, continue
+      → both empty → runtime_end
+```
+
+### 9.1 Steer 消息的存储与呈现
+
+Steer message persist 为**独立 PersistentEvent**（role = "user"，`meta.source = "steer"`）。
+
+```typescript
+// steer persist 为独立 message event
+{
+  type: "message",
+  id: "e14",
+  parentId: "e13",  // 挂在当前 tool_result 链之后
+  message: {
+    role: "user",
+    content: "别改了，直接跑测试",
+    meta: { source: "steer" }
+  }
+}
+```
+
+**convertToLlm 行为**（由 EventTypeHandler 声明）：
+
+| 前面有 tool_result | 行为 |
+|---|---|
+| ✅ 有 | `merge_prev` — 合入前一条 tool_result content 末尾，用 `<system-reminder>` 包裹 |
+| ❌ 没有（idle 状态） | `include` — 作为独立 user message |
+
+LLM 最终看到的（工具循环中）：
+```
+tool_result: "文件内容...\n\n<system-reminder>\n别改了，直接跑测试\n</system-reminder>"
+```
+
+LLM 最终看到的（idle 时）：
+```
+user: "别改了，直接跑测试"
+```
+
+FollowUp 同理：`meta: { source: "followUp" }`。
+
+### 9.2 Steer 在 idle 时
+
+- Runtime 空闲时收到 steer → 等同 send_message，直接触发新 turn
+- Runtime 运行中收到 steer → 注入 steeringQueue，下轮开始时消费
+
+---
+
+## 10. RuntimeBridge（Daemon-owned）
+
+RuntimeBridge 是 Daemon 与 Runtime 之间的桥接层。它在本 spec 中作为 integration contract 描述，因为它消费 RawRuntimeEvent；实现归属 `@scorel/daemon`，不能放进 `@scorel/core/runtime`。
+
+Daemon-owned RuntimeBridge 负责：
+
+1. 持久化 user MessageEvent
+2. 从 tree 构建 context
+3. 调用 runtime.executeTurn(context) 获得 AsyncGenerator
+4. 将 raw events 转换为统一事件（预分配 id、分配 seq）
+5. 持久化 assistant MessageEvent
+6. 如有 tool calls → 执行工具 → 持久化 tool_result MessageEvent → 继续循环
+
+```typescript
+interface RuntimeBridge {
+  readonly sessionId: SessionId;
+  readonly running: boolean;
+
+  /**
+   * 执行一轮对话。完整流程见上述 6 步。
+   */
+  executeTurn(userMessage: UserMessage, options?: SendOptions): Promise<void>;
+
+  cancel(): Promise<void>;
+}
+```
+
+### 10.1 Runtime 与 Session 关系
+
+- 一个 daemon 可以运行**多个 runtime**
+- 每个 runtime 服务**一个 session**（1:1）
+- 多个终端同时操作不同 session = 多个并发 runtime
+- 同一 session 的多个 client 共享一个 runtime（串行化通过 SessionLane）
+
+---
+
+## 11. 初期范围与延后项
+
+**初期落地**
+- ScorelRuntime 接口 + executeTurn
+- RawRuntimeEvent → ScorelEvent 转换（daemon-owned RuntimeBridge）
+- Persist 策略（partial persist + per-step persist）
+- Cancel 处理（补 error tool_result）
+- steeringQueue + followUpQueue 双队列
+
+**延后**
+- 工具并行执行优化（初期串行安全优先）
+- Runtime 资源限制（timeout per-turn、token budget）
+- Subagent 工具（递归调用隔离上下文）
+
+---
+
+*Runtime 是纯函数式执行引擎。给 context，出 events。状态、持久化、分发全部外置。*