mirror of
https://github.com/openai/codex.git
synced 2026-11-18 22:20:48 +00:00
## Why A fixed evidence view hides posts routed after the review cutoff. Live retrieval lets reviewers find those posts as they arrive while still allowing intake to confirm that evidence through a requested history position has been routed. ## What changed Guardian retrieval tools search the live message board, including channels the reviewer does not subscribe to. Subscription tools update only the acting reviewer's subscriptions. The housekeeper uses the subscribers present at each post's insertion to queue one committed post per original in each recipient's inbox, even when multiple subscribed channels match. It acknowledges catch-up requests after routing and queuing evidence through the requested history position. ## Testing Cover catch-up ordering, delivery based on subscription state at insertion, live search across unsubscribed channels, and caller-scoped subscription changes. GitOrigin-RevId: 28b447d936f19ea68bd3c3adb297d473d65173c0
336 lines
11 KiB
Rust
336 lines
11 KiB
Rust
//! Operations on one board. Requests describe intent independently of tool schemas.
|
|
//! Channel descriptions enforce their byte limit at construction and deserialization.
|
|
|
|
use crate::BoardReadView;
|
|
use crate::ChannelPage;
|
|
use crate::ChannelSummary;
|
|
use crate::Page;
|
|
use crate::PostContent;
|
|
use crate::PostMetadata;
|
|
use crate::PostPreview;
|
|
use crate::SubscriptionState;
|
|
use crate::ThreadPage;
|
|
use crate::ThreadSummary;
|
|
use codex_protocol::AgentPath;
|
|
use codex_protocol::SessionId;
|
|
use codex_protocol::ThreadId;
|
|
use codex_protocol::error::CodexErr;
|
|
use codex_protocol::error::Result;
|
|
use futures::future::BoxFuture;
|
|
use serde::Deserialize;
|
|
use serde::Serialize;
|
|
use std::collections::BTreeMap;
|
|
use std::num::NonZeroU32;
|
|
use std::sync::Arc;
|
|
use uuid::Uuid;
|
|
|
|
// Local and remote implementations must remain usable through the same handle.
|
|
const _: Option<&dyn AgentMessageBoard> = None;
|
|
|
|
/// Stores discussions and subscriptions for one board.
|
|
///
|
|
/// Every operation validates caller membership. IDs are scoped to this board;
|
|
/// an agent runtime's ThreadId is distinct from a discussion's root post UUID.
|
|
/// Mutation success acknowledges acceptance, not that recipients read a post.
|
|
/// Implementations enforce hard input/output limits and return backend failures
|
|
/// as errors. They own atomic subscription changes, posting and recipient
|
|
/// selection, excluding the post author even when explicitly targeted.
|
|
/// Notification delivery follows the host's scheduling and wake policy and may
|
|
/// be buffered for an idle recipient; see [`crate::MessageBoardHost`].
|
|
///
|
|
/// Boxed Send futures support an Arc<dyn AgentMessageBoard>, like AgentControl.
|
|
pub trait AgentMessageBoard: Send + Sync {
|
|
fn identity(&self) -> SessionId;
|
|
|
|
/// The host-selected storage namespace, if this backend identifies one.
|
|
fn storage_namespace(&self) -> Option<&str> {
|
|
None
|
|
}
|
|
|
|
/// Return a live handle with literal search inside JSON encoded at this JSON pointer.
|
|
/// Other handles retain their existing search behavior.
|
|
fn with_json_search(&self, _pointer: &'static str) -> Result<Arc<dyn AgentMessageBoard>> {
|
|
Err(CodexErr::UnsupportedOperation(
|
|
"searching nested JSON on a live message board".into(),
|
|
))
|
|
}
|
|
|
|
/// Capture a live board's channel summaries and post boundary together for read-only access.
|
|
fn read_view(&self, _caller: ThreadId) -> BoxFuture<'_, Result<Arc<dyn BoardReadView>>> {
|
|
unsupported("capturing a board read view")
|
|
}
|
|
|
|
fn create_channel(
|
|
&self,
|
|
caller: ThreadId,
|
|
request: CreateChannelRequest,
|
|
) -> BoxFuture<'_, Result<ChannelSummary>>;
|
|
|
|
/// Creates a channel or replaces only its description. Preserves existing
|
|
/// posts, authorship, creation time and subscriptions; never sends notices.
|
|
/// Backends without upsert support must reject this rather than substitute creation.
|
|
fn upsert_channel(
|
|
&self,
|
|
caller: ThreadId,
|
|
request: UpsertChannelRequest,
|
|
) -> BoxFuture<'_, Result<()>>;
|
|
|
|
fn list_channels(
|
|
&self,
|
|
caller: ThreadId,
|
|
query: ChannelQuery,
|
|
) -> BoxFuture<'_, Result<ChannelPage>>;
|
|
|
|
/// Uses the caller's configured clock; clock failures must not create a post.
|
|
/// The request ID identifies a logical call across retries. A retry with
|
|
/// different input is an error; a successful retry returns the same metadata.
|
|
/// Creating a channel while posting also subscribes its author to new roots there.
|
|
fn post(&self, caller: ThreadId, request: PostRequest) -> BoxFuture<'_, Result<PostMetadata>>;
|
|
|
|
/// Writes without automatic subscriptions or notifications. Uses caller-scoped
|
|
/// retry IDs shared with posting; changing the operation or payload is an error.
|
|
/// Backends without silent-write support must reject this, never fall back to posting.
|
|
fn append(
|
|
&self,
|
|
caller: ThreadId,
|
|
request: AppendRequest,
|
|
) -> BoxFuture<'_, Result<PostMetadata>>;
|
|
|
|
/// Like a silent append, also returns the subscribers at the moment of insertion.
|
|
/// An idempotent retry returns the existing post and no new deliveries.
|
|
fn append_with_subscribers(
|
|
&self,
|
|
_caller: ThreadId,
|
|
_request: AppendRequest,
|
|
) -> BoxFuture<'_, Result<(PostMetadata, Vec<ThreadId>)>> {
|
|
unsupported("appending with subscribers")
|
|
}
|
|
|
|
fn list_threads(
|
|
&self,
|
|
caller: ThreadId,
|
|
query: ThreadQuery,
|
|
) -> BoxFuture<'_, Result<Page<ThreadSummary>>>;
|
|
|
|
fn search_posts(
|
|
&self,
|
|
caller: ThreadId,
|
|
query: PostQuery,
|
|
) -> BoxFuture<'_, Result<Page<PostPreview>>>;
|
|
|
|
fn read_thread(
|
|
&self,
|
|
caller: ThreadId,
|
|
request: ReadThreadRequest,
|
|
) -> BoxFuture<'_, Result<ThreadPage>>;
|
|
|
|
fn read_post(
|
|
&self,
|
|
caller: ThreadId,
|
|
request: ReadPostRequest,
|
|
) -> BoxFuture<'_, Result<PostContent>>;
|
|
|
|
/// Channel subscriptions concern new roots; thread subscriptions concern
|
|
/// replies. Changing one does not change the other. Any member may change
|
|
/// another member's subscription. Posting subscribes its author to the thread
|
|
/// by default, but preserves an explicit unsubscribe until subscribed again.
|
|
fn set_subscription(
|
|
&self,
|
|
caller: ThreadId,
|
|
request: SubscriptionRequest,
|
|
) -> BoxFuture<'_, Result<SubscriptionState>>;
|
|
|
|
/// List a caller's current channel subscriptions on a live board.
|
|
fn subscribed_channels(
|
|
&self,
|
|
_caller: ThreadId,
|
|
_page: PageRequest,
|
|
) -> BoxFuture<'_, Result<Page<String>>> {
|
|
unsupported("listing channel subscriptions")
|
|
}
|
|
|
|
/// Set the caller's membership in the supplied channels as one atomic change.
|
|
/// Other channels and thread subscriptions retain their current membership.
|
|
fn set_subscriptions<'a>(
|
|
&'a self,
|
|
_caller: ThreadId,
|
|
_channels: &'a BTreeMap<&str, SubscriptionChange>,
|
|
) -> BoxFuture<'a, Result<()>> {
|
|
unsupported("setting channel subscriptions in bulk")
|
|
}
|
|
}
|
|
|
|
fn unsupported<T>(operation: &'static str) -> BoxFuture<'static, Result<T>> {
|
|
Box::pin(async move { Err(CodexErr::UnsupportedOperation(operation.into())) })
|
|
}
|
|
|
|
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
|
pub struct PageRequest {
|
|
pub cursor: Option<String>,
|
|
pub limit: NonZeroU32,
|
|
}
|
|
|
|
impl Default for PageRequest {
|
|
fn default() -> Self {
|
|
Self {
|
|
cursor: None,
|
|
limit: NonZeroU32::new(20).unwrap_or(NonZeroU32::MIN),
|
|
}
|
|
}
|
|
}
|
|
|
|
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
|
pub enum SortDirection {
|
|
NewestFirst,
|
|
OldestFirst,
|
|
}
|
|
|
|
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
|
pub enum SubscriptionChange {
|
|
Subscribe,
|
|
Unsubscribe,
|
|
}
|
|
|
|
#[derive(Clone, Debug, Serialize, Deserialize)]
|
|
pub struct CreateChannelRequest {
|
|
pub channel_name: String,
|
|
/// Optional channel purpose, at most 512 UTF-8 bytes.
|
|
#[serde(default, skip_serializing_if = "Option::is_none")]
|
|
pub description: Option<ChannelDescription>,
|
|
pub subscription: SubscriptionChange,
|
|
}
|
|
|
|
/// Creates or updates navigation metadata without changing stored evidence or delivery.
|
|
#[derive(Clone, Debug, Serialize, Deserialize)]
|
|
#[serde(deny_unknown_fields)]
|
|
pub struct UpsertChannelRequest {
|
|
pub channel_name: String,
|
|
pub description: ChannelDescription,
|
|
}
|
|
|
|
/// A channel purpose containing at most 512 UTF-8 bytes.
|
|
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
|
#[serde(try_from = "String")]
|
|
pub struct ChannelDescription(String);
|
|
|
|
impl TryFrom<String> for ChannelDescription {
|
|
type Error = CodexErr;
|
|
|
|
fn try_from(text: String) -> Result<Self> {
|
|
if text.len() > 512 {
|
|
return Err(CodexErr::InvalidRequest(
|
|
"channel descriptions must contain at most 512 UTF-8 bytes".into(),
|
|
));
|
|
}
|
|
Ok(Self(text))
|
|
}
|
|
}
|
|
|
|
impl ChannelDescription {
|
|
pub fn as_str(&self) -> &str {
|
|
&self.0
|
|
}
|
|
}
|
|
|
|
impl From<ChannelDescription> for String {
|
|
fn from(description: ChannelDescription) -> Self {
|
|
description.0
|
|
}
|
|
}
|
|
|
|
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
|
pub struct ChannelQuery {
|
|
pub query: Option<String>,
|
|
pub direction: SortDirection,
|
|
pub page: PageRequest,
|
|
}
|
|
|
|
/// Exactly one destination; discussion threads use their root post's ID.
|
|
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
|
pub enum PostDestination {
|
|
Channel(String),
|
|
NewChannel(String),
|
|
Thread(Uuid),
|
|
}
|
|
|
|
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
|
pub struct PostRequest {
|
|
/// Host-generated tool invocation identity, never a model argument.
|
|
pub request_id: String,
|
|
pub destination: PostDestination,
|
|
pub text: String,
|
|
/// Resolved paths in this board's tree; duplicates notify only once.
|
|
pub agents_to_notify: Vec<AgentPath>,
|
|
}
|
|
|
|
#[derive(Clone, Copy, PartialEq, Eq)]
|
|
pub(crate) enum PostBehavior {
|
|
Discussion,
|
|
SilentAppend,
|
|
SilentAppendWithSubscribers,
|
|
}
|
|
|
|
/// Request to append evidence without subscribing its author or notifying anyone.
|
|
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
|
pub struct AppendRequest {
|
|
/// Caller-scoped invocation identity, shared with posting to reject conflicting retries.
|
|
pub request_id: String,
|
|
pub destination: PostDestination,
|
|
pub text: String,
|
|
}
|
|
|
|
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
|
#[serde(rename_all = "snake_case")]
|
|
pub enum ThreadSort {
|
|
Created,
|
|
Activity,
|
|
}
|
|
|
|
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
|
pub struct ThreadQuery {
|
|
pub channel_name: String,
|
|
pub sort: ThreadSort,
|
|
pub direction: SortDirection,
|
|
pub page: PageRequest,
|
|
pub max_chars_per_post: NonZeroU32,
|
|
}
|
|
|
|
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
|
pub struct PostQuery {
|
|
pub channel_name: Option<String>,
|
|
pub query: Option<String>,
|
|
pub after_message_id: Option<Uuid>,
|
|
pub author: Option<AgentPath>,
|
|
pub page: PageRequest,
|
|
pub max_chars_per_post: NonZeroU32,
|
|
}
|
|
|
|
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
|
pub struct ReadThreadRequest {
|
|
pub thread_id: Uuid,
|
|
pub page: PageRequest,
|
|
pub max_chars_per_post: NonZeroU32,
|
|
}
|
|
|
|
#[derive(Clone, Debug, Serialize, Deserialize)]
|
|
pub struct ReadPostRequest {
|
|
pub message_id: Uuid,
|
|
/// Offsets and lengths count Unicode scalar values, not UTF-8 bytes.
|
|
pub offset_chars: u32,
|
|
pub limit_chars: NonZeroU32,
|
|
}
|
|
|
|
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
|
|
pub enum SubscriptionTarget {
|
|
Channel(String),
|
|
Thread(Uuid),
|
|
}
|
|
|
|
#[derive(Clone, Debug, Serialize, Deserialize)]
|
|
pub struct SubscriptionRequest {
|
|
pub target: SubscriptionTarget,
|
|
/// None changes the caller's subscription.
|
|
pub target_agent: Option<AgentPath>,
|
|
pub change: SubscriptionChange,
|
|
}
|