@cleocode/core 2026.3.43 → 2026.3.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/core",
-  "version": "2026.3.43",
+  "version": "2026.3.45",
   "description": "CLEO core business logic kernel — tasks, sessions, memory, orchestration, lifecycle, with bundled SQLite store",
   "type": "module",
   "main": "./dist/index.js",
@@ -36,7 +36,7 @@
     "write-file-atomic": "^6.0.0",
     "yaml": "^2.8.2",
     "zod": "^3.25.76",
-    "@cleocode/contracts": "2026.3.43"
+    "@cleocode/contracts": "2026.3.45"
   },
   "engines": {
     "node": ">=24.0.0"

package/src/admin/export-tasks.ts

@@ -175,15 +175,12 @@ export async function exportTasksPackage(params: ExportTasksParams): Promise<Exp
   }
 
   const projectMeta = await accessor.getMetaValue<{ name?: string }>('project');
-  const taskData = {
-    tasks: allTasks,
-    project: projectMeta,
-  } as import('@cleocode/contracts').TaskFile;
-  const pkg = buildExportPackage(selectedTasks, taskData, {
+  const pkg = buildExportPackage(selectedTasks, {
     mode: exportMode,
     rootTaskIds: parsedIds.length > 0 ? parsedIds : selectedTasks.map((t) => t.id),
     includeChildren: subtreeMode,
     filters: filters.length > 0 ? filters : undefined,
+    projectName: projectMeta?.name,
   });
 
   const content = JSON.stringify(pkg, null, 2);

package/src/admin/import-tasks.ts

@@ -3,13 +3,14 @@
  *
  * Extracted from CLI import-tasks command for dispatch layer access.
  *
- * @task T5323, T5328
+ * @task T5323, T5328, T046
  * @epic T4545
  */
 
 import { constants as fsConstants } from 'node:fs';
 import { access, readFile } from 'node:fs/promises';
 import type { Task, TaskStatus } from '@cleocode/contracts';
+import type { ImportFromPackageOptions, ImportFromPackageResult } from '../nexus/transfer-types.js';
 import { getAccessor } from '../store/data-accessor.js';
 import type { ExportPackage } from '../store/export.js';
 import {
@@ -74,25 +75,13 @@ export interface ImportTasksResult {
 }
 
 /**
- * Import tasks from a cross-project export package with ID remapping.
+ * Import tasks from an in-memory ExportPackage with ID remapping.
+ * Core logic extracted from importTasksPackage for reuse by transfer engine.
  */
-export async function importTasksPackage(params: ImportTasksParams): Promise<ImportTasksResult> {
-  const { file } = params;
-
-  try {
-    await access(file, fsConstants.R_OK);
-  } catch {
-    throw new Error(`Export file not found: ${file}`);
-  }
-
-  const content = await readFile(file, 'utf-8');
-  let exportPkg: ExportPackage;
-  try {
-    exportPkg = JSON.parse(content) as ExportPackage;
-  } catch {
-    throw new Error(`Invalid JSON in: ${file}`);
-  }
-
+export async function importFromPackage(
+  exportPkg: ExportPackage,
+  options: ImportFromPackageOptions = {},
+): Promise<ImportFromPackageResult> {
   if (exportPkg._meta?.format !== 'cleo-export') {
     throw new Error(
       `Invalid export format (expected 'cleo-export', got '${exportPkg._meta?.format}')`,
@@ -103,17 +92,17 @@ export async function importTasksPackage(params: ImportTasksParams): Promise<Imp
     throw new Error('Export package contains no tasks');
   }
 
-  const accessor = await getAccessor(params.cwd);
+  const accessor = await getAccessor(options.cwd);
   const { tasks: existingTasks } = await accessor.queryTasks({});
 
-  const onConflict: OnConflict = params.onConflict ?? 'fail';
-  const onMissingDep: OnMissingDep = params.onMissingDep ?? 'strip';
-  const force = params.force ?? false;
-  const parentId = params.parent;
-  const phaseOverride = params.phase;
-  const addLabel = params.addLabel;
-  const resetStatus = params.resetStatus;
-  const addProvenance = params.provenance !== false;
+  const onConflict: OnConflict = options.onConflict ?? 'fail';
+  const onMissingDep: OnMissingDep = options.onMissingDep === 'fail' ? 'fail' : 'strip';
+  const force = options.force ?? false;
+  const parentId = options.parent;
+  const phaseOverride = options.phase;
+  const addLabel = options.addLabel;
+  const resetStatus = options.resetStatus;
+  const addProvenance = options.provenance !== false;
 
   if (parentId) {
     const parentExists = existingTasks.some((t) => t.id === parentId);
@@ -195,7 +184,7 @@ export async function importTasksPackage(params: ImportTasksParams): Promise<Imp
     existingIds.add(remapped.id);
   }
 
-  if (params.dryRun) {
+  if (options.dryRun) {
     return {
       imported: transformed.length,
       skipped: skipped.length,
@@ -217,3 +206,38 @@ export async function importTasksPackage(params: ImportTasksParams): Promise<Imp
     idRemap: idRemapJson,
   };
 }
+
+/**
+ * Import tasks from a cross-project export package file with ID remapping.
+ * Thin wrapper around importFromPackage that handles file I/O.
+ */
+export async function importTasksPackage(params: ImportTasksParams): Promise<ImportTasksResult> {
+  const { file } = params;
+
+  try {
+    await access(file, fsConstants.R_OK);
+  } catch {
+    throw new Error(`Export file not found: ${file}`);
+  }
+
+  const content = await readFile(file, 'utf-8');
+  let exportPkg: ExportPackage;
+  try {
+    exportPkg = JSON.parse(content) as ExportPackage;
+  } catch {
+    throw new Error(`Invalid JSON in: ${file}`);
+  }
+
+  return importFromPackage(exportPkg, {
+    cwd: params.cwd,
+    dryRun: params.dryRun,
+    parent: params.parent,
+    phase: params.phase,
+    addLabel: params.addLabel,
+    provenance: params.provenance,
+    resetStatus: params.resetStatus,
+    onConflict: params.onConflict,
+    onMissingDep: params.onMissingDep === 'placeholder' ? 'strip' : params.onMissingDep,
+    force: params.force,
+  });
+}

package/src/agents/__tests__/capacity.test.ts

@@ -0,0 +1,219 @@
+/**
+ * Tests for capacity tracking and load balancing.
+ *
+ * @module agents/__tests__/capacity.test
+ */
+
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  findLeastLoadedAgent,
+  getAvailableCapacity,
+  getCapacitySummary,
+  isOverloaded,
+  updateCapacity,
+} from '../capacity.js';
+import { registerAgent, updateAgentStatus } from '../registry.js';
+
+describe('Capacity Tracking', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'cleo-capacity-test-'));
+    await mkdir(join(tempDir, '.cleo'), { recursive: true });
+    await mkdir(join(tempDir, '.cleo', 'backups', 'operational'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    try {
+      const { closeAllDatabases } = await import('../../store/sqlite.js');
+      await closeAllDatabases();
+    } catch {
+      /* module may not be loaded */
+    }
+    await Promise.race([
+      rm(tempDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 300 }).catch(() => {}),
+      new Promise<void>((resolve) => setTimeout(resolve, 8_000)),
+    ]);
+  });
+
+  // ==========================================================================
+  // updateCapacity
+  // ==========================================================================
+
+  describe('updateCapacity', () => {
+    it('updates capacity value', async () => {
+      const agent = await registerAgent({ agentType: 'executor' }, tempDir);
+      const updated = await updateCapacity(agent.id, 0.5, tempDir);
+
+      expect(updated).not.toBeNull();
+      expect(parseFloat(updated!.capacity)).toBeCloseTo(0.5, 4);
+    });
+
+    it('returns null for non-existent agent', async () => {
+      const result = await updateCapacity('agt_nonexistent_abc123', 0.5, tempDir);
+      expect(result).toBeNull();
+    });
+
+    it('rejects capacity below 0', async () => {
+      const agent = await registerAgent({ agentType: 'executor' }, tempDir);
+      await expect(updateCapacity(agent.id, -0.1, tempDir)).rejects.toThrow(
+        'Capacity must be between 0.0 and 1.0',
+      );
+    });
+
+    it('rejects capacity above 1', async () => {
+      const agent = await registerAgent({ agentType: 'executor' }, tempDir);
+      await expect(updateCapacity(agent.id, 1.5, tempDir)).rejects.toThrow(
+        'Capacity must be between 0.0 and 1.0',
+      );
+    });
+
+    it('accepts boundary values', async () => {
+      const agent = await registerAgent({ agentType: 'executor' }, tempDir);
+
+      const zero = await updateCapacity(agent.id, 0, tempDir);
+      expect(parseFloat(zero!.capacity)).toBeCloseTo(0, 4);
+
+      const one = await updateCapacity(agent.id, 1, tempDir);
+      expect(parseFloat(one!.capacity)).toBeCloseTo(1, 4);
+    });
+  });
+
+  // ==========================================================================
+  // getAvailableCapacity
+  // ==========================================================================
+
+  describe('getAvailableCapacity', () => {
+    it('sums capacity of active and idle agents', async () => {
+      const a1 = await registerAgent({ agentType: 'executor' }, tempDir);
+      const a2 = await registerAgent({ agentType: 'researcher' }, tempDir);
+      await updateAgentStatus(a1.id, { status: 'active' }, tempDir);
+      await updateAgentStatus(a2.id, { status: 'idle' }, tempDir);
+      await updateCapacity(a1.id, 0.7, tempDir);
+      await updateCapacity(a2.id, 0.3, tempDir);
+
+      const capacity = await getAvailableCapacity(tempDir);
+      expect(capacity).toBeCloseTo(1.0, 1);
+    });
+
+    it('excludes stopped and crashed agents', async () => {
+      const a1 = await registerAgent({ agentType: 'executor' }, tempDir);
+      const a2 = await registerAgent({ agentType: 'researcher' }, tempDir);
+      const a3 = await registerAgent({ agentType: 'validator' }, tempDir);
+      await updateAgentStatus(a1.id, { status: 'active' }, tempDir);
+      await updateAgentStatus(a2.id, { status: 'stopped' }, tempDir);
+      await updateAgentStatus(a3.id, { status: 'crashed' }, tempDir);
+
+      const capacity = await getAvailableCapacity(tempDir);
+      // Only a1 contributes (1.0 default)
+      expect(capacity).toBeCloseTo(1.0, 1);
+    });
+
+    it('returns 0 when no active agents', async () => {
+      const capacity = await getAvailableCapacity(tempDir);
+      expect(capacity).toBe(0);
+    });
+  });
+
+  // ==========================================================================
+  // findLeastLoadedAgent
+  // ==========================================================================
+
+  describe('findLeastLoadedAgent', () => {
+    it('finds agent with highest capacity', async () => {
+      const a1 = await registerAgent({ agentType: 'executor' }, tempDir);
+      const a2 = await registerAgent({ agentType: 'executor' }, tempDir);
+      const a3 = await registerAgent({ agentType: 'executor' }, tempDir);
+      await updateAgentStatus(a1.id, { status: 'active' }, tempDir);
+      await updateAgentStatus(a2.id, { status: 'active' }, tempDir);
+      await updateAgentStatus(a3.id, { status: 'active' }, tempDir);
+      await updateCapacity(a1.id, 0.2, tempDir);
+      await updateCapacity(a2.id, 0.8, tempDir);
+      await updateCapacity(a3.id, 0.5, tempDir);
+
+      const least = await findLeastLoadedAgent(undefined, tempDir);
+      expect(least).not.toBeNull();
+      expect(least!.id).toBe(a2.id);
+    });
+
+    it('filters by agent type', async () => {
+      const a1 = await registerAgent({ agentType: 'executor' }, tempDir);
+      const a2 = await registerAgent({ agentType: 'researcher' }, tempDir);
+      await updateAgentStatus(a1.id, { status: 'active' }, tempDir);
+      await updateAgentStatus(a2.id, { status: 'active' }, tempDir);
+      await updateCapacity(a1.id, 0.3, tempDir);
+      await updateCapacity(a2.id, 0.9, tempDir);
+
+      const least = await findLeastLoadedAgent('executor', tempDir);
+      expect(least).not.toBeNull();
+      expect(least!.id).toBe(a1.id);
+      expect(least!.agentType).toBe('executor');
+    });
+
+    it('returns null when no matching agents', async () => {
+      const result = await findLeastLoadedAgent('orchestrator', tempDir);
+      expect(result).toBeNull();
+    });
+  });
+
+  // ==========================================================================
+  // isOverloaded
+  // ==========================================================================
+
+  describe('isOverloaded', () => {
+    it('returns true when capacity below threshold', async () => {
+      const a1 = await registerAgent({ agentType: 'executor' }, tempDir);
+      await updateAgentStatus(a1.id, { status: 'active' }, tempDir);
+      await updateCapacity(a1.id, 0.05, tempDir);
+
+      expect(await isOverloaded(0.1, tempDir)).toBe(true);
+    });
+
+    it('returns false when capacity above threshold', async () => {
+      const a1 = await registerAgent({ agentType: 'executor' }, tempDir);
+      await updateAgentStatus(a1.id, { status: 'active' }, tempDir);
+      await updateCapacity(a1.id, 0.5, tempDir);
+
+      expect(await isOverloaded(0.1, tempDir)).toBe(false);
+    });
+
+    it('returns true when no active agents (0 capacity)', async () => {
+      expect(await isOverloaded(0.1, tempDir)).toBe(true);
+    });
+  });
+
+  // ==========================================================================
+  // getCapacitySummary
+  // ==========================================================================
+
+  describe('getCapacitySummary', () => {
+    it('produces correct summary', async () => {
+      const a1 = await registerAgent({ agentType: 'executor' }, tempDir);
+      const a2 = await registerAgent({ agentType: 'researcher' }, tempDir);
+      await updateAgentStatus(a1.id, { status: 'active' }, tempDir);
+      await updateAgentStatus(a2.id, { status: 'idle' }, tempDir);
+      await updateCapacity(a1.id, 0.6, tempDir);
+      await updateCapacity(a2.id, 0.4, tempDir);
+
+      const summary = await getCapacitySummary(0.1, tempDir);
+
+      expect(summary.totalCapacity).toBeCloseTo(1.0, 1);
+      expect(summary.activeAgentCount).toBe(2);
+      expect(summary.averageCapacity).toBeCloseTo(0.5, 1);
+      expect(summary.overloaded).toBe(false);
+      expect(summary.threshold).toBe(0.1);
+    });
+
+    it('reports overloaded when below threshold', async () => {
+      const summary = await getCapacitySummary(0.5, tempDir);
+
+      expect(summary.totalCapacity).toBe(0);
+      expect(summary.activeAgentCount).toBe(0);
+      expect(summary.overloaded).toBe(true);
+    });
+  });
+});