@cleocode/core 2026.3.66 → 2026.3.68

package/dist/agents/agent-schema.js

@@ -0,0 +1,85 @@
+/**
+ * Drizzle ORM schema for the CLEO Agent dimension.
+ *
+ * Defines the `agent_instances` table that tracks live agent processes,
+ * their health (heartbeat protocol), capacity, and error history.
+ *
+ * This is the DB-backed runtime registry -- distinct from the file-based
+ * skill agent registry in `skills/agents/registry.ts` which tracks
+ * installed agent *definitions*. This table tracks running agent *instances*.
+ *
+ * @module agents/agent-schema
+ */
+import { sql } from 'drizzle-orm';
+import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+// ============================================================================
+// Canonical enum constants
+// ============================================================================
+/** Agent instance status values matching DB CHECK constraint. */
+export const AGENT_INSTANCE_STATUSES = [
+    'starting',
+    'active',
+    'idle',
+    'error',
+    'crashed',
+    'stopped',
+];
+/** Agent type values for classification. */
+export const AGENT_TYPES = [
+    'orchestrator',
+    'executor',
+    'researcher',
+    'architect',
+    'validator',
+    'documentor',
+    'custom',
+];
+// ============================================================================
+// Agent Instances Table
+// ============================================================================
+export const agentInstances = sqliteTable('agent_instances', {
+    id: text('id').primaryKey(),
+    agentType: text('agent_type', { enum: AGENT_TYPES }).notNull(),
+    status: text('status', { enum: AGENT_INSTANCE_STATUSES }).notNull().default('starting'),
+    // T033: FK constraints enforced at DB level by migration; kept soft here
+    // to avoid circular dependency with tasks-schema.ts (which imports agent-schema.ts).
+    // The migration SQL adds: session_id -> sessions ON DELETE SET NULL,
+    //                         task_id -> tasks ON DELETE SET NULL,
+    //                         parent_agent_id -> agent_instances ON DELETE SET NULL.
+    sessionId: text('session_id'),
+    taskId: text('task_id'),
+    startedAt: text('started_at').notNull().default(sql `(datetime('now'))`),
+    lastHeartbeat: text('last_heartbeat').notNull().default(sql `(datetime('now'))`),
+    stoppedAt: text('stopped_at'),
+    errorCount: integer('error_count').notNull().default(0),
+    totalTasksCompleted: integer('total_tasks_completed').notNull().default(0),
+    capacity: text('capacity').notNull().default('1.0'),
+    metadataJson: text('metadata_json').default('{}'),
+    parentAgentId: text('parent_agent_id'),
+}, (table) => [
+    index('idx_agent_instances_status').on(table.status),
+    index('idx_agent_instances_agent_type').on(table.agentType),
+    index('idx_agent_instances_session_id').on(table.sessionId),
+    index('idx_agent_instances_task_id').on(table.taskId),
+    index('idx_agent_instances_parent_agent_id').on(table.parentAgentId),
+    index('idx_agent_instances_last_heartbeat').on(table.lastHeartbeat),
+]);
+// ============================================================================
+// Agent Error Log Table
+// ============================================================================
+export const agentErrorLog = sqliteTable('agent_error_log', {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    agentId: text('agent_id').notNull(),
+    errorType: text('error_type', {
+        enum: ['retriable', 'permanent', 'unknown'],
+    }).notNull(),
+    message: text('message').notNull(),
+    stack: text('stack'),
+    occurredAt: text('occurred_at').notNull().default(sql `(datetime('now'))`),
+    resolved: integer('resolved', { mode: 'boolean' }).notNull().default(false),
+}, (table) => [
+    index('idx_agent_error_log_agent_id').on(table.agentId),
+    index('idx_agent_error_log_error_type').on(table.errorType),
+    index('idx_agent_error_log_occurred_at').on(table.occurredAt),
+]);
+//# sourceMappingURL=agent-schema.js.map

package/dist/agents/agent-schema.js.map

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

package/dist/agents/capacity.js

@@ -0,0 +1,116 @@
+/**
+ * Capacity tracking and load balancing for the Agent dimension.
+ *
+ * Tracks per-agent capacity (0.0-1.0) and provides queries for
+ * capacity-aware work distribution.
+ *
+ * @module agents/capacity
+ */
+import { eq } from 'drizzle-orm';
+import { getDb } from '../store/sqlite.js';
+import { agentInstances } from './agent-schema.js';
+import { listAgentInstances } from './registry.js';
+// ============================================================================
+// Capacity Updates
+// ============================================================================
+/**
+ * Update the capacity value for an agent instance.
+ *
+ * @param id - Agent instance ID
+ * @param capacity - New capacity value (0.0 to 1.0)
+ * @param cwd - Working directory
+ * @returns Updated agent row, or null if not found
+ */
+export async function updateCapacity(id, capacity, cwd) {
+    if (capacity < 0 || capacity > 1) {
+        throw new Error(`Capacity must be between 0.0 and 1.0, got ${capacity}`);
+    }
+    const db = await getDb(cwd);
+    const existing = await db.select().from(agentInstances).where(eq(agentInstances.id, id)).get();
+    if (!existing)
+        return null;
+    const capacityStr = capacity.toFixed(4);
+    await db.update(agentInstances).set({ capacity: capacityStr }).where(eq(agentInstances.id, id));
+    return { ...existing, capacity: capacityStr };
+}
+// ============================================================================
+// Capacity Queries
+// ============================================================================
+/**
+ * Get the total available capacity across all active agents.
+ *
+ * Only considers agents in 'active' or 'idle' status.
+ * Returns the sum of all capacity values.
+ */
+export async function getAvailableCapacity(cwd) {
+    const agents = await listAgentInstances({ status: ['active', 'idle'] }, cwd);
+    return agents.reduce((sum, agent) => sum + parseCapacity(agent.capacity), 0);
+}
+/**
+ * Find the agent with the most available capacity.
+ *
+ * @param agentType - Optional type filter
+ * @param cwd - Working directory
+ * @returns Agent with highest capacity, or null if no active agents
+ */
+export async function findLeastLoadedAgent(agentType, cwd) {
+    const filters = agentType
+        ? { status: ['active', 'idle'], agentType }
+        : { status: ['active', 'idle'] };
+    const agents = await listAgentInstances(filters, cwd);
+    if (agents.length === 0)
+        return null;
+    let best = agents[0];
+    let bestCapacity = parseCapacity(best.capacity);
+    for (let i = 1; i < agents.length; i++) {
+        const cap = parseCapacity(agents[i].capacity);
+        if (cap > bestCapacity) {
+            best = agents[i];
+            bestCapacity = cap;
+        }
+    }
+    return best;
+}
+/**
+ * Check if the system is overloaded (total capacity below threshold).
+ *
+ * @param threshold - Minimum acceptable capacity (default: 0.1)
+ * @param cwd - Working directory
+ * @returns true if total available capacity is below the threshold
+ */
+export async function isOverloaded(threshold = 0.1, cwd) {
+    const capacity = await getAvailableCapacity(cwd);
+    return capacity < threshold;
+}
+/**
+ * Get a capacity summary across the entire agent pool.
+ *
+ * @param threshold - Overload threshold (default: 0.1)
+ * @param cwd - Working directory
+ */
+export async function getCapacitySummary(threshold = 0.1, cwd) {
+    const agents = await listAgentInstances({ status: ['active', 'idle'] }, cwd);
+    const totalCapacity = agents.reduce((sum, a) => sum + parseCapacity(a.capacity), 0);
+    const activeAgentCount = agents.length;
+    return {
+        totalCapacity,
+        activeAgentCount,
+        averageCapacity: activeAgentCount > 0 ? totalCapacity / activeAgentCount : 0,
+        overloaded: totalCapacity < threshold,
+        threshold,
+    };
+}
+// ============================================================================
+// Utilities
+// ============================================================================
+/**
+ * Parse a capacity string to a number.
+ * The DB stores capacity as TEXT to avoid floating-point representation issues.
+ */
+function parseCapacity(value) {
+    if (!value)
+        return 0;
+    const parsed = parseFloat(value);
+    return Number.isNaN(parsed) ? 0 : Math.max(0, Math.min(1, parsed));
+}
+//# sourceMappingURL=capacity.js.map

package/dist/agents/capacity.js.map

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