dsh-timer-scheduler

dsh-timer-scheduler-ui

Languages: English · 简体中文

A DeepSeek Harness (DSH) plugin: an agent self-scheduler that wakes the agent at a future time to autonomously check on background jobs, remote tasks, or anything that needs a "come back later" look — without a human having to prompt it — plus a header reminder menu in the web UI.

Features

• schedule_reminder — schedule a one-shot reminder, relative (delay_seconds) or absolute (at: ISO 8601 / HH:MM[:SS]).
• Auto-cancel via subject — pass a subject (background subagent id / shell background job id); when that subagent or background job settles and its completion notice enters the parent inbox, the plugin cancels matching reminders automatically.
• list_reminders — list pending reminders.
• cancel_reminder — cancel a reminder by id.
• Auto-wake — on fire, the agent is woken through agent.followup() with a new turn; it acts and reports on its own, no human wake-up needed.
• Persistence — pending reminders are serialized to $DSH_HOME/timer-reminders.json and re-armed on restart.
• Header reminder menu (client half) — per-reminder note + live countdown, theme-aware via --dsw-alias-* tokens, hidden when empty, never covering the send button.

Structure

One package, two halves, in the standard dsh.client + dsh.bundle.patch shape. Everything is host-plane: composing this bundle into the web profile's host composition makes the model tools available to every agent regardless of preset, and the route serves the browser panel.

Preset adaptation: the anchored-standard preset keeps these tools resident for its agents via its residentTools option; every other preset works without any configuration.

Installation

Not published to npm yet. Install from source:

Host-plane tools: once this bundle is composed, every agent on any preset can call schedule_reminder / list_reminders / cancel_reminder. If a preset uses an aggressive tool-bootstrap filter (like anchored-standard), keep the three tool names resident so its agents still see them:

# inside the tool-bootstrap row's config
residentTools: [schedule_reminder, list_reminders, cancel_reminder]

1. Install it into a profile (this registers both the dependency and the bundle entry, so the Host half is composed):

   dsh plugin --profile web add /path/to/dsh-timer-scheduler
   

   Manual equivalent, if you prefer editing the profile yourself — the profile's package.json needs the package in both places:

   {
     "dependencies": { "dsh-timer-scheduler-ui": "file:./packages/dsh-timer-scheduler-ui" },
     "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-timer-scheduler-ui"] } }
   }
   

2. Restart DSH (the Host half lives in the server process; a browser refresh is not enough), then hard-refresh the page.

3. Verify from a shell — the Host half must answer both the list and an action:

   curl 'http://127.0.0.1:<port>/api/timer-reminders?sessionId=x'                  # → {"reminders":[]}
   curl -X POST 'http://127.0.0.1:<port>/api/timer-reminders?action=retry&id=nope&sessionId=x'
   # → 404 {"ok":false,"error":"not-found","id":"nope"}   (an OLD host answers 200 with the reminder list here)
   

   Then open any session: the session-header menu shows the countdown, and each row has 补触发 / 取消.

Standalone check (no DSH session needed)

node test/delivery.mjs          # 8 cases: same-session delivery, resume w/ preset, queue actions, dedupe
node --check lib/index.js lib/client.js

A full standalone proof installs into a disposable profile and boots it; the exact commands and their recorded output are in PROFILE_EVIDENCE.md.

Usage

In an agent session, just say:

• "Remind me in 30 minutes to check that background job" → schedule_reminder(delay_seconds=1800, note=…, subject=<subagentId>)
• "Check the deployment at 3pm" → schedule_reminder(at="15:00", note=…)
• Manage with list_reminders / cancel_reminder.

The header reminder menu shows the countdown while reminders are pending and hides when empty.

How it works

1. The agent calls schedule_reminder; the host plugin arms a one-shot Cordis timer and writes {id, note, dueMs, sessionId, subject?} to ~/.dsh/timer-reminders.json.
2. On fire, the host plugin wakes the same session that armed the reminder — never a relaunched stand-in and never a pre-branch/archived parent:
   • live session → agent.followup() (a live agent already carries its own tools);
   • cold ordinary session (forked/branched ones included) → ctx.agents.resume() with the session's own persisted preset mounted in the factory setup (header.agentPreset → agentPresets.mount), so the resumed agent gets the tool registry and prompt sections it was created with. Resuming without that setup composes no tools at all — the historical unknown tool "bash" failure after a wake;
   • cold session-backed subagent child → ctx.subagents.sendMessage() through its exact live direct parent, so the continuation seam cold-resumes the same child with the persona/toolFilter recorded in its durable subagent/descriptor and keeps the parent's ownership of it. Resuming such a child as a root instead breaks later parent→child delivery with "already owned by an active write handle". A message is then built with source.kind = 'plugin' and delivered to that agent to wake its driver. header.parentSession is durable fork lineage (or a child's direct parent) — installation history, never a delivery target.
3. If a reminder carries a subject and a matching background subagent completion notice (source.kind = 'subagent-settled') or shell background job completion notice (source.plugin = 'tool-jobs') enters the parent session's inbox, the host plugin cancels the reminder automatically.
4. This package's client half fetches /api/timer-reminders?sessionId=… every second and renders the countdown in the session-header menu.
5. The menu is also the manual control surface: each row has 补触发 (fire now, in the SAME session) and 取消 buttons, backed by POST /api/timer-reminders?action=retry|cancel&id=…&sessionId=…. Without them a parked or overdue entry was visible but unpushable from the browser — only an agent could call retry_reminder.
6. Scheduling the same note for the same session within the same minute reuses the pending entry instead of stacking a second identical reminder (已设定时提醒 vs 复用已存在的定时提醒), so an agent asked twice cannot leave two wakes that both fire.

Known limitations

• Cold resume requires session persistence to be configured and the owning session to be resumable. Resuming a session mounts the preset named by its durable agentPreset; if that preset was deleted or will not mount, the reminder is parked for manual retry (list_reminders shows the reason) instead of being resumed under a different composition.
• Transient resume failures (agent-loop not loaded yet at startup, session still owned by an in-flight write handle) are retried with bounded backoff (2s/5s/15s) — never by re-routing the reminder to another session.
• A cold subagent child can only be resumed through its live direct parent. If that parent is offline the reminder is parked for manual retry; the plugin will not wake an archived parent session on your behalf.
• Cold resume is bounded at 90s: a resume that never settles retries with backoff instead of leaving the entry delivering forever (which made it invisible to re-arming and unpushable).
• The cold-resumed AgentHandle is kept until the plugin is unloaded, so the woken session stays resident after the reminder; a future version may dispose it after the wake turn settles. A handle whose session was closed or replaced in the meantime is dropped and resumed again.
• Reminders that become due while the DSH process is down are re-armed on startup and fire immediately (instead of being skipped).
• Delays beyond ~24.8 days are chunked, so they work, but the mechanism is "in-process timer + disk snapshot"; the timer only needs the process to stay up to fire.

Installing into a profile

node scripts/sync-profile.mjs [profile-dir] copies lib/ into both installed copies (packages/… and node_modules/…) and into the root aliases index.js / client.js.

That last part is not cosmetic. The host loader resolves the bundle name to the package directory and can prefer a root index.js when one exists, so a stale root alias makes the profile keep running old host code after a restart while lib/ looks current — the visible symptom is a menu action that returns HTTP 200 and does nothing, because the old handler ignores the request method. Always sync through the script (or copy both layouts) after editing lib/.

Tests

node test/delivery.mjs runs the delivery-contract regression suite against a fake host: live session, cold forked session with preset restoration, deleted preset, transient factory-missing retry, cold subagent child with an offline parent, and cold subagent child with a live parent. It asserts that a reminder never reroutes to a parent/branch session.

License

MIT