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}
58
59impl RunSpec {
60 pub fn new(prompt: impl Into<String>) -> Self {
61 Self {
62 prompt: prompt.into(),
63 provider: None,
64 base_url: None,
65 model: None,
66 shell: true,
67 system_prompt: None,
68 effort: None,
69 approve: Approve::default(),
70 deadline: None,
71 tool_budget: None,
72 token_budget: None,
73 detached: false,
74 continuation: Continuation::default(),
75 hop: 0,
76 not_after_ms: None,
77 }
78 }
79
80 pub fn with_provider(self, provider: impl Into<String>) -> Self {
81 Self {
82 provider: Some(provider.into()),
83 ..self
84 }
85 }
86
87 pub fn with_base_url(self, base_url: impl Into<String>) -> Self {
88 Self {
89 base_url: Some(base_url.into()),
90 ..self
91 }
92 }
93
94 pub fn with_model(self, model: impl Into<String>) -> Self {
95 Self {
96 model: Some(model.into()),
97 ..self
98 }
99 }
100
101 /// Refuses the task shell access — sugar over the workspace's own
102 /// `ShellAccess::from_flag`.
103 pub fn without_shell(self) -> Self {
104 Self {
105 shell: false,
106 ..self
107 }
108 }
109
110 pub fn with_system_prompt(self, system_prompt: SystemPrompt) -> Self {
111 Self {
112 system_prompt: Some(system_prompt),
113 ..self
114 }
115 }
116
117 pub fn with_effort(self, effort: Effort) -> Self {
118 Self {
119 effort: Some(effort),
120 ..self
121 }
122 }
123
124 /// Every consequential call this task's turns make is put to this.
125 pub fn with_approve(self, approve: Approve) -> Self {
126 Self { approve, ..self }
127 }
128
129 /// Gives up on the task after `deadline`, counted from spawn. Defaults to
130 /// [`DEFAULT_DEADLINE`] when never set — an unattended task always gets a
131 /// finite service bound.
132 pub fn with_deadline(self, deadline: Duration) -> Self {
133 Self {
134 deadline: Some(deadline),
135 ..self
136 }
137 }
138
139 /// Never gives the task longer than the instant `not_after_ms`
140 /// (milliseconds since the epoch), whatever [`with_deadline`](Self::with_deadline)
141 /// adds up to.
142 ///
143 /// For a deadline that is someone else's: a caller over A2A says when it
144 /// stops waiting, as an instant, and re-anchoring that as a duration at
145 /// spawn would hand the task a little more than the caller has.
146 pub fn with_not_after_ms(self, not_after_ms: u64) -> Self {
147 Self {
148 not_after_ms: Some(not_after_ms),
149 ..self
150 }
151 }
152
153 pub fn with_tool_budget(self, tool_budget: usize) -> Self {
154 Self {
155 tool_budget: Some(tool_budget),
156 ..self
157 }
158 }
159
160 pub fn with_token_budget(self, token_budget: u64) -> Self {
161 Self {
162 token_budget: Some(token_budget),
163 ..self
164 }
165 }
166
167 /// Spawns outside the calling task's ownership tree even when this
168 /// process is itself executing one — see [`crate::current_task`]. A
169 /// detached task inherits no scope: nothing cancels it downward, and
170 /// nothing waits for it before its would-be parent settles.
171 pub fn detached(self) -> Self {
172 Self {
173 detached: true,
174 ..self
175 }
176 }
177
178 /// How many agent-to-agent hops away from a top-level caller this task's
179 /// work arrived — `0` (the default) for work nobody handed over a wire.
180 /// A host serving tasks to other agents records the hop a request came
181 /// in at, so the task's own delegations can say how far along they are
182 /// (ADR-0030 §9). Recorded at spawn, published to the task's commands as
183 /// [`BASIS_HOP`](crate::BASIS_HOP), and inherited by its children, which
184 /// are the same work one level down in-process, not a hop further.
185 pub fn with_hop(self, hop: u32) -> Self {
186 Self { hop, ..self }
187 }
188
189 /// Picks up an existing conversation instead of opening a new one.
190 pub fn continuing(self, continuation: Continuation) -> Self {
191 Self {
192 continuation,
193 ..self
194 }
195 }
196}