mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
refactor(schedule): keep reminder delivery conversational
This commit is contained in:
Tianyi Cui
@@ -20,7 +20,7 @@ This vocabulary is the foundation for interception decisions, the durable `hook/
|
||||
|
||||
**Three domains, one job each, with a single boundary rule.**
|
||||
|
||||
- **`session/*` — the durable, replayable FACT log and its checkpoint signals.** Owns `SessionEventMap`; every entry is JSON-only (no live objects). One `session/event` emit follows each append. The parallel `session/flush` checkpoint and contained `session/flushed` success observer are runtime signals rather than log entries; `session/flushed` carries the exclusive prefix proven durable by a listener's explicit acknowledgement. `session/event` is also the live transcript feed: a consumer that wants to render or react to what happened subscribes here, so live rendering and replay projections share one path.
|
||||
- **`session/*` — the durable, replayable FACT log.** Owns `SessionEventMap`; every entry is JSON-only (no live objects). One `session/event` emit per append, plus the `session/flush` parallel durability checkpoint. It is also the live transcript feed: a consumer that wants to render or react to what happened subscribes here, so live rendering and replay projections share one path.
|
||||
- **`agent/*` — the LIVE runtime surface.** Always carries the live `Agent`. Interception waterfalls (`agent/pre-step`, `agent/request`, `agent/request-error`) transform, reject, or recover; awaited `agent/turn-stopping` observes the stop boundary; transient emits report lifecycle, status, inbox insertion/claim/discard, and errors. Turn and step BOUNDARIES are NOT here — they are durable session events read off `session/event`, as are the token stream (`assistant/chunk`) and mid-turn steering (a `user/message`).
|
||||
- **`tools/*` — the tool registry and execution pipeline.**
|
||||
|
||||
|
||||
@@ -79,7 +79,7 @@ Cold resume cannot depend on an optional method of `SubagentRun`, because that r
|
||||
|
||||
The internal continuation manager's resume path loads the known child session, folds its descriptor, authorizes the persisted `parentSession`, and runs inside the Task it creates. It passes a fully resolved `SubagentProviderResumeRequest`, including the Task-owned cancellation signal, through a private service closure whose only responsibility is capability-checked provider dispatch and the ordinary run lifecycle observation used by `start`. The selected `SubagentProvider.resume?()` owns transport-specific reconstruction (in-process: `parent.ctx.agents.resume` under the currently loaded parent scope) and returns a fresh run. Presence of the provider method is the continuation capability, so no redundant capability flag exists. `SubagentService.followup()` chooses between the associated run's `steer?()` operation and this cold-resume path. Neither private provider dispatch nor a provider enumerates durable children or associates Tasks.
|
||||
|
||||
The background tool validates and snapshots descriptor inputs before calling `TaskService.start()`. A synchronous validation failure rejects the tool call and creates no Task. The tool otherwise returns the child and Task ids immediately, without waiting for child publication or descriptor durability. In-process continuable providers perform a final `SessionStore.flush()` after the child becomes idle and before reading the result; `true` confirms that at least one listener completed durability work, `false` is a required-checkpoint failure, and rejection carries a listener failure. This retries a failed loop checkpoint while the child is still live. If the final confirmation fails, the provider rejects instead of returning unconfirmed output, the continuation manager disposes the run, and the already-created Task settles as `failed` with the durability diagnosis in its detail. Cancellation during the confirmation owns the still-unpublished activation result, so a completed child turn or a later checkpoint failure cannot replace the Task's `killed` outcome. Foreground one-shot runs retain the loop's best-effort checkpoint behavior. In-process spawn and fork reconstruct composition under the currently loaded parent scope. A fork resume loads the child's own persisted transcript, which already contains the completed-turn prefix captured at initial creation; it never forks the parent's newer history again. Resuming a parent does not eagerly resume its children.
|
||||
The background tool validates and snapshots descriptor inputs before calling `TaskService.start()`. A synchronous validation failure rejects the tool call and creates no Task. The tool otherwise returns the child and Task ids immediately, without waiting for child publication or descriptor durability. In-process continuable providers perform a final `SessionStore.flush()` after the child becomes idle and before reading the result; `true` confirms at least one durability listener participated, `false` is a required-checkpoint failure, and rejection carries a listener failure. This retries a failed loop checkpoint while the child is still live. If the final confirmation fails, the provider rejects instead of returning unconfirmed output, the continuation manager disposes the run, and the already-created Task settles as `failed` with the durability diagnosis in its detail. Cancellation during the confirmation owns the still-unpublished activation result, so a completed child turn or a later checkpoint failure cannot replace the Task's `killed` outcome. Foreground one-shot runs retain the loop's best-effort checkpoint behavior. In-process spawn and fork reconstruct composition under the currently loaded parent scope. A fork resume loads the child's own persisted transcript, which already contains the completed-turn prefix captured at initial creation; it never forks the parent's newer history again. Resuming a parent does not eagerly resume its children.
|
||||
|
||||
TODO (ACP continuation): persist the remote ACP session id as provider-specific descriptor data and implement `AcpProvider.resume?()` as spawn, initialize, `loadSession`, then prompt. The initial ACP run must verify `initialize.agentCapabilities.loadSession`, and every resumed process must use the same durable backend; replayed history from `loadSession` must not be collected as the new activation's output. Because ACP load support is negotiated per child rather than established solely by the provider method's presence, this follow-up must also define how a start result advertises child-specific continuation before ACP children enter the durable catalog.
|
||||
|
||||
|
||||
@@ -79,7 +79,7 @@ durable child Session
|
||||
|
||||
内部继续执行管理器的恢复路径会加载已知 child 会话、归并其描述符、根据持久化的 `parentSession` 鉴权，并在其创建的 Task 内部运行。它通过私有服务闭包传递完全解析的 `SubagentProviderResumeRequest`，其中包含由 Task 持有的取消信号；该闭包只负责在检查提供方功能后进行分发，并执行 `start` 所使用的普通 run 生命周期观察。选中的 `SubagentProvider.resume?()` 负责传输相关的重建（进程内：在当前加载的 parent 作用域下执行 `parent.ctx.agents.resume`），并返回一个新 run。提供方是否存在该方法本身就是继续执行功能，无需额外功能标志。`SubagentService.followup()` 在关联 run 的 `steer?()` 操作与该持久化恢复路径之间做出选择。私有的提供方分发与提供方本身都不会枚举持久化 child 或关联 Task。
|
||||
|
||||
后台工具会在调用 `TaskService.start()` 前校验描述符输入并建立快照。同步校验失败会拒绝工具调用，且不会创建 Task。除此之外，工具会立即返回 child id 和 Task id，不等待 child 发布或描述符持久化完成。进程内可继续提供方会在 child 进入 idle 后、读取结果之前执行最终的 `SessionStore.flush()`；返回 `true` 表示至少一个 listener 已完成持久化工作，返回 `false` 表示必需的检查点失败，而拒绝则携带 listener 失败。此操作会在 child 仍存活时重试循环中失败的检查点。如果最终确认失败，提供方会拒绝而不返回未经确认的输出，继续执行管理器会 dispose 该 run，已经创建的 Task 会结算为 `failed`，其详情包含持久性诊断。最终确认期间发生取消时，尚未发布的激活结果由取消操作接管；即使 child 轮次已记录为完成，或之后的检查点失败，也不能取代 Task 的 `killed` 结果。前台一次性运行仍保留循环仅尽力执行检查点的行为。进程内 spawn 和 fork 会在当前已加载的 parent 作用域下重建组合配置。恢复 fork 时只加载 child 自己的持久化 transcript，其中已经包含初始创建时捕获的已完成轮次前缀；系统绝不会再次 fork parent 更新后的历史。恢复 parent 不会立即恢复其 child。
|
||||
后台工具会在调用 `TaskService.start()` 前校验描述符输入并建立快照。同步校验失败会拒绝工具调用，且不会创建 Task。除此之外，工具会立即返回 child id 和 Task id，不等待 child 发布或描述符持久化完成。进程内可继续提供方会在 child 进入 idle 后、读取结果之前执行最终的 `SessionStore.flush()`；返回 `true` 表示至少有一个持久性监听器参与，返回 `false` 表示必需的检查点失败，而拒绝则携带监听器失败。此操作会在 child 仍存活时重试循环中失败的检查点。如果最终确认失败，提供方会拒绝而不返回未经确认的输出，继续执行管理器会 dispose 该 run，已经创建的 Task 会结算为 `failed`，其详情包含持久性诊断。最终确认期间发生取消时，尚未发布的激活结果由取消操作接管；即使 child 轮次已记录为完成，或之后的检查点失败，也不能取代 Task 的 `killed` 结果。前台一次性运行仍保留循环仅尽力执行检查点的行为。进程内 spawn 和 fork 会在当前已加载的 parent 作用域下重建组合配置。恢复 fork 时只加载 child 自己的持久化 transcript，其中已经包含初始创建时捕获的已完成轮次前缀；系统绝不会再次 fork parent 更新后的历史。恢复 parent 不会立即恢复其 child。
|
||||
|
||||
TODO（ACP 继续执行）：将远端 ACP session id 作为提供方专用描述符数据持久化，并实现 `AcpProvider.resume?()`，依次执行 spawn、initialize、`loadSession` 和 prompt。初始 ACP run 必须检查 `initialize.agentCapabilities.loadSession`，恢复后的每个进程必须使用同一个持久化后端；`loadSession` 回放的历史消息不得计入新激活的输出。由于 ACP 的加载支持是按 child 协商的，不能仅根据提供方是否存在该方法来确定，因此该后续工作还必须定义 start 结果如何声明单个 child 支持继续执行，之后才能将 ACP child 写入持久化目录。
|
||||
|
||||
|
||||
@@ -103,7 +103,7 @@ Every Activation owns its `AgentHandle` and an `ownedChildren: Set<SessionId>`.
|
||||
|
||||
When the authenticated parent is itself a continuation-managed Activation, starting a child or submitting parent-originated work adds the child Session id to that parent's `ownedChildren` before the child can run or the message can enter its inbox. That parent cannot settle or dispose while this set is non-empty. A top-level or other non-continuation Agent has no Activation and does not join this waiting graph.
|
||||
|
||||
Child release occurs only after the child Agent is quiescent, every child of that child is disposed, the best-effort final session flush settles, and the child's `AgentHandle` completes disposal. The manager awaits `ctx.sessions.flush(child.session)` but does not require its durability-acknowledgement boolean: final lifecycle cleanup remains best-effort and cannot retain a child indefinitely when no backend acknowledges. A rejection is logged without preventing handle disposal or ownership release, because retaining a child would permanently pin its ancestors in `waiting`. If the child is owned, the manager then resolves the live parent through `SessionHeader.parentSession` and removes the child Session id from its `ownedChildren`. Manager teardown uses the same child-first order.
|
||||
Child release occurs only after the child Agent is quiescent, every child of that child is disposed, the best-effort final session flush settles, and the child's `AgentHandle` completes disposal. The manager awaits `ctx.sessions.flush(child.session)` but does not interpret its participation boolean: an arbitrary listener cannot prove that the selected persistence backend stored the state. A rejection is logged without preventing handle disposal or ownership release, because retaining a child would permanently pin its ancestors in `waiting`. If the child is owned, the manager then resolves the live parent through `SessionHeader.parentSession` and removes the child Session id from its `ownedChildren`. Manager teardown uses the same child-first order.
|
||||
|
||||
Ownership is retained until the child Activation is disposed. A later refinement may release a request-scoped lease earlier, but it would require an exact turn-completion correlation that this Task-free proposal deliberately does not add.
|
||||
|
||||
@@ -135,7 +135,7 @@ Without Tasks there is no `task_output`, `task_kill`, Task status, or per-messag
|
||||
|
||||
Host and manager teardown remains the lifecycle stop path. Manager unload applies it globally; a host applies it only below the exact top-level Agents it owns. Each form closes the applicable admission scope, stops the selected visible Activations, awaits admitted materializations in that scope, releases child-first, and preserves the durable Sessions.
|
||||
|
||||
Each turn requests the Session durability checkpoint, while final Activation settlement additionally awaits `ctx.sessions.flush()` as a best-effort barrier. The manager deliberately ignores the durability-acknowledgement boolean because lifecycle cleanup must still finish when no backend acknowledges. A rejection is logged without changing the lifecycle result or host-drain outcome; the manager still disposes the handle and releases ownership, and the persisted child state may be missing or stale on a later resume.
|
||||
Each turn requests the Session durability checkpoint, while final Activation settlement additionally awaits `ctx.sessions.flush()` as a best-effort barrier. The manager deliberately ignores the boolean result because listener participation cannot identify a persistence backend. A rejection is logged without changing the lifecycle result or host-drain outcome; the manager still disposes the handle and releases ownership, and the persisted child state may be missing or stale on a later resume.
|
||||
|
||||
Only messages written to the child Session log are reconstructable with the source that supplied them; inbox acceptance alone provides no restart guarantee.
|
||||
|
||||
@@ -191,7 +191,7 @@ The implementation pins these behaviors:
|
||||
- An idle Agent with live owned children yields a `waiting` Activation whose `AgentHandle` remains retained.
|
||||
- A `next-turn` delivered to `waiting` wakes the same Activation; delivery after completed disposal cold-resumes a new Activation.
|
||||
- Every continuation-managed parent Activation disposes only after all directly owned child Activations complete `AgentHandle` disposal; top-level Agents do not join the waiting graph.
|
||||
- Final Activation settlement awaits `ctx.sessions.flush(child.session)` as a best-effort barrier, ignores a missing durability acknowledgement and logs rejection, then disposes the child handle and releases parent ownership so a flush failure cannot leak a `waiting` Activation.
|
||||
- Final Activation settlement awaits `ctx.sessions.flush(child.session)` as a best-effort barrier, logs rejection without interpreting listener participation as durability proof, then disposes the child handle and releases parent ownership so a flush failure cannot leak a `waiting` Activation.
|
||||
- Manager teardown closes admission globally; a host owning selected top-level Agents instead closes admission only below their exact identities until those roots leave the registry. Both track admitted materializations by exact ancestry, install one memoized disposal cutoff per selected visible Activation, propagate cancellation top-down, release handles child-first, await every selected branch despite individual failures, and only then dispose the corresponding top-level Agents or manager scope.
|
||||
- The base lifecycle has no implicit report behavior; the optional report package contributes an explicit child-scoped tool through the setup hook.
|
||||
- Session logs reconstruct only messages that were actually written, with the source that supplied each message; inbox-accepted but unlogged messages have no restart guarantee.
|
||||
|
||||
@@ -103,7 +103,7 @@ Agent inbox 是唯一队列。每条继续执行消息都使用 `Agent.followup(
|
||||
|
||||
当经过身份认证的 parent 自身是由继续执行管理器管理的激活时，启动 child 或提交由 parent 发起的工作，会在 child 可以运行或消息可以进入其 inbox 前，将 child 会话 id 加入该 parent 的 `ownedChildren`。该集合非空时，这个 parent 不能结算或 dispose。顶层 Agent 或其他非继续执行 Agent 没有激活，也不会加入该等待图。
|
||||
|
||||
只有在 child Agent 完全停稳、该 child 持有的每个 child 都已 dispose、best-effort 的最终会话 flush 结算且 child 的 `AgentHandle` 完成 dispose 后，系统才释放 child。管理器会等待 `ctx.sessions.flush(child.session)`，但不要求其持久化确认布尔值：最终生命周期清理保持 best-effort，不能因为没有后端确认就无限保留 child。rejection 会被记录，但不会阻止 handle dispose 或释放所有权，因为保留 child 会让其祖先永久固定在 `waiting`。如果 child 归 parent 所有，管理器随后会通过 `SessionHeader.parentSession` 解析在线 parent，并从其 `ownedChildren` 中移除 child 会话 id。管理器拆卸使用相同的 child-first 顺序。
|
||||
只有在 child Agent 完全停稳、该 child 持有的每个 child 都已 dispose、best-effort 的最终会话 flush 结算且 child 的 `AgentHandle` 完成 dispose 后，系统才释放 child。管理器会等待 `ctx.sessions.flush(child.session)`，但不解释其参与布尔值：任意 listener 都无法证明所选持久化后端已存储该状态。rejection 会被记录，但不会阻止 handle dispose 或释放所有权，因为保留 child 会让其祖先永久固定在 `waiting`。如果 child 归 parent 所有，管理器随后会通过 `SessionHeader.parentSession` 解析在线 parent，并从其 `ownedChildren` 中移除 child 会话 id。管理器拆卸使用相同的 child-first 顺序。
|
||||
|
||||
系统会一直保留所有权，直至 child 激活完成 dispose。后续改进可以更早释放限定到请求的 lease，但这需要精确关联轮次完成，而本 Task-free 提案特意不增加该机制。
|
||||
|
||||
@@ -135,7 +135,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
|
||||
|
||||
宿主和管理器拆卸仍是生命周期停止路径。管理器卸载会全局应用它；宿主只会在自己确切拥有的顶层 Agent 之下应用它。两种形式都会关闭适用的准入作用域，停止选中的可见 Activation，等待该作用域中已获准的物化过程，按 child-first 顺序释放，并保留持久化 Session。
|
||||
|
||||
每个轮次都会请求执行会话持久性检查点，而 Activation 最终结算还会等待 `ctx.sessions.flush()`，将其作为 best-effort 屏障。管理器特意忽略持久化确认布尔值，因为没有后端确认时生命周期清理仍必须完成。rejection 会被记录，但不会改变生命周期结果或宿主 drain 的结果；管理器仍会 dispose handle 并释放所有权，后续恢复时持久化 child 状态可能缺失或陈旧。
|
||||
每个轮次都会请求执行会话持久性检查点，而 Activation 最终结算还会等待 `ctx.sessions.flush()`，将其作为 best-effort 屏障。管理器特意忽略布尔结果，因为 listener 是否参与无法标识持久化后端。rejection 会被记录，但不会改变生命周期结果或宿主 drain 的结果；管理器仍会 dispose handle 并释放所有权，后续恢复时持久化 child 状态可能缺失或陈旧。
|
||||
|
||||
只有实际写入 child 会话日志的消息，才能在重建时保留提供它的来源；仅被 inbox 接受并不提供重启保证。
|
||||
|
||||
@@ -191,7 +191,7 @@ activation-owner 作用域之所以存在，是因为普通 Cordis owner effect
|
||||
- 带有在线所持 child 的空闲 Agent 会产生 `waiting` 激活，其 `AgentHandle` 继续保留。
|
||||
- 向 `waiting` 投递 `next-turn` 会唤醒同一个激活；完成 dispose 后投递消息会冷恢复新激活。
|
||||
- 每个由继续执行管理器管理的 parent 激活只会在直接持有的所有 child 激活完成 `AgentHandle` dispose 后进行 dispose；顶层 Agent 不加入等待图。
|
||||
- Activation 最终结算会等待 `ctx.sessions.flush(child.session)`，将其作为 best-effort 屏障；它会忽略缺失的持久化确认并记录 rejection，然后 dispose child handle 并释放 parent 所有权，使 flush 失败不会泄漏 `waiting` Activation。
|
||||
- Activation 最终结算会等待 `ctx.sessions.flush(child.session)`，将其作为 best-effort 屏障；它会记录 rejection，但不会把 listener 参与解释为持久性证明，然后 dispose child handle 并释放 parent 所有权，使 flush 失败不会泄漏 `waiting` Activation。
|
||||
- 管理器拆卸会全局关闭准入；拥有选定顶层 Agent 的宿主则只关闭这些确切身份之下的准入，直到这些根离开注册表。两者都会按确切祖先关系跟踪已获准的物化过程，为每个选中的可见 Activation 安装一个记忆化 dispose 截止点，自顶向下传播取消，按 child-first 顺序释放 handle，即使个别分支失败也会等待所有选中分支，之后才 dispose 对应的顶层 Agent 或管理器作用域。
|
||||
- 基础生命周期不暴露隐式报告行为；可选的 report 包通过 setup 钩子贡献一个显式的 child 作用域工具。
|
||||
- 会话日志只会重建实际写入的消息，并保留每条消息的提供来源；已被 inbox 接受但未写入日志的消息没有重启保证。
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-05-durable-web-schedule.md
|
||||
2026-08-05-durable-web-schedule.md: b27ac93e0dcd191ac7242bf6754a1d1bec456647
|
||||
2026-08-05-durable-web-schedule.zh.md: eba6ea9b62e6b4e384b35277fbb323cc8340b6bd
|
||||
2026-08-05-durable-web-schedule.md: 9229ff33873252ffaf13b44ccd403b12fbd656d6
|
||||
2026-08-05-durable-web-schedule.zh.md: d4050ca8295c211f9454492e5203c8ed64c368c2
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Agent Note: Durable Session-local Web reminders
|
||||
# Agent Note: Durable Session-local reminders
|
||||
|
||||
Status: implemented
|
||||
|
||||
@@ -6,22 +6,22 @@ English | [中文](2026-08-05-durable-web-schedule.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
A reminder created inside a conversation needs to survive a process restart and remain attributable to that exact Session. A process-local timer or model inbox item cannot provide that durability, while a global scheduler or private database would introduce a second identity, persistence, and lifecycle system. The user also needs a visible receipt even when the best-effort model turn later fails, without seeing a reminder whose dispatch never reached storage.
|
||||
A reminder created inside a conversation must remain attributable to that exact Session and survive a process restart. A process-local timer or inbox item cannot provide that durability, while a global scheduler or private database introduces a second identity, persistence, and lifecycle system.
|
||||
|
||||
Busy Agents, long waits, wall-clock changes, cold Sessions, forks, persistence failures, and browser history races make a simple timeout insufficient. The design must distinguish a durable record from its disposable live wait, keep a fork from inheriting its parent's active reminders, and merge a presentation sidecar that can arrive after the underlying event.
|
||||
Busy Agents, long waits, wall-clock changes, cold Sessions, forks, persistence failures, and teardown make a simple timeout insufficient. The design must distinguish a durable record from its disposable live wait and keep a fork from inheriting its parent's active reminders.
|
||||
|
||||
## Decision
|
||||
|
||||
The [`examples/web-schedule`](../../../../examples/web-schedule/README.md) overlay explicitly loads `@deepseek-ai/dsh-tool-schedule` and the separate `@deepseek-ai/dsh-client-ui-schedule` renderer. The default Web tree remains unchanged. Schedule observes only root Agents published after the plugin loads and installs its three tools plus one disposable owner in that Agent scope. Cold history reads, already-published roots, child Agents, and other hosts do not activate it.
|
||||
The [`examples/web-schedule`](../../../../examples/web-schedule/README.md) overlay explicitly loads `@deepseek-ai/dsh-tool-schedule`; the default Web tree remains unchanged. Schedule observes only root Agents published after the plugin loads and installs its three tools plus one disposable owner in that Agent scope. Cold history reads, already-published roots, child Agents, and other hosts do not activate it.
|
||||
|
||||
The user-visible boundary is `session-local`: the original Session runs an on-time reminder only while it is live, does no external notification while cold, and processes an overdue reminder after that Session becomes live again.
|
||||
The user-visible boundary is `session-local`: the original Session runs an on-time reminder only while it is live, does no external notification while cold, and processes an overdue reminder after that Session becomes live again. Due work waits until the Agent is fully idle, then enters the ordinary next-turn queue through `followup()`; it never steers the current turn. The separate Web receipt portion of the original design is superseded by [conversational Schedule delivery](../simplification/2026-08-09-conversational-schedule-delivery.md).
|
||||
|
||||
| Scenario | Durable fact | Live behavior | User-visible result |
|
||||
| --- | --- | --- | --- |
|
||||
| Create and manage | `schedule/change` create/delete events in the original Session | Agent-scoped tools checkpoint before reading and after mutations | Stable id, UTC target, `scheduled`/`overdue`, and `session-local` disclosure |
|
||||
| Due while busy | Active create remains in the fold | Owner waits for `whenIdle()`, claims idle maintenance, queues one followup, then appends dispatch | One replayable reminder receipt; model failure does not retract it |
|
||||
| Due while busy | Active create remains in the fold | Owner waits for `whenIdle()`, claims idle maintenance, queues one follow-up, then appends dispatch | A later ordinary conversation turn |
|
||||
| Process stopped or Session cold | Active create remains in persistence | No timer or background scan exists; resume rebuilds the owner | Future target waits again; overdue target is attempted once |
|
||||
| Fork | Parent events remain in the inherited prefix | Child fold starts at `seedLength` | Parent receipt may appear in history, but no parent reminder becomes active child work |
|
||||
| Fork | Parent events remain in the inherited prefix | Child fold starts at `seedLength` | No parent reminder becomes active child work |
|
||||
|
||||
### Session log authority and tools
|
||||
|
||||
@@ -29,72 +29,38 @@ The version-1 `schedule/change` stream is the only durable Schedule authority. A
|
||||
|
||||
The current rule accepts a non-empty prompt and exactly one positive safe-integer `after_seconds`. Its record is `{ id, kind: 'after', prompt, afterSeconds, scheduledAt }`; dispatch stores only the id because the record already fixes its occurrence. `at`, `every_seconds`, `cron`, and `time_zone` are rejected rather than hidden in unused fields. Tool values derive `scheduled` or `overdue` and always include `deliveryMode: 'session-local'`.
|
||||
|
||||
An Agent-scoped FIFO serializes each accepted management transaction and the live owner's due transaction from preflight through any post-append barrier. Every tool operation that reads or decides from the fold first awaits `ctx.sessions.flush(session)`. Create may reject input-shape failures before entering the FIFO; after a successful preflight it allocates an id, appends create, and waits for a second barrier. Delete validates its id before the FIFO, then preflights before deciding whether the id is active and waits for a second barrier only when it appends. List and unknown or finished delete never answer from an unconfirmed live suffix or observe a dispatch before its own barrier. A failed barrier returns `persistence_uncertain` rather than guessing whether an eager write committed.
|
||||
An Agent-scoped FIFO serializes each accepted management transaction and the live owner's due transaction from preflight through any post-append barrier. Every tool operation that reads or decides from the fold first awaits `ctx.sessions.flush(session)`. Create may reject input-shape failures before entering the FIFO; after a successful preflight it allocates an id, appends create, and waits for a second barrier. Delete validates its id before the FIFO, then preflights before deciding whether an id is active and waits for a second barrier only when it appends. List and unknown or finished delete never answer from an unconfirmed live suffix or observe a dispatch before their own barrier. A failed barrier returns `persistence_uncertain` rather than guessing whether an eager write committed.
|
||||
|
||||
Every successful management preflight also asks the live owner to recompute. This closes the recovery path where create appended successfully but its post-append barrier rejected: a later list can confirm the coordinator's retained batch, return the active record, and arm its timer without a Schedule-specific retry loop.
|
||||
|
||||
### Persistence checkpoint and initialization recovery
|
||||
|
||||
`SessionStore.flush()` awaits every scoped listener and treats literal `true` as an explicit durability acknowledgement. An acknowledged call publishes a contained `session/flushed(session, throughSeq)` observation whose exclusive boundary was captured at call entry; append notification itself is not durability evidence. Observe-only listeners return void, an empty or observe-only checkpoint returns `false`, and any listener rejection prevents the success observation after all listeners settle.
|
||||
|
||||
The persistence coordinator supplies that acknowledgement only after its write path is quiescent. Its live controller retains the initial `seedEnd` scalar rather than a seed copy. If the first initialization rejects, a later flush rebuilds that immutable prefix from the append-only Session, reads the backend's actual cursor, and appends only a missing suffix. This covers failures before storage changed and failures reported after a commit, so one transient error neither permanently poisons the Session nor duplicates its prefix.
|
||||
Every successful management preflight also asks the live owner to recompute. This closes the recovery path where create appended successfully but its post-append barrier rejected: a later list can confirm the retained batch, return the active record, and arm its timer without a Schedule-specific retry loop.
|
||||
|
||||
### Live delivery lifecycle
|
||||
|
||||
The Agent-scoped owner derives its earliest target from the durable fold. Long targets use bounded timer segments, and every wake reads the wall clock again, so a rollback cannot fire early and a forward jump becomes overdue. If a turn or another maintenance task already owns the Agent, `runMaintenance()` rejects the claim; the record stays active and one `whenIdle()` wait triggers a later retry. A rejected persistence preflight or contained framing/synchronous-enqueue failure also leaves the record active, but no private retry timer runs; later Agent activity reaching idle or a successful Schedule management preflight asks the owner to try again.
|
||||
The Agent-scoped owner derives its earliest target from the durable fold. Long targets use bounded timer segments, and every wake reads the wall clock again, so a rollback cannot fire early and a forward jump becomes overdue. If a turn or another maintenance task already owns the Agent, `runMaintenance()` rejects the claim; the record stays active and one `whenIdle()` wait triggers a later retry. A rejected persistence preflight or contained framing or synchronous-enqueue failure also leaves the record active, but no private retry timer runs; later Agent activity reaching idle or a successful Schedule management preflight asks the owner to try again.
|
||||
|
||||
The accepted path first clears pending persistence and claims the true idle phase through `runMaintenance()`. Inside that task it refolds the exact Session suffix so a direct management mutation that won the claim race cannot be followed by a stale dispatch, samples the decision clock once, constructs the complete fixed reminder frame with JSON-escaped id and prompt, synchronously queues one `followup()`, and appends the id-only dispatch. Waking input remains parked until maintenance settles, so the driver cannot claim the message before dispatch enters the log; only after the task releases the phase does the owner wait for the dispatch barrier. A framing or synchronous enqueue failure is contained and appends no dispatch. An append failure faults that owner because the message may already be queued. A later prompt-admission, request-checkpoint, or model failure cannot retract a dispatch.
|
||||
The accepted path first clears pending persistence and claims the idle phase through `runMaintenance()`. Inside that task it refolds the exact Session suffix, samples the decision clock once, constructs the complete fixed reminder frame with JSON-escaped id and prompt, synchronously queues one `followup()`, and appends the id-only dispatch. Waking input remains parked until maintenance settles, so the driver cannot claim the message before dispatch enters the log; only after the task releases the phase does the owner wait for the dispatch barrier.
|
||||
|
||||
Agent or plugin disposal cancels timers, stops new work, unwinds the three tool registrations, and waits for in-flight preflights or idle waits. It never deletes durable records during teardown. The narrow crash interval after synchronous followup admission and before durable dispatch may repeat the reminder after recovery; the design prefers a visible duplicate over silent loss and makes no model-success, user-read, external-effect, or exactly-once promise.
|
||||
|
||||
### Commit-aware Web receipt
|
||||
|
||||
The Schedule package owns `scheduleReminderPresentation()`, which derives `{ scheduleId, prompt, occurrenceAt }` from create plus dispatch; the client renderer adds the fixed `session-local` label. The current fork's `seedLength` is a hard boundary for child-owned dispatches. An inherited dispatch instead pairs with its nearest preceding same-id create because `session/end-seed` also marks replay or resume construction, not only fork ownership. This keeps resumed ancestor receipts renderable, preserves nested-generation id reuse, and never changes live ownership.
|
||||
|
||||
The Host continues to send every raw event on append. It keeps one monotonic watermark per exact live `Session` in a `WeakMap`; only `session/flushed` advancement makes it redeliver newly covered dispatch events with the generic `{ for: 'event', view }` sidecar. The durable `schedule/change` type selects the client renderer. Taking the maximum contains reversed concurrent flush completion, and exact object identity prevents a reused Session id from inheriting another lifecycle's cursor.
|
||||
|
||||
Attached history independently inspects persistence and adds views only to a stored event prefix whose header identity and every event match the live Session. Persistence canonically writes absent top-level `delegationDepth` as zero, so those two forms are identity-equivalent; cwd, lineage, origin, timestamps, version, id, and every event still match exactly. Missing, failed, divergent, or longer inspection withholds the view while returning raw history. Detached history is already a persisted prefix. A parent dispatch copied into a fork seed therefore appears in child history only after child storage proves that prefix.
|
||||
|
||||
The browser Session accepts a repeated seq only when the durable event is deeply identical, then upgrades the sidecar immediately without appending another event. Tail loading and true gap repair retain uncovered events in the existing `liveBuffer`; an accepted repair snapshot starts another pull when it advanced the tail but left a later buffered gap, while an identity conflict triggers a full resync. Ordinary older-page pagination keeps receiving live tail events in the current arrays, while a sidecar below the current window stays with the in-flight page and attaches only when that page returns the identical event. Reconnect generations prevent stale page or repair results and `finally` blocks from touching the rebuilt window. `TranscriptAdapter` creates a generic `PresentedEventNode` keyed by the durable event type. `ui-conversation` dispatches it through `conversation.chat.eventview` and retains an expandable JSON fallback, while `ui-schedule` owns the bilingual `schedule/change` reminder row.
|
||||
|
||||
```text
|
||||
schedule_create → Session create event → persistence
|
||||
↓ live owner
|
||||
due → admission → followup → dispatch → flush(true) → session/flushed
|
||||
↓
|
||||
Host late event sidecar
|
||||
↓
|
||||
client same-seq upgrade → event-keyed UI receipt
|
||||
```
|
||||
Dispatch records queue admission, not model completion or user receipt. A framing or synchronous enqueue failure appends no dispatch. An append failure faults that owner because the message may already be queued. A later prompt-admission, request-checkpoint, or model failure cannot retract a dispatch. Agent or plugin disposal cancels timers, stops new work, unwinds the three tool registrations, and waits for in-flight preflights or idle waits without deleting durable records.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Use `ctx.tasks`.** Tasks own process-local work, terminal outcomes, collection, and notifications rather than Session-log state and replayable conversation receipts. Reusing them would make the wrong lifecycle authoritative.
|
||||
**Use `ctx.tasks`.** Tasks own process-local work, terminal outcomes, collection, and notifications rather than Session-log state and conversation follow-ups. Reusing them would make the wrong lifecycle authoritative.
|
||||
|
||||
**Store reminders in a private SQLite table or global scheduler.** This could run cold Sessions, but requires a second Session identity map, startup scan, ownership lease, crash protocol, and notification policy. The accepted scope deliberately runs only while the original Session is live.
|
||||
|
||||
**Claim dispatch before `followup()` or add exactly-once fencing.** A claim-first record can silently lose the user-visible reminder when enqueue fails. Cross-process exactly-once requires a lease, outbox, acknowledgement, and downstream idempotency boundary that Session-local best-effort model work does not provide.
|
||||
|
||||
**Treat the model message as the receipt.** The queued inbox item is process-local and may fail before a durable user message exists. A dispatch-derived Web receipt remains visible and replayable independently of model success.
|
||||
|
||||
**Attach the reminder view on append.** `session/event` precedes the durability result, so this would display a ghost receipt after a rejected flush. The success watermark makes presentation follow the commit point.
|
||||
|
||||
**Add a Schedule-specific wire frame, client cache, or management page.** The generic event sidecar, existing Session window buffer, keyed slot, and model-facing tools already carry the required result. A parallel transport or state store would duplicate identity and replay logic.
|
||||
|
||||
**Adopt existing roots or register global tools.** Late adoption makes plugin load order change which unseen timers begin running and exposes tools outside the supported root-Agent composition. Future-root, Agent-scoped installation gives one clear lifecycle.
|
||||
|
||||
The design does not recognize or migrate any unmerged Schedule implementation or private storage format. No fixed Session id, claim-before-send record, startup miss, or private database is a compatibility input.
|
||||
|
||||
## Verification
|
||||
|
||||
Package tests pin strict decoding, transitions, fork suffixes, id reuse, time bounds, bounded waits, wall-clock movement, overdue admission, fixed framing, enqueue and append failures, barrier recovery, registration rollback, and quiescent disposal at 100% per-file coverage. Persistence tests cover new, fork, and resumed initialization failures against the actual durable cursor. The assembled Loader/Web restart lane proves pending recovery, fork isolation, one durable dispatch, cold-history rendering without Agent activation, and no redelivery after another restart. Host/client tests cover commit gating, reversed watermarks, semantic header identity, per-event prefix matching, immediate same-seq upgrades, concurrent live-tail pagination, true gaps, and reconnect generations.
|
||||
|
||||
The opt-in Loader composition boots the source and built packages. A keyless real-browser scenario executes `schedule_create` through the complete tool pipeline, waits for a one-second dispatch, observes the identity-matched persisted prefix, and renders the durable reminder card from attached history. The deliberately absent model adapter closes the turn with an error after dispatch, proving that model failure does not remove the receipt.
|
||||
Package tests pin strict decoding, transitions, fork suffixes, id reuse, time bounds, bounded waits, wall-clock movement, overdue admission, fixed framing, enqueue and append failures, barrier recovery, registration rollback, and quiescent disposal. A production-JSONL restart test resumes one overdue record through the real Agent lifecycle and proves that a later restart does not dispatch it again. The opt-in Loader composition boots the package, and a keyless browser scenario executes `schedule_create` through the complete tool pipeline and snapshots the ordinary assistant follow-up.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Reminder state survives process restart and replays through ordinary Session persistence without a new database or public service.
|
||||
- A cold Session does no work and sends no external notification; reopening it may deliver an overdue reminder, and every tool/card says `session-local`.
|
||||
- Each live root adds only fold-derived timers, an optional idle wait, and one in-flight operation. Long waits and plugin unload do not create a second durable state machine.
|
||||
- The generic commit-aware event-view path is reusable by other durable events, but it adds event-identity checks and request-generation fencing to the client Session window.
|
||||
- A cold Session does no work and sends no external notification; reopening it may deliver an overdue reminder.
|
||||
- Each live root adds only fold-derived timers, an optional idle wait, and one in-flight operation.
|
||||
- The narrow crash interval after synchronous follow-up admission and before durable dispatch can repeat the reminder after recovery; the design prefers a visible duplicate over silent loss and makes no exactly-once promise.
|
||||
- The strict after-only protocol is intentionally small; other rule families require explicit record, time, and recurrence semantics rather than dormant fields.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Agent Note: 持久、仅限 Session 内的 Web 提醒
|
||||
# Agent Note: 持久、仅限 Session 内的提醒
|
||||
|
||||
Status: implemented
|
||||
|
||||
@@ -6,22 +6,22 @@ Status: implemented
|
||||
|
||||
## 问题
|
||||
|
||||
在对话中创建的提醒需要跨进程重启存活，并始终归属于确切的原 Session。进程内 timer 或模型 inbox 项无法提供这种持久性，而全局 scheduler 或私有数据库又会引入第二套身份、持久化和生命周期系统。即使后续 best-effort 模型轮次失败，用户仍需要看到回执；但 dispatch 尚未到达存储的提醒绝不能提前显示。
|
||||
在对话中创建的提醒必须始终归属于确切的原 Session，并跨进程重启存活。进程内 timer 或 inbox 项无法提供这种持久性，而全局 scheduler 或私有数据库会引入第二套身份、持久化和生命周期系统。
|
||||
|
||||
繁忙的 Agent、长等待、墙钟变化、cold Session、fork、持久化失败和浏览器 history 竞态，使简单 timeout 无法满足要求。设计必须区分持久 record 与可丢弃的 live wait，阻止 fork 继承父 Session 的活动提醒，并合并可能晚于原始 event 到达的 presentation sidecar。
|
||||
繁忙的 Agent、长等待、墙钟变化、cold Session、fork、持久化失败和 teardown，使简单 timeout 无法满足要求。设计必须区分持久 record 与可丢弃的 live wait，并阻止 fork 继承父 Session 的活动提醒。
|
||||
|
||||
## 决策
|
||||
|
||||
[`examples/web-schedule`](../../../../examples/web-schedule/README.md) overlay 显式加载 `@deepseek-ai/dsh-tool-schedule` 与独立 renderer `@deepseek-ai/dsh-client-ui-schedule`。默认 Web 配置树保持不变。Schedule 只观察插件加载后发布的根 Agent，并在该 Agent scope 中安装三个工具和一个可丢弃 owner。cold history 读取、已发布的根、child Agent 与其他宿主都不会激活它。
|
||||
[`examples/web-schedule`](../../../../examples/web-schedule/README.md) overlay 显式加载 `@deepseek-ai/dsh-tool-schedule`；默认 Web 配置树保持不变。Schedule 只观察插件加载后发布的根 Agent，并在该 Agent scope 中安装三个工具和一个可丢弃 owner。cold history 读取、已发布的根、child Agent 与其他宿主都不会激活它。
|
||||
|
||||
用户可见边界固定为 `session-local`：原 Session 只有在 live 时才会准点运行提醒，cold 期间不发送任何外部通知；该 Session 再次 live 后才会处理 overdue 提醒。
|
||||
用户可见边界固定为 `session-local`：原 Session 只有在 live 时才会准点运行提醒，cold 期间不发送任何外部通知；该 Session 再次 live 后才会处理 overdue 提醒。到期工作会等待 Agent 完全 idle，再通过 `followup()` 进入普通的下一轮队列；它绝不会中途引导当前轮次。原设计中独立 Web 回执的部分已由[对话式 Schedule 交付](../simplification/2026-08-09-conversational-schedule-delivery.md)取代。
|
||||
|
||||
| 场景 | 持久事实 | live 行为 | 用户可见结果 |
|
||||
| --- | --- | --- | --- |
|
||||
| 创建与管理 | 原 Session 中的 `schedule/change` create／delete event | Agent-scoped 工具在读取前、变更后执行 checkpoint | 稳定 id、UTC 目标、`scheduled`／`overdue` 与 `session-local` 说明 |
|
||||
| 到期时繁忙 | 活动 create 仍在 fold 中 | owner 等待 `whenIdle()`、认领 idle maintenance、排入一次 followup，再追加 dispatch | 一条可回放提醒回执；模型失败不会撤回它 |
|
||||
| 到期时繁忙 | 活动 create 仍在 fold 中 | owner 等待 `whenIdle()`、认领 idle maintenance、排入一次 follow-up，再追加 dispatch | 稍后的普通对话轮次 |
|
||||
| 进程停止或 Session cold | 活动 create 仍在 persistence 中 | 不存在 timer 或后台扫描；resume 重建 owner | 未来目标继续等待；overdue 目标尝试一次 |
|
||||
| fork | 父 event 留在继承前缀 | child fold 从 `seedLength` 开始 | history 可显示父回执，但父提醒不会成为 child 活动工作 |
|
||||
| fork | 父 event 留在继承前缀 | child fold 从 `seedLength` 开始 | 父提醒不会成为 child 活动工作 |
|
||||
|
||||
### Session 日志权威与工具
|
||||
|
||||
@@ -31,70 +31,36 @@ Status: implemented
|
||||
|
||||
一个 Agent-scoped FIFO 会将每项已接纳的管理事务与 live owner 的到期事务从 preflight 到任何 post-append barrier 全程串行化。每项从 fold 读取或作出判断的工具操作都会先等待 `ctx.sessions.flush(session)`。create 可以在进入 FIFO 前拒绝只依赖输入 shape 的失败；preflight 成功后才分配 id、追加 create，并等待第二个 barrier。delete 在进入 FIFO 前验证其 id，随后在判断 id 是否活动前先 preflight，只有实际追加时才等待第二个 barrier。list 与未知或已终结 delete 绝不会从未确认的 live 后缀作答，也不会在自身的 barrier 前观察到 dispatch。barrier 失败会返回 `persistence_uncertain`，而不是猜测 eager write 是否已经提交。
|
||||
|
||||
每次成功的管理 preflight 也会要求 live owner 重新计算。这闭合了 create 已成功追加、但 post-append barrier 拒绝时的恢复路径：后续 list 可以确认 coordinator 保留的 batch、返回活动 record，并在没有 Schedule 私有重试循环的情况下 arm timer。
|
||||
|
||||
### Persistence checkpoint 与初始化恢复
|
||||
|
||||
`SessionStore.flush()` 会等待所有 scoped listener，并把字面量 `true` 视为显式 durability acknowledgement。获得确认的调用会发布受包含的 `session/flushed(session, throughSeq)` observation；其中排他边界在调用入口捕获，append 通知本身不是 durability 证据。仅观察 listener 返回 void；空或只有观察者的 checkpoint 返回 `false`；任一 listener 拒绝都会在全部结算后阻止成功 observation。
|
||||
|
||||
persistence coordinator 只有在写路径完全停稳后才给出该确认。live controller 只保留初始 `seedEnd` 标量，不复制 seed。首次初始化拒绝后，后续 flush 会从仅追加 Session 重建该不可变前缀、读取后端实际 cursor，并只追加缺失 suffix。无论失败发生在存储变更前，还是提交后才返回拒绝，一次暂时性错误都不会永久毒化 Session 或重复写入其前缀。
|
||||
每次成功的管理 preflight 也会要求 live owner 重新计算。这闭合了 create 已成功追加、但 post-append barrier 拒绝时的恢复路径：后续 list 可以确认保留的 batch、返回活动 record，并在没有 Schedule 私有重试循环的情况下 arm timer。
|
||||
|
||||
### Live 交付生命周期
|
||||
|
||||
Agent-scoped owner 从持久 fold 派生最早目标。超长目标使用有界 timer 分段，每次 wake 都重新读取墙钟，因此回拨不会提前触发，前跳则会形成 overdue。如果 agent 已被某个轮次或另一项 maintenance task 占用，`runMaintenance()` 会拒绝此次认领；record 保持活动，并由一个 `whenIdle()` wait 触发稍后的重试。被拒绝的 persistence preflight 或被收容的 framing／同步入队失败同样会让 record 保持活动，但不会运行私有重试 timer；后续 agent 活动进入 idle，或成功的 Schedule 管理 preflight 会要求 owner 再次尝试。
|
||||
|
||||
获得准入的路径会先清空 pending persistence，并通过 `runMaintenance()` 认领真正的 idle phase。该任务会重新折叠确切的 Session 后缀，从而确保在认领竞态中胜出的直接管理变更之后不会跟随陈旧 dispatch；随后只采样一次 decision clock，使用 JSON-escaped id 与 prompt 构造完整固定 reminder frame，同步排入一次 `followup()`，再追加只含 id 的 dispatch。触发唤醒的 input 会保持 parked，直到 maintenance 结束，因此 driver 无法在 dispatch 进入 log 前认领消息；只有该任务释放 phase 后，owner 才会等待 dispatch barrier。framing 或同步入队失败会被收容，且不会追加 dispatch。append 失败会使该 owner fault，因为消息可能已经入队。后续 prompt admission、request checkpoint 或模型失败都不能撤回 dispatch。
|
||||
获得准入的路径会先清空 pending persistence，并通过 `runMaintenance()` 认领 idle phase。该任务会重新折叠确切的 Session 后缀，只采样一次 decision clock，使用 JSON-escaped id 与 prompt 构造完整固定 reminder frame，同步排入一次 `followup()`，再追加只含 id 的 dispatch。触发唤醒的 input 会保持 parked，直到 maintenance 结束，因此 driver 无法在 dispatch 进入 log 前认领消息；只有该任务释放 phase 后，owner 才会等待 dispatch barrier。
|
||||
|
||||
Agent 或插件 dispose 会取消 timer、停止新工作、撤销三个工具注册，并等待进行中的 preflight 或 idle wait。teardown 绝不会删除持久 record。同步 followup 获得准入后、durable dispatch 前的狭窄崩溃窗口可能在恢复后重复提醒；本设计选择可见重复而非静默丢失，不承诺模型成功、用户阅读、外部副作用或 exactly-once。
|
||||
|
||||
### Commit-aware Web 回执
|
||||
|
||||
Schedule package 拥有 `scheduleReminderPresentation()`，从 create 加 dispatch 派生 `{ scheduleId, prompt, occurrenceAt }`。client renderer 会添加固定的 `session-local` 标签。当前 fork 的 `seedLength` 是 child 自有 dispatch 的硬边界。继承的 dispatch 则会与它之前最近的同 id create 配对，因为 `session/end-seed` 也会标记回放或恢复构造，而不仅标记 fork 所有权。这使恢复后的祖先回执仍可渲染，保留嵌套 generation 的 id 复用，并且绝不会改变 live ownership。
|
||||
|
||||
Host 在 append 时继续发送所有 raw event。它在 `WeakMap` 中按 exact live `Session` 保存一个单调 watermark；只有 `session/flushed` 前进时，才会用通用 `{ for: 'event', view }` sidecar 重投新覆盖的 dispatch event。持久 `schedule/change` 类型用于选择 client renderer。取最大值可以收容反序完成的并发 flush，按对象身份键控则阻止复用的 Session id 继承另一个生命周期的 cursor。
|
||||
|
||||
已附加 history 会独立 inspect persistence，只有 stored event prefix 的 header identity 与每个 event 都和 live Session 匹配时才添加 view。persistence 会把顶层缺失的 `delegationDepth` 规范写成零，因此两种形式在身份上等价；cwd、lineage、origin、时间戳、版本、id 与每个 event 仍必须精确匹配。inspect 缺失、失败、分歧或比 live 更长时，只会省略 view，raw history 仍然返回。已分离 history 本身就是持久前缀。因此复制进 fork seed 的 parent dispatch 只有在 child storage 证明该前缀后才会显示。
|
||||
|
||||
浏览器 Session 只有在 durable event 深度一致时才接受重复 seq，随后立即升级 sidecar，不再追加 event。只有尾部加载与真正的 gap repair 才会将尚未覆盖的事件保留在既有 `liveBuffer` 中；已接受的 repair 快照在推进 tail 但仍留下后续已缓冲的 gap 时会启动另一次 pull，身份冲突则会触发全量重新同步。普通旧页分页会让当前数组继续接收 live tail 事件，当前 window 以下的 sidecar 则由 in-flight page 自身暂存，只有该页返回身份完全相同的事件时才附着。重连 generation 会阻止陈旧的 page 或 repair 结果以及 `finally` 块触碰重建后的 window。`TranscriptAdapter` 创建按持久事件类型键控的通用 `PresentedEventNode`。`ui-conversation` 通过 `conversation.chat.eventview` 分发，并保留可展开 JSON fallback；`ui-schedule` 则拥有双语 `schedule/change` 提醒行。
|
||||
|
||||
```text
|
||||
schedule_create → Session create event → persistence
|
||||
↓ live owner
|
||||
due → admission → followup → dispatch → flush(true) → session/flushed
|
||||
↓
|
||||
Host late event sidecar
|
||||
↓
|
||||
client same-seq upgrade → event-keyed UI receipt
|
||||
```
|
||||
dispatch 记录的是队列准入，而不是模型完成或用户收到提醒。framing 构造或同步入队失败不会追加 dispatch。append 失败会使该 owner fault，因为消息可能已经入队。后续 prompt admission、request checkpoint 或模型失败都不能撤回 dispatch。Agent 或插件 dispose 会取消 timer、停止新工作、撤销三个工具注册，并等待进行中的 preflight 或 idle wait，且不会删除持久 record。
|
||||
|
||||
## 已考虑的替代方案
|
||||
|
||||
**使用 `ctx.tasks`。** Task 拥有进程内工作、终态结果、收集与通知语义，而不是 Session 日志状态和可回放会话回执。复用它会让错误的生命周期成为权威。
|
||||
**使用 `ctx.tasks`。** Task 拥有进程内工作、终态结果、收集与通知语义，而不是 Session 日志状态和对话 follow-up。复用它会让错误的生命周期成为权威。
|
||||
|
||||
**把提醒存入私有 SQLite 表或全局 scheduler。** 这样可以运行 cold Session，却必须增加第二套 Session 身份映射、startup 扫描、ownership lease、崩溃协议与通知政策。当前范围有意只在原 Session live 时运行。
|
||||
|
||||
**在 `followup()` 前 claim dispatch，或增加 exactly-once fencing。** claim-first record 会在入队失败时静默丢失用户可见提醒。跨进程 exactly-once 需要 lease、outbox、acknowledgement 与下游幂等边界，而 Session-local best-effort 模型工作不具备这些边界。
|
||||
|
||||
**把模型消息当作回执。** 已排队 inbox 项是进程内状态，可能在产生持久 user message 前失败。从 dispatch 派生的 Web 回执不依赖模型成功，仍然可见、可回放。
|
||||
|
||||
**在 append 时附加提醒 view。** `session/event` 早于 durability 结果；这样会在 flush 拒绝后显示幽灵回执。成功 watermark 让 presentation 服从提交点。
|
||||
|
||||
**增加 Schedule 专属 wire frame、client cache 或管理页面。** 通用 event sidecar、既有 Session window buffer、键控 slot 与面向模型工具已经能承载所需结果。平行 transport 或状态 store 会重复身份与回放逻辑。
|
||||
|
||||
**接管既有根或注册全局工具。** 晚接管会让插件加载顺序改变哪些不可见 timer 开始运行，并把工具暴露到支持范围之外。只面向未来根、按 Agent scope 安装，提供了单一明确生命周期。
|
||||
|
||||
本设计不会识别或迁移任何未合入的 Schedule 实现或私有存储格式。固定 Session id、claim-before-send record、startup miss 与私有数据库都不是兼容输入。
|
||||
|
||||
## 验证
|
||||
|
||||
package 测试以逐文件 100% coverage 固定严格 decoding、transition、fork suffix、id 不复用、时间边界、有界等待、墙钟变化、overdue 准入、固定 framing、入队与 append 失败、barrier 恢复、注册 rollback 和完全停稳 dispose。persistence 测试依据实际 durable cursor 覆盖 new、fork 与 resumed 初始化失败。组装后的 Loader/Web restart lane 证明 pending 恢复、fork 隔离、单次 durable dispatch、无需激活 agent 的 cold-history rendering，以及再次 restart 后不重投。Host/client 测试覆盖 commit gating、反序 watermark、语义 header identity、逐 event 前缀匹配、same-seq 立即升级、并发 live-tail 分页、真正的 gap 和 reconnect generation。
|
||||
|
||||
显式 Loader 组合可以启动 source 与 built package。无密钥真实浏览器场景会通过完整工具 pipeline 执行 `schedule_create`、等待一秒 dispatch、观察 identity-matched 持久前缀，并从已附加 history 渲染 durable reminder card。刻意缺少的模型 adapter 会在 dispatch 后以错误关闭 turn，从而证明模型失败不会移除回执。
|
||||
package 测试固定严格 decoding、transition、fork suffix、id 不复用、时间边界、有界等待、墙钟变化、overdue 准入、固定 framing、入队与 append 失败、barrier 恢复、注册 rollback 和完全停稳 dispose。production JSONL restart 测试通过真实 Agent 生命周期恢复一条 overdue record，并证明后续再次 restart 不会重复 dispatch。显式启用的 Loader 组合可启动该 package，无密钥浏览器场景会通过完整工具 pipeline 执行 `schedule_create`，并为普通 assistant follow-up 生成快照。
|
||||
|
||||
## 后果
|
||||
|
||||
- 提醒状态通过普通 Session persistence 跨进程重启并回放，无需新数据库或公开 service。
|
||||
- cold Session 不工作、不发送外部通知；重新打开后可能交付 overdue 提醒，且每个工具／卡片都会显示 `session-local`。
|
||||
- 每个 live 根只增加从 fold 派生的 timer、可选 idle wait 与一个 in-flight operation。长等待和插件卸载不会创建第二套持久状态机。
|
||||
- 通用 commit-aware event-view 路径可供其他持久 event 复用，但为 client Session window 增加了事件身份检查与请求 generation 栅栏。
|
||||
- cold Session 不工作、不发送外部通知；重新打开后可能交付 overdue 提醒。
|
||||
- 每个 live 根只增加从 fold 派生的 timer、可选 idle wait 与一个 in-flight operation。
|
||||
- 同步 follow-up 获得准入后、持久 dispatch 前的狭窄崩溃窗口可能在恢复后重复提醒；本设计选择可见重复而非静默丢失，不作 exactly-once 承诺。
|
||||
- 严格的 after-only 协议有意保持小型；其他规则系列需要显式 record、时间与 recurrence 语义，而不是 dormant 字段。
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-07-27-intent-named-subagent-continuation-operations.md
|
||||
2026-07-27-intent-named-subagent-continuation-operations.md: 4175e6d593e066033f3796357c6f0aefd767c588
|
||||
2026-07-27-intent-named-subagent-continuation-operations.zh.md: 6aeb036153a7d32ee61f2c08caf56273aa062ade
|
||||
2026-07-27-intent-named-subagent-continuation-operations.md: e74d62b7582e92f8e5ce68327a677259c8453d24
|
||||
2026-07-27-intent-named-subagent-continuation-operations.zh.md: ae7b370441d8e0ee045f4d0fcf851d28d055b295
|
||||
|
||||
@@ -18,7 +18,7 @@ The durability boundary also exposed both `SessionStore.flush()` and `flushRequi
|
||||
|
||||
Caller and provider requests are distinct. `SubagentStartRequest` contains caller-supplied one-shot data; `ResolvedSubagentStartRequest` adds the service-resolved descriptor before `SubagentProvider.start()`. For continuable creation, the manager passes a `ContinuableCreateRequest` to optional `SubagentProvider.prepareContinuable()` and receives detached creation data only. `SubagentService.resume()` and provider resume dispatch are absent: the continuation manager loads the descriptor, authorizes the parent, and owns Agent materialization, prompt delivery, cold resume, and teardown.
|
||||
|
||||
`SessionStore.flush(session)` is the single durability barrier and returns `Promise<boolean>`. Every scoped listener settles; a listener returns literal `true` only when it completed durability work. The call resolves `true` when at least one listener gives that acknowledgement, resolves `false` when none does, and rejects with the first registered listener failure after all listeners settle. The acknowledgement does not identify a selected persistence backend when several listeners are present. Ordinary checkpoints may ignore the boolean; the continuation manager also treats its final flush as a best-effort barrier, deliberately ignores it, logs rejection, and still disposes the child and releases ownership.
|
||||
`SessionStore.flush(session)` is the single durability barrier and returns `Promise<boolean>`. It resolves `true` after at least one scoped listener participates successfully, resolves `false` for an empty listener snapshot, and rejects with the first registered listener failure after all listeners settle. Participation cannot identify whether a selected persistence backend stored the state. Ordinary checkpoints may ignore the boolean; the continuation manager also treats its final flush as a best-effort barrier, deliberately ignores participation, logs rejection, and still disposes the child and releases ownership.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
@@ -26,7 +26,7 @@ Caller and provider requests are distinct. `SubagentStartRequest` contains calle
|
||||
|
||||
**Keep `sendMessage` on the service.** The model tool sends a message, but the service operation represents a follow-up that may steer or cold-resume. `followup` aligns with the structural `Agent` interface and does not promise a particular route.
|
||||
|
||||
**Keep `flushRequired()`.** A second method hides only a missing-durability-acknowledgement check. Returning that acknowledgement from the existing barrier keeps dispatch in one implementation and lets each caller state whether absence is acceptable.
|
||||
**Keep `flushRequired()`.** A second method hides only an empty-listener check. Returning participation from the existing barrier keeps dispatch in one implementation and lets each caller state whether absence is acceptable.
|
||||
|
||||
**Fold ordinary and continuable starts together.** A flag would make one method return either an awaited holder-owned one-shot run or immediate durable child and message identities. Separate intent methods preserve the ownership and timing distinction without a return union.
|
||||
|
||||
@@ -34,5 +34,5 @@ Caller and provider requests are distinct. `SubagentStartRequest` contains calle
|
||||
|
||||
- The Cordis service catalog contains only caller operations; a provider can opt into continuable first creation through `SubagentProvider.prepareContinuable?()` without receiving Agent lifecycle authority or a public resume operation.
|
||||
- Follow-up source and cancellation travel in one options object, matching the intent-helper shape on `Agent` while retaining the existing live-delivery and cold-resume semantics.
|
||||
- Session durability has one barrier operation. Its explicit durability acknowledgement remains observable, but no continuable-child path depends on which backend supplied it.
|
||||
- Session durability has one barrier operation. Its participation result remains observable, but no continuable-child path treats arbitrary listener participation as proof that a persistence backend stored the state.
|
||||
- The `send_message` and `report` schemas, accepted message identities, `AgentHandle` ownership, durable event vocabulary, and model-visible transcript follow the activation-based realization linked above.
|
||||
|
||||
@@ -18,7 +18,7 @@ Status: implemented
|
||||
|
||||
调用方请求与提供方请求相互分离。`SubagentStartRequest` 包含调用方提供的 one-shot 数据；`ResolvedSubagentStartRequest` 会在调用 `SubagentProvider.start()` 前加入由服务解析的描述符。创建可继续 child 时，管理器将 `ContinuableCreateRequest` 传给可选的 `SubagentProvider.prepareContinuable()`，且只接收分离的创建数据。`SubagentService.resume()` 与提供方恢复分发均不存在：继续执行管理器加载描述符、对 parent 进行鉴权，并负责 Agent 实体化、提示词投递、冷恢复与 teardown。
|
||||
|
||||
`SessionStore.flush(session)` 是唯一的持久性屏障，并返回 `Promise<boolean>`。所有作用域内 listener 都会结算；只有在完成持久化工作后，listener 才返回字面量 `true`。至少一个 listener 给出该确认时，调用解析为 `true`；没有 listener 确认时解析为 `false`；所有 listener 结算后，如有失败，则以注册顺序最靠前的错误拒绝。当存在多个 listener 时，该确认不会标识具体由哪个持久化后端提供。普通检查点可以忽略该布尔值；继续执行管理器同样将最终 flush 视为 best-effort 屏障，有意忽略它，记录拒绝日志，并仍会对 child 执行 dispose（资源释放）并释放所有权。
|
||||
`SessionStore.flush(session)` 是唯一的持久性屏障，并返回 `Promise<boolean>`。至少一个作用域内监听器成功参与后，它解析为 `true`；监听器快照为空时解析为 `false`；所有监听器结算后，如有失败，则以注册顺序最靠前的监听器错误拒绝。参与结果无法表明所选的持久化后端是否已经存储状态。普通检查点可以忽略该布尔值；继续执行管理器同样将最终 flush 视为 best-effort 屏障，有意忽略参与结果，记录拒绝日志，并仍会对 child 执行 dispose（资源释放）并释放所有权。
|
||||
|
||||
## 已考虑的替代方案
|
||||
|
||||
@@ -26,7 +26,7 @@ Status: implemented
|
||||
|
||||
**在服务上保留 `sendMessage`。** 面向模型的工具发送消息，但服务操作表达的是后续操作，既可能对运行中的激活执行 steering，也可能从持久化存储恢复。`followup` 与结构化 `Agent` 接口保持一致，也不承诺特定路由。
|
||||
|
||||
**保留 `flushRequired()`。** 第二个方法只封装了缺少持久化确认的检查。由现有屏障返回该确认，可以让分发只保留一套实现，并让每个调用方自行判定缺少确认是否可接受。
|
||||
**保留 `flushRequired()`。** 第二个方法只封装了空监听器检查。由现有屏障返回是否有监听器参与，可以让分发只保留一套实现，并让每个调用方自行判定缺少监听器是否可接受。
|
||||
|
||||
**合并普通启动与可继续启动。** 一个标志会让同一方法要么等待由持有方负责的 one-shot run 就绪后返回，要么立即返回持久化 child 与消息标识。按意图拆分的方法无需返回值联合类型即可保留所有权与时序差异。
|
||||
|
||||
@@ -34,5 +34,5 @@ Status: implemented
|
||||
|
||||
- Cordis 服务目录只包含调用方操作；提供方可以通过 `SubagentProvider.prepareContinuable?()` 选择参与可继续 child 的首次创建，但不会获得 Agent 生命周期权限或公开恢复操作。
|
||||
- 后续操作的来源与取消信号通过同一个选项对象传递，与 `Agent` 上按意图命名的辅助方法形态一致，同时保留在线投递与从持久化存储恢复的语义。
|
||||
- 会话持久性只有一个屏障操作。显式持久化确认仍可观测，但任何可继续 child 路径都不依赖由哪个后端提供确认。
|
||||
- 会话持久性只有一个屏障操作。参与结果仍可观测，但任何可继续 child 路径都不会将任意监听器参与视为持久化后端已存储状态的证明。
|
||||
- `send_message` 与 `report` schema、已接受的消息标识、`AgentHandle` 所有权、持久化事件词汇与模型可见的 transcript（文本记录）遵循上文链接的基于 Activation 的实现。
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-09-conversational-schedule-delivery.md
|
||||
2026-08-09-conversational-schedule-delivery.md: ee58ae25abf125ed5507f3cd27ee2ba09b1711ec
|
||||
2026-08-09-conversational-schedule-delivery.zh.md: 15fe0d1bba2590119b1457fc0a8437a40f7d75d2
|
||||
@@ -0,0 +1,39 @@
|
||||
# Agent Note: Conversational Schedule delivery
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-08-09-conversational-schedule-delivery.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
Schedule already delivers a due reminder by queuing a normal Agent follow-up. A second durable Web receipt represented the same occurrence through a Schedule projection, a persistence-success event, Host history and live sidecars, client same-sequence upgrades, a generic event-view slot, and a dedicated renderer. That path spread one feature's confirmation UI across Session, persistence, Host, client runtime, conversation UI, and an extra package.
|
||||
|
||||
The receipt also created a second meaning of delivery. It remained visible when the model turn failed, while the conversation itself contained no successful reminder answer. Users need the scheduled conversation to continue; they do not need a separate durable badge proving that an internal dispatch was attempted.
|
||||
|
||||
## Decision
|
||||
|
||||
A due reminder waits for the Agent's idle maintenance phase and calls `followup()`. The follow-up starts a normal later turn and appears through the ordinary conversation transcript; Schedule never calls `steer()` and never interrupts the current turn.
|
||||
|
||||
`schedule/change` remains the only durable Schedule state. Its dispatch operation records that the follow-up was synchronously queued, which prevents ordinary restart replay after the dispatch is durable. Dispatch does not claim model success, user acknowledgement, or an external notification. The narrow crash interval between enqueue and durable dispatch remains at-least-once.
|
||||
|
||||
Schedule exposes no presentation projection, Host sidecar, browser event node, keyed event slot, or client renderer. Session persistence retains its shared `flush()` contract and has no Schedule-driven success event. The opt-in Web overlay loads only `@deepseek-ai/dsh-tool-schedule`.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Keep the commit-aware receipt.** It could prove that a dispatch reached persistence even when the model failed, but that is an implementation outcome rather than the user's reminder. Its cross-component protocol and late same-sequence merge logic are disproportionate to that value.
|
||||
|
||||
**Render raw `schedule/change` events in the conversation.** This avoids a domain card but still exposes internal state transitions as user-facing messages and requires generic non-surface event presentation machinery solely for Schedule.
|
||||
|
||||
**Treat dispatch as successful reminder delivery.** The dispatch precedes the model request and cannot establish that an assistant answer exists or was read. Naming it delivery would overstate the durable fact.
|
||||
|
||||
**Steer the current turn when a reminder becomes due.** Steering changes the in-progress request path and lets timing interrupt unrelated work. Waiting for full idle and using `followup()` preserves one reminder per ordinary later turn.
|
||||
|
||||
## Verification
|
||||
|
||||
Package lifecycle tests pin idle waiting, maintenance ownership, follow-up-before-dispatch ordering, synchronous enqueue failure, model-independent dispatch, and restart replay. The assembled Web scenario snapshots the resulting assistant row and asserts that a persisted Schedule dispatch has no special history view. Source and dependency audits reject the removed presentation symbols, event, sidecar, slot, renderer package, and overlay entry.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Schedule is contained in its package plus ordinary composition and catalog wiring; Session, persistence, Host, client runtime, and conversation UI carry no Schedule-specific behavior.
|
||||
- Users see the reminder only through the conversation's normal model response. A failed model turn remains a failed turn rather than a contradictory success receipt.
|
||||
- Consumers that need external or acknowledged delivery require a different product boundary with its own notification and acknowledgement semantics.
|
||||
@@ -0,0 +1,39 @@
|
||||
# Agent Note: 对话式 Schedule 交付
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-08-09-conversational-schedule-delivery.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
Schedule 已经通过将普通的 agent（智能体）后续轮次排入队列来交付到期提醒。第二条持久 Web 回执通过 Schedule 投影、持久化成功事件、Host 历史记录与 live 伴随数据、客户端同序号升级、通用事件视图 slot 和专用渲染器表示同一次提醒触发。这条路径把一项功能的确认 UI 分散到会话、持久化、Host、客户端运行时、对话 UI 和一个额外包中。
|
||||
|
||||
该回执还让「交付」有了第二种含义。即使模型轮次失败，它仍然可见，而对话本身没有成功的提醒答复。用户需要定时对话继续进行；他们不需要一枚单独的持久标记来证明内部 dispatch 已经尝试过。
|
||||
|
||||
## 决策
|
||||
|
||||
到期提醒会等待 agent 的 idle maintenance phase，再调用 `followup()`。该操作会在稍后开启一个普通轮次，并通过普通对话 transcript（文本记录）显示；Schedule 绝不会调用 `steer()`，也绝不会中断当前轮次。
|
||||
|
||||
`schedule/change` 仍是唯一持久 Schedule 状态。其 dispatch 操作记录后续轮次已同步入队，这会在 dispatch 持久化后阻止普通的重启回放。dispatch 不表示模型成功、用户确认或外部通知。入队与持久 dispatch 之间的狭窄崩溃窗口仍保留至少一次语义。
|
||||
|
||||
Schedule 不公开呈现投影、Host 伴随数据、浏览器事件节点、按事件键控的 slot 或客户端渲染器。会话持久化保留共享的 `flush()` 约定，且不存在由 Schedule 驱动的成功事件。显式启用的 Web overlay 只加载 `@deepseek-ai/dsh-tool-schedule`。
|
||||
|
||||
## 已考虑的替代方案
|
||||
|
||||
**保留提交感知回执。** 即使模型失败，它也可以证明 dispatch 已到达持久化，但这是实现结果，而不是用户的提醒。其跨组件协议与后到的同序号合并逻辑，与这点价值不成比例。
|
||||
|
||||
**在对话中渲染原始 `schedule/change` 事件。** 这样可以避免领域卡片，但仍会把内部状态转换暴露为面向用户的消息，而且仅为 Schedule 就需要通用的内部事件呈现机制。
|
||||
|
||||
**把 dispatch 当作提醒已成功交付。** dispatch 发生在模型请求之前，无法证明 assistant 答复存在或已被读取。将其称为交付会夸大持久事实。
|
||||
|
||||
**提醒到期时中途引导当前轮次。** 中途引导会改变进行中的请求路径，并让定时触发中断无关工作。等待完全 idle 后使用 `followup()`，可让每条提醒分别进入一个普通的后续轮次。
|
||||
|
||||
## 验证
|
||||
|
||||
包生命周期测试固定 idle 等待、maintenance 所有权、后续轮次先于 dispatch 的顺序、同步入队失败、与模型无关的 dispatch 和重启回放。组装后的 Web 场景为产生的 assistant 行生成快照，并断言已持久化的 Schedule dispatch 没有特殊 history view。源码与依赖审计会拒绝残留的已移除呈现符号、事件、sidecar、slot、渲染器包与 overlay 配置项。
|
||||
|
||||
## 后果
|
||||
|
||||
- Schedule 的实现仅涉及其自身包、常规组合与目录接线；会话、持久化、Host、客户端运行时和对话 UI 不携带 Schedule 专属行为。
|
||||
- 用户只能通过对话中的普通模型响应看到提醒。失败的模型轮次仍是失败轮次，不会出现与之矛盾的成功回执。
|
||||
- 需要外部交付或交付确认的消费方必须采用另一条产品边界，并由其拥有自己的通知和确认语义。
|
||||
@@ -24,5 +24,3 @@ The [CLI behavior reference](reference/README.md) owns exact layer precedence, f
|
||||
## Development
|
||||
|
||||
Production runs require built package and frontend artifacts. From a checkout, `pnpm run dsh` runs the TypeScript entry and forwards arguments; the [source-launcher reference](reference/README.md#source-launcher) describes the PATH symlink and module-resolution contract.
|
||||
|
||||
Schedule reminders are opt-in rather than part of the default Web tree. `dsh web --patch examples/web-schedule/cordis.yml` loads the Schedule tools and receipt renderer over the existing JSONL persistence path; reminders run only while their original Session has a live root Agent and are reported as `session-local`, never as an external notification.
|
||||
|
||||
@@ -19,7 +19,6 @@
|
||||
"@cordisjs/plugin-timer": "workspace:*",
|
||||
"@deepseek-ai/dsh-app-boot": "workspace:^",
|
||||
"@deepseek-ai/dsh-base": "workspace:^",
|
||||
"@deepseek-ai/dsh-client-ui-schedule": "workspace:^",
|
||||
"@deepseek-ai/dsh-headless": "workspace:^",
|
||||
"@deepseek-ai/dsh-mcp-client": "workspace:^",
|
||||
"@deepseek-ai/dsh-paths": "workspace:^",
|
||||
|
||||
@@ -87,7 +87,6 @@ describe('parseDshArgs', () => {
|
||||
expect(exitCode(['web', '--dump-config', '--dump-default-config'])).toBe(1)
|
||||
expect(exitCode(['web', '--dump-default-config', '--patch', 'w.yml'])).toBe(1)
|
||||
expect(exitCode(['web', '--patch='])).toBe(1)
|
||||
expect(exitCode(['web', '--config', 'w.yml'])).toBe(1)
|
||||
// Boot-free dumps derive no flag patches; silently dropping the flags
|
||||
// would print a tree that differs from the same invocation's boot.
|
||||
expect(exitCode(['web', '--dump-config', '--port', '8080'])).toBe(1)
|
||||
|
||||
@@ -185,7 +185,7 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
|
||||
expect(help.stdout).toContain('dsh run "run the tests"')
|
||||
expect(help.stdout).toContain('dsh plugin --profile')
|
||||
expect(help.stdout).not.toMatch(/^\s+(?:tui|meta|upgrade)\b/mu)
|
||||
for (const removed of [['tui'], ['--config', 'x.yml'], ['web', '--config', 'x.yml'], ['-p', 'task'], ['--profile', 'headless', 'task']]) {
|
||||
for (const removed of [['tui'], ['--config', 'x.yml'], ['-p', 'task'], ['--profile', 'headless', 'task']]) {
|
||||
const result = await runBuiltBin(removed)
|
||||
expect(result.code).toBe(1)
|
||||
}
|
||||
|
||||
@@ -167,11 +167,6 @@ export interface WebScaffold {
|
||||
|
||||
/** Options for {@link launchWebScaffold}. */
|
||||
export interface LaunchOptions {
|
||||
/** Caller-owned workspace and persistence roots reused across process-style restarts. */
|
||||
world?: {
|
||||
workspaceCwd: string
|
||||
persistenceRoot: string
|
||||
}
|
||||
/**
|
||||
* Optional product overlay applied after the shipped Web surface and before
|
||||
* the scaffold's hermetic test patches, matching the launcher's `--patch`
|
||||
@@ -242,18 +237,11 @@ export interface LaunchOptions {
|
||||
}
|
||||
|
||||
/** Dispose the booted tree and remove both owned temp roots, reporting every independent cleanup failure. */
|
||||
async function cleanupScaffoldWorld(
|
||||
ctx: Context,
|
||||
workspaceCwd: string,
|
||||
persistenceRoot: string,
|
||||
removeWorld: boolean,
|
||||
): Promise<unknown[]> {
|
||||
async function cleanupScaffoldWorld(ctx: Context, workspaceCwd: string, persistenceRoot: string): Promise<unknown[]> {
|
||||
const failures: unknown[] = []
|
||||
await Promise.resolve(ctx.fiber.dispose()).catch((error: unknown) => failures.push(error))
|
||||
if (removeWorld) {
|
||||
await rm(workspaceCwd, { recursive: true, force: true }).catch((error: unknown) => failures.push(error))
|
||||
await rm(persistenceRoot, { recursive: true, force: true }).catch((error: unknown) => failures.push(error))
|
||||
}
|
||||
await rm(workspaceCwd, { recursive: true, force: true }).catch((error: unknown) => failures.push(error))
|
||||
await rm(persistenceRoot, { recursive: true, force: true }).catch((error: unknown) => failures.push(error))
|
||||
return failures
|
||||
}
|
||||
|
||||
@@ -288,26 +276,19 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
|
||||
process.env.DEEPSEEK_API_KEY = originalDeepSeekCredential
|
||||
}
|
||||
}
|
||||
const ownsWorld = options.world === undefined
|
||||
const workspaceCwd = options.world === undefined
|
||||
? await realpath(await mkdtemp(join(tmpdir(), 'dsh-web-e2e-ws-')))
|
||||
: await realpath(options.world.workspaceCwd)
|
||||
const workspaceCwd = await realpath(await mkdtemp(join(tmpdir(), 'dsh-web-e2e-ws-')))
|
||||
// Isolated harness home: the settings/credentials rows resolve $DSH_HOME
|
||||
// paths at load, and an in-process boot must NEVER touch the developer's
|
||||
// real ~/.dsh document or credential file.
|
||||
const harnessHome = join(workspaceCwd, '.dsh-home')
|
||||
let persistenceRoot: string
|
||||
if (options.world !== undefined) {
|
||||
persistenceRoot = await realpath(options.world.persistenceRoot)
|
||||
} else {
|
||||
try {
|
||||
persistenceRoot = await mkdtemp(join(tmpdir(), 'dsh-web-e2e-sessions-'))
|
||||
} catch (error) {
|
||||
const failures: unknown[] = [error]
|
||||
await rm(workspaceCwd, { recursive: true, force: true }).catch((cleanupError: unknown) => failures.push(cleanupError))
|
||||
if (failures.length > 1) throw new AggregateError(failures, 'web scaffold temp-root setup failed')
|
||||
throw error
|
||||
}
|
||||
try {
|
||||
persistenceRoot = await mkdtemp(join(tmpdir(), 'dsh-web-e2e-sessions-'))
|
||||
} catch (error) {
|
||||
const failures: unknown[] = [error]
|
||||
await rm(workspaceCwd, { recursive: true, force: true }).catch((cleanupError: unknown) => failures.push(cleanupError))
|
||||
if (failures.length > 1) throw new AggregateError(failures, 'web scaffold temp-root setup failed')
|
||||
throw error
|
||||
}
|
||||
if (maskDeepSeekCredential) Reflect.deleteProperty(process.env, 'DEEPSEEK_API_KEY')
|
||||
|
||||
@@ -466,7 +447,7 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
|
||||
}
|
||||
} catch (error) {
|
||||
if (process.cwd() !== originalCwd) process.chdir(originalCwd)
|
||||
const cleanupFailures = await cleanupScaffoldWorld(ctx, workspaceCwd, persistenceRoot, ownsWorld)
|
||||
const cleanupFailures = await cleanupScaffoldWorld(ctx, workspaceCwd, persistenceRoot)
|
||||
restoreCredentialEnvironment()
|
||||
if (cleanupFailures.length > 0) {
|
||||
throw new AggregateError([error, ...cleanupFailures], 'web scaffold setup failed and cleanup was incomplete')
|
||||
@@ -512,7 +493,7 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
|
||||
failures.push(error)
|
||||
}
|
||||
try {
|
||||
failures.push(...await cleanupScaffoldWorld(ctx, workspaceCwd, persistenceRoot, ownsWorld))
|
||||
failures.push(...await cleanupScaffoldWorld(ctx, workspaceCwd, persistenceRoot))
|
||||
} finally {
|
||||
restoreCredentialEnvironment()
|
||||
}
|
||||
|
||||
@@ -1,77 +1,100 @@
|
||||
// Keyless assembled-browser evidence for the opt-in Schedule overlay. A real
|
||||
// root Agent receives schedule_create through the complete tool pipeline; the
|
||||
// one-second owner path queues its best-effort followup, commits dispatch, and
|
||||
// the browser renders the Host's durability-gated reminder sidecar. No model
|
||||
// fixture is installed: the later prompt failure cannot retract the receipt.
|
||||
import { mkdtemp, realpath, rm } from 'node:fs/promises'
|
||||
import { tmpdir } from 'node:os'
|
||||
/** Keyless assembled-Web evidence for conversational Schedule delivery. */
|
||||
|
||||
import { join } from 'node:path'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
import type { Browser, Page } from 'playwright'
|
||||
import { chromium } from 'playwright'
|
||||
import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
|
||||
import type { AgentHandle } from '@deepseek-ai/dsh-agent'
|
||||
import { CallId, createUserMessage } from '@deepseek-ai/dsh-llm'
|
||||
import { SessionId } from '@deepseek-ai/dsh-session'
|
||||
import type { Session } from '@deepseek-ai/dsh-session'
|
||||
import { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm'
|
||||
import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
|
||||
import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
|
||||
import { RpcId } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
|
||||
import {
|
||||
assertFixtureInventory, captureStableAria, compareOrRefreshGolden,
|
||||
launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold,
|
||||
assertFixtureInventory,
|
||||
captureStableAria,
|
||||
compareOrRefreshGolden,
|
||||
launchWebScaffold,
|
||||
watchConsole,
|
||||
webSnapshotMode,
|
||||
type WebScaffold,
|
||||
} from './scaffold.ts'
|
||||
import { newEnglishPage, saveFailureShot } from './support.ts'
|
||||
import {
|
||||
ScheduleId,
|
||||
createAfterScheduleRecord,
|
||||
foldScheduleEvents,
|
||||
} from '@deepseek-ai/dsh-tool-schedule'
|
||||
import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './support.ts'
|
||||
|
||||
const MODE = webSnapshotMode()
|
||||
const OVERLAY = fileURLToPath(new URL('../../../examples/web-schedule/cordis.yml', import.meta.url))
|
||||
const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/schedule-after', import.meta.url))
|
||||
const RECEIPT_EXPECTED = fileURLToPath(new URL('./snapshots/schedule-after/receipt.expected.md', import.meta.url))
|
||||
const CONVERSATION_EXPECTED = join(SNAPSHOT_DIR, 'conversation.expected.md')
|
||||
const PROVIDER = 'schedule-web-test'
|
||||
const MODEL = 'reply'
|
||||
const PROMPT = 'Check the deployment log'
|
||||
const REPLY = 'Reminder: Check the deployment log.'
|
||||
|
||||
interface CreatedScheduleView {
|
||||
id: string
|
||||
deliveryMode: 'session-local'
|
||||
}
|
||||
|
||||
/** Wait for one in-process lifecycle fact without using test-scoped expect.poll in beforeAll. */
|
||||
async function waitForFact(read: () => boolean, timeoutMs: number): Promise<void> {
|
||||
const deadline = Date.now() + timeoutMs
|
||||
while (!read()) {
|
||||
if (Date.now() >= deadline) throw new Error(`Schedule lifecycle fact did not arrive within ${timeoutMs}ms`)
|
||||
await new Promise(resolve => setTimeout(resolve, 20))
|
||||
/** Deterministic model seam that turns the scheduled follow-up into ordinary assistant prose. */
|
||||
class ReminderAdapter extends LlmAdapter {
|
||||
override async * stream(_options: GenerateOptions): AsyncIterable<StreamChunk> {
|
||||
yield { type: 'block-start', index: 0, blockType: 'text' }
|
||||
yield { type: 'block-end', index: 0, block: { type: 'text', text: REPLY } }
|
||||
yield { type: 'finish', reason: { kind: 'stop' } }
|
||||
}
|
||||
}
|
||||
|
||||
/** Give a seeded Session one completed turn so the real Host fork path can cut it. */
|
||||
function appendCompletedTurn(session: Session, prompt: string): void {
|
||||
session.append('turn/start', { turn: 1 })
|
||||
session.append('user/message', createUserMessage({
|
||||
content: [{ type: 'text', text: prompt }],
|
||||
source: { kind: 'user' },
|
||||
}), { surfaceOp: 'append' })
|
||||
session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
|
||||
/** Extract text from one durable assistant message. */
|
||||
function assistantText(event: Extract<SessionEvent, { type: 'assistant/message' }>): string {
|
||||
return event.data.message.content
|
||||
.filter(block => block.type === 'text')
|
||||
.map(block => block.text)
|
||||
.join('')
|
||||
}
|
||||
|
||||
describe.skipIf(MODE === 'record')('web e2e: durable after reminder receipt', () => {
|
||||
/** Wait for the exact scheduled assistant reply and return its durable sequence. */
|
||||
async function waitForReply(handle: AgentHandle, timeoutMs: number): Promise<number> {
|
||||
const deadline = Date.now() + timeoutMs
|
||||
while (true) {
|
||||
const event = handle.agent.session.events.find((candidate): candidate is SessionEvent<'assistant/message'> => (
|
||||
candidate.type === 'assistant/message' && assistantText(candidate) === REPLY
|
||||
))
|
||||
if (event !== undefined) return event.seq
|
||||
if (Date.now() >= deadline) throw new Error(`scheduled assistant reply did not arrive within ${timeoutMs}ms`)
|
||||
await new Promise<void>(resolve => setTimeout(resolve, 20))
|
||||
}
|
||||
}
|
||||
|
||||
describe.skipIf(MODE === 'record')('web e2e: conversational after reminder', () => {
|
||||
let scaffold: WebScaffold
|
||||
let agentHandle: AgentHandle
|
||||
let browser: Browser
|
||||
let page: Page
|
||||
let scheduleId = ''
|
||||
let assistantSeq = -1
|
||||
let tripwire: ReturnType<typeof watchConsole>
|
||||
|
||||
beforeAll(async () => {
|
||||
scaffold = await launchWebScaffold({ extraOverlayPath: OVERLAY })
|
||||
scaffold.ctx.effect(
|
||||
() => scaffold.ctx.llm.registerAdapter([PROVIDER], new ReminderAdapter()),
|
||||
'schedule Web reminder adapter',
|
||||
)
|
||||
|
||||
browser = await chromium.launch()
|
||||
page = await newEnglishPage(browser)
|
||||
tripwire = watchConsole(page)
|
||||
await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
|
||||
await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
|
||||
await connectFreshWorkspace(page, scaffold.workspaceCwd)
|
||||
|
||||
const cwd = join(scaffold.workspaceCwd, 'workspace')
|
||||
agentHandle = await scaffold.ctx.agents.create({
|
||||
sessionId: SessionId('schedule-after-web-e2e'),
|
||||
meta: { cwd: scaffold.workspaceCwd },
|
||||
agentOptions: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
|
||||
meta: { cwd },
|
||||
agentOptions: { provider: PROVIDER, model: MODEL },
|
||||
})
|
||||
const workspace = await scaffold.ctx.workspace.create(scaffold.workspaceCwd, 'Schedule')
|
||||
agentHandle.agent.session.append('session/title', {
|
||||
title: 'Scheduled follow-up',
|
||||
messageSeqs: [],
|
||||
source: { kind: 'user' },
|
||||
})
|
||||
const workspace = await scaffold.ctx.workspace.resolveByPath(cwd)
|
||||
if (workspace === undefined) throw new Error('connected Web workspace was not registered')
|
||||
await workspace.attachSession(agentHandle.agent.id)
|
||||
|
||||
const created = await scaffold.ctx.tools.execute({
|
||||
@@ -82,47 +105,23 @@ describe.skipIf(MODE === 'record')('web e2e: durable after reminder receipt', ()
|
||||
agent: agentHandle.agent,
|
||||
})
|
||||
expect(created.isError).toBe(false)
|
||||
if (created.isError) throw new Error(created.error.message)
|
||||
const value = created.value as unknown as CreatedScheduleView
|
||||
expect(value.deliveryMode).toBe('session-local')
|
||||
scheduleId = value.id
|
||||
expect(scheduleId.length).toBeGreaterThan(0)
|
||||
|
||||
await waitForFact(() => agentHandle.agent.session.events.some(event =>
|
||||
event.type === 'schedule/change'
|
||||
&& (event.data as { operation?: unknown }).operation === 'dispatch'), 15_000)
|
||||
assistantSeq = await waitForReply(agentHandle, 15_000)
|
||||
await agentHandle.agent.whenIdle()
|
||||
await expect(scaffold.ctx.sessions.flush(agentHandle.agent.session)).resolves.toBe(true)
|
||||
const durable = await scaffold.ctx.sessionPersistence.inspect(agentHandle.agent.id)
|
||||
expect(durable.meta).toMatchObject(agentHandle.agent.session.header)
|
||||
expect({ ...durable.meta, delegationDepth: durable.meta.delegationDepth ?? 0 }).toEqual({
|
||||
...agentHandle.agent.session.header,
|
||||
delegationDepth: agentHandle.agent.session.header.delegationDepth ?? 0,
|
||||
})
|
||||
expect(durable.events).toEqual(agentHandle.agent.session.events.slice(0, durable.events.length))
|
||||
|
||||
const stored = await scaffold.ctx.sessionPersistence.inspect(agentHandle.agent.id)
|
||||
expect(stored.events.filter(event => (
|
||||
event.type === 'schedule/change' && event.data.operation === 'dispatch'
|
||||
))).toHaveLength(1)
|
||||
const history = await scaffold.ctx.apiProxy.sessions.history({
|
||||
rpcId: RpcId('schedule-history-baseline'), payload: { sessionId: agentHandle.agent.id },
|
||||
rpcId: RpcId('schedule-after-history'),
|
||||
payload: { sessionId: agentHandle.agent.id },
|
||||
})
|
||||
if (!history.result.ok) throw new Error(history.result.error.message)
|
||||
expect(history.result.value.events?.find(entry =>
|
||||
entry.event.type === 'schedule/change'
|
||||
&& (entry.event.data as { operation?: unknown }).operation === 'dispatch')?.view).toMatchObject({
|
||||
for: 'event',
|
||||
})
|
||||
await waitForFact(
|
||||
() => agentHandle.agent.session.events.some(event => event.type === 'turn/start'),
|
||||
10_000,
|
||||
)
|
||||
const listed = await scaffold.ctx.apiProxy.sessions.list({
|
||||
rpcId: RpcId('schedule-list-baseline'), payload: {},
|
||||
})
|
||||
if (!listed.result.ok) throw new Error(listed.result.error.message)
|
||||
expect(listed.result.value.items.find(item => item.sessionId === agentHandle.agent.id)?.blank).toBe(false)
|
||||
|
||||
browser = await chromium.launch()
|
||||
page = await newEnglishPage(browser)
|
||||
tripwire = watchConsole(page)
|
||||
await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
|
||||
await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
|
||||
const dispatch = history.result.value.events.find(entry => (
|
||||
entry.event.type === 'schedule/change' && entry.event.data.operation === 'dispatch'
|
||||
))
|
||||
expect(dispatch?.view).toBeUndefined()
|
||||
}, 120_000)
|
||||
|
||||
afterAll(async () => {
|
||||
@@ -134,152 +133,28 @@ describe.skipIf(MODE === 'record')('web e2e: durable after reminder receipt', ()
|
||||
if (failures.length > 1) throw new AggregateError(failures, 'Schedule Web evidence teardown failed')
|
||||
})
|
||||
|
||||
it('renders the committed reminder from attached history', async () => {
|
||||
it('renders the reminder as an ordinary assistant follow-up', async () => {
|
||||
onTestFailed(() => saveFailureShot(page, 'web-e2e-schedule-after'))
|
||||
const group = page.locator('[role="treeitem"]').first()
|
||||
await group.waitFor({ timeout: 15_000 })
|
||||
if (await group.getAttribute('aria-expanded') !== 'true') {
|
||||
await group.click()
|
||||
}
|
||||
await expect.poll(() => group.getAttribute('aria-expanded'), { timeout: 5_000 }).toBe('true')
|
||||
const session = page.locator('[role="treeitem"][aria-selected]').nth(1)
|
||||
await session.waitFor({ timeout: 10_000 })
|
||||
const session = page.getByRole('treeitem', { name: /Scheduled follow-up/ })
|
||||
await session.waitFor({ timeout: 15_000 })
|
||||
await session.click()
|
||||
|
||||
const receipt = page.locator('[data-schedule-reminder]')
|
||||
await receipt.waitFor({ timeout: 15_000 })
|
||||
expect(await receipt.getByText(PROMPT, { exact: true }).count()).toBe(1)
|
||||
expect(await receipt.getByText('Delivered in this session only', { exact: true }).count()).toBe(1)
|
||||
const snapshot = (await captureStableAria(page, '[data-schedule-reminder]', scaffold.workspaceCwd))
|
||||
.split(scheduleId).join('{{scheduleId}}')
|
||||
.replace(/\d{4}-\d{2}-\d{2}T(?:\d{2}:\d{2}:\d{2}\.\d{3}|\{\{clock\}\})Z/gu, '{{occurrenceAt}}')
|
||||
await compareOrRefreshGolden(RECEIPT_EXPECTED, snapshot, MODE)
|
||||
const selector = `[data-chat-anchor-key="node:${String(assistantSeq)}"]`
|
||||
const row = page.locator(selector)
|
||||
await row.waitFor({ timeout: 15_000 })
|
||||
expect(await row.getAttribute('data-chat-flow-kind')).toBe('assistant')
|
||||
expect(await row.textContent()).toContain(REPLY)
|
||||
await compareOrRefreshGolden(
|
||||
CONVERSATION_EXPECTED,
|
||||
await captureStableAria(page, selector, scaffold.workspaceCwd),
|
||||
MODE,
|
||||
)
|
||||
expect(await page.locator('[data-schedule-reminder]').count()).toBe(0)
|
||||
expect(tripwire.pageErrors).toEqual([])
|
||||
expect(tripwire.warnings).toEqual([])
|
||||
}, 60_000)
|
||||
|
||||
it('keeps the fixture inventory closed', async () => {
|
||||
await assertFixtureInventory(SNAPSHOT_DIR, ['receipt.expected.md'])
|
||||
await assertFixtureInventory(SNAPSHOT_DIR, ['conversation.expected.md'])
|
||||
})
|
||||
})
|
||||
|
||||
describe.skipIf(MODE === 'record')('web e2e: Schedule restart, fork, and cold history', () => {
|
||||
it('preserves pending work, commits one overdue receipt, and replays it cold without activation', async () => {
|
||||
const workspaceCwd = await realpath(await mkdtemp(join(tmpdir(), 'dsh-schedule-restart-ws-')))
|
||||
const persistenceRoot = await mkdtemp(join(tmpdir(), 'dsh-schedule-restart-sessions-'))
|
||||
const world = { workspaceCwd, persistenceRoot }
|
||||
const pendingId = SessionId('schedule-restart-pending')
|
||||
const deliveredId = SessionId('schedule-restart-delivered')
|
||||
let scaffold: WebScaffold | undefined
|
||||
try {
|
||||
scaffold = await launchWebScaffold({ extraOverlayPath: OVERLAY, world })
|
||||
const workspace = await scaffold.ctx.workspace.create(workspaceCwd, 'Schedule restart')
|
||||
|
||||
const pending = scaffold.ctx.sessions.create(pendingId, { meta: { cwd: workspaceCwd } })
|
||||
appendCompletedTurn(pending, 'pending parent turn')
|
||||
pending.append('session/title', {
|
||||
title: 'Pending restart session', messageSeqs: [], source: { kind: 'user' },
|
||||
})
|
||||
const pendingRecord = createAfterScheduleRecord(
|
||||
ScheduleId('schedule-pending'), 'Pending across restart', 3_600, Date.now(),
|
||||
)
|
||||
pending.append('schedule/change', { version: 1, operation: 'create', schedule: pendingRecord })
|
||||
await expect(scaffold.ctx.sessions.flush(pending)).resolves.toBe(true)
|
||||
await workspace.attachSession(pendingId)
|
||||
|
||||
const delivered = scaffold.ctx.sessions.create(deliveredId, { meta: { cwd: workspaceCwd } })
|
||||
appendCompletedTurn(delivered, 'delivered parent turn')
|
||||
delivered.append('session/title', {
|
||||
title: 'Delivered restart session', messageSeqs: [], source: { kind: 'user' },
|
||||
})
|
||||
const overdueRecord = createAfterScheduleRecord(
|
||||
ScheduleId('schedule-delivered'), 'Delivered after restart', 1, Date.now() - 60_000,
|
||||
)
|
||||
delivered.append('schedule/change', { version: 1, operation: 'create', schedule: overdueRecord })
|
||||
await expect(scaffold.ctx.sessions.flush(delivered)).resolves.toBe(true)
|
||||
await workspace.attachSession(deliveredId)
|
||||
|
||||
await scaffold.close()
|
||||
scaffold = undefined
|
||||
|
||||
scaffold = await launchWebScaffold({ extraOverlayPath: OVERLAY, world })
|
||||
const pendingResume = await scaffold.ctx.apiProxy.sessions.create({
|
||||
rpcId: RpcId('schedule-pending-resume'),
|
||||
payload: { sessionId: pendingId, cwd: workspaceCwd },
|
||||
})
|
||||
if (!pendingResume.result.ok) throw new Error(pendingResume.result.error.message)
|
||||
const pendingAgent = scaffold.ctx.agents.get(pendingId)
|
||||
if (pendingAgent === undefined) throw new Error('pending Session did not resume')
|
||||
expect(foldScheduleEvents(
|
||||
pendingAgent.session.events,
|
||||
pendingAgent.session.header.seedLength ?? 0,
|
||||
).active).toEqual([expect.objectContaining({ id: 'schedule-pending' })])
|
||||
|
||||
const forked = await scaffold.ctx.apiProxy.sessions.fork({
|
||||
rpcId: RpcId('schedule-pending-fork'),
|
||||
payload: { sessionId: pendingId },
|
||||
})
|
||||
if (!forked.result.ok) throw new Error(forked.result.error.message)
|
||||
const child = scaffold.ctx.agents.get(forked.result.value.sessionId)
|
||||
if (child === undefined) throw new Error('fork child was not published')
|
||||
expect(foldScheduleEvents(
|
||||
child.session.events,
|
||||
child.session.header.seedLength ?? 0,
|
||||
).active).toEqual([])
|
||||
|
||||
const deliveredResume = await scaffold.ctx.apiProxy.sessions.create({
|
||||
rpcId: RpcId('schedule-delivered-resume'),
|
||||
payload: { sessionId: deliveredId, cwd: workspaceCwd },
|
||||
})
|
||||
if (!deliveredResume.result.ok) throw new Error(deliveredResume.result.error.message)
|
||||
const deliveredAgent = scaffold.ctx.agents.get(deliveredId)
|
||||
if (deliveredAgent === undefined) throw new Error('overdue Session did not resume')
|
||||
await waitForFact(() => deliveredAgent.session.events.some(event =>
|
||||
event.type === 'schedule/change' && event.data.operation === 'dispatch'), 15_000)
|
||||
await deliveredAgent.whenIdle()
|
||||
await expect(scaffold.ctx.sessions.flush(deliveredAgent.session)).resolves.toBe(true)
|
||||
expect(deliveredAgent.session.events.filter(event =>
|
||||
event.type === 'schedule/change' && event.data.operation === 'dispatch')).toHaveLength(1)
|
||||
|
||||
await scaffold.close()
|
||||
scaffold = undefined
|
||||
|
||||
scaffold = await launchWebScaffold({ extraOverlayPath: OVERLAY, world })
|
||||
expect(scaffold.ctx.agents.get(deliveredId)).toBeUndefined()
|
||||
const coldHistory = await scaffold.ctx.apiProxy.sessions.history({
|
||||
rpcId: RpcId('schedule-cold-history'),
|
||||
payload: { sessionId: deliveredId },
|
||||
})
|
||||
if (!coldHistory.result.ok) throw new Error(coldHistory.result.error.message)
|
||||
const dispatchEntries = coldHistory.result.value.events.filter(entry =>
|
||||
entry.event.type === 'schedule/change'
|
||||
&& entry.event.data.operation === 'dispatch')
|
||||
expect(dispatchEntries).toHaveLength(1)
|
||||
expect(dispatchEntries[0]?.view?.for).toBe('event')
|
||||
expect(scaffold.ctx.agents.get(deliveredId)).toBeUndefined()
|
||||
|
||||
await scaffold.close()
|
||||
scaffold = undefined
|
||||
|
||||
scaffold = await launchWebScaffold({ extraOverlayPath: OVERLAY, world })
|
||||
const replayed = await scaffold.ctx.apiProxy.sessions.create({
|
||||
rpcId: RpcId('schedule-delivered-replay'),
|
||||
payload: { sessionId: deliveredId, cwd: workspaceCwd },
|
||||
})
|
||||
if (!replayed.result.ok) throw new Error(replayed.result.error.message)
|
||||
const replayedAgent = scaffold.ctx.agents.get(deliveredId)
|
||||
if (replayedAgent === undefined) throw new Error('delivered Session did not resume again')
|
||||
await replayedAgent.whenIdle()
|
||||
await expect(scaffold.ctx.sessions.flush(replayedAgent.session)).resolves.toBe(true)
|
||||
expect(replayedAgent.session.events.filter(event =>
|
||||
event.type === 'schedule/change' && event.data.operation === 'dispatch')).toHaveLength(1)
|
||||
} finally {
|
||||
const failures: unknown[] = []
|
||||
await scaffold?.close().catch((error: unknown) => failures.push(error))
|
||||
await rm(workspaceCwd, { recursive: true, force: true }).catch((error: unknown) => failures.push(error))
|
||||
await rm(persistenceRoot, { recursive: true, force: true }).catch((error: unknown) => failures.push(error))
|
||||
if (failures.length === 1) throw failures[0]
|
||||
if (failures.length > 1) throw new AggregateError(failures, 'Schedule restart evidence teardown failed')
|
||||
}
|
||||
}, 180_000)
|
||||
})
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
- paragraph: "Reminder: Check the deployment log."
|
||||
- button "Copy":
|
||||
- img
|
||||
- button "Branch into a new conversation":
|
||||
- img
|
||||
- text: {{clock}} Ran for {{duration}}
|
||||
@@ -1,6 +0,0 @@
|
||||
- note:
|
||||
- banner: Scheduled reminder Delivered in this session only
|
||||
- paragraph: Check the deployment log
|
||||
- contentinfo:
|
||||
- text: ID {{scheduleId}}
|
||||
- time: Due at {{occurrenceAt}}
|
||||
@@ -142,7 +142,7 @@ The session log is authoritative. `deriveMessages()` projects model history; raw
|
||||
|
||||
**Model-visible ⟺ logged**: messages entering at `step/start` plus the folded `request/header` reconstruct every request. The header marks adapter defaults so later proposals discard them and re-resolve the route without losing explicit settings. `request/context` separately records registration-bound provider, model, and capacity metadata when the route changes; it does not participate in request reconstruction or header equality. `dsh-agent-loop/invariant` asserts reconstructability through `ctx.invariants` ([reconstructability](../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)).
|
||||
|
||||
Durability is a plugin concern. Backends copy synchronous `session/event` notifications into fixed-window durable batches; `session/flush` bypasses the wait before requests and top-level tool dispatch, then follows `turn/end` before another queued turn or idle observation. A listener returns literal `true` only after durability work completes; a successful acknowledged barrier publishes contained `session/flushed(session, throughSeq)` with the exclusive event boundary captured at entry, so commit-aware projections can advance without treating append notification as durability. `SessionPersistence` stores events and header metadata; JSONL defaults to checksummed Zstandard and SQLite shares the contract ([checkpoint decision](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md), [batching decision](../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)).
|
||||
Durability is a plugin concern. Backends copy synchronous `session/event` notifications into fixed-window durable batches; `session/flush` bypasses the wait before requests and top-level tool dispatch, and after `turn/end` before another turn or idle. `SessionPersistence` stores events and header metadata; JSONL defaults to checksummed Zstandard and SQLite shares the contract ([checkpoint decision](../.agents/notes/implemented/bug-fix/2026-07-21-semantic-session-checkpoints.md), [batching decision](../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)).
|
||||
|
||||
Between turns, owners append log-only events through `Session`, flushing only for durability. `session/title` relies on bounded background persistence and lifecycle drains; manual compaction flushes its bracket before the operation completes. Title work never delays responses; the latest title event wins, and it records the source message seqs and whether the user, fallback, or provider supplied it. Title records are inherited fork boundaries ([decision](../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md)).
|
||||
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/config-catalog.md
|
||||
config-catalog.md: 5f3bc744b25bf20d50e88ce75812fe8bd624905a
|
||||
config-catalog.zh.md: a7d4252c526d36643a1b9f7aebd627faa60e1c77
|
||||
config-catalog.md: 5c4b80be5159455589d48a4f185393426a198833
|
||||
config-catalog.zh.md: 4f18b898f57e1c135e20e51544aa08c1127e547b
|
||||
|
||||
@@ -2593,7 +2593,6 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
|
||||
- `@deepseek-ai/dsh-client-ui-permission` ([`packages/client/ui-permission/src/index.ts`](../packages/client/ui-permission/src/index.ts))
|
||||
- `@deepseek-ai/dsh-client-ui-plan` ([`packages/client/ui-plan/src/index.ts`](../packages/client/ui-plan/src/index.ts))
|
||||
- `@deepseek-ai/dsh-client-ui-question` — requires `tools` · `userInteraction` ([`packages/client/ui-question/src/index.ts`](../packages/client/ui-question/src/index.ts))
|
||||
- `@deepseek-ai/dsh-client-ui-schedule` ([`packages/client/ui-schedule/src/index.ts`](../packages/client/ui-schedule/src/index.ts))
|
||||
- `@deepseek-ai/dsh-client-ui-settings` ([`packages/client/ui-settings/src/index.ts`](../packages/client/ui-settings/src/index.ts))
|
||||
- `@deepseek-ai/dsh-client-ui-settings-general` ([`packages/client/ui-settings-general/src/index.ts`](../packages/client/ui-settings-general/src/index.ts))
|
||||
- `@deepseek-ai/dsh-client-ui-sidebar` ([`packages/client/ui-sidebar/src/index.ts`](../packages/client/ui-sidebar/src/index.ts))
|
||||
@@ -2626,6 +2625,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
|
||||
- `@deepseek-ai/dsh-tasks-local` ([`packages/tasks/tasks-local/src/index.ts`](../packages/tasks/tasks-local/src/index.ts))
|
||||
- `@deepseek-ai/dsh-timeout-policy` — requires `tools` ([`packages/guard/timeout-policy/src/index.ts`](../packages/guard/timeout-policy/src/index.ts))
|
||||
- `@deepseek-ai/dsh-tool-ask-user` — requires `tools` · `userInteraction` ([`packages/interaction/tool-ask-user/src/index.ts`](../packages/interaction/tool-ask-user/src/index.ts))
|
||||
- `@deepseek-ai/dsh-tool-schedule` — requires `agents` · `sessions` · `tools` · `sessionPersistence` ([`packages/schedule/tool-schedule/src/index.ts`](../packages/schedule/tool-schedule/src/index.ts))
|
||||
- `@deepseek-ai/dsh-tool-subagent-control` — requires `tools` · `subagents` ([`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts))
|
||||
- `@deepseek-ai/dsh-user-interaction` ([`packages/interaction/user-interaction/src/index.ts`](../packages/interaction/user-interaction/src/index.ts))
|
||||
- `@deepseek-ai/dsh-workspace` — requires `storageDomain` · `sessionPersistence` ([`packages/workspace/workspace/src/index.ts`](../packages/workspace/workspace/src/index.ts))
|
||||
|
||||
@@ -2626,6 +2626,7 @@ export interface Config {
|
||||
- `@deepseek-ai/dsh-tasks-local`（[`packages/tasks/tasks-local/src/index.ts`](../packages/tasks/tasks-local/src/index.ts)）
|
||||
- `@deepseek-ai/dsh-timeout-policy` — 需要 `tools`（[`packages/guard/timeout-policy/src/index.ts`](../packages/guard/timeout-policy/src/index.ts)）
|
||||
- `@deepseek-ai/dsh-tool-ask-user` — 需要 `tools` · `userInteraction`（[`packages/interaction/tool-ask-user/src/index.ts`](../packages/interaction/tool-ask-user/src/index.ts)）
|
||||
- `@deepseek-ai/dsh-tool-schedule` — 需要 `agents` · `sessions` · `tools` · `sessionPersistence`（[`packages/schedule/tool-schedule/src/index.ts`](../packages/schedule/tool-schedule/src/index.ts)）
|
||||
- `@deepseek-ai/dsh-tool-subagent-control` — 需要 `tools` · `subagents`（[`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts)）
|
||||
- `@deepseek-ai/dsh-user-interaction`（[`packages/interaction/user-interaction/src/index.ts`](../packages/interaction/user-interaction/src/index.ts)）
|
||||
- `@deepseek-ai/dsh-workspace` — 需要 `storageDomain` · `sessionPersistence`（[`packages/workspace/workspace/src/index.ts`](../packages/workspace/workspace/src/index.ts)）
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/event-producer-consumer.md
|
||||
event-producer-consumer.md: 5b36725402c0a12c5e2a09c743c2e7cf28d2c14a
|
||||
event-producer-consumer.zh.md: 2d4c805f9a5d3b0531ee59eebe9e6564347f0a00
|
||||
event-producer-consumer.md: 840f935dbe982c44b11feccedca90d75a5b4c661
|
||||
event-producer-consumer.zh.md: 2b9f457168e5c4e877d5de04bc63290377f9403a
|
||||
|
||||
@@ -8,7 +8,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
|
||||
| Event | Mode | Declared in | Dispatchers | Listeners |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:182`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
|
||||
| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:158`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session) |
|
||||
| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:158`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session), [`tool-schedule`](../packages/schedule/tool-schedule) |
|
||||
| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:167`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
|
||||
| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:289`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/session/session-telemetry) |
|
||||
| `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/types.ts:196`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
|
||||
@@ -18,7 +18,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
|
||||
| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:243`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
|
||||
| `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:259`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
|
||||
| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:216`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
|
||||
| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), `server` |
|
||||
| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), `server`, [`tool-schedule`](../packages/schedule/tool-schedule) |
|
||||
| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:277`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
|
||||
| `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
|
||||
| `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:172`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
|
||||
@@ -64,7 +64,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
|
||||
| `commands/changed` | `runtime` (`emit`) | `ui-command` |
|
||||
| `connection/reset` | `runtime` (`emit`) | `ui-command`, `ui-models`, `ui-permission`, `ui-settings-general` |
|
||||
| `credentials/changed` | `runtime` (`emit`) | `ui-models` |
|
||||
| `internal/dispatch` | - | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/interaction/permission), [`plan-mode`](../packages/plan/plan-mode), [`pty-local`](../packages/pty/pty-local), `runtime`, [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`workflow`](../packages/workflow/workflow) |
|
||||
| `internal/dispatch` | - | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/interaction/permission), [`plan-mode`](../packages/plan/plan-mode), [`pty-local`](../packages/pty/pty-local), `runtime`, [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-schedule`](../packages/schedule/tool-schedule), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`workflow`](../packages/workflow/workflow) |
|
||||
| `internal/plugin` | - | `hmr`, `loader`, [`lsp-local`](../packages/lsp/lsp-local), `modules`, `webserver` |
|
||||
| `internal/service` | - | `gateway` |
|
||||
| `internal/status` | - | [`agent`](../packages/core/agent) |
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
| 事件 | 模式 | 声明位置 | 派发方 | 监听方 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:182`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | - |
|
||||
| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:158`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session) |
|
||||
| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:158`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session), [`tool-schedule`](../packages/schedule/tool-schedule) |
|
||||
| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:167`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
|
||||
| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:289`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/session/session-telemetry) |
|
||||
| `agent/inbox/claimed` | `emit` | [`packages/core/agent/src/types.ts:196`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`acp`](../packages/acp/acp), [`goal-session`](../packages/goal/goal-session), [`subagent`](../packages/subagent/subagent) |
|
||||
@@ -20,7 +20,7 @@
|
||||
| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:243`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
|
||||
| `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:259`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
|
||||
| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:216`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
|
||||
| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), `server` |
|
||||
| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), `server`, [`tool-schedule`](../packages/schedule/tool-schedule) |
|
||||
| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:277`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
|
||||
| `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
|
||||
| `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:172`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |
|
||||
@@ -32,7 +32,7 @@
|
||||
| `goal/changed` | `emit` | [`packages/goal/goal/src/domain.ts:114`](../packages/goal/goal/src/domain.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
|
||||
| `llm/adapters-updated` | `emit` | [`packages/llm/llm/src/index.ts:73`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`events.dispatch`) | `apiproxy`, [`llm`](../packages/llm/llm) |
|
||||
| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:62`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay), [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), [`session-title`](../packages/session/session-title) |
|
||||
| `session/created` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/interaction/permission), [`plan-mode`](../packages/plan/plan-mode), `server`, [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
|
||||
| `session/created` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | `apiproxy`, [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/interaction/permission), [`plan-mode`](../packages/plan/plan-mode), `server`, [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry), [`tool-schedule`](../packages/schedule/tool-schedule), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) |
|
||||
| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:84`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`session-persistence`](../packages/session/session-persistence), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title) |
|
||||
| `session/event` | `emit` | [`packages/core/session/src/index.ts:96`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-loop`](../packages/core/agent-loop), `apiproxy`, [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`loader-smoke`](../packages/support/loader-smoke), `server`, [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`workspace-context`](../packages/context/workspace-context) |
|
||||
| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:105`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session/session-persistence), [`session-telemetry`](../packages/session/session-telemetry) |
|
||||
@@ -66,7 +66,7 @@
|
||||
| `commands/changed` | `runtime` (`emit`) | `ui-command` |
|
||||
| `connection/reset` | `runtime` (`emit`) | `ui-command`, `ui-models`, `ui-permission`, `ui-settings-general` |
|
||||
| `credentials/changed` | `runtime` (`emit`) | `ui-models` |
|
||||
| `internal/dispatch` | - | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/interaction/permission), [`plan-mode`](../packages/plan/plan-mode), [`pty-local`](../packages/pty/pty-local), `runtime`, [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`workflow`](../packages/workflow/workflow) |
|
||||
| `internal/dispatch` | - | [`commands`](../packages/interaction/commands), [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/interaction/permission), [`plan-mode`](../packages/plan/plan-mode), [`pty-local`](../packages/pty/pty-local), `runtime`, [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-schedule`](../packages/schedule/tool-schedule), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`workflow`](../packages/workflow/workflow) |
|
||||
| `internal/plugin` | - | `hmr`, `loader`, [`lsp-local`](../packages/lsp/lsp-local), `modules`, `webserver` |
|
||||
| `internal/service` | - | `gateway` |
|
||||
| `internal/status` | - | [`agent`](../packages/core/agent) |
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/module-graph.md
|
||||
module-graph.md: e7d6b47e709c3edf4dcdb506bd8f2be0c717aaab
|
||||
module-graph.zh.md: 255253bcfa9cfad1ab85602dfa9f953a02dfc427
|
||||
module-graph.md: e3d58401db3ca81966b701e35325f8b094f8ac0a
|
||||
module-graph.zh.md: c1095a5865532d6ddc8fa0ca89e9f7e098236b5c
|
||||
|
||||
@@ -240,6 +240,9 @@ flowchart TD
|
||||
pkg_sdk_protocol["sdk-protocol"]
|
||||
pkg_telemetry["telemetry"]
|
||||
end
|
||||
subgraph group_schedule["packages/schedule"]
|
||||
pkg_tool_schedule["tool-schedule"]
|
||||
end
|
||||
subgraph group_self_modification["packages/self-modification"]
|
||||
pkg_repository_plugin["repository-plugin"]
|
||||
pkg_tool_cordis["tool-cordis"]
|
||||
@@ -932,6 +935,13 @@ flowchart TD
|
||||
pkg_tool_pty --> pkg_system_prompt
|
||||
pkg_tool_pty --> pkg_tasks
|
||||
pkg_tool_pty --> pkg_tools
|
||||
pkg_tool_schedule --> pkg_agent
|
||||
pkg_tool_schedule --> pkg_brand
|
||||
pkg_tool_schedule --> pkg_invariants
|
||||
pkg_tool_schedule --> pkg_llm
|
||||
pkg_tool_schedule --> pkg_session
|
||||
pkg_tool_schedule --> pkg_session_persistence
|
||||
pkg_tool_schedule --> pkg_tools
|
||||
pkg_tool_cordis --> pkg_invariants
|
||||
pkg_tool_cordis --> pkg_scope
|
||||
pkg_tool_cordis --> pkg_tools
|
||||
@@ -1338,6 +1348,7 @@ flowchart TD
|
||||
| [`mcp-client`](../packages/mcp/mcp-client) | `mcp` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subprocess`](../packages/subprocess/subprocess), [`tools`](../packages/core/tools) |
|
||||
| [`tool-bash-persistent`](../packages/pty/tool-bash-persistent) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
|
||||
| [`tool-pty`](../packages/pty/tool-pty) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`pty`](../packages/pty/pty), [`retention`](../packages/util/retention), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
|
||||
| [`tool-schedule`](../packages/schedule/tool-schedule) | `schedule` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
|
||||
| [`tool-cordis`](../packages/self-modification/tool-cordis) | `self-modification` | [`invariants`](../packages/support/invariants), [`scope`](../packages/core/scope), [`tools`](../packages/core/tools) |
|
||||
| [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy) | `session` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
|
||||
| [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | `session` | [`brand`](../packages/util/brand), [`command-feedback`](../packages/feedback/command-feedback), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) |
|
||||
|
||||
@@ -242,6 +242,9 @@ flowchart TD
|
||||
pkg_sdk_protocol["sdk-protocol"]
|
||||
pkg_telemetry["telemetry"]
|
||||
end
|
||||
subgraph group_schedule["packages/schedule"]
|
||||
pkg_tool_schedule["tool-schedule"]
|
||||
end
|
||||
subgraph group_self_modification["packages/self-modification"]
|
||||
pkg_repository_plugin["repository-plugin"]
|
||||
pkg_tool_cordis["tool-cordis"]
|
||||
@@ -934,6 +937,13 @@ flowchart TD
|
||||
pkg_tool_pty --> pkg_system_prompt
|
||||
pkg_tool_pty --> pkg_tasks
|
||||
pkg_tool_pty --> pkg_tools
|
||||
pkg_tool_schedule --> pkg_agent
|
||||
pkg_tool_schedule --> pkg_brand
|
||||
pkg_tool_schedule --> pkg_invariants
|
||||
pkg_tool_schedule --> pkg_llm
|
||||
pkg_tool_schedule --> pkg_session
|
||||
pkg_tool_schedule --> pkg_session_persistence
|
||||
pkg_tool_schedule --> pkg_tools
|
||||
pkg_tool_cordis --> pkg_invariants
|
||||
pkg_tool_cordis --> pkg_scope
|
||||
pkg_tool_cordis --> pkg_tools
|
||||
@@ -1340,6 +1350,7 @@ flowchart TD
|
||||
| [`mcp-client`](../packages/mcp/mcp-client) | `mcp` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subprocess`](../packages/subprocess/subprocess), [`tools`](../packages/core/tools) |
|
||||
| [`tool-bash-persistent`](../packages/pty/tool-bash-persistent) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`pty`](../packages/pty/pty), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
|
||||
| [`tool-pty`](../packages/pty/tool-pty) | `pty` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`pty`](../packages/pty/pty), [`retention`](../packages/util/retention), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
|
||||
| [`tool-schedule`](../packages/schedule/tool-schedule) | `schedule` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
|
||||
| [`tool-cordis`](../packages/self-modification/tool-cordis) | `self-modification` | [`invariants`](../packages/support/invariants), [`scope`](../packages/core/scope), [`tools`](../packages/core/tools) |
|
||||
| [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy) | `session` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`tools`](../packages/core/tools) |
|
||||
| [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | `session` | [`brand`](../packages/util/brand), [`command-feedback`](../packages/feedback/command-feedback), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) |
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/persistence-catalog.md
|
||||
persistence-catalog.md: 614f6afbeb8fbaadbb43a76782c5a345180b25e7
|
||||
persistence-catalog.zh.md: 364912b88c3b2c5efd92a616034be9ef5025ee67
|
||||
persistence-catalog.md: 86538551c543bea208ada8682fe6c07e0f048b0a
|
||||
persistence-catalog.zh.md: d8b319fd15576755d6c891cdd104b4e5f4bae3b6
|
||||
|
||||
@@ -526,7 +526,7 @@ Source: [`packages/sandbox/sandbox-policy/src/session-mode.ts:33`](../packages/s
|
||||
'schedule/change': ScheduleChange
|
||||
```
|
||||
|
||||
Source: [`packages/schedule/tool-schedule/src/types.ts:154`](../packages/schedule/tool-schedule/src/types.ts)
|
||||
Source: [`packages/schedule/tool-schedule/src/types.ts:144`](../packages/schedule/tool-schedule/src/types.ts)
|
||||
|
||||
### `session/*`
|
||||
|
||||
|
||||
@@ -516,6 +516,20 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
|
||||
来源：[`packages/sandbox/sandbox-policy/src/session-mode.ts:33`](../packages/sandbox/sandbox-policy/src/session-mode.ts)
|
||||
|
||||
### `schedule/*`
|
||||
|
||||
#### `schedule/change` — log-only
|
||||
|
||||
```ts persistence-catalog
|
||||
/**
|
||||
* Versioned Schedule mutation. The owning package validates the complete
|
||||
* session-local transition stream before accepting a candidate event.
|
||||
*/
|
||||
'schedule/change': ScheduleChange
|
||||
```
|
||||
|
||||
来源：[`packages/schedule/tool-schedule/src/types.ts:144`](../packages/schedule/tool-schedule/src/types.ts)
|
||||
|
||||
### `session/*`
|
||||
|
||||
#### `session/end-seed` — log-only
|
||||
|
||||
@@ -10,8 +10,6 @@ The seam is a textbook [capability seam](../../.agents/notes/implemented/archite
|
||||
|
||||
`session/event` is a *synchronous* notification; persistence plugins copy the event into a per-session controller without blocking the producer. The first pending event starts a fixed batching window, and later events join without resetting its deadline. Expiry starts one durable batch; events admitted during that write receive their own deadline and form a follow-up batch. `session/flush` cancels the wait and drains through quiescence, so the loop still uses it as the ordering and error-observation checkpoint before claiming the next ordinary turn. A rejected background write retains its events and pauses automatic retry; a new event starts a fresh window, while explicit flush retries immediately and reports failure through `agent/error` and the logger, never as a session event past the closed turn. Disposal performs the same final drain. The configured maximum bounds only intentional batching wait, not event-loop scheduling or backend durability latency ([decision](../../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)).
|
||||
|
||||
A `session/flush` listener returns literal `true` only after completing durability work; observe-only listeners return void. Once every listener settles, `SessionStore.flush()` returns `true` and publishes contained `session/flushed(session, throughSeq)` only when at least one listener acknowledged durability and none failed. `throughSeq` is the exclusive event boundary captured at call entry, so events appended during the checkpoint require a later success; concurrent checkpoints may publish boundaries out of order. An empty or observe-only checkpoint returns `false`, and a rejection publishes no success observation.
|
||||
|
||||
## Crash recovery preserves an interrupted turn
|
||||
|
||||
A backend that reloads a log crashed mid-turn finds an open `turn/start` with no `turn/end`. It does **not** truncate — a single turn can be huge in a long-horizon task (many steps, large tool output), and those events were durably appended before the crash. Instead it closes the orphaned turn with a synthetic `turn/end { reason: { kind: 'interrupted' } }`, keeping the interrupted execution balanced without changing any standalone events before or after it. `interrupted` is the one `TurnEndReason` no loop emits (see [session.md](session.md#why-a-turn-ended-turnendreasonmap)).
|
||||
|
||||
@@ -10,8 +10,6 @@
|
||||
|
||||
`session/event` 是一个*同步*通知；持久化插件会将事件复制到逐会话控制器，而不阻塞生产方。第一个待处理事件会开启固定批处理窗口，后续事件会加入但不会重置截止时间。窗口到期后会启动一个持久化批次；该次写入期间接纳的事件会获得自己的截止时间，并形成后续批次。`session/flush` 会取消等待并排空至完全停稳，因此循环仍将其用作在领取下一个普通轮次之前的顺序与错误观察检查点。后台写入被拒绝时会保留对应事件并暂停自动重试；新事件会开启新的固定窗口，而显式 flush 会立即重试，并通过 `agent/error` 和 logger 报告失败，绝不会把失败记录成已关闭轮次之后的会话事件。dispose（资源释放）会执行同样的最终排空。配置的最大值只限制有意的批处理等待，不限制事件循环调度或后端完成持久化的延迟（[决策](../../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)）。
|
||||
|
||||
`session/flush` 监听器只有在完成持久性工作后才返回字面量 `true`；仅观察监听器返回 void。每个监听器都结算后，仅当至少一个监听器确认持久性且没有监听器失败时，`SessionStore.flush()` 才返回 `true`，并以失败收容方式发布 `session/flushed(session, throughSeq)`。`throughSeq` 是调用入口捕获的事件排他边界，因此检查点期间追加的事件需要后续另一次成功；并发检查点可能不按顺序发布边界。空检查点或仅观察检查点返回 `false`，出现拒绝时不会发布成功观测。
|
||||
|
||||
## 崩溃恢复保留被中断的轮次
|
||||
|
||||
后端重新加载一个在轮次中途崩溃的日志时，会发现一个已打开的 `turn/start` 却没有 `turn/end`。它**不会**截断日志：在长周期任务中，单个轮次可能非常庞大（许多步骤、大量工具输出），而这些事件在崩溃前已被持久追加。后端改为用一个合成的 `turn/end { reason: { kind: 'interrupted' } }` 关闭这个遗留轮次，在不改变其前后任何独立事件的情况下配平被中断的执行。`interrupted` 是唯一一个不由循环发出的 `TurnEndReason`（见 [session.md](session.md#why-a-turn-ended-turnendreasonmap)）。
|
||||
|
||||
@@ -156,7 +156,7 @@ type SubagentInterruptAuthority =
|
||||
|
||||
Every Activation owns its `AgentHandle` and an `ownedChildren: Set<SessionId>`; because one Session has at most one live Activation, the child Session id identifies the live child without another runtime-incarnation reference. Starting a child or submitting parent-originated work registers the child in a continuation-managed parent's set before the child can run, and that parent cannot settle while the set is non-empty. A top-level or other non-continuation Agent has no Activation and stays outside the waiting graph. Child release happens only after the child Agent is quiescent, every child of that child is disposed, the best-effort final session flush settles, and the child's `AgentHandle` completes disposal.
|
||||
|
||||
Final settlement awaits `ctx.sessions.flush(session)` but deliberately does not make its durability acknowledgement a release condition because continuation teardown is best effort. A `false` result still disposes the handle and releases ownership; rejection is logged without failing the Activation, and the persisted child state may then be missing or stale on a later resume. Manager unload invokes an internal manager-wide drain that closes admission and disposes every live forest; `drainContinuableDescendants(parents)` closes admission only below exact live host-owned Agents and disposes their continuable descendants while unrelated forests remain live. Both await already-admitted materializations in their scope, propagate cancellation top-down, release handles child-first, and await every selected branch despite individual failures. Durable child Sessions survive that process-local teardown.
|
||||
Final settlement awaits `ctx.sessions.flush(session)` but ignores its participation boolean because an arbitrary listener cannot prove that a persistence backend stored the state. Rejection is logged without failing the Activation, and the manager still disposes the handle and releases ownership; the persisted child state may then be missing or stale on a later resume. Manager unload invokes an internal manager-wide drain that closes admission and disposes every live forest; `drainContinuableDescendants(parents)` closes admission only below exact live host-owned Agents and disposes their continuable descendants while unrelated forests remain live. Both await already-admitted materializations in their scope, propagate cancellation top-down, release handles child-first, and await every selected branch despite individual failures. Durable child Sessions survive that process-local teardown.
|
||||
|
||||
```ts type-equiv
|
||||
/** Attribution for a model coordinator's follow-up to one of its children. */
|
||||
|
||||
@@ -156,7 +156,7 @@ type SubagentInterruptAuthority =
|
||||
|
||||
每个 Activation 都拥有自己的 `AgentHandle` 和一个 `ownedChildren: Set<SessionId>`；由于一份会话至多有一个存活 Activation，子会话 id 无需另一个运行时化身引用即可标识存活的子 agent。启动子 agent 或提交源自 parent 的工作，会在子 agent 能够运行之前将其注册到受继续执行管理的父级集合中；只要该集合非空，该父级就无法 settle。顶层或其他非继续执行的 Agent 没有 Activation，处于 waiting 图之外。只有当子 Agent 已完全停稳、该子 agent 的每个子级都已 dispose、best-effort 的最终会话 flush 结算完毕，且子 agent 的 `AgentHandle` 完成 dispose 之后，才会释放子 agent。
|
||||
|
||||
最终结算会等待 `ctx.sessions.flush(session)`，但由于继续执行拆卸采用 best-effort，明确不把其持久性确认作为释放条件。结果为 `false` 时仍会 dispose 该 handle 并释放所有权；rejection 会被记录，但不会使 Activation 失败，此后持久化的子 agent 状态在后续恢复时可能缺失或陈旧。管理器卸载会调用内部的管理器全局 drain，关闭准入并 dispose 每片在线森林；`drainContinuableDescendants(parents)` 只关闭由 host 确切拥有的在线 Agent 之下的准入，并 dispose 其可继续后代，而无关森林保持在线。两者都会等待各自作用域内已获准的物化过程，自顶向下传播取消，按 child-first 顺序释放 handle，并且即使个别分支失败也会等待所有选中分支。持久化子会话不受该进程内拆卸的影响。
|
||||
最终结算会等待 `ctx.sessions.flush(session)`，但会忽略其参与布尔值，因为任意 listener 都无法证明某个持久化后端已存储该状态。rejection 会被记录，但不会使 Activation 失败；管理器仍会 dispose 该 handle 并释放所有权，此后持久化的子 agent 状态在后续恢复时可能缺失或陈旧。管理器卸载会调用内部的管理器全局 drain，关闭准入并 dispose 每片在线森林；`drainContinuableDescendants(parents)` 只关闭由 host 确切拥有的在线 Agent 之下的准入，并 dispose 其可继续后代，而无关森林保持在线。两者都会等待各自作用域内已获准的物化过程，自顶向下传播取消，按 child-first 顺序释放 handle，并且即使个别分支失败也会等待所有选中分支。持久化子会话不受该进程内拆卸的影响。
|
||||
|
||||
```ts type-equiv
|
||||
/** Attribution for a model coordinator's follow-up to one of its children. */
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/tool-catalog.md
|
||||
tool-catalog.md: f6a41da266db6eb2f347fb3c455a67b4dd44c4c0
|
||||
tool-catalog.zh.md: b36e8ccf63f4bdde7efca050bd92cbfcb03b3fbb
|
||||
tool-catalog.md: fad163c41b6f645d1d5e91d3b550fa74e3a63903
|
||||
tool-catalog.zh.md: e6777f666cba84a5743cecbe2131e3d5caef88f0
|
||||
|
||||
@@ -29,6 +29,7 @@
|
||||
| `@deepseek-ai/dsh-tool-fs-search` | `glob`、`grep` | `ctx.tools`、`ctx.subprocess`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | glob 和 grep 是无条件可用的发现工具，通过 ctx.subprocess spawn 随包提供的 ripgrep 二进制文件（`@vscode/ripgrep`），并作为普通前台调用运行，绝不作为后台任务；无需在宿主机安装 `rg`，也不经过 shell 层。本目录使用 `sampleOverCapGlobResults: true`；部署必须显式选择该行为。结果超过上限时，会通过可选的 ctx.spillStore 后端保存完整的格式化列表；在共置部署中，如果后端公开本地路径，返回的定位信息可供后续读取／搜索。 |
|
||||
| `@deepseek-ai/dsh-tool-pty` | `terminal_close`、`terminal_list`、`terminal_open`、`terminal_read`、`terminal_send`、`terminal_signal` | `ctx.tools`、`ctx.pty`、`ctx.systemPrompt`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | 这 6 个终端工具需要选择启用，用于补充一次性 bash／文件系统工具。`terminal_send(run_in_background: true)` 会注册到 `ctx.tasks`；schema 不包含 TUI、具名按键序列、BEL、调整尺寸、自动启动和跨 agent 共享。 |
|
||||
| `@deepseek-ai/dsh-tool-goal` | `create_goal`、`get_goal`、`update_goal` | `ctx.tools`、`ctx.agents`、`ctx.goals`、`ctx.systemPrompt`、`a calling Agent in an authorized open turn` | `tool/call`、`goal/change for mutations`、`tool/result` | - | create、edit、pause 和 resume 要求直接来自人类的根权限；complete 和 blocked 也接受确切的当前 Goal Round。blocked 的默认下限是 3 个获准的 Round。 |
|
||||
| `@deepseek-ai/dsh-tool-schedule` | `schedule_create`、`schedule_delete`、`schedule_list` | `ctx.tools`、`ctx.sessions`、Session 持久化、未来创建的 live 根 Agent | `tool/call`、`schedule/change create or delete`、`tool/result` | - | 仅在选择启用的 Schedule 插件加载后创建的 live 根 Agent scope 内注册。版本 1 接受正的安全整数 after_seconds，并披露 session-local 交付；管理读取与变更必须通过共享的 Session 持久化 barrier。 |
|
||||
| `@deepseek-ai/dsh-tool-lsp` | `lsp` | `ctx.tools`、`ctx.lsp`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | lsp 工具将提供方选择和语言服务器子进程置于 ctx.lsp 之后，因此其模型可见 schema 在更换提供方时保持稳定。运行时要求已注册提供方，例如 `@deepseek-ai/dsh-lsp-local`；如果没有提供方，查询会返回结构化 `LSP_UNAVAILABLE` 错误，而不会改变 schema。 |
|
||||
| `@deepseek-ai/dsh-tool-ralph` | `ralph` | `ctx.tools`、`ctx.workflows`、`ctx.subagents`、`ctx.systemPrompt`、`a calling Agent (exec.agent parents every fresh round)` | `tool/call`、`tool/result`、`workflow and child session events during execution` | - | 固定的前台工作流会在每个 Round 启动一个全新的结构化子级；模型只能选择不可变目标和可选的 Round 上限。 |
|
||||
| `@deepseek-ai/dsh-tool-skill` | `skill` | `ctx.tools`、`ctx.agents`、`ctx.skills` | `tool/call`、`tool/result`、`user/message replacement catalogs via agent.inject()` | - | - |
|
||||
@@ -830,6 +831,70 @@ glob 和 grep 是无条件可用的发现工具，通过 ctx.subprocess spawn
|
||||
|
||||
create、edit、pause 和 resume 要求直接来自人类的根权限；complete 和 blocked 也接受确切的当前 Goal Round。blocked 的默认下限是 3 个获准的 Round。
|
||||
|
||||
## `@deepseek-ai/dsh-tool-schedule`
|
||||
|
||||
### `schedule_create`
|
||||
|
||||
在当前会话中创建一条提醒。v1 只接受非空 prompt 和正的安全整数 after_seconds 延时。交付模式是 session-local：只有此会话处于 live 状态时，提醒才会准时运行；否则提醒会进入 overdue 状态，直至会话恢复。
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"prompt": {
|
||||
"type": "string",
|
||||
"description": "Reminder content to present when the target becomes due."
|
||||
},
|
||||
"after_seconds": {
|
||||
"type": "number",
|
||||
"description": "Positive safe-integer delay in seconds."
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"prompt",
|
||||
"after_seconds"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
来源：[`packages/schedule/tool-schedule/src/tools.ts`](../packages/schedule/tool-schedule/src/tools.ts)
|
||||
|
||||
### `schedule_delete`
|
||||
|
||||
使用 schedule_create 或 schedule_list 返回的确切 id，删除当前会话中的一条活动提醒。未知或已经结束的 id 会返回 deleted false。
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"description": "Exact session-local schedule id."
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"id"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
来源：[`packages/schedule/tool-schedule/src/tools.ts`](../packages/schedule/tool-schedule/src/tools.ts)
|
||||
|
||||
### `schedule_list`
|
||||
|
||||
按创建顺序列出当前会话中的所有活动提醒，包括确切 id、UTC 目标、scheduled 或 overdue 状态，以及 session-local 交付模式。
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {}
|
||||
}
|
||||
```
|
||||
|
||||
来源：[`packages/schedule/tool-schedule/src/tools.ts`](../packages/schedule/tool-schedule/src/tools.ts)
|
||||
|
||||
仅在选择启用的 Schedule 插件加载后创建的 live 根 Agent scope 内注册。版本 1 接受正的安全整数 after_seconds，并披露 session-local 交付；管理读取与变更必须通过共享的 Session 持久化 barrier。
|
||||
|
||||
## `@deepseek-ai/dsh-tool-lsp`
|
||||
|
||||
### `lsp`
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write examples/README.md
|
||||
README.md: 209b23d6325b1ed0db8f23ab049369efc9427af4
|
||||
README.zh.md: 5a9e5615d8ccef2c1627e3facf97a30a25e1fb5e
|
||||
README.md: 826e15e461d2544d664ce73683031b8cc0307595
|
||||
README.zh.md: 97f6722f9bf16073af5605ff5c3d3efb8fddf435
|
||||
|
||||
@@ -22,7 +22,7 @@ A self-referential agent that can inspect and change its in-memory Cordis plugin
|
||||
|
||||
## web-schedule
|
||||
|
||||
An opt-in Web overlay for durable, Session-local reminders. It supports positive whole-second `after_seconds` reminders through `schedule_create`, `schedule_list`, and `schedule_delete`; active reminders persist in the original Session, resume when that Session becomes live again, and do not run while it is cold. Run `dsh web --patch examples/web-schedule/cordis.yml`; see [web-schedule/README.md](web-schedule/README.md) for the delivery and recovery boundary.
|
||||
An opt-in Web overlay for durable, Session-local scheduled follow-ups. See the [Web Schedule example reference](web-schedule/README.md).
|
||||
|
||||
## acp-agent
|
||||
|
||||
|
||||
@@ -22,7 +22,7 @@
|
||||
|
||||
## web-schedule
|
||||
|
||||
用于持久、仅限 Session 内提醒的显式 Web overlay。它通过 `schedule_create`、`schedule_list` 和 `schedule_delete` 支持正整数秒的 `after_seconds` 提醒；活动提醒保存在原 Session 中，该 Session 再次 live 时恢复，而 cold 期间不会运行。使用 `dsh web --patch examples/web-schedule/cordis.yml` 启动；交付与恢复边界详见 [web-schedule/README.md](web-schedule/README.md)。
|
||||
一个可显式启用的 Web overlay，用于提供持久且仅限会话内的定时后续轮次。详见 [Web Schedule 示例参考](web-schedule/README.md)。
|
||||
|
||||
## acp-agent
|
||||
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write examples/web-schedule/README.md
|
||||
README.md: 4071bdb4f52ccd75359a91ad8269d1bc18bae521
|
||||
README.zh.md: 10db04f9ec494d86c93141ace4f6f56fa79deaca
|
||||
README.md: 6849f1cf086074e54c16344500e98fe4a6f9c07c
|
||||
README.zh.md: 6d3597d30a992acf6e80f820fa6a09d5a995c056
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Durable Web Schedule
|
||||
# Session-local Schedule
|
||||
|
||||
English | [中文](README.zh.md)
|
||||
|
||||
This overlay opts one `dsh web` process into durable Schedule reminders without changing the shipped default Web composition:
|
||||
This overlay opts one `dsh web` process into Schedule reminders without changing the shipped default Web composition:
|
||||
|
||||
```sh
|
||||
dsh web --patch examples/web-schedule/cordis.yml
|
||||
@@ -10,8 +10,8 @@ dsh web --patch examples/web-schedule/cordis.yml
|
||||
|
||||
The current overlay supports one-shot reminders created with a positive whole-number `after_seconds`. The model manages them through `schedule_create`, `schedule_list`, and `schedule_delete`; every result identifies the delivery mode as `session-local`.
|
||||
|
||||
The original Session log owns each reminder. A live root Agent waits, retries after it becomes idle, and records a durable dispatch receipt in the Web conversation. Closing the process or leaving the Session cold stops its in-memory timer without deleting the record; reopening that same Session restores the wait and delivers an overdue reminder. Merely reading cold history never activates it, and a fork does not inherit its parent's reminders.
|
||||
The original Session log owns each reminder. A live root Agent waits and retries after it becomes idle, then queues a normal follow-up turn in that conversation. Closing the process or leaving the Session cold stops its in-memory timer without deleting the record; reopening that same Session restores the wait and delivers an overdue reminder. Merely reading cold history never activates it, and a fork does not inherit its parent's reminders.
|
||||
|
||||
Create and actual delete operations acknowledge success only after Session persistence confirms their event prefix. A reminder receipt likewise appears only after its dispatch is durable. Schedule does not provide browser, operating-system, email, SMS, or other external notification, and the best-effort model follow-up is not a delivery acknowledgement.
|
||||
Create and actual delete operations acknowledge success only after Session persistence confirms their event prefix. Schedule does not provide browser, operating-system, email, SMS, or other external notification. A durable dispatch records that the follow-up was queued; it does not acknowledge model success or user receipt.
|
||||
|
||||
Absolute-time, fixed-interval, and cron rules are not accepted by this layer.
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# 持久 Web Schedule
|
||||
# 仅限 Session 内的 Schedule
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
此 overlay 让一个 `dsh web` 进程显式启用持久 Schedule 提醒，同时不改变交付的默认 Web 组合：
|
||||
此 overlay 让一个 `dsh web` 进程显式启用 Schedule 提醒，同时不改变交付的默认 Web 组合：
|
||||
|
||||
```sh
|
||||
dsh web --patch examples/web-schedule/cordis.yml
|
||||
@@ -10,8 +10,8 @@ dsh web --patch examples/web-schedule/cordis.yml
|
||||
|
||||
当前 overlay 支持使用正整数 `after_seconds` 创建的一次性提醒。模型通过 `schedule_create`、`schedule_list` 和 `schedule_delete` 管理它们；每个结果都会把交付模式标为 `session-local`。
|
||||
|
||||
每条提醒由原 Session 日志拥有。live 根 Agent 会等待，在恢复 idle 后重试，并在 Web 会话中记录持久 dispatch 回执。关闭进程或让 Session 保持 cold 会停止内存 timer，但不会删除记录；重新打开同一个 Session 会恢复等待并交付逾期提醒。仅查看 cold 历史不会激活提醒，fork 也不会继承父 Session 的提醒。
|
||||
每条提醒由原 Session 日志拥有。live 根 Agent 会等待并在恢复 idle 后重试，随后在该对话中排入一个普通 follow-up 轮次。关闭进程或让 Session 保持 cold 会停止内存 timer，但不会删除记录；重新打开同一个 Session 会恢复等待并交付逾期提醒。仅查看 cold 历史不会激活提醒，fork 也不会继承父 Session 的提醒。
|
||||
|
||||
创建和实际删除操作只有在 Session persistence 确认对应事件前缀后才会确认成功。提醒回执同样只在 dispatch 持久化后出现。Schedule 不提供浏览器、操作系统、邮件、短信或其他外部通知，best-effort 模型 follow-up 也不构成交付确认。
|
||||
创建和实际删除操作只有在 Session persistence 确认对应事件前缀后才会确认成功。Schedule 不提供浏览器、操作系统、邮件、短信或其他外部通知。持久 dispatch 会记录 follow-up 已经入队；它不确认模型成功或用户已收到提醒。
|
||||
|
||||
本层不接受绝对时间、固定间隔或 cron 规则。
|
||||
|
||||
@@ -1,10 +1,6 @@
|
||||
# Opt-in Schedule patch over the shipped Web composition. The Schedule owner
|
||||
# only observes roots published after this overlay loads, so this remains an
|
||||
# explicit capability rather than changing the default Web tree.
|
||||
# Opt-in Schedule patch over the shipped Web composition. The owner observes
|
||||
# only roots published after this overlay loads.
|
||||
|
||||
- insert:
|
||||
- id: tool-schedule
|
||||
name: '@deepseek-ai/dsh-tool-schedule'
|
||||
|
||||
- id: ui-schedule
|
||||
name: '@deepseek-ai/dsh-client-ui-schedule'
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/README.md
|
||||
README.md: eff1d9522e3ca6e8a7efaa20463d73036101f8f5
|
||||
README.zh.md: cc2d37d3999e2e59095a8000feb3f963d0b4e4a1
|
||||
README.md: 51f926f02bd4df0ada61bda88b4181fe3ebea89f
|
||||
README.zh.md: c9912481febcbc742e2853a1c8eff822c7810245
|
||||
|
||||
@@ -14,8 +14,8 @@ Groups hold `packages/<group>/<pkg>/`; names stay `@deepseek-ai/dsh-<pkg>`. **Gr
|
||||
| [`api/`](api/README.md) | Remote BFF assembly and TypeRT RPC gateway | Product — stable surface |
|
||||
| [`typert/`](typert/README.md) | Type graph generation, artifact loading, and runtime registry | Product — stable surface |
|
||||
| [`goal/`](goal/README.md) | Same-session goal persistence and lifecycle | Product — stable surface |
|
||||
| [`schedule/`](schedule/README.md) | Session-local scheduled follow-ups | Product — stable surface |
|
||||
| [`feedback/`](feedback/README.md) | Human feedback | Product — stable surface |
|
||||
| [`schedule/`](schedule/README.md) | Session-local reminders | Product — stable surface |
|
||||
| [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable surface |
|
||||
| [`e2b/`](e2b/README.md) | E2B providers | POC |
|
||||
| [`subprocess/`](subprocess/README.md) | Subprocess capability family: Service Definition + local process-tree provider | Product — stable surface |
|
||||
@@ -56,7 +56,7 @@ Groups hold `packages/<group>/<pkg>/`; names stay `@deepseek-ai/dsh-<pkg>`. **Gr
|
||||
| [`support/`](support/README.md) | Support infrastructure (testkits, invariants, replay, Loader smokes) | Support — lower compatibility expectations |
|
||||
| [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (`Branded<B>`, Harness home/path helpers, timeout, retention) | Support — small, stable, harness-dep-free |
|
||||
|
||||
New packages join existing groups; new groups update this table.
|
||||
New packages join existing groups; new groups update their README and this table.
|
||||
|
||||
## Dependencies
|
||||
|
||||
|
||||
@@ -14,8 +14,8 @@
|
||||
| [`api/`](api/README.md) | Remote BFF 装配与 TypeRT RPC Gateway | 产品：稳定接口 |
|
||||
| [`typert/`](typert/README.md) | 类型图生成、产物加载与运行时注册表 | 产品：稳定接口 |
|
||||
| [`goal/`](goal/README.md) | 同会话 goal 的持久化与生命周期 | 产品：稳定接口 |
|
||||
| [`schedule/`](schedule/README.md) | 仅限会话内的定时后续轮次 | 产品：稳定接口 |
|
||||
| [`feedback/`](feedback/README.md) | 人类反馈 | 产品：稳定接口 |
|
||||
| [`schedule/`](schedule/README.md) | 仅限 Session 内的提醒 | 产品：稳定接口 |
|
||||
| [`llm/`](llm/README.md) | LLM（大语言模型）能力系列：抽象服务 + 提供方适配器 | 产品：稳定接口 |
|
||||
| [`e2b/`](e2b/README.md) | E2B 提供方 | POC |
|
||||
| [`subprocess/`](subprocess/README.md) | 进程管理能力系列：Service Definition + 本地进程树提供方 | 产品：稳定接口 |
|
||||
@@ -56,7 +56,7 @@
|
||||
| [`support/`](support/README.md) | 支持基础设施（testkit、不变式、回放、Loader 冒烟测试） | 支持：兼容性预期较低 |
|
||||
| [`util/`](util/README.md) | 组间共享的低层零依赖工具（`Branded<B>`、Harness home／路径辅助函数、超时、保留策略） | 支持：小型、稳定、无 harness 依赖 |
|
||||
|
||||
新包加入现有组；新组更新此表。
|
||||
新包加入现有组；新组更新其 README 和此表。
|
||||
|
||||
## 依赖
|
||||
|
||||
|
||||
@@ -23,8 +23,6 @@ The browser side of the dsh web GUI: shell boot, browser-host communication, sha
|
||||
| [`ui-workspace/`](ui-workspace/README.md) | Provides workspace selection and creation surfaces. |
|
||||
| [`ui-conversation/`](ui-conversation/README.md) | Presents the active conversation and its input surface. |
|
||||
| [`ui-tool/`](ui-tool/README.md) | Composes Tool call trees and keyed per-Tool views. |
|
||||
| [`ui-deliverables/`](ui-deliverables/README.md) | Presents files produced by each completed turn. |
|
||||
| [`ui-schedule/`](ui-schedule/README.md) | Presents durable Schedule reminder receipts. |
|
||||
| [`ui-goal/`](ui-goal/README.md) | Presents and manages the current goal. |
|
||||
| [`ui-trajectory/`](ui-trajectory/README.md) | Presents alternate views of agent activity. |
|
||||
| [`ui-command/`](ui-command/README.md) | Provides session-aware command discovery and dispatch. |
|
||||
|
||||
@@ -23,8 +23,6 @@ dsh web GUI 的浏览器侧：shell 启动、浏览器与宿主通信、共享 U
|
||||
| [`ui-workspace/`](ui-workspace/README.md) | 提供 Workspace 选择与创建界面。 |
|
||||
| [`ui-conversation/`](ui-conversation/README.md) | 展示当前会话及其输入界面。 |
|
||||
| [`ui-tool/`](ui-tool/README.md) | 编排工具调用树和按工具键控的视图。 |
|
||||
| [`ui-deliverables/`](ui-deliverables/README.md) | 展示每个已完成轮次产出的文件。 |
|
||||
| [`ui-schedule/`](ui-schedule/README.md) | 展示持久 Schedule 提醒回执。 |
|
||||
| [`ui-goal/`](ui-goal/README.md) | 展示和管理当前目标。 |
|
||||
| [`ui-trajectory/`](ui-trajectory/README.md) | 提供 agent（智能体）活动的其他视图。 |
|
||||
| [`ui-command/`](ui-command/README.md) | 提供会话感知的命令发现与分发。 |
|
||||
|
||||
@@ -12,12 +12,6 @@ The node half guards every entry under `/api` before bridging or upgrading (`src
|
||||
|
||||
`/api/events.mux` and `/api/events.host` each accept a WebSocket upgrade and send only the corresponding `ServerRequest` text messages to the browser; the client sends no application data over these sockets. If either socket ends, the current connection generation fails and rebuilds both streams; readiness still requires both sockets to be open and the `host.describe` HTTP call to succeed. Host teardown terminates both sockets, aborts their sources, and waits for source cleanup before returning. Ordinary network GETs to these paths return 426 with no SSE fallback; `toFetchHandler`'s SSE codec serves only the isomorphic in-process carrier.
|
||||
|
||||
`SessionEventView` is an optional non-persistent sidecar on both `session.history` entries and live `session/event` frames. Tool views keep their closed call/result shapes; a presented durable event instead carries `{ for: 'event', view }`, leaving the JSON-compatible payload open to domain plugins while its durable event type selects the renderer. The same Session event may be delivered again with a new or changed sidecar, so consumers merge it by exact event identity and seq rather than treating the second frame as another log append.
|
||||
|
||||
## Keyless fixture
|
||||
|
||||
Any `fixture` query parameter selects the in-memory carrier. `fixture=empty` starts with no Workspace or Session; `fixturePrompt=reject` rejects prompts before acceptance; `fixtureAttach=fail` publishes a Session but rejects its Workspace attachment; `fixtureSessionCreate=drop-response` publishes and frames a Session before dropping the create response; and `fixtureFrames=workspace-first` reverses the default session-first create-frame order. Workspace creation by name/path and caller-preallocated SessionIds remain deterministic enough for assembled Web tests to reconcile list and frame arrival. Fixture content search preserves the production-facing `unicode61`-style case, diacritic, and token-phrase behavior and returns a match-centered snippet of at most 120 Unicode code points.
|
||||
|
||||
## Model Experience
|
||||
|
||||
None, as the wire consumer layer moves already-composed messages between browser and host; nothing here reaches a model request.
|
||||
@@ -29,5 +23,3 @@ None; this package neither assembles nor sends a provider request.
|
||||
## Known Limitations and Deferred Work
|
||||
|
||||
- **History resumes an unattached session** — opening history may create the host-side agent and add latency to the first open; there is no persistence-only read path.
|
||||
- **Attached history may omit commit-aware event views** — when persistence inspection is unavailable, fails, or cannot prove an identity-matching prefix, the Host still serves raw live events and withholds only those sidecars. A later durable live redelivery or history read can add them.
|
||||
- **Tool-specific view types remain transitional** — `ToolEventView`/`ToolCallView`/`ToolResultView` stay exported while the Host's tool `viewFor` presenter exists. The generic presented-event branch is independent and remains the domain-plugin extension shape.
|
||||
|
||||
@@ -12,12 +12,6 @@ node 半侧在桥接或 upgrade 前守卫 `/api` 下的每个入口（`src/api-r
|
||||
|
||||
`/api/events.mux` 与 `/api/events.host` 各接受一条 WebSocket upgrade，并只向浏览器发送对应的 `ServerRequest` text message；客户端不会在这些 socket 上发送业务数据。任一 socket 结束都会使当前 connection generation 失败并重建两条流，连接就绪仍要求两条 socket open 且 `host.describe` HTTP 调用成功。Host teardown 会终止两条 socket、中止各自的 source，并等待 source 清理完成后再返回。普通网络 GET 这些路径会返回 426，不保留 SSE 回退；`toFetchHandler` 的 SSE 编解码只服务进程内同构载体。
|
||||
|
||||
`SessionEventView` 是 `session.history` 条目与实时 `session/event` 帧上的可选、非持久 sidecar。工具 view 保持封闭的 call／result 形状；由 Host presentation 的持久事件则携带 `{ for: 'event', view }`，把兼容 JSON 的 payload 开放给领域插件，并由持久事件类型选择 renderer。同一个 Session event 可以再次投递并带有新增或变化的 sidecar，因此消费方会按完全一致的事件身份与 seq 合并，而不会把第二个帧当作另一次日志 append。
|
||||
|
||||
## 无密钥 fixture
|
||||
|
||||
任何 `fixture` 查询参数都会选择内存载体。`fixture=empty` 启动时不含 Workspace 或 Session；`fixturePrompt=reject` 在接受前拒绝提示词；`fixtureAttach=fail` 发布 Session 但拒绝将其附加到 Workspace；`fixtureSessionCreate=drop-response` 在丢弃创建响应前发布 Session 并为其发出帧；`fixtureFrames=workspace-first` 则反转默认的 Session 优先创建帧顺序。按名称／路径创建 Workspace 以及由调用方预先分配 SessionId，均具有足够的确定性，组装后的 Web 测试可以据此协调列表与帧的到达。fixture 内容搜索会保留面向生产环境的 `unicode61` 式大小写、变音符号和 token／短语行为，并返回以匹配位置为中心、最多包含 120 个 Unicode 码点的 snippet。
|
||||
|
||||
## 模型体验
|
||||
|
||||
无。协议消费层只在浏览器与主机之间搬运已经组合好的消息；这里没有任何内容进入模型请求。
|
||||
@@ -29,5 +23,3 @@ node 半侧在桥接或 upgrade 前守卫 `/api` 下的每个入口（`src/api-r
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
- **History 会恢复未附加的会话**：打开 history 可能创建宿主侧 agent，并增加首次打开的延迟；没有仅从持久化读取的路径。
|
||||
- **已附加 history 可能省略 commit-aware event view**：当 persistence inspect 不可用、失败或无法证明 identity-matching prefix 时，Host 仍会返回原始 live event，只会省略这些 sidecar。之后的持久 live 重投或 history 读取仍可补上它们。
|
||||
- **工具专属 view 类型仍是过渡表面**：只要 Host 的工具 `viewFor` presenter 仍存在，`ToolEventView`／`ToolCallView`／`ToolResultView` 就继续导出。通用 presented-event 分支与此独立，并保持为领域插件的扩展形状。
|
||||
|
||||
@@ -7,8 +7,7 @@
|
||||
|
||||
export type {
|
||||
ApiProxy, SessionsApi, SessionSearchItem, SessionSummary, HostApi, EventsApi, MuxFrame, HostFrame,
|
||||
ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, PresentedEventView,
|
||||
SessionEventView, ToolEventView,
|
||||
ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, ToolEventView,
|
||||
DirectoryEntry, DirectoryListing,
|
||||
WorkspaceApi, WorkspaceId, WorkspaceView,
|
||||
CommandsApi, CommandDescriptor, SkillsApi, SkillEntry,
|
||||
|
||||
@@ -15,8 +15,7 @@ import type { ClientConnectionRpc } from '../rpc.ts'
|
||||
// ---- Contract re-exports (browser-safe apiproxy channels + core types) ----
|
||||
export type {
|
||||
ApiProxy, SessionsApi, SessionSearchItem, SessionSummary, HostApi, EventsApi, MuxFrame, HostFrame,
|
||||
ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, PresentedEventView,
|
||||
SessionEventView, ToolEventView,
|
||||
ApprovalResponsePayload, QuestionResponsePayload, HistoryEntry, ToolEventView,
|
||||
DirectoryEntry, DirectoryListing,
|
||||
ToolCallView, ToolResultView, WorkspaceApi, WorkspaceId, WorkspaceView,
|
||||
CommandsApi, CommandDescriptor, SkillsApi, SkillEntry,
|
||||
|
||||
@@ -40,8 +40,6 @@ SlotsService gives the renderer separate bare observables for `useSessions` and
|
||||
|
||||
Because the projection is log-ordered, the node array is seq-monotonic by construction: log-only `command/run` / `command/done` nodes splice in by seq, `Session` merges interrupted frozen nodes by their fractional seqs, and a window whose checkpoint cites a shadowed range outside it renders the marker with nothing logged. The marker's summary text, replaced-item count, and estimated shadowed-token count come from the checkpoint's cited `compact/summary` event; a window cut that left that event outside makes those fields unavailable, and a later page that supplies it resolves them. `CommandNode.outcome.sourceEventSeq` preserves a successful command's explicit reference to that summary event, allowing the presentation layer to pair `/compact` with its checkpoint without parsing settlement copy or assuming the two rows are adjacent. Performance contract: one append materializes at most one node and copies the projection only when it adds that node; an event that changes no node keeps the previous array reference (a chunk storm costs nothing), and unchanged nodes keep their object identity.
|
||||
|
||||
A Host may redeliver the same Session event seq with a new or changed non-persistent view after the event reaches its presentation commit point. `Session` first requires deep event identity, then upgrades only the sidecar; a generic event view becomes one `PresentedEventNode` keyed by the durable event type. Tail loading and true gap repair continue to use the existing `liveBuffer`; repair continues while each accepted snapshot advances the tail and a buffered gap remains, while an identity-conflicting snapshot triggers a full resync. Ordinary `loadOlder` leaves live-tail appends in the current window and prepends its page after the await, while an overlapping late sidecar upgrades immediately. Reconnect advances the generation and clears page or repair ownership, so an older request's result or `finally` cannot mutate or block the rebuilt window.
|
||||
|
||||
## Request inspection
|
||||
|
||||
`SessionHistoryInspection.requests` is one chronological, purpose-discriminated provider-request stream. Assistant requests always carry their numeric `turn` and `step`; compaction requests carry `step: 0` and a `turn` owner that may be `null`. That null owner means a manual compaction ran standalone between turns, not that it belongs to either adjacent turn. A `session/end-seed` boundary closes an unmatched compaction request as an error at the boundary time with `Compaction was interrupted before completion.`; a later start projects as an independent request instead of overwriting the orphan.
|
||||
|
||||
@@ -40,8 +40,6 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
|
||||
|
||||
由于投影按日志顺序，节点数组天然按 seq 单调：仅日志的 `command/run` / `command/done` 节点按 seq 插入，`Session` 按分数 seq 归并被打断的冻结节点，而检查点所引范围落在窗口之外的窗口会渲染出标记且不打印任何日志。标记的摘要文本、被替换条目数量和估算的被遮蔽 token 数量都来自检查点引用的 `compact/summary` 事件；窗口切分把该事件留在窗口外时这些字段不可用，后续包含该事件的分页会解析出它们。`CommandNode.outcome.sourceEventSeq` 保留成功命令对该摘要事件的显式引用，使呈现层能够配对 `/compact` 与其检查点，而无须解析结算文案或假定两行相邻。性能约定：一次追加最多物化一个节点，并且仅在加入该节点时复制投影；不改变任何节点的事件保持上一次的数组引用（分片风暴零成本），未变化的节点保持其对象标识。
|
||||
|
||||
一个 Session event 到达其 presentation 提交点后，Host 可以用同一 seq 重新投递完全相同的事件，并携带新增或变化的非持久 view。`Session` 会先要求事件深度一致，再只升级 sidecar；通用 event view 会按持久事件类型形成一个 `PresentedEventNode`。`liveBuffer` 仍只用于尾部加载与真正的 gap repair；每当已接受的快照推进 tail 后仍留有已缓冲的 gap，repair 就会继续；身份冲突的快照则会触发全量重新同步。普通 `loadOlder` 会将 live-tail 追加项留在当前窗口中，并在 await 后前插所取页面；重叠的迟到 sidecar 则会立即升级。重连会推进 generation 并清除 page／repair 的所有权，因此旧请求的结果或 `finally` 既不能改写，也不能阻塞重建后的窗口。
|
||||
|
||||
## 请求检查
|
||||
|
||||
`SessionHistoryInspection.requests` 是一条按时间顺序排列、以用途为判别字段的提供方请求流。助手请求始终携带数值型 `turn` 与 `step`；压缩请求携带 `step: 0`，其 `turn` 所有者可以是 `null`。这个 null 所有者表示手动压缩独立运行在两个轮次之间，并不表示它属于任一相邻轮次。`session/end-seed` 边界会在边界时刻将未匹配的压缩请求以错误状态结束，错误固定为 `Compaction was interrupted before completion.`；后续 start 会投影为独立请求，而不会覆盖这项遗留的未匹配请求。
|
||||
|
||||
@@ -50,7 +50,7 @@ export type {
|
||||
export type {
|
||||
AssistantBlock, AssistantMessageNode, AssistantProvenanceView, AssistantRequestConfig,
|
||||
AssistantTiming, CommandNode, CompactionSummaryNode, ComposerPhase,
|
||||
ContextMessageNode, ConversationNode, ConversationSnapshot, ModelRetryNode, PresentedEventNode, QueuedMessage,
|
||||
ContextMessageNode, ConversationNode, ConversationSnapshot, ModelRetryNode, QueuedMessage,
|
||||
RunningToolCall,
|
||||
SteeringMessageNode, TodoItem, ToolCallBlock, ToolResultNode, TurnErrorNode, UnknownSurfaceNode, UserMessageNode,
|
||||
} from './sessions/conversation.ts'
|
||||
|
||||
@@ -252,23 +252,6 @@ export interface CommandNode {
|
||||
} | null
|
||||
}
|
||||
|
||||
/**
|
||||
* Host-computed presentation for one durable non-surface event. The generic
|
||||
* runtime carries the durable event type and JSON-compatible payload without
|
||||
* importing the producing domain; a client plugin owns the keyed renderer.
|
||||
*/
|
||||
export interface PresentedEventNode {
|
||||
kind: 'presented-event'
|
||||
/** Seq of the durable event whose sidecar produced this node. */
|
||||
seq: number
|
||||
/** Unix epoch ms from the source Session event. */
|
||||
time: number
|
||||
/** Durable event type selecting an optional domain renderer. */
|
||||
eventType: string
|
||||
/** Domain-owned JSON-compatible presentation payload. */
|
||||
view: unknown
|
||||
}
|
||||
|
||||
/** Finalized conversation node union (kind discriminates; seq is the React key). */
|
||||
export type ConversationNode =
|
||||
| UserMessageNode
|
||||
@@ -279,7 +262,6 @@ export type ConversationNode =
|
||||
| TurnErrorNode
|
||||
| ToolResultNode
|
||||
| CommandNode
|
||||
| PresentedEventNode
|
||||
| CompactionSummaryNode
|
||||
| UnknownSurfaceNode
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ import type { LlmRetryEventData } from '@deepseek-ai/dsh-llm-retry/types'
|
||||
import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
|
||||
import type {
|
||||
HistoryEntry, IApiClient, MessageId, MuxFrame, QueueAction, RpcError,
|
||||
RpcId, RpcResponse, RpcResult, SessionEventView, SessionId, SubagentAddress,
|
||||
RpcId, RpcResponse, RpcResult, SessionId, SubagentAddress, ToolEventView,
|
||||
} from '@deepseek-ai/dsh-client-connection/client'
|
||||
// Value import from the inline-safe wire layer (not the connection plugin):
|
||||
// plugin-to-plugin value imports are a bundle purity error.
|
||||
@@ -74,36 +74,6 @@ function queueTextOf(content: readonly ContentBlock[]): string | null {
|
||||
return content.map(block => block.text).join('')
|
||||
}
|
||||
|
||||
/** Browser-safe structural equality for JSON-compatible wire values. */
|
||||
function sameWireValue(left: unknown, right: unknown): boolean {
|
||||
if (Object.is(left, right)) return true
|
||||
if (left === null || right === null || typeof left !== 'object' || typeof right !== 'object') return false
|
||||
if (Array.isArray(left) || Array.isArray(right)) {
|
||||
if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) return false
|
||||
return left.every((value, index) => sameWireValue(value, right[index]))
|
||||
}
|
||||
const leftRecord = left as Record<string, unknown>
|
||||
const rightRecord = right as Record<string, unknown>
|
||||
const leftKeys = Object.keys(leftRecord).sort()
|
||||
const rightKeys = Object.keys(rightRecord).sort()
|
||||
return leftKeys.length === rightKeys.length
|
||||
&& leftKeys.every((key, index) =>
|
||||
key === rightKeys[index] && sameWireValue(leftRecord[key], rightRecord[key]))
|
||||
}
|
||||
|
||||
/** Same-seq deliveries may add a sidecar, but must carry the identical durable event. */
|
||||
function assertSameEvent(left: SessionEvent, right: SessionEvent): void {
|
||||
if (!sameWireValue(left, right)) {
|
||||
throw new Error(`session event identity mismatch at seq ${left.seq}`)
|
||||
}
|
||||
}
|
||||
|
||||
/** One in-flight older-page request and the late sidecars that may belong to its result. */
|
||||
interface OlderPageLoad {
|
||||
readonly beforeSeq: number
|
||||
readonly views: Map<number, { event: SessionEvent; view: SessionEventView }>
|
||||
}
|
||||
|
||||
/**
|
||||
* Owns a session's event window, derived conversation state, and observable
|
||||
* snapshot. React bindings remain outside this data layer. Features see only
|
||||
@@ -115,7 +85,7 @@ export class Session implements SessionFace {
|
||||
private events: SessionEvent[] = []
|
||||
/** Wire views aligned with `events` by index (envelope-level annotations; undefined = no view).
|
||||
* Kept parallel rather than merged so `events` stays the raw log slice (model-visible ⟺ logged). */
|
||||
private views: (SessionEventView | undefined)[] = []
|
||||
private views: (ToolEventView | undefined)[] = []
|
||||
private baseSeq = 0
|
||||
private hasMore = false
|
||||
private openState: OpenState = 'cold'
|
||||
@@ -125,7 +95,7 @@ export class Session implements SessionFace {
|
||||
* a pre-disconnect open whose history request is already doomed (audit S4). Stale doOpen
|
||||
* passes drop all writes once the generation moves on. */
|
||||
private openGeneration = 0
|
||||
private loadingOlder: OlderPageLoad | null = null
|
||||
private loadingOlder = false
|
||||
private readonly transcript = new TranscriptAdapter()
|
||||
private partial: PartialAccumulator | null = null
|
||||
private openCalls = new Map<string, RunningToolCall>()
|
||||
@@ -177,7 +147,7 @@ export class Session implements SessionFace {
|
||||
private promptError: PromptError | null = null
|
||||
private lastAgentError: string | null = null
|
||||
/** Live events buffered during open/resync and stitched by sequence once history lands. */
|
||||
private liveBuffer: { event: SessionEvent; view: SessionEventView | undefined }[] = []
|
||||
private liveBuffer: { event: SessionEvent; view: ToolEventView | undefined }[] = []
|
||||
/** Gap repair in flight; live events detour to the buffer until the tail page lands. */
|
||||
private stitching = false
|
||||
/** subscribed.lastSeq baseline (gap detection; null when no subscribed frame arrived — degrade to the liveBuffer dedup path). */
|
||||
@@ -396,16 +366,11 @@ export class Session implements SessionFace {
|
||||
|
||||
/** Page up: pull one earlier page with the window's first seq as beforeSeq and prepend (§D.2). */
|
||||
async loadOlder(): Promise<void> {
|
||||
if (this.openState !== 'open' || !this.hasMore || this.loadingOlder !== null) return
|
||||
const loading: OlderPageLoad = { beforeSeq: this.baseSeq, views: new Map() }
|
||||
this.loadingOlder = loading
|
||||
if (this.openState !== 'open' || !this.hasMore || this.loadingOlder) return
|
||||
this.loadingOlder = true
|
||||
this.notifier.markDirty()
|
||||
try {
|
||||
const { result } = await this.history({ beforeSeq: loading.beforeSeq, maxMessages: PAGE_MESSAGES })
|
||||
if (this.loadingOlder !== loading) return
|
||||
// A concurrent gap repair may replace the window with a newer tail page.
|
||||
// The captured older page no longer adjoins that window and must be dropped.
|
||||
if (this.baseSeq !== loading.beforeSeq) return
|
||||
const { result } = await this.history({ beforeSeq: this.baseSeq, maxMessages: PAGE_MESSAGES })
|
||||
if (!result.ok) return // keep the window as-is; do not overwrite openError (open already succeeded)
|
||||
const older = result.value.events
|
||||
if (older.length === 0) {
|
||||
@@ -413,42 +378,24 @@ export class Session implements SessionFace {
|
||||
return
|
||||
}
|
||||
const tail = older[older.length - 1]
|
||||
if (tail === undefined || tail.event.seq + 1 !== loading.beforeSeq) {
|
||||
if (tail === undefined || tail.event.seq + 1 !== this.baseSeq) {
|
||||
// §D.2 continuity assertion: on violation drop the page fail-soft rather than render an out-of-order stream.
|
||||
console.error(`[web-runtime] history page discontinuous: tail seq ${tail?.event.seq} vs baseSeq ${loading.beforeSeq}`)
|
||||
console.error(`[web-runtime] history page discontinuous: tail seq ${tail?.event.seq} vs baseSeq ${this.baseSeq}`)
|
||||
this.hasMore = false
|
||||
return
|
||||
}
|
||||
let settled: HistoryEntry[]
|
||||
try {
|
||||
settled = older.map((entry): HistoryEntry => {
|
||||
const late = loading.views.get(entry.event.seq)
|
||||
if (late === undefined) return entry
|
||||
assertSameEvent(entry.event, late.event)
|
||||
return { ...entry, view: late.view }
|
||||
})
|
||||
} catch (error) {
|
||||
console.error('[web-runtime] older-page session event failed identity validation:', error)
|
||||
void this.resync()
|
||||
return
|
||||
}
|
||||
this.events = [...settled.map(entry => entry.event), ...this.events]
|
||||
this.views = [...settled.map(entry => entry.view), ...this.views]
|
||||
/* v8 ignore next -- the empty-page branch returned above. */
|
||||
this.events = [...older.map(e => e.event), ...this.events]
|
||||
this.views = [...older.map(e => e.view), ...this.views]
|
||||
/* v8 ignore next -- the ?? arm needs older[0] undefined, but the empty-page branch above already returned. */
|
||||
this.baseSeq = older[0]?.event.seq ?? this.baseSeq
|
||||
this.hasMore = result.value.hasMore
|
||||
this.transcript.reset(this.events, this.views)
|
||||
this.transcript.reset(this.events, this.views) // prepend forces a rebuild (the window grew at the head)
|
||||
this.rebuildDerivedFromWindow()
|
||||
} catch (error) {
|
||||
if (this.loadingOlder === loading) {
|
||||
console.error('[web-runtime] loadOlder failed:', error)
|
||||
}
|
||||
console.error('[web-runtime] loadOlder failed:', error)
|
||||
} finally {
|
||||
if (this.loadingOlder === loading) {
|
||||
this.loadingOlder = null
|
||||
if (this.liveBuffer.length > 0) void this.repairGap()
|
||||
this.notifier.markDirty()
|
||||
}
|
||||
this.loadingOlder = false
|
||||
this.notifier.markDirty()
|
||||
}
|
||||
}
|
||||
|
||||
@@ -476,8 +423,6 @@ export class Session implements SessionFace {
|
||||
this.pendingRev++
|
||||
this.subscribedLastSeq = null
|
||||
this.liveBuffer = []
|
||||
this.loadingOlder = null
|
||||
this.stitching = false
|
||||
this.notifier.markDirty()
|
||||
await this.open()
|
||||
}
|
||||
@@ -682,9 +627,7 @@ export class Session implements SessionFace {
|
||||
if (generation !== this.openGeneration) return
|
||||
if (result.ok) this.installWindow(result.value.events, result.value.hasMore, result.value.projections)
|
||||
}
|
||||
const { hasGap } = this.mergeWindow()
|
||||
this.openState = 'open'
|
||||
if (hasGap) void this.repairGap()
|
||||
} catch (error) {
|
||||
if (generation !== this.openGeneration) return
|
||||
this.openState = 'error'
|
||||
@@ -696,137 +639,29 @@ export class Session implements SessionFace {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Install one history window and settle every buffered overlap or safe
|
||||
* contiguous suffix through {@link mergeWindow}. A carried projections
|
||||
* block seeds the value store (higher seq wins, so a stale baseline cannot
|
||||
* overwrite a newer push frame); the window events themselves are never
|
||||
* folded — the host is the only computation site.
|
||||
*/
|
||||
private installWindow(
|
||||
entries: HistoryEntry[],
|
||||
hasMore: boolean,
|
||||
projections?: ProjectionsBaseline,
|
||||
): { changed: boolean; hasGap: boolean } {
|
||||
const merged = this.mergeWindow(entries)
|
||||
/** Install the history window + stitch the liveBuffer (seq is the sole dedup key).
|
||||
* Stitching MUST NOT route through acceptLiveEvent: openState is still 'loading' here
|
||||
* (doOpen flips it after install), so recursing would push every buffered event straight
|
||||
* back into liveBuffer where nothing ever drains it — a silent drop loop (audit S1).
|
||||
* A carried projections block seeds the value store (higher seq wins, so a stale
|
||||
* baseline cannot overwrite a newer push frame); the window events themselves are
|
||||
* never folded — the host is the only computation site. */
|
||||
private installWindow(entries: HistoryEntry[], hasMore: boolean, projections?: ProjectionsBaseline): void {
|
||||
this.events = entries.map(e => e.event)
|
||||
this.views = entries.map(e => e.view)
|
||||
this.baseSeq = this.events[0]?.seq ?? 0
|
||||
this.hasMore = hasMore
|
||||
this.transcript.reset(this.events, this.views)
|
||||
this.rebuildDerivedFromWindow()
|
||||
if (projections !== undefined) this.projections.seed(projections)
|
||||
const buffered = this.liveBuffer
|
||||
this.liveBuffer = []
|
||||
for (const item of buffered) this.appendLive(item.event, item.view)
|
||||
this.notifier.markDirty()
|
||||
return merged
|
||||
}
|
||||
|
||||
/**
|
||||
* Reconcile a history snapshot (when supplied), the current window, and
|
||||
* buffered live deliveries by seq. Same-seq events must be identical;
|
||||
* defined late sidecars upgrade but an absent sidecar never erases an
|
||||
* existing one. Only the contiguous suffix joins the window, leaving a real
|
||||
* gap buffered for the existing repair path.
|
||||
* @param entries - replacement/prepended history window, or undefined to
|
||||
* settle the current window after an RPC failure or empty page.
|
||||
* @returns whether the visible window changed and whether a true gap remains.
|
||||
*/
|
||||
private mergeWindow(entries?: readonly HistoryEntry[]): { changed: boolean; hasGap: boolean } {
|
||||
const current = new Map<number, { event: SessionEvent; view: SessionEventView | undefined }>()
|
||||
for (let index = 0; index < this.events.length; index++) {
|
||||
const event = this.events[index]
|
||||
/* v8 ignore next -- dense-array guard: index stays within events.length. */
|
||||
if (event !== undefined) current.set(event.seq, { event, view: this.views[index] })
|
||||
}
|
||||
|
||||
const events: SessionEvent[] = []
|
||||
const views: (SessionEventView | undefined)[] = []
|
||||
if (entries === undefined) {
|
||||
events.push(...this.events)
|
||||
views.push(...this.views)
|
||||
} else {
|
||||
let previousSeq: number | undefined
|
||||
for (const entry of entries) {
|
||||
if (previousSeq !== undefined && entry.event.seq !== previousSeq + 1) {
|
||||
throw new Error(`history window is not contiguous at seq ${entry.event.seq}`)
|
||||
}
|
||||
previousSeq = entry.event.seq
|
||||
const retained = current.get(entry.event.seq)
|
||||
if (retained !== undefined) assertSameEvent(retained.event, entry.event)
|
||||
events.push(entry.event)
|
||||
views.push(entry.view ?? retained?.view)
|
||||
}
|
||||
}
|
||||
|
||||
const buffered = new Map<number, { event: SessionEvent; view: SessionEventView | undefined }>()
|
||||
for (const item of this.liveBuffer) {
|
||||
const retained = buffered.get(item.event.seq)
|
||||
if (retained !== undefined) {
|
||||
assertSameEvent(retained.event, item.event)
|
||||
if (item.view !== undefined) retained.view = item.view
|
||||
} else {
|
||||
buffered.set(item.event.seq, { ...item })
|
||||
}
|
||||
}
|
||||
|
||||
const bySeq = new Map<number, number>()
|
||||
for (let index = 0; index < events.length; index++) {
|
||||
const event = events[index]
|
||||
/* v8 ignore next -- dense-array guard: index stays within events.length. */
|
||||
if (event !== undefined) bySeq.set(event.seq, index)
|
||||
}
|
||||
const consumed = new Set<number>()
|
||||
let viewChanged = false
|
||||
const baseSeq = events[0]?.seq
|
||||
const tailSeq = events.at(-1)?.seq
|
||||
for (const [seq, item] of buffered) {
|
||||
const index = bySeq.get(seq)
|
||||
if (index !== undefined) {
|
||||
const event = events[index]
|
||||
/* v8 ignore next -- bySeq indexes the dense events array. */
|
||||
if (event === undefined) continue
|
||||
assertSameEvent(event, item.event)
|
||||
if (item.view !== undefined && !sameWireValue(views[index], item.view)) {
|
||||
views[index] = item.view
|
||||
viewChanged = true
|
||||
}
|
||||
consumed.add(seq)
|
||||
continue
|
||||
}
|
||||
// A replay older than the retained tail window is irrelevant to this
|
||||
// page and cannot become a future suffix.
|
||||
if (baseSeq !== undefined && seq < baseSeq) {
|
||||
consumed.add(seq)
|
||||
continue
|
||||
}
|
||||
if (tailSeq !== undefined && seq <= tailSeq) {
|
||||
throw new Error(`history window is missing buffered seq ${seq}`)
|
||||
}
|
||||
}
|
||||
|
||||
const appended: SessionEvent[] = []
|
||||
let expectedSeq = tailSeq === undefined ? 0 : tailSeq + 1
|
||||
for (let item = buffered.get(expectedSeq); item !== undefined; item = buffered.get(++expectedSeq)) {
|
||||
events.push(item.event)
|
||||
views.push(item.view)
|
||||
appended.push(item.event)
|
||||
consumed.add(expectedSeq)
|
||||
}
|
||||
|
||||
const remaining = [...buffered.entries()]
|
||||
.filter(([seq]) => !consumed.has(seq))
|
||||
.sort(([left], [right]) => left - right)
|
||||
.map(([, item]) => item)
|
||||
this.liveBuffer = remaining
|
||||
|
||||
const changed = entries !== undefined || viewChanged || appended.length > 0
|
||||
if (changed) {
|
||||
this.events = events
|
||||
this.views = views
|
||||
this.baseSeq = events[0]?.seq ?? 0
|
||||
this.transcript.reset(events, views)
|
||||
this.rebuildDerivedFromWindow()
|
||||
for (const event of appended) this.handoffPendingSteering(event)
|
||||
}
|
||||
return { changed, hasGap: remaining.length > 0 }
|
||||
}
|
||||
|
||||
/** Seq-guarded append shared by stitching and the open-state live path. */
|
||||
private appendLive(event: SessionEvent, view?: SessionEventView): void {
|
||||
private appendLive(event: SessionEvent, view?: ToolEventView): void {
|
||||
const tailSeq = this.windowTailSeq()
|
||||
if (tailSeq !== null && event.seq <= tailSeq) return // replay overlap, drop
|
||||
this.events.push(event)
|
||||
@@ -836,21 +671,6 @@ export class Session implements SessionFace {
|
||||
this.applyEventSideEffects(event, view)
|
||||
}
|
||||
|
||||
/** Verify one retained event and apply a defined late sidecar immediately. */
|
||||
private upgradeLiveView(event: SessionEvent, view?: SessionEventView): boolean {
|
||||
const index = this.events.findIndex(candidate => candidate.seq === event.seq)
|
||||
if (index === -1) return false
|
||||
const retained = this.events[index]
|
||||
/* v8 ignore next -- findIndex returned a dense-array position. */
|
||||
if (retained === undefined) return false
|
||||
assertSameEvent(retained, event)
|
||||
if (view === undefined || sameWireValue(this.views[index], view)) return false
|
||||
this.views[index] = view
|
||||
this.transcript.reset(this.events, this.views)
|
||||
this.rebuildDerivedFromWindow()
|
||||
return true
|
||||
}
|
||||
|
||||
/** Retire the first matching live steering occurrence when its durable message takes over. */
|
||||
private handoffPendingSteering(event: SessionEvent): void {
|
||||
if (event.type !== 'user/message') return
|
||||
@@ -862,52 +682,21 @@ export class Session implements SessionFace {
|
||||
this.queueRev++
|
||||
}
|
||||
|
||||
/** Land a live session/event (open/repair in flight -> buffer; retained overlap -> validate
|
||||
* and upgrade; an overlap below the window waits only for its in-flight older page). A seq gap
|
||||
* buffers and repulls the tail instead of appending a hole (audit S3: a gap is an expected
|
||||
* reconnect-window artifact, repaired by refetch). The window stays one contiguous raw range,
|
||||
* which lets the transcript render every event between its ends and a compaction checkpoint
|
||||
* find its cited summary event. */
|
||||
private acceptLiveEvent(event: SessionEvent, view?: SessionEventView): void {
|
||||
const loading = this.loadingOlder
|
||||
if (loading !== null && view !== undefined && event.seq < loading.beforeSeq) {
|
||||
try {
|
||||
const retained = loading.views.get(event.seq)
|
||||
if (retained !== undefined) assertSameEvent(retained.event, event)
|
||||
loading.views.set(event.seq, { event, view })
|
||||
} catch (error) {
|
||||
console.error('[web-runtime] older-page late session event failed identity validation:', error)
|
||||
void this.resync()
|
||||
}
|
||||
return
|
||||
}
|
||||
/** Land a live session/event (open/repair in flight -> buffer; overlapping seq -> drop;
|
||||
* a seq gap -> buffer + tail-page repull instead of appending a hole (audit S3: a gap is an
|
||||
* expected reconnect-window artifact, repaired by refetch). The window stays one contiguous
|
||||
* raw range, which is what lets the transcript render every event between its ends and lets a
|
||||
* compaction checkpoint find its cited summary event. */
|
||||
private acceptLiveEvent(event: SessionEvent, view?: ToolEventView): void {
|
||||
if (this.openState === 'loading' || this.stitching) {
|
||||
this.liveBuffer.push({ event, view })
|
||||
return
|
||||
}
|
||||
if (this.openState !== 'open') return // cold/error: no window upkeep (history fully backfills on open)
|
||||
const tailSeq = this.windowTailSeq()
|
||||
if (tailSeq !== null && event.seq <= tailSeq) {
|
||||
try {
|
||||
if (event.seq < this.baseSeq) {
|
||||
return
|
||||
}
|
||||
const changed = this.upgradeLiveView(event, view)
|
||||
if (changed) this.notifier.markDirty()
|
||||
} catch (error) {
|
||||
console.error('[web-runtime] duplicate session event failed identity validation:', error)
|
||||
void this.resync()
|
||||
}
|
||||
return
|
||||
}
|
||||
if (tailSeq !== null && event.seq > tailSeq + 1) {
|
||||
this.liveBuffer.push({ event, view })
|
||||
if (this.loadingOlder === null) void this.repairGap()
|
||||
return
|
||||
}
|
||||
if (tailSeq === null && event.seq !== 0) {
|
||||
this.liveBuffer.push({ event, view })
|
||||
if (this.loadingOlder === null) void this.repairGap()
|
||||
void this.repairGap()
|
||||
return
|
||||
}
|
||||
this.appendLive(event, view)
|
||||
@@ -926,54 +715,22 @@ export class Session implements SessionFace {
|
||||
if (this.stitching) return
|
||||
this.stitching = true
|
||||
const generation = this.openGeneration
|
||||
let retryGap = false
|
||||
let acceptedHistory = false
|
||||
try {
|
||||
const { result } = await this.history({ maxMessages: PAGE_MESSAGES })
|
||||
if (generation !== this.openGeneration || this.openState !== 'open') return
|
||||
if (result.ok) {
|
||||
acceptedHistory = true
|
||||
const previousTail = this.windowTailSeq()
|
||||
const { hasGap } = this.installWindow(
|
||||
result.value.events,
|
||||
result.value.hasMore,
|
||||
result.value.projections,
|
||||
)
|
||||
const repairedTail = this.windowTailSeq()
|
||||
retryGap = hasGap && repairedTail !== null
|
||||
&& (previousTail === null || repairedTail > previousTail)
|
||||
} else {
|
||||
// Keep buffered events for the next live frame or reconnect; retrying
|
||||
// immediately would spin against the same unavailable history endpoint.
|
||||
this.mergeWindow()
|
||||
// Failure or superseded by a full resync: drop — the resync path rebuilds and clears the buffer itself.
|
||||
if (result.ok && generation === this.openGeneration && this.openState === 'open') {
|
||||
this.installWindow(result.value.events, result.value.hasMore, result.value.projections)
|
||||
}
|
||||
} catch (error) {
|
||||
if (generation === this.openGeneration) {
|
||||
if (acceptedHistory) {
|
||||
console.error('[web-runtime] gap repair snapshot failed validation:', error)
|
||||
void this.resync()
|
||||
return
|
||||
}
|
||||
console.error('[web-runtime] gap repair failed:', error)
|
||||
try {
|
||||
this.mergeWindow()
|
||||
} catch (mergeError) {
|
||||
console.error('[web-runtime] gap repair buffer merge failed:', mergeError)
|
||||
void this.resync()
|
||||
}
|
||||
}
|
||||
console.error('[web-runtime] gap repair failed:', error)
|
||||
} finally {
|
||||
if (generation === this.openGeneration) {
|
||||
this.stitching = false
|
||||
this.notifier.markDirty()
|
||||
if (retryGap) void this.repairGap()
|
||||
}
|
||||
this.stitching = false
|
||||
}
|
||||
}
|
||||
|
||||
/** Per-event side effects (right column of the §A.9 dispatch table):
|
||||
* chunk/retry projection and openCalls add-remove. */
|
||||
private applyEventSideEffects(event: SessionEvent, view?: SessionEventView): void {
|
||||
private applyEventSideEffects(event: SessionEvent, view?: ToolEventView): void {
|
||||
const eventType = event.type as string
|
||||
if (eventType === 'llm/retry') {
|
||||
const data = parseRetryEventData(event.data)
|
||||
@@ -1209,7 +966,7 @@ export class Session implements SessionFace {
|
||||
openState: this.openState,
|
||||
openError: this.openError,
|
||||
hasMore: this.hasMore,
|
||||
loadingOlder: this.loadingOlder !== null,
|
||||
loadingOlder: this.loadingOlder,
|
||||
promptError: this.promptError,
|
||||
blank: this.blankBit,
|
||||
lastAgentError: this.lastAgentError,
|
||||
|
||||
@@ -19,9 +19,7 @@ import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
|
||||
// `sessions: ISessions` (TS2717, the one-program-per-side rule in
|
||||
// docs/development.md).
|
||||
import type { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact/checkpoint'
|
||||
import type {
|
||||
PresentedEventView, SessionEventView, ToolCallView, ToolResultView,
|
||||
} from '@deepseek-ai/dsh-client-connection/client'
|
||||
import type { ToolCallView, ToolEventView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
|
||||
import type { CommandNode, CompactionSummaryNode, ConversationNode } from './conversation.ts'
|
||||
import { toAssistantBlocks } from './conversation.ts'
|
||||
import { contextForm, contextProvenance } from './context-provenance.ts'
|
||||
@@ -50,7 +48,7 @@ interface CallIndexEntry {
|
||||
callView: ToolCallView | null
|
||||
}
|
||||
|
||||
/** One ordinary surface event -> UI node. */
|
||||
/** One event -> UI node (pure function; the ten-variant ConversationNode union). */
|
||||
function materializeNode(
|
||||
event: SessionEvent,
|
||||
callIndex: ReadonlyMap<string, CallIndexEntry>,
|
||||
@@ -119,17 +117,6 @@ function materializeNode(
|
||||
}
|
||||
}
|
||||
|
||||
/** One host-presented non-surface event -> generic keyed conversation node. */
|
||||
function materializePresented(event: SessionEvent, sidecar: PresentedEventView): ConversationNode {
|
||||
return {
|
||||
kind: 'presented-event',
|
||||
seq: event.seq,
|
||||
time: event.time,
|
||||
eventType: event.type,
|
||||
view: sidecar.view,
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether an event is a landed compaction checkpoint — all three conditions,
|
||||
* matching the terminal's `isCompactCheckpoint`: a `user/message`, carrying the
|
||||
@@ -268,7 +255,7 @@ export class TranscriptAdapter {
|
||||
* @param events - the new window contents (seq-ascending).
|
||||
* @param views - per-event wire views aligned with `events` by index (undefined slots for view-less events).
|
||||
*/
|
||||
reset(events: readonly SessionEvent[], views?: readonly (SessionEventView | undefined)[]): void {
|
||||
reset(events: readonly SessionEvent[], views?: readonly (ToolEventView | undefined)[]): void {
|
||||
this.rev++
|
||||
this.eventIndex = new Map()
|
||||
this.callIdx = new Map()
|
||||
@@ -290,13 +277,8 @@ export class TranscriptAdapter {
|
||||
// Indexes first, then project: a tool/result materializes against the
|
||||
// complete call index, and a checkpoint against the complete event index.
|
||||
const projected: ConversationNode[] = []
|
||||
for (let index = 0; index < events.length; index++) {
|
||||
const event = events[index]
|
||||
/* v8 ignore next -- dense-array guard: index stays within events.length. */
|
||||
if (event === undefined) continue
|
||||
const view = views?.[index]
|
||||
if (view?.for === 'event') projected.push(materializePresented(event, view))
|
||||
else if (isTranscriptEvent(event)) projected.push(this.materialize(event, steeringSeqs.has(event.seq)))
|
||||
for (const event of events) {
|
||||
if (isTranscriptEvent(event)) projected.push(this.materialize(event, steeringSeqs.has(event.seq)))
|
||||
}
|
||||
this.projected = projected
|
||||
}
|
||||
@@ -310,17 +292,12 @@ export class TranscriptAdapter {
|
||||
* @param event - the live event (seq = window tail + 1).
|
||||
* @param view - host-computed tool view paired with the event when it is a tool call/result; indexed for card rendering.
|
||||
*/
|
||||
append(event: SessionEvent, view?: SessionEventView): void {
|
||||
append(event: SessionEvent, view?: ToolEventView): void {
|
||||
this.eventIndex.set(event.seq, event)
|
||||
this.indexCall(event, view)
|
||||
const steering = this.steeringHistory.apply(event)
|
||||
indexAssistantStepTiming(this.stepTimings, event)
|
||||
if (this.indexCommand(event)) this.rev++
|
||||
if (view?.for === 'event') {
|
||||
this.projected = [...this.projected, materializePresented(event, view)]
|
||||
this.rev++
|
||||
return
|
||||
}
|
||||
if (!isTranscriptEvent(event)) return
|
||||
this.projected = [...this.projected, this.materialize(event, steering)]
|
||||
this.rev++
|
||||
@@ -415,7 +392,7 @@ export class TranscriptAdapter {
|
||||
return true
|
||||
}
|
||||
|
||||
private indexCall(event: SessionEvent, view?: SessionEventView): void {
|
||||
private indexCall(event: SessionEvent, view?: ToolEventView): void {
|
||||
if (event.type === 'tool/result') {
|
||||
if (view?.for === 'result') this.resultViews.set(event.seq, view.view)
|
||||
return
|
||||
|
||||
@@ -33,22 +33,6 @@ function histResponse(events: SessionEvent[], hasMore = false) {
|
||||
return Promise.resolve(ok({ events: entries(events) as never[], hasMore }))
|
||||
}
|
||||
|
||||
function logRange(start: number, end: number, label = 'fixture/log'): SessionEvent[] {
|
||||
return Array.from({ length: end - start }, (_value, offset) =>
|
||||
at(start + offset, { type: label, data: { index: start + offset } }))
|
||||
}
|
||||
|
||||
function reminderEvent(seq: number, id: string): SessionEvent {
|
||||
return at(seq, { type: 'schedule/change', data: { version: 1, operation: 'dispatch', id } })
|
||||
}
|
||||
|
||||
function reminderView(id: string, prompt = '检查日志') {
|
||||
return {
|
||||
for: 'event' as const,
|
||||
view: { id, prompt },
|
||||
}
|
||||
}
|
||||
|
||||
describe('open', () => {
|
||||
it('installs the tail page: cold → loading → open with window and nodes in place', async () => {
|
||||
const { api, session } = makeSession()
|
||||
@@ -98,9 +82,9 @@ describe('open', () => {
|
||||
const gate = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
api.onHistory = () => gate.promise
|
||||
const opening = session.open()
|
||||
const page = plainTurn(10, 0, '早', '安')
|
||||
// Three live frames land mid-open; seq 15 overlaps the page tail (page covers 10..15).
|
||||
session.handleMuxEnvelope('r1' as never, { type: 'session/event', sessionId: SID, event: page[5]! })
|
||||
const page = plainTurn(10, 0, '早', '安')
|
||||
session.handleMuxEnvelope('r1' as never, { type: 'session/event', sessionId: SID, event: ev.turnStart(15, 1) })
|
||||
session.handleMuxEnvelope('r2' as never, { type: 'session/event', sessionId: SID, event: ev.user(16, '插进来的') })
|
||||
gate.resolve(ok({
|
||||
events: entries(page) as never[],
|
||||
@@ -114,284 +98,6 @@ describe('open', () => {
|
||||
})
|
||||
})
|
||||
|
||||
describe('late event views', () => {
|
||||
it('upgrades an already-open raw event without duplicating it or letting an absent sidecar erase it', async () => {
|
||||
const { api, session } = makeSession()
|
||||
const event = reminderEvent(0, 'schedule-1')
|
||||
api.onHistory = () => histResponse([event])
|
||||
await session.open()
|
||||
expect(session.getSnapshot().nodes).toEqual([])
|
||||
|
||||
session.handleMuxEnvelope('rv1' as never, {
|
||||
type: 'session/event', sessionId: SID, event, view: reminderView('schedule-1'),
|
||||
})
|
||||
expect(session.getSnapshot().nodes).toMatchObject([{
|
||||
kind: 'presented-event', seq: 0, eventType: 'schedule/change',
|
||||
view: { id: 'schedule-1', prompt: '检查日志' },
|
||||
}])
|
||||
|
||||
session.handleMuxEnvelope('rv2' as never, {
|
||||
type: 'session/event', sessionId: SID, event,
|
||||
})
|
||||
expect(session.getSnapshot().nodes).toMatchObject([{
|
||||
kind: 'presented-event', view: { prompt: '检查日志' },
|
||||
}])
|
||||
|
||||
session.handleMuxEnvelope('rv3' as never, {
|
||||
type: 'session/event', sessionId: SID, event, view: reminderView('schedule-1', '检查发布'),
|
||||
})
|
||||
expect(session.getSnapshot().nodes).toMatchObject([{
|
||||
kind: 'presented-event', view: { prompt: '检查发布' },
|
||||
}])
|
||||
})
|
||||
|
||||
it('merges a view delivered while the tail history is loading', async () => {
|
||||
const { api, session } = makeSession()
|
||||
const event = reminderEvent(0, 'schedule-loading')
|
||||
const gate = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
api.onHistory = () => gate.promise
|
||||
const opening = session.open()
|
||||
session.handleMuxEnvelope('rv' as never, {
|
||||
type: 'session/event', sessionId: SID, event, view: reminderView('schedule-loading'),
|
||||
})
|
||||
gate.resolve(ok({ events: [{ event }] as never[], hasMore: false }))
|
||||
await opening
|
||||
expect(session.getSnapshot().nodes).toMatchObject([{
|
||||
kind: 'presented-event', seq: 0, view: { id: 'schedule-loading' },
|
||||
}])
|
||||
})
|
||||
|
||||
it('merges a late view buffered behind a gap repair snapshot', async () => {
|
||||
const { api, session } = makeSession()
|
||||
const first = logRange(0, 6)
|
||||
api.onHistory = () => histResponse(first)
|
||||
await session.open()
|
||||
|
||||
const due = reminderEvent(9, 'schedule-gap')
|
||||
const full = [...first, ...logRange(6, 9), due]
|
||||
const gate = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
api.onHistory = () => gate.promise
|
||||
session.handleMuxEnvelope('raw' as never, {
|
||||
type: 'session/event', sessionId: SID, event: due,
|
||||
})
|
||||
session.handleMuxEnvelope('late' as never, {
|
||||
type: 'session/event', sessionId: SID, event: due, view: reminderView('schedule-gap'),
|
||||
})
|
||||
gate.resolve(ok({ events: entries(full) as never[], hasMore: false }))
|
||||
|
||||
await vi.waitFor(() => {
|
||||
expect(session.getSnapshot().nodes).toMatchObject([{
|
||||
kind: 'presented-event', seq: 9, view: { id: 'schedule-gap' },
|
||||
}])
|
||||
})
|
||||
})
|
||||
|
||||
it('upgrades a retained view during loadOlder and preserves it across prepend', async () => {
|
||||
const { api, session } = makeSession()
|
||||
const target = reminderEvent(9, 'schedule-loading-older')
|
||||
const newer = [...logRange(6, 9), target, ...logRange(10, 12)]
|
||||
api.onHistory = () => histResponse(newer, true)
|
||||
await session.open()
|
||||
|
||||
const gate = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
api.onHistory = () => gate.promise
|
||||
const loading = session.loadOlder()
|
||||
session.handleMuxEnvelope('late' as never, {
|
||||
type: 'session/event', sessionId: SID, event: target,
|
||||
view: reminderView('schedule-loading-older'),
|
||||
})
|
||||
expect(session.getSnapshot().nodes).toMatchObject([{
|
||||
kind: 'presented-event', seq: target.seq,
|
||||
view: { id: 'schedule-loading-older' },
|
||||
}])
|
||||
|
||||
gate.resolve(ok({ events: entries(logRange(0, 6)) as never[], hasMore: false }))
|
||||
await loading
|
||||
expect(session.getSnapshot().nodes).toMatchObject([{
|
||||
kind: 'presented-event', seq: target.seq,
|
||||
view: { id: 'schedule-loading-older' },
|
||||
}])
|
||||
})
|
||||
|
||||
it('keeps a late view for the raw event returned by an in-flight older page', async () => {
|
||||
const { api, session } = makeSession()
|
||||
const target = reminderEvent(3, 'schedule-older-page')
|
||||
const older = [...logRange(0, 3), target, ...logRange(4, 6)]
|
||||
api.onHistory = () => histResponse(logRange(6, 12), true)
|
||||
await session.open()
|
||||
|
||||
const gate = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
api.onHistory = () => gate.promise
|
||||
const loading = session.loadOlder()
|
||||
session.handleMuxEnvelope('late' as never, {
|
||||
type: 'session/event', sessionId: SID, event: target,
|
||||
view: reminderView('schedule-older-page'),
|
||||
})
|
||||
session.handleMuxEnvelope('later' as never, {
|
||||
type: 'session/event', sessionId: SID, event: target,
|
||||
view: reminderView('schedule-older-page', '检查更新'),
|
||||
})
|
||||
expect(session.getSnapshot().nodes).toEqual([])
|
||||
|
||||
gate.resolve(ok({ events: entries(older) as never[], hasMore: false }))
|
||||
await loading
|
||||
expect(session.getSnapshot().nodes).toMatchObject([{
|
||||
kind: 'presented-event', seq: target.seq,
|
||||
view: { id: 'schedule-older-page', prompt: '检查更新' },
|
||||
}])
|
||||
})
|
||||
|
||||
it('keeps an older-page late view while a gap repair is also in flight', async () => {
|
||||
const { api, session } = makeSession()
|
||||
api.onHistory = () => histResponse(logRange(6, 12), true)
|
||||
await session.open()
|
||||
|
||||
const repair = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
const page = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
api.onHistory = payload => payload.beforeSeq === undefined ? repair.promise : page.promise
|
||||
const gapTail = ev.user(15, '修复后的尾部')
|
||||
session.handleMuxEnvelope('gap' as never, {
|
||||
type: 'session/event', sessionId: SID, event: gapTail,
|
||||
})
|
||||
await vi.waitFor(() => {
|
||||
expect(api.callsOf('session.history')).toHaveLength(2)
|
||||
})
|
||||
|
||||
const loading = session.loadOlder()
|
||||
const target = reminderEvent(3, 'schedule-overlapping-repairs')
|
||||
session.handleMuxEnvelope('late' as never, {
|
||||
type: 'session/event', sessionId: SID, event: target,
|
||||
view: reminderView('schedule-overlapping-repairs'),
|
||||
})
|
||||
|
||||
repair.resolve(ok({
|
||||
events: entries([...logRange(6, 15), gapTail]) as never[],
|
||||
hasMore: true,
|
||||
}))
|
||||
await vi.waitFor(() => {
|
||||
expect(session.getSnapshot().nodes).toMatchObject([{ kind: 'user', seq: 15 }])
|
||||
})
|
||||
page.resolve(ok({
|
||||
events: entries([...logRange(0, 3), target, ...logRange(4, 6)]) as never[],
|
||||
hasMore: false,
|
||||
}))
|
||||
await loading
|
||||
|
||||
expect(session.getSnapshot().nodes).toMatchObject([
|
||||
{
|
||||
kind: 'presented-event', seq: target.seq,
|
||||
view: { id: 'schedule-overlapping-repairs' },
|
||||
},
|
||||
{ kind: 'user', seq: 15 },
|
||||
])
|
||||
})
|
||||
|
||||
it('drops an older page after a concurrent gap repair advances the window base', async () => {
|
||||
const { api, session } = makeSession()
|
||||
api.onHistory = () => histResponse(logRange(50, 100), true)
|
||||
await session.open()
|
||||
|
||||
const repair = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
const page = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
api.onHistory = payload => payload.beforeSeq === undefined ? repair.promise : page.promise
|
||||
const gapTail = ev.user(200, '修复后的新窗口')
|
||||
session.handleMuxEnvelope('gap' as never, {
|
||||
type: 'session/event', sessionId: SID, event: gapTail,
|
||||
})
|
||||
await vi.waitFor(() => {
|
||||
expect(api.callsOf('session.history')).toHaveLength(2)
|
||||
})
|
||||
|
||||
const loading = session.loadOlder()
|
||||
repair.resolve(ok({
|
||||
events: entries([...logRange(150, 200), gapTail]) as never[],
|
||||
hasMore: true,
|
||||
}))
|
||||
await vi.waitFor(() => {
|
||||
expect(session.getSnapshot().nodes.map(node => node.seq)).toEqual([200])
|
||||
})
|
||||
|
||||
page.resolve(ok({
|
||||
events: entries([...logRange(0, 44), ...plainTurn(44, 0, '陈旧问题', '陈旧回答')]) as never[],
|
||||
hasMore: false,
|
||||
}))
|
||||
await loading
|
||||
expect(session.getSnapshot()).toMatchObject({ hasMore: true })
|
||||
expect(session.getSnapshot().nodes.map(node => node.seq)).toEqual([200])
|
||||
})
|
||||
|
||||
it('resyncs when repeated older-page late views disagree on event identity', async () => {
|
||||
const { api, session } = makeSession()
|
||||
const newer = logRange(6, 12)
|
||||
api.onHistory = () => histResponse(newer, true)
|
||||
await session.open()
|
||||
|
||||
const page = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
api.onHistory = () => page.promise
|
||||
const loading = session.loadOlder()
|
||||
const delivered = reminderEvent(3, 'schedule-delivered')
|
||||
session.handleMuxEnvelope('late' as never, {
|
||||
type: 'session/event', sessionId: SID, event: delivered,
|
||||
view: reminderView('schedule-delivered'),
|
||||
})
|
||||
|
||||
api.onHistory = () => histResponse(newer)
|
||||
const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
|
||||
try {
|
||||
session.handleMuxEnvelope('drifted' as never, {
|
||||
type: 'session/event', sessionId: SID, event: reminderEvent(3, 'schedule-drifted'),
|
||||
view: reminderView('schedule-drifted'),
|
||||
})
|
||||
await vi.waitFor(() => {
|
||||
expect(api.callsOf('session.history')).toHaveLength(3)
|
||||
expect(session.getSnapshot().openState).toBe('open')
|
||||
})
|
||||
expect(errorSpy).toHaveBeenCalledWith(
|
||||
'[web-runtime] older-page late session event failed identity validation:',
|
||||
expect.objectContaining({ message: 'session event identity mismatch at seq 3' }),
|
||||
)
|
||||
} finally {
|
||||
errorSpy.mockRestore()
|
||||
page.resolve(ok({ events: entries(logRange(0, 6)) as never[], hasMore: false }))
|
||||
await loading
|
||||
}
|
||||
})
|
||||
|
||||
it('resyncs when an older page disagrees with its buffered late event identity', async () => {
|
||||
const { api, session } = makeSession()
|
||||
const newer = logRange(6, 12)
|
||||
const pageEvent = reminderEvent(3, 'schedule-page')
|
||||
const delivered = reminderEvent(3, 'schedule-delivered')
|
||||
const older = [...logRange(0, 3), pageEvent, ...logRange(4, 6)]
|
||||
api.onHistory = () => histResponse(newer, true)
|
||||
await session.open()
|
||||
|
||||
const gate = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
api.onHistory = () => gate.promise
|
||||
const loading = session.loadOlder()
|
||||
session.handleMuxEnvelope('late' as never, {
|
||||
type: 'session/event', sessionId: SID, event: delivered,
|
||||
view: reminderView('schedule-delivered'),
|
||||
})
|
||||
api.onHistory = () => histResponse(newer)
|
||||
const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
|
||||
try {
|
||||
gate.resolve(ok({ events: entries(older) as never[], hasMore: false }))
|
||||
await loading
|
||||
await vi.waitFor(() => {
|
||||
expect(api.callsOf('session.history')).toHaveLength(3)
|
||||
expect(session.getSnapshot().openState).toBe('open')
|
||||
})
|
||||
expect(errorSpy).toHaveBeenCalledWith(
|
||||
'[web-runtime] older-page session event failed identity validation:',
|
||||
expect.objectContaining({ message: 'session event identity mismatch at seq 3' }),
|
||||
)
|
||||
} finally {
|
||||
errorSpy.mockRestore()
|
||||
}
|
||||
})
|
||||
})
|
||||
|
||||
|
||||
describe('live event path', () => {
|
||||
async function opened(events: SessionEvent[] = plainTurn(0, 0, 'a', 'b')) {
|
||||
@@ -842,12 +548,11 @@ describe('live event path', () => {
|
||||
})
|
||||
|
||||
it('repairs a seq gap by repulling the tail page instead of appending a hole', async () => {
|
||||
const first = plainTurn(0, 0, 'a', 'b')
|
||||
const { api, session } = await opened(first) // tail seq = 5
|
||||
const repaired = [...first, ...plainTurn(6, 1, 'c', 'd')]
|
||||
const { api, session } = await opened(plainTurn(0, 0, 'a', 'b')) // tail seq = 5
|
||||
const repaired = [...plainTurn(0, 0, 'a', 'b'), ...plainTurn(6, 1, 'c', 'd')]
|
||||
api.onHistory = () => histResponse(repaired)
|
||||
// seq 9 with tail 5 → gap; the event detours to the buffer and one history refetch fires.
|
||||
session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: repaired[9]! })
|
||||
session.handleMuxEnvelope('r' as never, { type: 'session/event', sessionId: SID, event: ev.assistant(9, 1, 'd') })
|
||||
await vi.waitFor(() => {
|
||||
expect(api.callsOf('session.history').length).toBe(2)
|
||||
})
|
||||
@@ -855,64 +560,6 @@ describe('live event path', () => {
|
||||
const seqs = session.getSnapshot().nodes.map(n => n.seq)
|
||||
expect(seqs).toEqual([1, 3, 7, 9]) // both turns' user/assistant, no hole, no duplicate 9
|
||||
})
|
||||
|
||||
it('continues repair when one tail snapshot leaves a later buffered gap', async () => {
|
||||
const initial = logRange(0, 6)
|
||||
const firstGap = ev.user(9, 'first repaired event')
|
||||
const laterGap = ev.user(12, 'later buffered event')
|
||||
const firstSnapshot = [...initial, ...logRange(6, 9), firstGap]
|
||||
const completeSnapshot = [...firstSnapshot, ...logRange(10, 12), laterGap]
|
||||
const firstRepair = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
const secondRepair = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
const { api, session } = await opened(initial)
|
||||
let repairs = 0
|
||||
api.onHistory = () => ++repairs === 1 ? firstRepair.promise : secondRepair.promise
|
||||
|
||||
session.handleMuxEnvelope('first-gap' as never, {
|
||||
type: 'session/event', sessionId: SID, event: firstGap,
|
||||
})
|
||||
session.handleMuxEnvelope('later-gap' as never, {
|
||||
type: 'session/event', sessionId: SID, event: laterGap,
|
||||
})
|
||||
firstRepair.resolve(ok({ events: entries(firstSnapshot) as never[], hasMore: false }))
|
||||
|
||||
await vi.waitFor(() => { expect(repairs).toBe(2) })
|
||||
secondRepair.resolve(ok({ events: entries(completeSnapshot) as never[], hasMore: false }))
|
||||
await vi.waitFor(() => {
|
||||
expect(session.getSnapshot().nodes.map(node => node.seq)).toEqual([9, 12])
|
||||
})
|
||||
})
|
||||
|
||||
it('resyncs when a successful gap snapshot conflicts with a buffered event identity', async () => {
|
||||
const initial = logRange(0, 6)
|
||||
const live = ev.user(9, 'live identity')
|
||||
const conflicting = ev.user(9, 'conflicting history identity')
|
||||
const consistent = [...initial, ...logRange(6, 9), live]
|
||||
const { api, session } = await opened(initial)
|
||||
let repairs = 0
|
||||
api.onHistory = () => {
|
||||
repairs++
|
||||
return repairs === 1
|
||||
? histResponse([...initial, ...logRange(6, 9), conflicting])
|
||||
: histResponse(consistent)
|
||||
}
|
||||
const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined)
|
||||
try {
|
||||
session.handleMuxEnvelope('gap' as never, {
|
||||
type: 'session/event', sessionId: SID, event: live,
|
||||
})
|
||||
await vi.waitFor(() => {
|
||||
expect(repairs).toBe(2)
|
||||
expect(session.getSnapshot().nodes.map(node => node.seq)).toEqual([9])
|
||||
})
|
||||
expect(errorSpy).toHaveBeenCalledWith(
|
||||
'[web-runtime] gap repair snapshot failed validation:',
|
||||
expect.objectContaining({ message: 'session event identity mismatch at seq 9' }),
|
||||
)
|
||||
} finally {
|
||||
errorSpy.mockRestore()
|
||||
}
|
||||
})
|
||||
})
|
||||
|
||||
describe('paging', () => {
|
||||
@@ -931,27 +578,6 @@ describe('paging', () => {
|
||||
expect(snapshot.nodes.map(n => n.seq)).toEqual([1, 3, 7, 9])
|
||||
})
|
||||
|
||||
it('keeps a concurrent live tail in the current window before prepending the older page', async () => {
|
||||
const older = plainTurn(0, 0, '旧问', '旧答')
|
||||
const newer = plainTurn(6, 1, '新问', '新答')
|
||||
const page = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
const { api, session } = makeSession()
|
||||
api.onHistory = payload => payload.beforeSeq === undefined
|
||||
? histResponse(newer, true)
|
||||
: page.promise
|
||||
await session.open()
|
||||
|
||||
const loading = session.loadOlder()
|
||||
session.handleMuxEnvelope('live-tail' as never, {
|
||||
type: 'session/event', sessionId: SID, event: ev.user(12, '并发尾部'),
|
||||
})
|
||||
expect(session.getSnapshot().nodes.map(node => node.seq)).toEqual([7, 9, 12])
|
||||
page.resolve(await histResponse(older, false))
|
||||
await loading
|
||||
|
||||
expect(session.getSnapshot().nodes.map(node => node.seq)).toEqual([1, 3, 7, 9, 12])
|
||||
})
|
||||
|
||||
it('renders a page whose checkpoint shadows seqs below the window head, logging nothing', async () => {
|
||||
// Pagination no longer spends maxMessages quota on replacement copies, so a
|
||||
// page can carry a compaction checkpoint whose surfaceOp.start lies outside
|
||||
@@ -1257,12 +883,11 @@ describe('remaining branches', () => {
|
||||
|
||||
it('subscribed baseline past the window tail triggers the second stitch pull in doOpen', async () => {
|
||||
const { api, session } = makeSession()
|
||||
const first = plainTurn(0, 0, 'a', 'b')
|
||||
const full = [...first, ...plainTurn(6, 1, 'c', 'd')]
|
||||
const full = [...plainTurn(0, 0, 'a', 'b'), ...plainTurn(6, 1, 'c', 'd')]
|
||||
let call = 0
|
||||
api.onHistory = () => {
|
||||
call++
|
||||
return histResponse(call === 1 ? first : full)
|
||||
return histResponse(call === 1 ? plainTurn(0, 0, 'a', 'b') : full)
|
||||
}
|
||||
// Baseline arrives before open: lastSeq 11 > first page tail 5 → doOpen repulls once.
|
||||
session.handleMuxEnvelope('rs' as never, { type: 'session/subscribed', sessionId: SID, lastSeq: 11 })
|
||||
@@ -1550,107 +1175,6 @@ describe('resync', () => {
|
||||
expect(snapshot.nodes.map(n => n.seq)).toEqual([7, 9])
|
||||
})
|
||||
|
||||
it('a stale loadOlder success and finally cannot mutate or clear a fresh-generation page request', async () => {
|
||||
const { api, session } = makeSession()
|
||||
api.onHistory = () => histResponse(logRange(6, 12), true)
|
||||
await session.open()
|
||||
|
||||
const stale = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
api.onHistory = () => stale.promise
|
||||
const staleLoad = session.loadOlder()
|
||||
|
||||
api.onHistory = () => histResponse(logRange(12, 18), true)
|
||||
await session.resync()
|
||||
const fresh = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
api.onHistory = () => fresh.promise
|
||||
const freshLoad = session.loadOlder()
|
||||
expect(session.getSnapshot()).toMatchObject({ loadingOlder: true, hasMore: true })
|
||||
|
||||
stale.resolve(ok({ events: entries(logRange(0, 6)) as never[], hasMore: false }))
|
||||
await staleLoad
|
||||
expect(session.getSnapshot()).toMatchObject({ loadingOlder: true, hasMore: true })
|
||||
|
||||
fresh.resolve(ok({ events: entries(logRange(6, 12)) as never[], hasMore: false }))
|
||||
await freshLoad
|
||||
expect(session.getSnapshot()).toMatchObject({ loadingOlder: false, hasMore: false })
|
||||
})
|
||||
|
||||
it('a stale rejected or never-settled loadOlder cannot freeze the new generation', async () => {
|
||||
const { api, session } = makeSession()
|
||||
api.onHistory = () => histResponse(logRange(6, 12), true)
|
||||
await session.open()
|
||||
|
||||
const stale = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
api.onHistory = () => stale.promise
|
||||
const staleLoad = session.loadOlder()
|
||||
api.onHistory = () => histResponse(logRange(12, 18), false)
|
||||
await session.resync()
|
||||
expect(session.getSnapshot()).toMatchObject({ openState: 'open', loadingOlder: false })
|
||||
|
||||
stale.reject(new Error('old page connection closed'))
|
||||
await staleLoad
|
||||
expect(session.getSnapshot()).toMatchObject({ openState: 'open', loadingOlder: false })
|
||||
|
||||
const never = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
// Re-open a pageable generation and park a request that never settles.
|
||||
api.onHistory = () => histResponse(logRange(18, 24), true)
|
||||
await session.resync()
|
||||
api.onHistory = () => never.promise
|
||||
void session.loadOlder()
|
||||
expect(session.getSnapshot().loadingOlder).toBe(true)
|
||||
api.onHistory = () => histResponse(logRange(24, 30), false)
|
||||
await session.resync()
|
||||
expect(session.getSnapshot()).toMatchObject({ openState: 'open', loadingOlder: false })
|
||||
})
|
||||
|
||||
it('stale gap success, rejection, and finally cannot clear a fresh repair owner', async () => {
|
||||
const { api, session } = makeSession()
|
||||
const initial = logRange(0, 6)
|
||||
api.onHistory = () => histResponse(initial)
|
||||
await session.open()
|
||||
|
||||
const staleRepair = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
api.onHistory = () => staleRepair.promise
|
||||
session.handleMuxEnvelope('old-gap' as never, {
|
||||
type: 'session/event', sessionId: SID, event: reminderEvent(9, 'old-gap'),
|
||||
})
|
||||
|
||||
const freshBase = logRange(10, 16)
|
||||
api.onHistory = () => histResponse(freshBase)
|
||||
await session.resync()
|
||||
|
||||
const freshRepair = deferred<Awaited<ReturnType<FakeApiClient['onHistory']>>>()
|
||||
let freshRepairCalls = 0
|
||||
api.onHistory = () => {
|
||||
freshRepairCalls++
|
||||
return freshRepair.promise
|
||||
}
|
||||
const due = reminderEvent(18, 'fresh-gap')
|
||||
session.handleMuxEnvelope('fresh-gap' as never, {
|
||||
type: 'session/event', sessionId: SID, event: due, view: reminderView('fresh-gap'),
|
||||
})
|
||||
expect(freshRepairCalls).toBe(1)
|
||||
|
||||
staleRepair.reject(new Error('stale gap connection closed'))
|
||||
await Promise.resolve()
|
||||
await Promise.resolve()
|
||||
const trailing = at(19, { type: 'fixture/log', data: { index: 19 } })
|
||||
session.handleMuxEnvelope('fresh-trailing' as never, {
|
||||
type: 'session/event', sessionId: SID, event: trailing,
|
||||
})
|
||||
expect(freshRepairCalls).toBe(1)
|
||||
|
||||
freshRepair.resolve(ok({
|
||||
events: entries([...freshBase, ...logRange(16, 18), due, trailing]) as never[],
|
||||
hasMore: false,
|
||||
}))
|
||||
await vi.waitFor(() => {
|
||||
expect(session.getSnapshot().nodes).toMatchObject([{
|
||||
kind: 'presented-event', seq: 18, view: { id: 'fresh-gap' },
|
||||
}])
|
||||
})
|
||||
})
|
||||
|
||||
})
|
||||
|
||||
describe('nested run_code sub-dispatches', () => {
|
||||
|
||||
@@ -434,32 +434,6 @@ describe('TranscriptAdapter', () => {
|
||||
})
|
||||
})
|
||||
|
||||
it('materializes generic presented-event nodes on replay and live append', () => {
|
||||
const replayed = at(0, { type: 'schedule/change', data: { operation: 'dispatch', id: 'schedule-1' } })
|
||||
const live = at(1, { type: 'schedule/change', data: { operation: 'dispatch', id: 'schedule-2' } })
|
||||
const adapter = new TranscriptAdapter()
|
||||
adapter.reset([replayed], [{
|
||||
for: 'event',
|
||||
view: { id: 'schedule-1', prompt: '检查日志' },
|
||||
}])
|
||||
adapter.append(live, {
|
||||
for: 'event',
|
||||
view: { id: 'schedule-2', prompt: '检查发布' },
|
||||
})
|
||||
expect(adapter.nodes()).toEqual([
|
||||
{
|
||||
kind: 'presented-event', seq: 0, time: 1_700_000_000_000,
|
||||
eventType: 'schedule/change',
|
||||
view: { id: 'schedule-1', prompt: '检查日志' },
|
||||
},
|
||||
{
|
||||
kind: 'presented-event', seq: 1, time: 1_700_000_000_001,
|
||||
eventType: 'schedule/change',
|
||||
view: { id: 'schedule-2', prompt: '检查发布' },
|
||||
},
|
||||
])
|
||||
})
|
||||
|
||||
it('leaves callView null when the paired call fell outside the window (cross-page break)', () => {
|
||||
const adapter = new TranscriptAdapter()
|
||||
const resultView = { for: 'result' as const, view: { card: 'generic' as const, title: '孤儿' } }
|
||||
|
||||
@@ -24,8 +24,6 @@ The chat view keeps Tool placement but delegates Tool presentation. It passes ea
|
||||
|
||||
The chat flow projects consecutive model-retry nodes across retry turns into one stable, muted status row updated to the latest attempt; every retry event remains in the runtime snapshot and session log. Its frontend countdown anchors the scheduled delay to client receipt, avoiding host/browser clock skew, rounds remaining time up to seconds, and has a one-second floor. The latest unresolved retry uses a left-to-right text shimmer. Subsequent turn facts distinguish an attempt that started from one cancelled during backoff, while the Host running bit only controls the live animation; the row then shows a static completed or cancelled label. Normal policy rows show the finite retry maximum; always policy rows show `∞`. Activating the row reveals the latest exact retry delay and failure message. The client runtime removes each failed step's streaming tail before its retry node arrives, while the status remains visible after a later attempt succeeds. An unretried terminal failure renders as a persistent inline status at its turn boundary, showing the display-safe durable message and optional error code without offering an action the Host cannot fulfill; AUTH copy never echoes provider-supplied credential fragments.
|
||||
|
||||
Host-presented durable events use the keyed `'conversation.chat.eventview'` seat alongside whole-Tool presentation. The React-free runtime turns a generic event sidecar into a `PresentedEventNode` carrying the durable event type and view; Chat dispatches on that open type, and a domain UI plugin may register its own row without adding domain vocabulary here. When no registrant is loaded, `GenericEventCard` keeps the event type and JSON payload visible in an expandable disclosure rather than dropping the durable event.
|
||||
|
||||
`TodoDock` takes the `'conversation.input.dock'` list slot at `order: 0` — before Goal and Queue — and is the plan strip: it reads the host-computed `todos` projection via `useProjection` (standing plan: latest `todo/write` with no later `turn/start`) and renders `TodoPanel`, which takes the plain list, hides itself while the list is empty, and starts collapsed as a header of title plus its own `·`-joined per-status counts (localized, `1 completed · 2 in progress · 1 pending`, zero-count segments omitted). The dock adapter owns selection so the panel stays a pure function of its props. Anything the input-zone composer chain hides (a `conversation.composer` takeover such as ui-question's) hides the whole dock, this strip included. The `todo_write` Tool row belongs to [`ui-tool`](../ui-tool/README.md).
|
||||
|
||||
`QueueDock` is the terminal input-dock entry at `order: 20`. It hides while empty, renders one pending row directly, and defaults two or more rows to a collapsed `"<n> 条排队消息"` header whose button expands or collapses the complete list. The header exposes `aria-expanded` and `aria-controls`; the expanded list scrolls within a 180px height bound. An active edit or mutation keeps its rows visible, and emptying the queue restores the collapsed default for the next queue. Each visible ordinary-session row remains a single-line preview with its exact-occurrence edit, delete, and strict-steer actions; addressed subagents retain the rows as a read-only projection because their continuation transport does not expose queue mutation. If strict steer loses to a closed window, the original occurrence remains queued for normal delivery; if the driver already claimed it, normal delivery is already underway. Neither converged race displays a failure, while transport and unknown failures do.
|
||||
|
||||
@@ -24,8 +24,6 @@ Think 行默认保持折叠，并在不展开思维链的情况下暴露实时
|
||||
|
||||
审批经由本包声明的链接管编辑器：`ApprovalPanel` 注册为按选择器路由的 `'conversation.composer'` 配置项（ui-question 模式），在审批等待未决期间取代 InputBar 占据编辑器（琥珀色条、理由标题、来自运行中调用参数的配对命令行、一次性的拒绝／允许）。`contract/slots.ts` 中的 `PendingApproval` 领域面在运行时 `PendingWait` 载体之上拥有 wire 编码——带审计关联的 `ApprovalResponsePayload` 值；广播的 `approval/resolved` 帧使等待落定并恢复编辑器。运行时 manager 会将所有审批或问题等待通过 `SessionSummary.pendingInteraction` 投影出来，未实例化的 Session 也不例外；`ui-workspace` 负责其侧边栏呈现。未决等待完全离开消息流：问题（ui-question）与审批（ApprovalPanel）都经编辑器接管作答，不再保留只读占位卡。编辑器底行的 Access 席位挂载 `PermissionSelect`，由 host 计算的 `permissions` 投影经标准工具包 `useProjection` 供数（key 缺席即隐藏 chip）；chip 打开 Menu 原语下拉，其中 kebab-case 预设名渲染为 Title Case 标签；普通安全预设会立即经输入栏注入的 `command` 回调提交 `/permission <preset>`，而 `danger-full-access` 在界面中显示为 `Full access`，选择后先打开页面内的 Modal 风险确认。用户勾选确认项前启用按钮始终不可用；取消、Escape、关闭按钮与点击遮罩都不会提交命令。
|
||||
|
||||
由 Host presentation 的持久事件使用键控的 `'conversation.chat.eventview'` 座位，与整体 Tool presentation 并行。无 React 的 runtime 会把通用事件 sidecar 转为携带持久事件类型与 view 的 `PresentedEventNode`；Chat 按该开放类型分发，领域 UI 插件无需在本包增加领域词汇即可注册自己的行。没有 registrant 被加载时，`GenericEventCard` 会在可展开 disclosure 中保留可见的事件类型与 JSON payload，而不会丢弃该持久事件。
|
||||
|
||||
`TodoDock` 以 `order: 0` 占用 `'conversation.input.dock'` 列表 slot（位于 Goal 与 Queue 之前），作为计划条读取 host 计算的 `todos` 投影（站立计划：其后没有更晚 `turn/start` 的最近一次 `todo/write`）并渲染 `TodoPanel`。面板接收纯列表，列表为空时自我隐藏；列表非空时默认折叠，表头显示标题及以 `·` 连接的各状态计数（如 `1 已完成 · 2 进行中 · 1 待处理`，省略零计数）。dock adapter 拥有 selection，因此面板保持为 props 的纯函数。输入区 composer 链隐藏的一切也会隐藏整个 dock。`todo_write` Tool 行属于 [`ui-tool`](../ui-tool/README.md)。
|
||||
|
||||
`QueueDock` 是 `order: 20` 的末端 input-dock 条目。队列为空时隐藏；只有一个待处理项时直接渲染该行；存在两个或更多待处理项时，默认收起为 `"<n> 条排队消息"` 表头，其按钮可展开或收起完整列表。表头暴露 `aria-expanded` 和 `aria-controls`；展开后的列表以 180px 为高度上限，并可滚动。存在进行中的编辑或变更时，列表行会保持可见；队列清空后，下一次出现队列时会恢复默认收起状态。普通会话中的每条可见行仍是单行预览，并提供针对精确单次入队项的编辑、删除和严格 steering 操作；已寻址 subagent 则保留只读行，因为其继续执行传输不提供 Queue 变更。如果严格 steering 输给已关闭的窗口，原单次入队项会留在 Queue 中正常投递；如果驱动器已经认领该项，正常投递就已开始。这两种已收敛的竞态都不显示失败，传输和未知错误仍会显示。
|
||||
|
||||
@@ -306,7 +306,6 @@ export function apply(ctx: Context): void {
|
||||
locale: NS,
|
||||
children: {
|
||||
'conversation.chat.tool': { kind: 'single', scope: 'session' },
|
||||
'conversation.chat.eventview': { kind: 'keyed', scope: 'session' },
|
||||
'conversation.chat.commandview': { kind: 'keyed', scope: 'session' },
|
||||
'conversation.chat.turnTail': { kind: 'chain', scope: 'session' },
|
||||
},
|
||||
|
||||
@@ -24,7 +24,7 @@ import {
|
||||
memo, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode,
|
||||
} from 'react'
|
||||
import type {
|
||||
CommandNode, ConversationNode, ConversationSnapshot, PresentedEventNode, RunningToolCall, ToolCallBlock, ToolResultNode,
|
||||
CommandNode, ConversationNode, ConversationSnapshot, RunningToolCall, ToolCallBlock, ToolResultNode,
|
||||
} from '@deepseek-ai/dsh-client-runtime/client'
|
||||
import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
|
||||
import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
|
||||
@@ -33,7 +33,6 @@ import { assistantActionsSeqs, assistantBranchSeqs, deriveChatFlow, runningTurnS
|
||||
import { AssistantMarkdown } from './AssistantMarkdown.tsx'
|
||||
import { CompactionCommandCard } from './CompactionCommandCard.tsx'
|
||||
import { GenericCommandCard } from './GenericCommandCard.tsx'
|
||||
import { GenericEventCard } from './GenericEventCard.tsx'
|
||||
import { MessageItem, PendingSteeringBubble } from './MessageItem.tsx'
|
||||
import { formatRunDuration } from './message-chrome.ts'
|
||||
import { deriveTurnMetrics } from './turn-metrics.ts'
|
||||
@@ -212,24 +211,6 @@ const CommandRow = memo(function CommandRow({ renderSlot, node, compaction, t }:
|
||||
)
|
||||
})
|
||||
|
||||
/** One Host-presented durable event: dispatch by durable event type, with a
|
||||
* visible JSON disclosure when no domain renderer is loaded. */
|
||||
const EventRow = memo(function EventRow({ renderSlot, node, t }: {
|
||||
renderSlot: RenderChatSlot
|
||||
node: PresentedEventNode
|
||||
t: ChatViewSlotProps['t']
|
||||
}) {
|
||||
const owner = useMemo(() => ({ node }), [node])
|
||||
return (
|
||||
<div className={css.callRow}>
|
||||
{renderSlot('conversation.chat.eventview', owner, {
|
||||
entryKey: node.eventType,
|
||||
fallback: <GenericEventCard {...owner} t={t} />,
|
||||
})}
|
||||
</div>
|
||||
)
|
||||
})
|
||||
|
||||
/** Turn-level model activity label retained across first-token, tool, and streaming phases. */
|
||||
function TurnStatus({ startTime, t }: {
|
||||
/** The running turn's logged `turn/start` time; null falls back to mount
|
||||
@@ -563,9 +544,6 @@ export function ChatView({
|
||||
if (node.kind === 'command') {
|
||||
return <CommandRow renderSlot={renderSlot} node={node} t={t} />
|
||||
}
|
||||
if (node.kind === 'presented-event') {
|
||||
return <EventRow renderSlot={renderSlot} node={node} t={t} />
|
||||
}
|
||||
/* v8 ignore next -- tool-result never reaches here: deriveChatFlow folds them into groups. */
|
||||
if (node.kind === 'tool-result') return null
|
||||
return (
|
||||
|
||||
@@ -1,33 +0,0 @@
|
||||
// GenericEventCard: the visible fallback for a Host-presented durable event.
|
||||
// A domain plugin may replace it through the keyed eventview slot; without
|
||||
// one, the durable event type and JSON sidecar remain inspectable in the flow.
|
||||
|
||||
import { useMemo, useState } from 'react'
|
||||
import { DisclosureRow, IconSparkle16 } from '@deepseek-ai/dsh-client-ui-primitives'
|
||||
import type { ChatViewSlotProps, EventRowOwnerProps } from '../contract/slots.ts'
|
||||
import css from './ContextInjectionRow.module.css'
|
||||
|
||||
/** Card props: the event owner payload plus the render site's locale seat. */
|
||||
export interface GenericEventCardProps extends EventRowOwnerProps {
|
||||
t: ChatViewSlotProps['t']
|
||||
}
|
||||
|
||||
/** Render an unregistered event presentation as a visible JSON disclosure. */
|
||||
export function GenericEventCard({ node, t }: GenericEventCardProps) {
|
||||
const [open, setOpen] = useState(false)
|
||||
const body = useMemo(() => open ? JSON.stringify(node.view, null, 2) : '', [node.view, open])
|
||||
return (
|
||||
<DisclosureRow
|
||||
className={css.root}
|
||||
icon={<IconSparkle16 size={14} />}
|
||||
chevronClassName={css.chevron}
|
||||
title={t('message.presentedEvent', { key: node.eventType })}
|
||||
open={open}
|
||||
expandable
|
||||
expandOnRowClick
|
||||
onToggle={() => { setOpen(value => !value) }}
|
||||
>
|
||||
<pre className={css.body} data-presented-event-body>{body}</pre>
|
||||
</DisclosureRow>
|
||||
)
|
||||
}
|
||||
@@ -3,10 +3,7 @@ import type { ReactNode, RefObject } from 'react'
|
||||
import type {
|
||||
InjectFace, MaybeSnapshotSelectorHook, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore, SnapshotSelectorHook,
|
||||
} from '@deepseek-ai/dsh-client-ui-slots'
|
||||
import type {
|
||||
CommandNode, CompactionSummaryNode, ConversationNode, ConversationSnapshot, ObservableSnapshot, PendingInteraction,
|
||||
PendingWait, PresentedEventNode, SessionId, ToolCallBlock, WorkspaceId,
|
||||
} from '@deepseek-ai/dsh-client-runtime/client'
|
||||
import type { CommandNode, CompactionSummaryNode, ConversationNode, ConversationSnapshot, ObservableSnapshot, PendingInteraction, PendingWait, SessionId, ToolCallBlock, WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
|
||||
import type { MarkdownFileMentions } from '@deepseek-ai/dsh-client-ui-primitives'
|
||||
import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
|
||||
import type { ComposerBlock } from '../input/blocks.ts'
|
||||
@@ -41,13 +38,6 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
|
||||
* {@link ToolTreeOwnerProps} for every root and child wrapper.
|
||||
*/
|
||||
'conversation.chat.tool': { kind: 'single'; scope: 'session'; owner: ToolTreeOwnerProps }
|
||||
/**
|
||||
* The chat view's per-event presentation hole: keyed dispatch on the
|
||||
* durable event type. The durable event remains in the
|
||||
* runtime node; a feature plugin may replace the visible JSON fallback
|
||||
* with a domain renderer without entering ui-conversation.
|
||||
*/
|
||||
'conversation.chat.eventview': { kind: 'keyed'; scope: 'session'; owner: EventRowOwnerProps }
|
||||
/**
|
||||
* The chat view's per-command row hole: keyed dispatch on the command
|
||||
* name (`command/run.name`; a run-less cross-window node has none and
|
||||
@@ -249,15 +239,6 @@ export interface DetailsToolOwnerProps {
|
||||
cwd?: string | undefined
|
||||
}
|
||||
|
||||
/** Owner share for one Host-presented durable event. */
|
||||
export interface EventRowOwnerProps {
|
||||
/** Generic runtime node carrying the durable event identity and keyed sidecar. */
|
||||
node: PresentedEventNode
|
||||
}
|
||||
|
||||
/** Full props of a registered event-presentation row component. */
|
||||
export type EventRowProps = PropsRuntime<'conversation.chat.eventview'>
|
||||
|
||||
/**
|
||||
* Owner share of the per-command row slot: the frozen {@link CommandNode}
|
||||
* slice off the snapshot (cache-stable reference — memo premise). The node
|
||||
@@ -572,10 +553,9 @@ export interface ChatViewInjected {
|
||||
fileMentions: (owner: TurnTailOwnerProps) => MarkdownFileMentions | undefined
|
||||
}
|
||||
|
||||
/** Full chat-view component props: runtime plus Tool, event, command, and turn-tail render shares. */
|
||||
/** Full chat-view component props: runtime & its Tool/command/tail render shares & store & injected & locale seat. */
|
||||
export type ChatViewSlotProps =
|
||||
PropsRuntime<'conversation.view'>
|
||||
& PropsRenderSlots<'conversation.chat.tool' | 'conversation.chat.eventview' | 'conversation.chat.commandview' | 'conversation.chat.turnTail'>
|
||||
PropsRuntime<'conversation.view'> & PropsRenderSlots<'conversation.chat.tool' | 'conversation.chat.commandview' | 'conversation.chat.turnTail'>
|
||||
& PropsStore<ChatStore> & ChatViewInjected & PropsLocale<'conversation'>
|
||||
|
||||
/**
|
||||
|
||||
@@ -17,7 +17,7 @@ export type {
|
||||
ComposerChainProps, ConversationInjected,
|
||||
ConversationSessionHeaderInjected, ConversationSessionInjected, ConversationSlotProps, ConvViewOwnerProps,
|
||||
ConvViewProps, DetailsInjected, DetailsSlotProps, DetailsToolOwnerProps, EmptyWorkspaceOwnerProps,
|
||||
EventRowOwnerProps, EventRowProps, ToolTreeOwnerProps, TurnTailOwnerProps,
|
||||
ToolTreeOwnerProps, TurnTailOwnerProps,
|
||||
} from './contract/slots.ts'
|
||||
// Export discipline: packages/client/AGENTS.md.
|
||||
|
||||
|
||||
@@ -68,7 +68,6 @@ export const zh = {
|
||||
'chat.toBottom': '回到底部',
|
||||
'message.extraBlock': '附加内容块',
|
||||
'message.contextInjection': '上下文注入',
|
||||
'message.presentedEvent': '事件：{key}',
|
||||
'message.contextRecall': '跨会话召回',
|
||||
'message.context.instructions.loaded': '已载入',
|
||||
'message.context.instructions.added': '已新增',
|
||||
@@ -212,7 +211,6 @@ export const en = {
|
||||
'chat.toBottom': 'Back to bottom',
|
||||
'message.extraBlock': 'Extra content block',
|
||||
'message.contextInjection': 'Context injection',
|
||||
'message.presentedEvent': 'Event: {key}',
|
||||
'message.contextRecall': 'Session recall',
|
||||
'message.context.instructions.loaded': 'loaded',
|
||||
'message.context.instructions.added': 'added',
|
||||
|
||||
@@ -53,7 +53,7 @@ describe('apply wiring', () => {
|
||||
await b.runtime.dispose()
|
||||
})
|
||||
|
||||
it('registers the chat view as the first ring entry with Tool and event seats', async () => {
|
||||
it('registers the chat view as the first ring entry, declaring the whole-Tool seat', async () => {
|
||||
const b = await bench()
|
||||
const entries = b.slots.entries('conversation.view')
|
||||
expect(entries.map(e => e.options.id)).toEqual(['chat'])
|
||||
@@ -63,7 +63,6 @@ describe('apply wiring', () => {
|
||||
// Declaring is claiming: the chat entry's registration put the hole on
|
||||
// the ledger with the contract's kind/scope.
|
||||
expect(b.slots.spec('conversation.chat.tool')).toEqual({ kind: 'single', scope: 'session' })
|
||||
expect(b.slots.spec('conversation.chat.eventview')).toEqual({ kind: 'keyed', scope: 'session' })
|
||||
await b.runtime.dispose()
|
||||
})
|
||||
|
||||
@@ -111,8 +110,6 @@ describe('apply wiring', () => {
|
||||
expect(b.slots.entries('conversation.view')).toHaveLength(0)
|
||||
expect(b.slots.entries('conversation.chat.tool')).toHaveLength(0)
|
||||
expect(b.slots.spec('conversation.chat.tool')).toBeUndefined()
|
||||
expect(b.slots.entries('conversation.chat.eventview')).toHaveLength(0)
|
||||
expect(b.slots.spec('conversation.chat.eventview')).toBeUndefined()
|
||||
expect(b.slots.entries('details')).toHaveLength(0)
|
||||
expect(b.slots.entries('settings.general.item')).toHaveLength(0)
|
||||
expect(b.runtime.ctx.get('conversation')).toBeUndefined()
|
||||
|
||||
@@ -8,7 +8,7 @@ import { Profiler } from 'react'
|
||||
import { act, cleanup, fireEvent, render, within } from '@testing-library/react'
|
||||
import type {
|
||||
AssistantMessageNode, CommandNode, CompactionSummaryNode, ConversationNode, ConversationSnapshot,
|
||||
ModelRetryNode, PresentedEventNode, RunningToolCall, SessionId, SessionListState, ToolResultNode, TurnErrorNode,
|
||||
ModelRetryNode, RunningToolCall, SessionId, SessionListState, ToolResultNode, TurnErrorNode,
|
||||
UserMessageNode, WorkspaceListState,
|
||||
} from '@deepseek-ai/dsh-client-runtime/client'
|
||||
import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
|
||||
@@ -106,13 +106,6 @@ const compaction = (over: Partial<CompactionSummaryNode> = {}): CompactionSummar
|
||||
shadowedTokenCount: 11_309,
|
||||
...over,
|
||||
})
|
||||
const presentedEvent = (seq: number): PresentedEventNode => ({
|
||||
kind: 'presented-event',
|
||||
seq,
|
||||
time: seq * 1_000,
|
||||
eventType: 'schedule/change',
|
||||
view: { prompt: 'check logs', scheduleId: 'schedule-1' },
|
||||
})
|
||||
|
||||
/** Empty sessions-list hook for the global standard-kit seat. */
|
||||
function emptySessions() {
|
||||
@@ -960,21 +953,6 @@ describe('ChatView', () => {
|
||||
expect(calls[0]?.entryKey).toBeUndefined()
|
||||
})
|
||||
|
||||
it('dispatches presented events by key and keeps a visible JSON fallback', () => {
|
||||
const node = presentedEvent(3)
|
||||
const h = makeHarness({ nodes: [node] })
|
||||
const calls: { key: string; entryKey?: string }[] = []
|
||||
h.props.renderSlot = ((key: string, _owner: object, opts?: { entryKey?: string; fallback?: React.ReactNode }) => {
|
||||
calls.push({ key, ...(opts?.entryKey !== undefined ? { entryKey: opts.entryKey } : {}) })
|
||||
return opts?.fallback ?? null
|
||||
})
|
||||
const view = render(<h.ChatView {...h.props} />)
|
||||
expect(calls).toEqual([{ key: 'conversation.chat.eventview', entryKey: 'schedule/change' }])
|
||||
fireEvent.click(view.getByText('事件：schedule/change'))
|
||||
expect(view.getByText(/"prompt": "check logs"/)).toBeTruthy()
|
||||
expect(view.getByText(/"scheduleId": "schedule-1"/)).toBeTruthy()
|
||||
})
|
||||
|
||||
it('prepend preserves a semantic row; a trailing user node force-scrolls', () => {
|
||||
const h = makeHarness({ nodes: [user(5, 'later'), assistant(6, 'a')], hasMore: true })
|
||||
const view = render(<h.ChatView {...h.props} />)
|
||||
|
||||
@@ -1,6 +0,0 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/client/ui-schedule/README.md
|
||||
README.md: c7b1934cd5a8e6ac3e3cc022ec67a948ec538786
|
||||
README.zh.md: 8ba09550e1506ad9233827ec4e95fc35fa8d7c0d
|
||||
@@ -1,20 +0,0 @@
|
||||
# @deepseek-ai/dsh-client-ui-schedule
|
||||
|
||||
English | [中文](README.zh.md)
|
||||
|
||||
Browser-only renderer for durable Schedule reminder receipts. The plugin registers the durable `schedule/change` event type in the conversation-owned `conversation.chat.eventview` slot. The generic runtime continues to carry the durable event identity and its Host-computed JSON sidecar; this package owns only the Schedule card.
|
||||
|
||||
The card displays the reminder prompt, Session-local Schedule ID, exact UTC occurrence, and the `session-local` delivery boundary. A malformed or incompatible sidecar remains visible as a contained unavailable receipt instead of crashing the conversation. Unloading the plugin removes only the keyed renderer; `ui-conversation` then shows its generic visible JSON fallback for the same durable event.
|
||||
|
||||
## Model Experience
|
||||
|
||||
None, as this browser-only renderer registers no model surface; Schedule tools and reminder framing belong to `@deepseek-ai/dsh-tool-schedule`.
|
||||
|
||||
#### KV Cache effect
|
||||
|
||||
None. The renderer consumes a browser-side presentation sidecar after the durable event is committed.
|
||||
|
||||
## Known Limitations and Deferred Work
|
||||
|
||||
- **Receipt-only UI** — creating, listing, and deleting reminders remains model-driven through the Schedule tools; this package does not add a management page.
|
||||
- **Session-local delivery** — the card records a receipt in the original Session. It does not imply a system, browser, email, or other external notification.
|
||||
@@ -1,20 +0,0 @@
|
||||
# @deepseek-ai/dsh-client-ui-schedule
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
用于渲染持久 Schedule 提醒回执的纯浏览器插件。插件在会话拥有的 `conversation.chat.eventview` slot 中注册持久事件类型 `schedule/change`。通用运行时继续携带持久事件身份与 Host 计算的 JSON sidecar；本包只拥有 Schedule 卡片。
|
||||
|
||||
卡片显示提醒原文、Session 内的 Schedule ID、精确 UTC 发生时刻，以及 `session-local` 交付边界。若 sidecar 损坏或版本不兼容，组件会显示受控的不可用回执，而不会让会话崩溃。卸载插件只会移除该键控 renderer；`ui-conversation` 随后仍会为同一个持久事件显示通用且可见的 JSON fallback。
|
||||
|
||||
## 模型体验
|
||||
|
||||
无，因为这个纯浏览器 renderer 不注册模型 surface；Schedule 工具与提醒 framing 由 `@deepseek-ai/dsh-tool-schedule` 拥有。
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
无。renderer 只在持久事件提交后消费浏览器侧 presentation sidecar。
|
||||
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
- **仅提供回执 UI**：创建、列出和删除提醒仍由模型通过 Schedule 工具完成；本包不增加管理页面。
|
||||
- **仅在 Session 内交付**：卡片记录的是原 Session 中的回执，并不表示系统、浏览器、邮件或其他外部通知。
|
||||
@@ -1,68 +0,0 @@
|
||||
{
|
||||
"name": "@deepseek-ai/dsh-client-ui-schedule",
|
||||
"description": "Web renderer for durable Schedule reminder receipts in the conversation flow",
|
||||
"version": "0.0.1",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"main": "lib/index.js",
|
||||
"types": "lib/types/index.d.ts",
|
||||
"exports": {
|
||||
".": {
|
||||
"types": "./lib/types/index.d.ts",
|
||||
"default": "./lib/index.js"
|
||||
},
|
||||
"./invariant": {
|
||||
"types": "./lib/types/invariant.d.ts",
|
||||
"default": "./lib/invariant.js"
|
||||
},
|
||||
"./client": {
|
||||
"types": "./lib/types/client/index.d.ts",
|
||||
"default": "./lib/client.js"
|
||||
},
|
||||
"./src/*": "./src/*",
|
||||
"./package.json": "./package.json"
|
||||
},
|
||||
"dshClient": {
|
||||
"inject": [
|
||||
"@deepseek-ai/dsh-client-runtime",
|
||||
"@deepseek-ai/dsh-client-locale",
|
||||
"@deepseek-ai/dsh-client-ui-conversation"
|
||||
],
|
||||
"platform": "web"
|
||||
},
|
||||
"scripts": {
|
||||
"bundle": "tsdown",
|
||||
"watch": "tsdown --watch"
|
||||
},
|
||||
"license": "BSD-3-Clause",
|
||||
"peerDependencies": {
|
||||
"@deepseek-ai/dsh-client-locale": "^0.0.1",
|
||||
"@deepseek-ai/dsh-client-runtime": "^0.0.1",
|
||||
"@deepseek-ai/dsh-client-ui-conversation": "^0.0.1",
|
||||
"@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
|
||||
"@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
|
||||
"@deepseek-ai/dsh-invariants": "^0.0.1",
|
||||
"cordis": "^4.0.0-rc.7",
|
||||
"react": "^18.2.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@deepseek-ai/dsh-client-locale": "workspace:^",
|
||||
"@deepseek-ai/dsh-client-runtime": "workspace:^",
|
||||
"@deepseek-ai/dsh-client-test-runtime": "workspace:^",
|
||||
"@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
|
||||
"@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
|
||||
"@deepseek-ai/dsh-client-ui-slots": "workspace:^",
|
||||
"@deepseek-ai/dsh-invariants": "workspace:^",
|
||||
"@testing-library/react": "^16.1.0",
|
||||
"@types/react": "~18.3.1",
|
||||
"cordis": "^4.0.0-rc.7",
|
||||
"react": "^18.2.0",
|
||||
"react-dom": "^18.2.0"
|
||||
},
|
||||
"files": [
|
||||
"lib/index.js",
|
||||
"lib/invariant.js",
|
||||
"lib/client.js",
|
||||
"lib/types/**/*.d.ts"
|
||||
]
|
||||
}
|
||||
@@ -1,63 +0,0 @@
|
||||
.root {
|
||||
display: grid;
|
||||
min-width: 0;
|
||||
gap: 8px;
|
||||
padding: 12px 14px;
|
||||
border: 1px solid var(--dsw-alias-border-l2);
|
||||
border-radius: 10px;
|
||||
background: var(--dsw-alias-bg-module-platform);
|
||||
color: var(--dsw-alias-label-primary);
|
||||
}
|
||||
|
||||
.header {
|
||||
display: flex;
|
||||
min-width: 0;
|
||||
align-items: center;
|
||||
gap: 7px;
|
||||
}
|
||||
|
||||
.icon {
|
||||
display: inline-flex;
|
||||
flex: none;
|
||||
color: var(--dsw-alias-brand-text);
|
||||
}
|
||||
|
||||
.title {
|
||||
min-width: 0;
|
||||
flex: 1;
|
||||
font: 600 13px/18px var(--ds-font-family);
|
||||
}
|
||||
|
||||
.delivery {
|
||||
flex: none;
|
||||
color: var(--dsw-alias-label-tertiary);
|
||||
font: 400 11px/16px var(--ds-font-family);
|
||||
}
|
||||
|
||||
.prompt {
|
||||
margin: 0;
|
||||
color: var(--dsw-alias-label-primary);
|
||||
font: 400 14px/21px var(--ds-font-family);
|
||||
overflow-wrap: anywhere;
|
||||
white-space: pre-wrap;
|
||||
}
|
||||
|
||||
.meta {
|
||||
display: flex;
|
||||
min-width: 0;
|
||||
flex-wrap: wrap;
|
||||
gap: 4px 12px;
|
||||
color: var(--dsw-alias-label-tertiary);
|
||||
font: 400 11px/16px var(--ds-font-family);
|
||||
}
|
||||
|
||||
.id {
|
||||
font-family: var(--ds-font-family-code);
|
||||
overflow-wrap: anywhere;
|
||||
}
|
||||
|
||||
.invalid {
|
||||
margin: 0;
|
||||
color: var(--dsw-alias-label-secondary);
|
||||
font: 400 13px/18px var(--ds-font-family);
|
||||
}
|
||||
@@ -1,58 +0,0 @@
|
||||
import { IconSparkle16 } from '@deepseek-ai/dsh-client-ui-primitives'
|
||||
import type { EventRowProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
|
||||
import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
|
||||
import css from './ReminderRow.module.css'
|
||||
|
||||
interface ReminderPresentation {
|
||||
scheduleId: string
|
||||
prompt: string
|
||||
occurrenceAt: string
|
||||
}
|
||||
|
||||
/** Full Schedule row props: event owner/runtime share plus the locale seat. */
|
||||
export type ReminderRowProps = EventRowProps & PropsLocale<'schedule'>
|
||||
|
||||
/** Narrow the domain-owned JSON sidecar without trusting its unknown carrier type. */
|
||||
function reminderPresentation(value: unknown): ReminderPresentation | null {
|
||||
if (typeof value !== 'object' || value === null || Array.isArray(value)) return null
|
||||
const record = value as Record<string, unknown>
|
||||
if (typeof record['scheduleId'] !== 'string' || record['scheduleId'].length === 0) return null
|
||||
if (typeof record['prompt'] !== 'string') return null
|
||||
if (typeof record['occurrenceAt'] !== 'string' || record['occurrenceAt'].length === 0) return null
|
||||
return {
|
||||
scheduleId: record['scheduleId'],
|
||||
prompt: record['prompt'],
|
||||
occurrenceAt: record['occurrenceAt'],
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Render one durable reminder dispatch carried by the generic event sidecar.
|
||||
* @param props - Keyed event owner payload and the Schedule translator.
|
||||
* @returns A visible reminder receipt, or a contained invalid-payload row.
|
||||
*/
|
||||
export function ReminderRow({ node, t }: ReminderRowProps) {
|
||||
const reminder = reminderPresentation(node.view)
|
||||
return (
|
||||
<section className={css.root} role="note" data-schedule-reminder>
|
||||
<header className={css.header}>
|
||||
<span className={css.icon} aria-hidden><IconSparkle16 size={14} /></span>
|
||||
<span className={css.title}>{t('reminder.title')}</span>
|
||||
{reminder !== null && <span className={css.delivery}>{t('reminder.delivery')}</span>}
|
||||
</header>
|
||||
{reminder === null
|
||||
? <p className={css.invalid}>{t('reminder.invalid')} · {node.eventType}</p>
|
||||
: (
|
||||
<>
|
||||
<p className={css.prompt}>{reminder.prompt}</p>
|
||||
<footer className={css.meta}>
|
||||
<span className={css.id}>{t('reminder.id', { id: reminder.scheduleId })}</span>
|
||||
<time dateTime={reminder.occurrenceAt}>
|
||||
{t('reminder.occurrence', { time: reminder.occurrenceAt })}
|
||||
</time>
|
||||
</footer>
|
||||
</>
|
||||
)}
|
||||
</section>
|
||||
)
|
||||
}
|
||||
@@ -1,34 +0,0 @@
|
||||
/** Register the Schedule durable-reminder renderer into the conversation event slot. */
|
||||
import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
|
||||
// Type-only: pulls the locale plugin's Context merge (ctx.locale).
|
||||
import type {} from '@deepseek-ai/dsh-client-locale/client'
|
||||
import { ReminderRow } from './ReminderRow.tsx'
|
||||
import { en, NS, zh, type ScheduleKey } from './locales.ts'
|
||||
|
||||
export type { ReminderRowProps } from './ReminderRow.tsx'
|
||||
export type { ScheduleKey } from './locales.ts'
|
||||
|
||||
declare module '@deepseek-ai/dsh-client-ui-slots' {
|
||||
interface LocaleNamespaceMap {
|
||||
/** Copy for durable Schedule reminder receipts. */
|
||||
schedule: ScheduleKey
|
||||
}
|
||||
}
|
||||
|
||||
export const inject = ['slots', 'locale']
|
||||
|
||||
/**
|
||||
* Register bilingual copy and the Schedule reminder keyed row.
|
||||
* @param ctx - Client root context.
|
||||
*/
|
||||
export function apply(ctx: ClientContext): void {
|
||||
ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-schedule: dictionaries')
|
||||
ctx.slots.inject(
|
||||
'conversation.chat.eventview',
|
||||
() => ctx.slots.register({
|
||||
name: 'conversation.chat.eventview',
|
||||
key: 'schedule/change',
|
||||
locale: NS,
|
||||
}, ReminderRow),
|
||||
)
|
||||
}
|
||||
@@ -1,25 +0,0 @@
|
||||
/** `schedule` namespace dictionaries. */
|
||||
|
||||
/** Dictionary namespace owned by this plugin. */
|
||||
export const NS = 'schedule'
|
||||
|
||||
/** Simplified Chinese dictionary (the key-set source of truth). */
|
||||
export const zh = {
|
||||
'reminder.title': '定时提醒',
|
||||
'reminder.delivery': '仅在当前会话中交付',
|
||||
'reminder.invalid': '提醒回执不可用',
|
||||
'reminder.id': '编号 {id}',
|
||||
'reminder.occurrence': '触发时间 {time}',
|
||||
} satisfies Record<string, string>
|
||||
|
||||
/** The Schedule namespace key union. */
|
||||
export type ScheduleKey = keyof typeof zh
|
||||
|
||||
/** English dictionary, checked complete against the Chinese key set. */
|
||||
export const en = {
|
||||
'reminder.title': 'Scheduled reminder',
|
||||
'reminder.delivery': 'Delivered in this session only',
|
||||
'reminder.invalid': 'Reminder receipt unavailable',
|
||||
'reminder.id': 'ID {id}',
|
||||
'reminder.occurrence': 'Due at {time}',
|
||||
} satisfies Record<ScheduleKey, string>
|
||||
@@ -1,4 +0,0 @@
|
||||
declare module '*.module.css' {
|
||||
const classes: Readonly<Record<string, string>>
|
||||
export default classes
|
||||
}
|
||||
@@ -1,4 +0,0 @@
|
||||
/** Host loader entry for the browser-only Schedule receipt renderer. */
|
||||
|
||||
/** Provides no host-side behavior. */
|
||||
export function apply(): void {}
|
||||
@@ -1,30 +0,0 @@
|
||||
/**
|
||||
* Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-schedule`.
|
||||
* @module @deepseek-ai/dsh-client-ui-schedule/invariant
|
||||
*/
|
||||
|
||||
/* jscpd:ignore-start */
|
||||
import type { Context } from 'cordis'
|
||||
import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
|
||||
|
||||
const PACKAGE_NAME = '@deepseek-ai/dsh-client-ui-schedule'
|
||||
|
||||
/** Cordis companion plugin name. */
|
||||
export const name = 'client-ui-schedule-invariant'
|
||||
/** Service required before the companion can reserve package ownership. */
|
||||
export const inject = ['invariants']
|
||||
|
||||
/**
|
||||
* No runtime invariant: the keyed slot registry owns contribution lifecycle,
|
||||
* and the component has no state outside its immutable owner payload.
|
||||
*/
|
||||
const install: InvariantInstaller = () => {}
|
||||
|
||||
/**
|
||||
* Register this package's invariant companion.
|
||||
* @param ctx - Cordis context carrying the invariant service.
|
||||
* @returns The installed registration's disposer after setup succeeds.
|
||||
*/
|
||||
export const apply = (ctx: Context): Promise<() => void> =>
|
||||
Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
|
||||
/* jscpd:ignore-end */
|
||||
@@ -1,90 +0,0 @@
|
||||
import { Context } from 'cordis'
|
||||
import { describe, expect, it } from 'vitest'
|
||||
import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
|
||||
import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
|
||||
import { apply, inject } from '../src/client/index.ts'
|
||||
import { ReminderRow } from '../src/client/ReminderRow.tsx'
|
||||
import { apply as nodeApply } from '../src/index.ts'
|
||||
import {
|
||||
apply as invariantApply,
|
||||
inject as invariantInject,
|
||||
name as invariantName,
|
||||
} from '../src/invariant.ts'
|
||||
|
||||
async function bench(declareBeforeApply = true) {
|
||||
const ctx = new Context()
|
||||
await ctx.plugin(SlotsService)
|
||||
const slots = ctx.slots as unknown as {
|
||||
register: (options: object, component: unknown) => () => void
|
||||
}
|
||||
const declareHost = () => slots.register({
|
||||
name: 'root',
|
||||
children: { 'conversation.chat.eventview': { kind: 'keyed', scope: 'session' } },
|
||||
}, () => null)
|
||||
const initialHost = declareBeforeApply ? declareHost() : undefined
|
||||
ctx.provide('locale', new LocaleService(ctx))
|
||||
const fiber = ctx.plugin({ inject: [...inject], apply })
|
||||
await fiber.await()
|
||||
return {
|
||||
ctx,
|
||||
fiber,
|
||||
declareHost,
|
||||
initialHost,
|
||||
entry: () => ctx.slots.entries('conversation.chat.eventview')[0],
|
||||
}
|
||||
}
|
||||
|
||||
describe('ui-schedule browser plugin', () => {
|
||||
it('registers the keyed reminder renderer and unloads it with the fiber', async () => {
|
||||
const b = await bench()
|
||||
expect(b.entry()?.options).toEqual({ key: 'schedule/change' })
|
||||
expect(b.entry()?.locale).toBe('schedule')
|
||||
expect(b.entry()?.component).toBe(ReminderRow)
|
||||
|
||||
await b.fiber.dispose()
|
||||
expect(b.entry()).toBeUndefined()
|
||||
b.initialHost?.()
|
||||
})
|
||||
|
||||
it('follows delayed declaration, collapse, and redeclaration until contributor disposal', async () => {
|
||||
const b = await bench(false)
|
||||
expect(b.entry()).toBeUndefined()
|
||||
|
||||
const firstHost = b.declareHost()
|
||||
expect(b.entry()?.component).toBe(ReminderRow)
|
||||
firstHost()
|
||||
expect(b.entry()).toBeUndefined()
|
||||
|
||||
const secondHost = b.declareHost()
|
||||
expect(b.entry()?.component).toBe(ReminderRow)
|
||||
await b.fiber.dispose()
|
||||
expect(b.entry()).toBeUndefined()
|
||||
secondHost()
|
||||
})
|
||||
})
|
||||
|
||||
describe('ui-schedule node and invariant companions', () => {
|
||||
it('keeps the node half inert', () => {
|
||||
expect(() => { nodeApply() }).not.toThrow()
|
||||
})
|
||||
|
||||
it('registers exact package ownership and returns its disposer', async () => {
|
||||
const ctx = new Context()
|
||||
let owner: string | undefined
|
||||
let disposed = false
|
||||
ctx.provide('invariants', {
|
||||
register(packageName: string, install: unknown) {
|
||||
expect(install).toBeTypeOf('function')
|
||||
owner = packageName
|
||||
return () => { disposed = true }
|
||||
},
|
||||
})
|
||||
|
||||
expect(invariantName).toBe('client-ui-schedule-invariant')
|
||||
expect(invariantInject).toEqual(['invariants'])
|
||||
const dispose = await invariantApply(ctx)
|
||||
expect(owner).toBe('@deepseek-ai/dsh-client-ui-schedule')
|
||||
dispose()
|
||||
expect(disposed).toBe(true)
|
||||
})
|
||||
})
|
||||
@@ -1,95 +0,0 @@
|
||||
// @vitest-environment jsdom
|
||||
|
||||
import { cleanup, render, screen } from '@testing-library/react'
|
||||
import { afterEach, describe, expect, it } from 'vitest'
|
||||
import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
|
||||
import type { PresentedEventNode } from '@deepseek-ai/dsh-client-runtime/client'
|
||||
import { ReminderRow, type ReminderRowProps } from '../src/client/ReminderRow.tsx'
|
||||
import { zh } from '../src/client/locales.ts'
|
||||
|
||||
const t: ReminderRowProps['t'] = makeTranslate(zh)
|
||||
|
||||
const invalidSidecars: ReadonlyArray<{ name: string; view: unknown }> = [
|
||||
{ name: 'non-object', view: undefined },
|
||||
{ name: 'null', view: null },
|
||||
{ name: 'array', view: [] },
|
||||
{
|
||||
name: 'missing schedule id',
|
||||
view: {
|
||||
scheduleId: null,
|
||||
prompt: 'not trusted',
|
||||
occurrenceAt: '2026-08-05T08:00:00.000Z',
|
||||
},
|
||||
},
|
||||
{
|
||||
name: 'empty schedule id',
|
||||
view: {
|
||||
scheduleId: '',
|
||||
prompt: 'not trusted',
|
||||
occurrenceAt: '2026-08-05T08:00:00.000Z',
|
||||
},
|
||||
},
|
||||
{
|
||||
name: 'non-string prompt',
|
||||
view: {
|
||||
scheduleId: 'schedule-7',
|
||||
prompt: 7,
|
||||
occurrenceAt: '2026-08-05T08:00:00.000Z',
|
||||
},
|
||||
},
|
||||
{
|
||||
name: 'non-string occurrence',
|
||||
view: {
|
||||
scheduleId: 'schedule-7',
|
||||
prompt: 'not trusted',
|
||||
occurrenceAt: 7,
|
||||
},
|
||||
},
|
||||
{
|
||||
name: 'empty occurrence',
|
||||
view: {
|
||||
scheduleId: 'schedule-7',
|
||||
prompt: 'not trusted',
|
||||
occurrenceAt: '',
|
||||
},
|
||||
},
|
||||
]
|
||||
|
||||
afterEach(cleanup)
|
||||
|
||||
function props(view: unknown): ReminderRowProps {
|
||||
const node: PresentedEventNode = {
|
||||
kind: 'presented-event',
|
||||
seq: 4,
|
||||
time: Date.parse('2026-08-05T08:00:00.000Z'),
|
||||
eventType: 'schedule/change',
|
||||
view,
|
||||
}
|
||||
return { node, t } as ReminderRowProps
|
||||
}
|
||||
|
||||
describe('ReminderRow', () => {
|
||||
it('shows the durable reminder payload and its session-local boundary', () => {
|
||||
render(<ReminderRow {...props({
|
||||
scheduleId: 'schedule-7',
|
||||
prompt: 'Check the deploy',
|
||||
occurrenceAt: '2026-08-05T08:00:00.000Z',
|
||||
})} />)
|
||||
|
||||
expect(screen.getByRole('note')).toBeTruthy()
|
||||
expect(screen.getByText('定时提醒')).toBeTruthy()
|
||||
expect(screen.getByText('仅在当前会话中交付')).toBeTruthy()
|
||||
expect(screen.getByText('Check the deploy')).toBeTruthy()
|
||||
expect(screen.getByText('编号 schedule-7')).toBeTruthy()
|
||||
const time = screen.getByText('触发时间 2026-08-05T08:00:00.000Z')
|
||||
expect(time.getAttribute('datetime')).toBe('2026-08-05T08:00:00.000Z')
|
||||
})
|
||||
|
||||
it.each(invalidSidecars)('contains an incompatible $name sidecar as an unavailable receipt', ({ view }) => {
|
||||
render(<ReminderRow {...props(view)} />)
|
||||
|
||||
expect(screen.getByText('提醒回执不可用 · schedule/change')).toBeTruthy()
|
||||
expect(screen.queryByText('not trusted')).toBeNull()
|
||||
expect(screen.queryByText('仅在当前会话中交付')).toBeNull()
|
||||
})
|
||||
})
|
||||
@@ -1,33 +0,0 @@
|
||||
{
|
||||
"extends": "../../../tsconfig.base.client.json",
|
||||
"compilerOptions": {
|
||||
"rootDir": "src",
|
||||
"outDir": "lib/types"
|
||||
},
|
||||
"include": [
|
||||
"src"
|
||||
],
|
||||
"references": [
|
||||
{
|
||||
"path": "../../../vendor/cordis"
|
||||
},
|
||||
{
|
||||
"path": "../locale"
|
||||
},
|
||||
{
|
||||
"path": "../runtime"
|
||||
},
|
||||
{
|
||||
"path": "../ui-conversation"
|
||||
},
|
||||
{
|
||||
"path": "../ui-primitives"
|
||||
},
|
||||
{
|
||||
"path": "../ui-slots"
|
||||
},
|
||||
{
|
||||
"path": "../../support/invariants"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -1,3 +0,0 @@
|
||||
import { clientBundle } from '../tsdown.client.ts'
|
||||
|
||||
export default clientBundle('@deepseek-ai/dsh-client-ui-schedule', ['lib/types/index.js', 'lib/types/invariant.js'])
|
||||
@@ -26,7 +26,6 @@ const scopedSubjectResolvers: Readonly<Record<string, ScopedSubjectResolver | nu
|
||||
'session/disposed': null,
|
||||
'session/event': null,
|
||||
'session/flush': null,
|
||||
'session/flushed': null,
|
||||
'subagent/end': null,
|
||||
'subagent/start': null,
|
||||
'system-prompt/assemble': args => (args[1] as Record<string, unknown>)['scope'],
|
||||
|
||||
@@ -12,9 +12,8 @@ Creates and holds event-sourced `Session` instances. Persistence is intentionall
|
||||
|
||||
### Public API
|
||||
|
||||
- `ctx.sessions.create(id?, { seed?, meta? }?)` validates and detaches durable seed/header data, fills the version and id, defaults `createdAt` to now, publishes the session, and binds it to the calling fiber. Persisted reconstruction supplies its original `createdAt`, `seedLength`, `origin`, and `delegationDepth`.
|
||||
- `ctx.sessions.flush(session)` dispatches an awaited parallel checkpoint through the session's captured scope. Every listener starts and the call waits for all to settle before reporting failure; observe-only listeners return void, while a persistence listener returns literal `true` only after completing durability work. A fully successful checkpoint with at least one such acknowledgement returns `true` and emits contained `session/flushed(session, throughSeq)` with the exclusive event boundary captured at entry; no durability acknowledgement returns `false`, and unpublished, detached, or stale objects reject. A caller that requires durable storage rejects `false` at its own policy boundary.
|
||||
- `findLastMessageTurnEnd(events)` pairs message-triggered starts with their ends and returns the latest matched `turn/end`. Outcome consumers use this fold instead of the raw latest log event because between-turn records and non-message turns have no prompt outcome.
|
||||
- `ctx.sessions.create(id?, { seed?, meta? }?)` validates and detaches durable seed/header data, fills the version and id, defaults `createdAt` to now, publishes the session, and binds it to the calling fiber. Persisted reconstruction supplies its original `createdAt`, `seedLength`, and `delegationDepth`.
|
||||
- `ctx.sessions.flush(session)` dispatches the awaited parallel durability checkpoint through the session's captured scope. Every listener starts and the call waits for all to settle before reporting failure; unpublished, detached, and stale objects reject.
|
||||
- `ctx.sessions.fork(source, boundary?, childSessionId?): Session` — Resolve a live session object or id, select a seed through the inclusive `boundary` event seq (default: current last event), require that prefix to end outside an open turn, and create a live child session with lineage metadata.
|
||||
- `ctx.sessions.get(id: SessionId): Session | undefined`
|
||||
- `ctx.sessions.list(): Session[]`
|
||||
|
||||
@@ -12,9 +12,8 @@
|
||||
|
||||
### 公共 API
|
||||
|
||||
- `ctx.sessions.create(id?, { seed?, meta? }?)` 校验持久种子／头部数据并生成脱离副本，补齐版本和 id，在未提供 `createdAt` 时使用当前时间，发布会话并将其绑定到调用方 fiber。持久化重建会提供原始的 `createdAt`、`seedLength`、`origin` 和 `delegationDepth`。
|
||||
- `ctx.sessions.flush(session)` 通过会话捕获的作用域分发受等待的并行检查点。每个监听器都会启动，调用会等待全部结算后才报告失败；仅观察的监听器返回 void，持久化监听器只有在完成持久化工作后才返回字面量 `true`。全部成功且至少有一个此类确认时，调用返回 `true`，并发布受包含的 `session/flushed(session, throughSeq)`，其中 `throughSeq` 是入口处捕获的事件排他边界；没有持久化确认时返回 `false`，未发布、已脱离或陈旧对象会被拒绝。要求持久化存储的调用方应在自己的策略边界拒绝 `false`。
|
||||
- `findLastMessageTurnEnd(events)` 将由消息触发的开始与结束配对，并返回最近匹配的 `turn/end`。结果消费方使用该折叠逻辑，而不直接取日志中最近的事件，因为轮次间记录和非消息轮次没有提示词结果。
|
||||
- `ctx.sessions.create(id?, { seed?, meta? }?)` 校验持久种子／头部数据并生成脱离副本，补齐版本和 id，在未提供 `createdAt` 时使用当前时间，发布会话并将其绑定到调用方 fiber。持久化重建会提供原始的 `createdAt`、`seedLength` 和 `delegationDepth`。
|
||||
- `ctx.sessions.flush(session)` 通过会话捕获的作用域分发受等待的并行持久性检查点。每个监听器都会启动；调用会等待全部结算后才报告失败。未发布、已脱离和陈旧的对象会被拒绝。
|
||||
- `ctx.sessions.fork(source, boundary?, childSessionId?): Session`：解析实时会话对象或 id，选取截至 `boundary` 事件序号（含该事件）的种子（默认为当前最后一个事件），要求所选前缀结束时没有开放轮次，再创建带谱系元数据的实时子会话。
|
||||
- `ctx.sessions.get(id: SessionId): Session | undefined`
|
||||
- `ctx.sessions.list(): Session[]`
|
||||
|
||||
@@ -95,32 +95,14 @@ declare module 'cordis' {
|
||||
*/
|
||||
'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
|
||||
/**
|
||||
* Awaited parallel checkpoint: every listener runs and the caller awaits
|
||||
* all of them, with no waterfall veto. A listener returns literal `true`
|
||||
* only after completing durability work; observe-only listeners return
|
||||
* void. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the
|
||||
* session's owner scope.
|
||||
* Awaited parallel durability checkpoint: every listener runs and the
|
||||
* caller awaits all of them, with no waterfall veto. Scope-filtered dispatch
|
||||
* (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
|
||||
* @param session - the session whose buffered events must reach durable storage.
|
||||
* @dshScopeScan unsupported
|
||||
* @mode parallel
|
||||
*/
|
||||
'session/flush'(this: Scoped<Session>, session: Session): Promise<true | void> | true | void
|
||||
/**
|
||||
* Observe a successful durability checkpoint. `throughSeq` is the exclusive
|
||||
* event boundary captured when {@link SessionStore.flush} began; events
|
||||
* appended while its listeners run require a later successful checkpoint.
|
||||
* Concurrent checkpoints may publish their boundaries out of order, so a
|
||||
* consumer retaining progress must advance by the maximum observed value.
|
||||
* No notification is published when no durability listener participated or
|
||||
* any listener failed. Observer failures are logged and contained.
|
||||
* Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the session's
|
||||
* owner scope.
|
||||
* @param session - the session whose prefix completed the checkpoint.
|
||||
* @param throughSeq - exclusive event sequence boundary proven by the checkpoint.
|
||||
* @dshScopeScan unsupported
|
||||
* @mode emit
|
||||
*/
|
||||
'session/flushed'(this: Scoped<Session>, session: Session, throughSeq: number): void
|
||||
'session/flush'(this: Scoped<Session>, session: Session): Promise<void> | void
|
||||
}
|
||||
}
|
||||
|
||||
@@ -406,16 +388,6 @@ function assertSupportedRequestHeader(type: string, data: unknown, location: str
|
||||
|
||||
type SessionCallback = (...args: unknown[]) => unknown
|
||||
|
||||
/** Render any thrown observer value without violating callback containment. */
|
||||
function renderSessionObserverError(error: unknown): string {
|
||||
try {
|
||||
return String(error)
|
||||
} catch {
|
||||
// String coercion itself may throw.
|
||||
return '[unrenderable thrown value]'
|
||||
}
|
||||
}
|
||||
|
||||
/** Resolve one listener snapshot, including Cordis's internal dispatch checks. */
|
||||
function collectSessionCallbacks(ctx: Context, args: unknown[]): SessionCallback[] {
|
||||
return [...ctx.events.dispatch('emit', args)] as SessionCallback[]
|
||||
@@ -424,7 +396,7 @@ function collectSessionCallbacks(ctx: Context, args: unknown[]): SessionCallback
|
||||
/** Invoke one resolved observe-only listener snapshot with per-listener containment. */
|
||||
function invokeContainedSessionObservers(
|
||||
ctx: Context,
|
||||
name: 'session/event' | 'session/disposed' | 'session/flushed',
|
||||
name: 'session/event' | 'session/disposed',
|
||||
id: SessionId,
|
||||
args: unknown[],
|
||||
callbacks: SessionCallback[],
|
||||
@@ -433,10 +405,10 @@ function invokeContainedSessionObservers(
|
||||
try {
|
||||
const returned: unknown = callback(...args)
|
||||
void Promise.resolve(returned).catch((error: unknown) => {
|
||||
ctx.logger.warn(`session "${id}": ${name} listener rejected: ${renderSessionObserverError(error)}`)
|
||||
ctx.logger.warn(`session "${id}": ${name} listener rejected: ${String(error)}`)
|
||||
})
|
||||
} catch (error: unknown) {
|
||||
ctx.logger.warn(`session "${id}": ${name} listener threw: ${renderSessionObserverError(error)}`)
|
||||
ctx.logger.warn(`session "${id}": ${name} listener threw: ${String(error)}`)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1028,7 +1000,7 @@ export class SessionStore extends Service {
|
||||
// of becoming unhandled.
|
||||
const returned: unknown = callback(...callbackArgs)
|
||||
void Promise.resolve(returned).catch((error: unknown) => {
|
||||
this.ctx.logger.warn(`session "${entry.id}": session/created listener rejected: ${renderSessionObserverError(error)}`)
|
||||
this.ctx.logger.warn(`session "${entry.id}": session/created listener rejected: ${String(error)}`)
|
||||
})
|
||||
}
|
||||
} finally {
|
||||
@@ -1044,7 +1016,7 @@ export class SessionStore extends Service {
|
||||
const callbacks = collectSessionCallbacks(this.ctx, [entry.carrier, 'session/disposed', entry.session])
|
||||
invokeContainedSessionObservers(this.ctx, 'session/disposed', entry.id, callbackArgs, callbacks)
|
||||
} catch (error: unknown) {
|
||||
this.ctx.logger.warn(`session "${entry.id}": session/disposed dispatch threw: ${renderSessionObserverError(error)}`)
|
||||
this.ctx.logger.warn(`session "${entry.id}": session/disposed dispatch threw: ${String(error)}`)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1057,13 +1029,12 @@ export class SessionStore extends Service {
|
||||
* rather than dispatch a raw `ctx.parallel('session/flush', …)` — one owner,
|
||||
* one spelling, and the scoped-dispatch invariant can pin it.
|
||||
* @param session - the session whose buffered events must reach durable storage.
|
||||
* @returns whether at least one listener acknowledged completed durability,
|
||||
* after every listener has settled successfully.
|
||||
* @returns whether at least one durability listener participated, after every
|
||||
* listener has settled successfully.
|
||||
* @throws the first registered listener failure after every listener settles.
|
||||
*/
|
||||
async flush(session: Session): Promise<boolean> {
|
||||
const { carrier } = this.liveEntryFor(session)
|
||||
const throughSeq = session.seq
|
||||
const callbackArgs: unknown[] = [session]
|
||||
const callbacks = collectSessionCallbacks(this.ctx, [carrier, 'session/flush', session])
|
||||
const results = await Promise.allSettled(callbacks.map((callback) => {
|
||||
@@ -1078,27 +1049,7 @@ export class SessionStore extends Service {
|
||||
}))
|
||||
const failure = results.find((result): result is PromiseRejectedResult => result.status === 'rejected')
|
||||
if (failure !== undefined) throw failure.reason
|
||||
const durable = results.some(result => result.status === 'fulfilled' && result.value === true)
|
||||
if (durable) {
|
||||
const flushedArgs: unknown[] = [session, throughSeq]
|
||||
try {
|
||||
const observers = collectSessionCallbacks(this.ctx, [
|
||||
carrier,
|
||||
'session/flushed',
|
||||
...flushedArgs,
|
||||
])
|
||||
invokeContainedSessionObservers(
|
||||
this.ctx,
|
||||
'session/flushed',
|
||||
session.id,
|
||||
flushedArgs,
|
||||
observers,
|
||||
)
|
||||
} catch (error: unknown) {
|
||||
this.ctx.logger.warn(`session "${session.id}": session/flushed dispatch threw: ${renderSessionObserverError(error)}`)
|
||||
}
|
||||
}
|
||||
return durable
|
||||
return callbacks.length > 0
|
||||
}
|
||||
|
||||
/** Return the exact live entry; detached/prepared objects reject. */
|
||||
|
||||
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
|
||||
import { Context } from 'cordis'
|
||||
import { createScope, scopeOf } from '@deepseek-ai/dsh-scope'
|
||||
import type { Scope, ScopeKey } from '@deepseek-ai/dsh-scope'
|
||||
import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
|
||||
import SessionStore from '@deepseek-ai/dsh-session'
|
||||
import type { Session } from '@deepseek-ai/dsh-session'
|
||||
|
||||
async function mount(): Promise<Context> {
|
||||
@@ -83,41 +83,19 @@ describe('sessions.flush()', () => {
|
||||
it('allows an ordinary flush with no listeners', async () => {
|
||||
const ctx = await mount()
|
||||
const session = ctx.sessions.create()
|
||||
const flushed: number[] = []
|
||||
ctx.on('session/flushed', (_current, throughSeq) => { flushed.push(throughSeq) })
|
||||
|
||||
await expect(ctx.sessions.flush(session)).resolves.toBe(false)
|
||||
expect(flushed).toEqual([])
|
||||
})
|
||||
|
||||
it('reports a durability listener after it acknowledges success', async () => {
|
||||
it('reports a participating listener after it succeeds', async () => {
|
||||
const ctx = await mount()
|
||||
const session = ctx.sessions.create()
|
||||
const flushed: Session[] = []
|
||||
const checkpoints: number[] = []
|
||||
ctx.on('session/flush', (current) => {
|
||||
flushed.push(current)
|
||||
return true as const
|
||||
})
|
||||
ctx.on('session/flushed', (_current, throughSeq) => { checkpoints.push(throughSeq) })
|
||||
ctx.on('session/flush', current => void flushed.push(current))
|
||||
|
||||
await expect(ctx.sessions.flush(session)).resolves.toBe(true)
|
||||
|
||||
expect(flushed).toEqual([session])
|
||||
expect(checkpoints).toEqual([0])
|
||||
})
|
||||
|
||||
it('does not treat an observe-only flush listener as durability', async () => {
|
||||
const ctx = await mount()
|
||||
const session = ctx.sessions.create()
|
||||
const observed: Session[] = []
|
||||
const checkpoints: number[] = []
|
||||
ctx.on('session/flush', current => void observed.push(current))
|
||||
ctx.on('session/flushed', (_current, throughSeq) => { checkpoints.push(throughSeq) })
|
||||
|
||||
await expect(ctx.sessions.flush(session)).resolves.toBe(false)
|
||||
expect(observed).toEqual([session])
|
||||
expect(checkpoints).toEqual([])
|
||||
})
|
||||
|
||||
it('dispatches session/flush with the owning carrier and awaits all listeners', async () => {
|
||||
@@ -143,13 +121,9 @@ describe('sessions.flush()', () => {
|
||||
|
||||
it('propagates a rejecting flush listener (the caller owns the failure policy)', async () => {
|
||||
const ctx = await mount()
|
||||
const checkpoints: number[] = []
|
||||
ctx.on('session/flush', () => Promise.reject(new Error('disk full')))
|
||||
ctx.on('session/flush', () => true)
|
||||
ctx.on('session/flushed', (_session, throughSeq) => { checkpoints.push(throughSeq) })
|
||||
const session = ctx.sessions.create()
|
||||
await expect(ctx.sessions.flush(session)).rejects.toThrow('disk full')
|
||||
expect(checkpoints).toEqual([])
|
||||
})
|
||||
|
||||
it('does not let a synchronous flush failure starve later listeners', async () => {
|
||||
@@ -186,86 +160,6 @@ describe('sessions.flush()', () => {
|
||||
expect(settled).toBe(true)
|
||||
})
|
||||
|
||||
it('publishes the entry prefix while a concurrent suffix waits for a later checkpoint', async () => {
|
||||
const ctx = await mount()
|
||||
const gate = Promise.withResolvers<undefined>()
|
||||
let attempts = 0
|
||||
ctx.on('session/flush', async () => {
|
||||
attempts += 1
|
||||
if (attempts === 1) await gate.promise
|
||||
return true as const
|
||||
})
|
||||
const checkpoints: number[] = []
|
||||
ctx.on('session/flushed', (_session, throughSeq) => { checkpoints.push(throughSeq) })
|
||||
const session = ctx.sessions.create()
|
||||
session.append('turn/start', { turn: 1 })
|
||||
|
||||
const first = ctx.sessions.flush(session)
|
||||
session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
|
||||
gate.resolve(undefined)
|
||||
await first
|
||||
await ctx.sessions.flush(session)
|
||||
|
||||
expect(checkpoints).toEqual([1, 2])
|
||||
})
|
||||
|
||||
it('contains successful-checkpoint observers without reversing the barrier', async () => {
|
||||
const ctx = await mount()
|
||||
const checkpoints: number[] = []
|
||||
ctx.on('session/flush', () => true)
|
||||
ctx.on('session/flushed', () => { throw new Error('observer failed') })
|
||||
ctx.on('session/flushed', (_session, throughSeq) => { checkpoints.push(throughSeq) })
|
||||
const session = ctx.sessions.create()
|
||||
|
||||
await expect(ctx.sessions.flush(session)).resolves.toBe(true)
|
||||
expect(checkpoints).toEqual([0])
|
||||
})
|
||||
|
||||
it('contains successful-checkpoint dispatch resolution failure without reversing the barrier', async () => {
|
||||
const ctx = await mount()
|
||||
const warnings: string[] = []
|
||||
ctx.logger.warn = ((message: unknown) => { warnings.push(String(message)) }) as typeof ctx.logger.warn
|
||||
const checkpoints: number[] = []
|
||||
ctx.on('session/flush', () => true)
|
||||
ctx.on('internal/dispatch', (_mode, name) => {
|
||||
if (name === 'session/flushed') throw Object.create(null)
|
||||
})
|
||||
ctx.on('session/flushed', (_session, throughSeq) => { checkpoints.push(throughSeq) })
|
||||
const session = ctx.sessions.create(SessionId('flushed-dispatch'))
|
||||
|
||||
await expect(ctx.sessions.flush(session)).resolves.toBe(true)
|
||||
expect(checkpoints).toEqual([])
|
||||
expect(warnings).toEqual([
|
||||
'session "flushed-dispatch": session/flushed dispatch threw: [unrenderable thrown value]',
|
||||
])
|
||||
})
|
||||
|
||||
it('may publish overlapping checkpoints out of order without widening either boundary', async () => {
|
||||
const ctx = await mount()
|
||||
const firstGate = Promise.withResolvers<undefined>()
|
||||
const secondGate = Promise.withResolvers<undefined>()
|
||||
const gates = [firstGate, secondGate]
|
||||
ctx.on('session/flush', async () => {
|
||||
const gate = gates.shift()
|
||||
if (gate === undefined) throw new Error('unexpected checkpoint attempt')
|
||||
await gate.promise
|
||||
return true as const
|
||||
})
|
||||
const checkpoints: number[] = []
|
||||
ctx.on('session/flushed', (_session, throughSeq) => { checkpoints.push(throughSeq) })
|
||||
const session = ctx.sessions.create()
|
||||
|
||||
const first = ctx.sessions.flush(session)
|
||||
session.append('turn/start', { turn: 1 })
|
||||
const second = ctx.sessions.flush(session)
|
||||
secondGate.resolve(undefined)
|
||||
await second
|
||||
firstGate.resolve(undefined)
|
||||
await first
|
||||
|
||||
expect(checkpoints).toEqual([1, 0])
|
||||
})
|
||||
|
||||
it('rejects a never-entered session instead of inventing a carrier', async () => {
|
||||
const ctx = await mount()
|
||||
const scope = await mintScope(ctx, 'owner')
|
||||
|
||||
@@ -26,8 +26,6 @@ Question responses are validated against their pending request before the first
|
||||
|
||||
`session.history` reads an attached Session in memory or inspects a cold log through persistence without resuming or publishing an Agent, then pages on append-origin message boundaries. `maxMessages` counts `user/message` and `assistant/message` events that entered the surface by appending, so a model-only replacement copy consumes no quota. Each page stays one contiguous raw event range, which keeps a compaction's log-only `compact/summary` record on the same page as the replacement that cites it.
|
||||
|
||||
An optional `SessionEventView` is a non-persistent presentation sidecar. Tool calls/results keep their existing Host presenters. A Schedule dispatch remains raw on append; after an acknowledged `session/flushed(session, throughSeq)`, the gateway advances an exact-Session `WeakMap` cursor with `max`, derives newly covered receipts through the Schedule package, and redelivers the identical event with `{ for: 'event', view }`. The durable event type selects the client renderer. Reversed flush completion cannot move the cursor backward or duplicate a receipt. Attached history adds these views only within a persistence-inspected prefix whose header and every event match the live identity; unavailable, failed, or mismatched inspection serves raw history without the sidecar. Detached history is already a persisted prefix.
|
||||
|
||||
`session.history`'s tail page (`beforeSeq` absent) additionally carries an optional `projections` block — the watermark snapshot of every unit registered on `ctx.sessionProjections` (`@deepseek-ai/dsh-session-projection`), with `asOfSeq` = the last event seq the values reflect (`-1` on an empty log). The gateway also subscribes to the registry's change feed and mints a `session/projection` mux frame per changed unit (`{sessionId, key, value, seq}` — live push state, never logged; clients hold one generic per-session value store under higher-seq-wins). The carrier holds zero domain knowledge (each value passed its unit's own schema inside the registry; the wire schemas keep `values`/`value` wide); loadOlder pages never carry the block, and a composition without the registry serves histories without either surface.
|
||||
|
||||
Session titles ride the generic projection pair like every other domain — the history-tail `projections` block plus `session/projection` frames under the `title` key (the bespoke `session/title` frame is retired). Titles do not join `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs. `session.rename` accepts an explicit user title (resuming a cold session first), delegating to `ctx.sessionTitle.rename` — the accepted `session/title` event pins the title against automatic regeneration — and returns the normalized title plus its event seq so a client settles its `title` projection cell ahead of the push frame; a title that normalizes to empty returns `title-invalid`.
|
||||
|
||||
@@ -26,9 +26,7 @@ Settings 分节中的 `reasoningEffort` 在 agent-default-model 插件配置中
|
||||
|
||||
`session.history` 会读取已附加 Session 的内存状态，或通过持久化检查冷日志，而不会恢复或发布 agent，然后按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message` 和 `assistant/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志 `compact/summary` 记录与引用它的替换留在同一页。
|
||||
|
||||
可选的 `SessionEventView` 是非持久 presentation sidecar。工具 call／result 保留既有 Host presenter。Schedule dispatch 在 append 时保持 raw；收到获确认的 `session/flushed(session, throughSeq)` 后，网关才以 `max` 推进按 exact Session 键控的 `WeakMap` cursor，通过 Schedule package 派生新覆盖的回执，并用 `{ for: 'event', view }` 重投完全相同的事件。持久事件类型选择客户端 renderer。反序完成的 flush 不能让 cursor 后退或重复回执。已附加 history 只会在 persistence inspect 得到的前缀内添加这些 view，而且该前缀的 header 与每个 event 都必须和 live identity 一致；inspect 不可用、失败或不匹配时，仍会返回 raw history，只省略 sidecar。已分离 history 本身已经是持久前缀。
|
||||
|
||||
`session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元铸造一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。
|
||||
`session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元生成一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。
|
||||
|
||||
会话标题与其他所有领域一样搭乘这对通用投影机制——历史尾页的 `projections` 块外加 `title` 键下的 `session/projection` 帧（专设的 `session/title` 帧已下线）。标题不会加入 `session.list`；冷会话在其中仍只有元数据，直到打开或恢复操作附加其日志。`session.rename` 接受用户显式标题（冷会话先恢复），委托给 `ctx.sessionTitle.rename`——被接受的 `session/title` 事件将标题钉住、不再被自动生成覆盖——并返回规范化后的标题及其事件 seq，让 client 在推送帧到达前就结算自己的 `title` 投影格；规范化后为空的标题返回 `title-invalid`。
|
||||
|
||||
|
||||
@@ -55,7 +55,6 @@
|
||||
"@deepseek-ai/dsh-session-query": "workspace:^",
|
||||
"@deepseek-ai/dsh-session-title": "workspace:^",
|
||||
"@deepseek-ai/dsh-settings": "workspace:^",
|
||||
"@deepseek-ai/dsh-tool-schedule": "workspace:^",
|
||||
"@deepseek-ai/dsh-skill": "workspace:^",
|
||||
"@deepseek-ai/dsh-subagent": "workspace:^",
|
||||
"@deepseek-ai/dsh-tools": "workspace:^",
|
||||
|
||||
@@ -6,7 +6,6 @@
|
||||
import { randomUUID } from 'node:crypto'
|
||||
import { mkdir, stat } from 'node:fs/promises'
|
||||
import { join } from 'node:path'
|
||||
import { isDeepStrictEqual } from 'node:util'
|
||||
import type { Context } from 'cordis'
|
||||
import { installModelSelection } from '@deepseek-ai/dsh-agent'
|
||||
import type { Agent, ModelSelection, ModelSelectionRef, AgentOptions, AgentStatus } from '@deepseek-ai/dsh-agent'
|
||||
@@ -31,9 +30,8 @@ import type {} from '@deepseek-ai/dsh-tools'
|
||||
import type {
|
||||
ApiProxy, ConfigurableProviderView, CredentialView, GoalRef, HistoryEntry, HostFrame,
|
||||
ModelCatalogFailure, ModelProviderGroup,
|
||||
ModelReasoning, MuxFrame, PresentedEventView, QuestionResponsePayload, SessionEventView,
|
||||
QueuedInboxItem, SessionProjectionsBlock, SessionSearchItem, SessionSummary, SettingsNamespaceView,
|
||||
SubagentAddress, ToolEventView,
|
||||
ModelReasoning, MuxFrame, QuestionResponsePayload, SessionProjectionsBlock, SessionSearchItem,
|
||||
QueuedInboxItem, SessionSummary, SettingsNamespaceView, SubagentAddress, ToolEventView,
|
||||
WorkspaceId, WorkspaceView,
|
||||
} from './api/index.ts'
|
||||
import {
|
||||
@@ -60,7 +58,6 @@ import { credentialRef } from '@deepseek-ai/dsh-credentials'
|
||||
// Value edge: the rename impl narrows the title service's validation failure; the import also resolves `ctx.get('sessionTitle')`.
|
||||
import { SessionTitleInvalidError } from '@deepseek-ai/dsh-session-title'
|
||||
import type { CallId } from '@deepseek-ai/dsh-llm/brand'
|
||||
import { scheduleReminderPresentation } from '@deepseek-ai/dsh-tool-schedule'
|
||||
import type { ApprovalOutcome, ApprovalRequestId } from '@deepseek-ai/dsh-user-approval'
|
||||
// Side-effect type import: resolves the `approval/request` waterfall and
|
||||
// `ctx.get('approval')` without a value dependency on the seam (optional composition).
|
||||
@@ -468,28 +465,6 @@ function viewFor(ctx: Context, event: SessionEvent, argsFor: (callId: string) =>
|
||||
return undefined
|
||||
}
|
||||
|
||||
/**
|
||||
* Derive one Schedule-owned event sidecar without allowing corrupt domain data
|
||||
* to break raw event delivery. `seedLength` keeps a child-owned dispatch inside
|
||||
* its own suffix while the package helper pairs inherited receipts by id.
|
||||
*/
|
||||
function scheduleViewFor(
|
||||
ctx: Context,
|
||||
header: SessionHeader,
|
||||
events: readonly SessionEvent[],
|
||||
event: SessionEvent,
|
||||
): PresentedEventView | undefined {
|
||||
try {
|
||||
const view = scheduleReminderPresentation(events, event.seq, header.seedLength ?? 0)
|
||||
return view === undefined
|
||||
? undefined
|
||||
: { for: 'event', view }
|
||||
} catch (error: unknown) {
|
||||
ctx.logger.warn(`api-proxy: Schedule presentation failed at seq ${event.seq}; serving raw event: ${String(error)}`)
|
||||
return undefined
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve a tool/result's call pairing by scanning a window of events backwards
|
||||
* for the matching tool/call. Used by the history path (the page is the
|
||||
@@ -518,49 +493,17 @@ function historyPage(
|
||||
events: readonly SessionEvent[],
|
||||
beforeSeq: number | undefined,
|
||||
maxMessages: number | undefined,
|
||||
presentation?: { header: SessionHeader; throughSeq: number },
|
||||
): { events: HistoryEntry[]; hasMore: boolean } {
|
||||
const page = paginate(events, beforeSeq, maxMessages ?? DEFAULT_MAX_MESSAGES)
|
||||
return {
|
||||
events: page.events.map((event) => {
|
||||
const toolView = viewFor(ctx, event, callId => backscanArgs(page.events, callId))
|
||||
const eventView = presentation !== undefined && event.seq < presentation.throughSeq
|
||||
? scheduleViewFor(ctx, presentation.header, events, event)
|
||||
: undefined
|
||||
const view: SessionEventView | undefined = toolView ?? eventView
|
||||
const view = viewFor(ctx, event, callId => backscanArgs(page.events, callId))
|
||||
return { event, ...view === undefined ? {} : { view } }
|
||||
}),
|
||||
hasMore: page.hasMore,
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Prove the exclusive durable prefix of one attached Session against a
|
||||
* detached persistence inspection. The header and every stored event must
|
||||
* match the live identity; absent top-level `delegationDepth` is the persisted
|
||||
* format's canonical zero. A divergent or impossible suffix proves nothing
|
||||
* and therefore returns zero.
|
||||
*/
|
||||
function identityMatchingStoredPrefix(
|
||||
session: Pick<Session, 'header'>,
|
||||
liveEvents: readonly SessionEvent[],
|
||||
stored: { meta: SessionHeader; events: readonly SessionEvent[] },
|
||||
): number {
|
||||
const liveIdentity = {
|
||||
...session.header,
|
||||
delegationDepth: session.header.delegationDepth ?? 0,
|
||||
}
|
||||
const storedIdentity = {
|
||||
...stored.meta,
|
||||
delegationDepth: stored.meta.delegationDepth ?? 0,
|
||||
}
|
||||
if (!isDeepStrictEqual(storedIdentity, liveIdentity) || stored.events.length > liveEvents.length) return 0
|
||||
for (let index = 0; index < stored.events.length; index += 1) {
|
||||
if (!isDeepStrictEqual(stored.events[index], liveEvents[index])) return 0
|
||||
}
|
||||
return stored.events.length
|
||||
}
|
||||
|
||||
/**
|
||||
* The projection baseline for one history tail page: the registry's
|
||||
* watermark-cache snapshot — one fully synchronous read (no await between the
|
||||
@@ -802,8 +745,6 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
|
||||
const pendingQuestions = new Map<RpcId, PendingQuestion>()
|
||||
const pendingApprovals = new Map<RpcId, PendingApproval>()
|
||||
const muxQueues = new Set<FrameQueue<RpcRequest<MuxFrame>>>()
|
||||
/** Commit-aware event presentation cursor keyed by exact live Session identity. */
|
||||
const presentedThrough = new WeakMap<Session, number>()
|
||||
|
||||
/**
|
||||
* Install or return the session-local model selection that prompt assembly snapshots.
|
||||
@@ -869,25 +810,6 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
|
||||
for (const queue of muxQueues) queue.push(envelope)
|
||||
}
|
||||
|
||||
// Raw append delivery remains unchanged. A successful durability checkpoint
|
||||
// later replays only newly covered Schedule dispatches with their sidecar;
|
||||
// exact-Session identity and max advancement contain id reuse and reversed
|
||||
// concurrent flush completion without creating another durable state owner.
|
||||
ctx.on('session/flushed', (session, throughSeq) => {
|
||||
const previous = presentedThrough.get(session) ?? 0
|
||||
if (throughSeq <= previous) return
|
||||
presentedThrough.set(session, throughSeq)
|
||||
for (let seq = previous; seq < throughSeq; seq += 1) {
|
||||
const event = session.events[seq]
|
||||
if (event === undefined) {
|
||||
throw new Error(`api-proxy: flushed prefix for "${session.id}" is missing event seq ${seq}`)
|
||||
}
|
||||
const view = scheduleViewFor(ctx, session.header, session.events, event)
|
||||
if (view === undefined) continue
|
||||
broadcast({ type: 'session/event', sessionId: session.id, event, view })
|
||||
}
|
||||
})
|
||||
|
||||
// Projection change feed → session/projection push frames. The carrier
|
||||
// mints the wire frame (the Service Definition package holds no wire vocabulary); the
|
||||
// child activates only when a projection registry is composed, and the
|
||||
@@ -1101,57 +1023,17 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
|
||||
async function historyStateFor(
|
||||
sessionId: SessionId,
|
||||
includeProjections: boolean,
|
||||
): Promise<{
|
||||
header: SessionHeader
|
||||
events: SessionEvent[]
|
||||
presentedThroughSeq: number
|
||||
projections?: SessionProjectionsBlock
|
||||
}> {
|
||||
): Promise<{ events: SessionEvent[]; projections?: SessionProjectionsBlock }> {
|
||||
const attached = ctx.sessions.get(sessionId)
|
||||
if (attached !== undefined) {
|
||||
const events = [...attached.events]
|
||||
const projections = includeProjections ? projectionsFor(ctx, attached) : undefined
|
||||
let presentedThroughSeq = 0
|
||||
const persistence = ctx.get('sessionPersistence')
|
||||
if (persistence !== undefined) {
|
||||
try {
|
||||
const stored = await persistence.readFrom(sessionId, 0)
|
||||
presentedThroughSeq = identityMatchingStoredPrefix(attached, events, stored)
|
||||
} catch (error: unknown) {
|
||||
// Attached history remains available from the live Session. A
|
||||
// failed or not-yet-materialized physical read only withholds
|
||||
// commit-gated event presentation sidecars.
|
||||
ctx.logger.warn(`session.history: physical persistence read for attached "${sessionId}" failed; serving raw events: ${String(error)}`)
|
||||
}
|
||||
}
|
||||
return {
|
||||
header: attached.header,
|
||||
events,
|
||||
presentedThroughSeq,
|
||||
...projections === undefined ? {} : { projections },
|
||||
}
|
||||
return { events, ...projections === undefined ? {} : { projections } }
|
||||
}
|
||||
const inspected = await inspectServable(sessionId)
|
||||
const projections = includeProjections ? detachedProjectionsFor(ctx, inspected.events) : undefined
|
||||
let presentedThroughSeq = 0
|
||||
const persistence = ctx.get('sessionPersistence')
|
||||
/* v8 ignore next -- inspectServable already rejects when persistence is absent */
|
||||
if (persistence !== undefined) {
|
||||
try {
|
||||
const stored = await persistence.readFrom(sessionId, 0)
|
||||
presentedThroughSeq = identityMatchingStoredPrefix(
|
||||
{ header: inspected.meta },
|
||||
inspected.events,
|
||||
stored,
|
||||
)
|
||||
} catch (error: unknown) {
|
||||
ctx.logger.warn(`session.history: physical persistence read for detached "${sessionId}" failed; serving raw events: ${String(error)}`)
|
||||
}
|
||||
}
|
||||
return {
|
||||
header: inspected.meta,
|
||||
events: inspected.events,
|
||||
presentedThroughSeq,
|
||||
...projections === undefined ? {} : { projections },
|
||||
}
|
||||
}
|
||||
@@ -1729,12 +1611,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
|
||||
|
||||
async history(request) {
|
||||
const { sessionId, beforeSeq, maxMessages } = request.payload
|
||||
let state: {
|
||||
header: SessionHeader
|
||||
events: SessionEvent[]
|
||||
presentedThroughSeq: number
|
||||
projections?: SessionProjectionsBlock
|
||||
}
|
||||
let state: { events: SessionEvent[]; projections?: SessionProjectionsBlock }
|
||||
try {
|
||||
state = await historyStateFor(sessionId, beforeSeq === undefined)
|
||||
} catch (error: unknown) {
|
||||
@@ -1747,10 +1624,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
|
||||
details: {},
|
||||
})
|
||||
}
|
||||
const page = historyPage(ctx, state.events, beforeSeq, maxMessages, {
|
||||
header: state.header,
|
||||
throughSeq: state.presentedThroughSeq,
|
||||
})
|
||||
const page = historyPage(ctx, state.events, beforeSeq, maxMessages)
|
||||
return ok(request, {
|
||||
events: page.events,
|
||||
hasMore: page.hasMore,
|
||||
|
||||
@@ -11,7 +11,7 @@ import type { Wire } from './rpc.schema.ts'
|
||||
import { rpcErrorSchema, rpcIdSchema } from './rpc.schema.ts'
|
||||
import { approvalRequestIdSchema } from './approvals.schema.ts'
|
||||
import {
|
||||
contentBlockSchema, messageIdSchema, sessionEventSchema, sessionEventViewSchema, sessionIdSchema,
|
||||
contentBlockSchema, messageIdSchema, sessionEventSchema, sessionIdSchema, toolEventViewSchema,
|
||||
} from './sessions.schema.ts'
|
||||
import { workspaceIdSchema, workspaceViewSchema } from './workspace.schema.ts'
|
||||
|
||||
@@ -40,7 +40,7 @@ const messageSchema = z.object({
|
||||
|
||||
/** MuxFrame union (payload slot of a mux-stream ServerRequest). */
|
||||
export const muxFrameSchema = z.discriminatedUnion('type', [
|
||||
z.object({ type: z.literal('session/event'), sessionId: sessionIdSchema, event: sessionEventSchema, view: sessionEventViewSchema.optional() }),
|
||||
z.object({ type: z.literal('session/event'), sessionId: sessionIdSchema, event: sessionEventSchema, view: toolEventViewSchema.optional() }),
|
||||
z.object({ type: z.literal('session/subscribed'), sessionId: sessionIdSchema, lastSeq: z.number().int() }),
|
||||
z.object({ type: z.literal('approval/requested'), sessionId: sessionIdSchema, approvalId: approvalRequestIdSchema, toolName: z.string(), callId: z.string().optional(), reason: z.string().optional() }),
|
||||
z.object({ type: z.literal('approval/resolved'), sessionId: sessionIdSchema, approvalId: approvalRequestIdSchema, outcome: z.union([z.literal('allowed-once'), z.literal('rejected'), z.literal('cancelled'), z.literal('unavailable')]) }),
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user