@johpaz/hive-agents 0.0.34 → 0.0.36

package/packages/core/src/scheduler/dag/TaskNode.ts

@@ -0,0 +1,97 @@
+/**
+ * DAGScheduler — TaskNode
+ *
+ * Represents a single node in the task graph. Tracks its own state,
+ * retry count, timing, and the results of its dependencies.
+ */
+
+export type NodeStatus = "PENDING" | "READY" | "RUNNING" | "COMPLETED" | "FAILED"
+
+export interface TaskNodeConfig {
+  /** Unique ID within this graph (can match SQLite task.id) */
+  id: string
+  /** agents.id of the worker agent to execute */
+  agentId: string
+  /** Human-readable name for logging */
+  name: string
+  /** Task description passed to the worker */
+  taskDescription: string
+  /** IDs of other TaskNodes that must complete first */
+  deps: string[]
+  /** Timeout in ms before the task is cancelled. Default: 120_000 */
+  timeout?: number
+  /** How many times to retry on failure. Default: 1 */
+  maxRetries?: number
+  /** Priority hint for PriorityStrategy. Higher = runs first. Default: 0 */
+  priority?: number
+  /** Optional arbitrary metadata forwarded to the worker */
+  metadata?: Record<string, unknown>
+}
+
+export class TaskNode {
+  readonly id: string
+  readonly agentId: string
+  readonly name: string
+  readonly taskDescription: string
+  readonly deps: string[]
+  readonly timeout: number
+  readonly maxRetries: number
+  readonly priority: number
+  readonly metadata: Record<string, unknown>
+
+  status: NodeStatus = "PENDING"
+  retryCount = 0
+  startedAt?: number
+  completedAt?: number
+  result?: string
+  error?: string
+
+  constructor(config: TaskNodeConfig) {
+    this.id = config.id
+    this.agentId = config.agentId
+    this.name = config.name
+    this.taskDescription = config.taskDescription
+    this.deps = config.deps
+    this.timeout = config.timeout ?? 120_000
+    this.maxRetries = config.maxRetries ?? 1
+    this.priority = config.priority ?? 0
+    this.metadata = config.metadata ?? {}
+  }
+
+  /** Returns true if all dependency IDs are in the completed set */
+  canStart(completedIds: Set<string>): boolean {
+    return this.deps.every(dep => completedIds.has(dep))
+  }
+
+  markReady(): void {
+    this.status = "READY"
+  }
+
+  markRunning(): void {
+    this.status = "RUNNING"
+    this.startedAt = Date.now()
+  }
+
+  markCompleted(result: string): void {
+    this.status = "COMPLETED"
+    this.completedAt = Date.now()
+    this.result = result
+  }
+
+  markFailed(error: string): void {
+    this.status = "FAILED"
+    this.completedAt = Date.now()
+    this.error = error
+  }
+
+  canRetry(): boolean {
+    return this.retryCount < this.maxRetries
+  }
+
+  /** Elapsed time in seconds since start, or total duration if done */
+  elapsedSeconds(): number {
+    if (!this.startedAt) return 0
+    const end = this.completedAt ?? Date.now()
+    return Math.round((end - this.startedAt) / 1000)
+  }
+}

package/packages/core/src/scheduler/dag/TaskResult.ts

@@ -0,0 +1,22 @@
+/**
+ * DAGScheduler — Result types
+ */
+
+export interface NodeSummary {
+  id: string
+  name: string
+  status: "COMPLETED" | "FAILED"
+  durationMs: number
+  result?: string
+  error?: string
+  retries: number
+}
+
+export interface DAGResult {
+  swarmId: string
+  totalDurationMs: number
+  completed: NodeSummary[]
+  failed: NodeSummary[]
+  /** true if all nodes completed successfully */
+  success: boolean
+}

package/packages/core/src/scheduler/dag/errors.ts

@@ -0,0 +1,37 @@
+/**
+ * DAGScheduler — Custom errors
+ */
+
+export class CyclicDependencyError extends Error {
+  readonly cycle: string[]
+
+  constructor(cycle: string[]) {
+    super(`Cyclic dependency detected: ${cycle.join(" → ")}`)
+    this.name = "CyclicDependencyError"
+    this.cycle = cycle
+  }
+}
+
+export class TaskTimeoutError extends Error {
+  readonly nodeId: string
+  readonly timeoutMs: number
+
+  constructor(nodeId: string, timeoutMs: number) {
+    super(`Task "${nodeId}" timed out after ${timeoutMs}ms`)
+    this.name = "TaskTimeoutError"
+    this.nodeId = nodeId
+    this.timeoutMs = timeoutMs
+  }
+}
+
+export class TaskFailureError extends Error {
+  readonly nodeId: string
+  readonly cause: Error
+
+  constructor(nodeId: string, cause: Error) {
+    super(`Task "${nodeId}" failed: ${cause.message}`)
+    this.name = "TaskFailureError"
+    this.nodeId = nodeId
+    this.cause = cause
+  }
+}

package/packages/core/src/scheduler/dag/index.ts

@@ -0,0 +1,26 @@
+/**
+ * DAGScheduler — Public API
+ *
+ * Usage:
+ *   import { DAGScheduler, TaskGraph, ParallelStrategy } from "./dag"
+ */
+
+export { DAGScheduler } from "./DAGScheduler"
+export type { DAGSchedulerOptions } from "./DAGScheduler"
+
+export { TaskGraph } from "./TaskGraph"
+export { TaskNode } from "./TaskNode"
+export type { TaskNodeConfig, NodeStatus } from "./TaskNode"
+export type { DAGResult, NodeSummary } from "./TaskResult"
+
+export { AgentExecutor } from "./AgentExecutor"
+export { EventBridge } from "./EventBridge"
+
+export { CyclicDependencyError, TaskTimeoutError, TaskFailureError } from "./errors"
+
+export { ParallelStrategy } from "./strategies/ParallelStrategy"
+export type { ExecutionStrategy } from "./strategies/ParallelStrategy"
+export { PriorityStrategy } from "./strategies/PriorityStrategy"
+
+export { createResearchGraph } from "./presets/ResearchPreset"
+export type { ResearchAgentIds } from "./presets/ResearchPreset"

package/packages/core/src/scheduler/dag/presets/ResearchPreset.ts

@@ -0,0 +1,97 @@
+/**
+ * ResearchPreset — Pre-configured DAG for general research swarms
+ *
+ * Dependency graph:
+ *   ResearchAgent ─┐
+ *   StrategyAgent  ├── SynthesisAgent  (all three run in parallel)
+ *   DesignAgent   ─┘
+ *
+ * All three parallel agents are fully independent. SynthesisAgent
+ * waits for all three and combines their outputs into a final deliverable.
+ *
+ * Usage:
+ *   const graph = createResearchGraph(
+ *     { research: "agent-uuid-1", strategy: "agent-uuid-2",
+ *       design: "agent-uuid-3", synthesis: "agent-uuid-4" },
+ *     "Design a distributed caching strategy for the platform"
+ *   )
+ *   await scheduler.execute(graph, { projectId, coordinatorId })
+ */
+
+import { TaskGraph } from "../TaskGraph"
+import type { TaskNodeConfig } from "../TaskNode"
+
+export interface ResearchAgentIds {
+  research: string
+  strategy: string
+  design: string
+  synthesis: string
+}
+
+export function createResearchGraph(
+  agentIds: ResearchAgentIds,
+  topic: string,
+  options: {
+    researchTimeout?: number
+    strategyTimeout?: number
+    designTimeout?: number
+    synthesisTimeout?: number
+  } = {}
+): TaskGraph {
+  const nodes: TaskNodeConfig[] = [
+    {
+      id: "research",
+      agentId: agentIds.research,
+      name: "ResearchAgent",
+      taskDescription:
+        `Research the following topic using available knowledge bases and sources: "${topic}".` +
+        ` Output: { findings: string[], sources: string[], keyInsights: string[] }.`,
+      deps: [],
+      timeout: options.researchTimeout ?? 120_000,
+      maxRetries: 1,
+      priority: 8,
+    },
+    {
+      id: "strategy",
+      agentId: agentIds.strategy,
+      name: "StrategyAgent",
+      taskDescription:
+        `Design a strategic framework or approach for: "${topic}".` +
+        ` Work independently — you will NOT have the research findings yet.` +
+        ` Output: { approach: string, phases: string[], risks: string[], successMetrics: string[] }.`,
+      deps: [],
+      timeout: options.strategyTimeout ?? 90_000,
+      maxRetries: 1,
+      priority: 8,
+    },
+    {
+      id: "design",
+      agentId: agentIds.design,
+      name: "DesignAgent",
+      taskDescription:
+        `Design the structure or architecture for: "${topic}".` +
+        ` Work independently — focus on structure, not content.` +
+        ` Output: { structure: string, components: string[], diagram: string (ASCII or Mermaid) }.`,
+      deps: [],
+      timeout: options.designTimeout ?? 90_000,
+      maxRetries: 1,
+      priority: 8,
+    },
+    {
+      id: "synthesis",
+      agentId: agentIds.synthesis,
+      name: "SynthesisAgent",
+      taskDescription:
+        `Synthesize the research findings, strategic framework, and design structure into a cohesive deliverable.` +
+        ` The dependency context contains all three agents' outputs.` +
+        ` Topic: "${topic}".` +
+        ` Output a comprehensive, well-structured document that combines all inputs coherently.`,
+      deps: ["research", "strategy", "design"],
+      timeout: options.synthesisTimeout ?? 150_000,
+      maxRetries: 2,
+      priority: 0,
+    },
+  ]
+
+  return new TaskGraph(nodes)
+}

package/packages/core/src/scheduler/dag/strategies/ParallelStrategy.ts

@@ -0,0 +1,21 @@
+/**
+ * ParallelStrategy — executes DAG nodes in parallel as slots become available
+ *
+ * Picks nodes from the READY queue in FIFO order.
+ * Nodes are launched immediately when a worker slot is available,
+ * otherwise they wait in the queue.
+ */
+
+import { TaskNode } from "../TaskNode"
+
+export interface ExecutionStrategy {
+  pick(queue: TaskNode[]): TaskNode | undefined
+  /** Called once at graph start to allow strategy-level initialization */
+  initialize?(nodes: Map<string, TaskNode>): void
+}
+
+export class ParallelStrategy implements ExecutionStrategy {
+  pick(queue: TaskNode[]): TaskNode | undefined {
+    return queue.shift()
+  }
+}

package/packages/core/src/scheduler/dag/strategies/PriorityStrategy.ts

@@ -0,0 +1,46 @@
+/**
+ * PriorityStrategy — for research swarms
+ *
+ * Boosts the priority of nodes on the critical path so they run first
+ * when slots are limited. Within same effective priority, FIFO order applies.
+ */
+
+import { TaskNode } from "../TaskNode"
+import { TaskGraph } from "../TaskGraph"
+import type { ExecutionStrategy } from "./ParallelStrategy"
+
+export class PriorityStrategy implements ExecutionStrategy {
+  private criticalPathSet = new Set<string>()
+  private readonly CRITICAL_BOOST = 1000
+
+  initialize(nodes: Map<string, TaskNode>): void {
+    // Build a temporary graph for critical path calculation
+    const configs = [...nodes.values()].map(n => ({
+      id: n.id,
+      agentId: n.agentId,
+      name: n.name,
+      taskDescription: n.taskDescription,
+      deps: n.deps,
+      timeout: n.timeout,
+      maxRetries: n.maxRetries,
+      priority: n.priority,
+    }))
+    const graph = new TaskGraph(configs)
+    for (const id of graph.getCriticalPath()) {
+      this.criticalPathSet.add(id)
+    }
+  }
+
+  pick(queue: TaskNode[]): TaskNode | undefined {
+    if (queue.length === 0) return undefined
+
+    // Sort: critical path nodes first, then by node.priority desc, then FIFO (stable)
+    queue.sort((a, b) => {
+      const aBoost = this.criticalPathSet.has(a.id) ? this.CRITICAL_BOOST : 0
+      const bBoost = this.criticalPathSet.has(b.id) ? this.CRITICAL_BOOST : 0
+      return (b.priority + bBoost) - (a.priority + aBoost)
+    })
+
+    return queue.shift()
+  }
+}

package/packages/core/src/scheduler/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Hive Scheduler Module
+ * 
+ * Croner-based scheduling system for Hive.
+ * Supports recurring and one-shot cron jobs with SQLite persistence.
+ */
+
+export { CronScheduler } from "./CronScheduler";
+export { executeScheduledTask, createTaskHandler, notifyTaskCompletion, setSchedulerForCleanup } from "./integration";
+export type {
+  CronJob,
+  TaskRun,
+  CreateCronJobInput,
+  UpdateCronJobInput,
+  CronJobStatus,
+  CronJobExecutionHandler,
+  CronJobExecutionResult,
+  TaskType,
+  TaskStatus,
+  TaskRunStatus,
+  CronerOptions,
+} from "./types";

package/packages/core/src/scheduler/integration.ts

@@ -0,0 +1,237 @@
+/**
+ * Hive Scheduler - Pipeline Integration
+ * 
+ * Integrates cron jobs with the Hive agent pipeline.
+ * Converts cron jobs into system messages that flow through the agent system.
+ */
+
+import type { CronJob, CronJobExecutionResult } from "./types";
+import { logger } from "../utils/logger";
+import { getDb } from "../storage/sqlite";
+import { buildAgentLoop } from "../agent/agent-loop";
+import { resolveAgentId } from "../storage/onboarding";
+import { sendToUserChannel } from "../gateway/channel-notify";
+import { addMessage } from "../agent/conversation-store";
+import { resolveBestChannel } from "../tools/cron/index";
+
+const log = logger.child("SchedulerIntegration");
+
+let _scheduler: { runCleanup(): void } | null = null;
+
+export function setSchedulerForCleanup(scheduler: { runCleanup(): void }): void {
+  _scheduler = scheduler;
+}
+
+/**
+ * Execute a cron job through the agent pipeline
+ * 
+ * This handler:
+ * 1. Parses the job payload
+ * 2. Builds a system message with metadata including the `task` field as instruction
+ * 3. Routes to the target agent (or Coordinator if none specified)
+ * 4. Executes the tool if tool_name is specified
+ * 5. Returns the agent response
+ */
+export async function executeScheduledTask(job: CronJob): Promise<CronJobExecutionResult> {
+  log.info(`[execute] Processing job "${job.name}" (${job.id})`);
+
+  try {
+    let payload: Record<string, unknown>;
+    try {
+      payload = JSON.parse(job.payload);
+    } catch (err) {
+      log.error(`[execute] Invalid payload JSON for job "${job.id}": ${(err as Error).message}`);
+      return { success: false, error: "Invalid payload JSON" };
+    }
+
+    const prompt = (payload.prompt || payload.message) as string | undefined;
+    if (!prompt && !payload._internal && !job.task) {
+      log.error(`[execute] Job "${job.id}" has no prompt, message, or task instruction`);
+      return { success: false, error: "Missing prompt, message, or task instruction" };
+    }
+
+    if (payload._internal === true && (payload as any).action === "cleanup") {
+      if (_scheduler) {
+        _scheduler.runCleanup();
+      } else {
+        log.warn("[execute] Cleanup job fired but scheduler instance not available");
+      }
+      log.info("[execute] Cleanup job executed");
+      return { success: true, response: "Cleanup completed" };
+    }
+
+    // Build message metadata
+    const metadata = {
+      source: "scheduler" as const,
+      task_id: job.id,
+      task_name: job.name,
+      channel: job.channel,
+      scheduled: true,
+      tool_name: job.tool_name || undefined,
+    };
+
+    let targetAgentId: string | null = job.agent_id || null;
+    
+    if (!targetAgentId) {
+      targetAgentId = resolveAgentId(null);
+      log.debug(`[execute] No agent specified, routing to Coordinator: ${targetAgentId}`);
+    }
+
+    const db = getDb();
+    const user = db.query("SELECT id, timezone, language FROM users LIMIT 1").get() as {
+      id: string;
+      timezone: string;
+      language: string | null;
+    } | undefined;
+
+    const userTimezone = user?.timezone || "UTC";
+    const userLanguage = user?.language || "en";
+
+    const now = new Date();
+    const dateOptions: Intl.DateTimeFormatOptions = {
+      timeZone: userTimezone,
+      year: "numeric",
+      month: "long",
+      day: "numeric",
+      weekday: "long",
+    };
+    const timeOptions: Intl.DateTimeFormatOptions = {
+      timeZone: userTimezone,
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      hour12: false,
+    };
+
+    const fecha_usuario = new Intl.DateTimeFormat(userLanguage === "es" ? "es-ES" : "en-US", dateOptions).format(now);
+    const hora_usuario = new Intl.DateTimeFormat(userLanguage === "es" ? "es-ES" : "en-US", timeOptions).format(now);
+
+    // Build the full prompt with the `task` field as the primary instruction
+    const contextPrompt = `[SCHEDULED TASK]
+Name: ${job.name}
+Instruction: ${job.task}
+Type: ${job.task_type}
+Triggered at: ${hora_usuario} on ${fecha_usuario} (${userTimezone})
+
+${prompt || `Execute tool: ${job.tool_name}`}`;
+
+    log.debug(`[execute] Sending to agent ${targetAgentId}: "${contextPrompt.slice(0, 100)}..."`);
+
+    try {
+      const agentLoop = buildAgentLoop({ mcpManager: undefined });
+      
+      const sessionId = `sched_${job.id}_${Date.now()}`;
+
+      const agentChannel = (job.channel && job.channel !== "system")
+        ? job.channel
+        : resolveBestChannel(user?.id || "");
+
+      const messages = [{ role: "user", content: contextPrompt }];
+      const stream = agentLoop.stream({ messages }, {
+        configurable: {
+          thread_id: sessionId,
+          agent_id: targetAgentId || undefined,
+          channel: agentChannel,
+          user_id: user?.id || "",
+          system_prompt: undefined,
+          raw_user_message: contextPrompt,
+        },
+      });
+
+      let response = "";
+      let hasError = false;
+      
+      for await (const chunk of stream) {
+        if (chunk.agent?.messages) {
+          const lastMsg = chunk.agent.messages[chunk.agent.messages.length - 1];
+          if (lastMsg?.content) {
+            response += lastMsg.content;
+          }
+        }
+        if (chunk.tools?.messages) {
+          for (const msg of chunk.tools.messages) {
+            if (msg.content?.error) {
+              hasError = true;
+              response += ` [Tool error: ${JSON.stringify(msg.content)}]`;
+            }
+          }
+        }
+      }
+
+      if (hasError && !response) {
+        throw new Error("Agent execution returned errors");
+      }
+
+      log.info(`[execute] Agent response received for job "${job.name}"`);
+
+      return {
+        success: true,
+        response: response || "Task executed successfully",
+      };
+    } catch (agentErr) {
+      log.error(`[execute] Agent execution failed: ${(agentErr as Error).message}`);
+      return {
+        success: false,
+        error: `Agent execution failed: ${(agentErr as Error).message}`,
+      };
+    }
+  } catch (err) {
+    log.error(`[execute] Job execution failed: ${(err as Error).message}`);
+    return {
+      success: false,
+      error: (err as Error).message,
+    };
+  }
+}
+
+/**
+ * Send notification to user's channel after job execution
+ */
+export async function notifyTaskCompletion(
+  taskId: string,
+  taskName: string,
+  success: boolean,
+  response?: string,
+  error?: string
+): Promise<void> {
+  const db = getDb();
+
+  const task = db.query(
+    "SELECT channel, agent_id FROM cron_jobs WHERE id = ?"
+  ).get(taskId) as { channel: string; agent_id: string | null } | undefined;
+
+  if (!task) {
+    log.warn(`[notify] Job "${taskId}" not found`);
+    return;
+  }
+
+  const userRow = db.query("SELECT id FROM users LIMIT 1").get() as { id: string } | undefined;
+  const userId = userRow?.id || "";
+
+  const explicitChannel = task.channel && task.channel !== "system" ? task.channel : undefined;
+  const notifyChannel = resolveBestChannel(userId, explicitChannel) || "webchat";
+  log.info(`[notifyTaskCompletion] task.channel=${task.channel} explicit=${explicitChannel} resolved=${notifyChannel}`);
+
+  const status = success ? "✅" : "❌";
+  const message = success
+    ? `${status} Scheduled task "${taskName}" completed\n${response || ""}`
+    : `${status} Scheduled task "${taskName}" failed\n${error || ""}`;
+
+  log.info(`[notify] Sending notification to ${notifyChannel}: "${message.slice(0, 50)}..."`);
+
+  try {
+    addMessage(userId, "assistant", message, { channel: notifyChannel });
+  } catch (e) {
+    log.warn(`[notify] Failed to persist notification to DB: ${(e as Error).message}`);
+  }
+
+  await sendToUserChannel(notifyChannel, userId, message);
+  log.info(`[notify] Notification sent to ${notifyChannel}`);
+}
+
+/**
+ * Create the job execution handler for CronScheduler
+ */
+export function createTaskHandler() {
+  return executeScheduledTask;
+}