dsh-later 1.0.0

package/lib/types/owned-event-registration.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 把 `OWNED_EVENT` 注册进宿主的已知会话事件类型集合（进程级、幂等）。
+ *
+ * 2026-09 起插件**不再写入**该事件（所有权改存 sidecar，见 ownership-store.ts），
+ * 本注册保留为**读兼容**：早期版本写入的历史日志（含当前 format 的日志）仍含
+ * 此事件类型，未注册时宿主读路径会以「unknown event type not marked ignorable」
+ * 拒读整份日志。
+ *
+ * 历史教训（为什么当初需要它 + 为什么现在不再写入）：当前构建的
+ * `Session.append(type, data)` 不暴露 envelope 的 `ignorable` 字段，插件无法
+ * 在写入侧自保；持久化层在特定时序下会「seq 已消费但行未落盘」，在日志里留下
+ * 永久 seq 缺口，任何读方（含 v0→v3 格式迁移）都会拒读整份历史（GUI 表现为
+ * 「历史加载失败」）。唯一根治 = 不往会话日志写宿主词汇表之外的事件。
+ *
+ * 安全性：该事件是纯信息性的所有权记录，`{version, operation, id}` 自描述；
+ * dsh-schedule 的 fold 天然跳过它，本插件投影按严格解码消费，把它当作
+ * 「已知必需」不会让任何读者误解释日志其余部分。
+ *
+ * TODO(上游)：待 dsh-session 暴露 append 侧的 `ignorable` 标记后，改为写入
+ * 时标记（更符合 envelope 契约），并移除本注册。
+ */
+export declare function registerOwnedSessionEventType(): void;

package/lib/types/ownership-store.d.ts

@@ -0,0 +1,20 @@
+import type { UserScheduleDelivery } from './domain.js';
+/** 单条所有权记录。 */
+export interface OwnedEntry {
+    /** 到点注入形态（/later 为 'user'，其余 'context'）。 */
+    readonly delivery: UserScheduleDelivery;
+    /** 创建时刻（epoch ms，诊断用）。 */
+    readonly createdAt: number;
+}
+/** 读取某会话的全部所有权记录（缓存优先；返回副本语义，调用方不得变更）。 */
+export declare function allOwnership(sessionId: string): Readonly<Record<string, OwnedEntry>>;
+/** 某 schedule id 是否由用户工具创建。 */
+export declare function hasOwnership(sessionId: string, id: string): boolean;
+/** 某条所有权记录（缺失返回 undefined）。 */
+export declare function getOwnership(sessionId: string, id: string): OwnedEntry | undefined;
+/** 记录（新增或覆盖）一条所有权；幂等。 */
+export declare function recordOwnership(sessionId: string, id: string, delivery: UserScheduleDelivery): void;
+/** 撤销一条所有权；幂等（不存在时无操作）。 */
+export declare function removeOwnership(sessionId: string, id: string): void;
+/** 测试辅助：清空进程内缓存（不删文件）。 */
+export declare function resetCacheForTests(): void;

package/lib/types/presence.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 侧栏「定时状态」badge 的纯逻辑（宿主与客户端共享）。
+ *
+ * 数据源说明（路线 B 的关键事实）：本插件的 `userSchedules` 投影是
+ * client-visible 单元，宿主在 `session.list` 基线里为**每个**会话携带
+ * projections 块（live 会话走注册表现值，冷会话走持久化投影缓存，零日志
+ * 加载）；客户端把每行的块喂进 per-session 投影 store，并合入
+ * `SessionSummary.projectionValues`。因此客户端从 `sessions.list` 就能拿到
+ * 跨会话的任务概要，**无需宿主新增任何数据通道**。
+ *
+ * 本模块不触碰 DOM / React，全部函数可在 node --test 下运行。
+ * @module dsh-later/presence
+ */
+/** badge 状态：正常排期 / 紧急（≤5min）/ 到期未派发（瞬时，等会话空闲）。 */
+export type PresenceBadgeState = 'scheduled' | 'urgent' | 'overdue';
+/** 紧急窗口：下次触发在该窗口内时，badge 从 scheduled 升级为 urgent。 */
+export declare const PRESENCE_URGENT_WINDOW_MS: number;
+/** 参与归纳的最小任务形状（投影 wire 项 / runtime 记录的超集）。 */
+export interface PresenceScheduleLike {
+    readonly scheduled_at?: string;
+    readonly scheduledAt?: string;
+}
+/** 由一组活动任务归纳的 badge 概要。 */
+export interface PresenceSummary {
+    /** 可解析触发时刻的活动任务数量。 */
+    readonly count: number;
+    /** 最早触发时刻（epoch ms）；全部不可解析时缺省。 */
+    readonly nextAt?: number;
+}
+/**
+ * 归纳：取最早触发时刻 + 可解析数量。`every` 类任务在投影里携带推进后的
+ * `scheduledAt`（下次触发点），与一次性任务同构参与排序。
+ */
+export declare function summarizeSchedules(schedules: readonly PresenceScheduleLike[] | undefined): PresenceSummary;
+/** 由当前时刻判定 badge 状态。 */
+export declare function badgeStateFor(nextAt: number | undefined, now: number): PresenceBadgeState;
+/** 相对触发时间的文案槽位（由调用方按语言准备；时间串经 formatHhmm 注入）。 */
+export interface RelativeFireLabels {
+    /** ≤1 分钟：即将发送。 */
+    readonly imminent: string;
+    /** 1–59 分钟：{m} 分后。 */
+    readonly minutes: (m: number) => string;
+    /** 今天且 ≥1 小时：{h} 小时后。 */
+    readonly hours: (h: number) => string;
+    /** 明天：明天 {time}。 */
+    readonly tomorrow: (time: string) => string;
+    /** 已到期 / 更远日期缺省时钟面。 */
+    readonly clock: (time: string) => string;
+    /** ≥2 天：{date} {time}。 */
+    readonly date: (date: string, time: string) => string;
+}
+/**
+ * 下次触发的相对时间标签。已到期（≤0）返回绝对时钟面（overdue 态文案由
+ * 调用方另行处理），≤1min 返回「即将发送」，其余按 分/小时/明天/日期 分档。
+ */
+export declare function relativeFireLabel(nextAt: number, now: number, labels: RelativeFireLabels, formatHhmm: (epoch: number) => string, formatDate: (epoch: number) => string): string;

package/lib/types/projection.d.ts

@@ -0,0 +1,115 @@
+/**
+ * `userSchedules` 会话投影：宿主侧维护的「用户创建的、当前活动的定时提醒」，
+ * 通过 `session/projection` 帧实时推给客户端（GUI 用 `useProjection` 读取）。
+ *
+ * fold 输入两路事件：
+ *  - `schedule/change`：dsh-schedule 的严格 v1 事件（我们写入时与其完全兼容），
+ *    用其导出的 `decodeScheduleChange` 解码；
+ *  - `session-scheduler/user-schedule`：本插件自有的所有权记录（哪种来源）。
+ *
+ * fork 隔离：`session/end-seed` 标记派生会话的耐久边界。投影在遇到该事件时
+ * 重置自身状态（清空 owned/active），因此子会话不继承父会话的提醒（AC-07）。
+ *
+ * 注意 `apply` 为增量 fold：无关事件必须返回同一状态引用，否则会误触发推送。
+ * @module dsh-later/projection
+ */
+import { z } from 'zod';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { ScheduleRecord } from '@deepseek-ai/dsh-schedule';
+import type { UserScheduleProjectionValue } from './domain.js';
+/** 投影 wire 值 schema（wire.viewSchema：离开宿主前校验客户端载荷）。 */
+export declare const userSchedulesSchema: z.ZodObject<{
+    schedules: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodUnion<readonly [z.ZodLiteral<"after">, z.ZodLiteral<"at">, z.ZodLiteral<"every">]>;
+        prompt: z.ZodString;
+        after_seconds: z.ZodOptional<z.ZodNumber>;
+        every_seconds: z.ZodOptional<z.ZodNumber>;
+        scheduled_at: z.ZodString;
+        created_at: z.ZodOptional<z.ZodString>;
+        delivery_mode: z.ZodLiteral<"session-local">;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const userSchedulesStateSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    owned: z.ZodArray<z.ZodString>;
+    active: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodUnion<readonly [z.ZodLiteral<"after">, z.ZodLiteral<"at">, z.ZodLiteral<"every">]>;
+        prompt: z.ZodString;
+        afterSeconds: z.ZodOptional<z.ZodNumber>;
+        everySeconds: z.ZodOptional<z.ZodNumber>;
+        scheduledAt: z.ZodString;
+        createdAt: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+    seedSeq: z.ZodNumber;
+}, z.core.$strip>;
+/** 活动存储记录：dsh-schedule 记录 + 创建时刻（来自 create 事件的 time）。 */
+export type StoredScheduleRecord = ScheduleRecord & {
+    readonly createdAt?: number;
+};
+/** 投影内部状态（plain JSON：owned/active 用数组承载）。 */
+export interface UserScheduleProjectionState {
+    /** 会话 id（init 由 header 注入）。 */
+    readonly sessionId: string;
+    /** 用户工具创建的 schedule id 集合。 */
+    readonly owned: readonly string[];
+    /** 当前活动记录（按 schedule/change 严格 fold）。 */
+    readonly active: readonly StoredScheduleRecord[];
+    /** 已见 `session/end-seed` 的 seq；更早的继承前缀一律忽略。 */
+    readonly seedSeq: number;
+}
+/** 初始状态：按会话 id 从所有权 sidecar 装载（进程重启后恢复 GUI 归属）。 */
+export declare function initUserScheduleProjection(header?: {
+    readonly id?: string;
+}): UserScheduleProjectionState;
+/**
+ * 增量 fold。返回同一引用当事件无关；返回新状态当 owned/active 发生变化。
+ */
+export declare function applyUserScheduleProjection(state: UserScheduleProjectionState, event: SessionEvent): UserScheduleProjectionState;
+/** 投影 view：只暴露用户创建的、当前活动的记录。 */
+export declare function viewUserScheduleProjection(state: UserScheduleProjectionState): UserScheduleProjectionValue;
+/**
+ * 投影单元声明（传给 sessionProjections.register）。
+ *
+ * 形状必须匹配 `ProjectionDefinition`：
+ *  - `stateSchema`（不是 schema）：宿主持久化缓存恢复前校验内部状态；
+ *  - `wire: { viewSchema, view }`（不是顶层 view）：**只有带 wire 的单元才是
+ *    client-visible 的**——`snapshot()`/变更帧都会跳过无 wire 的单元，
+ *    客户端 `useProjection(key)` 将永远读到 undefined。
+ */
+export declare const userSchedulesProjectionUnit: {
+    readonly key: "userSchedules";
+    readonly stateSchema: z.ZodObject<{
+        sessionId: z.ZodString;
+        owned: z.ZodArray<z.ZodString>;
+        active: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodUnion<readonly [z.ZodLiteral<"after">, z.ZodLiteral<"at">, z.ZodLiteral<"every">]>;
+            prompt: z.ZodString;
+            afterSeconds: z.ZodOptional<z.ZodNumber>;
+            everySeconds: z.ZodOptional<z.ZodNumber>;
+            scheduledAt: z.ZodString;
+            createdAt: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
+        seedSeq: z.ZodNumber;
+    }, z.core.$strip>;
+    readonly init: typeof initUserScheduleProjection;
+    readonly apply: typeof applyUserScheduleProjection;
+    readonly wire: {
+        readonly viewSchema: z.ZodObject<{
+            schedules: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                kind: z.ZodUnion<readonly [z.ZodLiteral<"after">, z.ZodLiteral<"at">, z.ZodLiteral<"every">]>;
+                prompt: z.ZodString;
+                after_seconds: z.ZodOptional<z.ZodNumber>;
+                every_seconds: z.ZodOptional<z.ZodNumber>;
+                scheduled_at: z.ZodString;
+                created_at: z.ZodOptional<z.ZodString>;
+                delivery_mode: z.ZodLiteral<"session-local">;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        readonly view: typeof viewUserScheduleProjection;
+    };
+    readonly stateVersion: 3;
+};

package/lib/types/runtime.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 用户提醒的独立调度器（per root agent）。
+ *
+ * 为什么需要它：dsh-schedule 的 runtime 只在三类时机重驱——agent 创建、**其
+ * 自身工具**的持久化变更、agent 转 idle。用户经本插件命令/工具创建的提醒不会
+ * 触发这三类，导致 timer 不武装、不到期触发（GUI 显示任务但永远不 fire）。
+ *
+ * 本调度器只处理**用户创建**的提醒，复用 dsh-schedule 导出的领域函数
+ * （fold / resolveEveryOccurrence / render*Framing）和 `agent.followup`。
+ * 防重复：两套调度器（本插件 + dsh-schedule）都通过**同一份持久化日志**做
+ * 「fold → append dispatch」的原子判断（同一 JS 线程内同步完成），先到者写入
+ * dispatch 事件后，后者 fold 即见已被派发 → 跳过，不会双触发。
+ *
+ * 触发点：用户 create/delete 成功后 requestDrive；agent 转 idle 时也
+ * requestDrive（自愈）；agent 创建时启动。
+ * @module dsh-later/runtime
+ */
+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';
+/** 一次「用户提醒决策」：一批同形态到期一次性、或一批到期固定间隔、或下一次等待目标。
+ *
+ * P1-5：one-shot 从单条改为**同投递形态的批次**——网页关闭期间积压的多条
+ * 到期提醒合并为一条注入消息，而不是逐条刷屏。批次内投递形态必然一致
+ * （`/later` 与 `/schedule` 不同组，各组按时间先后分轮派发）。
+ */
+type UserDecision = {
+    kind: 'one-shot';
+    delivery: UserScheduleDelivery;
+    records: readonly OneShotScheduleRecord[];
+} | {
+    kind: 'every';
+    acceptedAt: string;
+    reminders: readonly {
+        record: EveryScheduleRecord;
+        occurrenceAt: string;
+    }[];
+} | {
+    kind: 'wait';
+    target?: number;
+};
+export declare function dueUserDecision(active: readonly ScheduleRecord[], now: number, delivery?: ReadonlyMap<string, UserScheduleDelivery>): UserDecision;
+/** 每个 agent 的独立调度器。 */
+export declare class UserScheduleRuntime {
+    private readonly ctx;
+    private readonly agent;
+    private readonly stop;
+    private resolveStop;
+    private timer;
+    private run;
+    private requested;
+    private stopping;
+    /** 连续 run 级失败次数（P0-3：用于指数退避，成功一次即清零）。 */
+    private failures;
+    private idleWait;
+    private disposal;
+    constructor(ctx: Context, agent: Agent);
+    /** 是否仍为活动 root agent。 */
+    private isLive;
+    /** 发起一次重算（合并多个触发为一次）。 */
+    requestDrive(): void;
+    /** 清空已武装的 timer。 */
+    private clearTimer;
+    /** 武装一次到下次目标的 timer。 */
+    private arm;
+    /** 串行 drain 合并的触发。 */
+    private runRequested;
+    /** 等待一次 public 的 idle 边界（供 agent 忙碌时重试）。 */
+    private waitForIdle;
+    /** 停止调度器、取消 timer、等待在途派发收敛。 */
+    dispose(): Promise<void>;
+    /**
+     * 用户主动插话（QueueDock「插话发送」语义）：把指定 id 的提醒内容**立即**推给 agent。
+     * - 仅 one-shot（at / after）支持；every 类型因 batch framing 需要更多 plumbing，留待后续
+     * - **不要求已到点**：与 QueueDock 一致，排队中的内容随时可被主动插话提前送达；
+     *   成功即出列（写 dispatch），不会到点再 fire 一次
+     * - 与 fold/dispatch 共享「单一真相」：steer 成功后立即写 `schedule/change: dispatch`，
+     *   否则后续 fold 路径会再 fire 一次（双触发）
+     *
+     * 为什么不用 `runMaintenance`：插话按钮只在 overdue 时出现，而 overdue 恰恰发生在
+     * agent 正在跑（auto-driver 只能 waitForIdle）——`runMaintenance` 在 agent 有活跃工作
+     * 时直接 throw（`agent "..." already has active work`），会让插话在唯一可见的场景里
+     * 必然失败（曾以 `internal_error: 插话执行失败` 落日志）。`agent.steer` 是为「in-flight
+     * 也要在下一个 step boundary 立即消费」设计的原语：空闲则开 turn、忙碌则排到边界，
+     * 不需要空闲。dispatch 事件在同一同步块内 append，与 auto-driver 的 fold 无并发窗口
+     * （JS 单线程；两者要么整块先执行要么整块后执行，后执行者 fold 即见 dispatch 而跳过）。
+     */
+    steerById(id: string): Promise<{
+        ok: true;
+        id: string;
+        steered: true;
+    } | {
+        ok: false;
+        code: string;
+        message: string;
+    }>;
+    /** 执行一次用户提醒决策与派发。 */
+    private driveOnce;
+    /**
+     * 构造注入的消息，按投递形态分流：
+     *  - `user`（`/later` 显式请求的延迟发送）：原样内容 + `source.kind='user'`，
+     *    让 GUI 呈现为「我」发出的普通气泡（产品取舍：用户明确要求以本人身份）。
+     *    跳过 framing 防护 —— 这是「代发」语义，不是注入。
+     *  - `context`（默认）：复用 dsh-schedule 的注入防护 framing + notice 表单，
+     *    保持「上下文注入」的可信审计线；多条一次性到期合并为批次 framing（P1-5），
+     *    形状与 dsh-schedule 的固定间隔批次一致。
+     */
+    private buildMessage;
+}
+export {};

package/lib/types/smart-window.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 智能时段计算（纯函数，host 与 client 共享）。
+ *
+ * 默认时段（v1 硬编码，可经 cordis config 覆盖）：
+ *   工作时间 09:00–18:00
+ *   午休时间 12:00–14:00
+ *   晚间时间 18:00–22:00
+ *   夜间静默 22:00–次日 09:00（不发送）
+ *
+ * 计算在**用户显式选定的 IANA 时区**内进行（不自动推断，确定性优先）。
+ * 墙钟→epoch 的解析采用 dsh-schedule `resolveLocalInstant` 同款偏移校正法，
+ * 避免依赖进程时区。
+ * @module dsh-later/smart-window
+ */
+/** 智能时段配置（HH:mm 格式，可配置）。 */
+export interface SmartWindowConfig {
+    /** 工作时间开始。 */
+    readonly workStart: string;
+    /** 工作时间结束。 */
+    readonly workEnd: string;
+    /** 午休开始。 */
+    readonly lunchStart: string;
+    /** 午休结束。 */
+    readonly lunchEnd: string;
+    /** 晚间结束（夜间静默起点）。 */
+    readonly eveningEnd: string;
+}
+/** 默认时段。 */
+export declare const DEFAULT_SMART_WINDOW: SmartWindowConfig;
+/** 校验一个 HH:mm 字符串。 */
+export declare function isValidHhmm(value: unknown): value is string;
+/**
+ * 清洗用户/配置层提供的时段字段：非法或缺省的字段逐项回落默认值
+ * （host schema 与 client 设置面共用；保证下游 `nextSmartTarget` 永不因脏输入抛错）。
+ */
+export declare function sanitizeSmartWindowConfig(raw: Partial<Record<keyof SmartWindowConfig, unknown>> | undefined | null): SmartWindowConfig;
+/** 两次提醒之间至少等待的毫秒数（智能模式下）。 */
+export declare const SMART_MIN_DELAY_MS: number;
+/** 一小时/一天的毫秒数。 */
+export declare const MINUTE_MS: number;
+export declare const HOUR_MS: number;
+export declare const DAY_MS: number;
+/** 当日第几分钟（0–1439）。 */
+export type DayMinutes = number;
+/** 本地日历字段。 */
+export interface LocalFields {
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+    readonly hour: number;
+    readonly minute: number;
+    readonly second: number;
+}
+/**
+ * 把 "HH:mm" 解析为当日第几分钟；非法返回 undefined。
+ */
+export declare function hhmmToMinutes(value: string): DayMinutes | undefined;
+/** 把当日第几分钟格式化为 "HH:mm"。 */
+export declare function minutesToHhmm(minutes: DayMinutes): string;
+/**
+ * 可配置时段是否有效：所有边界均为合法 HH:mm 且满足
+ * workStart < lunchStart < lunchEnd < workEnd < eveningEnd。
+ */
+export declare function isValidWindow(window: SmartWindowConfig): boolean;
+/** 取整到整分钟（秒、毫秒清零）。 */
+export declare function floorToMinute(epoch: number): number;
+/** 把 epoch 投影到指定时区的本地日历字段。 */
+export declare function localFieldsOf(epoch: number, timeZone: string): LocalFields;
+/**
+ * 解析一个本地墙钟时刻（hour/min 表示，sec=00）在指定时区内对应的 epoch。
+ * 采用「偏移校正」法：把墙钟当 UTC 构造候选，再用采样偏移反推真实 epoch，
+ * 并验证映射回原墙钟字段；DST 重叠取最早候选，缺口会导致无候选。
+ */
+export declare function resolveWallClock(epochOnDay: number, timeZone: string, hour: number, minute: number, second?: number): number | undefined;
+/**
+ * 计算下一个智能时段的本地墙钟目标。
+ *
+ * 规则：
+ *  - 若当前在午休时段（lunchStart ≤ now < lunchEnd）→ 目标为 now + 2 分钟；
+ *  - 否则候选为下一个 工作开始 / 午休结束 / 晚间开始（均 > now + 2 分钟），取最早者；
+ *  - 夜间静默（≥ eveningEnd 或 < workStart）自然被「下一个工作开始」覆盖。
+ *
+ * @param now - 当前墙钟 epoch 毫秒。
+ * @param timeZone - 用户显式选定的 IANA 时区。
+ * @param window - 时段配置（默认 {@link DEFAULT_SMART_WINDOW}）。
+ * @returns 目标 epoch 毫秒（严格位于未来，且至少 SMART_MIN_DELAY_MS 之后）。
+ */
+export declare function nextSmartTarget(now: number, timeZone: string, window?: SmartWindowConfig): number;
+/**
+ * 把本地墙钟字符串（date YYYY-MM-DD、time HH:mm[:ss]）在指定时区解析为 epoch。
+ * 用于自定义时间的预览与合法性校验。解析失败返回 undefined（如 DST 缺口）。
+ */
+export declare function epochFromLocal(date: string, time: string, timeZone: string): number | undefined;
+/**
+ * 智能模式的一站式目标构造：返回可直接作为 `at` 对象使用的本地日历字段。
+ * @returns null 当配置非法或无法解析时。
+ */
+export declare function nextSmartAt(now: number, timeZone: string, window?: SmartWindowConfig): {
+    date: string;
+    time: string;
+    time_zone: string;
+    epoch: number;
+} | null;

package/lib/types/time-utils.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 时间格式化与通用工具（纯函数，host 与 client 共享）。
+ * 文案遵循 docs/ui/08-microcopy.md 的微文案规范。
+ * @module dsh-later/time-utils
+ */
+/** 校验一个字符串是否为合法 IANA 时区（或 UTC）。 */
+export declare function isValidTimeZone(value: string): boolean;
+/** 浏览器默认时区（客户端）；host 侧无合理默认则退回 UTC。 */
+export declare function detectTimeZone(): string;
+/** 常见时区候选（面板下拉用）。 */
+export declare const COMMON_TIME_ZONES: readonly string[];
+/** 文案语言 id（zh 中文；en 英文；其余回退中文）。 */
+export type TextLocale = 'zh' | 'en';
+/**
+ * 相对时间文案：zh "约 X 分钟后"；en "in ~X minutes" 等。
+ * @param epoch - 目标 epoch 毫秒。
+ * @param now - 当前 epoch 毫秒（默认 Date.now()）。
+ * @param locale - 文案语言（默认 zh，host 侧无浏览器语境保持中文）。
+ */
+export declare function formatRelative(epoch: number, now?: number, locale?: TextLocale): string;
+/** 毫秒常量（避免依赖 smart-window 再复制）。 */
+export declare const MINUTE_MS: number;
+export declare const HOUR_MS: number;
+export declare const DAY_MS: number;
+/**
+ * 完整时间文案：zh "{M}月{d}日 {周X} HH:mm"、en "Wed, Aug 26, 14:45"（按指定时区）。
+ */
+export declare function formatAbsolute(epoch: number, timeZone: string, locale?: TextLocale): string;
+/** 仅时间部分 "HH:mm"（按指定时区）。 */
+export declare function formatHhmm(epoch: number, timeZone: string): string;
+/** 周期几第几天（与 formatAbsolute 里的 wkday 词对齐）。 */
+export declare function weekdayLabel(epoch: number, timeZone: string): string;
+/**
+ * 倒计时 "HH:MM:SS"（或剩余不足 1 小时时 "MM:SS"）。
+ */
+export declare function formatCountdown(epoch: number, now?: number): string;
+/** 未来距离（毫秒）；用于紧急度判断。 */
+export declare function remainingMs(epoch: number, now?: number): number;
+/**
+ * 构造 `at` 对象：{date, time, time_zone}。
+ * @param epoch - 目标 epoch 毫秒。
+ * @param timeZone - IANA 时区。
+ */
+export declare function atObjectOf(epoch: number, timeZone: string): {
+    date: string;
+    time: string;
+    time_zone: string;
+};

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

@@ -0,0 +1,176 @@
+/**
+ * 用户工具核心实现：`user_schedule_create` / `user_schedule_list` /
+ * `user_schedule_delete`。
+ *
+ * 复用 dsh-schedule 导出的领域函数（fold / allocate / 各 create 函数 /
+ * scheduleView），写入**完全兼容**的 `schedule/change` 事件（不携带 `source`
+ * 字段，避免破坏 dsh-schedule 严格解码）。
+ *
+ * 用户来源（所有权 + 投递形态）记录在**插件自己的 sidecar 文件**里
+ * （ownership-store.ts），**不再写入会话日志**——2026-09 根治：伴生事件
+ * `session-scheduler/user-schedule` 曾因宿主持久化静默丢行而留下永久 seq
+ * 缺口，让整份历史被拒读。日志里若仍残留旧的伴生事件（历史日志），fold
+ * 会继续读取（读兼容），但本模块不再产生它们。
+ *
+ * 所有读改写操作按 agent 串行化（同 dsh-schedule 的 agent-scoped 队列），
+ * 保证 id 分配与 fold 不会并发竞争。
+ * @module dsh-later/user-tools
+ */
+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';
+/** 单 session 用户任务上限（PRD：防滥用）。 */
+export declare const DEFAULT_MAX_SCHEDULES = 100;
+/**
+ * 经过 trim 后允许的默认最大提示字符数（P0：注入防护的保守下限）。
+ *
+ * 当 settings 中 `allowLongPrompts=false` 时此值始终生效；为 `true` 时
+ * 由 `maxPromptChars` 字段接管实际字符上限。用户必须显式 opt-in 才解除
+ * 该硬上限——保持默认安全的姿态。
+ */
+export declare const DEFAULT_MAX_PROMPT_CHARS = 1000;
+/** 用户工具的提示字符上限策略（来自插件 settings）。 */
+export interface PromptLimits {
+    /** 是否解除 `DEFAULT_MAX_PROMPT_CHARS` 硬上限；未开启时 maxChars 始终等于默认值。 */
+    readonly allowLong: boolean;
+    /** 当前允许的最大字符数（已根据 allowLong 解析过）。 */
+    readonly maxChars: number;
+}
+/**
+ * 从 settings 解析出实际生效的 PromptLimits。
+ * 容错非法值（NaN / 负数 / 非数）回落 DEFAULT_MAX_PROMPT_CHARS。
+ */
+export declare function resolvePromptLimits(settings: {
+    readonly allowLongPrompts?: boolean;
+    readonly maxPromptChars?: number;
+} | undefined): PromptLimits;
+/** 单条提示的字符校验（纯函数）。返回 trim 后的字符串或闭包错误。 */
+export declare function validatePrompt(raw: unknown, limits: PromptLimits): {
+    ok: true;
+    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 interface UserScheduleError {
+    readonly ok: false;
+    readonly code: UserScheduleErrorCode;
+    readonly message: string;
+}
+/** 成功值。 */
+export type UserScheduleResult<TSuccess> = TSuccess | UserScheduleError;
+/** `user_schedule_create` 成功响应。 */
+export type UserScheduleCreateResult = UserScheduleResult<ScheduleRecordView & {
+    readonly ok: true;
+}>;
+/** `user_schedule_list` 成功响应。 */
+export type UserScheduleListResult = UserScheduleResult<{
+    readonly ok: true;
+    readonly schedules: readonly ScheduleRecordView[];
+}>;
+/** `user_schedule_delete` 成功响应。 */
+export type UserScheduleDeleteResult = UserScheduleResult<{
+    readonly ok: true;
+    readonly id: string;
+    readonly deleted: true;
+} | {
+    readonly ok: true;
+    readonly id: string;
+    readonly deleted: false;
+    readonly code: 'schedule_not_found';
+}>;
+/** `user_schedule_create` 的规范化输入。 */
+export interface UserScheduleCreateInput {
+    readonly prompt: string;
+    readonly time_zone: string;
+    readonly after_seconds?: number;
+    readonly at?: string | {
+        readonly date: string;
+        readonly time: string;
+        readonly time_zone: string;
+    };
+    readonly every_seconds?: number;
+}
+/** 校验 `user_schedule_create` 参数（纯函数，含 TRIM 非空、长度、三选一）。
+ *
+ * `limits` 可选：未传时回落到 `DEFAULT_MAX_PROMPT_CHARS`（保持向后兼容）；
+ * 命令与工具的注册路径会按当前 settings 传入实际 limits，校验消息会反映
+ * 当前生效的字符上限（与模型可见的 tool description 同步）。
+ */
+export declare function validateCreateInput(input: unknown, limits?: PromptLimits): {
+    ok: true;
+    value: UserScheduleCreateInput;
+} | UserScheduleError;
+/** 校验 IANA 时区（与 dsh-schedule canonicalize 同源，容错）。 */
+export declare function isValidIanaZone(value: string): boolean;
+/** 从会话日志导出「用户创建过的 schedule id 集合」（历史遗留读兼容）。 */
+export declare function foldOwnedIds(events: readonly SessionEvent[]): Set<string>;
+/**
+ * 从会话日志导出「schedule id → 到点注入形态」映射（默认 `context`）。
+ * 供 runtime 在 dispatch 时按 `/later` 与 `/schedule` 分别注入。
+ */
+export declare function foldOwnedDelivery(events: readonly SessionEvent[]): ReadonlyMap<string, UserScheduleDelivery>;
+/**
+ * 会话级 fold 缓存（P1-6）：事件日志只增不改（事件溯源），
+ * 按「数组身份 + 长度」判定命中——append 原地 push 使长度变化即失效；
+ * 整体换数组则身份不同也失效。两种实现风格下都安全。
+ *
+ * 消除热路径（每次 drive / 每次工具调用）对全量日志的重复 O(n) 扫描。
+ */
+export interface UserFoldState {
+    readonly folded: ReturnType<typeof foldScheduleEvents>;
+    readonly owned: ReadonlySet<string>;
+    readonly delivery: ReadonlyMap<string, UserScheduleDelivery>;
+}
+/** fold 当前会话的完整用户调度状态（带缓存；调用方不得变更返回值）。
+ *
+ * 跨代兼容：0.1.1 暴露 `session.events` + `header.seedLength`；0.1.2 改名
+ * 为 `session.ownEvents()` + `session.inheritedEventCount`。通过鸭子类型
+ * （`(session as { ownEvents?; events? })`）双轨探测，不引入 `any`。
+ */
+export declare function foldUserState(session: Session): UserFoldState;
+/** 稳定内部错误（不透出异常细节）。 */
+export declare function internalError(): UserScheduleError;
+/** 稳定持久化不确定错误。 */
+export declare function persistenceError(): UserScheduleError;
+/** 把 dsh-schedule 的 ScheduleInputError 翻译为闭包错误值。 */
+export declare function toInputError(error: unknown): UserScheduleError;
+/** 记录视图的 snake_case 序列化。 */
+export type ScheduleRecordView = {
+    readonly id: string;
+    readonly kind: ScheduleRecord['kind'];
+    readonly prompt: string;
+    readonly after_seconds?: number;
+    readonly every_seconds?: number;
+    readonly scheduled_at: string;
+    readonly state: 'scheduled' | 'overdue';
+    readonly delivery_mode: 'session-local';
+    readonly source: 'user-tool';
+};
+/** 把 dsh-schedule 的 view 序列化为 snake_case 记录。 */
+export declare function serializeScheduleView(view: ScheduleView): ScheduleRecordView;
+/** 在当前 agent 的事务尾之后运行操作。 */
+export declare function runUserScheduleTransaction<T>(agent: Agent, operation: () => Promise<T>): Promise<T>;
+/**
+ * `user_schedule_create` 的可信通道选项。
+ *
+ * 安全边界（P0-1）：`delivery:'user'`（到点以用户身份代发，绕过注入防护）只能
+ * 由人类显式输入的 `/later` 命令经 `trustedDelivery` **显式声明**——原始输入里的
+ * 同名字段一律被忽略。模型工具与 GUI 面板通道不传该选项，永远得到安全的
+ * `context` 注入形态；即使模型在工具参数里夹带 `delivery:'user'` 也无效。
+ */
+export interface UserScheduleCreateOptions {
+    /** 可信通道显式声明的投递形态；未提供或非 'user' 一律按安全默认 'context'。 */
+    readonly trustedDelivery?: UserScheduleDelivery;
+}
+/** `user_schedule_create` 核心实现。 */
+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` 核心实现。 */
+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>;