_KermanandTianyi Cui
f4a32dbd0a
Represent tool results as tool-role messages and migrate released wrappers without losing outer own JSON fields, call identity, error state, or writer field order. Refuse nested or wrapper-only information that has no lossless current representation before successor publication. Validate current event relationships directly instead of projecting V4 data back into V3. Keep lifecycle, PTC, title/command, compaction, system-field and retired-syntax checks on catalog restoration and ordinary JSONL opens. The Worker JSON equality helper must inspect own keys so it cannot admit PTC arguments that Node rejects. Keep the source role change, required native admission and consumer fixture updates in one complete review layer. Explain shared-type changes in the persistence record and the native reader rationale in its existing note. Use checked branded fixture identities and discriminant narrowing instead of unknown double casts; fixture values and assertions remain intact. This recomposes the original tool-role work by _Kerman with the independently validated migration and admission repairs by Tianyi Cui. Frozen generations and snapshot input version selection are retained. Co-authored-by: Tianyi Cui <[email protected]>
description, kind
| description | kind |
|---|---|
| Semantic session durability checkpoints for users and maintainers deploying persisted agents that must not lose a model request or tool side effect on crash. | package-reference |
@deepseek-ai/dsh-session-checkpoint-policy
English | 中文
Summary
Use this package with a session persistence backend to make work durable before a model request, before a top-level tool can cause external effects, and before the next agent step begins. After each checkpoint, work can resume after a crash from stored requests, tool calls, responses, and results without loss. Checkpoint failures are fail-closed: a model adapter or top-level tool body does not run until the durable write succeeds. The package has no configuration and adds no prompt or tool schema; unfinished Assistant streams remain transient, and interrupted tool calls recover with an unknown outcome instead of an automatic retry.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
Mount this plugin in any composition that persists sessions and must survive a crash without redoing or losing work. Persistence and checkpoint scheduling are separate plugins: a backend stores the event log, and this policy decides when the store must be flushed.
When to choose it
Choose it for every persisted agent that can be interrupted — a crash between a recorded tool call and its result, or between a model request and its response, is exactly the failure this policy contains. Loading a backend without it is valid but weaker: events still inside the backend's batching window or an outstanding write can be lost. Skip the policy when nothing persists sessions, or when a specialized deployment deliberately replaces the checkpoint schedule.
Minimal configuration
No configuration fields exist; the plugin is a single load beside one persistence backend:
- id: session-persistence
name: '@deepseek-ai/dsh-session-persistence-jsonl'
- id: session-checkpoints
name: '@deepseek-ai/dsh-session-checkpoint-policy'
What becomes durable
Three barriers are checkpointed. The model request is flushed before the adapter stream is constructed, so a crash before a response cannot replay an unpersisted request. A top-level tool call is flushed before the tool body runs, so a recorded call is durable before any external side effect; nested tool dispatches reuse the outer call's checkpoint. At each agent/pre-step boundary, everything the preceding step committed — its response and ordered tool results — is flushed before the next request is derived.
Observable behavior and failures
After a checkpoint, the checkpointed work is durable: resume restores it from the store like any persisted session. If cancellation lands while a tool checkpoint flush is pending, the wrapper returns the canonical ABORTED_BEFORE_DISPATCH result and never enters the tool body. A checkpoint rejection is fail-closed at both boundaries — the adapter or top-level tool body does not run — and a step-boundary rejection fails the turn before another request starts.
Understand the implementation
Implementation internals — click to expand
This section explains how the policy joins the loop and the persistence seam; the observable contract is covered in Use this package.
Design concept
The plugin is a listener-only composition over three seams, with no state of its own: it wraps llm/stream so the downstream stream is not constructed until the live session's buffered request events are durable, wraps tools/execute after pre-execute policy and guards so a top-level tool body runs only after its recorded call is durable, and listens to agent/pre-step to persist the preceding response/result batch before request derivation. The session store's flush is the shared durability barrier; concurrent tool checkpoints serialize through it and cannot duplicate sequence numbers.
Source map
| File | Role |
|---|---|
src/index.ts |
Plugin entry: apply installs the three checkpoint listeners |
| — | No runtime invariant companion is published; checkpoint ordering is enforced at the intercepted waterfall and persistence seams; this stateless policy owns no independent mutable relation. |
Further Exploration
Read these pages when the package-level contract is not enough. They move from the durability model to the seam it joins and the shipped backends.
- Session persistence subsystem — the flush checkpoint, batching window, and crash recovery every backend shares.
- Session package map — adjacent persistence, projection, title, and telemetry packages.
- Session persistence seam — the
ctx.sessionPersistenceservice this policy flushes through. - JSONL persistence backend — the shipped backend this policy is usually loaded beside.
Model Experience
Interrupted calls
What the model sees
The plugin adds no prompt or tool schema. A hard crash after a tool checkpoint but before its result leaves a durable unmatched call; session recovery supplies the model-visible TOOL_OUTCOME_UNKNOWN result owned by dsh-session. The message permits retry for read-only or idempotent work and requires state verification or user confirmation for calls that may have side effects.
Token effect
Successful checkpoints add no tokens and do not change the request. Recovery adds one short tool-result message to balance the interrupted transcript.
KV Cache effect
The repair result is appended after the reusable prefix, so it does not invalidate earlier cache entries.
Known Limitations and Deferred Work
These limits define where the policy's durability guarantee stops. They are current package constraints, not a task backlog.
- Durable execution intent, not exactly-once effects — the policy records that a call was dispatched, not that its external effect completed. Side-effecting tools should forward
exec.callIdas an idempotency key when their provider supports one. - No checkpoint inside an active model attempt — a hard crash may lose transient Assistant frames that have not reached their durable
assistant/messageorassistant/attemptsettlement. - Unknown outcome, not automatic retry — a persisted call without a result cannot prove whether its external effect completed, so recovery records an unknown outcome instead of retrying.
Dev Note
Working context for maintainers — click to expand
None.