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{