headless-json

dsh's built-in headless mode prints the final assistant text and exits 0 or 1, which is adequate for a quick smoke test but far too thin once you want a dsh session to be a first-class citizen in a CI pipeline. headless-json fills that gap: it mounts as a profile bundle on any dsh session and turns the entire conversation into a set of machine-readable artifacts. You get a transaction-level JSON report containing session metadata, per-event details, outcome, and statistics; an append-only NDJSON event stream you can tail while the run is still live; and a JUnit XML report that drops straight into GitLab CI, Jenkins, or Azure DevOps. Exit codes go beyond the usual 0/1 split into six semantic categories—success, error, timeout, blocked, aborted, and interrupted—so downstream scripts can branch on the exact failure mode.

Two design commitments stand out. First, privacy: every output passes through a redaction layer before hitting disk. Text is truncated, tool arguments can be hidden or summarized, secret-shaped strings are masked, and paths are relativized against the session working directory. All of these knobs are configurable at mount time and mutable mid-run via the set_options tool. Second, determinism: given the same session log and the same options, the produced bytes are identical, which makes diffing runs, auditing changes, and building regression checks straightforward. The plugin also never writes to stdout, so it composes cleanly with dsh's official headless runner, and every event listener is wrapped so a malformed event can never crash the loader tree or corrupt a report.

If you are wiring dsh into continuous integration as an automated agent, need a durable auditable artifact for every run, or want your CI dashboard to display agent executions the way it already displays test suites, headless-json is the missing piece. It is also a natural fit for multi-agent setups that need to collect referenced file paths into an artifact manifest, or for teams that must batch-redact session output before archiving it to long-term storage.