larkin 0.4.27 → 0.4.29

package/dist/app/agent-cli.mjs

@@ -157,7 +157,7 @@ function agentConfigRequest(argv, env, config, agent, dependencies) {
     const target = config.agents[targetId];
     if (!target)
         throw new Error(`Agent 不存在：${targetId}；运行 larkin config show --json 查看可用 Agent`);
-    const currentDirectory = (runtime = target.runtime) => (dependencies.modelDirectory ?? ((input) => discoverRuntimeModelDirectorySync(input, env)))({
+    const currentDirectory = (runtime = larkinConfig.toUserRuntime(target.runtime, target.piDistribution)) => (dependencies.modelDirectory ?? ((input) => discoverRuntimeModelDirectorySync(input, env)))({
         agentId: target.agentId, cwd: target.workspaceDir, runtime,
     });
     if (operation === "show") {
@@ -593,7 +593,9 @@ export function runAgentCli(argv, env = process.env, dependencies = {}) {
                 kind: "agent", id: agent.agentId, isSelf: true, name, displayName: name,
                 openId: identity?.open_id ?? identity?.openId ?? null,
                 avatarUrl: identity?.avatar_url ?? identity?.avatarUrl ?? null,
-                runtime: agent.runtime, model: agent.model, reasoningEffort: agent.effort ?? null,
+                runtime: agent.runtime,
+                runtimeOption: larkinConfig.toUserRuntime(agent.runtime, agent.piDistribution),
+                model: agent.model, reasoningEffort: agent.effort ?? null,
                 createdAt: agent.createdAt ?? "1970-01-01T00:00:00.000Z",
             });
             return 0;

package/dist/app/agent-config.mjs

@@ -11,7 +11,8 @@ import { isChannelReconnecting, projectAgentReadiness } from "./agent-readiness.
 import { requestAgentUpsert } from "./local-control.mjs";
 import * as larkinConfig from "../platform/config.mjs";
 import { managedOfficialLarkCli } from "./agent-lark-cli-workspace.mjs";
-import { assertBuiltinPiAgentDirectory, ownedPiCatalogAgentDir, piAgentDirectory, piCatalogCommandSpec, piDistributionLabel } from "../runtime/pi-provider-config.mjs";
+import { assertBuiltinPiAgentDirectory, ownedPiCatalogAgentDir, piAgentDirectory, piCatalogCommandSpec } from "../runtime/pi-provider-config.mjs";
+import { RUNTIME_OPTIONS, fromUserRuntime, isUserRuntime, piCatalogDistributionForUserRuntime, toUserRuntime } from "../runtime/user-runtime.mjs";
 import { traceProcessBoundary } from "../platform/process-boundary-trace.mjs";
 function safeDocumentCommentCapabilities(configDir, profile) {
     try {
@@ -223,6 +224,7 @@ if (kind === "agents") {
                 agent_id: agent.agentId,
                 name: agent.name,
                 runtime: agent.runtime,
+                runtimeOption: toUserRuntime(agent.runtime, agent.piDistribution),
                 model: effectiveModel,
                 document_comment: {
                     event: "drive.notice.comment_add_v1",
@@ -293,7 +295,7 @@ if (kind === "agents") {
         say(`  ${agent.name}${agent.name === config.activeAgent ? " [active]" : ""}`);
         const effectiveModel = status?.session?.runtime === agent.runtime && status.session.model ? status.session.model : agent.model;
         const effectiveEffort = status?.session?.runtime === agent.runtime && status.session.reasoningEffort ? status.session.reasoningEffort : agent.effort;
-        say(`    runtime=${agent.runtime}  model=${effectiveModel}${effectiveModel !== agent.model ? `  stored=${agent.model}` : ""}${effectiveEffort ? `  effort=${effectiveEffort}` : ""}`);
+        say(`    runtime=${toUserRuntime(agent.runtime, agent.piDistribution)}  model=${effectiveModel}${effectiveModel !== agent.model ? `  stored=${agent.model}` : ""}${effectiveEffort ? `  effort=${effectiveEffort}` : ""}`);
         if (status?.runtimeReadiness) {
             const current = projectedReadiness.readiness.runtime_ready;
             const state = status.runtimeReadiness.state === "ready" && !current ? "unavailable" : status.runtimeReadiness.state || "incompatible";
@@ -427,7 +429,7 @@ if (!key) {
         say(`共 ${keys.length} 个 agent（用 --agent <appId> 查看/修改指定一个）:`);
         for (const candidate of keys) {
             const item = config.agents[candidate];
-            say(`  ${candidate}${candidate === config.activeAgent ? " [active]" : ""}  runtime=${item.runtime}  model=${item.model}`);
+            say(`  ${candidate}${candidate === config.activeAgent ? " [active]" : ""}  runtime=${toUserRuntime(item.runtime, item.piDistribution)}  model=${item.model}`);
         }
         process.exit(0);
     }
@@ -441,7 +443,12 @@ if (kind === "pi-distribution") {
     if (importExternalProfile && requested !== "builtin")
         die("--import-external-profile 只允许与 builtin 一起使用");
     if (requested === "show") {
-        say(JSON.stringify({ agentId: selectedKey, runtime: agent.runtime, piDistribution: agent.piDistribution ?? "external" }));
+        say(JSON.stringify({
+            agentId: selectedKey,
+            runtime: agent.runtime,
+            runtimeOption: toUserRuntime(agent.runtime, agent.piDistribution),
+            piDistribution: agent.piDistribution ?? "external",
+        }));
         process.exit(0);
     }
     if (requested !== "builtin" && requested !== "external")
@@ -455,7 +462,9 @@ if (kind === "pi-distribution") {
             assertBuiltinPiAgentDirectory(piAgentDirectory(configDir, selectedKey));
         }
         catch {
-            die("内置 Pi provider 尚未为该 Agent 配置；请先运行 larkin setup 完成内置 Pi provider 配置，或使用 --import-external-profile");
+            die(agent.piDistribution === "builtin"
+                ? "内置 Pi provider 尚未为该 Agent 配置。请使用 Dashboard Provider Credentials 或 larkin pi-auth login。"
+                : "内置 Pi provider 尚未为该 Agent 配置。");
         }
     }
     try {
@@ -492,11 +501,18 @@ if ((["model", "effort"].includes(kind || "") && agent.runtime === "claude") ||
     }
 }
 let piCatalog = null;
-if (agent.runtime === "pi" || (kind === "runtime" && value === "pi")) {
-    if (kind === "model" && !value)
-        say(`发行版: ${piDistributionLabel(agent.piDistribution)}`);
+const userRuntime = toUserRuntime(agent.runtime, agent.piDistribution);
+const catalogUserRuntime = kind === "runtime" && (value === "pi" || value === "builtin-pi")
+    ? value
+    : userRuntime;
+if ((kind === "model" || kind === "effort" || kind === "runtime") && !value) {
+    say(`agent=${selectedKey}  runtime=${userRuntime}  model=${agent.model}`);
+}
+const needsLivePiCatalog = (["model", "effort"].includes(kind) && agent.runtime === "pi")
+    || (kind === "runtime" && (value === "pi" || value === "builtin-pi") && Boolean(flagModel));
+if (needsLivePiCatalog) {
     try {
-        const catalogCommand = piCatalogCommandSpec(agent.piDistribution, process.env);
+        const catalogCommand = piCatalogCommandSpec(piCatalogDistributionForUserRuntime(catalogUserRuntime), process.env);
         piCatalog = await discoverPiModelCatalog({
             cwd: String(agent.workspaceDir),
             agentDir: ownedPiCatalogAgentDir(configDir, selectedKey),
@@ -513,10 +529,14 @@ if (agent.runtime === "pi" || (kind === "runtime" && value === "pi")) {
     const loadedPiCatalog = piCatalog;
     for (const diagnostic of loadedPiCatalog.diagnostics)
         console.error(`Pi diagnostic: ${diagnostic}`);
-    catalog.pi = [{ id: "default", label: `default: ${loadedPiCatalog.effectiveModel}` }, ...loadedPiCatalog.models];
+    const piModels = [{ id: "default", label: `default: ${loadedPiCatalog.effectiveModel}` }, ...loadedPiCatalog.models];
+    catalog.pi = piModels;
+}
+function catalogRuntimeKey(runtime) {
+    return isUserRuntime(runtime) ? fromUserRuntime(runtime).runtime : runtime;
 }
 function listModels(runtime, current) {
-    const items = catalog[runtime];
+    const items = catalog[catalogRuntimeKey(runtime)];
     if (!items) {
         say(`  （无 ${runtime} 的目录数据）`);
         return;
@@ -536,7 +556,7 @@ function writeAndHint(mutation) {
         say("  运行 larkin config apply --agent <App ID> 后应用到新 Runtime session");
 }
 function effortChoicesFor(runtime, model) {
-    const entry = catalog[runtime]?.find((candidate) => candidate.id === model);
+    const entry = catalog[catalogRuntimeKey(runtime)]?.find((candidate) => candidate.id === model);
     if (!entry?.supportedReasoningEfforts?.length)
         return null;
     return { list: entry.supportedReasoningEfforts, note: "模型声明", def: entry.defaultReasoningEffort || null };
@@ -554,15 +574,14 @@ function dropEffortIfInvalid(next) {
     return withoutEffort;
 }
 if (kind === "model") {
-    const runtime = agent.runtime;
+    const runtime = userRuntime;
     if (!value) {
-        say(`agent=${selectedKey}  runtime=${runtime}  model=${agent.model}`);
         say(`\n${runtime} 可选模型:`);
         listModels(runtime, agent.model);
         say("\n切换: larkin model <id>");
         process.exit(0);
     }
-    const items = catalog[runtime];
+    const items = catalog[catalogRuntimeKey(runtime)];
     if (items && !items.some((model) => model.id === value)) {
         console.error(`✗ "${value}" 不是 ${runtime} 的合法模型。合法值:`);
         for (const model of items)
@@ -588,13 +607,11 @@ else if (kind === "effort") {
     }
     const choices = effortChoicesFor(agent.runtime, agent.model);
     if (!choices) {
-        say(`agent=${selectedKey}  runtime=${agent.runtime}  model=${agent.model}`);
-        say(`模型 ${agent.runtime}/${agent.model} 未显式声明 supportedReasoningEfforts，不能设置 effort。`);
+        say(`模型 ${userRuntime}/${agent.model} 未显式声明 supportedReasoningEfforts，不能设置 effort。`);
         process.exit(value ? 1 : 0);
     }
     const { list, note, def } = choices;
     if (!value) {
-        say(`agent=${selectedKey}  runtime=${agent.runtime}  model=${agent.model}`);
         say(`effort=${agent.effort || `（未设置，runtime 默认${def ? `，该模型默认 ${def}` : ""}）`}`);
         say(`\n${agent.model} 可选档位（${note}）:`);
         for (const level of list)
@@ -603,7 +620,7 @@ else if (kind === "effort") {
         process.exit(0);
     }
     if (!list.includes(value)) {
-        console.error(`✗ "${value}" 不是 ${agent.runtime}/${agent.model} 的合法档位。合法值: ${list.join(", ")}`);
+        console.error(`✗ "${value}" 不是 ${userRuntime}/${agent.model} 的合法档位。合法值: ${list.join(", ")}`);
         process.exit(1);
     }
     if (value === agent.effort) {
@@ -671,34 +688,33 @@ else if (kind === "chats") {
 }
 else {
     if (!value) {
-        say(`agent=${selectedKey}  runtime=${agent.runtime}  model=${agent.model}`);
         say("\n可选 runtime:");
-        for (const runtime of Object.keys(catalog)) {
-            say(`  ${runtime.padEnd(12)}${runtime === agent.runtime ? "  [← 当前]" : ""}  默认模型=${larkinConfig.defaultModelFor(runtime)}`);
+        for (const runtime of RUNTIME_OPTIONS) {
+            say(`  ${runtime.padEnd(12)}${runtime === userRuntime ? "  [← 当前]" : ""}  默认模型=${larkinConfig.defaultModelFor(runtime)}`);
         }
         say("\n切换: larkin runtime <id> [--model <id>]");
         process.exit(0);
     }
-    if (!catalog[value]) {
-        console.error(`✗ "${value}" 不是合法 runtime。合法值: ${Object.keys(catalog).join(", ")}`);
+    if (!isUserRuntime(value)) {
+        console.error(`✗ "${value}" 不是合法 runtime。合法值: ${RUNTIME_OPTIONS.join(", ")}`);
         process.exit(1);
     }
     let model = flagModel;
     if (model) {
-        const items = catalog[value];
-        if (!items.some((candidate) => candidate.id === model)) {
+        const items = catalog[catalogRuntimeKey(value)];
+        if (!items || !items.some((candidate) => candidate.id === model)) {
             console.error(`✗ "${model}" 不是 ${value} 的合法模型。合法值:`);
-            for (const item of items)
+            for (const item of items || [])
                 console.error(`    ${item.id}`);
             process.exit(1);
         }
     }
     else {
         model = larkinConfig.defaultModelFor(value);
-        if (value !== agent.runtime)
+        if (value !== userRuntime)
             say(`model 随 runtime 重置为默认: ${agent.model} → ${model}（可用 --model 显式指定）`);
     }
-    if (value === agent.runtime && model === agent.model) {
+    if (value === userRuntime && model === agent.model) {
         say(`runtime 已经是 ${value}，无需修改`);
         process.exit(0);
     }

package/dist/app/cli.mjs

@@ -49,8 +49,8 @@ if (runtimeAgentAuthority && command === "comment")
 const commandHelp = {
     start: `Usage: larkin start [--agent <App ID> | --agents <App ID,...>]
 Start one foreground supervisor for the daemon and local dashboard, or reuse it.`,
-    setup: `Usage: larkin setup [--tenant feishu|lark] [--runtime <builtin-pi|external-pi|codex|claude>] [--provider <id> --api-key <key>]
-Run setup to create or connect a bot, configure its Agent, and attach it. Choose Feishu or Lark before the authorization QR (--tenant; default feishu). Interactive terminals keep the guided flow; Agent-driven (non-TTY) runs default to builtin-pi and need --provider/--api-key (or --runtime external-pi).`,
+    setup: `Usage: larkin setup [--tenant feishu|lark] [--runtime <builtin-pi|pi|codex|claude>] [--provider <id> --api-key <key>]
+Run setup to create or connect a bot, configure its Agent, and attach it. Choose Feishu or Lark before the authorization QR (--tenant; default feishu). Interactive terminals keep the guided flow; Agent-driven (non-TTY) runs default to builtin-pi and need --provider/--api-key (or --runtime pi).`,
     status: `Usage: larkin status [--json]
 Show Agent configuration, bot identity, credentials, and connection status. Use --json for readiness automation.`,
     agents: `Usage: larkin agents [--json]
@@ -58,7 +58,7 @@ List every configured Agent and its current local status. Use --json for daemon/
     model: `Usage: larkin model [<model>] [--agent <App ID>]
 Show or change an Agent model.`,
     runtime: `Usage: larkin runtime [<runtime>] [--agent <App ID>] [--model <model>]
-Show or change an Agent runtime.`,
+Show or change an Agent runtime. User-facing ids: pi | builtin-pi | codex | claude.`,
     "pi-distribution": `Usage: larkin pi-distribution [show|builtin|external] [--agent <App ID>] [--snapshot <private-file>] [--import-external-profile]
        larkin pi-distribution rollback --snapshot <private-file>
 Show or change one Pi Agent distribution. builtin requires configured provider state, or explicitly imports the external Pi 0.84.2 profile with --import-external-profile; all changes support config-lock CAS rollback.`,
@@ -84,8 +84,10 @@ Credentials, internal paths, serverId, activeAgent, and raw config are never exp
        larkin session recover --agent <App ID> --reason context-overflow --json [--wait-ready <seconds>]
 Reset replaces one idle, zero-backlog Runtime session. Recover is an explicit operator-only context-window recovery that preserves and replays canonical Inbox deliveries.`,
     "pi-auth": `Usage: larkin pi-auth status [--agent <App ID>] [--json]
+       larkin pi-auth providers [--json]
+       larkin pi-auth login <preset|custom> --agent <App ID> [--model <model>] [--base-url <url>] [--api-key-stdin] [--json]
        larkin pi-auth logout <provider> [--agent <App ID>]
-Show non-sensitive official Pi credential metadata or remove one target provider credential.`,
+Show a redacted builtin Pi provider catalog, configure one existing Agent with a known preset or custom OpenAI-compatible endpoint, or remove one target provider credential. API keys are accepted only from a TTY prompt or --api-key-stdin.`,
     comment: `Usage: larkin comment reply --message-id <doc_comment_message_id> --text '<reply>' --json
 Reply as the Runtime-bound Bot to the exact cloud-document comment locator supplied by canonical Inbox. Retrying the same body is idempotent; a different body appends a follow-up reply to the same comment.`,
     telemetry: `Usage: larkin telemetry <status|export|import|flush>
@@ -130,7 +132,7 @@ Usage: larkin <command>
   config           Inspect effective config/source, edit mention inheritance, or explicitly apply runtime changes
   session reset    Replace one idle, zero-backlog Agent Runtime session for a fresh scenario
   session recover  Explicitly recover a context-overflowed session and replay retained Inbox deliveries
-  pi-auth          Show non-sensitive built-in Pi auth status or logout one provider
+  pi-auth          Show, configure, or logout one built-in Pi Agent provider credential
   comment reply    Reply to the exact cloud-document comment bound by a polled Inbox message
   telemetry        Inspect, export, import, or flush the durable OpenTelemetry trace queue
   <lark-cli 命令组>  im/docs/wiki/drive 等 lark-cli 命令原样转发，机器人身份已锁定（如 larkin im +chat-list）
@@ -144,7 +146,15 @@ Process persistence is managed externally. larkin start stays in the foreground
 }
 const [mode, ...presetArguments] = routes[command];
 const childSpec = internalCommandSpec(mode, [...presetArguments, ...rest]);
-const child = spawn(childSpec.command, childSpec.args, { stdio: "inherit" });
+// 管道 stdin 必须显式转发：Linux 上 inherit 会在父进程排空后再交给子进程，导致 --api-key-stdin 读到空。
+const pipeStdin = command === "pi-auth" && rest.includes("--api-key-stdin") && !process.stdin.isTTY;
+if (pipeStdin && typeof process.stdin.pause === "function")
+    process.stdin.pause();
+const child = spawn(childSpec.command, childSpec.args, {
+    stdio: [pipeStdin ? "pipe" : "inherit", "inherit", "inherit"],
+});
+if (pipeStdin && child.stdin)
+    process.stdin.pipe(child.stdin);
 // Package-manager bin shims add a wrapper process. Forward terminal signals so the actual command
 // does not become an orphan that keeps the machine lock or Feishu connection.
 const signalForwarders = new Map();

package/dist/app/local-control.mjs

@@ -14,6 +14,7 @@ const WINDOWS_SOCKET_BINDING = { device: "0", inode: "0", owner: "0", changeTime
 const AGENT_ID = /^cli_[A-Za-z0-9]+$/;
 const OPERATION_ID = /^[A-Za-z0-9_-]{8,128}$/;
 const AUTHORIZATION = /^[A-Za-z0-9_-]{43,128}$/;
+const CONFIG_SIGNATURE = /^sha256:[a-f0-9]{64}$/;
 const UNIX_SOCKET_PATH_MAX_BYTES = process.platform === "darwin" ? 103 : 107;
 function recoveryErrorText(code) {
     switch (code) {
@@ -159,9 +160,13 @@ function parseRequest(line) {
     if (value.waitReadyMs !== undefined) {
         throw new Error("invalid session reset waitReadyMs");
     }
-    if (Object.keys(value).some((key) => !["operationId", "agentId", "authorization"].includes(key))) {
+    if (Object.keys(value).some((key) => !["operationId", "agentId", "authorization", "expectedSignature"].includes(key))) {
         throw new Error("agent control request 包含未知字段");
     }
+    if (value.expectedSignature !== undefined
+        && (typeof value.expectedSignature !== "string" || !CONFIG_SIGNATURE.test(value.expectedSignature))) {
+        throw new Error("invalid agent upsert expectedSignature");
+    }
     return value;
 }
 function atomicWritePrivateJson(file, value) {
@@ -741,7 +746,11 @@ export function createAgentControlServer({ larkinHome, authorityToken, upsert, r
                         }
                         const execute = async () => {
                             try {
-                                await upsert({ operationId: upsertRequest.operationId, agentId: upsertRequest.agentId });
+                                await upsert({
+                                    operationId: upsertRequest.operationId,
+                                    agentId: upsertRequest.agentId,
+                                    ...(upsertRequest.expectedSignature ? { expectedSignature: upsertRequest.expectedSignature } : {}),
+                                });
                                 return { ok: true, operationId: upsertRequest.operationId, agentId: upsertRequest.agentId };
                             }
                             catch (error) {
@@ -926,7 +935,11 @@ async function requestAgentControl({ larkinHome, timeoutMs = 30_000, request, })
 }
 export async function requestAgentUpsert(input) {
     return requestAgentControl({ larkinHome: input.larkinHome, timeoutMs: input.timeoutMs,
-        request: { operationId: input.operationId ?? crypto.randomUUID(), agentId: input.agentId } });
+        request: {
+            operationId: input.operationId ?? crypto.randomUUID(),
+            agentId: input.agentId,
+            ...(input.expectedSignature ? { expectedSignature: input.expectedSignature } : {}),
+        } });
 }
 export async function requestSessionReset({ larkinHome, agentId, waitReadyMs = 30_000, }) {
     return requestAgentControl({

package/dist/app/pi-auth-cli.mjs

@@ -1,13 +1,234 @@
+import fs from "node:fs";
 import * as larkinConfig from "../platform/config.mjs";
-import { beginBuiltinPiCredentialTransaction, createOfficialPiCredentialRuntime, createOfficialPiLogoutRuntime, logoutOfficialPiProvider, officialPiAuthStatus, } from "../runtime/pi-official-auth.mjs";
+import { createOfficialPiCredentialRuntime, officialPiAuthStatus, } from "../runtime/pi-official-auth.mjs";
+import { configureBuiltinPiProvider, listBuiltinPiProviderCatalog, logoutBuiltinPiProvider, } from "../runtime/pi-provider-login.mjs";
+import { MAX_BUILTIN_PI_API_KEY_LENGTH } from "../runtime/pi-provider-config.mjs";
 const APP_ID = /^cli_[A-Za-z0-9]+$/;
+const USAGE = "Usage: larkin pi-auth status [--agent <App ID>] [--json] | larkin pi-auth providers [--json] | larkin pi-auth login <preset|custom> --agent <App ID> [--model <model>] [--base-url <url>] [--api-key-stdin] [--json] | larkin pi-auth logout <provider> [--agent <App ID>]";
+const API_KEY_ARGV_MESSAGE = "existing-Agent login does not accept --api-key. Use --api-key-stdin or an interactive TTY prompt.";
+const API_KEY_BUDGET_MESSAGE = "API Key 不能为空或包含控制字符";
+const STDIN_CHUNK_BYTES = 1024;
+const STDIN_BOM_BYTES = 3;
+const STDIN_TRAILING_NEWLINE_SLACK = 32;
+const MAX_STDIN_API_KEY_BYTES = MAX_BUILTIN_PI_API_KEY_LENGTH + STDIN_BOM_BYTES + STDIN_TRAILING_NEWLINE_SLACK;
 function flag(args, name) {
     const index = args.indexOf(name);
     return index >= 0 ? args[index + 1] : undefined;
 }
-export async function main(args = process.argv.slice(2), env = process.env) {
+function hasApiKeyArgv(args) {
+    return args.some((argument) => argument === "--api-key" || argument.startsWith("--api-key="));
+}
+function consumeFlags(args, allowed, unary) {
+    let index = 0;
+    while (index < args.length) {
+        const argument = args[index];
+        if (!argument.startsWith("--"))
+            return false;
+        if (unary.has(argument)) {
+            index += 1;
+            continue;
+        }
+        if (allowed.has(argument) && args[index + 1] && !args[index + 1].startsWith("--")) {
+            index += 2;
+            continue;
+        }
+        return false;
+    }
+    return true;
+}
+/** 去掉 BOM 与全部尾部换行；保留内部控制字符给后续校验拒绝。 */
+export function normalizeStdinApiKey(raw) {
+    return raw.replace(/^\uFEFF/, "").replace(/[\r\n]+$/g, "");
+}
+function assertStdinApiKeyBudget(size) {
+    if (size > MAX_STDIN_API_KEY_BYTES)
+        throw new Error(API_KEY_BUDGET_MESSAGE);
+}
+function finishStdinApiKey(chunks) {
+    const normalized = normalizeStdinApiKey(Buffer.concat(chunks).toString("utf8"));
+    if (normalized.length > MAX_BUILTIN_PI_API_KEY_LENGTH)
+        throw new Error(API_KEY_BUDGET_MESSAGE);
+    return normalized;
+}
+function readFdChunk(fd, buffer) {
+    return new Promise((resolve, reject) => {
+        fs.read(fd, buffer, 0, buffer.length, null, (error, bytesRead) => {
+            if (error)
+                reject(error);
+            else
+                resolve(bytesRead);
+        });
+    });
+}
+/** 按块读取 fd，超过 key 上限立即停止，不等待管道 EOF。 */
+async function readBoundedFdSecret(fd) {
+    const chunks = [];
+    let size = 0;
+    const buffer = Buffer.alloc(STDIN_CHUNK_BYTES);
+    while (true) {
+        const bytesRead = await readFdChunk(fd, buffer);
+        if (bytesRead === 0)
+            break;
+        size += bytesRead;
+        assertStdinApiKeyBudget(size);
+        chunks.push(Buffer.from(buffer.subarray(0, bytesRead)));
+    }
+    return finishStdinApiKey(chunks);
+}
+async function readBoundedStreamSecret(stdin) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of stdin) {
+        const bytes = Buffer.from(chunk);
+        size += bytes.length;
+        assertStdinApiKeyBudget(size);
+        chunks.push(bytes);
+    }
+    return finishStdinApiKey(chunks);
+}
+export async function readStdinSecret(stdin) {
+    const stream = stdin;
+    if (typeof stream.fd === "number" && stream.fd >= 0 && !stream.isTTY) {
+        if (typeof stream.pause === "function")
+            stream.pause();
+        try {
+            return await readBoundedFdSecret(stream.fd);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === API_KEY_BUDGET_MESSAGE)
+                throw error;
+            // 回退到异步收集，例如测试传入的假 stream。
+        }
+    }
+    return readBoundedStreamSecret(stdin);
+}
+function createNoEchoQuestioner(stdin, stdout) {
+    return {
+        close() { },
+        secret(prompt) {
+            if (!stdin.isTTY || typeof stdin.setRawMode !== "function") {
+                throw new Error("non-interactive API-key login requires --api-key-stdin");
+            }
+            stdout.write(prompt);
+            const wasRaw = stdin.isRaw;
+            stdin.setRawMode(true);
+            stdin.resume();
+            return new Promise((resolve, reject) => {
+                let value = "";
+                const finish = (error) => {
+                    stdin.off("data", onData);
+                    stdin.setRawMode(Boolean(wasRaw));
+                    stdin.pause();
+                    stdout.write("\n");
+                    if (error)
+                        reject(error);
+                    else
+                        resolve(value);
+                };
+                const onData = (chunk) => {
+                    const bytes = Buffer.from(chunk);
+                    for (const byte of bytes) {
+                        if (byte === 3)
+                            return finish(new Error("pi-auth login cancelled"));
+                        if (byte === 10 || byte === 13)
+                            return finish();
+                        if (byte === 8 || byte === 127) {
+                            value = value.slice(0, -1);
+                            continue;
+                        }
+                        if (byte >= 32 && byte <= 126)
+                            value += String.fromCharCode(byte);
+                    }
+                };
+                stdin.on("data", onData);
+            });
+        },
+    };
+}
+function resolveAgentId(args, env) {
+    const loaded = larkinConfig.loadConfig(env);
+    const agentId = flag(args, "--agent") || loaded.config.activeAgent || undefined;
+    if (!agentId || !APP_ID.test(agentId))
+        throw new Error("请用 --agent <App ID> 选择 Agent");
+    const agent = loaded.config.agents[agentId];
+    if (!agent)
+        throw new Error(`Agent ${agentId} 不存在`);
+    if (agent.runtime !== "pi" || agent.piDistribution !== "builtin")
+        throw new Error(`Agent ${agentId} 不是内置 Pi`);
+    return agentId;
+}
+export async function main(args = process.argv.slice(2), env = process.env, io = { stdin: process.stdin, stdout: process.stdout, isTTY: Boolean(process.stdin.isTTY) }) {
     const action = args[0] || "status";
     const json = args.includes("--json");
+    if (hasApiKeyArgv(args))
+        throw new Error(API_KEY_ARGV_MESSAGE);
+    if (action === "providers") {
+        if (!consumeFlags(args.slice(1), new Set(), new Set(["--json"])))
+            throw new Error(USAGE);
+        const providers = listBuiltinPiProviderCatalog();
+        if (json) {
+            console.log(JSON.stringify({ providers }));
+            return;
+        }
+        console.log("Builtin Pi providers:");
+        for (const entry of providers) {
+            const model = entry.defaultModel ? ` default=${entry.defaultModel}` : " (requires --base-url and --model)";
+            console.log(`  ${entry.id}  ${entry.name}${model}`);
+        }
+        return;
+    }
+    if (action === "login") {
+        const preset = args[1];
+        const rest = args.slice(2);
+        if (!preset || preset.startsWith("--")
+            || !consumeFlags(rest, new Set(["--agent", "--model", "--base-url"]), new Set(["--json", "--api-key-stdin"]))) {
+            throw new Error(USAGE);
+        }
+        const agentId = resolveAgentId(rest, env);
+        const stdinKey = rest.includes("--api-key-stdin");
+        let apiKey = "";
+        if (stdinKey)
+            apiKey = await readStdinSecret(io.stdin);
+        else if (io.isTTY) {
+            const questioner = createNoEchoQuestioner(io.stdin, io.stdout);
+            try {
+                apiKey = await questioner.secret("API Key:\n> ");
+            }
+            finally {
+                questioner.close();
+            }
+        }
+        else {
+            throw new Error("non-interactive API-key login requires --api-key-stdin");
+        }
+        const result = await configureBuiltinPiProvider({
+            agentId,
+            preset,
+            apiKey,
+            model: flag(rest, "--model"),
+            baseUrl: flag(rest, "--base-url"),
+            env,
+        });
+        const payload = {
+            agentId: result.agentId,
+            provider: result.provider,
+            model: result.model,
+            credentialType: result.credentialType,
+            applyState: result.applyState,
+            ...(result.applyError ? { applyError: result.applyError } : {}),
+        };
+        if (json)
+            console.log(JSON.stringify(payload));
+        else {
+            const pending = result.applyState === "applied"
+                ? "applied"
+                : result.applyState === "pending"
+                    ? `pending${result.applyError ? ` (${result.applyError})` : ""}`
+                    : "saved; will apply on larkin start";
+            console.log(`Agent ${result.agentId} provider=${result.provider} model=${result.model} credential=${result.credentialType} apply=${pending}`);
+        }
+        return;
+    }
     const requestedAgent = flag(args, "--agent");
     let index = action === "logout" ? 2 : 1;
     let valid = action === "status" || action === "logout";
@@ -23,9 +244,8 @@ export async function main(args = process.argv.slice(2), env = process.env) {
         }
         valid = false;
     }
-    if (!valid) {
-        throw new Error("Usage: larkin pi-auth status [--agent <App ID>] [--json] | larkin pi-auth logout <provider> [--agent <App ID>]");
-    }
+    if (!valid)
+        throw new Error(USAGE);
     const loaded = larkinConfig.loadConfig(env);
     const agentId = requestedAgent || loaded.config.activeAgent || undefined;
     if (!agentId || !APP_ID.test(agentId))
@@ -50,18 +270,8 @@ export async function main(args = process.argv.slice(2), env = process.env) {
         return;
     }
     const providerId = args[1];
-    if (!providerId || providerId.startsWith("--") || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(providerId)) {
+    if (!providerId || providerId.startsWith("--"))
         throw new Error("logout 需要安全的 provider ID");
-    }
-    const transaction = beginBuiltinPiCredentialTransaction(loaded.configDir, agentId);
-    try {
-        const runtime = await createOfficialPiLogoutRuntime(loaded.configDir, agentId);
-        await logoutOfficialPiProvider(runtime, providerId);
-        transaction.commit();
-    }
-    catch (error) {
-        transaction.rollback();
-        throw error;
-    }
+    await logoutBuiltinPiProvider({ agentId, providerId, env });
     console.log(`Agent ${agentId} 已退出 ${providerId}；其他 provider 未修改`);
 }

package/dist/app/runtime-model-directory.mjs

@@ -7,6 +7,7 @@ import { discoverClaudeModelCatalog } from "../runtime/claude-model-catalog.mjs"
 import { discoverPiModelCatalog } from "../runtime/pi-model-catalog.mjs";
 import { discoverCodexModelCatalog } from "../runtime/codex-model-catalog.mjs";
 import { ownedPiCatalogAgentDir, piCatalogCommandSpec } from "../runtime/pi-provider-config.mjs";
+import { piCatalogDistributionForUserRuntime } from "../runtime/user-runtime.mjs";
 function readTestModelDirectory(env) {
     const fixture = env?.LARKIN_TEST_RUNTIME_MODEL_DIRECTORY_FILE;
     if (!fixture)
@@ -36,7 +37,7 @@ export async function discoverRuntimeModelDirectory(input) {
             ...catalog.models.map(({ id, label, supportedReasoningEfforts }) => ({ id, label, supportedReasoningEfforts })),
         ];
     }
-    if (input.runtime === "pi") {
+    if (input.runtime === "pi" || input.runtime === "builtin-pi") {
         const env = input.env ?? process.env;
         const agentId = input.agentId || "";
         if (!agentId)
@@ -46,7 +47,7 @@ export async function discoverRuntimeModelDirectory(input) {
         const agent = config.agents[agentId];
         if (!agent)
             throw new Error(`unknown agent: ${agentId}`);
-        const catalogCommand = piCatalogCommandSpec(agent.piDistribution, env);
+        const catalogCommand = piCatalogCommandSpec(piCatalogDistributionForUserRuntime(input.runtime), env);
         const catalog = await discoverPiModelCatalog({
             cwd: input.cwd,
             agentDir: ownedPiCatalogAgentDir(configDir, agentId),