larkin 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.5.1
+
+External pi is accepted at 0.84.2 or newer instead of exactly 0.84.2; 0.5.0 refused newer pi and left every migrated Agent not ready.
+
 ## 0.5.0
 
 BREAKING — builtin Pi is removed. Larkin supports only externally installed `pi`, `codex`, and `claude`. If the selected runtime is not installed, setup, runtime switch, and readiness fail with an explicit missing-install message.

package/dist/runtime/pi-compaction-recovery.cjs

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PiCompactionRecoveryMachine = exports.PiCompactionBreaker = exports.PI_COMPACTION_RECOVERY_FILE = exports.PI_COMPACTION_RECOVERY_VERSION = exports.PI_COMPACTION_THRESHOLD = exports.COMPACTION_KEEP_RECENT_TOKENS = exports.COMPACTION_RESERVE_TOKENS = exports.PI_CONTEXT_WINDOW = exports.PINNED_PI_VERSION = void 0;
+exports.PiCompactionRecoveryMachine = exports.PiCompactionBreaker = exports.PI_COMPACTION_RECOVERY_FILE = exports.PI_COMPACTION_RECOVERY_VERSION = exports.PI_COMPACTION_THRESHOLD = exports.COMPACTION_KEEP_RECENT_TOKENS = exports.COMPACTION_RESERVE_TOKENS = exports.PI_CONTEXT_WINDOW = exports.MINIMUM_PI_VERSION = void 0;
 exports.calculatePiCompactionSettings = calculatePiCompactionSettings;
 exports.isPiNativeCompactionRequired = isPiNativeCompactionRequired;
 exports.assertEffectivePiCompactionSettings = assertEffectivePiCompactionSettings;
@@ -14,6 +14,7 @@ exports.prepareOwnedPiDirectory = prepareOwnedPiDirectory;
 exports.mergeOwnedPiSettings = mergeOwnedPiSettings;
 exports.writeOwnedPiSettings = writeOwnedPiSettings;
 exports.readOwnedPiSettings = readOwnedPiSettings;
+exports.olderThanMinimumPiVersionMessage = olderThanMinimumPiVersionMessage;
 exports.parsePiExecutableVersion = parsePiExecutableVersion;
 exports.verifyPiCapabilities = verifyPiCapabilities;
 exports.prepareOwnedPiEnvironment = prepareOwnedPiEnvironment;
@@ -24,7 +25,8 @@ const node_crypto_1 = __importDefault(require("node:crypto"));
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
-exports.PINNED_PI_VERSION = "0.84.2";
+/** External `pi` must be this version or newer; handshake still guards protocol compatibility. */
+exports.MINIMUM_PI_VERSION = "0.84.2";
 /** Fallback values used while importing a Pi profile, before Pi reports its model. */
 exports.PI_CONTEXT_WINDOW = 272_000;
 exports.COMPACTION_RESERVE_TOKENS = 40_800;
@@ -254,21 +256,51 @@ function readOwnedPiSettings(directory) {
     }
     return { compaction: { enabled, reserveTokens: values.reserveTokens, keepRecentTokens: values.keepRecentTokens } };
 }
+const PI_VERSION_LINE = /^(?:pi(?:-coding-agent)?(?:\s+version)?\s+v?)?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/i;
+const PI_VERSION_CORE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?$/;
+function comparePiNumericVersions(left, right) {
+    const leftParts = left.split(".").map(Number);
+    const rightParts = right.split(".").map(Number);
+    for (let index = 0; index < 3; index += 1) {
+        if (leftParts[index] !== rightParts[index])
+            return Math.sign(leftParts[index] - rightParts[index]);
+    }
+    return 0;
+}
+function olderThanMinimumPiVersionMessage(version) {
+    return `Pi executable version ${version} is older than the minimum ${exports.MINIMUM_PI_VERSION}`;
+}
+function assertSupportedPiVersion(version) {
+    if (typeof version !== "string")
+        throw new Error(`Pi executable version ${exports.MINIMUM_PI_VERSION} or newer is required`);
+    const raw = version.trim();
+    const match = PI_VERSION_CORE.exec(raw);
+    if (!match)
+        throw new Error(`Pi executable version ${raw || "missing"} is not a supported version`);
+    const numeric = `${match[1]}.${match[2]}.${match[3]}`;
+    if (match[4]) {
+        throw new Error(`Pi executable version ${raw} is unsupported: SemVer ${raw} < ${numeric}; Larkin supports stable external pi only`);
+    }
+    if (comparePiNumericVersions(numeric, exports.MINIMUM_PI_VERSION) < 0) {
+        throw new Error(olderThanMinimumPiVersionMessage(numeric));
+    }
+    return numeric;
+}
 function parsePiExecutableVersion(output) {
     const lines = output.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
     if (lines.length !== 1)
         throw new Error("Pi executable version output must contain exactly one version line");
-    const line = lines[0];
-    // Pi's bare version is canonical; permit only the fixed official display prefix.
-    const escapedVersion = exports.PINNED_PI_VERSION.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    if (!new RegExp(`^(?:${escapedVersion}|pi(?:-coding-agent)?(?:\\s+version)?\\s+v?${escapedVersion})$`, "i").test(line)) {
-        throw new Error(`Pi executable version must be exactly ${exports.PINNED_PI_VERSION}`);
-    }
-    return exports.PINNED_PI_VERSION;
+    const match = PI_VERSION_LINE.exec(lines[0]);
+    if (!match)
+        throw new Error("Pi executable version output is not a supported version line");
+    const version = `${match[1]}.${match[2]}.${match[3]}`;
+    if (comparePiNumericVersions(version, exports.MINIMUM_PI_VERSION) < 0) {
+        throw new Error(olderThanMinimumPiVersionMessage(version));
+    }
+    return version;
 }
 function verifyPiCapabilities(capabilities) {
-    if (capabilities.version !== exports.PINNED_PI_VERSION)
-        throw new Error(`trusted Pi version ${exports.PINNED_PI_VERSION} is required`);
+    assertSupportedPiVersion(capabilities.version);
     if (capabilities.trustedProtocol === true) {
         throw new Error("external Pi cannot use a trusted protocol bypass");
     }

package/dist/runtime/pi-compaction-recovery.mjs

@@ -2,7 +2,8 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-export const PINNED_PI_VERSION = "0.84.2";
+/** External `pi` must be this version or newer; handshake still guards protocol compatibility. */
+export const MINIMUM_PI_VERSION = "0.84.2";
 /** Fallback values used while importing a Pi profile, before Pi reports its model. */
 export const PI_CONTEXT_WINDOW = 272_000;
 export const COMPACTION_RESERVE_TOKENS = 40_800;
@@ -232,21 +233,51 @@ export function readOwnedPiSettings(directory) {
     }
     return { compaction: { enabled, reserveTokens: values.reserveTokens, keepRecentTokens: values.keepRecentTokens } };
 }
+const PI_VERSION_LINE = /^(?:pi(?:-coding-agent)?(?:\s+version)?\s+v?)?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/i;
+const PI_VERSION_CORE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?$/;
+function comparePiNumericVersions(left, right) {
+    const leftParts = left.split(".").map(Number);
+    const rightParts = right.split(".").map(Number);
+    for (let index = 0; index < 3; index += 1) {
+        if (leftParts[index] !== rightParts[index])
+            return Math.sign(leftParts[index] - rightParts[index]);
+    }
+    return 0;
+}
+export function olderThanMinimumPiVersionMessage(version) {
+    return `Pi executable version ${version} is older than the minimum ${MINIMUM_PI_VERSION}`;
+}
+function assertSupportedPiVersion(version) {
+    if (typeof version !== "string")
+        throw new Error(`Pi executable version ${MINIMUM_PI_VERSION} or newer is required`);
+    const raw = version.trim();
+    const match = PI_VERSION_CORE.exec(raw);
+    if (!match)
+        throw new Error(`Pi executable version ${raw || "missing"} is not a supported version`);
+    const numeric = `${match[1]}.${match[2]}.${match[3]}`;
+    if (match[4]) {
+        throw new Error(`Pi executable version ${raw} is unsupported: SemVer ${raw} < ${numeric}; Larkin supports stable external pi only`);
+    }
+    if (comparePiNumericVersions(numeric, MINIMUM_PI_VERSION) < 0) {
+        throw new Error(olderThanMinimumPiVersionMessage(numeric));
+    }
+    return numeric;
+}
 export function parsePiExecutableVersion(output) {
     const lines = output.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
     if (lines.length !== 1)
         throw new Error("Pi executable version output must contain exactly one version line");
-    const line = lines[0];
-    // Pi's bare version is canonical; permit only the fixed official display prefix.
-    const escapedVersion = PINNED_PI_VERSION.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    if (!new RegExp(`^(?:${escapedVersion}|pi(?:-coding-agent)?(?:\\s+version)?\\s+v?${escapedVersion})$`, "i").test(line)) {
-        throw new Error(`Pi executable version must be exactly ${PINNED_PI_VERSION}`);
-    }
-    return PINNED_PI_VERSION;
+    const match = PI_VERSION_LINE.exec(lines[0]);
+    if (!match)
+        throw new Error("Pi executable version output is not a supported version line");
+    const version = `${match[1]}.${match[2]}.${match[3]}`;
+    if (comparePiNumericVersions(version, MINIMUM_PI_VERSION) < 0) {
+        throw new Error(olderThanMinimumPiVersionMessage(version));
+    }
+    return version;
 }
 export function verifyPiCapabilities(capabilities) {
-    if (capabilities.version !== PINNED_PI_VERSION)
-        throw new Error(`trusted Pi version ${PINNED_PI_VERSION} is required`);
+    assertSupportedPiVersion(capabilities.version);
     if (capabilities.trustedProtocol === true) {
         throw new Error("external Pi cannot use a trusted protocol bypass");
     }

package/dist/runtime/runtime-adapters.mjs

@@ -14,7 +14,7 @@ import { effectivePiStateDir, extractBackgroundPiSubagentDispatch } from "./pi-s
 import { resolvePiBashTimeoutExtensionArg } from "./pi-bash-timeout-injection.mjs";
 import { classifyPiMissingCredentialRejection, classifyRuntimePrerequisite, missingProviderCredentialReadiness, probeNativeRuntimeReadiness, providerAuthenticationFailureReadiness, RuntimePrerequisiteError, } from "./runtime-readiness.mjs";
 import { buildStrictProviderErrorInput, classifyStrictProviderError, INTERNAL_CONTEXT_WINDOW_PROJECTION_REASON, } from "./provider-error-classifier.mjs";
-import { assertEffectivePiCompactionSettings, assertNoProjectPiCompactionOverride, PINNED_PI_VERSION, calculatePiCompactionSettings, parsePiExecutableVersion, prepareOwnedPiDirectory, readOwnedPiSettings, verifyPiCapabilities, writeOwnedPiSettings, } from "./pi-compaction-recovery.mjs";
+import { assertEffectivePiCompactionSettings, assertNoProjectPiCompactionOverride, MINIMUM_PI_VERSION, calculatePiCompactionSettings, parsePiExecutableVersion, prepareOwnedPiDirectory, readOwnedPiSettings, verifyPiCapabilities, writeOwnedPiSettings, } from "./pi-compaction-recovery.mjs";
 function piAgentDirectory(configDir, agentId) {
     return path.join(path.resolve(configDir), "providers", "pi", agentId);
 }
@@ -1048,7 +1048,7 @@ async function createPiRpcBackend(input, dependencies, spawn, productionSpawn =
         ? parsePiExecutableVersion(String(spawnSync(command, [...commandPrefix, "--version"], {
             cwd: input.workspaceDir, env: childEnv, encoding: "utf8", timeout: 5_000,
         }).stdout || ""))
-        : PINNED_PI_VERSION;
+        : MINIMUM_PI_VERSION;
     const extensionInput = { piCommand: command, env: childEnv, platform: process.platform };
     // 假 spawn 不需要真实 extension 路径；默认 resolver 会 spawnSync(`pi --version`)。
     const extensionArgs = dependencies.resolvePiProcessExtensionArgs

package/dist/runtime/runtime-readiness.cjs

@@ -53,6 +53,7 @@ exports.probeNativeRuntimeReadiness = probeNativeRuntimeReadiness;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
+const pi_compaction_recovery_js_1 = require("./pi-compaction-recovery.cjs");
 function safeProviderId(value) {
     const provider = typeof value === "string" ? value.trim() : "";
     return /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(provider) ? provider : null;
@@ -191,6 +192,14 @@ function classifyRuntimePrerequisite(runtime, error, executable) {
             runtime, state: "unauthenticated", ...(executable ? { executable } : {}), reason,
             nextAction: runtimeLoginNextAction(runtime),
         };
+    if (/older than the minimum|not a supported version(?: line)?|version output must contain exactly one/i.test(reason)) {
+        return {
+            runtime, state: "incompatible", ...(executable ? { executable } : {}), reason,
+            nextAction: runtime === "pi"
+                ? `Upgrade pi to ${pi_compaction_recovery_js_1.MINIMUM_PI_VERSION} or newer`
+                : `Upgrade ${runtime}, then retry.`,
+        };
+    }
     if (/protocol (?:version )?(?:mismatch|unsupported|incompatible)|unsupported (?:rpc|protocol|schema)|schema (?:mismatch|incompatible)|requires (?:a )?newer version/i.test(reason)) {
         return {
             runtime, state: "incompatible", ...(executable ? { executable } : {}), reason,
@@ -238,7 +247,19 @@ async function probeNativeRuntimeReadiness(options) {
             nextAction: runtimeInstallNextAction(options.runtime),
         };
     }
-    const version = executableVersion(executable, env, options.commandArgs);
+    let version = executableVersion(executable, env, options.commandArgs);
+    if (options.runtime === "pi") {
+        try {
+            const probe = (0, node_child_process_1.spawnSync)(executable, [...options.commandArgs ?? [], "--version"], {
+                env, encoding: "utf8", timeout: 5_000, maxBuffer: 64 * 1024,
+            });
+            version = (0, pi_compaction_recovery_js_1.parsePiExecutableVersion)(String(probe.stdout || ""));
+        }
+        catch (error) {
+            const classified = classifyRuntimePrerequisite("pi", error, executable);
+            return { ...classified, executable, ...(version ? { version } : {}) };
+        }
+    }
     try {
         if (options.runtime === "pi") {
             const { discoverPiModelCatalog } = await Promise.resolve().then(() => __importStar(require("./pi-model-catalog.cjs")));

package/dist/runtime/runtime-readiness.mjs

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { MINIMUM_PI_VERSION, parsePiExecutableVersion } from "./pi-compaction-recovery.mjs";
 export function safeProviderId(value) {
     const provider = typeof value === "string" ? value.trim() : "";
     return /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(provider) ? provider : null;
@@ -138,6 +139,14 @@ export function classifyRuntimePrerequisite(runtime, error, executable) {
             runtime, state: "unauthenticated", ...(executable ? { executable } : {}), reason,
             nextAction: runtimeLoginNextAction(runtime),
         };
+    if (/older than the minimum|not a supported version(?: line)?|version output must contain exactly one/i.test(reason)) {
+        return {
+            runtime, state: "incompatible", ...(executable ? { executable } : {}), reason,
+            nextAction: runtime === "pi"
+                ? `Upgrade pi to ${MINIMUM_PI_VERSION} or newer`
+                : `Upgrade ${runtime}, then retry.`,
+        };
+    }
     if (/protocol (?:version )?(?:mismatch|unsupported|incompatible)|unsupported (?:rpc|protocol|schema)|schema (?:mismatch|incompatible)|requires (?:a )?newer version/i.test(reason)) {
         return {
             runtime, state: "incompatible", ...(executable ? { executable } : {}), reason,
@@ -185,7 +194,19 @@ export async function probeNativeRuntimeReadiness(options) {
             nextAction: runtimeInstallNextAction(options.runtime),
         };
     }
-    const version = executableVersion(executable, env, options.commandArgs);
+    let version = executableVersion(executable, env, options.commandArgs);
+    if (options.runtime === "pi") {
+        try {
+            const probe = spawnSync(executable, [...options.commandArgs ?? [], "--version"], {
+                env, encoding: "utf8", timeout: 5_000, maxBuffer: 64 * 1024,
+            });
+            version = parsePiExecutableVersion(String(probe.stdout || ""));
+        }
+        catch (error) {
+            const classified = classifyRuntimePrerequisite("pi", error, executable);
+            return { ...classified, executable, ...(version ? { version } : {}) };
+        }
+    }
     try {
         if (options.runtime === "pi") {
             const { discoverPiModelCatalog } = await import("./pi-model-catalog.mjs");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "larkin",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "private": false,
   "larkinPackageRole": "npm-published",
   "files": [