Skip to content

feat(session-analysis): add DeepSeek Harness evidence adapter #94

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
phodal merged 1 commit into from
Aug 19, 2026
Merged

feat(session-analysis): add DeepSeek Harness evidence adapter #94

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 39 additions & 4 deletions docs/adapters/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
# Host Adapter Matrix

This is the single entry point for Claude Code, Codex, Qoder, Cursor, Qwen,
GitHub Copilot, Pi, Kimi Code, WorkBuddy, and Grok host boundaries. Do not
GitHub Copilot, Pi, Kimi Code, WorkBuddy, and Grok host boundaries, plus the
DeepSeek Harness (DSH) developer-preview session-only slice. Do not
create `docs/adapters/claude-code.md`, `docs/adapters/codex.md`,
`docs/adapters/qoder.md`, `docs/adapters/cursor.md`, `docs/adapters/qwen.md`,
`docs/adapters/copilot.md`, `docs/adapters/pi.md`,
Expand Down Expand Up @@ -43,6 +44,7 @@ project `.kimi-code/skills/`), then runs `/skill:better-harness`.
| Kimi Code | Analysis-capable source-local host | `.kimi-plugin/plugin.json` | `scripts/agent-customize/providers/kimi.mjs` | `scripts/session-analysis/platforms/kimi.mjs` | self-contained HTML + Markdown | `AGENTS.md` + `~/.kimi-code/skills` + project `.kimi-code/skills`/`.kimi/skills` + `~/.kimi-code/mcp.json` | `harness evidence-bundle --platform kimi` -> validated `html` render |
| WorkBuddy | Analysis-capable source-local host | none (skills install into `~/.workbuddy/skills`) | `scripts/agent-customize/providers/workbuddy.mjs` | `scripts/session-analysis/platforms/workbuddy.mjs` | self-contained HTML + Markdown | `~/.workbuddy` `AGENTS.md` + identity files + `.agents` + `AGENTS.md` | `session-analysis --platform workbuddy sources` -> validated `html` render |
| Grok | Analysis-capable source-local host | none (skills install into `~/.grok/skills`) | `scripts/agent-customize/providers/grok.mjs` | `scripts/session-analysis/platforms/grok.mjs` | self-contained HTML + Markdown | `~/.grok` + `.grok` + `.agents` + `AGENTS.md` | `session-analysis --platform grok sources` -> skill symlink -> validated `html` render |
| DeepSeek Harness (DSH) | Partial session-evidence adapter (developer preview) | none / unavailable | unavailable | `scripts/session-analysis/platforms/dsh.mjs`; `dsh-v1` for DSH `dsh-v0.1.0-rc.7` session format `0`, raw `.jsonl` and feature-detected `.jsonl.zstd` | unavailable; no report route | unavailable | read-only `node scripts/session-analysis.mjs sources --platform dsh --workspace <path> [--dsh-home <dir>]` or `node scripts/session-analysis.mjs facts --platform dsh --workspace <path> [--dsh-home <dir>]` |

## Read-only Plugin Lifecycle

Expand Down Expand Up @@ -79,10 +81,12 @@ Plans never execute and always preserve native surface differences:
| Pi CLI / CLI session | Persistent user/project install guidance and inventory; separate `pi -e` session-only activation whose update/remove operations are not applicable |
| WorkBuddy | `PLUGIN_LIFECYCLE_UNSUPPORTED`; adapter evidence remains available |

Kimi Code and Grok are absent from this table on purpose: neither host has a
Kimi Code, Grok, and DSH are absent from this table on purpose: none has a
validated native lifecycle contract yet, so lifecycle targets reject them with
`UNKNOWN_HOST` instead of borrowing another host's install route. Their adapter,
configured-asset, and session evidence remain available through the matrix above.
`UNKNOWN_HOST` instead of borrowing another host's install route. Kimi Code and
Grok retain their configured-asset and session evidence. DSH retains only its
partial session-evidence slice and has no lifecycle profile or native lifecycle
claim.

The lifecycle commands do not read raw session transcripts, contact a registry,
edit host settings, or register an `apply` path.
Expand Down Expand Up @@ -188,6 +192,33 @@ edit host settings, or register an `apply` path.
`signals.json`). The adapter honors `GROK_HOME`. Grok has no install shell in
this repository; skills install manually into `~/.grok/skills` (symlink is
enough for `/better-harness`).
- DeepSeek Harness has a developer-preview, JSONL-only session adapter at
`scripts/session-analysis/platforms/dsh.mjs`. Home resolution is strictly
`--dsh-home` over `DSH_HOME` over `~/.dsh`, and the only source root is
`<home>/sessions`. Discovery is read-only and accepts only the fixed nested
`session.jsonl` or `session.jsonl.zstd` layout. Workspace qualification uses
only the format-0 header's absolute `cwd`; the lossy project directory is not
workspace evidence. Better Harness reports adapter metadata `dsh-v1` and
supports native DSH session format `0` pinned to `dsh-v0.1.0-rc.7`. The host
is registered only for the `sessionAnalysis` capability.
Known-but-unsupported events and unknown ignorable events are explicitly
accounted for. Unknown required events, malformed records, identity drift,
and unsupported versions fail closed; an open trailing turn remains
incomplete. Bounded source distinctions are retained without copying
arbitrary plugin data or inferring plugin ownership, causality, or faults.
Compressed artifacts are concatenated independently checksummed Zstandard
frames and are scanned and decompressed one complete frame at a time. The
public API available in supported Node.js 22.20 and 24 runtimes is
feature-detected; where it is absent, including Node.js 23.0 through 23.7,
compressed evidence is unavailable while independent raw JSONL evidence
remains readable. There is no fallback dependency or shell.
This slice does not provide native DSH installation or invocation, live PTY
or process state, configured assets or Skills, plugin lifecycle, a shell,
manifest or package integration, report/output routing, README Quickstart or
Installation placement, SQLite or custom persistence, automatic
optimization, plugin fault or causality attribution, or artifact repair or
writes. See [Story #93](https://github.com/QoderAI/better-harness/issues/93)
and the [dated support specification](../specs/2026-08-18-93-deepseek-harness-session-evidence.md).

## Output Modes

Expand All @@ -201,6 +232,10 @@ Canonical templates live under `templates/reporting/`.
`findings.json`, `report.md`, and `report.html`.
- Markdown-only output has no visual companion.

DSH is intentionally absent from these output-mode host lists. Its
`sessionAnalysis` capability does not grant report routing, HTML, Canvas, or
Markdown output support.

## Split Triggers

Split a host into `docs/adapters/<host>.md` only when at least one condition is
Expand Down
51 changes: 47 additions & 4 deletions docs/docs/hosts/adapter-matrix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,12 @@ host-neutral.

## Support levels

Better Harness currently declares ten capability-level host adapters. Six
have verified public Quickstart paths. Pi, Kimi Code, WorkBuddy, and Grok are visible as adapter
Better Harness currently declares ten more complete capability-level host
adapters plus one DSH session-only partial slice. Six have verified public
Quickstart paths. Pi, Kimi Code, WorkBuddy, and Grok are visible as adapter
support because their installation and end-to-end evidence boundaries differ
from that six-host set. The [canonical adapter matrix](https://github.com/QoderAI/better-harness/blob/main/docs/adapters/README.md)
from that six-host set. DSH is visible only as a developer-preview session
evidence contract, not as a runnable report adapter. The [canonical adapter matrix](https://github.com/QoderAI/better-harness/blob/main/docs/adapters/README.md)
remains the complete capability-level source of truth.

## Supported host adapters
Expand All @@ -33,6 +35,7 @@ remains the complete capability-level source of truth.
| Kimi Code | Adapter support | Analysis-capable source-local host | `.kimi-plugin/plugin.json` | Workspace-matching Kimi wire transcripts | Self-contained HTML + Markdown |
| WorkBuddy | Adapter support | Analysis-capable source-local host | None; skills use WorkBuddy-owned paths | Workspace-matching WorkBuddy JSONL transcripts | Self-contained HTML + Markdown |
| Grok | Adapter support | Analysis-capable source-local host | None; skills use Grok-owned paths | Workspace-matching Grok session dirs (`updates.jsonl`) | Self-contained HTML + Markdown |
| DeepSeek Harness (DSH) | Session analysis only | Partial, developer-preview contract | None | DSH JSONL backend session format `0`: raw `.jsonl` and feature-detected `.jsonl.zstd` | Unavailable |

The `@qoder-ai/better-harness` npm package includes all seven plugin metadata
roots. Pi reuses install metadata in the existing `package.json`, so it does
Expand All @@ -58,7 +61,9 @@ contract is stale, persistent Pi operations without native evidence stay
unavailable, transient Pi update/remove are not applicable, and WorkBuddy
returns `PLUGIN_LIFECYCLE_UNSUPPORTED`. Kimi Code and Grok have no validated
native lifecycle contract yet, so lifecycle targets reject them with
`UNKNOWN_HOST` while their adapter evidence stays available. The shadow host
`UNKNOWN_HOST` while their adapter evidence stays available. DSH likewise has
no lifecycle profile: lifecycle targets reject it with `UNKNOWN_HOST`, and only
its partial session evidence remains available. The shadow host
profiles do not replace the canonical adapter matrix while ADR-0002 remains
proposed.

Expand All @@ -73,6 +78,9 @@ proposed.
(see the [sample report](pathname:///demo/better-harness-report/)).
- **Markdown-only** — no visual companion.

DSH is not an output-mode host. Session-analysis evidence does not grant HTML,
Canvas, Markdown, or any report route.

## Adapter support boundaries

### Pi {#pi}
Expand Down Expand Up @@ -110,6 +118,41 @@ npm-packaged host artifact; installation is a manual skill symlink into
outside the verified Quickstart set until a complete interactive report-loop
smoke is observed.

### DeepSeek Harness (DSH) {#deepseek-harness-dsh}

DSH coverage is a developer-preview, JSONL-only session slice, with Better
Harness adapter metadata `dsh-v1` and native session format `0` pinned to DSH
`dsh-v0.1.0-rc.7`. Home resolution is strictly `--dsh-home` over `DSH_HOME`
over `~/.dsh`; the only source root is `<home>/sessions`. The adapter reads the
fixed nested `session.jsonl` or `session.jsonl.zstd` layout without writing or
repairing artifacts, and it qualifies a workspace only from the header's
absolute `cwd`. DSH is registered only for the `sessionAnalysis` capability.

Compressed artifacts are concatenated independently checksummed Zstandard
frames and are validated and decompressed one complete frame at a time. The
public API available in supported Node.js 22.20 and 24 runtimes is
feature-detected. When it is unavailable, including Node.js 23.0 through 23.7,
compressed evidence is reported unavailable while independent raw JSONL
evidence remains readable; no fallback dependency is installed.
Known-but-unsupported and unknown ignorable events are accounted
for, while unknown required events, malformed data, identity drift, and
unsupported versions fail closed. Open trailing turns remain incomplete, and
the adapter does not infer plugin ownership, causality, or faults.

The implemented source-checkout smoke boundary is read-only:

```bash
node scripts/session-analysis.mjs sources --platform dsh --workspace <path> [--dsh-home <dir>]
```

This is not evidence of native DSH installation or invocation. DSH has no live
PTY/process integration, configured-asset or Skill discovery, plugin lifecycle,
shell, manifest, package integration, report/output route, README Quickstart or
Installation path, SQLite or custom persistence support, automatic
optimization, plugin-fault attribution, or artifact mutation/recovery. See the
[canonical source matrix](https://github.com/QoderAI/better-harness/blob/main/docs/adapters/README.md)
and [Story #93](https://github.com/QoderAI/better-harness/issues/93).

## Capability coverage

Capabilities differ per host on purpose: no host claims a capability without a
Expand Down
Loading