dsh-edge 0.14.1 → 0.15.0-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # last confirmed-consistent state. Both languages carry equal authority.
 # After editing either side, update both and re-record every pair with:
 #   pnpm run doc-pairs -- --write
-README.md: 6f74df2cfdfd296bd3160bc0c66113c3c8a2147f
-README.zh.md: 6bf1ac6ab667a46d25ce5baa516b0cbe26f2585d
+README.md: 313b3877f1f962865c6a8d8ba3e3a05f11599346
+README.zh.md: 786e48302fb57a8d7b9646991a1b600eace86fec

package/README.md

@@ -14,7 +14,7 @@ The runtime keeps upstream ownership clear:
 
 - `ReactLoopAgent`, `AgentRegistry`, `LlmRuntime`, `ToolRuntime`, `SystemPrompt`, `SessionStore`, and `SessionPersistence` run through the upstream Cordis composition.
 - The upstream `dsh-llm-deepseek` cordis plugin is installed directly, auto-registering its settings namespace and configurable provider entry. Edge maps the native DSH `bash` tool onto Cloudflare Computer.
-- Durable Object SQLite implements the upstream persistence backend contract. `PersistenceCoordinator` still owns write-behind, revisions, resume preparation, and crash recovery.
+- Durable Object SQLite implements the upstream `SessionHandle` persistence contract. Edge buffers live events and flushes them before publication; initialization events, including `session/end-seed` during cold model selection, are persisted before subsequent mutations. The upstream agent loop supplies interrupted-turn closers on resume. Under write ownership, Edge first truncates a torn physical tail and atomically rebuilds summaries and reminder state; tails containing inbox events, malformed reminders, or already-dispatched reminders are rejected to prevent duplicate delivery.
 - Model history is projected from canonical events rather than persisted in a second Edge schema.
 - `GoalService` and `ToolGoal` run as upstream cordis plugins (direct composition). Browser GoalBar mutations route through `TypertGatewayService`.
 - `SessionProjectionCache` persists goal, title, and model state across Durable Object restart via KV cache.
@@ -150,7 +150,7 @@ This reference separates code that runs natively in Workers, code adapted at an
 | DSH transport | Typed HTTP RPC plus mux and host WebSocket downlinks | Reused with an Edge server implementation | Use the upstream fetch carrier for unary methods and preserve its envelopes, schemas, projections, lazy blank-session behavior, bounded content search, prompt and queue mutations, workspace mutations, queue snapshots, and event frames. Durable Object WebSocket hibernation owns both downlinks; mux reconnects replay pending live inbox state, while REST/SSE routes remain a diagnostic compatibility path. |
 | Workspace registry | Storage-domain global state plus `WorkspaceRecord` rows | Native backend adaptation | Keep the upstream global and record value shapes, including manual session order and archive membership, but map their physical keys and atomic writes to Durable Object storage. Edge constrains the registry to the one native `/workspace` VFS; rename, delete, recreation, and session reordering retain the upstream RPC and Host-frame semantics. |
 | Directory picker | `ctx.directoryPicker` seam with the `-native` OS chooser or the `-browse` filesystem backend, chosen at boot by `dsh-host-directory-picker-auto`, plus the Web browse dialog | Reused with an Edge browse backend | Install the upstream seam and pin the upstream `dsh-client-ui-directory-picker-browse` dialog in the Web roster; Edge answers the `browse` capability from the `/workspace` Computer VFS one level per call, rooted at `/workspace` with the upstream hidden, bound, and failure vocabulary, so the upstream `DirectoryPickerController` serves `directoryPicker/list` and `createDirectory` and refuses the native `pick`. |
-| Conversation file links | `session/openWorkspacePath` hands a clicked path to the Host desktop opener through `dsh-native-command`; `session/canOpenWorkspacePath` gates the affordance | Adapted at the upstream `SessionControllerInternals` seam plus a Web download fallback | Compose `SessionController` with Edge internals so the native probe answers false and an open attempt fails with a readable reason instead of a `child_process` error. The Edge Web plugin keeps the upstream `ctx.remote.session.openWorkspacePath` call and, when the Host refuses, streams the file through the owner-authenticated `GET /api/workspace/file` route as a browser download, so a clicked `read`, `write`, or `edit` row saves the file instead of showing the upstream open-failure dialog. |
+| Conversation file links | `session/openWorkspacePath` hands a clicked path to the Host desktop opener through `dsh-native-command`; `session/canOpenWorkspacePath` gates the affordance | Adapted at the upstream `SessionControllerInternals` seam plus a Web download fallback | Compose `SessionController` with Edge internals so the native probe answers false and an open attempt fails with a readable reason instead of a `child_process` error. The V3 Web client opens file links in its right-sidebar preview. Edge composes the upstream `workspaceFiles` controller over request-scoped VFS reads, including bounded text/byte windows and metadata subscriptions. The legacy `ctx.remote.session.openWorkspacePath` fallback and owner-authenticated `GET /api/workspace/file` download remain available. |
 | Existing Web UI | Runtime-loaded shell and `dsh.client` plugin graph | Reused with generic composition fallbacks | Assemble the upstream shell and supported upstream client bundles as Worker assets. Shared slot-occupancy rules hide actions whose provider is absent; Cloudflare serves ordinary assets directly, while `/`, `/login`, and `/api/*` enter the Worker for owner access control. The assembled asset policy prevents every direct or SPA-fallback shell alias from being framed. |
 | Other tools | Web Search, filesystem editor tools, MCP, skills, workflows, jobs, and subagents | Search, file, goal, and skill tools ported; MCP, workflows, and subagents not yet ported | Reuse upstream DeepSeek Web Search with its 30-second tool-call timeout. File tools (read/write/edit/read_image) adapted via `EdgeFileSystem` backed by Computer VFS. Goal tools (`ToolGoal`) composed directly with `GoalService` as upstream cordis plugins. Skill tool via `SkillRegistry` + `EdgeSkillProvider` (DO KV-backed); owner CRUD at `GET/PUT/DELETE /api/skills`. MCP client (`dsh-mcp-client`) not yet installed; Streamable HTTP transport is feasible on the free plan. Add the remaining tools individually against Worker-compatible capabilities; do not advertise unavailable host behavior. |
 | Attachments | Local attachment storage, upstream image references, composer, gallery, lightbox, and provider conversion | Adapted at the native storage seam | Reuse upstream `AttachmentStore`, admission, protocol, authorization, UI, and DeepSeek conversion unchanged. Store immutable PNG/JPEG bytes under their SHA-256 identities in private R2 for new permanent deployments or in a 64 MiB, 512 KiB-chunked DO backend for temporary deployments and owners who select it while upgrading a pre-attachment Worker; session events retain only upstream refs. The first backend is pinned per owner instance so claiming or upgrading cannot strand existing references. |
@@ -188,7 +188,7 @@ Cloudflare static assets -> upstream Web shell + client plugin graph
      (or optional Computer Worker Shell when LOADER is bound)
   -> Durable Object /workspace VFS
   -> upstream tool/result and next model step
-  -> ReactLoopAgent appends canonical inbox, chunk, message, tool and boundary events
+  -> ReactLoopAgent appends canonical inbox, message, tool and boundary events (V3 embeds compact streams in assistant events)
   -> sessions.flush durable barrier -> Durable Object SQLite backend
   -> session/event, projection, and status frames over Durable Object WebSockets
   -> upstream Web runtime reconciles and renders the canonical events
@@ -325,8 +325,13 @@ pnpm --filter dsh-edge example:install
 - After each committed inbox splice, mux publishes a complete `session/queue` snapshot. Reconnecting clients receive pending live-inbox baselines.
 - `POST /api/commands/list` uses the upstream generated-Remote envelope with an empty catalog because the Edge preset registers no human commands.
 - `GET /api/health` returns the public release/mode identifier and configured attachment default (`private-r2` or `temporary-do`). It validates owner authentication, deployment-scoped DeepSeek credentials, model/transport choices, and command timeouts before reporting ready.
+- `GET /api/ready` requires the owner cookie and waits for session migration, workspace registration, the browser's session/workspace controllers, and registration of the DeepSeek model adapter. It does not make a provider request. It returns HTTP 503 with `runtime-initialization-failed` if startup fails; public health alone does not prove runtime readiness. Ordinary authenticated routes wait for base initialization without requiring the model adapter, preserving history and recovery access when only model initialization failed.
 - Health does not call the provider, Durable Object, R2, VFS, or shell. The authenticated agent-preset projection reports the pinned backend, temporary cap, deployment-default model, and runtime-derived upstream catalog with session selection scope.
 
+Release upgrades automatically normalize the known legacy Edge cancellation records and migrate all outdated session logs, summaries, and blank headers in one SQLite transaction. All old logs are decoded and validated before the first migration write, so incompatible later logs cannot repeatedly consume earlier migration writes on restart. Preflight discards each decoded artifact; migration decodes again in the same synchronous transaction to avoid retaining every history in memory. If any session is incompatible or a write fails, that startup migration is rolled back in full. No session is silently skipped or deleted. This transaction covers session-format migration, not arbitrary plugin storage changes or external side effects. The installer matches the Cloudflare Worker version ID from upload output against both public health and authenticated readiness, so an earlier deployment of the same package cannot satisfy the check. The version metadata binding is included in both modes. The installer checks runtime readiness before reporting success; a timeout is reported as unverified, and a confirmed startup failure reports an error with recovery details. It never automatically rolls back Worker code after a schema upgrade. Release tests boot both prebuilt modes with legacy cancellation data, verify continuation, and reject false readiness on incompatible data; the packed npm artifact is also checked for authenticated runtime readiness.
+
+SQLite `DELETE` operations consume the daily row-write allowance too. During format migration, Edge compares the number of legacy and current event rows: a single index-backed probe stops once copying current rows would cost more; when copying is cheaper, it writes the migrated compact logs into a replacement table and swaps tables inside the same transaction, avoiding a billed delete for every legacy token delta. Otherwise it replaces only the affected sessions. Current session logs are preserved, and failed migrations roll back the table swap. This reduces migration writes but cannot guarantee that every database fits the Free plan's 100,000 daily row-write allowance; sufficiently large upgrades or earlier daily usage can still exhaust it. Point-in-time recovery restores data, not the account's consumed daily quota.
+
 ### Diagnostic REST routes
 
 - `PUT /api/workspace/file?path=/workspace/...` writes a UTF-8 file.

package/README.zh.md

@@ -14,7 +14,7 @@
 
 - `ReactLoopAgent`、`AgentRegistry`、`LlmRuntime`、`ToolRuntime`、`SystemPrompt`、`SessionStore` 和 `SessionPersistence` 通过上游 Cordis 组合运行。
 - 上游 `dsh-llm-deepseek` cordis 插件直接安装，自动注册 Settings 命名空间和可配置 Provider 条目。Edge 把原生 DSH `bash` 工具映射到 Cloudflare Computer。
-- Durable Object SQLite 实现上游持久化后端约定；write-behind、revision、恢复准备与崩溃恢复仍由 `PersistenceCoordinator` 负责。
+- Durable Object SQLite 实现上游 `SessionHandle` 持久化约定。Edge 缓冲实时事件并在发布前完成落盘；初始化事件（包括冷会话切换模型时的 `session/end-seed`）先于后续变更持久化。上游 agent loop 在恢复时补齐中断 turn 的结束事件。Edge 在持有写入所有权时先截断损坏的物理尾部，并原子重建摘要和提醒状态；对于含有 inbox 事件、格式损坏提醒或已派发提醒的尾部，拒绝自动修复，避免重复投递。
 - 模型历史从 canonical 事件投影，不在 Edge 中建立第二套 schema。
 - `GoalService` 和 `ToolGoal` 作为上游 cordis 插件直接组合。浏览器 GoalBar mutation 经由 `TypertGatewayService` 路由。
 - `SessionProjectionCache` 通过 KV 缓存在 Durable Object 重启后持久化 goal、title 和 model 状态。
@@ -150,7 +150,7 @@ curl -b /tmp/dsh-edge-cookie -N -X POST -H 'content-type: application/json' \
 | DSH transport | Typed HTTP RPC 加 mux/host WebSocket downlink | 复用并提供 Edge 服务端实现 | 对 unary method 使用上游 fetch carrier，并保留其 envelope、schema、projection、lazy blank-session 行为、有界内容搜索、prompt 与 queue mutation、workspace mutation、queue snapshot 和 event frame。两条 downlink 都由 Durable Object WebSocket 休眠机制持有；mux 重连会重放 live inbox 的待处理状态，REST/SSE 路由则保留为诊断兼容路径。 |
 | Workspace registry | Storage-domain global state 加 `WorkspaceRecord` rows | 原生 backend 适配 | 保持上游 global 和 record value shape，包括手动 session 顺序与 archive membership；仅把物理 key 和原子写入映射到 Durable Object storage。Edge 把 registry 限制为一个原生 `/workspace` VFS；rename、delete、recreate 与 session reorder 保持上游 RPC 和 Host-frame 语义。 |
 | Directory picker | `ctx.directoryPicker` seam，由 `dsh-host-directory-picker-auto` 在启动时选择 `-native` OS 选择器或 `-browse` 文件系统 backend，加 Web browse 对话框 | 复用并提供 Edge browse backend | 安装上游 seam，并把上游 `dsh-client-ui-directory-picker-browse` 对话框固定进 Web roster；Edge 从 `/workspace` Computer VFS 按每次一层回答 `browse` capability，以 `/workspace` 为根并沿用上游的 hidden、bound 与失败词汇，因此上游 `DirectoryPickerController` 提供 `directoryPicker/list` 与 `createDirectory`，并拒绝原生 `pick`。 |
-| 对话文件链接 | `session/openWorkspacePath` 经 `dsh-native-command` 把点击的路径交给宿主桌面打开器；`session/canOpenWorkspacePath` 决定是否展示该入口 | 在上游 `SessionControllerInternals` seam 适配，加 Web 端下载回退 | 用 Edge internals 组合 `SessionController`，让原生探测返回 false、打开尝试以可读原因失败而不是 `child_process` 错误。Edge Web 插件保留上游 `ctx.remote.session.openWorkspacePath` 调用，宿主拒绝时经 owner 鉴权的 `GET /api/workspace/file` 路由把文件作为浏览器下载流出，因此点击 `read`、`write`、`edit` 行会保存文件而不是弹出上游的打开失败对话框。 |
+| 对话文件链接 | `session/openWorkspacePath` 经 `dsh-native-command` 把点击的路径交给宿主桌面打开器；`session/canOpenWorkspacePath` 决定是否展示该入口 | 在上游 `SessionControllerInternals` seam 适配，加 Web 端下载回退 | 用 Edge internals 组合 `SessionController`，让原生探测返回 false、打开尝试以可读原因失败而不是 `child_process` 错误。V3 Web 客户端在右侧栏预览文件链接。Edge 将上游 `workspaceFiles` 控制器接入请求作用域内的 VFS 读取，支持有界文本/字节分页和元数据订阅。旧版 `ctx.remote.session.openWorkspacePath` 回退以及经 owner 鉴权的 `GET /api/workspace/file` 下载仍然可用。 |
 | Existing Web UI | 运行时加载的 shell 和 `dsh.client` 插件 graph | 复用并采用通用 composition fallback | 把上游 shell 和受支持的上游客户端包组装成 Worker 静态资源；共享的 slot occupancy 规则会隐藏缺少 provider 的 action。Cloudflare 直接提供普通资源，`/`、`/login` 与 `/api/*` 则进入 Worker 执行 owner access control。组装后的 asset policy 会阻止所有直接或 SPA-fallback shell alias 被嵌入 frame。 |
 | Other tools | Web Search、filesystem editor tools、MCP、skills、workflows、jobs 和 subagents | Search、文件、goal 和 skill 工具已移植；MCP、workflows 和 subagents 尚未移植 | 复用上游 DeepSeek Web Search 及其 30 秒 tool-call timeout。文件工具（read/write/edit/read_image）通过 `EdgeFileSystem` 适配 Computer VFS。Goal 工具（`ToolGoal`）作为上游 cordis 插件直接与 `GoalService` 组合。Skill 工具通过 `SkillRegistry` + `EdgeSkillProvider`（DO KV 存储）；owner CRUD 接口 `GET/PUT/DELETE /api/skills`。MCP client（`dsh-mcp-client`）尚未安装；Streamable HTTP transport 在免费 plan 上可行。逐个针对 Worker-compatible capabilities 增加其余工具，不宣称不可用的 host 行为。 |
 | Attachments | 本地 attachment storage、上游 image reference、composer、gallery、lightbox 与 provider conversion | 在原生 storage seam 上适配 | 原样复用上游 `AttachmentStore`、admission、协议、授权、UI 与 DeepSeek conversion。PNG/JPEG 不可变字节按 SHA-256 identity 存入新永久部署的私有 R2，或存入临时部署以及升级旧版 Worker 时由 owner 选择的 64 MiB、按 512 KiB 分块的 DO backend；session event 只保留上游 ref。每个 owner instance 首次选择的 backend 会被固定，认领或升级不会让既有引用失联。 |
@@ -188,7 +188,7 @@ Cloudflare static assets -> upstream Web shell + client plugin graph
      (or optional Computer Worker Shell when LOADER is bound)
   -> Durable Object /workspace VFS
   -> upstream tool/result and next model step
-  -> ReactLoopAgent appends canonical inbox, chunk, message, tool and boundary events
+  -> ReactLoopAgent appends canonical inbox, message, tool and boundary events (V3 embeds compact streams in assistant events)
   -> sessions.flush durable barrier -> Durable Object SQLite backend
   -> session/event, projection, and status frames over Durable Object WebSockets
   -> upstream Web runtime reconciles and renders the canonical events
@@ -325,8 +325,13 @@ pnpm --filter dsh-edge example:install
 - 每次 inbox splice 提交后，mux 都发布完整的 `session/queue` snapshot。客户端重连时会收到待处理的 live-inbox baseline。
 - `POST /api/commands/list` 使用上游 generated-Remote envelope 返回空 catalog，因为 Edge preset 没有注册 human command。
 - `GET /api/health` 返回公开 release/mode identifier 与配置的 attachment 默认值（`private-r2` 或 `temporary-do`）。它先验证 owner authentication、部署级 DeepSeek 凭据、模型/传输选择与命令 timeout，再报告 ready。
+- `GET /api/ready` 要求 owner cookie，等待会话迁移、工作区注册、浏览器所需的会话/工作区控制器就绪，以及 DeepSeek 模型适配器完成注册。此检查不会向模型服务发起请求。启动失败时返回 HTTP 503 和 `runtime-initialization-failed`；公开 health 响应不能单独证明运行时可用。普通认证路由只等待基础初始化，不要求模型适配器可用；仅模型初始化失败时，仍保留历史记录和恢复访问。
 - Health 不调用 provider、Durable Object、R2、VFS 或 shell。认证后的 agent-preset projection 会报告固定 backend、临时存储上限、部署默认模型，以及 runtime 实际读取的上游 catalog 与 session 选择范围。
 
+Release 升级会自动兼容已知的旧版 Edge 取消记录，并在一个 SQLite 事务中迁移所有旧格式会话日志、摘要和空会话头。首次迁移写入前会解码并校验所有旧日志，避免后面的不兼容日志导致每次重启都重复消耗前面会话的迁移写入。预检会释放每份解码结果；迁移阶段在同一同步事务内再次解码，避免把所有历史同时保留在内存中。任一会话不兼容或写入失败时，本次启动的迁移会整体回滚，不会静默跳过或删除会话。此事务覆盖会话格式迁移，不涵盖任意插件存储改动或外部副作用。安装器会把上传输出中的 Cloudflare Worker 版本 ID 与公开 health 和经过认证的就绪响应分别比对，同一软件包的旧部署不能满足该检查；两种模式都包含版本元数据绑定。安装器检查运行时就绪状态，通过后才报告成功；超时会报告尚未验证，确认启动失败则报告错误和恢复信息。它不会在存储格式升级后自动回滚 Worker 代码。发布测试使用含旧取消记录的数据启动两种预构建模式，验证继续聊天，并确认不兼容数据不会误报就绪；打包后的 npm 产物也会验证经过认证的运行时就绪状态。
+
+SQLite 的 `DELETE` 操作也会消耗每日行写入额度。迁移格式时，Edge 会比较旧格式与当前格式的事件行数：单条利用索引的探测查询在确认复制成本更高时即停止；如果复制当前事件的成本更低，就把迁移后的压缩日志写入替代表，并在同一事务内交换表，避免为每个旧 token 片段支付逐行删除费用；否则只替换需要迁移的会话。已有当前格式日志会保留，迁移失败也会回滚表交换。这会降低迁移写入量，但不能保证所有数据库都满足 Free 计划每日 100,000 行写入额度；数据库足够大或当天已使用较多额度时，仍可能触及上限。时间点恢复恢复的是数据，不会恢复账户已经消耗的每日额度。
+
 ### 诊断 REST 路由
 
 - `PUT /api/workspace/file?path=/workspace/...` 写入 UTF-8 文件。