@renseiai/agentfactory-server 0.8.0

package/dist/src/logger.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Structured JSON Logger for AgentFactory Server
+ *
+ * Provides consistent, structured logging with:
+ * - JSON output format for log aggregation
+ * - Log levels (debug, info, warn, error)
+ * - Context fields (requestId, sessionId, issueId, etc.)
+ * - Automatic timestamps
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface LogContext {
+    /** Unique request identifier for tracing */
+    requestId?: string;
+    /** Linear agent session ID */
+    sessionId?: string;
+    /** Linear issue ID */
+    issueId?: string;
+    /** Linear issue identifier (e.g., SUP-123) */
+    issueIdentifier?: string;
+    /** Linear workspace/organization ID */
+    workspaceId?: string;
+    /** Duration in milliseconds */
+    durationMs?: number;
+    /** Error object for error logs */
+    error?: Error | unknown;
+    /** Any additional context fields */
+    [key: string]: unknown;
+}
+/**
+ * Logger class for structured logging
+ */
+declare class Logger {
+    private service;
+    private defaultContext;
+    private minLevel;
+    private jsonEnabled;
+    constructor(service: string, defaultContext?: LogContext);
+    /**
+     * Create a child logger with additional default context
+     */
+    child(context: LogContext): Logger;
+    /**
+     * Check if a log level should be output
+     */
+    private shouldLog;
+    /**
+     * Format and output a log entry
+     */
+    private log;
+    /**
+     * Output JSON formatted log
+     */
+    private outputJson;
+    /**
+     * Output human-readable log for development
+     */
+    private outputPretty;
+    debug(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    warn(message: string, context?: LogContext): void;
+    error(message: string, context?: LogContext): void;
+}
+/**
+ * Create a logger instance for a service
+ */
+export declare function createLogger(service: string, defaultContext?: LogContext): Logger;
+/**
+ * Generate a unique request ID
+ */
+export declare function generateRequestId(): string;
+/**
+ * Default logger instance for the server
+ */
+export declare const logger: Logger;
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/dist/src/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAE1D,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,8CAA8C;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,+BAA+B;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,kCAAkC;IAClC,KAAK,CAAC,EAAE,KAAK,GAAG,OAAO,CAAA;IACvB,oCAAoC;IACpC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAgFD;;GAEG;AACH,cAAM,MAAM;IACV,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,cAAc,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,WAAW,CAAS;gBAEhB,OAAO,EAAE,MAAM,EAAE,cAAc,GAAE,UAAe;IAO5D;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM;IAQlC;;OAEG;IACH,OAAO,CAAC,SAAS;IAIjB;;OAEG;IACH,OAAO,CAAC,GAAG;IAuBX;;OAEG;IACH,OAAO,CAAC,UAAU;IAclB;;OAEG;IACH,OAAO,CAAC,YAAY;IAiDpB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIlD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIjD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;CAGnD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,cAAc,GAAE,UAAe,GAC9B,MAAM,CAER;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;GAEG;AACH,eAAO,MAAM,MAAM,QAAsC,CAAA"}

package/dist/src/logger.js

@@ -0,0 +1,218 @@
+/**
+ * Structured JSON Logger for AgentFactory Server
+ *
+ * Provides consistent, structured logging with:
+ * - JSON output format for log aggregation
+ * - Log levels (debug, info, warn, error)
+ * - Context fields (requestId, sessionId, issueId, etc.)
+ * - Automatic timestamps
+ */
+/**
+ * Log level priority for filtering
+ */
+const LOG_LEVEL_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+/**
+ * Get the minimum log level from environment
+ * Defaults to 'info' in production, 'debug' in development
+ */
+function getMinLogLevel() {
+    const envLevel = process.env.LOG_LEVEL?.toLowerCase();
+    if (envLevel && envLevel in LOG_LEVEL_PRIORITY) {
+        return envLevel;
+    }
+    return process.env.NODE_ENV === 'production' ? 'info' : 'debug';
+}
+/**
+ * Check if JSON logging is enabled
+ * Defaults to true in production, false in development for readability
+ */
+function isJsonLoggingEnabled() {
+    const envValue = process.env.LOG_JSON;
+    if (envValue !== undefined) {
+        return envValue === 'true' || envValue === '1';
+    }
+    return process.env.NODE_ENV === 'production';
+}
+/**
+ * Format an error for logging
+ */
+function formatError(error) {
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+            ...(error.cause ? { cause: formatError(error.cause) } : {}),
+        };
+    }
+    return { message: String(error) };
+}
+/**
+ * Format context for logging, handling special cases
+ */
+function formatContext(context) {
+    const formatted = {};
+    for (const [key, value] of Object.entries(context)) {
+        if (value === undefined)
+            continue;
+        if (key === 'error') {
+            formatted.error = formatError(value);
+        }
+        else if (value instanceof Error) {
+            formatted[key] = formatError(value);
+        }
+        else {
+            formatted[key] = value;
+        }
+    }
+    return formatted;
+}
+/**
+ * Logger class for structured logging
+ */
+class Logger {
+    service;
+    defaultContext;
+    minLevel;
+    jsonEnabled;
+    constructor(service, defaultContext = {}) {
+        this.service = service;
+        this.defaultContext = defaultContext;
+        this.minLevel = getMinLogLevel();
+        this.jsonEnabled = isJsonLoggingEnabled();
+    }
+    /**
+     * Create a child logger with additional default context
+     */
+    child(context) {
+        const child = new Logger(this.service, {
+            ...this.defaultContext,
+            ...context,
+        });
+        return child;
+    }
+    /**
+     * Check if a log level should be output
+     */
+    shouldLog(level) {
+        return LOG_LEVEL_PRIORITY[level] >= LOG_LEVEL_PRIORITY[this.minLevel];
+    }
+    /**
+     * Format and output a log entry
+     */
+    log(level, message, context = {}) {
+        if (!this.shouldLog(level))
+            return;
+        const mergedContext = { ...this.defaultContext, ...context };
+        const formattedContext = formatContext(mergedContext);
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            message,
+            service: this.service,
+            ...(Object.keys(formattedContext).length > 0
+                ? { context: formattedContext }
+                : {}),
+        };
+        if (this.jsonEnabled) {
+            this.outputJson(level, entry);
+        }
+        else {
+            this.outputPretty(level, entry);
+        }
+    }
+    /**
+     * Output JSON formatted log
+     */
+    outputJson(level, entry) {
+        const output = JSON.stringify(entry);
+        switch (level) {
+            case 'error':
+                console.error(output);
+                break;
+            case 'warn':
+                console.warn(output);
+                break;
+            default:
+                console.log(output);
+        }
+    }
+    /**
+     * Output human-readable log for development
+     */
+    outputPretty(level, entry) {
+        const levelColors = {
+            debug: '\x1b[36m', // cyan
+            info: '\x1b[32m', // green
+            warn: '\x1b[33m', // yellow
+            error: '\x1b[31m', // red
+        };
+        const reset = '\x1b[0m';
+        const dim = '\x1b[2m';
+        const color = levelColors[level];
+        const levelStr = level.toUpperCase().padEnd(5);
+        const time = entry.timestamp.split('T')[1].replace('Z', '');
+        let output = `${dim}${time}${reset} ${color}${levelStr}${reset} [${entry.service}] ${entry.message}`;
+        if (entry.context && Object.keys(entry.context).length > 0) {
+            const contextStr = Object.entries(entry.context)
+                .filter(([key]) => key !== 'error')
+                .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+                .join(' ');
+            if (contextStr) {
+                output += ` ${dim}${contextStr}${reset}`;
+            }
+            // Print error details on separate lines
+            if (entry.context.error) {
+                const err = entry.context.error;
+                output += `\n  ${color}${err.name}: ${err.message}${reset}`;
+                if (err.stack) {
+                    const stackLines = err.stack.split('\n').slice(1, 4);
+                    output += `\n${dim}${stackLines.join('\n')}${reset}`;
+                }
+            }
+        }
+        switch (level) {
+            case 'error':
+                console.error(output);
+                break;
+            case 'warn':
+                console.warn(output);
+                break;
+            default:
+                console.log(output);
+        }
+    }
+    debug(message, context) {
+        this.log('debug', message, context);
+    }
+    info(message, context) {
+        this.log('info', message, context);
+    }
+    warn(message, context) {
+        this.log('warn', message, context);
+    }
+    error(message, context) {
+        this.log('error', message, context);
+    }
+}
+/**
+ * Create a logger instance for a service
+ */
+export function createLogger(service, defaultContext = {}) {
+    return new Logger(service, defaultContext);
+}
+/**
+ * Generate a unique request ID
+ */
+export function generateRequestId() {
+    return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+/**
+ * Default logger instance for the server
+ */
+export const logger = createLogger('agentfactory-server');

package/dist/src/orphan-cleanup.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Orphan Cleanup Module
+ *
+ * Detects and handles orphaned sessions - sessions marked as running/claimed
+ * but whose worker is no longer active (heartbeat timeout).
+ *
+ * When a worker disconnects, the work is re-queued for another worker to resume.
+ * The Linear issue status is NOT rolled back - the issue remains in its current
+ * workflow state and the next worker will resume from where the previous one left off.
+ */
+import { type AgentSessionState } from './session-storage.js';
+/**
+ * Callback for when an orphaned session is re-queued
+ */
+export interface OrphanCleanupCallbacks {
+    /** Called when an orphaned session is re-queued. Use to post Linear comments, etc. */
+    onOrphanRequeued?: (session: AgentSessionState) => Promise<void>;
+    /** Called when a zombie pending session is recovered. Use to post Linear comments, etc. */
+    onZombieRecovered?: (session: AgentSessionState) => Promise<void>;
+}
+export interface OrphanCleanupResult {
+    checked: number;
+    orphaned: number;
+    requeued: number;
+    failed: number;
+    details: Array<{
+        sessionId: string;
+        issueIdentifier: string;
+        action: 'requeued' | 'failed';
+        reason?: string;
+        /** Path to worktree that may need cleanup (if on worker machine) */
+        worktreePath?: string;
+    }>;
+    /** Worktree paths that need cleanup on worker machines */
+    worktreePathsToCleanup: string[];
+}
+/**
+ * Find sessions that are orphaned (running/claimed but worker is gone)
+ */
+export declare function findOrphanedSessions(): Promise<AgentSessionState[]>;
+/**
+ * Find zombie pending sessions — sessions stuck in `pending` status
+ * that have no corresponding entry in the work queue or any issue-pending queue.
+ *
+ * These arise when:
+ * - claimWork() removes from queue, but claimSession() fails and requeue also fails
+ * - Issue lock expires but promotion fails silently
+ */
+export declare function findZombiePendingSessions(): Promise<AgentSessionState[]>;
+/**
+ * Clean up orphaned sessions by re-queuing them
+ *
+ * @param callbacks - Optional callbacks for external integrations (e.g., posting Linear comments)
+ */
+export declare function cleanupOrphanedSessions(callbacks?: OrphanCleanupCallbacks): Promise<OrphanCleanupResult>;
+export declare function shouldRunCleanup(): boolean;
+/**
+ * Run cleanup if enough time has passed (debounced)
+ * Safe to call frequently - will only actually run periodically
+ *
+ * @param callbacks - Optional callbacks for external integrations
+ */
+export declare function maybeCleanupOrphans(callbacks?: OrphanCleanupCallbacks): Promise<OrphanCleanupResult | null>;
+//# sourceMappingURL=orphan-cleanup.d.ts.map

package/dist/src/orphan-cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orphan-cleanup.d.ts","sourceRoot":"","sources":["../../src/orphan-cleanup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAA;AAqB7B;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,sFAAsF;IACtF,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAChE,2FAA2F;IAC3F,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAClE;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,KAAK,CAAC;QACb,SAAS,EAAE,MAAM,CAAA;QACjB,eAAe,EAAE,MAAM,CAAA;QACvB,MAAM,EAAE,UAAU,GAAG,QAAQ,CAAA;QAC7B,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,oEAAoE;QACpE,YAAY,CAAC,EAAE,MAAM,CAAA;KACtB,CAAC,CAAA;IACF,0DAA0D;IAC1D,sBAAsB,EAAE,MAAM,EAAE,CAAA;CACjC;AAED;;GAEG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAuDzE;AAKD;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAiC9E;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,SAAS,CAAC,EAAE,sBAAsB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAyP9B;AASD,wBAAgB,gBAAgB,IAAI,OAAO,CAO1C;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,CAAC,EAAE,sBAAsB,GACjC,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAKrC"}