iron-core 0.1.38

//! High-level agent, connection, session, and streaming prompt APIs.

use crate::plugin::rich_output::{transcript_text as plugin_transcript_text, view as plugin_view};
use crate::{
    capability::{CapabilityBackend, CapabilityDescriptor, CapabilityId},
    config::{Config, ConfigStore},
    connection::{ClientChannel, IronConnection},
    context::handoff::{HandoffExporter, HandoffImporter},
    durable::{
        ContentBlock, DurableSession, DurableToolRecord, SessionId, StructuredMessage,
        TimelineEntry,
    },
    error::RuntimeError,
    profile::{
        default_identity_prompt, normalize_profile_name, AgentApproval, AgentProfile,
        AgentProfileEntry, AgentProfileId, AgentProfileProvider, ProfileLoadDiagnostic,
        ProfileLoadIssue, ProfileLoadReport, SkillFilter, ToolFilter, PROFILE_SCHEMA_VERSION,
    },
    provider_credential::domain::{ProviderAuthStatus, ProviderPromptContext, ProviderSlug},
    provider_credential::store::DynCredentialStore,
    runtime::{ConnectionId, IronRuntime},
    stored_prompt::{
        load_prompts, PromptLoadReport, StoredPrompt, StoredPromptEntry, StoredPromptRegistry,
    },
    tool::Tool,
};
use agent_client_protocol::schema::v1 as acp;
use futures::Stream;
use iron_providers::Provider;
use parking_lot::{Mutex, RwLock};
use std::{
    cell::RefCell,
    collections::HashMap,
    pin::Pin,
    rc::Rc,
    sync::Arc,
    task::{Context, Poll},
};

// Permission option ID constants to avoid magic strings
const PERMISSION_ALLOW_ONCE: &str = "allow_once";
const PERMISSION_REJECT_ONCE: &str = "reject_once";

/// Outcome of a prompt/turn.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PromptOutcome {
    /// The turn completed normally.
    EndTurn,
    /// The turn was cancelled by the user.
    Cancelled,
    /// The maximum number of turn requests was reached.
    MaxTurnRequests,
    /// The turn stopped for a reason not recognized by this core version.
    Unknown,
}

impl From<acp::StopReason> for PromptOutcome {
    fn from(reason: acp::StopReason) -> Self {
        match reason {
            acp::StopReason::EndTurn => PromptOutcome::EndTurn,
            acp::StopReason::Cancelled => PromptOutcome::Cancelled,
            acp::StopReason::MaxTurnRequests => PromptOutcome::MaxTurnRequests,
            acp::StopReason::MaxTokens | acp::StopReason::Refusal | _ => PromptOutcome::Unknown,
        }
    }
}

/// Verdict for a permission request.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PermissionVerdict {
    /// Allow this tool call to proceed.
    AllowOnce,
    /// Deny this tool call.
    Deny,
    /// Cancel the entire prompt.
    Cancel,
}

/// A request for user approval of a tool call.
#[derive(Debug, Clone)]
pub struct PermissionRequest {
    /// Unique identifier for this tool call.
    pub call_id: String,
    /// Name of the tool being called.
    pub tool_name: String,
    /// Arguments passed to the tool.
    pub arguments: serde_json::Value,
}

// ---------------------------------------------------------------------------
// Stream-first prompt event types
// ---------------------------------------------------------------------------

/// Events emitted during a streaming prompt session.
///
/// These events are produced by the [`PromptEvents`] stream returned from
/// [`AgentSession::prompt_stream`] and [`AgentSession::prompt_stream_with_blocks`].
/// They provide real-time visibility into the agent's progress, including model
/// output, tool calls, and user approval requests.
///
/// # Event Ordering
///
/// Events preserve runtime occurrence order and may interleave across inference
/// iterations. For a given tool, [`ToolCall`](PromptEvent::ToolCall) precedes an
/// optional [`ApprovalRequest`](PromptEvent::ApprovalRequest), which precedes
/// its terminal [`ToolResult`](PromptEvent::ToolResult). Compaction start events
/// precede their matching finish or failure event. A successful stream task
/// emits one [`Complete`](PromptEvent::Complete) event last.
///
/// # Example
///
/// ```no_run
/// use iron_core::{Config, IronAgent, PromptEvent};
/// use iron_providers::{ApiFamily, ProviderConnection, ProviderProfile, RuntimeConfig};
///
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// # let provider = ProviderConnection::from_profile(ProviderProfile::new("openai", ApiFamily::Responses, "https://api.openai.com/v1"), RuntimeConfig::new("sk-example"))?;
/// # let agent = IronAgent::new(Config::default(), provider);
/// # let session = agent.connect().create_session()?;
/// let (handle, mut events) = session.prompt_stream("Hello");
/// while let Some(event) = events.next().await {
///     match event {
///         PromptEvent::Output { text } => print!("{}", text),
///         PromptEvent::ApprovalRequest { call_id, tool_name, .. } => {
///             println!("\nTool {} requires approval", tool_name);
///             handle.approve(&call_id).unwrap();
///         }
///         PromptEvent::Complete { outcome } => break,
///         _ => {}
///     }
/// }
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Clone)]
pub enum PromptEvent {
    /// A status update from the agent.
    Status {
        /// The status message.
        message: String,
    },
    /// Text output from the language model.
    Output {
        /// The text content.
        text: String,
    },
    /// A tool call has been initiated.
    ToolCall {
        /// Unique identifier for this tool call.
        call_id: String,
        /// Name of the tool being called.
        tool_name: String,
        /// Arguments passed to the tool.
        arguments: serde_json::Value,
    },
    /// A tool call requires user approval.
    ApprovalRequest {
        /// Unique identifier for this tool call.
        call_id: String,
        /// Name of the tool being called.
        tool_name: String,
        /// Arguments passed to the tool.
        arguments: serde_json::Value,
    },
    /// A tool call has completed.
    ToolResult {
        /// Unique identifier for this tool call.
        call_id: String,
        /// Name of the tool that was called.
        tool_name: String,
        /// Status of the tool execution.
        status: ToolResultStatus,
        /// The result value (if successful).
        result: Option<serde_json::Value>,
        /// Normalized transcript-safe text for plugin rich output, when present.
        transcript_text: Option<String>,
        /// Normalized rich view payload for plugin rich output, when present.
        view: Option<serde_json::Value>,
    },
    /// Activity from an embedded Python script.
    ScriptActivity {
        /// Unique identifier for the script.
        script_id: String,
        /// The parent tool call that started the script.
        parent_call_id: String,
        /// Type of activity.
        activity_type: ScriptActivityType,
        /// Current status of the activity.
        status: ScriptActivityStatus,
        /// Additional details about the activity.
        detail: Option<serde_json::Value>,
    },
    /// An authentication state transition occurred for a plugin.
    ///
    /// Emitted when a plugin's auth state changes (e.g. from `Unauthenticated`
    /// to `Authenticating`, or from `Authenticating` to `Authenticated`).
    /// Clients can use this to update their auth UX without polling.
    AuthStateChange {
        /// The plugin whose auth state changed.
        auth_id: String,
        /// Previous auth state.
        previous_state: crate::plugin::auth::AuthState,
        /// New auth state.
        new_state: crate::plugin::auth::AuthState,
    },
    /// A model switch has been applied to the session.
    ///
    /// Emitted when a model switch completes, either immediately (for idle
    /// sessions) or at turn boundary (for queued switches).
    ModelSwitched {
        /// The model that was active before the switch.
        from_model: String,
        /// The model that is now active.
        to_model: String,
        /// Whether context was adapted during the switch.
        adapted: bool,
        /// Capability differences between the old and new models.
        capability_diff: crate::context::CapabilityDiff,
    },
    /// A model switch has been queued for the next turn boundary.
    ///
    /// Emitted when a switch is requested while the session has an active
    /// prompt. The switch will be applied when the current turn completes.
    ModelSwitchPending {
        /// The model that will become active after the switch.
        target_model: String,
        /// The provider slug for the target model (if managed).
        target_provider: Option<String>,
    },
    /// Context compaction has started.
    ///
    /// Emitted when the runtime begins compressing context, whether
    /// triggered by the compress tool or automatic adaptation.
    CompactionStarted {
        /// Correlation identifier for pairing with Finished/Failed events.
        compaction_id: String,
        /// Method when known at start time (e.g. "model_summary" or "auto_compaction").
        method: String,
    },
    /// Context compaction has finished.
    ///
    /// Emitted when compression completes successfully.
    CompactionFinished {
        /// Correlation identifier matching the preceding CompactionStarted event.
        compaction_id: String,
        /// Estimated tokens before compaction.
        tokens_before: Option<u32>,
        /// Estimated tokens after compaction.
        tokens_after: Option<u32>,
        /// Method used (e.g. "model_summary" or "auto_compaction").
        method: String,
    },
    /// Context compaction has failed.
    ///
    /// Emitted when compression could not be applied.
    CompactionFailed {
        /// Correlation identifier matching the preceding CompactionStarted event.
        compaction_id: String,
        /// Human-readable reason for the failure.
        reason: String,
    },
    /// The prompt has completed.
    Complete {
        /// The final outcome of the prompt.
        outcome: PromptOutcome,
    },
}

/// Types of activities that can occur during embedded Python script execution.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ScriptActivityType {
    /// The script has started.
    ScriptStarted,
    /// A phase update during script execution.
    ScriptPhase,
    /// The script has completed.
    ScriptCompleted,
    /// A child tool call started within the script.
    ChildToolCallStarted,
    /// A child tool call completed within the script.
    ChildToolCallCompleted,
    /// A child tool call failed within the script.
    ChildToolCallFailed,
}

/// Status of a script activity.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ScriptActivityStatus {
    /// The activity is currently running.
    Running,
    /// The activity completed successfully.
    Completed,
    /// The activity completed but with some failures.
    CompletedWithFailures,
    /// The activity failed.
    Failed,
    /// The activity was cancelled.
    Cancelled,
}

/// Status of a tool call result.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ToolResultStatus {
    /// The tool call completed successfully.
    Completed,
    /// The tool call failed.
    Failed,
    /// The tool call was denied by the user.
    Denied,
    /// The tool call was cancelled.
    Cancelled,
}

/// Status of an active prompt.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PromptStatus {
    /// The prompt is pending (not yet started).
    Pending,
    /// The prompt is currently running.
    Running,
    /// The prompt has completed.
    Completed,
    /// The prompt was cancelled.
    Cancelled,
}

/// Handle to control an active streaming prompt.
///
/// Returned by [`AgentSession::prompt_stream`] and
/// [`AgentSession::prompt_stream_with_blocks`], this handle allows you to
/// approve or deny tool calls that require permission, or cancel the entire
/// prompt.
///
/// # Example
///
/// ```no_run
/// use iron_core::{Config, IronAgent};
/// use iron_providers::{ApiFamily, ProviderConnection, ProviderProfile, RuntimeConfig};
///
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// # let provider = ProviderConnection::from_profile(ProviderProfile::new("openai", ApiFamily::Responses, "https://api.openai.com/v1"), RuntimeConfig::new("sk-example"))?;
/// # let agent = IronAgent::new(Config::default(), provider);
/// # let session = agent.connect().create_session()?;
/// let (handle, mut events) = session.prompt_stream("Hello");
///
/// // Later, when an approval request is received...
/// handle.approve("call-123").unwrap();
///
/// // Or cancel the entire prompt
/// handle.cancel().await;
/// # Ok(())
/// # }
/// ```
pub struct PromptHandle {
    approval_resolvers:
        Rc<RefCell<HashMap<String, tokio::sync::oneshot::Sender<PermissionVerdict>>>>,
    session: AgentSession,
    status: Rc<RefCell<PromptStatus>>,
}

impl PromptHandle {
    /// Approve a tool call that is waiting for permission.
    ///
    /// # Arguments
    ///
    /// * `call_id` - The unique identifier of the tool call to approve.
    ///
    /// # Errors
    ///
    /// Returns an error if no pending approval exists for the given `call_id`.
    pub fn approve(&self, call_id: &str) -> Result<(), String> {
        let mut resolvers = self.approval_resolvers.borrow_mut();
        match resolvers.remove(call_id) {
            Some(tx) => {
                let _ = tx.send(PermissionVerdict::AllowOnce);
                Ok(())
            }
            None => Err(format!("no pending approval for call_id: {}", call_id)),
        }
    }

    /// Deny a tool call that is waiting for permission.
    ///
    /// # Arguments
    ///
    /// * `call_id` - The unique identifier of the tool call to deny.
    ///
    /// # Errors
    ///
    /// Returns an error if no pending approval exists for the given `call_id`.
    pub fn deny(&self, call_id: &str) -> Result<(), String> {
        let mut resolvers = self.approval_resolvers.borrow_mut();
        match resolvers.remove(call_id) {
            Some(tx) => {
                let _ = tx.send(PermissionVerdict::Deny);
                Ok(())
            }
            None => Err(format!("no pending approval for call_id: {}", call_id)),
        }
    }

    /// Cancel the active prompt.
    ///
    /// This will stop any in-progress model inference and tool execution.
    /// All pending approvals will be resolved with a cancel verdict.
    pub async fn cancel(&self) {
        {
            let mut resolvers = self.approval_resolvers.borrow_mut();
            for (_, tx) in resolvers.drain() {
                let _ = tx.send(PermissionVerdict::Cancel);
            }
        }
        *self.status.borrow_mut() = PromptStatus::Cancelled;
        self.session.cancel().await;
    }

    /// Get the current status of the prompt.
    pub fn status(&self) -> PromptStatus {
        *self.status.borrow()
    }
}

impl std::fmt::Debug for PromptHandle {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PromptHandle")
            .field("status", &*self.status.borrow())
            .finish()
    }
}

/// Asynchronous event receiver for one streaming prompt.
///
/// Returned by [`AgentSession::prompt_stream`] and
/// [`AgentSession::prompt_stream_with_blocks`], this struct provides
/// asynchronous access to events emitted during a prompt session.
/// It implements [`Stream`] and can be polled for events.
///
/// # Example
///
/// ```no_run
/// use iron_core::{Config, IronAgent, PromptEvent};
/// use iron_providers::{ApiFamily, ProviderConnection, ProviderProfile, RuntimeConfig};
///
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// # let provider = ProviderConnection::from_profile(ProviderProfile::new("openai", ApiFamily::Responses, "https://api.openai.com/v1"), RuntimeConfig::new("sk-example"))?;
/// # let agent = IronAgent::new(Config::default(), provider);
/// # let session = agent.connect().create_session()?;
/// let (handle, mut events) = session.prompt_stream("Hello");
///
/// while let Some(event) = events.next().await {
///     match event {
///         PromptEvent::Output { text } => print!("{}", text),
///         PromptEvent::Complete { .. } => break,
///         _ => {}
///     }
/// }
/// # Ok(())
/// # }
/// ```
pub struct PromptEvents {
    rx: tokio::sync::mpsc::UnboundedReceiver<PromptEvent>,
}

impl PromptEvents {
    /// Wait for the next event from the stream.
    ///
    /// Returns `None` if the stream has ended.
    pub async fn next(&mut self) -> Option<PromptEvent> {
        self.rx.recv().await
    }

    /// Try to get the next event without blocking.
    ///
    /// Returns `None` if no event is available or if the stream has ended.
    pub fn try_next(&mut self) -> Option<PromptEvent> {
        self.rx.try_recv().ok()
    }

    /// Convert this into a [`Stream`] for use with stream combinators.
    pub fn into_stream(self) -> Pin<Box<dyn Stream<Item = PromptEvent>>> {
        Box::pin(self)
    }
}

impl Stream for PromptEvents {
    type Item = PromptEvent;

    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
        self.rx.poll_recv(cx)
    }
}

impl std::fmt::Debug for PromptEvents {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PromptEvents").finish()
    }
}

// ---------------------------------------------------------------------------
// Stream prompt state (internal)
// ---------------------------------------------------------------------------

struct StreamPromptState {
    event_tx: tokio::sync::mpsc::UnboundedSender<PromptEvent>,
    approval_resolvers:
        Rc<RefCell<HashMap<String, tokio::sync::oneshot::Sender<PermissionVerdict>>>>,
    tool_name_index: Rc<RefCell<HashMap<String, String>>>,
}

// ---------------------------------------------------------------------------
// Profile registry helpers
// ---------------------------------------------------------------------------

type ProfileRegistry = HashMap<AgentProfileId, AgentProfile>;

fn default_profile_registry() -> ProfileRegistry {
    let mut registry = HashMap::new();
    let default = AgentProfileEntry {
        id: AgentProfileId::from("default"),
        profile: AgentProfile {
            name: "default".to_string(),
            provider: AgentProfileProvider::RuntimeDefault,
            tools: ToolFilter::Inherit,
            skills: SkillFilter::Inherit,
            approval: AgentApproval::PerTool,
            identity_prompt: Some(default_identity_prompt().to_string()),
        },
    };
    registry.insert(default.id, default.profile);
    registry
}

// ---------------------------------------------------------------------------
// IronAgent
// ---------------------------------------------------------------------------

/// Top-level owner of the runtime and its profile and stored-prompt registries.
///
/// `IronAgent` is the top-level type for creating and managing agent connections.
/// It owns the runtime, provider, and tool registry. Use [`IronAgent::connect`]
/// to establish a connection and begin interacting with the agent.
///
/// # Example
///
/// ```no_run
/// use iron_core::{Config, FunctionTool, IronAgent};
/// use iron_providers::{ApiFamily, ProviderConnection, ProviderProfile, RuntimeConfig};
/// use serde_json::json;
///
/// let config = Config::default();
/// let provider = ProviderConnection::from_profile(
///     ProviderProfile::new("openai", ApiFamily::Responses, "https://api.openai.com/v1"),
///     RuntimeConfig::new("sk-example"),
/// )
/// .expect("provider config should be valid");
/// let agent = IronAgent::new(config, provider);
///
/// // Register custom tools
/// let ping = FunctionTool::simple("ping", "Return pong", |_| Ok(json!("pong")));
/// agent.register_tool(ping);
///
/// // Connect and create a session
/// let conn = agent.connect();
/// let session = conn.create_session().unwrap();
/// ```
pub struct IronAgent {
    runtime: IronRuntime,
    profile_registry: Arc<RwLock<ProfileRegistry>>,
    stored_prompt_registry: Arc<RwLock<StoredPromptRegistry>>,
}

impl IronAgent {
    /// Create a new agent with the given configuration and provider.
    ///
    /// This creates an agent with its own private Tokio runtime. For integration
    /// with an existing Tokio runtime, use [`IronAgent::with_tokio_handle`].
    pub fn new<P: Provider + 'static>(config: Config, provider: P) -> Self {
        let runtime = IronRuntime::new(config, provider);
        let profile_registry = Arc::new(RwLock::new(default_profile_registry()));
        let stored_prompt_registry = Arc::new(RwLock::new(StoredPromptRegistry::new()));
        runtime.set_profile_registry(profile_registry.clone());
        runtime.set_stored_prompt_registry(stored_prompt_registry.clone());
        Self {
            runtime,
            profile_registry,
            stored_prompt_registry,
        }
    }

    /// Create a new agent using an existing Tokio runtime handle.
    ///
    /// This is useful when integrating Iron into an existing async application
    /// that already manages its own Tokio runtime.
    pub fn with_tokio_handle<P: Provider + 'static>(
        config: Config,
        provider: P,
        handle: tokio::runtime::Handle,
    ) -> Self {
        let runtime = IronRuntime::from_handle(config, provider, handle);
        let profile_registry = Arc::new(RwLock::new(default_profile_registry()));
        let stored_prompt_registry = Arc::new(RwLock::new(StoredPromptRegistry::new()));
        runtime.set_profile_registry(profile_registry.clone());
        runtime.set_stored_prompt_registry(stored_prompt_registry.clone());
        Self {
            runtime,
            profile_registry,
            stored_prompt_registry,
        }
    }

    /// Create a new agent with a credential store for managed provider resolution.
    pub fn new_with_credential_store<P: Provider + 'static>(
        config: Config,
        provider: P,
        credential_store: DynCredentialStore,
    ) -> Self {
        let runtime = IronRuntime::new_with_credential_store(config, provider, credential_store);
        let profile_registry = Arc::new(RwLock::new(default_profile_registry()));
        let stored_prompt_registry = Arc::new(RwLock::new(StoredPromptRegistry::new()));
        runtime.set_profile_registry(profile_registry.clone());
        runtime.set_stored_prompt_registry(stored_prompt_registry.clone());
        Self {
            runtime,
            profile_registry,
            stored_prompt_registry,
        }
    }

    /// Get a reference to the underlying runtime.
    pub fn runtime(&self) -> &IronRuntime {
        &self.runtime
    }

    /// Set the debug observation sink for this agent.
    ///
    /// The sink receives typed debug events emitted at semantic runtime
    /// transitions. Setting `None` restores the default no-op sink.
    pub fn set_debug_sink(&self, sink: Option<Arc<dyn crate::debug::DebugSink>>) {
        self.runtime.set_debug_sink(sink);
    }

    /// Register a custom tool with the agent.
    ///
    /// Tools must implement the [`Tool`] trait. Once registered,
    /// the tool becomes available for the model to call during prompts.
    pub fn register_tool<T: Tool + 'static>(&self, tool: T) {
        self.runtime.register_tool(tool);
    }

    /// Register all built-in tools with the agent.
    ///
    /// Built-in tools include file operations (read, write, edit), shell commands,
    /// web fetching, and search capabilities. Use the config to control which
    /// tools are enabled.
    pub fn register_builtin_tools(&self, config: &crate::builtin::BuiltinToolConfig) {
        self.runtime.register_builtin_tools(config);
    }

    /// Register the Python execution tool (requires `embedded-python` feature).
    #[cfg(feature = "embedded-python")]
    pub fn register_python_exec_tool(&self) {
        self.runtime
            .register_tool(crate::embedded_python::PythonExecTool::new());
    }

    /// Register the `activate_skill` model-facing tool.
    pub fn register_activate_skill_tool(&self) {
        self.runtime.register_activate_skill_tool();
    }

    /// Get a reference to the Tokio runtime handle.
    pub fn tokio_handle(&self) -> &tokio::runtime::Handle {
        self.runtime.tokio_handle()
    }

    /// Register a capability with the agent.
    ///
    /// Capabilities extend the agent with additional functionality beyond tools.
    pub fn register_capability(&self, descriptor: CapabilityDescriptor) {
        self.runtime.register_capability(descriptor);
    }

    /// Set the backend implementation for a capability.
    pub fn set_capability_backend(&self, id: CapabilityId, backend: CapabilityBackend) {
        self.runtime.set_capability_backend(id, backend);
    }

    /// Register an MCP server with the agent.
    ///
    /// This adds a configured MCP server to the runtime inventory.
    /// Servers must be registered before they can be enabled for sessions.
    pub fn register_mcp_server(&self, config: crate::mcp::McpServerConfig) {
        self.runtime.register_mcp_server(config);
    }

    /// Get the MCP server registry for inspection.
    pub fn mcp_registry(&self) -> parking_lot::RwLockReadGuard<'_, crate::mcp::McpServerRegistry> {
        self.runtime.mcp_registry()
    }

    /// Register a plugin with the agent.
    ///
    /// This adds a configured plugin to the runtime inventory.
    /// Plugins must be registered before they can be enabled for sessions.
    pub fn register_plugin(&self, config: crate::plugin::config::PluginConfig) {
        self.runtime.register_plugin(config);
    }

    /// Get the plugin registry for inspection.
    pub fn plugin_registry(
        &self,
    ) -> parking_lot::RwLockReadGuard<'_, crate::plugin::registry::PluginRegistry> {
        self.runtime.plugin_registry()
    }

    /// Get effective tool definitions for a session, including MCP and plugin tools.
    pub fn get_effective_tools(&self, session_id: SessionId) -> Vec<crate::tool::ToolDefinition> {
        self.runtime.get_effective_tool_definitions(session_id)
    }

    /// Get a full inventory of all registered plugins.
    ///
    /// Returns a [`PluginInfo`](crate::plugin::status::PluginInfo) for every
    /// plugin in the registry.
    pub fn get_plugin_inventory(&self) -> Vec<crate::plugin::status::PluginInfo> {
        self.runtime.get_plugin_inventory()
    }

    /// Get auth prompts for all plugins that require authentication.
    ///
    /// Returns a list of [`AuthPrompt`](crate::plugin::auth::AuthPrompt)
    /// values for every registered plugin that declares OAuth requirements.
    /// Clients can use this to render auth UX without polling individual
    /// plugin statuses.
    pub fn get_auth_prompts(&self) -> Vec<crate::plugin::auth::AuthPrompt> {
        self.runtime.get_auth_prompts()
    }

    /// Get the runtime status of a single plugin.
    ///
    /// Returns `None` if the plugin is not registered.
    pub fn get_plugin_status(
        &self,
        plugin_id: &str,
    ) -> Option<crate::plugin::status::PluginStatus> {
        self.runtime.get_plugin_status(plugin_id)
    }

    /// Set credentials for a plugin and mark it as authenticated.
    pub fn set_plugin_credentials(
        &self,
        plugin_id: &str,
        credentials: crate::plugin::auth::CredentialBinding,
    ) {
        self.runtime.set_plugin_credentials(plugin_id, credentials);
    }

    /// Clear credentials for a plugin and reset its auth state.
    pub fn clear_plugin_credentials(&self, plugin_id: &str) {
        self.runtime.clear_plugin_credentials(plugin_id);
    }

    /// Start a direct client-initiated auth flow for a plugin.
    ///
    /// Returns an [`AuthInteractionRequest`](crate::plugin::auth::AuthInteractionRequest)
    /// that the client should act on (e.g. open a browser to the authorization URL).
    ///
    /// # Errors
    ///
    /// Returns an error if the plugin is not found, does not require auth,
    /// is already authenticating, or is already authenticated.
    pub fn start_auth_flow(
        &self,
        plugin_id: &str,
    ) -> Result<crate::plugin::auth::AuthInteractionRequest, String> {
        self.runtime.begin_plugin_auth_flow(plugin_id)
    }

    /// Complete a direct client-initiated auth flow for a plugin.
    ///
    /// Processes the client's response.  On success, stores credentials and
    /// transitions to `Authenticated`.  On denial, failure, or cancellation,
    /// transitions back to `Unauthenticated`.
    ///
    /// Returns the [`AuthStatusTransition`](crate::plugin::auth::AuthStatusTransition)
    /// describing the state change.
    ///
    /// # Errors
    ///
    /// Returns an error if the plugin is not found or is not in the
    /// `Authenticating` state.
    pub fn complete_auth_flow(
        &self,
        plugin_id: &str,
        response: crate::plugin::auth::AuthInteractionResponse,
    ) -> Result<crate::plugin::auth::AuthStatusTransition, String> {
        self.runtime.complete_plugin_auth_flow(plugin_id, response)
    }

    /// Get a recomputed availability summary for a single plugin.
    ///
    /// Returns `None` if the plugin is not registered.
    pub fn get_plugin_availability(
        &self,
        plugin_id: &str,
    ) -> Option<crate::plugin::registry::PluginAvailabilitySummary> {
        self.runtime.get_plugin_availability(plugin_id)
    }

    /// Get unified tool diagnostics for a session.
    ///
    /// Returns `None` if the session does not exist.
    pub fn get_session_tool_diagnostics(
        &self,
        session_id: SessionId,
    ) -> Option<Vec<crate::mcp::session_catalog::ToolDiagnostic>> {
        self.runtime.get_session_tool_diagnostics(session_id)
    }

    /// Return the built-in default profile entry.
    ///
    /// The default profile uses the runtime default provider, inherits tools
    /// and skills, requires per-tool approval, and provides a generic identity
    /// prompt.
    pub fn default_profile(&self) -> AgentProfileEntry {
        AgentProfileEntry {
            id: AgentProfileId::from("default"),
            profile: AgentProfile {
                name: "default".to_string(),
                provider: AgentProfileProvider::RuntimeDefault,
                tools: ToolFilter::Inherit,
                skills: SkillFilter::Inherit,
                approval: AgentApproval::PerTool,
                identity_prompt: Some(default_identity_prompt().to_string()),
            },
        }
    }

    /// Seed the three shipped default profiles (explore, plan, apply) into the
    /// given config store according to `policy`.
    ///
    /// Delegates to [`crate::profile::seed_default_profiles`].
    pub async fn seed_default_profiles(
        &self,
        store: &ConfigStore,
        policy: crate::profile::DefaultProfileSeedPolicy,
    ) -> Result<crate::profile::DefaultProfileSeedReport, crate::config::ConfigError> {
        crate::profile::seed_default_profiles(store, policy).await
    }

    /// Load persisted provider profiles from the config store into the runtime's
    /// effective provider registry.
    ///
    /// Built-in provider profiles are preserved; persisted profiles with the
    /// same slug override built-ins, and persisted profiles with new slugs are
    /// added. Credential resolver support maps are also updated.
    pub async fn load_provider_profiles(
        &self,
        store: &ConfigStore,
    ) -> Result<(), crate::config::ConfigError> {
        self.runtime.load_provider_profiles(store).await
    }

    /// Register or replace an agent profile by stable ID.
    ///
    /// Validates the profile name and rejects reserved `default` IDs/names.
    /// If the ID is already registered, the previous profile is replaced only
    /// when the replacement is valid and does not duplicate a name owned by
    /// another profile ID.
    pub fn register_profile(
        &self,
        id: AgentProfileId,
        profile: AgentProfile,
    ) -> Result<(), String> {
        if id.as_str().eq_ignore_ascii_case("default") {
            return Err("profile ID 'default' is reserved".to_string());
        }
        if !crate::profile::is_valid_profile_id(id.as_str()) {
            return Err(format!("invalid profile ID: '{}'", id.as_str()));
        }
        let name = normalize_profile_name(&profile.name)
            .ok_or_else(|| format!("invalid profile name: '{}'", profile.name))?;
        if name.eq_ignore_ascii_case("default") {
            return Err("profile name 'default' is reserved".to_string());
        }

        // Reject ReadOnly and RequireApproval at the registration boundary.
        if !matches!(
            profile.approval,
            AgentApproval::PerTool | AgentApproval::AutoApprove
        ) {
            return Err(format!(
                "invalid profile approval value: {:?}. Only PerTool and AutoApprove are supported.",
                profile.approval
            ));
        }

        let mut registry = self.profile_registry.write();

        // If replacing, the new name must not duplicate a name owned by a
        // different profile ID.
        let name_conflict = registry.iter().any(|(existing_id, existing_profile)| {
            existing_id.as_str() != id.as_str() && existing_profile.name == name
        });
        if name_conflict {
            return Err(format!(
                "profile name '{}' is already used by another profile",
                name
            ));
        }

        let mut profile = profile;
        profile.name = name;
        registry.insert(id, profile);
        Ok(())
    }

    /// Unregister a profile by stable ID.
    ///
    /// Returns `true` if a profile was removed. The built-in `default` profile
    /// cannot be unregistered.
    pub fn unregister_profile(&self, id: &AgentProfileId) -> bool {
        if id.as_str().eq_ignore_ascii_case("default") {
            return false;
        }
        self.profile_registry.write().remove(id).is_some()
    }

    /// List all registered profiles with deterministic ordering.
    ///
    /// Profiles are ordered by stable profile ID ascending. The built-in
    /// `default` profile is always included.
    pub fn list_profiles(&self) -> Vec<AgentProfileEntry> {
        let registry = self.profile_registry.read();
        let mut ids: Vec<&AgentProfileId> = registry.keys().collect();
        ids.sort_by(|a, b| a.as_str().cmp(b.as_str()));
        ids.into_iter()
            .map(|id| AgentProfileEntry {
                id: id.clone(),
                profile: registry[id].clone(),
            })
            .collect()
    }

    /// Load typed profiles from a `ConfigStore` and merge them into the registry.
    ///
    /// This is a best-effort operation: valid profiles are registered by their
    /// record ID, while invalid, reserved, or duplicate records are reported as
    /// per-profile diagnostics. Fatal store failures are returned as `Err`.
    /// Profiles not present in the store remain registered.
    pub async fn load_profiles(
        &self,
        store: &ConfigStore,
    ) -> Result<ProfileLoadReport, crate::config::ConfigError> {
        let record_ids = store.list_profile_ids().await?;

        // Sort IDs ascending for deterministic duplicate-name handling.
        let mut record_ids = record_ids;
        record_ids.sort();

        let mut report = ProfileLoadReport::empty();

        for record_id in record_ids {
            let record = match store.get_profile(&record_id).await? {
                Some(record) => record,
                None => {
                    report.diagnostics.push(ProfileLoadDiagnostic {
                        profile_id: AgentProfileId::from(record_id),
                        name: None,
                        issue: ProfileLoadIssue::MissingRecord,
                    });
                    continue;
                }
            };

            if record.schema_version != PROFILE_SCHEMA_VERSION {
                report.diagnostics.push(ProfileLoadDiagnostic {
                    profile_id: AgentProfileId::from(record.id.clone()),
                    name: None,
                    issue: ProfileLoadIssue::UnsupportedSchemaVersion {
                        version: record.schema_version,
                    },
                });
                continue;
            }

            let profile: AgentProfile = match serde_json::from_value(record.payload.clone()) {
                Ok(profile) => profile,
                Err(_) => {
                    report.diagnostics.push(ProfileLoadDiagnostic {
                        profile_id: AgentProfileId::from(record.id.clone()),
                        name: None,
                        issue: ProfileLoadIssue::InvalidPayload,
                    });
                    continue;
                }
            };

            let profile_id = AgentProfileId::from(record.id.clone());

            // Reject reserved default ID/name.
            if profile_id.as_str().eq_ignore_ascii_case("default")
                || profile.name.trim().eq_ignore_ascii_case("default")
            {
                report.diagnostics.push(ProfileLoadDiagnostic {
                    profile_id: profile_id.clone(),
                    name: Some(profile.name.clone()),
                    issue: ProfileLoadIssue::ReservedDefault,
                });
                continue;
            }

            // Reject invalid IDs before mutating.
            if !crate::profile::is_valid_profile_id(profile_id.as_str()) {
                report.diagnostics.push(ProfileLoadDiagnostic {
                    profile_id: profile_id.clone(),
                    name: Some(profile.name.clone()),
                    issue: ProfileLoadIssue::InvalidProfileId,
                });
                continue;
            }

            // Validate name. We intentionally do not normalize here because
            // `register_profile` normalizes; however, an invalid name must be
            // reported before any mutation.
            if normalize_profile_name(&profile.name).is_none() {
                report.diagnostics.push(ProfileLoadDiagnostic {
                    profile_id: profile_id.clone(),
                    name: Some(profile.name.clone()),
                    issue: ProfileLoadIssue::InvalidName,
                });
                continue;
            }

            // Existing registry entries win duplicate-name conflicts. Hold the
            // write lock for the entire check-and-insert so the conflict check
            // and insertion are atomic with respect to concurrent registrations.
            let mut registry = self.profile_registry.write();
            let normalized_name =
                normalize_profile_name(&profile.name).unwrap_or_else(|| profile.name.clone());
            let conflict = registry.iter().any(|(existing_id, existing_profile)| {
                existing_id.as_str() != profile_id.as_str()
                    && existing_profile.name == normalized_name
            });
            if conflict {
                report.diagnostics.push(ProfileLoadDiagnostic {
                    profile_id: profile_id.clone(),
                    name: Some(profile.name.clone()),
                    issue: ProfileLoadIssue::DuplicateName,
                });
                continue;
            }

            let mut profile = profile;
            profile.name = normalized_name;
            registry.insert(profile_id.clone(), profile.clone());
            report.loaded.push(AgentProfileEntry {
                id: profile_id,
                profile,
            });
        }

        Ok(report)
    }

    /// Look up a registered profile by stable ID.
    ///
    /// Returns `None` if the profile is not registered. The built-in `default`
    /// profile is always available.
    pub fn get_profile(&self, id: &AgentProfileId) -> Option<AgentProfileEntry> {
        self.profile_registry
            .read()
            .get(id)
            .map(|profile| AgentProfileEntry {
                id: id.clone(),
                profile: profile.clone(),
            })
    }

    /// Register or replace a stored prompt by stable ID.
    pub fn register_stored_prompt(
        &self,
        id: impl Into<String>,
        prompt: StoredPrompt,
    ) -> Result<(), String> {
        self.stored_prompt_registry
            .write()
            .register(id.into(), prompt)
    }

    /// Unregister a stored prompt by stable ID.
    pub fn unregister_stored_prompt(&self, id: &str) -> bool {
        self.stored_prompt_registry.write().unregister(id.trim())
    }

    /// Delete a stored prompt from both the runtime registry and ConfigStore.
    ///
    /// Returns `ConfigError::PromptReferencedByTasks` if one or more
    /// automation tasks reference this prompt. The prompt is removed from
    /// the in-memory registry only after the durable deletion succeeds.
    pub async fn delete_stored_prompt(
        &self,
        store: &ConfigStore,
        id: &str,
    ) -> Result<(), crate::config::ConfigError> {
        let normalized_id = id.trim();
        store.delete_prompt(normalized_id).await?;
        self.stored_prompt_registry
            .write()
            .unregister(normalized_id);
        Ok(())
    }

    /// List all registered stored prompts with deterministic ordering.
    pub fn list_stored_prompts(&self) -> Vec<StoredPromptEntry> {
        self.stored_prompt_registry.read().list()
    }

    /// Look up a registered stored prompt by stable ID.
    pub fn get_stored_prompt(&self, id: &str) -> Option<StoredPromptEntry> {
        let normalized_id = id.trim();
        self.stored_prompt_registry
            .read()
            .get(normalized_id)
            .cloned()
            .map(|prompt| StoredPromptEntry {
                id: normalized_id.to_string(),
                prompt,
                identity_state: crate::stored_prompt::IdentityState::Ready,
            })
    }

    /// Load typed stored prompts from a `ConfigStore` into the registry.
    pub async fn load_stored_prompts(
        &self,
        store: &ConfigStore,
    ) -> Result<PromptLoadReport, crate::config::ConfigError> {
        let report = load_prompts(store).await?;
        let mut registry = self.stored_prompt_registry.write();
        for entry in &report.loaded {
            registry
                .register(entry.id.clone(), entry.prompt.clone())
                .map_err(crate::config::ConfigError::Validation)?;
        }
        Ok(report)
    }

    /// Establish a new connection to the agent.
    ///
    /// Returns an [`AgentConnection`] which can be used to create sessions
    /// and interact with the agent. Multiple connections can exist simultaneously.
    pub fn connect(&self) -> AgentConnection {
        AgentConnection::new(self.runtime.clone(), self.profile_registry.clone())
    }

    /// Shut down the agent runtime.
    ///
    /// This will cancel all active prompts and close all connections.
    /// After shutdown, no new connections can be established.
    pub fn shutdown(&self) {
        self.runtime.shutdown();
    }
}

impl Clone for IronAgent {
    fn clone(&self) -> Self {
        Self {
            runtime: self.runtime.clone(),
            profile_registry: self.profile_registry.clone(),
            stored_prompt_registry: self.stored_prompt_registry.clone(),
        }
    }
}

// ---------------------------------------------------------------------------
// AgentConnection
// ---------------------------------------------------------------------------

type AsyncPermissionHandler =
    Box<dyn Fn(PermissionRequest) -> Pin<Box<dyn std::future::Future<Output = PermissionVerdict>>>>;

type SyncPermissionHandler = Rc<RefCell<Option<Box<dyn Fn(&str) -> PermissionVerdict>>>>;

/// Inspectable metadata for a hidden runtime session.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HiddenSessionInfo {
    /// Identifier of the hidden session.
    pub session_id: SessionId,
    /// Connection that directly owns the hidden session.
    pub connection_id: ConnectionId,
    /// Parent session for delegated work, when registered.
    pub parent_session_id: Option<SessionId>,
}

/// Connection-scoped owner for sessions, events, and permission callbacks.
///
/// Connections are the primary interface for creating and managing sessions.
/// Each connection has its own event queue and can set up permission handlers
/// for tool approval. Multiple connections can coexist, each with their own
/// set of sessions.
///
/// # Session Ownership
///
/// Sessions created through a connection are owned by that connection. Only
/// the owning connection can prompt, cancel, or close its sessions. This is
/// enforced at the runtime level.
///
/// # Example
///
/// ```no_run
/// use iron_core::{Config, IronAgent, PermissionVerdict};
/// use iron_providers::{ApiFamily, ProviderConnection, ProviderProfile, RuntimeConfig};
///
/// # let provider = ProviderConnection::from_profile(ProviderProfile::new("openai", ApiFamily::Responses, "https://api.openai.com/v1"), RuntimeConfig::new("sk-example")).unwrap();
/// # let agent = IronAgent::new(Config::default(), provider);
/// let conn = agent.connect();
///
/// // Set up a permission handler
/// conn.on_permission(|call_id| {
///     println!("Tool call {} requires approval", call_id);
///     PermissionVerdict::AllowOnce
/// });
///
/// // Create a session
/// let session = conn.create_session().unwrap();
/// ```
pub struct AgentConnection {
    inner: Rc<IronConnection>,
    permission_handler: SyncPermissionHandler,
    async_permission_handler: Rc<RefCell<Option<AsyncPermissionHandler>>>,
    active_streams: Rc<RefCell<HashMap<String, StreamPromptState>>>,
}

impl AgentConnection {
    fn emit_auth_transition_to_all_streams(
        &self,
        auth_id: &str,
        previous_state: crate::plugin::auth::AuthState,
        new_state: crate::plugin::auth::AuthState,
    ) {
        let streams = self.active_streams.borrow();
        for (_, state) in streams.iter() {
            let _ = state.event_tx.send(PromptEvent::AuthStateChange {
                auth_id: auth_id.to_string(),
                previous_state,
                new_state,
            });
        }
    }

    fn new(runtime: IronRuntime, profile_registry: Arc<RwLock<ProfileRegistry>>) -> Self {
        let inner = Rc::new(IronConnection::new_with_profile_registry(
            runtime,
            profile_registry,
        ));
        let permission_handler = Rc::new(RefCell::new(None));
        let async_permission_handler = Rc::new(RefCell::new(None));
        let active_streams = Rc::new(RefCell::new(HashMap::new()));

        let client: Rc<dyn ClientChannel> = Rc::new(FacadeClientChannel {
            permission_handler: permission_handler.clone(),
            async_permission_handler: async_permission_handler.clone(),
            active_streams: active_streams.clone(),
        });
        inner.set_client(client);

        Self {
            inner,
            permission_handler,
            async_permission_handler,
            active_streams,
        }
    }

    /// Get the unique identifier for this connection.
    pub fn id(&self) -> ConnectionId {
        self.inner.id()
    }

    /// Set a synchronous permission handler for tool approval.
    ///
    /// The handler receives the call ID and should return a [`PermissionVerdict`].
    /// This is called when a tool requiring approval is invoked.
    pub fn on_permission(&self, handler: impl Fn(&str) -> PermissionVerdict + 'static) {
        *self.permission_handler.borrow_mut() = Some(Box::new(handler));
    }

    /// Set an asynchronous permission handler for tool approval.
    ///
    /// The handler receives a [`PermissionRequest`] and returns a future that
    /// resolves to a [`PermissionVerdict`]. This is useful when approval
    /// requires user interaction or external confirmation.
    pub fn on_permission_async(
        &self,
        handler: impl Fn(PermissionRequest) -> Pin<Box<dyn std::future::Future<Output = PermissionVerdict>>>
            + 'static,
    ) {
        *self.async_permission_handler.borrow_mut() = Some(Box::new(handler));
    }

    /// Create a new session on this connection.
    ///
    /// Returns an [`AgentSession`] which can be used to send prompts and
    /// receive responses. Each session maintains its own conversation history.
    ///
    /// # Errors
    ///
    /// Returns an error if the runtime has been shut down.
    pub fn create_session(&self) -> Result<AgentSession, RuntimeError> {
        let connection_id = self.inner.id();
        let (session_id, durable) = self.inner.runtime().create_session(connection_id)?;
        Ok(AgentSession {
            id: session_id,
            durable,
            connection: self.inner.clone(),
            active_streams: self.active_streams.clone(),
            profile_id: None,
        })
    }

    /// Create a new session with an explicit profile.
    ///
    /// The selected profile ID is resolved against the agent's profile registry
    /// at session creation time. If the profile is not found, the method returns
    /// an error and no session is allocated. The resolved profile policy is
    /// snapshotted into the session immediately so later edits or deletion of
    /// the stored profile do not affect this session.
    ///
    /// # Errors
    ///
    /// Returns an error if the profile is not found in the registry or if the
    /// runtime has been shut down.
    pub fn create_session_with_profile(
        &self,
        profile_id: AgentProfileId,
    ) -> Result<AgentSession, RuntimeError> {
        // Validate profile exists in registry BEFORE creating the session,
        // to avoid leaving an orphaned session on error.
        let selected_profile = {
            let registry = self.inner.profile_registry().read();
            registry
                .get(&profile_id)
                .cloned()
                .ok_or_else(|| RuntimeError::Session {
                    message: format!("Profile '{}' not found in registry", profile_id.as_str()),
                })?
        };

        let connection_id = self.inner.id();
        let (session_id, durable) = self.inner.runtime().create_session(connection_id)?;

        // Snapshot effective policy into the DurableSession so later
        // edits/deletion of the stored profile do not affect this session.
        {
            let mut session = durable.lock();
            session.profile_id = Some(profile_id.clone());
            session.effective_tool_filter = Some(selected_profile.tools.clone());
            session.effective_approval = Some(selected_profile.approval);
            if let Some(ref identity) = selected_profile.identity_prompt {
                if !identity.trim().is_empty() {
                    session.set_profile_identity(identity.clone());
                }
            }
        }

        Ok(AgentSession {
            id: session_id,
            durable,
            connection: self.inner.clone(),
            active_streams: self.active_streams.clone(),
            profile_id: Some(profile_id),
        })
    }

    /// Close a session, releasing its resources.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is not owned by this connection.
    pub fn close_session(&self, session: &AgentSession) -> Result<(), RuntimeError> {
        let owner = self.inner.runtime().get_session_connection(session.id);
        if owner != Some(self.inner.id()) {
            return Err(RuntimeError::Connection(
                "session not owned by this connection".into(),
            ));
        }
        self.inner.runtime().close_session(session.id);
        Ok(())
    }

    /// Get the list of active session IDs on this connection.
    ///
    /// Hidden sessions are excluded from this list by default.
    pub fn active_sessions(&self) -> Vec<SessionId> {
        self.inner
            .runtime()
            .sessions_for_connection(self.inner.id(), false)
    }

    /// Get all active session IDs on this connection, including hidden sessions.
    pub fn active_sessions_include_hidden(&self) -> Vec<SessionId> {
        self.inner
            .runtime()
            .sessions_for_connection(self.inner.id(), true)
    }

    /// List hidden sessions visible to this connection for inspection.
    ///
    /// Includes hidden sessions directly owned by this connection and hidden
    /// child sessions whose parent session is owned by this connection.
    pub fn hidden_sessions(&self) -> Vec<HiddenSessionInfo> {
        let runtime = self.inner.runtime();
        let connection_id = self.inner.id();
        runtime
            .list_hidden_sessions()
            .into_iter()
            .filter(|(_, child_connection_id, parent_session_id)| {
                *child_connection_id == connection_id
                    || parent_session_id.and_then(|parent| runtime.get_session_connection(parent))
                        == Some(connection_id)
            })
            .map(
                |(session_id, connection_id, parent_session_id)| HiddenSessionInfo {
                    session_id,
                    connection_id,
                    parent_session_id,
                },
            )
            .collect()
    }

    /// List child sessions registered under a parent session owned by this connection.
    pub fn child_sessions(&self, parent: &AgentSession) -> Result<Vec<SessionId>, RuntimeError> {
        let owner = self.inner.runtime().get_session_connection(parent.id);
        if owner != Some(self.inner.id()) {
            return Err(RuntimeError::Connection(
                "session not owned by this connection".into(),
            ));
        }
        Ok(self.inner.runtime().list_child_sessions(parent.id))
    }

    /// Start a direct client-initiated auth flow for a plugin.
    ///
    /// Returns an [`AuthInteractionRequest`](crate::plugin::auth::AuthInteractionRequest)
    /// that the client should act on (e.g. open a browser to the authorization URL).
    /// This does not require model mediation — the client triggers the flow directly.
    ///
    /// # Errors
    ///
    /// Returns an error if the plugin is not found, does not require auth,
    /// is already authenticating, or is already authenticated.
    pub fn start_auth_flow(
        &self,
        plugin_id: &str,
    ) -> Result<crate::plugin::auth::AuthInteractionRequest, String> {
        let previous_state = self
            .inner
            .runtime()
            .get_plugin_status(plugin_id)
            .map(|status| status.auth.state)
            .unwrap_or(crate::plugin::auth::AuthState::Unauthenticated);
        let request = self.inner.runtime().begin_plugin_auth_flow(plugin_id)?;
        self.emit_auth_transition_to_all_streams(
            plugin_id,
            previous_state,
            crate::plugin::auth::AuthState::Authenticating,
        );
        Ok(request)
    }

    /// Complete a direct client-initiated auth flow for a plugin.
    ///
    /// Processes the client's response.  On success, stores credentials and
    /// transitions to `Authenticated`.  On denial, failure, or cancellation,
    /// transitions back to `Unauthenticated`.
    ///
    /// Returns the [`AuthStatusTransition`](crate::plugin::auth::AuthStatusTransition)
    /// describing the state change.
    ///
    /// # Errors
    ///
    /// Returns an error if the plugin is not found or is not in the
    /// `Authenticating` state.
    pub fn complete_auth_flow(
        &self,
        plugin_id: &str,
        response: crate::plugin::auth::AuthInteractionResponse,
    ) -> Result<crate::plugin::auth::AuthStatusTransition, String> {
        let transition = self
            .inner
            .runtime()
            .complete_plugin_auth_flow(plugin_id, response)?;
        self.emit_auth_transition_to_all_streams(
            &transition.auth_id,
            transition.previous_state,
            transition.new_state,
        );
        Ok(transition)
    }

    /// Get auth prompts for all plugins that require authentication.
    ///
    /// Returns a list of [`AuthPrompt`](crate::plugin::auth::AuthPrompt)
    /// values for every registered plugin that declares OAuth requirements.
    pub fn get_auth_prompts(&self) -> Vec<crate::plugin::auth::AuthPrompt> {
        self.inner.runtime().get_auth_prompts()
    }

    /// Create a new session from a handoff bundle.
    ///
    /// This restores a session that was previously exported via
    /// [`AgentSession::export_handoff`]. The session will have the
    /// conversation history and context from the bundle.
    ///
    /// # Errors
    ///
    /// Returns an error if the runtime has been shut down or if the
    /// session ID conflicts with an existing session.
    pub fn create_session_from_handoff(
        &self,
        bundle: crate::context::HandoffBundle,
    ) -> Result<AgentSession, RuntimeError> {
        let connection_id = self.inner.id();
        let durable = crate::context::HandoffImporter::hydrate_into_new(bundle);
        let session_id = durable.id;

        self.inner
            .runtime()
            .insert_session(session_id, durable, connection_id)?;

        let durable = self
            .inner
            .runtime()
            .get_session(session_id)
            .ok_or_else(|| RuntimeError::Connection("Failed to retrieve created session".into()))?;

        Ok(AgentSession {
            id: session_id,
            durable,
            connection: self.inner.clone(),
            active_streams: self.active_streams.clone(),
            profile_id: None,
        })
    }
}

// ---------------------------------------------------------------------------
// FacadeClientChannel (routes ACP notifications and permission requests)
// ---------------------------------------------------------------------------

struct FacadeClientChannel {
    permission_handler: SyncPermissionHandler,
    async_permission_handler: Rc<RefCell<Option<AsyncPermissionHandler>>>,
    active_streams: Rc<RefCell<HashMap<String, StreamPromptState>>>,
}

impl FacadeClientChannel {
    fn emit_stream_event(&self, event: PromptEvent) {
        let streams = self.active_streams.borrow();
        for (_, state) in streams.iter() {
            let _ = state.event_tx.send(event.clone());
        }
    }
}

impl ClientChannel for FacadeClientChannel {
    fn send_notification(
        &self,
        notification: acp::SessionNotification,
    ) -> Pin<Box<dyn std::future::Future<Output = agent_client_protocol::Result<()>>>> {
        let session_key = notification.session_id.to_string();
        let streams = self.active_streams.borrow();
        if let Some(state) = streams.get(&session_key) {
            if let Some(prompt_event) = convert_notification_to_prompt_event_with_index(
                &notification,
                &state.tool_name_index,
            ) {
                let _ = state.event_tx.send(prompt_event);
            }
        }
        drop(streams);
        Box::pin(async { Ok(()) })
    }

    fn emit_script_activity(
        &self,
        script_id: &str,
        parent_call_id: &str,
        activity_type: &str,
        status: &str,
        detail: Option<serde_json::Value>,
    ) -> Pin<Box<dyn std::future::Future<Output = ()>>> {
        let activity = match activity_type {
            "script_started" => ScriptActivityType::ScriptStarted,
            "script_phase" => ScriptActivityType::ScriptPhase,
            "script_completed" => ScriptActivityType::ScriptCompleted,
            "child_tool_call_started" => ScriptActivityType::ChildToolCallStarted,
            "child_tool_call_completed" => ScriptActivityType::ChildToolCallCompleted,
            "child_tool_call_failed" => ScriptActivityType::ChildToolCallFailed,
            _ => return Box::pin(async {}),
        };
        let act_status = match status {
            "running" => ScriptActivityStatus::Running,
            "completed" => ScriptActivityStatus::Completed,
            "completed_with_failures" => ScriptActivityStatus::CompletedWithFailures,
            "failed" => ScriptActivityStatus::Failed,
            "cancelled" => ScriptActivityStatus::Cancelled,
            _ => return Box::pin(async {}),
        };
        self.emit_stream_event(PromptEvent::ScriptActivity {
            script_id: script_id.to_string(),
            parent_call_id: parent_call_id.to_string(),
            activity_type: activity,
            status: act_status,
            detail,
        });
        Box::pin(async {})
    }

    fn emit_compaction_event(
        &self,
        event_type: &str,
        tokens_before: Option<u32>,
        tokens_after: Option<u32>,
        method: &str,
        reason: Option<&str>,
        compaction_id: &str,
    ) -> Pin<Box<dyn std::future::Future<Output = ()>>> {
        let event = match event_type {
            "started" => Some(PromptEvent::CompactionStarted {
                compaction_id: compaction_id.to_string(),
                method: method.to_string(),
            }),
            "finished" => Some(PromptEvent::CompactionFinished {
                compaction_id: compaction_id.to_string(),
                tokens_before,
                tokens_after,
                method: method.to_string(),
            }),
            "failed" => reason.map(|r| PromptEvent::CompactionFailed {
                compaction_id: compaction_id.to_string(),
                reason: r.to_string(),
            }),
            _ => None,
        };
        if let Some(evt) = event {
            self.emit_stream_event(evt);
        }
        Box::pin(async {})
    }

    fn request_permission(
        &self,
        request: acp::RequestPermissionRequest,
    ) -> Pin<
        Box<
            dyn std::future::Future<
                Output = agent_client_protocol::Result<acp::RequestPermissionResponse>,
            >,
        >,
    > {
        let call_id = request.tool_call.tool_call_id.to_string();
        let tool_name = request.tool_call.fields.title.clone().unwrap_or_default();
        let arguments = request
            .tool_call
            .fields
            .raw_input
            .clone()
            .unwrap_or_default();

        let session_key = request.session_id.to_string();
        let stream_state = self.active_streams.borrow();
        if let Some(state) = stream_state.get(&session_key) {
            let (tx, rx) = tokio::sync::oneshot::channel();
            state
                .approval_resolvers
                .borrow_mut()
                .insert(call_id.clone(), tx);

            let event_tx = state.event_tx.clone();
            drop(stream_state);

            return Box::pin(async move {
                let _ = event_tx.send(PromptEvent::ApprovalRequest {
                    call_id,
                    tool_name,
                    arguments,
                });
                match rx.await {
                    Ok(verdict) => Ok(acp::RequestPermissionResponse::new(verdict_to_outcome(
                        verdict,
                    ))),
                    Err(_) => Ok(acp::RequestPermissionResponse::new(verdict_to_outcome(
                        PermissionVerdict::Deny,
                    ))),
                }
            });
        }
        drop(stream_state);

        let async_handler = self.async_permission_handler.borrow();
        if let Some(ref handler) = *async_handler {
            let perm_req = PermissionRequest {
                call_id,
                tool_name,
                arguments,
            };
            let future = handler(perm_req);
            drop(async_handler);
            return Box::pin(async move {
                let verdict = future.await;
                Ok(acp::RequestPermissionResponse::new(verdict_to_outcome(
                    verdict,
                )))
            });
        }
        drop(async_handler);

        let handler = self.permission_handler.borrow();
        let verdict = handler
            .as_ref()
            .map(|h| h(&call_id))
            .unwrap_or(PermissionVerdict::AllowOnce);
        drop(handler);

        Box::pin(async move {
            Ok(acp::RequestPermissionResponse::new(verdict_to_outcome(
                verdict,
            )))
        })
    }
}

fn verdict_to_outcome(verdict: PermissionVerdict) -> acp::RequestPermissionOutcome {
    match verdict {
        PermissionVerdict::AllowOnce => {
            acp::RequestPermissionOutcome::Selected(acp::SelectedPermissionOutcome::new(
                acp::PermissionOptionId::new(PERMISSION_ALLOW_ONCE),
            ))
        }
        PermissionVerdict::Deny => {
            acp::RequestPermissionOutcome::Selected(acp::SelectedPermissionOutcome::new(
                acp::PermissionOptionId::new(PERMISSION_REJECT_ONCE),
            ))
        }
        PermissionVerdict::Cancel => acp::RequestPermissionOutcome::Cancelled,
    }
}

fn convert_notification_to_prompt_event_with_index(
    notification: &acp::SessionNotification,
    tool_name_index: &Rc<RefCell<HashMap<String, String>>>,
) -> Option<PromptEvent> {
    match &notification.update {
        acp::SessionUpdate::AgentMessageChunk(chunk) => match &chunk.content {
            acp::ContentBlock::Text(tc) => Some(PromptEvent::Output {
                text: tc.text.clone(),
            }),
            _ => None,
        },
        acp::SessionUpdate::ToolCall(tc) => {
            let call_id = tc.tool_call_id.to_string();
            let tool_name = tc.title.clone();
            let arguments = tc.raw_input.clone().unwrap_or_default();
            tool_name_index
                .borrow_mut()
                .insert(call_id.clone(), tool_name.clone());
            Some(PromptEvent::ToolCall {
                call_id,
                tool_name,
                arguments,
            })
        }
        acp::SessionUpdate::ToolCallUpdate(update) => {
            let call_id = update.tool_call_id.to_string();
            let tool_name = update
                .fields
                .title
                .clone()
                .or_else(|| tool_name_index.borrow().get(&call_id).cloned())
                .unwrap_or_default();
            let result = update.fields.raw_output.clone();
            let transcript_text = result
                .as_ref()
                .and_then(plugin_transcript_text)
                .map(str::to_string);
            let view = result.as_ref().and_then(plugin_view).cloned();
            let status = match update.fields.status {
                Some(acp::ToolCallStatus::Completed) => ToolResultStatus::Completed,
                Some(acp::ToolCallStatus::Failed) => {
                    let is_denied = result.as_ref().is_some_and(|r| {
                        r.get("error")
                            .and_then(|v| v.as_str())
                            .is_some_and(|s| s.contains("denied"))
                    });
                    if is_denied {
                        ToolResultStatus::Denied
                    } else {
                        ToolResultStatus::Failed
                    }
                }
                Some(acp::ToolCallStatus::Pending) => {
                    return None;
                }
                Some(acp::ToolCallStatus::InProgress) => {
                    return None;
                }
                _ => return None,
            };
            Some(PromptEvent::ToolResult {
                call_id,
                tool_name,
                status,
                result,
                transcript_text,
                view,
            })
        }
        _ => None,
    }
}

// ---------------------------------------------------------------------------
// AgentSession
// ---------------------------------------------------------------------------

/// Connection-owned handle to one durable conversation and its active prompt.
///
/// Sessions maintain conversation history and context. Each session is owned
/// by the connection that created it. Use the session to send prompts and
/// receive responses from the agent.
///
/// # Prompt Methods
///
/// Two streaming methods are available for sending prompts:
///
/// - [`prompt_stream`](AgentSession::prompt_stream) - Streaming text-only
///   method. Returns a stream of events and a handle for real-time interaction.
///   This is a convenience wrapper over the shared streaming path.
///
/// - [`prompt_stream_with_blocks`](AgentSession::prompt_stream_with_blocks) -
///   Streaming multimodal method. Accepts structured [`ContentBlock`] values
///   (text, images, resources) and returns the same
///   `(PromptHandle, PromptEvents)` contract. This is the preferred method for
///   interactive applications that need multimodal input.
///
/// # Example
///
/// ```no_run
/// use iron_core::{Config, ContentBlock, IronAgent, PromptEvent};
/// use iron_providers::{ApiFamily, ProviderConnection, ProviderProfile, RuntimeConfig};
///
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// # let provider = ProviderConnection::from_profile(ProviderProfile::new("openai", ApiFamily::Responses, "https://api.openai.com/v1"), RuntimeConfig::new("sk-example"))?;
/// # let agent = IronAgent::new(Config::default(), provider);
/// # let conn = agent.connect();
/// let session = conn.create_session().unwrap();
///
/// // Using the streaming API (text-only convenience)
/// let (handle, mut events) = session.prompt_stream("Hello again");
/// while let Some(event) = events.next().await {
///     match event {
///         PromptEvent::Output { text } => print!("{}", text),
///         PromptEvent::Complete { outcome } => break,
///         _ => {}
///     }
/// }
///
/// // Using the streaming API (multimodal)
/// let blocks = vec![
///     ContentBlock::text("Describe this image:"),
///     ContentBlock::Image { data: "base64-data".into(), mime_type: "image/png".into() },
/// ];
/// let (handle, mut events) = session.prompt_stream_with_blocks(&blocks);
/// while let Some(event) = events.next().await {
///     match event {
///         PromptEvent::Output { text } => print!("{}", text),
///         PromptEvent::Complete { .. } => break,
///         _ => {}
///     }
/// }
/// # Ok(())
/// # }
/// ```
pub struct AgentSession {
    id: SessionId,
    durable: Arc<Mutex<DurableSession>>,
    connection: Rc<IronConnection>,
    active_streams: Rc<RefCell<HashMap<String, StreamPromptState>>>,
    profile_id: Option<AgentProfileId>,
}

impl AgentSession {
    fn emit_auth_transition_to_stream(
        &self,
        auth_id: &str,
        previous_state: crate::plugin::auth::AuthState,
        new_state: crate::plugin::auth::AuthState,
    ) {
        let session_key = self.id.to_string();
        let streams = self.active_streams.borrow();
        if let Some(state) = streams.get(&session_key) {
            let _ = state.event_tx.send(PromptEvent::AuthStateChange {
                auth_id: auth_id.to_string(),
                previous_state,
                new_state,
            });
        }
    }

    fn emit_model_switch_event(&self, event: PromptEvent) {
        let session_key = self.id.to_string();
        let streams = self.active_streams.borrow();
        if let Some(state) = streams.get(&session_key) {
            let _ = state.event_tx.send(event);
        }
    }

    /// Get the unique identifier for this session.
    pub fn id(&self) -> SessionId {
        self.id
    }

    /// Send a text prompt and await completion.
    ///
    /// Returns the terminal [`PromptOutcome`]. For incremental event access,
    /// use [`prompt_stream`](AgentSession::prompt_stream).
    pub async fn prompt(&self, text: &str) -> PromptOutcome {
        self.try_prompt(text)
            .await
            .unwrap_or(PromptOutcome::EndTurn)
    }

    /// Send a text prompt and await completion, returning errors instead of
    /// swallowing them.
    ///
    /// Unlike [`prompt`](AgentSession::prompt), this method surfaces
    /// connection-level errors as `Err`. After the prompt completes, callers
    /// should also check [`profile_unavailable`](AgentSession::profile_unavailable)
    /// to detect injected provider/auth errors that the runtime converts to
    /// successful-lookahead completions with error text.
    pub async fn try_prompt(&self, text: &str) -> Result<PromptOutcome, String> {
        let acp_session_id = acp::SessionId::new(self.id.to_string());
        let request = acp::PromptRequest::new(
            acp_session_id,
            vec![acp::ContentBlock::Text(acp::TextContent::new(text))],
        );
        match self
            .connection
            .handle_prompt(request, self.profile_id.as_ref())
            .await
        {
            Ok(response) => Ok(response.stop_reason.into()),
            Err(e) => Err(format!("prompt failed: {}", e)),
        }
    }

    /// Returns the profile-unavailable diagnostic if the runtime injected a
    /// provider/auth error during the last prompt.
    ///
    /// When `Some`, the prompt technically completed but the output contains
    /// injected error text rather than a genuine model response.
    pub fn profile_unavailable(&self) -> Option<String> {
        self.durable.lock().profile_unavailable.clone()
    }

    /// Send a multimodal prompt and await completion.
    pub async fn prompt_with_blocks(&self, blocks: &[ContentBlock]) -> PromptOutcome {
        let acp_session_id = acp::SessionId::new(self.id.to_string());
        let acp_blocks: Vec<_> = blocks.iter().map(to_acp_content_block).collect();
        let request = acp::PromptRequest::new(acp_session_id, acp_blocks);
        match self
            .connection
            .handle_prompt(request, self.profile_id.as_ref())
            .await
        {
            Ok(response) => response.stop_reason.into(),
            Err(_) => PromptOutcome::EndTurn,
        }
    }

    /// Send a text prompt with a managed provider and await completion.
    ///
    /// The managed path resolves credentials from the credential store (or uses
    /// the API key from `provider_context.api_key`) and retries once on auth
    /// errors after refreshing the stored OAuth token.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use iron_core::{Config, IronAgent};
    /// use iron_core::provider_credential::domain::{ProviderPromptContext, ProviderSlug};
    /// use iron_providers::{ApiFamily, ProviderConnection, ProviderProfile, RuntimeConfig};
    ///
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let provider = ProviderConnection::from_profile(ProviderProfile::new("openai", ApiFamily::Responses, "https://api.openai.com/v1"), RuntimeConfig::new("sk-example"))?;
    /// # let agent = IronAgent::new(Config::default(), provider);
    /// # let session = agent.connect().create_session()?;
    /// let context = ProviderPromptContext {
    ///     provider_slug: ProviderSlug::new("kimi-code"),
    ///     model: "kimi-for-coding".into(),
    ///     api_key: None,
    /// };
    /// let outcome = session.prompt_managed("Explain closures in Rust", context).await;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn prompt_managed(
        &self,
        text: &str,
        provider_context: ProviderPromptContext,
    ) -> PromptOutcome {
        let acp_session_id = acp::SessionId::new(self.id.to_string());
        let request = acp::PromptRequest::new(
            acp_session_id,
            vec![acp::ContentBlock::Text(acp::TextContent::new(text))],
        );
        match self
            .connection
            .handle_prompt_managed(request, provider_context, self.profile_id.as_ref())
            .await
        {
            Ok(response) => response.stop_reason.into(),
            Err(_) => PromptOutcome::EndTurn,
        }
    }

    /// Send a multimodal prompt with a managed provider and await completion.
    ///
    /// Like [`prompt_managed`](AgentSession::prompt_managed) but accepts
    /// [`ContentBlock`]s for multimodal input (images, files, etc.).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use iron_core::{Config, ContentBlock, IronAgent};
    /// use iron_core::provider_credential::domain::{ProviderPromptContext, ProviderSlug};
    /// use iron_providers::{ApiFamily, ProviderConnection, ProviderProfile, RuntimeConfig};
    ///
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let provider = ProviderConnection::from_profile(ProviderProfile::new("openai", ApiFamily::Responses, "https://api.openai.com/v1"), RuntimeConfig::new("sk-example"))?;
    /// # let agent = IronAgent::new(Config::default(), provider);
    /// # let session = agent.connect().create_session()?;
    /// let context = ProviderPromptContext {
    ///     provider_slug: ProviderSlug::new("kimi-code"),
    ///     model: "kimi-for-coding".into(),
    ///     api_key: Some("sk-...".into()),
    /// };
    /// let blocks = vec![ContentBlock::text("Describe this image")];
    /// let outcome = session.prompt_with_blocks_managed(&blocks, context).await;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn prompt_with_blocks_managed(
        &self,
        blocks: &[ContentBlock],
        provider_context: ProviderPromptContext,
    ) -> PromptOutcome {
        let acp_session_id = acp::SessionId::new(self.id.to_string());
        let acp_blocks: Vec<_> = blocks.iter().map(to_acp_content_block).collect();
        let request = acp::PromptRequest::new(acp_session_id, acp_blocks);
        match self
            .connection
            .handle_prompt_managed(request, provider_context, self.profile_id.as_ref())
            .await
        {
            Ok(response) => response.stop_reason.into(),
            Err(_) => PromptOutcome::EndTurn,
        }
    }

    /// Send a text prompt and return a stream of events.
    ///
    /// This is a convenience wrapper that wraps the text as a single text
    /// [`ContentBlock`] and delegates to the shared streaming path used by
    /// [`prompt_stream_with_blocks`](AgentSession::prompt_stream_with_blocks).
    ///
    /// See [`prompt_stream_with_blocks`](AgentSession::prompt_stream_with_blocks) for the full multimodal streaming API.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use iron_core::{Config, IronAgent, PromptEvent};
    /// use iron_providers::{ApiFamily, ProviderConnection, ProviderProfile, RuntimeConfig};
    ///
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let provider = ProviderConnection::from_profile(ProviderProfile::new("openai", ApiFamily::Responses, "https://api.openai.com/v1"), RuntimeConfig::new("sk-example"))?;
    /// # let agent = IronAgent::new(Config::default(), provider);
    /// # let session = agent.connect().create_session()?;
    /// let (handle, mut events) = session.prompt_stream("Hello");
    ///
    /// while let Some(event) = events.next().await {
    ///     match event {
    ///         PromptEvent::Output { text } => print!("{}", text),
    ///         PromptEvent::ApprovalRequest { call_id, .. } => {
    ///             handle.approve(&call_id).unwrap();
    ///         }
    ///         PromptEvent::Complete { outcome } => break,
    ///         _ => {}
    ///     }
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn prompt_stream(&self, text: &str) -> (PromptHandle, PromptEvents) {
        let acp_blocks = vec![acp::ContentBlock::Text(acp::TextContent::new(text))];
        self.prompt_stream_with_acp_blocks(acp_blocks)
    }

    /// Send a multimodal prompt and return a stream of events.
    ///
    /// This is the streaming API for structured content. It accepts a slice of
    /// [`ContentBlock`] values (text, images, resources) and returns the same
    /// `(PromptHandle, PromptEvents)` contract as [`prompt_stream`](AgentSession::prompt_stream).
    ///
    /// Multimodal streaming preserves the same event-ordering guarantees as
    /// text-only streaming: incremental output may arrive before completion,
    /// `ToolCall` precedes `ToolResult`, approval requests are emitted before
    /// resolution, and exactly one terminal `Complete` is emitted last.
    ///
    /// An empty slice is accepted and follows the same semantics as
    /// [`prompt_stream_with_blocks`](AgentSession::prompt_stream_with_blocks) for empty input.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use iron_core::{Config, ContentBlock, IronAgent, PromptEvent};
    /// use iron_providers::{ApiFamily, ProviderConnection, ProviderProfile, RuntimeConfig};
    ///
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let provider = ProviderConnection::from_profile(ProviderProfile::new("openai", ApiFamily::Responses, "https://api.openai.com/v1"), RuntimeConfig::new("sk-example"))?;
    /// # let agent = IronAgent::new(Config::default(), provider);
    /// # let session = agent.connect().create_session()?;
    /// let blocks = vec![
    ///     ContentBlock::text("Describe this image:"),
    ///     ContentBlock::Image {
    ///         data: "base64-data".into(),
    ///         mime_type: "image/png".into(),
    ///     },
    /// ];
    /// let (handle, mut events) = session.prompt_stream_with_blocks(&blocks);
    ///
    /// while let Some(event) = events.next().await {
    ///     match event {
    ///         PromptEvent::Output { text } => print!("{}", text),
    ///         PromptEvent::Complete { outcome } => break,
    ///         _ => {}
    ///     }
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn prompt_stream_with_blocks(
        &self,
        blocks: &[ContentBlock],
    ) -> (PromptHandle, PromptEvents) {
        let acp_blocks: Vec<_> = blocks.iter().map(to_acp_content_block).collect();
        self.prompt_stream_with_acp_blocks(acp_blocks)
    }

    /// Shared internal streaming path that accepts pre-converted ACP content
    /// blocks, sets up the active-stream state, and spawns the background
    /// prompt task.
    ///
    /// Both [`prompt_stream`] (text convenience) and
    /// [`prompt_stream_with_blocks`] (multimodal) delegate here so that
    /// ACP block request construction, active-stream registration/removal,
    /// and completion handling are unified in one place.
    fn prompt_stream_with_acp_blocks(
        &self,
        acp_blocks: Vec<acp::ContentBlock>,
    ) -> (PromptHandle, PromptEvents) {
        let (event_tx, event_rx) = tokio::sync::mpsc::unbounded_channel();
        let approval_resolvers: Rc<
            RefCell<HashMap<String, tokio::sync::oneshot::Sender<PermissionVerdict>>>,
        > = Rc::new(RefCell::new(HashMap::new()));

        let prompt_key = self.id.to_string();
        self.active_streams.borrow_mut().insert(
            prompt_key.clone(),
            StreamPromptState {
                event_tx: event_tx.clone(),
                approval_resolvers: approval_resolvers.clone(),
                tool_name_index: Rc::new(RefCell::new(HashMap::new())),
            },
        );

        let status = Rc::new(RefCell::new(PromptStatus::Running));
        let handle = PromptHandle {
            approval_resolvers,
            session: self.clone(),
            status: status.clone(),
        };
        let events = PromptEvents { rx: event_rx };

        let acp_session_id = acp::SessionId::new(self.id.to_string());
        let request = acp::PromptRequest::new(acp_session_id, acp_blocks);

        let connection = self.connection.clone();
        let active_streams = self.active_streams.clone();
        let status_cell = status.clone();
        let profile_id = self.profile_id.clone();

        tokio::task::spawn_local(async move {
            let outcome = match connection.handle_prompt(request, profile_id.as_ref()).await {
                Ok(response) => response.stop_reason.into(),
                Err(_) => PromptOutcome::EndTurn,
            };

            {
                let mut streams = active_streams.borrow_mut();
                if let Some(state) = streams.remove(&prompt_key) {
                    let _ = state.event_tx.send(PromptEvent::Complete { outcome });
                }
            }

            *status_cell.borrow_mut() = match outcome {
                PromptOutcome::Cancelled => PromptStatus::Cancelled,
                _ => PromptStatus::Completed,
            };
        });

        (handle, events)
    }

    /// Send a text prompt with a managed provider and return a stream of events.
    ///
    /// The managed path resolves credentials from the credential store (or uses
    /// the API key from `provider_context.api_key`) and retries once on auth
    /// errors after refreshing the stored OAuth token.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use iron_core::{Config, IronAgent};
    /// use iron_core::provider_credential::domain::{ProviderPromptContext, ProviderSlug};
    /// use iron_providers::{ApiFamily, ProviderConnection, ProviderProfile, RuntimeConfig};
    ///
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let provider = ProviderConnection::from_profile(ProviderProfile::new("openai", ApiFamily::Responses, "https://api.openai.com/v1"), RuntimeConfig::new("sk-example"))?;
    /// # let agent = IronAgent::new(Config::default(), provider);
    /// # let session = agent.connect().create_session()?;
    /// let context = ProviderPromptContext {
    ///     provider_slug: ProviderSlug::new("kimi-code"),
    ///     model: "kimi-for-coding".into(),
    ///     api_key: None,
    /// };
    /// let (handle, mut events) = session.prompt_stream_managed("Hello", context);
    /// while let Some(event) = events.next().await {
    ///     // handle PromptEvent
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn prompt_stream_managed(
        &self,
        text: &str,
        provider_context: ProviderPromptContext,
    ) -> (PromptHandle, PromptEvents) {
        let acp_blocks = vec![acp::ContentBlock::Text(acp::TextContent::new(text))];
        self.prompt_stream_with_acp_blocks_managed(acp_blocks, provider_context)
    }

    /// Send a multimodal prompt with a managed provider and return a stream of events.
    ///
    /// Like [`prompt_stream_managed`](AgentSession::prompt_stream_managed) but
    /// accepts [`ContentBlock`]s for multimodal input.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use iron_core::{Config, ContentBlock, IronAgent};
    /// use iron_core::provider_credential::domain::{ProviderPromptContext, ProviderSlug};
    /// use iron_providers::{ApiFamily, ProviderConnection, ProviderProfile, RuntimeConfig};
    ///
    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let provider = ProviderConnection::from_profile(ProviderProfile::new("openai", ApiFamily::Responses, "https://api.openai.com/v1"), RuntimeConfig::new("sk-example"))?;
    /// # let agent = IronAgent::new(Config::default(), provider);
    /// # let session = agent.connect().create_session()?;
    /// let context = ProviderPromptContext {
    ///     provider_slug: ProviderSlug::new("kimi-code"),
    ///     model: "kimi-for-coding".into(),
    ///     api_key: None,
    /// };
    /// let blocks = vec![ContentBlock::text("Describe this")];
    /// let (handle, mut events) = session.prompt_stream_with_blocks_managed(&blocks, context);
    /// # Ok(())
    /// # }
    /// ```
    pub fn prompt_stream_with_blocks_managed(
        &self,
        blocks: &[ContentBlock],
        provider_context: ProviderPromptContext,
    ) -> (PromptHandle, PromptEvents) {
        let acp_blocks: Vec<_> = blocks.iter().map(to_acp_content_block).collect();
        self.prompt_stream_with_acp_blocks_managed(acp_blocks, provider_context)
    }

    /// Shared internal streaming path for managed providers.
    fn prompt_stream_with_acp_blocks_managed(
        &self,
        acp_blocks: Vec<acp::ContentBlock>,
        provider_context: ProviderPromptContext,
    ) -> (PromptHandle, PromptEvents) {
        let (event_tx, event_rx) = tokio::sync::mpsc::unbounded_channel();
        let approval_resolvers: Rc<
            RefCell<HashMap<String, tokio::sync::oneshot::Sender<PermissionVerdict>>>,
        > = Rc::new(RefCell::new(HashMap::new()));

        let prompt_key = self.id.to_string();
        self.active_streams.borrow_mut().insert(
            prompt_key.clone(),
            StreamPromptState {
                event_tx: event_tx.clone(),
                approval_resolvers: approval_resolvers.clone(),
                tool_name_index: Rc::new(RefCell::new(HashMap::new())),
            },
        );

        let status = Rc::new(RefCell::new(PromptStatus::Running));
        let handle = PromptHandle {
            approval_resolvers,
            session: self.clone(),
            status: status.clone(),
        };
        let events = PromptEvents { rx: event_rx };

        let acp_session_id = acp::SessionId::new(self.id.to_string());
        let request = acp::PromptRequest::new(acp_session_id, acp_blocks);

        let connection = self.connection.clone();
        let active_streams = self.active_streams.clone();
        let status_cell = status.clone();
        let profile_id = self.profile_id.clone();

        tokio::task::spawn_local(async move {
            let outcome = match connection
                .handle_prompt_managed(request, provider_context, profile_id.as_ref())
                .await
            {
                Ok(response) => response.stop_reason.into(),
                Err(_) => PromptOutcome::EndTurn,
            };

            {
                let mut streams = active_streams.borrow_mut();
                if let Some(state) = streams.remove(&prompt_key) {
                    let _ = state.event_tx.send(PromptEvent::Complete { outcome });
                }
            }

            *status_cell.borrow_mut() = match outcome {
                PromptOutcome::Cancelled => PromptStatus::Cancelled,
                _ => PromptStatus::Completed,
            };
        });

        (handle, events)
    }

    /// Cancel any active prompt on this session.
    pub async fn cancel(&self) {
        let acp_session_id = acp::SessionId::new(self.id.to_string());
        let notification = acp::CancelNotification::new(acp_session_id);
        let _ = self.connection.handle_cancel(notification).await;
    }

    /// Get the conversation timeline.
    ///
    /// Returns a list of timeline entries representing the conversation history.
    pub fn timeline(&self) -> Vec<TimelineEntry> {
        self.durable.lock().timeline.clone()
    }

    /// Get the conversation messages.
    ///
    /// Returns the structured messages in the conversation.
    pub fn messages(&self) -> Vec<StructuredMessage> {
        self.durable.lock().messages.clone()
    }

    /// Get the tool call records.
    ///
    /// Returns a list of all tool calls made during this session.
    pub fn tool_records(&self) -> Vec<DurableToolRecord> {
        self.durable.lock().tool_records.clone()
    }

    /// Check if the session is empty (has no messages).
    pub fn is_empty(&self) -> bool {
        self.durable.lock().is_empty()
    }

    /// Set the system instructions for this session.
    pub fn set_instructions(&self, instructions: impl Into<String>) {
        self.durable.lock().set_instructions(instructions);
    }

    /// Set the workspace roots for this session.
    ///
    /// If the session is idle, roots are applied immediately and the session's
    /// available skills are refreshed from the new roots.
    ///
    /// If a prompt is currently active, the roots are deferred until the prompt
    /// completes, at which point they will be applied automatically.
    ///
    /// Returns `true` if the roots were applied immediately, or `false` if they
    /// were deferred until the next turn boundary.
    pub fn set_workspace_roots(
        &self,
        roots: Vec<std::path::PathBuf>,
    ) -> Result<bool, RuntimeError> {
        self.connection
            .runtime()
            .set_session_workspace_roots(self.id, roots)
    }

    // -- Provider Credential APIs --

    /// Get the auth status for a provider.
    pub async fn provider_auth_status(&self, slug: &ProviderSlug) -> Option<ProviderAuthStatus> {
        self.connection.runtime().provider_auth_status(slug).await
    }

    /// Get the auth status for a provider while considering an app-owned API key.
    pub async fn provider_auth_status_with_api_key(
        &self,
        slug: &ProviderSlug,
        api_key: Option<&str>,
    ) -> Option<ProviderAuthStatus> {
        self.connection
            .runtime()
            .provider_auth_status_with_api_key(slug, api_key)
            .await
    }

    /// Get the auth status for a managed prompt context.
    pub async fn provider_auth_status_for_context(
        &self,
        context: &ProviderPromptContext,
    ) -> Option<ProviderAuthStatus> {
        self.connection
            .runtime()
            .provider_auth_status_for_context(context)
            .await
    }

    /// Disconnect OAuth for a provider without removing API keys.
    pub async fn disconnect_provider_oauth(&self, slug: &ProviderSlug) {
        self.connection
            .runtime()
            .disconnect_provider_oauth(slug)
            .await;
    }

    // -- Skill APIs --

    /// Refresh the skill catalog by re-scanning all configured sources.
    ///
    /// Returns diagnostics from the discovery process.
    pub fn refresh_skill_catalog(&self) -> Vec<crate::skill::SkillDiagnostic> {
        let diagnostics = self.connection.runtime().refresh_skill_catalog();
        let available_skills = self.connection.runtime().available_skill_snapshot();
        self.durable.lock().set_available_skills(available_skills);
        diagnostics
    }

    /// List skills available in the runtime catalog.
    pub fn list_available_skills(&self) -> Vec<crate::skill::SkillMetadata> {
        self.durable
            .lock()
            .list_available_skills()
            .iter()
            .map(|skill| skill.metadata.clone())
            .collect()
    }

    /// Activate a skill for this session.
    pub fn activate_skill(&self, name: &str) -> Result<(), String> {
        let skill = self
            .durable
            .lock()
            .load_available_skill(name)
            .ok_or_else(|| format!("Skill '{}' not found", name))?;
        self.durable.lock().activate_skill(
            &skill.metadata.id,
            &skill.body,
            skill.resources.clone(),
        );
        Ok(())
    }

    /// Deactivate a skill for this session.
    pub fn deactivate_skill(&self, name: &str) {
        self.durable.lock().deactivate_skill(name);
    }

    /// List the names of skills currently active in this session.
    pub fn list_active_skills(&self) -> Vec<String> {
        self.durable
            .lock()
            .list_active_skills()
            .into_iter()
            .map(|s| s.to_string())
            .collect()
    }

    /// Get a snapshot of the active context.
    ///
    /// This provides telemetry about the current context window usage.
    pub fn active_context(
        &self,
        tool_registry: &crate::tool::ToolRegistry,
        current_prompt: Option<&str>,
        context_window_hint: Option<usize>,
    ) -> crate::context::ActiveContextSnapshot {
        let session = self.durable.lock();
        let tail = session.to_transcript();
        let mut snapshot = crate::context::ContextTelemetry::for_session(
            session.instruction_text_for_estimate().as_deref(),
            &session.compressed_blocks,
            &tail.messages,
            tool_registry,
            current_prompt,
            context_window_hint,
            crate::context::SessionModelInfo {
                current_model: session.current_model.as_deref(),
                model_switch_count: session.model_switch_history.len(),
            },
            Some(&session.token_tracker),
        );
        let context_config = &self.connection.runtime().config().context_management;
        if context_config.enabled {
            snapshot.compact_threshold_tokens = Some(context_config.maintenance_threshold);
        }
        snapshot
    }

    /// Check if the session is idle (no active prompts or tool calls).
    pub fn is_idle(&self) -> bool {
        let durable_idle = self.durable.lock().is_idle();
        let has_active_prompt = self.connection.runtime().has_active_prompt(self.id);
        durable_idle && !has_active_prompt
    }

    /// Get the number of uncompacted tokens in the session.
    pub fn uncompacted_tokens(&self) -> usize {
        self.durable.lock().uncompacted_tokens
    }

    /// Get the compressed blocks.
    pub fn compressed_blocks(&self) -> Vec<crate::context::models::CompressedBlock> {
        self.durable.lock().compressed_blocks.clone()
    }

    /// Create a checkpoint by compacting the session context.
    ///
    /// This uses the provider to generate a summary of older messages,
    /// reducing the token count while preserving conversation context.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is not idle or if context management
    /// is not enabled.
    pub async fn checkpoint(&self) -> Result<(), String> {
        if !self.is_idle() {
            return Err("Cannot checkpoint: session is not idle".into());
        }

        let config = self.connection.runtime().config().clone();
        if !config.context_management.enabled {
            return Err("Context management is not enabled".into());
        }

        self.try_prompt("/compact").await.map(|_| ())
    }

    /// Export a handoff bundle for transferring this session to another agent.
    ///
    /// The bundle contains the session's conversation history and context,
    /// allowing it to be resumed elsewhere via
    /// [`AgentConnection::create_session_from_handoff`].
    ///
    /// # Errors
    ///
    /// Returns an error if the session is not idle.
    pub async fn export_handoff(
        &self,
        model: &str,
        provider_name: Option<&str>,
    ) -> Result<crate::context::HandoffBundle, String> {
        if !self.is_idle() {
            return Err("Cannot export handoff: session is not idle".into());
        }

        let config = self.connection.runtime().config().clone();

        let (compressed_blocks, tail) = {
            let session = self.durable.lock();
            let tail = session.messages.clone();
            (session.compressed_blocks.clone(), tail)
        };

        let session = self.durable.lock();
        HandoffExporter::export(
            &session,
            model,
            &compressed_blocks,
            tail,
            &config.context_management,
            provider_name,
        )
    }

    /// Enable or disable an MCP server for this session.
    pub fn set_mcp_server_enabled(&self, server_id: impl Into<String>, enabled: bool) {
        self.durable
            .lock()
            .set_mcp_server_enabled(server_id, enabled);
    }

    /// Check if an MCP server is enabled for this session.
    pub fn is_mcp_server_enabled(&self, server_id: &str) -> Option<bool> {
        self.durable.lock().is_mcp_server_enabled(server_id)
    }

    /// Get list of MCP servers enabled for this session.
    pub fn list_enabled_mcp_servers(&self) -> Vec<String> {
        self.durable.lock().list_enabled_mcp_servers()
    }

    /// Enable or disable a plugin for this session.
    pub fn set_plugin_enabled(&self, plugin_id: impl Into<String>, enabled: bool) {
        self.durable.lock().set_plugin_enabled(plugin_id, enabled);
    }

    /// Check if a plugin is enabled for this session.
    pub fn is_plugin_enabled(&self, plugin_id: &str) -> Option<bool> {
        self.durable.lock().is_plugin_enabled(plugin_id)
    }

    /// Get list of plugins enabled for this session.
    pub fn list_enabled_plugins(&self) -> Vec<String> {
        self.durable.lock().list_enabled_plugins()
    }

    /// Request a model switch for this session.
    ///
    /// If the session is idle, the switch is applied immediately.
    /// If the session has an active prompt, the switch is queued and
    /// applied at the next turn boundary.
    ///
    /// # Arguments
    ///
    /// * `request` - The model switch request (managed or unmanaged)
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` if the switch was queued or applied successfully,
    /// or an error if the switch request is invalid.
    pub fn switch_model(
        &self,
        request: crate::context::model_switch::ModelSwitchRequest,
    ) -> Result<(), String> {
        let runtime = self.connection.runtime();

        if self.is_idle() {
            let from_model = self
                .durable
                .lock()
                .current_model
                .clone()
                .unwrap_or_else(|| "unknown".to_string());

            let (capability_diff, compaction_info) = runtime
                .apply_model_switch(self.id, request.clone())
                .map_err(|e| e.to_string())?;

            let (to_model, _to_provider) = match &request {
                crate::context::model_switch::ModelSwitchRequest::Managed {
                    provider_slug,
                    model,
                    ..
                } => (model.clone(), Some(provider_slug.clone())),
                crate::context::model_switch::ModelSwitchRequest::Unmanaged {
                    model,
                    provider_name,
                } => (model.clone(), Some(provider_name.clone())),
            };

            if let Some(info) = compaction_info {
                let compaction_id = uuid::Uuid::new_v4().to_string();
                self.emit_model_switch_event(PromptEvent::CompactionStarted {
                    compaction_id: compaction_id.clone(),
                    method: info.method.clone(),
                });
                self.emit_model_switch_event(PromptEvent::CompactionFinished {
                    compaction_id,
                    tokens_before: Some(info.tokens_before),
                    tokens_after: Some(info.tokens_after),
                    method: info.method,
                });
            }

            self.emit_model_switch_event(PromptEvent::ModelSwitched {
                from_model,
                to_model,
                adapted: capability_diff.window_shrink.is_some()
                    || !capability_diff.hidden_tools.is_empty()
                    || !capability_diff.unsupported_modalities.is_empty(),
                capability_diff,
            });

            Ok(())
        } else {
            runtime
                .queue_model_switch(self.id, request.clone())
                .map_err(|e| e.to_string())?;

            // Emit pending event
            let (target_model, target_provider) = match &request {
                crate::context::model_switch::ModelSwitchRequest::Managed {
                    provider_slug,
                    model,
                    ..
                } => (model.clone(), Some(provider_slug.clone())),
                crate::context::model_switch::ModelSwitchRequest::Unmanaged {
                    model,
                    provider_name,
                } => (model.clone(), Some(provider_name.clone())),
            };

            self.emit_model_switch_event(PromptEvent::ModelSwitchPending {
                target_model,
                target_provider,
            });

            Ok(())
        }
    }

    /// Start a direct client-initiated auth flow for a plugin.
    ///
    /// Convenience wrapper that delegates to the connection's
    /// [`AgentConnection::start_auth_flow`].
    ///
    /// # Errors
    ///
    /// Returns an error if the plugin is not found, does not require auth,
    /// is already authenticating, or is already authenticated.
    pub fn start_auth_flow(
        &self,
        plugin_id: &str,
    ) -> Result<crate::plugin::auth::AuthInteractionRequest, String> {
        let previous_state = self
            .connection
            .runtime()
            .get_plugin_status(plugin_id)
            .map(|status| status.auth.state)
            .unwrap_or(crate::plugin::auth::AuthState::Unauthenticated);
        let request = self
            .connection
            .runtime()
            .begin_plugin_auth_flow(plugin_id)?;
        self.emit_auth_transition_to_stream(
            plugin_id,
            previous_state,
            crate::plugin::auth::AuthState::Authenticating,
        );
        Ok(request)
    }

    /// Complete a direct client-initiated auth flow for a plugin.
    ///
    /// Convenience wrapper that delegates to the connection's
    /// [`AgentConnection::complete_auth_flow`].
    ///
    /// # Errors
    ///
    /// Returns an error if the plugin is not found or is not in the
    /// `Authenticating` state.
    pub fn complete_auth_flow(
        &self,
        plugin_id: &str,
        response: crate::plugin::auth::AuthInteractionResponse,
    ) -> Result<crate::plugin::auth::AuthStatusTransition, String> {
        let transition = self
            .connection
            .runtime()
            .complete_plugin_auth_flow(plugin_id, response)?;
        self.emit_auth_transition_to_stream(
            &transition.auth_id,
            transition.previous_state,
            transition.new_state,
        );
        Ok(transition)
    }

    /// Get auth prompts for all plugins that require authentication.
    ///
    /// Convenience wrapper that delegates to the runtime.
    pub fn get_auth_prompts(&self) -> Vec<crate::plugin::auth::AuthPrompt> {
        self.connection.runtime().get_auth_prompts()
    }

    /// Get a session-scoped summary of plugin tool availability.
    ///
    /// Combines the runtime-level registry state with this session's plugin
    /// enablement to produce a per-plugin summary of usable tool counts.
    pub fn get_plugin_tool_summary(
        &self,
    ) -> crate::plugin::effective_tools::SessionPluginToolSummary {
        self.connection
            .runtime()
            .get_session_plugin_summary(self.id)
            .unwrap_or_default()
    }

    /// Get unified tool diagnostics for this session.
    ///
    /// Returns diagnostics for every tool visible (or potentially visible)
    /// to this session, including unavailable plugin tools with reasons.
    pub fn get_tool_diagnostics(&self) -> Vec<crate::mcp::session_catalog::ToolDiagnostic> {
        self.connection
            .runtime()
            .get_session_tool_diagnostics(self.id)
            .unwrap_or_default()
    }

    /// Import a handoff bundle into this session.
    ///
    /// # Errors
    ///
    /// Returns an error if the session is not idle or is not empty.
    /// To import into a new session, use [`AgentConnection::create_session_from_handoff`].
    pub fn import_handoff(&self, bundle: crate::context::HandoffBundle) -> Result<(), String> {
        if !self.is_idle() {
            return Err("Cannot import handoff: session is not idle".into());
        }
        if !self.is_empty() {
            return Err(
                "Cannot import handoff: session must be empty. Use create_session_from_handoff instead.".into(),
            );
        }
        let mut session = self.durable.lock();
        HandoffImporter::hydrate(&mut session, bundle)
    }
}

fn to_acp_content_block(block: &ContentBlock) -> acp::ContentBlock {
    match block {
        ContentBlock::Text { text } => acp::ContentBlock::Text(acp::TextContent::new(text)),
        ContentBlock::Image { data, mime_type } => {
            acp::ContentBlock::Image(acp::ImageContent::new(data, mime_type))
        }
        ContentBlock::Resource { uri, name } => acp::ContentBlock::ResourceLink(
            acp::ResourceLink::new(name.as_deref().unwrap_or("resource"), uri),
        ),
    }
}

impl Clone for AgentSession {
    fn clone(&self) -> Self {
        Self {
            id: self.id,
            durable: self.durable.clone(),
            connection: self.connection.clone(),
            active_streams: self.active_streams.clone(),
            profile_id: self.profile_id.clone(),
        }
    }
}

impl std::fmt::Debug for IronAgent {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("IronAgent").finish()
    }
}

impl std::fmt::Debug for AgentConnection {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("AgentConnection")
            .field("id", &self.inner.id())
            .finish()
    }
}

impl std::fmt::Debug for AgentSession {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("AgentSession")
            .field("id", &self.id)
            .finish()
    }
}