crewly 1.5.18 → 1.5.20

package/dist/backend/backend/src/services/v3/escalation.service.js

@@ -0,0 +1,371 @@
+/**
+ * EscalationService — Periodic evaluation of MissionPolicy escalation rules.
+ *
+ * Periodically scans all active Missions, builds an EscalationContext from
+ * current runtime data (cost, time elapsed, failure count), and evaluates
+ * each Mission's escalationRules via PolicyEnforcementService. When a rule
+ * triggers, the specified action is executed:
+ *
+ * - **notify**: Sends a notification to the escalation target (user/orchestrator/team_lead)
+ * - **pause**: Pauses the Mission and its associated WorkItems
+ * - **block**: Blocks further Mission execution until manual review
+ *
+ * Integration with TriggerEngine:
+ * On startup, registers a cron-based Trigger that periodically invokes
+ * the escalation evaluation loop. This leverages TriggerEngine's lifecycle
+ * management (fire counting, idle tracking, persistence).
+ *
+ * @module services/v3/escalation.service
+ */
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import { LoggerService } from '../core/logger.service.js';
+import { PolicyEnforcementService } from '../policy/policy-enforcement.service.js';
+import { TaskPoolService } from '../task-pool/task-pool.service.js';
+import { TriggerEngine } from './trigger-engine.service.js';
+import { ensureDir, safeReadJson } from '../../utils/file-io.utils.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default cron expression for escalation checks: every 5 minutes. */
+const DEFAULT_ESCALATION_CRON = '*/5 * * * *';
+/** Directory name for missions under .crewly. */
+const MISSIONS_DIR = 'missions';
+/** Maximum escalation results to log per evaluation cycle. */
+const MAX_LOG_RESULTS = 20;
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+/**
+ * EscalationService periodically evaluates MissionPolicy escalation rules
+ * and executes the required actions when thresholds are exceeded.
+ *
+ * @example
+ * ```typescript
+ * const service = new EscalationService('/path/to/project');
+ * service.setActionHandler(async (mission, rule, action) => {
+ *   if (action === 'notify') await sendSlackNotification(mission, rule);
+ *   if (action === 'pause') await pauseMission(mission.id);
+ * });
+ * await service.start();
+ * ```
+ */
+export class EscalationService {
+    logger;
+    projectPath;
+    missionsDir;
+    policyService;
+    actionHandler = null;
+    triggerId = null;
+    started = false;
+    /**
+     * Creates a new EscalationService.
+     *
+     * @param projectPath - Absolute path to the project root
+     * @param policyService - Optional PolicyEnforcementService instance (for DI/testing)
+     */
+    constructor(projectPath, policyService) {
+        this.logger = LoggerService.getInstance().createComponentLogger('EscalationService');
+        this.projectPath = projectPath;
+        this.missionsDir = path.join(projectPath, '.crewly', MISSIONS_DIR);
+        this.policyService = policyService ?? new PolicyEnforcementService();
+    }
+    /**
+     * Registers a handler for escalation actions.
+     * The handler is called whenever an escalation rule triggers.
+     *
+     * @param handler - Callback for executing escalation actions
+     */
+    setActionHandler(handler) {
+        this.actionHandler = handler;
+    }
+    /**
+     * Starts the escalation service by registering a periodic trigger
+     * with the TriggerEngine.
+     *
+     * @param cronExpression - Cron expression for evaluation frequency (default: every 5 min)
+     */
+    async start(cronExpression) {
+        if (this.started) {
+            this.logger.warn('EscalationService already started');
+            return;
+        }
+        const cron = cronExpression ?? DEFAULT_ESCALATION_CRON;
+        try {
+            const triggerEngine = TriggerEngine.getInstance(this.projectPath);
+            const trigger = await triggerEngine.create({
+                type: 'time',
+                config: {
+                    type: 'time',
+                    cronExpression: cron,
+                    timezone: 'UTC',
+                },
+                action: {
+                    runReconciler: true, // Re-used as a "run escalation" signal
+                },
+                createdBy: 'system',
+                maxIdleFires: 50, // Allow many idle fires since not all cycles trigger
+            });
+            this.triggerId = trigger.id;
+            // Register a custom action handler on the TriggerEngine that intercepts
+            // our trigger and runs the evaluation loop.
+            const originalHandler = triggerEngine['actionHandler'];
+            triggerEngine.setActionHandler(async (t, action) => {
+                if (t.id === this.triggerId) {
+                    await this.evaluate();
+                    return;
+                }
+                // Delegate to original handler for other triggers
+                if (originalHandler) {
+                    await originalHandler(t, action);
+                }
+            });
+            this.started = true;
+            this.logger.info('EscalationService started', {
+                triggerId: this.triggerId,
+                cron,
+            });
+        }
+        catch (err) {
+            this.logger.warn('Failed to register escalation trigger (non-fatal)', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /**
+     * Stops the escalation service by cancelling its trigger.
+     */
+    async stop() {
+        if (this.triggerId) {
+            try {
+                const triggerEngine = TriggerEngine.getInstance(this.projectPath);
+                await triggerEngine.cancel(this.triggerId);
+            }
+            catch {
+                // Trigger may already be cleaned up
+            }
+            this.triggerId = null;
+        }
+        this.started = false;
+        this.logger.info('EscalationService stopped');
+    }
+    /**
+     * Returns whether the service is currently running.
+     */
+    isStarted() {
+        return this.started;
+    }
+    // ---------------------------------------------------------------------------
+    // Core Evaluation Loop
+    // ---------------------------------------------------------------------------
+    /**
+     * Evaluates all active Missions' escalation rules against current context.
+     * This is the main loop called periodically by the TriggerEngine.
+     *
+     * @returns Summary of the evaluation cycle
+     */
+    async evaluate() {
+        const evaluatedAt = new Date().toISOString();
+        const results = [];
+        try {
+            const missions = await this.loadActiveMissions();
+            for (const mission of missions) {
+                try {
+                    const context = await this.buildEscalationContext(mission);
+                    const escalation = this.policyService.evaluateEscalationRules(mission.policy.escalationRules, context);
+                    if (escalation.triggered) {
+                        const actionsExecuted = await this.executeEscalationActions(mission, escalation);
+                        results.push({
+                            missionId: mission.id,
+                            objective: mission.objective,
+                            escalation,
+                            actionsExecuted,
+                        });
+                    }
+                }
+                catch (err) {
+                    this.logger.warn('Escalation evaluation failed for mission (non-fatal)', {
+                        missionId: mission.id,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            const summary = {
+                missionsEvaluated: missions.length,
+                escalationsTriggered: results.length,
+                results: results.slice(0, MAX_LOG_RESULTS),
+                evaluatedAt,
+            };
+            if (results.length > 0) {
+                this.logger.info('Escalation cycle completed with triggers', {
+                    missionsEvaluated: summary.missionsEvaluated,
+                    escalationsTriggered: summary.escalationsTriggered,
+                });
+            }
+            else {
+                this.logger.debug('Escalation cycle completed — no triggers');
+            }
+            return summary;
+        }
+        catch (err) {
+            this.logger.warn('Escalation evaluation cycle failed (non-fatal)', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return {
+                missionsEvaluated: 0,
+                escalationsTriggered: 0,
+                results: [],
+                evaluatedAt,
+            };
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Context Building
+    // ---------------------------------------------------------------------------
+    /**
+     * Builds an EscalationContext for a Mission by aggregating runtime data.
+     *
+     * Sources:
+     * - Cost: sum of WorkItem costs linked to this mission
+     * - Time: hours elapsed since mission creation
+     * - Failures: count of failed WorkItems linked to this mission
+     *
+     * @param mission - The Mission to build context for
+     * @returns Populated EscalationContext
+     */
+    async buildEscalationContext(mission) {
+        const taskPool = TaskPoolService.getInstance();
+        const allItems = await taskPool.getAllItems();
+        // Filter WorkItems belonging to this mission
+        const missionItems = allItems.filter((wi) => wi.missionId === mission.id);
+        // Calculate cost
+        const currentCost = missionItems.reduce((sum, wi) => sum + (wi.cost ?? 0), 0);
+        // Calculate hours elapsed since mission creation
+        const createdAt = new Date(mission.createdAt).getTime();
+        const now = Date.now();
+        const hoursElapsed = (now - createdAt) / (1000 * 60 * 60);
+        // Count failures
+        const failureCount = missionItems.filter((wi) => wi.status === 'failed').length;
+        return {
+            currentCost,
+            hoursElapsed,
+            failureCount,
+            scopeChanged: false,
+            securityConcern: false,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Action Execution
+    // ---------------------------------------------------------------------------
+    /**
+     * Executes the required actions from an escalation result.
+     *
+     * Action severity order: block > pause > notify.
+     * Each triggered rule's action is executed via the registered handler.
+     *
+     * @param mission - The Mission being escalated
+     * @param escalation - The evaluation result with triggered rules
+     * @returns List of action descriptions that were executed
+     */
+    async executeEscalationActions(mission, escalation) {
+        const executed = [];
+        for (const rule of escalation.triggeredRules) {
+            try {
+                // Execute via registered handler
+                if (this.actionHandler) {
+                    await this.actionHandler(mission, rule, rule.action);
+                }
+                // Built-in actions
+                if (rule.action === 'pause') {
+                    await this.pauseMissionWorkItems(mission.id);
+                }
+                executed.push(`${rule.action}:${rule.condition}(${rule.threshold})→${rule.escalateTo}`);
+                this.logger.info('Escalation action executed', {
+                    missionId: mission.id,
+                    condition: rule.condition,
+                    threshold: rule.threshold,
+                    action: rule.action,
+                    escalateTo: rule.escalateTo,
+                });
+            }
+            catch (err) {
+                this.logger.warn('Escalation action failed (non-fatal)', {
+                    missionId: mission.id,
+                    rule,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return executed;
+    }
+    /**
+     * Pauses all active WorkItems belonging to a Mission.
+     * Sets queued/running items to 'blocked' status.
+     *
+     * @param missionId - The Mission ID whose WorkItems should be paused
+     */
+    async pauseMissionWorkItems(missionId) {
+        try {
+            const taskPool = TaskPoolService.getInstance();
+            const allItems = await taskPool.getAllItems();
+            const activeItems = allItems.filter((wi) => wi.missionId === missionId &&
+                (wi.status === 'queued' || wi.status === 'running'));
+            for (const item of activeItems) {
+                try {
+                    // queued → blocked requires queued→running→blocked or direct update
+                    await taskPool.updateItemStatus(item.id, 'blocked');
+                }
+                catch {
+                    // Some transitions may not be valid — skip
+                }
+            }
+            this.logger.info('Paused mission WorkItems', {
+                missionId,
+                pausedCount: activeItems.length,
+            });
+        }
+        catch (err) {
+            this.logger.warn('Failed to pause mission WorkItems (non-fatal)', {
+                missionId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Mission Loading
+    // ---------------------------------------------------------------------------
+    /**
+     * Loads all active Missions from disk.
+     *
+     * @returns Array of active Mission objects
+     */
+    async loadActiveMissions() {
+        try {
+            await ensureDir(this.missionsDir);
+            const files = await fs.readdir(this.missionsDir);
+            const missions = [];
+            for (const file of files) {
+                if (!file.endsWith('.json'))
+                    continue;
+                try {
+                    const filePath = path.join(this.missionsDir, file);
+                    const mission = await safeReadJson(filePath, null);
+                    if (mission &&
+                        mission.id &&
+                        mission.status === 'active' &&
+                        mission.policy?.escalationRules?.length > 0) {
+                        missions.push(mission);
+                    }
+                }
+                catch {
+                    // Skip malformed files
+                }
+            }
+            return missions;
+        }
+        catch {
+            return [];
+        }
+    }
+}
+//# sourceMappingURL=escalation.service.js.map

package/dist/backend/backend/src/services/v3/escalation.service.js.map

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

package/dist/backend/backend/src/services/v3/kr-tracking.service.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Key Result Tracking Service
+ *
+ * CRUD, measurement recording, progress aggregation, and WorkItem linkage
+ * for structured Key Results attached to Missions.
+ *
+ * Does NOT contain LLM logic — all status derivation is pure math.
+ * Agent reasoning happens in skills (review-mission, measure-kr).
+ *
+ * @module services/v3/kr-tracking.service
+ */
+import type { WorkItem } from '../../types/v2/work-item.types.js';
+import { type KeyResult, type KRMeasurement, type CreateKeyResultInput, type UpdateKeyResultInput, type MissionOKRSummary } from '../../types/v2/key-result.types.js';
+/**
+ * Service for managing Key Result lifecycle, measurements, and aggregation.
+ */
+export declare class KRTrackingService {
+    private static instance;
+    private readonly logger;
+    private constructor();
+    /**
+     * Get the singleton instance.
+     */
+    static getInstance(): KRTrackingService;
+    /**
+     * Reset the singleton (for testing).
+     */
+    static resetInstance(): void;
+    /**
+     * Create a new Key Result for a mission.
+     *
+     * @param input - Validated creation input
+     * @returns The created KeyResult
+     */
+    create(input: CreateKeyResultInput): Promise<KeyResult>;
+    /**
+     * Get a Key Result by ID.
+     *
+     * @param missionId - Parent mission ID
+     * @param krId - Key Result ID
+     * @returns The KeyResult, or null if not found
+     */
+    get(missionId: string, krId: string): Promise<KeyResult | null>;
+    /**
+     * List all Key Results for a mission.
+     *
+     * @param missionId - Mission ID
+     * @returns Array of KeyResults
+     */
+    listByMission(missionId: string): Promise<KeyResult[]>;
+    /**
+     * Update a Key Result.
+     *
+     * @param missionId - Parent mission ID
+     * @param krId - Key Result ID
+     * @param update - Fields to update
+     * @returns Updated KeyResult, or null if not found
+     */
+    update(missionId: string, krId: string, update: UpdateKeyResultInput): Promise<KeyResult | null>;
+    /**
+     * Delete a Key Result.
+     *
+     * @param missionId - Parent mission ID
+     * @param krId - Key Result ID
+     */
+    delete(missionId: string, krId: string): Promise<boolean>;
+    /**
+     * Record a new measurement for a Key Result.
+     * Automatically updates current value, recomputes status,
+     * and appends to measurement history.
+     *
+     * @param missionId - Parent mission ID
+     * @param krId - Key Result ID
+     * @param value - Measured value
+     * @param source - Who/what took the measurement
+     * @param note - Optional context
+     * @returns The recorded measurement, or null if KR not found
+     */
+    recordMeasurement(missionId: string, krId: string, value: number, source: string, note?: string): Promise<KRMeasurement | null>;
+    /**
+     * Link a WorkItem to a Key Result.
+     *
+     * @param missionId - Parent mission ID
+     * @param krId - Key Result ID
+     * @param workItemId - WorkItem ID to link
+     */
+    linkWorkItem(missionId: string, krId: string, workItemId: string): Promise<void>;
+    /**
+     * Handle WorkItem completion — auto-update KRs with task_completion source.
+     *
+     * For KRs measured by task completion, progress = completed linked items / total linked items.
+     *
+     * @param workItem - The completed WorkItem
+     */
+    onWorkItemCompleted(workItem: WorkItem): Promise<void>;
+    /**
+     * Compute aggregated OKR progress for a mission.
+     *
+     * @param missionId - Mission ID
+     * @param staleCycles - Number of consecutive stale review cycles
+     * @returns Aggregated summary with recommendation
+     */
+    computeMissionOKRProgress(missionId: string, staleCycles?: number): Promise<MissionOKRSummary>;
+    /**
+     * Persist a KeyResult to disk.
+     */
+    private persist;
+}
+//# sourceMappingURL=kr-tracking.service.d.ts.map

package/dist/backend/backend/src/services/v3/kr-tracking.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kr-tracking.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/v3/kr-tracking.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAClE,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAElB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EAQvB,MAAM,oCAAoC,CAAC;AAyB5C;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAkC;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC,OAAO;IAIP;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,iBAAiB;IAOvC;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,IAAI;IAQ5B;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,SAAS,CAAC;IAa7D;;;;;;OAMG;IACG,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IASrE;;;;;OAKG;IACG,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAkB5D;;;;;;;OAOG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAqBtG;;;;;OAKG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAa/D;;;;;;;;;;;OAWG;IACG,iBAAiB,CACrB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAuChC;;;;;;OAMG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWtF;;;;;;OAMG;IACG,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAsC5D;;;;;;OAMG;IACG,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,GAAE,MAAU,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAuCvG;;OAEG;YACW,OAAO;CAOtB"}