@ottttto/dsh-scheduled-send 0.2.0

package/src/client-core.js

@@ -0,0 +1,225 @@
+// Client-layer core for dsh-scheduled-send (browser side, framework-free and
+// testable in Node). The lib/client.js bundle wraps this with React/slots.
+
+/** Media query marking the mobile layout (FIX 5). */
+export const MOBILE_QUERY = '(max-width: 480px)';
+
+/**
+ * Grace window during which a freshly POSTed task survives a refresh whose
+ * server snapshot was taken BEFORE the task existed (FIX 4 race).
+ */
+export const LOCAL_ADD_GRACE_MS = 10_000;
+
+/** Safe matchMedia probe: never throws, false when unavailable. */
+export function isMobileViewport(matchMedia) {
+  try {
+    if (typeof matchMedia !== 'function') return false;
+    return !!matchMedia(MOBILE_QUERY)?.matches;
+  } catch {
+    return false;
+  }
+}
+
+/** Sort a task list by sendAt ascending (display order). */
+export function sortTasks(tasks) {
+  return [...(tasks || [])].sort((a, b) => (a.sendAt || 0) - (b.sendAt || 0));
+}
+
+/**
+ * Collapse rule for the dock (FIX 2):
+ *  - default (desktop): >1 entry → show ONLY the soonest (sendAt-min) entry
+ *    plus a 「其余 N 条定时任务 ⌄」 summary toggle; ≤1 entry → expanded.
+ *  - default (mobile): fully collapsed (summary only).
+ *  - user 'expanded' → all entries; user 'collapsed' → nothing but the
+ *    summary (manual collapse-all works for ANY count, including 1).
+ * @param {Array} tasks already sorted ascending by sendAt
+ * @param {{user?: 'expanded'|'collapsed'|null, mobile?: boolean}} [opts]
+ */
+export function collapseState(tasks, { user = null, mobile = false } = {}) {
+  const list = tasks || [];
+  if (!list.length) {
+    return { display: 'expanded', visibleCount: 0, hiddenCount: 0, summary: null, collapsed: false };
+  }
+  let display = mobile ? 'summary' : (list.length > 1 ? 'one' : 'expanded');
+  if (user === 'expanded') display = 'expanded';
+  else if (user === 'collapsed') display = list.length > 1 ? 'one' : 'summary';
+  if (display === 'one') {
+    return { display, visibleCount: 1, hiddenCount: list.length - 1, summary: `其余 ${list.length - 1} 条定时任务 ⌄`, collapsed: true };
+  }
+  if (display === 'summary') {
+    return { display, visibleCount: 0, hiddenCount: list.length, summary: `${list.length} 条定时任务 ⌄`, collapsed: true };
+  }
+  return { display: 'expanded', visibleCount: list.length, hiddenCount: 0, summary: '收起 ⌃', collapsed: false };
+}
+
+/** Local-timezone "YYYY-MM-DD HH:mm" for a planned send time. */
+export function formatLocalTime(ms) {
+  if (typeof ms !== 'number' || !Number.isFinite(ms)) return '';
+  const d = new Date(ms);
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+/** Countdown until sendAt ("N分N秒后" / "N小时N分后" / "即将发送"). */
+export function formatCountdown(sendAt, now) {
+  const ms = sendAt - now;
+  if (ms <= 0) return '即将发送';
+  const totalSec = Math.floor(ms / 1000);
+  const h = Math.floor(totalSec / 3600);
+  const m = Math.floor((totalSec % 3600) / 60);
+  const s = totalSec % 60;
+  if (h > 0) return `${h}小时${m}分后`;
+  if (m > 0) return `${m}分${s}秒后`;
+  return `${s}秒后`;
+}
+
+/** Default confirmation time = now + 5 minutes. */
+export function defaultSendAt(now = Date.now(), offsetMs = 5 * 60_000) {
+  return now + offsetMs;
+}
+
+/**
+ * Stateful client controller: polls the host state route, holds the visible
+ * task list (extended with the server-confirmed task right after POST so new
+ * entries show WITHOUT a refresh), and exposes cancel.
+ *
+ * FIX 1: setSession() reports session changes so the view can refresh
+ * immediately; refresh failures keep the LAST data and surface an error
+ * instead of flashing empty.
+ *
+ * FIX 4: refresh() merges by id — a recently POSTed task (within
+ * LOCAL_ADD_GRACE_MS) survives a stale server snapshot that predates it.
+ *
+ * @param {object} deps
+ * @param {() => Promise<object>} deps.fetchState GET the host state route
+ * @param {(payload:object)=>Promise<{task:object}>} deps.postSchedule
+ * @param {(id:string)=>Promise<boolean>} deps.cancelSchedule
+ * @param {() => number} [deps.now]
+ */
+export function createScheduledClientState({ fetchState, postSchedule, cancelSchedule, now = () => Date.now() } = {}) {
+  let tasks = [];
+  let error = null;
+  let timer = null;
+  let stopped = false;
+  let sessionId = null; // this dock belongs to exactly one conversation
+  const recentAdds = new Map(); // id → addedAt (FIX 4 grace window)
+  // per-conversation cache: switching sessions shows the cached list
+  // INSTANTLY (no ~1s wait for the network), then refresh() revalidates.
+  const sessionCache = new Map(); // sid → task[]
+
+  // strict conversation filter: with a session bound, only entries belonging
+  // to THIS conversation are ever visible; other-session tasks are dropped
+  // from the local list on every refresh.
+  const own = (it) => !sessionId || !it?.conversationId || it.conversationId === sessionId;
+  const dedupeById = (list) => {
+    const seen = new Set();
+    return list.filter((t) => (t?.id && !seen.has(t.id) ? (seen.add(t.id), true) : false));
+  };
+
+  return {
+    /**
+     * Bind this client to one conversation. Returns true when the session
+     * actually CHANGED (the view refreshes immediately in that case — FIX 1).
+     */
+    setSession(sid) {
+      const next = sid || null;
+      const changed = next !== sessionId;
+      if (sessionId !== null) sessionCache.set(sessionId, tasks.filter(own));
+      sessionId = next;
+      if (changed) {
+        // instant swap: show the cached list for the target session first
+        tasks = sessionId !== null && sessionCache.has(sessionId)
+          ? [...sessionCache.get(sessionId)]
+          : [];
+        error = null;
+      }
+      return changed;
+    },
+
+    /** Session this client is currently bound to (view fetch uses it). */
+    currentSession() {
+      return sessionId;
+    },
+
+    /** Pending tasks sorted ascending by sendAt, own session only. */
+    visibleTasks() {
+      return sortTasks(tasks).filter(own);
+    },
+    /** Last refresh error, or null (view shows old data + this line). */
+    lastError() {
+      return error;
+    },
+    snapshot() {
+      return { tasks: sortTasks(tasks).filter(own), error, fetchedAt: now() };
+    },
+
+    async refresh() {
+      let s;
+      try {
+        s = await fetchState();
+      } catch (err) {
+        // FIX 1 failure mode: keep the previous list, surface the error —
+        // never flash an empty dock on a transient failure.
+        error = String(err?.message || err);
+        return this.snapshot();
+      }
+      error = null;
+      const server = (s?.tasks ?? []).filter(own);
+      // FIX 4: keep freshly POSTed tasks whose id the (possibly stale) server
+      // snapshot does not know yet; the server list stays authoritative for
+      // everything else (cancellations included).
+      const t = now();
+      const freshLocal = tasks.filter(
+        (it) => it?.id && !server.some((x) => x.id === it.id) && own(it) && t - (recentAdds.get(it.id) ?? -Infinity) < LOCAL_ADD_GRACE_MS,
+      );
+      for (const id of [...recentAdds.keys()]) {
+        if (t - recentAdds.get(id) >= LOCAL_ADD_GRACE_MS || server.some((x) => x.id === id)) recentAdds.delete(id);
+      }
+      tasks = dedupeById([...server, ...freshLocal]);
+      if (sessionId !== null) sessionCache.set(sessionId, tasks); // keep the instant-swap cache fresh
+      return this.snapshot();
+    },
+
+    /**
+     * User-facing schedule entry: POST to the host route and locally enqueue
+     * the SERVER-RETURNED task so it is visible IMMEDIATELY (无需刷新立即显示,
+     * id-deduped). Nothing is added on failure, so the view keeps the form
+     * with its content intact (失败回滚保留表单).
+     */
+    async scheduleMessage(payload) {
+      if (!postSchedule) throw new Error('postSchedule 未配置');
+      const result = await postSchedule(payload);
+      const task = result?.task ?? result;
+      if (task?.id && own(task)) {
+        tasks = dedupeById([...tasks, task]);
+        recentAdds.set(task.id, now());
+      }
+      return task;
+    },
+
+    /** Cancel a pending task: DELETE on the host + drop locally. */
+    async cancelTask(id) {
+      if (cancelSchedule) await cancelSchedule(id);
+      tasks = tasks.filter((t) => t.id !== id);
+      recentAdds.delete(id);
+    },
+
+    start(intervalMs = 4_000) {
+      if (timer) return;
+      stopped = false;
+      const loop = async () => {
+        if (stopped) return;
+        await this.refresh().catch(() => {});
+        timer = setTimeout(loop, intervalMs);
+        timer.unref?.();
+      };
+      void loop();
+    },
+
+    stop() {
+      stopped = true;
+      clearTimeout(timer);
+      timer = null;
+    },
+  };
+}

package/src/client-view.js

@@ -0,0 +1,291 @@
+// Browser view layer for dsh-scheduled-send.
+// This file is CONCATENATED into lib/client.js by scripts/build-client.mjs
+// together with src/client-core.js — it must stay import/export-free plain JS.
+// Inside the bundle it references: React (platform module) and the client-core
+// helpers (sortTasks/collapseState/formatLocalTime/formatCountdown/…).
+
+/* ==== view ==== */
+function createClientPluginBody(React) {
+  const h = React.createElement;
+  const TOUCH_MIN = 40; // FIX 5: touch target height on mobile
+
+  function pad2(n) { return String(n).padStart(2, "0"); }
+
+  function toDatetimeLocalValue(ms) {
+    const d = new Date(ms);
+    return d.getFullYear() + "-" + pad2(d.getMonth() + 1) + "-" + pad2(d.getDate())
+      + "T" + pad2(d.getHours()) + ":" + pad2(d.getMinutes());
+  }
+
+  function isMobile() {
+    return isMobileViewport(typeof window !== "undefined" ? window.matchMedia : null);
+  }
+
+  /* --- ⏰ composer button (conversation.input.right) -------------------- */
+  function ScheduleButton(props) {
+    const core = props.core;
+    const [open, setOpen] = React.useState(false);
+    const [timeValue, setTimeValue] = React.useState("");
+    const [busy, setBusy] = React.useState(false);
+    const [error, setError] = React.useState(null);
+    // standard session props: useInput(s => s.draft) reads the composer draft
+    const draft = typeof props.useInput === "function"
+      ? (props.useInput((s) => (s == null ? "" : s.draft)) ?? "")
+      : "";
+    const mobile = isMobile();
+
+    const openPopover = () => {
+      setTimeValue(toDatetimeLocalValue(typeof core.defaultSendAt === "function" ? core.defaultSendAt() : Date.now() + 5 * 60_000));
+      setError(null);
+      setOpen(true);
+    };
+
+    const submit = async () => {
+      if (busy) return;
+      const content = String(draft ?? "");
+      if (!content.trim()) { setError("输入框内容为空，请先输入要定时发送的内容"); return; }
+      const at = timeValue ? new Date(timeValue).getTime() : NaN;
+      if (!Number.isFinite(at) || at <= Date.now()) { setError("发送时间必须是未来时间"); return; }
+      setBusy(true);
+      setError(null);
+      try {
+        const payload = { content, sendAt: at, conversationId: props.sessionId };
+        await core.scheduleMessage(payload);
+        // spec: 内容转为定时任务并清空输入框 — 绝不立即发送（不调 submit）
+        if (props.inputActions && typeof props.inputActions.setDraft === "function") props.inputActions.setDraft("");
+        setOpen(false);
+      } catch (err) {
+        // FIX 4 failure mode: nothing was enqueued — keep the popover open
+        // with the form (time + draft) intact and surface the error.
+        setError(String(err?.message || err));
+      } finally {
+        setBusy(false);
+      }
+    };
+
+    const btnStyle = {
+      cursor: "pointer", flexShrink: 0, border: "1px solid " + (open ? "#3b82f6" : "transparent"),
+      background: open ? "rgba(59,130,246,.12)" : "transparent",
+      color: open ? "#3b82f6" : "inherit",
+      borderRadius: 999, fontSize: 12, fontWeight: 600, lineHeight: "18px", padding: "1px 8px",
+      display: "inline-flex", alignItems: "center", gap: 3,
+      opacity: open ? 1 : 0.8,
+      ...(mobile ? { minHeight: TOUCH_MIN } : {}),
+    };
+    const isDark = typeof window !== "undefined" && window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches;
+    // FIX 5: on ≤480px the popover spans (nearly) the full viewport width.
+    const popCard = {
+      position: "absolute", bottom: "100%", right: 0, marginBottom: 6, zIndex: 30,
+      minWidth: 280, padding: "10px 12px", fontSize: 12,
+      borderRadius: 12, border: "1px solid " + (isDark ? "rgba(255,255,255,.14)" : "rgba(0,0,0,.10)"),
+      background: isDark ? "#1c1c1e" : "#fff",
+      boxShadow: "0 8px 24px rgba(0,0,0,.18)",
+      color: isDark ? "#eee" : "#111",
+      ...(mobile ? { left: 0, right: 0, minWidth: 0, width: "calc(100vw - 16px)", maxWidth: "calc(100vw - 16px)", boxSizing: "border-box" } : {}),
+    };
+    const fieldLbl = { display: "block", fontSize: 11, opacity: .65, margin: "6px 0 3px" };
+    const fieldIn = {
+      width: "100%", boxSizing: "border-box",
+      border: "1px solid " + (isDark ? "rgba(255,255,255,.2)" : "rgba(0,0,0,.18)"),
+      borderRadius: 8, padding: "5px 8px", fontSize: 12,
+      background: isDark ? "rgba(255,255,255,.05)" : "#fff", color: "inherit",
+      ...(mobile ? { minHeight: TOUCH_MIN } : {}),
+    };
+    const actionBtn = (extra) => ({
+      cursor: "pointer", borderRadius: 999, padding: "5px 16px", fontSize: 12, ...(extra || {}),
+      ...(mobile ? { minHeight: TOUCH_MIN, boxSizing: "border-box" } : {}),
+    });
+
+    return h("div", { "data-plugin": "dsh-scheduled-send-button", style: { position: "relative", display: "inline-flex", alignItems: "center", gap: 6 } }, [
+      open
+        ? h("span", { key: "badge", style: { flexShrink: 0 } },
+            h("span", { style: {
+              display: "inline-flex", alignItems: "center", borderRadius: 999,
+              padding: "1px 8px", fontSize: 11, fontWeight: 700,
+              background: "rgba(59,130,246,.16)", color: "#3b82f6",
+            } }, "⏳ 定时发送中"))
+        : null,
+      h("button", {
+        key: "alarm", type: "button", onClick: open ? () => setOpen(false) : openPopover,
+        title: "定时发送", "aria-label": "定时发送", style: btnStyle,
+      }, "⏰ 定时"),
+      open
+        ? h("div", { key: "pop", style: popCard }, [
+            h("div", { key: "title", style: { fontWeight: 700, fontSize: 13 } }, "定时发送"),
+            h("label", { key: "lt", style: fieldLbl }, "发送时间（默认当前 +5 分钟）"),
+            h("input", {
+              key: "t", type: "datetime-local", value: timeValue,
+              onChange: (e) => setTimeValue(e?.target?.value ?? e), style: fieldIn,
+            }),
+            h("div", { key: "act", style: { display: "flex", gap: 8, marginTop: 10, alignItems: "center", flexWrap: "wrap" } }, [
+              h("button", {
+                key: "ok", type: "button", disabled: busy, onClick: submit,
+                style: actionBtn({ border: "none", fontWeight: 600, color: "#fff", background: "#3b82f6", opacity: busy ? .6 : 1, cursor: busy ? "wait" : "pointer" }),
+              }, busy ? "提交中…" : "确认"),
+              h("button", {
+                key: "no", type: "button", onClick: () => setOpen(false),
+                style: actionBtn({ border: "1px solid " + (isDark ? "rgba(255,255,255,.2)" : "rgba(0,0,0,.18)"), background: "transparent", color: "inherit", cursor: "pointer" }),
+              }, "取消"),
+              error ? h("span", { key: "e", style: { color: "#dc2626", wordBreak: "break-word" } }, error) : null,
+            ]),
+          ])
+        : null,
+    ]);
+  }
+
+  /* --- pending-task dock (conversation.input.dock) ---------------------- */
+  function ScheduledDock(props) {
+    const core = props.core;
+    const [, setTick] = React.useState(0);
+    // FIX 2: tri-state user override — null = default policy, 'expanded',
+    // 'collapsed' (manual collapse-all works for ANY count).
+    const [user, setUser] = React.useState(null);
+    const mobile = isMobile();
+
+    // FIX 1: react to sessionId changes — bind the core to the NEW session
+    // and refresh IMMEDIATELY (no waiting for the next poll tick).
+    React.useEffect(() => {
+      let stopped = false;
+      let timer = null;
+      core.setSession(props.sessionId);
+      const loop = async () => {
+        if (stopped) return;
+        await core.refresh().catch(() => {});
+        if (!stopped) setTick((n) => n + 1);
+        if (!stopped) { timer = setTimeout(loop, 3000); timer.unref?.(); }
+      };
+      void loop();
+      return () => {
+        stopped = true;
+        clearTimeout(timer);
+      };
+    }, [props.sessionId]);
+    // countdown ticker
+    React.useEffect(() => {
+      const t = setInterval(() => setTick((n) => n + 1), 1000);
+      t.unref?.(); // never hold the host loop for a UI countdown
+      return () => clearInterval(t);
+    }, []);
+
+    const tasks = core.visibleTasks();
+    const err = core.lastError();
+    const st = collapseState(tasks, { user, mobile });
+    const visible = tasks.slice(0, st.visibleCount);
+    const showToggle = tasks.length > 0;
+    if (!tasks.length && !err) return null;
+
+    const rowStyle = {
+      display: "flex", flexDirection: "column", gap: 2, width: "100%", maxWidth: "48rem",
+      margin: "2px auto 0", fontSize: 12, lineHeight: "18px",
+      boxSizing: "border-box",
+    };
+    const entryStyle = {
+      display: "flex", flexDirection: "column", gap: 2, padding: "4px 8px", borderRadius: 8,
+      background: "rgba(59,130,246,.10)", border: "1px solid rgba(59,130,246,.22)",
+      maxWidth: "100%", width: "100%", boxSizing: "border-box", overflowWrap: "break-word",
+    };
+    const srcStyle = {
+      margin: 0, whiteSpace: "pre-wrap", fontFamily: "monospace", fontSize: 12,
+      wordBreak: "break-word", maxWidth: "100%",
+    };
+    const metaStyle = { display: "flex", alignItems: "center", gap: 8, color: "rgba(128,128,128,1)", flexWrap: "wrap", maxWidth: "100%" };
+    const cancelBtn = (id) => h("button", {
+      key: "x", type: "button", onClick: () => { core.cancelTask(id); },
+      style: {
+        cursor: "pointer", border: "1px solid rgba(128,128,128,.4)", borderRadius: 999, padding: "0 8px",
+        fontSize: 11, background: "transparent", color: "inherit", flexShrink: 0,
+        ...(mobile ? { minHeight: TOUCH_MIN } : {}),
+      },
+    }, "取消");
+
+    return h("div", { "data-plugin": "dsh-scheduled-send-dock", style: rowStyle }, [
+      err
+        ? h("div", {
+            key: "err",
+            style: { padding: "3px 8px", borderRadius: 8, background: "rgba(220,38,38,.10)", color: "#dc2626", wordBreak: "break-word" },
+          }, "⚠ 加载失败，显示上一次列表：" + err)
+        : null,
+      showToggle && st.summary
+        ? h("button", {
+            key: "sum", type: "button",
+            onClick: () => { setUser(st.display === "expanded" ? "collapsed" : "expanded"); setTick((n) => n + 1); },
+            style: {
+              cursor: "pointer", alignSelf: "center", border: "1px solid rgba(59,130,246,.35)", borderRadius: 999,
+              padding: "1px 10px", fontSize: 11, fontWeight: 600, background: "rgba(59,130,246,.10)", color: "inherit",
+              ...(mobile ? { minHeight: TOUCH_MIN, boxSizing: "border-box" } : {}),
+            },
+          }, st.summary)
+        : null,
+      visible.map((t) => h("div", { key: t.id, style: entryStyle }, [
+          h("div", { key: "src", style: srcStyle }, t.content),
+          h("div", { key: "meta", style: metaStyle }, [
+            h("span", { key: "at" }, formatLocalTime(t.sendAt)),
+            h("span", { key: "cd" }, formatCountdown(t.sendAt, Date.now())),
+            h("span", { key: "sp", style: { marginLeft: "auto" } }, cancelBtn(t.id)),
+          ]),
+        ])),
+    ]);
+  }
+
+  /** Client plugin body. Returns the cordis plugin ({inject, apply}). */
+  return function buildPlugin({ stateRoutePath, fetchImpl }) {
+    const schedulePath = stateRoutePath.replace(/\/state$/, "/schedule");
+    const doFetch = fetchImpl || ((...a) => fetch(...a));
+
+    let currentSessionId = null;
+
+    const core = createScheduledClientState({
+      fetchState: async () => {
+        // ask the host for THIS conversation's view (the core's bound session
+        // is authoritative — the view binds it before every refresh); the
+        // core still filters strictly client-side against stale caches.
+        const sid = core.currentSession();
+        const q = sid ? "?conversationId=" + encodeURIComponent(sid) : "";
+        const res = await doFetch(stateRoutePath + q, { headers: { accept: "application/json" } });
+        if (!res.ok) throw new Error("state HTTP " + res.status);
+        return res.json();
+      },
+      postSchedule: async (payload) => {
+        const res = await doFetch(schedulePath, {
+          method: "POST", headers: { "content-type": "application/json", accept: "application/json" },
+          body: JSON.stringify(payload),
+        });
+        const body = await res.json().catch(() => ({}));
+        if (!res.ok) throw new Error(body.error || ("HTTP " + res.status));
+        return body;
+      },
+      cancelSchedule: async (id) => {
+        const res = await doFetch(schedulePath + "?id=" + encodeURIComponent(id), { method: "DELETE" });
+        return res.ok;
+      },
+    });
+    core.defaultSendAt = () => defaultSendAt();
+
+    const inject = ["slots"];
+    function apply(ctx) {
+      ctx.inject(inject, (scope) => {
+        scope.slots.inject("conversation.input.right", () => scope.slots.register({
+          name: "conversation.input.right",
+          id: "dsh-scheduled-send",
+          order: 100,
+          inject: (sessionId) => {
+            currentSessionId = sessionId;
+            core.setSession(sessionId); // dock/button are conversation-scoped
+            return { sessionId, core };
+          },
+        }, ScheduleButton));
+        scope.slots.inject("conversation.input.dock", () => scope.slots.register({
+          name: "conversation.input.dock",
+          id: "dsh-scheduled-send",
+          order: 30,
+          inject: (sessionId) => {
+            currentSessionId = sessionId;
+            core.setSession(sessionId);
+            return { sessionId, core };
+          },
+        }, ScheduledDock));
+      });
+    }
+    return { core, inject, apply };
+  };
+}

package/src/delivery.js

@@ -0,0 +1,101 @@
+// Real injection channel for scheduled tasks. When a task comes due, we
+// build a REAL user message (role 'user', fresh id, source kind 'user' with a
+// `via` tag — NOT kind 'plugin', which the UI renders as an injected line
+// instead of a normal user bubble) and hand it to the live agent of the task's
+// ORIGINAL conversation via agent.runMaintenance(() => agent.followup(msg)).
+// This mirrors the host's real prompt path
+// (@deepseek-ai/dsh-api-session-controller prompt(): createUserMessage with
+// kind:"user" source + followup). If the session is not live or the agent is
+// busy, delivery throws so the scheduler keeps the task queued and retries.
+//
+// Model switching has been REMOVED. Legacy tasks may still carry a `model`
+// field (written by earlier versions); it is silently ignored — the task
+// delivers on the conversation's current model.
+
+export const PLUGIN_NAME = 'dsh-scheduled-send';
+
+/**
+ * Inline equivalent of @deepseek-ai/dsh-llm createUserMessage: completes the
+ * message with role 'user' and a fresh stable UUID id, then freezes it before
+ * publication (same contract as the host's createUserMessage, which is not
+ * resolvable from a plugin directory).
+ */
+export function defaultCreateUserMessage(spec) {
+  const message = {
+    id: crypto.randomUUID(),
+    role: 'user',
+    content: spec.content,
+    source: spec.source,
+  };
+  return Object.freeze(message);
+}
+
+/**
+ * Track root agents published after plugin load (same install rule as
+ * dsh-schedule: agents live at load time are not adopted). agent.id IS the
+ * conversation/session id (dsh-agent: agent id must equal session id), so
+ * tasks bind back to their original conversation after restarts.
+ * @param {object} ctx host plugin context exposing ctx.on
+ * @returns {{agents:()=>any[], live:()=>any[], dispose:()=>void}}
+ */
+export function installAgentTracking(ctx) {
+  const agents = new Set();
+  let stopped = false;
+  const offCreated = ctx?.on?.('agent/created', ({ agent }) => {
+    if (stopped || !agent || typeof agent.followup !== 'function') return;
+    agents.add(agent);
+  });
+  const offDisposed = ctx?.on?.('agent/disposed', ({ agent }) => {
+    agents.delete(agent);
+  });
+  return {
+    agents: () => [...agents],
+    live: () => [...agents].filter((a) => typeof a.followup === 'function'),
+    dispose: () => {
+      stopped = true; // stop accepting new ones
+      if (typeof offCreated === 'function') offCreated();
+      if (typeof offDisposed === 'function') offDisposed();
+    },
+  };
+}
+
+/**
+ * Build the delivery callback for the scheduler: inject one due task into the
+ * live session of its conversation as a follow-up user message.
+ * @param {object} p
+ * @param {{live:()=>any[]}} p.tracking agent tracking from installAgentTracking
+ * @param {(spec:object)=>object} [p.createUserMessage] message factory (injectable)
+ * @param {string} [p.pluginName]
+ * @returns {(item:{id:string, content:string, conversationId?:string, model?:object}) => Promise<true>}
+ */
+export function createFollowupDelivery({
+  tracking,
+  createUserMessage = defaultCreateUserMessage,
+  pluginName = PLUGIN_NAME,
+} = {}) {
+  return async function deliver(item) {
+    const live = tracking.live();
+    // bind to the task's conversation (agent.id === conversationId): a task
+    // bound to a conversation NEVER falls through to another live session
+    // (会话绑定); only legacy tasks without a conversationId may use any agent.
+    const agent = item.conversationId
+      ? live.find((a) => a.id === item.conversationId) ?? null
+      : live[0] ?? null;
+    if (!agent) {
+      const err = new Error('当前无活跃会话代理，任务保留在队列等待会话恢复后补发');
+      err.code = 'NO_LIVE_AGENT';
+      throw err;
+    }
+    const message = createUserMessage({
+      content: [{ type: 'text', text: item.content }],
+      source: { kind: 'user', via: pluginName },
+    });
+    // runMaintenance throws when the agent is mid-turn (busy) — the throw
+    // propagates so the scheduler re-queues with backoff.
+    await agent.runMaintenance(async () => {
+      agent.followup(message);
+      return true;
+    });
+    return true;
+  };
+}

package/src/deps.js

@@ -0,0 +1,2 @@
+// Node built-ins re-exported so modules stay testable without mocking loaders.
+export { promises as fs } from 'node:fs';