@kjerneverk/riotplan-ai 1.0.0-dev.0

package/dist/index.d.ts

@@ -0,0 +1,731 @@
+import { Tool } from '@kjerneverk/agentic';
+
+export declare interface AIValidationReport {
+    overallPassed: boolean;
+    checks: {
+        name: string;
+        result: AIValidationResult;
+    }[];
+    allWarnings: string[];
+}
+
+export declare interface AIValidationResult {
+    passed: boolean;
+    warnings: string[];
+    details: Record<string, any>;
+}
+
+/**
+ * Apply tiering decisions to evidence array
+ */
+export declare function applyEvidenceTiering(evidence: {
+    name: string;
+    content: string;
+    size: number;
+}[], decision: TieringDecision): {
+    name: string;
+    content: string;
+    size: number;
+    tiered?: 'summarized' | 'listOnly';
+}[];
+
+export declare interface ApproachAnalysis {
+    selectedApproach: string;
+    commitments: string;
+    implementationStrategy: string;
+}
+
+/**
+ * Artifact Loading Utilities
+ *
+ * Shared functions for loading and extracting plan artifacts (IDEA.md, SHAPING.md, evidence, history)
+ * Used by both build.ts and context.ts to ensure consistent artifact handling
+ */
+export declare interface ArtifactBundle {
+    ideaContent: string | null;
+    shapingContent: string | null;
+    lifecycleContent: string | null;
+    artifactDiagnostics?: {
+        planId: string;
+        hasIdeaArtifact: boolean;
+        detectedArtifacts: Array<{
+            type: string;
+            filename: string;
+        }>;
+    };
+    constraints: string[];
+    questions: string[];
+    selectedApproach: {
+        name: string;
+        description: string;
+        reasoning: string;
+    } | null;
+    evidence: {
+        name: string;
+        content: string;
+        size: number;
+    }[];
+    historyContext: {
+        recentEvents: {
+            type: string;
+            timestamp: string;
+            summary: string;
+        }[];
+        totalEvents: number;
+    };
+    catalystContent?: {
+        constraints: string;
+        domainKnowledge: string;
+        outputTemplates: string;
+        processGuidance: string;
+        questions: string;
+        validationRules: string;
+        appliedCatalysts: string[];
+    };
+}
+
+/**
+ * Attributed content item from merged catalyst
+ */
+declare interface AttributedContentItem {
+    content: string;
+    sourceId: string;
+    filename?: string;
+}
+
+/**
+ * Build the user prompt for plan generation
+ *
+ * If structured artifact fields are present (constraints, evidence, selectedApproach, history),
+ * constructs a rich prompt with labeled sections. Otherwise, falls back to the simple
+ * description-based prompt for backward compatibility.
+ */
+export declare function buildPlanPrompt(context: GenerationContext): string;
+
+/**
+ * Calculate tiering decisions based on artifact sizes and budget
+ */
+export declare function calculateTiering(constraints: string[], selectedApproach: {
+    name: string;
+    description: string;
+    reasoning: string;
+} | null, evidence: {
+    name: string;
+    content: string;
+    size: number;
+}[], historyEventCount: number, budget?: TokenBudget): TieringDecision;
+
+export declare interface ConstraintAnalysis {
+    constraint: string;
+    understanding: string;
+    plannedApproach: string;
+}
+
+/**
+ * Constraint Coverage Validation
+ * Ensures each constraint from IDEA.md is addressed by at least one step
+ */
+export declare class ConstraintCoverageCheck implements ValidationCheck {
+    name: string;
+    validate(plan: GeneratedPlan, context: GenerationContext): AIValidationResult;
+}
+
+/**
+ * Create a write_plan tool with a connected promise.
+ *
+ * The caller awaits `planPromise` while the agent explores the codebase.
+ * When the agent is ready, it calls `write_plan` with the plan JSON,
+ * which resolves the promise and returns the plan to the caller.
+ */
+export declare function createWritePlanTool(): WritePlanToolResult;
+
+export declare const DEFAULT_TOKEN_BUDGET: TokenBudget;
+
+/**
+ * Detect available providers
+ */
+export declare function detectAvailableProviders(): Promise<string[]>;
+
+/**
+ * Estimate token count from text
+ * Uses character count / 4 as a reasonable approximation
+ */
+export declare function estimateTokens(text: string): number;
+
+export declare interface EvidenceAnalysis {
+    evidenceFile: string;
+    keyFindings: string;
+    impactOnPlan: string;
+}
+
+/**
+ * Evidence Reference Validation
+ * Checks if provided evidence files are referenced in the plan
+ */
+export declare class EvidenceReferenceCheck implements ValidationCheck {
+    name: string;
+    validate(plan: GeneratedPlan, context: GenerationContext): AIValidationResult;
+}
+
+export declare interface ExecutionOptions {
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+    timeout?: number;
+}
+
+/**
+ * Extract constraints from IDEA.md content
+ */
+export declare function extractConstraints(ideaContent: string): string[];
+
+/**
+ * Extract questions from IDEA.md content
+ */
+export declare function extractQuestions(ideaContent: string): string[];
+
+/**
+ * Extract selected approach from SHAPING.md content
+ */
+export declare function extractSelectedApproach(shapingContent: string): {
+    name: string;
+    description: string;
+    reasoning: string;
+} | null;
+
+/**
+ * Format step into markdown content
+ */
+export declare function formatStep(step: GeneratedStep): string;
+
+/**
+ * Format a generated plan into markdown content for SUMMARY.md
+ */
+export declare function formatSummary(plan: GeneratedPlan, planName: string): string;
+
+export declare interface GeneratedPlan {
+    summary: string;
+    approach: string;
+    successCriteria: string;
+    steps: GeneratedStep[];
+    analysis?: PlanAnalysis;
+}
+
+export declare interface GeneratedStep {
+    number: number;
+    title: string;
+    objective: string;
+    background: string;
+    tasks: GeneratedTask[];
+    acceptanceCriteria: string[];
+    testing: string;
+    filesChanged: string[];
+    notes: string;
+    provenance?: StepProvenance;
+}
+
+export declare interface GeneratedTask {
+    id: string;
+    description: string;
+}
+
+/**
+ * Generate a plan using AI
+ */
+export declare function generatePlan(context: GenerationContext, provider: Provider, options?: GenerationOptionsWithProgress): Promise<GenerationResult>;
+
+/**
+ * Generate a plan using an agent loop with codebase tools.
+ *
+ * The agent explores the codebase using read-only tools, then calls
+ * write_plan to submit the structured plan. This produces higher-quality
+ * plans than the one-shot approach because the agent can:
+ * - Read actual source files
+ * - Search for patterns and references
+ * - Understand the project structure
+ * - Reference real file paths, interfaces, and functions
+ *
+ * @param context - Generation context with artifacts and description
+ * @param provider - Execution provider (will be adapted to AgentProvider)
+ * @param codebaseTools - Read-only environment tools (read_file, grep, etc.)
+ * @param options - Generation options including model and progress callback
+ * @param projectRoot - Project root directory for tool working directory
+ * @returns GenerationResult with the plan and tiering info
+ */
+export declare function generatePlanWithAgent(context: GenerationContext, provider: Provider, codebaseTools: Tool[], options?: GenerationOptionsWithProgress, projectRoot?: string): Promise<GenerationResult>;
+
+/**
+ * Generate PROVENANCE.md content
+ */
+export declare function generateProvenanceMarkdown(data: ProvenanceData): string;
+
+export declare interface GenerationContext {
+    planName: string;
+    description: string;
+    elaborations?: string[];
+    stepCount?: number;
+    constraints?: string[];
+    questions?: string[];
+    selectedApproach?: {
+        name: string;
+        description: string;
+        reasoning: string;
+    };
+    evidence?: {
+        name: string;
+        content: string;
+        size: number;
+    }[];
+    historyContext?: {
+        recentEvents: {
+            type: string;
+            timestamp: string;
+            summary: string;
+        }[];
+        totalEvents: number;
+    };
+    ideaContent?: string;
+    shapingContent?: string;
+    tokenBudget?: {
+        maxTokens?: number;
+        evidenceFullThreshold?: number;
+        evidenceSummaryThreshold?: number;
+        historyFullCount?: number;
+        historyAbbreviatedCount?: number;
+    };
+    codebaseContext?: string;
+    catalystContent?: {
+        constraints: string;
+        domainKnowledge: string;
+        outputTemplates: string;
+        processGuidance: string;
+        questions: string;
+        validationRules: string;
+        appliedCatalysts: string[];
+    };
+}
+
+/**
+ * Extended options for plan generation
+ */
+export declare interface GenerationOptionsWithProgress extends ExecutionOptions {
+    onProgress?: GenerationProgressCallback;
+}
+
+/**
+ * Progress callback for plan generation
+ */
+export declare type GenerationProgressCallback = (event: {
+    type: 'started' | 'streaming' | 'parsing' | 'complete';
+    charsReceived?: number;
+    message?: string;
+}) => void;
+
+export declare interface GenerationResult {
+    plan: GeneratedPlan;
+    tiering?: TieringDecision;
+}
+
+/**
+ * Get default provider based on environment variables
+ */
+export declare function getDefaultProvider(): string | null;
+
+export declare function getPlanGenerationSystemPrompt(): string;
+
+/**
+ * Get API key for a provider from environment
+ */
+export declare function getProviderApiKey(provider: string): string | undefined;
+
+/**
+ * Load all plan artifacts into a structured bundle
+ *
+ * This is the main entry point for artifact loading, used by build.ts
+ */
+export declare function loadArtifacts(planPath: string): Promise<ArtifactBundle>;
+
+/**
+ * Convert merged catalyst to the format needed by GenerationContext
+ *
+ * Takes a MergedCatalyst from @kjerneverk/riotplan-catalyst and converts it
+ * to the catalystContent format used by the generator.
+ *
+ * The mergedCatalyst parameter uses a simplified type to avoid tight coupling
+ * with the riotplan-catalyst package types.
+ */
+export declare function loadCatalystContent(mergedCatalyst: {
+    catalystIds: string[];
+    facets: {
+        questions?: AttributedContentItem[];
+        constraints?: AttributedContentItem[];
+        outputTemplates?: AttributedContentItem[];
+        domainKnowledge?: AttributedContentItem[];
+        processGuidance?: AttributedContentItem[];
+        validationRules?: AttributedContentItem[];
+    };
+} | null): ArtifactBundle['catalystContent'] | undefined;
+
+/**
+ * Load a provider based on session context and configuration
+ *
+ * Priority:
+ * 1. If session has sampling available → use SamplingProvider
+ * 2. If explicit provider name given → use that provider
+ * 3. If API keys available → use default provider
+ * 4. Otherwise → error with helpful message
+ */
+export declare function loadProvider(config: ProviderConfig): Promise<Provider>;
+
+/**
+ * LLM Provider types for AI plan generation
+ *
+ * These types define the interface between the AI module and LLM providers.
+ */
+export declare interface Message {
+    role: 'user' | 'assistant' | 'system' | 'developer' | 'tool';
+    content: string | string[] | null;
+    name?: string;
+}
+
+export declare function parsePlanResponse(content: string, _stepCount: number): GeneratedPlan;
+
+export declare const PLAN_GENERATION_RESPONSE_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly analysis: {
+            readonly type: "object";
+            readonly properties: {
+                readonly constraintAnalysis: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly constraint: {
+                                readonly type: "string";
+                            };
+                            readonly understanding: {
+                                readonly type: "string";
+                            };
+                            readonly plannedApproach: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly required: readonly ["constraint", "understanding", "plannedApproach"];
+                    };
+                };
+                readonly evidenceAnalysis: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly evidenceFile: {
+                                readonly type: "string";
+                            };
+                            readonly keyFindings: {
+                                readonly type: "string";
+                            };
+                            readonly impactOnPlan: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly required: readonly ["evidenceFile", "keyFindings", "impactOnPlan"];
+                    };
+                };
+                readonly approachAnalysis: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly selectedApproach: {
+                            readonly type: "string";
+                        };
+                        readonly commitments: {
+                            readonly type: "string";
+                        };
+                        readonly implementationStrategy: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+                readonly risks: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                };
+            };
+            readonly required: readonly ["constraintAnalysis"];
+        };
+        readonly summary: {
+            readonly type: "string";
+        };
+        readonly approach: {
+            readonly type: "string";
+        };
+        readonly successCriteria: {
+            readonly type: "string";
+        };
+        readonly steps: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly number: {
+                        readonly type: "number";
+                    };
+                    readonly title: {
+                        readonly type: "string";
+                    };
+                    readonly objective: {
+                        readonly type: "string";
+                    };
+                    readonly background: {
+                        readonly type: "string";
+                    };
+                    readonly tasks: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly id: {
+                                    readonly type: "string";
+                                };
+                                readonly description: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly required: readonly ["id", "description"];
+                        };
+                    };
+                    readonly acceptanceCriteria: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly testing: {
+                        readonly type: "string";
+                    };
+                    readonly filesChanged: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly notes: {
+                        readonly type: "string";
+                    };
+                    readonly provenance: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly constraintsAddressed: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly evidenceUsed: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly rationale: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                };
+                readonly required: readonly ["number", "title", "objective", "background", "tasks", "acceptanceCriteria", "testing", "filesChanged", "notes"];
+            };
+        };
+    };
+    readonly required: readonly ["analysis", "summary", "approach", "successCriteria", "steps"];
+};
+
+export declare interface PlanAnalysis {
+    constraintAnalysis: ConstraintAnalysis[];
+    evidenceAnalysis?: EvidenceAnalysis[];
+    approachAnalysis?: ApproachAnalysis;
+    risks?: string[];
+}
+
+export declare interface ProvenanceData {
+    plan: GeneratedPlan;
+    context: GenerationContext;
+    validation: AIValidationReport;
+    tiering?: TieringDecision;
+    generatedAt: Date;
+}
+
+export declare interface Provider {
+    name: string;
+    execute(request: Request_2, options?: ExecutionOptions): Promise<ProviderResponse>;
+    executeStream?(request: Request_2, options?: ExecutionOptions): AsyncIterable<StreamChunk>;
+}
+
+export declare interface ProviderConfig {
+    name: string;
+    apiKey?: string;
+    model?: string;
+    session?: SessionContext;
+    mcpServer?: any;
+}
+
+export declare interface ProviderResponse {
+    content: string;
+    model: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    toolCalls?: Array<{
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+}
+
+/**
+ * Read evidence files from the evidence directory
+ */
+export declare function readEvidenceFiles(planPath: string, includeContent?: boolean): Promise<{
+    name: string;
+    content: string;
+    size: number;
+}[]>;
+
+/**
+ * Read recent history events from timeline.jsonl
+ */
+export declare function readRecentHistory(planPath: string, limit?: number): Promise<{
+    recentEvents: {
+        type: string;
+        timestamp: string;
+        summary: string;
+    }[];
+    totalEvents: number;
+}>;
+
+declare interface Request_2 {
+    messages: Message[];
+    model: string;
+    responseFormat?: any;
+    validator?: any;
+    addMessage(message: Message): void;
+}
+export { Request_2 as Request }
+
+/**
+ * Selected Approach Validation
+ * Ensures the selected approach is reflected in the analysis
+ */
+export declare class SelectedApproachCheck implements ValidationCheck {
+    name: string;
+    validate(plan: GeneratedPlan, context: GenerationContext): AIValidationResult;
+}
+
+/**
+ * Minimal session context shape needed by the provider loader.
+ * The full SessionContext type lives in @kjerneverk/riotplan-mcp-http.
+ */
+declare interface SessionContext {
+    sessionId: string;
+    providerMode: 'sampling' | 'direct' | 'none';
+    clientInfo: {
+        name: string;
+        version: string;
+    } | null;
+}
+
+export declare interface StepProvenance {
+    constraintsAddressed?: string[];
+    evidenceUsed?: string[];
+    rationale?: string;
+}
+
+export declare interface StreamChunk {
+    type: 'text' | 'tool_call_start' | 'tool_call_delta' | 'tool_call_end' | 'usage' | 'done';
+    text?: string;
+    toolCall?: {
+        id?: string;
+        index?: number;
+        name?: string;
+        argumentsDelta?: string;
+    };
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+
+export declare interface TieringDecision {
+    totalEstimatedTokens: number;
+    budgetExceeded: boolean;
+    evidenceTiered: {
+        full: string[];
+        summarized: string[];
+        listOnly: string[];
+    };
+    historyAbbreviated: boolean;
+    warnings: string[];
+}
+
+/**
+ * Token Estimation and Budget Management
+ *
+ * Utilities for estimating token counts and managing prompt budgets
+ */
+export declare interface TokenBudget {
+    maxTokens: number;
+    evidenceFullThreshold: number;
+    evidenceSummaryThreshold: number;
+    historyFullCount: number;
+    historyAbbreviatedCount: number;
+}
+
+/**
+ * Truncate text to a line count with ellipsis
+ */
+export declare function truncateToLines(text: string, lineCount: number): string;
+
+/**
+ * Create and run validation pipeline
+ */
+export declare function validateGeneratedPlan(plan: GeneratedPlan, context: GenerationContext): AIValidationReport;
+
+export declare interface ValidationCheck {
+    name: string;
+    validate(plan: GeneratedPlan, context: GenerationContext): AIValidationResult;
+}
+
+/**
+ * Validation Pipeline
+ * Runs all validation checks and aggregates results
+ */
+export declare class ValidationPipeline {
+    private checks;
+    constructor();
+    /**
+     * Add a custom validation check
+     */
+    addCheck(check: ValidationCheck): void;
+    /**
+     * Run all validation checks
+     */
+    validate(plan: GeneratedPlan, context: GenerationContext): AIValidationReport;
+}
+
+/**
+ * Result of creating a write_plan tool
+ */
+export declare interface WritePlanToolResult {
+    /** The tool to register with the agent's ToolRegistry */
+    tool: Tool;
+    /** Promise that resolves when the agent calls write_plan */
+    planPromise: Promise<GeneratedPlan>;
+}
+
+export { }