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 fn coordination_records(&mut self, kind: &str, locator: Option<&str>) -> Result<Vec<Memory>> {
207 let want = locator.map(|l| locator_hash_of(kind, l));
208 let legacy = self.legacy_coordination_ids()?;
209 let entries: Vec<CatalogEntry> = self
210 .catalog
211 .iter()
212 .filter(|e| !e.deleted)
213 .filter(|e| {
214 legacy.contains(&e.id)
215 || e.v9.is_none_or(|r| {
216 r.kind == ROW_KIND_COORDINATION && want.is_none_or(|h| r.thread_hash == h)
217 })
218 })
219 .cloned()
220 .collect();
221 let mut out = Vec::new();
222 for e in entries {
223 let m = self.read_memory(&e)?;
224 if m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str) != Some(kind) {
225 continue;
226 }
227 if let Some(l) = locator {
228 if locator_of(&m) != Some(l) {
229 continue;
230 }
231 }
232 out.push(m);
233 }
234 Ok(out)
235 }
236
237 fn legacy_coordination_ids(&mut self) -> Result<std::collections::HashSet<u128>> {
245 if let Some(ids) = &self.legacy_coordination {
246 return Ok(ids.clone());
247 }
248 let episodic = super::records::memory_type_code(MemoryType::Episodic);
249 let candidates: Vec<CatalogEntry> = self
250 .catalog
251 .iter()
252 .filter(|e| !e.deleted)
253 .filter(|e| {
254 e.v9.is_some_and(|r| {
255 r.kind == super::records::ROW_KIND_FACT && r.memory_type == episodic
256 })
257 })
258 .cloned()
259 .collect();
260 let mut ids = std::collections::HashSet::new();
261 let mut pages: std::collections::HashMap<(u64, u64), Option<Vec<u8>>> =
263 std::collections::HashMap::new();
264 for e in candidates {
265 let vector = match e.v9 {
266 Some(r) if r.vec_page != 0 && !self.has_hot_vector(&e) => {
267 let page = pages
268 .entry((r.vec_page, r.vec_gen))
269 .or_insert_with(|| self.pager.read_page(r.vec_page, r.vec_gen).ok());
270 page.as_ref().and_then(|p| {
271 crate::veccol::decode_entry(p, self.dimensions, r.vec_slot as usize).ok()
272 })
273 }
274 _ => self.column_entry(&e).ok(),
275 };
276 if matches!(vector, Some((h, _)) if !is_sentinel(&h)) {
277 continue;
278 }
279 if is_coordination(&self.read_memory(&e)?) {
280 ids.insert(e.id);
281 }
282 }
283 self.legacy_coordination = Some(ids.clone());
284 Ok(ids)
285 }
286
287 pub fn mistagged_coordination(&mut self) -> Result<usize> {
291 let ids = self.legacy_coordination_ids()?;
292 Ok(self
293 .catalog
294 .iter()
295 .filter(|e| !e.deleted && ids.contains(&e.id))
296 .filter(|e| {
297 e.v9.is_some_and(|r| r.kind == super::records::ROW_KIND_FACT)
298 })
299 .count())
300 }
301
302 fn messages(&mut self) -> Result<Vec<Memory>> {
304 let mut out = self.coordination_records(crate::memory::MNEMO_META_KIND_MESSAGE, None)?;
305 out.sort_by_key(|m| m.created_at);
308 Ok(out)
309 }
310
311 #[allow(clippy::too_many_arguments)]
323 pub fn post(
324 &mut self,
325 to: &str,
326 subject: &str,
327 body: &str,
328 refs: &[String],
329 conversation: Option<&str>,
330 from: Option<&str>,
331 from_role: Option<&str>,
332 ) -> Result<Message> {
333 if self.read_only {
334 return Err(MnemoError::ReadOnly);
335 }
336 if !valid_address(to) {
337 return Err(MnemoError::Invalid(format!(
338 "{to:?} isn't an address: an agent id, role:<role>, or all"
339 )));
340 }
341 let subject = subject.trim();
342 if subject.is_empty() || subject.contains('\n') {
343 return Err(MnemoError::Invalid(
344 "a message's subject is one line, and not empty".into(),
345 ));
346 }
347 if subject.len() > crate::memory::MESSAGE_SUBJECT_MAX {
348 return Err(MnemoError::Invalid(format!(
349 "a message's subject is at most {} bytes",
350 crate::memory::MESSAGE_SUBJECT_MAX
351 )));
352 }
353 if body.len() > crate::memory::MESSAGE_BODY_MAX {
354 return Err(MnemoError::Invalid(format!(
355 "a message's body is at most {} bytes; put a longer one in a fact and send its id \
356 in refs",
357 crate::memory::MESSAGE_BODY_MAX
358 )));
359 }
360 let from = from
361 .map(str::to_string)
362 .or_else(|| self.author.clone())
363 .unwrap_or_else(|| "anonymous".to_string());
364 let now = memory::now_secs();
365 let earlier: Vec<Message> = self
366 .messages()?
367 .iter()
368 .filter_map(Message::from_memory)
369 .collect();
370 let mut hops = 0u64;
371 if let Some(c) = conversation {
372 if let Some(h) = earlier
373 .iter()
374 .filter(|m| m.conversation == c)
375 .map(|m| m.hops)
376 .max()
377 {
378 hops = h + 1;
379 }
380 }
381 if let Some(h) = earlier
384 .iter()
385 .filter(|m| now - m.created_at <= crate::memory::MESSAGE_PAIR_CARRY_SECS)
386 .filter(|m| (m.from == from && m.to == to) || (m.from == to && m.to == from))
387 .map(|m| m.hops)
388 .max()
389 {
390 hops = hops.max(h + 1);
391 }
392 let id = Ulid::new();
393 let conversation = conversation
394 .map(str::to_string)
395 .unwrap_or_else(|| id.to_string());
396 let mut meta = Map::new();
397 meta.insert(MNEMO_META_TO.into(), Value::String(to.into()));
398 meta.insert(MNEMO_META_FROM.into(), Value::String(from));
399 if let Some(r) = from_role {
400 meta.insert("_mnemo.from_role".into(), Value::String(r.to_string()));
401 }
402 meta.insert(MNEMO_META_CONVERSATION.into(), Value::String(conversation));
403 meta.insert(MNEMO_META_HOPS.into(), Value::from(hops));
404 meta.insert(
405 MNEMO_META_REFS.into(),
406 Value::Array(refs.iter().map(|r| Value::String(r.clone())).collect()),
407 );
408 meta.insert(
409 MNEMO_META_STATUS.into(),
410 Value::String(crate::memory::MESSAGE_UNREAD.into()),
411 );
412 meta.insert(
413 MNEMO_META_DELIVERY.into(),
414 Value::String(crate::memory::delivery::SENT.into()),
415 );
416 let content = if body.is_empty() {
417 subject.to_string()
418 } else {
419 format!("{subject}\n\n{body}")
420 };
421 let id = self.put_coordination_with_id(
422 id,
423 crate::memory::MNEMO_META_KIND_MESSAGE,
424 content,
425 meta,
426 )?;
427 let m = self.get(&id)?;
428 Ok(Message::from_memory(&m).expect("just written"))
429 }
430
431 pub fn inbox(
436 &mut self,
437 agent: Option<&str>,
438 role: Option<&str>,
439 unread_only: bool,
440 ) -> Result<Vec<Message>> {
441 self.inbox_in(
442 agent,
443 role,
444 unread_only,
445 crate::memory::VisibilitySet::DEFAULT,
446 )
447 }
448
449 pub fn inbox_in(
452 &mut self,
453 agent: Option<&str>,
454 role: Option<&str>,
455 unread_only: bool,
456 visibility: crate::memory::VisibilitySet,
457 ) -> Result<Vec<Message>> {
458 Ok(self
459 .messages()?
460 .iter()
461 .filter(|m| visibility.shows(m))
462 .filter_map(Message::from_memory)
463 .filter(|m| m.is_for(agent, role))
464 .filter(|m| !unread_only || m.status == crate::memory::MESSAGE_UNREAD)
465 .collect())
466 }
467
468 pub fn mark_seen(&mut self, ids: &[Ulid]) -> Result<usize> {
471 if self.read_only {
472 return Err(MnemoError::ReadOnly);
473 }
474 let mut changed = 0;
475 for id in ids {
476 let mut m = self.get(id)?;
477 let Some(msg) = Message::from_memory(&m) else {
478 continue;
479 };
480 let mut dirty = false;
481 if msg.delivery == crate::memory::delivery::SENT
482 || msg.delivery == crate::memory::delivery::DELIVERED
483 {
484 m.metadata.insert(
485 MNEMO_META_DELIVERY.into(),
486 Value::String(crate::memory::delivery::SEEN.into()),
487 );
488 dirty = true;
489 }
490 if msg.to == "all" || msg.to.starts_with("role:") {
493 if let Some(a) = self.author.clone() {
494 dirty |= add_seen_by(&mut m, &a);
495 }
496 }
497 if dirty {
498 self.put(m)?;
499 changed += 1;
500 }
501 }
502 Ok(changed)
503 }
504
505 pub fn ack(&mut self, id: &Ulid, note: Option<&str>, by: Option<&str>) -> Result<WriteOutcome> {
510 if self.read_only {
511 return Err(MnemoError::ReadOnly);
512 }
513 let mut m = self.get(id)?;
514 let Some(msg) = Message::from_memory(&m) else {
515 return Err(MnemoError::Invalid(format!("{id} isn't a message")));
516 };
517 if msg.status == crate::memory::MESSAGE_ACKED {
518 return Ok(WriteOutcome::Unchanged);
519 }
520 let now = memory::now_secs();
521 let by = by
522 .map(str::to_string)
523 .or_else(|| self.author.clone())
524 .unwrap_or_else(|| "anonymous".to_string());
525 let mut entry = Map::new();
526 entry.insert("from".into(), Value::String(msg.status.clone()));
527 entry.insert(
528 "to".into(),
529 Value::String(crate::memory::MESSAGE_ACKED.into()),
530 );
531 entry.insert("at".into(), Value::from(now));
532 entry.insert("by".into(), Value::String(by));
533 if let Some(n) = note {
534 entry.insert("note".into(), Value::String(n.to_string()));
535 }
536 let mut history = m
537 .metadata
538 .get(MNEMO_META_STATUS_HISTORY)
539 .and_then(Value::as_array)
540 .cloned()
541 .unwrap_or_default();
542 history.push(Value::Object(entry));
543 m.metadata
544 .insert(MNEMO_META_STATUS_HISTORY.into(), Value::Array(history));
545 m.metadata.insert(
546 MNEMO_META_STATUS.into(),
547 Value::String(crate::memory::MESSAGE_ACKED.into()),
548 );
549 m.metadata.insert(
550 MNEMO_META_DELIVERY.into(),
551 Value::String(crate::memory::delivery::DONE.into()),
552 );
553 m.metadata
554 .insert(MNEMO_META_ACKED_AT.into(), Value::from(now));
555 self.put(m)?;
556 Ok(WriteOutcome::Updated)
557 }
558
559 pub fn prune_messages(&mut self, older_than_secs: i64) -> Result<usize> {
563 if self.read_only {
564 return Err(MnemoError::ReadOnly);
565 }
566 let now = memory::now_secs();
567 let old: Vec<Ulid> = self
568 .messages()?
569 .iter()
570 .filter_map(Message::from_memory)
571 .filter(|m| prunable(m, now, older_than_secs))
572 .map(|m| m.id)
573 .collect();
574 for id in &old {
575 self.delete(id)?;
576 }
577 Ok(old.len())
578 }
579}
580
581fn prunable(m: &Message, now: i64, keep: i64) -> bool {
583 m.status == crate::memory::MESSAGE_ACKED && m.acked_at.is_some_and(|t| now - t > keep)
584}
585
586pub(super) fn compact_drops(m: &Memory, now: i64) -> bool {
589 Message::from_memory(m)
590 .is_some_and(|msg| prunable(&msg, now, crate::memory::MESSAGE_ACKED_KEEP_SECS))
591}
592
593use crate::memory::{
596 CLAIM_LAPSE_GRACE_SECS, CLAIM_TOPIC_MAX, CLAIM_TTL_DEFAULT, CLAIM_TTL_MAX, CLAIM_TTL_MIN,
597 MNEMO_META_AGENT, MNEMO_META_CLAIM_TOKEN, MNEMO_META_DEAD_SEEN_AT, MNEMO_META_EXPIRES_AT,
598 MNEMO_META_HOLDER, MNEMO_META_HOLDER_LOCK, MNEMO_META_KIND_CLAIM, MNEMO_META_KIND_PRESENCE,
599 MNEMO_META_LAST_ACTIVE, MNEMO_META_LEASE, MNEMO_META_PRESENCE_LOCK, MNEMO_META_TOOL,
600 MNEMO_META_TOPIC, PRESENCE_EVERY_SECS,
601};
602
603fn locator_of(m: &Memory) -> Option<&str> {
605 let key = match m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str)? {
606 MNEMO_META_KIND_CLAIM => MNEMO_META_TOPIC,
607 MNEMO_META_KIND_PRESENCE => MNEMO_META_AGENT,
608 crate::memory::MNEMO_META_KIND_TASK => crate::memory::MNEMO_META_SLUG,
609 _ => return None,
610 };
611 m.metadata.get(key).and_then(Value::as_str)
612}
613
614fn locator_hash_of(kind: &str, locator: &str) -> u32 {
615 super::records::fnv1a32(&[b"_mnemo.coordination", kind.as_bytes(), locator.as_bytes()])
616}
617
618pub(super) fn locator_hash(m: &Memory) -> u32 {
622 match (
623 m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str),
624 locator_of(m),
625 ) {
626 (Some(kind), Some(l)) => locator_hash_of(kind, l),
627 _ => 0,
628 }
629}
630
631#[derive(Debug, Clone, PartialEq, Eq)]
633pub enum ClaimOutcome {
634 Claimed {
637 token: String,
639 expires_at: i64,
641 },
642 HeldBy {
644 agent: String,
646 expires_at: i64,
648 },
649}
650
651#[derive(Debug, Clone, Copy, PartialEq, Eq)]
653pub enum ClaimStatus {
654 Held {
656 expires_at: i64,
658 },
659 Released,
661 Lost,
665}
666
667#[derive(Debug, Clone, PartialEq, Eq)]
669pub struct Claim {
670 pub topic: String,
672 pub holder: String,
674 pub expires_at: i64,
676 pub lease: i64,
678}
679
680#[derive(Debug, Clone, Copy, PartialEq, Eq)]
682pub enum Alive {
683 Yes,
685 No,
687 Unknown,
690}
691
692#[derive(Debug, Clone, PartialEq, Eq)]
694pub struct Presence {
695 pub agent: String,
697 pub role: Option<String>,
699 pub tool: Option<String>,
701 pub last_active: i64,
703 pub alive: Alive,
705 pub claims: Vec<String>,
707}
708
709fn meta_i64(m: &Memory, k: &str) -> Option<i64> {
710 m.metadata.get(k).and_then(Value::as_i64)
711}
712
713fn meta_string(m: &Memory, k: &str) -> Option<String> {
714 m.metadata
715 .get(k)
716 .and_then(Value::as_str)
717 .map(str::to_string)
718}
719
720fn effective_expiry(m: &Memory, now: i64) -> Option<i64> {
723 let token = m
724 .metadata
725 .get(MNEMO_META_CLAIM_TOKEN)
726 .and_then(Value::as_str)?;
727 if token.is_empty() {
728 return None;
729 }
730 let expires = meta_i64(m, MNEMO_META_EXPIRES_AT)?;
731 let lease = meta_i64(m, MNEMO_META_LEASE).unwrap_or(CLAIM_TTL_DEFAULT);
732 Some(expires.min(now.saturating_add(lease)))
733}
734
735fn is_live(m: &Memory, now: i64) -> bool {
737 effective_expiry(m, now).is_some_and(|e| now < e)
738}
739
740fn new_token() -> String {
741 format!(
742 "{:016x}{:016x}",
743 crate::crypto::random_u64(),
744 crate::crypto::random_u64()
745 )
746}
747
748fn check_topic(topic: &str) -> Result<()> {
749 if topic.trim().is_empty() || topic.contains('\n') || topic.len() > CLAIM_TOPIC_MAX {
750 return Err(MnemoError::Invalid(format!(
751 "a claim's topic is one line, not empty, at most {CLAIM_TOPIC_MAX} bytes"
752 )));
753 }
754 Ok(())
755}
756
757fn check_ttl(ttl: Option<i64>) -> Result<i64> {
758 let t = ttl.unwrap_or(CLAIM_TTL_DEFAULT);
759 if !(CLAIM_TTL_MIN..=CLAIM_TTL_MAX).contains(&t) {
760 return Err(MnemoError::Invalid(format!(
761 "a claim's ttl is {CLAIM_TTL_MIN} s to {CLAIM_TTL_MAX} s (24 h); got {t}"
762 )));
763 }
764 Ok(t)
765}
766
767impl Mnemo {
768 pub fn coordination_now(&self) -> i64 {
771 #[cfg(feature = "dev-hooks")]
772 let env: i64 = std::env::var("MNEMO_DEV_CLOCK_OFFSET")
773 .ok()
774 .and_then(|v| v.parse().ok())
775 .unwrap_or(0);
776 #[cfg(not(feature = "dev-hooks"))]
777 let env: i64 = 0;
778 memory::now_secs() + self.clock_offset + env
779 }
780
781 #[cfg(feature = "dev-hooks")]
784 #[doc(hidden)]
785 pub fn __set_clock_offset_for_testing(&mut self, secs: i64) {
786 self.clock_offset = secs;
787 }
788
789 fn claim_agent(&self) -> Result<String> {
790 self.author.clone().ok_or_else(|| {
791 MnemoError::Invalid(
792 "a claim needs an agent: set MNEMO_AGENT (or --as), or call set_author".into(),
793 )
794 })
795 }
796
797 fn find_claim(&mut self, topic: &str) -> Result<Option<Memory>> {
798 Ok(self
799 .coordination_records(MNEMO_META_KIND_CLAIM, Some(topic))?
800 .into_iter()
801 .next())
802 }
803
804 pub fn claim(&mut self, topic: &str, ttl: Option<i64>) -> Result<ClaimOutcome> {
819 if self.read_only {
820 return Err(MnemoError::ReadOnly);
821 }
822 check_topic(topic)?;
823 let ttl = check_ttl(ttl)?;
824 let agent = self.claim_agent()?;
825 let now = self.coordination_now();
826 let existing = self.find_claim(topic)?;
827 if let Some(mut m) = existing.clone() {
828 if is_live(&m, now) {
829 let holder = meta_string(&m, MNEMO_META_HOLDER).unwrap_or_default();
830 let expires = effective_expiry(&m, now).unwrap_or(now);
831 let mut changed = false;
832 let mut lapse = false;
833 let had_lock = m
834 .metadata
835 .get(MNEMO_META_HOLDER_LOCK)
836 .and_then(Value::as_bool)
837 .unwrap_or(false);
838 if had_lock && holder != agent {
839 match crate::shared::probe_presence_once(&self.path, &holder) {
840 Some(false) => match meta_i64(&m, MNEMO_META_DEAD_SEEN_AT) {
841 Some(t) if now - t >= CLAIM_LAPSE_GRACE_SECS => lapse = true,
842 Some(_) => {}
843 None => {
844 m.metadata
845 .insert(MNEMO_META_DEAD_SEEN_AT.into(), Value::from(now));
846 changed = true;
847 }
848 },
849 _ => {
850 changed |= m.metadata.remove(MNEMO_META_DEAD_SEEN_AT).is_some();
851 }
852 }
853 }
854 if !lapse {
855 if meta_i64(&m, MNEMO_META_EXPIRES_AT) != Some(expires) {
858 m.metadata
859 .insert(MNEMO_META_EXPIRES_AT.into(), Value::from(expires));
860 changed = true;
861 }
862 if changed {
863 self.put(m)?;
864 }
865 return Ok(ClaimOutcome::HeldBy {
866 agent: holder,
867 expires_at: expires,
868 });
869 }
870 }
871 }
872 let token = new_token();
873 let expires_at = now + ttl;
874 let mut meta = existing
875 .as_ref()
876 .map(|m| m.metadata.clone())
877 .unwrap_or_default();
878 meta.remove(MNEMO_META_DEAD_SEEN_AT);
879 meta.insert(MNEMO_META_TOPIC.into(), Value::String(topic.to_string()));
880 meta.insert(MNEMO_META_HOLDER.into(), Value::String(agent));
881 meta.insert(MNEMO_META_CLAIM_TOKEN.into(), Value::String(token.clone()));
882 meta.insert(MNEMO_META_EXPIRES_AT.into(), Value::from(expires_at));
883 meta.insert(MNEMO_META_LEASE.into(), Value::from(ttl));
884 meta.insert(
885 MNEMO_META_HOLDER_LOCK.into(),
886 Value::Bool(self.presence_held),
887 );
888 match existing {
889 Some(mut m) => {
890 m.metadata = meta;
891 self.put(m)?;
892 }
893 None => {
894 self.put_coordination_with_id(
895 Ulid::new(),
896 MNEMO_META_KIND_CLAIM,
897 format!("claim {topic}"),
898 meta,
899 )?;
900 }
901 }
902 Ok(ClaimOutcome::Claimed { token, expires_at })
903 }
904
905 pub fn renew(&mut self, topic: &str, token: &str, ttl: Option<i64>) -> Result<ClaimStatus> {
908 if self.read_only {
909 return Err(MnemoError::ReadOnly);
910 }
911 let now = self.coordination_now();
912 let Some(mut m) = self.find_claim(topic)? else {
913 return Ok(ClaimStatus::Lost);
914 };
915 if !is_live(&m, now) || meta_string(&m, MNEMO_META_CLAIM_TOKEN).as_deref() != Some(token) {
916 return Ok(ClaimStatus::Lost);
917 }
918 let lease = match ttl {
919 Some(t) => check_ttl(Some(t))?,
920 None => meta_i64(&m, MNEMO_META_LEASE).unwrap_or(CLAIM_TTL_DEFAULT),
921 };
922 let expires_at = now + lease;
923 m.metadata
924 .insert(MNEMO_META_EXPIRES_AT.into(), Value::from(expires_at));
925 m.metadata
926 .insert(MNEMO_META_LEASE.into(), Value::from(lease));
927 m.metadata.remove(MNEMO_META_DEAD_SEEN_AT);
928 self.put(m)?;
929 Ok(ClaimStatus::Held { expires_at })
930 }
931
932 pub fn release(&mut self, topic: &str, token: &str) -> Result<ClaimStatus> {
935 if self.read_only {
936 return Err(MnemoError::ReadOnly);
937 }
938 let now = self.coordination_now();
939 let Some(mut m) = self.find_claim(topic)? else {
940 return Ok(ClaimStatus::Lost);
941 };
942 if !is_live(&m, now) || meta_string(&m, MNEMO_META_CLAIM_TOKEN).as_deref() != Some(token) {
943 return Ok(ClaimStatus::Lost);
944 }
945 m.metadata.remove(MNEMO_META_CLAIM_TOKEN);
946 m.metadata.remove(MNEMO_META_DEAD_SEEN_AT);
947 m.metadata
948 .insert(MNEMO_META_EXPIRES_AT.into(), Value::from(now));
949 self.put(m)?;
950 Ok(ClaimStatus::Released)
951 }
952
953 pub fn check_claim(&mut self, topic: &str, token: &str) -> Result<ClaimStatus> {
956 let now = self.coordination_now();
957 let Some(m) = self.find_claim(topic)? else {
958 return Ok(ClaimStatus::Lost);
959 };
960 if meta_string(&m, MNEMO_META_CLAIM_TOKEN).as_deref() != Some(token) {
961 return Ok(ClaimStatus::Lost);
962 }
963 match effective_expiry(&m, now) {
964 Some(e) if now < e => Ok(ClaimStatus::Held { expires_at: e }),
965 _ => Ok(ClaimStatus::Lost),
966 }
967 }
968
969 pub fn claims(&mut self) -> Result<Vec<Claim>> {
971 let now = self.coordination_now();
972 let mut out: Vec<Claim> = self
973 .coordination_records(MNEMO_META_KIND_CLAIM, None)?
974 .iter()
975 .filter(|m| is_live(m, now))
976 .map(|m| Claim {
977 topic: meta_string(m, MNEMO_META_TOPIC).unwrap_or_default(),
978 holder: meta_string(m, MNEMO_META_HOLDER).unwrap_or_default(),
979 expires_at: effective_expiry(m, now).unwrap_or(now),
980 lease: meta_i64(m, MNEMO_META_LEASE).unwrap_or(CLAIM_TTL_DEFAULT),
981 })
982 .collect();
983 out.sort_by(|a, b| a.topic.cmp(&b.topic));
984 Ok(out)
985 }
986
987 pub fn touch_presence(&mut self, role: Option<&str>, tool: Option<&str>) -> Result<bool> {
994 if self.read_only {
995 return Err(MnemoError::ReadOnly);
996 }
997 let Some(agent) = self.author.clone() else {
998 return Ok(false);
999 };
1000 let now = self.coordination_now();
1001 let existing = self
1002 .coordination_records(MNEMO_META_KIND_PRESENCE, Some(&agent))?
1003 .into_iter()
1004 .next();
1005 let role_v = role.map(|r| Value::String(r.to_string()));
1006 let tool_v = tool.map(|t| Value::String(t.to_string()));
1007 let defer = !self.presence_held
1011 && existing.as_ref().is_some_and(|m| {
1012 m.metadata
1013 .get(MNEMO_META_PRESENCE_LOCK)
1014 .and_then(Value::as_bool)
1015 .unwrap_or(false)
1016 });
1017 if let Some(m) = &existing {
1018 let fresh = meta_i64(m, MNEMO_META_LAST_ACTIVE)
1019 .is_some_and(|t| now >= t && now - t < PRESENCE_EVERY_SECS);
1020 let same = defer
1021 || (m.metadata.get(crate::memory::MNEMO_META_ROLE) == role_v.as_ref()
1022 && m.metadata.get(MNEMO_META_TOOL) == tool_v.as_ref()
1023 && m.metadata
1024 .get(MNEMO_META_PRESENCE_LOCK)
1025 .and_then(Value::as_bool)
1026 == Some(self.presence_held));
1027 if fresh && same {
1028 return Ok(false);
1029 }
1030 }
1031 if defer {
1032 let mut m = existing.expect("checked");
1033 m.metadata
1034 .insert(MNEMO_META_LAST_ACTIVE.into(), Value::from(now));
1035 self.put(m)?;
1036 return Ok(true);
1037 }
1038 let mut meta = existing
1039 .as_ref()
1040 .map(|m| m.metadata.clone())
1041 .unwrap_or_default();
1042 meta.insert(MNEMO_META_AGENT.into(), Value::String(agent.clone()));
1043 for (k, v) in [
1044 (crate::memory::MNEMO_META_ROLE, role_v),
1045 (MNEMO_META_TOOL, tool_v),
1046 ] {
1047 match v {
1048 Some(v) => {
1049 meta.insert(k.into(), v);
1050 }
1051 None => {
1052 meta.remove(k);
1053 }
1054 }
1055 }
1056 meta.insert(MNEMO_META_LAST_ACTIVE.into(), Value::from(now));
1057 meta.insert(
1058 MNEMO_META_PRESENCE_LOCK.into(),
1059 Value::Bool(self.presence_held),
1060 );
1061 match existing {
1062 Some(mut m) => {
1063 m.metadata = meta;
1064 self.put(m)?;
1065 }
1066 None => {
1067 self.put_coordination_with_id(
1068 Ulid::new(),
1069 MNEMO_META_KIND_PRESENCE,
1070 format!("presence {agent}"),
1071 meta,
1072 )?;
1073 }
1074 }
1075 Ok(true)
1076 }
1077
1078 pub fn who(&mut self) -> Result<Vec<Presence>> {
1083 let claims = self.claims()?;
1084 let records = self.coordination_records(MNEMO_META_KIND_PRESENCE, None)?;
1085 let mut out: Vec<Presence> = records
1086 .iter()
1087 .map(|m| {
1088 let agent = meta_string(m, MNEMO_META_AGENT).unwrap_or_default();
1089 let locked = m
1090 .metadata
1091 .get(MNEMO_META_PRESENCE_LOCK)
1092 .and_then(Value::as_bool)
1093 .unwrap_or(false);
1094 let alive = if !locked {
1095 Alive::Unknown
1096 } else {
1097 match crate::shared::probe_presence(&self.path, &agent) {
1098 Some(true) => Alive::Yes,
1099 Some(false) => Alive::No,
1100 None => Alive::Unknown,
1101 }
1102 };
1103 Presence {
1104 claims: claims
1105 .iter()
1106 .filter(|c| c.holder == agent)
1107 .map(|c| c.topic.clone())
1108 .collect(),
1109 role: meta_string(m, crate::memory::MNEMO_META_ROLE),
1110 tool: meta_string(m, MNEMO_META_TOOL),
1111 last_active: meta_i64(m, MNEMO_META_LAST_ACTIVE).unwrap_or(0),
1112 alive,
1113 agent,
1114 }
1115 })
1116 .collect();
1117 out.sort_by(|a, b| {
1118 b.last_active
1119 .cmp(&a.last_active)
1120 .then(a.agent.cmp(&b.agent))
1121 });
1122 Ok(out)
1123 }
1124}
1125
1126use crate::memory::{
1129 task_status, MNEMO_META_AFTER, MNEMO_META_CREATOR, MNEMO_META_KIND_TASK, MNEMO_META_OWNER,
1130 MNEMO_META_PRE_APPROVED, MNEMO_META_SLUG, TASK_CLAIM_TTL, TASK_SLUG_MAX, TASK_TRANSITIONS,
1131};
1132
1133#[derive(Debug, Clone, Default, PartialEq, Eq)]
1135pub struct TaskSpec {
1136 pub title: String,
1138 pub body: String,
1140 pub role: Option<String>,
1142 pub after: Vec<String>,
1144 pub pre_approved: bool,
1146 pub slug: Option<String>,
1148}
1149
1150#[derive(Debug, Clone, PartialEq)]
1152pub struct Task {
1153 pub id: Ulid,
1155 pub slug: String,
1157 pub title: String,
1159 pub body: String,
1161 pub role: Option<String>,
1163 pub status: String,
1165 pub owner: Option<String>,
1167 pub creator: String,
1169 pub after: Vec<String>,
1171 pub pre_approved: bool,
1173 pub created_at: i64,
1175 pub history: Vec<Value>,
1178}
1179
1180impl Task {
1181 pub fn from_memory(m: &Memory) -> Option<Task> {
1183 if m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str) != Some(MNEMO_META_KIND_TASK) {
1184 return None;
1185 }
1186 let (title, body) = match m.content.split_once("\n\n") {
1187 Some((a, b)) => (a.to_string(), b.to_string()),
1188 None => (m.content.clone(), String::new()),
1189 };
1190 Some(Task {
1191 id: m.id,
1192 slug: meta_string(m, MNEMO_META_SLUG).unwrap_or_default(),
1193 title,
1194 body,
1195 role: meta_string(m, crate::memory::MNEMO_META_ROLE),
1196 status: meta_string(m, MNEMO_META_STATUS).unwrap_or_default(),
1197 owner: meta_string(m, MNEMO_META_OWNER),
1198 creator: meta_string(m, MNEMO_META_CREATOR).unwrap_or_default(),
1199 after: m
1200 .metadata
1201 .get(MNEMO_META_AFTER)
1202 .and_then(Value::as_array)
1203 .map(|a| {
1204 a.iter()
1205 .filter_map(|v| v.as_str().map(str::to_string))
1206 .collect()
1207 })
1208 .unwrap_or_default(),
1209 pre_approved: m
1210 .metadata
1211 .get(MNEMO_META_PRE_APPROVED)
1212 .and_then(Value::as_bool)
1213 .unwrap_or(false),
1214 created_at: m.created_at,
1215 history: m
1216 .metadata
1217 .get(MNEMO_META_STATUS_HISTORY)
1218 .and_then(Value::as_array)
1219 .cloned()
1220 .unwrap_or_default(),
1221 })
1222 }
1223
1224 fn for_role(&self, role: Option<&str>) -> bool {
1227 self.role.is_none() || self.role.as_deref() == role
1228 }
1229}
1230
1231#[derive(Debug, Clone, PartialEq)]
1233pub struct TaskTaken {
1234 pub task: Task,
1236 pub token: String,
1239 pub expires_at: i64,
1241 pub reclaimed_from: Option<String>,
1243}
1244
1245#[derive(Debug, Clone, PartialEq, Eq)]
1248pub struct TaskClaim {
1249 pub token: String,
1251 pub expires_at: i64,
1253 pub retaken: bool,
1256}
1257
1258#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1260pub enum TaskLost {
1261 TakenBack,
1263 OtherToken,
1266}
1267
1268#[derive(Debug, Clone, PartialEq)]
1270pub enum TaskOutcome {
1271 Updated(Box<Task>, Option<TaskClaim>),
1275 Lost(TaskLost),
1277}
1278
1279pub fn slug_of(title: &str) -> String {
1282 let mut out = String::new();
1283 for c in title.chars() {
1284 if c.is_ascii_alphanumeric() {
1285 out.push(c.to_ascii_lowercase());
1286 } else if !out.ends_with('-') && !out.is_empty() {
1287 out.push('-');
1288 }
1289 if out.len() >= TASK_SLUG_MAX {
1290 break;
1291 }
1292 }
1293 out.trim_end_matches('-').to_string()
1294}
1295
1296fn valid_slug(s: &str) -> bool {
1297 !s.is_empty()
1298 && s.len() <= TASK_SLUG_MAX
1299 && s.bytes()
1300 .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b"._-".contains(&b))
1301}
1302
1303fn task_topic(slug: &str) -> String {
1304 format!("task:{slug}")
1305}
1306
1307impl Mnemo {
1308 fn task_records(&mut self, slug: Option<&str>) -> Result<Vec<Memory>> {
1309 let mut v = self.coordination_records(MNEMO_META_KIND_TASK, slug)?;
1310 v.sort_by_key(|m| m.created_at);
1311 Ok(v)
1312 }
1313
1314 fn task_record(&mut self, slug: &str) -> Result<Option<Memory>> {
1315 Ok(self.task_records(Some(slug))?.into_iter().next())
1316 }
1317
1318 pub fn task(&mut self, slug: &str) -> Result<Option<Task>> {
1320 Ok(self.task_record(slug)?.as_ref().and_then(Task::from_memory))
1321 }
1322
1323 pub fn tasks(&mut self, status: Option<&str>, role: Option<&str>) -> Result<Vec<Task>> {
1326 Ok(self
1327 .task_records(None)?
1328 .iter()
1329 .filter_map(Task::from_memory)
1330 .filter(|t| status.is_none_or(|s| t.status == s))
1331 .filter(|t| role.is_none() || t.for_role(role))
1332 .collect())
1333 }
1334
1335 pub fn ready_tasks(&mut self, role: Option<&str>) -> Result<Vec<Task>> {
1338 let all: Vec<Task> = self
1339 .task_records(None)?
1340 .iter()
1341 .filter_map(Task::from_memory)
1342 .collect();
1343 let done: std::collections::HashSet<&str> = all
1344 .iter()
1345 .filter(|t| t.status == task_status::DONE)
1346 .map(|t| t.slug.as_str())
1347 .collect();
1348 Ok(all
1349 .iter()
1350 .filter(|t| t.status == task_status::QUEUED && t.for_role(role))
1351 .filter(|t| t.after.iter().all(|a| done.contains(a.as_str())))
1352 .cloned()
1353 .collect())
1354 }
1355
1356 pub fn task_add(&mut self, spec: &TaskSpec) -> Result<(Task, WriteOutcome)> {
1362 if self.read_only {
1363 return Err(MnemoError::ReadOnly);
1364 }
1365 let title = spec.title.trim();
1366 if title.is_empty()
1367 || title.contains('\n')
1368 || title.len() > crate::memory::MESSAGE_SUBJECT_MAX
1369 {
1370 return Err(MnemoError::Invalid(format!(
1371 "a task's title is one line, not empty, at most {} bytes",
1372 crate::memory::MESSAGE_SUBJECT_MAX
1373 )));
1374 }
1375 if spec.body.len() > crate::memory::MESSAGE_BODY_MAX {
1376 return Err(MnemoError::Invalid(format!(
1377 "a task's body is at most {} bytes; put more in a fact and name it",
1378 crate::memory::MESSAGE_BODY_MAX
1379 )));
1380 }
1381 let slug = match &spec.slug {
1382 Some(s) => s.clone(),
1383 None => slug_of(title),
1384 };
1385 if !valid_slug(&slug) {
1386 return Err(MnemoError::Invalid(format!(
1387 "{slug:?} isn't a slug: 1 to {TASK_SLUG_MAX} of a-z, 0-9, '.', '_' and '-' \
1388 (give one with --slug)"
1389 )));
1390 }
1391 if let Some(r) = &spec.role {
1392 if !crate::memory::valid_agent_id(r) {
1393 return Err(MnemoError::Invalid(format!("{r:?} isn't a role")));
1394 }
1395 }
1396 for a in &spec.after {
1397 if a == &slug {
1398 return Err(MnemoError::Invalid("a task can't wait for itself".into()));
1399 }
1400 if self.task_record(a)?.is_none() {
1401 return Err(MnemoError::Invalid(format!("after: no task {a:?}")));
1402 }
1403 }
1404 let content = if spec.body.is_empty() {
1405 title.to_string()
1406 } else {
1407 format!("{title}\n\n{}", spec.body)
1408 };
1409 let set = |meta: &mut Map<String, Value>| {
1410 match &spec.role {
1411 Some(r) => {
1412 meta.insert(
1413 crate::memory::MNEMO_META_ROLE.into(),
1414 Value::String(r.clone()),
1415 );
1416 }
1417 None => {
1418 meta.remove(crate::memory::MNEMO_META_ROLE);
1419 }
1420 }
1421 meta.insert(
1422 MNEMO_META_AFTER.into(),
1423 Value::Array(
1424 spec.after
1425 .iter()
1426 .map(|a| Value::String(a.clone()))
1427 .collect(),
1428 ),
1429 );
1430 meta.insert(
1431 MNEMO_META_PRE_APPROVED.into(),
1432 Value::Bool(spec.pre_approved),
1433 );
1434 };
1435 if let Some(mut m) = self.task_record(&slug)? {
1436 let t = Task::from_memory(&m).expect("a task");
1437 let mut meta = m.metadata.clone();
1438 set(&mut meta);
1439 if meta == m.metadata && m.content == content {
1440 return Ok((t, WriteOutcome::Unchanged));
1441 }
1442 if t.status == task_status::DONE {
1445 let mut n = 2;
1446 while self.task_record(&format!("{slug}-{n}"))?.is_some() {
1447 n += 1;
1448 }
1449 return Err(MnemoError::Invalid(format!(
1450 "{slug} is done; give a new slug ({slug}-{n}?)"
1451 )));
1452 }
1453 let caller = self.author.clone().unwrap_or_else(|| "anonymous".into());
1454 if caller != t.creator {
1455 return Err(MnemoError::Invalid(format!(
1456 "that slug is {}'s task; it wasn't changed",
1457 t.creator
1458 )));
1459 }
1460 if self.closes_cycle(&slug, &spec.after)? {
1462 return Err(MnemoError::Invalid(format!(
1463 "after: that would make {slug} wait for itself, through the tasks it waits for"
1464 )));
1465 }
1466 m.metadata = meta;
1467 m.content = content;
1468 let id = m.id;
1469 self.put(m)?;
1470 let t = Task::from_memory(&self.get(&id)?).expect("a task");
1471 return Ok((t, WriteOutcome::Updated));
1472 }
1473 let mut meta = Map::new();
1474 meta.insert(MNEMO_META_SLUG.into(), Value::String(slug));
1475 meta.insert(
1476 MNEMO_META_STATUS.into(),
1477 Value::String(task_status::QUEUED.into()),
1478 );
1479 meta.insert(
1480 MNEMO_META_CREATOR.into(),
1481 Value::String(self.author.clone().unwrap_or_else(|| "anonymous".into())),
1482 );
1483 meta.insert(
1484 MNEMO_META_DELIVERY.into(),
1485 Value::String(crate::memory::delivery::SENT.into()),
1486 );
1487 set(&mut meta);
1488 let id = self.put_coordination_with_id(Ulid::new(), MNEMO_META_KIND_TASK, content, meta)?;
1489 let t = Task::from_memory(&self.get(&id)?).expect("a task");
1490 Ok((t, WriteOutcome::Added))
1491 }
1492
1493 fn closes_cycle(&mut self, slug: &str, after: &[String]) -> Result<bool> {
1496 let all: std::collections::HashMap<String, Vec<String>> = self
1497 .task_records(None)?
1498 .iter()
1499 .filter_map(Task::from_memory)
1500 .map(|t| (t.slug, t.after))
1501 .collect();
1502 let mut stack: Vec<&str> = after.iter().map(String::as_str).collect();
1503 let mut seen = std::collections::HashSet::new();
1504 while let Some(s) = stack.pop() {
1505 if s == slug {
1506 return Ok(true);
1507 }
1508 if seen.insert(s.to_string()) {
1509 if let Some(next) = all.get(s) {
1510 stack.extend(next.iter().map(String::as_str));
1511 }
1512 }
1513 }
1514 Ok(false)
1515 }
1516
1517 fn task_history(
1519 m: &mut Memory,
1520 from: &str,
1521 to: &str,
1522 by: &str,
1523 at: i64,
1524 extra: &[(&str, &str)],
1525 ) {
1526 let mut e = Map::new();
1527 e.insert("from".into(), Value::String(from.into()));
1528 e.insert("to".into(), Value::String(to.into()));
1529 e.insert("at".into(), Value::from(at));
1530 e.insert("by".into(), Value::String(by.into()));
1531 for (k, v) in extra {
1532 e.insert((*k).into(), Value::String((*v).into()));
1533 }
1534 let mut h = m
1535 .metadata
1536 .get(MNEMO_META_STATUS_HISTORY)
1537 .and_then(Value::as_array)
1538 .cloned()
1539 .unwrap_or_default();
1540 h.push(Value::Object(e));
1541 m.metadata
1542 .insert(MNEMO_META_STATUS_HISTORY.into(), Value::Array(h));
1543 }
1544
1545 pub fn task_next(&mut self, role: Option<&str>) -> Result<Option<TaskTaken>> {
1553 if self.read_only {
1554 return Err(MnemoError::ReadOnly);
1555 }
1556 let agent = self.claim_agent()?;
1557 let now = self.coordination_now();
1558 let ready: Vec<Ulid> = self.ready_tasks(role)?.iter().map(|t| t.id).collect();
1559 let taken: Vec<Task> = self
1564 .task_records(None)?
1565 .iter()
1566 .filter_map(Task::from_memory)
1567 .filter(|t| t.status == task_status::ACTIVE || t.status == task_status::BLOCKED)
1568 .filter(|t| t.for_role(role))
1569 .collect();
1570 let (own, others): (Vec<&Task>, Vec<&Task>) = taken
1571 .iter()
1572 .partition(|t| t.owner.as_deref() == Some(agent.as_str()));
1573 for (id, back) in own
1574 .iter()
1575 .map(|t| (t.id, true))
1576 .chain(ready.into_iter().map(|i| (i, false)))
1577 .chain(others.iter().map(|t| (t.id, true)))
1578 {
1579 let mut m = self.get(&id)?;
1580 let t = Task::from_memory(&m).expect("a task");
1581 let (token, expires_at) =
1582 match self.claim(&task_topic(&t.slug), Some(TASK_CLAIM_TTL))? {
1583 ClaimOutcome::Claimed { token, expires_at } => (token, expires_at),
1584 ClaimOutcome::HeldBy { .. } => continue,
1585 };
1586 m = self.get(&id)?;
1589 let old = t.owner.clone();
1590 let own = old.as_deref() == Some(agent.as_str());
1591 if back && own {
1592 Self::task_history(
1593 &mut m,
1594 &t.status,
1595 task_status::ACTIVE,
1596 &agent,
1597 now,
1598 &[("note", "taken again after its claim lapsed")],
1599 );
1600 } else if back {
1601 let from = old.clone().unwrap_or_default();
1602 Self::task_history(
1603 &mut m,
1604 &t.status,
1605 task_status::ACTIVE,
1606 &agent,
1607 now,
1608 &[("reclaimed_from", from.as_str())],
1609 );
1610 } else {
1611 Self::task_history(
1612 &mut m,
1613 task_status::QUEUED,
1614 task_status::ACTIVE,
1615 &agent,
1616 now,
1617 &[],
1618 );
1619 }
1620 m.metadata.insert(
1621 MNEMO_META_STATUS.into(),
1622 Value::String(task_status::ACTIVE.into()),
1623 );
1624 m.metadata
1625 .insert(MNEMO_META_OWNER.into(), Value::String(agent.clone()));
1626 self.put(m)?;
1627 let task = Task::from_memory(&self.get(&id)?).expect("a task");
1628 return Ok(Some(TaskTaken {
1629 task,
1630 token,
1631 expires_at,
1632 reclaimed_from: if back && !own { old } else { None },
1633 }));
1634 }
1635 Ok(None)
1636 }
1637
1638 pub fn task_update(
1653 &mut self,
1654 slug: &str,
1655 status: Option<&str>,
1656 note: Option<&str>,
1657 token: Option<&str>,
1658 ) -> Result<TaskOutcome> {
1659 if self.read_only {
1660 return Err(MnemoError::ReadOnly);
1661 }
1662 let agent = self.claim_agent()?;
1663 let now = self.coordination_now();
1664 let Some(m) = self.task_record(slug)? else {
1665 return Err(MnemoError::Invalid(format!("no task {slug:?}")));
1666 };
1667 let t = Task::from_memory(&m).expect("a task");
1668 let to = status.unwrap_or(&t.status).to_string();
1669 if status.is_none() && note.is_none() {
1670 return Err(MnemoError::Invalid("give a status or a note".into()));
1671 }
1672 if token.is_some() && t.owner.as_deref() != Some(agent.as_str()) {
1675 return Ok(TaskOutcome::Lost(TaskLost::TakenBack));
1676 }
1677 let changing = to != t.status;
1678 if changing && !TASK_TRANSITIONS.contains(&(t.status.as_str(), to.as_str())) {
1679 return Err(MnemoError::Invalid(format!(
1680 "a task can't go from {} to {to}",
1681 t.status
1682 )));
1683 }
1684 if changing && t.status == task_status::QUEUED {
1685 return Err(MnemoError::Invalid(
1686 "a queued task is taken with `task next`".into(),
1687 ));
1688 }
1689 let topic = task_topic(slug);
1690 let claim = self.find_claim(&topic)?;
1691 let live = claim.as_ref().filter(|c| is_live(c, now));
1692 let claim_token = claim
1693 .as_ref()
1694 .and_then(|c| meta_string(c, MNEMO_META_CLAIM_TOKEN));
1695 let held_by_owner = live.is_some_and(|c| meta_string(c, MNEMO_META_HOLDER) == t.owner);
1696 let is_owner = t.owner.as_deref() == Some(agent.as_str());
1697 let is_creator = t.creator == agent;
1698 let by_owner = if changing && t.status == task_status::READY {
1700 if !(is_creator || (is_owner && t.pre_approved)) {
1702 return Err(MnemoError::Invalid(format!(
1703 "{slug} waits for its creator ({}) to set done",
1704 t.creator
1705 )));
1706 }
1707 false
1708 } else if changing && to == task_status::QUEUED && !is_owner {
1709 if let Some(c) = live {
1711 return Err(MnemoError::Invalid(format!(
1712 "{slug} is {}'s, and its claim is live until {}; only its owner can hand \
1713 it back before then",
1714 t.owner.as_deref().unwrap_or("its owner"),
1715 crate::memory::date_time_of(effective_expiry(c, now).unwrap_or(now))
1716 )));
1717 }
1718 false
1719 } else if t.status == task_status::DONE || (!changing && t.status == task_status::READY) {
1720 if !(is_creator || is_owner) {
1722 return Err(MnemoError::Invalid(format!("{slug} isn't yours")));
1723 }
1724 false
1725 } else if !changing && is_creator && !is_owner {
1726 false } else if t.status == task_status::QUEUED {
1728 if !is_creator {
1730 return Err(MnemoError::Invalid(format!("{slug} isn't yours")));
1731 }
1732 false
1733 } else {
1734 if !is_owner {
1735 return Ok(TaskOutcome::Lost(TaskLost::TakenBack));
1736 }
1737 true
1738 };
1739 let mut renew_token = None;
1746 if by_owner {
1747 let token_ok = token.is_none_or(|tk| claim_token.as_deref() == Some(tk));
1748 if live.is_some() && !held_by_owner {
1749 return Ok(TaskOutcome::Lost(TaskLost::TakenBack));
1750 }
1751 if !token_ok {
1752 return Ok(TaskOutcome::Lost(TaskLost::OtherToken));
1753 }
1754 if held_by_owner {
1755 renew_token = claim_token.clone();
1756 }
1757 }
1758 let mut m = m;
1759 let mut extra: Vec<(&str, &str)> = Vec::new();
1760 if let Some(n) = note {
1761 extra.push(("note", n));
1762 }
1763 Self::task_history(&mut m, &t.status, &to, &agent, now, &extra);
1764 m.metadata
1765 .insert(MNEMO_META_STATUS.into(), Value::String(to.clone()));
1766 if to == task_status::QUEUED {
1767 m.metadata.remove(MNEMO_META_OWNER);
1768 }
1769 let id = m.id;
1770 self.put(m)?;
1771 let releases =
1772 [task_status::READY, task_status::DONE, task_status::QUEUED].contains(&to.as_str());
1773 let mut held: Option<TaskClaim> = None;
1774 match (releases, by_owner, renew_token) {
1775 (true, _, Some(tk)) => {
1776 self.release(&topic, &tk)?;
1777 }
1778 (true, _, None) => {
1779 if let Some(mut c) = self.find_claim(&topic)? {
1781 if is_live(&c, now)
1782 && meta_string(&c, MNEMO_META_HOLDER) == t.owner
1783 && to == task_status::DONE
1784 {
1785 c.metadata.remove(MNEMO_META_CLAIM_TOKEN);
1786 c.metadata
1787 .insert(MNEMO_META_EXPIRES_AT.into(), Value::from(now));
1788 self.put(c)?;
1789 }
1790 }
1791 }
1792 (false, true, Some(tk)) => {
1793 if let ClaimStatus::Held { expires_at } =
1794 self.renew(&topic, &tk, Some(TASK_CLAIM_TTL))?
1795 {
1796 held = Some(TaskClaim {
1797 token: tk,
1798 expires_at,
1799 retaken: false,
1800 });
1801 }
1802 }
1803 (false, true, None) => {
1804 if let ClaimOutcome::Claimed { token, expires_at } =
1807 self.claim(&topic, Some(TASK_CLAIM_TTL))?
1808 {
1809 held = Some(TaskClaim {
1810 token,
1811 expires_at,
1812 retaken: true,
1813 });
1814 }
1815 }
1816 (false, false, _) => {}
1817 }
1818 Ok(TaskOutcome::Updated(
1819 Box::new(Task::from_memory(&self.get(&id)?).expect("a task")),
1820 held,
1821 ))
1822 }
1823}
1824
1825use crate::memory::{
1828 HOP_CAP, MNEMO_META_WAKES, MNEMO_META_WAKE_PAUSED, MNEMO_META_WARNED_EXPIRY, PAIR_BURST,
1829 PAIR_BURST_SECS, TASK_CLAIM_WARN_SECS, WAKE_COOLDOWN_SECS, WAKE_PER_HOUR,
1830};
1831
1832#[derive(Debug, Clone, Default, PartialEq)]
1835pub struct NewWork {
1836 pub messages: Vec<Message>,
1838 pub tasks: Vec<Task>,
1840 pub lapsing: Vec<Claim>,
1844 pub ready_for_done: Vec<Task>,
1848 pub agent: Option<String>,
1851}
1852
1853impl NewWork {
1854 pub fn is_empty(&self) -> bool {
1856 self.messages.is_empty()
1857 && self.tasks.is_empty()
1858 && self.lapsing.is_empty()
1859 && self.ready_for_done.is_empty()
1860 }
1861}
1862
1863#[derive(Debug, Clone, PartialEq, Eq)]
1865pub enum Wake {
1866 Now {
1869 tasks: usize,
1871 messages: usize,
1873 },
1874 Nothing,
1876 Held(&'static str),
1879}
1880
1881impl Mnemo {
1882 pub fn new_work(&mut self, agent: Option<&str>, role: Option<&str>) -> Result<NewWork> {
1885 let now = self.coordination_now();
1886 let unseen =
1887 |d: &str| d == crate::memory::delivery::SENT || d == crate::memory::delivery::DELIVERED;
1888 let mut messages = Vec::new();
1892 for msg in self.inbox(agent, role, true)? {
1893 let broadcast = msg.to == "all" || msg.to.starts_with("role:");
1894 let new = match (broadcast, agent) {
1895 (true, Some(a)) => !seen_by(&self.get(&msg.id)?).iter().any(|s| s == a),
1896 _ => unseen(&msg.delivery),
1897 };
1898 if new {
1899 messages.push(msg);
1900 }
1901 }
1902 let mut tasks = Vec::new();
1903 for t in self.ready_tasks(role)? {
1904 let m = self.get(&t.id)?;
1905 let new = match agent {
1906 Some(a) => !seen_by(&m).iter().any(|s| s == a),
1907 None => meta_string(&m, MNEMO_META_DELIVERY).is_none_or(|d| unseen(&d)),
1908 };
1909 if new {
1910 tasks.push(t);
1911 }
1912 }
1913 let mut ready_for_done = Vec::new();
1916 if let Some(a) = agent {
1917 for t in self.tasks(Some(crate::memory::task_status::READY), None)? {
1918 if t.creator == a && !ready_seen_by(&self.get(&t.id)?).iter().any(|s| s == a) {
1919 ready_for_done.push(t);
1920 }
1921 }
1922 }
1923 let mut lapsing = Vec::new();
1924 if let Some(a) = agent {
1925 for m in self.coordination_records(MNEMO_META_KIND_CLAIM, None)? {
1926 let topic = meta_string(&m, MNEMO_META_TOPIC).unwrap_or_default();
1927 if !topic.starts_with("task:")
1928 || meta_string(&m, MNEMO_META_HOLDER).as_deref() != Some(a)
1929 || !is_live(&m, now)
1930 {
1931 continue;
1932 }
1933 let e = effective_expiry(&m, now).unwrap_or(now);
1934 if e - now <= TASK_CLAIM_WARN_SECS
1935 && meta_i64(&m, MNEMO_META_WARNED_EXPIRY) != Some(e)
1936 {
1937 lapsing.push(Claim {
1938 topic,
1939 holder: a.to_string(),
1940 expires_at: e,
1941 lease: meta_i64(&m, MNEMO_META_LEASE).unwrap_or(CLAIM_TTL_DEFAULT),
1942 });
1943 }
1944 }
1945 }
1946 Ok(NewWork {
1947 messages,
1948 tasks,
1949 lapsing,
1950 ready_for_done,
1951 agent: agent.map(str::to_string),
1952 })
1953 }
1954
1955 pub fn mark_shown(&mut self, work: &NewWork) -> Result<()> {
1960 if self.read_only {
1961 return Err(MnemoError::ReadOnly);
1962 }
1963 let ids: Vec<Ulid> = work.messages.iter().map(|m| m.id).collect();
1964 let who = work.agent.clone().or_else(|| self.author.clone());
1966 let author = std::mem::replace(&mut self.author, who.clone());
1967 let r = self.mark_seen(&ids);
1968 self.author = author;
1969 r?;
1970 for t in &work.tasks {
1971 let mut m = self.get(&t.id)?;
1972 match who.clone() {
1973 Some(a) => {
1975 if add_seen_by(&mut m, &a) {
1976 self.put(m)?;
1977 }
1978 }
1979 None => {
1980 m.metadata.insert(
1981 MNEMO_META_DELIVERY.into(),
1982 Value::String(crate::memory::delivery::SEEN.into()),
1983 );
1984 self.put(m)?;
1985 }
1986 }
1987 }
1988 if let Some(a) = &who {
1990 for t in &work.ready_for_done {
1991 let mut m = self.get(&t.id)?;
1992 let mut v = ready_seen_by(&m);
1993 if v.iter().any(|s| s == a) {
1994 continue;
1995 }
1996 v.push(a.clone());
1997 m.metadata.insert(
1998 crate::memory::MNEMO_META_READY_SEEN_BY.into(),
1999 Value::Array(v.into_iter().map(Value::String).collect()),
2000 );
2001 self.put(m)?;
2002 }
2003 }
2004 for c in &work.lapsing {
2005 if let Some(mut m) = self.find_claim(&c.topic)? {
2006 m.metadata
2007 .insert(MNEMO_META_WARNED_EXPIRY.into(), Value::from(c.expires_at));
2008 self.put(m)?;
2009 }
2010 }
2011 Ok(())
2012 }
2013
2014 pub fn wake_paused(&mut self) -> Result<Option<(String, i64)>> {
2017 let Some(m) = self
2018 .about_in(crate::memory::VisibilitySet::ALL)?
2019 .into_iter()
2020 .find(is_manifest)
2021 else {
2022 return Ok(None);
2023 };
2024 Ok(m.metadata.get(MNEMO_META_WAKE_PAUSED).map(|v| {
2025 (
2026 v.get("by")
2027 .and_then(Value::as_str)
2028 .unwrap_or("")
2029 .to_string(),
2030 v.get("at").and_then(Value::as_i64).unwrap_or(0),
2031 )
2032 }))
2033 }
2034
2035 pub fn set_wake_paused(&mut self, paused: bool) -> Result<WriteOutcome> {
2039 if self.read_only {
2040 return Err(MnemoError::ReadOnly);
2041 }
2042 let Some(mut m) = self
2043 .about_in(crate::memory::VisibilitySet::ALL)?
2044 .into_iter()
2045 .find(is_manifest)
2046 else {
2047 return Err(MnemoError::Invalid(
2048 "this brain has no manifest to record the pause on".into(),
2049 ));
2050 };
2051 if m.metadata.contains_key(MNEMO_META_WAKE_PAUSED) == paused {
2052 return Ok(WriteOutcome::Unchanged);
2053 }
2054 if paused {
2055 let mut v = Map::new();
2056 v.insert(
2057 "by".into(),
2058 Value::String(self.author.clone().unwrap_or_else(|| "anonymous".into())),
2059 );
2060 v.insert("at".into(), Value::from(self.coordination_now()));
2061 m.metadata
2062 .insert(MNEMO_META_WAKE_PAUSED.into(), Value::Object(v));
2063 } else {
2064 m.metadata.remove(MNEMO_META_WAKE_PAUSED);
2065 }
2066 self.put(m)?;
2067 Ok(WriteOutcome::Updated)
2068 }
2069
2070 pub fn wake(&mut self, agent: &str, role: Option<&str>) -> Result<Wake> {
2085 if self.read_only {
2086 return Err(MnemoError::ReadOnly);
2087 }
2088 let now = self.coordination_now();
2089 let sent = crate::memory::delivery::SENT;
2090 let mut tasks = Vec::new();
2091 for t in self.ready_tasks(role)? {
2092 let m = self.get(&t.id)?;
2093 if t.pre_approved
2094 && meta_string(&m, MNEMO_META_DELIVERY).as_deref() == Some(sent)
2095 && !seen_by(&m).iter().any(|s| s == agent)
2096 {
2097 tasks.push(t.id);
2098 }
2099 }
2100 let all_msgs: Vec<Message> = self
2101 .messages()?
2102 .iter()
2103 .filter_map(Message::from_memory)
2104 .collect();
2105 let candidates: Vec<&Message> = all_msgs
2106 .iter()
2107 .filter(|m| m.to == agent && m.from != agent)
2108 .filter(|m| m.status == crate::memory::MESSAGE_UNREAD && m.delivery == sent)
2109 .collect();
2110 if tasks.is_empty() && candidates.is_empty() {
2111 return Ok(Wake::Nothing);
2112 }
2113 if self.wake_paused()?.is_some() {
2114 return Ok(Wake::Held("paused"));
2115 }
2116 let burst = |a: &str, b: &str| {
2117 all_msgs
2118 .iter()
2119 .filter(|m| now - m.created_at <= PAIR_BURST_SECS)
2120 .filter(|m| (m.from == a && m.to == b) || (m.from == b && m.to == a))
2121 .count()
2122 >= PAIR_BURST
2123 };
2124 let mut reason = None;
2125 let messages: Vec<Ulid> = candidates
2126 .iter()
2127 .filter(|m| {
2128 let reply = m.conversation != m.id.to_string();
2129 if reply && m.hops > HOP_CAP {
2130 reason = Some("the thread reached its hop cap");
2131 return false;
2132 }
2133 if burst(&m.from, &m.to) {
2134 reason = Some("a burst of messages between two agents");
2135 return false;
2136 }
2137 true
2138 })
2139 .map(|m| m.id)
2140 .collect();
2141 if tasks.is_empty() && messages.is_empty() {
2142 return Ok(Wake::Held(reason.unwrap_or("a guardrail")));
2143 }
2144 let presence = self
2146 .coordination_records(MNEMO_META_KIND_PRESENCE, Some(agent))?
2147 .into_iter()
2148 .next();
2149 let mut wakes: Vec<i64> = presence
2150 .as_ref()
2151 .and_then(|m| m.metadata.get(MNEMO_META_WAKES))
2152 .and_then(Value::as_array)
2153 .map(|a| a.iter().filter_map(Value::as_i64).collect())
2154 .unwrap_or_default();
2155 wakes.retain(|t| now - t < 3600 && *t <= now);
2156 if wakes.len() >= WAKE_PER_HOUR {
2157 return Ok(Wake::Held("the hourly limit of wake-ups"));
2158 }
2159 if wakes.iter().any(|t| now - t < WAKE_COOLDOWN_SECS) {
2160 return Ok(Wake::Held("the cooldown between wake-ups"));
2161 }
2162 wakes.push(now);
2163 let delivered = Value::String(crate::memory::delivery::DELIVERED.into());
2164 for id in tasks.iter().chain(messages.iter()) {
2165 let mut m = self.get(id)?;
2166 m.metadata
2167 .insert(MNEMO_META_DELIVERY.into(), delivered.clone());
2168 self.put(m)?;
2169 }
2170 let w = Value::Array(wakes.into_iter().map(Value::from).collect());
2171 match presence {
2172 Some(mut m) => {
2173 m.metadata.insert(MNEMO_META_WAKES.into(), w);
2174 self.put(m)?;
2175 }
2176 None => {
2177 let mut meta = Map::new();
2178 meta.insert(MNEMO_META_AGENT.into(), Value::String(agent.to_string()));
2179 meta.insert(MNEMO_META_LAST_ACTIVE.into(), Value::from(0));
2180 meta.insert(MNEMO_META_PRESENCE_LOCK.into(), Value::Bool(false));
2181 meta.insert(MNEMO_META_WAKES.into(), w);
2182 self.put_coordination_with_id(
2183 Ulid::new(),
2184 MNEMO_META_KIND_PRESENCE,
2185 format!("presence {agent}"),
2186 meta,
2187 )?;
2188 }
2189 }
2190 Ok(Wake::Now {
2191 tasks: tasks.len(),
2192 messages: messages.len(),
2193 })
2194 }
2195}
2196
2197#[derive(Debug, Clone, PartialEq, Eq)]
2201pub struct Stale {
2202 pub id: Ulid,
2204 pub what: String,
2208 pub since: i64,
2210 pub text: String,
2212 pub whose: Option<String>,
2214 pub visibility: String,
2216}
2217
2218impl Mnemo {
2219 pub fn stale(&mut self) -> Result<Vec<Stale>> {
2226 use super::records::{ROW_KIND_ESSENCE, ROW_REVIEW};
2227 let now = self.coordination_now();
2228 let entries: Vec<CatalogEntry> = self
2229 .catalog
2230 .iter()
2231 .filter(|e| !e.deleted)
2232 .filter(|e| {
2233 e.v9.is_none_or(|r| {
2234 r.kind == ROW_KIND_ESSENCE
2235 || r.kind == ROW_KIND_COORDINATION
2236 || r.flags & ROW_REVIEW != 0
2237 })
2238 })
2239 .cloned()
2240 .collect();
2241 let mut out = Vec::new();
2242 for e in entries {
2243 let m = self.read_memory(&e)?;
2244 let Some(since) = crate::memory::stale_since(&m, now) else {
2245 continue;
2246 };
2247 let s = |k: &str| meta_string(&m, k);
2248 let kind = s(MNEMO_META_KIND);
2249 let what = match kind.as_deref() {
2250 Some("essence") => format!(
2251 "essence {}",
2252 s(crate::memory::MNEMO_META_SECTION).unwrap_or_default()
2253 ),
2254 Some(k @ ("task" | "message")) => {
2255 format!("{k} {}", s(MNEMO_META_STATUS).unwrap_or_default())
2256 }
2257 Some(k) => k.to_string(),
2258 None => "fact".to_string(),
2259 };
2260 let whose = match kind.as_deref() {
2261 Some("task") => s(MNEMO_META_OWNER),
2262 Some("message") => s(MNEMO_META_TO),
2263 _ => s(crate::memory::MNEMO_META_AUTHOR),
2264 };
2265 out.push(Stale {
2266 id: m.id,
2267 what,
2268 since,
2269 text: m.content.lines().next().unwrap_or("").to_string(),
2270 whose,
2271 visibility: crate::memory::visibility_of(&m).to_string(),
2272 });
2273 }
2274 out.sort_by_key(|x| (x.since, x.id.0));
2275 Ok(out)
2276 }
2277}
2278
2279#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
2281pub struct KindCounts {
2282 pub facts: usize,
2284 pub turns: usize,
2286 pub essence: usize,
2288 pub coordination: usize,
2290}
2291
2292impl Mnemo {
2293 pub fn kind_counts(&self) -> KindCounts {
2297 use super::records::{ROW_KIND_ESSENCE, ROW_KIND_THREAD_LINK, ROW_KIND_TURN};
2298 let mut c = KindCounts::default();
2299 for e in self.catalog.iter().filter(|e| !e.deleted) {
2300 match e.v9.map(|r| r.kind) {
2301 Some(ROW_KIND_TURN | ROW_KIND_THREAD_LINK) => c.turns += 1,
2302 Some(ROW_KIND_ESSENCE) => c.essence += 1,
2303 Some(ROW_KIND_COORDINATION) => c.coordination += 1,
2304 _ => c.facts += 1,
2305 }
2306 }
2307 c
2308 }
2309}
2310
2311#[cfg(test)]
2312mod legacy_scan_tests {
2313 use super::is_sentinel;
2314
2315 #[test]
2318 fn the_sentinel_is_told_from_an_ordinary_vector() {
2319 for dims in [4, 32, 384, 768] {
2320 let s = vec![1.0 / (dims as f32).sqrt(); dims];
2321 let (h, _) = crate::veccol::quantize(&s);
2322 assert!(is_sentinel(&h), "{dims}");
2323 let mut v = s.clone();
2324 v[dims / 2] += 0.05;
2325 assert!(!is_sentinel(&crate::veccol::quantize(&v).0), "{dims}");
2326 let flat = vec![0.5; dims];
2327 assert_eq!(
2328 is_sentinel(&crate::veccol::quantize(&flat).0),
2329 dims == 4,
2330 "{dims}"
2331 );
2332 }
2333 assert!(!is_sentinel(&[]));
2334 }
2335}