dsh-loop-doctor

中文 | English

A self-diagnosing plugin family for DeepSeek Harness (dsh): deterministic detour detection over the harness's own SessionEvent log, human-reviewable optimization suggestions with replay verification, and accepted-fix sediment that grows over time — the harness reading its own log to tell the operator where it wasted work.

Observation before advice, advice before writes, writes behind human review.

The four packages

Package	Plane	What it does
@hubert-hwk/dsh-loop-doctor-detector	Observation	Folds the session/event firehose into DetourSignals (retry storms, tool misuse, context thrash, prompt bloat, effect churn) — pure deterministic rules, no LLM.
@hubert-hwk/dsh-loop-doctor-advisor	Advice	Maps a signal to a Suggestion via a fix-pattern table and replay-verifies it against the exact log (replay-verified vs simulated, never conflated).
@hubert-hwk/dsh-loop-doctor-apply	Write	The only durable decisions: a human-review ledger, a narrow auto-apply gate (off by default), and accepted-fix sediment growth with live reload.
@hubert-hwk/dsh-loop-doctor-tool	Model surface	The loop_doctor_diagnose tool: an agent diagnosing its own session on demand.

The self-optimization loop

session log ──▶ detector ──▶ signal ──▶ advisor ──▶ suggestion + replay
                                    │                        │
                                    │                        ▼
                                    │                 apply: ledger (human)
                                    │                        │
                                    ▼                        ▼
                       tool: loop_doctor_diagnose      accepted-fix sediment
                                                             │
                                    advisor reload ◀──────────┘
                                    (next match injects the validated fix)

Safety baseline

• Rules before LLM. Detection is deterministic; no model call is on the detection path.
• Confidence ceiling 0.9. A rule engine never claims certainty; expert-labeled patterns are marked unproven.
• Replay-verified ≠ simulated. Only behavior-modeling simulations measured on the exact log earn replay-verified; policy-cap arithmetic carries simulated and never drives auto-apply.
• Writes behind review. The family's only writes are its own ledger and sediment files; auto-apply is off by default and gated to replay-verified, ceiling-confidence fixes.
• Two-layer honesty. The keyless snapshot proves the pipeline in a real loop; the emergent proof (a real model naturally detouring) needs a keyed run and is documented as a recipe, never claimed as verified.

Get started

From this repository

pnpm install
pnpm run typecheck   # tsc over the whole family
pnpm test            # vitest — 140 tests across the four packages

The end-to-end keyless proof lives at examples/headless-agent/loop-doctor.cordis.snapshot.yml (three real detours, self-diagnosis twice, auto-apply + reload observed in-snapshot). It runs inside a full deepseek-harness checkout with the branch applied; see the Agent Note for the replay-fixture constraints.

Install from npm

pnpm add @hubert-hwk/dsh-loop-doctor-detector \
         @hubert-hwk/dsh-loop-doctor-advisor \
         @hubert-hwk/dsh-loop-doctor-apply \
         @hubert-hwk/dsh-loop-doctor-tool

Inside DeepSeek Harness

The four packages are designed to be mounted as plugins of a dsh host: wire the installed packages into your dsh plugin configuration. To run them from a source checkout of the harness instead, copy packages/loop-doctor/ into the harness workspace and rename the packages back to the upstream @hubert-hwk/dsh-loop-doctor-* names (or use the upstream feat/loop-doctor branch directly).

Relationship to upstream

This family was authored as an upstream contribution to deepseek-ai/deepseek-harness (branch feat/loop-doctor, based on the official master). The upstream project currently does not accept external pull requests (see their CONTRIBUTING.md), so this repository exists as the public, community-visible home of the work:

• Designed to upstream: layout and gates mirror the harness monorepo so the branch can be re-based onto a future upstream master when contributions reopen. The packages are published under the community scope @hubert-hwk/ because the @deepseek-ai/ npm scope is reserved for the official organization; inside the harness they carry the upstream names @hubert-hwk/dsh-loop-doctor-*.
• Agent Note included: .agents/notes/implemented/feature/2026-08-19-loop-doctor-self-diagnosis.md.

Community

• Discuss / upvote on the DeepSeek Harness GitHub Discussions (category: Show Your Plugins!).
• This repository carries the dsh-plugin topic so the harness community can discover it.

License

MIT