@clawswarm/core 0.1.0-alpha

package/dist/swarm.js

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * ClawSwarm — the top-level orchestrator.
+ * @module @clawswarm/core/swarm
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClawSwarm = void 0;
+const eventemitter3_1 = __importDefault(require("eventemitter3"));
+const agent_js_1 = require("./agent.js");
+const task_js_1 = require("./task.js");
+const goal_js_1 = require("./goal.js");
+const chief_js_1 = require("./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);
+ * ```
+ */
+class ClawSwarm extends eventemitter3_1.default {
+    config;
+    agents;
+    taskManager;
+    goalManager;
+    planner;
+    reviewer;
+    constructor(config) {
+        super();
+        this.config = config;
+        this.agents = config.agents.map(c => new agent_js_1.Agent(c));
+        this.taskManager = new task_js_1.TaskManager();
+        this.goalManager = new goal_js_1.GoalManager();
+        this.planner = new goal_js_1.GoalPlanner(config);
+        this.reviewer = new chief_js_1.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) {
+        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) {
+        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() {
+        return [...this.agents];
+    }
+    /**
+     * Get an agent by type.
+     */
+    getAgent(type) {
+        return this.agents.find(a => a.type === type && a.status === 'idle');
+    }
+    // ─── Private ──────────────────────────────────────────────────────────────
+    async _executeTask(task) {
+        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 };
+    }
+}
+exports.ClawSwarm = ClawSwarm;
+//# sourceMappingURL=swarm.js.map

package/dist/swarm.js.map

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

package/dist/task.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Task lifecycle management.
+ * @module @clawswarm/core/task
+ */
+import { Task, AgentType, Deliverable } from './types.js';
+/**
+ * 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 declare class TaskManager {
+    private tasks;
+    /**
+     * Create a new task.
+     */
+    create(input: Omit<Task, 'id' | 'status' | 'deliverables' | 'reworkCount' | 'maxReworkCycles' | 'createdAt' | 'updatedAt'>): Task;
+    /**
+     * Get a task by ID.
+     */
+    get(taskId: string): Task | undefined;
+    /**
+     * Get all tasks.
+     */
+    getAll(): Task[];
+    /**
+     * Get tasks by goal ID.
+     */
+    getByGoal(goalId: string): Task[];
+    /**
+     * Get tasks that are ready to run (all dependencies completed).
+     */
+    getReady(goalId: string): Task[];
+    /**
+     * Assign a task to an agent type.
+     */
+    assign(taskId: string, agentType: AgentType): Task;
+    /**
+     * Mark a task as in progress.
+     */
+    start(taskId: string): Task;
+    /**
+     * Submit a task for review with its deliverables.
+     */
+    submitForReview(taskId: string, deliverables: Deliverable[]): Task;
+    /**
+     * Mark a task as approved.
+     */
+    approve(taskId: string): Task;
+    /**
+     * Mark a task as completed (after approval and any post-processing).
+     */
+    complete(taskId: string): Task;
+    /**
+     * Mark a task for rework. Increments rework counter.
+     * @throws If max rework cycles exceeded
+     */
+    rework(taskId: string, feedback: string): Task;
+    /**
+     * Mark a task as rejected (max rework exceeded or explicitly rejected).
+     */
+    reject(taskId: string, reason: string): Task;
+    /**
+     * Mark a task as failed (unexpected error).
+     */
+    fail(taskId: string, error: Error): Task;
+    /**
+     * Check if a goal has all tasks completed or failed.
+     */
+    isGoalDone(goalId: string): boolean;
+    private _transition;
+    private _getOrThrow;
+}
+//# sourceMappingURL=task.d.ts.map

package/dist/task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../src/task.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAc,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAItE;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAgC;IAE7C;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,GAAG,cAAc,GAAG,aAAa,GAAG,iBAAiB,GAAG,WAAW,GAAG,WAAW,CAAC,GAAG,IAAI;IAgBjI;;OAEG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIrC;;OAEG;IACH,MAAM,IAAI,IAAI,EAAE;IAIhB;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE;IAIjC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE;IAYhC;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI;IAMlD;;OAEG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI3B;;OAEG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,IAAI;IAMlE;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI7B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI9B;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAuB9C;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAS5C;;OAEG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI;IASxC;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAQnC,OAAO,CAAC,WAAW;IAYnB,OAAO,CAAC,WAAW;CAKpB"}

package/dist/task.js

@@ -0,0 +1,177 @@
+"use strict";
+/**
+ * Task lifecycle management.
+ * @module @clawswarm/core/task
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskManager = void 0;
+// ─── 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: '...' }]);
+ * ```
+ */
+class TaskManager {
+    tasks = new Map();
+    /**
+     * Create a new task.
+     */
+    create(input) {
+        const 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) {
+        return this.tasks.get(taskId);
+    }
+    /**
+     * Get all tasks.
+     */
+    getAll() {
+        return Array.from(this.tasks.values());
+    }
+    /**
+     * Get tasks by goal ID.
+     */
+    getByGoal(goalId) {
+        return this.getAll().filter(t => t.goalId === goalId);
+    }
+    /**
+     * Get tasks that are ready to run (all dependencies completed).
+     */
+    getReady(goalId) {
+        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, agentType) {
+        return this._transition(taskId, 'assigned', task => {
+            task.assignedTo = agentType;
+        });
+    }
+    /**
+     * Mark a task as in progress.
+     */
+    start(taskId) {
+        return this._transition(taskId, 'in_progress');
+    }
+    /**
+     * Submit a task for review with its deliverables.
+     */
+    submitForReview(taskId, deliverables) {
+        return this._transition(taskId, 'review', task => {
+            task.deliverables = deliverables;
+        });
+    }
+    /**
+     * Mark a task as approved.
+     */
+    approve(taskId) {
+        return this._transition(taskId, 'approved');
+    }
+    /**
+     * Mark a task as completed (after approval and any post-processing).
+     */
+    complete(taskId) {
+        return this._transition(taskId, 'completed');
+    }
+    /**
+     * Mark a task for rework. Increments rework counter.
+     * @throws If max rework cycles exceeded
+     */
+    rework(taskId, feedback) {
+        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, reason) {
+        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, error) {
+        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) {
+        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 ──────────────────────────────────────────────────────────────
+    _transition(taskId, status, mutate) {
+        const task = this._getOrThrow(taskId);
+        task.status = status;
+        task.updatedAt = new Date().toISOString();
+        mutate?.(task);
+        return task;
+    }
+    _getOrThrow(taskId) {
+        const task = this.tasks.get(taskId);
+        if (!task)
+            throw new Error(`Task not found: ${taskId}`);
+        return task;
+    }
+}
+exports.TaskManager = TaskManager;
+//# sourceMappingURL=task.js.map

package/dist/task.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Shared types for the ClawSwarm core framework.
+ * @module @clawswarm/core/types
+ */
+/** Supported LLM model identifiers */
+export type ModelId = 'claude-sonnet-4' | 'claude-opus-4' | 'gpt-4o' | 'gpt-4o-mini' | 'gemini-pro' | 'gemini-flash' | string;
+/** Agent specializations available in ClawSwarm */
+export type AgentType = 'research' | 'code' | 'ops' | 'planner' | 'custom';
+/** Current status of an agent */
+export type AgentStatus = 'idle' | 'busy' | 'error' | 'offline';
+/** Configuration for creating an agent */
+export interface AgentConfig {
+    /** Agent type/specialization */
+    type: AgentType;
+    /** LLM model to use */
+    model: ModelId;
+    /** Optional display name */
+    name?: string;
+    /** System prompt override */
+    systemPrompt?: string;
+    /** Max tokens per request */
+    maxTokens?: number;
+    /** Temperature (0-1) */
+    temperature?: number;
+    /** Tools/capabilities this agent has access to */
+    tools?: string[];
+}
+/** Task lifecycle states */
+export type TaskStatus = 'pending' | 'assigned' | 'in_progress' | 'review' | 'approved' | 'rejected' | 'rework' | 'completed' | 'failed';
+/** A deliverable produced by a task */
+export interface Deliverable {
+    /** Type of deliverable */
+    type: 'text' | 'code' | 'file' | 'url' | 'data';
+    /** Human-readable label */
+    label: string;
+    /** The content */
+    content: string;
+    /** MIME type if applicable */
+    mimeType?: string;
+    /** File path if type is 'file' */
+    filePath?: string;
+}
+/** A task within a goal */
+export interface Task {
+    /** Unique task ID */
+    id: string;
+    /** Parent goal ID */
+    goalId: string;
+    /** Task title */
+    title: string;
+    /** Detailed description of what to do */
+    description: string;
+    /** Current lifecycle status */
+    status: TaskStatus;
+    /** Agent type assigned to this task */
+    assignedTo?: AgentType;
+    /** Task outputs/deliverables */
+    deliverables: Deliverable[];
+    /** Number of rework cycles attempted */
+    reworkCount: number;
+    /** Max rework cycles allowed */
+    maxReworkCycles: number;
+    /** ISO timestamp when created */
+    createdAt: string;
+    /** ISO timestamp when last updated */
+    updatedAt: string;
+    /** Dependencies: task IDs that must complete before this one */
+    dependsOn: string[];
+}
+/** Goal lifecycle states */
+export type GoalStatus = 'created' | 'planning' | 'in_progress' | 'review' | 'completed' | 'failed';
+/** Input for creating a goal */
+export interface CreateGoalInput {
+    /** Short title for the goal */
+    title: string;
+    /** Full description of what to accomplish */
+    description: string;
+    /** Priority (higher = more urgent) */
+    priority?: number;
+    /** Deadline as ISO timestamp */
+    deadline?: string;
+    /** Tags for categorization */
+    tags?: string[];
+}
+/** A goal with all its tasks */
+export interface Goal extends CreateGoalInput {
+    /** Unique goal ID */
+    id: string;
+    /** Current status */
+    status: GoalStatus;
+    /** Tasks decomposed from this goal */
+    tasks: Task[];
+    /** Combined deliverables from all completed tasks */
+    deliverables: Deliverable[];
+    /** Cost tracking */
+    cost: CostSummary;
+    /** ISO timestamp when created */
+    createdAt: string;
+    /** ISO timestamp when completed */
+    completedAt?: string;
+}
+/** Result of a chief review */
+export interface ReviewResult {
+    /** Task ID that was reviewed */
+    taskId: string;
+    /** Score from 0-10 */
+    score: number;
+    /** Decision based on score thresholds */
+    decision: 'approved' | 'human_review' | 'rejected';
+    /** Reviewer's feedback */
+    feedback: string;
+    /** Specific issues found (if any) */
+    issues: string[];
+    /** Suggestions for improvement */
+    suggestions: string[];
+    /** ISO timestamp of review */
+    reviewedAt: string;
+}
+/** Configuration for the chief review pipeline */
+export interface ChiefReviewConfig {
+    /** Score threshold for auto-approval (default: 8) */
+    autoApproveThreshold?: number;
+    /** Score threshold for human review (default: 5) */
+    humanReviewThreshold?: number;
+    /** Model to use for the reviewer */
+    reviewerModel?: ModelId;
+    /** Custom review criteria */
+    criteria?: string[];
+}
+/** Token usage for a single request */
+export interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/** Cost summary for a goal or task */
+export interface CostSummary {
+    /** Total tokens used */
+    totalTokens: number;
+    /** Estimated cost in USD */
+    estimatedCostUsd: number;
+    /** Per-agent breakdown */
+    byAgent: Record<string, {
+        tokens: number;
+        costUsd: number;
+    }>;
+}
+/** Events emitted by ClawSwarm */
+export interface SwarmEvents {
+    'goal:created': (goal: Goal) => void;
+    'goal:planning': (goal: Goal) => void;
+    'goal:completed': (goal: Goal) => void;
+    'goal:failed': (goal: Goal, error: Error) => void;
+    'task:assigned': (task: Task, agentType: AgentType) => void;
+    'task:started': (task: Task) => void;
+    'task:completed': (task: Task) => void;
+    'task:review': (task: Task, review: ReviewResult) => void;
+    'task:rejected': (task: Task, review: ReviewResult) => void;
+    'task:rework': (task: Task, review: ReviewResult) => void;
+    'task:failed': (task: Task, error: Error) => void;
+    'human:review_required': (task: Task, review: ReviewResult) => void;
+}
+/** Top-level ClawSwarm configuration */
+export interface SwarmConfig {
+    /** Agents to deploy */
+    agents: AgentConfig[];
+    /** Chief review configuration */
+    chiefReview?: ChiefReviewConfig;
+    /** Bridge URL for real-time communication */
+    bridgeUrl?: string;
+    /** Organization ID (for multi-tenant setups) */
+    orgId?: string;
+    /** Max concurrent goals */
+    maxConcurrentGoals?: number;
+}
+/** Result of executing a goal */
+export interface GoalResult {
+    /** The completed goal */
+    goal: Goal;
+    /** All deliverables from all tasks */
+    deliverables: Deliverable[];
+    /** Total cost */
+    cost: CostSummary;
+    /** Whether any tasks required human review */
+    hadHumanReview: boolean;
+    /** Duration in milliseconds */
+    durationMs: number;
+}
+//# sourceMappingURL=types.d.ts.map