From 124bf198cc5982f0ffc4244b0d867a6e3497e9f8 Mon Sep 17 00:00:00 2001 From: TroyHernandez Date: Wed, 18 Nov 2026 11:52:29 -0600 Subject: [PATCH 1/4] Carry a caller's own content keys on send, edit and receive chat_send() and chat_edit() take content, a named list of keys for the message's own content, such as a namespaced "ai.cornball.agent" that one client reads and the rest ignore. Matrix adds them beside body and msgtype, in the cleartext path through mx_send() (as rich goes, since mx_send_text() takes no extra content, with the mentions, thread and markdown it would have built) and in the encrypted path as extra content inside the ciphertext. An edit puts them in m.new_content. A key chat.api writes itself is refused. Received, a cleartext message's raw now carries the event's whole content as raw$content, looked up from the sync by event id as the times are: mx_extract_text_events() keeps 6 fields and drops the rest. A decrypted record has content already, and history's raw is the event, so raw$content reads the same on all 3. The loopback adapter records the keys there too; the other adapters take the argument and ignore it, as they ignore rich. --- R/contract.R | 60 ++++++- R/irc.R | 2 +- R/loopback.R | 23 ++- R/matrix.R | 120 ++++++++++++-- R/slack.R | 6 +- R/telegram.R | 5 +- inst/tinytest/test_contract.R | 49 ++++++ inst/tinytest/test_matrix.R | 225 +++++++++++++++++++++++++++ inst/tinytest/test_matrix_mxclient.R | 5 +- man/chat_edit.Rd | 7 + man/chat_matrix.Rd | 3 +- man/chat_message.Rd | 7 +- man/chat_send.Rd | 18 +++ 13 files changed, 499 insertions(+), 31 deletions(-) diff --git a/R/contract.R b/R/contract.R index da8c1d2..e0f85ee 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,11 @@ 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. 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 +1259,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..83a618c 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 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 three. +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 @@ -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,10 @@ 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 belong to the replacement, which is what a client + # that understands edits shows; the fallback copy around it does not + # repeat them. Encrypted, they ride inside the ciphertext with it. + 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)) { @@ -1251,19 +1304,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..63fe690 100644 --- a/inst/tinytest/test_matrix.R +++ b/inst/tinytest/test_matrix.R @@ -2382,3 +2382,228 @@ 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 +# the fallback copy around it does not repeat 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_null(seen$extra[["ai.cornball.agent"]]) + expect_identical(seen$body, "* [tool] ls (completed)") + # Without keys the replacement has none, as before. + chat_edit(cl, "!a:ex", "$o", "x", kind = "notice") + expect_identical(names(seen$extra[["m.new_content"]]), c("msgtype", "body")) +}) +# ... 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_null(seen$extra[["ai.cornball.agent"]]) + 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 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..a69adf5 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,12 @@ 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. 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{ From 126801620488c12ee73fbb0244b3ed40ce770c92 Mon Sep 17 00:00:00 2001 From: TroyHernandez Date: Wed, 18 Nov 2026 12:13:12 -0600 Subject: [PATCH 2/4] Put an edit's content keys in its fallback copy too The keys went in m.new_content only. A client showing the edit event itself, its original out of view, saw the fallback without them. They now go in both, as chat_edit() already does with formatted text. Asked for by the app that reads the keys. --- R/contract.R | 3 ++- R/matrix.R | 9 ++++++--- inst/tinytest/test_matrix.R | 11 +++++++---- man/chat_edit.Rd | 3 ++- 4 files changed, 17 insertions(+), 9 deletions(-) diff --git a/R/contract.R b/R/contract.R index e0f85ee..bb23f35 100644 --- a/R/contract.R +++ b/R/contract.R @@ -1237,7 +1237,8 @@ chat_relogin.default <- function(client, ...) { #' 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. Like the text, they replace the +#' 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. diff --git a/R/matrix.R b/R/matrix.R index 83a618c..b64a8fa 100644 --- a/R/matrix.R +++ b/R/matrix.R @@ -1255,9 +1255,11 @@ 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 belong to the replacement, which is what a client - # that understands edits shows; the fallback copy around it does not - # repeat them. Encrypted, they ride inside the ciphertext with it. + # 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)) @@ -1269,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 diff --git a/inst/tinytest/test_matrix.R b/inst/tinytest/test_matrix.R index 63fe690..48d7a17 100644 --- a/inst/tinytest/test_matrix.R +++ b/inst/tinytest/test_matrix.R @@ -2507,7 +2507,8 @@ local({ }) # An edit's keys go in m.new_content, which is the edited message, and -# the fallback copy around it does not repeat them. Cleartext ... +# 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 @@ -2521,11 +2522,13 @@ local({ 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_null(seen$extra[["ai.cornball.agent"]]) + expect_identical(seen$extra[["ai.cornball.agent"]], done) expect_identical(seen$body, "* [tool] ls (completed)") - # Without keys the replacement has none, as before. + # 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({ @@ -2545,7 +2548,7 @@ local({ 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_null(seen$extra[["ai.cornball.agent"]]) + expect_identical(seen$extra[["ai.cornball.agent"]], done) expect_identical(seen$extra[["m.relates_to"]], list(rel_type = "m.replace", event_id = "$orig")) }) diff --git a/man/chat_edit.Rd b/man/chat_edit.Rd index a69adf5..1ca59bd 100644 --- a/man/chat_edit.Rd +++ b/man/chat_edit.Rd @@ -44,7 +44,8 @@ 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. Like the text, they replace the +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.} From cf976954381cd4bff8357dfc1aef34b33ae0f119 Mon Sep 17 00:00:00 2001 From: TroyHernandez Date: Wed, 18 Nov 2026 15:10:32 -0600 Subject: [PATCH 3/4] Carry a picture's event content in its raw too chat_message()'s raw now promises the event's whole content in raw$content for a Matrix message. A picture reached chat_poll() with the media record alone as its raw. --- R/matrix.R | 10 +++++----- inst/tinytest/test_matrix.R | 14 ++++++++++++++ 2 files changed, 19 insertions(+), 5 deletions(-) diff --git a/R/matrix.R b/R/matrix.R index b64a8fa..80955e0 100644 --- a/R/matrix.R +++ b/R/matrix.R @@ -294,10 +294,10 @@ matrix_event_contents <- function(sync) { out } -# A cleartext record 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 three. +# 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)]] @@ -666,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, diff --git a/inst/tinytest/test_matrix.R b/inst/tinytest/test_matrix.R index 48d7a17..e79b2be 100644 --- a/inst/tinytest/test_matrix.R +++ b/inst/tinytest/test_matrix.R @@ -2594,6 +2594,20 @@ local({ # 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. From 6c9ed9ac6d73a434d8f3c2b63e46e15f64657bd1 Mon Sep 17 00:00:00 2001 From: TroyHernandez Date: Wed, 18 Nov 2026 17:22:59 -0600 Subject: [PATCH 4/4] Bump version to 0.2.0.1 --- DESCRIPTION | 4 ++-- NEWS.md | 12 ++++++++++++ 2 files changed, 14 insertions(+), 2 deletions(-) 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