refactor(pi): use native RPC CLI runtime

docs/agent-profile-schema.md

@@ -84,7 +84,8 @@ to one of these built-in driver integrations:
 - `claude`: Claude Code SDK
 - `opencode`: the host-installed OpenCode CLI; DevSpace probes its major version
   and uses the matching 1.x or 2.x protocol internally
-- `pi`: the installed Pi coding-agent SDK, one in-process session per DevSpace agent
+- `pi`: Pi's normal `--mode rpc` CLI process. DevSpace preserves Pi's native
+  auth, settings, extensions, skills, context files, and session store.
 - `acp`: generic Agent Client Protocol integration. Cursor, Copilot, and Grok
   are default provider instances using this driver; other ACP agents can be
   configured without adding a DevSpace driver.
@@ -94,8 +95,9 @@ as executables. Run their normal login/setup flows before using them; set
 `CODEX_COMMAND` when Codex is not on the normal PATH. OpenCode is discovered as
 `opencode`, and DevSpace automatically routes OpenCode 1.x and 2.x to their
 matching runtime implementations. OpenCode, Cursor, and Copilot runtimes are
-started and reused by the daemon internally, while Pi is embedded through its
-Node SDK.
+started and reused by the daemon internally. Pi is launched in RPC mode and
+uses its native persisted session file as DevSpace's continuation identity;
+`PI_COMMAND` (or a provider `command`) can select another Pi executable.
 
 ### `model`
 

docs/configuration.md

@@ -192,14 +192,14 @@ does not expand `$NAME` references in these values.
 All subagent providers accept `env`. The daemon inherits its startup
 environment, then overlays the provider's `env` without mutating the daemon's
 process environment. OpenCode receives that environment on its managed server
-process; embedded Pi scopes it to its provider requests and command execution.
+process; Pi receives it on its managed RPC process.
 
 The `opencode` driver runs `opencode --version` before creating its first
 runtime and automatically selects the OpenCode 1.x or 2.x protocol. Both major
 versions use the same provider instance and profile configuration; `opencode2`
 is not a separate driver.
 
-Codex, Claude, and ACP instances also accept `command`. OpenCode and Pi do not
+Codex, Claude, Pi, and ACP instances also accept `command`. OpenCode does not
 expose a command override. Cursor, Copilot, and Grok retain their built-in ACP
 commands when `command` is omitted. An arbitrary ACP instance declares its
 executable and may provide fixed startup arguments under `config.args`:
@@ -217,6 +217,12 @@ executable and may provide fixed startup arguments under `config.args`:
 `config.flavor` is reserved for the small built-in protocol quirks currently
 needed by `cursor`, `copilot`, and `grok`; generic ACP agents normally omit it.
 
+Pi runs as the normal CLI in `--mode rpc`, so user-installed extensions,
+skills, context files, auth, models, and settings load normally. Restricted
+DevSpace modes inject a sandbox extension and pin Pi's active built-in tools to
+the matching read-only/workspace-safe set; `full_access` leaves Pi's normal
+tool configuration untouched.
+
 Existing process-level overrides remain supported: `CODEX_COMMAND`,
 `CODEX_HOME`, `CLAUDE_COMMAND`, `CURSOR_COMMAND`, `COPILOT_COMMAND`,
 `GROK_COMMAND`, and `GROK_AGENT_PROFILE`. Provider configuration takes

src/local-agent-adapters.ts

@@ -27,7 +27,7 @@ import {
   PiLocalAgentDriver,
   extractPiFinalResponse,
   extractPiProviderError,
-  type PiSessionFactory,
+  type PiRpcFactory,
 } from "./local-agent-pi.js";
 import type { LocalAgentDriver } from "./local-agent-runtime.js";
 import { LocalAgentProviderRegistry } from "./local-agent-provider-registry.js";
@@ -39,7 +39,7 @@ export interface LocalAgentDriverOptions {
   subagents?: SubagentsConfig;
   claudeQueryFactory?: ClaudeQueryFactory;
   opencodeFactory?: OpencodeFactory;
-  piSessionFactory?: PiSessionFactory;
+  piRpcFactory?: PiRpcFactory;
 }
 
 export function createLocalAgentDrivers(
@@ -62,7 +62,7 @@ export function createLocalAgentProviderRegistry(
     .register("codex", ({ env }) => new CodexLocalAgentDriver(env))
     .register("claude", ({ env }) => new ClaudeLocalAgentDriver(options.claudeQueryFactory, env))
     .register("opencode", ({ env }) => new OpencodeLocalAgentDriver({ factory: options.opencodeFactory, env }))
-    .register("pi", ({ envOverrides }) => new PiLocalAgentDriver(options.piSessionFactory, envOverrides))
+    .register("pi", ({ env }) => new PiLocalAgentDriver(options.piRpcFactory, env))
     .register("acp", ({ instance, env }) => new AcpLocalAgentDriver({
       env,
       command: instance.command,

src/local-agent-availability.ts

@@ -53,7 +53,9 @@ function checkLocalAgentProviderAvailability(
     case "opencode":
       return commandAvailability(providerInstanceId, "opencode", providerEnv);
     case "pi":
-      return packageAvailability(providerInstanceId, "@earendil-works/pi-coding-agent");
+      return providerEnv.PI_COMMAND
+        ? commandAvailability(providerInstanceId, providerEnv.PI_COMMAND, providerEnv)
+        : packageAvailability(providerInstanceId, "@earendil-works/pi-coding-agent");
     case "acp": {
       const configured = config ? subagentProviderConfig(config, providerInstanceId) : undefined;
       const command = configured?.command

src/local-agent-config.test.ts

@@ -165,10 +165,15 @@ for (const id of ["opencode", "pi"] as const) {
     providers: [{ id, enabled: true, env: { HARNESS_ENV: id } }],
   });
   assert.equal(localAgentProviderEnvironment(embedded, id, {}).HARNESS_ENV, id);
-  assert.throws(
-    () => subagentsConfigSchema.parse({
-      enabled: true,
-      providers: [{ id, enabled: true, command: "/opt/bin/agent" }],
-    }),
-  );
 }
+assert.throws(
+  () => subagentsConfigSchema.parse({
+    enabled: true,
+    providers: [{ id: "opencode", enabled: true, command: "/opt/bin/agent" }],
+  }),
+);
+const piCommand = parseSubagentsConfig({
+  enabled: true,
+  providers: [{ id: "pi", enabled: true, command: "/opt/bin/pi" }],
+});
+assert.equal(localAgentProviderEnvironment(piCommand, "pi", {}).PI_COMMAND, "/opt/bin/pi");

src/local-agent-config.ts

@@ -53,7 +53,7 @@ const providerSchema = z.object({
     });
     return;
   }
-  if ((driver === "opencode" || driver === "pi") && provider.command !== undefined) {
+  if (driver === "opencode" && provider.command !== undefined) {
     context.addIssue({
       code: "custom",
       path: ["command"],
@@ -169,8 +169,8 @@ export function providerCommandVariable(driver: LocalAgentDriverKind): string |
   switch (driver) {
     case "codex": return "CODEX_COMMAND";
     case "claude": return "CLAUDE_COMMAND";
+    case "pi": return "PI_COMMAND";
     case "opencode":
-    case "pi":
     case "acp":
       return undefined;
   }

src/local-agent-pi-rpc.test.ts

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+import { PiRpcConnection } from "./local-agent-pi-rpc.js";
+
+const script = String.raw`
+let buffer = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buffer += chunk;
+  for (;;) {
+    const newline = buffer.indexOf("\n");
+    if (newline < 0) break;
+    const line = buffer.slice(0, newline);
+    buffer = buffer.slice(newline + 1);
+    if (!line) continue;
+    const request = JSON.parse(line);
+    process.stdout.write("not-json\n");
+    process.stdout.write(JSON.stringify({ type: "agent_start" }) + "\n");
+    process.stdout.write(JSON.stringify({
+      type: "response",
+      id: request.id,
+      command: request.type,
+      success: true,
+      data: { echoed: request.value },
+    }) + "\n");
+  }
+});
+`;
+
+const connection = PiRpcConnection.spawn({
+  command: process.execPath,
+  args: ["-e", script],
+  cwd: process.cwd(),
+  env: process.env,
+});
+const response = await connection.request({ type: "echo", value: "hello" });
+assert.deepEqual(response, { echoed: "hello" });
+assert.deepEqual(await connection.nextEvent(1_000), { type: "agent_start" });
+connection.close();

src/local-agent-pi-rpc.ts

@@ -0,0 +1,197 @@
+import { createRequire } from "node:module";
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import { terminateProcessTree } from "./process-platform.js";
+
+const require = createRequire(import.meta.url);
+const spawn = require("cross-spawn") as typeof import("node:child_process").spawn;
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const MAX_RECORD_CHARS = 8 * 1024 * 1024;
+
+export type PiRpcRecord = Record<string, unknown>;
+
+interface PendingRequest {
+  resolve(value: unknown): void;
+  reject(error: Error): void;
+  timer: NodeJS.Timeout;
+}
+
+export class PiRpcConnection {
+  private readonly pending = new Map<string, PendingRequest>();
+  private readonly queuedEvents: PiRpcRecord[] = [];
+  private readonly eventWaiters: Array<{
+    resolve(value: PiRpcRecord): void;
+    reject(error: Error): void;
+    timer?: NodeJS.Timeout;
+  }> = [];
+  private nextRequestId = 0;
+  private buffer = "";
+  private closed = false;
+  private failure?: Error;
+
+  private constructor(private readonly child: ChildProcessWithoutNullStreams) {
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk: string) => this.consume(chunk));
+    child.once("error", (error) => this.fail(error));
+    child.once("exit", (code) => {
+      if (!this.closed) this.fail(new Error(`Pi RPC process exited with code ${code}.`));
+    });
+  }
+
+  static spawn(input: {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+  }): PiRpcConnection {
+    const detached = process.platform !== "win32";
+    const child = spawn(input.command, input.args, {
+      cwd: input.cwd,
+      env: input.env,
+      stdio: ["pipe", "pipe", "pipe"],
+      detached,
+      windowsHide: true,
+    });
+    if (!child.stdin || !child.stdout || !child.stderr) {
+      throw new Error("Pi RPC process did not expose stdio pipes.");
+    }
+    return new PiRpcConnection(child as ChildProcessWithoutNullStreams);
+  }
+
+  async request(record: PiRpcRecord, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS): Promise<unknown> {
+    this.assertOpen();
+    const id = `devspace-${++this.nextRequestId}`;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Pi RPC ${String(record.type ?? "request")} timed out after ${timeoutMs}ms.`));
+      }, timeoutMs);
+      timer.unref();
+      this.pending.set(id, { resolve, reject, timer });
+      this.write({ ...record, id }).catch((error) => {
+        const pending = this.pending.get(id);
+        if (!pending) return;
+        this.pending.delete(id);
+        clearTimeout(pending.timer);
+        pending.reject(error);
+      });
+    });
+  }
+
+  async send(record: PiRpcRecord): Promise<void> {
+    this.assertOpen();
+    await this.write(record);
+  }
+
+  async nextEvent(timeoutMs?: number): Promise<PiRpcRecord | undefined> {
+    this.assertOpen();
+    const queued = this.queuedEvents.shift();
+    if (queued) return queued;
+    return new Promise((resolve, reject) => {
+      const waiter: (typeof this.eventWaiters)[number] = {
+        resolve: (value) => {
+          if (waiter.timer) clearTimeout(waiter.timer);
+          resolve(value);
+        },
+        reject: (error) => {
+          if (waiter.timer) clearTimeout(waiter.timer);
+          reject(error);
+        },
+      };
+      if (timeoutMs !== undefined) {
+        waiter.timer = setTimeout(() => {
+          const index = this.eventWaiters.indexOf(waiter);
+          if (index >= 0) this.eventWaiters.splice(index, 1);
+          resolve(undefined);
+        }, timeoutMs);
+        waiter.timer.unref();
+      }
+      this.eventWaiters.push(waiter);
+    });
+  }
+
+  isAlive(): boolean {
+    return !this.closed && !this.failure && this.child.exitCode === null;
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    const detached = process.platform !== "win32";
+    terminateProcessTree(this.child, "SIGTERM", detached);
+    this.fail(new Error("Pi RPC process closed."));
+  }
+
+  private async write(record: PiRpcRecord): Promise<void> {
+    const line = `${JSON.stringify(record)}\n`;
+    await new Promise<void>((resolve, reject) => {
+      this.child.stdin.write(line, (error) => error ? reject(error) : resolve());
+    });
+  }
+
+  private consume(chunk: string): void {
+    this.buffer += chunk;
+    if (this.buffer.length > MAX_RECORD_CHARS && !this.buffer.includes("\n")) {
+      this.buffer = "";
+      return;
+    }
+    for (;;) {
+      const newline = this.buffer.indexOf("\n");
+      if (newline < 0) return;
+      let line = this.buffer.slice(0, newline);
+      this.buffer = this.buffer.slice(newline + 1);
+      if (line.endsWith("\r")) line = line.slice(0, -1);
+      if (!line.trim()) continue;
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+      this.route(parsed as PiRpcRecord);
+    }
+  }
+
+  private route(record: PiRpcRecord): void {
+    if (record.type === "response" && typeof record.id === "string") {
+      const pending = this.pending.get(record.id);
+      if (pending) {
+        this.pending.delete(record.id);
+        clearTimeout(pending.timer);
+        if (record.success === true) pending.resolve(record.data);
+        else pending.reject(new Error(String(record.error ?? `Pi RPC ${String(record.command)} failed.`)));
+        return;
+      }
+    }
+    const waiter = this.eventWaiters.shift();
+    if (waiter) waiter.resolve(record);
+    else this.queuedEvents.push(record);
+  }
+
+  private assertOpen(): void {
+    if (this.failure) throw this.failure;
+    if (this.closed) throw new Error("Pi RPC process is closed.");
+  }
+
+  private fail(error: Error): void {
+    if (!this.failure) this.failure = error;
+    for (const [id, pending] of this.pending) {
+      this.pending.delete(id);
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    for (const waiter of this.eventWaiters.splice(0)) waiter.reject(error);
+  }
+}
+
+export function piRecordString(value: unknown, key: string): string | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const field = (value as Record<string, unknown>)[key];
+  return typeof field === "string" ? field : undefined;
+}
+
+export function parsePiModelSlug(model: string): { provider: string; modelId: string } | undefined {
+  const separator = model.indexOf("/");
+  if (separator <= 0 || separator === model.length - 1) return undefined;
+  return { provider: model.slice(0, separator), modelId: model.slice(separator + 1) };
+}