dsh-memory-guard

dsh plugin --profile web add dsh-memory-guard

dsh-memory-guard



Host memory and session-log guard for DeepSeek Harness (dsh).

It exists because a single DSH session log can grow far past the size the Host

can parse at once. A real case: a 7,913-line session reached **954 MB

decompressed / 177 MB on disk**, of which 98.5% was duplicated PTC dispatch

payloads, and opening it exhausted the Host heap. This plugin watches for that

before it happens, blocks the worst single calls, and can shrink existing logs

offline.

What it does

• Heap monitoring — samples process.memoryUsage() and

v8.getHeapStatistics() every 3 s (used / limit / ratio / RSS).

• Session-log accounting — scans $DSH_HOME/sessions every 15 s, reports

total bytes, file count, and the largest sessions.

• Runtime guard — synchronously rejects any tool call whose arguments are

estimated above maxToolArgBytes (default 2 MiB), with a message telling

the model to chunk the write or generate the file from a script.

• Persisted-payload alerts — watches session/event rows that were already

appended (tool/call, tool/ptc-dispatch*) and warns at 8 MiB, escalates at

32 MiB. Session logs warn at 50 MiB / critical at 200 MiB.

• Offline vacuum — /memguard vacuum previews; `/memguard vacuum <id>

confirm` rewrites a cold session log: oversized argument strings are

replaced with an identical placeholder in PTC start/final pairs, a verified

copy is produced, and the original is kept as .orig-<timestamp>.

• Header chip — MEM 42% · 24.6 MB in the session header, turning yellow /

red when the Host reports warn / critical.

• /memguard command and memguard tool — status report; the tool also

exposes vacuum-scan / vacuum-apply for agents.

Requirements

Item · Requirement

DSH · tested on 0.2.1-rc.2 (desktop and web profiles)

Node.js · >= 22.15 (uses the built-in zstd API; DSH bundles a suitable runtime)

Platform · developed and verified on Windows; code is path-agnostic, Linux/macOS are untested

Install

# desktop profile (DeepSeek Harness desktop app)
dsh plugin --profile desktop add dsh-memory-guard

# web / headless profile
dsh plugin --profile web add dsh-memory-guard

From the DSH UI: Settings → Plugins → Install and enter dsh-memory-guard.

Restart the app after the Host half is installed; the client chip needs a page

refresh.

Upgrade:

dsh plugin --profile desktop remove dsh-memory-guard
dsh plugin --profile desktop add dsh-memory-guard

Uninstall:

dsh plugin --profile desktop remove dsh-memory-guard

Header chip

The chip is registered in conversation.session.header.utilities. It polls the

same-origin endpoint /memory-guard/stats every 5 seconds. Hover it for heap,

RSS, session totals, the largest session, recent alerts and recent large

payloads.

If the chip does not appear after a DSH upgrade, the Host functionality still

works through /memguard and the memguard tool.

Commands

Command · Description

/memguard · Heap, session-log top 5, alerts, recent large payloads, current thresholds

/memguard vacuum · Dry-run: list cold sessions eligible for vacuum and the bytes they could save

/memguard vacuum <session-id> confirm · Rewrite that cold session log, verify it, keep .orig-<timestamp>

memguard tool actions: status, vacuum-scan, vacuum-apply (the last one

requires confirm: true and refuses live sessions).

Configuration

Edit the config block in the installed cordis.patch.yml (or the bundle row in

your profile composition), then restart DSH.

Key · Default · Meaning

guardEnabled · true · Set false to disable rejection while keeping monitoring

guardExemptTools · [] · Tool names that bypass the size guard, e.g. ["write"]

maxToolArgBytes · 2097152 (2 MiB) · Reject tool calls whose arguments estimate above this

noticeToolArgBytes · 524288 (512 KiB) · Only record, do not alert

heapWarnRatio / heapCriticalRatio · 0.75 / 0.90 · Host heap yellow / red

sessionLogWarnBytes / sessionLogCriticalBytes · 50 MiB / 200 MiB · Per-session log yellow / red

maxEventWarnBytes / maxEventCriticalBytes · 8 MiB / 32 MiB · Already-persisted event yellow / red

vacuumMinBytes · 10485760 (10 MiB) · Do not consider smaller logs for vacuum

notifyCooldownMs · 300000 · Per session + code alert cooldown

sampleIntervalMs / scanIntervalMs · 3000 / 15000 · Heap sampling / session scan interval

HTTP endpoints

Local, same-origin prefix /memory-guard:

Method · Path · Description

GET · /memory-guard/stats · Heap, session sizes, alerts, recent large payloads

POST · /memory-guard/limit · {"maxToolArgBytes": <int>} — temporary runtime override (resets on restart)

POST · /memory-guard/vacuum · Dry-run scan of cold sessions

There is no authentication beyond an Origin check. Do not expose the DSH web

port to untrusted networks.

Offline vacuum CLI

For a session log you already have on disk (for example a backup) you can run the

vacuum without installing DSH:

npx dsh-memory-guard-vacuum ./session.v4.jsonl.zstd scan
npx dsh-memory-guard-vacuum ./session.v4.jsonl.zstd write --out=./session.slim.jsonl.zstd

Always keep the source file. The CLI writes a new file, verifies line count,

JSON validity, header, and PTC pairing, and never edits the input.

Why the vacuum is conservative

DSH stores a session as concatenated zstd frames, and its reader requires the

first frame to contain exactly the header line. Writing the whole file as a

single frame makes the session unlistable. Th

…(truncated)