solpi-dsh: four efficiency mechanisms for long task sessions (an out-of-tree dsh-plugin)

[ryanxie113]

Hi all 👋 We've been running long multi-hour coding sessions on dsh and kept hitting
the same four frictions: edits needed a manual follow-up command, planning phases got
spilled previews instead of full code, ten-thousand-line test logs drowned the
context, and the session only ever grew.

solpi-dsh is our answer — a single npm
bundle that ships four independent mechanisms:

Mechanism	What it does
Action Fusion	edit/write + a follow-up shell command in one tool call (thenRun), result marked [then_run:succeeded/failed/skipped]
ObservationPack	exempt large tool outputs from spill truncation while the session is in plan mode
Evidence-Preserving Reducer	collapse huge diagnostic output into a ~1KB receipt that preserves quotable lines verbatim; full text stays on disk ($DSH_HOME/sol-pi/epr/)
Online Context Compact	token-economics gate decides when compacting pays for itself (writeTokens vs archiveTokens vs breakeven), then reuses compaction-basic's region machinery

Everything is off by default, each mechanism can be toggled independently, and they
compose naturally: spill-policy trims big outputs first, EPR collapses diagnostics,
and OCC's economic gate works on what's left — the session skeleton, not the raw flood.

It's measurable. A durable event log lands at $DSH_HOME/sol-pi/telemetry/events.jsonl
(fail-open, size-rotated). In our live-fire run — a red→green node:test fix loop —
14 events closed the loop across three ledgers: telemetry epoch=2 ↔ OCC state file
epoch=2/requestCount=6 ↔ six gate checks. One concrete sample: a 5255-byte failing
test log reduced to a 1480-byte receipt carrying 5 verbatim quotes; the model cited
the fatal line correctly afterwards.

Build notes that might help other plugin authors (things we learned the hard way):

1. Plugins are transpiled by the entry loader in CJS output format — top-level
   await in a plugin module fails the boot ("Top-level await is currently not
   supported"). Keep module init synchronous.
2. Bundle packages must watch their files whitelist: compaction-basic ships only
   lib/, so its "./src/*" export map entry is unreachable from npm installs.
   If you reach into another package's internals, ask upstream to make it public API.
3. dsh plugin add <dir> ≠ bare pnpm add <dir> — only the former reconciles
   dsh.profile.bundles. And it operates under $DSH_HOME, which may not be the
   directory you're looking at.
4. The SOLPI_DSH_ROOT-style escape hatch (env var → walk-up probe → fail-fast) has
   worked well as a general pattern for out-of-tree plugins that need to anchor
   against the running installation.

Three upstream proposals came out of this work (drafts here):

1. Expose cache read/write token metering through tokenMeter.measure (cache
   economics gates are currently config assumptions, not measurements);
2. Tag compaction boundaries with a purpose field so third-party and built-in
   compactions are distinguishable in forensics;
3. Make region-selection logic part of a package's public surface for safe reuse.

Known limits are documented honestly in the README (single model/provider validated,
dual-session concurrency tested only lightly). Feedback and issue reports welcome —
especially if you try it against different providers or larger windows.

---

[ryanxie113]