diff --git a/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.i18n.yaml new file mode 100644 index 0000000000..d47947c99f --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.i18n.yaml @@ -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/architecture/2026-09-05-canonical-feedback-log.md +2026-09-05-canonical-feedback-log.md: e30e21bc89c8fd21177ef1f0be98de506cc67a61 +2026-09-05-canonical-feedback-log.zh.md: b1b1623fc16768a15a45554e41e6856364fb91a5 diff --git a/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.md b/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.md new file mode 100644 index 0000000000..e30e21bc89 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.md @@ -0,0 +1,33 @@ +# Agent Note: Canonical feedback log and request delivery + +Status: implemented + +English | [中文](2026-09-05-canonical-feedback-log.zh.md) + +## Problem + +Editable message ratings need one durable authority that Session export and request delivery can retain. A separate feedback store makes those consumers incomplete and introduces a second commit relationship with the target message. Recording a human judgment must not change model input or imply that a collector accepted it. + +## Decision + +The canonical Session log owns feedback. Session-level remarks use `feedback/record`; material message edits and deletions use `feedback/message-put` and `feedback/message-delete`. All are log-only. The service folds current items from events matching the requested `sessionId`, so inherited parent events do not become a fork's current feedback. Deletion removes the current item, not earlier ratings or notes from the log. + +Live message-feedback mutations append through the owning Session and await its durability checkpoint; cold mutations hold a persistence write handle across read, comparison, append, and flush without creating a Session or Agent. A matching no-op appends nothing but still awaits persistence. Failures propagate, and a failed live flush can leave an observable in-memory item for retry. Per-item versions prevent unrelated message edits from conflicting; strict stale-write rejection prevents ABA overwrites even when the desired value matches. Target validation binds a judgment to a sent assistant message, and forks keep independent judgments. These choices retain rationale recorded in the [archived sidecar decision](../../archived/architecture/2026-08-10-message-feedback-sidecar.md), whose storage and commit mechanism is superseded. + +The existing opt-in [session-log-deepseek contribution](../../../../packages/session/session-log-deepseek/README.md) includes feedback in the ordinary `dsh_session_log` suffix on a subsequent eligible request. It uses the existing DeepSeek destination selection and acceptance watermark. There is no separate `dsh_feedback` uploader, feedback-triggered request, or model-input field. The shipped base disables its OTel row; this supersedes the default composition in the [feedback-gated default decision](../feature/2026-08-25-feedback-gated-telemetry-default.md), not the optional backend's modes. + +The command confirms recording with the Session and anonymous user ids, without depending on telemetry or disclosing its policy. Its append remains unflushed. This supersedes the command-copy decision in the [archived sharing disclosure note](../../archived/feature/2026-08-07-feedback-acknowledgement-sharing-disclosure.md). The [telemetry service's policy API](../../../../packages/session/session-telemetry/README.md#the-sharing-disclosure) remains independently available: a backend discloses its policy, not delivery or retention, and the optional OTel package does not own that vocabulary. + +## Alternatives considered + +**Keep the sidecar.** It supports destructive local edits, but cannot make feedback part of ordinary canonical-log export and delivery without another join and durability relationship. + +**Reuse `feedback/record` for message edits.** A free-text Session remark does not identify an item mutation, and its optional OTel consumer treats it as a release trigger. Distinct events preserve message identity and deletion semantics without that coupling. + +**Add a dedicated uploader or immediate request.** The existing opt-in log contribution already carries canonical events and records acceptance. A second path would add delivery ownership and deduplication policy; this design accepts delayed delivery instead. + +## Consequences + +Feedback survives ordinary log export and replay without consuming model-input tokens or changing KV Cache. Current-item deletion is not erasure, and feedback recorded after the last eligible request can remain local indefinitely. The Web controller remains a unary Remote consumer and does not consume feedback log events for cross-tab updates. + +[Message-feedback tests](../../../../packages/feedback/message-feedback/tests/message-feedback.spec.ts) cover material events, no-ops, strict versions, fork isolation, and persistence failures. The [request contribution tests](../../../../packages/session/session-log-deepseek/tests) own suffix acceptance and retry; the [command tests](../../../../packages/feedback/command-feedback/tests/command-feedback.spec.ts) pin the plain confirmation. diff --git a/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.zh.md b/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.zh.md new file mode 100644 index 0000000000..b1b1623fc1 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.zh.md @@ -0,0 +1,33 @@ +# Agent Note: 权威反馈日志与请求投递 + +Status: implemented + +[English](2026-09-05-canonical-feedback-log.md) | 中文 + +## 问题 + +可编辑的消息评分需要一个能由 Session 导出与请求投递保留的持久权威来源。独立的反馈存储会让这些消费方拿到不完整的数据，并引入与目标消息之间的第二套提交关系。记录人类判断不能改变模型输入，也不能暗示采集端已经接受数据。 + +## 决策 + +权威 Session 日志拥有反馈。Session 级备注使用 `feedback/record`；消息的实质编辑与删除使用 `feedback/message-put` 和 `feedback/message-delete`。三者都仅写日志。服务从与请求的 `sessionId` 匹配的事件中归约当前条目，因此继承的父级事件不会成为 fork 的当前反馈。删除会移除当前条目，但不会抹除日志中早先的评分或备注。 + +live 消息反馈变更通过所属 Session 追加，并等待其持久化检查点；cold 变更在读取、比较、追加和 flush 期间持有持久化写句柄，不创建 Session 或 Agent。匹配版本的无变更操作不追加事件，但仍等待持久化。故障会原样传播，live flush 失败可能留下可观测的内存条目以供重试。逐条版本避免不同消息的编辑互相冲突；严格拒绝陈旧写入避免 ABA 覆盖，即使期望值已经匹配也不例外。目标校验把判断绑定到已发送的 assistant 消息，fork 保持独立判断。这些选择保留[已归档伴随记录决策](../../archived/architecture/2026-08-10-message-feedback-sidecar.md)记载的理由，但其存储与提交机制已被取代。 + +现有需显式启用的 [session-log-deepseek 贡献](../../../../packages/session/session-log-deepseek/README.zh.md)会在后续符合条件的请求中，把反馈纳入普通 `dsh_session_log` 后缀。它使用现有的 DeepSeek 目标选择和接受水位。没有独立的 `dsh_feedback` 上传器、反馈触发的请求或模型输入字段。随附基础配置禁用 OTel 配置行；这取代[反馈门控默认值决策](../feature/2026-08-25-feedback-gated-telemetry-default.zh.md)中的默认组合，不改变可选后端的模式。 + +命令用 Session 与匿名用户 id 确认记录，不依赖遥测，也不披露其策略。其追加仍不执行 flush。这取代[已归档共享披露记录](../../archived/feature/2026-08-07-feedback-acknowledgement-sharing-disclosure.md)中的命令文案决策。[遥测服务的策略 API](../../../../packages/session/session-telemetry/README.zh.md#the-sharing-disclosure) 仍可独立使用：后端披露策略，而不保证投递或保留，可选 OTel 包不拥有这套词汇。 + +## 考虑过的替代方案 + +**保留伴随记录。** 它支持破坏性的本地编辑，但若不增加关联读取及持久化关系，就无法让反馈参与普通权威日志导出与投递。 + +**对消息编辑复用 `feedback/record`。** 自由文本的 Session 备注不能标识条目变更，其可选 OTel 消费方还会将它当作释放触发器。独立事件保留消息身份和删除语义，不引入该耦合。 + +**增加专用上传器或立即发起请求。** 现有需显式启用的日志贡献已经传送权威事件并记录接受结果。第二条路径会增加投递归属与去重策略；本设计接受延迟投递。 + +## 后果 + +反馈随普通日志导出与回放保留，不消耗模型输入 token，也不改变 KV Cache。删除当前条目不等于抹除历史，最后一次符合条件的请求之后记录的反馈可能无限期保留在本地。Web 控制器仍消费一元 Remote，不消费反馈日志事件来更新其他标签页。 + +[消息反馈测试](../../../../packages/feedback/message-feedback/tests/message-feedback.spec.ts)覆盖实质事件、无变更操作、严格版本、fork 隔离与持久化故障。[请求贡献测试](../../../../packages/session/session-log-deepseek/tests)负责后缀接受与重试；[命令测试](../../../../packages/feedback/command-feedback/tests/command-feedback.spec.ts)固定纯确认文本。 diff --git a/.agents/notes/implemented/feature/2026-08-25-feedback-gated-telemetry-default.i18n.yaml b/.agents/notes/implemented/feature/2026-08-25-feedback-gated-telemetry-default.i18n.yaml index 99cd82ef90..baeea9c7b5 100644 --- a/.agents/notes/implemented/feature/2026-08-25-feedback-gated-telemetry-default.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-25-feedback-gated-telemetry-default.i18n.yaml @@ -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-25-feedback-gated-telemetry-default.md -2026-08-25-feedback-gated-telemetry-default.md: 19ed75859b54044d38c473f9bd5e8840c5cd2844 -2026-08-25-feedback-gated-telemetry-default.zh.md: d82776b4250e1c37b821df5f387f9df05e0fbfd0 +2026-08-25-feedback-gated-telemetry-default.md: f3de87e8aec62b5fe6ddc71a008ac0fd82aef78d +2026-08-25-feedback-gated-telemetry-default.zh.md: be3a0d6819a0074a2d30a200cde19e0d3f260363 diff --git a/.agents/notes/implemented/feature/2026-08-25-feedback-gated-telemetry-default.md b/.agents/notes/implemented/feature/2026-08-25-feedback-gated-telemetry-default.md index 19ed75859b..f3de87e8ae 100644 --- a/.agents/notes/implemented/feature/2026-08-25-feedback-gated-telemetry-default.md +++ b/.agents/notes/implemented/feature/2026-08-25-feedback-gated-telemetry-default.md @@ -10,20 +10,22 @@ Diagnosing a `/feedback` report needs the session data the report describes. Wit ## Decision -The shared dsh base resolves an unset or empty `DSH_TELEMETRY_MODE` to `FEEDBACK_ONLY` instead of `DISABLED`. Nothing is uploaded before the user records `/feedback`. On a Session object already captured, each feedback uploads the suffix after the last handoff through that exact event. A new object starts at its constructor boundary: a fresh Session begins at seq 0, while a forked, resumed, or migrated Session excludes its constructor seed and begins with this lifecycle's `session/end-seed`. The acknowledgement's sharing disclosure therefore matches the released lifecycle-local prefix. `FULL` and `DISABLED` remain explicit `DSH_TELEMETRY_MODE` overrides, any non-empty `DSH_TELEMETRY_DISABLED` remains the authoritative pre-load hard opt-out, and the plugin's own omitted-`mode` default stays `DISABLED`: the default changes only in the shared base's config expression, where deployments already override it. +The [canonical feedback decision](../architecture/2026-09-05-canonical-feedback-log.md) supersedes this default composition: the shipped base disables its OTel row. The optional backend retains its modes; the release-boundary rationale below does not authorize upload in a default installation. -This supersedes the session-backend default of the [default-off decision](../../archived/feature/2026-08-10-telemetry-default-off.md), accepting the user's explicit feedback action as the release authorization that note required a deployment setting for. That note's hard opt-out and its launcher-feed history remain current, and the [default-mount decision](../../archived/feature/2026-07-31-web-telemetry-default-mount.md) continues to own the endpoint, batching cadence, and exit-drain settings. +When explicitly enabled without replacing its config, the shared base's OTel row resolves an unset or empty `DSH_TELEMETRY_MODE` to `FEEDBACK_ONLY`. The plugin's own omitted-`mode` default remains `DISABLED`; `FULL` and `DISABLED` are explicit environment overrides, and non-empty `DSH_TELEMETRY_DISABLED` remains the pre-load hard opt-out. In `FEEDBACK_ONLY`, each `feedback/record` releases the canonical suffix after the same Session object's handoff cursor through that event. A new object starts at its constructor boundary: a fresh Session begins at seq 0, while a forked, resumed, or migrated Session excludes its constructor seed and begins with this lifecycle's `session/end-seed`. + +Feedback-gated release lets a reporter share the lifecycle that exhibited the problem without reproducing it. It trades continuous export for an explicit feedback trigger, but a deployment must establish consent before enabling that policy. The [archived default-off](../../archived/feature/2026-08-10-telemetry-default-off.md) and [default-mount](../../archived/feature/2026-07-31-web-telemetry-default-mount.md) notes record the earlier composition; the [base patch](../../../../packages/bundle/base/cordis.patch.yml) and [OTel README](../../../../packages/session/session-telemetry-otel/README.md) own current configuration. ## Alternatives considered -**Keep `DISABLED` and instruct reporters to re-run with `DSH_TELEMETRY_MODE=FEEDBACK_ONLY`.** Rejected: the session that exhibited the problem is the one worth uploading, and re-running loses it. +**Require reporters to re-run after enabling telemetry.** Rejected as the feedback-gated workflow: the Session that exhibited the problem is the useful evidence, and re-running loses it. -**Default to `FULL`.** Rejected: continuous export without any user action is exactly what the default-off decision forbids, and nothing in a fresh installation authorizes it. +**Default to `FULL`.** Rejected: a fresh installation does not authorize continuous export without user action. -**Gate the official DeepSeek `dsh_session_log` request contribution on feedback instead of reviving the OTel default.** Not taken here: that contribution uploads through subsequent LLM requests rather than at the feedback boundary, so a session's final feedback would never be delivered; a feedback-triggered flush on that path is a larger design than a default flip. +**Use only subsequent DeepSeek requests for delivery.** The canonical feedback decision accepts this for the shipped default, including the risk that a final feedback entry remains local. The optional feedback-gated OTel mode retains its event-time release trigger; request-time delivery cannot provide that timing without initiating another request. ## Consequences -- A fresh installation uploads the not-yet-shared session-log records to the production collector when — and only when — the user records `/feedback`; no other trigger uploads. -- Released exports remain the raw captured copy: the shipped base mounts no `session-telemetry/record` redaction rule, so they can contain message text, tool arguments and results, and workspace paths. -- The sharing disclosure is part of the `/feedback` acknowledgement, so the user reads it after the release has been triggered. A deployment that requires prior informed consent must override the default to `DISABLED` or add a pre-upload confirmation before this default is defensible there. +- The shipped base uploads nothing through OTel. An explicitly enabled `FEEDBACK_ONLY` backend hands off the unreleased lifecycle-local prefix only on `feedback/record`; message-rating events do not themselves trigger release. +- On-demand capture copies and redacts the canonical log at feedback time. Without a deployment redaction rule, exported data can include message text, tool arguments and results, and workspace paths. +- The command acknowledgement confirms recording, not sharing or delivery. A deployment requiring prior informed consent must provide it before enabling uploads; OTel handoff remains subject to the SDK's batching, retry, and loss policy. diff --git a/.agents/notes/implemented/feature/2026-08-25-feedback-gated-telemetry-default.zh.md b/.agents/notes/implemented/feature/2026-08-25-feedback-gated-telemetry-default.zh.md index d82776b425..be3a0d6819 100644 --- a/.agents/notes/implemented/feature/2026-08-25-feedback-gated-telemetry-default.zh.md +++ b/.agents/notes/implemented/feature/2026-08-25-feedback-gated-telemetry-default.zh.md @@ -10,20 +10,22 @@ Status: implemented ## 决定 -共享 dsh 基础配置把未设置或为空的 `DSH_TELEMETRY_MODE` 解析为 `FEEDBACK_ONLY` 而不是 `DISABLED`。用户记录 `/feedback` 之前不上传任何数据。对于已经捕获的 Session 对象，每条反馈会上传从上次交接之后至该事件的后缀。新对象从 constructor boundary 开始：全新 Session 从 seq 0 开始，而 fork、resume 或迁移 Session 排除 constructor seed，从本生命周期的 `session/end-seed` 开始。因此，确认信息中的共享声明与所释放的生命周期本地前缀一致。`FULL` 和 `DISABLED` 仍是显式的 `DSH_TELEMETRY_MODE` 覆盖值，任何非空的 `DSH_TELEMETRY_DISABLED` 仍是加载前的强制关闭开关，插件自身省略 `mode` 的默认值仍是 `DISABLED`：默认值只在共享基础配置的配置表达式中改变，部署本来就在那里覆盖它。 +[权威反馈决策](../architecture/2026-09-05-canonical-feedback-log.zh.md)取代此默认组合：随附基础配置禁用 OTel 配置行。可选后端保留其模式；下述释放边界的理由不构成默认安装的上传授权。 -本决定取代[默认关闭决定](../../archived/feature/2026-08-10-telemetry-default-off.md)中会话后端的默认值，把用户显式的反馈动作接受为该决定原本要求由部署设置提供的释放授权。该决定的强制关闭开关和 launcher 上报历史仍然有效，端点、批处理节奏和退出排空设置仍由[默认挂载决定](../../archived/feature/2026-07-31-web-telemetry-default-mount.md)持有。 +共享基础配置的 OTel 行被显式启用且其 config 未被替换时，会把未设置或为空的 `DSH_TELEMETRY_MODE` 解析为 `FEEDBACK_ONLY`。插件自身省略 `mode` 的默认值仍是 `DISABLED`；`FULL` 和 `DISABLED` 是显式环境覆盖值，非空 `DSH_TELEMETRY_DISABLED` 仍是加载前的强制关闭开关。在 `FEEDBACK_ONLY` 下，每个 `feedback/record` 会释放同一 Session 对象的 handoff 游标之后至该事件的权威后缀。新对象从 constructor boundary 开始：全新 Session 从 seq 0 开始，而 fork、resume 或迁移 Session 排除 constructor seed，从本生命周期的 `session/end-seed` 开始。 + +反馈门控释放让报告者无需复现问题就能共享出问题的生命周期。它用显式反馈触发取代持续导出，但部署必须在启用该策略前取得同意。[已归档默认关闭](../../archived/feature/2026-08-10-telemetry-default-off.md)与[默认挂载](../../archived/feature/2026-07-31-web-telemetry-default-mount.md)记录记载早期组合；当前配置由[基础补丁](../../../../packages/bundle/base/cordis.patch.yml)与 [OTel README](../../../../packages/session/session-telemetry-otel/README.zh.md) 持有。 ## 考虑过的替代方案 -**保持 `DISABLED`，让报告者带着 `DSH_TELEMETRY_MODE=FEEDBACK_ONLY` 重跑。** 否决：值得上传的正是出现问题的那个会话，重跑会丢掉它。 +**要求报告者启用遥测后重跑。** 不作为反馈门控工作流：值得保留的证据是出问题的那个 Session，重跑会丢掉它。 -**默认 `FULL`。** 否决：没有任何用户动作的持续导出正是默认关闭决定所禁止的，全新安装中没有任何东西授权它。 +**默认 `FULL`。** 否决：全新安装不授权没有用户动作的持续导出。 -**改为在反馈时门控官方 DeepSeek `dsh_session_log` 请求贡献，而不是恢复 OTel 默认值。** 此处未采用：该贡献通过后续 LLM 请求上传，而不是在反馈边界上传，会话的最后一条反馈永远不会被交付；在那条路径上做反馈触发的冲刷是比翻转默认值更大的设计。 +**仅通过后续 DeepSeek 请求投递。** 权威反馈决策为随附默认配置接受此方案，包括最后一条反馈可能留在本地的风险。可选反馈门控 OTel 模式保留事件发生时的释放触发；请求时投递若不发起另一个请求，就无法提供这种时机。 ## 后果 -- 全新安装只在用户记录 `/feedback` 时把尚未共享的会话日志记录上传到生产 collector；没有其他触发上传的途径。 -- 释放的导出仍是未加工的原始副本：随附基础配置没有挂载 `session-telemetry/record` 脱敏规则，导出可能包含消息文本、工具参数和结果，以及 workspace 路径。 -- 共享声明是 `/feedback` 确认信息的一部分，用户读到它时释放已被触发。要求事先知情同意的部署必须把默认值覆盖为 `DISABLED`，或在上传前增加确认步骤，此默认值在那类部署中才站得住。 +- 随附基础配置不通过 OTel 上传任何内容。显式启用的 `FEEDBACK_ONLY` 后端只在 `feedback/record` 时交接未释放的生命周期本地前缀；消息评分事件本身不触发释放。 +- 按需捕获在反馈时复制权威日志并脱敏。部署未挂载脱敏规则时，导出数据可能包含消息文本、工具参数和结果，以及 workspace 路径。 +- 命令确认文本确认记录，而非共享或投递。要求事先知情同意的部署必须在启用上传前提供该步骤；OTel 交接仍受 SDK 的批处理、重试与丢失策略约束。 diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml index 37aef6b7ae..62a15983f8 100644 --- a/apps/cli/reference/README.i18n.yaml +++ b/apps/cli/reference/README.i18n.yaml @@ -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 apps/cli/reference/README.md -README.md: 78328be4d614ebf647d6f00a6f0d66978919da3e -README.zh.md: c140c3ba528509611ae17712851c6d406c190972 +README.md: fe2b5bab5a41095d4184f49de36dfec40cc87bc0 +README.zh.md: 01e0d06fe57f9364d7411d2e2dae7892327d803e diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md index 78328be4d6..fe2b5bab5a 100644 --- a/apps/cli/reference/README.md +++ b/apps/cli/reference/README.md @@ -89,9 +89,9 @@ New sessions in base-backed profiles default to the `workspace-write` permission ## Shared deployment behavior -The base bundle mounts the native DeepSeek adapter, settings and credential providers, stable `web_search` and `web_fetch`, the public-only HTTP fetch provider, and feedback-gated session telemetry. Provider credentials resolve from the inherited environment, `$DSH_HOME/.credentials.yaml`, the invoking directory's `.env`, then `$DSH_HOME/.env`; the managed document is never materialized into `process.env`, while both `.env` files are ordinary launch environment layers. Search uses `DEEPSEEK_API_KEY` and accepts `DEEPSEEK_SEARCH_BASE_URL`. Enabled fetch calls run in every sandbox and approval mode without per-call confirmation; the provider rejects non-public destinations before connecting. The Web app disables the base tool row and exposes the same tools through its `cordis`, `ptc`, and `standard` agent presets. +The base bundle mounts the native DeepSeek adapter, settings and credential providers, stable `web_search` and `web_fetch`, the public-only HTTP fetch provider, and opt-in DeepSeek session-log upload. Provider credentials resolve from the inherited environment, `$DSH_HOME/.credentials.yaml`, the invoking directory's `.env`, then `$DSH_HOME/.env`; the managed document is never materialized into `process.env`, while both `.env` files are ordinary launch environment layers. Search uses `DEEPSEEK_API_KEY` and accepts `DEEPSEEK_SEARCH_BASE_URL`. Enabled fetch calls run in every sandbox and approval mode without per-call confirmation; the provider rejects non-public destinations before connecting. The Web app disables the base tool row and exposes the same tools through its `cordis`, `ptc`, and `standard` agent presets. -Session telemetry defaults to feedback-gated sharing: nothing is uploaded until the user records `/feedback`, and each recorded feedback uploads the session records not yet shared, through that event; a resumed session shares only its current lifecycle. `DSH_TELEMETRY_MODE=FULL` instead streams every projected session event as OTLP/HTTP logs, `DSH_TELEMETRY_MODE=DISABLED` keeps everything local, and any non-empty `DSH_TELEMETRY_DISABLED` remains an authoritative hard opt-out. `DSH_TELEMETRY_OTLP_URL` selects another collector. The shipped base has no telemetry redaction rule, so released exports can contain message text, tool arguments and results, and workspace paths; the [feedback-gated-default Agent Note](../../../.agents/notes/implemented/feature/2026-08-25-feedback-gated-telemetry-default.md) owns that deployment decision. +Feedback is recorded in the Session log without starting model work. Enable the [DeepSeek session-log contributor](../../../packages/session/session-log-deepseek/README.md) to send complete unaccepted log suffixes with subsequent DeepSeek requests, including configured gateways. The shipped OTel session-upload row is disabled; changing `DSH_TELEMETRY_MODE` alone does not enable it. Session-log upload can include message text, tool arguments and results, and workspace paths. Install external plugin bundles through `dsh plugin --profile add `. The installed package owns its dependencies and contributes its declared `cordis.patch.yml` layer. The CLI also ships `@deepseek-ai/dsh-mcp-client` as a dependency for patch layers, but no MCP server is enabled by default because each server command is trusted executable code outside the agent sandbox. diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md index c140c3ba52..01e0d06fe5 100644 --- a/apps/cli/reference/README.zh.md +++ b/apps/cli/reference/README.zh.md @@ -89,9 +89,9 @@ dsh web --help ## 共享部署行为 -基础组合包挂载原生 DeepSeek 适配器、settings 与凭据提供方、稳定的 `web_search` 和 `web_fetch`、仅限公网的 HTTP fetch 提供方，以及按反馈门控的会话遥测。提供方凭据依次从继承环境、`$DSH_HOME/.credentials.yaml`、调用目录的 `.env` 和 `$DSH_HOME/.env` 解析；受管文档从不物化进 `process.env`，而两个 `.env` 文件都是普通启动环境层。搜索使用 `DEEPSEEK_API_KEY` 并接受 `DEEPSEEK_SEARCH_BASE_URL`。已启用的抓取调用会在所有 sandbox 与审批模式下执行，无需逐次确认；提供方会在连接前拒绝非公开目的地址。Web app 会禁用 base 工具配置项，再通过 `cordis`、`ptc` 与 `standard` agent preset 暴露相同工具。 +基础组合包挂载原生 DeepSeek 适配器、settings 与凭据提供方、稳定的 `web_search` 和 `web_fetch`、仅限公网的 HTTP fetch 提供方，以及需主动开启的 DeepSeek 会话日志上传。提供方凭据依次从继承环境、`$DSH_HOME/.credentials.yaml`、调用目录的 `.env` 和 `$DSH_HOME/.env` 解析；受管文档从不物化进 `process.env`，而两个 `.env` 文件都是普通启动环境层。搜索使用 `DEEPSEEK_API_KEY` 并接受 `DEEPSEEK_SEARCH_BASE_URL`。已启用的抓取调用会在所有 sandbox 与审批模式下执行，无需逐次确认；提供方会在连接前拒绝非公开目的地址。Web app 会禁用 base 工具配置项，再通过 `cordis`、`ptc` 与 `standard` agent preset 暴露相同工具。 -会话遥测默认按反馈门控共享：在用户记录 `/feedback` 之前不上传任何数据，每条已记录的反馈通过该事件上传尚未共享的会话记录；恢复的会话只共享当前生命周期。`DSH_TELEMETRY_MODE=FULL` 改为将每条已投影会话事件作为 OTLP/HTTP 日志流式发送，`DSH_TELEMETRY_MODE=DISABLED` 让全部数据留在本地，任何非空的 `DSH_TELEMETRY_DISABLED` 仍是具有最终效力的遥测强制关闭开关。`DSH_TELEMETRY_OTLP_URL` 选择其他 collector。随附基础配置没有遥测脱敏规则，因此释放的导出可能包含消息文本、工具参数和结果，以及 workspace 路径；相关部署决策见[反馈门控默认值 Agent Note](../../../.agents/notes/implemented/feature/2026-08-25-feedback-gated-telemetry-default.zh.md)。 +反馈记录在会话日志中，不会启动模型工作。开启 [DeepSeek 会话日志贡献器](../../../packages/session/session-log-deepseek/README.zh.md)后，后续 DeepSeek 请求会发送尚未确认的完整日志后缀，包括发往配置网关的请求。随附 OTel 会话上传行处于禁用状态；仅修改 `DSH_TELEMETRY_MODE` 不会启用该行。会话日志上传可能包含消息文本、工具参数和结果，以及工作区路径。 通过 `dsh plugin --profile add ` 安装外部插件组合包。安装的包拥有其依赖，并贡献其声明的 `cordis.patch.yml` 层。CLI 还随附 `@deepseek-ai/dsh-mcp-client` 作为供 patch 层使用的依赖，但默认不启用 MCP 服务器，因为每条服务器命令都是 agent（智能体）沙箱之外的受信任可执行代码。 diff --git a/apps/web/tests/feedback-command.e2e.ts b/apps/web/tests/feedback-command.e2e.ts index c1b82236d4..9e4a7be60e 100644 --- a/apps/web/tests/feedback-command.e2e.ts +++ b/apps/web/tests/feedback-command.e2e.ts @@ -2,12 +2,8 @@ // shipped Web bundles and the real host wire. The command plane settles // without a model turn: the host appends the log-only command/run + // feedback/record + command/done lifecycle, and the transcript renders the -// acknowledgement — the recorded session id plus the session-sharing -// disclosure — as a persistent command row. The scaffold mounts the shipped -// telemetry row in FULL mode against a local dead endpoint (no record leaves -// the process), so the golden pins the shipped default sentence -// `Session sharing is enabled.`; the per-status sentences are pinned by the -// package and OTel unit tests. +// acknowledgement with the session and anonymous user ids as a persistent +// command row. import { readFile } from 'node:fs/promises' import { fileURLToPath } from 'node:url' import { join } from 'node:path' @@ -26,9 +22,6 @@ const FIXTURE = join(SNAPSHOT_DIR, 'session.v2.jsonl') const ACK_EXPECTED = join(SNAPSHOT_DIR, 'ack.expected.md') const ACK_EXPANDED_EXPECTED = join(SNAPSHOT_DIR, 'ack-expanded.expected.md') const MODE = webSnapshotMode() -// Discard port: loopback listener never binds, so FULL telemetry discloses -// the shipped default policy without any record reaching a collector. -const TELEMETRY_URL = 'http://127.0.0.1:9/v1/logs' const PROMPT = 'Reply with the single word LIGHTHOUSE and stop.' @@ -40,7 +33,6 @@ describe('web e2e: /feedback command acknowledgement', () => { beforeAll(async () => { scaffold = await launchWebScaffold({ - telemetryUrl: TELEMETRY_URL, compareReplaySession: true, ...(MODE === 'record' ? {} : { replayFixture: FIXTURE, paceMs: 5 }), }) @@ -78,7 +70,7 @@ describe('web e2e: /feedback command acknowledgement', () => { } }, 60_000) - it.skipIf(MODE === 'record')('records feedback and renders the acknowledgement with session id and sharing status', async () => { + it.skipIf(MODE === 'record')('records feedback and renders the acknowledgement with session and anonymous user ids', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-feedback-command')) // The drive test settled the recorded turn: the transcript is active (a // command row does not render while a fresh session is still blank) and @@ -87,10 +79,8 @@ describe('web e2e: /feedback command acknowledgement', () => { const input = page.locator('[data-composer-input]').first() await input.fill('/feedback the diff view is unreadable') await input.press('Enter') - // The command plane settles without a model turn: the ack row names the - // recorded session and the mounted FULL backend's disclosure. await page.getByText(/Feedback recorded for session/).waitFor({ timeout: 10_000 }) - expect(await page.getByText(/Session sharing is enabled/).count()).toBe(1) + expect(await page.getByText(/Anonymous user: [0-9a-f-]+\.$/i).count()).toBe(1) const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd) await compareOrRefreshGolden(ACK_EXPECTED, snapshot, MODE) const expanded = await captureExpandedTurnProcessAria( diff --git a/apps/web/tests/feedback-release.e2e.ts b/apps/web/tests/feedback-release.e2e.ts index 73be6d2ac5..44854eddfa 100644 --- a/apps/web/tests/feedback-release.e2e.ts +++ b/apps/web/tests/feedback-release.e2e.ts @@ -1,11 +1,6 @@ -// Keyless assembled-browser coverage for the shipped FEEDBACK_ONLY default -// over the Web bundles and the real host wire. The scaffold mounts the -// shipped telemetry row in FEEDBACK_ONLY mode against this suite's own -// loopback mock collector, so the default release path is real: /feedback -// releases the session records through that event (exactly one OTLP request, -// carrying the drive prompt and the feedback text), the acknowledgement pins -// the feedback-gated disclosure sentence, and a second feedback releases only -// the records since the first handoff — the earlier prompt does not repeat. +// The shipped disabled OTel row keeps feedback local. A loopback collector +// observes the complete browser session through scaffold shutdown, while a +// separate persistence reader verifies both remarks reach the session log. import { readFile } from 'node:fs/promises' import { fileURLToPath } from 'node:url' import { join } from 'node:path' @@ -14,16 +9,17 @@ import { once } from 'node:events' import { gunzipSync } from 'node:zlib' import type { Browser, Page } from 'playwright' import { chromium } from 'playwright' +import type { SessionId } from '@deepseek-ai/dsh-session' import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest' import { assertFixtureInventory, captureExpandedTurnProcessAria, captureStableAria, compareOrRefreshGolden, fixtureUserPrompts, - launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold, + launchWebScaffold, readPersistedEvents, watchConsole, webSnapshotMode, type WebScaffold, } from './scaffold.ts' import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './support.ts' const SNAPSHOT_DIR = fileURLToPath(new URL('../../../snapshots/web/feedback-release', import.meta.url)) -// The release path needs only a settled ordinary turn, so this lane replays +// The local-only path needs only a settled ordinary turn, so this lane replays // the feedback-command scenario's recorded session (declared as this // manifest's `session.source`) instead of recording a duplicate. const FIXTURE = fileURLToPath(new URL('../../../snapshots/web/feedback-command/session.v2.jsonl', import.meta.url)) @@ -33,12 +29,13 @@ const MODE = webSnapshotMode() const PROMPT = 'Reply with the single word LIGHTHOUSE and stop.' -describe('web e2e: feedback-gated release under the shipped default mode', () => { +describe('web e2e: feedback stays local with shipped OTel disabled', () => { let scaffold: WebScaffold let browser: Browser let page: Page let tripwire: ReturnType let collector: Server + let sessionId: SessionId const uploads: string[] = [] beforeAll(async () => { @@ -57,13 +54,12 @@ describe('web e2e: feedback-gated release under the shipped default mode', () => if (address === null || typeof address === 'string') throw new Error('collector has no port') scaffold = await launchWebScaffold({ telemetryUrl: `http://127.0.0.1:${address.port}/v1/logs`, - telemetryMode: 'FEEDBACK_ONLY', // The replayed session.v2.jsonl belongs to the feedback-command scenario; // comparing (or refreshing) the persisted session here would rewrite - // that shared source with this lane's feedback events. The release - // evidence lives in this lane's golden and collector assertions. + // that shared source with this lane's feedback events. Persistence and + // collector assertions belong to this lane. compareReplaySession: false, - ...(MODE === 'record' ? {} : { replayFixture: FIXTURE }), + ...(MODE === 'record' ? {} : { replayFixture: FIXTURE, paceMs: 5 }), }) browser = await chromium.launch() page = await newEnglishPage(browser) @@ -74,10 +70,21 @@ describe('web e2e: feedback-gated release under the shipped default mode', () => }, 120_000) afterAll(async () => { - await browser?.close() - await scaffold?.close() - collector?.close() - collector?.closeAllConnections() + try { + await browser?.close() + await scaffold?.close() + expect(uploads).toEqual([]) + } finally { + if (collector?.listening) { + await new Promise((resolve, reject) => { + collector.close((error) => { + if (error) reject(error) + else resolve() + }) + collector.closeAllConnections() + }) + } + } }) it('drives the recorded prompt to a settled turn (all modes)', async () => { @@ -91,10 +98,10 @@ describe('web e2e: feedback-gated release under the shipped default mode', () => const settled = scaffold.whenTurnSettled() await input.fill(PROMPT) await input.press('Enter') - await settled + sessionId = await settled }, 60_000) - it.skipIf(MODE === 'record')('releases the session records through the feedback and pins the disclosure', async () => { + it.skipIf(MODE === 'record')('records feedback locally and acknowledges its session and anonymous user ids', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-feedback-release')) await page.getByText('LIGHTHOUSE', { exact: true }).waitFor({ timeout: 15_000 }) expect(uploads).toEqual([]) @@ -103,13 +110,8 @@ describe('web e2e: feedback-gated release under the shipped default mode', () => await input.press('Enter') await page.getByText(/Feedback recorded for session/).waitFor({ timeout: 10_000 }) - expect(await page.getByText(/recording feedback uploads the session records not yet shared/).count()).toBe(1) - - // FEEDBACK_ONLY releases through the committed feedback event: exactly - // one request reaches the collector, carrying the whole unshared range. - await expect.poll(() => uploads.length, { timeout: 15_000 }).toBe(1) - expect(uploads[0]).toContain('the diff view is unreadable') - expect(uploads[0]).toContain(PROMPT) + expect(await page.getByText(/Anonymous user: [0-9a-f-]+\.$/i).count()).toBe(1) + expect(uploads).toEqual([]) const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd) await compareOrRefreshGolden(ACK_EXPECTED, snapshot, MODE) @@ -123,16 +125,22 @@ describe('web e2e: feedback-gated release under the shipped default mode', () => expect(tripwire.warnings).toEqual([]) }, 60_000) - it.skipIf(MODE === 'record')('releases only the records since the last handoff on a second feedback', async () => { + it.skipIf(MODE === 'record')('persists both feedback remarks without uploading session records', async () => { onTestFailed(() => saveFailureShot(page, 'web-e2e-feedback-release-suffix')) const input = page.locator('[data-composer-input]').first() await input.fill('/feedback the second remark') await input.press('Enter') - await expect.poll(() => uploads.length, { timeout: 15_000 }).toBe(2) - // Suffix semantics: the second release starts after the first feedback's - // handoff, so the drive prompt already shared must not repeat. - expect(uploads[1]).toContain('the second remark') - expect(uploads[1]).not.toContain(PROMPT) + await expect.poll(() => page.getByText(/Feedback recorded for session/).count()).toBe(2) + const agent = scaffold.ctx.agents.get(sessionId) + if (agent === undefined) throw new Error('feedback session has no active agent') + await scaffold.ctx.sessions.flush(agent.session) + const events = await readPersistedEvents(scaffold, sessionId) + expect(events.filter(event => event.type === 'feedback/record')).toMatchObject([ + { data: { text: 'the diff view is unreadable' } }, + { data: { text: 'the second remark' } }, + ]) + expect(events.filter(event => event.type === 'turn/end')).toHaveLength(1) + expect(uploads).toEqual([]) }, 60_000) it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => { diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts index ad59c14dc8..3dc33032c2 100644 --- a/apps/web/tests/scaffold.ts +++ b/apps/web/tests/scaffold.ts @@ -383,13 +383,12 @@ export interface LaunchOptions { default: string } /** - * Mount the shipped telemetry row against this exporter URL instead of - * disabling it. Used to pin a real backend disclosure in assembled - * coverage; point the URL at a local endpoint (a dead port, or a scenario's - * own mock collector) so no record leaves the machine. + * Patch the telemetry exporter URL while preserving the shipped disabled + * setting. Point it at a scenario-owned loopback collector so a regression + * enabling the row cannot send fixture sessions outside the test. */ telemetryUrl?: string - /** Uploading mode for the mounted telemetry row. Defaults to `FULL`. */ + /** Mode when telemetryUrl is supplied; defaults to FULL without enabling a disabled row. */ telemetryMode?: 'FULL' | 'FEEDBACK_ONLY' /** * Browse through a trusted non-loopback hostname that the browser resolves @@ -552,8 +551,8 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise { let normalized = value - .replace(/Anonymous user: [^.]+(?=\. Session sharing)/g, 'Anonymous user: {{anonymousUserId}}') + .replace(/Anonymous user: [0-9a-f-]{36}(?=\.$)/gi, 'Anonymous user: {{anonymousUserId}}') for (const cwd of cwdSpellings) normalized = replaceWebCwd(normalized, cwd) return normalized }) as { type?: unknown; data?: { endpoint?: unknown } } @@ -977,7 +976,7 @@ function stableSessionFixture( cwd: workspaceCwd, }) const fresh = scrubSessionSnapshot(stabilized) - .split(session.id).join('{{sessionId}}') + .split(session.id).join('{{session:1}}') .split(harnessHome).join('{{harnessHome}}') const stable = redactSessionSnapshotIds(stabilizeFixtureMessageIds([fresh], [existing]))[0] if (stable === undefined) throw new Error('session harvest produced no stabilized fixture') diff --git a/apps/web/tests/seeded-history.e2e.ts b/apps/web/tests/seeded-history.e2e.ts index 66986cdf00..925bb5322b 100644 --- a/apps/web/tests/seeded-history.e2e.ts +++ b/apps/web/tests/seeded-history.e2e.ts @@ -520,7 +520,7 @@ describe('web e2e: seeded history renders through cold resume', () => { if (done?.type !== 'command/done') throw new Error('feedback command did not settle') const [sessionLine, userLine, extraLine] = done.data.text?.split('\n') ?? [] expect(sessionLine).toBe(`Feedback recorded for session ${SEED_ID}`) - expect(userLine).toMatch(/^Anonymous user: [0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\./i) + expect(userLine).toMatch(/^Anonymous user: [0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.$/i) expect(extraLine).toBeUndefined() const userId = userLine?.match(/^Anonymous user: ([0-9a-f-]+)/i)?.[1] if (userId === undefined) throw new Error('feedback command omitted the user id') diff --git a/docs/capability-seams.i18n.yaml b/docs/capability-seams.i18n.yaml index 1b3b1a5d5c..93823b7b78 100644 --- a/docs/capability-seams.i18n.yaml +++ b/docs/capability-seams.i18n.yaml @@ -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/capability-seams.md -capability-seams.md: ecc88e397f41c4d279effa2df9d1b29108756ea5 -capability-seams.zh.md: 105752ac01007d24788bcfbcb2eb22c07cfdd0f5 +capability-seams.md: fd27d61959fbc53589c1345cfb9cc9bc0acbb161 +capability-seams.zh.md: 6fb09b90df6656c6b57f69afd0c76ef39baf5510 diff --git a/docs/capability-seams.md b/docs/capability-seams.md index ecc88e397f..fd27d61959 100644 --- a/docs/capability-seams.md +++ b/docs/capability-seams.md @@ -421,7 +421,6 @@ flowchart LR svc_skills --> pkg_tool_skill svc_spillStore --> pkg_spill_policy svc_storage --> pkg_storage_domain - svc_storageDomain --> pkg_message_feedback svc_storageDomain --> pkg_workspace svc_subagentModelSelection --> pkg_tool_subagent svc_subagents --> pkg_tool_ralph @@ -493,8 +492,8 @@ flowchart LR | `ctx.authorization` | `seam` | [`authorization`](../packages/credentials/authorization) | - | [`llm-pi-ai`](../packages/llm/llm-pi-ai) | - | Flows are registered by the plugin that knows how to obtain one credential and keyed by the record they write; the seam owns the conversation and the one-attempt-per-key lifecycle, never the protocol. | | `ctx.sessionTelemetry` | `seam` | [`session-telemetry`](../packages/session/session-telemetry) | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | - | - | The seam captures, redacts, and hands session records to one backend; nothing else consumes the service — its output leaves the process. | | `ctx.storage` | `seam` | [`storage`](../packages/storage/storage) | [`storage-json`](../packages/storage/storage-json), [`storage-sqlite`](../packages/storage/storage-sqlite) | [`storage-domain`](../packages/storage/storage-domain) | - | Backends register side by side under names; data forms (domain first) mount on the hub and translate typed operations into opaque KV-unit primitives. | -| `ctx.storageDomain` | `core` | [`storage-domain`](../packages/storage/storage-domain) | - | [`workspace`](../packages/workspace/workspace), [`message-feedback`](../packages/feedback/message-feedback) | - | Waits for every configured backend, then publishes the domain form as one lifecycle-bound service for typed durable state. | -| `ctx.messageFeedback` | `core` | [`message-feedback`](../packages/feedback/message-feedback) | - | - | - | Owns local per-assistant-message feedback, lifecycle and target validation, per-item compare-and-set, and the Host unary Remote contract without entering Session history or telemetry. | +| `ctx.storageDomain` | `core` | [`storage-domain`](../packages/storage/storage-domain) | - | [`workspace`](../packages/workspace/workspace) | - | Waits for every configured backend, then publishes the domain form as one lifecycle-bound service for typed durable state. | +| `ctx.messageFeedback` | `core` | [`message-feedback`](../packages/feedback/message-feedback) | - | - | - | Owns per-assistant-message feedback in the canonical Session log, target validation, per-item compare-and-set, and the Host unary Remote contract. Feedback stays outside model history; log export follows the consumer policy. | | `ctx.workspaceRegistry` | `core` | [`workspace`](../packages/workspace/workspace) | - | [`api-workspace-controller`](../packages/api/workspace-controller), [`api-session-controller`](../packages/api/session-controller) | - | Owns WorkspaceId-branded records over the domain facility; stable sessionIds accounts drive Host RPC and GUI projections. | | `ctx.sessionQuery` | `seam` | [`session-query`](../packages/session-query/session-query) | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | [`session-reference`](../packages/context/session-reference), [`tool-session-query`](../packages/session-query/tool-session-query) | - | The interface supplies exact reads, filters, and traces; its concrete backend adds full-text reconciliation, ranking, snippets, and cursor generations, while the model consumer owns workspace authority and cursor-free rendering. | | `ctx.fileReferences` | `seam` | [`file-reference`](../packages/context/file-reference) | [`file-reference-local`](../packages/context/file-reference-local) | [`api-session-controller`](../packages/api/session-controller) | - | The interface returns path-only completion candidates within an Agent cwd; providers own namespace access and ranking without reading file contents. | diff --git a/docs/capability-seams.zh.md b/docs/capability-seams.zh.md index 105752ac01..6fb09b90df 100644 --- a/docs/capability-seams.zh.md +++ b/docs/capability-seams.zh.md @@ -423,7 +423,6 @@ flowchart LR svc_skills --> pkg_tool_skill svc_spillStore --> pkg_spill_policy svc_storage --> pkg_storage_domain - svc_storageDomain --> pkg_message_feedback svc_storageDomain --> pkg_workspace svc_subagentModelSelection --> pkg_tool_subagent svc_subagents --> pkg_tool_ralph @@ -495,8 +494,8 @@ flowchart LR | `ctx.authorization` | `seam` | [`authorization`](../packages/credentials/authorization) | - | [`llm-pi-ai`](../packages/llm/llm-pi-ai) | - | flow 由知道如何取得某份凭据的插件注册，并以其写入的记录为键；seam 拥有这段对话与"每个键同时只跑一次尝试"的生命周期，而非协议本身。 | | `ctx.sessionTelemetry` | `seam` | [`session-telemetry`](../packages/session/session-telemetry) | [`session-telemetry-otel`](../packages/session/session-telemetry-otel) | - | - | 该 seam 捕获会话记录、进行脱敏并交给一个后端；没有其他组件消费该服务，其输出会离开当前进程。 | | `ctx.storage` | `seam` | [`storage`](../packages/storage/storage) | [`storage-json`](../packages/storage/storage-json), [`storage-sqlite`](../packages/storage/storage-sqlite) | [`storage-domain`](../packages/storage/storage-domain) | - | 各后端以不同名称并列注册；数据形态（领域优先）挂载到枢纽上，并将类型化操作转换为不透明的 KV 单元原语。 | -| `ctx.storageDomain` | `core` | [`storage-domain`](../packages/storage/storage-domain) | - | [`workspace`](../packages/workspace/workspace), [`message-feedback`](../packages/feedback/message-feedback) | - | 等待所有已配置后端就绪，然后将领域形态发布为一个受生命周期约束的服务，用于类型化持久状态。 | -| `ctx.messageFeedback` | `core` | [`message-feedback`](../packages/feedback/message-feedback) | - | - | - | 拥有本地逐 assistant 消息反馈、生命周期与目标校验、逐条目 compare-and-set 及 Host 一元 Remote 契约，且不进入 Session 历史或遥测。 | +| `ctx.storageDomain` | `core` | [`storage-domain`](../packages/storage/storage-domain) | - | [`workspace`](../packages/workspace/workspace) | - | 等待所有已配置后端就绪，然后将领域形态发布为一个受生命周期约束的服务，用于类型化持久状态。 | +| `ctx.messageFeedback` | `core` | [`message-feedback`](../packages/feedback/message-feedback) | - | - | - | 拥有权威 Session 日志中的逐 assistant 消息反馈、目标校验、逐条目 compare-and-set 及 Host 一元 Remote 契约。反馈不进入模型历史；日志导出遵循消费方策略。 | | `ctx.workspaceRegistry` | `core` | [`workspace`](../packages/workspace/workspace) | - | [`api-workspace-controller`](../packages/api/workspace-controller), [`api-session-controller`](../packages/api/session-controller) | - | 通过领域设施拥有带 WorkspaceId 品牌类型的记录；稳定的 sessionIds 账户驱动 Host RPC 与 GUI 投影。 | | `ctx.sessionQuery` | `seam` | [`session-query`](../packages/session-query/session-query) | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | [`session-reference`](../packages/context/session-reference), [`tool-session-query`](../packages/session-query/tool-session-query) | - | 该接口提供精确读取、过滤和追踪；具体后端还提供全文协调、排序、摘要片段和游标世代，而模型消费方负责工作区权限与不含游标的渲染。 | | `ctx.fileReferences` | `seam` | [`file-reference`](../packages/context/file-reference) | [`file-reference-local`](../packages/context/file-reference-local) | [`api-session-controller`](../packages/api/session-controller) | - | 该接口返回 Agent cwd 内仅含路径的补全候选；提供方负责命名空间访问与排序，但不读取文件内容。 | diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml index 33144f2d48..b4953ee587 100644 --- a/docs/config-catalog.i18n.yaml +++ b/docs/config-catalog.i18n.yaml @@ -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: 413228689d01794a1cc4e421b5e6d9f3021851f0 -config-catalog.zh.md: 44486d652aa754d1574854a2c1508c02201667f2 +config-catalog.md: 28fc6e327a14f6f2f41330f01becbcddf50eeb20 +config-catalog.zh.md: 49aad4a46eecb39001ec0b3d5c880fdcd74614d3 diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 413228689d..28fc6e327a 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -1515,7 +1515,7 @@ Source: [`packages/mcp/mcp-client/src/index.ts:98`](../packages/mcp/mcp-client/s ## `@deepseek-ai/dsh-message-feedback` -Requires: `storageDomain` · `sessionPersistence` · `sessions` +Requires: `sessionPersistence` · `sessions` ```ts config-catalog /** Required deployment policy for optional notes. */ @@ -1525,7 +1525,7 @@ export interface Config { } ``` -Source: [`packages/feedback/message-feedback/src/index.ts:50`](../packages/feedback/message-feedback/src/index.ts) +Source: [`packages/feedback/message-feedback/src/index.ts:39`](../packages/feedback/message-feedback/src/index.ts) diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md index 44486d652a..49aad4a46e 100644 --- a/docs/config-catalog.zh.md +++ b/docs/config-catalog.zh.md @@ -1517,7 +1517,7 @@ export interface ReconnectConfig { ## `@deepseek-ai/dsh-message-feedback` -需要：`storageDomain` · `sessionPersistence` · `sessions` +需要：`sessionPersistence` · `sessions` ```ts config-catalog /** Required deployment policy for optional notes. */ @@ -1527,7 +1527,7 @@ export interface Config { } ``` -来源：[`packages/feedback/message-feedback/src/index.ts:50`](../packages/feedback/message-feedback/src/index.ts) +来源：[`packages/feedback/message-feedback/src/index.ts:39`](../packages/feedback/message-feedback/src/index.ts) diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml index fac4831da7..672bca5416 100644 --- a/docs/module-graph.i18n.yaml +++ b/docs/module-graph.i18n.yaml @@ -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: 5286f8729930be0abc4c5f11325c93408915b808 -module-graph.zh.md: 0a43108841558b68f376f6129b8f52b8bed2c244 +module-graph.md: 8128e19e32a0afdf3061c26879cc34d43d736ef5 +module-graph.zh.md: 63a056c2a1b5c41a3d3fc7b3d4ab2813334354a4 diff --git a/docs/module-graph.md b/docs/module-graph.md index 5286f87299..8128e19e32 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -466,7 +466,6 @@ flowchart TD pkg_message_feedback --> pkg_llm pkg_message_feedback --> pkg_session pkg_message_feedback --> pkg_session_persistence - pkg_message_feedback --> pkg_storage_domain pkg_message_feedback --> pkg_typert_protocol pkg_sandbox_local --> pkg_llm pkg_sandbox_local --> pkg_sandbox @@ -657,7 +656,6 @@ flowchart TD pkg_command_feedback --> pkg_anonymous_user_id pkg_command_feedback --> pkg_commands pkg_command_feedback --> pkg_session - pkg_command_feedback --> pkg_session_telemetry pkg_permission_presets --> pkg_commands pkg_permission_presets --> pkg_invariants pkg_permission_presets --> pkg_sandbox @@ -1288,7 +1286,7 @@ flowchart TD | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) | | [`spill-local`](../packages/spill/spill-local) | `spill` | [`spill`](../packages/spill/spill) | | [`session-log-export`](../packages/session-query/session-log-export) | `session-query` | [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) | -| [`message-feedback`](../packages/feedback/message-feedback) | `feedback` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol) | +| [`message-feedback`](../packages/feedback/message-feedback) | `feedback` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`typert-protocol`](../packages/typert/protocol) | | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) | | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl) | `session` | [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) | | [`session-projection-cache`](../packages/session/session-projection-cache) | `session` | [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`storage-domain`](../packages/storage/storage-domain) | @@ -1331,7 +1329,7 @@ flowchart TD | [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) | | [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`compaction`](../packages/compaction/compaction) | `compaction` | [`brand`](../packages/util/brand), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | -| [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`commands`](../packages/interaction/commands), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) | +| [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`commands`](../packages/interaction/commands), [`session`](../packages/core/session) | | [`permission-presets`](../packages/interaction/permission-presets) | `interaction` | [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`shell`](../packages/shell/shell), [`user-approval`](../packages/interaction/user-approval) | | [`jobs-local`](../packages/jobs/jobs-local) | `jobs` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`scope`](../packages/core/scope), [`timeout`](../packages/util/timeout) | | [`session-title-llm`](../packages/session/session-title-llm) | `session` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`timeout`](../packages/util/timeout) | diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md index 0a43108841..63a056c2a1 100644 --- a/docs/module-graph.zh.md +++ b/docs/module-graph.zh.md @@ -468,7 +468,6 @@ flowchart TD pkg_message_feedback --> pkg_llm pkg_message_feedback --> pkg_session pkg_message_feedback --> pkg_session_persistence - pkg_message_feedback --> pkg_storage_domain pkg_message_feedback --> pkg_typert_protocol pkg_sandbox_local --> pkg_llm pkg_sandbox_local --> pkg_sandbox @@ -659,7 +658,6 @@ flowchart TD pkg_command_feedback --> pkg_anonymous_user_id pkg_command_feedback --> pkg_commands pkg_command_feedback --> pkg_session - pkg_command_feedback --> pkg_session_telemetry pkg_permission_presets --> pkg_commands pkg_permission_presets --> pkg_invariants pkg_permission_presets --> pkg_sandbox @@ -1290,7 +1288,7 @@ flowchart TD | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) | | [`spill-local`](../packages/spill/spill-local) | `spill` | [`spill`](../packages/spill/spill) | | [`session-log-export`](../packages/session-query/session-log-export) | `session-query` | [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) | -| [`message-feedback`](../packages/feedback/message-feedback) | `feedback` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol) | +| [`message-feedback`](../packages/feedback/message-feedback) | `feedback` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`typert-protocol`](../packages/typert/protocol) | | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) | | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl) | `session` | [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) | | [`session-projection-cache`](../packages/session/session-projection-cache) | `session` | [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`storage-domain`](../packages/storage/storage-domain) | @@ -1333,7 +1331,7 @@ flowchart TD | [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) | | [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`compaction`](../packages/compaction/compaction) | `compaction` | [`brand`](../packages/util/brand), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | -| [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`commands`](../packages/interaction/commands), [`session`](../packages/core/session), [`session-telemetry`](../packages/session/session-telemetry) | +| [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`commands`](../packages/interaction/commands), [`session`](../packages/core/session) | | [`permission-presets`](../packages/interaction/permission-presets) | `interaction` | [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`settings`](../packages/settings/settings), [`shell`](../packages/shell/shell), [`user-approval`](../packages/interaction/user-approval) | | [`jobs-local`](../packages/jobs/jobs-local) | `jobs` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`scope`](../packages/core/scope), [`timeout`](../packages/util/timeout) | | [`session-title-llm`](../packages/session/session-title-llm) | `session` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`timeout`](../packages/util/timeout) | diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml index 12e46151b8..3abb4e9658 100644 --- a/docs/persistence-catalog.i18n.yaml +++ b/docs/persistence-catalog.i18n.yaml @@ -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: 1505a188f065e7fdcc5c01e29730c1d751537442 -persistence-catalog.zh.md: 8d4b040c42ce3201012e0b548fd41f3b09bb4453 +persistence-catalog.md: 1111d72573fffb290929361fc48320fbe47bb497 +persistence-catalog.zh.md: 80cc19441eb151a28ade4110bd364e3efcbed384 diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md index 1505a188f0..1111d72573 100644 --- a/docs/persistence-catalog.md +++ b/docs/persistence-catalog.md @@ -403,6 +403,28 @@ Source: [`packages/compaction/compaction/src/types.ts:34`](../packages/compactio ### `feedback/*` + + +#### `feedback/message-delete` — log-only + +```ts persistence-catalog +/** Log-only deletion; earlier ratings and notes remain in the log. */ +'feedback/message-delete': MessageFeedbackDelete +``` + +Source: [`packages/feedback/message-feedback/src/types.ts:55`](../packages/feedback/message-feedback/src/types.ts) + + + +#### `feedback/message-put` — log-only + +```ts persistence-catalog +/** Log-only human feedback; never enters model history. */ +'feedback/message-put': MessageFeedbackPut +``` + +Source: [`packages/feedback/message-feedback/src/types.ts:53`](../packages/feedback/message-feedback/src/types.ts) + #### `feedback/record` — log-only @@ -415,7 +437,7 @@ Source: [`packages/compaction/compaction/src/types.ts:34`](../packages/compactio 'feedback/record': { text: string } ``` -Source: [`packages/feedback/command-feedback/src/index.ts:62`](../packages/feedback/command-feedback/src/index.ts) +Source: [`packages/feedback/command-feedback/src/index.ts:25`](../packages/feedback/command-feedback/src/index.ts) ### `goal/*` diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md index 8d4b040c42..80cc19441e 100644 --- a/docs/persistence-catalog.zh.md +++ b/docs/persistence-catalog.zh.md @@ -405,6 +405,28 @@ export type SessionEvent = { ### `feedback/*` + + +#### `feedback/message-delete` — log-only + +```ts persistence-catalog +/** Log-only deletion; earlier ratings and notes remain in the log. */ +'feedback/message-delete': MessageFeedbackDelete +``` + +来源： [`packages/feedback/message-feedback/src/types.ts:55`](../packages/feedback/message-feedback/src/types.ts) + + + +#### `feedback/message-put` — log-only + +```ts persistence-catalog +/** Log-only human feedback; never enters model history. */ +'feedback/message-put': MessageFeedbackPut +``` + +来源： [`packages/feedback/message-feedback/src/types.ts:53`](../packages/feedback/message-feedback/src/types.ts) + #### `feedback/record` — log-only @@ -417,7 +439,7 @@ export type SessionEvent = { 'feedback/record': { text: string } ``` -来源：[`packages/feedback/command-feedback/src/index.ts:62`](../packages/feedback/command-feedback/src/index.ts) +来源：[`packages/feedback/command-feedback/src/index.ts:25`](../packages/feedback/command-feedback/src/index.ts) ### `goal/*` diff --git a/docs/subsystems/feedback.i18n.yaml b/docs/subsystems/feedback.i18n.yaml index c78fd14493..48f540d8b5 100644 --- a/docs/subsystems/feedback.i18n.yaml +++ b/docs/subsystems/feedback.i18n.yaml @@ -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/subsystems/feedback.md -feedback.md: 0bb01315d74cc41c1ab1008144dd8fca84efd76a -feedback.zh.md: 46f382edd270e5bb557f304a2f770b5fe7791dc5 +feedback.md: e1f2d05435cb5e0fe09c315d4123c4621e4c7c68 +feedback.zh.md: 9ce5b44995302687a39a655bf019f623e8c8c7e7 diff --git a/docs/subsystems/feedback.md b/docs/subsystems/feedback.md index 0bb01315d7..e1f2d05435 100644 --- a/docs/subsystems/feedback.md +++ b/docs/subsystems/feedback.md @@ -2,7 +2,7 @@ English | [中文](feedback.zh.md) -[`@deepseek-ai/dsh-message-feedback`](../../packages/feedback/message-feedback) owns editable feedback for individual assistant messages. It is deliberately separate from the immutable Session-level `feedback/record` event: message feedback is a local storage-domain sidecar, not Session-log content or a projection, and it performs no telemetry handoff. +[`@deepseek-ai/dsh-message-feedback`](../../packages/feedback/message-feedback) owns editable feedback for individual assistant messages. The canonical Session log stores `feedback/message-put` and `feedback/message-delete`; the immutable Session-level remark remains `feedback/record`. All three are log-only events that never enter model context. Source: [`packages/feedback/message-feedback/src/types.ts`](../../packages/feedback/message-feedback/src/types.ts) @@ -36,10 +36,30 @@ interface MessageFeedbackItem { } ``` +```ts type-equiv +/** A material creation or edit, retaining its complete current value. */ +interface MessageFeedbackPut { + /** Owning Session; inherited feedback in a fork belongs to its parent. */ + readonly sessionId: SessionId + /** Value after this mutation, including the original creation time. */ + readonly item: MessageFeedbackItem +} +``` + +```ts type-equiv +/** A material deletion of one current feedback item. */ +interface MessageFeedbackDelete { + /** Session that owns the deleted feedback. */ + readonly sessionId: SessionId + /** Message whose feedback was removed. */ + readonly messageId: MessageId +} +``` + ```ts type-equiv /** Read all message feedback belonging to one persisted Session lifecycle. */ interface MessageFeedbackListRequest { - /** Persisted Session whose sidecar should be read. */ + /** Session whose feedback events should be read. */ readonly sessionId: SessionId } ``` @@ -71,7 +91,7 @@ interface MessageFeedbackPutRequest { ```ts type-equiv /** Delete feedback for one message after observing its current version. */ interface MessageFeedbackDeleteRequest { - /** Persisted Session that owns the sidecar. */ + /** Session that owns the feedback. */ readonly sessionId: SessionId /** Message whose feedback should be absent after this operation. */ readonly messageId: MessageId @@ -185,21 +205,23 @@ type MessageFeedbackDeleteResult = ## Data and concurrency -One Session sidecar row contains its header identity `{createdAt, cwd}` and feedback items keyed by `MessageId`. Each item carries a positive or negative rating, an optional note, Host-assigned `createdAt`/`updatedAt` timestamps, and its own opaque version. Versions are compared only for equality and only against the addressed message; callers do not order or synthesize them. +Current items are folded from canonical feedback events whose payload `sessionId` matches the owning Session. Each item carries a positive or negative rating, an optional note, Host-assigned `createdAt`/`updatedAt` timestamps, and its own opaque version. Versions are compared only for equality and only against the addressed message; callers do not order or synthesize them. -`put` uses strict optimistic concurrency: every request for an existing item must match its current `ifVersion`, including a no-op. A conflict returns the authoritative current item (or `null`), so a caller can reconcile a lost response or a concurrent edit without another read. Deleting an already absent item succeeds. A per-Session queue encloses inspection, read, conflict evaluation, and whole-row write, so these guarantees cover concurrent calls in one Host process. +`put` uses strict optimistic concurrency: every request for an existing item must match its current `ifVersion`, including a no-op. A conflict returns the authoritative current item (or `null`), so a caller can reconcile a lost response or a concurrent edit without another read. Deleting an already absent item succeeds. A per-Session queue serializes reads and mutations; cold mutations hold a persistence write handle across read, comparison, append, and flush. Matching no-ops append no event. ## Target and lifecycle authority -A live owner's in-memory log supplies the target Session observation directly; a cold target is read through a `SessionPersistence.open(id, 'read')` handle without publishing or resuming an Agent and without writing recovery. A `stat(id)` preflight classifies definite absence; a read failure for a Session `stat` confirmed propagates as infrastructure failure. `put` accepts only a non-empty, append-origin `assistant/message` with the requested `MessageId`; replacement-origin, usage-only empty, and non-assistant records are not feedback targets. +A live owner's in-memory log supplies the target Session observation directly; cold reads use a `SessionPersistence.open(id, 'read')` handle, while mutations use a write handle. Neither path constructs a Session or Agent. A `stat(id)` preflight classifies definite absence; a read failure for a Session `stat` confirmed propagates as infrastructure failure. `put` accepts only a non-empty, append-origin `assistant/message` with the requested `MessageId`; replacement-origin, usage-only empty, and non-assistant records are not feedback targets. -The stored `{createdAt, cwd}` identity must match the inspected header. A mismatch is treated as absence: `list` returns no items, while `put` may replace the stale row with one bound to the current header identity. Forks use a new Session identity and receive no sidecar copy even when their seed contains the same messages. +Fork seeds can contain parent feedback events, but their payload retains the parent `sessionId`, so they do not become current feedback for the child. Deleting an item appends a tombstone; earlier ratings and notes remain in the log. ## Persistence and Remote contract -The service stores whole Session rows in the `message_feedback` storage domain through `ctx.storageDomain`. Before `put` commits a row that references a target message, a matching live target passes through the canonical `ctx.sessions.flush` checkpoint; both live and cold paths are then physically read from sequence zero through a fresh read handle, which observes at least the flushed prefix by the seam's freshness guarantee. The resulting observation is revalidated before the sidecar write, so the durable target log always precedes its sidecar commit. `maxNoteBytes` is required and bounds note text by UTF-8 bytes; the Web Host composition sets `8192`. The package publishes the Host `messageFeedback.list`, `messageFeedback.put`, and `messageFeedback.delete` unary Remote contract through `TypertRemoteService` and `@Remote`; the generated Cordis API below is the method-level authority. +Successful message-feedback mutations await canonical persistence: live operations append through the owning Session and require a participating `ctx.sessions.flush` listener; cold operations append and flush through their write handle. Persistence failures propagate rather than reporting success. `maxNoteBytes` is required and bounds note text by UTF-8 bytes; the Web Host composition sets `8192`. The package publishes the Host `messageFeedback.list`, `messageFeedback.put`, and `messageFeedback.delete` unary Remote contract through `TypertRemoteService` and `@Remote`; the generated Cordis API below is the method-level authority. -Plugin disposal closes mutation admission, drains accepted per-Session queue work, and then closes the storage domain. +Plugin disposal closes operation admission and drains accepted per-Session queue work. + +When explicitly enabled, [`session-log-deepseek`](../../packages/session/session-log-deepseek/README.md) carries feedback as part of the ordinary `dsh_session_log` suffix on subsequent eligible DeepSeek requests. Recording feedback does not trigger a request or a separate `dsh_feedback` upload. The command acknowledgement confirms recording and identifies the Session and anonymous user; it reports neither telemetry policy nor delivery. ## Web surface @@ -211,14 +233,13 @@ One `MessageFeedbackController` per Session backs every message control in that ## Boundaries and limitations -- The mutation queue is process-local. Storage-domain has no cross-process conditional write, so multiple Host writers to one storage root have no compare-and-swap or lost-update guarantee. -- Session persistence has no durable deletion API. The service does not treat `session/disposed` or `api-session/removed` as deletion and therefore performs no fake cascade; orphan sidecar rows may remain after out-of-band log removal. +- The operation queue is process-local; cold writer exclusion relies on the selected persistence provider. +- Deletion removes the current item, not earlier note text from the append-only log or an already delivered suffix. - A request in the narrow interval after live detach but before the persistence catalog materializes the header can receive `session-not-found`; callers retry after retirement materialization. -- Cold requests scan the complete Session snapshot catalog because persistence has no lookup-by-id metadata operation. One Session row also has no item-count or aggregate-byte cap; `maxNoteBytes` bounds only each note until a concrete consumer owns a row policy. -- Header identity detects a reused id only when `{createdAt, cwd}` differs; a cloned log retaining the same header identity is indistinguishable by this contract. +- Cold requests read the complete log; the service has no item-count or aggregate-byte cap. `maxNoteBytes` bounds only each note. - The Host contract records no authenticated actor or audit identity and therefore assumes a trusted caller boundary. - The Web controls appear in the chat view only. The trajectory and waterfall views render no feedback entry even though their assistant nodes carry the same `messageId`. -- The sidecar publishes no live frames, so a second tab's rating becomes visible on reconnect or on the next conflict reply rather than immediately. +- The Web controller does not consume feedback log events, so a second tab's rating becomes visible on reconnect or on the next conflict reply rather than immediately. - The note editor does not pre-check `maxNoteBytes`; an oversized note fails on save with `note-too-large` rather than while typing. @@ -233,31 +254,28 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp ### `ctx.messageFeedback` — `MessageFeedbackService` -Storage-domain sidecar service. It inspects persisted Session history and never creates or resumes an Agent or Session. +Session-log service; cold operations never construct a Session or Agent. ```ts cordis-catalog /** - * Read feedback belonging to the current persisted Session lifecycle. - * A stale row from a reused Session id is invisible. - * @param request - Session identity to inspect and list. - * @returns current immutable items or `session-not-found`. + * Read current feedback from the canonical log. + * @param request - Session to inspect. + * @returns immutable items or a definite persistence miss. */ -@Remote('list') async list(request: MessageFeedbackListRequest): Promise +@Remote('list') list(request: MessageFeedbackListRequest): Promise /** - * Create or replace feedback for one derived append-origin assistant - * message. Every request must match the addressed item's current version; - * a matching no-op returns the stored item without changing its revision. - * @param request - target, desired value, and observed item version. - * @returns the committed item or an explicit business failure. + * Create or replace feedback after checking its current version. + * Matching no-ops retain the version and append no event. + * @param request - Target, desired value, and observed item version. + * @returns the durable item or an explicit business failure. */ @Remote('put') put(request: MessageFeedbackPutRequest): Promise /** - * Delete one feedback item. Absence is successful regardless of the - * supplied version; an existing item requires an exact version match. + * Delete one item after checking its version; absence succeeds without an event. * @param request - Session, message, and observed item version. - * @returns the stable absent postcondition, or an explicit failure. + * @returns the stable absent postcondition or an explicit failure. */ @Remote('delete') delete(request: MessageFeedbackDeleteRequest): Promise ``` diff --git a/docs/subsystems/feedback.zh.md b/docs/subsystems/feedback.zh.md index 46f382edd2..9ce5b44995 100644 --- a/docs/subsystems/feedback.zh.md +++ b/docs/subsystems/feedback.zh.md @@ -2,7 +2,7 @@ [English](feedback.md) | 中文 -[`@deepseek-ai/dsh-message-feedback`](../../packages/feedback/message-feedback)拥有针对单条 assistant 消息的可编辑反馈。它刻意与不可变的 Session 级 `feedback/record` 事件分离：message feedback 是本地 storage-domain 伴随记录（sidecar），不是 Session 日志内容或投影，也不执行遥测交接。 +[`@deepseek-ai/dsh-message-feedback`](../../packages/feedback/message-feedback)拥有针对单条 assistant 消息的可编辑反馈。权威 Session 日志保存 `feedback/message-put` 和 `feedback/message-delete`；不可变的 Session 级备注仍使用 `feedback/record`。三者都是仅写日志的事件，绝不进入模型上下文。 来源：[`packages/feedback/message-feedback/src/types.ts`](../../packages/feedback/message-feedback/src/types.ts) @@ -36,10 +36,30 @@ interface MessageFeedbackItem { } ``` +```ts type-equiv +/** A material creation or edit, retaining its complete current value. */ +interface MessageFeedbackPut { + /** Owning Session; inherited feedback in a fork belongs to its parent. */ + readonly sessionId: SessionId + /** Value after this mutation, including the original creation time. */ + readonly item: MessageFeedbackItem +} +``` + +```ts type-equiv +/** A material deletion of one current feedback item. */ +interface MessageFeedbackDelete { + /** Session that owns the deleted feedback. */ + readonly sessionId: SessionId + /** Message whose feedback was removed. */ + readonly messageId: MessageId +} +``` + ```ts type-equiv /** Read all message feedback belonging to one persisted Session lifecycle. */ interface MessageFeedbackListRequest { - /** Persisted Session whose sidecar should be read. */ + /** Session whose feedback events should be read. */ readonly sessionId: SessionId } ``` @@ -71,7 +91,7 @@ interface MessageFeedbackPutRequest { ```ts type-equiv /** Delete feedback for one message after observing its current version. */ interface MessageFeedbackDeleteRequest { - /** Persisted Session that owns the sidecar. */ + /** Session that owns the feedback. */ readonly sessionId: SessionId /** Message whose feedback should be absent after this operation. */ readonly messageId: MessageId @@ -185,21 +205,23 @@ type MessageFeedbackDeleteResult = ## 数据与并发 -每个 Session 的一条伴随记录包含 header 身份 `{createdAt, cwd}` 和以 `MessageId` 为键的反馈条目。每个条目携带好评或差评、可选备注、Host 分配的 `createdAt`/`updatedAt` 时间戳及自己的 opaque version。version 只能用于相等比较，且只与目标消息比较；调用方不能排序或自行合成它。 +当前条目由 payload 中 `sessionId` 与所属 Session 匹配的权威反馈事件归约得到。每个条目携带好评或差评、可选备注、Host 分配的 `createdAt`/`updatedAt` 时间戳及自己的 opaque version。version 只能用于相等比较，且只与目标消息比较；调用方不能排序或自行合成它。 -`put` 采用严格乐观并发：已有条目的每次请求都必须匹配当前 `ifVersion`，即使请求不会改变目标值。冲突会返回权威当前条目（不存在时为 `null`），因此调用方无需额外读取，即可协调丢失响应或并发编辑。删除已经不存在的条目同样成功。按 Session 划分的队列覆盖检查、读取、冲突判断与整行写入，因此这些保证适用于单个 Host 进程中的并发调用。 +`put` 采用严格乐观并发：已有条目的每次请求都必须匹配当前 `ifVersion`，即使请求不会改变目标值。冲突会返回权威当前条目（不存在时为 `null`），因此调用方无需额外读取，即可协调丢失响应或并发编辑。删除已经不存在的条目同样成功。按 Session 划分的队列串行执行读取与变更；cold 变更在读取、比较、追加和 flush 期间持有持久化写句柄。匹配版本的无变更操作不追加事件。 ## 目标与生命周期权威 -live 持有者的内存日志直接提供目标 Session 的观测；cold 目标则通过 `SessionPersistence.open(id, 'read')` 句柄读取，既不会发布或恢复 Agent，也不会写入恢复内容。先由 `stat(id)` 预检明确不存在；`stat` 已确认存在的 Session 若读取失败，会按基础设施故障原样传播。`put` 只接受具有指定 `MessageId` 的非空、append-origin `assistant/message`；replacement-origin、仅承载 usage 的空记录和非 assistant 记录都不是反馈目标。 +live 持有者的内存日志直接提供目标 Session 的观测；cold 读取使用 `SessionPersistence.open(id, 'read')` 句柄，变更则使用写句柄。两条路径都不构造 Session 或 Agent。先由 `stat(id)` 预检明确不存在；`stat` 已确认存在的 Session 若读取失败，会按基础设施故障原样传播。`put` 只接受具有指定 `MessageId` 的非空、append-origin `assistant/message`；replacement-origin、仅承载 usage 的空记录和非 assistant 记录都不是反馈目标。 -存储的 `{createdAt, cwd}` 身份必须与检查所得 header 匹配。不匹配按不存在处理：`list` 返回空条目，`put` 则可用绑定当前 header 身份的新记录替换陈旧行。fork 使用新的 Session 身份，即使种子包含相同消息，也不获得伴随记录副本。 +fork 种子可以包含父 Session 的反馈事件，但 payload 保留父级 `sessionId`，因此不会成为子 Session 的当前反馈。删除条目会追加删除标记；早先的评分与备注仍保留在日志中。 ## 持久化与 Remote 约定 -服务通过 `ctx.storageDomain` 在 `message_feedback` 存储域中保存完整 Session 行。`put` 提交引用目标消息的伴随记录前，身份匹配的 live 目标先经过权威 `ctx.sessions.flush` checkpoint；随后 live 与 cold 路径都会通过一个新开的读句柄从序列零做物理复读，依据该 seam 的新鲜度保证，它至少能观察到已 flush 的前缀。写入伴随记录前会再次校验所得观测，因此目标日志的持久提交始终先于其伴随记录。`maxNoteBytes` 为必填项，按 UTF-8 字节限制备注文本；Web Host 组合将其设为 `8192`。该包通过 `TypertRemoteService` 与 `@Remote` 发布 Host `messageFeedback.list`、`messageFeedback.put` 和 `messageFeedback.delete` 一元 Remote 约定；下方生成的 Cordis API 是方法级权威。 +成功的消息反馈变更会等待权威持久化完成：live 操作通过所属 Session 追加，并要求有 `ctx.sessions.flush` 监听器参与；cold 操作通过写句柄追加并 flush。持久化故障会原样传播，不会报告成功。`maxNoteBytes` 为必填项，按 UTF-8 字节限制备注文本；Web Host 组合将其设为 `8192`。该包通过 `TypertRemoteService` 与 `@Remote` 发布 Host `messageFeedback.list`、`messageFeedback.put` 和 `messageFeedback.delete` 一元 Remote 约定；下方生成的 Cordis API 是方法级权威。 -Plugin disposal 会先关闭变更接纳，排空已进入各 Session 队列的工作，然后才关闭 storage domain。 +插件释放会关闭操作接纳，并排空已进入各 Session 队列的工作。 + +显式启用后，[`session-log-deepseek`](../../packages/session/session-log-deepseek/README.zh.md) 会在后续符合条件的 DeepSeek 请求中，把反馈作为普通 `dsh_session_log` 后缀的一部分传送。记录反馈不会触发请求，也不会单独上传 `dsh_feedback`。命令确认文本确认记录并标识 Session 与匿名用户，不报告遥测策略或投递结果。 ## Web 界面 @@ -211,14 +233,13 @@ Plugin disposal 会先关闭变更接纳，排空已进入各 Session 队列的 ## 边界与限制 -- 变更队列仅在进程内生效。storage-domain 没有跨进程条件写，因此多个 Host 写入同一存储根目录时，不提供 compare-and-swap 或防止丢失更新的保证。 -- Session persistence 没有持久删除接口。服务不把 `session/disposed` 或 `api-session/removed` 当作删除，因此不伪造级联；在带外移除日志后，孤儿伴随记录可能继续存在。 +- 操作队列仅在进程内生效；cold 写入排他性依赖所选持久化提供方。 +- 删除只移除当前条目，不会抹除 append-only 日志或已投递后缀中的早先备注。 - 请求若恰好落在 live detach 之后、persistence catalog 物化 header 之前的极短窗口，可能收到 `session-not-found`；调用方应在 retirement materialization 后重试。 -- 由于 persistence 没有按 id 读取元数据的操作，cold 请求会扫描完整的 Session snapshot 目录。单个 Session 行也没有条目数或聚合字节上限；在具体消费方拥有行策略之前，`maxNoteBytes` 只限制每条备注。 -- 只有 `{createdAt, cwd}` 不同时，header 身份才能识别复用的 id；本约定无法区分保留相同 header 身份的克隆日志。 +- cold 请求读取完整日志；服务没有条目数或聚合字节上限。`maxNoteBytes` 只限制每条备注。 - Host 约定不记录已认证的 actor 或审计身份，因此假设调用方边界可信。 - Web 控件只出现在对话视图。trajectory 与 waterfall 视图不渲染反馈条目，尽管它们的助手节点携带相同的 `messageId`。 -- 该 sidecar 不发布实时帧，因此另一个标签页的评分要等到重连或下一次冲突响应才可见，不会立即出现。 +- Web 控制器不消费反馈日志事件，因此另一个标签页的评分要等到重连或下一次冲突响应才可见，不会立即出现。 - 备注编辑器不预先校验 `maxNoteBytes`；超长备注在保存时以 `note-too-large` 失败，而不是在输入过程中。 @@ -233,31 +254,28 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp ### `ctx.messageFeedback` — `MessageFeedbackService` -Storage-domain sidecar service. It inspects persisted Session history and never creates or resumes an Agent or Session. +Session-log service; cold operations never construct a Session or Agent. ```ts cordis-catalog /** - * Read feedback belonging to the current persisted Session lifecycle. - * A stale row from a reused Session id is invisible. - * @param request - Session identity to inspect and list. - * @returns current immutable items or `session-not-found`. + * Read current feedback from the canonical log. + * @param request - Session to inspect. + * @returns immutable items or a definite persistence miss. */ -@Remote('list') async list(request: MessageFeedbackListRequest): Promise +@Remote('list') list(request: MessageFeedbackListRequest): Promise /** - * Create or replace feedback for one derived append-origin assistant - * message. Every request must match the addressed item's current version; - * a matching no-op returns the stored item without changing its revision. - * @param request - target, desired value, and observed item version. - * @returns the committed item or an explicit business failure. + * Create or replace feedback after checking its current version. + * Matching no-ops retain the version and append no event. + * @param request - Target, desired value, and observed item version. + * @returns the durable item or an explicit business failure. */ @Remote('put') put(request: MessageFeedbackPutRequest): Promise /** - * Delete one feedback item. Absence is successful regardless of the - * supplied version; an existing item requires an exact version match. + * Delete one item after checking its version; absence succeeds without an event. * @param request - Session, message, and observed item version. - * @returns the stable absent postcondition, or an explicit failure. + * @returns the stable absent postcondition or an explicit failure. */ @Remote('delete') delete(request: MessageFeedbackDeleteRequest): Promise ``` diff --git a/packages/bundle/base/README.i18n.yaml b/packages/bundle/base/README.i18n.yaml index 455bd870bf..92c6908053 100644 --- a/packages/bundle/base/README.i18n.yaml +++ b/packages/bundle/base/README.i18n.yaml @@ -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/bundle/base/README.md -README.md: 0995f5bc69905e643a117c1f5a833be0f114cdc6 -README.zh.md: c1d180f2dd85d6767f197b561b46f722d653d4fc +README.md: cfc5bd2b0e0951909f7616bf0011e2ffe1f3ddb8 +README.zh.md: 326ea6b122ec878a99db1cc93fd1dcb344941256 diff --git a/packages/bundle/base/README.md b/packages/bundle/base/README.md index 0995f5bc69..cfc5bd2b0e 100644 --- a/packages/bundle/base/README.md +++ b/packages/bundle/base/README.md @@ -47,7 +47,7 @@ Run `dsh --profile my-profile "your task"` and you get a working agent with mode ### What you get -Out of the box, every profile built on this core provides: a DeepSeek model connection (the provider and model are configurable, and you can enable extra providers from your settings), the full tool set — file editing, shell commands, web search, public HTTP(S) fetch, subagents, task and goal tracking — durable sessions that survive restarts, and the default permission policy that confines file writes to your workspace and asks before risky actions. Web fetch runs without per-call approval; its provider rejects non-public destinations. Telemetry stays off unless you opt in. +Out of the box, every profile built on this core provides: a DeepSeek model connection (the provider and model are configurable, and you can enable extra providers from your settings), the full tool set — file editing, shell commands, web search, public HTTP(S) fetch, subagents, task and goal tracking — durable sessions that survive restarts, and the default permission policy that confines file writes to your workspace and asks before risky actions. Web fetch runs without per-call approval; its provider rejects non-public destinations. Feedback stays in the Session log. The opt-in [DeepSeek session-log contributor](../../session/session-log-deepseek/README.md) carries it with model requests; the OTel session-upload row is disabled. ### Shell tools per platform diff --git a/packages/bundle/base/README.zh.md b/packages/bundle/base/README.zh.md index c1d180f2dd..326ea6b122 100644 --- a/packages/bundle/base/README.zh.md +++ b/packages/bundle/base/README.zh.md @@ -47,7 +47,7 @@ kind: "package-bundle" ### 你得到什么 -开箱即用，基于本核心构建的每个 profile 都提供：DeepSeek 模型连接（provider 与模型可配置，你还可以在设置中启用额外 provider）、完整工具集——文件编辑、shell 命令、web 搜索、公开 HTTP(S) 抓取、subagent、任务与目标跟踪——可跨重启存活的持久会话，以及默认权限策略：把文件写入限制在工作区内，危险操作前征询许可。Web 抓取无需逐次审批，其提供方会拒绝非公开目的地址。遥测默认关闭，除非你主动开启。 +开箱即用，基于本核心构建的每个 profile 都提供：DeepSeek 模型连接（provider 与模型可配置，你还可以在设置中启用额外 provider）、完整工具集——文件编辑、shell 命令、web 搜索、公开 HTTP(S) 抓取、subagent、任务与目标跟踪——可跨重启存活的持久会话，以及默认权限策略：把文件写入限制在工作区内，危险操作前征询许可。Web 抓取无需逐次审批，其提供方会拒绝非公开目的地址。反馈保存在会话日志中。需主动开启的 [DeepSeek 会话日志贡献器](../../session/session-log-deepseek/README.zh.md)随模型请求发送日志；OTel 会话上传行处于禁用状态。 ### 各平台的 shell 工具 diff --git a/packages/bundle/base/cordis.patch.yml b/packages/bundle/base/cordis.patch.yml index 94b5d23204..0628406ad1 100644 --- a/packages/bundle/base/cordis.patch.yml +++ b/packages/bundle/base/cordis.patch.yml @@ -140,7 +140,7 @@ # Durable KV storage: the storage hub, the json backend, and the # schema-validated domain form over them. Session-layer persistence (the - # projection cache below; workspace and message-feedback in web layers) + # projection cache below; workspace in web layers) # routes through this stack, so it belongs to the shared base. - id: storage name: '@deepseek-ai/dsh-storage' @@ -165,14 +165,8 @@ writeEveryEvents: 200 writeIntervalMs: 5000 - # Session telemetry defaults to feedback-gated sharing: FEEDBACK_ONLY - # uploads only when the user records /feedback, releasing the session - # records since the last handoff through that event (a resumed session - # shares only its current lifecycle). DSH_TELEMETRY_MODE overrides to - # FULL or DISABLED; uploading mirrors session-log records onto OTLP/HTTP - # logs with no session-telemetry/record redaction rule, so exports are - # the raw captured copy. The deployment stance, env seams, and follow-ups - # are pinned in the feedback-gated-default Agent Note. + # OTel session upload is disabled. Session-log sharing uses the opt-in + # session-log-deepseek contributor on DeepSeek requests. # DSH_TELEMETRY_OTLP_URL overrides the production endpoint. A non-empty # DSH_TELEMETRY_DISABLED — any value, including '0'/'false' — opts the # process out (the launchers patch the row disabled; config cannot disable @@ -189,6 +183,7 @@ # on SIGINT/SIGTERM. - id: session-telemetry-otel name: '@deepseek-ai/dsh-session-telemetry-otel' + disabled: true config: mode: !!js process.env.DSH_TELEMETRY_MODE || 'FEEDBACK_ONLY' shutdownTimeoutMillis: 3000 diff --git a/packages/bundle/base/tests/base.spec.ts b/packages/bundle/base/tests/base.spec.ts index a260c39760..a0fbafd69b 100644 --- a/packages/bundle/base/tests/base.spec.ts +++ b/packages/bundle/base/tests/base.spec.ts @@ -32,6 +32,7 @@ describe('dsh-base bundle', () => { ) expect(rows.length).toBeGreaterThan(50) expect(rows.some(row => row.id === 'agent-loop')).toBe(true) + expect(rows.find(row => row.id === 'session-telemetry-otel')?.disabled).toBe(true) expect(rows.find(row => row.id === 'session-telemetry-otel')?.config?.['mode']).toEqual({ __jsExpr: "process.env.DSH_TELEMETRY_MODE || 'FEEDBACK_ONLY'", }) diff --git a/packages/client/ui-message-feedback/README.i18n.yaml b/packages/client/ui-message-feedback/README.i18n.yaml index 06d31edb7f..6570ef5e3e 100644 --- a/packages/client/ui-message-feedback/README.i18n.yaml +++ b/packages/client/ui-message-feedback/README.i18n.yaml @@ -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/client/ui-message-feedback/README.md -README.md: 58e3bd3eeae2f5701a23dc3bdf7da94f72acfbba -README.zh.md: f04fda4f038c2c301b21a2332f4c20ce776a629c +README.md: 171a812acc836eec243eb9f596270359c0a3aa9c +README.zh.md: e34eba9014779fc27bbd5a7ef071a086e8982f45 diff --git a/packages/client/ui-message-feedback/README.md b/packages/client/ui-message-feedback/README.md index 58e3bd3eea..171a812acc 100644 --- a/packages/client/ui-message-feedback/README.md +++ b/packages/client/ui-message-feedback/README.md @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -This package adds per-message feedback to the Web GUI: a Like/Dislike pair plus an optional note, contributed as the `feedback` entry of the finalized assistant message's action strip. It renders on the closing assistant message of each turn — earlier steps of a multi-step turn produce tool rows rather than a rateable body. One controller per Session backs every message control in that Session, so a single list read seeds the whole transcript. Feedback is a sidecar: ratings and notes never enter the session log, the model context, or telemetry. +This package adds per-message feedback to the Web GUI: a Like/Dislike pair plus an optional note, contributed as the `feedback` entry of the finalized assistant message's action strip. It renders on the closing assistant message of each turn — earlier steps of a multi-step turn produce tool rows rather than a rateable body. One controller per Session backs every message control in that Session, so a single list read seeds the whole transcript. Ratings and notes are log-only Session events: they never enter model context. Deletion retracts the current item without erasing its earlier log entries. ## Table of Contents @@ -48,9 +48,9 @@ The package contributes the `feedback` entry (order 10) of `conversation.chat.as ## Further Exploration -Read these pages when the feedback surface is not enough. They move from the browser strip to the sidecar backend and the conversation shell. +Read these pages when the feedback surface is not enough. They move from the browser strip to the Session-log backend and the conversation shell. -- [dsh-message-feedback](../../feedback/message-feedback/README.md) — the sidecar backend that owns per-item compare-and-set. +- [dsh-message-feedback](../../feedback/message-feedback/README.md) — the Session-log backend that owns per-item compare-and-set and persistence. - [ui-conversation](../ui-conversation/README.md) — declares the assistant-actions strip and renders the action row. - [Client package map](../README.md) — adjacent browser UI packages. @@ -59,11 +59,11 @@ Read these pages when the feedback surface is not enough. They move from the bro ## Model Experience -None, as feedback is a sidecar that never enters the append-only Session log, the model context, or telemetry; no rating or note is ever visible to the model. +None, as ratings and notes are log-only events, not model input. Optional Session-log delivery uses request metadata rather than model context. #### KV Cache effect -None; no feedback mutation touches the history tail. +None; feedback mutations leave the model-visible history unchanged. ## Known Limitations and Deferred Work @@ -73,7 +73,7 @@ None; no feedback mutation touches the history tail. These limits define the current feedback surface. They are current package constraints, not a general rating comparison or a task backlog. - **Note size is a Host policy** — the deployment configures `maxNoteBytes` (8192 in the Web bundle) and the Host rejects an oversized note with `note-too-large`. The editor does not pre-check the limit, so an oversized note fails on save rather than while typing. -- **No cross-tab push** — a second tab's rating becomes visible on reconnect or on the next conflict reply, not immediately; the sidecar publishes no live frames. +- **No cross-tab push** — a second tab's rating becomes visible on reconnect or on the next conflict reply, not immediately; the controller does not consume feedback log events. - **Chat view only** — the trajectory and waterfall views render no feedback controls even though their assistant nodes carry the same `messageId`. diff --git a/packages/client/ui-message-feedback/README.zh.md b/packages/client/ui-message-feedback/README.zh.md index f04fda4f03..e34eba9014 100644 --- a/packages/client/ui-message-feedback/README.zh.md +++ b/packages/client/ui-message-feedback/README.zh.md @@ -9,7 +9,7 @@ kind: "package-reference" ## 概述 -本包为 Web GUI 增加逐消息反馈：一对 Like/Dislike 按钮加一个可选备注，作为已定稿助手消息动作条的 `feedback` 条目贡献。它渲染在每个轮次的收尾助手消息上——多步骤轮次中较早的步骤产出工具行而非可评分正文。每个 Session 一个控制器支撑该 Session 内所有消息的控件，因此一次列表读取即可填充整段对话。反馈是 sidecar：评分与备注绝不进入会话日志、模型上下文或遥测。 +本包为 Web GUI 增加逐消息反馈：一对 Like/Dislike 按钮加一个可选备注，作为已定稿助手消息动作条的 `feedback` 条目贡献。它渲染在每个轮次的收尾助手消息上——多步骤轮次中较早的步骤产出工具行而非可评分正文。每个 Session 一个控制器支撑该 Session 内所有消息的控件，因此一次列表读取即可填充整段对话。评分与备注是仅写日志的 Session 事件：它们绝不进入模型上下文。删除会撤回当前条目，但不会抹除早先的日志记录。 ## 目录 @@ -48,9 +48,9 @@ kind: "package-reference" ## 进一步探索 -当反馈面不够用时阅读以下页面。它们从浏览器条带进入 sidecar 后端与会话外壳。 +当反馈面不够用时阅读以下页面。它们从浏览器条带进入 Session 日志后端与会话外壳。 -- [dsh-message-feedback](../../feedback/message-feedback/README.zh.md)——拥有按条目比较并交换的 sidecar 后端。 +- [dsh-message-feedback](../../feedback/message-feedback/README.zh.md)——拥有按条目比较并交换与持久化的 Session 日志后端。 - [ui-conversation](../ui-conversation/README.zh.md)——声明助手动作条并渲染动作行。 - [客户端包映射](../README.zh.md)——相邻的浏览器 UI 包。 @@ -59,11 +59,11 @@ kind: "package-reference" ## 模型体验 -无。反馈是 sidecar，不进入 append-only 的 Session 日志、模型上下文或遥测；任何评分与备注对模型都不可见。 +无。评分与备注是仅写日志的事件，不是模型输入。可选的 Session 日志投递使用请求元数据，而非模型上下文。 #### KV Cache 影响 -无；任何反馈变更都不触碰历史尾部。 +无；反馈变更不改变模型可见的历史。 ## 已知限制与延期工作 @@ -73,7 +73,7 @@ kind: "package-reference" 这些限制界定了当前反馈表面。它们是当前包约束，不是通用评分对比或任务积压。 - **备注大小是宿主策略**——部署方配置 `maxNoteBytes`（Web bundle 中为 8192），超长备注由宿主以 `note-too-large` 拒绝。编辑器不预先校验该上限，因此超长备注在保存时才失败，而不是在输入过程中。 -- **无跨标签页推送**——另一个标签页的评分要等到重连或下一次冲突响应才可见，不会立即出现；该 sidecar 不发布实时帧。 +- **无跨标签页推送**——另一个标签页的评分要等到重连或下一次冲突响应才可见，不会立即出现；控制器不消费反馈日志事件。 - **仅限对话视图**——trajectory 与 waterfall 视图不渲染反馈控件，尽管它们的助手节点也带有相同的 `messageId`。 diff --git a/packages/core/session/src/known-event-types.ts b/packages/core/session/src/known-event-types.ts index 6fc390220a..3bc31ec32d 100644 --- a/packages/core/session/src/known-event-types.ts +++ b/packages/core/session/src/known-event-types.ts @@ -33,6 +33,8 @@ export const KNOWN_SESSION_EVENT_TYPES: ReadonlySet = new Set([ 'compaction/prune', 'compaction/start', 'compaction/summary', + 'feedback/message-delete', + 'feedback/message-put', 'feedback/record', 'goal/change', 'hook/invoked', diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index 0ebb3f6692..3c15e6c8f8 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -1306,26 +1306,26 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ }, { key: 'messageFeedback', - summary: 'Storage-domain sidecar service.', - description: 'Storage-domain sidecar service. It inspects persisted Session history and never creates or resumes an Agent or Session.', + summary: 'Session-log service; cold operations never construct a Session or Agent.', + description: 'Session-log service; cold operations never construct a Session or Agent.', methods: [ { - signature: '@Remote(\'list\') async list(request: MessageFeedbackListRequest): Promise', - description: 'Read feedback belonging to the current persisted Session lifecycle. A stale row from a reused Session id is invisible.', - parameters: [{ name: 'request', description: 'Session identity to inspect and list.' }], - returns: 'current immutable items or `session-not-found`.', + signature: '@Remote(\'list\') list(request: MessageFeedbackListRequest): Promise', + description: 'Read current feedback from the canonical log.', + parameters: [{ name: 'request', description: 'Session to inspect.' }], + returns: 'immutable items or a definite persistence miss.', }, { signature: '@Remote(\'put\') put(request: MessageFeedbackPutRequest): Promise', - description: 'Create or replace feedback for one derived append-origin assistant message. Every request must match the addressed item\'s current version; a matching no-op returns the stored item without changing its revision.', - parameters: [{ name: 'request', description: 'target, desired value, and observed item version.' }], - returns: 'the committed item or an explicit business failure.', + description: 'Create or replace feedback after checking its current version. Matching no-ops retain the version and append no event.', + parameters: [{ name: 'request', description: 'Target, desired value, and observed item version.' }], + returns: 'the durable item or an explicit business failure.', }, { signature: '@Remote(\'delete\') delete(request: MessageFeedbackDeleteRequest): Promise', - description: 'Delete one feedback item. Absence is successful regardless of the supplied version; an existing item requires an exact version match.', + description: 'Delete one item after checking its version; absence succeeds without an event.', parameters: [{ name: 'request', description: 'Session, message, and observed item version.' }], - returns: 'the stable absent postcondition, or an explicit failure.', + returns: 'the stable absent postcondition or an explicit failure.', }, ], }, diff --git a/packages/feedback/command-feedback/README.i18n.yaml b/packages/feedback/command-feedback/README.i18n.yaml index bc1c579e0e..20606fc8ce 100644 --- a/packages/feedback/command-feedback/README.i18n.yaml +++ b/packages/feedback/command-feedback/README.i18n.yaml @@ -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/feedback/command-feedback/README.md -README.md: 92ba5d28eb5602ef063216ca15967495857737f7 -README.zh.md: 338d6884003d39f0379536a0917b0c3322f47574 +README.md: 83cb5b759431607a1702b2cc3038532d47db2d32 +README.zh.md: 493ddf72b3b22454773dedcfbdd7d6910bf41e02 diff --git a/packages/feedback/command-feedback/README.md b/packages/feedback/command-feedback/README.md index 92ba5d28eb..83cb5b7594 100644 --- a/packages/feedback/command-feedback/README.md +++ b/packages/feedback/command-feedback/README.md @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -`dsh-command-feedback` lets a user tell the harness what they think of a session: type `/feedback` plus a remark, and the remark is recorded and acknowledged. Recording is immediate and never starts model work, so it is safe at any point in a conversation — the model neither sees the remark nor is interrupted by it. The acknowledgement names the session and the anonymous user, and reports how the session is shared under the deployment's telemetry policy. The command ships with the Web client and needs no configuration; headless, ACP, and JSON-RPC entry points do not provide slash commands and cannot run it. +`dsh-command-feedback` lets a user tell the harness what they think of a session: type `/feedback` plus a remark, and the remark is recorded and acknowledged. Recording is immediate and never starts model work, so it is safe at any point in a conversation — the model neither sees the remark nor is interrupted by it. The acknowledgement names the session and the anonymous user. The command ships with the Web client and needs no configuration; headless, ACP, and JSON-RPC entry points do not provide slash commands and cannot run it. ## Table of Contents @@ -29,28 +29,15 @@ Users can record feedback from the Web client out of the box: the `/feedback` co ### The `/feedback` command -Type `/feedback` followed by your remark and send it. A successful entry is acknowledged with the receiving session id, the anonymous user id, and the session-sharing policy: +Type `/feedback` followed by your remark and send it. A successful entry is acknowledged with the receiving session id and the anonymous user id: | Input | Result | |---|---| -| `/feedback the diff view is unreadable` | Record the remark and acknowledge: `Feedback recorded for session {sessionId}`, `Anonymous user: {userId}`, plus the sharing disclosure. | +| `/feedback the diff view is unreadable` | Record the remark and acknowledge with two lines: `Feedback recorded for session {sessionId}` and `Anonymous user: {userId}.` | | `/feedback` | A usage error: `Feedback text is required. Usage: /feedback `. Whitespace-only input counts as empty. | Surrounding whitespace is trimmed, but the remark is otherwise kept exactly as typed: no truncation, case folding, or command parsing — `/feedback /plan felt slow` records that literal text. Each command records its own entry; nothing is merged or replaced. -### The sharing disclosure - -The acknowledgement also states how the session is shared under the deployment's telemetry policy: - -| Disclosed status | Acknowledgement sentence | -|---|---| -| `full` | `Session sharing is enabled.` | -| `feedback-only` | `Session sharing is feedback-gated; recording feedback uploads the session records not yet shared.` | -| `disabled` | `Session sharing is disabled.` | -| no telemetry service | `Session sharing is not configured.` | - -The sentence reports the current policy only; it never claims the feedback or the session was delivered anywhere. The disclosure records nothing itself and never reaches the model. - ### Recording feedback from your own UI Feedback does not have to come from the slash command: any UI, hook, or host integration can record a remark directly, with the same guarantees and without a model turn. A custom app that wants the slash command mounts the command registry plus this plugin: @@ -74,7 +61,7 @@ The Web client ships the command. Headless mode, ACP automation, and JSON-RPC pr ### Design concept -The remark is one append-only fact in the session log, owned by the event rather than by the command that produced it: feedback can arrive from any trigger, so the fact must not depend on the slash command. The command keeps its own bookkeeping payload-free, so the remark text exists in exactly one place in the log, and the event never surfaces to the model. The sharing disclosure reads the optional telemetry service through the plugin context, so the command still works when no backend is mounted, and its sentence set mirrors the telemetry status union so an unknown status fails closed. +The remark is one append-only fact in the session log, owned by the event rather than by the command that produced it: feedback can arrive from any trigger, so the fact must not depend on the slash command. The command keeps its own bookkeeping payload-free, so the remark text exists in exactly one place in the log, and the event never surfaces to the model. ### How a remark is recorded @@ -94,10 +81,8 @@ The producer trims the text, rejects empty input, and writes one event into the ## Further Exploration -Read these pages when the package-level contract is not enough. They move from the sharing policy and command registry behind this capture path to the persistence and identity facts the acknowledgement relies on. +Read these pages when the package-level contract is not enough. They cover the command registry, persistence, and identity facts this capture path relies on. -- [Session telemetry subsystem](../../../docs/subsystems/session-telemetry.md) — the `SessionTelemetrySharingStatus` vocabulary and backend contract behind the disclosure. -- [dsh-session-telemetry](../../session/session-telemetry/README.md) — the seam whose `sharing` member drives the acknowledgement sentence. - [dsh-commands](../../interaction/commands/README.md) — the registry that discovers the global command and its `recordInput` semantics. - [Session persistence subsystem](../../../docs/subsystems/persistence.md) — how appended events become durable and what a flush barrier means. - [Anonymous user identity](../../identity/anonymous-user-id/README.md) — the id the acknowledgement reports. @@ -129,7 +114,7 @@ Independent of the model request path. Recording appends to the session log only These limits define where `/feedback` is a poor fit or behaves differently than a user might expect. They are current package constraints, not a task backlog. -- **No feedback retrieval or management surface** — the optional OTel plugin uses the event only as a sharing trigger. There is no retrieval, aggregation, categorization, or model-facing tool for `feedback/record`. +- **No feedback retrieval or management surface** — there is no retrieval, aggregation, categorization, or model-facing tool for `feedback/record`. - **No structured fields** — an entry is one free-text string with no category, severity, or referenced-event link, so feedback cannot be filtered by subject without re-reading its text. - **No amend or withdraw** — the session log is append-only and this package adds no tombstone, so a mistaken entry stays recorded and can only be superseded by a later one. - **No explicit durability barrier** — the acknowledgement follows the append, not a flush, so an entry recorded immediately before a crash can be lost with any other unflushed tail. A consumer that needs a barrier awaits `ctx.sessions.flush(session)`. @@ -144,7 +129,7 @@ These limits define where `/feedback` is a poor fit or behaves differently than This Dev Note is working context for maintainers; it is explicitly non-authoritative. Shipped behavior, limits, and rationale live in the sections above and the package code. -- The acknowledgement sentences are pinned by [`tests/command-feedback.spec.ts`](tests/command-feedback.spec.ts); changing them changes user-visible copy and the disclosure tests. +- The acknowledgement sentences are pinned by [`tests/command-feedback.spec.ts`](tests/command-feedback.spec.ts); changing them changes user-visible copy. - Structured fields and a retrieval surface remain the open direction behind the first two limitations; nothing in the current contract reserves a format for them. diff --git a/packages/feedback/command-feedback/README.zh.md b/packages/feedback/command-feedback/README.zh.md index 338d688400..493ddf72b3 100644 --- a/packages/feedback/command-feedback/README.zh.md +++ b/packages/feedback/command-feedback/README.zh.md @@ -9,7 +9,7 @@ kind: "package-reference" ## 概述 -`dsh-command-feedback` 让用户告诉 harness 他们对会话的看法：输入 `/feedback` 加一条评价，评价即被记录并得到确认。记录是即时的，绝不会启动模型工作，因此在对话的任何时刻都是安全的——模型既看不到这条评价，也不会被打断。确认文本会点名会话与匿名用户，并报告部署的遥测策略下会话如何被共享。命令随 Web 客户端交付，无需任何配置；无头模式、ACP（Agent Client Protocol）与 JSON-RPC 入口不提供斜杠命令，因此无法运行它。 +`dsh-command-feedback` 让用户告诉 harness 他们对会话的看法：输入 `/feedback` 加一条评价，评价即被记录并得到确认。记录是即时的，绝不会启动模型工作，因此在对话的任何时刻都是安全的——模型既看不到这条评价，也不会被打断。确认文本会点名会话与匿名用户。命令随 Web 客户端交付，无需任何配置；无头模式、ACP（Agent Client Protocol）与 JSON-RPC 入口不提供斜杠命令，因此无法运行它。 ## 目录 @@ -29,28 +29,15 @@ kind: "package-reference" ### `/feedback` 命令 -输入 `/feedback` 加你的评价并发送。成功时会以接收会话 id、匿名用户 id 与共享策略确认： +输入 `/feedback` 加你的评价并发送。成功时会以接收会话 id 与匿名用户 id 确认： | 输入 | 结果 | |---|---| -| `/feedback the diff view is unreadable` | 记录评价并确认：`Feedback recorded for session {sessionId}`、`Anonymous user: {userId}`，外加共享披露。 | +| `/feedback the diff view is unreadable` | 记录评价并以两行确认：`Feedback recorded for session {sessionId}` 和 `Anonymous user: {userId}.` | | `/feedback` | 用法错误：`Feedback text is required. Usage: /feedback `。仅含空白的输入视为空输入。 | 前后空白会被去除，但除此之外，评价会按输入原样保留：不进行截断、大小写折叠或命令解析——`/feedback /plan felt slow` 记录的就是这段字面文本。每次执行命令都会记录自己的条目；不会发生合并或替换。 -### 共享披露 - -确认文本还会说明部署的遥测策略下会话如何被共享： - -| 披露的状态 | 确认文本中的句子 | -|---|---| -| `full` | `Session sharing is enabled.` | -| `feedback-only` | `Session sharing is feedback-gated; recording feedback uploads the session records not yet shared.` | -| `disabled` | `Session sharing is disabled.` | -| 无遥测服务 | `Session sharing is not configured.` | - -句子只报告当前策略，绝不声称反馈或会话已投递到任何地方。披露本身不记录任何内容，也绝不会到达模型。 - ### 从自己的 UI 记录反馈 反馈不一定来自斜杠命令：任何 UI、钩子或 host 集成都可以直接记录评价，享有同样的保证且无需模型轮次。想要斜杠命令的自定义应用，把命令注册表与本插件组合在一起即可： @@ -74,7 +61,7 @@ Web 客户端随附该命令。无头模式、ACP 自动化和 JSON-RPC 不提 ### 设计理念 -评价是会话日志中一个仅追加的事实，由事件而非产生它的命令拥有：反馈可能来自任何触发方式，因此事实绝不能依赖斜杠命令。命令自身的簿记不携带载荷，所以评价文本在日志中只存在于一个地方，且该事件绝不会浮出到模型。共享披露通过插件上下文读取可选的遥测服务，因此未挂载后端时命令仍可用；句子集镜像遥测状态 union，未知状态会快速失败。 +评价是会话日志中一个仅追加的事实，由事件而非产生它的命令拥有：反馈可能来自任何触发方式，因此事实绝不能依赖斜杠命令。命令自身的簿记不携带载荷，所以评价文本在日志中只存在于一个地方，且该事件绝不会浮出到模型。 ### 评价如何被记录 @@ -94,10 +81,8 @@ Web 客户端随附该命令。无头模式、ACP 自动化和 JSON-RPC 不提 ## 进一步探索 -当包级约定不够用时阅读以下页面。它们从这条采集路径背后的共享策略与命令注册表，逐步进入确认文本所依赖的持久化与身份事实。 +当包级约定不够用时阅读以下页面。它们涵盖这条采集路径所依赖的命令注册表、持久化与身份事实。 -- [会话遥测子系统](../../../docs/subsystems/session-telemetry.zh.md)——披露背后的 `SessionTelemetrySharingStatus` 词汇与后端约定。 -- [dsh-session-telemetry](../../session/session-telemetry/README.zh.md)——其 `sharing` 成员决定确认文本句子的 seam。 - [dsh-commands](../../interaction/commands/README.zh.md)——发现全局命令并定义 `recordInput` 语义的注册表。 - [会话持久化子系统](../../../docs/subsystems/persistence.zh.md)——追加事件如何持久化、flush 屏障的含义。 - [匿名用户身份](../../identity/anonymous-user-id/README.zh.md)——确认文本报告的 id。 @@ -129,7 +114,7 @@ Web 客户端随附该命令。无头模式、ACP 自动化和 JSON-RPC 不提 这些限制说明 `/feedback` 何时不合适，或何时行为与用户预期不同。它们是当前包约束，不是任务积压。 -- **没有反馈检索或管理 surface**——可选的 OTel 插件仅将该事件用作共享触发器。本包不为 `feedback/record` 提供检索、聚合、分类或面向模型的工具。 +- **没有反馈检索或管理 surface**——本包不为 `feedback/record` 提供检索、聚合、分类或面向模型的工具。 - **没有结构化字段**——一条条目就是一个自由文本字符串，没有类别、严重程度或关联事件链接，因此无法在不重读文本的情况下按主题过滤反馈。 - **不支持修改或撤回**——会话日志是仅追加的，本包也不新增 tombstone，因此错误的条目会一直保留在记录中，只能由后续条目取代。 - **没有显式持久化屏障**——确认文本紧随追加而非 flush，因此紧临崩溃前记录的条目可能与其他未 flush 的尾部一同丢失。需要该保证的消费方可自行等待 `ctx.sessions.flush(session)`。 @@ -144,7 +129,7 @@ Web 客户端随附该命令。无头模式、ACP 自动化和 JSON-RPC 不提 本开发备注是维护者的工作上下文，明确不具权威性。已交付的行为、限制与理由以上文与包代码为准。 -- 确认文本句子由 [`tests/command-feedback.spec.ts`](tests/command-feedback.spec.ts) 固定；修改它们会改变用户可见文案与披露测试。 +- 确认文本句子由 [`tests/command-feedback.spec.ts`](tests/command-feedback.spec.ts) 固定；修改它们会改变用户可见文案。 - 结构化字段与检索 surface 仍是前两条限制背后的开放方向；当前约定没有为它们预留任何格式。 diff --git a/packages/feedback/command-feedback/package.json b/packages/feedback/command-feedback/package.json index c3c6a8892c..68f6a36286 100644 --- a/packages/feedback/command-feedback/package.json +++ b/packages/feedback/command-feedback/package.json @@ -29,7 +29,6 @@ "peerDependencies": { "@deepseek-ai/dsh-commands": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-session-telemetry": "workspace:^", "@deepseek-ai/dsh-anonymous-user-id": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, @@ -40,7 +39,6 @@ "@deepseek-ai/dsh-commands": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-session-telemetry": "workspace:^", "@deepseek-ai/dsh-anonymous-user-id": "workspace:^", "@deepseek-ai/cordis": "workspace:^" } diff --git a/packages/feedback/command-feedback/src/index.ts b/packages/feedback/command-feedback/src/index.ts index e64e147b5c..ef840fe9c8 100644 --- a/packages/feedback/command-feedback/src/index.ts +++ b/packages/feedback/command-feedback/src/index.ts @@ -8,7 +8,6 @@ import type { Context } from '@deepseek-ai/cordis' import type { CommandInvocation, CommandResult } from '@deepseek-ai/dsh-commands' -import type { SessionTelemetryBackend, SessionTelemetrySharingStatus } from '@deepseek-ai/dsh-session-telemetry' import type { Session } from '@deepseek-ai/dsh-session' import { getOrCreateAnonymousUserId } from '@deepseek-ai/dsh-anonymous-user-id' @@ -17,42 +16,6 @@ export const inject = ['commands'] const USAGE = 'Usage: /feedback ' -/** Fail closed when a future sharing status reaches the sentence switch. */ -/* v8 ignore next 3 -- only the ignored default arm calls this; the closed union cannot reach it via the public API. */ -function assertNever(value: never): never { - throw new Error(`command-feedback: unsupported sharing status ${JSON.stringify(value)}`) -} - -/** The acknowledgement's sharing sentence for a disclosed policy. */ -function sharingSentence(sharing: SessionTelemetrySharingStatus): string { - switch (sharing) { - case 'full': - return 'Session sharing is enabled.' - case 'feedback-only': - return 'Session sharing is feedback-gated; recording feedback uploads the session records not yet shared.' - case 'disabled': - return 'Session sharing is disabled.' - /* v8 ignore next 2 -- the seam's closed union cannot reach the default; a future status must be given a sentence here. */ - default: - return assertNever(sharing) - } -} - -/** - * The sharing disclosure appended to the acknowledgement: the mounted - * backend's disclosed policy, or a "not configured" notice when no backend - * is mounted. Read through the plugin context so the command still works - * when the telemetry service is absent. - * @param telemetry - the mounted telemetry service, or undefined. - * @returns one sentence describing this session's sharing policy. - */ -function sharingDisclosure(telemetry: SessionTelemetryBackend | undefined): string { - if (telemetry === undefined) { - return 'Session sharing is not configured.' - } - return sharingSentence(telemetry.sharing) -} - declare module '@deepseek-ai/dsh-session/types' { interface SessionEventMap { /** @@ -79,20 +42,17 @@ export function recordFeedback(session: Session, text: string): void { * Validate, record, and acknowledge one feedback entry. Returning an error * leaves no `feedback/record` event. * @param invocation - receiving agent, raw command input, and UI cancellation. - * @param ctx - plugin context used to read the optional telemetry service. * @returns an acknowledgement containing the receiving session and anonymous - * user ids plus the session-sharing disclosure, or a usage error when no - * feedback text was supplied. + * user ids, or a usage error when no feedback text was supplied. */ -function executeFeedbackCommand(invocation: CommandInvocation, ctx: Context): CommandResult { +function executeFeedbackCommand(invocation: CommandInvocation): CommandResult { if (invocation.rawInput.trim().length === 0) { return { kind: 'error', text: `Feedback text is required. ${USAGE}` } } recordFeedback(invocation.agent.session, invocation.rawInput) - const telemetry = ctx.get('sessionTelemetry') return { kind: 'success', - text: `Feedback recorded for session ${invocation.agent.session.id}\nAnonymous user: ${getOrCreateAnonymousUserId()}. ${sharingDisclosure(telemetry)}`, + text: `Feedback recorded for session ${invocation.agent.session.id}\nAnonymous user: ${getOrCreateAnonymousUserId()}.`, } } @@ -103,6 +63,6 @@ export function apply(ctx: Context): void { description: 'record feedback about this session', input: { hint: '' }, recordInput: false, - handler: invocation => executeFeedbackCommand(invocation, ctx), + handler: executeFeedbackCommand, }) } diff --git a/packages/feedback/command-feedback/tests/command-feedback.spec.ts b/packages/feedback/command-feedback/tests/command-feedback.spec.ts index 647eeb3da4..71aa288cc5 100644 --- a/packages/feedback/command-feedback/tests/command-feedback.spec.ts +++ b/packages/feedback/command-feedback/tests/command-feedback.spec.ts @@ -5,7 +5,6 @@ import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent' import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent' import CommandRuntime from '@deepseek-ai/dsh-commands' import SessionStore, { foldSurface, Session, SessionId } from '@deepseek-ai/dsh-session' -import { SessionTelemetryBackend, type SessionTelemetrySharingStatus } from '@deepseek-ai/dsh-session-telemetry' import * as commandFeedback from '@deepseek-ai/dsh-command-feedback' const { USER_ID, getOrCreateAnonymousUserId } = vi.hoisted(() => { @@ -26,20 +25,6 @@ interface Harness { readonly plugin: Awaited> } -/** Minimal mounted backend disclosing one sharing policy. */ -class FakeTelemetry extends SessionTelemetryBackend { - override readonly sharing: SessionTelemetrySharingStatus - - constructor(ctx: Context, config: { sharing: SessionTelemetrySharingStatus }) { - super(ctx) - this.sharing = config.sharing - } - - emit(): void {} - - async shutdown(): Promise {} -} - /** Build a live idle agent over a store-owned session, as an app's spine does. */ function stubAgent(ctx: Context, id: string): { agent: Agent; session: Session } { const session = ctx.sessions.create(SessionId(id)) @@ -63,17 +48,11 @@ function stubAgent(ctx: Context, id: string): { agent: Agent; session: Session } return { agent, session } } -/** - * Mount the real command registry, this producer, and optionally a telemetry - * backend disclosing one sharing policy. Without `sharing`, no telemetry - * service exists and the acknowledgement reports "not configured". - */ -async function harness(sharing?: SessionTelemetrySharingStatus): Promise { +async function harness(): Promise { const ctx = new Context() await ctx.plugin(CommandRuntime) await ctx.plugin(AgentRegistry) await ctx.plugin(SessionStore) - if (sharing !== undefined) await ctx.plugin(FakeTelemetry, { sharing }) const plugin = await ctx.plugin(commandFeedback) const { agent, session } = stubAgent(ctx, `command-feedback-${Math.random()}`) ctx.agents.register(agent) @@ -125,7 +104,7 @@ describe('/feedback human command', () => { const test = await harness() await expect(run(test, ' the diff view is unreadable')).resolves.toEqual({ kind: 'success', - text: `Feedback recorded for session ${test.session.id}\nAnonymous user: ${USER_ID}. Session sharing is not configured.`, + text: `Feedback recorded for session ${test.session.id}\nAnonymous user: ${USER_ID}.`, }) expect(feedbackTexts(test.session)).toEqual(['the diff view is unreadable']) const commandRun = test.session.snapshotEvents().find(event => event.type === 'command/run') @@ -173,39 +152,12 @@ describe('/feedback human command', () => { test.ctx.commands.execute(test.agent, '/feedback second', [], signal), ]) expect(settled.map(item => item?.result)).toEqual([ - { kind: 'success', text: `Feedback recorded for session ${test.session.id}\nAnonymous user: ${USER_ID}. Session sharing is not configured.` }, - { kind: 'success', text: `Feedback recorded for session ${test.session.id}\nAnonymous user: ${USER_ID}. Session sharing is not configured.` }, + { kind: 'success', text: `Feedback recorded for session ${test.session.id}\nAnonymous user: ${USER_ID}.` }, + { kind: 'success', text: `Feedback recorded for session ${test.session.id}\nAnonymous user: ${USER_ID}.` }, ]) expect(feedbackTexts(test.session)).toEqual(['first', 'second']) }) - it('discloses full session sharing in the acknowledgement', async () => { - const test = await harness('full') - await expect(run(test, ' everything shared')).resolves.toEqual({ - kind: 'success', - text: `Feedback recorded for session ${test.session.id}\nAnonymous user: ${USER_ID}. Session sharing is enabled.`, - }) - expect(feedbackTexts(test.session)).toEqual(['everything shared']) - }) - - it('discloses feedback-gated session sharing in the acknowledgement', async () => { - const test = await harness('feedback-only') - await expect(run(test, ' gated sharing')).resolves.toEqual({ - kind: 'success', - text: `Feedback recorded for session ${test.session.id}\nAnonymous user: ${USER_ID}. Session sharing is feedback-gated; recording feedback uploads the session records not yet shared.`, - }) - expect(feedbackTexts(test.session)).toEqual(['gated sharing']) - }) - - it('discloses disabled session sharing in the acknowledgement', async () => { - const test = await harness('disabled') - await expect(run(test, ' local only')).resolves.toEqual({ - kind: 'success', - text: `Feedback recorded for session ${test.session.id}\nAnonymous user: ${USER_ID}. Session sharing is disabled.`, - }) - expect(feedbackTexts(test.session)).toEqual(['local only']) - }) - it('keeps every recorded event out of model context and derived history', async () => { const test = await harness() await run(test, ' invisible to the model') diff --git a/packages/feedback/command-feedback/tests/loader-composition.spec.ts b/packages/feedback/command-feedback/tests/loader-composition.spec.ts index 624ca05af5..1ad8abf770 100644 --- a/packages/feedback/command-feedback/tests/loader-composition.spec.ts +++ b/packages/feedback/command-feedback/tests/loader-composition.spec.ts @@ -93,7 +93,7 @@ describe('/feedback real Loader composition through cordis.yml', () => { const userId = getOrCreateAnonymousUserId({ env: { DSH_HOME: root } }) expect(accepted?.result).toEqual({ kind: 'success', - text: `Feedback recorded for session feedback-loader-agent\nAnonymous user: ${userId}. Session sharing is not configured.`, + text: `Feedback recorded for session feedback-loader-agent\nAnonymous user: ${userId}.`, }) const rejected = await context.commands.execute(owner, '/feedback', [], signal) expect(rejected?.result).toEqual({ diff --git a/packages/feedback/command-feedback/tsconfig.json b/packages/feedback/command-feedback/tsconfig.json index 27d95e93fa..4de25870dc 100644 --- a/packages/feedback/command-feedback/tsconfig.json +++ b/packages/feedback/command-feedback/tsconfig.json @@ -22,9 +22,6 @@ }, { "path": "../../identity/anonymous-user-id" - }, - { - "path": "../../session/session-telemetry" } ] } diff --git a/packages/feedback/message-feedback/README.i18n.yaml b/packages/feedback/message-feedback/README.i18n.yaml index 7d0d4ca3cf..cc0a951754 100644 --- a/packages/feedback/message-feedback/README.i18n.yaml +++ b/packages/feedback/message-feedback/README.i18n.yaml @@ -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/feedback/message-feedback/README.md -README.md: b8d085a1d8cb8cdb46cfc51c7cadda5ee6d925c9 -README.zh.md: 027bd6286642ec1ecc9fe38882743185d132ac38 +README.md: 2490655514ec4266100724e0645c29fdf61a3be1 +README.zh.md: 5f6f7ff1e78671426123bf6b61c703fb00a8faf4 diff --git a/packages/feedback/message-feedback/README.md b/packages/feedback/message-feedback/README.md index b8d085a1d8..2490655514 100644 --- a/packages/feedback/message-feedback/README.md +++ b/packages/feedback/message-feedback/README.md @@ -1,5 +1,5 @@ --- -description: "Per-message ratings and notes for finalized assistant messages, for users and maintainers choosing, composing, or debugging the feedback service." +description: "Canonical Session-log ratings and notes for finalized assistant messages." kind: "package-reference" --- @@ -9,152 +9,93 @@ English | [中文](README.zh.md) ## Summary -`dsh-message-feedback` lets product surfaces offer per-message feedback: a user marks an assistant message positive or negative and can attach a short note, and the rating stays with that message. Ratings are stored with the session, survive restarts, and never enter model history or telemetry. Product surfaces read, create, and change ratings through the `messageFeedback` service, whose `list`, `put`, and `delete` operations are the whole surface. The one deployment setting is the maximum note length (`maxNoteBytes`), which the Web bundle sets to 8192. Browser controls live in a separate client package; this package provides the service itself. +This service records positive or negative ratings and optional verbatim notes for finalized assistant messages. The canonical Session log owns every creation, edit, and deletion; `list`, `put`, and `delete` expose current feedback without constructing or waking an Agent. Feedback is log-only and does not enter model history. ## Table of Contents - [Use this package](#use-this-package) - [Understand the implementation](#understand-the-implementation) -- [Further Exploration](#further-exploration) - [Model Experience](#model-experience) - [Known Limitations and Deferred Work](#known-limitations-and-deferred-work) - [Dev Note](#dev-note) ------ - ## Use this package -Choose this service when a product surface should let users rate and annotate individual assistant messages. Feedback attaches only to a finalized message — one that has already been sent — and using the service never starts or resumes an agent. A custom app mounts the service together with session persistence and storage; the shipped Web bundle already composes all of it with `maxNoteBytes: 8192`. +Mount `dsh-message-feedback` alongside `sessions` and `sessionPersistence`. It needs no storage-domain service. The Web bundle supplies the browser consumer and a note limit of 8192 bytes. ### Configuration | Field | Default | Meaning | |---|---|---| -| `maxNoteBytes` | required | Maximum UTF-8 byte length accepted for one optional note. | +| `maxNoteBytes` | required | Positive safe-integer maximum UTF-8 bytes in one optional note. | -```yaml -- id: message-feedback - name: '@deepseek-ai/dsh-message-feedback' - config: - maxNoteBytes: 8192 -``` - -A note must contain at least one non-whitespace character and fit within the configured byte length; a blank note is rejected with `note-blank` and an oversized one with `note-too-large`. Accepted text is stored exactly as submitted — nothing is trimmed. The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-message-feedback) is the exhaustive source for every accepted field and its JSDoc. +A supplied note must contain a non-whitespace character and fit the configured byte limit. Blank notes return `note-blank`; oversized notes return `note-too-large`. Accepted text is preserved exactly, including surrounding whitespace. Omitting a note clears it. Note validation precedes Session lookup. ### Reading and changing feedback -Callers use three operations to read and change feedback for a session: - -| Operation | Request | Success | Rejected when | +| Operation | Request | Success | Business failures | |---|---|---|---| -| `list` | the session id | the current ratings and notes, in creation order | the session is not found | -| `put` | session, message, rating, optional note, expected version | the stored rating and note | session not found, message is not a valid target, version conflict, blank or oversized note | -| `delete` | session, message, expected version | the rating is absent | session not found, version conflict | +| `list` | Session id | Current items in creation order | Session not found | +| `put` | Session, message, rating, optional note, expected version | Current item | Session or target not found, version conflict, invalid note | +| `delete` | Session, message, expected version | Item absent | Session not found, version conflict | -Every change must be based on the version the service returned for that rating: a change based on an older version is rejected with `version-conflict`, and the reply carries the current rating so the caller can see what changed without another read. Deleting a rating that is already absent succeeds, and concurrent changes to different messages do not conflict. An omitted note clears an existing note. +Create with `ifVersion: null`; edit or delete with the returned version. Stale mutations return `version-conflict` and the current item. Each material put mints a fresh token and preserves the original creation time. A matching no-op put returns the same item without appending an event. Deleting an absent item succeeds regardless of the supplied version, without appending an event. Recreating a deleted item starts a new creation time and ordering position. -### What you can rate - -A rating attaches to one finalized assistant message: the message must exist and be an assistant message that was sent. User messages, empty assistant placeholders, and replaced messages are not valid targets and are rejected with `target-not-found`. Once recorded, the rating and note stay with that message and survive restarts; a fork of the session starts with no feedback. - -### Durability - -A rating is committed only after the message it refers to is durably stored, so feedback never points at a message that can be lost. Reading or writing feedback never starts or resumes an agent; the service inspects the persisted session directly. - ------ +Targets must be non-empty assistant messages produced by append-origin events. User messages, empty assistant placeholders, and replacement-origin messages return `target-not-found`. Feedback survives restart; a fork starts without owned feedback even when its inherited prefix contains parent feedback. ## Understand the implementation -
-Implementation internals — click to expand +### Canonical log and durability -### Design concept +`feedback/message-put` stores the owning Session id and complete item, including its version and timestamps. `feedback/message-delete` stores the owner and message id. Current state is derived from these events, ignoring other Session owners. Durable payloads are validated before use. No second feedback store or cache exists. -The service keeps feedback outside the session log entirely: each session owns one sidecar row in a storage domain, so a rating can never be confused with conversation content, model history, or telemetry. The sidecar is only ever committed after the message it references is durable — the row extends the target log instead of preceding it. Every operation returns a business result that distinguishes a handled failure (missing session, invalid target, stale version, bad note) from an infrastructure failure, which rejects instead of being mislabeled. +Live operations append through `Session.append` and await `sessions.flush`, then verify the captured log endpoint and Session header through a persistence read handle before reporting success. Cold mutations hold a persistence write handle across read, validation, comparison, append, flush, and close. Cold reads use a read handle. Neither path constructs a Session or appends lifecycle events. -### What a sidecar holds - -One row per session binds the inspected session identity (`createdAt`, `cwd`) to its feedback items; the identity fences a reused session id, so a row from an earlier lifecycle is invisible and a fork starts with no feedback. Items are immutable values — a change writes a new version of the item, preserving its creation time — and the row schema rejects duplicate message ids and reused versions so lookup stays unambiguous. The exact row schema and validation live in [`src/spec.ts`](src/spec.ts). - -### Concurrency - -Mutations are optimistic and per message: a caller sends the version it last observed, a stale version is rejected with the authoritative current item so the caller reconciles without another read, and every material change mints a fresh version token so a stale write can never masquerade as current. A per-session queue serializes the whole read-compare-write through one service instance; storage provides no cross-process conditional write, which is the Known Limitation below. - -### Durability and target validation - -A write is staged, verified, then committed: the target message is flushed through the canonical checkpoint, the physical log prefix is re-read, and only then is the sidecar row written — feedback can never reference a message that is not durable. Cold sessions are read without resuming an agent, absence is decided by the persistence store's `stat` rather than guessed, and only a real, sent assistant message is a valid target. The flush and read path lives in [`src/index.ts`](src/index.ts). - -### Failure modes - -The service fails closed: disposal drains in-flight writes before closing the domain, a write submitted after disposal starts is rejected as a lifecycle failure, and invalid configuration or a read before domain initialization fails loudly. +A per-Session queue serializes operations within one service instance; the persistence write handle excludes competing cold writers. Disposal stops admission and drains admitted operations before releasing the service. Persistence failures reject instead of becoming business failures. A failed flush does not roll back an accepted event; callers can list and retry with its version. Successful no-op mutations also flush the current prefix. ### Source map | File | Role | |---|---| -| [`src/index.ts`](src/index.ts) | Service class: config validation, per-Session queue, durability barrier, `@Remote` methods | -| [`src/types.ts`](src/types.ts) | Public request, value, and failure vocabulary (types only, for generated Remote clients) | -| [`src/spec.ts`](src/spec.ts) | Storage-domain declaration: `message_feedback` domain, `sessions` table, row schemas | -| — | No runtime invariant companion is published; the private typed writer owns current row mutations, the domain schema validates rows on reopen, and no second authority exists. | +| [`src/index.ts`](src/index.ts) | Remote service, payload validation, event projection, and persistence ownership | +| [`src/types.ts`](src/types.ts) | Requests, results, and Session event declarations; types only | -
+No runtime invariant companion is published: the service derives feedback directly from validated canonical events and owns no independently mutable projection. ------ - - -## Further Exploration - -Read these pages when the package-level contract is not enough. They move from the subsystem types and design boundary to the persistence primitives and the browser consumer that drives this service. - -- [Feedback subsystem](../../../docs/subsystems/feedback.md) — the public types, Remote contract, and Web consumer details. -- [Session persistence subsystem](../../../docs/subsystems/persistence.md) — the handle `read`, `stat`, and `flush` semantics behind the durability barrier. -- [dsh-client-ui-message-feedback](../../client/ui-message-feedback/README.md) — the browser consumer that drives the Host Remote contract. -- [Feedback package map](../README.md) — where per-message feedback sits next to the log-only capture command. - ------ +See the [feedback subsystem](../../../docs/subsystems/feedback.md), [Session persistence](../../../docs/subsystems/persistence.md), and [browser consumer](../../client/ui-message-feedback/README.md) for their respective APIs. ## Model Experience -### Local message-feedback state +### Message feedback #### What the model sees -Nothing. `ctx.messageFeedback` registers no tool, prompt section, model-facing context, or Session event; feedback stays in a Host-owned sidecar unless a separately documented Consumer explicitly exposes it. +Nothing. `feedback/message-put` and `feedback/message-delete` carry no surface placement, tool, prompt section, or model-facing context. Log export and delivery policies belong to their consumers. #### Token effect -Zero. No request, result, rating, note, timestamp, or failure from this package enters a model request. +Zero. Ratings, notes, and service results do not enter model requests. #### KV Cache effect -Independent. Listing or mutating message feedback does not touch a model request prefix and cannot invalidate an otherwise reusable provider cache entry. +Independent. Feedback does not change the model request prefix. ## Known Limitations and Deferred Work - -These limits define when the service is a poor fit or needs special operational care. They are current package constraints, not a task backlog. - -- **Compare-and-set is single-process** — the per-Session queue serializes one service instance only; storage-domain has no cross-process conditional write, so multiple Host processes writing one storage root can still lose updates. -- **No durable Session deletion cascade** — Session persistence has no deletion API, and `session/disposed`/`api-session/removed` mean detach rather than durable deletion. The service therefore retains empty rows and may leave orphan rows after out-of-band log removal instead of deleting valid feedback on detach. -- **Header identity is not a content fingerprint** — `{createdAt, cwd}` detects reuse only when those fields differ; a cloned log retaining the same header identity is indistinguishable. -- **Trusted caller boundary** — `list`/`put`/`delete` carry no authenticated actor or audit identity. A deployment must expose the Host gateway only through its trusted or separately authenticated boundary until authorization and attribution are added. -- **Row bounds** — `maxNoteBytes` bounds one note, but the item count and aggregate retained bytes of one Session row are not capped; a deployment-owned row bound remains deferred until a concrete consumer defines its policy. +- **Log-only authority:** existing `message_feedback` sidecar data is neither read nor migrated. Those files remain untouched, but their feedback is unavailable through this service. +- **Deletion retains history:** delete removes current feedback, not earlier ratings or notes from the append-only log; it is not a privacy-erasure operation. +- **Writer ownership:** another process holding a Session write handle causes cold mutations to reject. The service does not wake that owner or coordinate Remote calls across processes. +- **Trusted callers:** requests contain no authenticated actor or audit identity. Deployments must protect the Host gateway. +- **Telemetry export:** the shipped OTel row is disabled. If enabled in `FULL`, it exports live feedback events; in `FEEDBACK_ONLY`, `/feedback` releases the pending canonical-log prefix, including message-feedback ratings and verbatim notes, not just the command text. Deployments own redaction; see the [OTel export policy](../../session/session-telemetry-otel/README.md). +- **Scan cost:** each `list`, `put`, or `delete` that reaches an existing Session scans its full event log to derive current feedback; cold operations also read the full log from persistence. Work grows with total Session history, not just the number of feedback items. +- **Retention:** `maxNoteBytes` limits one note, not aggregate log size or mutation count. ### Dev Note -
-Working context for maintainers — click to expand - -This Dev Note is working context for maintainers; it is explicitly non-authoritative. Shipped behavior, limits, and rationale live in the sections above, the package code, and the linked Agent Note. - -- The browser controls and the client Remote mount live in `dsh-client-ui-message-feedback` and `dsh-api-remotes`; their open items belong to those packages' notes. -- The trusted-caller limitation is the open authorization direction: the Host gateway records no actor or audit identity, and any authentication layer must land at the deployment boundary before the service exposes per-user attribution. -- Note validation precedes Session lookup by design, so `note-blank` and `note-too-large` win over `session-not-found` for a missing Session; tests pin this order. - -
+The [package tests](tests/message-feedback.spec.ts) cover current-state and durable-history semantics; the [Loader composition](tests/loader-composition.spec.ts) verifies live and cold JSONL operations across restart. diff --git a/packages/feedback/message-feedback/README.zh.md b/packages/feedback/message-feedback/README.zh.md index 027bd62866..5f6f7ff1e7 100644 --- a/packages/feedback/message-feedback/README.zh.md +++ b/packages/feedback/message-feedback/README.zh.md @@ -1,5 +1,5 @@ --- -description: "针对已完成 assistant 消息的逐消息评分与备注，供用户与维护者选择、组合或排查该反馈服务。" +description: "在权威 Session 日志中保存已完成 assistant 消息的评分与备注。" kind: "package-reference" --- @@ -9,152 +9,93 @@ kind: "package-reference" ## 概述 -`dsh-message-feedback` 让产品界面提供逐消息反馈：用户可以把一条 assistant 消息标记为好评或差评，并可附上简短备注，评分会与该消息绑定。评分与会话一起保存，重启后依然存在，并且绝不会进入模型历史或遥测。产品界面通过 `messageFeedback` 服务读取、创建和修改评分，其 `list`、`put`、`delete` 三个操作就是全部对外表面。唯一需要部署方设置的项是备注最大长度（`maxNoteBytes`），Web 组合将其设为 8192。浏览器控件位于独立的客户端包中；本包提供服务本身。 +本服务为已完成的 assistant 消息记录好评、差评及可选的原样备注。每次创建、编辑和删除都由权威 Session 日志保存；`list`、`put` 和 `delete` 提供当前反馈，不会构造或唤醒 Agent。反馈仅写入日志，不进入模型历史。 ## 目录 - [使用本包](#use-this-package) - [理解实现](#understand-the-implementation) -- [进一步探索](#further-exploration) - [模型体验](#model-experience) - [已知限制与延期工作](#known-limitations-and-deferred-work) - [开发备注](#dev-note) ------ - ## 使用本包 -当产品界面需要让用户对单条 assistant 消息评分或加备注时，选择此服务。反馈只绑定已完成的（即已发出的）消息，并且使用该服务绝不会启动或恢复 agent。自定义应用需要把此服务与会话持久化和存储一起挂载；随附的 Web 组合已用 `maxNoteBytes: 8192` 组合好全部组件。 +将 `dsh-message-feedback` 与 `sessions`、`sessionPersistence` 一起挂载。它不需要 storage-domain 服务。Web 组合提供浏览器消费方，并将备注上限设为 8192 字节。 ### 配置 | 字段 | 默认值 | 含义 | |---|---|---| -| `maxNoteBytes` | 必填 | 一条可选备注的最大 UTF-8 字节长度。 | +| `maxNoteBytes` | 必填 | 单条可选备注的 UTF-8 字节上限，必须为正安全整数。 | -```yaml -- id: message-feedback - name: '@deepseek-ai/dsh-message-feedback' - config: - maxNoteBytes: 8192 -``` - -备注必须包含至少一个非空白字符，并且不得超过配置的字节长度；空白备注会以 `note-blank` 拒绝，超长备注会以 `note-too-large` 拒绝。通过校验的文本按提交原样存储——不做任何 trim。生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-message-feedback)是每个受支持字段及其 JSDoc 的穷尽式真源。 +提交的备注必须包含非空白字符，且不超过配置的字节上限。空白备注返回 `note-blank`；过长备注返回 `note-too-large`。通过校验的文本会完整保留，包括首尾空白。省略备注会清除它。备注校验先于 Session 查找。 ### 读取与修改反馈 -调用方用三个操作读取和修改某个会话的反馈： - -| 操作 | 请求 | 成功 | 拒绝时机 | +| 操作 | 请求 | 成功 | 业务失败 | |---|---|---|---| -| `list` | 会话 id | 当前的评分与备注，按创建顺序 | 会话不存在 | -| `put` | 会话、消息、评分、可选备注、期望的 version | 已存储的评分与备注 | 会话不存在、消息不是有效目标、version 冲突、备注空白或超长 | -| `delete` | 会话、消息、期望的 version | 评分已不存在 | 会话不存在、version 冲突 | +| `list` | Session id | 按创建顺序返回当前条目 | Session 不存在 | +| `put` | Session、消息、评分、可选备注、预期版本 | 当前条目 | Session 或目标不存在、版本冲突、备注无效 | +| `delete` | Session、消息、预期版本 | 条目不存在 | Session 不存在、版本冲突 | -每次修改都必须基于服务为该项评分返回的 version：基于更旧 version 的修改会以 `version-conflict` 拒绝，且回复携带当前评分，调用方无需再次读取即可看到变化。删除一条已经不存在的评分会成功；对不同消息的并发修改互不冲突。省略 `note` 会清除已有备注。 +创建时传入 `ifVersion: null`；编辑或删除时使用返回的版本。陈旧修改返回 `version-conflict` 及当前条目。每次实质 put 都生成新 token，并保留原始创建时间。匹配的无变化 put 返回相同条目，不追加事件。删除不存在的条目始终成功，不受所传版本影响，也不追加事件。重新创建已删除条目会产生新的创建时间和排序位置。 -### 可以对什么评分 - -评分绑定一条已完成的 assistant 消息：消息必须存在，并且是发送过的 assistant 消息。用户消息、空的 assistant 占位与已被替换的消息都不是有效目标，会以 `target-not-found` 拒绝。评分与备注一旦记录就与该消息绑定并跨重启保留；会话的 fork 从没有反馈开始。 - -### 持久性 - -只有当评分所指的消息已被持久存储后，评分才会提交，因此反馈绝不会指向可能丢失的消息。读取或写入反馈绝不会启动或恢复 agent；服务直接检查已持久化的会话。 - ------ +目标必须是由 append 来源事件产生的非空 assistant 消息。用户消息、空 assistant 占位及 replacement 来源消息返回 `target-not-found`。反馈跨重启保留；fork 即使继承了包含父会话反馈的前缀，也从没有自有反馈开始。 ## 理解实现 -
-实现细节——点击展开 +### 权威日志与持久性 -### 设计理念 +`feedback/message-put` 保存所属 Session id 及完整条目，包括版本和时间戳。`feedback/message-delete` 保存所属 Session 和消息 id。当前状态从这些事件推导，忽略属于其他 Session 的事件。持久化 payload 在使用前经过校验。不存在第二个反馈存储或缓存。 -服务把反馈完全放在会话日志之外：每个会话在存储域中拥有一条伴随记录行，因此评分绝不会与对话内容、模型历史或遥测混淆。伴随记录只在所引用消息已持久之后提交——该行是目标日志的延伸，而不是先于它。每个操作都返回业务结果，把已处理的失败（会话缺失、目标无效、版本陈旧、备注不合格）与基础设施故障区分开，后者会 reject 而非被误标。 +活跃会话通过 `Session.append` 追加，并等待 `sessions.flush`，然后通过持久化读 handle 核实捕获的日志末端与 Session header，才会报告成功。冷会话修改在读取、校验、比较、追加、flush 和关闭期间持有持久化写 handle。冷读取使用读 handle。两条路径都不会构造 Session 或追加生命周期事件。 -### 伴随记录里有什么 - -每个会话一行，把检查所得的会话身份（`createdAt`、`cwd`）与其反馈条目绑定；该身份隔离复用的会话 id，因此更早生命周期的行不可见，fork 也从无反馈开始。条目是不可变值——修改会写入条目新版本并保留其创建时间——行 schema 拒绝重复消息 id 与复用的版本，保证查找无歧义。精确的行 schema 与校验见 [`src/spec.ts`](src/spec.ts)。 - -### 并发 - -修改是乐观的、按消息进行的：调用方发送其最后观察到的 version，陈旧的 version 会连同权威当前条目一起被拒绝，调用方无需再次读取即可协调；每次实质修改都会铸造新的 version token，陈旧写入绝不会被误认为当前。按 Session 的队列把整个读-比较-写串行化在一个服务实例内；存储不提供跨进程条件写，这正是下文「已知限制」。 - -### 持久性与目标校验 - -写入按「暂存—校验—提交」进行：目标消息先通过权威 checkpoint flush，再物理重读日志前缀，之后才写入伴随记录行——反馈绝不会引用尚未持久的消息。冷会话在不恢复 agent 的情况下被读取，缺失由持久化存储的 `stat` 判定而非猜测，只有真实发送过的 assistant 消息才是有效目标。flush 与读取路径见 [`src/index.ts`](src/index.ts)。 - -### 故障模式 - -服务失败时保持封闭：disposal 先排空在途写入再关闭域，disposal 开始后提交的写入会以生命周期故障拒绝，无效配置或域初始化前的读取都会明确失败。 +每个 Session 的队列在同一服务实例内串行化操作；持久化写 handle 排除其他冷写入方。销毁时停止接收操作并排空已接收操作，然后释放服务。持久化故障会 reject，而非变成业务失败。flush 失败不会回滚已接受的事件；调用方可以读取并使用其版本重试。成功的无变化修改也会 flush 当前前缀。 ### 源码地图 | 文件 | 职责 | |---|---| -| [`src/index.ts`](src/index.ts) | 服务类：配置校验、按 Session 队列、持久性屏障、`@Remote` 方法 | -| [`src/types.ts`](src/types.ts) | 公开的请求、值与失败词汇（仅类型，供生成的 Remote 客户端使用） | -| [`src/spec.ts`](src/spec.ts) | storage-domain 声明：`message_feedback` 域、`sessions` 表、行 schema | -| — | 不发布运行时不变式伴生入口；域 schema 在重开时校验行。 | +| [`src/index.ts`](src/index.ts) | Remote 服务、payload 校验、事件投影与持久化所有权 | +| [`src/types.ts`](src/types.ts) | 请求、结果和 Session 事件声明；仅类型 | -
+不发布运行时不变式伴生入口：服务直接从校验后的权威事件推导反馈，不持有可独立修改的投影。 ------ - - -## 进一步探索 - -当包级约定不够用时阅读以下页面。它们从子系统类型与设计边界，逐步进入持久化原语与驱动此服务的浏览器消费方。 - -- [反馈子系统](../../../docs/subsystems/feedback.zh.md)——公开类型、Remote 契约与 Web 消费方细节。 -- [会话持久化子系统](../../../docs/subsystems/persistence.zh.md)——持久性屏障背后的 handle `read`、`stat` 与 `flush` 语义。 -- [dsh-client-ui-message-feedback](../../client/ui-message-feedback/README.zh.md)——驱动 Host Remote 契约的浏览器消费方。 -- [反馈包映射](../README.zh.md)——逐消息反馈与仅写入日志的采集命令并存的组。 - ------ +各自的 API 见[反馈子系统](../../../docs/subsystems/feedback.zh.md)、[Session 持久化](../../../docs/subsystems/persistence.zh.md)和[浏览器消费方](../../client/ui-message-feedback/README.zh.md)。 ## 模型体验 -### 本地消息反馈状态 +### 消息反馈 #### 模型看到什么 -无。`ctx.messageFeedback` 不注册工具、提示词段落、模型可见上下文或 Session 事件；除非另一个具有独立文档的 Consumer 显式公开反馈，否则它只留在 Host 拥有的伴随记录中。 +无。`feedback/message-put` 和 `feedback/message-delete` 不携带 surface 位置、工具、提示词段落或模型可见上下文。日志导出与投递策略由相应消费方负责。 #### Token 影响 -为零。本包的请求、结果、评分、备注、时间戳或失败都不会进入模型请求。 +为零。评分、备注和服务结果不进入模型请求。 #### KV Cache 影响 -相互独立。读取或变更消息反馈不会触碰模型请求前缀，也不会使本可复用的提供方缓存条目失效。 +相互独立。反馈不改变模型请求前缀。 ## 已知限制与延期工作 - -这些限制说明服务何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是任务积压。 - -- **Compare-and-set 仅限单进程**——按 Session 划分的队列只串行化一个服务实例；storage-domain 不提供跨进程条件写，因此多个 Host 进程写入同一存储根目录时仍可能丢失更新。 -- **没有持久 Session 删除级联**——Session persistence 没有删除接口，且 `session/disposed`/`api-session/removed` 表示 detach 而非持久删除。因此服务会保留空行，并可能在带外移除日志后留下遗留行，而不会在 detach 时删除仍有效的反馈。 -- **Header 身份不是内容指纹**——只有 `{createdAt, cwd}` 不同时才能识别复用；本契约无法区分保留相同 header 身份的克隆日志。 -- **调用方边界受信任**——`list`/`put`/`delete` 不携带已认证的 actor 或审计身份。在加入授权与归属信息前，部署方必须只通过受信任或另行认证的边界暴露 Host gateway。 -- **行边界**——`maxNoteBytes` 只限制单条备注，单个 Session 行的条目数和聚合保留字节尚无上限；由部署决定的行边界，延后到具体消费方明确策略时处理。 +- **仅日志具有权威性：**不读取或迁移现有 `message_feedback` 伴随数据。这些文件保持不变，但其反馈无法通过本服务访问。 +- **删除保留历史：**delete 移除当前反馈，不会从只追加日志中清除更早的评分或备注；它不是隐私擦除操作。 +- **写入所有权：**另一个进程持有 Session 写 handle 时，冷会话修改会 reject。服务不会唤醒该所有者，也不协调跨进程 Remote 调用。 +- **受信任调用方：**请求不包含经过认证的 actor 或审计身份。部署方必须保护 Host gateway。 +- **遥测导出：**随附的 OTel 配置行处于禁用状态。启用后，`FULL` 会实时导出反馈事件；`FEEDBACK_ONLY` 则在 `/feedback` 时释放尚未导出的权威日志前缀，包括 message-feedback 评分和原样备注，而不只是命令文本。部署方负责脱敏；见 [OTel 导出策略](../../session/session-telemetry-otel/README.zh.md)。 +- **扫描成本：**每次访问已有 Session 的 `list`、`put` 或 `delete` 都会扫描完整事件日志来推导当前反馈；冷会话操作还会从持久化存储读取完整日志。工作量随 Session 历史总量增长，而不只是反馈条目数。 +- **保留量：**`maxNoteBytes` 只限制单条备注，不限制日志总大小或修改次数。 ### 开发备注 -
-维护者的工作上下文——点击展开 - -本开发备注是维护者的工作上下文，明确不具权威性。已交付的行为、限制与理由以上文、包代码与所链接的 Agent Note 为准。 - -- 浏览器控件与客户端 Remote 挂载位于 `dsh-client-ui-message-feedback` 与 `dsh-api-remotes`；它们的开放事项属于这些包的备注。 -- 受信任调用方限制是开放的授权方向：Host gateway 不记录任何 actor 或审计身份，任何认证层都必须在部署边界落地，之后服务才能暴露按用户归属。 -- 按设计，备注校验早于 Session 查找，因此对不存在的 Session，`note-blank` 与 `note-too-large` 优先于 `session-not-found`；测试固定了这一顺序。 - -
+[包测试](tests/message-feedback.spec.ts)覆盖当前状态与持久历史语义；[Loader 组合](tests/loader-composition.spec.ts)验证跨重启的活跃和冷 JSONL 操作。 diff --git a/packages/feedback/message-feedback/package.json b/packages/feedback/message-feedback/package.json index 0b5c98ffd7..1f3834d036 100644 --- a/packages/feedback/message-feedback/package.json +++ b/packages/feedback/message-feedback/package.json @@ -1,6 +1,6 @@ { "name": "@deepseek-ai/dsh-message-feedback", - "description": "Lifecycle-bound per-message rating and note sidecar for the DeepSeek Harness", + "description": "Canonical Session-log ratings and notes for finalized assistant messages", "version": "0.1.3-alpha.1", "publishConfig": { "access": "public" @@ -48,7 +48,6 @@ "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/dsh-session-persistence": "workspace:^", - "@deepseek-ai/dsh-storage-domain": "workspace:^", "@deepseek-ai/dsh-typert-protocol": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, @@ -64,9 +63,6 @@ "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/dsh-session-persistence": "workspace:^", "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^", - "@deepseek-ai/dsh-storage": "workspace:^", - "@deepseek-ai/dsh-storage-domain": "workspace:^", - "@deepseek-ai/dsh-storage-json": "workspace:^", "@deepseek-ai/dsh-typert-protocol": "workspace:^", "@deepseek-ai/cordis": "workspace:^" } diff --git a/packages/feedback/message-feedback/src/index.ts b/packages/feedback/message-feedback/src/index.ts index 8808b199bb..847f59f019 100644 --- a/packages/feedback/message-feedback/src/index.ts +++ b/packages/feedback/message-feedback/src/index.ts @@ -1,29 +1,27 @@ /** - * Durable, lifecycle-bound feedback for finalized assistant messages. + * Canonical Session-log feedback for finalized assistant messages. * @module @deepseek-ai/dsh-message-feedback */ import { Buffer } from 'node:buffer' import { randomUUID } from 'node:crypto' +import { isDeepStrictEqual } from 'node:util' import { Context, Service } from '@deepseek-ai/cordis' import s from '@deepseek-ai/schemastery' +import { z } from 'zod' +import { SessionSeq } from '@deepseek-ai/dsh-session/types' import { deriveEventMessage, isAppendSurfaceEvent } from '@deepseek-ai/dsh-session/surface' -import type { SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session/types' +import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session/types' import type {} from '@deepseek-ai/dsh-session' import type {} from '@deepseek-ai/dsh-session-persistence' -import type { KvTable } from '@deepseek-ai/dsh-storage-domain' import { TypertRemoteService, Remote } from '@deepseek-ai/dsh-typert-protocol' -import { messageFeedbackDomainSpec } from './spec.ts' -import type { MessageFeedbackRow, MessageFeedbackSessionIdentity } from './spec.ts' import type { MessageFeedbackDeleteRequest, MessageFeedbackDeleteResult, - MessageFeedbackDeleteValue, MessageFeedbackFailure, MessageFeedbackItem, MessageFeedbackListRequest, MessageFeedbackListResult, - MessageFeedbackListValue, MessageFeedbackNoteBlank, MessageFeedbackNoteTooLarge, MessageFeedbackPutRequest, @@ -36,15 +34,6 @@ import type { } from './types.ts' export type * from './types.ts' -export { - messageFeedbackDomainSpec, - messageFeedbackItemSchema, - messageFeedbackRatingSchema, - messageFeedbackRowSchema, - messageFeedbackSessionIdentitySchema, - messageFeedbackVersionSchema, -} from './spec.ts' -export type { MessageFeedbackRow, MessageFeedbackSessionIdentity } from './spec.ts' /** Required deployment policy for optional notes. */ export interface Config { @@ -58,104 +47,63 @@ declare module '@deepseek-ai/cordis' { } } -/** Immutable empty list reused only as an input to caller-owned copying. */ -const EMPTY_ITEMS: readonly MessageFeedbackItem[] = Object.freeze([]) +const timestamp = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER) +const itemSchema = z.object({ + messageId: z.string().min(1), + rating: z.enum(['positive', 'negative']), + note: z.string().refine(note => note.trim().length > 0).optional(), + version: z.uuid(), + createdAt: timestamp, + updatedAt: timestamp, +}).refine(item => item.updatedAt >= item.createdAt) +const putSchema = z.object({ sessionId: z.string().min(1), item: itemSchema }) +const deleteSchema = z.object({ sessionId: z.string().min(1), messageId: z.string().min(1) }) -/** Validate the one deployment-varying limit at the configuration boundary. */ -function resolveMaxNoteBytes(value: number): number { - if (!Number.isSafeInteger(value) || value < 1) { - throw new TypeError( - `message-feedback: maxNoteBytes must be a positive safe integer, got ${String(value)}`, - ) - } - return value -} +type FeedbackEvent = SessionEvent<'feedback/message-put' | 'feedback/message-delete'> +type Mutation = Pick, 'type' | 'data'> + | Pick, 'type' | 'data'> +type Append = (event?: Mutation) => Promise +type MissingSession = MessageFeedbackRejected +type ResolvedNote = MessageFeedbackSuccess + | MessageFeedbackRejected -/** Copy and freeze one item before it crosses the service boundary. */ +/** Return a caller-owned immutable value, detached from the log. */ function snapshotItem(item: MessageFeedbackItem): MessageFeedbackItem { - return Object.freeze({ - messageId: item.messageId, - rating: item.rating, - ...(item.note === undefined ? {} : { note: item.note }), - version: item.version, - createdAt: item.createdAt, - updatedAt: item.updatedAt, - }) + return Object.freeze({ ...item }) } -/** Copy and freeze a list response. */ -function snapshotList(items: readonly MessageFeedbackItem[]): MessageFeedbackListValue { - return Object.freeze({ items: Object.freeze(items.map(snapshotItem)) }) -} - -/** Build a frozen success branch. */ function success(value: T): MessageFeedbackSuccess { return Object.freeze({ ok: true, value }) } -/** Build a frozen business-failure branch. */ function rejected(error: E): MessageFeedbackRejected { return Object.freeze({ ok: false, error: Object.freeze(error) }) } -/** Project the Session fields that distinguish one persisted log lifecycle. */ -function identityOf(header: SessionHeader): MessageFeedbackSessionIdentity { - return Object.freeze({ - createdAt: header.createdAt, - ...(header.cwd === undefined ? {} : { cwd: header.cwd }), - }) +/** Validate persisted payloads before deriving current, Session-owned feedback. */ +function currentItems(sessionId: SessionId, events: readonly SessionEvent[]): MessageFeedbackItem[] { + const items = new Map() + for (const event of events) { + switch (event.type) { + case 'feedback/message-put': + putSchema.parse(event.data) + if (event.data.sessionId === sessionId) items.set(event.data.item.messageId, event.data.item) + break + case 'feedback/message-delete': + deleteSchema.parse(event.data) + if (event.data.sessionId === sessionId) items.delete(event.data.messageId) + break + default: + // Other plugins' events do not change message feedback. + break + } + } + return [...items.values()] } -/** Whether a stored row belongs to the inspected Session lifecycle. */ -function sameIdentity(row: MessageFeedbackRow, header: SessionHeader): boolean { - return row.session.createdAt === header.createdAt && row.session.cwd === header.cwd -} - -/** Whether two observations name the same persisted Session lifecycle. */ -function sameHeaderIdentity(left: SessionHeader, right: SessionHeader): boolean { - return left.id === right.id && left.createdAt === right.createdAt && left.cwd === right.cwd -} - -/** Freeze the replacement row so storage-domain never exposes mutable aliases. */ -function rowSnapshot( - session: MessageFeedbackSessionIdentity, - items: readonly MessageFeedbackItem[], -): MessageFeedbackRow { - const copiedItems = items.map(snapshotItem) - Object.freeze(copiedItems) - return Object.freeze({ - session, - items: copiedItems, - }) -} - -/** Generate an opaque equality token for one material mutation. */ -function nextVersion(): MessageFeedbackVersion { - return randomUUID() as MessageFeedbackVersion -} - -/** Observed session view: header identity plus the logged events. */ -interface SessionObservation { - readonly meta: SessionHeader - readonly events: readonly SessionEvent[] -} - -/** Session observation result that keeps absence inside the business union. */ -type KnownSession = - | MessageFeedbackSuccess - | MessageFeedbackRejected - -/** Validated note or one explicit request failure. */ -type ResolvedNote = - | MessageFeedbackSuccess - | MessageFeedbackRejected - -/** - * Storage-domain sidecar service. It inspects persisted Session history and - * never creates or resumes an Agent or Session. - */ +/** Session-log service; cold operations never construct a Session or Agent. */ export class MessageFeedbackService extends TypertRemoteService { - static inject = ['storageDomain', 'sessionPersistence', 'sessions'] + static inject = ['sessionPersistence', 'sessions'] /** Loader validation for the required note-size policy. */ static Config: s = s.object({ @@ -163,205 +111,151 @@ export class MessageFeedbackService extends TypertRemoteService { }) private readonly maxNoteBytes: number - private table?: KvTable private readonly operationTails = new Map>() private mutationAdmissionOpen = true /** - * @param ctx - Host context carrying persistence and the storage-domain form. + * @param ctx - Host context carrying Session persistence and live owners. * @param config - Required note-size policy. */ constructor(ctx: Context, config: Config) { super(ctx, 'messageFeedback') - this.maxNoteBytes = resolveMaxNoteBytes(config.maxNoteBytes) + if (!Number.isSafeInteger(config.maxNoteBytes) || config.maxNoteBytes < 1) { + throw new TypeError('message-feedback: maxNoteBytes must be a positive safe integer') + } + this.maxNoteBytes = config.maxNoteBytes } - /** Open and own the one message-feedback sidecar domain. */ - protected async [Service.init](): Promise { - const domain = await this.ctx.storageDomain.open(messageFeedbackDomainSpec) + protected [Service.init](): void { this.ctx.effect(() => async () => { this.mutationAdmissionOpen = false await Promise.all(this.operationTails.values()) - await domain.close() - }, 'message-feedback.domainClose') - this.table = domain.table('sessions') + }, 'message-feedback.drain') } /** - * Read feedback belonging to the current persisted Session lifecycle. - * A stale row from a reused Session id is invisible. - * @param request - Session identity to inspect and list. - * @returns current immutable items or `session-not-found`. + * Read current feedback from the canonical log. + * @param request - Session to inspect. + * @returns immutable items or a definite persistence miss. */ @Remote('list') - async list(request: MessageFeedbackListRequest): Promise { - const known = await this.inspectSession(request.sessionId) - if (!known.ok) return known - const row = this.requireTable().get(request.sessionId) - const items = row !== undefined && sameIdentity(row, known.value.meta) ? row.items : EMPTY_ITEMS - return success(snapshotList(items)) + list(request: MessageFeedbackListRequest): Promise { + return this.enqueue(request.sessionId, () => this.withSession(request.sessionId, false, events => + success(Object.freeze({ items: Object.freeze(currentItems(request.sessionId, events).map(snapshotItem)) })))) } /** - * Create or replace feedback for one derived append-origin assistant - * message. Every request must match the addressed item's current version; - * a matching no-op returns the stored item without changing its revision. - * @param request - target, desired value, and observed item version. - * @returns the committed item or an explicit business failure. + * Create or replace feedback after checking its current version. + * Matching no-ops retain the version and append no event. + * @param request - Target, desired value, and observed item version. + * @returns the durable item or an explicit business failure. */ @Remote('put') put(request: MessageFeedbackPutRequest): Promise { const note = this.resolveNote(request.note) if (!note.ok) return Promise.resolve(note) - return this.enqueue(request.sessionId, async () => { - const known = await this.inspectSession(request.sessionId) - if (!known.ok) return known - if (!this.hasFeedbackTarget(known.value, request.messageId)) { - return rejected({ - code: 'target-not-found', - sessionId: request.sessionId, - messageId: request.messageId, - }) + return this.enqueue(request.sessionId, () => this.withSession(request.sessionId, true, async (events, append) => { + const items = currentItems(request.sessionId, events) + if (!events.some(event => event.type === 'assistant/message' + && isAppendSurfaceEvent(event) + && deriveEventMessage(event)?.id === request.messageId)) { + return rejected({ code: 'target-not-found', sessionId: request.sessionId, messageId: request.messageId }) } - - const durable = await this.ensureTargetDurable(known.value) - if (!sameHeaderIdentity(durable.meta, known.value.meta) - || !this.hasFeedbackTarget(durable, request.messageId)) { - return rejected({ - code: 'target-not-found', - sessionId: request.sessionId, - messageId: request.messageId, - }) - } - - const table = this.requireTable() - const stored = table.get(request.sessionId) - const current = stored !== undefined && sameIdentity(stored, durable.meta) ? stored : undefined - const items = current?.items ?? EMPTY_ITEMS - const index = items.findIndex(item => item.messageId === request.messageId) - const existing = items[index] + const existing = items.find(item => item.messageId === request.messageId) if (request.ifVersion !== (existing?.version ?? null)) { return rejected(this.versionConflict(existing ?? null)) } - if (existing !== undefined - && existing.rating === request.rating - && existing.note === note.value) { + if (existing !== undefined && existing.rating === request.rating && existing.note === note.value) { + await append() return success(snapshotItem(existing)) } - const now = Date.now() - const item = snapshotItem({ + const item: MessageFeedbackItem = { messageId: request.messageId, rating: request.rating, ...(note.value === undefined ? {} : { note: note.value }), - version: nextVersion(), + version: randomUUID() as MessageFeedbackVersion, createdAt: existing?.createdAt ?? now, updatedAt: existing === undefined ? now : Math.max(now, existing.updatedAt), - }) - const nextItems = [...items] - if (index === -1) nextItems.push(item) - else nextItems[index] = item - await table.put( - request.sessionId, - rowSnapshot(identityOf(durable.meta), nextItems), - ) + } + await append({ type: 'feedback/message-put', data: { sessionId: request.sessionId, item } }) return success(snapshotItem(item)) - }) + })) } /** - * Delete one feedback item. Absence is successful regardless of the - * supplied version; an existing item requires an exact version match. + * Delete one item after checking its version; absence succeeds without an event. * @param request - Session, message, and observed item version. - * @returns the stable absent postcondition, or an explicit failure. + * @returns the stable absent postcondition or an explicit failure. */ @Remote('delete') delete(request: MessageFeedbackDeleteRequest): Promise { - return this.enqueue(request.sessionId, async () => { - const known = await this.inspectSession(request.sessionId) - if (!known.ok) return known - - const table = this.requireTable() - const stored = table.get(request.sessionId) - const current = stored !== undefined && sameIdentity(stored, known.value.meta) ? stored : undefined - const items = current?.items ?? EMPTY_ITEMS - const existing = items.find(item => item.messageId === request.messageId) - if (existing === undefined) { - return success(Object.freeze({ absent: true })) + return this.enqueue(request.sessionId, () => this.withSession(request.sessionId, true, async (events, append) => { + const existing = currentItems(request.sessionId, events).find(item => item.messageId === request.messageId) + if (existing !== undefined) { + if (request.ifVersion !== existing.version) return rejected(this.versionConflict(existing)) + await append({ type: 'feedback/message-delete', data: { sessionId: request.sessionId, messageId: request.messageId } }) + } else { + await append() } - if (request.ifVersion !== existing.version) { - return rejected(this.versionConflict(existing)) - } - - await table.put( - request.sessionId, - rowSnapshot(identityOf(known.value.meta), items.filter(item => item !== existing)), - ) - return success(Object.freeze({ absent: true })) - }) + return success(Object.freeze({ absent: true as const })) + })) } - /** - * Resolve a live owner directly; otherwise use `stat` as the existence - * authority before reading the log. Read failures for a Session that `stat` - * confirmed remain infrastructure failures rather than being guessed into - * the business `session-not-found` branch. - */ - private async inspectSession(sessionId: SessionId): Promise { - if (this.ctx.sessions.get(sessionId) === undefined) { - if (await this.ctx.sessionPersistence.stat(sessionId) === undefined - && this.ctx.sessions.get(sessionId) === undefined) { - return rejected({ code: 'session-not-found', sessionId }) - } + /** Hold cold write ownership across read/compare/append; use live owners directly. */ + private async withSession( + sessionId: SessionId, + write: boolean, + operation: (events: readonly SessionEvent[], append: Append) => T | Promise, + ): Promise { + if (this.ctx.sessions.get(sessionId) === undefined + && await this.ctx.sessionPersistence.stat(sessionId) === undefined + && this.ctx.sessions.get(sessionId) === undefined) { + return rejected({ code: 'session-not-found', sessionId }) } - return success(await this.observeSession(sessionId)) - } - - /** Observe a live owner's in-memory log when one exists, else the durable log. */ - private async observeSession(sessionId: SessionId): Promise { const live = this.ctx.sessions.get(sessionId) - if (live !== undefined) return { meta: live.header, events: live.snapshotEvents() } - return await this.readDurable(sessionId) - } - - /** Read the complete durable log prefix through a fresh read handle. */ - private async readDurable(sessionId: SessionId): Promise { - const handle = await this.ctx.sessionPersistence.open(sessionId, 'read') + if (live !== undefined) { + return operation(live.snapshotEvents(), async (event) => { + if (event !== undefined) { + live.append(event.type, event.data) + } + const last = live.snapshotEvents().at(-1) + if (!(await this.ctx.sessions.flush(live))) { + throw new Error( + `message-feedback: no durability listener participated for live session '${sessionId}'`, + ) + } + // Listener participation alone does not prove this Session has a persistence writer. + const handle = await this.ctx.sessionPersistence.open(sessionId, 'read') + try { + const stored = await handle.read(last?.seq ?? 0, 1) + if (!isDeepStrictEqual( + [handle.header.id, handle.header.createdAt, handle.header.cwd], + [live.header.id, live.header.createdAt, live.header.cwd], + ) + || (last !== undefined && !isDeepStrictEqual(stored[0], last))) { + throw new Error(`message-feedback: feedback prefix is not durable for live session '${sessionId}'`) + } + } finally { + await handle.close() + } + }) + } + const handle = await this.ctx.sessionPersistence.open(sessionId, write ? 'write' : 'read') try { - return { meta: handle.header, events: await handle.read() } + const events = await handle.read() + return await operation(events, async (event) => { + if (event !== undefined) { + const entry: FeedbackEvent = { ...event, seq: SessionSeq(events.length), time: Date.now() } + await handle.append([entry]) + } + await handle.flush() + }) } finally { await handle.close() } } - /** Require the exact finalized append-origin assistant message projection. */ - private hasFeedbackTarget(observation: SessionObservation, messageId: MessageFeedbackItem['messageId']): boolean { - return observation.events.some((event) => { - if (event.type !== 'assistant/message' || !isAppendSurfaceEvent(event)) return false - const message = deriveEventMessage(event) - return message?.role === 'assistant' && message.id === messageId - }) - } - - /** - * Put the target log prefix behind a durability barrier before its sidecar. - * A live owner flushes through the SessionStore's canonical checkpoint; the - * physical durable prefix is then re-read, which observes at least the - * flushed prefix by the `SessionPersistence` freshness guarantee. - */ - private async ensureTargetDurable(observation: SessionObservation): Promise { - const live = this.ctx.sessions.get(observation.meta.id) - if (live !== undefined && sameHeaderIdentity(live.header, observation.meta)) { - if (!(await this.ctx.sessions.flush(live))) { - throw new Error( - `message-feedback: no durability listener participated for live session '${observation.meta.id}'`, - ) - } - } - return await this.readDurable(observation.meta.id) - } - - /** Validate optional-note semantics and the configured complete UTF-8 byte bound. */ private resolveNote(note: string | undefined): ResolvedNote { if (note === undefined) return success(undefined) if (note.trim().length === 0) return rejected({ code: 'note-blank' }) @@ -372,19 +266,13 @@ export class MessageFeedbackService extends TypertRemoteService { return success(note) } - /** Return the authoritative item needed to reconcile one failed comparison. */ private versionConflict(current: MessageFeedbackItem | null): MessageFeedbackVersionConflict { - return { - code: 'version-conflict', - current: current === null ? null : snapshotItem(current), - } + return { code: 'version-conflict', current: current === null ? null : snapshotItem(current) } } - /** Queue a complete read/compare/write mutation behind this Session's prior mutation. */ + /** Serialize complete operations and drain their handles before disposal. */ private enqueue(sessionId: SessionId, operation: () => Promise): Promise { - if (!this.mutationAdmissionOpen) { - return Promise.reject(new Error('message-feedback: service is disposing')) - } + if (!this.mutationAdmissionOpen) return Promise.reject(new Error('message-feedback: service is disposing')) const previous = this.operationTails.get(sessionId) ?? Promise.resolve() const result = previous.then(operation) const tail = result.then(() => undefined, () => undefined) @@ -393,14 +281,6 @@ export class MessageFeedbackService extends TypertRemoteService { if (this.operationTails.get(sessionId) === tail) this.operationTails.delete(sessionId) }) } - - /** Resolve the initialized durable table or fail a broken service lifecycle. */ - private requireTable(): KvTable { - if (this.table === undefined) { - throw new Error('message-feedback: durable domain is not initialized') - } - return this.table - } } export default MessageFeedbackService diff --git a/packages/feedback/message-feedback/src/spec.ts b/packages/feedback/message-feedback/src/spec.ts deleted file mode 100644 index d08a536d06..0000000000 --- a/packages/feedback/message-feedback/src/spec.ts +++ /dev/null @@ -1,90 +0,0 @@ -/** - * Durable storage-domain declaration for lifecycle-bound message feedback. - * @module @deepseek-ai/dsh-message-feedback/src/spec - */ - -import { z } from 'zod' -import type { MessageId } from '@deepseek-ai/dsh-llm/brand' -import type { SessionId } from '@deepseek-ai/dsh-session/types' -import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain' -import type { MessageFeedbackItem, MessageFeedbackRating, MessageFeedbackVersion } from './types.ts' - -const nonNegativeSafeInteger = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER) - -/** Runtime schema for the closed rating vocabulary. */ -export const messageFeedbackRatingSchema = z.union([ - z.literal('positive'), - z.literal('negative'), -]) satisfies z.ZodType - -/** Runtime schema for one opaque item version stored on disk. */ -export const messageFeedbackVersionSchema = z.uuid() - .transform(value => value as MessageFeedbackVersion) - -/** Runtime schema for one current feedback item. */ -// Zod infers transformed branded fields structurally, so it cannot name the -// public interface even though every branded output is created below. -export const messageFeedbackItemSchema = z.object({ - messageId: z.string().min(1).transform(value => value as MessageId), - rating: messageFeedbackRatingSchema, - note: z.string().refine(note => note.trim().length > 0, { - message: 'message feedback note must contain a non-whitespace character', - }).optional(), - version: messageFeedbackVersionSchema, - createdAt: nonNegativeSafeInteger, - updatedAt: nonNegativeSafeInteger, -}).refine(item => item.updatedAt >= item.createdAt, { - path: ['updatedAt'], - message: 'message feedback updatedAt must not precede createdAt', -}) as unknown as z.ZodType - -/** Persisted Session fields that fence a sidecar row to one log lifecycle. */ -export const messageFeedbackSessionIdentitySchema = z.object({ - createdAt: nonNegativeSafeInteger, - cwd: z.string().optional(), -}) - -/** Persisted lifecycle identity inferred from its durable schema. */ -export type MessageFeedbackSessionIdentity = z.infer - -/** - * One whole-Session sidecar. Duplicate message ids would make item lookup - * ambiguous; duplicate versions would break their independent identity. - */ -export const messageFeedbackRowSchema = z.object({ - session: messageFeedbackSessionIdentitySchema, - items: z.array(messageFeedbackItemSchema), -}).superRefine((row, ctx) => { - const messageIds = new Set() - const versions = new Set() - row.items.forEach((item, index) => { - if (messageIds.has(item.messageId)) { - ctx.addIssue({ - code: 'custom', - path: ['items', index, 'messageId'], - message: `duplicate message feedback id '${item.messageId}'`, - }) - } - messageIds.add(item.messageId) - if (versions.has(item.version)) { - ctx.addIssue({ - code: 'custom', - path: ['items', index, 'version'], - message: `duplicate message feedback version '${item.version}'`, - }) - } - versions.add(item.version) - }) -}) - -/** Durable sidecar row inferred from {@link messageFeedbackRowSchema}. */ -export type MessageFeedbackRow = z.infer - -/** One lifecycle-bound sidecar record per Session id. */ -export const messageFeedbackDomainSpec = defineDomain({ - name: 'message_feedback', - version: 0, - tables: { - sessions: domainTable(messageFeedbackRowSchema), - }, -}) diff --git a/packages/feedback/message-feedback/src/types.ts b/packages/feedback/message-feedback/src/types.ts index 0be57b17b4..c954724881 100644 --- a/packages/feedback/message-feedback/src/types.ts +++ b/packages/feedback/message-feedback/src/types.ts @@ -31,9 +31,34 @@ export interface MessageFeedbackItem { readonly updatedAt: number } +/** A material creation or edit, retaining its complete current value. */ +export interface MessageFeedbackPut { + /** Owning Session; inherited feedback in a fork belongs to its parent. */ + readonly sessionId: SessionId + /** Value after this mutation, including the original creation time. */ + readonly item: MessageFeedbackItem +} + +/** A material deletion of one current feedback item. */ +export interface MessageFeedbackDelete { + /** Session that owns the deleted feedback. */ + readonly sessionId: SessionId + /** Message whose feedback was removed. */ + readonly messageId: MessageId +} + +declare module '@deepseek-ai/dsh-session/types' { + interface SessionEventMap { + /** Log-only human feedback; never enters model history. */ + 'feedback/message-put': MessageFeedbackPut + /** Log-only deletion; earlier ratings and notes remain in the log. */ + 'feedback/message-delete': MessageFeedbackDelete + } +} + /** Read all message feedback belonging to one persisted Session lifecycle. */ export interface MessageFeedbackListRequest { - /** Persisted Session whose sidecar should be read. */ + /** Session whose feedback events should be read. */ readonly sessionId: SessionId } @@ -59,7 +84,7 @@ export interface MessageFeedbackPutRequest { /** Delete feedback for one message after observing its current version. */ export interface MessageFeedbackDeleteRequest { - /** Persisted Session that owns the sidecar. */ + /** Session that owns the feedback. */ readonly sessionId: SessionId /** Message whose feedback should be absent after this operation. */ readonly messageId: MessageId diff --git a/packages/feedback/message-feedback/tests/helpers.ts b/packages/feedback/message-feedback/tests/helpers.ts index 3759db032d..61cc6832f0 100644 --- a/packages/feedback/message-feedback/tests/helpers.ts +++ b/packages/feedback/message-feedback/tests/helpers.ts @@ -21,9 +21,6 @@ import SessionPersistence, { type SessionHandle, type SessionPersistenceSnapshot, } from '@deepseek-ai/dsh-session-persistence' -import Storage from '@deepseek-ai/dsh-storage' -import * as StorageDomain from '@deepseek-ai/dsh-storage-domain' -import * as StorageJson from '@deepseek-ai/dsh-storage-json' import MessageFeedbackService from '../src/index.ts' export interface MessageFixture { @@ -110,6 +107,11 @@ interface StoredSession { class TestPersistence extends SessionPersistence { readonly durable = new Map() readFailure: Error | undefined + appendFailure: Error | undefined + flushFailure: Error | undefined + openCalls: SessionAccess[] = [] + closeCalls = 0 + appendCalls = 0 statCalls = 0 readCalls = 0 onRead: (() => void | Promise) | undefined @@ -126,6 +128,7 @@ class TestPersistence extends SessionPersistence { async flush(): Promise {} async open(id: SessionId, access: SessionAccess): Promise { + this.openCalls.push(access) const stored = this.durable.get(id) if (stored === undefined) throw new SessionPersistenceNotFoundError(id) return this.handle(stored, access) @@ -164,13 +167,16 @@ class TestPersistence extends SessionPersistence { append: async (events) => { if (closed) throw new SessionHandleClosedError(stored.meta.id, 'append') if (access !== 'write') throw new SessionReadOnlyError(stored.meta.id, 'append') + if (this.appendFailure !== undefined) throw this.appendFailure + this.appendCalls += 1 stored.events = [...stored.events, ...events] }, flush: async () => { if (closed) throw new SessionHandleClosedError(stored.meta.id, 'flush') if (access !== 'write') throw new SessionReadOnlyError(stored.meta.id, 'flush') + if (this.flushFailure !== undefined) throw this.flushFailure }, - close: async () => { closed = true }, + close: async () => { closed = true; this.closeCalls += 1 }, [Symbol.asyncDispose]() { return handle.close() }, } return handle @@ -193,7 +199,7 @@ export interface TestHarness { dispose(): Promise } -/** Compose the service over the real storage hub/domain/JSON backend. */ +/** Compose feedback over a controllable Session persistence backend. */ export async function setupHarness(maxNoteBytes = 64): Promise { const root = await mkdtemp(join(tmpdir(), 'dsh-message-feedback-test-')) const ctx = new Context() @@ -201,9 +207,6 @@ export async function setupHarness(maxNoteBytes = 64): Promise { try { await ctx.plugin(SessionStore) await ctx.plugin(TestPersistence) - await ctx.plugin(Storage) - await ctx.plugin(StorageJson, { root }) - await ctx.plugin(StorageDomain, { backend: 'json' }) const feedbackFiber = await ctx.plugin(MessageFeedbackService, { maxNoteBytes }) disposeFeedback = feedbackFiber.dispose } catch (error) { diff --git a/packages/feedback/message-feedback/tests/loader-composition.spec.ts b/packages/feedback/message-feedback/tests/loader-composition.spec.ts index 5fc528360b..f83eaefa34 100644 --- a/packages/feedback/message-feedback/tests/loader-composition.spec.ts +++ b/packages/feedback/message-feedback/tests/loader-composition.spec.ts @@ -8,9 +8,6 @@ import Include from '@deepseek-ai/cordis-plugin-include' import Loader from '@deepseek-ai/cordis-plugin-loader' import SessionStore, { SessionId } from '@deepseek-ai/dsh-session' import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl' -import Storage from '@deepseek-ai/dsh-storage' -import * as StorageDomain from '@deepseek-ai/dsh-storage-domain' -import * as StorageJson from '@deepseek-ai/dsh-storage-json' import { remoteMethods } from '@deepseek-ai/dsh-typert-protocol' import MessageFeedbackService from '../src/index.ts' import { appendMessageFixture } from './helpers.ts' @@ -32,9 +29,6 @@ async function loadComposition(configPath: string): Promise { const modules = new Map([ ['@deepseek-ai/dsh-session', SessionStore], ['@deepseek-ai/dsh-session-persistence-jsonl', JsonlSessionPersistence], - ['@deepseek-ai/dsh-storage', Storage], - ['@deepseek-ai/dsh-storage-json', StorageJson], - ['@deepseek-ai/dsh-storage-domain', StorageDomain], ['@deepseek-ai/dsh-message-feedback', MessageFeedbackService], ]) ctx.loader.internal = { @@ -57,7 +51,7 @@ async function loadComposition(configPath: string): Promise { } describe('message feedback through a real Loader composition', () => { - it('persists a checkpointed target and its sidecar across a cold restart', async () => { + it('persists canonical feedback across live and cold operations', async () => { root = await mkdtemp(join(tmpdir(), 'dsh-message-feedback-loader-')) const configPath = join(root, 'cordis.yml') await writeFile(configPath, [ @@ -66,13 +60,6 @@ describe('message feedback through a real Loader composition', () => { ' config:', ` root: ${JSON.stringify(join(root, 'sessions'))}`, ' compression: none', - "- name: '@deepseek-ai/dsh-storage'", - "- name: '@deepseek-ai/dsh-storage-json'", - ' config:', - ` root: ${JSON.stringify(join(root, 'storage'))}`, - "- name: '@deepseek-ai/dsh-storage-domain'", - ' config:', - ' backend: json', "- name: '@deepseek-ai/dsh-message-feedback'", ' config:', ' maxNoteBytes: 32', @@ -84,6 +71,19 @@ describe('message feedback through a real Loader composition', () => { expect(remoteMethods(first.messageFeedback).map(marker => marker.method)) .toEqual(['list', 'put', 'delete']) + const unowned = first.sessions.create(SessionId('unowned-feedback')) + const unownedFixture = appendMessageFixture(unowned) + const unownedRequest = { + sessionId: unowned.id, messageId: unownedFixture.assistantMessageIds[0], rating: 'positive' as const, ifVersion: null, + } + // A mounted JSONL listener alone does not persist Sessions without a write handle. + await expect(first.messageFeedback.put(unownedRequest)).rejects.toThrow(/not found/u) + expect(await first.sessionPersistence.stat(unowned.id)).toBeUndefined() + const unownedItems = await first.messageFeedback.list({ sessionId: unowned.id }) + if (!unownedItems.ok) throw new Error(unownedItems.error.code) + await expect(first.messageFeedback.put({ ...unownedRequest, ifVersion: unownedItems.value.items[0]!.version })) + .rejects.toThrow(/not found/u) + const session = first.sessions.create(SessionId('loader-feedback'), { meta: { cwd: root }, }) @@ -115,6 +115,23 @@ describe('message feedback through a real Loader composition', () => { ok: true, value: { items: [put.value] }, }) + const edited = await second.messageFeedback.put({ + sessionId: session.id, + messageId: fixture.assistantMessageIds[0], + rating: 'negative', + note: 'cold edit', + ifVersion: put.value.version, + }) + if (!edited.ok) throw new Error(edited.error.code) + await second.messageFeedback.delete({ sessionId: session.id, messageId: edited.value.messageId, ifVersion: edited.value.version }) + const coldHandle = await second.sessionPersistence.open(session.id, 'read') + try { + const coldEvents = await coldHandle.read() + expect(coldEvents.slice(0, durableEvents.length)).toEqual(durableEvents) + expect(coldEvents.slice(durableEvents.length).map(event => event.type)).toEqual(['feedback/message-put', 'feedback/message-delete']) + } finally { + await coldHandle.close() + } expect(second.sessions.get(session.id)).toBeUndefined() }) }) diff --git a/packages/feedback/message-feedback/tests/message-feedback.spec.ts b/packages/feedback/message-feedback/tests/message-feedback.spec.ts index e623f6fa5a..7a94fefca2 100644 --- a/packages/feedback/message-feedback/tests/message-feedback.spec.ts +++ b/packages/feedback/message-feedback/tests/message-feedback.spec.ts @@ -2,9 +2,9 @@ import { randomUUID } from 'node:crypto' import { afterEach, describe, expect, it, vi } from 'vitest' import { Context } from '@deepseek-ai/cordis' import type { MessageId } from '@deepseek-ai/dsh-llm/brand' -import { Session, SessionId } from '@deepseek-ai/dsh-session' +import { Session, SessionId, SessionLogOffset, SessionSeq, type SessionEvent } from '@deepseek-ai/dsh-session' import { remoteMethods } from '@deepseek-ai/dsh-typert-protocol' -import MessageFeedbackService, { messageFeedbackRowSchema } from '../src/index.ts' +import MessageFeedbackService from '../src/index.ts' import type { MessageFeedbackItem, MessageFeedbackVersion, @@ -247,59 +247,32 @@ describe('MessageFeedbackService public contract', () => { })) }) - it('fails invalid direct configuration and a read before domain initialization', async () => { - const invalidCtx = new Context() - expect(() => new MessageFeedbackService(invalidCtx, { maxNoteBytes: 0 })) - .toThrow(/positive safe integer/u) - await invalidCtx.fiber.dispose() - - const fixture = messageFixture('uninitialized-domain') - const rawCtx = new Context() - rawCtx.provide('sessions', { get: () => undefined } as never) - rawCtx.provide('sessionPersistence', { - stat: () => Promise.resolve({ header: fixture.session.header, revision: 'test' }), - open: () => Promise.resolve({ - header: fixture.session.header, - read: () => Promise.resolve(fixture.session.snapshotEvents()), - close: () => Promise.resolve(), - }), - } as never) - const raw = new MessageFeedbackService(rawCtx, { maxNoteBytes: 1 }) - await expect(raw.list({ sessionId: fixture.session.id })) - .rejects.toThrow(/durable domain is not initialized/u) - await rawCtx.fiber.dispose() + it('rejects invalid configuration', async () => { + const ctx = new Context() + try { + expect(() => new MessageFeedbackService(ctx, { maxNoteBytes: 0 })).toThrow(/positive safe integer/u) + } finally { + await ctx.fiber.dispose() + } }) - it('rejects durable rows with duplicate message ids or reused item versions', () => { - const version = staleVersion() - const duplicate = messageFeedbackRowSchema.safeParse({ - session: { createdAt: 1 }, - items: [ - { - messageId: 'same-message', - rating: 'positive', - version, - createdAt: 1, - updatedAt: 1, - }, - { - messageId: 'same-message', - rating: 'negative', - version, - createdAt: 1, - updatedAt: 1, - }, - ], - }) - expect(duplicate.success).toBe(false) - if (duplicate.success) throw new Error('expected duplicate row rejection') - expect(duplicate.error.issues.map(issue => issue.path.join('.'))) - .toEqual(['items.1.messageId', 'items.1.version']) - }) }) describe('MessageFeedbackService item concurrency', () => { - it('serializes whole-row writes while keeping versions independent per message', async () => { + it('allows only one of two concurrent creates for the same message', async () => { + const { ctx, persistence } = await harness() + const fixture = messageFixture('same-item-race') + persistence.persist(fixture.session) + const request = { + sessionId: fixture.session.id, messageId: fixture.assistantMessageIds[0], rating: 'positive' as const, ifVersion: null, + } + const [first, second] = await Promise.all([ctx.messageFeedback.put(request), ctx.messageFeedback.put(request)]) + const item = expectItem(first) + expect(second).toEqual({ ok: false, error: { code: 'version-conflict', current: item } }) + expect(persistence.appendCalls).toBe(1) + }) + + it('serializes canonical event writes while keeping versions independent per message', async () => { const { ctx, persistence } = await harness() const fixture = messageFixture('concurrent-items') persistence.persist(fixture.session) @@ -428,7 +401,7 @@ describe('MessageFeedbackService item concurrency', () => { }) }) - it('fences a reused Session id and lets the new lifecycle start cleanly', async () => { + it('starts clean when a stored log is replaced without feedback events', async () => { const { ctx, persistence } = await harness() const old = messageFixture('reused-session', { createdAt: 10, cwd: '/old' }) persistence.persist(old.session) @@ -464,7 +437,7 @@ describe('MessageFeedbackService item concurrency', () => { expect(newItem.version).not.toBe(oldItem.version) }) - it('drains admitted mutations before domain close and rejects later admission', async () => { + it('drains admitted mutations before disposal and rejects later admission', async () => { const current = await harness() const { ctx, persistence } = current const fixture = messageFixture('dispose-quiescence') @@ -474,16 +447,12 @@ describe('MessageFeedbackService item concurrency', () => { const started = Promise.withResolvers() const release = Promise.withResolvers() let physicalReads = 0 - let committed = 0 persistence.onRead = async () => { physicalReads += 1 if (physicalReads !== 1) return started.resolve(undefined) await release.promise } - ctx.on('domain/changed', (change) => { - if (change.domain === 'message_feedback') committed += 1 - }) const first = service.put({ sessionId: fixture.session.id, @@ -511,150 +480,155 @@ describe('MessageFeedbackService item concurrency', () => { expectItem(await first) expectItem(await second) await disposal - expect(physicalReads).toBe(4) - expect(committed).toBe(2) + expect(physicalReads).toBe(2) + expect(persistence.appendCalls).toBe(2) + expect(persistence.closeCalls).toBe(2) }) }) -describe('MessageFeedbackService durability ordering', () => { - it('rejects a live target missing from the re-read physical durable prefix', async () => { +describe('canonical message feedback history', () => { + it('appends only material cold mutations and leaves lifecycle and model history alone', async () => { const { ctx, persistence } = await harness() - const session = ctx.sessions.create(SessionId('live-prefix'), { - meta: { createdAt: 50, cwd: '/prefix' }, - }) - const fixture = appendMessageFixture(session) - ctx.on('session/flush', () => { - persistence.setDurable({ meta: session.header, events: [] }) - }) - - await expect(ctx.messageFeedback.put({ - sessionId: session.id, - messageId: fixture.assistantMessageIds[0], - rating: 'positive', - ifVersion: null, - })).resolves.toEqual({ - ok: false, - error: { - code: 'target-not-found', - sessionId: session.id, - messageId: fixture.assistantMessageIds[0], - }, - }) - expect(persistence.readCalls).toBe(1) - await expect(ctx.messageFeedback.list({ sessionId: session.id })).resolves.toEqual({ - ok: true, - value: { items: [] }, - }) + const fixture = messageFixture('cold-log') + const sessionId = fixture.session.id + const messageId = fixture.assistantMessageIds[0] + persistence.persist(fixture.session) + const prefix = fixture.session.snapshotEvents() + const lifecycle: string[] = [] + ctx.on('session/created', () => { lifecycle.push('created') }) + ctx.on('session/event', () => { lifecycle.push('event') }) + const created = expectItem(await ctx.messageFeedback.put({ sessionId, messageId, rating: 'positive', note: ' exact\ntext ', ifVersion: null })) + const edited = expectItem(await ctx.messageFeedback.put({ sessionId, messageId, rating: 'negative', ifVersion: created.version })) + expectItem(await ctx.messageFeedback.put({ sessionId, messageId, rating: 'negative', ifVersion: edited.version })) + await ctx.messageFeedback.delete({ sessionId, messageId, ifVersion: edited.version }) + await ctx.messageFeedback.delete({ sessionId, messageId, ifVersion: edited.version }) + const events = persistence.durable.get(sessionId)!.events + expect(events.slice(0, prefix.length)).toEqual(prefix) + expect(events.slice(prefix.length).map(({ type, data }) => ({ type, data }))).toEqual([ + { type: 'feedback/message-put', data: { sessionId, item: created } }, + { type: 'feedback/message-put', data: { sessionId, item: edited } }, + { type: 'feedback/message-delete', data: { sessionId, messageId } }, + ]) + expect(events.map(event => event.seq)).toEqual(events.map((_, index) => index)) + expect(lifecycle).toEqual([]) + expect(ctx.sessions.get(sessionId)).toBeUndefined() + expect(persistence.openCalls).toEqual(['write', 'write', 'write', 'write', 'write']) + expect(persistence.closeCalls).toBe(5) }) - it('commits and physically verifies a live target checkpoint before the sidecar write', async () => { + it('starts a fork without inherited feedback and keeps parent mutations independent', async () => { const { ctx, persistence } = await harness() - const session = ctx.sessions.create(SessionId('live-checkpoint'), { - meta: { createdAt: 30, cwd: '/live' }, - }) + const parent = messageFixture('feedback-parent') + persistence.persist(parent.session) + const messageId = parent.assistantMessageIds[0] + const parentItem = expectItem(await ctx.messageFeedback.put({ sessionId: parent.session.id, messageId, rating: 'positive', ifVersion: null })) + const seed = persistence.durable.get(parent.session.id)!.events + const childId = SessionId('feedback-child') + const child = Session.create(childId, seed, { + ...parent.session.header, id: childId, isSeeded: true, parentSession: parent.session.id, + }, SessionLogOffset(seed.length)) + persistence.persist(child) + await expect(ctx.messageFeedback.list({ sessionId: childId })).resolves.toEqual({ ok: true, value: { items: [] } }) + const childItem = expectItem(await ctx.messageFeedback.put({ sessionId: childId, messageId, rating: 'negative', ifVersion: null })) + await ctx.messageFeedback.delete({ sessionId: parent.session.id, messageId, ifVersion: parentItem.version }) + await expect(ctx.messageFeedback.list({ sessionId: childId })).resolves.toEqual({ ok: true, value: { items: [childItem] } }) + }) + + it('flushes live feedback with the target and retries durability without a duplicate event', async () => { + const { ctx, persistence } = await harness() + const session = ctx.sessions.create(SessionId('live-log')) const fixture = appendMessageFixture(session) - const order: string[] = [] + const before = session.snapshotEvents().length + const failure = new Error('disk unavailable') + let fail = true ctx.on('session/flush', (current) => { - order.push('session:durable') + if (fail) throw failure persistence.persist(current) }) - ctx.on('domain/changed', (change) => { - if (change.domain === 'message_feedback') order.push('sidecar:durable') - }) - persistence.onRead = () => { order.push('session:verified') } - - expectItem(await ctx.messageFeedback.put({ - sessionId: session.id, - messageId: fixture.assistantMessageIds[0], - rating: 'positive', - ifVersion: null, - })) - expect(order).toEqual(['session:durable', 'session:verified', 'sidecar:durable']) - expect(persistence.readCalls).toBe(1) - expect(persistence.durable.get(session.id)?.events).toContainEqual( - expect.objectContaining({ type: 'assistant/message' }), - ) + const request = { sessionId: session.id, messageId: fixture.assistantMessageIds[0], rating: 'positive' as const, ifVersion: null } + await expect(ctx.messageFeedback.put(request)).rejects.toBe(failure) + const listed = await ctx.messageFeedback.list({ sessionId: session.id }) + if (!listed.ok) throw new Error('missing live session') + const item = listed.value.items[0]! + fail = false + expectItem(await ctx.messageFeedback.put({ ...request, ifVersion: item.version })) + expect(session.snapshotEvents()).toHaveLength(before + 1) + expect(persistence.durable.get(session.id)?.events).toEqual(session.snapshotEvents()) + expect(persistence.openCalls).toEqual(['read']) }) - it('fails closed when a live checkpoint fails, has no participant, or is not physically durable', async () => { - const failed = await harness() - const failedSession = failed.ctx.sessions.create(SessionId('live-flush-failure')) - const failedFixture = appendMessageFixture(failedSession) - const diskFailure = new Error('disk unavailable') - failed.ctx.on('session/flush', () => { throw diskFailure }) - await expect(failed.ctx.messageFeedback.put({ - sessionId: failedSession.id, - messageId: failedFixture.assistantMessageIds[0], - rating: 'positive', - ifVersion: null, - })).rejects.toBe(diskFailure) - await expect(failed.ctx.messageFeedback.list({ sessionId: failedSession.id })).resolves.toEqual({ - ok: true, - value: { items: [] }, - }) + it.each(['missing-tail', 'different-tail', 'different-lifecycle'] as const)( + 'rejects a live checkpoint with %s and closes its verification handle', async (kind) => { + const { ctx, persistence } = await harness() + const session = ctx.sessions.create(SessionId('mismatched-checkpoint')) + const fixture = appendMessageFixture(session) + ctx.on('session/flush', () => { + const events = [...session.snapshotEvents()] + if (kind === 'missing-tail') events.pop() + if (kind === 'different-tail') events[events.length - 1] = { ...events.at(-1)!, time: 0 } + const meta = kind === 'different-lifecycle' ? { ...session.header, createdAt: 0 } : session.header + persistence.setDurable({ meta, events }) + }) + await expect(ctx.messageFeedback.put({ + sessionId: session.id, messageId: fixture.assistantMessageIds[0], rating: 'positive', ifVersion: null, + })).rejects.toThrow(/feedback prefix is not durable/u) + expect(persistence.closeCalls).toBe(1) + }, + ) - const absent = await harness() - const absentSession = absent.ctx.sessions.create(SessionId('live-no-flush')) - const absentFixture = appendMessageFixture(absentSession) - await expect(absent.ctx.messageFeedback.put({ - sessionId: absentSession.id, - messageId: absentFixture.assistantMessageIds[0], - rating: 'positive', - ifVersion: null, - })).rejects.toThrow(/no durability listener participated/u) - await expect(absent.ctx.messageFeedback.list({ sessionId: absentSession.id })).resolves.toEqual({ - ok: true, - value: { items: [] }, - }) - - const noDurability = await harness() - const unpersistedSession = noDurability.ctx.sessions.create(SessionId('live-unpersisted')) - const unpersistedFixture = appendMessageFixture(unpersistedSession) - noDurability.ctx.on('session/flush', () => {}) - await expect(noDurability.ctx.messageFeedback.put({ - sessionId: unpersistedSession.id, - messageId: unpersistedFixture.assistantMessageIds[0], - rating: 'positive', - ifVersion: null, - })).rejects.toThrow(/not found/u) - expect(noDurability.persistence.durable.has(unpersistedSession.id)).toBe(false) - await expect(noDurability.ctx.messageFeedback.list({ sessionId: unpersistedSession.id })).resolves.toEqual({ - ok: true, - value: { items: [] }, - }) - }) - - it('finishes the captured live checkpoint when the Session detaches mid-flush', async () => { + it('verifies an empty live no-op and captures its checkpoint before concurrent appends', async () => { const { ctx, persistence } = await harness() - const session = ctx.sessions.prepare(SessionId('detach-during-flush'), { - meta: { createdAt: 40, cwd: '/detach' }, - }) - const detach = ctx.sessions.enter(session) - ctx.sessions.announce(session) + const session = ctx.sessions.create(SessionId('checkpoint-prefix')) + ctx.on('session/flush', () => { persistence.persist(session) }) + await expect(ctx.messageFeedback.delete({ sessionId: session.id, messageId: 'absent' as MessageId, ifVersion: staleVersion() })) + .resolves.toEqual({ ok: true, value: { absent: true } }) const fixture = appendMessageFixture(session) - const started = Promise.withResolvers() - const release = Promise.withResolvers() - ctx.on('session/flush', async (current) => { - started.resolve(undefined) - await release.promise - persistence.persist(current) - }) + persistence.onRead = () => { session.append('turn/start', { turn: 2 }) } + expectItem(await ctx.messageFeedback.put({ + sessionId: session.id, messageId: fixture.assistantMessageIds[0], rating: 'positive', ifVersion: null, + })) + expect(persistence.durable.get(session.id)!.events.length).toBe(session.snapshotEvents().length - 1) + }) - const pending = ctx.messageFeedback.put({ - sessionId: session.id, - messageId: fixture.assistantMessageIds[0], - rating: 'positive', - ifVersion: null, - }) - await started.promise - detach() - expect(ctx.sessions.get(session.id)).toBeUndefined() - release.resolve(undefined) - expectItem(await pending) - expect(persistence.readCalls).toBe(1) - await expect(ctx.messageFeedback.list({ sessionId: session.id })).resolves.toMatchObject({ - ok: true, - value: { items: [{ messageId: fixture.assistantMessageIds[0] }] }, - }) + it('rejects an unowned durability checkpoint and closes cold handles on failures', async () => { + const { ctx, persistence } = await harness() + const live = ctx.sessions.create(SessionId('no-flush-owner')) + const fixture = appendMessageFixture(live) + await expect(ctx.messageFeedback.put({ sessionId: live.id, messageId: fixture.assistantMessageIds[0], rating: 'positive', ifVersion: null })) + .rejects.toThrow(/no durability listener participated/u) + const cold = messageFixture('cold-failures') + persistence.persist(cold.session) + const request = { sessionId: cold.session.id, messageId: cold.assistantMessageIds[0], rating: 'positive' as const, ifVersion: null } + const appendFailure = new Error('append failed') + persistence.appendFailure = appendFailure + await expect(ctx.messageFeedback.put(request)).rejects.toBe(appendFailure) + expect(persistence.closeCalls).toBe(1) + persistence.appendFailure = undefined + const flushFailure = new Error('flush failed') + persistence.flushFailure = flushFailure + await expect(ctx.messageFeedback.put(request)).rejects.toBe(flushFailure) + expect(persistence.closeCalls).toBe(2) + }) + + it.each([ + { type: 'feedback/message-put', data: null }, + { type: 'feedback/message-put', data: { sessionId: 'x', item: {} } }, + ...[ + { messageId: '' }, { rating: 'neutral' }, { version: 'bad-token' }, { note: ' ' }, + { createdAt: -1 }, { updatedAt: 0 }, { updatedAt: 1.5 }, + ].map(patch => ({ type: 'feedback/message-put', data: { sessionId: 'x', item: { + messageId: 'message', rating: 'positive', version: randomUUID(), createdAt: 1, updatedAt: 1, ...patch, + } } })), + { type: 'feedback/message-delete', data: { sessionId: 'x', messageId: '' } }, + { type: 'feedback/message-delete', data: { sessionId: 12, messageId: 'message' } }, + ])('rejects malformed durable feedback payload %#', async (record) => { + const { ctx, persistence } = await harness() + const fixture = messageFixture('invalid-feedback') + const events = fixture.session.snapshotEvents() + persistence.setDurable({ meta: fixture.session.header, events: [...events, { + ...record, seq: SessionSeq(events.length), time: 1, + } as SessionEvent] }) + await expect(ctx.messageFeedback.list({ sessionId: fixture.session.id })).rejects.toThrow() + expect(persistence.closeCalls).toBe(1) }) }) diff --git a/packages/feedback/message-feedback/tsconfig.json b/packages/feedback/message-feedback/tsconfig.json index 203d78aa99..f79c3ff9de 100644 --- a/packages/feedback/message-feedback/tsconfig.json +++ b/packages/feedback/message-feedback/tsconfig.json @@ -29,12 +29,6 @@ { "path": "../../session/session-persistence" }, - { - "path": "../../storage/storage" - }, - { - "path": "../../storage/storage-domain" - }, { "path": "../../typert/protocol" } diff --git a/packages/session/session-log-deepseek/package.json b/packages/session/session-log-deepseek/package.json index a5b6b72f28..5e2d9ebba0 100644 --- a/packages/session/session-log-deepseek/package.json +++ b/packages/session/session-log-deepseek/package.json @@ -49,8 +49,16 @@ }, "devDependencies": { "@deepseek-ai/cordis": "workspace:^", + "@deepseek-ai/cordis-plugin-include": "workspace:^", + "@deepseek-ai/cordis-plugin-loader": "workspace:^", + "@deepseek-ai/dsh-command-feedback": "workspace:^", "@deepseek-ai/dsh-deepseek-llm-api-extensions": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^" + "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-llm-deepseek": "workspace:^", + "@deepseek-ai/dsh-llm-mock-server": "workspace:^", + "@deepseek-ai/dsh-message-feedback": "workspace:^", + "@deepseek-ai/dsh-session": "workspace:^", + "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^" } } diff --git a/packages/session/session-log-deepseek/tests/feedback-composition.spec.ts b/packages/session/session-log-deepseek/tests/feedback-composition.spec.ts new file mode 100644 index 0000000000..8de7cfa842 --- /dev/null +++ b/packages/session/session-log-deepseek/tests/feedback-composition.spec.ts @@ -0,0 +1,139 @@ +import { mkdtemp, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { pathToFileURL } from 'node:url' +import { afterEach, expect, it, vi } from 'vitest' +import { Context } from '@deepseek-ai/cordis' +import Loader from '@deepseek-ai/cordis-plugin-loader' +import Include from '@deepseek-ai/cordis-plugin-include' +import SessionStore, { SessionId } from '@deepseek-ai/dsh-session' +import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl' +import MessageFeedback from '@deepseek-ai/dsh-message-feedback' +import { recordFeedback } from '@deepseek-ai/dsh-command-feedback' +import LlmRuntime, { createAssistantMessage, createUserMessage } from '@deepseek-ai/dsh-llm' +import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek' +import DeepSeekLlmApiExtensions from '@deepseek-ai/dsh-deepseek-llm-api-extensions' +import { startMockLlmServer, type MockLlmServer } from '@deepseek-ai/dsh-llm-mock-server' +import * as SessionLogDeepSeek from '../src/index.ts' +import type { DeepSeekSessionLogExtension } from '../src/types.ts' + +let root: string | undefined +let ctx: Context | undefined +let server: MockLlmServer | undefined + +afterEach(async () => { + await ctx?.fiber.dispose() + await server?.close() + if (root !== undefined) await rm(root, { recursive: true, force: true }) + ctx = undefined + server = undefined + root = undefined + vi.unstubAllEnvs() +}) + +it('uploads freeform feedback and message put/edit/delete through the unchanged provider route', async () => { + root = await mkdtemp(join(tmpdir(), 'dsh-feedback-upload-')) + vi.stubEnv('DSH_HOME', root) + vi.stubEnv('DEEPSEEK_API_KEY', 'feedback-test-key') + server = await startMockLlmServer({ sequence: ['invalid_request', 'success', 'success'] }) + const modules = new Map([ + ['@deepseek-ai/dsh-session', SessionStore], + ['@deepseek-ai/dsh-session-persistence-jsonl', JsonlSessionPersistence], + ['@deepseek-ai/dsh-message-feedback', MessageFeedback], + ['@deepseek-ai/dsh-llm', LlmRuntime], + ['@deepseek-ai/dsh-llm-deepseek', LlmDeepSeek], + ['@deepseek-ai/dsh-deepseek-llm-api-extensions', DeepSeekLlmApiExtensions], + ['@deepseek-ai/dsh-session-log-deepseek', SessionLogDeepSeek], + ]) + const config = join(root, 'cordis.yml') + await writeFile(config, JSON.stringify([...modules.keys()].map(name => ({ + name, + ...name === '@deepseek-ai/dsh-session-persistence-jsonl' + ? { config: { root: join(root!, 'sessions'), compression: 'none' } } + : name === '@deepseek-ai/dsh-message-feedback' + ? { config: { maxNoteBytes: 1024 } } + : name === '@deepseek-ai/dsh-llm-deepseek' + ? { config: { baseURL: server!.baseURL } } + : name === '@deepseek-ai/dsh-session-log-deepseek' + ? { config: { enabled: true } } + : {}, + })))) + ctx = new Context() + ctx.baseUrl = pathToFileURL(root).href + '/' + await ctx.plugin(Loader) + ctx.loader.builtins.include = Include + ctx.loader.internal = { + version: 'v2', + async import(specifier: string) { + if (!modules.has(specifier)) throw new Error(`unexpected Loader import: ${specifier}`) + return modules.get(specifier) + }, + } as unknown as NonNullable + await ctx.loader.create({ name: 'cordis:include', config: { path: pathToFileURL(config).href } }) + await ctx.loader.await() + expect([...ctx.loader.entries()].filter(entry => entry.fiber === undefined && !entry.disabled)).toEqual([]) + + const session = ctx.sessions.create(SessionId('feedback-upload')) + const handle = await ctx.sessionPersistence.create(session.header) + try { + const user = createUserMessage({ content: [{ type: 'text', text: 'Question' }], source: { kind: 'user' } }) + const assistant = createAssistantMessage({ content: [{ type: 'text', text: 'Answer' }], source: { provider: 'deepseek-official', model: 'deepseek-v4-flash' } }) + session.append('user/message', user, { surfaceOp: 'append' }) + session.append('assistant/message', { message: assistant, stream: [], turn: 1, step: 1 }, { surfaceOp: 'append' }) + const messages = session.deriveMessages() + recordFeedback(session, ' The session needs a clearer explanation. ') + const created = await ctx.messageFeedback.put({ sessionId: session.id, messageId: assistant.id, rating: 'negative', note: 'Explain the result.', ifVersion: null }) + if (!created.ok) throw new Error(created.error.code) + const initialPrefix = session.snapshotEvents() + const request = async () => { + const chunks = [] + for await (const chunk of ctx!.llm.stream({ provider: 'deepseek-official', model: 'deepseek-v4-flash', sessionId: session.id, messages: session.deriveMessages() })) chunks.push(chunk) + return chunks.at(-1) + } + expect(await request()).toMatchObject({ type: 'finish', reason: { kind: 'error' } }) + expect(SessionLogDeepSeek.acceptedThrough(session)).toBe(-1) + expect(await request()).toMatchObject({ type: 'finish', reason: { kind: 'stop' } }) + const first = (server.requests[0]!.body as { dsh_session_log: DeepSeekSessionLogExtension }).dsh_session_log + const retry = (server.requests[1]!.body as { dsh_session_log: DeepSeekSessionLogExtension }).dsh_session_log + expect(retry).toEqual(first) + expect(first.events).toEqual(initialPrefix) + expect(first.events.slice(-2)).toMatchObject([ + { type: 'feedback/record', data: { text: 'The session needs a clearer explanation.' } }, + { type: 'feedback/message-put', data: { sessionId: session.id, item: created.value } }, + ]) + expect(SessionLogDeepSeek.acceptedThrough(session)).toBe(first.throughSeq) + + const edited = await ctx.messageFeedback.put({ + sessionId: session.id, messageId: assistant.id, rating: 'positive', + note: 'The explanation is clear now.', ifVersion: created.value.version, + }) + if (!edited.ok) throw new Error(edited.error.code) + expect(await ctx.messageFeedback.delete({ + sessionId: session.id, messageId: assistant.id, ifVersion: edited.value.version, + })).toEqual({ ok: true, value: { absent: true } }) + expect(await request()).toMatchObject({ type: 'finish', reason: { kind: 'stop' } }) + const suffix = (server.requests[2]!.body as { dsh_session_log: DeepSeekSessionLogExtension }).dsh_session_log + expect(suffix.afterSeq).toBe(first.throughSeq) + expect(suffix.events).toMatchObject([ + { type: 'session-log-deepseek/delivery-accepted' }, + { type: 'feedback/message-put', data: { sessionId: session.id, item: edited.value } }, + { type: 'feedback/message-delete', data: { sessionId: session.id, messageId: assistant.id } }, + ]) + expect(suffix.events.every(event => event.seq > first.throughSeq)).toBe(true) + expect(SessionLogDeepSeek.acceptedThrough(session)).toBe(suffix.throughSeq) + expect(session.deriveMessages()).toEqual(messages) + expect(await ctx.messageFeedback.list({ sessionId: session.id })).toEqual({ ok: true, value: { items: [] } }) + for (const wire of server.requests) { + expect(wire.path).toBe('/chat/completions') + expect(wire.body).not.toHaveProperty('dsh_feedback') + expect(wire.body).toMatchObject({ model: 'deepseek-v4-flash', messages: [ + { role: 'user', content: 'Question' }, + { role: 'assistant', content: 'Answer' }, + ] }) + } + await ctx.sessions.flush(session) + expect(await handle.read()).toEqual(session.snapshotEvents()) + } finally { + await handle.close() + } +}) diff --git a/packages/session/session-telemetry-otel/README.i18n.yaml b/packages/session/session-telemetry-otel/README.i18n.yaml index cf5550a799..e7ffd61a28 100644 --- a/packages/session/session-telemetry-otel/README.i18n.yaml +++ b/packages/session/session-telemetry-otel/README.i18n.yaml @@ -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/session/session-telemetry-otel/README.md -README.md: 8ae8d0091ef1a92cd9caf0b57dec5ea56d9f6ba3 -README.zh.md: 3edf91a812d42a14b4a39de53079ab89dc72bd1c +README.md: f1ce945a363cff489f9f81d32f6842e2d13c99a0 +README.zh.md: da9838e570fea036dccc5c5b4743721746283874 diff --git a/packages/session/session-telemetry-otel/README.md b/packages/session/session-telemetry-otel/README.md index 8ae8d0091e..f1ce945a36 100644 --- a/packages/session/session-telemetry-otel/README.md +++ b/packages/session/session-telemetry-otel/README.md @@ -35,7 +35,7 @@ Mount this plugin when a deployment should export session records through OpenTe | `FEEDBACK_ONLY` | Each `feedback/record` replays, copies, and redacts every canonical event after the handoff cursor through that event; later records wait for another feedback event and remain local if none arrives | | `DISABLED` | Default. No coordinator, provider, processor, or exporter is constructed; no telemetry record leaves the process, and a `feedback/record` logs that nothing will be shared | -Programmatic TypeScript configuration uses the exported `SessionTelemetryMode` enum; raw string literals are not assignable. The mounted service discloses the resolved mode through the seam's [`SessionTelemetrySharingStatus`](../session-telemetry/README.md#the-sharing-disclosure) `sharing` property (`full` / `feedback-only` / `disabled`), so the `/feedback` acknowledgement reports whether and how the session is shared — even `DISABLED` discloses `disabled`. +Programmatic TypeScript configuration uses the exported `SessionTelemetryMode` enum; raw string literals are not assignable. The mounted service discloses the resolved mode through the seam's [`SessionTelemetrySharingStatus`](../session-telemetry/README.md#the-sharing-disclosure) `sharing` property (`full` / `feedback-only` / `disabled`), including `disabled` in `DISABLED` mode. This API reports policy independently of the `/feedback` acknowledgement, which confirms recording only. ### Minimal configuration diff --git a/packages/session/session-telemetry-otel/README.zh.md b/packages/session/session-telemetry-otel/README.zh.md index 3edf91a812..da9838e570 100644 --- a/packages/session/session-telemetry-otel/README.zh.md +++ b/packages/session/session-telemetry-otel/README.zh.md @@ -35,7 +35,7 @@ kind: "package-reference" | `FEEDBACK_ONLY` | 每个 `feedback/record` 都会回放、复制并脱敏 handoff 游标之后直至该事件的每条权威事件；后续记录等待下一个反馈事件；如果没有后续反馈，则留在本地 | | `DISABLED` | 默认值。不构造协调器、提供方、处理器或导出器；没有遥测记录会离开进程，`feedback/record` 会记录「不会共享任何内容」 | -程序化 TypeScript 配置使用导出的 `SessionTelemetryMode` 枚举；原始字符串字面量不可赋值。已挂载服务通过 seam 的 [`SessionTelemetrySharingStatus`](../session-telemetry/README.zh.md#the-sharing-disclosure) `sharing` 属性披露解析后的模式（`full` / `feedback-only` / `disabled`），因此 `/feedback` 的确认文本可以报告会话是否以及如何被共享——即使 `DISABLED` 也会披露 `disabled`。 +程序化 TypeScript 配置使用导出的 `SessionTelemetryMode` 枚举；原始字符串字面量不可赋值。已挂载服务通过 seam 的 [`SessionTelemetrySharingStatus`](../session-telemetry/README.zh.md#the-sharing-disclosure) `sharing` 属性披露解析后的模式（`full` / `feedback-only` / `disabled`），包括在 `DISABLED` 模式下披露 `disabled`。此 API 独立报告策略；`/feedback` 确认文本只确认记录。 ### 最小配置 diff --git a/packages/session/session-telemetry-otel/tests/fixtures/telemetry.patch.yml b/packages/session/session-telemetry-otel/tests/fixtures/telemetry.patch.yml index 88cb0c6540..c5542517a8 100644 --- a/packages/session/session-telemetry-otel/tests/fixtures/telemetry.patch.yml +++ b/packages/session/session-telemetry-otel/tests/fixtures/telemetry.patch.yml @@ -1,5 +1,8 @@ # Test-only patch over the shipped headless profile. The driver points the # production telemetry row at its mock collector through the public env vars. +- id: session-telemetry-otel + disabled: false + - id: headless-startup disabled: true diff --git a/packages/session/session-telemetry/README.i18n.yaml b/packages/session/session-telemetry/README.i18n.yaml index b73fd5c181..328941c647 100644 --- a/packages/session/session-telemetry/README.i18n.yaml +++ b/packages/session/session-telemetry/README.i18n.yaml @@ -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/session/session-telemetry/README.md -README.md: 2e20de1befe06801ae06de9da6ccc234ee8bdec3 -README.zh.md: d83c9763170e35a5a3ed6ecf1a0b363e438b0723 +README.md: d6916d26272daed47c2a148240fab94b13fafaa2 +README.zh.md: c82afc5384deb2e6d7f950b5efe2e8d0b67599bd diff --git a/packages/session/session-telemetry/README.md b/packages/session/session-telemetry/README.md index 2e20de1bef..d6916d2627 100644 --- a/packages/session/session-telemetry/README.md +++ b/packages/session/session-telemetry/README.md @@ -29,7 +29,7 @@ As a deployment, choose a backend, mount it, and add redaction rules when record ### Choosing and mounting a backend -Load exactly one backend plugin; it registers `ctx.sessionTelemetry` with the capture coordinator and its own delivery pipeline, and a duplicate load throws. The mounted backend discloses its sharing policy through the required [`sharing` member](#the-sharing-disclosure), which the `/feedback` acknowledgement renders; a consumer renders "not configured" only when no telemetry service is mounted. +Load exactly one backend plugin; it registers `ctx.sessionTelemetry` with the capture coordinator and its own delivery pipeline, and a duplicate load throws. The mounted backend discloses its sharing policy through the required [`sharing` member](#the-sharing-disclosure); a consumer may report "not configured" only when no telemetry service is mounted. The `/feedback` command confirms recording without reading this policy. ### The backend contract @@ -43,7 +43,7 @@ Capture runs in one of two modes. `live` capture follows session events as they -Every backend discloses its deployment-selected sharing policy through the seam's `sharing` vocabulary: `full` (every event is handed over as it happens), `feedback-only` (nothing is handed over until a `feedback/record` event releases the unreleased prefix), or `disabled` (nothing is handed over at all). The acknowledgement of a recorded feedback entry reports this status; the disclosure never claims delivery — handoff is the non-blocking enqueue, and batching, retry, and loss policy stay the backend SDK's. +Every backend discloses its deployment-selected sharing policy through the seam's `sharing` vocabulary: `full` (every event is handed over as it happens), `feedback-only` (nothing is handed over until a `feedback/record` event releases the unreleased prefix), or `disabled` (nothing is handed over at all). The policy API never claims delivery — handoff is the non-blocking enqueue, and batching, retry, and loss policy stay the backend SDK's. ### Redacting records diff --git a/packages/session/session-telemetry/README.zh.md b/packages/session/session-telemetry/README.zh.md index d83c976317..c82afc5384 100644 --- a/packages/session/session-telemetry/README.zh.md +++ b/packages/session/session-telemetry/README.zh.md @@ -29,7 +29,7 @@ kind: "package-library" ### 选择并挂载后端 -只加载一个后端插件；它把捕获协调器与自己的投递流水线注册为 `ctx.sessionTelemetry`，重复加载会抛出异常。已挂载后端通过必需的 [`sharing` 成员](#the-sharing-disclosure) 披露共享策略，`/feedback` 的确认文本会渲染它；只有在未挂载任何遥测服务时，消费方才渲染「未配置」。 +只加载一个后端插件；它把捕获协调器与自己的投递流水线注册为 `ctx.sessionTelemetry`，重复加载会抛出异常。已挂载后端通过必需的 [`sharing` 成员](#the-sharing-disclosure) 披露共享策略；只有在未挂载任何遥测服务时，消费方才可报告「未配置」。`/feedback` 命令确认记录，不读取此策略。 ### 后端约定 @@ -43,7 +43,7 @@ kind: "package-library" -每个后端都通过 seam 的 `sharing` 词汇披露其部署级共享策略：`full`（每个事件在发生时立即交接）、`feedback-only`（在 `feedback/record` 事件释放其之前的未释放前缀之前，不交接任何内容）或 `disabled`（完全不交接任何内容）。已记录反馈条目的确认文本会报告该状态；披露从不声称投递——交接是非阻塞入队，批处理、重试与丢失策略仍归后端 SDK。 +每个后端都通过 seam 的 `sharing` 词汇披露其部署级共享策略：`full`（每个事件在发生时立即交接）、`feedback-only`（在 `feedback/record` 事件释放其之前的未释放前缀之前，不交接任何内容）或 `disabled`（完全不交接任何内容）。策略 API 从不声称投递——交接是非阻塞入队，批处理、重试与丢失策略仍归后端 SDK。 ### 脱敏记录 diff --git a/packages/test-support/session-snapshot/src/identity.ts b/packages/test-support/session-snapshot/src/identity.ts index 78be7a0020..22d8d69c0f 100644 --- a/packages/test-support/session-snapshot/src/identity.ts +++ b/packages/test-support/session-snapshot/src/identity.ts @@ -101,7 +101,12 @@ export function redactSessionSnapshotIds(logs: readonly string[]): string[] { } } for (const log of parsed) { - for (const record of log.records) collect(record, record.type) + for (const record of log.records) { + if (record.type === 'feedback/message-put' && isRecord(record.data) && isRecord(record.data.item)) { + claim(record.data.item.version, 'id') + } + collect(record, record.type) + } } const replacements = [...tokenByValue] diff --git a/packages/test-support/session-snapshot/src/normalize.ts b/packages/test-support/session-snapshot/src/normalize.ts index b5248e9cf4..1b95812517 100644 --- a/packages/test-support/session-snapshot/src/normalize.ts +++ b/packages/test-support/session-snapshot/src/normalize.ts @@ -374,6 +374,7 @@ export function normalizeSessionLog( const data = record.data as Record if ('durationMs' in data) data.durationMs = 0 } + normalizeFeedbackClocks(record) if (record.type === 'goal/change' && record.data !== null && typeof record.data === 'object') { const data = record.data as Record if ('createdAt' in data) data.createdAt = 0 @@ -578,10 +579,21 @@ export function scrubSessionSnapshot(rawLog: string): string { return line } omitFixtureEnvelope(record) + normalizeFeedbackClocks(record) return JSON.stringify(record) }).join('\n') } +/** Normalize service-owned feedback clocks without touching user-authored payloads. */ +function normalizeFeedbackClocks(record: Record): void { + if (record.type !== 'feedback/message-put' || record.data === null || typeof record.data !== 'object') return + const item = (record.data as { item?: unknown }).item + if (item === null || typeof item !== 'object') return + const clocks = item as Record + if ('createdAt' in clocks) clocks.createdAt = 0 + if ('updatedAt' in clocks) clocks.updatedAt = 0 +} + /** Which independent request-header payloads a scrubber replaces. */ interface HeaderScrubOptions { system?: boolean diff --git a/packages/test-support/session-snapshot/tests/identity.spec.ts b/packages/test-support/session-snapshot/tests/identity.spec.ts index 48ef96ead2..b6d0fef836 100644 --- a/packages/test-support/session-snapshot/tests/identity.spec.ts +++ b/packages/test-support/session-snapshot/tests/identity.spec.ts @@ -10,6 +10,23 @@ const otherId = '66666666-6666-4666-8666-666666666666' const proseUuid = '77777777-7777-4777-8777-777777777777' describe('session snapshot identity redaction', () => { + it('preserves feedback versions and target relationships without redacting unrelated prose', () => { + const source = [ + { type: 'session', id: parentId }, + { type: 'assistant/message', data: { message: { id: messageId, role: 'assistant', content: [], source: {} } } }, + { type: 'feedback/message-put', data: { sessionId: parentId, item: { messageId, version: approvalId, note: proseUuid } } }, + { type: 'feedback/message-put', data: { sessionId: parentId, item: { messageId, version: runId } } }, + { type: 'feedback/message-delete', data: { sessionId: parentId, messageId } }, + { type: 'example', data: { version: proseUuid } }, + ].map(record => JSON.stringify(record)).join('\n') + const [output] = redactSessionSnapshotIds([source]) + expect(output).toContain('"version":"{{id:1}}"') + expect(output).toContain('"version":"{{id:2}}"') + expect(output?.match(/"messageId":"{{message:1}}"/g)).toHaveLength(3) + expect(output).toContain(proseUuid) + expect(redactSessionSnapshotIds([output!])).toEqual([output]) + }) + it('preserves typed relationships across parent and child logs', () => { const parent = [ JSON.stringify({ type: 'session', id: parentId, createdAt: 1, cwd: '/tmp/work' }), diff --git a/packages/test-support/session-snapshot/tests/normalize.spec.ts b/packages/test-support/session-snapshot/tests/normalize.spec.ts index 6b07797137..9baea0876f 100644 --- a/packages/test-support/session-snapshot/tests/normalize.spec.ts +++ b/packages/test-support/session-snapshot/tests/normalize.spec.ts @@ -254,6 +254,14 @@ Additional instructions from: nested\AGENTS.md`, }) describe('normalizeSessionLog', () => { + it('normalizes only message-feedback item clocks', () => { + const item = { messageId: 'answer', version: 'version', createdAt: 123, updatedAt: 456, note: 'keep 123' } + const input = ['feedback/message-put', 'tool/result'].map(type => JSON.stringify({ type, data: { item } })).join('\n') + const output = normalizeSessionLog(input, ctx) + expect(output).toContain('"createdAt":0,"updatedAt":0,"note":"keep 123"') + expect(output).toContain('"createdAt":123,"updatedAt":456,"note":"keep 123"') + }) + const header = (over: object) => JSON.stringify({ type: 'session', version: 0, id: 's', createdAt: 123, ...over }) const event = (over: object) => JSON.stringify({ type: 'turn/start', seq: 1, time: 999, data: { turn: 1 }, ...over }) @@ -972,6 +980,19 @@ describe('scrubRequestHeaders', () => { }) describe('scrubSessionSnapshot', () => { + it('writes stable feedback clocks while retaining notes and version identity', () => { + const input = [ + { type: 'session', id: 's' }, + { type: 'feedback/message-put', data: { item: { version: 'opaque-version', createdAt: 12, updatedAt: 34, note: 'keep 12' } } }, + { type: 'feedback/message-put', data: null }, + { type: 'feedback/message-put', data: { item: null } }, + { type: 'feedback/message-put', data: { item: {} } }, + ].map(record => JSON.stringify(record)).join('\n') + const output = scrubSessionSnapshot(input) + expect(output).toContain('"version":"opaque-version","createdAt":0,"updatedAt":0,"note":"keep 12"') + expect(scrubSessionSnapshot(output)).toBe(output) + }) + it('preserves the header while projecting and scrubbing each body record', () => { const header = ' {"type":"session","version":0,"id":"s","createdAt":7} ' const request = JSON.stringify({ diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c67c086cc2..eaec5187fd 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -5182,9 +5182,6 @@ importers: '@deepseek-ai/dsh-session': specifier: workspace:^ version: link:../../core/session - '@deepseek-ai/dsh-session-telemetry': - specifier: workspace:^ - version: link:../../session/session-telemetry packages/feedback/message-feedback: dependencies: @@ -5219,15 +5216,6 @@ importers: '@deepseek-ai/dsh-session-persistence-jsonl': specifier: workspace:^ version: link:../../session/session-persistence-jsonl - '@deepseek-ai/dsh-storage': - specifier: workspace:^ - version: link:../../storage/storage - '@deepseek-ai/dsh-storage-domain': - specifier: workspace:^ - version: link:../../storage/storage-domain - '@deepseek-ai/dsh-storage-json': - specifier: workspace:^ - version: link:../../storage/storage-json '@deepseek-ai/dsh-typert-protocol': specifier: workspace:^ version: link:../../typert/protocol @@ -7240,15 +7228,39 @@ importers: '@deepseek-ai/cordis': specifier: workspace:^ version: link:../../../vendor/cordis + '@deepseek-ai/cordis-plugin-include': + specifier: workspace:^ + version: link:../../../vendor/include + '@deepseek-ai/cordis-plugin-loader': + specifier: workspace:^ + version: link:../../../vendor/loader + '@deepseek-ai/dsh-command-feedback': + specifier: workspace:^ + version: link:../../feedback/command-feedback '@deepseek-ai/dsh-deepseek-llm-api-extensions': specifier: workspace:^ version: link:../../llm/deepseek-llm-api-extensions '@deepseek-ai/dsh-invariants': specifier: workspace:^ version: link:../../runtime-diagnostics/invariants + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm + '@deepseek-ai/dsh-llm-deepseek': + specifier: workspace:^ + version: link:../../llm/llm-deepseek + '@deepseek-ai/dsh-llm-mock-server': + specifier: workspace:^ + version: link:../../test-support/llm-mock-server + '@deepseek-ai/dsh-message-feedback': + specifier: workspace:^ + version: link:../../feedback/message-feedback '@deepseek-ai/dsh-session': specifier: workspace:^ version: link:../../core/session + '@deepseek-ai/dsh-session-persistence-jsonl': + specifier: workspace:^ + version: link:../session-persistence-jsonl packages/session/session-persistence: dependencies: diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts index cd74be4272..0df05a31df 100644 --- a/scripts/gen-doc-graphs.ts +++ b/scripts/gen-doc-graphs.ts @@ -296,7 +296,7 @@ const SERVICE_ROLES: ServiceRole[] = [ pkg: 'storage-domain', title: 'Domain data facility', mode: 'core', - consumers: ['workspace', 'message-feedback'], + consumers: ['workspace'], note: 'Waits for every configured backend, then publishes the domain form as one lifecycle-bound service for typed durable state.', }, { @@ -304,7 +304,7 @@ const SERVICE_ROLES: ServiceRole[] = [ pkg: 'message-feedback', title: 'Lifecycle-bound message feedback', mode: 'core', - note: 'Owns local per-assistant-message feedback, lifecycle and target validation, per-item compare-and-set, and the Host unary Remote contract without entering Session history or telemetry.', + note: 'Owns per-assistant-message feedback in the canonical Session log, target validation, per-item compare-and-set, and the Host unary Remote contract. Feedback stays outside model history; log export follows the consumer policy.', }, { key: 'workspaceRegistry', diff --git a/scripts/smoke-python-runtime.py b/scripts/smoke-python-runtime.py index 22de831bd4..ad7e663bad 100644 --- a/scripts/smoke-python-runtime.py +++ b/scripts/smoke-python-runtime.py @@ -1269,13 +1269,20 @@ def smoke_sdk_snapshot(base_url: str, executable: Path, update_snapshots: bool) dsh_home = root / "home" sessions = dsh_home / "sessions" patch = write_advanced_profile_patch(root, "snapshot.patch.yml", sessions) + feedback_patch = write_profile_patch(root, "feedback.patch.yml", sessions, [{"insert": [ + {"id": "snapshot-message-feedback", "name": "@deepseek-ai/dsh-message-feedback", + "config": {"maxNoteBytes": 1024}}, + {"id": "snapshot-feedback-producer", "name": ( + Path(__file__).resolve().parent.parent / "snapshots/sdk/text-turn/feedback-producer.mjs" + ).as_uri()}, + ]}]) with DeepSeekHarness( provider="deepseek-official", model="smoke-model", cwd=str(root), dsh_bin=str(executable), dsh_home=str(dsh_home), - patches=(str(patch),), + patches=(str(patch), str(feedback_patch)), env={ "DSH_PERMISSION_MODE": "danger-full-access", "DSH_TELEMETRY_DISABLED": "1", @@ -1287,6 +1294,10 @@ def smoke_sdk_snapshot(base_url: str, executable: Path, update_snapshots: bool) result = harness.run(SNAPSHOT_PROMPT, session_id=SNAPSHOT_SESSION_ID) assert result.final_response == SNAPSHOT_FINAL_TEXT, result.final_response + feedback_types = [event.get("type") for event in result.events + if str(event.get("type")).startswith("feedback/")] + if feedback_types != ["feedback/record", "feedback/message-put", "feedback/message-put", "feedback/message-delete"]: + raise AssertionError(f"advanced snapshot did not exercise all feedback mutations: {feedback_types}") methods = [notification.method for notification in result.notifications] if methods.count("subagent.started") != 2 or methods.count("subagent.finished") != 2: raise AssertionError(f"advanced snapshot emitted unexpected subagent lifecycle: {methods}") @@ -1725,6 +1736,30 @@ def build_snapshot_files( replacements.append((child_id, f"{{{{child-{index}}}}}")) agent_id = snapshot_agent_id(result, child_id) replacements.append((agent_id, f"{{{{agent-{index}}}}}")) + command_index = 0 + for record in logs[SNAPSHOT_SESSION_ID]: + data = record.get("data") + if record.get("type") == "command/run" and isinstance(data, dict): + command_index += 1 + replacements.append((data["commandId"], f"{{{{command:{command_index}}}}}")) + if record.get("type") == "command/done" and isinstance(data, dict): + anonymous = re.search(r"Anonymous user: ([0-9a-f-]{36})", str(data.get("text"))) + if anonymous is not None: + replacements.append((anonymous.group(1), "{{anonymous-user}}")) + feedback_targets = dict.fromkeys( + record["data"]["item"]["messageId"] + for record in logs[SNAPSHOT_SESSION_ID] + if record.get("type") == "feedback/message-put" + ) + for index, message_id in enumerate(feedback_targets, start=1): + replacements.append((message_id, f"{{{{message:{index}}}}}")) + feedback_versions = dict.fromkeys( + record["data"]["item"]["version"] + for record in logs[SNAPSHOT_SESSION_ID] + if record.get("type") == "feedback/message-put" + ) + for index, version in enumerate(feedback_versions, start=1): + replacements.append((version, f"{{{{feedback-version:{index}}}}}")) replacements.sort(key=lambda pair: len(pair[0]), reverse=True) result_value = { @@ -1902,7 +1937,16 @@ def normalize_snapshot_value( if isinstance(dt, list): member["dt"] = [0] * len(dt) if isinstance(normalized.get("id"), str) and normalized.get("role") in ("assistant", "user"): - normalized["id"] = "{{messageId}}" + if not normalized["id"].startswith("{{message:"): + normalized["id"] = "{{messageId}}" + if normalized.get("type") in ("feedback/message-put", "feedback/message-delete"): + data = normalized.get("data") + if isinstance(data, dict): + item = data.get("item") if normalized["type"] == "feedback/message-put" else data + if isinstance(item, dict): + if normalized["type"] == "feedback/message-put": + item["createdAt"] = 0 + item["updatedAt"] = 0 scrub_snapshot_header(normalized) return normalized diff --git a/scripts/snapshots/python-sdk-single-exe/advanced/result.json b/scripts/snapshots/python-sdk-single-exe/advanced/result.json index 8d23d50100..0074eca78f 100644 --- a/scripts/snapshots/python-sdk-single-exe/advanced/result.json +++ b/scripts/snapshots/python-sdk-single-exe/advanced/result.json @@ -1335,7 +1335,7 @@ "provider": "deepseek-official", "model": "smoke-model" }, - "id": "{{messageId}}" + "id": "{{message:1}}" }, "usage": { "inputTokens": 3, @@ -1409,9 +1409,80 @@ } }, { - "type": "turn/end", + "type": "command/run", "seq": 59, "time": 0, + "data": { + "commandId": "{{command:1}}", + "name": "feedback", + "source": { + "kind": "user" + } + } + }, + { + "type": "feedback/record", + "seq": 60, + "time": 0, + "data": { + "text": "The session needs a clearer explanation." + } + }, + { + "type": "command/done", + "seq": 61, + "time": 0, + "data": { + "commandId": "{{command:1}}", + "kind": "success", + "text": "Feedback recorded for session {{parent}}\nAnonymous user: {{anonymous-user}}." + } + }, + { + "type": "feedback/message-put", + "seq": 62, + "time": 0, + "data": { + "sessionId": "{{parent}}", + "item": { + "messageId": "{{message:1}}", + "rating": "negative", + "note": "Explain the result.", + "version": "{{feedback-version:1}}", + "createdAt": 0, + "updatedAt": 0 + } + } + }, + { + "type": "feedback/message-put", + "seq": 63, + "time": 0, + "data": { + "sessionId": "{{parent}}", + "item": { + "messageId": "{{message:1}}", + "rating": "positive", + "note": "The explanation is clear now.", + "version": "{{feedback-version:2}}", + "createdAt": 0, + "updatedAt": 0 + } + } + }, + { + "type": "feedback/message-delete", + "seq": 64, + "time": 0, + "data": { + "sessionId": "{{parent}}", + "messageId": "{{message:1}}" + } + }, + { + "type": "turn/end", + "seq": 65, + "time": 0, "data": { "turn": 1, "reason": { @@ -3942,7 +4013,7 @@ "provider": "deepseek-official", "model": "smoke-model" }, - "id": "{{messageId}}" + "id": "{{message:1}}" }, "usage": { "inputTokens": 3, @@ -4028,9 +4099,116 @@ "payload": { "sessionId": "{{parent}}", "event": { - "type": "turn/end", + "type": "command/run", "seq": 59, "time": 0, + "data": { + "commandId": "{{command:1}}", + "name": "feedback", + "source": { + "kind": "user" + } + } + } + } + }, + { + "method": "session.event", + "payload": { + "sessionId": "{{parent}}", + "event": { + "type": "feedback/record", + "seq": 60, + "time": 0, + "data": { + "text": "The session needs a clearer explanation." + } + } + } + }, + { + "method": "session.event", + "payload": { + "sessionId": "{{parent}}", + "event": { + "type": "command/done", + "seq": 61, + "time": 0, + "data": { + "commandId": "{{command:1}}", + "kind": "success", + "text": "Feedback recorded for session {{parent}}\nAnonymous user: {{anonymous-user}}." + } + } + } + }, + { + "method": "session.event", + "payload": { + "sessionId": "{{parent}}", + "event": { + "type": "feedback/message-put", + "seq": 62, + "time": 0, + "data": { + "sessionId": "{{parent}}", + "item": { + "messageId": "{{message:1}}", + "rating": "negative", + "note": "Explain the result.", + "version": "{{feedback-version:1}}", + "createdAt": 0, + "updatedAt": 0 + } + } + } + } + }, + { + "method": "session.event", + "payload": { + "sessionId": "{{parent}}", + "event": { + "type": "feedback/message-put", + "seq": 63, + "time": 0, + "data": { + "sessionId": "{{parent}}", + "item": { + "messageId": "{{message:1}}", + "rating": "positive", + "note": "The explanation is clear now.", + "version": "{{feedback-version:2}}", + "createdAt": 0, + "updatedAt": 0 + } + } + } + } + }, + { + "method": "session.event", + "payload": { + "sessionId": "{{parent}}", + "event": { + "type": "feedback/message-delete", + "seq": 64, + "time": 0, + "data": { + "sessionId": "{{parent}}", + "messageId": "{{message:1}}" + } + } + } + }, + { + "method": "session.event", + "payload": { + "sessionId": "{{parent}}", + "event": { + "type": "turn/end", + "seq": 65, + "time": 0, "data": { "turn": 1, "reason": { diff --git a/scripts/snapshots/python-sdk-single-exe/advanced/session.v2.jsonl b/scripts/snapshots/python-sdk-single-exe/advanced/session.v2.jsonl index f03172bb92..651f662c19 100644 --- a/scripts/snapshots/python-sdk-single-exe/advanced/session.v2.jsonl +++ b/scripts/snapshots/python-sdk-single-exe/advanced/session.v2.jsonl @@ -56,6 +56,12 @@ {"type":"step/start","data":{"turn":1,"step":7}} {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"smoke-model","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"system":"{{system}}","tools":["cordis_define","cordis_inspect_list","cordis_inspect_query","cordis_inspect_self","cordis_run","cordis_stop","cordis_undefine","job_kill","job_list","job_output","run_code","subagent","workflow"]},"reason":"change"}} {"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{parent}}","sessionFormatVersion":2,"throughSeq":55}} -{"type":"assistant/message","data":{"turn":1,"step":7,"message":{"role":"assistant","content":[{"type":"text","text":"ADVANCED_EXECUTABLE_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":0,"index":0,"dt":[],"texts":["ADVANCED_EXECUTABLE_OK"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"ADVANCED_EXECUTABLE_OK"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"} +{"type":"assistant/message","data":{"turn":1,"step":7,"message":{"role":"assistant","content":[{"type":"text","text":"ADVANCED_EXECUTABLE_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{message:1}}"},"usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":0,"index":0,"dt":[],"texts":["ADVANCED_EXECUTABLE_OK"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"ADVANCED_EXECUTABLE_OK"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3,"totalTokens":6}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"} {"type":"step/end","data":{"turn":1,"step":7}} +{"type":"command/run","data":{"commandId":"{{command:1}}","name":"feedback","source":{"kind":"user"}}} +{"type":"feedback/record","data":{"text":"The session needs a clearer explanation."}} +{"type":"command/done","data":{"commandId":"{{command:1}}","kind":"success","text":"Feedback recorded for session {{parent}}\nAnonymous user: {{anonymous-user}}."}} +{"type":"feedback/message-put","data":{"sessionId":"{{parent}}","item":{"messageId":"{{message:1}}","rating":"negative","note":"Explain the result.","version":"{{feedback-version:1}}","createdAt":0,"updatedAt":0}}} +{"type":"feedback/message-put","data":{"sessionId":"{{parent}}","item":{"messageId":"{{message:1}}","rating":"positive","note":"The explanation is clear now.","version":"{{feedback-version:2}}","createdAt":0,"updatedAt":0}}} +{"type":"feedback/message-delete","data":{"sessionId":"{{parent}}","messageId":"{{message:1}}"}} {"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index ecbfecc038..168b275a8c 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -1951,6 +1951,16 @@ "symbol": "MessageFeedbackItem", "source": "packages/feedback/message-feedback/src/types.ts" }, + { + "doc": "docs/subsystems/feedback.md", + "symbol": "MessageFeedbackPut", + "source": "packages/feedback/message-feedback/src/types.ts" + }, + { + "doc": "docs/subsystems/feedback.md", + "symbol": "MessageFeedbackDelete", + "source": "packages/feedback/message-feedback/src/types.ts" + }, { "doc": "docs/subsystems/feedback.md", "symbol": "MessageFeedbackListRequest", diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts index 33010ed079..86b82d2d37 100644 --- a/scripts/verify-package-readme-model-experience.ts +++ b/scripts/verify-package-readme-model-experience.ts @@ -89,7 +89,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly> = { 'packages/client/ui-conversation': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' }, 'packages/client/ui-approval': { kind: 'none', reason: 'Browser-side approval presentation; registers nothing model-facing.' }, 'packages/client/ui-chat': { kind: 'none', reason: 'Browser-side Chat presentation; registers nothing model-facing.' }, - 'packages/client/ui-message-feedback': { kind: 'none', reason: 'Browser-side controls over the message-feedback sidecar; ratings and notes never enter the Session log, model context, or telemetry.' }, + 'packages/client/ui-message-feedback': { kind: 'none', reason: 'Browser-side controls over log-only message feedback; ratings and notes never enter model context or change model-input tokens.' }, 'packages/client/ui-tool': { kind: 'none', reason: 'Browser-side Tool presentation layer; renders logged calls without changing model context.' }, 'packages/client/ui-jobs': { kind: 'none', reason: 'Browser-side read-only projection of ctx.jobs records; dsh-tool-jobs owns the model-facing behavior.' }, 'packages/client/ui-schedule': { kind: 'none', reason: 'Browser-side read-only projection of active Schedule records; dsh-schedule owns the model-facing tools and delivery.' }, diff --git a/snapshots/sdk/sdk.snapshot.ts b/snapshots/sdk/sdk.snapshot.ts index 47642fd908..c234163424 100644 --- a/snapshots/sdk/sdk.snapshot.ts +++ b/snapshots/sdk/sdk.snapshot.ts @@ -336,11 +336,17 @@ function normalizeNotifications(notifications: readonly HarnessNotification[], c const events = notifications .filter(n => n.method === 'session.event') .map(n => n.params.event as Record) + const typedFeedback = events.some(event => event.type === 'feedback/message-put') + const eventLog = events.map(event => JSON.stringify(event)).join('\n') + '\n' + const typedLog = typedFeedback + ? redactSessionSnapshotIds([JSON.stringify({ type: 'session', id: ctx.sessionIds[0] }) + '\n' + eventLog])[0]!.split('\n').slice(1).join('\n') + : eventLog const normalizedEvents = events.length === 0 ? [] : scrubRequestHeaders(normalizeSessionLog( - normalizeSessionFormatProvenance(`${events.map(event => JSON.stringify(event)).join('\n')}\n`), + normalizeSessionFormatProvenance(typedLog), ctx, + typedFeedback ? { identityMode: 'preserve' } : {}, )).trimEnd().split('\n').map(line => JSON.parse(line) as Record) let eventIndex = 0 const records = notifications.map((notification) => { @@ -348,7 +354,11 @@ function normalizeNotifications(notifications: readonly HarnessNotification[], c const event = normalizedEvents[eventIndex++] return { method: notification.method, params: { ...notification.params, event } } }) - return normalizeStdout(`${records.map(record => JSON.stringify(record)).join('\n')}\n`, ctx) + let output = records.map(record => JSON.stringify(record)).join('\n') + '\n' + if (typedFeedback) { + for (const [index, id] of ctx.sessionIds.entries()) output = output.replaceAll(id, '{{session:' + (index + 1) + '}}') + } + return normalizeStdout(output, ctx, typedFeedback ? { identityMode: 'preserve' } : {}) } /** Normalize the owned-run projection. */ @@ -597,6 +607,12 @@ async function runScenario(scenario: CorpusScenario): Promise<{ }, }) results.push(result) + if (scenario.manifest.environment?.DSH_SNAPSHOT_FEEDBACK === '1') { + const feedback = result.events.filter(event => event.type.startsWith('feedback/')) + expect(feedback.map(event => event.type)).toEqual([ + 'feedback/record', 'feedback/message-put', 'feedback/message-put', 'feedback/message-delete', + ]) + } await waitForRootEvent( subscription, sessionId, diff --git a/snapshots/sdk/text-turn/cordis.yml b/snapshots/sdk/text-turn/cordis.yml index a4b88aabea..d3111e59ad 100644 --- a/snapshots/sdk/text-turn/cordis.yml +++ b/snapshots/sdk/text-turn/cordis.yml @@ -32,3 +32,13 @@ name: '@deepseek-ai/dsh-session-log-deepseek' config: enabled: true + +- insert: + - id: snapshot-message-feedback + name: '@deepseek-ai/dsh-message-feedback' + disabled: !!js "process.env.DSH_SNAPSHOT_FEEDBACK !== '1'" + config: + maxNoteBytes: 1024 + - id: snapshot-feedback-producer + name: './feedback-producer.mjs' + disabled: !!js "process.env.DSH_SNAPSHOT_FEEDBACK !== '1'" diff --git a/snapshots/sdk/text-turn/feedback-producer.mjs b/snapshots/sdk/text-turn/feedback-producer.mjs new file mode 100644 index 0000000000..864ddc846d --- /dev/null +++ b/snapshots/sdk/text-turn/feedback-producer.mjs @@ -0,0 +1,27 @@ +/** Exercise real feedback services before the SDK closes the recorded root turn. */ +export const name = 'snapshot-feedback-producer' +export const inject = ['commands', 'messageFeedback'] + +/** + * @param {import('@deepseek-ai/cordis').Context} ctx - Composed runtime services. + */ +export function apply(ctx) { + ctx.on('agent/turn-stopping', async ({ agent, signal }) => { + if (agent.session.header.parentSession !== undefined) return + const messages = agent.session.deriveMessages() + const message = messages.findLast(message => message.role === 'assistant') + if (message === undefined) throw new Error('feedback snapshot requires an assistant message') + const command = await ctx.commands.execute(agent, '/feedback The session needs a clearer explanation.', [], signal) + if (command?.result.kind !== 'success') throw new Error('feedback command did not succeed') + const target = { sessionId: agent.id, messageId: message.id } + const created = await ctx.messageFeedback.put({ ...target, rating: 'negative', note: 'Explain the result.', ifVersion: null }) + if (!created.ok) throw new Error(created.error.code) + const edited = await ctx.messageFeedback.put({ ...target, rating: 'positive', note: 'The explanation is clear now.', ifVersion: created.value.version }) + if (!edited.ok) throw new Error(edited.error.code) + const deleted = await ctx.messageFeedback.delete({ ...target, ifVersion: edited.value.version }) + if (!deleted.ok) throw new Error(deleted.error.code) + if (JSON.stringify(agent.session.deriveMessages()) !== JSON.stringify(messages)) { + throw new Error('feedback changed model-visible messages') + } + }) +} diff --git a/snapshots/sdk/text-turn/notifications.expected.jsonl b/snapshots/sdk/text-turn/notifications.expected.jsonl index 37a1199c12..b947c2a5e8 100644 --- a/snapshots/sdk/text-turn/notifications.expected.jsonl +++ b/snapshots/sdk/text-turn/notifications.expected.jsonl @@ -1,15 +1,21 @@ -{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"agent/inbox/spliced","seq":3,"time":0,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Reply with exactly: SDK snapshot OK"}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"}]}}}} -{"method":"session.status","params":{"sessionId":"{{sessionId}}","status":"running"}} -{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"turn/start","seq":4,"time":0,"data":{"turn":1}}}} -{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"agent/inbox/spliced","seq":5,"time":0,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}}} -{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"step/start","seq":6,"time":0,"data":{"turn":1,"step":1}}}} -{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"user/message","seq":7,"time":0,"data":{"content":[{"type":"text","text":"Reply with exactly: SDK snapshot OK"}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}}} -{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"user/message","seq":8,"time":0,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}}} -{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"session/title","seq":9,"time":0,"data":{"title":"Reply with exactly: SDK snapshot","messageSeqs":[7],"source":{"kind":"fallback"}}}}} -{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"request/header","seq":10,"time":0,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}}} -{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"request/context","seq":11,"time":0,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}}} -{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"session-log-deepseek/delivery-accepted","seq":12,"time":0,"data":{"sessionId":"{{sessionId}}"}}}} -{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":13,"time":0,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to reply with exactly \"SDK snapshot OK\". Let me do that."},{"type":"text","text":"SDK snapshot OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{sessionId}}"},"usage":{"inputTokens":1769,"outputTokens":24,"cacheReadTokens":0,"reasoningTokens":19},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":0,"index":0,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," user"," wants"," me"," to"," reply"," with"," exactly"," \"","SD","K"," snapshot"," OK","\"."," Let"," me"," do"," that","."]},{"type":"chunk","time":0,"chunk":{"type":"block-start","index":1,"blockType":"text"}},{"type":"text-chunks","time0":0,"index":1,"dt":[0,0,0],"texts":["SD","K"," snapshot"," OK"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to reply with exactly \"SDK snapshot OK\". Let me do that."}}},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"SDK snapshot OK"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":1769,"outputTokens":24,"cacheReadTokens":0,"reasoningTokens":19}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}}} -{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"step/end","seq":14,"time":0,"data":{"turn":1,"step":1}}}} -{"method":"session.event","params":{"sessionId":"{{sessionId}}","event":{"type":"turn/end","seq":15,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}}} -{"method":"session.status","params":{"sessionId":"{{sessionId}}","status":"idle"}} +{"method":"session.event","params":{"sessionId":"{{session:1}}","event":{"type":"agent/inbox/spliced","seq":3,"time":0,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Reply with exactly: SDK snapshot OK"}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}}}} +{"method":"session.status","params":{"sessionId":"{{session:1}}","status":"running"}} +{"method":"session.event","params":{"sessionId":"{{session:1}}","event":{"type":"turn/start","seq":4,"time":0,"data":{"turn":1}}}} +{"method":"session.event","params":{"sessionId":"{{session:1}}","event":{"type":"agent/inbox/spliced","seq":5,"time":0,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}}} +{"method":"session.event","params":{"sessionId":"{{session:1}}","event":{"type":"step/start","seq":6,"time":0,"data":{"turn":1,"step":1}}}} +{"method":"session.event","params":{"sessionId":"{{session:1}}","event":{"type":"user/message","seq":7,"time":0,"data":{"content":[{"type":"text","text":"Reply with exactly: SDK snapshot OK"}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}}} +{"method":"session.event","params":{"sessionId":"{{session:1}}","event":{"type":"user/message","seq":8,"time":0,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: \"{{cwd}}\". Some platform temporary areas may also be writable."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{message:2}}"},"surfaceOp":"append"}}} +{"method":"session.event","params":{"sessionId":"{{session:1}}","event":{"type":"session/title","seq":9,"time":0,"data":{"title":"Reply with exactly: SDK snapshot","messageSeqs":[7],"source":{"kind":"fallback"}}}}} +{"method":"session.event","params":{"sessionId":"{{session:1}}","event":{"type":"request/header","seq":10,"time":0,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}}} +{"method":"session.event","params":{"sessionId":"{{session:1}}","event":{"type":"request/context","seq":11,"time":0,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}}} +{"method":"session.event","params":{"sessionId":"{{session:1}}","event":{"type":"session-log-deepseek/delivery-accepted","seq":12,"time":0,"data":{"sessionId":"{{session:1}}","throughSeq":11}}}} +{"method":"session.event","params":{"sessionId":"{{session:1}}","event":{"type":"assistant/message","seq":13,"time":0,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to reply with exactly \"SDK snapshot OK\". Let me do that."},{"type":"text","text":"SDK snapshot OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:3}}"},"usage":{"inputTokens":1769,"outputTokens":24,"cacheReadTokens":0,"reasoningTokens":19},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":0,"index":0,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," user"," wants"," me"," to"," reply"," with"," exactly"," \"","SD","K"," snapshot"," OK","\"."," Let"," me"," do"," that","."]},{"type":"chunk","time":0,"chunk":{"type":"block-start","index":1,"blockType":"text"}},{"type":"text-chunks","time0":0,"index":1,"dt":[0,0,0],"texts":["SD","K"," snapshot"," OK"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to reply with exactly \"SDK snapshot OK\". Let me do that."}}},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"SDK snapshot OK"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":1769,"outputTokens":24,"cacheReadTokens":0,"reasoningTokens":19}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}}} +{"method":"session.event","params":{"sessionId":"{{session:1}}","event":{"type":"step/end","seq":14,"time":0,"data":{"turn":1,"step":1}}}} +{"method":"session.event","params":{"sessionId":"{{session:1}}","event":{"type":"command/run","seq":15,"time":0,"data":{"commandId":"{{command:1}}","name":"feedback","source":{"kind":"user"}}}}} +{"method":"session.event","params":{"sessionId":"{{session:1}}","event":{"type":"feedback/record","seq":16,"time":0,"data":{"text":"The session needs a clearer explanation."}}}} +{"method":"session.event","params":{"sessionId":"{{session:1}}","event":{"type":"command/done","seq":17,"time":0,"data":{"commandId":"{{command:1}}","kind":"success","text":"Feedback recorded for session {{session:1}}\nAnonymous user: {{id:1}}."}}}} +{"method":"session.event","params":{"sessionId":"{{session:1}}","event":{"type":"feedback/message-put","seq":18,"time":0,"data":{"sessionId":"{{session:1}}","item":{"messageId":"{{message:3}}","rating":"negative","note":"Explain the result.","version":"{{id:2}}","createdAt":0,"updatedAt":0}}}}} +{"method":"session.event","params":{"sessionId":"{{session:1}}","event":{"type":"feedback/message-put","seq":19,"time":0,"data":{"sessionId":"{{session:1}}","item":{"messageId":"{{message:3}}","rating":"positive","note":"The explanation is clear now.","version":"{{id:3}}","createdAt":0,"updatedAt":0}}}}} +{"method":"session.event","params":{"sessionId":"{{session:1}}","event":{"type":"feedback/message-delete","seq":20,"time":0,"data":{"sessionId":"{{session:1}}","messageId":"{{message:3}}"}}}} +{"method":"session.event","params":{"sessionId":"{{session:1}}","event":{"type":"turn/end","seq":21,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}}} +{"method":"session.status","params":{"sessionId":"{{session:1}}","status":"idle"}} diff --git a/snapshots/sdk/text-turn/session.v2.jsonl b/snapshots/sdk/text-turn/session.v2.jsonl index 860a95b4cf..e37b94e6f0 100644 --- a/snapshots/sdk/text-turn/session.v2.jsonl +++ b/snapshots/sdk/text-turn/session.v2.jsonl @@ -12,6 +12,12 @@ {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} {"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}} {"type":"session-log-deepseek/delivery-accepted","data":{"sessionId":"{{session:1}}","sessionFormatVersion":2,"throughSeq":11}} -{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to reply with exactly \"SDK snapshot OK\". Let me do that."},{"type":"text","text":"SDK snapshot OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:3}}"},"usage":{"inputTokens":1769,"outputTokens":24,"cacheReadTokens":0,"reasoningTokens":19},"stream":[{"type":"chunk","time":1788199069112,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1788199069112,"index":0,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," user"," wants"," me"," to"," reply"," with"," exactly"," \"","SD","K"," snapshot"," OK","\"."," Let"," me"," do"," that","."]},{"type":"chunk","time":1788199069112,"chunk":{"type":"block-start","index":1,"blockType":"text"}},{"type":"text-chunks","time0":1788199069112,"index":1,"dt":[0,0,0],"texts":["SD","K"," snapshot"," OK"]},{"type":"chunk","time":1788199069112,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to reply with exactly \"SDK snapshot OK\". Let me do that."}}},{"type":"chunk","time":1788199069112,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"SDK snapshot OK"}}},{"type":"chunk","time":1788199069112,"chunk":{"type":"usage","usage":{"inputTokens":1769,"outputTokens":24,"cacheReadTokens":0,"reasoningTokens":19}}},{"type":"chunk","time":1788199069112,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"} +{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to reply with exactly \"SDK snapshot OK\". Let me do that."},{"type":"text","text":"SDK snapshot OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:3}}"},"usage":{"inputTokens":1769,"outputTokens":24,"cacheReadTokens":0,"reasoningTokens":19},"stream":[{"type":"chunk","time":1788603540672,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1788603540672,"index":0,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," user"," wants"," me"," to"," reply"," with"," exactly"," \"","SD","K"," snapshot"," OK","\"."," Let"," me"," do"," that","."]},{"type":"chunk","time":1788603540672,"chunk":{"type":"block-start","index":1,"blockType":"text"}},{"type":"text-chunks","time0":1788603540672,"index":1,"dt":[0,0,0],"texts":["SD","K"," snapshot"," OK"]},{"type":"chunk","time":1788603540672,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to reply with exactly \"SDK snapshot OK\". Let me do that."}}},{"type":"chunk","time":1788603540672,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"SDK snapshot OK"}}},{"type":"chunk","time":1788603540672,"chunk":{"type":"usage","usage":{"inputTokens":1769,"outputTokens":24,"cacheReadTokens":0,"reasoningTokens":19}}},{"type":"chunk","time":1788603540672,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"} {"type":"step/end","data":{"turn":1,"step":1}} +{"type":"command/run","data":{"commandId":"{{command:1}}","name":"feedback","source":{"kind":"user"}}} +{"type":"feedback/record","data":{"text":"The session needs a clearer explanation."}} +{"type":"command/done","data":{"commandId":"{{command:1}}","kind":"success","text":"Feedback recorded for session {{session:1}}\nAnonymous user: {{id:1}}."}} +{"type":"feedback/message-put","data":{"sessionId":"{{session:1}}","item":{"messageId":"{{message:3}}","rating":"negative","note":"Explain the result.","version":"{{id:2}}","createdAt":0,"updatedAt":0}}} +{"type":"feedback/message-put","data":{"sessionId":"{{session:1}}","item":{"messageId":"{{message:3}}","rating":"positive","note":"The explanation is clear now.","version":"{{id:3}}","createdAt":0,"updatedAt":0}}} +{"type":"feedback/message-delete","data":{"sessionId":"{{session:1}}","messageId":"{{message:3}}"}} {"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/snapshots/sdk/text-turn/snapshot.yml b/snapshots/sdk/text-turn/snapshot.yml index da0d62a38c..e9153b97bc 100644 --- a/snapshots/sdk/text-turn/snapshot.yml +++ b/snapshots/sdk/text-turn/snapshot.yml @@ -3,6 +3,8 @@ scenario: text-turn profile: sdk composition: sdk-upload recording: live +environment: + DSH_SNAPSHOT_FEEDBACK: '1' header: class: sdk-upload pin: true diff --git a/snapshots/web/feedback-command/ack-expanded.expected.md b/snapshots/web/feedback-command/ack-expanded.expected.md index 4202ac6ef7..4d6f0f24c0 100644 --- a/snapshots/web/feedback-command/ack-expanded.expected.md +++ b/snapshots/web/feedback-command/ack-expanded.expected.md @@ -40,10 +40,10 @@ - img - text: Ran for {{duration}} - text: {{clock}} -- 'button "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}. Session sharing is enabled."': +- 'button "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}."': - img - img - - text: "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}. Session sharing is enabled." + - text: "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}." - textbox "Message or run a task... / commands, @ files or sessions" - button "Commands": - img diff --git a/snapshots/web/feedback-command/ack.expected.md b/snapshots/web/feedback-command/ack.expected.md index 9d1a40d048..7dfd7fe123 100644 --- a/snapshots/web/feedback-command/ack.expected.md +++ b/snapshots/web/feedback-command/ack.expected.md @@ -32,10 +32,10 @@ - img - text: Ran for {{duration}} - text: {{clock}} -- 'button "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}. Session sharing is enabled."': +- 'button "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}."': - img - img - - text: "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}. Session sharing is enabled." + - text: "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}." - textbox "Message or run a task... / commands, @ files or sessions" - button "Commands": - img diff --git a/snapshots/web/feedback-command/session.v2.jsonl b/snapshots/web/feedback-command/session.v2.jsonl index 1fdf817264..200aa74579 100644 --- a/snapshots/web/feedback-command/session.v2.jsonl +++ b/snapshots/web/feedback-command/session.v2.jsonl @@ -16,4 +16,4 @@ {"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}} {"type":"command/run","data":{"commandId":"{{command:1}}","name":"feedback","source":{"kind":"user"}}} {"type":"feedback/record","data":{"text":"the diff view is unreadable"}} -{"type":"command/done","data":{"commandId":"{{command:1}}","kind":"success","text":"Feedback recorded for session {{session:1}}\nAnonymous user: {{anonymousUserId}}. Session sharing is enabled."}} +{"type":"command/done","data":{"commandId":"{{command:1}}","kind":"success","text":"Feedback recorded for session {{session:1}}\nAnonymous user: {{anonymousUserId}}."}} diff --git a/snapshots/web/feedback-release/ack-expanded.expected.md b/snapshots/web/feedback-release/ack-expanded.expected.md index 4f88197939..4d6f0f24c0 100644 --- a/snapshots/web/feedback-release/ack-expanded.expected.md +++ b/snapshots/web/feedback-release/ack-expanded.expected.md @@ -40,10 +40,10 @@ - img - text: Ran for {{duration}} - text: {{clock}} -- 'button "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}. Session sharing is feedback-gated; recording feedback uploads the session records not yet shared."': +- 'button "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}."': - img - img - - text: "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}. Session sharing is feedback-gated; recording feedback uploads the session records not yet shared." + - text: "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}." - textbox "Message or run a task... / commands, @ files or sessions" - button "Commands": - img diff --git a/snapshots/web/feedback-release/ack.expected.md b/snapshots/web/feedback-release/ack.expected.md index ed35656abe..7dfd7fe123 100644 --- a/snapshots/web/feedback-release/ack.expected.md +++ b/snapshots/web/feedback-release/ack.expected.md @@ -32,10 +32,10 @@ - img - text: Ran for {{duration}} - text: {{clock}} -- 'button "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}. Session sharing is feedback-gated; recording feedback uploads the session records not yet shared."': +- 'button "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}."': - img - img - - text: "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}. Session sharing is feedback-gated; recording feedback uploads the session records not yet shared." + - text: "feedback Feedback recorded for session session-{{uuid}} Anonymous user: {{uuid}}." - textbox "Message or run a task... / commands, @ files or sessions" - button "Commands": - img diff --git a/snapshots/web/seeded-history/feedback-row.expected.md b/snapshots/web/seeded-history/feedback-row.expected.md index 57505c708b..7ce1e515d4 100644 --- a/snapshots/web/seeded-history/feedback-row.expected.md +++ b/snapshots/web/seeded-history/feedback-row.expected.md @@ -58,10 +58,10 @@ - text: Context injection AGENTS.md - img - text: permission preset read-only -- 'button "feedback Feedback recorded for session {{seededId}} Anonymous user: {{uuid}}. Session sharing is not configured." [expanded]': +- 'button "feedback Feedback recorded for session {{seededId}} Anonymous user: {{uuid}}." [expanded]': - img - - text: "feedback Feedback recorded for session {{seededId}} Anonymous user: {{uuid}}. Session sharing is not configured." -- text: "Feedback recorded for session {{seededId}} Anonymous user: {{uuid}}. Session sharing is not configured." + - text: "feedback Feedback recorded for session {{seededId}} Anonymous user: {{uuid}}." +- text: "Feedback recorded for session {{seededId}} Anonymous user: {{uuid}}." - textbox "Message or run a task... / commands, @ files or sessions" - button "Commands": - img