larkin 0.4.19 → 0.4.21

package/dist/runtime/pi-supervised-command.mjs

@@ -0,0 +1,420 @@
+import { spawn, spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+export const DEFAULT_WAIT_SECONDS = 60;
+export const DEFAULT_LIFE_SECONDS = 600;
+export const LARKIN_SUPERVISED_COMMAND_CAPABILITY = "larkin-pi-supervised-command-v1";
+const MAX_STREAM_BYTES = 64 * 1024;
+export function supervisedWaitSeconds() {
+    const raw = Number.parseInt(process.env.LARKIN_PI_SUPERVISED_WAIT_SECONDS || "", 10);
+    if (Number.isInteger(raw) && raw > 0)
+        return Math.min(raw, DEFAULT_WAIT_SECONDS);
+    return DEFAULT_WAIT_SECONDS;
+}
+export function supervisedLifeSeconds() {
+    const raw = Number.parseInt(process.env.LARKIN_PI_SUPERVISED_LIFE_SECONDS || "", 10);
+    if (Number.isInteger(raw) && raw > 0)
+        return Math.min(raw, DEFAULT_LIFE_SECONDS);
+    return DEFAULT_LIFE_SECONDS;
+}
+export function resolveSupervisedCwd(root, requested) {
+    if (typeof root !== "string" || root.length === 0)
+        throw new Error("supervised cwd root is required");
+    if (fs.lstatSync(root).isSymbolicLink())
+        throw new Error("supervised cwd must not be a symlink");
+    const base = fs.realpathSync(root);
+    const target = requested && requested.length > 0 ? path.resolve(base, requested) : base;
+    const relative = path.relative(base, target);
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        throw new Error("supervised cwd escapes the session root");
+    let current = base;
+    if (relative && relative !== ".") {
+        for (const part of relative.split(path.sep)) {
+            if (!part || part === ".")
+                continue;
+            current = path.join(current, part);
+            if (fs.lstatSync(current).isSymbolicLink())
+                throw new Error("supervised cwd must not be a symlink");
+        }
+    }
+    const real = fs.realpathSync(current);
+    const prefix = base.endsWith(path.sep) ? base : base + path.sep;
+    if (real !== base && !real.startsWith(prefix))
+        throw new Error("supervised cwd escapes the session root");
+    if (!fs.statSync(real).isDirectory())
+        throw new Error("supervised cwd is not a directory");
+    return real;
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function listDescendantPids(root) {
+    if (process.platform === "win32")
+        return [];
+    const found = new Set();
+    const queue = [root];
+    while (queue.length > 0) {
+        const current = queue.pop();
+        if (current === undefined)
+            break;
+        const listed = spawnSync("pgrep", ["-P", String(current)], { encoding: "utf8" });
+        if (listed.status !== 0 || !listed.stdout)
+            continue;
+        for (const line of listed.stdout.split(/\s+/)) {
+            const child = Number.parseInt(line, 10);
+            if (!Number.isInteger(child) || child <= 0 || found.has(child) || child === root)
+                continue;
+            found.add(child);
+            queue.push(child);
+        }
+    }
+    return [...found];
+}
+function refreshTreePids(pid, known) {
+    known.add(pid);
+    for (const child of listDescendantPids(pid))
+        known.add(child);
+    return [...known];
+}
+async function killProcessTree(pid, known = new Set([pid])) {
+    const descendants = refreshTreePids(pid, known).filter((child) => child !== pid);
+    if (process.platform === "win32") {
+        const result = await new Promise((resolve) => {
+            const child = spawn("taskkill", ["/F", "/T", "/PID", String(pid)], { stdio: "ignore", windowsHide: true });
+            child.once("error", (error) => resolve({ status: null, error }));
+            child.once("exit", (status) => resolve({ status }));
+        });
+        if (result.error && pidAlive(pid))
+            throw result.error;
+    }
+    else {
+        for (const child of [...descendants].reverse()) {
+            try {
+                process.kill(child, "SIGKILL");
+            }
+            catch { /* already dead */ }
+        }
+        try {
+            process.kill(-pid, "SIGKILL");
+        }
+        catch {
+            try {
+                process.kill(pid, "SIGKILL");
+            }
+            catch { /* already dead */ }
+        }
+    }
+    const started = Date.now();
+    const pending = () => pidAlive(pid) || descendants.some((child) => pidAlive(child));
+    while (pending() && Date.now() - started < 2000) {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        if (process.platform !== "win32") {
+            for (const child of descendants) {
+                try {
+                    process.kill(child, "SIGKILL");
+                }
+                catch { /* already dead */ }
+            }
+            try {
+                process.kill(pid, "SIGKILL");
+            }
+            catch { /* already dead */ }
+        }
+    }
+    if (pending())
+        throw new Error(`supervised process tree ${pid} still alive`);
+}
+class ByteCursor {
+    chunks = [];
+    dropped = 0;
+    write(chunk) {
+        let data = chunk;
+        if (chunk.length > MAX_STREAM_BYTES) {
+            this.dropped += chunk.length - MAX_STREAM_BYTES;
+            data = chunk.subarray(chunk.length - MAX_STREAM_BYTES);
+        }
+        this.chunks.push(data);
+        let total = this.chunks.reduce((n, c) => n + c.length, 0);
+        while (total > MAX_STREAM_BYTES && this.chunks.length) {
+            const overflow = total - MAX_STREAM_BYTES;
+            const head = this.chunks[0];
+            if (head.length <= overflow) {
+                this.chunks.shift();
+                this.dropped += head.length;
+                total -= head.length;
+            }
+            else {
+                this.chunks[0] = head.subarray(overflow);
+                this.dropped += overflow;
+                total -= overflow;
+            }
+        }
+    }
+    snapshot(cursor) {
+        const joined = Buffer.concat(this.chunks);
+        let start = Math.max(0, cursor - this.dropped);
+        if (start < joined.length) {
+            while (start < joined.length && (joined[start] & 0b1100_0000) === 0b1000_0000)
+                start++;
+        }
+        let end = joined.length;
+        if (end > start) {
+            let cont = 0;
+            let i = end;
+            while (i > start && (joined[i - 1] & 0b1100_0000) === 0b1000_0000) {
+                i--;
+                cont++;
+            }
+            if (i > start) {
+                const lead = joined[i - 1];
+                const need = lead < 0x80 ? 1 : lead < 0xe0 ? 2 : lead < 0xf0 ? 3 : 4;
+                if (cont + 1 < need)
+                    end = i - 1;
+            }
+        }
+        const slice = joined.subarray(Math.min(start, end), end);
+        return {
+            text: slice.toString("utf8"),
+            cursor: this.dropped + end,
+            truncated: this.dropped > cursor || start > Math.max(0, cursor - this.dropped),
+        };
+    }
+}
+const handles = new Map();
+const terminals = new Map();
+const MAX_TERMINALS = 32;
+function rememberTerminal(id, owner, snapshot) {
+    terminals.set(id, { owner, snapshot });
+    while (terminals.size > MAX_TERMINALS) {
+        const oldest = terminals.keys().next().value;
+        if (!oldest)
+            break;
+        terminals.delete(oldest);
+    }
+}
+function notify(record) {
+    const waiters = record.exitWaiters.splice(0);
+    for (const wake of waiters)
+        wake();
+}
+function finish(record, status, exitCode) {
+    if (record.lifetimeTimer) {
+        clearTimeout(record.lifetimeTimer);
+        record.lifetimeTimer = undefined;
+    }
+    if (record.treePoll) {
+        clearInterval(record.treePoll);
+        record.treePoll = undefined;
+    }
+    if (record.status === "running") {
+        record.status = status;
+        record.exitCode = exitCode;
+    }
+    notify(record);
+}
+export function startSupervisedCommand(input) {
+    if (typeof input.executable !== "string" || input.executable.length === 0) {
+        throw new Error("executable must be a non-empty string");
+    }
+    if (!Array.isArray(input.args) || input.args.some((arg) => typeof arg !== "string")) {
+        throw new Error("args must be a string array");
+    }
+    const cwd = resolveSupervisedCwd(input.cwd);
+    const child = spawn(input.executable, input.args, {
+        cwd,
+        shell: false,
+        detached: process.platform !== "win32",
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    let record;
+    child.on("error", (error) => {
+        if (!record)
+            return;
+        const current = record;
+        void current.chain.then(async () => {
+            await killProcessTree(current.pid, current.treePids);
+            finish(current, "killed", null);
+        });
+        void error;
+    });
+    if (!child.pid)
+        throw new Error("failed to spawn supervised command");
+    const id = randomBytes(16).toString("hex");
+    record = {
+        id,
+        owner: input.owner,
+        child,
+        pid: child.pid,
+        startedAt: Date.now(),
+        deadlineAt: Date.now() + supervisedLifeSeconds() * 1000,
+        stdout: new ByteCursor(),
+        stderr: new ByteCursor(),
+        stdoutCursor: 0,
+        stderrCursor: 0,
+        status: "running",
+        exitCode: null,
+        terminalConsumed: false,
+        cancelRequested: false,
+        exitWaiters: [],
+        treePids: new Set([child.pid]),
+        chain: Promise.resolve(),
+        closed: Promise.resolve(),
+    };
+    const started = record;
+    let markClosed = () => { };
+    started.closed = new Promise((resolve) => { markClosed = resolve; });
+    child.stdout?.on("data", (chunk) => started.stdout.write(Buffer.from(chunk)));
+    child.stderr?.on("data", (chunk) => started.stderr.write(Buffer.from(chunk)));
+    started.treePoll = setInterval(() => {
+        refreshTreePids(started.pid, started.treePids);
+    }, 50);
+    started.treePoll.unref?.();
+    child.once("close", (code) => {
+        markClosed();
+        void started.chain.then(async () => {
+            await killProcessTree(started.pid, started.treePids);
+            finish(started, "exited", code);
+        });
+    });
+    started.lifetimeTimer = setTimeout(() => {
+        void started.chain.then(async () => {
+            if (started.status !== "running")
+                return;
+            await killProcessTree(started.pid, started.treePids);
+            finish(started, "lifetime_exceeded", null);
+        });
+    }, supervisedLifeSeconds() * 1000);
+    started.lifetimeTimer.unref?.();
+    handles.set(id, started);
+    return { handle: id, pid: started.pid };
+}
+function snapshot(record) {
+    const out = record.stdout.snapshot(record.stdoutCursor);
+    const err = record.stderr.snapshot(record.stderrCursor);
+    record.stdoutCursor = out.cursor;
+    record.stderrCursor = err.cursor;
+    return {
+        handle: record.id,
+        pid: record.pid,
+        status: record.status,
+        exitCode: record.exitCode,
+        stdout: out.text,
+        stderr: err.text,
+        stdoutCursor: out.cursor,
+        stderrCursor: err.cursor,
+        truncated: out.truncated || err.truncated,
+    };
+}
+function requireHandle(owner, handle) {
+    const record = handles.get(handle);
+    if (!record || record.owner !== owner)
+        throw new Error("supervised handle not found");
+    return record;
+}
+function enqueue(record, work) {
+    const next = record.chain.then(work, work);
+    record.chain = next.then(() => undefined, () => undefined);
+    return next;
+}
+export async function waitSupervisedCommand(owner, handle, timeoutSeconds) {
+    const remembered = terminals.get(handle);
+    if (remembered && remembered.owner === owner && !handles.has(handle))
+        return remembered.snapshot;
+    const record = requireHandle(owner, handle);
+    return enqueue(record, async () => {
+        const cap = supervisedWaitSeconds();
+        const requested = typeof timeoutSeconds === "number" && timeoutSeconds > 0 ? timeoutSeconds : cap;
+        if (requested > cap)
+            throw new Error(`wait timeout:${requested} exceeds the ${cap}s supervised wait limit`);
+        const remainingLife = Math.max(0, record.deadlineAt - Date.now());
+        const waitMs = Math.min(requested * 1000, remainingLife, cap * 1000);
+        if (record.status === "running" && waitMs > 0) {
+            await new Promise((resolve) => {
+                let done = false;
+                const finishWait = () => {
+                    if (done)
+                        return;
+                    done = true;
+                    record.exitWaiters = record.exitWaiters.filter((item) => item !== finishWait);
+                    resolve();
+                };
+                const timer = setTimeout(finishWait, waitMs);
+                record.exitWaiters.push(() => {
+                    clearTimeout(timer);
+                    finishWait();
+                });
+            });
+        }
+        if (record.status !== "running" && record.terminalConsumed) {
+            throw new Error("supervised terminal result already consumed");
+        }
+        const result = snapshot(record);
+        if (result.status !== "running") {
+            record.terminalConsumed = true;
+            rememberTerminal(record.id, owner, result);
+            handles.delete(record.id);
+        }
+        return result;
+    });
+}
+export async function cancelSupervisedCommand(owner, handle) {
+    const remembered = terminals.get(handle);
+    if (remembered && remembered.owner === owner && !handles.has(handle))
+        return remembered.snapshot;
+    const record = requireHandle(owner, handle);
+    return enqueue(record, async () => {
+        record.cancelRequested = true;
+        notify(record);
+        if (record.status === "running") {
+            await killProcessTree(record.pid, record.treePids);
+            record.status = "killed";
+        }
+        if (record.lifetimeTimer) {
+            clearTimeout(record.lifetimeTimer);
+            record.lifetimeTimer = undefined;
+        }
+        await record.closed;
+        const result = record.terminalConsumed && remembered?.owner === owner
+            ? remembered.snapshot
+            : snapshot(record);
+        record.terminalConsumed = true;
+        rememberTerminal(record.id, owner, result);
+        handles.delete(record.id);
+        return result;
+    });
+}
+export async function reapSupervisedCommands(owner) {
+    for (const [id, remembered] of terminals) {
+        if (remembered.owner === owner)
+            terminals.delete(id);
+    }
+    const owned = [...handles.values()].filter((record) => record.owner === owner);
+    const errors = [];
+    await Promise.all(owned.map(async (record) => {
+        try {
+            await cancelSupervisedCommand(owner, record.id);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        if (record.lifetimeTimer)
+            clearTimeout(record.lifetimeTimer);
+        try {
+            await killProcessTree(record.pid, record.treePids);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        handles.delete(record.id);
+    }));
+    if (errors.length > 0)
+        throw errors[0];
+}

package/dist/setup/bot-register.mjs

@@ -19,6 +19,7 @@ import { beginBuiltinPiCredentialTransaction, createOfficialPiCredentialRuntime,
 import { documentCommentSubscriptionCapability, markDocumentCommentSubscriptionVerified, } from "../platform/callback-capability.mjs";
 import { openPlatformHost, parseLarkinTenant, registerAppAccountsHost, } from "../feishu/platform-hosts.mjs";
 import { authorizationUrlFailureMessage, presentAuthorizationUrl } from "./setup-authorization-url.mjs";
+import { missingGrantedTenantScopes } from "./tenant-scope-grant.mjs";
 // qrcode-terminal does not publish TypeScript declarations.
 // @ts-expect-error bundled CommonJS dependency
 import qrcodePackage from "qrcode-terminal";
@@ -28,6 +29,7 @@ const testFixture = process.env.LARKIN_TEST_BOT_REGISTER_MODULE
 const registerApp = testFixture?.registerApp ?? channelRegisterApp;
 const qrcode = testFixture?.qrcode ?? qrcodePackage;
 const spawnSync = testFixture?.spawnSync ?? systemSpawnSync;
+const spawnChild = testFixture?.spawn ?? systemSpawn;
 const synchronizeAgentProfile = testFixture?.syncAgentProfile ?? syncAgentProfile;
 const resolveOfficialCli = testFixture?.resolveOfficialLarkCli ?? resolveOfficialLarkCli;
 const wait = testFixture?.wait ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
@@ -306,7 +308,7 @@ async function runBindProcess(command, args) {
         return spawnSync(command, [...args], { env: process.env, stdio: "inherit" }).status;
     }
     return await new Promise((resolve, reject) => {
-        const child = systemSpawn(command, [...args], { env: process.env, stdio: "inherit" });
+        const child = spawnChild(command, [...args], { env: process.env, stdio: "inherit" });
         trackPendingChild(child);
         let killTimer = null;
         const abort = () => {
@@ -339,7 +341,7 @@ async function runBoundedCliProcess(command, args, env, label) {
         return { status: result.status, stdout: result.stdout || "", stderr: result.stderr || "" };
     }
     return await new Promise((resolve, reject) => {
-        const child = systemSpawn(command, [...args], { env, stdio: ["ignore", "pipe", "pipe"] });
+        const child = spawnChild(command, [...args], { env, stdio: ["ignore", "pipe", "pipe"] });
         trackPendingChild(child);
         let stdout = "";
         let stderr = "";
@@ -641,12 +643,13 @@ Lark 必须用 --tenant lark：授权二维码是官方 /page/cli（begin 仍走
         : commentSubscription === "none" || !priorSubscription
             ? { mode: "none", status: "safe-default", source: "setup-default", updatedAt: requestedAt }
             : priorSubscription;
-    if (!flag("--runtime") && (!testFixture || process.env.LARKIN_TEST_ENABLE_AGENT_CHOICE === "1")) {
+    const injectedAgentChoice = testFixture?.collectSetupAgentChoice;
+    if (!flag("--runtime") && (!testFixture || injectedAgentChoice || process.env.LARKIN_TEST_ENABLE_AGENT_CHOICE === "1")) {
         const existing = larkinConfig.loadConfig(process.env).config.agents[id];
         // The official resolver performs a synchronous login-shell probe. Resolve it
         // exactly once before the credential heartbeat lock becomes active.
         resolvedSetupOfficialCli = resolveOfficialCli({ env: process.env });
-        const questioner = terminalSetupQuestioner();
+        const questioner = injectedAgentChoice ? { ask: async () => "", secret: async () => "" } : terminalSetupQuestioner();
         // One setup-owned transaction starts before status/logout and remains active
         // through selection, login, bind, readiness, and the final setup commit.
         pendingPiAuthTransaction = beginBuiltinPiCredentialTransaction(CFG_DIR, id);
@@ -657,37 +660,43 @@ Lark 必须用 --tenant lark：授权二维码是官方 /page/cli（begin 仍走
             report: (message) => say(message),
         };
         try {
-            const requested = await collectSetupAgentChoice(questioner, existing, authServices);
-            const choice = await recoverUnavailableExternalPi(requested, questioner, () => probeNativeRuntimeReadiness({
-                runtime: "pi", agentId: id, cwd: path.join(CFG_DIR, "agents", id), env: process.env,
-            }), (message) => say(`! ${message}`), authServices);
+            const requested = injectedAgentChoice
+                ? await injectedAgentChoice()
+                : await collectSetupAgentChoice(questioner, existing, authServices);
+            const choice = injectedAgentChoice
+                ? requested
+                : await recoverUnavailableExternalPi(requested, questioner, () => probeNativeRuntimeReadiness({
+                    runtime: "pi", agentId: id, cwd: path.join(CFG_DIR, "agents", id), env: process.env,
+                }), (message) => say(`! ${message}`), authServices);
             if (choice) {
                 let serializedChoice = choice;
                 if (choice.runtime === "pi" && choice.distribution === "builtin") {
-                    const official = choice.preset === "official" ? choice : null;
-                    const configured = official ? null : configureBuiltinPiProviderModel(CFG_DIR, id, choice);
-                    const providerId = official?.providerId || configured.provider;
-                    const authType = official?.authType || "api_key";
-                    let piRuntime;
-                    try {
-                        say(`正在通过捆绑官方 Pi 登录 ${providerId}（${authType}）…`);
-                        piRuntime = await createOfficialPiModelRuntime(CFG_DIR, id);
-                        await runOfficialPiLogin(piRuntime, providerId, authType, createOfficialPiAuthInteraction({ questioner, report: (message) => say(message), openUrl: openBrowser }));
-                    }
-                    catch {
-                        pendingPiAuthTransaction.rollback();
-                        pendingPiAuthTransaction = null;
-                        throw new Error(`官方 Pi ${providerId} 登录失败或已取消；credential/config 未修改`);
-                    }
-                    if (process.env.LARKIN_TEST_SKIP_BUILTIN_PI_PROVIDER_TURN !== "1") {
-                        say("正在验证内置 Pi provider（受控单轮，不发送飞书（Lark）消息）…");
+                    if (!injectedAgentChoice) {
+                        const official = choice.preset === "official" ? choice : null;
+                        const configured = official ? null : configureBuiltinPiProviderModel(CFG_DIR, id, choice);
+                        const providerId = official?.providerId || configured.provider;
+                        const authType = official?.authType || "api_key";
+                        let piRuntime;
                         try {
-                            await verifyOfficialPiProviderTurn(piRuntime, choice.model);
+                            say(`正在通过捆绑官方 Pi 登录 ${providerId}（${authType}）…`);
+                            piRuntime = await createOfficialPiModelRuntime(CFG_DIR, id);
+                            await runOfficialPiLogin(piRuntime, providerId, authType, createOfficialPiAuthInteraction({ questioner, report: (message) => say(message), openUrl: openBrowser }));
                         }
                         catch {
                             pendingPiAuthTransaction.rollback();
                             pendingPiAuthTransaction = null;
-                            throw new Error(`官方 Pi ${providerId} readiness 失败；credential/config 未修改`);
+                            throw new Error(`官方 Pi ${providerId} 登录失败或已取消；credential/config 未修改`);
+                        }
+                        if (process.env.LARKIN_TEST_SKIP_BUILTIN_PI_PROVIDER_TURN !== "1") {
+                            say("正在验证内置 Pi provider（受控单轮，不发送飞书（Lark）消息）…");
+                            try {
+                                await verifyOfficialPiProviderTurn(piRuntime, choice.model);
+                            }
+                            catch {
+                                pendingPiAuthTransaction.rollback();
+                                pendingPiAuthTransaction = null;
+                                throw new Error(`官方 Pi ${providerId} readiness 失败；credential/config 未修改`);
+                            }
                         }
                     }
                     serializedChoice = { ...choice, authCompleted: true, readinessCompleted: true };
@@ -850,6 +859,21 @@ Lark 必须用 --tenant lark：授权二维码是官方 /page/cli（begin 仍走
         }
         if (!verified)
             throw new Error("Bot identity verification failed");
+        const scopeResult = await runIdentityProcess(official.command, [...official.argsPrefix, "api", "GET", "/open-apis/application/v6/scopes"], cliEnv);
+        let scopePayload;
+        try {
+            scopePayload = JSON.parse(scopeResult.stdout || "");
+        }
+        catch {
+            scopePayload = null;
+        }
+        const missing = missingGrantedTenantScopes(scopePayload);
+        if (scopeResult.status !== 0 || missing.length > 0) {
+            const reason = scopeResult.status !== 0
+                ? `scopes API 失败 status=${scopeResult.status}`
+                : `缺 ${missing.join(", ")}`;
+            throw new Error(`Bot tenant scope 未就绪，${reason}；+chat-list 成功不能当作可发群消息。请在开发者后台开通后重跑 setup，不要重建 Agent。`);
+        }
         if (commentSubscription !== "preserve") {
             const reconciled = await applyDocumentCommentSubscription({
                 mode: commentSubscription,
@@ -901,6 +925,8 @@ Lark 必须用 --tenant lark：授权二维码是官方 /page/cli（begin 仍走
     }
     catch (error) {
         const diagnostic = errorMessage(error);
+        if (diagnostic.startsWith("Bot tenant scope 未就绪"))
+            die(diagnostic);
         if (diagnostic.startsWith("document comment application subscription")
             || diagnostic.startsWith("document comment local verified-state persistence"))
             say(`! ${diagnostic}`);

package/dist/setup/grant-scopes.mjs

@@ -10,6 +10,7 @@ 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";
+import { presentAuthorizationUrl } from "./setup-authorization-url.mjs";
 // qrcode-terminal does not publish TypeScript declarations.
 // @ts-expect-error bundled CommonJS dependency
 import qrcodePackage from "qrcode-terminal";
@@ -108,18 +109,26 @@ export async function main() {
         },
         onQRCodeReady: (info) => {
             const minutes = Math.max(1, Math.round(info.expireIn / 60));
+            const official = resolveManagedOfficialCli(selected, process.env);
+            const presented = presentAuthorizationUrl(info.url, {
+                tenant: TENANT,
+                larkCliVersion: official.command.version,
+            });
+            if (TENANT === "lark" && /\/page\/launcher(?:\?|$)/.test(presented)) {
+                throw new Error("Lark 租户拒绝把 /page/launcher 交给浏览器");
+            }
             log("\n请用飞书（Lark）扫码或打开链接，确认给应用增补权限：\n");
-            qrcode.generate(info.url, { small: true });
-            log(`\n链接: ${info.url}\n有效期约 ${minutes} 分钟（⚠️ 需本进程保持轮询，否则 user_code 立即失效）\n`);
+            qrcode.generate(presented, { small: true });
+            log(`\n链接: ${presented}\n有效期约 ${minutes} 分钟（⚠️ 需本进程保持轮询，否则 user_code 立即失效）\n`);
             if (URL_FILE) {
                 try {
-                    fs.writeFileSync(URL_FILE, info.url);
+                    fs.writeFileSync(URL_FILE, presented);
                 }
                 catch (error) {
                     log(`[grant] 写 url-file 失败: ${error instanceof Error ? error.message : String(error)}`);
                 }
             }
-            sendUrlToChat(info.url, minutes);
+            sendUrlToChat(presented, minutes);
         },
         onStatusChange: (info) => log(`[grant] 状态: ${info.status}`),
         domain: registerAppAccountsHost(TENANT),

package/dist/setup/tenant-scope-grant.mjs

@@ -0,0 +1,16 @@
+/** Tenant scopes the freshness gate needs on the Bot application. */
+export const FRESHNESS_REQUIRED_TENANT_SCOPES = ["im:message.group_msg"];
+function asRows(payload) {
+    if (!payload || typeof payload !== "object")
+        return [];
+    const root = payload;
+    const raw = Array.isArray(root.data?.scopes) ? root.data.scopes
+        : Array.isArray(root.scopes) ? root.scopes
+            : [];
+    return raw.filter((row) => !!row && typeof row === "object");
+}
+/** grant_status 1 is granted on GET /open-apis/application/v6/scopes. */
+export function missingGrantedTenantScopes(payload, required = FRESHNESS_REQUIRED_TENANT_SCOPES) {
+    const rows = asRows(payload);
+    return required.filter((name) => !rows.some((row) => row.scope_name === name && row.grant_status === 1));
+}

package/package.json

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