dsh-context-steady
A DeepSeek Harness plugin that transplants the core of San v0.1
Context Steady onto DSH's public seams, without modifying the agent loop.
San's claim is about a runtime property, not a prompt template: provider-bound
context must stop growing linearly with the raw transcript, while continuity
and auditability survive. This plugin reproduces that property with DSH's own
Session log + ordered surface.
- TurnDigest ledger — every settled turn becomes a structured digest
(intent / actions / decisions / files / tool evidence / risks / next steps).
- Stable checkpoint — older digests roll up into one budget-bounded,
stable layer.
- Bounded ContextPacket — at turn settle (before
turn/end), a snapshot
user message carries checkpoint + recent digest tail under an explicit token
budget; it is durable in the session log and therefore survives resume.
- Provider payload pruning — when a span is covered by authoritative
digests, the new packet replaces the old packet and the covered raw span
in a single surface
replace. The append-only event log keeps the raw span;
only the provider-bound derived history shrinks.
- Durable authoritative digest sidecar — when DSH's optional
ctx.storageDomain service is mounted, successful LLM digests are stored
outside the session log and restored on resume. Without storage, replay
remains deterministic and fail-closed.
context_steady_expand — re-reads the raw journal span behind a digest
ref (bounded, oldest side truncated).context_steady_status — model-facing audit of the ledger, checkpoint,
packet budget, and pruning coverage.
Optional LLM digestion uses one side ctx.llm.stream request per configured
batch (four settled turns by default) with deterministic fallbacks; the main
loop has no hard dependency on it.
Why DSH is a good fit
| San mechanism | DSH mechanism used here |
|---|
san.turn_digest CustomEntry | in-memory ledger rebuilt from session.events; authoritative LLM digests optionally persisted through ctx.storageDomain |
san.context_checkpoint | deterministic fold over older digests, budgeted by ctx.tokenMeter |
san.context_packet injection | user/message with source: {kind:'plugin', plugin:'dsh-context-steady', form:'snapshot'} |
provider payload pruning (prune.ts) | one surfaceOp: {op:'replace', start, end} shadowing [old packet … covered raw] |
| append-only journal / audit | DSH session log (replacements shadow surface only, log is untouched) |
context_expand | context_steady_expand tool reading session.events[fromSeq..toSeq] |
| budget / reserve ratio | ctx.tokenMeter.measure + estimateMessage, San's formulas |
| optional LLM digest | batched ctx.llm.stream + JSON recovery + deterministic fallback |
One important difference: DSH third-party plugins cannot currently add new
required session event types safely (the known-event-type whitelist is built
into the harness). The digest ledger is therefore derived state, not a new
session event type. Deterministic fallback digests always rebuild from the
raw log. When the host exposes ctx.storageDomain (the standard web bundle
does), authoritative LLM digests also survive restart in the
dsh_context_steady sidecar domain; hosts without storage keep the original
deterministic replay behavior.
Install
Requires Node.js 22+ and DeepSeek Harness 0.1.0-rc.6.
The package declares Harness service libraries as peers; dsh plugin add
resolves them from the profile's @deepseek-ai/dsh-base bundle rather than
installing duplicate runtime copies.
Install the published package:
dsh plugin --profile demo add dsh-context-steady
dsh --profile demo --dump-config # expect a "# == dsh-context-steady" layer
To test a source checkout before publishing:
dsh plugin --profile demo add ./dsh-context-steady
Or manually append the bundle patch to a profile's cordis.patch.yml:
- insert:
- id: context-steady
name: 'dsh-context-steady'
config: {}
Configuration
All fields are optional and defaulted by the loader schema.
- id: context-steady
name: 'dsh-context-steady'
config:
enabled: true
activationThresholdTokens: 500000 # 0 = activate immediately; sticky once crossed
qualityWindowTokens: 240000
reserveRatio: 0.25
digest:
enabled: true
everyTurns: 4 # one side request covers up to four settled turns
llm:
enabled: false # enable to upgrade digests + authorize raw pruning
provider: "" # empty = reuse the session's routed provider/model
model: ""
maxTokens: 768 # budget for the whole batch response
timeoutMs: 20000
maxTranscriptChars: 12000 # budget shared by the batched turn payload
checkpoint:
enabled: true
everyTurns: 6
maxTokens: 12000
packet:
enabled: true
recentDigests: 5
maxTokens: 3000 # packet layer budget
prune:
enabled: true
requireAuthoritativeDigest: true # San's fail-closed default: deterministic digests never authorize raw pruning
toolExpandMaxChars: 8000
Packet budget follows San's legacy formula:
min(packet.maxTokens, max(0, qualityWindowTokens * (1 - reserveRatio))).
Behavior contract
- Before activation the plugin is native-equivalent: it only measures.
Activation is sticky per session and also restored on resume when a packet
event is already present in the log.
- After activation, every settled turn produces a digest. The deterministic
fallback is pure structure/regex extraction and never throws.
When LLM digestion is enabled, fallbacks are upgraded in batches at
digest.everyTurns; only those authoritative upgrades authorize pruning.
- Coverage is fail-closed. With
requireAuthoritativeDigest: true (the
default, matching San), only a successful LLM digest marks a turn
authoritative and allows its raw surface span to be shadowed. Fallback
digests still flow into the packet as continuity, but they never delete raw
provider-bound history. Set the flag to false only for experiments.
- The log is never mutated. Every packet is an append; pruning is a surface
replace whose sourceEventSeqs cite every shadowed node. UI/transcript
consumers read append-origin events; the replacement copy is model-only.
- The packet is durable, not a pre-step side effect. It is appended at
agent/turn-stopping, before turn/end, so its content, surfaceOp,
and sourceEventSeqs coverage survive process restarts with the session
log. agent/pre-step only fills in if a turn ended without one (for
example a crash before emission). If compaction runs in the same
waterfall, the packet is already on the surface and the compaction
transaction simply sees it.
- Digest sidecar is optional. The plugin does not require storage to
activate. With
ctx.storageDomain, authoritative digest content survives
restart; without it, packet/coverage stay durable in the session log and
historical digest content rebuilds as deterministic fallback.
- Batch failures stay fail-closed. Invalid JSON, timeout, model-routing
failure, or a result-count mismatch keeps every turn's deterministic
fallback and leaves its raw surface nodes provider-visible. The next cadence
boundary retries the pending batch.
Tools
context_steady_status() — ledger size, authoritative digest count,
sidecar availability/restored count, checkpoint coverage, packet
presence/tokens, surface/request token estimate, covered-node count.context_steady_expand(ref, maxChars?) — expands [ref: dshcs:digest:N]
from the packet into the raw journal span. Output is bounded; the oldest
side is truncated.
Verification
See BENCHMARK.md for the persistent baseline comparison,
cost breakdown, release gates, and honest limitations.
Observed release gate (8 × 22K-character synthetic coding turns, 3
repetitions, forced activation): exact cross-turn recall passed 3/3 for both
arms; plugin raw retention and turn-1 expansion passed 3/3; mean provider
tokens fell 51.63% and mean surface nodes fell 63.90%. Estimated peak-price
cost rose 114.86%, so this is not advertised as a cost-saving plugin. See the
report for workload, pricing assumptions, variance, and raw artifact path.
npm test
npm run test:release
The smoke suite runs against real Session/surface machinery with a mocked
context and asserts:
- loader contract and schema defaults;
- deterministic digest ledger + fail-closed append packet;
context_steady_expand raw-span recall;- LLM digest authorizes packet replacement and raw-surface pruning while the
append-only log retains the raw span;
- a process-restart replay (fresh
Session seeded from the durable log)
reconstructs packet presence and coverage from surfaceOp +
sourceEventSeqs alone;
- batched LLM digests at the configured cadence, including fenced JSON-array
recovery;
- subsequent fallback turns replace only the previous packet;
- checkpoint rollup and stable→recent packet layer ordering;
- optional storage-domain persistence restores authoritative LLM digest
content and count after a fresh
Session replay.
A live profile check can be done with:
DSH_HOME=/tmp/dsh-context-steady-home \
dsh plugin --profile cs add /path/to/dsh-context-steady
DSH_HOME=/tmp/dsh-context-steady-home dsh --profile cs --dump-config
Real persistent E2E (headless + resume, opencode-go/deepseek-v4-flash)
A four-turn persistent run was driven through dsh-base + dsh-headless + dsh-context-steady with activationThresholdTokens: 0 (forced activation for
the mechanism test) and LLM digest enabled.
Each turn ran in a separate process: run 1 created the session, runs 2–4
resumed it via ctx.agents.resume. The persisted session.jsonl.zstd shows:
- raw log grew to 215 events (26 surface-producing), all retained;
- every
turn/end boundary was preceded by one packet replace whose
sourceEventSeqs cite the covered raw nodes;
- after 4 turns the derived surface is exactly 4 nodes
(
initial runtime context + latest packet), while surfaceTokens
held at ~3k and packet at ~480/3000 tokens;
context_steady_expand recovered the original turn-1 prompt verbatim from
the journal after pruning.
This is the DSH equivalent of San's acceptance shape: provider-bound context
stops growing with the raw transcript while the raw log stays append-only.
Known limitations and deferred work
- Authoritative digest persistence is optional, not universal. Standard
DSH web profiles mount
ctx.storageDomain, so successful LLM digest content
is restored across process restarts. Minimal/headless profiles without that
service still retain packet content and pruning coverage in the session log,
but historical digests rebuild as deterministic fallback.
- LLM digest runs at
agent/turn-stopping. DSH has no post-turn async hook
that is awaited before the next prompt. The plugin therefore batches four
settled turns by default and pays one synchronous side request at each
cadence boundary (bounded by digest.llm.timeoutMs). This keeps the next
packet race-free while avoiding one side request per turn.
- A batch can remain fallback. In the final three-repetition gate, one of
six side batches did not upgrade to authoritative. The fail-closed contract
held: raw evidence remained visible and every quality/expand gate passed.
Monitor
context_steady_status.authoritativeDigests when bounded-surface
behavior is an operational requirement.
- No recall layer. San's
retrieved_context layer depends on San Brain and
a memory backend; DSH has no equivalent seam yet. The packet template and
budget code already reserve the layer slot for a future DSH memory backend.
- No quality-gate burst mode / emergency stub. The first DSH port keeps the
steady-state path only; San's burst/hard-pressure and tool-stub degradation
need a DSH pressure event (e.g.
agent/request-error context overflow) and
are deferred.
- Deterministic digest quality is deliberately conservative. It extracts
files/tool evidence from structured tool events and patterns from assistant
text; enable
digest.llm for richer digests and pruning authorization.
