OS Model Migration Guide

import System.Agents.Runtime

-- Create runtime directly
runtime <- newRuntime tracer config tools

import System.Agents.OS

-- Initialize OS
os <- initializeOS defaultOSConfig

-- Create agent in OS
agentId <- createAgent os AgentConfig
    { agentName = "my-agent"
    , agentModel = ModelConfig "openai" "..." "gpt-4" "key1"
    , agentSystemPrompt = "You are helpful"
    , agentToolboxBindings = []
    }

-- Tools passed to Runtime constructor
let tools = bashTools ++ mcpTools ++ ioTools
runtime <- newRuntime tracer config tools

-- Toolboxes created as entities in the World
bashId <- createToolbox os bashConfig
sqlId <- createToolbox os sqliteConfig

-- Bound to agent via agentToolboxBindings
let agentConfig = AgentConfig
    { ...
    , agentToolboxBindings = 
        [ unToolboxId bashId
        , unToolboxId sqlId
        ]
    }

-- Manual resource tracking
connections <- newTVarIO []
-- Cleanup handled per-runtime

import System.Agents.OS.Resources

-- Create registry
registry <- atomically newResourceRegistry
let ctx = ResourceContext [ProgramScope] registry

-- Create scoped resource
rid <- createResource ctx (SqliteResource config) $ \rid -> do
    conn <- openConnection config
    pure ResourceHandle
        { handleId = rid
        , handleCleanup = closeConnection conn
        , handleAccess = \f -> f (SqliteAccessor conn)
        }

-- Automatic cleanup
cleanupScope registry (AgentScope agentId)

-- Session managed separately
session <- loadSession sessionPath
-- Conversation ID tracked in Session type

-- Conversation is a first-class entity
convId <- createEntity
atomically $ do
    setComponent world convId ConversationConfig{...}
    setComponent world convId ConversationState{...}

-- Link to agent
atomically $ modifyComponent @AgentState world (unAgentId agentId) $
    \s -> s { agentCurrentConversation = Just (ConversationId convId) }

-- Subcalls invisible to TUI
result <- turnAgentRuntimeIntoIOTool agent prompt
-- No visibility into subcall conversation

-- Subcalls visible as OSEvents
result <- turnAgentRuntimeIntoIOTool agent prompt
-- OSEvent_SubcallStarted, OSEvent_SubcallProgress, 
-- OSEvent_SubcallCompleted emitted
-- TUI displays subcall as separate conversation

import System.Agents.OS.Compat.Runtime

-- Run existing Runtime code with OS backend
withCompatOS $ \compat -> do
    -- Use compatRuntime for legacy code
    let runtime = compatRuntime compat
    
    -- Or use OS directly
    let os = compatOS compat
    
    -- Both are kept in sync

bridge <- newRuntimeBridge agentId os
runWithBridge bridge $ do
    -- Legacy Runtime code
    tools <- listTools
    callTool "my-tool" args

-- Initialize both
runtime <- newRuntime tracer config tools
os <- runtimeToOS runtime

-- Use whichever is appropriate
useRuntime runtime  -- Legacy code
useOS os            -- New code

-- Wrap Runtime operations with OS event emission
wrappedCallTool ctx tool args = do
    -- Emit subcall events if in OS context
    case ctxEventQueue ctx of
        Just q -> emitSubcallStart q
        Nothing -> pure ()
    
    -- Execute tool
    result <- callTool tool args
    
    -- Emit completion
    case ctxEventQueue ctx of
        Just q -> emitSubcallComplete q result
        Nothing -> pure ()
    
    pure result

-- Before
import System.Agents.Runtime
import qualified System.Agents.Runtime.Runtime as Runtime

-- After
import System.Agents.OS
import qualified System.Agents.OS.Agents as OSAgents

-- Before
runtime <- newRuntime tracer config tools

-- After
os <- initializeOS defaultOSConfig

-- Create agent
agentId <- createAgent os agentConfig

-- Create toolboxes and bind to agent
toolboxId <- createToolbox os toolboxConfig

-- Before
config = AgentConfig
    { slug = "my-agent"
    , toolDirectory = "./tools"
    , ...
    }

-- After
config = AgentConfig
    { agentName = "my-agent"
    , agentModel = ...
    , agentSystemPrompt = ...
    , agentToolboxBindings = [unToolboxId bashId, unToolboxId sqliteId]
    }

-- Before
conn <- openConnection config
-- Cleanup handled manually

-- After
rid <- createResource ctx (SqliteResource config) $ \rid -> do
    conn <- openConnection config
    pure ResourceHandle
        { handleId = rid
        , handleCleanup = closeConnection conn
        , handleAccess = \f -> f (SqliteAccessor conn)
        }

-- Automatic cleanup on scope exit
cleanupScope registry scope

-- Before
result <- turnAgentRuntimeIntoIOTool agent prompt

-- After
-- Ensure ToolExecutionContext has event queue
let ctx' = ctx { ctxEventQueue = Just eventQueue }
result <- turnAgentRuntimeIntoIOTool agent prompt
-- Events automatically emitted

-- Test OS operations directly
spec :: Spec
spec = describe "OS Core" $ do
    it "creates agents" $ do
        os <- initializeOS testConfig
        agentId <- createAgent os testAgentConfig
        
        mConfig <- atomically $ 
            getComponent @AgentConfig (osWorld os) (unAgentId agentId)
        
        mConfig `shouldSatisfy` isJust

-- Test full agent lifecycle
spec :: Spec
spec = describe "Agent Lifecycle" $ do
    it "runs conversation" $ do
        os <- initializeOS testConfig
        agentId <- createAgent os testAgentConfig
        
        -- Create conversation
        convId <- startConversation os agentId
        
        -- Add user message
        addMessage os convId UserRole "Hello!"
        
        -- Run agent turn
        result <- runAgentTurn os agentId convId
        
        -- Verify response
        messages <- getConversationMessages os convId
        length messages `shouldBe` 2

-- Verify entity exists
exists <- atomically $ entityExists world eid
when (not exists) $ error "Entity not found"

-- Check component store registered
hasStore <- atomically $ hasComponentStore @MyComponent world
when (not hasStore) $ error "Component store not registered"

-- Bad: IO inside atomically
atomically $ do
    val <- getComponent world eid
    result <- liftIO $ expensiveOp val  -- DON'T DO THIS
    setComponent world eid result

-- Good: Separate IO
mVal <- atomically $ getComponent world eid
case mVal of
    Just val -> do
        result <- expensiveOp val
        atomically $ setComponent world eid result
    Nothing -> pure ()

import Control.Exception (bracket)

-- Using bracket
bracket 
    (createResource ctx config mkHandle)
    (\rid -> cleanupResource registry rid)
    (\rid -> do
        withResource registry rid $ \accessor ->
            useResource accessor
    )

-- Or use cleanupScope for batch cleanup
cleanupScope registry (AgentScope agentId)

-- Check if event queue exists
case ctxEventQueue ctx of
    Nothing -> putStrLn "Warning: No event queue, subcall won't be visible"
    Just q -> putStrLn "Event queue configured"

-- When creating context, include event queue
ctx = ToolExecutionContext
    { ...
    , ctxEventQueue = Just eventQueue  -- Required for visibility
    }

-- Good: Separate TVars per component type
agentStore :: TVar (Map EntityId AgentConfig)
toolboxStore :: TVar (Map EntityId ToolboxConfig)

-- Bad: Single TVar for everything
allComponents :: TVar (Map EntityId (AgentConfig, ToolboxConfig, ...))

-- HTTP pool: size = expected concurrent requests
httpRid <- createHttpPool ctx 20

-- SQLite with WAL: can have many readers
sqliteRid <- createSqliteResource ctx config True  -- WAL mode

config = defaultOSConfig
    { osSnapshotInterval = Just (secondsToNominalDiffTime 60)
    , osMaxSnapshotsPerEntity = 10
    }

-- Query all busy agents
busyAgents <- query world $ 
    select @AgentState 
    where_ (\s -> agentStatus s == AgentBusy)

-- Query conversations with recent activity
recentConvs <- query world $
    select @ConversationState
    where_ (\s -> conversationLastActivity s > cutoffTime)

-- Initialize distributed OS
os <- initializeDistributedOS 
    { osNodeId = "node-1"
    , osCluster = ["node-1", "node-2", "node-3"]
    , osConsensus = RaftConsensus
    }

-- Replay from event log
events <- loadEvents backend
world <- foldM applyEvent emptyWorld events

-- Where applyEvent applies each event to world state