@johpaz/hive-sdk 0.0.12 → 0.0.15

package/packages/core/src/swarm/presets/HiveLearnPreset.ts

@@ -0,0 +1,99 @@
+/**
+ * HiveLearnPreset — Pre-configured DAG for the HiveLearn swarm
+ *
+ * Dependency graph:
+ *   CurriculumAgent (no deps, priority=10)
+ *       ↓               ↓
+ *   ContentAgent    VisualAgent   ← run IN PARALLEL after Curriculum
+ *       ↓               ↓
+ *       └──── GamificationAgent (waits for both)
+ *
+ * Expected timing with maxConcurrentWorkers=2 on BOSGAME:
+ *   T=0s    → CurriculumAgent starts
+ *   T=~30s  → CurriculumAgent done → Content + Visual start in parallel
+ *   T=~100s → both done → GamificationAgent starts
+ *   T=~120s → GamificationAgent done → swarm:completed
+ *   Savings vs sequential: ~38% (~75s)
+ */
+
+import { TaskGraph } from "../TaskGraph"
+import type { TaskNodeConfig } from "../TaskNode"
+
+export interface HiveLearnAgentIds {
+  curriculum: string
+  content: string
+  visual: string
+  gamification: string
+}
+
+export interface HiveLearnInput {
+  learnerGoal: string
+  nodeType: string
+  /** Optional session/user context to include in descriptions */
+  context?: string
+}
+
+export function createHiveLearnGraph(
+  agentIds: HiveLearnAgentIds,
+  input: HiveLearnInput
+): TaskGraph {
+  const ctxNote = input.context ? ` Context: ${input.context}` : ""
+
+  const nodes: TaskNodeConfig[] = [
+    {
+      id: "curriculum",
+      agentId: agentIds.curriculum,
+      name: "CurriculumAgent",
+      taskDescription:
+        `Design a structured curriculum for the following learner goal: "${input.learnerGoal}".` +
+        ` Focus on the node type: "${input.nodeType}".` +
+        ` Output a JSON object with: { title, objectives: string[], prerequisites: string[], estimatedMinutes: number }.` +
+        ctxNote,
+      deps: [],
+      timeout: 60_000,
+      maxRetries: 1,
+      priority: 10,
+    },
+    {
+      id: "content",
+      agentId: agentIds.content,
+      name: "ContentAgent",
+      taskDescription:
+        `Generate educational content for the node type "${input.nodeType}".` +
+        ` Use the curriculum from the dependency context.` +
+        ` Output: { explanation: string, examples: string[], exercises: { question: string, answer: string }[] }.`,
+      deps: ["curriculum"],
+      timeout: 90_000,
+      maxRetries: 2,
+      priority: 5,
+    },
+    {
+      id: "visual",
+      agentId: agentIds.visual,
+      name: "VisualAgent",
+      taskDescription:
+        `Generate visual asset descriptions for the node type "${input.nodeType}".` +
+        ` You only need the curriculum context (NOT the full text content).` +
+        ` Output: { diagram: string (mermaid or ASCII), iconSuggestion: string, colorTheme: string }.`,
+      deps: ["curriculum"],
+      timeout: 120_000,
+      maxRetries: 2,
+      priority: 5,
+    },
+    {
+      id: "gamification",
+      agentId: agentIds.gamification,
+      name: "GamificationAgent",
+      taskDescription:
+        `Add a gamification layer to the educational node.` +
+        ` You have access to the generated content AND visual assets in the dependency context.` +
+        ` Output: { xpReward: number, badge: string, challengeMode: { description: string, successCriteria: string } }.`,
+      deps: ["content", "visual"],
+      timeout: 45_000,
+      maxRetries: 1,
+      priority: 0,
+    },
+  ]
+
+  return new TaskGraph(nodes)
+}

package/packages/core/src/swarm/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 HiveLearn"
+ *   )
+ *   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/swarm/presets/index.ts

@@ -0,0 +1,4 @@
+export type { HiveLearnAgentIds, HiveLearnInput } from "./HiveLearnPreset.ts";
+export { createHiveLearnGraph } from "./HiveLearnPreset.ts";
+export type { ResearchAgentIds } from "./ResearchPreset.ts";
+export { createResearchGraph } from "./ResearchPreset.ts";

package/packages/core/src/swarm/strategies/ParallelStrategy.ts

@@ -0,0 +1,21 @@
+/**
+ * ParallelStrategy — default for HiveLearn
+ *
+ * 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/swarm/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/swarm/strategies/index.ts

@@ -0,0 +1,3 @@
+export type { ExecutionStrategy } from "./ParallelStrategy.ts";
+export { ParallelStrategy } from "./ParallelStrategy.ts";
+export { PriorityStrategy } from "./PriorityStrategy.ts";

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

@@ -0,0 +1,164 @@
+/**
+ * Hive Scheduler - Type Definitions
+ * 
+ * Type interfaces for the Croner-based scheduling system.
+ * All names use "CronJob" terminology (formerly ScheduledTask).
+ */
+
+import type { Database } from "bun:sqlite";
+import type { Cron } from "croner";
+
+/**
+ * Task type: recurring uses cron expression, one_shot uses fire_at
+ */
+export type TaskType = "recurring" | "one_shot";
+
+/**
+ * Task status
+ */
+export type TaskStatus = "active" | "paused" | "completed" | "failed" | "cancelled";
+
+/**
+ * Task run status
+ */
+export type TaskRunStatus = "running" | "success" | "failed" | "timeout";
+
+/**
+ * CronJob as stored in SQLite (cron_jobs table)
+ */
+export interface CronJob {
+  id: string;
+  name: string;
+  task: string;
+  task_type: TaskType;
+  cron_expression: string | null;
+  fire_at: string | null;
+  timezone: string;
+  start_at: string | null;
+  stop_at: string | null;
+  dom_and_dow: number;
+  max_runs: number | null;
+  protect: number;
+  interval_sec: number | null;
+  agent_id: string | null;
+  channel: string;
+  payload: string;
+  tool_name: string | null;
+  status: TaskStatus;
+  run_count: number;
+  error_count: number;
+  last_error: string | null;
+  created_at: string;
+  updated_at: string;
+  last_run_at: string | null;
+  next_run_at: string | null;
+  completed_at: string | null;
+}
+
+/**
+ * Task run history record
+ */
+export interface TaskRun {
+  id: string;
+  task_id: string;
+  status: TaskRunStatus;
+  started_at: string;
+  finished_at: string | null;
+  duration_ms: number | null;
+  error_message: string | null;
+  payload_snapshot: string | null;
+  agent_response: string | null;
+}
+
+/**
+ * Input for creating a new cron job
+ */
+export interface CreateCronJobInput {
+  name: string;
+  task: string;
+  task_type: TaskType;
+  cron_expression?: string;
+  fire_at?: string;
+  timezone: string;
+  start_at?: string;
+  stop_at?: string;
+  dom_and_dow?: boolean;
+  agent_id?: string | null;
+  channel?: string;
+  payload?: Record<string, unknown>;
+  tool_name?: string | null;
+  max_runs?: number | null;
+  protect?: boolean;
+  interval_sec?: number | null;
+}
+
+/**
+ * Input for updating an existing cron job
+ */
+export interface UpdateCronJobInput {
+  name?: string;
+  task?: string;
+  task_type?: TaskType;
+  cron_expression?: string | null;
+  fire_at?: string | null;
+  timezone?: string;
+  start_at?: string | null;
+  stop_at?: string | null;
+  dom_and_dow?: boolean;
+  agent_id?: string | null;
+  channel?: string;
+  payload?: Record<string, unknown>;
+  tool_name?: string | null;
+  max_runs?: number | null;
+  protect?: boolean;
+  interval_sec?: number | null;
+  status?: TaskStatus;
+}
+
+/**
+ * Scheduler status for a cron job
+ */
+export interface CronJobStatus {
+  id: string;
+  name: string;
+  nextRun: Date | null;
+  isBusy: boolean;
+  status: TaskStatus;
+}
+
+/**
+ * Handler function type for executing cron jobs
+ */
+export type CronJobExecutionHandler = (job: CronJob) => Promise<CronJobExecutionResult>;
+
+/**
+ * Result of cron job execution
+ */
+export interface CronJobExecutionResult {
+  success: boolean;
+  response?: string;
+  error?: string;
+}
+
+/**
+ * Internal job wrapper holding Croner instance and metadata
+ */
+export interface CronJobEntry {
+  job: CronJob;
+  cron: Cron;
+}
+
+/**
+ * Options for Croner job creation
+ */
+export interface CronerOptions {
+  timezone: string;
+  protect: boolean;
+  catch: boolean | ((error: Error) => void);
+  name: string;
+  maxRuns?: number;
+  interval?: number;
+  startAt?: string;
+  stopAt?: string;
+  domAndDow?: boolean;
+}

package/packages/core/src/tools/ToolExecutor.ts

@@ -0,0 +1,58 @@
+import type { ToolDefinition } from "./ToolRegistry";
+import type { ToolRegistry } from "./ToolRegistry";
+
+export interface ToolExecutionResult {
+  toolName: string;
+  args: any;
+  result: any;
+  durationMs: number;
+  error?: string;
+}
+
+export class ToolExecutor {
+  constructor(private registry: ToolRegistry) {}
+
+  async execute(
+    name: string,
+    args: any,
+    config?: any
+  ): Promise<ToolExecutionResult> {
+    const tool = this.registry.get(name);
+    if (!tool) {
+      return {
+        toolName: name,
+        args,
+        result: null,
+        durationMs: 0,
+        error: `Tool '${name}' not found`,
+      };
+    }
+
+    const start = Date.now();
+    try {
+      const validatedArgs = tool.schema ? tool.schema.parse(args) : args;
+      const result = await tool.execute(validatedArgs, config);
+      return {
+        toolName: name,
+        args: validatedArgs,
+        result,
+        durationMs: Date.now() - start,
+      };
+    } catch (error: any) {
+      return {
+        toolName: name,
+        args,
+        result: null,
+        durationMs: Date.now() - start,
+        error: error.message || String(error),
+      };
+    }
+  }
+
+  async executeBatch(
+    calls: Array<{ name: string; args: any }>,
+    config?: any
+  ): Promise<ToolExecutionResult[]> {
+    return Promise.all(calls.map(c => this.execute(c.name, c.args, config)));
+  }
+}

package/packages/core/src/tools/ToolRegistry.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect } from "bun:test";
+import { ToolRegistry, defineTool } from "./ToolRegistry.ts";
+import { ToolExecutor } from "./ToolExecutor.ts";
+
+describe("defineTool", () => {
+	it("creates a tool definition", () => {
+		const tool = defineTool({
+			name: "hello",
+			description: "Say hello",
+			execute: async (args: { name?: string }) => ({ greeting: `Hello, ${args.name ?? "world"}!` }),
+		});
+		expect(tool.name).toBe("hello");
+		expect(tool.description).toBe("Say hello");
+	});
+});
+
+describe("ToolRegistry", () => {
+	it("register, get, has", () => {
+		const reg = new ToolRegistry();
+		const tool = defineTool({
+			name: "test",
+			description: "a test tool",
+			execute: async () => ({ ok: true }),
+		});
+		reg.register(tool);
+		expect(reg.has("test")).toBe(true);
+		expect(reg.get("test")).toBe(tool);
+		expect(reg.get("nope")).toBeUndefined();
+	});
+
+	it("throws on duplicate registration", () => {
+		const reg = new ToolRegistry();
+		reg.register(defineTool({ name: "dup", description: "", execute: async () => ({}) }));
+		expect(() =>
+			reg.register(defineTool({ name: "dup", description: "", execute: async () => ({}) }))
+		).toThrow("already registered");
+	});
+
+	it("lists and categorizes", () => {
+		const reg = new ToolRegistry();
+		reg.register(defineTool({ name: "a", description: "", category: "web", execute: async () => ({}) }));
+		reg.register(defineTool({ name: "b", description: "", category: "fs", execute: async () => ({}) }));
+		reg.register(defineTool({ name: "c", description: "", category: "web", execute: async () => ({}) }));
+		expect(reg.size()).toBe(3);
+		expect(reg.list()).toHaveLength(3);
+		expect(reg.getByCategory("web")).toHaveLength(2);
+		expect(reg.getNames()).toEqual(["a", "b", "c"]);
+	});
+
+	it("merge and clear", () => {
+		const a = new ToolRegistry();
+		const b = new ToolRegistry();
+		a.register(defineTool({ name: "x", description: "", execute: async () => ({}) }));
+		b.register(defineTool({ name: "y", description: "", execute: async () => ({}) }));
+		a.merge(b);
+		expect(a.size()).toBe(2);
+		a.clear();
+		expect(a.size()).toBe(0);
+	});
+});
+
+describe("ToolExecutor", () => {
+	it("executes a registered tool", async () => {
+		const reg = new ToolRegistry();
+		reg.register(
+			defineTool({
+				name: "echo",
+				description: "echo args",
+				execute: async (args) => args,
+			})
+		);
+		const exec = new ToolExecutor(reg);
+		const result = await exec.execute("echo", { msg: "hi" });
+		expect(result.toolName).toBe("echo");
+		expect(result.result).toEqual({ msg: "hi" });
+		expect(result.error).toBeUndefined();
+		expect(result.durationMs).toBeGreaterThanOrEqual(0);
+	});
+
+	it("returns error for unknown tool", async () => {
+		const exec = new ToolExecutor(new ToolRegistry());
+		const result = await exec.execute("ghost", {});
+		expect(result.error).toBeString();
+		expect(result.error).toContain("not found");
+	});
+
+	it("executes batch", async () => {
+		const reg = new ToolRegistry();
+		reg.register(defineTool({ name: "t1", description: "", execute: async () => 1 }));
+		reg.register(defineTool({ name: "t2", description: "", execute: async () => 2 }));
+		const exec = new ToolExecutor(reg);
+		const results = await exec.executeBatch([{ name: "t1", args: {} }, { name: "t2", args: {} }, { name: "nope", args: {} }]);
+		expect(results).toHaveLength(3);
+		expect(results[0].result).toBe(1);
+		expect(results[1].result).toBe(2);
+		expect(results[2].error).toBeString();
+	});
+});

package/packages/core/src/tools/ToolRegistry.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  schema?: z.ZodType;
+  execute: (args: any, config?: any) => Promise<any>;
+  category?: string;
+  abstractionLevel?: "atomic" | "orchestration";
+}
+
+export class ToolRegistry {
+  private tools: Map<string, ToolDefinition> = new Map();
+
+  register(tool: ToolDefinition): void {
+    if (this.tools.has(tool.name)) {
+      throw new Error(`Tool '${tool.name}' already registered`);
+    }
+    this.tools.set(tool.name, tool);
+  }
+
+  get(name: string): ToolDefinition | undefined {
+    return this.tools.get(name);
+  }
+
+  has(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  list(): ToolDefinition[] {
+    return Array.from(this.tools.values());
+  }
+
+  getByCategory(category: string): ToolDefinition[] {
+    return this.list().filter(t => t.category === category);
+  }
+
+  getNames(): string[] {
+    return Array.from(this.tools.keys());
+  }
+
+  size(): number {
+    return this.tools.size;
+  }
+
+  merge(other: ToolRegistry): void {
+    for (const tool of other.list()) {
+      if (!this.tools.has(tool.name)) {
+        this.tools.set(tool.name, tool);
+      }
+    }
+  }
+
+  clear(): void {
+    this.tools.clear();
+  }
+}
+
+export function defineTool(config: ToolDefinition): ToolDefinition {
+  return config;
+}