@argszero/cordis-plugin-schedule-cron 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 argszero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# @argszero/cordis-plugin-schedule-cron
+
+Cron-driven **autonomous task runs** for the deepseek-harness (`dsh`) agent.
+
+Unlike the official [`@deepseek-ai/dsh-schedule`](https://www.npmjs.com/package/@deepseek-ai/dsh-schedule) — which only **messages the live session** (a follow-up delivered into whatever agent is already running and idle) — this plugin **spawns a fresh agent run** when a calendar fire occurs, so scheduled work actually happens even with no browser session open. It is the "EMRG-style" scheduled-task runner: a cron calendar rule awakens a brand-new agent turn.
+
+## Why this exists
+
+`dsh-schedule` explicitly documents the gap:
+
+> "当交付必须到达会话之外时请避开它...或者当你需要**「每个工作日 9 点」这类日历规则**时：重复提醒**只按固定间隔运行**。"
+
+That is, it has:
+- **No calendar rules** — only `after_seconds` / `at` / `every_seconds` fixed intervals.
+- **No autonomous drive** — it delivers into a live session; closed/cold sessions just leave the reminder overdue.
+
+`dsh-cron` fills both: standard 5-field cron calendar rules and a fresh agent run per fire.
+
+## Install
+
+```sh
+npm install @argszero/cordis-plugin-schedule-cron
+```
+
+Then mount it into your `dsh` profile (a Cordis overlay). For example:
+
+```yaml
+# cordis.yml fragment
+plugins:
+  schedule-cron:
+    cron:
+      - id: daily-triage
+        expression: "0 9 * * 1-5"          # 09:00 Mon–Fri
+        task: "Review the open issues in this repo and summarize anything urgent."
+      - id: weekly-report
+        expression: "0 8 * * 1"             # 08:00 Monday
+        task: "Write this week's status report."
+        provider: deepseek
+        model: deepseek-chat
+        cwd: /path/to/workspace
+    tickMs: 60000
+```
+
+## How it works
+
+On a tick (`tickMs`, default `60_000`), the plugin checks each rule. When a rule is due:
+
+1. `ctx.agents.create({ sessionId, meta, agentOptions })` composes a **fresh agent** (a brand new session) — the same primitive the ACP bridge uses for non-interactive sessions.
+2. `agent.followup(createUserMessage({ content: [{ type: 'text', text: task }], source: { kind: 'plugin', plugin: 'schedule-cron' } }))` drives its first turn **autonomously**.
+
+The fire uses a **monotonic per-rule cursor** (`croner`), so:
+- Each occurrence fires exactly once.
+- On first mount, every cursor anchors to its **next future** occurrence (no backfill burst for past times).
+- A long-downed schedule is capped at `MAX_CATCH_UP_PER_TICK = 4` fires per tick (no burst).
+- Disabled rules (`enabled: false`) are parsed but never fired.
+
+A rule's state is recoverable across a restart via `initialState` (`lastFiredAt` per rule id), so a process restart mid-window resumes forward instead of re-firing.
+
+## API
+
+### Config
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `cron` | `CronRule[]` | `[]` | The rules to fire. |
+| `tickMs` | number | `60000` | How often (ms) to check for due rules. |
+| `initialState` | `CronRuleState[]` | `[]` | Restore `lastFiredAt` baselines across a restart. |
+
+### `CronRule`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Stable persistence key (defaults to `expr:<expr>`). |
+| `expression` | `string \| string[]` | 5-field cron; an array acts as alternatives. |
+| `task` | string | Prompt delivered as the spawned agent's first turn. |
+| `provider` | string | Provider route (defaults to harness default). |
+| `model` | string | Model id (defaults to harness default). |
+| `cwd` | string | Working dir for the spawned agent (defaults to harness default). |
+| `enabled` | boolean | `true` if the rule should fire (defaults true). |
+
+### Engine (pure, no harness needed)
+
+```ts
+import { collectDue, initialCursor, resumeCursor, ruleIdOf, normalizeExpression } from '@argszero/cordis-plugin-schedule-cron'
+```
+
+The `collectDue(cursors, now)` function is dependency-free and unit-tested, so it can be driven by any timer (not just Cordis).
+
+## Development
+
+```sh
+npm install
+npm run build   # tsc emits lib/
+npm test        # node test/logic.test.mjs (needs build first)
+```
+
+## License
+
+MIT

package/lib/engine.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Pure fire-engine logic for the cron plugin.
+ *
+ * No Cordis dependency: the computation (which rules are due, how to advance a
+ * per-rule cursor) is kept pure so it can be unit-tested without a harness.
+ * The Cordis plugin (`index.ts`) owns the tick timer and the
+ * `ctx.agents.create()` call; this module only answers "what should fire now".
+ *
+ * @module @argszero/cordis-plugin-schedule-cron/engine
+ */
+import { Cron } from 'croner';
+import type { CronRule, CronRuleState } from './types.js';
+/**
+ * The deadline offset (ms) a fire must sit before the clock for a rule already
+ * behind on multiple occurrences. We fire at most one occurrence per tick so a
+ * long-downed schedule doesn't backfill a burst of runs.
+ */
+export declare const MAX_CATCH_UP_PER_TICK = 4;
+/**
+ * A rule that is due to fire right now, along with the occurrence timestamp.
+ */
+export interface DueFire {
+    readonly rule: CronRule;
+    /** The occurrence this fire represents (the schedule time it satisfies). */
+    readonly occurrenceAt: Date;
+}
+/**
+ * A normalized, mutable view of one rule's schedule state. The plugin holds a
+ * `Map<id, CronCursor>`; each cursor is advanced one occurrence per fire.
+ */
+export interface CronCursor {
+    /** The rule this cursor serves. */
+    readonly rule: CronRule;
+    /** The parsed Cron engine (one per rule, reused across ticks). */
+    readonly cron: Cron;
+    /** The next un-fired occurrence. `null` when the rule is exhausted/absent. */
+    next: Date | null;
+}
+/**
+ * Resolve a stable id for a rule. Falls back to the joined expression so a
+ * rule configured without an explicit `id` still has a durable persistence key.
+ */
+export declare function ruleIdOf(rule: CronRule): string;
+/**
+ * Normalize a cron expression (or array of them) to a single croner-parseable
+ * string. `croner` accepts a single string; an array is joined with `,` so
+ * multiple expressions act as alternatives on the same rule.
+ */
+export declare function normalizeExpression(expression: CronRule['expression']): string;
+/**
+ * Compute the next strict occurrence of a cron expression at or after `from`.
+ * Returns `null` when the expression yields no future occurrence.
+ */
+export declare function nextOccurrence(cron: Cron, from: Date): Date | null;
+/**
+ * Build the initial cursor for a rule. On first boot we anchor the cursor to
+ * the **next** future occurrence (never a past one), so a freshly-mounted
+ * schedule does not immediately backfill a burst of runs for every past
+ * occurrence.
+ *
+ * @param rule - the cron rule.
+ * @param now - the current time (the boot anchor).
+ */
+export declare function initialCursor(rule: CronRule, now: Date): CronCursor;
+/**
+ * Restore a cursor from persisted `lastFiredAt`. The cursor is anchored one
+ * occurrence **after** the last fire, so a restart in the middle of an
+ * overdue window resumes forward without re-firing a completed occurrence.
+ *
+ * @param rule - the cron rule.
+ * @param lastFiredAt - the ISO timestamp of the last fire recorded for this rule.
+ * @param fallbackNow - the boot anchor when the recorded timestamp is invalid.
+ */
+export declare function resumeCursor(rule: CronRule, lastFiredAt: string, fallbackNow: Date): CronCursor;
+/**
+ * Advance a cursor to the strictly-next occurrence after it fired.
+ * @param cursor - the cursor that just fired.
+ * @returns the advanced cursor (same object).
+ */
+export declare function advance(cursor: CronCursor): CronCursor;
+/**
+ * Decide which rules are due at `now`, producing the fires + the per-rule
+ * state to persist afterwards. At most {@link MAX_CATCH_UP_PER_TICK} fires
+ * total are produced per call so a long-downed schedule doesn't burst.
+ *
+ * @param cursors - the current cursor map (keyed by rule id).
+ * @param now - the current time this tick observed.
+ * @returns the due fires and a snapshot of the post-fire cursors (for the
+ * optional state projection).
+ */
+export declare function collectDue(cursors: ReadonlyMap<string, CronCursor>, now: Date): {
+    fires: DueFire[];
+    state: CronRuleState[];
+};
+//# sourceMappingURL=engine.d.ts.map

package/lib/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAC7B,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAEzD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAA;AAEtC;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAA;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,8EAA8E;IAC9E,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;CAClB;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAI/C;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,QAAQ,CAAC,YAAY,CAAC,GAAG,MAAM,CAE9E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAGlE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,GAAG,UAAU,CAInE;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,GAAG,UAAU,CAM/F;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAGtD;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,EACxC,GAAG,EAAE,IAAI,GACR;IAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE,CAqB9C"}

package/lib/engine.js

@@ -0,0 +1,116 @@
+/**
+ * Pure fire-engine logic for the cron plugin.
+ *
+ * No Cordis dependency: the computation (which rules are due, how to advance a
+ * per-rule cursor) is kept pure so it can be unit-tested without a harness.
+ * The Cordis plugin (`index.ts`) owns the tick timer and the
+ * `ctx.agents.create()` call; this module only answers "what should fire now".
+ *
+ * @module @argszero/cordis-plugin-schedule-cron/engine
+ */
+import { Cron } from 'croner';
+/**
+ * The deadline offset (ms) a fire must sit before the clock for a rule already
+ * behind on multiple occurrences. We fire at most one occurrence per tick so a
+ * long-downed schedule doesn't backfill a burst of runs.
+ */
+export const MAX_CATCH_UP_PER_TICK = 4;
+/**
+ * Resolve a stable id for a rule. Falls back to the joined expression so a
+ * rule configured without an explicit `id` still has a durable persistence key.
+ */
+export function ruleIdOf(rule) {
+    if (rule.id !== undefined && rule.id !== '')
+        return rule.id;
+    const expr = Array.isArray(rule.expression) ? rule.expression.join(',') : rule.expression;
+    return `expr:${expr}`;
+}
+/**
+ * Normalize a cron expression (or array of them) to a single croner-parseable
+ * string. `croner` accepts a single string; an array is joined with `,` so
+ * multiple expressions act as alternatives on the same rule.
+ */
+export function normalizeExpression(expression) {
+    return Array.isArray(expression) ? expression.join(',') : expression;
+}
+/**
+ * Compute the next strict occurrence of a cron expression at or after `from`.
+ * Returns `null` when the expression yields no future occurrence.
+ */
+export function nextOccurrence(cron, from) {
+    const next = cron.nextRun(from);
+    return next ?? null;
+}
+/**
+ * Build the initial cursor for a rule. On first boot we anchor the cursor to
+ * the **next** future occurrence (never a past one), so a freshly-mounted
+ * schedule does not immediately backfill a burst of runs for every past
+ * occurrence.
+ *
+ * @param rule - the cron rule.
+ * @param now - the current time (the boot anchor).
+ */
+export function initialCursor(rule, now) {
+    const cron = new Cron(normalizeExpression(rule.expression));
+    const next = nextOccurrence(cron, now);
+    return { rule, cron, next };
+}
+/**
+ * Restore a cursor from persisted `lastFiredAt`. The cursor is anchored one
+ * occurrence **after** the last fire, so a restart in the middle of an
+ * overdue window resumes forward without re-firing a completed occurrence.
+ *
+ * @param rule - the cron rule.
+ * @param lastFiredAt - the ISO timestamp of the last fire recorded for this rule.
+ * @param fallbackNow - the boot anchor when the recorded timestamp is invalid.
+ */
+export function resumeCursor(rule, lastFiredAt, fallbackNow) {
+    const cron = new Cron(normalizeExpression(rule.expression));
+    const from = new Date(lastFiredAt);
+    const parsed = Number.isNaN(from.getTime()) ? fallbackNow : from;
+    const next = nextOccurrence(cron, parsed);
+    return { rule, cron, next };
+}
+/**
+ * Advance a cursor to the strictly-next occurrence after it fired.
+ * @param cursor - the cursor that just fired.
+ * @returns the advanced cursor (same object).
+ */
+export function advance(cursor) {
+    cursor.next = cursor.next === null ? null : nextOccurrence(cursor.cron, cursor.next);
+    return cursor;
+}
+/**
+ * Decide which rules are due at `now`, producing the fires + the per-rule
+ * state to persist afterwards. At most {@link MAX_CATCH_UP_PER_TICK} fires
+ * total are produced per call so a long-downed schedule doesn't burst.
+ *
+ * @param cursors - the current cursor map (keyed by rule id).
+ * @param now - the current time this tick observed.
+ * @returns the due fires and a snapshot of the post-fire cursors (for the
+ * optional state projection).
+ */
+export function collectDue(cursors, now) {
+    const fires = [];
+    const state = [];
+    let budget = MAX_CATCH_UP_PER_TICK;
+    for (const cursor of cursors.values()) {
+        if (cursor.rule.enabled === false)
+            continue;
+        if (cursor.next === null)
+            continue;
+        if (cursor.next > now)
+            continue;
+        // One fire per tick per rule, up to the catch-up budget.
+        if (budget <= 0)
+            break;
+        const occurrenceAt = cursor.next;
+        fires.push({ rule: cursor.rule, occurrenceAt });
+        advance(cursor);
+        // Persist the occurrence the cursor just consumed (before advance mutated `next`).
+        state.push({ id: ruleIdOf(cursor.rule), lastFiredAt: occurrenceAt.toISOString() });
+        budget -= 1;
+    }
+    return { fires, state };
+}
+//# sourceMappingURL=engine.js.map

package/lib/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @argszero/cordis-plugin-schedule-cron
+ *
+ * Cron-driven autonomous task runs for the dsh harness. On a calendar cron
+ * fire this plugin **spawns a fresh agent run** via `ctx.agents.create()` and
+ * `agent.followup()`, so scheduled work happens even with no browser session
+ * open. This is the EMRG-style "autonomous scheduled task" model, distinct
+ * from the official @deepseek-ai/dsh-schedule which only messages the live
+ * session.
+ *
+ * @module @argszero/cordis-plugin-schedule-cron
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ScheduleCronConfig } from './types.js';
+export type * from './types.js';
+export { collectDue, initialCursor, resumeCursor, ruleIdOf, normalizeExpression } from './engine.js';
+export type { CronCursor, DueFire } from './engine.js';
+/** Cordis function-plugin name. */
+export declare const name = "schedule-cron";
+/** Services required before any scheduled run can be spawned. */
+export declare const inject: string[];
+/**
+ * Mount the cron scheduler. Config holds the rules; each fire spawns a fresh
+ * agent run.
+ */
+export declare function apply(ctx: Context, config: ScheduleCronConfig): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAYlD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpD,mBAAmB,YAAY,CAAA;AAC/B,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACpG,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAEtD,mCAAmC;AACnC,eAAO,MAAM,IAAI,kBAAkB,CAAA;AACnC,iEAAiE;AACjE,eAAO,MAAM,MAAM,UAAgC,CAAA;AAInD;;;GAGG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,kBAAkB,GAAG,IAAI,CA6DpE"}

package/lib/index.js

@@ -0,0 +1,87 @@
+/**
+ * @argszero/cordis-plugin-schedule-cron
+ *
+ * Cron-driven autonomous task runs for the dsh harness. On a calendar cron
+ * fire this plugin **spawns a fresh agent run** via `ctx.agents.create()` and
+ * `agent.followup()`, so scheduled work happens even with no browser session
+ * open. This is the EMRG-style "autonomous scheduled task" model, distinct
+ * from the official @deepseek-ai/dsh-schedule which only messages the live
+ * session.
+ *
+ * @module @argszero/cordis-plugin-schedule-cron
+ */
+import { SessionId as toSessionId } from '@deepseek-ai/dsh-session';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { randomUUID } from 'node:crypto';
+import { collectDue, initialCursor, resumeCursor, ruleIdOf, } from './engine.js';
+export { collectDue, initialCursor, resumeCursor, ruleIdOf, normalizeExpression } from './engine.js';
+/** Cordis function-plugin name. */
+export const name = 'schedule-cron';
+/** Services required before any scheduled run can be spawned. */
+export const inject = ['agents', 'sessions', 'llm'];
+const DEFAULT_TICK_MS = 60_000;
+/**
+ * Mount the cron scheduler. Config holds the rules; each fire spawns a fresh
+ * agent run.
+ */
+export function apply(ctx, config) {
+    const tickMs = config.tickMs ?? DEFAULT_TICK_MS;
+    const rules = config.cron ?? [];
+    // Build the cursor map. Restore from initialState when present, else anchor
+    // each cursor to its next future occurrence (no backfill burst on mount).
+    const cursors = new Map();
+    const bootNow = new Date();
+    const restored = new Map();
+    for (const state of config.initialState ?? [])
+        restored.set(state.id, state.lastFiredAt);
+    for (const rule of rules) {
+        const id = ruleIdOf(rule);
+        if (cursors.has(id))
+            continue;
+        const lastFiredAt = restored.get(id);
+        cursors.set(id, lastFiredAt === undefined
+            ? initialCursor(rule, bootNow)
+            : resumeCursor(rule, lastFiredAt, bootNow));
+    }
+    let stopped = false;
+    /** Spawn one fresh agent run for a fired rule. */
+    async function fire(rule) {
+        const sessionId = toSessionId(`session-${randomUUID()}`);
+        const handle = await ctx.agents.create({
+            sessionId,
+            meta: rule.cwd === undefined ? {} : { cwd: rule.cwd },
+            agentOptions: rule.provider === undefined
+                ? (rule.model === undefined ? {} : { model: rule.model })
+                : { provider: rule.provider, ...(rule.model === undefined ? {} : { model: rule.model }) },
+        });
+        const message = createUserMessage({
+            content: [{ type: 'text', text: rule.task }],
+            source: { kind: 'plugin', plugin: 'schedule-cron' },
+        });
+        // Commit the fire to the durable log even if the turn errors.
+        handle.agent.followup(message);
+        // The agent lives on; the handle's disposer stays with the plugin.
+    }
+    ctx.effect(() => {
+        const onTick = async () => {
+            if (stopped)
+                return;
+            const now = new Date();
+            const { fires } = collectDue(cursors, now);
+            for (const due of fires) {
+                try {
+                    await fire(due.rule);
+                }
+                catch (error) {
+                    ctx.logger.warn('[schedule-cron] fire failed', { rule: due.rule.id, error });
+                }
+            }
+        };
+        const timerId = setInterval(() => { void onTick(); }, tickMs);
+        return () => {
+            stopped = true;
+            clearInterval(timerId);
+        };
+    }, 'schedule-cron.tick()');
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Types for @argszero/cordis-plugin-schedule-cron.
+ *
+ * A cron rule describes a calendar-based recurrence and the task the harness
+ * should run when it fires. Unlike the official @deepseek-ai/dsh-schedule
+ * (which messages the *live* session), each fire here spawns a **fresh
+ * autonomous agent run** via `ctx.agents.create()` + `agent.followup()`,
+ * so work happens even when no browser session is open.
+ *
+ * @module @argszero/cordis-plugin-schedule-cron
+ */
+/** A calendar cron expression in the standard 5-field form. */
+export interface CronRule {
+    /**
+     * The rule id. Persistence keys on this to dedupe fires. Auto-assigned when omitted.
+     */
+    readonly id?: string;
+    /**
+     * Standard 5-field cron expression: `minute hour day-of-month month day-of-week`.
+     * Example: `"0 9 * * 1-5"` for 09:00 on weekdays. May be an array of expressions.
+     */
+    readonly expression: string | readonly string[];
+    /**
+     * The prompt/task to run when the rule fires. This is delivered as a
+     * `UserMessage` into the spawned agent's first turn.
+     */
+    readonly task: string;
+    /**
+     * Optional provider route for the spawned agent. Defaults to the harness's
+     * current default selection when omitted.
+     */
+    readonly provider?: string;
+    /**
+     * Optional model id interpreted by the selected provider. Defaults to the
+     * harness's current default selection when omitted.
+     */
+    readonly model?: string;
+    /**
+     * Optional working directory for the spawned agent. Defaults to the
+     * harness default `cwd` when omitted.
+     */
+    readonly cwd?: string;
+    /**
+     * Whether the rule is enabled. Disabled rules are parsed but never fired.
+     * Useful for a persisted registry that the host toggles without deleting.
+     */
+    readonly enabled?: boolean;
+}
+/**
+ * Per-rule fire state. Duration-preserving key so the plugin can survive a
+ * process restart without re-firing already-completed shedules.
+ */
+export interface CronRuleState {
+    /** The rule id. */
+    readonly id: string;
+    /** The last scheduled occurrence the plugin actually fired. */
+    readonly lastFiredAt: string;
+}
+/** Plugin configuration shape. */
+export interface ScheduleCronConfig {
+    /**
+     * The cron rules this plugin owns. When a rule fires, the plugin spawns a
+     * fresh agent run with the rule's `task` as its first turn.
+     */
+    readonly cron: readonly CronRule[];
+    /**
+     * How often (milliseconds) the plugin wakes to check for due rules.
+     * Defaults to 60_000 (one minute). For fine-grained schedules, lower this
+     * (e.g. 15_000) — but sub-minute cron expressions are not honored by the
+     * standard 5-field form.
+     */
+    readonly tickMs?: number;
+    /**
+     * Optional initial state to restore dedupe baselines across a restart.
+     * Without it the plugin refuses to fire a rule it has no baseline for on
+     * the first boot (guarding against a "backfill burst" of fires for every
+     * past occurrence).
+     */
+    readonly initialState?: readonly CronRuleState[];
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,+DAA+D;AAC/D,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAA;IAC/C;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,mBAAmB;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,kCAAkC;AAClC,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAA;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,aAAa,EAAE,CAAA;CACjD"}

package/lib/types.js

@@ -0,0 +1,13 @@
+/**
+ * Types for @argszero/cordis-plugin-schedule-cron.
+ *
+ * A cron rule describes a calendar-based recurrence and the task the harness
+ * should run when it fires. Unlike the official @deepseek-ai/dsh-schedule
+ * (which messages the *live* session), each fire here spawns a **fresh
+ * autonomous agent run** via `ctx.agents.create()` + `agent.followup()`,
+ * so work happens even when no browser session is open.
+ *
+ * @module @argszero/cordis-plugin-schedule-cron
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@argszero/cordis-plugin-schedule-cron",
+  "description": "Cron-driven autonomous task runs for the dsh harness: fire a calendar cron rule and spawn a fresh agent run via ctx.agents.create(), unlike the official @deepseek-ai/dsh-schedule which only messages the live session.",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.0 <5",
+    "@deepseek-ai/dsh-agent": ">=0.1.0",
+    "@deepseek-ai/dsh-brand": ">=0.1.0",
+    "@deepseek-ai/dsh-llm": ">=0.1.0",
+    "@deepseek-ai/dsh-session": ">=0.1.0",
+    "@deepseek-ai/dsh-tools": ">=0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "prepack": "tsc -p .",
+    "test": "node test/logic.test.mjs"
+  },
+  "engines": {
+    "node": "^22.19 || >=24"
+  },
+  "keywords": [
+    "deepseek",
+    "dsh",
+    "cordis",
+    "plugin",
+    "schedule",
+    "cron",
+    "task-runner",
+    "autonomous",
+    "scheduler"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/argszero/cordis-plugin-schedule-cron.git"
+  },
+  "dependencies": {
+    "croner": "^10.0.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.1-rc.4",
+    "@deepseek-ai/dsh-agent": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-brand": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-session": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-tools": "0.1.2-rc.1",
+    "@types/node": "^26.4.1",
+    "typescript": "^7.0.2"
+  }
+}