@goodandready/dsh-cron 0.3.1 → 0.3.3

package/lib/dag.js

@@ -0,0 +1,330 @@
+/**
+ * Directed Acyclic Graph (DAG) Engine for Chained Tasks (#328, #334)
+ * Provides cycle detection, topological sorting, dependency resolution,
+ * and graph visualization modeling for multi-step task workflows.
+ */
+
+/**
+ * Normalizes dependency specifications into an array of string task IDs.
+ * Accepts arrays, comma/space separated strings, or single task IDs.
+ *
+ * @param {string|string[]|undefined|null} deps
+ * @returns {string[]} Deduplicated array of valid task IDs
+ */
+export function sanitizeDependsOn(deps) {
+  if (!deps) return [];
+  let rawList = [];
+  if (Array.isArray(deps)) {
+    rawList = deps;
+  } else if (typeof deps === 'string') {
+    rawList = deps.split(/[,;\s]+/);
+  }
+  const result = [];
+  const seen = new Set();
+  for (const item of rawList) {
+    if (typeof item !== 'string') continue;
+    const trimmed = item.trim();
+    if (trimmed && !seen.has(trimmed)) {
+      seen.add(trimmed);
+      result.push(trimmed);
+    }
+  }
+  return result;
+}
+
+/**
+ * Validates join policy string.
+ *
+ * @param {string|undefined} policy
+ * @returns {'all_success'|'any_success'}
+ */
+export function sanitizeJoinPolicy(policy) {
+  if (policy === 'any_success') return 'any_success';
+  return 'all_success';
+}
+
+/**
+ * Parses and returns a list of target task IDs for chaining (onSuccess / onFailure).
+ * Supports single ID, comma-separated IDs, or arrays of IDs.
+ *
+ * @param {string|string[]|undefined|null} target
+ * @returns {string[]}
+ */
+export function parseChainTargets(target) {
+  if (!target) return [];
+  if (Array.isArray(target)) {
+    return target.map((t) => String(t || '').trim()).filter(Boolean);
+  }
+  if (typeof target === 'string') {
+    return target.split(/[,;\s]+/).map((t) => t.trim()).filter(Boolean);
+  }
+  return [];
+}
+
+/**
+ * Validates that adding or updating a task does not introduce cyclic dependencies.
+ * Analyzes both `dependsOn` relationships and `onSuccess` chain links.
+ *
+ * @param {Array<Object>|Map<string, Object>|Object} allTasks All current tasks
+ * @param {Object} [pendingTask] Task being created or updated
+ * @returns {{ ok: boolean, error?: string, cycle?: string[] }}
+ */
+export function validateDAG(allTasks, pendingTask = null) {
+  // Build task dictionary
+  const taskMap = new Map();
+  if (Array.isArray(allTasks)) {
+    for (const t of allTasks) {
+      if (t && t.id) taskMap.set(t.id, t);
+    }
+  } else if (allTasks instanceof Map) {
+    for (const [k, v] of allTasks.entries()) {
+      if (v && v.id) taskMap.set(v.id, v);
+    }
+  } else if (allTasks && typeof allTasks === 'object') {
+    for (const k of Object.keys(allTasks)) {
+      const t = allTasks[k];
+      if (t && t.id) taskMap.set(t.id, t);
+    }
+  }
+
+  // Merge pending task if provided
+  if (pendingTask && pendingTask.id) {
+    taskMap.set(pendingTask.id, { ...(taskMap.get(pendingTask.id) || {}), ...pendingTask });
+  }
+
+  // Self-dependency check
+  for (const [id, task] of taskMap.entries()) {
+    const deps = sanitizeDependsOn(task.dependsOn);
+    if (deps.includes(id)) {
+      return { ok: false, error: `Task "${task.title || id}" cannot depend on itself`, cycle: [id, id] };
+    }
+    const chainTargets = parseChainTargets(task.onSuccess);
+    if (chainTargets.includes(id)) {
+      return { ok: false, error: `Task "${task.title || id}" cannot trigger itself as next step`, cycle: [id, id] };
+    }
+  }
+
+  // Construct adjacency list: Edge from U to V means U must complete before V runs.
+  // Sources of edges:
+  // 1) dependsOn: If V depends on U, then U -> V
+  // 2) onSuccess: If U has onSuccess V, then U -> V
+  const adj = new Map();
+  for (const id of taskMap.keys()) {
+    adj.set(id, new Set());
+  }
+
+  for (const [id, task] of taskMap.entries()) {
+    // 1) dependsOn (deps -> id)
+    const deps = sanitizeDependsOn(task.dependsOn);
+    for (const depId of deps) {
+      if (!adj.has(depId)) adj.set(depId, new Set());
+      adj.get(depId).add(id);
+    }
+
+    // 2) onSuccess (id -> target)
+    const targets = parseChainTargets(task.onSuccess);
+    for (const targetId of targets) {
+      if (!adj.has(id)) adj.set(id, new Set());
+      adj.get(id).add(targetId);
+    }
+  }
+
+  // DFS Cycle Detection (3 colors: 0=unvisited, 1=visiting, 2=visited)
+  const state = new Map(); // id -> 0 | 1 | 2
+  const path = [];
+
+  for (const node of adj.keys()) {
+    state.set(node, 0);
+  }
+
+  function dfs(u) {
+    state.set(u, 1);
+    path.push(u);
+
+    const neighbors = adj.get(u) || new Set();
+    for (const v of neighbors) {
+      const vState = state.get(v) || 0;
+      if (vState === 1) {
+        // Cycle detected
+        const cycleStartIndex = path.indexOf(v);
+        const cyclePath = path.slice(cycleStartIndex).concat(v);
+        return { ok: false, error: `Cyclic dependency detected: ${cyclePath.join(' -> ')}`, cycle: cyclePath };
+      }
+      if (vState === 0) {
+        const res = dfs(v);
+        if (!res.ok) return res;
+      }
+    }
+
+    path.pop();
+    state.set(u, 2);
+    return { ok: true };
+  }
+
+  for (const node of adj.keys()) {
+    if ((state.get(node) || 0) === 0) {
+      const res = dfs(node);
+      if (!res.ok) return res;
+    }
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Returns topological sort of task IDs or throws error if cycle exists.
+ *
+ * @param {Array<Object>|Map<string, Object>} tasks
+ * @returns {string[]} Ordered task IDs
+ */
+export function topologicalSort(tasks) {
+  const check = validateDAG(tasks);
+  if (!check.ok) {
+    throw new Error(check.error || 'Cyclic dependency in task DAG');
+  }
+
+  const taskMap = new Map();
+  if (Array.isArray(tasks)) {
+    for (const t of tasks) if (t?.id) taskMap.set(t.id, t);
+  } else if (tasks instanceof Map) {
+    for (const [k, v] of tasks.entries()) if (v?.id) taskMap.set(v.id, v);
+  }
+
+  // In-degree calculation
+  const inDegree = new Map();
+  const adj = new Map();
+  for (const id of taskMap.keys()) {
+    inDegree.set(id, 0);
+    adj.set(id, new Set());
+  }
+
+  for (const [id, task] of taskMap.entries()) {
+    const deps = sanitizeDependsOn(task.dependsOn);
+    for (const depId of deps) {
+      if (taskMap.has(depId)) {
+        adj.get(depId).add(id);
+        inDegree.set(id, (inDegree.get(id) || 0) + 1);
+      }
+    }
+    const targets = parseChainTargets(task.onSuccess);
+    for (const targetId of targets) {
+      if (taskMap.has(targetId)) {
+        adj.get(id).add(targetId);
+        inDegree.set(targetId, (inDegree.get(targetId) || 0) + 1);
+      }
+    }
+  }
+
+  const queue = [];
+  for (const [id, deg] of inDegree.entries()) {
+    if (deg === 0) queue.push(id);
+  }
+
+  const order = [];
+  while (queue.length > 0) {
+    const u = queue.shift();
+    order.push(u);
+    for (const v of adj.get(u) || []) {
+      const newDeg = (inDegree.get(v) || 0) - 1;
+      inDegree.set(v, newDeg);
+      if (newDeg === 0) queue.push(v);
+    }
+  }
+
+  return order;
+}
+
+/**
+ * Builds a visual graph model (nodes and edges) for UI rendering (#334).
+ *
+ * @param {Array<Object>} tasks All relevant tasks
+ * @param {Array<Object>} [snapshots] Checkpoints for the chain run
+ * @param {string} [focusTaskId] Task ID to center or highlight
+ * @returns {{ nodes: Array<Object>, edges: Array<Object>, hasFailure: boolean }}
+ */
+export function buildTaskGraphModel(tasks = [], snapshots = [], focusTaskId = null) {
+  const taskMap = new Map();
+  for (const t of tasks) {
+    if (t?.id) taskMap.set(t.id, t);
+  }
+
+  const snapshotMap = new Map();
+  for (const s of snapshots) {
+    if (s?.stepTaskId) snapshotMap.set(s.stepTaskId, s);
+  }
+
+  const nodes = [];
+  const edges = [];
+  let hasFailure = false;
+
+  for (const [id, task] of taskMap.entries()) {
+    const snap = snapshotMap.get(id);
+    let nodeStatus = 'pending';
+    let durationMs = 0;
+    let outputSnippet = '';
+    let retryCount = 0;
+
+    if (snap) {
+      nodeStatus = snap.status === 'completed' || snap.status === 'success' ? 'success' : 'failed';
+      durationMs = snap.durationMs || 0;
+      retryCount = snap.retryCount || 0;
+      if (snap.output) {
+        outputSnippet = String(snap.output).slice(0, 200);
+      }
+      if (nodeStatus === 'failed') {
+        hasFailure = true;
+      }
+    } else if (task.status === 'running') {
+      nodeStatus = 'running';
+    }
+
+    nodes.push({
+      id,
+      title: task.title || id,
+      type: task.type || 'prompt',
+      status: nodeStatus,
+      durationMs,
+      retryCount,
+      outputSnippet,
+      isFocus: Boolean(focusTaskId && id === focusTaskId),
+      isRetryable: nodeStatus === 'failed',
+      dependsOn: sanitizeDependsOn(task.dependsOn),
+      joinPolicy: sanitizeJoinPolicy(task.joinPolicy),
+    });
+
+    // Edges from dependsOn
+    const deps = sanitizeDependsOn(task.dependsOn);
+    for (const depId of deps) {
+      edges.push({
+        from: depId,
+        to: id,
+        type: 'dependsOn',
+        label: task.joinPolicy === 'any_success' ? 'join:any' : 'join:all',
+      });
+    }
+
+    // Edges from onSuccess
+    const targets = parseChainTargets(task.onSuccess);
+    for (const targetId of targets) {
+      edges.push({
+        from: id,
+        to: targetId,
+        type: 'onSuccess',
+        label: 'onSuccess',
+      });
+    }
+
+    // Edges from onFailure
+    const failTargets = parseChainTargets(task.onFailure);
+    for (const failId of failTargets) {
+      edges.push({
+        from: id,
+        to: failId,
+        type: 'onFailure',
+        label: 'onFailure',
+      });
+    }
+  }
+
+  return { nodes, edges, hasFailure };
+}

package/lib/log-streamer.js

@@ -0,0 +1,153 @@
+/**
+ * Real-time Task Execution Log Streaming (SSE) (#336)
+ *
+ * Keeps an in-memory Ring Buffer of output chunks for active tasks and
+ * broadcasts them to connected Server-Sent Events (SSE) clients.
+ */
+
+import { EventEmitter } from 'node:events';
+import { logger } from './logger.js';
+
+const MAX_BUFFER_LINES = 500;
+const RETENTION_MS = 60000; // retain logs for 60s after completion for late inspectors
+
+export class LogStreamer extends EventEmitter {
+  constructor() {
+    super();
+    this.streams = new Map(); // taskId -> StreamEntry
+  }
+
+  startStream(taskId, runId) {
+    if (!taskId) return;
+    const existing = this.streams.get(taskId);
+    if (existing && existing.cleanupTimer) {
+      clearTimeout(existing.cleanupTimer);
+    }
+    const entry = {
+      taskId,
+      runId: runId || `run_${Date.now()}`,
+      startTime: Date.now(),
+      buffer: [],
+      subscribers: new Set(),
+      completed: false,
+      outcome: null,
+      cleanupTimer: null,
+    };
+    this.streams.set(taskId, entry);
+    this.emit('start', { taskId, runId: entry.runId });
+    return entry;
+  }
+
+  appendLog(taskId, text, streamType = 'stdout') {
+    if (!taskId || text === undefined || text === null) return;
+    const entry = this.streams.get(taskId);
+    if (!entry) return;
+
+    const chunkStr = String(text);
+    const item = {
+      chunk: chunkStr,
+      stream: streamType,
+      ts: Date.now(),
+    };
+
+    entry.buffer.push(item);
+    if (entry.buffer.length > MAX_BUFFER_LINES) {
+      entry.buffer.shift();
+    }
+
+    const ssePayload = `event: log\ndata: ${JSON.stringify(item)}\n\n`;
+    for (const res of entry.subscribers) {
+      try {
+        res.write(ssePayload);
+      } catch (err) {
+        entry.subscribers.delete(res);
+      }
+    }
+  }
+
+  completeStream(taskId, outcome = {}) {
+    if (!taskId) return;
+    const entry = this.streams.get(taskId);
+    if (!entry) return;
+
+    entry.completed = true;
+    entry.outcome = {
+      status: outcome.status || 'success',
+      durationMs: Date.now() - entry.startTime,
+      error: outcome.error || null,
+      exitCode: outcome.exitCode !== undefined ? outcome.exitCode : (outcome.status === 'error' ? 1 : 0),
+    };
+
+    const ssePayload = `event: complete\ndata: ${JSON.stringify(entry.outcome)}\n\n`;
+    for (const res of entry.subscribers) {
+      try {
+        res.write(ssePayload);
+        res.end();
+      } catch (err) {
+        // client closed
+      }
+    }
+    entry.subscribers.clear();
+
+    // Schedule cleanup of memory after retention period
+    entry.cleanupTimer = setTimeout(() => {
+      this.streams.delete(taskId);
+    }, RETENTION_MS);
+    if (entry.cleanupTimer.unref) entry.cleanupTimer.unref();
+  }
+
+  getStream(taskId) {
+    return this.streams.get(taskId) || null;
+  }
+
+  handleSseRequest(taskId, req, res) {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream; charset=utf-8',
+      'Cache-Control': 'no-cache, no-transform',
+      'Connection': 'keep-alive',
+      'X-Accel-Buffering': 'no',
+      'Access-Control-Allow-Origin': '*',
+    });
+
+    const entry = this.streams.get(taskId);
+
+    // Initial event with current state and buffered logs
+    const initData = {
+      taskId,
+      runId: entry?.runId || null,
+      status: entry ? (entry.completed ? 'completed' : 'running') : 'idle',
+      bufferedLogs: entry?.buffer || [],
+    };
+    res.write(`event: init\ndata: ${JSON.stringify(initData)}\n\n`);
+
+    if (!entry || entry.completed) {
+      // Not running or already completed
+      if (entry?.completed) {
+        res.write(`event: complete\ndata: ${JSON.stringify(entry.outcome)}\n\n`);
+      }
+      res.end();
+      return;
+    }
+
+    // Subscribe to live events
+    entry.subscribers.add(res);
+
+    // Keepalive ping every 15 seconds
+    const pingTimer = setInterval(() => {
+      try {
+        res.write(': keepalive\n\n');
+      } catch (e) {
+        clearInterval(pingTimer);
+        entry.subscribers.delete(res);
+      }
+    }, 15000);
+    if (pingTimer.unref) pingTimer.unref();
+
+    req.on('close', () => {
+      clearInterval(pingTimer);
+      entry.subscribers.delete(res);
+    });
+  }
+}
+
+export const logStreamer = new LogStreamer();

package/lib/prompt-interpolation.js

@@ -30,7 +30,7 @@ export function buildPromptContext(task = {}, options = {}) {
   const fileSize = options.fileSize != null ? String(options.fileSize) : '';
   const fileEvent = options.fileEvent != null ? String(options.fileEvent) : '';
 
-  return {
+  const ctx = {
     // Chaining context
     'prev.output': prevOutput,
     'prev_output': prevOutput,
@@ -72,17 +72,41 @@ export function buildPromptContext(task = {}, options = {}) {
     'task.title': task.title || '',
     'task_title': task.title || '',
   };
+
+  // DAG / Fan-In predecessor outputs (#328)
+  if (options.prevOutputs && typeof options.prevOutputs === 'object') {
+    for (const [k, v] of Object.entries(options.prevOutputs)) {
+      const valStr = v != null ? String(v) : '';
+      ctx[`prevOutputs.${k}`] = valStr;
+      ctx[`outputs.${k}`] = valStr;
+      ctx[`step.${k}.output`] = valStr;
+      ctx[`prevOutputs['${k}']`] = valStr;
+      ctx[`prevOutputs["${k}"]`] = valStr;
+    }
+  }
+
+  return ctx;
 }
 
 /**
  * Replace {{var}} or {var} placeholders with values from context.
- * Supports dot notation like {{prev.output}}. Unknown variables are left untouched.
+ * Supports dot notation like {{prev.output}} and bracket notation like {{prevOutputs['step1']}}.
  */
 export function interpolateTaskPrompt(text, context = {}) {
   if (typeof text !== 'string') return text;
   if (!text) return '';
 
-  return text.replace(/\{\{([a-zA-Z0-9_.]+)\}\}/g, (match, varName) => {
+  // 1. Bracket notation: {{prevOutputs['step1']}} or {prevOutputs['step1']} or with double quotes
+  let result = text.replace(/\{\{?prevOutputs\[['"]([^'"]+)['"]\]\}?\}/g, (match, stepId) => {
+    const key = `prevOutputs.${stepId}`;
+    if (Object.prototype.hasOwnProperty.call(context, key)) {
+      return context[key];
+    }
+    return match;
+  });
+
+  // 2. 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];
       return val == null ? '' : String(val);
@@ -95,6 +119,8 @@ export function interpolateTaskPrompt(text, context = {}) {
     }
     return match;
   });
+
+  return result;
 }
 
 /**

package/lib/routes.js

@@ -10,6 +10,7 @@ import { recipesByCategory } from './recipes.js';
 import { sendTelegramMessage, createTelegramTaskKeyboard } from './telegram.js';
 import { createKanbanCard } from './integrations.js';
 import { sanitizeSettingsPayload, applySettingsToScope } from './settings.js';
+import { buildTaskGraphModel } from './dag.js';
 
 export function registerRoutes(ctx, { store, scheduler, recommendations }) {
   // handler per route family; registered WITHOUT the trailing slash (#96)
@@ -220,6 +221,27 @@ export function registerRoutes(ctx, { store, scheduler, recommendations }) {
 export async function handleChainRoutes(store, scheduler, req, res) {
   if (req.method === 'POST' && rejectCrossOrigin(req, res)) return;
   const url = new URL(req.url, 'http://localhost');
+
+  // GET /dsh-cron/chains/:chainRunId (#334)
+  const getMatch = url.pathname.match(/^\/dsh-cron\/chains\/([^\/]+)$/);
+  if (getMatch && req.method === 'GET') {
+    const chainRunId = getMatch[1];
+    const snapshots = store.chainCheckpointManager ? store.chainCheckpointManager.getChainSnapshots(chainRunId) : [];
+    const relevantTasks = [];
+    const stepIds = new Set(snapshots.map((s) => s.stepTaskId));
+    if (store.tasks) {
+      for (const t of Object.values(store.tasks)) {
+        if (t && (stepIds.has(t.id) || t.onSuccess || t.onFailure || t.dependsOn)) {
+          relevantTasks.push(t);
+        }
+      }
+    }
+    const graph = buildTaskGraphModel(relevantTasks, snapshots);
+    sendJson(res, 200, { ok: true, chainRunId, snapshots, graph });
+    return;
+  }
+
+  // POST /dsh-cron/chains/:chainRunId/retry-from/:stepTaskId (#319, #328)
   const m = url.pathname.match(/^\/dsh-cron\/chains\/([^\/]+)\/retry-from\/([^\/]+)$/);
   if (!m) {
     sendJson(res, 404, { ok: false, error: 'Route not found' });

package/lib/runner-external.js

@@ -1,3 +1,4 @@
+import { logStreamer } from './log-streamer.js';
 import { logger } from './logger.js';
 import { bestEffort } from './best-effort.js';
 import {
@@ -59,6 +60,10 @@ export function isTransientError(errOrStatus) {
 
 /** HTTP trigger runtime (#7) with transient retry (#134). */
 export async function runHttp(task, request, signal) {
+  const streamRunId = `run_${Date.now()}`;
+  logStreamer.startStream(task.id, streamRunId);
+  logStreamer.appendLog(task.id, `> ${request.method} ${request.url}
+`, 'stdout');
   let attempts = 0;
   const maxAttempts = 3;
   while (attempts < maxAttempts) {
@@ -201,6 +206,8 @@ export async function runExternal(task, runtime, signal, execOptions = {}, { ctx
     if (execOptions?.prevOutput !== undefined) {
       runEnv.DSH_PREV_OUTPUT = String(execOptions.prevOutput);
     }
+    const streamRunId = execOptions?.runId || `run_${Date.now()}`;
+    logStreamer.startStream(task.id, streamRunId);
     const options = {
       cwd,
       env: runEnv,
@@ -218,15 +225,18 @@ export async function runExternal(task, runtime, signal, execOptions = {}, { ctx
 
     child.stdout.on('data', (chunk) => {
       if (stdout.length < maxBuffer) stdout += chunk;
+      logStreamer.appendLog(task.id, chunk.toString('utf-8'), 'stdout');
     });
     child.stderr.on('data', (chunk) => {
       if (stderr.length < maxBuffer) stderr += chunk;
+      logStreamer.appendLog(task.id, chunk.toString('utf-8'), 'stderr');
     });
 
     child.on('error', (err) => {
       if (settled) return;
       settled = true;
       if (signal) signal.removeEventListener('abort', abortHandler);
+      logStreamer.completeStream(task.id, { status: 'error', error: err.message, exitCode: 1 });
       reject(err);
     });
 

package/lib/runner.js

@@ -1,3 +1,4 @@
+import { logStreamer } from './log-streamer.js';
 import { logger } from './logger.js';
 import { bestEffort } from './best-effort.js';
 import { estimateTokenCost } from './integrations.js';
@@ -92,6 +93,11 @@ export class SessionRunner {
       }, { once: true });
     }
 
+    const streamRunId = options.runId || `run_${Date.now()}`;
+    logStreamer.startStream(task.id, streamRunId);
+    logStreamer.appendLog(task.id, `[dsh-cron] Starting task "${task.title}" (type: ${task.type || 'llm'})
+`, 'stdout');
+
     const timeoutPromise = new Promise((_, reject) => {
       timeoutId = setTimeout(() => {
         const timeoutErr = new Error(`Task execution timed out after ${timeoutSeconds} seconds`);
@@ -103,7 +109,18 @@ export class SessionRunner {
     const executionPromise = this._run(task, controller.signal, options);
 
     try {
-      return await Promise.race([executionPromise, timeoutPromise]);
+      const res = await Promise.race([executionPromise, timeoutPromise]);
+      logStreamer.appendLog(task.id, `
+[dsh-cron] Task execution finished
+`, 'stdout');
+      logStreamer.completeStream(task.id, { status: 'success' });
+      return res;
+    } catch (err) {
+      logStreamer.appendLog(task.id, `
+[dsh-cron] Task execution error: ${err.message}
+`, 'stderr');
+      logStreamer.completeStream(task.id, { status: 'error', error: err.message });
+      throw err;
     } finally {
       if (timeoutId) clearTimeout(timeoutId);
     }