pi-cordis
pi-cordis packages the Pi coding agent as a Cordis runtime
plugin. It provides a Pi SDK session through the host's existing Cordis tree,
so an ACRYL runtime can mount, remove, or replace Pi without making Pi the
owner of application composition.
Install
pnpm add pi-cordis @deepseek-ai/cordis@4.0.1
Compose
Use a stable Loader row in a host that already provides loader:
- id: pi-engine
name: pi-cordis
config:
persistent: false
persistent: false keeps the Pi session in memory. Set persistent: true to
use Pi's session storage in the configured working directory. ACRYL's future
engine-neutral session record remains the owner of cross-engine continuity.
Runtime API
The plugin provides ctx.piEngine.
const sessionId = await ctx.piEngine.open()
ctx.piEngine.subscribe(event => observe(event))
await ctx.piEngine.prompt('Inspect this project')
await ctx.piEngine.abort()
Pi owns its agent loop, model runtime, session operations, and event stream.
Cordis owns the Pi engine's service lifetime, subscriptions, cleanup, and
replacement in the surrounding host.
Engineering principles
pi-cordis keeps the Pi integration narrow and lifecycle-safe.
- Dependency inversion and separated interfaces. Consumers use
ctx.piEngine; they do not create or retain Pi SDK sessions directly.
- A capability seam for replacement. Pi becomes a provider entry that a
host can observe, remove, or replace without rewriting its consumers.
- Orthogonality over startup order. The plugin waits for
loader; it does
not assume a particular initialization sequence or create its own root.
- One owner for live resources. The service owns the active Pi session and
event subscription. Fiber disposal unsubscribes, aborts, and disposes them.
- YAGNI at the integration boundary. This package uses Pi's SDK rather than
recreating Pi's agent loop, model registry, extensions, or session manager.
- Information hiding. Pi SDK details stay behind a small service surface.
Pi's transitive packages, including Chord, are not used as an ACRYL
composition runtime; Cordis remains the lifecycle and dependency system.
- Fail fast and refactor safely. Invalid configuration is rejected before
activation. Tests cover missing Loader behavior, service mount/unmount, and
repeated activation without stale providers.
Source and provenance
The repository includes pi/ as a shallow, one-commit Git submodule
from https://github.com/earendil-works/pi, pinned to upstream main.
pnpm run upstream:sync # restore the recorded pin
pnpm run upstream:update # deliberately fetch upstream main and update the pin
The submodule is source provenance only. The published package uses the pinned
@earendil-works/pi-coding-agent SDK and does not load source directly from
the checkout. See provenance.json for the exact source
revision and dependency mapping.
pi-cordis is an engine provider for ACRYL's selectable runtime host. The
--engine pi CLI selection, canonical cross-engine session record, and
DSH+Pi hybrid engine are subsequent integration work.
pi-cordis
