72 lines
3.7 KiB
Markdown
72 lines
3.7 KiB
Markdown
|
# Sol — Developer Context
|
||
|
|
|
||
|
|
## Build & Test
|
||
|
|
|
||
|
|
```sh
|
||
|
|
cargo build --release # debug: cargo build
|
||
|
|
cargo test # 102 unit tests, no external services needed
|
||
|
|
cargo build --release --target x86_64-unknown-linux-gnu # cross-compile for production
|
||
|
|
```
|
||
|
|
|
||
|
|
Docker (multi-stage, vendored deps):
|
||
|
|
|
||
|
|
```sh
|
||
|
|
docker build -t sol .
|
||
|
|
```
|
||
|
|
|
||
|
|
Production build + deploy via sunbeam CLI:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
sunbeam build sol --push --deploy
|
||
|
|
```
|
||
|
|
|
||
|
|
## Private Cargo Registry
|
||
|
|
|
||
|
|
`mistralai-client` is published to Sunbeam's private Gitea cargo registry at `src.sunbeam.pt`. The crate is vendored into `vendor/` for Docker builds. Registry config lives in `.cargo/config.toml` (not checked in — generated by Dockerfile and locally via `cargo vendor vendor/`).
|
||
|
|
|
||
|
|
## Vendor Workflow
|
||
|
|
|
||
|
|
After adding/updating deps:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
cargo vendor vendor/
|
||
|
|
```
|
||
|
|
|
||
|
|
This updates the vendored sources. Commit `vendor/` changes alongside `Cargo.lock`.
|
||
|
|
|
||
|
|
## Key Architecture Notes
|
||
|
|
|
||
|
|
- **`chat_blocking()` workaround**: The Mistral client's `chat_async` holds a `std::sync::MutexGuard` across `.await`, making the future `!Send`. All chat calls use `chat_blocking()` which runs `client.chat()` via `tokio::task::spawn_blocking`.
|
||
|
|
- **Two response paths**: Controlled by `agents.use_conversations_api` config toggle.
|
||
|
|
- Legacy: manual `Vec<ChatMessage>` assembly, chat completions, tool iteration loop.
|
||
|
|
- Conversations API: `ConversationRegistry` with persistent state (SQLite-backed), agents, function call loop.
|
||
|
|
- **deno_core sandbox**: `run_script` tool spins up a fresh V8 isolate per invocation with `sol.*` host API bindings. Timeout via V8 isolate termination. Output truncated to 4096 chars.
|
||
|
|
|
||
|
|
## K8s Context
|
||
|
|
|
||
|
|
- Namespace: `matrix`
|
||
|
|
- Deployment: `sol` (Recreate strategy — single replica, SQLite can't share)
|
||
|
|
- PVC: `sol-data` (1Gi RWO) mounted at `/data` — holds `sol.db` + `matrix-state/`
|
||
|
|
- ConfigMap: `sol-config` — `sol.toml` + `system_prompt.md` (subPath mounts)
|
||
|
|
- Secrets: `sol-secrets` via VaultStaticSecret from OpenBao `secret/sol` (5 keys: `matrix-access-token`, `matrix-device-id`, `mistral-api-key`, `gitea-admin-username`, `gitea-admin-password`)
|
||
|
|
- Vault auth: Sol authenticates to OpenBao via K8s auth (role `sol-agent`, policy `sol-agent`) for storing user impersonation tokens at `secret/sol-tokens/{localpart}/{service}`
|
||
|
|
- Build target: `x86_64-unknown-linux-gnu` (Scaleway amd64 server)
|
||
|
|
- Base image: `gcr.io/distroless/cc-debian12:nonroot`
|
||
|
|
|
||
|
|
## Source Layout
|
||
|
|
|
||
|
|
- `src/main.rs` — startup, component wiring, backfill, agent recreation + sneeze
|
||
|
|
- `src/sync.rs` — Matrix event handlers, context hint injection for new conversations
|
||
|
|
- `src/config.rs` — TOML config with serde defaults (6 sections: matrix, opensearch, mistral, behavior, agents, services, vault)
|
||
|
|
- `src/context.rs` — `ResponseContext`, `derive_user_id`, `localpart`
|
||
|
|
- `src/conversations.rs` — `ConversationRegistry` (room→conversation mapping, SQLite-backed, reset_all)
|
||
|
|
- `src/persistence.rs` — SQLite store (WAL mode, 3 tables: `conversations`, `agents`, `service_users`)
|
||
|
|
- `src/agent_ux.rs` — `AgentProgress` (reaction lifecycle + thread posting)
|
||
|
|
- `src/matrix_utils.rs` — message extraction, image download, reactions
|
||
|
|
- `src/brain/` — evaluator (full system prompt context), responder (per-message context headers + memory), personality, conversation manager
|
||
|
|
- `src/agents/` — registry (instructions hash + automatic recreation), definitions (dynamic delegation)
|
||
|
|
- `src/sdk/` — vault client (K8s auth), token store (Vault-backed), gitea client (PAT auto-provisioning)
|
||
|
|
- `src/memory/` — schema, store, extractor
|
||
|
|
- `src/tools/` — registry (12 tools), search, room_history, room_info, script, devtools (gitea), bridge
|
||
|
|
- `src/archive/` — schema, indexer
|