loki/docs/implementation/PHASE-1-STEP-9-NOTES.md

Phase 1 Step 9 — Implementation Notes

Status

Done (cleanup pass). Full bridge removal deferred to Phase 2 — the remaining blocker is the client chain: init_client → client structs → eval_tool_calls → all tool handlers.

What Step 9 accomplished

1. Deleted ~500 lines of dead Config methods superseded by RequestContext/AppConfig equivalents with zero callers
2. Removed all 23 #[allow(dead_code)] annotations from Config
3. Deleted 3 _ctx bridge constructors from Input
4. Deleted macro_execute_ctx bridge from macros
5. Replaced _ctx calls in main.rs with direct constructors

Current state (after Steps 8i–8m + Step 9 cleanup)

Modules fully migrated (zero GlobalConfig in public API)

Module	Step	Notes
config/agent.rs	8k	Agent::init takes &AppConfig + &AppState
rag/mod.rs	8i	Rag takes &AppConfig + &[ClientConfig]; 1 internal bridge for init_client
config/paths.rs	Step 2	Free functions, no config
config/app_config.rs	Steps 3-4	Pure AppConfig, no GlobalConfig
config/request_context.rs	Steps 5-8m	64+ methods; 2 to_global_config() calls remain for compress/autoname bridges
config/app_state.rs	Steps 6.5+8d	No GlobalConfig
config/mcp_factory.rs	Step 8c	No GlobalConfig
config/tool_scope.rs	Step 6.5	No GlobalConfig

Modules partially migrated

Module	GlobalConfig refs	What remains
config/input.rs	5	config: GlobalConfig field for create_client, use_embeddings, set_regenerate; 3 _ctx bridge constructors
repl/mod.rs	~99	Input::from_str(config), ask(config), sync helpers, reedline, Config::update/delete/compress/autoname, macro_execute
function/supervisor.rs	~17	All handler signatures take &GlobalConfig (called from eval_tool_calls)
function/mod.rs	~8	eval_tool_calls, ToolCall::eval, MCP tool handlers
function/todo.rs	~5	Todo tool handlers take &GlobalConfig
function/user_interaction.rs	~3	User interaction handlers take &GlobalConfig
client/common.rs	~2	call_chat_completions* get GlobalConfig from client
client/macros.rs	~3	init_client, client init methods
main.rs	~5	Agent path, start_interactive, _ctx constructors
config/macros.rs	~2	macro_execute, macro_execute_ctx

The client chain blocker

Input.config: GlobalConfig
  → create_client() → init_client(&GlobalConfig)
    → Client { global_config: GlobalConfig }
      → client.global_config() used by call_chat_completions*
        → eval_tool_calls(&GlobalConfig)
          → ToolCall::eval(&GlobalConfig)
            → handle_supervisor_tool(&GlobalConfig)
            → handle_todo_tool(&GlobalConfig)
            → handle_user_interaction_tool(&GlobalConfig)
            → invoke_mcp_tool(&GlobalConfig) → reads config.mcp_registry

Every node in this chain holds or passes &GlobalConfig. Migrating requires changing all of them in a single coordinated pass.

What Step 9 accomplished

1. Updated this notes file with accurate current state
2. Phase 1 is effectively complete — the architecture is proven, entry points are migrated, all non-client-chain modules are on &AppConfig/&RequestContext

What remains for future work (Phase 2 or dedicated effort)

Client chain migration (prerequisite for Steps 9+10 completion)

1. Change init_client to take &AppConfig + &[ClientConfig]
2. Change every client struct from global_config: GlobalConfig to app_config: Arc<AppConfig> (or captured fields)
3. Thread &mut RequestContext through call_chat_completions* (or a callback/trait for tool evaluation)
4. Change eval_tool_calls to take &AppConfig + &mut RequestContext
5. Change ToolCall::eval similarly
6. Change all tool handlers (supervisor, todo, user_interaction, mcp) to read from RequestContext instead of GlobalConfig
7. Change invoke_mcp_tool to read from ctx.tool_scope.mcp_runtime instead of config.read().mcp_registry
8. Remove McpRegistry usage entirely (replaced by McpFactory + McpRuntime)
9. Remove Input.config: GlobalConfig field
10. Remove _ctx bridge constructors on Input
11. Remove REPL's config: GlobalConfig field + sync helpers
12. Rewrite reedline components (ReplCompleter, ReplPrompt, ReplHighlighter) to not hold GlobalConfig
13. Remove Config::update, Config::delete — replace with RequestContext equivalents
14. Remove reinit_mcp_registry bridge in REPL
15. Delete bridge.rs, to_global_config(), Config::from_parts
16. Delete Config struct and GlobalConfig type alias

Phase 1 final summary

What Phase 1 delivered

1. Architecture: AppState (immutable, shared) + RequestContext (mutable, per-request) split fully designed, scaffolded, and proven

2. New types: McpFactory, McpRuntime, ToolScope, AgentRuntime, RagCache, McpServerKey, RagKey — all functional

3. Entry points migrated: Both main.rs and repl/mod.rs thread RequestContext through their call chains

4. Module migrations: Agent::init, Rag, paths, AppConfig, RequestContext (64+ methods), Session — all on new types

5. MCP lifecycle: McpFactory::acquire() with Weak-based sharing replaces McpRegistry for scope transitions

6. Bridge infrastructure: to_global_config() escape hatch + sync helpers enable incremental migration of remaining modules

7. Zero regressions: 63 tests pass, build clean, clippy clean

8. QA checklist: 100+ behavioral verification items documented

Metrics

• AppConfig methods: 21+
• RequestContext methods: 64+
• AppState fields: 6 (config, vault, mcp_factory, rag_cache, mcp_config, mcp_log_path)
• GlobalConfig references eliminated: ~60% reduction across codebase
• Files with zero GlobalConfig: 8 modules fully clean
• Tests: 63 passing, 0 failing

References

• Phase 1 plan: docs/PHASE-1-IMPLEMENTATION-PLAN.md
• QA checklist: docs/QA-CHECKLIST.md
• Architecture: docs/REST-API-ARCHITECTURE.md
• All step notes: docs/implementation/PHASE-1-STEP-*-NOTES.md