Crate smooth_operator_server 

smooth-operator-server

The reference WebSocket service for smooth-operator. It speaks the schema-driven protocol in smooth-operator/spec/ over a smooth-operator-backed knowledge-chat runtime, so the generated TypeScript / Go / .NET / Python clients can connect and drive real LLM turns unmodified.

Pieces

• config — env-driven ServerConfig (gateway URL / key / model / limits). The gateway key is optional at startup; without it send_message returns a clean error so protocol conformance is testable with zero credentials.
• protocol — builders for the server→client event envelopes, matched field-for-field to spec/events/*.json.
• state — shared AppState: storage adapter + session registry.
• handler — action dispatch (ping, create_conversation_session, get_session, send_message).
• runner — the streaming, memory-carrying turn runner over a smooth-operator Agent.
• server — the axum app + per-connection socket loop. server::bind and server::router let tests boot the service in-process.
• local — the local deployment flavor (the third target alongside deploy/k8s and deploy/sst): an embeddable, fully in-memory, auth-off server. local::serve_local runs it to completion; local::LocalServer::builder boots it in-process with a shutdown handle.
• admin — the auth-gated admin HTTP API (Phase 12) mounted under /admin: whoami, chat history, indexing status, document sets. Consumed by the Next.js management console (increment 2). See docs/ADMIN-API.md.

Env contract (reused by every language’s E2E harness)

See config for the full table. The load-bearing ones: SMOOTH_AGENT_PORT, SMOOAI_GATEWAY_URL, SMOOAI_GATEWAY_KEY, SMOOTH_AGENT_MODEL, SMOOTH_AGENT_SEED_KB.

Re-exports

pub use config::ServerConfig;

pub use embedder::build_embedder;

pub use embedder::EmbedderConfig;

pub use local::serve_local;

pub use local::LocalServer;

pub use local::LocalServerBuilder;

pub use local::DEFAULT_LOCAL_ADDR;

pub use reranker::build_reranker;

pub use reranker::RerankMode;

pub use reranker::RerankerConfig;

pub use server::bind;

pub use server::build_state;

pub use server::build_state_from_env;

pub use server::build_state_from_env_async;

pub use server::router;

pub use server::run;

pub use server::serve_state;

pub use server::serve_state_on;

pub use state::AppState;

Modules

admin

The admin HTTP API (Phase 12, increment 1).

config

Server configuration, read entirely from the environment.

embedder

Embedder selection — the seam that makes production retrieval real.

handler

Action dispatch — parses a client action envelope and produces the matching server events.

local

The local deployment flavor — an embeddable, zero-config server.

protocol

Wire protocol — server→client event envelopes built to match spec/.

reranker

Reranker selection — the opt-in post-retrieval reorder stage (feature gap G8).

runner

The streaming, memory-carrying agent runner used by the WS service.

server

The axum WebSocket server: one /ws endpoint, one task per connection.

state

Server + per-connection state.