docs(runtime): separate pi dependency boundary

README.md

@@ -185,7 +185,7 @@ src/
 | `scripts/` | Build, release, and packaging Node scripts. |
 | `landing/` | Marketing site (Next.js). Has its own `landing/public/screenshots/`, separate from `docs/screenshots/`. |
 | `AgentCompany-Rust/` | Exploratory Rust port; see section below. |
-| `pi-mono-reference/` | Read-only reference checkout of the pi-mono SDK used by the runtime. |
+| `pi-mono-reference/` | Local reference snapshot only. Shipping runtime source of truth is the pinned `@mariozechner/*` npm dependencies in root `package.json`. |
 
 ---
 

src/main/agent-runtime/agent-event-projection.ts

@@ -7,8 +7,8 @@
  * types are added here; the bridge pipes the result into its run-log
  * stream.
  *
- * Reference: pi-mono-reference/packages/agent/src/types.ts `AgentEvent`
- * union is the canonical shape we project.
+ * The `@mariozechner/pi-agent-core` `AgentEvent` union is the
+ * canonical shape we project.
  */
 
 export type AgentEventLogChunk = { stream: "stdout" | "stderr"; chunk: string };

src/main/connector-definitions/apikey.ts

@@ -1,8 +1,8 @@
 /**
  * API-key pi-mono connectors.
  *
- * Each entry maps to a pi-ai `KnownProvider` (see
- * `pi-mono-reference/packages/ai/src/env-api-keys.ts`) — except for the two
+ * Each entry maps to a pi-ai `KnownProvider` from the pinned
+ * `@mariozechner/pi-ai` runtime, except for the two
  * Fireworks entries, which are resolved locally in `src/main/model-resolver.ts`.
  *
  * `envKey` is the standard environment variable pi-mono reads when no

src/main/connector-definitions/cloud.ts

@@ -4,7 +4,7 @@
  * Cloud providers have bespoke credential discovery — multi-variable AWS /
  * Azure setups, or gcloud Application Default Credentials for Vertex. The
  * `auth.type` marker tells the credential resolver which discovery path to
- * run (see `pi-mono-reference/packages/ai/src/env-api-keys.ts`).
+ * run in the pinned `@mariozechner/pi-ai` runtime.
  */
 
 import type { ConnectorDefinition } from "../connector-definitions";

src/main/connector-definitions/oauth.ts

@@ -1,8 +1,8 @@
 /**
  * OAuth-based pi-mono connectors.
  *
- * Each entry targets one of the five built-in pi-ai OAuth providers
- * (see `pi-mono-reference/packages/ai/src/utils/oauth/index.ts`). The
+ * Each entry targets one of the five built-in OAuth providers from the
+ * pinned `@mariozechner/pi-ai` runtime. The
  * runtime opens the provider's browser auth flow, stores the refreshed
  * token in the `credentials` table, and passes it as the API key when
  * invoking pi-ai.

src/main/worker/runtime/pi-hook-contract.ts

@@ -2,7 +2,7 @@
  * Compile-time contract between local hook implementations and
  * `pi-agent-core` callback signatures.
  *
- * B1 pinned `@mariozechner/pi-agent-core` to 0.67.68 (in-tree reference)
+ * Root `package.json` pins `@mariozechner/pi-agent-core` to 0.67.68
  * while our worker wires local hooks — `beforeToolCall`, `afterToolCall`,
  * `transformContext` — into the pi Agent constructor. Those hooks carry
  * deep structural coupling: pi decides the context shape passed in and

tests/unit/pi-runtime-dependency-contract.test.ts

@@ -0,0 +1,28 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+type PackageJson = {
+  dependencies?: Record<string, string>;
+};
+
+const PI_RUNTIME_PACKAGES = [
+  "@mariozechner/pi-agent-core",
+  "@mariozechner/pi-ai",
+  "@mariozechner/pi-coding-agent",
+] as const;
+
+function readRootPackage(): PackageJson {
+  return JSON.parse(readFileSync(join(process.cwd(), "package.json"), "utf8")) as PackageJson;
+}
+
+describe("pi runtime dependency contract", () => {
+  it("keeps the shipping pi runtime on exact npm package pins", () => {
+    const dependencies = readRootPackage().dependencies ?? {};
+
+    for (const packageName of PI_RUNTIME_PACKAGES) {
+      expect(dependencies[packageName]).toBe("0.67.68");
+      expect(dependencies[packageName]).toMatch(/^\d+\.\d+\.\d+$/);
+    }
+  });
+});