@alphacoder-v0/pi-loops 0.17.4 → 0.17.6

package/CHANGELOG.md

@@ -3,6 +3,41 @@
 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
+- **`/pi-loops install-launcher` ignored `--dir`, and asked about a directory it was not going to
+  use.** Found by following the README, which says either route takes `--dir <dir>`: the
+  command-line `install-launcher` did, the one inside pi called `installLauncher(undefined)` and
+  showed a confirmation naming `~/.local/bin` whatever it was about to do. Answering yes to that
+  question, with a launcher you already rely on in `~/.local/bin`, replaced it. The slash command now
+  reads `--dir` (quoted, or starting with a `~` that no shell expanded on the way in) and the
+  question names the absolute directory that will be written, which is then the one written — and says when that directory is not on your PATH instead
+  of promising that `pi-loops` will work from anywhere. With nowhere to write it asks nothing and
+  prints the refusal, which already explains `--dir`. The menu shows the flag.
+- **The browser window used `~/.pi/agent/loops` even when pi's agent directory was somewhere else.**
+  `PI_CODING_AGENT_DIR` moves everything pi keeps and the extension follows it; the launcher and
+  `web.mjs` did not. With the variable set, the page's token, its automation panel and the
+  `ui.json` holding the model you pick all lived in the default directory while the session behind
+  the page wrote to the moved one — so the page opened on another setup's remembered model (a
+  `Model "…" not found` warning, in the case that found it) and picking a model overwrote that
+  setup's choice. Both now resolve the directory the way the extension does, `~` included.
+  `PI_LOOPS_DIR` and `--loops-dir` still come first.
+
 ## [0.17.4] - 2026-09-14
 
 ### Added

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.4    # 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.4    # 或者从 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.4",
+  "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/cli.ts

@@ -583,6 +583,40 @@ export function cliRoute(argv: string[]): "launch" | "subcommand" {
 	return "subcommand";
 }
 
+/**
+ * Where the launcher goes: `--dir` if given, otherwise the first of ~/.local/bin and /usr/local/bin
+ * that is on PATH. One function, because the question asked before writing and the write itself
+ * have to name the same directory.
+ */
+export function launcherTarget(dir: string | undefined, pathEnv: string = process.env.PATH ?? ""): string | undefined {
+	if (dir) return path.resolve(dir);
+	return [path.join(os.homedir(), ".local", "bin"), "/usr/local/bin"].find((d) => isOnPath(d, pathEnv));
+}
+
+function isOnPath(dir: string, pathEnv: string = process.env.PATH ?? ""): boolean {
+	return pathEnv.split(path.delimiter).filter(Boolean).some((p) => path.resolve(p) === path.resolve(dir));
+}
+
+/**
+ * `/pi-loops install-launcher [--dir <dir>]`: the command line's `install-launcher`, asked first,
+ * because inside pi it is a click away from replacing a launcher you already have. The question
+ * names the directory that will be written and nothing else. Resolves undefined when the answer
+ * is no; with nowhere to write there is nothing to ask, and the refusal says why.
+ */
+export async function installLauncherWithConfirm(args: string[], confirm: (title: string, body: string) => Promise<boolean>, out: (line: string) => void): Promise<number | undefined> {
+	const flag = parseCliArgs(["install-launcher", ...args]).flags.get("dir");
+	// No shell has expanded `~` on the way here, so it is expanded now or becomes a directory named `~`.
+	const dir = typeof flag === "string" ? flag.replace(/^~(?=$|\/)/, os.homedir()) : undefined;
+	const target = launcherTarget(dir);
+	if (!target) return installLauncher(undefined, out);
+	const reach = isOnPath(target) ? ["Afterwards `pi-loops` starts a session from any directory."] : [`${target} is not on your PATH, so \`pi-loops\` will not be found until it is.`];
+	const ok = await confirm("Put `pi-loops` on your PATH?", [`This writes a launcher into ${target}.`, "", "It is a two-line shell script that runs this package with this node.", ...reach].join("\n"));
+	if (!ok) return undefined;
+	// The absolute directory the question named, not the flag again: resolving a relative --dir a
+	// second time, after the dialog, would follow a working directory that may have moved meanwhile.
+	return installLauncher(target, out);
+}
+
 /**
  * `pi install` puts this package under pi's managed directory rather than on your PATH, so the
  * command that is supposed to start your sessions is reachable only by absolute path. This writes
@@ -590,14 +624,13 @@ export function cliRoute(argv: string[]): "launch" | "subcommand" {
  * that fixes it without asking you to publish or install anything else.
  */
 export async function installLauncher(dir: string | undefined, out: (line: string) => void): Promise<number> {
-	const onPath = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean).map((p) => path.resolve(p));
-	const target = dir ? path.resolve(dir) : [path.join(os.homedir(), ".local", "bin"), "/usr/local/bin"].find((d) => onPath.includes(path.resolve(d)));
+	const target = launcherTarget(dir);
 	if (!target) {
 		out("no directory to install into: neither ~/.local/bin nor /usr/local/bin is on your PATH.");
 		out("pass one with --dir <dir>, or add ~/.local/bin to PATH and run this again.");
 		return 1;
 	}
-	if (dir && !onPath.includes(target)) out(`note: ${target} is not on your PATH, so the command will not be found there yet`);
+	if (dir && !isOnPath(target)) out(`note: ${target} is not on your PATH, so the command will not be found there yet`);
 	const entry = path.join(path.dirname(fileURLToPath(import.meta.url)), "cli-entry.mjs");
 	const file = path.join(target, "pi-loops");
 	// A launcher rather than a symlink: it survives the package moving, and it names the node that
@@ -641,13 +674,17 @@ async function launch(argv: string[], out: (line: string) => void): Promise<numb
 	return runChild(process.execPath, [web, ...ours.filter((a) => a !== "--web" && a !== "--tui"), ...(withDefaults.length ? ["--", ...withDefaults] : [])]);
 }
 
-/** Where the data lives for this run: the flag, then the environment, then the default. */
-function loopsDir(ours: string[]): string {
+/**
+ * Where the data lives for this run: the flag, then the environment, then the default — the default
+ * being the extension's own (`loops` under pi's agent directory, which `PI_CODING_AGENT_DIR` moves),
+ * so the window reads what the session behind it writes.
+ */
+export function loopsDir(ours: string[]): string {
 	const at = ours.indexOf("--loops-dir");
 	if (at !== -1 && ours[at + 1]) return ours[at + 1];
 	const eq = ours.find((a) => a.startsWith("--loops-dir="));
 	if (eq) return eq.slice("--loops-dir=".length);
-	return process.env.PI_LOOPS_DIR || path.join(os.homedir(), ".pi", "agent", "loops");
+	return process.env.PI_LOOPS_DIR || defaultLoopsDir(getAgentDir());
 }
 
 /**

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;
+}

package/src/pi-loops.ts

@@ -18,7 +18,7 @@ import { ProjectTrustStore, VERSION as PI_VERSION, getAgentDir, readStoredCreden
 import { ARCHIVE_EXT, defaultExportPath, exportSession, importSession } from "./archive.ts";
 import { Box, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { parseAddArgs, parseSetArgs, splitCommand } from "./args.ts";
+import { parseAddArgs, parseSetArgs, splitCommand, tokenize } from "./args.ts";
 import { envFlag, loadConfig } from "./config.ts";
 import { GOAL_ENTRY, type GoalAction, type GoalState, MAX_CONTINUATIONS, applyDecision, branchMovedSince, continuationPrompt, evaluatorPrompt, latestGoal, newGoal, parseDecision, pauseFor, transcriptFromMessages } from "./goal.ts";
 import { withinProject } from "./presence.ts";
@@ -32,7 +32,7 @@ import { McpSource, PI_BUILTIN_TOOL_NAMES, type McpServerConfig, type McpToolDef
 import { capRedacted, previewRedacted, redact } from "./redact.ts";
 import { shouldEmitSnapshot, snapshotFingerprint } from "./snapshot.ts";
 import { type ShareMessage, renderShare, shareSummary } from "./share.ts";
-import { installLauncher } from "./cli.ts";
+import { installLauncherWithConfirm } from "./cli.ts";
 import { createHash } from "node:crypto";
 import { computeDue, computeNext, formatLocal, formatSchedule, localOffset, parseSchedule, stamp } from "./schedule.ts";
 import { applyJobEdit } from "./job-edit.ts";
@@ -1821,13 +1821,12 @@ export default function piLoops(pi: ExtensionAPI) {
 				// `pi install` does not put the package on your PATH. You are already inside pi with
 				// this extension loaded, so here is where that circle can be broken.
 				const lines: string[] = [];
-				const target = path.join(os.homedir(), ".local", "bin");
-				const ok = await ctx.ui.confirm("Put `pi-loops` on your PATH?", [`This writes a launcher into ${target} (or another directory on your PATH).`, "", "It is a two-line shell script that runs this package with this node.", "Afterwards `pi-loops` starts a session from any directory."].join("\n"));
-				if (!ok) {
+				const words = tokenize(splitCommand(args).rest).map((t) => t.value);
+				const code = await installLauncherWithConfirm(words, (title, body) => ctx.ui.confirm(title, body), (l) => lines.push(l));
+				if (code === undefined) {
 					ctx.ui.notify("not installed", "info");
 					return;
 				}
-				const code = await installLauncher(undefined, (l) => lines.push(l));
 				show(ctx, code === 0 ? "installed the pi-loops launcher" : "could not install the launcher", lines.map((l) => `  ${l.trim()}`));
 				return;
 			}
@@ -1835,7 +1834,7 @@ export default function piLoops(pi: ExtensionAPI) {
 				`  loops directory: ${homeRel(dir)}`,
 				`  package: ${homeRel(PACKAGE_DIR)}`,
 				"",
-				"  /pi-loops install-launcher   put the `pi-loops` command on your PATH",
+				"  /pi-loops install-launcher [--dir <dir>]   put the `pi-loops` command on your PATH",
 				"  /cron · /triggers · /inbox · /goal   the automation itself",
 			]);
 		},

package/src/web.mjs

@@ -91,7 +91,12 @@ if (!/^\d+$/.test(portArg) || Number(portArg) > 65535) {
 	process.exit(1);
 }
 const PORT = Number(portArg);
-const LOOPS_DIR = optionValue("loops-dir", process.env.PI_LOOPS_DIR || path.join(os.homedir(), ".pi", "agent", "loops"));
+// The directory the extension inside the pi behind this page uses (`defaultLoopsDir(getAgentDir())`,
+// which this file cannot import): PI_LOOPS_DIR, else `loops` under pi's agent directory — moved by
+// PI_CODING_AGENT_DIR, with a leading `~` expanded as pi expands it. Reading ~/.pi/agent/loops
+// regardless put the panel, the token and the remembered model in a directory the session was not using.
+const AGENT_DIR = process.env.PI_CODING_AGENT_DIR ? process.env.PI_CODING_AGENT_DIR.replace(process.platform === "win32" ? /^~(?=$|[\\/])/ : /^~(?=$|\/)/, os.homedir()) : path.join(os.homedir(), ".pi", "agent");
+const LOOPS_DIR = optionValue("loops-dir", process.env.PI_LOOPS_DIR || path.join(AGENT_DIR, "loops"));
 /**
  * The token is kept in a file rather than made fresh each launch, so the address stays the same
  * one every time: bookmark http://127.0.0.1:4173/ and it works tomorrow. It is a boring secret —