@maci0/dsh-cron 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcel W. Wysocki
+
+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,95 @@
+# dsh-cron
+
+Run a prompt on a schedule in a DeepSeek Harness session: `/cron` takes a cron
+expression or plain English like "every weekday at 9am", parses it in code,
+and hands the timer to the harness schedule service, which keeps it across
+restarts and wakes the session when it is due. Only text no grammar reads goes
+to the model.
+
+## What you get
+
+```
+/cron */15 9-17 * * 1-5 check the deploy      # cron; MON-FRI, JAN and @daily work too
+/cron every 5 minutes check the queue         # fixed interval (at least one minute)
+/cron 5m check the build                      # the same, as /loop takes it
+/cron every day at 9am standup notes          # daily wall-clock time
+/cron every mon, wed and fri at 18:00 gym log # weekly
+/cron monthly on the 1st at 9am pay rent      # monthly, as cron
+/cron in 10 minutes check the oven            # once, after a delay
+/cron tomorrow at 9:30 review the PR          # once, at a time
+/cron every day at 9 Europe/Berlin standup    # an explicit zone (the host zone otherwise)
+/cron list                                    # this session's schedules
+/cron delete 2                                # by list number, by id, or all
+```
+
+Each run arrives in the session as a message with the prompt, the way a
+`/loop` round does.
+
+## Install
+
+> **Install it as a bundle.** `dsh plugin add …` mounts the row from the
+> package's own patch layer, which is what the settings editor can write to. A
+> row added with `--patch` is an overlay: it disappears at the next start.
+
+```sh
+dsh plugin --profile web add @maci0/dsh-cron@0.1.1 @deepseek-ai/dsh-experimental-schedule-bundle@0.2.0-rc.2
+```
+
+This installs the public npm package; no GitHub token or `~/.secrets` setup is needed.
+The version is pinned. To upgrade, run the same command with a newer version,
+then restart `dsh web` (bundle layers compose at boot).
+
+The timers belong to the harness schedule service, which ships in the optional
+`@deepseek-ai/dsh-experimental-schedule-bundle` (also on the Plugins page,
+Official group). Without it `/cron` answers an error that names the bundle.
+
+## How it works
+
+`/cron <schedule> <prompt>` tries, in order:
+
+1. **Cron.** When the first five tokens are cron-shaped (numbers, `*`, month or
+   day names, `,` `-` `/`), they are read as the service's five-field Vixie
+   dialect: names become numbers and `@hourly`, `@daily`, `@weekly`,
+   `@monthly`, `@yearly` become their expressions. A field the dialect cannot
+   take (out of range, `L`, `W`, `#`, `?`, a zero step, an inverted range) is
+   an error naming the field, never a guess.
+2. **Phrases.** A small English grammar: `every N minutes|hours|days|weeks`
+   and the compact `5m`/`2h`/`1d` (fixed intervals); `hourly`, `every hour at
+   :15`; `every day|daily`, a weekday, a list (`mon, wed and fri`), a range
+   (`monday to friday`), `weekdays`, `weekends`, each optionally `at <time>`
+   (weekly or daily wall-clock); `monthly on the 15th at 18:30` (cron);
+   `in 10 minutes`, `at 3pm`, `today|tomorrow at <time>`, `on 2026-12-24 at
+   18:00` (once). Times are `9`, `9:30`, `9am`, `7:30pm`, `21:00`, `noon`,
+   `midnight`; a day phrase with no time means 09:00. A trailing IANA zone or
+   `UTC` overrides the host zone.
+3. **The model.** Anything else, including a recognized start followed by a
+   qualifier the grammar does not read (`every 15 minutes during business
+   hours …`), is sent to the agent as a message asking it to set the schedule
+   up with its `schedule_create` tool and report what it created.
+
+The prompt is what follows the schedule (a leading `:` or `to` is dropped); the
+task title is its first line, cut to 80 characters. The reply names the
+schedule and its next run in the host zone. The service validates again and
+its refusal (for example a date that never occurs) is reported with its code.
+
+## Limits
+
+- Recurring intervals are at least one minute, the service's floor.
+- The phrase grammar is English only; other languages reach the model.
+- The model fallback runs as an agent turn, so it needs a working model route,
+  and its result is whatever the agent creates (it reports it in the session).
+
+## Development
+
+```sh
+bun test   # parser table, the /cron handler over a fake schedule service, and a real Cordis mount
+```
+
+For local development, install the checkout into a profile with
+`dsh plugin --profile <name> add <path-to-checkout>`.
+
+dsh loads plugins on Node `^22.19.0 || >=24.0.0`; development and tests run on bun.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# Bundle layer: applied when a profile lists this bundle in dsh.profile.bundles
+# (dsh plugin add does that from dsh.bundle). Do not also paste this row into
+# the profile's cordis.patch.yml: insert does not dedupe ids.
+- insert:
+    - id: cron
+      name: '@maci0/dsh-cron'

package/icon.svg

@@ -0,0 +1,4 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <circle cx="18" cy="18" r="10.5" stroke="#145AF3" stroke-width="2.4"/>
+  <path d="M18 12v6.5l4 2.5" stroke="#145AF3" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/index.js

@@ -0,0 +1,153 @@
+/**
+ * dsh-cron: `/cron <schedule> <prompt>` runs a prompt on a schedule in this
+ * session, the way `/loop` repeats one across turns.
+ *
+ * The schedule is parsed in code first: a five-field cron expression, or a
+ * phrase like "every 5 minutes", "weekdays at 9am", "tomorrow at 15:00"
+ * (lib/parse.js). Only when neither grammar reads it is the text handed to the
+ * agent, which sets the timer up itself with the harness's `schedule_create`
+ * tool. Timers belong to the harness schedule service, which keeps them across
+ * restarts and wakes a cold session when one is due.
+ *
+ *   /cron <schedule> <prompt>     create a schedule in this session
+ *   /cron list                    this session's schedules
+ *   /cron delete <n|id|all>       remove one by list number or id, or all
+ *   /cron help                    the forms
+ */
+import { createUserMessage } from '@deepseek-ai/dsh-llm/message'
+
+import { parseSchedule } from './lib/parse.js'
+
+export const name = 'cron'
+export const inject = ['commands']
+
+/** The optional bundle that mounts the harness schedule service. */
+const SCHEDULE_BUNDLE = '@deepseek-ai/dsh-experimental-schedule-bundle'
+/** Longest task title shown in lists; the service allows 120. */
+const MAX_TITLE = 80
+
+const USAGE = [
+  'Usage: /cron <schedule> <prompt>',
+  '  cron:      /cron */15 9-17 * * 1-5 check the deploy   (names like MON-FRI and @daily work too)',
+  '  interval:  /cron every 5 minutes check the queue       (/cron 5m … as /loop takes it)',
+  '  daily:     /cron every day at 9am standup notes',
+  '  weekly:    /cron every mon, wed and fri at 18:00 gym log',
+  '  once:      /cron in 10 minutes check the oven · /cron tomorrow at 9:30 review',
+  '  zone:      add an IANA zone after the time: /cron every day at 9 Europe/Berlin …',
+  'Anything else is handed to the agent to set up with schedule_create.',
+  '/cron list · /cron delete <n|id|all>',
+].join('\n')
+
+/** The host's IANA zone, used unless the schedule names one. */
+function hostTimeZone() {
+  return new Intl.DateTimeFormat().resolvedOptions().timeZone
+}
+
+/** A task name from the prompt's first line, cut to fit lists. */
+function titleOf(prompt) {
+  const line = prompt.split('\n')[0].trim()
+  return line.length <= MAX_TITLE ? line : `${line.slice(0, MAX_TITLE - 1).trimEnd()}…`
+}
+
+/** A stored UTC target in the host's zone, as YYYY-MM-DD HH:MM. */
+function localTime(iso, timeZone) {
+  const parts = Object.fromEntries(new Intl.DateTimeFormat('en-CA', {
+    timeZone, year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', hourCycle: 'h23',
+  }).formatToParts(new Date(iso)).map(part => [part.type, part.value]))
+  return `${parts.year}-${parts.month}-${parts.day} ${parts.hour}:${parts.minute}`
+}
+
+/** The message that asks the agent to read a schedule this plugin could not. */
+function agentRequest(text, timeZone) {
+  return createUserMessage({
+    content: [{
+      type: 'text',
+      text: [
+        '[cron] Set this up with the schedule_create tool. It matched neither a cron expression nor the',
+        `/cron phrase grammar, so read the timing and the task from it yourself. Use time zone ${timeZone}`,
+        'unless it names another. If it cannot be expressed as one schedule, say why instead of guessing.',
+        'Then reply with what you created: title, timing, next run.',
+        '',
+        `Request: ${text}`,
+      ].join('\n'),
+    }],
+    source: { kind: 'cron', form: 'relay' },
+  })
+}
+
+async function create(schedule, invocation, text) {
+  const timeZone = hostTimeZone()
+  const parsed = parseSchedule(text, { now: new Date(), timeZone })
+  if (parsed.kind === 'invalid') return { kind: 'error', text: parsed.text }
+  if (parsed.kind === 'unparsed') {
+    invocation.agent.followup(agentRequest(text, timeZone))
+    return { kind: 'success', text: 'No cron expression or built-in phrase matched; asked the agent to set it up with schedule_create.' }
+  }
+  const title = titleOf(parsed.prompt)
+  let record
+  try {
+    record = await schedule.create(invocation.agent.session.id, { prompt: parsed.prompt, title, ...parsed.selector }, invocation.signal)
+  } catch (error) {
+    // The service validates again (e.g. a cron date that never occurs) and
+    // names its rule; anything else propagates.
+    if (typeof error?.code !== 'string') throw error
+    return { kind: 'error', text: `The schedule service refused it (${error.code}): ${error.message}` }
+  }
+  return {
+    kind: 'success',
+    text: `Scheduled "${title}": ${parsed.description}; next run ${localTime(record.scheduledAt, timeZone)} (${timeZone}). /cron list shows it.`,
+  }
+}
+
+async function list(schedule, sessionId) {
+  const records = await schedule.list({ sessionId })
+  if (records.length === 0) return { kind: 'success', text: 'No schedules in this session.' }
+  const timeZone = hostTimeZone()
+  return {
+    kind: 'success',
+    text: records.map((record, index) => `${String(index + 1)}. ${record.title} · next ${localTime(record.scheduledAt, timeZone)} (${timeZone}) · ${record.id}`).join('\n'),
+  }
+}
+
+async function remove(schedule, sessionId, target) {
+  const records = await schedule.list({ sessionId })
+  const chosen = target === 'all'
+    ? records
+    : records.filter((record, index) => record.id === target || String(index + 1) === target)
+  if (chosen.length === 0) return { kind: 'error', text: `No schedule "${target}" in this session; /cron list shows them.` }
+  const deleted = []
+  for (const record of chosen) {
+    const result = await schedule.delete({ sessionId, id: record.id })
+    if (result.deleted) deleted.push(record)
+  }
+  if (target === 'all') return { kind: 'success', text: `Deleted ${String(deleted.length)} schedule(s).` }
+  if (deleted.length === 0) return { kind: 'error', text: `Schedule "${target}" was already gone.` }
+  return { kind: 'success', text: `Deleted "${deleted[0].title}".` }
+}
+
+async function cronHandler(invocation, ctx) {
+  const input = invocation.rawInput.trim()
+  const verb = input.toLowerCase()
+  if (verb === '' || verb === 'help') return { kind: 'success', text: USAGE }
+  // Read per call: the service comes from an optional bundle, and /cron should
+  // say what is missing rather than vanish when it is not mounted.
+  const schedule = ctx.get('schedule')
+  if (schedule == null) {
+    return { kind: 'error', text: `/cron needs the harness schedule service: enable ${SCHEDULE_BUNDLE} (Plugins page, Official group) or list it in the profile's dsh.profile.bundles.` }
+  }
+  const sessionId = invocation.agent.session.id
+  if (verb === 'list') return list(schedule, sessionId)
+  const deleteMatch = /^delete\s+(\S+)$/iu.exec(input)
+  if (deleteMatch !== null) return remove(schedule, sessionId, deleteMatch[1].toLowerCase() === 'all' ? 'all' : deleteMatch[1])
+  return create(schedule, invocation, input)
+}
+
+export function apply(ctx) {
+  ctx.effect(() => ctx.commands.register({
+    definitionId: 'dsh-cron:cron',
+    name: 'cron',
+    description: 'Run a prompt on a schedule: /cron <cron expression or phrase> <prompt>, /cron list, /cron delete <n|id|all>',
+    input: { hint: '<schedule> <prompt> | list | delete <n|id|all> | help' },
+    handler: (invocation) => cronHandler(invocation, ctx),
+  }))
+}

package/lib/parse.js

@@ -0,0 +1,375 @@
+/**
+ * Parse the schedule at the start of a `/cron` argument into the harness
+ * schedule service's selectors, deterministically: a five-field cron
+ * expression (names and @macros translated to the service's numeric dialect)
+ * or a phrase from a small English grammar. What follows the schedule is the
+ * prompt. Text neither grammar covers is `unparsed`, and the caller hands it to
+ * the model; text that is clearly a schedule but cannot be one is `invalid`
+ * and is reported, never guessed at.
+ *
+ * @module dsh-cron/parse
+ */
+
+/** The service's fixed-interval floor. */
+const MIN_EVERY_SECONDS = 60
+/** Time used when a recurring day phrase names no time ("every monday"). */
+const DEFAULT_TIME = '09:00:00'
+
+const UNIT_SECONDS = { s: 1, second: 1, sec: 1, m: 60, min: 60, minute: 60, h: 3600, hr: 3600, hour: 3600, d: 86400, day: 86400, w: 604800, week: 604800 }
+
+const MONTH_NAMES = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec']
+const DOW_NAMES = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat']
+const ISO_DAY_LABELS = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
+
+const CRON_FIELDS = [
+  { name: 'minute', min: 0, max: 59 },
+  { name: 'hour', min: 0, max: 23 },
+  { name: 'day-of-month', min: 1, max: 31 },
+  { name: 'month', min: 1, max: 12, names: MONTH_NAMES, base: 1 },
+  { name: 'day-of-week', min: 0, max: 7, names: DOW_NAMES, base: 0 },
+]
+
+const MACROS = {
+  '@yearly': '0 0 1 1 *',
+  '@annually': '0 0 1 1 *',
+  '@monthly': '0 0 1 * *',
+  '@weekly': '0 0 * * 0',
+  '@daily': '0 0 * * *',
+  '@midnight': '0 0 * * *',
+  '@hourly': '0 * * * *',
+}
+
+/** Words that, right after a recognized schedule, mean the schedule goes on in a way this grammar does not read. */
+const QUALIFIERS = /^(at|and|during|between|from|on|except|until|till|unless|starting|after|before|only|while|when|if|but)\b/u
+
+/** One cron atom: `*`, a number, or an L/W/#/? form the dialect rejects but cron users write. */
+const CRON_ATOM = /^(\*|\d+|L|\d+[LW]|\d+#\d+|\?)$/u
+const CRON_NAMES = new Set([...MONTH_NAMES, ...DOW_NAMES])
+
+/** Whether a token is shaped like a cron field (atoms or real month/day names), which decides whether input is meant as cron. */
+function isCronToken(token) {
+  return token.split(/[,\-/]/u).every(atom => CRON_ATOM.test(atom) || CRON_NAMES.has(atom.toLowerCase()))
+}
+
+/** Weekday words: ISO number (Mon 1 .. Sun 7). */
+const WEEKDAY_WORDS = [
+  [/^mon(day)?s?$/u, 1], [/^tue(s|sday)?s?$/u, 2], [/^wed(nesday)?s?$/u, 3], [/^thu(r|rs|rsday)?s?$/u, 4],
+  [/^fri(day)?s?$/u, 5], [/^sat(urday)?s?$/u, 6], [/^sun(day)?s?$/u, 7],
+]
+const WEEKDAY = '(?:mon(?:day)?s?|tue(?:s|sday)?s?|wed(?:nesday)?s?|thu(?:r|rs|rsday)?s?|fri(?:day)?s?|sat(?:urday)?s?|sun(?:day)?s?)'
+const TIME = '(?:noon|midnight|\\d{1,2}(?::\\d{2})?\\s*(?:am|pm)?)'
+const ZONE = '(?:\\s+(utc|[A-Za-z_]+(?:/[A-Za-z0-9_+-]+)+))?'
+// A range before a list: "monday to friday" must not stop at "monday".
+const DAY_SEPARATOR = '(?:,\\s*(?:and\\s+)?|and|&)'
+const DAYSPEC = `(?:day|weekdays?|weekends?|${WEEKDAY}\\s*(?:-|to|through|thru)\\s*${WEEKDAY}|${WEEKDAY}(?:\\s*${DAY_SEPARATOR}\\s*${WEEKDAY})*)`
+
+/** @returns {{ kind: 'invalid', text: string }} */
+const invalid = (text) => ({ kind: 'invalid', text })
+
+/**
+ * Parse one `/cron` argument.
+ * @param {string} input - the text after `/cron`.
+ * @param {{ now: Date, timeZone: string }} context - the clock and the host's IANA zone.
+ * @returns {{ kind: 'schedule', selector: object, prompt: string, description: string }
+ *   | { kind: 'invalid', text: string } | { kind: 'unparsed' }}
+ */
+export function parseSchedule(input, context) {
+  const text = input.trim()
+  const cron = parseCron(text, context)
+  if (cron !== undefined) return cron
+  return parseHuman(text, context)
+}
+
+// --- cron ---
+
+function parseCron(text, context) {
+  const tokens = text.split(/\s+/u)
+  const macro = tokens[0]?.toLowerCase()
+  if (macro?.startsWith('@')) {
+    if (!(macro in MACROS)) return invalid(`${tokens[0]} is not a schedule this plugin can set (use a five-field cron expression).`)
+    return finishCron(MACROS[macro], text.slice(tokens[0].length), context)
+  }
+  if (tokens.length < 5 || tokens.slice(0, 5).filter(isCronToken).length < 4) return undefined
+  // Four cron-shaped fields still identify a cron with a malformed fifth field.
+  const fields = []
+  for (const [index, token] of tokens.slice(0, 5).entries()) {
+    const field = normalizeCronField(token, CRON_FIELDS[index])
+    if (typeof field !== 'string') return field
+    fields.push(field)
+  }
+  return finishCron(fields.join(' '), text.slice(/^\S+(?:\s+\S+){4}/u.exec(text)[0].length), context)
+}
+
+function finishCron(expression, rest, context) {
+  const { zone, prompt } = takeZone(rest, context)
+  if (zone.kind === 'invalid') return zone
+  return schedule({ cron: { expression, time_zone: zone.value } }, prompt, `cron ${expression} (${zone.value})`)
+}
+
+/** Translate names to numbers and check one field against the service's dialect. */
+function normalizeCronField(token, field) {
+  const fail = () => invalid(`cron ${field.name} field "${token}" is not valid: use *, a value, a-b, */n or a-b/n, or a comma list of those, within ${field.min}-${field.max}.`)
+  const value = (raw) => {
+    const lower = raw.toLowerCase()
+    if (field.names !== undefined && field.names.includes(lower)) return field.names.indexOf(lower) + field.base
+    if (!/^\d+$/u.test(raw)) return undefined
+    const number = Number(raw)
+    return number >= field.min && number <= field.max ? number : undefined
+  }
+  const parts = []
+  for (const part of token.split(',')) {
+    const match = /^(\*|[a-z0-9]+(?:-[a-z0-9]+)?)(?:\/(\d+))?$/iu.exec(part)
+    if (match === null) return fail()
+    const [, range, step] = match
+    if (step !== undefined && (!Number.isSafeInteger(Number(step)) || Number(step) < 1 || (range !== '*' && !range.includes('-')))) return fail()
+    let out = range
+    if (range !== '*') {
+      const [from, to] = range.split('-').map(value)
+      if (from === undefined || (range.includes('-') && (to === undefined || to < from))) return fail()
+      out = range.includes('-') ? `${from}-${to}` : `${from}`
+    }
+    parts.push(step === undefined ? out : `${out}/${step}`)
+  }
+  return parts.join(',')
+}
+
+// --- human grammar ---
+
+function parseHuman(text, context) {
+  const lower = text.toLowerCase()
+  for (const rule of RULES) {
+    const match = rule.pattern.exec(lower)
+    if (match === null) continue
+    const rest = text.slice(match[0].length)
+    if (QUALIFIERS.test(rest.trim().toLowerCase())) return { kind: 'unparsed' }
+    // The grammar matched lowercased text; read the zone back in the user's casing.
+    const lowered = match.groups?.zone
+    const at = lowered === undefined ? -1 : lower.lastIndexOf(lowered, match[0].length - lowered.length)
+    const zone = resolveZone(at < 0 ? undefined : text.slice(at, at + lowered.length), context)
+    if (zone.kind === 'invalid') return zone
+    const built = rule.build(match.groups ?? {}, { ...context, timeZone: zone.value })
+    if (built.kind === 'invalid') return built
+    return schedule(built.selector, rest, built.description)
+  }
+  return { kind: 'unparsed' }
+}
+
+/** Anchored at the start; the match's end is where the prompt begins. Order matters: specific before general. */
+const RULES = [
+  {
+    // in 10 minutes / in an hour
+    pattern: new RegExp(`^in\\s+(?<count>\\d+|an?)\\s+(?<unit>seconds?|secs?|minutes?|mins?|hours?|hrs?|days?|weeks?)\\b`, 'u'),
+    build: ({ count, unit }) => {
+      const seconds = amount(count) * unitSeconds(unit)
+      if (!Number.isSafeInteger(seconds) || seconds < 1) return invalid('a delay must be a positive safe integer number of seconds.')
+      return { selector: { after_seconds: seconds }, description: `once in ${plural(amount(count), unitName(unit))}` }
+    },
+  },
+  {
+    // hourly / hourly at :15 / every hour at :15 (a bare "every hour" is a fixed interval)
+    pattern: /^(?:hourly(?:\s+at\s+:?(?<minute>\d{1,2})(?:\s+past)?)?|(?:every|each)\s+hour\s+at\s+:?(?<atMinute>\d{1,2})(?:\s+past)?)(?=\s|$)/u,
+    build: ({ minute: hourlyMinute, atMinute }, context) => {
+      const minute = hourlyMinute ?? atMinute
+      const m = minute === undefined ? 0 : Number(minute)
+      if (m > 59) return invalid(`minute ${minute} is not a minute of the hour.`)
+      const expression = `${m} * * * *`
+      return { selector: { cron: { expression, time_zone: context.timeZone } }, description: `cron ${expression} (${context.timeZone})` }
+    },
+  },
+  {
+    // monthly on the 1st at 9am / every month on the 15th
+    pattern: new RegExp(`^(?:monthly|(?:every|each)\\s+month)(?:\\s+on\\s+the\\s+(?<dom>\\d{1,2})(?:st|nd|rd|th)?)?(?:\\s+at\\s+(?<time>${TIME}))?${ZONE.replace('(utc', '(?<zone>utc')}(?=\\s|$)`, 'u'),
+    build: ({ dom, time }, context) => {
+      const day = dom === undefined ? 1 : Number(dom)
+      if (day < 1 || day > 31) return invalid(`day ${dom} is not a day of the month.`)
+      const clock = parseTime(time ?? DEFAULT_TIME.slice(0, 5))
+      if (clock.kind === 'invalid') return clock
+      const expression = `${clock.minute} ${clock.hour} ${day} * *`
+      return { selector: { cron: { expression, time_zone: context.timeZone } }, description: `cron ${expression} (${context.timeZone})` }
+    },
+  },
+  {
+    // every day at 9 / every mon, wed and fri at 18:00 / weekdays at 8:45 / mondays at 9
+    pattern: new RegExp(`^(?:(?:every|each)\\s+(?<days>${DAYSPEC})|(?<bare>daily|${DAYSPEC.replace('(?:day|', '(?:')}))(?:\\s+at\\s+(?<time>${TIME}))?${ZONE.replace('(utc', '(?<zone>utc')}(?=\\s|$|[,:;])`, 'u'),
+    build: ({ days, bare, time }, context) => recurringDays(days ?? bare, time, context),
+  },
+  {
+    // at 7:30pm every day / at 9 on weekdays
+    pattern: new RegExp(`^at\\s+(?<time>${TIME})\\s+(?:every\\s+(?<days>${DAYSPEC})|on\\s+(?<on>${DAYSPEC})|(?<daily>daily))${ZONE.replace('(utc', '(?<zone>utc')}(?=\\s|$|[,:;])`, 'u'),
+    build: ({ time, days, on, daily }, context) => recurringDays(days ?? on ?? daily, time, context),
+  },
+  {
+    // every 5 minutes / every minute / each hour (fixed rate)
+    pattern: /^(?:every|each)\s+(?:(?<count>\d+)\s+)?(?<unit>seconds?|secs?|minutes?|mins?|hours?|hrs?|days?|weeks?)\b/u,
+    build: ({ count, unit }) => every(count === undefined ? 1 : Number(count), unit),
+  },
+  {
+    // 5m / 2h / 1d, as /loop takes them
+    pattern: /^(?<count>\d+)(?<unit>[smhdw])(?=\s|$)/u,
+    build: ({ count, unit }) => every(Number(count), unit),
+  },
+  {
+    // on 2026-12-24 at 18:00 / 2026-12-31 23:59 / tomorrow at 9 / today at 18:00 / at 3pm
+    pattern: new RegExp(`^(?:(?:on\\s+)?(?<date>\\d{4}-\\d{2}-\\d{2})(?:\\s+(?:at\\s+)?(?<dateTime>${TIME}))?|(?<day>today|tonight|tomorrow)(?:\\s+at\\s+(?<dayTime>${TIME}))|at\\s+(?<atTime>${TIME}))${ZONE.replace('(utc', '(?<zone>utc')}(?=\\s|$|[,:;])`, 'u'),
+    build: (groups, context) => oneShot(groups, context),
+  },
+]
+
+function every(count, unit) {
+  const seconds = count * unitSeconds(unit)
+  if (!Number.isSafeInteger(seconds)) return invalid('an interval must be a safe integer number of seconds.')
+  if (seconds < MIN_EVERY_SECONDS) return invalid(`a repeating schedule must be at least one minute apart (got ${plural(count, unitName(unit))}).`)
+  return { selector: { every_seconds: seconds }, description: `every ${count === 1 ? unitName(unit) : plural(count, unitName(unit))}` }
+}
+
+function recurringDays(spec, time, context) {
+  const clock = time === undefined ? { hour: 9, minute: 0 } : parseTime(time)
+  if (clock.kind === 'invalid') return clock
+  const hhmmss = time === undefined ? DEFAULT_TIME : `${pad(clock.hour)}:${pad(clock.minute)}:00`
+  const days = weekdaysOf(spec)
+  if (days.length === 7) {
+    return { selector: { daily: { time: hhmmss, time_zone: context.timeZone } }, description: `daily at ${hhmmss.slice(0, 5)} (${context.timeZone})` }
+  }
+  return {
+    selector: { weekly: { time: hhmmss, time_zone: context.timeZone, weekdays: days } },
+    description: `weekly on ${days.map(day => ISO_DAY_LABELS[day - 1]).join(', ')} at ${hhmmss.slice(0, 5)} (${context.timeZone})`,
+  }
+}
+
+/** ISO weekday numbers a day phrase covers, ascending. */
+function weekdaysOf(spec) {
+  const phrase = spec.trim()
+  if (phrase === 'day' || phrase === 'daily') return [1, 2, 3, 4, 5, 6, 7]
+  if (/^weekdays?$/u.test(phrase)) return [1, 2, 3, 4, 5]
+  if (/^weekends?$/u.test(phrase)) return [6, 7]
+  const range = new RegExp(`^(${WEEKDAY})\\s*(?:-|to|through|thru)\\s*(${WEEKDAY})$`, 'u').exec(phrase)
+  if (range !== null) {
+    const from = weekday(range[1])
+    const to = weekday(range[2])
+    const out = []
+    for (let day = from; ; day = day % 7 + 1) {
+      out.push(day)
+      if (day === to) break
+    }
+    return out.sort((a, b) => a - b)
+  }
+  return [...new Set(phrase.split(new RegExp(`\\s*${DAY_SEPARATOR}\\s*`, 'u')).map(weekday))].sort((a, b) => a - b)
+}
+
+function weekday(word) {
+  return WEEKDAY_WORDS.find(([pattern]) => pattern.test(word))[1]
+}
+
+function oneShot({ date, dateTime, day, dayTime, atTime }, context) {
+  const today = localParts(context.now, context.timeZone)
+  let target
+  let raw
+  if (date !== undefined) {
+    if (!validDate(date)) return invalid(`${date} is not a calendar date.`)
+    target = date
+    raw = dateTime ?? '00:00'
+  } else if (day !== undefined) {
+    target = day === 'tomorrow' ? addDays(today.date, 1) : today.date
+    raw = dayTime
+  } else {
+    raw = atTime
+  }
+  const clock = parseTime(raw)
+  if (clock.kind === 'invalid') return clock
+  const time = `${pad(clock.hour)}:${pad(clock.minute)}:00`
+  // A bare "at T" is the next T: today while it is still ahead, else tomorrow.
+  if (target === undefined) target = time > today.time ? today.date : addDays(today.date, 1)
+  if (target < today.date || (target === today.date && time <= today.time)) {
+    return invalid(`${target} ${time.slice(0, 5)} (${context.timeZone}) has already passed.`)
+  }
+  return {
+    selector: { at: { date: target, time, time_zone: context.timeZone } },
+    description: `once on ${target} at ${time.slice(0, 5)} (${context.timeZone})`,
+  }
+}
+
+// --- shared pieces ---
+
+function schedule(selector, rest, description) {
+  const prompt = rest.trim().replace(/^[,:;-]+\s*/u, '').replace(/^(to|then)\s+/iu, '').trim()
+  if (prompt === '') return invalid(`${description}: what to run? Put the prompt after the schedule, e.g. /cron every day at 9 check the deploy.`)
+  return { kind: 'schedule', selector, prompt, description }
+}
+
+/** A trailing zone token on cron input; the host zone otherwise. */
+function takeZone(rest, context) {
+  const prompt = rest.trimStart()
+  const first = /^\S+/u.exec(prompt)?.[0]
+  if (first !== undefined && (/^utc$/iu.test(first) || /^[A-Za-z_]+(\/[A-Za-z0-9_+-]+)+$/u.test(first))) {
+    return { zone: resolveZone(first, context), prompt: prompt.slice(first.length) }
+  }
+  return { zone: { kind: 'zone', value: context.timeZone }, prompt }
+}
+
+function resolveZone(raw, context) {
+  if (raw === undefined) return { kind: 'zone', value: context.timeZone }
+  if (/^utc$/iu.test(raw)) return { kind: 'zone', value: 'UTC' }
+  // The grammar lowercased the text; Intl canonicalizes the zone's case.
+  try {
+    return { kind: 'zone', value: new Intl.DateTimeFormat('en-US', { timeZone: raw }).resolvedOptions().timeZone }
+  } catch {
+    return invalid(`${raw} is not a time zone (use an IANA name like Europe/Berlin, or UTC).`)
+  }
+}
+
+/** 9, 9:30, 9am, 9:30pm, 21:00, noon, midnight. */
+function parseTime(raw) {
+  const text = raw.trim().toLowerCase()
+  if (text === 'noon') return { hour: 12, minute: 0 }
+  if (text === 'midnight') return { hour: 0, minute: 0 }
+  const match = /^(\d{1,2})(?::(\d{2}))?\s*(am|pm)?$/u.exec(text)
+  const fail = invalid(`${raw} is not a time of day.`)
+  if (match === null) return fail
+  let hour = Number(match[1])
+  const minute = match[2] === undefined ? 0 : Number(match[2])
+  if (minute > 59) return fail
+  if (match[3] !== undefined) {
+    if (hour < 1 || hour > 12) return fail
+    hour = hour % 12 + (match[3] === 'pm' ? 12 : 0)
+  } else if (hour > 23) return fail
+  return { hour, minute }
+}
+
+/** The local calendar date and HH:MM:SS of `now` in `timeZone`. */
+function localParts(now, timeZone) {
+  const parts = Object.fromEntries(new Intl.DateTimeFormat('en-CA', {
+    timeZone, year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit', hourCycle: 'h23',
+  }).formatToParts(now).map(part => [part.type, part.value]))
+  return { date: `${parts.year}-${parts.month}-${parts.day}`, time: `${parts.hour}:${parts.minute}:${parts.second}` }
+}
+
+function addDays(date, days) {
+  const [y, m, d] = date.split('-').map(Number)
+  return new Date(Date.UTC(y, m - 1, d + days)).toISOString().slice(0, 10)
+}
+
+function validDate(date) {
+  const [y, m, d] = date.split('-').map(Number)
+  return new Date(Date.UTC(y, m - 1, d)).toISOString().slice(0, 10) === date
+}
+
+function amount(count) {
+  return /^an?$/u.test(count) ? 1 : Number(count)
+}
+
+function unitSeconds(unit) {
+  return UNIT_SECONDS[unit.replace(/s$/u, '')] ?? UNIT_SECONDS[unit]
+}
+
+function unitName(unit) {
+  const seconds = unitSeconds(unit)
+  return { 1: 'second', 60: 'minute', 3600: 'hour', 86400: 'day', 604800: 'week' }[seconds]
+}
+
+function plural(count, word) {
+  return `${count} ${word}${count === 1 ? '' : 's'}`
+}
+
+function pad(n) {
+  return String(n).padStart(2, '0')
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Cron",
+    "description": "Run a prompt on a schedule with /cron: cron expressions or plain English like \"every weekday at 9am\", parsed in code."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "定时任务",
+    "description": "用 /cron 按计划运行提示：支持 cron 表达式或“每个工作日上午 9 点”这类英文描述，在代码中解析。"
+  }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@maci0/dsh-cron",
+  "version": "0.1.1",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "index.js",
+  "description": "/cron for DeepSeek Harness: run a prompt on a cron or plain-English schedule, parsed in code, with the model as the last resort.",
+  "license": "MIT",
+  "exports": {
+    ".": "./index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./locale/*.json": "./locale/*.json",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "compatibility": {
+      "dsh": ">=0.2.0-rc.2 <0.3.0"
+    }
+  },
+  "files": [
+    "icon.svg",
+    "locale/*.json",
+    "index.js",
+    "lib/parse.js",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:node": "node --test tests/*.test.*"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/maci0/dsh-cron.git"
+  },
+  "icon": "./icon.svg",
+  "dependencies": {
+    "@deepseek-ai/dsh-llm": "0.2.1-alpha.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.5-alpha.1"
+  }
+}