larkin 0.4.27 → 0.4.29

package/dist/feishu/host-shell.cjs

@@ -208,26 +208,72 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
             runtimeReadiness: { runtime: agent.runtime, state: "unavailable", reason, nextAction: "Wait for the current daemon epoch to publish Runtime readiness.", observedAt: new Date().toISOString() },
         });
     };
+    const unresolvedCurrentAuth = (agent) => {
+        try {
+            const persisted = (0, runtime_readiness_js_1.parsePersistedAuthFailure)(stateStore(agent).readJson("agentState", {}));
+            if (!persisted)
+                return null;
+            // 只使用当前 agentState 作用域标记，不扫描历史 delivery 的 authProvider。
+            return (0, runtime_readiness_js_1.authFailureAppliesTo)({
+                runtime: agent.runtime,
+                model: agent.model,
+                piDistribution: agent.piDistribution,
+            }, persisted) ? persisted : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const projectReadyUnlessUnresolvedAuth = (agent, observedAt) => {
+        const failure = unresolvedCurrentAuth(agent);
+        if (failure) {
+            hostState.updateStatus(agent, {
+                runtimeReadiness: { ...(0, runtime_readiness_js_1.readinessForPersistedAuthFailure)(failure), observedAt },
+            });
+            return;
+        }
+        hostState.updateStatus(agent, { runtimeReadiness: { runtime: agent.runtime, state: "ready", observedAt } });
+    };
     const recordInboundDeliveryFailure = (agent, code) => {
         const at = new Date().toISOString();
         const reason = "Inbound Runtime delivery failed non-retryably; durable Inbox/ledger state is retained for recovery.";
         const nextAction = "Inspect the delivery/status error, correct the Runtime or canonical Inbox state, then restart to replay safely.";
+        const currentReadiness = hostState.readStatus(agent).runtimeReadiness;
         hostState.updateStatus(agent, {
             inboundDeliveryHealth: { state: "error", code, at, reason, nextAction },
-            runtimeReadiness: { runtime: agent.runtime, state: "incompatible", reason, nextAction },
+            ...(currentReadiness?.state === "unauthenticated" ? {} : {
+                runtimeReadiness: { runtime: agent.runtime, state: "incompatible", reason, nextAction },
+            }),
         });
         hostState.recordStatusError(agent, `${reason} ${nextAction} code=${code}`);
     };
     const agentStates = new Map();
+    const mergePersistedAgentState = (record) => {
+        const latest = record.store.readJson("agentState", {});
+        if (isRecord(latest.previousSessions)) {
+            record.state.previousSessions = {
+                ...latest.previousSessions,
+                ...(record.state.previousSessions ?? {}),
+            };
+        }
+        const persisted = (0, runtime_readiness_js_1.parsePersistedAuthFailure)(latest);
+        if (persisted) {
+            record.state.authFailure = persisted;
+            if (persisted.kind === "missing-provider" && persisted.provider) {
+                record.state.authFailureProvider = persisted.provider;
+            }
+            else {
+                delete record.state.authFailureProvider;
+            }
+        }
+        else {
+            delete record.state.authFailure;
+            delete record.state.authFailureProvider;
+        }
+    };
     const saveAgentState = (record) => {
         try {
-            const latest = record.store.readJson("agentState", {});
-            if (isRecord(latest.previousSessions)) {
-                record.state.previousSessions = {
-                    ...latest.previousSessions,
-                    ...(record.state.previousSessions ?? {}),
-                };
-            }
+            mergePersistedAgentState(record);
             record.store.writeJson("agentState", record.state);
         }
         catch (error) {
@@ -1276,12 +1322,16 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
                         observedAt,
                     },
                 });
-            else if (message.readiness)
-                hostState.updateStatus(agent, { runtimeReadiness: { ...message.readiness, observedAt } });
+            else if (message.readiness) {
+                if (message.readiness.state === "ready" && unresolvedCurrentAuth(agent)) {
+                    projectReadyUnlessUnresolvedAuth(agent, observedAt);
+                }
+                else {
+                    hostState.updateStatus(agent, { runtimeReadiness: { ...message.readiness, observedAt } });
+                }
+            }
             else if (message.status === "active")
-                hostState.updateStatus(agent, { runtimeReadiness: {
-                        runtime: agent.runtime, state: "ready", observedAt,
-                    } });
+                projectReadyUnlessUnresolvedAuth(agent, observedAt);
             if (message.status === "active") {
                 const redeliveryTimer = setTimeout(() => {
                     void reminder.redeliverUnread(agent).catch((error) => log("启动补投失败", errorMessage(error)));
@@ -1448,6 +1498,7 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
                         record.state.sessions[agent.runtime] = reset.sessionId;
                     else
                         delete record.state.sessions[agent.runtime];
+                    mergePersistedAgentState(record);
                     record.store.writeJson("agentState", record.state);
                 }
                 if (!reset.sessionId) {
@@ -1455,11 +1506,11 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
                     hostState.updateStatus(agent, {
                         session: { runtime: agent.runtime, id: null, launchId: null, startedAt: observedAt,
                             lastSeenAt: null, lastTurnAt: null, turns: 0 },
-                        runtimeReadiness: { runtime: agent.runtime, state: "ready", observedAt },
                     });
+                    projectReadyUnlessUnresolvedAuth(agent, observedAt);
                 }
                 else if (reset.runtimeReady) {
-                    hostState.updateStatus(agent, { runtimeReadiness: { runtime: agent.runtime, state: "ready", observedAt: new Date().toISOString() } });
+                    projectReadyUnlessUnresolvedAuth(agent, new Date().toISOString());
                 }
             }
             catch (error) {
@@ -1527,7 +1578,7 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
                 throw Object.assign(error instanceof Error ? error : new Error(String(error)), readinessProjection());
             }
             if (recovery.runtimeReady) {
-                hostState.updateStatus(agent, { runtimeReadiness: { runtime: agent.runtime, state: "ready", observedAt: new Date().toISOString() } });
+                projectReadyUnlessUnresolvedAuth(agent, new Date().toISOString());
             }
             const record = agentStates.get(agentId);
             try {
@@ -1536,6 +1587,7 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
                         record.state.sessions[agent.runtime] = recovery.sessionId;
                     else
                         delete record.state.sessions[agent.runtime];
+                    mergePersistedAgentState(record);
                     record.store.writeJson("agentState", record.state);
                 }
             }

package/dist/feishu/host-shell.mjs

@@ -16,7 +16,7 @@ import { inboxAuditRegistryFile, observeInboxAuditTarget } from "../agent/missed
 import { HostChannelBusiness } from "./host-channel-business.mjs";
 import { HostInteractionOrchestrator } from "./interaction-orchestrator.mjs";
 import { targetFor } from "./message-policy.mjs";
-import { providerAuthenticationFailureReadiness, RuntimePrerequisiteError } from "../runtime/runtime-readiness.mjs";
+import { authFailureAppliesTo, parsePersistedAuthFailure, providerAuthenticationFailureReadiness, readinessForPersistedAuthFailure, RuntimePrerequisiteError, } from "../runtime/runtime-readiness.mjs";
 import { readDocumentCommentSubscription, verifyCallbackProbe } from "../platform/callback-capability.mjs";
 import { loadConfig, resolveMentionPolicy } from "../platform/config.mjs";
 import { processCommandToken } from "../app/internal-command.mjs";
@@ -168,26 +168,72 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
             runtimeReadiness: { runtime: agent.runtime, state: "unavailable", reason, nextAction: "Wait for the current daemon epoch to publish Runtime readiness.", observedAt: new Date().toISOString() },
         });
     };
+    const unresolvedCurrentAuth = (agent) => {
+        try {
+            const persisted = parsePersistedAuthFailure(stateStore(agent).readJson("agentState", {}));
+            if (!persisted)
+                return null;
+            // 只使用当前 agentState 作用域标记，不扫描历史 delivery 的 authProvider。
+            return authFailureAppliesTo({
+                runtime: agent.runtime,
+                model: agent.model,
+                piDistribution: agent.piDistribution,
+            }, persisted) ? persisted : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const projectReadyUnlessUnresolvedAuth = (agent, observedAt) => {
+        const failure = unresolvedCurrentAuth(agent);
+        if (failure) {
+            hostState.updateStatus(agent, {
+                runtimeReadiness: { ...readinessForPersistedAuthFailure(failure), observedAt },
+            });
+            return;
+        }
+        hostState.updateStatus(agent, { runtimeReadiness: { runtime: agent.runtime, state: "ready", observedAt } });
+    };
     const recordInboundDeliveryFailure = (agent, code) => {
         const at = new Date().toISOString();
         const reason = "Inbound Runtime delivery failed non-retryably; durable Inbox/ledger state is retained for recovery.";
         const nextAction = "Inspect the delivery/status error, correct the Runtime or canonical Inbox state, then restart to replay safely.";
+        const currentReadiness = hostState.readStatus(agent).runtimeReadiness;
         hostState.updateStatus(agent, {
             inboundDeliveryHealth: { state: "error", code, at, reason, nextAction },
-            runtimeReadiness: { runtime: agent.runtime, state: "incompatible", reason, nextAction },
+            ...(currentReadiness?.state === "unauthenticated" ? {} : {
+                runtimeReadiness: { runtime: agent.runtime, state: "incompatible", reason, nextAction },
+            }),
         });
         hostState.recordStatusError(agent, `${reason} ${nextAction} code=${code}`);
     };
     const agentStates = new Map();
+    const mergePersistedAgentState = (record) => {
+        const latest = record.store.readJson("agentState", {});
+        if (isRecord(latest.previousSessions)) {
+            record.state.previousSessions = {
+                ...latest.previousSessions,
+                ...(record.state.previousSessions ?? {}),
+            };
+        }
+        const persisted = parsePersistedAuthFailure(latest);
+        if (persisted) {
+            record.state.authFailure = persisted;
+            if (persisted.kind === "missing-provider" && persisted.provider) {
+                record.state.authFailureProvider = persisted.provider;
+            }
+            else {
+                delete record.state.authFailureProvider;
+            }
+        }
+        else {
+            delete record.state.authFailure;
+            delete record.state.authFailureProvider;
+        }
+    };
     const saveAgentState = (record) => {
         try {
-            const latest = record.store.readJson("agentState", {});
-            if (isRecord(latest.previousSessions)) {
-                record.state.previousSessions = {
-                    ...latest.previousSessions,
-                    ...(record.state.previousSessions ?? {}),
-                };
-            }
+            mergePersistedAgentState(record);
             record.store.writeJson("agentState", record.state);
         }
         catch (error) {
@@ -1236,12 +1282,16 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
                         observedAt,
                     },
                 });
-            else if (message.readiness)
-                hostState.updateStatus(agent, { runtimeReadiness: { ...message.readiness, observedAt } });
+            else if (message.readiness) {
+                if (message.readiness.state === "ready" && unresolvedCurrentAuth(agent)) {
+                    projectReadyUnlessUnresolvedAuth(agent, observedAt);
+                }
+                else {
+                    hostState.updateStatus(agent, { runtimeReadiness: { ...message.readiness, observedAt } });
+                }
+            }
             else if (message.status === "active")
-                hostState.updateStatus(agent, { runtimeReadiness: {
-                        runtime: agent.runtime, state: "ready", observedAt,
-                    } });
+                projectReadyUnlessUnresolvedAuth(agent, observedAt);
             if (message.status === "active") {
                 const redeliveryTimer = setTimeout(() => {
                     void reminder.redeliverUnread(agent).catch((error) => log("启动补投失败", errorMessage(error)));
@@ -1408,6 +1458,7 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
                         record.state.sessions[agent.runtime] = reset.sessionId;
                     else
                         delete record.state.sessions[agent.runtime];
+                    mergePersistedAgentState(record);
                     record.store.writeJson("agentState", record.state);
                 }
                 if (!reset.sessionId) {
@@ -1415,11 +1466,11 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
                     hostState.updateStatus(agent, {
                         session: { runtime: agent.runtime, id: null, launchId: null, startedAt: observedAt,
                             lastSeenAt: null, lastTurnAt: null, turns: 0 },
-                        runtimeReadiness: { runtime: agent.runtime, state: "ready", observedAt },
                     });
+                    projectReadyUnlessUnresolvedAuth(agent, observedAt);
                 }
                 else if (reset.runtimeReady) {
-                    hostState.updateStatus(agent, { runtimeReadiness: { runtime: agent.runtime, state: "ready", observedAt: new Date().toISOString() } });
+                    projectReadyUnlessUnresolvedAuth(agent, new Date().toISOString());
                 }
             }
             catch (error) {
@@ -1487,7 +1538,7 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
                 throw Object.assign(error instanceof Error ? error : new Error(String(error)), readinessProjection());
             }
             if (recovery.runtimeReady) {
-                hostState.updateStatus(agent, { runtimeReadiness: { runtime: agent.runtime, state: "ready", observedAt: new Date().toISOString() } });
+                projectReadyUnlessUnresolvedAuth(agent, new Date().toISOString());
             }
             const record = agentStates.get(agentId);
             try {
@@ -1496,6 +1547,7 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
                         record.state.sessions[agent.runtime] = recovery.sessionId;
                     else
                         delete record.state.sessions[agent.runtime];
+                    mergePersistedAgentState(record);
                     record.store.writeJson("agentState", record.state);
                 }
             }

package/dist/platform/config.cjs

@@ -36,6 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.toUserRuntime = exports.runtimeOptionTarget = exports.runtimeOptionOf = exports.isUserRuntime = exports.isAdapterRuntime = exports.fromUserRuntime = exports.RUNTIME_OPTIONS = void 0;
 exports.loadRuntimeModels = loadRuntimeModels;
 exports.defaultModelFor = defaultModelFor;
 exports.resolveConfigDir = resolveConfigDir;
@@ -52,6 +53,8 @@ exports.resolveAgentGlobalMentionPolicy = resolveAgentGlobalMentionPolicy;
 exports.runtimeConfigSignature = runtimeConfigSignature;
 exports.configApplyState = configApplyState;
 exports.markConfigApplied = markConfigApplied;
+exports.withConfigMutationLock = withConfigMutationLock;
+exports.withConfigMutationLockAsync = withConfigMutationLockAsync;
 exports.mutateConfig = mutateConfig;
 exports.rollbackConfig = rollbackConfig;
 exports.commitSetupConfig = commitSetupConfig;
@@ -63,8 +66,18 @@ const path = __importStar(require("node:path"));
 const root_layout_js_1 = require("./root-layout.cjs");
 const secure_metadata_js_1 = require("./secure-metadata.cjs");
 const runtime_model_catalog_js_1 = require("../runtime/runtime-model-catalog.cjs");
+const pi_provider_config_js_1 = require("../runtime/pi-provider-config.cjs");
+const user_runtime_js_1 = require("../runtime/user-runtime.cjs");
 const process_inspect_cjs_1 = __importDefault(require("./process-inspect.cjs"));
 const pi_profile_migration_js_1 = require("../runtime/pi-profile-migration.cjs");
+var user_runtime_js_2 = require("../runtime/user-runtime.cjs");
+Object.defineProperty(exports, "RUNTIME_OPTIONS", { enumerable: true, get: function () { return user_runtime_js_2.RUNTIME_OPTIONS; } });
+Object.defineProperty(exports, "fromUserRuntime", { enumerable: true, get: function () { return user_runtime_js_2.fromUserRuntime; } });
+Object.defineProperty(exports, "isAdapterRuntime", { enumerable: true, get: function () { return user_runtime_js_2.isAdapterRuntime; } });
+Object.defineProperty(exports, "isUserRuntime", { enumerable: true, get: function () { return user_runtime_js_2.isUserRuntime; } });
+Object.defineProperty(exports, "runtimeOptionOf", { enumerable: true, get: function () { return user_runtime_js_2.runtimeOptionOf; } });
+Object.defineProperty(exports, "runtimeOptionTarget", { enumerable: true, get: function () { return user_runtime_js_2.runtimeOptionTarget; } });
+Object.defineProperty(exports, "toUserRuntime", { enumerable: true, get: function () { return user_runtime_js_2.toUserRuntime; } });
 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"]);
@@ -105,7 +118,8 @@ function loadRuntimeModels() {
     return runtimeModels;
 }
 function defaultModelFor(runtime) {
-    const models = loadRuntimeModels()[runtime];
+    const adapter = (0, user_runtime_js_1.isUserRuntime)(runtime) ? (0, user_runtime_js_1.fromUserRuntime)(runtime).runtime : runtime;
+    const models = loadRuntimeModels()[adapter];
     if (!models)
         throw new Error(`runtime 模型目录不存在 runtime: ${runtime}`);
     return models[0].id;
@@ -153,7 +167,7 @@ function validateStoredAgent(key, agent, version) {
     assertAllowedFields(agent, version === 3 ? AGENT_FIELDS_V3 : AGENT_FIELDS_V4, `Agent ${key}`);
     if (typeof agent.runtime !== "string" || !agent.runtime)
         throw new Error(`Agent ${key}.runtime 必须是非空字符串`);
-    if (!loadRuntimeModels()[agent.runtime])
+    if (!(0, user_runtime_js_1.isAdapterRuntime)(agent.runtime))
         throw new Error(`Agent ${key}.runtime 未知：${agent.runtime}`);
     if (typeof agent.model !== "string" || !agent.model)
         throw new Error(`Agent ${key}.model 必须是非空字符串`);
@@ -632,16 +646,30 @@ function applyMutation(config, mutation) {
         agent.piDistribution = mutation.distribution;
     }
     else if (mutation.kind === "set-agent-runtime") {
-        if (!loadRuntimeModels()[mutation.runtime])
+        if (!(0, user_runtime_js_1.isUserRuntime)(mutation.runtime))
             throw new Error(`未知 runtime：${mutation.runtime}`);
-        assertModel(mutation.runtime, mutation.model || "default");
-        agent.runtime = mutation.runtime;
+        const stored = (0, user_runtime_js_1.fromUserRuntime)(mutation.runtime);
+        if (stored.piDistribution === "builtin") {
+            try {
+                (0, pi_provider_config_js_1.assertBuiltinPiAgentDirectory)((0, pi_provider_config_js_1.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 (mutation.runtime !== "pi")
+        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);
@@ -792,7 +820,7 @@ function assertConfigRoot(root) {
     if (typeof process.getuid === "function" && stat.uid !== process.getuid())
         throw new Error("config root owner is unsafe");
 }
-function withConfigLock(layout, action) {
+function acquireConfigLock(layout) {
     assertNoSymlinkAncestors(layout.root);
     fs.mkdirSync(layout.root, { recursive: true, mode: 0o700 });
     const rootStat = fs.lstatSync(layout.root);
@@ -831,20 +859,43 @@ function withConfigLock(layout, action) {
     }
     if (!acquired)
         throw new Error("配置正被其他进程修改，请稍后重试");
+    return {
+        release() {
+            const current = readLockRecord(lock);
+            if (current?.record?.nonce === owner.nonce && current.record.pid === owner.pid) {
+                try {
+                    fs.unlinkSync(lock);
+                    (0, secure_metadata_js_1.fsyncDirectoryOf)(lock);
+                }
+                catch { /* best effort */ }
+            }
+        },
+    };
+}
+function withConfigLock(layout, action) {
+    const held = acquireConfigLock(layout);
     try {
         recoverMigrationJournal(layout.root);
         recoverRollbackJournal(layout.root);
         return action();
     }
     finally {
-        const current = readLockRecord(lock);
-        if (current?.record?.nonce === owner.nonce && current.record.pid === owner.pid) {
-            try {
-                fs.unlinkSync(lock);
-                (0, secure_metadata_js_1.fsyncDirectoryOf)(lock);
-            }
-            catch { /* best effort */ }
-        }
+        held.release();
+    }
+}
+function withConfigMutationLock(env, action) {
+    return withConfigLock(root_layout_js_1.TargetRootLayout.fromConfigDir(resolveConfigDir(env)), action);
+}
+async function withConfigMutationLockAsync(env, action) {
+    const layout = root_layout_js_1.TargetRootLayout.fromConfigDir(resolveConfigDir(env));
+    const held = acquireConfigLock(layout);
+    try {
+        recoverMigrationJournal(layout.root);
+        recoverRollbackJournal(layout.root);
+        return await action();
+    }
+    finally {
+        held.release();
     }
 }
 const CONFIG_ROLLBACK_JOURNAL_FILE = ".config-rollback-journal.json";
@@ -1105,7 +1156,7 @@ function commitSetupConfig(env, expectedRevision, nextStored) {
 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, model: agent.model, piDistribution: agent.piDistribution ?? (agent.runtime === "pi" ? "external" : null), effort: agent.effort ?? null,
+        agentId, runtime: agent.runtime, runtimeOption: (0, user_runtime_js_1.toUserRuntime)(agent.runtime, agent.piDistribution), model: agent.model, piDistribution: agent.piDistribution ?? (agent.runtime === "pi" ? "external" : null), effort: agent.effort ?? null,
         mention: {
             override: agent.mentionPolicy ?? "inherit",
             effective: agent.mentionPolicy ?? config.mentionPolicy,

package/dist/platform/config.mjs

@@ -5,8 +5,11 @@ 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"]);
@@ -47,7 +50,8 @@ export function loadRuntimeModels() {
     return runtimeModels;
 }
 export function defaultModelFor(runtime) {
-    const models = loadRuntimeModels()[runtime];
+    const adapter = isUserRuntime(runtime) ? fromUserRuntime(runtime).runtime : runtime;
+    const models = loadRuntimeModels()[adapter];
     if (!models)
         throw new Error(`runtime 模型目录不存在 runtime: ${runtime}`);
     return models[0].id;
@@ -95,7 +99,7 @@ function validateStoredAgent(key, agent, version) {
     assertAllowedFields(agent, version === 3 ? AGENT_FIELDS_V3 : AGENT_FIELDS_V4, `Agent ${key}`);
     if (typeof agent.runtime !== "string" || !agent.runtime)
         throw new Error(`Agent ${key}.runtime 必须是非空字符串`);
-    if (!loadRuntimeModels()[agent.runtime])
+    if (!isAdapterRuntime(agent.runtime))
         throw new Error(`Agent ${key}.runtime 未知：${agent.runtime}`);
     if (typeof agent.model !== "string" || !agent.model)
         throw new Error(`Agent ${key}.model 必须是非空字符串`);
@@ -574,16 +578,30 @@ function applyMutation(config, mutation) {
         agent.piDistribution = mutation.distribution;
     }
     else if (mutation.kind === "set-agent-runtime") {
-        if (!loadRuntimeModels()[mutation.runtime])
+        if (!isUserRuntime(mutation.runtime))
             throw new Error(`未知 runtime：${mutation.runtime}`);
-        assertModel(mutation.runtime, mutation.model || "default");
-        agent.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 (mutation.runtime !== "pi")
+        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);
@@ -734,7 +752,7 @@ function assertConfigRoot(root) {
     if (typeof process.getuid === "function" && stat.uid !== process.getuid())
         throw new Error("config root owner is unsafe");
 }
-function withConfigLock(layout, action) {
+function acquireConfigLock(layout) {
     assertNoSymlinkAncestors(layout.root);
     fs.mkdirSync(layout.root, { recursive: true, mode: 0o700 });
     const rootStat = fs.lstatSync(layout.root);
@@ -773,20 +791,43 @@ function withConfigLock(layout, action) {
     }
     if (!acquired)
         throw new Error("配置正被其他进程修改，请稍后重试");
+    return {
+        release() {
+            const current = readLockRecord(lock);
+            if (current?.record?.nonce === owner.nonce && current.record.pid === owner.pid) {
+                try {
+                    fs.unlinkSync(lock);
+                    fsyncDirectoryOf(lock);
+                }
+                catch { /* best effort */ }
+            }
+        },
+    };
+}
+function withConfigLock(layout, action) {
+    const held = acquireConfigLock(layout);
     try {
         recoverMigrationJournal(layout.root);
         recoverRollbackJournal(layout.root);
         return action();
     }
     finally {
-        const current = readLockRecord(lock);
-        if (current?.record?.nonce === owner.nonce && current.record.pid === owner.pid) {
-            try {
-                fs.unlinkSync(lock);
-                fsyncDirectoryOf(lock);
-            }
-            catch { /* best effort */ }
-        }
+        held.release();
+    }
+}
+export function withConfigMutationLock(env, action) {
+    return withConfigLock(TargetRootLayout.fromConfigDir(resolveConfigDir(env)), action);
+}
+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();
+    }
+    finally {
+        held.release();
     }
 }
 const CONFIG_ROLLBACK_JOURNAL_FILE = ".config-rollback-journal.json";
@@ -1047,7 +1088,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, model: agent.model, piDistribution: agent.piDistribution ?? (agent.runtime === "pi" ? "external" : null), effort: agent.effort ?? null,
+        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,
         mention: {
             override: agent.mentionPolicy ?? "inherit",
             effective: agent.mentionPolicy ?? config.mentionPolicy,