docs: comprehensive README rewrite — orchestrator, gRPC, code indexing, new tools

Cover the transport-agnostic orchestrator, gRPC CodeAgent service, tree-sitter code indexing, client/server tool dispatch, research tool, SearXNG web search, Kratos identity tools, breadcrumbs, and all new config sections.
2026-03-24 12:58:18 +00:00
parent 4528739a5f
commit 2949ea354f
1 changed files with 245 additions and 100 deletions
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Sol

-A virtual librarian for Matrix. Sol lives in your chat rooms, archives conversations in OpenSearch, and responds with the help of Mistral AI — with end-to-end encryption, tool use, per-user memory, and a multi-agent architecture.
+A virtual librarian for Matrix. Sol lives in your chat rooms, archives conversations in OpenSearch, and responds with the help of Mistral AI — with end-to-end encryption, tool use, per-user memory, a multi-agent architecture, and a gRPC coding agent service.

 Sol is built by [Sunbeam Studios](https://sunbeam.pt) as part of our self-hosted collaboration stack.

@@ -8,12 +8,17 @@ Sol is built by [Sunbeam Studios](https://sunbeam.pt) as part of our self-hosted

 - **Matrix Presence** — Joins rooms, reads the vibe, decides when to speak. Direct messages always get a response; in group rooms, Sol evaluates relevance before jumping in.
 - **Message Archive** — Every message is indexed in OpenSearch with full-text and semantic search. Sol can search its own archive via tools.
- **Tool Use** — Mistral calls tools mid-conversation: archive search, room context retrieval, room info, and a sandboxed TypeScript/JavaScript runtime (deno_core) for computation.
+- **Tool Use** — Mistral calls tools mid-conversation: archive search, code search, room context retrieval, web search, a sandboxed TypeScript/JavaScript runtime (deno_core), and parallel research agents.
 - **Per-User Memory** — Sol remembers things about the people it talks to. Memories are extracted automatically after conversations, injected into the system prompt before responding, and accessible from scripts via `sol.memory.get/set`.
 - **User Impersonation** — Sol acts on behalf of users when calling external services. PATs are auto-provisioned via admin APIs and stored securely in OpenBao (Vault). OIDC-to-service username mappings handle identity mismatches.
- **Gitea Integration** — First domain agent (sol-devtools): list repos, search issues, create issues, list PRs, get file contents — all as the requesting user.
+- **Gitea Integration** — Devtools agent: list repos, search issues, create issues, list PRs, get file contents, search code, create pull requests — all as the requesting user.
+- **Identity Management** — Kratos integration for user account operations: create, get, list, update, delete users via the admin API.
 - **Multi-Agent Architecture** — An orchestrator agent with personality + tools + web search. Domain agent delegation is dynamic — only active agents appear in instructions. Agent state is persisted in SQLite with instructions hash for automatic recreation on prompt changes.
 - **Conversations API** — Persistent conversation state per room via Mistral's Conversations API, with automatic compaction at token thresholds. Per-message context headers inject timestamps, room info, and memory notes.
+- **Code Indexing** — Tree-sitter symbol extraction from Gitea repos (Rust, Python, TypeScript, Go, Java). Indexed to OpenSearch for hybrid keyword + semantic code search.
+- **gRPC Coding Agent** — Bidirectional streaming service for `sunbeam code` TUI sessions. Transport-agnostic orchestrator emits events; gRPC bridge translates to protobuf. JWT auth in production, dev mode for local use.
+- **Research Tool** — Spawns parallel micro-agents with depth control for multi-step research tasks.
+- **Web Search** — Self-hosted search via SearXNG. No commercial API keys needed.
 - **Multimodal** — `m.image` messages are downloaded from Matrix via `mxc://`, converted to base64 data URIs, and sent as `ContentPart::ImageUrl` to Mistral vision models.
 - **Reactions** — Sol can react to messages with emoji when it has something to express but not enough to say.
 - **E2EE** — Full end-to-end encryption via matrix-sdk with SQLite state store.
@@ -22,84 +27,66 @@ Sol is built by [Sunbeam Studios](https://sunbeam.pt) as part of our self-hosted

 ```mermaid
 flowchart TD
-    subgraph Matrix
-        sync[Matrix Sync Loop]
+    subgraph Clients
+        matrix[Matrix Sync Loop]
+        grpc[gRPC CodeAgent<br/>sunbeam code TUI]
    end

-    subgraph Engagement
+    subgraph Engagement["Engagement (Matrix only)"]
        eval[Evaluator]
        rules[Rule Checks]
        llm_eval[LLM Evaluation<br/>ministral-3b]
    end

-    subgraph Response
-        legacy[Legacy Path<br/>Manual messages + chat completions]
-        convapi[Conversations API Path<br/>ConversationRegistry + agents]
-        tools[Tool Execution]
+    subgraph Core
+        orchestrator[Orchestrator<br/>Event-driven, transport-agnostic]
+        tools[Tool Registry]
+        agents[Agent Registry<br/>Orchestrator + domain agents]
+    end
+
+    subgraph Tools
+        server_tools[Server-Side Tools<br/>search_archive, search_code,<br/>list_rooms, get_room_members,<br/>get_room_context, run_script,<br/>search_web, research,<br/>gitea_*, identity_*]
+        client_tools[Client-Side Tools<br/>file_read, file_write,<br/>search_replace, grep, bash,<br/>list_directory, lsp_*]
    end

    subgraph Persistence
-        sqlite[(SQLite<br/>conversations + agents)]
-        opensearch[(OpenSearch<br/>archive + memory)]
+        sqlite[(SQLite<br/>conversations, agents,<br/>service_users)]
+        opensearch[(OpenSearch<br/>archive, memory, code)]
    end

-    sync --> |message event| eval
+    subgraph External
+        mistral[Mistral AI<br/>Agents + Conversations API]
+        gitea[Gitea<br/>repos, issues, PRs, code]
+        searxng[SearXNG<br/>web search]
+        vault[OpenBao<br/>user tokens]
+        kratos[Kratos<br/>identity management]
+    end
+
+    matrix --> eval
    eval --> rules
-    rules --> |MustRespond| Response
+    rules --> |MustRespond| orchestrator
    rules --> |no rule match| llm_eval
-    llm_eval --> |MaybeRespond| Response
-    llm_eval --> |React| sync
-    llm_eval --> |Ignore| sync
-    legacy --> tools
-    convapi --> tools
-    tools --> opensearch
-    legacy --> |response text| sync
-    convapi --> |response text| sync
-    sync --> |archive| opensearch
-    convapi --> sqlite
-    sync --> |memory extraction| opensearch
-```
+    llm_eval --> |MaybeRespond| orchestrator
+    llm_eval --> |React/Ignore| matrix

-## Source Tree
+    grpc --> orchestrator

-```
-src/
-├── main.rs                 Entrypoint, Matrix client setup, backfill, orchestrator init
-├── sync.rs                 Event loop — messages, reactions, redactions, invites
-├── config.rs               TOML config with serde defaults
-├── context.rs              ResponseContext — per-message sender identity threading
-├── conversations.rs        ConversationRegistry — room→conversation mapping, SQLite-backed
-├── persistence.rs          SQLite store (WAL mode, tables: conversations, agents, service_users)
-├── agent_ux.rs             AgentProgress — reaction lifecycle (🔍→⚙️→✅) + thread posting
-├── matrix_utils.rs         Message extraction, reply/edit/thread detection, image download
-├── archive/
-│   ├── schema.rs           ArchiveDocument, OpenSearch index mapping
-│   └── indexer.rs          Batched indexing, reactions, edits, redactions
-├── brain/
-│   ├── conversation.rs     Sliding-window context per room (configurable group/DM windows)
-│   ├── evaluator.rs        Engagement decision (MustRespond/MaybeRespond/React/Ignore)
-│   ├── personality.rs      System prompt templating ({date}, {room_name}, {members}, etc.)
-│   └── responder.rs        Both response paths, tool iteration loops, memory loading
-├── memory/
-│   ├── schema.rs           MemoryDocument, index mapping
-│   ├── store.rs            Query (topical), get_recent, set — OpenSearch operations
-│   └── extractor.rs        Post-response fact extraction via ministral-3b
-├── agents/
-│   ├── definitions.rs      Orchestrator config + domain agent definitions (dynamic delegation)
-│   └── registry.rs         Agent lifecycle with instructions hash staleness detection
-├── sdk/
-│   ├── mod.rs              SDK module root
-│   ├── vault.rs            OpenBao/Vault client (K8s auth, KV v2 read/write/delete)
-│   ├── tokens.rs           TokenStore — Vault-backed secrets + SQLite username mappings
-│   └── gitea.rs            GiteaClient — typed Gitea API v1 with PAT auto-provisioning
-└── tools/
-    ├── mod.rs              ToolRegistry — tool definitions + dispatch (core + gitea)
-    ├── search.rs           Archive search (keyword + semantic via embedding pipeline)
-    ├── room_history.rs     Context around a timestamp or event
-    ├── room_info.rs        Room listing, member queries
-    ├── script.rs           deno_core sandbox with sol.* host API, TS transpilation
-    ├── devtools.rs         Gitea tool handlers (repos, issues, PRs, files)
-    └── bridge.rs           ToolBridge — generic async handler map for future SDK integration
+    orchestrator --> mistral
+    orchestrator --> tools
+    tools --> server_tools
+    tools --> |relay to client| client_tools
+
+    server_tools --> opensearch
+    server_tools --> gitea
+    server_tools --> searxng
+    server_tools --> kratos
+
+    orchestrator --> |response| matrix
+    orchestrator --> |events| grpc
+    orchestrator --> sqlite
+    matrix --> |archive| opensearch
+    matrix --> |memory extraction| opensearch
+    agents --> mistral
 ```

 ## Engagement Pipeline
@@ -110,7 +97,7 @@ sequenceDiagram
    participant S as Sync Handler
    participant E as Evaluator
    participant LLM as ministral-3b
-    participant R as Responder
+    participant O as Orchestrator

    M->>S: m.room.message
    S->>S: Archive message
@@ -140,55 +127,140 @@ sequenceDiagram
    alt MustRespond or MaybeRespond
        S->>S: Check in-flight guard
        S->>S: Check cooldown (15s default)
-        S->>R: Generate response
+        S->>O: Generate response
    end
 ```

-## Response Generation
+## Orchestrator

-Sol has two response paths, controlled by `agents.use_conversations_api`:
+The orchestrator is a transport-agnostic, event-driven pipeline that sits between input sources (Matrix sync, gRPC sessions) and Mistral's Agents API. It has no knowledge of Matrix, gRPC, or any specific UI — transport bridges subscribe to its events and translate to their protocol.

-### Legacy Path (`generate_response`)
+```mermaid
+flowchart LR
+    subgraph Input
+        matrix_bridge[Matrix Bridge]
+        grpc_bridge[gRPC Bridge]
+    end

-1. Apply response delay (random within configured range)
-2. Send typing indicator
-3. Load memory notes (topical query + recent backfill, max 5)
-4. Build system prompt via `Personality` (template substitution: `{date}`, `{room_name}`, `{members}`, `{memory_notes}`, `{room_context_rules}`, `{epoch_ms}`)
-5. Assemble message array: system → context messages (with timestamps) → trigger (multimodal if image)
-6. Tool iteration loop (up to `max_tool_iterations`, default 5):
-   - If `finish_reason == ToolCalls`: execute tools, append results, continue
-   - If text response: strip "sol:" prefix, return
-7. Fire-and-forget memory extraction
+    subgraph Orchestrator
+        request[GenerateRequest]
+        engine[Engine<br/>tool loop]
+        events[OrchestratorEvent<br/>broadcast channel]
+    end

-### Conversations API Path (`generate_response_conversations`)
+    subgraph Output
+        matrix_out[Matrix Room]
+        grpc_out[gRPC Stream]
+    end

-1. Apply response delay
-2. Send typing indicator
-3. Load memory notes for the user
-4. Build per-message context header (timestamps, room name, memory notes)
-5. Format input: raw text for DMs, `<@user:server> text` for groups
-6. Send through `ConversationRegistry.send_message()` (creates or appends to Mistral conversation)
-7. Function call loop (up to `max_tool_iterations`):
-   - Execute tool calls locally via `ToolRegistry`
-   - Send `FunctionResultEntry` back to conversation
-8. Extract assistant text, strip prefix, return
+    matrix_bridge --> request
+    grpc_bridge --> request
+    request --> engine
+    engine --> events
+    events --> matrix_out
+    events --> grpc_out
+```
+
+Events emitted during response generation:
+
+| Event | Description |
+|-------|-------------|
+| `Started` | Generation begun, carries routing metadata |
+| `Thinking` | Model is generating |
+| `ToolCallDetected` | Tool call found in output (server-side or client-side) |
+| `ToolStarted` | Tool execution began |
+| `ToolCompleted` | Tool finished with result preview |
+| `Done` | Final response text + token usage |
+| `Failed` | Generation error |
+
+Tool dispatch routes calls to either the server (Sol executes them) or the client (relayed to the gRPC TUI for local execution). The orchestrator parks on a oneshot channel for client-side results, transparent to the tool loop.
+
+## gRPC Coding Agent
+
+Sol exposes a `CodeAgent` gRPC service for `sunbeam code` TUI sessions. The protocol is defined in `proto/code.proto`.
+
+```mermaid
+sequenceDiagram
+    participant CLI as sunbeam code
+    participant gRPC as gRPC Service
+    participant O as Orchestrator
+    participant M as Mistral
+
+    CLI->>gRPC: StartSession (project context, capabilities)
+    gRPC->>gRPC: Create Matrix room, auth
+    gRPC-->>CLI: SessionReady (session_id, room_id, model)
+
+    CLI->>gRPC: IndexSymbols (tree-sitter symbols)
+    gRPC->>gRPC: Index to OpenSearch
+
+    CLI->>gRPC: UserInput (text)
+    gRPC->>O: GenerateRequest
+    O->>M: Conversation append
+
+    alt Server-side tool
+        O->>O: Execute locally
+        gRPC-->>CLI: Status (TOOL_RUNNING → TOOL_DONE)
+    else Client-side tool
+        gRPC-->>CLI: ToolCall (is_local=true)
+        CLI->>CLI: Execute (file_read, bash, etc.)
+        CLI->>gRPC: ToolResult
+        gRPC->>O: Resume tool loop
+    end
+
+    M-->>O: Response text
+    gRPC-->>CLI: TextDone (full_text, token usage)
+```
+
+Two RPC methods:
+
+- **`Session`** — Bidirectional stream for interactive coding sessions
+- **`ReindexCode`** — On-demand Gitea repo indexing via tree-sitter
+
+Auth: JWT validation via JWKS in production, fixed dev identity when `grpc.dev_mode = true`.

 ## Tool System

+### Server-Side Tools
+
 | Tool | Parameters | Description |
 |------|-----------|-------------|
 | `search_archive` | `query` (required), `room`, `sender`, `after`, `before`, `limit`, `semantic` | Search the message archive (keyword or semantic) |
+| `search_code` | `query` (required), `language`, `repo`, `branch`, `limit` | Search the code index for functions, types, patterns |
 | `get_room_context` | `room_id` (required), `around_timestamp`, `around_event_id`, `before_count`, `after_count` | Get messages around a point in time or event |
 | `list_rooms` | *(none)* | List all rooms Sol is in with names and member counts |
 | `get_room_members` | `room_id` (required) | Get members of a specific room |
 | `run_script` | `code` (required) | Execute TypeScript/JavaScript in a sandboxed deno_core runtime |
+| `search_web` | `query` (required), `limit` | Search the web via SearXNG |
+| `research` | `query` (required), `depth` | Spawn parallel micro-agents for multi-step research |
 | `gitea_list_repos` | `query`, `org`, `limit` | List or search repositories on Gitea |
 | `gitea_get_repo` | `owner`, `repo` (required) | Get details about a specific repository |
-| `gitea_list_issues` | `owner`, `repo` (required), `state`, `labels`, `limit` | List issues in a repository |
-| `gitea_get_issue` | `owner`, `repo`, `number` (required) | Get full details of a specific issue |
+| `gitea_search_code` | `query` (required), `repo`, `limit` | Search code across Gitea repositories |
 | `gitea_create_issue` | `owner`, `repo`, `title` (required), `body`, `labels` | Create a new issue as the requesting user |
-| `gitea_list_pulls` | `owner`, `repo` (required), `state`, `limit` | List pull requests in a repository |
+| `gitea_create_pr` | `owner`, `repo`, `title`, `head`, `base` (required), `body` | Create a pull request as the requesting user |
 | `gitea_get_file` | `owner`, `repo`, `path` (required), `ref` | Get file contents from a repository |
+| `identity_create_user` | `email`, `name` (required) | Create a new user account via Kratos |
+| `identity_get_user` | `email` (required) | Get user account details |
+| `identity_list_users` | `limit` | List all user accounts |
+| `identity_update_user` | `email` (required), `name`, `active` | Update a user account |
+| `identity_delete_user` | `email` (required) | Delete a user account |
+
+Tools are conditionally registered — Gitea tools only appear when `services.gitea` is configured, Kratos tools when `services.kratos` is configured, LSP tools when the client advertises capabilities.
+
+### Client-Side Tools (gRPC sessions)
+
+| Tool | Permission | Description |
+|------|-----------|-------------|
+| `file_read` | always | Read file contents with optional line ranges |
+| `file_write` | ask | Write or create files |
+| `search_replace` | ask | Apply SEARCH/REPLACE diffs to files |
+| `grep` | always | Search files with ripgrep |
+| `bash` | ask | Execute shell commands |
+| `list_directory` | always | List directory tree |
+| `lsp_definition` | always | Jump to definition |
+| `lsp_references` | always | Find all references |
+| `lsp_hover` | always | Type info + docs |
+| `lsp_diagnostics` | always | Compiler errors |
+| `lsp_symbols` | always | Document/workspace symbols |

 ### `run_script` Sandbox

@@ -217,6 +289,39 @@ sol.fs.list(path?)               // List sandbox directory

 All `sol.*` methods are async — use `await`.

+## Code Indexing
+
+Sol indexes source code from Gitea repositories using tree-sitter for symbol extraction. Symbols are stored in OpenSearch and searchable via the `search_code` tool and adaptive breadcrumbs.
+
+```mermaid
+flowchart LR
+    subgraph Sources
+        gitea_repos[Gitea Repos<br/>via API]
+        sidecar[sunbeam code<br/>IndexSymbols]
+    end
+
+    subgraph Extraction
+        treesitter[Tree-Sitter<br/>Rust, Python, TypeScript,<br/>Go, Java]
+    end
+
+    subgraph Storage
+        opensearch_code[(OpenSearch<br/>sol_code index)]
+    end
+
+    subgraph Consumers
+        search_code_tool[search_code tool]
+        breadcrumbs[Adaptive Breadcrumbs<br/>project outline + hybrid search]
+    end
+
+    gitea_repos --> treesitter
+    sidecar --> opensearch_code
+    treesitter --> opensearch_code
+    opensearch_code --> search_code_tool
+    opensearch_code --> breadcrumbs
+```
+
+Each symbol is a `SymbolDocument` with file path, repo name, language, symbol name/kind, signature, docstring, line numbers, content, branch, and source. The `ReindexCode` gRPC endpoint triggers on-demand indexing for specific orgs, repos, or branches.
+
 ## Memory System

 ### Extraction (Post-Response, Fire-and-Forget)
@@ -246,6 +351,7 @@ Every message event is archived as an `ArchiveDocument` in OpenSearch:
 - **Redaction** — `m.room.redaction` sets `redacted: true` on the original
 - **Reactions** — `m.reaction` events append `{sender, emoji, timestamp}` to the document's reactions array
 - **Backfill** — On startup, conversation context is backfilled from the archive; reactions are backfilled from Matrix room timelines (last 500 events per room)
+- **Cross-room visibility** — Search results from other rooms are filtered by member overlap (`behavior.room_overlap_threshold`, default 0.25)

 ## Agent Architecture

@@ -269,13 +375,15 @@ stateDiagram-v2

 ### Orchestrator

-The orchestrator agent carries Sol's full personality (system prompt) plus all tool definitions converted to `AgentTool` format, including Mistral's built-in `web_search`. It's created on startup if `agents.use_conversations_api` is enabled.
+The orchestrator agent carries Sol's full personality (system prompt) plus all tool definitions converted to `AgentTool` format, including web search. It's created on startup if `agents.use_conversations_api` is enabled.

 When the system prompt changes, the instructions hash detects staleness and the agent is automatically recreated. All existing conversations are reset and Sol sneezes into all rooms to signal the context reset.

+Agent names can be prefixed via `agents.agent_prefix` — set to `"dev"` in local development to avoid colliding with production agents on the same Mistral account.
+
 ### Domain Agents

-Domain agents are defined in `agents/definitions.rs` as `DOMAIN_AGENTS` (name, description, instructions). The delegation section in the orchestrator's instructions is built dynamically — only agents that are actually registered appear.
+Domain agents are defined in `agents/definitions.rs`. The delegation section in the orchestrator's instructions is built dynamically — only agents that are actually registered appear.

 ### User Impersonation

@@ -335,6 +443,7 @@ Config is loaded from `SOL_CONFIG` (default: `/etc/sol/sol.toml`).
 | `evaluation_model` | string | `ministral-3b-latest` | Model for engagement evaluation + memory extraction |
 | `research_model` | string | `mistral-large-latest` | Model for research tasks |
 | `max_tool_iterations` | usize | `5` | Max tool call rounds per response |
+| `tokenizer_path` | string? | *(none)* | Path to local `tokenizer.json` (downloads from HuggingFace Hub if unset) |

 ### `[behavior]`

@@ -361,6 +470,8 @@ Config is loaded from `SOL_CONFIG` (default: `/etc/sol/sol.toml`).
 | `script_max_heap_mb` | usize | `64` | V8 heap limit for scripts |
 | `script_fetch_allowlist` | string[] | `[]` | Domains allowed for `sol.fetch()` |
 | `memory_extraction_enabled` | bool | `true` | Enable post-response memory extraction |
+| `room_overlap_threshold` | f32 | `0.25` | Min member overlap for cross-room search visibility |
+| `silence_duration_ms` | u64 | `1800000` | Duration Sol stays quiet when told to (30 minutes) |

 ### `[agents]`

@@ -370,6 +481,20 @@ Config is loaded from `SOL_CONFIG` (default: `/etc/sol/sol.toml`).
 | `domain_model` | string | `mistral-medium-latest` | Model for domain agents |
 | `compaction_threshold` | u32 | `118000` | Token estimate before conversation reset (~90% of 131K context) |
 | `use_conversations_api` | bool | `false` | Enable Conversations API path (vs legacy chat completions) |
+| `coding_model` | string | `mistral-medium-latest` | Model for `sunbeam code` sessions |
+| `research_model` | string | `ministral-3b-latest` | Model for research micro-agents |
+| `research_max_iterations` | usize | `10` | Max tool calls per research micro-agent |
+| `research_max_agents` | usize | `25` | Max parallel agents per research wave |
+| `research_max_depth` | usize | `4` | Max recursion depth for research agents |
+| `agent_prefix` | string | `""` | Name prefix for agents (e.g. `"dev"` to avoid production collisions) |
+
+### `[grpc]`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `listen_addr` | string | `0.0.0.0:50051` | gRPC server listen address |
+| `jwks_url` | string? | *(none)* | JWKS URL for JWT validation (required unless `dev_mode`) |
+| `dev_mode` | bool | `false` | Disable JWT auth, use fixed dev identity |

 ### `[vault]`

@@ -385,6 +510,18 @@ Config is loaded from `SOL_CONFIG` (default: `/etc/sol/sol.toml`).
 |-------|------|---------|-------------|
 | `url` | string | *required if enabled* | Gitea API base URL |

+### `[services.kratos]`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `admin_url` | string | *required if enabled* | Kratos admin API URL |
+
+### `[services.searxng]`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `url` | string | *required if enabled* | SearXNG API URL |
+
 ## Environment Variables

 | Variable | Required | Description |
@@ -399,15 +536,17 @@ Config is loaded from `SOL_CONFIG` (default: `/etc/sol/sol.toml`).

 ## Dependencies

-Sol talks to five external services:
+Sol talks to seven external services:

 - **Matrix homeserver** — [Tuwunel](https://github.com/tulir/tuwunel) (or any Matrix server)
- **OpenSearch** — Message archive + user memory indices
- **Mistral AI** — Response generation, engagement evaluation, memory extraction, agents + web search
+- **OpenSearch** — Message archive, user memory, and code symbol indices
+- **Mistral AI** — Response generation, engagement evaluation, memory extraction, agents + conversations
 - **OpenBao** — Secure token storage for user impersonation PATs (K8s auth, KV v2)
- **Gitea** — Git hosting API for devtools agent (repos, issues, PRs)
+- **Gitea** — Git hosting API for devtools agent (repos, issues, PRs, code search, indexing)
+- **Kratos** — Identity management for user account operations
+- **SearXNG** — Self-hosted web search (no API keys required)

-Key crates: `matrix-sdk` 0.9 (E2EE + SQLite), `mistralai-client` 1.1.0 (private registry), `opensearch` 2, `deno_core` 0.393, `rusqlite` 0.32 (bundled), `ruma` 0.12.
+Key crates: `matrix-sdk` 0.9 (E2EE + SQLite), `mistralai-client` 1.1.0 (private registry), `opensearch` 2, `deno_core` 0.393, `tonic` 0.14 (gRPC), `tree-sitter` 0.24, `rusqlite` 0.32 (bundled), `ruma` 0.12, `tokenizers` 0.22.

 ## Building

@@ -435,6 +574,12 @@ The Dockerfile uses a two-stage build: deps layer (cached until Cargo.toml/vendo
 cargo test
 ```

+Integration tests against the Mistral API require a `.env` file with `SOL_MISTRAL_API_KEY`:
+
+```sh
+cargo test --test integration_test
+```
+
 ## License

 Sol is dual-licensed: