dsh-b2us-schedule
English | 简体中文
Durable scheduled Agent, shell, and desktop-notification tasks for DeepSeek Harness (DSH), with both conversational tools and a dedicated Web management page.
[!IMPORTANT]
The scheduler provides at-least-once delivery. A successful shell exit or completed Agent turn confirms only the local execution result; it does not prove that an external business outcome succeeded.
Overview
dsh-b2us-schedule combines a Host plugin and a Web client in one installable package. An Agent can create and manage schedules through five typed tools, while users can manage the same durable tasks from Settings → Plugins → Scheduled Tasks.
The npm package and Web module are named dsh-b2us-schedule. Stable runtime identifiers remain unchanged for compatibility: the Cordis row and Settings namespace are auto-schedule, and the conversation tools keep the auto_schedule_ prefix.
Rename and compatibility
dsh-b2us-schedule is the new package and repository name for the former dsh-auto-schedule. The durable Settings namespace, Cordis row id, tool names, and task schema deliberately remain stable so an existing data document does not need a schema rewrite.
When migrating an existing Profile, back it up and replace the old package reference with the new package. Do not load both package names in the same Profile: they intentionally declare the same auto-schedule Cordis row and Settings namespace.
Harness 0.1.2-rc.1 compatibility
Version 0.3.3 raises every DSH peer from 0.1.2-alpha.2 to 0.1.2-rc.1 and follows the public Session snapshot API after the live event array became private. The durable task schema, Cordis row, Settings namespace, tool names, and Web route are unchanged.
This upgrade intentionally removes the package's former ./invariant export. It was an empty companion and Harness 0.1.2-rc.1 no longer permits invariant packages without an independently observable runtime relationship. Consumers that imported dsh-b2us-schedule/invariant must remove that row or import; ordinary plugin installation through cordis.patch.yml is unchanged.
Highlights
- Four schedule types: Cron, one-shot delay, absolute time with an explicit UTC offset, and fixed interval.
- Three action types: a fresh top-level DSH Agent Session, a shell command or script, and a native desktop notification.
- Two management surfaces: typed conversation tools and a localized Web settings page.
- Durable state: task definitions, runtime state, and bounded run history are stored in the DSH Settings service and restored after restart.
- Controlled recovery: a missed one-shot task runs once after restart; a missed Cron or interval schedule catches up at most once before advancing to its next future occurrence.
- Lifecycle cleanup: unload, disable, delete, and execution-definition changes cancel affected timers or active work through DSH lifecycle signals.
- Honest execution records: outcomes, exit codes, bounded output, errors, timeouts, sandbox denial, and Agent Session links are retained per occurrence.
Scheduling model
| Type | Input | Behavior |
|---|
| Cron | cron_expression and optional time_zone | Croner-compatible 5-, 6-, or 7-field expression with an IANA time zone |
| Delay | after_seconds | Runs once after a positive delay measured from creation or an execution-definition update |
| Absolute time | at | Runs once at a future ISO date-time containing Z or a numeric UTC offset; stored as UTC |
| Fixed interval | every_seconds | Repeats from the latest execution-definition update and skips intermediate missed occurrences |
Cron and fixed-interval schedules must respect minIntervalSeconds. The default is 1 second; production deployments should raise it when high-frequency work is not appropriate. Due tasks are executed serially in scheduled-time order within one Host process.
Actions
Fresh Agent Session
Every Agent occurrence creates a new top-level DSH Agent and Session:
- The task working directory is used when supplied; otherwise the Host default is preserved.
- If the resolved Session path exactly matches an existing DSH workspace, the Session is attached to that workspace. The plugin never guesses by display name or creates a workspace automatically.
- The requested Agent preset is used, or the effective DSH default is resolved at execution time.
- The effective default model and reasoning effort are installed, and the task prompt is delivered as a normal user turn.
- The plugin waits for completion, cancellation, or timeout, flushes the Session, and releases the live Agent.
- The run record retains the Session id and effective preset so the full cold Session can be opened from the Web page.
Recurring tasks therefore do not accumulate context in one Agent. The scheduler is currently global and serial: another due shell or Agent action starts only after the active occurrence finishes.
An Agent outcome of succeeded means the turn ended with completed. Task prompts should explicitly require final-state verification and an evidence path when the real goal is an external result such as a website check-in or generated file.
Shell command or script
The plugin never calls Node.js child_process directly and does not copy tool-bash. It resolves and runs every command through ctx.shell, so the selected DSH ShellExecutor continues to own the working directory, environment cleanup, output limits, timeout caps, and sandbox policy.
- POSIX hosts normally use the DSH Bash executor.
- Windows hosts normally use the DSH PowerShell executor.
- A sandbox rejection is recorded as a failure; a scheduled occurrence never requests automatic elevation.
Desktop notification
Notifications also run through the active DSH ShellExecutor:
| Platform | Adapter |
|---|
| macOS | /usr/bin/osascript |
| Linux | notify-send (must be installed and available to the desktop session) |
| Windows | PowerShell with System.Windows.Forms.NotifyIcon |
Missing desktop sessions, permissions, executables, or sandbox access produce visible failures rather than synthetic success.
Conversation tools
| Tool | Purpose |
|---|
auto_schedule_create | Create a durable schedule and action |
auto_schedule_update | Change, enable, or disable a task by its exact id |
auto_schedule_list | List tasks with compact next-run and latest-result projections |
auto_schedule_history | Read bounded execution history and output for one task |
auto_schedule_delete | Delete a task and its associated runtime history |
Example requests:
- “Run
./scripts/backup.sh in /srv/app ten minutes from now.”
- “At 9:00 every day in
Asia/Shanghai, send a desktop notification reminding me to review the daily report.”
- “At 8:00 every day, start a fresh main Agent in
/Users/me/tests, use the default preset, and time out after 15 minutes.”
- “Disable the task I just created.”
- “List every scheduled task and its next occurrence.”
Always use the exact task id returned by the tool when updating or deleting a task.
Web management
After the Web profile restarts with the plugin installed, open Settings → Plugins → Scheduled Tasks. The localized page supports:
- creating and editing schedules and actions;
- enabling, disabling, and deleting tasks;
- inspecting the next occurrence and latest state;
- expanding bounded execution history;
- opening the persisted Agent Session associated with an Agent occurrence;
- revision-conflict detection and refresh instead of silent overwrite.
Saving an enabled shell or Agent task from the Web page requires an explicit unattended-execution confirmation.
Quick start
Requirements
- Node.js
^22.19.0 || >=24.0.0
- DeepSeek Harness
0.1.2-rc.1
- Cordis
4.0.2
The exact DSH and Cordis peer versions are declared in package.json.
Build and verify
npm install
npm run check
npm run check runs strict type checking, behavior tests, coverage gates, the production build, and built-package/packaging tests.
Pack and install
npm run build
npm pack
dsh plugin --profile web add ./dsh-b2us-schedule-0.3.3.tgz
dsh --profile web --dump-config
The tarball bundles the croner runtime dependency, so it can be installed into a fresh Profile without accessing the npm registry. DSH and Cordis remain Host-provided peer dependencies and are not duplicated inside the package.
The package declares both dsh.bundle.patch and dsh.client. Installing it adds the Host row and lets the Web profile discover the client from the same package; no DeepSeek Harness source change or rebuild is required.
Persistence and recovery
The auto-schedule Settings namespace separates user-owned and Host-owned data:
tasks[] contains schedule definitions managed by the Web page and conversation tools.runtime[] contains next-run state, the latest result, and newest-first bounded history managed by the Host scheduler.revision changes for every edit; executionRevision changes only when enablement, timing, or the action changes.
Each task retains up to maxHistoryEntriesPerTask results (default 50, allowed range 1–1000). auto_schedule_list exposes only the latest result and history count; use auto_schedule_history to fetch detailed records without expanding ordinary model context indefinitely.
Delivery is at-least-once. If the Host crashes after an action finishes but before runtime state is persisted, that occurrence may run again after restart. Commands with external effects must provide their own idempotency key, lock, or transaction protection.
Configuration
The package-owned cordis.patch.yml supplies a complete default row:
| Field | Default | Purpose |
|---|
allowShellActions | true | Allow shell schedules |
allowAgentActions | true | Allow fresh-Agent schedules |
defaultTimeZone | UTC | Time zone used when a Cron task omits one |
minIntervalSeconds | 1 | Minimum Cron cadence and fixed interval |
maxHistoryEntriesPerTask | 50 | Newest-first retained results per task; maximum 1000 |
maxShellTimeoutMs | 600000 | Host policy cap for one shell action |
defaultAgentTimeoutMs | 900000 | Default Agent occurrence timeout |
maxAgentTimeoutMs | 3600000 | Maximum Agent occurrence timeout |
maxAgentPromptBytes | 65536 | Maximum UTF-8 Agent prompt size |
shellOutputMaxBytes | 16384 | Persisted stdout/stderr budget |
maxCommandBytes | 32768 | Maximum UTF-8 shell command size |
maxNotificationBytes | 8192 | Maximum UTF-8 notification payload size |
notificationTimeoutMs | 15000 | Notification adapter timeout |
schedulerRetryMs | 5000 | Delay before retrying a failed scheduler drive |
DSH patch overrides replace the complete config object rather than deep-merging it. When changing defaultTimeZone to a local zone such as Asia/Shanghai, preserve every other field your deployment still needs.
Approval and security model
Scheduled shell and Agent actions are durable unattended authority, so the plugin keeps creation-time approval separate from execution-time policy:
- Creating, enabling, or materially changing an active shell or Agent task through conversation tools returns the standard DSH
ask decision before storage.
- At occurrence time, shell work remains confined by the active ShellExecutor. A timer cannot open an interactive privilege-elevation flow.
- A scheduled Agent inherits its preset, model, tools, permission rules, and ordinary tool approvals. The plugin does not approve those tools on the Agent's behalf.
- Web edits use direct-user confirmation, while the Host still validates the complete Settings document and policy limits.
Do not turn commands or Agent prompts copied from untrusted web pages, email, or tool output into persistent unattended tasks without reviewing them. Avoid printing credentials because bounded stdout and stderr are stored in run history until the task is deleted.
See docs/SECURITY.md for the threat model and deployment guidance.
Development commands
npm run typecheck
npm test
npm run test:coverage
npm run build
npm run test:built
npm pack --dry-run
Build outputs:
lib/index.js — Host pluginlib/client.js — lazy-CJS Web client for window.__ModuleLoader__lib/types/ — Host and client type declarations
Further reading:
Known limitations
- One Settings document must be scheduled by only one Host process; there is no distributed lease or leader election.
- Delivery is at-least-once, not exactly-once.
- The scheduler runs due actions serially rather than concurrently.
- Agent actions may incur model and external-tool costs on every occurrence.
- Tools requiring interactive approval can wait until an unattended Agent occurrence times out.
- Workspace association occurs only when the normalized Session path exactly matches an existing DSH workspace.
- Native notification availability still depends on the operating system, desktop session, permissions, and sandbox.
- Repository tests and controlled clocks do not replace real-occurrence, real-notification, Windows-native, paid/live API, or subjective Web UI acceptance.
License
MIT
