Introduction

The extension mechanism of DSH is “everything is a plugin”. A common problem for agent developers is: after an agent starts a background subagent or shell background job, the user still needs to return later to prompt it to check. dsh-timer-scheduler handles this step: it provides the agent with a one-time reminder tool, wakes the agent up and lets it continue its actions when the time comes, while simultaneously displaying the reminder and countdown in the top bar of the Web UI.

What is this

dsh-timer-scheduler is a DSH plugin maintained by GMH13552 with an MIT license. The package name in the README is dsh-timer-scheduler-ui, and the repository name is dsh-timer-scheduler. The README notes that it has not yet been published to npm; it is currently installed from source. If it is published to npm in the future, the command given in the README is:

dsh plugin --profile web add dsh-timer-scheduler-ui

After the plugin is combined into the web profile, schedule_reminder, list_reminders, and cancel_reminder are available to all preset agents.

Core Features

Below are the verified capabilities.

  • schedule_reminder: Schedule a one-time reminder. Relative time uses delay_seconds, absolute time uses at, supports ISO 8601 or HH:MM[:SS].
  • subject auto-cancel: Specify a background subagent or shell background job as the subject. When it completes and enters the parent session inbox, the plugin automatically cancels the matching reminder.
  • list_reminders: List pending reminders.
  • cancel_reminder: Cancel a reminder by id.
  • Wake up at time: After the reminder expires, the plugin initiates a new round via agent.followup(). The agent acts and reports on its own without needing a human to prompt again.
  • Persistence: Pending reminders are persisted to $DSH_HOME/timer-reminders.json and re-enabled after a restart.
  • Web UI top bar reminder menu: Displays the note of each reminder and a real-time countdown; hidden when there are no reminders; uses --dsw-alias-* theme tokens.
  • Host-plane combination: The three tools can be called by all preset agents. If a preset uses the tool-bootstrap filter (e.g., anchored-standard), the following must be retained:
residentTools: [schedule_reminder, list_reminders, cancel_reminder]

Installation and Activation

First perform a source installation, then restart and verify.

The README notes that it has not yet been published to npm, so it is currently installed from source: mount the package as a dependency and bundle for the web profile, then execute:

cd <web-profile>
pnpm install

After that, restart dsh web and hard refresh the browser.

For verification, check the reminder interface:

curl 'http://127.0.0.1:<port>/api/timer-reminders?sessionId=x'

Expected return:

{"reminders":[]}

Then check the client script:

curl 'http://127.0.0.1:<port>/plugins/dsh-timer-scheduler-ui/client.js'

Expected return is 200 with JS content.

Typical Usage

In an agent session, you can directly ask the agent to schedule a reminder. The README provides the following examples:

  • “Remind me in 30 minutes to check that background task”:
schedule_reminder(delay_seconds=1800, note=…, subject=<subagentId>)
  • “Check deployment at 3 PM”:
schedule_reminder(at="15:00", note=…)
  • Management and cancellation:
list_reminders
cancel_reminder

Applicable Scenarios and Notes

Suitable for developers running in a DSH web profile who want the agent to automatically return when a background task or remote task requires a “check later”. The plugin runs with the permissions of the current dsh process; check the source code and license before installing; the license is MIT.

Notes before use:

  • Cold recovery requires session persistence to be configured and the session to be resumable; if resume fails, the reminder will be logged and skipped.
  • Reminders due during the period the dsh process is stopped will be re-enabled and triggered immediately upon startup.
  • Delays longer than approximately 24.8 days are handled in chunks, relying on the process staying running.
  • The Web client polls /api/timer-reminders?sessionId=… every second.
  • If a preset uses the tool-bootstrap filter (e.g., anchored-standard), the residentTools: [schedule_reminder, list_reminders, cancel_reminder] must be retained.

Links

GitHub Repository: https://github.com/GMH13552/dsh-timer-scheduler