Skip to content

The open-source app everyone uses to manage agents at work

Adding support for pi-local

Richard Anayaeb7f690ceb32
diff --git a/cli/package.json b/cli/package.json
index 4126d93b88..84edcb5813 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -38,6 +38,7 @@
"@paperclipai/adapter-codex-local": "workspace:*",
"@paperclipai/adapter-cursor-local": "workspace:*",
"@paperclipai/adapter-opencode-local": "workspace:*",
+ "@paperclipai/adapter-pi-local": "workspace:*",
"@paperclipai/adapter-openclaw": "workspace:*",
"@paperclipai/adapter-utils": "workspace:*",
"@paperclipai/db": "workspace:*",
diff --git a/cli/src/adapters/registry.ts b/cli/src/adapters/registry.ts
index 818bc6e6b7..66829b2cba 100644
--- a/cli/src/adapters/registry.ts
+++ b/cli/src/adapters/registry.ts
@@ -3,6 +3,7 @@ import { printClaudeStreamEvent } from "@paperclipai/adapter-claude-local/cli";
import { printCodexStreamEvent } from "@paperclipai/adapter-codex-local/cli";
import { printCursorStreamEvent } from "@paperclipai/adapter-cursor-local/cli";
import { printOpenCodeStreamEvent } from "@paperclipai/adapter-opencode-local/cli";
+import { printPiStreamEvent } from "@paperclipai/adapter-pi-local/cli";
import { printOpenClawStreamEvent } from "@paperclipai/adapter-openclaw/cli";
import { processCLIAdapter } from "./process/index.js";
import { httpCLIAdapter } from "./http/index.js";
@@ -22,6 +23,11 @@ const openCodeLocalCLIAdapter: CLIAdapterModule = {
formatStdoutEvent: printOpenCodeStreamEvent,
};
+const piLocalCLIAdapter: CLIAdapterModule = {
+ type: "pi_local",
+ formatStdoutEvent: printPiStreamEvent,
+};
+
const cursorLocalCLIAdapter: CLIAdapterModule = {
type: "cursor",
formatStdoutEvent: printCursorStreamEvent,
@@ -33,7 +39,7 @@ const openclawCLIAdapter: CLIAdapterModule = {
};
const adaptersByType = new Map<string, CLIAdapterModule>(
- [claudeLocalCLIAdapter, codexLocalCLIAdapter, openCodeLocalCLIAdapter, cursorLocalCLIAdapter, openclawCLIAdapter, processCLIAdapter, httpCLIAdapter].map((a) => [a.type, a]),
+ [claudeLocalCLIAdapter, codexLocalCLIAdapter, openCodeLocalCLIAdapter, piLocalCLIAdapter, cursorLocalCLIAdapter, openclawCLIAdapter, processCLIAdapter, httpCLIAdapter].map((a) => [a.type, a]),
);
export function getCLIAdapter(type: string): CLIAdapterModule {
diff --git a/packages/adapters/pi-local/package.json b/packages/adapters/pi-local/package.json
new file mode 100644
index 0000000000..1184c1ca0d
--- /dev/null
+++ b/packages/adapters/pi-local/package.json
@@ -0,0 +1,50 @@
+{
+ "name": "@paperclipai/adapter-pi-local",
+ "version": "0.1.0",
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts",
+ "./server": "./src/server/index.ts",
+ "./ui": "./src/ui/index.ts",
+ "./cli": "./src/cli/index.ts"
+ },
+ "publishConfig": {
+ "access": "public",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "import": "./dist/index.js"
+ },
+ "./server": {
+ "types": "./dist/server/index.d.ts",
+ "import": "./dist/server/index.js"
+ },
+ "./ui": {
+ "types": "./dist/ui/index.d.ts",
+ "import": "./dist/ui/index.js"
+ },
+ "./cli": {
+ "types": "./dist/cli/index.d.ts",
+ "import": "./dist/cli/index.js"
+ }
+ },
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts"
+ },
+ "files": [
+ "dist"
+ ],
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "typecheck": "tsc --noEmit"
+ },
+ "dependencies": {
+ "@paperclipai/adapter-utils": "workspace:*",
+ "picocolors": "^1.1.1"
+ },
+ "devDependencies": {
+ "@types/node": "^24.6.0",
+ "typescript": "^5.7.3"
+ }
+}
diff --git a/packages/adapters/pi-local/src/cli/format-event.ts b/packages/adapters/pi-local/src/cli/format-event.ts
new file mode 100644
index 0000000000..e93319a668
--- /dev/null
+++ b/packages/adapters/pi-local/src/cli/format-event.ts
@@ -0,0 +1,107 @@
+import pc from "picocolors";
+
+function safeJsonParse(text: string): unknown {
+ try {
+ return JSON.parse(text);
+ } catch {
+ return null;
+ }
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+ return value as Record<string, unknown>;
+}
+
+function asString(value: unknown, fallback = ""): string {
+ return typeof value === "string" ? value : fallback;
+}
+
+function extractTextContent(content: string | Array<{ type: string; text?: string }>): string {
+ if (typeof content === "string") return content;
+ if (!Array.isArray(content)) return "";
+ return content
+ .filter((c) => c.type === "text" && c.text)
+ .map((c) => c.text!)
+ .join("");
+}
+
+export function printPiStreamEvent(raw: string, _debug: boolean): void {
+ const line = raw.trim();
+ if (!line) return;
+
+ const parsed = asRecord(safeJsonParse(line));
+ if (!parsed) {
+ console.log(line);
+ return;
+ }
+
+ const type = asString(parsed.type);
+
+ if (type === "agent_start") {
+ console.log(pc.blue("Pi agent started"));
+ return;
+ }
+
+ if (type === "agent_end") {
+ console.log(pc.blue("Pi agent finished"));
+ return;
+ }
+
+ if (type === "turn_start") {
+ console.log(pc.blue("Turn started"));
+ return;
+ }
+
+ if (type === "turn_end") {
+ const message = asRecord(parsed.message);
+ if (message) {
+ const content = message.content as string | Array<{ type: string; text?: string }>;
+ const text = extractTextContent(content);
+ if (text) {
+ console.log(pc.green(`assistant: ${text}`));
+ }
+ }
+ return;
+ }
+
+ if (type === "message_update") {
+ const assistantEvent = asRecord(parsed.assistantMessageEvent);
+ if (assistantEvent) {
+ const msgType = asString(assistantEvent.type);
+ if (msgType === "text_delta") {
+ const delta = asString(assistantEvent.delta);
+ if (delta) {
+ console.log(pc.green(delta));
+ }
+ }
+ }
+ return;
+ }
+
+ if (type === "tool_execution_start") {
+ const toolName = asString(parsed.toolName);
+ const args = parsed.args;
+ console.log(pc.yellow(`tool_start: ${toolName}`));
+ if (args !== undefined) {
+ try {
+ console.log(pc.gray(JSON.stringify(args, null, 2)));
+ } catch {
+ console.log(pc.gray(String(args)));
+ }
+ }
+ return;
+ }
+
+ if (type === "tool_execution_end") {
+ const result = parsed.result;
+ const isError = parsed.isError === true;
+ const output = typeof result === "string" ? result : JSON.stringify(result);
+ if (output) {
+ console.log((isError ? pc.red : pc.gray)(output));
+ }
+ return;
+ }
+
+ console.log(line);
+}
diff --git a/packages/adapters/pi-local/src/cli/index.ts b/packages/adapters/pi-local/src/cli/index.ts
new file mode 100644
index 0000000000..94d5961a8d
--- /dev/null
+++ b/packages/adapters/pi-local/src/cli/index.ts
@@ -0,0 +1 @@
+export { printPiStreamEvent } from "./format-event.js";
diff --git a/packages/adapters/pi-local/src/index.ts b/packages/adapters/pi-local/src/index.ts
new file mode 100644
index 0000000000..3794426f0a
--- /dev/null
+++ b/packages/adapters/pi-local/src/index.ts
@@ -0,0 +1,40 @@
+export const type = "pi_local";
+export const label = "Pi (local)";
+
+export const models: Array<{ id: string; label: string }> = [];
+
+export const agentConfigurationDoc = `# pi_local agent configuration
+
+Adapter: pi_local
+
+Use when:
+- You want Paperclip to run Pi (the AI coding agent) locally as the agent runtime
+- You want provider/model routing in Pi format (--provider <name> --model <id>)
+- You want Pi session resume across heartbeats via --session
+- You need Pi's tool set (read, bash, edit, write, grep, find, ls)
+
+Don't use when:
+- You need webhook-style external invocation (use openclaw or http)
+- You only need one-shot shell commands (use process)
+- Pi CLI is not installed on the machine
+
+Core fields:
+- cwd (string, optional): default absolute working directory fallback for the agent process (created if missing when possible)
+- instructionsFilePath (string, optional): absolute path to a markdown instructions file appended to system prompt via --append-system-prompt
+- promptTemplate (string, optional): user prompt template passed via -p flag
+- model (string, required): Pi model id in provider/model format (for example xai/grok-4)
+- thinking (string, optional): thinking level (off, minimal, low, medium, high, xhigh)
+- command (string, optional): defaults to "pi"
+- env (object, optional): KEY=VALUE environment variables
+
+Operational fields:
+- timeoutSec (number, optional): run timeout in seconds
+- graceSec (number, optional): SIGTERM grace period in seconds
+
+Notes:
+- Pi supports multiple providers and models. Use \`pi --list-models\` to list available options.
+- Paperclip requires an explicit \`model\` value for \`pi_local\` agents.
+- Sessions are stored in ~/.pi/paperclips/ and resumed with --session.
+- All tools (read, bash, edit, write, grep, find, ls) are enabled by default.
+- Agent instructions are appended to Pi's system prompt via --append-system-prompt, while the user task is sent via -p.
+`;
diff --git a/packages/adapters/pi-local/src/server/execute.ts b/packages/adapters/pi-local/src/server/execute.ts
new file mode 100644
index 0000000000..3ea848f590
--- /dev/null
+++ b/packages/adapters/pi-local/src/server/execute.ts
@@ -0,0 +1,435 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";
+import {
+ asString,
+ asNumber,
+ asStringArray,
+ parseObject,
+ buildPaperclipEnv,
+ redactEnvForLogs,
+ ensureAbsoluteDirectory,
+ ensureCommandResolvable,
+ ensurePathInEnv,
+ renderTemplate,
+ runChildProcess,
+} from "@paperclipai/adapter-utils/server-utils";
+import { isPiUnknownSessionError, parsePiJsonl } from "./parse.js";
+import { ensurePiModelConfiguredAndAvailable } from "./models.js";
+
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const PAPERCLIP_SKILLS_CANDIDATES = [
+ path.resolve(__moduleDir, "../../skills"),
+ path.resolve(__moduleDir, "../../../../../skills"),
+];
+
+const PAPERCLIP_SESSIONS_DIR = path.join(os.homedir(), ".pi", "paperclips");
+
+function firstNonEmptyLine(text: string): string {
+ return (
+ text
+ .split(/\r?\n/)
+ .map((line) => line.trim())
+ .find(Boolean) ?? ""
+ );
+}
+
+function parseModelProvider(model: string | null): string | null {
+ if (!model) return null;
+ const trimmed = model.trim();
+ if (!trimmed.includes("/")) return null;
+ return trimmed.slice(0, trimmed.indexOf("/")).trim() || null;
+}
+
+function parseModelId(model: string | null): string | null {
+ if (!model) return null;
+ const trimmed = model.trim();
+ if (!trimmed.includes("/")) return trimmed || null;
+ return trimmed.slice(trimmed.indexOf("/") + 1).trim() || null;
+}
+
+async function resolvePaperclipSkillsDir(): Promise<string | null> {
+ for (const candidate of PAPERCLIP_SKILLS_CANDIDATES) {
+ const isDir = await fs.stat(candidate).then((s) => s.isDirectory()).catch(() => false);
+ if (isDir) return candidate;
+ }
+ return null;
+}
+
+async function ensurePiSkillsInjected(onLog: AdapterExecutionContext["onLog"]) {
+ const skillsDir = await resolvePaperclipSkillsDir();
+ if (!skillsDir) return;
+
+ const piSkillsHome = path.join(os.homedir(), ".pi", "agent", "skills");
+ await fs.mkdir(piSkillsHome, { recursive: true });
+
+ const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+ for (const entry of entries) {
+ if (!entry.isDirectory()) continue;
+ const source = path.join(skillsDir, entry.name);
+ const target = path.join(piSkillsHome, entry.name);
+ const existing = await fs.lstat(target).catch(() => null);
+ if (existing) continue;
+
+ try {
+ await fs.symlink(source, target);
+ await onLog(
+ "stderr",
+ `[paperclip] Injected Pi skill "${entry.name}" into ${piSkillsHome}\n`,
+ );
+ } catch (err) {
+ await onLog(
+ "stderr",
+ `[paperclip] Failed to inject Pi skill "${entry.name}" into ${piSkillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
+ );
+ }
+ }
+}
+
+async function ensureSessionsDir(): Promise<string> {
+ await fs.mkdir(PAPERCLIP_SESSIONS_DIR, { recursive: true });
+ return PAPERCLIP_SESSIONS_DIR;
+}
+
+function buildSessionPath(agentId: string, timestamp: string): string {
+ const safeTimestamp = timestamp.replace(/[:.]/g, "-");
+ return path.join(PAPERCLIP_SESSIONS_DIR, `${safeTimestamp}-${agentId}.jsonl`);
+}
+
+export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
+ const { runId, agent, runtime, config, context, onLog, onMeta, authToken } = ctx;
+
+ const promptTemplate = asString(
+ config.promptTemplate,
+ "You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.",
+ );
+ const command = asString(config.command, "pi");
+ const model = asString(config.model, "").trim();
+ const thinking = asString(config.thinking, "").trim();
+
+ // Parse model into provider and model id
+ const provider = parseModelProvider(model);
+ const modelId = parseModelId(model);
+
+ const workspaceContext = parseObject(context.paperclipWorkspace);
+ const workspaceCwd = asString(workspaceContext.cwd, "");
+ const workspaceSource = asString(workspaceContext.source, "");
+ const workspaceId = asString(workspaceContext.workspaceId, "");
+ const workspaceRepoUrl = asString(workspaceContext.repoUrl, "");
+ const workspaceRepoRef = asString(workspaceContext.repoRef, "");
+ const workspaceHints = Array.isArray(context.paperclipWorkspaces)
+ ? context.paperclipWorkspaces.filter(
+ (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
+ )
+ : [];
+ const configuredCwd = asString(config.cwd, "");
+ const useConfiguredInsteadOfAgentHome = workspaceSource === "agent_home" && configuredCwd.length > 0;
+ const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
+ const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
+ await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
+
+ // Ensure sessions directory exists
+ await ensureSessionsDir();
+
+ // Inject skills
+ await ensurePiSkillsInjected(onLog);
+
+ // Build environment
+ const envConfig = parseObject(config.env);
+ const hasExplicitApiKey =
+ typeof envConfig.PAPERCLIP_API_KEY === "string" && envConfig.PAPERCLIP_API_KEY.trim().length > 0;
+ const env: Record<string, string> = { ...buildPaperclipEnv(agent) };
+ env.PAPERCLIP_RUN_ID = runId;
+
+ const wakeTaskId =
+ (typeof context.taskId === "string" && context.taskId.trim().length > 0 && context.taskId.trim()) ||
+ (typeof context.issueId === "string" && context.issueId.trim().length > 0 && context.issueId.trim()) ||
+ null;
+ const wakeReason =
+ typeof context.wakeReason === "string" && context.wakeReason.trim().length > 0
+ ? context.wakeReason.trim()
+ : null;
+ const wakeCommentId =
+ (typeof context.wakeCommentId === "string" && context.wakeCommentId.trim().length > 0 && context.wakeCommentId.trim()) ||
+ (typeof context.commentId === "string" && context.commentId.trim().length > 0 && context.commentId.trim()) ||
+ null;
+ const approvalId =
+ typeof context.approvalId === "string" && context.approvalId.trim().length > 0
+ ? context.approvalId.trim()
+ : null;
+ const approvalStatus =
+ typeof context.approvalStatus === "string" && context.approvalStatus.trim().length > 0
+ ? context.approvalStatus.trim()
+ : null;
+ const linkedIssueIds = Array.isArray(context.issueIds)
+ ? context.issueIds.filter((value): value is string => typeof value === "string" && value.trim().length > 0)
+ : [];
+
+ if (wakeTaskId) env.PAPERCLIP_TASK_ID = wakeTaskId;
+ if (wakeReason) env.PAPERCLIP_WAKE_REASON = wakeReason;
+ if (wakeCommentId) env.PAPERCLIP_WAKE_COMMENT_ID = wakeCommentId;
+ if (approvalId) env.PAPERCLIP_APPROVAL_ID = approvalId;
+ if (approvalStatus) env.PAPERCLIP_APPROVAL_STATUS = approvalStatus;
+ if (linkedIssueIds.length > 0) env.PAPERCLIP_LINKED_ISSUE_IDS = linkedIssueIds.join(",");
+ if (workspaceCwd) env.PAPERCLIP_WORKSPACE_CWD = workspaceCwd;
+ if (workspaceSource) env.PAPERCLIP_WORKSPACE_SOURCE = workspaceSource;
+ if (workspaceId) env.PAPERCLIP_WORKSPACE_ID = workspaceId;
+ if (workspaceRepoUrl) env.PAPERCLIP_WORKSPACE_REPO_URL = workspaceRepoUrl;
+ if (workspaceRepoRef) env.PAPERCLIP_WORKSPACE_REPO_REF = workspaceRepoRef;
+ if (workspaceHints.length > 0) env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);
+
+ for (const [key, value] of Object.entries(envConfig)) {
+ if (typeof value === "string") env[key] = value;
+ }
+ if (!hasExplicitApiKey && authToken) {
+ env.PAPERCLIP_API_KEY = authToken;
+ }
+
+ const runtimeEnv = Object.fromEntries(
+ Object.entries(ensurePathInEnv({ ...process.env, ...env })).filter(
+ (entry): entry is [string, string] => typeof entry[1] === "string",
+ ),
+ );
+ await ensureCommandResolvable(command, cwd, runtimeEnv);
+
+ // Validate model is available before execution
+ await ensurePiModelConfiguredAndAvailable({
+ model,
+ command,
+ cwd,
+ env: runtimeEnv,
+ });
+
+ const timeoutSec = asNumber(config.timeoutSec, 0);
+ const graceSec = asNumber(config.graceSec, 20);
+ const extraArgs = (() => {
+ const fromExtraArgs = asStringArray(config.extraArgs);
+ if (fromExtraArgs.length > 0) return fromExtraArgs;
+ return asStringArray(config.args);
+ })();
+
+ // Handle session
+ const runtimeSessionParams = parseObject(runtime.sessionParams);
+ const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
+ const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
+ const canResumeSession =
+ runtimeSessionId.length > 0 &&
+ (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(cwd));
+ const sessionPath = canResumeSession ? runtimeSessionId : buildSessionPath(agent.id, new Date().toISOString());
+
+ if (runtimeSessionId && !canResumeSession) {
+ await onLog(
+ "stderr",
+ `[paperclip] Pi session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${cwd}".\n`,
+ );
+ }
+
+ // Ensure session file exists (Pi requires this on first run)
+ if (!canResumeSession) {
+ try {
+ await fs.writeFile(sessionPath, "", { flag: "wx" });
+ } catch (err) {
+ // File may already exist, that's ok
+ if ((err as NodeJS.ErrnoException).code !== "EEXIST") {
+ throw err;
+ }
+ }
+ }
+
+ // Handle instructions file and build system prompt extension
+ const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
+ const resolvedInstructionsFilePath = instructionsFilePath
+ ? path.resolve(cwd, instructionsFilePath)
+ : "";
+ const instructionsFileDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
+
+ let systemPromptExtension = "";
+ if (resolvedInstructionsFilePath) {
+ try {
+ const instructionsContents = await fs.readFile(resolvedInstructionsFilePath, "utf8");
+ systemPromptExtension =
+ `${instructionsContents}\n\n` +
+ `The above agent instructions were loaded from ${resolvedInstructionsFilePath}. ` +
+ `Resolve any relative file references from ${instructionsFileDir}.\n\n` +
+ `You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.`;
+ await onLog(
+ "stderr",
+ `[paperclip] Loaded agent instructions file: ${resolvedInstructionsFilePath}\n`,
+ );
+ } catch (err) {
+ const reason = err instanceof Error ? err.message : String(err);
+ await onLog(
+ "stderr",
+ `[paperclip] Warning: could not read agent instructions file "${resolvedInstructionsFilePath}": ${reason}\n`,
+ );
+ // Fall back to base prompt template
+ systemPromptExtension = promptTemplate;
+ }
+ } else {
+ systemPromptExtension = promptTemplate;
+ }
+
+ const renderedSystemPromptExtension = renderTemplate(systemPromptExtension, {
+ agentId: agent.id,
+ companyId: agent.companyId,
+ runId,
+ company: { id: agent.companyId },
+ agent,
+ run: { id: runId, source: "on_demand" },
+ context,
+ });
+
+ // User prompt is simple - just the rendered prompt template without instructions
+ const userPrompt = renderTemplate(promptTemplate, {
+ agentId: agent.id,
+ companyId: agent.companyId,
+ runId,
+ company: { id: agent.companyId },
+ agent,
+ run: { id: runId, source: "on_demand" },
+ context,
+ });
+
+ const commandNotes = (() => {
+ if (!resolvedInstructionsFilePath) return [] as string[];
+ if (systemPromptExtension.length > 0) {
+ return [
+ `Loaded agent instructions from ${resolvedInstructionsFilePath}`,
+ `Appended instructions + path directive to system prompt (relative references from ${instructionsFileDir}).`,
+ ];
+ }
+ return [
+ `Configured instructionsFilePath ${resolvedInstructionsFilePath}, but file could not be read; continuing without injected instructions.`,
+ ];
+ })();
+
+ const buildArgs = (sessionFile: string): string[] => {
+ const args: string[] = ["-p", userPrompt];
+
+ // Use --append-system-prompt to extend Pi's default system prompt
+ args.push("--append-system-prompt", renderedSystemPromptExtension);
+
+ if (provider) args.push("--provider", provider);
+ if (modelId) args.push("--model", modelId);
+ if (thinking) args.push("--thinking", thinking);
+
+ args.push("--mode", "json");
+ args.push("--tools", "read,bash,edit,write,grep,find,ls");
+ args.push("--session", sessionFile);
+
+ if (extraArgs.length > 0) args.push(...extraArgs);
+
+ return args;
+ };
+
+ const runAttempt = async (sessionFile: string) => {
+ const args = buildArgs(sessionFile);
+ if (onMeta) {
+ await onMeta({
+ adapterType: "pi_local",
+ command,
+ cwd,
+ commandNotes,
+ commandArgs: args,
+ env: redactEnvForLogs(env),
+ prompt: userPrompt,
+ context,
+ });
+ }
+
+ const proc = await runChildProcess(runId, command, args, {
+ cwd,
+ env: runtimeEnv,
+ timeoutSec,
+ graceSec,
+ onLog,
+ });
+ return {
+ proc,
+ rawStderr: proc.stderr,
+ parsed: parsePiJsonl(proc.stdout),
+ };
+ };
+
+ const toResult = (
+ attempt: {
+ proc: { exitCode: number | null; signal: string | null; timedOut: boolean; stdout: string; stderr: string };
+ rawStderr: string;
+ parsed: ReturnType<typeof parsePiJsonl>;
+ },
+ clearSessionOnMissingSession = false,
+ ): AdapterExecutionResult => {
+ if (attempt.proc.timedOut) {
+ return {
+ exitCode: attempt.proc.exitCode,
+ signal: attempt.proc.signal,
+ timedOut: true,
+ errorMessage: `Timed out after ${timeoutSec}s`,
+ clearSession: clearSessionOnMissingSession,
+ };
+ }
+
+ const resolvedSessionId = clearSessionOnMissingSession ? null : sessionPath;
+ const resolvedSessionParams = resolvedSessionId
+ ? { sessionId: resolvedSessionId, cwd }
+ : null;
+
+ const stderrLine = firstNonEmptyLine(attempt.proc.stderr);
+ const rawExitCode = attempt.proc.exitCode;
+ const fallbackErrorMessage = stderrLine || `Pi exited with code ${rawExitCode ?? -1}`;
+
+ return {
+ exitCode: rawExitCode,
+ signal: attempt.proc.signal,
+ timedOut: false,
+ errorMessage: (rawExitCode ?? 0) === 0 ? null : fallbackErrorMessage,
+ usage: {
+ inputTokens: attempt.parsed.usage.inputTokens,
+ outputTokens: attempt.parsed.usage.outputTokens,
+ cachedInputTokens: attempt.parsed.usage.cachedInputTokens,
+ },
+ sessionId: resolvedSessionId,
+ sessionParams: resolvedSessionParams,
+ sessionDisplayId: resolvedSessionId,
+ provider: provider,
+ model: model,
+ billingType: "unknown",
+ costUsd: attempt.parsed.usage.costUsd,
+ resultJson: {
+ stdout: attempt.proc.stdout,
+ stderr: attempt.proc.stderr,
+ },
+ summary: attempt.parsed.finalMessage ?? attempt.parsed.messages.join("\n\n").trim(),
+ clearSession: Boolean(clearSessionOnMissingSession),
+ };
+ };
+
+ const initial = await runAttempt(sessionPath);
+ const initialFailed =
+ !initial.proc.timedOut && ((initial.proc.exitCode ?? 0) !== 0 || initial.parsed.errors.length > 0);
+
+ if (
+ canResumeSession &&
+ initialFailed &&
+ isPiUnknownSessionError(initial.proc.stdout, initial.rawStderr)
+ ) {
+ await onLog(
+ "stderr",
+ `[paperclip] Pi session "${runtimeSessionId}" is unavailable; retrying with a fresh session.\n`,
+ );
+ const newSessionPath = buildSessionPath(agent.id, new Date().toISOString());
+ try {
+ await fs.writeFile(newSessionPath, "", { flag: "wx" });
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code !== "EEXIST") {
+ throw err;
+ }
+ }
+ const retry = await runAttempt(newSessionPath);
+ return toResult(retry, true);
+ }
+
+ return toResult(initial);
+}
diff --git a/packages/adapters/pi-local/src/server/index.ts b/packages/adapters/pi-local/src/server/index.ts
new file mode 100644
index 0000000000..a18d5264a0
--- /dev/null
+++ b/packages/adapters/pi-local/src/server/index.ts
@@ -0,0 +1,60 @@
+import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";
+
+function readNonEmptyString(value: unknown): string | null {
+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+export const sessionCodec: AdapterSessionCodec = {
+ deserialize(raw: unknown) {
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+ const record = raw as Record<string, unknown>;
+ const sessionId =
+ readNonEmptyString(record.sessionId) ??
+ readNonEmptyString(record.session_id) ??
+ readNonEmptyString(record.session);
+ if (!sessionId) return null;
+ const cwd =
+ readNonEmptyString(record.cwd) ??
+ readNonEmptyString(record.workdir) ??
+ readNonEmptyString(record.folder);
+ return {
+ sessionId,
+ ...(cwd ? { cwd } : {}),
+ };
+ },
+ serialize(params: Record<string, unknown> | null) {
+ if (!params) return null;
+ const sessionId =
+ readNonEmptyString(params.sessionId) ??
+ readNonEmptyString(params.session_id) ??
+ readNonEmptyString(params.session);
+ if (!sessionId) return null;
+ const cwd =
+ readNonEmptyString(params.cwd) ??
+ readNonEmptyString(params.workdir) ??
+ readNonEmptyString(params.folder);
+ return {
+ sessionId,
+ ...(cwd ? { cwd } : {}),
+ };
+ },
+ getDisplayId(params: Record<string, unknown> | null) {
+ if (!params) return null;
+ return (
+ readNonEmptyString(params.sessionId) ??
+ readNonEmptyString(params.session_id) ??
+ readNonEmptyString(params.session)
+ );
+ },
+};
+
+export { execute } from "./execute.js";
+export { testEnvironment } from "./test.js";
+export {
+ listPiModels,
+ discoverPiModels,
+ discoverPiModelsCached,
+ ensurePiModelConfiguredAndAvailable,
+ resetPiModelsCacheForTests,
+} from "./models.js";
+export { parsePiJsonl, isPiUnknownSessionError } from "./parse.js";
diff --git a/packages/adapters/pi-local/src/server/models.test.ts b/packages/adapters/pi-local/src/server/models.test.ts
new file mode 100644
index 0000000000..df777544a1
--- /dev/null
+++ b/packages/adapters/pi-local/src/server/models.test.ts
@@ -0,0 +1,33 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+ ensurePiModelConfiguredAndAvailable,
+ listPiModels,
+ resetPiModelsCacheForTests,
+} from "./models.js";
+
+describe("pi models", () => {
+ afterEach(() => {
+ delete process.env.PAPERCLIP_PI_COMMAND;
+ resetPiModelsCacheForTests();
+ });
+
+ it("returns an empty list when discovery command is unavailable", async () => {
+ process.env.PAPERCLIP_PI_COMMAND = "__paperclip_missing_pi_command__";
+ await expect(listPiModels()).resolves.toEqual([]);
+ });
+
+ it("rejects when model is missing", async () => {
+ await expect(
+ ensurePiModelConfiguredAndAvailable({ model: "" }),
+ ).rejects.toThrow("Pi requires `adapterConfig.model`");
+ });
+
+ it("rejects when discovery cannot run for configured model", async () => {
+ process.env.PAPERCLIP_PI_COMMAND = "__paperclip_missing_pi_command__";
+ await expect(
+ ensurePiModelConfiguredAndAvailable({
+ model: "xai/grok-4",
+ }),
+ ).rejects.toThrow();
+ });
+});
diff --git a/packages/adapters/pi-local/src/server/models.ts b/packages/adapters/pi-local/src/server/models.ts
new file mode 100644
index 0000000000..4a85a457db
--- /dev/null
+++ b/packages/adapters/pi-local/src/server/models.ts
@@ -0,0 +1,208 @@
+import { createHash } from "node:crypto";
+import type { AdapterModel } from "@paperclipai/adapter-utils";
+import { asString, runChildProcess } from "@paperclipai/adapter-utils/server-utils";
+
+const MODELS_CACHE_TTL_MS = 60_000;
+
+function firstNonEmptyLine(text: string): string {
+ return (
+ text
+ .split(/\r?\n/)
+ .map((line) => line.trim())
+ .find(Boolean) ?? ""
+ );
+}
+
+function parseModelsOutput(stdout: string): AdapterModel[] {
+ const parsed: AdapterModel[] = [];
+ const lines = stdout.split(/\r?\n/);
+
+ // Skip header line if present
+ let startIndex = 0;
+ if (lines.length > 0 && (lines[0].includes("provider") || lines[0].includes("model"))) {
+ startIndex = 1;
+ }
+
+ for (let i = startIndex; i < lines.length; i++) {
+ const line = lines[i].trim();
+ if (!line) continue;
+
+ // Parse format: "provider model context max-out thinking images"
+ // Split by 2+ spaces to handle the columnar format
+ const parts = line.split(/\s{2,}/);
+ if (parts.length < 2) continue;
+
+ const provider = parts[0].trim();
+ const model = parts[1].trim();
+
+ if (!provider || !model) continue;
+ if (provider === "provider" && model === "model") continue; // Skip header
+
+ const id = `${provider}/${model}`;
+ parsed.push({ id, label: id });
+ }
+
+ return parsed;
+}
+
+function dedupeModels(models: AdapterModel[]): AdapterModel[] {
+ const seen = new Set<string>();
+ const deduped: AdapterModel[] = [];
+ for (const model of models) {
+ const id = model.id.trim();
+ if (!id || seen.has(id)) continue;
+ seen.add(id);
+ deduped.push({ id, label: model.label.trim() || id });
+ }
+ return deduped;
+}
+
+function sortModels(models: AdapterModel[]): AdapterModel[] {
+ return [...models].sort((a, b) =>
+ a.id.localeCompare(b.id, "en", { numeric: true, sensitivity: "base" }),
+ );
+}
+
+function resolvePiCommand(input: unknown): string {
+ const envOverride =
+ typeof process.env.PAPERCLIP_PI_COMMAND === "string" &&
+ process.env.PAPERCLIP_PI_COMMAND.trim().length > 0
+ ? process.env.PAPERCLIP_PI_COMMAND.trim()
+ : "pi";
+ return asString(input, envOverride);
+}
+
+const discoveryCache = new Map<string, { expiresAt: number; models: AdapterModel[] }>();
+const VOLATILE_ENV_KEY_PREFIXES = ["PAPERCLIP_", "npm_", "NPM_"] as const;
+const VOLATILE_ENV_KEY_EXACT = new Set(["PWD", "OLDPWD", "SHLVL", "_", "TERM_SESSION_ID"]);
+
+function isVolatileEnvKey(key: string): boolean {
+ if (VOLATILE_ENV_KEY_EXACT.has(key)) return true;
+ return VOLATILE_ENV_KEY_PREFIXES.some((prefix) => key.startsWith(prefix));
+}
+
+function hashValue(value: string): string {
+ return createHash("sha256").update(value).digest("hex");
+}
+
+function discoveryCacheKey(command: string, cwd: string, env: Record<string, string>) {
+ const envKey = Object.entries(env)
+ .filter(([key]) => !isVolatileEnvKey(key))
+ .sort(([a], [b]) => a.localeCompare(b))
+ .map(([key, value]) => `${key}=${hashValue(value)}`)
+ .join("\n");
+ return `${command}\n${cwd}\n${envKey}`;
+}
+
+function pruneExpiredDiscoveryCache(now: number) {
+ for (const [key, value] of discoveryCache.entries()) {
+ if (value.expiresAt <= now) discoveryCache.delete(key);
+ }
+}
+
+export async function discoverPiModels(input: {
+ command?: unknown;
+ cwd?: unknown;
+ env?: unknown;
+} = {}): Promise<AdapterModel[]> {
+ const command = resolvePiCommand(input.command);
+ const cwd = asString(input.cwd, process.cwd());
+ const env = normalizeEnv(input.env);
+ const runtimeEnv = normalizeEnv({ ...process.env, ...env });
+
+ const result = await runChildProcess(
+ `pi-models-${Date.now()}-${Math.random().toString(16).slice(2)}`,
+ command,
+ ["--list-models"],
+ {
+ cwd,
+ env: runtimeEnv,
+ timeoutSec: 20,
+ graceSec: 3,
+ onLog: async () => {},
+ },
+ );
+
+ if (result.timedOut) {
+ throw new Error("`pi --list-models` timed out.");
+ }
+ if ((result.exitCode ?? 1) !== 0) {
+ const detail = firstNonEmptyLine(result.stderr) || firstNonEmptyLine(result.stdout);
+ throw new Error(detail ? "`pi --list-models` failed: ${detail}" : "`pi --list-models` failed.");
+ }
+
+ return sortModels(dedupeModels(parseModelsOutput(result.stdout)));
+}
+
+function normalizeEnv(input: unknown): Record<string, string> {
+ const envInput = typeof input === "object" && input !== null && !Array.isArray(input)
+ ? (input as Record<string, unknown>)
+ : {};
+ const env: Record<string, string> = {};
+ for (const [key, value] of Object.entries(envInput)) {
+ if (typeof value === "string") env[key] = value;
+ }
+ return env;
+}
+
+export async function discoverPiModelsCached(input: {
+ command?: unknown;
+ cwd?: unknown;
+ env?: unknown;
+} = {}): Promise<AdapterModel[]> {
+ const command = resolvePiCommand(input.command);
+ const cwd = asString(input.cwd, process.cwd());
+ const env = normalizeEnv(input.env);
+ const key = discoveryCacheKey(command, cwd, env);
+ const now = Date.now();
+ pruneExpiredDiscoveryCache(now);
+ const cached = discoveryCache.get(key);
+ if (cached && cached.expiresAt > now) return cached.models;
+
+ const models = await discoverPiModels({ command, cwd, env });
+ discoveryCache.set(key, { expiresAt: now + MODELS_CACHE_TTL_MS, models });
+ return models;
+}
+
+export async function ensurePiModelConfiguredAndAvailable(input: {
+ model?: unknown;
+ command?: unknown;
+ cwd?: unknown;
+ env?: unknown;
+}): Promise<AdapterModel[]> {
+ const model = asString(input.model, "").trim();
+ if (!model) {
+ throw new Error("Pi requires `adapterConfig.model` in provider/model format.");
+ }
+
+ const models = await discoverPiModelsCached({
+ command: input.command,
+ cwd: input.cwd,
+ env: input.env,
+ });
+
+ if (models.length === 0) {
+ throw new Error("Pi returned no models. Run `pi --list-models` and verify provider auth.");
+ }
+
+ if (!models.some((entry) => entry.id === model)) {
+ const sample = models.slice(0, 12).map((entry) => entry.id).join(", ");
+ throw new Error(
+ `Configured Pi model is unavailable: ${model}. Available models: ${sample}${models.length > 12 ? ", ..." : ""}`,
+ );
+ }
+
+ return models;
+}
+
+export async function listPiModels(): Promise<AdapterModel[]> {
+ try {
+ return await discoverPiModelsCached();
+ } catch {
+ return [];
+ }
+}
+
+export function resetPiModelsCacheForTests() {
+ discoveryCache.clear();
+}
diff --git a/packages/adapters/pi-local/src/server/parse.test.ts b/packages/adapters/pi-local/src/server/parse.test.ts
new file mode 100644
index 0000000000..d1d695b30d
--- /dev/null
+++ b/packages/adapters/pi-local/src/server/parse.test.ts
@@ -0,0 +1,113 @@
+import { describe, expect, it } from "vitest";
+import { parsePiJsonl, isPiUnknownSessionError } from "./parse.js";
+
+describe("parsePiJsonl", () => {
+ it("parses agent lifecycle and messages", () => {
+ const stdout = [
+ JSON.stringify({ type: "agent_start" }),
+ JSON.stringify({
+ type: "turn_end",
+ message: {
+ role: "assistant",
+ content: [{ type: "text", text: "Hello from Pi" }],
+ },
+ }),
+ JSON.stringify({ type: "agent_end", messages: [] }),
+ ].join("\n");
+
+ const parsed = parsePiJsonl(stdout);
+ expect(parsed.messages).toContain("Hello from Pi");
+ expect(parsed.finalMessage).toBe("Hello from Pi");
+ });
+
+ it("parses streaming text deltas", () => {
+ const stdout = [
+ JSON.stringify({
+ type: "message_update",
+ assistantMessageEvent: { type: "text_delta", delta: "Hello " },
+ }),
+ JSON.stringify({
+ type: "message_update",
+ assistantMessageEvent: { type: "text_delta", delta: "World" },
+ }),
+ JSON.stringify({
+ type: "turn_end",
+ message: {
+ role: "assistant",
+ content: "Hello World",
+ },
+ }),
+ ].join("\n");
+
+ const parsed = parsePiJsonl(stdout);
+ expect(parsed.messages).toContain("Hello World");
+ });
+
+ it("parses tool execution", () => {
+ const stdout = [
+ JSON.stringify({
+ type: "tool_execution_start",
+ toolCallId: "tool_1",
+ toolName: "read",
+ args: { path: "/tmp/test.txt" },
+ }),
+ JSON.stringify({
+ type: "tool_execution_end",
+ toolCallId: "tool_1",
+ toolName: "read",
+ result: "file contents",
+ isError: false,
+ }),
+ JSON.stringify({
+ type: "turn_end",
+ message: { role: "assistant", content: "Done" },
+ toolResults: [
+ {
+ toolCallId: "tool_1",
+ content: "file contents",
+ isError: false,
+ },
+ ],
+ }),
+ ].join("\n");
+
+ const parsed = parsePiJsonl(stdout);
+ expect(parsed.toolCalls).toHaveLength(1);
+ expect(parsed.toolCalls[0].toolName).toBe("read");
+ expect(parsed.toolCalls[0].result).toBe("file contents");
+ expect(parsed.toolCalls[0].isError).toBe(false);
+ });
+
+ it("handles errors in tool execution", () => {
+ const stdout = [
+ JSON.stringify({
+ type: "tool_execution_start",
+ toolCallId: "tool_1",
+ toolName: "read",
+ args: { path: "/missing.txt" },
+ }),
+ JSON.stringify({
+ type: "tool_execution_end",
+ toolCallId: "tool_1",
+ toolName: "read",
+ result: "File not found",
+ isError: true,
+ }),
+ ].join("\n");
+
+ const parsed = parsePiJsonl(stdout);
+ expect(parsed.toolCalls).toHaveLength(1);
+ expect(parsed.toolCalls[0].isError).toBe(true);
+ expect(parsed.toolCalls[0].result).toBe("File not found");
+ });
+});
+
+describe("isPiUnknownSessionError", () => {
+ it("detects unknown session errors", () => {
+ expect(isPiUnknownSessionError("session not found: s_123", "")).toBe(true);
+ expect(isPiUnknownSessionError("", "unknown session id")).toBe(true);
+ expect(isPiUnknownSessionError("", "no session available")).toBe(true);
+ expect(isPiUnknownSessionError("all good", "")).toBe(false);
+ expect(isPiUnknownSessionError("working fine", "no errors")).toBe(false);
+ });
+});
diff --git a/packages/adapters/pi-local/src/server/parse.ts b/packages/adapters/pi-local/src/server/parse.ts
new file mode 100644
index 0000000000..095e814ee6
--- /dev/null
+++ b/packages/adapters/pi-local/src/server/parse.ts
@@ -0,0 +1,182 @@
+import { asNumber, asString, parseJson, parseObject } from "@paperclipai/adapter-utils/server-utils";
+
+interface ParsedPiOutput {
+ sessionId: string | null;
+ messages: string[];
+ errors: string[];
+ usage: {
+ inputTokens: number;
+ outputTokens: number;
+ cachedInputTokens: number;
+ costUsd: number;
+ };
+ finalMessage: string | null;
+ toolCalls: Array<{ toolName: string; args: unknown; result: string | null; isError: boolean }>;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+ return value as Record<string, unknown>;
+}
+
+function extractTextContent(content: string | Array<{ type: string; text?: string }>): string {
+ if (typeof content === "string") return content;
+ if (!Array.isArray(content)) return "";
+ return content
+ .filter((c) => c.type === "text" && c.text)
+ .map((c) => c.text!)
+ .join("");
+}
+
+export function parsePiJsonl(stdout: string): ParsedPiOutput {
+ const result: ParsedPiOutput = {
+ sessionId: null,
+ messages: [],
+ errors: [],
+ usage: {
+ inputTokens: 0,
+ outputTokens: 0,
+ cachedInputTokens: 0,
+ costUsd: 0,
+ },
+ finalMessage: null,
+ toolCalls: [],
+ };
+
+ let currentToolCall: { toolName: string; args: unknown } | null = null;
+
+ for (const rawLine of stdout.split(/\r?\n/)) {
+ const line = rawLine.trim();
+ if (!line) continue;
+
+ const event = parseJson(line);
+ if (!event) continue;
+
+ const eventType = asString(event.type, "");
+
+ // Agent lifecycle
+ if (eventType === "agent_start") {
+ continue;
+ }
+
+ if (eventType === "agent_end") {
+ const messages = event.messages as Array<Record<string, unknown>> | undefined;
+ if (messages && messages.length > 0) {
+ const lastMessage = messages[messages.length - 1];
+ if (lastMessage?.role === "assistant") {
+ const content = lastMessage.content as string | Array<{ type: string; text?: string }>;
+ result.finalMessage = extractTextContent(content);
+ }
+ }
+ continue;
+ }
+
+ // Turn lifecycle
+ if (eventType === "turn_start") {
+ continue;
+ }
+
+ if (eventType === "turn_end") {
+ const message = asRecord(event.message);
+ if (message) {
+ const content = message.content as string | Array<{ type: string; text?: string }>;
+ const text = extractTextContent(content);
+ if (text) {
+ result.finalMessage = text;
+ result.messages.push(text);
+ }
+ }
+
+ // Tool results are in toolResults array
+ const toolResults = event.toolResults as Array<Record<string, unknown>> | undefined;
+ if (toolResults) {
+ for (const tr of toolResults) {
+ const toolCallId = asString(tr.toolCallId, "");
+ const content = tr.content;
+ const isError = tr.isError === true;
+
+ // Find matching tool call
+ const existingCall = result.toolCalls.find((tc) => tc.toolName === toolCallId);
+ if (existingCall) {
+ existingCall.result = typeof content === "string" ? content : JSON.stringify(content);
+ existingCall.isError = isError;
+ }
+ }
+ }
+ continue;
+ }
+
+ // Message updates (streaming)
+ if (eventType === "message_update") {
+ const assistantEvent = asRecord(event.assistantMessageEvent);
+ if (assistantEvent) {
+ const msgType = asString(assistantEvent.type, "");
+ if (msgType === "text_delta") {
+ const delta = asString(assistantEvent.delta, "");
+ if (delta) {
+ // Append to last message or create new
+ if (result.messages.length === 0) {
+ result.messages.push(delta);
+ } else {
+ result.messages[result.messages.length - 1] += delta;
+ }
+ }
+ }
+ }
+ continue;
+ }
+
+ // Tool execution
+ if (eventType === "tool_execution_start") {
+ const toolName = asString(event.toolName, "");
+ const args = event.args;
+ currentToolCall = { toolName, args };
+ result.toolCalls.push({
+ toolName,
+ args,
+ result: null,
+ isError: false,
+ });
+ continue;
+ }
+
+ if (eventType === "tool_execution_end") {
+ const toolCallId = asString(event.toolCallId, "");
+ const toolName = asString(event.toolName, "");
+ const toolResult = event.result;
+ const isError = event.isError === true;
+
+ // Find the tool call
+ const existingCall = result.toolCalls.find((tc) => tc.toolName === toolName);
+ if (existingCall) {
+ existingCall.result = typeof toolResult === "string" ? toolResult : JSON.stringify(toolResult);
+ existingCall.isError = isError;
+ }
+ currentToolCall = null;
+ continue;
+ }
+
+ // Usage tracking if available in the event
+ if (eventType === "usage" || event.usage) {
+ const usage = asRecord(event.usage);
+ if (usage) {
+ result.usage.inputTokens += asNumber(usage.inputTokens, 0);
+ result.usage.outputTokens += asNumber(usage.outputTokens, 0);
+ result.usage.cachedInputTokens += asNumber(usage.cachedInputTokens, 0);
+ result.usage.costUsd += asNumber(usage.costUsd, 0);
+ }
+ }
+ }
+
+ return result;
+}
+
+export function isPiUnknownSessionError(stdout: string, stderr: string): boolean {
+ const haystack = `${stdout}\n${stderr}`
+ .split(/\r?\n/)
+ .map((line) => line.trim())
+ .filter(Boolean)
+ .join("\n");
+
+ return /unknown\s+session|session\s+not\s+found|session\s+.*\s+not\s+found|no\s+session/i.test(haystack);
+}
diff --git a/packages/adapters/pi-local/src/server/test.ts b/packages/adapters/pi-local/src/server/test.ts
new file mode 100644
index 0000000000..cf8fa80adf
--- /dev/null
+++ b/packages/adapters/pi-local/src/server/test.ts
@@ -0,0 +1,276 @@
+import type {
+ AdapterEnvironmentCheck,
+ AdapterEnvironmentTestContext,
+ AdapterEnvironmentTestResult,
+} from "@paperclipai/adapter-utils";
+import {
+ asString,
+ parseObject,
+ ensureAbsoluteDirectory,
+ ensureCommandResolvable,
+ ensurePathInEnv,
+ runChildProcess,
+} from "@paperclipai/adapter-utils/server-utils";
+import {
+ asStringArray,
+} from "@paperclipai/adapter-utils/server-utils";
+import { discoverPiModelsCached } from "./models.js";
+import { parsePiJsonl } from "./parse.js";
+
+function summarizeStatus(checks: AdapterEnvironmentCheck[]): AdapterEnvironmentTestResult["status"] {
+ if (checks.some((check) => check.level === "error")) return "fail";
+ if (checks.some((check) => check.level === "warn")) return "warn";
+ return "pass";
+}
+
+function firstNonEmptyLine(text: string): string {
+ return (
+ text
+ .split(/\r?\n/)
+ .map((line) => line.trim())
+ .find(Boolean) ?? ""
+ );
+}
+
+function summarizeProbeDetail(stdout: string, stderr: string, parsedError: string | null): string | null {
+ const raw = parsedError?.trim() || firstNonEmptyLine(stderr) || firstNonEmptyLine(stdout);
+ if (!raw) return null;
+ const clean = raw.replace(/\s+/g, " ").trim();
+ const max = 240;
+ return clean.length > max ? `${clean.slice(0, max - 1)}...` : clean;
+}
+
+function normalizeEnv(input: unknown): Record<string, string> {
+ if (typeof input !== "object" || input === null || Array.isArray(input)) return {};
+ const env: Record<string, string> = {};
+ for (const [key, value] of Object.entries(input as Record<string, unknown>)) {
+ if (typeof value === "string") env[key] = value;
+ }
+ return env;
+}
+
+const PI_AUTH_REQUIRED_RE =
+ /(?:auth(?:entication)?\s+required|api\s*key|invalid\s*api\s*key|not\s+logged\s+in|free\s+usage\s+exceeded)/i;
+
+export async function testEnvironment(
+ ctx: AdapterEnvironmentTestContext,
+): Promise<AdapterEnvironmentTestResult> {
+ const checks: AdapterEnvironmentCheck[] = [];
+ const config = parseObject(ctx.config);
+ const command = asString(config.command, "pi");
+ const cwd = asString(config.cwd, process.cwd());
+
+ try {
+ await ensureAbsoluteDirectory(cwd, { createIfMissing: false });
+ checks.push({
+ code: "pi_cwd_valid",
+ level: "info",
+ message: `Working directory is valid: ${cwd}`,
+ });
+ } catch (err) {
+ checks.push({
+ code: "pi_cwd_invalid",
+ level: "error",
+ message: err instanceof Error ? err.message : "Invalid working directory",
+ detail: cwd,
+ });
+ }
+
+ const envConfig = parseObject(config.env);
+ const env: Record<string, string> = {};
+ for (const [key, value] of Object.entries(envConfig)) {
+ if (typeof value === "string") env[key] = value;
+ }
+ const runtimeEnv = normalizeEnv(ensurePathInEnv({ ...process.env, ...env }));
+
+ const cwdInvalid = checks.some((check) => check.code === "pi_cwd_invalid");
+ if (cwdInvalid) {
+ checks.push({
+ code: "pi_command_skipped",
+ level: "warn",
+ message: "Skipped command check because working directory validation failed.",
+ detail: command,
+ });
+ } else {
+ try {
+ await ensureCommandResolvable(command, cwd, runtimeEnv);
+ checks.push({
+ code: "pi_command_resolvable",
+ level: "info",
+ message: `Command is executable: ${command}`,
+ });
+ } catch (err) {
+ checks.push({
+ code: "pi_command_unresolvable",
+ level: "error",
+ message: err instanceof Error ? err.message : "Command is not executable",
+ detail: command,
+ });
+ }
+ }
+
+ const canRunProbe =
+ checks.every((check) => check.code !== "pi_cwd_invalid" && check.code !== "pi_command_unresolvable");
+
+ if (canRunProbe) {
+ try {
+ const discovered = await discoverPiModelsCached({ command, cwd, env: runtimeEnv });
+ if (discovered.length > 0) {
+ checks.push({
+ code: "pi_models_discovered",
+ level: "info",
+ message: `Discovered ${discovered.length} model(s) from Pi.`,
+ });
+ } else {
+ checks.push({
+ code: "pi_models_empty",
+ level: "warn",
+ message: "Pi returned no models.",
+ hint: "Run `pi --list-models` and verify provider authentication.",
+ });
+ }
+ } catch (err) {
+ checks.push({
+ code: "pi_models_discovery_failed",
+ level: "warn",
+ message: err instanceof Error ? err.message : "Pi model discovery failed.",
+ hint: "Run `pi --list-models` manually to verify provider auth and config.",
+ });
+ }
+ }
+
+ const configuredModel = asString(config.model, "").trim();
+ if (!configuredModel) {
+ checks.push({
+ code: "pi_model_required",
+ level: "error",
+ message: "Pi requires a configured model in provider/model format.",
+ hint: "Set adapterConfig.model using an ID from `pi --list-models`.",
+ });
+ } else if (canRunProbe) {
+ // Verify model is in the list
+ try {
+ const discovered = await discoverPiModelsCached({ command, cwd, env: runtimeEnv });
+ const modelExists = discovered.some((m: { id: string }) => m.id === configuredModel);
+ if (modelExists) {
+ checks.push({
+ code: "pi_model_configured",
+ level: "info",
+ message: `Configured model: ${configuredModel}`,
+ });
+ } else {
+ checks.push({
+ code: "pi_model_not_found",
+ level: "warn",
+ message: `Configured model "${configuredModel}" not found in available models.`,
+ hint: "Run `pi --list-models` and choose a currently available provider/model ID.",
+ });
+ }
+ } catch {
+ // If we can't verify, just note it
+ checks.push({
+ code: "pi_model_configured",
+ level: "info",
+ message: `Configured model: ${configuredModel}`,
+ });
+ }
+ }
+
+ if (canRunProbe && configuredModel) {
+ // Parse model for probe
+ const provider = configuredModel.includes("/")
+ ? configuredModel.slice(0, configuredModel.indexOf("/"))
+ : "";
+ const modelId = configuredModel.includes("/")
+ ? configuredModel.slice(configuredModel.indexOf("/") + 1)
+ : configuredModel;
+ const thinking = asString(config.thinking, "").trim();
+ const extraArgs = (() => {
+ const fromExtraArgs = asStringArray(config.extraArgs);
+ if (fromExtraArgs.length > 0) return fromExtraArgs;
+ return asStringArray(config.args);
+ })();
+
+ const args = ["-p", "Respond with hello.", "--mode", "json"];
+ if (provider) args.push("--provider", provider);
+ if (modelId) args.push("--model", modelId);
+ if (thinking) args.push("--thinking", thinking);
+ args.push("--tools", "read");
+ if (extraArgs.length > 0) args.push(...extraArgs);
+
+ try {
+ const probe = await runChildProcess(
+ `pi-envtest-${Date.now()}-${Math.random().toString(16).slice(2)}`,
+ command,
+ args,
+ {
+ cwd,
+ env: runtimeEnv,
+ timeoutSec: 60,
+ graceSec: 5,
+ onLog: async () => {},
+ },
+ );
+
+ const parsed = parsePiJsonl(probe.stdout);
+ const detail = summarizeProbeDetail(probe.stdout, probe.stderr, parsed.errors[0] ?? null);
+ const authEvidence = `${parsed.errors.join("\n")}\n${probe.stdout}\n${probe.stderr}`.trim();
+
+ if (probe.timedOut) {
+ checks.push({
+ code: "pi_hello_probe_timed_out",
+ level: "warn",
+ message: "Pi hello probe timed out.",
+ hint: "Retry the probe. If this persists, run Pi manually in this working directory.",
+ });
+ } else if ((probe.exitCode ?? 1) === 0 && parsed.errors.length === 0) {
+ const summary = (parsed.finalMessage || parsed.messages.join(" ")).trim();
+ const hasHello = /\bhello\b/i.test(summary);
+ checks.push({
+ code: hasHello ? "pi_hello_probe_passed" : "pi_hello_probe_unexpected_output",
+ level: hasHello ? "info" : "warn",
+ message: hasHello
+ ? "Pi hello probe succeeded."
+ : "Pi probe ran but did not return `hello` as expected.",
+ ...(summary ? { detail: summary.replace(/\s+/g, " ").trim().slice(0, 240) } : {}),
+ ...(hasHello
+ ? {}
+ : {
+ hint: "Run `pi --mode json` manually and prompt `Respond with hello` to inspect output.",
+ }),
+ });
+ } else if (PI_AUTH_REQUIRED_RE.test(authEvidence)) {
+ checks.push({
+ code: "pi_hello_probe_auth_required",
+ level: "warn",
+ message: "Pi is installed, but provider authentication is not ready.",
+ ...(detail ? { detail } : {}),
+ hint: "Set provider API key environment variable (e.g., ANTHROPIC_API_KEY, XAI_API_KEY) and retry.",
+ });
+ } else {
+ checks.push({
+ code: "pi_hello_probe_failed",
+ level: "error",
+ message: "Pi hello probe failed.",
+ ...(detail ? { detail } : {}),
+ hint: "Run `pi --mode json` manually in this working directory to debug.",
+ });
+ }
+ } catch (err) {
+ checks.push({
+ code: "pi_hello_probe_failed",
+ level: "error",
+ message: "Pi hello probe failed.",
+ detail: err instanceof Error ? err.message : String(err),
+ hint: "Run `pi --mode json` manually in this working directory to debug.",
+ });
+ }
+ }
+
+ return {
+ adapterType: ctx.adapterType,
+ status: summarizeStatus(checks),
+ checks,
+ testedAt: new Date().toISOString(),
+ };
+}
diff --git a/packages/adapters/pi-local/src/ui/build-config.ts b/packages/adapters/pi-local/src/ui/build-config.ts
new file mode 100644
index 0000000000..f871019d71
--- /dev/null
+++ b/packages/adapters/pi-local/src/ui/build-config.ts
@@ -0,0 +1,71 @@
+import type { CreateConfigValues } from "@paperclipai/adapter-utils";
+
+function parseEnvVars(text: string): Record<string, string> {
+ const env: Record<string, string> = {};
+ for (const line of text.split(/\r?\n/)) {
+ const trimmed = line.trim();
+ if (!trimmed || trimmed.startsWith("#")) continue;
+ const eq = trimmed.indexOf("=");
+ if (eq <= 0) continue;
+ const key = trimmed.slice(0, eq).trim();
+ const value = trimmed.slice(eq + 1);
+ if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+ env[key] = value;
+ }
+ return env;
+}
+
+function parseEnvBindings(bindings: unknown): Record<string, unknown> {
+ if (typeof bindings !== "object" || bindings === null || Array.isArray(bindings)) return {};
+ const env: Record<string, unknown> = {};
+ for (const [key, raw] of Object.entries(bindings)) {
+ if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+ if (typeof raw === "string") {
+ env[key] = { type: "plain", value: raw };
+ continue;
+ }
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) continue;
+ const rec = raw as Record<string, unknown>;
+ if (rec.type === "plain" && typeof rec.value === "string") {
+ env[key] = { type: "plain", value: rec.value };
+ continue;
+ }
+ if (rec.type === "secret_ref" && typeof rec.secretId === "string") {
+ env[key] = {
+ type: "secret_ref",
+ secretId: rec.secretId,
+ ...(typeof rec.version === "number" || rec.version === "latest"
+ ? { version: rec.version }
+ : {}),
+ };
+ }
+ }
+ return env;
+}
+
+export function buildPiLocalConfig(v: CreateConfigValues): Record<string, unknown> {
+ const ac: Record<string, unknown> = {};
+ if (v.cwd) ac.cwd = v.cwd;
+ if (v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
+ if (v.promptTemplate) ac.promptTemplate = v.promptTemplate;
+ if (v.model) ac.model = v.model;
+ if (v.thinkingEffort) ac.thinking = v.thinkingEffort;
+
+ // Pi sessions can run until the CLI exits naturally; keep timeout disabled (0)
+ ac.timeoutSec = 0;
+ ac.graceSec = 20;
+
+ const env = parseEnvBindings(v.envBindings);
+ const legacy = parseEnvVars(v.envVars);
+ for (const [key, value] of Object.entries(legacy)) {
+ if (!Object.prototype.hasOwnProperty.call(env, key)) {
+ env[key] = { type: "plain", value };
+ }
+ }
+ if (Object.keys(env).length > 0) ac.env = env;
+ if (v.command) ac.command = v.command;
+ if (v.extraArgs) ac.extraArgs = v.extraArgs;
+ if (v.args) ac.args = v.args;
+
+ return ac;
+}
diff --git a/packages/adapters/pi-local/src/ui/index.ts b/packages/adapters/pi-local/src/ui/index.ts
new file mode 100644
index 0000000000..89b781a719
--- /dev/null
+++ b/packages/adapters/pi-local/src/ui/index.ts
@@ -0,0 +1,2 @@
+export { parsePiStdoutLine } from "./parse-stdout.js";
+export { buildPiLocalConfig } from "./build-config.js";
diff --git a/packages/adapters/pi-local/src/ui/parse-stdout.ts b/packages/adapters/pi-local/src/ui/parse-stdout.ts
new file mode 100644
index 0000000000..08e1329040
--- /dev/null
+++ b/packages/adapters/pi-local/src/ui/parse-stdout.ts
@@ -0,0 +1,142 @@
+import type { TranscriptEntry } from "@paperclipai/adapter-utils";
+
+function safeJsonParse(text: string): unknown {
+ try {
+ return JSON.parse(text);
+ } catch {
+ return null;
+ }
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+ return value as Record<string, unknown>;
+}
+
+function asString(value: unknown, fallback = ""): string {
+ return typeof value === "string" ? value : fallback;
+}
+
+function extractTextContent(content: string | Array<{ type: string; text?: string }>): string {
+ if (typeof content === "string") return content;
+ if (!Array.isArray(content)) return "";
+ return content
+ .filter((c) => c.type === "text" && c.text)
+ .map((c) => c.text!)
+ .join("");
+}
+
+export function parsePiStdoutLine(line: string, ts: string): TranscriptEntry[] {
+ const parsed = asRecord(safeJsonParse(line));
+ if (!parsed) {
+ return [{ kind: "stdout", ts, text: line }];
+ }
+
+ const type = asString(parsed.type);
+
+ // Agent lifecycle
+ if (type === "agent_start") {
+ return [{ kind: "system", ts, text: "Pi agent started" }];
+ }
+
+ if (type === "agent_end") {
+ return [{ kind: "system", ts, text: "Pi agent finished" }];
+ }
+
+ // Turn lifecycle
+ if (type === "turn_start") {
+ return [{ kind: "system", ts, text: "Turn started" }];
+ }
+
+ if (type === "turn_end") {
+ const message = asRecord(parsed.message);
+ const toolResults = parsed.toolResults as Array<Record<string, unknown>> | undefined;
+
+ const entries: TranscriptEntry[] = [];
+
+ if (message) {
+ const content = message.content as string | Array<{ type: string; text?: string }>;
+ const text = extractTextContent(content);
+ if (text) {
+ entries.push({ kind: "assistant", ts, text });
+ }
+ }
+
+ // Process tool results
+ if (toolResults) {
+ for (const tr of toolResults) {
+ const content = tr.content;
+ const isError = tr.isError === true;
+ const contentStr = typeof content === "string" ? content : JSON.stringify(content);
+ entries.push({
+ kind: "tool_result",
+ ts,
+ toolUseId: asString(tr.toolCallId, "unknown"),
+ content: contentStr,
+ isError,
+ });
+ }
+ }
+
+ return entries.length > 0 ? entries : [{ kind: "system", ts, text: "Turn ended" }];
+ }
+
+ // Message streaming
+ if (type === "message_start") {
+ return [];
+ }
+
+ if (type === "message_update") {
+ const assistantEvent = asRecord(parsed.assistantMessageEvent);
+ if (assistantEvent) {
+ const msgType = asString(assistantEvent.type);
+ if (msgType === "text_delta") {
+ const delta = asString(assistantEvent.delta);
+ if (delta) {
+ return [{ kind: "assistant", ts, text: delta, delta: true }];
+ }
+ }
+ }
+ return [];
+ }
+
+ if (type === "message_end") {
+ return [];
+ }
+
+ // Tool execution
+ if (type === "tool_execution_start") {
+ const toolName = asString(parsed.toolName);
+ const args = parsed.args;
+ if (toolName) {
+ return [{
+ kind: "tool_call",
+ ts,
+ name: toolName,
+ input: args,
+ }];
+ }
+ return [{ kind: "system", ts, text: `Tool started` }];
+ }
+
+ if (type === "tool_execution_update") {
+ return [];
+ }
+
+ if (type === "tool_execution_end") {
+ const toolCallId = asString(parsed.toolCallId);
+ const result = parsed.result;
+ const isError = parsed.isError === true;
+ const contentStr = typeof result === "string" ? result : JSON.stringify(result);
+
+ return [{
+ kind: "tool_result",
+ ts,
+ toolUseId: toolCallId || "unknown",
+ content: contentStr,
+ isError,
+ }];
+ }
+
+ return [{ kind: "stdout", ts, text: line }];
+}
diff --git a/packages/adapters/pi-local/tsconfig.json b/packages/adapters/pi-local/tsconfig.json
new file mode 100644
index 0000000000..2f355cfeeb
--- /dev/null
+++ b/packages/adapters/pi-local/tsconfig.json
@@ -0,0 +1,8 @@
+{
+ "extends": "../../../tsconfig.json",
+ "compilerOptions": {
+ "outDir": "dist",
+ "rootDir": "src"
+ },
+ "include": ["src"]
+}
diff --git a/packages/adapters/pi-local/vitest.config.ts b/packages/adapters/pi-local/vitest.config.ts
new file mode 100644
index 0000000000..f624398e8d
--- /dev/null
+++ b/packages/adapters/pi-local/vitest.config.ts
@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+ test: {
+ environment: "node",
+ },
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 492cd35ae0..cb2d1d55fc 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -41,6 +41,9 @@ importers:
'@paperclipai/adapter-opencode-local':
specifier: workspace:*
version: link:../packages/adapters/opencode-local
+ '@paperclipai/adapter-pi-local':
+ specifier: workspace:*
+ version: link:../packages/adapters/pi-local
'@paperclipai/adapter-utils':
specifier: workspace:*
version: link:../packages/adapter-utils
@@ -156,8 +159,24 @@ importers:
version: 1.1.1
devDependencies:
'@types/node':
- specifier: ^22.12.0
- version: 22.19.11
+ specifier: ^24.6.0
+ version: 24.12.0
+ typescript:
+ specifier: ^5.7.3
+ version: 5.9.3
+
+ packages/adapters/pi-local:
+ dependencies:
+ '@paperclipai/adapter-utils':
+ specifier: workspace:*
+ version: link:../../adapter-utils
+ picocolors:
+ specifier: ^1.1.1
+ version: 1.1.1
+ devDependencies:
+ '@types/node':
+ specifier: ^24.6.0
+ version: 24.12.0
typescript:
specifier: ^5.7.3
version: 5.9.3
@@ -220,6 +239,9 @@ importers:
'@paperclipai/adapter-opencode-local':
specifier: workspace:*
version: link:../packages/adapters/opencode-local
+ '@paperclipai/adapter-pi-local':
+ specifier: workspace:*
+ version: link:../packages/adapters/pi-local
'@paperclipai/adapter-utils':
specifier: workspace:*
version: link:../packages/adapter-utils
@@ -332,6 +354,9 @@ importers:
'@paperclipai/adapter-opencode-local':
specifier: workspace:*
version: link:../packages/adapters/opencode-local
+ '@paperclipai/adapter-pi-local':
+ specifier: workspace:*
+ version: link:../packages/adapters/pi-local
'@paperclipai/adapter-utils':
specifier: workspace:*
version: link:../packages/adapter-utils
@@ -8162,7 +8187,7 @@ snapshots:
dependencies:
'@types/connect': 3.4.38
- '@types/node': 24.12.0
+ '@types/node': 25.2.3
dependencies:
@@ -8171,7 +8196,7 @@ snapshots:
dependencies:
- '@types/node': 24.12.0
+ '@types/node': 25.2.3
'@types/[email protected]': {}
@@ -8189,7 +8214,7 @@ snapshots:
dependencies:
- '@types/node': 24.12.0
+ '@types/node': 25.2.3
'@types/qs': 6.14.0
'@types/range-parser': 1.2.7
'@types/send': 1.2.1
@@ -8246,18 +8271,18 @@ snapshots:
dependencies:
- '@types/node': 24.12.0
+ '@types/node': 25.2.3
dependencies:
'@types/http-errors': 2.0.5
- '@types/node': 24.12.0
+ '@types/node': 25.2.3
dependencies:
'@types/cookiejar': 2.1.5
'@types/methods': 1.1.4
- '@types/node': 24.12.0
+ '@types/node': 25.2.3
form-data: 4.0.5
@@ -8271,7 +8296,7 @@ snapshots:
dependencies:
- '@types/node': 24.12.0
+ '@types/node': 25.2.3
'@ungap/[email protected]': {}
diff --git a/server/package.json b/server/package.json
index 2e47011152..ae5407894e 100644
--- a/server/package.json
+++ b/server/package.json
@@ -35,6 +35,7 @@
"@paperclipai/adapter-codex-local": "workspace:*",
"@paperclipai/adapter-cursor-local": "workspace:*",
"@paperclipai/adapter-opencode-local": "workspace:*",
+ "@paperclipai/adapter-pi-local": "workspace:*",
"@paperclipai/adapter-openclaw": "workspace:*",
"@paperclipai/adapter-utils": "workspace:*",
"@paperclipai/db": "workspace:*",
diff --git a/server/src/adapters/registry.ts b/server/src/adapters/registry.ts
index cc8c040cf9..3d1b98d885 100644
--- a/server/src/adapters/registry.ts
+++ b/server/src/adapters/registry.ts
@@ -37,6 +37,15 @@ import {
} from "@paperclipai/adapter-openclaw";
import { listCodexModels } from "./codex-models.js";
import { listCursorModels } from "./cursor-models.js";
+import {
+ execute as piExecute,
+ testEnvironment as piTestEnvironment,
+ sessionCodec as piSessionCodec,
+ listPiModels,
+} from "@paperclipai/adapter-pi-local/server";
+import {
+ agentConfigurationDoc as piAgentConfigurationDoc,
+} from "@paperclipai/adapter-pi-local";
import { processAdapter } from "./process/index.js";
import { httpAdapter } from "./http/index.js";
@@ -93,8 +102,19 @@ const openCodeLocalAdapter: ServerAdapterModule = {
agentConfigurationDoc: openCodeAgentConfigurationDoc,
};
+const piLocalAdapter: ServerAdapterModule = {
+ type: "pi_local",
+ execute: piExecute,
+ testEnvironment: piTestEnvironment,
+ sessionCodec: piSessionCodec,
+ models: [],
+ listModels: listPiModels,
+ supportsLocalAgentJwt: true,
+ agentConfigurationDoc: piAgentConfigurationDoc,
+};
+
const adaptersByType = new Map<string, ServerAdapterModule>(
- [claudeLocalAdapter, codexLocalAdapter, openCodeLocalAdapter, cursorLocalAdapter, openclawAdapter, processAdapter, httpAdapter].map((a) => [a.type, a]),
+ [claudeLocalAdapter, codexLocalAdapter, openCodeLocalAdapter, piLocalAdapter, cursorLocalAdapter, openclawAdapter, processAdapter, httpAdapter].map((a) => [a.type, a]),
);
export function getServerAdapter(type: string): ServerAdapterModule {
diff --git a/ui/package.json b/ui/package.json
index ccd40dd723..d6cb11130b 100644
--- a/ui/package.json
+++ b/ui/package.json
@@ -18,6 +18,7 @@
"@paperclipai/adapter-codex-local": "workspace:*",
"@paperclipai/adapter-cursor-local": "workspace:*",
"@paperclipai/adapter-opencode-local": "workspace:*",
+ "@paperclipai/adapter-pi-local": "workspace:*",
"@paperclipai/adapter-openclaw": "workspace:*",
"@paperclipai/adapter-utils": "workspace:*",
"@paperclipai/shared": "workspace:*",
diff --git a/ui/src/adapters/pi-local/config-fields.tsx b/ui/src/adapters/pi-local/config-fields.tsx
new file mode 100644
index 0000000000..e6afacb3e8
--- /dev/null
+++ b/ui/src/adapters/pi-local/config-fields.tsx
@@ -0,0 +1,47 @@
+import type { AdapterConfigFieldsProps } from "../types";
+import {
+ Field,
+ DraftInput,
+} from "../../components/agent-config-primitives";
+import { ChoosePathButton } from "../../components/PathInstructionsModal";
+
+const inputClass =
+ "w-full rounded-md border border-border px-2.5 py-1.5 bg-transparent outline-none text-sm font-mono placeholder:text-muted-foreground/40";
+const instructionsFileHint =
+ "Absolute path to a markdown file (e.g. AGENTS.md) that defines this agent's behavior. Injected into the system prompt at runtime.";
+
+export function PiLocalConfigFields({
+ isCreate,
+ values,
+ set,
+ config,
+ eff,
+ mark,
+}: AdapterConfigFieldsProps) {
+ return (
+ <Field label="Agent instructions file" hint={instructionsFileHint}>
+ <div className="flex items-center gap-2">
+ <DraftInput
+ value={
+ isCreate
+ ? values!.instructionsFilePath ?? ""
+ : eff(
+ "adapterConfig",
+ "instructionsFilePath",
+ String(config.instructionsFilePath ?? ""),
+ )
+ }
+ onCommit={(v) =>
+ isCreate
+ ? set!({ instructionsFilePath: v })
+ : mark("adapterConfig", "instructionsFilePath", v || undefined)
+ }
+ immediate
+ className={inputClass}
+ placeholder="/absolute/path/to/AGENTS.md"
+ />
+ <ChoosePathButton />
+ </div>
+ </Field>
+ );
+}
diff --git a/ui/src/adapters/pi-local/index.ts b/ui/src/adapters/pi-local/index.ts
new file mode 100644
index 0000000000..cfebf6698d
--- /dev/null
+++ b/ui/src/adapters/pi-local/index.ts
@@ -0,0 +1,12 @@
+import type { UIAdapterModule } from "../types";
+import { parsePiStdoutLine } from "@paperclipai/adapter-pi-local/ui";
+import { PiLocalConfigFields } from "./config-fields";
+import { buildPiLocalConfig } from "@paperclipai/adapter-pi-local/ui";
+
+export const piLocalUIAdapter: UIAdapterModule = {
+ type: "pi_local",
+ label: "Pi (local)",
+ parseStdoutLine: parsePiStdoutLine,
+ ConfigFields: PiLocalConfigFields,
+ buildAdapterConfig: buildPiLocalConfig,
+};
diff --git a/ui/src/adapters/registry.ts b/ui/src/adapters/registry.ts
index 2ce643f02a..f9e0080c11 100644
--- a/ui/src/adapters/registry.ts
+++ b/ui/src/adapters/registry.ts
@@ -3,12 +3,13 @@ import { claudeLocalUIAdapter } from "./claude-local";
import { codexLocalUIAdapter } from "./codex-local";
import { cursorLocalUIAdapter } from "./cursor";
import { openCodeLocalUIAdapter } from "./opencode-local";
+import { piLocalUIAdapter } from "./pi-local";
import { openClawUIAdapter } from "./openclaw";
import { processUIAdapter } from "./process";
import { httpUIAdapter } from "./http";
const adaptersByType = new Map<string, UIAdapterModule>(
- [claudeLocalUIAdapter, codexLocalUIAdapter, openCodeLocalUIAdapter, cursorLocalUIAdapter, openClawUIAdapter, processUIAdapter, httpUIAdapter].map((a) => [a.type, a]),
+ [claudeLocalUIAdapter, codexLocalUIAdapter, openCodeLocalUIAdapter, piLocalUIAdapter, cursorLocalUIAdapter, openClawUIAdapter, processUIAdapter, httpUIAdapter].map((a) => [a.type, a]),
);
export function getUIAdapter(type: string): UIAdapterModule {