1use super::*;
8
9impl Mnemo {
10 #[cfg_attr(not(feature = "dev-hooks"), allow(dead_code))]
17 pub(super) fn put_coordination(
18 &mut self,
19 kind: &str,
20 content: String,
21 metadata: Map<String, Value>,
22 ) -> Result<Ulid> {
23 self.put_coordination_with_id(Ulid::new(), kind, content, metadata)
24 }
25
26 pub(super) fn put_coordination_with_id(
29 &mut self,
30 id: Ulid,
31 kind: &str,
32 content: String,
33 mut metadata: Map<String, Value>,
34 ) -> Result<Ulid> {
35 if self.read_only {
36 return Err(MnemoError::ReadOnly);
37 }
38 if !crate::memory::COORDINATION_KINDS.contains(&kind) {
39 return Err(MnemoError::Invalid(format!(
40 "{kind:?} isn't a coordination kind"
41 )));
42 }
43 metadata.insert(MNEMO_META_KIND.into(), Value::String(kind.to_string()));
44 let mut m = Memory::new(content, MemoryType::Episodic, self.sentinel_vector())
45 .with_scope(Scope::Shared);
46 m.id = id;
47 m.metadata = metadata;
48 self.put(m)
49 }
50}
51
52#[derive(Debug, Clone, PartialEq)]
54pub struct Message {
55 pub id: Ulid,
57 pub to: String,
59 pub from: String,
61 pub subject: String,
63 pub body: String,
65 pub refs: Vec<String>,
67 pub conversation: String,
69 pub hops: u64,
71 pub status: String,
73 pub delivery: String,
75 pub created_at: i64,
77 pub acked_at: Option<i64>,
79}
80
81impl Message {
82 pub fn from_memory(m: &Memory) -> Option<Message> {
84 if m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str)
85 != Some(crate::memory::MNEMO_META_KIND_MESSAGE)
86 {
87 return None;
88 }
89 let s = |k: &str| {
90 m.metadata
91 .get(k)
92 .and_then(Value::as_str)
93 .unwrap_or("")
94 .to_string()
95 };
96 let (subject, body) = match m.content.split_once("\n\n") {
97 Some((a, b)) => (a.to_string(), b.to_string()),
98 None => (m.content.clone(), String::new()),
99 };
100 Some(Message {
101 id: m.id,
102 to: s(MNEMO_META_TO),
103 from: s(MNEMO_META_FROM),
104 subject,
105 body,
106 refs: m
107 .metadata
108 .get(MNEMO_META_REFS)
109 .and_then(Value::as_array)
110 .map(|a| {
111 a.iter()
112 .filter_map(|v| v.as_str().map(str::to_string))
113 .collect()
114 })
115 .unwrap_or_default(),
116 conversation: s(MNEMO_META_CONVERSATION),
117 hops: m
118 .metadata
119 .get(MNEMO_META_HOPS)
120 .and_then(Value::as_u64)
121 .unwrap_or(0),
122 status: s(MNEMO_META_STATUS),
123 delivery: s(MNEMO_META_DELIVERY),
124 created_at: m.created_at,
125 acked_at: m.metadata.get(MNEMO_META_ACKED_AT).and_then(Value::as_i64),
126 })
127 }
128
129 pub fn is_for(&self, agent: Option<&str>, role: Option<&str>) -> bool {
132 if agent.is_some_and(|a| a == self.from) {
133 return false;
134 }
135 self.to == "all"
136 || agent.is_some_and(|a| a == self.to)
137 || role.is_some_and(|r| self.to.strip_prefix("role:") == Some(r))
138 }
139}
140
141fn valid_address(to: &str) -> bool {
143 to == "all"
144 || crate::memory::valid_agent_id(to) && !to.starts_with("role:")
145 || to
146 .strip_prefix("role:")
147 .is_some_and(crate::memory::valid_agent_id)
148}
149
150fn seen_by(m: &Memory) -> Vec<String> {
153 m.metadata
154 .get(crate::memory::MNEMO_META_SEEN_BY)
155 .and_then(Value::as_array)
156 .map(|a| {
157 a.iter()
158 .filter_map(|v| v.as_str().map(str::to_string))
159 .collect()
160 })
161 .unwrap_or_default()
162}
163
164fn is_sentinel(h: &[u16]) -> bool {
167 let Some(&first) = h.first() else {
168 return false;
169 };
170 let want = 1.0 / (h.len() as f32).sqrt();
171 h.iter().all(|&x| x == first) && (crate::veccol::f16_to_f32(first) - want).abs() < 1e-3
172}
173
174fn ready_seen_by(m: &Memory) -> Vec<String> {
177 m.metadata
178 .get(crate::memory::MNEMO_META_READY_SEEN_BY)
179 .and_then(Value::as_array)
180 .map(|a| {
181 a.iter()
182 .filter_map(|v| v.as_str().map(str::to_string))
183 .collect()
184 })
185 .unwrap_or_default()
186}
187
188fn add_seen_by(m: &mut Memory, agent: &str) -> bool {
190 let mut v = seen_by(m);
191 if v.iter().any(|a| a == agent) {
192 return false;
193 }
194 v.push(agent.to_string());
195 m.metadata.insert(
196 crate::memory::MNEMO_META_SEEN_BY.into(),
197 Value::Array(v.into_iter().map(Value::String).collect()),
198 );
199 true
200}
201
202impl Mnemo {
203 pub(super) fn coordination_records(
207 &mut self,
208 kind: &str,
209 locator: Option<&str>,
210 ) -> Result<Vec<Memory>> {
211 let want = locator.map(|l| locator_hash_of(kind, l));
212 let legacy = self.legacy_coordination_ids()?;
213 let entries: Vec<CatalogEntry> = self
214 .catalog
215 .iter()
216 .filter(|e| !e.deleted)
217 .filter(|e| {
218 legacy.contains(&e.id)
219 || e.v9.is_none_or(|r| {
220 r.kind == ROW_KIND_COORDINATION && want.is_none_or(|h| r.thread_hash == h)
221 })
222 })
223 .cloned()
224 .collect();
225 let mut out = Vec::new();
226 for e in entries {
227 let m = self.read_memory(&e)?;
228 if m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str) != Some(kind) {
229 continue;
230 }
231 if let Some(l) = locator {
232 if locator_of(&m) != Some(l) {
233 continue;
234 }
235 }
236 out.push(m);
237 }
238 Ok(out)
239 }
240
241 fn legacy_coordination_ids(&mut self) -> Result<std::collections::HashSet<u128>> {
249 if let Some(ids) = &self.legacy_coordination {
250 return Ok(ids.clone());
251 }
252 let episodic = super::records::memory_type_code(MemoryType::Episodic);
253 let candidates: Vec<CatalogEntry> = self
254 .catalog
255 .iter()
256 .filter(|e| !e.deleted)
257 .filter(|e| {
258 e.v9.is_some_and(|r| {
259 r.kind == super::records::ROW_KIND_FACT && r.memory_type == episodic
260 })
261 })
262 .cloned()
263 .collect();
264 let mut ids = std::collections::HashSet::new();
265 let mut pages: std::collections::HashMap<(u64, u64), Option<Vec<u8>>> =
267 std::collections::HashMap::new();
268 for e in candidates {
269 let vector = match e.v9 {
270 Some(r) if r.vec_page != 0 && !self.has_hot_vector(&e) => {
271 let page = pages
272 .entry((r.vec_page, r.vec_gen))
273 .or_insert_with(|| self.pager.read_page(r.vec_page, r.vec_gen).ok());
274 page.as_ref().and_then(|p| {
275 crate::veccol::decode_entry(p, self.dimensions, r.vec_slot as usize).ok()
276 })
277 }
278 _ => self.column_entry(&e).ok(),
279 };
280 if matches!(vector, Some((h, _)) if !is_sentinel(&h)) {
281 continue;
282 }
283 if is_coordination(&self.read_memory(&e)?) {
284 ids.insert(e.id);
285 }
286 }
287 self.legacy_coordination = Some(ids.clone());
288 Ok(ids)
289 }
290
291 pub fn mistagged_coordination(&mut self) -> Result<usize> {
295 let ids = self.legacy_coordination_ids()?;
296 Ok(self
297 .catalog
298 .iter()
299 .filter(|e| !e.deleted && ids.contains(&e.id))
300 .filter(|e| {
301 e.v9.is_some_and(|r| r.kind == super::records::ROW_KIND_FACT)
302 })
303 .count())
304 }
305
306 fn messages(&mut self) -> Result<Vec<Memory>> {
308 let mut out = self.coordination_records(crate::memory::MNEMO_META_KIND_MESSAGE, None)?;
309 out.sort_by_key(|m| m.created_at);
312 Ok(out)
313 }
314
315 #[allow(clippy::too_many_arguments)]
327 pub fn post(
328 &mut self,
329 to: &str,
330 subject: &str,
331 body: &str,
332 refs: &[String],
333 conversation: Option<&str>,
334 from: Option<&str>,
335 from_role: Option<&str>,
336 ) -> Result<Message> {
337 if self.read_only {
338 return Err(MnemoError::ReadOnly);
339 }
340 if !valid_address(to) {
341 return Err(MnemoError::Invalid(format!(
342 "{to:?} isn't an address: an agent id, role:<role>, or all"
343 )));
344 }
345 let subject = subject.trim();
346 if subject.is_empty() || subject.contains('\n') {
347 return Err(MnemoError::Invalid(
348 "a message's subject is one line, and not empty".into(),
349 ));
350 }
351 if subject.len() > crate::memory::MESSAGE_SUBJECT_MAX {
352 return Err(MnemoError::Invalid(format!(
353 "a message's subject is at most {} bytes",
354 crate::memory::MESSAGE_SUBJECT_MAX
355 )));
356 }
357 if body.len() > crate::memory::MESSAGE_BODY_MAX {
358 return Err(MnemoError::Invalid(format!(
359 "a message's body is at most {} bytes; put a longer one in a fact and send its id \
360 in refs",
361 crate::memory::MESSAGE_BODY_MAX
362 )));
363 }
364 let from = from
365 .map(str::to_string)
366 .or_else(|| self.author.clone())
367 .unwrap_or_else(|| "anonymous".to_string());
368 let now = memory::now_secs();
369 let earlier: Vec<Message> = self
370 .messages()?
371 .iter()
372 .filter_map(Message::from_memory)
373 .collect();
374 let mut hops = 0u64;
375 if let Some(c) = conversation {
376 if let Some(h) = earlier
377 .iter()
378 .filter(|m| m.conversation == c)
379 .map(|m| m.hops)
380 .max()
381 {
382 hops = h + 1;
383 }
384 }
385 if let Some(h) = earlier
388 .iter()
389 .filter(|m| now - m.created_at <= crate::memory::MESSAGE_PAIR_CARRY_SECS)
390 .filter(|m| (m.from == from && m.to == to) || (m.from == to && m.to == from))
391 .map(|m| m.hops)
392 .max()
393 {
394 hops = hops.max(h + 1);
395 }
396 let id = Ulid::new();
397 let conversation = conversation
398 .map(str::to_string)
399 .unwrap_or_else(|| id.to_string());
400 let mut meta = Map::new();
401 meta.insert(MNEMO_META_TO.into(), Value::String(to.into()));
402 meta.insert(MNEMO_META_FROM.into(), Value::String(from));
403 if let Some(r) = from_role {
404 meta.insert("_mnemo.from_role".into(), Value::String(r.to_string()));
405 }
406 meta.insert(MNEMO_META_CONVERSATION.into(), Value::String(conversation));
407 meta.insert(MNEMO_META_HOPS.into(), Value::from(hops));
408 meta.insert(
409 MNEMO_META_REFS.into(),
410 Value::Array(refs.iter().map(|r| Value::String(r.clone())).collect()),
411 );
412 meta.insert(
413 MNEMO_META_STATUS.into(),
414 Value::String(crate::memory::MESSAGE_UNREAD.into()),
415 );
416 meta.insert(
417 MNEMO_META_DELIVERY.into(),
418 Value::String(crate::memory::delivery::SENT.into()),
419 );
420 let content = if body.is_empty() {
421 subject.to_string()
422 } else {
423 format!("{subject}\n\n{body}")
424 };
425 let id = self.put_coordination_with_id(
426 id,
427 crate::memory::MNEMO_META_KIND_MESSAGE,
428 content,
429 meta,
430 )?;
431 let m = self.get(&id)?;
432 Ok(Message::from_memory(&m).expect("just written"))
433 }
434
435 pub fn inbox(
440 &mut self,
441 agent: Option<&str>,
442 role: Option<&str>,
443 unread_only: bool,
444 ) -> Result<Vec<Message>> {
445 self.inbox_in(
446 agent,
447 role,
448 unread_only,
449 crate::memory::VisibilitySet::DEFAULT,
450 )
451 }
452
453 pub fn inbox_in(
456 &mut self,
457 agent: Option<&str>,
458 role: Option<&str>,
459 unread_only: bool,
460 visibility: crate::memory::VisibilitySet,
461 ) -> Result<Vec<Message>> {
462 Ok(self
463 .messages()?
464 .iter()
465 .filter(|m| visibility.shows(m))
466 .filter_map(Message::from_memory)
467 .filter(|m| m.is_for(agent, role))
468 .filter(|m| !unread_only || m.status == crate::memory::MESSAGE_UNREAD)
469 .collect())
470 }
471
472 pub fn mark_seen(&mut self, ids: &[Ulid]) -> Result<usize> {
475 if self.read_only {
476 return Err(MnemoError::ReadOnly);
477 }
478 let mut changed = 0;
479 for id in ids {
480 let mut m = self.get(id)?;
481 let Some(msg) = Message::from_memory(&m) else {
482 continue;
483 };
484 let mut dirty = false;
485 if msg.delivery == crate::memory::delivery::SENT
486 || msg.delivery == crate::memory::delivery::DELIVERED
487 {
488 m.metadata.insert(
489 MNEMO_META_DELIVERY.into(),
490 Value::String(crate::memory::delivery::SEEN.into()),
491 );
492 dirty = true;
493 }
494 if msg.to == "all" || msg.to.starts_with("role:") {
497 if let Some(a) = self.author.clone() {
498 dirty |= add_seen_by(&mut m, &a);
499 }
500 }
501 if dirty {
502 self.put(m)?;
503 changed += 1;
504 }
505 }
506 Ok(changed)
507 }
508
509 pub fn ack(&mut self, id: &Ulid, note: Option<&str>, by: Option<&str>) -> Result<WriteOutcome> {
514 if self.read_only {
515 return Err(MnemoError::ReadOnly);
516 }
517 let mut m = self.get(id)?;
518 let Some(msg) = Message::from_memory(&m) else {
519 return Err(MnemoError::Invalid(format!("{id} isn't a message")));
520 };
521 if msg.status == crate::memory::MESSAGE_ACKED {
522 return Ok(WriteOutcome::Unchanged);
523 }
524 let now = memory::now_secs();
525 let by = by
526 .map(str::to_string)
527 .or_else(|| self.author.clone())
528 .unwrap_or_else(|| "anonymous".to_string());
529 let mut entry = Map::new();
530 entry.insert("from".into(), Value::String(msg.status.clone()));
531 entry.insert(
532 "to".into(),
533 Value::String(crate::memory::MESSAGE_ACKED.into()),
534 );
535 entry.insert("at".into(), Value::from(now));
536 entry.insert("by".into(), Value::String(by));
537 if let Some(n) = note {
538 entry.insert("note".into(), Value::String(n.to_string()));
539 }
540 let mut history = m
541 .metadata
542 .get(MNEMO_META_STATUS_HISTORY)
543 .and_then(Value::as_array)
544 .cloned()
545 .unwrap_or_default();
546 history.push(Value::Object(entry));
547 m.metadata
548 .insert(MNEMO_META_STATUS_HISTORY.into(), Value::Array(history));
549 m.metadata.insert(
550 MNEMO_META_STATUS.into(),
551 Value::String(crate::memory::MESSAGE_ACKED.into()),
552 );
553 m.metadata.insert(
554 MNEMO_META_DELIVERY.into(),
555 Value::String(crate::memory::delivery::DONE.into()),
556 );
557 m.metadata
558 .insert(MNEMO_META_ACKED_AT.into(), Value::from(now));
559 self.put(m)?;
560 Ok(WriteOutcome::Updated)
561 }
562
563 pub fn prune_messages(&mut self, older_than_secs: i64) -> Result<usize> {
567 if self.read_only {
568 return Err(MnemoError::ReadOnly);
569 }
570 let now = memory::now_secs();
571 let old: Vec<Ulid> = self
572 .messages()?
573 .iter()
574 .filter_map(Message::from_memory)
575 .filter(|m| prunable(m, now, older_than_secs))
576 .map(|m| m.id)
577 .collect();
578 for id in &old {
579 self.delete(id)?;
580 }
581 Ok(old.len())
582 }
583}
584
585fn prunable(m: &Message, now: i64, keep: i64) -> bool {
587 m.status == crate::memory::MESSAGE_ACKED && m.acked_at.is_some_and(|t| now - t > keep)
588}
589
590pub(super) fn compact_drops(m: &Memory, now: i64) -> bool {
593 Message::from_memory(m)
594 .is_some_and(|msg| prunable(&msg, now, crate::memory::MESSAGE_ACKED_KEEP_SECS))
595}
596
597use crate::memory::{
600 CLAIM_LAPSE_GRACE_SECS, CLAIM_TOPIC_MAX, CLAIM_TTL_DEFAULT, CLAIM_TTL_MAX, CLAIM_TTL_MIN,
601 MNEMO_META_AGENT, MNEMO_META_CLAIM_TOKEN, MNEMO_META_DEAD_SEEN_AT, MNEMO_META_EXPIRES_AT,
602 MNEMO_META_HOLDER, MNEMO_META_HOLDER_LOCK, MNEMO_META_KIND_CLAIM, MNEMO_META_KIND_PRESENCE,
603 MNEMO_META_LAST_ACTIVE, MNEMO_META_LEASE, MNEMO_META_PRESENCE_LOCK, MNEMO_META_TOOL,
604 MNEMO_META_TOPIC, PRESENCE_EVERY_SECS,
605};
606
607fn locator_of(m: &Memory) -> Option<&str> {
609 let key = match m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str)? {
610 MNEMO_META_KIND_CLAIM => MNEMO_META_TOPIC,
611 MNEMO_META_KIND_PRESENCE => MNEMO_META_AGENT,
612 crate::memory::MNEMO_META_KIND_TASK => crate::memory::MNEMO_META_SLUG,
613 crate::memory::MNEMO_META_KIND_FINDING => crate::memory::MNEMO_META_FINDING_ID,
614 _ => return None,
615 };
616 m.metadata.get(key).and_then(Value::as_str)
617}
618
619fn locator_hash_of(kind: &str, locator: &str) -> u32 {
620 super::records::fnv1a32(&[b"_mnemo.coordination", kind.as_bytes(), locator.as_bytes()])
621}
622
623pub(super) fn locator_hash(m: &Memory) -> u32 {
627 match (
628 m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str),
629 locator_of(m),
630 ) {
631 (Some(kind), Some(l)) => locator_hash_of(kind, l),
632 _ => 0,
633 }
634}
635
636#[derive(Debug, Clone, PartialEq, Eq)]
638pub enum ClaimOutcome {
639 Claimed {
642 token: String,
644 expires_at: i64,
646 },
647 HeldBy {
649 agent: String,
651 expires_at: i64,
653 },
654}
655
656#[derive(Debug, Clone, Copy, PartialEq, Eq)]
658pub enum ClaimStatus {
659 Held {
661 expires_at: i64,
663 },
664 Released,
666 Lost,
670}
671
672#[derive(Debug, Clone, PartialEq, Eq)]
674pub struct Claim {
675 pub topic: String,
677 pub holder: String,
679 pub expires_at: i64,
681 pub lease: i64,
683}
684
685#[derive(Debug, Clone, Copy, PartialEq, Eq)]
687pub enum Alive {
688 Yes,
690 No,
692 Unknown,
695}
696
697#[derive(Debug, Clone, PartialEq, Eq)]
699pub struct Presence {
700 pub agent: String,
702 pub role: Option<String>,
704 pub tool: Option<String>,
706 pub last_active: i64,
708 pub alive: Alive,
710 pub claims: Vec<String>,
712}
713
714fn meta_i64(m: &Memory, k: &str) -> Option<i64> {
715 m.metadata.get(k).and_then(Value::as_i64)
716}
717
718fn meta_string(m: &Memory, k: &str) -> Option<String> {
719 m.metadata
720 .get(k)
721 .and_then(Value::as_str)
722 .map(str::to_string)
723}
724
725fn effective_expiry(m: &Memory, now: i64) -> Option<i64> {
728 let token = m
729 .metadata
730 .get(MNEMO_META_CLAIM_TOKEN)
731 .and_then(Value::as_str)?;
732 if token.is_empty() {
733 return None;
734 }
735 let expires = meta_i64(m, MNEMO_META_EXPIRES_AT)?;
736 let lease = meta_i64(m, MNEMO_META_LEASE).unwrap_or(CLAIM_TTL_DEFAULT);
737 Some(expires.min(now.saturating_add(lease)))
738}
739
740fn is_live(m: &Memory, now: i64) -> bool {
742 effective_expiry(m, now).is_some_and(|e| now < e)
743}
744
745fn new_token() -> String {
746 format!(
747 "{:016x}{:016x}",
748 crate::crypto::random_u64(),
749 crate::crypto::random_u64()
750 )
751}
752
753fn check_topic(topic: &str) -> Result<()> {
754 if topic.trim().is_empty() || topic.contains('\n') || topic.len() > CLAIM_TOPIC_MAX {
755 return Err(MnemoError::Invalid(format!(
756 "a claim's topic is one line, not empty, at most {CLAIM_TOPIC_MAX} bytes"
757 )));
758 }
759 Ok(())
760}
761
762fn check_ttl(ttl: Option<i64>) -> Result<i64> {
763 let t = ttl.unwrap_or(CLAIM_TTL_DEFAULT);
764 if !(CLAIM_TTL_MIN..=CLAIM_TTL_MAX).contains(&t) {
765 return Err(MnemoError::Invalid(format!(
766 "a claim's ttl is {CLAIM_TTL_MIN} s to {CLAIM_TTL_MAX} s (24 h); got {t}"
767 )));
768 }
769 Ok(t)
770}
771
772impl Mnemo {
773 pub fn coordination_now(&self) -> i64 {
776 #[cfg(feature = "dev-hooks")]
777 let env: i64 = std::env::var("MNEMO_DEV_CLOCK_OFFSET")
778 .ok()
779 .and_then(|v| v.parse().ok())
780 .unwrap_or(0);
781 #[cfg(not(feature = "dev-hooks"))]
782 let env: i64 = 0;
783 memory::now_secs() + self.clock_offset + env
784 }
785
786 #[cfg(feature = "dev-hooks")]
789 #[doc(hidden)]
790 pub fn __set_clock_offset_for_testing(&mut self, secs: i64) {
791 self.clock_offset = secs;
792 }
793
794 fn claim_agent(&self) -> Result<String> {
795 self.author.clone().ok_or_else(|| {
796 MnemoError::Invalid(
797 "a claim needs an agent: set MNEMO_AGENT (or --as), or call set_author".into(),
798 )
799 })
800 }
801
802 fn find_claim(&mut self, topic: &str) -> Result<Option<Memory>> {
803 Ok(self
804 .coordination_records(MNEMO_META_KIND_CLAIM, Some(topic))?
805 .into_iter()
806 .next())
807 }
808
809 pub fn claim(&mut self, topic: &str, ttl: Option<i64>) -> Result<ClaimOutcome> {
824 if self.read_only {
825 return Err(MnemoError::ReadOnly);
826 }
827 check_topic(topic)?;
828 let ttl = check_ttl(ttl)?;
829 let agent = self.claim_agent()?;
830 let now = self.coordination_now();
831 let existing = self.find_claim(topic)?;
832 if let Some(mut m) = existing.clone() {
833 if is_live(&m, now) {
834 let holder = meta_string(&m, MNEMO_META_HOLDER).unwrap_or_default();
835 let expires = effective_expiry(&m, now).unwrap_or(now);
836 let mut changed = false;
837 let mut lapse = false;
838 let had_lock = m
839 .metadata
840 .get(MNEMO_META_HOLDER_LOCK)
841 .and_then(Value::as_bool)
842 .unwrap_or(false);
843 if had_lock && holder != agent {
844 match crate::shared::probe_presence_once(&self.path, &holder) {
845 Some(false) => match meta_i64(&m, MNEMO_META_DEAD_SEEN_AT) {
846 Some(t) if now - t >= CLAIM_LAPSE_GRACE_SECS => lapse = true,
847 Some(_) => {}
848 None => {
849 m.metadata
850 .insert(MNEMO_META_DEAD_SEEN_AT.into(), Value::from(now));
851 changed = true;
852 }
853 },
854 _ => {
855 changed |= m.metadata.remove(MNEMO_META_DEAD_SEEN_AT).is_some();
856 }
857 }
858 }
859 if !lapse {
860 if meta_i64(&m, MNEMO_META_EXPIRES_AT) != Some(expires) {
863 m.metadata
864 .insert(MNEMO_META_EXPIRES_AT.into(), Value::from(expires));
865 changed = true;
866 }
867 if changed {
868 self.put(m)?;
869 }
870 return Ok(ClaimOutcome::HeldBy {
871 agent: holder,
872 expires_at: expires,
873 });
874 }
875 }
876 }
877 let token = new_token();
878 let expires_at = now + ttl;
879 let mut meta = existing
880 .as_ref()
881 .map(|m| m.metadata.clone())
882 .unwrap_or_default();
883 meta.remove(MNEMO_META_DEAD_SEEN_AT);
884 meta.insert(MNEMO_META_TOPIC.into(), Value::String(topic.to_string()));
885 meta.insert(MNEMO_META_HOLDER.into(), Value::String(agent));
886 meta.insert(MNEMO_META_CLAIM_TOKEN.into(), Value::String(token.clone()));
887 meta.insert(MNEMO_META_EXPIRES_AT.into(), Value::from(expires_at));
888 meta.insert(MNEMO_META_LEASE.into(), Value::from(ttl));
889 meta.insert(
890 MNEMO_META_HOLDER_LOCK.into(),
891 Value::Bool(self.presence_held),
892 );
893 match existing {
894 Some(mut m) => {
895 m.metadata = meta;
896 self.put(m)?;
897 }
898 None => {
899 self.put_coordination_with_id(
900 Ulid::new(),
901 MNEMO_META_KIND_CLAIM,
902 format!("claim {topic}"),
903 meta,
904 )?;
905 }
906 }
907 Ok(ClaimOutcome::Claimed { token, expires_at })
908 }
909
910 pub fn renew(&mut self, topic: &str, token: &str, ttl: Option<i64>) -> Result<ClaimStatus> {
913 if self.read_only {
914 return Err(MnemoError::ReadOnly);
915 }
916 let now = self.coordination_now();
917 let Some(mut m) = self.find_claim(topic)? else {
918 return Ok(ClaimStatus::Lost);
919 };
920 if !is_live(&m, now) || meta_string(&m, MNEMO_META_CLAIM_TOKEN).as_deref() != Some(token) {
921 return Ok(ClaimStatus::Lost);
922 }
923 let lease = match ttl {
924 Some(t) => check_ttl(Some(t))?,
925 None => meta_i64(&m, MNEMO_META_LEASE).unwrap_or(CLAIM_TTL_DEFAULT),
926 };
927 let expires_at = now + lease;
928 m.metadata
929 .insert(MNEMO_META_EXPIRES_AT.into(), Value::from(expires_at));
930 m.metadata
931 .insert(MNEMO_META_LEASE.into(), Value::from(lease));
932 m.metadata.remove(MNEMO_META_DEAD_SEEN_AT);
933 self.put(m)?;
934 Ok(ClaimStatus::Held { expires_at })
935 }
936
937 pub fn release(&mut self, topic: &str, token: &str) -> Result<ClaimStatus> {
940 if self.read_only {
941 return Err(MnemoError::ReadOnly);
942 }
943 let now = self.coordination_now();
944 let Some(mut m) = self.find_claim(topic)? else {
945 return Ok(ClaimStatus::Lost);
946 };
947 if !is_live(&m, now) || meta_string(&m, MNEMO_META_CLAIM_TOKEN).as_deref() != Some(token) {
948 return Ok(ClaimStatus::Lost);
949 }
950 m.metadata.remove(MNEMO_META_CLAIM_TOKEN);
951 m.metadata.remove(MNEMO_META_DEAD_SEEN_AT);
952 m.metadata
953 .insert(MNEMO_META_EXPIRES_AT.into(), Value::from(now));
954 self.put(m)?;
955 Ok(ClaimStatus::Released)
956 }
957
958 pub fn check_claim(&mut self, topic: &str, token: &str) -> Result<ClaimStatus> {
961 let now = self.coordination_now();
962 let Some(m) = self.find_claim(topic)? else {
963 return Ok(ClaimStatus::Lost);
964 };
965 if meta_string(&m, MNEMO_META_CLAIM_TOKEN).as_deref() != Some(token) {
966 return Ok(ClaimStatus::Lost);
967 }
968 match effective_expiry(&m, now) {
969 Some(e) if now < e => Ok(ClaimStatus::Held { expires_at: e }),
970 _ => Ok(ClaimStatus::Lost),
971 }
972 }
973
974 pub fn claims(&mut self) -> Result<Vec<Claim>> {
976 let now = self.coordination_now();
977 let mut out: Vec<Claim> = self
978 .coordination_records(MNEMO_META_KIND_CLAIM, None)?
979 .iter()
980 .filter(|m| is_live(m, now))
981 .map(|m| Claim {
982 topic: meta_string(m, MNEMO_META_TOPIC).unwrap_or_default(),
983 holder: meta_string(m, MNEMO_META_HOLDER).unwrap_or_default(),
984 expires_at: effective_expiry(m, now).unwrap_or(now),
985 lease: meta_i64(m, MNEMO_META_LEASE).unwrap_or(CLAIM_TTL_DEFAULT),
986 })
987 .collect();
988 out.sort_by(|a, b| a.topic.cmp(&b.topic));
989 Ok(out)
990 }
991
992 pub fn touch_presence(&mut self, role: Option<&str>, tool: Option<&str>) -> Result<bool> {
999 if self.read_only {
1000 return Err(MnemoError::ReadOnly);
1001 }
1002 let Some(agent) = self.author.clone() else {
1003 return Ok(false);
1004 };
1005 let now = self.coordination_now();
1006 let existing = self
1007 .coordination_records(MNEMO_META_KIND_PRESENCE, Some(&agent))?
1008 .into_iter()
1009 .next();
1010 let role_v = role.map(|r| Value::String(r.to_string()));
1011 let tool_v = tool.map(|t| Value::String(t.to_string()));
1012 let defer = !self.presence_held
1016 && existing.as_ref().is_some_and(|m| {
1017 m.metadata
1018 .get(MNEMO_META_PRESENCE_LOCK)
1019 .and_then(Value::as_bool)
1020 .unwrap_or(false)
1021 });
1022 if let Some(m) = &existing {
1023 let fresh = meta_i64(m, MNEMO_META_LAST_ACTIVE)
1024 .is_some_and(|t| now >= t && now - t < PRESENCE_EVERY_SECS);
1025 let same = defer
1026 || (m.metadata.get(crate::memory::MNEMO_META_ROLE) == role_v.as_ref()
1027 && m.metadata.get(MNEMO_META_TOOL) == tool_v.as_ref()
1028 && m.metadata
1029 .get(MNEMO_META_PRESENCE_LOCK)
1030 .and_then(Value::as_bool)
1031 == Some(self.presence_held));
1032 if fresh && same {
1033 return Ok(false);
1034 }
1035 }
1036 if defer {
1037 let mut m = existing.expect("checked");
1038 m.metadata
1039 .insert(MNEMO_META_LAST_ACTIVE.into(), Value::from(now));
1040 self.put(m)?;
1041 return Ok(true);
1042 }
1043 let mut meta = existing
1044 .as_ref()
1045 .map(|m| m.metadata.clone())
1046 .unwrap_or_default();
1047 meta.insert(MNEMO_META_AGENT.into(), Value::String(agent.clone()));
1048 for (k, v) in [
1049 (crate::memory::MNEMO_META_ROLE, role_v),
1050 (MNEMO_META_TOOL, tool_v),
1051 ] {
1052 match v {
1053 Some(v) => {
1054 meta.insert(k.into(), v);
1055 }
1056 None => {
1057 meta.remove(k);
1058 }
1059 }
1060 }
1061 meta.insert(MNEMO_META_LAST_ACTIVE.into(), Value::from(now));
1062 meta.insert(
1063 MNEMO_META_PRESENCE_LOCK.into(),
1064 Value::Bool(self.presence_held),
1065 );
1066 match existing {
1067 Some(mut m) => {
1068 m.metadata = meta;
1069 self.put(m)?;
1070 }
1071 None => {
1072 self.put_coordination_with_id(
1073 Ulid::new(),
1074 MNEMO_META_KIND_PRESENCE,
1075 format!("presence {agent}"),
1076 meta,
1077 )?;
1078 }
1079 }
1080 Ok(true)
1081 }
1082
1083 pub fn who(&mut self) -> Result<Vec<Presence>> {
1088 let claims = self.claims()?;
1089 let records = self.coordination_records(MNEMO_META_KIND_PRESENCE, None)?;
1090 let mut out: Vec<Presence> = records
1091 .iter()
1092 .map(|m| {
1093 let agent = meta_string(m, MNEMO_META_AGENT).unwrap_or_default();
1094 let locked = m
1095 .metadata
1096 .get(MNEMO_META_PRESENCE_LOCK)
1097 .and_then(Value::as_bool)
1098 .unwrap_or(false);
1099 let alive = if !locked {
1100 Alive::Unknown
1101 } else {
1102 match crate::shared::probe_presence(&self.path, &agent) {
1103 Some(true) => Alive::Yes,
1104 Some(false) => Alive::No,
1105 None => Alive::Unknown,
1106 }
1107 };
1108 Presence {
1109 claims: claims
1110 .iter()
1111 .filter(|c| c.holder == agent)
1112 .map(|c| c.topic.clone())
1113 .collect(),
1114 role: meta_string(m, crate::memory::MNEMO_META_ROLE),
1115 tool: meta_string(m, MNEMO_META_TOOL),
1116 last_active: meta_i64(m, MNEMO_META_LAST_ACTIVE).unwrap_or(0),
1117 alive,
1118 agent,
1119 }
1120 })
1121 .collect();
1122 out.sort_by(|a, b| {
1123 b.last_active
1124 .cmp(&a.last_active)
1125 .then(a.agent.cmp(&b.agent))
1126 });
1127 Ok(out)
1128 }
1129}
1130
1131use crate::memory::{
1134 task_status, MNEMO_META_AFTER, MNEMO_META_CREATOR, MNEMO_META_KIND_TASK, MNEMO_META_OWNER,
1135 MNEMO_META_PRE_APPROVED, MNEMO_META_SLUG, TASK_CLAIM_TTL, TASK_SLUG_MAX, TASK_TRANSITIONS,
1136};
1137
1138#[derive(Debug, Clone, Default, PartialEq, Eq)]
1140pub struct TaskSpec {
1141 pub title: String,
1143 pub body: String,
1145 pub role: Option<String>,
1147 pub after: Vec<String>,
1149 pub pre_approved: bool,
1151 pub slug: Option<String>,
1153}
1154
1155#[derive(Debug, Clone, PartialEq)]
1157pub struct Task {
1158 pub id: Ulid,
1160 pub slug: String,
1162 pub title: String,
1164 pub body: String,
1166 pub role: Option<String>,
1168 pub status: String,
1170 pub owner: Option<String>,
1172 pub creator: String,
1174 pub after: Vec<String>,
1176 pub pre_approved: bool,
1178 pub created_at: i64,
1180 pub history: Vec<Value>,
1183}
1184
1185impl Task {
1186 pub fn from_memory(m: &Memory) -> Option<Task> {
1188 if m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str) != Some(MNEMO_META_KIND_TASK) {
1189 return None;
1190 }
1191 let (title, body) = match m.content.split_once("\n\n") {
1192 Some((a, b)) => (a.to_string(), b.to_string()),
1193 None => (m.content.clone(), String::new()),
1194 };
1195 Some(Task {
1196 id: m.id,
1197 slug: meta_string(m, MNEMO_META_SLUG).unwrap_or_default(),
1198 title,
1199 body,
1200 role: meta_string(m, crate::memory::MNEMO_META_ROLE),
1201 status: meta_string(m, MNEMO_META_STATUS).unwrap_or_default(),
1202 owner: meta_string(m, MNEMO_META_OWNER),
1203 creator: meta_string(m, MNEMO_META_CREATOR).unwrap_or_default(),
1204 after: m
1205 .metadata
1206 .get(MNEMO_META_AFTER)
1207 .and_then(Value::as_array)
1208 .map(|a| {
1209 a.iter()
1210 .filter_map(|v| v.as_str().map(str::to_string))
1211 .collect()
1212 })
1213 .unwrap_or_default(),
1214 pre_approved: m
1215 .metadata
1216 .get(MNEMO_META_PRE_APPROVED)
1217 .and_then(Value::as_bool)
1218 .unwrap_or(false),
1219 created_at: m.created_at,
1220 history: m
1221 .metadata
1222 .get(MNEMO_META_STATUS_HISTORY)
1223 .and_then(Value::as_array)
1224 .cloned()
1225 .unwrap_or_default(),
1226 })
1227 }
1228
1229 fn for_role(&self, role: Option<&str>) -> bool {
1232 self.role.is_none() || self.role.as_deref() == role
1233 }
1234}
1235
1236#[derive(Debug, Clone, PartialEq)]
1238pub struct TaskTaken {
1239 pub task: Task,
1241 pub token: String,
1244 pub expires_at: i64,
1246 pub reclaimed_from: Option<String>,
1248}
1249
1250#[derive(Debug, Clone, PartialEq, Eq)]
1253pub struct TaskClaim {
1254 pub token: String,
1256 pub expires_at: i64,
1258 pub retaken: bool,
1261}
1262
1263#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1265pub enum TaskLost {
1266 TakenBack,
1268 OtherToken,
1271}
1272
1273#[derive(Debug, Clone, PartialEq)]
1275pub enum TaskOutcome {
1276 Updated(Box<Task>, Option<TaskClaim>),
1280 Lost(TaskLost),
1282}
1283
1284pub fn slug_of(title: &str) -> String {
1287 let mut out = String::new();
1288 for c in title.chars() {
1289 if c.is_ascii_alphanumeric() {
1290 out.push(c.to_ascii_lowercase());
1291 } else if !out.ends_with('-') && !out.is_empty() {
1292 out.push('-');
1293 }
1294 if out.len() >= TASK_SLUG_MAX {
1295 break;
1296 }
1297 }
1298 out.trim_end_matches('-').to_string()
1299}
1300
1301fn valid_slug(s: &str) -> bool {
1302 !s.is_empty()
1303 && s.len() <= TASK_SLUG_MAX
1304 && s.bytes()
1305 .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b"._-".contains(&b))
1306}
1307
1308fn task_topic(slug: &str) -> String {
1309 format!("task:{slug}")
1310}
1311
1312impl Mnemo {
1313 fn task_records(&mut self, slug: Option<&str>) -> Result<Vec<Memory>> {
1314 let mut v = self.coordination_records(MNEMO_META_KIND_TASK, slug)?;
1315 v.sort_by_key(|m| m.created_at);
1316 Ok(v)
1317 }
1318
1319 fn task_record(&mut self, slug: &str) -> Result<Option<Memory>> {
1320 Ok(self.task_records(Some(slug))?.into_iter().next())
1321 }
1322
1323 pub fn task(&mut self, slug: &str) -> Result<Option<Task>> {
1325 Ok(self.task_record(slug)?.as_ref().and_then(Task::from_memory))
1326 }
1327
1328 pub fn tasks(&mut self, status: Option<&str>, role: Option<&str>) -> Result<Vec<Task>> {
1331 Ok(self
1332 .task_records(None)?
1333 .iter()
1334 .filter_map(Task::from_memory)
1335 .filter(|t| status.is_none_or(|s| t.status == s))
1336 .filter(|t| role.is_none() || t.for_role(role))
1337 .collect())
1338 }
1339
1340 pub fn ready_tasks(&mut self, role: Option<&str>) -> Result<Vec<Task>> {
1343 let all: Vec<Task> = self
1344 .task_records(None)?
1345 .iter()
1346 .filter_map(Task::from_memory)
1347 .collect();
1348 let done: std::collections::HashSet<&str> = all
1349 .iter()
1350 .filter(|t| t.status == task_status::DONE)
1351 .map(|t| t.slug.as_str())
1352 .collect();
1353 Ok(all
1354 .iter()
1355 .filter(|t| t.status == task_status::QUEUED && t.for_role(role))
1356 .filter(|t| t.after.iter().all(|a| done.contains(a.as_str())))
1357 .cloned()
1358 .collect())
1359 }
1360
1361 pub fn task_add(&mut self, spec: &TaskSpec) -> Result<(Task, WriteOutcome)> {
1367 if self.read_only {
1368 return Err(MnemoError::ReadOnly);
1369 }
1370 let title = spec.title.trim();
1371 if title.is_empty()
1372 || title.contains('\n')
1373 || title.len() > crate::memory::MESSAGE_SUBJECT_MAX
1374 {
1375 return Err(MnemoError::Invalid(format!(
1376 "a task's title is one line, not empty, at most {} bytes",
1377 crate::memory::MESSAGE_SUBJECT_MAX
1378 )));
1379 }
1380 if spec.body.len() > crate::memory::MESSAGE_BODY_MAX {
1381 return Err(MnemoError::Invalid(format!(
1382 "a task's body is at most {} bytes; put more in a fact and name it",
1383 crate::memory::MESSAGE_BODY_MAX
1384 )));
1385 }
1386 let slug = match &spec.slug {
1387 Some(s) => s.clone(),
1388 None => slug_of(title),
1389 };
1390 if !valid_slug(&slug) {
1391 return Err(MnemoError::Invalid(format!(
1392 "{slug:?} isn't a slug: 1 to {TASK_SLUG_MAX} of a-z, 0-9, '.', '_' and '-' \
1393 (give one with --slug)"
1394 )));
1395 }
1396 if let Some(r) = &spec.role {
1397 if !crate::memory::valid_agent_id(r) {
1398 return Err(MnemoError::Invalid(format!("{r:?} isn't a role")));
1399 }
1400 }
1401 for a in &spec.after {
1402 if a == &slug {
1403 return Err(MnemoError::Invalid("a task can't wait for itself".into()));
1404 }
1405 if self.task_record(a)?.is_none() {
1406 return Err(MnemoError::Invalid(format!("after: no task {a:?}")));
1407 }
1408 }
1409 let content = if spec.body.is_empty() {
1410 title.to_string()
1411 } else {
1412 format!("{title}\n\n{}", spec.body)
1413 };
1414 let set = |meta: &mut Map<String, Value>| {
1415 match &spec.role {
1416 Some(r) => {
1417 meta.insert(
1418 crate::memory::MNEMO_META_ROLE.into(),
1419 Value::String(r.clone()),
1420 );
1421 }
1422 None => {
1423 meta.remove(crate::memory::MNEMO_META_ROLE);
1424 }
1425 }
1426 meta.insert(
1427 MNEMO_META_AFTER.into(),
1428 Value::Array(
1429 spec.after
1430 .iter()
1431 .map(|a| Value::String(a.clone()))
1432 .collect(),
1433 ),
1434 );
1435 meta.insert(
1436 MNEMO_META_PRE_APPROVED.into(),
1437 Value::Bool(spec.pre_approved),
1438 );
1439 };
1440 if let Some(mut m) = self.task_record(&slug)? {
1441 let t = Task::from_memory(&m).expect("a task");
1442 let mut meta = m.metadata.clone();
1443 set(&mut meta);
1444 if meta == m.metadata && m.content == content {
1445 return Ok((t, WriteOutcome::Unchanged));
1446 }
1447 if t.status == task_status::DONE {
1450 let mut n = 2;
1451 while self.task_record(&format!("{slug}-{n}"))?.is_some() {
1452 n += 1;
1453 }
1454 return Err(MnemoError::Invalid(format!(
1455 "{slug} is done; give a new slug ({slug}-{n}?)"
1456 )));
1457 }
1458 let caller = self.author.clone().unwrap_or_else(|| "anonymous".into());
1459 if caller != t.creator {
1460 return Err(MnemoError::Invalid(format!(
1461 "that slug is {}'s task; it wasn't changed",
1462 t.creator
1463 )));
1464 }
1465 if self.closes_cycle(&slug, &spec.after)? {
1467 return Err(MnemoError::Invalid(format!(
1468 "after: that would make {slug} wait for itself, through the tasks it waits for"
1469 )));
1470 }
1471 m.metadata = meta;
1472 m.content = content;
1473 let id = m.id;
1474 self.put(m)?;
1475 let t = Task::from_memory(&self.get(&id)?).expect("a task");
1476 return Ok((t, WriteOutcome::Updated));
1477 }
1478 let mut meta = Map::new();
1479 meta.insert(MNEMO_META_SLUG.into(), Value::String(slug));
1480 meta.insert(
1481 MNEMO_META_STATUS.into(),
1482 Value::String(task_status::QUEUED.into()),
1483 );
1484 meta.insert(
1485 MNEMO_META_CREATOR.into(),
1486 Value::String(self.author.clone().unwrap_or_else(|| "anonymous".into())),
1487 );
1488 meta.insert(
1489 MNEMO_META_DELIVERY.into(),
1490 Value::String(crate::memory::delivery::SENT.into()),
1491 );
1492 set(&mut meta);
1493 let id = self.put_coordination_with_id(Ulid::new(), MNEMO_META_KIND_TASK, content, meta)?;
1494 let t = Task::from_memory(&self.get(&id)?).expect("a task");
1495 Ok((t, WriteOutcome::Added))
1496 }
1497
1498 fn closes_cycle(&mut self, slug: &str, after: &[String]) -> Result<bool> {
1501 let all: std::collections::HashMap<String, Vec<String>> = self
1502 .task_records(None)?
1503 .iter()
1504 .filter_map(Task::from_memory)
1505 .map(|t| (t.slug, t.after))
1506 .collect();
1507 let mut stack: Vec<&str> = after.iter().map(String::as_str).collect();
1508 let mut seen = std::collections::HashSet::new();
1509 while let Some(s) = stack.pop() {
1510 if s == slug {
1511 return Ok(true);
1512 }
1513 if seen.insert(s.to_string()) {
1514 if let Some(next) = all.get(s) {
1515 stack.extend(next.iter().map(String::as_str));
1516 }
1517 }
1518 }
1519 Ok(false)
1520 }
1521
1522 pub(super) fn task_history(
1524 m: &mut Memory,
1525 from: &str,
1526 to: &str,
1527 by: &str,
1528 at: i64,
1529 extra: &[(&str, &str)],
1530 ) {
1531 let mut e = Map::new();
1532 e.insert("from".into(), Value::String(from.into()));
1533 e.insert("to".into(), Value::String(to.into()));
1534 e.insert("at".into(), Value::from(at));
1535 e.insert("by".into(), Value::String(by.into()));
1536 for (k, v) in extra {
1537 e.insert((*k).into(), Value::String((*v).into()));
1538 }
1539 let mut h = m
1540 .metadata
1541 .get(MNEMO_META_STATUS_HISTORY)
1542 .and_then(Value::as_array)
1543 .cloned()
1544 .unwrap_or_default();
1545 h.push(Value::Object(e));
1546 m.metadata
1547 .insert(MNEMO_META_STATUS_HISTORY.into(), Value::Array(h));
1548 }
1549
1550 pub fn task_next(&mut self, role: Option<&str>) -> Result<Option<TaskTaken>> {
1558 if self.read_only {
1559 return Err(MnemoError::ReadOnly);
1560 }
1561 let agent = self.claim_agent()?;
1562 let now = self.coordination_now();
1563 let ready: Vec<Ulid> = self.ready_tasks(role)?.iter().map(|t| t.id).collect();
1564 let taken: Vec<Task> = self
1569 .task_records(None)?
1570 .iter()
1571 .filter_map(Task::from_memory)
1572 .filter(|t| t.status == task_status::ACTIVE || t.status == task_status::BLOCKED)
1573 .filter(|t| t.for_role(role))
1574 .collect();
1575 let (own, others): (Vec<&Task>, Vec<&Task>) = taken
1576 .iter()
1577 .partition(|t| t.owner.as_deref() == Some(agent.as_str()));
1578 for (id, back) in own
1579 .iter()
1580 .map(|t| (t.id, true))
1581 .chain(ready.into_iter().map(|i| (i, false)))
1582 .chain(others.iter().map(|t| (t.id, true)))
1583 {
1584 let mut m = self.get(&id)?;
1585 let t = Task::from_memory(&m).expect("a task");
1586 let (token, expires_at) =
1587 match self.claim(&task_topic(&t.slug), Some(TASK_CLAIM_TTL))? {
1588 ClaimOutcome::Claimed { token, expires_at } => (token, expires_at),
1589 ClaimOutcome::HeldBy { .. } => continue,
1590 };
1591 m = self.get(&id)?;
1594 let old = t.owner.clone();
1595 let own = old.as_deref() == Some(agent.as_str());
1596 if back && own {
1597 Self::task_history(
1598 &mut m,
1599 &t.status,
1600 task_status::ACTIVE,
1601 &agent,
1602 now,
1603 &[("note", "taken again after its claim lapsed")],
1604 );
1605 } else if back {
1606 let from = old.clone().unwrap_or_default();
1607 Self::task_history(
1608 &mut m,
1609 &t.status,
1610 task_status::ACTIVE,
1611 &agent,
1612 now,
1613 &[("reclaimed_from", from.as_str())],
1614 );
1615 } else {
1616 Self::task_history(
1617 &mut m,
1618 task_status::QUEUED,
1619 task_status::ACTIVE,
1620 &agent,
1621 now,
1622 &[],
1623 );
1624 }
1625 m.metadata.insert(
1626 MNEMO_META_STATUS.into(),
1627 Value::String(task_status::ACTIVE.into()),
1628 );
1629 m.metadata
1630 .insert(MNEMO_META_OWNER.into(), Value::String(agent.clone()));
1631 self.put(m)?;
1632 let task = Task::from_memory(&self.get(&id)?).expect("a task");
1633 return Ok(Some(TaskTaken {
1634 task,
1635 token,
1636 expires_at,
1637 reclaimed_from: if back && !own { old } else { None },
1638 }));
1639 }
1640 Ok(None)
1641 }
1642
1643 pub fn task_update(
1658 &mut self,
1659 slug: &str,
1660 status: Option<&str>,
1661 note: Option<&str>,
1662 token: Option<&str>,
1663 ) -> Result<TaskOutcome> {
1664 if self.read_only {
1665 return Err(MnemoError::ReadOnly);
1666 }
1667 let agent = self.claim_agent()?;
1668 let now = self.coordination_now();
1669 let Some(m) = self.task_record(slug)? else {
1670 return Err(MnemoError::Invalid(format!("no task {slug:?}")));
1671 };
1672 let t = Task::from_memory(&m).expect("a task");
1673 let to = status.unwrap_or(&t.status).to_string();
1674 if status.is_none() && note.is_none() {
1675 return Err(MnemoError::Invalid("give a status or a note".into()));
1676 }
1677 if token.is_some() && t.owner.as_deref() != Some(agent.as_str()) {
1680 return Ok(TaskOutcome::Lost(TaskLost::TakenBack));
1681 }
1682 let changing = to != t.status;
1683 if changing && !TASK_TRANSITIONS.contains(&(t.status.as_str(), to.as_str())) {
1684 return Err(MnemoError::Invalid(format!(
1685 "a task can't go from {} to {to}",
1686 t.status
1687 )));
1688 }
1689 if changing && t.status == task_status::QUEUED {
1690 return Err(MnemoError::Invalid(
1691 "a queued task is taken with `task next`".into(),
1692 ));
1693 }
1694 let topic = task_topic(slug);
1695 let claim = self.find_claim(&topic)?;
1696 let live = claim.as_ref().filter(|c| is_live(c, now));
1697 let claim_token = claim
1698 .as_ref()
1699 .and_then(|c| meta_string(c, MNEMO_META_CLAIM_TOKEN));
1700 let held_by_owner = live.is_some_and(|c| meta_string(c, MNEMO_META_HOLDER) == t.owner);
1701 let is_owner = t.owner.as_deref() == Some(agent.as_str());
1702 let is_creator = t.creator == agent;
1703 let by_owner = if changing && t.status == task_status::READY {
1705 if !(is_creator || (is_owner && t.pre_approved)) {
1707 return Err(MnemoError::Invalid(format!(
1708 "{slug} waits for its creator ({}) to set done",
1709 t.creator
1710 )));
1711 }
1712 false
1713 } else if changing && to == task_status::QUEUED && !is_owner {
1714 if let Some(c) = live {
1716 return Err(MnemoError::Invalid(format!(
1717 "{slug} is {}'s, and its claim is live until {}; only its owner can hand \
1718 it back before then",
1719 t.owner.as_deref().unwrap_or("its owner"),
1720 crate::memory::date_time_of(effective_expiry(c, now).unwrap_or(now))
1721 )));
1722 }
1723 false
1724 } else if t.status == task_status::DONE || (!changing && t.status == task_status::READY) {
1725 if !(is_creator || is_owner) {
1727 return Err(MnemoError::Invalid(format!("{slug} isn't yours")));
1728 }
1729 false
1730 } else if !changing && is_creator && !is_owner {
1731 false } else if t.status == task_status::QUEUED {
1733 if !is_creator {
1735 return Err(MnemoError::Invalid(format!("{slug} isn't yours")));
1736 }
1737 false
1738 } else {
1739 if !is_owner {
1740 return Ok(TaskOutcome::Lost(TaskLost::TakenBack));
1741 }
1742 true
1743 };
1744 let mut renew_token = None;
1751 if by_owner {
1752 let token_ok = token.is_none_or(|tk| claim_token.as_deref() == Some(tk));
1753 if live.is_some() && !held_by_owner {
1754 return Ok(TaskOutcome::Lost(TaskLost::TakenBack));
1755 }
1756 if !token_ok {
1757 return Ok(TaskOutcome::Lost(TaskLost::OtherToken));
1758 }
1759 if held_by_owner {
1760 renew_token = claim_token.clone();
1761 }
1762 }
1763 let mut m = m;
1764 let mut extra: Vec<(&str, &str)> = Vec::new();
1765 if let Some(n) = note {
1766 extra.push(("note", n));
1767 }
1768 Self::task_history(&mut m, &t.status, &to, &agent, now, &extra);
1769 m.metadata
1770 .insert(MNEMO_META_STATUS.into(), Value::String(to.clone()));
1771 if to == task_status::QUEUED {
1772 m.metadata.remove(MNEMO_META_OWNER);
1773 }
1774 let id = m.id;
1775 self.put(m)?;
1776 let releases =
1777 [task_status::READY, task_status::DONE, task_status::QUEUED].contains(&to.as_str());
1778 let mut held: Option<TaskClaim> = None;
1779 match (releases, by_owner, renew_token) {
1780 (true, _, Some(tk)) => {
1781 self.release(&topic, &tk)?;
1782 }
1783 (true, _, None) => {
1784 if let Some(mut c) = self.find_claim(&topic)? {
1786 if is_live(&c, now)
1787 && meta_string(&c, MNEMO_META_HOLDER) == t.owner
1788 && to == task_status::DONE
1789 {
1790 c.metadata.remove(MNEMO_META_CLAIM_TOKEN);
1791 c.metadata
1792 .insert(MNEMO_META_EXPIRES_AT.into(), Value::from(now));
1793 self.put(c)?;
1794 }
1795 }
1796 }
1797 (false, true, Some(tk)) => {
1798 if let ClaimStatus::Held { expires_at } =
1799 self.renew(&topic, &tk, Some(TASK_CLAIM_TTL))?
1800 {
1801 held = Some(TaskClaim {
1802 token: tk,
1803 expires_at,
1804 retaken: false,
1805 });
1806 }
1807 }
1808 (false, true, None) => {
1809 if let ClaimOutcome::Claimed { token, expires_at } =
1812 self.claim(&topic, Some(TASK_CLAIM_TTL))?
1813 {
1814 held = Some(TaskClaim {
1815 token,
1816 expires_at,
1817 retaken: true,
1818 });
1819 }
1820 }
1821 (false, false, _) => {}
1822 }
1823 Ok(TaskOutcome::Updated(
1824 Box::new(Task::from_memory(&self.get(&id)?).expect("a task")),
1825 held,
1826 ))
1827 }
1828}
1829
1830use crate::memory::{
1833 HOP_CAP, MNEMO_META_WAKES, MNEMO_META_WAKE_PAUSED, MNEMO_META_WARNED_EXPIRY, PAIR_BURST,
1834 PAIR_BURST_SECS, TASK_CLAIM_WARN_SECS, WAKE_COOLDOWN_SECS, WAKE_PER_HOUR,
1835};
1836
1837#[derive(Debug, Clone, Default, PartialEq)]
1840pub struct NewWork {
1841 pub messages: Vec<Message>,
1843 pub tasks: Vec<Task>,
1845 pub lapsing: Vec<Claim>,
1849 pub ready_for_done: Vec<Task>,
1853 pub findings: Vec<super::Finding>,
1857 pub agent: Option<String>,
1860}
1861
1862impl NewWork {
1863 pub fn is_empty(&self) -> bool {
1865 self.messages.is_empty()
1866 && self.tasks.is_empty()
1867 && self.lapsing.is_empty()
1868 && self.ready_for_done.is_empty()
1869 && self.findings.is_empty()
1870 }
1871}
1872
1873#[derive(Debug, Clone, PartialEq, Eq)]
1875pub enum Wake {
1876 Now {
1879 tasks: usize,
1881 messages: usize,
1883 },
1884 Nothing,
1886 Held(&'static str),
1889}
1890
1891impl Mnemo {
1892 pub fn new_work(&mut self, agent: Option<&str>, role: Option<&str>) -> Result<NewWork> {
1895 let now = self.coordination_now();
1896 let unseen =
1897 |d: &str| d == crate::memory::delivery::SENT || d == crate::memory::delivery::DELIVERED;
1898 let mut messages = Vec::new();
1902 for msg in self.inbox(agent, role, true)? {
1903 let broadcast = msg.to == "all" || msg.to.starts_with("role:");
1904 let new = match (broadcast, agent) {
1905 (true, Some(a)) => !seen_by(&self.get(&msg.id)?).iter().any(|s| s == a),
1906 _ => unseen(&msg.delivery),
1907 };
1908 if new {
1909 messages.push(msg);
1910 }
1911 }
1912 let mut tasks = Vec::new();
1913 for t in self.ready_tasks(role)? {
1914 let m = self.get(&t.id)?;
1915 let new = match agent {
1916 Some(a) => !seen_by(&m).iter().any(|s| s == a),
1917 None => meta_string(&m, MNEMO_META_DELIVERY).is_none_or(|d| unseen(&d)),
1918 };
1919 if new {
1920 tasks.push(t);
1921 }
1922 }
1923 let mut ready_for_done = Vec::new();
1926 if let Some(a) = agent {
1927 for t in self.tasks(Some(crate::memory::task_status::READY), None)? {
1928 if t.creator == a && !ready_seen_by(&self.get(&t.id)?).iter().any(|s| s == a) {
1929 ready_for_done.push(t);
1930 }
1931 }
1932 }
1933 let mut findings = Vec::new();
1935 if let (Some(a), Some("planner")) = (agent, role) {
1936 let open = super::FindingFilter {
1937 status: Some(crate::memory::finding_status::OPEN.into()),
1938 ..Default::default()
1939 };
1940 for f in self.findings(&open)? {
1941 if !seen_by(&self.get(&f.record_id)?).iter().any(|s| s == a) {
1942 findings.push(f);
1943 }
1944 }
1945 }
1946 let mut lapsing = Vec::new();
1947 if let Some(a) = agent {
1948 for m in self.coordination_records(MNEMO_META_KIND_CLAIM, None)? {
1949 let topic = meta_string(&m, MNEMO_META_TOPIC).unwrap_or_default();
1950 if !topic.starts_with("task:")
1951 || meta_string(&m, MNEMO_META_HOLDER).as_deref() != Some(a)
1952 || !is_live(&m, now)
1953 {
1954 continue;
1955 }
1956 let e = effective_expiry(&m, now).unwrap_or(now);
1957 if e - now <= TASK_CLAIM_WARN_SECS
1958 && meta_i64(&m, MNEMO_META_WARNED_EXPIRY) != Some(e)
1959 {
1960 lapsing.push(Claim {
1961 topic,
1962 holder: a.to_string(),
1963 expires_at: e,
1964 lease: meta_i64(&m, MNEMO_META_LEASE).unwrap_or(CLAIM_TTL_DEFAULT),
1965 });
1966 }
1967 }
1968 }
1969 Ok(NewWork {
1970 messages,
1971 tasks,
1972 lapsing,
1973 ready_for_done,
1974 findings,
1975 agent: agent.map(str::to_string),
1976 })
1977 }
1978
1979 pub fn mark_shown(&mut self, work: &NewWork) -> Result<()> {
1984 if self.read_only {
1985 return Err(MnemoError::ReadOnly);
1986 }
1987 let ids: Vec<Ulid> = work.messages.iter().map(|m| m.id).collect();
1988 let who = work.agent.clone().or_else(|| self.author.clone());
1990 let author = std::mem::replace(&mut self.author, who.clone());
1991 let r = self.mark_seen(&ids);
1992 self.author = author;
1993 r?;
1994 for t in &work.tasks {
1995 let mut m = self.get(&t.id)?;
1996 match who.clone() {
1997 Some(a) => {
1999 if add_seen_by(&mut m, &a) {
2000 self.put(m)?;
2001 }
2002 }
2003 None => {
2004 m.metadata.insert(
2005 MNEMO_META_DELIVERY.into(),
2006 Value::String(crate::memory::delivery::SEEN.into()),
2007 );
2008 self.put(m)?;
2009 }
2010 }
2011 }
2012 if let Some(a) = &who {
2014 for f in &work.findings {
2015 let mut m = self.get(&f.record_id)?;
2016 if add_seen_by(&mut m, a) {
2017 self.put(m)?;
2018 }
2019 }
2020 }
2021 if let Some(a) = &who {
2023 for t in &work.ready_for_done {
2024 let mut m = self.get(&t.id)?;
2025 let mut v = ready_seen_by(&m);
2026 if v.iter().any(|s| s == a) {
2027 continue;
2028 }
2029 v.push(a.clone());
2030 m.metadata.insert(
2031 crate::memory::MNEMO_META_READY_SEEN_BY.into(),
2032 Value::Array(v.into_iter().map(Value::String).collect()),
2033 );
2034 self.put(m)?;
2035 }
2036 }
2037 for c in &work.lapsing {
2038 if let Some(mut m) = self.find_claim(&c.topic)? {
2039 m.metadata
2040 .insert(MNEMO_META_WARNED_EXPIRY.into(), Value::from(c.expires_at));
2041 self.put(m)?;
2042 }
2043 }
2044 Ok(())
2045 }
2046
2047 pub fn wake_paused(&mut self) -> Result<Option<(String, i64)>> {
2050 let Some(m) = self
2051 .about_in(crate::memory::VisibilitySet::ALL)?
2052 .into_iter()
2053 .find(is_manifest)
2054 else {
2055 return Ok(None);
2056 };
2057 Ok(m.metadata.get(MNEMO_META_WAKE_PAUSED).map(|v| {
2058 (
2059 v.get("by")
2060 .and_then(Value::as_str)
2061 .unwrap_or("")
2062 .to_string(),
2063 v.get("at").and_then(Value::as_i64).unwrap_or(0),
2064 )
2065 }))
2066 }
2067
2068 pub fn set_wake_paused(&mut self, paused: bool) -> Result<WriteOutcome> {
2072 if self.read_only {
2073 return Err(MnemoError::ReadOnly);
2074 }
2075 let Some(mut m) = self
2076 .about_in(crate::memory::VisibilitySet::ALL)?
2077 .into_iter()
2078 .find(is_manifest)
2079 else {
2080 return Err(MnemoError::Invalid(
2081 "this brain has no manifest to record the pause on".into(),
2082 ));
2083 };
2084 if m.metadata.contains_key(MNEMO_META_WAKE_PAUSED) == paused {
2085 return Ok(WriteOutcome::Unchanged);
2086 }
2087 if paused {
2088 let mut v = Map::new();
2089 v.insert(
2090 "by".into(),
2091 Value::String(self.author.clone().unwrap_or_else(|| "anonymous".into())),
2092 );
2093 v.insert("at".into(), Value::from(self.coordination_now()));
2094 m.metadata
2095 .insert(MNEMO_META_WAKE_PAUSED.into(), Value::Object(v));
2096 } else {
2097 m.metadata.remove(MNEMO_META_WAKE_PAUSED);
2098 }
2099 self.put(m)?;
2100 Ok(WriteOutcome::Updated)
2101 }
2102
2103 pub fn wake(&mut self, agent: &str, role: Option<&str>) -> Result<Wake> {
2118 if self.read_only {
2119 return Err(MnemoError::ReadOnly);
2120 }
2121 let now = self.coordination_now();
2122 let sent = crate::memory::delivery::SENT;
2123 let mut tasks = Vec::new();
2124 for t in self.ready_tasks(role)? {
2125 let m = self.get(&t.id)?;
2126 if t.pre_approved
2127 && meta_string(&m, MNEMO_META_DELIVERY).as_deref() == Some(sent)
2128 && !seen_by(&m).iter().any(|s| s == agent)
2129 {
2130 tasks.push(t.id);
2131 }
2132 }
2133 let all_msgs: Vec<Message> = self
2134 .messages()?
2135 .iter()
2136 .filter_map(Message::from_memory)
2137 .collect();
2138 let candidates: Vec<&Message> = all_msgs
2139 .iter()
2140 .filter(|m| m.to == agent && m.from != agent)
2141 .filter(|m| m.status == crate::memory::MESSAGE_UNREAD && m.delivery == sent)
2142 .collect();
2143 if tasks.is_empty() && candidates.is_empty() {
2144 return Ok(Wake::Nothing);
2145 }
2146 if self.wake_paused()?.is_some() {
2147 return Ok(Wake::Held("paused"));
2148 }
2149 let burst = |a: &str, b: &str| {
2150 all_msgs
2151 .iter()
2152 .filter(|m| now - m.created_at <= PAIR_BURST_SECS)
2153 .filter(|m| (m.from == a && m.to == b) || (m.from == b && m.to == a))
2154 .count()
2155 >= PAIR_BURST
2156 };
2157 let mut reason = None;
2158 let messages: Vec<Ulid> = candidates
2159 .iter()
2160 .filter(|m| {
2161 let reply = m.conversation != m.id.to_string();
2162 if reply && m.hops > HOP_CAP {
2163 reason = Some("the thread reached its hop cap");
2164 return false;
2165 }
2166 if burst(&m.from, &m.to) {
2167 reason = Some("a burst of messages between two agents");
2168 return false;
2169 }
2170 true
2171 })
2172 .map(|m| m.id)
2173 .collect();
2174 if tasks.is_empty() && messages.is_empty() {
2175 return Ok(Wake::Held(reason.unwrap_or("a guardrail")));
2176 }
2177 let presence = self
2179 .coordination_records(MNEMO_META_KIND_PRESENCE, Some(agent))?
2180 .into_iter()
2181 .next();
2182 let mut wakes: Vec<i64> = presence
2183 .as_ref()
2184 .and_then(|m| m.metadata.get(MNEMO_META_WAKES))
2185 .and_then(Value::as_array)
2186 .map(|a| a.iter().filter_map(Value::as_i64).collect())
2187 .unwrap_or_default();
2188 wakes.retain(|t| now - t < 3600 && *t <= now);
2189 if wakes.len() >= WAKE_PER_HOUR {
2190 return Ok(Wake::Held("the hourly limit of wake-ups"));
2191 }
2192 if wakes.iter().any(|t| now - t < WAKE_COOLDOWN_SECS) {
2193 return Ok(Wake::Held("the cooldown between wake-ups"));
2194 }
2195 wakes.push(now);
2196 let delivered = Value::String(crate::memory::delivery::DELIVERED.into());
2197 for id in tasks.iter().chain(messages.iter()) {
2198 let mut m = self.get(id)?;
2199 m.metadata
2200 .insert(MNEMO_META_DELIVERY.into(), delivered.clone());
2201 self.put(m)?;
2202 }
2203 let w = Value::Array(wakes.into_iter().map(Value::from).collect());
2204 match presence {
2205 Some(mut m) => {
2206 m.metadata.insert(MNEMO_META_WAKES.into(), w);
2207 self.put(m)?;
2208 }
2209 None => {
2210 let mut meta = Map::new();
2211 meta.insert(MNEMO_META_AGENT.into(), Value::String(agent.to_string()));
2212 meta.insert(MNEMO_META_LAST_ACTIVE.into(), Value::from(0));
2213 meta.insert(MNEMO_META_PRESENCE_LOCK.into(), Value::Bool(false));
2214 meta.insert(MNEMO_META_WAKES.into(), w);
2215 self.put_coordination_with_id(
2216 Ulid::new(),
2217 MNEMO_META_KIND_PRESENCE,
2218 format!("presence {agent}"),
2219 meta,
2220 )?;
2221 }
2222 }
2223 Ok(Wake::Now {
2224 tasks: tasks.len(),
2225 messages: messages.len(),
2226 })
2227 }
2228}
2229
2230#[derive(Debug, Clone, PartialEq, Eq)]
2234pub struct Stale {
2235 pub id: Ulid,
2237 pub what: String,
2241 pub since: i64,
2243 pub text: String,
2245 pub whose: Option<String>,
2247 pub visibility: String,
2249}
2250
2251impl Mnemo {
2252 pub fn stale(&mut self) -> Result<Vec<Stale>> {
2259 use super::records::{ROW_KIND_ESSENCE, ROW_REVIEW};
2260 let now = self.coordination_now();
2261 let entries: Vec<CatalogEntry> = self
2262 .catalog
2263 .iter()
2264 .filter(|e| !e.deleted)
2265 .filter(|e| {
2266 e.v9.is_none_or(|r| {
2267 r.kind == ROW_KIND_ESSENCE
2268 || r.kind == ROW_KIND_COORDINATION
2269 || r.flags & ROW_REVIEW != 0
2270 })
2271 })
2272 .cloned()
2273 .collect();
2274 let mut out = Vec::new();
2275 for e in entries {
2276 let m = self.read_memory(&e)?;
2277 let Some(since) = crate::memory::stale_since(&m, now) else {
2278 continue;
2279 };
2280 let s = |k: &str| meta_string(&m, k);
2281 let kind = s(MNEMO_META_KIND);
2282 let what = match kind.as_deref() {
2283 Some("essence") => format!(
2284 "essence {}",
2285 s(crate::memory::MNEMO_META_SECTION).unwrap_or_default()
2286 ),
2287 Some(k @ ("task" | "message")) => {
2288 format!("{k} {}", s(MNEMO_META_STATUS).unwrap_or_default())
2289 }
2290 Some(k) => k.to_string(),
2291 None => "fact".to_string(),
2292 };
2293 let whose = match kind.as_deref() {
2294 Some("task") => s(MNEMO_META_OWNER),
2295 Some("message") => s(MNEMO_META_TO),
2296 _ => s(crate::memory::MNEMO_META_AUTHOR),
2297 };
2298 out.push(Stale {
2299 id: m.id,
2300 what,
2301 since,
2302 text: m.content.lines().next().unwrap_or("").to_string(),
2303 whose,
2304 visibility: crate::memory::visibility_of(&m).to_string(),
2305 });
2306 }
2307 out.sort_by_key(|x| (x.since, x.id.0));
2308 Ok(out)
2309 }
2310}
2311
2312#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
2314pub struct KindCounts {
2315 pub facts: usize,
2317 pub turns: usize,
2319 pub essence: usize,
2321 pub coordination: usize,
2323}
2324
2325impl Mnemo {
2326 pub fn kind_counts(&self) -> KindCounts {
2330 use super::records::{ROW_KIND_ESSENCE, ROW_KIND_THREAD_LINK, ROW_KIND_TURN};
2331 let mut c = KindCounts::default();
2332 for e in self.catalog.iter().filter(|e| !e.deleted) {
2333 match e.v9.map(|r| r.kind) {
2334 Some(ROW_KIND_TURN | ROW_KIND_THREAD_LINK) => c.turns += 1,
2335 Some(ROW_KIND_ESSENCE) => c.essence += 1,
2336 Some(ROW_KIND_COORDINATION) => c.coordination += 1,
2337 _ => c.facts += 1,
2338 }
2339 }
2340 c
2341 }
2342}
2343
2344#[cfg(test)]
2345mod legacy_scan_tests {
2346 use super::is_sentinel;
2347
2348 #[test]
2351 fn the_sentinel_is_told_from_an_ordinary_vector() {
2352 for dims in [4, 32, 384, 768] {
2353 let s = vec![1.0 / (dims as f32).sqrt(); dims];
2354 let (h, _) = crate::veccol::quantize(&s);
2355 assert!(is_sentinel(&h), "{dims}");
2356 let mut v = s.clone();
2357 v[dims / 2] += 0.05;
2358 assert!(!is_sentinel(&crate::veccol::quantize(&v).0), "{dims}");
2359 let flat = vec![0.5; dims];
2360 assert_eq!(
2361 is_sentinel(&crate::veccol::quantize(&flat).0),
2362 dims == 4,
2363 "{dims}"
2364 );
2365 }
2366 assert!(!is_sentinel(&[]));
2367 }
2368}