dsh-trajectory-governance

Agent trajectory governance & anomaly diagnosis for DeepSeek Harness (dsh).

Rebuilds the flat session/event log into a structured, multi-branch trajectory tree, keeps observation-layer snapshots, and runs three temporal anomaly strategies (loop deadlock / invalid retry / goal drift) with results mounted on tree nodes and surfaced in an independent GUI tab.

Zero kernel modification · consume-only event subscription · observation-layer snapshots (no control-plane rollback) · independent SQLite storage · never overwrites the official Trajectory view.

---

Why

The official Trajectory page is a flat raw-event log. For long-running agent tasks (dozens of turns, subagents, forks) you cannot see:

• which tool call belongs to which sub-task / subagent / fork branch,
• where the agent started drifting from the original goal,
• whether it is looping in place burning tokens (deadlock / invalid retry).

This plugin is an upper observation & reasoning layer: it consumes committed events and derives structure, snapshots, and diagnoses — it never steers, intercepts, or rolls back the agent. Both views coexist.

Aspect	Official Trajectory	dsh-trajectory-governance
View	flat raw event log	structured multi-branch trajectory tree
Lineage	none	parent/child + fork/subagent branches (derived implicitly)
Snapshots	no	observation-layer snapshots (nodeId + context hash + branchId)
Diagnosis	no	loop_deadlock / invalid_retry / goal_drift with confidence + suggestions
Storage	host storage	plugin-private SQLite (~/.dsh-trajectory-governance/)
Behavior	—	consume-only; never schedules, forks, or rewinds the agent

Architecture

dsh web profile
 ├─ @deepseek-ai/dsh-base (official core)
 └─ dsh-trajectory-governance (this bundle)
      │
      │  ctx.on('session/event' | 'session/created' | 'session/disposed'
      │         | 'subagent/start' | 'subagent/end')   ← emit-mode, post-commit, read-only
      ▼
 ┌─ ingest ───────────────┐   ┌─ tree ─────────────────┐
 │ normalize (scalars)    │──▶│ cross-session trajectory │
 │ sqlite (events/sessions)│   │ tree + branch attach    │
 └────────────────────────┘   └─────────────────────────┘
 ┌─ snapshot ─────────────┐   ┌─ diagnose ──────────────┐
 │ index-only snapshots    │   │ 3 strategies (async)    │
 │ LRU/TTL prune, branches │   │ results → anomalies DB  │
 └────────────────────────┘   └─────────────────────────┘
      │
      ▼
 ┌─ api (host) ────────────┐   ┌─ client (browser) ─────┐
 │ /trajectory-governance/  │◀──│ independent Tab:        │
 │ api/* (JSON, same-origin)│   │ conversation.view slot, │
 └─────────────────────────┘   │ id 'trajectory-…'       │
                               └─────────────────────────┘

Data flow: session/event (durable, post-commit) → normalized + persisted → tree/snapshot/diagnosis services → JSON API → the GUI tab. The diagnosis engine runs asynchronously on an interval (incremental watermark + tail overlap) and never blocks the agent loop.

Install

Requires dsh >= 0.1.0-rc.6. Two ways:

Bundle (published / git):

dsh plugin --profile web add github:dfycaly98931680/dsh-trajectory-governance#<commit-sha>

A git install fetches sources, so the package ships a prepare build; pnpm requires an explicit allow-list for it (add the printed key to the profile's pnpm-workspace.yaml, then re-run):

…