pi-cordis

Readme

# pi-cordis

`pi-cordis` packages the [Pi coding agent](https://pi.dev/) 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

```sh
pnpm add pi-cordis @deepseek-ai/cordis@4.0.1
```

## Compose

Use a stable Loader row in a host that already provides `loader`:

```yaml
- 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`.

```ts
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/`](./pi) as a shallow, one-commit Git submodule
from <https://github.com/earendil-works/pi>, pinned to upstream `main`.

```sh
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`](./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