dsh-contradictions-indicator

Readme

# Contradictions Indicator

A DeepSeek Harness plugin that scores the live conversation for internal contradictions and shows a 0–100 coherence badge in the session header.

0 means the conversation is riddled with contradictions. 100 means it is consistent. Click the badge for commentary, a manual Analyze Now button, and per-session controls.

## Install, update, and remove

Use the web profile:

```sh
dsh plugin --profile web add https://github.com/iimaguest/dsh-contradictions-indicator
```

```sh
dsh plugin --profile web update dsh-contradictions-indicator
```

```sh
dsh plugin --profile web remove dsh-contradictions-indicator
```

`dsh plugin --profile web` forwards to pnpm in that profile directory (`add` / `update` / `remove`). After add or update, restart `dsh web` so the host and client halves load. The badge appears in the conversation header utilities. Global defaults live under **Settings → Plugins → Contradictions**.

Requires DSH web with the settings and conversation UI packages that this plugin injects. Tested against dsh 0.1.1-rc.2 and 0.1.2-rc.1.

## What it does

- Watches main conversation `llm/stream` calls (skips compaction, session-title, and its own analysis calls).
- On demand, or on a turn interval, fires a parallel model call that reuses the conversation's provider, model, system prompt, tools, session id, and messages, then appends one analysis user message so the provider KV cache stays warm. Every other request field the session declared — reasoning effort, temperature, stop sequences, and the output budget — is forwarded verbatim too, so the request body is the main call plus exactly one message and no adapter default is substituted anywhere. The only field deliberately replaced is the abort signal. Nothing is ever removed from the request to steer the model's answer: dropping the tool list would invalidate the whole context cache.
- Parses `SCORE: <n>` and `ANALYSIS: <text>` from that response.
- Shows a colored header badge (green ≥80, yellow ≥50, red &lt;50) and an overlay with the commentary.
- Auto-analysis is **on by default** for new conversations (default interval 25 turns, editable 1–500). Turn it off globally in Settings → Plugins → Contradictions, or per conversation in the panel.
- Optional system-reminder steer using `{{score}}` and `{{commentary}}`. While a turn is running it is pushed into the conversation as a user message **the moment the analysis finishes** (`agent.steer()` on the live agent, landing at the next step boundary). An idle conversation is never woken just to carry a notice — the text stays pending and is handed over at that conversation's next step. If no live agent can be resolved (registry absent, session closed, inbox rejection), the same `agent/pre-step` fallback applies. Off entirely if you uncheck it.
- A response that ignores the required `SCORE:`/`ANALYSIS:` format, or that arrives as a bare tool call with no text at all, is retried once before the run is reported as failed. The retry re-sends the identical cached prefix, so it costs almost nothing — and the tool list is never dropped from the request, because removing it would invalidate the provider's context cache.
- The badge, panel, and settings tab are localized (English / 简体中文) through the shell's locale service, so **Settings → Language** applies to this plugin too, and every surface color/radius/shadow comes from the shell's `--dsw-*` theme tokens, so **Settings → Appearance** themes it like host UI.

### Settings: two planes, strictly separated

Global defaults (`autoEnabled`, interval, steer, both prompt texts) live in **Settings → Plugins → Contradictions** and persist via DSH settings (with a file fallback at `~/.dsh/contradictions-indicator.json`). Each conversation snapshots those defaults **once, at creation**; after that the conversation's panel owns its own copy. Editing settings therefore affects **only conversations started afterwards** — it never reaches into a live one — and adjusting one conversation never writes back to the defaults (the old `persist` flag on `/contradictions/auto` is ignored and gone).

## HTTP endpoints (local DSH web server)

The host half registers four exact paths on the DSH web server. They are meant for this plugin's client UI on the same origin:

| Method | Path | Purpose |
|---|---|---|
| GET | `/contradictions/state?sessionId=` | Current score, commentary, and session flags |
| POST | `/contradictions/auto?sessionId=` | Update auto-analysis, interval, steer, prompts |
| GET/POST | `/contradictions/defaults` | Read or write global defaults |
| POST | `/contradictions/trigger?sessionId=` | Run analysis now |

These routes are not covered by DSH's `/api` browser-trust fence, so the plugin
applies its own same-origin check (`Sec-Fetch-Site` / `Origin` vs `Host`) and
rejects cross-site requests before touching session state. All four also
reject bodies over 1&nbsp;MB and cap persisted prompt text length.

## Peer packages after a local clone

If you `link:` this directory into a profile, Node resolves imports from the real path and will not see the profile's `@deepseek-ai` packages. Re-run after a fresh clone (`node_modules/` is gitignored):

```sh
./link-peer-deps.sh
```

Only `dsh-settings` and `schemastery` are linked — those are the only bare
`import`s this plugin's host half actually executes in Node. `cordis` is a
type-only import (used solely by `lib/types/index.d.ts`) and `react` is
resolved through the DSH browser module table, not Node's `node_modules`, so
neither needs linking here.

All four `peerDependencies` are marked `optional` in `package.json`. That is
the correct *install* contract for a DSH host plugin — it tells pnpm these
packages are provided by the profile, not duplicated by this package — but it
does **not** mean the plugin runs without them. `lib/index.js` hard-imports
`@deepseek-ai/dsh-settings` and `@deepseek-ai/schemastery` and will fail to
load if the profile does not provide them.

The settings import is a namespace import on purpose, and the section is
installed through a small shim: `dsh-settings` ≤ 0.1.0-rc.8 exports
`installSettingsSection(ns, …)` with a validated namespace, while 0.1.1+
exposes the same hook as `settings.installSection(owner, ns, …)` with a plain
namespace string. A named import of the old symbol fails at module-link time
on the newer line, which would take the whole host half down with it.

Run the host-side regression tests with:

```sh
npm test
```

The `./client` export (`lib/client.js`) is a DSH `window.__ModuleLoader__`
lazy-load factory, not a standard ESM/CJS module. It only runs inside the DSH
browser runtime; `import … from 'dsh-contradictions-indicator/client'` will
not work outside of it.

## Layout

- `lib/index.js` — host plugin (Cordis `apply`)
- `lib/client.js` — web client (badge, overlay, settings tab)
- `cordis.patch.yml` — bundle insert for `dsh plugin add`
- `test/` — host-side delivery-timing regression tests (`npm test`)
- `plugin/` — working copy of the same host/client sources

## License

Apache License 2.0. See `LICENSE`.