@mndrk/agx 2.0.19 → 2.0.21

package/cloud-runtime/standalone/Projects/Agents/agx-cloud/src/graph/schedule.ts

@@ -0,0 +1,207 @@
+import type { ExecutionGraph, GraphSchedule } from './types';
+import { computeNextTickFromCron } from './scheduler';
+
+/**
+ * Determines whether a scheduled tick should fire.
+ *
+ * Returns the mutated graph with reset nodes if a tick fires,
+ * or null if no tick is due.
+ *
+ * Invariants:
+ * - Skip if schedule is not active
+ * - Skip if a tick is already in progress (overlap prevention)
+ * - Skip if maxRuns reached
+ * - Reset only the specified resetNodeIds to pending
+ * - Mark tickInProgress = true so concurrent ticks are skipped
+ */
+export interface ScheduleTickResult {
+  graph: ExecutionGraph;
+  tickFired: boolean;
+  /** Node IDs that were reset to pending */
+  resetNodeIds: string[];
+  /** Reason tick was skipped (if tickFired is false) */
+  skipReason?: 'not_active' | 'tick_in_progress' | 'max_runs_reached' | 'not_due' | 'no_schedule';
+}
+
+export function scheduleTickIfDue(
+  graph: ExecutionGraph,
+  nowMs: number = Date.now(),
+): ScheduleTickResult {
+  const noTick = (reason: ScheduleTickResult['skipReason']): ScheduleTickResult => ({
+    graph,
+    tickFired: false,
+    resetNodeIds: [],
+    skipReason: reason,
+  });
+
+  if (!graph.schedule) {
+    return noTick('no_schedule');
+  }
+
+  const schedule = graph.schedule;
+
+  if (schedule.state !== 'active') {
+    return noTick('not_active');
+  }
+
+  if (schedule.tickInProgress) {
+    return noTick('tick_in_progress');
+  }
+
+  if (schedule.maxRuns != null && schedule.runCount >= schedule.maxRuns) {
+    return noTick('max_runs_reached');
+  }
+
+  // Check timing: cron-based (nextTickAt) or interval-based
+  if (schedule.cronExpr && typeof schedule.nextTickAt === 'number') {
+    if (nowMs < schedule.nextTickAt) {
+      return noTick('not_due');
+    }
+  } else {
+    const lastTick = schedule.lastTickAt ?? 0;
+    if (nowMs - lastTick < schedule.intervalMs) {
+      return noTick('not_due');
+    }
+  }
+
+  // Fire the tick: reset target nodes and mark tick in progress
+  const nextGraph: ExecutionGraph = JSON.parse(JSON.stringify(graph));
+  const resetIds: string[] = [];
+
+  for (const nodeId of schedule.resetNodeIds) {
+    const node = nextGraph.nodes[nodeId];
+    if (!node) continue;
+
+    // Only reset terminal nodes back to pending
+    if (
+      node.status === 'done' ||
+      node.status === 'passed' ||
+      node.status === 'failed' ||
+      node.status === 'skipped'
+    ) {
+      nextGraph.nodes[nodeId] = {
+        ...node,
+        status: 'pending',
+        startedAt: undefined,
+        completedAt: undefined,
+        metrics: undefined,
+        // Clear output for function nodes so downstream conditionals see fresh data
+        ...(node.type === 'function' ? { output: undefined } : {}),
+        // Clear evaluatedTo for conditional nodes
+        ...(node.type === 'conditional' ? { evaluatedTo: undefined } : {}),
+      } as typeof node;
+      resetIds.push(nodeId);
+    }
+  }
+
+  nextGraph.schedule = {
+    ...schedule,
+    tickInProgress: true,
+    lastTickAt: nowMs,
+    runCount: schedule.runCount + 1,
+  };
+
+  return {
+    graph: nextGraph,
+    tickFired: true,
+    resetNodeIds: resetIds,
+  };
+}
+
+/**
+ * Mark a scheduled tick as complete. Call after the tick's subgraph
+ * has finished executing (all reset nodes reached terminal state or
+ * were skipped by conditional).
+ */
+export function completeScheduleTick(graph: ExecutionGraph): ExecutionGraph {
+  if (!graph.schedule || !graph.schedule.tickInProgress) {
+    return graph;
+  }
+
+  const schedule = graph.schedule;
+  let nextTickAt = schedule.nextTickAt;
+  if (schedule.cronExpr) {
+    nextTickAt = computeNextTickFromCron(schedule.cronExpr);
+  }
+
+  return {
+    ...graph,
+    schedule: {
+      ...schedule,
+      tickInProgress: false,
+      nextTickAt,
+    },
+  };
+}
+
+/**
+ * Check if all nodes in resetNodeIds have reached a terminal state,
+ * meaning the tick's subgraph is done executing.
+ */
+export function isScheduleTickComplete(graph: ExecutionGraph): boolean {
+  if (!graph.schedule) return true;
+
+  const terminalStatuses = new Set(['done', 'passed', 'failed', 'skipped']);
+
+  for (const nodeId of graph.schedule.resetNodeIds) {
+    const node = graph.nodes[nodeId];
+    if (!node) continue;
+    if (!terminalStatuses.has(node.status)) {
+      return false;
+    }
+  }
+
+  // Also check nodes downstream of resetNodeIds that may have been triggered
+  // For now, just check the reset nodes themselves — the conditional and work
+  // nodes downstream will be covered by the graph's normal completion check
+  return true;
+}
+
+/**
+ * Create a schedule configuration for the thread monitor subgraph.
+ */
+export function createThreadMonitorSchedule(
+  resetNodeIds: string[],
+  intervalMs: number = 60000,
+  maxRuns?: number,
+): GraphSchedule {
+  return {
+    intervalMs,
+    state: 'active',
+    resetNodeIds,
+    maxRuns,
+    runCount: 0,
+    tickInProgress: false,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Activate an existing schedule (idempotent — no-op if already active).
+ */
+export function activateSchedule(graph: ExecutionGraph): ExecutionGraph {
+  if (!graph.schedule) return graph;
+  if (graph.schedule.state === 'active') return graph; // idempotent
+  return {
+    ...graph,
+    schedule: {
+      ...graph.schedule,
+      state: 'active',
+    },
+  };
+}
+
+/**
+ * Stop a schedule immediately. Clears tickInProgress.
+ */
+export function stopSchedule(graph: ExecutionGraph): ExecutionGraph {
+  if (!graph.schedule) return graph;
+  return {
+    ...graph,
+    schedule: {
+      ...graph.schedule,
+      state: 'stopped',
+      tickInProgress: false,
+    },
+  };
+}

package/cloud-runtime/standalone/Projects/Agents/agx-cloud/src/graph/scheduler.ts

@@ -9,6 +9,7 @@ import { evaluateCondition } from './condition';
 import {
   transitionConditionalNode,
   transitionForkNode,
+  transitionFunctionNode,
   transitionJoinNode,
   transitionWorkNode,
   transitionGateNode,
@@ -17,9 +18,24 @@ import type {
   ConditionalNode,
   Edge,
   ExecutionGraph,
+  GraphSchedule,
   GraphNode,
   NodeStatus,
 } from './types';
+import { CronExpressionParser } from 'cron-parser';
+
+/**
+ * Compute the next tick timestamp from a cron expression.
+ * Returns epoch ms, or undefined if the expression is invalid.
+ */
+export function computeNextTickFromCron(cronExpr: string, fromDate?: Date): number | undefined {
+  try {
+    const expr = CronExpressionParser.parse(cronExpr, { currentDate: fromDate });
+    return expr.next().toDate().getTime();
+  } catch {
+    return undefined;
+  }
+}
 
 const SOFT_DEP_SATISFIED_STATUS_SET = new Set<NodeStatus>(SOFT_DEP_SATISFIED_STATUSES);
 const SUCCESS_STATUS_SET = new Set<NodeStatus>(SUCCESS_NODE_STATUSES);
@@ -122,6 +138,9 @@ function skipNodeIfPending(node: GraphNode): GraphNode {
   if (node.type === 'work') {
     return transitionWorkNode(node, { type: 'SKIP' });
   }
+  if (node.type === 'function') {
+    return transitionFunctionNode(node, { type: 'SKIP' });
+  }
   if (node.type === 'gate') {
     return transitionGateNode(node, { type: 'SKIP' });
   }
@@ -175,7 +194,9 @@ function resolveConditionContext(
 ): Record<string, unknown> {
   const sourceNode = graph.nodes[node.condition.inputFrom];
   const sourceOutput =
-    sourceNode && sourceNode.type === 'work' ? (sourceNode.output ?? {}) : sourceNode ?? null;
+    sourceNode && 'output' in sourceNode
+      ? (sourceNode.output ?? null)
+      : null;
 
   return {
     graph,
@@ -192,6 +213,10 @@ function resolveConditionContext(
   };
 }
 
+function hasStructuredConditionInput(input: unknown): input is Record<string, unknown> {
+  return Boolean(input) && typeof input === 'object' && !Array.isArray(input);
+}
+
 export interface ControlEvaluationOptions {
   conditionContextByNodeId?: Record<string, Record<string, unknown>>;
 }
@@ -239,10 +264,16 @@ export function evaluateControlNodes(
     const started = transitionConditionalNode(node, { type: 'START', depsSatisfied: true }).node;
 
     try {
-      const result = evaluateCondition(
-        node.condition.expression,
-        resolveConditionContext(nextGraph, nodeId, node, conditionContextByNodeId),
+      const conditionContext = resolveConditionContext(
+        nextGraph,
+        nodeId,
+        node,
+        conditionContextByNodeId,
       );
+      // Fail-safe: if inputFrom cannot resolve to structured upstream output, route to else.
+      const result = hasStructuredConditionInput(conditionContext.input)
+        ? evaluateCondition(node.condition.expression, conditionContext)
+        : false;
       const completed = transitionConditionalNode(started, {
         type: result ? 'CONDITION_TRUE' : 'CONDITION_FALSE',
       });
@@ -300,23 +331,33 @@ export function evaluateControlNodes(
 
 export interface RunnableNodeSets {
   workRunnable: string[];
+  functionRunnable: string[];
   lightweightGateRunnable: string[];
   autoGateRunnable: string[];
 }
 
 export function findRunnableWorkAndGateNodes(graph: ExecutionGraph): RunnableNodeSets {
   const workRunnable: string[] = [];
+  const functionRunnable: string[] = [];
   const lightweightGateRunnable: string[] = [];
   const autoGateRunnable: string[] = [];
 
   for (const [nodeId, node] of Object.entries(graph.nodes)) {
-    if ((node.type !== 'work' && node.type !== 'gate') || node.status !== 'pending') {
+    if (node.type !== 'work' && node.type !== 'gate' && node.type !== 'function') {
+      continue;
+    }
+    if (node.status !== 'pending') {
       continue;
     }
     if (!areNodeDepsSatisfied(graph, nodeId, node.deps)) {
       continue;
     }
 
+    if (node.type === 'function') {
+      functionRunnable.push(nodeId);
+      continue;
+    }
+
     if (node.type === 'work') {
       workRunnable.push(nodeId);
       continue;
@@ -331,6 +372,7 @@ export function findRunnableWorkAndGateNodes(graph: ExecutionGraph): RunnableNod
 
   return {
     workRunnable,
+    functionRunnable,
     lightweightGateRunnable,
     autoGateRunnable,
   };
@@ -474,12 +516,264 @@ function countRunningAutoChecks(graph: ExecutionGraph): number {
   ).length;
 }
 
+export interface CreateGraphScheduleInput {
+  intervalMs: number;
+  cronExpr?: string;
+  cadence?: string;
+  name?: string;
+  description?: string;
+  resetNodeIds: string[];
+  maxRuns?: number;
+  maxConsecutiveFailures?: number;
+  activeUntil?: string;
+  rootMessageId?: string;
+  nowIso?: string;
+}
+
+export type ScheduledTickSkipReason =
+  | 'no_schedule'
+  | 'inactive'
+  | 'overlap'
+  | 'before_interval'
+  | 'max_runs_reached'
+  | 'expired';
+
+export interface PrepareScheduledTickResult {
+  graph: ExecutionGraph;
+  shouldRun: boolean;
+  skipReason?: ScheduledTickSkipReason;
+}
+
+function resetNodeForScheduledTick(node: GraphNode): GraphNode {
+  if (node.type === 'root') {
+    return node;
+  }
+
+  const resetBase: GraphNode = {
+    ...node,
+    status: 'pending',
+    startedAt: undefined,
+    completedAt: undefined,
+    actualMinutes: undefined,
+  } as GraphNode;
+
+  if (resetBase.type === 'work') {
+    return {
+      ...resetBase,
+      attempts: 0,
+      output: undefined,
+    };
+  }
+
+  if (resetBase.type === 'function') {
+    return {
+      ...resetBase,
+      output: undefined,
+    };
+  }
+
+  if (resetBase.type === 'gate') {
+    return {
+      ...resetBase,
+      verificationResult: undefined,
+    };
+  }
+
+  if (resetBase.type === 'conditional') {
+    return {
+      ...resetBase,
+      evaluatedTo: undefined,
+    };
+  }
+
+  return resetBase;
+}
+
+function normalizeIntervalMs(intervalMs: number): number {
+  return Math.max(1, Math.trunc(intervalMs));
+}
+
+function normalizeOptionalMaxRuns(maxRuns: number | undefined): number | undefined {
+  if (maxRuns === undefined) {
+    return undefined;
+  }
+  return Math.max(1, Math.trunc(maxRuns));
+}
+
+function normalizeOptionalIso(iso: string | undefined): string | undefined {
+  if (!iso) {
+    return undefined;
+  }
+  const parsed = Date.parse(iso);
+  return Number.isNaN(parsed) ? undefined : new Date(parsed).toISOString();
+}
+
+function shouldStopByExpiry(schedule: GraphSchedule, nowMs: number): boolean {
+  if (!schedule.activeUntil) {
+    return false;
+  }
+  const expiresAtMs = Date.parse(schedule.activeUntil);
+  if (Number.isNaN(expiresAtMs)) {
+    return false;
+  }
+  return nowMs >= expiresAtMs;
+}
+
+export function createGraphSchedule(input: CreateGraphScheduleInput): GraphSchedule {
+  const schedule: GraphSchedule = {
+    intervalMs: normalizeIntervalMs(input.intervalMs),
+    state: 'active',
+    resetNodeIds: input.resetNodeIds,
+    maxRuns: normalizeOptionalMaxRuns(input.maxRuns),
+    runCount: 0,
+    tickInProgress: false,
+    createdAt: normalizeOptionalIso(input.nowIso) ?? new Date().toISOString(),
+    activeUntil: normalizeOptionalIso(input.activeUntil),
+    rootMessageId: input.rootMessageId?.trim() || undefined,
+    cronExpr: input.cronExpr?.trim() || undefined,
+    cadence: input.cadence?.trim() || undefined,
+    name: input.name?.trim() || undefined,
+    description: input.description?.trim() || undefined,
+    maxConsecutiveFailures: input.maxConsecutiveFailures,
+    consecutiveFailures: 0,
+  };
+
+  // Compute nextTickAt from cron expression if present
+  if (schedule.cronExpr) {
+    schedule.nextTickAt = computeNextTickFromCron(schedule.cronExpr);
+  }
+
+  return schedule;
+}
+
+export function activateGraphSchedule(
+  graph: ExecutionGraph,
+  input: CreateGraphScheduleInput,
+): ExecutionGraph {
+  if (graph.schedule?.state === 'active') {
+    return graph;
+  }
+
+  const schedule = createGraphSchedule(input);
+  return {
+    ...graph,
+    schedule,
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+export function deactivateGraphSchedule(graph: ExecutionGraph): ExecutionGraph {
+  if (!graph.schedule || graph.schedule.state === 'stopped') {
+    return graph;
+  }
+
+  return {
+    ...graph,
+    schedule: {
+      ...graph.schedule,
+      state: 'stopped',
+      tickInProgress: false,
+    },
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+export function prepareScheduledTick(
+  graph: ExecutionGraph,
+  nowMs: number = Date.now(),
+): PrepareScheduledTickResult {
+  const schedule = graph.schedule;
+  if (!schedule) {
+    return { graph, shouldRun: false, skipReason: 'no_schedule' };
+  }
+  if (schedule.state !== 'active') {
+    return { graph, shouldRun: false, skipReason: 'inactive' };
+  }
+  if (schedule.tickInProgress) {
+    return { graph, shouldRun: false, skipReason: 'overlap' };
+  }
+  if (schedule.maxRuns !== undefined && schedule.runCount >= schedule.maxRuns) {
+    return {
+      graph: deactivateGraphSchedule(graph),
+      shouldRun: false,
+      skipReason: 'max_runs_reached',
+    };
+  }
+  if (shouldStopByExpiry(schedule, nowMs)) {
+    return {
+      graph: deactivateGraphSchedule(graph),
+      shouldRun: false,
+      skipReason: 'expired',
+    };
+  }
+  // Check timing: cron-based (nextTickAt) or interval-based
+  if (schedule.cronExpr && typeof schedule.nextTickAt === 'number') {
+    if (nowMs < schedule.nextTickAt) {
+      return { graph, shouldRun: false, skipReason: 'before_interval' };
+    }
+  } else if (
+    typeof schedule.lastTickAt === 'number'
+    && nowMs - schedule.lastTickAt < schedule.intervalMs
+  ) {
+    return { graph, shouldRun: false, skipReason: 'before_interval' };
+  }
+
+  const nextGraph = structuredClone(graph);
+  nextGraph.schedule = {
+    ...schedule,
+    tickInProgress: true,
+    lastTickAt: nowMs,
+  };
+  for (const nodeId of schedule.resetNodeIds) {
+    const node = nextGraph.nodes[nodeId];
+    if (!node) {
+      continue;
+    }
+    nextGraph.nodes[nodeId] = resetNodeForScheduledTick(node);
+  }
+
+  return { graph: nextGraph, shouldRun: true };
+}
+
+export function finalizeScheduledTick(
+  graph: ExecutionGraph,
+  nowMs: number = Date.now(),
+): ExecutionGraph {
+  const schedule = graph.schedule;
+  if (!schedule) {
+    return graph;
+  }
+
+  const runCount = schedule.tickInProgress ? schedule.runCount + 1 : schedule.runCount;
+  const shouldStop = schedule.maxRuns !== undefined && runCount >= schedule.maxRuns;
+
+  // Compute next tick for cron schedules
+  let nextTickAt = schedule.nextTickAt;
+  if (schedule.cronExpr && !shouldStop) {
+    nextTickAt = computeNextTickFromCron(schedule.cronExpr, new Date(nowMs));
+  }
+
+  return {
+    ...graph,
+    schedule: {
+      ...schedule,
+      runCount,
+      tickInProgress: false,
+      state: shouldStop ? 'stopped' : schedule.state,
+      lastTickAt: schedule.lastTickAt ?? nowMs,
+      nextTickAt,
+    },
+    updatedAt: new Date(nowMs).toISOString(),
+  };
+}
+
 export interface SchedulerTickOptions extends ControlEvaluationOptions {}
 
 export interface SchedulerTickResult extends RunnableNodeSets {
   graph: ExecutionGraph;
   control: ControlEvaluationResult;
   workToRun: string[];
+  functionToRun: string[];
   lightweightGatesToRun: string[];
   autoGatesToRun: string[];
   dispatchOrder: string[];
@@ -505,15 +799,18 @@ export function schedulerTick(
   );
 
   const workToRun = prioritizeNodeIds(nextGraph, runnable.workRunnable).slice(0, availableWork);
+  // Function nodes are lightweight (no agent) — dispatch all of them without concurrency limits
+  const functionToRun = [...runnable.functionRunnable];
   const lightweightGatesToRun = [...runnable.lightweightGateRunnable];
   const autoGatesToRun = runnable.autoGateRunnable.slice(0, availableAutoChecks);
-  const dispatchOrder = [...lightweightGatesToRun, ...autoGatesToRun, ...workToRun];
+  const dispatchOrder = [...functionToRun, ...lightweightGatesToRun, ...autoGatesToRun, ...workToRun];
 
   return {
     graph: nextGraph,
     control,
     ...runnable,
     workToRun,
+    functionToRun,
     lightweightGatesToRun,
     autoGatesToRun,
     dispatchOrder,