@dsh-external/dsh-tool-failure-journal
失败日志：每次异常退出的工具调用都会写入磁盘上的持久化 JSONL 日志，按错误特征进行聚类，并可由代理通过 `failure_journal` 工具读取。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:catsenior507/dsh-tool-failure-journal#8aa4fbfc243d4eee33510c2e51a6b5f55e65f640Tool Failure Journal 以 @dsh-external/dsh-tool-failure-journal 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
The same error, five times, is one row — written to disk before it scrolls away.
A DeepSeek Harness host plugin that appends every tool call that exits abnormally
to a durable JSONL journal, folds near-identical failures into signatures with
counts, and exposes the whole thing to the agent as one tool: failure_journal.
A coding agent does not only fail. It fails the same way over and over, and the evidence leaves the context window before anyone can see the pattern: the tool result is folded, compacted, or simply buried under the next four attempts.
The harness keeps a session log — but the session log is the model's context. It is rewritten, folded, and pruned. It cannot be the place a failure history lives.
So this plugin keeps a second record, outside the context window, in a format that outlives the process.
One listener on tools/result, which is the harness's own final notification for
a call — emitted after pre-policy, guards, the body, post-policy, and output
validation. That single hook covers:
One hook instead of four, and no polling.
Each record carries its own context, because a record has to stay useful after the session it came from is gone:
{"v":1,"at":"2026-09-11T00:31:07.412Z","sessionId":"session-c9a2…","callId":"call_00_…",
"turn":12,"step":3,"tool":"pwsh","aborted":false,"errorCode":"COMMAND_NOT_FOUND",
"message":"'lake' is not recognized as an error…","messageHead":"…","argsChars":41,
"args":"{\"command\":\"lake build\"}","content":"…","signature":"9f2c1ab73e04",
"tag":"failure","recurrence":3,"recurring":true,"firstSeenAt":"2026-09-11T00:28:51.003Z",
"remediation":["The binary is not on PATH for this shell; …"]}
Signatures. Every failure is hashed to a stable id built from the tool, the error code, and a normalized message — paths, timestamps, UUIDs, and long numbers replaced by placeholders. Forty near-identical failures become one row with a count, which is the unit a reader can act on.
regression: true. A tool that already succeeded earlier in the session and
fails afterwards is marked. That is the strongest signal in the journal: something
that worked has stopped working, and it points at whatever changed in between.
aborted is not failure. A withdrawn call is tagged separately and never
counted as a defect. Counting cancellations as failures would poison the
recurrence numbers that make the journal worth reading.
Shipped remediation. For the failure classes whose fix is unambiguous —
EDIT_NO_MATCH, EDIT_NOT_UNIQUE, COMMAND_NOT_FOUND, TIMEOUT,
PERMISSION_DENIED, SYNTAX, BAD_ARGS — the record carries the cause and the
next action that is actually different from the one that just failed.
| Action | What it answers |
|---|---|
stats | What keeps breaking, folded by signature. Start here. |
list | What failed most recently, newest first |
show | Every occurrence of one signature, by prefix |
sessions | Which journal files exist on disk, with sizes |
clear | Archive the live page and start fresh |
selftest | Prove the observer is attached and the directory is writable |
stats is the one that changes behaviour. "The same error five times" printed as
one row with count=5, recurring=true is a different instruction to a reader than
five separate stack traces.
The plugin is installed as a package into a dsh profile, the same way every
other dsh plugin is. dsh plugin forwards to pnpm inside the profile directory,
so any spec pnpm accepts works.
# from GitHub (the published form)
dsh plugin --profile web add github:catsenior507/dsh-tool-failure-journal
# a local checkout, while developing
dsh plugin --profile web add /absolute/path/to/dsh-tool-failure-journal
web is the shipped GUI profile; substitute headless, sdk, acp, or your own
profile name. On Windows, use forward slashes in a path.
Then restart the host so the profile recomposes, and confirm with:
failure_journal action=selftest
selftest reports whether the observer is attached and writes a probe file into
the journal directory to prove writability.
dist, no bundler, and no prepare script, so nothing runs on install.dependencies and peerDependencies are both empty; the
plugin needs only the harness it is loaded into. Cordis is provided by the host
at runtime.Node.js 20 or newer, because the harness itself requires it.
<DSH_HOME>/failure-journal/sessions/<sessionId>.jsonl, one file per session,
rotated by size (maxBytes, default 4 MiB, maxRotated generations kept).
Rotated generations are kept, not deleted: a session that loops on one error fifty times is the case worth reading afterwards, and truncating the file at the moment it becomes interesting would defeat the point.
dsh plugin add already inserted the plugin row. To change the defaults, edit
that row's config in the profile's cordis.patch.yml:
- insert:
- id: tool-failure-journal
name: '@dsh-external/dsh-tool-failure-journal'
config:
maxBytes: 4194304
clusterThreshold: 3
excludeTools: ['todo_write']
recordSuccesses: false
exposeTool: true
recordSuccesses: true also journals successful calls — useful for "what did the
command actually do". Note that success tracking for the regression signal
runs regardless; the flag only controls what reaches the disk.
selftest reports records written,
dropped, and rotated, so a journal that stopped working says so.npm test # 31 tests, including a real cordis mount and a real event
npm test needs @deepseek-ai/cordis resolvable, which comes with a dsh
installation. Running from a checkout rather than an installed package, point
node_modules at the profile's copy — on Windows a directory junction works.
The mount test registers a fake tools service on a real cordis Context, emits
the genuine tools/result event, and reads the journal file back through the
tool — because "inject was declared wrong so the observer never attached" is
exactly the failure a hand-rolled fake context cannot catch.
| File | Role |
|---|---|
lib/index.js | Cordis plugin: resolve config, attach, register |
lib/observer.js | The tools/result and session/event listeners |
lib/store.js | JSONL storage, rotation, archiving |
lib/signature.js | Failure identity, normalization, remediation catalog |
lib/tool.js | The failure_journal tool |
MIT