pi-proactive 0.2.0-beta.3 → 0.2.0-beta.4

package/build/src/mailbox.js

@@ -1,3 +1,5 @@
+// 【S0 归属】L1 内核 · 宿主无关（契约：docs/project/kernel-contract-s0.md §6.1）
+//   → 不得 import 宿主包、不得出现宿主类型/字段；对外只经宿主无关接口（HostPort 一族）。
 /**
  * `src/mailbox.ts` —— 收件侧文件邮箱（M4c：扫描 / 原子认领 / 过期归档 / 去重闭环 / 清理）。
  *

package/build/src/notify.js

@@ -1,3 +1,5 @@
+// 【S0 归属】L2 适配器 · 宿主相关（契约：docs/project/kernel-contract-s0.md §6.1）
+//   → 宿主概念只许出现在这一层；这里的耦合是**适配**，不是内核耦合。
 /**
  * 设备级通知（形态 A · N1）与「会话内联系」**共用同一份载荷**。
  *

package/build/src/peer-spawn.js

@@ -1,3 +1,5 @@
+// 【S0 归属】L3 宿主集成（契约：docs/project/kernel-contract-s0.md §6.1）
+//   → 直接面对宿主/操作系统；内核面（机制/协议/记录/决策/目标/接口）不在本文件。
 /**
  * `src/peer-spawn.ts` —— **创建**一个对端会话（peer 生命周期的「创建」这条腿）。
  *

package/build/src/peer.js

@@ -1,3 +1,5 @@
+// 【S0 归属】L1 内核 · 宿主无关（契约：docs/project/kernel-contract-s0.md §6.1）
+//   → 不得 import 宿主包、不得出现宿主类型/字段；对外只经宿主无关接口（HostPort 一族）。
 /**
  * `src/peer.ts` —— M5a：**逐条** reply 归因（问 → 答 → 回信 一一对应）。
  *

package/build/src/registry.js

@@ -1,3 +1,5 @@
+// 【S0 归属】L1 内核 · 宿主无关（契约：docs/project/kernel-contract-s0.md §6.1）
+//   → 不得 import 宿主包、不得出现宿主类型/字段；对外只经宿主无关接口（HostPort 一族）。
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";

package/build/src/socket.js

@@ -1,3 +1,5 @@
+// 【S0 归属】L1 内核 · 宿主无关（契约：docs/project/kernel-contract-s0.md §6.1）
+//   → 不得 import 宿主包、不得出现宿主类型/字段；对外只经宿主无关接口（HostPort 一族）。
 /**
  * `src/socket.ts` —— 跨进程实时传输通道（M4b：unix domain socket）。
  *

package/build/src/supervisor-state.js

@@ -0,0 +1,355 @@
+/**
+ * 监督面的**状态聚合**（双面同源的单一真源）。
+ *
+ * 为什么要单独一个模块：Web 看板与 pi-agent 的 TUI 面板是**两个渲染层**，
+ * 若各算各的 → 两处数字必然漂移（这是本仓库反复踩到的坑）。
+ * ⇒ 本模块**只读**既有事实面，算出**一次**，两个渲染层各自呈现、**不重算**。
+ *
+ * 只读的事实面（**不新造数据结构、不新增协议**）：
+ * - 事件流（血缘）`<agentDir>/proactive/lineage/*.jsonl` → 联系时间线 + 四段计数；
+ * - 心跳 `<agentDir>/proactive/daemon/heartbeat.json` → 在不在 / 宿主 / 进程 / 心跳龄期；
+ * - 值班状态 `<agentDir>/proactive/daemon/state.json` → 预算已用 + 人工确认队列；
+ * - 配置 `<agentDir>/proactive/daemon.json` → 预算硬上限；
+ * - 托付登记册 `<agentDir>/proactive/trust/registry.json` → 托付 / 目标。
+ *
+ * 口径说明：
+ * - 四段计数 = **按事件类型计数**（triggered / delivered / answered / outcome），
+ *   与 `scripts/team/progress-snapshot.sh` 的守恒等式**同一口径**（第三方可独立复算）；
+ * - 托付四段（登记/到达/知会/结账）直接复用 `src/trust-metrics.ts` 的守恒判定，**不另写一套**；
+ * - **脱敏默认**：会话正文只给长度与摘要（sha256 前 12 位）；提示词原文、队列原始提示一律不进结果。
+ *
+ * **只读**：本模块不写任何文件（坏文件只跳过、不修复、不备份）。
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { proactiveDir, resolveAgentDir } from "./config.js";
+import { daemonConfigPath, daemonStatePath, heartbeatPath, loadDaemonConfig } from "./daemon-config.js";
+import { formatAgo, readAssistantStatus } from "./assistant.js";
+import { computeTrustMetrics, readLineageEvents } from "./trust-metrics.js";
+import { TrustRegistry } from "./trust-registry.js";
+/** 读 JSON（坏文件 / 不存在 / 不是对象 → undefined，绝不抛、绝不写）。 */
+function readJsonSafe(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function num(v, fallback) {
+    return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+function str(v) {
+    return typeof v === "string" && v !== "" ? v : undefined;
+}
+/** 一条事件的人话摘要（**只描述事件事实，不含正文**）。 */
+function describeEvent(e) {
+    switch (e.type) {
+        case "triggered":
+            return `触发（${e.cause}）`;
+        case "delivered":
+            return `投递 → ${e.result ?? "（无结果）"}`;
+        case "answered":
+            return `回应（${e.responder ?? "未知"}）`;
+        case "outcome":
+            return `结账 → ${e.result ?? "（无结果）"}`;
+        case "dropped":
+            return `拦下（${e.reason ?? "未注明"}）`;
+        case "decision":
+            return `决策 → ${e.decision?.decision ?? "（无）"}（${e.decision?.reason ?? "未注明"}）`;
+        case "trust":
+            return `托付 · ${e.trust?.stage ?? "（无阶段）"}`;
+        default:
+            return e.type;
+    }
+}
+/** 时间线一条（脱敏）。 */
+function toTimelineEntry(e) {
+    const entry = {
+        ts: e.ts,
+        type: e.type,
+        cause: e.cause,
+        summary: describeEvent(e),
+    };
+    if (e.bodyLen !== undefined)
+        entry.bodyLen = e.bodyLen;
+    if (e.bodyDigest !== undefined)
+        entry.bodyDigest = e.bodyDigest;
+    if (e.peer !== undefined)
+        entry.peer = e.peer;
+    const detail = e.result ?? e.reason;
+    if (detail !== undefined)
+        entry.detail = detail;
+    return entry;
+}
+/**
+ * 采集监督面状态（**只读**）。
+ *
+ * @param opts 见 {@link SupervisorOptions}。
+ */
+export function collectSupervisorState(opts = {}) {
+    const agentDir = opts.agentDir ?? resolveAgentDir();
+    const now = opts.now ?? Date.now();
+    const agentId = opts.agentId ?? "supervisor";
+    const limit = opts.timelineLimit ?? 50;
+    // ---- 事件流（血缘）：时间线 + 四段计数 + 托付四段 ----
+    const lineageDir = path.join(proactiveDir(agentDir), "lineage");
+    const events = readLineageEvents(lineageDir);
+    const sorted = [...events].sort((a, b) => a.ts - b.ts);
+    let triggered = 0;
+    let delivered = 0;
+    let answered = 0;
+    let outcome = 0;
+    for (const e of sorted) {
+        if (e.type === "triggered")
+            triggered += 1;
+        else if (e.type === "delivered")
+            delivered += 1;
+        else if (e.type === "answered")
+            answered += 1;
+        else if (e.type === "outcome")
+            outcome += 1;
+    }
+    const metrics = computeTrustMetrics(sorted);
+    const timeline = sorted.slice(Math.max(0, sorted.length - limit)).map(toTimelineEntry);
+    // ---- 状态卡（心跳 / 上次联系）：复用既有读法，不另写一套 ----
+    const assistant = readAssistantStatus(agentDir, now);
+    const hb = readJsonSafe(heartbeatPath(agentDir));
+    const status = {
+        present: assistant.present,
+        running: assistant.installed,
+        pidAlive: assistant.pidAlive,
+    };
+    if (assistant.notRunningReason !== undefined)
+        status.notRunningReason = assistant.notRunningReason;
+    if (assistant.heartbeatTs !== undefined)
+        status.heartbeatTs = assistant.heartbeatTs;
+    if (assistant.heartbeatAgeMs !== undefined)
+        status.heartbeatAgeMs = assistant.heartbeatAgeMs;
+    if (assistant.lastContactTs !== undefined) {
+        status.lastContactTs = assistant.lastContactTs;
+        status.lastContactAgeMs = Math.max(0, now - assistant.lastContactTs);
+    }
+    if (hb !== undefined) {
+        const host = str(hb.host);
+        if (host !== undefined)
+            status.host = host;
+        const pid = hb.pid;
+        if (typeof pid === "number" && Number.isFinite(pid))
+            status.pid = pid;
+        const hbAgent = str(hb.agentId);
+        if (hbAgent !== undefined)
+            status.agentId = hbAgent;
+        const runMode = str(hb.runMode);
+        if (runMode !== undefined)
+            status.runMode = runMode;
+        if (typeof hb.enabled === "boolean")
+            status.enabled = hb.enabled;
+        if (typeof hb.contactEnabled === "boolean")
+            status.contactEnabled = hb.contactEnabled;
+    }
+    // ---- 预算（上限来自配置，已用来自值班状态）----
+    const configured = fs.existsSync(daemonConfigPath(agentDir));
+    const daemonConfig = loadDaemonConfig(agentDir, agentId).config;
+    const limits = daemonConfig.budget;
+    const rawState = readJsonSafe(daemonStatePath(agentDir));
+    const used = rawState?.budget ?? {};
+    const hourCount = num(used.hourCount, 0);
+    const dayCount = num(used.dayCount, 0);
+    const limitedDayCount = num(used.limitedDayCount, 0);
+    const tokenUnits = num(used.tokenUnits, 0);
+    const budget = {
+        configured,
+        hourCount,
+        maxActionsPerHour: limits.maxActionsPerHour,
+        hourRemaining: Math.max(0, limits.maxActionsPerHour - hourCount),
+        dayCount,
+        maxActionsPerDay: limits.maxActionsPerDay,
+        dayRemaining: Math.max(0, limits.maxActionsPerDay - dayCount),
+        limitedDayCount,
+        maxLimitedActionsPerDay: limits.maxLimitedActionsPerDay,
+        limitedDayRemaining: Math.max(0, limits.maxLimitedActionsPerDay - limitedDayCount),
+        tokenUnits,
+        maxTokenUnitsPerDay: limits.maxTokenUnitsPerDay,
+        tokenRemaining: Math.max(0, limits.maxTokenUnitsPerDay - tokenUnits),
+        exhausted: false,
+        degradeToObserve: limits.degradeToObserveWhenExhausted,
+    };
+    if (hourCount >= limits.maxActionsPerHour) {
+        budget.exhausted = true;
+        budget.reason = `每小时动作上限已满（${hourCount}/${limits.maxActionsPerHour}）`;
+    }
+    else if (dayCount >= limits.maxActionsPerDay) {
+        budget.exhausted = true;
+        budget.reason = `每日动作上限已满（${dayCount}/${limits.maxActionsPerDay}）`;
+    }
+    else if (tokenUnits >= limits.maxTokenUnitsPerDay) {
+        budget.exhausted = true;
+        budget.reason = `每日 token 估算上限已满（${tokenUnits}/${limits.maxTokenUnitsPerDay}，估算口径非实测）`;
+    }
+    // ---- 托付登记册（坏文件 → 空册，绝不抛）----
+    let goals = [];
+    let entrustments = [];
+    try {
+        const registry = new TrustRegistry({ agentDir, agentId });
+        goals = registry.listGoals();
+        entrustments = registry.listEntrustments();
+    }
+    catch {
+        // 坏登记册 → 当作空册（只读面不做任何修复写）
+    }
+    const trusts = entrustments.map((e) => {
+        const entry = { id: e.id, target: e.target, status: e.status, createdAt: e.createdAt };
+        if (e.goalId !== undefined)
+            entry.goalId = e.goalId;
+        if (e.arrivedAt !== undefined)
+            entry.arrivedAt = e.arrivedAt;
+        if (e.notifiedAt !== undefined)
+            entry.notifiedAt = e.notifiedAt;
+        if (e.settledAt !== undefined)
+            entry.settledAt = e.settledAt;
+        if (e.revokedAt !== undefined)
+            entry.revokedAt = e.revokedAt;
+        if (e.needsHuman === true)
+            entry.needsHuman = true;
+        if (e.humanReason !== undefined)
+            entry.humanReason = e.humanReason;
+        return entry;
+    });
+    const goalEntries = goals.map((g) => {
+        const entry = {
+            id: g.id,
+            title: g.title,
+            status: g.status,
+            progressSteps: g.progressSteps,
+            maxActions: g.budget?.maxActions ?? 0,
+            usedActions: g.budget?.usedActions ?? 0,
+            permission: g.permission,
+            updatedAt: g.updatedAt,
+        };
+        if (g.humanReason !== undefined)
+            entry.humanReason = g.humanReason;
+        return entry;
+    });
+    // ---- 阻塞（等人决策 / 预算闸门 / 动作失败）----
+    const blockers = [];
+    for (const g of goalEntries) {
+        if (g.status === "needs-human") {
+            blockers.push({
+                id: `goal:${g.id}`,
+                category: "human-decision",
+                title: `目标等人工决策：${g.title}`,
+                ...(g.humanReason !== undefined ? { detail: g.humanReason } : {}),
+                since: g.updatedAt,
+            });
+        }
+    }
+    for (const t of trusts) {
+        if (t.needsHuman === true) {
+            blockers.push({
+                id: `entrustment:${t.id}`,
+                category: "human-decision",
+                title: `托付等人工决策：${t.target}`,
+                ...(t.humanReason !== undefined ? { detail: t.humanReason } : {}),
+                since: t.createdAt,
+            });
+        }
+    }
+    for (const q of rawState?.queue ?? []) {
+        const title = str(q.title) ?? "（未命名动作）";
+        const reason = str(q.reason);
+        blockers.push({
+            id: `queue:${str(q.id) ?? String(q.ts ?? 0)}`,
+            category: "human-decision",
+            title: `待人工确认：${title}`,
+            ...(reason !== undefined ? { detail: reason } : {}),
+            ...(typeof q.ts === "number" ? { since: q.ts } : {}),
+        });
+    }
+    if (budget.exhausted) {
+        blockers.push({
+            id: "budget:exhausted",
+            category: "budget",
+            title: budget.reason ?? "预算已耗尽",
+        });
+    }
+    for (const a of rawState?.actions ?? []) {
+        if (a.outcome !== "failed")
+            continue;
+        const title = str(a.title) ?? "（未命名动作）";
+        const reason = str(a.reason);
+        blockers.push({
+            id: `action:${String(a.ts ?? 0)}`,
+            category: "action-failed",
+            title: `动作失败：${title}`,
+            ...(reason !== undefined ? { detail: reason } : {}),
+            ...(typeof a.ts === "number" ? { since: a.ts } : {}),
+        });
+    }
+    const conservation = {
+        triggered,
+        delivered,
+        answered,
+        outcome,
+        equal: triggered === delivered && delivered === answered && answered === outcome,
+        entrustmentRegistered: metrics.conservation.registered,
+        entrustmentArrived: metrics.conservation.arrived,
+        entrustmentNotified: metrics.conservation.notified,
+        entrustmentSettled: metrics.conservation.settled,
+        entrustmentRevoked: metrics.conservation.revoked,
+        entrustmentInFlight: metrics.conservation.inFlight,
+        entrustmentBalanced: metrics.conservation.balanced,
+        entrustmentViolations: metrics.conservation.violations,
+        responseRate: metrics.responseRate.value,
+        closureRate: metrics.entrustmentClosureRate.value,
+        watchDurationMs: metrics.watchDuration.averageMs,
+    };
+    return {
+        generatedAt: now,
+        agentDir,
+        status,
+        timeline,
+        trusts,
+        goals: goalEntries,
+        budget,
+        blockers,
+        conservation,
+    };
+}
+// ---------------------------------------------------------------- 共享口径文本
+//
+// 为什么文本也放在这里：两个渲染面（Web 看板 / TUI 面板）显示的**同一组数字**
+// 必须**逐字一致**（验收 A8）→ 文本构造与聚合放在同一处，两边只是摆放。
+// （若各写各的字符串，迟早漂移 —— 这正是本仓库反复踩到的坑。）
+/** 「助理在不在」的一行摘要（**状态栏一行**：在不在 · 上次联系 · 预算余量）。 */
+export function formatSupervisorSummary(state) {
+    const where = state.status.running ? "在" : state.status.present ? "不在（装过但没在跑）" : "不在";
+    const contact = state.status.lastContactAgeMs === undefined ? "从未联系" : `${formatAgo(state.status.lastContactAgeMs)}`;
+    return `助理 ${where} · 上次联系 ${contact} · 预算余量 每日 ${state.budget.dayRemaining}/${state.budget.maxActionsPerDay}（小时 ${state.budget.hourRemaining}/${state.budget.maxActionsPerHour}）`;
+}
+/** 四段守恒等式的一行（`triggered=… delivered=… answered=… outcome=…`）。 */
+export function formatConservationLine(state) {
+    const c = state.conservation;
+    return `triggered=${c.triggered} delivered=${c.delivered} answered=${c.answered} outcome=${c.outcome} → ${c.equal ? "相等（无悬空）" : "有悬空"}`;
+}
+/** 托付四段守恒等式的一行。 */
+export function formatEntrustmentConservationLine(state) {
+    const c = state.conservation;
+    return `登记=${c.entrustmentRegistered} 到达=${c.entrustmentArrived} 知会=${c.entrustmentNotified} 结账=${c.entrustmentSettled} 撤销=${c.entrustmentRevoked} 在途=${c.entrustmentInFlight} → ${c.entrustmentBalanced ? "守恒" : "有悬空"}`;
+}
+/** 预算的一行（三档余量）。 */
+export function formatBudgetLine(state) {
+    const b = state.budget;
+    return `小时 ${b.hourCount}/${b.maxActionsPerHour}（余 ${b.hourRemaining}）· 每日 ${b.dayCount}/${b.maxActionsPerDay}（余 ${b.dayRemaining}）· token ${b.tokenUnits}/${b.maxTokenUnitsPerDay}（余 ${b.tokenRemaining}）`;
+}
+/** 状态卡的一行（宿主 / 进程 / 心跳龄期）。 */
+export function formatStatusLine(state) {
+    const s = state.status;
+    const host = s.host ?? "未知";
+    const pid = s.pid === undefined ? "无" : String(s.pid);
+    const age = s.heartbeatAgeMs === undefined ? "无心跳" : formatAgo(s.heartbeatAgeMs);
+    return `宿主 ${host} · 进程 ${pid}（${s.pidAlive ? "活" : "不在"}）· 心跳 ${age}`;
+}

package/build/src/supervisor-tui.js

@@ -0,0 +1,85 @@
+/**
+ * TUI 监督面（**只读渲染层**）：状态栏摘要 + 可展开面板。
+ *
+ * 与 Web 面**同源**：两个渲染层都消费 `src/supervisor-state.ts` 的**同一份聚合**，
+ * 且关键数字的**文本构造**也在那个模块里（`formatConservationLine` 等）→
+ * 两处的数字**逐字一致**（验收 A8），不是"各算各的、碰巧一样"。
+ *
+ * 本模块**纯文本**、不依赖宿主 API（无 ANSI、无终端宽度库）：
+ * 着色由扩展层用宿主的 theme 加，宽度裁剪由扩展层做 → 本模块可被纯 Node 测试直接断言。
+ */
+import { formatBudgetLine, formatConservationLine, formatEntrustmentConservationLine, formatStatusLine, formatSupervisorSummary, } from "./supervisor-state.js";
+/** 毫秒 → `MM-DD HH:mm:ss`（本地时区）。 */
+function fmtTime(ts) {
+    const d = new Date(ts);
+    const p = (n) => String(n).padStart(2, "0");
+    return `${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+/**
+ * 渲染监督面板的行（**只读**：没有任何可点的操作）。
+ *
+ * @param state 同一份聚合状态（Web 面用的是同一个对象来源）。
+ * @param opts 显示条数上限。
+ */
+export function formatSupervisorPanel(state, opts = {}) {
+    const timelineLimit = opts.timelineLimit ?? 10;
+    const trustLimit = opts.trustLimit ?? 10;
+    const blockerLimit = opts.blockerLimit ?? 10;
+    const lines = [];
+    lines.push("监督面（只读 · 改配置请回 Pi 会话）");
+    lines.push(`状态  ${formatSupervisorSummary(state)}`);
+    lines.push(`      ${formatStatusLine(state)}`);
+    const timeline = state.timeline.slice(Math.max(0, state.timeline.length - timelineLimit)).reverse();
+    lines.push(`时间线（最近 ${timeline.length} 条 · 会话正文只给长度/摘要）`);
+    if (timeline.length === 0) {
+        lines.push("      暂无记录");
+    }
+    else {
+        for (const t of timeline) {
+            const len = t.bodyLen === undefined ? "" : ` · 正文 ${t.bodyLen} 字`;
+            const digest = t.bodyDigest === undefined ? "" : ` · 摘要 ${t.bodyDigest}`;
+            const peer = t.peer === undefined ? "" : ` · 对端 ${t.peer}`;
+            lines.push(`      ${fmtTime(t.ts)}  ${t.summary}${len}${digest}${peer}`);
+        }
+    }
+    lines.push(`托付（${state.trusts.length}）`);
+    if (state.trusts.length === 0) {
+        lines.push("      暂无托付");
+    }
+    else {
+        for (const t of state.trusts.slice(0, trustLimit)) {
+            const human = t.needsHuman ? " · 需人决策" : "";
+            const reason = t.humanReason === undefined ? "" : ` · ${t.humanReason}`;
+            lines.push(`      ${t.target} · ${t.status}${human}${reason}`);
+        }
+    }
+    if (state.goals.length > 0) {
+        lines.push(`目标（${state.goals.length}）`);
+        for (const g of state.goals.slice(0, trustLimit)) {
+            const reason = g.humanReason === undefined ? "" : ` · ${g.humanReason}`;
+            lines.push(`      ${g.title} · ${g.status} · 推进 ${g.progressSteps} 步 · 行动 ${g.usedActions}/${g.maxActions}${reason}`);
+        }
+    }
+    lines.push(`阻塞（${state.blockers.length}）`);
+    if (state.blockers.length === 0) {
+        lines.push("      无阻塞");
+    }
+    else {
+        for (const b of state.blockers.slice(0, blockerLimit)) {
+            const detail = b.detail === undefined ? "" : ` · ${b.detail}`;
+            lines.push(`      ${b.title}${detail}`);
+        }
+    }
+    lines.push(`预算  ${formatBudgetLine(state)}`);
+    lines.push(`守恒  ${formatConservationLine(state)}`);
+    lines.push(`      ${formatEntrustmentConservationLine(state)}`);
+    return lines;
+}
+/**
+ * 非交互模式（json / print / rpc 无 TUI）下的**纯文本**呈现。
+ *
+ * 与面板**逐字同源**（同一份聚合 + 同一批文本构造）→ 监督信息不依赖 TUI 能力（验收 A10）。
+ */
+export function formatSupervisorText(state, opts = {}) {
+    return formatSupervisorPanel(state, opts).join("\n");
+}