dsh-later 1.0.0 → 1.2.0

package/lib/presence.js

@@ -14,12 +14,25 @@
 /** 紧急窗口：下次触发在该窗口内时，badge 从 scheduled 升级为 urgent。 */
 export const PRESENCE_URGENT_WINDOW_MS = 5 * 60_000;
 /**
- * 归纳：取最早触发时刻 + 可解析数量。`every` 类任务在投影里携带推进后的
- * `scheduledAt`（下次触发点），与一次性任务同构参与排序。
+ * 归纳：取最早触发时刻 + 任务数量。
+ *
+ * ⚠️ **暂停项不得参与 `nextAt`**（这是一个真实缺陷的根因）。暂停 = 日志 delete +
+ * sidecar 留档；wire 里的 `scheduled_at` 是 `originalScheduledAt`（**原目标时刻**），
+ * 而该时刻在暂停时通常已成过去。若照常参与取最小值，侧栏会算出 `nextAt <= now`
+ * → 显示「有 N 条定时提醒已到期，等待发送」，但这其实是一条**已冻结、不会触发**的
+ * 提醒，用户看到的是自相矛盾的状态（实测复现）。
+ *
+ * 正确语义：暂停项**计入 `count`**（它确实是待办提醒），但**不参与 `nextAt`**
+ * ——它没有排定的触发时刻，只在恢复后才重新拥有。
+ *
+ * 全部都是暂停项时 `nextAt` 为 undefined：调用方据此显示中性的「已暂停」而非
+ * 「已到期」或"下次 X 分后"。
  */
 export function summarizeSchedules(schedules) {
     let nextAt;
+    let progressFrom;
     let count = 0;
+    let pausedCount = 0;
     for (const item of schedules ?? []) {
         const raw = item.scheduled_at ?? item.scheduledAt;
         if (raw === undefined)
@@ -28,10 +41,85 @@ export function summarizeSchedules(schedules) {
         if (!Number.isFinite(epoch))
             continue;
         count += 1;
-        if (nextAt === undefined || epoch < nextAt)
+        if (item.status === 'paused') {
+            pausedCount += 1;
+            continue; // 冻结项没有排定的触发时刻，不参与 nextAt
+        }
+        if (nextAt === undefined || epoch < nextAt) {
             nextAt = epoch;
+            // 窗口起点只跟随被选中的那一条；并列最早时保留先出现者的窗口。
+            progressFrom = windowStartOf(item, epoch);
+        }
+    }
+    if (count === 0)
+        return { count: 0, pausedCount: 0 };
+    // 字段用条件展开：无进度时不产生 `progressFrom: undefined`，保持既有
+    // deepEqual 测试与 wire 形状不变。
+    return nextAt === undefined
+        ? { count, pausedCount }
+        : { count, nextAt, pausedCount, ...(progressFrom !== undefined ? { progressFrom } : {}) };
+}
+/**
+ * 推导进度窗口的起点时刻（epoch ms）；无从推导时返回 `undefined`。
+ *
+ * 口径按优先级：
+ *  1. `window_seconds` —— 宿主/投影直接给的总窗口，最权威（暂停项的 wire 正是
+ *     用它携带"原 after 间隔"，见 projection.ts 的 `pausedWireItemOf`）。
+ *  2. 按 `kind` 推：`after` 用 `after_seconds`，`every` 用 `every_seconds`。
+ *     两者都是"从触发时刻往回推一整个窗口"，天然得到本周期起点。
+ *  3. `created_at` —— `at` 类型没有周期，只能拿任务创建时刻当起点。
+ *
+ * **推不出就返回 `undefined`**，绝不拿 `scheduledAt` 兜底：那会让 span 为 0，
+ * 进度恒为 100%，把"算不出来"伪装成"已经走完"。
+ */
+function windowStartOf(item, scheduledEpoch) {
+    const explicit = toFiniteSeconds(item.window_seconds ?? item.windowSeconds);
+    if (explicit !== undefined)
+        return scheduledEpoch - explicit * 1000;
+    const afterSec = toFiniteSeconds(item.after_seconds ?? item.afterSeconds);
+    const everySec = toFiniteSeconds(item.every_seconds ?? item.everySeconds);
+    const span = item.kind === 'every' ? everySec : (afterSec ?? everySec);
+    if (span !== undefined)
+        return scheduledEpoch - span * 1000;
+    const created = toEpochMs(item.created_at) ?? toEpochMs(item.createdAt);
+    if (created !== null)
+        return created;
+    return undefined;
+}
+/** 秒数归一：只接受有限正数（0 / 负数 / NaN 一律视为"没给"）。 */
+function toFiniteSeconds(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+/** epoch ms（number）或 ISO 字符串统一成 epoch ms；无法解析返回 `null`。 */
+function toEpochMs(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === 'string' && value.length > 0) {
+        const parsed = Date.parse(value);
+        return Number.isFinite(parsed) ? parsed : null;
     }
-    return nextAt === undefined ? { count: 0 } : { count, nextAt };
+    return null;
+}
+/**
+ * 进度环比例（0–1）：`now` 在 `[progressFrom, nextAt]` 中的位置。
+ *
+ * 返回 `undefined` 表示**无从算起**（缺窗口起点，或窗口已退化），调用方此时应
+ * 退回「恒定整环」的旧表现，而不是画一个 0% 的空环 —— 后者是错误信息：
+ * 0% 是"刚开始"，`undefined` 是"算不出来"。
+ *
+ * 两端夹住：`overdue` 时 `now > nextAt`，环停在满环而不是绕出去。
+ */
+export function progressOf(entry, now) {
+    const { nextAt, progressFrom } = entry;
+    if (nextAt === undefined || progressFrom === undefined)
+        return undefined;
+    const span = nextAt - progressFrom;
+    if (!(span > 0))
+        return undefined;
+    const ratio = (now - progressFrom) / span;
+    if (!Number.isFinite(ratio))
+        return undefined;
+    return ratio <= 0 ? 0 : ratio >= 1 ? 1 : ratio;
 }
 /** 由当前时刻判定 badge 状态。 */
 export function badgeStateFor(nextAt, now) {
@@ -44,6 +132,36 @@ export function badgeStateFor(nextAt, now) {
         return 'urgent';
     return 'scheduled';
 }
+/**
+ * 悬浮卡片状态行的完整文案（与宿主 `.hoverStatus` 行同构：一个状态点 + 一句
+ * 描述）。宿主的状态链对定时任务无感知，本插件**只追加**这样一行，不改写也
+ * 不替换宿主已有的 `空闲` / `进行中` 等行，因此既有状态优先级天然不变。
+ *
+ * @param entry - 该会话的定时概要（调用方保证 count > 0）。
+ * @param now - 当前时刻（epoch ms），用于判定 overdue 与相对时间。
+ * @param labels - 相对时间文案槽位。
+ * @param strings - 当前语言的字典。
+ * @param formatHhmm - 时钟面格式化（注入以便单测）。
+ * @param formatDate - 日期面格式化（注入以便单测）。
+ * @returns 状态文案 + 视觉状态（`done` 为中性信息态，与宿主同款状态点）。
+ */
+export function hoverScheduleStatus(entry, now, labels, strings, formatHhmm, formatDate) {
+    const tone = badgeStateFor(entry.nextAt, now);
+    // 全部暂停：没有排定时刻 → 既不是「下次 X」也不是「已到期」（暂停项不会自行触发）。
+    if (entry.nextAt === undefined && entry.pausedCount > 0) {
+        const paused = strings.hoverSchedulePaused ?? strings.hoverScheduleOverdue;
+        return { label: formatTemplate(paused, { n: entry.count }), tone };
+    }
+    if (tone === 'overdue' || entry.nextAt === undefined) {
+        return { label: formatTemplate(strings.hoverScheduleOverdue, { n: entry.count }), tone };
+    }
+    const time = relativeFireLabel(entry.nextAt, now, labels, formatHhmm, formatDate);
+    return { label: formatTemplate(strings.hoverScheduleStatus, { n: entry.count, time }), tone };
+}
+/** `{name}` 占位符替换（与 client/strings 的 format 同语义；此处零依赖）。 */
+function formatTemplate(template, params) {
+    return template.replace(/\{(\w+)\}/g, (match, key) => key in params ? String(params[key]) : match);
+}
 function startOfDay(epoch) {
     const d = new Date(epoch);
     d.setHours(0, 0, 0, 0);

package/lib/projection.js

@@ -16,7 +16,7 @@
 import { z } from 'zod';
 import { decodeScheduleChange, resolveEveryOccurrence } from '@deepseek-ai/dsh-schedule';
 import { OWNED_EVENT, PROJECTION_KEY } from './domain.js';
-import { allOwnership, hasOwnership } from './ownership-store.js';
+import { allOwnership, allPaused, findPausedByScheduleId, getOwnership, hasOwnership, } from './ownership-store.js';
 /** 单条 wire 项 schema。 */
 const wireItemSchema = z
     .object({
@@ -28,6 +28,11 @@ const wireItemSchema = z
     scheduled_at: z.string(),
     created_at: z.string().optional(),
     delivery_mode: z.literal('session-local'),
+    status: z.union([z.literal('active'), z.literal('paused')]).optional(),
+    remaining_seconds: z.number().optional(),
+    paused_at: z.string().optional(),
+    schedule_id: z.string().optional(),
+    window_seconds: z.number().optional(),
 })
     .strict();
 /** 投影 wire 值 schema（wire.viewSchema：离开宿主前校验客户端载荷）。 */
@@ -53,6 +58,17 @@ const scheduleRecordStateSchema = z
     createdAt: z.number().optional(),
 })
     .passthrough();
+const pausedStateSchema = z.object({
+    uid: z.string(),
+    prompt: z.string(),
+    delivery: z.union([z.literal('context'), z.literal('user')]),
+    kind: z.literal('after'),
+    remainingSeconds: z.number(),
+    originalScheduledAt: z.string(),
+    originalAfterSeconds: z.number().optional(),
+    lastScheduleId: z.string(),
+    pausedAt: z.number(),
+});
 export const userSchedulesStateSchema = z.object({
     /** 会话 id（init 由 header 注入；apply 据此查询所有权 sidecar 缓存）。 */
     sessionId: z.string(),
@@ -62,24 +78,73 @@ export const userSchedulesStateSchema = z.object({
     active: z.array(scheduleRecordStateSchema),
     /** 已见 `session/end-seed` 的 seq；更早的继承前缀一律忽略。 */
     seedSeq: z.number(),
+    /** sidecar 暂停留档镜像（v4）。 */
+    paused: z.array(pausedStateSchema).default([]),
 });
+function pausedFromSidecar(sessionId) {
+    if (sessionId.length === 0)
+        return [];
+    return Object.values(allPaused(sessionId));
+}
 /** 初始状态：按会话 id 从所有权 sidecar 装载（进程重启后恢复 GUI 归属）。 */
 export function initUserScheduleProjection(header) {
     const sessionId = typeof header?.id === 'string' && header.id.length > 0 ? header.id : '';
     const entries = sessionId.length > 0 ? allOwnership(sessionId) : {};
-    return { sessionId, owned: Object.keys(entries), active: [], seedSeq: -1 };
+    return {
+        sessionId,
+        owned: Object.keys(entries),
+        active: [],
+        seedSeq: -1,
+        paused: pausedFromSidecar(sessionId),
+    };
 }
-/** 序列化一条活动记录为 wire 项（不含随墙钟变化的状态）。 */
-function wireItemOf(record) {
+/** 序列化一条活动记录为 wire 项（id 优先稳定 uid）。 */
+function wireItemOf(record, sessionId) {
+    const ownership = sessionId.length > 0 ? getOwnership(sessionId, record.id) : undefined;
+    const uid = ownership?.uid;
+    const windowSeconds = ownership?.windowSeconds;
+    // 0.1.7 的 `ScheduleRecord` 联合含 daily/weekly/cron，本插件的 wire 契约
+    // （`UserScheduleWireItem.kind`）仍只认 after/at/every —— 这三个变体只可能
+    // 来自其他插件写入的日志。归一为 `every`（与编辑路径的 300s 默认一致），
+    // 避免把未知 kind 泄漏到客户端。
+    //
+    // 字段读取按 `record.kind` 而非归一后的 `kind`：只有前者能让 TS 对判别式
+    // 联合收窄，从而确认 `afterSeconds` / `everySeconds` 存在。
+    const kind = record.kind === 'after' || record.kind === 'at' ? record.kind : 'every';
+    const everySeconds = record.kind === 'every' && typeof record.everySeconds === 'number'
+        ? record.everySeconds
+        : undefined;
     return {
-        id: record.id,
-        kind: record.kind,
+        id: uid ?? record.id,
+        kind,
         prompt: record.prompt,
         ...(record.kind === 'after' ? { after_seconds: record.afterSeconds } : {}),
-        ...(record.kind === 'every' ? { every_seconds: record.everySeconds } : {}),
+        ...(everySeconds !== undefined ? { every_seconds: everySeconds } : {}),
         ...(typeof record.createdAt === 'number' ? { created_at: new Date(record.createdAt).toISOString() } : {}),
+        ...(record.kind === 'after' && typeof windowSeconds === 'number'
+            ? { window_seconds: windowSeconds }
+            : {}),
         scheduled_at: record.scheduledAt,
         delivery_mode: 'session-local',
+        status: 'active',
+        schedule_id: record.id,
+    };
+}
+function pausedWireItemOf(entry) {
+    const windowSec = entry.originalAfterSeconds ?? entry.remainingSeconds;
+    return {
+        id: entry.uid,
+        kind: 'after',
+        prompt: entry.prompt,
+        // 进度条总窗口用原 after 间隔；remaining 单独给冻结剩余
+        after_seconds: windowSec,
+        window_seconds: windowSec,
+        scheduled_at: entry.originalScheduledAt,
+        delivery_mode: 'session-local',
+        status: 'paused',
+        remaining_seconds: entry.remainingSeconds,
+        paused_at: new Date(entry.pausedAt).toISOString(),
+        schedule_id: entry.lastScheduleId,
     };
 }
 /** 对 `every` dispatch 推进 scheduledAt（与 dsh-schedule dispatchedRecord 一致）。 */
@@ -97,14 +162,24 @@ function advanceEvery(record, acceptedAt) {
 export function applyUserScheduleProjection(state, event) {
     // 派生会话边界：重置自身，忽略继承前缀（AC-07 fork 隔离）。
     if (event.type === 'session/end-seed') {
-        if (state.seedSeq === event.seq && state.owned.length === 0 && state.active.length === 0)
+        if (state.seedSeq === event.seq &&
+            state.owned.length === 0 &&
+            state.active.length === 0 &&
+            state.paused.length === 0) {
             return state;
+        }
         // 派生会话（fork）：sidecar 以 sessionId 隔离，派生 id 天然空表；此处再清一次
         // 兜底「同 id 重播种」场景，保持 AC-07 语义。
         const owned = state.sessionId.length > 0
             ? Object.keys(allOwnership(state.sessionId))
             : [];
-        return { sessionId: state.sessionId, owned, active: [], seedSeq: event.seq };
+        return {
+            sessionId: state.sessionId,
+            owned,
+            active: [],
+            seedSeq: event.seq,
+            paused: pausedFromSidecar(state.sessionId),
+        };
     }
     if (seedIsBefore(state, event))
         return state;
@@ -115,7 +190,13 @@ export function applyUserScheduleProjection(state, event) {
         if (data.operation === 'add') {
             if (state.owned.includes(data.id))
                 return state;
-            return { sessionId: state.sessionId, owned: [...state.owned, data.id], active: state.active, seedSeq: state.seedSeq };
+            return {
+                sessionId: state.sessionId,
+                owned: [...state.owned, data.id],
+                active: state.active,
+                seedSeq: state.seedSeq,
+                paused: state.paused,
+            };
         }
         if (data.operation === 'remove') {
             if (!state.owned.includes(data.id))
@@ -125,6 +206,7 @@ export function applyUserScheduleProjection(state, event) {
                 owned: state.owned.filter((id) => id !== data.id),
                 active: state.active,
                 seedSeq: state.seedSeq,
+                paused: state.paused,
             };
         }
         return state;
@@ -146,10 +228,14 @@ export function applyUserScheduleProjection(state, event) {
                 if (!owned.includes(record.id) && state.sessionId.length > 0 && hasOwnership(state.sessionId, record.id)) {
                     owned = [...owned, record.id];
                 }
+                // resume：同 uid 的暂停项应在 create 后从 paused 列表消失
+                const paused = state.sessionId.length > 0
+                    ? pausedFromSidecar(state.sessionId)
+                    : state.paused;
                 // 固化创建时刻（事件 time），供客户端进度条按真实起点计算
                 const withCreated = typeof event.time === 'number' ? { ...record, createdAt: event.time } : record;
                 const existing = state.active.find((entry) => entry.id === record.id);
-                if (existing === withCreated && owned === state.owned)
+                if (existing === withCreated && owned === state.owned && paused === state.paused)
                     return state;
                 return {
                     sessionId: state.sessionId,
@@ -158,18 +244,39 @@ export function applyUserScheduleProjection(state, event) {
                         ? [...state.active, withCreated]
                         : state.active.map((entry) => (entry.id === record.id ? withCreated : entry)),
                     seedSeq: state.seedSeq,
+                    paused,
                 };
             }
             case 'delete': {
-                if (!state.active.some((entry) => entry.id === change.id) && !state.owned.includes(change.id))
+                if (!state.active.some((entry) => entry.id === change.id) && !state.owned.includes(change.id)) {
+                    // 仍可能要把 sidecar 暂停项挂进视图（pause 刚写完留档）
+                    if (state.sessionId.length > 0) {
+                        const paused = pausedFromSidecar(state.sessionId);
+                        const linked = findPausedByScheduleId(state.sessionId, change.id) !== undefined;
+                        if (linked && paused !== state.paused) {
+                            return {
+                                sessionId: state.sessionId,
+                                owned: state.owned.filter((id) => id !== change.id),
+                                active: state.active.filter((entry) => entry.id !== change.id),
+                                seedSeq: state.seedSeq,
+                                paused,
+                            };
+                        }
+                    }
                     return state;
+                }
                 // 删除即撤销所有权声明（sidecar 由工具路径在 flush 后清理；此处先清视图）。
                 const owned = state.owned.filter((id) => id !== change.id);
+                const active = state.active.filter((entry) => entry.id !== change.id);
+                const paused = state.sessionId.length > 0 ? pausedFromSidecar(state.sessionId) : state.paused;
+                if (owned === state.owned && active === state.active && paused === state.paused)
+                    return state;
                 return {
                     sessionId: state.sessionId,
                     owned,
-                    active: state.active.filter((entry) => entry.id !== change.id),
+                    active,
                     seedSeq: state.seedSeq,
+                    paused,
                 };
             }
             case 'dispatch': {
@@ -193,7 +300,13 @@ export function applyUserScheduleProjection(state, event) {
                 }
                 if (nextActive === state.active)
                     return state;
-                return { sessionId: state.sessionId, owned: state.owned, active: nextActive, seedSeq: state.seedSeq };
+                return {
+                    sessionId: state.sessionId,
+                    owned: state.owned,
+                    active: nextActive,
+                    seedSeq: state.seedSeq,
+                    paused: state.paused,
+                };
             }
             /* c8 ignore next 2 -- decodeScheduleChange 是闭包联合 */
             default:
@@ -205,13 +318,29 @@ export function applyUserScheduleProjection(state, event) {
 function seedIsBefore(state, event) {
     return state.seedSeq >= 0 && typeof event.seq === 'number' && event.seq < state.seedSeq;
 }
-/** 投影 view：只暴露用户创建的、当前活动的记录。 */
+/**
+ * 投影 view：活动 + 暂停（同列表；paused 靠 status 区分，dock 原地冻结）。
+ *
+ * ⚠️ 这里是**唯一**能让「删除暂停项」生效的地方。原因链：
+ *  - 删除暂停项只清 sidecar、**不写会话事件**（补写 `schedule/change` delete 会
+ *    因为该 id 在 pause 时已被删除而抛 `targets inactive id`，把日志读坏）；
+ *  - 投影 cell 只在事件到达时由 `apply` 推进，且跨进程持久化（projcache），
+ *    客户端又按 seq「更高者胜」消费控制帧——没有新事件就没有新帧；
+ *  - 于是 `state.paused` 会永久停留在最后一次事件时的快照上。
+ * 因此 view 不能直接信任 `state.paused`，必须**以 sidecar 为准重读**：
+ * sidecar 是暂停留档的权威存储（`ownship-store`），`state.paused` 只是镜像。
+ * 这样无论 cell 多陈旧，读出来的 paused 列表都与真实留档一致。
+ */
 export function viewUserScheduleProjection(state) {
-    const schedules = state.active
+    const active = state.active
         .filter((record) => state.owned.includes(record.id))
         .sort((a, b) => Date.parse(a.scheduledAt) - Date.parse(b.scheduledAt))
-        .map(wireItemOf);
-    return { schedules };
+        .map((record) => wireItemOf(record, state.sessionId));
+    // sidecar 权威：readFresh 带缓存但会按文件 mtime/内容失效，读到的是最新留档。
+    // sessionId 缺失（init 未注入）时退回镜像，保持旧行为。
+    const live = state.sessionId.length > 0 ? pausedFromSidecar(state.sessionId) : state.paused;
+    const paused = live.map(pausedWireItemOf);
+    return { schedules: [...active, ...paused] };
 }
 /**
  * 投影单元声明（传给 sessionProjections.register）。
@@ -231,6 +360,6 @@ export const userSchedulesProjectionUnit = {
         viewSchema: userSchedulesSchema,
         view: viewUserScheduleProjection,
     },
-    // v3：状态新增 sessionId + 所有权改走 sidecar（init 装载）；旧缓存行按版本丢弃
-    stateVersion: 3,
+    // v3：sessionId + 所有权 sidecar；v4：paused[] 镜像（暂停/恢复）
+    stateVersion: 4,
 };