dsh-later 1.0.0 → 1.2.0

package/lib/types/projection.d.ts

@@ -15,7 +15,8 @@
  */
 import { z } from 'zod';
 import type { SessionEvent } from '@deepseek-ai/dsh-session';
-import type { ScheduleRecord } from '@deepseek-ai/dsh-schedule';
+import type { AfterScheduleRecord, AtScheduleRecord, EveryScheduleRecord } from '@deepseek-ai/dsh-schedule';
+import type { PausedEntry } from './ownership-store.js';
 import type { UserScheduleProjectionValue } from './domain.js';
 /** 投影 wire 值 schema（wire.viewSchema：离开宿主前校验客户端载荷）。 */
 export declare const userSchedulesSchema: z.ZodObject<{
@@ -28,6 +29,11 @@ export declare const userSchedulesSchema: z.ZodObject<{
         scheduled_at: z.ZodString;
         created_at: z.ZodOptional<z.ZodString>;
         delivery_mode: z.ZodLiteral<"session-local">;
+        status: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"active">, z.ZodLiteral<"paused">]>>;
+        remaining_seconds: z.ZodOptional<z.ZodNumber>;
+        paused_at: z.ZodOptional<z.ZodString>;
+        schedule_id: z.ZodOptional<z.ZodString>;
+        window_seconds: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const userSchedulesStateSchema: z.ZodObject<{
@@ -43,11 +49,37 @@ export declare const userSchedulesStateSchema: z.ZodObject<{
         createdAt: z.ZodOptional<z.ZodNumber>;
     }, z.core.$loose>>;
     seedSeq: z.ZodNumber;
+    paused: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        uid: z.ZodString;
+        prompt: z.ZodString;
+        delivery: z.ZodUnion<readonly [z.ZodLiteral<"context">, z.ZodLiteral<"user">]>;
+        kind: z.ZodLiteral<"after">;
+        remainingSeconds: z.ZodNumber;
+        originalScheduledAt: z.ZodString;
+        originalAfterSeconds: z.ZodOptional<z.ZodNumber>;
+        lastScheduleId: z.ZodString;
+        pausedAt: z.ZodNumber;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
-/** 活动存储记录：dsh-schedule 记录 + 创建时刻（来自 create 事件的 time）。 */
-export type StoredScheduleRecord = ScheduleRecord & {
+/**
+ * 活动存储记录：dsh-schedule 记录 + 创建时刻（来自 create 事件的 time）。
+ *
+ * 显式按**本插件产出的三种 kind** 收窄，而非直接用 `ScheduleRecord`：
+ * 0.1.7 的联合新增了 daily/weekly/cron，它们的字段面
+ * （`afterSeconds` / `everySeconds`）与本插件的 wire 契约不同，透传会让
+ * `wireItemOf` 读到不存在的字段。
+ *
+ * 逐个具名引用而非 `Extract`：`Extract<ScheduleRecord, {kind:'after'|…}>`
+ * 在本仓库的 tsc 配置下不触发收窄（判别式联合的 `Extract` 需 kind 为
+ * 单字面量，逐个列举后交集才正确）。
+ */
+export type StoredScheduleRecord = (AfterScheduleRecord & {
     readonly createdAt?: number;
-};
+}) | (AtScheduleRecord & {
+    readonly createdAt?: number;
+}) | (EveryScheduleRecord & {
+    readonly createdAt?: number;
+});
 /** 投影内部状态（plain JSON：owned/active 用数组承载）。 */
 export interface UserScheduleProjectionState {
     /** 会话 id（init 由 header 注入）。 */
@@ -58,6 +90,8 @@ export interface UserScheduleProjectionState {
     readonly active: readonly StoredScheduleRecord[];
     /** 已见 `session/end-seed` 的 seq；更早的继承前缀一律忽略。 */
     readonly seedSeq: number;
+    /** sidecar 暂停留档镜像。 */
+    readonly paused: readonly PausedEntry[];
 }
 /** 初始状态：按会话 id 从所有权 sidecar 装载（进程重启后恢复 GUI 归属）。 */
 export declare function initUserScheduleProjection(header?: {
@@ -67,7 +101,19 @@ export declare function initUserScheduleProjection(header?: {
  * 增量 fold。返回同一引用当事件无关；返回新状态当 owned/active 发生变化。
  */
 export declare function applyUserScheduleProjection(state: UserScheduleProjectionState, event: SessionEvent): UserScheduleProjectionState;
-/** 投影 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 declare function viewUserScheduleProjection(state: UserScheduleProjectionState): UserScheduleProjectionValue;
 /**
  * 投影单元声明（传给 sessionProjections.register）。
@@ -93,6 +139,17 @@ export declare const userSchedulesProjectionUnit: {
             createdAt: z.ZodOptional<z.ZodNumber>;
         }, z.core.$loose>>;
         seedSeq: z.ZodNumber;
+        paused: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            uid: z.ZodString;
+            prompt: z.ZodString;
+            delivery: z.ZodUnion<readonly [z.ZodLiteral<"context">, z.ZodLiteral<"user">]>;
+            kind: z.ZodLiteral<"after">;
+            remainingSeconds: z.ZodNumber;
+            originalScheduledAt: z.ZodString;
+            originalAfterSeconds: z.ZodOptional<z.ZodNumber>;
+            lastScheduleId: z.ZodString;
+            pausedAt: z.ZodNumber;
+        }, z.core.$strip>>>;
     }, z.core.$strip>;
     readonly init: typeof initUserScheduleProjection;
     readonly apply: typeof applyUserScheduleProjection;
@@ -107,9 +164,14 @@ export declare const userSchedulesProjectionUnit: {
                 scheduled_at: z.ZodString;
                 created_at: z.ZodOptional<z.ZodString>;
                 delivery_mode: z.ZodLiteral<"session-local">;
+                status: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"active">, z.ZodLiteral<"paused">]>>;
+                remaining_seconds: z.ZodOptional<z.ZodNumber>;
+                paused_at: z.ZodOptional<z.ZodString>;
+                schedule_id: z.ZodOptional<z.ZodString>;
+                window_seconds: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strict>>;
         }, z.core.$strict>;
         readonly view: typeof viewUserScheduleProjection;
     };
-    readonly stateVersion: 3;
+    readonly stateVersion: 4;
 };

package/lib/types/runtime.d.ts

@@ -19,6 +19,13 @@ import type { Context } from '@deepseek-ai/cordis';
 import type { Agent } from '@deepseek-ai/dsh-agent';
 import type { ScheduleRecord, OneShotScheduleRecord, EveryScheduleRecord } from '@deepseek-ai/dsh-schedule';
 import type { UserScheduleDelivery } from './domain.js';
+import type { DeliveryMode } from './delivery.js';
+/** runtime 关心的设置子集（插话投递策略）。 */
+export interface SteerDeliverySettings {
+    readonly steerDelivery: DeliveryMode;
+    readonly confirmDelivery: boolean;
+    readonly onUnconfirmed: 'keep' | 'discard';
+}
 /** 一次「用户提醒决策」：一批同形态到期一次性、或一批到期固定间隔、或下一次等待目标。
  *
  * P1-5：one-shot 从单条改为**同投递形态的批次**——网页关闭期间积压的多条
@@ -41,10 +48,31 @@ type UserDecision = {
     target?: number;
 };
 export declare function dueUserDecision(active: readonly ScheduleRecord[], now: number, delivery?: ReadonlyMap<string, UserScheduleDelivery>): UserDecision;
+/**
+ * 多条到期一次性提醒的合并注入 framing（P1-5）。
+ * 形状与 dsh-schedule 的固定间隔批次 framing 完全一致：
+ * 动态字段全部经 JSON 转义，保持「非信任提醒内容」的防护语义。
+ *
+ * ⚠️ 这是**上游文案的本地副本**。0.2.0 起 dsh-schedule 把 one-shot 与 recurring
+ * 两条 framing 统一收敛为一句 `SCHEDULED_MESSAGE_FRAMING`，取代了此前
+ * 「Present all due reminders … not new user instructions.」的长句。
+ * 本插件只对**多条合并**这一种上游不提供的形态自渲染（单条走
+ * `renderReminderFraming`，自动跟随上游），故此处需手工对齐，否则同一会话里
+ * 单条与批次的防护措辞会不一致。
+ */
+export declare function renderOneShotBatchFraming(records: readonly OneShotScheduleRecord[]): string;
 /** 每个 agent 的独立调度器。 */
 export declare class UserScheduleRuntime {
     private readonly ctx;
     private readonly agent;
+    /**
+     * 读取当前生效设置（每次调用按需取值，与工具/命令同源）。
+     *
+     * 注入而非直接读 ctx.settings：settings 的注册在 index 的 `ctx.inject(['settings'])`
+     * 回调里完成，runtime 拿不到那个 scope；把它做成闭包注入，保证「设置 UI 改了立刻生效」
+     * 这一既有语义（`applies: 'live'`）在插话路径上同样成立。
+     */
+    private readonly getSettings;
     private readonly stop;
     private resolveStop;
     private timer;
@@ -55,7 +83,7 @@ export declare class UserScheduleRuntime {
     private failures;
     private idleWait;
     private disposal;
-    constructor(ctx: Context, agent: Agent);
+    constructor(ctx: Context, agent: Agent, getSettings: () => SteerDeliverySettings);
     /** 是否仍为活动 root agent。 */
     private isLive;
     /** 发起一次重算（合并多个触发为一次）。 */
@@ -95,8 +123,37 @@ export declare class UserScheduleRuntime {
         code: string;
         message: string;
     }>;
+    /**
+     * 按配置把消息投进队列。
+     *
+     * `followup`（默认）入 `next-turn`：与 `next-step` 是两条独立队列，
+     * `claim('next-step', …)` 不触碰它，**结构上不存在**与 `turn/start` 竞争的窗口。
+     * `steer` 入 `next-step`，更快但会在撞上回合启动时被吞（见 delivery.ts 注释）。
+     */
+    private deliver;
+    /**
+     * 核对投递是否真正进入会话日志。
+     *
+     * 关闭确认时直接返回 true（fire-and-forget，保持旧语义）。
+     */
+    private verifyDelivery;
     /** 执行一次用户提醒决策与派发。 */
     private driveOnce;
+    /**
+     * 暂停项的插话投递。
+     *
+     * 暂停项不在日志里（其日志记录在 pause 时被删），所以从 sidecar 留档取材：
+     * `PausedEntry` 已含 `prompt` 与 `delivery`，足以构造消息。呈现方式与
+     * {@link buildMessage} 的 one-shot 分支保持一致（`user` 代发 vs `context` 注入），
+     * 避免两条路径的语义分叉。
+     *
+     * 投递成功后清掉留档：提醒已送达，不应再留在待发送列表。这与 dispatch 会把记录
+     * 移出 `active` 语义一致。（清留档不写会话事件，故投影不会自动刷新——客户端已用
+     * 本地摘除 + 投影对账处理同类情况，与"删除暂停项"同源。）
+     *
+     * @returns `undefined` 表示该 id 不是暂停项，交由调用方走常规日志路径。
+     */
+    private steerPausedById;
     /**
      * 构造注入的消息，按投递形态分流：
      *  - `user`（`/later` 显式请求的延迟发送）：原样内容 + `source.kind='user'`，

package/lib/types/schedule-compat.d.ts

@@ -0,0 +1,111 @@
+/**
+ * dsh-schedule 0.1.5 → 0.1.7 的版本桥接层。
+ *
+ * 0.1.7 对 `dsh-schedule` 做了三处破坏性变更，本模块把差异收敛为三个函数，
+ * 使 `user-tools.ts` / `runtime.ts` 不必写版本分支：
+ *
+ * 1. `allocateScheduleId(folded)` → 删除。0.1.5 用确定性递增
+ *    （`schedule-1`、`schedule-2`…，靠 `seenIds` 避让），0.1.7 内联改为
+ *    `ScheduleId(\`schedule-${randomUUID()}\`)`（见 0.1.7 `ScheduleService.create`）。
+ *    本插件的 `ownership-store` 把 id 当**不透明字符串**处理（无排序、无数字
+ *    解析，见 docs/verification.md），故行为差异对功能无影响。
+ *
+ * 2. `createAfterScheduleRecord` 新增第 5 个必填参数 `title`。0.1.7 起
+ *    `decodeStoredTitle` 会在读取时校验：缺失 / 未 trim / 超长（>120）的
+ *    存量记录抛 `ScheduleLogError`——**不是跳过，是整份日志拒读**。
+ *
+ * 3. `renderEveryReminderBatchFraming` → 改名
+ *    `renderRecurringReminderBatchFraming`（语义与参数不变）。
+ *
+ * @module dsh-later/schedule-compat
+ */
+import * as sched from '@deepseek-ai/dsh-schedule';
+import type { ScheduleRecord } from '@deepseek-ai/dsh-schedule';
+declare const ScheduleId: typeof sched.ScheduleId;
+/** 0.1.7 `MAX_TITLE_LENGTH`；0.1.5 无此概念，该常量在此仅作截断阈值。 */
+export declare const SCHEDULE_TITLE_MAX = 120;
+/**
+ * 0.1.7 的 `allocateScheduleId` 等价物。
+ *
+ * 随机 UUID 而非递增序号：与官方 `ScheduleService.create` 行为一致，且并发
+ * 创建时天然无碰撞。0.1.5 下也可用（`ScheduleId` 是纯 brand 校验，任意
+ * 非空字符串通过），因此本函数在两个代次上语义相同，无需双轨。
+ *
+ * @param _folded 仅为**保持调用点不变**而接受 0.1.5 的 `folded` 参数；0.1.7
+ *   不再需要它来避让碰撞（UUID 本身唯一），故不使用。
+ */
+export declare function allocateScheduleIdCompat(_folded?: unknown): ReturnType<typeof ScheduleId>;
+/**
+ * 从提醒正文派生 `title`。
+ *
+ * 0.1.7 要求 title 非空、已 trim、≤120 字符。实测本插件历史 496 条提醒中
+ * 最长 575 字符（27 条超限，占 5.4%），故**必须截断**而非直接透传 prompt。
+ * 截断在词边界优先，找不到合适边界时按字符硬切并补省略号，保证结果始终
+ * 是合法 title（`scheduleTitle` 不会抛）。
+ */
+export declare function deriveScheduleTitle(prompt: string): string;
+/** `createAfterScheduleRecord` 的跨版本包装。 */
+export declare function createAfterRecord(id: ReturnType<typeof ScheduleId>, prompt: string, afterSeconds: number, now: number): ScheduleRecord;
+/** `createAtScheduleRecord` 的跨版本包装。 */
+export declare function createAtRecord(id: ReturnType<typeof ScheduleId>, prompt: string, scheduledAt: string, now: number): ScheduleRecord;
+/** `createEveryScheduleRecord` 的跨版本包装。 */
+export declare function createEveryRecord(id: ReturnType<typeof ScheduleId>, prompt: string, everySeconds: number, now: number): ScheduleRecord;
+/**
+ * 周期提醒批次的 framing 渲染。
+ *
+ * 0.1.5 导出 `renderEveryReminderBatchFraming`，0.1.7 改名为
+ * `renderRecurringReminderBatchFraming`（并扩展到 daily/weekly/cron，本插件
+ * 只产生 `every` 记录）。两代参数与返回结构一致，按存在性择一。
+ */
+export declare function renderRecurringBatchFraming(reminders: readonly unknown[]): string;
+/**
+ * 提醒注入消息的 `source`。
+ *
+ * 0.1.5 的 `MessageSourceMap` 含 `plugin: { kind:'plugin'; plugin:string }`；
+ * 0.1.7 **删除了 `plugin` 与 `host` 两个 kind**，改由内核为每个生产者登记
+ * 具名 kind。官方 `dsh-schedule` 在 0.1.7 里注入提醒用的正是
+ * `source: { kind: 'schedule' }`（见其 `lib/index.js` 的 `agent.followup` 调用点）
+ * —— 与本插件投递的语义一致，故 0.1.7 走 `schedule`。
+ *
+ * `form:'notice'` + `summary` 两代都在（`ContextFormed` 未变），保留。
+ *
+ * 不能用具名类型断言跨代：source 的字面量 union 在两代不同，断言只会把
+ * 编译错误推迟到运行期。
+ */
+export declare function scheduleMessageSource(boundedSummary: string): Record<string, unknown>;
+/**
+ * `foldScheduleEvents` 结果的读视图收窄。
+ *
+ * 0.1.5 的 `FoldedSchedules.active` 是 `ScheduleRecord[]`；0.1.7 改为
+ * `LegacyScheduleRecord[]`（title 可选）。本插件只消费 `id` / `kind` /
+ * `prompt` / `afterSeconds` / `everySeconds` / `scheduledAt`，这些字段在
+ * `Legacy*` 视图中全部存在，故收窄无损。
+ */
+export declare function asLegacySchedules(folded: unknown): {
+    readonly active: readonly ScheduleRecord[];
+    readonly seenIds: ReadonlySet<string>;
+};
+/**
+ * `schedule/change` 事件里 `create` 操作的载荷类型。
+ *
+ * 0.1.7 起内核把「事件载荷」与「内部记录」拆成两个类型：
+ * - `ScheduleCreateChange.schedule` 是 **`LegacyScheduleRecord`**（title 可选）
+ * - `ScheduleRecord` 是 Host 内部的新格式（title 必填，且含 daily/weekly/cron）
+ *
+ * 本插件只产生 `after` / `at` / `every` 三种（见 buildScheduleRecord），三者都是
+ * `Legacy*` 的对应分支去掉「title 必填」后的结果，故结构兼容。
+ *
+ * 但 TS 层面 `ScheduleRecord`（6 变体联合）对 `LegacyScheduleRecord`（3 变体）
+ * 不可赋值——**这不是运行时问题，是联合宽度问题**。故在此显式收窄：本插件
+ * 的产出已经过 `createAfter/At/EveryRecord` 限定，不含 daily/weekly/cron。
+ */
+export declare function toChangePayload(record: ScheduleRecord): never;
+/**
+ * `foldScheduleEvents().active` 元素的读取侧类型。
+ *
+ * 0.1.5 直接返回 `ScheduleRecord`；0.1.7 返回 `LegacyScheduleRecord`
+ * （title 可选，因为历史事件没有）。本插件读路径只在 title 存在时展示，
+ * 缺失时回退到 prompt——故按 Legacy 收窄是**语义正确**的，而非绕过检查。
+ */
+export declare function asLegacyRecords(records: readonly unknown[]): readonly ScheduleRecord[];
+export {};

package/lib/types/schedule-summary-store.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 定时摘要 store：把 {@link buildScheduleSummary} 的纯计算接到宿主 `sessions`
+ * 服务上，得到一个**可订阅的公共数据源**。
+ *
+ * 为什么需要它（issue #17）：dsh-later 自己的侧栏 badge 与外部插件（如
+ * dsh-group-status）都需要「全会话定时任务摘要」。两条独立通路会各自订阅
+ * `sessions.list`、各自周期 `refresh()`，既浪费 RPC 又容易漂移。本 store 是
+ * **唯一**的数据权威：内部负责列表订阅、状态 tick（scheduled→urgent→overdue）
+ * 与 `session.list` 读 RPC 补时效；外部只读 {@link ScheduleSummaryStore.getSnapshot}
+ * 或订阅变更。
+ *
+ * 跨插件使用方式（消费方声明 `dsh.client.external: ["dsh-later"]` 后）：
+ * ```js
+ * const later = require('dsh-later/client')
+ * const store = later.getScheduleSummaryStore()
+ * ```
+ *
+ * 本模块零 DOM / 零 React 依赖（`document` / `window` 一律经 `globalThis`
+ * 结构化探测），宿主 tsc 与浏览器 esbuild 都能编译，`node --test` 也能直接跑。
+ * @module dsh-later/schedule-summary-store
+ */
+import { type ScheduleSummaryMap, type ScheduleSummarySource } from './schedule-summary.js';
+/** 摘要状态重算周期（本地时钟，零网络）。 */
+export declare const SUMMARY_STATE_TICK_MS = 30000;
+/** `session.list` 重拉周期（读 RPC；仅页面可见时执行）。 */
+export declare const SUMMARY_REFRESH_INTERVAL_MS = 60000;
+/** 宿主 `sessions` 服务的结构子集（只用到列表快照与 refresh）。 */
+export interface ScheduleSummarySessionsLike {
+    /** 会话列表 store（快照 + 变更订阅）。 */
+    readonly list: {
+        getSnapshot(): ScheduleSummarySource;
+        subscribe(listener: () => void): () => void;
+    };
+    /** 重拉会话列表（读 RPC，不写会话日志）。 */
+    refresh(): Promise<unknown>;
+}
+/** 可订阅的定时摘要 store。 */
+export interface ScheduleSummaryStore {
+    /** 当前摘要（引用稳定；内容变化时才换成新对象）。 */
+    getSnapshot(): ScheduleSummaryMap;
+    /** 订阅变更；返回退订函数。 */
+    subscribe(listener: () => void): () => void;
+    /** 立即按最新会话列表快照重算（内容有变化才通知）。 */
+    reload(): void;
+    /** 释放订阅/定时器（宿主卸载时调用）。 */
+    dispose(): void;
+}
+export interface ScheduleSummaryStoreOptions {
+    /** 状态重算周期（毫秒）；缺省 {@link SUMMARY_STATE_TICK_MS}。 */
+    readonly stateTickMs?: number;
+    /** 会话列表重拉周期（毫秒）；缺省 {@link SUMMARY_REFRESH_INTERVAL_MS}。 */
+    readonly refreshIntervalMs?: number;
+    /** 当前时刻注入（单测用）；缺省 `Date.now`。 */
+    readonly now?: () => number;
+    /** 是否允许发起 refresh RPC；缺省「页面可见时允许」。 */
+    readonly canRefresh?: () => boolean;
+    /** 是否自动周期 refresh；缺省 true（单测可关）。 */
+    readonly autoRefresh?: boolean;
+}
+/**
+ * 创建定时摘要 store（宿主 `apply` 内创建一次，全插件共享）。
+ * @param sessions - 宿主 `sessions` 服务。
+ * @param options - 周期/时钟/刷新策略覆盖（单测用）。
+ * @returns 可订阅 store。
+ */
+export declare function createScheduleSummaryStore(sessions: ScheduleSummarySessionsLike, options?: ScheduleSummaryStoreOptions): ScheduleSummaryStore;
+/**
+ * 登记/撤销当前 store（由 dsh-later 自身 `apply` 调用；外部插件不要调用）。
+ * @param store - 生效的 store；undefined 表示撤销。
+ */
+export declare function setActiveScheduleSummaryStore(store: ScheduleSummaryStore | undefined): void;
+/** 读取当前生效的 store；dsh-later 未加载时为 undefined。 */
+export declare function getScheduleSummaryStore(): ScheduleSummaryStore | undefined;
+/** 订阅 store 登记变化（供 React hook 在 store 迟到时仍能重渲染）。 */
+export declare function subscribeScheduleSummaryStore(listener: () => void): () => void;

package/lib/types/schedule-summary.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 定时任务摘要：dsh-later 对外暴露的**公共数据面**（跨会话 / 跨插件）。
+ *
+ * 关键事实（本插件「路线 B」的数据源）：`userSchedules` 是 client-visible 投影，
+ * 宿主在 `session.list` 基线里为**每个**会话携带 projections 块（live 会话走注册
+ * 表现值、冷会话走持久化投影缓存），客户端把它合入
+ * `SessionSummary.projectionValues`。因此**任何**持有 `sessions` 服务的客户端插件
+ * 都能读到全会话的定时任务，本模块只负责把它折叠成稳定形状。
+ *
+ * 契约形状（issue #17）：`Map<SessionId, { count, nextAt, state }>`——即
+ * {@link ScheduleSummaryMap}。dsh-later 通过 `dsh-later/client` 导出
+ * {@link buildScheduleSummary}（纯函数）、`createScheduleSummaryStore`（可订阅
+ * store）与 `useScheduleSummary`（React hook），消费方按需选用。
+ *
+ * 本模块零 DOM / 零 React 依赖：宿主、浏览器与 `node --test` 都能直接跑。
+ * @module dsh-later/schedule-summary
+ */
+import { type PresenceBadgeState, type PresenceScheduleLike, type PresenceSummary } from './presence.js';
+/** `userSchedules` 投影值在 `projectionValues` 里的键名。 */
+export declare const SCHEDULE_PROJECTION_KEY = "userSchedules";
+/**
+ * 一条会话的定时摘要：数量 + 下次触发 + 视觉状态。
+ *
+ * `state` 是**快照时刻**由 {@link badgeStateFor} 判定的结果（`scheduled` /
+ * `urgent` ≤5min / `overdue` 已到期未派发），因此 store 每次重算/定时 tick 都会
+ * 刷新它；暂停项计入 `count`/`pausedCount`，但**不参与** `nextAt`（见 presence 模块
+ * 对暂停语义的说明）。
+ */
+export interface ScheduleSummaryEntry extends PresenceSummary {
+    /** 该会话的 badge 状态（按快照时刻判定）。 */
+    readonly state: PresenceBadgeState;
+}
+/** 会话 id → 该会话的定时摘要（**仅**包含有任务的会话）。 */
+export type ScheduleSummaryMap = ReadonlyMap<string, ScheduleSummaryEntry>;
+/** 摘要所需的最小会话列表快照面（`SessionListState` 的结构子集）。 */
+export interface ScheduleSummarySource {
+    /** 会话 id → 会话行事实（只用到 `projectionValues`）。 */
+    readonly byId: Readonly<Record<string, ScheduleSummaryRowLike | undefined>>;
+}
+/** 会话行事实的结构子集。 */
+export interface ScheduleSummaryRowLike {
+    /** 该会话的投影现值（含 `userSchedules`）。 */
+    readonly projectionValues?: Readonly<Record<string, unknown>>;
+}
+/**
+ * 从 `projectionValues` 里取出任务数组（容错：形状不对一律当作无任务）。
+ * @param projectionValues - 会话行的投影现值集合。
+ * @returns 任务数组；缺失或形状非法时 undefined。
+ */
+export declare function schedulesOfProjection(projectionValues: Readonly<Record<string, unknown>> | undefined): readonly PresenceScheduleLike[] | undefined;
+/**
+ * 全会话归纳：把会话列表快照折叠成 {@link ScheduleSummaryMap}。
+ * @param source - 会话列表快照（`sessions.list.getSnapshot()`）。
+ * @param now - 判定 `state` 的当前时刻（epoch ms）。
+ * @returns 会话 id → 摘要；无任务的会话不出现在 map 里。
+ */
+export declare function buildScheduleSummary(source: ScheduleSummarySource, now: number): ScheduleSummaryMap;
+/**
+ * 两份摘要是否等价（逐条比对五个字段）。store 用它决定是否需要通知订阅者，
+ * 避免每次重算都产生新的 Map 引用导致 React 无谓重渲染。
+ *
+ * `progressFrom` 一并比对：它虽然通常随 `nextAt` 同进同退，但暂停→恢复会让
+ * 同一条任务重新拥有窗口起点，此时 `nextAt` 可能未变而窗口已换 —— 漏比会
+ * 让进度环停在上一个窗口的比例上。
+ * @param a - 旧摘要。
+ * @param b - 新摘要。
+ * @returns 键集合与每条内容都相同时为 true。
+ */
+export declare function sameScheduleSummary(a: ScheduleSummaryMap, b: ScheduleSummaryMap): boolean;
+/** 分组聚合结果（折叠的工作区分组徽标直接用这一份）。 */
+export interface GroupScheduleSummary {
+    /** 组内**有任务**的会话数。 */
+    readonly sessions: number;
+    /** 组内任务总数（含暂停项）。 */
+    readonly count: number;
+    /** 组内暂停项数量。 */
+    readonly pausedCount: number;
+    /** 组内最早触发时刻（epoch ms）；全部暂停或缺省时为 undefined。 */
+    readonly nextAt?: number;
+    /** 组内最高优先级状态（overdue > urgent > scheduled）；无任务时为 undefined。 */
+    readonly state?: PresenceBadgeState;
+}
+/**
+ * 按**分组**聚合摘要：给定组内会话 id，折叠出可直接渲染的分组事实。
+ *
+ * 消费方（如 dsh-group-status 的 `GroupLiveStatus`）只需把组内会话 id 传进来，
+ * 无需理解 `nextAt`/暂停语义。
+ * @param summary - {@link ScheduleSummaryMap}。
+ * @param sessionIds - 组内会话 id（顺序无关；不在摘要里的会被忽略）。
+ * @returns 分组级摘要；组内无任务时 `sessions`/`count` 为 0、`state` 缺省。
+ */
+export declare function summarizeScheduleGroup(summary: ScheduleSummaryMap, sessionIds: Iterable<string>): GroupScheduleSummary;

package/lib/types/upstream-compat.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 上游内核跨代兼容层：把「鸭子类型双轨探测 + peer 代次矩阵」收敛到单文件。
+ *
+ * 背景（docs/verification.md）：DSH 内核 0.1.1 → 0.1.2 之间有多处不兼容，
+ * 此前散落在 user-tools / index / package.json 各处。上游每发新 rc 需要：
+ *   1. package.json peer + dev 各包补一枚举项（node-semver 不把预发布算进范围）
+ *   2. Session API 形状若有变化，只改本模块的 read* 函数
+ *
+ * 新 rc 落地 checklist：
+ *   - 在 KERNEL_GENERATIONS 追加一代（id + peerRange + sessionApi）
+ *   - 跑 `node scripts/sync-peer-matrix.mjs` 重写 package.json peer 枚举
+ *   - 跑 `npm test`（含 tests/upstream-compat.test.mjs 矩阵护栏）
+ *
+ * @module dsh-later/upstream-compat
+ */
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
+/**
+ * 已验证的内核代次（peer 枚举的唯一事实来源）。
+ *
+ * - `id`：semver 精确版本（发布 tag）
+ * - `peerRange`：写入 package.json 的范围（node-semver 预发布需显式枚举）
+ * - `sessionApi`：Session 读日志的形状（见 readOwnEvents / readInheritedEventCount）
+ */
+export declare const KERNEL_GENERATIONS: readonly [{
+    readonly id: "0.1.1-rc.2";
+    readonly peerRange: "^0.1.1-rc.2";
+    readonly sessionApi: "legacy-events";
+}, {
+    readonly id: "0.1.2-rc.1";
+    readonly peerRange: "^0.1.2-rc.1";
+    readonly sessionApi: "own-events";
+}, {
+    /**
+     * `0.1.5` 代次：Session 形状未变（仍 `ownEvents()` + `inheritedEventCount`），
+     * 且插件依赖的 `dsh-schedule` 导出面完整 —— 实测 `rc.1/rc.2/rc.3` 逐个
+     * `import()` 全部 15 个 host 模块均通过（见 docs/verification.md）。
+     */
+    readonly id: "0.1.5-rc.1";
+    readonly peerRange: "^0.1.5-rc.1";
+    readonly sessionApi: "own-events";
+}, {
+    /**
+     * `0.1.7` 代次：Session 形状仍未变（`ownEvents()` + `inheritedEventCount`）；
+     * `dsh-schedule` 的三处破坏性变更（`allocateScheduleId` 删除、
+     * `renderEveryReminderBatchFraming` 改名 `renderRecurringReminderBatchFraming`、
+     * `createAfterScheduleRecord` 新增必填 `title`）**全部收敛在
+     * `schedule-compat.ts`**——调用点 `user-tools.ts` / `runtime.ts` 不含版本分支。
+     *
+     * 三条差异在 bridge 里按「存在性择一」（framing）或「统一用新语义」
+     * （UUID id、title 派生）处理，两代行为一致，故可安全同时声明这两个范围。
+     *
+     * 不单列 0.1.6-alpha.*：alpha 线无独立兼容面，且 0.1.7 已覆盖其功能面。
+     */
+    readonly id: "0.1.7-rc.2";
+    readonly peerRange: "^0.1.7-rc.2";
+    readonly sessionApi: "own-events";
+}, {
+    /**
+     * `0.2.0` 代次：内核跨了次版本号（0.1 → 0.2），但本插件依赖的 API 面
+     * **全部保持**。逐项核对（见 docs/verification.md「0.2.0 兼容核对」）：
+     *
+     * - Session：形状未变（`ownEvents()` + `inheritedEventCount`）
+     * - dsh-schedule：0.1.7 的三处破坏性变更即为 0.2.0 现状；`foldScheduleEvents`
+     *   / `renderReminderFraming` / `resolveEveryOccurrence` / `decodeScheduleChange`
+     *   / `scheduleView` / `ScheduleId` 导出面完整，且
+     *   `renderRecurringReminderBatchFraming` 仍在 —— `schedule-compat.ts` 无需改动
+     * - dsh-llm：`createUserMessage` / `boundContextSummary` 仍在；`MessageSourceMap`
+     *   已无 `plugin` kind，仅剩 user/model/tool/system-prompt，而 dsh-schedule
+     *   声明的 `schedule` kind 经 module augmentation 并入 —— 0.1.7 分支继续适用
+     * - dsh-agent：`followup()`（next-turn）与 `steer()`（next-step）语义未变
+     * - dsh-tools：`defineTool` 仍在
+     *
+     * 实证：以 0.2.0-rc.2 类型面对 `src/**`（host 端）跑 `tsc --noEmit` **零错误**，
+     * 且本地 183 项测试全绿。
+     *
+     * 附带影响：0.2.0 内核开始**强制**校验本范围（peer 不满足即整插件不加载，
+     * 此前只是警告）。故这一代次的缺失曾让插件在 0.2.0 上完全失效。
+     */
+    readonly id: "0.2.0-rc.2";
+    readonly peerRange: "^0.2.0-rc.2";
+    readonly sessionApi: "own-events";
+}];
+/**
+ * 随内核代次一起 bump 的 peer 包（宿主 hoisting 变化会波及这些运行时 import）。
+ * cordis / schemastery 等独立 semver 包**不**列入——它们不随内核 rc 枚举。
+ */
+export declare const KERNEL_SCOPED_PACKAGES: readonly ["@deepseek-ai/dsh-agent", "@deepseek-ai/dsh-commands", "@deepseek-ai/dsh-llm", "@deepseek-ai/dsh-schedule", "@deepseek-ai/dsh-session", "@deepseek-ai/dsh-session-projection", "@deepseek-ai/dsh-settings", "@deepseek-ai/dsh-tools"];
+/** 由 KERNEL_GENERATIONS 拼出的 peer 范围串（`a || b`）。 */
+export declare function peerRangeFor(packageName: string): string;
+/** 全部需逐代枚举的 `{ package, range }`（sync-peer-matrix / 矩阵测试共用）。 */
+export declare function peerMatrixEntries(): ReadonlyArray<{
+    packageName: string;
+    range: string;
+}>;
+/** Session 读日志的最小结构（鸭子类型；两代公有面）。 */
+export interface SessionLogSurface {
+    readonly header?: {
+        readonly seedLength?: unknown;
+    } | undefined;
+    readonly events?: readonly SessionEvent[] | undefined;
+    readonly ownEvents?: (() => readonly SessionEvent[]) | undefined;
+    readonly inheritedEventCount?: unknown;
+}
+/**
+ * 读取「本会话自有」事件日志（不含 fork 继承前缀时由调用方配合 offset）。
+ *
+ * - 0.1.2+：`session.ownEvents()`（推荐；仅 live 段）
+ * - 0.1.1：`session.events`（含 seed；配合 seedLength 切片）
+ */
+export declare function readOwnEvents(session: SessionLogSurface | Session): readonly SessionEvent[];
+/**
+ * 读取「fork 继承前缀长度」——`foldScheduleEvents` 第二参数。
+ *
+ * - 0.1.2+：`session.inheritedEventCount`（SessionLogOffset 品牌数字，运行时仍是 number）
+ * - 0.1.1：`session.header.seedLength`（等价物；此前实现漏了这条回退）
+ * - 均缺失：0（新建会话 / 测试假 Session）
+ *
+ * 统一以裸 `number` 返回：cache key 可用 `===`；传入 foldScheduleEvents 时
+ * 0.1.2 的 brandshape 校验接受 safe integer。
+ */
+export declare function readInheritedEventCount(session: SessionLogSurface | Session): number;
+/** 探测到的 sessionApi 代次（诊断 / 测试用；不参与业务分支）。 */
+export declare function detectSessionApi(session: SessionLogSurface | Session): 'own-events' | 'legacy-events';