Skip to content

Messages carry files: upload with a send, read back through the message - #4889

Merged
trissim merged 9 commits into
mainfrom
fork-bus-attachments
Nov 18, 2026
Merged

trissim merged 9 commits into
mainfrom
fork-bus-attachments

Conversation

@trissim

@trissim trissim commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

What

Messages can carry files. Toad's file picker (Android SAF, desktop dialog or path search, TUI pickers) sends them, and recipients read them back through the message.

  • messaging/message_files.py holds three pieces:
    • FileUpload: name, MIME type and base64 data, validated like ImageInput, 8 MiB per message in all.
    • MessageFile: message reference, position, name, MIME type, size and SHA-256.
    • MessageFiles: a carried DurableStore (message_files.sqlite3) holding bytes once per SHA-256 and one row per message file.
  • comms_user_send (UI) and comms_send (agents) take files through one SendsFiles mixin. The list is left off the wire when empty, so a file-free send is the request an older Core decodes.
  • Two new reads:
    • comms_message_files(conversation, participant, messages) lists a page's files.
    • comms_message_file(conversation, participant, message, position) returns one file's bytes.

Why Message is unchanged

The field codec refuses unknown fields, so a file field on Message would crash every installed client: the phone APK and the installed TUI. Files are rows beside the bus keyed by MessageReference. Every page, inbox and history an older reader decodes is byte-for-byte what it decoded before.

Visibility: one rule, the message's own

A file is read only through its message. There is no second check: ServedMessageFileRead.readable asks the owner that decides which messages a conversation read returns. It builds the conversation's HistoryView for the caller's viewer exactly as comms_history does (CommandTarget.history_view(caller.history_viewer(participant), ...)), captures its MessageDisplayScope, and refuses any named message whose scope.includes(message) is false. A message missing from the bus is refused the same way. Both reads, the list and the bytes, go through it. A DM's files are therefore readable only as one of its participants, and a channel's by whoever reads the channel. participant is named the way comms_history's is, so file reads are exactly as open as history reads, no more. The digest only deduplicates storage and grants no access.

Refusal test: tests/test_message_files.py::test_a_reader_outside_the_conversation_is_refused_its_files. An outsider is refused the list and the bytes of a DM it is not in, including through a channel it reads; a missing position is refused; and a channel message's file is readable by a non-sender.

Agents see the files

  • The native delivered segment (DeliveredMessageSegment) and a local CLI bridge's frame derive one line per file from the store, naming the read that returns it. Each route keeps its own frame class (incoming_frame); the route answers only which files it names (HarnessDeliveryRecords.files_of).
  • A remote watch frames the wire message on the session's machine, whose installed decoder knows no files. So PushedTranscript.files_of names none, and the watch client frames the body alone (ClaudeMonitorFrame.of_wire). Naming files there needs a watch protocol change and its own rollout.

Limits derived from one owner

MAX_SEND_REQUEST_BYTES derives from the file cap. It sets the connector's client_max_size, which aiohttp otherwise defaults to 1 MiB and which would refuse any file over about 750 KB, and the native tool socket's line limit.

Evidence

Head b80128b, base 4d0206b (the merge base).

  • New tests (tests/test_message_files.py), 6 of 6 pass:
    • a 2 MiB upload over the connector (above aiohttp's default 1 MiB body) round-trips to identical bytes as the recipient;
    • an agent send carries files, and a send without files encodes no files key;
    • the size limit, and the name, MIME type and base64 refusals (including ., .., ../escape and a backslash), all refuse before anything is written;
    • the visibility refusal, named above;
    • a page with files encodes no file key and decodes unchanged;
    • the store is a declared DurableFile, ReconciledFile.existing_in lists it, and carry_schema keeps its rows (the carry test).
  • Delivery-line tests:
    • tests/test_coordinated_runtime.py::test_delivered_frame_names_each_file_with_the_read_that_returns_it;
    • tests/test_codex_delivery_reporting.py::test_a_bridge_frames_a_message_with_its_files_and_refuses_an_echo_without_them.
  • Old client. tools/old_reader_decodes_files.py runs the installed runtime's own interpreter, $(head -1 ~/.local/bin/toad), with agent_comms from its site-packages and no PYTHONPATH. It decodes a DM page, a channel history, an inbox and a file-free send request, all carrying file-bearing messages:
    [".../runtimes/core-cfcfedb67-lock-b11dca9f9c11a5cc/lib/python3.14/site-packages/agent_comms/__init__.py", ["a DM with a file", "a DM without one"], ["a channel message with a file"], ["a DM with a file", "a DM without one"], "no files"]
    older reader decoded every record
    
  • The first targeted batch (137 test files naming each changed declaration, at 38241ed): 46 failed.
    • 42 fail identically on clean main at the merge base 4d0206b, run in a separate worktree (42 failed there too). They are deselected below.
    • The other 4, rerun serially:
      • test_acp_selected_write_plan::test_second_pid_public_acp_owner_ipc_preplan: pass.
      • test_concurrency::TestConcurrentWire::test_concurrent_claims_allocate_unique_names: pass.
      • test_forks::test_registered_fork_sends_parent_problem_with_fork_actor: pass.
      • test_monitor_delivery::test_wrong_complete_parts_stay_pending_without_claiming_delivery: failed on this branch (IncomingFrame missing files, from a fixture building a frame by hand). Fixed: the fixture frames through the route. It passes.
  • Final runs, one at a time, at -n 2:
    • The 27 test files that name a changed declaration (frames, bridges, wake segments, queued input, message files), on b0026f9: 314 passed, 1 failed, 8 skipped. The failure, test_private_idle_drain.py::test_observation_waits_for_the_held_coordinator_snapshot, fails the same way on base 4d0206b (assert not any(task.done() ...)). It is blocked by this host's systemd user manager outage since 04:54 and will be rerun once that is back. Its path (input_drain._observe_private_revision) does not reach this change.
    • The last commit changes only read_export. Its tests on b80128b (test_claude_turn, test_monitor_delivery, test_inbox_watch, test_codex_delivery_reporting, test_message_files): 139 passed, 0 failed.
  • NRA debt gate (tools/nra_gate.py, base 4d0206b, head b80128b):
    • --root src: exit 0. 17 paths, nothing introduced, nothing grew. Eight type errors that exist on base are gone: inbox_watch −1, shared −1, connector −1, send −1, served −2, and toad's focus_burst_scenario client check −2.
    • --root tools: exit 0, nothing introduced.

Rollout

  1. Merge this PR.
  2. Install the bus.
  3. Merge Attach files to bus messages: Android picker, desktop dialog or path search, TUI pickers, history chips toad#2123.
  4. Build the APK.

A toad built from that branch needs this change on the bus first: it reads a page's files through comms_message_files.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3

trissim and others added 9 commits November 18, 2026 02:15
…ad through their message

A send (comms_user_send from a UI, comms_send from an agent) may carry files, each
a name, MIME type and base64 data, 8 MiB per message in all. The list is left off
the wire when empty, so a send with no files is the request an older Core decodes.

MessageFiles is a carried DurableStore beside the bus: bytes once per SHA-256 and
one row per message file keyed by the message's reference. Message is unchanged,
so every page and message an older reader decodes is the one it decoded before
(tools/old_reader_decodes_files.py runs the installed runtime's decoder over one).

comms_message_files lists a page's files and comms_message_file returns one file's
bytes. Both name the conversation and participant the way comms_history does, and
refuse any message that conversation's display scope does not include, so a file
is read only by whoever may read its message; the digest is storage, not access.

An agent learns of a message's files from the line its delivery derives: the
native delivered segment and a local CLI bridge's frame each name every file with
the read that returns it. A remote watch frames the wire message on the session's
machine, whose installed decoder knows no files, so both ends of that route frame
the body alone.

The connector's request body limit and the native tool socket's line limit derive
from the file limit, so a send at the limit is accepted on either route.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3
…bridge

The old-reader proof tool carries no string-keyed records and types its reads.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3
…tes files

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3
…rd both check it

A record naming a directory, only dots, a backslash or NUL never decodes, so a
reader keeping a file under its name needs no check of its own.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3
…lass

frame() widened every route's frame to IncomingFrame, so the monitor routes lost
their frame's type. Each route builds its frame from incoming_frame as before and
answers files_of; a remote watch names none. A read export skips a message the
bus no longer holds, as the other confirmation loops do.

The wake frame no longer carries a copy of the batch's files: input_segments
takes them from the reader. Comms declares messaging as the Messaging it holds.
The file name rule is two checks, and the touched lines and imports are formatted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3
…onfirms nothing

messages() returns the held messages at the given references; message() derives
from it. read_export loops over what is held instead of testing for None.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3
@github-actions

Copy link
Copy Markdown

debt-tools at b80128b failed without a verdict line; the last lines of its stderr:

concurrent.futures.process._RemoteTraceback:
"""
Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.14.10/x64/lib/python3.14/concurrent/futures/process.py", line 255, in _process_worker
    r = call_item.fn(*call_item.args, **call_item.kwargs)
  File "/home/runner/work/agent-comms/agent-comms/src/agent_comms/execution/child_process.py", line 2735, in _work
    return work()
  File "/home/runner/work/agent-comms/agent-comms/tools/agent_comms_project.py", line 300, in findings
    output = cls.checker_output(result, f"{client.name} at {ref}")
  File "/home/runner/work/_temp/checker-venv/lib/python3.14/site-packages/nominal_refactor_advisor/audit/gate.py", line 165, in checker_output
    raise ValueError(f"{cls.__name__} could not check {subject}: {output}")
ValueError: ClientTypeErrors could not check batrachian-toad at a73a3a12e3f091a283b3a9dfee7f8ef38d131450: tools/qt_drive.py: error: Source file found twice under different module names: "tools.qt_drive" and "qt_drive"
tools/qt_drive.py: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#mapping-file-paths-to-modules for more info
tools/qt_drive.py: note: Common resolutions include:
tools/qt_drive.py: note:     a) adding `__init__.py` somewhere,
tools/qt_drive.py: note:     b) using `--explicit-package-bases` or adjusting `MYPYPATH`
"""
The above exception was the direct cause of the following exception:
Traceback (most recent call last):
  File "/home/runner/work/agent-comms/agent-comms/tools/nra_gate.py", line 15, in <module>
    raise SystemExit(audit.gate.main(project, arguments))
                     ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/_temp/checker-venv/lib/python3.14/site-packages/nominal_refactor_advisor/audit/gate.py", line 1161, in main
    return gate(project, args.base, args.head, args.root, args.workers)
  File "/home/runner/work/_temp/checker-venv/lib/python3.14/site-packages/nominal_refactor_advisor/audit/gate.py", line 1134, in gate
    result = compare(repo, base, head, root, workers, Compared.members())
  File "/home/runner/work/_temp/checker-venv/lib/python3.14/site-packages/nominal_refactor_advisor/audit/gate.py", line 1101, in compare
    results[measure] = [part.result() for part in parts[measure]]
                        ~~~~~~~~~~~^^
  File "/opt/hostedtoolcache/Python/3.14.10/x64/lib/python3.14/concurrent/futures/_base.py", line 447, in result
    return self.__get_result()
           ~~~~~~~~~~~~~~~~~^^
  File "/opt/hostedtoolcache/Python/3.14.10/x64/lib/python3.14/concurrent/futures/_base.py", line 396, in __get_result
    raise self._exception
ValueError: ClientTypeErrors could not check batrachian-toad at a73a3a12e3f091a283b3a9dfee7f8ef38d131450: tools/qt_drive.py: error: Source file found twice under different module names: "tools.qt_drive" and "qt_drive"
tools/qt_drive.py: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#mapping-file-paths-to-modules for more info
tools/qt_drive.py: note: Common resolutions include:
tools/qt_drive.py: note:     a) adding `__init__.py` somewhere,
tools/qt_drive.py: note:     b) using `--explicit-package-bases` or adjusting `MYPYPATH`

@github-actions

Copy link
Copy Markdown

debt-src at b80128b failed without a verdict line; the last lines of its stderr:

concurrent.futures.process._RemoteTraceback:
"""
Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.14.10/x64/lib/python3.14/concurrent/futures/process.py", line 255, in _process_worker
    r = call_item.fn(*call_item.args, **call_item.kwargs)
  File "/home/runner/work/agent-comms/agent-comms/src/agent_comms/execution/child_process.py", line 2735, in _work
    return work()
  File "/home/runner/work/agent-comms/agent-comms/tools/agent_comms_project.py", line 300, in findings
    output = cls.checker_output(result, f"{client.name} at {ref}")
  File "/home/runner/work/_temp/checker-venv/lib/python3.14/site-packages/nominal_refactor_advisor/audit/gate.py", line 165, in checker_output
    raise ValueError(f"{cls.__name__} could not check {subject}: {output}")
ValueError: ClientTypeErrors could not check batrachian-toad at a73a3a12e3f091a283b3a9dfee7f8ef38d131450: tools/qt_drive.py: error: Source file found twice under different module names: "tools.qt_drive" and "qt_drive"
tools/qt_drive.py: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#mapping-file-paths-to-modules for more info
tools/qt_drive.py: note: Common resolutions include:
tools/qt_drive.py: note:     a) adding `__init__.py` somewhere,
tools/qt_drive.py: note:     b) using `--explicit-package-bases` or adjusting `MYPYPATH`
"""
The above exception was the direct cause of the following exception:
Traceback (most recent call last):
  File "/home/runner/work/agent-comms/agent-comms/tools/nra_gate.py", line 15, in <module>
    raise SystemExit(audit.gate.main(project, arguments))
                     ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/_temp/checker-venv/lib/python3.14/site-packages/nominal_refactor_advisor/audit/gate.py", line 1161, in main
    return gate(project, args.base, args.head, args.root, args.workers)
  File "/home/runner/work/_temp/checker-venv/lib/python3.14/site-packages/nominal_refactor_advisor/audit/gate.py", line 1134, in gate
    result = compare(repo, base, head, root, workers, Compared.members())
  File "/home/runner/work/_temp/checker-venv/lib/python3.14/site-packages/nominal_refactor_advisor/audit/gate.py", line 1101, in compare
    results[measure] = [part.result() for part in parts[measure]]
                        ~~~~~~~~~~~^^
  File "/opt/hostedtoolcache/Python/3.14.10/x64/lib/python3.14/concurrent/futures/_base.py", line 447, in result
    return self.__get_result()
           ~~~~~~~~~~~~~~~~~^^
  File "/opt/hostedtoolcache/Python/3.14.10/x64/lib/python3.14/concurrent/futures/_base.py", line 396, in __get_result
    raise self._exception
ValueError: ClientTypeErrors could not check batrachian-toad at a73a3a12e3f091a283b3a9dfee7f8ef38d131450: tools/qt_drive.py: error: Source file found twice under different module names: "tools.qt_drive" and "qt_drive"
tools/qt_drive.py: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#mapping-file-paths-to-modules for more info
tools/qt_drive.py: note: Common resolutions include:
tools/qt_drive.py: note:     a) adding `__init__.py` somewhere,
tools/qt_drive.py: note:     b) using `--explicit-package-bases` or adjusting `MYPYPATH`

@trissim
trissim marked this pull request as ready for review November 18, 2026 15:53
@trissim
trissim merged commit 11a019b into main Nov 18, 2026
8 of 10 checks passed
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