objectiveai_sdk/cli/command/agents/instances/list/
mod.rs

1//! `agents instances list` — enumerate agent instances under one or
2//! more targets, reporting per-agent aggregates (tags, queued count,
3//! spawn/active timestamps, total logged messages).
4
5use crate::cli::command::CommandRequest;
6
7/// Reuse the shared `--target` enum (`instance=L[,parent=P]`, `tag=T`,
8/// `me`) from `agents logs read all`. Each target resolves to an AIH
9/// whose direct children this command lists.
10pub use super::super::logs::read::all::Target;
11
12#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
13#[schemars(rename = "cli.command.agents.instances.list.Request")]
14pub struct Request {
15    pub path_type: Path,
16    pub targets: Vec<Target>,
17    #[serde(flatten)]
18    pub base: crate::cli::command::RequestBase,
19}
20
21#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
22#[schemars(rename = "cli.command.agents.instances.list.Path")]
23pub enum Path {
24    #[serde(rename = "agents/instances/list")]
25    AgentsInstancesList,
26}
27
28impl CommandRequest for Request {
29    fn into_command(&self) -> Vec<String> {
30        let mut argv = vec![
31            "agents".to_string(),
32            "instances".to_string(),
33            "list".to_string(),
34        ];
35        for target in &self.targets {
36            argv.push("--target".to_string());
37            argv.push(target.into_arg_string());
38        }
39        self.base.push_flags(&mut argv);
40        argv
41    }
42
43    fn request_base(&self) -> &crate::cli::command::RequestBase {
44        &self.base
45    }
46
47    fn request_base_mut(&mut self) -> Option<&mut crate::cli::command::RequestBase> {
48        Some(&mut self.base)
49    }
50}
51
52/// One discovered agent instance under a target. Aggregated from the
53/// `logs.messages`, `message_queue`, and `tags` tiers.
54#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
55#[schemars(rename = "cli.command.agents.instances.list.ResponseItem")]
56pub struct ResponseItem {
57    /// Full hierarchy of this agent instance.
58    pub agent_instance_hierarchy: String,
59    /// Tag names currently bound to this AIH, newest-bound first.
60    pub tags: Vec<String>,
61    /// Active `message_queue` rows targeting this agent — counting
62    /// both direct-AIH rows and rows whose tag is bound to this AIH.
63    pub queued: u64,
64    /// Timestamp of the first `logs.messages` row for this agent.
65    /// `None` when the agent has no logs yet (queue-only).
66    #[serde(default, skip_serializing_if = "Option::is_none")]
67    #[schemars(extend("omitempty" = true))]
68    pub timestamp_spawned: Option<i64>,
69    /// Timestamp of the most recent `logs.messages` row for this
70    /// agent. `None` when the agent has no logs yet (queue-only).
71    #[serde(default, skip_serializing_if = "Option::is_none")]
72    #[schemars(extend("omitempty" = true))]
73    pub timestamp_active: Option<i64>,
74    /// Total `logs.messages` rows for this agent over all time.
75    pub logged: u64,
76}
77
78#[derive(clap::Args)]
79pub struct Args {
80    /// One or more `--target instance=L[,parent=P]` entries. Also
81    /// accepts `--target tag=T` and `--target me`. Lists the direct
82    /// children of each resolved target.
83    #[arg(long = "target", required = true)]
84    pub targets: Vec<String>,
85    #[command(flatten)]
86    pub base: crate::cli::command::RequestBaseArgs,
87}
88
89#[derive(clap::Args)]
90#[command(args_conflicts_with_subcommands = true)]
91pub struct Command {
92    #[command(flatten)]
93    pub args: Args,
94    #[command(subcommand)]
95    pub schema: Option<Schema>,
96}
97
98#[derive(clap::Subcommand)]
99pub enum Schema {
100    /// Emit the JSON Schema for this leaf's `Request` type and exit.
101    RequestSchema(request_schema::Args),
102    /// Emit the JSON Schema for this leaf's `Response` type and exit.
103    ResponseSchema(response_schema::Args),
104}
105
106impl TryFrom<Args> for Request {
107    type Error = crate::cli::command::FromArgsError;
108    fn try_from(args: Args) -> Result<Self, Self::Error> {
109        let targets = args
110            .targets
111            .iter()
112            .map(|s| {
113                s.parse::<Target>().map_err(|msg| {
114                    crate::cli::command::FromArgsError::path_parse("target", msg)
115                })
116            })
117            .collect::<Result<Vec<_>, _>>()?;
118        Ok(Self {
119            path_type: Path::AgentsInstancesList,
120            targets,
121            base: args.base.into(),
122        })
123    }
124}
125
126#[cfg(feature = "cli-executor")]
127pub async fn execute<E: crate::cli::command::CommandExecutor>(
128    executor: &E,
129    mut request: Request,
130
131        agent_arguments: Option<&crate::cli::command::AgentArguments>,
132    ) -> Result<E::Stream<ResponseItem>, E::Error> {
133    request.base.clear_transform();
134    executor.execute(request, agent_arguments).await
135}
136
137#[cfg(feature = "cli-executor")]
138pub async fn execute_transform<E: crate::cli::command::CommandExecutor>(
139    executor: &E,
140    mut request: Request,
141    transform: crate::cli::command::Transform,
142
143        agent_arguments: Option<&crate::cli::command::AgentArguments>,
144    ) -> Result<E::Stream<serde_json::Value>, E::Error> {
145    request.base.set_transform(transform);
146    executor.execute(request, agent_arguments).await
147}
148
149#[cfg(feature = "mcp")]
150impl crate::cli::command::CommandResponse for ResponseItem {
151    fn into_mcp(self) -> crate::cli::command::McpResponseItem {
152        crate::cli::command::McpResponseItem::JSONL(serde_json::to_value(self).unwrap())
153    }
154}
155
156pub mod request_schema;
157
158
159pub mod response_schema;
objectiveai_sdk/cli/command/agents/instances/list/mod.rs

objectiveai_sdk/cli/command/agents/instances/list/
mod.rs
