@goodandready/dsh-cron 0.1.17 → 0.1.19

package/README.md

@@ -192,3 +192,8 @@ MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
 - **Automatic Kanban Card Creation**: Automatically creates task/bug cards in `dsh-kanban` on task failure (`on_failure`) or every run (`always`).
 - **Token & Execution Cost Meter**: Tracks token consumption (input, output, cache tokens) for LLM executions and estimates USD expenses using current model pricing.
 - **Aggregated Analytics Bar**: Live dashboard displaying active jobs count, total executions, total token consumption, and aggregate estimated dollar spend.
+
+### One-Shot Delayed Tasks (v0.1.18)
+- **Precise Timing & Relative Delays**: Supports one-time tasks triggered at exact ISO 8601 timestamps (`at: 2026-09-05T12:00:00Z`) or human-friendly relative delays (`in 20m`, `in 2h`, `через 15 минут`).
+- **Auto-Completion Lifecycle**: One-shot jobs transition automatically to `completed` status after their single run, preventing unexpected repeats.
+- **Dedicated Filter**: View historical and pending one-shot executions under the «Completed» (`completed`) tab.

package/docs/README.ru.md

@@ -175,3 +175,8 @@ MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
 - **Автосоздание карточек в Kanban**: Автоматическое заведение задач в бэклог `dsh-kanban` при обнаружении сбоев/ошибок (`on_failure`) или при каждом завершении (`always`).
 - **Трекинг токенов и расчет расходов (USD)**: Подсчет потребления токенов (input, output, cacheRead) для каждой задачи и запуск с расчетом примерной стоимости в долларах США.
 - **Сводная панель статистики**: Отображение общего числа запусков, активных задач, суммарного расхода токенов и совокупных затрат прямо в заголовке планировщика.
+
+### Разовые отложенные задачи (v0.1.18)
+- **Точное время и относительные задержки**: Поддержка однократных задач, запускаемых в конкретный момент времени по стандарту ISO 8601 (`at: 2026-09-05T12:00:00Z`) или через заданный интервал (`in 20m`, `in 2h`, `через 15 минут`).
+- **Автоматический перевод в «Завершенные»**: После единичного выполнения задача автоматически переходит в статус `completed`, исключая повторные старты.
+- **Индикация в интерфейсе**: Разовые задачи помечаются специальным бейджем «Разовая» и фильтруются по вкладке «Завершенные».

package/lib/client.js

@@ -145,6 +145,7 @@ const React = window.React || require('react');
       .dsh-cron-stat-card { background: rgba(255, 255, 255, 0.02); border: 1px solid #222; border-radius: 8px; padding: 10px 14px; }
       .dsh-cron-stat-val { font-size: 16px; font-weight: 600; color: #fff; }
       .dsh-cron-stat-lbl { font-size: 11.5px; color: #777; margin-top: 2px; }
+            .dsh-cron-oneshot-tag { font-size: 11px; padding: 2px 6px; border-radius: 4px; background: rgba(168, 85, 247, 0.15); color: #c084fc; font-weight: 500; }
       .dsh-cron-cost-tag { font-size: 11px; padding: 2px 6px; border-radius: 4px; background: rgba(16, 185, 129, 0.12); color: #10b981; font-weight: 500; }
       .dsh-cron-tokens-tag { font-size: 11px; padding: 2px 6px; border-radius: 4px; background: rgba(59, 130, 246, 0.12); color: #60a5fa; }
       .dsh-cron-checkbox-row { display: flex; align-items: center; gap: 8px; font-size: 13px; color: #ccc; cursor: pointer; user-select: none; }
@@ -654,6 +655,7 @@ const React = window.React || require('react');
                           }
                         }, task.type === 'script' ? 'Shell' : 'LLM'),
                         task.model ? React.createElement('span', { className: 'dsh-cron-task-model-tag' }, task.model.split('/').pop()) : null,
+                        task.oneShot ? React.createElement('span', { className: 'dsh-cron-oneshot-tag' }, 'Разовая') : null,
                         task.totalCostUsd > 0 ? React.createElement('span', { className: 'dsh-cron-cost-tag' }, '$' + task.totalCostUsd.toFixed(4)) : null,
                         task.totalTokens > 0 ? React.createElement('span', { className: 'dsh-cron-tokens-tag' }, (task.totalTokens > 1000 ? Math.round(task.totalTokens / 1000) + 'k' : task.totalTokens) + ' tok') : null
                       ),
@@ -815,7 +817,7 @@ const React = window.React || require('react');
                   React.createElement('input', {
                     required: true,
                     value: formSchedule,
-                    placeholder: '0 */6 * * * или every 2h',
+                    placeholder: '0 */6 * * * или every 2h или in 30m или at: 2026-09-05T15:00:00Z',
                     onChange: (e) => setFormSchedule(e.target.value)
                   })
                 )
@@ -1199,8 +1201,12 @@ const React = window.React || require('react');
         container.setAttribute(VIEW_ATTR, '');
         container.setAttribute('data-dsh-plugin', 'cron');
         column.appendChild(container);
-        root = ReactDOM.createRoot(container);
-        root.render(React.createElement(CronScreen, { ctx, toggle, onClose: () => toggle.set(false) }));
+        if (ReactDOM && typeof ReactDOM.createRoot === 'function') {
+          root = ReactDOM.createRoot(container);
+          root.render(React.createElement(CronScreen, { ctx, toggle, onClose: () => toggle.set(false) }));
+        } else if (ReactDOM && typeof ReactDOM.render === 'function') {
+          ReactDOM.render(React.createElement(CronScreen, { ctx, toggle, onClose: () => toggle.set(false) }), container);
+        }
       };
 
       const applyActive = () => {

package/lib/index.js

@@ -101,7 +101,7 @@ export function apply(ctx, config) {
           const task = store.set({
             id: body.id,
             title: body.title,
-            schedule: parsed.cronPattern,
+            schedule: parsed.cronPattern || body.schedule,
             scheduleText: body.scheduleText || parsed.humanText,
             prompt: body.prompt,
             type: body.type || 'prompt',
@@ -114,6 +114,7 @@ export function apply(ctx, config) {
             timeoutSeconds: body.timeoutSeconds !== undefined ? Number(body.timeoutSeconds) : 1800,
             overlapPolicy: body.overlapPolicy || 'skip',
             kanbanMode: body.kanbanMode || 'none',
+            oneShot: Boolean(parsed.isOneShot || body.oneShot),
           });
           scheduler.scheduleTask(task);
           sendJson(res, 200, { ok: true, task });
@@ -316,30 +317,38 @@ export function apply(ctx, config) {
   // 2. Tools
   ctx.tools.register(defineTool({
     name: 'cron_create_task',
-    description: 'Создать новую запланированную задачу cron (запуск по расписанию)',
+    description: 'Создать новую запланированную задачу cron (запуск по расписанию или разово через "at: ISO" или "in 20m")',
     parameters: {
-      type: 'object',
-      properties: {
-        title: { type: 'string', description: 'Краткое название задачи' },
-        schedule: { type: 'string', description: 'Расписание: cron-выражение (например, "0 9 * * *") или интервал ("every 2h", "каждый день в 15:00")' },
-        prompt: { type: 'string', description: 'Промпт/инструкция для агента при запуске' },
-        type: { type: 'string', enum: ['prompt', 'script'], description: 'Тип задачи' },
-        delivery: { type: 'string', enum: ['current', 'isolated'], description: 'Режим запуска: current (в текущем чате) или isolated (изолированная сессия)' },
-        provider: { type: 'string', description: 'Провайдер модели (опционально)' },
-        model: { type: 'string', description: 'Модель (опционально)' },
-        notifyTelegram: { type: 'boolean', description: 'Отправлять отчет в Telegram' },
-        onlyOnFailure: { type: 'boolean', description: 'Отправлять отчет только при сбоях' },
-        timeoutSeconds: { type: 'number', description: 'Лимит времени выполнения в секундах' },
-        overlapPolicy: { type: 'string', enum: ['skip', 'queue', 'replace'], description: 'Политика перекрытия' },
-        kanbanMode: { type: 'string', enum: ['none', 'on_failure', 'always'], description: 'Создавать карточку в Kanban' },
+      title: { type: 'string', description: 'Краткое название задачи', required: true },
+      schedule: { type: 'string', description: 'Расписание: cron ("0 9 * * *"), интервал ("every 2h") или разово ("in 30m", "at: 2026-09-05T15:00:00Z")', required: true },
+      prompt: { type: 'string', description: 'Промпт/инструкция для агента при запуске', required: true },
+      type: { type: 'string', enum: ['prompt', 'script'], description: 'Тип задачи' },
+      delivery: { type: 'string', enum: ['current', 'isolated'], description: 'Режим запуска: current (в текущем чате) или isolated (изолированная сессия)' },
+      provider: { type: 'string', description: 'Провайдер модели (опционально)' },
+      model: { type: 'string', description: 'Модель (опционально)' },
+      notifyTelegram: { type: 'boolean', description: 'Отправлять отчет в Telegram' },
+      onlyOnFailure: { type: 'boolean', description: 'Отправлять отчет только при сбоях' },
+      timeoutSeconds: { type: 'number', description: 'Лимит времени выполнения в секундах' },
+      overlapPolicy: { type: 'string', enum: ['skip', 'queue', 'replace'], description: 'Политика перекрытия' },
+      kanbanMode: { type: 'string', enum: ['none', 'on_failure', 'always'], description: 'Создавать карточку в Kanban' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          success: { type: 'boolean' },
+          message: { type: 'string' },
+          task: { type: 'object', additionalProperties: true }
+        }
       },
-      required: ['title', 'schedule', 'prompt']
+      render: (_args, val) => [{ type: 'text', text: val.message || JSON.stringify(val) }]
     },
     execute: async (args) => {
       const parsed = parseScheduleExpression(args.schedule);
       const task = store.set({
         title: args.title,
-        schedule: parsed.cronPattern,
+        schedule: parsed.cronPattern || args.schedule,
         scheduleText: parsed.humanText,
         prompt: args.prompt,
         type: args.type || 'prompt',
@@ -352,6 +361,7 @@ export function apply(ctx, config) {
         timeoutSeconds: Number(args.timeoutSeconds) || 1800,
         overlapPolicy: args.overlapPolicy || 'skip',
         kanbanMode: args.kanbanMode || 'none',
+        oneShot: Boolean(parsed.isOneShot),
       });
       scheduler.scheduleTask(task);
       return {
@@ -366,10 +376,18 @@ export function apply(ctx, config) {
     name: 'cron_list_tasks',
     description: 'Получить список всех запланированных задач cron',
     parameters: {
-      type: 'object',
-      properties: {
-        status: { type: 'string', enum: ['all', 'active', 'paused'], description: 'Фильтр по статусу' }
-      }
+      status: { type: 'string', enum: ['all', 'active', 'paused', 'completed'], description: 'Фильтр по статусу' }
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          count: { type: 'number' },
+          tasks: { type: 'array', items: { type: 'object', additionalProperties: true } }
+        }
+      },
+      render: (_args, val) => [{ type: 'text', text: `Всего задач: ${val.count}` }]
     },
     execute: async (args) => {
       const tasks = store.list({ status: args.status || 'all' });
@@ -384,6 +402,7 @@ export function apply(ctx, config) {
           lastStatus: t.lastStatus,
           totalTokens: t.totalTokens || 0,
           totalCostUsd: t.totalCostUsd || 0,
+          oneShot: Boolean(t.oneShot),
         }))
       };
     }
@@ -393,11 +412,18 @@ export function apply(ctx, config) {
     name: 'cron_pause_task',
     description: 'Приостановить выполнение задачи по её ID',
     parameters: {
-      type: 'object',
-      properties: {
-        id: { type: 'string', description: 'Идентификатор задачи' }
+      id: { type: 'string', description: 'Идентификатор задачи', required: true }
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          success: { type: 'boolean' },
+          message: { type: 'string' }
+        }
       },
-      required: ['id']
+      render: (_args, val) => [{ type: 'text', text: val.message }]
     },
     execute: async (args) => {
       const task = scheduler.pauseTask(args.id);
@@ -410,11 +436,18 @@ export function apply(ctx, config) {
     name: 'cron_resume_task',
     description: 'Возобновить выполнение приостановленной задачи',
     parameters: {
-      type: 'object',
-      properties: {
-        id: { type: 'string', description: 'Идентификатор задачи' }
+      id: { type: 'string', description: 'Идентификатор задачи', required: true }
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          success: { type: 'boolean' },
+          message: { type: 'string' }
+        }
       },
-      required: ['id']
+      render: (_args, val) => [{ type: 'text', text: val.message }]
     },
     execute: async (args) => {
       const task = scheduler.resumeTask(args.id);
@@ -427,11 +460,18 @@ export function apply(ctx, config) {
     name: 'cron_delete_task',
     description: 'Удалить задачу по её ID',
     parameters: {
-      type: 'object',
-      properties: {
-        id: { type: 'string', description: 'Идентификатор задачи' }
+      id: { type: 'string', description: 'Идентификатор задачи', required: true }
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          success: { type: 'boolean' },
+          message: { type: 'string' }
+        }
       },
-      required: ['id']
+      render: (_args, val) => [{ type: 'text', text: val.message }]
     },
     execute: async (args) => {
       scheduler.pauseTask(args.id);
@@ -444,11 +484,18 @@ export function apply(ctx, config) {
     name: 'cron_run_task',
     description: 'Запустить задачу немедленно вне очереди',
     parameters: {
-      type: 'object',
-      properties: {
-        id: { type: 'string', description: 'Идентификатор задачи' }
+      id: { type: 'string', description: 'Идентификатор задачи', required: true }
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          success: { type: 'boolean' },
+          message: { type: 'string' }
+        }
       },
-      required: ['id']
+      render: (_args, val) => [{ type: 'text', text: val.message }]
     },
     execute: async (args) => {
       const task = store.get(args.id);

package/lib/scheduler.js

@@ -28,6 +28,49 @@ export function parseScheduleExpression(input) {
   const str = String(input || '').trim();
   if (!str) throw new Error('Строка расписания не должна быть пустой');
 
+  // 1. One-shot ISO 8601 timestamp or explicit "at: <ISO/datetime>"
+  const atPrefixMatch = str.match(/^(?:at:\s*|at\s+)(.+)$/i);
+  const candidateIso = atPrefixMatch ? atPrefixMatch[1].trim() : str;
+  const parsedDate = new Date(candidateIso);
+  if (!isNaN(parsedDate.getTime()) && (candidateIso.includes('-') || candidateIso.includes('T') || atPrefixMatch)) {
+    const targetMs = parsedDate.getTime();
+    return {
+      cronPattern: null,
+      isOneShot: true,
+      targetTimestamp: targetMs,
+      humanText: `Разово: ${parsedDate.toLocaleString('ru-RU')}`,
+      nextRun: targetMs
+    };
+  }
+
+  // 2. Relative one-shot: "in 20m", "in 2h", "in 30s", "in 1d", "через 15 минут"
+  const inRelMatch = str.match(/^(?:in\s+|через\s+)(\d+)\s*(s|sec|seconds?|m|min|minutes?|h|hr|hours?|d|days?|мин|минут|часа?|часов)?$/i);
+  if (inRelMatch) {
+    const num = parseInt(inRelMatch[1], 10);
+    const unit = (inRelMatch[2] || 'm').toLowerCase();
+    let delayMs = num * 60 * 1000;
+    let unitText = `${num} мин`;
+    if (unit.startsWith('s')) {
+      delayMs = num * 1000;
+      unitText = `${num} сек`;
+    } else if (unit.startsWith('h') || unit.startsWith('час')) {
+      delayMs = num * 3600 * 1000;
+      unitText = `${num} ч`;
+    } else if (unit.startsWith('d')) {
+      delayMs = num * 86400 * 1000;
+      unitText = `${num} дн`;
+    }
+    const targetMs = Date.now() + delayMs;
+    return {
+      cronPattern: null,
+      isOneShot: true,
+      targetTimestamp: targetMs,
+      humanText: `Разово через ${unitText} (${new Date(targetMs).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })})`,
+      nextRun: targetMs
+    };
+  }
+
+  // 3. Repeating Interval: "every 5m", "every 2h", "every 1d"
   const intervalMatch = str.match(/^every\s+(\d+)\s*(m|min|minute|minutes|h|hr|hour|hours|d|day|days)?$/i);
   if (intervalMatch) {
     const num = parseInt(intervalMatch[1], 10);
@@ -55,6 +98,7 @@ export function parseScheduleExpression(input) {
     }
   }
 
+  // 4. Friendly recurring aliases
   const lower = str.toLowerCase();
   if (lower === 'daily' || lower === 'каждый день') {
     return { cronPattern: '0 9 * * *', humanText: 'Каждый день в 09:00' };
@@ -66,6 +110,7 @@ export function parseScheduleExpression(input) {
     return { cronPattern: '0 * * * *', humanText: 'Каждый час' };
   }
 
+  // 5. Standard 5-field cron expression
   try {
     const testJob = new Cron(str);
     const next = testJob.nextRun();
@@ -83,7 +128,8 @@ export class TaskScheduler {
   constructor(store, executeFn) {
     this.store = store;
     this.executeFn = executeFn;
-    this.jobs = new Map();
+    this.jobs = new Map(); // taskId -> Cron instance
+    this.timers = new Map(); // taskId -> setTimeout handle (for one-shot tasks)
     this.running = new Map(); // taskId -> { controller, startedAt, queueCount }
   }
 
@@ -104,6 +150,13 @@ export class TaskScheduler {
     }
     this.jobs.clear();
 
+    for (const [id, timer] of this.timers.entries()) {
+      try {
+        clearTimeout(timer);
+      } catch {}
+    }
+    this.timers.clear();
+
     for (const [, run] of this.running.entries()) {
       try {
         run.controller.abort(new Error('Планировщик остановлен'));
@@ -113,15 +166,40 @@ export class TaskScheduler {
   }
 
   scheduleTask(task) {
+    // Clear any existing job or timer for this task
     if (this.jobs.has(task.id)) {
       this.jobs.get(task.id).stop();
       this.jobs.delete(task.id);
     }
+    if (this.timers.has(task.id)) {
+      clearTimeout(this.timers.get(task.id));
+      this.timers.delete(task.id);
+    }
 
     if (task.status !== 'active') return;
 
     try {
       const parsed = parseScheduleExpression(task.schedule);
+
+      // Handle One-shot task
+      if (parsed.isOneShot) {
+        task.oneShot = true;
+        const now = Date.now();
+        const delay = Math.max(0, parsed.targetTimestamp - now);
+        task.nextRunAt = parsed.targetTimestamp;
+        this.store.set(task);
+
+        // If target is in the past, or when delay triggers:
+        const timer = setTimeout(async () => {
+          this.timers.delete(task.id);
+          await this.runTask(task.id);
+        }, delay);
+
+        this.timers.set(task.id, timer);
+        return;
+      }
+
+      // Handle Recurring Cron job
       const job = new Cron(parsed.cronPattern, { protect: true }, async () => {
         await this.runTask(task.id);
       });
@@ -271,11 +349,18 @@ export class TaskScheduler {
         console.error('[dsh-cron] kanban error:', kanbanErr.message);
       }
 
-      const job = this.jobs.get(taskId);
-      if (job) {
-        const next = job.nextRun();
-        task.nextRunAt = next ? next.getTime() : null;
+      // 3. Reschedule or mark completed for one-shot
+      if (task.oneShot) {
+        task.status = 'completed';
+        task.nextRunAt = null;
         this.store.set(task);
+      } else {
+        const job = this.jobs.get(taskId);
+        if (job) {
+          const next = job.nextRun();
+          task.nextRunAt = next ? next.getTime() : null;
+          this.store.set(task);
+        }
       }
 
       if (queuedCount > 0) {
@@ -295,6 +380,10 @@ export class TaskScheduler {
       this.jobs.get(taskId).stop();
       this.jobs.delete(taskId);
     }
+    if (this.timers.has(taskId)) {
+      clearTimeout(this.timers.get(taskId));
+      this.timers.delete(taskId);
+    }
     const running = this.running.get(taskId);
     if (running) {
       try {
@@ -320,6 +409,10 @@ export class TaskScheduler {
       this.jobs.get(taskId).stop();
       this.jobs.delete(taskId);
     }
+    if (this.timers.has(taskId)) {
+      clearTimeout(this.timers.get(taskId));
+      this.timers.delete(taskId);
+    }
     const running = this.running.get(taskId);
     if (running) {
       try {
@@ -337,6 +430,9 @@ export class TaskScheduler {
   getNextRun(schedule) {
     try {
       const parsed = parseScheduleExpression(schedule);
+      if (parsed.isOneShot) {
+        return parsed.targetTimestamp;
+      }
       const tempJob = new Cron(parsed.cronPattern);
       const next = tempJob.nextRun();
       return next ? next.getTime() : null;

package/lib/store.js

@@ -132,6 +132,7 @@ export class TaskStore {
       timeoutSeconds: task.timeoutSeconds !== undefined ? Number(task.timeoutSeconds) : (prev.timeoutSeconds || 1800),
       overlapPolicy: task.overlapPolicy !== undefined ? String(task.overlapPolicy) : (prev.overlapPolicy || 'skip'),
       kanbanMode: task.kanbanMode !== undefined ? String(task.kanbanMode) : (prev.kanbanMode || 'none'), // 'none' | 'on_failure' | 'always'
+      oneShot: task.oneShot !== undefined ? Boolean(task.oneShot) : Boolean(prev.oneShot),
       totalTokens: prev.totalTokens || 0,
       totalCostUsd: prev.totalCostUsd || 0,
       createdAt: prev.createdAt || task.createdAt || now,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-cron",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Scheduled cron tasks, background automation and agent execution for DeepSeek Harness.",
   "type": "module",
   "main": "lib/index.js",