@cleocode/core 2026.4.7 → 2026.4.11

package/dist/adrs/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../src/adrs/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC/E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG1C,iFAAiF;AACjF,SAAS,mBAAmB,CAAC,GAAW;IACtC,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAClC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1B,CAAC;AAED,gEAAgE;AAChE,SAAS,YAAY,CAAC,GAAW;IAC/B,OAAO,GAAG;SACP,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACzC,CAAC;AAED,mEAAmE;AACnE,SAAS,eAAe,CAAC,GAAW;IAClC,MAAM,OAAO,GAA6C,EAAE,CAAC;IAC7D,IAAI,OAAmC,CAAC;IACxC,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAClC,IAAI,QAAkB,CAAC;YACvB,IAAI,CAAC;gBACH,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;YAC9B,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS;YACX,CAAC;YACD,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;gBACzB,IAAI,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC5C,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC3D,CAAC;YACH,CAAC;QACH,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACrE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,WAAmB;IACpD,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACnD,MAAM,MAAM,GAAkB,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAElF,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACzB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;IACrD,MAAM,EAAE,EAAE,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IAC3C,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,CAAC;IACpC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAErC,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IAC1C,iEAAiE;IACjE,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IACrE,MAAM,eAAe,GAA8B,EAAE,CAAC;IAEtD,qCAAqC;IACrC,KAAK,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,WAAW,EAAE,CAAC;QAC5C,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACxC,MAAM,MAAM,GAAG,YAAY,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;YACnD,MAAM,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC;YAC9B,MAAM,SAAS,GAAG,cAAc,OAAO,EAAE,CAAC;YAC1C,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAEhD,MAAM,YAAY,GAAG,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,mBAAmB,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAC/E,MAAM,cAAc,GAAG,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAC7F,MAAM,QAAQ,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,mBAAmB,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAEnE,MAAM,OAAO,GAAG;gBACd,EAAE,EAAE,MAAM,CAAC,EAAE;gBACb,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,MAAM,EAAE,EAAE,CAAC,MAAM,IAAI,UAAU;gBAC/B,OAAO;gBACP,QAAQ,EAAE,SAAS;gBACnB,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,EAAE;gBACnB,UAAU,EAAE,EAAE,CAAC,QAAQ,IAAI,IAAI;gBAC/B,IAAI,EAAE,CAAC,EAAE,CAAC,IAAI,IAAI,IAAI,CAAgC;gBACtD,UAAU,EAAE,CAAC,EAAE,CAAC,aAAa,CAAC,IAAI,IAAI,CAA2C;gBACjF,QAAQ;gBACR,YAAY;gBACZ,cAAc;gBACd,OAAO,EAAE,EAAE,CAAC,OAAO,IAAI,IAAI;gBAC3B,QAAQ,EAAE,EAAE,CAAC,QAAQ,IAAI,IAAI;gBAC7B,MAAM,EAAE,EAAE,CAAC,MAAM,IAAI,IAAI;gBACzB,SAAS,EAAE,GAAG;aACN,CAAC;YAEX,MAAM,QAAQ,GAAG,MAAM,EAAE;iBACtB,MAAM,CAAC,EAAE,EAAE,EAAE,qBAAqB,CAAC,EAAE,EAAE,CAAC;iBACxC,IAAI,CAAC,qBAAqB,CAAC;iBAC3B,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;iBAC9C,GAAG,EAAE,CAAC;YAET,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxB,MAAM,EAAE;qBACL,MAAM,CAAC,qBAAqB,CAAC;qBAC7B,GAAG,CAAC,OAAO,CAAC;qBACZ,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;gBAClD,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,CAAC;iBAAM,CAAC;gBACN,MAAM,EAAE,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;gBAC9E,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpB,CAAC;YAED,MAAM,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;YACvE,IAAI,EAAE,CAAC,eAAe,CAAC,EAAE,CAAC;gBACxB,KAAK,MAAM,MAAM,IAAI,YAAY,CAAC,EAAE,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC;oBACvD,MAAM,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;gBAC1F,CAAC;YACH,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IAED,uDAAuD;IACvD,KAAK,MAAM,EAAE,OAAO,EAAE,IAAI,QAAQ,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACxC,MAAM,MAAM,GAAG,YAAY,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;YACnD,MAAM,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC;YAE9B,MAAM,KAAK,GAA4B;gBACrC,EAAE,EAAE,MAAM,CAAC,EAAE;gBACb,IAAI,EAAE,cAAc,OAAO,EAAE;gBAC7B,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,MAAM,EAAE,EAAE,CAAC,MAAM,IAAI,SAAS;gBAC9B,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,EAAE;aACpB,CAAC;YACF,IAAI,EAAE,CAAC,QAAQ;gBAAE,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC;YACjD,IAAI,EAAE,CAAC,UAAU;gBAAE,KAAK,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC;YACvD,IAAI,EAAE,CAAC,eAAe,CAAC;gBAAE,KAAK,CAAC,cAAc,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,CAAC;YACrE,IAAI,EAAE,CAAC,MAAM;gBAAE,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC;YAC3C,IAAI,EAAE,CAAC,YAAY,CAAC;gBAAE,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,CAAC;YAC5D,IAAI,EAAE,CAAC,eAAe,CAAC,EAAE,CAAC;gBACxB,KAAK,CAAC,cAAc,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC;qBACxC,KAAK,CAAC,GAAG,CAAC;qBACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;qBACpB,MAAM,CAAC,OAAO,CAAC,CAAC;YACrB,CAAC;YACD,IAAI,EAAE,CAAC,IAAI;gBAAE,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;YACrC,IAAI,EAAE,CAAC,aAAa,CAAC;gBAAE,KAAK,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC,CAAC;YAC/D,IAAI,EAAE,CAAC,OAAO;gBAAE,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC;YAC9C,IAAI,EAAE,CAAC,QAAQ;gBACb,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC;qBACvC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;qBACpB,MAAM,CAAC,OAAO,CAAC,CAAC;YACrB,IAAI,EAAE,CAAC,MAAM;gBACX,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC;qBACnC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;qBACpB,MAAM,CAAC,OAAO,CAAC,CAAC;YAErB,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,mEAAmE;QACrE,CAAC;IACH,CAAC;IAED,aAAa,CACX,IAAI,CAAC,OAAO,EAAE,gBAAgB,CAAC,EAC/B,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,EAC/D,OAAO,CACR,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/adrs/types.js

@@ -0,0 +1,9 @@
+/**
+ * ADR Core Types (ADR-017)
+ *
+ * Type definitions for parsed ADR frontmatter and operations.
+ *
+ * @task T4792
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/adrs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/adrs/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/adrs/validate.js

@@ -0,0 +1,57 @@
+/**
+ * ADR Frontmatter Validation (ADR-017)
+ *
+ * Validates all ADR markdown files against schemas/adr-frontmatter.schema.json.
+ *
+ * @task T4792
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { default as AjvImport } from 'ajv';
+// Handle ESM/CJS interop for Ajv
+const ajvMod = AjvImport;
+const Ajv = (typeof ajvMod.default === 'function' ? ajvMod.default : AjvImport);
+import { parseAdrFile } from './parse.js';
+/** Validate all ADRs in .cleo/adrs/ against the schema */
+export async function validateAllAdrs(projectRoot) {
+    const adrsDir = join(projectRoot, '.cleo', 'adrs');
+    const schemaPath = join(projectRoot, 'schemas', 'adr-frontmatter.schema.json');
+    if (!existsSync(schemaPath)) {
+        return {
+            valid: false,
+            errors: [
+                {
+                    file: 'schemas/adr-frontmatter.schema.json',
+                    field: 'schema',
+                    message: 'Schema file not found',
+                },
+            ],
+            checked: 0,
+        };
+    }
+    if (!existsSync(adrsDir)) {
+        return { valid: true, errors: [], checked: 0 };
+    }
+    const schema = JSON.parse(readFileSync(schemaPath, 'utf-8'));
+    const ajv = new Ajv({ allErrors: true });
+    const validate = ajv.compile(schema);
+    const files = readdirSync(adrsDir)
+        .filter((f) => f.endsWith('.md') && f.startsWith('ADR-'))
+        .map((f) => join(adrsDir, f));
+    const errors = [];
+    for (const filePath of files) {
+        const record = parseAdrFile(filePath, projectRoot);
+        const valid = validate(record.frontmatter);
+        if (!valid && validate.errors) {
+            for (const err of validate.errors) {
+                errors.push({
+                    file: filePath.replace(projectRoot + '/', ''),
+                    field: err.instancePath ? err.instancePath.replace('/', '') : 'root',
+                    message: err.message ?? 'Validation error',
+                });
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors, checked: files.length };
+}
+//# sourceMappingURL=validate.js.map

package/dist/adrs/validate.js.map

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

package/dist/agents/agent-registry.js

@@ -0,0 +1,288 @@
+/**
+ * Agent registry with capacity tracking for load balancing.
+ *
+ * Provides task-count-based capacity queries, specialization lookup,
+ * and performance recording on top of the existing `agent_instances` schema.
+ *
+ * Capacity model: each agent has a maximum of {@link MAX_TASKS_PER_AGENT}
+ * concurrent tasks. "Remaining capacity" is that constant minus the number of
+ * tasks currently assigned to an active agent instance.
+ *
+ * Specializations are stored as a `specializations` array inside the agent's
+ * `metadata_json` column. Use {@link updateAgentSpecializations} to write them.
+ *
+ * Performance recording delegates to the existing `recordAgentExecution`
+ * function in `execution-learning.ts` and wraps it with a simpler metrics
+ * interface suited for load-balancer callers.
+ *
+ * @module agents/agent-registry
+ * @task T041
+ * @epic T038
+ */
+import { and, eq, inArray } from 'drizzle-orm';
+import { getDb } from '../store/sqlite.js';
+import { agentInstances } from './agent-schema.js';
+import { recordAgentExecution, } from './execution-learning.js';
+import { listAgentInstances } from './registry.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Maximum number of tasks that can be concurrently assigned to one agent.
+ * Used as the upper bound for task-count-based capacity calculation.
+ */
+export const MAX_TASKS_PER_AGENT = 5;
+// ============================================================================
+// Capacity queries
+// ============================================================================
+/**
+ * Get task-count-based remaining capacity for an agent.
+ *
+ * Remaining capacity = {@link MAX_TASKS_PER_AGENT} minus the number of tasks
+ * currently routed to this agent instance (tracked via the `task_id` column
+ * on `agent_instances` — each instance handles one task at a time; child agents
+ * spawned by an orchestrator appear as sibling rows referencing the same
+ * `parent_agent_id`).
+ *
+ * For capacity purposes the "active tasks" count is derived from the number of
+ * non-terminal sibling rows that share the same `parent_agent_id` as this
+ * agent, plus 1 for the agent's own current task when `task_id` is set.
+ *
+ * @remarks
+ * Agents in terminal states (`stopped`, `crashed`) always return 0 remaining
+ * capacity because they cannot accept work.
+ *
+ * @param agentId - Agent instance ID (agt_...) to check
+ * @param cwd - Working directory used to resolve tasks.db path
+ * @returns Capacity breakdown or null if the agent does not exist
+ *
+ * @example
+ * ```ts
+ * const cap = await getAgentCapacity('agt_20260321120000_ab12cd', '/project');
+ * if (cap && cap.available) {
+ *   console.log(`Agent can take ${cap.remainingCapacity} more tasks`);
+ * }
+ * ```
+ */
+export async function getAgentCapacity(agentId, cwd) {
+    const db = await getDb(cwd);
+    const agent = await db.select().from(agentInstances).where(eq(agentInstances.id, agentId)).get();
+    if (!agent)
+        return null;
+    // Terminal agents have zero capacity
+    const isTerminal = agent.status === 'stopped' || agent.status === 'crashed';
+    if (isTerminal) {
+        return {
+            agentId: agent.id,
+            agentType: agent.agentType,
+            status: agent.status,
+            activeTasks: 0,
+            remainingCapacity: 0,
+            maxCapacity: MAX_TASKS_PER_AGENT,
+            available: false,
+        };
+    }
+    // Count active child agents (subtasks delegated by this agent)
+    const children = await db
+        .select({ id: agentInstances.id })
+        .from(agentInstances)
+        .where(and(eq(agentInstances.parentAgentId, agentId), inArray(agentInstances.status, ['starting', 'active', 'idle', 'error'])))
+        .all();
+    // The agent itself counts as 1 active task when it has a task assigned
+    const selfTask = agent.taskId != null ? 1 : 0;
+    const activeTasks = selfTask + children.length;
+    const remainingCapacity = Math.max(0, MAX_TASKS_PER_AGENT - activeTasks);
+    return {
+        agentId: agent.id,
+        agentType: agent.agentType,
+        status: agent.status,
+        activeTasks,
+        remainingCapacity,
+        maxCapacity: MAX_TASKS_PER_AGENT,
+        available: remainingCapacity > 0,
+    };
+}
+/**
+ * List all non-terminal agents sorted by remaining task capacity (descending).
+ *
+ * Returns agents with the most available slots first, enabling callers to
+ * select the least-loaded agent for new work assignment.
+ *
+ * @remarks
+ * Only agents in `active` or `idle` states are included — `starting` agents
+ * are excluded because they may not yet be ready to accept work.
+ * Terminal agents (`stopped`, `crashed`) are always omitted.
+ *
+ * @param agentType - Optional filter to limit results to one agent type
+ * @param cwd - Working directory used to resolve tasks.db path
+ * @returns Array of capacity entries sorted highest remaining capacity first
+ *
+ * @example
+ * ```ts
+ * const agents = await getAgentsByCapacity('executor', '/project');
+ * const best = agents[0]; // most available slots
+ * if (best && best.available) {
+ *   await assignTask(best.agentId, taskId);
+ * }
+ * ```
+ */
+export async function getAgentsByCapacity(agentType, cwd) {
+    const filters = agentType
+        ? { status: ['active', 'idle'], agentType }
+        : { status: ['active', 'idle'] };
+    const activeAgents = await listAgentInstances(filters, cwd);
+    const capacities = await Promise.all(activeAgents.map((agent) => getAgentCapacity(agent.id, cwd)));
+    return capacities
+        .filter((c) => c !== null)
+        .sort((a, b) => b.remainingCapacity - a.remainingCapacity);
+}
+/**
+ * Get the specialization/skills list for an agent.
+ *
+ * Specializations are stored as a string array under the `specializations`
+ * key in the agent's `metadata_json` column. An empty array is returned when
+ * the field is absent or the agent is not found.
+ *
+ * @remarks
+ * Write specializations with {@link updateAgentSpecializations} when
+ * registering or updating an agent. The metadata column is a free-form JSON
+ * blob — specializations are one namespaced key inside it.
+ *
+ * @param agentId - Agent instance ID (agt_...)
+ * @param cwd - Working directory used to resolve tasks.db path
+ * @returns Array of specialization strings (empty if none recorded)
+ *
+ * @example
+ * ```ts
+ * const skills = await getAgentSpecializations('agt_20260321120000_ab12cd', '/project');
+ * // ['typescript', 'testing', 'documentation']
+ * if (skills.includes('typescript')) {
+ *   console.log('Agent can handle TypeScript tasks');
+ * }
+ * ```
+ */
+export async function getAgentSpecializations(agentId, cwd) {
+    const db = await getDb(cwd);
+    const agent = await db
+        .select({ metadataJson: agentInstances.metadataJson })
+        .from(agentInstances)
+        .where(eq(agentInstances.id, agentId))
+        .get();
+    if (!agent)
+        return [];
+    try {
+        const meta = JSON.parse(agent.metadataJson ?? '{}');
+        const specs = meta.specializations;
+        if (!Array.isArray(specs))
+            return [];
+        return specs.filter((s) => typeof s === 'string');
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Update the specializations list stored in an agent's metadata.
+ *
+ * Merges the new list into the existing `metadata_json` object, preserving
+ * any other keys already present. Returns the updated specializations list,
+ * or null if the agent was not found.
+ *
+ * @remarks
+ * This is a write-side companion to {@link getAgentSpecializations}. Call it
+ * after {@link registerAgent} to record the skills an agent was spawned with.
+ *
+ * @param agentId - Agent instance ID (agt_...)
+ * @param specializations - New specializations list (replaces existing)
+ * @param cwd - Working directory used to resolve tasks.db path
+ * @returns Updated specializations list, or null if agent not found
+ *
+ * @example
+ * ```ts
+ * await updateAgentSpecializations(
+ *   'agt_20260321120000_ab12cd',
+ *   ['typescript', 'testing'],
+ *   '/project',
+ * );
+ * ```
+ */
+export async function updateAgentSpecializations(agentId, specializations, cwd) {
+    const db = await getDb(cwd);
+    const agent = await db
+        .select({ metadataJson: agentInstances.metadataJson })
+        .from(agentInstances)
+        .where(eq(agentInstances.id, agentId))
+        .get();
+    if (!agent)
+        return null;
+    let existing = {};
+    try {
+        existing = JSON.parse(agent.metadataJson ?? '{}');
+    }
+    catch {
+        // Proceed with empty object if metadata is unparseable
+    }
+    const updated = { ...existing, specializations };
+    await db
+        .update(agentInstances)
+        .set({ metadataJson: JSON.stringify(updated) })
+        .where(eq(agentInstances.id, agentId));
+    return specializations;
+}
+// ============================================================================
+// Performance recording
+// ============================================================================
+/**
+ * Record agent performance metrics to the BRAIN execution history.
+ *
+ * Translates a simplified {@link AgentPerformanceMetrics} object into the
+ * {@link AgentExecutionEvent} format expected by `execution-learning.ts` and
+ * delegates to {@link recordAgentExecution}. The agent type is resolved from
+ * the `agent_instances` table so callers only need to supply the agent ID.
+ *
+ * @remarks
+ * Recording is best-effort — if brain.db is unavailable the error is swallowed
+ * and null is returned, consistent with the rest of the execution-learning
+ * module. Agent lifecycle code is never disrupted by a brain write failure.
+ *
+ * @param agentId - Agent instance ID whose performance is being recorded
+ * @param metrics - Performance metrics for the task that was processed
+ * @param cwd - Working directory used to resolve tasks.db and brain.db paths
+ * @returns The brain decision ID if recorded, null on failure or not found
+ *
+ * @example
+ * ```ts
+ * const decisionId = await recordAgentPerformance('agt_20260321120000_ab12cd', {
+ *   taskId: 'T041',
+ *   taskType: 'task',
+ *   outcome: 'success',
+ *   durationMs: 4200,
+ *   sessionId: 'ses_20260321_abc',
+ * }, '/project');
+ * ```
+ */
+export async function recordAgentPerformance(agentId, metrics, cwd) {
+    const db = await getDb(cwd);
+    const agent = await db
+        .select({ agentType: agentInstances.agentType, sessionId: agentInstances.sessionId })
+        .from(agentInstances)
+        .where(eq(agentInstances.id, agentId))
+        .get();
+    if (!agent)
+        return null;
+    const event = {
+        agentId,
+        agentType: agent.agentType,
+        taskId: metrics.taskId,
+        taskType: metrics.taskType,
+        outcome: metrics.outcome,
+        taskLabels: metrics.taskLabels,
+        sessionId: metrics.sessionId ?? agent.sessionId ?? undefined,
+        durationMs: metrics.durationMs,
+        errorMessage: metrics.errorMessage,
+        errorType: metrics.errorType,
+    };
+    const decision = await recordAgentExecution(event, cwd);
+    return decision?.id ?? null;
+}
+//# sourceMappingURL=agent-registry.js.map

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

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

package/dist/agents/agent-schema.d.ts

@@ -54,7 +54,7 @@ export declare const agentInstances: import("drizzle-orm/sqlite-core").SQLiteTab
             name: string;
             tableName: "agent_instances";
             dataType: "string enum";
-            data: "error" | "starting" | "active" | "idle" | "crashed" | "stopped";
+            data: "error" | "active" | "starting" | "idle" | "crashed" | "stopped";
             driverParam: string;
             notNull: true;
             hasDefault: true;
@@ -269,7 +269,7 @@ export declare const agentErrorLog: import("drizzle-orm/sqlite-core").SQLiteTabl
             name: string;
             tableName: "agent_error_log";
             dataType: "string enum";
-            data: "retriable" | "permanent" | "unknown";
+            data: "unknown" | "retriable" | "permanent";
             driverParam: string;
             notNull: true;
             hasDefault: false;

package/dist/agents/agent-schema.js

@@ -0,0 +1,82 @@
+/**
+ * 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'),
+    // Soft references — no DB-level FK (SQLite cannot ALTER TABLE ADD CONSTRAINT).
+    // Application-layer validation via agentExistsInSignaldockDb (T238).
+    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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"}