When developing agents in the DSH Web environment, debugging complex tool-call chains and reasoning processes often requires precise execution snapshots. The dsh-trace-repeat plugin records execution traces for any session in an atomic, versioned way, encapsulates each completed reasoning step or tool execution as an immutable version, and supports restoring historical versions based on git worktrees.

Features

Atomic Version Recording

The plugin subscribes to the host’s session/event and records three types of versions in order:
1. Reasoning version: corresponds to assistant/message and records the final message after it has been fully collected.
2. Tool version: corresponds to tool/call and tool/result, including the tool name, arguments, execution result, and error status.
3. User version: corresponds to regular user input.

Each version is an immutable JSON file, persisted using atomic write operations (tmp file + rename). The index file is also updated atomically to avoid data corruption.

Fully Reproducible Metadata

Each version includes complete contextual information for reproducing the execution environment at that time:
* Reasoning metadata: provider, model, reasoningEffort, maxTokens, usage, and full content.
* Tool metadata: tool name, callId, arguments, result, and isError.
* Session header information: workspace, cwd, preset, agentOptions.

Git Versioning and Recovery

Git versioning is enabled by default: the trace root directory is initialized as a dedicated git repository, and each version corresponds to one commit. The plugin supports materializing historical versions as git worktrees, located at .dsh-trace-worktrees/<session>-v<seq>.

Using the /trace resume command, execution can be restored from any historical version. The system automatically rebuilds a balanced context (truncated to the most recent completed reasoning version without pending tool calls) and opens a new session in the corresponding worktree to continue execution. The new session’s trace is generated independently.

Installation and Enabling

The plugin is automatically activated through the manifest and requires no additional configuration. After installation, restart the host process.

# 从 GitHub 安装
dsh plugin --profile web add github:p2coder/dsh-trace-repeat

After installation, refresh the DSH Web page in the browser to take effect.

Usage

After installation and restart, no manual enabling is required. Execution in any session is automatically recorded. Use the following commands to operate:

# 列出当前所有会话
/trace

# 查看指定会话的版本时间线及详情
/trace show <session> [vN]

# 从指定版本恢复执行
/trace resume <session> <vN>

Notes

  • Records final messages only: The plugin only records fully collected final messages and does not record incremental streaming output.
  • Recovery version restriction: Execution can only be restored at a “reasoning completed” version (i.e., one without pending tool calls). If you attempt to restore from a mid-turn version, the system reports an error and points to an earlier balanced version.
  • New independent session: Replaying or restoring does not modify the original session’s trace; it generates a new independent trace.
  • Workspace snapshot: Git materialization only covers trace files and does not include a snapshot of workspace files at that time.
  • Pause/resume markers: Pause/resume marker versions are written only on the “next session event after pause/resume.” If only pause and resume are performed with no other events in between, no marker version is generated.

Summary

dsh-trace-repeat provides a complete recording chain from low-level tool calls to high-level session state. Through immutable versions and git worktrees, developers can easily trace the execution context at any point in time and perform state rollback.

GitHub repository: https://github.com/p2coder/dsh-trace-repeat