DeepSeek Harness (DSH) provides official Session logs for auditing, but day-to-day development often requires more fine-grained metrics when debugging Agent runtime behavior, such as token usage and tool-call latency, or a visual waterfall chart. This plugin converts Session events into runtime trace records and generates local files that can be analyzed quickly with a viewer.

This is a DeepSeek Harness plugin for writing compact local JSONL trace files and providing a real-time, read-only viewer. It is maintained by bluefateludi and is designed to convert session events into runtime, step, model, and tool timing records without replacing the official Session logs.

Core Features

The plugin primarily provides the following capabilities:

  • Local JSONL tracing: Converts Session events into compact local JSONL trace files.
  • Real-time viewer: Provides a locally running, read-only web viewer.
  • Detailed logging: Records Agent runs, model steps, tool calls, timings, results, and token usage.
  • Visual presentation: Displays session lineage, waterfall charts, event details, failures, token usage, time gaps, and truncated values in the viewer.

Installation and Activation

First install the plugin package:

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 plugin adds the following configuration lines by default (which can be overridden via a Profile Patch):

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

outputDir can be an absolute path or a path relative to the Session working directory. redactKeys can be used to add custom sensitive field names (case-insensitive).

Typical Usage

After installation and configuration, start DeepSeek Harness to begin recording. To view the generated traces, run the viewer command in the project root directory (the directory containing .dsh/traces):

npx dsh-agent-run-logger view

The command binds to 127.0.0.1 by default, starting from port 4318, and opens the dashboard in a browser. It does not accept remote connections.

Common viewer options are:

--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 JSONL files at startup (default: do not delete)

Use Cases and Caveats

Use cases:
* Analyzing token usage in the Agent runtime.
* Debugging tool-call latency and results.
* Understanding event execution order with a visual waterfall chart.

Caveats:
* Content capture is disabled by default: To avoid leaking sensitive information, prompts, responses, tool arguments, and results are not recorded by default. If truly required, set includeContent: true, but the plugin redacts values containing credential-like patterns before logging and limits the UTF-8 byte length of each value.
* Only post-activation events are recorded: The plugin observes committed events after activation and does not backfill official Session history records.
* Subsession handling: Sub-Agent sessions generate separate files. When both files exist, the viewer can navigate via the parentSessionId relationship but does not merge their timelines.
* Viewer limitations: The viewer is local-access only and does not provide authentication, remote export, trace upload, database, or OpenTelemetry integration features.
* File nature: The trace files are diagnostic tools and do not replace the official DeepSeek Harness Session logs.
* Data safety: Operating-system or power failures can still cause loss of unsynchronized trailing data.

Summary

dsh-agent-run-logger provides a lightweight solution that lets developers convert DSH session data into local JSONL traces and use the built-in viewer to quickly pinpoint runtime issues. It is suitable for observing Agent execution details and performance metrics during development.