DSH | dsh-logbook | See your plugins' log output at last (dsh silently drops warnings today)

[d3vmeh]

Project URL:
https://github.com/d3vmeh/dsh-logbook

npm:
https://www.npmjs.com/package/dsh-logbook

Introduction

While building my last plugin I found something surprising about DSH logging, and this plugin came out of it.

Every plugin logs through ctx.logger, but no shipped profile mounts a log sink (#2905, #1241, #4994). The only default destination is a 1000-record in-memory buffer. The surprise: that buffer 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 a logger default of 1, so a plugin can warn about a real problem and the warning goes nowhere at all, not even into memory. You can verify it in one minute:

import { Context } from '@deepseek-ai/cordis'
const ctx = new Context()
ctx.logger.warn('W')
console.log(ctx.logger.buffer.map(m => m.type))   // [] , the warn is gone

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

1. stderr, live: warnings and errors by default, so a healthy session stays silent; open it up per plugin (llm-gate: debug, hmr: off). Never stdout, which stays free for SDK/ACP protocol traffic.
2. /logs in the chat: the recent history, all levels, with --level, --name, --grep, --since, --limit filters.

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:11 llm-gate warn llm-gate: llamacpp session=059a680f queue full, rejecting

How it integrates with DSH

A host-side cordis plugin, one file. It registers a single ctx.logger.exporter with levels: { default: 3 } and a /logs command via ctx.commands. It filters by type name in its own code because a numeric threshold cannot express "warnings and errors only" in cordis's ordering (info sits below warn). The stderr writer attaches an error listener so a closed pipe (a dying tee) cannot crash the host, something a plain process.stderr.write in a try/catch does not protect against.

dsh plugin --profile web add dsh-logbook

Works with zero config; works headless.

What you should know

• One more upstream find from the review: cordis's exporter() disposer removes the most recently registered exporter instead of its own, so a plugin reload can detach another plugin's log sink. dsh-logbook keeps an internal flag so a stale copy of its exporter goes inert. I will write both cordis findings up separately.
• Related work, honestly compared: dsh-logger-panel is a web Settings page with rotating JSONL files, dsh-boot-doctor mounts a minimal console sink for boot problems, dsh-o11y-plugin exports to OpenTelemetry. dsh-logbook is the terminal-and-chat option: filters, stderr, no web dependency.
• Tested with 30 unit tests including a real-cordis regression for the dropped-warnings behaviour, a crash probe against a destroyed stderr pipe, and live runs through dsh headless and web.

This joins my local-model set (dsh-llm-gate #4995, dsh-context-budget #5078, dsh-fetch-timeouts #5124, dsh-turn-doctor #5135), though this one is for every plugin user, local model or not.

MIT License. Feedback welcome!

> Unofficial project, independently developed and maintained by community members.

[d3vmeh]

I wrote up the two cordis findings behind this plugin here: #5145