@evandu/super-pi 0.1.167 → 0.1.168

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-BptmWfVR.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-DWjVnvsQ.css">
+    <script type="module" crossorigin src="/assets/index-C4d7l2t8.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-C3ETe3EL.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/server/agents.d.ts

@@ -199,6 +199,24 @@ export declare function readAgents(directory: string | readonly string[], option
     mode?: AgentModeFilter;
     builtinDir?: string;
 }): Promise<AgentScan>;
+/**
+ * WHAT KIND OF AGENT IS THIS ID?
+ *
+ * The catalogue is read in halves - the primaries and the subagents - and a question about ONE id
+ * has to be asked of both halves. The answer is the `mode:` frontmatter of the definition that
+ * WINS, which is the same override rule `readAgents` already applies: the first directory to offer
+ * an id owns it.
+ *
+ * `undefined` MEANS "NO SUCH AGENT IN THESE DIRECTORIES", and that is NOT the same as "not
+ * primary". An id nobody has heard of is a CUSTOM agent, and custom agents are legal - §3 keeps
+ * them legal on purpose, so that a project can name an agent the catalogue does not carry yet.
+ * Only an agent that EXISTS and is a subagent is a subagent.
+ *
+ * THE HIDDEN ONES COUNT. `hidden` decides whether a person is SHOWN an agent in a picker, not
+ * whether the agent exists, so a hidden subagent is still a subagent here. A guard that could be
+ * walked around by ticking one box in a frontmatter would not be a guard.
+ */
+export declare function agentModeOf(directories: string | readonly string[], agentId: string): Promise<"primary" | "subagent" | undefined>;
 /** Parses one definition file, or returns the reason it is not a usable agent. */
 export declare function parseDefinition(file: string, source: string): AgentDefinition | AgentProblem;
 /**

package/dist/server/agents.js

@@ -545,6 +545,35 @@ export async function readAgents(directory, options = {}) {
         problems,
     };
 }
+/**
+ * WHAT KIND OF AGENT IS THIS ID?
+ *
+ * The catalogue is read in halves - the primaries and the subagents - and a question about ONE id
+ * has to be asked of both halves. The answer is the `mode:` frontmatter of the definition that
+ * WINS, which is the same override rule `readAgents` already applies: the first directory to offer
+ * an id owns it.
+ *
+ * `undefined` MEANS "NO SUCH AGENT IN THESE DIRECTORIES", and that is NOT the same as "not
+ * primary". An id nobody has heard of is a CUSTOM agent, and custom agents are legal - §3 keeps
+ * them legal on purpose, so that a project can name an agent the catalogue does not carry yet.
+ * Only an agent that EXISTS and is a subagent is a subagent.
+ *
+ * THE HIDDEN ONES COUNT. `hidden` decides whether a person is SHOWN an agent in a picker, not
+ * whether the agent exists, so a hidden subagent is still a subagent here. A guard that could be
+ * walked around by ticking one box in a frontmatter would not be a guard.
+ */
+export async function agentModeOf(directories, agentId) {
+    const id = agentId.trim();
+    if (!id)
+        return undefined;
+    const dirs = Array.isArray(directories) ? [...directories] : [directories];
+    for (const mode of ["subagent", "primary"]) {
+        const scan = await readAgents(dirs, { mode });
+        if (scan.agents.some((agent) => agent.id === id))
+            return mode;
+    }
+    return undefined;
+}
 /** Only `#rgb` and `#rrggbb`. A `color:` frontmatter value is rendered as a CSS background, so it has to
  *  be a colour and nothing else - accepting an arbitrary string would put author-controlled text into a
  *  style declaration. Anything else is dropped rather than sanitised into something misleading. */

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

@@ -80,12 +80,56 @@ export type BudgetRaiseResult = {
     /** How many budget exceptions were closed by the raise. */
     resolvedEscalations: number;
 };
+/**
+ * HOW THE SERVICE ASKS WHAT AN AGENT ID IS.
+ *
+ * The employee rule is a fact about the agent DIRECTORY, so the directory is read through the one
+ * reader the server already has (`readAgents`, through `agentModeOf`), and the question is asked of
+ * whoever owns those directories. The service deliberately does not know where the definitions
+ * live: the directories change when the user adds one, and a service that kept its own copy of the
+ * path would answer about a directory that is no longer there.
+ *
+ * `undefined` means "no such agent" - NOT "not primary". An id that is in no directory is a custom
+ * agent, and §3 keeps custom agents legal.
+ */
+export type AgentModeLookup = {
+    agentModeOf(agentId: string): Promise<"primary" | "subagent" | undefined>;
+};
 /** Persist explicit domain fields only; transport credentials never enter project records. */
 export declare class ProjectService {
     private readonly store;
     private readonly orchestrator?;
+    /**
+     * Optional on purpose: a service built without an agent directory cannot tell a subagent from a
+     * custom agent, and it then behaves exactly as it did before this check existed. The real
+     * server always passes one.
+     */
+    private readonly agents?;
     private readonly queues;
-    constructor(store: Store, orchestrator?: (Pick<SessionOrchestratorService, "spawn" | "dispatch"> & Partial<Pick<SessionOrchestratorService, "stopSubtree">>) | undefined);
+    constructor(store: Store, orchestrator?: (Pick<SessionOrchestratorService, "spawn" | "dispatch"> & Partial<Pick<SessionOrchestratorService, "stopSubtree">>) | undefined, 
+    /**
+     * Optional on purpose: a service built without an agent directory cannot tell a subagent from a
+     * custom agent, and it then behaves exactly as it did before this check existed. The real
+     * server always passes one.
+     */
+    agents?: AgentModeLookup | undefined);
+    /**
+     * A PROJECT EMPLOYEE MUST BE A PRIMARY AGENT.
+     *
+     * §1 says a subagent cannot be a project employee: a subagent is a tool-level, one-shot,
+     * invisible call, and a project that leans on one leans on a role the user can never see and
+     * never interrupt. The client only offers primary agents in the candidate list, but a candidate
+     * list is a SUGGESTION - the server is the constraint, and the refusal belongs at the moment the
+     * profile is written, while the reader is still looking at the form. Refusing later (when the
+     * task is dispatched) teaches the reader that the panel accepted something the project cannot
+     * use.
+     *
+     * WHAT IS REFUSED, AND WHAT IS NOT. An agent that EXISTS and is a subagent is refused, and the
+     * message names the slot and the agent, so the reader knows WHICH employee to change. An id that
+     * is in NO directory is a custom agent, and §3 keeps custom agents legal - so it is accepted here,
+     * exactly as it was before this check existed.
+     */
+    private assertEmployee;
     static taskView(task: ProjectTask, project: Pick<Project, "defaultExecutorProfile" | "defaultReviewerProfile">): ProjectTask;
     private filterEscalations;
     private projectView;
@@ -265,8 +309,8 @@ export declare class ProjectService {
      */
     raiseBudgetAndContinue(id: string, workspaceId: string, callerConversationId?: string): Promise<BudgetRaiseResult>;
     addReport(id: string, input: Omit<ProjectReport, "id" | "projectId" | "createdAt">, workspaceId?: string, actor?: string): Promise<ProjectReport>;
-    addEscalation(id: string, input: Pick<ProjectEscalation, "reason" | "severity" | "taskId">, workspaceId?: string, actor?: string): Promise<ProjectEscalation>;
-    resolveEscalation(id: string, escalationId: string, decision: string, status: "resolved" | "dismissed", workspaceId?: string, actor?: string): Promise<ProjectEscalation>;
+    addEscalation(id: string, input: Pick<ProjectEscalation, "reason" | "severity" | "taskId" | "title">, workspaceId?: string, actor?: string): Promise<ProjectEscalation>;
+    resolveEscalation(id: string, escalationId: string, decision: string, status: "resolved" | "dismissed" | "returned", workspaceId?: string, actor?: string): Promise<ProjectEscalation>;
     complete(id: string, summary: string, evidenceRefs: unknown, workspaceId: string, actor?: string): Promise<Project>;
     /**
      * The tasks an initiator hands over with create. A dependency names the TITLE of another task in

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

@@ -171,7 +171,7 @@ const EVENT_TEXT = {
     budget: "预算变更", report: "进展汇报", escalated: "例外升级", decision: "决定",
     completed: "项目完成", ready: "依赖就绪", unreachable: "转述对象不可达",
 };
-const ESCALATION_STATUS_TEXT = { open: "未决", resolved: "已解决", dismissed: "已忽略" };
+const ESCALATION_STATUS_TEXT = { open: "未决", resolved: "已解决", dismissed: "已忽略", returned: "已退回补充材料" };
 const SEVERITY_TEXT = { low: "低", medium: "中", high: "高" };
 const REPORT_KIND_TEXT = {
     progress: "进展", blocked: "阻塞", delivery: "交付", decision_request: "决策请求", review: "复核",
@@ -202,10 +202,43 @@ const lightweight = (p) => p.mode === "lightweight";
 export class ProjectService {
     store;
     orchestrator;
+    agents;
     queues = new Map();
-    constructor(store, orchestrator) {
+    constructor(store, orchestrator, 
+    /**
+     * Optional on purpose: a service built without an agent directory cannot tell a subagent from a
+     * custom agent, and it then behaves exactly as it did before this check existed. The real
+     * server always passes one.
+     */
+    agents) {
         this.store = store;
         this.orchestrator = orchestrator;
+        this.agents = agents;
+    }
+    /**
+     * A PROJECT EMPLOYEE MUST BE A PRIMARY AGENT.
+     *
+     * §1 says a subagent cannot be a project employee: a subagent is a tool-level, one-shot,
+     * invisible call, and a project that leans on one leans on a role the user can never see and
+     * never interrupt. The client only offers primary agents in the candidate list, but a candidate
+     * list is a SUGGESTION - the server is the constraint, and the refusal belongs at the moment the
+     * profile is written, while the reader is still looking at the form. Refusing later (when the
+     * task is dispatched) teaches the reader that the panel accepted something the project cannot
+     * use.
+     *
+     * WHAT IS REFUSED, AND WHAT IS NOT. An agent that EXISTS and is a subagent is refused, and the
+     * message names the slot and the agent, so the reader knows WHICH employee to change. An id that
+     * is in NO directory is a custom agent, and §3 keeps custom agents legal - so it is accepted here,
+     * exactly as it was before this check existed.
+     */
+    async assertEmployee(profile, label) {
+        const agentId = profile?.agentId;
+        if (!agentId || !this.agents)
+            return;
+        const mode = await this.agents.agentModeOf(agentId);
+        if (mode === "subagent") {
+            throw new Error(`${label}.agentId 指向的是 subagent（${agentId}），项目员工必须是 primary：subagent 是一次性的工具级调用，用户在侧栏看不到它的中间步骤，也插不上话。`);
+        }
     }
     static taskView(task, project) {
         const t = { ...task };
@@ -820,6 +853,12 @@ export class ProjectService {
         const defaultLeaderProfile = profile(input.defaultLeaderProfile, "默认 Leader 配置");
         const defaultExecutorProfile = profile(input.defaultExecutorProfile, "默认执行配置");
         const defaultReviewerProfile = profile(input.defaultReviewerProfile, "默认复核配置");
+        // THE PROJECT'S OWN EMPLOYEE DEFAULTS ARE EMPLOYEES TOO. They are the profiles every task
+        // inherits when it names no one, so a subagent written here would become the employee of the
+        // whole project - and it would be refused at every task that inherited it, one by one, long
+        // after the person who wrote it had walked away.
+        await this.assertEmployee(defaultExecutorProfile, "defaultExecutorProfile");
+        await this.assertEmployee(defaultReviewerProfile, "defaultReviewerProfile");
         const initiator = (initiatorConversationId ?? (typeof input.initiatorConversationId === "string" ? input.initiatorConversationId : undefined))?.trim() || undefined;
         const now = stamp();
         const p = { id: `project_${randomUUID()}`, workspaceId, title: text(input.title, "项目标题"), objective: text(input.objective, "项目目标"),
@@ -909,7 +948,7 @@ export class ProjectService {
         });
     }
     async addTask(id, input, workspaceId, actor) {
-        return this.change(id, workspaceId, (p) => {
+        return this.change(id, workspaceId, async (p) => {
             this.live(p);
             const parentTaskId = optional(input.parentTaskId, "父任务 id");
             // A LIGHTWEIGHT PROJECT HAS ONE SESSION, SO IT HAS NO TREE OF TASKS. Decomposing the work
@@ -961,6 +1000,11 @@ export class ProjectService {
                 throw new Error("项目最多 100 个任务，请收敛分工范围");
             const executorProfile = profile(input.executorProfile, "执行配置");
             const reviewerProfile = profile(input.reviewerProfile, "复核配置");
+            // THE EMPLOYEE IS CHECKED BEFORE THE TASK EXISTS. The refusal happens in the write itself,
+            // so a project never carries a task whose employee is a subagent - not even for the moment
+            // between the write and the next read.
+            await this.assertEmployee(executorProfile, "executorProfile");
+            await this.assertEmployee(reviewerProfile, "reviewerProfile");
             const now = stamp();
             const t = { id: `task_${randomUUID()}`, projectId: id, title: text(input.title, "任务标题"), objective: text(input.objective, "任务目标"),
                 status: dependencies.length ? "pending" : "ready", accountableConversationId: manager, parentTaskId, role: input.role ?? "executor", dependencies,
@@ -1126,7 +1170,7 @@ export class ProjectService {
         });
     }
     async updateTask(id, taskId, patch, actor) {
-        const result = await this.change(id, patch.workspaceId, (p) => {
+        const result = await this.change(id, patch.workspaceId, async (p) => {
             this.live(p);
             const t = this.task(p, taskId);
             this.member(p, actor);
@@ -1160,6 +1204,9 @@ export class ProjectService {
                 if (t.ownerConversationId)
                     throw new Error("执行会话已创建，禁止修改执行配置");
                 const ep = profile(patch.executorProfile, "执行配置");
+                // THE CHECK COMES BEFORE THE ASSIGNMENT. The task keeps the employee it had; what it must
+                // not do is end up holding an employee the project is not allowed to have.
+                await this.assertEmployee(ep, "executorProfile");
                 if (ep)
                     t.executorProfile = ep;
                 else
@@ -1169,6 +1216,7 @@ export class ProjectService {
                 if (t.reviewerConversationId)
                     throw new Error("复核会话已创建，禁止修改复核配置");
                 const rp = profile(patch.reviewerProfile, "复核配置");
+                await this.assertEmployee(rp, "reviewerProfile");
                 if (rp)
                     t.reviewerProfile = rp;
                 else
@@ -1374,7 +1422,7 @@ export class ProjectService {
             if (actor && actor !== p.ownerConversationId && (!t || ![t.ownerConversationId, t.reviewerConversationId, this.manager(p, t)].includes(actor)))
                 throw new Error("仅可汇报本人负责的任务");
             const report = { id: randomUUID(), projectId: id, taskId: t?.id, authorConversationId: actor, kind: input.kind,
-                progress: text(input.progress, "汇报进展"), variance: optional(input.variance, "偏差"), nextStep: optional(input.nextStep, "下一步"), risks: strings(input.risks, "风险"),
+                progress: text(input.progress, "汇报进展"), summary: typeof input.summary === "string" && input.summary.trim() ? text(input.summary, "汇报标题") : undefined, variance: optional(input.variance, "偏差"), nextStep: optional(input.nextStep, "下一步"), risks: strings(input.risks, "风险"),
                 decisionNeeded: optional(input.decisionNeeded, "所需决策"), evidenceRefs: strings(input.evidenceRefs, "证据"), createdAt: stamp() };
             p.reports.push(report);
             if (report.kind === "blocked") {
@@ -1438,6 +1486,10 @@ export class ProjectService {
                 projectId: id,
                 taskId: t?.id,
                 reason: text(input.reason, "升级原因"),
+                /* THE QUESTION IS KEPT BESIDE THE CASE. The title is what the reader decides ON - one
+                   sentence, in the reader's terms - and the reason is the case for it. An escalation
+                   * without a title is still a valid escalation; it simply has to be read in full. */
+                ...(typeof input.title === "string" && input.title.trim() ? { title: text(input.title, "升级标题") } : {}),
                 severity: input.severity,
                 status: "open",
                 requestedByConversationId: actor,
@@ -1446,19 +1498,19 @@ export class ProjectService {
                 createdAt: stamp(),
             };
             p.escalations.push(e);
-            this.event(p, "escalated", e.reason, t?.id, actor);
+            this.event(p, "escalated", e.title ? `${e.title}：${e.reason}` : e.reason, t?.id, actor);
             this.reconcile(p);
             return e;
         }, actor);
         if (supervisorToWake) {
-            await this.wake(supervisorToWake, `下级成员（会话：${actor}，身份：${wakeMemberRole ?? "执行者"}）发起例外升级（ID：${result.id}）：\n原因：${result.reason}\n严重级别：${result.severity}\n请及时处理该例外（调用 project action="resolve_escalation" 记录处理意见），或按需向上级转述升级。`, `例外升级（ID：${result.id}）`, id, workspaceId, actor);
+            await this.wake(supervisorToWake, `下级成员（会话：${actor}，身份：${wakeMemberRole ?? "执行者"}）发起例外升级（ID：${result.id}）：\n${result.title ? `待决问题：${result.title}\n` : ""}原因：${result.reason}\n严重级别：${result.severity}\n请及时处理该例外（调用 project action="resolve_escalation" 记录处理意见），或按需向上级转述升级。`, `例外升级（ID：${result.id}）`, id, workspaceId, actor);
         }
         return result;
     }
     async resolveEscalation(id, escalationId, decision, status, workspaceId, actor) {
         const result = await this.change(id, workspaceId, (p) => {
             this.live(p);
-            if (status !== "resolved" && status !== "dismissed")
+            if (status !== "resolved" && status !== "dismissed" && status !== "returned")
                 throw new Error("升级处理状态不合法");
             const e = p.escalations.find((e) => e.id === escalationId);
             if (!e)
@@ -1481,10 +1533,24 @@ export class ProjectService {
             e.decision = text(decision, "处理意见");
             e.resolvedAt = stamp();
             const decider = audience === "boss" ? "Boss" : "直接上级";
-            this.event(p, "decision", `${decider}决策：${e.decision}`, e.taskId, actor);
+            /* A RETURN IS NOT A DECISION. It says the case was not ready - the reader is being asked
+             * for more material, not for a ruling - so the timeline says so in those words. */
+            this.event(p, "decision", status === "returned"
+                ? `${decider}退回例外，等待补充材料：${e.decision}`
+                : `${decider}决策：${e.decision}`, e.taskId, actor);
             this.reconcile(p);
             return e;
         }, actor);
+        /* THE CASE GOES BACK TO WHO RAISED IT. A returned escalation leaves the inbox without being
+         * answered, so nobody would ever know it was still open - unless the person who raised it is
+         * woken up and told to bring the missing material. This is the one wake that is NOT about a
+         * decision: it is about work coming back. */
+        if (status === "returned") {
+            if (result.requestedByConversationId) {
+                await this.wake(result.requestedByConversationId, `例外已退回，等待对方补充材料（ID：${result.id}）：${result.title ?? result.reason}\n退回意见：${result.decision}\n请补充材料后重新发起升级。`, `例外已退回（ID：${result.id}）`, id, workspaceId, actor);
+            }
+            return result;
+        }
         const p = this.raw(id, workspaceId);
         if (result.audience === "supervisor") {
             if (result.requestedByConversationId) {

package/dist/server/index.js

@@ -9,7 +9,7 @@ import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { openStateStore } from "./persistence/open-state-store.js";
 import { PiRpcRuntime, WelcomeRuntime } from "./runtime.js";
-import { resolveAgentDirectories } from "./agents.js";
+import { agentModeOf, resolveAgentDirectories } from "./agents.js";
 import { releaseAllCapabilities } from "./capability.js";
 import { SubagentSupervisor } from "./subagents.js";
 import { SubagentRunRecorder } from "./subagent-runs.js";
@@ -297,7 +297,18 @@ runService.setExecService(execService);
 const scheduledTaskService = new ScheduledTaskService(store, runService, conversationService, broadcaster);
 const sessionLedger = new SessionLedger();
 const sessionOrchestratorService = new SessionOrchestratorService(store, conversationService, runService, sessionLedger, broadcaster);
-const projectService = new ProjectService(store, sessionOrchestratorService);
+/**
+ * THE PROJECT SERVICE IS TOLD HOW TO ASK WHAT AN AGENT IS.
+ *
+ * The employee rule of §1 - "a subagent cannot be a project employee" - is a fact about the agent
+ * DIRECTORY, and the directory is read through the same reader the picker and the runtime use
+ * (`readAgents`, through `agentModeOf`). The directories are asked of the catalogue service
+ * because THEY are the live ones: the user can add an agents directory at any time, and a guard
+ * that read a path captured at startup would answer about a directory that is no longer there.
+ */
+const projectService = new ProjectService(store, sessionOrchestratorService, {
+    agentModeOf: (agentId) => agentModeOf(catalogService.getAgentDirs(), agentId),
+});
 void sessionOrchestratorService.restoreWatchdogs().catch((error) => {
     console.warn("Super Pi: restoring watchdogs failed:", error instanceof Error ? error.message : String(error));
 });

package/dist/server/types.d.ts

@@ -1011,6 +1011,7 @@ export type ProjectReport = {
     authorConversationId?: string;
     kind: "progress" | "blocked" | "delivery" | "decision_request" | "review";
     progress: string;
+    summary?: string;
     variance?: string;
     nextStep?: string;
     risks?: string[];
@@ -1022,9 +1023,12 @@ export type ProjectEscalation = {
     id: string;
     projectId: string;
     taskId?: string;
-    reason: string;
+    reason: string; /** THE QUESTION, IN ONE SENTENCE. What the Boss has to decide - as opposed to `reason`,
+       *  which is the case for it. The reader decides in a glance, and reads the case only if the
+       *  question is not obvious; an escalation without a title falls back to the reason. */
+    title?: string;
     severity: ProjectRisk;
-    status: "open" | "resolved" | "dismissed";
+    status: "open" | "resolved" | "dismissed" | "returned";
     requestedByConversationId?: string;
     decision?: string;
     createdAt: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evandu/super-pi",
-  "version": "0.1.167",
+  "version": "0.1.168",
   "description": "Web control plane and companion for Pi",
   "license": "MIT",
   "type": "module",
@@ -196,6 +196,7 @@
     "scripts/session-state-icon.test.mjs",
     "scripts/provider-fetch-models.test.mjs",
     "scripts/shared-chrome.test.mjs",
+    "scripts/shared-chrome-recovery.test.mjs",
     "scripts/prompt-templates.test.mjs",
     "scripts/documents.test.mjs",
     "scripts/web-tools.test.mjs",
@@ -232,7 +233,8 @@
     "scripts/awaiting-background-status.test.mjs",
     "scripts/project-lifecycle-e2e.test.mjs",
     "scripts/agent-tiers.test.mjs",
-    "scripts/design-principles.test.mjs"
+    "scripts/design-principles.test.mjs",
+    "scripts/primary-employee-guard.test.mjs"
   ],
   "check:browser": [
     "scripts/interrupt-browser.test.mjs",
@@ -266,8 +268,10 @@
     "scripts/workspace-identity-browser.test.mjs",
     "scripts/sidebar-tools-browser.test.mjs",
     "scripts/project-employee-panel-browser.test.mjs",
+    "scripts/primary-employee-guard-browser.test.mjs",
     "scripts/project-evidence-panel-browser.test.mjs",
     "scripts/project-panel-fixes-browser.test.mjs",
+    "scripts/boss-approval-readability-browser.test.mjs",
     "scripts/builtin-agents-project-browser.test.mjs",
     "scripts/tool-runtime-browser.test.mjs",
     "scripts/session-context-menu-browser.test.mjs",