diff --git a/DESCRIPTION b/DESCRIPTION
index fc1bf85..2d2d66a 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,8 +1,8 @@
Package: chat.api
Type: Package
Title: Transport-Agnostic Chat Contract
-Version: 0.2.0
-Date: 2026-11-10
+Version: 0.2.0.1
+Date: 2026-11-18
Authors@R: c(
person("Troy", "Hernandez", role = c("aut", "cre"),
email = "troy@cornball.ai",
diff --git a/NEWS.md b/NEWS.md
index 1fa0165..be678b6 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,3 +1,15 @@
+# chat.api 0.2.0.1
+
+* `chat_send()` and `chat_edit()` take `content`, a named list of keys
+ for the message's own content: data a consumer's client reads and
+ other clients ignore. On Matrix the keys go beside the body, in
+ cleartext and encrypted rooms alike, and an edit carries them in its
+ new content. A key chat.api writes itself is refused before anything
+ is sent. Slack, Telegram and IRC take the argument and ignore it.
+* A received Matrix message's `raw` carries the event's whole content in
+ `raw$content`, for text and pictures, in cleartext and encrypted
+ rooms. A cleartext message's `raw` had no `content` before.
+
# chat.api 0.2.0
* Send encrypted Matrix attachments using the adapter's existing crypto
diff --git a/R/contract.R b/R/contract.R
index da8c1d2..bb23f35 100644
--- a/R/contract.R
+++ b/R/contract.R
@@ -61,6 +61,22 @@ chat_poll <- function(client, since = NULL, timeout = NULL, ...) {
#' nothing else.
#' @param notify Logical; FALSE requests a silent delivery where
#' supported.
+#' @param content Keys of the caller's own for the message's content, as
+#' a named list, or NULL. Matrix adds them to the \code{m.room.message}
+#' content beside \code{body} and \code{msgtype}, inside the ciphertext
+#' in an encrypted room, so a consumer can carry data its own client
+#' reads and every other client ignores, under a namespaced key such
+#' as \code{"ai.cornball.agent"}. A received message carries its
+#' content in \code{raw$content}, and the loopback adapter records
+#' these keys there too; the other adapters ignore them, as they
+#' ignore \code{rich}, so \code{text} has to stand on its own.
+#'
+#' A key chat.api writes itself is refused: \code{body},
+#' \code{msgtype}, \code{format}, \code{formatted_body},
+#' \code{m.relates_to}, \code{m.mentions} and \code{m.new_content}.
+#' \code{text}, \code{kind}, \code{rich}, \code{thread} and the
+#' \code{mentions} option set those. With \code{files}, the keys go on
+#' the text's event, not on the attachments'.
#' @param ... Adapter-specific options.
#' @return Character vector of the message ids this call created, in the
#' order they were sent, invisibly. Usually length one. A platform that
@@ -78,10 +94,38 @@ chat_poll <- function(client, since = NULL, timeout = NULL, ...) {
chat_send <- function(client, channel, text, markup = c("plain", "markdown"),
thread = NULL, reply_to = NULL, identity = NULL,
files = NULL, kind = "message", notify = TRUE,
- rich = NULL, ...) {
+ rich = NULL, content = NULL, ...) {
UseMethod("chat_send")
}
+# The keys chat_send() and chat_edit() write themselves, which a
+# caller's content may not name. Each has an argument of its own, and a
+# second way to set it would leave the two disagreeing on the wire.
+CHAT_CONTENT_RESERVED <- c("body", "msgtype", "format", "formatted_body",
+ "m.relates_to", "m.mentions", "m.new_content")
+
+# A caller's content keys, checked: NULL for none (an empty list is
+# none too), or a named list whose names are distinct, non-empty and
+# not chat.api's own.
+chat_content_keys <- function(content) {
+ if (is.null(content) || (is.list(content) && !length(content))) {
+ return(NULL)
+ }
+ nms <- names(content)
+ if (!is.list(content) || is.null(nms) || anyNA(nms) ||
+ !all(nzchar(nms)) || anyDuplicated(nms)) {
+ stop("content must be NULL or a list with distinct names.",
+ call. = FALSE)
+ }
+ taken <- intersect(nms, CHAT_CONTENT_RESERVED)
+ if (length(taken)) {
+ stop("content may not set ", paste(taken, collapse = ", "),
+ ", which chat.api writes itself. Use text, kind, rich, thread ",
+ "or mentions instead.", call. = FALSE)
+ }
+ content
+}
+
#' Signal typing state in a channel
#'
#' Capability-gated: the default method is a no-op so adapters without
@@ -555,6 +599,11 @@ chat_disconnect.default <- function(client, ...) {
#' adapter-specific and may already be normalized by the transport
#' package (Matrix hands over an extracted record, not the timeline
#' event), so it is an escape hatch, not a guarantee of completeness.
+#' One part is promised: a Matrix message, cleartext or decrypted,
+#' carries its event's whole content in \code{raw$content}, with any
+#' keys a sender added of its own (\code{\link{chat_send}}'s
+#' \code{content}), and the loopback adapter records those keys
+#' there.
#' @param attachments List of \code{\link{chat_attachment}} records,
#' or NULL. Inbound media: what a sent \code{files =} looks like
#' from the receiving side, on adapters whose
@@ -1186,6 +1235,12 @@ chat_relogin.default <- function(client, ...) {
#' the message was sent as: Matrix carries the msgtype inside the
#' replacement content, so editing an \code{m.notice} without saying so
#' turns it into an ordinary message.
+#' @param content Keys of the caller's own for the replacement, as
+#' \code{\link{chat_send}}. Matrix puts them in \code{m.new_content},
+#' beside the replacement text, and in the fallback copy around it, as
+#' it does the formatted text. Like the text, they replace the
+#' original's: a key the edit does not repeat is gone from the edited
+#' message.
#' @param ... Adapter-specific options.
#' @return The identifier of the event the edit created where the
#' platform makes one (Matrix), or of the edited message where it does
@@ -1205,14 +1260,14 @@ chat_relogin.default <- function(client, ...) {
#' @export
chat_edit <- function(client, channel, message_id, text,
markup = c("plain", "markdown"), rich = NULL,
- kind = "message", ...) {
+ kind = "message", content = NULL, ...) {
UseMethod("chat_edit")
}
#' @export
chat_edit.default <- function(client, channel, message_id, text,
markup = c("plain", "markdown"), rich = NULL,
- kind = "message", ...) {
+ kind = "message", content = NULL, ...) {
stop("chat_edit() is not supported by this adapter (",
paste(class(client), collapse = "/"),
"). Check chat_capabilities()$edits.", call. = FALSE)
diff --git a/R/irc.R b/R/irc.R
index 37fded8..c525a60 100644
--- a/R/irc.R
+++ b/R/irc.R
@@ -98,7 +98,7 @@ chat_send.chat_irc <- function(client, channel, text,
thread = NULL, reply_to = NULL,
identity = NULL, files = NULL,
kind = "message", notify = TRUE, rich = NULL,
- ...) {
+ content = NULL, ...) {
markup <- match.arg(markup)
verb <- if (identical(kind, "notice")) {
"NOTICE"
diff --git a/R/loopback.R b/R/loopback.R
index c29cae9..70e29e0 100644
--- a/R/loopback.R
+++ b/R/loopback.R
@@ -84,8 +84,9 @@ chat_send.chat_loopback <- function(client, channel, text,
thread = NULL, reply_to = NULL,
identity = NULL, files = NULL,
kind = "message", notify = TRUE,
- rich = NULL, ...) {
+ rich = NULL, content = NULL, ...) {
markup <- match.arg(markup)
+ content <- chat_content_keys(content)
attachments <- NULL
if (!is.null(files)) {
# A missing file errors rather than sending a message that
@@ -111,11 +112,22 @@ chat_send.chat_loopback <- function(client, channel, text,
else identity$name,
body = text, ts = Sys.time(), thread = thread,
markup = markup, kind = kind,
- attachments = attachments)
+ attachments = attachments,
+ raw = loopback_raw(content))
client$env$log[[length(client$env$log) + 1L]] <- msg
invisible(id)
}
+# A caller's content keys where a Matrix message carries its content,
+# raw$content, so a consumer reads them the same way against the
+# reference adapter and a homeserver. NULL when there are none.
+loopback_raw <- function(content) {
+ if (is.null(content)) {
+ return(NULL)
+ }
+ list(content = content)
+}
+
#' @export
chat_download.chat_loopback <- function(client, attachment, dest = NULL, ...) {
dest <- attachment_dest(attachment, dest)
@@ -224,8 +236,10 @@ chat_history.chat_loopback <- function(client, channel, limit = 50L,
#' @export
chat_edit.chat_loopback <- function(client, channel, message_id, text,
markup = c("plain", "markdown"),
- rich = NULL, kind = "message", ...) {
+ rich = NULL, kind = "message",
+ content = NULL, ...) {
markup <- match.arg(markup)
+ content <- chat_content_keys(content)
pos <- which(vapply(client$env$log,
function(m) identical(m$id, message_id), logical(1)))
if (!length(pos)) {
@@ -238,6 +252,9 @@ chat_edit.chat_loopback <- function(client, channel, message_id, text,
msg <- client$env$log[[pos[[1L]]]]
msg$body <- text
msg$markup <- markup
+ # The edit's keys replace the original's, as on Matrix, where the
+ # edited message is m.new_content and nothing else.
+ msg["raw"] <- list(loopback_raw(content))
client$env$log[[pos[[1L]]]] <- msg
invisible(message_id)
}
diff --git a/R/matrix.R b/R/matrix.R
index cc84e4a..80955e0 100644
--- a/R/matrix.R
+++ b/R/matrix.R
@@ -157,7 +157,8 @@
#' (\code{mx.api::mx_upload} and \code{mx_set_avatar_url}). Leave
#' NULL in production.
#' @param .rich Testing seam: replacement for \code{mx.api::mx_send} on
-#' the rich-send path. Leave NULL in production.
+#' the rich-send path, and on the path of a send with \code{content}
+#' outside an encrypted room. Leave NULL in production.
#' @param .edit Testing seam: replacement for \code{mx.api::mx_send} on
#' the edit path. Leave NULL in production.
#' @return A \code{chat_client} of class \code{chat_matrix}.
@@ -277,6 +278,33 @@ matrix_event_times <- function(sync) {
out
}
+# Every joined-room timeline event's content, keyed by event id, the
+# same keyed lookup: mx_extract_text_events() keeps 6 fields of a
+# message's content, and keys a sender added of its own
+# (chat_send(content =)) are none of them.
+matrix_event_contents <- function(sync) {
+ out <- list()
+ for (room in sync$rooms$join %||% list()) {
+ for (ev in room$timeline$events %||% list()) {
+ if (!is.null(ev$event_id) && is.list(ev$content)) {
+ out[[as.character(ev$event_id)]] <- ev$content
+ }
+ }
+ }
+ out
+}
+
+# A cleartext record, text or media, as a message's raw, with its event's
+# whole content in raw$content. A decrypted record has content already
+# (mx.client keeps the decrypted payload's), and history's raw is the
+# event itself, so raw$content reads the same for all of them.
+matrix_raw_with_content <- function(record, contents) {
+ if (is.null(record$content)) {
+ record$content <- contents[[as.character(record$event_id)]]
+ }
+ record
+}
+
# Each timeline event's position in the sync, by event id. Walks the same
# structure matrix_event_times() does, and for the same reason: it is the
# only place the homeserver's own ordering survives, since the cleartext
@@ -547,6 +575,7 @@ chat_poll.chat_matrix <- function(client, since = NULL, timeout = NULL, ...) {
event_ts <- matrix_event_times(res$sync)
event_pos <- matrix_event_order(res$sync)
+ event_content <- matrix_event_contents(res$sync)
recs <- client$extract_fn(res$sync, self_id = res$client$user_id)
messages <- lapply(recs, function(r) {
# ts is the event's own origin_server_ts, from the record when
@@ -568,7 +597,7 @@ chat_poll.chat_matrix <- function(client, since = NULL, timeout = NULL, ...) {
markup = "plain", kind = matrix_kind(r$msgtype),
self = isTRUE(r$is_self),
mentions = unlist(r$mentions, use.names = FALSE),
- raw = r)
+ raw = matrix_raw_with_content(r, event_content))
})
# Decrypted traffic folds in alongside the cleartext, in the same
# chat_message shape, so a consumer cannot tell which arrived
@@ -637,7 +666,7 @@ chat_poll.chat_matrix <- function(client, since = NULL, timeout = NULL, ...) {
url = as.character(a$url),
sha256 = a$sha256 %||% NA_character_,
raw = a)),
- raw = a)
+ raw = matrix_raw_with_content(a, event_content))
}
# Back into the order the homeserver sent them. Appending the
# decrypted events put every one of them after every cleartext one,
@@ -686,8 +715,11 @@ chat_send.chat_matrix <- function(client, channel, text,
thread = NULL, reply_to = NULL,
identity = NULL, files = NULL,
kind = "message", notify = TRUE,
- rich = NULL, ...) {
+ rich = NULL, content = NULL, ...) {
markup <- match.arg(markup)
+ # Checked before anything is uploaded, like the encryption question
+ # below: a refused key must not leave the files posted already.
+ content <- chat_content_keys(content)
# Resolved before anything is uploaded or posted. The encryption
# question used to be asked after the attachment loop had already run,
# which put the files on the homeserver in the clear before the text
@@ -750,10 +782,25 @@ chat_send.chat_matrix <- function(client, channel, text,
# shape for a caller's fragment. The text still arrives, and
# chat_capabilities()$rich_markup is empty on an e2ee client
# so a consumer can know beforehand.
- event <- client$crypto_ops$send(crypto, client$env$mx, channel,
- text, msgtype = msgtype,
+ args <- list(crypto, client$env$mx, channel, text,
+ msgtype = msgtype,
+ markdown = identical(markup, "markdown"),
+ mentions = list(...)$mentions)
+ # A caller's keys go in as extra content, which the Megolm
+ # path encrypts with the rest. Named only when there are
+ # some, so a crypto seam without the argument still sends.
+ if (!is.null(content)) {
+ args$extra <- content
+ }
+ event <- do.call(client$crypto_ops$send, args)
+ return(invisible(c(media_ids, as.character(event))))
+ }
+ if (!is.null(content)) {
+ event <- matrix_send_content(client, channel, text, msgtype,
+ content, rich = rich,
markdown = identical(markup, "markdown"),
- mentions = list(...)$mentions)
+ mentions = list(...)$mentions,
+ thread = thread)
return(invisible(c(media_ids, as.character(event))))
}
if (!is.null(rich)) {
@@ -1187,8 +1234,10 @@ chat_mark_read.chat_matrix <- function(client, channel, message_id, ...) {
#' @export
chat_edit.chat_matrix <- function(client, channel, message_id, text,
markup = c("plain", "markdown"),
- rich = NULL, kind = "message", ...) {
+ rich = NULL, kind = "message",
+ content = NULL, ...) {
markup <- match.arg(markup)
+ content <- chat_content_keys(content)
msgtype <- matrix_msgtype(kind)
html <- if (identical(markup, "markdown")) {
mx.client::mx_markdown_to_html(text)
@@ -1206,6 +1255,12 @@ chat_edit.chat_matrix <- function(client, channel, message_id, text,
new_content$format <- "org.matrix.custom.html"
new_content$formatted_body <- html
}
+ # A caller's keys go in the replacement, which is what a client that
+ # understands edits shows, and in the fallback copy around it, as the
+ # formatted text does: a client showing the edit event itself, its
+ # original out of view, still has them. Encrypted, they ride inside
+ # the ciphertext with the rest.
+ new_content <- c(new_content, content)
extra <- list(`m.new_content` = new_content,
`m.relates_to` = list(rel_type = "m.replace", event_id = message_id))
if (!is.null(html)) {
@@ -1216,6 +1271,7 @@ chat_edit.chat_matrix <- function(client, channel, message_id, text,
# it is a correction rather than the bot repeating itself.
extra$formatted_body <- paste0("* ", html)
}
+ extra <- c(extra, content)
# In an encrypted room the whole event -- the "* " fallback body, the
# m.new_content and the relation -- is encrypted with Megolm, so the
# replacement text never reaches the homeserver in the clear. The
@@ -1251,19 +1307,54 @@ matrix_send_rich <- function(client, channel, text, rich, msgtype,
fn <- client$rich_fn %||% mx.api::mx_send
extra <- list(format = "org.matrix.custom.html", formatted_body = rich)
if (!is.null(thread)) {
- # Built here rather than borrowed from mx_send_text(), which
- # this path exists to bypass: it renders its own HTML and has
- # nowhere to put a supplied fragment. The relation is the same
- # one, fallback included, so a rich threaded reply is threaded
- # in exactly the clients a plain one is.
- extra[["m.relates_to"]] <- list(
- rel_type = "m.thread", event_id = thread,
- is_falling_back = TRUE,
- "m.in_reply_to" = list(event_id = thread))
+ extra[["m.relates_to"]] <- matrix_thread_relation(thread)
}
fn(sess, channel, text, msgtype = msgtype, extra = extra)
}
+# A threaded reply's relation, for the sends that bypass mx_send_text():
+# it renders its own HTML and has nowhere to put a supplied fragment or
+# a caller's keys. The relation is the one it builds, fallback included,
+# so such a reply is threaded in exactly the clients a plain one is.
+matrix_thread_relation <- function(thread) {
+ list(rel_type = "m.thread", event_id = thread, is_falling_back = TRUE,
+ "m.in_reply_to" = list(event_id = thread))
+}
+
+# A send carrying a caller's own content keys (chat_send(content =)) in
+# a room that is not encrypted. mx_send_text() takes no extra content,
+# so this builds the event it would have built -- HTML rendered from
+# markdown with the mentions as pills, m.mentions, the thread relation
+# -- or carries the caller's fragment as matrix_send_rich() does, and
+# adds the keys last. m.mentions goes in with a fragment too, since the
+# notification depends on it; only the pills need HTML of chat.api's
+# own. Through the rich seam: both are an mx_send() with extra content.
+matrix_send_content <- function(client, channel, text, msgtype, content,
+ rich = NULL, markdown = FALSE,
+ mentions = NULL, thread = NULL) {
+ html <- rich
+ if (is.null(html) && (isTRUE(markdown) || length(mentions))) {
+ html <- mx.client::mx_markdown_to_html(text)
+ if (length(mentions)) {
+ html <- mx.client::mx_pill_mentions(html, mentions)
+ }
+ }
+ extra <- list()
+ if (!is.null(html)) {
+ extra$format <- "org.matrix.custom.html"
+ extra$formatted_body <- html
+ }
+ if (length(mentions)) {
+ extra[["m.mentions"]] <- list(user_ids = as.list(mentions))
+ }
+ if (!is.null(thread)) {
+ extra[["m.relates_to"]] <- matrix_thread_relation(thread)
+ }
+ sess <- mx.client::mx_client_session(client$env$mx)
+ fn <- client$rich_fn %||% mx.api::mx_send
+ fn(sess, channel, text, msgtype = msgtype, extra = c(extra, content))
+}
+
# The contract's kind vocabulary as a Matrix msgtype, plus a documented
# way past it: a kind already spelled as a msgtype goes out as itself.
# The contract has no word for an image or a file, and mapping those to
diff --git a/R/slack.R b/R/slack.R
index 0e055c3..138140f 100644
--- a/R/slack.R
+++ b/R/slack.R
@@ -205,7 +205,8 @@ chat_send.chat_slack <- function(client, channel, text,
thread = NULL, reply_to = NULL,
identity = NULL, files = NULL,
kind = "message", notify = TRUE,
- rich = NULL, as_user = FALSE, ...) {
+ rich = NULL, content = NULL,
+ as_user = FALSE, ...) {
markup <- match.arg(markup)
if (isTRUE(as_user) && !nzchar(client$user_token %||% "")) {
stop("chat_send(as_user = TRUE) needs a user token ",
@@ -645,7 +646,8 @@ chat_set_identity.chat_slack <- function(client, display = NULL,
#' @export
chat_edit.chat_slack <- function(client, channel, message_id, text,
markup = c("plain", "markdown"),
- rich = NULL, kind = "message", ...) {
+ rich = NULL, kind = "message",
+ content = NULL, ...) {
markup <- match.arg(markup)
api <- client$api_fn %||% slackr::call_slack_api
resp <- api("/api/chat.update", .method = "POST", token = client$token,
diff --git a/R/telegram.R b/R/telegram.R
index 91105fb..df0ca4d 100644
--- a/R/telegram.R
+++ b/R/telegram.R
@@ -500,7 +500,7 @@ chat_send.chat_telegram <- function(client, channel, text,
thread = NULL, reply_to = NULL,
identity = NULL, files = NULL,
kind = "message", notify = TRUE,
- rich = NULL, ...) {
+ rich = NULL, content = NULL, ...) {
markup <- match.arg(markup)
# identity is ignored: a bot posts as itself and Telegram has no
# per-message override, which identity_override = FALSE says. kind
@@ -538,7 +538,8 @@ chat_send.chat_telegram <- function(client, channel, text,
#' @export
chat_edit.chat_telegram <- function(client, channel, message_id, text,
markup = c("plain", "markdown"),
- rich = NULL, kind = "message", ...) {
+ rich = NULL, kind = "message",
+ content = NULL, ...) {
markup <- match.arg(markup)
r <- telegram_render(text, markup, rich)
telegram_call(client, "editMessageText",
diff --git a/inst/tinytest/test_contract.R b/inst/tinytest/test_contract.R
index d7c38bb..dcbeffe 100644
--- a/inst/tinytest/test_contract.R
+++ b/inst/tinytest/test_contract.R
@@ -315,6 +315,55 @@ local({
"not supported by this adapter")
})
+# ---- A caller's content keys on the reference adapter ----
+# Recorded where a Matrix message carries its content, raw$content, so a
+# consumer's test reads them as its code does against a homeserver.
+local({
+ cl <- chat_loopback()
+ tool <- list(v = 1L, kind = "tool", tool_call_id = "t1",
+ status = "pending")
+ id <- chat_send(cl, "general", "[tool] ls (pending)", kind = "notice",
+ content = list(ai.cornball.agent = tool))
+ m <- chat_poll(cl)$messages[[1L]]
+ expect_identical(m$raw$content, list(ai.cornball.agent = tool))
+ expect_identical(m$kind, "notice")
+ # An edit's keys replace the original's, as the edited Matrix message
+ # is m.new_content alone; an edit without keys leaves none.
+ tool$status <- "completed"
+ chat_edit(cl, "general", id, "[tool] ls (completed)", kind = "notice",
+ content = list(ai.cornball.agent = tool))
+ h <- chat_history(cl, "general")$messages[[1L]]
+ expect_identical(h$raw$content[["ai.cornball.agent"]]$status, "completed")
+ chat_edit(cl, "general", id, "plain now")
+ h <- chat_history(cl, "general")$messages[[1L]]
+ expect_null(h$raw)
+ expect_true("raw" %in% names(h))
+ # Without keys, a message has no raw, as before; an empty list is
+ # no keys.
+ chat_send(cl, "general", "hello", content = list())
+ expect_null(chat_poll(cl, since = 1L)$messages[[1L]]$raw)
+ # The same refusals as Matrix: the reference adapter is where a
+ # consumer finds out.
+ expect_error(chat_send(cl, "general", "x", content = list(body = "y")),
+ "content may not set body")
+ expect_error(chat_edit(cl, "general", id, "x",
+ content = list(format = "html")),
+ "content may not set format")
+})
+
+# The other adapters take the argument and ignore it, as they ignore
+# rich: text is the message there.
+local({
+ for (fn in list(chat.api:::chat_send.chat_slack,
+ chat.api:::chat_send.chat_telegram,
+ chat.api:::chat_send.chat_irc,
+ chat.api:::chat_edit.chat_slack,
+ chat.api:::chat_edit.chat_telegram,
+ chat.api:::chat_edit.default)) {
+ expect_true("content" %in% names(formals(fn)))
+ }
+})
+
# ---- Channel lifecycle on the reference adapter ----
# A created channel exists before any traffic: chat_channels() must
# report it, or a consumer that creates and then lists sees its own
diff --git a/inst/tinytest/test_matrix.R b/inst/tinytest/test_matrix.R
index 3853bc0..e79b2be 100644
--- a/inst/tinytest/test_matrix.R
+++ b/inst/tinytest/test_matrix.R
@@ -2382,3 +2382,245 @@ expect_identical(chat.api:::matrix_msgtype("emote"), "m.emote")
expect_identical(chat.api:::matrix_msgtype("message"), "m.text")
expect_identical(chat.api:::matrix_msgtype("m.image"), "m.image")
expect_identical(chat.api:::matrix_msgtype(NULL), "m.text")
+
+# ---- A caller's content keys ----
+# A consumer's own data rides in the event's content under a namespaced
+# key, which its client reads while every other client shows the body.
+# Both ways, cleartext and encrypted.
+
+agent <- list(v = 1L, kind = "tool", tool_call_id = "t1", status = "pending")
+done <- list(v = 1L, kind = "tool", tool_call_id = "t1", status = "completed")
+
+# A cleartext send puts the keys beside body and msgtype. mx_send_text()
+# takes no extra content, so the send goes through mx_send(), and still
+# carries what mx_send_text() would have: mentions, thread, markdown.
+if (requireNamespace("mx.client", quietly = TRUE))
+local({
+ seen <- NULL
+ plain <- 0L
+ cl <- seam_client(send = function(...) {
+ plain <<- plain + 1L
+ "$plain"
+ },
+ .rich = function(session, channel, text, msgtype = "m.text",
+ extra = NULL) {
+ seen <<- list(channel = channel, text = text, msgtype = msgtype,
+ extra = extra)
+ "$c1"
+ })
+ expect_identical(chat_send(cl, "!a:ex", "[tool] ls (pending)",
+ kind = "notice",
+ content = list(ai.cornball.agent = agent)),
+ "$c1")
+ expect_identical(seen$channel, "!a:ex")
+ expect_identical(seen$text, "[tool] ls (pending)")
+ expect_identical(seen$msgtype, "m.notice")
+ expect_identical(seen$extra[["ai.cornball.agent"]], agent)
+ # Plain, with nobody mentioned: no HTML and no m.mentions to add.
+ expect_null(seen$extra$format)
+ expect_null(seen$extra[["m.mentions"]])
+ expect_null(seen$extra[["m.relates_to"]])
+
+ chat_send(cl, "!a:ex", "Turn done, @owner", kind = "notice",
+ content = list(ai.cornball.agent = done),
+ mentions = "@owner:ex", thread = "$root")
+ expect_identical(seen$extra[["m.mentions"]],
+ list(user_ids = list("@owner:ex")))
+ expect_identical(seen$extra$format, "org.matrix.custom.html")
+ expect_identical(seen$extra[["m.relates_to"]]$rel_type, "m.thread")
+ expect_identical(seen$extra[["m.relates_to"]]$event_id, "$root")
+ expect_identical(seen$extra[["ai.cornball.agent"]], done)
+
+ chat_send(cl, "!a:ex", "**ok**", markup = "markdown",
+ content = list(ai.cornball.agent = agent))
+ expect_true(grepl("ok", seen$extra$formatted_body,
+ fixed = TRUE))
+ # A caller's own fragment is sent as given, and its mentions still
+ # notify.
+ chat_send(cl, "!a:ex", "ok", rich = "ok",
+ content = list(ai.cornball.agent = agent),
+ mentions = "@owner:ex")
+ expect_identical(seen$extra$formatted_body, "ok")
+ expect_identical(seen$extra[["m.mentions"]],
+ list(user_ids = list("@owner:ex")))
+
+ # Without keys, nothing changes: the ordinary path, and an empty
+ # list is no keys.
+ expect_identical(plain, 0L)
+ chat_send(cl, "!a:ex", "hello")
+ chat_send(cl, "!a:ex", "hello", content = list())
+ expect_identical(plain, 2L)
+})
+
+# A key chat.api writes itself is refused, before anything is sent: a
+# second way to set it would leave the two disagreeing on the wire.
+local({
+ cl <- seam_client(send = function(...) stop("sent"),
+ .rich = function(...) stop("sent"),
+ media = function(...) stop("uploaded"))
+ expect_error(chat_send(cl, "!a:ex", "x", content = list(body = "y")),
+ "content may not set body")
+ expect_error(chat_send(cl, "!a:ex", "x",
+ content = list(`m.relates_to` = list())),
+ "m.relates_to")
+ expect_error(chat_send(cl, "!a:ex", "x",
+ files = tempfile(), content = list(msgtype = "m.text")),
+ "msgtype")
+ expect_error(chat_send(cl, "!a:ex", "x", content = list(1)),
+ "distinct names")
+ expect_error(chat_send(cl, "!a:ex", "x", content = "ai.cornball.agent"),
+ "distinct names")
+ expect_error(chat_send(cl, "!a:ex", "x",
+ content = list(a = 1, a = 2)),
+ "distinct names")
+ expect_error(chat_edit(cl, "!a:ex", "$o", "x",
+ content = list(`m.new_content` = list())),
+ "m.new_content")
+})
+
+# Encrypted, the keys go in as extra content, which the Megolm path
+# encrypts with the rest. No cleartext transport is touched. Without
+# keys no extra is named, so a crypto seam without the argument sends.
+local({
+ ctx <- new.env(parent = emptyenv())
+ seen <- list()
+ ops <- list(init = function(...) ctx,
+ encrypted = function(crypto, mx, room_id) TRUE,
+ send = function(crypto, mx, room_id, text, ...) {
+ seen[[length(seen) + 1L]] <<- c(list(text = text), list(...))
+ "$enc"
+ },
+ decrypt = function(...) list())
+ cl <- seam_client(mx = fake_mx(user_id = "@e2ee-content:ex"),
+ .crypto = ops, e2ee = TRUE,
+ send = function(...) stop("cleartext send"),
+ .rich = function(...) stop("cleartext send"))
+ expect_identical(chat_send(cl, "!secret:ex", "[tool] ls (pending)",
+ kind = "notice",
+ content = list(ai.cornball.agent = agent)),
+ "$enc")
+ expect_identical(seen[[1L]]$text, "[tool] ls (pending)")
+ expect_identical(seen[[1L]]$msgtype, "m.notice")
+ expect_identical(seen[[1L]]$extra, list(ai.cornball.agent = agent))
+ chat_send(cl, "!secret:ex", "plain")
+ expect_false("extra" %in% names(seen[[2L]]))
+})
+
+# An edit's keys go in m.new_content, which is the edited message, and
+# in the fallback copy around it, as the formatted text does: a client
+# showing the edit event itself still has them. Cleartext ...
+if (requireNamespace("mx.client", quietly = TRUE))
+local({
+ seen <- NULL
+ cl <- seam_client(.edit = function(session, room_id, body, msgtype = "m.text",
+ extra = NULL) {
+ seen <<- list(body = body, msgtype = msgtype, extra = extra)
+ "$e"
+ })
+ chat_edit(cl, "!a:ex", "$o", "[tool] ls (completed)", kind = "notice",
+ content = list(ai.cornball.agent = done))
+ expect_identical(seen$extra[["m.new_content"]][["ai.cornball.agent"]], done)
+ expect_identical(seen$extra[["m.new_content"]]$body, "[tool] ls (completed)")
+ expect_identical(seen$extra[["m.new_content"]]$msgtype, "m.notice")
+ expect_identical(seen$extra[["ai.cornball.agent"]], done)
+ expect_identical(seen$body, "* [tool] ls (completed)")
+ # Without keys the replacement has none, and the fallback none, as
+ # before.
+ chat_edit(cl, "!a:ex", "$o", "x", kind = "notice")
+ expect_identical(names(seen$extra[["m.new_content"]]), c("msgtype", "body"))
+ expect_identical(names(seen$extra), c("m.new_content", "m.relates_to"))
+})
+# ... and encrypted, inside the ciphertext.
+local({
+ ctx <- new.env(parent = emptyenv())
+ seen <- NULL
+ ops <- list(init = function(...) ctx,
+ encrypted = function(crypto, mx, room_id) TRUE,
+ send = function(crypto, mx, room_id, text, ...) {
+ seen <<- c(list(text = text), list(...))
+ "$enc"
+ },
+ decrypt = function(...) list())
+ cl <- seam_client(mx = fake_mx(user_id = "@e2ee-content-edit:ex"),
+ .crypto = ops, e2ee = TRUE,
+ .edit = function(...) stop("must not be reached"))
+ chat_edit(cl, "!secret:ex", "$orig", "[tool] ls (completed)",
+ kind = "notice", content = list(ai.cornball.agent = done))
+ expect_identical(seen$text, "* [tool] ls (completed)")
+ expect_identical(seen$extra[["m.new_content"]][["ai.cornball.agent"]], done)
+ expect_identical(seen$extra[["ai.cornball.agent"]], done)
+ expect_identical(seen$extra[["m.relates_to"]],
+ list(rel_type = "m.replace", event_id = "$orig"))
+})
+
+# The relation of an encrypted edit has to be readable outside the
+# ciphertext, or the server cannot aggregate the edit and a client that
+# reads relations off the envelope shows a new message. chat.api hands
+# it to mx.client inside the content, and mx.client's envelope copies
+# it out; pinned here, since chat.api's encrypted edits rely on that.
+if (requireNamespace("mx.client", quietly = TRUE) &&
+ requireNamespace("mx.crypto", quietly = TRUE) &&
+ utils::packageVersion("mx.client") >= "0.3.0")
+local({
+ account <- mx.crypto::mxc_account_new()
+ curve <- mx.crypto::mxc_account_identity_keys(account)$curve25519
+ rel <- list(rel_type = "m.replace", event_id = "$orig")
+ env <- mx.client::mx_crypto_encrypt_event(
+ mx.crypto::mxc_megolm_outbound_new(),
+ list(msgtype = "m.notice", body = "* x", `m.relates_to` = rel,
+ `m.new_content` = list(msgtype = "m.notice", body = "x",
+ ai.cornball.agent = done)),
+ "!secret:ex", curve, "DEV1")
+ expect_identical(env[["m.relates_to"]], rel)
+ # The replacement and its keys are in the ciphertext only.
+ expect_null(env[["m.new_content"]])
+})
+
+# Received, a cleartext message carries its event's whole content in
+# raw$content: the extractor's record keeps 6 fields of it, and a
+# sender's own keys are none of them.
+local({
+ answer <- list(v = 1L, kind = "approval_response", approval_id = "a1",
+ option_id = "allow")
+ cl <- seam_client(recs = list(rec("$1", body = "/approve a1")),
+ sync = wrap_sync(list(ev("$1", body = "/approve a1",
+ content = list(ai.cornball.agent = answer)))))
+ m <- chat_poll(cl)$messages[[1L]]
+ expect_identical(m$raw$content[["ai.cornball.agent"]], answer)
+ expect_identical(m$raw$content$body, "/approve a1")
+ # The record's own fields stay.
+ expect_identical(m$raw$event_id, "$1")
+ expect_identical(m$raw$msgtype, "m.text")
+ # An event the sync does not carry gets no content, not an error.
+ cl <- seam_client(recs = list(rec("$2")), sync = wrap_sync(list()))
+ expect_null(chat_poll(cl)$messages[[1L]]$raw$content)
+ # A picture is a message too: its raw has the event's content, and
+ # the media record's own fields stay.
+ cl <- seam_client(sync = wrap_sync(list(ev("$img", body = "cat.png",
+ msgtype = "m.image",
+ content = list(url = "mxc://ex/abc",
+ ai.cornball.agent = answer)))),
+ .extract_media = function(sync, self_id) {
+ list(media_rec("$img", body = "cat.png"))
+ })
+ m <- chat_poll(cl)$messages[[1L]]
+ expect_identical(m$raw$content[["ai.cornball.agent"]], answer)
+ expect_identical(m$raw$content$msgtype, "m.image")
+ expect_identical(m$raw$url, "mxc://ex/abc")
+ expect_null(m$attachments[[1L]]$raw$content)
+})
+# A decrypted message has the decrypted payload's content, which
+# mx.client keeps, so raw$content reads the same way.
+local({
+ answer <- list(v = 1L, kind = "approval_response", approval_id = "a1",
+ option_id = "allow")
+ d <- dec_rec("$e1", body = "/approve a1")
+ d$content <- list(msgtype = "m.text", body = "/approve a1",
+ ai.cornball.agent = answer)
+ f <- fake_crypto(decrypted = list(d))
+ cl <- seam_client(mx = fake_mx(user_id = "@e2ee-recv:ex"), e2ee = TRUE,
+ .crypto = f$ops)
+ m <- chat_poll(cl)$messages[[1L]]
+ expect_true(m$encrypted)
+ expect_identical(m$raw$content[["ai.cornball.agent"]], answer)
+})
diff --git a/inst/tinytest/test_matrix_mxclient.R b/inst/tinytest/test_matrix_mxclient.R
index af67a97..6b38441 100644
--- a/inst/tinytest/test_matrix_mxclient.R
+++ b/inst/tinytest/test_matrix_mxclient.R
@@ -202,10 +202,11 @@ expect_false("a notice" %in% vapply(got$messages, `[[`, "", "body"))
# The record shape the adapter reads. The wire's content$m.relates_to
# arrives as the record's `relates_to`, so nothing here looks for the
-# wire name.
+# wire name. The event's whole content rides beside the record, as
+# raw$content, which the extractor's fields do not include.
expect_true(all(c("room_id", "event_id", "sender", "is_self", "body",
"msgtype", "mentions") %in% names(m$raw)))
-expect_false("content" %in% names(m$raw))
+expect_identical(m$raw$content$body, m$body)
expect_null(m$raw[["m.relates_to"]])
# An unthreaded message has no thread, and NULL is the answer.
expect_null(m$thread)
diff --git a/man/chat_edit.Rd b/man/chat_edit.Rd
index ad35657..1ca59bd 100644
--- a/man/chat_edit.Rd
+++ b/man/chat_edit.Rd
@@ -11,6 +11,7 @@ chat_edit(
markup = c("plain", "markdown"),
rich = NULL,
kind = "message",
+ content = NULL,
...
)
}
@@ -41,6 +42,13 @@ the message was sent as: Matrix carries the msgtype inside the
replacement content, so editing an \code{m.notice} without saying so
turns it into an ordinary message.}
+\item{content}{Keys of the caller's own for the replacement, as
+\code{\link{chat_send}}. Matrix puts them in \code{m.new_content},
+beside the replacement text, and in the fallback copy around it, as
+it does the formatted text. Like the text, they replace the
+original's: a key the edit does not repeat is gone from the edited
+message.}
+
\item{...}{Adapter-specific options.}
}
\value{
diff --git a/man/chat_matrix.Rd b/man/chat_matrix.Rd
index 4ecf1da..4d64ac2 100644
--- a/man/chat_matrix.Rd
+++ b/man/chat_matrix.Rd
@@ -217,7 +217,8 @@ Leave NULL in production.}
the edit path. Leave NULL in production.}
\item{.rich}{Testing seam: replacement for \code{mx.api::mx_send} on
-the rich-send path. Leave NULL in production.}
+the rich-send path, and on the path of a send with \code{content}
+outside an encrypted room. Leave NULL in production.}
\item{.avatar}{Testing seam: replacement for the upload-then-set
pair behind \code{chat_set_identity(avatar =)}
diff --git a/man/chat_message.Rd b/man/chat_message.Rd
index 4c0d334..36d19b4 100644
--- a/man/chat_message.Rd
+++ b/man/chat_message.Rd
@@ -59,7 +59,12 @@ substring matching misses rich mentions that carry no plain text.}
exactly as the transport layer handed it over. Shape is
adapter-specific and may already be normalized by the transport
package (Matrix hands over an extracted record, not the timeline
-event), so it is an escape hatch, not a guarantee of completeness.}
+event), so it is an escape hatch, not a guarantee of completeness.
+One part is promised: a Matrix message, cleartext or decrypted,
+carries its event's whole content in \code{raw$content}, with any
+keys a sender added of its own (\code{\link{chat_send}}'s
+\code{content}), and the loopback adapter records those keys
+there.}
\item{encrypted}{Logical: did this message arrive end-to-end
encrypted? FALSE on transports without E2EE and on cleartext
diff --git a/man/chat_send.Rd b/man/chat_send.Rd
index 39cf511..f8eb52b 100644
--- a/man/chat_send.Rd
+++ b/man/chat_send.Rd
@@ -15,6 +15,7 @@ chat_send(
kind = "message",
notify = TRUE,
rich = NULL,
+ content = NULL,
...
)
}
@@ -62,6 +63,23 @@ Ignored rather than refused where unsupported, on
the markup is decoration, so losing it costs presentation and
nothing else.}
+\item{content}{Keys of the caller's own for the message's content, as
+a named list, or NULL. Matrix adds them to the \code{m.room.message}
+content beside \code{body} and \code{msgtype}, inside the ciphertext
+in an encrypted room, so a consumer can carry data its own client
+reads and every other client ignores, under a namespaced key such
+as \code{"ai.cornball.agent"}. A received message carries its
+content in \code{raw$content}, and the loopback adapter records
+these keys there too; the other adapters ignore them, as they
+ignore \code{rich}, so \code{text} has to stand on its own.
+
+A key chat.api writes itself is refused: \code{body},
+\code{msgtype}, \code{format}, \code{formatted_body},
+\code{m.relates_to}, \code{m.mentions} and \code{m.new_content}.
+\code{text}, \code{kind}, \code{rich}, \code{thread} and the
+\code{mentions} option set those. With \code{files}, the keys go on
+the text's event, not on the attachments'.}
+
\item{...}{Adapter-specific options.}
}
\value{