@mainwp/control 1.0.0

package/dist/chat/chat-engine.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Chat Engine for mainwpcontrol
+ *
+ * LLM interaction loop with safety enforcement.
+ *
+ * CRITICAL INVARIANTS (from PLAN.md, CHAT_PROMPT.md):
+ * - AI proposes tool calls; ChatEngine executes via AbilitiesExecutor
+ * - AI NEVER executes directly
+ * - Destructive actions always preview first
+ * - Max tool calls per turn enforced
+ * - JSON retry logic (max 2 retries)
+ */
+import type { LLMProvider, Message } from './providers/provider.js';
+import { type SystemPromptConfig } from './system-prompt.js';
+import { type AbilitiesExecutor, type Ability, type ExecutionResult } from '../core/abilities-executor.js';
+import { type PreviewResult } from '../core/safety-controller.js';
+/**
+ * Chat response types
+ */
+export type ChatResponse = {
+    type: 'message';
+    content: string;
+} | {
+    type: 'tool_result';
+    tool: string;
+    result: ExecutionResult;
+    preview?: PreviewResult;
+} | {
+    type: 'preview';
+    preview: PreviewResult;
+    requiresApproval: boolean;
+} | {
+    type: 'error';
+    error: string;
+};
+/**
+ * Chat engine options
+ */
+export interface ChatEngineOptions {
+    /** LLM provider */
+    provider: LLMProvider;
+    /** Abilities executor */
+    executor: AbilitiesExecutor;
+    /** Maximum tool calls per turn */
+    maxToolCallsPerTurn?: number;
+    /** Maximum JSON parse retries */
+    maxParseRetries?: number;
+    /** Model to use */
+    model?: string;
+    /** Temperature */
+    temperature?: number;
+    /** System prompt config */
+    promptConfig?: Partial<SystemPromptConfig>;
+    /** Maximum messages to keep in context (excluding system prompt). undefined = no limit */
+    maxContextMessages?: number;
+    /** Maximum estimated tokens in context. Reserved for future use. */
+    maxContextTokens?: number;
+    /** Whether to use streaming responses (default: false) */
+    stream?: boolean;
+    /** Callback for streaming content chunks (called as content arrives) */
+    onStreamChunk?: (content: string) => void;
+}
+/**
+ * Chat engine class
+ *
+ * SAFETY: All execution flows through SafetyController and AbilitiesExecutor.
+ * ChatEngine never bypasses safety checks.
+ *
+ * Context window management: The engine maintains a sliding window of messages
+ * to prevent unbounded memory growth. The system prompt is always preserved,
+ * and message coherence (user-assistant pairs, tool call-result pairs) is maintained.
+ */
+export declare class ChatEngine {
+    private readonly provider;
+    private readonly executor;
+    private readonly safetyController;
+    private readonly maxToolCallsPerTurn;
+    private readonly maxParseRetries;
+    private readonly model;
+    private readonly temperature;
+    private readonly promptConfig;
+    private readonly maxContextMessages;
+    private readonly stream;
+    private readonly onStreamChunk?;
+    private messages;
+    private abilities;
+    private tools;
+    private pendingPreview;
+    private initialized;
+    constructor(options: ChatEngineOptions);
+    /**
+     * Initialize the chat session
+     */
+    initialize(): Promise<void>;
+    /**
+     * Send a user message and process the response
+     */
+    sendMessage(userMessage: string): Promise<ChatResponse[]>;
+    /**
+     * Handle response to a pending preview
+     */
+    private handlePreviewResponse;
+    /**
+     * Process LLM response with tool calling loop
+     */
+    private processLLMResponse;
+    /**
+     * Execute a tool with safety checks
+     *
+     * CRITICAL: All execution goes through SafetyController
+     */
+    private executeTool;
+    /**
+     * Execute destructive action with preview
+     */
+    private executeWithPreview;
+    /**
+     * Accumulate streaming chunks into a complete LLM response.
+     * This method consumes an AsyncGenerator<StreamChunk> and reconstructs
+     * a complete LLMResponse compatible with the existing parseResponse() logic.
+     *
+     * @param stream - The streaming generator from the provider
+     * @returns A complete LLMResponse with accumulated content and tool calls
+     */
+    private accumulateStream;
+    /**
+     * Check if there's a pending preview awaiting approval
+     */
+    hasPendingPreview(): boolean;
+    /**
+     * Get the pending preview
+     */
+    getPendingPreview(): PreviewResult | null;
+    /**
+     * Cancel pending preview
+     */
+    cancelPendingPreview(): void;
+    /**
+     * Get conversation history (for debugging)
+     */
+    getHistory(): Message[];
+    /**
+     * Clear conversation history (keep system prompt)
+     */
+    clearHistory(): void;
+    /**
+     * Get message count (excluding system prompt)
+     */
+    private getMessageCount;
+    /**
+     * Estimate tokens for a set of messages using character count as a rough proxy.
+     * Uses character_count / 4 as a heuristic (common approximation for English text).
+     *
+     * NOTE: This is a rough estimate. Actual token counts from LLMResponse.usage
+     * are more accurate when available.
+     *
+     * @param messages - Messages to estimate tokens for
+     * @returns Estimated token count
+     */
+    private estimateTokens;
+    /**
+     * Check if context truncation should occur based on message count limits.
+     * Token-based limits are reserved for future implementation.
+     *
+     * @returns true if truncation should occur, false if:
+     *   - maxContextMessages is undefined (no limit)
+     *   - maxContextMessages is 0 (explicit unlimited)
+     *   - message count is within limit
+     */
+    private shouldTruncate;
+    /**
+     * Find the index where truncation should start, respecting message boundaries.
+     * This ensures we keep complete user-assistant exchanges and tool call-result pairs.
+     *
+     * @returns Index in the messages array where truncation should start (exclusive of system prompt)
+     */
+    private findTruncationPoint;
+    /**
+     * Truncate message history using a sliding window approach.
+     * Preserves:
+     * - System prompt (always first message)
+     * - Messages since pending preview (if any)
+     * - Most recent N messages where N = maxContextMessages
+     * - Complete message exchanges (user-assistant, tool call-result pairs)
+     */
+    private truncateHistory;
+    /**
+     * Get context window statistics for monitoring.
+     *
+     * @returns Object with current message count, max limit, and estimated tokens
+     */
+    getContextStats(): {
+        messageCount: number;
+        maxMessages: number | undefined;
+        estimatedTokens: number;
+    };
+    /**
+     * Get loaded abilities
+     */
+    getAbilities(): Ability[];
+    /**
+     * Get provider info
+     */
+    getProviderInfo(): {
+        name: string;
+        model: string;
+    };
+}
+/**
+ * Create a chat engine
+ */
+export declare function createChatEngine(options: ChatEngineOptions): ChatEngine;
+//# sourceMappingURL=chat-engine.d.ts.map

package/dist/chat/chat-engine.d.ts.map

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