pi-proactive 0.0.0-stage → 0.2.0-beta.3

package/build/src/idle.js

@@ -0,0 +1,388 @@
+import { resolveDecisionConfig } from "./config.js";
+/**
+ * **决策环**（brief-v4 §1.2 / §7 第 1 步）：把「固定 afterMs 定时器」换成
+ * `score = (value × urgency) / interruptionCost` 的**可打分、可复算、可归因**判定。
+ *
+ * - **三个分量都是显式输入**，来源全是**既有能力**（不许凭空发明业务语义）：
+ *   - `value` ← `activity.ts:ActivityTracker.snapshot().idleForMs`（距最近**任何**活动 → 系统空转程度 → 值不值得继续推进）；
+ *   - `urgency` ← `activity.ts:ActivityTracker.snapshot().lastUserActivityAt`（距最近**用户**活动 → 用户不在场的时长 → 有多急）；
+ *   - `interruptionCost` ← `guard.ts:Guard.remainingThisHour`（近 1 小时打扰次数）+ `activity.ts` 的 `busy` + `limits.quietHours`（值不值得打断）。
+ * - **缺省配置下与旧 `afterMs` 判定等价**：`value = idleForMs/afterMs`、`urgency = min(1, userIdleForMs/afterMs)`、
+ *   `interruptionCost = 1`（近 1 小时未重复打扰）→ `score >= 1` ⟺ `idleForMs >= afterMs`。
+ * - **每次决策都落账**（含不触发）→ 事件流里的 `decision` 事件（`/proactive history` 可见）。
+ *
+ * @capability: decide-ring
+ * @observable: pi-proactive/src/lineage.ts:formatLineageHistory
+ * @attribution: pi-proactive/src/idle.ts:scoreDecision
+ * @outcome: pi-proactive/src/lineage.ts:LineageOutcome → pi-proactive/src/lineage.ts:DEFAULT_OUTCOME_WINDOW_MS
+ * @checked: test:pi-proactive/tests/decide-ring.test.ts#可分辨：高分输入 → 触发；低分输入 → 不触发（分数不是常数）
+ */
+/**
+ * 空闲判定（任务卡 M2 §2.1；R2 修复：判定与投递解耦）。
+ *
+ * 规则来源：
+ * - 基线 = `lastUserActivityAt`（来自 ActivityTracker），**仅用户活动刷新**；
+ * - `idleForMs = now - lastUserActivityAt`；
+ * - 分档：`terminal`（仅 TUI） / `input-only` / `off`（非 TUI 默认档）；
+ * - 判定式：`enabled && idleTrigger.enabled && idleDetect !== "off" && !busy && idleForMs >= afterMs && guard.check() === "allow"`；
+ * - `guard.check()` 在这里只是**预判**（纯读，不改状态、不消耗额度）：判断「值不值得尝试投递」；
+ *   真正的判定与记账**唯一**发生在 Trigger 内部 → 本模块不得记账（否则额度扣减不确定，
+ *   且 askUser 路径的额度预留会重复扣减）。
+ * - 自触发抑制：插件自己注入的消息标 `mark("self")`，不刷新基线。
+ *
+ * 本模块**不实现投递**：只调用注入的 `Trigger.deliverToModel`（契约 §5），并按其返回的
+ * `DeliverOutcome` 决定「是否算已执行」。
+ */
+/**
+ * 空闲相关能力的**真实**开启方式（用户可见文案）。
+ *
+ * `/proactive idle on` 现已存在（内存态开关）→ 可以直接指引它；
+ * 配置文件是「重启后仍然生效」的那条路。两处都要如实给出，不得指引不存在的命令。
+ */
+export const IDLE_ENABLE_HINT = "开启方式：/proactive idle on（开启空闲触发；内存态，重启后回到配置文件值）" +
+    "或编辑配置文件 <agent-dir>/proactive/config.json（空闲触发：idleTrigger.enabled=true；空闲检测：idleDetect=\"terminal\" 或 \"input-only\"）。";
+/**
+ * 生效的空闲检测档位。
+ * `terminal` 只在 TUI 有效；其它模式降级为 `input-only`（保守模式，仍需用户输入事件刷新基线）。
+ */
+export function effectiveIdleDetect(configured, runtimeMode) {
+    if (configured === "off")
+        return "off";
+    if (configured === "terminal")
+        return runtimeMode === "tui" ? "terminal" : "input-only";
+    return "input-only";
+}
+/** 判断某时刻是否落在静默时段（跨零点，如 22:00-08:00）。 */
+export function isWithinQuietHours(qh, now) {
+    if (!qh)
+        return false;
+    const from = parseHm(qh.from);
+    const to = parseHm(qh.to);
+    if (from === undefined || to === undefined || from === to)
+        return false;
+    const d = new Date(now);
+    const cur = d.getHours() * 60 + d.getMinutes();
+    return from < to ? cur >= from && cur < to : cur >= from || cur < to;
+}
+function parseHm(v) {
+    const m = /^(\d{1,2}):(\d{2})$/.exec(v.trim());
+    if (!m)
+        return undefined;
+    const h = Number(m[1]);
+    const min = Number(m[2]);
+    if (!Number.isInteger(h) || !Number.isInteger(min) || h > 23 || min > 59)
+        return undefined;
+    return h * 60 + min;
+}
+/**
+ * **决策环的打分**（纯函数）：`score = (value × urgency) / interruptionCost`。
+ *
+ * - 三个分量是**显式输入**（各自带来源）→ 分数可**手工复算**；
+ * - `band` 只看分数：`trigger`（>= 阈值）/ `observe`（观察带）/ `skip`；
+ * - `decision` 是**最终**决策（由 `evaluateIdle` 叠加前置条件后写回）。
+ *
+ * 阈值与观察带都可配（`decision.threshold` / `decision.observeRatio`）。
+ */
+export function scoreDecision(inputs, threshold, observeRatio) {
+    // 代价下限：避免除零（代价是倍数，>= 1 恒成立；这里是纯函数的健壮性护栏）。
+    const cost = Math.max(inputs.interruptionCost.score, 1e-6);
+    const score = (inputs.value.score * inputs.urgency.score) / cost;
+    const band = score >= threshold ? "trigger" : observeRatio > 0 && score >= threshold * observeRatio ? "observe" : "skip";
+    return { ...inputs, score, threshold, band, decision: band };
+}
+/**
+ * 决策环的**输入构造**（三个分量的来源全是既有能力，见文件头的说明）。
+ *
+ * - `value` = `idleForMs / horizon`（`horizon = max(afterMs, 1)`）—— 距最近**任何**活动；
+ * - `urgency` = `min(1, userIdleForMs / horizon)` —— 距最近**用户**活动（用户不在场的时长）；
+ * - `interruptionCost` = `1 + 重复打扰权重 × max(0, 近 1 小时打扰次数 − 1) + 忙加成 + 静默加成`。
+ *
+ * 等价性（缺省配置）：无重复打扰（近 1 小时 <= 1 次）且不忙、不在静默期 → 代价 = 1 →
+ * `score = (idleForMs/afterMs) × min(1, userIdleForMs/afterMs) >= 1` ⟺ `idleForMs >= afterMs`
+ * （`userIdleForMs >= idleForMs` 恒成立：用户基线不晚于「任何活动」基线）。
+ */
+export function scoreIdleDecision(env, now, snap) {
+    const cfg = resolveDecisionConfig(env.config);
+    if (!cfg.enabled)
+        return undefined;
+    const afterMs = env.config.idleTrigger.afterMs;
+    // `afterMs <= 0` = 旧语义「立刻触发」（`idleForMs >= 0` 恒真）→ 价值/紧急度恒为 1（保持等价）。
+    const immediate = afterMs <= 0;
+    const horizon = immediate ? 1 : afterMs;
+    const userIdleForMs = Math.max(0, now - snap.lastUserActivityAt);
+    // 近 1 小时的打扰次数（护栏的既有账本；Guard 的频率窗口 = 1 小时）。
+    const recentCount = countRecentInterruptions(env.guard, now, env.config.limits.maxPerHour);
+    let cost = 1 + cfg.repeatedInterruptionWeight * Math.max(0, recentCount - 1);
+    if (snap.busy)
+        cost += cfg.busyInterruptionWeight;
+    if (isWithinQuietHours(env.config.limits.quietHours, now))
+        cost += cfg.quietInterruptionWeight;
+    const inputs = {
+        value: {
+            score: immediate ? 1 : snap.idleForMs / horizon,
+            source: "activity:ActivityTracker.snapshot().idleForMs",
+        },
+        urgency: {
+            score: immediate ? 1 : Math.min(1, userIdleForMs / horizon),
+            source: "activity:ActivityTracker.snapshot().lastUserActivityAt",
+        },
+        interruptionCost: {
+            score: cost,
+            source: "guard:Guard.remainingThisHour（近 1 小时打扰次数）· activity:snapshot().busy · limits:quietHours",
+        },
+    };
+    return scoreDecision(inputs, cfg.threshold, cfg.observeRatio);
+}
+/**
+ * 近 1 小时内的打扰次数（**护栏的既有账本**，不新增状态）。
+ *
+ * - 护栏暴露 `fireLog`（打扰时刻数组）→ 直接数窗口内的条数（**精确**）；
+ * - 只暴露 `remainingThisHour`（生产环境的 `Guard` 就是这种）→ `maxPerHour − 剩余额度`（同一本账的等价读法）。
+ *
+ * 两条路径读的是**同一本账** → 代价不会因为读法不同而漂移。
+ */
+function countRecentInterruptions(guard, now, maxPerHour) {
+    const log = guard.fireLog;
+    if (log !== undefined) {
+        const from = now - 3_600_000;
+        return log.filter((t) => t > from && t <= now).length;
+    }
+    const remaining = guard.remainingThisHour?.(now);
+    if (remaining === undefined)
+        return 0;
+    return Math.max(0, maxPerHour - remaining);
+}
+/** 空闲判定（纯函数，无副作用；`guard.check()` 为只读预判）。 */
+export function evaluateIdle(env) {
+    const now = env.now ? env.now() : Date.now();
+    const { config } = env;
+    const detect = effectiveIdleDetect(config.idleDetect, env.runtimeMode);
+    const snap = env.tracker.snapshot();
+    const idleForMs = snap.idleForMs;
+    const remainingMs = Math.max(0, config.idleTrigger.afterMs - idleForMs);
+    const decision = {
+        eligible: false,
+        reason: "disabled",
+        idleForMs,
+        remainingMs,
+        effectiveIdleDetect: detect,
+        intent: config.idleTrigger.intent,
+        askUser: config.idleTrigger.askUser === true,
+        maxPerHour: config.limits.maxPerHour,
+        ...(config.limits.quietHours ? { quietHours: config.limits.quietHours } : {}),
+    };
+    if (!config.enabled)
+        return decision;
+    if (!config.idleTrigger.enabled) {
+        decision.reason = "idle-trigger-disabled";
+        return decision;
+    }
+    if (detect === "off") {
+        decision.reason = "detect-off";
+        return decision;
+    }
+    // ---- 决策环：先算分（**即使不触发也要算**：不触发也要能回答「为什么」）----
+    const scoring = scoreIdleDecision(env, now, snap);
+    if (scoring !== undefined) {
+        decision.scoring = scoring;
+        decision.userIdleForMs = Math.max(0, now - snap.lastUserActivityAt);
+    }
+    if (snap.busy) {
+        decision.reason = "busy";
+        if (scoring !== undefined)
+            scoring.decision = "skip";
+        return decision;
+    }
+    // 预判：只读地问一次护栏「值不值得尝试投递」（不消耗额度、不改状态）。
+    // 真正的判定与记账在 Trigger 内部 → 即使这里放行，投递时仍可能被护栏推迟（deferred）。
+    const verdict = env.guard.check(now);
+    if (verdict !== "allow") {
+        const classified = classifyGuard(verdict, env, now);
+        decision.reason = classified.reason;
+        if (classified.cooldownRemainingMs !== undefined)
+            decision.cooldownRemainingMs = classified.cooldownRemainingMs;
+        if (scoring !== undefined)
+            scoring.decision = "skip";
+        return decision;
+    }
+    if (scoring === undefined) {
+        // 决策环关闭（`decision.enabled=false`）→ 完全走旧 afterMs 判定（等价回退）。
+        if (idleForMs < config.idleTrigger.afterMs) {
+            decision.reason = "threshold";
+            return decision;
+        }
+        decision.eligible = true;
+        decision.reason = "eligible";
+        return decision;
+    }
+    if (scoring.band !== "trigger") {
+        // 观察带：分数不足以打扰（只记一笔，不投递）；分数太低：直接不触发。
+        scoring.decision = scoring.band;
+        decision.reason = idleForMs < config.idleTrigger.afterMs ? "threshold" : "below-score";
+        return decision;
+    }
+    decision.eligible = true;
+    decision.reason = "eligible";
+    scoring.decision = "trigger";
+    return decision;
+}
+function classifyGuard(verdict, env, now) {
+    if (verdict === "drop")
+        return { reason: "rate-limit" };
+    // defer：可能是冷却 / 每小时上限 / 静默时段
+    const remaining = env.guard.remainingThisHour?.(now);
+    if (remaining === 0)
+        return { reason: "rate-limit" };
+    const lastFireAt = env.guard.lastFireAt ?? env.guard.fireLog?.[env.guard.fireLog.length - 1];
+    if (lastFireAt !== undefined) {
+        const left = env.config.limits.minGapMs - (now - lastFireAt);
+        if (left > 0)
+            return { reason: "cooldown", cooldownRemainingMs: left };
+    }
+    if (isWithinQuietHours(env.config.limits.quietHours, now))
+        return { reason: "quiet-hours" };
+    return { reason: "cooldown" };
+}
+/** 构造空闲触发的信封（裸 body —— 来源前缀唯一由 Trigger 添加，避免双前缀）。 */
+export function buildIdleEnvelope(args) {
+    const body = args.prompt.trim() || "用户已经离开一段时间；如果有未完成的任务请继续推进，否则等用户回来。";
+    return {
+        id: `idle-${args.now}`,
+        from: args.agentId,
+        to: args.agentId,
+        kind: args.askUser ? "ask" : "task",
+        intent: args.intent,
+        subject: "空闲触发",
+        body,
+        hop: 0,
+        maxHops: 1,
+        ttlMs: 60000,
+        priority: "normal",
+        createdAt: args.now,
+    };
+}
+/**
+ * 空闲触发：判定（预判）→ 投递 → **await 最终 outcome 后决策**。
+ *
+ * 本模块**不记账**：护栏记账唯一归 Trigger（内部），否则会出现两次扣减、
+ * 且 askUser 路径会在用户回答后被护栏丢弃（用户回答被静默丢弃的根因）。
+ *
+ * 投递异常整体隔离（宿主对未捕获异常直接 `process.exit(1)`）。
+ *
+ * 返回值是**纯 Promise**：调用方 `await` 之后拿到最终结果（判定 / fired / error）。
+ * （旧实现曾在 Promise 上挂 `.decision` 作为同步句柄，那是入口 tick 还是同步时的兼容垫片；
+ * 入口已改为 `void fireIdle(...).then(...)`，垫片已删除。）
+ */
+export function fireIdle(env) {
+    const now = env.now ? env.now() : Date.now();
+    const decision = evaluateIdle({ config: env.config, tracker: env.tracker, guard: env.guard, runtimeMode: env.runtimeMode, now: () => now });
+    // **决策落账**（含「不触发」）：没有这条记录就无法回答「为什么它没理我」。
+    noteDecision(env, decision);
+    return runIdleFire(env, decision, now);
+}
+/**
+ * 把一次决策落进事件流（`decision` 事件）。
+ *
+ * 落什么：分数 / 三个分量 + 各自来源 / 阈值 / 决策（触发·观察·不触发）/ 原因 /
+ * 空闲时长与用户静默时长 → **为什么现在 · 为什么这个动作 · 代价多少**。
+ *
+ * 不抛错（事件流写失败不得影响投递语义）；写失败由 `Lineage` 内部兜底。
+ */
+function noteDecision(env, decision) {
+    const scoring = decision.scoring;
+    const lineage = env.lineage;
+    if (scoring === undefined || lineage === undefined)
+        return;
+    const record = {
+        decision: scoring.decision,
+        reason: decision.reason,
+        score: scoring.score,
+        value: scoring.value.score,
+        urgency: scoring.urgency.score,
+        interruptionCost: scoring.interruptionCost.score,
+        threshold: scoring.threshold,
+        valueSource: scoring.value.source,
+        urgencySource: scoring.urgency.source,
+        interruptionCostSource: scoring.interruptionCost.source,
+        idleForMs: decision.idleForMs,
+        userIdleForMs: decision.userIdleForMs ?? 0,
+    };
+    try {
+        lineage.noteDecision({ cause: "idle", decision: record });
+    }
+    catch (err) {
+        console.error("[proactive] 决策落账失败", err);
+    }
+}
+/** 空闲触发的实际执行：投递 → await 最终 outcome → 决策（异常整体隔离，不冒泡）。 */
+async function runIdleFire(env, decision, now) {
+    let envelope;
+    try {
+        if (!decision.eligible)
+            return { fired: false, decision };
+        envelope = env.buildEnvelope
+            ? env.buildEnvelope(decision, now)
+            : buildIdleEnvelope({
+                agentId: env.agentId ?? "self",
+                prompt: env.config.idleTrigger.prompt,
+                intent: decision.intent,
+                askUser: decision.askUser,
+                now,
+            });
+        let outcome;
+        try {
+            // **决策必须基于最终 outcome**：await 之后才知道是不是真的投递了
+            // （askUser 路径：额度在开口提问时预留 → 回答到达后必定投递，不会被静默丢弃）。
+            outcome = await env.trigger.deliverToModel(envelope, decision.intent, { askUser: decision.askUser });
+        }
+        catch (err) {
+            decision.reason = "deliver-failed";
+            decision.outcome = "failed";
+            return { fired: false, decision, envelope, error: errText(err) };
+        }
+        decision.outcome = outcome;
+        switch (outcome) {
+            case "delivered":
+            case "notified": {
+                // 已执行（模型接手 / 用户已被告知）。
+                // 自触发抑制：插件自己注入的消息不刷新空闲基线。
+                try {
+                    env.tracker.mark("self");
+                }
+                catch {
+                    /* 标记失败不得让宿主崩溃 */
+                }
+                return { fired: true, decision, envelope };
+            }
+            case "deferred": {
+                // 被护栏推迟 → 未执行：原因按护栏状态归类（冷却 / 静默时段 / 超上限）。
+                const classified = classifyGuard("defer", env, now);
+                decision.reason = classified.reason;
+                if (classified.cooldownRemainingMs !== undefined)
+                    decision.cooldownRemainingMs = classified.cooldownRemainingMs;
+                return { fired: false, decision, envelope };
+            }
+            case "dropped": {
+                // 超频率上限 → 未执行。
+                decision.reason = "rate-limit";
+                return { fired: false, decision, envelope };
+            }
+            case "failed": {
+                // 投递异常 → 未执行（Trigger 内部已隔离异常并留日志）。
+                decision.reason = "deliver-failed";
+                return { fired: false, decision, envelope, error: "投递失败（详见 Trigger 日志）" };
+            }
+            default:
+                return { fired: false, decision, envelope };
+        }
+    }
+    catch (err) {
+        // 整体隔离：宿主对未捕获异常直接 process.exit(1)
+        decision.reason = "deliver-failed";
+        decision.outcome = "failed";
+        return { fired: false, decision, envelope, error: errText(err) };
+    }
+}
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}