@goodandready/dsh-cron 0.3.10 → 0.3.12

package/lib/prompt-interpolation.js

@@ -14,6 +14,36 @@ function formatTime(d) {
   return `${hours}:${minutes}:${seconds}`;
 }
 
+/**
+ * Safely extract nested property from object by path.
+ * Supports dot and array bracket notation: "alerts[0].labels.container" or "issue.title".
+ */
+export function getNestedValue(obj, path) {
+  if (!obj || typeof obj !== 'object' || !path) return undefined;
+  // If property exists directly (e.g. headers with dashes like "x-github-event")
+  if (Object.prototype.hasOwnProperty.call(obj, path)) {
+    return obj[path];
+  }
+  // Try lowercase lookup for headers
+  const lowerPath = path.toLowerCase();
+  for (const [k, v] of Object.entries(obj)) {
+    if (k.toLowerCase() === lowerPath) return v;
+  }
+
+  const normalized = path.replace(/\[(\w+)\]/g, '.$1');
+  const parts = normalized.split('.');
+  let current = obj;
+  for (const p of parts) {
+    if (current == null) return undefined;
+    if (typeof current === 'object' && Object.prototype.hasOwnProperty.call(current, p)) {
+      current = current[p];
+    } else {
+      return undefined;
+    }
+  }
+  return current;
+}
+
 /**
  * Build dictionary of prompt interpolation variables for a task and run options.
  */
@@ -73,6 +103,16 @@ export function buildPromptContext(task = {}, options = {}) {
     'task_title': task.title || '',
   };
 
+  // Webhook context (#348)
+  if (options.webhook && typeof options.webhook === 'object') {
+    ctx.__webhook = options.webhook;
+    if (options.webhook.body !== undefined) {
+      ctx['webhook.body'] = typeof options.webhook.body === 'object'
+        ? JSON.stringify(options.webhook.body)
+        : String(options.webhook.body);
+    }
+  }
+
   // DAG / Fan-In predecessor outputs (#328)
   if (options.prevOutputs && typeof options.prevOutputs === 'object') {
     for (const [k, v] of Object.entries(options.prevOutputs)) {
@@ -90,14 +130,17 @@ export function buildPromptContext(task = {}, options = {}) {
 
 /**
  * Replace {{var}} or {var} placeholders with values from context.
- * Supports dot notation like {{prev.output}} and bracket notation like {{prevOutputs['step1']}}.
+ * Supports dot notation like {{prev.output}}, bracket notation like {{prevOutputs['step1']}},
+ * and nested webhook properties like {{webhook.body.alerts[0].labels.container}} (#348).
  */
 export function interpolateTaskPrompt(text, context = {}) {
   if (typeof text !== 'string') return text;
   if (!text) return '';
 
-  // 1. Bracket notation: {{prevOutputs['step1']}} or {prevOutputs['step1']} or with double quotes
-  let result = text.replace(/\{\{?prevOutputs\[['"]([^'"]+)['"]\]\}?\}/g, (match, stepId) => {
+  let result = text;
+
+  // 1. Bracket notation for DAG: {{prevOutputs['step1']}} or {prevOutputs['step1']}
+  result = result.replace(/\{\{?prevOutputs\[['"]([^'"]+)['"]\]\}?\}/g, (match, stepId) => {
     const key = `prevOutputs.${stepId}`;
     if (Object.prototype.hasOwnProperty.call(context, key)) {
       return context[key];
@@ -105,7 +148,21 @@ export function interpolateTaskPrompt(text, context = {}) {
     return match;
   });
 
-  // 2. Standard {{var}} and {var}
+  // 2. Webhook payload interpolation (#348): {webhook.body.path}, {webhook.headers.key}, {webhook.query.param}
+  if (context.__webhook && typeof context.__webhook === 'object') {
+    result = result.replace(/\{\{?webhook\.(body|headers|query)(?:\.([a-zA-Z0-9_.\[\]-]+))?\}?\}/g, (match, source, path) => {
+      const srcObj = context.__webhook[source];
+      if (!path) {
+        if (srcObj === undefined) return '';
+        return typeof srcObj === 'object' ? JSON.stringify(srcObj) : String(srcObj);
+      }
+      const val = getNestedValue(srcObj, path);
+      if (val === undefined) return '';
+      return typeof val === 'object' ? JSON.stringify(val) : String(val);
+    });
+  }
+
+  // 3. Standard {{var}} and {var}
   result = result.replace(/\{\{([a-zA-Z0-9_.]+)\}\}/g, (match, varName) => {
     if (Object.prototype.hasOwnProperty.call(context, varName)) {
       const val = context[varName];
@@ -143,5 +200,20 @@ export function resolveTaskForExecution(task, options = {}) {
   if (typeof resolved.url === 'string') {
     resolved.url = interpolateTaskPrompt(resolved.url, context);
   }
+
+  // Expose webhook payload in process environment for scripts (#348)
+  if (options.webhook && typeof options.webhook === 'object') {
+    const env = { ...(resolved.env || {}) };
+    if (options.webhook.body !== undefined) {
+      env.DSH_CRON_WEBHOOK_BODY = typeof options.webhook.body === 'object'
+        ? JSON.stringify(options.webhook.body)
+        : String(options.webhook.body);
+    }
+    if (options.webhook.headers !== undefined) {
+      env.DSH_CRON_WEBHOOK_HEADERS = JSON.stringify(options.webhook.headers);
+    }
+    resolved.env = env;
+  }
+
   return resolved;
 }

package/lib/routes.js

@@ -1,3 +1,4 @@
+import { handleTaskWebhookRoute } from './api-task-webhook.js';
 import { calculateCostHeatmap } from './timeline.js';
 import { buildAnalyticsDigest, formatDigestMarkdown, sendAnalyticsDigest } from './analytics-digest.js';
 import { listVerifiedRecipes } from './recipes-catalog.js';
@@ -19,32 +20,39 @@ export function registerRoutes(ctx, { store, scheduler, recommendations }) {
   ctx.effect(() => ctx.webServer.register({
     kind: 'prefix',
     path: '/dsh-cron/tasks',
-    handler: createCronApiHandler(store, scheduler, { recommendations })
+    handler: createCronApiHandler(store, scheduler, { recommendations, ctx })
   }), 'dsh-cron: /tasks[...]');
 
   // Alias route /dsh-cron/action/:id/:action for backward compatibility (#66)
   ctx.effect(() => ctx.webServer.register({
     kind: 'prefix',
     path: '/dsh-cron/action',
-    handler: createCronApiHandler(store, scheduler, null)
+    handler: createCronApiHandler(store, scheduler, { ctx })
   }), 'dsh-cron: /action/:id/:action');
 
   ctx.effect(() => ctx.webServer.register({
     kind: 'prefix',
     path: '/dsh-cron/telegram',
-    handler: createCronApiHandler(store, scheduler, null)
+    handler: createCronApiHandler(store, scheduler, { ctx })
   }), 'dsh-cron: /telegram[...]');
 
+  // Incoming HTTP Webhook triggers (#348)
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'prefix',
+    path: '/dsh-cron/webhook',
+    handler: (req, res) => handleTaskWebhookRoute({ store, scheduler, req, res })
+  }), 'dsh-cron: /webhook[...]');
+
   ctx.effect(() => ctx.webServer.register({
     kind: 'prefix',
     path: '/dsh-cron/heartbeat-ping',
-    handler: createCronApiHandler(store, scheduler, null)
+    handler: createCronApiHandler(store, scheduler, { ctx })
   }), 'dsh-cron: /heartbeat-ping[...]');
 
   ctx.effect(() => ctx.webServer.register({
     kind: 'prefix',
     path: '/dsh-cron/schedule',
-    handler: createCronApiHandler(store, scheduler, null)
+    handler: createCronApiHandler(store, scheduler, { ctx })
   }), 'dsh-cron: /schedule[...]');
 
 
@@ -52,14 +60,14 @@ export function registerRoutes(ctx, { store, scheduler, recommendations }) {
   ctx.effect(() => ctx.webServer.register({
     kind: 'prefix',
     path: '/dsh-cron/chains',
-    handler: (req, res) => handleChainRoutes(store, scheduler, req, res)
+    handler: (req, res) => handleChainRoutes(store, scheduler, req, res, ctx)
   }), 'dsh-cron: /chains[...]');
 
   // Run artifacts listing, download and safe preview (#321)
   ctx.effect(() => ctx.webServer.register({
     kind: 'prefix',
     path: '/dsh-cron/runs',
-    handler: (req, res) => handleRunArtifactRoutes(store, req, res)
+    handler: (req, res) => handleRunArtifactRoutes(store, req, res, ctx)
   }), 'dsh-cron: /runs[...]');
 
   // GET /dsh-cron/metrics (#53) — Prometheus text exposition
@@ -90,7 +98,7 @@ export function registerRoutes(ctx, { store, scheduler, recommendations }) {
     handler: async (req, res) => {
       const settings = store && typeof store.getSettings === 'function' ? store.getSettings() : {};
       const apiToken = settings.apiToken;
-      if (rejectCrossOrigin(req, res, { apiToken })) return;
+      if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
       await getModelsHandler(ctx, req, res, sendJson);
     }
   }), 'dsh-cron: /models');
@@ -100,7 +108,7 @@ export function registerRoutes(ctx, { store, scheduler, recommendations }) {
     kind: 'exact',
     path: '/dsh-cron/chat/start',
     handler: async (req, res) => {
-      if (req.method === 'POST' && rejectCrossOrigin(req, res)) return;
+      if (req.method === 'POST' && rejectCrossOrigin(req, res, { ctx })) return;
       await chatStartHandler(ctx, req, res, parseJsonBody, sendJson, randomUUID);
     }
   }), 'dsh-cron: /chat/start');
@@ -113,7 +121,7 @@ export function registerRoutes(ctx, { store, scheduler, recommendations }) {
       try {
         const settings = store && typeof store.getSettings === 'function' ? store.getSettings() : {};
         const apiToken = settings.apiToken;
-        if (rejectCrossOrigin(req, res, { apiToken })) return;
+        if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
 
         const url = new URL(req.url, 'http://127.0.0.1');
         const path = url.pathname;
@@ -161,7 +169,7 @@ export function registerRoutes(ctx, { store, scheduler, recommendations }) {
         }
 
         if (req.method === 'POST') {
-          if (rejectCrossOrigin(req, res)) return;
+          if (rejectCrossOrigin(req, res, { ctx })) return;
           const { body } = await readBody(req, res);
           const days = parseInt(body?.days || url.searchParams.get('days') || '7', 10);
           const tasks = store.list ? store.list() : Object.values(store.tasks || {});
@@ -219,7 +227,7 @@ export function registerRoutes(ctx, { store, scheduler, recommendations }) {
         }
         const settings = store.getSettings ? store.getSettings() : {};
         const apiToken = settings.apiToken;
-        if (rejectCrossOrigin(req, res, { apiToken })) return;
+        if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
         const categories = recipesByCategory();
         const recipes = listVerifiedRecipes(settings);
         sendJson(res, 200, { ok: true, categories, recipes });
@@ -241,7 +249,7 @@ export function registerRoutes(ctx, { store, scheduler, recommendations }) {
         }
         const settings = store.getSettings ? store.getSettings() : {};
         const apiToken = settings.apiToken;
-        if (rejectCrossOrigin(req, res, { apiToken })) return;
+        if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
 
         const tasks = store.list({ status: 'active' });
         const lastRuns = tasks.map((t) => t.lastRunAt || 0);
@@ -268,7 +276,7 @@ export function registerRoutes(ctx, { store, scheduler, recommendations }) {
           sendJson(res, 405, { ok: false, error: 'Method not allowed' });
           return;
         }
-        if (rejectCrossOrigin(req, res)) return;
+        if (rejectCrossOrigin(req, res, { ctx })) return;
         const { body, error } = await readBody(req, res);
         if (error) return;
         const settings = store.getSettings();
@@ -300,7 +308,7 @@ export function registerRoutes(ctx, { store, scheduler, recommendations }) {
           sendJson(res, 405, { ok: false, error: 'Method not allowed' });
           return;
         }
-        if (rejectCrossOrigin(req, res)) return;
+        if (rejectCrossOrigin(req, res, { ctx })) return;
         const { body, error } = await readBody(req, res);
         if (error) return;
         const settings = store.getSettings();
@@ -331,10 +339,10 @@ export function registerRoutes(ctx, { store, scheduler, recommendations }) {
 /**
  * Handler for chain step retries (#319)
  */
-export async function handleChainRoutes(store, scheduler, req, res) {
+export async function handleChainRoutes(store, scheduler, req, res, ctx) {
   const settings = store && typeof store.getSettings === 'function' ? store.getSettings() : {};
   const apiToken = settings.apiToken;
-  if (rejectCrossOrigin(req, res, { apiToken })) return;
+  if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
   const url = new URL(req.url, 'http://localhost');
 
   // GET /dsh-cron/chains/:chainRunId (#334)
@@ -378,7 +386,7 @@ export async function handleChainRoutes(store, scheduler, req, res) {
 /**
  * Handler for run artifacts (#321)
  */
-export async function handleRunArtifactRoutes(store, req, res) {
+export async function handleRunArtifactRoutes(store, req, res, ctx) {
   const url = new URL(req.url, 'http://localhost');
   const m = url.pathname.match(/^\/dsh-cron\/runs\/([^\/]+)\/artifacts(?:\/([^\/]+)(?:\/(preview))?)?$/);
   if (!m) {
@@ -391,7 +399,7 @@ export async function handleRunArtifactRoutes(store, req, res) {
   }
   const settings = store && typeof store.getSettings === 'function' ? store.getSettings() : {};
   const apiToken = settings.apiToken;
-  if (rejectCrossOrigin(req, res, { apiToken })) return;
+  if (rejectCrossOrigin(req, res, { apiToken, ctx })) return;
 
   const [, runId, artifactId, action] = m;
   if (!artifactId) {

package/lib/scheduler.js

@@ -2,6 +2,7 @@ import { logger } from './logger.js';
 import { bestEffort } from './best-effort.js';
 import { Cron } from 'croner';
 import { FileSystemWatcherManager } from './watcher.js';
+import { parseNaturalSchedule } from './nl-schedule.js';
 
 const MAX_TIMEOUT_MS = 2147483647; // 2^31 - 1 ms (~24.85 days)
 import {
@@ -31,6 +32,7 @@ import {
 } from './scheduler-lifecycle.js';
 
 export {
+  parseNaturalSchedule,
   executePreflight,
   AGENT_TASK_TYPES,
   addUsage,
@@ -212,25 +214,35 @@ function parseIntervalExpression(str) {
  * @-shorthands (#15) and the friendly aliases, including the Russian input
  * aliases. Russian keywords are accepted input, not display strings.
  */
+function makeAliasResult(cronPattern, humanText) {
+  try {
+    const job = new Cron(cronPattern, { sloppyRanges: true });
+    const next = job.nextRun();
+    return { cronPattern, humanText, nextRun: next ? next.getTime() : null };
+  } catch {
+    return { cronPattern, humanText };
+  }
+}
+
 function parseAliasExpression(str) {
   const lower = str.toLowerCase();
-  if (lower === '@hourly') return { cronPattern: '0 * * * *', humanText: 'Every hour' };
-  if (lower === '@daily' || lower === '@midnight') return { cronPattern: '0 0 * * *', humanText: 'Every day at 00:00' };
-  if (lower === '@weekly') return { cronPattern: '0 0 * * 0', humanText: 'Every week on Sunday at 00:00' };
-  if (lower === '@monthly') return { cronPattern: '0 0 1 * *', humanText: 'Every month on the 1st at 00:00' };
-  if (lower === '@yearly' || lower === '@annually') return { cronPattern: '0 0 1 1 *', humanText: 'Every year on Jan 1 at 00:00' };
+  if (lower === '@hourly') return makeAliasResult('0 * * * *', 'Every hour');
+  if (lower === '@daily' || lower === '@midnight') return makeAliasResult('0 0 * * *', 'Every day at 00:00');
+  if (lower === '@weekly') return makeAliasResult('0 0 * * 0', 'Every week on Sunday at 00:00');
+  if (lower === '@monthly') return makeAliasResult('0 0 1 * *', 'Every month on the 1st at 00:00');
+  if (lower === '@yearly' || lower === '@annually') return makeAliasResult('0 0 1 1 *', 'Every year on Jan 1 at 00:00');
   const everyAlias = str.match(/^@every\s+(\d+)\s*(sec|seconds?|m|min|minutes?|h|hr|hours?|d|days?)$/i);
   if (everyAlias) {
     return parseIntervalExpression(`every ${everyAlias[1]} ${everyAlias[2]}`);
   }
   if (lower === 'daily' || lower === 'каждый день') {
-    return { cronPattern: '0 9 * * *', humanText: 'Every day at 09:00' };
+    return makeAliasResult('0 9 * * *', 'Every day at 09:00');
   }
   if (lower === 'weekdays' || lower === 'в будние дни' || lower === 'по будням') {
-    return { cronPattern: '0 9 * * 1-5', humanText: 'Weekdays at 09:00' };
+    return makeAliasResult('0 9 * * 1-5', 'Weekdays at 09:00');
   }
   if (lower === 'hourly' || lower === 'каждый час') {
-    return { cronPattern: '0 * * * *', humanText: 'Every hour' };
+    return makeAliasResult('0 * * * *', 'Every hour');
   }
   return null;
 }
@@ -261,6 +273,7 @@ export function parseScheduleExpression(input) {
     || parseRelativeOneShot(str)
     || parseIntervalExpression(str)
     || parseAliasExpression(str)
+    || parseNaturalSchedule(str)
     || parseCronExpression(str);
 }
 

package/lib/store.js

@@ -629,6 +629,12 @@ export class TaskStore {
       targetSessionId: task.targetSessionId !== undefined ? String(task.targetSessionId).trim() : (prev.targetSessionId || ''),
       targetSessionReset: task.targetSessionReset !== undefined ? String(task.targetSessionReset).trim() : (prev.targetSessionReset || 'never'),
       sessionTitle: task.sessionTitle !== undefined ? String(task.sessionTitle).trim() : (prev.sessionTitle || ''),
+      webhookEnabled: task.webhookEnabled !== undefined
+        ? Boolean(task.webhookEnabled)
+        : (prev.webhookEnabled !== undefined ? Boolean(prev.webhookEnabled) : Boolean(task.webhookTrigger?.enabled || prev.webhookTrigger?.enabled || false)),
+      webhookToken: task.webhookToken !== undefined ? String(task.webhookToken).trim() : (prev.webhookToken || (task.webhookTrigger?.token ? String(task.webhookTrigger.token).trim() : '')),
+      webhookSecret: task.webhookSecret !== undefined ? String(task.webhookSecret).trim() : (prev.webhookSecret || (task.webhookTrigger?.secret ? String(task.webhookTrigger.secret).trim() : '')),
+      webhookDebounceMs: task.webhookDebounceMs !== undefined ? Number(task.webhookDebounceMs) : (prev.webhookDebounceMs !== undefined ? Number(prev.webhookDebounceMs) : (Number(task.webhookTrigger?.debounceMs || prev.webhookTrigger?.debounceMs) || 0)),
       totalTokens: task.totalTokens !== undefined ? Number(task.totalTokens) : (prev.totalTokens || 0),
       totalCostUsd: task.totalCostUsd !== undefined ? Number(task.totalCostUsd) : (prev.totalCostUsd || 0),
       createdAt: prev.createdAt || task.createdAt || now,

package/lib/task-create.js

@@ -49,6 +49,10 @@ export function executeCreateTask(store, scheduler, args) {
     targetSessionId: args.targetSessionId ? String(args.targetSessionId).trim() : '',
     targetSessionReset: args.targetSessionReset ? String(args.targetSessionReset).trim() : 'never',
     sessionTitle: args.sessionTitle ? String(args.sessionTitle).trim() : '',
+    webhookEnabled: args.webhookEnabled !== undefined ? Boolean(args.webhookEnabled) : (args.webhookTrigger?.enabled !== undefined ? Boolean(args.webhookTrigger.enabled) : false),
+    webhookToken: args.webhookToken ? String(args.webhookToken).trim() : (args.webhookTrigger?.token ? String(args.webhookTrigger.token).trim() : undefined),
+    webhookSecret: args.webhookSecret ? String(args.webhookSecret).trim() : (args.webhookTrigger?.secret ? String(args.webhookTrigger.secret).trim() : undefined),
+    webhookDebounceMs: args.webhookDebounceMs !== undefined ? Number(args.webhookDebounceMs) : (args.webhookTrigger?.debounceMs !== undefined ? Number(args.webhookTrigger.debounceMs) : undefined),
     onSuccess: args.onSuccess ? String(args.onSuccess).trim() : '',
     onFailure: args.onFailure ? String(args.onFailure).trim() : '',
     dependsOn: args.dependsOn !== undefined ? sanitizeDependsOn(args.dependsOn) : undefined,

package/lib/task-patch.js

@@ -91,6 +91,18 @@ export function buildTaskPatch(current, body) {
       return { ok: false, error: err.message };
     }
   }
+  if (patch.webhookEnabled !== undefined) {
+    patch.webhookEnabled = Boolean(patch.webhookEnabled);
+  }
+  if (patch.webhookToken !== undefined) {
+    patch.webhookToken = String(patch.webhookToken).trim();
+  }
+  if (patch.webhookSecret !== undefined) {
+    patch.webhookSecret = String(patch.webhookSecret).trim();
+  }
+  if (patch.webhookDebounceMs !== undefined) {
+    patch.webhookDebounceMs = Math.max(0, Number(patch.webhookDebounceMs) || 0);
+  }
   if (patch.requireApproval !== undefined) {
     patch.requireApproval = Boolean(patch.requireApproval);
   }

package/lib/task-transfer.js

@@ -34,6 +34,11 @@ export const PATCHABLE_TASK_FIELDS = [
   'targetSessionId',
   'targetSessionReset',
   'sessionTitle',
+  'webhookEnabled',
+  'webhookToken',
+  'webhookSecret',
+  'webhookDebounceMs',
+  'webhookTrigger',
   'env',
   'cwd',
   'workspaceId',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-cron",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "description": "Background automation runner for DSH: isolated agent runs, script/HTTP/SSH/Docker runtimes, cost guard, notifications, heartbeats.",
   "type": "module",
   "main": "lib/index.js",