From da34f41798128321379d128b014c52a2c027becc Mon Sep 17 00:00:00 2001 From: Joakim Persson Date: Sat, 9 May 2026 21:20:53 +0200 Subject: [PATCH] AGENTS: note that extension imports are coupled to host pi version The 2026-05-09 rename of extension imports from @mariozechner/pi-* to @earendil-works/pi-* surfaced a sequencing failure: extensions are loaded by jiti at runtime, and their import statements resolve against whatever node_modules the running pi binary bundles. A host pi still on @mariozechner-bundle 0.73.1 cannot resolve @earendil-works/* and fails extension load with 'Cannot find module'. Bun build --external '*' does NOT catch this \u2014 it only validates the bundle shape, not runtime module resolution. The actual gate is running pi against the extensions on the target system. Codify the rule in Conventions so future renames (or major-version deps bumps) sequence the host upgrade alongside the import change. --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index efec9cf..4ab8fa6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,6 +33,8 @@ LICENSE # MIT. ## Conventions +- **Extension imports are coupled to the running pi version.** Extensions are loaded by jiti at runtime; their `import { ... } from "@earendil-works/pi-*"` statements resolve against whatever node_modules the running `pi` binary has bundled. **When extension imports change package names** (e.g. the 2026-05-09 rename from `@mariozechner/pi-*` to `@earendil-works/pi-*`), the host pi MUST be upgraded to the matching version *before or at the same time as* the import-rename push, otherwise users on the older pi see `Cannot find module '@earendil-works/...'` at extension load. Container path: bump `PI_VERSION` build-arg in opencode-devbox. Host path: `npm install -g @earendil-works/pi-coding-agent` (and `brew uninstall pi-coding-agent` if previously installed via brew at the old name). `bun build --external '*'` does NOT catch this regression — it only validates the bundle shape, not module resolution against the runtime pi's deps. Real test: run `pi --version` on the target system after the rename. + - **One `.ts` file per extension**, flat under `extensions/`. If an extension grows multiple files, use a subdirectory with an `index.ts` entry point — pi's auto-discovery handles both shapes.