Iteratio

What is Iteratio?

Iteratio is a lightweight, DI-driven agent execution loop library. It provides the conversational loop that powers every channel in armament: add a message, call the LLM, execute tools, store results, repeat — in a configurable step pipeline.

It is not a monolithic orchestration engine. Features like provider routing, session persistence, budget tracking, channel management, and the TUI are handled by armament’s app layer — iteratio focuses on the inner agent loop.

npm install iteratio

(Requires reflect-metadata and inversify — peer dependency on flight-controller is optional.)

Architecture

Iteratio uses InversifyJS for dependency injection, with a fluent builder pattern for configuration:

AgentLoopBuilder
  │
  ├── withLLM(provider)       ← required: implements ILLMProvider
  ├── withTools([...])        ← register tools
  ├── withPlugin(plugin)      ← add lifecycle hooks
  ├── withPlugins([...])      ← add multiple
  ├── withSystemPrompt(text)  ← system prompt
  ├── withLogLevel(level)     ← verbosity
  ├── onToolEvents({...})     ← observe tool calls
  ├── onUsage(fn)             ← track token usage
  └── build()                 → AgentLoop

Core Classes

Class	Responsibility
`AgentLoop`	Main loop — orchestrates turn execution, manages plugins
`StepPipeline`	Ordered pipeline of steps run per turn
`TurnExecutor`	Coordinates a single LLM+tool call round
`MessageManager`	Conversation history with context window management
`StateManager`	Key-value state store with persistence hooks
`ToolExecutor`	Registers and invokes tools, manages tool definitions
`EventBus`	Typed pub/sub for loop events
`InterruptionController`	Pause/resume loop execution

Default Pipeline Steps

Each turn runs through these steps in order:

AddUserMessageStep — Injects user input into conversation
CallLLMStep — Sends messages to the LLM, gets response
ExecuteToolsStep — Runs any tool calls the LLM made
AddToolResultsStep — Injects tool results back into conversation
AddAssistantResponseStep — Records the final assistant response

Steps can be reordered, removed, or custom steps injected via loop.registerStep().

Usage

import { AgentLoopBuilder } from 'iteratio';
import { OpenAIProvider } from 'llm-flight-controller';

// Create an LLM provider (from flight-controller)
const provider = new OpenAIProvider({ apiKey: '...' });

// Build the loop
const loop = AgentLoopBuilder.create()
  .name('helper')
  .withLLM(provider)
  .withSystemPrompt('You are a helpful assistant.')
  .withTools([myTool])
  .onUsage((usage) => console.log(`Tokens: ${usage.total_tokens}`))
  .build();

// Run a turn
const response = await loop.runTurn('Hello!');
console.log(response);

Plugin System

Plugins hook into turn lifecycle events via the IPlugin interface:

interface IPlugin {
  name: string;
  beforeTurn?(ctx: TurnContext): Promise<void>;
  afterTurn?(ctx: TurnContext): Promise<void>;
  shutdown?(): Promise<void>;
}

14 official plugin packages are available:

Package	Purpose
`iteratio-plugin-a2a`	Agent-to-agent communication
`iteratio-plugin-constraints`	Constraint-based step routing
`iteratio-plugin-federation`	Cross-instance agent federation
`iteratio-plugin-graph`	Dependency graph execution
`iteratio-plugin-human`	Human-in-the-loop approval
`iteratio-plugin-mcp`	MCP tool server integration
`iteratio-plugin-memory`	Persistent memory backends
`iteratio-plugin-metrics`	Telemetry and metrics
`iteratio-plugin-parallel`	Parallel tool execution
`iteratio-plugin-retry`	Retry with backoff
`iteratio-plugin-sessions`	Session checkpoint/restore
`iteratio-plugin-state`	State persistence adapters
`iteratio-plugin-tools`	Tool lifecycle management
`iteratio-plugin-tracing`	Distributed tracing
`iteratio-plugin-workflow`	Multi-step workflow orchestration

Cross-Cutting Concerns

WorkerPool — Managed pool of child agents with scaling and backpressure
CircuitBreaker — Failure isolation for external dependencies
RateLimiter — Per-provider/minute rate limits
RBAC — Role-based access control for tool execution
Sandbox — Isolated tool execution environment
SessionCheckpoint — Snapshot/restore loop state
DistributedLock — Leader election via Redis/NATS

Integration with Armament

Armament wraps iteratio’s AgentLoop inside ChannelAgent, which adds:

Provider resolution via flight-controller (routing, fallback, cost tracking)
Channel-scoped tool registration via BuiltinTools + CatalogAdapter
Session persistence and resumption
Budget enforcement via BudgetManager
Streaming output to the TUI via ChannelAgentStreaming

Repository

Source: github.com/rjtruitt/iteratio