Preface¶

DSH session logs record events during a single run, but the raw events themselves don’t directly answer several practical questions: How long did this run take? How many turns and steps were there? Which tool calls failed? Were there repeated calls or repeated reads of the same file? Were verification commands like test, build, lint, or typecheck observed in the end?

This is where dsh-session-audit comes in. It outputs an execution analysis and audit report for a single DSH session, helping you see how the Agent actually worked.

What This Is¶

dsh-session-audit is a session execution analysis plugin for DeepSeek Harness (DSH), maintained by bwndlct.

The problem it solves is: consolidating the steps, tool calls, failures, repeated actions, token usage, and verification signals from a session into a readable report. Licensed under MIT.

Core Features¶

Session Metrics¶

The report includes session-level execution metrics:

• Duration
• Turns
• Steps
• Number of assistant messages
• Total tool calls
• Distribution by tool
• Success / failure breakdown

Token Usage¶

Token usage is collapsed into input / output / cache buckets by turn:step, semantically consistent with the official session-stats projection.

If the provider does not report token information, the report will show Unavailable and will not perform estimations.

Deterministic Audit Signals¶

dsh-session-audit uses purely rule-based logic to determine audit signals, without LLM scoring. Verified signals include:

• Consecutive failures
• Failure rate
• High-frequency tools
• Identical repeated calls
• Repeated reads of the same file

Verification Command Recognition¶

The plugin can identify test / build / lint / typecheck commands within shell tool calls and report the actually observed results.

Output Formats¶

The report supports three formats:

• text: default format
• Markdown
• JSON: with a stable schemaVersion

Current or Historical Sessions¶

By default, it audits the current in-memory session. You can also audit any persisted session by id, and list recent sessions.

Robustness¶

The following situations are handled safely and reported in the report’s data quality notes:

• Empty sessions
• Malformed events
• Future event types
• Orphaned results
• Trailing frames from crashes

Installation and Enablement¶

First, check the DSH version requirement:

@deepseek-ai/dsh 0.1.0-rc.6+

Next, install and enable it step by step.

1. Execute the installation command:

dsh plugin --profile web add dsh-session-audit

2. Edit ~/.dsh/profiles/web/package.json and add the package to dsh.profile.bundles. The install command above does not do this step.

For example:

{
  "dsh": {
    "profile": {
      "bundles": [
        "dsh-session-audit"
      ]
    }
  }
}

If there are already other bundle entries, keep the existing entries and add dsh-session-audit to the array.

3. Restart dsh:

dsh web

4. Verify the mount:

dsh --profile web --dump-config | grep -A2 session-audit

After the steps above, the plugin should be enabled in the current profile.

Typical Usage¶

Audit the Current Session¶

You can use natural language directly:

Audit the current session

You can also specify the format:

Audit the current session in markdown/json format

In interactive profiles, you can use the slash command:

/session-audit [text|markdown|json]

Where an empty argument defaults to the text format.

Audit a Historical Session¶

If you already know the session id, you can audit by id:

Audit session session-abc123

To list auditable persisted sessions, you can use:

List recent sessions

The corresponding slash command is:

/audit-list

Use Cases and Considerations¶

Who It’s For¶

If you need to review a DSH Agent run, check tool call failures, repeated actions, token usage, and verification command results, dsh-session-audit serves as a suitable local auditing tool.

Permissions and Security Checks¶

The plugin runs with the current dsh process permissions. It reads the local DSH home session logs and the in-memory live session registry.

Before installing, it is recommended to review the source code and license to ensure it meets your security requirements.

Local-Only Operation¶

dsh-session-audit performs only local analysis:

• Makes no network requests
• Does not call LLM APIs
• Sends no telemetry
• Collects no user data

Reports remain local, returned to you and the model as a tool result for reading, and are not written to disk.

Limitations¶

Verified limitations include:

• Verification command recognition is pattern-based; validators wrapped in special script names cannot be identified.
• Sub-agent sessions must be audited individually by id; no cross-session aggregation currently exists.
• Reasoning tokens are displayed when the provider reports them, but step-by-step values from some providers cannot be reconstructed.
• No time-series / context growth analysis is available currently.

Conclusion¶

The value of dsh-session-audit lies in turning a DSH session’s execution process into checkable information: steps, tool calls, failures, repeated actions, token usage, and verification signals all appear in the report.

Repository address:

https://github.com/bwndlct/dsh-session-audit

Search the plugin name on the directory page:

dsh-session-audit