README.md 11 KB
description: "Per-message ratings and notes for finalized assistant messages, for users and maintainers choosing, composing, or debugging the feedback service."
kind: "package-reference"
@deepseek-ai/dsh-message-feedback
English | 中文
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.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- 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.
Configuration
| Field | Default | Meaning |
|---|---|---|
maxNoteBytes |
required | Maximum UTF-8 byte length accepted for one optional note. |
- 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 is the exhaustive source for every accepted field and its JSDoc.
Reading and changing feedback
Callers use three operations to read and change feedback for a session:
| Operation | Request | Success | Rejected when |
|---|---|---|---|
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 |
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.
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.
Understand the implementation
Implementation internals — click to expand
### Design concept 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. ### 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 inspected without resuming an agent, absence is decided from the persistence catalog rather than guessed, and only a real, sent assistant message is a valid target. The flush and inspect 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. ### 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 | | [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant; the domain schema validates rows on reopen) |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 — the public types, Remote contract, and Web consumer details.
- Message-feedback sidecar decision — the design boundary that keeps this sidecar out of Session-log content.
- Session persistence subsystem —
inspect,readFrom, andflushsemantics behind the durability barrier. - dsh-client-ui-message-feedback — the browser consumer that drives the Host Remote contract.
- Feedback package map — where per-message feedback sits next to the log-only capture command.
Model Experience
Local message-feedback state
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.
Token effect
Zero. No request, result, rating, note, timestamp, or failure from this package enters a model request.
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.
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/removedmean 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. - Detach/catalog retirement window — 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. - 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/deletecarry 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. - Catalog and row bounds — a cold request scans the complete Session snapshot catalog because persistence has no lookup-by-id metadata operation.
maxNoteBytesbounds one note, but the item count and aggregate retained bytes of one Session row are not capped; an indexed metadata read and deployment-owned row bound remain deferred until a concrete consumer defines their policy.