dsh-price-less

---

Read First: Dependencies & Experimental Status

⚠️ This plugin is experimental, unpublished, and needs a patched harness. It is not production software. It rewrites conversation history, it depends on a harness patch that is not in upstream, and its trigger behaviour is still being validated on real sessions. Read this section before you install it.

Hard dependencies

Experimental status — what is not guaranteed

• Field validation is thin. R1–R4 are implementation complete (code written, npm run gate green) — not validated at scale. On real-traffic replay, boundary compaction has fired once; the trigger chain is still being tuned, and discriminator task granularity was changed again on 2026-09-11 (v5). Expect the numbers in this README to move.
• Behaviour changes between commits. Task granularity, trigger thresholds and prompt contracts are under active revision. Every change lands as a ledger snapshot in docs/ledger-history.md; treat any figure here as a dated snapshot, never a promise.
• It edits your conversation history. Compaction rewrites message ranges through the harness replace API. Every path is guarded (fail-lazy: on any doubt, nothing is changed), but this remains the highest-risk thing a context plugin can do — back up ~/.dsh/sessions before first use.
• It is tied to a specific host build. The best-tested configuration is one local harness revision, not a released one. Upgrading the harness can break the plugin without warning — follow docs/14-upstream-upgrade.md.
• Savings are the goal, not a promise. No per-session cost benchmark is published, and auxiliary calls can cost more than they save if you enable everything.
• No support contract. Single maintainer, no release process, no compatibility matrix, no deprecation policy. MIT, no warranty.

---

Table of Contents

• Read First: Dependencies & Experimental Status
• About The Project
• How It Works
• Current Status
• Features
• Architecture
  • Layers at a Glance
  • Key Mechanisms & Field Fixes
• Getting Started
  • Prerequisites
  • Source Installation
• Usage
• Configuration
• Commands
• Session Events
• Documentation
• Roadmap
• Known Limitations
• Contributing
• License
• Acknowledgments

About The Project

Long AI-coding sessions get expensive — and drift. dsh-price-less is an unofficial context steward for DeepSeek Harness: it tracks what you are working on, keeps the context sent to the model lean, and never touches anything it isn't sure about — so every token you send earns its place.

• Explicit tasks: /task marks what you are working on; opening and closing tasks is always your call
• Project brief (project frame): /init asks a few questions and persists a project brief, so the model always knows what this project is
• Intent detection: decides whether each message continues the current task or starts a new one — keyword rules first, a light auxiliary model only when unsure
• Star button / prompt optimizer: one click folds the current intent into a deterministic execution package, previewed and confirmed by you
• Tool shear: slims tool output at write time, drops reads superseded by a later write, and flushes finished question/verification runs
• Compaction: folds closed tasks into a versioned archive with a hot tail, a 35%-of-window pressure path, and an overflow fuse
• Log-only & replayable: every plugin action leaves a replayable fact log; on any failure it changes nothing — your content is never lost

How It Works

One sentence: you just say what you are working on; the plugin keeps the context lean, and never touches anything it isn't sure about.

Four defence layers fire in order, from earliest to latest:

flowchart LR
    A["1. Write-time shaping<br/>before a tool result is booked"] --> B["2. Exchange-pair shear<br/>while a task is running"]
    B --> C["3. Compaction<br/>task closed / window at 35%"]
    C --> D["4. Restore<br/>on session restart"]

Three rules hold across all four layers:

• Failure means keep: if the criteria don't hold, parsing fails, or a call times out — no cut, no replace, no backfill.
• Cut points are fixed before a result is booked: no dependence on model replies, no behavioural signals (they break the cache and cost more).
• Out-of-band: plugin-internal flags never enter the model's view; the model only sees the tidied content.

To see what each action cost, read logs/context-economy.log; for the historical account, see docs/ledger-history.md.

Current Status

Important: automatic intent detection is off by default — enable it explicitly with discriminator.auto = true. Tool shear (shear.enabled) and both compaction paths default to on. All facts are log-only; any failure changes nothing.

Features

• Task boundaries: /task, /task close, /task — split continuous work into clearly bounded tasks
• Project brief: /init proposal → your confirmation → persisted as project brief v1 (project_frame)
• Intent detection: explicit instruction → zero-cost keyword rules → past verdicts → light-model fallback; anything unresolved stays untouched (fail-lazy)
• Prompt optimizer + star button: /optimize-prompt and the star button share one section; output = verbatim key facts plus a rewritten execution package, previewed before it is applied
• Tool shear: write-time shaping (process logs only), superseded reads, declaration-table repair, and run flush for finished question/verification runs
• Compaction: task-boundary folding into a versioned archive + hot tail; 35%-of-window pressure path; overflow fuse; restore on session start
• Workspace isolation: archive/prefix keys are scoped by the session workspace (header.cwd)
• Log-only & replayable: all context-economy/* events are log-only and ignorable; if the channel is missing, facts degrade to a KV mirror

Architecture

Source = docs/architecture.svg (Chinese version architecture.zh-CN.svg). Solid = implemented; dashed = pending validation. Each box is annotated with the field-fix ids that shaped it.

Layers at a Glance

Top to bottom is the data flow; bottom to top is the "who obeys whom" constraint:

src/
├─ platform/    # adapter layer — the plugin's only way to touch the harness
├─ core/        # pure logic — computation only, zero harness imports
├─ domains/     # orchestration — commands, intent detection, wiring
├─ config.ts    # config schema and defaults
├─ settings.ts  # settings UI wiring
└─ index.ts     # plugin entry
client/         # settings card and star-button UI
docs/           # design canon and work orders

Key Mechanisms & Field Fixes

Every item below is landed in code and recorded in the ledger; the diagram annotates them next to the mechanism they belong to:

Getting Started

Prerequisites

• Node.js with ESM support (Node 20+ recommended)
• A local DeepSeek Harness source checkout for building
• dsh CLI or dev_inject_plugin for loading the plugin

Host version: the peerDependencies range accepts both the patched 0.1.3-alpha.* line and prerelease 0.1.5-* hosts (>=0.1.3-alpha.1 <2 || >=0.1.5-alpha.0 <2). Two caveats, both verified on the harness source (2026-09-10):

• The ignorable write channel (SESSION_LOG_INTENT / LogIntent) is a local harness patch that has not reached upstream. On a vanilla host the fact track degrades to the KV mirror; the ledger semantics are unchanged (docs/12 §3).
• Upstream 0.1.5 renamed the replace surfaceOp endpoints ({start,end} → {startSeq,endSeq}) and bumped the session format to v3. src/platform/history.ts carries a compile-time anchor for exactly this drift: targeting such a host turns that anchor red on purpose. Do not silence it — change the one REPLACE_OP_KEYS constant next to it (docs/implement/REPAIR-2026-09-10.md §8).

Source Installation

This is currently a source-build / developer installation. There is no published npm package or tarball distribution yet.

# 1. Install dependencies
npm install --legacy-peer-deps --ignore-scripts --no-audit --no-fund --no-package-lock

# 2. Build from source (requires a local DSH checkout)
DSH_CHECKOUT=/path/to/deepseek-harness npm run build

# 3. Inject into a DSH instance
dev_inject_plugin /path/to/dsh-price-less

Planned distribution forms (not available yet):

• npm: dsh plugin add dsh-price-less
• tarball: dsh plugin add ./dsh-price-less-0.0.1.tgz

Usage

/init I am building a context management plugin
/init confirm

/task Design the command face
/task
/task close

/optimize-prompt

• /init is only a proposal; /init confirm persists the brief. Cancel any time with /init cancel.
• /task opens a new task; later messages are classified as continuation or new task by intent detection (when enabled); /task close marks the end, which is what triggers boundary compaction.
• /optimize-prompt or the star button opens a preview first: it applies only after you confirm, and your edited version is final.
• Any step can fail without changing anything — the worst case is that nothing happened.

Configuration

Configuration is grouped under shear (tool shear), compression (compaction) and discriminator (intent detection / auxiliary model). Use the GUI settings card, or write ~/.dsh/settings.yaml directly:

context-economy:
  shear:
    enabled: true
  compression:
    boundary: true
    pressure: true
    pressureRatio: 0.35      # pressure valve = ratio × main-model context window
    domainTokens: 125000     # assumed window when the main model declares none
    retainTokens: 10000      # hot-tail budget
    thresholdTokens: 100000  # absolute safety net
    archiveCapTokens: 10000  # archive hard cap (digest only)
  discriminator:
    auto: false              # intent detection is off by default
    # provider: deepseek-official
    # model: deepseek-v4-flash-vision-exp
    # reasoningEffort: high

The schema declares no default for provider/model, and the plugin ships no built-in default model either (2026-09-10: the previously hard-coded id was date-expired, and "the plugin guessing a model id" is itself a drift source). Left empty, auxiliary calls (intent detection, /init, star section, boundary compaction) follow the current session model (provider/model of the latest request). On the first message of a session there is no request record yet, so discrimination is skipped and an observable CE_JUDGE_NO_ROUTE fact is emitted (/init and the star button report "model not configured" instead); from the second message on it follows the session model automatically. Setting both values overrides all of this. Enabling discriminator.auto or using /init, the star button, or boundary compaction may invoke the auxiliary LLM. This can incur API costs and may send relevant prompt content to the configured provider.

Commands

Session Events

All custom events are log-only and carry ignorable: true.

Documentation

The design canon is maintained under docs/:

• 00 · System overview
• 01 · Architecture
• 02 · Discriminator
• 03 · Shear
• 04 · Compactor
• 05 · Constitution
• 06 · Cache
• 07 · Metrics
• 08 · Experiment protocol (sealed)
• 09 · State
• 10 · Wiring
• 11 · Structure
• 12 · Platform capabilities
• 13 · Harness plugin spec
• legacy · Retired designs
• TODO · Pending directions
• ledger-history · Snapshot archive

Inside docs/implement/archive/, the R1–R4 work orders and the remaining retired docs are local-only (excluded by .gitignore; the full text remains in git history). Two research records are tracked: the W2c output-shape evaluation and the N-series master.

Roadmap

Known Limitations

Short version below — the up-front warning is Read First: Dependencies & Experimental Status.

• Field validation is thin: R1–R4 are implementation-complete, not proven at scale. On real-traffic replay, boundary compaction has fired once; trigger tuning is ongoing and the discriminator's task granularity changed again on 2026-09-11.
• Not published: the package is still marked private and there is no official npm/tarball release.
• A rebuilt lib/ needs a DSH restart: mechanisms load on the next restart.
• Intent detection is opt-in: discriminator.auto defaults to false to avoid unexpected auxiliary LLM costs.
• Auxiliary LLM calls may cost money: enabling intent detection, using /init, the star button, or boundary compaction can send content to the configured provider.
• Ignorable-channel dependency: if the host harness does not include the local ignorable channel, plugin facts are mirrored to KV instead of being written as session events. Replay and observability may be reduced until the upstream channel is merged.
• Archive docs are mostly local-only: docs/implement/archive/ is gitignored by default (the full text stays in git history); only W2c-output-shape.md and 00-master-N-series.md are tracked.
• Local checkout required: building currently requires a local DeepSeek Harness source checkout and dev_inject_plugin.
• Non-affiliation: this project is not affiliated with DeepSeek.

Contributing

Contributions are welcome. Before submitting a change, ensure:

npm run gate

passes completely.

When changing documentation, please update both README.md and README.zh-CN.md together.

License

Distributed under the MIT License.

Acknowledgments