@evandu/super-pi 0.1.131 → 0.1.133

package/dist/client/index.html

@@ -8,8 +8,8 @@
     <link rel="alternate icon" href="/favicon.ico" />
     <link rel="apple-touch-icon" href="/favicon.svg" />
     <title>Super Pi</title>
-    <script type="module" crossorigin src="/assets/index-BApJ3Zbq.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-CXB6U5mz.css">
+    <script type="module" crossorigin src="/assets/index-YEN4ysHF.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-D3MEG8uH.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/server/agents.js

@@ -447,7 +447,27 @@ export async function readAgents(directory, options = {}) {
             throw error;
         }
         for (const file of entries.filter((name) => name.toLowerCase().endsWith(".md")).sort()) {
-            const source = await readFile(join(dir, file), "utf8");
+            // A FILE THAT CANNOT BE READ IS THE SAME KIND OF PROBLEM AS ONE THAT CANNOT BE PARSED.
+            //
+            // The function's own reason for existing says it plainly: "one typo in one agent must not take
+            // down the picker and hide every other agent with it". A file that cannot be READ is at least as
+            // ordinary as that - on Windows "another program has this file open" is a Tuesday, not an
+            // emergency - and it used to be the one unguarded step in this loop: the parse failure below is
+            // collected as a problem, while the read failure was thrown, so a single locked file emptied the
+            // whole directory. Four callers ate that: the main agent's own definition (the turn could not
+            // start), the roster handed to sub-agents on every turn, the roster used when dispatching one,
+            // and the picker (which came back with an empty agent list).
+            let source;
+            try {
+                source = await readFile(join(dir, file), "utf8");
+            }
+            catch (error) {
+                const fileId = file.replace(/\.md$/i, "");
+                if (!seenIds.has(fileId)) {
+                    problems.push({ file, message: `读取失败：${error instanceof Error ? error.message : String(error)}` });
+                }
+                continue;
+            }
             const parsed = parseDefinition(file, source);
             if ("message" in parsed) {
                 const fileId = file.replace(/\.md$/i, "");

package/dist/server/application/feishu-service.d.ts

@@ -0,0 +1,179 @@
+import { FeishuCli } from "../feishu-cli.js";
+/**
+ * The largest request the Feishu endpoint accepts.
+ *
+ * The Markdown of a document rides in the request body, so the cap is generous for a document and
+ * small enough that a runaway paste is refused rather than accepted.
+ */
+export declare const MAX_FEISHU_REQUEST_BYTES: number;
+/**
+ * WHAT THE PANEL NEEDS TO SHOW, in words a person can act on.
+ */
+export type FeishuStatus = {
+    /** Whether the official CLI is on this machine at all. */
+    installed: boolean;
+    version?: string;
+    /** The application the CLI is configured with, when it has one. */
+    appId?: string;
+    /** Whether a person has authorized the CLI to act as them. */
+    userReady: boolean;
+    /** Whether the CLI can act as the application itself. */
+    botReady: boolean;
+    /** The identity the CLI will use by default. */
+    identity?: "user" | "bot";
+    /** Whether the agent can read and write documents right now. */
+    connected: boolean;
+    /**
+     * WHICH STEP OF THE GUIDE THE PERSON IS ON.
+     *
+     * 1 = install the CLI, 2 = connect the account, 3 = ready. The panel draws the three steps and
+     * marks this one, so "what do I do now" is answered by where the cursor is rather than by a
+     * sentence the person has to interpret.
+     */
+    step: 1 | 2 | 3;
+    /** What to do next, in one sentence. */
+    message: string;
+    /** The CLI's own words, when it had something to say about the situation. */
+    detail?: string;
+    /** The CLI's own hint, which usually names the exact command to run. */
+    hint?: string;
+    /** Whether the check actually reached Feishu. */
+    verified?: boolean;
+    /**
+     * WHETHER THE APPLICATION ITSELF HAS TO BE REBUILT.
+     *
+     * Distinct from "step 2": a person whose application is fine but who has not logged in still
+     * needs step 2, while a person whose credential was refused needs a NEW application. Telling
+     * those two apart is what keeps a transient network failure from being answered by "let me
+     * create you another application".
+     */
+    rebuild?: boolean;
+};
+/** The outcome of starting the connect flow. */
+export type FeishuConnectResult = {
+    ok: boolean;
+    /** Which step the person is on: creating an application, or authorizing their account. */
+    step?: "app" | "login";
+    /** The URL to open in a browser. */
+    verificationUri?: string;
+    /** The device code, kept server-side until the person says they are done. */
+    deviceCode?: string;
+    message: string;
+    /** Feishu's own "what to do about it", when there was one. */
+    hint?: string;
+};
+/**
+ * THE FEISHU SERVICE: what an agent can do with the cloud documents of a Feishu enterprise.
+ *
+ * IT OWNS NO CREDENTIAL. The official CLI owns them, in the OS keychain, and this service only
+ * runs commands. That is the whole point of going through the CLI: Super Pi never sees an App
+ * Secret, never sees a user token, and never writes a credential file to disk.
+ */
+export declare class FeishuService {
+    private readonly cli;
+    /** The device code of a login that is waiting for the person to authorize it. */
+    private pendingDeviceCode?;
+    /** Whether an application registration is running and waiting for the browser confirmation. */
+    private pendingAppCreation;
+    constructor(cli?: FeishuCli);
+    /**
+     * WHAT THE CLI CAN DO RIGHT NOW.
+     *
+     * The states a person can be in, and what each one means for the agent:
+     *
+     * - The CLI is not installed: nothing works, and the fix is one command.
+     * - The CLI has no application: `config init --new` creates one through a browser confirmation,
+     *   so the developer console is never visited.
+     * - The application exists but its credential is no longer accepted: the CLI says
+     *   `verify_failed` and names the reason, and the fix is a new application - which is the same
+     *   browser confirmation, so it stays one button.
+     * - The application works but no person is logged in: the agent can act as the application, but
+     *   it cannot reach that person's own documents until they authorize it.
+     */
+    status(): Promise<FeishuStatus>;
+    /**
+     * CHECKS THE CONNECTION, and says whether it actually works.
+     *
+     * The status already verifies; this is the same answer shaped for a button, so that a person can
+     * ask "it still doesn't work, why?" and get the CLI's own verdict rather than a guess.
+     */
+    verify(): Promise<{
+        ok: boolean;
+        message: string;
+        detail?: string;
+        hint?: string;
+    }>;
+    /**
+     * STARTS THE CONNECT FLOW.
+     *
+     * Two steps, and which one runs is decided by what the CLI already has:
+     *
+     * - No application, or one whose credential no longer works: `config init --new` registers a
+     *   fresh application through a browser confirmation. It BLOCKS until the person confirms, so it
+     *   runs in the background and the URL is taken from its output. The broken case goes here too,
+     *   because a new application is the one repair that needs no secret to be typed into a form.
+     * - A working application but no person: `auth login --no-wait --json` asks for a device code
+     *   and hands back the URL to open. The code is kept here until the person says they are done.
+     */
+    connect(): Promise<FeishuConnectResult>;
+    /**
+     * FINISHES THE FLOW, once the person says they are done.
+     *
+     * TWO KINDS OF "DONE", and the difference is what the CLI is waiting for:
+     *
+     * - An application is being registered: `config init --new` finishes by itself once the person
+     *   confirms in the browser, so there is nothing to hand back. The status is re-read and the
+     *   answer is whether the application showed up.
+     * - A login is being authorized: the device code is handed back to the CLI, which completes the
+     *   exchange and stores the token in the keychain. Super Pi never sees the token itself.
+     */
+    completeConnect(): Promise<FeishuConnectResult>;
+    /**
+     * READS A DOCUMENT.
+     *
+     * The CLI resolves a knowledge-base link itself, so a `/wiki/` URL is passed through untouched -
+     * and it answers with Markdown, which is the shape a model wants.
+     */
+    read(input: {
+        url: string;
+    }): Promise<{
+        documentId?: string;
+        revisionId?: number;
+        title?: string;
+        url: string;
+        format: "markdown";
+        content: string;
+    }>;
+    /**
+     * WRITES A DOCUMENT.
+     *
+     * THREE MODES, and the difference between them is who decides what survives:
+     *
+     * - `create` makes a new document. Nothing can be lost, because nothing was there.
+     * - `append` adds to the end. Nothing can be lost either.
+     * - `replace` replaces the whole document. This one CAN lose a person's work, so it needs the
+     *   revision the caller read - the same rule the file panel's write lives by, and for the same
+     *   reason: an agent told to "把这份报告改成正式版" would otherwise destroy a hand edit made an
+     *   hour ago, with no refusal and no warning.
+     *
+     * THE REVISION IS THE ETAG. The CLI passes it as the base revision of the edit, and Feishu
+     * refuses the edit when the document has moved on - so the check is enforced by the API rather
+     * than by a comparison Super Pi makes and then has to keep honest.
+     */
+    write(input: {
+        url?: string;
+        content: string;
+        mode?: "create" | "append" | "replace";
+        title?: string;
+        baseRevisionId?: string;
+    }): Promise<{
+        documentId?: string;
+        revisionId?: number;
+        url?: string;
+        mode: "create" | "append" | "replace";
+    }>;
+    /**
+     * THE TOOL CALL, as the extension sends it.
+     */
+    tool(body: unknown): Promise<unknown>;
+}

package/dist/server/application/feishu-service.js

@@ -0,0 +1,358 @@
+import { FeishuCli, FeishuCliError, errorHint, errorMessage } from "../feishu-cli.js";
+/**
+ * The largest request the Feishu endpoint accepts.
+ *
+ * The Markdown of a document rides in the request body, so the cap is generous for a document and
+ * small enough that a runaway paste is refused rather than accepted.
+ */
+export const MAX_FEISHU_REQUEST_BYTES = 4 * 1024 * 1024;
+/**
+ * THE FEISHU SERVICE: what an agent can do with the cloud documents of a Feishu enterprise.
+ *
+ * IT OWNS NO CREDENTIAL. The official CLI owns them, in the OS keychain, and this service only
+ * runs commands. That is the whole point of going through the CLI: Super Pi never sees an App
+ * Secret, never sees a user token, and never writes a credential file to disk.
+ */
+export class FeishuService {
+    cli;
+    /** The device code of a login that is waiting for the person to authorize it. */
+    pendingDeviceCode;
+    /** Whether an application registration is running and waiting for the browser confirmation. */
+    pendingAppCreation = false;
+    constructor(cli = new FeishuCli()) {
+        this.cli = cli;
+    }
+    /**
+     * WHAT THE CLI CAN DO RIGHT NOW.
+     *
+     * The states a person can be in, and what each one means for the agent:
+     *
+     * - The CLI is not installed: nothing works, and the fix is one command.
+     * - The CLI has no application: `config init --new` creates one through a browser confirmation,
+     *   so the developer console is never visited.
+     * - The application exists but its credential is no longer accepted: the CLI says
+     *   `verify_failed` and names the reason, and the fix is a new application - which is the same
+     *   browser confirmation, so it stays one button.
+     * - The application works but no person is logged in: the agent can act as the application, but
+     *   it cannot reach that person's own documents until they authorize it.
+     */
+    async status() {
+        const status = await this.cli.status();
+        if (!status.installed) {
+            return {
+                installed: false,
+                userReady: false,
+                botReady: false,
+                connected: false,
+                step: 1,
+                message: "还没有安装官方飞书 CLI。在终端里跑一次 npm i -g @larksuite/cli 就行，装完回到这里点「连接飞书账号」。",
+                ...(status.hint ? { hint: status.hint } : {}),
+            };
+        }
+        const common = {
+            installed: true,
+            ...(status.version ? { version: status.version } : {}),
+            ...(status.appId ? { appId: status.appId } : {}),
+            ...(status.verified !== undefined ? { verified: status.verified } : {}),
+            ...(status.note ? { detail: status.note } : {}),
+        };
+        if (!status.appId) {
+            return {
+                ...common,
+                userReady: false,
+                botReady: false,
+                connected: false,
+                step: 2,
+                message: "CLI 已就绪，还差一个应用。点「连接飞书账号」，浏览器里确认一下就有了——不用去开发者后台注册。",
+            };
+        }
+        // A CREDENTIAL THE CLI KNOWS IS BROKEN is the case a plain status would have hidden: the local
+        // file still holds an app, so the panel would have said "已配置", and every document call
+        // would have failed. The CLI's own verdict is the one that can be acted on.
+        const broken = status.botStatus === "verify_failed" || (status.verified === true && !status.botReady && !status.userReady);
+        if (broken) {
+            return {
+                ...common,
+                userReady: false,
+                botReady: false,
+                connected: false,
+                step: 2,
+                rebuild: true,
+                message: `应用的凭据已经失效：${trimSentence(status.botMessage ?? "飞书拒绝了这次验证")}。点「连接飞书账号」会重新走一遍确认流程、建一个可用的应用。`,
+                ...(status.hint ? { hint: status.hint } : {}),
+            };
+        }
+        if (status.verified === false) {
+            return {
+                ...common,
+                userReady: false,
+                botReady: false,
+                connected: false,
+                step: 2,
+                message: "没能连上飞书（本地配置读到了，但验证请求没出去）。检查一下网络，然后点「测试连接」重试。",
+                ...(status.hint ? { hint: status.hint } : {}),
+            };
+        }
+        if (!status.userReady) {
+            return {
+                ...common,
+                userReady: false,
+                botReady: status.botReady,
+                connected: false,
+                step: 2,
+                ...(status.identity ? { identity: status.identity } : {}),
+                message: "应用已经能用，但还没登录你的账号。点「连接飞书账号」在浏览器里授权一下，授权之后 Agent 就能以你的身份读写你自己的文档，不用逐篇加协作者。",
+                ...(status.hint ? { hint: status.hint } : {}),
+            };
+        }
+        return {
+            ...common,
+            userReady: true,
+            botReady: status.botReady,
+            connected: true,
+            identity: status.identity ?? "user",
+            step: 3,
+            message: "已连接：Agent 会以你的身份读写飞书云文档。",
+        };
+    }
+    /**
+     * CHECKS THE CONNECTION, and says whether it actually works.
+     *
+     * The status already verifies; this is the same answer shaped for a button, so that a person can
+     * ask "it still doesn't work, why?" and get the CLI's own verdict rather than a guess.
+     */
+    async verify() {
+        const status = await this.status();
+        if (status.connected) {
+            return {
+                ok: true,
+                message: status.message,
+                ...(status.detail ? { detail: status.detail } : {}),
+            };
+        }
+        return {
+            ok: false,
+            message: status.message,
+            ...(status.detail ? { detail: status.detail } : {}),
+            ...(status.hint ? { hint: status.hint } : {}),
+        };
+    }
+    /**
+     * STARTS THE CONNECT FLOW.
+     *
+     * Two steps, and which one runs is decided by what the CLI already has:
+     *
+     * - No application, or one whose credential no longer works: `config init --new` registers a
+     *   fresh application through a browser confirmation. It BLOCKS until the person confirms, so it
+     *   runs in the background and the URL is taken from its output. The broken case goes here too,
+     *   because a new application is the one repair that needs no secret to be typed into a form.
+     * - A working application but no person: `auth login --no-wait --json` asks for a device code
+     *   and hands back the URL to open. The code is kept here until the person says they are done.
+     */
+    async connect() {
+        const status = await this.status();
+        if (!status.installed) {
+            return { ok: false, message: status.message };
+        }
+        // Step 2 is "connect the account"; the application part of it is missing or broken when the
+        // person has no application OR when the one they have was refused by Feishu.
+        if (!status.appId || status.rebuild) {
+            const verificationUri = await this.cli.startAppCreation();
+            this.pendingAppCreation = true;
+            return {
+                ok: true,
+                step: "app",
+                ...(verificationUri ? { verificationUri } : {}),
+                message: verificationUri
+                    ? "在浏览器里打开这个链接确认一下，应用就建好了（CLI 会把应用和凭据存进系统钥匙串）。确认完点「我已完成」。"
+                    : "CLI 没有打印出链接。请在终端里运行 lark-cli config init --new，按提示扫码确认，然后回到这里点「连接飞书账号」。",
+            };
+        }
+        try {
+            const login = await this.cli.beginLogin();
+            this.pendingDeviceCode = login.deviceCode;
+            return {
+                ok: true,
+                step: "login",
+                ...(login.verificationUri ? { verificationUri: login.verificationUri } : {}),
+                deviceCode: login.deviceCode,
+                message: login.verificationUri
+                    ? "在浏览器里打开这个链接，用你的飞书账号确认授权，然后点「我已完成」。"
+                    : "CLI 已经发起设备码授权。请在浏览器里确认，然后点「我已完成」。",
+            };
+        }
+        catch (error) {
+            return { ok: false, message: messageOf(error), ...(hintOf(error) ? { hint: hintOf(error) } : {}) };
+        }
+    }
+    /**
+     * FINISHES THE FLOW, once the person says they are done.
+     *
+     * TWO KINDS OF "DONE", and the difference is what the CLI is waiting for:
+     *
+     * - An application is being registered: `config init --new` finishes by itself once the person
+     *   confirms in the browser, so there is nothing to hand back. The status is re-read and the
+     *   answer is whether the application showed up.
+     * - A login is being authorized: the device code is handed back to the CLI, which completes the
+     *   exchange and stores the token in the keychain. Super Pi never sees the token itself.
+     */
+    async completeConnect() {
+        if (this.pendingAppCreation) {
+            this.pendingAppCreation = false;
+            const status = await this.status();
+            if (status.appId) {
+                return {
+                    ok: true,
+                    message: "应用建好了。接下来点「连接飞书账号」授权你的账号，Agent 就能以你的身份读写文档了。",
+                };
+            }
+            return {
+                ok: false,
+                message: "还没看到应用建好。请确认浏览器里的确认已经提交（有时要等 CLI 写完钥匙串），然后再点一次「我已完成」。",
+            };
+        }
+        if (!this.pendingDeviceCode) {
+            return { ok: false, message: "没有待完成的登录。点「连接飞书账号」重新开始。" };
+        }
+        const deviceCode = this.pendingDeviceCode;
+        this.pendingDeviceCode = undefined;
+        try {
+            const envelope = await this.cli.completeLogin(deviceCode);
+            if (envelope.ok === false) {
+                return { ok: false, message: errorMessage(envelope), ...(errorHint(envelope) ? { hint: errorHint(envelope) } : {}) };
+            }
+            return { ok: true, message: "已连接。现在 Agent 能以你的身份读写飞书云文档了。" };
+        }
+        catch (error) {
+            return { ok: false, message: messageOf(error), ...(hintOf(error) ? { hint: hintOf(error) } : {}) };
+        }
+    }
+    /**
+     * READS A DOCUMENT.
+     *
+     * The CLI resolves a knowledge-base link itself, so a `/wiki/` URL is passed through untouched -
+     * and it answers with Markdown, which is the shape a model wants.
+     */
+    async read(input) {
+        const document = await this.cli.fetchDocument(input.url);
+        return {
+            ...(document.documentId ? { documentId: document.documentId } : {}),
+            ...(document.revisionId !== undefined ? { revisionId: document.revisionId } : {}),
+            ...(document.title ? { title: document.title } : {}),
+            url: input.url,
+            format: "markdown",
+            content: document.content,
+        };
+    }
+    /**
+     * WRITES A DOCUMENT.
+     *
+     * THREE MODES, and the difference between them is who decides what survives:
+     *
+     * - `create` makes a new document. Nothing can be lost, because nothing was there.
+     * - `append` adds to the end. Nothing can be lost either.
+     * - `replace` replaces the whole document. This one CAN lose a person's work, so it needs the
+     *   revision the caller read - the same rule the file panel's write lives by, and for the same
+     *   reason: an agent told to "把这份报告改成正式版" would otherwise destroy a hand edit made an
+     *   hour ago, with no refusal and no warning.
+     *
+     * THE REVISION IS THE ETAG. The CLI passes it as the base revision of the edit, and Feishu
+     * refuses the edit when the document has moved on - so the check is enforced by the API rather
+     * than by a comparison Super Pi makes and then has to keep honest.
+     */
+    async write(input) {
+        const mode = input.mode ?? (input.url ? "append" : "create");
+        const content = String(input.content ?? "");
+        if (!content.trim())
+            throw new Error("要写入的内容是空的。");
+        if (mode === "create") {
+            const title = input.title?.trim() || titleFromMarkdown(content);
+            const created = await this.cli.createDocument(title, content);
+            return {
+                ...(created.documentId ? { documentId: created.documentId } : {}),
+                ...(created.revisionId !== undefined ? { revisionId: created.revisionId } : {}),
+                ...(created.url ? { url: created.url } : {}),
+                mode,
+            };
+        }
+        if (!input.url)
+            throw new Error("追加或覆盖需要给出文档链接或 token。");
+        if (mode === "replace") {
+            if (!input.baseRevisionId) {
+                throw new Error("覆盖前需要确认文档版本：先用 feishu_doc_read 读一次这篇文档，把它返回的 revisionId 作为 baseRevisionId 传入。覆盖会清空整篇文档，必须先看过。");
+            }
+            const revision = Number(input.baseRevisionId);
+            if (!Number.isFinite(revision)) {
+                throw new Error(`baseRevisionId 不是有效的版本号：${input.baseRevisionId}`);
+            }
+            const updated = await this.cli.updateDocument(input.url, "overwrite", content, revision);
+            return {
+                ...(updated.revisionId !== undefined ? { revisionId: updated.revisionId } : {}),
+                url: input.url,
+                mode,
+            };
+        }
+        const updated = await this.cli.updateDocument(input.url, "append", content);
+        return {
+            ...(updated.revisionId !== undefined ? { revisionId: updated.revisionId } : {}),
+            url: input.url,
+            mode,
+        };
+    }
+    /**
+     * THE TOOL CALL, as the extension sends it.
+     */
+    async tool(body) {
+        const request = (body ?? {});
+        const action = String(request.action ?? "read");
+        if (action === "read") {
+            return this.read({ url: String(request.url ?? "") });
+        }
+        if (action === "write") {
+            const mode = request.mode === "create" || request.mode === "append" || request.mode === "replace" ? request.mode : undefined;
+            return this.write({
+                ...(request.url ? { url: String(request.url) } : {}),
+                content: String(request.content ?? ""),
+                ...(mode ? { mode } : {}),
+                ...(request.title ? { title: String(request.title) } : {}),
+                ...(request.baseRevisionId ? { baseRevisionId: String(request.baseRevisionId) } : {}),
+            });
+        }
+        throw new Error(`未知的飞书工具操作：${action}`);
+    }
+}
+/**
+ * A SENTENCE WITHOUT ITS OWN FULL STOP.
+ *
+ * The CLI writes English sentences that end in a period, and this service writes Chinese ones that
+ * end in 。 — so a message pasted in verbatim reads "invalid.。点「重新连接」".
+ */
+function trimSentence(text) {
+    return text.trim().replace(/[.\s]+$/, "");
+}
+/** The message of a failure, whatever shape the failure has. */ function messageOf(error) {
+    if (error instanceof FeishuCliError)
+        return error.message;
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+/** The hint of a failure, when it carries one. */
+function hintOf(error) {
+    return error instanceof FeishuCliError ? error.hint : undefined;
+}
+/**
+ * A TITLE FROM THE CONTENT, for a document created without one.
+ *
+ * The first heading is what a person would have called it, and a generated title is better than
+ * "未命名文档" only when there is something to take.
+ */
+function titleFromMarkdown(content) {
+    for (const line of content.split("\n")) {
+        const heading = /^#{1,6}\s+(.+?)\s*$/.exec(line.trim());
+        if (heading?.[1])
+            return heading[1].slice(0, 800);
+    }
+    const firstLine = content.split("\n").map((line) => line.trim()).find((line) => line.length > 0);
+    return (firstLine ? firstLine.slice(0, 800) : "未命名文档");
+}

package/dist/server/application/run-service.js

@@ -1132,9 +1132,17 @@ export class RunService {
                 // `active: true` on every delta is not a field Pi sent - it is the conclusion Super Pi draws from
                 // having received one. Pi announces the END of reasoning with `thinking_end` and puts nothing on
                 // the delta, so these two halves together are the whole lifecycle.
-                onThinking: (delta) => {
+                onThinking: async (delta) => {
                     if (!delta)
                         return;
+                    // THINKING IS THE MODEL PRODUCING SOMETHING, SO THE TURN IS RUNNING. The contract above
+                    // says a turn moves from `waiting` to `running` once the model has produced ANY signal -
+                    // "regardless of shape" - and a thinking delta is the same signal as a text delta: it is Pi
+                    // yielding data back. Only two shapes promoted the turn (text and a tool-call notice), so a
+                    // model that thinks before it answers sat in `waiting` for the whole of its reasoning: the
+                    // panel said 「等待 LLM 返回」 while the model was plainly working, and - because the stop
+                    // button appears while a turn is in flight - the reader had no way to stop it for exactly
+                    // as long as the thinking lasted.
                     const newBlock = thinkingAnswerAt !== spoken || thinkingInterrupted;
                     if (newBlock) {
                         thinkingBlock++;
@@ -1145,6 +1153,12 @@ export class RunService {
                     this.store.setThinkingActiveLive(conversation.id, assistant.id, true);
                     thought += delta.length;
                     this.store.appendThinkingDeltaLive(conversation.id, assistant.id, delta, spoken, newBlock);
+                    // THE PROMOTION COMES AFTER THE DELTA IS IN THE STORE, so the state snapshot it broadcasts
+                    // carries the same thinking the client is about to receive as a live event. Promoting first
+                    // broadcast a snapshot WITHOUT this delta, and the client - which prefers the live body only
+                    // while the conversation is running - took that stale snapshot, lost the thinking block's
+                    // boundary, and dropped a tool call out of the block it belonged to.
+                    await promoteToRunning();
                     this.broadcaster.broadcast({ type: "message.thinking", conversationId: conversation.id, messageId: assistant.id, delta, active: true, at: spoken, blockIndex: thinkingBlock });
                     scheduleCheckpoint();
                 },