dsh-codex-observability

Readme

# dsh-observability

Two small plugins for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
that close the observability gap around external subagent runs. Background and
upstream proposal: [discussion #1493](https://github.com/deepseek-ai/deepseek-harness/discussions/1493).

## Packages

| Path | Package | What it does |
|---|---|---|
| (root) | `dsh-codex-observability` | Fingerprints product session roots (`~/.codex/sessions`, `~/.cursor/chats`, …) before and after tracked tool calls and writes an attribution envelope (`sessionRef`, `sessionStatus`) to a journal file. Pointers only — never prompt or transcript content. |
| `plugin-cursor/` | `dsh-tool-cursor` | A `cursor_delegate` tool that delegates a task to the official `cursor-agent` CLI (headless), ported from the opencodex `cursor.ts` reference. Read-only by default; `edit` proposes but never applies changes. |

Both are boot-tested in a real composition (isolated `DSH_HOME`, headless,
`--patch`, dsh 0.1.0-rc.6). Evidence:

```json
{"kind":"subagent-attribution","runId":"c091edac-…","provider":"bash","callId":"call_00_…",
 "error":"none","sessionRef":"/tmp/obs-test-root/new-artifact.jsonl",
 "sessionStatus":"attributed-single-artifact"}
```

```json
{"kind":"subagent-attribution","runId":"55f45e12-…","provider":"read","callId":"call_00_…",
 "error":"none","sessionRef":null,"sessionStatus":"not-observed"}
```

## Install

```sh
# from git (builds via the package's prepare script; pnpm >= 10 asks for
# allowBuilds permission the first time — copy the printed key into the
# profile's pnpm-workspace.yaml, then re-run)
dsh plugin --profile web add github:jeremy9682/dsh-observability

# or from a local checkout
dsh plugin --profile web add ~/Projects/dsh-observability

# cursor tool: local checkout form (the repo root is the observability package)
dsh plugin --profile web add ~/Projects/dsh-observability/plugin-cursor
```

Requires dsh 0.1.0-rc.6 and Node `^22.19 || >=24`.

Configure (defaults shown):

```yaml
- id: codex-observability
  name: dsh-codex-observability
  config:
    enabled: true
    roots: ['~/.codex/sessions', '~/.cursor/chats']
    tools: [subagent_codex, subagent_claude_code]
    journal: '~/.dsh/storages/codex-observability.jsonl'

- id: tool-cursor
  name: dsh-tool-cursor
  config:
    timeoutSeconds: 600
    defaultMode: ask
```

## Standalone utility (no DSH needed)

`bin/dsh-run-attributed.mjs` wraps any CLI with the same fingerprint +
envelope + three-tier timeout (first-event / idle / total):

```sh
node bin/dsh-run-attributed.mjs --provider codex --seat codex-landing \
  --root ~/.codex/sessions --first-event 60 --idle 240 --total 300 \
  -- codex exec --json "<task>"
```

## Known upstream blocker

The durable in-session-log pointer (instead of the file journal) waits on two
upstream items, raised in #1493: a downstream event-type registration surface,
and append-time `ignorable` control. `Session.append()` offers neither today;
`KNOWN_SESSION_EVENT_TYPES` excludes out-of-repo plugin events by construction.
The file journal is the working fallback until then.

## License

MIT.