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}