crewly 1.13.0 → 1.14.0

package/dist/cli/backend/src/services/v3/escalation-router.service.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Escalation Router Service
+ *
+ * Routes escalations to the appropriate target:
+ * - target === 'team_lead' → Send message to TL agent via MessageQueue
+ * - target === 'human' → Send Slack notification to user + pause task + create pending record
+ *
+ * Also handles MissionPolicy escalation rules (cost_exceeded, failure_count, etc.)
+ * by routing `escalateTo: 'user'` to human and `escalateTo: 'orchestrator'` to agent.
+ *
+ * Pending human escalations are stored in `.crewly/escalations/` and resolved
+ * via POST /api/escalations/:id/resolve.
+ *
+ * @module services/v3/escalation-router.service
+ */
+import type { AlignmentRequest } from '../../types/v2/work-item.types.js';
+import type { EscalationRule, Mission } from '../../types/v2/mission.types.js';
+/** Status of a pending human escalation. */
+export type EscalationStatus = 'pending' | 'resolved' | 'expired';
+/**
+ * Minimal WorkItem shape `escalateFailedWorkItem` needs. Defined locally
+ * (rather than importing the full WorkItem type) to keep this service's
+ * dependency surface narrow — escalation only reads, never writes,
+ * fields it doesn't recognise.
+ */
+export interface WorkItemForEscalation {
+    id: string;
+    title: string;
+    type: string;
+    target?: string | null;
+    retryCount: number;
+    maxRetries: number;
+    error?: string | null;
+    requestId?: string | null;
+    missionId?: string | null;
+    parentWorkItemId?: string | null;
+    priority?: string | null;
+}
+/** A persisted escalation record awaiting human resolution. */
+export interface PendingEscalation {
+    id: string;
+    status: EscalationStatus;
+    /** What triggered this escalation */
+    source: 'alignment_request' | 'policy_rule' | 'tl_verification' | 'manual' | 'workitem_failed';
+    /** Who needs to resolve it */
+    target: 'human' | 'team_lead' | 'orchestrator';
+    /** The escalation content */
+    summary: string;
+    details: Record<string, unknown>;
+    /** Related IDs */
+    workItemId?: string;
+    missionId?: string;
+    taskId?: string;
+    /** Who raised it */
+    raisedBy: string;
+    raisedAt: string;
+    /** Resolution (filled when resolved) */
+    resolvedAt?: string;
+    resolvedBy?: string;
+    resolution?: string;
+}
+export declare class EscalationRouterService {
+    private static instance;
+    private readonly logger;
+    private readonly escalationsDir;
+    private constructor();
+    static getInstance(projectPath?: string): EscalationRouterService;
+    static resetInstance(): void;
+    /**
+     * Route a worker's AlignmentRequest to the correct target.
+     *
+     * @param request - The structured alignment request from the worker
+     * @param workItemId - The WorkItem being escalated
+     * @param workerSession - Worker's session name
+     * @returns The escalation ID if routed to human, null if handled by agent
+     */
+    routeAlignmentRequest(request: AlignmentRequest, workItemId: string, workerSession: string): Promise<string | null>;
+    /**
+     * Route a MissionPolicy escalation rule trigger.
+     *
+     * @param mission - The Mission that triggered the rule
+     * @param rule - The escalation rule that fired
+     * @param context - Current context values (cost, time, failures)
+     */
+    routePolicyEscalation(mission: Mission, rule: EscalationRule, context: Record<string, number>): Promise<string | null>;
+    /**
+     * Resolve a pending human escalation.
+     *
+     * @param escalationId - The escalation to resolve
+     * @param resolution - What the human decided
+     * @param resolvedBy - Who resolved it (user ID or name)
+     * @returns The updated escalation, or null if not found
+     */
+    resolve(escalationId: string, resolution: string, resolvedBy: string): Promise<PendingEscalation | null>;
+    /**
+     * Escalate a WorkItem that exhausted its retry budget to the
+     * orchestrator. The orchestrator receives a structured message via
+     * the same MessageQueue used by `target='team_lead'` escalations,
+     * decides whether to (a) surface to the user, (b) replan, (c) hand
+     * off to a different agent. Also persists a `PendingEscalation`
+     * record for the dashboard / API.
+     *
+     * Called from `V3DataService.onTaskFailed` once `retryCount >=
+     * maxRetries`. Best-effort — exceptions are caught and logged so a
+     * messaging blip doesn't strand the upstream failure handler.
+     *
+     * @param wi      - The failed WorkItem (post-`failItem`, with retryCount
+     *                  and maxRetries reflecting the exhausted budget)
+     * @param reason  - Final failure reason (same string written to wi.error)
+     * @returns The persisted escalation id, or null on persistence failure
+     */
+    escalateFailedWorkItem(wi: WorkItemForEscalation, reason: string): Promise<string | null>;
+    /**
+     * Deliver the FINAL deliverable judgment to the orchestrator when a Request
+     * completes — every child WorkItem was verified (P2 acceptance gate), so the
+     * whole deliverable is assembled and per-piece accepted. Asks the orc (the
+     * top-level TL) to do the holistic check the per-piece verification cannot:
+     * does the ASSEMBLED result meet the original goal and is it actually usable?
+     * Accept to close, or reopen with concrete gaps (which re-delegates rework).
+     *
+     * Best-effort — enqueues a self-contained orc message; never throws.
+     *
+     * @param request - The completed Request (id + goal/title for the summary).
+     * @param childItems - Its child WorkItems (title + status, for the summary).
+     * @returns Resolves when the message is enqueued (or silently on failure).
+     */
+    requestFinalDeliverableReview(request: {
+        id: string;
+        title?: string;
+        description?: string;
+        objective?: string;
+    }, childItems: Array<{
+        title: string;
+        status: string;
+    }>): Promise<void>;
+    /**
+     * Escalate a WorkItem whose worker reported done but whose Team Leader has
+     * NOT verified it within the deadline (verification-enforcement, P1).
+     *
+     * Asks the orchestrator to render an EXPLICIT verdict — verify/accept
+     * (→ verified) or reject (→ rejected → the existing rework loop) — so
+     * unverified work is never silently auto-accepted by the 24h TTL fallback
+     * (`pickTTLExpiryTarget('done_by_worker') → 'verified'`). Mirrors
+     * {@link escalateFailedWorkItem}: persists a `tl_verification` escalation
+     * targeted at the orchestrator and enqueues a self-contained orc-facing
+     * message. Best-effort — persistence/message failures are logged, not
+     * thrown, so the reconciler pass never strands on it.
+     *
+     * @param wi - The unverified WorkItem (only read).
+     * @param awaitingMs - How long it has awaited verification (for the message).
+     * @returns The escalation id, or null on a hard failure.
+     */
+    escalateUnverifiedWorkItem(wi: WorkItemForEscalation, awaitingMs: number): Promise<string | null>;
+    /**
+     * List all pending escalations.
+     */
+    listPending(): Promise<PendingEscalation[]>;
+    private createPendingEscalation;
+    private saveEscalation;
+    private loadEscalation;
+    /**
+     * Notify human via the same channel the original request came from.
+     * Falls back to Slack → Chat UI if source channel can't be determined.
+     */
+    private notifyHuman;
+    /**
+     * Resolve the source channel for an escalation by tracing back to the
+     * original Request/ChatMessage that started the work.
+     */
+    private resolveSourceChannel;
+    /**
+     * Notify TL agent via message queue (for team_lead-targeted escalations).
+     */
+    private notifyAgent;
+    private pauseWorkItem;
+    private resumeWorkItem;
+}
+//# sourceMappingURL=escalation-router.service.d.ts.map

package/dist/cli/backend/src/services/v3/escalation-router.service.d.ts.map

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