crewly 1.5.18 → 1.5.20

package/dist/backend/backend/src/types/v2/reconcile.types.d.ts

@@ -0,0 +1,199 @@
+/**
+ * V2 Reconciler Type Definitions
+ *
+ * The Reconciler is the "CPU" of Crewly V3 — it periodically recomputes
+ * system truth from durable state, not trusting event delivery.
+ * These types define its outputs and configuration.
+ *
+ * @module types/v2/reconcile.types
+ */
+/**
+ * The output of a single reconciliation pass.
+ * Captures what the Reconciler found and corrected.
+ */
+export interface ReconcileResult {
+    /** Requests whose status was corrected */
+    requestsUpdated: number;
+    /** WorkItems that were timed out */
+    workItemsTimedOut: number;
+    /** WorkItems that were re-queued (recovered from stuck state) */
+    workItemsRequeued: number;
+    /** Triggers that were rebuilt (missed fires detected and fixed) */
+    triggersRebuilt: number;
+    /** Claims revoked due to expired lease + grace period */
+    claimsRevoked: number;
+    /** Stale data cleaned up (orphan tasks, expired items) */
+    staleItemsCleaned: number;
+    /** ISO8601 timestamp of this reconciliation */
+    reconciledAt: string;
+    /** Duration of the reconcile pass in milliseconds */
+    durationMs: number;
+    /** Whether this was a full or targeted reconciliation */
+    type: ReconcileType;
+    /** Agents woken up via Hybrid Wake (suspended rehydrated or inactive started) */
+    agentsWoken: number;
+    /** Detailed log of individual corrections (for debugging/audit) */
+    corrections: ReconcileCorrection[];
+    /** Wake actions triggered during this pass */
+    wakeActions: WakeAction[];
+    /** Errors encountered during reconciliation (non-fatal) */
+    errors: string[];
+}
+/**
+ * Type of reconciliation pass.
+ * - full: Scans all entities (periodic, on restart)
+ * - targeted_request: Only reconciles a single Request + its WorkItems
+ * - targeted_mission: Only reconciles a single Mission + its ProjectTasks
+ * - fast: Quick pass — only checks lease expiry + agent health
+ */
+export type ReconcileType = 'full' | 'targeted_request' | 'targeted_mission' | 'fast';
+/** All valid ReconcileType values. */
+export declare const RECONCILE_TYPES: readonly ReconcileType[];
+/**
+ * A single correction made by the Reconciler.
+ * Follows CEO principle: "All automation is explainable."
+ */
+export interface ReconcileCorrection {
+    /** What entity was corrected (request, work_item, trigger, claim, etc.) */
+    entityType: 'request' | 'work_item' | 'trigger' | 'project_task' | 'claim';
+    /** ID of the corrected entity */
+    entityId: string;
+    /** What the status was before correction */
+    previousState: string;
+    /** What the status was changed to */
+    newState: string;
+    /** Why this correction was made */
+    reason: string;
+    /** What evidence triggered this correction */
+    evidence: string;
+    /** ISO8601 timestamp */
+    correctedAt: string;
+}
+/**
+ * Strategy for waking an agent based on its current status.
+ * - rehydrate: Agent is suspended → call AgentSuspendService.rehydrateAgent()
+ * - start: Agent is inactive → call start-agent API
+ */
+export type WakeStrategy = 'rehydrate' | 'start';
+/**
+ * A wake action to bring a dormant agent online for unclaimed work.
+ * Produced by the detectUnclaimedTasks reconcile rule.
+ */
+export interface WakeAction {
+    /** WorkItem ID that triggered the wake */
+    workItemId: string;
+    /** Agent session name to wake */
+    agentSessionName: string;
+    /** How to wake: rehydrate (suspended) or start (inactive) */
+    strategy: WakeStrategy;
+    /** Score from the agent selection algorithm */
+    score: number;
+    /** Breakdown of how the score was computed */
+    scoreBreakdown: AgentScoreBreakdown;
+    /** ISO8601 timestamp */
+    triggeredAt: string;
+    /** Optional team ID for start strategy */
+    teamId?: string;
+    /** Optional member ID for start strategy */
+    memberId?: string;
+}
+/**
+ * Breakdown of agent selection score components.
+ * Final score = skillMatch + urgency + contextFamiliarity - loadPenalty
+ */
+export interface AgentScoreBreakdown {
+    /** 0–40: How well the agent's role/type matches the WorkItem */
+    skillMatch: number;
+    /** 0–30: How urgent the WorkItem is (based on wait time) */
+    urgency: number;
+    /** 0–20: How familiar the agent is with the WorkItem's context */
+    contextFamiliarity: number;
+    /** 0–20: Penalty for agent's current load */
+    loadPenalty: number;
+}
+/**
+ * Configuration for the ReconcilerService.
+ * Controls timing, thresholds, and behavior.
+ */
+export interface ReconcilerConfig {
+    /** Fast loop interval in ms (default: 10000 = 10s) — lease + agent health only */
+    fastLoopIntervalMs: number;
+    /** Full loop interval in ms (default: 60000 = 60s) — complete scan */
+    fullLoopIntervalMs: number;
+    /** Max duration allowed for a single reconcile pass in ms (budget: 3s) */
+    maxReconcileDurationMs: number;
+    /** WorkItem timeout threshold in ms — running longer than this = stuck */
+    workItemTimeoutMs: number;
+    /** How many recent ReconcileResults to retain in history */
+    maxHistorySize: number;
+    /** Whether event-triggered targeted reconciliation is enabled */
+    eventTriggeredEnabled: boolean;
+}
+/**
+ * Default Reconciler configuration values.
+ * Performance budget: single reconcile < 3s (CEO requirement).
+ */
+export declare const DEFAULT_RECONCILER_CONFIG: Readonly<ReconcilerConfig>;
+/**
+ * Current status of the ReconcilerService.
+ * Exposed via GET /api/reconciler/status.
+ */
+export interface ReconcilerStatus {
+    /** Whether the Reconciler is currently running a pass */
+    isRunning: boolean;
+    /** Last completed reconciliation result */
+    lastResult?: ReconcileResult;
+    /** Next scheduled full reconciliation time (ISO8601) */
+    nextFullReconcileAt?: string;
+    /** Next scheduled fast reconciliation time (ISO8601) */
+    nextFastReconcileAt?: string;
+    /** Total number of reconcile passes since startup */
+    totalPasses: number;
+    /** Total corrections made since startup */
+    totalCorrections: number;
+    /** Current configuration */
+    config: ReconcilerConfig;
+}
+/**
+ * Checks whether a string is a valid ReconcileType.
+ *
+ * @param value - The string to check
+ * @returns True if value is a valid ReconcileType
+ */
+export declare function isValidReconcileType(value: string): value is ReconcileType;
+/**
+ * Validates that an unknown value is structurally a valid ReconcileResult.
+ *
+ * @param value - Unknown value to validate
+ * @returns True if value conforms to the ReconcileResult interface
+ */
+export declare function isReconcileResult(value: unknown): value is ReconcileResult;
+/**
+ * Validates that an unknown value is a valid ReconcilerConfig.
+ *
+ * @param value - Unknown value to validate
+ * @returns True if value conforms to ReconcilerConfig
+ */
+export declare function isValidReconcilerConfig(value: unknown): value is ReconcilerConfig;
+/**
+ * Creates an empty ReconcileResult for a new reconciliation pass.
+ *
+ * @param type - The type of reconciliation being performed
+ * @returns A ReconcileResult with all counters at zero
+ */
+export declare function createEmptyReconcileResult(type: ReconcileType): ReconcileResult;
+/**
+ * Creates a ReconcileCorrection entry.
+ *
+ * @param params - Correction details
+ * @returns A fully populated ReconcileCorrection
+ */
+export declare function createCorrection(params: {
+    entityType: ReconcileCorrection['entityType'];
+    entityId: string;
+    previousState: string;
+    newState: string;
+    reason: string;
+    evidence: string;
+}): ReconcileCorrection;
+//# sourceMappingURL=reconcile.types.d.ts.map

package/dist/backend/backend/src/types/v2/reconcile.types.d.ts.map

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

package/dist/backend/backend/src/types/v2/reconcile.types.js

@@ -0,0 +1,121 @@
+/**
+ * V2 Reconciler Type Definitions
+ *
+ * The Reconciler is the "CPU" of Crewly V3 — it periodically recomputes
+ * system truth from durable state, not trusting event delivery.
+ * These types define its outputs and configuration.
+ *
+ * @module types/v2/reconcile.types
+ */
+/** All valid ReconcileType values. */
+export const RECONCILE_TYPES = [
+    'full',
+    'targeted_request',
+    'targeted_mission',
+    'fast',
+];
+/**
+ * Default Reconciler configuration values.
+ * Performance budget: single reconcile < 3s (CEO requirement).
+ */
+export const DEFAULT_RECONCILER_CONFIG = {
+    fastLoopIntervalMs: 10_000, // 10 seconds
+    fullLoopIntervalMs: 60_000, // 60 seconds
+    maxReconcileDurationMs: 3_000, // 3 seconds performance budget
+    workItemTimeoutMs: 600_000, // 10 minutes
+    maxHistorySize: 100,
+    eventTriggeredEnabled: true,
+};
+// ---------------------------------------------------------------------------
+// Type Guards
+// ---------------------------------------------------------------------------
+/**
+ * Checks whether a string is a valid ReconcileType.
+ *
+ * @param value - The string to check
+ * @returns True if value is a valid ReconcileType
+ */
+export function isValidReconcileType(value) {
+    return RECONCILE_TYPES.includes(value);
+}
+/**
+ * Validates that an unknown value is structurally a valid ReconcileResult.
+ *
+ * @param value - Unknown value to validate
+ * @returns True if value conforms to the ReconcileResult interface
+ */
+export function isReconcileResult(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const obj = value;
+    return (typeof obj.requestsUpdated === 'number' &&
+        typeof obj.workItemsTimedOut === 'number' &&
+        typeof obj.workItemsRequeued === 'number' &&
+        typeof obj.claimsRevoked === 'number' &&
+        typeof obj.triggersRebuilt === 'number' &&
+        typeof obj.staleItemsCleaned === 'number' &&
+        typeof obj.reconciledAt === 'string' &&
+        typeof obj.durationMs === 'number' &&
+        typeof obj.type === 'string' &&
+        isValidReconcileType(obj.type) &&
+        typeof obj.agentsWoken === 'number' &&
+        Array.isArray(obj.corrections) &&
+        Array.isArray(obj.wakeActions) &&
+        Array.isArray(obj.errors));
+}
+/**
+ * Validates that an unknown value is a valid ReconcilerConfig.
+ *
+ * @param value - Unknown value to validate
+ * @returns True if value conforms to ReconcilerConfig
+ */
+export function isValidReconcilerConfig(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const obj = value;
+    return (typeof obj.fastLoopIntervalMs === 'number' && obj.fastLoopIntervalMs > 0 &&
+        typeof obj.fullLoopIntervalMs === 'number' && obj.fullLoopIntervalMs > 0 &&
+        typeof obj.maxReconcileDurationMs === 'number' && obj.maxReconcileDurationMs > 0 &&
+        typeof obj.workItemTimeoutMs === 'number' && obj.workItemTimeoutMs > 0 &&
+        typeof obj.maxHistorySize === 'number' && obj.maxHistorySize > 0 &&
+        typeof obj.eventTriggeredEnabled === 'boolean');
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Creates an empty ReconcileResult for a new reconciliation pass.
+ *
+ * @param type - The type of reconciliation being performed
+ * @returns A ReconcileResult with all counters at zero
+ */
+export function createEmptyReconcileResult(type) {
+    return {
+        requestsUpdated: 0,
+        workItemsTimedOut: 0,
+        workItemsRequeued: 0,
+        claimsRevoked: 0,
+        triggersRebuilt: 0,
+        staleItemsCleaned: 0,
+        agentsWoken: 0,
+        reconciledAt: new Date().toISOString(),
+        durationMs: 0,
+        type,
+        corrections: [],
+        wakeActions: [],
+        errors: [],
+    };
+}
+/**
+ * Creates a ReconcileCorrection entry.
+ *
+ * @param params - Correction details
+ * @returns A fully populated ReconcileCorrection
+ */
+export function createCorrection(params) {
+    return {
+        ...params,
+        correctedAt: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=reconcile.types.js.map

package/dist/backend/backend/src/types/v2/reconcile.types.js.map

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

package/dist/backend/backend/src/types/v2/request.types.d.ts

@@ -0,0 +1,188 @@
+/**
+ * V2 Request Type Definitions
+ *
+ * A Request represents a single user goal — "one thing the user wants
+ * the system to accomplish." Requests are the primary user-facing object
+ * in V2 architecture.
+ *
+ * @module types/v2/request.types
+ */
+/**
+ * Lifecycle statuses for a Request.
+ *
+ * State machine:
+ *   open → ready                  (planner created WorkItems)
+ *   open → cancelled              (user cancelled before planning)
+ *   ready → running               (first WorkItem started)
+ *   running → blocked             (all active WorkItems blocked/failed)
+ *   running → waiting_confirmation (all done, requiresConfirmation=true)
+ *   running → done                (all done, requiresConfirmation=false)
+ *   blocked → running             (WorkItem unblocked or new WorkItem created)
+ *   waiting_confirmation → done   (user confirmed)
+ *   waiting_confirmation → running (user rejected, new WorkItems needed)
+ *   any → cancelled               (user explicitly cancels)
+ */
+export type RequestStatus = 'open' | 'ready' | 'running' | 'blocked' | 'waiting_confirmation' | 'done' | 'cancelled';
+/** All valid RequestStatus values as a readonly array. */
+export declare const REQUEST_STATUSES: readonly RequestStatus[];
+/** Terminal statuses — no further transitions allowed (except cancel). */
+export declare const TERMINAL_REQUEST_STATUSES: ReadonlySet<RequestStatus>;
+/**
+ * Intent category carried from v1 IntentTask system.
+ */
+export type IntentCategory = 'query' | 'code_change' | 'debugging' | 'deployment' | 'research' | 'review' | 'planning' | 'communication' | 'other';
+/** All valid IntentCategory values. */
+export declare const INTENT_CATEGORIES: readonly IntentCategory[];
+/**
+ * Intent complexity level — determines planning strategy.
+ * - L0: trivial, no WorkItem needed (direct response)
+ * - L1: single WorkItem sufficient
+ * - L2: multiple WorkItems, potentially parallel
+ */
+export type IntentLevel = 'L0' | 'L1' | 'L2';
+/**
+ * A user-level request representing a single goal.
+ *
+ * Requests are the primary unit of work visible to users.
+ * Each Request is fulfilled through one or more WorkItems.
+ */
+export interface Request {
+    /** UUID v4 */
+    id: string;
+    /** ConversationItem that originated this Request */
+    sourceConversationItemId: string;
+    /** Human-readable title (generated from intent parsing) */
+    title: string;
+    /** Detailed description of what the user wants */
+    description: string;
+    /** Lifecycle status */
+    status: RequestStatus;
+    /** User-assigned or auto-classified priority */
+    priority: 'low' | 'normal' | 'high';
+    /** Whether completion requires explicit user confirmation */
+    requiresConfirmation: boolean;
+    /** Reason confirmation is needed (shown to user) */
+    confirmationReason?: string;
+    /** WorkItem IDs created to fulfill this Request */
+    workItemIds: string[];
+    /** Optional link to a Mission this Request contributes to */
+    missionId?: string;
+    /** Optional link to a ProjectTask created from this Request */
+    projectTaskId?: string;
+    /** Intent complexity level */
+    intentLevel: IntentLevel;
+    /** Intent category */
+    intentCategory: IntentCategory;
+    /** Tags for filtering */
+    tags: string[];
+    /** ISO8601 timestamps */
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    /** Result summary (set on completion) */
+    result?: string;
+    /** Total token usage across all WorkItems */
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    /** Total cost in USD */
+    totalCost: number;
+    /** Session name of the agent that handled this Request directly (no WorkItem delegation) */
+    ownerAgent?: string;
+}
+/**
+ * Input for creating a new Request.
+ * Fields with defaults are optional.
+ */
+export interface CreateRequestInput {
+    sourceConversationItemId: string;
+    title: string;
+    description: string;
+    priority?: 'low' | 'normal' | 'high';
+    requiresConfirmation?: boolean;
+    confirmationReason?: string;
+    missionId?: string;
+    intentLevel?: IntentLevel;
+    intentCategory?: IntentCategory;
+    tags?: string[];
+}
+/**
+ * Input for updating an existing Request.
+ * All fields optional — only provided fields are updated.
+ */
+export interface UpdateRequestInput {
+    title?: string;
+    description?: string;
+    status?: RequestStatus;
+    priority?: 'low' | 'normal' | 'high';
+    requiresConfirmation?: boolean;
+    confirmationReason?: string;
+    missionId?: string;
+    projectTaskId?: string;
+    result?: string;
+    tags?: string[];
+    /** Token roll-up fields — incremented by V3.1 task completion hooks */
+    totalInputTokens?: number;
+    totalOutputTokens?: number;
+    totalCost?: number;
+    /** Session name of the agent that handled this Request directly */
+    ownerAgent?: string;
+}
+/**
+ * Map of valid status transitions.
+ * Key = current status, Value = set of allowed next statuses.
+ */
+export declare const REQUEST_TRANSITIONS: Record<RequestStatus, ReadonlySet<RequestStatus>>;
+/**
+ * Checks whether a string is a valid RequestStatus.
+ *
+ * @param value - The string to check
+ * @returns True if value is a valid RequestStatus
+ */
+export declare function isValidRequestStatus(value: string): value is RequestStatus;
+/**
+ * Checks whether a string is a valid IntentCategory.
+ *
+ * @param value - The string to check
+ * @returns True if value is a valid IntentCategory
+ */
+export declare function isValidIntentCategory(value: string): value is IntentCategory;
+/**
+ * Checks whether a status transition is valid according to the state machine.
+ *
+ * @param from - Current status
+ * @param to - Desired next status
+ * @returns True if transition is allowed
+ */
+export declare function isValidRequestTransition(from: RequestStatus, to: RequestStatus): boolean;
+/**
+ * Validates that an object is structurally a valid Request.
+ *
+ * @param value - Unknown value to validate
+ * @returns True if value conforms to the Request interface
+ */
+export declare function isRequest(value: unknown): value is Request;
+/**
+ * Validates CreateRequestInput and returns an array of error messages.
+ * Empty array means input is valid.
+ *
+ * @param input - The creation input to validate
+ * @returns Array of validation error strings (empty = valid)
+ */
+export declare function validateCreateRequestInput(input: CreateRequestInput): string[];
+/**
+ * Creates a new Request with sensible defaults.
+ *
+ * @param input - Required and optional creation fields
+ * @returns A fully populated Request object
+ *
+ * @example
+ * ```typescript
+ * const request = createRequest({
+ *   sourceConversationItemId: 'conv-123',
+ *   title: 'Deploy staging',
+ *   description: 'Deploy the current build to staging env',
+ * });
+ * ```
+ */
+export declare function createRequest(input: CreateRequestInput): Request;
+//# sourceMappingURL=request.types.d.ts.map

package/dist/backend/backend/src/types/v2/request.types.d.ts.map

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