dsh-agent-run-logger

Agent Run Logger

中文 | English

Agent Run Logger is a DeepSeek Harness plugin that writes compact local JSONL traces and serves a live, read-only viewer. It turns Session events into run, step, model, and tool timing records without replacing the canonical Session log.

Each Session writes to its own file under <session cwd>/.dsh/traces/ by default. Writers preserve source-event order inside one Session and drain independently across concurrent Sessions. The viewer incrementally indexes those files and presents Session lineage, a timing waterfall, event details, failures, token usage, gaps, and truncated values.

Content capture is off by default. Enabling it records prompts, replies, tool arguments, and tool results after credential-like values are redacted and before each value is truncated to its configured UTF-8 byte limit.

Install

Install the package directly from npm:

npm install dsh-agent-run-logger

Add the plugin to a DeepSeek Harness profile:

dsh plugin --profile trace-demo add dsh-agent-run-logger
dsh --profile trace-demo --dump-config
dsh --profile trace-demo

The bundle adds this row, which a profile patch may replace:

- id: agent-run-logger
  name: dsh-agent-run-logger
  config:
    outputDir: .dsh/traces
    includeContent: false
    maxContentBytes: 65536
    maxPendingBytes: 4194304
    redactSensitiveContent: true
    redactKeys: []

outputDir may be absolute or relative to each Session working directory. Byte limits are positive integers. redactKeys adds case-insensitive object-key names to the built-in credential list.

View traces

Run the viewer from the project whose .dsh/traces directory you want to inspect:

npx dsh-agent-run-logger view

The command binds to 127.0.0.1, selects a port beginning at 4318, and opens the dashboard. It does not accept remote connections.

Usage: dsh-agent-run-logger view [options]

  --trace-dir <path>       Trace directory (default: .dsh/traces)
  --port <number>          Preferred loopback port (default: 4318)
  --poll-ms <number>       Refresh interval (default: 750)
  --page-size <number>     Records returned per page (default: 500)
  --no-open                Print the URL without opening a browser
  --retention-days <days>  Delete old regular JSONL files at startup

Retention is disabled unless --retention-days is supplied. The viewer otherwise performs read-only filesystem access. See the viewer design for data, lifecycle, privacy, and HTTP behavior.

Record behavior

The trace schema version is 1. The plugin writes session.meta, run.start, run.end, step.start, step.end, llm.first_token, llm.end, tool.start, tool.end, and trace.gap. Every record includes sessionId, sourceSeq, and time.

The Session event path never waits for disk I/O. Each Session has a bounded 4 MiB queue by default. Queue overflow drops new trace records and a later trace.gap reports the affected source sequence range. A directory, write, or sync failure warns once and disables only that Session writer.

Limitations

• The logger observes only events committed after activation; it does not backfill canonical Session history.
• Subagent Sessions remain separate files. The viewer navigates parentSessionId relationships when both files are present, but does not merge their timelines.
• The viewer is local only and provides no authentication, remote exporter, trace upload, database, or OpenTelemetry integration.
• Content redaction reduces accidental credential storage but cannot classify every secret. Keep includeContent: false unless content is required.
• run.end and plugin disposal request a filesystem sync, but an operating-system or power failure may still lose an unsynced tail.
• Trace files are diagnostics, not a replacement for the canonical DeepSeek Harness Session log.