@evandu/super-pi 0.1.88 → 0.1.89

package/dist/client/.super-pi-client-sources.json

@@ -24,5 +24,5 @@
     "src/client/types.ts": "d84b66d06691e450fbf53c76881344d718a4c34ccfb972d6d98d0576a4279f4f",
     "src/client/vite-env.d.ts": "65996936fbb042915f7b74a200fcdde7e410f32a669b1ab9597cfaa4b0faddb5"
   },
-  "recordedAt": "2026-10-19T06:13:57.734Z"
+  "recordedAt": "2026-10-19T08:04:40.664Z"
 }

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

@@ -7,6 +7,66 @@ import { validateWorkflowPlan, workflowSummary } from "../workflow.js";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
+/**
+ * Translates a thrown error from the turn loop into a sentence a person reads.
+ *
+ * The turn loop throws for very different reasons: a model-provider rate limit, a 5xx that Pi's RPC
+ * layer chose to surface as a child exit, an OOM that took the whole process down, a path that
+ * resolved to a directory the workspace contract forbids, an `imageInput: false` mismatch. The
+ * throw message carries the technical fact; what the reader needs is the action it implies - retry,
+ * change model, check the key, change workspace - and that is the level this function writes at.
+ *
+ * The reason the shape is match-on-substring rather than match-on-error-class is that the upstream
+ * error is whatever Pi wrote to its own log: a string, not an exception class, and the host has
+ * nothing to pattern-match against other than the message itself. The literals below are
+ * deliberately permissive on the LLM side ("quota", "rate limit", "usage limit", "too many requests",
+ * "5-hour", "5h") because the underlying model APIs name this limit in several ways, and the
+ * reader cares about the bucket, not the exact wording.
+ */
+function formatTurnFailure(error) {
+    if (controllerAborted(error))
+        return "本轮任务已停止。";
+    const raw = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+    const lower = raw.toLowerCase();
+    // PROVIDER QUOTA / RATE LIMIT - the only reason the user is in this branch is because Pi was
+    // answering them a moment ago and now the model will not let it. The action is "wait or change
+    // model"; the wording has to make that obvious from the banner alone, without a tooltip.
+    if (/quota|rate limit|usage limit|too many requests|5-hour|5h|resource_exhausted|resourc exhaust|hit your limit|usage cap|usage restrict/.test(lower)) {
+        return "模型额度已用完（5 小时限额或类似上限），Pi 已停止回答。可以等待重置后重试，或在会话里换一个模型再发。";
+    }
+    // RPC CHANNEL DEAD - Pi died without producing a `settled` event. Anything in the turn is now
+    // unanswerable, but the deltas the user already saw are still on screen, so the message has to
+    // say "we noticed and stopped" rather than "your input was lost".
+    if (lower.includes("pi rpc channel closed") || lower.includes("agent rpc") || lower.includes("exited before settling")) {
+        return "Pi 进程异常退出，未完成本轮回答。已停止运行，可以直接重发任务继续。";
+    }
+    // NO PI - the launch path failed (binary missing, executable bit, Windows shim). The reader's
+    // best move is a `which pi` / reinstall, and the banner should point there.
+    if (lower.includes("could not find") && lower.includes("pi") || lower.includes("pi command") || lower.startsWith("pi ")) {
+        return `无法启动 Pi：${raw || "未知原因"}。请确认 Pi 已正确安装并可在命令行运行。`;
+    }
+    // WORKSPACE PATH - turn refused on directory the contract forbids. Refusal happens before
+    // anything is on screen, so the banner is also the only place the reason lives.
+    if (lower.includes("workspace directory") || lower.includes("does not exist or is not a directory")) {
+        return `工作区目录无效：${raw}`;
+    }
+    // IMAGE MISMATCH - explicit by the caller, no need to translate.
+    if (lower.includes("不支持图片输入")) {
+        return raw;
+    }
+    // GENERIC - the literal message is more useful than a paraphrase, but it has to be the LAST
+    // branch and the message has to be non-empty (a thrown `new Error()` is empty and renders
+    // nothing, which is exactly the silence this whole change exists to break).
+    return raw || "Pi 未能完成本轮回答，已标记为失败。可以重发任务继续。";
+}
+function controllerAborted(error) {
+    if (!error)
+        return false;
+    if (error instanceof Error && error.name === "AbortError")
+        return true;
+    const msg = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+    return /abort|cancel|aborted/i.test(msg);
+}
 /** Expands composer references into explicit context for the model. */
 async function expandAtReferences(store, workspace, content) {
     const refs = [...content.matchAll(/@(worktree|session):([^\s]+)/gi)];
@@ -893,13 +953,61 @@ export class RunService {
                 // first line, so it is outside this try for exactly that reason. A failure from in there is a turn
                 // that has already consumed these words, and putting them back would send them twice.
                 await this.store.markMessageWaiting(conversationId, message.id).catch(() => undefined);
+                // The reason for the refusal is also worth showing - a banner above the transcript is the only
+                // place the user can read it from, because the message itself was rolled back to the queue and
+                // the banner is the difference between "the message is waiting" and "I know why it is
+                // 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));
+                // 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
+                // that ran and broke - the opposite of what actually happened.
+                await this.store.setStatus(conversationId, "idle");
+                // Tag the error so the outer catch knows to stay out of the way: no status flip, no second
+                // setFailureReason (the one above is the only one the reader should see). A free-standing
+                // property on the Error object is enough - it is checked with `in`, not by class, and the
+                // throw immediately below carries it through the propagation.
+                error.__superPiPreflight = true;
+                this.broadcaster.broadcastState();
                 throw error;
             }
             await this.runConversationTurns(conversation, workspace, expanded, controller, message.id, validImages);
             await this.store.setStatus(conversation.id, controller.signal.aborted ? "stopped" : "completed");
         }
         catch (error) {
+            // A failing turn needs to be READ AS A FAILING TURN, not just stamped "failed" in a corner no one
+            // watches. The status flip is necessary but not sufficient: a turn that was answering the user a
+            // moment ago, now reporting 「failed」 with no reason, looks identical to a turn that the user
+            // stopped themselves, and the reader has no way to tell which one it is. The only honest move
+            // is to put the reason in front of them - `Conversation.error` is the banner above the
+            // transcript that the failure state was never reaching.
+            //
+            // The reason is taken from the error itself, with the most common upstream cases translated to
+            // the wording a person reads. The literal `error.message` would say "Pi RPC channel closed
+            // before producing a record (code 3)" - that is true and useless. The translate here is what
+            // the model-provider documentation actually says and what the reader can act on (retry, change
+            // model, check the key), and it matches the banner the reader sees elsewhere in the app.
+            //
+            // NOT EVERY CATCH PATH IS A FAILURE the reader should see. A stop signalled through the
+            // controller reaches the catch too (the abort propagates as a throw), and a stop is not a
+            // failure - it is what the user asked for, and painting it red would be both wrong and a
+            // regression from the pre-change behavior of these very lines. The reason is recorded only
+            // when the controller was NOT aborted.
+            //
+            // Preflight refusals - bad model choice, unresolvable `@`-reference - carry the same shape but
+            // never opened a turn, so flipping status to `failed` would be a lie: the previous state was
+            // `idle` (or whatever the conversation was before the send) and that is what the conversation
+            // is now. The preflight branch above already wrote the reason and set status back to `idle`,
+            // so this catch only has to stay out of the way. The marker is set on the error there and
+            // checked here.
+            if (error?.__superPiPreflight) {
+                throw error;
+            }
             await this.store.setStatus(conversation.id, "failed");
+            if (!controller.signal.aborted) {
+                await this.store.setFailureReason(conversation.id, formatTurnFailure(error));
+            }
             throw error;
         }
         finally {

package/dist/server/rpc-channel.d.ts

@@ -96,7 +96,20 @@ export declare class RpcChannel {
     write(command: object): void;
     /** Returns a response to its waiter after the drain loop encountered it. */
     stash(record: RpcRecord): void;
-    /** Removes and returns the next record, or undefined after `timeoutMs` with nothing to read. */
+    /**
+     * Removes and returns the next record, or returns `undefined` after `timeoutMs` with nothing to read.
+     *
+     * THROWS once the child is gone, rather than returning undefined. The old contract was "undefined on
+     * EOF" and it had a specific shape of failure it could not see: Pi dying without ever emitting
+     * `agent_settled` (a 4xx/5xx from the model provider is the obvious one, an OOM kill another) used
+     * to look exactly like "Pi had nothing to say", so the host's drain loop kept polling until the
+     * generator returned and the turn was reported as completed - a quota-exhausted turn presented to
+     * the reader as 「已完成」 with no error and no message, which is the exact silence this threw exit
+     * exists to break. The thrown `Error` carries the exit reason and a `code: "CHANNEL_CLOSED"`
+     * property the runtime layer can pattern-match on when it wants to decide between "this turn
+     * failed before settling" and any other drain-loop failure; a host that does not match it still
+     * sees a real error with a real reason.
+     */
     next(timeoutMs?: number): Promise<RpcRecord | undefined>;
     /** Sends a command and waits for its response. For one command; use write()+waitFor() to overlap several. */
     request(command: {

package/dist/server/rpc-channel.js

@@ -74,13 +74,31 @@ export class RpcChannel {
             this.wake();
         }
     }
-    /** Removes and returns the next record, or undefined after `timeoutMs` with nothing to read. */
+    /**
+     * Removes and returns the next record, or returns `undefined` after `timeoutMs` with nothing to read.
+     *
+     * THROWS once the child is gone, rather than returning undefined. The old contract was "undefined on
+     * EOF" and it had a specific shape of failure it could not see: Pi dying without ever emitting
+     * `agent_settled` (a 4xx/5xx from the model provider is the obvious one, an OOM kill another) used
+     * to look exactly like "Pi had nothing to say", so the host's drain loop kept polling until the
+     * generator returned and the turn was reported as completed - a quota-exhausted turn presented to
+     * the reader as 「已完成」 with no error and no message, which is the exact silence this threw exit
+     * exists to break. The thrown `Error` carries the exit reason and a `code: "CHANNEL_CLOSED"`
+     * property the runtime layer can pattern-match on when it wants to decide between "this turn
+     * failed before settling" and any other drain-loop failure; a host that does not match it still
+     * sees a real error with a real reason.
+     */
     async next(timeoutMs = 100) {
         const deadline = performance.now() + timeoutMs;
         for (;;) {
             if (this.records.length)
                 return this.records.shift();
-            if (this.exited || this.child.exitCode !== null || performance.now() >= deadline)
+            if (this.exited || this.child.exitCode !== null) {
+                const err = new Error(`Pi RPC channel closed before producing a record (${this.exitReason || "no reason recorded"}). ${this.stderr.trim()}`);
+                err.code = "CHANNEL_CLOSED";
+                throw err;
+            }
+            if (performance.now() >= deadline)
                 return undefined;
             await this.changed(deadline - performance.now());
         }

package/dist/server/store.d.ts

@@ -365,6 +365,22 @@ export declare class Store {
      */
     clearPreparingToolCalls(conversationId: string, messageId: string, rows: readonly number[]): Promise<ToolCallBlock[]>;
     setStatus(conversationId: string, status: Conversation["status"]): Promise<void>;
+    /**
+     * Records WHY a turn failed in a way the reader can see. `Conversation.error` is rendered as a red
+     * banner above the transcript (`App.tsx:conversation-error`), and it is the only field that survives
+     * a status flip and a navigation away and back - so it is the only place a "Pi died without saying
+     * anything" failure becomes visible to a person.
+     *
+     * Settled through `persistMetadata` rather than `persistState` so the message and tool deltas the
+     * turn had already written are not re-validated against a partial read; a previous build took the
+     * heavier path and an early failure mid-turn left the transcript rolled back to the last good
+     * checkpoint, hiding exactly the deltas the reader would have wanted to see.
+     *
+     * Set to `undefined` to clear, which the next `addUserMessage` does anyway - so callers only need
+     * this when they want the banner without a follow-up message (the turn did fail and the user is
+     * going to act on it without sending another prompt first).
+     */
+    setFailureReason(conversationId: string, reason: string | undefined): Promise<void>;
     /** The plan a revert would carry out, without carrying it out. The server reads this to stop children first. */
     planRevert(conversationId: string, messageId: string, withdraw?: boolean): RevertPlan;
     /**

package/dist/server/store.js

@@ -1252,6 +1252,30 @@ export class Store {
         return structuredClone(calls);
     }
     async setStatus(conversationId, status) { const conversation = this.requireConversation(conversationId); conversation.status = status; conversation.updatedAt = now(); await this.persistMetadata(conversationId); }
+    /**
+     * Records WHY a turn failed in a way the reader can see. `Conversation.error` is rendered as a red
+     * banner above the transcript (`App.tsx:conversation-error`), and it is the only field that survives
+     * a status flip and a navigation away and back - so it is the only place a "Pi died without saying
+     * anything" failure becomes visible to a person.
+     *
+     * Settled through `persistMetadata` rather than `persistState` so the message and tool deltas the
+     * turn had already written are not re-validated against a partial read; a previous build took the
+     * heavier path and an early failure mid-turn left the transcript rolled back to the last good
+     * checkpoint, hiding exactly the deltas the reader would have wanted to see.
+     *
+     * Set to `undefined` to clear, which the next `addUserMessage` does anyway - so callers only need
+     * this when they want the banner without a follow-up message (the turn did fail and the user is
+     * going to act on it without sending another prompt first).
+     */
+    async setFailureReason(conversationId, reason) {
+        const conversation = this.requireConversation(conversationId);
+        if (reason === undefined)
+            delete conversation.error;
+        else
+            conversation.error = reason;
+        conversation.updatedAt = now();
+        await this.persistMetadata(conversationId);
+    }
     /** The plan a revert would carry out, without carrying it out. The server reads this to stop children first. */
     planRevert(conversationId, messageId, withdraw = false) { return planRevert(this.state, conversationId, messageId, withdraw); }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evandu/super-pi",
-  "version": "0.1.88",
+  "version": "0.1.89",
   "description": "Web control plane and companion for Pi",
   "license": "MIT",
   "type": "module",