# dsh-automation

> Introducing standalone session scheduled tasks for DeepSeek Harness: execute self-contained tasks on schedule within the new Agent + Session, with dual access via Web console and Agent tools.

## Metadata

- Author: [@titanwings](https://github.com/titanwings)
- Repo: <https://github.com/titanwings/dsh-automation.git>
- GitHub: [titanwings/dsh-automation](https://github.com/titanwings/dsh-automation)
- Stars: 69
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `automation`, `coding-agent`, `cordis`, `deepseek-harness`, `dsh`, `dsh-bundle`, `dsh-plugin`, `scheduled-tasks`
- Forks: 5
- Open Issues: 2
- Last push: 2026-08-17T07:05:01.000Z
- Added: 2026-08-13T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:titanwings/dsh-automation
```

## Wiki

## One-Line Positioning
dsh-automation adds "standalone scheduled task" capability to DeepSeek Harness. Whenever it's time, it executes a self-contained prompt in a brand new root Agent + new Session, and leaves each execution result as an auditable record. Unlike DSH Core Schedule which is "come back to this session in ten minutes", each execution here is an independent new session.

## Core Capabilities
- Supports four scheduling types: one-time, fixed interval (≥5 minutes), daily, weekly (by IANA timezone), daily/weekly schedules are normalized to RFC 5545 RRULE for persistence
- Each trigger executes in a brand new root Agent + new Session, with prompts explicitly marked source.kind = "automation" for auditability
- Provides a Web "Automation" tab for creating, pausing/resuming, running immediately, deleting, and viewing history directly in the browser
- Provides 6 Agent tools (automation_create / list / update / run_now / runs / delete), tool scope bound to the current workspace, cannot cross workspaces
- Each execution leaves a complete record (definition version, prompt snapshot, target snapshot, scheduled time, result Session ID, summary, structured errors), status includes queued / running / succeeded / failed / skipped / cancelled
- Security guardrails: only accepts read-only / workspace-write permissions; approval policy fixed to never; background processes rejected; tool whitelist strictly validated at the executor layer

## Technical Implementation
- **Language**: TypeScript (ESM, main entry compiled to lib/)
- **Key Dependencies**: luxon (timezone and DST calculations), zod (domain schema and schedule validation), @deepseek-ai/cordis (host plugin runtime)
- **Architecture Pattern**: Single Cordis plugin split into two lines—Host side (src/index.ts / service.ts) holds the single authoritative service, Client side (src/client/index.ts) injects Web tabs via conversation.view slot; Agent tools are dynamically attached to each root Agent through agent/created events
- **Entry Files**: src/index.ts (Host entry), src/client/index.ts (Web client entry, exposed via package.json#dsh.client)

## Use Cases
Suitable for people who need DSH to "independently" complete coding/inspection/regression tasks at specified times or intervals, such as automatically running regression triage at 9:30 AM on workdays, generating weekly repository health reports, or delayed retesting for an unstable failure. Tasks must be written as self-contained and independently verifiable, not suitable for "continue from last chat" or "fix everything" that relies on conversation context.

## Prerequisites and Compatibility
| Dependency | Minimum Version | Notes |
|---|---|---|
| Node.js | ^22.19.0 \|\| >=24.0.0 | Enforced by package.json#engines; won't run below this version |
| React (optional) | ^18.2.0 | peerDependencies, optional; only needed for Web client |
| Platform | Cross-platform | No os/cpu restrictions declared; pure TypeScript/Node implementation |
| Native modules | None | No dependencies on node-pty, node:sqlite, or similar native modules |

## Installation
```bash
dsh plugin --profile web add github:titanwings/dsh-automation
```

## Configuration Options
| Configuration | Type | Description | Default Value |
|---|---|---|---|
| maxConcurrentRuns | Integer 1-32 | Maximum concurrent runs allowed at any time; each automation remains internally exclusive | 2 |
| runTimeoutMinutes | Integer 1-1440 | Maximum duration in minutes before a run is cancelled and marked failed | 60 |
| misfireGraceMinutes | Integer 0-10080 | Maximum delay in minutes for catching up on recent due items after Host recovery; exceeded items are marked as misfire skipped | 15 |
| historyLimit | Integer 1-5000 | Maximum finished run records retained per automation; in-progress or queued runs are never trimmed | 200 |
| archiveRunSessions | Boolean | Whether to archive finished run Sessions from the regular session list; current DSH host has no unarchive API, archived sessions cannot be reopened | false |

## FAQ

**Q: Does this plugin add a cron to DSH?**

A: It's more restrictive and secure than cron. Each trigger executes a self-contained prompt in a brand new root Agent + new Session, with permissions limited to read-only or workspace-write only; danger-full-access is not accepted, and arbitrary shell execution is prevented.

**Q: Can automation tasks inherit the current session's context, inbox, or historical approvals?**

A: No. Each run cannot access the source session's history, inbox, or historical authorizations; tasks are explicitly delivered with source.kind = "automation" for traceable behavior.

**Q: If the host crashes and misses an execution time, will it rerun?**

A: No. Within the default 15-minute tolerance window, only the most recent due item is backfilled; earlier ones are marked as misfire skipped; runs with potential side effects are not silently re-executed.

**Q: What happens if execution times out or crashes mid-run?**

A: A single run is cancelled and marked failed after the default 60-minute timeout; when the Host restarts, any lingering queued/running records are uniformly marked as failed(host_interrupted), with no silent retry.

**Q: Can I manage automations from both Web and Agent?**

A: Yes. The Web has an "Automation" tab (create, pause/resume, run immediately, delete, view history), and any root Agent can invoke 6 tools: automation_create / list / update / run_now / runs / delete. Tool scope is bound to the caller's current workspace and cannot target other workspaces.

**Q: Does deleting a task also delete its history?**

A: No. Deletion only removes the definition; finished run records are retained for auditing; only the oldest finished records are trimmed by historyLimit (default 200 per task); in-progress or queued runs are never trimmed.

## Learning Curve
Advanced — Requires understanding DSH's workspace, Agent presets, permission presets, and session model, plus writing "self-contained, independently verifiable" prompts; scheduling syntax and timezone/DST rules also require some learning time.

## Known Issues and Limitations
- No same-session heartbeat reminders; use DSH Core Schedule if needed
- No raw cron expressions or arbitrary shell commands
- Does not accept danger-full-access in unattended mode
- No automatic retry for runs with potential side effects
- No Git worktree creation or cleanup
- No multi-workspace targeting, DAG dependencies, or cross-run hidden memory
- No email, SMS, push, or other external notification channels
- No "exactly once" guarantee for external side effects, only "at most once" dispatch
- Local execution only; multiple Hosts cannot share the same storage directory (README.md:230)
- Version 0.1 does not implement OS-level daemon
- Tool whitelist rejects bash/pwsh with run_in_background=true (src/executor.ts:33-42)
- After enabling archiveRunSessions, archived Sessions cannot be reopened in the current Harness version

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-automation](https://deepseek-plugin.org/plugins/titanwings/dsh-automation)
Wiki generated by AI (model: `MiniMax-M2.7`)