dsh-later 1.0.0 → 1.1.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/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';

package/lib/types/user-tools.d.ts

@@ -19,9 +19,9 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { Agent } from '@deepseek-ai/dsh-agent';
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
-import { foldScheduleEvents } from '@deepseek-ai/dsh-schedule';
 import type { ScheduleRecord, ScheduleView } from '@deepseek-ai/dsh-schedule';
 import type { UserScheduleDelivery } from './domain.js';
+import type { PausedEntry } from './ownership-store.js';
 /** 单 session 用户任务上限（PRD：防滥用）。 */
 export declare const DEFAULT_MAX_SCHEDULES = 100;
 /**
@@ -53,7 +53,7 @@ export declare function validatePrompt(raw: unknown, limits: PromptLimits): {
     value: string;
 } | UserScheduleError;
 /** 用户工具稳定的闭包错误集合（在 dsh-schedule 闭包之上追加本插件专用码）。 */
-export type UserScheduleErrorCode = 'invalid_prompt' | 'invalid_selector' | 'invalid_time_zone' | 'not_future' | 'time_out_of_range' | 'frequency_too_high' | 'invalid_rule' | 'schedule_not_found' | 'already_overdue' | 'quota_exceeded' | 'persistence_uncertain' | 'internal_error';
+export type UserScheduleErrorCode = 'invalid_prompt' | 'invalid_selector' | 'invalid_time_zone' | 'not_future' | 'time_out_of_range' | 'frequency_too_high' | 'invalid_rule' | 'schedule_not_found' | 'already_overdue' | 'quota_exceeded' | 'persistence_uncertain' | 'unsupported_kind' | 'not_paused' | 'internal_error';
 /** 封闭错误值。 */
 export interface UserScheduleError {
     readonly ok: false;
@@ -82,6 +82,21 @@ export type UserScheduleDeleteResult = UserScheduleResult<{
     readonly deleted: false;
     readonly code: 'schedule_not_found';
 }>;
+/** `user_schedule_pause` 成功响应（仅 after）。 */
+export type UserSchedulePauseResult = UserScheduleResult<{
+    readonly ok: true;
+    readonly uid: string;
+    readonly schedule_id: string;
+    readonly remaining_seconds: number;
+    readonly scheduled_at: string;
+}>;
+/** `user_schedule_resume` 成功响应：新 scheduleId + 原 uid。 */
+export type UserScheduleResumeResult = UserScheduleResult<{
+    readonly ok: true;
+    readonly uid: string;
+    readonly schedule_id: string;
+    readonly remaining_seconds: number;
+}>;
 /** `user_schedule_create` 的规范化输入。 */
 export interface UserScheduleCreateInput {
     readonly prompt: string;
@@ -121,15 +136,30 @@ export declare function foldOwnedDelivery(events: readonly SessionEvent[]): Read
  * 消除热路径（每次 drive / 每次工具调用）对全量日志的重复 O(n) 扫描。
  */
 export interface UserFoldState {
-    readonly folded: ReturnType<typeof foldScheduleEvents>;
+    /**
+     * `foldScheduleEvents` 的结果，按**本插件的读视图**收窄。
+     *
+     * 0.1.5 返回 `ScheduleRecord`；0.1.7 返回 `LegacyScheduleRecord`
+     * （`title` 可选，因为 title 成为必填前写入的历史事件没有该字段），
+     * 且 `ScheduleRecord` 联合新增了 daily/weekly/cron 三个本插件不产生的变体。
+     *
+     * 收窄到 `Legacy*` 视图对读路径是**语义正确**的：本插件只创建
+     * after/at/every，title 缺失时投影回退到 prompt（见 projection.ts）。
+     * 统一在此收口，避免每个消费点各写一次断言。
+     */
+    readonly folded: FoldedUserSchedules;
     readonly owned: ReadonlySet<string>;
     readonly delivery: ReadonlyMap<string, UserScheduleDelivery>;
 }
+/** fold 结果中本插件关心的字段面（`active` 按 Legacy 视图收窄）。 */
+export interface FoldedUserSchedules {
+    readonly active: readonly ScheduleRecord[];
+    readonly seenIds: ReadonlySet<string>;
+}
 /** fold 当前会话的完整用户调度状态（带缓存；调用方不得变更返回值）。
  *
- * 跨代兼容：0.1.1 暴露 `session.events` + `header.seedLength`；0.1.2 改名
- * 为 `session.ownEvents()` + `session.inheritedEventCount`。通过鸭子类型
- * （`(session as { ownEvents?; events? })`）双轨探测，不引入 `any`。
+ * 跨代 Session API 探测已收敛到 `upstream-compat.ts`（readOwnEvents /
+ * readInheritedEventCount）——新 rc 若再改名只动那一处。
  */
 export declare function foldUserState(session: Session): UserFoldState;
 /** 稳定内部错误（不透出异常细节）。 */
@@ -170,7 +200,18 @@ export interface UserScheduleCreateOptions {
 export declare function userScheduleCreate(input: unknown, agent: Agent, ctx: Context, maxSchedules?: number, options?: UserScheduleCreateOptions, limits?: PromptLimits): Promise<UserScheduleCreateResult>;
 /** `user_schedule_list` 核心实现。 */
 export declare function userScheduleList(agent: Agent, ctx: Context): Promise<UserScheduleListResult>;
-/** `user_schedule_delete` 核心实现。 */
+/** `user_schedule_delete` 核心实现。id 可为 scheduleId 或稳定 uid。 */
 export declare function userScheduleDelete(id: unknown, agent: Agent, ctx: Context): Promise<UserScheduleDeleteResult>;
 /** `user_schedule_edit`（改内容）核心实现：删旧建新，保留原时刻与 delivery。 */
 export declare function userScheduleEditPrompt(id: unknown, newPrompt: unknown, agent: Agent, ctx: Context, limits?: PromptLimits): Promise<UserScheduleCreateResult | UserScheduleError>;
+/**
+ * 暂停一条 **after** 提醒（方案 B）：sidecar 留档 + 日志 delete。
+ * 仅 kind==='after' 且未到点；恢复见 {@link userScheduleResume}。
+ */
+export declare function userSchedulePause(id: unknown, agent: Agent, ctx: Context): Promise<UserSchedulePauseResult>;
+/** 恢复一条暂停中的 after 提醒：`after_seconds = remaining` 重建；uid 不变。 */
+export declare function userScheduleResume(uid: unknown, agent: Agent, ctx: Context, maxSchedules?: number): Promise<UserScheduleResumeResult>;
+/** 测试/投影辅助：某会话全部暂停留档。 */
+export declare function listPausedForSession(sessionId: string): Readonly<Record<string, PausedEntry>>;
+/** 测试辅助：按 pause 前 schedule id 查留档。 */
+export declare function findPausedEntry(sessionId: string, scheduleId: string): PausedEntry | undefined;