@dcrays/scheduled-task 0.1.0

package/src/protocol.js

@@ -0,0 +1,94 @@
+import { assertMinimumCronInterval, CronExpressionError, validTimeZone } from "./cron.js";
+export const CRON_CREATE_TYPE = "dsh/cron.create";
+export const CRON_LIST_TYPE = "dsh/cron.list";
+export class CronAutomationInputError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "CronAutomationInputError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function exactKeys(value, keys) {
+    const actual = Object.keys(value).sort();
+    const expected = [...keys].sort();
+    return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+export function decodeCronCreateEnvelope(value) {
+    if (!isRecord(value) || value.type !== CRON_CREATE_TYPE) {
+        throw new CronAutomationInputError("invalid_envelope", `type must be ${CRON_CREATE_TYPE}`);
+    }
+    if (!exactKeys(value, ["type", "requestId", "name", "prompt", "cron", "timezone"])) {
+        throw new CronAutomationInputError("invalid_envelope", "cron envelope contains unknown or missing fields");
+    }
+    if (typeof value.requestId !== "string" || value.requestId.trim() !== value.requestId || value.requestId.length < 1 || value.requestId.length > 128) {
+        throw new CronAutomationInputError("invalid_request_id", "requestId must contain 1-128 characters without surrounding whitespace");
+    }
+    if (typeof value.name !== "string" || value.name.trim() !== value.name || value.name.length < 1 || value.name.length > 120) {
+        throw new CronAutomationInputError("invalid_name", "name must contain 1-120 characters without surrounding whitespace");
+    }
+    if (typeof value.prompt !== "string" || value.prompt.trim() !== value.prompt || value.prompt.length === 0) {
+        throw new CronAutomationInputError("invalid_prompt", "prompt must be a non-empty string without surrounding whitespace");
+    }
+    if (typeof value.cron !== "string") {
+        throw new CronAutomationInputError("invalid_cron", "cron must be a standard five-field expression");
+    }
+    try {
+        assertMinimumCronInterval(value.cron);
+    }
+    catch (error) {
+        if (error instanceof CronExpressionError) {
+            throw new CronAutomationInputError("invalid_cron", error.message);
+        }
+        throw error;
+    }
+    if (typeof value.timezone !== "string" || !validTimeZone(value.timezone)) {
+        throw new CronAutomationInputError("invalid_timezone", "timezone must be a valid IANA time zone");
+    }
+    return {
+        type: CRON_CREATE_TYPE,
+        requestId: value.requestId,
+        name: value.name,
+        prompt: value.prompt,
+        cron: value.cron,
+        timezone: value.timezone
+    };
+}
+/** Parse a cron control envelope carried as the sole text block of a direct user message. */
+export function parseCronAutomationMessage(message) {
+    if (message.source.kind !== "user" || message.content.length !== 1)
+        return undefined;
+    const block = message.content[0];
+    if (block?.type !== "text")
+        return undefined;
+    const text = block.text.trim();
+    if (!text.startsWith("{"))
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(value) || value.type !== CRON_CREATE_TYPE)
+        return undefined;
+    return decodeCronCreateEnvelope(value);
+}
+/** Recognize the stable prompt prefix emitted by the Mobook scheduled-task editor. */
+export function parseCronEditorRequest(message) {
+    if (message.source.kind !== "user" || message.content.length !== 1)
+        return undefined;
+    const block = message.content[0];
+    if (block?.type !== "text")
+        return undefined;
+    const text = block.text.trim();
+    const match = /^编辑定时任务[（(]\s*任务\s*ID\s+([^）)]+?)\s*[）)][：:]/u.exec(text);
+    const id = match?.[1]?.trim();
+    if (!id || id.length > 128 || !/^[A-Za-z0-9][A-Za-z0-9._:-]*$/u.test(id))
+        return undefined;
+    return { id, text };
+}

package/src/repository.d.ts

@@ -0,0 +1,85 @@
+export type OpenClawCronSchedule = {
+    kind: 'at';
+    at?: string;
+    atMs?: number;
+    [key: string]: unknown;
+} | {
+    kind: 'every';
+    everyMs: number;
+    anchorMs?: number;
+    [key: string]: unknown;
+} | {
+    kind: 'cron';
+    expr: string;
+    tz?: string;
+    [key: string]: unknown;
+};
+export interface OpenClawCronPayload {
+    kind: 'agentTurn';
+    message: string;
+    timeoutSeconds?: number;
+    [key: string]: unknown;
+}
+export interface OpenClawCronDelivery {
+    mode: 'announce' | 'none' | 'webhook';
+    channel?: string;
+    to?: string;
+    accountId?: string;
+    bestEffort?: boolean;
+    [key: string]: unknown;
+}
+/** OpenClaw-compatible job. Unknown fields survive migration unchanged. */
+export interface StoredCronAutomation {
+    id: string;
+    name: string;
+    description?: string;
+    enabled: boolean;
+    createdAtMs: number;
+    updatedAtMs: number;
+    schedule: OpenClawCronSchedule;
+    payload: OpenClawCronPayload;
+    agentId: string;
+    /** DSH-only execution binding; OpenClaw ignores this extension. */
+    dshSessionId?: string;
+    sessionKey?: string;
+    sessionTarget: 'isolated';
+    wakeMode: 'now';
+    deleteAfterRun?: boolean;
+    delivery: OpenClawCronDelivery;
+    state: {
+        nextRunAtMs?: number;
+        runningAtMs?: number;
+        lastRunAtMs?: number;
+        lastRunStatus?: 'ok' | 'error' | 'skipped';
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+export interface CronImportResult {
+    added: StoredCronAutomation[];
+    skippedIds: string[];
+}
+export interface CronAutomationRepositoryOptions {
+    readOnly?: boolean;
+}
+export declare function decodeJob(value: unknown): StoredCronAutomation;
+export declare class CronAutomationRepository {
+    readonly file: string;
+    private readonly database;
+    private readonly insertJobStatement;
+    private readonly readOnly;
+    private closed;
+    constructor(file: string, options?: CronAutomationRepositoryOptions);
+    load(): Promise<StoredCronAutomation[]>;
+    upsert(jobs: readonly StoredCronAutomation[]): Promise<void>;
+    delete(jobId: string): Promise<boolean>;
+    previewImport(source: string, incoming: readonly StoredCronAutomation[]): Promise<CronImportResult>;
+    import(source: string, incoming: readonly StoredCronAutomation[]): Promise<CronImportResult>;
+    close(): void;
+    private planImport;
+    private nextSortOrder;
+    private insertJob;
+    private assertOpen;
+    private assertWritable;
+    private writeTransaction;
+}

package/src/repository.js

@@ -0,0 +1,393 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { parseCronExpression, validTimeZone } from './cron.js';
+const STORE_KEY = 'dsh-cron-automation';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function finiteTimestamp(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+function decodeSchedule(value) {
+    if (!isRecord(value) || typeof value.kind !== 'string')
+        throw new Error('cron job has an invalid schedule');
+    if (value.kind === 'cron') {
+        const expr = typeof value.expr === 'string' ? value.expr : value.cron;
+        if (typeof expr !== 'string')
+            throw new Error('cron job has an invalid cron expression');
+        parseCronExpression(expr);
+        if (value.tz !== undefined && (typeof value.tz !== 'string' || !validTimeZone(value.tz))) {
+            throw new Error('cron job has an invalid time zone');
+        }
+        const { cron: _legacyCron, ...rest } = value;
+        return { ...rest, kind: 'cron', expr };
+    }
+    if (value.kind === 'every') {
+        if (!finiteTimestamp(value.everyMs) || value.everyMs < 60_000) {
+            throw new Error('cron job has an invalid interval');
+        }
+        if (value.anchorMs !== undefined && !finiteTimestamp(value.anchorMs)) {
+            throw new Error('cron job has an invalid interval anchor');
+        }
+        return value;
+    }
+    if (value.kind === 'at') {
+        const atMs = finiteTimestamp(value.atMs) ? value.atMs : typeof value.at === 'string' ? Date.parse(value.at) : Number.NaN;
+        if (!Number.isFinite(atMs))
+            throw new Error('cron job has an invalid one-shot time');
+        return value;
+    }
+    throw new Error('cron job uses an unsupported schedule kind');
+}
+export function decodeJob(value) {
+    if (!isRecord(value))
+        throw new Error('cron store contains a non-object job');
+    if (typeof value.id !== 'string' || !value.id || typeof value.name !== 'string' || !value.name) {
+        throw new Error('cron job has an invalid id or name');
+    }
+    if (!isRecord(value.payload) ||
+        value.payload.kind !== 'agentTurn' ||
+        typeof value.payload.message !== 'string' ||
+        !value.payload.message) {
+        throw new Error('cron job has an invalid agentTurn payload');
+    }
+    const agentId = typeof value.agentId === 'string' && value.agentId
+        ? value.agentId
+        : typeof value.sessionKey === 'string'
+            ? (value.sessionKey.split(':').filter(Boolean).at(-2) ?? 'main')
+            : 'main';
+    if (value.dshSessionId !== undefined && (typeof value.dshSessionId !== 'string' || !value.dshSessionId)) {
+        throw new Error('cron job has an invalid DSH session binding');
+    }
+    if (!finiteTimestamp(value.createdAtMs) || !finiteTimestamp(value.updatedAtMs)) {
+        throw new Error('cron job has invalid timestamps');
+    }
+    if (typeof value.enabled !== 'boolean')
+        throw new Error('cron job has an invalid enabled flag');
+    if (value.sessionTarget !== undefined && value.sessionTarget !== 'isolated') {
+        throw new Error('agentTurn cron jobs must use an isolated session');
+    }
+    if (value.delivery !== undefined &&
+        (!isRecord(value.delivery) || !['announce', 'none', 'webhook'].includes(String(value.delivery.mode)))) {
+        throw new Error('cron job has invalid delivery settings');
+    }
+    const state = isRecord(value.state) ? value.state : {};
+    for (const key of ['nextRunAtMs', 'runningAtMs', 'lastRunAtMs']) {
+        if (state[key] !== undefined && !finiteTimestamp(state[key]))
+            throw new Error(`cron job has invalid ${key}`);
+    }
+    return {
+        ...value,
+        id: value.id,
+        name: value.name,
+        enabled: value.enabled,
+        createdAtMs: value.createdAtMs,
+        updatedAtMs: value.updatedAtMs,
+        schedule: decodeSchedule(value.schedule),
+        payload: value.payload,
+        agentId,
+        sessionTarget: 'isolated',
+        wakeMode: 'now',
+        delivery: isRecord(value.delivery) ? value.delivery : { mode: 'none' },
+        state: state
+    };
+}
+function booleanInteger(value) {
+    return value === undefined ? null : value ? 1 : 0;
+}
+function atValue(schedule) {
+    if (schedule.kind !== 'at')
+        return null;
+    if (schedule.at)
+        return schedule.at;
+    return schedule.atMs === undefined ? null : new Date(schedule.atMs).toISOString();
+}
+function uniqueJobs(jobs) {
+    const unique = new Map();
+    for (const job of jobs) {
+        const decoded = decodeJob(job);
+        if (unique.has(decoded.id))
+            throw new Error(`cron store contains duplicate job id: ${decoded.id}`);
+        unique.set(decoded.id, decoded);
+    }
+    return [...unique.values()];
+}
+export class CronAutomationRepository {
+    file;
+    database;
+    insertJobStatement;
+    readOnly;
+    closed = false;
+    constructor(file, options = {}) {
+        this.file = file;
+        this.readOnly = options.readOnly === true;
+        if (!this.readOnly)
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+        this.database = new DatabaseSync(file, { readOnly: this.readOnly, timeout: 5_000 });
+        if (this.readOnly)
+            return;
+        this.database.exec('PRAGMA journal_mode = WAL');
+        this.database.exec('PRAGMA synchronous = FULL');
+        this.database.exec('PRAGMA busy_timeout = 5000');
+        this.database.exec(`
+      CREATE TABLE IF NOT EXISTS cron_jobs (
+        store_key TEXT NOT NULL,
+        job_id TEXT NOT NULL,
+        name TEXT NOT NULL,
+        description TEXT,
+        enabled INTEGER NOT NULL,
+        delete_after_run INTEGER,
+        created_at_ms INTEGER NOT NULL,
+        agent_id TEXT,
+        session_key TEXT,
+        schedule_kind TEXT NOT NULL,
+        schedule_expr TEXT,
+        schedule_tz TEXT,
+        every_ms INTEGER,
+        anchor_ms INTEGER,
+        at TEXT,
+        stagger_ms INTEGER,
+        session_target TEXT NOT NULL,
+        wake_mode TEXT NOT NULL,
+        payload_kind TEXT NOT NULL,
+        payload_message TEXT,
+        payload_model TEXT,
+        payload_fallbacks_json TEXT,
+        payload_thinking TEXT,
+        payload_timeout_seconds INTEGER,
+        payload_allow_unsafe_external_content INTEGER,
+        payload_external_content_source_json TEXT,
+        payload_light_context INTEGER,
+        payload_tools_allow_json TEXT,
+        delivery_mode TEXT,
+        delivery_channel TEXT,
+        delivery_to TEXT,
+        delivery_thread_id TEXT,
+        delivery_account_id TEXT,
+        delivery_best_effort INTEGER,
+        delivery_completion_mode TEXT,
+        delivery_completion_to TEXT,
+        failure_delivery_mode TEXT,
+        failure_delivery_channel TEXT,
+        failure_delivery_to TEXT,
+        failure_delivery_account_id TEXT,
+        failure_alert_disabled INTEGER,
+        failure_alert_after INTEGER,
+        failure_alert_channel TEXT,
+        failure_alert_to TEXT,
+        failure_alert_cooldown_ms INTEGER,
+        failure_alert_include_skipped INTEGER,
+        failure_alert_mode TEXT,
+        failure_alert_account_id TEXT,
+        next_run_at_ms INTEGER,
+        running_at_ms INTEGER,
+        last_run_at_ms INTEGER,
+        last_run_status TEXT,
+        last_error TEXT,
+        last_duration_ms INTEGER,
+        consecutive_errors INTEGER,
+        consecutive_skipped INTEGER,
+        schedule_error_count INTEGER,
+        last_delivery_status TEXT,
+        last_delivery_error TEXT,
+        last_delivered INTEGER,
+        last_failure_alert_at_ms INTEGER,
+        job_json TEXT NOT NULL,
+        state_json TEXT NOT NULL DEFAULT '{}',
+        runtime_updated_at_ms INTEGER,
+        schedule_identity TEXT,
+        sort_order INTEGER NOT NULL DEFAULT 0,
+        updated_at INTEGER NOT NULL,
+        PRIMARY KEY (store_key, job_id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_cron_jobs_store_updated
+        ON cron_jobs(store_key, sort_order ASC, updated_at DESC, job_id);
+      CREATE INDEX IF NOT EXISTS idx_cron_jobs_store_order
+        ON cron_jobs(store_key, sort_order ASC, updated_at ASC, job_id);
+      CREATE INDEX IF NOT EXISTS idx_cron_jobs_enabled_next_run
+        ON cron_jobs(store_key, enabled, next_run_at_ms, job_id)
+        WHERE next_run_at_ms IS NOT NULL;
+      CREATE INDEX IF NOT EXISTS idx_cron_jobs_agent_session
+        ON cron_jobs(agent_id, session_key, updated_at DESC, job_id)
+        WHERE agent_id IS NOT NULL OR session_key IS NOT NULL;
+
+      CREATE TABLE IF NOT EXISTS cron_imported_jobs (
+        source TEXT NOT NULL,
+        job_id TEXT NOT NULL,
+        imported_at INTEGER NOT NULL,
+        PRIMARY KEY (source, job_id)
+      );
+    `);
+        this.insertJobStatement = this.database.prepare(`
+      INSERT INTO cron_jobs (
+        store_key, job_id, name, description, enabled, delete_after_run,
+        created_at_ms, agent_id, session_key,
+        schedule_kind, schedule_expr, schedule_tz, every_ms, anchor_ms, at,
+        session_target, wake_mode,
+        payload_kind, payload_message, payload_timeout_seconds,
+        delivery_mode, delivery_channel, delivery_to, delivery_account_id, delivery_best_effort,
+        next_run_at_ms, running_at_ms, last_run_at_ms, last_run_status,
+        job_json, state_json, runtime_updated_at_ms, sort_order, updated_at
+      ) VALUES (
+        ?, ?, ?, ?, ?, ?,
+        ?, ?, ?,
+        ?, ?, ?, ?, ?, ?,
+        ?, ?,
+        ?, ?, ?,
+        ?, ?, ?, ?, ?,
+        ?, ?, ?, ?,
+        ?, ?, ?, ?, ?
+      )
+      ON CONFLICT(store_key, job_id) DO UPDATE SET
+        name = excluded.name,
+        description = excluded.description,
+        enabled = excluded.enabled,
+        delete_after_run = excluded.delete_after_run,
+        created_at_ms = excluded.created_at_ms,
+        agent_id = excluded.agent_id,
+        session_key = excluded.session_key,
+        schedule_kind = excluded.schedule_kind,
+        schedule_expr = excluded.schedule_expr,
+        schedule_tz = excluded.schedule_tz,
+        every_ms = excluded.every_ms,
+        anchor_ms = excluded.anchor_ms,
+        at = excluded.at,
+        session_target = excluded.session_target,
+        wake_mode = excluded.wake_mode,
+        payload_kind = excluded.payload_kind,
+        payload_message = excluded.payload_message,
+        payload_timeout_seconds = excluded.payload_timeout_seconds,
+        delivery_mode = excluded.delivery_mode,
+        delivery_channel = excluded.delivery_channel,
+        delivery_to = excluded.delivery_to,
+        delivery_account_id = excluded.delivery_account_id,
+        delivery_best_effort = excluded.delivery_best_effort,
+        next_run_at_ms = excluded.next_run_at_ms,
+        running_at_ms = excluded.running_at_ms,
+        last_run_at_ms = excluded.last_run_at_ms,
+        last_run_status = excluded.last_run_status,
+        job_json = excluded.job_json,
+        state_json = excluded.state_json,
+        runtime_updated_at_ms = excluded.runtime_updated_at_ms,
+        updated_at = excluded.updated_at
+    `);
+        try {
+            fs.chmodSync(file, 0o600);
+        }
+        catch {
+            // Best effort on filesystems without POSIX modes.
+        }
+    }
+    async load() {
+        this.assertOpen();
+        const rows = this.database
+            .prepare(`
+      SELECT job_json
+      FROM cron_jobs
+      WHERE store_key = ?
+      ORDER BY sort_order ASC, updated_at ASC, job_id ASC
+    `)
+            .all(STORE_KEY);
+        return rows.map((row) => decodeJob(JSON.parse(row.job_json)));
+    }
+    async upsert(jobs) {
+        this.assertWritable();
+        const decoded = uniqueJobs(jobs);
+        if (decoded.length === 0)
+            return;
+        this.writeTransaction(() => {
+            const nextOrder = this.nextSortOrder();
+            decoded.forEach((job, index) => this.insertJob(job, nextOrder + index));
+        });
+    }
+    async delete(jobId) {
+        this.assertWritable();
+        const result = this.database.prepare('DELETE FROM cron_jobs WHERE store_key = ? AND job_id = ?').run(STORE_KEY, jobId);
+        return Number(result.changes) > 0;
+    }
+    async previewImport(source, incoming) {
+        this.assertOpen();
+        return this.planImport(source, uniqueJobs(incoming));
+    }
+    async import(source, incoming) {
+        this.assertWritable();
+        if (!source.trim())
+            throw new Error('cron import source must be non-empty');
+        const decoded = uniqueJobs(incoming);
+        return this.writeTransaction(() => {
+            const result = this.planImport(source, decoded);
+            const nextOrder = this.nextSortOrder();
+            result.added.forEach((job, index) => this.insertJob(job, nextOrder + index));
+            const mark = this.database.prepare(`
+        INSERT OR IGNORE INTO cron_imported_jobs (source, job_id, imported_at)
+        VALUES (?, ?, ?)
+      `);
+            const importedAt = Date.now();
+            for (const job of decoded)
+                mark.run(source, job.id, importedAt);
+            return result;
+        });
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.database.close();
+    }
+    planImport(source, incoming) {
+        const existing = new Set(this.database.prepare('SELECT job_id FROM cron_jobs WHERE store_key = ?').all(STORE_KEY).map((row) => row.job_id));
+        const imported = new Set(this.database.prepare('SELECT job_id FROM cron_imported_jobs WHERE source = ?').all(source).map((row) => row.job_id));
+        const added = [];
+        const skippedIds = [];
+        for (const job of incoming) {
+            if (existing.has(job.id) || imported.has(job.id)) {
+                skippedIds.push(job.id);
+                continue;
+            }
+            existing.add(job.id);
+            added.push(job);
+        }
+        return { added, skippedIds };
+    }
+    nextSortOrder() {
+        const row = this.database
+            .prepare(`
+      SELECT COALESCE(MAX(sort_order), -1) + 1 AS next_order
+      FROM cron_jobs
+      WHERE store_key = ?
+    `)
+            .get(STORE_KEY);
+        return row.next_order;
+    }
+    insertJob(job, sortOrder) {
+        const statement = this.insertJobStatement;
+        if (!statement)
+            throw new Error('cron sqlite repository is read-only');
+        const schedule = job.schedule;
+        const state = job.state;
+        statement.run(STORE_KEY, job.id, job.name, job.description ?? null, booleanInteger(job.enabled), booleanInteger(job.deleteAfterRun), job.createdAtMs, job.agentId, job.sessionKey ?? null, schedule.kind, schedule.kind === 'cron' ? schedule.expr : null, schedule.kind === 'cron' ? (schedule.tz ?? null) : null, schedule.kind === 'every' ? schedule.everyMs : null, schedule.kind === 'every' ? (schedule.anchorMs ?? null) : null, atValue(schedule), job.sessionTarget, job.wakeMode, job.payload.kind, job.payload.message, typeof job.payload.timeoutSeconds === 'number' ? job.payload.timeoutSeconds : null, job.delivery.mode, job.delivery.channel ?? null, job.delivery.to ?? null, job.delivery.accountId ?? null, booleanInteger(job.delivery.bestEffort), state.nextRunAtMs ?? null, state.runningAtMs ?? null, state.lastRunAtMs ?? null, state.lastRunStatus ?? null, JSON.stringify(job), JSON.stringify(state), job.updatedAtMs, sortOrder, job.updatedAtMs);
+    }
+    assertOpen() {
+        if (this.closed)
+            throw new Error('cron sqlite repository is closed');
+    }
+    assertWritable() {
+        this.assertOpen();
+        if (this.readOnly)
+            throw new Error('cron sqlite repository is read-only');
+    }
+    writeTransaction(operation) {
+        this.database.exec('BEGIN IMMEDIATE');
+        try {
+            const result = operation();
+            this.database.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            this.database.exec('ROLLBACK');
+            throw error;
+        }
+    }
+}