dsh-logbook

Readme

# dsh-logbook

A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that makes `ctx.logger` output visible: a `/logs` command in the chat, and a stderr exporter that is on by default for warnings and errors.

## The problem it fixes

Every dsh plugin logs through `ctx.logger`, but no shipped profile mounts a log sink. The only default destination is a 1000-record in-memory buffer, and that buffer has a surprise: it silently drops `warn` and `debug` records. Cordis orders its levels error=0, info=1, warn=2, debug=3, and the buffer exporter falls back to each logger's default level of 1, so warnings never make it in. A plugin can warn about a real problem and there is no way to see it, live or after the fact (discussions #2905, #1241, #4994).

dsh-logbook registers one full-capture exporter (it asks cordis for everything, then filters itself) and gives you two views:

1. **stderr, live.** By default only warnings and errors, so a healthy session stays silent. Open it up per plugin with a config map. Never writes to stdout, which stays free for SDK and ACP protocol traffic.
2. **`/logs` in the chat.** The recent history (default ring of 2000 records, all levels), with filters:

```
/logs
/logs --level warn
/logs --name llm-gate --grep queue
/logs --since 10m --limit 100
```

```
logs: 3 of 41 records shown (ring 2000, buffer seeded 12)
14:01:59 llm-gate info llm-gate: llamacpp session=059a680f queued (depth 1)
14:02:03 llm-gate info llm-gate: llamacpp session=059a680f dispatched after 4012ms
14:02:11 llm-gate warn llm-gate: llamacpp session=059a680f queue full, rejecting
```

## Install

```
dsh plugin --profile web add dsh-logbook
```

That is enough. To tune it, add to your profile's `cordis.patch.yml`:

```yaml
- id: logs
  config:
    ring: 2000            # records kept for /logs
    stderr:
      enabled: true
      types:
        default: warn     # error | warn | info | debug | off
        llm-gate: debug   # everything from one plugin
        hmr: off          # silence one logger entirely
```

A value means "this type and anything more severe", in the order error, warn, info, debug. This deliberately differs from cordis's numeric levels, where info sits below warn and "warnings and errors only" cannot be expressed.

## What you should know

- The ring captures every level from the moment the plugin mounts, and seeds itself from the built-in buffer for anything earlier. Records from before the mount can only be error and info, because of the buffer behaviour described above.
- The stderr writer attaches an error listener so a closed pipe (for example a dying `tee`) cannot crash dsh, and it never throws into the logging path.
- Upstream note: cordis's `ctx.logger.exporter()` disposer currently removes the most recently registered exporter rather than its own, so any plugin reload can detach some other plugin's log sink. dsh-logbook keeps an internal flag so a stale copy of its exporter goes inert instead of double-reporting.
- Related work: [dsh-logger-panel](https://github.com/LingLambda/dsh-logger-panel) is a web Settings page with rotating JSONL files; [dsh-boot-doctor](https://github.com/Mide69/dsh-boot-doctor) mounts a minimal console sink aimed at boot problems; [dsh-o11y-plugin](https://github.com/fly3366/dsh-o11y-plugin) exports to OpenTelemetry. dsh-logbook is the terminal-and-chat option: filters, stderr, no web dependency, works headless.

## License

MIT