dsh-later 1.0.0

package/lib/smart-window.js

@@ -0,0 +1,260 @@
+/**
+ * 智能时段计算（纯函数，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
+ */
+/** 默认时段。 */
+export const DEFAULT_SMART_WINDOW = Object.freeze({
+    workStart: '09:00',
+    workEnd: '18:00',
+    lunchStart: '12:00',
+    lunchEnd: '14:00',
+    eveningEnd: '22:00',
+});
+/** HH:mm（24 小时制）格式。 */
+const HHMM_RE = /^([01]\d|2[0-3]):[0-5]\d$/;
+/** 校验一个 HH:mm 字符串。 */
+export function isValidHhmm(value) {
+    return typeof value === 'string' && HHMM_RE.test(value);
+}
+/**
+ * 清洗用户/配置层提供的时段字段：非法或缺省的字段逐项回落默认值
+ * （host schema 与 client 设置面共用；保证下游 `nextSmartTarget` 永不因脏输入抛错）。
+ */
+export function sanitizeSmartWindowConfig(raw) {
+    const pick = (key, fallback) => isValidHhmm(raw?.[key]) ? raw[key] : fallback;
+    return {
+        workStart: pick('workStart', DEFAULT_SMART_WINDOW.workStart),
+        workEnd: pick('workEnd', DEFAULT_SMART_WINDOW.workEnd),
+        lunchStart: pick('lunchStart', DEFAULT_SMART_WINDOW.lunchStart),
+        lunchEnd: pick('lunchEnd', DEFAULT_SMART_WINDOW.lunchEnd),
+        eveningEnd: pick('eveningEnd', DEFAULT_SMART_WINDOW.eveningEnd),
+    };
+}
+/** 两次提醒之间至少等待的毫秒数（智能模式下）。 */
+export const SMART_MIN_DELAY_MS = 2 * 60 * 1000;
+/** 一小时/一天的毫秒数。 */
+export const MINUTE_MS = 60 * 1000;
+export const HOUR_MS = 60 * MINUTE_MS;
+export const DAY_MS = 24 * HOUR_MS;
+/**
+ * 把 "HH:mm" 解析为当日第几分钟；非法返回 undefined。
+ */
+export function hhmmToMinutes(value) {
+    const match = /^(\d{2}):(\d{2})$/.exec(value.trim());
+    if (match === null)
+        return undefined;
+    const hour = Number(match[1]);
+    const minute = Number(match[2]);
+    if (hour > 23 || minute > 59)
+        return undefined;
+    return hour * 60 + minute;
+}
+/** 把当日第几分钟格式化为 "HH:mm"。 */
+export function minutesToHhmm(minutes) {
+    const hour = Math.floor(minutes / 60);
+    const minute = minutes % 60;
+    return `${String(hour).padStart(2, '0')}:${String(minute).padStart(2, '0')}`;
+}
+/**
+ * 可配置时段是否有效：所有边界均为合法 HH:mm 且满足
+ * workStart < lunchStart < lunchEnd < workEnd < eveningEnd。
+ */
+export function isValidWindow(window) {
+    const order = [
+        hhmmToMinutes(window.workStart),
+        hhmmToMinutes(window.lunchStart),
+        hhmmToMinutes(window.lunchEnd),
+        hhmmToMinutes(window.workEnd),
+        hhmmToMinutes(window.eveningEnd),
+    ];
+    if (order.some((value) => value === undefined))
+        return false;
+    return (order[0] < order[1] &&
+        order[1] < order[2] &&
+        order[2] < order[3] &&
+        order[3] < order[4]);
+}
+/** 取整到整分钟（秒、毫秒清零）。 */
+export function floorToMinute(epoch) {
+    return Math.floor(epoch / MINUTE_MS) * MINUTE_MS;
+}
+/** 为该时区构建一个 ISO 投影 formatter（含长期偏移）。 */
+function formatterFor(timeZone) {
+    return new Intl.DateTimeFormat('en-US-u-ca-iso8601-nu-latn', {
+        timeZone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hourCycle: 'h23',
+    });
+}
+/** 把 epoch 投影到指定时区的本地日历字段。 */
+export function localFieldsOf(epoch, timeZone) {
+    const formatter = formatterFor(timeZone);
+    const parts = Object.fromEntries(formatter.formatToParts(epoch).map((part) => [part.type, part.value]));
+    return {
+        year: Number(parts['year']),
+        month: Number(parts['month']),
+        day: Number(parts['day']),
+        hour: Number(parts['hour']),
+        minute: Number(parts['minute']),
+        second: Number(parts['second']),
+    };
+}
+/** 该 epoch 在指定时区的 UTC 偏移（毫秒）：local − UTC。 */
+function offsetOf(epoch, timeZone) {
+    const f = localFieldsOf(epoch, timeZone);
+    return Date.UTC(f.year, f.month - 1, f.day, f.hour, f.minute, f.second, 0) - epoch;
+}
+/**
+ * 解析一个本地墙钟时刻（hour/min 表示，sec=00）在指定时区内对应的 epoch。
+ * 采用「偏移校正」法：把墙钟当 UTC 构造候选，再用采样偏移反推真实 epoch，
+ * 并验证映射回原墙钟字段；DST 重叠取最早候选，缺口会导致无候选。
+ */
+export function resolveWallClock(epochOnDay, timeZone, hour, minute, second = 0) {
+    const base = localFieldsOf(epochOnDay, timeZone);
+    const localEpoch = Date.UTC(base.year, base.month - 1, base.day, hour, minute, second, 0);
+    const offsets = new Set();
+    for (let delta = -2; delta <= 2; delta += 1) {
+        offsets.add(offsetOf(localEpoch + delta * DAY_MS, timeZone));
+    }
+    const candidates = [];
+    for (const offset of offsets) {
+        const candidate = localEpoch - offset;
+        const f = localFieldsOf(candidate, timeZone);
+        if (f.year === base.year &&
+            f.month === base.month &&
+            f.day === base.day &&
+            f.hour === hour &&
+            f.minute === minute &&
+            f.second === second) {
+            candidates.push(candidate);
+        }
+    }
+    candidates.sort((a, b) => a - b);
+    return candidates[0];
+}
+/** 求「下一个严格晚于 now 的本地 HH:mm 时刻」的 epoch。 */
+function nextMinutesAfter(now, timeZone, minutes) {
+    const hour = Math.floor(minutes / 60);
+    const minute = minutes % 60;
+    let probe = resolveWallClock(now, timeZone, hour, minute);
+    if (probe === undefined) {
+        // DST 缺口：该墙钟时刻当天不存在，跳到次日
+        probe = resolveWallClock(now + DAY_MS, timeZone, hour, minute);
+    }
+    if (probe === undefined) {
+        // 兜底：按纯 UTC 猜测
+        return Date.UTC(localFieldsOf(now, timeZone).year, localFieldsOf(now, timeZone).month - 1, localFieldsOf(now, timeZone).day, hour, minute, 0, 0);
+    }
+    if (probe > now)
+        return probe;
+    const nextDay = resolveWallClock(probe + DAY_MS, timeZone, hour, minute) ?? probe + DAY_MS;
+    return nextDay > now ? nextDay : nextDay + DAY_MS;
+}
+/**
+ * 计算下一个智能时段的本地墙钟目标。
+ *
+ * 规则：
+ *  - 若当前在午休时段（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 function nextSmartTarget(now, timeZone, window = DEFAULT_SMART_WINDOW) {
+    if (!isValidWindow(window))
+        throw new TypeError('smart window configuration is invalid');
+    const fields = localFieldsOf(now, timeZone);
+    const minutes = fields.hour * 60 + fields.minute;
+    const lunchStart = hhmmToMinutes(window.lunchStart);
+    const lunchEnd = hhmmToMinutes(window.lunchEnd);
+    // 午休优先：直接 now + 2 分钟
+    if (minutes >= lunchStart && minutes < lunchEnd) {
+        return now + SMART_MIN_DELAY_MS;
+    }
+    const workStart = hhmmToMinutes(window.workStart);
+    const eveningStart = hhmmToMinutes(window.workEnd); // 工作结束 = 晚间开始
+    const candidates = [
+        nextMinutesAfter(now, timeZone, workStart),
+        nextMinutesAfter(now, timeZone, lunchEnd),
+        nextMinutesAfter(now, timeZone, eveningStart),
+    ].filter((target) => target > now + SMART_MIN_DELAY_MS);
+    if (candidates.length === 0) {
+        const earliest = Math.min(nextMinutesAfter(now, timeZone, workStart), nextMinutesAfter(now, timeZone, lunchEnd), nextMinutesAfter(now, timeZone, eveningStart));
+        return Math.max(earliest, now + SMART_MIN_DELAY_MS);
+    }
+    return Math.min(...candidates);
+}
+/**
+ * 把本地墙钟字符串（date YYYY-MM-DD、time HH:mm[:ss]）在指定时区解析为 epoch。
+ * 用于自定义时间的预览与合法性校验。解析失败返回 undefined（如 DST 缺口）。
+ */
+export function epochFromLocal(date, time, timeZone) {
+    const dateMatch = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+    const timeMatch = /^(\d{2}):(\d{2})(?::(\d{2}))?$/.exec(time);
+    if (dateMatch === null || timeMatch === null)
+        return undefined;
+    const year = Number(dateMatch[1]);
+    const month = Number(dateMatch[2]);
+    const day = Number(dateMatch[3]);
+    const hour = Number(timeMatch[1]);
+    const minute = Number(timeMatch[2]);
+    const second = Number(timeMatch[3] ?? '0');
+    if (hour > 23 ||
+        minute > 59 ||
+        second > 59 ||
+        month < 1 ||
+        month > 12 ||
+        day < 1 ||
+        day > 31) {
+        return undefined;
+    }
+    // 以纯 UTC 构造「当日近似 epoch」作为锚点，再用偏移校正解析真实墙钟时刻。
+    const approx = Date.UTC(year, month - 1, day, 0, 0, 0, 0);
+    return resolveWallClock(approx, timeZone, hour, minute, second);
+}
+/**
+ * 智能模式的一站式目标构造：返回可直接作为 `at` 对象使用的本地日历字段。
+ * @returns null 当配置非法或无法解析时。
+ */
+export function nextSmartAt(now, timeZone, window = DEFAULT_SMART_WINDOW) {
+    let target;
+    try {
+        target = nextSmartTarget(now, timeZone, window);
+    }
+    catch {
+        return null;
+    }
+    let parts;
+    try {
+        parts = localFieldsOf(target, timeZone);
+    }
+    catch {
+        return null;
+    }
+    const date = `${String(parts.year).padStart(4, '0')}-${String(parts.month).padStart(2, '0')}-${String(parts.day).padStart(2, '0')}`;
+    const time = `${String(parts.hour).padStart(2, '0')}:${String(parts.minute).padStart(2, '0')}:${String(parts.second).padStart(2, '0')}`;
+    return {
+        date,
+        time,
+        time_zone: timeZone,
+        epoch: target,
+    };
+}

package/lib/time-utils.js

@@ -0,0 +1,170 @@
+/**
+ * 时间格式化与通用工具（纯函数，host 与 client 共享）。
+ * 文案遵循 docs/ui/08-microcopy.md 的微文案规范。
+ * @module dsh-later/time-utils
+ */
+/** 校验一个字符串是否为合法 IANA 时区（或 UTC）。 */
+export function isValidTimeZone(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return false;
+    try {
+        const resolved = new Intl.DateTimeFormat('en-US', { timeZone: value }).resolvedOptions().timeZone;
+        return resolved === value || value === 'UTC';
+    }
+    catch {
+        return false;
+    }
+}
+/** 浏览器默认时区（客户端）；host 侧无合理默认则退回 UTC。 */
+export function detectTimeZone() {
+    try {
+        const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        return tz?.length ? tz : 'UTC';
+    }
+    catch {
+        return 'UTC';
+    }
+}
+/** 常见时区候选（面板下拉用）。 */
+export const COMMON_TIME_ZONES = [
+    'Asia/Shanghai',
+    'Asia/Tokyo',
+    'Asia/Singapore',
+    'Asia/Hong_Kong',
+    'UTC',
+    'America/Los_Angeles',
+    'America/New_York',
+    'Europe/London',
+    'Europe/Paris',
+];
+/**
+ * 相对时间文案：zh "约 X 分钟后"；en "in ~X minutes" 等。
+ * @param epoch - 目标 epoch 毫秒。
+ * @param now - 当前 epoch 毫秒（默认 Date.now()）。
+ * @param locale - 文案语言（默认 zh，host 侧无浏览器语境保持中文）。
+ */
+export function formatRelative(epoch, now = Date.now(), locale = 'zh') {
+    const diff = epoch - now;
+    if (locale === 'en') {
+        if (diff < 0)
+            return 'overdue';
+        if (diff < MINUTE_MS)
+            return 'sending soon';
+        const minutes = Math.round(diff / MINUTE_MS);
+        if (minutes < 60)
+            return `in ~${minutes} min`;
+        const hours = Math.floor(minutes / 60);
+        const restMinutes = minutes % 60;
+        if (hours < 24) {
+            return restMinutes === 0 ? `in ~${hours} h` : `in ~${hours} h ${restMinutes} min`;
+        }
+        const days = Math.floor(hours / 24);
+        return `in ~${days} days`;
+    }
+    if (diff < 0)
+        return '已到期';
+    if (diff < MINUTE_MS)
+        return '即将发送';
+    const minutes = Math.round(diff / MINUTE_MS);
+    if (minutes < 60)
+        return `约 ${minutes} 分钟后`;
+    const hours = Math.floor(minutes / 60);
+    const restMinutes = minutes % 60;
+    if (hours < 24) {
+        return restMinutes === 0 ? `约 ${hours} 小时后` : `约 ${hours} 小时 ${restMinutes} 分后`;
+    }
+    const days = Math.floor(hours / 24);
+    return `约 ${days} 天后`;
+}
+/** 毫秒常量（避免依赖 smart-window 再复制）。 */
+export const MINUTE_MS = 60 * 1000;
+export const HOUR_MS = 60 * MINUTE_MS;
+export const DAY_MS = 24 * HOUR_MS;
+/** 周几中文缩写。 */
+const WEEKDAYS = ['周日', '周一', '周二', '周三', '周四', '周五', '周六'];
+/**
+ * 完整时间文案：zh "{M}月{d}日 {周X} HH:mm"、en "Wed, Aug 26, 14:45"（按指定时区）。
+ */
+export function formatAbsolute(epoch, timeZone, locale = 'zh') {
+    const formatter = new Intl.DateTimeFormat(locale === 'en' ? 'en-US' : 'zh-CN', {
+        timeZone,
+        month: 'numeric',
+        day: 'numeric',
+        weekday: 'short',
+        hour: '2-digit',
+        minute: '2-digit',
+        hourCycle: 'h23',
+    });
+    return formatter.format(epoch).replace(/\s+/g, ' ');
+}
+/** 仅时间部分 "HH:mm"（按指定时区）。 */
+export function formatHhmm(epoch, timeZone) {
+    const formatter = new Intl.DateTimeFormat('en-GB-u-ca-iso8601-nu-latn', {
+        timeZone,
+        hour: '2-digit',
+        minute: '2-digit',
+        hourCycle: 'h23',
+    });
+    return formatter.format(epoch);
+}
+/** 周期几第几天（与 formatAbsolute 里的 wkday 词对齐）。 */
+export function weekdayLabel(epoch, timeZone) {
+    const weekday = new Intl.DateTimeFormat('en-US-u-ca-iso8601-nu-latn', {
+        timeZone,
+        weekday: 'short',
+    }).format(epoch);
+    const map = {
+        Sun: '周日',
+        Mon: '周一',
+        Tue: '周二',
+        Wed: '周三',
+        Thu: '周四',
+        Fri: '周五',
+        Sat: '周六',
+    };
+    return map[weekday] ?? weekday;
+}
+/**
+ * 倒计时 "HH:MM:SS"（或剩余不足 1 小时时 "MM:SS"）。
+ */
+export function formatCountdown(epoch, now = Date.now()) {
+    const remain = Math.max(0, epoch - now);
+    const totalSeconds = Math.floor(remain / 1000);
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    const mm = String(minutes).padStart(2, '0');
+    const ss = String(seconds).padStart(2, '0');
+    if (hours > 0)
+        return `${String(hours).padStart(2, '0')}:${mm}:${ss}`;
+    return `${mm}:${ss}`;
+}
+/** 未来距离（毫秒）；用于紧急度判断。 */
+export function remainingMs(epoch, now = Date.now()) {
+    return Math.max(0, epoch - now);
+}
+/**
+ * 构造 `at` 对象：{date, time, time_zone}。
+ * @param epoch - 目标 epoch 毫秒。
+ * @param timeZone - IANA 时区。
+ */
+export function atObjectOf(epoch, timeZone) {
+    const parts = new Intl.DateTimeFormat('en-US-u-ca-iso8601-nu-latn', {
+        timeZone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hourCycle: 'h23',
+    }).formatToParts(epoch);
+    const map = {};
+    for (const part of parts)
+        map[part.type] = part.value;
+    return {
+        date: `${map['year']}-${map['month']}-${map['day']}`,
+        time: `${map['hour']}:${map['minute']}:${map['second']}`,
+        time_zone: timeZone,
+    };
+}

package/lib/types/commands.d.ts

@@ -0,0 +1,109 @@
+/**
+ * 客户端 → host 变更通道：通过 DSH 的 slash-command 一等机制把 GUI 的
+ * 创建/删除/列表请求送到宿主，由 handler 复用 `user-tools` 一次性写入会话日志。
+ *
+ * 为什么不用 Typert Remote：命令 handler 直接携带 `agent`，天然按会话路由，
+ * 且 `command/run` / `command/done` 自动落日志（审计友好）。`recordInput: false`
+ * 避免把 GUI 的 JSON 载荷重复写进日志（权威载荷在 domain 事件里）。
+ *
+ * 客户端经 `session.command('/user-schedule-create <json>')` 调用；
+ * 返回的 `RemoteResult<{matched}>` 只表达“已受理”，状态以 `userSchedules`
+ * 投影回流（commands 框架本身的 admission 语义）。
+ * @module dsh-later/commands
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { CommandDefinition } from '@deepseek-ai/dsh-commands';
+import type { PromptLimits } from './user-tools.js';
+/** 用户创建/删除成功后的通知回调（宿主用它重驱用户调度器）。 */
+export type UserChangeNotifier = (agent: Agent) => void;
+/**
+ * 用户主动插话回调（GUI「插话发送」按钮触发）。handler 返回 steer 结果；
+ * - `{ ok: true, steered: true }` 表示已成功把消息立即推给 in-flight agent；
+ * - `{ ok: false, code }` 表示拒绝（未到点 / 不存在 / every 类型暂不支持）。
+ * @module dsh-later/commands
+ */
+export type UserSteerHandler = (agent: Agent, id: string) => Promise<{
+    readonly ok: true;
+    readonly id: string;
+    readonly steered: true;
+} | {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+}>;
+/** `parseScheduleSpec` 的结果。 */
+export type ParsedScheduleSpec = {
+    ok: true;
+    kind: 'after';
+    afterSeconds: number;
+} | {
+    ok: true;
+    kind: 'at';
+    at: {
+        date: string;
+        time: string;
+        time_zone: string;
+    };
+    epoch: number;
+} | {
+    ok: false;
+    error: string;
+};
+/** `parseScheduleInput` 的结果：时间目标 + 剩余内容。 */
+export type ParsedScheduleInput = {
+    ok: true;
+    target: {
+        kind: 'after';
+        afterSeconds: number;
+    } | {
+        kind: 'at';
+        at: {
+            date: string;
+            time: string;
+            time_zone: string;
+        };
+        epoch: number;
+    };
+    content: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * 解析 `/schedule` 的完整输入：开头的时间表达式 + 剩余内容。
+ *
+ * 支持格式（示例）：
+ *  - `+30m` `+1h30m` `+90s` `+1w`
+ *  - `30分钟后` `半小时后` `两小时后` `1天以后`
+ *  - `1532` `15:32` `15：32` `15时32分` `9点` `9点半`
+ *  - `明天 15:32` `后天9点` `大后天 10:00`
+ *  - `8月21日 15:32` `08-21 15:32`
+ *  - `2026-08-21 15:32` `0821-1532` `20260821-1532`
+ *
+ * `limits` 可选：未传时回落到 `DEFAULT_MAX_PROMPT_CHARS=1000`，错误文案里
+ * 的字符数与 settings 实际生效值一致。
+ */
+export declare function parseScheduleInput(raw: string, now: number, timeZone: string, limits?: PromptLimits): ParsedScheduleInput;
+/**
+ * 兼容旧签名：解析纯时间描述（不含内容）。
+ */
+export declare function parseScheduleSpec(spec: string, now: number, timeZone: string): ParsedScheduleSpec;
+/** 命令工厂：返回三个命令定义。
+ *
+ * `getSettings` 支持传数字（静态，兼容旧签名）、返回 `{maxSchedules}` 的 getter，
+ * `() => { maxSchedules, allowLongPrompts, maxPromptChars }` 的 getter——传 getter
+ * 时每次调用读取设置页的**实时**上限（设置保存后即时生效，按需 scope.get()，
+ * 与 dsh-smooth-stream 一致）。
+ */
+export declare function userScheduleCommands(ctx: Context, getSettings?: number | (() => number) | (() => {
+    maxSchedules: number;
+    allowLongPrompts?: boolean;
+    maxPromptChars?: number;
+}), onUserChange?: UserChangeNotifier, onUserSteer?: UserSteerHandler): CommandDefinition[];
+/** 注册三个命令，返回统一 disposer。 */
+export declare function registerUserScheduleCommands(ctx: Context, getSettings?: number | (() => number) | (() => {
+    maxSchedules: number;
+    allowLongPrompts?: boolean;
+    maxPromptChars?: number;
+}), onUserChange?: UserChangeNotifier, onUserSteer?: UserSteerHandler): () => void;

package/lib/types/domain.d.ts

@@ -0,0 +1,109 @@
+/**
+ * dsh-later 领域类型与事件荷载。
+ *
+ * 兼容性说明（关键设计决策）：
+ * dsh-schedule 对 `schedule/change` 荷载采用严格解码（`hasExactKeys` 拒绝任何
+ * 多余字段）。因此本插件**不会**在 `schedule/change` 里追加 `source` 字段——
+ * 那会让 dsh-schedule 自身 fold 抛 `corrupt_schedule_log`，破坏 AC-20 互不干扰。
+ * 用户来源**不再**用伴生会话事件记录（2026-09 根治）：曾用自有事件
+ * `session-scheduler/user-schedule` 写进会话日志，但该类型不在宿主词汇表内，
+ * 持久化层在特定时序下会静默丢行、留下永久 seq 缺口，导致整份历史被拒读。
+ * 现改为 sidecar 文件（见 ownership-store.ts）；该事件类型仅作**读兼容**
+ * 保留（旧日志可能仍含此事件，注册 + fold 逻辑不再写入）。
+ *
+ * @module dsh-later/domain
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** 插件名（与 cordis 条目 id / manifest 一致）。 */
+export declare const name = "dsh-later";
+/** 会话投影键：GUI 通过 `useProjection` / `faceOf` 读取用户任务列表。 */
+export declare const PROJECTION_KEY = "userSchedules";
+/**
+ * 伴生所有权事件类型（**历史遗留，仅读兼容**；新写入一律走 ownership-store）。
+ * 字面量保留旧名 `session-scheduler/user-schedule`：它是历史会话日志里的
+ * 数据键，改名不追溯——读方必须继续认它。
+ */
+export declare const OWNED_EVENT = "session-scheduler/user-schedule";
+/**
+ * 伴生所有权事件荷载。语义：`add` 声明一个由用户工具创建的 schedule id；
+ * `remove` 撤销该声明。它与 `schedule/change` 的 create/delete 成对出现，
+ * 但由本插件独立解码——dsh-schedule 永远不会看到它。
+ *
+ * `delivery`（可选，默认 `context`）标记到点注入的形态：
+ *  - `context`：框架认可的安全形式（source.kind='plugin'，带 notice 表单 + 防护
+ *    framing，保持「上下文注入」的可信审计线）；
+ *  - `user`：延迟发送的「代发」形式（source.kind='user'），由 `/later` 命令显式
+ *    请求，需用户明确表达『到点以我身份发出』，产品取舍见 commands.ts。
+ */
+export interface UserScheduleOwnedChange {
+    readonly version: 1;
+    readonly operation: 'add' | 'remove';
+    readonly id: string;
+    readonly delivery?: 'context' | 'user';
+}
+/** 到点注入形态（见 {@link UserScheduleOwnedChange}）。 */
+export type UserScheduleDelivery = 'context' | 'user';
+/**
+ * 投影输出的一条用户任务骨架（不含随墙钟变化的状态字段；
+ * `scheduled`/`overdue` 由客户端用 `scheduledAt` 实时推导）。
+ * 字段用 snake_case，与 `user_schedule_list` 工具响应保持一致。
+ */
+export interface UserScheduleWireItem {
+    readonly id: string;
+    readonly kind: 'after' | 'at' | 'every';
+    readonly prompt: string;
+    readonly after_seconds?: number;
+    readonly every_seconds?: number;
+    readonly scheduled_at: string;
+    /** 创建时刻（来自 create 事件的 time；旧日志/未知时缺省）。 */
+    readonly created_at?: string;
+    readonly delivery_mode: 'session-local';
+}
+/** 投影输出值。 */
+export interface UserScheduleProjectionValue {
+    readonly schedules: readonly UserScheduleWireItem[];
+}
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /** 本插件自有的用户所有权记录（dsh-schedule 忽略）。 */
+        'session-scheduler/user-schedule': UserScheduleOwnedChange;
+    }
+}
+declare module '@deepseek-ai/dsh-session-projection/types' {
+    interface SessionProjectionMap {
+        /** 用户创建的、当前活动的定时提醒列表。 */
+        userSchedules: UserScheduleProjectionValue;
+    }
+    interface SessionProjectionStateMap {
+        /**
+         * 投影内部折叠状态（plain JSON：owned/active 用数组承载，
+         * 满足持久化投影缓存的 plain-JSON 前提）。
+         */
+        userSchedules: UserScheduleProjectionState;
+    }
+}
+/**
+ * 投影内部折叠状态（plain JSON）。与 `src/projection.ts` 中的同名接口
+ * 结构一致；在 domain.ts 里用结构化类型承载是因为合并的
+ * `SessionProjectionStateMap` 需要在这里给出 —— 而 projection.ts 依赖
+ * domain.ts，反向 import 会形成环。
+ */
+export interface UserScheduleProjectionState {
+    /** 会话 id（init 时由 header 注入；apply 据此查询所有权 sidecar 缓存）。 */
+    readonly sessionId: string;
+    readonly owned: readonly string[];
+    readonly active: readonly {
+        id: string;
+        kind: 'after' | 'at' | 'every';
+        prompt: string;
+        afterSeconds?: number;
+        everySeconds?: number;
+        scheduledAt: string;
+        createdAt?: number;
+    }[];
+    readonly seedSeq: number;
+}
+/** 判断事件是否属于本插件所有权流。 */
+export declare function isOwnedEvent(event: SessionEvent): event is SessionEvent & {
+    data: UserScheduleOwnedChange;
+};

package/lib/types/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * dsh-later 宿主入口。
+ *
+ * 挂载职责：
+ *  1. 注册 `userSchedules` 会话投影（GUI 读取任务列表的权威状态）；
+ *  2. 注册 slash 命令（客户端 → host 的创建/删除/列表变更通道）；
+ *  3. 为每个 root agent 注册用户工具 `user_schedule_create/list/delete`
+ *     （PRD「用户工具（底层暴露）」，模型亦可调用，与 dsh-schedule 双入口互补）。
+ *
+ * 依赖顺序：作为 peer 依赖的 dsh-schedule 需先加载（其 agent-runtime 负责
+ * 到期 dispatch + followup 注入；本插件只负责「用户接口层」）。
+ * @module dsh-later
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import s from '@deepseek-ai/schemastery';
+import { name } from './domain.js';
+/** 插件配置 schema（全可选，默认开箱即用；经 cordis config 覆盖）。 */
+export declare const Config: s<Schemastery.ObjectS<{
+    /** 单 session 用户任务上限。 */
+    maxSchedules: s<number, number>;
+}>, Schemastery.ObjectT<{
+    /** 单 session 用户任务上限。 */
+    maxSchedules: s<number, number>;
+}>>;
+/** 所需服务（延后激活，缺失时插件不加载）。 */
+export declare const inject: string[];
+/** 宿主持有的 settings 形状（settings getter 返回值与 register* 接受入参）。 */
+export interface SchedulerSettings {
+    readonly maxSchedules: number;
+    readonly allowLongPrompts: boolean;
+    readonly maxPromptChars: number;
+}
+export declare function apply(ctx: Context, config?: {
+    maxSchedules?: number;
+}): void;
+export { name };