larkin 0.4.7 → 0.4.9

package/README.md

@@ -87,6 +87,8 @@ Feishu clients do not reliably render Markdown links such as `[label](URL)` as c
 
 ## Setup and configuration
 
+Feishu (https://open.feishu.cn) and Lark (https://open.larksuite.com) are different platforms; `larkin setup` must be told which brand with `--tenant feishu|lark` or the interactive prompt before the authorization QR, and must never emit a `feishu.cn` host for a Lark tenant.
+
 During setup, a new Agent is offered Pi first, followed by Codex and Claude Code. Provider keys are stored only in the selected Agent's private provider directory, not in the ordinary Agent config. Setup also discovers every API-key and OAuth/subscription login exposed by the pinned official Pi registry and delegates those flows to Pi.
 
 Use `larkin pi-auth status` or `larkin pi-auth logout <provider>` to manage Pi auth. The builtin Pi runtime loads Larkin's two supported extensions inline: background subagents and the 60-second foreground bash timeout guard are enabled without writing extension files or arguments. A compatible external Pi installation keeps the existing explicit `-e` extension path.

package/dist/agent/context-prompt.cjs

@@ -16,7 +16,7 @@ const agent_cli_capabilities_js_1 = require("./agent-cli-capabilities.cjs");
  * 5. 版本化：每次实质改动 bump LARKIN_STANDING_PROMPT_VERSION，并同步 eval 数据集/graders/断言。
  * 6. 用 eval 验证：行为变化必须配套固定场景 + rubric（evals/*、test/support/*-grader.mjs、live 测试）。
  */
-exports.LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v20";
+exports.LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v21";
 /**
  * Agent 间协作唤醒引导（issue #75）：纯文本 @ 不会产生飞书 mention 事件，
  * 必须由模型直接构造真实的 mention 元素；`--mention` 扩展参数已移除。
@@ -126,6 +126,7 @@ class ContextPromptBuilder {
             "## Feishu IM command map",
             "",
             `Use only the Larkin-owned \`${executable}\` command for Feishu. Bot identity, private configuration, and freshness are Runtime-bound; the wrapper delegates to the unmodified global official CLI. Use \`${executable} <command> --help\`, never invoke bare \`lark-cli\`, and never pass \`--agent\`, \`--as user\`, \`--profile\`, or \`--config-dir\`. If a command reports a missing scope, relay that error unchanged and ask the user to authorize it; do not bypass the scope boundary.`,
+            "If a platform URL must be shown, use the current Agent tenant host; never emit feishu.cn for a Lark tenant.",
             `Use the exact Inbox target for history reads. For \`thread:<chat_id>:<thread_id>\`, run \`${executable} im +threads-messages-list --thread <thread_id> --order desc --page-size 10 --no-reactions --json\`. For \`chat:<chat_id>\`, run \`${executable} im +chat-messages-list --chat-id <chat_id> --order desc --page-size 10 --no-reactions --json\`.`,
             "Successful history response messages are always at `data.messages`. Never use a chat-wide fallback for a thread target, never merge stderr with `2>&1` before parsing JSON, and never truncate structured output before parsing it.",
             "If the scoped history read fails or its schema is invalid, fail visibly. Do not reuse remembered or hard-coded text to make the task appear successful.",

package/dist/agent/context-prompt.mjs

@@ -13,7 +13,7 @@ import { agentCliPromptCapabilities } from "./agent-cli-capabilities.mjs";
  * 5. 版本化：每次实质改动 bump LARKIN_STANDING_PROMPT_VERSION，并同步 eval 数据集/graders/断言。
  * 6. 用 eval 验证：行为变化必须配套固定场景 + rubric（evals/*、test/support/*-grader.mjs、live 测试）。
  */
-export const LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v20";
+export const LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v21";
 /**
  * Agent 间协作唤醒引导（issue #75）：纯文本 @ 不会产生飞书 mention 事件，
  * 必须由模型直接构造真实的 mention 元素；`--mention` 扩展参数已移除。
@@ -123,6 +123,7 @@ export class ContextPromptBuilder {
             "## Feishu IM command map",
             "",
             `Use only the Larkin-owned \`${executable}\` command for Feishu. Bot identity, private configuration, and freshness are Runtime-bound; the wrapper delegates to the unmodified global official CLI. Use \`${executable} <command> --help\`, never invoke bare \`lark-cli\`, and never pass \`--agent\`, \`--as user\`, \`--profile\`, or \`--config-dir\`. If a command reports a missing scope, relay that error unchanged and ask the user to authorize it; do not bypass the scope boundary.`,
+            "If a platform URL must be shown, use the current Agent tenant host; never emit feishu.cn for a Lark tenant.",
             `Use the exact Inbox target for history reads. For \`thread:<chat_id>:<thread_id>\`, run \`${executable} im +threads-messages-list --thread <thread_id> --order desc --page-size 10 --no-reactions --json\`. For \`chat:<chat_id>\`, run \`${executable} im +chat-messages-list --chat-id <chat_id> --order desc --page-size 10 --no-reactions --json\`.`,
             "Successful history response messages are always at `data.messages`. Never use a chat-wide fallback for a thread target, never merge stderr with `2>&1` before parsing JSON, and never truncate structured output before parsing it.",
             "If the scoped history read fails or its schema is invalid, fail visibly. Do not reuse remembered or hard-coded text to make the task appear successful.",

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 [--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. 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|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).`,
     status: `Usage: larkin status [--json]
 Show Agent configuration, bot identity, credentials, and connection status. Use --json for readiness automation.`,
     agents: `Usage: larkin agents [--json]

package/dist/app/runtime-agent-config.mjs

@@ -9,6 +9,7 @@ import { assertSecureBotsDirectory, readSecureBotCredential, validCredentialReco
 import { resolveOfficialLarkCli } from "./official-lark-cli.mjs";
 import { internalCommandSpec } from "./internal-command.mjs";
 import { assertAgentWorkspaceBound, larkChannelSourceConfigPath, larkChannelWorkspaceConfigPath, managedLarkCliEnv, } from "./agent-lark-cli-workspace.mjs";
+import { accountTenantFromOpenHost, openPlatformHost, } from "../feishu/platform-hosts.mjs";
 function assertSecureProfileDirectory(directory) {
     const stat = fs.lstatSync(directory);
     if (!stat.isDirectory() || stat.isSymbolicLink()
@@ -140,7 +141,7 @@ export function hydrateRuntimeAgent(configDir, agent) {
     return {
         ...agent,
         feishuAppSecret: credential.appSecret,
-        feishuDomain: credential.tenant === "lark" ? "https://open.larksuite.com" : "https://open.feishu.cn",
+        feishuDomain: openPlatformHost(credential.tenant),
         credentialRevision,
     };
 }
@@ -248,7 +249,7 @@ export function installRuntimeCommandShims(agent) {
     }
     return commandDir;
 }
-function sourceProjection(agent, env) {
+export function sourceProjection(agent, env) {
     const configDir = path.resolve(env.LARKIN_CONFIG_DIR || "");
     if (!configDir)
         throw new Error("LARKIN_CONFIG_DIR required for lark-channel source projection");
@@ -261,7 +262,7 @@ function sourceProjection(agent, env) {
         accounts: { app: {
                 id: agent.feishuAppId,
                 secret: { source: "exec", provider: "larkin-bot-credential", id: agent.feishuAppId },
-                tenant: agent.feishuDomain === "https://open.larksuite.com" ? "lark" : "feishu",
+                tenant: accountTenantFromOpenHost(agent.feishuDomain),
             } },
         secrets: { providers: { "larkin-bot-credential": {
                     source: "exec", command: provider.command, args: provider.args,
@@ -294,6 +295,9 @@ function validateSourceProjection(file, agent) {
         throw new Error("lark-channel source projection 不得包含 plaintext secret 字段");
     if (root.credentialRevision !== agent.credentialRevision)
         throw new Error(`Agent ${agent.agentId} lark-channel credential revision mismatch`);
+    if (app?.tenant !== accountTenantFromOpenHost(agent.feishuDomain)) {
+        throw new Error(`Agent ${agent.agentId} lark-channel source projection tenant mismatch`);
+    }
 }
 export function syncAgentProfile(agent, env, dependencies = {}) {
     const expected = path.join(path.resolve(env.LARKIN_CONFIG_DIR || ""), "state", "agents", agent.agentId, "lark-cli-config");

package/dist/app/setup.mjs

@@ -82,6 +82,11 @@ Options:
   --base-url <url>                      custom 端点（provider=custom 时必填；也可覆盖 preset 默认端点）
   --model <id>                          模型 ID；默认取 provider 预设。不同 runtime 的模型可用
                                           \`larkin model\` 查看 / 切换
+  --tenant feishu|lark                  授权二维码之前选择品牌。默认 feishu（accounts.feishu.cn /
+                                          https://open.feishu.cn）。Lark 用 --tenant lark
+                                          （accounts.larksuite.com / https://open.larksuite.com）。
+                                          交互式未指定时会先询问。飞书与 Lark 是不同平台，
+                                          Lark 租户不得使用 feishu.cn 主机。
 
 setup handles browser authorization, permission grants, credential storage, Agent configuration,
 and target-only hot attach. Each Agent is identified by its bot App ID: selecting the same bot reuses
@@ -152,6 +157,12 @@ export async function main() {
             registerArgs.push("--pi-distribution", normalizedRuntime.distribution);
     }
     registerArgs.push("--comment-subscription", OPT.commentSubscription);
+    if (has("--tenant")) {
+        const tenant = flag("--tenant");
+        if (tenant !== "feishu" && tenant !== "lark")
+            die("--tenant 只支持 feishu 或 lark");
+        registerArgs.push("--tenant", tenant === "lark" ? "lark" : "feishu");
+    }
     for (const name of ["--provider", "--api-key", "--base-url", "--model"]) {
         const value = flag(name);
         if (value)

package/dist/feishu/host-shell.cjs

@@ -61,6 +61,7 @@ const internal_command_js_1 = require("../app/internal-command.cjs");
 const agent_lark_cli_workspace_js_1 = require("../app/agent-lark-cli-workspace.cjs");
 const agent_readiness_js_1 = require("../app/agent-readiness.cjs");
 const document_comment_js_1 = require("./document-comment.cjs");
+const platform_hosts_js_1 = require("./platform-hosts.cjs");
 const PENDING_DOCUMENT_COMMENT_LIMIT = 256;
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -152,7 +153,7 @@ function loadAgents(env, testEventSource, larkinHome, reconcileAgentWorkspaceImp
             }
         }
         if (!testEventSource && (typeof candidate.feishuAppSecret !== "string" || !candidate.feishuAppSecret.trim()
-            || !["https://open.feishu.cn", "https://open.larksuite.com"].includes(String(candidate.feishuDomain)))) {
+            || !(0, platform_hosts_js_1.isOpenPlatformHost)(candidate.feishuDomain))) {
             throw new Error(`LARKIN_AGENTS_CONFIG Agent ${id} 缺少有效 channel 凭证/domain`);
         }
         const expectedWorkspace = node_path_1.default.join(larkinHome, "agents", id);
@@ -742,7 +743,7 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
         const channel = createLarkChannel({
             appId: agent.feishuAppId,
             appSecret: agent.feishuAppSecret,
-            domain: agent.feishuDomain || "https://open.feishu.cn",
+            domain: (0, platform_hosts_js_1.requireOpenDomain)(agent.feishuDomain),
             source: "larkin",
             policy: { dmMode: "open", requireMention: false, respondToMentionAll: true },
             // issue #88：关闭 SDK 的防抖批量合并（默认 600ms），逐条投递，
@@ -857,7 +858,7 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
             const channel = createLarkChannel({
                 appId: agent.feishuAppId,
                 appSecret: agent.feishuAppSecret,
-                domain: agent.feishuDomain || "https://open.feishu.cn",
+                domain: (0, platform_hosts_js_1.requireOpenDomain)(agent.feishuDomain),
                 source: "larkin",
                 policy: { dmMode: "open", requireMention: false, respondToMentionAll: true },
                 // issue #88：关闭 SDK 的防抖批量合并（默认 600ms），逐条投递，
@@ -1165,6 +1166,9 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
                     }, 80);
                     hostState.updateStatus(agent, { droughtReconnectAt, droughtReconnectAbandonedAt: null });
                     reconnectFns.get(agent.agentId)?.();
+                    void runtimeHost.scanPendingInboxUpdates?.(agent.agentId)?.catch((error) => {
+                        log(`drought reconnect inbox scan failed agent=${agent.name}: ${errorMessage(error)}`);
+                    });
                 }).catch((error) => {
                     maintenance.inFlight = false;
                     if (shuttingDown || fataling)

package/dist/feishu/host-shell.mjs

@@ -21,6 +21,7 @@ import { processCommandToken } from "../app/internal-command.mjs";
 import { managedOfficialLarkCli } from "../app/agent-lark-cli-workspace.mjs";
 import { isChannelReconnecting, isRuntimeReadinessCurrent } from "../app/agent-readiness.mjs";
 import { documentCommentMessageId, documentCommentNoticeType, projectDocumentCommentEnvelope, resolveDocumentCommentContext, } from "./document-comment.mjs";
+import { isOpenPlatformHost, requireOpenDomain } from "./platform-hosts.mjs";
 const PENDING_DOCUMENT_COMMENT_LIMIT = 256;
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -112,7 +113,7 @@ function loadAgents(env, testEventSource, larkinHome, reconcileAgentWorkspaceImp
             }
         }
         if (!testEventSource && (typeof candidate.feishuAppSecret !== "string" || !candidate.feishuAppSecret.trim()
-            || !["https://open.feishu.cn", "https://open.larksuite.com"].includes(String(candidate.feishuDomain)))) {
+            || !isOpenPlatformHost(candidate.feishuDomain))) {
             throw new Error(`LARKIN_AGENTS_CONFIG Agent ${id} 缺少有效 channel 凭证/domain`);
         }
         const expectedWorkspace = path.join(larkinHome, "agents", id);
@@ -702,7 +703,7 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
         const channel = createLarkChannel({
             appId: agent.feishuAppId,
             appSecret: agent.feishuAppSecret,
-            domain: agent.feishuDomain || "https://open.feishu.cn",
+            domain: requireOpenDomain(agent.feishuDomain),
             source: "larkin",
             policy: { dmMode: "open", requireMention: false, respondToMentionAll: true },
             // issue #88：关闭 SDK 的防抖批量合并（默认 600ms），逐条投递，
@@ -817,7 +818,7 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
             const channel = createLarkChannel({
                 appId: agent.feishuAppId,
                 appSecret: agent.feishuAppSecret,
-                domain: agent.feishuDomain || "https://open.feishu.cn",
+                domain: requireOpenDomain(agent.feishuDomain),
                 source: "larkin",
                 policy: { dmMode: "open", requireMention: false, respondToMentionAll: true },
                 // issue #88：关闭 SDK 的防抖批量合并（默认 600ms），逐条投递，
@@ -1125,6 +1126,9 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
                     }, 80);
                     hostState.updateStatus(agent, { droughtReconnectAt, droughtReconnectAbandonedAt: null });
                     reconnectFns.get(agent.agentId)?.();
+                    void runtimeHost.scanPendingInboxUpdates?.(agent.agentId)?.catch((error) => {
+                        log(`drought reconnect inbox scan failed agent=${agent.name}: ${errorMessage(error)}`);
+                    });
                 }).catch((error) => {
                     maintenance.inFlight = false;
                     if (shuttingDown || fataling)

package/dist/feishu/platform-hosts.cjs

@@ -0,0 +1,49 @@
+"use strict";
+// Official Feishu vs Lark hosts from @larksuite/cli ResolveEndpoints
+// (open / accounts / applink) plus Open-host docs and console paths.
+// Do not add larkoffice.com or any unofficial host.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLATFORM_HOSTS = void 0;
+exports.parseLarkinTenant = parseLarkinTenant;
+exports.openPlatformHost = openPlatformHost;
+exports.registerAppAccountsHost = registerAppAccountsHost;
+exports.isOpenPlatformHost = isOpenPlatformHost;
+exports.requireOpenDomain = requireOpenDomain;
+exports.accountTenantFromOpenHost = accountTenantFromOpenHost;
+exports.PLATFORM_HOSTS = {
+    feishu: {
+        open: "https://open.feishu.cn",
+        accounts: "https://accounts.feishu.cn",
+        applink: "https://applink.feishu.cn",
+        docs: "https://open.feishu.cn/document",
+        console: "https://open.feishu.cn/app",
+    },
+    lark: {
+        open: "https://open.larksuite.com",
+        accounts: "https://accounts.larksuite.com",
+        applink: "https://applink.larksuite.com",
+        docs: "https://open.larksuite.com/document",
+        console: "https://open.larksuite.com/app",
+    },
+};
+function parseLarkinTenant(value) {
+    return value === "feishu" || value === "lark" ? value : null;
+}
+function openPlatformHost(tenant) {
+    return exports.PLATFORM_HOSTS[tenant].open;
+}
+function registerAppAccountsHost(tenant) {
+    // node-sdk registerApp.domain / larkDomain interpolate https://${host}
+    return new URL(exports.PLATFORM_HOSTS[tenant].accounts).host;
+}
+function isOpenPlatformHost(value) {
+    return value === exports.PLATFORM_HOSTS.feishu.open || value === exports.PLATFORM_HOSTS.lark.open;
+}
+function requireOpenDomain(value) {
+    if (isOpenPlatformHost(value))
+        return value;
+    throw new Error("missing or invalid Open Platform domain");
+}
+function accountTenantFromOpenHost(domain) {
+    return domain === exports.PLATFORM_HOSTS.lark.open ? "lark" : "feishu";
+}

package/dist/feishu/platform-hosts.mjs

@@ -0,0 +1,40 @@
+// Official Feishu vs Lark hosts from @larksuite/cli ResolveEndpoints
+// (open / accounts / applink) plus Open-host docs and console paths.
+// Do not add larkoffice.com or any unofficial host.
+export const PLATFORM_HOSTS = {
+    feishu: {
+        open: "https://open.feishu.cn",
+        accounts: "https://accounts.feishu.cn",
+        applink: "https://applink.feishu.cn",
+        docs: "https://open.feishu.cn/document",
+        console: "https://open.feishu.cn/app",
+    },
+    lark: {
+        open: "https://open.larksuite.com",
+        accounts: "https://accounts.larksuite.com",
+        applink: "https://applink.larksuite.com",
+        docs: "https://open.larksuite.com/document",
+        console: "https://open.larksuite.com/app",
+    },
+};
+export function parseLarkinTenant(value) {
+    return value === "feishu" || value === "lark" ? value : null;
+}
+export function openPlatformHost(tenant) {
+    return PLATFORM_HOSTS[tenant].open;
+}
+export function registerAppAccountsHost(tenant) {
+    // node-sdk registerApp.domain / larkDomain interpolate https://${host}
+    return new URL(PLATFORM_HOSTS[tenant].accounts).host;
+}
+export function isOpenPlatformHost(value) {
+    return value === PLATFORM_HOSTS.feishu.open || value === PLATFORM_HOSTS.lark.open;
+}
+export function requireOpenDomain(value) {
+    if (isOpenPlatformHost(value))
+        return value;
+    throw new Error("missing or invalid Open Platform domain");
+}
+export function accountTenantFromOpenHost(domain) {
+    return domain === PLATFORM_HOSTS.lark.open ? "lark" : "feishu";
+}

package/dist/runtime/runtime-host.cjs

@@ -120,8 +120,20 @@ function boundedRecords(agent) {
     const bounded = [...active, ...terminal].slice(-MAX_DELIVERIES);
     agent.records = new Map(bounded.map((record) => [record.deliveryId, record]));
     agent.byMessage = new Map(bounded.map((record) => [record.messageId, record.deliveryId]));
+    prunePromotedInboxUpdateIds(agent);
     return bounded;
 }
+function prunePromotedInboxUpdateIds(agent) {
+    if (!agent.promotedInboxUpdateIds?.size)
+        return;
+    for (const id of agent.promotedInboxUpdateIds) {
+        if (!agent.records.has(id))
+            agent.promotedInboxUpdateIds.delete(id);
+    }
+    if (agent.promotedInboxUpdateIds.size <= MAX_DELIVERIES)
+        return;
+    agent.promotedInboxUpdateIds = new Set([...agent.promotedInboxUpdateIds].slice(-MAX_DELIVERIES));
+}
 function createRuntimeHost(options) {
     const managed = new Map();
     const listeners = new Set();
@@ -294,6 +306,20 @@ function createRuntimeHost(options) {
         }
     };
     const TURN_END_RETRY_REASON = "runtime turn ended before Inbox consumption was observed";
+    const INBOX_UPDATE_PROMOTE_REASON = "accepted inbox_update promoted after Agent became idle";
+    const isInboxUpdateKind = (kind) => kind === "inbox_update" || kind === "inbox-update";
+    const agentIsIdleForInboxScan = (agent) => !agent.stopped && !agent.busy && !agent.submitting && !agent.turnInProgress && !agent.starting && Boolean(agent.session);
+    const acceptedInboxStillPending = (agent, record) => {
+        if (!agent.stateStore?.readNdjson)
+            return true;
+        try {
+            return agent.stateStore.readNdjson("inbox")
+                .some((row) => row?.message_id === record.messageId);
+        }
+        catch {
+            return false;
+        }
+    };
     /**
      * Runtime acceptance acknowledges only the notification. At the safe turn
      * boundary, canonical Inbox presence decides whether that same delivery
@@ -494,6 +520,7 @@ function createRuntimeHost(options) {
                 agent.retryAfterSubmit = false;
                 queueMicrotask(() => { void retryPending(agent); });
             }
+            queueMicrotask(() => { void scanAndPromoteAcceptedInboxUpdates(agent); });
         }
     };
     const retryPending = async (agent) => {
@@ -533,6 +560,45 @@ function createRuntimeHost(options) {
                 agent.retryPendingInFlight = null;
         }
     };
+    /**
+     * After busy/submitting clears, accepted inbox_update notices have no later
+     * turn boundary. Promote each delivery id at most once to a wake.
+     */
+    const scanAndPromoteAcceptedInboxUpdates = async (agent) => {
+        if (!agentIsIdleForInboxScan(agent))
+            return;
+        if (agent.compactionMachines.size > 0 || agent.compactionRecoveryInFlight.size > 0)
+            return;
+        const candidates = [...agent.records.values()].filter((record) => record.status === "accepted"
+            && isInboxUpdateKind(record.input?.kind) && !agent.promotedInboxUpdateIds.has(record.deliveryId));
+        if (!candidates.length)
+            return;
+        reconcileExternalConsumption(agent);
+        let promoted = 0;
+        for (const record of candidates) {
+            const current = agent.records.get(record.deliveryId);
+            if (current?.status !== "accepted")
+                continue;
+            if (!acceptedInboxStillPending(agent, current)) {
+                reconcileAbsentCanonical(agent, current);
+                continue;
+            }
+            agent.promotedInboxUpdateIds.add(current.deliveryId);
+            current.reason = INBOX_UPDATE_PROMOTE_REASON;
+            current.retryable = true;
+            const finalRecord = setRecord(agent, current, "pending");
+            if (finalRecord.status === "consumed")
+                continue;
+            emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: finalRecord.deliveryId,
+                messageId: finalRecord.messageId, status: "deferred", reason: INBOX_UPDATE_PROMOTE_REASON });
+            promoted += 1;
+        }
+        if (!promoted)
+            return;
+        if (agent.retryPendingInFlight)
+            agent.retryAfterSubmit = true;
+        await retryPending(agent);
+    };
     const scheduleRecreate = (agent, reason) => {
         if (agent.stopped || agent.retryTimer || agent.starting || agent.session)
             return;
@@ -870,6 +936,7 @@ function createRuntimeHost(options) {
                 if (outcome !== "failed")
                     return retryPending(agent);
             });
+            queueMicrotask(() => { void scanAndPromoteAcceptedInboxUpdates(agent); });
         }
         else if (event.type === "activity") {
             if (agent.turnInProgress && event.activity !== "internal")
@@ -1230,6 +1297,14 @@ function createRuntimeHost(options) {
             };
         },
         isBusy(agentId) { const agent = managed.get(agentId); return Boolean(agent?.busy || agent?.submitting || agent?.starting); },
+        async scanPendingInboxUpdates(agentId) {
+            const agents = agentId ? [managed.get(agentId)] : [...managed.values()];
+            for (const agent of agents) {
+                if (!agent || agent.stopped)
+                    continue;
+                await scanAndPromoteAcceptedInboxUpdates(agent);
+            }
+        },
         async resetSession(agentId) {
             const agent = managed.get(agentId);
             if (!agent || agent.stopped)
@@ -1546,7 +1621,8 @@ function createRuntimeHost(options) {
                     compactionMachines: new Map(), compactionRecoveryInFlight: new Set(), piOverflowCompactionFailed: new Set(),
                     piProactiveCompaction: null, piProactiveCompactionGeneration: null, piProactiveCompactionSession: null,
                     piProactiveCompactionFailedGeneration: null, readiness: null,
-                    turnInProgress: false, turnHadFailure: false, turnHadAuthenticatedOutput: false, authFailureActive: false };
+                    turnInProgress: false, turnHadFailure: false, turnHadAuthenticatedOutput: false, authFailureActive: false,
+                    promotedInboxUpdateIds: new Set() };
                 const startupConsumed = [];
                 const startupQuarantined = [];
                 for (const record of agent.records.values()) {
@@ -1648,6 +1724,7 @@ function createRuntimeHost(options) {
                         : { inputId: existing.deliveryId, deliveryId: existing.deliveryId, kind: "wake", text: "", attempt: priorAttempt + 1 };
                     delete existing.reason;
                     delete existing.retryable;
+                    agent.promotedInboxUpdateIds.delete(existing.deliveryId);
                     setRecord(agent, existing, "pending");
                     const receipt = await (telemetry?.phase(messageId, "runtime.deliver", api_1.SpanKind.PRODUCER, () => submit(agent, existing, agent.busy || agent.submitting)) ?? submit(agent, existing, agent.busy || agent.submitting));
                     telemetry?.delivery(agentId, messageId, receipt.status);

package/dist/runtime/runtime-host.mjs

@@ -111,8 +111,20 @@ function boundedRecords(agent) {
     const bounded = [...active, ...terminal].slice(-MAX_DELIVERIES);
     agent.records = new Map(bounded.map((record) => [record.deliveryId, record]));
     agent.byMessage = new Map(bounded.map((record) => [record.messageId, record.deliveryId]));
+    prunePromotedInboxUpdateIds(agent);
     return bounded;
 }
+function prunePromotedInboxUpdateIds(agent) {
+    if (!agent.promotedInboxUpdateIds?.size)
+        return;
+    for (const id of agent.promotedInboxUpdateIds) {
+        if (!agent.records.has(id))
+            agent.promotedInboxUpdateIds.delete(id);
+    }
+    if (agent.promotedInboxUpdateIds.size <= MAX_DELIVERIES)
+        return;
+    agent.promotedInboxUpdateIds = new Set([...agent.promotedInboxUpdateIds].slice(-MAX_DELIVERIES));
+}
 export function createRuntimeHost(options) {
     const managed = new Map();
     const listeners = new Set();
@@ -285,6 +297,20 @@ export function createRuntimeHost(options) {
         }
     };
     const TURN_END_RETRY_REASON = "runtime turn ended before Inbox consumption was observed";
+    const INBOX_UPDATE_PROMOTE_REASON = "accepted inbox_update promoted after Agent became idle";
+    const isInboxUpdateKind = (kind) => kind === "inbox_update" || kind === "inbox-update";
+    const agentIsIdleForInboxScan = (agent) => !agent.stopped && !agent.busy && !agent.submitting && !agent.turnInProgress && !agent.starting && Boolean(agent.session);
+    const acceptedInboxStillPending = (agent, record) => {
+        if (!agent.stateStore?.readNdjson)
+            return true;
+        try {
+            return agent.stateStore.readNdjson("inbox")
+                .some((row) => row?.message_id === record.messageId);
+        }
+        catch {
+            return false;
+        }
+    };
     /**
      * Runtime acceptance acknowledges only the notification. At the safe turn
      * boundary, canonical Inbox presence decides whether that same delivery
@@ -485,6 +511,7 @@ export function createRuntimeHost(options) {
                 agent.retryAfterSubmit = false;
                 queueMicrotask(() => { void retryPending(agent); });
             }
+            queueMicrotask(() => { void scanAndPromoteAcceptedInboxUpdates(agent); });
         }
     };
     const retryPending = async (agent) => {
@@ -524,6 +551,45 @@ export function createRuntimeHost(options) {
                 agent.retryPendingInFlight = null;
         }
     };
+    /**
+     * After busy/submitting clears, accepted inbox_update notices have no later
+     * turn boundary. Promote each delivery id at most once to a wake.
+     */
+    const scanAndPromoteAcceptedInboxUpdates = async (agent) => {
+        if (!agentIsIdleForInboxScan(agent))
+            return;
+        if (agent.compactionMachines.size > 0 || agent.compactionRecoveryInFlight.size > 0)
+            return;
+        const candidates = [...agent.records.values()].filter((record) => record.status === "accepted"
+            && isInboxUpdateKind(record.input?.kind) && !agent.promotedInboxUpdateIds.has(record.deliveryId));
+        if (!candidates.length)
+            return;
+        reconcileExternalConsumption(agent);
+        let promoted = 0;
+        for (const record of candidates) {
+            const current = agent.records.get(record.deliveryId);
+            if (current?.status !== "accepted")
+                continue;
+            if (!acceptedInboxStillPending(agent, current)) {
+                reconcileAbsentCanonical(agent, current);
+                continue;
+            }
+            agent.promotedInboxUpdateIds.add(current.deliveryId);
+            current.reason = INBOX_UPDATE_PROMOTE_REASON;
+            current.retryable = true;
+            const finalRecord = setRecord(agent, current, "pending");
+            if (finalRecord.status === "consumed")
+                continue;
+            emit({ type: "delivery", agentId: agent.config.agentId, deliveryId: finalRecord.deliveryId,
+                messageId: finalRecord.messageId, status: "deferred", reason: INBOX_UPDATE_PROMOTE_REASON });
+            promoted += 1;
+        }
+        if (!promoted)
+            return;
+        if (agent.retryPendingInFlight)
+            agent.retryAfterSubmit = true;
+        await retryPending(agent);
+    };
     const scheduleRecreate = (agent, reason) => {
         if (agent.stopped || agent.retryTimer || agent.starting || agent.session)
             return;
@@ -861,6 +927,7 @@ export function createRuntimeHost(options) {
                 if (outcome !== "failed")
                     return retryPending(agent);
             });
+            queueMicrotask(() => { void scanAndPromoteAcceptedInboxUpdates(agent); });
         }
         else if (event.type === "activity") {
             if (agent.turnInProgress && event.activity !== "internal")
@@ -1221,6 +1288,14 @@ export function createRuntimeHost(options) {
             };
         },
         isBusy(agentId) { const agent = managed.get(agentId); return Boolean(agent?.busy || agent?.submitting || agent?.starting); },
+        async scanPendingInboxUpdates(agentId) {
+            const agents = agentId ? [managed.get(agentId)] : [...managed.values()];
+            for (const agent of agents) {
+                if (!agent || agent.stopped)
+                    continue;
+                await scanAndPromoteAcceptedInboxUpdates(agent);
+            }
+        },
         async resetSession(agentId) {
             const agent = managed.get(agentId);
             if (!agent || agent.stopped)
@@ -1537,7 +1612,8 @@ export function createRuntimeHost(options) {
                     compactionMachines: new Map(), compactionRecoveryInFlight: new Set(), piOverflowCompactionFailed: new Set(),
                     piProactiveCompaction: null, piProactiveCompactionGeneration: null, piProactiveCompactionSession: null,
                     piProactiveCompactionFailedGeneration: null, readiness: null,
-                    turnInProgress: false, turnHadFailure: false, turnHadAuthenticatedOutput: false, authFailureActive: false };
+                    turnInProgress: false, turnHadFailure: false, turnHadAuthenticatedOutput: false, authFailureActive: false,
+                    promotedInboxUpdateIds: new Set() };
                 const startupConsumed = [];
                 const startupQuarantined = [];
                 for (const record of agent.records.values()) {
@@ -1639,6 +1715,7 @@ export function createRuntimeHost(options) {
                         : { inputId: existing.deliveryId, deliveryId: existing.deliveryId, kind: "wake", text: "", attempt: priorAttempt + 1 };
                     delete existing.reason;
                     delete existing.retryable;
+                    agent.promotedInboxUpdateIds.delete(existing.deliveryId);
                     setRecord(agent, existing, "pending");
                     const receipt = await (telemetry?.phase(messageId, "runtime.deliver", SpanKind.PRODUCER, () => submit(agent, existing, agent.busy || agent.submitting)) ?? submit(agent, existing, agent.busy || agent.submitting));
                     telemetry?.delivery(agentId, messageId, receipt.status);

package/dist/setup/bot-register.mjs

@@ -17,6 +17,7 @@ import { probeNativeRuntimeReadiness } from "../runtime/runtime-readiness.mjs";
 import { configureBuiltinPiProviderModel, stageBuiltinPiProvider, validatePiBaseUrl, validateBuiltinPiProviderSelection, listProviderModels, PI_PROVIDER_PRESETS } from "../runtime/pi-provider-config.mjs";
 import { beginBuiltinPiCredentialTransaction, createOfficialPiCredentialRuntime, createOfficialPiAuthInteraction, createOfficialPiModelRuntime, createOfficialPiLogoutRuntime, createOfficialPiRegistryRuntime, listOfficialPiAuthProviders, logoutOfficialPiProvider, officialPiAuthStatus, runOfficialPiLogin, verifyOfficialPiProviderTurn, } from "../runtime/pi-official-auth.mjs";
 import { documentCommentSubscriptionCapability, markDocumentCommentSubscriptionVerified, } from "../platform/callback-capability.mjs";
+import { openPlatformHost, parseLarkinTenant, registerAppAccountsHost, } from "../feishu/platform-hosts.mjs";
 // qrcode-terminal does not publish TypeScript declarations.
 // @ts-expect-error bundled CommonJS dependency
 import qrcodePackage from "qrcode-terminal";
@@ -217,6 +218,45 @@ export async function applyDocumentCommentSubscription(input) {
         throw new Error("document comment local verified-state persistence failed; external subscription rollback was verified");
     }
 }
+async function resolveSelectedTenant() {
+    const raw = flag("--tenant");
+    if (raw !== undefined) {
+        const parsed = parseLarkinTenant(raw);
+        if (parsed === "feishu" || parsed === "lark")
+            return parsed;
+        die("--tenant 只支持 feishu 或 lark");
+    }
+    if (process.stdin.isTTY && process.stdout.isTTY && !testFixture) {
+        const questioner = terminalSetupQuestioner();
+        try {
+            const answer = (await questioner.ask("选择平台（授权二维码必须对应正确品牌；lark-cli --domain 是业务域，品牌是 feishu|lark）：\n"
+                + "  1. 中国飞书 Feishu（accounts.feishu.cn / https://open.feishu.cn）\n"
+                + "  2. International Lark（accounts.larksuite.com / https://open.larksuite.com）\n> ")).trim();
+            if (answer === "1" || /^feishu$/i.test(answer))
+                return "feishu";
+            if (answer === "2" || /^lark$/i.test(answer))
+                return "lark";
+            die("必须选择 1/feishu 或 2/lark；未开始授权");
+        }
+        finally {
+            questioner.close?.();
+        }
+    }
+    return "feishu";
+}
+function persistTenant(selected, userInfo) {
+    const brand = userInfo?.tenant_brand;
+    if (brand === undefined || brand === null || brand === "")
+        return selected;
+    const observed = parseLarkinTenant(brand);
+    if (observed !== "feishu" && observed !== "lark") {
+        die("授权返回的租户品牌非法；未执行凭证同步、文件写入或 Agent 绑定");
+    }
+    if (observed !== selected) {
+        die(`授权返回的租户 ${observed} 与预先选择的 ${selected} 不一致；未执行凭证同步、文件写入或 Agent 绑定`);
+    }
+    return selected;
+}
 function botVerificationRetryable(result) {
     const text = `${typeof result.stdout === "string" ? result.stdout : ""}\n${typeof result.stderr === "string" ? result.stderr : ""}`;
     return /\binvalid_client\b|specified app does not exist|EAI_AGAIN|ENOTFOUND|ECONNREFUSED|ECONNRESET|ETIMEDOUT|fetch failed|temporary network|too many requests|\b(?:429|502|503|504)\b/i.test(text);
@@ -374,7 +414,7 @@ async function fetchBotInfoViaHttp(appId, tenant) {
     }
     if (typeof credential.appSecret !== "string" || !credential.appSecret)
         return null;
-    const base = tenant === "lark" ? "https://open.larksuite.com" : "https://open.feishu.cn";
+    const base = openPlatformHost(tenant === "lark" ? "lark" : "feishu");
     try {
         const tokenResponse = await fetch(`${base}/open-apis/auth/v3/tenant_access_token/internal`, {
             method: "POST",
@@ -424,7 +464,10 @@ export async function main() {
         say(`setup 内部机器人注册阶段
 
 用法:
-  bun bot-register.mjs --auto
+  bun bot-register.mjs --auto [--tenant feishu|lark]
+
+--tenant 在授权二维码之前选择品牌。默认 feishu（accounts.feishu.cn）；
+Lark 必须用 --tenant lark 或交互选择，授权主机是 accounts.larksuite.com。
 
 完成后自动：按返回 appId 判定新旧 → 同步并校验 lark-cli bot 凭证 →
   原子写 bots/<appId>.json（0600）→ 绑定 Agent。`);
@@ -447,7 +490,8 @@ export async function main() {
     }
     if (!autoSelect)
         die("setup 注册阶段必须由交互式选择流程启动");
-    say("[setup 1/5] 在网页选择已有机器人或创建新机器人");
+    const selectedTenant = await resolveSelectedTenant();
+    say(`[setup 1/5] 在${selectedTenant === "lark" ? " International Lark" : "中国飞书 Feishu"}网页选择已有机器人或创建新机器人`);
     if (commentSubscription === "application") {
         say(`! 已显式选择 ${commentSubscription} 维度评论订阅：一旦平台状态验证为已订阅，Bot 可见文档中实际送达的每条支持评论都会进入 Inbox 并唤醒 Agent，不要求 @Bot。`);
         say("! setup 将通过官方 lark-cli 的结构化 API 请求创建该订阅，并以只读 subscription_status 二次核验；不会从意图或事件配置推断订阅已生效。");
@@ -483,6 +527,8 @@ export async function main() {
     let pollingCount = 0;
     const result = await registerApp({
         source: "larkin",
+        domain: registerAppAccountsHost(selectedTenant),
+        larkDomain: registerAppAccountsHost("lark"),
         addons: {
             scopes: { tenant: TENANT_SCOPES },
             events: { items: { tenant: TENANT_EVENTS } },
@@ -509,9 +555,9 @@ export async function main() {
         die("授权完成但未取得有效凭证；未执行凭证同步、文件写入或 Agent 绑定");
     const id = rawId;
     const secret = rawSecret;
+    const tenant = persistTenant(selectedTenant, userInfo);
     const botsDir = ensureSecureBotsDir();
     say(`[setup 3/5] 正在按 App ID ${id} 刷新凭证并配置 Agent`);
-    const tenant = userInfo?.tenant_brand === "lark" ? "lark" : "feishu";
     const botFile = path.join(botsDir, `${id}.json`);
     const prior = (() => {
         try {

package/dist/setup/grant-scopes.mjs

@@ -8,6 +8,8 @@ import { registerApp as channelRegisterApp } from "@larksuite/channel";
 import { markSetupCapabilitiesRequested } from "../platform/callback-capability.mjs";
 import * as larkinConfig from "../platform/config.mjs";
 import { managedOfficialLarkCli } from "../app/agent-lark-cli-workspace.mjs";
+import { loadValidatedBotCredential } from "./run-credential-preflight.mjs";
+import { parseLarkinTenant, registerAppAccountsHost } from "../feishu/platform-hosts.mjs";
 // qrcode-terminal does not publish TypeScript declarations.
 // @ts-expect-error bundled CommonJS dependency
 import qrcodePackage from "qrcode-terminal";
@@ -41,7 +43,19 @@ if (explicitAppId && explicitAppId !== selected.feishuAppId)
 if (!/^cli_[A-Za-z0-9]+$/.test(APP_ID))
     throw new Error(`无效飞书（Lark） App ID：${APP_ID}`);
 const SEND_TO = flag("--send-to", "");
-const TENANT = flag("--tenant", "feishu");
+const explicitTenant = argv.includes("--tenant") ? flag("--tenant", "") : "";
+if (argv.includes("--tenant") && !parseLarkinTenant(explicitTenant)) {
+    throw new Error("--tenant 只支持 feishu 或 lark");
+}
+function storedCredentialTenant() {
+    try {
+        return loadValidatedBotCredential(path.join(config.larkinHome, "bots"), APP_ID).tenant;
+    }
+    catch {
+        return "feishu";
+    }
+}
+const TENANT = parseLarkinTenant(explicitTenant) ?? storedCredentialTenant();
 const WAIT_MIN = Number(flag("--wait-min", "9"));
 const URL_FILE = flag("--url-file", "");
 const TENANT_SCOPES = [
@@ -108,9 +122,8 @@ export async function main() {
             sendUrlToChat(info.url, minutes);
         },
         onStatusChange: (info) => log(`[grant] 状态: ${info.status}`),
+        domain: registerAppAccountsHost(TENANT),
     };
-    if (TENANT === "lark")
-        options.domain = "lark";
     let result;
     try {
         result = await registerApp(options);

package/package.json

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