CQRS Call-Site Migration: Agent Query Migration

[michaelbeale-IL]

CQRS Call-Site Migration: Agent Query Migration

Labels

phase-3, workstream-a, architecture, cqrs

Milestone

Phase 3: Architecture Completion

Summary

Migrate 122 agent query call sites from direct Context.AppAgentMgr access to CQRS query handlers using an extension method approach. This is Phase 4 of the CQRS Implementation Guide — the largest batch by count but the most uniform pattern.

Context

All 122 sites follow the same pattern — they call Context.AppAgentMgr.GetCurrentAgentName() or similar query methods. The registered GetActiveAgentNameQueryHandler already delegates to IAgentManager.GetCurrentAgentName().

Existing CQRS query handler (registered in AddCQRSHandlers()):

public class GetActiveAgentNameQueryHandler : IQueryHandler<GetActiveAgentNameQuery, string>
{
    public string Handle(GetActiveAgentNameQuery query) => _agentManager.GetCurrentAgentName();
}

Recommended migration pattern — Extension Method (least disruptive for 122 sites):

// Extension method wrapping the CQRS query
public static class AgentManagerExtensions
{
    public static string GetCurrentAgentNameViaQuery(this IAgentManager mgr)
    {
        var handler = Context.ServiceProvider?.GetService(typeof(IQueryHandler<GetActiveAgentNameQuery, string>))
            as IQueryHandler<GetActiveAgentNameQuery, string>;
        return handler?.Handle(new GetActiveAgentNameQuery()) ?? mgr.GetCurrentAgentName();
    }
}

After all callers are migrated, the extension method body can be simplified to use only the CQRS path.

Implementation Steps

1. Create extension methods in src/Libraries/ACATCore/Patterns/CQRS/AgentManagerExtensions.cs

   • GetCurrentAgentNameViaQuery() wrapping GetActiveAgentNameQuery
   • Add extension methods for other agent query types found during migration
   • Each method includes safe fallback to direct IAgentManager call

2. Identify all 122 call sites using grep/search:

   Context.AppAgentMgr.GetCurrentAgentName
   Context.AppAgentMgr.GetActiveProfile
   Context.AppAgentMgr.GetRunningAgents
   

   These are spread across:

   • src/Extensions/Default/UI/Scanners/ (scanner panels)
   • src/Extensions/Default/FunctionalAgents/ (agent implementations)
   • src/Libraries/ACATCore/AgentManagement/ (agent framework)
   • src/Extensions/Default/UI/CommandHandlers/ (command handlers)

3. Batch-replace call sites — For each query method:

   • Find all occurrences of Context.AppAgentMgr.<MethodName>(
   • Replace with Context.AppAgentMgr.<MethodName>ViaQuery(
   • Add using statement for the extension methods namespace
   • This is a mechanical find-and-replace operation

4. Add any missing query types — If agent queries beyond GetActiveAgentNameQuery are found:

   • Create new query classes in src/Libraries/ACATCore/Patterns/CQRS/
   • Create corresponding query handlers
   • Register in AddCQRSHandlers() in ServiceCollectionExtensions.cs

5. Verify build and tests — Ensure all 122 sites compile and existing tests pass

Acceptance Criteria

• Extension method class created with safe-fallback wrappers for all agent query types
• All 122 Context.AppAgentMgr query call sites migrated to extension methods
• Any new query types discovered during migration have handlers created and registered in DI
• Solution builds successfully with zero errors
• All existing tests pass
• Add at least 2 unit tests verifying extension method resolution (DI available vs. fallback)

Key Files

File	Role
src/docs/SECTION_3_3_IMPLEMENTATION_GUIDE.md	Implementation guide (Phase 4 section)
src/Libraries/ACATCore/Patterns/CQRS/	CQRS interfaces, handlers, new extension methods
src/Libraries/ACATCore/DependencyInjection/ServiceCollectionExtensions.cs	Handler registration
src/Extensions/Default/UI/Scanners/	Major call site location
src/Extensions/Default/FunctionalAgents/	Major call site location

Dependencies

• Issue DOC: Add url with MSDN review and screenshots. #1 (CQRS structural wiring) should be completed first to establish patterns

Blocked By

• Issue DOC: Add url with MSDN review and screenshots. #1 (recommended but not strictly required — patterns are documented)