957 lines
60 KiB
Markdown
957 lines
60 KiB
Markdown
# Phase 1 Implementation Plan: Extract AppState from Config
|
||
|
||
## Overview
|
||
|
||
Split the monolithic `Config` struct into:
|
||
- **`AppConfig`** — immutable server-wide settings (deserialized from `config.yaml`)
|
||
- **`RequestContext`** — per-request mutable state (current role, session, agent, supervisor, etc.)
|
||
|
||
The existing `GlobalConfig` (`Arc<RwLock<Config>>`) type alias is replaced. CLI and REPL continue working identically. No API code is added in this phase.
|
||
|
||
**Estimated effort:** ~3-4 weeks (originally estimated 1-2 weeks; revised during implementation as Steps 6.5 and 7 deferred their semantic rewrites to an expanded Step 8)
|
||
**Risk:** Medium — touches 91 callsites across 15 modules
|
||
**Mitigation:** Incremental migration with tests passing at every step
|
||
**Sub-step tracking:** Each step has per-step implementation notes in `docs/implementation/PHASE-1-STEP-*-NOTES.md`
|
||
|
||
---
|
||
|
||
## Current State: Config Field Classification
|
||
|
||
### Serialized Fields (from config.yaml → AppConfig)
|
||
|
||
These are loaded from disk once and should be immutable during request processing:
|
||
|
||
| Field | Type | Notes |
|
||
|---|---|---|
|
||
| `model_id` | `String` | Default model ID |
|
||
| `temperature` | `Option<f64>` | Default temperature |
|
||
| `top_p` | `Option<f64>` | Default top_p |
|
||
| `dry_run` | `bool` | Can be overridden per-request |
|
||
| `stream` | `bool` | Can be overridden per-request |
|
||
| `save` | `bool` | Whether to persist to messages.md |
|
||
| `keybindings` | `String` | REPL keybinding style |
|
||
| `editor` | `Option<String>` | Editor command |
|
||
| `wrap` | `Option<String>` | Text wrapping |
|
||
| `wrap_code` | `bool` | Code block wrapping |
|
||
| `vault_password_file` | `Option<PathBuf>` | Vault password location |
|
||
| `function_calling_support` | `bool` | Global function calling toggle |
|
||
| `mapping_tools` | `IndexMap<String, String>` | Tool aliases |
|
||
| `enabled_tools` | `Option<String>` | Default enabled tools |
|
||
| `visible_tools` | `Option<Vec<String>>` | Visible tool list |
|
||
| `mcp_server_support` | `bool` | Global MCP toggle |
|
||
| `mapping_mcp_servers` | `IndexMap<String, String>` | MCP server aliases |
|
||
| `enabled_mcp_servers` | `Option<String>` | Default enabled MCP servers |
|
||
| `repl_prelude` | `Option<String>` | REPL prelude config |
|
||
| `cmd_prelude` | `Option<String>` | CLI prelude config |
|
||
| `agent_session` | `Option<String>` | Default agent session |
|
||
| `save_session` | `Option<bool>` | Session save behavior |
|
||
| `compression_threshold` | `usize` | Session compression threshold |
|
||
| `summarization_prompt` | `Option<String>` | Compression prompt |
|
||
| `summary_context_prompt` | `Option<String>` | Summary context prompt |
|
||
| `rag_embedding_model` | `Option<String>` | RAG embedding model |
|
||
| `rag_reranker_model` | `Option<String>` | RAG reranker model |
|
||
| `rag_top_k` | `usize` | RAG top-k results |
|
||
| `rag_chunk_size` | `Option<usize>` | RAG chunk size |
|
||
| `rag_chunk_overlap` | `Option<usize>` | RAG chunk overlap |
|
||
| `rag_template` | `Option<String>` | RAG template |
|
||
| `document_loaders` | `HashMap<String, String>` | Document loader mappings |
|
||
| `highlight` | `bool` | Syntax highlighting |
|
||
| `theme` | `Option<String>` | Color theme |
|
||
| `left_prompt` | `Option<String>` | REPL left prompt format |
|
||
| `right_prompt` | `Option<String>` | REPL right prompt format |
|
||
| `user_agent` | `Option<String>` | HTTP User-Agent |
|
||
| `save_shell_history` | `bool` | Shell history persistence |
|
||
| `sync_models_url` | `Option<String>` | Models sync URL |
|
||
| `clients` | `Vec<ClientConfig>` | LLM provider configs |
|
||
|
||
### Runtime Fields (#[serde(skip)] → RequestContext)
|
||
|
||
These are created at runtime and are per-request/per-session mutable state:
|
||
|
||
| Field | Type | Destination |
|
||
|---|---|---|
|
||
| `vault` | `GlobalVault` | `AppState.vault` (shared service) |
|
||
| `macro_flag` | `bool` | `RequestContext.macro_flag` |
|
||
| `info_flag` | `bool` | `RequestContext.info_flag` |
|
||
| `agent_variables` | `Option<AgentVariables>` | `RequestContext.agent_variables` |
|
||
| `model` | `Model` | `RequestContext.model` |
|
||
| `functions` | `Functions` | `RequestContext.tool_scope.functions` (unified in Step 6) |
|
||
| `mcp_registry` | `Option<McpRegistry>` | **REMOVED.** Replaced by per-`ToolScope` `McpRuntime`s produced by a new `McpFactory` on `AppState`. See the architecture doc's "Tool Scope Isolation" section. |
|
||
| `working_mode` | `WorkingMode` | `RequestContext.working_mode` |
|
||
| `last_message` | `Option<LastMessage>` | `RequestContext.last_message` |
|
||
| `role` | `Option<Role>` | `RequestContext.role` |
|
||
| `session` | `Option<Session>` | `RequestContext.session` |
|
||
| `rag` | `Option<Arc<Rag>>` | `RequestContext.rag` |
|
||
| `agent` | `Option<Agent>` | `RequestContext.agent` (agent spec + role + RAG) |
|
||
| `tool_call_tracker` | `Option<ToolCallTracker>` | `RequestContext.tool_scope.tool_tracker` (unified in Step 6) |
|
||
| `supervisor` | `Option<Arc<RwLock<Supervisor>>>` | `RequestContext.agent_runtime.supervisor` |
|
||
| `parent_supervisor` | `Option<Arc<RwLock<Supervisor>>>` | `RequestContext.agent_runtime.parent_supervisor` |
|
||
| `self_agent_id` | `Option<String>` | `RequestContext.agent_runtime.self_agent_id` |
|
||
| `current_depth` | `usize` | `RequestContext.agent_runtime.current_depth` |
|
||
| `inbox` | `Option<Arc<Inbox>>` | `RequestContext.agent_runtime.inbox` |
|
||
| `root_escalation_queue` | `Option<Arc<EscalationQueue>>` | `RequestContext.agent_runtime.escalation_queue` (shared from the root via `Arc`) |
|
||
|
||
**Note on `ToolScope` and `AgentRuntime`:** during Phase 1 Step 0 the new `RequestContext` struct keeps `functions`, `tool_call_tracker`, supervisor/inbox/escalation fields as **flat fields** mirroring today's `Config`. This is deliberate — it makes the field-by-field migration mechanical. In Step 6.5 these fields collapse into two sub-structs:
|
||
|
||
- `ToolScope { functions, mcp_runtime, tool_tracker }` — owned by every active `RoleLike` scope, rebuilt on role/session/agent transitions via `McpFactory::acquire()`.
|
||
- `AgentRuntime { spec, rag, supervisor, inbox, escalation_queue, todo_list, self_agent_id, parent_supervisor, current_depth, auto_continue_count }` — owned only when an agent is active.
|
||
|
||
**Two behavior changes land during Step 6.5** that tighten today's code:
|
||
|
||
1. `todo_list` becomes `Option<TodoList>`. Today the code always allocates `TodoList::default()` for every agent, even when `auto_continue: false`. Since the todo tools and instructions are only exposed when `auto_continue: true`, the allocation is wasted. The new shape skips allocation unless the agent opts in. No user-visible change.
|
||
|
||
2. A unified `RagCache` on `AppState` serves **both** standalone RAGs (attached via `.rag <name>`) and agent-owned RAGs (loaded from an agent's `documents:` field). Today, both paths independently call `Rag::load` from disk on every use; with the cache, any scope requesting the same `RagKey` shares the same `Arc<Rag>`. Standalone RAG lives in `ctx.rag`; agent RAG lives in `ctx.agent_runtime.rag`. Roles and Sessions do **not** own RAG (the structs have no RAG fields) — this is true today and unchanged by the refactor. `rebuild_rag` and `edit_rag_docs` call `RagCache::invalidate()`.
|
||
|
||
See `docs/REST-API-ARCHITECTURE.md` section 5 for the full `ToolScope`, `McpFactory`, `RagCache`, and MCP pooling designs.
|
||
|
||
---
|
||
|
||
## Migration Strategy: The Facade Pattern
|
||
|
||
**Do NOT rewrite everything at once.** Instead, use a transitional facade that keeps the old `Config` working while new code uses the split types.
|
||
|
||
### Step 0: Add new types alongside Config (no breaking changes) ✅ DONE
|
||
|
||
Create the new structs in new files. `Config` stays untouched. Nothing breaks.
|
||
|
||
**Files created:**
|
||
- `src/config/app_config.rs` — `AppConfig` struct (the serialized half)
|
||
- `src/config/request_context.rs` — `RequestContext` struct (the runtime half)
|
||
- `src/config/app_state.rs` — `AppState` struct (Arc-wrapped global services, no `mcp_registry` — see below)
|
||
|
||
**`AppConfig`** is essentially the current `Config` struct but containing ONLY the serialized fields (no `#[serde(skip)]` fields). It should derive `Deserialize` identically so the existing `config.yaml` still loads.
|
||
|
||
**Important change from the original plan:** `AppState` does NOT hold an `McpRegistry`. MCP server processes are scoped per `RoleLike`, not process-wide. An `McpFactory` service will be added to `AppState` in Step 6.5. See `docs/REST-API-ARCHITECTURE.md` section 5 for the design rationale.
|
||
|
||
```rust
|
||
// src/config/app_config.rs
|
||
#[derive(Debug, Clone, Deserialize)]
|
||
#[serde(default)]
|
||
pub struct AppConfig {
|
||
#[serde(rename(serialize = "model", deserialize = "model"))]
|
||
pub model_id: String,
|
||
pub temperature: Option<f64>,
|
||
pub top_p: Option<f64>,
|
||
pub dry_run: bool,
|
||
pub stream: bool,
|
||
pub save: bool,
|
||
pub keybindings: String,
|
||
pub editor: Option<String>,
|
||
pub wrap: Option<String>,
|
||
pub wrap_code: bool,
|
||
vault_password_file: Option<PathBuf>,
|
||
pub function_calling_support: bool,
|
||
pub mapping_tools: IndexMap<String, String>,
|
||
pub enabled_tools: Option<String>,
|
||
pub visible_tools: Option<Vec<String>>,
|
||
pub mcp_server_support: bool,
|
||
pub mapping_mcp_servers: IndexMap<String, String>,
|
||
pub enabled_mcp_servers: Option<String>,
|
||
pub repl_prelude: Option<String>,
|
||
pub cmd_prelude: Option<String>,
|
||
pub agent_session: Option<String>,
|
||
pub save_session: Option<bool>,
|
||
pub compression_threshold: usize,
|
||
pub summarization_prompt: Option<String>,
|
||
pub summary_context_prompt: Option<String>,
|
||
pub rag_embedding_model: Option<String>,
|
||
pub rag_reranker_model: Option<String>,
|
||
pub rag_top_k: usize,
|
||
pub rag_chunk_size: Option<usize>,
|
||
pub rag_chunk_overlap: Option<usize>,
|
||
pub rag_template: Option<String>,
|
||
pub document_loaders: HashMap<String, String>,
|
||
pub highlight: bool,
|
||
pub theme: Option<String>,
|
||
pub left_prompt: Option<String>,
|
||
pub right_prompt: Option<String>,
|
||
pub user_agent: Option<String>,
|
||
pub save_shell_history: bool,
|
||
pub sync_models_url: Option<String>,
|
||
pub clients: Vec<ClientConfig>,
|
||
}
|
||
```
|
||
|
||
```rust
|
||
// src/config/app_state.rs
|
||
#[derive(Clone)]
|
||
pub struct AppState {
|
||
pub config: Arc<AppConfig>,
|
||
pub vault: GlobalVault,
|
||
// NOTE: no `mcp_registry` field. MCP runtime is scoped per-`ToolScope`
|
||
// on `RequestContext`, not process-wide. An `McpFactory` will be added
|
||
// here later (Step 6 / Phase 5) to pool and ref-count MCP processes
|
||
// across concurrent ToolScopes. See architecture doc section 5.
|
||
}
|
||
```
|
||
|
||
```rust
|
||
// src/config/request_context.rs
|
||
pub struct RequestContext {
|
||
pub app: Arc<AppState>,
|
||
|
||
// per-request flags
|
||
pub macro_flag: bool,
|
||
pub info_flag: bool,
|
||
pub working_mode: WorkingMode,
|
||
|
||
// active context
|
||
pub model: Model,
|
||
pub functions: Functions,
|
||
pub role: Option<Role>,
|
||
pub session: Option<Session>,
|
||
pub rag: Option<Arc<Rag>>,
|
||
pub agent: Option<Agent>,
|
||
pub agent_variables: Option<AgentVariables>,
|
||
|
||
// conversation state
|
||
pub last_message: Option<LastMessage>,
|
||
pub tool_call_tracker: Option<ToolCallTracker>,
|
||
|
||
// agent supervision
|
||
pub supervisor: Option<Arc<RwLock<Supervisor>>>,
|
||
pub parent_supervisor: Option<Arc<RwLock<Supervisor>>>,
|
||
pub self_agent_id: Option<String>,
|
||
pub current_depth: usize,
|
||
pub inbox: Option<Arc<Inbox>>,
|
||
pub root_escalation_queue: Option<Arc<EscalationQueue>>,
|
||
}
|
||
```
|
||
|
||
### Step 1: Make Config constructible from AppConfig + RequestContext
|
||
|
||
Add conversion methods so the old `Config` can be built from the new types, and vice versa. This is the bridge that lets us migrate incrementally.
|
||
|
||
```rust
|
||
// On Config:
|
||
impl Config {
|
||
/// Extract the global portion into AppConfig
|
||
pub fn to_app_config(&self) -> AppConfig { /* copy serialized fields */ }
|
||
|
||
/// Extract the runtime portion into RequestContext
|
||
pub fn to_request_context(&self, app: Arc<AppState>) -> RequestContext { /* copy runtime fields */ }
|
||
|
||
/// Reconstruct Config from the split types (for backward compat during migration)
|
||
pub fn from_parts(app: &AppState, ctx: &RequestContext) -> Config { /* merge back */ }
|
||
}
|
||
```
|
||
|
||
**Test:** After this step, `Config::from_parts(config.to_app_config(), config.to_request_context())` round-trips correctly. Existing tests still pass.
|
||
|
||
### Step 2: Migrate static methods off Config
|
||
|
||
There are ~30 static methods on Config (no `self` parameter). These are pure utility functions that don't need Config at all — they compute file paths, list directories, etc.
|
||
|
||
**Target:** Move these to a standalone `paths` module or keep on `AppConfig` where appropriate.
|
||
|
||
| Method | Move to |
|
||
|---|---|
|
||
| `config_dir()` | `paths::config_dir()` |
|
||
| `local_path(name)` | `paths::local_path(name)` |
|
||
| `cache_path()` | `paths::cache_path()` |
|
||
| `oauth_tokens_path()` | `paths::oauth_tokens_path()` |
|
||
| `token_file(client)` | `paths::token_file(client)` |
|
||
| `log_path()` | `paths::log_path()` |
|
||
| `config_file()` | `paths::config_file()` |
|
||
| `roles_dir()` | `paths::roles_dir()` |
|
||
| `role_file(name)` | `paths::role_file(name)` |
|
||
| `macros_dir()` | `paths::macros_dir()` |
|
||
| `macro_file(name)` | `paths::macro_file(name)` |
|
||
| `env_file()` | `paths::env_file()` |
|
||
| `rags_dir()` | `paths::rags_dir()` |
|
||
| `functions_dir()` | `paths::functions_dir()` |
|
||
| `functions_bin_dir()` | `paths::functions_bin_dir()` |
|
||
| `mcp_config_file()` | `paths::mcp_config_file()` |
|
||
| `global_tools_dir()` | `paths::global_tools_dir()` |
|
||
| `global_utils_dir()` | `paths::global_utils_dir()` |
|
||
| `bash_prompt_utils_file()` | `paths::bash_prompt_utils_file()` |
|
||
| `agents_data_dir()` | `paths::agents_data_dir()` |
|
||
| `agent_data_dir(name)` | `paths::agent_data_dir(name)` |
|
||
| `agent_config_file(name)` | `paths::agent_config_file(name)` |
|
||
| `agent_bin_dir(name)` | `paths::agent_bin_dir(name)` |
|
||
| `agent_rag_file(agent, rag)` | `paths::agent_rag_file(agent, rag)` |
|
||
| `agent_functions_file(name)` | `paths::agent_functions_file(name)` |
|
||
| `models_override_file()` | `paths::models_override_file()` |
|
||
| `list_roles(with_builtin)` | `Role::list(with_builtin)` or `paths` |
|
||
| `list_rags()` | `Rag::list()` or `paths` |
|
||
| `list_macros()` | `Macro::list()` or `paths` |
|
||
| `has_role(name)` | `Role::exists(name)` |
|
||
| `has_macro(name)` | `Macro::exists(name)` |
|
||
| `sync_models(url, abort)` | Standalone function or on `AppConfig` |
|
||
| `local_models_override()` | Standalone function |
|
||
| `log_config()` | Standalone function |
|
||
|
||
**Approach:** Create `src/config/paths.rs`, move functions there, and add `#[deprecated]` forwarding methods on `Config` that call the new locations. Compile, run tests, fix callsites module by module, then remove the deprecated methods.
|
||
|
||
**Callsite count:** Low — most of these are called from 1-3 places. This is a quick-win step.
|
||
|
||
### Step 3: Migrate global-read methods to AppConfig
|
||
|
||
These methods only read serialized config values and should live on `AppConfig`:
|
||
|
||
| Method | Current Signature | New Home |
|
||
|---|---|---|
|
||
| `vault_password_file` | `&self -> PathBuf` | `AppConfig` |
|
||
| `editor` | `&self -> Result<String>` | `AppConfig` |
|
||
| `sync_models_url` | `&self -> String` | `AppConfig` |
|
||
| `light_theme` | `&self -> bool` | `AppConfig` |
|
||
| `render_options` | `&self -> Result<RenderOptions>` | `AppConfig` |
|
||
| `print_markdown` | `&self, text -> Result<()>` | `AppConfig` |
|
||
| `rag_template` | `&self, embeddings, sources, text -> String` | `AppConfig` |
|
||
| `select_functions` | `&self, role -> Option<Vec<...>>` | `AppConfig` |
|
||
| `select_enabled_functions` | `&self, role -> Vec<...>` | `AppConfig` |
|
||
| `select_enabled_mcp_servers` | `&self, role -> Vec<...>` | `AppConfig` |
|
||
|
||
**Same pattern:** Add new methods on `AppConfig`, add `#[deprecated]` forwarding on `Config`, migrate callers, remove.
|
||
|
||
### Step 4: Migrate global-write methods
|
||
|
||
These modify serialized config settings (`.set` command, environment loading):
|
||
|
||
| Method | Notes |
|
||
|---|---|
|
||
| `set_wrap` | Modifies `self.wrap` |
|
||
| `update` | Generic key-value update of config settings |
|
||
| `load_envs` | Applies env var overrides |
|
||
| `load_functions` | Initializes function definitions |
|
||
| `load_mcp_servers` | Starts MCP servers |
|
||
| `setup_model` | Sets default model |
|
||
| `setup_document_loaders` | Sets default doc loaders |
|
||
| `setup_user_agent` | Sets user agent string |
|
||
|
||
The `load_*` / `setup_*` methods are initialization-only (called once in `Config::init`). They become part of `AppState` construction.
|
||
|
||
`update` and `set_wrap` are runtime mutations of global config. For the API world, these should require a config reload. For now, they can stay as methods that mutate `AppConfig` through interior mutability or require a mutable reference during REPL setup.
|
||
|
||
### Step 5: Migrate request-read methods to RequestContext
|
||
|
||
Pure reads of per-request state:
|
||
|
||
| Method | Notes |
|
||
|---|---|
|
||
| `state` | Returns flags for active role/session/agent/rag |
|
||
| `messages_file` | Path depends on active agent |
|
||
| `sessions_dir` | Path depends on active agent |
|
||
| `session_file` | Path depends on active agent |
|
||
| `rag_file` | Path depends on active agent |
|
||
| `info` | Reads current agent/session/role/rag |
|
||
| `role_info` | Reads current role |
|
||
| `session_info` | Reads current session |
|
||
| `agent_info` | Reads current agent |
|
||
| `agent_banner` | Reads current agent |
|
||
| `rag_info` | Reads current rag |
|
||
| `list_sessions` | Depends on sessions_dir (agent context) |
|
||
| `list_autoname_sessions` | Depends on sessions_dir |
|
||
| `is_compressing_session` | Reads session state |
|
||
| `role_like_mut` | Returns mutable ref to role-like |
|
||
|
||
### Step 6: Migrate request-write methods to RequestContext
|
||
|
||
Mutations of per-request state:
|
||
|
||
| Method | Notes |
|
||
|---|---|
|
||
| `use_prompt` | Sets temporary role |
|
||
| `use_role` / `use_role_obj` | Sets role on session or self |
|
||
| `exit_role` | Clears role |
|
||
| `edit_role` | Edits and re-applies role |
|
||
| `use_session` | Sets session |
|
||
| `exit_session` | Saves and clears session |
|
||
| `save_session` | Persists session |
|
||
| `empty_session` | Clears session messages |
|
||
| `set_save_session_this_time` | Session flag |
|
||
| `compress_session` / `maybe_compress_session` | Session compression |
|
||
| `autoname_session` / `maybe_autoname_session` | Session naming |
|
||
| `use_rag` / `exit_rag` / `edit_rag_docs` / `rebuild_rag` | RAG lifecycle |
|
||
| `use_agent` / `exit_agent` / `exit_agent_session` | Agent lifecycle |
|
||
| `apply_prelude` | Sets role/session from prelude config |
|
||
| `before_chat_completion` | Pre-LLM state updates |
|
||
| `after_chat_completion` | Post-LLM state updates |
|
||
| `discontinuous_last_message` | Message state |
|
||
| `init_agent_shared_variables` | Agent vars |
|
||
| `init_agent_session_variables` | Agent session vars |
|
||
|
||
### Step 6.5: Unify tool/MCP fields into `ToolScope` and agent fields into `AgentRuntime`
|
||
|
||
After Step 6, `RequestContext` has many flat fields that logically cluster into two sub-structs. This step collapses them and introduces three new services on `AppState`.
|
||
|
||
**New types:**
|
||
|
||
```rust
|
||
pub struct ToolScope {
|
||
pub functions: Functions,
|
||
pub mcp_runtime: McpRuntime,
|
||
pub tool_tracker: ToolCallTracker,
|
||
}
|
||
|
||
pub struct McpRuntime {
|
||
servers: HashMap<String, Arc<McpServerHandle>>,
|
||
}
|
||
|
||
pub struct AgentRuntime {
|
||
pub spec: AgentSpec,
|
||
pub rag: Option<Arc<Rag>>, // shared across siblings of same type
|
||
pub supervisor: Supervisor,
|
||
pub inbox: Arc<Inbox>,
|
||
pub escalation_queue: Arc<EscalationQueue>, // shared from root
|
||
pub todo_list: Option<TodoList>, // Some(...) only when auto_continue: true
|
||
pub self_agent_id: String,
|
||
pub parent_supervisor: Option<Arc<Supervisor>>,
|
||
pub current_depth: usize,
|
||
pub auto_continue_count: usize,
|
||
}
|
||
```
|
||
|
||
**New services on `AppState`:**
|
||
|
||
```rust
|
||
pub struct AppState {
|
||
pub config: Arc<AppConfig>,
|
||
pub vault: GlobalVault,
|
||
pub mcp_factory: Arc<McpFactory>,
|
||
pub rag_cache: Arc<RagCache>,
|
||
}
|
||
|
||
pub struct McpFactory {
|
||
active: Mutex<HashMap<McpServerKey, Weak<McpServerHandle>>>,
|
||
// idle pool + reaper added in Phase 5; Step 6.5 ships the no-pool version
|
||
}
|
||
|
||
impl McpFactory {
|
||
pub async fn acquire(&self, key: &McpServerKey) -> Result<Arc<McpServerHandle>>;
|
||
}
|
||
|
||
pub struct RagCache {
|
||
entries: RwLock<HashMap<RagKey, Weak<Rag>>>,
|
||
}
|
||
|
||
#[derive(Hash, Eq, PartialEq, Clone, Debug)]
|
||
pub enum RagKey {
|
||
Named(String), // standalone: rags/<name>.yaml
|
||
Agent(String), // agent-owned: agents/<name>/rag.yaml
|
||
}
|
||
|
||
impl RagCache {
|
||
pub async fn load(&self, key: &RagKey) -> Result<Option<Arc<Rag>>>;
|
||
pub fn invalidate(&self, key: &RagKey);
|
||
}
|
||
```
|
||
|
||
**`RequestContext` after collapse:**
|
||
|
||
```rust
|
||
pub struct RequestContext {
|
||
pub app: Arc<AppState>,
|
||
pub macro_flag: bool,
|
||
pub info_flag: bool,
|
||
pub working_mode: WorkingMode,
|
||
pub model: Model,
|
||
pub agent_variables: Option<AgentVariables>,
|
||
|
||
pub role: Option<Role>,
|
||
pub session: Option<Session>,
|
||
pub rag: Option<Arc<Rag>>, // session/standalone RAG, not agent RAG
|
||
pub agent: Option<Agent>,
|
||
|
||
pub last_message: Option<LastMessage>,
|
||
|
||
pub tool_scope: ToolScope, // replaces functions + tool_call_tracker + global mcp_registry
|
||
pub agent_runtime: Option<AgentRuntime>, // replaces supervisor + inbox + escalation_queue + todo + self_id + parent + depth; holds shared agent RAG
|
||
}
|
||
```
|
||
|
||
**What this step does:**
|
||
|
||
1. Implement `McpRuntime` and `ToolScope`.
|
||
2. Implement `McpFactory` — **no pool, no idle handling, no reaper.** `acquire()` checks `active` for an upgradable `Weak`, otherwise spawns fresh. `Drop` on `McpServerHandle` tears down the subprocess directly. Pooling lands in Phase 5.
|
||
3. Implement `RagCache` with `RagKey` enum, weak-ref sharing, and per-key serialization for concurrent first-load.
|
||
4. Implement `AgentRuntime` with the shape above. `todo_list` is `Option` — only allocated when `agent.spec.auto_continue == true`. `rag` is served from `RagCache` during activation via `RagKey::Agent(name)`.
|
||
5. Rewrite scope transitions (`use_role`, `use_session`, `use_agent`, `exit_*`, `Config::update`) to:
|
||
- Resolve the effective enabled-tool / enabled-MCP-server list using priority `Agent > Session > Role > Global`
|
||
- Build a fresh `McpRuntime` by calling `McpFactory::acquire()` for each required server key
|
||
- Construct a new `ToolScope` wrapping the runtime + resolved `Functions`
|
||
- Swap `ctx.tool_scope` atomically
|
||
6. `use_rag` (standalone / `.rag <name>` path) is rewritten to call `app.rag_cache.load(RagKey::Named(name))` and assign the result to `ctx.rag`. No role/session RAG changes because roles/sessions do not own RAG.
|
||
7. Agent activation additionally:
|
||
- Calls `app.rag_cache.load(RagKey::Agent(agent_name))` and stores the returned `Arc<Rag>` in the new `AgentRuntime.rag`
|
||
- Allocates `todo_list: Some(TodoList::default())` only when `auto_continue: true`; otherwise `None`
|
||
- Constructs the `AgentRuntime` and assigns it to `ctx.agent_runtime`
|
||
- **Preserves today's clobber behavior for standalone RAG:** does NOT save `ctx.rag` anywhere. When the agent exits, the user's previous `.rag <name>` selection is not restored (matches current behavior). Stacking / restoration is flagged as a Phase 2+ enhancement.
|
||
8. `exit_agent` drops `ctx.agent_runtime` (which drops the agent's `Arc<Rag>`; the cache entry becomes evictable if no other scope holds it) and rebuilds `ctx.tool_scope` from the now-topmost `RoleLike`.
|
||
9. Sub-agent spawning (in `function/supervisor.rs`) constructs a fresh `RequestContext` for the child from the shared `AppState`:
|
||
- Its own `ToolScope` via `McpFactory::acquire()` calls for the child agent's `mcp_servers`
|
||
- Its own `AgentRuntime` with:
|
||
- `rag` via `rag_cache.load(RagKey::Agent(child_agent_name))` — shared with parent/siblings of same type
|
||
- Fresh `Supervisor`, fresh `Inbox`, `current_depth = parent.depth + 1`
|
||
- `parent_supervisor = Some(parent.supervisor.clone())` (for messaging)
|
||
- `escalation_queue = parent.escalation_queue.clone()` — one queue, rooted at the human
|
||
- `todo_list` honoring the child's own `auto_continue` flag
|
||
10. Old `Agent::init` logic that mutates a global `McpRegistry` is removed — that's now `McpFactory::acquire()` producing scope-local handles.
|
||
11. `rebuild_rag` and `edit_rag_docs` are updated to determine the correct `RagKey` (check `ctx.agent_runtime` first — if present use `RagKey::Agent(spec.name)`, otherwise use the standalone name from `ctx.rag`'s origin) and call `rag_cache.invalidate(&key)` before reloading.
|
||
|
||
**What this step preserves:**
|
||
|
||
- **Diff-based reinit for REPL users** — when you `.exit role` from `[github, jira]` back to global `[github]`, the new `ToolScope` is built by calling `McpFactory::acquire("github")`. Without pooling (Phase 1), this respawns `github`. With pooling (Phase 5), `github`'s `Arc` is still held by no one, but the idle pool keeps it warm, so revival is instant. The Phase 1 version has a mild regression here that Phase 5 fixes.
|
||
- **Agent-vs-non-agent compatibility** — today's `Agent::init` reinits a global registry; after this step, agent activation replaces `ctx.tool_scope` with an agent-specific one, and `exit_agent` restores the pre-agent scope by rebuilding from the (now-active) role/session/global lists.
|
||
- **Todo semantics from the user's perspective** — today's behavior is "todos are available when `auto_continue: true`". After Step 6.5, it's still "todos are available when `auto_continue: true`" — the only difference is we skip the wasted `TodoList::default()` allocation for the other agents.
|
||
|
||
**Risk:** Medium–high. This is where the Phase 1 refactor stops being mechanical and starts having semantic implications. Five things to watch:
|
||
|
||
1. **Parent scope restoration on `exit_agent`.** Today, `exit_agent` tears down the agent's MCP set but leaves the registry in whatever state `reinit` put it — the parent's original MCP set is NOT restored. Users don't notice because the next scope activation (or REPL exit) reinits anyway. In the new design, `exit_agent` MUST rebuild the parent's `ToolScope` from the still-active role/session/global lists so the user sees the expected state. Test this carefully.
|
||
2. **`McpFactory` contention.** With many concurrent sub-agents (say, 4 siblings each needing different MCP sets), the factory's mutex could become a bottleneck during `acquire()`. Hold the lock only while touching `active`, never while awaiting subprocess spawn.
|
||
3. **`RagCache` concurrent first-load.** If two consumers request the same `RagKey` simultaneously and neither finds a cached entry, both will try to `Rag::load` from disk. Use per-key `tokio::sync::Mutex` or `OnceCell` to serialize the first load — the second caller blocks briefly and receives the shared Arc. This applies equally to standalone and agent RAGs.
|
||
4. **Weak ref staleness in `RagCache`.** The `Weak<Rag>` in the map might point to a dropped `Rag`. The `load()` path MUST attempt `Weak::upgrade()` before returning; if upgrade fails, treat it as a miss and reload.
|
||
5. **`rebuild_rag` / `edit_rag_docs` race.** If a user runs `.rag rebuild` while another scope holds the same `Arc<Rag>` (concurrent API session, running sub-agent, etc.), the cache invalidation must NOT yank the Arc out from under the active holder. The `Arc` keeps its reference alive — invalidation just ensures *future* loads read fresh. This is the correct behavior for both standalone and agent RAG; worth confirming in tests.
|
||
6. **Identifying the right `RagKey` during rebuild.** `rebuild_rag` today operates on `Config.rag` without knowing its origin. In the new model, the code needs to check `ctx.agent_runtime` first to determine if the active RAG is agent-owned (`RagKey::Agent`) or standalone (`RagKey::Named`). Get this wrong and you invalidate the wrong cache entry, silently breaking subsequent loads.
|
||
|
||
### Step 7: Tackle mixed methods (THE HARD PART)
|
||
|
||
These 17 methods conditionally read global config OR per-request state depending on what's active. They need to be split into explicit parameter passing.
|
||
|
||
| Method | Why it's mixed | Refactoring approach |
|
||
|---|---|---|
|
||
| `current_model` | Returns agent model, session model, role model, or global model | Take `(&AppConfig, &RequestContext) -> &Model` — check ctx first, fall back to app |
|
||
| `extract_role` | Builds role from session/agent/role or global settings | Take `(&AppConfig, &RequestContext) -> Role` |
|
||
| `sysinfo` | Reads global settings + current rag/session/agent | Take `(&AppConfig, &RequestContext) -> String` |
|
||
| `set_temperature` | Sets on role-like or global | Split: `ctx.set_temperature()` for role-like, `app.set_temperature()` for global |
|
||
| `set_top_p` | Same pattern as temperature | Same split |
|
||
| `set_enabled_tools` | Same pattern | Same split |
|
||
| `set_enabled_mcp_servers` | Same pattern | Same split |
|
||
| `set_save_session` | Sets on session or global | Same split |
|
||
| `set_compression_threshold` | Sets on session or global | Same split |
|
||
| `set_rag_reranker_model` | Sets on rag or global | Same split |
|
||
| `set_rag_top_k` | Sets on rag or global | Same split |
|
||
| `set_max_output_tokens` | Sets on role-like model or global model | Same split |
|
||
| `set_model` | Sets on role-like or global | Same split |
|
||
| `retrieve_role` | Loads role, merges with current model settings | Take `(&AppConfig, &RequestContext, name) -> Role` |
|
||
| `use_role_safely` | Takes GlobalConfig, does take/replace pattern | Refactor to `(&mut RequestContext, name)` |
|
||
| `use_session_safely` | Takes GlobalConfig, does take/replace pattern | Refactor to `(&mut RequestContext, name)` |
|
||
| `save_message` | Reads `save` flag (global) + writes to messages_file (agent-dependent path) | Take `(&AppConfig, &RequestContext, input, output)` |
|
||
| `render_prompt_left/right` | Reads prompt format (global) + current model/session/agent/role (request) | Take `(&AppConfig, &RequestContext) -> String` |
|
||
| `generate_prompt_context` | Same as prompt rendering | Take `(&AppConfig, &RequestContext) -> HashMap` |
|
||
| `repl_complete` | Reads both global config and request state for completions | Take `(&AppConfig, &RequestContext, cmd, args) -> Vec<...>` |
|
||
|
||
**Common pattern for `set_*` methods:** The current code does something like:
|
||
```rust
|
||
fn set_temperature(&mut self, value: Option<f64>) {
|
||
if let Some(role_like) = self.role_like_mut() {
|
||
role_like.set_temperature(value);
|
||
} else {
|
||
self.temperature = value;
|
||
}
|
||
}
|
||
```
|
||
|
||
This becomes:
|
||
```rust
|
||
// On RequestContext:
|
||
fn set_temperature(&mut self, value: Option<f64>, app_defaults: &AppConfig) {
|
||
if let Some(role_like) = self.role_like_mut() {
|
||
role_like.set_temperature(value);
|
||
}
|
||
// Global default mutation goes through a separate path if needed
|
||
}
|
||
```
|
||
|
||
### Step 8: The Caller Migration Epic (absorbed scope from Steps 6.5 and 7)
|
||
|
||
**Important:** the original plan described Step 8 as "rewrite main.rs and repl/mod.rs entry points." During implementation, Steps 6.5 and 7 deliberately deferred their semantic rewrites to Step 8 so the bridge pattern (add new methods alongside old, don't migrate callers yet) stayed consistent. As a result, Step 8 now absorbs:
|
||
|
||
- **Original Step 8 scope:** entry point rewrite (`main.rs`, `repl/mod.rs`)
|
||
- **From Step 6.5 deferrals:** `McpFactory::acquire()` implementation, scope transition rewrites (`use_role`, `use_session`, `use_agent`, `exit_agent`), RAG lifecycle via `RagCache` (`use_rag`, `edit_rag_docs`, `rebuild_rag`), session compression/autoname, `apply_prelude`, sub-agent spawning
|
||
- **From Step 7 deferrals:** `Model::retrieve_model` client module refactor, `retrieve_role`, `set_model`, `repl_complete`, `setup_model`, `update` dispatcher, `set_rag_reranker_model`, `set_rag_top_k`, `use_role_safely`/`use_session_safely` elimination, `use_prompt`, `edit_role`
|
||
|
||
This is a large amount of work. Step 8 is split into **8 sub-steps (8a–8h)** for clarity and reviewability. Each sub-step keeps the build green and can be completed as a standalone unit.
|
||
|
||
**Dependency graph between sub-steps:**
|
||
|
||
```
|
||
┌─────────┐
|
||
│ 8a │ client module refactor
|
||
│ (Model: │ (Model::retrieve_model, list_models,
|
||
│ &App- │ list_all_models! → &AppConfig)
|
||
│ Config) │
|
||
└────┬────┘
|
||
│ unblocks
|
||
▼
|
||
┌─────────┐
|
||
│ 8b │ remaining Step 7 deferrals
|
||
│ (Step 7 │ (retrieve_role, set_model, setup_model,
|
||
│ debt) │ use_prompt, edit_role, update, etc.)
|
||
└────┬────┘
|
||
│
|
||
┌──────────┐ │
|
||
│ 8c │ │
|
||
│(McpFac- │──┐ │
|
||
│ tory:: │ │ unblocks │
|
||
│acquire())│ │ │
|
||
└──────────┘ │ │
|
||
▼ │
|
||
┌─────────┐ │
|
||
│ 8d │ │
|
||
│ (scope │──┐ │
|
||
│ trans.) │ │ unblocks │
|
||
└─────────┘ │ │
|
||
▼ │
|
||
┌─────────┐ │
|
||
│ 8e │ │
|
||
│ (RAG + │──┐ │
|
||
│session) │ │ │
|
||
└─────────┘ │ │
|
||
▼ ▼
|
||
┌───────────────────┐
|
||
│ 8f + 8g │
|
||
│ caller migration │
|
||
│ (main.rs, REPL) │
|
||
└─────────┬─────────┘
|
||
▼
|
||
┌──────────┐
|
||
│ 8h │ remaining callsites
|
||
│ (sweep) │ (priority-ordered)
|
||
└──────────┘
|
||
```
|
||
|
||
---
|
||
|
||
#### Step 8a: Client module refactor — `Model::retrieve_model` takes `&AppConfig`
|
||
|
||
Target: remove the `&Config` dependency from the LLM client infrastructure so Step 8b's mixed-method migrations (`retrieve_role`, `set_model`, `repl_complete`, `setup_model`) can proceed.
|
||
|
||
**Files touched:**
|
||
- `src/client/model.rs` — `Model::retrieve_model(config: &Config, ...)` → `Model::retrieve_model(config: &AppConfig, ...)`
|
||
- `src/client/macros.rs` — `list_all_models!` macro takes `&AppConfig` instead of `&Config`
|
||
- `src/client/*.rs` — `list_models`, helper functions updated to take `&AppConfig`
|
||
- Any callsite in `src/config/`, `src/main.rs`, `src/repl/`, etc. that calls these client functions — updated to pass `&config.app_config_snapshot()` or equivalent during the bridge window
|
||
|
||
**Bridge strategy:** add a helper `Config::app_config_snapshot(&self) -> AppConfig` that clones the serialized fields into an `AppConfig`. Callsites that currently pass `&*config.read()` pass `&config.read().app_config_snapshot()` instead. This is slightly wasteful (clones ~40 fields per call) but keeps the bridge window working without a mass caller rewrite. Step 8f/8g will eliminate the clones when callers hold `Arc<AppState>` directly.
|
||
|
||
**Verification:** full build green. All existing tests pass. CLI/REPL manual smoke test: `loki --model openai:gpt-4o "hello"` still works.
|
||
|
||
**Risk:** Low. Mechanical refactor. The bridge helper absorbs the signature change cost.
|
||
|
||
---
|
||
|
||
#### Step 8b: Finish Step 7's deferred mixed-method migrations
|
||
|
||
With Step 8a done, the methods that transitively depended on `Model::retrieve_model(&Config)` can now migrate to `RequestContext` with `&AppConfig` parameters.
|
||
|
||
**Methods migrated to `RequestContext`:**
|
||
- `retrieve_role(&self, app: &AppConfig, name: &str) -> Result<Role>`
|
||
- `set_model_on_role_like(&mut self, app: &AppConfig, model_id: &str) -> Result<bool>` (paired with `AppConfig::set_model_default`)
|
||
- `repl_complete(&self, app: &AppConfig, cmd: &str, args: &[&str]) -> Vec<(String, Option<String>)>`
|
||
- `setup_model(&mut self, app: &AppConfig) -> Result<()>` — actually, `setup_model` writes to `self.model_id` (serialized) AND `self.model` (runtime). The split: `AppConfig::ensure_default_model_id()` picks the first available model and updates `self.model_id`; `RequestContext::reload_current_model(&AppConfig)` refreshes `ctx.model` from the app config's id.
|
||
- `use_prompt(&mut self, app: &AppConfig, prompt: &str) -> Result<()>` — trivial wrapper around `extract_role` (already done) + `use_role_obj` (Step 6)
|
||
- `edit_role(&mut self, app: &AppConfig, abort_signal: AbortSignal) -> Result<()>` — calls `app.editor()`, `upsert_role`, `use_role` (still deferred to 8d)
|
||
|
||
**RAG-related deferrals:**
|
||
- `set_rag_reranker_model` and `set_rag_top_k` get split: the runtime branch (update the active `Rag`) becomes a `RequestContext` method taking `Arc<Rag>` mutation, and the global branch becomes `AppConfig::set_rag_reranker_model_default` / `AppConfig::set_rag_top_k_default`.
|
||
|
||
**`update` dispatcher:** Once all the individual `set_*` methods exist on both types, `update` migrates to `RequestContext::update(&mut self, app: &mut AppConfig, data: &str) -> Result<()>`. The dispatcher's body becomes a match that calls the appropriate split pair for each key.
|
||
|
||
**`use_role_safely` / `use_session_safely`:** Still not eliminated in 8b — they're wrappers around the still-`Config`-based `use_role` and `use_session`. Eliminated in 8f/8g when callers switch to `&mut RequestContext`.
|
||
|
||
**Verification:** full build green. All tests pass. Smoke test: `.set temperature 0.7`, `.set enabled_tools fs`, `.model openai:gpt-4o` all work in REPL.
|
||
|
||
**Risk:** Low. Same bridge pattern, now unblocked by 8a.
|
||
|
||
---
|
||
|
||
#### Step 8c: Extract `McpFactory::acquire()` from `McpRegistry::init_server`
|
||
|
||
Target: give `McpFactory` a working `acquire()` method so Step 8d can build real `ToolScope` instances.
|
||
|
||
**Files touched:**
|
||
- `src/mcp/mod.rs` — extract the MCP subprocess spawn + rmcp handshake logic (currently inside `McpRegistry::init_server`, ~60 lines) into a standalone function:
|
||
```rust
|
||
pub(crate) async fn spawn_mcp_server(
|
||
spec: &McpServer,
|
||
log_path: Option<&Path>,
|
||
abort_signal: &AbortSignal,
|
||
) -> Result<ConnectedServer>
|
||
```
|
||
`McpRegistry::init_server` then calls this helper and does its own bookkeeping. Backward-compatible for bridge callers.
|
||
- `src/config/mcp_factory.rs` — implement `McpFactory::acquire(spec: &McpServer, log_path, abort_signal) -> Result<Arc<ConnectedServer>>`:
|
||
1. Build an `McpServerKey` from the spec
|
||
2. Try `self.try_get_active(&key)` → share if upgraded
|
||
3. Otherwise call `spawn_mcp_server(spec, ...).await` → wrap in `Arc` → `self.insert_active(key, &arc)` → return
|
||
- Write a couple of integration tests that exercise the factory's sharing behavior with a mock server spec (or document why a real integration test needs Phase 5's pooling work)
|
||
|
||
**What this step does NOT do:** no caller migration, no `ToolScope` construction, no changes to `McpRegistry::reinit`. Step 8d does those.
|
||
|
||
**Verification:** new unit tests pass. Existing tests pass. `McpRegistry` still works for all current callers.
|
||
|
||
**Risk:** Medium. The spawn logic is intricate (child process + stdio handshake + error recovery). Extracting without a behavior change requires careful diff review.
|
||
|
||
---
|
||
|
||
#### Step 8d: Scope transition rewrites — `use_role`, `use_session`, `use_agent`, `exit_agent`
|
||
|
||
Target: build real `ToolScope` instances via `McpFactory` when scopes change. This is where Step 6.5's scaffolding stops being scaffolding.
|
||
|
||
**New methods on `RequestContext`:**
|
||
- `use_role(&mut self, app: &AppConfig, name: &str, abort_signal: AbortSignal) -> Result<()>`:
|
||
1. Call `self.retrieve_role(app, name)?` (from 8b)
|
||
2. Resolve the role's `enabled_mcp_servers` list
|
||
3. Build a fresh `ToolScope` by calling `app.mcp_factory.acquire(spec, ...)` for each required server
|
||
4. Populate `ctx.tool_scope.functions` with the role's effective function list via `select_functions(app, &role)`
|
||
5. Swap `ctx.tool_scope` atomically
|
||
6. Call `self.use_role_obj(role)` (from Step 6)
|
||
- `use_session(&mut self, app: &AppConfig, session_name: Option<&str>, abort_signal) -> Result<()>` — same pattern, with session-specific handling for `agent_session_variables`
|
||
- `use_agent(&mut self, app: &AppConfig, agent_name: &str, session_name: Option<&str>, abort_signal) -> Result<()>` — builds an `AgentRuntime` (Step 6.5 scaffolding), populates `ctx.agent_runtime`, activates the optional inner session
|
||
- `exit_agent(&mut self, app: &AppConfig) -> Result<()>` — drops `ctx.agent_runtime`, rebuilds `ctx.tool_scope` from the now-topmost RoleLike (role/session/global), cancels the supervisor, clears RAG if it came from the agent
|
||
|
||
**Key invariant: parent scope restoration on `exit_agent`.** Today's `Config::exit_agent` leaves the `McpRegistry` in whatever state the agent left it. The new `exit_agent` explicitly rebuilds `ctx.tool_scope` from the current role/session/global enabled-server lists so the user sees the expected state after exiting an agent. This is a semantic improvement over today's behavior (which technically has a latent bug that nobody notices because the next scope activation fixes it).
|
||
|
||
**What this step does NOT do:** no caller migration. `Config::use_role`, `Config::use_session`, etc. are still on `Config` and still work for existing callers. The `_safely` wrappers are still around.
|
||
|
||
**Verification:** new `RequestContext::use_role` etc. have unit tests. Full build green. Existing tests pass. No runtime behavior change because nothing calls the new methods yet.
|
||
|
||
**Risk:** Medium–high. This is the first time `McpFactory::acquire()` is exercised outside unit tests. Specifically watch:
|
||
- **`McpFactory` mutex contention** — hold the `active` lock only during HashMap mutation, never across subprocess spawn or `await`
|
||
- **Parent scope restoration correctness** — write a targeted test that activates an agent with `[github]`, exits, activates a role with `[jira]`, and verifies the tool scope has only `jira` (not `github` leftover)
|
||
|
||
---
|
||
|
||
#### Step 8e: RAG lifecycle + session compression + `apply_prelude`
|
||
|
||
Target: migrate the Category C deferrals from Step 6 (session/RAG lifecycle methods that currently take `&GlobalConfig`).
|
||
|
||
**New methods on `RequestContext`:**
|
||
- `use_rag(&mut self, app: &AppConfig, name: Option<&str>, abort_signal) -> Result<()>` — routes through `app.rag_cache.load(RagKey::Named(name))`
|
||
- `edit_rag_docs(&mut self, app: &AppConfig, abort_signal) -> Result<()>` — determines the `RagKey` (Agent or Named) from `ctx.agent_runtime` / `ctx.rag` origin, calls `app.rag_cache.invalidate(&key)`, reloads
|
||
- `rebuild_rag(&mut self, app: &AppConfig, abort_signal) -> Result<()>` — same pattern as `edit_rag_docs`
|
||
- `compress_session(&mut self, app: &AppConfig) -> Result<()>` — reads `app.summarization_prompt`, `app.summary_context_prompt`, mutates `ctx.session`. Async, does an LLM call via an existing `Input::from_str` pattern.
|
||
- `maybe_compress_session(&mut self, app: &AppConfig) -> bool` — checks `ctx.session.needs_compression(app.compression_threshold)`, triggers compression if so. Returns whether compression was triggered; caller decides whether to spawn a background task (the task spawning moves to the caller's responsibility, not the method's).
|
||
- `autoname_session(&mut self, app: &AppConfig) -> Result<()>` — same pattern, uses `CREATE_TITLE_ROLE` and `Input::from_str`
|
||
- `maybe_autoname_session(&mut self, app: &AppConfig) -> bool` — same return-bool pattern
|
||
- `apply_prelude(&mut self, app: &AppConfig, abort_signal) -> Result<()>` — parses `app.repl_prelude` / `app.cmd_prelude`, calls the new `self.use_role()` / `self.use_session()` from 8d
|
||
|
||
**The `GlobalConfig`-taking static methods go away.** Today's code uses the pattern `Config::maybe_compress_session(config: GlobalConfig)` which takes an owned `Arc<RwLock<Config>>` and spawns a background task. After 8e, the new `RequestContext::maybe_compress_session` returns a bool; callers that want async compression spawn the task themselves with their `RequestContext` context. This is simpler and more explicit.
|
||
|
||
**Verification:** new methods have unit tests where feasible. Full build green. `compress_session` and `autoname_session` are tricky to unit-test because they do LLM calls; mock the LLM or skip the full path in tests.
|
||
|
||
**Risk:** Medium. The session compression flow is the most behavior-sensitive — getting the semantics wrong here results in lost session history. Write a targeted integration test that feeds 10+ user messages into a session, triggers compression, and verifies the session's summary is preserved.
|
||
|
||
---
|
||
|
||
#### Step 8f: Entry point rewrite — `main.rs`
|
||
|
||
Target: rewrite `main.rs` to construct `AppState` + `RequestContext` explicitly instead of using `GlobalConfig`.
|
||
|
||
**Specific changes:**
|
||
- `Config::init()` → `AppState::init()` which:
|
||
1. Loads `config.yaml` into `AppConfig`
|
||
2. Applies environment variable overrides (calls `AppConfig::load_envs` from Step 4)
|
||
3. Calls `AppConfig::setup_document_loaders` / `AppConfig::setup_user_agent` (Step 4)
|
||
4. Constructs the `Vault`, `McpFactory`, `RagCache`
|
||
5. Returns `Arc<AppState>`
|
||
- `main::run()` constructs a `RequestContext` from the `AppState` and threads it through to subcommands
|
||
- `main::start_directive(ctx: &mut RequestContext, ...)` — signature change
|
||
- `main::create_input(ctx: &RequestContext, ...)` — signature change
|
||
- `main::shell_execute(ctx: &mut RequestContext, ...)` — signature change
|
||
- All 18 `main.rs` callsites updated
|
||
|
||
**`load_functions` and `load_mcp_servers`:** These are initialization-time methods that populate `ctx.tool_scope.functions` and `ctx.tool_scope.mcp_runtime`. They move from `Config` to a new `RequestContext::bootstrap_tools(&mut self, app: &AppConfig, abort_signal) -> Result<()>` that:
|
||
1. Initializes `Functions` via `Functions::init(visible_tools)` (existing code)
|
||
2. Resolves the initial enabled-MCP-server list from `app.enabled_mcp_servers`
|
||
3. Calls `app.mcp_factory.acquire()` for each
|
||
4. Assigns the result to `ctx.tool_scope`
|
||
|
||
This replaces the `Config::load_functions` + `Config::load_mcp_servers` call sequence in today's `main.rs`.
|
||
|
||
**Verification:** CLI smoke tests from the original plan's Step 8 verification checklist. Specifically:
|
||
- `loki "hello"` — plain prompt
|
||
- `loki --role explain "what is TCP"` — role activation
|
||
- `loki --session my-project "..."` — session
|
||
- `loki --agent sisyphus "..."` — agent activation
|
||
- `loki --info` — sysinfo output
|
||
|
||
Each should produce output matching the pre-Step-8 behavior exactly.
|
||
|
||
**Risk:** High. `main.rs` is the primary entry point; any regression here is user-visible. Write smoke tests that compare CLI output byte-for-byte with a recorded baseline.
|
||
|
||
---
|
||
|
||
#### Step 8g: REPL rewrite — `repl/mod.rs`
|
||
|
||
Target: rewrite `repl/mod.rs` to use `&mut RequestContext` instead of `GlobalConfig`.
|
||
|
||
**Specific changes:**
|
||
- `Repl` struct: `config: GlobalConfig` → `ctx: RequestContext` (long-lived, mutable across turns)
|
||
- `run_repl_command(ctx: &mut RequestContext, ...)` — signature change
|
||
- `ask(ctx: &mut RequestContext, ...)` — signature change
|
||
- Every dot-command handler updated. Dot-commands that take the `GlobalConfig` pattern (like the `_safely` wrappers) are **eliminated** — they just call `ctx.use_role(...)` directly.
|
||
- All 39 command handlers migrated
|
||
- All 12 `repl/mod.rs` internal callsites updated
|
||
|
||
**`use_role_safely` / `use_session_safely` elimination:** these wrappers exist only because `Config::use_role` is `&mut self` and the REPL holds `Arc<RwLock<Config>>`. After Step 8g, the REPL holds `RequestContext` directly (no lock), so the wrappers are no longer needed and get deleted.
|
||
|
||
**Verification:** REPL smoke tests matching the pre-Step-8 behavior. Specifically:
|
||
- Start REPL, issue a prompt → should see same output
|
||
- `.role explain`, `.session my-session`, `.agent sisyphus`, `.exit agent` — should all work identically
|
||
- `.set temperature 0.7` then `.info` — should show updated temperature
|
||
- Ctrl-C during an LLM call — should cleanly abort
|
||
- `.macro run-tests` — should execute without errors
|
||
|
||
**Risk:** High. Same reason as 8f — this is a user-visible entry point. Test every dot-command.
|
||
|
||
---
|
||
|
||
#### Step 8h: Remaining callsite sweep
|
||
|
||
Target: migrate the remaining modules in priority order (lowest callsite count first, keeping the build green after each module):
|
||
|
||
| Priority | Module | Callsites | Notes |
|
||
|---|---|---|---|
|
||
| 1 | `render/mod.rs` | 1 | `render_stream` just reads config — trivial |
|
||
| 2 | `repl/completer.rs` | 1 | Just reads for completions |
|
||
| 3 | `repl/prompt.rs` | 1 | Just reads for prompt rendering |
|
||
| 4 | `function/user_interaction.rs` | 1 | Just reads for user prompts |
|
||
| 5 | `function/mod.rs` | 2 | `eval_tool_calls` reads config |
|
||
| 6 | `config/macros.rs` | 3 | `macro_execute` reads and writes |
|
||
| 7 | `function/todo.rs` | 4 | Todo handlers read/write agent state |
|
||
| 8 | `config/input.rs` | 6 | Input creation — reads config |
|
||
| 9 | `rag/mod.rs` | 6 | RAG init/search |
|
||
| 10 | `function/supervisor.rs` | 8 | Sub-agent spawning — complex |
|
||
| 11 | `config/agent.rs` | 12 | Agent init — complex, many mixed concerns |
|
||
|
||
**Sub-agent spawning** (`function/supervisor.rs`) is the most complex item in the sweep. Each child agent gets a fresh `RequestContext` forked from the parent's `Arc<AppState>`:
|
||
- Own `ToolScope` built by calling `app.mcp_factory.acquire()` for the child's `mcp_servers` list
|
||
- Own `AgentRuntime` with fresh supervisor, fresh inbox, `current_depth = parent.depth + 1`
|
||
- `parent_supervisor = Some(parent.agent_runtime.supervisor.clone())` — weakly linked to parent for messaging
|
||
- `escalation_queue = parent.agent_runtime.escalation_queue.clone()` — `Arc`-shared from root
|
||
- RAG served via `app.rag_cache.load(RagKey::Agent(child_name))` — shared with any sibling of the same type
|
||
|
||
`config/agent.rs` — `Agent::init` is currently tightly coupled to `Config`. It needs to be rewritten to take `&AppState` + `&mut RequestContext`. Some of its complexity (MCP server startup, RAG loading) moves into `RequestContext::use_agent` from Step 8d; `Agent::init` becomes just the spec-loading portion.
|
||
|
||
**Verification:** after each module migrates, run full `cargo check` + `cargo test`. After all modules migrate, run the full smoke test suite from 8f and 8g.
|
||
|
||
**Risk:** Medium. The sub-agent spawning and `config/agent.rs` work is complex, but the bridge pattern means we can take each module independently.
|
||
|
||
---
|
||
|
||
### Step 9: Remove the Bridge
|
||
|
||
After Step 8h, no caller references `GlobalConfig` or calls `Config`-based methods that have `RequestContext` / `AppConfig` equivalents. Step 9 is the cleanup:
|
||
|
||
1. Delete `src/config/bridge.rs` (the conversion methods added in Step 1)
|
||
2. Delete the `#[allow(dead_code)]` attributes from `AppConfig` impl blocks (now that callers use them)
|
||
3. Delete the `#[allow(dead_code)]` attributes from `RequestContext` impl blocks
|
||
4. Remove the flat runtime fields from `RequestContext` that have been superseded by `tool_scope` and `agent_runtime` (i.e., delete `functions`, `tool_call_tracker`, `supervisor`, `parent_supervisor`, `self_agent_id`, `current_depth`, `inbox`, `root_escalation_queue` from `RequestContext`; they now live inside `ToolScope` and `AgentRuntime`)
|
||
5. Run the full test suite
|
||
|
||
This step is mostly mechanical deletion. The one care-ful part is removing the flat fields — make sure no remaining code path still reads them. `cargo check` will catch any stragglers.
|
||
|
||
### Step 10: Remove the old Config struct and GlobalConfig type alias
|
||
|
||
Once Step 9 is done and the tree is clean:
|
||
|
||
1. Delete all Step 2-7 method definitions on `Config` (the ones that got duplicated to `paths` / `AppConfig` / `RequestContext`)
|
||
2. Delete the `#[serde(skip)]` runtime fields on `Config` (they're all on `RequestContext` now)
|
||
3. At this point `Config` should be nearly empty — possibly just the serialized fields
|
||
4. Delete `Config` entirely (or rename it to `RawConfig` if it's still useful as a serde DTO, though `AppConfig` already plays that role)
|
||
5. Delete the `pub type GlobalConfig = Arc<RwLock<Config>>` type alias
|
||
6. Run `cargo check`, `cargo test`, `cargo clippy` — all clean
|
||
7. Run the full manual smoke test suite one more time
|
||
|
||
Phase 1 complete.
|
||
|
||
---
|
||
|
||
## Callsite Migration Summary
|
||
|
||
| Module | Functions to Migrate | Handled In |
|
||
|---|---|---|
|
||
| `config/mod.rs` | 120 methods (30 static, 10 global-read, 8 global-write, 35 request-read/write, 17 mixed) | Steps 2-7 (mechanical duplication), Step 10 (deletion) |
|
||
| `client/` macros and `model.rs` | `Model::retrieve_model`, `list_all_models!`, `list_models` | Step 8a |
|
||
| `main.rs` | `run`, `start_directive`, `shell_execute`, `create_input`, `apply_prelude_safely` | Step 8f |
|
||
| `repl/mod.rs` | `run_repl_command`, `ask`, plus 39 command handlers | Step 8g |
|
||
| `config/agent.rs` | `Agent::init`, agent lifecycle methods | Step 8h (partial) + Step 8d (scope transitions) |
|
||
| `function/supervisor.rs` | Sub-agent spawning, task management | Step 8h |
|
||
| `config/input.rs` | `Input::from_str`, `from_files`, `from_files_with_spinner` | Step 8h |
|
||
| `rag/mod.rs` | RAG init, load, search | Step 8e (lifecycle) + Step 8h (remaining) |
|
||
| `mcp/mod.rs` | `McpRegistry::init_server` spawn logic extraction | Step 8c |
|
||
| `function/mod.rs` | `eval_tool_calls` | Step 8h |
|
||
| `function/todo.rs` | Todo handlers | Step 8h |
|
||
| `function/user_interaction.rs` | User prompt handler | Step 8h |
|
||
| `render/mod.rs` | `render_stream` | Step 8h |
|
||
| `repl/completer.rs` | Completion logic | Step 8h |
|
||
| `repl/prompt.rs` | Prompt rendering | Step 8h |
|
||
| `config/macros.rs` | `macro_execute` | Step 8h |
|
||
|
||
### Step 8 effort estimates
|
||
|
||
| Sub-step | Effort | Risk |
|
||
|---|---|---|
|
||
| 8a — client module refactor | 0.5–1 day | Low |
|
||
| 8b — Step 7 deferrals | 0.5–1 day | Low |
|
||
| 8c — `McpFactory::acquire()` extraction | 1 day | Medium |
|
||
| 8d — scope transition rewrites | 1–2 days | Medium–high |
|
||
| 8e — RAG + session lifecycle migration | 1–2 days | Medium |
|
||
| 8f — `main.rs` rewrite | 1 day | High |
|
||
| 8g — `repl/mod.rs` rewrite | 1–2 days | High |
|
||
| 8h — remaining callsite sweep | 1–2 days | Medium |
|
||
|
||
**Total estimated Step 8 effort: ~7–12 days.** The "total Phase 1 effort" from the plan header needs to be updated once Step 8 finishes.
|
||
|
||
---
|
||
|
||
## Verification Checkpoints
|
||
|
||
After each step, verify:
|
||
|
||
1. **`cargo check`** — no compilation errors
|
||
2. **`cargo test`** — all existing tests pass
|
||
3. **Manual smoke test** — CLI one-shot prompt works, REPL starts and processes a prompt
|
||
4. **No behavior changes** — identical output for identical inputs
|
||
|
||
## Risk Factors
|
||
|
||
### Phase-wide risks
|
||
|
||
| Risk | Severity | Mitigation |
|
||
|---|---|---|
|
||
| Bridge-window duplication drift — bug fixed in `Config::X` but not `RequestContext::X` or vice versa | Medium | Keep the bridge window as short as possible. Step 8 should finish within 2 weeks of Step 7 ideally. Any bug fix during Steps 8a-8h must be applied to both places if the method is still duplicated. |
|
||
| Sub-agent spawning semantics change subtly | High | Cross-agent MCP trampling is a latent bug today that Step 8d/8h fixes. Write targeted integration tests for the sub-agent spawning path before and after Step 8h to verify semantics match (or improve intentionally). |
|
||
| Long-running Phase 1 blocking Phase 2+ work | Medium | Phase 2 (Engine + Emitter) can start prep work in parallel with Step 8h — the final callsite sweep doesn't block the new Engine design. |
|
||
|
||
### Step 8 sub-step risks
|
||
|
||
| Sub-step | Risk | Severity | Mitigation |
|
||
|---|---|---|---|
|
||
| 8a | Client macro refactor breaks LLM provider integration | Low | All LLM providers use the same `Model::retrieve_model` entry point. Test with at least 2 providers (openai + another) before declaring 8a done. |
|
||
| 8b | `update` dispatcher has ~15 cases — easy to miss one | Low | Enumerate every `.set` key handled today; check each is in the new dispatcher. |
|
||
| 8c | Extracting `spawn_mcp_server` introduces behavior differences (e.g., error handling, abort signal propagation) | Medium | Do a line-by-line diff review. Write a test that kills an in-flight spawn via the abort signal. |
|
||
| 8d | `McpFactory` mutex contention under parallel sub-agent spawning | Medium | Hold the `active` lock only during HashMap operations, never across `await`. Benchmark with 4 concurrent scope transitions before declaring 8d done. |
|
||
| 8d | Parent scope restoration on `exit_agent` differs from today's implicit behavior | High | Write a targeted test: activate global→role(jira)→agent(github,slack)→exit_agent. Verify scope is role(jira), not agent's (github,slack) or stale. |
|
||
| 8e | Session compression loses messages when triggered mid-request | High | Integration test: feed 10+ user messages, compress, verify summary preserves all user intent. Also test concurrent compression (REPL background task + foreground turn). |
|
||
| 8e | `rebuild_rag` / `edit_rag_docs` pick the wrong `RagKey` variant | Medium | Test both paths explicitly: agent-scoped rebuild and standalone rebuild. Assert the right cache entry is invalidated. |
|
||
| 8f | CLI output bytes differ from pre-refactor baseline | High | Record baseline CLI outputs for 10 common invocations. After 8f, diff byte-for-byte. Any difference is a regression unless explicitly justified. |
|
||
| 8g | REPL dot-command behavior regresses silently | High | Test every dot-command end-to-end: `.role`, `.session`, `.agent`, `.rag`, `.set`, `.info`, `.exit *`, `.compress session`, etc. |
|
||
| 8h | Sub-agent spawning in `function/supervisor.rs` shares state incorrectly between parent and child | High | Integration test: parent activates agent A (github), spawns child B (jira), verify B's tool scope has only jira and parent's has only github. Each parallel child has independent tool scopes. |
|
||
| 8h | `Agent::init` refactor drops initialization logic | Medium | `Agent::init` is ~100 lines today. Diff the old vs new init paths line-by-line. |
|
||
|
||
### Legacy risks (resolved during the refactor)
|
||
|
||
These risks from the original plan have been addressed by the step-by-step scaffolding approach:
|
||
|
||
| Original risk | How it was resolved |
|
||
|---|---|
|
||
| `use_role_safely` / `use_session_safely` use take/replace pattern | Eliminated entirely in Step 8g — REPL holds `&mut RequestContext` directly, no lock take/replace needed |
|
||
| `Agent::init` creates MCP servers, functions, RAG on Config | Resolved in Step 8d + Step 8h — MCP via `McpFactory::acquire()`, RAG via `RagCache`, functions via `RequestContext::bootstrap_tools` |
|
||
| Sub-agent spawning clones Config | Resolved in Step 8h — children get fresh `RequestContext` forked from `Arc<AppState>` |
|
||
| Input holds `GlobalConfig` clone | Resolved in Step 8f — `Input` now holds references to the context it needs from `RequestContext`, not an owned clone |
|
||
| Concurrent REPL operations spawn tasks with `GlobalConfig` clone | Resolved in Step 8e — task spawning moves to the caller's responsibility with explicit `RequestContext` context |
|
||
|
||
## What This Phase Does NOT Do
|
||
|
||
- No REST API server code
|
||
- No Engine::run() unification (that's Phase 2)
|
||
- No Emitter trait (that's Phase 2)
|
||
- No SessionStore abstraction (that's Phase 3)
|
||
- No UUID-based sessions (that's Phase 3)
|
||
- No agent isolation refactoring (that's Phase 5)
|
||
- No new dependencies added
|
||
|
||
The sole goal is: **split Config into immutable global + mutable per-request, with identical external behavior.**
|