M5: Multi-Session Concurrency for API Server

[kovtcharov]

Priority: P1 — Required for multi-user deployments

Effort: Large (7-10 days)

Problem

GAIA's API server can only handle one chat request at a time. The UI server enforces this with chat_semaphore = asyncio.Semaphore(1). The OpenAI API server creates a single agent instance per model. Root cause: _TOOL_REGISTRY in src/gaia/agents/base/tools.py is a global dict. Concurrent agents registering tools corrupt each other's state.

Deliverable

Support N concurrent chat sessions without tool registry corruption.

Approach options (choose one)

1. Instance-scoped tool registry: Move _TOOL_REGISTRY from module-level global to an instance attribute on each Agent. Tools are registered per-agent, not globally. Cleanest fix but touches the core agent architecture.
2. Agent pool: Pre-create N agent instances at startup, each with a frozen copy of the tool registry. Incoming requests grab an available agent from the pool. Simpler to implement but uses more memory.
3. Copy-on-use: Keep the global registry as a template. Each request creates a shallow copy for its agent instance. Minimal change but adds per-request overhead.

Files to change

• src/gaia/agents/base/tools.py — make _TOOL_REGISTRY instance-scoped or copyable
• src/gaia/agents/base/agent.py — agent instantiation changes
• src/gaia/api/openai_server.py — agent pool or per-request instantiation
• src/gaia/ui/server.py — remove or increase chat_semaphore

Acceptance criteria

• 5+ concurrent /v1/chat/completions requests complete without errors
• No tool registry corruption across sessions
• Each session maintains independent conversation state
• Memory usage scales linearly (not exponentially) with concurrent sessions
• Existing single-user behavior unchanged

Context

Full milestone plan: docs/plans/webapp-integration.md