> ## Documentation Index
> Fetch the complete documentation index at: https://smithers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# PI Integration

> Use PI as a Smithers workflow CLI backend and understand how PI extensibility composes with Smithers declarative orchestration.

Smithers provides deterministic orchestration (workflow graph, approvals, retries, durable state). PI provides adaptive agent capabilities (providers, models, extensions, skills, prompt templates). Use both when you need deterministic execution with flexible agent behavior.

## Integration Modes

### 1) PI as Workflow Agent

```tsx theme={null}
import { PiAgent } from "smithers-orchestrator";

const pi = new PiAgent({
  provider: "openai",
  model: "gpt-5.5",
  mode: "text",
});

{/* outputs comes from createSmithers() */}
<Task id="implementation" output={outputs.implementation} agent={pi}>
  {`Implement feature X and explain tradeoffs.`}
</Task>
```

`PiAgent` supports all PI CLI flags: provider/model, tools, extensions, skills, prompt templates, themes, sessions. Text mode uses `--print` by default; JSON/RPC modes set `--mode` and omit `--print`.

PI sessions are first-class hijack targets. `bunx smithers-orchestrator hijack RUN_ID --target pi` reopens the PI session for local steering.

### 2) PI Server Client

Drive Smithers server APIs from a PI extension or Bun process via `@smithers-orchestrator/pi-plugin`:

```ts theme={null}
import { runWorkflow, approve, streamEvents } from "@smithers-orchestrator/pi-plugin";
```

`@smithers-orchestrator/pi-plugin` currently publishes TypeScript source entrypoints; run it with Bun or bundle it before using it from plain Node.

The older `smithers-orchestrator/pi-plugin` and `smithers-orchestrator/pi-extension` subpaths were removed; use the scoped package directly.

### 3) Hybrid: PI Extensibility + Smithers Orchestration

* Keep orchestration in Smithers (`<Sequence>`, `<Parallel>`, `<Branch>`, `<Loop>`).
* Run adaptive logic in PI tasks (extensions/skills/provider overrides).

Patterns:

1. PI skill-driven coding task inside a Smithers `<Task>`.
2. PI extension command that starts/resumes Smithers workflows via server API or `@smithers-orchestrator/pi-plugin`.
3. Smithers workflow output persisted to SQLite and consumed by later PI-assisted tasks.

## Hijacking PI Sessions

PI is a native-session hijack backend.

* Live run: Smithers watches PI's event stream, waits between blocking tool calls, then hands off the session.
* Finished/cancelled run: Smithers reopens the latest persisted PI session.
* Relaunch uses the stored session ID: `pi --session <id>`.
* Clean exit resumes the workflow automatically.

Session persistence:

* `PiAgent` defaults `noSession` to `true` for one-shot calls.
* For workflow hijack/resume/streaming, Smithers keeps session persistence enabled automatically.
* `mode: "json"` is not required for hijack support.

## Setup

1. Install PI CLI and add to `PATH`.
2. Configure PI credentials via env/config (prefer over CLI args for API keys).
3. Instantiate `PiAgent` with explicit options in workflows.
4. For server-driven workflows, use `@smithers-orchestrator/pi-plugin`.

```bash theme={null}
# Verify PI is installed
pi --version
```

## Design Guidance

| Use `PiAgent` tasks when                                | Use Smithers-native tasks when                            |
| ------------------------------------------------------- | --------------------------------------------------------- |
| You need PI capabilities inside deterministic workflows | You need strict reproducibility and narrow tool contracts |
| You want PI calls as auditable workflow steps           |                                                           |

## Limitations

Smithers does not provide a chat interface for PI. Chat UI integration is the responsibility of the host application using `@smithers-orchestrator/pi-plugin`.