Improve Pi adapter diagnostics

packages/adapters/pi-local/src/server/test.ts

@@ -51,6 +51,26 @@ function normalizeEnv(input: unknown): Record<string, string> {
 
 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;
+const PI_STALE_PACKAGE_RE = /pi-driver|npm:\s*pi-driver/i;
+
+function buildPiModelDiscoveryFailureCheck(message: string): AdapterEnvironmentCheck {
+  if (PI_STALE_PACKAGE_RE.test(message)) {
+    return {
+      code: "pi_package_install_failed",
+      level: "warn",
+      message: "Pi startup failed while installing configured package `npm:pi-driver`.",
+      detail: message,
+      hint: "Remove `npm:pi-driver` from ~/.pi/agent/settings.json or set adapter env HOME to a clean Pi profile, then retry `pi --list-models`.",
+    };
+  }
+
+  return {
+    code: "pi_models_discovery_failed",
+    level: "warn",
+    message,
+    hint: "Run `pi --list-models` manually to verify provider auth and config.",
+  };
+}
 
 export async function testEnvironment(
   ctx: AdapterEnvironmentTestContext,
@@ -130,12 +150,11 @@ export async function testEnvironment(
         });
       }
     } 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.",
-      });
+      checks.push(
+        buildPiModelDiscoveryFailureCheck(
+          err instanceof Error ? err.message : "Pi model discovery failed.",
+        ),
+      );
     }
   }
 

server/src/__tests__/pi-local-adapter-environment.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { testEnvironment } from "@paperclipai/adapter-pi-local/server";
+
+async function writeFakePiCommand(binDir: string, mode: "success" | "stale-package"): Promise<void> {
+  const commandPath = path.join(binDir, "pi");
+  const script =
+    mode === "success"
+      ? `#!/usr/bin/env node
+if (process.argv.includes("--list-models")) {
+  console.log("provider  model");
+  console.log("openai    gpt-4.1-mini");
+  process.exit(0);
+}
+console.log(JSON.stringify({ type: "session", version: 3, id: "session-1", timestamp: new Date().toISOString(), cwd: process.cwd() }));
+console.log(JSON.stringify({ type: "agent_start" }));
+console.log(JSON.stringify({ type: "turn_start" }));
+console.log(JSON.stringify({
+  type: "turn_end",
+  message: {
+    role: "assistant",
+    content: [{ type: "text", text: "hello" }],
+    usage: { input: 1, output: 1, cacheRead: 0, cost: { total: 0 } }
+  },
+  toolResults: []
+}));
+`
+      : `#!/usr/bin/env node
+if (process.argv.includes("--list-models")) {
+  console.error("npm error 404 'pi-driver@*' is not in this registry.");
+  process.exit(1);
+}
+process.exit(1);
+`;
+  await fs.writeFile(commandPath, script, "utf8");
+  await fs.chmod(commandPath, 0o755);
+}
+
+describe("pi_local environment diagnostics", () => {
+  it("passes a hello probe when model discovery and execution succeed", async () => {
+    const root = path.join(
+      os.tmpdir(),
+      `paperclip-pi-local-probe-${Date.now()}-${Math.random().toString(16).slice(2)}`,
+    );
+    const binDir = path.join(root, "bin");
+    const cwd = path.join(root, "workspace");
+    await fs.mkdir(binDir, { recursive: true });
+    await fs.mkdir(cwd, { recursive: true });
+    await writeFakePiCommand(binDir, "success");
+
+    const result = await testEnvironment({
+      companyId: "company-1",
+      adapterType: "pi_local",
+      config: {
+        command: "pi",
+        cwd,
+        model: "openai/gpt-4.1-mini",
+        env: {
+          OPENAI_API_KEY: "test-key",
+          PATH: `${binDir}${path.delimiter}${process.env.PATH ?? ""}`,
+        },
+      },
+    });
+
+    expect(result.status).toBe("pass");
+    expect(result.checks.some((check) => check.code === "pi_models_discovered")).toBe(true);
+    expect(result.checks.some((check) => check.code === "pi_hello_probe_passed")).toBe(true);
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("surfaces stale configured package installs with a targeted hint", async () => {
+    const root = path.join(
+      os.tmpdir(),
+      `paperclip-pi-local-stale-package-${Date.now()}-${Math.random().toString(16).slice(2)}`,
+    );
+    const binDir = path.join(root, "bin");
+    const cwd = path.join(root, "workspace");
+    await fs.mkdir(binDir, { recursive: true });
+    await fs.mkdir(cwd, { recursive: true });
+    await writeFakePiCommand(binDir, "stale-package");
+
+    const result = await testEnvironment({
+      companyId: "company-1",
+      adapterType: "pi_local",
+      config: {
+        command: "pi",
+        cwd,
+        env: {
+          PATH: `${binDir}${path.delimiter}${process.env.PATH ?? ""}`,
+        },
+      },
+    });
+
+    const stalePackageCheck = result.checks.find((check) => check.code === "pi_package_install_failed");
+    expect(stalePackageCheck?.level).toBe("warn");
+    expect(stalePackageCheck?.hint).toContain("Remove `npm:pi-driver`");
+    await fs.rm(root, { recursive: true, force: true });
+  });
+});