Skip to main content

Shared crates

The shared Rust crates in nexus-platform. The guiding rule: traits for dynamic providers, not for fixed agent roles.

nexus-domain​

Pure domain types — zero database or HTTP logic.

pub enum AgentStatus { Draft, Enabled, Disabled, Quarantined, Archived }

pub enum TaskStatus {
    Draft, Planned, ReadyForAgent, Leased, Running,
    WaitingReview, Blocked, Done,
}

Libraries: serde, serde_json, schemars, uuid, chrono, strum, validator.

nexus-db​

MongoDB repository layer: CRUD for agents/skills/memory/tasks/runs, indexes, transactions where needed, change streams later.

Collections: agents, agent_blueprints, skills, memories, goals, tasks, agent_runs, events, approvals, integrations, board_links, telegram_commands. The official MongoDB Rust driver provides async access.

Libraries: mongodb, bson, serde, futures, thiserror, tracing.

nexus-events​

Internal event bus over NATS JetStream.

nexus.task.created · nexus.task.updated
nexus.agent.run.started · nexus.agent.run.completed
nexus.board.sync.requested · nexus.memory.proposed · nexus.approval.requested

Libraries: async-nats, serde, serde_json, tokio, tracing.

nexus-board​

Generic board abstraction.

#[async_trait::async_trait]
pub trait BoardProvider {
    async fn create_item(&self, input: CreateBoardItem) -> anyhow::Result<BoardItemRef>;
    async fn update_item_status(&self, item_id: &str, status: BoardStatus) -> anyhow::Result<()>;
    async fn add_comment(&self, item_id: &str, body: &str) -> anyhow::Result<()>;
    async fn get_item(&self, item_id: &str) -> anyhow::Result<BoardItem>;
}

Implementations: PlaneBoardProvider, JiraBoardProvider (later), NexusInternalBoardProvider. Libraries: async-trait, serde, thiserror, anyhow.

nexus-board-plane​

Plane implementation: create work items, update states, comments, receive webhooks, reconcile. Plane's REST API has a documented ~60 req/min per-key rate limit, so this crate applies rate limiting and verifies webhook HMACs.

Libraries: reqwest, serde, async-trait, governor, tracing, hmac, sha2.

nexus-agent-runtime​

Agent execution abstraction.

#[async_trait::async_trait]
pub trait AgentRuntime {
    async fn start_run(&self, request: AgentRunRequest) -> anyhow::Result<AgentRunHandle>;
    async fn cancel_run(&self, run_id: &str) -> anyhow::Result<()>;
    async fn stream_logs(&self, run_id: &str) -> anyhow::Result<()>;
}

Libraries: async-trait, serde, tokio, thiserror.

nexus-ai-runtime​

The agent-execution library. Nexus does not adopt an external "agent framework" as its core — it owns orchestration and treats model APIs and coding-agent CLIs as pluggable backends behind one trait:

#[async_trait::async_trait]
pub trait AgentBackend: Send + Sync {
    fn kind(&self) -> AgentBackendKind;
    async fn run(&self, req: AgentRunRequest) -> anyhow::Result<AgentRunResult>;
}

Backends:

KindImplementation
OpenAiApiOpenAiApiBackend — via genai
AnthropicApiAnthropicApiBackend — direct reqwest (Anthropic Messages API)
ClaudeCodeCliClaudeCodeCliBackend — claude -p --output-format stream-json
CodexCliCodexCliBackend — codex exec --json --sandbox workspace-write --output-schema
OpenAiCliOpenAiCliBackend — openai responses create --format json
CustomCliconstruct your own

Every agent is instructed to emit a final {status, summary, files_changed, next_tasks} JSON block; result_parse extracts it (fenced block or bare object) and JsonlEventParser reads CLI event streams for text, token usage, and cost. build_backend(&BackendSpec) turns an agent document's declarative backend config into a live backend — the backend is data, not a compiled choice.

Libraries: genai, reqwest, tokio (process), async-trait, serde, serde_json, schemars, uuid, tokio-stream, thiserror, anyhow, tracing. Optional async-openai behind the openai-sdk feature.

nexus-k8s​

Kubernetes implementation of the runtime: create Jobs, watch pods, stream logs, set resource limits, mount secrets, delete/cancel jobs. kube-rs is the main Rust client/controller ecosystem.

Libraries: kube, k8s-openapi, serde, tokio, futures, tracing.

nexus-skills​

Skill registry: create/version skills, attach to agents, render into runtime context, validate skill YAML, test against sample tasks.

Libraries: serde, serde_yaml, pulldown-cmark, schemars, jsonschema, semver.

nexus-memory​

Memory system: project / agent_private / global / task memory, the approval queue, retrieval. Start simple (text search + tags + importance + scope filtering); add a vector DB (Qdrant / Atlas Vector Search / pgvector) later.

Libraries: mongodb, serde, serde_json, regex, rust-stemmers (opt), reqwest (opt, embeddings).

nexus-llm​

LLM provider abstraction — your own trait, not tied to one SDK.

#[async_trait::async_trait]
pub trait LlmProvider {
    async fn complete(&self, request: LlmRequest) -> anyhow::Result<LlmResponse>;
}

Implementations: OpenAiProvider, AnthropicProvider, LocalOpenAiCompatibleProvider. Libraries: reqwest, serde, async-trait, tokio, backoff, tiktoken-rs (opt).

nexus-git​

Git / PR operations: clone, branch, commit, diff, push, open PR, read changed files. Inside agent containers use the git CLI for reliability; in Core use API clients for PR creation.

Libraries: git2 or gix, reqwest, octocrab (opt GitHub), gitlab (opt), duct, tempfile.

nexus-auth​

Authentication and permissions: admin users, API keys, agent tokens, Telegram allowlist, tool permissions, project permissions.

agent.can_commit · agent.can_open_pr · agent.can_merge
agent.can_use_kubectl · agent.can_apply_k8s
agent.can_write_memory · agent.can_create_plane_task

Libraries: jsonwebtoken, argon2, rand, serde, axum-extra, tower-http.

nexus-observability​

Metrics, logs, traces.

nexus_agent_runs_total · nexus_agent_run_failures_total
nexus_task_duration_seconds · nexus_plane_sync_errors_total
nexus_llm_tokens_total · nexus_llm_cost_usd_total

Libraries: tracing, tracing-subscriber, opentelemetry, opentelemetry-otlp, metrics, metrics-exporter-prometheus.