@goodandready/dsh-cron 0.3.3 → 0.3.5

package/lib/prompt-evolver.js

@@ -0,0 +1,148 @@
+/**
+ * Prompt Auto-Evolver & Versioning Engine (#331)
+ *
+ * Tracks prompt revisions, maintains versioned prompt history, computes
+ * empirical Success Rates across versions, and enables 1-click rollback.
+ */
+
+const MAX_PROMPT_HISTORY = 20;
+
+export function sanitizePromptHistory(history) {
+  if (!Array.isArray(history)) return [];
+  return history
+    .filter((h) => h && typeof h === 'object' && typeof h.prompt === 'string')
+    .slice(-MAX_PROMPT_HISTORY)
+    .map((h, idx) => ({
+      version: typeof h.version === 'number' && h.version > 0 ? h.version : (idx + 1),
+      prompt: String(h.prompt || ''),
+      note: typeof h.note === 'string' ? h.note.slice(0, 100) : 'Revision',
+      runs: typeof h.runs === 'number' && h.runs >= 0 ? h.runs : 0,
+      successes: typeof h.successes === 'number' && h.successes >= 0 ? h.successes : 0,
+      successRate: typeof h.successRate === 'number' && h.successRate >= 0 && h.successRate <= 1
+        ? Number(h.successRate.toFixed(3))
+        : (typeof h.runs === 'number' && h.runs > 0 ? Number(((h.successes || 0) / h.runs).toFixed(3)) : 1.0),
+      createdAt: typeof h.createdAt === 'number' ? h.createdAt : Date.now(),
+      lastRunAt: typeof h.lastRunAt === 'number' ? h.lastRunAt : null,
+    }));
+}
+
+export function trackPromptEdit(currentTask, newPrompt, note = 'Manual edit') {
+  if (!currentTask || typeof newPrompt !== 'string') {
+    return {
+      prompt: currentTask ? currentTask.prompt : newPrompt,
+      promptVersion: currentTask ? (currentTask.promptVersion || 1) : 1,
+      promptHistory: currentTask ? sanitizePromptHistory(currentTask.promptHistory) : [],
+    };
+  }
+
+  const trimmedNew = newPrompt.trim();
+  const trimmedOld = (currentTask.prompt || '').trim();
+
+  let history = sanitizePromptHistory(currentTask.promptHistory);
+
+  // If prompt has not changed, keep current version and baseline history if needed
+  if (trimmedNew === trimmedOld) {
+    if (history.length === 0 && trimmedOld) {
+      history.push({
+        version: currentTask.promptVersion || 1,
+        prompt: currentTask.prompt,
+        note: 'Initial baseline',
+        runs: typeof currentTask.runs === 'number' ? currentTask.runs : 0,
+        successes: typeof currentTask.successes === 'number' ? currentTask.successes : 0,
+        successRate: currentTask.runs > 0
+          ? Number(((currentTask.successes || 0) / currentTask.runs).toFixed(3))
+          : 1.0,
+        createdAt: currentTask.createdAt || Date.now(),
+        lastRunAt: currentTask.lastRun || null,
+      });
+    }
+    return {
+      prompt: currentTask.prompt,
+      promptVersion: currentTask.promptVersion || 1,
+      promptHistory: history,
+    };
+  }
+
+  // If no history exists yet, record baseline version 1 with existing task metrics before bumping
+  if (history.length === 0 && trimmedOld) {
+    history.push({
+      version: 1,
+      prompt: currentTask.prompt,
+      note: 'Initial baseline',
+      runs: typeof currentTask.runs === 'number' ? currentTask.runs : 0,
+      successes: typeof currentTask.successes === 'number' ? currentTask.successes : 0,
+      successRate: currentTask.runs > 0
+        ? Number(((currentTask.successes || 0) / currentTask.runs).toFixed(3))
+        : 1.0,
+      createdAt: currentTask.createdAt || Date.now(),
+      lastRunAt: currentTask.lastRun || null,
+    });
+  }
+
+  const maxVersion = history.reduce((max, h) => Math.max(max, h.version || 1), currentTask.promptVersion || 1);
+  const nextVersion = maxVersion + 1;
+
+  history.push({
+    version: nextVersion,
+    prompt: newPrompt,
+    note: String(note || 'Manual edit').slice(0, 100),
+    runs: 0,
+    successes: 0,
+    successRate: 1.0,
+    createdAt: Date.now(),
+    lastRunAt: null,
+  });
+
+  return {
+    prompt: newPrompt,
+    promptVersion: nextVersion,
+    promptHistory: sanitizePromptHistory(history),
+  };
+}
+
+export function recordPromptRunOutcome(task, isSuccess) {
+  if (!task || typeof task.prompt !== 'string') return task?.promptHistory || [];
+
+  let history = sanitizePromptHistory(task.promptHistory);
+  const activeVersion = task.promptVersion || 1;
+
+  let entry = history.find((h) => h.version === activeVersion);
+  if (!entry) {
+    entry = {
+      version: activeVersion,
+      prompt: task.prompt,
+      note: 'Active prompt',
+      runs: 0,
+      successes: 0,
+      successRate: 1.0,
+      createdAt: Date.now(),
+      lastRunAt: null,
+    };
+    history.push(entry);
+  }
+
+  entry.runs = (entry.runs || 0) + 1;
+  if (isSuccess) {
+    entry.successes = (entry.successes || 0) + 1;
+  }
+  entry.successRate = Number((entry.successes / entry.runs).toFixed(3));
+  entry.lastRunAt = Date.now();
+
+  task.promptHistory = sanitizePromptHistory(history);
+  return task.promptHistory;
+}
+
+export function rollbackPromptVersion(task, targetVersion) {
+  if (!task) return null;
+  const history = sanitizePromptHistory(task.promptHistory);
+  const target = history.find((h) => h.version === targetVersion);
+  if (!target) {
+    throw new Error(`Target prompt version ${targetVersion} not found in history`);
+  }
+
+  const edit = trackPromptEdit(task, target.prompt, `Rollback to v${targetVersion}`);
+  task.prompt = edit.prompt;
+  task.promptVersion = edit.promptVersion;
+  task.promptHistory = edit.promptHistory;
+  return task;
+}

package/lib/routes.js

@@ -1,3 +1,5 @@
+import { calculateCostHeatmap } from './timeline.js';
+import { buildAnalyticsDigest, formatDigestMarkdown, sendAnalyticsDigest } from './analytics-digest.js';
 import { listVerifiedRecipes } from './recipes-catalog.js';
 import { randomUUID } from 'node:crypto';
 import { createCronApiHandler } from './api.js';
@@ -100,6 +102,104 @@ export function registerRoutes(ctx, { store, scheduler, recommendations }) {
     }
   }), 'dsh-cron: /chat/start');
 
+  // Analytics digest routes (#330)
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'prefix',
+    path: '/dsh-cron/analytics',
+    handler: async (req, res) => {
+      try {
+        const url = new URL(req.url, 'http://127.0.0.1');
+        const path = url.pathname;
+
+        if (req.method === 'GET') {
+          if (path === '/dsh-cron/analytics/heatmap') {
+            const modelFilter = url.searchParams.get('model') || null;
+            const providerFilter = url.searchParams.get('provider') || null;
+            const costLedger = store.costLedger || [];
+            let history = [];
+            if (store.history) {
+              if (typeof store.history.values === 'function') {
+                for (const runs of store.history.values()) {
+                  if (Array.isArray(runs)) history.push(...runs);
+                }
+              } else if (typeof store.history === 'object') {
+                for (const runs of Object.values(store.history)) {
+                  if (Array.isArray(runs)) history.push(...runs);
+                }
+              }
+            }
+            const heatmap = calculateCostHeatmap({ costLedger, history, modelFilter, providerFilter });
+            sendJson(res, 200, { ok: true, heatmap });
+            return;
+          }
+          const days = parseInt(url.searchParams.get('days') || '7', 10);
+          const tasks = store.list ? store.list() : Object.values(store.tasks || {});
+          let history = [];
+          if (store.history) {
+            if (typeof store.history.values === 'function') {
+              for (const runs of store.history.values()) {
+                if (Array.isArray(runs)) history.push(...runs);
+              }
+            } else if (typeof store.history === 'object') {
+              for (const runs of Object.values(store.history)) {
+                if (Array.isArray(runs)) history.push(...runs);
+              }
+            }
+          }
+          const costLedger = store.costLedger || [];
+          const digest = buildAnalyticsDigest({ tasks, history, costLedger, periodDays: days });
+          const markdown = formatDigestMarkdown(digest);
+          sendJson(res, 200, { ok: true, digest, markdown });
+          return;
+        }
+
+        if (req.method === 'POST') {
+          if (rejectCrossOrigin(req, res)) 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 || {});
+          let history = [];
+          if (store.history) {
+            if (typeof store.history.values === 'function') {
+              for (const runs of store.history.values()) {
+                if (Array.isArray(runs)) history.push(...runs);
+              }
+            } else if (typeof store.history === 'object') {
+              for (const runs of Object.values(store.history)) {
+                if (Array.isArray(runs)) history.push(...runs);
+              }
+            }
+          }
+          const costLedger = store.costLedger || [];
+          const digest = buildAnalyticsDigest({ tasks, history, costLedger, periodDays: days });
+          const settings = store.getSettings ? store.getSettings() : {};
+          const deliveryConfig = {
+            telegram: body?.telegram !== false && Boolean(settings.botToken && settings.chatId),
+            webhookUrl: body?.webhookUrl || settings.webhookUrl,
+          };
+          const channels = {
+            sendTelegram: async (text) => sendTelegramMessage({ botToken: settings.botToken, chatId: settings.chatId, text }),
+            sendWebhook: async (targetUrl, payload) => {
+              const r = await fetch(targetUrl, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(payload),
+              });
+              return { ok: r.ok, status: r.status };
+            },
+          };
+          const delivery = await sendAnalyticsDigest({ digest, channels, deliveryConfig });
+          sendJson(res, 200, { ok: true, digest, delivery });
+          return;
+        }
+
+        sendJson(res, 405, { ok: false, error: 'Method not allowed' });
+      } catch (err) {
+        sendJson(res, 500, { ok: false, error: err.message });
+      }
+    }
+  }), 'dsh-cron: /analytics');
+
   // GET /dsh-cron/recipes (#48): the built-in recipe catalog.
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',

package/lib/scheduler-execution.js

@@ -1,3 +1,4 @@
+import { recordPromptRunOutcome } from './prompt-evolver.js';
 import { evaluateAdaptiveRun, calculateNextAdaptiveState } from './adaptive.js';
 import { approvalManager } from './approval.js';
 import { globalBudgetManager } from './global-budgets.js';
@@ -513,6 +514,15 @@ export async function deliverNotifications(task, runInfo, { store, resolveSecret
 export function finishRun(scheduler, taskSnapshot, taskId, status, queuedCount, meta = {}) {
   scheduler.countRun(status);
 
+  // Track prompt version success rate outcome (#331)
+  if (taskSnapshot && taskSnapshot.prompt && (taskSnapshot.promptVersion || taskSnapshot.promptHistory)) {
+    const isSuccess = status === 'success';
+    recordPromptRunOutcome(taskSnapshot, isSuccess);
+    if (scheduler.store && typeof scheduler.store.set === 'function') {
+      scheduler.store.set(taskSnapshot);
+    }
+  }
+
   // Adaptive polling backoff (#329)
   if (taskSnapshot && taskSnapshot.adaptive && taskSnapshot.adaptive.enabled && !taskSnapshot.oneShot && taskSnapshot.status === 'active' && !scheduler.isStopped) {
     const history = scheduler.store.getHistory ? scheduler.store.getHistory(taskId, 2) : [];

package/lib/task-create.js

@@ -1,3 +1,4 @@
+import { sanitizePromptHistory } from './prompt-evolver.js';
 import { sanitizeAdaptiveConfig } from './adaptive.js';
 import { sanitizeValidators } from './validators.js';
 import { normalizeTaskType, EXTERNAL_RUNTIMES } from './runtimes.js';
@@ -33,6 +34,8 @@ export function executeCreateTask(store, scheduler, args) {
     schedule: parsed.cronPattern || args.schedule,
     scheduleText: parsed.humanText,
     prompt: args.prompt,
+    promptVersion: args.prompt ? 1 : undefined,
+    promptHistory: args.prompt ? [{ version: 1, prompt: args.prompt, note: 'Initial creation', runs: 0, successes: 0, successRate: 1.0, createdAt: Date.now(), lastRunAt: null }] : undefined,
     type: taskType,
     delivery: args.delivery || 'isolated',
     status: 'active',

package/lib/task-patch.js

@@ -1,3 +1,4 @@
+import { trackPromptEdit, sanitizePromptHistory } from './prompt-evolver.js';
 import { sanitizeAdaptiveConfig } from './adaptive.js';
 import { sanitizeValidators } from './validators.js';
 import { sanitizeFileWatch } from './task-create.js';
@@ -108,6 +109,14 @@ export function buildTaskPatch(current, body) {
   if (patch.validators !== undefined) {
     patch.validators = Array.isArray(patch.validators) ? sanitizeValidators(patch.validators) : [];
   }
+  if (patch.prompt !== undefined && current && typeof current.prompt === 'string') {
+    const edit = trackPromptEdit(current, patch.prompt, body && body.promptNote ? body.promptNote : 'Manual edit');
+    patch.prompt = edit.prompt;
+    patch.promptVersion = edit.promptVersion;
+    patch.promptHistory = edit.promptHistory;
+  } else if (patch.promptHistory !== undefined) {
+    patch.promptHistory = sanitizePromptHistory(patch.promptHistory);
+  }
   if (patch.costLimitUsd !== undefined) {
     patch.costLimitUsd = patch.costLimitUsd === null ? null : (Number(patch.costLimitUsd) > 0 ? Number(patch.costLimitUsd) : null);
   }

package/lib/task-transfer.js

@@ -81,6 +81,8 @@ export const PATCHABLE_TASK_FIELDS = [
   'joinPolicy',
   'adaptive',
   'adaptiveState',
+  'promptVersion',
+  'promptHistory',
 ];
 
 /** Fields a duplicate inherits; anything else is runtime state, not config. */

package/lib/timeline.js

@@ -0,0 +1,230 @@
+/**
+ * Visual Schedule Timeline & Cost Heatmap Engine (#332, #333)
+ *
+ * 1. 24-hour schedule projection with collision and peak concurrency detection.
+ * 2. 7x24 weekly hour-of-day cost and token burn heatmap matrix.
+ */
+
+import { Cron } from 'croner';
+
+const DAY_LABELS = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
+
+export function calculate24hTimeline({
+  tasks = [],
+  maxConcurrent = 3,
+  fromTimestamp = Date.now(),
+  hoursCount = 24,
+}) {
+  const limit = Math.max(1, Number(maxConcurrent) || 3);
+  const activeTasks = (Array.isArray(tasks) ? tasks : Object.values(tasks || {})).filter(
+    (t) => t && t.status === 'active'
+  );
+
+  const startMs = typeof fromTimestamp === 'number' ? fromTimestamp : Date.now();
+  const endMs = startMs + hoursCount * 3600000;
+
+  const buckets = Array.from({ length: hoursCount }, (_, i) => {
+    const bucketStart = startMs + i * 3600000;
+    const d = new Date(bucketStart);
+    const hourPad = String(d.getHours()).padStart(2, '0');
+    return {
+      index: i,
+      label: `${hourPad}:00`,
+      startMs: bucketStart,
+      endMs: bucketStart + 3600000,
+      runs: [],
+      count: 0,
+      isPeak: false,
+    };
+  });
+
+  let totalRuns = 0;
+
+  for (const task of activeTasks) {
+    if (task.oneShot) {
+      const runAt = Number(task.nextRunAt || task.targetTimestamp);
+      if (runAt >= startMs && runAt < endMs) {
+        const bIdx = Math.floor((runAt - startMs) / 3600000);
+        if (bIdx >= 0 && bIdx < hoursCount) {
+          buckets[bIdx].runs.push({
+            taskId: task.id,
+            title: task.title || task.id,
+            runAt,
+            durationEstMs: task.avgDuration || 2000,
+            type: task.type || 'llm',
+          });
+          totalRuns += 1;
+        }
+      }
+      continue;
+    }
+
+    if (task.schedule) {
+      try {
+        const c = new Cron(task.schedule, { timezone: task.timezone });
+        let cursor = new Date(startMs - 1);
+        // Bound to max 96 occurrences per task in 24h window
+        for (let step = 0; step < 96; step++) {
+          const nextDate = c.nextRun(cursor);
+          if (!nextDate) break;
+          const runMs = nextDate.getTime();
+          if (runMs >= endMs) break;
+
+          const bIdx = Math.floor((runMs - startMs) / 3600000);
+          if (bIdx >= 0 && bIdx < hoursCount) {
+            buckets[bIdx].runs.push({
+              taskId: task.id,
+              title: task.title || task.id,
+              runAt: runMs,
+              durationEstMs: task.avgDuration || 2000,
+              type: task.type || 'llm',
+            });
+            totalRuns += 1;
+          }
+          cursor = new Date(runMs + 1000);
+        }
+      } catch (err) {
+        // Fallback for custom or invalid cron schedules
+        const runAt = Number(task.nextRunAt);
+        if (runAt >= startMs && runAt < endMs) {
+          const bIdx = Math.floor((runAt - startMs) / 3600000);
+          if (bIdx >= 0 && bIdx < hoursCount) {
+            buckets[bIdx].runs.push({
+              taskId: task.id,
+              title: task.title || task.id,
+              runAt,
+              durationEstMs: task.avgDuration || 2000,
+              type: task.type || 'llm',
+            });
+            totalRuns += 1;
+          }
+        }
+      }
+    }
+  }
+
+  const peakHours = [];
+
+  for (const b of buckets) {
+    b.count = b.runs.length;
+    b.isPeak = b.count > limit;
+    if (b.isPeak) {
+      peakHours.push(b.label);
+    }
+  }
+
+  return {
+    fromTimestamp: startMs,
+    toTimestamp: endMs,
+    maxConcurrent: limit,
+    totalRuns,
+    peakHoursCount: peakHours.length,
+    peakHours,
+    buckets,
+  };
+}
+
+export function calculateCostHeatmap({
+  costLedger = [],
+  history = [],
+  modelFilter = null,
+  providerFilter = null,
+}) {
+  const ledger = Array.isArray(costLedger) ? costLedger : [];
+  const historyList = Array.isArray(history) ? history : [];
+
+  // Matrix: 7 rows (Mon..Sun) x 24 columns (00..23h)
+  const matrix = Array.from({ length: 7 }, (_, dIdx) =>
+    Array.from({ length: 24 }, (_, hIdx) => ({
+      day: dIdx,
+      dayLabel: DAY_LABELS[dIdx],
+      hour: hIdx,
+      hourLabel: `${String(hIdx).padStart(2, '0')}:00`,
+      tokens: 0,
+      costUsd: 0,
+      runs: 0,
+      costIntensity: 0,
+      tokenIntensity: 0,
+    }))
+  );
+
+  let totalCostUsd = 0;
+  let totalTokens = 0;
+  let totalRuns = 0;
+
+  // Aggregate costLedger
+  for (const entry of ledger) {
+    if (!entry || typeof entry.timestamp !== 'number') continue;
+    if (modelFilter && entry.model && entry.model !== modelFilter) continue;
+    if (providerFilter && entry.provider && entry.provider !== providerFilter) continue;
+
+    const d = new Date(entry.timestamp);
+    const dayOfWeek = (d.getUTCDay() + 6) % 7; // Convert Sun(0) to 6, Mon(1) to 0
+    const hour = d.getUTCHours();
+
+    if (dayOfWeek >= 0 && dayOfWeek < 7 && hour >= 0 && hour < 24) {
+      const cell = matrix[dayOfWeek][hour];
+      const cost = typeof entry.costUsd === 'number' ? entry.costUsd : 0;
+      const tokens = typeof entry.tokens === 'number' ? entry.tokens : 0;
+
+      cell.costUsd += cost;
+      cell.tokens += tokens;
+      totalCostUsd += cost;
+      totalTokens += tokens;
+    }
+  }
+
+  // Aggregate run counts from history
+  for (const r of historyList) {
+    if (!r) continue;
+    const t = r.startedAt || r.completedAt || r.timestamp;
+    if (typeof t !== 'number') continue;
+    if (modelFilter && r.model && r.model !== modelFilter) continue;
+    if (providerFilter && r.provider && r.provider !== providerFilter) continue;
+
+    const d = new Date(t);
+    const dayOfWeek = (d.getUTCDay() + 6) % 7;
+    const hour = d.getUTCHours();
+
+    if (dayOfWeek >= 0 && dayOfWeek < 7 && hour >= 0 && hour < 24) {
+      matrix[dayOfWeek][hour].runs += 1;
+      totalRuns += 1;
+    }
+  }
+
+  // Calculate maximums for intensity normalisation
+  let maxCostHour = 0;
+  let maxTokensHour = 0;
+
+  for (let d = 0; d < 7; d++) {
+    for (let h = 0; h < 24; h++) {
+      const cell = matrix[d][h];
+      cell.costUsd = Number(cell.costUsd.toFixed(4));
+      if (cell.costUsd > maxCostHour) maxCostHour = cell.costUsd;
+      if (cell.tokens > maxTokensHour) maxTokensHour = cell.tokens;
+    }
+  }
+
+  // Normalise intensity (0.0 to 1.0)
+  const costDenom = maxCostHour > 0 ? maxCostHour : 1;
+  const tokenDenom = maxTokensHour > 0 ? maxTokensHour : 1;
+
+  for (let d = 0; d < 7; d++) {
+    for (let h = 0; h < 24; h++) {
+      const cell = matrix[d][h];
+      cell.costIntensity = Number((cell.costUsd / costDenom).toFixed(3));
+      cell.tokenIntensity = Number((cell.tokens / tokenDenom).toFixed(3));
+    }
+  }
+
+  return {
+    dayLabels: DAY_LABELS,
+    hourLabels: Array.from({ length: 24 }, (_, i) => `${String(i).padStart(2, '0')}:00`),
+    matrix,
+    maxCostHour,
+    maxTokensHour,
+    totalCostUsd: Number(totalCostUsd.toFixed(4)),
+    totalTokens,
+    totalRuns,
+  };
+}

package/package.json

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