zeph-commands 0.22.4

Slash command registry, handler trait, and channel sink abstraction for Zeph
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
// SPDX-License-Identifier: MIT OR Apache-2.0

//! [`MessageAccess`] trait for command handlers that read or clear conversation state.
//!
//! Used by `/clear`, `/reset`, and `/clear-queue` handlers.

/// Access to conversation message history and related runtime caches.
///
/// Implemented by `zeph-core` on a struct holding `MessageState`, `ToolState`,
/// `ProviderState`, `MetricsState`, and the tool orchestrator. Grouped into one trait
/// because all of these are mutated together by the clear operation.
pub trait MessageAccess: Send {
    /// Clear conversation history, keeping only the system prompt (first message).
    ///
    /// Also clears tool dependency state, recomputes prompt token count, clears pending
    /// image parts, the tool orchestrator cache, and the user-provided URL tracking set.
    fn clear_history(&mut self);

    /// Return the number of messages currently queued for processing.
    fn queue_len(&self) -> usize;

    /// Discard all queued messages. Returns the number that were discarded.
    fn drain_queue(&mut self) -> usize;

    /// Notify the channel of the updated queue count after clearing, if supported.
    ///
    /// Implementations that cannot access the channel (due to borrow splitting) may be no-ops;
    /// the `/clear-queue` handler calls `ctx.sink.send_queue_count(0)` directly.
    fn notify_queue_count<'a>(
        &'a mut self,
        count: usize,
    ) -> std::pin::Pin<Box<dyn std::future::Future<Output = ()> + Send + 'a>>;

    /// Total number of transcript-eligible (non-system) messages currently in history
    /// (spec-068 §13.6).
    fn transcript_len(&self) -> usize;

    /// Return a page of transcript entries, oldest-first.
    ///
    /// `start` is the 0-based index of the first entry to include; `count` bounds how many
    /// entries are returned. Slicing happens before formatting (INV-SP-6) — callers must never
    /// materialize the full history and then trim.
    fn transcript_page(
        &self,
        start: usize,
        count: usize,
    ) -> Vec<crate::transcript::TranscriptEntry>;

    /// Current `/history all` pagination cursor (0 = not yet started/reset).
    fn history_cursor(&self) -> usize;

    /// Set the `/history all` pagination cursor after a page is shown.
    fn set_history_cursor(&mut self, pos: usize);
}