@goodandready/dsh-cron 0.3.10 → 0.3.12

package/README.md

@@ -588,6 +588,8 @@ All endpoints are served by the DSH web server under `/dsh-cron/`. Endpoints are
 | `GET` / `POST` | `/dsh-cron/api/tasks` | External token-guarded surface: list / create-or-update (#54) |
 | `GET` / `DELETE` | `/dsh-cron/api/tasks/:id` | External token-guarded surface: read / delete (#54) |
 | `POST` | `/dsh-cron/api/tasks/:id/run` | External token-guarded surface: force a run (#54) |
+| `POST` | `/dsh-cron/webhook/:id` | Incoming webhook trigger: trigger task with HMAC SHA-256 / Bearer token authentication, debouncing and JSON payload prompt interpolation (#348) |
+| `POST` | `/dsh-cron/api/webhook/:id` | External token-guarded incoming webhook trigger (#348) |
 
 ---
 
@@ -619,6 +621,28 @@ Save LLM tokens and API quotas on watcher tasks by dynamically slowing down exec
 
 Connect to `GET /dsh-cron/tasks/:id/stream` using Server-Sent Events (SSE) to receive live stdout/stderr chunks and execution completion events with an automatic 500-line ring buffer.
 
+### 🪝 Incoming HTTP Webhook Triggers (#348)
+
+Execute tasks instantaneously on external events via incoming HTTP POST requests with enterprise-grade security and dynamic template interpolation:
+
+- **Authentication & Verification**: Supports HMAC SHA-256 signatures (`x-hub-signature-256` or `x-signature-sha256`) using task-level `webhookSecret`, bearer tokens passed via headers (`x-dsh-cron-webhook-token`, `x-webhook-token`, `Authorization: Bearer <token>`) against task `webhookToken` or master `apiToken`. Query parameter token authentication (`?token=`) is strictly rejected to prevent secret leakage in proxy logs and browser history (#358). Fail-closed security rejects unconfigured webhooks.
+- **Fail-Closed API Authentication**: All REST routes verify callers via DSH `ctx.connection.requestRejection(req)`, token verification, and loopback verification. Requests without socket/remoteAddress and without valid authentication are strictly rejected with 401/403, preventing remote unauthenticated state modification and RCE (#357).
+- **Deep JSON Payload Interpolation**: Dynamic prompt variables resolve incoming payload fields using dot notation (`{webhook.body.repository.full_name}`, `{webhook.headers.x_github_event}`, `{webhook.query.ref}`, `{webhook.body}`).
+- **Script Environment Injection**: Script and shell tasks automatically receive the raw request body and headers in `DSH_CRON_WEBHOOK_BODY` and `DSH_CRON_WEBHOOK_HEADERS`.
+- **Anti-Spam Debouncing**: Configurable per-task `webhookDebounceMs` (default 500ms) guarantees protection against webhook storms and burst duplicate executions.
+
+### 🗣️ Multi-Lingual Natural Language Scheduling (#349)
+
+Define schedules naturally in conversation, tool calls, and API inputs in English and Russian without wrestling with cron syntax:
+
+- **Intervals**: `"every 15 minutes"`, `"каждые 30 минут"`, `"every 2 hours"`, `"каждые 4 часа"`.
+- **Daily & Time-of-Day**: `"every day at 9:00"`, `"каждый день в 18:30"`, `"every morning at 8am"`, `"каждый вечер в 21:00"`, `"at midnight"`, `"в полночь"`, `"at noon"`, `"в полдень"`.
+- **Weekdays & Weekends**: `"every weekday at 9:00"`, `"по будням в 10:00"`, `"on weekends at noon"`, `"по выходным в 12:00"`.
+- **Days of the Week**: `"every Monday at 10am"`, `"каждую пятницу в 17:00"`, `"every Tuesday and Thursday at 14:00"`.
+- **Relative One-Shots**: `"in 15 minutes"`, `"через 2 часа"`, `"in 3 days at 10:00"`, `"через 30 минут"`.
+
+The dedicated parser (`lib/nl-schedule.js`) translates expressions into strict Croner expressions or deterministic one-shot execution timestamps seamlessly.
+
 ---
 
 ## 🧪 Testing & Preflight Verification

package/README.ru.md

@@ -569,6 +569,25 @@ bash deploy.sh verify [exact-version]
 | `GET` / `POST` | `/dsh-cron/api/tasks` | Внешняя поверхность под токеном: список / создание-обновление (#54) |
 | `GET` / `DELETE` | `/dsh-cron/api/tasks/:id` | Внешняя поверхность под токеном: чтение / удаление (#54) |
 | `POST` | `/dsh-cron/api/tasks/:id/run` | Внешняя поверхность под токеном: принудительный запуск (#54) |
+| `POST` | `/dsh-cron/webhook/:id` | Входящий HTTP Webhook: запуск задачи по событию с проверкой HMAC SHA-256 / токена, дебаунсом и подстановкой JSON payload в промпт (#348) |
+| `POST` | `/dsh-cron/api/webhook/:id` | Внешний эндпоинт входящего вебхука под токеном (#348) |
+
+---
+
+### 32. Входящие HTTP Webhook триггеры и естественно-языковой парсер расписаний (v0.3.11, #348, #349)
+
+- **Входящие Webhook триггеры (`/dsh-cron/webhook/:id`)**: Моментальный запуск задач по внешним событиям (GitHub, Gitea, CI/CD, сторонние сервисы).
+  - **Аутентификация и безопасность**: Поддержка HMAC SHA-256 подписи (`x-hub-signature-256`, `x-signature-sha256`) через `webhookSecret`, индивидуальных токенов задачи (`webhookToken`) исключительно через заголовки (`x-dsh-cron-webhook-token`, `x-webhook-token`, `Authorization: Bearer`), а также мастер-токена `apiToken`. Приём токенов из query-параметров (`?token=`) строго заблокирован для предотвращения утечки в логи прокси и историю браузера (#358).
+  - **Fail-closed защита API и RCE Guard (#357)**: Все маршруты плагина проверяются через DSH `ctx.connection.requestRejection(req)` для допуска браузерных сессий DSH, а также требуют валидный Bearer-токен или локальный loopback адрес. Запросы без валидной аутентификации отсекаются с 401/403 до парсинга тела, предотвращая несанкционированное создание задач и удалённое выполнение кода.
+  - **Глубокая интерполяция payload**: Шаблоны `{webhook.body.path.to.key}`, `{webhook.headers.key}`, `{webhook.query.param}` и `{webhook.body}` автоматически раскрываются в промпте задачи.
+  - **Проброс в окружение**: Скриптовым и shell-задачам передаются переменные `DSH_CRON_WEBHOOK_BODY` и `DSH_CRON_WEBHOOK_HEADERS`.
+  - **Дебаунс от штормов**: Настраиваемый `webhookDebounceMs` (по умолчанию 500 мс) защищает от дублирующих всплесков событий.
+- **Естественно-языковой парсер расписаний (`lib/nl-schedule.js`)**: Умное распознавание расписаний на русском и английском языках в чате, туле агента и API:
+  - Интервалы: `"каждые 15 минут"`, `"every 2 hours"`, `"каждые 4 часа"`.
+  - Время суток: `"каждый день в 9:00"`, `"every morning at 8am"`, `"в полночь"`, `"в полдень"`.
+  - Будни и выходные: `"по будням в 10:00"`, `"every weekday at 9:00"`, `"по выходным в 12:00"`, `"on weekends at noon"`.
+  - Дни недели: `"каждую пятницу в 17:00"`, `"every Monday at 10am"`, `"по вторникам и четвергам в 14:00"`.
+  - Относительные отложенные задачи: `"через 15 минут"`, `"in 2 hours"`, `"через 3 дня в 10:00"`.
 
 ---
 

package/README.zh.md

@@ -569,6 +569,19 @@ dsh-cron:
 | `GET` / `POST` | `/dsh-cron/api/tasks` | 令牌保护的外部接口：列表 / 创建或更新（#54） |
 | `GET` / `DELETE` | `/dsh-cron/api/tasks/:id` | 令牌保护的外部接口：读取 / 删除（#54） |
 | `POST` | `/dsh-cron/api/tasks/:id/run` | 令牌保护的外部接口：强制执行（#54） |
+| `POST` | `/dsh-cron/webhook/:id` | 入站 HTTP Webhook 触发器：支持 HMAC SHA-256 / 令牌鉴权、防抖与 JSON 负载提示词变量插值（#348） |
+| `POST` | `/dsh-cron/api/webhook/:id` | 令牌保护的入站 Webhook 外部接口（#348） |
+
+---
+
+### 32. 入站 HTTP Webhook 与接口鉴权加固 (v0.3.12, #348, #357, #358)
+
+- **入站 HTTP Webhook 触发器 (`/dsh-cron/webhook/:id`)**：外部事件（GitHub、Gitea、CI/CD 及第三方服务）实时触发任务执行。
+  - **安全鉴权**：支持基于任务级 `webhookSecret` 的 HMAC SHA-256 签名（`x-hub-signature-256`、`x-signature-sha256`）、任务级 `webhookToken`（仅限标头：`x-dsh-cron-webhook-token`、`x-webhook-token`、`Authorization: Bearer`）以及全局 `apiToken` 鉴权。严格禁止从 URL 查询参数（`?token=`）传递令牌以防止日志泄露（#358）。
+  - **深度 JSON 负载插值**：提示词中通过 `{webhook.body.path.to.key}`、`{webhook.headers.key}`、`{webhook.query.param}` 及 `{webhook.body}` 自动解构提取入站数据。
+  - **环境注入**：脚本与 shell 任务自动注入 `DSH_CRON_WEBHOOK_BODY` 和 `DSH_CRON_WEBHOOK_HEADERS` 环境变量。
+  - **防抖保护**：可配置 `webhookDebounceMs`（默认 500ms）有效防止 Webhook 事件风暴与瞬态重复触发。
+- **Fail-Closed 接口鉴权与 RCE 防御（#357）**：所有 REST 端点通过 DSH `ctx.connection.requestRejection(req)` 校验会话权限，并对无有效令牌及非本地回环地址的请求实行 Fail-closed 严格拦截（401/403），杜绝未授权远程任务创建与代码执行。
 
 ---
 

package/lib/api-helpers.js

@@ -4,13 +4,13 @@ import { sendJson, readBody, rejectCrossOrigin } from './http-utils.js';
 
 const NOT_ALLOWED = { ok: false, error: 'Method not allowed' };
 
-export function handleHeartbeatPing({ store, req, res, taskId, apiToken: explicitToken }) {
+export function handleHeartbeatPing({ store, req, res, taskId, apiToken: explicitToken, ctx }) {
   if (req.method !== 'POST') {
     sendJson(res, 405, NOT_ALLOWED);
     return;
   }
   const apiToken = explicitToken || store?.getSettings?.()?.apiToken;
-  if (rejectCrossOrigin(req, res, { apiToken })) return;
+  if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
 
   const task = store.get(taskId);
   if (!task) {
@@ -25,9 +25,9 @@ export function handleHeartbeatPing({ store, req, res, taskId, apiToken: explici
   sendJson(res, 200, result);
 }
 
-export async function handleSchedulePreview({ req, res, url, store, apiToken: explicitToken }) {
+export async function handleSchedulePreview({ req, res, url, store, apiToken: explicitToken, ctx }) {
   const apiToken = explicitToken || store?.getSettings?.()?.apiToken;
-  if (rejectCrossOrigin(req, res, { apiToken })) return;
+  if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
 
   let schedule = '';
   let timezone = '';
@@ -61,9 +61,9 @@ export async function handleSchedulePreview({ req, res, url, store, apiToken: ex
   }
 }
 
-export async function handleDryRunTask({ store, scheduler, req, res, id }) {
-  const apiToken = store?.getSettings?.()?.apiToken;
-  if (rejectCrossOrigin(req, res, { apiToken })) return;
+export async function handleDryRunTask({ store, scheduler, req, res, id, apiToken: explicitToken, ctx }) {
+  const apiToken = explicitToken || store?.getSettings?.()?.apiToken;
+  if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
   const task = store.get(id);
   if (!task) {
     sendJson(res, 404, { ok: false, error: 'Task not found' });
@@ -78,9 +78,9 @@ export async function handleDryRunTask({ store, scheduler, req, res, id }) {
   }
 }
 
-export async function handleScheduleTimeline({ req, res, url, store, scheduler, apiToken: explicitToken }) {
+export async function handleScheduleTimeline({ req, res, url, store, scheduler, apiToken: explicitToken, ctx }) {
   const apiToken = explicitToken || store?.getSettings?.()?.apiToken;
-  if (rejectCrossOrigin(req, res, { apiToken })) return;
+  if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
 
   if (req.method !== 'GET') {
     sendJson(res, 405, NOT_ALLOWED);

package/lib/api-task-webhook.js

@@ -0,0 +1,247 @@
+/**
+ * lib/api-task-webhook.js — Incoming HTTP Webhook Triggers (#348).
+ *
+ * Implements POST /dsh-cron/webhook/:taskId and POST /dsh-cron/api/webhook/:taskId.
+ * Authenticates via HMAC SHA-256 signature (GitHub/Stripe style), per-task token,
+ * or master apiToken, applies debouncing, parses JSON/text payload, and triggers
+ * the task with variable interpolation.
+ */
+
+import crypto from 'node:crypto';
+import { logger } from './logger.js';
+import { sendJson } from './http-utils.js';
+
+const MAX_WEBHOOK_BYTES = 512 * 1024; // 512 KiB limit
+const NOT_ALLOWED = { ok: false, error: 'Method not allowed' };
+const lastWebhookRuns = new Map();
+
+/**
+ * Constant-time string/buffer comparison.
+ */
+export function safeCompare(a, b) {
+  if (!a || !b) return false;
+  const bufA = Buffer.from(String(a), 'utf8');
+  const bufB = Buffer.from(String(b), 'utf8');
+  if (bufA.length !== bufB.length) return false;
+  return crypto.timingSafeEqual(bufA, bufB);
+}
+
+/**
+ * Verify HMAC SHA-256 signature from headers.
+ * Supports x-hub-signature-256 (sha256=...), x-signature-256, or x-dsh-cron-signature.
+ */
+export function verifyHmacSignature(rawBuffer, secret, signatureHeader) {
+  if (!secret || !signatureHeader) return false;
+  const expectedHex = crypto.createHmac('sha256', secret).update(rawBuffer).digest('hex');
+  const provided = String(signatureHeader).replace(/^sha256=/i, '').trim();
+  return safeCompare(expectedHex, provided);
+}
+
+/**
+ * Verify token from header or Bearer auth.
+ * Query parameter authentication is strictly rejected to prevent token leakage in proxy logs and browser history (#358).
+ */
+export function verifyToken(expectedToken, req, url) {
+  if (!expectedToken) return false;
+  const headers = req?.headers || {};
+  const headerToken = headers['x-dsh-cron-webhook-token'] || headers['x-webhook-token'];
+  const authHeader = headers['authorization'];
+  let bearerToken = '';
+  if (authHeader && /^Bearer\s+/i.test(authHeader)) {
+    bearerToken = authHeader.replace(/^Bearer\s+/i, '').trim();
+  }
+  const candidate = headerToken || bearerToken;
+  if (!candidate) return false;
+  return safeCompare(expectedToken, candidate);
+}
+
+/**
+ * Read request body with raw Buffer preserved for signature verification.
+ */
+export function readRawBody(req, limit = MAX_WEBHOOK_BYTES) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let bytes = 0;
+    let settled = false;
+
+    const fail = (err) => {
+      if (settled) return;
+      settled = true;
+      reject(err);
+    };
+
+    req.on('data', (chunk) => {
+      if (settled) return;
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      bytes += buf.length;
+      if (bytes > limit) {
+        fail(Object.assign(new Error('Webhook payload exceeds 512 KiB limit'), { statusCode: 413 }));
+        req.destroy();
+        return;
+      }
+      chunks.push(buf);
+    });
+
+    req.on('end', () => {
+      if (settled) return;
+      settled = true;
+      const raw = chunks.length ? Buffer.concat(chunks) : Buffer.alloc(0);
+      let parsed = null;
+      const text = raw.toString('utf8').trim();
+      if (text) {
+        try {
+          parsed = JSON.parse(text);
+        } catch {
+          parsed = text;
+        }
+      } else {
+        parsed = {};
+      }
+      resolve({ raw, parsed });
+    });
+
+    req.on('error', (err) => {
+      fail(Object.assign(err, { statusCode: 400 }));
+    });
+  });
+}
+
+/**
+ * Handle incoming webhook request for a task.
+ */
+export async function handleTaskWebhookRoute({ store, scheduler, req, res, taskId: explicitTaskId }) {
+  if (req.method !== 'POST') {
+    sendJson(res, 405, NOT_ALLOWED);
+    return;
+  }
+
+  const url = new URL(req.url, 'http://127.0.0.1');
+  let taskId = explicitTaskId;
+  if (!taskId) {
+    const parts = url.pathname.split('/').filter(Boolean);
+    // /dsh-cron/webhook/:taskId or /dsh-cron/api/webhook/:taskId
+    const webhookIdx = parts.indexOf('webhook');
+    if (webhookIdx !== -1 && parts[webhookIdx + 1]) {
+      taskId = parts[webhookIdx + 1];
+    }
+  }
+
+  if (!taskId) {
+    sendJson(res, 400, { ok: false, error: 'Task ID is required in webhook URL path' });
+    return;
+  }
+
+  const task = store.get(taskId);
+  if (!task) {
+    sendJson(res, 404, { ok: false, error: `Task "${taskId}" not found` });
+    return;
+  }
+
+  if (task.status !== 'active') {
+    sendJson(res, 400, { ok: false, error: `Task "${taskId}" is not active (current status: ${task.status})` });
+    return;
+  }
+
+  const isEnabled = Boolean(
+    task.webhookEnabled ||
+    (task.webhookTrigger && task.webhookTrigger.enabled)
+  );
+  if (!isEnabled) {
+    logger.warn(`[dsh-cron] Webhook received for task "${taskId}" but webhooks are not enabled for this task`);
+    sendJson(res, 403, { ok: false, error: `Webhooks are not enabled for task "${taskId}"` });
+    return;
+  }
+
+  // Read raw body
+  let bodyData;
+  try {
+    bodyData = await readRawBody(req);
+  } catch (err) {
+    sendJson(res, err.statusCode || 400, { ok: false, error: err.message });
+    return;
+  }
+
+  const { raw, parsed } = bodyData;
+  const headers = req.headers || {};
+  const settings = typeof store.getSettings === 'function' ? store.getSettings() : {};
+
+  // Authentication check (fail-closed)
+  const taskSecret = task.webhookSecret || (task.webhookTrigger && task.webhookTrigger.secret);
+  const taskToken = task.webhookToken || (task.webhookTrigger && task.webhookTrigger.token);
+  const masterToken = settings.apiToken;
+
+  let authenticated = false;
+
+  if (taskSecret) {
+    const sigHeader = headers['x-hub-signature-256'] || headers['x-signature-256'] || headers['x-dsh-cron-signature'];
+    if (sigHeader && verifyHmacSignature(raw, taskSecret, sigHeader)) {
+      authenticated = true;
+    } else {
+      logger.warn(`[dsh-cron] Invalid HMAC signature for webhook task "${taskId}"`);
+      sendJson(res, 401, { ok: false, error: 'Invalid HMAC signature' });
+      return;
+    }
+  } else if (taskToken) {
+    if (verifyToken(taskToken, req, url)) {
+      authenticated = true;
+    } else {
+      logger.warn(`[dsh-cron] Invalid webhook token for task "${taskId}"`);
+      sendJson(res, 401, { ok: false, error: 'Invalid webhook token' });
+      return;
+    }
+  } else if (masterToken) {
+    if (verifyToken(masterToken, req, url)) {
+      authenticated = true;
+    } else {
+      logger.warn(`[dsh-cron] Invalid API token for webhook task "${taskId}"`);
+      sendJson(res, 401, { ok: false, error: 'Unauthorized: missing or invalid token' });
+      return;
+    }
+  } else {
+    logger.warn(`[dsh-cron] Webhook task "${taskId}" rejected: no secret or token configured (fail-closed)`);
+    sendJson(res, 403, { ok: false, error: 'Webhook secret or token must be configured for security' });
+    return;
+  }
+
+  // Debounce check
+  const debounceMs = Math.max(0, Number(task.webhookDebounceMs || (task.webhookTrigger && task.webhookTrigger.debounceMs) || 0));
+  if (debounceMs > 0) {
+    const now = Date.now();
+    const last = lastWebhookRuns.get(taskId) || 0;
+    if (now - last < debounceMs) {
+      logger.info(`[dsh-cron] Webhook for task "${taskId}" debounced (${now - last}ms < ${debounceMs}ms)`);
+      sendJson(res, 200, { ok: true, debounced: true, message: `Webhook debounced (${debounceMs}ms cooldown)` });
+      return;
+    }
+    lastWebhookRuns.set(taskId, now);
+  } else {
+    lastWebhookRuns.set(taskId, Date.now());
+  }
+
+  const query = Object.fromEntries(url.searchParams.entries());
+  const webhookPayload = {
+    body: parsed,
+    raw: raw.toString('utf8'),
+    headers,
+    query,
+  };
+
+  logger.info(`[dsh-cron] Webhook accepted for task "${taskId}", triggering execution`);
+
+  try {
+    const runPromise = scheduler.triggerManualRun(taskId, {
+      webhook: webhookPayload,
+      triggeredBy: 'webhook',
+    });
+
+    sendJson(res, 200, {
+      ok: true,
+      triggered: true,
+      taskId,
+      message: `Webhook received and task "${task.title}" triggered`,
+    });
+  } catch (runErr) {
+    logger.error(`[dsh-cron] Failed to trigger task "${taskId}" from webhook: ${runErr.message}`);
+    sendJson(res, 500, { ok: false, error: `Failed to trigger task: ${runErr.message}` });
+  }
+}

package/lib/api.js

@@ -1,3 +1,4 @@
+import { handleTaskWebhookRoute } from './api-task-webhook.js';
 import { rollbackPromptVersion, sanitizePromptHistory } from './prompt-evolver.js';
 import { sanitizeAdaptiveConfig } from './adaptive.js';
 import { logStreamer } from './log-streamer.js';
@@ -70,9 +71,11 @@ function refuseConfigOwned(res, id) {
  * deeper path unrouted (#96). Exported for unit tests.
  */
 export function createCronApiHandler(store, scheduler, collection) {
+  const ctx = collection?.ctx;
   return async function handleCronApi(req, res) {
     try {
       const apiToken = store?.getSettings?.()?.apiToken;
+      const authOptions = { apiToken, ctx };
       const url = new URL(req.url, 'http://127.0.0.1');
       const parts = url.pathname.split('/').filter(Boolean);
       const scope = parts[1]; // 'tasks' | 'action' | 'heartbeat-ping'
@@ -83,27 +86,31 @@ export function createCronApiHandler(store, scheduler, collection) {
         await handleTelegramWebhook({ store, scheduler, req, res });
         return;
       }
+      if (scope === 'webhook' && id) {
+        await handleTaskWebhookRoute({ store, scheduler, req, res, taskId: id });
+        return;
+      }
 
       if ((scope === 'heartbeat' || scope === 'heartbeat-ping') && id) {
-        handleHeartbeatPing({ store, req, res, taskId: id });
+        handleHeartbeatPing({ store, req, res, taskId: id, apiToken, ctx });
         return;
       }
 
       if (scope === 'schedule' && id === 'preview') {
-        await handleSchedulePreview({ req, res, url, store });
+        await handleSchedulePreview({ req, res, url, store, apiToken, ctx });
         return;
       }
       if (scope === 'schedule' && id === 'timeline-24h') {
-        await handleScheduleTimeline({ req, res, url, store, scheduler });
+        await handleScheduleTimeline({ req, res, url, store, scheduler, apiToken, ctx });
         return;
       }
 
       if (!id) {
-        await handleTaskCollection({ store, scheduler, collection, req, res, url, scope, apiToken });
+        await handleTaskCollection({ store, scheduler, collection, req, res, url, scope, apiToken, ctx });
         return;
       }
 
-      if (rejectCrossOrigin(req, res, { apiToken })) return;
+      if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
 
       // Export/import are collection operations that live under /tasks/:id/…,
       // so they are matched before the generic id handling below.
@@ -124,7 +131,7 @@ export function createCronApiHandler(store, scheduler, collection) {
         return;
       }
 
-      await handleTaskItem({ store, scheduler, req, res, url, id, action, apiToken });
+      await handleTaskItem({ store, scheduler, req, res, url, id, action, apiToken, ctx });
     } catch (err) {
       sendJson(res, err.statusCode || 500, { ok: false, error: err.message });
     }
@@ -133,19 +140,19 @@ export function createCronApiHandler(store, scheduler, collection) {
 
 // ------------------------------------------------------------- collection
 
-async function handleTaskCollection({ store, scheduler, collection, req, res, url, scope, apiToken }) {
+async function handleTaskCollection({ store, scheduler, collection, req, res, url, scope, apiToken, ctx }) {
   // The alias family only exists for individual tasks.
   if (scope === 'action' || !collection) {
     sendJson(res, 405, NOT_ALLOWED);
     return;
   }
   if (req.method === 'GET') {
-    if (rejectCrossOrigin(req, res, { apiToken })) return;
+    if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
     listTasks({ store, scheduler, collection, req, res, url });
     return;
   }
   if (req.method === 'POST') {
-    await createOrUpdateTask({ store, scheduler, req, res, apiToken });
+    await createOrUpdateTask({ store, scheduler, req, res, apiToken, ctx: undefined });
     return;
   }
   sendJson(res, 405, NOT_ALLOWED);
@@ -182,8 +189,8 @@ function listTasks({ store, scheduler, collection, req, res, url }) {
   sendJson(res, 200, payload);
 }
 
-async function createOrUpdateTask({ store, scheduler, req, res, apiToken }) {
-  if (rejectCrossOrigin(req, res, { apiToken })) return;
+async function createOrUpdateTask({ store, scheduler, req, res, apiToken, ctx }) {
+  if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
   const { body: rawBody, error } = await readBody(req, res);
   if (error) return;
   const existing = rawBody.id ? store.get(rawBody.id) : null;
@@ -286,14 +293,14 @@ function buildTaskRecord(store, body, taskType, parsed) {
 
 // ------------------------------------------------------------ single task
 
-async function handleTaskItem({ store, scheduler, req, res, url, id, action, apiToken }) {
+async function handleTaskItem({ store, scheduler, req, res, url, id, action, apiToken, ctx }) {
   if (action === 'heartbeat') {
-    handleHeartbeatPing({ store, req, res, taskId: id });
+    handleHeartbeatPing({ store, req, res, taskId: id, apiToken, ctx });
     return;
   }
 
   if (req.method === 'POST' && action === 'dry-run') {
-    await handleDryRunTask({ store, scheduler, req, res, id });
+    await handleDryRunTask({ store, scheduler, req, res, id, apiToken, ctx });
     return;
   }
 
@@ -302,7 +309,7 @@ async function handleTaskItem({ store, scheduler, req, res, url, id, action, api
       logStreamer.handleSseRequest(id, req, res);
       return;
     }
-    if (rejectCrossOrigin(req, res, { apiToken })) return;
+    if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
     if (action === 'archive') {
       const limit = parseInt(url.searchParams.get('limit') || '50', 10);
       const offset = parseInt(url.searchParams.get('offset') || '0', 10);
@@ -640,6 +647,18 @@ function mergeExecutionFields(current, body, parsed) {
     targetSessionId: body.targetSessionId !== undefined ? String(body.targetSessionId).trim() : (current ? (current.targetSessionId || '') : ''),
     targetSessionReset: body.targetSessionReset !== undefined ? String(body.targetSessionReset).trim() : (current ? (current.targetSessionReset || 'never') : 'never'),
     sessionTitle: body.sessionTitle !== undefined ? String(body.sessionTitle).trim() : (current ? (current.sessionTitle || '') : ''),
+    webhookEnabled: body.webhookEnabled !== undefined
+      ? Boolean(body.webhookEnabled)
+      : (body.webhookTrigger?.enabled !== undefined ? Boolean(body.webhookTrigger.enabled) : (current ? Boolean(current.webhookEnabled || current.webhookTrigger?.enabled) : false)),
+    webhookToken: body.webhookToken !== undefined
+      ? String(body.webhookToken).trim()
+      : (body.webhookTrigger?.token ? String(body.webhookTrigger.token).trim() : (current ? (current.webhookToken || current.webhookTrigger?.token || '') : '')),
+    webhookSecret: body.webhookSecret !== undefined
+      ? String(body.webhookSecret).trim()
+      : (body.webhookTrigger?.secret ? String(body.webhookTrigger.secret).trim() : (current ? (current.webhookSecret || current.webhookTrigger?.secret || '') : '')),
+    webhookDebounceMs: body.webhookDebounceMs !== undefined
+      ? (Number(body.webhookDebounceMs) || 0)
+      : (body.webhookTrigger?.debounceMs !== undefined ? (Number(body.webhookTrigger.debounceMs) || 0) : (current ? (Number(current.webhookDebounceMs || current.webhookTrigger?.debounceMs) || 0) : 0)),
     onSuccess: body.onSuccess !== undefined ? String(body.onSuccess).trim() : (current ? (current.onSuccess || '') : ''),
     onFailure: body.onFailure !== undefined ? String(body.onFailure).trim() : (current ? (current.onFailure || '') : ''),
     heartbeatIntervalSeconds: body.heartbeatIntervalSeconds !== undefined ? Number(body.heartbeatIntervalSeconds) : (current ? (Number(current.heartbeatIntervalSeconds) || 0) : 0),
@@ -665,6 +684,10 @@ function mergeExecutionFields(current, body, parsed) {
  */
 export async function handleExternalTaskRequest({ store, scheduler, req, res, url, apiToken }) {
   const parts = url.pathname.split('/').filter(Boolean); // dsh-cron, api, [tasks|heartbeat|schedule], :id?, :action?
+  if (parts[2] === 'webhook' && parts[3]) {
+    await handleTaskWebhookRoute({ store, scheduler, req, res, taskId: parts[3] });
+    return;
+  }
   if (parts[2] === 'heartbeat' && parts[3]) {
     handleHeartbeatPing({ store, req, res, taskId: parts[3], apiToken });
     return;
@@ -685,7 +708,7 @@ export async function handleExternalTaskRequest({ store, scheduler, req, res, ur
       return;
     }
     if (req.method === 'POST') {
-      await createOrUpdateTask({ store, scheduler, req, res, apiToken });
+      await createOrUpdateTask({ store, scheduler, req, res, apiToken, ctx: undefined });
       return;
     }
     sendJson(res, 405, NOT_ALLOWED);

package/lib/cron-tool.js

@@ -64,7 +64,7 @@ export const cronToolParameters = {
   },
   schedule: {
     type: 'string',
-    description: 'Schedule expression: cron ("0 9 * * *"), shorthand ("@daily", "@every 30m"), interval ("every 2h"), or one-shot ("in 30m", "at: 2026-09-05T15:00:00Z")',
+    description: 'Schedule expression: natural language ("every day at 9am", "every weekday at 10am", "in 2 hours", Russian phrases supported), cron ("0 9 * * *"), shorthand ("@daily"), interval ("every 2h"), or one-shot ("in 30m")',
   },
   prompt: {
     type: 'string',