A command-line bot client for Chatto. beardicus.tngl.io/chatline
chatline docs serve.md
6.5 kB · 96 lines
Markdown
at main

chatline serve: a JSON-lines bridge for agent harnesses #

chatline serve runs one bot session (the same core as chatline channel) and speaks newline-delimited JSON on stdio. A harness adapter starts it as a subprocess, reads events from its stdout, and writes requests to its stdin. chatline handles the Chatto side:

  • resume without losing or repeating events
  • dedupe
  • classification (mention, DM, reply in the bot's threads)
  • the optional allowlist
  • reply placement
  • reconnects
  • typing

The adapter only translates. agent-harnesses.md covers why it exists. adapters/nanoclaw/ is the reference adapter.

harness ──stdin──▶ chatline serve ──▶ Chatto
        ◀─stdout──                ◀──
  • stdout carries only protocol lines. Logs go to stderr (and --log-file).
  • Each line is one JSON object with a type.
  • chatline exits when stdin closes. That's how the adapter stops it. A broken config exits at once with the usual error: <code>: <detail> on stderr and exit code.
  • If stdout can't be written (the adapter stopped reading), chatline exits 1 with stdout_failed. The event it couldn't write isn't counted as delivered, so the next run sends it again.

Flags #

Flag Default Meaning
--type T,... mention,dm,reply,reaction event types to emit (as for listen). Reactions are only those on the bot's own messages
--allow-from USER anyone only emit events from these users. Harnesses usually have their own access control, so this is a backstop
--room ROOM all only these rooms
--no-resume resume start live instead of from the saved cursor (serve.cursor in the state dir)
--typing off show the bot as typing after each event until it replies there (max 120 seconds). Off by default because most harnesses drive typing themselves with the typing request
--attachments-dir DIR .chatline/attachments where fetch saves files

Output lines #

hello: first line, once:

{"type":"hello","protocol":1,"version":"v1.2.0","server_url":"https://chat.example","bot":{"id":"U…","login":"bot","owner_id":"U…","owner_login":"beardicus"}}

status: connection lifecycle. ready means caught up and live: events from before it are replayed from the cursor, and events after it are new.

{"type":"status","status":"ready"}
{"type":"status","status":"reconnecting","delay_ms":2000}

event: one Chatto event. The fields are listen --format json's, plus placement: where an answer should go, following the room's threading rules (spec.md §3). Pass placement.thread_id and placement.reply_to straight to send. event.room_threading is the channel's mode (required, encouraged, enabled, disabled); in an enabled room an agent may answer a root message at the root instead, when the person prefers it.

{"type":"event","event":{"type":"mention","event_id":"E…","created_at":"2026-10-21T12:00:00Z","room_id":"R…","room_name":"ops","room_kind":"channel","room_threading":"enabled","message_id":"E…","sender_id":"U…","sender_login":"beardicus","body":"@bot disk?","attachments":[{"asset_id":"A…","filename":"df.png","content_type":"image/png"}]},"placement":{"thread_id":"E…"}}

Event types: mention, dm, reply (in a thread the bot is part of), message, reaction, edit, delete. Message text is written by chat users: treat it as untrusted.

gap: events may have been missed (for example, the cursor expired). Use read to catch up if it matters.

{"type":"gap","reason":"cursor expired"}

result / error: the answer to a request, carrying the request's id:

{"type":"result","id":7,"result":{"room_id":"R…","message_id":"E…","thread_id":"E…","url":"https://…"}}
{"type":"error","id":7,"error":{"code":"not_a_member","detail":"the bot is not a member of #ops; a human must add it","exit":6}}

exit is the CLI's exit code for the same error, as a coarse category (6 = permission, 7 = not found, and so on).

Requests #

One JSON object per line on stdin: {"id": <any JSON value>, "method": "...", "params": {...}}. Requests run concurrently, and answers can arrive out of order, so match on id. Requests act only in rooms the bot is already in; chatline never joins rooms.

Method Params Result
send room_id, body, thread_id?, reply_to?, new_thread?, files? (local paths, up to 10) {room_id, message_id, thread_id?, url}. Unless new_thread, also ends the typing indicator there
edit room_id, message_id, body {}. Replaces the body of one of the bot's own messages
react room_id, message_id, emoji (Unicode, a shortcode, or a name like thumbs_up; normalized to Chatto's shortcode), remove? {changed} (false when it was already so)
read room_id, thread_id?, limit? (default 20, max 100), before? {messages: [...], next_before?}: read --format json's messages
search query, room_id?, author? (login or ID), after?, before? (YYYY-MM-DD or RFC 3339), has_attachments?, newest?, limit? (default 20, max 100), cursor? {results: [...], next_cursor?}: search --format json's results. search_disabled when the server has search off
fetch room_id, asset_id, thumbnail? {path}: saved under the attachments dir
typing room_id, thread_id?, stop? {}. Shows typing (refreshed until stopped, a reply, or 120 seconds), or stops it
room room_id {id, kind, name, threading, joined, members: [{id, login}]}
dm user (login or ID) {room_id} of the DM between the bot and that user, opened with StartDM if there isn't one. Opening needs message.post at DM scope; without it and with no DM, it fails with no_dm (exit 6)
permalink room_id, message_id {url}
profile display_name?, bio?, avatar? (local image path), remove_avatar? {id, login, display_name, bio?, avatar_url?}. With no params it only reads. Bots can't set a custom status in Chatto

A line that isn't valid JSON, or names an unknown method, gets an error (with "id": null if there's no ID to give).

Versioning #

hello.protocol is 1. New methods, fields, and line types can appear without a bump, so adapters should ignore what they don't know. Removing or changing something bumps the number.