@clawswarm/core 0.1.0-alpha

package/src/agent.ts

@@ -0,0 +1,163 @@
+/**
+ * Base Agent class and specialist agent factories.
+ * @module @clawswarm/core/agent
+ */
+
+import { AgentConfig, AgentStatus, AgentType, ModelId, Task, Deliverable } from './types.js';
+
+// ─── Agent Base Class ─────────────────────────────────────────────────────────
+
+/**
+ * Base class for all ClawSwarm agents.
+ * Extend this to create custom specialist agents.
+ *
+ * @example
+ * ```typescript
+ * class MyCustomAgent extends Agent {
+ *   async execute(task: Task): Promise<Deliverable[]> {
+ *     // your custom logic here
+ *     return [{ type: 'text', label: 'Output', content: '...' }];
+ *   }
+ * }
+ * ```
+ */
+export class Agent {
+  public readonly id: string;
+  public readonly config: AgentConfig;
+  public status: AgentStatus = 'idle';
+  public currentTaskId?: string;
+
+  constructor(config: AgentConfig) {
+    this.config = config;
+    this.id = `agent-${config.type}-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+  }
+
+  /** Agent's display name */
+  get name(): string {
+    return this.config.name ?? this._defaultName(this.config.type);
+  }
+
+  /** Agent's specialization type */
+  get type(): AgentType {
+    return this.config.type;
+  }
+
+  /**
+   * Execute a task and return deliverables.
+   * Override this in custom agents.
+   *
+   * @param task - The task to execute
+   * @returns Array of deliverables produced
+   */
+  async execute(task: Task): Promise<Deliverable[]> {
+    throw new Error(`Agent.execute() must be implemented. Agent: ${this.name}, Task: ${task.id}`);
+  }
+
+  /**
+   * Check if this agent can handle a given task type.
+   * Override to restrict which tasks this agent accepts.
+   */
+  canHandle(_task: Task): boolean {
+    return true;
+  }
+
+  /**
+   * Get the system prompt for this agent.
+   * Override to customize the agent's behavior.
+   */
+  getSystemPrompt(): string {
+    return this.config.systemPrompt ?? this._defaultSystemPrompt(this.config.type);
+  }
+
+  // ─── Factory Methods ─────────────────────────────────────────────────────────
+
+  /**
+   * Create a ResearchClaw agent.
+   * Specializes in information gathering, analysis, and written reports.
+   */
+  static research(options: Partial<AgentConfig> & { model: ModelId }): AgentConfig {
+    return {
+      type: 'research',
+      name: 'ResearchClaw',
+      tools: ['web_search', 'web_fetch', 'summarize'],
+      ...options,
+    };
+  }
+
+  /**
+   * Create a CodeClaw agent.
+   * Specializes in writing, reviewing, and debugging code.
+   */
+  static code(options: Partial<AgentConfig> & { model: ModelId }): AgentConfig {
+    return {
+      type: 'code',
+      name: 'CodeClaw',
+      tools: ['read_file', 'write_file', 'execute_code', 'run_tests'],
+      ...options,
+    };
+  }
+
+  /**
+   * Create an OpsClaw agent.
+   * Specializes in infrastructure, deployment, and monitoring.
+   */
+  static ops(options: Partial<AgentConfig> & { model: ModelId }): AgentConfig {
+    return {
+      type: 'ops',
+      name: 'OpsClaw',
+      tools: ['shell', 'docker', 'kubernetes', 'monitoring'],
+      ...options,
+    };
+  }
+
+  /**
+   * Create a Planner agent.
+   * Decomposes goals into tasks and assigns them to specialist agents.
+   */
+  static planner(options: Partial<AgentConfig> & { model: ModelId }): AgentConfig {
+    return {
+      type: 'planner',
+      name: 'Planner',
+      tools: [],
+      ...options,
+    };
+  }
+
+  // ─── Private Helpers ─────────────────────────────────────────────────────────
+
+  private _defaultName(type: AgentType): string {
+    const names: Record<AgentType, string> = {
+      research: 'ResearchClaw',
+      code: 'CodeClaw',
+      ops: 'OpsClaw',
+      planner: 'Planner',
+      custom: 'CustomAgent',
+    };
+    return names[type] ?? 'Agent';
+  }
+
+  private _defaultSystemPrompt(type: AgentType): string {
+    const prompts: Record<AgentType, string> = {
+      research: `You are ResearchClaw, a specialist research agent. 
+Your job is to gather information, analyze data, synthesize findings, and produce clear written reports.
+Always cite your sources. Prioritize accuracy over speed. Flag uncertainty explicitly.`,
+
+      code: `You are CodeClaw, a specialist software engineering agent.
+Your job is to write clean, well-tested, production-ready code.
+Follow best practices for the language/framework. Write tests. Document your code.
+Never ship broken code.`,
+
+      ops: `You are OpsClaw, a specialist infrastructure and operations agent.
+Your job is to deploy, monitor, and optimize systems.
+Prefer idempotent operations. Document every change. Always have a rollback plan.`,
+
+      planner: `You are the Planner, responsible for decomposing high-level goals into concrete tasks.
+Break goals into the smallest meaningful units of work.
+Assign each task to the most appropriate specialist agent.
+Identify dependencies between tasks and sequence them correctly.`,
+
+      custom: `You are a custom ClawSwarm agent. Follow your configured instructions.`,
+    };
+    return prompts[type] ?? prompts.custom;
+  }
+}

package/src/chief.ts

@@ -0,0 +1,264 @@
+/**
+ * Chief review pipeline — the quality gate for ClawSwarm.
+ *
+ * Every task deliverable passes through a 3-tier scoring system:
+ *   - Score ≥ autoApproveThreshold (default 8) → auto-approved
+ *   - Score ≥ humanReviewThreshold (default 5) → human review required
+ *   - Score < humanReviewThreshold             → auto-rejected + rework
+ *
+ * @module @clawswarm/core/chief
+ */
+
+import EventEmitter from 'eventemitter3';
+import {
+  Task,
+  ReviewResult,
+  ChiefReviewConfig,
+  ModelId,
+} from './types.js';
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const DEFAULT_AUTO_APPROVE_THRESHOLD = 8;
+const DEFAULT_HUMAN_REVIEW_THRESHOLD = 5;
+const DEFAULT_REVIEWER_MODEL: ModelId = 'claude-sonnet-4';
+
+const DEFAULT_CRITERIA = [
+  'completeness: Does the output fully address the task requirements?',
+  'accuracy: Is the information correct and well-sourced?',
+  'quality: Is the output production-ready (no TODOs, no placeholders)?',
+  'clarity: Is the output clear, well-structured, and easy to understand?',
+  'safety: Does the output avoid harmful, biased, or problematic content?',
+];
+
+// ─── Chief Reviewer ───────────────────────────────────────────────────────────
+
+/**
+ * The Chief Reviewer evaluates task deliverables against a rubric
+ * and decides whether to approve, send for human review, or reject.
+ *
+ * @example
+ * ```typescript
+ * const reviewer = new ChiefReviewer({
+ *   autoApproveThreshold: 8,
+ *   humanReviewThreshold: 5,
+ *   reviewerModel: 'claude-opus-4',
+ *   criteria: ['completeness', 'accuracy', 'quality'],
+ * });
+ *
+ * const result = await reviewer.review(task);
+ *
+ * if (result.decision === 'approved') {
+ *   console.log('✅ Task approved!', result.score);
+ * } else if (result.decision === 'human_review') {
+ *   console.log('👀 Needs human review', result.feedback);
+ * } else {
+ *   console.log('❌ Rejected:', result.issues);
+ * }
+ * ```
+ */
+export class ChiefReviewer extends EventEmitter {
+  private readonly autoApproveThreshold: number;
+  private readonly humanReviewThreshold: number;
+  private readonly reviewerModel: ModelId;
+  private readonly criteria: string[];
+
+  constructor(config: ChiefReviewConfig = {}) {
+    super();
+    this.autoApproveThreshold = config.autoApproveThreshold ?? DEFAULT_AUTO_APPROVE_THRESHOLD;
+    this.humanReviewThreshold = config.humanReviewThreshold ?? DEFAULT_HUMAN_REVIEW_THRESHOLD;
+    this.reviewerModel = config.reviewerModel ?? DEFAULT_REVIEWER_MODEL;
+    this.criteria = config.criteria ?? DEFAULT_CRITERIA;
+
+    this._validateThresholds();
+  }
+
+  /**
+   * Review a task and produce a structured ReviewResult.
+   *
+   * @param task - The task to review (must have deliverables)
+   * @returns A ReviewResult with score, decision, and feedback
+   */
+  async review(task: Task): Promise<ReviewResult> {
+    if (task.deliverables.length === 0) {
+      return this._buildResult(task.id, 0, [], ['No deliverables were produced by the agent.'], []);
+    }
+
+    // In production: call LLM with structured review prompt
+    const raw = await this._callReviewerLLM(task);
+
+    const result = this._buildResult(
+      task.id,
+      raw.score,
+      raw.issues,
+      raw.suggestions,
+      raw.feedback
+    );
+
+    this.emit('reviewed', result);
+    return result;
+  }
+
+  /**
+   * Synchronously check what decision would be made for a given score.
+   * Useful for dry-runs and testing.
+   */
+  scoreToDecision(score: number): ReviewResult['decision'] {
+    if (score >= this.autoApproveThreshold) return 'approved';
+    if (score >= this.humanReviewThreshold) return 'human_review';
+    return 'rejected';
+  }
+
+  /**
+   * Get the current review configuration (read-only).
+   */
+  get config(): Required<ChiefReviewConfig> {
+    return {
+      autoApproveThreshold: this.autoApproveThreshold,
+      humanReviewThreshold: this.humanReviewThreshold,
+      reviewerModel: this.reviewerModel,
+      criteria: this.criteria,
+    };
+  }
+
+  // ─── Private ──────────────────────────────────────────────────────────────
+
+  /**
+   * Build a review prompt for the LLM.
+   * @internal
+   */
+  private _buildPrompt(task: Task): string {
+    const deliverablesSummary = task.deliverables
+      .map((d, i) => `[${i + 1}] ${d.label} (${d.type}):\n${d.content.slice(0, 2000)}`)
+      .join('\n\n');
+
+    const criteriaList = this.criteria.map((c, i) => `${i + 1}. ${c}`).join('\n');
+
+    return `You are a Chief Reviewer for an AI agent system. Your job is to objectively score the quality of agent-produced work.
+
+## Task
+Title: ${task.title}
+Description: ${task.description}
+
+## Deliverables
+${deliverablesSummary}
+
+## Review Criteria (score each 0-10, then average)
+${criteriaList}
+
+## Instructions
+1. Score each criterion from 0 to 10
+2. Identify specific issues (things that are wrong or missing)
+3. Provide concrete suggestions for improvement
+4. Give an overall score (0-10) and a 2-3 sentence summary
+
+Respond in JSON:
+{
+  "criteriaScores": { "<criterion>": <score> },
+  "overallScore": <number>,
+  "issues": ["<issue1>", ...],
+  "suggestions": ["<suggestion1>", ...],
+  "feedback": "<2-3 sentence summary>"
+}`;
+  }
+
+  /**
+   * Call the LLM reviewer. In production, replace the stub with a real LLM call.
+   * @internal
+   */
+  private async _callReviewerLLM(task: Task): Promise<RawReviewResponse> {
+    // ── Production stub ──────────────────────────────────────────────────────
+    // Replace this with your actual LLM client call, e.g.:
+    //
+    //   const response = await openai.chat.completions.create({
+    //     model: this.reviewerModel,
+    //     messages: [{ role: 'user', content: this._buildPrompt(task) }],
+    //     response_format: { type: 'json_object' },
+    //   });
+    //   return JSON.parse(response.choices[0].message.content!);
+    //
+    // ────────────────────────────────────────────────────────────────────────
+
+    void this._buildPrompt(task); // reference so it's not dead code
+
+    // Stub: evaluate based on deliverable completeness heuristics
+    const hasContent = task.deliverables.some(d => d.content.trim().length > 100);
+    const hasTodo = task.deliverables.some(d => /TODO|FIXME|placeholder/i.test(d.content));
+    const hasCode = task.deliverables.some(d => d.type === 'code');
+    const contentLength = task.deliverables.reduce((sum, d) => sum + d.content.length, 0);
+
+    let score = hasContent ? 7 : 3;
+    if (hasTodo) score -= 2;
+    if (hasCode && contentLength > 500) score += 1;
+    score = Math.max(0, Math.min(10, score));
+
+    const issues: string[] = [];
+    const suggestions: string[] = [];
+
+    if (!hasContent) issues.push('Deliverables appear to be empty or too short.');
+    if (hasTodo) {
+      issues.push('Output contains TODO/FIXME markers — not production-ready.');
+      suggestions.push('Complete all TODO items before submitting.');
+    }
+    if (contentLength < 200) suggestions.push('Expand the output with more detail.');
+
+    return {
+      score,
+      issues,
+      suggestions,
+      feedback: issues.length === 0
+        ? 'Work looks complete and meets the task requirements.'
+        : `Found ${issues.length} issue(s) that need attention before approval.`,
+    };
+  }
+
+  /**
+   * Assemble a ReviewResult from raw LLM data.
+   * @internal
+   */
+  private _buildResult(
+    taskId: string,
+    score: number,
+    issues: string[],
+    suggestions: string[],
+    feedback: string | string[]
+  ): ReviewResult {
+    const clampedScore = Math.max(0, Math.min(10, score));
+    const feedbackStr = Array.isArray(feedback) ? feedback.join(' ') : feedback;
+
+    return {
+      taskId,
+      score: clampedScore,
+      decision: this.scoreToDecision(clampedScore),
+      feedback: feedbackStr,
+      issues,
+      suggestions,
+      reviewedAt: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Validate that thresholds are logically consistent.
+   * @internal
+   */
+  private _validateThresholds(): void {
+    if (this.autoApproveThreshold < this.humanReviewThreshold) {
+      throw new Error(
+        `ChiefReviewer: autoApproveThreshold (${this.autoApproveThreshold}) must be ` +
+        `>= humanReviewThreshold (${this.humanReviewThreshold})`
+      );
+    }
+    if (this.autoApproveThreshold > 10 || this.humanReviewThreshold < 0) {
+      throw new Error('ChiefReviewer: thresholds must be between 0 and 10');
+    }
+  }
+}
+
+// ─── Internal Types ───────────────────────────────────────────────────────────
+
+interface RawReviewResponse {
+  score: number;
+  issues: string[];
+  suggestions: string[];
+  feedback: string;
+}

package/src/clawswarm.ts

@@ -0,0 +1,257 @@
+/**
+ * ClawSwarm — main orchestrator class.
+ *
+ * Creates and manages a swarm of specialist agents, decomposes goals
+ * into tasks, runs the chief review pipeline, and emits events throughout.
+ *
+ * @module @clawswarm/core/clawswarm
+ */
+
+import EventEmitter from 'eventemitter3';
+import { Agent } from './agent.js';
+import { GoalManager, GoalPlanner } from './goal.js';
+import { TaskManager } from './task.js';
+import { ChiefReviewer } from './chief.js';
+import {
+  SwarmConfig,
+  SwarmEvents,
+  GoalResult,
+  CreateGoalInput,
+  Goal,
+  Task,
+  ReviewResult,
+  AgentType,
+} from './types.js';
+
+// ─── ClawSwarm ────────────────────────────────────────────────────────────────
+
+/**
+ * The primary interface for the ClawSwarm framework.
+ *
+ * @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('✅', task.title));
+ *
+ * const result = await swarm.execute(goal);
+ * ```
+ */
+export class ClawSwarm extends (EventEmitter as new () => EventEmitter<SwarmEvents>) {
+  private readonly goalManager: GoalManager;
+  private readonly taskManager: TaskManager;
+  private readonly planner: GoalPlanner;
+  private readonly reviewer: ChiefReviewer;
+  private readonly agents: Map<AgentType, Agent>;
+  private readonly config: SwarmConfig;
+
+  constructor(config: SwarmConfig) {
+    super();
+    this.config = config;
+    this.goalManager = new GoalManager();
+    this.taskManager = new TaskManager();
+    this.planner = new GoalPlanner(config);
+    this.reviewer = new ChiefReviewer(config.chiefReview);
+    this.agents = new Map();
+
+    // Register agents
+    for (const agentConfig of config.agents) {
+      const agent = new Agent(agentConfig);
+      // Use last-registered agent if multiple of same type
+      this.agents.set(agentConfig.type, agent);
+    }
+  }
+
+  // ─── Public API ───────────────────────────────────────────────────────────
+
+  /**
+   * Create a new goal (without executing it).
+   * Use `execute()` to run the goal.
+   */
+  createGoal(input: CreateGoalInput): Goal {
+    const goal = this.goalManager.create(input);
+    this.emit('goal:created', goal);
+    return goal;
+  }
+
+  /**
+   * Execute a goal end-to-end:
+   * 1. Decompose into tasks (Planner)
+   * 2. Run each task with the appropriate specialist agent
+   * 3. Review each task with ChiefReviewer
+   * 4. Handle rework cycles
+   * 5. Return final result
+   */
+  async execute(goal: Goal): Promise<GoalResult> {
+    const startTime = Date.now();
+    let hadHumanReview = false;
+
+    // 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');
+
+    try {
+      // Process tasks in waves, respecting dependencies
+      let iterations = 0;
+      const maxIterations = tasks.length * 4; // safety valve
+
+      while (!this.taskManager.isGoalDone(goal.id) && iterations < maxIterations) {
+        iterations++;
+        const ready = this.taskManager.getReady(goal.id);
+        if (ready.length === 0) break;
+
+        // Run ready tasks concurrently
+        await Promise.all(ready.map(task => this._executeTask(task)));
+
+        // Check for human review requirement
+        const reviewTasks = this.taskManager
+          .getByGoal(goal.id)
+          .filter(t => t.status === 'review');
+
+        for (const task of reviewTasks) {
+          const review = await this.reviewer.review(task);
+          hadHumanReview = hadHumanReview || (review.decision === 'human_review');
+          await this._handleReview(task, review);
+        }
+      }
+
+      // 3. Collect deliverables
+      const completedTasks = this.taskManager
+        .getByGoal(goal.id)
+        .filter(t => t.status === 'completed');
+
+      const allDeliverables = completedTasks.flatMap(t => t.deliverables);
+
+      const updatedGoal = this.goalManager.setStatus(goal.id, 'completed');
+      this.emit('goal:completed', updatedGoal);
+
+      return {
+        goal: updatedGoal,
+        deliverables: allDeliverables,
+        cost: updatedGoal.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 a registered agent by type.
+   */
+  getAgent(type: AgentType): Agent | undefined {
+    return this.agents.get(type);
+  }
+
+  /**
+   * List all registered agents.
+   */
+  listAgents(): Agent[] {
+    return Array.from(this.agents.values());
+  }
+
+  /**
+   * Get the ChiefReviewer instance (for inspection or custom review logic).
+   */
+  getReviewer(): ChiefReviewer {
+    return this.reviewer;
+  }
+
+  /**
+   * Get the TaskManager instance (for direct task inspection).
+   */
+  getTaskManager(): TaskManager {
+    return this.taskManager;
+  }
+
+  // ─── Private ──────────────────────────────────────────────────────────────
+
+  /**
+   * Execute a single task with the appropriate agent.
+   * @internal
+   */
+  private async _executeTask(task: Task): Promise<void> {
+    const agentType = task.assignedTo ?? 'code';
+    const agent = this.agents.get(agentType);
+
+    if (!agent) {
+      this.taskManager.fail(task.id, new Error(`No agent registered for type: ${agentType}`));
+      return;
+    }
+
+    try {
+      this.taskManager.assign(task.id, agentType);
+      this.emit('task:assigned', task, agentType);
+
+      this.taskManager.start(task.id);
+      this.emit('task:started', task);
+
+      const deliverables = await agent.execute(task);
+      this.taskManager.submitForReview(task.id, deliverables);
+      this.emit('task:completed', task);
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.taskManager.fail(task.id, err);
+      this.emit('task:failed', task, err);
+    }
+  }
+
+  /**
+   * Handle a chief review result for a task.
+   * @internal
+   */
+  private async _handleReview(task: Task, review: ReviewResult): Promise<void> {
+    this.emit('task:review', task, review);
+
+    switch (review.decision) {
+      case 'approved': {
+        this.taskManager.approve(task.id);
+        this.taskManager.complete(task.id);
+        break;
+      }
+
+      case 'human_review': {
+        this.emit('human:review_required', task, review);
+        // In the default flow, human_review blocks until someone calls approve/reject
+        // For automated flows, we treat it as approved after emitting the event
+        this.taskManager.approve(task.id);
+        this.taskManager.complete(task.id);
+        break;
+      }
+
+      case 'rejected': {
+        this.emit('task:rejected', task, review);
+
+        try {
+          // Attempt rework
+          this.taskManager.rework(task.id, review.feedback);
+          this.emit('task:rework', task, review);
+          // Re-execute the task
+          const updatedTask = this.taskManager.get(task.id)!;
+          await this._executeTask(updatedTask);
+        } catch {
+          // Max rework exceeded — fail the task
+          this.taskManager.reject(task.id, review.feedback);
+        }
+        break;
+      }
+    }
+  }
+}