Trait Session 

pub trait Session: Send + Sync {
    // Required methods
    fn id(&self) -> &SessionId;
    fn provider_info(&self) -> ProviderInfo;
    fn current_model(&self) -> String;
    fn list_models(
        &self,
    ) -> BoxFuture<'_, Result<Vec<ModelInfo>, ProviderError>>;
    fn list_candidates(
        &self,
    ) -> BoxFuture<'_, Result<Vec<ModelCandidate>, ProviderError>>;
    fn set_model(
        &self,
        selection: ModelSelection,
    ) -> BoxFuture<'_, Result<(), ProviderError>>;
    fn current_mode(&self) -> Option<String>;
    fn available_modes(&self) -> Vec<ModeDescriptor>;
    fn set_mode(&self, mode_id: String) -> Result<(), AgentError>;
    fn current_reasoning_effort(&self) -> Option<ReasoningEffort>;
    fn set_reasoning_effort(&self, effort: Option<ReasoningEffort>);
    fn subscribe(&self) -> EventStream;
    fn history_snapshot(&self) -> Vec<Message>;
    fn run_turn(
        &self,
        prompt: Vec<ContentBlock>,
    ) -> BoxFuture<'_, Result<StopReason, TurnError>>;
    fn cancel_turn(&self);
    fn resolve_permission(&self, id: ToolCallId, outcome: PermissionResolution);
    fn context_status(&self) -> ContextStatus;
    fn compact_now(
        &self,
    ) -> BoxFuture<'_, Result<Option<CompactionReport>, TurnError>>;
}

A single session.

All methods are trait-object-friendly (&self + BoxFuture). The Arc<dyn Session> is shared between defect-acp and the main loop.

Required Methods

fn id(&self) -> &SessionId

fn provider_info(&self) -> ProviderInfo

Provider metadata used by the current session.

fn current_model(&self) -> String

The model ID used by the current session.

fn list_models(&self) -> BoxFuture<'_, Result<Vec<ModelInfo>, ProviderError>>

List the model candidates available from the current provider for this session.

Errors

Returns ProviderError if the provider fails to fetch the model list.

fn list_candidates( &self, ) -> BoxFuture<'_, Result<Vec<ModelCandidate>, ProviderError>>

List the (provider, model) candidate pairs visible to the session. Under a multi-provider setup, the same session may switch models across providers, so ACP rendering needs to annotate each candidate with its provider.

Errors

Same as Self::list_models: returns ProviderError if fetching the provider list fails.

fn set_model( &self, selection: ModelSelection, ) -> BoxFuture<'_, Result<(), ProviderError>>

Switches the model for the current session.

The selection key is a (provider vendor, model) pair — the same model id may be advertised by multiple providers (multiple gateways for the same model), so the provider must be explicitly specified. The currently in-progress turn retains its original selection; subsequent turns use the new selection.

Errors

Returns ProviderError when the provider fails to fetch its model list, or when the requested (provider, model) pair does not exist.

fn current_mode(&self) -> Option<String>

The current active permission mode ID. Returns None if no mode catalog is loaded.

Maps to ACP SessionModeState::current_mode_id.

fn available_modes(&self) -> Vec<ModeDescriptor>

The list of permission modes available to this session, in assembly order. Returns an empty list when no mode directory is mounted. Maps to ACP SessionModeState::available_modes.

fn set_mode(&self, mode_id: String) -> Result<(), AgentError>

Switch the current permission mode. The change takes effect on subsequent turns; the in-flight turn retains its original policy (same semantics as Self::set_model — the policy is snapshotted when run_turn starts).

Errors

Returns AgentError::ModeNotFound if mode_id does not match any available mode, or if the session has no mode directory installed.

fn current_reasoning_effort(&self) -> Option<ReasoningEffort>

The current reasoning_effort level (None = unset, falling back to the provider default). Maps to the current value of the ACP thought-level configuration item.

fn set_reasoning_effort(&self, effort: Option<ReasoningEffort>)

Sets the reasoning_effort level. None clears the override (falls back to the provider default). Takes effect on subsequent turns. Providers that do not support this concept ignore it when assembling requests.

fn subscribe(&self) -> EventStream

Subscribe to the event stream. Three independent consumers (acp / storage / tracing) each call this once without interfering with each other — internally uses mpsc with fan-out so that slow consumers only experience backpressure without dropping events.

fn history_snapshot(&self) -> Vec<Message>

A read-only snapshot of the current history, used to replay the transcript to the client after a session load.

fn run_turn( &self, prompt: Vec<ContentBlock>, ) -> BoxFuture<'_, Result<StopReason, TurnError>>

Starts a turn.

The returned future resolves when the turn ends:

• Ok(StopReason) – normal termination (including Cancelled); drives the ACP PromptResponse
• Err(TurnError) – fatal error (auth expiry, model unavailable, etc.); drives the ACP JSON-RPC Error response

AgentEvents produced during the turn are pushed via Session::subscribe, not through this future. The TurnEnded event is still emitted on the event stream (for storage / tracing), but the ACP bridge uses this future’s outcome.

Only one turn may be in progress per session at a time; concurrent calls return TurnError::TurnInProgress.

fn cancel_turn(&self)

Cancels the current turn. Idempotent: no-op if no turn is in progress.

fn resolve_permission(&self, id: ToolCallId, outcome: PermissionResolution)

Writes back the client response to the ACP reverse request session/request_permission to the main loop.

fn context_status(&self) -> ContextStatus

Current context usage. Read-only and cheap; backs the /context slash command.

fn compact_now( &self, ) -> BoxFuture<'_, Result<Option<CompactionReport>, TurnError>>

Synchronously compact the session history now (out-of-band /compact command), reusing the same boundary selection + summarization as the turn loop’s hard watermark.

Returns Ok(Some(report)) when a compaction ran, Ok(None) when there was no safe boundary to summarize (e.g. a single short turn — nothing to do).

Errors

Returns TurnError::TurnInProgress if a turn is currently running: compaction rewrites history and would race the in-flight turn, so the caller must /cancel or wait first.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl Session for DefaultSession