Introduction¶

When developing agents in the DSH ecosystem, you often need to reuse the Pi coding agent but do not want it to take over the complete lifecycle management of the host application (ACRYL/Cordis). Direct integration can easily lead to tight coupling and make it difficult to dynamically replace or uninstall it.

Below is an introduction to pi-cordis. It packages the Pi coding agent as a Cordis runtime plugin and provides Pi SDK sessions through the host’s existing Cordis tree. This allows the ACRYL runtime to mount, remove, or replace Pi as needed without making Pi the owner of the application composition.

Plugin Positioning¶

• Name: pi-cordis
• Owner: cordisplugins
• Purpose: Provides the Pi coding agent as a Cordis runtime plugin.
• Core Value: Provides Pi SDK sessions through the host’s Cordis tree, decoupling Pi from the host lifecycle.

Core Features¶

This plugin provides the following capabilities:
* engine:pi
* agent-loop
* sessions
* tools

Installation and Enablement¶

When installing the dependency, you need to specify the version of Cordis.

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

To enable the plugin, use the stable Loader entry in the host configuration.

- id: pi-engine
  name: pi-cordis
  config:
    persistent: false

• persistent: false: Keeps Pi sessions in memory.
• persistent: true: Uses Pi’s session store in the configured working directory.

Typical Usage¶

The plugin provides the ctx.piEngine interface at runtime.

1. Open a session

    const sessionId = await ctx.piEngine.open()

2. Subscribe to events

    ctx.piEngine.subscribe(event => observe(event))

3. Send a prompt

    await ctx.piEngine.prompt('Inspect this project')

4. Abort a session

    await ctx.piEngine.abort()

Use Cases and Notes¶

This plugin is suitable for scenarios that require flexibly invoking Pi coding capabilities within the Cordis ecosystem.

Architecture Notes:
* Separation of Responsibilities: Pi owns the agent loop, model runtime, session operations, and event stream. Cordis owns the service lifecycle, subscriptions, cleanup, and replacement of the Pi engine.
* Dependency Inversion: Consumers use the service through ctx.piEngine and do not directly create or retain Pi SDK sessions.
* Fault Tolerance: Invalid configurations are rejected before plugin activation.

Runtime Environment: This plugin runs with the permissions of the current dsh process. Please ensure that you review the source code and license before installation.

Summary¶

pi-cordis embeds the Pi coding agent into the Cordis tree through a plugin approach, addressing lifecycle management issues in agent integration. It applies the dependency inversion principle, allowing Cordis to control the host environment and Pi to control its own logic. It is suitable for developers pursuing architectural decoupling.

Directory Page | GitHub Repository