@illoops/core

Core orchestration engine for illoops — pure logic, no VSCode dependency.

Installation

pnpm add @illoops/core

Modules

Models

• Task, Milestone, Action — data structures defining units of work
• TaskState, MilestoneState — lifecycle enums
• RetryPolicy, VerificationSpec — configuration types

Agents

Autonomous executors that receive task payloads and produce results:

| Agent | Description | | ---------------- | ----------------------------------------------- | | CmdAgent | Shell commands via child_process.spawn | | LlmAgent | LLM provider calls with fallback chains | | HttpAgent | HTTP requests via fetch | | FileAgent | File system operations (read/write/copy/delete) | | GitAgent | Git commit and diff operations | | CompositeAgent | Delegates to inner agents by action type |

All agents implement the Agent interface:

interface Agent {
  id: string;
  type: AgentType;
  status: AgentStatus;
  execute(payload: TaskPayload): Promise<AgentResult>;
  cancel(): Promise<void>;
  dispose(): Promise<void>;
}

Agent Pool

Manages agent concurrency with configurable limits, acquire timeouts, and queue processing:

const pool = new AgentPool({ maxConcurrency: 4, acquireTimeout: 30_000 });
pool.setFactory(registry.createFactory());
const agent = await pool.acquire("cmd");
// ... use agent ...
pool.release(agent);

State Machines

Deterministic finite state machines for Task and Milestone lifecycles:

import { processEvent, TaskState } from "@illoops/core";

const next = processEvent(TaskState.Pending, "DISPATCH");
// → TaskState.InProgress

Store

Pluggable persistence layer with built-in MemoryStore (in-memory) and JsonStore (file-based):

import { MemoryStore, JsonStore } from "@illoops/core";

const store = new JsonStore("./data");
await store.save(milestone);
const loaded = await store.load("milestone-id");

Configuration

YAML/JSON configuration loader with schema validation:

import { loadConfig } from "@illoops/core";

const config = await loadConfig("./illoops.config.yaml");

Security

• SecretRedactor — redacts sensitive data from logs
• ResourceMonitor — enforces CPU/memory/time limits
• Sandbox — restricts agent file system access

Verification

Post-task verification pipeline — runs commands and checks exit codes:

import { runVerificationPipeline } from "@illoops/core";

const summary = await runVerificationPipeline(task.verification, cwd);
if (!summary.allPassed) {
  /* handle failure */
}

Metrics

Execution metrics collection and reporting:

import { generateReport } from "@illoops/core";

const report = generateReport(results, durationMs);
console.log(report);

Scripts

pnpm build         # Build with tsup
pnpm test          # Run tests
pnpm test:coverage # Run tests with coverage
pnpm typecheck     # Type check
pnpm clean         # Remove dist/