Introduction

When calling external sub-agents in DSH, you may encounter a common intermediate state: DSH has initiated tool calls such as subagent_codex or subagent_claude_code, and the external CLI has finished execution, but the DSH side may not be able to directly determine if this call corresponds to a session artifact from Codex or Cursor.

Below is an introduction to dsh-observability. It is maintained by jeremy9682, licensed under MIT, and aims to provide observability for external sub-agent execution in DeepSeek Harness.

What is it

The dsh-observability repository contains two small plugins:

  • Root directory package: dsh-codex-observability
  • Package under plugin-cursor/: dsh-tool-cursor

Please note the naming convention: the repository name and README use dsh-observability, while the package name in the root package.json is dsh-codex-observability. When writing configuration, checking logs, or troubleshooting dependencies, it is recommended to distinguish based on the actual package names.

Core Features

dsh-codex-observability

dsh-codex-observability is used to fingerprint product session roots before and after tracked tool calls, and writes the attribution envelope into a journal file.

Verified default targets include:

~/.codex/sessions
~/.cursor/chats

It writes attribution information such as sessionRef and sessionStatus. It only writes pointers here, not the content of prompts or transcripts.

dsh-tool-cursor

dsh-tool-cursor provides the cursor_delegate tool, used to delegate tasks to the official cursor-agent CLI in headless mode. This implementation is ported from the opencodex cursor.ts reference implementation.

The behavioral boundaries are:

  • Default read-only
  • edit mode only proposes changes, never applies them

Standalone Tool

The repository also provides a standalone tool:

bin/dsh-run-attributed.mjs

It can wrap any CLI with the same type of fingerprinting, envelope, and three-level timeouts:

  • first-event
  • idle
  • total

Installation and Enablement

Prerequisites

First, confirm that the runtime environment meets:

dsh 0.1.0-rc.6
Node ^22.19 || >=24

If using pnpm >= 10, the first execution of prepare or build will request the allowBuilds permission. You need to write the printed key to the profile’s pnpm-workspace.yaml and then run it again.

Installation from GitHub

Install the root package:

dsh plugin --profile web add github:jeremy9682/dsh-observability

Installation from Local Checkout

Install the root package:

dsh plugin --profile web add ~/Projects/dsh-observability

Install the cursor tool package:

dsh plugin --profile web add ~/Projects/dsh-observability/plugin-cursor

Default Configuration

Below are the default configuration items for the two plugins:

- id: codex-observability
  name: dsh-codex-observability
  config:
    enabled: true
    roots: ['~/.codex/sessions', '~/.cursor/chats']
    tools: [subagent_codex, subagent_claude_code]
    journal: '~/.dsh/storages/codex-observability.jsonl'

- id: tool-cursor
  name: dsh-tool-cursor
  config:
    timeoutSeconds: 600
    defaultMode: ask

The meaning of configuration items can be understood by their names:

  • roots: Product session root directories that need to be observed
  • tools: External sub-agent tools that need to be tracked
  • journal: The journal file where attribution pointers are written
  • timeoutSeconds: Timeout duration for cursor_delegate
  • defaultMode: Default mode for cursor_delegate

Typical Usage

Wrapping Codex CLI with the Standalone Tool

If you just want to add fingerprinting, envelope, and timeout control to a CLI call, you can use:

node bin/dsh-run-attributed.mjs --provider codex --seat codex-landing \
  --root ~/.codex/sessions --first-event 60 --idle 240 --total 300 \
  -- codex exec --json "<task>"

This step does the following: first specify the provider, seat, and session root directory to observe, then set the three-level timeouts, and finally pass the actual codex exec --json "<task>" command as the object to be wrapped.

Where to Find Observability Results

dsh-codex-observability writes attribution information to a journal file, with the default location being:

~/.dsh/storages/codex-observability.jsonl

The written content is pointer-level information, such as sessionRef and sessionStatus, and does not include prompt or transcript content.

Applicable Scenarios and Notes

Suitable for the following scenarios:

  • Calling external Codex, Cursor, and other CLI sub-agents from within DSH
  • Need to determine if a specific tool call produced observable product session files
  • Want to record only attribution pointers without persisting prompt or transcript content

Pre-use notes:

  1. The plugin runs with the permissions of the current DSH process; you should check the source code and license before installing.
  2. The license is MIT.
  3. dsh-tool-cursor is default read-only; edit mode only proposes changes, never applies them.
  4. dsh-codex-observability only writes pointers, not prompt or transcript content.
  5. Persisting in-session-log pointers is currently waiting for upstream support for two capabilities:
    - downstream event-type registration surface
    - append-time ignorable control

Before support is implemented, the current fallback is to use the file journal.
6. The root package package.json shows peerDependencies:

{
  "@deepseek-ai/cordis": "4.0.1",
  "@deepseek-ai/schemastery": "3.18.1"
}

Conclusion

The problem dsh-observability solves is specific: after DSH calls an external sub-agent, it completes the observation chain to determine if this call corresponds to a session artifact. It does not expand permission boundaries and does not record full conversation content; it mainly provides pointers, timeouts, and attribution status.

Related addresses:

  • Directory page: https://www.skillhub.cn/plugins/jeremy9682/dsh-observability
  • GitHub: https://github.com/jeremy9682/dsh-observability