Skip to main content

objectiveai_sdk/cli/command/channels/logs/list/
mod.rs

1//! `channels logs list` — the channel's message log as ENVELOPES
2//! (id, timestamp, kind, writer identity); the arbitrary-JSON content
3//! is revealed only by `channels logs open`. `--all` lists every
4//! entry; `--pending` lists only the entries THIS role hasn't read
5//! (messages from the other side past its watermark) and advances the
6//! watermark. Authenticate with a channel secret (`S_pub` or
7//! `S_owner`) — the daemon infers the role.
8
9use crate::cli::command::CommandRequest;
10
11/// What a stored entry IS — `request` is publisher→owner, `reply` is
12/// owner→publisher, and the two `publish*` kinds are the accept-time
13/// SEED rows holding the offer (`publish` = the details,
14/// `publish_message` = the human message; the pair surfaces in
15/// [`ChannelLogEntry`] as ONE `publish` item). Retained for
16/// [`super::open`]'s flat entry; [`ChannelLogEntry`] is split into an
17/// enum along this same axis.
18#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
19#[serde(rename_all = "snake_case")]
20#[schemars(rename = "cli.command.channels.logs.list.MessageKind")]
21pub enum MessageKind {
22    Request,
23    Reply,
24    Publish,
25    PublishMessage,
26}
27
28/// One channel-log entry ENVELOPE — no content (open reveals that).
29/// Identity is INLINE and daemon-authored (unspoofable). The kinds
30/// are ASYMMETRIC in identity and shape, so the entry is an enum
31/// tagged by `kind`:
32///
33/// - `publish` (the accept-time seed, every channel's FIRST entry):
34///   the offer itself — `details_id` opens the offer details,
35///   `message_id` opens the human message. Publisher-authored, so
36///   the plugin trio is REQUIRED.
37/// - `request` (publisher→owner): the publisher is a PLUGIN — the
38///   plugin trio is REQUIRED.
39/// - `reply` (owner→publisher): the replier is never a plugin — no
40///   plugin trio at all.
41#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
42#[serde(tag = "kind", rename_all = "snake_case")]
43#[schemars(rename = "cli.command.channels.logs.list.ChannelLogEntry")]
44pub enum ChannelLogEntry {
45    /// The channel's offer, seeded at accept — ONE per channel, its
46    /// first entry. Two openable ids so a reader pulls the bulky
47    /// parts only when it wants them.
48    #[schemars(title = "Publish")]
49    Publish {
50        /// The DETAILS entry id — `channels logs open` reveals the
51        /// offer's `details` JSON. Also the `--after-id` cursor.
52        details_id: i64,
53        /// The MESSAGE entry id — `channels logs open` reveals the
54        /// offer's human-readable message.
55        message_id: i64,
56        /// RFC3339 delivery time (the channel's accept time).
57        timestamp: String,
58        /// The AIH of the publishing agent (always present — the
59        /// daemon defaults it).
60        sender_agent_instance_hierarchy: String,
61        /// The originating plugin (owner/repository/version) — always
62        /// present: a channel's publisher is a plugin.
63        plugin_owner: String,
64        plugin_name: String,
65        plugin_version: String,
66    },
67    /// A publisher→owner message. The publisher is a plugin, so the
68    /// originating plugin trio is always present.
69    #[schemars(title = "Request")]
70    Request {
71        /// The entry's `channel_messages.id` — the cursor for
72        /// `--after-id` and the `--entry-id` for `channels logs open`
73        /// (revealing the entry's content).
74        details_id: i64,
75        /// RFC3339 delivery time.
76        timestamp: String,
77        /// The AIH of the agent that sent the entry (always present —
78        /// the daemon defaults it).
79        sender_agent_instance_hierarchy: String,
80        /// The originating plugin (owner/repository/version) — always
81        /// present: a channel's requester is a plugin.
82        plugin_owner: String,
83        plugin_name: String,
84        plugin_version: String,
85    },
86    /// An owner→publisher message. The replier is typically not a
87    /// plugin, so the plugin trio is OPTIONAL — present only when a
88    /// plugin happened to send the reply.
89    #[schemars(title = "Reply")]
90    Reply {
91        /// The entry's `channel_messages.id` — the cursor for
92        /// `--after-id` and the `--entry-id` for `channels logs open`
93        /// (revealing the entry's content).
94        details_id: i64,
95        /// RFC3339 delivery time.
96        timestamp: String,
97        /// The AIH of the agent that sent the entry (always present —
98        /// the daemon defaults it).
99        sender_agent_instance_hierarchy: String,
100        /// The originating plugin (owner/repository/version) — present
101        /// only when a plugin sent the reply.
102        #[serde(default, skip_serializing_if = "Option::is_none")]
103        #[schemars(extend("omitempty" = true))]
104        plugin_owner: Option<String>,
105        #[serde(default, skip_serializing_if = "Option::is_none")]
106        #[schemars(extend("omitempty" = true))]
107        plugin_name: Option<String>,
108        #[serde(default, skip_serializing_if = "Option::is_none")]
109        #[schemars(extend("omitempty" = true))]
110        plugin_version: Option<String>,
111    },
112}
113
114#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
115#[schemars(rename = "cli.command.channels.logs.list.Request")]
116pub struct Request {
117    pub path_type: Path,
118    pub channel_id: String,
119    pub secret: String,
120    /// `true` = `--pending` (unread for this role, advances the
121    /// watermark); `false` = `--all`.
122    pub pending: bool,
123    /// Skip entries with `id <= after_id`.
124    #[serde(default, skip_serializing_if = "Option::is_none")]
125    #[schemars(extend("omitempty" = true))]
126    pub after_id: Option<i64>,
127    /// Cap on entries returned.
128    #[serde(default, skip_serializing_if = "Option::is_none")]
129    #[schemars(extend("omitempty" = true))]
130    pub limit: Option<i64>,
131    #[serde(flatten)]
132    pub base: crate::cli::command::RequestBase,
133}
134
135#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
136#[schemars(rename = "cli.command.channels.logs.list.Path")]
137pub enum Path {
138    #[serde(rename = "channels/logs/list")]
139    ChannelsLogsList,
140}
141
142impl CommandRequest for Request {
143    fn request_base(&self) -> &crate::cli::command::RequestBase {
144        &self.base
145    }
146
147    fn request_base_mut(&mut self) -> Option<&mut crate::cli::command::RequestBase> {
148        Some(&mut self.base)
149    }
150}
151
152/// The listed entries, ascending by id.
153#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
154#[schemars(rename = "cli.command.channels.logs.list.Response")]
155pub struct Response {
156    pub entries: Vec<ChannelLogEntry>,
157}
158
159#[derive(clap::Args)]
160#[command(group(clap::ArgGroup::new("channel_required").required(true).args(["id"])))]
161#[command(group(clap::ArgGroup::new("secret_required").required(true).args(["secret"])))]
162#[command(group(clap::ArgGroup::new("list_mode").required(true).multiple(false).args(["all", "pending"])))]
163pub struct Args {
164    /// The channel id.
165    #[arg(long)]
166    pub id: Option<String>,
167    /// A channel secret (`S_pub` or `S_owner`).
168    #[arg(long)]
169    pub secret: Option<String>,
170    /// List every entry.
171    #[arg(long)]
172    pub all: bool,
173    /// List only the entries this role hasn't read (advances the
174    /// watermark).
175    #[arg(long)]
176    pub pending: bool,
177    /// Skip entries with id <= after_id.
178    #[arg(long)]
179    pub after_id: Option<i64>,
180    /// Cap on entries returned.
181    #[arg(long)]
182    pub limit: Option<i64>,
183    #[command(flatten)]
184    pub base: crate::cli::command::RequestBaseArgs,
185}
186
187#[derive(clap::Args)]
188#[command(args_conflicts_with_subcommands = true)]
189pub struct Command {
190    #[command(flatten)]
191    pub args: Args,
192    #[command(subcommand)]
193    pub schema: Option<Schema>,
194}
195
196#[derive(clap::Subcommand)]
197pub enum Schema {
198    /// Emit the JSON Schema for this leaf's `Request` type and exit.
199    RequestSchema(request_schema::Args),
200    /// Emit the JSON Schema for this leaf's `Response` type and exit.
201    ResponseSchema(response_schema::Args),
202}
203
204impl TryFrom<Args> for Request {
205    type Error = crate::cli::command::FromArgsError;
206    fn try_from(args: Args) -> Result<Self, Self::Error> {
207        let channel_id = args.id.ok_or_else(|| {
208            crate::cli::command::FromArgsError::path_parse("id", "--id is required".to_string())
209        })?;
210        let secret = args.secret.ok_or_else(|| {
211            crate::cli::command::FromArgsError::path_parse(
212                "secret",
213                "--secret is required".to_string(),
214            )
215        })?;
216        // The ArgGroup guarantees exactly one of --all/--pending.
217        Ok(Self {
218            path_type: Path::ChannelsLogsList,
219            channel_id,
220            secret,
221            pending: args.pending,
222            after_id: args.after_id,
223            limit: args.limit,
224            base: args.base.into(),
225        })
226    }
227}
228
229#[cfg(feature = "mcp")]
230impl crate::cli::command::CommandResponse for Response {
231    fn into_mcp(self) -> crate::cli::command::McpResponseItem {
232        crate::cli::command::McpResponseItem::JSONL(serde_json::to_value(self).unwrap())
233    }
234}
235
236#[cfg(feature = "cli-executor")]
237pub async fn execute<E: crate::cli::command::CommandExecutor>(
238    executor: &E,
239    mut request: Request,
240    identity: Option<&crate::identity::Identity>,
241) -> Result<Response, E::Error> {
242    request.base.clear_transform();
243    executor.execute_one(request, identity).await
244}
245
246#[cfg(feature = "cli-executor")]
247pub async fn execute_transform<E: crate::cli::command::CommandExecutor>(
248    executor: &E,
249    mut request: Request,
250    transform: crate::cli::command::Transform,
251    identity: Option<&crate::identity::Identity>,
252) -> Result<serde_json::Value, E::Error> {
253    request.base.set_transform(transform);
254    executor.execute_one(request, identity).await
255}
256
257pub mod request_schema;
258
259pub mod response_schema;
260
261/// See [`crate::daemon::command_listener`].
262#[cfg(all(feature = "cli", feature = "daemon"))]
263pub struct ListenerExecution {
264    pub request: Request,
265    pub identity: crate::identity::Identity,
266    pub response: crate::daemon::command_listener::UnaryResponse<Response>,
267}