pi-dsh durable agent adapter

Experimental personal harness

Pi’s loop.
A durable spine.

pi-dsh keeps Pi’s small, readable coding-agent loop and four tools. It adds the part a long-running agent needs when the process dies: an fsynced event ledger, repair semantics, durable constraints, causal history, and human-approved runtime tools.

Run it locally Read the architecture

In plain English: the agent stays Pi; pi-dsh makes its work recoverable and explainable.

ONE TURN THROUGH PI-DSH durable
  1. 01
    Freeze the effective requestmodel, prompt, tools, constraints
  2. 02
    Run Pi’s agent loopprovider stream + read, bash, edit, write
  3. 03
    Checkpoint before side effectstool_started is durable before the body runs
  4. 04
    Append → fsync → acknowledgethe ledger advances only after durable write
  5. 05
    Resume without guessingrepair records what is known—and what is not

THE BOUNDARY

It is an adapter, not a replacement agent.

Pi still decides how a turn runs. pi-dsh owns what must survive and what can be inspected later.

KEPT FROM PI

The behavior you already understand

  • Pi’s runAgentLoop and provider stream
  • read, bash, edit, and write
  • Steering, follow-ups, abort, resume, and forks
  • Pi v4 as the only durable session vocabulary

ADDED BY PI-DSH

The failure semantics around the loop

  • Exact request snapshots before provider dispatch
  • Durable pre-tool checkpoints and interrupted-turn repair
  • Closed-prefix compaction with provenance
  • Durable constraints, causal query, and trace UI

DELIBERATELY NOT

A disguised dsh fork

  • No dsh code or Cordis vendored into the runtime
  • No profiles, bundles, HMR, or general plugin loader
  • No parallel transcript or second event vocabulary
  • No claim that approved JavaScript is safely sandboxed

WHY THE ADAPTER EXISTS

Failures become facts, not guesses.

The useful difference is not “more events.” It is what the runtime can prove after a crash, compaction, restart, or dynamic tool change.

01

Crash-consistent tools

A missing result is classified as NOT_STARTED or OUTCOME_UNKNOWN. Resume never invents success or blindly retries a side effect.

02

Context with provenance

Compaction shadows a closed, tool-balanced prefix. The summary cites what it replaced; the append-only history stays inspectable.

03

Rules that survive context loss

Constraints are add/revoke events folded into every request, independent of transcript text and preserved across compaction and restart.

04

Causal recall

Search cold sessions, open bounded event windows, trace direct relationships, and cite evidence as stable sessionId:seq:line locations.

05

Bounded modularity

A small per-session component graph supports awaited disposal and idle-only replacement—without making the engine itself a plugin framework.

06

Approved self-extension

The model can define a tool, but a human approves the exact revision and source hash. Activation is process-local and never restored automatically.

READ-ONLY TRAJECTORY

See the complete durable story.

Chat shows the model-visible projection. Trajectory shows requests, operations, tool checkpoints, usage, repairs, compaction, extensions, and causal links.

pi-dsh trajectory viewer showing a durable event ledger with session list, events, filters, and event details
The viewer never acquires the writer lock, repairs a file, or appends to a session.

RUN IT

One agent, one session file, one truthful ledger.

Requires Node.js 22.19+, npm, an OpenRouter-compatible key, and a model id.

Getting started → Testing guide → Self-extension trust model →
terminal
$ git clone --recurse-submodules \
  https://github.com/abhishekgahlot2/pi-dsh.git
$ cd pi-dsh && npm ci
$ cp .env.example .env

# Set PIDSH_MODEL and OPENROUTER_API_KEY
$ npm start

# In another terminal
$ npm run web

A containment boundary, not a security boundary.

Approved extension JavaScript is trusted local code. Worker threads and node:vm provide lifecycle cleanup and preemption; they do not make malicious code safe.