@alphacoder-v0/pi-loops 0.17.5 → 0.17.6

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to pi-loops are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow SemVer.
 
+## [0.17.6] - 2026-09-14
+
+### Added
+- **A pi version floor, and a refusal that names it.** pi-loops needs pi ≥ 0.84.3 — found by
+  type-checking `src/` against older releases: 0.80.8 fails on `ctx.thinkingLevel` and
+  `session_compact_failed`, 0.84.3 passes clean — and nothing said so. `peerDependencies` is `*`
+  because pi's docs ask for that and pi installs with `--legacy-peer-deps`, which reads no range
+  anyway; so on an older pi the first sign was a link error, "does not provide an export named
+  ModelRuntime", from which nobody could read "your pi is too old". The manifest now points at
+  `src/extension-entry.ts`, which imports nothing pi has not exported for a long time, reads
+  pi's `VERSION` against `PI_MIN_VERSION` in `src/pi-floor.ts`, and only then imports the
+  extension; an old pi prints `pi-loops needs pi 0.84.3 or newer and this is pi 0.80.8: upgrade pi`.
+  Both READMEs state the floor and a test keeps them, the manifest and the code on one number.
+
 ## [0.17.5] - 2026-09-14
 
 ### Fixed

package/README.md

@@ -29,15 +29,16 @@ reaches you is what changed rather than everything that is there.
 
 ## Install
 
-Node ≥ 22.6 (pi loads the TypeScript sources directly) and a pi to load it into — 0.85 is what this
-is tested against, and older ones are untested rather than refused. Nothing else: pi-loops has no
+Node ≥ 22.6 (pi loads the TypeScript sources directly) and pi ≥ 0.84.3 to load it into — 0.85 is
+what this is tested against, and an older pi is refused at load with a line that names the version
+it needs, rather than a link error naming one missing export. Nothing else: pi-loops has no
 runtime dependencies. What you do want first is a provider you can actually talk to — run `pi`, send
 one message, make sure you get an answer. pi-loops runs sub-agents while you are not watching, and
 the first sign of credentials that do not work should not be an empty inbox tomorrow morning.
 
 ```bash
 pi install npm:@alphacoder-v0/pi-loops                      # from npm, following new releases
-pi install git:github.com/alphacoder-v0/pi-loops@v0.17.5    # or from GitHub, at a pinned tag
+pi install git:github.com/alphacoder-v0/pi-loops@v0.17.6    # or from GitHub, at a pinned tag
 pi install /path/to/pi-loops                                # or a local checkout — `pi install .` in this repo
 pi -e /path/to/pi-loops                                     # or none of them: try it for one run, installing nothing
 ```

package/README.zh-CN.md

@@ -37,7 +37,7 @@ pi-loops host status                  # 看一眼没有 pi 开着时在跑的自
 
 ### 1. 先确认前提
 
-Node ≥ 22.6（pi 直接加载 TypeScript 源码），一个新到带得动扩展 API 的 pi（没有版本下限可查：`peerDependencies` 写的是 `*`，少了哪个 API 是加载时当场报错），以及**一个真的能说上话的 provider**——先跑一次 `pi`，发一句，确认有回答。pi-loops 会在你不看着的时候替你跑子代理；凭据没配好，别等到第二天早上看见空 inbox 才知道。
+Node ≥ 22.6（pi 直接加载 TypeScript 源码），pi ≥ 0.84.3（实际在 0.85 上测；更老的 pi 会在加载时被明确拒绝，报一句写明所需版本的话，而不是一个缺导出的链接错误），以及**一个真的能说上话的 provider**——先跑一次 `pi`，发一句，确认有回答。pi-loops 会在你不看着的时候替你跑子代理；凭据没配好，别等到第二天早上看见空 inbox 才知道。
 
 pi-loops 自己没有任何运行时依赖。
 
@@ -45,7 +45,7 @@ pi-loops 自己没有任何运行时依赖。
 
 ```bash
 pi install npm:@alphacoder-v0/pi-loops                      # 从 npm 装，跟着新版本走
-pi install git:github.com/alphacoder-v0/pi-loops@v0.17.5    # 或者从 GitHub 装，钉住一个 tag
+pi install git:github.com/alphacoder-v0/pi-loops@v0.17.6    # 或者从 GitHub 装，钉住一个 tag
 pi install /path/to/pi-loops                                # 或者本地检出；本仓库里就是 pi install .
 ```
 
@@ -515,7 +515,8 @@ Output protocol (mandatory):
 ## 代码结构
 
 ```
-src/pi-loops.ts             扩展入口：命令、工具、生命周期、状态栏角标、面板
+src/extension-entry.ts      pi 加载的入口：先查 pi 版本（src/pi-floor.ts），够了再导入 src/pi-loops.ts
+src/pi-loops.ts             扩展本体：命令、工具、生命周期、状态栏角标、面板
 src/cli.ts                  `pi-loops`：会话入口（网页或终端）与 sessions / inspect / export / import / host
 src/cli-entry.mjs           bin
 src/ts-entry.mjs            .mjs 入口怎么加载本包的 .ts：Node 自己剥类型，装在 node_modules 下就借 pi 的 jiti

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphacoder-v0/pi-loops",
-  "version": "0.17.5",
+  "version": "0.17.6",
   "description": "An automation layer for pi: cron + stateful loops with a triage inbox, maker/checker verification, dynamic triggers, MCP notifications and tools, lifecycle hooks, session archives. A non-invasive pi extension.",
   "type": "module",
   "license": "MIT",
@@ -59,7 +59,7 @@
   "pi": {
     "image": "https://raw.githubusercontent.com/alphacoder-v0/pi-loops/main/docs/screenshot.png",
     "extensions": [
-      "./src/pi-loops.ts"
+      "./src/extension-entry.ts"
     ],
     "skills": [
       "./skills"

package/src/extension-entry.ts

@@ -0,0 +1,24 @@
+/**
+ * What pi loads (`pi.extensions` in package.json): a version check, then the extension.
+ *
+ * The check cannot sit in `src/pi-loops.ts`. That file and the modules under it import names pi
+ * did not always export (`ModelRuntime`, `readStoredCredential`, `createSyntheticSourceInfo`) and
+ * subscribe to events it did not always emit. ESM links a whole import graph before running a line
+ * of it, so on an older pi the failure is a link error naming one export — "does not provide an
+ * export named ModelRuntime" — and nothing in it says "your pi is too old". This file imports only
+ * what every pi has exported for a long time, reads the version, and imports the rest afterwards,
+ * so what an old pi prints is the sentence that says which pi it needs.
+ *
+ * A namespace import on purpose: a name missing from an old pi is then `undefined` rather than a
+ * link error, which is exactly the case the check exists for.
+ */
+import * as sdk from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { piTooOld } from "./pi-floor.ts";
+
+export default async function (pi: ExtensionAPI) {
+	const refusal = piTooOld(sdk.VERSION);
+	if (refusal) throw new Error(refusal);
+	const { default: piLoops } = await import("./pi-loops.ts");
+	return piLoops(pi);
+}

package/src/pi-floor.ts

@@ -0,0 +1,37 @@
+/**
+ * The oldest pi this extension loads into. `src/extension-entry.ts` reads it before anything else
+ * is imported, both READMEs state it, and `test/pi-floor.test.ts` keeps the three the same.
+ *
+ * 0.84.3 is where the API this code is written against became complete: `session_compact_failed`
+ * arrived there, `ModelRuntime` and `readStoredCredential` in 0.80.8, `ctx.thinkingLevel` in
+ * between. It was found by type-checking `src/` against older releases rather than by reading
+ * changelogs — 0.80.8 fails on the two newest names, 0.84.3 passes clean — and it is the version
+ * to re-check the same way when a newer name is used. Nothing enforces it at install time: pi
+ * installs packages with `--legacy-peer-deps`, so `peerDependencies` stays `*` as pi's docs ask
+ * and the range there would not be read anyway.
+ */
+export const PI_MIN_VERSION = "0.84.3";
+
+/** `[major, minor, patch]`, or undefined for anything that does not start `N.N.N` (a `v` in front is fine). */
+function parse(version: string): [number, number, number] | undefined {
+	const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+	return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : undefined;
+}
+
+/**
+ * Why this pi cannot load pi-loops, as the one sentence pi prints after "Failed to load extension",
+ * or undefined when it can. A pi that reports no version is refused as well: every pi new enough
+ * to load this exports `VERSION`, so a missing one is an old one, not an unknown one.
+ */
+export function piTooOld(version: string | undefined, min: string = PI_MIN_VERSION): string | undefined {
+	const have = version === undefined ? undefined : parse(version);
+	const need = parse(min);
+	if (!need) throw new Error(`PI_MIN_VERSION is not a version: ${JSON.stringify(min)}`);
+	const upgrade = "upgrade pi (`pi update`, or `npm i -g @earendil-works/pi-coding-agent`)";
+	if (!have) return `pi-loops needs pi ${min} or newer and this pi reports ${version === undefined ? "no version" : `version ${JSON.stringify(version)}`}: ${upgrade}`;
+	for (let i = 0; i < 3; i++) {
+		if (have[i] > need[i]) return undefined;
+		if (have[i] < need[i]) return `pi-loops needs pi ${min} or newer and this is pi ${version}: ${upgrade}`;
+	}
+	return undefined;
+}