awaken_runtime/runtime/agent_runtime/
run_request.rs

1//! RunRequest — unified request for starting or resuming a run.
2
3use crate::inbox::{InboxReceiver, InboxSender};
4use awaken_contract::contract::inference::InferenceOverride;
5use awaken_contract::contract::message::Message;
6use awaken_contract::contract::storage::RunRequestOrigin;
7use awaken_contract::contract::suspension::ToolCallResume;
8use awaken_contract::contract::tool::ToolDescriptor;
9use awaken_contract::contract::tool_intercept::{AdapterKind, RunMode};
10
11/// In-process inbox pair owned by a single run.
12pub struct RunInbox {
13    pub sender: InboxSender,
14    pub receiver: InboxReceiver,
15}
16
17/// Unified request for starting or resuming a run.
18pub struct RunRequest {
19    /// New messages to append before running.
20    pub messages: Vec<Message>,
21    /// True when `messages` already exist in the thread message log.
22    ///
23    /// Mailbox-backed dispatch reconstructs new input messages from
24    /// `RunRecord.request` and the thread log, so the runtime must use them as
25    /// the current turn without appending a duplicate copy.
26    pub messages_already_persisted: bool,
27    /// Thread ID. Existing → load history; new → create.
28    pub thread_id: String,
29    /// Target agent ID.
30    /// `None` = infer from latest thread state/run record, fallback to default.
31    pub agent_id: Option<String>,
32    /// Runtime parameter overrides for this run.
33    pub overrides: Option<InferenceOverride>,
34    /// Resume decisions for suspended tool calls. Empty = fresh run.
35    pub decisions: Vec<(String, ToolCallResume)>,
36    /// Frontend-defined tools for this run.
37    pub frontend_tools: Vec<ToolDescriptor>,
38    /// Where this request originated.
39    pub origin: RunRequestOrigin,
40    /// Execution mode used by framework-level policy hooks.
41    pub run_mode: RunMode,
42    /// Protocol or adapter that submitted this request.
43    pub adapter: AdapterKind,
44    /// Parent run ID for child run linkage (tracing/lineage).
45    pub parent_run_id: Option<String>,
46    /// Parent thread ID for message routing back to parent.
47    pub parent_thread_id: Option<String>,
48    /// Continue a previous run instead of creating a new one.
49    pub continue_run_id: Option<String>,
50    /// Optional canonical run ID preallocated by the caller.
51    pub run_id_hint: Option<String>,
52    /// Optional transport dispatch/task ID that should be used as the run ID.
53    pub dispatch_id_hint: Option<String>,
54    /// Queue dispatch that delivered this run request, if any.
55    pub dispatch_id: Option<String>,
56    /// External session/dispatch identifier associated with this run.
57    pub session_id: Option<String>,
58    /// Transport request identifier associated with this run.
59    pub transport_request_id: Option<String>,
60    /// Optional in-process inbox pair for background-task notifications.
61    pub run_inbox: Option<RunInbox>,
62}
63
64impl RunRequest {
65    /// Build a message-first request with default options.
66    pub fn new(thread_id: impl Into<String>, messages: Vec<Message>) -> Self {
67        Self {
68            messages,
69            messages_already_persisted: false,
70            thread_id: thread_id.into(),
71            agent_id: None,
72            overrides: None,
73            decisions: Vec::new(),
74            frontend_tools: Vec::new(),
75            origin: RunRequestOrigin::User,
76            run_mode: RunMode::Foreground,
77            adapter: AdapterKind::Internal,
78            parent_run_id: None,
79            parent_thread_id: None,
80            continue_run_id: None,
81            run_id_hint: None,
82            dispatch_id_hint: None,
83            dispatch_id: None,
84            session_id: None,
85            transport_request_id: None,
86            run_inbox: None,
87        }
88    }
89
90    #[must_use]
91    pub fn with_agent_id(mut self, agent_id: impl Into<String>) -> Self {
92        self.agent_id = Some(agent_id.into());
93        self
94    }
95
96    #[must_use]
97    pub fn with_overrides(mut self, overrides: InferenceOverride) -> Self {
98        self.overrides = Some(overrides);
99        self
100    }
101
102    #[must_use]
103    pub fn with_decisions(mut self, decisions: Vec<(String, ToolCallResume)>) -> Self {
104        self.decisions = decisions;
105        self
106    }
107
108    #[must_use]
109    pub fn with_frontend_tools(mut self, tools: Vec<ToolDescriptor>) -> Self {
110        self.frontend_tools = tools;
111        self
112    }
113
114    #[must_use]
115    pub fn with_origin(mut self, origin: RunRequestOrigin) -> Self {
116        self.origin = origin;
117        self
118    }
119
120    #[must_use]
121    pub fn with_run_mode(mut self, run_mode: RunMode) -> Self {
122        self.run_mode = run_mode;
123        self
124    }
125
126    #[must_use]
127    pub fn with_adapter(mut self, adapter: AdapterKind) -> Self {
128        self.adapter = adapter;
129        self
130    }
131
132    #[must_use]
133    pub fn with_parent_run_id(mut self, parent_run_id: impl Into<String>) -> Self {
134        self.parent_run_id = Some(parent_run_id.into());
135        self
136    }
137
138    #[must_use]
139    pub fn with_parent_thread_id(mut self, parent_thread_id: impl Into<String>) -> Self {
140        self.parent_thread_id = Some(parent_thread_id.into());
141        self
142    }
143
144    #[must_use]
145    pub fn with_continue_run_id(mut self, continue_run_id: impl Into<String>) -> Self {
146        self.continue_run_id = Some(continue_run_id.into());
147        self
148    }
149
150    #[must_use]
151    pub fn with_run_id_hint(mut self, run_id_hint: impl Into<String>) -> Self {
152        self.run_id_hint = Some(run_id_hint.into());
153        self
154    }
155
156    #[must_use]
157    pub fn with_dispatch_id_hint(mut self, dispatch_id_hint: impl Into<String>) -> Self {
158        self.dispatch_id_hint = Some(dispatch_id_hint.into());
159        self
160    }
161
162    #[must_use]
163    pub fn with_trace_dispatch_id(mut self, dispatch_id: impl Into<String>) -> Self {
164        self.dispatch_id = Some(dispatch_id.into());
165        self
166    }
167
168    #[must_use]
169    pub fn with_dispatch_id(mut self, dispatch_id: impl Into<String>) -> Self {
170        self.dispatch_id = Some(dispatch_id.into());
171        self
172    }
173
174    #[must_use]
175    pub fn with_session_id(mut self, session_id: impl Into<String>) -> Self {
176        self.session_id = Some(session_id.into());
177        self
178    }
179
180    #[must_use]
181    pub fn with_transport_request_id(mut self, transport_request_id: impl Into<String>) -> Self {
182        self.transport_request_id = Some(transport_request_id.into());
183        self
184    }
185
186    #[must_use]
187    pub fn with_inbox(mut self, sender: InboxSender, receiver: InboxReceiver) -> Self {
188        self.run_inbox = Some(RunInbox { sender, receiver });
189        self
190    }
191
192    #[must_use]
193    pub fn with_messages_already_persisted(mut self, value: bool) -> Self {
194        self.messages_already_persisted = value;
195        self
196    }
197}
awaken_runtime/runtime/agent_runtime/run_request.rs

awaken_runtime/runtime/agent_runtime/
run_request.rs
