dsh-deliberation

English | 简体中文

An unofficial DeepSeek Harness plugin for bounded, Primary-controlled deliberation and opt-in reasoning-masked review.

Status: experimental preview. The runtime and failure boundaries are tested. Paired benchmark data does not yet establish a correctness or cost benefit, so automatic review is disabled by default.

The plugin adds two related capabilities:

Capability	Trigger	What it does
deliberate tool	The Primary calls it	Runs 1–3 bounded alternative, audit, or masked-review children concurrently and returns compact JSON packets
automatic masked review	Optional agent/turn-stopping hook	Re-reads the current tool-bearing Turn without its recorded reasoning and publishes only decision-relevant updates

Children propose evidence, uncertainty, possible errors, and next checks. They never vote, select a winner, or replace the Primary.

Quick start

Requirements

• Node.js 22.19+ or 24+
• pnpm available on PATH (dsh plugin forwards installs to pnpm)
• a working DeepSeek Harness Web profile and model credentials

Check the prerequisites:

node --version
pnpm --version
npx @deepseek-ai/dsh --version

Install the published package

npx @deepseek-ai/dsh plugin --profile web add dsh-deliberation@0.1.0
npx @deepseek-ai/dsh --profile web --dump-config
npx @deepseek-ai/dsh web

Restart a running Web process after adding, removing, or updating the bundle. The dump should contain all three rows:

subagent-mid-fork-step-family-in-process
subagent-mid-fork-current-turn-in-process
tool-deliberation

Start Web from the directory that should become the Agent workspace.

Test a local checkout before publishing

git clone https://github.com/fly1989/dsh-deliberation.git
cd dsh-deliberation
npm ci
npm run release:check

# Latest DSH anchors `.` to this checkout before entering the profile directory.
npx @deepseek-ai/dsh plugin --profile web add .
npx @deepseek-ai/dsh --profile web --dump-config
npx @deepseek-ai/dsh web

The local install is a link, so rebuild after changing TypeScript and restart the runtime after changing bundle membership or compiled code:

npm run build

First manual test

The plugin registers a model-facing tool named deliberate. The model still chooses whether to call it, so use an explicit smoke prompt first:

Inspect this workspace and diagnose the failing check. Do not edit yet.
First use the read-only tools to collect one concrete observation. Then call
deliberate with one trajectory-audit branch and one masked-review branch over
the most recent completed Step. Use route=same; use capability=read-only for
the audit and reason-only for the masked review. After receiving the packets,
choose the cheapest discriminating check and continue normally.

Expected behavior:

1. The Primary performs at least one completed tool-bearing Step.
2. A generic deliberate tool card appears.
3. Separate child Sessions run; their transcripts do not enter the Primary context.
4. The tool result contains one compact packet per successful branch.
5. The Primary decides whether to use the packet.

Enable automatic masked review

Automatic review is deliberately opt-in. The included example is a complete DSH config-row replacement:

$reviewPatch = (Resolve-Path .\examples\auto-review.patch.yml).Path
npx @deepseek-ai/dsh --profile web --patch $reviewPatch --dump-config
npx @deepseek-ai/dsh --profile web --patch $reviewPatch

The example enables:

autoReview:
  enabled: true
  scope: tool-bearing-turns
  provider: mid-fork-current-turn
  route: same
  capability: read-only
  publish: updates-only
  timeoutMs: 300000

For a persistent deployment, copy the complete tool-deliberation entry from examples/auto-review.patch.yml into the profile's cordis.patch.yml. DSH patch rows replace the target row's entire config; they do not deep-merge nested keys. Ordinary profile patch edits hot-reload, but installing or removing the plugin bundle still requires a restart.

Use publish: observe-only first when collecting shadow-evaluation data. It runs and persists the child but never writes to the Primary inbox.

Roles

Role	History	Incumbent	Intended use
independent-alternative	fresh / spawn	hidden	Find one materially different mechanism or strategy
trajectory-audit	completed prefix / fork	visible	Falsify the current trajectory and localize the earliest questionable decision
masked-review	older native prefix + recent-Step snapshot	hidden	Re-read observable actions/results without the selected Steps' recorded reasoning

Manual masked-review requires recentSteps from 1 through maxRecentSteps (8 in the bundle). A Step is one completed model decision and every tool call/result caused by that response; parallel tool calls remain one Step. The active Step containing deliberate is excluded.

Automatic review uses window: current-turn: earlier completed Turns remain native history, while completed Steps in the stopping Turn become the reasoning-masked snapshot.

Result packet

Children return structured decision support, never hidden reasoning or a full transcript:

{
  "role": "masked-review",
  "status": "update",
  "items": [
    { "kind": "possible_error", "certainty": "likely", "content": "..." },
    { "kind": "unknown", "certainty": "uncertain", "content": "..." },
    { "kind": "suggestion", "certainty": "likely", "content": "..." }
  ]
}

• status: update or no_update
• kind: observation, conclusion, assumption, unknown, possible_error, or suggestion
• certainty: certain, likely, or uncertain

Certainty is the child's self-report, not fact verification. A real timeout, abort, child error, malformed packet, or role mismatch publishes no packet. A strict final-text JSON fallback is accepted only when the child Session proves that its Turn completed normally.

Configuration reference

Tool configuration

Key	Bundle value	Meaning
freshProvider	spawn	Provider used by independent-alternative
forkProvider	fork	Provider used by trajectory-audit
midForkProvider	mid-fork-step	Prefix of the recent-Step provider family
maxRecentSteps	8	Maximum K exposed to manual masked review
maxBranches	3	Maximum branches in one tool call
maxDepth	1	Absolute child delegation-depth ceiling
branchTimeoutMs	600000	Independent wall-clock timeout per manual branch
routes	same	Deployment-approved model routes visible to the Primary
capabilityProfiles	reason-only, read-only	Deployment-approved child tool boundaries
debug	false	Safe lifecycle breadcrumbs; never logs prompts or child content

Automatic review

Key	Values	Meaning
enabled	false / true	Mount or disable the stopping-boundary policy
scope	tool-bearing-turns / all-primary-turns	Eligible top-level Primary Turns
provider	default mid-fork-current-turn	Deployment-owned history projection
route	default same	Child provider/model route
capability	default read-only in bundle	Child tool ceiling
publish	updates-only / all / observe-only	Which packets may enter the Primary inbox
timeoutMs	300000	Automatic child wall-clock timeout

Projection provider

Key	Bundle value	Meaning
window	recent-steps or current-turn	Snapshot selection policy
mask	reasoning-only	Remove reasoning/replay state; action-only is an evaluation overlay
maxSnapshotChars	65536	Whole-snapshot text budget; overflow skips rather than truncates
maxSnapshotImages	20	Projected-suffix image ceiling

Routes and capabilities are allowlists, not registrations. The portable same route inherits the Primary model; it is not model-family independence. read-only requests read, grep, and glob, but a profile that does not expose those tools safely degrades toward reasoning-only execution.

Safety and runtime boundaries

• Children never receive deliberate; maxDepth prevents recursive branch growth.
• Manual siblings run concurrently and fail independently.
• Reasoning masking never edits the append-only Parent Session.
• In-process children share the workspace. Tool filtering is not filesystem, process, or credential isolation.
• The bundle provides no mutation-capable child profile and cannot roll back files, commands, databases, or network side effects.
• Image-bearing reviews start only when the effective child route explicitly supports image input; otherwise they skip before child creation.
• turn-stopping is a deterministic checkpoint, not a token-entropy detector.
• Same-model agreement is weak evidence. Children are proposal generators, not external fact verifiers.
• Every automatic attempt pays for a child LLM call; a published update also creates a Primary assimilation Step.

Troubleshooting

deliberate is missing

Restart Web after installing the bundle, then inspect:

npx @deepseek-ai/dsh plugin --profile web why dsh-deliberation
npx @deepseek-ai/dsh --profile web --dump-config

The model did not call deliberate

Installation makes the tool available; it does not force invocation. Use the explicit smoke prompt above. Automatic review is a separate runtime path and remains disabled unless configured.

Automatic review ran but the Primary showed no update

With updates-only, a valid no_update intentionally creates no parent notice or assimilation Step. Use publish: all for protocol debugging or observe-only for shadow evaluation.

Git installation is blocked by pnpm build approval

Git-hosted source dependencies run prepare, which pnpm 10 may block until the profile's pnpm-workspace.yaml allows the package build. Prefer the published npm package or follow the exact allowBuilds key printed by pnpm and rerun the install.

pnpm reports missing DSH peer dependencies

DSH profiles intentionally set autoInstallPeers: false. Out-of-tree plugins declare the Host APIs as peers, while the DSH launcher supplies the installation's single Cordis/DSH instances through its healed profile fallback. A peer warning during plugin add is therefore expected; do not install a second Cordis copy into the plugin. Confirm compatibility with --dump-config and an actual Web boot.

Development and release check

npm ci
npm run release:check

The release check runs type checking, all tests, the production build, and an npm tarball dry run. The package targets the DSH 0.1.1-rc.2 line; DeepSeek Harness is still a developer preview, so rerun the smoke test after every Harness upgrade.

Documentation

• Runtime flow
• Cordis / Harness / source mapping
• Research assumptions, papers, local experiments, and evaluation plan
• Reasoning-masked fork implementation notes
• Terminology
• Deferred and unsupported work

MIT. This project is not affiliated with or endorsed by DeepSeek.