Introduction¶

DeepSeek Harness (dsh) is a plugin-based workflow framework. When developing agents or managing automated tasks, you often need the system to execute specific instructions in the background, independently of the current session. dsh-cron is an unattended scheduled job plugin for DeepSeek Harness, supporting task triggering via cron expressions, fixed intervals, or one-time immediate times.

Unlike session-dependent persistent reminders, dsh-cron is host-side scheduling: jobs belong to background processes that are not bound to interactive sessions, and will trigger automatically as long as the dsh process is running.

Core Features¶

This plugin provides the following core capabilities:

1. Three trigger methods

   • cron: Supports 5-field standard expressions and explicit IANA time zones.
   • everySeconds: Anchor-aligned fixed intervals, with a minimum interval of 60 seconds.
   • at: Supports one-time trigger times in RFC3339 format.

2. Three task types

   • agent: Creates a headless agent to execute prompts through the full dsh toolchain.
   • command: Spawns child processes directly on the host and records exit codes and output tails.
   • callback: Invokes registered plugin callback functions.

3. Three declaration methods

   • Declarative configuration via Profile Config.
   • Declaration via Runtime Overlay (sidebar + or session command).
   • Registration by calling the cron service from other plugins.

4. Reliability guarantees

   • State is persistently stored in ctx.storage.domain (domain name cron).
   • Semantics are at-most-once, meaning lastFiredMs is persisted before execution.
   • Supports clock discipline: long waits are chunked to prevent triggering anomalies caused by clock jumps.

5. Policy configuration

   • overlap: When the previous task has not finished, choose skip (skip), queue (queue), or replace (replace).
   • misfire: For missed triggers while the process is suspended, choose skip (ignore) or runOnce (run once).

Installation and Enablement¶

Install the plugin using one of the following methods:

1. Install via Command Line¶

dsh plugin --profile web add https://github.com/squirrel20/dsh-cron/releases/latest/download/dsh-cron.tgz

2. Install via Plugin Market¶

After installing dsh-market, go to Settings → Plugin Market, search for dsh-cron, and install it.

After installation, add "dsh-cron" to the dsh.profile.bundles configuration to enable it.

Declaring Tasks¶

The plugin supports declaring persistent tasks in configuration files or creating them dynamically at runtime.

Declaring via Profile Config¶

Declare it in the Profile’s cordis.patch.yml, suitable for declarative, version-controlled resident tasks:

- id: dsh-cron
  config:
    historyLimit: 50
    jobs:
      - name: daily-log-review
        schedule: { cron: "0 7 * * *", timeZone: "Asia/Shanghai" }
        task:
          kind: agent
          prompt: Read yesterday's logs under logs/, summarize anomalies.
          cwd: /path/to/project
          timeoutSeconds: 1800
        policy: { overlap: skip, misfire: skip }
        delivery:
          argv: ["/usr/local/bin/notify", "--stdin"]
          onlyOnFailure: true
      - name: heartbeat
        schedule: { everySeconds: 3600 }
        task: { kind: command, argv: ["./scripts/heartbeat.sh"], cwd: /path/to/project }
    sessionGc:
      enabled: true
      graceMinutes: 30

Note: Configuration errors (such as duplicate names or invalid expressions) report errors immediately at mount time and do not fail silently.

Declaring via Plugin Service¶

In other plugins, you can dynamically register tasks using ctx.cron.registerJob.

Security and Permissions¶

Important: Cron tasks belong to host administration and are not sandbox extensions. Tools executing tasks require the danger-full-access permission policy and the never approval policy. Preset names cannot authorize alone, and unresolved permission policies will cause execution failure.

Web Write Control¶

If you need to operate through the Web UI, you must set webControlToken, and its length must be at least 32 characters. This token is used for verifying the Authorization: Bearer <webControlToken> header.

Example token generation:

openssl rand -hex 32

Notes:
* Web writes require an HTTPS connection.
* Configuration declarations and plugin registrations are treated as trusted host declarations, and commands and delivery commands are executed on the host.
* Existing manual jobs without matching authorization records are isolated (requiresApproval: true); edit and save them to authorize.

Use Cases and Considerations¶

• Use cases: Background tasks that require periodic execution, such as log analysis, health checks, scheduled notification delivery, and scheduled data synchronization.
• Dependencies: The plugin depends on zod and several DeepSeek Harness related libraries; note version compatibility ranges during installation.
• Ecosystem context: The plugin is maintained by the community, and its directory page is located at skillhub.cn.