crewly 1.0.7 → 1.0.10

package/dist/backend/backend/src/services/agent/context-window-monitor.service.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Context Window Monitor Service
+ *
+ * Monitors PTY session output for context window usage percentages and triggers
+ * proactive warnings and runtime-native compaction when thresholds are exceeded.
+ *
+ * When an agent's session reports context usage (e.g., "85% context"),
+ * this service detects the percentage, evaluates it against configured thresholds,
+ * and takes action:
+ * - Yellow (70%): Publishes a warning event
+ * - Red (85%): Publishes a warning + triggers runtime compact (/compact or /compress)
+ * - Critical (95%): Retries compact with cooldown; auto-recovery disabled by default
+ *
+ * Strategy: prefer runtime-native compact/compress commands which preserve session
+ * state over session kill + restart which loses all context. Auto-recovery is
+ * available as a last resort via AUTO_RECOVERY_ENABLED constant.
+ *
+ * Follows the PTY subscription pattern from RuntimeExitMonitorService and the
+ * lifecycle/restart pattern from AgentHeartbeatMonitorService.
+ *
+ * @module services/agent/context-window-monitor
+ */
+import { StorageService } from '../core/storage.service.js';
+import { TaskTrackingService } from '../project/task-tracking.service.js';
+import type { RuntimeType } from '../../constants.js';
+import type { AgentRegistrationService } from './agent-registration.service.js';
+import type { ISessionBackend } from '../session/session-backend.interface.js';
+import type { EventBusService } from '../event-bus/event-bus.service.js';
+/**
+ * Context usage severity level.
+ */
+export type ContextLevel = 'normal' | 'yellow' | 'red' | 'critical';
+/**
+ * Per-session context window monitoring state.
+ */
+export interface ContextWindowState {
+    /** PTY session name */
+    sessionName: string;
+    /** Team member ID */
+    memberId: string;
+    /** Team ID */
+    teamId: string;
+    /** Agent role */
+    role: string;
+    /** Runtime type for this session (determines compact command) */
+    runtimeType: RuntimeType;
+    /** Last detected context usage percentage (0-100) */
+    contextPercent: number;
+    /** Current severity level */
+    level: ContextLevel;
+    /** Timestamp of last context % detection */
+    lastDetectedAt: number;
+    /** Whether auto-recovery has been triggered for this session */
+    recoveryTriggered: boolean;
+    /** Total recovery count for this session */
+    recoveryCount: number;
+    /** Timestamps of recent recoveries for cooldown tracking */
+    recoveryTimestamps: number[];
+    /** Number of compact attempts for current high-usage episode */
+    compactAttempts: number;
+    /** Whether a compact is currently in progress */
+    compactInProgress: boolean;
+    /** Timestamp of the last compact attempt */
+    lastCompactAt: number;
+}
+/**
+ * Monitors agent PTY sessions for context window usage and triggers
+ * threshold-based warnings and auto-recovery.
+ *
+ * @example
+ * ```typescript
+ * const monitor = ContextWindowMonitorService.getInstance();
+ * monitor.setDependencies(backend, regService, storageService, taskService, eventBus);
+ * monitor.start();
+ * monitor.startSessionMonitoring('agent-dev', 'member-1', 'team-1', 'developer');
+ * ```
+ */
+export declare class ContextWindowMonitorService {
+    private static instance;
+    private logger;
+    /** Per-session context window state */
+    private contextStates;
+    /** Per-session PTY data subscriptions + rolling buffers */
+    private sessionSubscriptions;
+    /** Periodic check interval timer */
+    private checkTimer;
+    /** Dependencies (injected via setDependencies) */
+    private sessionBackend;
+    private agentRegistrationService;
+    private storageService;
+    private taskTrackingService;
+    private eventBusService;
+    private constructor();
+    /**
+     * Get the singleton instance.
+     *
+     * @returns The ContextWindowMonitorService singleton
+     */
+    static getInstance(): ContextWindowMonitorService;
+    /**
+     * Reset the singleton (for testing).
+     */
+    static resetInstance(): void;
+    /**
+     * Inject required dependencies.
+     *
+     * @param sessionBackend - Session backend for PTY access
+     * @param agentRegistrationService - For recreating agent sessions on recovery
+     * @param storageService - For querying agent status
+     * @param taskTrackingService - For querying in-progress tasks for re-delivery
+     * @param eventBusService - For publishing context warning/critical events
+     */
+    setDependencies(sessionBackend: ISessionBackend, agentRegistrationService: AgentRegistrationService, storageService: StorageService, taskTrackingService: TaskTrackingService, eventBusService: EventBusService): void;
+    /**
+     * Start the periodic check loop for stale detection and cleanup.
+     */
+    start(): void;
+    /**
+     * Stop the periodic check loop.
+     */
+    stop(): void;
+    /**
+     * Check if the monitor is currently running.
+     *
+     * @returns True if the periodic check loop is active
+     */
+    isRunning(): boolean;
+    /**
+     * Start monitoring a specific session for context window usage.
+     *
+     * Subscribes to the session's PTY onData events and parses output
+     * for context usage percentages.
+     *
+     * @param sessionName - PTY session name
+     * @param memberId - Team member ID
+     * @param teamId - Team ID
+     * @param role - Agent role
+     * @param runtimeType - Runtime type (defaults to 'claude-code')
+     */
+    startSessionMonitoring(sessionName: string, memberId: string, teamId: string, role: string, runtimeType?: RuntimeType): void;
+    /**
+     * Stop monitoring a specific session.
+     *
+     * @param sessionName - PTY session name
+     */
+    stopSessionMonitoring(sessionName: string): void;
+    /**
+     * Get the context window state for a specific session.
+     *
+     * @param sessionName - PTY session name
+     * @returns The context window state or undefined if not monitored
+     */
+    getContextState(sessionName: string): ContextWindowState | undefined;
+    /**
+     * Get all monitored context window states.
+     *
+     * @returns Map of session name to context window state
+     */
+    getAllContextStates(): Map<string, ContextWindowState>;
+    /**
+     * Handle incoming PTY data for a monitored session.
+     * Strips ANSI codes, appends to rolling buffer, and checks for context % patterns.
+     *
+     * @param sessionName - PTY session name
+     * @param data - Raw PTY output data
+     */
+    private handleData;
+    /**
+     * Extract context usage percentage from terminal output.
+     *
+     * @param text - Cleaned terminal output text
+     * @returns The extracted percentage (0-100) or null if not found
+     */
+    private extractContextPercent;
+    /**
+     * Update context usage for a session and evaluate thresholds.
+     *
+     * @param sessionName - PTY session name
+     * @param percent - New context usage percentage
+     */
+    updateContextUsage(sessionName: string, percent: number): void;
+    /**
+     * Evaluate threshold transitions and take appropriate actions.
+     *
+     * Strategy (compact-first):
+     * 1. Yellow (70%): Publish warning event only
+     * 2. Red (85%): Publish warning + trigger runtime-native compact/compress
+     * 3. Critical (95%): Retry compact; periodic checks will continue retrying
+     *    with cooldown. Auto-recovery (kill + restart) only if enabled.
+     *
+     * @param state - Current context window state
+     * @param previousLevel - The level before this update
+     */
+    private evaluateThresholds;
+    /**
+     * Publish a context event via the event bus.
+     *
+     * @param state - Context window state
+     * @param eventType - Event type to publish
+     */
+    private publishContextEvent;
+    /**
+     * Broadcast context window status to frontend via WebSocket.
+     *
+     * @param state - Context window state to broadcast
+     */
+    private broadcastContextWarning;
+    /**
+     * Trigger context compaction by sending the runtime's native compact command.
+     *
+     * Writes the appropriate slash command (e.g., `/compact` for Claude Code,
+     * `/compress` for Gemini CLI) to the PTY session stdin. The runtime handles
+     * the actual compression — typically via LLM-based summarization.
+     *
+     * @param state - Context window state for the session to compact
+     */
+    private triggerCompact;
+    /**
+     * Trigger auto-recovery for a session at critical context usage.
+     *
+     * Mirrors the restart pattern from AgentHeartbeatMonitorService:
+     * 1. Check cooldown
+     * 2. Save Claude session ID
+     * 3. Stop exit monitoring
+     * 4. Kill PTY session
+     * 5. Clear activity tracker
+     * 6. Pre-set session ID for resume
+     * 7. Recreate agent session
+     * 8. Broadcast status
+     * 9. Re-deliver tasks
+     *
+     * @param state - Context window state for the session to recover
+     */
+    private triggerAutoRecovery;
+    /**
+     * Re-deliver in-progress tasks to a recovered agent.
+     *
+     * @param state - Context window state for the recovered session
+     */
+    private redeliverTasks;
+    /**
+     * Periodic check for stale states, cleanup, compact retries, and proactive compaction.
+     *
+     * For stale sessions (no context % detected recently), resets to normal.
+     * For critical sessions with exhausted compacts, retries compact after
+     * COMPACT_RETRY_COOLDOWN_MS has elapsed since the last attempt.
+     * For all monitored sessions, checks cumulative output bytes and triggers
+     * proactive compact when threshold is exceeded.
+     */
+    private performCheck;
+    /** Timestamp of last proactive compact per session for cooldown tracking */
+    private proactiveCompactLastTriggered;
+    /**
+     * Check all monitored sessions for cumulative output volume and trigger
+     * proactive compact when the threshold is exceeded.
+     *
+     * @param now - Current timestamp in epoch ms
+     */
+    private checkProactiveCompact;
+    /**
+     * Destroy all PTY subscriptions. Used during resetInstance.
+     */
+    private destroyAllSubscriptions;
+}
+//# sourceMappingURL=context-window-monitor.service.d.ts.map

package/dist/backend/backend/src/services/agent/context-window-monitor.service.d.ts.map

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