zeph_commands/context.rs
1// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Non-generic command execution context.
5//!
6//! [`CommandContext`] is the single argument passed to every [`CommandHandler`]. It provides
7//! access to agent subsystems through trait objects, eliminating the `C: Channel` generic from
8//! `CommandHandler` and `CommandRegistry`.
9//!
10//! `zeph-core` constructs a `CommandContext` at dispatch time from `Agent<C>` fields:
11//!
12//! ```rust,ignore
13//! let mut ctx = CommandContext {
14//! sink: &mut sink_adapter,
15//! debug: &mut self.debug_state,
16//! messages: &mut messages_impl,
17//! session: &session_impl,
18//! agent: &mut agent_impl,
19//! };
20//! registry.dispatch(&mut ctx, input).await;
21//! ```
22//!
23//! [`CommandHandler`]: crate::CommandHandler
24
25use crate::sink::ChannelSink;
26use crate::traits::agent::AgentAccess;
27use crate::traits::debug::DebugAccess;
28use crate::traits::messages::MessageAccess;
29use crate::traits::session::SessionAccess;
30
31/// Typed access to agent subsystems for slash command handlers.
32///
33/// Each field is a trait object providing access to one subsystem group. Constructed by
34/// `zeph-core` at dispatch time from `Agent<C>` fields. Handlers receive `&mut CommandContext`
35/// and access only the fields they need.
36///
37/// # Lifetimes
38///
39/// The lifetime `'a` ties all references to the dispatch scope. A `CommandContext` must not
40/// outlive the `&mut Agent<C>` it was constructed from.
41pub struct CommandContext<'a> {
42 /// I/O channel for sending responses to the user.
43 pub sink: &'a mut dyn ChannelSink,
44 /// Debug/diagnostics state: dump, format, logging config.
45 pub debug: &'a mut dyn DebugAccess,
46 /// Conversation message history and queue operations.
47 pub messages: &'a mut dyn MessageAccess,
48 /// Session and channel properties (e.g., `supports_exit`).
49 pub session: &'a dyn SessionAccess,
50 /// Broad access to agent subsystems for commands that need multiple agent fields.
51 pub agent: &'a mut dyn AgentAccess,
52}