Turtle
38c7a9fbf4
* feat(release): publish package source, declaration maps, and documentation Every release member publishes its TypeScript source and the declaration maps that resolve into it, and @deepseek-ai/dsh publishes the repository Markdown documentation staged from docs/ at prepack time. The ./src/* export most members already declared now resolves for an installed consumer, and a consumer editor follows a declaration to the implementation. Bundled JavaScript maps stay unpublished; the vendored family and the Desktop runtime file policy are unchanged. Rationale: .agents/notes/implemented/process/2026-10-08-published-source-and-docs.md * feat(release): publish JavaScript maps and compress bundles Every emitted JavaScript map ships beside the bundle it describes, and the workspace build and the client preset compress bundles without mangling identifiers. The documentation payload now mirrors the website publication manifest and is removed again by `postpack`; Desktop and the Python executable exclude the published source, documentation, and maps; `clean` removes a staged copy. Typert's publication contract gains the Remote declaration map. * fix(release): keep node bundles readable for the worker image The browser worker image lowers `yield*` only as a whole statement and rewrites `for await` loops by their source layout, so compressed node-side entries either fail that lowering or lower to unparseable code. Only the browser bundles keep compression, which removes about a third of their text. The bundle-purity assertion now matches the module-loader call regardless of the quote style compression picks, and the release-pack fixture exercises the installed package's new documentation requirement. * feat(release): publish the whole documentation tree `@deepseek-ai/dsh` copies `docs/` in full instead of the website's page set: the maintainer documents, the generated migration records, the translation guidelines, and the `*.i18n.yaml` consistency records ship with the installed package, so the documentation's own links resolve without a checkout. * feat(release): publish the upgrade guides with the documentation The staged documentation keeps the website's page set and adds every `docs/upgrade-guide/` document, which is what an installed reader consults when a released change breaks something. The rest of the maintainer tree stays out. * test(release): expect source and maps in master's new payload cases * feat(release): keep installed docs and source readable in Desktop Desktop keeps the published src/ and docs/ trees inside app.asar, and every model shell call receives DSH_INSTALL_DIR and DSH_NODE_EXECUTABLE so an agent can read them through Electron's Node mode. Staging also generates docs/upgrade-guide/README.md, an index of the upgrade guides grouped by the release they upgrade from. Minified client bundles print string literals with backticks: the worker image packer now recognizes those chunk requests, client license banners are prepended after minification so their text survives, and the affected artifact tests accept either quote. * test(desktop): read archived docs through the Windows PowerShell form Regenerate the config catalog for the shifted shell-env source line. * test(desktop): wait for the GUI-subsystem Electron process from PowerShell * build(release): publish source and maps from the message-quotes package * build(release): publish source and maps from packages new on master * build(release): publish source and maps from the tool-office package
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 |
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.