Skip to content

Carry a caller's own content keys on send, edit and receive - #32

Merged
TroyHernandez merged 4 commits into
mainfrom
content-keys
Nov 18, 2026
Merged

TroyHernandez merged 4 commits into
mainfrom
content-keys

Conversation

@TroyHernandez

@TroyHernandez TroyHernandez commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

A consumer can now carry data of its own in a Matrix message's content, under a namespaced key that its own client reads and every other client ignores. A relay that posts an agent's tool calls as notices needs it: the app renders a card from the key, and a stock client shows the plain-text body. Before this, rich could carry an HTML fragment and nothing else, and a received cleartext message lost every content key the text extractor does not keep.

The change

  • chat_send(..., content = NULL) and chat_edit(..., content = NULL) on the contract. content is a named list of keys for the message's own content.
  • Matrix, cleartext: the keys go beside body and msgtype. mx_send_text() takes no extra content, so a send with keys goes through mx.api::mx_send(), as a rich send already does. It still builds what mx_send_text() would have: the HTML from markdown with mention pills, m.mentions and the thread relation. With a caller's rich fragment, the fragment is sent as given and m.mentions still goes in, since the notification depends on it.
  • Matrix, encrypted: the keys go to crypto_ops$send() as extra, which the Megolm path encrypts with the rest. extra is named only when there are keys, so a crypto seam without the argument still sends.
  • An edit puts the keys in m.new_content, beside the replacement text, and in the fallback copy around it, on both paths, as chat_edit() already does with formatted text. A client that shows the edit event itself, with its original out of view, still has them. They replace the original's, as the text does. (The fallback copy came in 1268016, at the app's request.)
  • A key chat.api writes itself is refused before anything is uploaded or sent: body, msgtype, format, formatted_body, m.relates_to, m.mentions, m.new_content. Each has its own argument. An empty list means no keys.
  • Received: a cleartext message's raw gains raw$content, the event's whole content, looked up from the sync by event id the way the timestamps already are. mx_extract_text_events() keeps 6 fields of the content and drops the rest. A decrypted record already carries content (mx.client 0.3.0), and history's raw is the event itself, so raw$content reads the same on all 3 paths. chat_message()'s documentation now promises it.
  • The loopback adapter records the keys as raw$content, so a consumer's tests read them as its code does against a homeserver. Slack, Telegram and IRC take the argument and ignore it, as they ignore rich.
  • matrix_thread_relation() holds the threaded-reply relation that matrix_send_rich() built inline, now shared with the new path. Its output is unchanged.

Behavior change

  • A cleartext Matrix message's raw has one more field, content. test_matrix_mxclient.R asserted its absence, and now asserts the new shape.
  • Nothing else changes for a caller that passes no content.

Not changed

  • An encrypted edit's relation already reaches the cleartext envelope: mx.client 0.3.0's mx_crypto_encrypt_event() copies m.relates_to out of the ciphertext. A new test pins it.
  • chat_send() still refuses a thread in an encrypted room. Its comment says the encrypted path has nowhere to put a relation, which is no longer so: extra can carry one, and mx.client lifts it to the envelope. Lifting the refusal is a separate change.

Checked

  • test_matrix.R: 571 results.
    • Cleartext send: keys, msgtype, no HTML or mentions when plain, then mentions, a thread, markdown and a caller's fragment with keys, and the ordinary path untouched without keys or with an empty list.
    • The refusals.
    • Encrypted send: keys as extra, and no extra without keys.
    • Edits with keys on both paths, in m.new_content and the fallback; without keys, neither has any.
    • The envelope's relation.
    • Received keys on the cleartext and decrypted paths, and no content for an event the sync lacks.
  • test_contract.R: 312 results, including the loopback's send, edit, refusals, and the other adapters' signatures.
  • Against main's code the new tests fail 26 assertions in test_matrix.R and 10 in test_contract.R. Against 124bf19, the 2 fallback assertions fail.
  • Every test file from a scratch library and an empty home, at 124bf19: 1,533 results, 0 failed, nothing left in the home. At 1268016, test_matrix.R and test_contract.R, the only files it touches: 571 and 312, 0 failed.
  • R CMD check --as-cran on the built tarball at 124bf19: Status OK. It covers the S3 method signatures, which all take content. It ran without the suggested telegram package, which this machine lacks.
  • Every added line in R/ is as rformat writes it.

The version bump follows as its own commit after review. #31 also bumps to 0.2.0.1, so whichever merges second takes the next number.

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.
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.
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.
@TroyHernandez
TroyHernandez merged commit 16c72a8 into main Nov 18, 2026
2 checks passed
@TroyHernandez
TroyHernandez deleted the content-keys branch November 18, 2026 23:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant