dsh-todo-freshness-guard

Readme

# DSH Todo Freshness Guard｜DSH 待办新鲜度守卫

English | [简体中文](README.zh-CN.md)

**Problem it solves:** During long agent turns, the model may keep calling tools without updating its unfinished `todo_write` list. The visible plan then stops matching the work actually being done.

**Most painful failure:** The agent is still active, but the user is looking at stale status—completed work still appears pending, new blockers are missing, and the next step is unclear. This removes progress visibility exactly when a long task needs it most.

**How it fixes it:** This out-of-tree [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Guard reminds the model to reconcile the complete Todo list, then blocks ordinary tools if the list remains stale. `todo_write` and the outer `run_code` recovery path always remain available.

**解决的问题：**Agent 在长任务中可能持续调用工具，却不更新未完成的 `todo_write` 列表，导致用户看到的计划与真实执行状态脱节。

**最痛的问题：**Agent 明明还在运行，用户看到的却是过期状态——已完成事项仍显示未完成，新阻塞没有记录，下一步也无法判断。任务越长，进度越不可信。

![DSH Todo Freshness Guard keeps long-running task progress visible](assets/progress-stays-visible.png)

## Behavior

After a successful `todo_write` contains unfinished items, the Guard counts non-bookkeeping tool attempts for that Session:

- At `reminderAfterCalls`, it injects one model-visible reminder to reconcile the complete todo list.
- After `blockAfterCalls`, it denies ordinary tools until another complete `todo_write` replaces the list.
- Native calls and Code Mode SDK sub-dispatches share the counter.
- `todo_write` always remains reachable.
- The outer `run_code` transport remains reachable so Code Mode can call `todo_write`.
- A completed or empty todo list disables enforcement.

This plugin fixes stale `todo_write` state. It does not replace or patch the filesystem Write tool.

## Compatibility

- DeepSeek Harness: `0.1.0-rc.6`
- Node.js: `^22.19.0 || >=24.0.0`
- Package status: community preview

## Install

Install the compatible DSH CLI, then add the release archive to the profile that should enforce the Guard:

```sh
npm install --global @deepseek-ai/dsh@0.1.0-rc.6
dsh plugin --profile web add https://github.com/lamost423/dsh-todo-freshness-guard/releases/download/v0.1.1/dsh-todo-freshness-guard-0.1.1.tgz
dsh web
```

To install from a checkout instead:

```sh
git clone https://github.com/lamost423/dsh-todo-freshness-guard.git
cd dsh-todo-freshness-guard
corepack enable
pnpm install --frozen-lockfile
pnpm build
dsh plugin --profile web add .
dsh web
```

The package contributes this default patch layer:

```yaml
- insert:
    - id: todo-freshness-guard
      name: dsh-todo-freshness-guard
      config:
        reminderAfterCalls: 5
        blockAfterCalls: 8
```

Profile and command-line patch layers applied after this bundle may replace the row configuration. `blockAfterCalls` must be an integer greater than `reminderAfterCalls`; both values must be positive integers.

Remove it with:

```sh
dsh plugin --profile web remove dsh-todo-freshness-guard
```

## Verify

```sh
pnpm check
pnpm pack --pack-destination /tmp
```

The test suite covers the native and Code Mode policies, concurrent resets, Loader composition, the packed Bundle contract, and an actual Web startup through official DSH `0.1.0-rc.6`.

## License

MIT. Derived portions retain the DeepSeek Harness license; see [`NOTICE`](NOTICE).