AI Context - Working on the Agents Framework

-- 1. What is this project?
SELECT * FROM project_overview;

-- 2. What docs exist?
SELECT doc_path, title FROM docs_index ORDER BY doc_path;

-- 3. What's the module structure?
SELECT module_name, purpose, documented_in 
FROM code_index 
ORDER BY filepath;

-- 4. Check for recent changes
SELECT * FROM code_index 
WHERE module_name LIKE '%OS%' 
ORDER BY filepath;

-- Entity: Just a unique ID
newtype EntityId = EntityId UUID
newtype AgentId = AgentId EntityId
newtype ToolboxId = ToolboxId EntityId

-- Component: Pure data attached to entities
data AgentConfig = AgentConfig
    { agentName :: Text
    , agentModel :: ModelConfig
    , agentSystemPrompt :: Text
    , agentToolboxBindings :: [ToolboxBindingSpec]
    }

data AgentState = AgentState
    { agentStatus :: AgentStatus
    , agentCurrentConversation :: Maybe ConversationId
    , agentCreatedAt :: UTCTime
    }

-- World: Container for all component stores
newtype World = World 
    { componentStores :: HashMap ComponentTypeId (TVar Any) 
    }

import System.Agents.OS

-- Initialize world with component stores
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 = []
    }
result <- createAgent world config

-- Key tables:
--   project_overview  - project metadata
--   code_index        - 108 Haskell modules with docs linkage
--   docs_index        - 15+ documentation files
--   commits_seen      - git commits already processed

-- Common queries:
-- Find OS modules:
SELECT * FROM code_index WHERE filepath LIKE '%OS%';

-- Find where a module is documented:
SELECT documented_in FROM code_index 
WHERE module_name = 'System.Agents.OS.Core';

-- Check documentation coverage:
SELECT 
    COUNT(*) as total_modules,
    SUM(CASE WHEN documented_in IS NOT NULL THEN 1 ELSE 0 END) as documented
FROM code_index;

-- Define component type
newtype ComponentTypeId = ComponentTypeId { unComponentTypeId :: Int }

class Component a where
    componentId :: Proxy a -> ComponentTypeId

-- Create a component
instance Component MyComponent where
    componentId _ = ComponentTypeId 100  -- Unique ID

-- Use with world
atomically $ do
    setComponent world eid myComponent
    mComp <- getComponent @MyComponent world eid

-- OS model approach
import System.Agents.OS

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

case result of
    Left err -> handleError err
    Right agentId -> do
        -- Agent created successfully

import System.Agents.OS.Resources

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

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

-- Cleanup
cleanupScope registry (AgentScope agentId)

-- During migration, use compatibility layer
import System.Agents.OS.Compat.Runtime

result <- initializeWithMigration defaultMigrationConfig
case result of
    Right os -> do
        -- Use new OS with compatibility bridge
        bridge <- newRuntimeBridge agentId os
        runWithBridge bridge $ do
            tools <- listTools
            callTool "my-tool" args
    _ -> error "Migration not configured"

-- All operations are traced
import Prod.Tracer

data MyTrace = Started | Completed | Failed String

myFunction :: Tracer IO MyTrace -> IO ()
myFunction tracer = do
    runTracer tracer Started
    result <- try operation
    case result of
        Right _ -> runTracer tracer Completed
        Left e  -> runTracer tracer (Failed $ show e)

-- SQLite with concurrent reads (WAL mode)
result <- runResourceM ctx $ withRead rid $ do
    queryDatabase sql

-- Lua with exclusive access
result <- runResourceM ctx $ withExclusive luaRid $ do
    runLuaScript script

-- HTTP with connection pool
result <- runResourceM ctx $ withPooled httpRid $ do
    makeHttpRequest req

-- ECS Core
newtype EntityId = EntityId UUID
newtype AgentId = AgentId EntityId
newtype ToolboxId = ToolboxId EntityId
newtype ConversationId = ConversationId EntityId

-- Agent Components
data AgentConfig = AgentConfig
    { agentName :: Text
    , agentModel :: ModelConfig
    , agentSystemPrompt :: Text
    , agentToolboxBindings :: [Text]
    }

data AgentState = AgentState
    { agentStatus :: AgentStatus
    , agentCurrentConversation :: Maybe ConversationId
    , agentCreatedAt :: UTCTime
    }

-- Resource Management
data ResourceScope
    = ScopeGlobal
    | ScopeAgent AgentId
    | ScopeConversation ConversationId

data AccessPattern
    = ExclusiveAccess      -- TMVar
    | ReadWriteAccess      -- RWLock
    | PoolAccess Int       -- TBQueue
    | StatelessAccess      -- No lock

-- Original Runtime types
data Agent = Agent
    { slug :: Text
    , apiKeyId :: Text
    , flavor :: Text
    , modelUrl :: Text
    , modelName :: Text
    , systemPrompt :: [Text]
    , toolDirectory :: FilePath
    , mcpServers :: Maybe [McpServerDescription]
    , extraAgents :: Maybe [ExtraAgentRef]
    }

data ExtraAgentRef = ExtraAgentRef
    { extraAgentSlug :: Text
    , extraAgentPath :: FilePath
    }

-- Find all OS-related modules:
SELECT module_name, filepath 
FROM code_index 
WHERE module_name LIKE '%OS%' OR filepath LIKE '%OS%'
ORDER BY filepath;

-- Find all documentation:
SELECT doc_path, title FROM docs_index ORDER BY doc_path;

-- Check documentation coverage:
SELECT 
    COUNT(*) as total,
    SUM(CASE WHEN documented_in IS NOT NULL THEN 1 ELSE 0 END) as documented,
    ROUND(100.0 * SUM(CASE WHEN documented_in IS NOT NULL THEN 1 ELSE 0 END) / COUNT(*), 1) as pct
FROM code_index;

-- Find modules by documentation file:
SELECT module_name, filepath 
FROM code_index 
WHERE documented_in = 'documentation/OS-API.md'
ORDER BY module_name;

-- Library exports modules under System.Agents
library
    exposed-modules:
        System.Agents
        System.Agents.OS           -- NEW
        System.Agents.OS.Core      -- NEW
        System.Agents.OS.Agents    -- NEW
        System.Agents.Base
        System.Agents.Runtime
        ...

-- Executable is app/Main.hs
executable agents-exe
    main-is: Main.hs
    hs-source-dirs: app
    build-depends: agents, ...

-- Test suite
test-suite agents-tests
    other-modules:
        OS.CoreTests
        OS.IntegrationTests
        OS.CompatibilityTests
        ...

-- Benchmarks
benchmark os-benchmarks
    main-is: OSBenchmarks.hs
    hs-source-dirs: bench

-- OS Model (New)
import System.Agents.OS
import System.Agents.OS.Core
import System.Agents.OS.Agents
import System.Agents.OS.Compat.Runtime

-- Core types
import System.Agents.Base

-- Legacy Runtime (being deprecated)
import System.Agents.Runtime
import qualified System.Agents.Runtime.Runtime as Runtime

-- Agent tree
import qualified System.Agents.AgentTree as AgentTree
import qualified System.Agents.OS.AgentTree as OSAgentTree

-- Tools
import qualified System.Agents.Tools.Bash as Bash
import qualified System.Agents.Tools.BashToolbox as BashToolbox

-- Sessions
import qualified System.Agents.Session.Base as Session

-- Tracing
import Prod.Tracer

-- STM for concurrency
import Control.Concurrent.STM