byterover-cli 0.4.0 → 1.0.0

package/dist/infra/cipher/agent/agent-state-manager.js

@@ -0,0 +1,275 @@
+/**
+ * Unified agent state manager combining DextoAgent config patterns with execution state tracking.
+ *
+ * Manages two concerns:
+ *
+ * 1. Configuration State (DextoAgent pattern):
+ *    - baselineConfig: Original validated config, never mutated
+ *    - runtimeConfig: Current active config, can be mutated
+ *    - sessionOverrides: Per-session config overrides
+ *
+ * 2. Execution State (runtime tracking):
+ *    - currentIteration: Turn counter
+ *    - executionState: idle | executing | complete | error | aborted | tool_calling
+ *    - terminationReason: Why execution ended
+ *    - timing: startTime, endTime, durationMs
+ *    - toolCallsExecuted: Tool call counter
+ *    - executionHistory: Legacy history records
+ */
+export class AgentStateManager {
+    agentEventBus;
+    baselineConfig;
+    currentIteration = 0;
+    durationMs;
+    endTime;
+    executionHistory = [];
+    executionState = 'idle';
+    runtimeConfig;
+    sessionOverrides = new Map();
+    startTime;
+    terminationReason;
+    toolCallsExecuted = 0;
+    constructor(staticConfig, agentEventBus) {
+        this.agentEventBus = agentEventBus;
+        // Deep clone to prevent external mutations
+        this.baselineConfig = structuredClone(staticConfig);
+        this.runtimeConfig = structuredClone(staticConfig);
+    }
+    /**
+     * Add an execution record to history (legacy method).
+     * @param record - Execution record to add
+     */
+    addExecutionRecord(record) {
+        this.executionHistory.push(record);
+    }
+    /**
+     * Clear session-specific overrides.
+     */
+    clearSessionOverride(sessionId) {
+        const hadOverride = this.sessionOverrides.has(sessionId);
+        this.sessionOverrides.delete(sessionId);
+        if (hadOverride) {
+            this.agentEventBus.emit('cipher:stateReset', { sessionId });
+        }
+    }
+    /**
+     * Mark execution as complete with reason.
+     * @param reason - Why execution terminated
+     */
+    complete(reason) {
+        this.executionState = 'complete';
+        this.terminationReason = reason;
+        this.endTime = new Date();
+        if (this.startTime) {
+            this.durationMs = this.endTime.getTime() - this.startTime.getTime();
+        }
+    }
+    /**
+     * Export current runtime state as a config object.
+     */
+    exportAsConfig() {
+        return structuredClone(this.runtimeConfig);
+    }
+    /**
+     * Mark execution as errored.
+     * @param reason - Error termination reason
+     */
+    fail(reason) {
+        this.executionState = 'error';
+        this.terminationReason = reason;
+        this.endTime = new Date();
+        if (this.startTime) {
+            this.durationMs = this.endTime.getTime() - this.startTime.getTime();
+        }
+    }
+    /**
+     * Get the original baseline configuration.
+     */
+    getBaselineConfig() {
+        return structuredClone(this.baselineConfig);
+    }
+    /**
+     * Get the current execution state.
+     * @returns Current agent state with all execution fields
+     */
+    getExecutionState() {
+        return {
+            currentIteration: this.currentIteration,
+            durationMs: this.durationMs,
+            endTime: this.endTime,
+            executionHistory: [...this.executionHistory],
+            executionState: this.executionState,
+            startTime: this.startTime,
+            terminationReason: this.terminationReason,
+            toolCallsExecuted: this.toolCallsExecuted,
+        };
+    }
+    /**
+     * Get effective LLM config for a session.
+     */
+    getLLMConfig(sessionId) {
+        return this.getRuntimeConfig(sessionId).llm;
+    }
+    /**
+     * Get the current model identifier.
+     */
+    getModel(sessionId) {
+        return this.getRuntimeConfig(sessionId).model;
+    }
+    /**
+     * Get runtime configuration for a session (includes session overrides if sessionId provided).
+     */
+    getRuntimeConfig(sessionId) {
+        if (!sessionId) {
+            return structuredClone(this.runtimeConfig);
+        }
+        const override = this.sessionOverrides.get(sessionId);
+        if (!override) {
+            return structuredClone(this.runtimeConfig);
+        }
+        // Merge session overrides into runtime config
+        return {
+            ...this.runtimeConfig,
+            llm: { ...this.runtimeConfig.llm, ...override.llm },
+        };
+    }
+    /**
+     * Get all session IDs that have overrides.
+     */
+    getSessionsWithOverrides() {
+        return [...this.sessionOverrides.keys()];
+    }
+    /**
+     * Check if a session has overrides.
+     */
+    hasSessionOverride(sessionId) {
+        return this.sessionOverrides.has(sessionId);
+    }
+    /**
+     * Increment the iteration counter.
+     * @returns The new iteration count
+     */
+    incrementIteration() {
+        this.currentIteration++;
+        return this.currentIteration;
+    }
+    /**
+     * Increment the tool calls counter.
+     * @returns The new tool calls count
+     */
+    incrementToolCalls() {
+        this.toolCallsExecuted++;
+        return this.toolCallsExecuted;
+    }
+    /**
+     * Reset all state to initial values.
+     * Resets both execution state and configuration state.
+     */
+    reset() {
+        // Reset execution state
+        this.currentIteration = 0;
+        this.durationMs = undefined;
+        this.endTime = undefined;
+        this.executionHistory = [];
+        this.executionState = 'idle';
+        this.startTime = undefined;
+        this.terminationReason = undefined;
+        this.toolCallsExecuted = 0;
+    }
+    /**
+     * Reset runtime configuration to baseline.
+     * Also clears all session overrides.
+     */
+    resetToBaseline() {
+        this.runtimeConfig = structuredClone(this.baselineConfig);
+        this.sessionOverrides.clear();
+        this.agentEventBus.emit('cipher:stateReset', {});
+    }
+    /**
+     * Set the current execution state.
+     * @param state - New execution state
+     */
+    setExecutionState(state) {
+        this.executionState = state;
+    }
+    /**
+     * Start execution tracking.
+     * Sets startTime and transitions to executing state.
+     */
+    startExecution() {
+        this.startTime = new Date();
+        this.executionState = 'executing';
+    }
+    /**
+     * Update LLM configuration globally or for a specific session.
+     *
+     * @param updates - Partial LLM configuration updates
+     * @param sessionId - Optional session ID for session-specific override
+     */
+    updateLLM(updates, sessionId) {
+        const oldValue = sessionId ? this.getRuntimeConfig(sessionId).llm : this.runtimeConfig.llm;
+        if (sessionId) {
+            // Session-specific override
+            this.setSessionOverride(sessionId, { llm: updates });
+        }
+        else {
+            // Global update
+            this.runtimeConfig = {
+                ...this.runtimeConfig,
+                llm: { ...this.runtimeConfig.llm, ...updates },
+            };
+        }
+        const newValue = sessionId ? this.getRuntimeConfig(sessionId).llm : this.runtimeConfig.llm;
+        this.agentEventBus.emit('cipher:stateChanged', {
+            field: 'llm',
+            newValue,
+            oldValue,
+            sessionId,
+        });
+    }
+    /**
+     * Update the model globally or for a specific session.
+     */
+    updateModel(model, sessionId) {
+        const oldValue = this.getModel(sessionId);
+        if (sessionId) {
+            // For session-specific model change, we need to track it differently
+            // since model is at the root level, not in llm config
+            // For now, emit state change event
+            this.agentEventBus.emit('cipher:stateChanged', {
+                field: 'model',
+                newValue: model,
+                oldValue,
+                sessionId,
+            });
+        }
+        else {
+            this.runtimeConfig = {
+                ...this.runtimeConfig,
+                model,
+            };
+            this.agentEventBus.emit('cipher:stateChanged', {
+                field: 'model',
+                newValue: model,
+                oldValue,
+            });
+        }
+    }
+    /**
+     * Set a session-specific override.
+     */
+    setSessionOverride(sessionId, override) {
+        const existing = this.sessionOverrides.get(sessionId) ?? {};
+        // Merge LLM overrides
+        const mergedOverride = {
+            ...existing,
+            llm: { ...existing.llm, ...override.llm },
+        };
+        this.sessionOverrides.set(sessionId, mergedOverride);
+        this.agentEventBus.emit('cipher:stateChanged', {
+            field: 'sessionOverride',
+            newValue: structuredClone(mergedOverride),
+            sessionId,
+        });
+    }
+}

package/dist/infra/cipher/agent/base-agent.d.ts

@@ -0,0 +1,118 @@
+import type { CipherAgentServices } from '../../../core/interfaces/cipher/cipher-services.js';
+import type { AgentEventBus } from '../events/event-emitter.js';
+import { type LLMUpdates, type ValidatedAgentConfig, type ValidatedLLMConfig } from './agent-schemas.js';
+import { AgentStateManager } from './agent-state-manager.js';
+/**
+ * Abstract base agent class encapsulating DextoAgent patterns.
+ *
+ * Provides:
+ * - Two-phase initialization (constructor + start)
+ * - Lifecycle management (start, stop, restart)
+ * - State management with session overrides
+ * - Typed error handling
+ * - Configuration validation
+ *
+ * Subclasses must implement:
+ * - initializeServices(): Create agent-specific services
+ * - cleanupServices(): Cleanup on stop
+ */
+export declare abstract class BaseAgent {
+    protected _isStarted: boolean;
+    protected _isStopped: boolean;
+    readonly config: ValidatedAgentConfig;
+    protected services?: CipherAgentServices;
+    protected stateManager?: AgentStateManager;
+    /**
+     * Create a new agent instance.
+     * Does NOT initialize services - call start() for async initialization.
+     *
+     * @param config - Agent configuration (will be validated with Zod)
+     * @throws AgentError if configuration validation fails
+     */
+    constructor(config: unknown);
+    /**
+     * Cleanup agent-specific services.
+     * Called during stop().
+     */
+    protected abstract cleanupServices(): Promise<void>;
+    /**
+     * Clear session-specific configuration overrides.
+     */
+    clearSessionConfig(sessionId: string): void;
+    /**
+     * Ensure the agent is started before operations.
+     * @throws AgentError if not started or stopped
+     */
+    protected ensureStarted(): void;
+    /**
+     * Get the agent event bus (for subscribing to events).
+     */
+    getAgentEventBus(): AgentEventBus;
+    /**
+     * Get the baseline configuration (original config, never modified).
+     */
+    getBaselineConfig(): Readonly<ValidatedAgentConfig>;
+    /**
+     * Get effective configuration for a session.
+     * Includes session-specific overrides if sessionId is provided.
+     */
+    getEffectiveConfig(sessionId?: string): Readonly<ValidatedAgentConfig>;
+    /**
+     * Get current LLM configuration.
+     */
+    getLLMConfig(sessionId?: string): Readonly<ValidatedLLMConfig>;
+    /**
+     * Get services (guaranteed to be defined after start).
+     */
+    protected getServices(): CipherAgentServices;
+    /**
+     * Get the state manager (guaranteed to be defined after start).
+     */
+    protected getStateManager(): AgentStateManager;
+    /**
+     * Initialize agent-specific services.
+     * Called during start().
+     */
+    protected abstract initializeServices(): Promise<CipherAgentServices>;
+    /**
+     * Check if the agent is started.
+     */
+    isStarted(): boolean;
+    /**
+     * Check if the agent is stopped.
+     */
+    isStopped(): boolean;
+    /**
+     * Reset configuration to baseline.
+     */
+    resetConfig(): void;
+    /**
+     * Restart the agent (stop + start).
+     */
+    restart(): Promise<void>;
+    /**
+     * Start the agent and initialize all services.
+     * Must be called before using other methods.
+     *
+     * @throws AgentError if already started or initialization fails
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the agent and cleanup all services.
+     * After stopping, the agent can be restarted with start().
+     */
+    stop(): Promise<void>;
+    /**
+     * Update LLM configuration at runtime.
+     *
+     * @param updates - Partial LLM configuration updates
+     * @param sessionId - Optional session ID for session-specific override
+     * @returns Updated LLM configuration
+     */
+    updateLLM(updates: LLMUpdates, sessionId?: string): ValidatedLLMConfig;
+    /**
+     * Validate that all required services are present.
+     * Can be overridden by subclasses to add custom validation.
+     */
+    protected validateServices(services: CipherAgentServices): void;
+}

package/dist/infra/cipher/agent/base-agent.js

@@ -0,0 +1,240 @@
+import { AgentError } from './agent-error.js';
+import { AgentConfigSchema, LLMUpdatesSchema } from './agent-schemas.js';
+import { AgentStateManager } from './agent-state-manager.js';
+/**
+ * Abstract base agent class encapsulating DextoAgent patterns.
+ *
+ * Provides:
+ * - Two-phase initialization (constructor + start)
+ * - Lifecycle management (start, stop, restart)
+ * - State management with session overrides
+ * - Typed error handling
+ * - Configuration validation
+ *
+ * Subclasses must implement:
+ * - initializeServices(): Create agent-specific services
+ * - cleanupServices(): Cleanup on stop
+ */
+export class BaseAgent {
+    // === Lifecycle State ===
+    _isStarted = false;
+    _isStopped = false;
+    // === Configuration ===
+    config;
+    // === Services (initialized in start()) ===
+    services;
+    stateManager;
+    /**
+     * Create a new agent instance.
+     * Does NOT initialize services - call start() for async initialization.
+     *
+     * @param config - Agent configuration (will be validated with Zod)
+     * @throws AgentError if configuration validation fails
+     */
+    constructor(config) {
+        // Validate and transform config using Zod schema
+        const parseResult = AgentConfigSchema.safeParse(config);
+        if (!parseResult.success) {
+            throw AgentError.invalidConfig('Configuration validation failed', parseResult.error.format());
+        }
+        this.config = parseResult.data;
+    }
+    /**
+     * Clear session-specific configuration overrides.
+     */
+    clearSessionConfig(sessionId) {
+        this.ensureStarted();
+        this.getStateManager().clearSessionOverride(sessionId);
+    }
+    /**
+     * Ensure the agent is started before operations.
+     * @throws AgentError if not started or stopped
+     */
+    ensureStarted() {
+        if (this._isStopped && !this._isStarted) {
+            throw AgentError.stopped();
+        }
+        if (!this._isStarted) {
+            throw AgentError.notStarted();
+        }
+    }
+    /**
+     * Get the agent event bus (for subscribing to events).
+     */
+    getAgentEventBus() {
+        this.ensureStarted();
+        return this.getServices().agentEventBus;
+    }
+    /**
+     * Get the baseline configuration (original config, never modified).
+     */
+    getBaselineConfig() {
+        this.ensureStarted();
+        return this.getStateManager().getBaselineConfig();
+    }
+    /**
+     * Get effective configuration for a session.
+     * Includes session-specific overrides if sessionId is provided.
+     */
+    getEffectiveConfig(sessionId) {
+        this.ensureStarted();
+        return this.getStateManager().getRuntimeConfig(sessionId);
+    }
+    /**
+     * Get current LLM configuration.
+     */
+    getLLMConfig(sessionId) {
+        this.ensureStarted();
+        return this.getStateManager().getLLMConfig(sessionId);
+    }
+    /**
+     * Get services (guaranteed to be defined after start).
+     */
+    getServices() {
+        if (!this.services) {
+            throw AgentError.serviceNotInitialized('CipherAgentServices');
+        }
+        return this.services;
+    }
+    /**
+     * Get the state manager (guaranteed to be defined after start).
+     */
+    getStateManager() {
+        if (!this.stateManager) {
+            throw AgentError.serviceNotInitialized('AgentStateManager');
+        }
+        return this.stateManager;
+    }
+    /**
+     * Check if the agent is started.
+     */
+    isStarted() {
+        return this._isStarted;
+    }
+    /**
+     * Check if the agent is stopped.
+     */
+    isStopped() {
+        return this._isStopped;
+    }
+    /**
+     * Reset configuration to baseline.
+     */
+    resetConfig() {
+        this.ensureStarted();
+        this.getStateManager().resetToBaseline();
+    }
+    /**
+     * Restart the agent (stop + start).
+     */
+    async restart() {
+        await this.stop();
+        await this.start();
+    }
+    /**
+     * Start the agent and initialize all services.
+     * Must be called before using other methods.
+     *
+     * @throws AgentError if already started or initialization fails
+     */
+    async start() {
+        if (this._isStarted) {
+            throw AgentError.alreadyStarted();
+        }
+        if (this._isStopped) {
+            // Reset stopped flag to allow restart
+            this._isStopped = false;
+        }
+        try {
+            // Initialize services (implemented by subclass)
+            const services = await this.initializeServices();
+            // Validate required services
+            this.validateServices(services);
+            // Assign services
+            this.services = services;
+            // Create state manager with the event bus from services
+            this.stateManager = new AgentStateManager(this.config, services.agentEventBus);
+            this._isStarted = true;
+        }
+        catch (error) {
+            if (error instanceof AgentError) {
+                throw error;
+            }
+            throw AgentError.initializationFailed(error instanceof Error ? error.message : String(error), error);
+        }
+    }
+    /**
+     * Stop the agent and cleanup all services.
+     * After stopping, the agent can be restarted with start().
+     */
+    async stop() {
+        if (this._isStopped) {
+            return; // Already stopped, no-op
+        }
+        if (!this._isStarted) {
+            // Not started, just mark as stopped
+            this._isStopped = true;
+            return;
+        }
+        try {
+            // Cleanup services (implemented by subclass)
+            await this.cleanupServices();
+            // Clear state
+            this.services = undefined;
+            this.stateManager = undefined;
+            this._isStopped = true;
+            this._isStarted = false;
+        }
+        catch (error) {
+            // Still mark as stopped even if cleanup fails
+            this._isStopped = true;
+            this._isStarted = false;
+            throw AgentError.executionFailed(`Failed to stop agent: ${error instanceof Error ? error.message : String(error)}`, error);
+        }
+    }
+    /**
+     * Update LLM configuration at runtime.
+     *
+     * @param updates - Partial LLM configuration updates
+     * @param sessionId - Optional session ID for session-specific override
+     * @returns Updated LLM configuration
+     */
+    updateLLM(updates, sessionId) {
+        this.ensureStarted();
+        // Validate updates
+        const parseResult = LLMUpdatesSchema.safeParse(updates);
+        if (!parseResult.success) {
+            throw AgentError.invalidConfig('Invalid LLM updates', parseResult.error.format());
+        }
+        // Get current config and merge
+        const currentConfig = this.getStateManager().getLLMConfig(sessionId);
+        const mergedUpdates = { ...currentConfig, ...parseResult.data };
+        // Update state
+        this.getStateManager().updateLLM(mergedUpdates, sessionId);
+        return this.getStateManager().getLLMConfig(sessionId);
+    }
+    /**
+     * Validate that all required services are present.
+     * Can be overridden by subclasses to add custom validation.
+     */
+    validateServices(services) {
+        const requiredServices = [
+            'agentEventBus',
+            'toolManager',
+            'systemPromptManager',
+            'fileSystemService',
+            'processService',
+            'historyStorage',
+            'memoryManager',
+            'blobStorage',
+            'policyEngine',
+            'toolProvider',
+            'toolScheduler',
+        ];
+        for (const serviceName of requiredServices) {
+            if (!services[serviceName]) {
+                throw AgentError.missingRequiredService(serviceName);
+            }
+        }
+    }
+}