network-ai 4.14.0 → 4.15.0

package/dist/lib/goal-decomposer.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Goal Decomposer — LLM-powered goal → task DAG → parallel execution
+ *
+ * Provides the `runTeam()` one-liner: describe a goal in plain English,
+ * specify which agents to use, and let an LLM plan the task graph.
+ * Execution respects all Network-AI guardrails (budgets, permissions, audit).
+ *
+ * Zero external dependencies — LLM calls go through the adapter system.
+ *
+ * @module GoalDecomposer
+ * @version 1.0.0
+ */
+import { EventEmitter } from 'events';
+import type { AgentPayload, AgentContext, AgentResult } from '../types/agent-adapter';
+/** A single node in the task DAG */
+export interface TaskNode {
+    /** Unique task identifier */
+    id: string;
+    /** Human-readable description of the task */
+    description: string;
+    /** Agent ID (or pool/template) to execute this task */
+    agent: string;
+    /** Action to invoke on the agent */
+    action: string;
+    /** Parameters for the action */
+    params: Record<string, unknown>;
+    /** IDs of tasks that must complete before this one starts */
+    dependencies: string[];
+    /** Priority (higher = more urgent) */
+    priority: number;
+    /** Execution status */
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+    /** Result after execution */
+    result?: AgentResult;
+    /** Error message if failed */
+    error?: string;
+    /** Timestamps */
+    startedAt?: number;
+    completedAt?: number;
+}
+/** Directed acyclic graph of tasks */
+export interface TaskDAG {
+    /** The original goal */
+    goal: string;
+    /** All task nodes */
+    nodes: TaskNode[];
+    /** Adjacency list: taskId → downstream task IDs */
+    edges: Map<string, string[]>;
+    /** When the DAG was created */
+    createdAt: number;
+}
+/** Configuration for an agent available to the team */
+export interface TeamAgent {
+    /** Agent ID (must match an adapter-registered agent or be resolvable by the executor) */
+    id: string;
+    /** What this agent can do (fed to LLM for planning) */
+    role: string;
+    /** Which adapter handles this agent */
+    adapter?: string;
+    /** Default action to invoke */
+    defaultAction?: string;
+    /** Default parameters */
+    defaultParams?: Record<string, unknown>;
+}
+/** Function that invokes an LLM to produce a decomposition plan */
+export type PlannerFunction = (goal: string, agents: TeamAgent[], context?: Record<string, unknown>) => Promise<PlannedTask[]>;
+/** Output from the planner (LLM-generated) */
+export interface PlannedTask {
+    id: string;
+    description: string;
+    agent: string;
+    action: string;
+    params: Record<string, unknown>;
+    dependencies: string[];
+    priority?: number;
+}
+/** Function that executes a single task via the adapter system */
+export type ExecutorFunction = (agentId: string, payload: AgentPayload, context: AgentContext) => Promise<AgentResult>;
+/** Options for `runTeam` */
+export interface RunTeamOptions {
+    /** Maximum number of tasks to run in parallel (default: 5) */
+    concurrency?: number;
+    /** Timeout per task in ms (default: 30000) */
+    taskTimeout?: number;
+    /** Timeout for the entire run in ms (default: 300000) */
+    totalTimeout?: number;
+    /** Whether to continue executing tasks after one fails (default: false) */
+    continueOnFailure?: boolean;
+    /** Session ID for context propagation */
+    sessionId?: string;
+    /** Arbitrary metadata passed to agent contexts */
+    metadata?: Record<string, unknown>;
+    /** Maximum LLM retries for planning (default: 1) */
+    plannerRetries?: number;
+    /** Callback for approval before execution starts */
+    approvalCallback?: (dag: TaskDAG) => Promise<boolean>;
+}
+/** Final result from a team run */
+export interface TeamResult {
+    /** Whether the overall goal was achieved */
+    success: boolean;
+    /** The task graph that was executed */
+    dag: TaskDAG;
+    /** Aggregated results from all completed tasks */
+    results: Map<string, AgentResult>;
+    /** Summary of what happened */
+    summary: string;
+    /** Total execution time in ms */
+    durationMs: number;
+    /** Count of tasks by status */
+    stats: {
+        total: number;
+        completed: number;
+        failed: number;
+        skipped: number;
+    };
+}
+/** Events emitted during a team run */
+export interface TeamRunnerEvents {
+    'dag:created': (dag: TaskDAG) => void;
+    'task:start': (node: TaskNode) => void;
+    'task:complete': (node: TaskNode, result: AgentResult) => void;
+    'task:fail': (node: TaskNode, error: string) => void;
+    'task:skip': (node: TaskNode, reason: string) => void;
+    'run:complete': (result: TeamResult) => void;
+}
+/**
+ * Validate that a set of planned tasks forms a valid DAG (no cycles, valid refs).
+ * @throws Error if the graph contains cycles or invalid dependency references
+ */
+export declare function validateDAG(tasks: PlannedTask[]): void;
+/**
+ * Compute topological layers — tasks in the same layer can execute in parallel.
+ * Returns arrays of task IDs grouped by execution layer.
+ */
+export declare function topologicalLayers(tasks: PlannedTask[]): string[][];
+/**
+ * Create a planner function that uses an LLM (via executor) to decompose goals.
+ *
+ * The planner sends a structured prompt to the specified agent and parses
+ * the JSON response into PlannedTask[]. Falls back gracefully on parse errors.
+ *
+ * @param executor - Function to call the LLM agent
+ * @param plannerAgent - Agent ID for the LLM that does planning
+ * @param plannerAdapter - Adapter name (optional, defaults to agent's adapter)
+ */
+export declare function createLLMPlanner(executor: ExecutorFunction, plannerAgent: string): PlannerFunction;
+/**
+ * Parse JSON from an LLM response string, handling markdown fences and preamble.
+ */
+export declare function parsePlanJSON(text: string): PlannedTask[];
+/**
+ * LLM-powered goal decomposition engine.
+ *
+ * Takes a natural language goal, creates a task DAG via an LLM planner,
+ * validates the graph, and returns a ready-to-execute TaskDAG.
+ */
+export declare class GoalDecomposer {
+    private planner;
+    constructor(planner: PlannerFunction);
+    /**
+     * Decompose a goal into a validated TaskDAG.
+     * @param goal - Natural language description of the goal
+     * @param agents - Available team agents
+     * @param context - Optional context to feed to the planner
+     * @param retries - Number of retries on planning failure (default: 1)
+     */
+    decompose(goal: string, agents: TeamAgent[], context?: Record<string, unknown>, retries?: number): Promise<TaskDAG>;
+}
+/**
+ * Executes a TaskDAG by running tasks in parallel layers, respecting
+ * dependencies, concurrency limits, and timeouts.
+ *
+ * @example
+ * ```typescript
+ * const runner = new TeamRunner(executor);
+ * const result = await runner.run(dag, { concurrency: 3 });
+ * console.log(result.summary);
+ * ```
+ */
+export declare class TeamRunner extends EventEmitter {
+    private executor;
+    constructor(executor: ExecutorFunction);
+    /**
+     * Execute a TaskDAG with parallel scheduling.
+     */
+    run(dag: TaskDAG, options?: RunTeamOptions): Promise<TeamResult>;
+}
+/**
+ * Decompose a goal into tasks and execute them with a team of agents.
+ *
+ * This is the main entry point — one line to go from goal to results:
+ *
+ * ```typescript
+ * const result = await runTeam(
+ *   "Build a REST API for user management",
+ *   [
+ *     { id: "architect", role: "System design and API specification" },
+ *     { id: "coder", role: "Write TypeScript code" },
+ *     { id: "reviewer", role: "Code review and quality checks" },
+ *   ],
+ *   { planner, executor }
+ * );
+ * ```
+ *
+ * @param goal - Natural language description of what to achieve
+ * @param agents - Team of agents available for task execution
+ * @param config - Planner (LLM decomposition) and executor (agent invocation) functions
+ * @param options - Optional concurrency, timeout, and failure handling settings
+ * @returns Full result with DAG, individual results, and stats
+ */
+export declare function runTeam(goal: string, agents: TeamAgent[], config: {
+    planner: PlannerFunction;
+    executor: ExecutorFunction;
+}, options?: RunTeamOptions): Promise<TeamResult>;
+//# sourceMappingURL=goal-decomposer.d.ts.map

package/dist/lib/goal-decomposer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"goal-decomposer.d.ts","sourceRoot":"","sources":["../../lib/goal-decomposer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAMtF,oCAAoC;AACpC,MAAM,WAAW,QAAQ;IACvB,6BAA6B;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,6DAA6D;IAC7D,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,uBAAuB;IACvB,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;IACnE,6BAA6B;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,sCAAsC;AACtC,MAAM,WAAW,OAAO;IACtB,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,mDAAmD;IACnD,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7B,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,uDAAuD;AACvD,MAAM,WAAW,SAAS;IACxB,yFAAyF;IACzF,EAAE,EAAE,MAAM,CAAC;IACX,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yBAAyB;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,mEAAmE;AACnE,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,EAAE,EACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC9B,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;AAE5B,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,kEAAkE;AAClE,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,YAAY,KAClB,OAAO,CAAC,WAAW,CAAC,CAAC;AAE1B,4BAA4B;AAC5B,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACvD;AAED,mCAAmC;AACnC,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,uCAAuC;IACvC,GAAG,EAAE,OAAO,CAAC;IACb,kDAAkD;IAClD,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,KAAK,EAAE;QACL,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED,uCAAuC;AACvC,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IACtC,YAAY,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACvC,eAAe,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;IAC/D,WAAW,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrD,WAAW,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACtD,cAAc,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;CAC9C;AAMD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI,CAqDtD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,MAAM,EAAE,EAAE,CAqClE;AAMD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,gBAAgB,EAC1B,YAAY,EAAE,MAAM,GACnB,eAAe,CAkFjB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAwBzD;AAMD;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAkB;gBAErB,OAAO,EAAE,eAAe;IAIpC;;;;;;OAMG;IACG,SAAS,CACb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,EAAE,EACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,SAAI,GACV,OAAO,CAAC,OAAO,CAAC;CAyDpB;AAMD;;;;;;;;;;GAUG;AACH,qBAAa,UAAW,SAAQ,YAAY;IAC1C,OAAO,CAAC,QAAQ,CAAmB;gBAEvB,QAAQ,EAAE,gBAAgB;IAKtC;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,UAAU,CAAC;CAoK3E;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,OAAO,CAC3B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,EAAE,EACnB,MAAM,EAAE;IAAE,OAAO,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,gBAAgB,CAAA;CAAE,EAChE,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,UAAU,CAAC,CAgCrB"}