Changelog: OS Model Migration

Generated from documentation/CHANGELOG-OS-MIGRATION.md, the repository is the canonical source and may be ahead of this page.

Changelog: OS Model Migration

Date: March 2026
Commits: 0eb5263 to cb52af7

Summary

This release introduces a major architectural refactoring of the agents-exe core, migrating from a Runtime-per-agent model to a centralized Entity-Component-System (ECS) based OS model.

Major Changes

New Architecture: ECS-Based OS Model

The framework now uses an Entity-Component-System (ECS) pattern at its core:

• Entities: Lightweight UUID-based identifiers (AgentId, ToolboxId, ConversationId, etc.)
• Components: Pure, serializable data attached to entities (AgentConfig, AgentState, ToolboxConfig)
• Systems: Functions that operate on entities with specific component combinations

New Modules (27 OS Modules Added)

Migration Phases

The migration follows a phased approach:

PhaseOldOnly (REMOVED) ──> PhaseDual ──> PhaseNewOnly
    (Legacy only)          (Both)        (OS only)

March 2026 Update: PhaseOldOnly has been removed. The system now operates in:

• PhaseDual (default): Both Runtime and OS available
• PhaseNewOnly: OS only, Runtime deprecated

Key New Capabilities

1. Shared Toolboxes: Multiple agents can share the same SQLite database, HTTP connection pool, or other resources
2. Better Resource Management: Explicit lifecycle scopes (Program, Agent, Toolbox, Conversation, Turn, ToolCall)
3. Concurrent Access: STM-based synchronization with multiple patterns:
   • ExclusiveAccess: Single accessor (TMVar) - for Lua interpreters
   • ReadWriteAccess: Multiple readers/single writer (RWLock) - for SQLite
   • PoolAccess: Bounded pool (TBQueue) - for HTTP connections
   • StatelessAccess: No synchronization needed
4. Durable Persistence: Pluggable backends (SQLite, PostgreSQL, file-based)
5. Complete Lineage Tracking: Full call chains for debugging and accounting
6. Foundation for Web API: Centralized state enables HTTP server interface

Component Type IDs

New CLI Modules

• System.Agents.CLI.Export - Export tools and agents
• System.Agents.CLI.Import - Import tools and agents

New Documentation

New Tests

New Benchmarks

API Changes

Old (Still Supported via Compatibility Layer)

-- Legacy Runtime approach
runtime <- newRuntime props agent tracer
result <- runWithRuntime runtime $ do
    tools <- listTools
    callTool "my-tool" args

New (OS Model)

-- OS model approach
import System.Agents.OS

-- Initialize world
world <- atomically $ do
    w <- newWorld
    w' <- registerComponentStore w (Proxy @AgentConfig)
    registerComponentStore w' (Proxy @AgentState)

-- Create agent
let config = AgentConfig
    { agentName = "my-agent"
    , agentModel = ModelConfig "openai" "url" "gpt-4" "key"
    , agentSystemPrompt = "You are helpful"
    , agentToolboxBindings = []
    }
agentId <- createAgent world config

Migration Path

1. Current (PhaseDual): Use System.Agents.OS.Compat.Runtime for gradual migration
2. Future (PhaseNewOnly): Direct OS model usage

See documentation/MIGRATION-OS.md for detailed migration instructions.

Build Changes

New Dependencies

• deepseq - For benchmark strictness
• criterion - Benchmarking framework
• async - Concurrent test execution
• mtl - Monad transformers

Cabal Updates

• Added 27 new OS modules to library
• Added new test modules
• Added benchmark section

Benefits

1. Shared Resources: Multiple agents sharing toolboxes
2. Resource Pooling: HTTP connections pooled across agents
3. Better Lifecycle: Explicit cleanup with scopes
4. Web API Ready: Centralized state for HTTP interface
5. Durable Persistence: Multiple backend options
6. Lineage Tracking: Complete call chains

Tradeoffs

1. ECS Complexity: Adds indirection but enables flexible composition
2. STM Overhead: Slight performance cost for composability
3. Dual Mode: Maintenance burden during transition
4. Storage Overhead: More memory than direct fields

Backward Compatibility

• Full compatibility layer provided
• Old Runtime interface still works
• Gradual migration supported
• Breaking changes documented in migration guide

Related Issues

• #348 - Core Entity and Component Types
• #349 - Resource Management
• #350 - Concurrent Access
• #351 - Conversation and Lineage Tracking
• #352 - OS Monad
• #353 - Runtime Compatibility
• #354 - TUI and OneShot Adaptation
• #355 - Persistence Layer
• #356 - Documentation and Integration (this release)

Contributors

• Lucas DiCioccio

For questions about the migration, see documentation/MIGRATION-OS.md or file an issue with the “migration” label.