Yixiang TuandTianyi Cui
e0bd7e1960
Session V4 reserves developer-role messages for incremental model-visible session changes. The role, tool addition/removal blocks, and deferred-loading marker need a durable representation before independent provider and UI integrations can emit or consume them. Known developer events must match an open turn and step; unsupported providers and UI consumers fail explicitly. Request headers already capture full tool definitions. Persisting another ToolSchema in each addition would duplicate Session information and create two definitions that could drift. Additions therefore store toolName, and the containing developer event uses headerSeq to select one earlier known request/header for all its additions. A same-name replacement keeps its historical definition identity through restart, fork and surface changes. Removals require no definition copy, and ordinary developer messages omit headerSeq. Generic sourceEventSeqs remains independent derivation metadata. The rejected inline tool field is optional never with @persistenceReserved. The schema extractor retains that uninhabited slot, so permitting a future value requires a format bump instead of being mistaken for compatible optional metadata. Unrelated optional fields remain additive and readable. Native and Session admission reject missing, forward, non-header, unknown, ambiguous and incomplete referenced definitions, and reject the retired inline tool field. Validate complete schema fields only for referenced definitions, preserving unrelated header behavior and extra JSON metadata. Unknown ignorable records remain opaque. Empty developer nodes retain their surface position without producing a message or shadowing the system head. No automatic emitter, provider activation, UI implementation, or speculative public resolver is added. Keep the core-owned developer source binding beside the introduced role, including the request-only type rejection and attribution round trips. Update consumer guards, SDK/snapshot handling, bilingual owner documentation, and the same unreleased V4 acknowledgement. Keep earlier tool/source migration work and its documentation in the parent. Preserve the existing recorded Cordis inspection generation from the original developer change. Integration keeps the final source layer as the sole parent and preserves master's Messages input filtering, empty-user omission, empty tool results, and system-update placement. Developer/deferred guards still run before conversion. Native V4 admission, header references, reservation declarations, and generic tooling match the validated marker candidate. Parent-owned fixture and generator fixes remain in the parent. Earlier feature validation passed full build, full lint, 41 doc-sync gates, and 16 hygiene gates. The unchanged native implementation retains that evidence. The focused Session/V4/request-input run passes 884 tests across 38 files with 100% statement, branch, function and line coverage for the V3-to-V4 package and Session surface. Consumer tests pass 482 with one existing skip; tool, message and optional-field tests pass 146. Cordis inspection and compaction replays pass in both source and built modes (two cases per mode). Ten invalid referenced-definition/unknown-header controls failed before their scoped guards and pass after them. Reservation validation: the actual generated developer root records tool as optional primitive never. Widening it requires a bump, while traceId remains additive and preserved; all 85 focused reader/classifier tests pass. Final-parent validation: 205 tests across eight provider, type, catalog, Session and native-format files pass. The preserved parent fixture verifies Messages input-history replay; runtime/declaration and parent-owned-file comparisons show no loss during the final rebase. Co-authored-by: Tianyi Cui <[email protected]>
description, kind
| description | kind |
|---|---|
| Incremental canonical session-log upload for deployments enabling official DeepSeek request metadata. | package-reference |
@deepseek-ai/dsh-session-log-deepseek
English | 中文
Summary
Incremental canonical session-log upload for official DeepSeek LLM API requests. This function plugin injects ctx.sessions and ctx.deepseekLlmApiExtensions, then owns the dsh_session_log request field and the durable session-log-deepseek/delivery-accepted event from which it derives the acceptance watermark. Disable it only when the official API must not receive a Session-log suffix.
Table of Contents
- Configuration
- Request field
- Acceptance and retry
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Configuration
| Key | Default | Meaning |
|---|---|---|
enabled |
true |
Register the dsh_session_log contribution. Set it to false to stop Session-log upload. |
Shipped profiles mount the plugin, so the default configuration registers the request field and appends the acceptance watermark; an overlay opts out with enabled: false.
Request field
For a request carrying a live sessionId, the plugin folds the greatest accepted watermark for that exact Session format generation, snapshots Session.events, and sends the contiguous suffix after the watermark. A process-local fold scans each event once and consumes later appends incrementally; restart and HMR rebuild it from the durable log. The version-1 field contains sessionFormatVersion, a raw session header (seedLength is present only for a seeded Session), numeric afterSeq and throughSeq, and every complete canonical event translated to raw-number envelope fields. Forked sessions ignore inherited parent watermarks because both the recorded Session id and format generation must match the request source. Surface events require surfaceOp, with numeric startSeq and endSeq for replacements; only system, user, and tool events may carry sourceEventSeqs. Assistant provider metadata stays in the embedded stream, and log-only events carry neither metadata field.
Acceptance and retry
The DeepSeek adapter calls the prepared contribution's accept() after HTTP 2xx, before it consumes the SSE body. Acceptance appends session-log-deepseek/delivery-accepted with the uploaded throughSeq and sessionFormatVersion; a record that omits the format field denotes v0. The next request uploads that event as part of its new suffix. Transport and non-2xx failures append no acceptance record, so later requests resend the uncertain range. Concurrent deliveries may be accepted out of order; folding the maximum matching throughSeq prevents cursor regression.
A crash after server acceptance but before the watermark reaches persistence can replay an accepted range after restart. This is the at-least-once failure direction: uncertainty creates duplicates, never a skipped sequence. The ordinary session checkpoint policy persists the watermark at the next semantic checkpoint; this plugin performs no independent I/O.
Direct requests without a live Session omit dsh_session_log. Normal agent, compaction, and session-title calls carry their live Session id.
Model Experience
Session-log metadata
What the model sees
Nothing. dsh_session_log is a sibling of the DeepSeek request's model-input fields and is not inserted into messages, the system prompt, or tool schemas.
Token effect
Zero model-input tokens; the field only increases HTTP request bytes.
KV Cache effect
None; the model-visible request prefix remains unchanged.
Known Limitations and Deferred Work
- Crash-window duplicates — a 2xx followed by process loss before the acceptance watermark persists causes conservative replay on resume.
- No live Session means no field — direct or stale-session calls have no canonical log to snapshot; explicit absence semantics remain deferred.
- No independent request-size cap — complete delivery is fail-closed; provider rejection leaves the cursor unchanged instead of truncating the log.
Dev Note
Working context for maintainers — click to expand
None.