@goodandready/dsh-cron 0.2.5 → 0.2.6

package/lib/scheduler.js

@@ -1,4 +1,18 @@
 import { Cron } from 'croner';
+import { applySilentRule } from './silent-rule.js';
+import { inspectFailure } from './failure-inspector.js';
+
+/** Task types that talk to a model and can therefore use a fallback model. */
+export const AGENT_TASK_TYPES = ['llm', 'skill', 'workflow'];
+
+/** Sum two usage records, so a fallback attempt is not lost in accounting. */
+export function addUsage(a, b) {
+  return {
+    inputTokens: (a?.inputTokens || 0) + (b?.inputTokens || 0),
+    outputTokens: (a?.outputTokens || 0) + (b?.outputTokens || 0),
+    cacheReadTokens: (a?.cacheReadTokens || 0) + (b?.cacheReadTokens || 0),
+  };
+}
 
 function pad(v) {
   return String(v).padStart(2, '0');
@@ -297,44 +311,28 @@ export class TaskScheduler {
     }
   }
 
-  async runTask(taskId) {
-    const task = this.store.get(taskId);
-    if (!task) return;
-
+  /**
+   * Pre-flight guards for a run: the global concurrency throttle (#52) and the
+   * per-task overlap policy. Returns the run token to continue with, or null
+   * when this tick must not execute (the reason is already recorded).
+   */
+  beginRun(task, taskId) {
     // Global concurrency throttle (#52): a run that would exceed the limit is
     // skipped and recorded; already-running tasks are never throttled against
     // themselves.
     if (!this.running.has(taskId) && this.maxConcurrent > 0 && this.running.size >= this.maxConcurrent) {
       console.log(`[dsh-cron] Task "${task.title}" (${taskId}) skipped: concurrency limit (${this.maxConcurrent})`);
-      this.store.recordRun(taskId, {
-        at: Date.now(),
-        status: 'skipped',
-        durationMs: 0,
-        output: `Skipped: concurrency limit reached (${this.maxConcurrent} parallel runs)`,
-        error: null,
-        usage: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0 },
-        costUsd: 0,
-      });
-      return;
+      this.recordSkipped(taskId, `Skipped: concurrency limit reached (${this.maxConcurrent} parallel runs)`);
+      return null;
     }
 
     const overlapPolicy = task.overlapPolicy || 'skip';
-
-    // Check overlap with currently running task
     const active = this.running.get(taskId);
     if (active) {
       if (overlapPolicy === 'skip') {
         console.log(`[dsh-cron] Task "${task.title}" (${taskId}) is already running, skipping run (overlapPolicy: skip)`);
-        this.store.recordRun(taskId, {
-          at: Date.now(),
-          status: 'skipped',
-          durationMs: 0,
-          output: 'Skipped: the previous run is still in progress (overlapPolicy: skip)',
-          error: null,
-          usage: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0 },
-          costUsd: 0,
-        });
-        return;
+        this.recordSkipped(taskId, 'Skipped: the previous run is still in progress (overlapPolicy: skip)');
+        return null;
       }
       if (overlapPolicy === 'replace') {
         console.log(`[dsh-cron] Task "${task.title}" (${taskId}) is already running, canceling current run (overlapPolicy: replace)`);
@@ -343,73 +341,221 @@ export class TaskScheduler {
       if (overlapPolicy === 'queue') {
         console.log(`[dsh-cron] Task "${task.title}" (${taskId}) is already running, queueing next run (overlapPolicy: queue)`);
         active.queueCount = (active.queueCount || 0) + 1;
-        return;
+        return null;
       }
     }
 
     const controller = new AbortController();
-    const currentRun = {
-      controller,
-      startedAt: Date.now(),
-      queueCount: 0,
-    };
+    const currentRun = { controller, startedAt: Date.now(), queueCount: 0 };
     this.running.set(taskId, currentRun);
+    return currentRun;
+  }
 
-    const start = Date.now();
-    let status = 'success';
-    let output = '';
-    let error = null;
-    let usage = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0 };
-    let costUsd = 0;
-    let sessionId = null;
+  /** Record a run that never started, with the reason in the history entry. */
+  recordSkipped(taskId, reason) {
+    this.store.recordRun(taskId, {
+      at: Date.now(),
+      status: 'skipped',
+      durationMs: 0,
+      output: reason,
+      error: null,
+      usage: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0 },
+      costUsd: 0,
+    });
+  }
 
+  /** Run the task body once and normalise whatever the executor returned. */
+  async executeOnce(task, signal) {
+    const result = {
+      status: 'success',
+      output: '',
+      error: null,
+      usage: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0 },
+      costUsd: 0,
+      sessionId: null,
+      model: task.model || '',
+      fallback: false,
+    };
+    if (typeof this.executeFn !== 'function') return result;
     try {
-      if (typeof this.executeFn === 'function') {
-        const res = await this.executeFn(task, { signal: controller.signal });
-        if (typeof res === 'object' && res !== null) {
-          output = res.output || '';
-          usage = res.usage || usage;
-          costUsd = res.costUsd || 0;
-          sessionId = res.sessionId || null;
-        } else {
-          output = String(res || '');
-        }
-      }
-    } catch (err) {
-      error = err.message || String(err);
-      if (error.toLowerCase().includes('timed out') || error.toLowerCase().includes('timeout')) {
-        status = 'timeout';
+      const res = await this.executeFn(task, { signal });
+      if (typeof res === 'object' && res !== null) {
+        result.output = res.output || '';
+        result.usage = res.usage || result.usage;
+        result.costUsd = res.costUsd || 0;
+        result.sessionId = res.sessionId || null;
+        if (res.model) result.model = res.model;
       } else {
-        status = 'error';
-      }
-    } finally {
-      const durationMs = Date.now() - start;
-      const runInfo = {
-        at: start,
-        status,
-        durationMs,
-        output,
-        error,
-        usage,
-        costUsd,
-        sessionId,
-      };
-      try {
-        this.store.recordRun(taskId, runInfo);
-      } catch (recordErr) {
-        console.error(`[dsh-cron] failed to record the run of task ${taskId}:`, recordErr.message);
+        result.output = String(res || '');
       }
+    } catch (err) {
+      result.error = err.message || String(err);
+      const timedOut = result.error.toLowerCase().includes('timed out') || result.error.toLowerCase().includes('timeout');
+      result.status = timedOut ? 'timeout' : 'error';
+    }
+    return result;
+  }
+
+  /**
+   * Run the task, retrying once on the configured fallback model when the
+   * primary attempt failed (#45).
+   *
+   * The point is cost: a task can default to the cheap model and still finish
+   * on the strong one when the cheap model cannot do the job. Exactly one
+   * fallback attempt is made — the ordinary retry backoff still applies
+   * afterwards — and usage and cost of BOTH attempts are summed, because both
+   * were really spent.
+   */
+  async executeWithFallback(task, signal) {
+    const primary = await this.executeOnce(task, signal);
+    if (!this.shouldUseFallback(task, primary)) return primary;
+
+    const fallbackTask = {
+      ...task,
+      provider: task.fallbackProvider || task.provider,
+      model: task.fallbackModel,
+    };
+    console.log(`[dsh-cron] task "${task.title}" failed on ${task.model || 'the default model'}, retrying once on ${task.fallbackModel}`);
+    const secondary = await this.executeOnce(fallbackTask, signal);
+    return {
+      ...secondary,
+      fallback: true,
+      usage: addUsage(primary.usage, secondary.usage),
+      costUsd: Number((primary.costUsd + secondary.costUsd).toFixed(6)),
+      primaryModel: task.model || '',
+    };
+  }
+
+  /** Only agent-mediated types use a model, and only a failed run falls back. */
+  shouldUseFallback(task, outcome) {
+    if (!task || !task.fallbackModel) return false;
+    if (!AGENT_TASK_TYPES.includes(task.type || 'llm')) return false;
+    return outcome.status === 'error' || outcome.status === 'timeout';
+  }
 
-      // Clean up running map
-      const finishedRun = this.running.get(taskId);
-      if (finishedRun === currentRun) {
-        this.running.delete(taskId);
-      }
 
-      const queuedCount = finishedRun?.queueCount || 0;
+  async runTask(taskId) {
+    const task = this.store.get(taskId);
+    if (!task) return;
+
+    const currentRun = this.beginRun(task, taskId);
+    if (currentRun === null) return;
+
+    const start = Date.now();
+    const outcome = await this.executeWithFallback(task, currentRun.controller.signal);
+    await this.completeRun(task, taskId, currentRun, outcome, start);
+  }
+
+  /**
+   * Record the run, release the run slot and hand the result to delivery and
+   * bookkeeping. Kept separate from runTask so the run flow reads in steps.
+   */
+  async completeRun(task, taskId, currentRun, outcome, start) {
+    const runInfo = {
+      at: start,
+      status: outcome.status,
+      durationMs: Date.now() - start,
+      output: outcome.output,
+      error: outcome.error,
+      usage: outcome.usage,
+      costUsd: outcome.costUsd,
+      sessionId: outcome.sessionId,
+      // #45: which model actually produced this result, and whether the run
+      // only finished thanks to the configured fallback.
+      model: outcome.model || task.model || '',
+      fallback: Boolean(outcome.fallback),
+    };
+
+    // #43/#44 decide before the run is recorded, so the single history entry
+    // already carries the diagnosis and the silence verdict.
+    const silent = await this.applyModelAssists(task, runInfo);
+
+    try {
+      this.store.recordRun(taskId, runInfo);
+    } catch (recordErr) {
+      console.error(`[dsh-cron] failed to record the run of task ${taskId}:`, recordErr.message);
+    }
+
+    // Release the slot before delivery so a long notification never blocks the
+    // next tick of this task.
+    const finishedRun = this.running.get(taskId);
+    if (finishedRun === currentRun) this.running.delete(taskId);
+    const queuedCount = finishedRun?.queueCount || 0;
+
+    if (!silent.skipped) await this.deliverNotifications(task, runInfo);
+    this.finishRun(task, taskId, outcome.status, queuedCount);
+  }
+
+  /**
+   * Run the model-assisted steps for a finished run: diagnose a failure (#43)
+   * and decide whether a successful run should stay silent (#44). Both are
+   * fail-open and write their outcome into `runInfo`.
+   */
+  async applyModelAssists(task, runInfo) {
+    const inspection = await this.inspectFailureRun(task, runInfo);
+    if (inspection.inspected) {
+      runInfo.diagnosis = inspection.diagnosis;
+      runInfo.suggestion = inspection.suggestion;
+      runInfo.confidence = inspection.confidence;
+      console.log(`[dsh-cron] task "${task.title}" failure diagnosed (${inspection.confidence}): ${inspection.diagnosis}`);
+    } else if (inspection.error && task.inspectOnFailure) {
+      console.warn(`[dsh-cron] failure inspection for "${task.title}" not applied: ${inspection.error}`);
+    }
+
+    const silent = await this.applySilentRuleToRun(task, runInfo);
+    if (silent.skipped) {
+      runInfo.silentSkip = true;
+      runInfo.silentReason = silent.reason;
+      console.log(`[dsh-cron] task "${task.title}" stayed silent by rule: ${silent.reason || 'no reason given'}`);
+    } else if (silent.verdictError) {
+      console.warn(`[dsh-cron] silent rule for "${task.title}" not applied: ${silent.verdictError}`);
+    }
+    return silent;
+  }
+
+  /** Ask the model to diagnose a failed run (#43). Never throws. */
+  async inspectFailureRun(task, runInfo) {
+    if (typeof this.askModel !== 'function') return { inspected: false, error: 'no model is available' };
+    const settings = this.readSettings();
+    try {
+      return await inspectFailure({
+        task,
+        runInfo,
+        ask: this.askModel,
+        preferredModel: String(settings.inspectorModel || ''),
+        timeoutMs: this.inspectTimeoutMs || 25000,
+      });
+    } catch (err) {
+      return { inspected: false, error: err.message };
+    }
+  }
+
+  /** Settings snapshot, or an empty object when the store has none. */
+  readSettings() {
+    try {
+      return typeof this.store.getSettings === 'function' ? this.store.getSettings() : {};
+    } catch {
+      return {};
+    }
+  }
 
-      await this.deliverNotifications(task, runInfo);
-      this.finishRun(task, taskId, status, queuedCount);
+  /**
+   * Ask the silent rule whether this run should be delivered (#44).
+   * Never throws: any problem means "deliver".
+   */
+  async applySilentRuleToRun(task, runInfo) {
+    if (typeof this.askModel !== 'function') return { skipped: false, reason: '' };
+    const preferredModel = String(this.readSettings().silentRuleModel || '');
+    try {
+      return await applySilentRule({
+        task,
+        runInfo,
+        ask: this.askModel,
+        preferredModel,
+        timeoutMs: this.silentRuleTimeoutMs || 20000,
+      });
+    } catch (err) {
+      return { skipped: false, reason: '', verdictError: err.message };
     }
   }
 

package/lib/silent-rule.js

@@ -0,0 +1,100 @@
+/**
+ * The "silent rule" (#44): a plain-language condition that decides whether a
+ * successful run is worth alerting about.
+ *
+ * A script that runs every 30 minutes usually produces nothing interesting, and
+ * `onlyOnFailure` cannot tell "the disk is at 12%" from "the disk is at 96%".
+ * The rule is written by the user in words; a cheap model call turns it into a
+ * yes/no verdict with a reason.
+ *
+ * Fail-open by design: no rule, no model, a broken call or an unusable answer all
+ * mean "deliver the report". Silence is only ever produced by an explicit
+ * verdict.
+ */
+
+import { askModel, parseJsonAnswer, resolveAskTarget } from './llm-ask.js';
+
+/** Task types whose runs produce output a rule can judge. */
+export const SILENT_RULE_TASK_TYPES = ['script', 'node', 'python', 'http'];
+
+export function supportsSilentRule(task) {
+  return SILENT_RULE_TASK_TYPES.includes(String(task && task.type ? task.type : 'script'));
+}
+
+const SYSTEM_PROMPT = [
+  'You decide whether a monitoring job should notify its owner.',
+  'Answer with a single JSON object and nothing else:',
+  '{"notify": true|false, "reason": "short explanation"}',
+  'Be conservative: when the output shows a problem, a warning, an error or anything uncertain, notify.',
+  'Only stay silent when the output clearly matches the condition for silence.',
+].join(' ');
+
+export function buildSilentRulePrompt(task, runInfo) {
+  const output = String((runInfo && runInfo.output) || '').slice(0, 4000);
+  return [
+    `Task: ${task.title || 'scheduled task'} (type: ${task.type || 'script'})`,
+    `Schedule: ${task.scheduleText || task.schedule || ''}`,
+    `Exit status: ${(runInfo && runInfo.status) || 'success'}`,
+    '',
+    'Condition for staying silent:',
+    String(task.silentRule || '').trim(),
+    '',
+    'Output of the run:',
+    '```',
+    output || '(no output)',
+    '```',
+  ].join('\n');
+}
+
+/** Turn a model answer into a verdict; anything unusable means "notify". */
+export function readVerdict(text) {
+  const parsed = parseJsonAnswer(text);
+  if (!parsed || typeof parsed.notify !== 'boolean') {
+    return { ok: false, error: 'the model did not answer with a notify verdict' };
+  }
+  return { ok: true, notify: parsed.notify, reason: String(parsed.reason || '').slice(0, 500) };
+}
+
+/**
+ * Decide whether a finished run should be delivered.
+ * Returns `{ skipped, reason, verdictError? }`; `skipped` is true only after an
+ * explicit "stay silent" verdict.
+ */
+export async function applySilentRule({ task, runInfo, ask, preferredModel, timeoutMs }) {
+  if (!task || !task.silentRule || String(task.silentRule).trim() === '') {
+    return { skipped: false, reason: '' };
+  }
+  if ((runInfo && runInfo.status) !== 'success') {
+    return { skipped: false, reason: '', note: 'the rule only judges successful runs' };
+  }
+  if (typeof ask !== 'function') {
+    return { skipped: false, reason: '', verdictError: 'no model is available for the silent rule' };
+  }
+  try {
+    const result = await ask({
+      task,
+      prompt: buildSilentRulePrompt(task, runInfo),
+      system: SYSTEM_PROMPT,
+      preferredModel,
+      maxTokens: 200,
+      timeoutMs,
+    });
+    if (!result || !result.ok) {
+      return { skipped: false, reason: '', verdictError: (result && result.error) || 'the model call failed' };
+    }
+    const verdict = readVerdict(result.text);
+    if (!verdict.ok) return { skipped: false, reason: '', verdictError: verdict.error };
+    return { skipped: verdict.notify === false, reason: verdict.reason };
+  } catch (err) {
+    // The rule never decides by failing: a thrown model call means "deliver".
+    return { skipped: false, reason: '', verdictError: (err && err.message) || String(err) };
+  }
+}
+
+/** Ask helper bound to a context, used by the scheduler. */
+export function makeAsk(ctx) {
+  return async ({ prompt, system, preferredModel, maxTokens, timeoutMs, task }) => {
+    const target = resolveAskTarget(ctx, task || {}, preferredModel);
+    return askModel(ctx, { ...target, prompt, system, maxTokens, timeoutMs });
+  };
+}

package/lib/store.js

@@ -283,6 +283,17 @@ export class TaskStore {
       usage,
       costUsd,
       sessionId: runInfo.sessionId || null,
+      // #45: which model produced the run, and whether it only finished thanks
+      // to the configured fallback.
+      model: runInfo.model || '',
+      fallback: Boolean(runInfo.fallback),
+      // #44: this run was suppressed by its silent rule, with the reason.
+      silentSkip: Boolean(runInfo.silentSkip),
+      silentReason: runInfo.silentSkip ? String(runInfo.silentReason || '').slice(0, 500) : '',
+      // #43: the failure diagnosis and the prompt change it proposes.
+      diagnosis: runInfo.diagnosis ? String(runInfo.diagnosis).slice(0, 1000) : '',
+      suggestion: runInfo.suggestion ? String(runInfo.suggestion).slice(0, 2000) : '',
+      confidence: runInfo.confidence || '',
     });
     if (runs.length > 50) runs.length = 50;
     this.history.set(id, runs);

package/lib/task-patch.js

@@ -0,0 +1,81 @@
+/**
+ * Partial task updates, shared by the HTTP PATCH route and the cron_update_task
+ * tool (#49).
+ *
+ * One implementation keeps the whitelist, the type validation, the schedule
+ * re-parse and the re-scheduling identical on both surfaces; the HTTP route adds
+ * its own cross-origin and confirmation checks on top, while an agent calling the
+ * tool acts on the user's explicit instruction.
+ */
+
+import { parseScheduleExpression } from './scheduler.js';
+import { normalizeTaskType, CODE_EXECUTING_TYPES } from './runtimes.js';
+import { PATCHABLE_TASK_FIELDS, validateTaskType } from './task-transfer.js';
+import { pickPatchableFields } from './http-utils.js';
+
+/** True when a patch changes a task into a type that executes code. */
+export function isCodeTypeSwitch(current, nextType) {
+  if (!current || nextType === undefined) return false;
+  const target = normalizeTaskType(nextType);
+  return CODE_EXECUTING_TYPES.includes(target) && !CODE_EXECUTING_TYPES.includes(current.type);
+}
+
+/**
+ * Normalise a patch: whitelist the fields, resolve the type, re-parse the
+ * schedule so cron patterns and one-shot markers stay consistent.
+ * Returns `{ ok: false, error }` when the merged task would be invalid.
+ */
+export function buildTaskPatch(current, body) {
+  const patch = pickPatchableFields(body || {}, PATCHABLE_TASK_FIELDS);
+  if (patch.type !== undefined) {
+    patch.type = normalizeTaskType(patch.type);
+    const typeError = validateTaskType(patch.type, { ...current, ...patch });
+    if (typeError) return { ok: false, error: typeError };
+  }
+  if (patch.schedule !== undefined) {
+    // An empty schedule would leave an armed task that can never fire.
+    if (!String(patch.schedule).trim()) return { ok: false, error: 'Schedule cannot be empty' };
+    const parsed = parseScheduleExpression(patch.schedule);
+    patch.schedule = parsed.cronPattern || patch.schedule;
+    patch.scheduleText = (body && body.scheduleText) || parsed.humanText;
+    patch.oneShot = Boolean(parsed.isOneShot || (body && body.oneShot));
+  }
+  return { ok: true, patch };
+}
+
+/**
+ * Apply a patch to a stored task and re-arm or pause it.
+ *
+ * Switching a task into a code-executing type is the one change that turns a
+ * harmless schedule into code execution, so it needs explicit confirmation on
+ * EVERY surface: the HTTP route passes the result of its confirmation header,
+ * and the tool exposes its own switch. A prose request in a tool description is
+ * not a gate, so the refusal lives here instead.
+ *
+ * Returns `{ ok: true, task }`, `{ ok: false, error }`, or
+ * `{ ok: false, needsConfirmation: true, error }` for that switch.
+ */
+export function applyTaskPatch({ store, scheduler, id, body, allowCodeSwitch = false }) {
+  const current = store.get(id);
+  if (!current) return { ok: false, notFound: true, error: 'Task not found' };
+  if (isCodeTypeSwitch(current, body && body.type) && allowCodeSwitch !== true) {
+    return {
+      ok: false,
+      needsConfirmation: true,
+      error: `Switching this task to ${normalizeTaskType(body.type)} makes it execute code; confirm that explicitly and retry`,
+    };
+  }
+  const built = buildTaskPatch(current, body);
+  if (!built.ok) return built;
+  const task = store.set({ ...current, ...built.patch, id });
+  if (task.status === 'active') scheduler.scheduleTask(task);
+  else scheduler.pauseTask(id);
+  return { ok: true, task, patch: built.patch };
+}
+
+/** Human-readable summary of what changed, for tool output and logs. */
+export function describeTaskPatch(task, patch) {
+  const keys = Object.keys(patch || {}).filter((k) => k !== 'scheduleText');
+  if (!keys.length) return 'no changes';
+  return keys.map((key) => `${key}=${JSON.stringify(patch[key])}`).join(', ');
+}

package/lib/task-transfer.js

@@ -21,6 +21,10 @@ export const PATCHABLE_TASK_FIELDS = [
   'delivery',
   'provider',
   'model',
+  'fallbackProvider',
+  'fallbackModel',
+  'silentRule',
+  'inspectOnFailure',
   'timezone',
   'misfirePolicy',
   'maxRetries',

package/lib/templates.js

@@ -17,6 +17,8 @@ export const TEMPLATE_VARIABLES = [
   'time',
   'tokens',
   'cost',
+  'model',
+  'diagnosis',
 ];
 
 export const DEFAULT_PLAIN_TEMPLATE = '⏰ {title}\nStatus: {status}\nSchedule: {schedule}\nDuration: {duration}\n{output}';
@@ -60,6 +62,8 @@ export function buildTemplateVars(task, runInfo = {}) {
     time: new Date(runInfo.at || Date.now()).toISOString(),
     tokens: String(tokens),
     cost: `$${Number(runInfo.costUsd || 0).toFixed(4)}`,
+    model: runInfo.model || '',
+    diagnosis: truncateText(runInfo.diagnosis || ''),
   };
 }
 

package/package.json

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