@renseiai/agentfactory-server 0.8.0

package/dist/src/work-queue.js

@@ -0,0 +1,384 @@
+/**
+ * Work Queue Module (Optimized)
+ *
+ * Manages the queue of pending agent work items in Redis.
+ * Workers poll this queue to claim and process work.
+ *
+ * Data Structures (optimized for high concurrency):
+ * - work:items (Hash): sessionId -> JSON work item - O(1) lookup
+ * - work:queue (Sorted Set): score = priority, member = sessionId - O(log n) operations
+ * - work:claim:{sessionId} (String): workerId with TTL - atomic claims
+ *
+ * Performance:
+ * - queueWork: O(log n) - HSET + ZADD
+ * - claimWork: O(log n) - SETNX + HGET + ZREM
+ * - peekWork: O(log n + k) - ZRANGEBYSCORE + HMGET where k = limit
+ * - getQueueLength: O(1) - ZCARD
+ */
+import { redisSetNX, redisDel, redisGet, redisZAdd, redisZRem, redisZRangeByScore, redisZCard, redisHSet, redisHGet, redisHDel, redisHMGet, isRedisConfigured, 
+// Legacy list operations for migration
+redisLRange, redisLRem, } from './redis.js';
+const log = {
+    info: (msg, data) => console.log(`[work-queue] ${msg}`, data ? JSON.stringify(data) : ''),
+    warn: (msg, data) => console.warn(`[work-queue] ${msg}`, data ? JSON.stringify(data) : ''),
+    error: (msg, data) => console.error(`[work-queue] ${msg}`, data ? JSON.stringify(data) : ''),
+    debug: (_msg, _data) => { },
+};
+// Redis key constants
+const WORK_QUEUE_KEY = 'work:queue'; // Sorted set: priority queue
+const WORK_ITEMS_KEY = 'work:items'; // Hash: sessionId -> work item
+const WORK_CLAIM_PREFIX = 'work:claim:';
+// Legacy key for migration
+const LEGACY_QUEUE_KEY = 'work:queue:legacy';
+// Default TTL for work claims (1 hour)
+const WORK_CLAIM_TTL = parseInt(process.env.WORK_CLAIM_TTL ?? '3600', 10);
+/**
+ * Calculate priority score for sorted set
+ * Lower scores = higher priority (processed first)
+ * Score = (priority * 1e13) + timestamp
+ * This ensures priority is the primary sort key, timestamp is secondary
+ */
+function calculateScore(priority, queuedAt) {
+    // Clamp priority to 1-9 to ensure score calculation works correctly
+    const clampedPriority = Math.max(1, Math.min(9, priority));
+    // Use 1e13 multiplier to leave room for timestamps up to year ~2286
+    return clampedPriority * 1e13 + queuedAt;
+}
+/**
+ * Add work to the queue
+ *
+ * @param work - Work item to queue
+ * @returns true if queued successfully
+ */
+export async function queueWork(work) {
+    if (!isRedisConfigured()) {
+        log.warn('Redis not configured, cannot queue work');
+        return false;
+    }
+    try {
+        const score = calculateScore(work.priority, work.queuedAt);
+        const serialized = JSON.stringify(work);
+        // Store work item in hash (O(1) lookup)
+        await redisHSet(WORK_ITEMS_KEY, work.sessionId, serialized);
+        // Add to priority queue (O(log n))
+        await redisZAdd(WORK_QUEUE_KEY, score, work.sessionId);
+        log.info('Work queued', {
+            sessionId: work.sessionId,
+            issueIdentifier: work.issueIdentifier,
+            priority: work.priority,
+            score,
+        });
+        return true;
+    }
+    catch (error) {
+        log.error('Failed to queue work', { error, sessionId: work.sessionId });
+        return false;
+    }
+}
+/**
+ * Peek at pending work without removing from queue
+ * Returns items sorted by priority (lowest number = highest priority)
+ *
+ * @param limit - Maximum number of items to return
+ * @returns Array of work items sorted by priority
+ */
+export async function peekWork(limit = 10) {
+    if (!isRedisConfigured()) {
+        return [];
+    }
+    try {
+        // Get session IDs from priority queue (lowest scores first)
+        const sessionIds = await redisZRangeByScore(WORK_QUEUE_KEY, '-inf', '+inf', limit);
+        if (sessionIds.length === 0) {
+            return [];
+        }
+        // Batch fetch work items from hash
+        const items = await redisHMGet(WORK_ITEMS_KEY, sessionIds);
+        // Parse and filter out any missing items
+        const result = [];
+        for (let i = 0; i < items.length; i++) {
+            const item = items[i];
+            if (item) {
+                try {
+                    result.push(JSON.parse(item));
+                }
+                catch {
+                    log.warn('Failed to parse work item', { sessionId: sessionIds[i] });
+                }
+            }
+        }
+        return result;
+    }
+    catch (error) {
+        log.error('Failed to peek work queue', { error });
+        return [];
+    }
+}
+/**
+ * Get the number of items in the queue
+ */
+export async function getQueueLength() {
+    if (!isRedisConfigured()) {
+        return 0;
+    }
+    try {
+        return await redisZCard(WORK_QUEUE_KEY);
+    }
+    catch (error) {
+        log.error('Failed to get queue length', { error });
+        return 0;
+    }
+}
+/**
+ * Claim a work item for processing
+ *
+ * Uses SETNX for atomic claim to prevent race conditions.
+ * O(log n) complexity for claim + remove operations.
+ *
+ * @param sessionId - Session ID to claim
+ * @param workerId - Worker claiming the work
+ * @returns The work item if claimed successfully, null otherwise
+ */
+export async function claimWork(sessionId, workerId) {
+    if (!isRedisConfigured()) {
+        log.warn('Redis not configured, cannot claim work');
+        return null;
+    }
+    const claimKey = `${WORK_CLAIM_PREFIX}${sessionId}`;
+    let claimAcquired = false;
+    try {
+        // Try to atomically set the claim
+        const claimed = await redisSetNX(claimKey, workerId, WORK_CLAIM_TTL);
+        if (!claimed) {
+            log.debug('Work already claimed', { sessionId, workerId });
+            return null;
+        }
+        claimAcquired = true;
+        // Get work item from hash (O(1))
+        const itemJson = await redisHGet(WORK_ITEMS_KEY, sessionId);
+        if (!itemJson) {
+            // Work item not found - release the claim
+            await redisDel(claimKey);
+            claimAcquired = false;
+            log.warn('Work item not found in hash after claim', { sessionId });
+            return null;
+        }
+        const work = JSON.parse(itemJson);
+        // Remove from priority queue (O(log n))
+        await redisZRem(WORK_QUEUE_KEY, sessionId);
+        // Remove from items hash (O(1))
+        await redisHDel(WORK_ITEMS_KEY, sessionId);
+        log.info('Work claimed', {
+            sessionId,
+            workerId,
+            issueIdentifier: work.issueIdentifier,
+        });
+        return work;
+    }
+    catch (error) {
+        // Release the claim key if we acquired it to prevent deadlock.
+        // Without this, a transient Redis error after SETNX would leave the
+        // claim key stuck for its full TTL (1 hour), blocking all workers
+        // from claiming this work item while it remains in the queue.
+        if (claimAcquired) {
+            try {
+                await redisDel(claimKey);
+            }
+            catch (cleanupError) {
+                log.error('Failed to release claim during error cleanup', {
+                    cleanupError,
+                    sessionId,
+                });
+            }
+        }
+        log.error('Failed to claim work', { error, sessionId, workerId });
+        return null;
+    }
+}
+/**
+ * Release a work claim (e.g., on failure or cancellation)
+ *
+ * @param sessionId - Session ID to release
+ * @returns true if released successfully
+ */
+export async function releaseClaim(sessionId) {
+    if (!isRedisConfigured()) {
+        return false;
+    }
+    try {
+        const claimKey = `${WORK_CLAIM_PREFIX}${sessionId}`;
+        const deleted = await redisDel(claimKey);
+        return deleted > 0;
+    }
+    catch (error) {
+        log.error('Failed to release claim', { error, sessionId });
+        return false;
+    }
+}
+/**
+ * Check which worker has claimed a session
+ *
+ * @param sessionId - Session ID to check
+ * @returns Worker ID if claimed, null otherwise
+ */
+export async function getClaimOwner(sessionId) {
+    if (!isRedisConfigured()) {
+        return null;
+    }
+    try {
+        const claimKey = `${WORK_CLAIM_PREFIX}${sessionId}`;
+        return await redisGet(claimKey);
+    }
+    catch (error) {
+        log.error('Failed to get claim owner', { error, sessionId });
+        return null;
+    }
+}
+/**
+ * Check if a session has an entry in the work queue.
+ * O(1) check via the work items hash.
+ *
+ * @param sessionId - Session ID to check
+ * @returns true if the session is present in the work queue
+ */
+export async function isSessionInQueue(sessionId) {
+    if (!isRedisConfigured()) {
+        return false;
+    }
+    try {
+        const item = await redisHGet(WORK_ITEMS_KEY, sessionId);
+        return item !== null;
+    }
+    catch (error) {
+        log.error('Failed to check if session is in queue', { error, sessionId });
+        return false;
+    }
+}
+/**
+ * Re-queue work that failed or was abandoned
+ *
+ * @param work - Work item to re-queue
+ * @param priorityBoost - Decrease priority number (higher priority) by this amount
+ * @returns true if re-queued successfully
+ */
+export async function requeueWork(work, priorityBoost = 1) {
+    if (!isRedisConfigured()) {
+        return false;
+    }
+    try {
+        // Release any existing claim
+        await releaseClaim(work.sessionId);
+        // Boost priority (lower number = higher priority)
+        const newPriority = Math.max(1, work.priority - priorityBoost);
+        // Re-queue with updated priority and timestamp
+        const updatedWork = {
+            ...work,
+            priority: newPriority,
+            queuedAt: Date.now(),
+        };
+        return await queueWork(updatedWork);
+    }
+    catch (error) {
+        log.error('Failed to requeue work', { error, sessionId: work.sessionId });
+        return false;
+    }
+}
+/**
+ * Get all pending work items (for dashboard/monitoring)
+ * Returns items sorted by priority
+ */
+export async function getAllPendingWork() {
+    if (!isRedisConfigured()) {
+        return [];
+    }
+    try {
+        // Get all session IDs from priority queue
+        const sessionIds = await redisZRangeByScore(WORK_QUEUE_KEY, '-inf', '+inf');
+        if (sessionIds.length === 0) {
+            return [];
+        }
+        // Batch fetch all work items
+        const items = await redisHMGet(WORK_ITEMS_KEY, sessionIds);
+        const result = [];
+        for (const item of items) {
+            if (item) {
+                try {
+                    result.push(JSON.parse(item));
+                }
+                catch {
+                    // Skip invalid items
+                }
+            }
+        }
+        return result;
+    }
+    catch (error) {
+        log.error('Failed to get all pending work', { error });
+        return [];
+    }
+}
+/**
+ * Remove a work item from queue (without claiming)
+ * Used for cleanup operations
+ *
+ * @param sessionId - Session ID to remove
+ * @returns true if removed
+ */
+export async function removeFromQueue(sessionId) {
+    if (!isRedisConfigured()) {
+        return false;
+    }
+    try {
+        // Remove from both data structures
+        await redisZRem(WORK_QUEUE_KEY, sessionId);
+        await redisHDel(WORK_ITEMS_KEY, sessionId);
+        return true;
+    }
+    catch (error) {
+        log.error('Failed to remove from queue', { error, sessionId });
+        return false;
+    }
+}
+/**
+ * Migrate data from legacy list-based queue to new sorted set/hash structure
+ * Run this once after deployment to migrate existing data
+ */
+export async function migrateFromLegacyQueue() {
+    if (!isRedisConfigured()) {
+        return { migrated: 0, failed: 0 };
+    }
+    let migrated = 0;
+    let failed = 0;
+    try {
+        // Check if there's data in the legacy queue (same key, but was a list)
+        // Try to read as list first
+        const legacyItems = await redisLRange(WORK_QUEUE_KEY, 0, -1);
+        if (legacyItems.length === 0) {
+            log.info('No legacy queue data to migrate');
+            return { migrated: 0, failed: 0 };
+        }
+        log.info('Migrating legacy queue data', { itemCount: legacyItems.length });
+        for (const itemJson of legacyItems) {
+            try {
+                const work = JSON.parse(itemJson);
+                // Add to new data structures
+                const score = calculateScore(work.priority, work.queuedAt);
+                await redisHSet(WORK_ITEMS_KEY, work.sessionId, itemJson);
+                await redisZAdd(WORK_QUEUE_KEY, score, work.sessionId);
+                // Remove from legacy list
+                await redisLRem(WORK_QUEUE_KEY, 1, itemJson);
+                migrated++;
+            }
+            catch (err) {
+                log.warn('Failed to migrate work item', { error: err, itemJson });
+                failed++;
+            }
+        }
+        log.info('Legacy queue migration complete', { migrated, failed });
+    }
+    catch (error) {
+        // This might fail if the key doesn't exist as a list (already migrated)
+        log.debug('No legacy queue to migrate or already migrated', { error });
+    }
+    return { migrated, failed };
+}

package/dist/src/worker-auth.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Worker Authentication Module
+ *
+ * Framework-agnostic API key verification for worker endpoints.
+ * Workers must include a valid API key in the Authorization header.
+ */
+/**
+ * Extract a Bearer token from an Authorization header value
+ *
+ * @param authHeader - The Authorization header value
+ * @returns The bearer token or null if not a valid Bearer header
+ */
+export declare function extractBearerToken(authHeader: string | null | undefined): string | null;
+/**
+ * Verify an API key against the expected key using timing-safe comparison
+ *
+ * @param providedKey - The API key from the request
+ * @param expectedKey - The expected API key (defaults to WORKER_API_KEY env var)
+ * @returns true if the key is valid
+ */
+export declare function verifyApiKey(providedKey: string, expectedKey?: string): boolean;
+/**
+ * Check if worker auth is configured
+ * (useful for development/testing where auth might be disabled)
+ *
+ * @param envVar - Environment variable name to check (default: WORKER_API_KEY)
+ */
+export declare function isWorkerAuthConfigured(envVar?: string): boolean;
+//# sourceMappingURL=worker-auth.d.ts.map

package/dist/src/worker-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-auth.d.ts","sourceRoot":"","sources":["../../src/worker-auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAKvF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAiBT;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,SAAmB,GAAG,OAAO,CAEzE"}

package/dist/src/worker-auth.js

@@ -0,0 +1,49 @@
+/**
+ * Worker Authentication Module
+ *
+ * Framework-agnostic API key verification for worker endpoints.
+ * Workers must include a valid API key in the Authorization header.
+ */
+import crypto from 'crypto';
+/**
+ * Extract a Bearer token from an Authorization header value
+ *
+ * @param authHeader - The Authorization header value
+ * @returns The bearer token or null if not a valid Bearer header
+ */
+export function extractBearerToken(authHeader) {
+    if (!authHeader?.startsWith('Bearer ')) {
+        return null;
+    }
+    return authHeader.slice(7);
+}
+/**
+ * Verify an API key against the expected key using timing-safe comparison
+ *
+ * @param providedKey - The API key from the request
+ * @param expectedKey - The expected API key (defaults to WORKER_API_KEY env var)
+ * @returns true if the key is valid
+ */
+export function verifyApiKey(providedKey, expectedKey) {
+    const expected = expectedKey ?? process.env.WORKER_API_KEY;
+    if (!expected) {
+        return false;
+    }
+    // Use timing-safe comparison to prevent timing attacks
+    try {
+        return crypto.timingSafeEqual(Buffer.from(providedKey), Buffer.from(expected));
+    }
+    catch {
+        // Buffers have different lengths
+        return false;
+    }
+}
+/**
+ * Check if worker auth is configured
+ * (useful for development/testing where auth might be disabled)
+ *
+ * @param envVar - Environment variable name to check (default: WORKER_API_KEY)
+ */
+export function isWorkerAuthConfigured(envVar = 'WORKER_API_KEY') {
+    return !!process.env[envVar];
+}

package/dist/src/worker-storage.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Worker Storage Module
+ *
+ * Manages worker registration and tracking in Redis.
+ * Workers register on startup, send periodic heartbeats,
+ * and deregister on shutdown.
+ */
+/**
+ * Worker registration data stored in Redis
+ */
+export interface WorkerData {
+    id: string;
+    hostname: string;
+    capacity: number;
+    activeCount: number;
+    registeredAt: number;
+    lastHeartbeat: number;
+    status: 'active' | 'draining' | 'offline';
+    version?: string;
+    projects?: string[];
+}
+/**
+ * Worker info returned to API consumers
+ */
+export interface WorkerInfo extends WorkerData {
+    activeSessions: string[];
+}
+/**
+ * Register a new worker
+ *
+ * @param hostname - Worker's hostname
+ * @param capacity - Maximum concurrent agents the worker can handle
+ * @param version - Optional worker software version
+ * @returns Worker ID and configuration
+ */
+export declare function registerWorker(hostname: string, capacity: number, version?: string, projects?: string[]): Promise<{
+    workerId: string;
+    heartbeatInterval: number;
+    pollInterval: number;
+} | null>;
+/**
+ * Update worker heartbeat
+ *
+ * @param workerId - Worker ID
+ * @param activeCount - Current number of active agents
+ * @param load - Optional system load metrics
+ * @returns Heartbeat acknowledgment or null on failure
+ */
+export declare function updateHeartbeat(workerId: string, activeCount: number, load?: {
+    cpu: number;
+    memory: number;
+}): Promise<{
+    acknowledged: boolean;
+    serverTime: string;
+    pendingWorkCount: number;
+} | null>;
+/**
+ * Get worker by ID
+ */
+export declare function getWorker(workerId: string): Promise<WorkerInfo | null>;
+/**
+ * Deregister a worker
+ *
+ * @param workerId - Worker ID to deregister
+ * @returns List of session IDs that need to be re-queued
+ */
+export declare function deregisterWorker(workerId: string): Promise<{
+    deregistered: boolean;
+    unclaimedSessions: string[];
+}>;
+/**
+ * List all registered workers
+ */
+export declare function listWorkers(): Promise<WorkerInfo[]>;
+/**
+ * Get workers that have missed heartbeats (stale workers)
+ */
+export declare function getStaleWorkers(): Promise<WorkerInfo[]>;
+/**
+ * Add a session to a worker's active sessions
+ *
+ * @param workerId - Worker ID
+ * @param sessionId - Session ID being processed
+ */
+export declare function addWorkerSession(workerId: string, sessionId: string): Promise<boolean>;
+/**
+ * Remove a session from a worker's active sessions
+ *
+ * @param workerId - Worker ID
+ * @param sessionId - Session ID to remove
+ */
+export declare function removeWorkerSession(workerId: string, sessionId: string): Promise<boolean>;
+/**
+ * Get total capacity across all active workers.
+ *
+ * Accepts an optional pre-fetched workers list to avoid redundant Redis scans
+ * (callers like the stats handler already call listWorkers()).
+ *
+ * Uses activeSessions.length (authoritative Redis set) instead of the
+ * heartbeat-reported activeCount, which can be stale after re-registration
+ * or between heartbeat intervals.
+ */
+export declare function getTotalCapacity(prefetchedWorkers?: WorkerInfo[]): Promise<{
+    totalCapacity: number;
+    totalActive: number;
+    availableCapacity: number;
+}>;
+//# sourceMappingURL=worker-storage.d.ts.map

package/dist/src/worker-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-storage.d.ts","sourceRoot":"","sources":["../../src/worker-storage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA8CH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAA;IACzC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,UAAW,SAAQ,UAAU;IAC5C,cAAc,EAAE,MAAM,EAAE,CAAA;CACzB;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAyCvF;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrC,OAAO,CAAC;IAAE,YAAY,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAsCzF;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAyB5E;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,YAAY,EAAE,OAAO,CAAC;IAAC,iBAAiB,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CA6BjE;AAED;;GAEG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAoCzD;AAED;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAY7D;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAalB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAalB;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,iBAAiB,CAAC,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAChF,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,iBAAiB,EAAE,MAAM,CAAA;CAC1B,CAAC,CAqBD"}