crewly 1.5.18 → 1.5.20

package/dist/backend/backend/src/services/reconciler/reconcile-rules.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Reconcile Rules — Individual reconciliation checks
+ *
+ * Each rule inspects a specific aspect of system state and returns
+ * corrections when discrepancies are found. Rules follow the CEO principle:
+ * "All automation is explainable" — every correction records who, what, why.
+ *
+ * @module services/reconciler/reconcile-rules
+ */
+import type { WorkItem, Request, TaskClaim, ReconcileCorrection, WakeAction, AgentScoreBreakdown } from '../../types/v2/index.js';
+/**
+ * Minimal agent info needed by reconcile rules.
+ * Abstraction over AgentRegistrationService / StorageService.
+ */
+export interface AgentHealth {
+    sessionName: string;
+    status: 'active' | 'started' | 'inactive' | 'suspended' | 'unknown';
+    lastSeenAt?: string;
+    /** Agent role (developer, qa, team-lead, etc.) — used for skill matching */
+    role?: string;
+    /** Tags describing agent capabilities (e.g. ['backend', 'typescript', 'rust']) */
+    tags?: string[];
+    /** Number of WorkItems currently assigned to this agent */
+    activeWorkItemCount?: number;
+    /** Team ID the agent belongs to */
+    teamId?: string;
+    /** Member ID within the team */
+    memberId?: string;
+}
+/**
+ * Detects WorkItems that are 'running' but whose assigned agent is not alive.
+ * Returns corrections to transition them to 'blocked' or 'failed'.
+ *
+ * @param workItems - All running WorkItems
+ * @param agentHealthMap - Map of agent session → health info
+ * @param timeoutMs - Max duration a WorkItem can be running (default: 10 min)
+ * @returns Array of corrections and affected WorkItem IDs
+ */
+export declare function detectStuckWorkItems(workItems: WorkItem[], agentHealthMap: Map<string, AgentHealth>, timeoutMs?: number): {
+    corrections: ReconcileCorrection[];
+    stuckIds: string[];
+};
+/**
+ * Detects TaskClaims whose lease has expired and should be released or revoked.
+ *
+ * @param claims - All active claims
+ * @param gracePeriodMs - Grace period duration in ms
+ * @returns Claims to mark as expiring and claims to revoke
+ */
+export declare function detectExpiredClaims(claims: TaskClaim[], gracePeriodMs?: number): {
+    corrections: ReconcileCorrection[];
+    expiringIds: string[];
+    revokedIds: string[];
+};
+/**
+ * Recomputes the correct status for a Request based on its WorkItems' statuses.
+ * This is the core "truth recomputation" — events are hints, this is truth.
+ *
+ * @param request - The Request to reconcile
+ * @param workItems - All WorkItems belonging to this Request
+ * @returns Correction if status needs updating, null otherwise
+ */
+export declare function reconcileRequestStatus(request: Request, workItems: WorkItem[]): ReconcileCorrection | null;
+/**
+ * Detects WorkItems whose parent has been cancelled/failed but are still active.
+ * These should be cascade-cancelled.
+ *
+ * @param workItems - All WorkItems to check
+ * @param workItemMap - Map of WorkItem ID → WorkItem for parent lookup
+ * @returns Corrections for orphan WorkItems
+ */
+export declare function detectOrphanWorkItems(workItems: WorkItem[], workItemMap: Map<string, WorkItem>): {
+    corrections: ReconcileCorrection[];
+    orphanIds: string[];
+};
+/**
+ * Detects WorkItems that have exceeded their time-to-live.
+ * Default TTL is 24 hours.
+ *
+ * @param workItems - All non-terminal WorkItems to check
+ * @param ttlMs - Maximum age before auto-cancel (default: 24h)
+ * @returns Corrections for expired WorkItems
+ */
+export declare function detectTTLExpiredWorkItems(workItems: WorkItem[], ttlMs?: number): {
+    corrections: ReconcileCorrection[];
+    expiredIds: string[];
+};
+/**
+ * Detects blocked WorkItems whose assigned agent is now alive,
+ * suggesting they can be re-queued for retry.
+ *
+ * @param workItems - All blocked WorkItems
+ * @param agentHealthMap - Map of agent session → health info
+ * @returns Corrections to re-queue recoverable WorkItems
+ */
+export declare function detectRecoverableWorkItems(workItems: WorkItem[], agentHealthMap: Map<string, AgentHealth>): {
+    corrections: ReconcileCorrection[];
+    recoverableIds: string[];
+};
+/**
+ * Performs deep cascade cancellation: when a WorkItem is cancelled/failed,
+ * all descendants (children, grandchildren, etc.) should be cancelled too.
+ * This is a recursive version of detectOrphanWorkItems.
+ *
+ * @param cancelledIds - Set of WorkItem IDs that have been cancelled/failed
+ * @param allWorkItems - All WorkItems in the system
+ * @returns Corrections for cascaded cancellations
+ */
+export declare function cascadeCancelChildren(cancelledIds: Set<string>, allWorkItems: WorkItem[]): {
+    corrections: ReconcileCorrection[];
+    cascadedIds: string[];
+};
+/**
+ * Detects WorkItems that have been in 'queued' status for too long
+ * without being picked up. These may indicate assignment problems.
+ *
+ * @param workItems - All WorkItems to check
+ * @param staleThresholdMs - How long in queued before considered stale (default: 1h)
+ * @returns Corrections for stale queued WorkItems
+ */
+export declare function detectStaleQueuedWorkItems(workItems: WorkItem[], staleThresholdMs?: number): {
+    corrections: ReconcileCorrection[];
+    staleIds: string[];
+};
+/**
+ * Result of a pruning pass, aggregating all pruning-related corrections.
+ */
+export interface PruningResult {
+    /** WorkItems cancelled due to TTL expiry */
+    ttlExpiredCount: number;
+    /** WorkItems cancelled due to orphan cascade */
+    orphanCancelledCount: number;
+    /** WorkItems cancelled due to deep cascade */
+    cascadeCancelledCount: number;
+    /** WorkItems flagged as stale in queue */
+    staleQueuedCount: number;
+    /** Total corrections from pruning */
+    totalCorrections: ReconcileCorrection[];
+}
+/**
+ * Runs a complete pruning pass — combines TTL, orphan, cascade, and stale detection.
+ * Called as part of the Reconciler's full loop every 5 minutes.
+ *
+ * @param allWorkItems - All WorkItems in the system
+ * @param ttlMs - TTL threshold (default: 24h)
+ * @param staleThresholdMs - Stale queue threshold (default: 1h)
+ * @returns Aggregated pruning result
+ */
+export declare function runPruningPass(allWorkItems: WorkItem[], ttlMs?: number, staleThresholdMs?: number): PruningResult;
+/** Default threshold for unclaimed task detection (2 minutes). */
+export declare const UNCLAIMED_THRESHOLD_MS: number;
+/** Maximum number of wake actions per reconcile pass (rate limit). */
+export declare const MAX_WAKE_ACTIONS_PER_PASS = 3;
+/**
+ * Result from the detectUnclaimedTasks rule.
+ */
+export interface UnclaimedTasksResult {
+    /** Wake actions to execute */
+    wakeActions: WakeAction[];
+    /** WorkItem IDs that triggered wake actions */
+    unclaimedWorkItemIds: string[];
+}
+/**
+ * Detects WorkItems in 'queued' status that have gone unclaimed for longer
+ * than the threshold, and selects the best dormant agent to wake.
+ *
+ * Selection algorithm scores agents by:
+ *   skill_match (0–40) + urgency (0–30) + context_familiarity (0–20) - load_penalty (0–20)
+ *
+ * Wake strategy depends on agent status:
+ *   - suspended → rehydrate (AgentSuspendService.rehydrateAgent())
+ *   - inactive → start (start-agent API)
+ *
+ * @param workItems - All queued WorkItems in the pool
+ * @param agentHealthMap - Map of agent session → health info
+ * @param unclaimedThresholdMs - How long unclaimed before triggering wake (default: 2 min)
+ * @returns Wake actions and affected WorkItem IDs
+ */
+export declare function detectUnclaimedTasks(workItems: WorkItem[], agentHealthMap: Map<string, AgentHealth>, unclaimedThresholdMs?: number): UnclaimedTasksResult;
+/**
+ * Scores and selects the best agent to handle a WorkItem.
+ *
+ * Score = skill_match (0–40) + urgency (0–30) + context_familiarity (0–20) - load_penalty (0–20)
+ *
+ * @param workItem - The WorkItem needing an agent
+ * @param agents - Candidate agents (suspended or inactive)
+ * @param waitTimeMs - How long the WorkItem has been waiting
+ * @param excludeAgents - Agents already scheduled for wake in this pass
+ * @returns Best agent with score, or null if no suitable agent
+ */
+export declare function selectBestAgent(workItem: WorkItem, agents: AgentHealth[], waitTimeMs: number, excludeAgents?: Set<string>): {
+    agent: AgentHealth;
+    score: number;
+    breakdown: AgentScoreBreakdown;
+} | null;
+/**
+ * Computes the score breakdown for a single agent–WorkItem pair.
+ *
+ * @param workItem - The WorkItem being matched
+ * @param agent - The candidate agent
+ * @param waitTimeMs - How long the WorkItem has been waiting
+ * @returns Score breakdown
+ */
+export declare function computeAgentScore(workItem: WorkItem, agent: AgentHealth, waitTimeMs: number): AgentScoreBreakdown;
+/**
+ * Detects WorkItems in 'failed' status that still have remaining retries
+ * and can be automatically re-queued for another attempt.
+ *
+ * @param workItems - Active WorkItems to inspect
+ * @returns Corrections for retryable items and their IDs
+ */
+export declare function detectRetryableFailedWorkItems(workItems: WorkItem[]): {
+    corrections: ReconcileCorrection[];
+    retriedIds: string[];
+};
+/**
+ * Detects WorkItems in 'blocked' status whose blocking dependencies
+ * (tracked via dependsOn array) have all reached terminal status.
+ * These items can be unblocked and re-queued.
+ *
+ * @param workItems - Active WorkItems to inspect
+ * @param workItemMap - Map of all WorkItems by ID for dependency lookup
+ * @returns Corrections for unblocked items and their IDs
+ */
+export declare function detectDependencyResolvedWorkItems(workItems: WorkItem[], workItemMap: Map<string, WorkItem>): {
+    corrections: ReconcileCorrection[];
+    unblockedIds: string[];
+};
+//# sourceMappingURL=reconcile-rules.d.ts.map

package/dist/backend/backend/src/services/reconciler/reconcile-rules.d.ts.map

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