@kesike/reminder-dsh 0.0.0-stage → 0.2.1

package/scripts/test-popup.js

@@ -0,0 +1,19 @@
+import { createWindowsToast } from '../src/modules/popup/toast.js'
+
+if (process.platform !== 'win32') {
+  console.error('请在 Windows 桌面会话中运行 npm run test:popup。')
+  process.exitCode = 1
+} else {
+  const notifier = createWindowsToast({
+    title: 'DSH 通知测试', message: '任务总结（演示）：Windows 系统通知已就绪。',
+  })
+  let done, timeout
+  const reply = new Promise(resolve => { done = resolve })
+  try {
+    await notifier.notify({ onReply: text => { console.log('收到测试回复', text); done() } })
+    await Promise.race([reply, new Promise(resolve => { timeout = setTimeout(resolve, 60_000) })])
+  } finally {
+    clearTimeout(timeout)
+    notifier.dispose()
+  }
+}

package/scripts/test-taskbar.js

@@ -0,0 +1,11 @@
+import { createTaskbarNotifier } from '../src/modules/taskbar/windows.js'
+
+if (process.platform !== 'win32') {
+  console.error('请在 Windows 桌面会话中运行任务栏测试。')
+  process.exitCode = 1
+} else {
+  const notifier = createTaskbarNotifier({ isEnabled: () => true, getWindowTitle: () => process.argv[2] ?? '' })
+  try { await notifier.notify() }
+  catch (error) { console.error(error.message); process.exitCode = 1 }
+  finally { notifier.dispose() }
+}

package/src/index.js

@@ -0,0 +1,42 @@
+import Schema from '@deepseek-ai/schemastery'
+import { attachReminder } from './reminder.js'
+import { Config as PopupConfig, createPopupModule } from './modules/popup/index.js'
+import { attachApprovalNotifications } from './modules/popup/approval.js'
+import { Config as TaskbarConfig, createTaskbarModule } from './modules/taskbar/index.js'
+
+export const name = 'dsh-reminder'
+export const inject = ['llm']
+export const Config = Schema.object({
+  taskbar: TaskbarConfig.default({}).description('任务栏完成角标模块'),
+  popup: PopupConfig.default({}).description('Windows 系统通知模块'),
+})
+
+/** Mount both independently controlled modules behind one main-session completion observer. */
+export function apply(ctx, config = Config({})) {
+  ctx.inject(['settings'], child => {
+    child.effect(() => child.settings.configure({ auto: false }, ctx.fiber))
+  })
+  if (process.platform !== 'win32') {
+    ctx.logger(name).warn('Windows 提醒仅在 Windows 本机后端生效；设置入口仍可使用。')
+    return
+  }
+  startReminderRuntime(ctx, config)
+}
+
+/** Share only completion detection; each module keeps its own configuration and lifecycle. */
+export function startReminderRuntime(ctx, config, modules = {
+  taskbar: createTaskbarModule(config.taskbar), popup: createPopupModule(ctx, config.popup),
+}) {
+  const logger = ctx.logger(name)
+  ctx.effect(() => () => { for (const module of Object.values(modules)) module.dispose() })
+  ctx.on('loader/volatile-update', () => { for (const module of Object.values(modules)) module.update() })
+  if (modules.popup.notifyApproval) {
+    ctx.inject(['approval', 'typertGateway'], scope => attachApprovalNotifications(scope, modules.popup.notifyApproval))
+  }
+  attachReminder(ctx, options => Promise.all(Object.entries(modules).map(async ([name, module]) => {
+    try { await module.notify(options) }
+    catch (error) {
+      if (!options.signal.aborted) logger.warn(`${name} 提醒失败：${error instanceof Error ? error.message : String(error)}`)
+    }
+  })), error => logger.warn(`会话提醒失败：${error instanceof Error ? error.message : String(error)}`))
+}

package/src/modules/popup/ToastActivator.cs

@@ -0,0 +1,153 @@
+using System;
+using System.Diagnostics;
+using System.IO;
+using System.IO.Pipes;
+using System.Runtime.InteropServices;
+using System.Security.Principal;
+using System.Text;
+using System.Text.RegularExpressions;
+
+namespace DshReminder
+{
+    [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+    public struct NotificationInput
+    {
+        [MarshalAs(UnmanagedType.LPWStr)] public string Key;
+        [MarshalAs(UnmanagedType.LPWStr)] public string Value;
+    }
+
+    [ComImport, Guid("53E31837-6600-4A81-9395-75CFFE746F94")]
+    [InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+    public interface INotificationActivationCallback
+    {
+        [PreserveSig]
+        int Activate([MarshalAs(UnmanagedType.LPWStr)] string appId,
+            [MarshalAs(UnmanagedType.LPWStr)] string arguments,
+            [MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 3)] NotificationInput[] input,
+            uint count);
+    }
+
+    [ComImport, Guid("00000001-0000-0000-C000-000000000046")]
+    [InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+    public interface IClassFactory
+    {
+        [PreserveSig] int CreateInstance(IntPtr outer, ref Guid iid, out IntPtr instance);
+        [PreserveSig] int LockServer([MarshalAs(UnmanagedType.Bool)] bool locked);
+    }
+
+    // Run while the DSH backend holds the helper's stdin open.
+    [ComVisible(true), ClassInterface(ClassInterfaceType.None)]
+    public sealed class ToastActivator : INotificationActivationCallback
+    {
+        private static string launcher, toastScript;
+
+        public int Activate(string appId, string arguments, NotificationInput[] input, uint count)
+        {
+            if (appId != "KeS1Ke.DSH" || String.IsNullOrEmpty(arguments)) return 0;
+            var route = Regex.Match(arguments, @"\A([a-f0-9]{32}):([a-f0-9]{32})(:decision|:open)?\z");
+            if (!route.Success) return 0;
+            var kind = route.Groups[3].Value;
+            if (kind == ":open")
+            {
+                // Navigate the backend first (it answers the GUI long poll), then open the app either way.
+                try { Deliver(route.Groups[1].Value, route.Groups[2].Value, null); }
+                catch (IOException) { }
+                catch (UnauthorizedAccessException) { }
+                catch (TimeoutException) { }
+                catch (AggregateException) { }
+                OpenApp();
+                return 0;
+            }
+            bool approval = kind == ":decision";
+            bool delivered;
+            try
+            {
+                var entry = Array.Find(input ?? new NotificationInput[0], item => item.Key == "reply");
+                delivered = Deliver(route.Groups[1].Value, route.Groups[2].Value, approval ? "decision" : entry.Value);
+            }
+            catch (IOException) { delivered = false; }
+            catch (UnauthorizedAccessException) { delivered = false; }
+            catch (TimeoutException) { delivered = false; }
+            catch (AggregateException) { delivered = false; }
+            if (!delivered)
+            {
+                using (Process.Start(new ProcessStartInfo(launcher,
+                    "-NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File \"" + toastScript + "\" "
+                        + (approval ? "-ApprovalFailed" : "-ReplyFailed"))
+                {
+                    UseShellExecute = false,
+                    CreateNoWindow = true
+                })) { }
+            }
+            return 0;
+        }
+
+        private static void OpenApp()
+        {
+            try
+            {
+                using (Process.Start(new ProcessStartInfo("dsh://open") { UseShellExecute = true })) { }
+            }
+            catch
+            {
+                // The protocol may be unregistered (web-only profile); the GUI long poll already ran.
+            }
+        }
+
+        private static bool Deliver(string pipeId, string token, string text)
+        {
+            // A null text marks a body click: it carries the route token only.
+            if (text != null && (String.IsNullOrWhiteSpace(text) || text.Length > 8000)) return false;
+            using (var pipe = new NamedPipeClientStream(".", "kesike-dsh-reply-" + pipeId,
+                PipeDirection.InOut, PipeOptions.Asynchronous, TokenImpersonationLevel.Identification))
+            {
+                pipe.Connect(2000);
+                var body = text == null ? token + "\n" : token + " " + Convert.ToBase64String(Encoding.UTF8.GetBytes(text)) + "\n";
+                var message = Encoding.ASCII.GetBytes(body);
+                if (!pipe.WriteAsync(message, 0, message.Length).Wait(2000)) return false;
+                using (var reader = new StreamReader(pipe, Encoding.ASCII))
+                {
+                    var acknowledgment = reader.ReadLineAsync();
+                    return acknowledgment.Wait(3000) && acknowledgment.Result == "ok";
+                }
+            }
+        }
+
+        public static void Run(Guid clsid, string powershell, string script)
+        {
+            const uint localServer = 4, multipleUse = 1;
+            launcher = powershell;
+            toastScript = script;
+            Marshal.ThrowExceptionForHR(CoInitializeEx(IntPtr.Zero, 0)); // MTA
+            try
+            {
+                uint registration;
+                Marshal.ThrowExceptionForHR(CoRegisterClassObject(ref clsid, new Factory(), localServer, multipleUse, out registration));
+                try { Console.WriteLine("ready"); Console.ReadLine(); }
+                finally { CoRevokeClassObject(registration); }
+            }
+            finally { CoUninitialize(); }
+        }
+
+        [ComVisible(true), ClassInterface(ClassInterfaceType.None)]
+        public sealed class Factory : IClassFactory
+        {
+            public int CreateInstance(IntPtr outer, ref Guid iid, out IntPtr instance)
+            {
+                instance = IntPtr.Zero;
+                if (outer != IntPtr.Zero) return unchecked((int)0x80040110); // CLASS_E_NOAGGREGATION
+                var unknown = Marshal.GetIUnknownForObject(new ToastActivator());
+                try { return Marshal.QueryInterface(unknown, ref iid, out instance); }
+                finally { Marshal.Release(unknown); }
+            }
+
+            public int LockServer(bool locked) { return 0; }
+        }
+
+        [DllImport("ole32.dll")] private static extern int CoInitializeEx(IntPtr reserved, uint model);
+        [DllImport("ole32.dll")] private static extern void CoUninitialize();
+        [DllImport("ole32.dll")] private static extern int CoRegisterClassObject(ref Guid clsid,
+            [MarshalAs(UnmanagedType.Interface)] IClassFactory factory, uint context, uint flags, out uint registration);
+        [DllImport("ole32.dll")] private static extern int CoRevokeClassObject(uint registration);
+    }
+}

package/src/modules/popup/ToastIdentity.cs

@@ -0,0 +1,71 @@
+using System;
+using System.ComponentModel;
+using System.IO;
+using System.Runtime.InteropServices;
+using System.Runtime.InteropServices.ComTypes;
+
+public static class DshToastIdentity
+{
+    [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+    private static extern bool MoveFileEx(string source, string destination, uint flags);
+
+    [DllImport("shell32.dll", CharSet = CharSet.Unicode)]
+    private static extern void SHChangeNotify(int eventId, uint flags, string path, IntPtr unused);
+
+    [ComImport, Guid("00021401-0000-0000-C000-000000000046")]
+    private class ShellLink { }
+
+    [StructLayout(LayoutKind.Sequential)]
+    private struct PropertyKey { public Guid Format; public uint Id; }
+
+    [StructLayout(LayoutKind.Sequential)]
+    private struct PropertyValue
+    {
+        public ushort Type, Reserved1, Reserved2, Reserved3;
+        public IntPtr Data;
+        public int Padding;
+    }
+
+    [ComImport, Guid("886D8EEB-8CF2-4446-8D02-CDBA1DBDCF99")]
+    [InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+    private interface IPropertyStore
+    {
+        void GetCount(out uint count);
+        void GetAt(uint index, out PropertyKey key);
+        void GetValue(ref PropertyKey key, out PropertyValue value);
+        void SetValue(ref PropertyKey key, ref PropertyValue value);
+        void Commit();
+    }
+
+    public static void RegisterShortcut(string staged, string destination, string appId, Guid activator)
+    {
+        var link = new ShellLink();
+        try
+        {
+            var file = (IPersistFile)link;
+            file.Load(staged, 2); // STGM_READWRITE
+            var store = (IPropertyStore)link;
+            var key = new PropertyKey { Format = new Guid("9F4C2855-9F79-4B39-A8D0-E1D42DE1D5F3"), Id = 5 };
+            var value = new PropertyValue { Type = 31, Data = Marshal.StringToCoTaskMemUni(appId) }; // VT_LPWSTR
+            try { store.SetValue(ref key, ref value); }
+            finally { Marshal.FreeCoTaskMem(value.Data); }
+
+            key.Id = 26; // AppUserModel.ToastActivatorCLSID
+            value = new PropertyValue { Type = 72, Data = Marshal.AllocCoTaskMem(16) }; // VT_CLSID
+            try
+            {
+                Marshal.StructureToPtr(activator, value.Data, false);
+                store.SetValue(ref key, ref value);
+            }
+            finally { Marshal.FreeCoTaskMem(value.Data); }
+            store.Commit();
+            file.Save(staged, true);
+        }
+        finally { Marshal.FinalReleaseComObject(link); }
+
+        bool replaced = File.Exists(destination);
+        if (!MoveFileEx(staged, destination, 1)) // MOVEFILE_REPLACE_EXISTING
+            throw new Win32Exception(Marshal.GetLastWin32Error());
+        SHChangeNotify(replaced ? 0x2000 : 2, 0x1005, destination, IntPtr.Zero); // UPDATEITEM/CREATE, PATHW | FLUSH
+    }
+}

package/src/modules/popup/activate.ps1

@@ -0,0 +1,5 @@
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+Add-Type -Path (Join-Path $PSScriptRoot 'ToastActivator.cs')
+[DshReminder.ToastActivator]::Run([guid]'{BD86FD58-A2BF-430E-A8D9-8D20238ED61A}',
+  (Join-Path $PSHOME 'powershell.exe'), (Join-Path $PSScriptRoot 'toast.ps1'))

package/src/modules/popup/approval.js

@@ -0,0 +1,60 @@
+import { excerpt } from './summary.js'
+import { sessionTitleOf } from '../../reminder.js'
+
+/** Share the exact pending Remote event with DSH's existing approval card. */
+export function attachApprovalNotifications(ctx, notify) {
+  const { approval, typertGateway: gateway } = ctx
+  const logger = ctx.logger('reminder-approval')
+  // The gateway's public pending-event list omits request identity and cannot settle events.
+  if (!(gateway.pendingRemoteEvents instanceof Map) || typeof gateway.settleRemoteEvent !== 'function') {
+    logger.warn('当前 DSH 版本无法将审批请求接入 Windows 通知。')
+    return
+  }
+  const lifetime = new AbortController()
+  const requests = new WeakMap()
+  ctx.effect(() => () => lifetime.abort())
+  ctx.on('approval/request', (request, next) => {
+    const previous = requests.get(request)
+    if (previous) {
+      // Reusing a request object would make its pending event ambiguous.
+      previous.abort()
+      return next()
+    }
+    const session = request.agent.session
+    const pending = new AbortController()
+    requests.set(request, pending)
+    const decision = next()
+    const signal = AbortSignal.any([lifetime.signal, pending.signal, ...(request.signal ? [request.signal] : [])])
+    const finish = () => pending.abort()
+    void Promise.resolve(decision).then(finish, finish)
+
+    // Forwarding to the gateway runs asynchronously. Leave DSH's answerer in charge of the request.
+    setImmediate(() => {
+      if (signal.aborted) return
+      const event = [...gateway.pendingRemoteEvents.values()].find(item =>
+        item.frame?.event === 'approval/request' && item.source?.request === request && item.source.context?.subject === request.agent)
+      if (!event) return
+      const tool = excerpt(request.toolName, 64)
+      const description = request.reason
+      const reason = typeof description === 'string' && description.trim()
+        ? excerpt(description, 220) : '点击通知查看请求详情。'
+      void Promise.resolve().then(() => notify({
+        sessionId: session.id,
+        // The title stays the session title; the approval context moves into the body.
+        title: sessionTitleOf(ctx, session) ?? `需要审批 · ${tool}`,
+        message: `需要审批（${tool}）：${reason}`, signal,
+        onDecision(outcome) {
+          if (signal.aborted || request.agent.session !== session || approval.effectivePolicy(session) !== 'ask'
+            || gateway.pendingRemoteEvents.get(event.id) !== event
+            || (outcome !== 'allowed-once' && outcome !== 'rejected')) {
+            throw new Error('审批请求已失效，请回到 DSH 查看。')
+          }
+          gateway.settleRemoteEvent(event, { kind: 'result', value: outcome })
+        },
+      })).catch(error => {
+        if (!signal.aborted) logger.warn(`审批通知失败：${error instanceof Error ? error.message : String(error)}`)
+      })
+    })
+    return decision
+  }, { prepend: true })
+}

package/src/modules/popup/index.js

@@ -0,0 +1,103 @@
+import Schema from '@deepseek-ai/schemastery'
+import { createWindowsToast } from './toast.js'
+import { summarizeCompletion } from './summary.js'
+import { createReminderQueue } from './queue.js'
+import { createSessionOpenRequests } from './open.js'
+
+export const Config = Schema.object({
+  enabled: Schema.boolean().default(true).description('启用 Windows 完成和审批通知').volatile(),
+  durationSeconds: Schema.number().min(1).max(300).step(1).default(10)
+    .description('连续提交系统通知的最短间隔（秒）').volatile(),
+  showSummary: Schema.boolean().default(true)
+    .description('在通知正文中显示压缩到 3 行的任务总结；关闭后只显示会话标题').volatile(),
+  title: Schema.string().default('DSH 任务完成').description('无法取得会话标题时的通知标题'),
+  message: Schema.string().default('主会话已完成本轮任务。').description('没有最终文字回复时的备用提示'),
+  summaryMaxChars: Schema.number().min(20).max(1000).step(1).default(60)
+    .description('AI 总结最大字符数；通知正文按 3 行预算展示，最多 60 字'),
+  summaryTimeoutSeconds: Schema.number().min(1).max(60).step(1).default(15).description('AI 总结超时秒数'),
+})
+
+/**
+ * The GUI long-polls this route and navigates to the session a clicked toast belongs to.
+ * Registered only where the host owns a web server and connection trust (the web/desktop app).
+ */
+function attachSessionOpenRoute(ctx, requests, logger) {
+  ctx.inject(['webServer', 'connection'], scope => {
+    const webServer = scope.get('webServer')
+    const connection = scope.get('connection')
+    if (!webServer || !connection) return
+    scope.effect(() => {
+      try {
+        return webServer.register({
+          kind: 'exact',
+          path: '/reminder-dsh/session-open',
+          handler: async (request, response) => {
+            if (typeof connection.requestRejection === 'function' && connection.requestRejection(request) !== undefined) {
+              response.writeHead(403)
+              response.end()
+              return
+            }
+            if (request.method !== 'GET') {
+              response.writeHead(405)
+              response.end()
+              return
+            }
+            const sessionId = await requests.take()
+            if (sessionId === undefined) {
+              response.writeHead(204)
+              response.end()
+              return
+            }
+            response.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' })
+            response.end(JSON.stringify({ sessionId }))
+          },
+        })
+      } catch (error) {
+        // Session jumps are a convenience: never let a route conflict break reminders.
+        logger.warn(`会话跳转路由不可用：${error instanceof Error ? error.message : String(error)}`)
+        return () => {}
+      }
+    }, 'reminder-dsh: session open route')
+  })
+}
+
+/** Keep the popup configuration key for existing profiles. */
+export function createPopupModule(ctx, config, notifier = createWindowsToast(config)) {
+  const logger = ctx.logger('reminder-popup')
+  let approvals = new AbortController()
+  const opens = createSessionOpenRequests()
+  const openOf = options => options.sessionId
+    ? () => opens.request(options.sessionId)
+    : undefined
+  const queue = createReminderQueue({
+    enabled: config.enabled.get(), intervalSeconds: config.durationSeconds.get(),
+    prepare: async options => ({
+      title: options.sessionTitle || config.title,
+      message: config.showSummary.get()
+        ? await summarizeCompletion(ctx.llm, config, options, error => {
+          logger.warn(`AI 任务总结失败：${error instanceof Error ? error.message : String(error)}`)
+        })
+        : '',
+    }),
+    show: options => notifier.notify({ ...options, onOpen: openOf(options) }),
+  })
+  attachSessionOpenRoute(ctx, opens, logger)
+  return {
+    notify: options => queue.enqueue(options),
+    notifyApproval(options) {
+      if (!config.enabled.get()) return
+      const signal = AbortSignal.any([options.signal, approvals.signal])
+      return notifier.notify({ ...options, signal, onOpen: openOf(options), onDecision(outcome) {
+        signal.throwIfAborted()
+        return options.onDecision(outcome)
+      } })
+    },
+    update() {
+      queue.setEnabled(config.enabled.get())
+      queue.setIntervalSeconds(config.durationSeconds.get())
+      if (!config.enabled.get()) approvals.abort()
+      else if (approvals.signal.aborted) approvals = new AbortController()
+    },
+    dispose() { queue.dispose(); approvals.abort(); notifier.dispose() },
+  }
+}

package/src/modules/popup/open.js

@@ -0,0 +1,33 @@
+/** One-slot mailbox: a toast click posts the session id, the GUI's long poll consumes it once. */
+export function createSessionOpenRequests({ timeoutMs = 25_000 } = {}) {
+  let pending
+  const waiters = new Set()
+
+  return {
+    request(sessionId) {
+      if (typeof sessionId !== 'string' || sessionId === '') return
+      pending = sessionId
+      for (const waiter of [...waiters]) waiter()
+    },
+    /** Resolve with a posted session id, or undefined when the caller gives up first. */
+    take() {
+      if (pending !== undefined) {
+        const sessionId = pending
+        pending = undefined
+        return Promise.resolve(sessionId)
+      }
+      return new Promise(resolve => {
+        let timer
+        const settle = () => {
+          clearTimeout(timer)
+          waiters.delete(settle)
+          const sessionId = pending
+          pending = undefined
+          resolve(sessionId)
+        }
+        waiters.add(settle)
+        timer = setTimeout(settle, timeoutMs)
+      })
+    },
+  }
+}

package/src/modules/popup/queue.js

@@ -0,0 +1,93 @@
+/** Await preparation or a scheduling delay without retaining an aborted queue entry. */
+function interruptible(promise, signal) {
+  if (signal.aborted) return Promise.reject(signal.reason)
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason)
+    signal.addEventListener('abort', abort, { once: true })
+    promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort))
+  })
+}
+
+function waitUntil(time, signal) {
+  const delay = Math.max(0, time - Date.now())
+  if (!delay) return Promise.resolve()
+  let timer
+  const waiting = new Promise(resolve => { timer = setTimeout(resolve, delay) })
+  return interruptible(waiting, signal).finally(() => clearTimeout(timer))
+}
+
+/** FIFO completion queue with a live interval between Windows toast submissions. */
+export function createReminderQueue({ prepare, show, enabled = true, intervalSeconds = 10 }) {
+  const pending = [], live = new Set()
+  let running = false, disposed = false, lastSentAt, reschedule
+
+  async function waitForSlot(signal) {
+    while (lastSentAt !== undefined && Date.now() < lastSentAt + intervalSeconds * 1000) {
+      const delay = new AbortController()
+      reschedule = delay
+      try { await waitUntil(lastSentAt + intervalSeconds * 1000, AbortSignal.any([signal, delay.signal])) }
+      catch (error) { if (signal.aborted || !delay.signal.aborted) throw error }
+      finally { if (reschedule === delay) reschedule = undefined }
+    }
+  }
+
+  async function pump() {
+    if (running) return
+    running = true
+    try {
+      while (pending.length) {
+        const item = pending.shift()
+        try {
+          const prepared = await interruptible(item.prepared, item.signal)
+          if (prepared.error) throw prepared.error
+          await waitForSlot(item.signal)
+          item.signal.throwIfAborted()
+          await show({ ...item.options, ...prepared.value, signal: item.signal })
+          if (!item.signal.aborted) lastSentAt = Date.now()
+          item.resolve()
+        } catch (error) {
+          if (item.signal.aborted) item.resolve()
+          else item.reject(error)
+        } finally { live.delete(item) }
+      }
+    } finally { running = false }
+  }
+
+  function clear() {
+    for (const item of live) item.controller.abort()
+    for (const item of pending.splice(0)) {
+      live.delete(item)
+      item.resolve()
+    }
+    lastSentAt = undefined
+  }
+
+  return {
+    enqueue(options) {
+      if (disposed || !enabled || options.signal?.aborted) return Promise.resolve()
+      const controller = new AbortController()
+      const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal
+      return new Promise((resolve, reject) => {
+        const item = { options, controller, signal, resolve, reject }
+        // Prepare concurrently but reserve FIFO position before any model call settles.
+        item.prepared = Promise.resolve().then(() => {
+          signal.throwIfAborted()
+          return prepare({ ...options, signal })
+        }).then(value => ({ value }), error => ({ error }))
+        live.add(item)
+        pending.push(item)
+        void pump()
+      })
+    },
+    setEnabled(value) {
+      enabled = value
+      if (!enabled) clear()
+    },
+    setIntervalSeconds(value) {
+      if (value === intervalSeconds) return
+      intervalSeconds = value
+      reschedule?.abort()
+    },
+    dispose() { disposed = true; enabled = false; clear() },
+  }
+}