larkin 0.4.29 → 0.5.1

package/dist/platform/config.mjs

@@ -5,15 +5,14 @@ import * as path from "node:path";
 import { TargetRootLayout, resolveConfigDir as resolveRootConfigDir } from "./root-layout.mjs";
 import { exactMode, fsyncDirectoryOf } from "./secure-metadata.mjs";
 import { CURRENT_RUNTIME_MODELS } from "../runtime/runtime-model-catalog.mjs";
-import { assertBuiltinPiAgentDirectory, piAgentDirectory } from "../runtime/pi-provider-config.mjs";
 import { fromUserRuntime, isAdapterRuntime, isUserRuntime, toUserRuntime } from "../runtime/user-runtime.mjs";
 import processInspect from "./process-inspect.cjs";
-import { applyPiProfileMigration, assertPiProfileMigrationAfterState, preparePiProfileMigration, releasePiProfileMigrationLock, rollbackPiProfileMigration, validatePiProfileMigrationState, } from "../runtime/pi-profile-migration.mjs";
 export { RUNTIME_OPTIONS, fromUserRuntime, isAdapterRuntime, isUserRuntime, runtimeOptionOf, runtimeOptionTarget, toUserRuntime, } from "../runtime/user-runtime.mjs";
 const TOP_FIELDS_V3 = new Set(["version", "serverId", "activeAgent", "agents"]);
 const TOP_FIELDS_V4 = new Set(["version", "serverId", "mentionPolicy", "activeAgent", "agents"]);
 const AGENT_FIELDS_V3 = new Set(["runtime", "model", "effort", "noMentionChats", "createdAt"]);
-const AGENT_FIELDS_V4 = new Set(["runtime", "model", "piDistribution", "effort", "mentionPolicy", "chatMentionPolicies", "createdAt"]);
+const AGENT_FIELDS_V4 = new Set(["runtime", "model", "effort", "mentionPolicy", "chatMentionPolicies", "createdAt"]);
+const LEGACY_AGENT_FIELDS = new Set(["piDistribution", "runtimeOption"]);
 const APP_ID = /^cli_[A-Za-z0-9]+$/;
 const CHAT_ID = /^oc_[A-Za-z0-9_-]+$/;
 const PI_EFFORTS = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
@@ -91,31 +90,51 @@ function runtimeSupportsEffort(runtime, effort) {
         : runtime === "codex" ? CODEX_EFFORTS.has(effort)
             : runtime === "claude" ? CLAUDE_EFFORTS.has(effort) : false;
 }
+function takeLegacyAgentFields(agent) {
+    const cleaned = {};
+    for (const [field, value] of Object.entries(agent)) {
+        if (!LEGACY_AGENT_FIELDS.has(field))
+            cleaned[field] = value;
+    }
+    return cleaned;
+}
+function isLegacyBuiltinAgentRecord(agent) {
+    if (!isPlainObject(agent))
+        return false;
+    return agent.piDistribution === "builtin" || agent.runtime === "builtin-pi" || agent.runtimeOption === "builtin-pi";
+}
+function canonicalizeLegacyStoredAgent(key, agent) {
+    const cleaned = takeLegacyAgentFields(agent);
+    if (cleaned.runtime === "builtin-pi" || isLegacyBuiltinAgentRecord(agent))
+        cleaned.runtime = "pi";
+    if (typeof cleaned.runtime !== "string" || !cleaned.runtime)
+        throw new Error(`Agent ${key}.runtime 必须是非空字符串`);
+    return cleaned;
+}
 function validateStoredAgent(key, agent, version) {
     if (!APP_ID.test(key))
         throw new Error(`Agent key 必须是安全的飞书 App ID（cli_ + ASCII 字母数字）：${key}`);
     if (!isPlainObject(agent))
         throw new Error(`Agent ${key} 必须是普通 object`);
-    assertAllowedFields(agent, version === 3 ? AGENT_FIELDS_V3 : AGENT_FIELDS_V4, `Agent ${key}`);
-    if (typeof agent.runtime !== "string" || !agent.runtime)
+    const canonical = canonicalizeLegacyStoredAgent(key, agent);
+    assertAllowedFields(canonical, version === 3 ? AGENT_FIELDS_V3 : AGENT_FIELDS_V4, `Agent ${key}`);
+    if (typeof canonical.runtime !== "string" || !canonical.runtime)
         throw new Error(`Agent ${key}.runtime 必须是非空字符串`);
-    if (!isAdapterRuntime(agent.runtime))
-        throw new Error(`Agent ${key}.runtime 未知：${agent.runtime}`);
-    if (typeof agent.model !== "string" || !agent.model)
+    if (!isAdapterRuntime(canonical.runtime))
+        throw new Error(`Agent ${key}.runtime 未知：${canonical.runtime}`);
+    if (typeof canonical.model !== "string" || !canonical.model)
         throw new Error(`Agent ${key}.model 必须是非空字符串`);
-    assertModel(agent.runtime, agent.model);
-    if (Object.hasOwn(agent, "piDistribution")) {
-        if (agent.runtime !== "pi" || (agent.piDistribution !== "external" && agent.piDistribution !== "builtin")) {
-            throw new Error(`Agent ${key}.piDistribution 只允许 Pi runtime 使用 external/builtin`);
-        }
-    }
+    assertModel(canonical.runtime, canonical.model);
+    Object.assign(agent, canonical);
+    for (const field of LEGACY_AGENT_FIELDS)
+        delete agent[field];
     if (Object.hasOwn(agent, "effort") && (typeof agent.effort !== "string" || !agent.effort))
         throw new Error(`Agent ${key}.effort 必须是非空字符串`);
     if (agent.model === "default" && Object.hasOwn(agent, "effort"))
         throw new Error(`Agent ${key}.model=default 时不能保存 effort`);
     if (typeof agent.effort === "string") {
-        if (!runtimeSupportsEffort(agent.runtime, agent.effort))
-            throw new Error(`Agent ${key}.effort=${agent.effort} 不在 ${agent.runtime} 安全档位中`);
+        if (!runtimeSupportsEffort(canonical.runtime, agent.effort))
+            throw new Error(`Agent ${key}.effort=${agent.effort} 不在 ${canonical.runtime} 安全档位中`);
     }
     if (version === 3 && Object.hasOwn(agent, "noMentionChats")) {
         if (!Array.isArray(agent.noMentionChats) || agent.noMentionChats.some((chat) => typeof chat !== "string" || !CHAT_ID.test(chat))) {
@@ -150,7 +169,6 @@ function hydratedStoredAgent(key, agent, version) {
     return {
         runtime: agent.runtime,
         model: agent.model,
-        ...(agent.piDistribution === "external" || agent.piDistribution === "builtin" ? { piDistribution: agent.piDistribution } : {}),
         ...(typeof agent.effort === "string" ? { effort: agent.effort } : {}),
         ...(version === 4 && (agent.mentionPolicy === "require" || agent.mentionPolicy === "free") ? { mentionPolicy: agent.mentionPolicy } : {}),
         ...(Object.keys(chatMentionPolicies).length ? { chatMentionPolicies, noMentionChats: Object.entries(chatMentionPolicies).filter(([, policy]) => policy === "free").map(([chatId]) => chatId) } : {}),
@@ -162,7 +180,6 @@ export function hydrateAgent(key, agent, configDir) {
     return {
         name: key, agentId: key, feishuAppId: key, feishuProfile: key,
         runtime: agent.runtime, model: agent.model,
-        ...(agent.piDistribution ? { piDistribution: agent.piDistribution } : {}),
         workspaceDir: layout.workspaceDir(key), stateDir: layout.agentStateDir(key),
         larkConfigDir: path.join(layout.agentStateDir(key), "lark-cli-config"),
         ...(agent.effort ? { effort: agent.effort } : {}),
@@ -283,9 +300,137 @@ function readConfigFile(file, root = path.dirname(file)) {
         throw error;
     }
 }
+function collectLegacyBuiltinAgentIds(raw) {
+    if (!isPlainObject(raw) || !isPlainObject(raw.agents))
+        return [];
+    return Object.entries(raw.agents).filter(([, agent]) => isLegacyBuiltinAgentRecord(agent)).map(([agentId]) => agentId);
+}
+function ownedPiProviderDirectory(configDir, agentId) {
+    if (!APP_ID.test(agentId))
+        throw new Error(`Pi Agent ID 格式无效：${agentId}`);
+    return path.join(path.resolve(configDir), "providers", "pi", agentId);
+}
+function userPiHome(env) {
+    const home = typeof env.HOME === "string" && env.HOME.trim() ? env.HOME : os.homedir();
+    return path.resolve(home, ".pi");
+}
+function isInsideOrEqual(candidate, root) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+function pathExists(target) {
+    try {
+        fs.lstatSync(target);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function shouldSkipOwnedPiDeletion(configDir, expected, env) {
+    let userPi;
+    try {
+        userPi = fs.realpathSync(userPiHome(env));
+    }
+    catch {
+        userPi = path.resolve(userPiHome(env));
+    }
+    let configRoot;
+    try {
+        configRoot = fs.realpathSync(path.resolve(configDir));
+    }
+    catch {
+        configRoot = path.resolve(configDir);
+    }
+    let resolvedExpected;
+    try {
+        resolvedExpected = fs.realpathSync(path.resolve(expected));
+    }
+    catch {
+        resolvedExpected = path.resolve(expected);
+    }
+    if (isInsideOrEqual(configRoot, userPi))
+        return "config root is inside the user ~/.pi directory";
+    if (isInsideOrEqual(resolvedExpected, userPi))
+        return "owned Pi directory is inside the user ~/.pi directory";
+    return null;
+}
+function deleteOwnedPiProviderDirectory(configDir, agentId, env = process.env) {
+    const expected = ownedPiProviderDirectory(configDir, agentId);
+    const skip = shouldSkipOwnedPiDeletion(configDir, expected, env);
+    if (skip) {
+        process.stderr.write(`[larkin] skipped leftover builtin Pi directory for ${agentId}: ${skip}\n`);
+        return;
+    }
+    const parent = path.dirname(expected);
+    if (!pathExists(parent) || !pathExists(expected))
+        return;
+    assertNoSymlinkAncestors(expected);
+    const rootReal = fs.realpathSync(path.resolve(configDir));
+    const parentReal = fs.realpathSync(parent);
+    const relative = path.relative(rootReal, parentReal);
+    if (relative.startsWith(`..${path.sep}`) || relative === ".." || path.isAbsolute(relative)) {
+        throw new Error("owned Pi provider directory escaped the config root");
+    }
+    if (path.basename(parent) !== "pi" || path.basename(path.dirname(parent)) !== "providers") {
+        throw new Error("owned Pi provider directory is not providers/pi/<agentId>");
+    }
+    const stat = fs.lstatSync(expected);
+    if (stat.isSymbolicLink())
+        throw new Error("owned Pi provider directory is a symlink");
+    if (!stat.isDirectory())
+        throw new Error("owned Pi provider directory must be a directory");
+    fs.rmSync(expected, { recursive: true, force: false });
+}
+function rewriteLegacyBuiltinAgents(raw) {
+    if (!isPlainObject(raw) || !isPlainObject(raw.agents))
+        return raw;
+    const legacyIds = new Set(collectLegacyBuiltinAgentIds(raw));
+    if (legacyIds.size === 0)
+        return raw;
+    const agents = {};
+    for (const [agentId, agent] of Object.entries(raw.agents)) {
+        if (!legacyIds.has(agentId) || !isPlainObject(agent)) {
+            agents[agentId] = agent;
+            continue;
+        }
+        const next = takeLegacyAgentFields(agent);
+        if (next.runtime === "builtin-pi" || isLegacyBuiltinAgentRecord(agent))
+            next.runtime = "pi";
+        agents[agentId] = next;
+    }
+    return { ...raw, agents };
+}
+function persistLegacyBuiltinMigration(layout, opts, env) {
+    const current = readConfigFile(layout.configFile, layout.root);
+    const migratedIds = collectLegacyBuiltinAgentIds(current.raw);
+    if (migratedIds.length === 0)
+        return current;
+    const rewritten = rewriteLegacyBuiltinAgents(current.raw);
+    const config = normalizeConfig(structuredClone(rewritten), layout.root, opts);
+    const bytes = atomicWriteConfig(layout.configFile, rewritten);
+    for (const agentId of migratedIds) {
+        const agent = config.agents[agentId];
+        const model = typeof agent?.model === "string" ? agent.model : "unknown";
+        process.stderr.write(`[larkin] migrated Agent ${agentId} from builtin-pi to pi (model=${model})\n`);
+        try {
+            deleteOwnedPiProviderDirectory(layout.root, agentId, env);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`[larkin] failed to delete leftover builtin Pi directory for ${agentId}: ${reason}\n`);
+        }
+    }
+    return { raw: rewritten, bytes };
+}
 export function loadConfig(env = process.env, opts = {}) {
     const layout = TargetRootLayout.fromConfigDir(resolveConfigDir(env));
-    const { raw, bytes } = readConfigFile(layout.configFile, layout.root);
+    const initial = readConfigFile(layout.configFile, layout.root);
+    const { raw, bytes } = collectLegacyBuiltinAgentIds(initial.raw).length
+        ? withConfigLock(layout, () => persistLegacyBuiltinMigration(layout, opts, env))
+        : initial;
     return { configDir: layout.configDir, file: layout.configFile, revision: revision(bytes), config: normalizeConfig(raw, layout.root, opts) };
 }
 export function selectAgent(config, env = process.env) {
@@ -306,8 +451,6 @@ export function toStored(config) {
     const out = { version: 4, serverId: config.serverId, mentionPolicy: config.mentionPolicy, activeAgent: config.activeAgent, agents: {} };
     for (const [key, agent] of Object.entries(config.agents || {})) {
         const stored = { runtime: agent.runtime, model: agent.model };
-        if (agent.piDistribution)
-            stored.piDistribution = agent.piDistribution;
         if (typeof agent.effort === "string" && agent.effort)
             stored.effort = agent.effort;
         if (agent.mentionPolicy)
@@ -349,7 +492,8 @@ function agentSignature(config, agentId) {
         throw new Error(`Agent 不存在：${agentId}`);
     const chats = Object.fromEntries(Object.entries(agent.chatMentionPolicies || {}).sort(([left], [right]) => left.localeCompare(right)));
     return revision(JSON.stringify({
-        runtime: agent.runtime, model: agent.model, piDistribution: agent.piDistribution ?? null, effort: agent.effort ?? null,
+        schema: 2,
+        runtime: agent.runtime, model: agent.model, effort: agent.effort ?? null,
         globalMentionPolicy: config.mentionPolicy, agentMentionPolicy: agent.mentionPolicy ?? null, chatMentionPolicies: chats,
     }));
 }
@@ -386,12 +530,6 @@ function writeApplyFile(configDir, value) {
     atomicWriteConfig(applyStateFile(configDir), value);
 }
 function rollbackJournalFile(root) { return path.join(root, CONFIG_ROLLBACK_JOURNAL_FILE); }
-function migrationJournalFile(root) { return path.join(root, ".pi-profile-migration-journal.json"); }
-function assertMigrationTarget(root, agentId, migration) {
-    if (migration.agentId !== agentId || path.resolve(migration.targetDir) !== path.join(path.resolve(root), "providers", "pi", agentId)) {
-        throw new Error("Pi profile migration target is invalid");
-    }
-}
 function restoreTargetApplyState(root, targetAgentId, beforeRevision, before) {
     const current = readApplyFile(root);
     const agents = { ...current.agents };
@@ -430,15 +568,9 @@ function recoverRollbackJournal(root) {
     const beforeRaw = JSON.parse(beforeBytes.toString("utf8"));
     normalizeConfig(beforeRaw, root);
     validateApplyState(journal.beforeApplyState);
-    if (journal.migration !== undefined) {
-        validatePiProfileMigrationState(journal.migration);
-        assertMigrationTarget(root, journal.targetAgentId, journal.migration);
-    }
     const current = readConfigFile(path.join(root, "config.json"), root);
     const currentRevision = revision(current.bytes);
     if (currentRevision === journal.expectedAfterRevision) {
-        if (journal.migration)
-            rollbackPiProfileMigration(journal.migration);
         atomicWriteBytes(path.join(root, "config.json"), beforeBytes);
         restoreTargetApplyState(root, journal.targetAgentId, journal.beforeRevision, journal.beforeApplyState);
     }
@@ -453,47 +585,6 @@ function recoverRollbackJournal(root) {
     fs.unlinkSync(file);
     fsyncDirectoryOf(file);
 }
-function recoverMigrationJournal(root) {
-    const file = migrationJournalFile(root);
-    const bytes = readPrivateFile(file, root, PROFILE_MIGRATION_ROLLBACK_LIMIT_BYTES, "Pi profile migration journal");
-    if (bytes === null)
-        return;
-    let journal;
-    try {
-        journal = JSON.parse(bytes.toString("utf8"));
-    }
-    catch {
-        throw new Error("Pi profile migration journal is invalid");
-    }
-    if (journal.version !== 1 || journal.phase !== "forward" || typeof journal.targetAgentId !== "string"
-        || typeof journal.beforeRevision !== "string" || typeof journal.expectedAfterRevision !== "string" || !journal.migration) {
-        throw new Error("Pi profile migration journal is invalid");
-    }
-    validatePiProfileMigrationState(journal.migration);
-    assertMigrationTarget(root, journal.targetAgentId, journal.migration);
-    const current = readConfigFile(path.join(root, "config.json"), root);
-    const currentRevision = revision(current.bytes);
-    if (currentRevision === journal.beforeRevision) {
-        // Forward import did not publish config. The migration helper restores only
-        // files still matching its expected post-import hashes.
-        try {
-            rollbackPiProfileMigration(journal.migration);
-        }
-        catch (error) {
-            throw new Error(`Pi profile migration recovery refused: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    }
-    else if (currentRevision === journal.expectedAfterRevision) {
-        // Config won the race; verify the provider target before finalizing.
-        const migration = journal.migration;
-        assertPiProfileMigrationAfterState(migration);
-    }
-    else
-        throw new Error("Pi profile migration journal conflicts with the current configuration");
-    releasePiProfileMigrationLock(journal.migration);
-    fs.unlinkSync(file);
-    fsyncDirectoryOf(file);
-}
 export function configApplyState(env, config) {
     let state;
     try {
@@ -570,38 +661,16 @@ function applyMutation(config, mutation) {
         agent.noMentionChats = Object.entries(policies).filter(([, value]) => value === "free").map(([chatId]) => chatId);
         return { scope: "chat", agentId: mutation.agentId, runtimeChange: false, affectedAgentIds: [mutation.agentId] };
     }
-    if (mutation.kind === "set-agent-pi-distribution") {
-        if (agent.runtime !== "pi")
-            throw new Error(`Agent ${mutation.agentId} 不是 Pi runtime`);
-        if (mutation.distribution !== "builtin" && mutation.distribution !== "external")
-            throw new Error("Pi distribution 只允许 builtin/external");
-        agent.piDistribution = mutation.distribution;
-    }
-    else if (mutation.kind === "set-agent-runtime") {
+    if (mutation.kind === "set-agent-runtime") {
         if (!isUserRuntime(mutation.runtime))
             throw new Error(`未知 runtime：${mutation.runtime}`);
         const stored = fromUserRuntime(mutation.runtime);
-        if (stored.piDistribution === "builtin") {
-            try {
-                assertBuiltinPiAgentDirectory(piAgentDirectory(config.configDir, mutation.agentId));
-            }
-            catch (error) {
-                throw new Error(`无法切换到 builtin-pi：${error instanceof Error ? error.message : String(error)}。请使用 Dashboard Provider Credentials 或 larkin pi-auth login。`);
-            }
-        }
         assertModel(stored.runtime, mutation.model || "default");
         agent.runtime = stored.runtime;
         agent.model = mutation.model || "default";
-        if (stored.piDistribution)
-            agent.piDistribution = stored.piDistribution;
-        else
-            delete agent.piDistribution;
         delete agent.effort;
     }
     else if (mutation.kind === "set-agent-model") {
-        if (mutation.requireBuiltinPi && (agent.runtime !== "pi" || agent.piDistribution !== "builtin")) {
-            throw new Error(`Agent ${mutation.agentId} 不是内置 Pi`);
-        }
         if (!mutation.model.trim())
             throw new Error("model 不能为空");
         assertModel(agent.runtime, mutation.model);
@@ -807,7 +876,6 @@ function acquireConfigLock(layout) {
 function withConfigLock(layout, action) {
     const held = acquireConfigLock(layout);
     try {
-        recoverMigrationJournal(layout.root);
         recoverRollbackJournal(layout.root);
         return action();
     }
@@ -822,7 +890,6 @@ export async function withConfigMutationLockAsync(env, action) {
     const layout = TargetRootLayout.fromConfigDir(resolveConfigDir(env));
     const held = acquireConfigLock(layout);
     try {
-        recoverMigrationJournal(layout.root);
         recoverRollbackJournal(layout.root);
         return await action();
     }
@@ -922,10 +989,6 @@ function readConfigSnapshot(file, root) {
     if (JSON.stringify(beforeRaw) !== JSON.stringify(parsed.beforeConfig))
         throw new Error("config snapshot before config does not match bytes");
     validateApplyState(parsed.beforeApplyState);
-    if (parsed.migration !== undefined) {
-        validatePiProfileMigrationState(parsed.migration);
-        assertMigrationTarget(root, parsed.targetAgentId, parsed.migration);
-    }
     return parsed;
 }
 function atomicWriteBytes(file, bytes, limit = CONFIG_LIMIT_BYTES) {
@@ -969,12 +1032,6 @@ export function mutateConfig(env, mutation, authority, options = {}) {
             throw new Error(`没找到配置 ${layout.configFile}，先跑 larkin setup`);
         const config = normalizeConfig(current.raw, layout.root);
         const priorSignatures = Object.fromEntries(Object.keys(config.agents).map((agentId) => [agentId, agentSignature(config, agentId)]));
-        if (options.importExternalProfile && (mutation.kind !== "set-agent-pi-distribution" || mutation.distribution !== "builtin")) {
-            throw new Error("external Pi profile import is only valid for builtin Pi distribution");
-        }
-        const migrationPlan = options.importExternalProfile && mutation.kind === "set-agent-pi-distribution"
-            ? preparePiProfileMigration(env, layout.root, mutation.agentId, "builtin")
-            : undefined;
         const changed = applyMutation(config, mutation);
         const stored = toStored(config);
         normalizeConfig(stored, layout.root);
@@ -995,16 +1052,8 @@ export function mutateConfig(env, mutation, authority, options = {}) {
                 version: 2, targetAgentId: changed.agentId, beforeRevision: revision(current.bytes), afterRevision: nextRevision,
                 afterSignature: agentSignature(config, changed.agentId), beforeConfig: current.raw,
                 beforeConfigBytes: current.bytes.toString("base64"), beforeApplyState,
-                ...(migrationPlan ? { migration: migrationPlan.state } : {}),
             });
         }
-        if (migrationPlan) {
-            atomicWriteConfig(migrationJournalFile(layout.root), {
-                version: 1, phase: "forward", targetAgentId: changed.agentId, beforeRevision: revision(current.bytes),
-                expectedAfterRevision: nextRevision, migration: migrationPlan.state,
-            }, PROFILE_MIGRATION_ROLLBACK_LIMIT_BYTES);
-            applyPiProfileMigration(migrationPlan);
-        }
         atomicWriteConfig(layout.configFile, stored);
         let fullyApplied = changed.affectedAgentIds.length === 0;
         try {
@@ -1028,17 +1077,6 @@ export function mutateConfig(env, mutation, authority, options = {}) {
         catch {
             fullyApplied = false; /* Config persistence remains authoritative. */
         }
-        if (migrationPlan) {
-            releasePiProfileMigrationLock(migrationPlan.state);
-            try {
-                fs.unlinkSync(migrationJournalFile(layout.root));
-                fsyncDirectoryOf(migrationJournalFile(layout.root));
-            }
-            catch (error) {
-                if (error.code !== "ENOENT")
-                    throw error;
-            }
-        }
         return {
             revision: nextRevision, previousRevision: revision(current.bytes), changedScope: changed.scope,
             ...(changed.agentId ? { agentId: changed.agentId } : {}), persisted: true,
@@ -1062,11 +1100,8 @@ export function rollbackConfig(env, snapshotFile) {
         const journal = {
             version: 1, targetAgentId: snapshot.targetAgentId, expectedAfterRevision: snapshot.afterRevision,
             beforeRevision: snapshot.beforeRevision, beforeConfigBytes: snapshot.beforeConfigBytes, beforeApplyState: snapshot.beforeApplyState,
-            ...(snapshot.migration ? { migration: snapshot.migration } : {}),
         };
         atomicWriteConfig(rollbackJournalFile(layout.root), journal, PROFILE_MIGRATION_ROLLBACK_LIMIT_BYTES);
-        if (snapshot.migration)
-            rollbackPiProfileMigration(snapshot.migration);
         const bytes = atomicWriteBytes(layout.configFile, beforeBytes);
         restoreTargetApplyState(layout.root, snapshot.targetAgentId, snapshot.beforeRevision, snapshot.beforeApplyState);
         fs.unlinkSync(rollbackJournalFile(layout.root));
@@ -1088,7 +1123,7 @@ export function commitSetupConfig(env, expectedRevision, nextStored) {
 export function safeConfigView(config, onlyAgentId, chatId, applyState) {
     const entries = onlyAgentId ? [[onlyAgentId, config.agents[onlyAgentId]]] : Object.entries(config.agents);
     const agents = entries.filter((entry) => Boolean(entry[1])).map(([agentId, agent]) => ({
-        agentId, runtime: agent.runtime, runtimeOption: toUserRuntime(agent.runtime, agent.piDistribution), model: agent.model, piDistribution: agent.piDistribution ?? (agent.runtime === "pi" ? "external" : null), effort: agent.effort ?? null,
+        agentId, runtime: agent.runtime, runtimeOption: toUserRuntime(agent.runtime), model: agent.model, effort: agent.effort ?? null,
         mention: {
             override: agent.mentionPolicy ?? "inherit",
             effective: agent.mentionPolicy ?? config.mentionPolicy,

package/dist/runtime/pi-artifact-provenance.mjs

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { exactMode } from "../platform/secure-metadata.mjs";
 export const PI_RUNTIME_ARTIFACT_MANIFEST = ".larkin-pi-owned-artifacts.json";
-export const PI_RUNTIME_ARTIFACT_NAMES = [".larkin-official-pi-package", "models-store.json", "npm"];
+export const PI_RUNTIME_ARTIFACT_NAMES = ["models-store.json", "npm"];
 const MAX_FILE_BYTES = 256 * 1024 * 1024;
 const MAX_ENTRIES = 4096;
 function digest(value) {
@@ -53,7 +53,7 @@ function readManifest(file) {
         if (!stat.isFile() || !exactMode(stat, 0o600) || stat.size > 1024 * 1024)
             throw new Error("Pi artifact provenance manifest is unsafe");
         const value = JSON.parse(fs.readFileSync(file, "utf8"));
-        if (value?.version !== 1 || value.owner !== "larkin-builtin-pi" || !value.directory || !value.artifacts)
+        if (value?.version !== 1 || (value.owner !== "larkin-pi" && value.owner !== "larkin-builtin-pi") || !value.directory || !value.artifacts)
             throw new Error("Pi artifact provenance manifest is invalid");
         return value;
     }
@@ -83,7 +83,7 @@ export function recordPiRuntimeArtifactProvenance(targetDir, beforeEntries, boun
     const manifestFile = path.join(targetDir, PI_RUNTIME_ARTIFACT_MANIFEST);
     const existing = readManifest(manifestFile);
     const manifest = existing ?? {
-        version: 1, owner: "larkin-builtin-pi", directory: { device: String(target.dev), inode: String(target.ino) },
+        version: 1, owner: "larkin-pi", directory: { device: String(target.dev), inode: String(target.ino) },
         recordedAt: new Date(boundaryAt).toISOString(), artifacts: {},
     };
     if (manifest.directory.device !== String(target.dev) || manifest.directory.inode !== String(target.ino))

package/dist/runtime/pi-bash-timeout-extension.mjs

@@ -2,16 +2,15 @@ import { createBashToolDefinition } from "@earendil-works/pi-coding-agent";
 /**
  * pi bash 工具超时护栏扩展。
  *
- * 由 Larkin 向 builtin Pi 传入 inline factory，或通过 external Pi 的
- * `pi --extension/-e <bundle>` 注入，覆盖内置 `bash` 工具：
+ * 通过用户安装的 Pi 的 `pi --extension/-e <bundle>` 注入，覆盖内置 `bash` 工具：
  * - 无论模型是否传 `timeout`，都强制收窄到 <= MAX_BASH_SECONDS（默认 60s），
  *   避免单个 bash 调用无限期占住整个 agent 回合（issue #55）。
  * - 超时时 pi 会杀掉整个进程树（不残留卡死子进程，issue #56 的进程堆积），
  *   并在返回的错误里明确提示：长任务必须改用后台 subagent
  *   （Agent(run_in_background: true)，来自 pi-subagents 扩展）。
  *
- * 这是 pi 扩展，运行在 Pi RPC 子进程内部；build.mjs 仍为 external Pi
- * 单独产出注入 bundle。
+ * 这是 pi 扩展，运行在 Pi RPC 子进程内部；build.mjs 把 `@earendil-works/pi-*`
+ * 标为 external，由 host Pi 的 loader 在运行时提供模块。
  */
 /** 前台 bash 的硬性上限（秒）。issue #55 建议默认 60s。 */
 const MAX_BASH_SECONDS = 60;
@@ -24,7 +23,7 @@ function effectiveBashTimeout() {
 }
 export default function (pi) {
     const cwd = process.cwd();
-    // Built-in bash tool definition (keeps renderCall/renderResult/system-prompt metadata).
+    // Host bash tool definition (keeps renderCall/renderResult/system-prompt metadata).
     const builtin = createBashToolDefinition(cwd);
     const MAX = effectiveBashTimeout();
     const SUBAGENT_GUIDANCE = `This command exceeded the ${MAX}s foreground hard limit. ` +

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 = 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"));
-const pi_provider_config_js_1 = require("./pi-provider-config.cjs");
+/** 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,23 +256,53 @@ 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 = 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;
+    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 !== 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");
+    assertSupportedPiVersion(capabilities.version);
+    if (capabilities.trustedProtocol === true) {
+        throw new Error("external Pi cannot use a trusted protocol bypass");
     }
     const contextWindow = capabilities.contextWindow ?? capabilities.model?.contextWindow;
     const expected = (() => {
@@ -286,8 +318,6 @@ function verifyPiCapabilities(capabilities) {
     }
     if (capabilities.compactRpc !== true)
         throw new Error("Pi compact RPC capability is missing");
-    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}`);