DocsSource

Messaging

Sending a message

Opening send, writing bytes, and closing it posts exactly one message — every byte written between open() and close() is buffered and posted as a single unit on close (not split on newlines). This means:

  • echo "hi" > send and printf "hi\n" > send each post one message, since the shell opens and closes send once per invocation — the ordinary case is unaffected.
  • A bot that opens send once and writes several lines (a build summary, a short stack trace) posts it as one message with its internal newlines intact, rather than fragmenting into one message per line.
  • A message is capped at 64 KiB. A write that would push the buffered message past that cap is refused with EFBIG, and the entire buffered message is discarded rather than posted truncated. Bulk payloads belong on file/send (see file-transfer.md), which streams without ever buffering a whole payload.
  • A message that is empty after sanitization (an echo "", or a block of nothing but blank lines) is silently dropped rather than posted as a blank line.

Sanitization

Message text is sanitized at ingest, before it's ever stored or fanned out:

  • ANSI escape sequences (ESC and the CSI/OSC sequence that follows it) are stripped entirely — this closes the door on a message injecting terminal escape tricks into someone else's feed. Color in stream.human is applied server-side only, from the message's from field, never carried in the payload itself.
  • Other C0 control characters and DEL are stripped.
  • Tabs are preserved.
  • For a multi-line message, sanitization runs per line but the newlines between lines are preserved, so a multi-line block keeps its structure. Trailing newlines are trimmed.

The message shape

Every message (and every channel event — file transfers, voice/radio/tv join and leave, drop notices) is one JSON object with these fields:

{"type":"message","channel":"everyone","from":"wren","timestamp":"2026-01-15T20:04:11Z","data":"hi tomo"}
Field Meaning
type message, dropped, recv, file, timeout, voice_join/voice_leave, radio_join/radio_leave, tv_join/tv_leave
channel The channel name (e.g. tomo,wren), never a server path
from The sender's resolved chat username
timestamp UTC, set by the server — never trusted from the client
data The message body, or a human-readable description for an event
n Only present on a dropped marker: how many messages were dropped

Each event type exists so a bot can filter the stream by type alone, rather than parsing a description string — a member running both a radio and a tv broadcast at once gets distinguishable radio_join/tv_join events rather than one ambiguous "broadcast started."

The three feeds

All three are backed by the same underlying pubsub: each open() registers its own subscription with its own bounded, drop-oldest ring buffer, so one slow reader only ever drops its own messages — never anyone else's, and never blocks the writer. When a reader falls behind, the next thing it reads is a compact drop marker: {"type":"dropped","n":k}.

Feed Format Use
stream.bot One compact JSON object per line (the shape above) Scripts and bots
stream.human Plain text, ANSI-colorized, markdown rendered Humans at a terminal — no jq needed
stream.llm Plain text, no ANSI, markdown left as raw source An LLM/agent reader that parses markdown itself and gains nothing from server-side styling

stream.human/stream.llm render a line as:

15:04:05 wren hi tomo

(timestamp dimmed, sender colored by a stable per-username hash in stream.human; both plain in stream.llm.) A multi-line body puts the header on its own line above the body instead of squeezing everything onto one line. Non-message events render as an inline notice instead of a header+body line, e.g.:

-- wren started a radio broadcast --

A file event brackets its data as [filename] and deliberately bypasses markdown rendering — a filename isn't prose, and running metacharacters common in filenames (my_notes.txt, a*.log) through markdown could mangle or silently drop characters.

Markdown (in stream.human only)

stream.human renders a small, hand-rolled subset of CommonMark — no third-party dependency, and no headers/lists/tables/nested blocks, since none of those make sense inside a single chat message:

Syntax Renders as
`code` Inline code
```lang … ``` A fenced code block, set apart with dim ┄┄ dividers
**bold** / __bold__ Bold
*italic* / _italic_ Italic
[text](url) An underlined label followed by a dimmed URL
A bare https://… Auto-linked (underlined), trailing sentence punctuation excluded
:wave:, :tada:, :rocket:, … The matching emoji glyph; an unrecognized shortcode is left as literal text

Emphasis rules are careful about false positives: 2 * 3 and * item aren't read as emphasis (whitespace-flanked asterisks are excluded), and snake_case/my_notes_2024 aren't read as italic (underscore spans require a word boundary). Code spans and links are protected from having their contents re-interpreted as emphasis or emoji shortcodes.

Channel control (ctl/)

ctl/ is a directory of per-key settings, not a command file: each knob is its own rw entry — read it to see the current value, write to set a new one. Any channel member may read or write either entry — public and private channels have no separate "owner" concept. Each entry takes one open per value (there's no batching several settings into one write); a trailing partial write with no newline (as with echo "hi" > ctl/topic) is still applied when the handle is closed.

Entry Effect
ctl/topic Reading returns the current topic (shown in members); writing sets it, sanitized the same way message text is.
ctl/retention Reading returns the current history cap; writing a value caps retained history to that many messages, 0 meaning unbounded. Takes effect immediately if the backlog already exceeds the new cap, rather than waiting for the next message.

A ctl/retention write that isn't a non-negative integer is silently ignored.

History and retention

history is the only thing tbase writes to disk: one append-only JSONL file per channel. Default retention is 10,000 messages per channel (adjustable via ctl/retention above). The file is allowed to exceed the limit by up to 256 messages before it's rewritten to trim the excess — this amortizes the cost of a full-file rewrite over a batch of appends rather than paying it on every single message. A rewrite happens via a temp file plus atomic rename, so a concurrent read of history never sees a partially rewritten file.

Reading history always returns a complete view: it's trimmed to the last fully-written line, so a read never races an in-progress append and returns a torn record.