npm package: @illoops/core
Description: Core orchestration engine — pure logic, no VSCode dependency
Author: illodev
Latest version: 0.2.1

# @illoops/core

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

## Installation

```bash
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:

```typescript
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:

```typescript
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:

```typescript
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):

```typescript
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:

```typescript
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:

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

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

### Metrics

Execution metrics collection and reporting:

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

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

## Scripts

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