Skip to content

pi-integration.mdx

Latest commit

 

History

History
90 lines (61 loc) · 3.45 KB

pi-integration.mdx

File metadata and controls

90 lines (61 loc) · 3.45 KB
title PI Integration
description 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

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:

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.
# 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.