Skip to main content

agent_client_protocol_schema/v1/
plan.rs

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