crewly 1.5.18 → 1.5.20

package/dist/backend/backend/src/services/task-pool/claim.service.js

@@ -0,0 +1,354 @@
+/**
+ * ClaimService — Manages task claim lifecycle (lease, heartbeat, grace period)
+ *
+ * Agents claim WorkItems from the Task Pool via this service. Each claim has:
+ * - Lease (default 10min): agent must complete or extend before expiry
+ * - Heartbeat (2min interval): agent signals liveness
+ * - Grace period (3min): buffer after lease expiry before forced revocation
+ * - Max extensions (3): how many times a lease can be renewed
+ *
+ * The Reconciler uses this service to detect expired/grace-exceeded claims.
+ *
+ * @module services/task-pool/claim.service
+ */
+import { LoggerService } from '../core/logger.service.js';
+import { createTaskClaim, extendClaim, isLeaseExpired, isGracePeriodExceeded, canExtendLease, validateCreateClaimInput, DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_GRACE_PERIOD_MS, } from '../../types/v2/claim.types.js';
+// ---------------------------------------------------------------------------
+// ClaimService
+// ---------------------------------------------------------------------------
+/**
+ * Manages the lifecycle of task claims in the Task Pool.
+ *
+ * Responsibilities:
+ * - Create claims when agents claim work items
+ * - Process heartbeats from agents to prove liveness
+ * - Extend leases when agents need more time
+ * - Release claims when agents finish or give up
+ * - Revoke claims when grace period is exceeded
+ * - Scan for expired claims (used by Reconciler)
+ *
+ * @example
+ * ```typescript
+ * const claimService = new ClaimService(storage);
+ *
+ * // Agent claims a work item
+ * const claim = await claimService.createClaim({
+ *   workItemId: 'wi-123',
+ *   agentId: 'agent-leo',
+ * });
+ *
+ * // Agent sends heartbeats periodically
+ * await claimService.heartbeat(claim.id, 'agent-leo');
+ *
+ * // Agent finishes
+ * await claimService.release(claim.id, 'completed');
+ * ```
+ */
+export class ClaimService {
+    storage;
+    logger;
+    constructor(storage) {
+        this.storage = storage;
+        this.logger = LoggerService.getInstance().createComponentLogger('ClaimService');
+    }
+    // -----------------------------------------------------------------------
+    // Claim Creation
+    // -----------------------------------------------------------------------
+    /**
+     * Creates a new claim for a work item.
+     *
+     * Validates input, checks for duplicate claims, and creates the claim
+     * with default or specified lease parameters.
+     *
+     * @param input - Claim creation parameters
+     * @returns The created TaskClaim
+     * @throws Error if input is invalid or work item already has an active claim
+     */
+    async createClaim(input) {
+        const errors = validateCreateClaimInput(input);
+        if (errors.length > 0) {
+            throw new Error(`Invalid claim input: ${errors.join('; ')}`);
+        }
+        // Check for existing active claim on the work item
+        const existingByItem = await this.storage.findActiveClaimByWorkItem(input.workItemId);
+        if (existingByItem) {
+            throw new Error(`WorkItem ${input.workItemId} already has an active claim (${existingByItem.id}) by agent ${existingByItem.agentId}`);
+        }
+        // Check if agent already has an active claim
+        const existingByAgent = await this.storage.findActiveClaimByAgent(input.agentId);
+        if (existingByAgent) {
+            throw new Error(`Agent ${input.agentId} already has an active claim (${existingByAgent.id}) on WorkItem ${existingByAgent.workItemId}`);
+        }
+        const claim = createTaskClaim(input);
+        await this.storage.addClaim(claim);
+        this.logger.info('Claim created', {
+            claimId: claim.id,
+            workItemId: input.workItemId,
+            agentId: input.agentId,
+            leaseExpiresAt: claim.leaseExpiresAt,
+        });
+        return claim;
+    }
+    // -----------------------------------------------------------------------
+    // Heartbeat
+    // -----------------------------------------------------------------------
+    /**
+     * Processes a heartbeat from an agent for a specific claim.
+     *
+     * Updates the lastHeartbeatAt timestamp. The heartbeat is only accepted
+     * if the claim is active and belongs to the requesting agent.
+     *
+     * @param claimId - The claim ID
+     * @param agentId - The agent sending the heartbeat (must match claim owner)
+     * @returns HeartbeatResult indicating success or failure
+     */
+    async heartbeat(claimId, agentId) {
+        const claims = await this.storage.getClaims();
+        const claim = claims.find((c) => c.id === claimId);
+        if (!claim) {
+            return { success: false, reason: `Claim not found: ${claimId}` };
+        }
+        if (claim.agentId !== agentId) {
+            return {
+                success: false,
+                reason: `Agent ${agentId} does not own claim ${claimId} (owned by ${claim.agentId})`,
+            };
+        }
+        if (claim.status !== 'active' && claim.status !== 'expiring') {
+            return {
+                success: false,
+                reason: `Cannot heartbeat claim in status '${claim.status}'`,
+            };
+        }
+        const now = new Date().toISOString();
+        const updated = await this.storage.updateClaim(claimId, (c) => {
+            c.lastHeartbeatAt = now;
+            // If claim was expiring but agent is alive, restore to active
+            // (only if lease hasn't been fully exceeded + grace)
+            if (c.status === 'expiring') {
+                c.status = 'active';
+            }
+        });
+        if (!updated) {
+            return { success: false, reason: `Failed to update claim ${claimId}` };
+        }
+        const updatedClaim = claims.find((c) => c.id === claimId);
+        this.logger.debug?.('Heartbeat received', { claimId, agentId });
+        return { success: true, claim: updatedClaim };
+    }
+    // -----------------------------------------------------------------------
+    // Lease Extension
+    // -----------------------------------------------------------------------
+    /**
+     * Extends the lease on a claim, giving the agent more time.
+     *
+     * Extension is only allowed if:
+     * - Claim is active
+     * - Extension count < maxExtensions
+     * - Agent owns the claim
+     *
+     * @param claimId - The claim ID
+     * @param agentId - The agent requesting extension (must match claim owner)
+     * @returns ExtendLeaseResult indicating success or failure
+     */
+    async extendLease(claimId, agentId) {
+        const claims = await this.storage.getClaims();
+        const claim = claims.find((c) => c.id === claimId);
+        if (!claim) {
+            return { success: false, reason: `Claim not found: ${claimId}` };
+        }
+        if (claim.agentId !== agentId) {
+            return {
+                success: false,
+                reason: `Agent ${agentId} does not own claim ${claimId}`,
+            };
+        }
+        if (!canExtendLease(claim)) {
+            const reason = claim.status !== 'active'
+                ? `Claim is in '${claim.status}' status, must be 'active'`
+                : `Max extensions reached (${claim.extensionCount}/${claim.maxExtensions})`;
+            return { success: false, reason };
+        }
+        const extended = extendClaim(claim);
+        if (!extended) {
+            return { success: false, reason: 'Extension failed (internal)' };
+        }
+        // Apply the extension to storage
+        await this.storage.updateClaim(claimId, (c) => {
+            c.leaseExpiresAt = extended.leaseExpiresAt;
+            c.lastHeartbeatAt = extended.lastHeartbeatAt;
+            c.extensionCount = extended.extensionCount;
+        });
+        const updatedClaim = claims.find((c) => c.id === claimId);
+        this.logger.info('Lease extended', {
+            claimId,
+            agentId,
+            extensionCount: updatedClaim.extensionCount,
+            newExpiresAt: updatedClaim.leaseExpiresAt,
+        });
+        return { success: true, claim: updatedClaim };
+    }
+    // -----------------------------------------------------------------------
+    // Release & Revoke
+    // -----------------------------------------------------------------------
+    /**
+     * Voluntarily releases a claim (agent finished or gave up).
+     *
+     * @param claimId - The claim ID to release
+     * @param reason - Why the claim is being released
+     * @throws Error if claim not found
+     */
+    async release(claimId, reason) {
+        const claims = await this.storage.getClaims();
+        const claim = claims.find((c) => c.id === claimId);
+        if (!claim) {
+            throw new Error(`Claim not found: ${claimId}`);
+        }
+        if (claim.status === 'released' || claim.status === 'revoked') {
+            this.logger.warn('Claim already ended, skipping release', {
+                claimId,
+                status: claim.status,
+            });
+            return;
+        }
+        const now = new Date().toISOString();
+        await this.storage.updateClaim(claimId, (c) => {
+            c.status = 'released';
+            c.endedAt = now;
+            c.endReason = reason;
+        });
+        this.logger.info('Claim released', { claimId, reason, agentId: claim.agentId });
+    }
+    /**
+     * Force-revokes a claim (system action when grace period exceeded).
+     *
+     * @param claimId - The claim ID to revoke
+     * @param reason - Why the claim is being revoked
+     * @throws Error if claim not found
+     */
+    async revoke(claimId, reason) {
+        const claims = await this.storage.getClaims();
+        const claim = claims.find((c) => c.id === claimId);
+        if (!claim) {
+            throw new Error(`Claim not found: ${claimId}`);
+        }
+        if (claim.status === 'revoked') {
+            this.logger.warn('Claim already revoked, skipping', { claimId });
+            return;
+        }
+        const now = new Date().toISOString();
+        await this.storage.updateClaim(claimId, (c) => {
+            c.status = 'revoked';
+            c.endedAt = now;
+            c.endReason = reason;
+        });
+        this.logger.info('Claim revoked', { claimId, reason, agentId: claim.agentId });
+    }
+    // -----------------------------------------------------------------------
+    // Expiry Detection (used by Reconciler)
+    // -----------------------------------------------------------------------
+    /**
+     * Scans all active claims and categorizes expired ones.
+     *
+     * Returns two lists:
+     * - `expiring`: lease expired but within grace period (should be marked 'expiring')
+     * - `graceExceeded`: past grace period (should be revoked and work item released)
+     *
+     * @param now - Current timestamp in ms (default: Date.now())
+     * @param gracePeriodMs - Grace period duration (default: DEFAULT_GRACE_PERIOD_MS)
+     * @returns Summary of expired claims
+     */
+    async scanExpiredClaims(now = Date.now(), gracePeriodMs = DEFAULT_GRACE_PERIOD_MS) {
+        const claims = await this.storage.getClaims();
+        const activeClaims = claims.filter((c) => c.status === 'active' || c.status === 'expiring');
+        const expiring = [];
+        const graceExceeded = [];
+        for (const claim of activeClaims) {
+            if (isGracePeriodExceeded(claim, gracePeriodMs, now)) {
+                graceExceeded.push(claim);
+            }
+            else if (isLeaseExpired(claim, now)) {
+                expiring.push(claim);
+            }
+        }
+        return { expiring, graceExceeded };
+    }
+    /**
+     * Marks claims as 'expiring' status (called by Reconciler fast loop).
+     *
+     * @param claimIds - IDs of claims to mark as expiring
+     */
+    async markExpiring(claimIds) {
+        for (const claimId of claimIds) {
+            await this.storage.updateClaim(claimId, (c) => {
+                if (c.status === 'active') {
+                    c.status = 'expiring';
+                }
+            });
+        }
+        this.logger.info('Claims marked as expiring', { count: claimIds.length });
+    }
+    // -----------------------------------------------------------------------
+    // Queries
+    // -----------------------------------------------------------------------
+    /**
+     * Gets an active claim for a specific agent.
+     *
+     * @param agentId - Agent session name
+     * @returns The active claim, or undefined
+     */
+    async getActiveClaimByAgent(agentId) {
+        return this.storage.findActiveClaimByAgent(agentId);
+    }
+    /**
+     * Gets an active claim for a specific work item.
+     *
+     * @param workItemId - The work item ID
+     * @returns The active claim, or undefined
+     */
+    async getActiveClaimByWorkItem(workItemId) {
+        return this.storage.findActiveClaimByWorkItem(workItemId);
+    }
+    /**
+     * Gets all active claims.
+     *
+     * @returns Array of active/expiring claims
+     */
+    async getActiveClaims() {
+        const claims = await this.storage.getClaims();
+        return claims.filter((c) => c.status === 'active' || c.status === 'expiring');
+    }
+    /**
+     * Gets a claim by ID.
+     *
+     * @param claimId - The claim ID
+     * @returns The claim, or undefined
+     */
+    async getClaimById(claimId) {
+        const claims = await this.storage.getClaims();
+        return claims.find((c) => c.id === claimId);
+    }
+    /**
+     * Checks whether an agent's heartbeat is stale (no heartbeat within expected interval).
+     *
+     * @param claim - The claim to check
+     * @param heartbeatIntervalMs - Expected heartbeat interval (default: 2min)
+     * @param toleranceMs - Additional tolerance before considering stale (default: 30s)
+     * @param now - Current timestamp in ms
+     * @returns True if the last heartbeat is older than interval + tolerance
+     */
+    isHeartbeatStale(claim, heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS, toleranceMs = 30_000, now = Date.now()) {
+        const lastHb = new Date(claim.lastHeartbeatAt).getTime();
+        return now - lastHb > heartbeatIntervalMs + toleranceMs;
+    }
+    // -----------------------------------------------------------------------
+    // Flush
+    // -----------------------------------------------------------------------
+    /**
+     * Flushes pending storage writes to disk.
+     */
+    async flush() {
+        await this.storage.flush();
+    }
+}
+//# sourceMappingURL=claim.service.js.map

package/dist/backend/backend/src/services/task-pool/claim.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim.service.js","sourceRoot":"","sources":["../../../../../../backend/src/services/task-pool/claim.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,aAAa,EAAwB,MAAM,2BAA2B,CAAC;AAChF,OAAO,EAIL,eAAe,EACf,WAAW,EACX,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,wBAAwB,EAExB,6BAA6B,EAC7B,uBAAuB,GAExB,MAAM,+BAA+B,CAAC;AAwCvC,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,YAAY;IACN,OAAO,CAAc;IACrB,MAAM,CAAkB;IAEzC,YAAY,OAAoB;QAC9B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,aAAa,CAAC,WAAW,EAAE,CAAC,qBAAqB,CAAC,cAAc,CAAC,CAAC;IAClF,CAAC;IAED,0EAA0E;IAC1E,iBAAiB;IACjB,0EAA0E;IAE1E;;;;;;;;;OASG;IACH,KAAK,CAAC,WAAW,CAAC,KAAuB;QACvC,MAAM,MAAM,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAAC;QAC/C,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,wBAAwB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC/D,CAAC;QAED,mDAAmD;QACnD,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,yBAAyB,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACtF,IAAI,cAAc,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,YAAY,KAAK,CAAC,UAAU,iCAAiC,cAAc,CAAC,EAAE,cAAc,cAAc,CAAC,OAAO,EAAE,CACrH,CAAC;QACJ,CAAC;QAED,6CAA6C;QAC7C,MAAM,eAAe,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,sBAAsB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACjF,IAAI,eAAe,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACb,SAAS,KAAK,CAAC,OAAO,iCAAiC,eAAe,CAAC,EAAE,iBAAiB,eAAe,CAAC,UAAU,EAAE,CACvH,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;QACrC,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAEnC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE;YAChC,OAAO,EAAE,KAAK,CAAC,EAAE;YACjB,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,cAAc,EAAE,KAAK,CAAC,cAAc;SACrC,CAAC,CAAC;QAEH,OAAO,KAAK,CAAC;IACf,CAAC;IAED,0EAA0E;IAC1E,YAAY;IACZ,0EAA0E;IAE1E;;;;;;;;;OASG;IACH,KAAK,CAAC,SAAS,CAAC,OAAe,EAAE,OAAe;QAC9C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC;QAEnD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,OAAO,EAAE,EAAE,CAAC;QACnE,CAAC;QAED,IAAI,KAAK,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;YAC9B,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,SAAS,OAAO,uBAAuB,OAAO,cAAc,KAAK,CAAC,OAAO,GAAG;aACrF,CAAC;QACJ,CAAC;QAED,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YAC7D,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,qCAAqC,KAAK,CAAC,MAAM,GAAG;aAC7D,CAAC;QACJ,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE;YAC5D,CAAC,CAAC,eAAe,GAAG,GAAG,CAAC;YACxB,8DAA8D;YAC9D,qDAAqD;YACrD,IAAI,CAAC,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;gBAC5B,CAAC,CAAC,MAAM,GAAG,QAAQ,CAAC;YACtB,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,0BAA0B,OAAO,EAAE,EAAE,CAAC;QACzE,CAAC;QAED,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,CAAE,CAAC;QAC3D,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,oBAAoB,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QAEhE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;IAChD,CAAC;IAED,0EAA0E;IAC1E,kBAAkB;IAClB,0EAA0E;IAE1E;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,WAAW,CAAC,OAAe,EAAE,OAAe;QAChD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC;QAEnD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,OAAO,EAAE,EAAE,CAAC;QACnE,CAAC;QAED,IAAI,KAAK,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;YAC9B,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,SAAS,OAAO,uBAAuB,OAAO,EAAE;aACzD,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,MAAM,GACV,KAAK,CAAC,MAAM,KAAK,QAAQ;gBACvB,CAAC,CAAC,gBAAgB,KAAK,CAAC,MAAM,4BAA4B;gBAC1D,CAAC,CAAC,2BAA2B,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,aAAa,GAAG,CAAC;YAChF,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QACpC,CAAC;QAED,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,6BAA6B,EAAE,CAAC;QACnE,CAAC;QAED,iCAAiC;QACjC,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE;YAC5C,CAAC,CAAC,cAAc,GAAG,QAAQ,CAAC,cAAc,CAAC;YAC3C,CAAC,CAAC,eAAe,GAAG,QAAQ,CAAC,eAAe,CAAC;YAC7C,CAAC,CAAC,cAAc,GAAG,QAAQ,CAAC,cAAc,CAAC;QAC7C,CAAC,CAAC,CAAC;QAEH,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,CAAE,CAAC;QAC3D,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE;YACjC,OAAO;YACP,OAAO;YACP,cAAc,EAAE,YAAY,CAAC,cAAc;YAC3C,YAAY,EAAE,YAAY,CAAC,cAAc;SAC1C,CAAC,CAAC;QAEH,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;IAChD,CAAC;IAED,0EAA0E;IAC1E,mBAAmB;IACnB,0EAA0E;IAE1E;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,OAAe,EAAE,MAAc;QAC3C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC;QAEnD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;QACjD,CAAC;QAED,IAAI,KAAK,CAAC,MAAM,KAAK,UAAU,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC9D,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,uCAAuC,EAAE;gBACxD,OAAO;gBACP,MAAM,EAAE,KAAK,CAAC,MAAM;aACrB,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE;YAC5C,CAAC,CAAC,MAAM,GAAG,UAAU,CAAC;YACtB,CAAC,CAAC,OAAO,GAAG,GAAG,CAAC;YAChB,CAAC,CAAC,SAAS,GAAG,MAAM,CAAC;QACvB,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAClF,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,CAAC,OAAe,EAAE,MAAc;QAC1C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC;QAEnD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;QACjD,CAAC;QAED,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,iCAAiC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;YACjE,OAAO;QACT,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE;YAC5C,CAAC,CAAC,MAAM,GAAG,SAAS,CAAC;YACrB,CAAC,CAAC,OAAO,GAAG,GAAG,CAAC;YAChB,CAAC,CAAC,SAAS,GAAG,MAAM,CAAC;QACvB,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IACjF,CAAC;IAED,0EAA0E;IAC1E,wCAAwC;IACxC,0EAA0E;IAE1E;;;;;;;;;;OAUG;IACH,KAAK,CAAC,iBAAiB,CACrB,MAAc,IAAI,CAAC,GAAG,EAAE,EACxB,gBAAwB,uBAAuB;QAE/C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QAC9C,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAChC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,UAAU,CACxD,CAAC;QAEF,MAAM,QAAQ,GAAgB,EAAE,CAAC;QACjC,MAAM,aAAa,GAAgB,EAAE,CAAC;QAEtC,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;YACjC,IAAI,qBAAqB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,CAAC,EAAE,CAAC;gBACrD,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC5B,CAAC;iBAAM,IAAI,cAAc,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC;gBACtC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;QAED,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC;IACrC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,YAAY,CAAC,QAAkB;QACnC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE;gBAC5C,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;oBAC1B,CAAC,CAAC,MAAM,GAAG,UAAU,CAAC;gBACxB,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,2BAA2B,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED,0EAA0E;IAC1E,UAAU;IACV,0EAA0E;IAE1E;;;;;OAKG;IACH,KAAK,CAAC,qBAAqB,CAAC,OAAe;QACzC,OAAO,IAAI,CAAC,OAAO,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC;IACtD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,wBAAwB,CAAC,UAAkB;QAC/C,OAAO,IAAI,CAAC,OAAO,CAAC,yBAAyB,CAAC,UAAU,CAAC,CAAC;IAC5D,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,eAAe;QACnB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QAC9C,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC;IAChF,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,YAAY,CAAC,OAAe;QAChC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QAC9C,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED;;;;;;;;OAQG;IACH,gBAAgB,CACd,KAAgB,EAChB,sBAA8B,6BAA6B,EAC3D,cAAsB,MAAM,EAC5B,MAAc,IAAI,CAAC,GAAG,EAAE;QAExB,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,OAAO,EAAE,CAAC;QACzD,OAAO,GAAG,GAAG,MAAM,GAAG,mBAAmB,GAAG,WAAW,CAAC;IAC1D,CAAC;IAED,0EAA0E;IAC1E,QAAQ;IACR,0EAA0E;IAE1E;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IAC7B,CAAC;CACF"}

package/dist/backend/backend/src/services/task-pool/pool-storage.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Pool Storage — JSON file persistence for Task Pool
+ *
+ * Handles reading and writing the task pool state to disk using
+ * atomic writes (temp-file + fsync + rename) and operation locks
+ * to prevent corruption on crash or concurrent access.
+ *
+ * @module services/task-pool/pool-storage
+ */
+import type { WorkItem } from '../../types/v2/work-item.types.js';
+import type { TaskClaim } from '../../types/v2/claim.types.js';
+/**
+ * On-disk shape of the pool data file.
+ */
+export interface PoolData {
+    /** All work items currently in the pool */
+    workItems: WorkItem[];
+    /** All active and historical claims */
+    claims: TaskClaim[];
+    /** ISO8601 — last time the file was written */
+    lastUpdatedAt: string;
+}
+/**
+ * Options for PoolStorage construction.
+ */
+export interface PoolStorageOptions {
+    /** Override the default data directory (defaults to ~/.crewly/task-pool/) */
+    dataDir?: string;
+}
+/**
+ * Persists task pool state to a JSON file with atomic writes.
+ *
+ * Uses the same patterns as the rest of the Crewly backend:
+ * - {@link atomicWriteJson} for crash-safe writes
+ * - {@link modifyJsonFile} for locked read-modify-write cycles
+ * - Debounced flushing to reduce disk I/O under burst writes
+ */
+export declare class PoolStorage {
+    private readonly filePath;
+    private readonly logger;
+    /** In-memory cache — authoritative after first load. */
+    private cache;
+    /** Debounce timer handle for batching writes. */
+    private flushTimer;
+    /** Whether a flush is pending. */
+    private dirty;
+    constructor(options?: PoolStorageOptions);
+    /**
+     * Loads pool data from disk (or returns cached copy).
+     *
+     * @returns Current pool data
+     */
+    load(): Promise<PoolData>;
+    /**
+     * Returns all work items currently in the pool.
+     *
+     * @returns Array of WorkItems
+     */
+    getWorkItems(): Promise<WorkItem[]>;
+    /**
+     * Returns all claims.
+     *
+     * @returns Array of TaskClaims
+     */
+    getClaims(): Promise<TaskClaim[]>;
+    /**
+     * Finds a work item by ID.
+     *
+     * @param workItemId - The work item ID
+     * @returns The work item, or undefined
+     */
+    findWorkItem(workItemId: string): Promise<WorkItem | undefined>;
+    /**
+     * Finds a claim by work item ID (active claims only).
+     *
+     * @param workItemId - The work item ID
+     * @returns The active claim, or undefined
+     */
+    findActiveClaimByWorkItem(workItemId: string): Promise<TaskClaim | undefined>;
+    /**
+     * Finds a claim by agent ID (active claims only).
+     *
+     * @param agentId - The agent session name
+     * @returns The active claim, or undefined
+     */
+    findActiveClaimByAgent(agentId: string): Promise<TaskClaim | undefined>;
+    /**
+     * Adds a work item to the pool.
+     *
+     * @param workItem - The work item to add
+     */
+    addWorkItem(workItem: WorkItem): Promise<void>;
+    /**
+     * Updates a work item in-place.
+     *
+     * @param workItemId - ID of the work item to update
+     * @param updater - Function that mutates the work item
+     * @returns True if item was found and updated
+     */
+    updateWorkItem(workItemId: string, updater: (wi: WorkItem) => void): Promise<boolean>;
+    /**
+     * Removes a work item from the pool.
+     *
+     * @param workItemId - ID of the work item to remove
+     * @returns True if item was found and removed
+     */
+    removeWorkItem(workItemId: string): Promise<boolean>;
+    /**
+     * Adds a claim to storage.
+     *
+     * @param claim - The claim to add
+     */
+    addClaim(claim: TaskClaim): Promise<void>;
+    /**
+     * Updates a claim in-place.
+     *
+     * @param claimId - ID of the claim to update
+     * @param updater - Function that mutates the claim
+     * @returns True if claim was found and updated
+     */
+    updateClaim(claimId: string, updater: (claim: TaskClaim) => void): Promise<boolean>;
+    /**
+     * Forces an immediate flush to disk (bypasses debounce).
+     * Call this during graceful shutdown.
+     */
+    flush(): Promise<void>;
+    /**
+     * Clears all pool data (useful for testing).
+     */
+    clear(): Promise<void>;
+    /**
+     * Cleanup: cancels pending debounce timer and flushes.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Marks cache as dirty and schedules a debounced flush.
+     */
+    private markDirty;
+}
+/**
+ * Creates an empty pool data structure.
+ *
+ * @returns Empty PoolData
+ */
+export declare function createEmptyPoolData(): PoolData;
+//# sourceMappingURL=pool-storage.d.ts.map

package/dist/backend/backend/src/services/task-pool/pool-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool-storage.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/task-pool/pool-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAO/D;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,2CAA2C;IAC3C,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,uCAAuC;IACvC,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAmBD;;;;;;;GAOG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC,wDAAwD;IACxD,OAAO,CAAC,KAAK,CAAyB;IAEtC,iDAAiD;IACjD,OAAO,CAAC,UAAU,CAA+B;IAEjD,kCAAkC;IAClC,OAAO,CAAC,KAAK,CAAS;gBAEV,OAAO,CAAC,EAAE,kBAAkB;IAYxC;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC;IAa/B;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAKzC;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAKvC;;;;;OAKG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAKrE;;;;;OAKG;IACG,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAOnF;;;;;OAKG;IACG,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAO7E;;;;OAIG;IACG,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpD;;;;;;OAMG;IACG,cAAc,CAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,CAAC,EAAE,EAAE,QAAQ,KAAK,IAAI,GAC9B,OAAO,CAAC,OAAO,CAAC;IASnB;;;;;OAKG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAS1D;;;;OAIG;IACG,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAM/C;;;;;;OAMG;IACG,WAAW,CACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,GAClC,OAAO,CAAC,OAAO,CAAC;IASnB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAa5B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B;;OAEG;IACH,OAAO,CAAC,SAAS;CAUlB;AAMD;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,QAAQ,CAM9C"}