# Phase 1 Step 8d — Implementation Notes

## Status

Done.

## Plan reference

- Plan: `docs/PHASE-1-IMPLEMENTATION-PLAN.md`
- Section: "Step 8d: Scope transition rewrites — `use_role`,
  `use_session`, `use_agent`, `exit_agent`"

## Summary

Added scope transition methods to `RequestContext` that build real
`ToolScope` instances via `McpFactory::acquire()`. Added
`mcp_config` and `mcp_log_path` fields to `AppState` so scope
transitions can look up MCP server specs and acquire handles. Added
`Session::new_from_ctx` and `Session::load_from_ctx` constructors
that take `&RequestContext` + `&AppConfig` instead of `&Config`.
Migrated `edit_role` (deferred from Step 8b) since `use_role` is
now available. `use_agent` is deferred to Step 8h because
`Agent::init` takes `&GlobalConfig`.

## What was changed

### Files modified (4 files)

- **`src/config/app_state.rs`** — added 2 fields:
  - `mcp_config: Option<McpServersConfig>` — parsed MCP server
    specs from `mcp.json`, stored at init time for scope
    transitions to look up server specs by name
  - `mcp_log_path: Option<PathBuf>` — log path for MCP server
    stderr output, passed to `McpFactory::acquire`

- **`src/config/request_context.rs`** — added 6 methods in a new
  impl block:
  - `rebuild_tool_scope(&mut self, app, enabled_mcp_servers)` —
    private async helper that resolves MCP server IDs, acquires
    handles via `McpFactory::acquire()`, builds a fresh `Functions`
    instance, appends user interaction and MCP meta functions,
    assembles a `ToolScope`, and assigns it to `self.tool_scope`
  - `use_role(&mut self, app, name, abort_signal)` — retrieves
    the role, resolves its MCP server list, calls
    `rebuild_tool_scope`, then `use_role_obj`
  - `use_session(&mut self, app, session_name, abort_signal)` —
    creates or loads a session via `Session::new_from_ctx` /
    `Session::load_from_ctx`, rebuilds the tool scope, handles
    the "carry last message" prompt, calls
    `init_agent_session_variables`
  - `exit_agent(&mut self, app)` — exits the session, resets the
    tool scope to a fresh default (global functions + user
    interaction), clears agent/supervisor/rag state
  - `edit_role(&mut self, app, abort_signal)` — resolves the
    current role name, calls `upsert_role` (editor), then
    `use_role`
  - `upsert_role(&self, app, name)` — opens the role file in the
    editor (via `app.editor()`)

  Updated imports: `McpRuntime`, `TEMP_SESSION_NAME`, `AbortSignal`,
  `formatdoc`, `Confirm`, `remove_file`.

- **`src/config/session.rs`** — added 2 constructors:
  - `Session::new_from_ctx(&RequestContext, &AppConfig, name)` —
    equivalent to `Session::new(&Config, name)` but reads
    `ctx.extract_role(app)` and `app.save_session`
  - `Session::load_from_ctx(&RequestContext, &AppConfig, name, path)` —
    equivalent to `Session::load(&Config, name, path)` but calls
    `Model::retrieve_model(app, ...)` and
    `ctx.retrieve_role(app, role_name)` instead of `&Config` methods

- **`src/config/bridge.rs`** — added `mcp_config: None,
  mcp_log_path: None` to all 3 `AppState` construction sites in
  tests

### Files NOT changed

- **`src/mcp/mod.rs`** — untouched; Step 8c's extraction is used
  via `McpFactory::acquire()`
- **`src/config/mcp_factory.rs`** — untouched
- **`src/config/mod.rs`** — all `Config::use_role`,
  `Config::use_session`, `Config::use_agent`,
  `Config::exit_agent` stay intact for current callers

## Key decisions

### 1. `rebuild_tool_scope` replaces `McpRegistry::reinit`

The existing `Config::use_role` and `Config::use_session` both
follow the pattern: take `McpRegistry` → `McpRegistry::reinit` →
put registry back. The new `rebuild_tool_scope` replaces this with:
resolve server IDs → `McpFactory::acquire()` each → build
`ToolScope`. This is the core semantic change from the plan.

Key differences:
- `McpRegistry::reinit` does batch start/stop of servers (stops
  servers not in the new set, starts missing ones). The factory
  approach acquires each server independently — unused servers
  are dropped when their `Arc` refcount hits zero.
- The factory's `Weak` sharing means that switching from role A
  (github,slack) to role B (github,jira) shares the github
  handle instead of stopping and restarting it.

### 2. `ToolCallTracker` initialized with default params

`ToolCallTracker::new(4, 10)` — 4 max repeats, 10 chain length.
These match the constants used in the existing codebase (the
tracker is used for tool-call loop detection). A future step can
make these configurable via `AppConfig` if needed.

### 3. `use_agent` deferred to Step 8h

`Config::use_agent` is a static method that takes `&GlobalConfig`
and calls `Agent::init(config, agent_name, abort_signal)`.
`Agent::init` compiles agent tools, loads RAG, resolves the model,
and does ~100 lines of setup, all against `&Config`. Migrating
`Agent::init` is a significant cross-module change that belongs
in Step 8h alongside the other agent lifecycle methods.

The plan listed `use_agent` as a target for 8d, but the
dependency on `Agent::init(&Config)` makes a clean bridge
impossible without duplicating `Agent::init`.

### 4. `abort_signal` is unused in the new methods

The existing `Config::use_role` doesn't pass `abort_signal` to
individual server starts — it's used by `abortable_run_with_spinner`
wrapping the batch `McpRegistry::reinit`. The new methods use
`McpFactory::acquire()` which doesn't take an abort signal (see
Step 8c notes). The `_abort_signal` parameter is kept in the
signature for API compatibility; Step 8f can wire it into the
factory if per-server cancellation is needed.

### 5. Session constructors parallel existing ones

`Session::new_from_ctx` and `Session::load_from_ctx` are verbatim
copies of `Session::new` and `Session::load` with `config: &Config`
replaced by `ctx: &RequestContext` + `app: &AppConfig`. The copies
are under `#[allow(dead_code)]` and will replace the originals
when callers migrate in Steps 8f-8g.

### 6. `exit_agent` rebuilds tool scope inline

`Config::exit_agent` calls `self.load_functions()` to reset the
global function declarations after exiting an agent. The new
`exit_agent` does the equivalent inline: creates a fresh
`ToolScope` with `Functions::init()` + user interaction functions.
It does NOT call `rebuild_tool_scope` because there's no MCP
server set to resolve — we're returning to the global scope.

## Deviations from plan

| Deviation | Rationale |
|---|---|
| `use_agent` deferred to Step 8h | Depends on `Agent::init(&Config)` migration |
| No `abort_signal` propagation to `McpFactory::acquire` | Step 8c decided against it; behavior matches existing code |
| No parent scope restoration test | Testing requires spawning real MCP servers; documented as Phase 5 test target |

## Verification

### Compilation

- `cargo check` — clean, zero warnings, zero errors
- `cargo clippy` — clean

### Tests

- `cargo test` — **63 passed, 0 failed** (unchanged)

## Handoff to next step

### What Step 8e can rely on

- **`RequestContext::use_role(app, name, abort_signal)`** — full
  scope transition with ToolScope rebuild via McpFactory
- **`RequestContext::use_session(app, session_name, abort_signal)`** —
  full scope transition with Session creation/loading
- **`RequestContext::exit_agent(app)`** — cleans up agent state
  and rebuilds global ToolScope
- **`RequestContext::edit_role(app, abort_signal)`** — editor +
  use_role
- **`RequestContext::upsert_role(app, name)`** — editor only
- **`Session::new_from_ctx` / `Session::load_from_ctx`** — ctx-
  compatible session constructors
- **`AppState.mcp_config` / `AppState.mcp_log_path`** — MCP server
  specs and log path available for scope transitions

### Method count at end of Step 8d

- `AppConfig`: 21 methods (unchanged from 8b)
- `RequestContext`: 53 methods (46 from 8b + 6 from 8d + 1 private
  `rebuild_tool_scope`)
- `Session`: 2 new constructors (`new_from_ctx`, `load_from_ctx`)
- `AppState`: 2 new fields (`mcp_config`, `mcp_log_path`)

### What Step 8e should do

Migrate the Category C deferrals from Step 6:
- `compress_session`, `maybe_compress_session`
- `autoname_session`, `maybe_autoname_session`
- `use_rag`, `edit_rag_docs`, `rebuild_rag`
- `apply_prelude`

### Files to re-read at the start of Step 8e

- `docs/PHASE-1-IMPLEMENTATION-PLAN.md` — Step 8e section
- This notes file
- Step 6 notes — Category C deferral inventory
- `src/config/rag_cache.rs` — RagCache scaffolding from Step 6.5
- `src/config/mod.rs` — `compress_session`, `maybe_compress_session`,
  `autoname_session`, `maybe_autoname_session`, `use_rag`,
  `edit_rag_docs`, `rebuild_rag`, `apply_prelude` method bodies

## References

- Phase 1 plan: `docs/PHASE-1-IMPLEMENTATION-PLAN.md`
- Step 8b notes: `docs/implementation/PHASE-1-STEP-8b-NOTES.md`
- Step 8c notes: `docs/implementation/PHASE-1-STEP-8c-NOTES.md`
- Step 6.5 notes: `docs/implementation/PHASE-1-STEP-6.5-NOTES.md`
- Modified files:
  - `src/config/request_context.rs` (6 new methods)
  - `src/config/app_state.rs` (2 new fields)
  - `src/config/session.rs` (2 new constructors)
  - `src/config/bridge.rs` (test updates for new AppState fields)