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" > sendandprintf "hi\n" > sendeach post one message, since the shell opens and closessendonce per invocation — the ordinary case is unaffected.- A bot that opens
sendonce 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 onfile/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 (
ESCand 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 instream.humanis applied server-side only, from the message'sfromfield, 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.