bob_core/
tape.rs

1//! # Tape Types
2//!
3//! Append-only conversation recording types for the Bob Agent Framework.
4//!
5//! The tape system provides a persistent, searchable log of all interactions:
6//!
7//! - **Messages**: User and assistant conversation entries
8//! - **Events**: Tool calls, LLM calls, and other runtime events
9//! - **Anchors**: Semantic markers for task phases and milestones
10//! - **Handoffs**: Context window reset points for topic switching
11//!
12//! ## Design
13//!
14//! The tape is **append-only** — entries are never modified or deleted.
15//! This ensures auditability and allows reliable replay and search.
16//!
17//! ```text
18//! ┌────────┐  ┌────────┐  ┌────────┐  ┌─────────┐  ┌────────┐
19//! │ msg:U  │→ │ msg:A  │→ │ event  │→ │ anchor  │→ │handoff │→ ...
20//! └────────┘  └────────┘  └────────┘  └─────────┘  └────────┘
21//! ```
22//!
23//! ## Handoff
24//!
25//! When a conversation grows long or the user switches tasks, a **handoff**
26//! entry resets the context window. The LLM only sees entries **after** the
27//! most recent handoff, while the full history remains in the tape for search.
28
29use serde::{Deserialize, Serialize};
30
31use crate::types::Role;
32
33/// Unique identifier for a tape entry.
34pub type TapeEntryId = u64;
35
36/// A single record in the append-only tape.
37#[derive(Debug, Clone, Serialize, Deserialize)]
38pub struct TapeEntry {
39    /// Monotonically increasing entry identifier.
40    pub id: TapeEntryId,
41    /// What kind of entry this is.
42    pub kind: TapeEntryKind,
43    /// Unix epoch milliseconds when this entry was recorded.
44    pub timestamp_ms: u64,
45}
46
47/// Discriminated union of tape entry types.
48#[derive(Debug, Clone, Serialize, Deserialize)]
49#[serde(tag = "type", rename_all = "snake_case")]
50pub enum TapeEntryKind {
51    /// A conversation message (user, assistant, tool, or system).
52    Message { role: Role, content: String },
53    /// A runtime event (tool call, LLM call, etc.).
54    Event { event: String, payload: serde_json::Value },
55    /// A semantic bookmark marking a milestone or phase boundary.
56    Anchor { name: String, state: serde_json::Value },
57    /// A context-window reset point.
58    ///
59    /// Entries before the most recent handoff are excluded from the LLM
60    /// context window but remain in the tape for search.
61    Handoff {
62        name: String,
63        /// Number of tape entries that existed before this handoff.
64        entries_before: u64,
65        /// Optional human-readable summary of the preceding context.
66        summary: Option<String>,
67    },
68}
69
70/// A search hit within the tape.
71#[derive(Debug, Clone)]
72pub struct TapeSearchResult {
73    /// The matching entry.
74    pub entry: TapeEntry,
75    /// A short snippet highlighting the matching text.
76    pub snippet: String,
77}
78
79/// Returns the current time as Unix epoch milliseconds.
80///
81/// Falls back to `0` if the system clock is before the Unix epoch.
82#[must_use]
83pub fn now_ms() -> u64 {
84    std::time::SystemTime::now()
85        .duration_since(std::time::UNIX_EPOCH)
86        .map_or(0, |d| d.as_millis() as u64)
87}
bob_core/tape.rs

bob_core/
tape.rs
