larkin 0.4.28 → 0.4.29

package/dist/runtime/runtime-host.mjs

@@ -6,7 +6,8 @@ import { auditReminderDelivery } from "../agent/reminder-delivery-audit.mjs";
 import { isCanonicalInboxTarget, targetKeyOfInboxEnvelope } from "../agent/inbox-projection.mjs";
 import { SpanKind } from "@opentelemetry/api";
 import { buildStrictProviderErrorInput, classifyStrictProviderError } from "./provider-error-classifier.mjs";
-import { classifyRuntimePrerequisite, providerAuthenticationFailureReadiness, RuntimePrerequisiteError, } from "./runtime-readiness.mjs";
+import { authFailureAppliesTo, classifyPiMissingCredentialRejection, classifyRuntimePrerequisite, configuredProviderId, isBuiltinPiDistribution, missingProviderCredentialReadiness, parsePersistedAuthFailure, providerAuthenticationFailureReadiness, readinessForPersistedAuthFailure, safeProviderId, RuntimePrerequisiteError, } from "./runtime-readiness.mjs";
+import { officialPiHasStoredProvider } from "./pi-official-auth.mjs";
 import { resolveOfficialLarkCli } from "../app/official-lark-cli.mjs";
 import { assertAgentWorkspaceBound, managedLarkCliEnv } from "../app/agent-lark-cli-workspace.mjs";
 import { isPiNativeCompactionRequired, PiCompactionBreaker, PiCompactionRecoveryMachine, } from "./pi-compaction-recovery.mjs";
@@ -93,6 +94,121 @@ function persistPreviousSession(agent, previous) {
         // In-memory ref still holds for this process; restart will miss it only if this write failed.
     }
 }
+function isBuiltinPiAgent(agent) {
+    return agent.adapter.id === "pi"
+        && (isBuiltinPiDistribution(agent.config.piDistribution) || agent.config.runtime === "builtin-pi");
+}
+function authFailureScopeOf(agent) {
+    return {
+        runtime: agent.config.runtime,
+        model: agent.config.model,
+        piDistribution: agent.config.piDistribution,
+        adapterId: agent.adapter.id,
+    };
+}
+function currentAuthFailure(agent) {
+    if (!agent.authFailureActive)
+        return null;
+    const kind = agent.authFailureKind
+        ?? (agent.authFailureProvider ? "missing-provider" : "generic");
+    if (kind === "missing-provider") {
+        if (!agent.authFailureProvider)
+            return null;
+        return { kind: "missing-provider", runtime: "pi", piDistribution: "builtin", provider: agent.authFailureProvider };
+    }
+    const runtime = agent.adapter.id === "codex" || agent.adapter.id === "claude" || agent.adapter.id === "pi"
+        ? agent.adapter.id : null;
+    if (!runtime)
+        return null;
+    return {
+        kind: "generic",
+        runtime,
+        ...(runtime === "pi" && (agent.config.piDistribution === "builtin" || agent.config.piDistribution === "external")
+            ? { piDistribution: agent.config.piDistribution } : {}),
+        provider: agent.authFailureProvider,
+    };
+}
+function genericAuthProvider(agent, upstream) {
+    return safeProviderId(upstream?.provider) ?? configuredProviderId(agent.config.model);
+}
+function persistAuthFailure(agent) {
+    const store = agent.stateStore;
+    if (!store)
+        return;
+    try {
+        const write = () => {
+            const current = store.readJson("agentState", { sessions: {} });
+            if (Array.isArray(current.records) && !("sessions" in current))
+                return;
+            const { authFailureProvider: _legacy, authFailure: _scoped, ...rest } = current;
+            const failure = currentAuthFailure(agent);
+            if (!failure) {
+                if (!("authFailureProvider" in current) && !("authFailure" in current))
+                    return;
+                store.writeJson("agentState", rest);
+                return;
+            }
+            store.writeJson("agentState", {
+                ...rest,
+                authFailure: failure,
+                ...(failure.kind === "missing-provider" && failure.provider
+                    ? { authFailureProvider: failure.provider } : {}),
+            });
+        };
+        if (store.withInboxTransaction)
+            store.withInboxTransaction(write);
+        else
+            write();
+    }
+    catch {
+        // In-memory flags and the delivery ledger still hold for this process.
+    }
+}
+function loadPersistedAuthFailure(store) {
+    if (!store)
+        return null;
+    try {
+        return parsePersistedAuthFailure(store.readJson("agentState", {}));
+    }
+    catch {
+        return null;
+    }
+}
+function applyAuthFailure(agent, failure) {
+    agent.authFailureActive = true;
+    agent.authFailureKind = failure.kind;
+    agent.authFailureProvider = failure.provider ?? null;
+    agent.readiness = readinessForPersistedAuthFailure(failure);
+}
+function clearAuthFailure(agent, persist = true) {
+    agent.authFailureActive = false;
+    agent.authFailureKind = null;
+    agent.authFailureProvider = null;
+    if (persist)
+        persistAuthFailure(agent);
+}
+function restoreAuthFailure(agent) {
+    const persisted = loadPersistedAuthFailure(agent.stateStore);
+    if (!persisted)
+        return;
+    // 只恢复仍绑定当前 candidate 的当前作用域 auth；不从历史 delivery 回灌。
+    if (!authFailureAppliesTo(authFailureScopeOf(agent), persisted)) {
+        clearAuthFailure(agent);
+        return;
+    }
+    applyAuthFailure(agent, persisted);
+}
+function clearLedgerAuthProviders(agent) {
+    let changed = false;
+    for (const record of agent.records.values()) {
+        if (!record.authProvider)
+            continue;
+        delete record.authProvider;
+        changed = true;
+    }
+    if (changed)
+        persist(agent);
+}
 const REPLAY_FAILURE_CODES = new Set([
     "canonical_inbox_row_missing", "canonical_inbox_malformed", "duplicate_message_id",
     "inbox_state_conflict", "delivery_target_conflict", "structured_target_invalid",
@@ -481,6 +597,34 @@ export function createRuntimeHost(options) {
                 messageId: record.messageId, status: "consumed" });
         }
     };
+    const ownedConfigDir = () => {
+        const value = process.env.LARKIN_CONFIG_DIR?.trim();
+        return value || null;
+    };
+    const projectAuthFailure = (agent, readiness, failure) => {
+        agent.authFailureActive = true;
+        agent.authFailureKind = failure.kind;
+        agent.authFailureProvider = failure.provider;
+        agent.readiness = {
+            ...readiness,
+            ...(agent.readiness?.executable ? { executable: agent.readiness.executable } : {}),
+            ...(agent.readiness?.version ? { version: agent.readiness.version } : {}),
+        };
+        persistAuthFailure(agent);
+        emit({ type: "agent-status", agentId: agent.config.agentId, status: "error",
+            error: `${agent.readiness.reason} ${agent.readiness.nextAction}`, readiness: agent.readiness });
+    };
+    const namedAuthProviderPresent = (agent) => {
+        if (agent.authFailureKind !== "missing-provider" || !agent.authFailureProvider)
+            return true;
+        const failure = currentAuthFailure(agent);
+        if (!failure || !authFailureAppliesTo(authFailureScopeOf(agent), failure))
+            return false;
+        const configDir = ownedConfigDir();
+        if (!configDir)
+            return false;
+        return officialPiHasStoredProvider(configDir, agent.config.agentId, agent.authFailureProvider);
+    };
     const resultFor = (agent, record, result) => {
         if (result.status === "accepted") {
             if (record.errorCategory !== "context_window") {
@@ -494,6 +638,28 @@ export function createRuntimeHost(options) {
                     deliveryId: record.deliveryId, messageId: record.messageId, status: "accepted" });
             return { status: "accepted", deliveryId: record.deliveryId };
         }
+        const missing = result.status === "rejected" && isBuiltinPiAgent(agent)
+            ? classifyPiMissingCredentialRejection(result.reason)
+            : null;
+        if (missing) {
+            const readiness = missingProviderCredentialReadiness(agent.adapter.id, missing.provider);
+            const reason = readiness.reason ?? `Provider ${missing.provider} is missing from this Agent's official credential store.`;
+            if (record.status !== "error") {
+                record.reason = reason;
+                record.retryable = false;
+                record.errorCategory = "auth";
+                record.authProvider = missing.provider;
+                const finalRecord = setRecord(agent, record, "error");
+                if (finalRecord.status !== "consumed")
+                    emit({ type: "delivery", agentId: agent.config.agentId,
+                        deliveryId: record.deliveryId, messageId: record.messageId, status: "error", reason });
+                projectAuthFailure(agent, readiness, { kind: "missing-provider", provider: missing.provider });
+            }
+            return { status: "error", deliveryId: record.deliveryId, reason: record.reason ?? reason, retryable: false };
+        }
+        if (record.status === "error") {
+            return { status: "error", deliveryId: record.deliveryId, reason: record.reason ?? result.reason, retryable: false };
+        }
         if (record.errorCategory !== "context_window")
             delete record.errorCategory;
         const retryable = result.status === "deferred" || result.retryable;
@@ -1338,7 +1504,7 @@ export function createRuntimeHost(options) {
                     agent.compactionMachines.delete(inputId);
             }
             const recoveredAuthentication = agent.authFailureActive && agent.turnInProgress
-                && agent.turnHadAuthenticatedOutput && !agent.turnHadFailure;
+                && agent.turnHadAuthenticatedOutput && !agent.turnHadFailure && namedAuthProviderPresent(agent);
             agent.turnInProgress = false;
             agent.busy = false;
             emit({ type: "activity", agentId: agent.config.agentId, activity: "idle", activityKind: "idle", detailKind: "turn_ended" });
@@ -1360,7 +1526,8 @@ export function createRuntimeHost(options) {
             reconcileSubagentLedger(agent);
             telemetry?.runtimeEvent(agent.config.agentId, event);
             if (recoveredAuthentication) {
-                agent.authFailureActive = false;
+                clearAuthFailure(agent);
+                clearLedgerAuthProviders(agent);
                 const prior = agent.readiness;
                 agent.readiness = {
                     runtime: agent.adapter.id,
@@ -1453,21 +1620,24 @@ export function createRuntimeHost(options) {
                 record.errorCategory = classifiedCategory;
             else
                 delete record.errorCategory;
+            const missing = event.errorCategory === "auth" && !event.retryable && isBuiltinPiAgent(agent)
+                ? classifyPiMissingCredentialRejection(event.upstream?.message)
+                    ?? classifyPiMissingCredentialRejection(event.message)
+                : null;
+            if (missing)
+                record.authProvider = missing.provider;
             const finalRecord = setRecord(agent, record, event.retryable ? "pending" : "error");
             if (finalRecord.status !== "consumed")
                 emit({ type: "delivery", agentId: agent.config.agentId,
                     deliveryId: record.deliveryId, messageId: record.messageId,
                     status: event.retryable ? "deferred" : "error", reason: event.message });
             if (event.errorCategory === "auth" && !event.retryable) {
-                const readiness = providerAuthenticationFailureReadiness(agent.adapter.id, event.upstream?.provider);
-                agent.authFailureActive = true;
-                agent.readiness = {
-                    ...readiness,
-                    ...(agent.readiness?.executable ? { executable: agent.readiness.executable } : {}),
-                    ...(agent.readiness?.version ? { version: agent.readiness.version } : {}),
-                };
-                emit({ type: "agent-status", agentId: agent.config.agentId, status: "error",
-                    error: `${agent.readiness.reason} ${agent.readiness.nextAction}`, readiness: agent.readiness });
+                const readiness = missing
+                    ? missingProviderCredentialReadiness(agent.adapter.id, missing.provider)
+                    : providerAuthenticationFailureReadiness(agent.adapter.id, event.upstream?.provider);
+                projectAuthFailure(agent, readiness, missing
+                    ? { kind: "missing-provider", provider: missing.provider }
+                    : { kind: "generic", provider: genericAuthProvider(agent, event.upstream) });
             }
             if (event.retryable && !agent.busy && !agent.turnInProgress)
                 void retryPending(agent);
@@ -1739,14 +1909,27 @@ export function createRuntimeHost(options) {
                         clearTimeout(previous.backgroundCompletionRetryTimer);
                     if (previous.subagentReconcileTimer)
                         clearInterval(previous.subagentReconcileTimer);
+                    const previousFailure = currentAuthFailure(previous);
+                    const scoped = Boolean(previousFailure
+                        && authFailureAppliesTo({
+                            runtime: config.runtime,
+                            model: config.model,
+                            piDistribution: config.piDistribution,
+                            adapterId: adapter.id,
+                        }, previousFailure));
                     const candidate = {
                         ...previous, config, adapter, session, launchId: crypto.randomUUID(), busy: false, submitting: false,
                         starting: null, retryAfterSubmit: false, generation: 0, poller: null, retryTimer: null,
                         recreateAttempts: 0, stabilityTimer: null, recreateReason: null, stopped: false,
                         backgroundCompletionRetryTimer: null, subagentReconcileTimer: null,
                         disabledReason: null, configurationRecovery: null,
-                        readiness: previous.authFailureActive ? previous.readiness : readiness,
+                        authFailureActive: scoped && previous.authFailureActive,
+                        authFailureKind: scoped ? previous.authFailureKind : null,
+                        authFailureProvider: scoped ? previous.authFailureProvider : null,
+                        readiness: scoped && previous.authFailureActive ? previous.readiness : readiness,
                     };
+                    if (previous.authFailureActive && !candidate.authFailureActive)
+                        clearAuthFailure(candidate);
                     managed.set(config.agentId, candidate);
                     session.subscribe((event) => observe(candidate, session, event));
                     if (session.sessionId) {
@@ -1841,7 +2024,8 @@ export function createRuntimeHost(options) {
                 agent.config.sessionId = null;
                 agent.session = fresh;
                 persistPreviousSession(agent, previousRef);
-                agent.readiness = readiness;
+                if (!agent.authFailureActive)
+                    agent.readiness = readiness;
                 agent.disabledReason = null;
             };
             try {
@@ -1862,7 +2046,13 @@ export function createRuntimeHost(options) {
                     ...(fresh.effectiveReasoningEffort ? { reasoningEffort: fresh.effectiveReasoningEffort } : {}),
                     ...(agent.previousSession ? { previousSession: agent.previousSession } : {}) });
             }
-            emit({ type: "agent-status", agentId, status: "active", readiness });
+            emit({
+                type: "agent-status",
+                agentId,
+                status: agent.authFailureActive ? "error" : "active",
+                ...(agent.authFailureActive ? { error: `${agent.readiness?.reason} ${agent.readiness?.nextAction}` } : {}),
+                readiness: agent.authFailureActive ? agent.readiness ?? readiness : readiness,
+            });
             agent.piSessionOwner = probeEnv[PI_SUBAGENT_SESSION_OWNER_ENV];
             await oldSession.close("fresh session reset committed")
                 .catch((error) => log("previous runtime close after fresh reset failed", String(error)));
@@ -2000,7 +2190,8 @@ export function createRuntimeHost(options) {
                     agent.config.sessionId = null;
                     agent.session = fresh;
                     persistPreviousSession(agent, previousRef);
-                    agent.readiness = readiness;
+                    if (!agent.authFailureActive)
+                        agent.readiness = readiness;
                     agent.disabledReason = null;
                     for (const record of agent.records.values()) {
                         if (!messageIds.includes(record.messageId))
@@ -2018,7 +2209,13 @@ export function createRuntimeHost(options) {
                         ...(fresh.effectiveReasoningEffort ? { reasoningEffort: fresh.effectiveReasoningEffort } : {}),
                         ...(agent.previousSession ? { previousSession: agent.previousSession } : {}) });
                 }
-                emit({ type: "agent-status", agentId, status: "active", readiness });
+                emit({
+                    type: "agent-status",
+                    agentId,
+                    status: agent.authFailureActive ? "error" : "active",
+                    ...(agent.authFailureActive ? { error: `${agent.readiness?.reason} ${agent.readiness?.nextAction}` } : {}),
+                    readiness: agent.authFailureActive ? agent.readiness ?? readiness : readiness,
+                });
                 durableRollback = null;
                 agent.piSessionOwner = probeEnv[PI_SUBAGENT_SESSION_OWNER_ENV];
                 await oldSession.close("context-window recovery committed")
@@ -2108,11 +2305,13 @@ export function createRuntimeHost(options) {
                     piProactiveCompactionFailedGeneration: null,
                     previousSession: loadPersistedPreviousSession(config, stateStore), readiness: null,
                     turnInProgress: false, turnHadFailure: false, turnHadAuthenticatedOutput: false, authFailureActive: false,
+                    authFailureKind: null, authFailureProvider: null,
                     promotedInboxUpdateIds: new Set(),
                     backgroundCompletionQueue: [], backgroundCompletionKeys: new Set(),
                     backgroundCompletionInFlight: null, backgroundCompletionWakeInputId: null,
                     backgroundCompletionRejectStreak: 0, backgroundCompletionRetryTimer: null,
                     subagentLedger: loadSubagentLedger(config), subagentReconcileTimer: null };
+                restoreAuthFailure(agent);
                 const startupConsumed = [];
                 const startupQuarantined = [];
                 for (const record of agent.records.values()) {

package/dist/runtime/runtime-readiness.cjs

@@ -37,7 +37,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RuntimePrerequisiteError = void 0;
+exports.safeProviderId = safeProviderId;
+exports.isBuiltinPiDistribution = isBuiltinPiDistribution;
+exports.configuredProviderId = configuredProviderId;
+exports.parsePersistedAuthFailure = parsePersistedAuthFailure;
+exports.authFailureAppliesTo = authFailureAppliesTo;
+exports.readinessForPersistedAuthFailure = readinessForPersistedAuthFailure;
+exports.classifyPiMissingCredentialRejection = classifyPiMissingCredentialRejection;
 exports.providerAuthenticationFailureReadiness = providerAuthenticationFailureReadiness;
+exports.missingProviderCredentialReadiness = missingProviderCredentialReadiness;
 exports.resolveRuntimeExecutable = resolveRuntimeExecutable;
 exports.classifyRuntimePrerequisite = classifyRuntimePrerequisite;
 exports.probeNativeRuntimeReadiness = probeNativeRuntimeReadiness;
@@ -49,10 +57,103 @@ const root_layout_js_1 = require("../platform/root-layout.cjs");
 const builtin_pi_assets_js_1 = require("./builtin-pi-assets.cjs");
 const pi_provider_config_js_1 = require("./pi-provider-config.cjs");
 const process_boundary_trace_js_1 = require("../platform/process-boundary-trace.cjs");
-function safeProviderLabel(value) {
+function safeProviderId(value) {
     const provider = typeof value === "string" ? value.trim() : "";
     return /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(provider) ? provider : null;
 }
+function safeProviderLabel(value) {
+    return safeProviderId(value);
+}
+function isBuiltinPiDistribution(value) {
+    return value === "builtin";
+}
+/** Model ids are `provider/model`; only the provider prefix is used for scope. */
+function configuredProviderId(model) {
+    const value = typeof model === "string" ? model.trim() : "";
+    const slash = value.indexOf("/");
+    return slash > 0 ? safeProviderId(value.slice(0, slash)) : null;
+}
+function persistedRuntime(value) {
+    return value === "pi" || value === "codex" || value === "claude" ? value : null;
+}
+function parsePersistedAuthFailure(state) {
+    if (!state || typeof state !== "object" || Array.isArray(state))
+        return null;
+    const record = state;
+    if (record.authFailure && typeof record.authFailure === "object" && !Array.isArray(record.authFailure)) {
+        const failure = record.authFailure;
+        const kind = failure.kind === "missing-provider" || failure.kind === "generic" ? failure.kind : null;
+        const runtime = persistedRuntime(failure.runtime);
+        if (!kind || !runtime)
+            return null;
+        const provider = safeProviderId(failure.provider);
+        if (kind === "missing-provider" && !provider)
+            return null;
+        const piDistribution = failure.piDistribution === "builtin" || failure.piDistribution === "external"
+            ? failure.piDistribution : undefined;
+        return {
+            kind,
+            runtime,
+            ...(piDistribution ? { piDistribution } : {}),
+            provider,
+        };
+    }
+    const legacy = safeProviderId(record.authFailureProvider);
+    return legacy
+        ? { kind: "missing-provider", runtime: "pi", piDistribution: "builtin", provider: legacy }
+        : null;
+}
+function currentAdapterId(current) {
+    return current.adapterId ?? (current.runtime === "builtin-pi" ? "pi" : current.runtime);
+}
+function currentIsBuiltinPi(current) {
+    return currentAdapterId(current) === "pi"
+        && (isBuiltinPiDistribution(current.piDistribution) || current.runtime === "builtin-pi");
+}
+/**
+ * Missing-provider and known-provider generic markers apply only to that provider.
+ * Generic without a provider is conservative fallback: it still binds runtime /
+ * builtin distribution, but cannot reject an A→B model switch because the
+ * upstream provider was genuinely unavailable.
+ */
+function authFailureAppliesTo(current, failure) {
+    if (failure.kind === "missing-provider") {
+        return currentIsBuiltinPi(current)
+            && failure.runtime === "pi"
+            && failure.piDistribution === "builtin"
+            && Boolean(failure.provider)
+            && configuredProviderId(current.model) === failure.provider;
+    }
+    if (failure.runtime !== currentAdapterId(current))
+        return false;
+    if (failure.runtime === "pi") {
+        const persistedBuiltin = failure.piDistribution === "builtin";
+        if (currentIsBuiltinPi(current) !== persistedBuiltin)
+            return false;
+    }
+    if (!failure.provider)
+        return true;
+    const currentProvider = configuredProviderId(current.model);
+    if (currentIsBuiltinPi(current))
+        return currentProvider === failure.provider;
+    return currentProvider ? currentProvider === failure.provider : true;
+}
+function readinessForPersistedAuthFailure(failure) {
+    if (failure.kind === "missing-provider") {
+        return missingProviderCredentialReadiness(failure.runtime, failure.provider);
+    }
+    return providerAuthenticationFailureReadiness(failure.runtime, failure.provider);
+}
+const MISSING_CREDENTIAL_REJECTION = /^(?:Pi RPC (?:prompt|steer) failed: )?(No API key found for|No login found for) ([A-Za-z0-9][A-Za-z0-9._-]{0,79})$/;
+/** Narrow match for an explicit Pi absent-key / absent-login diagnostic. */
+function classifyPiMissingCredentialRejection(message) {
+    const text = typeof message === "string"
+        ? message.replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim()
+        : "";
+    const match = MISSING_CREDENTIAL_REJECTION.exec(text);
+    const provider = match ? safeProviderLabel(match[2]) : null;
+    return provider && match ? { provider, diagnostic: `${match[1]} ${provider}` } : null;
+}
 function providerAuthenticationFailureReadiness(runtime, provider) {
     const label = safeProviderLabel(provider);
     return {
@@ -64,6 +165,22 @@ function providerAuthenticationFailureReadiness(runtime, provider) {
         nextAction: "Check the provider login or API-key resolver command, then retry the Agent turn.",
     };
 }
+/** P0 分类；Pi nextAction 共用 UX preset 恢复文案，不写官方 provider ID。 */
+function missingProviderCredentialReadiness(runtime, provider) {
+    const label = safeProviderLabel(provider);
+    return {
+        runtime,
+        state: "unauthenticated",
+        reason: label
+            ? `Provider ${label} is missing from this Agent's official credential store.`
+            : "The configured provider is missing from this Agent's official credential store.",
+        nextAction: runtime === "pi"
+            ? (0, pi_provider_config_js_1.builtinPiProviderRecoveryNextAction)({ providerId: label ?? undefined })
+            : label
+                ? `Add the missing ${label} credential to this Agent's official store, then retry the Agent turn.`
+                : "Add the missing provider credential to this Agent's official store, then retry the Agent turn.",
+    };
+}
 class RuntimePrerequisiteError extends Error {
     readiness;
     constructor(readiness) {
@@ -100,7 +217,10 @@ function classifyRuntimePrerequisite(runtime, error, executable) {
     if (/no authenticated available models|login|credential|unauthenticated|unauthorized|oauth/i.test(reason))
         return {
             runtime, state: "unauthenticated", ...(executable ? { executable } : {}), reason,
-            nextAction: runtime === "pi" ? "Run the official `pi` login flow, then retry." : `Authenticate ${runtime}, then retry.`,
+            // 此分类没有 distribution：外部 Pi 不能指向 Dashboard / pi-auth login。
+            nextAction: runtime === "pi"
+                ? "Run the official `pi` login flow, then retry."
+                : `Authenticate ${runtime}, then retry.`,
         };
     if (/protocol (?:version )?(?:mismatch|unsupported|incompatible)|unsupported (?:rpc|protocol|schema)|schema (?:mismatch|incompatible)|requires (?:a )?newer version/i.test(reason))
         return {
@@ -151,7 +271,7 @@ async function probeNativeRuntimeReadiness(options) {
         catch (error) {
             (0, process_boundary_trace_js_1.traceProcessBoundary)(env, "readiness:builtin-pi-failure", { configDir: env.LARKIN_CONFIG_DIR, agentId: options.agentId, targetDir: options.agentId && env.LARKIN_CONFIG_DIR ? (0, pi_provider_config_js_1.piAgentDirectory)(env.LARKIN_CONFIG_DIR, options.agentId) : undefined, error });
             return { runtime: "pi", state: "unauthenticated", reason: error instanceof Error ? error.message : String(error),
-                nextAction: "重新运行 larkin setup，选择内置 Pi 并配置有效 API Key。" };
+                nextAction: (0, pi_provider_config_js_1.builtinPiProviderRecoveryNextAction)({ agentId: options.agentId }) };
         }
     }
     const command = selectedCommand(options);

package/dist/runtime/runtime-readiness.mjs

@@ -4,12 +4,105 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { resolveConfigDir as resolveRootConfigDir } from "../platform/root-layout.mjs";
 import { applyPiPackageDirForChild, piChildDistributionFromOverrides } from "./builtin-pi-assets.mjs";
-import { assertBuiltinPiAgentDirectory, BUNDLED_PI_VERSION, ownedPiCatalogAgentDir, piAgentDirectory } from "./pi-provider-config.mjs";
+import { assertBuiltinPiAgentDirectory, BUNDLED_PI_VERSION, builtinPiProviderRecoveryNextAction, ownedPiCatalogAgentDir, piAgentDirectory } from "./pi-provider-config.mjs";
 import { traceProcessBoundary } from "../platform/process-boundary-trace.mjs";
-function safeProviderLabel(value) {
+export function safeProviderId(value) {
     const provider = typeof value === "string" ? value.trim() : "";
     return /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(provider) ? provider : null;
 }
+function safeProviderLabel(value) {
+    return safeProviderId(value);
+}
+export function isBuiltinPiDistribution(value) {
+    return value === "builtin";
+}
+/** Model ids are `provider/model`; only the provider prefix is used for scope. */
+export function configuredProviderId(model) {
+    const value = typeof model === "string" ? model.trim() : "";
+    const slash = value.indexOf("/");
+    return slash > 0 ? safeProviderId(value.slice(0, slash)) : null;
+}
+function persistedRuntime(value) {
+    return value === "pi" || value === "codex" || value === "claude" ? value : null;
+}
+export function parsePersistedAuthFailure(state) {
+    if (!state || typeof state !== "object" || Array.isArray(state))
+        return null;
+    const record = state;
+    if (record.authFailure && typeof record.authFailure === "object" && !Array.isArray(record.authFailure)) {
+        const failure = record.authFailure;
+        const kind = failure.kind === "missing-provider" || failure.kind === "generic" ? failure.kind : null;
+        const runtime = persistedRuntime(failure.runtime);
+        if (!kind || !runtime)
+            return null;
+        const provider = safeProviderId(failure.provider);
+        if (kind === "missing-provider" && !provider)
+            return null;
+        const piDistribution = failure.piDistribution === "builtin" || failure.piDistribution === "external"
+            ? failure.piDistribution : undefined;
+        return {
+            kind,
+            runtime,
+            ...(piDistribution ? { piDistribution } : {}),
+            provider,
+        };
+    }
+    const legacy = safeProviderId(record.authFailureProvider);
+    return legacy
+        ? { kind: "missing-provider", runtime: "pi", piDistribution: "builtin", provider: legacy }
+        : null;
+}
+function currentAdapterId(current) {
+    return current.adapterId ?? (current.runtime === "builtin-pi" ? "pi" : current.runtime);
+}
+function currentIsBuiltinPi(current) {
+    return currentAdapterId(current) === "pi"
+        && (isBuiltinPiDistribution(current.piDistribution) || current.runtime === "builtin-pi");
+}
+/**
+ * Missing-provider and known-provider generic markers apply only to that provider.
+ * Generic without a provider is conservative fallback: it still binds runtime /
+ * builtin distribution, but cannot reject an A→B model switch because the
+ * upstream provider was genuinely unavailable.
+ */
+export function authFailureAppliesTo(current, failure) {
+    if (failure.kind === "missing-provider") {
+        return currentIsBuiltinPi(current)
+            && failure.runtime === "pi"
+            && failure.piDistribution === "builtin"
+            && Boolean(failure.provider)
+            && configuredProviderId(current.model) === failure.provider;
+    }
+    if (failure.runtime !== currentAdapterId(current))
+        return false;
+    if (failure.runtime === "pi") {
+        const persistedBuiltin = failure.piDistribution === "builtin";
+        if (currentIsBuiltinPi(current) !== persistedBuiltin)
+            return false;
+    }
+    if (!failure.provider)
+        return true;
+    const currentProvider = configuredProviderId(current.model);
+    if (currentIsBuiltinPi(current))
+        return currentProvider === failure.provider;
+    return currentProvider ? currentProvider === failure.provider : true;
+}
+export function readinessForPersistedAuthFailure(failure) {
+    if (failure.kind === "missing-provider") {
+        return missingProviderCredentialReadiness(failure.runtime, failure.provider);
+    }
+    return providerAuthenticationFailureReadiness(failure.runtime, failure.provider);
+}
+const MISSING_CREDENTIAL_REJECTION = /^(?:Pi RPC (?:prompt|steer) failed: )?(No API key found for|No login found for) ([A-Za-z0-9][A-Za-z0-9._-]{0,79})$/;
+/** Narrow match for an explicit Pi absent-key / absent-login diagnostic. */
+export function classifyPiMissingCredentialRejection(message) {
+    const text = typeof message === "string"
+        ? message.replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim()
+        : "";
+    const match = MISSING_CREDENTIAL_REJECTION.exec(text);
+    const provider = match ? safeProviderLabel(match[2]) : null;
+    return provider && match ? { provider, diagnostic: `${match[1]} ${provider}` } : null;
+}
 export function providerAuthenticationFailureReadiness(runtime, provider) {
     const label = safeProviderLabel(provider);
     return {
@@ -21,6 +114,22 @@ export function providerAuthenticationFailureReadiness(runtime, provider) {
         nextAction: "Check the provider login or API-key resolver command, then retry the Agent turn.",
     };
 }
+/** P0 分类；Pi nextAction 共用 UX preset 恢复文案，不写官方 provider ID。 */
+export function missingProviderCredentialReadiness(runtime, provider) {
+    const label = safeProviderLabel(provider);
+    return {
+        runtime,
+        state: "unauthenticated",
+        reason: label
+            ? `Provider ${label} is missing from this Agent's official credential store.`
+            : "The configured provider is missing from this Agent's official credential store.",
+        nextAction: runtime === "pi"
+            ? builtinPiProviderRecoveryNextAction({ providerId: label ?? undefined })
+            : label
+                ? `Add the missing ${label} credential to this Agent's official store, then retry the Agent turn.`
+                : "Add the missing provider credential to this Agent's official store, then retry the Agent turn.",
+    };
+}
 export class RuntimePrerequisiteError extends Error {
     readiness;
     constructor(readiness) {
@@ -56,7 +165,10 @@ export function classifyRuntimePrerequisite(runtime, error, executable) {
     if (/no authenticated available models|login|credential|unauthenticated|unauthorized|oauth/i.test(reason))
         return {
             runtime, state: "unauthenticated", ...(executable ? { executable } : {}), reason,
-            nextAction: runtime === "pi" ? "Run the official `pi` login flow, then retry." : `Authenticate ${runtime}, then retry.`,
+            // 此分类没有 distribution：外部 Pi 不能指向 Dashboard / pi-auth login。
+            nextAction: runtime === "pi"
+                ? "Run the official `pi` login flow, then retry."
+                : `Authenticate ${runtime}, then retry.`,
         };
     if (/protocol (?:version )?(?:mismatch|unsupported|incompatible)|unsupported (?:rpc|protocol|schema)|schema (?:mismatch|incompatible)|requires (?:a )?newer version/i.test(reason))
         return {
@@ -107,7 +219,7 @@ export async function probeNativeRuntimeReadiness(options) {
         catch (error) {
             traceProcessBoundary(env, "readiness:builtin-pi-failure", { configDir: env.LARKIN_CONFIG_DIR, agentId: options.agentId, targetDir: options.agentId && env.LARKIN_CONFIG_DIR ? piAgentDirectory(env.LARKIN_CONFIG_DIR, options.agentId) : undefined, error });
             return { runtime: "pi", state: "unauthenticated", reason: error instanceof Error ? error.message : String(error),
-                nextAction: "重新运行 larkin setup，选择内置 Pi 并配置有效 API Key。" };
+                nextAction: builtinPiProviderRecoveryNextAction({ agentId: options.agentId }) };
         }
     }
     const command = selectedCommand(options);

package/package.json

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