Skip to content
Mnemose

kernel-protocol — Architecture

The @mnemose/kernel-protocol package defines the immutably-typed Zod schemas for every byte that crosses a service boundary in the Mnemose remote agent-kernel integration. It is shared by the gateway, kernel-broker, loop-host MCP shim, and the remote agent-kernel (Rust) process.

Responsibilities

  • Define JSON-RPC 2.0 envelope schemas for tool dispatch (KernelHello, InvokeKernelTool, ToolCallResult)
  • Define the WebSocket handshake + heartbeat message types
  • Provide the kernelId cross-check contract (hello.kernelId must match the query-param kernel_id) enforced by the broker
  • Keep TypeScript + Rust counterparts in sync (canonical Rust types live in apps/agent-kernel/crates/)

Key Components

FileRole
src/index.tsAll Zod schemas: hello, heartbeat, tool-call request/result, error envelopes. Uses .readonly() so TS infers immutable types.

Dependencies

  • zod

Data Flow

loop-host MCP shim (kernel.invoke tool call)
  ↓ POST mnemose.commands → InvokeKernelTool (validated here)
  ↓ POST /invocations/:id/await → HTTP long-poll
kernel-broker (Cloud Run)
  ↓ WSS /kernel/connect — JSON-RPC 2.0 over WebSocket (validated here)
agent-kernel (remote host)

All schemas use .readonly() so TypeScript infers immutable types; array fields additionally carry z.array(...).readonly() to enforce ReadonlyArray<T>.