larkin 0.4.27 → 0.4.29

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/dist/runtime/user-runtime.cjs

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADAPTER_RUNTIMES = exports.USER_RUNTIMES = exports.RUNTIME_OPTIONS = void 0;
+exports.isUserRuntime = isUserRuntime;
+exports.isAdapterRuntime = isAdapterRuntime;
+exports.runtimeOptionOf = runtimeOptionOf;
+exports.toUserRuntime = toUserRuntime;
+exports.runtimeOptionTarget = runtimeOptionTarget;
+exports.fromUserRuntime = fromUserRuntime;
+exports.piCatalogDistributionForUserRuntime = piCatalogDistributionForUserRuntime;
+exports.RUNTIME_OPTIONS = ["codex", "claude", "pi", "builtin-pi"];
+exports.USER_RUNTIMES = exports.RUNTIME_OPTIONS;
+exports.ADAPTER_RUNTIMES = ["pi", "codex", "claude"];
+function isUserRuntime(value) {
+    return value === "pi" || value === "builtin-pi" || value === "codex" || value === "claude";
+}
+function isAdapterRuntime(value) {
+    return value === "pi" || value === "codex" || value === "claude";
+}
+/** Project stored adapter + distribution to the user-facing sibling id. Legacy `runtime=pi` without distribution is `pi`, never builtin. */
+function runtimeOptionOf(input) {
+    const { runtime, piDistribution } = input;
+    if (runtime === "codex" || runtime === "claude" || runtime === "builtin-pi")
+        return runtime;
+    if (runtime === "pi")
+        return piDistribution === "builtin" ? "builtin-pi" : "pi";
+    return runtime;
+}
+function toUserRuntime(runtime, piDistribution) {
+    return runtimeOptionOf({ runtime, piDistribution });
+}
+/** Persist a user-facing sibling as adapter id + distribution. Adapter id stays `pi` for both Pi siblings. */
+function runtimeOptionTarget(option) {
+    if (!isUserRuntime(option))
+        throw new Error(`未知 runtime：${option}`);
+    if (option === "builtin-pi")
+        return { runtime: "pi", piDistribution: "builtin" };
+    if (option === "pi")
+        return { runtime: "pi", piDistribution: "external" };
+    return { runtime: option };
+}
+function fromUserRuntime(userRuntime) {
+    return runtimeOptionTarget(userRuntime);
+}
+function piCatalogDistributionForUserRuntime(userRuntime) {
+    if (userRuntime === "builtin-pi")
+        return "builtin";
+    if (userRuntime === "pi")
+        return "external";
+    throw new Error(`非 Pi sibling runtime：${userRuntime}`);
+}

package/dist/runtime/user-runtime.mjs

@@ -0,0 +1,41 @@
+export const RUNTIME_OPTIONS = ["codex", "claude", "pi", "builtin-pi"];
+export const USER_RUNTIMES = RUNTIME_OPTIONS;
+export const ADAPTER_RUNTIMES = ["pi", "codex", "claude"];
+export function isUserRuntime(value) {
+    return value === "pi" || value === "builtin-pi" || value === "codex" || value === "claude";
+}
+export function isAdapterRuntime(value) {
+    return value === "pi" || value === "codex" || value === "claude";
+}
+/** Project stored adapter + distribution to the user-facing sibling id. Legacy `runtime=pi` without distribution is `pi`, never builtin. */
+export function runtimeOptionOf(input) {
+    const { runtime, piDistribution } = input;
+    if (runtime === "codex" || runtime === "claude" || runtime === "builtin-pi")
+        return runtime;
+    if (runtime === "pi")
+        return piDistribution === "builtin" ? "builtin-pi" : "pi";
+    return runtime;
+}
+export function toUserRuntime(runtime, piDistribution) {
+    return runtimeOptionOf({ runtime, piDistribution });
+}
+/** Persist a user-facing sibling as adapter id + distribution. Adapter id stays `pi` for both Pi siblings. */
+export function runtimeOptionTarget(option) {
+    if (!isUserRuntime(option))
+        throw new Error(`未知 runtime：${option}`);
+    if (option === "builtin-pi")
+        return { runtime: "pi", piDistribution: "builtin" };
+    if (option === "pi")
+        return { runtime: "pi", piDistribution: "external" };
+    return { runtime: option };
+}
+export function fromUserRuntime(userRuntime) {
+    return runtimeOptionTarget(userRuntime);
+}
+export function piCatalogDistributionForUserRuntime(userRuntime) {
+    if (userRuntime === "builtin-pi")
+        return "builtin";
+    if (userRuntime === "pi")
+        return "external";
+    throw new Error(`非 Pi sibling runtime：${userRuntime}`);
+}

package/dist/setup/bot-register.mjs

@@ -719,10 +719,10 @@ Lark 必须用 --tenant lark：授权二维码是官方 /page/cli（begin 仍走
     const setupModel = flag("--model");
     if (piDistributionFlag === "builtin") {
         if (!setupProvider && !setupBaseUrl) {
-            throw new Error(`builtin-pi 需要 --provider <id>（${PI_PROVIDER_PRESETS.map((p) => p.id).join("|")}|custom）或 --base-url；或改用 --runtime external-pi 使用已有 pi 环境`);
+            throw new Error(`builtin-pi 需要 --provider <id>（${PI_PROVIDER_PRESETS.map((p) => p.id).join("|")}|custom）或 --base-url；或改用 --runtime pi 使用已有 pi 环境`);
         }
         if (!setupApiKey)
-            throw new Error("builtin-pi 需要 --api-key；或改用 --runtime external-pi 使用已有 pi 登录");
+            throw new Error("builtin-pi 需要 --api-key；或改用 --runtime pi 使用已有 pi 登录");
         // 自定义网关（--base-url）走 custom 预设：pi 会把 baseUrl 作为 provider 端点写入配置，
         // 而不是用预设厂商目录（否则会打到预设默认地址，如 api.openai.com）。
         const presetId = setupBaseUrl ? "custom" : (setupProvider ?? "custom");
@@ -763,7 +763,7 @@ Lark 必须用 --tenant lark：授权二维码是官方 /page/cli（begin 仍走
         say(`[setup 2/5] ✓ 内置 Pi provider 已配置（${presetId}${setupBaseUrl ? " / custom" : ""}）`);
     }
     else if (piDistributionFlag === "external" && (setupProvider || setupApiKey || setupBaseUrl)) {
-        throw new Error("external-pi 使用已有 pi 环境与登录，不接受 --provider/--api-key/--base-url");
+        throw new Error("pi 使用已有 pi 环境与登录，不接受 --provider/--api-key/--base-url");
     }
     const stagedBotFile = path.join(botsDir, `.${id}.${process.pid}.tmp`);
     try {

package/dist/setup/setup-agent-choice.mjs

@@ -1,5 +1,6 @@
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
+import { toUserRuntime } from "../runtime/user-runtime.mjs";
 import { PI_PROVIDER_PRESETS, resolveBuiltinPiProviderSetupSelection, } from "../runtime/pi-provider-config.mjs";
 function number(value, fallback, max) {
     const parsed = value.trim() ? Number(value.trim()) : fallback;
@@ -54,20 +55,20 @@ export async function collectBuiltinPiChoice(questioner, services) {
 }
 export async function collectSetupAgentChoice(questioner, prior, services) {
     if (prior) {
-        const keep = (await questioner.ask(`已有 Agent：${prior.runtime}/${prior.model}。直接回车保留；输入 c 才修改：`)).trim().toLowerCase();
+        const keep = (await questioner.ask(`已有 Agent：${toUserRuntime(prior.runtime, prior.piDistribution)}/${prior.model}。直接回车保留；输入 c 才修改：`)).trim().toLowerCase();
         if (!keep)
             return null;
         if (keep !== "c")
             throw new Error("请输入 c 修改，或直接回车保留现有配置");
     }
-    const runtimeChoice = number(await questioner.ask("选择 Agent：\n  1. Pi（推荐）\n  2. Codex\n  3. Claude Code\n> "), 1, 3);
-    if (runtimeChoice === 2)
-        return { runtime: "codex" };
+    const runtimeChoice = number(await questioner.ask("选择 Agent：\n  1. builtin-pi（Larkin 捆绑，推荐）\n  2. pi（本机官方 pi CLI）\n  3. Codex\n  4. Claude Code\n> "), 1, 4);
     if (runtimeChoice === 3)
+        return { runtime: "codex" };
+    if (runtimeChoice === 4)
         return { runtime: "claude" };
-    const sourceChoice = number(await questioner.ask("选择 Pi：\n  1. 外置 Pi（使用本机官方 pi）\n  2. 内置 Pi（无需安装 Agent CLI，推荐）\n> "), 2, 2);
-    const distribution = sourceChoice === 1 ? "external" : "builtin";
-    return distribution === "external" ? { runtime: "pi", distribution } : collectBuiltinPiChoice(questioner, services);
+    if (runtimeChoice === 2)
+        return { runtime: "pi", distribution: "external" };
+    return collectBuiltinPiChoice(questioner, services);
 }
 export async function recoverUnavailableExternalPi(initial, questioner, probe, report = () => { }, services) {
     let choice = initial;
@@ -77,8 +78,8 @@ export async function recoverUnavailableExternalPi(initial, questioner, probe, r
         const readiness = await probe();
         if (readiness.state === "ready")
             return choice;
-        report(`外置 Pi ${readiness.state}：${readiness.reason || "prerequisite unavailable"}；${readiness.nextAction || "可切换到内置 Pi"}`);
-        const action = number(await questioner.ask("外置 Pi 当前不可用：\n  1. 切换到内置 Pi（推荐）\n  2. 重新选择 Agent\n  3. 取消 setup（保留原配置）\n> "), 1, 3);
+        report(`外置 Pi ${readiness.state}：${readiness.reason || "prerequisite unavailable"}；${readiness.nextAction || "可切换到 builtin-pi"}`);
+        const action = number(await questioner.ask("外置 Pi 当前不可用：\n  1. 切换到 builtin-pi（推荐）\n  2. 重新选择 Agent\n  3. 取消 setup（保留原配置）\n> "), 1, 3);
         if (action === 1)
             return collectBuiltinPiChoice(questioner, services);
         if (action === 3)

package/dist/setup/setup-bind.mjs

@@ -209,11 +209,11 @@ function formatExternalPiSetupFailure(error, options) {
     const alternatives = catalogModelsFromError(error);
     const parts = [];
     if (/external Pi (?:auth\.json|models\.json|settings\.json) is required|external Pi profile|external Pi auth\.json has an unsafe mode|external Pi models\.json has an unsafe mode|external Pi settings\.json has an unsafe mode/.test(original)) {
-        parts.push("external-pi requires the official file-backed Pi profile containing auth.json (0600), models.json, and settings.json, normally after `pi` login and default-model selection. Environment-variable-only credentials are unsupported.");
+        parts.push("pi requires the official file-backed Pi profile containing auth.json (0600), models.json, and settings.json, normally after `pi` login and default-model selection. Environment-variable-only credentials are unsupported.");
     }
     if (original)
         parts.push(original);
-    parts.push("Fix the official `pi` login and default model, then rerun `larkin setup --runtime external-pi`.");
+    parts.push("Fix the official `pi` login and default model, then rerun `larkin setup --runtime pi`.");
     if (options.agentExisted) {
         parts.push("This Agent already exists; after a successful setup you can switch models with `larkin model <provider>/<model>`.");
     }

package/package.json

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