@zds-ai/cli 0.1.8 → 0.1.10

package/dist/agent/context-manager.d.ts

@@ -0,0 +1,70 @@
+import { ChatEntry } from "./llm-agent.js";
+import { TokenCounter } from "../utils/token-counter.js";
+import { LLMMessage } from "../grok/client.js";
+/**
+ * Dependencies required by ContextManager for managing conversation context
+ */
+export interface ContextManagerDependencies {
+    /** Chat history entries for display */
+    chatHistory: ChatEntry[];
+    /** LLM API messages array */
+    messages: LLMMessage[];
+    /** Token counter instance */
+    tokenCounter: TokenCounter;
+    /** Get current token count */
+    getCurrentTokenCount: () => number;
+    /** Get maximum context size */
+    getMaxContextSize: () => number;
+    /** Emit events */
+    emit: (event: string, data: any) => void;
+    /** Clear cache when context limit reached */
+    clearCache: () => Promise<void>;
+}
+/**
+ * Manages conversation context size, warnings, and compaction
+ *
+ * Handles:
+ * - Context usage monitoring and warnings
+ * - Automatic cache clearing at 100% capacity
+ * - Context compaction when size limits exceeded
+ * - Event emission for context changes
+ */
+export declare class ContextManager {
+    private deps;
+    /** Warning flag for 80% context usage (one-time) */
+    private contextWarningAt80;
+    /** Warning flag for 90% context usage (one-time) */
+    private contextWarningAt90;
+    constructor(deps: ContextManagerDependencies);
+    /**
+     * Emit context change event and add warnings if needed
+     * Called after message additions to monitor context usage
+     */
+    emitContextChange(): Promise<void>;
+    /**
+     * Add system warnings based on context usage percentage
+     * - 80%: Initial warning (one-time)
+     * - 90%: Urgent warning (one-time)
+     * - 95%: Critical warning (every time)
+     * - 100%: Auto-clear cache
+     */
+    private addContextWarningIfNeeded;
+    /**
+     * Calculate current context usage as percentage
+     * @returns Percentage of context capacity used (0-100+)
+     */
+    getContextUsagePercent(): number;
+    /**
+     * Compact context by keeping only the last N messages
+     * Used when context becomes too large for backend to handle
+     *
+     * @param keepLastMessages Number of recent messages to retain
+     * @returns Number of messages removed
+     */
+    compactContext(keepLastMessages?: number): number;
+    /**
+     * Reset context warning flags
+     * Called when cache is cleared to allow warnings to trigger again
+     */
+    resetContextWarnings(): void;
+}

package/dist/agent/context-manager.js

@@ -0,0 +1,138 @@
+/**
+ * Manages conversation context size, warnings, and compaction
+ *
+ * Handles:
+ * - Context usage monitoring and warnings
+ * - Automatic cache clearing at 100% capacity
+ * - Context compaction when size limits exceeded
+ * - Event emission for context changes
+ */
+export class ContextManager {
+    deps;
+    /** Warning flag for 80% context usage (one-time) */
+    contextWarningAt80 = false;
+    /** Warning flag for 90% context usage (one-time) */
+    contextWarningAt90 = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Emit context change event and add warnings if needed
+     * Called after message additions to monitor context usage
+     */
+    async emitContextChange() {
+        const percent = this.getContextUsagePercent();
+        this.deps.emit('contextChange', {
+            current: this.deps.getCurrentTokenCount(),
+            max: this.deps.getMaxContextSize(),
+            percent
+        });
+        await this.addContextWarningIfNeeded(percent);
+    }
+    /**
+     * Add system warnings based on context usage percentage
+     * - 80%: Initial warning (one-time)
+     * - 90%: Urgent warning (one-time)
+     * - 95%: Critical warning (every time)
+     * - 100%: Auto-clear cache
+     */
+    async addContextWarningIfNeeded(percent) {
+        let warning = null;
+        const roundedPercent = Math.round(percent);
+        if (percent >= 100) {
+            warning = `CONTEXT LIMIT REACHED: You are at ${roundedPercent}% context capacity!  Automatically clearing cache to prevent context overflow...`;
+            this.deps.messages.push({
+                role: 'system',
+                content: warning
+            });
+            await this.deps.clearCache();
+            return;
+        }
+        if (percent >= 95) {
+            warning = `CRITICAL CONTEXT WARNING: You are at ${roundedPercent}% context capacity!  You MUST immediately save any notes and lessons learned, then run the 'clearCache' tool to reset the conversation context.  The conversation will fail if you do not take action now.`;
+        }
+        else if (percent >= 90 && !this.contextWarningAt90) {
+            this.contextWarningAt90 = true;
+            warning = `URGENT CONTEXT WARNING: You are at ${roundedPercent}% context capacity!  Perform your final tasks or responses and prepare to be reset.`;
+        }
+        else if (percent >= 80 && !this.contextWarningAt80) {
+            this.contextWarningAt80 = true;
+            warning = `Context Warning: You are at ${roundedPercent}% context capacity!  You are approaching the limit.  Be concise and avoid lengthy outputs.`;
+        }
+        if (warning) {
+            this.deps.messages.push({
+                role: 'system',
+                content: warning
+            });
+        }
+    }
+    /**
+     * Calculate current context usage as percentage
+     * @returns Percentage of context capacity used (0-100+)
+     */
+    getContextUsagePercent() {
+        const current = this.deps.getCurrentTokenCount();
+        const max = this.deps.getMaxContextSize();
+        return (current / max) * 100;
+    }
+    /**
+     * Compact context by keeping only the last N messages
+     * Used when context becomes too large for backend to handle
+     *
+     * @param keepLastMessages Number of recent messages to retain
+     * @returns Number of messages removed
+     */
+    compactContext(keepLastMessages = 20) {
+        if (this.deps.chatHistory.length <= keepLastMessages) {
+            return 0;
+        }
+        const removedCount = this.deps.chatHistory.length - keepLastMessages;
+        const keptMessages = this.deps.chatHistory.slice(-keepLastMessages);
+        this.deps.chatHistory.length = 0;
+        this.deps.chatHistory.push(...keptMessages);
+        this.deps.messages.length = 0;
+        const compactionNote = {
+            type: 'system',
+            content: `Context compacted: removed ${removedCount} older messages, keeping last ${keepLastMessages} messages.`,
+            timestamp: new Date()
+        };
+        this.deps.chatHistory.push(compactionNote);
+        for (const entry of this.deps.chatHistory) {
+            if (entry.type === 'system') {
+                this.deps.messages.push({
+                    role: 'system',
+                    content: entry.content
+                });
+            }
+            else if (entry.type === 'user') {
+                this.deps.messages.push({
+                    role: 'user',
+                    content: entry.content
+                });
+            }
+            else if (entry.type === 'assistant') {
+                this.deps.messages.push({
+                    role: 'assistant',
+                    content: entry.content
+                });
+            }
+            else if (entry.type === 'tool_result') {
+                this.deps.messages.push({
+                    role: 'tool',
+                    tool_call_id: entry.toolResult.output || '',
+                    content: JSON.stringify(entry.toolResult)
+                });
+            }
+        }
+        return removedCount;
+    }
+    /**
+     * Reset context warning flags
+     * Called when cache is cleared to allow warnings to trigger again
+     */
+    resetContextWarnings() {
+        this.contextWarningAt80 = false;
+        this.contextWarningAt90 = false;
+    }
+}
+//# sourceMappingURL=context-manager.js.map

package/dist/agent/context-manager.js.map

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

package/dist/agent/hook-manager.d.ts

@@ -0,0 +1,194 @@
+import { LLMClient } from "../grok/client.js";
+import { TokenCounter } from "../utils/token-counter.js";
+import { ChatEntry } from "./llm-agent.js";
+/**
+ * Dependencies required by HookManager for hook execution and state management
+ */
+export interface HookManagerDependencies {
+    /** Get LLM client for API calls */
+    getLLMClient(): LLMClient;
+    /** Get token counter for model operations */
+    getTokenCounter(): TokenCounter;
+    /** API key environment variable name */
+    apiKeyEnvVar: string;
+    /** LLM messages array */
+    messages: any[];
+    /** Chat history for display */
+    chatHistory: ChatEntry[];
+    /** Temperature for API calls */
+    temperature: number;
+    /** Get current token count */
+    getCurrentTokenCount(): number;
+    /** Get maximum context size */
+    getMaxContextSize(): number;
+    /** Get current model name */
+    getCurrentModel(): string;
+    /** Emit events */
+    emit(event: string, data: any): void;
+    /** Set API key environment variable */
+    setApiKeyEnvVar(value: string): void;
+    /** Set token counter */
+    setTokenCounter(counter: TokenCounter): void;
+    /** Set LLM client */
+    setLLMClient(client: LLMClient): void;
+    /** Set persona values */
+    setPersona(persona: string, color: string): void;
+    /** Set mood values */
+    setMood(mood: string, color: string): void;
+    /** Set active task values */
+    setActiveTask(task: string, action: string, color: string): void;
+    /** Execute a tool by name with parameters (for CALL commands) */
+    executeToolByName?(toolName: string, parameters: Record<string, any>): Promise<{
+        success: boolean;
+        output?: string;
+        error?: string;
+        hookCommands?: any[];
+    }>;
+}
+/**
+ * Manages hook execution for persona, mood, and task operations
+ *
+ * Handles:
+ * - Persona/mood/task hook execution with approval workflows
+ * - Backend and model switching with validation
+ * - Hook command processing and environment variable management
+ * - API testing for backend/model changes
+ * - System message generation for state changes
+ */
+export declare class HookManager {
+    private deps;
+    constructor(deps: HookManagerDependencies);
+    /**
+     * Set agent persona with optional hook execution
+     * Executes persona hook if configured and processes backend/model changes
+     *
+     * @param persona New persona name
+     * @param color Optional display color
+     * @returns Success status and error message if failed
+     */
+    setPersona(persona: string, color?: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Set agent mood with optional hook execution
+     * Executes mood hook if configured and adds system message to chat
+     *
+     * @param mood New mood name
+     * @param color Optional display color
+     * @returns Success status and error message if failed
+     */
+    setMood(mood: string, color?: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Start a new active task with approval hook
+     * Prevents starting if another task is already active
+     *
+     * @param activeTask Task name
+     * @param action Task action/status
+     * @param color Optional display color
+     * @returns Success status and error message if failed
+     */
+    startActiveTask(activeTask: string, action: string, color?: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Transition active task status with approval hook
+     * Requires an active task to be running
+     *
+     * @param action New task action/status
+     * @param color Optional display color
+     * @returns Success status and error message if failed
+     */
+    transitionActiveTaskStatus(action: string, color?: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Stop active task with approval hook and minimum delay
+     * Enforces 3-second minimum delay for task completion
+     *
+     * @param reason Reason for stopping task
+     * @param documentationFile Documentation file path
+     * @param color Optional display color
+     * @returns Success status and error message if failed
+     */
+    stopActiveTask(reason: string, documentationFile: string, color?: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Process hook result commands and apply environment changes
+     * Handles backend/model changes, environment variables, and system messages
+     *
+     * @param hookResult Hook execution result with commands
+     * @param envKey Optional environment key to extract transformed value
+     * @returns Success status and transformed value if applicable
+     */
+    processHookResult(hookResult: {
+        commands?: any[];
+    }, envKey?: string): Promise<{
+        success: boolean;
+        transformedValue?: string;
+    }>;
+    /**
+     * Process hook commands with backend/model testing
+     * Tests API connectivity before applying changes
+     *
+     * @param commands Processed hook commands
+     * @returns Success status of command processing
+     */
+    private processHookCommands;
+    /**
+     * Render system message with current variable state
+     * Updates messages[0] with fresh system prompt from variables
+     */
+    private renderSystemMessage;
+    /**
+     * Test model change by making API call
+     * Validates model compatibility before switching
+     *
+     * @param newModel Model name to test
+     * @returns Success status and error message if failed
+     */
+    private testModel;
+    /**
+     * Test backend and model change by making API call
+     * Validates backend connectivity and model compatibility
+     *
+     * @param backend Backend name
+     * @param baseUrl API base URL
+     * @param apiKeyEnvVar Environment variable for API key
+     * @param model Optional model name
+     * @returns Success status and error message if failed
+     */
+    private testBackendModelChange;
+    /**
+     * Strip in-progress tool calls from messages for API testing
+     * Removes incomplete tool call sequences to avoid API errors
+     *
+     * @param messages Message array to clean
+     * @returns Cleaned message array without incomplete tool calls
+     */
+    private stripInProgressToolCalls;
+    /**
+     * Execute CALL commands asynchronously with recursion depth and duplicate tracking
+     * Fire-and-forget execution that processes hooks from called tools
+     *
+     * @param calls Array of CALL command strings
+     * @param context Call context for tracking recursion and duplicates
+     */
+    private executeCalls;
+    /**
+     * Execute a single CALL asynchronously with hook processing
+     * Runs tool hooks which may generate more CALL commands
+     *
+     * @param toolName Tool to execute
+     * @param parameters Tool parameters
+     * @param context Call context for tracking recursion
+     */
+    private executeCallAsync;
+}