@supaku/agentfactory 0.1.0

package/dist/src/orchestrator/session-logger.js

@@ -0,0 +1,275 @@
+/**
+ * Session Logger
+ *
+ * Verbose logging of agent sessions for analysis and improvement.
+ * Uses JSON Lines format for append efficiency and easy parsing.
+ *
+ * Logs are stored at: .agent-logs/sessions/{session-id}/
+ *   - metadata.json: Session metadata
+ *   - events.jsonl: Event log (JSON Lines)
+ */
+import { existsSync, mkdirSync, writeFileSync, appendFileSync, readFileSync, } from 'fs';
+import { resolve } from 'path';
+/**
+ * SessionLogger handles verbose logging of agent sessions
+ */
+export class SessionLogger {
+    config;
+    sessionDir;
+    metadataPath;
+    eventsPath;
+    metadata;
+    stopped = false;
+    constructor(config) {
+        this.config = {
+            ...config,
+            logsDir: config.logsDir ?? '.agent-logs',
+        };
+        // Create session directory path
+        this.sessionDir = resolve(this.config.logsDir, 'sessions', this.config.sessionId);
+        this.metadataPath = resolve(this.sessionDir, 'metadata.json');
+        this.eventsPath = resolve(this.sessionDir, 'events.jsonl');
+        // Initialize metadata
+        this.metadata = {
+            sessionId: this.config.sessionId,
+            issueId: this.config.issueId,
+            issueIdentifier: this.config.issueIdentifier,
+            workType: this.config.workType,
+            prompt: this.config.prompt,
+            startedAt: Date.now(),
+            status: 'running',
+            toolCallsCount: 0,
+            errorsCount: 0,
+            workerId: this.config.workerId,
+        };
+    }
+    /**
+     * Initialize the logger - create directory and write initial metadata
+     */
+    initialize() {
+        try {
+            // Create directory
+            if (!existsSync(this.sessionDir)) {
+                mkdirSync(this.sessionDir, { recursive: true });
+            }
+            // Write initial metadata
+            this.writeMetadata();
+            // Log init event
+            this.logEvent({
+                timestamp: Date.now(),
+                type: 'init',
+                content: {
+                    issueIdentifier: this.config.issueIdentifier,
+                    workType: this.config.workType,
+                    promptPreview: this.config.prompt.substring(0, 200),
+                },
+            });
+        }
+        catch (error) {
+            // Silently fail - logging is best-effort
+            console.warn('SessionLogger: Failed to initialize:', error);
+        }
+    }
+    /**
+     * Log a generic event
+     */
+    logEvent(event) {
+        if (this.stopped)
+            return;
+        try {
+            const line = JSON.stringify(event) + '\n';
+            appendFileSync(this.eventsPath, line);
+        }
+        catch {
+            // Silently fail
+        }
+    }
+    /**
+     * Log a tool use event
+     */
+    logToolUse(toolName, input) {
+        this.metadata.toolCallsCount++;
+        this.logEvent({
+            timestamp: Date.now(),
+            type: 'tool_use',
+            tool: toolName,
+            content: {
+                tool: toolName,
+                input: input ? JSON.stringify(input).substring(0, 2000) : undefined,
+            },
+        });
+    }
+    /**
+     * Log a tool result event
+     */
+    logToolResult(toolName, result, isError = false) {
+        if (isError) {
+            this.metadata.errorsCount++;
+        }
+        this.logEvent({
+            timestamp: Date.now(),
+            type: 'tool_result',
+            tool: toolName,
+            content: {
+                tool: toolName,
+                result: typeof result === 'string' ? result.substring(0, 2000) : JSON.stringify(result).substring(0, 2000),
+            },
+            isError,
+        });
+    }
+    /**
+     * Log an assistant message/thought
+     */
+    logAssistant(content) {
+        this.logEvent({
+            timestamp: Date.now(),
+            type: 'assistant',
+            content: content.substring(0, 2000),
+        });
+    }
+    /**
+     * Log an error
+     */
+    logError(message, error, metadata) {
+        this.metadata.errorsCount++;
+        this.logEvent({
+            timestamp: Date.now(),
+            type: 'error',
+            content: {
+                message,
+                error: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? error.stack?.substring(0, 500) : undefined,
+            },
+            isError: true,
+            metadata,
+        });
+    }
+    /**
+     * Log a warning (non-fatal issue)
+     */
+    logWarning(message, details) {
+        this.logEvent({
+            timestamp: Date.now(),
+            type: 'warning',
+            content: {
+                message,
+                ...details,
+            },
+        });
+    }
+    /**
+     * Log a status change
+     */
+    logStatus(status, details) {
+        this.logEvent({
+            timestamp: Date.now(),
+            type: 'status',
+            content: {
+                status,
+                ...details,
+            },
+        });
+    }
+    /**
+     * Finalize the session with a final status
+     */
+    finalize(status, options) {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        const now = Date.now();
+        // Update metadata
+        this.metadata.endedAt = now;
+        this.metadata.status = status;
+        if (options?.errorMessage) {
+            this.metadata.errorMessage = options.errorMessage;
+        }
+        if (options?.pullRequestUrl) {
+            this.metadata.pullRequestUrl = options.pullRequestUrl;
+        }
+        // Log completion event
+        this.logEvent({
+            timestamp: now,
+            type: status === 'completed' ? 'complete' : 'stop',
+            content: {
+                status,
+                duration: now - this.metadata.startedAt,
+                toolCallsCount: this.metadata.toolCallsCount,
+                errorsCount: this.metadata.errorsCount,
+                ...options,
+            },
+        });
+        // Write final metadata
+        this.writeMetadata();
+    }
+    /**
+     * Get the session directory path
+     */
+    getSessionDir() {
+        return this.sessionDir;
+    }
+    /**
+     * Get current metadata
+     */
+    getMetadata() {
+        return { ...this.metadata };
+    }
+    /**
+     * Write metadata to file
+     */
+    writeMetadata() {
+        try {
+            writeFileSync(this.metadataPath, JSON.stringify(this.metadata, null, 2));
+        }
+        catch {
+            // Silently fail
+        }
+    }
+}
+/**
+ * Create and initialize a session logger
+ */
+export function createSessionLogger(config) {
+    const logger = new SessionLogger(config);
+    logger.initialize();
+    return logger;
+}
+/**
+ * Read session metadata from a session directory
+ */
+export function readSessionMetadata(sessionDir) {
+    const metadataPath = resolve(sessionDir, 'metadata.json');
+    try {
+        if (!existsSync(metadataPath))
+            return null;
+        const content = readFileSync(metadataPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read events from a session directory
+ * Returns an async generator for memory efficiency
+ */
+export function* readSessionEvents(sessionDir) {
+    const eventsPath = resolve(sessionDir, 'events.jsonl');
+    try {
+        if (!existsSync(eventsPath))
+            return;
+        const content = readFileSync(eventsPath, 'utf-8');
+        const lines = content.split('\n').filter((line) => line.trim());
+        for (const line of lines) {
+            try {
+                yield JSON.parse(line);
+            }
+            catch {
+                // Skip invalid lines
+            }
+        }
+    }
+    catch {
+        // Return empty if file doesn't exist or can't be read
+    }
+}

package/dist/src/orchestrator/state-recovery.d.ts

@@ -0,0 +1,96 @@
+/**
+ * State Recovery
+ *
+ * Detects and recovers agent state from the .agent/ directory.
+ * Enables crash recovery and duplicate agent prevention.
+ */
+import type { WorktreeState, HeartbeatState, TodosState, RecoveryCheckResult } from './state-types';
+import type { AgentWorkType } from '@supaku/agentfactory-linear';
+/**
+ * Get the .agent directory path for a worktree
+ */
+export declare function getAgentDir(worktreePath: string): string;
+/**
+ * Get the path to the state.json file
+ */
+export declare function getStatePath(worktreePath: string): string;
+/**
+ * Get the path to the heartbeat.json file
+ */
+export declare function getHeartbeatPath(worktreePath: string): string;
+/**
+ * Get the path to the todos.json file
+ */
+export declare function getTodosPath(worktreePath: string): string;
+/**
+ * Check if a heartbeat is fresh (agent is alive)
+ */
+export declare function isHeartbeatFresh(heartbeat: HeartbeatState | null, timeoutMs?: number): boolean;
+/**
+ * Read the current state from a worktree
+ */
+export declare function readWorktreeState(worktreePath: string): WorktreeState | null;
+/**
+ * Read the current heartbeat from a worktree
+ */
+export declare function readHeartbeat(worktreePath: string): HeartbeatState | null;
+/**
+ * Read the current todos from a worktree
+ */
+export declare function readTodos(worktreePath: string): TodosState | null;
+/**
+ * Check if recovery is possible for a worktree
+ */
+export declare function checkRecovery(worktreePath: string, options?: {
+    heartbeatTimeoutMs?: number;
+    maxRecoveryAttempts?: number;
+}): RecoveryCheckResult;
+/**
+ * Initialize the .agent directory for a worktree
+ */
+export declare function initializeAgentDir(worktreePath: string): void;
+/**
+ * Write the state.json file
+ */
+export declare function writeState(worktreePath: string, state: WorktreeState): void;
+/**
+ * Update specific fields in the state
+ */
+export declare function updateState(worktreePath: string, updates: Partial<WorktreeState>): WorktreeState | null;
+/**
+ * Write the todos.json file
+ */
+export declare function writeTodos(worktreePath: string, todos: TodosState): void;
+/**
+ * Create initial state for a new agent
+ */
+export declare function createInitialState(options: {
+    issueId: string;
+    issueIdentifier: string;
+    linearSessionId: string | null;
+    workType: AgentWorkType;
+    prompt: string;
+    workerId?: string | null;
+    pid?: number | null;
+}): WorktreeState;
+/**
+ * Generate the task list ID for a worktree (matches orchestrator format)
+ *
+ * @param issueIdentifier - Issue identifier (e.g., "SUP-123")
+ * @param workType - Work type suffix (e.g., "development" -> "DEV")
+ * @returns Task list ID (e.g., "SUP-123-DEV")
+ */
+export declare function getTaskListId(issueIdentifier: string, workType: AgentWorkType): string;
+/**
+ * Build a recovery prompt for resuming crashed work
+ */
+export declare function buildRecoveryPrompt(state: WorktreeState, todos?: TodosState): string;
+/**
+ * Parse environment variable for heartbeat timeout
+ */
+export declare function getHeartbeatTimeoutFromEnv(): number;
+/**
+ * Parse environment variable for max recovery attempts
+ */
+export declare function getMaxRecoveryAttemptsFromEnv(): number;
+//# sourceMappingURL=state-recovery.d.ts.map

package/dist/src/orchestrator/state-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-recovery.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/state-recovery.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,UAAU,EACV,mBAAmB,EAEpB,MAAM,eAAe,CAAA;AACtB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAQhE;;GAEG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEzD;AAeD;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,cAAc,GAAG,IAAI,EAChC,SAAS,GAAE,MAAqC,GAC/C,OAAO,CAIT;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAE5E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAEzE;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAEjE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE;IACP,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAA;CACxB,GACL,mBAAmB,CA2ErB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAK7D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CAI3E;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,GAC9B,aAAa,GAAG,IAAI,CAWtB;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAIxE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,eAAe,EAAE,MAAM,CAAA;IACvB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,QAAQ,EAAE,aAAa,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACpB,GAAG,aAAa,CAmBhB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,aAAa,GACtB,MAAM,CAcR;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,aAAa,EACpB,KAAK,CAAC,EAAE,UAAU,GACjB,MAAM,CA6CR;AAED;;GAEG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,CASnD;AAED;;GAEG;AACH,wBAAgB,6BAA6B,IAAI,MAAM,CAStD"}

package/dist/src/orchestrator/state-recovery.js

@@ -0,0 +1,301 @@
+/**
+ * State Recovery
+ *
+ * Detects and recovers agent state from the .agent/ directory.
+ * Enables crash recovery and duplicate agent prevention.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { resolve } from 'path';
+// Default heartbeat timeout: 30 seconds
+const DEFAULT_HEARTBEAT_TIMEOUT_MS = 30000;
+// Default max recovery attempts
+const DEFAULT_MAX_RECOVERY_ATTEMPTS = 3;
+/**
+ * Get the .agent directory path for a worktree
+ */
+export function getAgentDir(worktreePath) {
+    return resolve(worktreePath, '.agent');
+}
+/**
+ * Get the path to the state.json file
+ */
+export function getStatePath(worktreePath) {
+    return resolve(getAgentDir(worktreePath), 'state.json');
+}
+/**
+ * Get the path to the heartbeat.json file
+ */
+export function getHeartbeatPath(worktreePath) {
+    return resolve(getAgentDir(worktreePath), 'heartbeat.json');
+}
+/**
+ * Get the path to the todos.json file
+ */
+export function getTodosPath(worktreePath) {
+    return resolve(getAgentDir(worktreePath), 'todos.json');
+}
+/**
+ * Read and parse a JSON file safely
+ */
+function readJsonSafe(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        const content = readFileSync(path, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if a heartbeat is fresh (agent is alive)
+ */
+export function isHeartbeatFresh(heartbeat, timeoutMs = DEFAULT_HEARTBEAT_TIMEOUT_MS) {
+    if (!heartbeat)
+        return false;
+    const age = Date.now() - heartbeat.timestamp;
+    return age < timeoutMs;
+}
+/**
+ * Read the current state from a worktree
+ */
+export function readWorktreeState(worktreePath) {
+    return readJsonSafe(getStatePath(worktreePath));
+}
+/**
+ * Read the current heartbeat from a worktree
+ */
+export function readHeartbeat(worktreePath) {
+    return readJsonSafe(getHeartbeatPath(worktreePath));
+}
+/**
+ * Read the current todos from a worktree
+ */
+export function readTodos(worktreePath) {
+    return readJsonSafe(getTodosPath(worktreePath));
+}
+/**
+ * Check if recovery is possible for a worktree
+ */
+export function checkRecovery(worktreePath, options = {}) {
+    const heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS;
+    const maxRecoveryAttempts = options.maxRecoveryAttempts ?? DEFAULT_MAX_RECOVERY_ATTEMPTS;
+    const agentDir = getAgentDir(worktreePath);
+    // Check if .agent directory exists
+    if (!existsSync(agentDir)) {
+        return {
+            canRecover: false,
+            agentAlive: false,
+            reason: 'no_state',
+            message: 'No .agent directory found in worktree',
+        };
+    }
+    // Read state
+    const state = readWorktreeState(worktreePath);
+    if (!state) {
+        return {
+            canRecover: false,
+            agentAlive: false,
+            reason: 'no_state',
+            message: 'No state.json found in .agent directory',
+        };
+    }
+    // Validate state
+    if (!state.issueId || !state.issueIdentifier) {
+        return {
+            canRecover: false,
+            agentAlive: false,
+            state,
+            reason: 'invalid_state',
+            message: 'State is missing required fields (issueId, issueIdentifier)',
+        };
+    }
+    // Read heartbeat
+    const heartbeat = readHeartbeat(worktreePath);
+    // Check if agent is alive
+    if (isHeartbeatFresh(heartbeat, heartbeatTimeoutMs)) {
+        return {
+            canRecover: false,
+            agentAlive: true,
+            state,
+            heartbeat: heartbeat,
+            reason: 'agent_alive',
+            message: `Agent is still running (PID: ${heartbeat.pid}, last heartbeat: ${new Date(heartbeat.timestamp).toISOString()})`,
+        };
+    }
+    // Check recovery attempts
+    if (state.recoveryAttempts >= maxRecoveryAttempts) {
+        return {
+            canRecover: false,
+            agentAlive: false,
+            state,
+            heartbeat: heartbeat ?? undefined,
+            reason: 'max_attempts',
+            message: `Maximum recovery attempts reached (${state.recoveryAttempts}/${maxRecoveryAttempts})`,
+        };
+    }
+    // Recovery is possible
+    const todos = readTodos(worktreePath);
+    return {
+        canRecover: true,
+        agentAlive: false,
+        state,
+        heartbeat: heartbeat ?? undefined,
+        todos: todos ?? undefined,
+        message: `Recovery possible (attempt ${state.recoveryAttempts + 1}/${maxRecoveryAttempts})`,
+    };
+}
+/**
+ * Initialize the .agent directory for a worktree
+ */
+export function initializeAgentDir(worktreePath) {
+    const agentDir = getAgentDir(worktreePath);
+    if (!existsSync(agentDir)) {
+        mkdirSync(agentDir, { recursive: true });
+    }
+}
+/**
+ * Write the state.json file
+ */
+export function writeState(worktreePath, state) {
+    const statePath = getStatePath(worktreePath);
+    initializeAgentDir(worktreePath);
+    writeFileSync(statePath, JSON.stringify(state, null, 2));
+}
+/**
+ * Update specific fields in the state
+ */
+export function updateState(worktreePath, updates) {
+    const current = readWorktreeState(worktreePath);
+    if (!current)
+        return null;
+    const updated = {
+        ...current,
+        ...updates,
+        lastUpdatedAt: Date.now(),
+    };
+    writeState(worktreePath, updated);
+    return updated;
+}
+/**
+ * Write the todos.json file
+ */
+export function writeTodos(worktreePath, todos) {
+    const todosPath = getTodosPath(worktreePath);
+    initializeAgentDir(worktreePath);
+    writeFileSync(todosPath, JSON.stringify(todos, null, 2));
+}
+/**
+ * Create initial state for a new agent
+ */
+export function createInitialState(options) {
+    const now = Date.now();
+    const taskListId = getTaskListId(options.issueIdentifier, options.workType);
+    return {
+        issueId: options.issueId,
+        issueIdentifier: options.issueIdentifier,
+        linearSessionId: options.linearSessionId,
+        claudeSessionId: null,
+        workType: options.workType,
+        prompt: options.prompt,
+        startedAt: now,
+        status: 'initializing',
+        currentPhase: null,
+        lastUpdatedAt: now,
+        recoveryAttempts: 0,
+        workerId: options.workerId ?? null,
+        pid: options.pid ?? null,
+        taskListId,
+    };
+}
+/**
+ * Generate the task list ID for a worktree (matches orchestrator format)
+ *
+ * @param issueIdentifier - Issue identifier (e.g., "SUP-123")
+ * @param workType - Work type suffix (e.g., "development" -> "DEV")
+ * @returns Task list ID (e.g., "SUP-123-DEV")
+ */
+export function getTaskListId(issueIdentifier, workType) {
+    const suffixMap = {
+        research: 'RES',
+        'backlog-creation': 'BC',
+        development: 'DEV',
+        inflight: 'INF',
+        coordination: 'COORD',
+        qa: 'QA',
+        acceptance: 'AC',
+        refinement: 'REF',
+        'qa-coordination': 'QA-COORD',
+        'acceptance-coordination': 'AC-COORD',
+    };
+    return `${issueIdentifier}-${suffixMap[workType]}`;
+}
+/**
+ * Build a recovery prompt for resuming crashed work
+ */
+export function buildRecoveryPrompt(state, todos) {
+    const lines = [];
+    lines.push(`Resume work on ${state.issueIdentifier}.`);
+    lines.push('');
+    lines.push('RECOVERY CONTEXT:');
+    lines.push(`- Previous work type: ${state.workType}`);
+    lines.push(`- Last status: ${state.status}`);
+    if (state.currentPhase) {
+        lines.push(`- Last phase: ${state.currentPhase}`);
+    }
+    lines.push(`- Recovery attempt: ${state.recoveryAttempts + 1}`);
+    // Include task list ID for Claude Code Tasks integration
+    const taskListId = getTaskListId(state.issueIdentifier, state.workType);
+    lines.push(`- Task list ID: ${taskListId}`);
+    lines.push('');
+    // Note about Claude Code Tasks persistence
+    lines.push('TASK STATE:');
+    lines.push(`Your task list is preserved at: ~/.claude/tasks/${taskListId}/`);
+    lines.push('Use TaskList to see the current state of pending/completed tasks.');
+    lines.push('');
+    if (todos && todos.items.length > 0) {
+        lines.push('PREVIOUS TODO LIST (legacy):');
+        for (const item of todos.items) {
+            const statusIcon = item.status === 'completed' ? '\u2713' :
+                item.status === 'in_progress' ? '\u2192' : '\u25CB';
+            lines.push(`  ${statusIcon} [${item.status}] ${item.content}`);
+        }
+        lines.push('');
+    }
+    lines.push('INSTRUCTIONS:');
+    lines.push('1. Run TaskList to see any pending tasks from the previous session');
+    lines.push('2. Check git status to see what has been done');
+    lines.push('3. Review the codebase for any partial changes');
+    lines.push('4. Continue from where the previous session left off');
+    lines.push('5. If work appears complete, verify and create PR if needed');
+    lines.push('');
+    lines.push(`Original prompt: ${state.prompt}`);
+    return lines.join('\n');
+}
+/**
+ * Parse environment variable for heartbeat timeout
+ */
+export function getHeartbeatTimeoutFromEnv() {
+    const envValue = process.env.AGENT_HEARTBEAT_TIMEOUT_MS;
+    if (envValue) {
+        const parsed = parseInt(envValue, 10);
+        if (!isNaN(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return DEFAULT_HEARTBEAT_TIMEOUT_MS;
+}
+/**
+ * Parse environment variable for max recovery attempts
+ */
+export function getMaxRecoveryAttemptsFromEnv() {
+    const envValue = process.env.AGENT_MAX_RECOVERY_ATTEMPTS;
+    if (envValue) {
+        const parsed = parseInt(envValue, 10);
+        if (!isNaN(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return DEFAULT_MAX_RECOVERY_ATTEMPTS;
+}