@johpaz/hive-sdk 0.0.12 → 0.0.15

package/packages/core/src/swarm/TaskGraph.ts

@@ -0,0 +1,192 @@
+/**
+ * DAGScheduler — TaskGraph
+ *
+ * Owns the full set of TaskNodes for one swarm execution.
+ * Responsibilities:
+ *   1. Validate no cyclic dependencies (DFS) at construction time
+ *   2. Calculate the critical path (longest weighted path)
+ *   3. Provide runtime queries: ready nodes, overall progress
+ */
+
+import { TaskNode, type TaskNodeConfig } from "./TaskNode"
+import { CyclicDependencyError } from "./errors"
+
+export class TaskGraph {
+  readonly nodes: Map<string, TaskNode>
+  private criticalPath_: string[] | null = null
+
+  constructor(configs: TaskNodeConfig[]) {
+    this.nodes = new Map(configs.map(c => [c.id, new TaskNode(c)]))
+    this.validateNoCycles()
+  }
+
+  // ─── Validation ─────────────────────────────────────────────────────────────
+
+  private validateNoCycles(): void {
+    // Three-color DFS: WHITE=unvisited, GRAY=in-stack, BLACK=done
+    const WHITE = 0, GRAY = 1, BLACK = 2
+    const color = new Map<string, number>()
+
+    for (const id of this.nodes.keys()) color.set(id, WHITE)
+
+    const path: string[] = []
+
+    const visit = (id: string): void => {
+      color.set(id, GRAY)
+      path.push(id)
+
+      const node = this.nodes.get(id)!
+      for (const dep of node.deps) {
+        if (!this.nodes.has(dep)) {
+          throw new Error(`TaskGraph: node "${id}" depends on unknown node "${dep}"`)
+        }
+        const c = color.get(dep)!
+        if (c === GRAY) {
+          // Found back-edge: reconstruct cycle
+          const cycleStart = path.indexOf(dep)
+          throw new CyclicDependencyError([...path.slice(cycleStart), dep])
+        }
+        if (c === WHITE) visit(dep)
+      }
+
+      path.pop()
+      color.set(id, BLACK)
+    }
+
+    for (const id of this.nodes.keys()) {
+      if (color.get(id) === WHITE) visit(id)
+    }
+  }
+
+  // ─── Critical Path ───────────────────────────────────────────────────────────
+
+  /**
+   * Returns the IDs of the longest dependency chain (by node count).
+   * Nodes on this path get higher priority in PriorityStrategy.
+   */
+  getCriticalPath(): string[] {
+    if (this.criticalPath_) return this.criticalPath_
+
+    // longest[id] = length of longest path ending at id (inclusive)
+    const longest = new Map<string, number>()
+    const predecessor = new Map<string, string | null>()
+
+    const compute = (id: string): number => {
+      if (longest.has(id)) return longest.get(id)!
+      const node = this.nodes.get(id)!
+      if (node.deps.length === 0) {
+        longest.set(id, 1)
+        predecessor.set(id, null)
+        return 1
+      }
+      let max = 0
+      let maxPred: string | null = null
+      for (const dep of node.deps) {
+        const l = compute(dep)
+        if (l > max) { max = l; maxPred = dep }
+      }
+      longest.set(id, max + 1)
+      predecessor.set(id, maxPred)
+      return max + 1
+    }
+
+    for (const id of this.nodes.keys()) compute(id)
+
+    // Find sink with max longest
+    let sinkId = ""
+    let maxLen = 0
+    for (const [id, len] of longest) {
+      if (len > maxLen) { maxLen = len; sinkId = id }
+    }
+
+    // Reconstruct path from sink to source, then reverse
+    const path: string[] = []
+    let cur: string | null = sinkId
+    while (cur !== null) {
+      path.push(cur)
+      cur = predecessor.get(cur) ?? null
+    }
+    path.reverse()
+
+    this.criticalPath_ = path
+    return path
+  }
+
+  // ─── Runtime queries ─────────────────────────────────────────────────────────
+
+  /** Nodes that are still PENDING but now have all deps completed */
+  getNewlyReadyNodes(completedIds: Set<string>): TaskNode[] {
+    const ready: TaskNode[] = []
+    for (const node of this.nodes.values()) {
+      if (node.status === "PENDING" && node.canStart(completedIds)) {
+        ready.push(node)
+      }
+    }
+    return ready
+  }
+
+  /** All nodes currently in READY state */
+  getReadyNodes(): TaskNode[] {
+    return [...this.nodes.values()].filter(n => n.status === "READY")
+  }
+
+  /** IDs of all COMPLETED nodes */
+  getCompletedIds(): Set<string> {
+    const ids = new Set<string>()
+    for (const [id, node] of this.nodes) {
+      if (node.status === "COMPLETED") ids.add(id)
+    }
+    return ids
+  }
+
+  /** Collect results of all deps for a given node */
+  getDepResults(nodeId: string): Record<string, string> {
+    const node = this.nodes.get(nodeId)!
+    const results: Record<string, string> = {}
+    for (const dep of node.deps) {
+      const depNode = this.nodes.get(dep)!
+      if (depNode.result !== undefined) results[dep] = depNode.result
+    }
+    return results
+  }
+
+  /** 0–100 progress based on nodes in terminal state */
+  getProgress(): number {
+    const total = this.nodes.size
+    if (total === 0) return 100
+    let done = 0
+    for (const node of this.nodes.values()) {
+      if (node.status === "COMPLETED" || node.status === "FAILED") done++
+    }
+    return Math.round((done / total) * 100)
+  }
+
+  /** True when every node is in a terminal state */
+  isComplete(): boolean {
+    for (const node of this.nodes.values()) {
+      if (node.status === "PENDING" || node.status === "READY" || node.status === "RUNNING") {
+        return false
+      }
+    }
+    return true
+  }
+
+  /** Propagate FAILED status to all nodes that depend (directly or transitively) on failedId */
+  propagateFailure(failedId: string, reason: string): void {
+    const failedSet = new Set<string>([failedId])
+
+    let changed = true
+    while (changed) {
+      changed = false
+      for (const node of this.nodes.values()) {
+        if (node.status === "PENDING" || node.status === "READY") {
+          if (node.deps.some(d => failedSet.has(d))) {
+            node.markFailed(`dependency_failed: ${reason}`)
+            failedSet.add(node.id)
+            changed = true
+          }
+        }
+      }
+    }
+  }
+}

package/packages/core/src/swarm/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/swarm/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/swarm/WorkerPool.ts

@@ -0,0 +1,236 @@
+/**
+ * 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.ts";
+import { getDb } from "../storage/SQLiteStorage.ts";
+import { buildAgentLoop } from "../agent/AgentRunner.ts";
+import { resolveAgentId } from "../storage/onboarding.ts";
+import { sendToUserChannel } from "../gateway/channel-notify.ts";
+import { addMessage } from "../agent/ConversationStore.ts";
+import { resolveBestChannel } from "../tools/cron/index.ts";
+
+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";
+
+  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;
+}

package/packages/core/src/swarm/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/swarm/index.ts

@@ -0,0 +1,30 @@
+export { DAGScheduler } from "./Coordinator.ts";
+export type { DAGSchedulerOptions, IAgentExecutor } from "./Coordinator.ts";
+
+export { TaskGraph } from "./TaskGraph.ts";
+export { TaskNode } from "./TaskNode.ts";
+export type { TaskNodeConfig, NodeStatus } from "./TaskNode.ts";
+export type { DAGResult, NodeSummary } from "./TaskResult.ts";
+
+export { AgentExecutor } from "./AgentExecutor.ts";
+export { EventBridge } from "./EventBridge.ts";
+
+export { CyclicDependencyError, TaskTimeoutError, TaskFailureError } from "./errors.ts";
+
+export type { AgentBusEventMap, AgentBusEventKey, AgentBusEventHandler, AgentBusMessage } from "./AgentBus.ts";
+export { getUnreadMessagesForWorker, getProjectMessageHistory, agentBus } from "./AgentBus.ts";
+export type { AgentBus } from "./AgentBus.ts";
+
+export type { EventMap, EventKey, EventHandler } from "./EventBus.ts";
+export { eventBus } from "./EventBus.ts";
+export type { TypedEventBus } from "./EventBus.ts";
+
+export { setSchedulerForCleanup, executeScheduledTask, notifyTaskCompletion, createTaskHandler } from "./WorkerPool.ts";
+
+export type { ExecutionStrategy } from "./strategies/index.ts";
+export { ParallelStrategy, PriorityStrategy } from "./strategies/index.ts";
+
+export { createHiveLearnGraph } from "./presets/index.ts";
+export type { HiveLearnAgentIds, HiveLearnInput } from "./presets/index.ts";
+export { createResearchGraph } from "./presets/index.ts";
+export type { ResearchAgentIds } from "./presets/index.ts";