@clawswarm/core 0.1.0-alpha

package/README.md

@@ -0,0 +1,41 @@
+# @clawswarm/core
+
+The core agent framework for ClawSwarm. Provides the base classes and types for building multi-agent systems.
+
+## Installation
+
+```bash
+npm install @clawswarm/core
+```
+
+## Usage
+
+```typescript
+import { ClawSwarm, Agent, Goal } from '@clawswarm/core';
+
+const swarm = new ClawSwarm({
+  agents: [
+    Agent.research({ model: 'claude-sonnet-4' }),
+    Agent.code({ model: 'gpt-4o' }),
+  ],
+  chiefReview: {
+    autoApproveThreshold: 8,
+    humanReviewThreshold: 5,
+  },
+});
+
+const goal = await swarm.createGoal({
+  title: 'Build a REST API',
+  description: 'Create a Node.js REST API with authentication',
+});
+
+const result = await swarm.execute(goal);
+```
+
+## API
+
+See the [API Reference](../../docs/api-reference.md) for full documentation.
+
+## License
+
+MIT

package/dist/agent.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Base Agent class and specialist agent factories.
+ * @module @clawswarm/core/agent
+ */
+import { AgentConfig, AgentStatus, AgentType, ModelId, Task, Deliverable } from './types.js';
+/**
+ * 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 declare class Agent {
+    readonly id: string;
+    readonly config: AgentConfig;
+    status: AgentStatus;
+    currentTaskId?: string;
+    constructor(config: AgentConfig);
+    /** Agent's display name */
+    get name(): string;
+    /** Agent's specialization type */
+    get type(): AgentType;
+    /**
+     * Execute a task and return deliverables.
+     * Override this in custom agents.
+     *
+     * @param task - The task to execute
+     * @returns Array of deliverables produced
+     */
+    execute(task: Task): Promise<Deliverable[]>;
+    /**
+     * Check if this agent can handle a given task type.
+     * Override to restrict which tasks this agent accepts.
+     */
+    canHandle(_task: Task): boolean;
+    /**
+     * Get the system prompt for this agent.
+     * Override to customize the agent's behavior.
+     */
+    getSystemPrompt(): string;
+    /**
+     * Create a ResearchClaw agent.
+     * Specializes in information gathering, analysis, and written reports.
+     */
+    static research(options: Partial<AgentConfig> & {
+        model: ModelId;
+    }): AgentConfig;
+    /**
+     * Create a CodeClaw agent.
+     * Specializes in writing, reviewing, and debugging code.
+     */
+    static code(options: Partial<AgentConfig> & {
+        model: ModelId;
+    }): AgentConfig;
+    /**
+     * Create an OpsClaw agent.
+     * Specializes in infrastructure, deployment, and monitoring.
+     */
+    static ops(options: Partial<AgentConfig> & {
+        model: ModelId;
+    }): AgentConfig;
+    /**
+     * Create a Planner agent.
+     * Decomposes goals into tasks and assigns them to specialist agents.
+     */
+    static planner(options: Partial<AgentConfig> & {
+        model: ModelId;
+    }): AgentConfig;
+    private _defaultName;
+    private _defaultSystemPrompt;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI7F;;;;;;;;;;;;;GAaG;AACH,qBAAa,KAAK;IAChB,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,MAAM,EAAE,WAAW,CAAC;IAC7B,MAAM,EAAE,WAAW,CAAU;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;gBAElB,MAAM,EAAE,WAAW;IAK/B,2BAA2B;IAC3B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,kCAAkC;IAClC,IAAI,IAAI,IAAI,SAAS,CAEpB;IAED;;;;;;OAMG;IACG,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAIjD;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,IAAI,GAAG,OAAO;IAI/B;;;OAGG;IACH,eAAe,IAAI,MAAM;IAMzB;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,WAAW;IAShF;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,WAAW;IAS5E;;;OAGG;IACH,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,WAAW;IAS3E;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,WAAW;IAW/E,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,oBAAoB;CAwB7B"}

package/dist/agent.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * Base Agent class and specialist agent factories.
+ * @module @clawswarm/core/agent
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = void 0;
+// ─── 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: '...' }];
+ *   }
+ * }
+ * ```
+ */
+class Agent {
+    id;
+    config;
+    status = 'idle';
+    currentTaskId;
+    constructor(config) {
+        this.config = config;
+        this.id = `agent-${config.type}-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+    }
+    /** Agent's display name */
+    get name() {
+        return this.config.name ?? this._defaultName(this.config.type);
+    }
+    /** Agent's specialization type */
+    get type() {
+        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) {
+        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) {
+        return true;
+    }
+    /**
+     * Get the system prompt for this agent.
+     * Override to customize the agent's behavior.
+     */
+    getSystemPrompt() {
+        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) {
+        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) {
+        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) {
+        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) {
+        return {
+            type: 'planner',
+            name: 'Planner',
+            tools: [],
+            ...options,
+        };
+    }
+    // ─── Private Helpers ─────────────────────────────────────────────────────────
+    _defaultName(type) {
+        const names = {
+            research: 'ResearchClaw',
+            code: 'CodeClaw',
+            ops: 'OpsClaw',
+            planner: 'Planner',
+            custom: 'CustomAgent',
+        };
+        return names[type] ?? 'Agent';
+    }
+    _defaultSystemPrompt(type) {
+        const prompts = {
+            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;
+    }
+}
+exports.Agent = Agent;
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/chief.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 } from './types.js';
+/**
+ * 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 declare class ChiefReviewer extends EventEmitter {
+    private readonly autoApproveThreshold;
+    private readonly humanReviewThreshold;
+    private readonly reviewerModel;
+    private readonly criteria;
+    constructor(config?: ChiefReviewConfig);
+    /**
+     * 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
+     */
+    review(task: Task): Promise<ReviewResult>;
+    /**
+     * Synchronously check what decision would be made for a given score.
+     * Useful for dry-runs and testing.
+     */
+    scoreToDecision(score: number): ReviewResult['decision'];
+    /**
+     * Get the current review configuration (read-only).
+     */
+    get config(): Required<ChiefReviewConfig>;
+    /**
+     * Build a review prompt for the LLM.
+     * @internal
+     */
+    private _buildPrompt;
+    /**
+     * Call the LLM reviewer. In production, replace the stub with a real LLM call.
+     * @internal
+     */
+    private _callReviewerLLM;
+    /**
+     * Assemble a ReviewResult from raw LLM data.
+     * @internal
+     */
+    private _buildResult;
+    /**
+     * Validate that thresholds are logically consistent.
+     * @internal
+     */
+    private _validateThresholds;
+}
+//# sourceMappingURL=chief.d.ts.map

package/dist/chief.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chief.d.ts","sourceRoot":"","sources":["../src/chief.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,YAAY,MAAM,eAAe,CAAC;AACzC,OAAO,EACL,IAAI,EACJ,YAAY,EACZ,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAkBpB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,aAAc,SAAQ,YAAY;IAC7C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;gBAExB,MAAM,GAAE,iBAAsB;IAU1C;;;;;OAKG;IACG,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC;IAoB/C;;;OAGG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC,UAAU,CAAC;IAMxD;;OAEG;IACH,IAAI,MAAM,IAAI,QAAQ,CAAC,iBAAiB,CAAC,CAOxC;IAID;;;OAGG;IACH,OAAO,CAAC,YAAY;IAmCpB;;;OAGG;YACW,gBAAgB;IA8C9B;;;OAGG;IACH,OAAO,CAAC,YAAY;IAqBpB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;CAW5B"}

package/dist/chief.js

@@ -0,0 +1,221 @@
+"use strict";
+/**
+ * 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
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChiefReviewer = void 0;
+const eventemitter3_1 = __importDefault(require("eventemitter3"));
+// ─── Constants ────────────────────────────────────────────────────────────────
+const DEFAULT_AUTO_APPROVE_THRESHOLD = 8;
+const DEFAULT_HUMAN_REVIEW_THRESHOLD = 5;
+const DEFAULT_REVIEWER_MODEL = '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);
+ * }
+ * ```
+ */
+class ChiefReviewer extends eventemitter3_1.default {
+    autoApproveThreshold;
+    humanReviewThreshold;
+    reviewerModel;
+    criteria;
+    constructor(config = {}) {
+        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) {
+        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) {
+        if (score >= this.autoApproveThreshold)
+            return 'approved';
+        if (score >= this.humanReviewThreshold)
+            return 'human_review';
+        return 'rejected';
+    }
+    /**
+     * Get the current review configuration (read-only).
+     */
+    get config() {
+        return {
+            autoApproveThreshold: this.autoApproveThreshold,
+            humanReviewThreshold: this.humanReviewThreshold,
+            reviewerModel: this.reviewerModel,
+            criteria: this.criteria,
+        };
+    }
+    // ─── Private ──────────────────────────────────────────────────────────────
+    /**
+     * Build a review prompt for the LLM.
+     * @internal
+     */
+    _buildPrompt(task) {
+        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
+     */
+    async _callReviewerLLM(task) {
+        // ── 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 = [];
+        const suggestions = [];
+        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
+     */
+    _buildResult(taskId, score, issues, suggestions, feedback) {
+        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
+     */
+    _validateThresholds() {
+        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');
+        }
+    }
+}
+exports.ChiefReviewer = ChiefReviewer;
+//# sourceMappingURL=chief.js.map

package/dist/chief.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chief.js","sourceRoot":"","sources":["../src/chief.ts"],"names":[],"mappings":"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"}

package/dist/clawswarm.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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 { TaskManager } from './task.js';
+import { ChiefReviewer } from './chief.js';
+import { SwarmConfig, SwarmEvents, GoalResult, CreateGoalInput, Goal, AgentType } from './types.js';
+declare const ClawSwarm_base: new () => EventEmitter<SwarmEvents>;
+/**
+ * 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 declare class ClawSwarm extends ClawSwarm_base {
+    private readonly goalManager;
+    private readonly taskManager;
+    private readonly planner;
+    private readonly reviewer;
+    private readonly agents;
+    private readonly config;
+    constructor(config: SwarmConfig);
+    /**
+     * Create a new goal (without executing it).
+     * Use `execute()` to run the goal.
+     */
+    createGoal(input: CreateGoalInput): 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
+     */
+    execute(goal: Goal): Promise<GoalResult>;
+    /**
+     * Get a registered agent by type.
+     */
+    getAgent(type: AgentType): Agent | undefined;
+    /**
+     * List all registered agents.
+     */
+    listAgents(): Agent[];
+    /**
+     * Get the ChiefReviewer instance (for inspection or custom review logic).
+     */
+    getReviewer(): ChiefReviewer;
+    /**
+     * Get the TaskManager instance (for direct task inspection).
+     */
+    getTaskManager(): TaskManager;
+    /**
+     * Execute a single task with the appropriate agent.
+     * @internal
+     */
+    private _executeTask;
+    /**
+     * Handle a chief review result for a task.
+     * @internal
+     */
+    private _handleReview;
+}
+export {};
+//# sourceMappingURL=clawswarm.d.ts.map

package/dist/clawswarm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clawswarm.d.ts","sourceRoot":"","sources":["../src/clawswarm.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,YAAY,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EACL,WAAW,EACX,WAAW,EACX,UAAU,EACV,eAAe,EACf,IAAI,EAGJ,SAAS,EACV,MAAM,YAAY,CAAC;8BAuB4B,UAAU,YAAY,CAAC,WAAW,CAAC;AAnBnF;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,SAAU,SAAQ,cAAqD;IAClF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,MAAM,EAAE,WAAW;IAmB/B;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAMxC;;;;;;;OAOG;IACG,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC;IAgE9C;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,KAAK,GAAG,SAAS;IAI5C;;OAEG;IACH,UAAU,IAAI,KAAK,EAAE;IAIrB;;OAEG;IACH,WAAW,IAAI,aAAa;IAI5B;;OAEG;IACH,cAAc,IAAI,WAAW;IAM7B;;;OAGG;YACW,YAAY;IA0B1B;;;OAGG;YACW,aAAa;CAqC5B"}