Skip to main content

magi/
talk_external.rs

1//! Local external-process ingress. Publication, TurnLease and worker ownership
2//! are the same as web Chat; an uncertain submission is never replayed.
3use super::*;
4use serde_json::{Value, json};
5
6/// A durable occurrence, committed atomically with its exact transcript input.
7#[derive(Debug, Clone, Serialize, Deserialize)]
8pub struct Request {
9    /// Caller-saved occurrence identifier, unique within this conversation.
10    pub request: String,
11    /// Self-reported external display label; never an authority credential.
12    pub sender: String,
13    /// Exact original input, retained to reject conflicting request replays.
14    pub text: String,
15    /// Exact appended input turn, not a search for the next operator turn.
16    pub input_turn: usize,
17    /// Exact response turn, committed with that response.
18    pub reply_turn: Option<usize>,
19    /// Durable execution boundary: accepted, started, replied, failed,
20    /// not_started or uncertain. Transport timeouts never change this.
21    pub status: String,
22    /// Detached worker reservation that owns this occurrence.
23    pub worker: Option<String>,
24    /// Startup or response diagnostic, when known.
25    pub error: Option<String>,
26}
27
28pub(crate) fn active_input(talk: &Talk) -> Option<usize> {
29    // A historical interrupted request must never hijack a later owner turn.
30    // Bind execution to this worker's immutable payload, not a pending flag.
31    let home = crate::run::try_home()?;
32    let job = crate::worker::current_job(&home).ok()??;
33    if job.payload.get("talk")?.as_str()? != talk.id {
34        return None;
35    }
36    let request = job.payload.get("external_request")?.as_str()?;
37    talk.external_requests
38        .iter()
39        .find(|r| {
40            r.request == request
41                && r.status == "started"
42                && r.worker.as_deref() == Some(job.id.as_str())
43        })
44        .map(|r| r.input_turn)
45}
46
47fn resolve(store: &Talks, selector: &str) -> Result<std::result::Result<Talk, Value>> {
48    let (talks, unreadable) = store.list_counting_unreadable();
49    let mut hits: Vec<_> = talks
50        .into_iter()
51        .filter(|t| t.id == selector || t.id.starts_with(selector))
52        .collect();
53    if let Some(index) = hits.iter().position(|t| t.id == selector) {
54        return Ok(Ok(hits.swap_remove(index)));
55    }
56    Ok(match hits.len() {
57        0 => Err(json!({"status":"not_found", "selector":selector, "unreadable":unreadable})),
58        1 => Ok(hits.pop().expect("one match")),
59        _ => Err(
60            json!({"status":"ambiguous", "selector":selector, "candidates":hits.iter().map(|t| &t.id).collect::<Vec<_>>()}),
61        ),
62    })
63}
64
65/// Discover conversations without opening or reopening one.
66pub fn list(store: &Talks) -> Result<Value> {
67    let (talks, unreadable) = store.list_counting_unreadable();
68    Ok(
69        json!({"talks":talks.iter().map(|t| json!({"id":t.id,"repo":t.repo,"agent":t.agent,"status":t.status,"title":t.title})).collect::<Vec<_>>(),"unreadable":unreadable}),
70    )
71}
72
73fn cursor(talk: &Talk, turn: usize, message: usize) -> String {
74    use sha2::Digest as _;
75    let mut hash = sha2::Sha256::new();
76    if let Some(row) = talk.turns.get(turn) {
77        hash.update(serde_json::to_vec(&row.at).expect("timestamp serialization"));
78        let body = row
79            .messages
80            .get(message)
81            .map_or(row.body.as_str(), |m| m.body.as_str());
82        hash.update(body.as_bytes());
83    }
84    // A reverted admission may later reuse a coordinate. Bind the cursor to
85    // its contents and occurrence time so it never silently aliases that row.
86    use std::fmt::Write as _;
87    let mut id = format!("{}:{turn}:{message}:", talk.id);
88    id.reserve(64);
89    for byte in hash.finalize() {
90        write!(id, "{byte:02x}").expect("write to string");
91    }
92    id
93}
94
95/// Conversation-bound coordinates and occurrence fingerprints form stable IDs.
96pub fn history(store: &Talks, selector: &str, after: Option<&str>, limit: usize) -> Result<Value> {
97    anyhow::ensure!(
98        (1..=500).contains(&limit),
99        "limit must be between 1 and 500"
100    );
101    let talk = match resolve(store, selector)? {
102        Ok(t) => t,
103        Err(v) => return Ok(v),
104    };
105    let mut coordinates = talk
106        .turns
107        .iter()
108        .enumerate()
109        .flat_map(|(i, turn)| (0..turn.messages.len().max(1)).map(move |j| (i, j)));
110    if let Some(after) = after {
111        coordinates
112            .find(|&(i, j)| cursor(&talk, i, j) == after)
113            .context("cursor is not a message in this conversation")?;
114    } else {
115        let count: usize = talk.turns.iter().map(|t| t.messages.len().max(1)).sum();
116        for _ in 0..count.saturating_sub(limit) {
117            coordinates.next();
118        }
119    }
120    let messages: Vec<_> = coordinates
121        .by_ref()
122        .take(limit)
123        .map(|(i, j)| {
124            let turn = &talk.turns[i];
125            let message = turn.messages.get(j);
126            let body = message.map_or(turn.body.as_str(), |m| m.body.as_str());
127            json!({"id":cursor(&talk,i,j),"sender":sender(turn,message),"body":body,"at":turn.at})
128        })
129        .collect();
130    let more = coordinates.next().is_some();
131    let last = messages.last().and_then(|v| v["id"].as_str()).or(after);
132    Ok(json!({"talk":talk.id,"messages":messages,"cursor":last,"more":more}))
133}
134
135fn view(store: &Talks, talk: &Talk, record: &Request) -> Value {
136    let mut status = record.status.as_str();
137    if matches!(status, "accepted" | "started") {
138        // Absence of completion is not permission to execute again. A worker
139        // result may be pruned; that is unknown, not a fresh request.
140        if let Some(id) = &record.worker {
141            match crate::worker::get(store.home(), id) {
142                Ok(job)
143                    if matches!(
144                        job.status,
145                        crate::worker::Status::Failed | crate::worker::Status::Finished
146                    ) =>
147                {
148                    status = "uncertain"
149                }
150                Err(_) => status = "uncertain",
151                _ => {}
152            }
153        } else {
154            status = "uncertain";
155        }
156    }
157    json!({"talk":talk.id,"request":record.request,"status":status,
158        "input_id":cursor(talk,record.input_turn,0),
159        "reply_id":record.reply_turn.map(|i| cursor(talk,i,0)),
160        "reply":record.reply_turn.and_then(|i| talk.turns.get(i)).map(|t| &t.body),
161        "worker":record.worker,"error":record.error})
162}
163
164/// Accept once, or return the saved occurrence. Duplicate calls never dispatch.
165pub async fn send(
166    store: &Talks,
167    selector: &str,
168    request: &str,
169    label: &str,
170    text: &str,
171) -> Result<Value> {
172    anyhow::ensure!(
173        !request.is_empty()
174            && request.len() <= 128
175            && request
176                .bytes()
177                .all(|c| c.is_ascii_alphanumeric() || b"-_.".contains(&c)),
178        "request must contain 1..128 ASCII letters, digits, -, _ or ."
179    );
180    anyhow::ensure!(
181        !label.trim().is_empty() && label.len() <= 128 && !label.chars().any(char::is_control),
182        "sender must be a nonempty single-line label of at most 128 bytes"
183    );
184    anyhow::ensure!(!text.trim().is_empty(), "nothing to send");
185    let talk = match resolve(store, selector)? {
186        Ok(t) => t,
187        Err(v) => return Ok(v),
188    };
189    if let Some(r) = talk.external_requests.iter().find(|r| r.request == request) {
190        return Ok(if r.text == text && r.sender == label {
191            view(store, &talk, r)
192        } else {
193            json!({"talk":talk.id,"request":request,"status":"conflict"})
194        });
195    }
196    let Some(_publication) = crate::chat_worker::try_publication_guard(store, &talk.id)? else {
197        return Ok(json!({"talk":talk.id,"request":request,"status":"busy"}));
198    };
199    // Replays are observational even if the conversation is now busy/closed.
200    let fresh = store.get(&talk.id)?;
201    if let Some(r) = fresh
202        .external_requests
203        .iter()
204        .find(|r| r.request == request)
205    {
206        return Ok(if r.text == text && r.sender == label {
207            view(store, &fresh, r)
208        } else {
209            json!({"talk":fresh.id,"request":request,"status":"conflict"})
210        });
211    }
212    if !fresh.status.open() {
213        return Ok(json!({"talk":fresh.id,"request":request,"status":"closed"}));
214    }
215    // Refuse every live generation, including older executables unable to
216    // decode external provenance, before publishing a new-format record.
217    if crate::chat_worker::turn_worker_active(store, &fresh.id) {
218        return Ok(json!({"talk":fresh.id,"request":request,"status":"busy"}));
219    }
220    let Some(_turn) = store.claim_turn(&fresh.id)? else {
221        return Ok(json!({"talk":fresh.id,"request":request,"status":"busy"}));
222    };
223    {
224        let _guard = store.guard()?;
225        let mut fresh = store.get(&talk.id)?;
226        if !fresh.status.open() {
227            return Ok(json!({"talk":fresh.id,"request":request,"status":"closed"}));
228        }
229        if !fresh.pending.is_empty()
230            || !fresh.pending_messages.is_empty()
231            || !fresh.pending_attachments.is_empty()
232        {
233            return Ok(json!({"talk":fresh.id,"request":request,"status":"busy"}));
234        }
235        let index = fresh.turns.len();
236        fresh.turns.push(Turn {
237            sender: Some(Sender::External),
238            who: Who::Operator,
239            body: format!("External agent [{label}]:\n{text}"),
240            at: Timestamp::now(),
241            attachments: Vec::new(),
242            usage: None,
243            breaks: Some(Vec::new()),
244            messages: Vec::new(),
245            posted_by: None,
246        });
247        fresh.external_requests.push(Request {
248            request: request.to_owned(),
249            sender: label.to_owned(),
250            text: text.to_owned(),
251            input_turn: index,
252            reply_turn: None,
253            status: "accepted".into(),
254            worker: None,
255            error: None,
256        });
257        store.put(&mut fresh)?;
258    }
259    // The ledger is already durable. A crash at any subsequent boundary is an
260    // accepted but uncertain send, never an invitation to append or run again.
261    let result = crate::worker::spawn(
262        store.home(),
263        "chat",
264        &format!("chat-external:{}:{request}", talk.id),
265        json!({"talk":talk.id,"external_request":request}),
266    )
267    .await;
268    {
269        let _guard = store.guard()?;
270        let mut fresh = store.get(&talk.id)?;
271        let r = fresh
272            .external_requests
273            .iter_mut()
274            .find(|r| r.request == request)
275            .context("external request disappeared")?;
276        match result {
277            Ok(job) => {
278                r.worker = Some(job.id);
279            }
280            Err(error) => {
281                if r.status == "accepted" {
282                    r.status = if crate::worker::not_started(&error) {
283                        "not_started"
284                    } else {
285                        "uncertain"
286                    }
287                    .into();
288                }
289                r.error = Some(format!("{error:#}"));
290            }
291        }
292        store.put(&mut fresh)?;
293    }
294    let fresh = store.get(&talk.id)?;
295    Ok(view(
296        store,
297        &fresh,
298        fresh
299            .external_requests
300            .iter()
301            .find(|r| r.request == request)
302            .context("external request disappeared")?,
303    ))
304}
305
306/// Observation only: timeout neither cancels nor repeats accepted work.
307pub async fn reply(store: &Talks, selector: &str, request: &str, wait: u64) -> Result<Value> {
308    let talk = match resolve(store, selector)? {
309        Ok(t) => t,
310        Err(v) => return Ok(v),
311    };
312    let deadline = tokio::time::Instant::now()
313        .checked_add(Duration::from_secs(wait))
314        .context("wait duration exceeds the monotonic clock range")?;
315    loop {
316        let fresh = store.get(&talk.id)?;
317        let Some(record) = fresh
318            .external_requests
319            .iter()
320            .find(|r| r.request == request)
321        else {
322            return Ok(json!({"talk":talk.id,"request":request,"status":"not_found"}));
323        };
324        let mut value = view(store, &fresh, record);
325        if wait == 0 || matches!(record.status.as_str(), "replied" | "failed" | "not_started") {
326            return Ok(value);
327        }
328        if tokio::time::Instant::now() >= deadline {
329            value["state"] = value["status"].clone();
330            value["status"] = json!("timeout");
331            return Ok(value);
332        }
333        tokio::time::sleep(Duration::from_millis(100)).await;
334    }
335}
336
337/// Called only by the ordinary detached chat worker, under its execution lease.
338pub(crate) async fn run_worker(store: &Talks, id: &str, request: &str) -> Result<()> {
339    loop {
340        if let Some(lease) = store.claim_turn(id)? {
341            let publication = crate::chat_worker::publication_guard(store, id).await?;
342            let mut talk = {
343                let _guard = store.guard()?;
344                let mut talk = store.get(id)?;
345                let r = talk
346                    .external_requests
347                    .iter_mut()
348                    .find(|r| r.request == request)
349                    .context("external request missing")?;
350                // A second worker or uncertain restart cannot repeat a CLI call.
351                if r.status != "accepted" {
352                    return Ok(());
353                }
354                r.status = "started".into();
355                r.worker = crate::worker::current_job(store.home())?.map(|j| j.id);
356                store.put(&mut talk)?;
357                talk
358            };
359            let index = active_input(&talk).context("external input missing")?;
360            let text = talk
361                .turns
362                .get(index)
363                .context("external transcript input missing")?
364                .body
365                .clone();
366            drop(publication);
367            let (cfg, _) = Config::discover(&talk.repo, None)?;
368            return super::respond(&lease, &mut talk, store, &cfg, &text).await;
369        }
370        tokio::time::sleep(Duration::from_millis(100)).await;
371    }
372}