xml-pipeline/docs/AgentServer.md

This is a great idea. Your README.md.bak was a good start, but we’ve evolved the architecture significantly today. This updated executive summary captures the "Nervous System" philosophy and the rigorous cryptographic controls we've established.

Here is a refined Executive Summary you can add to your docs/ or update your README.md with:

AgentServer — Executive Summary (v1.0)

December 30, 2025
Architecture: Cryptographically Sovereign Multi-Agent Substrate

The Vision

AgentServer is a production-ready "body" for the xml-pipeline organism. It is a single-process, secure WebSocket server that hosts multiple concurrent, stateful agents (organs) sharing a unified, tamper-proof MessageBus.

Unlike traditional "swarms," AgentServer is built on the principles of Structural Rigidity and Runtime Evolution.

Core Architecture Pillars

1. Identity-First Messaging (envelope.xsd)

   • No Anonymous Messages: Every packet must have a mandatory <from/> tag.
   • The Universal Envelope: All communication—user-to-agent, agent-to-tool, and system-to-agent—uses a strictly validated XML envelope.
   • Continuity: Threading is maintained via a mandatory-if-existent convo_id contract, ensuring "dumb" tools never lose the conversation context.

2. The Immune System (repair_and_canonicalize)

   • Scar Tissue (<huh/>): Any malformed XML is automatically repaired by the server’s "stomach." Every repair is logged in a <huh/> tag within the message metadata, ensuring radical transparency for auditing and LLM feedback.
   • Exclusive C14N: All messages are canonicalized before signing or routing, preventing "semantic drift" and ensuring cryptographic integrity.

3. Cryptographic Sovereignty (privileged-msg.xsd)

   • Owner Control: Structural changes (registering new agents, re-wiring topology, or shutting down) require an offline-signed Ed25519 privileged command.
   • Runtime Evolution: The system supports "Hot-Swapping" of capabilities. New tools can be registered and "wired" to existing agents via a privileged update-topology command without restarting the server.

4. The Handshake of Death (Synchronized Shutdown)

   • Strict Audit Trail: Privileged commands bypass the standard bus for speed but are immediately "announced" back to the bus by the AgentServer.
   • Guaranteed Persistence: The process cannot exit until the Logger agent receives a final shutdown request, flushes all pending logs to disk, and sends a <system-shutdown-confirmed/> handshake back to the brainstem.

Technical Stack

• Protocol: Mandatory WSS (TLS) + TOTP 2FA.
• Data Format: Strict XML (Exclusive C14N).
• Routing: O(1) "Dictionary of Dictionaries" lookup by Root Tag and Target.
• Concurrency: Asyncio-based non-blocking dispatch.

Why It Matters

AgentServer treats AI agents not as isolated scripts, but as interdependent organs in a bounded, auditable, and owner-controlled body. It is "paperclip-proof" by design—agents can think freely within their scope, but they cannot escape the cryptographic skeleton of the organism.

One port. Many bounded minds. Total sovereignty. 🚀

— Built in collaboration with Grok & AI Assistant