Skip to main content

agent_client_protocol_schema/v1/
plan.rs

1//! Execution plans for multi-step tasks.
2//!
3//! A plan is the agent's list of steps for a task. Agents send plans to clients
4//! through session updates and update them as work progresses.
5//!
6//! See: [Agent Plan](https://agentclientprotocol.com/protocol/v1/agent-plan)
7
8#[cfg(feature = "unstable_plan_operations")]
9use std::{path::PathBuf, sync::Arc};
10
11#[cfg(feature = "unstable_plan_operations")]
12use derive_more::{Display, From};
13use serde::{Deserialize, Serialize};
14use serde_with::{DefaultOnError, VecSkipError, serde_as, skip_serializing_none};
15
16use crate::IntoOption;
17
18use super::Meta;
19
20/// An execution plan for accomplishing complex tasks.
21///
22/// Plans consist of multiple entries representing individual tasks or goals.
23/// Agents report plans to clients to provide visibility into their execution strategy.
24/// Plans can evolve during execution as the agent discovers new requirements or completes tasks.
25///
26/// See protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/v1/agent-plan)
27#[serde_as]
28#[skip_serializing_none]
29#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
30#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
31#[serde(rename_all = "camelCase")]
32#[non_exhaustive]
33pub struct Plan {
34    /// The list of tasks to be accomplished.
35    ///
36    /// When updating a plan, the agent must send a complete list of all entries
37    /// with their current status. The client replaces the entire plan with each update.
38    #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_>>")]
39    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
40    pub entries: Vec<PlanEntry>,
41    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
42    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
43    /// these keys.
44    ///
45    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
46    #[serde_as(deserialize_as = "DefaultOnError")]
47    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
48    #[serde(default)]
49    #[serde(rename = "_meta")]
50    pub meta: Option<Meta>,
51}
52
53impl Plan {
54    /// Builds [`Plan`] with the required fields set. Optional fields start unset or empty.
55    #[must_use]
56    pub fn new(entries: Vec<PlanEntry>) -> Self {
57        Self {
58            entries,
59            meta: None,
60        }
61    }
62
63    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
64    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
65    /// these keys.
66    ///
67    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
68    #[must_use]
69    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
70        self.meta = meta.into_option();
71        self
72    }
73}
74
75/// **UNSTABLE**
76///
77/// This capability is not part of the spec yet, and may be removed or changed at any point.
78///
79/// Unique identifier for a plan within a session.
80#[cfg(feature = "unstable_plan_operations")]
81#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
82#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, Display, From)]
83#[serde(transparent)]
84#[from(Arc<str>, String, &'static str)]
85#[non_exhaustive]
86pub struct PlanId(pub Arc<str>);
87
88#[cfg(feature = "unstable_plan_operations")]
89impl PlanId {
90    /// Wraps a protocol string as a typed [`PlanId`].
91    #[must_use]
92    pub fn new(id: impl Into<Arc<str>>) -> Self {
93        Self(id.into())
94    }
95}
96
97/// **UNSTABLE**
98///
99/// This capability is not part of the spec yet, and may be removed or changed at any point.
100///
101/// A content update for a plan identified by ID.
102#[cfg(feature = "unstable_plan_operations")]
103#[serde_as]
104#[skip_serializing_none]
105#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
106#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
107#[serde(rename_all = "camelCase")]
108#[non_exhaustive]
109pub struct PlanUpdate {
110    /// The updated plan content.
111    pub plan: PlanUpdateContent,
112    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
113    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
114    /// these keys.
115    ///
116    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
117    #[serde_as(deserialize_as = "DefaultOnError")]
118    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
119    #[serde(default)]
120    #[serde(rename = "_meta")]
121    pub meta: Option<Meta>,
122}
123
124#[cfg(feature = "unstable_plan_operations")]
125impl PlanUpdate {
126    /// Builds [`PlanUpdate`] with the required fields set. Optional fields start unset or empty.
127    #[must_use]
128    pub fn new(plan: PlanUpdateContent) -> Self {
129        Self { plan, meta: None }
130    }
131
132    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
133    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
134    /// these keys.
135    ///
136    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
137    #[must_use]
138    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
139        self.meta = meta.into_option();
140        self
141    }
142}
143
144/// **UNSTABLE**
145///
146/// This capability is not part of the spec yet, and may be removed or changed at any point.
147///
148/// Updated content for a plan.
149#[cfg(feature = "unstable_plan_operations")]
150#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
151#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
152#[serde(tag = "type", rename_all = "snake_case")]
153#[cfg_attr(feature = "schemars", schemars(extend("discriminator" = {"propertyName": "type"})))]
154#[non_exhaustive]
155pub enum PlanUpdateContent {
156    /// Structured plan entries.
157    Items(PlanItems),
158    /// Raw markdown content for the plan.
159    Markdown(PlanMarkdown),
160}
161
162#[cfg(feature = "unstable_plan_operations")]
163impl PlanUpdateContent {
164    /// Builds a plan update that replaces the itemized entries for a plan.
165    #[must_use]
166    pub fn items(plan_id: impl Into<PlanId>, entries: Vec<PlanEntry>) -> Self {
167        Self::Items(PlanItems::new(plan_id, entries))
168    }
169
170    /// Builds a plan update whose plan content is inline Markdown.
171    ///
172    /// To also name the file that holds the plan, wrap a [`PlanMarkdown`] built with
173    /// [`PlanMarkdown::path`] in [`PlanUpdateContent::Markdown`].
174    #[must_use]
175    pub fn markdown(plan_id: impl Into<PlanId>, content: impl Into<String>) -> Self {
176        Self::Markdown(PlanMarkdown::new(plan_id, content))
177    }
178}
179
180/// **UNSTABLE**
181///
182/// This capability is not part of the spec yet, and may be removed or changed at any point.
183///
184/// A plan represented as structured entries.
185#[cfg(feature = "unstable_plan_operations")]
186#[serde_as]
187#[skip_serializing_none]
188#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
189#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
190#[serde(rename_all = "camelCase")]
191#[non_exhaustive]
192pub struct PlanItems {
193    /// The plan ID to update.
194    pub plan_id: PlanId,
195    /// The list of tasks to be accomplished.
196    ///
197    /// When updating an item-based plan, the agent must send a complete list of all entries
198    /// with their current status. The client replaces that plan with each update.
199    #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_>>")]
200    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
201    pub entries: Vec<PlanEntry>,
202    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
203    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
204    /// these keys.
205    ///
206    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
207    #[serde_as(deserialize_as = "DefaultOnError")]
208    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
209    #[serde(default)]
210    #[serde(rename = "_meta")]
211    pub meta: Option<Meta>,
212}
213
214#[cfg(feature = "unstable_plan_operations")]
215impl PlanItems {
216    /// Builds [`PlanItems`] with the required fields set. Optional fields start unset or empty.
217    #[must_use]
218    pub fn new(plan_id: impl Into<PlanId>, entries: Vec<PlanEntry>) -> Self {
219        Self {
220            plan_id: plan_id.into(),
221            entries,
222            meta: None,
223        }
224    }
225
226    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
227    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
228    /// these keys.
229    ///
230    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
231    #[must_use]
232    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
233        self.meta = meta.into_option();
234        self
235    }
236}
237
238/// **UNSTABLE**
239///
240/// This capability is not part of the spec yet, and may be removed or changed at any point.
241///
242/// A plan represented as raw markdown content.
243#[cfg(feature = "unstable_plan_operations")]
244#[serde_as]
245#[skip_serializing_none]
246#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
247#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
248#[serde(rename_all = "camelCase")]
249#[non_exhaustive]
250pub struct PlanMarkdown {
251    /// The plan ID to update.
252    pub plan_id: PlanId,
253    /// Markdown content for the plan.
254    pub content: String,
255    /// The absolute path of the file that holds this plan.
256    ///
257    /// This field is optional. Omitting it or sending `null` both mean that the plan
258    /// has no file. `content` is the plan to display whether or not `path` is set.
259    /// Clients can use `path` to open the file.
260    #[serde_as(deserialize_as = "DefaultOnError")]
261    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
262    #[serde(default)]
263    pub path: Option<PathBuf>,
264    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
265    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
266    /// these keys.
267    ///
268    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
269    #[serde_as(deserialize_as = "DefaultOnError")]
270    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
271    #[serde(default)]
272    #[serde(rename = "_meta")]
273    pub meta: Option<Meta>,
274}
275
276#[cfg(feature = "unstable_plan_operations")]
277impl PlanMarkdown {
278    /// Builds [`PlanMarkdown`] with the required fields set. Optional fields start unset or empty.
279    #[must_use]
280    pub fn new(plan_id: impl Into<PlanId>, content: impl Into<String>) -> Self {
281        Self {
282            plan_id: plan_id.into(),
283            content: content.into(),
284            path: None,
285            meta: None,
286        }
287    }
288
289    /// The absolute path of the file that holds this plan.
290    ///
291    /// `content` is the plan to display whether or not `path` is set.
292    #[must_use]
293    pub fn path(mut self, path: impl IntoOption<PathBuf>) -> Self {
294        self.path = path.into_option();
295        self
296    }
297
298    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
299    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
300    /// these keys.
301    ///
302    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
303    #[must_use]
304    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
305        self.meta = meta.into_option();
306        self
307    }
308}
309
310/// **UNSTABLE**
311///
312/// This capability is not part of the spec yet, and may be removed or changed at any point.
313///
314/// Removal notice for a plan identified by ID.
315#[cfg(feature = "unstable_plan_operations")]
316#[serde_as]
317#[skip_serializing_none]
318#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
319#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
320#[serde(rename_all = "camelCase")]
321#[non_exhaustive]
322pub struct PlanRemoved {
323    /// The plan ID to remove.
324    pub plan_id: PlanId,
325    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
326    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
327    /// these keys.
328    ///
329    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
330    #[serde_as(deserialize_as = "DefaultOnError")]
331    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
332    #[serde(default)]
333    #[serde(rename = "_meta")]
334    pub meta: Option<Meta>,
335}
336
337#[cfg(feature = "unstable_plan_operations")]
338impl PlanRemoved {
339    /// Builds [`PlanRemoved`] with the required fields set. Optional fields start unset or empty.
340    #[must_use]
341    pub fn new(plan_id: impl Into<PlanId>) -> Self {
342        Self {
343            plan_id: plan_id.into(),
344            meta: None,
345        }
346    }
347
348    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
349    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
350    /// these keys.
351    ///
352    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
353    #[must_use]
354    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
355        self.meta = meta.into_option();
356        self
357    }
358}
359
360/// **UNSTABLE**
361///
362/// This capability is not part of the spec yet, and may be removed or changed at any point.
363///
364/// Capabilities for receiving `plan_update` and `plan_removed` session updates.
365#[cfg(feature = "unstable_plan_operations")]
366#[serde_as]
367#[skip_serializing_none]
368#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
369#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
370#[serde(rename_all = "camelCase")]
371#[non_exhaustive]
372pub struct PlanCapabilities {
373    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
374    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
375    /// these keys.
376    ///
377    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
378    #[serde_as(deserialize_as = "DefaultOnError")]
379    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
380    #[serde(default)]
381    #[serde(rename = "_meta")]
382    pub meta: Option<Meta>,
383}
384
385#[cfg(feature = "unstable_plan_operations")]
386impl PlanCapabilities {
387    /// Builds an empty [`PlanCapabilities`]. Use builder methods to advertise supported sub-capabilities.
388    #[must_use]
389    pub fn new() -> Self {
390        Self::default()
391    }
392
393    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
394    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
395    /// these keys.
396    ///
397    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
398    #[must_use]
399    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
400        self.meta = meta.into_option();
401        self
402    }
403}
404
405/// A single entry in the execution plan.
406///
407/// Represents a task or goal that the assistant intends to accomplish
408/// as part of fulfilling the user's request.
409/// See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/v1/agent-plan#plan-entries)
410#[serde_as]
411#[skip_serializing_none]
412#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
413#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
414#[serde(rename_all = "camelCase")]
415#[non_exhaustive]
416pub struct PlanEntry {
417    /// Human-readable description of what this task aims to accomplish.
418    pub content: String,
419    /// The relative importance of this task.
420    /// Used to indicate which tasks are most critical to the overall goal.
421    pub priority: PlanEntryPriority,
422    /// Current execution status of this task.
423    pub status: PlanEntryStatus,
424    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
425    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
426    /// these keys.
427    ///
428    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
429    #[serde_as(deserialize_as = "DefaultOnError")]
430    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
431    #[serde(default)]
432    #[serde(rename = "_meta")]
433    pub meta: Option<Meta>,
434}
435
436impl PlanEntry {
437    /// Builds [`PlanEntry`] with the required fields set. Optional fields start unset or empty.
438    #[must_use]
439    pub fn new(
440        content: impl Into<String>,
441        priority: PlanEntryPriority,
442        status: PlanEntryStatus,
443    ) -> Self {
444        Self {
445            content: content.into(),
446            priority,
447            status,
448            meta: None,
449        }
450    }
451
452    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
453    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
454    /// these keys.
455    ///
456    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
457    #[must_use]
458    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
459        self.meta = meta.into_option();
460        self
461    }
462}
463
464/// Priority levels for plan entries.
465///
466/// Used to indicate the relative importance or urgency of different
467/// tasks in the execution plan.
468/// See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/v1/agent-plan#plan-entries)
469#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
470#[derive(Deserialize, Serialize, Debug, Clone, PartialEq, Eq)]
471#[serde(rename_all = "snake_case")]
472#[non_exhaustive]
473pub enum PlanEntryPriority {
474    /// High priority task - critical to the overall goal.
475    High,
476    /// Medium priority task - important but not critical.
477    Medium,
478    /// Low priority task - nice to have but not essential.
479    Low,
480}
481
482/// Status of a plan entry in the execution flow.
483///
484/// Tracks the lifecycle of each task from planning through completion.
485/// See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/v1/agent-plan#plan-entries)
486#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
487#[derive(Deserialize, Serialize, Debug, Clone, PartialEq, Eq)]
488#[serde(rename_all = "snake_case")]
489#[non_exhaustive]
490pub enum PlanEntryStatus {
491    /// The task has not started yet.
492    Pending,
493    /// The task is currently being worked on.
494    InProgress,
495    /// The task has been successfully completed.
496    Completed,
497}