@cleocode/core 2026.3.57 → 2026.3.58

package/dist/agents/registry.js

@@ -0,0 +1,314 @@
+/**
+ * Agent instance registry -- runtime tracking of live agent processes.
+ *
+ * Provides CRUD operations for the `agent_instances` table:
+ * registration, deregistration, heartbeat, status updates, and queries.
+ *
+ * This is the DB-backed runtime registry for live agent *instances*.
+ * The file-based registry in `skills/agents/registry.ts` tracks installed
+ * agent *definitions* -- those are complementary, not competing, concepts.
+ *
+ * @module agents/registry
+ */
+import { randomBytes } from 'node:crypto';
+import { and, eq, inArray, lt, sql } from 'drizzle-orm';
+import { getDb } from '../store/sqlite.js';
+import { agentErrorLog, agentInstances, } from './agent-schema.js';
+// ============================================================================
+// ID generation
+// ============================================================================
+/**
+ * Generate a unique agent instance ID.
+ * Format: `agt_{YYYYMMDDHHmmss}_{6hex}`
+ */
+export function generateAgentId() {
+    const now = new Date();
+    const ts = now.toISOString().replace(/[-:T]/g, '').substring(0, 14);
+    const hex = randomBytes(3).toString('hex');
+    return `agt_${ts}_${hex}`;
+}
+/**
+ * Register a new agent instance in the database.
+ * Sets initial status to 'starting' and records the first heartbeat.
+ */
+export async function registerAgent(opts, cwd) {
+    const db = await getDb(cwd);
+    const id = generateAgentId();
+    const now = new Date().toISOString();
+    const row = {
+        id,
+        agentType: opts.agentType,
+        status: 'starting',
+        sessionId: opts.sessionId ?? null,
+        taskId: opts.taskId ?? null,
+        startedAt: now,
+        lastHeartbeat: now,
+        stoppedAt: null,
+        errorCount: 0,
+        totalTasksCompleted: 0,
+        capacity: '1.0',
+        metadataJson: opts.metadata ? JSON.stringify(opts.metadata) : '{}',
+        parentAgentId: opts.parentAgentId ?? null,
+    };
+    await db.insert(agentInstances).values(row);
+    return row;
+}
+/**
+ * Deregister (stop) an agent instance.
+ * Sets status to 'stopped' and records the stop timestamp.
+ */
+export async function deregisterAgent(id, cwd) {
+    const db = await getDb(cwd);
+    const now = new Date().toISOString();
+    const existing = await db.select().from(agentInstances).where(eq(agentInstances.id, id)).get();
+    if (!existing)
+        return null;
+    // Already stopped -- idempotent
+    if (existing.status === 'stopped')
+        return existing;
+    await db
+        .update(agentInstances)
+        .set({ status: 'stopped', stoppedAt: now })
+        .where(eq(agentInstances.id, id));
+    return { ...existing, status: 'stopped', stoppedAt: now };
+}
+// ============================================================================
+// Heartbeat
+// ============================================================================
+/**
+ * Record a heartbeat for an agent instance.
+ * Updates `last_heartbeat` and returns the current status so the agent
+ * can detect if it has been externally marked for shutdown.
+ */
+export async function heartbeat(id, cwd) {
+    const db = await getDb(cwd);
+    const now = new Date().toISOString();
+    const existing = await db.select().from(agentInstances).where(eq(agentInstances.id, id)).get();
+    if (!existing)
+        return null;
+    // Do not update heartbeat for terminal states
+    if (existing.status === 'stopped' || existing.status === 'crashed') {
+        return existing.status;
+    }
+    await db.update(agentInstances).set({ lastHeartbeat: now }).where(eq(agentInstances.id, id));
+    return existing.status;
+}
+/**
+ * Update agent status with optional error tracking.
+ * When status is 'error' or 'crashed', increments the error count
+ * and logs the error to the agent_error_log table.
+ */
+export async function updateAgentStatus(id, opts, cwd) {
+    const db = await getDb(cwd);
+    const existing = await db.select().from(agentInstances).where(eq(agentInstances.id, id)).get();
+    if (!existing)
+        return null;
+    const updates = {
+        status: opts.status,
+    };
+    if (opts.taskId !== undefined) {
+        updates.taskId = opts.taskId;
+    }
+    // If transitioning to active, update heartbeat
+    if (opts.status === 'active') {
+        updates.lastHeartbeat = new Date().toISOString();
+    }
+    // Track errors
+    if (opts.status === 'error' || opts.status === 'crashed') {
+        updates.errorCount = existing.errorCount + 1;
+        if (opts.error) {
+            const errorType = classifyError(new Error(opts.error));
+            await db.insert(agentErrorLog).values({
+                agentId: id,
+                errorType,
+                message: opts.error,
+                occurredAt: new Date().toISOString(),
+            });
+        }
+    }
+    // If stopped, set stoppedAt
+    if (opts.status === 'stopped') {
+        updates.stoppedAt = new Date().toISOString();
+    }
+    await db.update(agentInstances).set(updates).where(eq(agentInstances.id, id));
+    return { ...existing, ...updates };
+}
+/**
+ * Increment the completed task count for an agent.
+ */
+export async function incrementTasksCompleted(id, cwd) {
+    const db = await getDb(cwd);
+    await db
+        .update(agentInstances)
+        .set({ totalTasksCompleted: sql `${agentInstances.totalTasksCompleted} + 1` })
+        .where(eq(agentInstances.id, id));
+}
+/**
+ * List agent instances with optional filters.
+ */
+export async function listAgentInstances(filters, cwd) {
+    const db = await getDb(cwd);
+    const conditions = [];
+    if (filters?.status) {
+        const statuses = Array.isArray(filters.status) ? filters.status : [filters.status];
+        conditions.push(inArray(agentInstances.status, statuses));
+    }
+    if (filters?.agentType) {
+        const types = Array.isArray(filters.agentType) ? filters.agentType : [filters.agentType];
+        conditions.push(inArray(agentInstances.agentType, types));
+    }
+    if (filters?.sessionId) {
+        conditions.push(eq(agentInstances.sessionId, filters.sessionId));
+    }
+    if (filters?.parentAgentId) {
+        conditions.push(eq(agentInstances.parentAgentId, filters.parentAgentId));
+    }
+    if (conditions.length === 0) {
+        return db.select().from(agentInstances).all();
+    }
+    return db
+        .select()
+        .from(agentInstances)
+        .where(and(...conditions))
+        .all();
+}
+/**
+ * Get a single agent instance by ID.
+ */
+export async function getAgentInstance(id, cwd) {
+    const db = await getDb(cwd);
+    const row = await db.select().from(agentInstances).where(eq(agentInstances.id, id)).get();
+    return row ?? null;
+}
+// ============================================================================
+// Error classification
+// ============================================================================
+/** Patterns indicating retriable errors. */
+const RETRIABLE_PATTERNS = [
+    /timeout/i,
+    /ECONNREFUSED/,
+    /ECONNRESET/,
+    /EPIPE/,
+    /ETIMEDOUT/,
+    /rate.?limit/i,
+    /429/,
+    /503/,
+    /502/,
+    /SQLITE_BUSY/i,
+    /database is locked/i,
+    /temporarily unavailable/i,
+    /too many requests/i,
+    /network/i,
+    /socket hang up/i,
+];
+/** Patterns indicating permanent (non-retriable) errors. */
+const PERMANENT_PATTERNS = [
+    /permission denied/i,
+    /EACCES/,
+    /authentication/i,
+    /unauthorized/i,
+    /401/,
+    /403/,
+    /404/,
+    /not found/i,
+    /invalid.*token/i,
+    /SQLITE_CONSTRAINT/i,
+    /syntax error/i,
+    /type error/i,
+    /reference error/i,
+];
+/**
+ * Classify an error as retriable, permanent, or unknown.
+ *
+ * Retriable errors are transient conditions (network, rate limits, locks)
+ * where a retry may succeed. Permanent errors are structural (auth,
+ * not found, constraint violations) where retrying is pointless.
+ */
+export function classifyError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    for (const pattern of RETRIABLE_PATTERNS) {
+        if (pattern.test(message))
+            return 'retriable';
+    }
+    for (const pattern of PERMANENT_PATTERNS) {
+        if (pattern.test(message))
+            return 'permanent';
+    }
+    return 'unknown';
+}
+/**
+ * Get the error history for a specific agent.
+ */
+export async function getAgentErrorHistory(agentId, cwd) {
+    const db = await getDb(cwd);
+    return db.select().from(agentErrorLog).where(eq(agentErrorLog.agentId, agentId)).all();
+}
+// ============================================================================
+// Health Monitoring
+// ============================================================================
+/**
+ * Check agent health by finding instances whose last heartbeat exceeds the threshold.
+ * Default threshold: 30000ms (30 seconds) as specified by the BRAIN spec.
+ *
+ * Returns agents that appear to have crashed (stale heartbeat).
+ */
+export async function checkAgentHealth(thresholdMs = 30_000, cwd) {
+    const db = await getDb(cwd);
+    const cutoff = new Date(Date.now() - thresholdMs).toISOString();
+    return db
+        .select()
+        .from(agentInstances)
+        .where(and(inArray(agentInstances.status, ['active', 'idle', 'starting']), lt(agentInstances.lastHeartbeat, cutoff)))
+        .all();
+}
+/**
+ * Mark an agent instance as crashed.
+ * Increments error count and sets status to 'crashed'.
+ */
+export async function markCrashed(id, reason, cwd) {
+    return updateAgentStatus(id, { status: 'crashed', error: reason ?? 'Heartbeat timeout — agent presumed crashed' }, cwd);
+}
+/**
+ * Generate a health report summarizing all agent instances.
+ * Includes counts by status and identifies stale agents.
+ */
+export async function getHealthReport(thresholdMs = 30_000, cwd) {
+    const allAgents = await listAgentInstances(undefined, cwd);
+    const staleAgents = await checkAgentHealth(thresholdMs, cwd);
+    const report = {
+        total: allAgents.length,
+        active: 0,
+        idle: 0,
+        starting: 0,
+        error: 0,
+        crashed: 0,
+        stopped: 0,
+        totalErrors: 0,
+        staleAgents,
+    };
+    for (const agent of allAgents) {
+        switch (agent.status) {
+            case 'active':
+                report.active++;
+                break;
+            case 'idle':
+                report.idle++;
+                break;
+            case 'starting':
+                report.starting++;
+                break;
+            case 'error':
+                report.error++;
+                break;
+            case 'crashed':
+                report.crashed++;
+                break;
+            case 'stopped':
+                report.stopped++;
+                break;
+        }
+        report.totalErrors += agent.errorCount;
+    }
+    return report;
+}
+//# sourceMappingURL=registry.js.map

package/dist/agents/registry.js.map

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

package/dist/agents/retry.js

@@ -0,0 +1,176 @@
+/**
+ * Self-healing and retry logic for the Agent dimension.
+ *
+ * Provides configurable retry policies with exponential backoff + jitter,
+ * and recovery mechanisms for crashed agents. Error classification
+ * determines whether a retry is appropriate.
+ *
+ * @module agents/retry
+ */
+import { checkAgentHealth, classifyError, listAgentInstances, updateAgentStatus, } from './registry.js';
+/** Default retry policy matching the BRAIN specification. */
+export const DEFAULT_RETRY_POLICY = Object.freeze({
+    maxRetries: 3,
+    baseDelayMs: 1_000,
+    maxDelayMs: 30_000,
+    backoffMultiplier: 2,
+    jitter: true,
+    retryOnUnknown: true,
+});
+/**
+ * Create a retry policy by merging overrides with the default policy.
+ */
+export function createRetryPolicy(overrides) {
+    return { ...DEFAULT_RETRY_POLICY, ...overrides };
+}
+/**
+ * Calculate the delay for a given retry attempt using exponential backoff.
+ *
+ * Formula: min(baseDelay * multiplier^attempt, maxDelay) + jitter
+ * Jitter adds 0-25% randomness to prevent thundering herd.
+ */
+export function calculateDelay(attempt, policy) {
+    const exponentialDelay = policy.baseDelayMs * policy.backoffMultiplier ** attempt;
+    const clampedDelay = Math.min(exponentialDelay, policy.maxDelayMs);
+    if (!policy.jitter)
+        return clampedDelay;
+    // Add 0-25% jitter
+    const jitterRange = clampedDelay * 0.25;
+    const jitterValue = Math.random() * jitterRange;
+    return Math.floor(clampedDelay + jitterValue);
+}
+/**
+ * Determine whether an error should be retried based on its classification
+ * and the retry policy.
+ */
+export function shouldRetry(error, attempt, policy) {
+    if (attempt >= policy.maxRetries)
+        return false;
+    const classification = classifyError(error);
+    if (classification === 'permanent')
+        return false;
+    if (classification === 'retriable')
+        return true;
+    // 'unknown' classification -- policy determines behavior
+    return policy.retryOnUnknown;
+}
+/**
+ * Wrap an async function with retry logic using configurable exponential backoff.
+ *
+ * The function will be retried according to the policy when retriable errors
+ * occur. Permanent errors cause immediate failure. Unknown errors respect
+ * the `retryOnUnknown` policy setting.
+ *
+ * @param fn - The async function to execute with retries
+ * @param policy - Retry policy (uses DEFAULT_RETRY_POLICY if not provided)
+ * @returns The result of the operation with retry metadata
+ */
+export async function withRetry(fn, policy) {
+    const effectivePolicy = createRetryPolicy(policy);
+    let lastError;
+    let totalDelayMs = 0;
+    for (let attempt = 0; attempt <= effectivePolicy.maxRetries; attempt++) {
+        try {
+            const value = await fn();
+            return {
+                success: true,
+                value,
+                attempts: attempt + 1,
+                totalDelayMs,
+            };
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            if (!shouldRetry(err, attempt, effectivePolicy)) {
+                return {
+                    success: false,
+                    error: lastError,
+                    attempts: attempt + 1,
+                    totalDelayMs,
+                };
+            }
+            // Calculate and apply delay before next attempt
+            if (attempt < effectivePolicy.maxRetries) {
+                const delay = calculateDelay(attempt, effectivePolicy);
+                totalDelayMs += delay;
+                await sleep(delay);
+            }
+        }
+    }
+    return {
+        success: false,
+        error: lastError ?? new Error('Retry exhausted without error'),
+        attempts: effectivePolicy.maxRetries + 1,
+        totalDelayMs,
+    };
+}
+/**
+ * Attempt to recover crashed agents.
+ *
+ * Finds all agents with status 'crashed' and determines if they can be
+ * restarted based on their error history. Agents whose last error was
+ * classified as 'permanent' are abandoned. Agents with retriable errors
+ * are reset to 'starting' for the orchestration layer to re-assign.
+ *
+ * @param thresholdMs - Heartbeat threshold for crash detection (default: 30000)
+ * @param cwd - Working directory
+ * @returns Recovery results for each crashed agent
+ */
+export async function recoverCrashedAgents(thresholdMs = 30_000, cwd) {
+    const results = [];
+    // Step 1: detect stale agents and mark them crashed
+    const staleAgents = await checkAgentHealth(thresholdMs, cwd);
+    for (const agent of staleAgents) {
+        await updateAgentStatus(agent.id, { status: 'crashed', error: 'Heartbeat timeout detected during recovery sweep' }, cwd);
+    }
+    // Step 2: process all crashed agents
+    const crashedAgents = await listAgentInstances({ status: 'crashed' }, cwd);
+    for (const agent of crashedAgents) {
+        // Check error history to determine recovery action
+        const { getAgentErrorHistory } = await import('./registry.js');
+        const errors = await getAgentErrorHistory(agent.id, cwd);
+        const lastError = errors.length > 0 ? errors[errors.length - 1] : null;
+        // Too many errors -- abandon
+        if (agent.errorCount >= 5) {
+            await updateAgentStatus(agent.id, { status: 'stopped' }, cwd);
+            results.push({
+                agentId: agent.id,
+                recovered: false,
+                action: 'abandoned',
+                reason: `Error count (${agent.errorCount}) exceeds threshold (5)`,
+            });
+            continue;
+        }
+        // Last error was permanent -- abandon
+        if (lastError?.errorType === 'permanent') {
+            await updateAgentStatus(agent.id, { status: 'stopped' }, cwd);
+            results.push({
+                agentId: agent.id,
+                recovered: false,
+                action: 'abandoned',
+                reason: `Permanent error: ${lastError.message}`,
+            });
+            continue;
+        }
+        // Retriable or unknown -- attempt restart by resetting to 'starting'
+        await updateAgentStatus(agent.id, { status: 'starting' }, cwd);
+        results.push({
+            agentId: agent.id,
+            recovered: true,
+            action: 'restarted',
+            reason: 'Agent reset to starting for re-assignment',
+        });
+    }
+    return results;
+}
+// ============================================================================
+// Utilities
+// ============================================================================
+/**
+ * Sleep for a given number of milliseconds.
+ * Extracted for testability.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=retry.js.map

package/dist/agents/retry.js.map

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

package/dist/audit-prune.js

@@ -0,0 +1,94 @@
+/**
+ * Audit log pruning with optional archive-before-delete.
+ *
+ * Prunes audit_log rows older than a configurable retention period.
+ * When archiveBeforePrune is enabled, exports prunable rows to
+ * a gzip-compressed JSONL file before deletion.
+ *
+ * Never throws — logs warnings on failure. Safe for fire-and-forget
+ * startup wiring.
+ *
+ * @task T5339
+ */
+import { createWriteStream, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createGzip } from 'node:zlib';
+import { getLogger } from './logger.js';
+const log = getLogger('prune');
+/**
+ * Prune old audit_log rows from tasks.db.
+ *
+ * 1. If auditRetentionDays is 0 or undefined, skip age-based pruning.
+ * 2. Compute cutoff timestamp from auditRetentionDays.
+ * 3. If archiveBeforePrune, select rows older than cutoff and write to
+ *    .cleo/backups/logs/audit-YYYY-MM-DD.jsonl.gz.
+ * 4. Delete rows older than cutoff from audit_log.
+ *
+ * Idempotent — safe to call multiple times.
+ * Never throws — returns zero counts on any error.
+ *
+ * @param cleoDir  - Absolute path to .cleo directory
+ * @param config   - LoggingConfig with auditRetentionDays and archiveBeforePrune
+ */
+export async function pruneAuditLog(cleoDir, config) {
+    try {
+        if (!config.auditRetentionDays || config.auditRetentionDays <= 0) {
+            log.debug('auditRetentionDays is 0 or unset; skipping audit prune');
+            return { rowsArchived: 0, rowsDeleted: 0 };
+        }
+        const cutoff = new Date(Date.now() - config.auditRetentionDays * 86_400_000).toISOString();
+        // Derive projectRoot from cleoDir (cleoDir = /path/to/project/.cleo)
+        const projectRoot = join(cleoDir, '..');
+        const { getDb } = await import('./store/sqlite.js');
+        const { auditLog } = await import('./store/tasks-schema.js');
+        const { lt } = await import('drizzle-orm');
+        const db = await getDb(projectRoot);
+        // Select rows to prune
+        const oldRows = await db.select().from(auditLog).where(lt(auditLog.timestamp, cutoff));
+        if (oldRows.length === 0) {
+            log.debug('No audit_log rows older than cutoff; nothing to prune');
+            return { rowsArchived: 0, rowsDeleted: 0 };
+        }
+        let archivePath;
+        let rowsArchived = 0;
+        // Archive before pruning (if enabled)
+        if (config.archiveBeforePrune) {
+            try {
+                const archiveDir = join(cleoDir, 'backups', 'logs');
+                mkdirSync(archiveDir, { recursive: true });
+                const dateStamp = new Date().toISOString().slice(0, 10);
+                archivePath = join(archiveDir, `audit-${dateStamp}.jsonl.gz`);
+                // Build JSONL content: one JSON object per line
+                const lines = oldRows.map((row) => JSON.stringify(row));
+                const jsonlContent = lines.join('\n') + '\n';
+                // Gzip compress and write via streaming pipeline
+                const gzip = createGzip();
+                const outStream = createWriteStream(archivePath);
+                const inStream = Readable.from([jsonlContent]);
+                await pipeline(inStream, gzip, outStream);
+                rowsArchived = oldRows.length;
+                log.info({ archivePath, rowsArchived }, `Archived ${rowsArchived} audit rows to ${archivePath}`);
+            }
+            catch (archiveErr) {
+                // Archive failure must NOT prevent pruning — log and continue
+                log.warn({ err: archiveErr }, 'Failed to archive audit rows; continuing with deletion');
+                archivePath = undefined;
+            }
+        }
+        // Delete prunable rows
+        await db.delete(auditLog).where(lt(auditLog.timestamp, cutoff)).run();
+        log.info({ rowsDeleted: oldRows.length, cutoff }, `Pruned ${oldRows.length} audit_log rows older than ${cutoff}`);
+        return {
+            rowsArchived,
+            rowsDeleted: oldRows.length,
+            archivePath,
+        };
+    }
+    catch (err) {
+        log.warn({ err }, 'audit log pruning failed');
+        return { rowsArchived: 0, rowsDeleted: 0 };
+    }
+}
+//# sourceMappingURL=audit-prune.js.map

package/dist/audit-prune.js.map

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