Nexus: A Personal AI Assistant Gateway

Problem

I wanted a single, self-hostable entry point to AI assistants that I controlled end to end. The available options pushed me toward provider-specific SDKs scattered across one-off scripts, or hosted products that locked conversation state and routing logic behind someone else’s service. Neither let me move freely between Anthropic Claude and OpenAI GPT, or reach the same assistant from my terminal, my browser, and a chat app without re-implementing the plumbing each time.

The harder problem was architectural. An assistant gateway has to be a network server, a stateful conversation store, an agent runtime, and an extension host all at once. Done naively, those concerns bleed into each other and every new provider or channel becomes a rewrite. I built Nexus to draw those boundaries deliberately and keep them clean.

Approach

I structured Nexus as a TypeScript ESM monorepo of six core packages plus two channel extensions, sharing one dependency tree via npm workspaces. The layering is strict and one-directional: @nexus/core (persistence and utilities) depends on nothing internal; @nexus/agent reads and writes session state through core; @nexus/gateway exposes the network surface and delegates all business logic downward.

The gateway pairs a Hono HTTP server with a ws WebSocket server. Clients open a socket, send ConnectParams, and drive an RPC dispatch table — chat.send, sessions.create, agent.run, config.set. Every frame is validated against a Zod schema before processing, and a typed event bus broadcasts session:created and session:message to authenticated clients with monotonic sequence numbers so gaps are detectable.

For state, I chose SQLite in WAL mode through better-sqlite3, with PRAGMA synchronous = NORMAL to balance durability and throughput. The agent layer stays stateless: an execution loop assembles context, calls a provider behind a single Provider interface, dispatches tool calls, and repeats until the turn ends.

Key Design Elements

• Provider abstraction: a complete(messages, tools, options) interface lets me add or swap providers without touching gateway or core code.
• Schema-first protocol: Zod validates ConnectParams, request, response, and event frames at the boundary.
• Channel adapters as separate packages: Telegram and Discord connect over the same WebSocket API any client uses, with per-user sessions keyed by peerId.
• Security by default: token/password/device auth, per-client rate limiting, a prompt-injection guard, and device pairing for channels.

Outcomes

• One agent runtime is reachable from a SolidJS web UI, a Commander.js CLI, Telegram, and Discord — all through the same validated WebSocket protocol.
• Switching between Anthropic and OpenAI is a config change or per-turn override, not a code change, thanks to the provider resolver.
• The project ships with 533 passing tests under strict TypeScript, reflecting a test-first discipline across the package boundaries.

Key Contributions

• Designed the layered monorepo and the dependency rules that keep core, agent, and gateway concerns separate.
• Built the Zod-validated WebSocket RPC and server-push event system in the gateway.
• Implemented the multi-turn agent execution loop, context builder, and tool executor with bash and filesystem tools.
• Developed Telegram and Discord adapters, including message splitting, MarkdownV2 escaping, and device pairing.
• Created the plugin marketplace client and CLI commands for installing, updating, and publishing plugins against any HTTP registry.
• Engineered the SQLite persistence layer with WAL mode, migrations, and an append-only audit log.