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}