Preface

When running agent tasks with DeepSeek Harness (DSH), it’s often necessary to confirm some basic operational facts: what task was executed in this session, which model tier was used, which tools were called, how many failures occurred, how long the run took, and what the final status was.

If this information is only scattered throughout the session, it can be cumbersome to verify later. The approach of dsh-observation-journal is: after a session ends, write these operational facts into a human-readable journal and automatically maintain statistics blocks.

What This Is

dsh-observation-journal is a DSH pure observer plugin. The documentation clearly states its boundaries:

  • zero tools registered
  • zero LLM calls
  • zero agent involvement

It records operational facts, including:

  • task
  • model tier
  • tools
  • failures
  • duration
  • status

It does not inject records into the agent, nor does it participate in agent planning or memory recall.

Repository address:

https://github.com/Cavan-Ou/dsh-observation-journal

License:

MIT

The version and runtime environment declared in package.json are:

{
  "version": "0.1.0",
  "engines": {
    "node": ">=20"
  }
}

Core Features

Writing to Journal After Session Ends

After a session ends, the plugin writes the operational facts of a single session into a human-readable journal. The documentation states that the session card uses 10-column rows, with one session per row, without lossy merging.

Task titles are escaped:

  • Escape |
  • Escape newlines

At the same time, secrets redaction is performed based on a built-in secret table.

Automatically Maintaining Marker Blocks and Stats Blocks

Two types of blocks are maintained in the journal:

  • Journal blocks with markers
  • Auto-stats blocks

The documentation states that the marker section can preserve manually edited content. In other words, auto-written areas and manually edited areas can be separated.

Generating Append-Only Raw Sidecar

In addition to the journal, the plugin also generates an append-only raw sidecar. The path is:

obsFile + '.jsonl'

The raw sidecar contains:

  • todo planning trace (≤5)
  • Complete tool counts
  • Failed tools
  • Complete model id
  • Complete task description
  • Normalized task_hash

The documentation describes this as v2 material for LLM insight, and TTL-decoupled from the card.

Write Reliability

The reliability mechanisms listed in the documentation include:

  • Cross-process write locks
  • Stale lock reclaim
  • Dispose fallback flushes sessions without turn/end

Installation and Activation

First add the plugin, then run a DSH headless task, and finally view the journal. The installation command in the documentation uses placeholder parameters:

dsh plugin --profile headless add <repo-or-pkg>

You can also copy this repository as a local bundle for use.

Next, run a small task:

dsh --profile headless "run any small task"

Then view the default observation file:

cat ~/.dsh/observations.md

If journal rows and a stats section appear in the file, the plugin has successfully written the operational facts.

Configuration Options

The following configuration options are listed as optional in the documentation:

  • obsFile
  • maxRows
  • marker
  • redact
  • flushMs

Where:

  • obsFile: Journal file path; raw sidecar uses obsFile + '.jsonl'
  • marker: Journal block marker
  • redact: Redaction-related configuration; the documentation states that task titles will be redacted for secrets based on the built-in secret table

For the default values and detailed semantics of maxRows and flushMs, they are not provided in the verified documentation, so they will not be expanded here.

Environment Variables

Two environment variables are confirmed in the documentation:

  • OBS_FILE: Overrides obsFile
  • OBS_REPLAY=<session.jsonl>: Used to replay real session events, suitable for test/CI mode

Verification and Testing

The documentation states that verification has been performed using real session logs:

  • 14/14 replay tests
  • 5 real .zstd fixtures
  • One of which is a 2000+ event Pro long-synthesis session
  • 21-session full replay verification with human sections byte-identical

For local development, you can run:

node --check lib/index.js
node --test tests/test.mjs

Among these, node --test tests/test.mjs requires:

python3 + zstandard

Applicable Scenarios and Notes

Suitable for the following scenarios:

  • When you need to leave verifiable operational records for DSH sessions
  • When you need to view the task, model, tools, failures, and status of each session in a human-readable file
  • When you want to preserve manually edited areas while maintaining auto-generated statistics independently
  • When you need to replay real session events in test/CI

Boundary conditions to note:

  • It is not an agent memory plugin
  • Does not register tools
  • Does not call LLM
  • Does not inject into the agent
  • Does not participate in agent decision-making or recall

It is still recommended to check the source code and license before installation. The current documentation confirms the license is MIT, and package.json requires:

node >=20

Since the plugin runs with the current dsh process permissions, please confirm that you have a basic understanding of the plugin’s source, code, and write path before enabling it.

Conclusion

The value of dsh-observation-journal lies in extracting the operational facts of DSH sessions from temporary processes and writing them into a file with one session per row, which is human-editable, stat-stable, and replayable. It does not change agent behavior; it only leaves verifiable records.

This article’s documentation does not provide a community directory page URL. The GitHub repository address is:

https://github.com/Cavan-Ou/dsh-observation-journal