crewly 1.5.18 → 1.5.20

package/dist/backend/backend/src/services/task-pool/pool-storage.js

@@ -0,0 +1,243 @@
+/**
+ * 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 * as path from 'path';
+import * as os from 'os';
+import { ensureDir, safeReadJson, atomicWriteJson, } from '../../utils/file-io.utils.js';
+import { LoggerService } from '../core/logger.service.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default directory name under ~/.crewly/ for pool data. */
+const POOL_DIR_NAME = 'task-pool';
+/** File name for the pool data. */
+const POOL_FILE_NAME = 'pool.json';
+/** Debounce interval in ms for write batching. */
+const WRITE_DEBOUNCE_MS = 500;
+// ---------------------------------------------------------------------------
+// PoolStorage
+// ---------------------------------------------------------------------------
+/**
+ * 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 class PoolStorage {
+    filePath;
+    logger;
+    /** In-memory cache — authoritative after first load. */
+    cache = null;
+    /** Debounce timer handle for batching writes. */
+    flushTimer = null;
+    /** Whether a flush is pending. */
+    dirty = false;
+    constructor(options) {
+        const dataDir = options?.dataDir ??
+            path.join(os.homedir(), '.crewly', POOL_DIR_NAME);
+        this.filePath = path.join(dataDir, POOL_FILE_NAME);
+        this.logger = LoggerService.getInstance().createComponentLogger('PoolStorage');
+    }
+    // -----------------------------------------------------------------------
+    // Public API
+    // -----------------------------------------------------------------------
+    /**
+     * Loads pool data from disk (or returns cached copy).
+     *
+     * @returns Current pool data
+     */
+    async load() {
+        if (this.cache)
+            return this.cache;
+        await ensureDir(path.dirname(this.filePath));
+        const data = await safeReadJson(this.filePath, createEmptyPoolData(), this.logger);
+        this.cache = data;
+        return data;
+    }
+    /**
+     * Returns all work items currently in the pool.
+     *
+     * @returns Array of WorkItems
+     */
+    async getWorkItems() {
+        const data = await this.load();
+        return data.workItems;
+    }
+    /**
+     * Returns all claims.
+     *
+     * @returns Array of TaskClaims
+     */
+    async getClaims() {
+        const data = await this.load();
+        return data.claims;
+    }
+    /**
+     * Finds a work item by ID.
+     *
+     * @param workItemId - The work item ID
+     * @returns The work item, or undefined
+     */
+    async findWorkItem(workItemId) {
+        const data = await this.load();
+        return data.workItems.find((wi) => wi.id === workItemId);
+    }
+    /**
+     * Finds a claim by work item ID (active claims only).
+     *
+     * @param workItemId - The work item ID
+     * @returns The active claim, or undefined
+     */
+    async findActiveClaimByWorkItem(workItemId) {
+        const data = await this.load();
+        return data.claims.find((c) => c.workItemId === workItemId && c.status === 'active');
+    }
+    /**
+     * Finds a claim by agent ID (active claims only).
+     *
+     * @param agentId - The agent session name
+     * @returns The active claim, or undefined
+     */
+    async findActiveClaimByAgent(agentId) {
+        const data = await this.load();
+        return data.claims.find((c) => c.agentId === agentId && c.status === 'active');
+    }
+    /**
+     * Adds a work item to the pool.
+     *
+     * @param workItem - The work item to add
+     */
+    async addWorkItem(workItem) {
+        const data = await this.load();
+        data.workItems.push(workItem);
+        this.markDirty();
+    }
+    /**
+     * 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
+     */
+    async updateWorkItem(workItemId, updater) {
+        const data = await this.load();
+        const item = data.workItems.find((wi) => wi.id === workItemId);
+        if (!item)
+            return false;
+        updater(item);
+        this.markDirty();
+        return true;
+    }
+    /**
+     * Removes a work item from the pool.
+     *
+     * @param workItemId - ID of the work item to remove
+     * @returns True if item was found and removed
+     */
+    async removeWorkItem(workItemId) {
+        const data = await this.load();
+        const idx = data.workItems.findIndex((wi) => wi.id === workItemId);
+        if (idx === -1)
+            return false;
+        data.workItems.splice(idx, 1);
+        this.markDirty();
+        return true;
+    }
+    /**
+     * Adds a claim to storage.
+     *
+     * @param claim - The claim to add
+     */
+    async addClaim(claim) {
+        const data = await this.load();
+        data.claims.push(claim);
+        this.markDirty();
+    }
+    /**
+     * 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
+     */
+    async updateClaim(claimId, updater) {
+        const data = await this.load();
+        const claim = data.claims.find((c) => c.id === claimId);
+        if (!claim)
+            return false;
+        updater(claim);
+        this.markDirty();
+        return true;
+    }
+    /**
+     * Forces an immediate flush to disk (bypasses debounce).
+     * Call this during graceful shutdown.
+     */
+    async flush() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        if (!this.dirty || !this.cache)
+            return;
+        this.cache.lastUpdatedAt = new Date().toISOString();
+        await atomicWriteJson(this.filePath, this.cache);
+        this.dirty = false;
+        this.logger.debug?.('Pool data flushed to disk', { path: this.filePath });
+    }
+    /**
+     * Clears all pool data (useful for testing).
+     */
+    async clear() {
+        this.cache = createEmptyPoolData();
+        this.dirty = true;
+        await this.flush();
+    }
+    /**
+     * Cleanup: cancels pending debounce timer and flushes.
+     */
+    async destroy() {
+        await this.flush();
+    }
+    // -----------------------------------------------------------------------
+    // Internal
+    // -----------------------------------------------------------------------
+    /**
+     * Marks cache as dirty and schedules a debounced flush.
+     */
+    markDirty() {
+        this.dirty = true;
+        if (this.flushTimer)
+            return; // already scheduled
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            this.flush().catch((err) => {
+                this.logger.warn('Failed to flush pool data', { error: String(err) });
+            });
+        }, WRITE_DEBOUNCE_MS);
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Creates an empty pool data structure.
+ *
+ * @returns Empty PoolData
+ */
+export function createEmptyPoolData() {
+    return {
+        workItems: [],
+        claims: [],
+        lastUpdatedAt: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=pool-storage.js.map

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

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

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

@@ -0,0 +1,288 @@
+/**
+ * Task Pool Service — Unified task entry and queue management
+ *
+ * The Task Pool holds execution-ready WorkItems. Agents claim items
+ * from the pool, and the Reconciler returns unclaimed or failed items.
+ *
+ * CEO Decision: Pool only holds execution-ready WorkItems, not all ProjectTasks.
+ *
+ * @module services/task-pool/task-pool.service
+ */
+import { PoolStorage } from './pool-storage.js';
+import { ClaimService, type HeartbeatResult, type ExtendLeaseResult, type ExpiredClaimsSummary } from './claim.service.js';
+import type { WorkItem, WorkItemStatus, WorkItemType, WorkItemOwner } from '../../types/v2/work-item.types.js';
+import { type TaskClaim } from '../../types/v2/claim.types.js';
+/**
+ * Filters for claiming work items from the pool.
+ */
+export interface PoolFilters {
+    /** Only match items of these types */
+    types?: WorkItemType[];
+    /** Only match items with this owner role */
+    owner?: WorkItemOwner;
+    /** Only match items targeting a specific agent/team */
+    target?: string;
+    /** Only match items belonging to this mission */
+    missionId?: string;
+}
+/**
+ * Statistics snapshot of the pool's current state.
+ */
+export interface PoolSnapshot {
+    /** Total items in the pool (all statuses) */
+    total: number;
+    /** Items available for claiming (queued, no active claim) */
+    available: number;
+    /** Items currently claimed by an agent */
+    claimed: number;
+    /** Average wait time in ms for items that have been claimed */
+    avgWaitTimeMs: number;
+    /** Breakdown by WorkItem type */
+    byType: Record<string, number>;
+    /** Breakdown by status */
+    byStatus: Record<string, number>;
+    /** ISO8601 timestamp of this snapshot */
+    timestamp: string;
+}
+/**
+ * Result returned when claiming a work item.
+ */
+export interface ClaimResult {
+    /** The claimed work item */
+    workItem: WorkItem;
+    /** The claim object tracking the lease */
+    claim: TaskClaim;
+}
+/**
+ * TaskPoolService manages the lifecycle of execution-ready WorkItems.
+ *
+ * Core operations:
+ * - {@link addToPool} — enqueue an execution-ready WorkItem
+ * - {@link claimFromPool} — agent claims the next available item
+ * - {@link releaseBack} — release a claimed item back to the pool
+ * - {@link getPoolStatus} — snapshot of pool statistics
+ *
+ * @example
+ * ```typescript
+ * const pool = TaskPoolService.getInstance();
+ * pool.addToPool(workItem);
+ * const result = pool.claimFromPool('agent-leo', { types: ['delegate'] });
+ * if (result) {
+ *   // agent works on result.workItem
+ *   // when done:
+ *   pool.completeItem(result.workItem.id);
+ * }
+ * ```
+ */
+export declare class TaskPoolService {
+    private static instance;
+    private readonly storage;
+    private readonly claimService;
+    private readonly logger;
+    /**
+     * Serializes claim operations to prevent the race where two concurrent
+     * claimFromPool / claimSpecificItem calls both select the same queued
+     * WorkItem between their read and write phases. In-process only — does
+     * not protect against cross-process races, but the backend runs as a
+     * single process today.
+     */
+    private claimMutex;
+    constructor(storage?: PoolStorage);
+    /**
+     * Chains the given critical section after any in-flight claim operation.
+     * Guarantees FIFO ordering even under concurrent invocation.
+     */
+    private withClaimLock;
+    /**
+     * Get singleton instance of TaskPoolService.
+     *
+     * @returns The singleton TaskPoolService
+     */
+    static getInstance(): TaskPoolService;
+    /**
+     * Reset singleton (for testing).
+     */
+    static resetInstance(): void;
+    /**
+     * Adds an execution-ready WorkItem to the pool.
+     *
+     * Accepted statuses:
+     * - `queued`  — ready to run
+     * - `blocked` — waiting on unresolved dependsOn; the resolver will promote
+     *               it to `queued` when every upstream dep reaches terminal success.
+     *
+     * @param workItem - The work item to add
+     * @throws Error if workItem is invalid or in an ineligible status
+     */
+    addToPool(workItem: WorkItem): Promise<void>;
+    /**
+     * Claims the next available WorkItem from the pool for an agent.
+     *
+     * Selection strategy: FIFO among matching unclaimed 'queued' items.
+     * If a target filter is provided, only items targeting that agent are considered.
+     *
+     * @param agentId - Agent session name claiming the item
+     * @param filters - Optional filters to narrow which items to consider
+     * @returns The claimed work item and claim object, or null if nothing available
+     */
+    claimFromPool(agentId: string, filters?: PoolFilters): Promise<ClaimResult | null>;
+    /**
+     * Claims a specific WorkItem by ID for an agent.
+     * Used by AgentAutoClaimService for score-based selection where the caller
+     * already identified the best item (not FIFO).
+     *
+     * @param agentId - Agent session name claiming the item
+     * @param workItemId - The specific WorkItem to claim
+     * @returns The claimed work item and claim, or null if unavailable
+     */
+    claimSpecificItem(agentId: string, workItemId: string): Promise<ClaimResult | null>;
+    /**
+     * Releases a claimed WorkItem back to the pool.
+     *
+     * The item's status reverts to 'queued' and the claim is marked 'released'.
+     *
+     * @param workItemId - ID of the work item to release
+     * @param reason - Why the item is being released
+     * @throws Error if work item not found or not currently claimed
+     */
+    releaseBack(workItemId: string, reason: string): Promise<void>;
+    /**
+     * Marks a work item as completed ('done').
+     *
+     * @param workItemId - ID of the work item
+     * @param result - Optional result data
+     * @throws Error if work item not found or not in 'running' status
+     */
+    completeItem(workItemId: string, result?: Record<string, unknown>): Promise<void>;
+    /**
+     * Scans blocked WorkItems that list `completedId` in their `dependsOn` and
+     * promotes each to `queued` if every one of their deps has reached terminal
+     * success (`done` or `verified`). Idempotent and safe to call on any terminal
+     * success transition.
+     *
+     * Serialized via the claim mutex — a concurrent claimFromPool call must not
+     * observe a half-promoted item.
+     */
+    resolveBlockedDependents(completedId: string): Promise<void>;
+    /**
+     * Marks a work item as failed.
+     *
+     * @param workItemId - ID of the work item
+     * @param error - Error description
+     * @throws Error if work item not found or not in 'running' status
+     */
+    failItem(workItemId: string, error: string): Promise<void>;
+    /**
+     * Processes a heartbeat from an agent for their active claim.
+     *
+     * @param claimId - The claim ID
+     * @param agentId - The agent sending the heartbeat
+     * @returns HeartbeatResult
+     */
+    heartbeat(claimId: string, agentId: string): Promise<HeartbeatResult>;
+    /**
+     * Extends the lease on a claim.
+     *
+     * @param claimId - The claim ID
+     * @param agentId - The agent requesting extension
+     * @returns ExtendLeaseResult
+     */
+    extendLease(claimId: string, agentId: string): Promise<ExtendLeaseResult>;
+    /**
+     * Scans for expired claims (for Reconciler use).
+     *
+     * @param now - Current timestamp in ms
+     * @returns Summary of expiring and grace-exceeded claims
+     */
+    scanExpiredClaims(now?: number): Promise<ExpiredClaimsSummary>;
+    /**
+     * Revokes a claim and releases the work item back to the pool.
+     * Used by the Reconciler when a claim's grace period is exceeded.
+     *
+     * @param claimId - The claim to revoke
+     * @param reason - Reason for revocation
+     */
+    revokeAndRelease(claimId: string, reason: string): Promise<void>;
+    /**
+     * Exposes the underlying ClaimService for advanced operations.
+     *
+     * @returns The ClaimService instance
+     */
+    getClaimService(): ClaimService;
+    /**
+     * Returns a snapshot of pool statistics.
+     *
+     * @returns Pool statistics including counts and avg wait time
+     */
+    getPoolStatus(): Promise<PoolSnapshot>;
+    /**
+     * Returns all available (unclaimed, queued) work items.
+     *
+     * @param filters - Optional filters
+     * @returns Array of available WorkItems
+     */
+    getAvailableItems(filters?: PoolFilters): Promise<WorkItem[]>;
+    /**
+     * Returns all work items in the pool (all statuses).
+     *
+     * @returns Array of all WorkItems
+     */
+    getAllItems(): Promise<WorkItem[]>;
+    /**
+     * Removes a WorkItem from the pool entirely.
+     * Used for purging old completed/cancelled items.
+     *
+     * @param workItemId - ID of the item to remove
+     */
+    removeItem(workItemId: string): Promise<void>;
+    /**
+     * Forces an immediate flush of pool data to disk.
+     * Called during graceful shutdown to prevent data loss.
+     */
+    flush(): Promise<void>;
+    /**
+     * Returns all active/expiring claims.
+     * Used by the Reconciler to check lease health.
+     *
+     * @returns Array of active/expiring TaskClaims
+     */
+    getActiveClaims(): Promise<TaskClaim[]>;
+    /**
+     * Updates a work item's status directly.
+     * Used by the Reconciler for corrections (e.g., stuck → blocked).
+     *
+     * @param workItemId - The work item ID
+     * @param newStatus - The target status
+     * @throws Error if work item not found or transition is invalid
+     */
+    updateItemStatus(workItemId: string, newStatus: WorkItemStatus): Promise<void>;
+    /**
+     * Update token usage and cost on a WorkItem.
+     * Called after task completion when token data is available from TokenUsageService.
+     *
+     * @param workItemId - The work item ID
+     * @param inputTokens - Number of input tokens consumed
+     * @param outputTokens - Number of output tokens generated
+     * @param cost - Total cost in USD
+     * @returns True if the update was applied, false if WorkItem not found
+     */
+    updateTokenUsage(workItemId: string, inputTokens: number, outputTokens: number, cost: number): Promise<boolean>;
+    /**
+     * Marks a claim as 'expiring' (lease expired, within grace period).
+     * Used by the Reconciler fast loop.
+     *
+     * @param claimId - The claim ID to mark
+     */
+    markClaimExpiring(claimId: string): Promise<void>;
+    /**
+     * Graceful shutdown — flush pending writes.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Exposes underlying storage for advanced operations (e.g., Reconciler).
+     *
+     * @returns The PoolStorage instance
+     */
+    getStorage(): PoolStorage;
+}
+//# sourceMappingURL=task-pool.service.d.ts.map

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

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