@clawswarm/core 0.1.0-alpha → 0.2.0-alpha

package/src/goal.ts

@@ -1,183 +0,0 @@
-/**
- * Goal decomposition and planning.
- * @module @clawswarm/core/goal
- */
-
-import { Goal, GoalStatus, CreateGoalInput, Task, AgentType, SwarmConfig } from './types.js';
-import { TaskManager } from './task.js';
-
-// ─── Goal Planner ─────────────────────────────────────────────────────────────
-
-/**
- * Decomposes high-level goals into concrete, assignable tasks.
- *
- * The Planner analyzes a goal description and generates a task plan,
- * assigns each task to the appropriate specialist agent, and sequences
- * tasks based on their dependencies.
- *
- * @example
- * ```typescript
- * const planner = new GoalPlanner(swarmConfig);
- * const tasks = await planner.decompose(goal, taskManager);
- * ```
- */
-export class GoalPlanner {
-  constructor(private readonly config: SwarmConfig) {}
-
-  /**
-   * Decompose a goal into a list of tasks.
-   * Creates tasks via the TaskManager and returns them in execution order.
-   */
-  async decompose(goal: Goal, taskManager: TaskManager): Promise<Task[]> {
-    const plan = await this._generatePlan(goal);
-    const tasks: Task[] = [];
-
-    // Create tasks from plan (maintaining dependency ordering)
-    for (const step of plan) {
-      const task = taskManager.create({
-        goalId: goal.id,
-        title: step.title,
-        description: step.description,
-        assignedTo: step.agentType,
-        dependsOn: step.dependsOnTitles
-          ? tasks
-            .filter(t => step.dependsOnTitles!.includes(t.title))
-            .map(t => t.id)
-          : [],
-      });
-      tasks.push(task);
-    }
-
-    return tasks;
-  }
-
-  /**
-   * Generate a task plan for a goal.
-   * In production, this calls an LLM with the planner system prompt.
-   * Returns structured step definitions.
-   */
-  private async _generatePlan(goal: Goal): Promise<PlanStep[]> {
-    // TODO: Replace with actual LLM call
-    // This stub returns a basic 3-step plan as an example
-    return [
-      {
-        title: `Research: ${goal.title}`,
-        description: `Research and gather background information for: ${goal.description}`,
-        agentType: 'research' as AgentType,
-      },
-      {
-        title: `Execute: ${goal.title}`,
-        description: `Based on research, implement the core work for: ${goal.description}`,
-        agentType: this._inferPrimaryAgent(goal),
-        dependsOnTitles: [`Research: ${goal.title}`],
-      },
-      {
-        title: `Review: ${goal.title}`,
-        description: `Verify and validate the output for: ${goal.description}`,
-        agentType: 'research' as AgentType,
-        dependsOnTitles: [`Execute: ${goal.title}`],
-      },
-    ];
-  }
-
-  /**
-   * Infer the primary execution agent type from the goal description.
-   */
-  private _inferPrimaryAgent(goal: Goal): AgentType {
-    const desc = `${goal.title} ${goal.description}`.toLowerCase();
-
-    if (/deploy|infrastructure|k8s|docker|ci\/cd|monitoring|server/.test(desc)) {
-      return 'ops';
-    }
-    if (/code|build|implement|function|api|test|debug|refactor/.test(desc)) {
-      return 'code';
-    }
-    if (/research|analyze|report|summarize|find|investigate/.test(desc)) {
-      return 'research';
-    }
-
-    return 'code'; // default
-  }
-}
-
-// ─── Goal Manager ─────────────────────────────────────────────────────────────
-
-/**
- * Manages the lifecycle of goals in a ClawSwarm instance.
- */
-export class GoalManager {
-  private goals: Map<string, Goal> = new Map();
-
-  /**
-   * Create a new goal.
-   */
-  create(input: CreateGoalInput): Goal {
-    const goal: Goal = {
-      ...input,
-      id: `goal-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
-      status: 'created',
-      tasks: [],
-      deliverables: [],
-      priority: input.priority ?? 0,
-      tags: input.tags ?? [],
-      cost: {
-        totalTokens: 0,
-        estimatedCostUsd: 0,
-        byAgent: {},
-      },
-      createdAt: new Date().toISOString(),
-    };
-    this.goals.set(goal.id, goal);
-    return goal;
-  }
-
-  /**
-   * Get a goal by ID.
-   */
-  get(goalId: string): Goal | undefined {
-    return this.goals.get(goalId);
-  }
-
-  /**
-   * Get all goals.
-   */
-  getAll(): Goal[] {
-    return Array.from(this.goals.values());
-  }
-
-  /**
-   * Update a goal's status.
-   */
-  setStatus(goalId: string, status: GoalStatus): Goal {
-    const goal = this._getOrThrow(goalId);
-    goal.status = status;
-    if (status === 'completed') {
-      goal.completedAt = new Date().toISOString();
-    }
-    return goal;
-  }
-
-  /**
-   * Attach tasks to a goal.
-   */
-  setTasks(goalId: string, tasks: Goal['tasks']): Goal {
-    const goal = this._getOrThrow(goalId);
-    goal.tasks = tasks;
-    return goal;
-  }
-
-  private _getOrThrow(goalId: string): Goal {
-    const goal = this.goals.get(goalId);
-    if (!goal) throw new Error(`Goal not found: ${goalId}`);
-    return goal;
-  }
-}
-
-// ─── Internal Types ───────────────────────────────────────────────────────────
-
-interface PlanStep {
-  title: string;
-  description: string;
-  agentType: AgentType;
-  dependsOnTitles?: string[];
-}

package/src/index.ts

@@ -1,62 +0,0 @@
-/**
- * @clawswarm/core — Public API
- *
- * The main entry point for the ClawSwarm framework.
- * Import everything you need from this barrel export.
- *
- * @example
- * ```typescript
- * import { ClawSwarm, Agent, GoalManager, TaskManager, ChiefReviewer } from '@clawswarm/core';
- * ```
- *
- * @module @clawswarm/core
- */
-
-// ─── Main Class ───────────────────────────────────────────────────────────────
-export { ClawSwarm } from './clawswarm.js';
-
-// ─── Agent ────────────────────────────────────────────────────────────────────
-export { Agent } from './agent.js';
-
-// ─── Goal ─────────────────────────────────────────────────────────────────────
-export { GoalManager, GoalPlanner } from './goal.js';
-
-// ─── Task ─────────────────────────────────────────────────────────────────────
-export { TaskManager } from './task.js';
-
-// ─── Chief Review ─────────────────────────────────────────────────────────────
-export { ChiefReviewer } from './chief.js';
-
-// ─── Types ────────────────────────────────────────────────────────────────────
-export type {
-  // Agent types
-  AgentType,
-  AgentStatus,
-  AgentConfig,
-  ModelId,
-
-  // Task types
-  TaskStatus,
-  Task,
-  Deliverable,
-
-  // Goal types
-  GoalStatus,
-  Goal,
-  CreateGoalInput,
-
-  // Review types
-  ReviewResult,
-  ChiefReviewConfig,
-
-  // Cost tracking
-  TokenUsage,
-  CostSummary,
-
-  // Events
-  SwarmEvents,
-
-  // Config
-  SwarmConfig,
-  GoalResult,
-} from './types.js';

package/src/swarm.ts

@@ -1,225 +0,0 @@
-/**
- * ClawSwarm — the top-level orchestrator.
- * @module @clawswarm/core/swarm
- */
-
-import EventEmitter from 'eventemitter3';
-import {
-  SwarmConfig,
-  GoalResult,
-  CreateGoalInput,
-  Goal,
-  Task,
-  AgentType,
-  SwarmEvents,
-} from './types.js';
-import { Agent } from './agent.js';
-import { TaskManager } from './task.js';
-import { GoalManager, GoalPlanner } from './goal.js';
-import { ChiefReviewer } from './chief.js';
-
-/**
- * ClawSwarm — deploy and orchestrate a team of AI agents.
- *
- * @example
- * ```typescript
- * const swarm = new ClawSwarm({
- *   agents: [
- *     Agent.research({ model: 'claude-sonnet-4' }),
- *     Agent.code({ model: 'gpt-4o' }),
- *     Agent.ops({ model: 'gemini-pro' }),
- *   ],
- *   chiefReview: {
- *     autoApproveThreshold: 8,
- *     humanReviewThreshold: 5,
- *   },
- * });
- *
- * swarm.on('task:completed', (task) => console.log('Done:', task.title));
- *
- * const goal = await swarm.createGoal({
- *   title: 'Write a blog post about AI',
- *   description: 'Research AI trends and write a 1000-word post',
- * });
- *
- * const result = await swarm.execute(goal);
- * ```
- */
-export class ClawSwarm extends EventEmitter<SwarmEvents> {
-  private readonly config: SwarmConfig;
-  private readonly agents: Agent[];
-  private readonly taskManager: TaskManager;
-  private readonly goalManager: GoalManager;
-  private readonly planner: GoalPlanner;
-  private readonly reviewer: ChiefReviewer;
-
-  constructor(config: SwarmConfig) {
-    super();
-    this.config = config;
-    this.agents = config.agents.map(c => new Agent(c));
-    this.taskManager = new TaskManager();
-    this.goalManager = new GoalManager();
-    this.planner = new GoalPlanner(config);
-    this.reviewer = new ChiefReviewer(config.chiefReview);
-  }
-
-  /**
-   * Create a new goal. Does not start execution yet.
-   *
-   * @param input - Goal title, description, and optional metadata
-   * @returns The created goal
-   */
-  async createGoal(input: CreateGoalInput): Promise<Goal> {
-    const goal = this.goalManager.create(input);
-    this.emit('goal:created', goal);
-    return goal;
-  }
-
-  /**
-   * Execute a goal: plan, assign, run, review, and collect results.
-   *
-   * @param goal - The goal to execute (from createGoal)
-   * @returns Final result with deliverables and cost summary
-   */
-  async execute(goal: Goal): Promise<GoalResult> {
-    const startTime = Date.now();
-
-    try {
-      // 1. Planning phase
-      this.goalManager.setStatus(goal.id, 'planning');
-      this.emit('goal:planning', goal);
-
-      const tasks = await this.planner.decompose(goal, this.taskManager);
-      this.goalManager.setTasks(goal.id, tasks);
-
-      // 2. Execution phase
-      this.goalManager.setStatus(goal.id, 'in_progress');
-
-      let hadHumanReview = false;
-
-      // Execute tasks in dependency order
-      while (!this.taskManager.isGoalDone(goal.id)) {
-        const readyTasks = this.taskManager.getReady(goal.id);
-        if (readyTasks.length === 0) break;
-
-        // Run all ready tasks (can parallelize)
-        await Promise.all(
-          readyTasks.map(async (task) => {
-            const result = await this._executeTask(task);
-            if (result.hadHumanReview) hadHumanReview = true;
-          })
-        );
-      }
-
-      // 3. Collect results
-      const completedTasks = this.taskManager
-        .getByGoal(goal.id)
-        .filter(t => t.status === 'completed');
-
-      const deliverables = completedTasks.flatMap(t => t.deliverables);
-
-      const finalGoal = this.goalManager.setStatus(goal.id, 'completed');
-      this.emit('goal:completed', finalGoal);
-
-      return {
-        goal: finalGoal,
-        deliverables,
-        cost: finalGoal.cost,
-        hadHumanReview,
-        durationMs: Date.now() - startTime,
-      };
-    } catch (error) {
-      const err = error instanceof Error ? error : new Error(String(error));
-      const failedGoal = this.goalManager.setStatus(goal.id, 'failed');
-      this.emit('goal:failed', failedGoal, err);
-      throw err;
-    }
-  }
-
-  /**
-   * Get all agents in this swarm.
-   */
-  getAgents(): Agent[] {
-    return [...this.agents];
-  }
-
-  /**
-   * Get an agent by type.
-   */
-  getAgent(type: AgentType): Agent | undefined {
-    return this.agents.find(a => a.type === type && a.status === 'idle');
-  }
-
-  // ─── Private ──────────────────────────────────────────────────────────────
-
-  private async _executeTask(task: Task): Promise<{ hadHumanReview: boolean }> {
-    let hadHumanReview = false;
-
-    try {
-      // Assign to agent
-      const agentType = task.assignedTo ?? 'code';
-      const agent = this.getAgent(agentType);
-
-      if (!agent) {
-        throw new Error(`No available agent of type: ${agentType}`);
-      }
-
-      this.taskManager.assign(task.id, agentType);
-      this.emit('task:assigned', task, agentType);
-
-      // Execute
-      agent.status = 'busy';
-      this.taskManager.start(task.id);
-      this.emit('task:started', task);
-
-      const deliverables = await agent.execute(task);
-      agent.status = 'idle';
-
-      // Submit for review
-      const updatedTask = this.taskManager.submitForReview(task.id, deliverables);
-
-      // Run through chief review
-      let approved = false;
-      while (!approved) {
-        const review = await this.reviewer.review(updatedTask);
-        this.emit('task:review', updatedTask, review);
-
-        if (review.decision === 'approved') {
-          this.taskManager.approve(task.id);
-          this.taskManager.complete(task.id);
-          this.emit('task:completed', updatedTask);
-          approved = true;
-        } else if (review.decision === 'human_review') {
-          hadHumanReview = true;
-          this.emit('human:review_required', updatedTask, review);
-          // In production: wait for human decision via webhook/callback
-          // For now, auto-approve after emitting
-          this.taskManager.approve(task.id);
-          this.taskManager.complete(task.id);
-          approved = true;
-        } else {
-          // Rejected — attempt rework
-          this.emit('task:rejected', updatedTask, review);
-          try {
-            this.taskManager.rework(task.id, review.feedback);
-            this.emit('task:rework', updatedTask, review);
-            // Re-run with agent
-            const reworkDeliverables = await agent.execute(updatedTask);
-            this.taskManager.submitForReview(task.id, reworkDeliverables);
-          } catch {
-            // Max rework exceeded
-            this.taskManager.reject(task.id, review.feedback);
-            this.emit('task:failed', updatedTask, new Error('Max rework cycles exceeded'));
-            approved = true; // exit loop
-          }
-        }
-      }
-    } catch (error) {
-      const err = error instanceof Error ? error : new Error(String(error));
-      this.taskManager.fail(task.id, err);
-      this.emit('task:failed', task, err);
-    }
-
-    return { hadHumanReview };
-  }
-}

package/src/task.ts

@@ -1,204 +0,0 @@
-/**
- * Task lifecycle management.
- * @module @clawswarm/core/task
- */
-
-import { Task, TaskStatus, AgentType, Deliverable } from './types.js';
-
-// ─── Task Manager ─────────────────────────────────────────────────────────────
-
-/**
- * Manages the lifecycle of tasks within a goal.
- * Handles state transitions, rework cycles, and deliverable collection.
- *
- * @example
- * ```typescript
- * const manager = new TaskManager();
- * const task = manager.create({
- *   goalId: 'goal-123',
- *   title: 'Research AI trends',
- *   description: 'Find the top 5 AI trends in 2026',
- *   assignedTo: 'research',
- * });
- *
- * manager.start(task.id);
- * manager.complete(task.id, [{ type: 'text', label: 'Report', content: '...' }]);
- * ```
- */
-export class TaskManager {
-  private tasks: Map<string, Task> = new Map();
-
-  /**
-   * Create a new task.
-   */
-  create(input: Omit<Task, 'id' | 'status' | 'deliverables' | 'reworkCount' | 'maxReworkCycles' | 'createdAt' | 'updatedAt'>): Task {
-    const task: Task = {
-      ...input,
-      id: `task-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
-      status: 'pending',
-      deliverables: [],
-      reworkCount: 0,
-      maxReworkCycles: 3,
-      dependsOn: input.dependsOn ?? [],
-      createdAt: new Date().toISOString(),
-      updatedAt: new Date().toISOString(),
-    };
-    this.tasks.set(task.id, task);
-    return task;
-  }
-
-  /**
-   * Get a task by ID.
-   */
-  get(taskId: string): Task | undefined {
-    return this.tasks.get(taskId);
-  }
-
-  /**
-   * Get all tasks.
-   */
-  getAll(): Task[] {
-    return Array.from(this.tasks.values());
-  }
-
-  /**
-   * Get tasks by goal ID.
-   */
-  getByGoal(goalId: string): Task[] {
-    return this.getAll().filter(t => t.goalId === goalId);
-  }
-
-  /**
-   * Get tasks that are ready to run (all dependencies completed).
-   */
-  getReady(goalId: string): Task[] {
-    const tasks = this.getByGoal(goalId);
-    const completedIds = new Set(
-      tasks.filter(t => t.status === 'completed').map(t => t.id)
-    );
-
-    return tasks.filter(t =>
-      t.status === 'pending' &&
-      t.dependsOn.every(depId => completedIds.has(depId))
-    );
-  }
-
-  /**
-   * Assign a task to an agent type.
-   */
-  assign(taskId: string, agentType: AgentType): Task {
-    return this._transition(taskId, 'assigned', task => {
-      task.assignedTo = agentType;
-    });
-  }
-
-  /**
-   * Mark a task as in progress.
-   */
-  start(taskId: string): Task {
-    return this._transition(taskId, 'in_progress');
-  }
-
-  /**
-   * Submit a task for review with its deliverables.
-   */
-  submitForReview(taskId: string, deliverables: Deliverable[]): Task {
-    return this._transition(taskId, 'review', task => {
-      task.deliverables = deliverables;
-    });
-  }
-
-  /**
-   * Mark a task as approved.
-   */
-  approve(taskId: string): Task {
-    return this._transition(taskId, 'approved');
-  }
-
-  /**
-   * Mark a task as completed (after approval and any post-processing).
-   */
-  complete(taskId: string): Task {
-    return this._transition(taskId, 'completed');
-  }
-
-  /**
-   * Mark a task for rework. Increments rework counter.
-   * @throws If max rework cycles exceeded
-   */
-  rework(taskId: string, feedback: string): Task {
-    const task = this._getOrThrow(taskId);
-
-    if (task.reworkCount >= task.maxReworkCycles) {
-      throw new Error(
-        `Task ${taskId} has exceeded max rework cycles (${task.maxReworkCycles}). Failing task.`
-      );
-    }
-
-    return this._transition(taskId, 'rework', t => {
-      t.reworkCount += 1;
-      // Store feedback as a note in deliverables for the agent to reference
-      t.deliverables = [
-        ...t.deliverables,
-        {
-          type: 'text',
-          label: `Rework Feedback (Cycle ${t.reworkCount})`,
-          content: feedback,
-        },
-      ];
-    });
-  }
-
-  /**
-   * Mark a task as rejected (max rework exceeded or explicitly rejected).
-   */
-  reject(taskId: string, reason: string): Task {
-    return this._transition(taskId, 'rejected', task => {
-      task.deliverables = [
-        ...task.deliverables,
-        { type: 'text', label: 'Rejection Reason', content: reason },
-      ];
-    });
-  }
-
-  /**
-   * Mark a task as failed (unexpected error).
-   */
-  fail(taskId: string, error: Error): Task {
-    return this._transition(taskId, 'failed', task => {
-      task.deliverables = [
-        ...task.deliverables,
-        { type: 'text', label: 'Error', content: error.message },
-      ];
-    });
-  }
-
-  /**
-   * Check if a goal has all tasks completed or failed.
-   */
-  isGoalDone(goalId: string): boolean {
-    const tasks = this.getByGoal(goalId);
-    if (tasks.length === 0) return false;
-    return tasks.every(t => t.status === 'completed' || t.status === 'failed' || t.status === 'rejected');
-  }
-
-  // ─── Private ──────────────────────────────────────────────────────────────
-
-  private _transition(
-    taskId: string,
-    status: TaskStatus,
-    mutate?: (task: Task) => void
-  ): Task {
-    const task = this._getOrThrow(taskId);
-    task.status = status;
-    task.updatedAt = new Date().toISOString();
-    mutate?.(task);
-    return task;
-  }
-
-  private _getOrThrow(taskId: string): Task {
-    const task = this.tasks.get(taskId);
-    if (!task) throw new Error(`Task not found: ${taskId}`);
-    return task;
-  }
-}