widi

WIDI is a multi-agent runtime built on the AgentHarness module of Pi (pi-agent-core). Pi's harness owns single-agent concerns — model turns, the session tree, resources, tools, stream lifecycle. WIDI adds the runtime above it: agent lifecycle and orchestration, declarative profiles, session resume, model/auth registries, structured diagnostics, and an extension surface over all of it.

To be precise about what this repository is today: a runtime core with a documented architecture and a test suite, not yet a usable coding-agent product. What might still make it worth reading:

It is a real consumer of Pi's harness module. pi-coding-agent runs on its own AgentSession runtime and does not use AgentHarness; the harness is a clean module without a first-party product consumer so far. WIDI builds its entire runtime on it — session tree, resume, compaction, queue semantics — and sends the gaps it hits upstream as pull requests. Missing primitives are recorded in the Pi upstream roadmap; WIDI consumes Pi's JSONL session repository directly, including opaque header metadata used for recovery references. Since upstream began rewriting the harness, WIDI owns a frozen fork of it (docs/pi-fork.md) rather than tracking a moving target.

Agents are runtime entities, not processes. Pi's experimental orchestrator package supervises full coding-agent instances as RPC subprocesses. WIDI takes the other branch of that trade-off: multiple harnesses live in one process and share a tool registry, profile registry, session repo, and diagnostics channel, so agent lifecycle, availability, and recovery are observable inside the runtime rather than across process boundaries. This costs the isolation a process model gives you; the bet is that first-class orchestration semantics are worth it, and it is a bet — the collaboration tools that would prove it are still on the roadmap.

Decisions are recorded, including the failed ones. Milestones stay at planning level and only admit work with a concrete runtime goal (TODO.md). Settled boundaries live in canonical mechanism documents; detailed implementation history stays in Git. For example, command input is documented as an interaction-layer engine owned by the TUI rather than the orchestrator in runtime.md, and session/auth/config storage explicitly declares a single-process write assumption rather than shipping a half-locked file protocol.

At a glance

Three ways to get more than one agent out of the Pi codebase today:

	pi-coding-agent	pi orchestrator (experimental)	WIDI
Execution kernel	its own AgentSession runtime	one full coding-agent per instance	Pi AgentHarness
An "agent" is	the app session	an RPC subprocess	a runtime entity: profile + harness + session + status
Shared across agents	— (single agent)	nothing — per-process state	tool registry, profile registry, session repo, diagnostics channel
Failure surface	app/UI messages	process exit, RPC errors	structured diagnostics (profile.*, model.*, extension.*) with recoverability flags
Extension scope	single-agent app events (shipped, mature)	—	API v1: tool register/patch, resources/providers, scoped actions, observers/interceptors

Two pipelines that are already landed and tested. Input handling — an interaction-layer command engine owned by the TUI (the CLI entry routes straight into it), not an orchestrator protocol:

client input ──→ CommandEngine ──→ /command ──→ atomic orchestrator method ──→ event fanout
                    │                │
                    │                └─ /quit /exit ──→ ApplicationCommandHost ──→ app shutdown
                    │
                    └──→ inline expansion <prompt:…> <skill:…> ──→ promptAgent ──→ harness turn
                          └─ original input preserved as a session custom entry

Session resume — the reason WIDI needs header metadata on line 1 of the JSONL file:

sessions/*.jsonl ──→ list(): read line 1 only ──→ candidates (id, cwd, metadata.profile)
                                                        │
        profile registry ←── parse profile reference ←──┘
              │
              ├─ missing / disabled ──→ structured diagnostic, no harness created
              │
              └─ resolved ──→ session.buildContext() ──→ messages, model, thinking level,
                                                         active tools ──→ new AgentHarness

Status

The runtime foundation, seven core coding tools, command input, structured diagnostics, and extension API v1 are implemented. Current milestones are deliberately high-level: close the minimal multi-agent collaboration loop, move diagnostic construction toward domain runtimes, then improve core readability. See the Chinese milestones.

Documentation uses a stable language entry point; the current canonical set is Simplified Chinese. Code, identifiers, and diagnostics are English throughout. See apps/widi-pi/README.md for the module-by-module overview.

Workspace layout

• apps/widi-pi: the WIDI runtime core (active product code), exposing the widi-harness binary from dist/cli.js.
• packages/agent: @widi/agent-core, a fork of @earendil-works/pi-agent-core vendored at pi v0.83.0.

@earendil-works/pi-ai and @earendil-works/pi-tui are installed from the registry at exact versions; only the harness package is vendored. The upstream pi repository is not part of this repository — clone it into reference/pi (gitignored, never built) when you want to read upstream source.

The harness is forked because upstream is replacing it: harness-v2.md specifies a full rewrite of packages/agent/src/harness under a compatibility policy that preserves nothing but v3 JSONL session loading. docs/pi-fork.md records why the fork exists, its complete divergence from upstream, the invariants that keep it working, and the conditions for re-syncing. Gaps WIDI still needs from upstream are recorded in the upstream roadmap.

Development setup

Prerequisites: Node.js >= 22.19 and npm. Then:

npm install          # install workspace dependencies
npm run build        # build @widi/agent-core, then the app
npm run check        # Biome formatting/linting and TypeScript checks
npm run test         # run workspace tests

No network access and no code generation are needed to build: pi-ai ships its provider model catalogs inside the published tarball.

Upstream pi is optional and only useful for reading. Clone it when you want its source or history:

git clone https://github.com/earendil-works/pi.git reference/pi

Notes on the moving parts:

• npm run check covers both workspaces. It type-checks packages/agent/{src,test} and apps/widi-pi/{src,tests} through the root tsconfig.json. The app's own check script only sees the app.
• Biome formatting is partitioned. apps/** uses WIDI's defaults; packages/agent/** keeps upstream's settings so the vendored files stay byte-identical to upstream and cherry-picks stay cheap.
• The pi dependencies are pinned exactly, not by range, and typebox must match the version published pi-ai pins. Both constraints and their failure modes are in docs/pi-fork.md.

Benchmarks

Performance is tracked continuously with CodSpeed. The benchmarks use vitest bench through the @codspeed/vitest-plugin and live in apps/widi-pi/bench.

Run them locally:

npm --workspace apps/widi-pi exec -- vitest bench --run

On every push to main and every pull request, the CodSpeed GitHub Actions workflow runs the benchmarks in CPU simulation mode and reports performance changes.