basis_tasks/spec.rs
1//! `RunSpec`: one task's worth of spawn request.
2//!
3//! Built the way `basis::RunSpec` is — `new` plus `with_*` methods that
4//! return new values — because this is the same kind of thing one layer up:
5//! `basis::RunSpec` is a run's per-turn intent against an already-open
6//! [`basis::Workspace`]; this is what a *durable* task additionally records
7//! so a later attach, in a process that may not be this one, can open that
8//! workspace itself and mint the run.
9
10use std::time::Duration;
11
12use basis::{Effort, SystemPrompt};
13
14use crate::{approve::Approve, handle::TaskHandle};
15
16/// The default deadline an unattended task is given when nothing else names
17/// one: 30 minutes. A spawned task may never be waited on by an attentive
18/// caller, so — unlike an attended one-shot, which is unbounded unless asked
19/// — it always gets a finite service bound (`with_deadline` narrows it).
20pub const DEFAULT_DEADLINE: Duration = Duration::from_secs(30 * 60);
21
22/// Which conversation a spawned task picks up, if any.
23#[derive(Debug, Clone, Default, PartialEq, Eq)]
24pub enum Continuation {
25 /// Opens a new conversation. The ordinary case.
26 #[default]
27 New,
28 /// The conversation this workspace was last worked in — what a bare
29 /// `--continue` resolves against.
30 Latest,
31 /// A specific conversation, by the task that opened or last continued
32 /// it — what `--continue --session <ID>` resolves against.
33 Named(TaskHandle),
34}
35
36/// One task's worth of spawn request: `basis::RunSpec`'s per-run intent,
37/// plus the workspace-level overrides a [`basis::Workspace`] normally fixes
38/// once, and the facts a task that may run unattended, in another process,
39/// additionally needs recorded.
40#[derive(Debug, Clone, PartialEq)]
41pub struct RunSpec {
42 pub(crate) prompt: String,
43 pub(crate) provider: Option<String>,
44 pub(crate) base_url: Option<String>,
45 pub(crate) model: Option<String>,
46 pub(crate) shell: bool,
47 pub(crate) system_prompt: Option<SystemPrompt>,
48 pub(crate) effort: Option<Effort>,
49 pub(crate) approve: Approve,
50 pub(crate) deadline: Option<Duration>,
51 pub(crate) tool_budget: Option<usize>,
52 pub(crate) token_budget: Option<u64>,
53 pub(crate) detached: bool,
54 pub(crate) continuation: Continuation,
55 pub(crate) hop: u32,
56 pub(crate) not_after_ms: Option<u64>,
57 pub(crate) answering: bool,
58}
59
60impl RunSpec {
61 pub fn new(prompt: impl Into<String>) -> Self {
62 Self {
63 prompt: prompt.into(),
64 provider: None,
65 base_url: None,
66 model: None,
67 shell: true,
68 system_prompt: None,
69 effort: None,
70 approve: Approve::default(),
71 deadline: None,
72 tool_budget: None,
73 token_budget: None,
74 detached: false,
75 continuation: Continuation::default(),
76 hop: 0,
77 not_after_ms: None,
78 answering: false,
79 }
80 }
81
82 /// Marks the task as answering a caller, who can be handed files: the
83 /// task is offered [`ATTACH_FILE`](crate::ATTACH_FILE) to add a
84 /// workspace file to its answer, read back with
85 /// [`Tasks::answer_files`](crate::Tasks::answer_files) (ADR-0041 §7).
86 pub fn answering(self) -> Self {
87 Self {
88 answering: true,
89 ..self
90 }
91 }
92
93 pub fn with_provider(self, provider: impl Into<String>) -> Self {
94 Self {
95 provider: Some(provider.into()),
96 ..self
97 }
98 }
99
100 pub fn with_base_url(self, base_url: impl Into<String>) -> Self {
101 Self {
102 base_url: Some(base_url.into()),
103 ..self
104 }
105 }
106
107 pub fn with_model(self, model: impl Into<String>) -> Self {
108 Self {
109 model: Some(model.into()),
110 ..self
111 }
112 }
113
114 /// Refuses the task shell access — sugar over the workspace's own
115 /// `ShellAccess::from_flag`.
116 pub fn without_shell(self) -> Self {
117 Self {
118 shell: false,
119 ..self
120 }
121 }
122
123 pub fn with_system_prompt(self, system_prompt: SystemPrompt) -> Self {
124 Self {
125 system_prompt: Some(system_prompt),
126 ..self
127 }
128 }
129
130 pub fn with_effort(self, effort: Effort) -> Self {
131 Self {
132 effort: Some(effort),
133 ..self
134 }
135 }
136
137 /// Every consequential call this task's turns make is put to this.
138 pub fn with_approve(self, approve: Approve) -> Self {
139 Self { approve, ..self }
140 }
141
142 /// Gives up on the task after `deadline`, counted from spawn. Defaults to
143 /// [`DEFAULT_DEADLINE`] when never set — an unattended task always gets a
144 /// finite service bound.
145 pub fn with_deadline(self, deadline: Duration) -> Self {
146 Self {
147 deadline: Some(deadline),
148 ..self
149 }
150 }
151
152 /// Never gives the task longer than the instant `not_after_ms`
153 /// (milliseconds since the epoch), whatever [`with_deadline`](Self::with_deadline)
154 /// adds up to.
155 ///
156 /// For a deadline that is someone else's: a caller over A2A says when it
157 /// stops waiting, as an instant, and re-anchoring that as a duration at
158 /// spawn would hand the task a little more than the caller has.
159 pub fn with_not_after_ms(self, not_after_ms: u64) -> Self {
160 Self {
161 not_after_ms: Some(not_after_ms),
162 ..self
163 }
164 }
165
166 pub fn with_tool_budget(self, tool_budget: usize) -> Self {
167 Self {
168 tool_budget: Some(tool_budget),
169 ..self
170 }
171 }
172
173 pub fn with_token_budget(self, token_budget: u64) -> Self {
174 Self {
175 token_budget: Some(token_budget),
176 ..self
177 }
178 }
179
180 /// Spawns outside the calling task's ownership tree even when this
181 /// process is itself executing one — see [`crate::current_task`]. A
182 /// detached task inherits no scope: nothing cancels it downward, and
183 /// nothing waits for it before its would-be parent settles.
184 pub fn detached(self) -> Self {
185 Self {
186 detached: true,
187 ..self
188 }
189 }
190
191 /// How many agent-to-agent hops away from a top-level caller this task's
192 /// work arrived — `0` (the default) for work nobody handed over a wire.
193 /// A host serving tasks to other agents records the hop a request came
194 /// in at, so the task's own delegations can say how far along they are
195 /// (ADR-0030 §9). Recorded at spawn, published to the task's commands as
196 /// [`BASIS_HOP`](crate::BASIS_HOP), and inherited by its children, which
197 /// are the same work one level down in-process, not a hop further.
198 pub fn with_hop(self, hop: u32) -> Self {
199 Self { hop, ..self }
200 }
201
202 /// Picks up an existing conversation instead of opening a new one.
203 pub fn continuing(self, continuation: Continuation) -> Self {
204 Self {
205 continuation,
206 ..self
207 }
208 }
209}