144 lines
6.1 KiB
Markdown
144 lines
6.1 KiB
Markdown
# 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`
|