larkin 0.4.2 → 0.4.6

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

@@ -4,14 +4,17 @@ var __importDefault = (this && this.__importDefault) || function (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 = void 0;
+exports.calculatePiCompactionSettings = calculatePiCompactionSettings;
 exports.isPiNativeCompactionRequired = isPiNativeCompactionRequired;
 exports.assertEffectivePiCompactionSettings = assertEffectivePiCompactionSettings;
 exports.hasProjectPiCompactionOverride = hasProjectPiCompactionOverride;
 exports.ensureOwnedPiAgentDirectory = ensureOwnedPiAgentDirectory;
 exports.ownedPiSettings = ownedPiSettings;
 exports.prepareOwnedPiDirectory = prepareOwnedPiDirectory;
+exports.mergeOwnedPiSettings = mergeOwnedPiSettings;
 exports.writeOwnedPiSettings = writeOwnedPiSettings;
 exports.readOwnedPiSettings = readOwnedPiSettings;
+exports.parsePiExecutableVersion = parsePiExecutableVersion;
 exports.verifyPiCapabilities = verifyPiCapabilities;
 exports.prepareOwnedPiEnvironment = prepareOwnedPiEnvironment;
 exports.readProjectPiSettings = readProjectPiSettings;
@@ -21,10 +24,14 @@ 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"));
+const pi_provider_config_js_1 = require("./pi-provider-config.cjs");
+/** 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;
 exports.COMPACTION_KEEP_RECENT_TOKENS = 20_000;
 exports.PI_COMPACTION_THRESHOLD = exports.PI_CONTEXT_WINDOW - exports.COMPACTION_RESERVE_TOKENS;
+const COMPACTION_RESERVE_RATIO_PERCENT = 15;
+const MAX_KEEP_RECENT_TOKENS = 20_000;
 exports.PI_COMPACTION_RECOVERY_VERSION = 1;
 exports.PI_COMPACTION_RECOVERY_FILE = "piCompactionRecovery.json";
 const AGENT_ID = /^cli_[A-Za-z0-9]+$/;
@@ -52,20 +59,44 @@ function requireFiniteBoolean(value, name) {
         throw new Error(`${name} must be a boolean`);
     return value;
 }
-function isPiNativeCompactionRequired(contextTokens) {
-    return Number.isFinite(contextTokens) && contextTokens > exports.PI_COMPACTION_THRESHOLD;
+function calculatePiCompactionSettings(contextWindow) {
+    if (!Number.isSafeInteger(contextWindow) || contextWindow <= 0) {
+        throw new Error("Pi effective context window must be a positive safe integer");
+    }
+    const reserveTokens = Math.min(contextWindow - 1, Math.ceil(contextWindow * COMPACTION_RESERVE_RATIO_PERCENT / 100));
+    const threshold = contextWindow - reserveTokens;
+    if (reserveTokens < 1 || threshold <= 1)
+        throw new Error("Pi effective context window is too small for safe compaction");
+    const keepRecentTokens = Math.min(MAX_KEEP_RECENT_TOKENS, threshold - 1);
+    return { reserveTokens, keepRecentTokens, threshold };
+}
+function isPiNativeCompactionRequired(contextTokens, contextWindow = exports.PI_CONTEXT_WINDOW) {
+    if (!Number.isFinite(contextTokens))
+        return false;
+    try {
+        return contextTokens > calculatePiCompactionSettings(contextWindow).threshold;
+    }
+    catch {
+        return false;
+    }
 }
 function assertEffectivePiCompactionSettings(settings) {
     const contextWindow = settings.contextWindow ?? settings.model?.contextWindow;
-    if (contextWindow !== exports.PI_CONTEXT_WINDOW)
-        throw new Error(`Pi effective context window must be exactly ${exports.PI_CONTEXT_WINDOW}`);
+    const expected = (() => {
+        try {
+            return calculatePiCompactionSettings(contextWindow);
+        }
+        catch {
+            throw new Error("Pi effective context window must be a positive safe integer");
+        }
+    })();
     if (settings.compaction?.enabled !== true)
         throw new Error("Pi native compaction must be enabled");
-    if (settings.compaction.reserveTokens !== exports.COMPACTION_RESERVE_TOKENS) {
-        throw new Error(`Pi reserveTokens must be exactly ${exports.COMPACTION_RESERVE_TOKENS}`);
+    if (settings.compaction.reserveTokens !== expected.reserveTokens) {
+        throw new Error(`Pi reserveTokens must be exactly ${expected.reserveTokens} for context window ${contextWindow}`);
     }
-    if (settings.compaction.keepRecentTokens !== exports.COMPACTION_KEEP_RECENT_TOKENS) {
-        throw new Error(`Pi keepRecentTokens must be exactly ${exports.COMPACTION_KEEP_RECENT_TOKENS}`);
+    if (settings.compaction.keepRecentTokens !== expected.keepRecentTokens) {
+        throw new Error(`Pi keepRecentTokens must be exactly ${expected.keepRecentTokens} for context window ${contextWindow}`);
     }
 }
 function hasProjectPiCompactionOverride(settings) {
@@ -132,6 +163,7 @@ function ensureDirectoryChain(directory) {
 function ensureOwnedPiAgentDirectory(root, agentId) {
     if (!AGENT_ID.test(agentId))
         throw new Error("invalid Pi Agent ID");
+    ensureDirectoryChain(root);
     const resolvedRoot = node_path_1.default.resolve(root);
     ensureDirectory(resolvedRoot);
     const parent = node_path_1.default.join(resolvedRoot, "pi-agents");
@@ -143,15 +175,34 @@ function ensureOwnedPiAgentDirectory(root, agentId) {
 function ownedPiSettings(directory) {
     return node_path_1.default.join(directory, "settings.json");
 }
-function prepareOwnedPiDirectory(directory) {
+function prepareOwnedPiDirectory(directory, compaction) {
     ensureDirectoryChain(node_path_1.default.dirname(directory));
     ensureDirectory(node_path_1.default.dirname(directory));
     ensureDirectory(directory);
-    writeOwnedPiSettings(directory);
+    writeOwnedPiSettings(directory, compaction);
     return directory;
 }
-function writeOwnedPiSettings(directory) {
-    assertOwnedDirectory(directory);
+function mergeOwnedPiSettings(value, compaction = {
+    reserveTokens: exports.COMPACTION_RESERVE_TOKENS,
+    keepRecentTokens: exports.COMPACTION_KEEP_RECENT_TOKENS,
+    threshold: exports.PI_COMPACTION_THRESHOLD,
+}) {
+    if (value !== undefined && (!value || typeof value !== "object" || Array.isArray(value))) {
+        throw new Error("Pi owned settings are invalid");
+    }
+    const object = (value || {});
+    const existing = object.compaction;
+    if (existing !== undefined && (!existing || typeof existing !== "object" || Array.isArray(existing))) {
+        throw new Error("Pi owned compaction settings are invalid");
+    }
+    return { ...object, compaction: {
+            ...existing, enabled: true,
+            reserveTokens: compaction.reserveTokens, keepRecentTokens: compaction.keepRecentTokens,
+        } };
+}
+function writeOwnedPiSettings(directory, compaction) {
+    ensureDirectoryChain(node_path_1.default.dirname(directory));
+    ensureDirectory(directory);
     const file = ownedPiSettings(directory);
     try {
         const existing = node_fs_1.default.lstatSync(file);
@@ -162,15 +213,17 @@ function writeOwnedPiSettings(directory) {
         if (error.code !== "ENOENT")
             throw error;
     }
+    let value;
+    try {
+        value = JSON.parse(node_fs_1.default.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw new Error("Pi owned settings are invalid");
+    }
     const temporary = node_path_1.default.join(directory, `.${node_path_1.default.basename(file)}.${process.pid}.${node_crypto_1.default.randomUUID()}.tmp`);
     try {
-        node_fs_1.default.writeFileSync(temporary, `${JSON.stringify({
-            compaction: {
-                enabled: true,
-                reserveTokens: exports.COMPACTION_RESERVE_TOKENS,
-                keepRecentTokens: exports.COMPACTION_KEEP_RECENT_TOKENS,
-            },
-        }, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+        node_fs_1.default.writeFileSync(temporary, `${JSON.stringify(mergeOwnedPiSettings(value, compaction), null, 2)}\n`, { flag: "wx", mode: 0o600 });
         node_fs_1.default.renameSync(temporary, file);
         node_fs_1.default.chmodSync(file, 0o600);
     }
@@ -182,6 +235,8 @@ function writeOwnedPiSettings(directory) {
     }
 }
 function readOwnedPiSettings(directory) {
+    ensureDirectoryChain(node_path_1.default.dirname(directory));
+    assertOwnedDirectory(directory);
     const file = ownedPiSettings(directory);
     const stat = node_fs_1.default.lstatSync(file);
     if (stat.isSymbolicLink() || !stat.isFile())
@@ -199,28 +254,48 @@ function readOwnedPiSettings(directory) {
     }
     return { compaction: { enabled, reserveTokens: values.reserveTokens, keepRecentTokens: values.keepRecentTokens } };
 }
+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 = pi_provider_config_js_1.BUNDLED_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 ${pi_provider_config_js_1.BUNDLED_PI_VERSION}`);
+    }
+    return pi_provider_config_js_1.BUNDLED_PI_VERSION;
+}
 function verifyPiCapabilities(capabilities) {
-    if (!/(?:^|\D)0\.83\.0(?:$|\D)/.test(capabilities.version || "")) {
-        throw new Error("trusted Pi version 0.83.0 is required");
+    if (capabilities.version !== pi_provider_config_js_1.BUNDLED_PI_VERSION)
+        throw new Error(`trusted Pi version ${pi_provider_config_js_1.BUNDLED_PI_VERSION} is required`);
+    if (capabilities.distribution === "external" && capabilities.trustedProtocol === true) {
+        throw new Error("external Pi cannot use the bundled trusted protocol bypass");
     }
     const contextWindow = capabilities.contextWindow ?? capabilities.model?.contextWindow;
-    if (contextWindow !== exports.PI_CONTEXT_WINDOW)
-        throw new Error("Pi capability context window is not 272000");
+    const expected = (() => {
+        try {
+            return calculatePiCompactionSettings(contextWindow);
+        }
+        catch {
+            throw new Error("Pi capability context window is invalid");
+        }
+    })();
     if (requireFiniteBoolean(capabilities.autoCompactionEnabled, "Pi autoCompactionEnabled") !== true) {
         throw new Error("Pi effective native compaction is disabled");
     }
     if (capabilities.compactRpc !== true)
         throw new Error("Pi compact RPC capability is missing");
-    if (capabilities.trustedProtocol !== true) {
-        if (capabilities.reserveTokens !== exports.COMPACTION_RESERVE_TOKENS
-            || capabilities.keepRecentTokens !== exports.COMPACTION_KEEP_RECENT_TOKENS) {
-            throw new Error("Pi external effective compaction reserve/keep settings are unproven");
-        }
-        const events = new Set(capabilities.events || []);
-        for (const event of REQUIRED_PI_EVENTS)
-            if (!events.has(event))
-                throw new Error(`Pi capability event is unproven: ${event}`);
-    }
+    if (capabilities.distribution === "builtin" && capabilities.trustedProtocol === true)
+        return;
+    if (capabilities.reserveTokens !== expected.reserveTokens
+        || capabilities.keepRecentTokens !== expected.keepRecentTokens) {
+        throw new Error(`Pi external effective compaction reserve/keep settings are unproven for context window ${contextWindow}`);
+    }
+    const events = new Set(capabilities.events || []);
+    for (const event of REQUIRED_PI_EVENTS)
+        if (!events.has(event))
+            throw new Error(`Pi capability event is unproven: ${event}`);
 }
 function stateFile(root) {
     return node_path_1.default.join(root, exports.PI_COMPACTION_RECOVERY_FILE);
@@ -296,9 +371,14 @@ class PiCompactionBreaker {
         this.clock = options.now ?? (() => new Date().toISOString());
         this.records = new Map(this.read().records.map((record) => [record.key, record]));
         this.retentionMs = options.retentionMs ?? 30 * 24 * 60 * 60 * 1000;
-        this.withLock = options.withLock ?? ((operation) => operation());
+        this.withLock = options.withLock;
     }
     retentionMs;
+    runLocked(operation) {
+        if (!this.withLock)
+            throw new Error("Pi compaction breaker requires the canonical Agent state lock");
+        return this.withLock(operation);
+    }
     read() {
         try {
             const stat = node_fs_1.default.lstatSync(this.file);
@@ -351,13 +431,13 @@ class PiCompactionBreaker {
         this.records = new Map(this.read().records.map((record) => [record.key, record]));
     }
     get(key) {
-        return this.withLock(() => { this.reload(); const record = this.records.get(key); return record ? { ...record } : undefined; });
+        return this.runLocked(() => { this.reload(); const record = this.records.get(key); return record ? { ...record } : undefined; });
     }
     listNonTerminal() {
-        return this.withLock(() => { this.reload(); return [...this.records.values()].filter((record) => !TERMINAL_STATES.has(record.state)).map((record) => ({ ...record })); });
+        return this.runLocked(() => { this.reload(); return [...this.records.values()].filter((record) => !TERMINAL_STATES.has(record.state)).map((record) => ({ ...record })); });
     }
     save(record) {
-        this.withLock(() => { this.reload(); const checked = safeRecord({ ...record, updatedAt: this.clock() }); this.records.set(checked.key, checked); this.persist(); });
+        this.runLocked(() => { this.reload(); const checked = safeRecord({ ...record, updatedAt: this.clock() }); this.records.set(checked.key, checked); this.persist(); });
     }
     transitionUnlocked(key, patch, state) {
         this.reload();
@@ -400,13 +480,13 @@ class PiCompactionBreaker {
         return { ...next };
     }
     transition(key, patch, state) {
-        return this.withLock(() => this.transitionUnlocked(key, patch, state));
+        return this.runLocked(() => this.transitionUnlocked(key, patch, state));
     }
     transitionInTransaction(key, patch, state) {
         return this.transitionUnlocked(key, patch, state);
     }
     prune(consumedKeys = []) {
-        return this.withLock(() => this.pruneUnlocked(consumedKeys));
+        return this.runLocked(() => this.pruneUnlocked(consumedKeys));
     }
     pruneUnlocked(consumedKeys = []) {
         this.reload();
@@ -426,7 +506,7 @@ class PiCompactionBreaker {
         return count;
     }
     forceFallback(key, reason) {
-        return this.withLock(() => {
+        return this.runLocked(() => {
             this.reload();
             const current = this.records.get(key);
             if (!current)

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

@@ -2,10 +2,14 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { BUNDLED_PI_VERSION } from "./pi-provider-config.mjs";
+/** 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;
 export const COMPACTION_KEEP_RECENT_TOKENS = 20_000;
 export const PI_COMPACTION_THRESHOLD = PI_CONTEXT_WINDOW - COMPACTION_RESERVE_TOKENS;
+const COMPACTION_RESERVE_RATIO_PERCENT = 15;
+const MAX_KEEP_RECENT_TOKENS = 20_000;
 export const PI_COMPACTION_RECOVERY_VERSION = 1;
 export const PI_COMPACTION_RECOVERY_FILE = "piCompactionRecovery.json";
 const AGENT_ID = /^cli_[A-Za-z0-9]+$/;
@@ -33,20 +37,44 @@ function requireFiniteBoolean(value, name) {
         throw new Error(`${name} must be a boolean`);
     return value;
 }
-export function isPiNativeCompactionRequired(contextTokens) {
-    return Number.isFinite(contextTokens) && contextTokens > PI_COMPACTION_THRESHOLD;
+export function calculatePiCompactionSettings(contextWindow) {
+    if (!Number.isSafeInteger(contextWindow) || contextWindow <= 0) {
+        throw new Error("Pi effective context window must be a positive safe integer");
+    }
+    const reserveTokens = Math.min(contextWindow - 1, Math.ceil(contextWindow * COMPACTION_RESERVE_RATIO_PERCENT / 100));
+    const threshold = contextWindow - reserveTokens;
+    if (reserveTokens < 1 || threshold <= 1)
+        throw new Error("Pi effective context window is too small for safe compaction");
+    const keepRecentTokens = Math.min(MAX_KEEP_RECENT_TOKENS, threshold - 1);
+    return { reserveTokens, keepRecentTokens, threshold };
+}
+export function isPiNativeCompactionRequired(contextTokens, contextWindow = PI_CONTEXT_WINDOW) {
+    if (!Number.isFinite(contextTokens))
+        return false;
+    try {
+        return contextTokens > calculatePiCompactionSettings(contextWindow).threshold;
+    }
+    catch {
+        return false;
+    }
 }
 export function assertEffectivePiCompactionSettings(settings) {
     const contextWindow = settings.contextWindow ?? settings.model?.contextWindow;
-    if (contextWindow !== PI_CONTEXT_WINDOW)
-        throw new Error(`Pi effective context window must be exactly ${PI_CONTEXT_WINDOW}`);
+    const expected = (() => {
+        try {
+            return calculatePiCompactionSettings(contextWindow);
+        }
+        catch {
+            throw new Error("Pi effective context window must be a positive safe integer");
+        }
+    })();
     if (settings.compaction?.enabled !== true)
         throw new Error("Pi native compaction must be enabled");
-    if (settings.compaction.reserveTokens !== COMPACTION_RESERVE_TOKENS) {
-        throw new Error(`Pi reserveTokens must be exactly ${COMPACTION_RESERVE_TOKENS}`);
+    if (settings.compaction.reserveTokens !== expected.reserveTokens) {
+        throw new Error(`Pi reserveTokens must be exactly ${expected.reserveTokens} for context window ${contextWindow}`);
     }
-    if (settings.compaction.keepRecentTokens !== COMPACTION_KEEP_RECENT_TOKENS) {
-        throw new Error(`Pi keepRecentTokens must be exactly ${COMPACTION_KEEP_RECENT_TOKENS}`);
+    if (settings.compaction.keepRecentTokens !== expected.keepRecentTokens) {
+        throw new Error(`Pi keepRecentTokens must be exactly ${expected.keepRecentTokens} for context window ${contextWindow}`);
     }
 }
 export function hasProjectPiCompactionOverride(settings) {
@@ -113,6 +141,7 @@ function ensureDirectoryChain(directory) {
 export function ensureOwnedPiAgentDirectory(root, agentId) {
     if (!AGENT_ID.test(agentId))
         throw new Error("invalid Pi Agent ID");
+    ensureDirectoryChain(root);
     const resolvedRoot = path.resolve(root);
     ensureDirectory(resolvedRoot);
     const parent = path.join(resolvedRoot, "pi-agents");
@@ -124,15 +153,34 @@ export function ensureOwnedPiAgentDirectory(root, agentId) {
 export function ownedPiSettings(directory) {
     return path.join(directory, "settings.json");
 }
-export function prepareOwnedPiDirectory(directory) {
+export function prepareOwnedPiDirectory(directory, compaction) {
     ensureDirectoryChain(path.dirname(directory));
     ensureDirectory(path.dirname(directory));
     ensureDirectory(directory);
-    writeOwnedPiSettings(directory);
+    writeOwnedPiSettings(directory, compaction);
     return directory;
 }
-export function writeOwnedPiSettings(directory) {
-    assertOwnedDirectory(directory);
+export function mergeOwnedPiSettings(value, compaction = {
+    reserveTokens: COMPACTION_RESERVE_TOKENS,
+    keepRecentTokens: COMPACTION_KEEP_RECENT_TOKENS,
+    threshold: PI_COMPACTION_THRESHOLD,
+}) {
+    if (value !== undefined && (!value || typeof value !== "object" || Array.isArray(value))) {
+        throw new Error("Pi owned settings are invalid");
+    }
+    const object = (value || {});
+    const existing = object.compaction;
+    if (existing !== undefined && (!existing || typeof existing !== "object" || Array.isArray(existing))) {
+        throw new Error("Pi owned compaction settings are invalid");
+    }
+    return { ...object, compaction: {
+            ...existing, enabled: true,
+            reserveTokens: compaction.reserveTokens, keepRecentTokens: compaction.keepRecentTokens,
+        } };
+}
+export function writeOwnedPiSettings(directory, compaction) {
+    ensureDirectoryChain(path.dirname(directory));
+    ensureDirectory(directory);
     const file = ownedPiSettings(directory);
     try {
         const existing = fs.lstatSync(file);
@@ -143,15 +191,17 @@ export function writeOwnedPiSettings(directory) {
         if (error.code !== "ENOENT")
             throw error;
     }
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw new Error("Pi owned settings are invalid");
+    }
     const temporary = path.join(directory, `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
     try {
-        fs.writeFileSync(temporary, `${JSON.stringify({
-            compaction: {
-                enabled: true,
-                reserveTokens: COMPACTION_RESERVE_TOKENS,
-                keepRecentTokens: COMPACTION_KEEP_RECENT_TOKENS,
-            },
-        }, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+        fs.writeFileSync(temporary, `${JSON.stringify(mergeOwnedPiSettings(value, compaction), null, 2)}\n`, { flag: "wx", mode: 0o600 });
         fs.renameSync(temporary, file);
         fs.chmodSync(file, 0o600);
     }
@@ -163,6 +213,8 @@ export function writeOwnedPiSettings(directory) {
     }
 }
 export function readOwnedPiSettings(directory) {
+    ensureDirectoryChain(path.dirname(directory));
+    assertOwnedDirectory(directory);
     const file = ownedPiSettings(directory);
     const stat = fs.lstatSync(file);
     if (stat.isSymbolicLink() || !stat.isFile())
@@ -180,28 +232,48 @@ export function readOwnedPiSettings(directory) {
     }
     return { compaction: { enabled, reserveTokens: values.reserveTokens, keepRecentTokens: values.keepRecentTokens } };
 }
+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 = BUNDLED_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 ${BUNDLED_PI_VERSION}`);
+    }
+    return BUNDLED_PI_VERSION;
+}
 export function verifyPiCapabilities(capabilities) {
-    if (!/(?:^|\D)0\.83\.0(?:$|\D)/.test(capabilities.version || "")) {
-        throw new Error("trusted Pi version 0.83.0 is required");
+    if (capabilities.version !== BUNDLED_PI_VERSION)
+        throw new Error(`trusted Pi version ${BUNDLED_PI_VERSION} is required`);
+    if (capabilities.distribution === "external" && capabilities.trustedProtocol === true) {
+        throw new Error("external Pi cannot use the bundled trusted protocol bypass");
     }
     const contextWindow = capabilities.contextWindow ?? capabilities.model?.contextWindow;
-    if (contextWindow !== PI_CONTEXT_WINDOW)
-        throw new Error("Pi capability context window is not 272000");
+    const expected = (() => {
+        try {
+            return calculatePiCompactionSettings(contextWindow);
+        }
+        catch {
+            throw new Error("Pi capability context window is invalid");
+        }
+    })();
     if (requireFiniteBoolean(capabilities.autoCompactionEnabled, "Pi autoCompactionEnabled") !== true) {
         throw new Error("Pi effective native compaction is disabled");
     }
     if (capabilities.compactRpc !== true)
         throw new Error("Pi compact RPC capability is missing");
-    if (capabilities.trustedProtocol !== true) {
-        if (capabilities.reserveTokens !== COMPACTION_RESERVE_TOKENS
-            || capabilities.keepRecentTokens !== COMPACTION_KEEP_RECENT_TOKENS) {
-            throw new Error("Pi external effective compaction reserve/keep settings are unproven");
-        }
-        const events = new Set(capabilities.events || []);
-        for (const event of REQUIRED_PI_EVENTS)
-            if (!events.has(event))
-                throw new Error(`Pi capability event is unproven: ${event}`);
-    }
+    if (capabilities.distribution === "builtin" && capabilities.trustedProtocol === true)
+        return;
+    if (capabilities.reserveTokens !== expected.reserveTokens
+        || capabilities.keepRecentTokens !== expected.keepRecentTokens) {
+        throw new Error(`Pi external effective compaction reserve/keep settings are unproven for context window ${contextWindow}`);
+    }
+    const events = new Set(capabilities.events || []);
+    for (const event of REQUIRED_PI_EVENTS)
+        if (!events.has(event))
+            throw new Error(`Pi capability event is unproven: ${event}`);
 }
 function stateFile(root) {
     return path.join(root, PI_COMPACTION_RECOVERY_FILE);
@@ -277,9 +349,14 @@ export class PiCompactionBreaker {
         this.clock = options.now ?? (() => new Date().toISOString());
         this.records = new Map(this.read().records.map((record) => [record.key, record]));
         this.retentionMs = options.retentionMs ?? 30 * 24 * 60 * 60 * 1000;
-        this.withLock = options.withLock ?? ((operation) => operation());
+        this.withLock = options.withLock;
     }
     retentionMs;
+    runLocked(operation) {
+        if (!this.withLock)
+            throw new Error("Pi compaction breaker requires the canonical Agent state lock");
+        return this.withLock(operation);
+    }
     read() {
         try {
             const stat = fs.lstatSync(this.file);
@@ -332,13 +409,13 @@ export class PiCompactionBreaker {
         this.records = new Map(this.read().records.map((record) => [record.key, record]));
     }
     get(key) {
-        return this.withLock(() => { this.reload(); const record = this.records.get(key); return record ? { ...record } : undefined; });
+        return this.runLocked(() => { this.reload(); const record = this.records.get(key); return record ? { ...record } : undefined; });
     }
     listNonTerminal() {
-        return this.withLock(() => { this.reload(); return [...this.records.values()].filter((record) => !TERMINAL_STATES.has(record.state)).map((record) => ({ ...record })); });
+        return this.runLocked(() => { this.reload(); return [...this.records.values()].filter((record) => !TERMINAL_STATES.has(record.state)).map((record) => ({ ...record })); });
     }
     save(record) {
-        this.withLock(() => { this.reload(); const checked = safeRecord({ ...record, updatedAt: this.clock() }); this.records.set(checked.key, checked); this.persist(); });
+        this.runLocked(() => { this.reload(); const checked = safeRecord({ ...record, updatedAt: this.clock() }); this.records.set(checked.key, checked); this.persist(); });
     }
     transitionUnlocked(key, patch, state) {
         this.reload();
@@ -381,13 +458,13 @@ export class PiCompactionBreaker {
         return { ...next };
     }
     transition(key, patch, state) {
-        return this.withLock(() => this.transitionUnlocked(key, patch, state));
+        return this.runLocked(() => this.transitionUnlocked(key, patch, state));
     }
     transitionInTransaction(key, patch, state) {
         return this.transitionUnlocked(key, patch, state);
     }
     prune(consumedKeys = []) {
-        return this.withLock(() => this.pruneUnlocked(consumedKeys));
+        return this.runLocked(() => this.pruneUnlocked(consumedKeys));
     }
     pruneUnlocked(consumedKeys = []) {
         this.reload();
@@ -407,7 +484,7 @@ export class PiCompactionBreaker {
         return count;
     }
     forceFallback(key, reason) {
-        return this.withLock(() => {
+        return this.runLocked(() => {
             this.reload();
             const current = this.records.get(key);
             if (!current)

package/dist/runtime/pi-model-catalog.cjs

@@ -74,7 +74,7 @@ const discoveryCache = new Map();
 async function discoverPiModelCatalog(options) {
     if (!options.spawn) {
         const command = options.command ?? options.env?.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi";
-        const key = `${command}|${options.env?.PI_CODING_AGENT_DIR ?? ""}|${options.agentDir ?? ""}`;
+        const key = `${command}|${(options.commandArgs ?? []).join("\0")}|${options.env?.PI_CODING_AGENT_DIR ?? ""}|${options.agentDir ?? ""}`;
         const cached = discoveryCache.get(key);
         if (cached)
             return cached;
@@ -91,7 +91,7 @@ async function discoverPiModelCatalog(options) {
 async function discoverPiModelCatalogUncached(options) {
     const spawn = options.spawn ?? ((command, args, spawnOptions) => (0, node_child_process_1.spawn)(command, [...args], spawnOptions));
     const command = options.command ?? options.env?.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi";
-    const child = spawn(command, ["--mode", "rpc", "--no-session"], {
+    const child = spawn(command, [...(options.commandArgs ?? []), "--mode", "rpc", "--no-session"], {
         cwd: options.cwd,
         env: { ...process.env, ...options.env, ...(options.agentDir ? { PI_CODING_AGENT_DIR: path.resolve(options.agentDir) } : {}), NO_COLOR: "1" },
         stdio: ["pipe", "pipe", "pipe"],

package/dist/runtime/pi-model-catalog.mjs

@@ -33,7 +33,7 @@ const discoveryCache = new Map();
 export async function discoverPiModelCatalog(options) {
     if (!options.spawn) {
         const command = options.command ?? options.env?.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi";
-        const key = `${command}|${options.env?.PI_CODING_AGENT_DIR ?? ""}|${options.agentDir ?? ""}`;
+        const key = `${command}|${(options.commandArgs ?? []).join("\0")}|${options.env?.PI_CODING_AGENT_DIR ?? ""}|${options.agentDir ?? ""}`;
         const cached = discoveryCache.get(key);
         if (cached)
             return cached;
@@ -50,7 +50,7 @@ export async function discoverPiModelCatalog(options) {
 async function discoverPiModelCatalogUncached(options) {
     const spawn = options.spawn ?? ((command, args, spawnOptions) => nodeSpawn(command, [...args], spawnOptions));
     const command = options.command ?? options.env?.LARKIN_PI_COMMAND ?? process.env.LARKIN_PI_COMMAND ?? "pi";
-    const child = spawn(command, ["--mode", "rpc", "--no-session"], {
+    const child = spawn(command, [...(options.commandArgs ?? []), "--mode", "rpc", "--no-session"], {
         cwd: options.cwd,
         env: { ...process.env, ...options.env, ...(options.agentDir ? { PI_CODING_AGENT_DIR: path.resolve(options.agentDir) } : {}), NO_COLOR: "1" },
         stdio: ["pipe", "pipe", "pipe"],