Preface

In agent runtimes like DeepSeek Harness (DSH), which feature a “everything is a plugin” architecture, models often directly modify the workspace via tools: writing files, editing files, deleting files, or even executing shell commands or initiating HTTP requests. Once these side effects occur, developers often lack a stable rollback entry point: files may be overwritten, deletion actions may not be immediately recoverable, and dangerous commands are difficult to trace retrospectively.

dsh-time-travel is a DSH plugin maintained by helibeiqi, under the MIT license. Its goal is specific: to establish a “pre-state snapshot → execution → compensation” chain for tool side effects, provide the ability to restore the workspace in reverse order by turn, and record dangerous operations that hit audit rules in an audit log.

One-Sentence Positioning

This is a reversible time travel and audit plugin for the DSH plugin system: when tools like fs.write, fs.delete, bash, and http.request generate side effects, the plugin attempts to record the pre-state and register compensation actions, then restores the workspace by turn via ctx.timeTravel.rewindTo(turnId), while simultaneously recording dangerous operations via a built-in audit rule engine.

Repository Info:

name: dsh-time-travel
owner: helibeiqi
license: MIT
package.json version: 0.2.0
engines: node >=18

Core Features

The following introduces several verifiable capabilities.

Listening to Tool Pipeline Events

The plugin listens to DSH’s tool pipeline events:

tools/pre-execute
tools/result

It establishes snapshot and compensation chains for four categories of tools:

fs.write
fs.delete
bash
http.request

Among them, file-based tools are more suitable for automatic compensation; shell and HTTP request tools are usually difficult to automatically reverse, so the plugin will follow the audit or manual handling path.

Rolling Back the Workspace by Turn

The plugin provides ctx.timeTravel.rewindTo(turnId). After calling, it executes compensation in reverse order by turn, attempting to restore the workspace to before the specified turn.

For example:

const report = await ctx.timeTravel.rewindTo('T3')

This line means: undo all compensable tool side effects from T3 onwards, and return a rollback report.

Providing a Set of Runtime APIs

After the plugin is mounted, the runtime context exposes ctx.timeTravel, including the following capabilities:

rewindTo
rewindAll
records
clear

Where:

  • rewindTo(turnId): rollback to before the specified turn;
  • rewindAll(): execute all compensable rollbacks;
  • records(sessionId): view tool side effect records;
  • clear(): clear records.

Example:

const records = ctx.timeTravel.records('session-abc123')

await ctx.timeTravel.rewindAll()

Built-in Audit Rule Engine

The plugin includes a built-in audit rule engine. When an operation hits rules such as dangerous shell, sensitive path writing, or non-compensable write operations, a line of JSON will be appended to the audit log.

The default audit log path is:

audit-log.jsonl

This path can be configured via audit.logPath.

The audit log uses JSON Lines format, where each record is a line of JSON, making it easy to integrate with logging systems or for manual review later.

Failure Isolation

Plugin side effects are registered via ctx.on(). These side effects are automatically revoked when the plugin is unmounted.

At the same time, one of the plugin’s design goals is that snapshot or audit failures should not affect the execution of the tools themselves. In other words, rollback and audit are auxiliary chains and should not block normal tool calls.

Installation and Enablement

Execute in the plugin project root directory:

dsh plugin --profile web add /absolute/path/to/dsh-time-travel

Here, /absolute/path/to/dsh-time-travel needs to be replaced with the absolute path of the local repository.

If installing via manual packaging, the equivalent path provided in the README is to first execute npm pack, then install the generated tgz package in the profile directory. The example uses:

npm pack

Then:

cd ~/.dsh/profiles/web
npm install /absolute/path/to/dsh-time-travel-0.1.0.tgz --no-save --no-audit --no-fund

After installation, you need to restart dsh web for the plugin to take effect. The default port is:

3080

Typical Usage

The following example demonstrates the programmatic usage after the plugin is mounted.

import { Context } from '@deepseek-ai/cordis'
import { apply } from 'dsh-time-travel'

// After the plugin is loaded by dsh, apply has executed; the following is just a programmatic usage example
const ctx: Context = /* root Context injected by dsh */

// After the model calls write to overwrite a.txt:
const report = await ctx.timeTravel.rewindTo('T3')
// Undo all tool side effects from T3 onwards

// View current records (can be filtered by session)
const records = ctx.timeTravel.records('session-abc123')

// Rollback all
await ctx.timeTravel.rewindAll()

The usage order can usually be understood as follows:

  1. After the plugin loads, ctx.timeTravel is available;
  2. During tool execution, the plugin records side effects and prepares compensation actions;
  3. When confirming that operations starting at a certain turn need to be rolled back, call rewindTo(turnId);
  4. If you need to view all pending rollbacks or recorded tool side effects, call records(sessionId);
  5. If you confirm a full rollback, call rewindAll().

Configuration Items

Verified configuration items include:

audit.logPath

Audit log output path, default value:

audit-log.jsonl

Log format is JSON Lines, parsed relative to the current working directory.

dryRun

Type is boolean. When dryRun is true, rewind only outputs a report without actually executing compensation.

Suitable for troubleshooting: first confirm which side effects will be rolled back and which will be skipped, then decide whether to actually execute compensation.

maxRecords

Used to control the maximum number of tool records retained in memory, default value:

10000

After exceeding the limit, the oldest records will be discarded. Audit log writing is not affected by this memory record limit.

Auto-Compensate vs. Audit-Only Tools

In the default mapping, file-based tools are easier to auto-compensate:

write / edit: can restore original content or delete newly created files
delete: can write back original content

While the following tools are usually not auto-compensable:

bash
pwsh
http.request

After these tools hit audit rules, the plugin primarily leaves an audit trail or prompts with manual, leaving the judgment to humans.

This is quite important in actual usage: do not interpret rewindTo as “all side effects can be rolled back with one click.” What it can restore is the compensable file system state; for actions like shell execution results or external HTTP requests that have left the local workspace, the plugin will not risk automatically guessing the rollback method.

Compatibility and Installation Notes

Plugin compatibility:

DSH 0.1.0-rc.6
cordis 4.x
schemastery 3.x

When installing, refer to the version of this repository; it is not recommended to directly install @latest.

The plugin runs under the permissions of the current dsh process, and will read tool calls and write to the audit log; in some scenarios, it will also attempt to restore files. Before installation, it is recommended to check the source code, dependencies, and MIT license to confirm it fits the permission boundaries of the current environment.

Use Cases

This plugin is suitable for the following scenarios:

  • Running tool-intensive agents in the dsh web profile, requiring quick restoration of workspace files;
  • Wanting to establish a rollback chain for file tools like write, edit, delete;
  • Needing to leave audit trails for dangerous shell, sensitive path writes, and non-compensable write operations;
  • Hoping to automatically revoke listeners after plugin unmount to avoid polluting the DSH tool pipeline.

It primarily handles the rollback and audit of workspace file side effects. Session-level message rollback or session event log replay is not within the scope of this plugin’s responsibility.

Conclusion

The value of dsh-time-travel lies in transforming tool side effects from “manual troubleshooting only after execution” to “recordable, rollbackable, and audit-able.” It provides the ability to rollback by turn via ctx.timeTravel, preserves audit trails for dangerous operations via the audit log, and registers side effects via ctx.on(), ensuring that these side effects can be automatically revoked when the plugin is unmounted.

Repository address:

https://github.com/helibeiqi/dsh-time-travel.git
```</think># Preface

In agent runtimes like DeepSeek Harness (DSH), which feature a "everything is a plugin" architecture, models often directly modify the workspace via tools: writing files, editing files, deleting files, or even executing shell commands or initiating HTTP requests. Once these side effects occur, developers often lack a stable rollback entry point: files may be overwritten, deletion actions may not be immediately recoverable, and dangerous commands are difficult to trace retrospectively.

`dsh-time-travel` is a DSH plugin maintained by `helibeiqi`, under the MIT license. Its goal is specific: to establish a "pre-state snapshot → execution → compensation" chain for tool side effects, provide the ability to restore the workspace in reverse order by turn, and record dangerous operations that hit audit rules in an audit log.

# One-Sentence Positioning

This is a reversible time travel and audit plugin for the DSH plugin system: when tools like `fs.write`, `fs.delete`, `bash`, and `http.request` generate side effects, the plugin attempts to record the pre-state and register compensation actions, then restores the workspace by turn via `ctx.timeTravel.rewindTo(turnId)`, while simultaneously recording dangerous operations via a built-in audit rule engine.

Repository Info:
```text
name: dsh-time-travel
owner: helibeiqi
license: MIT
package.json version: 0.2.0
engines: node >=18

Core Features

The following introduces several verifiable capabilities.

Listening to Tool Pipeline Events

The plugin listens to DSH’s tool pipeline events:

tools/pre-execute
tools/result

It establishes snapshot and compensation chains for four categories of tools:

fs.write
fs.delete
bash
http.request

Among them, file-based tools are more suitable for automatic compensation; shell and HTTP request tools are usually difficult to automatically reverse, so the plugin will follow the audit or manual handling path.

Rolling Back the Workspace by Turn

The plugin provides ctx.timeTravel.rewindTo(turnId). After calling, it executes compensation in reverse order by turn, attempting to restore the workspace to before the specified turn.

For example:

const report = await ctx.timeTravel.rewindTo('T3')

This line means: undo all compensable tool side effects from T3 onwards, and return a rollback report.

Providing a Set of Runtime APIs

After the plugin is mounted, the runtime context exposes ctx.timeTravel, including the following capabilities:

rewindTo
rewindAll
records
clear

Where:

  • rewindTo(turnId): rollback to before the specified turn;
  • rewindAll(): execute all compensable rollbacks;
  • records(sessionId): view tool side effect records;
  • clear(): clear records.

Example:

const records = ctx.timeTravel.records('session-abc123')

await ctx.timeTravel.rewindAll()

Built-in Audit Rule Engine

The plugin includes a built-in audit rule engine. When an operation hits rules such as dangerous shell, sensitive path writing, or non-compensable write operations, a line of JSON will be appended to the audit log.

The default audit log path is:

audit-log.jsonl

This path can be configured via audit.logPath.

The audit log uses JSON Lines format, where each record is a line of JSON, making it easy to integrate with logging systems or for manual review later.

Failure Isolation

Plugin side effects are registered via ctx.on(). These side effects are automatically revoked when the plugin is unmounted.

At the same time, one of the plugin’s design goals is that snapshot or audit failures should not affect the execution of the tools themselves. In other words, rollback and audit are auxiliary chains and should not block normal tool calls.

Installation and Enablement

Execute in the plugin project root directory:

dsh plugin --profile web add /absolute/path/to/dsh-time-travel

Here, /absolute/path/to/dsh-time-travel needs to be replaced with the absolute path of the local repository.

If installing via manual packaging, the equivalent path provided in the README is to first execute npm pack, then install the generated tgz package in the profile directory. The example uses:

npm pack

Then:

cd ~/.dsh/profiles/web
npm install /absolute/path/to/dsh-time-travel-0.1.0.tgz --no-save --no-audit --no-fund

After installation, you need to restart dsh web for the plugin to take effect. The default port is:

3080

Typical Usage

The following example demonstrates the programmatic usage after the plugin is mounted.

import { Context } from '@deepseek-ai/cordis'
import { apply } from 'dsh-time-travel'

// After the plugin is loaded by dsh, apply has executed; the following is just a programmatic usage example
const ctx: Context = /* root Context injected by dsh */

// After the model calls write to overwrite a.txt:
const report = await ctx.timeTravel.rewindTo('T3')
// Undo all tool side effects from T3 onwards

// View current records (can be filtered by session)
const records = ctx.timeTravel.records('session-abc123')

// Rollback all
await ctx.timeTravel.rewindAll()

The usage order can usually be understood as follows:

  1. After the plugin loads, ctx.timeTravel is available;
  2. During tool execution, the plugin records side effects and prepares compensation actions;
  3. When confirming that operations starting at a certain turn need to be rolled back, call rewindTo(turnId);
  4. If you need to view all pending rollbacks or recorded tool side effects, call records(sessionId);
  5. If you confirm a full rollback, call rewindAll().

Configuration Items

Verified configuration items include:

audit.logPath

Audit log output path, default value:

audit-log.jsonl

Log format is JSON Lines, parsed relative to the current working directory.

dryRun

Type is boolean. When dryRun is true, rewind only outputs a report without actually executing compensation.

Suitable for troubleshooting: first confirm which side effects will be rolled back and which will be skipped, then decide whether to actually execute compensation.

maxRecords

Used to control the maximum number of tool records retained in memory, default value:

10000

After exceeding the limit, the oldest records will be discarded. Audit log writing is not affected by this memory record limit.

Auto-Compensate vs. Audit-Only Tools

In the default mapping, file-based tools are easier to auto-compensate:

write / edit: can restore original content or delete newly created files
delete: can write back original content

While the following tools are usually not auto-compensable:

bash
pwsh
http.request

After these tools hit audit rules, the plugin primarily leaves an audit trail or prompts with manual, leaving the judgment to humans.

This is quite important in actual usage: do not interpret rewindTo as “all side effects can be rolled back with one click.” What it can restore is the compensable file system state; for actions like shell execution results or external HTTP requests that have left the local workspace, the plugin will not risk automatically guessing the rollback method.

Compatibility and Installation Notes

Plugin compatibility:

DSH 0.1.0-rc.6
cordis 4.x
schemastery 3.x

When installing, refer to the version of this repository; it is not recommended to directly install @latest.

The plugin runs under the permissions of the current dsh process, and will read tool calls and write to the audit log; in some scenarios, it will also attempt to restore files. Before installation, it is recommended to check the source code, dependencies, and MIT license to confirm it fits the permission boundaries of the current environment.

Use Cases

This plugin is suitable for the following scenarios:

  • Running tool-intensive agents in the dsh web profile, requiring quick restoration of workspace files;
  • Wanting to establish a rollback chain for file tools like write, edit, delete;
  • Needing to leave audit trails for dangerous shell, sensitive path writes, and non-compensable write operations;
  • Hoping to automatically revoke listeners after plugin unmount to avoid polluting the DSH tool pipeline.

It primarily handles the rollback and audit of workspace file side effects. Session-level message rollback or session event log replay is not within the scope of this plugin’s responsibility.

Conclusion

The value of dsh-time-travel lies in transforming tool side effects from “manual troubleshooting only after execution” to “recordable, rollbackable, and audit-able.” It provides the ability to rollback by turn via ctx.timeTravel, preserves audit trails for dangerous operations via the audit log, and registers side effects via ctx.on(), ensuring that these side effects can be automatically revoked when the plugin is unmounted.

Repository address:

https://github.com/helibeiqi/dsh-time-travel.git