Module messaging

Expand description

Inter-project messaging primitive (issue #99).

Why: Replaces the Python /mpm-message skill (claude-mpm repo, writes to ~/.claude-mpm/messaging.db) with a trusty-memory-native primitive. Single-daemon-per-host architecture means cross-project messaging is just a write to a different palace and a read at session start — no IPC required.

What: helpers that encode messages as drawers tagged with a msg:* namespace so we don’t have to change the Drawer schema:

msg:v1 — marker tag for fast filtering / dedup.
msg:from=<palace> — sender palace id.
msg:to=<palace> — recipient palace id (redundant with the host palace, kept for audit + cross-palace queries).
msg:purpose=<string> — free-text purpose / category set by the sender.
msg:sent_at=<rfc3339> — UTC ISO 8601 timestamp when the sender wrote it.
msg:read=<bool> — receiver-controlled read flag (true after the SessionStart hook has delivered it once).

Sub-modules:

types: Message, tag-prefix constants, build_message_tags, slug helpers.
operations: send_message_to_palace, list_unread_messages, list_messages, mark_message_read, cwd_palace_slug.

Test: tests::round_trip_send_and_inbox, tests::slug_derivation_cases, tests::mark_read_is_atomic_under_concurrency.

Structs§

Message: Decoded view of a message drawer.

Constants§

MSG_MARKER_TAG: Tag namespace prefix marking a drawer as a v1 inter-project message.
TAG_FROM_PREFIX: Tag prefix carrying the sender’s palace id (e.g. msg:from=trusty-tools).
TAG_PURPOSE_PREFIX: Tag prefix carrying the sender-defined purpose (e.g. msg:purpose=task).
TAG_READ_PREFIX: Tag prefix carrying the read flag (msg:read=false or msg:read=true).
TAG_SENT_AT_PREFIX: Tag prefix carrying the RFC3339 send timestamp (e.g. msg:sent_at=2026-05-25T12:34:56+00:00).
TAG_TO_PREFIX: Tag prefix carrying the recipient palace id (e.g. msg:to=claude-mpm).

Functions§

build_message_tags: Build the tag vector for a freshly-sent message.
cwd_palace_slug: Resolve the calling project’s palace slug from cwd, preferring the git toplevel when available.
cwd_palace_slug_at: Variant of cwd_palace_slug that takes the working directory explicitly.
list_messages: List every message drawer in palace, optionally filtering to unread.
list_unread_messages: List every unread message drawer in palace.
mark_message_read: Mark a message drawer as read by atomically rewriting its msg:read=... tag.
send_message_to_palace: Persist a message into the recipient palace.
slugify_for_palace: Derive a palace slug from a filesystem path.
slugify_string: String-level slug helper used by slugify_for_palace.