dsh-delay-tools

Delay utilities for DeepSeek Harness: two tools sharing one core concept — delay:

Why

A plain background shell timer cannot do "wake me in 3 minutes": DSH background jobs are bound to the agent turn's lifecycle and get torn down when the turn ends (ctx.jobs owner-scoped dispose — the process exits with 0xC000013A and the cancel is misreported as completed). This plugin uses a host-level timer (not bound to any turn) plus the official followup() wake channel to deliver the message back into the same conversation.

Install

dsh plugin add github:keyiadiannao/dsh-delay-tools#master

Usage

Tell the agent:

Call the schedule_reminder tool and remind me in 30 seconds to drink water.

The agent calls the tool and returns the expected trigger time; when the delay elapses it wakes up and delivers the reminder in the same conversation. No matter how many other turns happen in between (including new messages you send), the reminder arrives on time. Multiple reminders per conversation are supported — each has its own reminder_id.

Durability note: reminders live in process memory. They survive agent turns (and plugin reloads cancel them cleanly), but restarting the DSH host cancels all pending reminders. Durable persistence is on the roadmap.

Tool parameters

Return value

scheduled / due_at / delay_ms / pending (how many reminders are still pending for this agent).

The second mode: wait (timed gate)

schedule_reminder means "wake later, keep working meanwhile"; wait is the opposite — it blocks the current turn, and the agent only continues after the countdown:

Call the wait tool for 30 seconds, then continue.

wait takes only delay_ms and returns waited_ms / elapsed_until / note. Messages you send during the gate go into the inbox queue (the composer shows "N queued messages") and are processed after the countdown — which makes it a reliable trigger for testing queue/merge plugins such as dsh-queue-merge.

wait observes exec.signal per the tools contract: pressing the stop button mid-wait interrupts the gate immediately (returns note: 'Wait interrupted by the user (stop).') instead of hanging for the full delay.

Configuration

- id: dsh-delay-tools
  config:
    defaultDelayMs: 60000       # default delay when delay_ms is omitted
    maxDelayMs: 3600000         # upper bound for a single delay
    minDelayMs: 1000            # lower bound, guards against instant re-entry

How it works

user: "tell me X in 3 minutes"
  ↓
schedule_reminder(delay_ms, message)
  ↓
host setTimeout(delay).unref()      ← not bound to any turn lifetime
  ↓ (turn ends, teardown, further turns — none of it matters)
due → agent.followup(userMessage)   ← official wake channel
  ↓
agent (idle) opens a new turn → replies in the same conversation

Key points:

• The timer lives in the plugin apply scope, not ctx.jobs (which dies with the owning turn).
• setTimeout().unref() lets the process exit normally when only the timer is left — it never blocks the DSH lifecycle.
• agent.followup() is the runtime's official wake channel: a wake submitted while the agent is idle always opens a new turn boundary (see the runtime-types comments), so cross-turn waking is a supported semantic.

Testing

tests/ holds config-validation tests (pnpm test). End-to-end verification:

1. New session → have the agent call schedule_reminder with a 30 s delay;
2. After the agent finishes its turn, send an interrupting message;
3. ~30 s later the agent wakes and delivers the reminder → cross-turn survival confirmed.

wait interruption: have the agent call wait for 40 s, press stop mid-way → the turn ends immediately instead of hanging for the full 40 s.

Roadmap

• cancel_reminder / list_reminders tools (per-agent, by reminder_id)
• Durable reminder store (reminders.json + re-hydrated timers on boot), so reminders survive a DSH host restart
• Pending-reminder cap

License

MIT