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

package/build/src/scheduler.js

@@ -0,0 +1,301 @@
+const DEFAULT_DEFER_MS = 300_000;
+const DEFAULT_TICK_MS = 1_000;
+/** repeat 任务未给 intervalMs 时的兜底周期。 */
+const DEFAULT_REPEAT_INTERVAL_MS = 60_000;
+/**
+ * 定时调度器：每 tick 扫一遍任务表，把到期任务投递给模型。
+ *
+ * 生命周期：`start()` 起 1s 定时器（只能在宿主 session_start 调用），
+ * `stop()` 幂等清理（宿主 session_shutdown 调用）。
+ *
+ * 决策依据（R2 修复）：调度器**不判定也不记账护栏** —— 投递结果由 Trigger 返回：
+ * - `delivered` / `notified` → 已执行 → once 删除 / repeat 顺延 intervalMs；
+ * - `deferred` → 未执行 → dueAt 顺延 deferMs；
+ * - `dropped` → 未执行 → 禁用该任务并记录原因；
+ * - `failed` → 未执行 → dueAt 顺延 deferMs（重试）并记录错误。
+ *
+ * 异常隔离：tick 整体 try/catch，单个任务失败只跳过该任务 —— 宿主
+ * `uncaughtException → process.exit(1)`，定时器里冒泡会直接杀进程。
+ */
+export class Scheduler {
+    opts;
+    now;
+    deferMs;
+    tickMs;
+    timer;
+    constructor(opts) {
+        this.opts = opts;
+        this.now = opts.now ?? Date.now;
+        this.deferMs = opts.deferMs ?? DEFAULT_DEFER_MS;
+        this.tickMs = opts.tickIntervalMs ?? DEFAULT_TICK_MS;
+    }
+    /** 起定时 tick（幂等：已在跑则不重复起）。 */
+    start() {
+        if (this.timer !== undefined)
+            return;
+        this.timer = setInterval(() => {
+            void this.tick();
+        }, this.tickMs);
+        // 定时器不应单独吊住宿主进程
+        this.timer.unref?.();
+    }
+    /** 停定时 tick（幂等）。 */
+    stop() {
+        if (this.timer === undefined)
+            return;
+        clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    /** 执行一次调度（测试可直接调用；异常不冒泡、不 reject）。 */
+    async tick(now = this.now()) {
+        try {
+            await this.runTick(now);
+        }
+        catch (err) {
+            this.log(`tick 失败：${errText(err)}`);
+        }
+    }
+    // ---- 内部实现 ----
+    async runTick(now) {
+        const tasks = this.opts.store.list();
+        for (const task of tasks) {
+            try {
+                await this.processTask(task, now);
+            }
+            catch (err) {
+                // 单个任务失败不影响其它任务
+                this.log(`任务 ${task.id} 处理失败：${errText(err)}`);
+            }
+        }
+    }
+    async processTask(task, now) {
+        if (!task.enabled)
+            return;
+        // 主动性总开关关闭（/proactive off）→ 不投递（任务保留，重新开启后仍可投递）。
+        if (this.opts.enabled?.() === false)
+            return;
+        if (task.dueAt > now)
+            return;
+        // session 作用域：只有**归属会话**才处理（会话优先，旧任务按进程兜底）
+        if (task.scope === "session" && !this.ownsSessionTask(task))
+            return;
+        // global 作用域：必须先原子认领，认领失败（他人已认领）则跳过
+        if (task.scope === "global" && !this.opts.store.claimIfGlobal(task, this.opts.agentId))
+            return;
+        const envelope = this.buildEnvelope(task, now);
+        let outcome;
+        try {
+            // **决策必须基于最终 outcome**：await 之后才知道任务是不是真的被投递了。
+            // 排期投递的 askUser 只来自**任务自身**（显式登记才问）；
+            // 任务创建时不再继承 idleTrigger.askUser（M5c RP-11 M-2：定时任务不得被静默
+            // 改造成「弹框提问任务」）。
+            outcome = await this.opts.trigger.deliverToModel(envelope, task.intent, { askUser: task.askUser });
+        }
+        catch (err) {
+            outcome = "failed";
+            this.log(`任务 ${task.id} 投递异常：${errText(err)}`);
+        }
+        switch (outcome) {
+            case "delivered":
+            case "notified": {
+                // 已执行（模型接手 / 用户已被告知）
+                if (task.schedule === "repeat") {
+                    this.opts.store.update(task.id, {
+                        // 节拍锚定**声明时刻**（prevDueAt + intervalMs），不按实际触发时刻重算
+                        // （M5c RP-11 M-1：成功路径与 defer 路径口径统一，避免触发延迟逐轮漂移）。
+                        dueAt: this.nextRepeatDueAt(task.dueAt, task.intervalMs ?? DEFAULT_REPEAT_INTERVAL_MS, now),
+                        lastFiredAt: now,
+                        fireCount: task.fireCount + 1,
+                    });
+                }
+                else {
+                    this.opts.store.remove(task.id);
+                }
+                return;
+            }
+            case "deferred": {
+                // 未执行：被护栏推迟 → 顺延（静默时段/冷却由 Trigger 侧的护栏负责，调度器只做顺延）
+                // 顺延不得改写用户声明的节拍：repeat 任务保 `prevDueAt + intervalMs`（且不早于冷却结束）。
+                const dueAt = this.nextDueAt(task, now);
+                this.opts.store.update(task.id, { dueAt });
+                this.log(`任务 ${task.id} 投递被护栏推迟，顺延到 ${dueAt}`);
+                return;
+            }
+            case "dropped": {
+                // 未执行：本小时丢弃 → 禁用该任务并记录原因（不再自动恢复）
+                this.opts.store.update(task.id, { enabled: false });
+                this.log(`任务 ${task.id} 超出频率上限被丢弃，已禁用`);
+                return;
+            }
+            case "failed": {
+                // 未执行：投递失败 → 顺延重试（任务保持启用，节拍同 deferred）
+                const dueAt = this.nextDueAt(task, now);
+                this.opts.store.update(task.id, { dueAt });
+                this.log(`任务 ${task.id} 投递失败，顺延到 ${dueAt} 重试`);
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    /**
+     * `scope:"session"` 任务的归属判定（**会话优先，进程兜底**）。
+     *
+     * - 任务带 `ownerSessionId` 且本进程有 `sessionId` → 按**会话**比对（跨进程重启稳定）；
+     * - 任务带 `ownerSessionId` 但本进程无 `sessionId` → 无法按会话判定 → 退回进程归属并记录日志；
+     * - 任务**没有** `ownerSessionId`（旧任务）→ 按进程归属（`ownerAgentId`）兜底并记录日志。
+     */
+    ownsSessionTask(task) {
+        const raw = task.ownerSessionId;
+        const ownerSessionId = typeof raw === "string" && raw !== "" ? raw : undefined;
+        const mySessionId = typeof this.opts.sessionId === "string" && this.opts.sessionId !== "" ? this.opts.sessionId : undefined;
+        if (ownerSessionId !== undefined && mySessionId !== undefined) {
+            return ownerSessionId === mySessionId;
+        }
+        const byAgent = task.ownerAgentId === this.opts.agentId;
+        if (byAgent) {
+            this.log(ownerSessionId !== undefined
+                ? `任务 ${task.id} 有会话归属但本进程无 sessionId → 按进程归属兜底投递`
+                : `任务 ${task.id} 无会话归属（旧任务）→ 按进程归属兜底投递`);
+        }
+        return byAgent;
+    }
+    /**
+     * 周期任务的下一个到期时刻（**锚定声明节拍**）。
+     *
+     * 口径（M5c RP-11 M-1）：`prevDueAt + intervalMs` —— 与 defer 路径同源；
+     * 触发延迟不得逐轮累积成节拍漂移。
+     *
+     * 若按声明节拍算出的时刻已经落在过去（本轮触发延迟超过了一个周期），
+     * 则**按声明节拍整周期跳过**到第一个尚未到来的时刻（不回到 `now + intervalMs`，
+     * 也不在原地反复触发）。
+     */
+    nextRepeatDueAt(prevDueAt, intervalMs, now) {
+        const next = prevDueAt + intervalMs;
+        if (next > now)
+            return next;
+        const skipped = Math.floor((now - prevDueAt) / intervalMs) + 1;
+        return prevDueAt + skipped * intervalMs;
+    }
+    /**
+     * 未执行（deferred / failed）时的下一次到期时刻。
+     *
+     * repeat 任务：**保持用户声明的节拍** → 与**成功路径同源**（Minor-1）：
+     * 节拍由**同一个函数**算出（`nextRepeatDueAt`：`prevDueAt + intervalMs`，落后则整周期跳过），
+     * 再取「不早于冷却结束」的下界 → 两条路径的**节拍口径一致**，
+     * 差异只剩**显式的冷却下界**（护栏要求等到冷却结束；这一条被 `tests/scheduler.test.ts` 锁定）。
+     * once 任务：`now + deferMs`。
+     */
+    nextDueAt(task, now) {
+        const deferredAt = now + this.deferMs;
+        if (task.schedule === "repeat" && task.intervalMs !== undefined) {
+            const cadence = this.nextRepeatDueAt(task.dueAt, task.intervalMs, now);
+            return Math.max(cadence, deferredAt);
+        }
+        return deferredAt;
+    }
+    /** 投递用 envelope；body 是裸内容 —— 来源前缀由 Trigger 唯一负责（避免双前缀）。 */
+    buildEnvelope(task, now) {
+        return {
+            id: task.id,
+            from: this.opts.agentId,
+            to: "self",
+            kind: "task",
+            intent: task.intent,
+            subject: task.prompt,
+            body: task.prompt,
+            hop: 0,
+            maxHops: 1,
+            ttlMs: 60_000,
+            priority: "normal",
+            createdAt: now,
+        };
+    }
+    log(msg) {
+        if (this.opts.logger) {
+            this.opts.logger(msg);
+            return;
+        }
+        console.warn(`[proactive] ${msg}`);
+    }
+}
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+// ---- 排期表达式解析（用户命令面与模型工具共用同一套） ----
+/** 支持的时长格式（错误文案与命令说明的唯一出处）。 */
+export const SUPPORTED_DURATION_FORMATS = "30s（秒）/ 10m（分）/ 2h（小时）/ 1d（天），或纯数字（按秒计）";
+/** 支持的触发时间格式（时长 + HH:MM + ISO 绝对时间）。 */
+export const SUPPORTED_WHEN_FORMATS = `${SUPPORTED_DURATION_FORMATS}、HH:MM（如 18:30）、ISO 时间（如 2026-10-24T09:00:00Z）`;
+/** 未指定触发时间时的默认时长（10 分钟）。 */
+export const DEFAULT_WHEN_MS = 600_000;
+/** 时长表达式：纯数字（按秒）或 数字 + s/m/h/d。 */
+const DURATION_RE = /^(\d+)([smhd]?)$/i;
+/** 一天毫秒数（仅用于「顺延到明天」的兜底计算）。 */
+const DAY_MS = 86_400_000;
+/**
+ * 解析时长表达式：`30s` / `10m` / `2h` / `1d` / 纯数字（按秒）。
+ *
+ * 只支持这四种单位 —— `3w` / `1mo` 之类一律报错并列出支持格式（不静默猜测）。
+ */
+export function parseDurationMs(value) {
+    const s = value.trim();
+    if (s === "")
+        throw new Error(`时长不能为空。支持格式：${SUPPORTED_DURATION_FORMATS}。`);
+    const m = DURATION_RE.exec(s);
+    if (!m)
+        throw new Error(`无法识别的时长 "${value}"。支持格式：${SUPPORTED_DURATION_FORMATS}。`);
+    const n = Number(m[1]);
+    const unit = m[2] === "" ? "s" : m[2].toLowerCase();
+    const factor = unit === "s" ? 1_000 : unit === "m" ? 60_000 : unit === "h" ? 3_600_000 : DAY_MS;
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new Error(`时长必须大于 0（得到 "${value}"）。支持格式：${SUPPORTED_DURATION_FORMATS}。`);
+    }
+    return n * factor;
+}
+/**
+ * 解析「今天该时刻」（HH:MM，本地时区）：今天还没到 → 今天；已过 → 顺延到明天。
+ */
+export function parseClockTimeMs(value, now) {
+    const m = /^(\d{1,2}):(\d{2})$/.exec(value.trim());
+    if (!m)
+        throw new Error(`无法识别的时间 "${value}"。支持格式：${SUPPORTED_WHEN_FORMATS}。`);
+    const hours = Number(m[1]);
+    const minutes = Number(m[2]);
+    if (hours > 23 || minutes > 59) {
+        throw new Error(`时间 "${value}" 非法（应为 00:00-23:59）。支持格式：${SUPPORTED_WHEN_FORMATS}。`);
+    }
+    const base = new Date(now);
+    base.setHours(hours, minutes, 0, 0);
+    if (base.getTime() > now)
+        return { dueAt: base.getTime(), rolledToTomorrow: false };
+    // 今天该时刻已过 → 顺延到明天（用 setDate + setHours，避免夏令时下加 24h 不等于「明天同一时刻」）。
+    const next = new Date(base);
+    next.setDate(next.getDate() + 1);
+    next.setHours(hours, minutes, 0, 0);
+    return { dueAt: next.getTime(), rolledToTomorrow: true };
+}
+/**
+ * 解析触发时间表达式：
+ * - 时长（`10m`）→ dueAt = now + 时长；
+ * - 时刻（`18:30`）→ 今天该时刻，已过则顺延到明天；
+ * - 绝对时间（ISO）→ 该时刻；
+ * - 缺失/空 → 默认 10 分钟（form="default"）。
+ */
+export function parseScheduleExpression(input, now) {
+    const s = (input ?? "").trim();
+    if (s === "")
+        return { form: "default", dueAt: now + DEFAULT_WHEN_MS, durationMs: DEFAULT_WHEN_MS };
+    if (/^\d{1,2}:\d{2}$/.test(s)) {
+        const clock = parseClockTimeMs(s, now);
+        return { form: "clock", dueAt: clock.dueAt, rolledToTomorrow: clock.rolledToTomorrow };
+    }
+    if (DURATION_RE.test(s)) {
+        const ms = parseDurationMs(s);
+        return { form: "duration", dueAt: now + ms, durationMs: ms };
+    }
+    const absolute = Date.parse(s);
+    if (!Number.isNaN(absolute))
+        return { form: "absolute", dueAt: absolute };
+    throw new Error(`无法识别的触发时间 "${input}"。支持格式：${SUPPORTED_WHEN_FORMATS}。`);
+}