@defai.digital/ax-cli 2.7.0 → 3.0.0

package/dist/planner/types.d.ts

@@ -0,0 +1,669 @@
+/**
+ * Multi-Phase Task Planning System - Type Definitions
+ *
+ * Defines the core data structures for task decomposition,
+ * phase execution, and plan persistence.
+ */
+import { z } from "zod";
+/**
+ * Risk level for a phase - determines approval requirements
+ */
+export declare enum RiskLevel {
+    LOW = "low",
+    MEDIUM = "medium",
+    HIGH = "high"
+}
+/**
+ * Fallback strategy when a phase fails
+ */
+export declare enum FallbackStrategy {
+    RETRY = "retry",// Retry the phase (up to max attempts)
+    SKIP = "skip",// Skip and continue to next phase
+    ABORT = "abort"
+}
+/**
+ * Status of an individual phase
+ */
+export declare enum PhaseStatus {
+    PENDING = "pending",// Not started yet
+    APPROVED = "approved",// User approved (if required)
+    QUEUED = "queued",// Ready to execute
+    EXECUTING = "executing",// Currently running
+    COMPLETED = "completed",// Successfully finished
+    FAILED = "failed",// Execution failed
+    SKIPPED = "skipped",// User skipped
+    CANCELLED = "cancelled"
+}
+/**
+ * Status of the overall plan
+ */
+export declare enum PlanStatus {
+    CREATED = "created",// Plan generated, not approved
+    APPROVED = "approved",// User approved, ready to execute
+    EXECUTING = "executing",// Currently running phases
+    PAUSED = "paused",// User paused execution
+    COMPLETED = "completed",// All phases done
+    FAILED = "failed",// A phase failed, awaiting action
+    ABANDONED = "abandoned"
+}
+/**
+ * Represents a single phase in the execution plan
+ */
+export interface TaskPhase {
+    /** Unique identifier for this phase */
+    id: string;
+    /** Order in the plan (0-indexed) */
+    index: number;
+    /** Short descriptive name */
+    name: string;
+    /** Detailed description of what this phase accomplishes */
+    description: string;
+    /** Specific objectives/goals for this phase */
+    objectives: string[];
+    /** Tools that this phase is expected to use */
+    toolsRequired: string[];
+    /** Phase IDs that must complete before this one */
+    dependencies: string[];
+    /** Whether this phase can run in parallel with others */
+    canRunInParallel: boolean;
+    /** Risk assessment for this phase */
+    riskLevel: RiskLevel;
+    /** Whether user approval is required before execution */
+    requiresApproval: boolean;
+    /** What to do if this phase fails */
+    fallbackStrategy: FallbackStrategy;
+    /** Maximum retry attempts (if fallbackStrategy is RETRY) */
+    maxRetries: number;
+    /** Current status of this phase */
+    status: PhaseStatus;
+    /** When execution started */
+    startedAt?: Date;
+    /** When execution completed */
+    completedAt?: Date;
+    /** Duration in milliseconds */
+    duration?: number;
+    /** Checkpoint ID created before this phase */
+    checkpointId?: string;
+    /** Number of retry attempts made */
+    retryCount: number;
+    /** Summary of phase output/results */
+    output?: string;
+    /** Error message if failed */
+    error?: string;
+    /** Tokens consumed by this phase */
+    tokensUsed?: number;
+    /** Files modified during this phase */
+    filesModified?: string[];
+}
+/**
+ * Represents a complete execution plan
+ */
+export interface TaskPlan {
+    /** Unique identifier for this plan */
+    id: string;
+    /** Schema version for migrations */
+    version: number;
+    /** Original user request that triggered planning */
+    originalPrompt: string;
+    /** LLM's reasoning for this decomposition */
+    reasoning: string;
+    /** Overall complexity assessment */
+    complexity: "simple" | "moderate" | "complex";
+    /** Ordered list of phases */
+    phases: TaskPhase[];
+    /** Index of currently executing phase (-1 if not started) */
+    currentPhaseIndex: number;
+    /** Overall plan status */
+    status: PlanStatus;
+    /** When the plan was created */
+    createdAt: Date;
+    /** Last update timestamp */
+    updatedAt: Date;
+    /** Estimated total tokens for all phases */
+    estimatedTotalTokens: number;
+    /** Estimated total duration in milliseconds */
+    estimatedDuration: number;
+    /** Checkpoint ID for plan start state */
+    initialCheckpointId?: string;
+    /** Total tokens actually used */
+    totalTokensUsed: number;
+    /** Actual total duration */
+    actualDuration: number;
+    /** Number of phases completed */
+    phasesCompleted: number;
+    /** Number of phases failed */
+    phasesFailed: number;
+    /** Number of phases skipped */
+    phasesSkipped: number;
+}
+/**
+ * Result of executing a single phase
+ */
+export interface PhaseResult {
+    /** Phase ID */
+    phaseId: string;
+    /** Whether execution succeeded */
+    success: boolean;
+    /** Output/summary from the phase */
+    output?: string;
+    /** Error message if failed */
+    error?: string;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Tokens consumed */
+    tokensUsed: number;
+    /** Files that were modified */
+    filesModified: string[];
+    /** Checkpoint ID after this phase */
+    checkpointId?: string;
+    /** Whether this was a retry */
+    wasRetry: boolean;
+    /** Retry attempt number (0 for first attempt) */
+    retryAttempt: number;
+}
+/**
+ * Result of executing an entire plan
+ */
+export interface PlanResult {
+    /** Plan ID */
+    planId: string;
+    /** Overall success (all phases completed) */
+    success: boolean;
+    /** Results for each phase */
+    phaseResults: PhaseResult[];
+    /** Total duration */
+    totalDuration: number;
+    /** Total tokens used */
+    totalTokensUsed: number;
+    /** Summary of what was accomplished */
+    summary: string;
+    /** Any warnings or notes */
+    warnings: string[];
+}
+/**
+ * Options for plan execution
+ */
+export interface ExecutionOptions {
+    /** Auto-approve all phases (bypass approval gates) */
+    autoApprove: boolean;
+    /** Auto-approve only low-risk phases */
+    autoApproveLowRisk: boolean;
+    /** Create checkpoints before each phase */
+    createCheckpoints: boolean;
+    /** Prune context between phases */
+    pruneContextBetweenPhases: boolean;
+    /** Target context percentage after pruning */
+    targetContextPercentage: number;
+    /** Maximum parallel phases */
+    maxParallelPhases: number;
+    /** Phase timeout in milliseconds */
+    phaseTimeoutMs: number;
+    /** Callback when phase starts */
+    onPhaseStart?: (phase: TaskPhase) => void;
+    /** Callback when phase completes */
+    onPhaseComplete?: (phase: TaskPhase, result: PhaseResult) => void;
+    /** Callback when phase fails */
+    onPhaseFailed?: (phase: TaskPhase, error: Error) => void;
+    /** Callback for approval request */
+    onApprovalRequest?: (phase: TaskPhase) => Promise<boolean>;
+    /** Callback when plan is paused */
+    onPlanPaused?: (plan: TaskPlan) => void;
+}
+/**
+ * Options for the TaskPlanner
+ */
+export interface PlannerOptions {
+    /** Maximum phases to generate */
+    maxPhases: number;
+    /** Minimum tool calls to trigger auto-planning */
+    autoPlanThreshold: number;
+    /** Whether to require plan approval before execution */
+    requirePlanApproval: boolean;
+    /** Whether to require approval for high-risk phases */
+    requireHighRiskApproval: boolean;
+    /** Default execution options */
+    defaultExecutionOptions: Partial<ExecutionOptions>;
+}
+/**
+ * Saved plan state for persistence
+ */
+export interface SavedPlanState {
+    /** The plan definition */
+    plan: TaskPlan;
+    /** When the state was saved */
+    savedAt: Date;
+    /** Reason for saving (paused, checkpoint, etc.) */
+    saveReason: "paused" | "checkpoint" | "completed" | "failed";
+    /** Conversation context at save time */
+    conversationContext?: unknown[];
+    /** Files that were tracked */
+    trackedFiles?: Array<{
+        path: string;
+        hash: string;
+    }>;
+}
+export declare const RiskLevelSchema: z.ZodNativeEnum<typeof RiskLevel>;
+export declare const FallbackStrategySchema: z.ZodNativeEnum<typeof FallbackStrategy>;
+export declare const PhaseStatusSchema: z.ZodNativeEnum<typeof PhaseStatus>;
+export declare const PlanStatusSchema: z.ZodNativeEnum<typeof PlanStatus>;
+export declare const TaskPhaseSchema: z.ZodObject<{
+    id: z.ZodString;
+    index: z.ZodNumber;
+    name: z.ZodString;
+    description: z.ZodString;
+    objectives: z.ZodArray<z.ZodString, "many">;
+    toolsRequired: z.ZodArray<z.ZodString, "many">;
+    dependencies: z.ZodArray<z.ZodString, "many">;
+    canRunInParallel: z.ZodBoolean;
+    riskLevel: z.ZodNativeEnum<typeof RiskLevel>;
+    requiresApproval: z.ZodBoolean;
+    fallbackStrategy: z.ZodNativeEnum<typeof FallbackStrategy>;
+    maxRetries: z.ZodDefault<z.ZodNumber>;
+    status: z.ZodNativeEnum<typeof PhaseStatus>;
+    startedAt: z.ZodOptional<z.ZodDate>;
+    completedAt: z.ZodOptional<z.ZodDate>;
+    duration: z.ZodOptional<z.ZodNumber>;
+    checkpointId: z.ZodOptional<z.ZodString>;
+    retryCount: z.ZodDefault<z.ZodNumber>;
+    output: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+    tokensUsed: z.ZodOptional<z.ZodNumber>;
+    filesModified: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    status: PhaseStatus;
+    description: string;
+    id: string;
+    index: number;
+    dependencies: string[];
+    objectives: string[];
+    toolsRequired: string[];
+    canRunInParallel: boolean;
+    riskLevel: RiskLevel;
+    requiresApproval: boolean;
+    fallbackStrategy: FallbackStrategy;
+    maxRetries: number;
+    retryCount: number;
+    duration?: number | undefined;
+    error?: string | undefined;
+    output?: string | undefined;
+    startedAt?: Date | undefined;
+    completedAt?: Date | undefined;
+    checkpointId?: string | undefined;
+    tokensUsed?: number | undefined;
+    filesModified?: string[] | undefined;
+}, {
+    name: string;
+    status: PhaseStatus;
+    description: string;
+    id: string;
+    index: number;
+    dependencies: string[];
+    objectives: string[];
+    toolsRequired: string[];
+    canRunInParallel: boolean;
+    riskLevel: RiskLevel;
+    requiresApproval: boolean;
+    fallbackStrategy: FallbackStrategy;
+    duration?: number | undefined;
+    error?: string | undefined;
+    output?: string | undefined;
+    maxRetries?: number | undefined;
+    startedAt?: Date | undefined;
+    completedAt?: Date | undefined;
+    checkpointId?: string | undefined;
+    retryCount?: number | undefined;
+    tokensUsed?: number | undefined;
+    filesModified?: string[] | undefined;
+}>;
+export declare const TaskPlanSchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodNumber;
+    originalPrompt: z.ZodString;
+    reasoning: z.ZodString;
+    complexity: z.ZodEnum<["simple", "moderate", "complex"]>;
+    phases: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        index: z.ZodNumber;
+        name: z.ZodString;
+        description: z.ZodString;
+        objectives: z.ZodArray<z.ZodString, "many">;
+        toolsRequired: z.ZodArray<z.ZodString, "many">;
+        dependencies: z.ZodArray<z.ZodString, "many">;
+        canRunInParallel: z.ZodBoolean;
+        riskLevel: z.ZodNativeEnum<typeof RiskLevel>;
+        requiresApproval: z.ZodBoolean;
+        fallbackStrategy: z.ZodNativeEnum<typeof FallbackStrategy>;
+        maxRetries: z.ZodDefault<z.ZodNumber>;
+        status: z.ZodNativeEnum<typeof PhaseStatus>;
+        startedAt: z.ZodOptional<z.ZodDate>;
+        completedAt: z.ZodOptional<z.ZodDate>;
+        duration: z.ZodOptional<z.ZodNumber>;
+        checkpointId: z.ZodOptional<z.ZodString>;
+        retryCount: z.ZodDefault<z.ZodNumber>;
+        output: z.ZodOptional<z.ZodString>;
+        error: z.ZodOptional<z.ZodString>;
+        tokensUsed: z.ZodOptional<z.ZodNumber>;
+        filesModified: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        status: PhaseStatus;
+        description: string;
+        id: string;
+        index: number;
+        dependencies: string[];
+        objectives: string[];
+        toolsRequired: string[];
+        canRunInParallel: boolean;
+        riskLevel: RiskLevel;
+        requiresApproval: boolean;
+        fallbackStrategy: FallbackStrategy;
+        maxRetries: number;
+        retryCount: number;
+        duration?: number | undefined;
+        error?: string | undefined;
+        output?: string | undefined;
+        startedAt?: Date | undefined;
+        completedAt?: Date | undefined;
+        checkpointId?: string | undefined;
+        tokensUsed?: number | undefined;
+        filesModified?: string[] | undefined;
+    }, {
+        name: string;
+        status: PhaseStatus;
+        description: string;
+        id: string;
+        index: number;
+        dependencies: string[];
+        objectives: string[];
+        toolsRequired: string[];
+        canRunInParallel: boolean;
+        riskLevel: RiskLevel;
+        requiresApproval: boolean;
+        fallbackStrategy: FallbackStrategy;
+        duration?: number | undefined;
+        error?: string | undefined;
+        output?: string | undefined;
+        maxRetries?: number | undefined;
+        startedAt?: Date | undefined;
+        completedAt?: Date | undefined;
+        checkpointId?: string | undefined;
+        retryCount?: number | undefined;
+        tokensUsed?: number | undefined;
+        filesModified?: string[] | undefined;
+    }>, "many">;
+    currentPhaseIndex: z.ZodNumber;
+    status: z.ZodNativeEnum<typeof PlanStatus>;
+    createdAt: z.ZodDate;
+    updatedAt: z.ZodDate;
+    estimatedTotalTokens: z.ZodNumber;
+    estimatedDuration: z.ZodNumber;
+    initialCheckpointId: z.ZodOptional<z.ZodString>;
+    totalTokensUsed: z.ZodDefault<z.ZodNumber>;
+    actualDuration: z.ZodDefault<z.ZodNumber>;
+    phasesCompleted: z.ZodDefault<z.ZodNumber>;
+    phasesFailed: z.ZodDefault<z.ZodNumber>;
+    phasesSkipped: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    status: PlanStatus;
+    id: string;
+    reasoning: string;
+    version: number;
+    originalPrompt: string;
+    complexity: "simple" | "moderate" | "complex";
+    phases: {
+        name: string;
+        status: PhaseStatus;
+        description: string;
+        id: string;
+        index: number;
+        dependencies: string[];
+        objectives: string[];
+        toolsRequired: string[];
+        canRunInParallel: boolean;
+        riskLevel: RiskLevel;
+        requiresApproval: boolean;
+        fallbackStrategy: FallbackStrategy;
+        maxRetries: number;
+        retryCount: number;
+        duration?: number | undefined;
+        error?: string | undefined;
+        output?: string | undefined;
+        startedAt?: Date | undefined;
+        completedAt?: Date | undefined;
+        checkpointId?: string | undefined;
+        tokensUsed?: number | undefined;
+        filesModified?: string[] | undefined;
+    }[];
+    currentPhaseIndex: number;
+    createdAt: Date;
+    updatedAt: Date;
+    estimatedTotalTokens: number;
+    estimatedDuration: number;
+    totalTokensUsed: number;
+    actualDuration: number;
+    phasesCompleted: number;
+    phasesFailed: number;
+    phasesSkipped: number;
+    initialCheckpointId?: string | undefined;
+}, {
+    status: PlanStatus;
+    id: string;
+    reasoning: string;
+    version: number;
+    originalPrompt: string;
+    complexity: "simple" | "moderate" | "complex";
+    phases: {
+        name: string;
+        status: PhaseStatus;
+        description: string;
+        id: string;
+        index: number;
+        dependencies: string[];
+        objectives: string[];
+        toolsRequired: string[];
+        canRunInParallel: boolean;
+        riskLevel: RiskLevel;
+        requiresApproval: boolean;
+        fallbackStrategy: FallbackStrategy;
+        duration?: number | undefined;
+        error?: string | undefined;
+        output?: string | undefined;
+        maxRetries?: number | undefined;
+        startedAt?: Date | undefined;
+        completedAt?: Date | undefined;
+        checkpointId?: string | undefined;
+        retryCount?: number | undefined;
+        tokensUsed?: number | undefined;
+        filesModified?: string[] | undefined;
+    }[];
+    currentPhaseIndex: number;
+    createdAt: Date;
+    updatedAt: Date;
+    estimatedTotalTokens: number;
+    estimatedDuration: number;
+    initialCheckpointId?: string | undefined;
+    totalTokensUsed?: number | undefined;
+    actualDuration?: number | undefined;
+    phasesCompleted?: number | undefined;
+    phasesFailed?: number | undefined;
+    phasesSkipped?: number | undefined;
+}>;
+export declare const PhaseResultSchema: z.ZodObject<{
+    phaseId: z.ZodString;
+    success: z.ZodBoolean;
+    output: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+    duration: z.ZodNumber;
+    tokensUsed: z.ZodNumber;
+    filesModified: z.ZodArray<z.ZodString, "many">;
+    checkpointId: z.ZodOptional<z.ZodString>;
+    wasRetry: z.ZodBoolean;
+    retryAttempt: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    duration: number;
+    success: boolean;
+    tokensUsed: number;
+    filesModified: string[];
+    phaseId: string;
+    wasRetry: boolean;
+    retryAttempt: number;
+    error?: string | undefined;
+    output?: string | undefined;
+    checkpointId?: string | undefined;
+}, {
+    duration: number;
+    success: boolean;
+    tokensUsed: number;
+    filesModified: string[];
+    phaseId: string;
+    wasRetry: boolean;
+    retryAttempt: number;
+    error?: string | undefined;
+    output?: string | undefined;
+    checkpointId?: string | undefined;
+}>;
+/**
+ * Schema for LLM-generated phase (before adding execution state)
+ */
+export declare const LLMPhaseResponseSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    objectives: z.ZodArray<z.ZodString, "many">;
+    toolsRequired: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    dependencies: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    canRunInParallel: z.ZodDefault<z.ZodBoolean>;
+    riskLevel: z.ZodDefault<z.ZodEnum<["low", "medium", "high"]>>;
+    requiresApproval: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    dependencies: string[];
+    objectives: string[];
+    toolsRequired: string[];
+    canRunInParallel: boolean;
+    riskLevel: "high" | "medium" | "low";
+    requiresApproval: boolean;
+}, {
+    name: string;
+    description: string;
+    objectives: string[];
+    dependencies?: string[] | undefined;
+    toolsRequired?: string[] | undefined;
+    canRunInParallel?: boolean | undefined;
+    riskLevel?: "high" | "medium" | "low" | undefined;
+    requiresApproval?: boolean | undefined;
+}>;
+/**
+ * Schema for LLM-generated plan response
+ */
+export declare const LLMPlanResponseSchema: z.ZodObject<{
+    reasoning: z.ZodString;
+    complexity: z.ZodEnum<["simple", "moderate", "complex"]>;
+    phases: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        objectives: z.ZodArray<z.ZodString, "many">;
+        toolsRequired: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        dependencies: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        canRunInParallel: z.ZodDefault<z.ZodBoolean>;
+        riskLevel: z.ZodDefault<z.ZodEnum<["low", "medium", "high"]>>;
+        requiresApproval: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description: string;
+        dependencies: string[];
+        objectives: string[];
+        toolsRequired: string[];
+        canRunInParallel: boolean;
+        riskLevel: "high" | "medium" | "low";
+        requiresApproval: boolean;
+    }, {
+        name: string;
+        description: string;
+        objectives: string[];
+        dependencies?: string[] | undefined;
+        toolsRequired?: string[] | undefined;
+        canRunInParallel?: boolean | undefined;
+        riskLevel?: "high" | "medium" | "low" | undefined;
+        requiresApproval?: boolean | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    reasoning: string;
+    complexity: "simple" | "moderate" | "complex";
+    phases: {
+        name: string;
+        description: string;
+        dependencies: string[];
+        objectives: string[];
+        toolsRequired: string[];
+        canRunInParallel: boolean;
+        riskLevel: "high" | "medium" | "low";
+        requiresApproval: boolean;
+    }[];
+}, {
+    reasoning: string;
+    complexity: "simple" | "moderate" | "complex";
+    phases: {
+        name: string;
+        description: string;
+        objectives: string[];
+        dependencies?: string[] | undefined;
+        toolsRequired?: string[] | undefined;
+        canRunInParallel?: boolean | undefined;
+        riskLevel?: "high" | "medium" | "low" | undefined;
+        requiresApproval?: boolean | undefined;
+    }[];
+}>;
+export type LLMPhaseResponse = z.infer<typeof LLMPhaseResponseSchema>;
+export type LLMPlanResponse = z.infer<typeof LLMPlanResponseSchema>;
+/**
+ * Phase with minimal info for display
+ */
+export interface PhaseDisplayInfo {
+    id: string;
+    index: number;
+    name: string;
+    status: PhaseStatus;
+    riskLevel: RiskLevel;
+    duration?: number;
+    isCurrentPhase: boolean;
+}
+/**
+ * Plan summary for listing
+ */
+export interface PlanSummary {
+    id: string;
+    originalPrompt: string;
+    status: PlanStatus;
+    totalPhases: number;
+    completedPhases: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Recovery action after phase failure
+ */
+export interface RecoveryAction {
+    action: "retry" | "skip" | "abort" | "rewind";
+    phaseId?: string;
+    reason?: string;
+    attempts?: number;
+    delay?: number;
+}
+/**
+ * Create a new TaskPhase with defaults
+ */
+export declare function createPhase(partial: Partial<TaskPhase> & Pick<TaskPhase, "id" | "index" | "name" | "description">): TaskPhase;
+/**
+ * Create a new TaskPlan with defaults
+ */
+export declare function createPlan(partial: Partial<TaskPlan> & Pick<TaskPlan, "id" | "originalPrompt" | "phases">): TaskPlan;
+/**
+ * Create default execution options
+ */
+export declare function createDefaultExecutionOptions(): ExecutionOptions;
+/**
+ * Create default planner options
+ */
+export declare function createDefaultPlannerOptions(): PlannerOptions;