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](docs/visualizer-design.md) 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.