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