reef-core 0.4.0

Provider-neutral primitives for building LLM agents: run lifecycle, transcript, tools, hooks
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
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
//! Owned provider-extension payloads and validated envelopes.

use std::error::Error;
use std::fmt::{self, Debug, Display, Formatter};

use crate::redact::Bytes;

/// An owned sequence of uninterpreted bytes.
///
/// # Equality
///
/// Two payloads are equal when they carry the same bytes in the same order, and
/// that is the whole of it. Nothing here is normalized, unescaped or parsed
/// before the comparison, because core never parsed these bytes in the first
/// place: two payloads that a provider would read as the same value are unequal
/// whenever their bytes differ. The relation is total, so this is an
/// [`Eq`], and a payload's length is public through
/// [`as_bytes`](Payload::as_bytes) — equality says nothing that was not already
/// observable.
#[derive(Clone, Eq, PartialEq)]
pub struct Payload(Box<[u8]>);

impl Debug for Payload {
    /// States how many bytes arrived, never which ones.
    ///
    /// These bytes are provider content that reef never parsed, so a size is
    /// the most a formatter can say about them and is also the fact worth
    /// saying: "the provider sent an empty compat blob" is a real bug report.
    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
        Bytes(self.0.len()).fmt(formatter)
    }
}

impl Payload {
    /// Takes ownership of a byte vector without parsing it.
    #[must_use]
    pub fn from_vec(bytes: Vec<u8>) -> Self {
        Self(bytes.into_boxed_slice())
    }

    /// Copies an arbitrary byte slice without parsing it.
    #[must_use]
    pub fn copy_from_slice(bytes: &[u8]) -> Self {
        Self(Box::from(bytes))
    }

    /// Borrows the exact payload bytes.
    #[must_use]
    pub fn as_bytes(&self) -> &[u8] {
        &self.0
    }

    /// Transfers ownership of the exact payload bytes.
    #[must_use]
    pub fn into_bytes(self) -> Box<[u8]> {
        self.0
    }
}

/// A validated, namespaced provider-extension payload.
///
/// `namespace` and `kind` print in full: they are the routing key a hook
/// matches on, and a rendering that hid them would be useless. `data` inherits
/// [`Payload`]'s size-only rendering.
///
/// # Equality
///
/// Field by field: same namespace, same kind, and a [`Payload`] equal by the
/// byte-wise rule that type documents. Validation accepts the payload without
/// normalizing it, so equality is **not** JSON equality — `{"a":1}` and
/// `{ "a" : 1 }` are both valid, mean the same thing to whoever wrote them, and
/// are two different envelopes here. Reading them as one would require core to
/// own a JSON value model, decide key order, duplicate keys and number
/// normalization, and thereby interpret the channel it exists in order not to
/// interpret.
///
/// ```
/// use reef_core::opaque;
///
/// let envelope = |data: &[u8]| {
///     opaque::Envelope::try_new(
///         "example.compat".to_owned(),
///         "matrix".to_owned(),
///         opaque::Payload::copy_from_slice(data),
///     )
///     .unwrap()
/// };
///
/// assert_eq!(envelope(br#"{"a":1}"#), envelope(br#"{"a":1}"#));
/// // Same JSON to a provider; different bytes, so a different envelope.
/// assert_ne!(envelope(br#"{"a":1}"#), envelope(br#"{ "a" : 1 }"#));
/// ```
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Envelope {
    namespace: String,
    kind: String,
    data: Payload,
}

/// A stable envelope-shape validation error.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum EnvelopeError {
    /// The namespace is empty.
    EmptyNamespace,
    /// The provider-defined kind is empty.
    EmptyKind,
    /// The payload has no bytes.
    EmptyData,
    /// The payload is not syntactically valid JSON.
    InvalidJson,
}

impl Display for EnvelopeError {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
        formatter.write_str(match self {
            Self::EmptyNamespace => "opaque envelope namespace is empty",
            Self::EmptyKind => "opaque envelope kind is empty",
            Self::EmptyData => "opaque envelope data is empty",
            Self::InvalidJson => "opaque envelope data is not valid JSON",
        })
    }
}

impl Error for EnvelopeError {}

impl Envelope {
    /// Creates an envelope after validating only its portable outer shape.
    ///
    /// Validation is a syntax boundary and nothing more: namespace, kind, and
    /// data are non-empty, and data must be syntactically valid JSON. That
    /// boundary accepts non-UTF-8 bytes inside quoted strings, rejects more
    /// than 10,000 nested containers, and never normalizes the retained bytes.
    ///
    /// # Errors
    ///
    /// The four conditions are checked in this order, so the first one that holds
    /// is the one reported.
    ///
    /// - [`EnvelopeError::EmptyNamespace`] if `namespace` has no characters.
    /// - [`EnvelopeError::EmptyKind`] if `kind` has no characters.
    /// - [`EnvelopeError::EmptyData`] if `data` carries no bytes. An envelope
    ///   whose payload says nothing is not a payload; a namespace and kind alone
    ///   are routing, not content.
    /// - [`EnvelopeError::InvalidJson`] if `data` is not syntactically valid JSON
    ///   by the boundary above — including one nested more than 10,000 containers
    ///   deep, which that boundary rejects rather than accepting unbounded
    ///   recursion.
    ///
    /// Nothing here inspects what the namespace *means*: an envelope no hook
    /// recognises is valid, and recognising one is composition-layer policy.
    pub fn try_new(namespace: String, kind: String, data: Payload) -> Result<Self, EnvelopeError> {
        if namespace.is_empty() {
            return Err(EnvelopeError::EmptyNamespace);
        }
        if kind.is_empty() {
            return Err(EnvelopeError::EmptyKind);
        }
        if data.as_bytes().is_empty() {
            return Err(EnvelopeError::EmptyData);
        }
        if !valid_json(data.as_bytes()) {
            return Err(EnvelopeError::InvalidJson);
        }
        Ok(Self {
            namespace,
            kind,
            data,
        })
    }

    /// Returns the provider namespace.
    #[must_use]
    pub fn namespace(&self) -> &str {
        &self.namespace
    }

    /// Returns the provider-defined payload kind.
    #[must_use]
    pub fn kind(&self) -> &str {
        &self.kind
    }

    /// Returns the exact validated payload bytes.
    #[must_use]
    pub const fn data(&self) -> &Payload {
        &self.data
    }

    /// Transfers ownership of all envelope parts.
    #[must_use]
    pub fn into_parts(self) -> (String, String, Payload) {
        (self.namespace, self.kind, self.data)
    }
}

// The nesting bound of the syntax boundary a payload is validated against: deep
// enough that no real provider extension reaches it, shallow enough that a
// hostile one cannot drive the validator into unbounded recursion.
const MAX_JSON_DEPTH: usize = 10_000;

#[derive(Clone, Copy)]
enum State {
    RootValue,
    RootDone,
    ArrayFirst,
    ArrayValue,
    ArraySeparator,
    ObjectFirst,
    ObjectKey,
    ObjectColon,
    ObjectValue,
    ObjectSeparator,
}

fn valid_json(bytes: &[u8]) -> bool {
    let mut parser = JsonParser {
        bytes,
        position: 0,
        states: vec![State::RootValue],
    };
    parser.parse()
}

struct JsonParser<'a> {
    bytes: &'a [u8],
    position: usize,
    states: Vec<State>,
}

impl JsonParser<'_> {
    fn parse(&mut self) -> bool {
        loop {
            self.skip_whitespace();
            match *self.states.last().expect("root state is retained") {
                State::RootValue => {
                    if !self.parse_value(State::RootDone) {
                        return false;
                    }
                }
                State::RootDone => return self.position == self.bytes.len(),
                State::ArrayFirst => {
                    if self.take(b']') {
                        self.states.pop();
                    } else if !self.parse_value(State::ArraySeparator) {
                        return false;
                    }
                }
                State::ArrayValue => {
                    if !self.parse_value(State::ArraySeparator) {
                        return false;
                    }
                }
                State::ArraySeparator => {
                    if self.take(b',') {
                        *self.states.last_mut().expect("state exists") = State::ArrayValue;
                    } else if self.take(b']') {
                        self.states.pop();
                    } else {
                        return false;
                    }
                }
                State::ObjectFirst => {
                    if self.take(b'}') {
                        self.states.pop();
                    } else {
                        *self.states.last_mut().expect("state exists") = State::ObjectKey;
                    }
                }
                State::ObjectKey => {
                    if !self.parse_string() {
                        return false;
                    }
                    *self.states.last_mut().expect("state exists") = State::ObjectColon;
                }
                State::ObjectColon => {
                    if !self.take(b':') {
                        return false;
                    }
                    *self.states.last_mut().expect("state exists") = State::ObjectValue;
                }
                State::ObjectValue => {
                    if !self.parse_value(State::ObjectSeparator) {
                        return false;
                    }
                }
                State::ObjectSeparator => {
                    if self.take(b',') {
                        *self.states.last_mut().expect("state exists") = State::ObjectKey;
                    } else if self.take(b'}') {
                        self.states.pop();
                    } else {
                        return false;
                    }
                }
            }
        }
    }

    fn parse_value(&mut self, next: State) -> bool {
        self.skip_whitespace();
        *self.states.last_mut().expect("state exists") = next;
        match self.peek() {
            Some(b'{') => {
                self.position += 1;
                self.push_container(State::ObjectFirst)
            }
            Some(b'[') => {
                self.position += 1;
                self.push_container(State::ArrayFirst)
            }
            Some(b'"') => self.parse_string(),
            Some(b't') => self.parse_literal(b"true"),
            Some(b'f') => self.parse_literal(b"false"),
            Some(b'n') => self.parse_literal(b"null"),
            Some(b'-' | b'0'..=b'9') => self.parse_number(),
            _ => false,
        }
    }

    fn push_container(&mut self, state: State) -> bool {
        if self.states.len() > MAX_JSON_DEPTH {
            return false;
        }
        self.states.push(state);
        true
    }

    fn parse_literal(&mut self, literal: &[u8]) -> bool {
        if self.bytes[self.position..].starts_with(literal) {
            self.position += literal.len();
            true
        } else {
            false
        }
    }

    fn parse_string(&mut self) -> bool {
        if !self.take(b'"') {
            return false;
        }
        while let Some(byte) = self.peek() {
            self.position += 1;
            match byte {
                b'"' => return true,
                b'\\' => match self.peek() {
                    Some(b'"' | b'\\' | b'/' | b'b' | b'f' | b'n' | b'r' | b't') => {
                        self.position += 1;
                    }
                    Some(b'u') => {
                        self.position += 1;
                        for _ in 0..4 {
                            if !self.peek().is_some_and(|digit| digit.is_ascii_hexdigit()) {
                                return false;
                            }
                            self.position += 1;
                        }
                    }
                    _ => return false,
                },
                0..=0x1f => return false,
                _ => {}
            }
        }
        false
    }

    fn parse_number(&mut self) -> bool {
        if self.take(b'-') && self.peek().is_none() {
            return false;
        }
        match self.peek() {
            Some(b'0') => self.position += 1,
            Some(b'1'..=b'9') => self.take_digits(),
            _ => return false,
        }
        if self.take(b'.') {
            if !self.peek().is_some_and(|byte| byte.is_ascii_digit()) {
                return false;
            }
            self.take_digits();
        }
        if matches!(self.peek(), Some(b'e' | b'E')) {
            self.position += 1;
            if matches!(self.peek(), Some(b'+' | b'-')) {
                self.position += 1;
            }
            if !self.peek().is_some_and(|byte| byte.is_ascii_digit()) {
                return false;
            }
            self.take_digits();
        }
        true
    }

    fn take_digits(&mut self) {
        while self.peek().is_some_and(|byte| byte.is_ascii_digit()) {
            self.position += 1;
        }
    }

    fn skip_whitespace(&mut self) {
        while matches!(self.peek(), Some(b' ' | b'\n' | b'\r' | b'\t')) {
            self.position += 1;
        }
    }

    fn take(&mut self, expected: u8) -> bool {
        if self.peek() == Some(expected) {
            self.position += 1;
            true
        } else {
            false
        }
    }

    fn peek(&self) -> Option<u8> {
        self.bytes.get(self.position).copied()
    }
}

/// The serialized form of [`Payload`] and [`Envelope`] (ADR-019 D5).
///
/// A payload is a byte string with no wrapper around it, because the wrapper is
/// a Rust representation detail. An envelope is the three fields `namespace`,
/// `kind` and `data`, and reading one re-runs [`Envelope::try_new`]: a session
/// file is untrusted input, so the validator that guards the call site guards the
/// file too.
#[cfg(feature = "serde")]
mod serde_impl {
    use std::fmt::{self, Formatter};

    use serde_core::de::{Deserialize, Deserializer, Error as _, MapAccess, SeqAccess, Visitor};
    use serde_core::ser::{Serialize, SerializeStruct, Serializer};

    use super::{Envelope, Payload};
    use crate::wire::{self, ByteBuf, Bytes, IdentifierSeed};

    const ENVELOPE_FIELDS: &[&str] = &["namespace", "kind", "data"];

    impl Serialize for Payload {
        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
        where
            S: Serializer,
        {
            Bytes(&self.0).serialize(serializer)
        }
    }

    impl<'de> Deserialize<'de> for Payload {
        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
        where
            D: Deserializer<'de>,
        {
            ByteBuf::deserialize(deserializer).map(|buffer| Self(buffer.0))
        }
    }

    impl Serialize for Envelope {
        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
        where
            S: Serializer,
        {
            let mut record = serializer.serialize_struct("Envelope", 3)?;
            record.serialize_field("namespace", &self.namespace)?;
            record.serialize_field("kind", &self.kind)?;
            record.serialize_field("data", &self.data)?;
            record.end()
        }
    }

    impl<'de> Deserialize<'de> for Envelope {
        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
        where
            D: Deserializer<'de>,
        {
            deserializer.deserialize_struct("Envelope", ENVELOPE_FIELDS, EnvelopeVisitor)
        }
    }

    struct EnvelopeVisitor;

    impl EnvelopeVisitor {
        fn build<E>(namespace: String, kind: String, data: Payload) -> Result<Envelope, E>
        where
            E: serde_core::de::Error,
        {
            Envelope::try_new(namespace, kind, data).map_err(E::custom)
        }
    }

    impl<'de> Visitor<'de> for EnvelopeVisitor {
        type Value = Envelope;

        fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
            formatter.write_str("an opaque envelope")
        }

        fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
        where
            A: SeqAccess<'de>,
        {
            let namespace = wire::element(&mut sequence, 0)?;
            let kind = wire::element(&mut sequence, 1)?;
            let data = wire::element(&mut sequence, 2)?;
            wire::end(&mut sequence, 3)?;
            Self::build(namespace, kind, data)
        }

        fn visit_map<A>(self, mut entries: A) -> Result<Self::Value, A::Error>
        where
            A: MapAccess<'de>,
        {
            let mut namespace = None;
            let mut kind = None;
            let mut data = None;
            while let Some(field) = entries.next_key_seed(IdentifierSeed(ENVELOPE_FIELDS))? {
                match field.0.as_str() {
                    "namespace" => {
                        wire::accept(&mut namespace, entries.next_value()?, "namespace")?
                    }
                    "kind" => wire::accept(&mut kind, entries.next_value()?, "kind")?,
                    "data" => wire::accept(&mut data, entries.next_value()?, "data")?,
                    unknown => return Err(A::Error::unknown_field(unknown, ENVELOPE_FIELDS)),
                }
            }
            Self::build(
                wire::require(namespace, "namespace")?,
                wire::require(kind, "kind")?,
                wire::require(data, "data")?,
            )
        }
    }
}

#[cfg(test)]
#[path = "opaque_tests.rs"]
mod opaque_tests;