@evandu/super-pi 0.1.132 → 0.1.135

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

@@ -6,6 +6,7 @@ import { verifyCapability } from "../capability.js";
 import { validateWorkflowPlan, workflowSummary } from "../workflow.js";
 import { ensureNameIndex } from "../file-name-index.js";
 import { formatTurnFailure } from "../turn-failure.js";
+import { describeThrownWithStack } from "../failure-text.js";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
@@ -84,6 +85,7 @@ export class RunService {
     extensionUiService;
     agentsDir;
     workflows;
+    questionWaiters = new Map();
     memory;
     setMemory(memory) { this.memory = memory; }
     /**
@@ -238,52 +240,32 @@ export class RunService {
                     this.broadcaster.broadcastState();
                     return row;
                 });
-                // AUTO-TRIGGER WHEN IDLE. The conversation may already be busy (running turn, taking the next
-                // waiting message in its own follow-up loop); if so, the existing loop picks this one up and
-                // this branch is a no-op. If idle, kick off a fresh turn so the model processes the result
-                // without the user having to send anything - the failure case is intentionally included: the
-                // model seeing "[后台任务 X 失败]" is part of the same "after current AI finishes, automatically
-                // processes the result" contract, and the auto-triggered turn goes through the same
-                // `composePrompt` path the success case does (so a helper failure surfaces as `state="error"`
-                // prose the agent can react to).
-                // EXACTLY ONE DELIVERY PER RESULT. The custom channel hands the result straight to Pi's own
-                // follow-up queue, but it knows nothing about the `waiting` row queued above, and
-                // `takeNextWaitingMessage` knows nothing about Pi's queue - so delivering through the channel
-                // while leaving the row waiting gave the model the SAME result twice (once as the custom
-                // message, once as the row's own prose turn). Measured by
-                // scripts/background-result-delivery.test.mjs. So a successful custom delivery CONSUMES the row,
-                // and a failed one - `SteerUnavailableError`, which is what oneshot mode and a not-yet-created
-                // session throw - falls back to the queue path, the same semantics the sub-agent result path
-                // (processWaitingMessage only) has always had.
-                let deliveredViaCustom = false;
-                const custom = this.runtime.sendCustomMessage;
-                if (custom) {
-                    try {
-                        await custom.call(this.runtime, task.conversationId, {
-                            customType: "super-pi-task-result",
-                            content: body,
-                            display: "后台任务结果",
-                            details: { taskId: sessionId, source: "exec", state: exitCode === 0 ? "completed" : "error", summary: task.title },
-                        });
-                        deliveredViaCustom = true;
-                    }
-                    catch (error) {
-                        console.warn(`Super Pi: custom delivery of the exec result failed, the queue path takes over: ${error instanceof Error ? error.message : "unknown error"}`);
-                    }
-                }
-                if (deliveredViaCustom) {
-                    await this.store.takeWaitingMessage(task.conversationId, queued.id);
-                }
-                else if (!this.activeRuns.has(task.conversationId) && !this.interruptTargets.has(task.conversationId)) {
+                // THE RESULT WAITS IN SUPER PI'S OWN QUEUE, AND THE QUEUE IS DRAINED ONE TURN AT A TIME.
+                //
+                // It used to go to Pi's own follow-up queue, and Pi DRAINS that queue all at once when a turn
+                // ends - the pending messages are collected into one array and fed to the model as a single
+                // turn. So two background results that finished close together were handed over TOGETHER, and
+                // the agent answered both at once (ledger TEST-033). That path also had a second defect of its
+                // own: Pi's queue knows nothing about the `waiting` row queued above, so delivering through it
+                // while leaving the row waiting gave the model the SAME result twice (ledger TEST-011).
+                //
+                // So the result is not delivered through that channel at all. It stays a `waiting` row, and
+                // Super Pi's own loop takes waiting messages ONE PER TURN - which is what that loop was built
+                // for, and what the sub-agent result path has always done.
+                //
+                // IDLE: a turn of its own starts now, so the model processes the result without the user
+                // having to send anything. The failure case is included on purpose: the model seeing
+                // "[后台任务 X 失败]" is part of the same "after the current answer finishes, the result is
+                // processed automatically" contract, and the auto-triggered turn goes through the same
+                // `composePrompt` path the success case does.
+                if (!this.activeRuns.has(task.conversationId) && !this.interruptTargets.has(task.conversationId)) {
                     void this.processWaitingMessage(task.conversationId, queued.id).catch((error) => {
                         console.warn(`Super Pi: auto-trigger for background exec result failed: ${error instanceof Error ? error.message : "unknown error"}`);
                     });
                 }
-                else {
-                    // THE CONVERSATION IS BUSY, so the run that is going answers this result itself - through
-                    // Pi's own follow-up queue, so the result does not have to wait for a turn of its own.
-                    await this.submitToPiQueue(task.conversationId, queued);
-                }
+                // BUSY: the row stays in the waiting queue, and the turn that is running takes it when that
+                // turn ends - one message per turn, in the queue's own order. Nothing of a background result
+                // goes into Pi's follow-up queue any more.
             }
             catch (error) {
                 console.warn(`Super Pi: exec result could not be appended as a tool message: ${error instanceof Error ? error.message : "unknown error"}`);
@@ -374,7 +356,7 @@ export class RunService {
      * other tool update uses - and the client can only get that index from the row it is already rendering.
      */
     async answerQuestion(command) {
-        const existing = this.store.snapshot().conversations.find((item) => item.id === command.conversationId)?.messages.find((item) => item.id === command.messageId)?.toolCalls?.[command.callIndex]?.question;
+        const existing = this.store.question(command.conversationId, command.messageId, command.callIndex);
         if (!existing)
             throw new Error("这个工具调用不是一个问题");
         const calls = await this.store.updateToolCall(command.conversationId, command.messageId, command.callIndex, {
@@ -385,6 +367,30 @@ export class RunService {
             },
         });
         this.broadcaster.broadcast({ type: "message.tools", conversationId: command.conversationId, messageId: command.messageId, toolCalls: calls });
+        this.settleQuestion(command.conversationId, command.messageId, command.callIndex, calls[command.callIndex]?.question);
+    }
+    questionKey(conversationId, messageId, index) {
+        return `${conversationId}\0${messageId}\0${index}`;
+    }
+    answerPayload(current) {
+        const answers = (current.answers ?? []).map((answer) => {
+            const asked = current.items.find((item) => item.id === answer.id);
+            return { question: asked?.question, selected: answer.selected, ...(answer.note ? { note: answer.note } : {}) };
+        });
+        return { answers, summary: `用户回答：${answers.map((answer) => answer.selected.join("、")).join("；")}` };
+    }
+    settleQuestion(conversationId, messageId, index, question) {
+        if (!question || question.status === "pending")
+            return;
+        const key = this.questionKey(conversationId, messageId, index);
+        const waiter = this.questionWaiters.get(key);
+        if (!waiter)
+            return;
+        this.questionWaiters.delete(key);
+        if (question.status === "answered")
+            waiter.resolve(this.answerPayload(question));
+        else
+            waiter.reject(new Error("用户没有回答这个问题"));
     }
     /**
      * THE `question` TOOL BLOCKS HERE, ON THE CALL THAT ASKED IT.
@@ -414,28 +420,13 @@ export class RunService {
         //
         // So the lookup WAITS. A few hundred milliseconds of polling covers the drain, and a question that
         // genuinely has no pending call still fails - just not instantly.
-        const findCall = () => {
-            const conversation = this.store.snapshot().conversations.find((item) => item.id === conversationId);
-            const message = conversation?.messages.slice().reverse().find((item) => item.role === "assistant");
-            if (!message)
-                return undefined;
-            for (let i = (message.toolCalls?.length ?? 0) - 1; i >= 0; i -= 1) {
-                const call = message.toolCalls?.[i];
-                if (call?.label === "question" && call.question?.status === "pending")
-                    return { messageId: message.id, index: i };
-            }
-            return undefined;
-        };
         let found;
         for (let attempt = 0; attempt < 50 && !found; attempt += 1) {
-            found = findCall();
+            found = this.store.pendingQuestion(conversationId);
             if (found)
                 break;
             await new Promise((resolve) => setTimeout(resolve, 100));
         }
-        const conversation = this.store.snapshot().conversations.find((item) => item.id === conversationId);
-        if (!conversation?.messages.length)
-            throw new Error("No active assistant message");
         if (!found)
             throw new Error("这个会话里没有正在等待回答的 question 工具调用");
         const { messageId, index } = found;
@@ -445,29 +436,7 @@ export class RunService {
             // continuing from a question that was never decided). The run-level teardown (stop / abort /
             // shutdown) clears the underlying ask and the client settles it as cancelled, which lands here
             // and rejects. A question that is simply unanswered waits indefinitely.
-            const poll = setInterval(() => {
-                const current = this.store.snapshot().conversations.find((item) => item.id === conversationId)?.messages.find((item) => item.id === messageId)?.toolCalls?.[index]?.question;
-                if (current?.status === "answered") {
-                    clearInterval(poll);
-                    resolve(answerPayload(current));
-                }
-                else if (current?.status === "cancelled") {
-                    clearInterval(poll);
-                    reject(new Error("用户没有回答这个问题"));
-                }
-            }, 250);
-            // WHAT GOES BACK TO THE MODEL IS WRITTEN FOR THE MODEL. The answers pair to their questions by id,
-            // which is what stops a person answering the second of two being recorded against the first - but an
-            // id is a UUID, and a model handed `{answers:[{id:"671b0f0b-…", selected:["发"]}]}` has to guess at
-            // what that means. It guessed, and reported a real answer as a cancellation. So the answer goes back
-            // as its questions and its choices, with a sentence naming the outcome.
-            const answerPayload = (current) => {
-                const answers = (current.answers ?? []).map((answer) => {
-                    const asked = current.items.find((item) => item.id === answer.id);
-                    return { question: asked?.question, selected: answer.selected, ...(answer.note ? { note: answer.note } : {}) };
-                });
-                return { answers, summary: `用户回答：${answers.map((answer) => answer.selected.join("、")).join("；")}` };
-            };
+            this.questionWaiters.set(this.questionKey(conversationId, messageId, index), { resolve, reject });
         });
     }
     /**
@@ -571,6 +540,7 @@ export class RunService {
         // Abort immediately before waiting for the conversation lane; otherwise a stop queued behind a
         // long streaming command could never reach the controller that it is meant to cancel.
         this.activeRuns.get(conversationId)?.abort();
+        this.broadcaster.broadcast({ type: "run.stopping", conversationId });
         await this.runtime.stop?.(conversationId);
         return this.serializeConversation(conversationId, () => this.stopRunUnsafe(conversationId));
     }
@@ -591,9 +561,9 @@ export class RunService {
                     continue;
                 const calls = await this.store.updateToolCall(conversationId, message.id, index, { question: { items: question.items, status: "cancelled" } });
                 this.broadcaster.broadcast({ type: "message.tools", conversationId, messageId: message.id, toolCalls: calls });
+                this.settleQuestion(conversationId, message.id, index, calls[index]?.question);
             }
         }
-        await this.store.setStatus(conversationId, "stopped");
         if (this.subagents.stopConversation(conversationId)) {
             console.log(`Super Pi: stopped the sub-agent runs of conversation ${conversationId}.`);
         }
@@ -603,6 +573,17 @@ export class RunService {
         if (this.workflows.stopConversation(conversationId)) {
             console.log(`Super Pi: stopped the running orchestration plans of conversation ${conversationId}.`);
         }
+        // AWAIT RUN SLOT RELEASE BEFORE CLAIMING "STOPPED".
+        // A stop previously called setStatus("stopped") immediately, while activeRuns still held the
+        // conversation slot and the streaming lane was still draining. This produced the contradiction:
+        // the UI displayed 「已停止」 and offered 「发送」, but sending a new message hit an active
+        // run slot and was falsely placed into 「排队中」, while the previous turn might still produce text.
+        await this.awaitRunSlotReleased(conversationId, false, 3_000);
+        if (this.activeRuns.has(conversationId)) {
+            console.warn(`Super Pi: run slot for conversation ${conversationId} not released after stop deadline; force-releasing.`);
+            this.releaseRunSlot(conversationId);
+        }
+        await this.store.setStatus(conversationId, "stopped");
         this.broadcaster.broadcastState();
     }
     /**
@@ -777,14 +758,29 @@ export class RunService {
         // long tool execution. The flag is the only way to make the flip one-shot: calling `setStatus` on
         // every delta would be a per-token status write.
         let firstSignal = true;
+        /**
+         * Promotes the turn to `running`, and ANSWERS WHETHER IT PUBLISHED A STATE SNAPSHOT.
+         *
+         * The answer matters because a state snapshot and a live event are two carriers of the same
+         * information: the snapshot is the whole truth (it carries the text, the thinking and the block
+         * boundaries), and a live `message.delta` / `message.thinking` event is an increment on top of it.
+         * A caller that has ALREADY put a delta into the store must therefore not also publish it as a
+         * live event, or the browser receives it twice and counts it twice - the reasoning the reader
+         * sees is longer than the reasoning the model wrote.
+         *
+         * So the rule is: WHOEVER PUTS THE DELTA IN THE STORE OWNS THE DELIVERY. The promotion publishes
+         * a snapshot only when it actually flips the status, and the caller asks.
+         */
         const promoteToRunning = async () => {
             if (!firstSignal)
-                return;
+                return false;
             firstSignal = false;
             if (this.store.snapshot().conversations.find((item) => item.id === conversation.id)?.status === "waiting") {
                 await this.store.setStatus(conversation.id, "running");
                 this.broadcaster.broadcastState();
+                return true;
             }
+            return false;
         };
         // Live events are independent from durable checkpoints. Persisting every token made the stdout
         // reader wait for one disk transaction per token; over a remote browser connection that backlog
@@ -1132,9 +1128,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++;
@@ -1144,8 +1148,27 @@ export class RunService {
                     thinkingActive = true;
                     this.store.setThinkingActiveLive(conversation.id, assistant.id, true);
                     thought += delta.length;
+                    // THE DELTA GOES INTO THE STORE FIRST, and the promotion that follows broadcasts a state
+                    // snapshot that therefore CARRIES it - the text, the thinking and the block boundary the
+                    // browser needs to put this fragment in the right fold. That snapshot is the delta's
+                    // delivery, so the live event is not sent as well: sent twice, the browser appends the
+                    // first fragment to a copy that already has it, and the reasoning the reader sees is longer
+                    // than the reasoning the model wrote.
+                    //
+                    // THE OTHER ORDER HAD ITS OWN FAILURE, and it is why the snapshot is not simply left to
+                    // carry everything: promoting BEFORE the append publishes a snapshot WITHOUT this delta,
+                    // and the browser - which rebuilds its fold blocks from the snapshot's boundaries - then
+                    // starts a second block for the same stretch of reasoning, so one continuous train of
+                    // thought arrives as two fold bars and the tool call inside it falls out of the block it
+                    // belonged to.
+                    //
+                    // So: the snapshot carries the delta, and only the deltas the snapshot did not carry are
+                    // published live. `promoteToRunning` answers whether it published one.
                     this.store.appendThinkingDeltaLive(conversation.id, assistant.id, delta, spoken, newBlock);
-                    this.broadcaster.broadcast({ type: "message.thinking", conversationId: conversation.id, messageId: assistant.id, delta, active: true, at: spoken, blockIndex: thinkingBlock });
+                    const promoted = await promoteToRunning();
+                    if (!promoted) {
+                        this.broadcaster.broadcast({ type: "message.thinking", conversationId: conversation.id, messageId: assistant.id, delta, active: true, at: spoken, blockIndex: thinkingBlock });
+                    }
                     scheduleCheckpoint();
                 },
                 // AN EMPTY DELTA THAT ONLY CARRIES THE FLAG. `thinking_end` is a fact the browser needs and not
@@ -1310,6 +1333,12 @@ export class RunService {
         // itself as an ordinary message and now finds the slot taken - its words are on screen with nobody
         // going to answer them. Repairing that is what the guard below is for; it is not a rare path, it is
         // what two fast sends looks like from the inside.
+        // An aborted run is unwinding its slot. Wait out that brief cleanup rather than falsely
+        // treating it as an active turn and sending this message to a dying follow-up queue.
+        const active = this.activeRuns.get(conversation.id);
+        if (active?.signal.aborted) {
+            await this.awaitRunSlotReleased(conversation.id, false);
+        }
         const busy = this.activeRuns.has(conversation.id) || this.interruptTargets.has(conversation.id);
         const message = await this.store.addUserMessage(conversationId, trimmed, validImages, attachments, { clientId, ...(busy ? { delivery: "waiting" } : {}) });
         this.broadcaster.broadcastState();
@@ -1361,6 +1390,9 @@ export class RunService {
                 // waiting". The banner is cleared by the next `addUserMessage` so a stale reason cannot
                 // survive a retry into the same conversation.
                 await this.store.setFailureReason(conversationId, formatTurnFailure(error));
+                // The refusal is written for the reader, but the reader is not the only one who needs to know
+                // why a turn never started: the server log is where the stack survives.
+                console.warn("Super Pi turn refused before it started:", describeThrownWithStack(error));
                 // Status is restored here, not relied on the outer catch to handle: a preflight failure never
                 // opened a turn, so the right state is the one the conversation had a moment ago (idle). The
                 // outer catch would otherwise flip it to `failed`, which the reader would render as a turn
@@ -1410,6 +1442,9 @@ export class RunService {
             if (controller.signal.aborted)
                 return;
             await this.store.setFailureReason(conversation.id, formatTurnFailure(error));
+            // A turn that broke is the failure the reader will complain about, and the banner only carries
+            // the sentence. The stack goes to the server log, where it can still be found.
+            console.error("Super Pi turn failed:", describeThrownWithStack(error));
             throw error;
         }
         finally {
@@ -1446,8 +1481,8 @@ export class RunService {
      * and nothing more. Waiting out an arbitrarily long RUNNING turn would turn "send now" into "send
      * whenever the current answer finishes", which is what the queue is for.
      */
-    async awaitRunSlotReleased(conversationId, onlyWhileStopped = false) {
-        const deadline = Date.now() + 15_000;
+    async awaitRunSlotReleased(conversationId, onlyWhileStopped = false, timeoutMs = 15_000) {
+        const deadline = Date.now() + timeoutMs;
         while (this.activeRuns.has(conversationId) && Date.now() < deadline) {
             if (onlyWhileStopped && this.store.snapshot().conversations.find((item) => item.id === conversationId)?.status !== "stopped")
                 return;

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

@@ -22,9 +22,8 @@ export declare class WorkspaceService {
     private readonly catalogService;
     private readonly runService;
     private readonly extensionUiService;
-    private readonly uploadsDir;
     private agentsDir;
-    constructor(store: Store, runtime: AgentRuntime, broadcaster: EventBroadcaster, catalogService: CatalogService, runService: RunService, extensionUiService: ExtensionUiService, uploadsDir: string, agentsDir: string | string[]);
+    constructor(store: Store, runtime: AgentRuntime, broadcaster: EventBroadcaster, catalogService: CatalogService, runService: RunService, extensionUiService: ExtensionUiService, agentsDir: string | string[]);
     setAgentsDir(dir: string | string[]): void;
     /**
      * Creates a new workspace.
@@ -35,8 +34,13 @@ export declare class WorkspaceService {
      */
     renameWorkspace(workspaceId: string, name: string): Promise<void>;
     /**
-     * Deletes a workspace and cascades cleanup to active runs, subagent runs,
-     * uploaded files, and stored conversations.
+     * Takes a workspace out of the sidebar. NOTHING IS DELETED.
+     *
+     * The conversations under it, the uploads attached to them and the workspace's own defaults all
+     * stay on disk: removing a workspace from the list is a soft unmount, and adding the same
+     * folder back brings the whole history with it. What does stop is the WORK: a turn that was still
+     * running cannot keep a model session alive behind a workspace the user can no longer see, and a
+     * pending question would wait for an answer the sidebar can no longer reach.
      */
     deleteWorkspace(workspaceId: string): Promise<void>;
     /**

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

@@ -1,5 +1,4 @@
 import { assertModelAllowed } from "../model-filter.js";
-import { deleteConversationUploads } from "../upload.js";
 /**
  * Service managing workspaces: creation, rename, cascade deletion, and defaults configuration.
  */
@@ -10,16 +9,14 @@ export class WorkspaceService {
     catalogService;
     runService;
     extensionUiService;
-    uploadsDir;
     agentsDir;
-    constructor(store, runtime, broadcaster, catalogService, runService, extensionUiService, uploadsDir, agentsDir) {
+    constructor(store, runtime, broadcaster, catalogService, runService, extensionUiService, agentsDir) {
         this.store = store;
         this.runtime = runtime;
         this.broadcaster = broadcaster;
         this.catalogService = catalogService;
         this.runService = runService;
         this.extensionUiService = extensionUiService;
-        this.uploadsDir = uploadsDir;
         this.agentsDir = agentsDir;
     }
     setAgentsDir(dir) {
@@ -41,21 +38,25 @@ export class WorkspaceService {
         this.broadcaster.broadcastState();
     }
     /**
-     * Deletes a workspace and cascades cleanup to active runs, subagent runs,
-     * uploaded files, and stored conversations.
+     * Takes a workspace out of the sidebar. NOTHING IS DELETED.
+     *
+     * The conversations under it, the uploads attached to them and the workspace's own defaults all
+     * stay on disk: removing a workspace from the list is a soft unmount, and adding the same
+     * folder back brings the whole history with it. What does stop is the WORK: a turn that was still
+     * running cannot keep a model session alive behind a workspace the user can no longer see, and a
+     * pending question would wait for an answer the sidebar can no longer reach.
      */
     async deleteWorkspace(workspaceId) {
         const snapshot = this.store.snapshot();
-        const doomed = snapshot.conversations.filter((c) => c.workspaceId === workspaceId);
-        for (const c of doomed) {
+        const affected = snapshot.conversations.filter((c) => c.workspaceId === workspaceId);
+        for (const c of affected) {
             this.extensionUiService.cancelPendingUi(c.id, "aborted");
             if (this.runService.isRunning(c.id)) {
                 await this.runService.stopRun(c.id);
             }
             this.runService.stopConversationSubagents(c.id);
         }
-        const doomedIds = await this.store.deleteWorkspace(workspaceId);
-        await Promise.all(doomedIds.map((id) => deleteConversationUploads(this.uploadsDir, id)));
+        await this.store.deleteWorkspace(workspaceId);
         this.broadcaster.broadcastState();
     }
     /**

package/dist/server/failure-text.d.ts

@@ -0,0 +1,18 @@
+/**
+ * THE TEXT OF A FAILURE.
+ *
+ * A server failure reaches the browser as a sentence, and the reader is entitled to know what
+ * actually went wrong. The trouble is that what was thrown is not always an `Error`: it can be a
+ * string, a plain object, a rejected promise with no reason at all. The old code answered
+ * `command failed` in those cases - the one sentence that says nothing about anything - so a real
+ * cause that had reached the server was replaced by a sentence with no cause in it.
+ *
+ * This module is the one place that decides what a thrown value turns into. It never invents
+ * text: an `Error` gives its message, a string gives itself, an object gives its `message` or its
+ * JSON, and a value that carries no information at all gives an EMPTY STRING - which the client
+ * reads as "no reason was given", and says so out loud instead of pretending.
+ */
+/** The failure as a person should read it. Empty when the thrown value carries no information. */
+export declare function describeThrown(error: unknown): string;
+/** The failure with its stack, for the log file. */
+export declare function describeThrownWithStack(error: unknown): string;

package/dist/server/failure-text.js

@@ -0,0 +1,44 @@
+/**
+ * THE TEXT OF A FAILURE.
+ *
+ * A server failure reaches the browser as a sentence, and the reader is entitled to know what
+ * actually went wrong. The trouble is that what was thrown is not always an `Error`: it can be a
+ * string, a plain object, a rejected promise with no reason at all. The old code answered
+ * `command failed` in those cases - the one sentence that says nothing about anything - so a real
+ * cause that had reached the server was replaced by a sentence with no cause in it.
+ *
+ * This module is the one place that decides what a thrown value turns into. It never invents
+ * text: an `Error` gives its message, a string gives itself, an object gives its `message` or its
+ * JSON, and a value that carries no information at all gives an EMPTY STRING - which the client
+ * reads as "no reason was given", and says so out loud instead of pretending.
+ */
+/** The failure as a person should read it. Empty when the thrown value carries no information. */
+export function describeThrown(error) {
+    if (error instanceof Error)
+        return error.message || error.name;
+    if (typeof error === "string")
+        return error;
+    if (error === null || error === undefined)
+        return "";
+    if (typeof error === "object") {
+        const message = error.message;
+        if (typeof message === "string" && message.trim())
+            return message;
+        try {
+            const text = JSON.stringify(error);
+            if (text && text !== "{}")
+                return text;
+        }
+        catch {
+            // Circular or otherwise unserializable: there is nothing better to say than "no reason".
+        }
+        return "";
+    }
+    return String(error);
+}
+/** The failure with its stack, for the log file. */
+export function describeThrownWithStack(error) {
+    if (error instanceof Error && error.stack)
+        return error.stack;
+    return describeThrown(error);
+}

package/dist/server/feishu-cli.d.ts

@@ -64,6 +64,16 @@ export type FeishuCliStatus = {
     identity?: FeishuIdentity;
     /** Feishu's own "what to do about it", when the CLI had something to say. */
     hint?: string;
+    /** The CLI's own summary of the situation, when it has one. */
+    note?: string;
+    /** The state of each identity, as the CLI words it: ready, missing, verify_failed, ... */
+    botStatus?: string;
+    userStatus?: string;
+    /** What the CLI says about each identity, in its own words. */
+    userMessage?: string;
+    botMessage?: string;
+    /** Whether the check actually reached Feishu, rather than only reading the local credential. */
+    verified?: boolean;
 };
 /** The outcome of a CLI call, in the shape this product speaks in. */
 export declare class FeishuCliError extends Error {
@@ -139,8 +149,14 @@ export declare class FeishuCli {
     /**
      * WHAT THE CLI KNOWS ABOUT ITSELF.
      *
-     * `auth status` is the one command that answers without touching the network unless asked to
-     * verify, so it is what the panel polls.
+     * THE VERIFY IS ON, and that is the whole point of asking the CLI at all. Without `--verify` the
+     * CLI only reads its local credential and reports the application as "ready" — which is what it
+     * said on a machine whose App Secret had expired, and which would have left the panel claiming
+     * everything was fine while every document call failed. With `--verify` the CLI asks Feishu, and
+     * the answer distinguishes the states a person can act on: `ready`, `missing`, `verify_failed`.
+     *
+     * When the verification cannot reach Feishu at all (no network), the plain status is read
+     * instead, and `verified: false` says so rather than pretending.
      */
     status(): Promise<FeishuCliStatus>;
     /**

package/dist/server/feishu-cli.js

@@ -198,38 +198,72 @@ export class FeishuCli {
     /**
      * WHAT THE CLI KNOWS ABOUT ITSELF.
      *
-     * `auth status` is the one command that answers without touching the network unless asked to
-     * verify, so it is what the panel polls.
+     * THE VERIFY IS ON, and that is the whole point of asking the CLI at all. Without `--verify` the
+     * CLI only reads its local credential and reports the application as "ready" — which is what it
+     * said on a machine whose App Secret had expired, and which would have left the panel claiming
+     * everything was fine while every document call failed. With `--verify` the CLI asks Feishu, and
+     * the answer distinguishes the states a person can act on: `ready`, `missing`, `verify_failed`.
+     *
+     * When the verification cannot reach Feishu at all (no network), the plain status is read
+     * instead, and `verified: false` says so rather than pretending.
      */
     async status() {
         const version = await this.version();
         if (!version)
             return { installed: false, userReady: false, botReady: false };
+        const read = async (args) => this.run(args, { timeoutMs: 30_000 });
         let envelope;
+        let verified = true;
         try {
-            envelope = await this.run(["auth", "status", "--json"], { timeoutMs: 30_000 });
+            envelope = await read(["auth", "status", "--verify", "--json"]);
+            // The CLI answers a failed verification with an error envelope. That is not the same as a
+            // credential that Feishu refused - it means the question was never answered - so the local
+            // status is read instead and the panel is told that Feishu was never asked.
+            if (envelope.ok === false) {
+                envelope = await read(["auth", "status", "--json"]);
+                verified = false;
+            }
         }
         catch (error) {
-            return {
-                installed: true,
-                version,
-                userReady: false,
-                botReady: false,
-                ...(error instanceof FeishuCliError ? { hint: error.message } : {}),
-            };
+            try {
+                envelope = await read(["auth", "status", "--json"]);
+                verified = false;
+            }
+            catch {
+                return {
+                    installed: true,
+                    version,
+                    userReady: false,
+                    botReady: false,
+                    ...(error instanceof FeishuCliError ? { hint: error.message } : {}),
+                };
+            }
         }
         const identities = pick(envelope.data ?? envelope, "identities");
         const user = identities?.user;
         const bot = identities?.bot;
         const identity = asString(envelope.identity) ?? pick(envelope.data ?? envelope, "identity");
+        const appId = asString(pick(envelope.data ?? envelope, "appId", "app_id"));
+        const note = asString(pick(envelope.data ?? envelope, "note"));
+        // THE HINT OF THE IDENTITY THAT IS FAILING. Both identities carry a hint, and the wrong one
+        // sends the person to the wrong command: the application's hint says "log in" when the real
+        // problem is that the credential was refused, and the user's hint says "check the credential"
+        // when all that is missing is a login.
+        const failing = bot?.available !== true ? bot : user;
         return {
             installed: true,
             version,
-            ...(asString(pick(envelope.data ?? envelope, "appId", "app_id")) ? { appId: asString(pick(envelope.data ?? envelope, "appId", "app_id")) } : {}),
+            ...(appId ? { appId } : {}),
             userReady: user?.available === true,
             botReady: bot?.available === true,
             ...(identity === "user" || identity === "bot" ? { identity } : {}),
-            ...(asString(user?.hint) ?? asString(bot?.hint) ? { hint: (asString(user?.hint) ?? asString(bot?.hint)) } : {}),
+            ...(asString(user?.status) ? { userStatus: asString(user?.status) } : {}),
+            ...(asString(bot?.status) ? { botStatus: asString(bot?.status) } : {}),
+            ...(asString(user?.message) ? { userMessage: asString(user?.message) } : {}),
+            ...(asString(bot?.message) ? { botMessage: asString(bot?.message) } : {}),
+            ...(asString(failing?.hint) ? { hint: asString(failing?.hint) } : {}),
+            ...(note ? { note } : {}),
+            verified,
         };
     }
     /**