crewly 1.2.3 → 1.2.4

package/dist/backend/backend/src/services/cloud/cloud-task.service.js

@@ -0,0 +1,265 @@
+/**
+ * Cloud Task Service
+ *
+ * Manages the lifecycle of cloud tasks submitted by customers:
+ * creation, queuing, processing via AI runtime, and result storage.
+ *
+ * MVP implementation uses an in-memory queue with file-based persistence.
+ * Future: migrate to Redis/BullMQ for production scale.
+ *
+ * @module services/cloud/cloud-task.service
+ */
+import { randomUUID } from 'node:crypto';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { LoggerService } from '../core/logger.service.js';
+import { CLOUD_TASK_STATUSES, } from '../../controllers/cloud/tasks/cloud-task.types.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Cloud task service configuration. */
+export const CLOUD_TASK_CONSTANTS = {
+    /** Storage directory under ~/.crewly/ */
+    STORAGE_DIR: 'cloud/tasks',
+    /** Task data file */
+    TASKS_FILE: 'tasks.json',
+    /** Maximum tasks returned per list query */
+    DEFAULT_PAGE_SIZE: 20,
+    /** Maximum allowed page size */
+    MAX_PAGE_SIZE: 100,
+    /** Maximum pending tasks per user (cost control) */
+    MAX_PENDING_PER_USER: 50,
+    /** Task processing timeout (ms) — 5 minutes */
+    PROCESSING_TIMEOUT_MS: 300_000,
+};
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+/**
+ * Manages cloud task CRUD, queuing, and processing.
+ *
+ * Singleton — access via `CloudTaskService.getInstance()`.
+ */
+export class CloudTaskService {
+    static instance = null;
+    logger;
+    storageDir;
+    tasksFilePath;
+    tasks = new Map();
+    initialized = false;
+    constructor() {
+        this.logger = LoggerService.getInstance().createComponentLogger('CloudTaskService');
+        this.storageDir = join(homedir(), '.crewly', CLOUD_TASK_CONSTANTS.STORAGE_DIR);
+        this.tasksFilePath = join(this.storageDir, CLOUD_TASK_CONSTANTS.TASKS_FILE);
+    }
+    /** Get singleton instance. */
+    static getInstance() {
+        if (!CloudTaskService.instance) {
+            CloudTaskService.instance = new CloudTaskService();
+        }
+        return CloudTaskService.instance;
+    }
+    /** Reset singleton (for testing). */
+    static resetInstance() {
+        CloudTaskService.instance = null;
+    }
+    // -----------------------------------------------------------------------
+    // Initialization
+    // -----------------------------------------------------------------------
+    /**
+     * Initialize the service — load persisted tasks from disk.
+     * Idempotent: safe to call multiple times.
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        try {
+            await mkdir(this.storageDir, { recursive: true });
+            const raw = await readFile(this.tasksFilePath, 'utf-8').catch(() => '[]');
+            const parsed = JSON.parse(raw);
+            for (const task of parsed) {
+                this.tasks.set(task.id, task);
+            }
+            this.logger.info(`Loaded ${this.tasks.size} tasks from disk`);
+        }
+        catch (err) {
+            this.logger.warn('Failed to load tasks, starting fresh', { error: String(err) });
+            this.tasks = new Map();
+        }
+        this.initialized = true;
+    }
+    // -----------------------------------------------------------------------
+    // CRUD Operations
+    // -----------------------------------------------------------------------
+    /**
+     * Create a new cloud task.
+     *
+     * @param userId - Authenticated user ID
+     * @param type - Task type (text, image_analysis, document)
+     * @param prompt - User instruction / prompt
+     * @param files - Attached file keys (DO Spaces object keys)
+     * @returns The created task
+     * @throws Error if user exceeds pending task limit
+     */
+    async createTask(userId, type, prompt, files = []) {
+        await this.initialize();
+        // Enforce per-user pending limit
+        const pendingCount = this.countUserPendingTasks(userId);
+        if (pendingCount >= CLOUD_TASK_CONSTANTS.MAX_PENDING_PER_USER) {
+            throw new Error(`Task limit reached: you have ${pendingCount} pending tasks. ` +
+                `Maximum is ${CLOUD_TASK_CONSTANTS.MAX_PENDING_PER_USER}.`);
+        }
+        const now = new Date().toISOString();
+        const task = {
+            id: randomUUID(),
+            userId,
+            type,
+            prompt,
+            files,
+            status: CLOUD_TASK_STATUSES.PENDING,
+            result: null,
+            error: null,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.tasks.set(task.id, task);
+        await this.persist();
+        this.logger.info('Task created', { taskId: task.id, userId, type });
+        return task;
+    }
+    /**
+     * Get a single task by ID, scoped to the requesting user.
+     *
+     * @param taskId - Task UUID
+     * @param userId - Authenticated user ID (ownership check)
+     * @returns The task or null if not found / not owned
+     */
+    async getTask(taskId, userId) {
+        await this.initialize();
+        const task = this.tasks.get(taskId);
+        if (!task || task.userId !== userId)
+            return null;
+        return task;
+    }
+    /**
+     * List tasks for a user, with optional status filter and pagination.
+     *
+     * @param userId - Authenticated user ID
+     * @param options - Filter and pagination options
+     * @returns Paginated task list with total count
+     */
+    async listTasks(userId, options = {}) {
+        await this.initialize();
+        const limit = Math.min(options.limit ?? CLOUD_TASK_CONSTANTS.DEFAULT_PAGE_SIZE, CLOUD_TASK_CONSTANTS.MAX_PAGE_SIZE);
+        const offset = options.offset ?? 0;
+        let userTasks = Array.from(this.tasks.values())
+            .filter((t) => t.userId === userId);
+        if (options.status) {
+            userTasks = userTasks.filter((t) => t.status === options.status);
+        }
+        // Sort newest first
+        userTasks.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+        const total = userTasks.length;
+        const tasks = userTasks.slice(offset, offset + limit);
+        return { tasks, total };
+    }
+    // -----------------------------------------------------------------------
+    // Task Lifecycle
+    // -----------------------------------------------------------------------
+    /**
+     * Dequeue the next pending task for processing.
+     *
+     * @returns The oldest pending task, or null if queue is empty
+     */
+    async dequeueNext() {
+        await this.initialize();
+        const pending = Array.from(this.tasks.values())
+            .filter((t) => t.status === CLOUD_TASK_STATUSES.PENDING)
+            .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+        if (pending.length === 0)
+            return null;
+        const task = pending[0];
+        task.status = CLOUD_TASK_STATUSES.PROCESSING;
+        task.updatedAt = new Date().toISOString();
+        await this.persist();
+        this.logger.info('Task dequeued for processing', { taskId: task.id, type: task.type });
+        return task;
+    }
+    /**
+     * Mark a task as completed with a result.
+     *
+     * @param taskId - Task UUID
+     * @param result - AI-generated result content
+     */
+    async completeTask(taskId, result) {
+        await this.initialize();
+        const task = this.tasks.get(taskId);
+        if (!task)
+            throw new Error(`Task not found: ${taskId}`);
+        task.status = CLOUD_TASK_STATUSES.COMPLETED;
+        task.result = result;
+        task.updatedAt = new Date().toISOString();
+        await this.persist();
+        this.logger.info('Task completed', { taskId, userId: task.userId });
+    }
+    /**
+     * Mark a task as failed with an error message.
+     *
+     * @param taskId - Task UUID
+     * @param error - Error description
+     */
+    async failTask(taskId, error) {
+        await this.initialize();
+        const task = this.tasks.get(taskId);
+        if (!task)
+            throw new Error(`Task not found: ${taskId}`);
+        task.status = CLOUD_TASK_STATUSES.FAILED;
+        task.error = error;
+        task.updatedAt = new Date().toISOString();
+        await this.persist();
+        this.logger.warn('Task failed', { taskId, userId: task.userId, error });
+    }
+    /**
+     * Get queue statistics.
+     *
+     * @returns Counts by status
+     */
+    async getQueueStats() {
+        await this.initialize();
+        const stats = {
+            [CLOUD_TASK_STATUSES.PENDING]: 0,
+            [CLOUD_TASK_STATUSES.PROCESSING]: 0,
+            [CLOUD_TASK_STATUSES.COMPLETED]: 0,
+            [CLOUD_TASK_STATUSES.FAILED]: 0,
+        };
+        for (const task of this.tasks.values()) {
+            stats[task.status] = (stats[task.status] ?? 0) + 1;
+        }
+        return stats;
+    }
+    // -----------------------------------------------------------------------
+    // Helpers
+    // -----------------------------------------------------------------------
+    /** Count pending tasks for a specific user. */
+    countUserPendingTasks(userId) {
+        let count = 0;
+        for (const task of this.tasks.values()) {
+            if (task.userId === userId && task.status === CLOUD_TASK_STATUSES.PENDING) {
+                count++;
+            }
+        }
+        return count;
+    }
+    /** Persist tasks to disk. */
+    async persist() {
+        try {
+            const data = JSON.stringify(Array.from(this.tasks.values()), null, 2);
+            await writeFile(this.tasksFilePath, data, 'utf-8');
+        }
+        catch (err) {
+            this.logger.error('Failed to persist tasks', { error: String(err) });
+        }
+    }
+}
+//# sourceMappingURL=cloud-task.service.js.map

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

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

package/dist/backend/backend/src/services/cloud/relay-client.service.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Relay Client Service
+ *
+ * WebSocket client that connects to a Relay Server for inter-node
+ * communication when direct connections are unavailable (NAT/firewall).
+ *
+ * Flow: Node A (Agent) <-> Cloud (Relay) <-> Node B (Orchestrator)
+ *
+ * Features:
+ * - Automatic fallback from direct connection to relay mode
+ * - End-to-end encryption (E2EE) — relay never sees plaintext
+ * - Heartbeat keep-alive with auto-reconnection
+ * - Exponential backoff on reconnection failures
+ *
+ * @module services/cloud/relay-client.service
+ */
+import { EventEmitter } from 'events';
+import { type RelayClientConfig, type RelayClientState, type RelaySessionId } from './relay.types.js';
+export interface RelayClientEvents {
+    /** Emitted when successfully paired with a peer */
+    paired: (peerSessionId: RelaySessionId, peerRole: string) => void;
+    /** Emitted when a decrypted message is received from the peer */
+    message: (plaintext: string) => void;
+    /** Emitted when the peer disconnects */
+    peerDisconnected: (peerSessionId: RelaySessionId) => void;
+    /** Emitted when the client state changes */
+    stateChange: (state: RelayClientState) => void;
+    /** Emitted on errors */
+    error: (error: Error) => void;
+}
+/**
+ * RelayClientService singleton.
+ *
+ * Manages a WebSocket connection to a relay server, handles registration,
+ * heartbeats, reconnection, and encrypts/decrypts messages for E2EE.
+ */
+export declare class RelayClientService extends EventEmitter {
+    private static instance;
+    private readonly logger;
+    /** Current WebSocket connection */
+    private ws;
+    /** Client configuration (set via connect()) */
+    private config;
+    /** Current connection state */
+    private state;
+    /** Assigned session ID after registration */
+    private sessionId;
+    /** Heartbeat interval timer */
+    private heartbeatInterval;
+    /** Reconnection attempt counter */
+    private reconnectAttempts;
+    /** Reconnection timer */
+    private reconnectTimer;
+    /** Derived encryption key */
+    private encryptionKey;
+    /** Salt for key derivation (exchanged as part of pairing code) */
+    private salt;
+    /** Whether disconnect was intentional (skip reconnect) */
+    private intentionalDisconnect;
+    private constructor();
+    /**
+     * Get the singleton instance.
+     *
+     * @returns RelayClientService instance
+     */
+    static getInstance(): RelayClientService;
+    /**
+     * Reset the singleton (for testing).
+     */
+    static resetInstance(): void;
+    /**
+     * Connect to a relay server.
+     *
+     * Establishes the WebSocket connection, sends a register message,
+     * and derives the E2EE encryption key from the shared secret.
+     *
+     * @param config - Relay client configuration
+     *
+     * @example
+     * ```ts
+     * const client = RelayClientService.getInstance();
+     * client.connect({
+     *   wsUrl: 'ws://cloud.crewly.dev:8787/relay',
+     *   pairingCode: 'abc-123',
+     *   role: 'agent',
+     *   token: 'sk-xxx',
+     *   sharedSecret: 'team-secret',
+     * });
+     * client.on('message', (plaintext) => console.log(plaintext));
+     * ```
+     */
+    connect(config: RelayClientConfig): void;
+    /**
+     * Disconnect from the relay server.
+     *
+     * Closes the WebSocket cleanly and stops heartbeats and reconnection.
+     */
+    disconnect(): void;
+    /**
+     * Send an encrypted message to the paired peer via the relay.
+     *
+     * The message is encrypted locally before being sent — the relay
+     * server only forwards the opaque ciphertext.
+     *
+     * @param plaintext - Message content to send
+     * @throws Error if not in paired state or encryption key is not available
+     *
+     * @example
+     * ```ts
+     * client.send('Hello from agent node!');
+     * ```
+     */
+    send(plaintext: string): void;
+    /**
+     * Get the current client state.
+     *
+     * @returns Current RelayClientState
+     */
+    getState(): RelayClientState;
+    /**
+     * Get the assigned session ID (available after registration).
+     *
+     * @returns Session ID or null if not registered
+     */
+    getSessionId(): RelaySessionId | null;
+    /**
+     * Establish the WebSocket connection and set up handlers.
+     */
+    private doConnect;
+    /**
+     * Send the registration message to the relay server.
+     */
+    private sendRegister;
+    /**
+     * Handle an incoming WebSocket message.
+     *
+     * @param data - Raw message data
+     */
+    private handleMessage;
+    /**
+     * Handle an incoming relay data message by decrypting the payload.
+     *
+     * @param msg - Relay data message with encrypted payload
+     */
+    private handleRelayData;
+    /**
+     * Start the heartbeat interval to keep the connection alive.
+     */
+    private startHeartbeat;
+    /**
+     * Stop the heartbeat interval.
+     */
+    private stopHeartbeat;
+    /**
+     * Schedule a reconnection attempt with exponential backoff.
+     */
+    private scheduleReconnect;
+    /**
+     * Send a raw relay message over the WebSocket.
+     *
+     * @param message - Relay message to send
+     */
+    private sendRaw;
+    /**
+     * Update the client state and emit a stateChange event.
+     *
+     * @param newState - New state
+     */
+    private setState;
+    /**
+     * Clean up timers and close the WebSocket connection.
+     */
+    private cleanup;
+}
+//# sourceMappingURL=relay-client.service.d.ts.map

package/dist/backend/backend/src/services/cloud/relay-client.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-client.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/cloud/relay-client.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAGtC,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EAKpB,MAAM,kBAAkB,CAAC;AAgB1B,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,MAAM,EAAE,CAAC,aAAa,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAClE,iEAAiE;IACjE,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,wCAAwC;IACxC,gBAAgB,EAAE,CAAC,aAAa,EAAE,cAAc,KAAK,IAAI,CAAC;IAC1D,4CAA4C;IAC5C,WAAW,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC/C,wBAAwB;IACxB,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAC/B;AAMD;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;IAClD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAmC;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC,mCAAmC;IACnC,OAAO,CAAC,EAAE,CAA0B;IACpC,+CAA+C;IAC/C,OAAO,CAAC,MAAM,CAAkC;IAChD,+BAA+B;IAC/B,OAAO,CAAC,KAAK,CAAoC;IACjD,6CAA6C;IAC7C,OAAO,CAAC,SAAS,CAA+B;IAChD,+BAA+B;IAC/B,OAAO,CAAC,iBAAiB,CAA+C;IACxE,mCAAmC;IACnC,OAAO,CAAC,iBAAiB,CAAK;IAC9B,yBAAyB;IACzB,OAAO,CAAC,cAAc,CAA8C;IACpE,6BAA6B;IAC7B,OAAO,CAAC,aAAa,CAAuB;IAC5C,kEAAkE;IAClE,OAAO,CAAC,IAAI,CAAuB;IACnC,0DAA0D;IAC1D,OAAO,CAAC,qBAAqB,CAAS;IAEtC,OAAO;IAKP;;;;OAIG;IACH,MAAM,CAAC,WAAW,IAAI,kBAAkB;IAOxC;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,IAAI;IAY5B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAiBxC;;;;OAIG;IACH,UAAU,IAAI,IAAI;IAMlB;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAe7B;;;;OAIG;IACH,QAAQ,IAAI,gBAAgB;IAI5B;;;;OAIG;IACH,YAAY,IAAI,cAAc,GAAG,IAAI;IAQrC;;OAEG;IACH,OAAO,CAAC,SAAS;IA4CjB;;OAEG;IACH,OAAO,CAAC,YAAY;IAYpB;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAwDrB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAsBvB;;OAEG;IACH,OAAO,CAAC,cAAc;IAQtB;;OAEG;IACH,OAAO,CAAC,aAAa;IAWrB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA6BzB;;;;OAIG;IACH,OAAO,CAAC,OAAO;IAMf;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAOhB;;OAEG;IACH,OAAO,CAAC,OAAO;CAkBhB"}