Skip to content

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

Improve Pi adapter diagnostics

Dotta5814249ea904
diff --git a/packages/adapters/pi-local/src/server/test.ts b/packages/adapters/pi-local/src/server/test.ts
index cf8fa80adf..57ba14d627 100644
--- a/packages/adapters/pi-local/src/server/test.ts
+++ b/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.",
+ ),
+ );
}
}
diff --git a/server/src/__tests__/pi-local-adapter-environment.test.ts b/server/src/__tests__/pi-local-adapter-environment.test.ts
new file mode 100644
index 0000000000..266e59eece
--- /dev/null
+++ b/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 });
+ });
+});