loop-host — Architecture

The loop-host service manages per-tenant agent-loop child processes. Each tenant that opens an interactive session in the console gets a dedicated loop-host process that owns the agent-loop runtime, persona context, and mnemosyne memory handle.

Responsibilities

• Spawn and manage a @freeside-collective/agent-loop child process per active tenant
• Expose a streaming WebSocket or HTTP/SSE interface that the gateway proxies to the console’s /agent view
• Wire the agent-loop to the correct MCP tool servers for the active tenant’s cloud platform and kernel fleet
• Forward agent-generated commands onto the CQRS command bus
• Persist agent memory checkpoints via the mnemosyne integration

Key Components

File	Role
src/index.ts	Process entry point — accepts loop-manager configuration via environment/IPC
src/personas.ts	Builds the MnemoseAgent persona configuration for the active tenant
src/wire.ts	Wires agent-loop events (tool calls, responses, memory writes) to downstream sinks

Loop Lifecycle

Gateway LoopManager
  ↓  spawn loop-host child process with tenantId + actorSub
loop-host src/index.ts starts
  ↓
Build persona config (src/personas.ts): mcp servers, memory provider, system prompt
  ↓
Start agent-loop runtime
  ↓  streaming WebSocket to gateway
Console /agent view ←→ gateway ←→ loop-host ←→ agent-loop ←→ MCP servers

Tool Server Wiring

Each loop-host instance connects to the full MCP server suite scoped to the tenant:

• @mnemose/mcp-gcp-compute — VM management
• @mnemose/mcp-gcp-iam — IAM binding management
• @mnemose/mcp-gcp-storage — object storage operations
• @mnemose/mcp-gcp-network — VPC, firewall, DNS
• @mnemose/mcp-gcp-monitoring — metrics and alerting
• @mnemose/mcp-gcp-security — Security Command Center findings
• @mnemose/mcp-mnemose-kernels — enrolled kernel enumeration and invocation

Memory

The loop-host connects the agent-loop to the mnemosyne memory provider using the tenant-scoped SQLite database. All significant agent decisions are checkpointed so the agent can resume with full context on the next session.