📦 @goodandready/dsh-cron
Automated Cron Scheduling, Background Automation & Agent Execution Engine for DeepSeek Harness
🇬🇧 English •
🇷🇺 Русский •
🇨🇳 中文说明
⭐ If you like this plugin, please star it on GitHub — it shows me that the plugin is useful to you and motivates me to keep developing it.
🐛 If you find a bug or would like to request a feature, open a GitHub issue in any language — I will review your proposal and implement useful suggestions in a future plugin version.
|
⚡ Overview & The Problem
Autonomous AI agents often need to perform recurring duties: generating daily morning digests, triaging bug trackers, checking API health, syncing databases, or running periodic Git hygiene. Without a dedicated scheduler inside the harness, users must rely on external crontab wrappers, complex webhook setups, or manual intervention.
@goodandready/dsh-cron is a native full-stack scheduling and background automation plugin for DeepSeek Harness. It bridges standard cron expressions and natural interval syntax with autonomous agent execution, providing:
- Rich Visual Task Manager — a sidebar button with a collapsible list of active jobs (next run or live state, capped and persisted), plus a full panel to inspect, filter by type/model/channel, pause, trigger, duplicate, export/import and create tasks.
- Interactive "Create with DSH" Workflow — chat with your agent to translate high-level requirements into a well-formed scheduled task.
- Autonomous AI Tool Calling — native
cron_* tools let agents schedule their own follow-up executions during conversations.
- Robust Scheduler & Atomic Storage — built on
croner with interval aliases, one-shot delays, atomic file persistence, run histories, and cost tracking.
- Six Execution Runtimes — shell, Node.js, Python, HTTP/webhook, remote SSH and Docker, plus per-task environment variables, workspace binding and isolated git worktrees for code-modifying agent tasks.
- Multi-Channel Delivery With Templates — one run fans out to Telegram, dsh-kanban, Discord, Slack, ntfy, Bark, PushPlus, voice (
dsh-tts) and Gitea, with {variable} message templates and secrets referenced by DSH credential name.
🏗️ Architecture
graph TD
subgraph Client ["Web Client Surface (DSH UI)"]
SidebarBtn["Sidebar Clock Action<br/>(DSH Client UI Slot)"]
Overlay["Visual Task Manager Panel<br/>(Tabs: All, Active, Paused, Completed)"]
CreateWithDSH["'Create with DSH' Dialog<br/>(natural language task)"]
ManualForm["Manual Task Form<br/>(Cron Expression, Timeout, Overlap, Model)"]
SettingsCard["Settings Card<br/>(Channels, Templates, Credentials)"]
end
subgraph Server ["Server Runtime (Cordis & DSH Services)"]
HttpRoutes["HTTP REST API<br/>(/dsh-cron/*)"]
AgentTools["AI Tool Calling Gateway<br/>(cron_create_task, cron_list_tasks, ...)"]
Scheduler["TaskScheduler Engine<br/>(Croner instances + one-shot timers)"]
Store["Atomic TaskStore<br/>(tasks.json with atomic write)"]
AgentRunner["Agent Session Dispatcher<br/>(Executes prompt with chosen model)"]
Runtimes["Execution Runtimes<br/>(shell, node, python, http, ssh, docker)"]
Notify["Delivery Router<br/>(templates + 9 channels)"]
Secrets["Credential References<br/>(DSH credentials / ENV)"]
end
SidebarBtn --> Overlay
Overlay --> CreateWithDSH
Overlay --> ManualForm
SettingsCard --> HttpRoutes
CreateWithDSH -->|POST /chat/start| HttpRoutes
ManualForm -->|POST /tasks| HttpRoutes
HttpRoutes --> Scheduler
AgentTools --> Scheduler
Scheduler --> Store
Scheduler -->|Trigger on interval/one-shot| AgentRunner
Scheduler --> Notify
✨ Features & Capabilities
1. Visual Task Manager & Sidebar Action
Click the clock icon in the DSH sidebar (positioned next to the new-session button) to open the management panel:
- Status Filter Tabs: toggle between All, Active, Paused, and Completed tasks.
- Instant Action Menu: trigger manual one-off executions (Run Now), pause/resume schedules, or delete obsolete tasks with a confirmation step.
- 1-Click Preset Templates: scaffold common workflows like Daily digest, Weekly review, and Follow-up monitor.
- Execution History: open any task card to review previous runs — timestamps, durations, statuses (success / failed / timeout / skipped / missed), outputs, and errors.
- Aggregated Stats Bar: live dashboard with active task count, total runs, total token consumption, and the estimated dollar spend.
2. "Create with DSH" Dialog
Transform natural language into a scheduled job without guessing cron syntax:
- Click Create ⌄ ➔ Create with DSH.
- Describe what you want to automate (e.g. "Check open PRs every weekday at 9:00 and draft review comments").
- The plugin spawns a dedicated agent session pre-injected with scheduler instructions. The agent clarifies the details with you — LLM vs no-LLM shell task, the exact cron expression, an economical model from those available in your DSH installation, and whether a "silent rule" (alert only on new events or failures) should apply — and registers the task through the
cron_create_task tool only after your confirmation.
3. Agent Tools (Tool Calling)
Autonomous agents can manage schedules directly:
| Tool | Description |
|---|
cron_create_task | Creates a scheduled task: title, schedule, prompt, fallbackModel (one retry on a stronger model when a run fails), optional type (llm/script/node/python/http/ssh/docker/skill/workflow), delivery, provider, model, channels, template, notifyTelegram, onlyOnFailure, timeoutSeconds, overlapPolicy, kanbanMode |
cron_schedule_task | Alias of cron_create_task kept for compatibility with existing agent prompts |
cron_list_tasks | Lists tasks with statuses, next run timestamps, token totals, and cost estimates |
cron_pause_task | Pauses a schedule without deleting its configuration |
cron_resume_task | Resumes a paused schedule |
cron_delete_task | Permanently removes a task and its history |
cron_run_task | Triggers an immediate out-of-band run |
cron_get_task | Reads the full configuration of one task, including fields the list does not show |
cron_update_task | Changes an existing task in place (whitelisted fields, same validation as the HTTP route); the model is told to confirm code-executing changes with the user first |
Example invocation the model can make during a conversation:
cron_create_task({
"title": "Morning digest",
"schedule": "0 8 * * 1-5",
"prompt": "Prepare a brief morning digest of active tasks and open tickets.",
"type": "llm",
"delivery": "isolated"
})
4. Schedule Expression Syntax
Powered by croner, supporting standard 5-field cron expressions plus user-friendly aliases:
0 9 * * 1-5 — weekdays at 09:00*/15 * * * * — every 15 minutes0 0 * * 0 — every Sunday at midnightevery 10m / every 2h / every 30s — natural duration intervalsdaily / hourly / weekdays shortcuts, plus standard @hourly / @daily / @weekly / @monthly / @yearly and @every 30m- Per-task time zones — set an IANA zone (e.g.
Europe/Berlin) on a task; without it the schedule follows the server's local time
- One-shot tasks:
at: 2026-09-05T15:00:00Z (exact ISO timestamp) or relative delays in 20m / in 2h (Russian aliases such as через 15 минут are accepted too). One-shot tasks flip to completed automatically after their single run and are listed under the Completed tab.
5. Execution Reliability
- Automatic retries — set
maxRetries and a base retryBackoffMs per task; failed runs (error/timeout) are retried with exponential backoff, and the attempt counter resets on success.
- Misfire policies — choose per task what happens when the daemon was offline at a scheduled time:
skip (default — record the gap), runOnce (execute once, late), or catchUpAll (run late and record the gap). A missed one-shot under skip is retired as completed instead of firing stale.
- Concurrency limit —
maxConcurrent (plugin setting) caps parallel runs; extra runs are recorded as skipped with a reason.
- Live execution indicator — the task list shows a pulsing status icon and a running timer for the task in flight.
6. Execution Runtimes
Every task picks its own runtime; non-LLM runtimes need no model and consume no tokens:
- Shell (
script) — command or script through the harness shell, with env and cwd.
- Node.js (
node) and Python (python) — run a snippet with an explicit interpreter path (nodePath, pythonPath); Python detects a project virtualenv.
- HTTP (
http) — GET/POST/… to a URL with custom headers and body, and the response status/output recorded in the run history.
- SSH (
ssh) — execute a command on a remote host through a dsh-remote-workspace profile (sshProfileId) or standalone host/key fields.
- Docker (
docker) — run the command in a container image (dockerImage).
- Environment variables — a per-task
env map (KEY VALUE per line in the UI) applied to external runtimes; secrets do not belong here.
- Workspaces and worktrees — bind a task to a harness workspace (
workspaceId) and, for code-modifying agent tasks, run it in an isolated git worktree (worktree, keepWorktree).
7. Cost Control: Fallback Model
A task can run on the cheap model by default and still finish on the strong one: set fallbackModel (and optionally fallbackProvider) and a failed run — error or timeout — is retried once on that model before the ordinary retry backoff applies. History records which model produced the result and whether the fallback was used, usage and cost of both attempts are summed, and the {model} template variable renders the model that finished the run. Only agent-mediated tasks (llm, skill, workflow) can use a fallback.
8. Session Integration & Permissions
- Per-task permission presets —
default, read-only, workspace-write, or full are applied to the task's agent session before the prompt runs.
- Session auto-archive — isolated cron sessions are archived after each run (best-effort) so they do not clutter the chat list.
- History → session navigation — every LLM run records its session; open it straight from the run history entry.
9. Quiet by Rule
A task with output can carry a silent rule written in plain words ("stay silent when no filesystem is above 80%"). On a successful run a cheap model judges the output against that rule and the report is skipped when the verdict is to stay silent, with the reason recorded in the run history. It fails open: no rule, no model, a failed call or an unreadable answer all mean the report is delivered. silentRuleModel (plugin setting) picks the model used for the judgement.
10. Failure Diagnosis
Agent tasks can ask for a diagnosis: with inspectOnFailure set, a failed run (error or timeout) is read by a model together with the task prompt and truncated output, and the run history stores a short diagnosis plus a concrete prompt change. The history entry offers to load that suggestion into the edit form — nothing is applied automatically. The model is configurable with inspectorModel, and {diagnosis} is available in message templates. A broken or unavailable model call leaves the failed run exactly as it was.
11. Notification Channels & Message Templates
A finished run is delivered to every channel configured for the task — Telegram, dsh-kanban, Discord, Slack, ntfy, Bark, PushPlus, voice via dsh-tts, and Gitea issues:
- Per-task channels — tick the channels in the task form; an explicit selection overrides the legacy
notifyTelegram / kanbanMode switches, and an empty selection falls back to them.
- Failure isolation — one unreachable channel is reported in the scheduler log with the other channels still delivered; a broken webhook never swallows the rest of the report.
- Message templates — a global template, per-channel overrides, or a per-task template rendered from
{title} {id} {status} {output} {error} {duration} {schedule} {time} {tokens} {cost}. Unknown placeholders are left intact, failed runs default to a failure template.
onlyOnFailure — globally or per task, clean runs stay silent and only error/timeout runs are dispatched.- Credentials by reference — webhook tokens and the Telegram bot token are entered as the NAME of a DSH credential (
botTokenRef, ntfyTokenRef, pushplusTokenRef, giteaTokenRef); the value is resolved at send time through the DSH credentials service with an environment-variable fallback, and never travels through plugin settings. Webhook URLs and the Bark device key do embed a secret, so they are stored in the plugin settings file but are always returned masked to the browser and a masked value echoed back by the UI never overwrites the stored one.
- Delivery timeout — every channel request is bounded (
deliveryTimeoutMs, default 15000 ms, editable in the settings panel or settings.yaml) and channels are dispatched concurrently, so one unresponsive endpoint is recorded as a failure and cannot delay the other channels or the next scheduled tick. The bound is enforced around the whole channel handler, which also covers credential resolution, which does not support abort signals.
- Telegram — Markdown report with status badges (✅ / ❌), duration, schedule description and monospace output; dynamic values are escaped so odd titles cannot break the message. Credentials may be entered directly, or inherited from the
dsh-messenger-gateway section of your DSH settings.yaml (best-effort fallback).
- Discord / Slack — webhook delivery; Discord carries an embed coloured by run status, Slack a plain text body.
- ntfy / Bark / PushPlus — mobile push with a topic/device key and an optional bearer token; the Bark title and text travel in the request path.
- Voice —
dsh-tts speaks the report through its HTTP route (, default ).
12. Kanban Integration & Cost Meter
- Automatic Kanban cards — with
kanbanMode set to on_failure or always, the plugin creates cards in dsh-kanban (on_failure → Backlog on error/timeout; always → Done/Backlog on completion).
- Token & execution cost meter — token consumption (input, output, cache reads) is tracked per run and per task, with USD estimates from a built-in pricing table and an aggregated analytics bar.
13. Overlap Policies & Execution Timeout
Prevent rogue processes from stacking concurrent duplicate executions:
- Execution timeout (
timeoutSeconds) — when the limit is reached, shell subprocesses are killed immediately via the abort signal and agent sessions are disposed so they stop consuming tokens. Default: 1800 (30 minutes).
- Overlap policy (
overlapPolicy) — controls what happens when a tick fires while the previous run is still active:
skip (default): drops the overlapping run and records a skipped entry in the run history.queue: queues the next execution and starts it as soon as the active job completes.replace: aborts the active run via AbortController and launches a fresh execution.
If the daemon was offline at a scheduled time, the run is recorded as missed on startup, so gaps in the history stay visible.
14. Heartbeat Monitoring (#16-style dead man's switch)
- Set
heartbeatUrl and heartbeatIntervalSec in the plugin settings and the scheduler pings that URL on schedule — an external monitor alerts when the pings stop.
- A built-in
GET /dsh-cron/heartbeat endpoint reports liveness, active task count and the last run time for your own watchdogs.
15. Declarative Jobs From the Profile Config (#50)
Long-lived operational jobs can be declared in the profile configuration instead of being recreated by hand in the UI. The config file owns the jobs it declares: at every plugin start they are created or updated, and a job that disappears from the file is removed.
Add a jobs list to the plugin section of your profile config (cordis.patch.yml):
dsh-cron:
jobs:
- id: nightly-backup
title: Nightly backup
schedule: "0 3 * * *"
type: script
prompt: "bash /path/to/backup.sh"
channels: ["telegram"]
timeoutSeconds: 3600
- id: morning-digest
title: Morning digest
schedule: "0 8 * * 1-5"
type: llm
prompt: "Prepare a brief morning digest of active tasks."
provider: my-provider
model: provider-id/model-id
- Required per entry:
id, title, schedule; the types that carry their payload in the prompt (script, node, python, ssh, docker, llm, skill, workflow) also need a non-empty prompt. http is exempt: its target is given by httpUrl (or prompt).
- Any other task field is passed through with the same validation as the API:
channels, model, provider, fallbackModel, silentRule, inspectOnFailure, timezone, timeoutSeconds, template, env, cwd, and the runtime fields (nodePath, pythonPath, httpUrl, httpMethod, httpHeaders, httpBody, sshProfileId, sshTarget, dockerImage, workspaceId, worktree, keepWorktree, skillName, workflowName).
- Declared jobs are marked managed by the config; the panel shows a source label instead of edit and delete actions.
- Editing, pausing, resuming, toggling or deleting a config-owned task is refused with
409 on the panel and on the API, and a create-or-update POST /dsh-cron/tasks that carries the existing id of a config-owned task is refused the same way — the config file is the source of truth. Run Now stays available.
- A task with the same
id created through the UI, the API or an agent tool is never overwritten: the entry is skipped and the conflict is written to the log.
- Code-executing types are activated like any other declared job, but at startup the plugin writes a warning to the log, so a code path introduced through the config file is visible.
- Entries are validated one by one with an indexed message (
config.jobs[i]: …); a broken entry is skipped and cannot stop the remaining jobs or the profile.
16. External REST API (/dsh-cron/api/*, #54)
External systems (CI, host cron, curl) can drive the scheduler without opening the browser panel. This is the only surface behind a bearer token; the panel routes stay local and cross-origin-protected.
Set the token as the plugin setting apiToken (masked like every secret). Auth and errors:
- no token configured → the whole surface answers
503;
- a missing or wrong
Authorization: Bearer <token> → 401, compared in constant time.
| Method | Path | Description |
|---|
GET | /dsh-cron/api/tasks | List tasks (status / query filters as the panel) |
GET | /dsh-cron/api/tasks/:id | Read one task |
POST | /dsh-cron/api/tasks | Create a task, or update the existing one when id is present |
DELETE | /dsh-cron/api/tasks/:id | Delete a task |
POST | /dsh-cron/api/tasks/:id/run | Force an immediate run |
The operations reuse the panel handlers, so the x-dsh-cron-confirm: script gate for code-executing types and the 409 refusals for config-owned tasks behave exactly as in the UI.
BASE="http://127.0.0.1:3080"
TOKEN="<API_TOKEN>"
# list
curl -s -H "Authorization: Bearer $TOKEN" "$BASE/dsh-cron/api/tasks"
# create, or update when the body carries the id
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"id":"cleanup","title":"Cleanup","schedule":"0 4 * * *","prompt":"Remove stale temporary files."}' \
"$BASE/dsh-cron/api/tasks"
# force a run
curl -s -X POST -H "Authorization: Bearer $TOKEN" "$BASE/dsh-cron/api/tasks/cleanup/run"
# delete
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/dsh-cron/api/tasks/cleanup"
# a code-executing task also needs the confirmation header
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "x-dsh-cron-confirm: script" \
-H "Content-Type: application/json" \
-d '{"title":"Disk check","schedule":"0 * * * *","type":"script","prompt":"df -h"}' \
"$BASE/dsh-cron/api/tasks"
17. Prometheus Metrics (#53)
GET /dsh-cron/metrics returns Prometheus text exposition, so the scheduler can be scraped without any extra dependency:
dsh_cron_tasks_total{status} — tasks by status (gauge).dsh_cron_task_last_duration_seconds{task} — duration of a task's last finished run, in seconds (gauge).dsh_cron_runs_total{status} — finished runs since the plugin process started (counter); the statuses are success, error, timeout, skipped and missed.dsh_cron_run_records — run records currently kept in memory (gauge).
Only counts, statuses and durations are exported; prompts, run output and task configuration never appear in the exposition.
scrape_configs:
- job_name: dsh-cron
static_configs:
- targets: ["127.0.0.1:3080"]
metrics_path: /dsh-cron/metrics
18. Strict Channel Validation (#121)
Creating or updating a task with an unknown delivery-channel id is now rejected with 400, and the offending ids are listed:
{ "ok": false, "error": "Unknown channel ids: email_ping", "unknownChannels": ["email_ping"] }
Changed in v0.2.7: previously an unknown id was silently dropped, so a client with a typo received ok: true and ended up with a task that delivered nowhere.
Import deliberately stays tolerant (a file may come from an older build): unknown ids are dropped from the imported task, but they are named in the response (unknownChannels) and written to the scheduler log instead of disappearing silently.
19. Post-Install Verification (#126)
deploy.sh has a verify-only mode that inspects an already installed profile without installing anything:
bash deploy.sh verify [exact-version]
It checks that the profile reports the requested version (default: the package.json version), authenticates to the web UI, then downloads the client bundle and confirms the package name is present.
Why it is needed: the web profile can sit behind an authentication plugin and answer 401 to an anonymous request, and a plugin client bundle is served only through the exact combined ?? URL printed in the authenticated index — a bare /plugins/<name>/client.js answers 404. The check therefore builds an authenticated session first.
Environment used by the check: DSH_WEB_BASE (default http://127.0.0.1:3080), DSH_WEB_TOKEN (the token; when unset, the script reads the last one printed to the unit journal), DSH_WEB_UNIT (default dsh-web.service). No secret is stored in the script.
20. Internal Refactor: Schedule Parsing and Arming (#97)
Developer-facing, no behaviour change. parseScheduleExpression was split into small functions that keep the same branch order — parseAtExpression, parseRelativeOneShot, parseIntervalExpression, parseAliasExpression, parseCronExpression — and scheduleTask into clearScheduled, scheduleOneShot and scheduleCron. The existing test suite passed unchanged and targeted tests were added for branch precedence and error messages.
21. Performance & Process Isolation Pack (Added in v0.2.9, #134)
- Process-Tree Termination: Shell and script tasks run in an isolated process group (
detached: true on POSIX); aborts and timeouts send SIGTERM followed by SIGKILL to the entire group (-child.pid) to eliminate orphan and zombie processes.
- Concurrency Throttling: Default safe limit
maxConcurrent = 2 prevents CPU and memory spikes during overlapping scheduled runs.
- Transient Error Retry: Exponential backoff retry (up to 3 attempts) for transient network and provider errors (
429, 502, 503, 504, ECONNRESET).
- Network & UI Optimization:
GET /dsh-cron/tasks provides ETag and responds with 304 Not Modified; client UI adapts polling frequency (visibilitychange: 30s in background tabs, 8s in active tabs).
- History Rotation & Archival: Active store holds the latest 100 runs per task; older entries are automatically archived into
tasks-history-archive.json.
- Autonomous PR Reviewer Recipe (#33): Preconfigured recipe in Template Hub with optional toggle
prReviewerEnabled in settings.
22. Automation, Task Chaining & Observability Pack (Added in v0.2.10, #137)
- Two-Way Telegram Interactive Controls: Run completion notifications include inline keyboard buttons (
🚀 Run Now, ⏸️ Pause / ▶️ Resume, 📋 Last Output). Actions are securely routed via POST /dsh-cron/telegram/webhook with Chat ID authorization matching plugin settings or harness defaults.
- Task Chaining & Pipelines: Tasks can declare
onSuccess and onFailure downstream task triggers. Upstream output is automatically forwarded to child tasks via $DSH_PREV_OUTPUT environment variable for shell/script tasks and {{prevOutput}} variable interpolation in LLM prompts. Infinite execution loops are strictly prevented with a recursion depth limit (max 5 consecutive executions).
- Structured LLM Actions: Autonomous model runs can output structured JSON directives to trigger secondary tasks, dispatch channel notifications, or open issues. Controlled via
llmActionsEnabled: false settings toggle (strictly disabled by default).
- History Archival & Latency Insights: Active task store retains the most recent 100 runs for instant performance, while older runs are archived in
tasks_archive.json. New REST endpoints GET /dsh-cron/tasks/:id/archive and GET /dsh-cron/tasks/:id/stats expose historical records and aggregated latency statistics. Task UI displays execution duration latency badges with color thresholds (<5s green, <30s yellow, >=30s red).
- Enriched Prometheus Observability: The
/dsh-cron/metrics endpoint exports the active concurrency gauge dsh_cron_concurrent_running, per-task prompt/completion token consumption counters dsh_cron_task_tokens_total{task,model,type}, and per-task cost estimation counters dsh_cron_task_cost_usd_total{task,model}.
23. Advanced Reliability, Self-Healing, Heartbeats & UX Pack (Added in v0.2.11, #139)
- Heartbeat & Dead Man's Snitch: Support for inverted cron monitoring where external backup scripts or background jobs ping
/dsh-cron/heartbeat/:id (or /dsh-cron/api/heartbeat/:id). If a ping is missed within heartbeatIntervalSeconds + gracePeriodSeconds, the task is flagged as missed, dispatches an overdue failure alert, and triggers an onFailure recovery pipeline.
- Pre-flight Execution Gates: Guard against wasted model tokens and noisy failures with preliminary checks (
preflightType: http status 2xx, command exit code 0, or disk free MB space). Failing the gate cleanly marks the task as skipped without invoking LLMs or dispatching channel errors.
- Dry-Run Mode & Schedule Simulator: Execute tasks on demand via
POST /dsh-cron/tasks/:id/dry-run or UI 🧪 Dry Run button without persisting run history or delivering messages. Preview next calculated execution dates via POST /dsh-cron/schedule/preview.
- Priority Queues & Concurrency Pools: When the concurrent run limit is reached, queued tasks are ordered by
priority (1 = highest, 10 = lowest) to ensure critical system alerts execute ahead of bulk background jobs.
- Self-Healing Runbooks & Auto-Diagnosis: Failed tasks automatically execute an optional compensatory
selfHealingCommand (e.g. system service restart or temp cleanup). Model failures can trigger autoDiagnose: true to append an instant root-cause diagnosis.
- Web UI Archive & Pipeline Visualization: Interactive archive drawer with pagination and full log viewing; visual indicators for
➜ onSuccess and ↳ onFailure task connections.
24. Automatic Agent Preset Mounting & Tool Availability (#141 / GH-1, Added in v0.2.12)
- Automatic Agent Preset Mounting: Scheduled autonomous
llm tasks and on-demand agent runs now automatically resolve and mount the system agent preset (defaulting to user's standard preset via presets.mount(agentCtx, preset.id) in setup). Scheduled agent turns now possess complete tool access (file editing, workspace exploration, shell commands, etc.) instead of running with bare chat sessions.
- Per-Task Preset Override: Tasks can explicitly configure an
agentPreset identifier in the task form UI, REST API, or profile jobs (e.g. coding, system, minimal). When left empty, tasks automatically resolve to the harness's default preset.
- Graceful Toolset Fallback: If the
agentPresets service is absent or an unknown preset ID is provided, the scheduler logs an informative warning and safely proceeds with basic model execution without aborting the scheduled task.
25. Persistent Execution Sessions & Context Continuity (targetSessionId, Added in v0.2.13, #143)
- Continuous Conversation Context: Tasks can configure a
targetSessionId. When set, the scheduler resumes the existing session via agents.resume() instead of generating an isolated ephemeral session (cron-exec-${id}-${uuid}) on every tick. The agent retains conversational memory across runs, allowing periodic auditors or assistants to reference prior findings and outputs directly in context.
- Context Window Protection & Session Rotation (
targetSessionReset): To prevent unbounded context growth and token cost explosion over long schedules, tasks can set an automatic rotation policy:
never: Continues a single session thread indefinitely.daily: Automatically rotates the session daily (<id>-YYYY-MM-DD).weekly: Automatically rotates the session weekly (<id>-YYYY-Www).- Custom templating: Any
targetSessionId containing {{date}} automatically interpolates today's date (YYYY-MM-DD).
- Main Chat Visibility: Persistent sessions are omitted from
sessions.archive() and unflagged from ephemeral/internal, making them visible and interactable directly in the DeepSeek Harness chat interface.
- Preset & Tooling Compatibility: Resumed sessions automatically preserve and remount configured
agentPresets, ensuring full access to workspace, terminal, and file tools on every turn.
- Inspiration credit: Community idea originally explored by @RaulLazaro.
26. Reliability, Hardening & Self-Healing Maintenance Pack (v0.2.14, #145)
- Automatic Retry Budget Reset: Fixed retry exhaustion amnesia. When a task exhausts its configured retry attempts (
maxRetries), its attempts counter is automatically cleared, ensuring that subsequent scheduled ticks retain their full retry budget. Any regular or manual execution also guarantees a clean retry budget on launch.
- Zombie Queue Elimination: Tasks paused via UI/API or deleted are immediately purged from the scheduler's concurrency waiting queue (
this.queue). Additionally, when dequeuing tasks upon concurrency slot release, inactive or deleted tasks are safely skipped.
- Bounded History Archive: Long-running production instances with high-frequency cron tasks safely bound
tasks-history-archive.json to the latest 1,000 runs per task, eliminating unbounded disk growth and synchronous JSON serialization lag.
- Disaster Recovery & Store Auto-Backup:
TaskStore maintains an automatic atomic .bak copy of tasks.json on every successful save. In the event of process crash or file corruption, the store snapshots the corrupted file to tasks.json.corrupted.<timestamp> for forensic analysis and self-heals seamlessly from the backup.
- Context Window Overflow Auto-Recovery: For persistent sessions (
targetSessionId), if an agent turn fails due to context window saturation (context_length_exceeded), the runner detects the overflow, archives the exhausted session, automatically rotates to a fresh session thread, and transparently retries execution without task failure.
- Windows Process Tree Termination: External process runners on Windows now execute
taskkill /pid <pid> /T /F on task cancellation or timeout, preventing zombie background processes and orphan shells from lingering in the operating system.
27. Modal Dialog Viewport Bounds & Package Hygiene (v0.2.15, #153, #148, #151, #152)
- Viewport Height Bounding & Sticky Footer: Modal forms (including task creation, editing, and ready recipe presets) now strictly respect viewport boundaries with
max-height: min(90vh, calc(100vh - 36px)) and smooth internal scrolling. The modal action footer (Cancel, Save, Create) is pinned via sticky positioning (position: sticky), guaranteeing that critical buttons remain immediately accessible and never clipped regardless of form complexity or display scale.
- Overlay Scroll Protection: Modal overlays now provide safe viewport padding and overflow handling (
overflow-y: auto), preventing flexbox centering clipping on small screens.
- Package Weight Optimization: Removed redundant documentation duplicates from npm distribution files, trimming tarball weight by over 32 kB and unpacked size by ~102 kB.
- Cordis Client Inject Compliance: Explicitly declared
locale and slots dependencies in package.json client injection manifest (dsh.client.inject).
31. Quality & Preflight Hardening Pack (v0.2.19, #149, #152, #155, #156, #162)
- Zero Empty Catch Blocks (#156): Implemented
lib/best-effort.js matching standard architecture with synchronous/asynchronous error suppression, fallback value handling, and optional context logging. Eliminated all 63 empty catch blocks across runner, scheduler, store, and UI client scripts.
- CI Workflows & Local Preflight Gate (#162): Added automated CI workflows (
.gitea/workflows/ci.yml and .github/workflows/ci.yml) running test suites and enforcing a strict preflight gate (scripts/ci-preflight.mjs) that halts on any syntax error, empty catch, theme hardcoding, or leak attempt.
- Theme Token Modernization (#149): Replaced all remaining raw
rgba(...) declarations in UI styles and modals with native color-mix(in srgb, var(--token) N%, transparent).
- Plugin Manifest Declarations (#152): Updated
dsh.client.inject in package.json to declare full package dependencies (@deepseek-ai/dsh-client-locale, @deepseek-ai/dsh-client-ui-slots).
- Production Export Integration (#155): Connected test-only exports (
findDestructiveRecipe in listRecipes, shouldNotifyTask in shouldSendToChannel, and TEMPLATE_VARIABLES in buildTemplateVars) into active production pipelines.
30. Updater Localization in English & Chinese (v0.2.18, #160)
- Settings Card Updater Localization (#160): Added native translations for all 10 in-app updater keys (
updater.title, updater.btnCheck, updater.checking, updater.btnUpdate, updater.updating, updater.desc, updater.current, updater.available, updater.upToDate, updater.success) into English (en) and Chinese (zh) dictionaries in lib/client-src/10-locales.js. In accordance with DSH core plugin architecture, Russian localization is maintained externally via dsh-russian-lang.
29. Client Modular Decomposition & Theme Standardization (v0.2.17, #149, #150)
- Modular Client Architecture (#150): Decomposed monolithic
lib/client.js (~3950 lines) into 14 focused, single-responsibility fragments under lib/client-src/ (none exceeding 580 lines). Integrated zero-dependency build script scripts/build-client.mjs wired into package.json (build:client, pretest). Development fragments are excluded from npm distribution via "files": ["lib/*.js", ...].
- DSH Theme Tokens & Visual Standardization (#149): Replaced inline styles on task type badges (
onSuccess, onFailure, heartbeat, targetSession, preflight) with dedicated .dsh-cron-tag-* CSS classes powered by semantic --dsh-cron-* theme variables. Modal overlay now adapts dynamically using var(--dsw-alias-bg-mask, rgba(0, 0, 0, 0.75)), and keyframe pulse animations use theme variables without hardcoded RGBA.
- Label Governance & Triage Audit (#95): Standardized 100% of repository issues and triage on the canonical repo-level label set.
28. In-App One-Click Auto-Updater & Error Resilience (v0.2.16, #147, #155, #156)
- Plugin Self-Updater (#147): Added in-app one-click self-updating module (
lib/updater.js) with /api/dsh-cron/update endpoint and dedicated Settings UI card. Automatically queries npm registry, compares semver versions including pre-releases, and upgrades @goodandready/dsh-cron in-place through the DSH CLI without manual SSH sessions. POST updates are protected via origin validation (rejectCrossOrigin).
- Silent Failure Elimination (#156): Replaced silent empty catches with diagnostic logging: uncompleted import transaction rollbacks are surfaced to system logs with warning severity, dynamic core module fallback reasons are logged, and session opening failures inform the user with actionable notifications.
- Dead Code & Export Hygiene (#155): Cleaned unused legacy helpers (
CHANNEL_LABELS, makeInspectAsk), stripped unnecessary exports from 16 internal modules, and wired supportsSilentRule directly into execution pipeline.
📦 Installation
Install into your DeepSeek Harness web profile:
dsh plugin --profile web add @goodandready/dsh-cron
Restart your DeepSeek Harness instance and refresh the browser.
⚙️ Configuration (settings.yaml)
Configuration can be applied in settings.yaml or managed interactively via the plugin settings card in DSH:
# settings.yaml
dsh-cron:
botToken: "" # Telegram Bot API token (kept secret; see notes)
chatId: "" # Telegram chat ID that receives reports
notifyTelegram: false # deliver reports for every task globally
onlyOnFailure: false # deliver reports only for failed runs
kanbanBaseUrl: "http://127.0.0.1:3000" # dsh-kanban HTTP API base URL
defaultTimezone: "" # default IANA time zone for schedules (empty = server local)
maxConcurrent: 0 # max parallel task runs (0 = unlimited)
heartbeatUrl: "" # dead man's snitch URL pinged on the heartbeat interval
heartbeatIntervalSec: 0 # heartbeat ping interval in seconds (0 = off)
# --- delivery channels ---
botTokenRef: "" # credential NAME for the Telegram bot token
template: "" # global message template, e.g. "⏰ {title} — {status}"
channelTemplates: {} # per-channel template overrides keyed by channel id
deliveryTimeoutMs: 15000 # per-channel delivery timeout; slow channel = failure, others unaffected
discordWebhookUrl: "" # Discord webhook
slackWebhookUrl: "" # Slack incoming webhook
ntfyUrl: "https://ntfy.sh" # ntfy server; ntfyTopic / ntfyTokenRef
ntfyTopic: ""
ntfyTokenRef: ""
barkServerUrl: "https://api.day.app" # Bark server; barkKey = device key
barkKey: ""
pushplusUrl: "https://www.pushplus.plus/send" # pushplusTokenRef
pushplusTokenRef: ""
ttsBaseUrl: "http://127.0.0.1:3080" # dsh-tts base URL
giteaBaseUrl: "" # giteaRepo = owner/repo, giteaTokenRef = credential NAME
giteaRepo: ""
giteaTokenRef: ""
# --- external REST API (#54) ---
apiToken: "" # bearer token for the external /dsh-cron/api/* surface (masked; empty = 503)
Configuration Parameters
| Parameter | Type | Default | Description |
|---|
botToken | string | "" | Telegram Bot API token. If left empty, the plugin tries to inherit the bot configured for dsh-messenger-gateway in the DSH settings as a best-effort fallback. Stored as a secret field; the UI only ever displays a masked value |
chatId | string | "" | Telegram chat ID that receives the reports. Empty value falls back to the first allowed chat of dsh-messenger-gateway |
notifyTelegram | boolean | false | Global switch: deliver run reports to Telegram |
onlyOnFailure | boolean | false | Global switch: deliver reports only for error/timeout runs |
kanbanBaseUrl | string | "http://127.0.0.1:3000" | Base URL of the dsh-kanban HTTP API used for automatic card creation |
defaultTimezone | string | "" | Default IANA time zone for task schedules; empty = server local time |
maxConcurrent | number | 0 | Cap on parallel task runs; extra runs are recorded as skipped (0 = unlimited) |
heartbeatUrl | string | "" | Dead man's snitch URL pinged every heartbeatIntervalSec while the scheduler is alive |
Notes:
- Run history is capped at 50 entries per task (fixed); each entry keeps up to 4000 characters of output.
- Tasks run in the server's local timezone; cron expressions are evaluated by
croner on the host clock.
- Tasks persist in the DSH data directory (
cron/tasks.json) and survive restarts; missed one-shots are detected on startup.
🔌 HTTP API Reference
All endpoints are served by the DSH web server under /dsh-cron/. Read endpoints are open to the local UI; mutating endpoints reject cross-origin requests and accept bodies up to 1 MB. Creating script-type tasks over HTTP additionally requires the x-dsh-cron-confirm: script header, which forged cross-site posts cannot attach.
| Method | Path | Description |
|---|
GET | /dsh-cron/tasks | List tasks; query params status (all/active/paused/completed), query (substring search). Returns tasks, recommendation templates and aggregated stats |
POST | /dsh-cron/tasks | Create or update a task (id present → update). Requires title, schedule, prompt |
GET | /dsh-cron/tasks/:id/history | Run history, ?limit=20 |
POST | /dsh-cron/tasks/:id/run | Trigger an immediate manual run |
POST | /dsh-cron/tasks/:id/pause | Pause the schedule |
POST | /dsh-cron/tasks/:id/resume | Resume the schedule |
POST | /dsh-cron/tasks/:id/toggle | Toggle active/paused |
POST | /dsh-cron/tasks/:id/duplicate | Creates a paused copy of a task: configuration copied, run state (history, counters, last run) reset |
GET | /dsh-cron/recipes | Built-in recipe catalog: ready-to-use monitoring presets grouped by category, all read-only |
GET | /dsh-cron/tasks/export | Versioned JSON document with task configuration only — no history or counters. Channels reference credentials by name, but a task-level env map or HTTP headers you typed in yourself are part of the configuration and therefore appear in the file |
🧪 Testing & Preflight Verification
Run the automated test suite covering schedule parsing, the scheduler engine, atomic storage, HTTP helpers, notifications and tool contracts:
npm test
Run the local preflight gate to verify syntax, zero empty catch blocks, theme token compliance, package boundaries and leak protection:
node scripts/ci-preflight.mjs
📄 License
MIT © GooDAnDReaDY
