@defai.digital/ax-cli 2.7.0 → 2.8.0

package/dist/agent/subagent-types.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Subagent System Types
+ *
+ * Type definitions for the autonomous subagent system that enables
+ * parallel task execution and specialized agent capabilities.
+ */
+import type { LLMToolCall } from '../llm/client.js';
+/**
+ * Types of specialized agents available
+ */
+export declare enum SubagentRole {
+    /** General-purpose agent for any task */
+    GENERAL = "general",
+    /** Specialized in writing and running tests */
+    TESTING = "testing",
+    /** Specialized in generating documentation */
+    DOCUMENTATION = "documentation",
+    /** Specialized in code refactoring */
+    REFACTORING = "refactoring",
+    /** Specialized in code analysis and bug detection */
+    ANALYSIS = "analysis",
+    /** Specialized in debugging and error resolution */
+    DEBUG = "debug",
+    /** Specialized in performance optimization */
+    PERFORMANCE = "performance"
+}
+/**
+ * Chat entry (from llm-agent.ts to avoid circular dependency)
+ */
+export interface ChatEntry {
+    type: 'user' | 'assistant' | 'tool_result' | 'tool_call';
+    content: string;
+    timestamp: Date;
+    toolCalls?: LLMToolCall[];
+    toolCall?: LLMToolCall;
+    toolResult?: {
+        success: boolean;
+        output?: string;
+        error?: string;
+    };
+    isStreaming?: boolean;
+    reasoningContent?: string;
+    isReasoningStreaming?: boolean;
+}
+/**
+ * Configuration for creating a subagent
+ */
+export interface SubagentConfig {
+    /** Role/specialization of the subagent */
+    role: SubagentRole;
+    /** Tools this subagent is allowed to use */
+    allowedTools: string[];
+    /** Maximum tool execution rounds */
+    maxToolRounds: number;
+    /** Number of conversation messages to include as context */
+    contextDepth: number;
+    /** Custom system prompt (overrides role-based prompt) */
+    customSystemPrompt?: string;
+    /** Execution timeout in milliseconds */
+    timeout?: number;
+    /** Priority level (higher = executed first) */
+    priority?: number;
+}
+/**
+ * Task to be executed by a subagent
+ */
+export interface SubagentTask {
+    /** Unique task identifier */
+    id: string;
+    /** Human-readable task description */
+    description: string;
+    /** Subagent role to use for this task */
+    role: SubagentRole;
+    /** Priority level (higher = executed first) */
+    priority: number;
+    /** Context to provide to the subagent */
+    context: SubagentContext;
+    /** IDs of tasks that must complete before this one */
+    dependencies?: string[];
+    /** Maximum tool rounds for this task */
+    maxToolRounds?: number;
+    /** Timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Context provided to a subagent
+ */
+export interface SubagentContext {
+    /** File paths to include in context */
+    files?: string[];
+    /** Code snippets to include */
+    codeSnippets?: CodeSnippet[];
+    /** Relevant conversation history */
+    conversationHistory?: ChatEntry[];
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Code snippet for context
+ */
+export interface CodeSnippet {
+    /** File path this snippet is from */
+    path: string;
+    /** The code content */
+    content: string;
+    /** Programming language */
+    language: string;
+    /** Starting line number */
+    startLine?: number;
+    /** Ending line number */
+    endLine?: number;
+}
+/**
+ * Execution state of a subagent
+ */
+export declare enum SubagentState {
+    /** Waiting to be started */
+    PENDING = "pending",
+    /** Currently executing */
+    RUNNING = "running",
+    /** Successfully completed */
+    COMPLETED = "completed",
+    /** Failed with error */
+    FAILED = "failed",
+    /** Cancelled by user or system */
+    CANCELLED = "cancelled"
+}
+/**
+ * Status information for a subagent
+ */
+export interface SubagentStatus {
+    /** Subagent unique identifier */
+    id: string;
+    /** Task being executed */
+    taskId: string;
+    /** Subagent role */
+    role: SubagentRole;
+    /** Current execution state */
+    state: SubagentState;
+    /** Progress percentage (0-100) */
+    progress: number;
+    /** When execution started */
+    startTime: Date;
+    /** When execution ended (if completed/failed) */
+    endTime?: Date;
+    /** Error message if failed */
+    error?: string;
+    /** Current action being performed */
+    currentAction?: string;
+    /** Tools used so far */
+    toolsUsed?: string[];
+    /** Number of tool rounds used */
+    toolRoundsUsed?: number;
+}
+/**
+ * Result of subagent execution
+ */
+export interface SubagentResult {
+    /** Subagent identifier */
+    id: string;
+    /** Task identifier */
+    taskId: string;
+    /** Subagent role */
+    role: SubagentRole;
+    /** Whether execution was successful */
+    success: boolean;
+    /** Output/response from the subagent */
+    output: string;
+    /** Files modified */
+    filesModified?: string[];
+    /** Files created */
+    filesCreated?: string[];
+    /** Tool calls made during execution */
+    toolCalls?: LLMToolCall[];
+    /** Error message if failed */
+    error?: string;
+    /** Execution time in milliseconds */
+    executionTime: number;
+    /** Final status */
+    status: SubagentStatus;
+    /** Artifacts produced (file paths, URLs, etc) */
+    artifacts?: string[];
+}
+/**
+ * Message sent to/from a subagent
+ */
+export interface SubagentMessage {
+    /** Message sender */
+    from: 'parent' | 'subagent';
+    /** Message recipient */
+    to: 'parent' | 'subagent';
+    /** Message type */
+    type: 'instruction' | 'progress' | 'result' | 'error' | 'cancellation';
+    /** Message content */
+    content: string;
+    /** Timestamp */
+    timestamp: Date;
+    /** Additional data */
+    data?: unknown;
+}
+/**
+ * Event emitted by subagent system
+ */
+export interface SubagentEvent {
+    /** Event type */
+    type: 'spawn' | 'start' | 'progress' | 'complete' | 'fail' | 'cancel';
+    /** Subagent ID */
+    subagentId: string;
+    /** Task ID */
+    taskId: string;
+    /** Event data */
+    data?: unknown;
+    /** Timestamp */
+    timestamp: Date;
+}
+/**
+ * Configuration for subagent orchestrator
+ */
+export interface OrchestratorConfig {
+    /** Maximum concurrent subagents */
+    maxConcurrentAgents: number;
+    /** Default timeout for subagents */
+    defaultTimeout: number;
+    /** Enable automatic checkpoint before spawning */
+    autoCheckpoint: boolean;
+    /** Enable detailed logging */
+    verbose: boolean;
+}
+/**
+ * Dependency graph node
+ */
+export interface DependencyNode {
+    /** Task ID */
+    taskId: string;
+    /** Tasks this depends on */
+    dependencies: string[];
+    /** Tasks that depend on this */
+    dependents: string[];
+    /** Execution level (0 = no dependencies) */
+    level: number;
+}
+/**
+ * Dependency graph
+ */
+export interface DependencyGraph {
+    /** All nodes in the graph */
+    nodes: Map<string, DependencyNode>;
+    /** Execution order (batches that can run in parallel) */
+    executionOrder: string[][];
+    /** Whether graph has cycles */
+    hasCycles: boolean;
+    /** Cycle details if any */
+    cycles?: string[][];
+}
+/**
+ * Default subagent configuration by role
+ */
+export declare const DEFAULT_SUBAGENT_CONFIG: Record<SubagentRole, Partial<SubagentConfig>>;
+/**
+ * System prompts for each subagent role
+ */
+export declare const SUBAGENT_SYSTEM_PROMPTS: Record<SubagentRole, string>;

package/dist/agent/subagent-types.js

@@ -0,0 +1,152 @@
+/**
+ * Subagent System Types
+ *
+ * Type definitions for the autonomous subagent system that enables
+ * parallel task execution and specialized agent capabilities.
+ */
+/**
+ * Types of specialized agents available
+ */
+export var SubagentRole;
+(function (SubagentRole) {
+    /** General-purpose agent for any task */
+    SubagentRole["GENERAL"] = "general";
+    /** Specialized in writing and running tests */
+    SubagentRole["TESTING"] = "testing";
+    /** Specialized in generating documentation */
+    SubagentRole["DOCUMENTATION"] = "documentation";
+    /** Specialized in code refactoring */
+    SubagentRole["REFACTORING"] = "refactoring";
+    /** Specialized in code analysis and bug detection */
+    SubagentRole["ANALYSIS"] = "analysis";
+    /** Specialized in debugging and error resolution */
+    SubagentRole["DEBUG"] = "debug";
+    /** Specialized in performance optimization */
+    SubagentRole["PERFORMANCE"] = "performance";
+})(SubagentRole || (SubagentRole = {}));
+/**
+ * Execution state of a subagent
+ */
+export var SubagentState;
+(function (SubagentState) {
+    /** Waiting to be started */
+    SubagentState["PENDING"] = "pending";
+    /** Currently executing */
+    SubagentState["RUNNING"] = "running";
+    /** Successfully completed */
+    SubagentState["COMPLETED"] = "completed";
+    /** Failed with error */
+    SubagentState["FAILED"] = "failed";
+    /** Cancelled by user or system */
+    SubagentState["CANCELLED"] = "cancelled";
+})(SubagentState || (SubagentState = {}));
+/**
+ * Default subagent configuration by role
+ */
+export const DEFAULT_SUBAGENT_CONFIG = {
+    [SubagentRole.GENERAL]: {
+        allowedTools: ['bash', 'text_editor', 'search', 'todo'],
+        maxToolRounds: 30,
+        contextDepth: 20,
+        priority: 1,
+    },
+    [SubagentRole.TESTING]: {
+        allowedTools: ['bash', 'text_editor', 'search'],
+        maxToolRounds: 20,
+        contextDepth: 15,
+        priority: 2,
+    },
+    [SubagentRole.DOCUMENTATION]: {
+        allowedTools: ['text_editor', 'search'],
+        maxToolRounds: 15,
+        contextDepth: 10,
+        priority: 2,
+    },
+    [SubagentRole.REFACTORING]: {
+        allowedTools: ['text_editor', 'search', 'bash'],
+        maxToolRounds: 25,
+        contextDepth: 20,
+        priority: 2,
+    },
+    [SubagentRole.ANALYSIS]: {
+        allowedTools: ['search', 'bash'],
+        maxToolRounds: 15,
+        contextDepth: 15,
+        priority: 3,
+    },
+    [SubagentRole.DEBUG]: {
+        allowedTools: ['bash', 'text_editor', 'search'],
+        maxToolRounds: 25,
+        contextDepth: 20,
+        priority: 3,
+    },
+    [SubagentRole.PERFORMANCE]: {
+        allowedTools: ['bash', 'search', 'text_editor'],
+        maxToolRounds: 20,
+        contextDepth: 15,
+        priority: 2,
+    },
+};
+/**
+ * System prompts for each subagent role
+ */
+export const SUBAGENT_SYSTEM_PROMPTS = {
+    [SubagentRole.GENERAL]: `You are a general-purpose AI coding assistant.
+You can handle any coding task assigned to you.
+Be thorough, clear, and follow best practices.`,
+    [SubagentRole.TESTING]: `You are a specialized testing agent.
+Your role is to:
+- Write comprehensive unit tests
+- Write integration tests
+- Ensure high test coverage
+- Follow testing best practices for the project's framework
+- Write clear, maintainable test code
+- Include edge cases and error scenarios
+Focus ONLY on testing tasks.`,
+    [SubagentRole.DOCUMENTATION]: `You are a specialized documentation agent.
+Your role is to:
+- Generate clear, comprehensive documentation
+- Follow documentation standards (JSDoc, Markdown, etc.)
+- Include usage examples
+- Document edge cases and limitations
+- Write in clear, concise language
+- Structure documentation logically
+Focus ONLY on documentation tasks.`,
+    [SubagentRole.REFACTORING]: `You are a specialized refactoring agent.
+Your role is to:
+- Improve code structure and readability
+- Apply SOLID principles
+- Reduce code duplication
+- Optimize performance where applicable
+- Maintain backward compatibility
+- Preserve existing functionality
+Focus ONLY on refactoring tasks.`,
+    [SubagentRole.ANALYSIS]: `You are a specialized code analysis agent.
+Your role is to:
+- Analyze code for potential bugs
+- Identify security vulnerabilities
+- Detect code smells and anti-patterns
+- Suggest improvements
+- Check for best practice violations
+- Provide detailed analysis reports
+Focus ONLY on analysis tasks.`,
+    [SubagentRole.DEBUG]: `You are a specialized debugging agent.
+Your role is to:
+- Identify and fix bugs
+- Add proper error handling
+- Improve error messages
+- Add logging where helpful
+- Test fixes thoroughly
+- Explain the root cause of issues
+Focus ONLY on debugging tasks.`,
+    [SubagentRole.PERFORMANCE]: `You are a specialized performance optimization agent.
+Your role is to:
+- Identify performance bottlenecks
+- Optimize algorithms and data structures
+- Reduce memory usage
+- Improve execution speed
+- Add performance monitoring
+- Benchmark optimizations
+Focus ONLY on performance tasks.`,
+};
+//# sourceMappingURL=subagent-types.js.map

package/dist/agent/subagent-types.js.map

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

package/dist/agent/subagent.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Subagent Base Class
+ *
+ * Base class for all specialized subagents. Subagents are lightweight AI agents
+ * that focus on specific tasks (testing, documentation, refactoring, etc.) with
+ * limited tool access and shallow conversation history.
+ */
+import { EventEmitter } from 'events';
+import { LLMClient } from '../llm/client.js';
+import type { LLMMessage } from '../llm/client.js';
+import type { ChatEntry } from './llm-agent.js';
+import type { SubagentConfig, SubagentTask, SubagentResult, SubagentStatus } from './subagent-types.js';
+import { SubagentRole } from './subagent-types.js';
+/**
+ * Base Subagent class
+ */
+export declare class Subagent extends EventEmitter {
+    readonly id: string;
+    readonly role: SubagentRole;
+    readonly config: SubagentConfig;
+    protected llmClient: LLMClient;
+    protected chatHistory: ChatEntry[];
+    protected messages: LLMMessage[];
+    protected tools: Map<string, any>;
+    protected isActive: boolean;
+    protected currentTaskId: string | null;
+    protected status: SubagentStatus;
+    constructor(role: SubagentRole, configOverrides?: Partial<SubagentConfig>);
+    /**
+     * Get default configuration for a role
+     */
+    private getDefaultConfig;
+    /**
+     * Initialize tools based on allowed tools in config
+     */
+    private initializeTools;
+    /**
+     * Build system prompt for this subagent role
+     * Override in specialized subagent classes
+     */
+    protected buildSystemPrompt(): string;
+    /**
+     * Execute a task
+     */
+    executeTask(task: SubagentTask): Promise<SubagentResult>;
+    /**
+     * Build context prompt from task
+     */
+    private buildContextPrompt;
+    /**
+     * Execute a tool call
+     */
+    private executeToolCall;
+    /**
+     * Get tool definitions for LLM
+     */
+    private getToolDefinitions;
+    /**
+     * Get current status
+     */
+    getStatus(): SubagentStatus;
+    /**
+     * Abort execution
+     */
+    abort(): void;
+    /**
+     * Terminate subagent
+     */
+    terminate(): Promise<void>;
+    /**
+     * Get chat history (for debugging/monitoring)
+     */
+    getChatHistory(): ChatEntry[];
+    /**
+     * Get logs (alias for getChatHistory for test compatibility)
+     */
+    getLogs(): ChatEntry[];
+    /**
+     * Receive a message from parent/orchestrator
+     */
+    receiveMessage(message: {
+        from: 'parent' | 'orchestrator';
+        to: 'subagent';
+        type: 'instruction' | 'cancellation' | 'query';
+        content: string;
+        timestamp: Date;
+    }): Promise<void>;
+}