@cleocode/core 2026.3.58 → 2026.3.60

package/dist/agents/execution-learning.js

@@ -0,0 +1,474 @@
+/**
+ * Agent Execution Learning — Agent dimension BRAIN integration.
+ *
+ * Tracks which agent types succeed or fail on which task types, logs agent
+ * decisions to brain_decisions with structured context, provides queries to
+ * retrieve agent performance history, and implements basic self-healing by
+ * recording failure patterns as brain_observations and surfacing healing
+ * suggestions when the same failure pattern recurs.
+ *
+ * This module bridges the agent registry (tasks.db) with the cognitive
+ * memory layer (brain.db) without introducing circular dependencies:
+ * - Tasks.db agent tables: agent_instances, agent_error_log (agent-schema.ts)
+ * - Brain.db tables: brain_decisions, brain_patterns, brain_observations
+ *
+ * All brain.db writes are best-effort — failures are silently swallowed so
+ * agent lifecycle events never fail due to a brain.db write error.
+ *
+ * @module agents/execution-learning
+ * @task T034
+ * @epic T029
+ */
+import { randomBytes } from 'node:crypto';
+import { getBrainAccessor } from '../store/brain-accessor.js';
+// ============================================================================
+// ID generation helpers
+// ============================================================================
+/** Generate a unique brain_decisions ID with `AGT-` prefix. */
+function generateDecisionId() {
+    return `AGT-${randomBytes(5).toString('hex')}`;
+}
+/** Generate a unique brain_patterns ID with `P-agt-` prefix. */
+function generatePatternId() {
+    return `P-agt-${randomBytes(4).toString('hex')}`;
+}
+/** Generate a unique brain_observations ID with `O-agt-` prefix. */
+function generateObservationId() {
+    return `O-agt-${randomBytes(4).toString('hex')}`;
+}
+/** Normalised ISO timestamp in SQLite-friendly format (space separator). */
+function nowSql() {
+    return new Date().toISOString().replace('T', ' ').slice(0, 19);
+}
+// ============================================================================
+// Execution event logging
+// ============================================================================
+/**
+ * Record an agent execution event to brain_decisions.
+ *
+ * Each event becomes a `tactical` decision entry describing which agent type
+ * handled which task type and whether it succeeded. This gives the BRAIN
+ * system a queryable history of agent-task execution for pattern extraction.
+ *
+ * The call is best-effort — if brain.db is unavailable the error is swallowed
+ * and null is returned so agent lifecycle code is never disrupted.
+ *
+ * @param event - Execution event to record
+ * @param cwd - Working directory (resolves brain.db path)
+ * @returns The stored decision row, or null on failure
+ */
+export async function recordAgentExecution(event, cwd) {
+    try {
+        const brain = await getBrainAccessor(cwd);
+        return await _recordAgentExecutionWithAccessor(event, brain);
+    }
+    catch {
+        // Best-effort — never propagate brain.db write failures to callers
+        return null;
+    }
+}
+/**
+ * Internal implementation that accepts a pre-constructed accessor.
+ * Separated for testability without touching the real file system.
+ *
+ * @internal
+ */
+export async function _recordAgentExecutionWithAccessor(event, brain) {
+    const id = generateDecisionId();
+    const outcomeMap = {
+        success: 'success',
+        failure: 'failure',
+        partial: 'mixed',
+    };
+    const decisionText = `Agent type "${event.agentType}" ${event.outcome === 'success' ? 'successfully completed' : `failed (${event.errorType ?? 'unknown'}) on`} task ${event.taskId} (type: ${event.taskType})`;
+    const rationale = [
+        `Agent: ${event.agentId}`,
+        `Task type: ${event.taskType}`,
+        `Outcome: ${event.outcome}`,
+        event.taskLabels?.length ? `Labels: ${event.taskLabels.join(', ')}` : null,
+        event.errorMessage ? `Error: ${event.errorMessage}` : null,
+        event.durationMs != null ? `Duration: ${event.durationMs}ms` : null,
+    ]
+        .filter(Boolean)
+        .join(' | ');
+    const alternativesJson = JSON.stringify({
+        agentId: event.agentId,
+        agentType: event.agentType,
+        taskType: event.taskType,
+        taskLabels: event.taskLabels ?? [],
+        errorType: event.errorType ?? null,
+        durationMs: event.durationMs ?? null,
+        sessionId: event.sessionId ?? null,
+    });
+    const row = await brain.addDecision({
+        id,
+        type: 'tactical',
+        decision: decisionText,
+        rationale,
+        confidence: event.outcome === 'success' ? 'high' : event.outcome === 'partial' ? 'medium' : 'low',
+        outcome: outcomeMap[event.outcome],
+        alternativesJson,
+        contextTaskId: event.taskId,
+        contextEpicId: null,
+        contextPhase: null,
+        createdAt: nowSql(),
+        updatedAt: null,
+    });
+    return row;
+}
+// ============================================================================
+// Performance queries
+// ============================================================================
+/**
+ * Retrieve agent execution performance history from brain_decisions.
+ *
+ * Queries all `tactical` decisions recorded by `recordAgentExecution` and
+ * aggregates them into per-(agentType, taskType) performance summaries.
+ *
+ * @param filters - Optional filters to narrow results
+ * @param cwd - Working directory
+ * @returns Array of performance summaries sorted by agentType then taskType
+ */
+export async function getAgentPerformanceHistory(filters = {}, cwd) {
+    try {
+        const brain = await getBrainAccessor(cwd);
+        return await _getAgentPerformanceHistoryWithAccessor(filters, brain);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Internal implementation with injected accessor for testability.
+ *
+ * @internal
+ */
+export async function _getAgentPerformanceHistoryWithAccessor(filters, brain) {
+    const decisions = await brain.findDecisions({
+        type: 'tactical',
+        limit: filters.limit ?? 500,
+    });
+    // Only process rows that were written by recordAgentExecution
+    const agentDecisions = decisions.filter((d) => d.id.startsWith('AGT-'));
+    // Aggregate per (agentType, taskType)
+    const buckets = new Map();
+    for (const d of agentDecisions) {
+        let meta = {};
+        try {
+            meta = d.alternativesJson ? JSON.parse(d.alternativesJson) : {};
+        }
+        catch {
+            continue;
+        }
+        const agentType = meta.agentType;
+        const taskType = meta.taskType;
+        if (!agentType || !taskType)
+            continue;
+        // Apply optional filters
+        if (filters.agentType && agentType !== filters.agentType)
+            continue;
+        if (filters.taskType && taskType !== filters.taskType)
+            continue;
+        const key = `${agentType}::${taskType}`;
+        const existing = buckets.get(key) ?? {
+            agentType,
+            taskType,
+            successes: 0,
+            failures: 0,
+            total: 0,
+            lastOutcome: null,
+            lastSeenAt: null,
+        };
+        existing.total += 1;
+        const outcome = d.outcome;
+        if (outcome === 'success') {
+            existing.successes += 1;
+            existing.lastOutcome = 'success';
+        }
+        else if (outcome === 'failure') {
+            existing.failures += 1;
+            existing.lastOutcome = 'failure';
+        }
+        else if (outcome === 'mixed') {
+            existing.lastOutcome = 'partial';
+        }
+        // Track most-recent timestamp
+        if (!existing.lastSeenAt || (d.createdAt && d.createdAt > existing.lastSeenAt)) {
+            existing.lastSeenAt = d.createdAt;
+        }
+        buckets.set(key, existing);
+    }
+    return Array.from(buckets.values())
+        .map((b) => ({
+        agentType: b.agentType,
+        taskType: b.taskType,
+        totalAttempts: b.total,
+        successCount: b.successes,
+        failureCount: b.failures,
+        successRate: b.total > 0 ? Math.round((b.successes / b.total) * 1000) / 1000 : 0,
+        lastOutcome: b.lastOutcome,
+        lastSeenAt: b.lastSeenAt,
+    }))
+        .sort((a, b) => a.agentType.localeCompare(b.agentType) || a.taskType.localeCompare(b.taskType));
+}
+// ============================================================================
+// Failure pattern recording
+// ============================================================================
+/**
+ * Record a task failure pattern to brain_patterns.
+ *
+ * When a task fails, the (agentType, taskType, errorType) combination is
+ * stored as a `failure` pattern in brain.db. On subsequent failures matching
+ * the same combination, the frequency counter is incremented and the success
+ * rate updated. This data is what powers `getSelfHealingSuggestions`.
+ *
+ * The call is best-effort and never throws.
+ *
+ * @param event - A failure execution event (outcome must be 'failure')
+ * @param cwd - Working directory
+ * @returns The upserted pattern row, or null on error
+ */
+export async function recordFailurePattern(event, cwd) {
+    if (event.outcome !== 'failure')
+        return null;
+    try {
+        const brain = await getBrainAccessor(cwd);
+        return await _recordFailurePatternWithAccessor(event, brain);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Internal implementation with injected accessor.
+ *
+ * @internal
+ */
+export async function _recordFailurePatternWithAccessor(event, brain) {
+    const errorType = event.errorType ?? 'unknown';
+    const patternText = `Agent type "${event.agentType}" fails on task type "${event.taskType}" with ${errorType} error`;
+    const contextText = `Failure pattern detected: ${event.agentType} agent encountering ${errorType} errors on ${event.taskType} tasks`;
+    // Look for an existing matching pattern (search by prefix naming convention)
+    const existing = await brain.findPatterns({ type: 'failure', limit: 200 });
+    const match = existing.find((p) => p.pattern === patternText);
+    if (match) {
+        // Update frequency counter and keep success_rate at 0 (all failures)
+        const newFrequency = match.frequency + 1;
+        const suggestion = buildHealingSuggestion(event.agentType, event.taskType, errorType, newFrequency);
+        await brain.updatePattern(match.id, {
+            frequency: newFrequency,
+            successRate: 0,
+            mitigation: suggestion,
+        });
+        return {
+            ...match,
+            frequency: newFrequency,
+            successRate: 0,
+            mitigation: suggestion,
+        };
+    }
+    // Create new failure pattern
+    const id = generatePatternId();
+    const now = nowSql();
+    const suggestion = buildHealingSuggestion(event.agentType, event.taskType, errorType, 1);
+    return brain.addPattern({
+        id,
+        type: 'failure',
+        pattern: patternText,
+        context: contextText,
+        frequency: 1,
+        successRate: 0,
+        impact: 'medium',
+        antiPattern: `${event.agentType} assigned to ${event.taskType} task with ${errorType} error risk`,
+        mitigation: suggestion,
+        examplesJson: JSON.stringify([event.taskId]),
+        extractedAt: now,
+        updatedAt: null,
+    });
+}
+// ============================================================================
+// Self-healing: observation storage
+// ============================================================================
+/**
+ * Store a healing strategy observation to brain_observations.
+ *
+ * When a failure pattern reaches a significant frequency threshold (≥ 3),
+ * a `change` observation is recorded to represent the healing action
+ * recommended for future recurrences of the same pattern.
+ *
+ * The call is best-effort and never throws.
+ *
+ * @param event - The failure event that triggered healing
+ * @param strategy - Human-readable healing strategy description
+ * @param cwd - Working directory
+ * @returns The stored observation row, or null on error
+ */
+export async function storeHealingStrategy(event, strategy, cwd) {
+    if (event.outcome !== 'failure')
+        return null;
+    try {
+        const brain = await getBrainAccessor(cwd);
+        return await _storeHealingStrategyWithAccessor(event, strategy, brain);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Internal implementation with injected accessor.
+ *
+ * @internal
+ */
+export async function _storeHealingStrategyWithAccessor(event, strategy, brain) {
+    const id = generateObservationId();
+    const now = nowSql();
+    return brain.addObservation({
+        id,
+        type: 'change',
+        title: `Healing strategy: ${event.agentType} on ${event.taskType}`,
+        subtitle: `Error type: ${event.errorType ?? 'unknown'}`,
+        narrative: strategy,
+        factsJson: JSON.stringify([
+            `Agent: ${event.agentType}`,
+            `Task type: ${event.taskType}`,
+            `Error: ${event.errorMessage ?? 'unspecified'}`,
+            `Suggested action: ${strategy}`,
+        ]),
+        conceptsJson: JSON.stringify([
+            'self-healing',
+            'agent-execution',
+            event.agentType,
+            event.taskType,
+        ]),
+        project: null,
+        filesReadJson: null,
+        filesModifiedJson: null,
+        sourceSessionId: event.sessionId ?? null,
+        sourceType: 'agent',
+        contentHash: null,
+        discoveryTokens: null,
+        createdAt: now,
+        updatedAt: null,
+    });
+}
+// ============================================================================
+// Self-healing: suggestion retrieval
+// ============================================================================
+/**
+ * Get self-healing suggestions for a given agent type and task type.
+ *
+ * Queries brain_patterns for known failure patterns matching the
+ * (agentType, taskType) combination and returns healing suggestions
+ * ordered by frequency (most-seen first).
+ *
+ * Returns an empty array if no failure patterns are found or brain.db
+ * is unavailable.
+ *
+ * @param agentType - The agent type to check
+ * @param taskType - The task type to check
+ * @param cwd - Working directory
+ * @returns Array of healing suggestions, highest frequency first
+ */
+export async function getSelfHealingSuggestions(agentType, taskType, cwd) {
+    try {
+        const brain = await getBrainAccessor(cwd);
+        return await _getSelfHealingSuggestionsWithAccessor(agentType, taskType, brain);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Internal implementation with injected accessor.
+ *
+ * @internal
+ */
+export async function _getSelfHealingSuggestionsWithAccessor(agentType, taskType, brain) {
+    const patterns = await brain.findPatterns({ type: 'failure', limit: 200 });
+    const prefix = `Agent type "${agentType}" fails on task type "${taskType}"`;
+    const matches = patterns.filter((p) => p.pattern.startsWith(prefix) && p.mitigation);
+    return matches
+        .map((p) => ({
+        patternId: p.id,
+        failurePattern: p.pattern,
+        frequency: p.frequency,
+        suggestion: p.mitigation,
+        confidence: Math.min(0.3 + p.frequency * 0.1, 0.9),
+    }))
+        .sort((a, b) => b.frequency - a.frequency);
+}
+// ============================================================================
+// Compound: record event + update patterns + suggest healing
+// ============================================================================
+/**
+ * Full agent lifecycle event processor.
+ *
+ * Convenience function that:
+ * 1. Records the execution event to brain_decisions
+ * 2. On failure: records/updates the failure pattern in brain_patterns
+ * 3. On failure with frequency ≥ 3: stores a healing strategy observation
+ *
+ * Returns a structured result with the recorded IDs and any healing
+ * suggestions that now apply.
+ *
+ * All operations are best-effort — the call never throws.
+ *
+ * @param event - The execution event
+ * @param cwd - Working directory
+ */
+export async function processAgentLifecycleEvent(event, cwd) {
+    const result = {
+        decisionId: null,
+        patternId: null,
+        observationId: null,
+        healingSuggestions: [],
+    };
+    try {
+        const brain = await getBrainAccessor(cwd);
+        // 1. Record decision
+        const decision = await _recordAgentExecutionWithAccessor(event, brain);
+        if (decision)
+            result.decisionId = decision.id;
+        // 2. On failure: record/update failure pattern
+        if (event.outcome === 'failure') {
+            const pattern = await _recordFailurePatternWithAccessor(event, brain);
+            if (pattern) {
+                result.patternId = pattern.id;
+                // 3. When pattern is well-established, store a healing strategy observation
+                if (pattern.frequency >= 3 && pattern.mitigation) {
+                    const obs = await _storeHealingStrategyWithAccessor(event, pattern.mitigation, brain);
+                    if (obs)
+                        result.observationId = obs.id;
+                }
+            }
+        }
+        // 4. Retrieve current suggestions (applies to all outcomes — useful for
+        //    monitoring even successful retries of previously-failing patterns)
+        if (event.outcome !== 'success') {
+            result.healingSuggestions = await _getSelfHealingSuggestionsWithAccessor(event.agentType, event.taskType, brain);
+        }
+    }
+    catch {
+        // Best-effort — never propagate failures
+    }
+    return result;
+}
+// ============================================================================
+// Internal: healing suggestion builder
+// ============================================================================
+/**
+ * Build a human-readable healing mitigation string for a failure pattern.
+ */
+function buildHealingSuggestion(agentType, taskType, errorType, frequency) {
+    if (errorType === 'retriable') {
+        return `Retry with exponential backoff. Consider switching to a different ${agentType} agent instance if failures exceed threshold (seen ${frequency}x).`;
+    }
+    if (errorType === 'permanent') {
+        return `Reassign task to a different agent type — ${agentType} has a permanent failure on ${taskType} tasks. Check permissions, inputs, and dependencies (seen ${frequency}x).`;
+    }
+    if (frequency >= 5) {
+        return `High-frequency unknown failure (${frequency}x): escalate to orchestrator for manual investigation of ${agentType} on ${taskType} tasks.`;
+    }
+    return `Unknown failure for ${agentType} on ${taskType} tasks (${frequency}x). Check agent logs, retry with fresh context, or reassign to a different agent type.`;
+}
+//# sourceMappingURL=execution-learning.js.map

package/dist/agents/execution-learning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-learning.js","sourceRoot":"","sources":["../../src/agents/execution-learning.ts"],"names":[],"mappings":"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"}

package/dist/agents/health-monitor.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Agent Health Monitoring -- Heartbeat and crash detection for live agent instances.
+ *
+ * Provides the public-facing health API specified by T039:
+ *   - `recordHeartbeat`    — update last_heartbeat for a live agent
+ *   - `checkAgentHealth`   — check health of a specific agent by ID
+ *   - `detectStaleAgents`  — find agents whose heartbeat is older than threshold
+ *   - `detectCrashedAgents` — find active agents with no heartbeat for >3 min
+ *
+ * These functions delegate to the lower-level `registry.ts` primitives
+ * (`heartbeat`, `checkAgentHealth`, `listAgentInstances`) and add the
+ * named, task-spec-aligned surface required for T039.
+ *
+ * @module agents/health-monitor
+ * @task T039
+ * @epic T038
+ */
+import type { AgentInstanceRow, AgentInstanceStatus } from './agent-schema.js';
+/** Default heartbeat interval (30 seconds) per BRAIN spec. */
+export declare const HEARTBEAT_INTERVAL_MS = 30000;
+/** Default staleness threshold: 3 minutes without a heartbeat. */
+export declare const STALE_THRESHOLD_MS: number;
+/**
+ * Health status of a specific agent instance.
+ */
+export interface AgentHealthStatus {
+    /** Agent instance ID. */
+    agentId: string;
+    /** Current DB status. */
+    status: AgentInstanceStatus;
+    /** ISO timestamp of the last recorded heartbeat. */
+    lastHeartbeat: string;
+    /** Milliseconds since the last heartbeat (at call time). */
+    heartbeatAgeMs: number;
+    /** Whether the agent is considered healthy (heartbeat within threshold). */
+    healthy: boolean;
+    /** Whether the agent is considered stale (heartbeat older than threshold). */
+    stale: boolean;
+    /** Threshold used for staleness determination (ms). */
+    thresholdMs: number;
+}
+/**
+ * Record a heartbeat for an agent instance.
+ *
+ * Updates `last_heartbeat` to the current time and returns the agent's
+ * current {@link AgentInstanceStatus}. Returns `null` if the agent does not
+ * exist or is already in a terminal state (`stopped` / `crashed`).
+ *
+ * This is the primary mechanism by which long-running agents signal liveness.
+ * Call this every {@link HEARTBEAT_INTERVAL_MS} (30 s) from the agent loop.
+ *
+ * @param agentId - The agent instance ID (e.g. `agt_20260322120000_a1b2c3`)
+ * @param cwd - Working directory used to resolve the tasks.db path (optional)
+ * @returns The agent's current status, or `null` if not found / terminal
+ *
+ * @remarks
+ * Terminal agents (`stopped`, `crashed`) will NOT have their heartbeat
+ * updated — the existing status is returned as-is so callers can detect
+ * external shutdown signals.
+ *
+ * @example
+ * ```ts
+ * // Inside the agent's main loop:
+ * const heartbeatTimer = setInterval(async () => {
+ *   const status = await recordHeartbeat(agentId);
+ *   if (status === 'stopped' || status === null) {
+ *     // Orchestrator shut us down — exit cleanly
+ *     clearInterval(heartbeatTimer);
+ *     process.exit(0);
+ *   }
+ * }, HEARTBEAT_INTERVAL_MS);
+ * ```
+ */
+export declare function recordHeartbeat(agentId: string, cwd?: string): Promise<AgentInstanceStatus | null>;
+/**
+ * Check the health of a specific agent instance by ID.
+ *
+ * Queries the agent's current record and returns a structured
+ * {@link AgentHealthStatus} describing staleness, heartbeat age, and
+ * whether the agent is considered healthy relative to `thresholdMs`.
+ *
+ * Returns `null` if the agent ID is not found in the database.
+ *
+ * @param agentId - The agent instance ID to check
+ * @param thresholdMs - Staleness threshold in milliseconds (default: 3 minutes)
+ * @param cwd - Working directory used to resolve the tasks.db path (optional)
+ * @returns {@link AgentHealthStatus} or `null` if the agent does not exist
+ *
+ * @remarks
+ * Returns null if the agent is not found. A non-null result includes
+ * staleness status based on the threshold comparison.
+ *
+ * @example
+ * ```ts
+ * const health = await checkAgentHealth('agt_20260322120000_a1b2c3');
+ * if (health && health.stale) {
+ *   console.log(`Agent stale for ${health.heartbeatAgeMs}ms — presumed crashed`);
+ * }
+ * ```
+ */
+export declare function checkAgentHealth(agentId: string, thresholdMs?: number, cwd?: string): Promise<AgentHealthStatus | null>;
+/**
+ * Find all non-terminal agents whose last heartbeat is older than `thresholdMs`.
+ *
+ * "Stale" means an agent with status `starting`, `active`, or `idle` has
+ * not sent a heartbeat within the threshold window. This is a precursor to
+ * crash detection — a stale agent may still recover if it is under heavy load.
+ *
+ * Agents with status `stopped` or `crashed` are excluded — they are already
+ * in a terminal state and do not participate in the heartbeat protocol.
+ *
+ * @param thresholdMs - Staleness threshold in ms (default: 3 minutes / 180 000 ms)
+ * @param cwd - Working directory used to resolve the tasks.db path (optional)
+ * @returns Array of {@link AgentHealthStatus} for each stale agent, sorted by
+ *   heartbeat age descending (most-stale first)
+ *
+ * @remarks
+ * The default threshold matches the crash-detection window specified in T039:
+ * "timeout detection after 3 minutes".
+ *
+ * @example
+ * ```ts
+ * const stale = await detectStaleAgents();
+ * for (const s of stale) {
+ *   console.log(`${s.agentId} has been stale for ${s.heartbeatAgeMs / 1000}s`);
+ * }
+ * ```
+ */
+export declare function detectStaleAgents(thresholdMs?: number, cwd?: string): Promise<AgentHealthStatus[]>;
+/**
+ * Find agents with status `active` whose heartbeat has been silent for
+ * longer than `thresholdMs`, and mark them as `crashed` in the database.
+ *
+ * An agent is considered crashed when it:
+ * 1. Has status `active` (not `idle`, `starting`, `stopped`, or `crashed`)
+ * 2. Has not sent a heartbeat for longer than `thresholdMs`
+ *
+ * Each detected agent is immediately marked `crashed` via {@link markCrashed},
+ * incrementing its error count and writing a reason to `agent_error_log`.
+ *
+ * @param thresholdMs - Crash threshold in ms (default: 3 minutes / 180 000 ms)
+ * @param cwd - Working directory used to resolve the tasks.db path (optional)
+ * @returns Array of agent instance rows for each agent that was just marked
+ *   `crashed`, sorted by last heartbeat ascending (oldest first).
+ *
+ * @remarks
+ * This function is WRITE-side: it mutates the database. Callers should run
+ * it on a schedule (e.g. every 60 s) from an orchestrator or health watchdog.
+ * For a read-only view, use {@link detectStaleAgents} instead.
+ *
+ * @example
+ * ```ts
+ * // Inside an orchestrator health watchdog:
+ * const crashed = await detectCrashedAgents();
+ * if (crashed.length > 0) {
+ *   logger.warn({ crashed: crashed.map(a => a.id) }, 'Agents marked crashed');
+ * }
+ * ```
+ */
+export declare function detectCrashedAgents(thresholdMs?: number, cwd?: string): Promise<AgentInstanceRow[]>;
+//# sourceMappingURL=health-monitor.d.ts.map

package/dist/agents/health-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-monitor.d.ts","sourceRoot":"","sources":["../../src/agents/health-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAO/E,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C,kEAAkE;AAClE,eAAO,MAAM,kBAAkB,QAAa,CAAC;AAS7C;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,cAAc,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,KAAK,EAAE,OAAO,CAAC;IACf,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAErC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,WAAW,GAAE,MAA2B,EACxC,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAMnC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,iBAAiB,CACrC,WAAW,GAAE,MAA2B,EACxC,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAO9B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,GAAE,MAA2B,EACxC,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA6B7B"}