phi-core 0.7.0

Simple, effective agent loop with tool execution and event streaming
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
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

use crate::types::*;
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};

// ---------------------------------------------------------------------------
// Compaction Block — non-destructive overlay on LoopRecord
// ---------------------------------------------------------------------------

/// Non-destructive compaction overlay. Stored on `LoopRecord` alongside
/// the original messages. When present, the context loader uses this block
/// instead of raw messages.
///
/// Three sections control what gets loaded into context:
/// - `keep_first`: turns kept verbatim from the start (most recent loop only)
/// - `keep_recent`: recent turns with truncated tool outputs (most recent loop only)
/// - `keep_compacted`: fully summarised section (all loops)
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CompactionBlock {
    /// Turns kept verbatim from the start of the loop.
    /// Only populated for the MOST RECENT loop. For older loops this is `None`.
    /// During context load: original messages in this range are used as-is.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub keep_first: Option<TurnRange>,

    /// Recent turns with tool outputs truncated. Rest unchanged.
    /// Only populated for the MOST RECENT loop. For older loops this is `None`.
    /// Invariant: if a ToolCall is in range, its corresponding ToolResult is too.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub keep_recent: Option<CompactedSection>,

    /// Fully summarised middle section (most recent loop) or entire loop (older loops).
    /// Relevant for ALL loops — this is what gets loaded from earlier loops.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub keep_compacted: Option<CompactedSection>,

    /// When this block was created.
    #[serde(rename = "createdAt")]
    pub created_at: DateTime<Utc>,
}

/// A range of turns within a loop, identified by turn indices.
/// Both bounds are inclusive. These correspond to `TurnId.turn_index` values.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TurnRange {
    #[serde(rename = "startTurn")]
    pub start_turn: u32,
    #[serde(rename = "endTurn")]
    pub end_turn: u32,
}

/// A range of turns plus the compacted replacement messages for that range.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CompactedSection {
    /// The turn range this section replaces.
    pub range: TurnRange,
    /// Replacement messages loaded into context instead of the originals.
    pub messages: Vec<AgentMessage>,
}

// ---------------------------------------------------------------------------
// TurnMap — maps turn indices to message index ranges
// ---------------------------------------------------------------------------

/// Maps turn indices to message index ranges within a message array.
/// Built from messages by grouping on `TurnId.turn_index`.
pub struct TurnMap {
    /// Indexed by position (0-based). Each entry is `(start_msg_idx, end_msg_idx)` inclusive.
    entries: Vec<(usize, usize)>,
}

impl TurnMap {
    /// Build from messages by grouping on `turn_id.turn_index`.
    /// Messages without a `turn_id` are treated as their own single-message group.
    pub fn from_messages(messages: &[AgentMessage]) -> Self {
        let mut entries: Vec<(usize, usize)> = Vec::new();
        let mut current_turn: Option<u32> = None;

        for (i, msg) in messages.iter().enumerate() {
            let turn_idx = msg.turn_id().map(|t| t.turn_index);
            match (turn_idx, current_turn) {
                (Some(idx), Some(cur)) if idx == cur => {
                    // Same turn — extend end index
                    if let Some(last) = entries.last_mut() {
                        last.1 = i;
                    }
                }
                (Some(idx), _) => {
                    // New turn
                    entries.push((i, i));
                    current_turn = Some(idx);
                }
                (None, _) => {
                    // Legacy message without turn_id — treat as its own group
                    entries.push((i, i));
                    current_turn = None;
                }
            }
        }

        Self { entries }
    }

    /// Number of turn groups.
    pub fn turn_count(&self) -> u32 {
        self.entries.len() as u32
    }

    /// Slice of messages belonging to a `TurnRange`.
    pub fn messages_for_range<'a>(
        &self,
        range: &TurnRange,
        all_msgs: &'a [AgentMessage],
    ) -> &'a [AgentMessage] {
        if range.start_turn as usize >= self.entries.len()
            || range.end_turn as usize >= self.entries.len()
        {
            return &[];
        }
        let start = self.entries[range.start_turn as usize].0;
        let end = self.entries[range.end_turn as usize].1;
        &all_msgs[start..=end]
    }

    /// Message index range `(start, end)` inclusive for a single turn.
    pub fn turn_msg_range(&self, turn_index: u32) -> Option<(usize, usize)> {
        self.entries.get(turn_index as usize).copied()
    }
}