From f90fb037f932ed18a326678218f48e0ea09389ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=9B=B7=E7=94=B5=E8=8A=BD=E8=A1=A3?= Date: Wed, 22 Apr 2026 14:39:19 -0400 Subject: [PATCH] docs(runtime): separate pi dependency boundary --- README.md | 2 +- .../agent-runtime/agent-event-projection.ts | 4 +-- src/main/connector-definitions/apikey.ts | 4 +-- src/main/connector-definitions/cloud.ts | 2 +- src/main/connector-definitions/oauth.ts | 4 +-- src/main/worker/runtime/pi-hook-contract.ts | 2 +- .../pi-runtime-dependency-contract.test.ts | 28 +++++++++++++++++++ 7 files changed, 37 insertions(+), 9 deletions(-) create mode 100644 tests/unit/pi-runtime-dependency-contract.test.ts diff --git a/README.md b/README.md index e68d25ff..869c9c69 100644 --- a/README.md +++ b/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`. | --- diff --git a/src/main/agent-runtime/agent-event-projection.ts b/src/main/agent-runtime/agent-event-projection.ts index 1740581c..ddb8003f 100644 --- a/src/main/agent-runtime/agent-event-projection.ts +++ b/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 }; diff --git a/src/main/connector-definitions/apikey.ts b/src/main/connector-definitions/apikey.ts index cda1a0fd..2d6620c3 100644 --- a/src/main/connector-definitions/apikey.ts +++ b/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 diff --git a/src/main/connector-definitions/cloud.ts b/src/main/connector-definitions/cloud.ts index 27ea9669..1661091d 100644 --- a/src/main/connector-definitions/cloud.ts +++ b/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"; diff --git a/src/main/connector-definitions/oauth.ts b/src/main/connector-definitions/oauth.ts index 80063ff0..a19b6bb3 100644 --- a/src/main/connector-definitions/oauth.ts +++ b/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. diff --git a/src/main/worker/runtime/pi-hook-contract.ts b/src/main/worker/runtime/pi-hook-contract.ts index 3cbfbbd6..681d18db 100644 --- a/src/main/worker/runtime/pi-hook-contract.ts +++ b/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 diff --git a/tests/unit/pi-runtime-dependency-contract.test.ts b/tests/unit/pi-runtime-dependency-contract.test.ts new file mode 100644 index 00000000..f9145fdb --- /dev/null +++ b/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; +}; + +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+$/); + } + }); +});