@evandu/super-pi 0.1.166 → 0.1.167

package/dist/server/agents.js

@@ -1,6 +1,7 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { orderAgentsForDisplay } from "../shared/agent-order.js";
 /**
  * A guard rather than a cast: it is the only thing that lets `tools:` be checked once and then used as
  * a map everywhere without the compiler complaining. It narrows to the index-signature shape that
@@ -526,12 +527,13 @@ export async function readAgents(directory, options = {}) {
     // invoked BY an agent and never chosen by a human, so listing one in the picker would promise a role
     // the runtime cannot honour.
     //
-    // The remainder is the PACKAGE'S OWN agents first, then the user's, each group alphabetical by id.
-    //
-    // WHY THE BUILT-IN GROUP COMES FIRST. The picker used to sort purely by id, which scattered the
-    // package's own agents - the ones drawn with a colour dot - among the user's own with no visible
-    // rule to say which was which. The built-in group is now a group, so the colours read as "these are
-    // the ones that ship with Super Pi" instead of as noise.
+    // THE ORDER IS NOT DECIDED HERE. It is `orderAgentsForDisplay` - the one rule in
+    // `src/shared/agent-order.ts`, which the client applies too. The server orders the whole catalogue it
+    // read and hands out the half that was asked for, so what leaves the server is ALREADY in display
+    // order: the package's own agents first, the conversation roles before the delegated ones, and
+    // alphabetical by id inside each. Every surface that draws a server catalogue therefore inherits that
+    // order instead of guessing it, and the one place that MERGES two catalogues re-applies the same
+    // rule rather than inventing a second one.
     //
     // WHY THE GROUP ORDER DOES NOT TOUCH THE OVERRIDE RULE. The rule that decides WHICH definition of
     // an id survives was applied above, while reading: the first directory to offer an id wins, and the
@@ -539,9 +541,7 @@ export async function readAgents(directory, options = {}) {
     // already survived that decision, so a user's copy of a built-in agent still wins - and it is then
     // listed as the user's, because it IS the user's file.
     return {
-        agents: agents
-            .filter((agent) => agent.mode === mode)
-            .sort((a, b) => (a.builtin === b.builtin ? a.id.localeCompare(b.id) : a.builtin ? -1 : 1)),
+        agents: orderAgentsForDisplay(agents).filter((agent) => agent.mode === mode),
         problems,
     };
 }

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

@@ -158,7 +158,7 @@ const REPORT_EVENT_LIMIT = 200;
 // THE WORDS THE REPORT SPEAKS IN. A reader of the report is a person, not a console, so every
 // state and every role is written the way a person would say it out loud.
 const PROJECT_STATUS_TEXT = {
-    planning: "草稿", active: "进行中", blocked: "已阻塞", awaiting_approval: "等待审批",
+    planning: "草稿", awaiting_start: "待启动", active: "进行中", blocked: "已阻塞", awaiting_approval: "等待审批",
     awaiting_review: "等待复核", completed: "已完成", cancelled: "已取消", failed: "失败",
 };
 const TASK_STATUS_TEXT = {
@@ -475,10 +475,22 @@ export class ProjectService {
         const hasLeaderBlockedTask = p.tasks.some((t) => t.status === "blocked" && isLeader(t.blockedReportedByConversationId));
         const lastLeaderProjectReport = [...p.reports].reverse().find((r) => !r.taskId && isLeader(r.authorConversationId));
         const leaderProjectBlocked = lastLeaderProjectReport?.kind === "blocked";
+        /* A PROJECT THAT HAS WORK REGISTERED BUT NO LEADER SESSION YET IS NOT RUNNING.
+           "active" used to mean "there is at least one task", so a project whose tasks were only
+           REGISTERED - nobody had started it, nobody was working on it - claimed on its card to be
+           running while the panel's own team section said there were no sessions at all. The card
+           and the team list contradicted each other, and the card was the one that lied: the
+           project's own status has to say what is true about the project, not what the client
+           happens to translate it into. So the state is split:
+             planning      - nothing has been broken down yet,
+             awaiting_start - the work is registered and the project has NOT been started,
+             active        - the project is started and a leader session exists.
+           A project has a leader session only after `start`, so the leader is the signal - not the
+           task count, and not anything the client sends. */
         p.status = openBoss.some((e) => e.severity === "high") ? "awaiting_approval"
             : openBoss.length || hasLeaderBlockedTask || leaderProjectBlocked ? "blocked"
                 : p.tasks.some((t) => t.status === "awaiting_review") ? "awaiting_review"
-                    : p.tasks.length ? "active" : "planning";
+                    : p.tasks.length ? (p.ownerConversationId ? "active" : "awaiting_start") : "planning";
     }
     resources(p) {
         const state = this.store.snapshot();
@@ -502,7 +514,8 @@ export class ProjectService {
          * initiator's conversation ("shared"). The leader is the root of the project's tree, so it is
          * "project" by the same rule as everybody else - there is no special case for it. */
         const projectTreeId = p.ownerConversationId ? this.store.conversation(p.ownerConversationId)?.treeId : undefined;
-        const sessions = state.conversations.filter((c) => c.workspaceId === p.workspaceId && members.has(c.id)).map((c) => ({
+        const memberConversations = state.conversations.filter((c) => c.workspaceId === p.workspaceId && members.has(c.id));
+        const sessions = memberConversations.map((c) => ({
             id: c.id, title: c.title, status: c.status, tokens: tokens(c.usage), contextPercent: c.contextUsage?.percent,
             // THE TREE SKELETON. The client draws the agents of a project as a tree, and the only
             // thing that knows who spawned whom is the conversation's own parent link. It is sent
@@ -529,12 +542,33 @@ export class ProjectService {
            Now it is counted once - through the session - and a project's budget therefore includes what
            its one-shot calls cost, which is the whole point of a budget a person can predict.
            See `Store.accountSubagentUsage`. */
-        return { tokens: sessions.reduce((sum, s) => sum + s.tokens, 0),
+        /* THE SAME USAGE, TWICE: ONCE IN THE BILLING-EQUIVALENT UNITS THE BUDGET IS SPENT IN, AND
+           ONCE IN THE RAW 1:1 UNITS THE READER'S OWN TOOLING COUNTS IN.
+           The panel used to show only the equivalent number, and the two differ by a factor of
+           two and a half on a real run - so a reader who compared the project's cost with their
+           own dashboard saw two different numbers and no way to tell which one the panel meant.
+           So the raw components are sent as well: 输入 + 输出 + 缓存写入 + 缓存读取, which the reader
+           can add up, and can also feed into the published formula themselves.
+           The equivalent number is computed from the SUMMED components and rounded ONCE, not by
+           adding up each session's own rounded number: that way the formula printed next to the
+           number reproduces the number exactly, instead of being off by a token per session. */
+        const usage = memberConversations.reduce((acc, c) => {
+            if (!c.usage)
+                return acc;
+            acc.input += c.usage.input;
+            acc.output += c.usage.output;
+            acc.cacheRead += c.usage.cacheRead;
+            acc.cacheWrite += c.usage.cacheWrite;
+            return acc;
+        }, { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 });
+        return { tokens: tokens(usage),
             usageKnown: sessions.length > 0 && sessions.every((s) => Boolean(this.store.conversation(s.id)?.usage)) && runs.every((r) => Boolean(r.usage)),
             activeWorkers: sessions.filter((s) => (!coordinatorIds.has(s.id) || (leaderIsWorker && s.id === p.ownerConversationId)) && busy(s.status)).length + runs.filter((r) => r.status === "running").length,
             // THE PROJECT'S OWN MEMORY TREE, named once so the client does not have to infer it from
             // the sessions. Absent only when the project has no leader session yet.
-            memoryTreeId: projectTreeId, sessions };
+            memoryTreeId: projectTreeId, sessions,
+            // THE RAW 1:1 PICTURE OF THE SAME MONEY, next to the equivalent number it is spent in.
+            usage, rawTokens: usage.input + usage.output + usage.cacheRead + usage.cacheWrite };
     }
     list(workspaceId) {
         const scope = this.workspace(workspaceId);
@@ -562,6 +596,12 @@ export class ProjectService {
             const reason = blockedTask.blockedReason ? `（${blockedTask.blockedReason}）` : "";
             return `项目已阻塞：${blockedTask.title}${reason}`;
         }
+        /* THE WORK IS REGISTERED AND THE PROJECT HAS NOT BEEN STARTED. The task is "ready to
+           dispatch", but dispatching needs a leader and there is no leader until the project is
+           started - so "waiting to dispatch" would point the reader at something nobody can do.
+           The headline says what is true, in the same words the card uses. */
+        if (total > 0 && !p.ownerConversationId)
+            return `已登记 ${total} 个任务，项目待启动`;
         const inProgressTask = p.tasks.find((t) => t.status === "in_progress");
         if (inProgressTask) {
             return `${completed}/${total} 任务完成，正在执行${inProgressTask.title}`;
@@ -689,7 +729,12 @@ export class ProjectService {
         // formula is printed next to the number: a budget nobody can predict is a budget nobody trusts.
         // The sentence after the formula says what the number INCLUDES - a one-shot call (a sub-agent)
         // is part of it, so a reader who dispatches children can see what that cost them.
-        lines.push(`- 已用等效 Token：${this.resources(p).tokens}（口径：输入 + 输出 + 缓存写入×${CACHE_WRITE_WEIGHT} + 缓存读取×${CACHE_READ_WEIGHT}，取整；含项目内的一次性调用（subagent））`);
+        // THE RAW 1:1 FIGURE FOLLOWS IT, because the two differ by a factor of two and a half on a
+        // real run, and a reader who checks the project's cost against their own tooling needs to
+        // see both numbers and the parts they are made of.
+        const usage = this.resources(p);
+        lines.push(`- 已用等效 Token：${usage.tokens}（口径：输入 + 输出 + 缓存写入×${CACHE_WRITE_WEIGHT} + 缓存读取×${CACHE_READ_WEIGHT}，取整；含项目内的一次性调用（subagent））`);
+        lines.push(`- 原始口径（1:1）：${usage.rawTokens}（输入 ${usage.usage?.input ?? 0} + 输出 ${usage.usage?.output ?? 0} + 缓存写入 ${usage.usage?.cacheWrite ?? 0} + 缓存读取 ${usage.usage?.cacheRead ?? 0}）`);
         lines.push(`- 任务：共 ${p.tasks.length} 个，已完成 ${p.tasks.filter((t) => t.status === "completed").length} 个`);
         lines.push("", "## 交付与验收", "");
         if (!p.tasks.length)
@@ -1192,6 +1237,12 @@ export class ProjectService {
                 throw new Error("项目完成必须提交最终交付，其他状态由任务和例外推导");
             if (status === "active" && p.escalations.some((e) => e.status === "open"))
                 throw new Error("请先处理未解决的例外");
+            /* A PROJECT WITH NO LEADER SESSION HAS NOTHING RUNNING IN IT. The status is derived from
+               the project's own state, and the API may not push it back into the contradiction that
+               derivation exists to prevent: a project whose tasks were only registered is 待启动, and
+               no caller - the panel included - may call it 执行中 until it has actually been started. */
+            if (status === "active" && !p.ownerConversationId)
+                throw new Error("项目尚未启动，请先启动项目负责人");
             p.status = status;
             if (closed(p))
                 p.closedAt = stamp();

package/dist/server/types.d.ts

@@ -939,7 +939,7 @@ export type TerminalShell = {
     file: string;
     args: string[];
 };
-export type ProjectStatus = "planning" | "active" | "blocked" | "awaiting_approval" | "awaiting_review" | "completed" | "failed" | "cancelled";
+export type ProjectStatus = "planning" | "awaiting_start" | "active" | "blocked" | "awaiting_approval" | "awaiting_review" | "completed" | "failed" | "cancelled";
 export type ProjectTaskStatus = "pending" | "ready" | "in_progress" | "blocked" | "awaiting_review" | "completed" | "failed" | "cancelled";
 export type ProjectRisk = "low" | "medium" | "high";
 /**
@@ -1095,6 +1095,13 @@ export type Project = {
         usageKnown: boolean;
         activeWorkers: number;
         memoryTreeId?: string;
+        usage?: {
+            input: number;
+            output: number;
+            cacheRead: number;
+            cacheWrite: number;
+        };
+        rawTokens?: number;
         sessions: {
             id: string;
             title: string;

package/dist/shared/agent-order.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The ONE order agent lists are shown in.
+ *
+ * WHY THERE IS A SINGLE RULE AND NOT A RULE PER SIDE. The picker's list, the settings page's grid, the
+ * sub-agent roster and the project panel's employee candidates are four views of the same catalogue, and
+ * they used to disagree about what a list of agents looks like. The server sorted what it read by
+ * "(built-in first, then id)", and the client re-sorted what the server sent by a rule of its own that
+ * added one more level - "roles before workers". A reader who saw the same agents in two orders had no
+ * way to tell which screen was wrong, because neither was: they were two answers to a question nobody
+ * had asked twice the same way.
+ *
+ * So the rule is stated once, HERE, and both sides apply it. The server imports it to order the
+ * catalogue it reads; the client imports it to order every list it draws. There is no second
+ * implementation to drift, because there is no second implementation.
+ *
+ * THE ORDER IS:
+ *
+ *   1. THE PACKAGE'S OWN agents first, then the user's. The ones that ship with Super Pi are drawn with
+ *      a colour dot, and a dot scattered among the user's own reads as noise rather than as a group.
+ *   2. Inside a group, the CONVERSATION ROLES (mode: primary) before the DELEGATED ones (mode:
+ *      subagent), so a list reads as "the roles, then the workers".
+ *   3. Inside a group and a role, alphabetical by id, so the order never depends on the order the
+ *      filesystem happened to hand the files over in.
+ *
+ * WHY THE FLAG IS NOT GUESSED HERE. "Is this the package's own agent?" is a question about where the app
+ * is installed, and only the server knows that: it reads the definitions and marks them. A client that
+ * tried to work it out from the directory path would be guessing, and would guess wrong the moment the
+ * package is installed somewhere unusual - which is exactly the case where the answer matters.
+ */
+/** The minimum an agent has to carry for this ordering to be able to place it. */
+export type OrderableAgent = {
+    id: string;
+    mode?: "primary" | "subagent";
+    /** True when the definition came from the package's own agents directory. */
+    builtin?: boolean;
+};
+/**
+ * The built-in group first, then the user's, each group by role and then by id.
+ *
+ * An agent with no `builtin` flag at all (an older server, or a hand-built fixture) counts as the
+ * user's, which is the safe direction: it puts the unflagged one where a user's own would sit rather
+ * than promoting it into the group that means "this ships with Super Pi".
+ */
+export declare function orderAgentsForDisplay<T extends OrderableAgent>(agents: readonly T[]): T[];

package/dist/shared/agent-order.js

@@ -0,0 +1,50 @@
+/**
+ * The ONE order agent lists are shown in.
+ *
+ * WHY THERE IS A SINGLE RULE AND NOT A RULE PER SIDE. The picker's list, the settings page's grid, the
+ * sub-agent roster and the project panel's employee candidates are four views of the same catalogue, and
+ * they used to disagree about what a list of agents looks like. The server sorted what it read by
+ * "(built-in first, then id)", and the client re-sorted what the server sent by a rule of its own that
+ * added one more level - "roles before workers". A reader who saw the same agents in two orders had no
+ * way to tell which screen was wrong, because neither was: they were two answers to a question nobody
+ * had asked twice the same way.
+ *
+ * So the rule is stated once, HERE, and both sides apply it. The server imports it to order the
+ * catalogue it reads; the client imports it to order every list it draws. There is no second
+ * implementation to drift, because there is no second implementation.
+ *
+ * THE ORDER IS:
+ *
+ *   1. THE PACKAGE'S OWN agents first, then the user's. The ones that ship with Super Pi are drawn with
+ *      a colour dot, and a dot scattered among the user's own reads as noise rather than as a group.
+ *   2. Inside a group, the CONVERSATION ROLES (mode: primary) before the DELEGATED ones (mode:
+ *      subagent), so a list reads as "the roles, then the workers".
+ *   3. Inside a group and a role, alphabetical by id, so the order never depends on the order the
+ *      filesystem happened to hand the files over in.
+ *
+ * WHY THE FLAG IS NOT GUESSED HERE. "Is this the package's own agent?" is a question about where the app
+ * is installed, and only the server knows that: it reads the definitions and marks them. A client that
+ * tried to work it out from the directory path would be guessing, and would guess wrong the moment the
+ * package is installed somewhere unusual - which is exactly the case where the answer matters.
+ */
+/** The conversation roles come before the delegated ones, so a screen keeps reading as "roles, then workers". */
+const modeRank = (mode) => (mode === "subagent" ? 1 : 0);
+/**
+ * The built-in group first, then the user's, each group by role and then by id.
+ *
+ * An agent with no `builtin` flag at all (an older server, or a hand-built fixture) counts as the
+ * user's, which is the safe direction: it puts the unflagged one where a user's own would sit rather
+ * than promoting it into the group that means "this ships with Super Pi".
+ */
+export function orderAgentsForDisplay(agents) {
+    return [...agents].sort((a, b) => {
+        const left = a.builtin ? 0 : 1;
+        const right = b.builtin ? 0 : 1;
+        if (left !== right)
+            return left - right;
+        const roles = modeRank(a.mode) - modeRank(b.mode);
+        if (roles !== 0)
+            return roles;
+        return a.id.localeCompare(b.id);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evandu/super-pi",
-  "version": "0.1.166",
+  "version": "0.1.167",
   "description": "Web control plane and companion for Pi",
   "license": "MIT",
   "type": "module",
@@ -48,6 +48,7 @@
     "scripts/stream-transport.test.mjs",
     "scripts/remote-transport.test.mjs",
     "scripts/browser-safe-port.test.mjs",
+    "scripts/agent-order.test.mjs",
     "scripts/agent-picker-order.test.mjs",
     "scripts/inline-thinking.test.mjs",
     "scripts/inline-thinking-close-tag.test.mjs",
@@ -266,6 +267,7 @@
     "scripts/sidebar-tools-browser.test.mjs",
     "scripts/project-employee-panel-browser.test.mjs",
     "scripts/project-evidence-panel-browser.test.mjs",
+    "scripts/project-panel-fixes-browser.test.mjs",
     "scripts/builtin-agents-project-browser.test.mjs",
     "scripts/tool-runtime-browser.test.mjs",
     "scripts/session-context-menu-browser.test.mjs",
@@ -294,6 +296,7 @@
     "scripts/stream-tail-browser.test.mjs",
     "scripts/scroll-restore-browser.test.mjs",
     "scripts/theme-contrast.test.mjs",
+    "scripts/ui-contrast-browser.test.mjs",
     "scripts/theme-switch-state.test.mjs",
     "scripts/settings-window-structure.test.mjs",
     "scripts/settings-model-browser.test.mjs",