pi-oxidized 0.1.1

package/crates/pi/src/core/agent_session_services.rs

@@ -0,0 +1,1613 @@
+//! Cwd-bound runtime services and session factory helpers.
+//!
+//! Ports the creation order and diagnostics surface from
+//! `coding-agent/src/core/agent-session-services.ts`, plus the model-priority /
+//! restore-fallback helpers from `model-resolver.ts` and auth-guidance strings.
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::fmt::Write as _;
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+use pi_ai::providers::KnownProvider;
+use pi_ai::types::{Model, ModelThinkingLevel};
+use pi_ext::protocol::FlagValueWire;
+use thiserror::Error;
+
+use super::config::{get_agent_dir, get_docs_path, resolve_path};
+use super::extension_host::HostExtensionRunner;
+use super::model_runtime::{
+    CreateModelRuntimeOptions, ModelRuntime, ModelRuntimeError, ProviderConfigInput,
+};
+use super::resources::{DefaultResourceLoader, DefaultResourceLoaderOptions, ResourceLoader};
+use super::settings::{SettingsManager, SettingsManagerCreateOptions};
+use super::trust::{ProjectTrustStore, ResolveProjectTrustedOptions, resolve_project_trusted};
+
+/// Default thinking level when none is configured (`medium`).
+pub const DEFAULT_THINKING_LEVEL: ModelThinkingLevel = ModelThinkingLevel::Medium;
+
+/// Default model ids for each known provider (catalog priority order).
+#[must_use]
+pub fn default_model_per_provider() -> &'static [(&'static str, &'static str)] {
+    &[
+        ("amazon-bedrock", "us.anthropic.claude-opus-4-6-v1"),
+        ("ant-ling", "Ring-2.6-1T"),
+        ("anthropic", "claude-opus-4-8"),
+        ("openai", "gpt-5.5"),
+        ("azure-openai-responses", "gpt-5.4"),
+        ("openai-codex", "gpt-5.5"),
+        ("radius", "auto"),
+        ("nvidia", "nvidia/nemotron-3-super-120b-a12b"),
+        ("deepseek", "deepseek-v4-pro"),
+        ("google", "gemini-3.1-pro-preview"),
+        ("google-vertex", "gemini-3.1-pro-preview"),
+        ("github-copilot", "gpt-5.4"),
+        ("openrouter", "moonshotai/kimi-k2.6"),
+        ("vercel-ai-gateway", "zai/glm-5.1"),
+        ("xai", "grok-4.5"),
+        ("groq", "openai/gpt-oss-120b"),
+        ("cerebras", "zai-glm-4.7"),
+        ("zai", "glm-5.1"),
+        ("zai-coding-cn", "glm-5.1"),
+        ("mistral", "devstral-medium-latest"),
+        ("minimax", "MiniMax-M2.7"),
+        ("minimax-cn", "MiniMax-M2.7"),
+        ("moonshotai", "kimi-k2.6"),
+        ("moonshotai-cn", "kimi-k2.6"),
+        ("huggingface", "moonshotai/Kimi-K2.6"),
+        ("fireworks", "accounts/fireworks/models/kimi-k2p6"),
+        ("together", "moonshotai/Kimi-K2.6"),
+        ("opencode", "kimi-k2.6"),
+        ("opencode-go", "kimi-k2.6"),
+        ("kimi-coding", "kimi-for-coding"),
+        ("cloudflare-workers-ai", "@cf/moonshotai/kimi-k2.6"),
+        (
+            "cloudflare-ai-gateway",
+            "workers-ai/@cf/moonshotai/kimi-k2.6",
+        ),
+        ("xiaomi", "mimo-v2.5-pro"),
+        ("xiaomi-token-plan-cn", "mimo-v2.5-pro"),
+        ("xiaomi-token-plan-ams", "mimo-v2.5-pro"),
+        ("xiaomi-token-plan-sgp", "mimo-v2.5-pro"),
+    ]
+}
+
+/// Severity of a runtime diagnostic collected while creating services/sessions.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum AgentSessionRuntimeDiagnosticKind {
+    /// Informational note.
+    Info,
+    /// Non-fatal issue the app may surface.
+    Warning,
+    /// Hard failure the app should treat as startup-blocking.
+    Error,
+}
+
+/// Non-fatal issue collected while creating services or sessions.
+///
+/// Runtime creation returns diagnostics to the caller instead of printing or
+/// exiting. The app layer decides whether warnings should be shown and whether
+/// errors should abort startup.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct AgentSessionRuntimeDiagnostic {
+    /// Severity.
+    pub kind: AgentSessionRuntimeDiagnosticKind,
+    /// Human-readable message (exact TypeScript wording where applicable).
+    pub message: String,
+}
+
+impl AgentSessionRuntimeDiagnostic {
+    /// Info diagnostic.
+    #[must_use]
+    pub fn info(message: impl Into<String>) -> Self {
+        Self {
+            kind: AgentSessionRuntimeDiagnosticKind::Info,
+            message: message.into(),
+        }
+    }
+
+    /// Warning diagnostic.
+    #[must_use]
+    pub fn warning(message: impl Into<String>) -> Self {
+        Self {
+            kind: AgentSessionRuntimeDiagnosticKind::Warning,
+            message: message.into(),
+        }
+    }
+
+    /// Error diagnostic.
+    #[must_use]
+    pub fn error(message: impl Into<String>) -> Self {
+        Self {
+            kind: AgentSessionRuntimeDiagnosticKind::Error,
+            message: message.into(),
+        }
+    }
+}
+
+/// Inputs for creating cwd-bound runtime services.
+#[derive(Default)]
+pub struct CreateAgentSessionServicesOptions {
+    /// Working directory for project-local discovery.
+    pub cwd: PathBuf,
+    /// Global agent config directory. Defaults to [`get_agent_dir`].
+    pub agent_dir: Option<PathBuf>,
+    /// Optional pre-built settings manager.
+    pub settings_manager: Option<SettingsManager>,
+    /// Optional pre-built model runtime.
+    pub model_runtime: Option<ModelRuntime>,
+    /// Extension CLI flag values (`--flag` / `--flag value`) awaiting validation.
+    pub extension_flag_values: Option<BTreeMap<String, ExtensionFlagValue>>,
+    /// Resource loader options excluding `cwd`/`agent_dir`/`settings_manager`.
+    pub resource_loader_options: Option<ResourceLoaderServiceOptions>,
+    /// Pending provider registrations discovered by extensions (tests / host).
+    ///
+    /// Each entry is `(provider_id, config, extension_path)`. Production wiring
+    /// feeds this from the extension host; Phase 3 resource loader only exposes
+    /// paths, so the seam is injectable.
+    pub pending_provider_registrations: Vec<PendingProviderRegistration>,
+    /// Registered extension flags for the unknown-flag validation seam.
+    ///
+    /// When empty, every supplied extension flag is treated as unknown.
+    pub registered_extension_flags: BTreeMap<String, ExtensionFlagType>,
+}
+
+/// Source-compatible boolean used by resource-discovery input fields.
+///
+/// Service creation immediately normalizes these flags into one private policy
+/// bitset so internal phases cannot observe an incoherent collection of booleans.
+pub type ResourceDiscoveryDisabled = bool;
+
+/// Resource-loader construction knobs owned by services creation.
+#[derive(Clone, Debug, Default)]
+pub struct ResourceLoaderServiceOptions {
+    /// Additional extension paths.
+    pub additional_extension_paths: Vec<String>,
+    /// Additional skill paths.
+    pub additional_skill_paths: Vec<String>,
+    /// Additional prompt template paths.
+    pub additional_prompt_template_paths: Vec<String>,
+    /// Additional theme paths.
+    pub additional_theme_paths: Vec<String>,
+    /// Disable extension discovery.
+    pub no_extensions: ResourceDiscoveryDisabled,
+    /// Disable skill discovery.
+    pub no_skills: ResourceDiscoveryDisabled,
+    /// Disable prompt templates.
+    pub no_prompt_templates: ResourceDiscoveryDisabled,
+    /// Disable themes.
+    pub no_themes: ResourceDiscoveryDisabled,
+    /// Disable context files.
+    pub no_context_files: ResourceDiscoveryDisabled,
+    /// Explicit system prompt override.
+    pub system_prompt: Option<String>,
+    /// Explicit append-system-prompt overrides.
+    pub append_system_prompt: Option<Vec<String>>,
+}
+
+#[derive(Clone, Copy, Debug, Default)]
+struct ResourceDiscoveryPolicy(u8);
+
+impl ResourceDiscoveryPolicy {
+    const EXTENSIONS: u8 = 1 << 0;
+    const SKILLS: u8 = 1 << 1;
+    const PROMPT_TEMPLATES: u8 = 1 << 2;
+    const THEMES: u8 = 1 << 3;
+    const CONTEXT_FILES: u8 = 1 << 4;
+
+    fn from_options(options: &ResourceLoaderServiceOptions) -> Self {
+        let mut bits = 0;
+        for (disabled, flag) in [
+            (options.no_extensions, Self::EXTENSIONS),
+            (options.no_skills, Self::SKILLS),
+            (options.no_prompt_templates, Self::PROMPT_TEMPLATES),
+            (options.no_themes, Self::THEMES),
+            (options.no_context_files, Self::CONTEXT_FILES),
+        ] {
+            if disabled {
+                bits |= flag;
+            }
+        }
+        Self(bits)
+    }
+
+    const fn disables(self, flag: u8) -> bool {
+        self.0 & flag != 0
+    }
+}
+
+/// Pending extension provider registration applied during services creation.
+#[derive(Clone, Debug)]
+pub struct PendingProviderRegistration {
+    /// Provider id to register.
+    pub name: String,
+    /// Provider configuration.
+    pub config: ProviderConfigInput,
+    /// Extension path used in diagnostic messages.
+    pub extension_path: String,
+}
+
+/// Extension CLI flag type.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ExtensionFlagType {
+    /// Boolean flag (`--flag` sets true).
+    Boolean,
+    /// String flag requiring a value.
+    String,
+}
+
+/// Parsed extension flag value from CLI unknown-flags capture.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum ExtensionFlagValue {
+    /// Boolean presence.
+    Bool(bool),
+    /// String value.
+    Str(String),
+}
+
+/// Coherent cwd-bound runtime services for one effective session cwd.
+///
+/// This is infrastructure only. The [`AgentSession`](crate::core::agent_session::AgentSession)
+/// itself is created separately so session options can be resolved against these services first.
+pub struct AgentSessionServices {
+    /// Resolved working directory.
+    pub cwd: PathBuf,
+    /// Resolved agent directory.
+    pub agent_dir: PathBuf,
+    /// Shared model/auth runtime.
+    pub model_runtime: ModelRuntime,
+    /// Resource loader (paths + snapshots; owns the cwd-bound settings manager).
+    pub resource_loader: DefaultResourceLoader,
+    /// Diagnostics collected during creation.
+    pub diagnostics: Vec<AgentSessionRuntimeDiagnostic>,
+    /// Validated extension flag values applied during creation.
+    pub extension_flag_values: BTreeMap<String, ExtensionFlagValue>,
+    /// Concrete host runner when extensions were discovered and loaded.
+    ///
+    /// `None` when no extension paths were discovered, discovery was disabled,
+    /// or host start failed (degraded to diagnostics only).
+    pub extension_runner: Option<Arc<HostExtensionRunner>>,
+}
+
+impl AgentSessionServices {
+    /// Settings manager bound to this services `cwd`/`agent_dir`.
+    #[must_use]
+    pub fn settings_manager(&self) -> &SettingsManager {
+        self.resource_loader.settings_manager()
+    }
+
+    /// Mutable settings manager.
+    pub fn settings_manager_mut(&mut self) -> &mut SettingsManager {
+        self.resource_loader.settings_manager_mut()
+    }
+}
+
+/// Inputs for creating a session from already-created services.
+pub struct CreateAgentSessionFromServicesOptions {
+    /// Previously created services.
+    pub services: AgentSessionServices,
+    /// Optional explicit model.
+    pub model: Option<Model>,
+    /// Optional thinking level.
+    pub thinking_level: Option<ModelThinkingLevel>,
+    /// Scoped models for cycling.
+    pub scoped_models: Vec<ScopedModel>,
+    /// Optional tool allowlist.
+    pub tools: Option<Vec<String>>,
+    /// Optional tool denylist.
+    pub exclude_tools: Option<Vec<String>>,
+    /// Default tool suppression mode when no allowlist is provided.
+    pub no_tools: Option<NoToolsMode>,
+    /// Session-start metadata carried into the session (reason + previous
+    /// session file for replacements).
+    pub session_start_event: Option<crate::core::agent_session::SessionStartEvent>,
+    /// Saved session model to restore (provider, model id).
+    pub saved_session_model: Option<(String, String)>,
+    /// Whether the session already has messages (affects restore vs initial).
+    pub has_existing_session: bool,
+}
+
+/// Tool-suppression mode when no explicit allowlist is provided.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum NoToolsMode {
+    /// Start with no tools enabled.
+    All,
+    /// Disable default built-ins but keep extension/custom tools.
+    Builtin,
+}
+
+/// Model + optional thinking level from a scope pattern.
+#[derive(Clone, Debug, PartialEq)]
+pub struct ScopedModel {
+    /// Resolved model.
+    pub model: Model,
+    /// Thinking level when the pattern specified one.
+    pub thinking_level: Option<ModelThinkingLevel>,
+}
+
+/// Result of initial model selection.
+#[derive(Clone, Debug, PartialEq)]
+pub struct InitialModelResult {
+    /// Selected model, when any is available/configured.
+    pub model: Option<Model>,
+    /// Thinking level to use with the model.
+    pub thinking_level: ModelThinkingLevel,
+    /// Optional fallback warning (unused by pure initial selection).
+    pub fallback_message: Option<String>,
+}
+
+/// Result of creating an agent session from services.
+///
+/// The concrete [`crate::core::agent_session::AgentSession`] constructor is
+/// owned by a sibling slice. This factory packages the resolved inputs and
+/// fallback message so callers (and later the real constructor) share one
+/// resolution path. When `AgentSession::new` lands, this result can carry the
+/// live session without changing the resolution contract.
+pub struct CreateAgentSessionResult {
+    /// Resolved model after restore / initial selection.
+    pub model: Option<Model>,
+    /// Resolved thinking level.
+    pub thinking_level: ModelThinkingLevel,
+    /// Initial active tool names after allow/exclude/`no_tools` resolution.
+    pub initial_active_tool_names: Vec<String>,
+    /// Optional allowlist (None = default set).
+    pub allowed_tool_names: Option<Vec<String>>,
+    /// Optional denylist.
+    pub excluded_tool_names: Option<Vec<String>>,
+    /// Scoped models for cycling.
+    pub scoped_models: Vec<ScopedModel>,
+    /// Warning when a saved model could not be restored or no model is available.
+    pub model_fallback_message: Option<String>,
+    /// Diagnostics accumulated during session creation (in addition to services).
+    pub diagnostics: Vec<AgentSessionRuntimeDiagnostic>,
+    /// Working directory bound into the session.
+    pub cwd: PathBuf,
+    /// Agent directory bound into the session.
+    pub agent_dir: PathBuf,
+    /// Shared model runtime.
+    pub model_runtime: ModelRuntime,
+    /// Resource loader retained for extension-driven reloads.
+    pub resource_loader: DefaultResourceLoader,
+    /// Session-start metadata forwarded from the creation options.
+    pub session_start_event: Option<crate::core::agent_session::SessionStartEvent>,
+    /// Concrete host runner moved out of services (if any).
+    pub extension_runner: Option<Arc<HostExtensionRunner>>,
+}
+
+/// Failures from services / session factory operations.
+#[derive(Clone, Debug, Error)]
+pub enum AgentSessionServicesError {
+    /// Model runtime construction failed.
+    #[error(transparent)]
+    ModelRuntime(#[from] ModelRuntimeError),
+    /// Project trust resolution failed before resource loading.
+    #[error("{0}")]
+    Trust(String),
+    /// Resource loader reload failed.
+    #[error("{0}")]
+    ResourceLoader(String),
+}
+
+/// Provider login help block used by no-model guidance strings.
+#[must_use]
+pub fn get_provider_login_help() -> String {
+    let docs = get_docs_path();
+    format!(
+        "Use /login to log into a provider via OAuth or API key. See:\n  {}\n  {}",
+        docs.join("providers.md").display(),
+        docs.join("models.md").display()
+    )
+}
+
+/// Message when no models are available at all.
+#[must_use]
+pub fn format_no_models_available_message() -> String {
+    format!("No models available. {}", get_provider_login_help())
+}
+
+/// Message when a prompt is attempted with no selected model.
+#[must_use]
+pub fn format_no_model_selected_message() -> String {
+    format!(
+        "No model selected.\n\n{}\n\nThen use /model to select a model.",
+        get_provider_login_help()
+    )
+}
+
+/// Message when auth is missing for a provider.
+#[must_use]
+pub fn format_no_api_key_found_message(provider: &str) -> String {
+    let provider_display = if provider == "unknown" {
+        "the selected model"
+    } else {
+        provider
+    };
+    format!(
+        "No API key found for {provider_display}.\n\n{}",
+        get_provider_login_help()
+    )
+}
+
+/// OAuth-specific auth failure guidance.
+#[must_use]
+pub fn format_oauth_auth_failed_message(provider: &str) -> String {
+    format!(
+        "Authentication failed for \"{provider}\". Credentials may have expired or network is unavailable. Run '/login {provider}' to re-authenticate."
+    )
+}
+
+/// Create all cwd-bound session services with trust resolved from saved/global state.
+///
+/// # Errors
+///
+/// Returns service construction, trust resolution, or resource loading errors.
+pub async fn create_agent_session_services(
+    options: CreateAgentSessionServicesOptions,
+) -> Result<AgentSessionServices, AgentSessionServicesError> {
+    create_agent_session_services_with_trust(options, None).await
+}
+
+/// Create all cwd-bound session services with an invocation-scoped trust override.
+///
+/// The override is resolved before project settings, packages, or extensions load.
+///
+/// # Errors
+///
+/// Returns service construction, trust resolution, or resource loading errors.
+pub async fn create_agent_session_services_with_trust(
+    options: CreateAgentSessionServicesOptions,
+    project_trust_override: Option<bool>,
+) -> Result<AgentSessionServices, AgentSessionServicesError> {
+    let CreateAgentSessionServicesOptions {
+        cwd,
+        agent_dir,
+        settings_manager,
+        model_runtime,
+        extension_flag_values,
+        resource_loader_options,
+        pending_provider_registrations,
+        registered_extension_flags,
+    } = options;
+    let settings_manager_was_supplied = settings_manager.is_some();
+    let mut foundation =
+        create_service_foundation(cwd, agent_dir, settings_manager, model_runtime).await?;
+    let project_trusted = if settings_manager_was_supplied && project_trust_override.is_none() {
+        foundation.settings_manager.is_project_trusted()
+    } else {
+        resolve_project_trusted(ResolveProjectTrustedOptions {
+            cwd: foundation.cwd.clone(),
+            trust_store: &ProjectTrustStore::new(&foundation.agent_dir),
+            trust_override: project_trust_override,
+            default_project_trust: foundation.settings_manager.get_default_project_trust(),
+            extension_hook: None,
+            ui: None,
+            on_extension_error: None,
+        })
+        .map_err(|error| AgentSessionServicesError::Trust(error.to_string()))?
+    };
+    foundation
+        .settings_manager
+        .set_project_trusted(project_trusted);
+    let (resource_loader, discovery) = create_service_resource_loader(
+        &foundation.cwd,
+        &foundation.agent_dir,
+        foundation.settings_manager,
+        resource_loader_options.unwrap_or_default(),
+    )
+    .await?;
+
+    let mut diagnostics = extension_discovery_diagnostics(&resource_loader);
+    let (mut extension_runner, host_registered_flags) = start_extension_phase(
+        &resource_loader,
+        discovery,
+        &foundation.cwd,
+        &foundation.model_runtime,
+        project_trusted,
+        &mut diagnostics,
+    )
+    .await;
+
+    let mut registered_flags = registered_extension_flags;
+    registered_flags.extend(host_registered_flags);
+    let (flag_diagnostics, applied_flags) =
+        apply_extension_flag_values(extension_flag_values.unwrap_or_default(), &registered_flags);
+    diagnostics.extend(flag_diagnostics);
+    if let Some(runner) = extension_runner.as_deref()
+        && let Err(error) = apply_flags_to_runner(runner, &applied_flags).await
+    {
+        diagnostics.push(AgentSessionRuntimeDiagnostic::error(format!(
+            "Extension flags failed to apply: {error}"
+        )));
+        runner.unregister_providers_from(&foundation.model_runtime);
+        runner.shutdown_once().await;
+        extension_runner = None;
+    }
+
+    for registration in pending_provider_registrations {
+        if let Err(error) = foundation
+            .model_runtime
+            .register_provider(&registration.name, registration.config)
+        {
+            diagnostics.push(AgentSessionRuntimeDiagnostic::error(format!(
+                "Extension \"{}\" error: {error}",
+                registration.extension_path
+            )));
+        }
+    }
+
+    let _ = foundation
+        .model_runtime
+        .refresh(super::model_runtime::ModelsRefreshOptions {
+            allow_network: Some(false),
+        })
+        .await;
+
+    Ok(AgentSessionServices {
+        cwd: foundation.cwd,
+        agent_dir: foundation.agent_dir,
+        model_runtime: foundation.model_runtime,
+        resource_loader,
+        diagnostics,
+        extension_flag_values: applied_flags,
+        extension_runner,
+    })
+}
+
+struct ServiceFoundation {
+    cwd: PathBuf,
+    agent_dir: PathBuf,
+    model_runtime: ModelRuntime,
+    settings_manager: SettingsManager,
+}
+
+async fn create_service_foundation(
+    cwd: PathBuf,
+    agent_dir: Option<PathBuf>,
+    settings_manager: Option<SettingsManager>,
+    model_runtime: Option<ModelRuntime>,
+) -> Result<ServiceFoundation, AgentSessionServicesError> {
+    let cwd = resolve_path(cwd.to_string_lossy().as_ref());
+    let agent_dir = agent_dir.map_or_else(get_agent_dir, |path| {
+        resolve_path(path.to_string_lossy().as_ref())
+    });
+    let model_runtime = match model_runtime {
+        Some(runtime) => runtime,
+        None => {
+            ModelRuntime::create(CreateModelRuntimeOptions {
+                auth_path: Some(agent_dir.join("auth.json")),
+                models_path: Some(agent_dir.join("models.json")),
+                models_store_path: Some(agent_dir.join("models-store.json")),
+                allow_model_network: Some(false),
+                ..CreateModelRuntimeOptions::default()
+            })
+            .await?
+        }
+    };
+    let settings_manager = settings_manager.unwrap_or_else(|| {
+        SettingsManager::create(
+            &cwd,
+            Some(&agent_dir),
+            SettingsManagerCreateOptions::default().project_trusted(false),
+        )
+    });
+    Ok(ServiceFoundation {
+        cwd,
+        agent_dir,
+        model_runtime,
+        settings_manager,
+    })
+}
+
+async fn create_service_resource_loader(
+    cwd: &Path,
+    agent_dir: &Path,
+    settings_manager: SettingsManager,
+    options: ResourceLoaderServiceOptions,
+) -> Result<(DefaultResourceLoader, ResourceDiscoveryPolicy), AgentSessionServicesError> {
+    let discovery = ResourceDiscoveryPolicy::from_options(&options);
+    let mut loader = DefaultResourceLoader::new(DefaultResourceLoaderOptions {
+        cwd: cwd.to_path_buf(),
+        agent_dir: agent_dir.to_path_buf(),
+        settings_manager: Some(settings_manager),
+        additional_extension_paths: options.additional_extension_paths,
+        additional_skill_paths: options.additional_skill_paths,
+        additional_prompt_template_paths: options.additional_prompt_template_paths,
+        additional_theme_paths: options.additional_theme_paths,
+        no_extensions: discovery.disables(ResourceDiscoveryPolicy::EXTENSIONS),
+        no_skills: discovery.disables(ResourceDiscoveryPolicy::SKILLS),
+        no_prompt_templates: discovery.disables(ResourceDiscoveryPolicy::PROMPT_TEMPLATES),
+        no_themes: discovery.disables(ResourceDiscoveryPolicy::THEMES),
+        no_context_files: discovery.disables(ResourceDiscoveryPolicy::CONTEXT_FILES),
+        system_prompt: options.system_prompt,
+        append_system_prompt: options.append_system_prompt,
+    });
+    loader
+        .reload()
+        .await
+        .map_err(|error| AgentSessionServicesError::ResourceLoader(error.to_string()))?;
+    Ok((loader, discovery))
+}
+
+fn extension_discovery_diagnostics(
+    loader: &DefaultResourceLoader,
+) -> Vec<AgentSessionRuntimeDiagnostic> {
+    loader
+        .get_extensions()
+        .errors
+        .iter()
+        .map(|error| {
+            AgentSessionRuntimeDiagnostic::error(format!(
+                "Extension \"{}\" error: {}",
+                error.path, error.error
+            ))
+        })
+        .collect()
+}
+
+async fn start_extension_phase(
+    loader: &DefaultResourceLoader,
+    discovery: ResourceDiscoveryPolicy,
+    cwd: &Path,
+    model_runtime: &ModelRuntime,
+    project_trusted: bool,
+    diagnostics: &mut Vec<AgentSessionRuntimeDiagnostic>,
+) -> (
+    Option<Arc<HostExtensionRunner>>,
+    BTreeMap<String, ExtensionFlagType>,
+) {
+    if discovery.disables(ResourceDiscoveryPolicy::EXTENSIONS) {
+        return (None, BTreeMap::new());
+    }
+    let paths = loader
+        .get_extensions()
+        .paths
+        .iter()
+        .map(|info| {
+            if info.resolved_path.is_empty() {
+                info.path.clone()
+            } else {
+                info.resolved_path.clone()
+            }
+        })
+        .collect::<Vec<_>>();
+    if paths.is_empty() {
+        return (None, BTreeMap::new());
+    }
+    match HostExtensionRunner::start_with_cwd_and_trust(
+        paths,
+        cwd.to_string_lossy().into_owned(),
+        project_trusted,
+    )
+    .await
+    {
+        Ok(runner) => {
+            for (path, message) in runner.load_errors() {
+                diagnostics.push(AgentSessionRuntimeDiagnostic::error(format!(
+                    "Extension \"{path}\" error: {message}"
+                )));
+            }
+            for (path, outcome) in runner.register_providers_on(model_runtime) {
+                if let Err(error) = outcome {
+                    diagnostics.push(AgentSessionRuntimeDiagnostic::error(format!(
+                        "Extension \"{path}\" error: {error}"
+                    )));
+                }
+            }
+            let flags = runner.registered_flag_types();
+            (Some(runner), flags)
+        }
+        Err(error) => {
+            diagnostics.push(AgentSessionRuntimeDiagnostic::error(format!(
+                "Extension host failed to start: {error}"
+            )));
+            (None, BTreeMap::new())
+        }
+    }
+}
+
+async fn apply_flags_to_runner(
+    runner: &HostExtensionRunner,
+    applied_flags: &BTreeMap<String, ExtensionFlagValue>,
+) -> Result<(), pi_ext::client::HostClientError> {
+    let values = applied_flags
+        .iter()
+        .map(|(name, value)| {
+            let value = match value {
+                ExtensionFlagValue::Bool(value) => FlagValueWire::Boolean(*value),
+                ExtensionFlagValue::Str(value) => FlagValueWire::String(value.clone()),
+            };
+            (name.clone(), value)
+        })
+        .collect();
+    runner.apply_flag_values(&values).await
+}
+
+/// Validate and apply extension CLI flag values.
+///
+/// Unknown flags produce a single error diagnostic with the exact
+/// `Unknown option[s]: --a, --b` wording. Boolean flags ignore provided string
+/// values and store `true`. String flags require a string value.
+#[must_use]
+pub fn apply_extension_flag_values(
+    extension_flag_values: BTreeMap<String, ExtensionFlagValue>,
+    registered_flags: &BTreeMap<String, ExtensionFlagType>,
+) -> (
+    Vec<AgentSessionRuntimeDiagnostic>,
+    BTreeMap<String, ExtensionFlagValue>,
+) {
+    if extension_flag_values.is_empty() {
+        return (Vec::new(), BTreeMap::new());
+    }
+
+    let mut diagnostics = Vec::new();
+    let mut applied = BTreeMap::new();
+    let mut unknown_flags = Vec::new();
+
+    for (name, value) in extension_flag_values {
+        let Some(flag_type) = registered_flags.get(&name) else {
+            unknown_flags.push(name);
+            continue;
+        };
+        match flag_type {
+            ExtensionFlagType::Boolean => {
+                applied.insert(name, ExtensionFlagValue::Bool(true));
+            }
+            ExtensionFlagType::String => match value {
+                ExtensionFlagValue::Str(text) => {
+                    applied.insert(name, ExtensionFlagValue::Str(text));
+                }
+                ExtensionFlagValue::Bool(_) => {
+                    diagnostics.push(AgentSessionRuntimeDiagnostic::error(format!(
+                        "Extension flag \"--{name}\" requires a value"
+                    )));
+                }
+            },
+        }
+    }
+
+    if !unknown_flags.is_empty() {
+        let plural = if unknown_flags.len() == 1 { "" } else { "s" };
+        let list = unknown_flags
+            .iter()
+            .map(|name| format!("--{name}"))
+            .collect::<Vec<_>>()
+            .join(", ");
+        diagnostics.push(AgentSessionRuntimeDiagnostic::error(format!(
+            "Unknown option{plural}: {list}"
+        )));
+    }
+
+    (diagnostics, applied)
+}
+
+/// Find the initial model based on priority:
+/// 1. CLI provider+model (caller resolves and passes via `cli_model`)
+/// 2. First scoped model when not continuing
+/// 3. Saved default from settings when auth is configured
+/// 4. First available default-per-provider match, else first available
+/// 5. None
+pub async fn find_initial_model(options: FindInitialModelOptions<'_>) -> InitialModelResult {
+    if let Some(model) = options.cli_model {
+        return InitialModelResult {
+            model: Some(model.clone()),
+            thinking_level: DEFAULT_THINKING_LEVEL,
+            fallback_message: None,
+        };
+    }
+
+    if !options.scoped_models.is_empty() && !options.is_continuing {
+        let first = &options.scoped_models[0];
+        return InitialModelResult {
+            model: Some(first.model.clone()),
+            thinking_level: first.thinking_level.unwrap_or(
+                options
+                    .default_thinking_level
+                    .unwrap_or(DEFAULT_THINKING_LEVEL),
+            ),
+            fallback_message: None,
+        };
+    }
+
+    if let (Some(provider), Some(model_id)) = (options.default_provider, options.default_model_id)
+        && let Some(found) = options.model_runtime.get_model(provider, model_id)
+        && options.model_runtime.has_configured_auth(&found.provider)
+    {
+        return InitialModelResult {
+            model: Some(found),
+            thinking_level: options
+                .default_thinking_level
+                .unwrap_or(DEFAULT_THINKING_LEVEL),
+            fallback_message: None,
+        };
+    }
+
+    let available = options
+        .model_runtime
+        .get_available(None)
+        .await
+        .unwrap_or_default();
+    if let Some(model) = pick_default_available(&available) {
+        return InitialModelResult {
+            model: Some(model),
+            thinking_level: DEFAULT_THINKING_LEVEL,
+            fallback_message: None,
+        };
+    }
+
+    InitialModelResult {
+        model: None,
+        thinking_level: DEFAULT_THINKING_LEVEL,
+        fallback_message: None,
+    }
+}
+
+/// Options for [`find_initial_model`].
+pub struct FindInitialModelOptions<'a> {
+    /// Pre-resolved CLI model (highest priority).
+    pub cli_model: Option<&'a Model>,
+    /// Scoped models for cycling.
+    pub scoped_models: &'a [ScopedModel],
+    /// Whether a session is being continued/resumed.
+    pub is_continuing: bool,
+    /// Settings default provider.
+    pub default_provider: Option<&'a str>,
+    /// Settings default model id.
+    pub default_model_id: Option<&'a str>,
+    /// Settings default thinking level.
+    pub default_thinking_level: Option<ModelThinkingLevel>,
+    /// Model runtime used for lookup/availability.
+    pub model_runtime: &'a ModelRuntime,
+}
+
+/// Restore a saved session model, falling back to `current_model` or available models.
+pub async fn restore_model_from_session(
+    saved_provider: &str,
+    saved_model_id: &str,
+    current_model: Option<&Model>,
+    model_runtime: &ModelRuntime,
+) -> (Option<Model>, Option<String>) {
+    let restored = model_runtime.get_model(saved_provider, saved_model_id);
+    let has_configured_auth = restored
+        .as_ref()
+        .is_some_and(|model| model_runtime.has_configured_auth(&model.provider));
+
+    if has_configured_auth && let Some(model) = restored {
+        return (Some(model), None);
+    }
+
+    let reason = if restored.is_none() {
+        "model no longer exists"
+    } else {
+        "no auth configured"
+    };
+
+    if let Some(current) = current_model {
+        return (
+            Some(current.clone()),
+            Some(format!(
+                "Could not restore model {saved_provider}/{saved_model_id} ({reason}). Using {}/{}.",
+                current.provider, current.id
+            )),
+        );
+    }
+
+    let available = model_runtime.get_available(None).await.unwrap_or_default();
+    if let Some(fallback) = pick_default_available(&available) {
+        return (
+            Some(fallback.clone()),
+            Some(format!(
+                "Could not restore model {saved_provider}/{saved_model_id} ({reason}). Using {}/{}.",
+                fallback.provider, fallback.id
+            )),
+        );
+    }
+
+    (None, None)
+}
+
+/// Create an [`AgentSession`](crate::core::agent_session::AgentSession) package from previously created services.
+///
+/// Resolves model restore / initial selection, thinking level, and tool names.
+/// The live `AgentSession` constructor is owned by a sibling module; this
+/// returns the fully resolved inputs plus fallback message.
+///
+/// # Errors
+///
+/// Currently infallible for the resolution path; the `Result` form matches the
+/// TypeScript promise API and leaves room for constructor failures once wired.
+pub async fn create_agent_session_from_services(
+    options: CreateAgentSessionFromServicesOptions,
+) -> Result<CreateAgentSessionResult, AgentSessionServicesError> {
+    let CreateAgentSessionFromServicesOptions {
+        services,
+        model: explicit_model,
+        thinking_level: explicit_thinking,
+        scoped_models,
+        tools,
+        exclude_tools,
+        no_tools,
+        session_start_event,
+        saved_session_model,
+        has_existing_session,
+    } = options;
+
+    let (model, model_fallback_message) = resolve_session_model(
+        &services,
+        explicit_model,
+        &scoped_models,
+        saved_session_model.as_ref(),
+        has_existing_session,
+    )
+    .await;
+    let mut thinking_level = explicit_thinking.unwrap_or_else(|| {
+        services
+            .settings_manager()
+            .get_default_thinking_level()
+            .unwrap_or(DEFAULT_THINKING_LEVEL)
+    });
+    if model.is_none() {
+        thinking_level = ModelThinkingLevel::Off;
+    }
+    let (initial_active_tool_names, allowed_tool_names) =
+        resolve_session_tools(tools, exclude_tools.as_deref(), no_tools);
+    let diagnostics = services.diagnostics.clone();
+
+    Ok(CreateAgentSessionResult {
+        model,
+        thinking_level,
+        initial_active_tool_names,
+        allowed_tool_names,
+        excluded_tool_names: exclude_tools,
+        scoped_models,
+        model_fallback_message,
+        diagnostics,
+        cwd: services.cwd,
+        agent_dir: services.agent_dir,
+        model_runtime: services.model_runtime,
+        resource_loader: services.resource_loader,
+        extension_runner: services.extension_runner,
+        session_start_event,
+    })
+}
+
+async fn resolve_session_model(
+    services: &AgentSessionServices,
+    explicit_model: Option<Model>,
+    scoped_models: &[ScopedModel],
+    saved_session_model: Option<&(String, String)>,
+    has_existing_session: bool,
+) -> (Option<Model>, Option<String>) {
+    let mut model = explicit_model;
+    let mut fallback = None;
+    if model.is_none()
+        && has_existing_session
+        && let Some((provider, model_id)) = saved_session_model
+    {
+        let restored = services.model_runtime.get_model(provider, model_id);
+        if let Some(found) = restored
+            && services.model_runtime.has_configured_auth(&found.provider)
+        {
+            model = Some(found);
+        } else {
+            fallback = Some(format!("Could not restore model {provider}/{model_id}"));
+        }
+    }
+    if model.is_none() {
+        let selected = find_initial_model(FindInitialModelOptions {
+            cli_model: None,
+            scoped_models,
+            is_continuing: has_existing_session,
+            default_provider: services
+                .settings_manager()
+                .get_default_provider()
+                .as_deref(),
+            default_model_id: services.settings_manager().get_default_model().as_deref(),
+            default_thinking_level: services.settings_manager().get_default_thinking_level(),
+            model_runtime: &services.model_runtime,
+        })
+        .await
+        .model;
+        match (selected.as_ref(), fallback.as_mut()) {
+            (None, _) => fallback = Some(format_no_models_available_message()),
+            (Some(selected), Some(existing)) => {
+                let _ = write!(existing, ". Using {}/{}", selected.provider, selected.id);
+            }
+            (Some(_), None) => {}
+        }
+        model = selected;
+    }
+    (model, fallback)
+}
+
+fn resolve_session_tools(
+    tools: Option<Vec<String>>,
+    exclude_tools: Option<&[String]>,
+    no_tools: Option<NoToolsMode>,
+) -> (Vec<String>, Option<Vec<String>>) {
+    let allowed = match (&tools, no_tools) {
+        (Some(tools), _) => Some(tools.clone()),
+        (None, Some(NoToolsMode::All)) => Some(Vec::new()),
+        (None, Some(NoToolsMode::Builtin) | None) => None,
+    };
+    let excluded = exclude_tools.map(|names| names.iter().cloned().collect::<BTreeSet<_>>());
+    let active = if let Some(tools) = tools {
+        tools
+            .into_iter()
+            .filter(|name| excluded.as_ref().is_none_or(|set| !set.contains(name)))
+            .collect()
+    } else if no_tools.is_some() {
+        Vec::new()
+    } else {
+        ["read", "bash", "edit", "write"]
+            .into_iter()
+            .filter(|name| excluded.as_ref().is_none_or(|set| !set.contains(*name)))
+            .map(str::to_owned)
+            .collect()
+    };
+    (active, allowed)
+}
+
+fn pick_default_available(available: &[Model]) -> Option<Model> {
+    for (provider, default_id) in default_model_per_provider() {
+        if let Some(match_model) = available
+            .iter()
+            .find(|model| model.provider == *provider && model.id == *default_id)
+        {
+            return Some(match_model.clone());
+        }
+        // Keep KnownProvider parse reachable so renames fail tests.
+        let _ = KnownProvider::from_id(provider);
+    }
+    available.first().cloned()
+}
+
+/// Resolve path helper re-export for tests.
+#[must_use]
+pub fn resolve_service_path(path: impl AsRef<Path>) -> PathBuf {
+    resolve_path(path.as_ref().to_string_lossy().as_ref())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pi_ai::auth::InMemoryCredentialStore;
+    use pi_ai::models_store::InMemoryModelsStore;
+    use pi_ai::types::{ModelCost, ModelInput};
+    use std::io;
+
+    use crate::core::model_runtime::{
+        CreateModelRuntimeOptions, ModelsJsonConfig, ProviderModelDefinition,
+    };
+
+    type TestResult<T = ()> = Result<T, Box<dyn std::error::Error>>;
+
+    fn required<T>(value: Option<T>, context: &'static str) -> io::Result<T> {
+        value.ok_or_else(|| io::Error::other(context))
+    }
+
+    async fn runtime_with_env_openai() -> TestResult<ModelRuntime> {
+        let mut env = pi_ai::auth::ProviderEnv::new();
+        env.insert("OPENAI_API_KEY".to_owned(), "sk-test".to_owned());
+        Ok(ModelRuntime::create(CreateModelRuntimeOptions {
+            credentials: Some(Arc::new(InMemoryCredentialStore::new())),
+            models_store: Some(Arc::new(InMemoryModelsStore::new())),
+            models_config: Some(ModelsJsonConfig::empty()),
+            allow_model_network: Some(false),
+            auth_env: Some(env),
+            ..CreateModelRuntimeOptions::default()
+        })
+        .await?)
+    }
+
+    #[test]
+    fn auth_guidance_strings_match_typescript() {
+        let help = get_provider_login_help();
+        assert!(help.contains("Use /login to log into a provider via OAuth or API key."));
+        assert!(help.contains("providers.md"));
+        assert!(help.contains("models.md"));
+
+        let no_models = format_no_models_available_message();
+        assert!(no_models.starts_with("No models available. "));
+        assert!(no_models.contains(&help));
+
+        let no_selected = format_no_model_selected_message();
+        assert!(no_selected.starts_with("No model selected."));
+        assert!(no_selected.contains("Then use /model to select a model."));
+
+        let no_key = format_no_api_key_found_message("anthropic");
+        assert_eq!(no_key, format!("No API key found for anthropic.\n\n{help}"));
+        let unknown = format_no_api_key_found_message("unknown");
+        assert!(unknown.contains("the selected model"));
+
+        let oauth = format_oauth_auth_failed_message("openai-codex");
+        assert_eq!(
+            oauth,
+            "Authentication failed for \"openai-codex\". Credentials may have expired or network is unavailable. Run '/login openai-codex' to re-authenticate."
+        );
+    }
+
+    #[test]
+    fn extension_flag_validation_unknown_and_string_required() {
+        let mut flags = BTreeMap::new();
+        flags.insert("verbose".to_owned(), ExtensionFlagValue::Bool(true));
+        flags.insert("mode".to_owned(), ExtensionFlagValue::Bool(true));
+        flags.insert("unknown".to_owned(), ExtensionFlagValue::Str("x".into()));
+
+        let mut registered = BTreeMap::new();
+        registered.insert("verbose".to_owned(), ExtensionFlagType::Boolean);
+        registered.insert("mode".to_owned(), ExtensionFlagType::String);
+
+        let (diagnostics, applied) = apply_extension_flag_values(flags, &registered);
+        assert!(applied.contains_key("verbose"));
+        assert!(!applied.contains_key("mode"));
+        assert_eq!(diagnostics.len(), 2);
+        assert!(
+            diagnostics
+                .iter()
+                .any(|d| d.message == "Extension flag \"--mode\" requires a value")
+        );
+        assert!(
+            diagnostics
+                .iter()
+                .any(|d| d.message == "Unknown option: --unknown")
+        );
+    }
+
+    #[test]
+    fn extension_flag_validation_plural_unknown_options() {
+        let mut flags = BTreeMap::new();
+        flags.insert("a".to_owned(), ExtensionFlagValue::Bool(true));
+        flags.insert("b".to_owned(), ExtensionFlagValue::Str("1".into()));
+        let (diagnostics, _) = apply_extension_flag_values(flags, &BTreeMap::new());
+        assert_eq!(diagnostics.len(), 1);
+        assert_eq!(diagnostics[0].message, "Unknown options: --a, --b");
+    }
+
+    #[tokio::test]
+    async fn services_creation_order_registers_pending_providers() -> TestResult {
+        let dir = tempfile::tempdir()?;
+        let cwd = dir.path().join("project");
+        let agent = dir.path().join("agent");
+        std::fs::create_dir_all(&cwd)?;
+        std::fs::create_dir_all(&agent)?;
+
+        let runtime = ModelRuntime::create(CreateModelRuntimeOptions {
+            credentials: Some(Arc::new(InMemoryCredentialStore::new())),
+            models_store: Some(Arc::new(InMemoryModelsStore::new())),
+            models_config: Some(ModelsJsonConfig::empty()),
+            allow_model_network: Some(false),
+            ..CreateModelRuntimeOptions::default()
+        })
+        .await?;
+
+        let services = create_agent_session_services(CreateAgentSessionServicesOptions {
+            cwd: cwd.clone(),
+            agent_dir: Some(agent.clone()),
+            model_runtime: Some(runtime),
+            pending_provider_registrations: vec![PendingProviderRegistration {
+                name: "acme".to_owned(),
+                config: ProviderConfigInput {
+                    base_url: Some("https://acme.test/v1".into()),
+                    api: Some("openai-completions".into()),
+                    api_key: Some("sk-acme".into()),
+                    models: Some(vec![ProviderModelDefinition {
+                        id: "acme-1".into(),
+                        name: Some("Acme 1".into()),
+                        api: Some("openai-completions".into()),
+                        base_url: Some("https://acme.test/v1".into()),
+                        reasoning: false,
+                        thinking_level_map: None,
+                        input: Some(vec![ModelInput::Text]),
+                        cost: Some(ModelCost::default()),
+                        context_window: Some(8_000),
+                        max_tokens: Some(1_024),
+                        headers: None,
+                        compat: None,
+                    }]),
+                    ..ProviderConfigInput::default()
+                },
+                extension_path: "/ext/acme.ts".into(),
+            }],
+            registered_extension_flags: BTreeMap::new(),
+            extension_flag_values: None,
+            settings_manager: None,
+            resource_loader_options: Some(ResourceLoaderServiceOptions {
+                no_extensions: true,
+                no_skills: true,
+                no_prompt_templates: true,
+                no_themes: true,
+                no_context_files: true,
+                ..ResourceLoaderServiceOptions::default()
+            }),
+        })
+        .await?;
+
+        assert!(services.model_runtime.get_model("acme", "acme-1").is_some());
+        assert!(services.model_runtime.has_configured_auth("acme"));
+        assert!(services.diagnostics.is_empty());
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn pending_provider_failure_becomes_diagnostic() -> TestResult {
+        let dir = tempfile::tempdir()?;
+        let cwd = dir.path().join("project");
+        let agent = dir.path().join("agent");
+        std::fs::create_dir_all(&cwd)?;
+        std::fs::create_dir_all(&agent)?;
+
+        let runtime = ModelRuntime::create_in_memory().await?;
+        let services = create_agent_session_services(CreateAgentSessionServicesOptions {
+            cwd,
+            agent_dir: Some(agent),
+            model_runtime: Some(runtime),
+            pending_provider_registrations: vec![PendingProviderRegistration {
+                name: "broken".into(),
+                config: ProviderConfigInput {
+                    models: Some(vec![ProviderModelDefinition {
+                        id: "m".into(),
+                        name: None,
+                        api: None,
+                        base_url: None,
+                        reasoning: false,
+                        thinking_level_map: None,
+                        input: None,
+                        cost: None,
+                        context_window: None,
+                        max_tokens: None,
+                        headers: None,
+                        compat: None,
+                    }]),
+                    ..ProviderConfigInput::default()
+                },
+                extension_path: "/ext/broken.ts".into(),
+            }],
+            resource_loader_options: Some(ResourceLoaderServiceOptions {
+                no_extensions: true,
+                no_skills: true,
+                no_prompt_templates: true,
+                no_themes: true,
+                no_context_files: true,
+                ..ResourceLoaderServiceOptions::default()
+            }),
+            ..CreateAgentSessionServicesOptions::default()
+        })
+        .await?;
+
+        assert_eq!(services.diagnostics.len(), 1);
+        assert!(
+            services.diagnostics[0]
+                .message
+                .starts_with("Extension \"/ext/broken.ts\" error:")
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn find_initial_model_priority_settings_then_available() -> TestResult {
+        let runtime = runtime_with_env_openai().await?;
+        let openai_default = required(
+            runtime.get_model("openai", "gpt-5.5"),
+            "OpenAI default must exist in the built-in catalog",
+        )?;
+
+        // Settings default with configured auth wins over first-available scan.
+        let result = find_initial_model(FindInitialModelOptions {
+            cli_model: None,
+            scoped_models: &[],
+            is_continuing: false,
+            default_provider: Some("openai"),
+            default_model_id: Some("gpt-5.5"),
+            default_thinking_level: Some(ModelThinkingLevel::High),
+            model_runtime: &runtime,
+        })
+        .await;
+        assert_eq!(
+            result.model.as_ref().map(|m| m.id.as_str()),
+            Some("gpt-5.5")
+        );
+        assert_eq!(result.thinking_level, ModelThinkingLevel::High);
+
+        // CLI model wins over settings.
+        let cli = openai_default.clone();
+        let result = find_initial_model(FindInitialModelOptions {
+            cli_model: Some(&cli),
+            scoped_models: &[],
+            is_continuing: false,
+            default_provider: Some("openai"),
+            default_model_id: Some("other"),
+            default_thinking_level: None,
+            model_runtime: &runtime,
+        })
+        .await;
+        assert_eq!(
+            result.model.as_ref().map(|m| m.id.as_str()),
+            Some("gpt-5.5")
+        );
+        assert_eq!(result.thinking_level, DEFAULT_THINKING_LEVEL);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn find_initial_model_scoped_skipped_when_continuing() -> TestResult {
+        let runtime = runtime_with_env_openai().await?;
+        let model = required(
+            runtime.get_model("openai", "gpt-5.5"),
+            "OpenAI test model must exist in the built-in catalog",
+        )?;
+        let scoped = vec![ScopedModel {
+            model: model.clone(),
+            thinking_level: Some(ModelThinkingLevel::Low),
+        }];
+
+        let continuing = find_initial_model(FindInitialModelOptions {
+            cli_model: None,
+            scoped_models: &scoped,
+            is_continuing: true,
+            default_provider: None,
+            default_model_id: None,
+            default_thinking_level: None,
+            model_runtime: &runtime,
+        })
+        .await;
+        // Continues into available-default path (openai default with env auth).
+        assert_eq!(
+            continuing.model.as_ref().map(|m| m.id.as_str()),
+            Some("gpt-5.5")
+        );
+        assert_eq!(continuing.thinking_level, DEFAULT_THINKING_LEVEL);
+
+        let fresh = find_initial_model(FindInitialModelOptions {
+            cli_model: None,
+            scoped_models: &scoped,
+            is_continuing: false,
+            default_provider: None,
+            default_model_id: None,
+            default_thinking_level: None,
+            model_runtime: &runtime,
+        })
+        .await;
+        assert_eq!(fresh.thinking_level, ModelThinkingLevel::Low);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn restore_model_fallback_message() -> TestResult {
+        let runtime = runtime_with_env_openai().await?;
+        let current = required(
+            runtime.get_model("openai", "gpt-5.5"),
+            "OpenAI fallback model must exist in the built-in catalog",
+        )?;
+        let (model, message) =
+            restore_model_from_session("missing", "gone", Some(&current), &runtime).await;
+        assert_eq!(model.as_ref().map(|m| m.id.as_str()), Some("gpt-5.5"));
+        assert_eq!(
+            message.as_deref(),
+            Some(
+                "Could not restore model missing/gone (model no longer exists). Using openai/gpt-5.5."
+            )
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn create_session_from_services_tool_resolution_and_fallback() -> TestResult {
+        let dir = tempfile::tempdir()?;
+        let cwd = dir.path().join("project");
+        let agent = dir.path().join("agent");
+        std::fs::create_dir_all(&cwd)?;
+        std::fs::create_dir_all(&agent)?;
+
+        let runtime = ModelRuntime::create_in_memory().await?;
+        let services = create_agent_session_services(CreateAgentSessionServicesOptions {
+            cwd,
+            agent_dir: Some(agent),
+            model_runtime: Some(runtime),
+            resource_loader_options: Some(ResourceLoaderServiceOptions {
+                no_extensions: true,
+                no_skills: true,
+                no_prompt_templates: true,
+                no_themes: true,
+                no_context_files: true,
+                ..ResourceLoaderServiceOptions::default()
+            }),
+            ..CreateAgentSessionServicesOptions::default()
+        })
+        .await?;
+
+        let result = create_agent_session_from_services(CreateAgentSessionFromServicesOptions {
+            services,
+            model: None,
+            thinking_level: None,
+            scoped_models: Vec::new(),
+            tools: None,
+            exclude_tools: Some(vec!["bash".into()]),
+            no_tools: None,
+            session_start_event: None,
+            saved_session_model: None,
+            has_existing_session: false,
+        })
+        .await?;
+
+        assert!(result.model.is_none());
+        assert_eq!(
+            result.model_fallback_message.as_deref(),
+            Some(format_no_models_available_message().as_str())
+        );
+        assert_eq!(
+            result.initial_active_tool_names,
+            vec!["read".to_owned(), "edit".to_owned(), "write".to_owned()]
+        );
+        assert_eq!(result.thinking_level, ModelThinkingLevel::Off);
+        assert!(result.allowed_tool_names.is_none());
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn from_services_forwards_session_start_event() -> TestResult {
+        let dir = tempfile::tempdir()?;
+        let cwd = dir.path().join("project");
+        let agent = dir.path().join("agent");
+        std::fs::create_dir_all(&cwd)?;
+        std::fs::create_dir_all(&agent)?;
+
+        let runtime = ModelRuntime::create_in_memory().await?;
+        let services = create_agent_session_services(CreateAgentSessionServicesOptions {
+            cwd,
+            agent_dir: Some(agent),
+            model_runtime: Some(runtime),
+            resource_loader_options: Some(ResourceLoaderServiceOptions {
+                no_extensions: true,
+                no_skills: true,
+                no_prompt_templates: true,
+                no_themes: true,
+                no_context_files: true,
+                ..ResourceLoaderServiceOptions::default()
+            }),
+            ..CreateAgentSessionServicesOptions::default()
+        })
+        .await?;
+
+        let event = crate::core::agent_session::SessionStartEvent {
+            reason: crate::core::agent_session::SessionStartReason::New,
+            previous_session_file: Some("prev.jsonl".to_owned()),
+        };
+        let result = create_agent_session_from_services(CreateAgentSessionFromServicesOptions {
+            services,
+            model: None,
+            thinking_level: None,
+            scoped_models: Vec::new(),
+            tools: None,
+            exclude_tools: None,
+            no_tools: None,
+            session_start_event: Some(event.clone()),
+            saved_session_model: None,
+            has_existing_session: false,
+        })
+        .await?;
+
+        assert_eq!(
+            result.session_start_event,
+            Some(event),
+            "replacement session-start metadata must survive services resolution"
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn no_tools_all_sets_empty_allowlist_builtin_leaves_none() -> TestResult {
+        let dir = tempfile::tempdir()?;
+        let cwd = dir.path().join("project");
+        let agent = dir.path().join("agent");
+        std::fs::create_dir_all(&cwd)?;
+        std::fs::create_dir_all(&agent)?;
+
+        let runtime = ModelRuntime::create_in_memory().await?;
+        let services = create_agent_session_services(CreateAgentSessionServicesOptions {
+            cwd: cwd.clone(),
+            agent_dir: Some(agent.clone()),
+            model_runtime: Some(runtime.clone()),
+            resource_loader_options: Some(ResourceLoaderServiceOptions {
+                no_extensions: true,
+                no_skills: true,
+                no_prompt_templates: true,
+                no_themes: true,
+                no_context_files: true,
+                ..ResourceLoaderServiceOptions::default()
+            }),
+            ..CreateAgentSessionServicesOptions::default()
+        })
+        .await?;
+
+        let all = create_agent_session_from_services(CreateAgentSessionFromServicesOptions {
+            services,
+            model: None,
+            thinking_level: None,
+            scoped_models: Vec::new(),
+            tools: None,
+            exclude_tools: None,
+            no_tools: Some(NoToolsMode::All),
+            session_start_event: None,
+            saved_session_model: None,
+            has_existing_session: false,
+        })
+        .await?;
+        assert_eq!(all.allowed_tool_names, Some(Vec::new()));
+        assert!(all.initial_active_tool_names.is_empty());
+
+        let runtime = ModelRuntime::create_in_memory().await?;
+        let services = create_agent_session_services(CreateAgentSessionServicesOptions {
+            cwd,
+            agent_dir: Some(agent),
+            model_runtime: Some(runtime),
+            resource_loader_options: Some(ResourceLoaderServiceOptions {
+                no_extensions: true,
+                no_skills: true,
+                no_prompt_templates: true,
+                no_themes: true,
+                no_context_files: true,
+                ..ResourceLoaderServiceOptions::default()
+            }),
+            ..CreateAgentSessionServicesOptions::default()
+        })
+        .await?;
+
+        let builtin = create_agent_session_from_services(CreateAgentSessionFromServicesOptions {
+            services,
+            model: None,
+            thinking_level: None,
+            scoped_models: Vec::new(),
+            tools: None,
+            exclude_tools: None,
+            no_tools: Some(NoToolsMode::Builtin),
+            session_start_event: None,
+            saved_session_model: None,
+            has_existing_session: false,
+        })
+        .await?;
+        assert!(builtin.allowed_tool_names.is_none());
+        assert!(builtin.initial_active_tool_names.is_empty());
+        Ok(())
+    }
+    #[tokio::test]
+    async fn trust_override_precedes_project_settings_load() -> TestResult {
+        for (trust_override, trusted) in [(None, false), (Some(false), false), (Some(true), true)] {
+            let dir = tempfile::tempdir()?;
+            let cwd = dir.path().join("project");
+            let agent = dir.path().join("agent");
+            std::fs::create_dir_all(cwd.join(".pi"))?;
+            std::fs::create_dir_all(&agent)?;
+            std::fs::write(agent.join("settings.json"), r#"{"theme":"global"}"#)?;
+            std::fs::write(
+                cwd.join(".pi").join("settings.json"),
+                r#"{"theme":"project"}"#,
+            )?;
+
+            let services = create_agent_session_services_with_trust(
+                CreateAgentSessionServicesOptions {
+                    cwd,
+                    agent_dir: Some(agent),
+                    model_runtime: Some(ModelRuntime::create_in_memory().await?),
+                    resource_loader_options: Some(ResourceLoaderServiceOptions {
+                        no_extensions: true,
+                        no_skills: true,
+                        no_prompt_templates: true,
+                        no_themes: true,
+                        no_context_files: true,
+                        ..Default::default()
+                    }),
+                    ..Default::default()
+                },
+                trust_override,
+            )
+            .await?;
+
+            assert_eq!(services.settings_manager().is_project_trusted(), trusted);
+            assert_eq!(
+                services.settings_manager().get_theme().as_deref(),
+                Some(if trusted { "project" } else { "global" })
+            );
+        }
+        Ok(())
+    }
+}