Writing an adapter

herdr-link talks to chat apps through adapters: small programs, in any language, that speak a JSON-RPC 2.0 protocol on stdin/stdout. The bridge does everything herdr-specific (spaces, tabs, agents, prompts, the archive); the adapter only knows its chat platform. The built-in adapters, Discord (src/adapters/discord/main.ts) and Telegram (src/adapters/telegram/main.ts, plain fetch, no SDK: a good one to read first), use the same protocol as yours would.

The machine-readable reference is schema/chat.openrpc.json (OpenRPC). This page explains how to use it.

The model

• Ids (room, thread, message, action) are opaque strings. The bridge stores the ones you return and gives them back; it never parses them. Encode whatever you need ("chat:-100123/topic:45" is fine).
• A place is where a message lives: {"kind": "thread", "thread": "<id>"} or {"kind": "direct"}.
• An adapter serves one owner. You check every inbound message, reaction, button press and command against the owner and drop everything else: whoever can write in these threads can run code on the owner's machine.

Lifecycle

1. The owner adds a section to ~/.config/herdr-link/config.toml:

   [adapters.telegram]
   command = ["herdr-link-telegram"]   # argv of your program
   env = ["TELEGRAM_TOKEN"]            # env vars your program may see
   owner = "123456789"                 # everything else is yours, sent in hello
   chat = "-1001234567890"
   

2. The bridge starts command with only the listed env variables plus PATH, HOME, USER, LANG… Secrets come from ~/.config/herdr-link/.env.

3. Messages are JSON-RPC 2.0, one per line, UTF-8, on stdin (from the bridge) and stdout (to the bridge). Both sides send requests and notifications; request ids are per sender. Write logs to stderr: the bridge copies them into its own log. Anything else on stdout breaks the protocol.

4. The bridge sends hello first. Validate your config, connect to your platform, and answer only when you are ready. Don't send anything before that.

5. When stdin closes, shut down. The bridge restarts an adapter that exits, with backoff, except after an InvalidConfig or UnsupportedProtocol error.

hello

→ {"jsonrpc":"2.0","id":1,"method":"hello","params":{"protocol":1,"config":{"owner":"123456789","chat":"-1001234567890"},"commands":[{"name":"status","description":"What every agent is doing","options":[]},{"name":"space new","description":"Make a herdr space","options":[{"name":"name","description":"Space name","type":"string","required":true}]}],"agents":[{"name":"claude","emoji":"✳️","logo":"claude"},{"name":"shell","emoji":"🐚"}]}}
← {"jsonrpc":"2.0","id":1,"result":{"protocol":1,"adapter":{"name":"telegram","version":"0.1.0"},"capabilities":{"rooms":true,"direct":true,"threadCreation":true,"actions":true,"reactions":true,"customEmoji":false,"commands":true,"edit":true,"files":true,"maxText":4096,"maxActions":8}}}

• config is your section of the config file without command and env. If it is wrong, answer with error -32003 (InvalidConfig) and a message the owner can act on; the bridge then stops instead of restarting you.
• commands are the slash commands to register, if your platform has them. A name with a space (space new) is a command with a subcommand.
• agents are the agents the bridge can start: the name that space.create and thread.created take as agent, the emoji that starts its threads' names, and logo, a custom emoji's name for platforms that have them. They change only with the config, which restarts you. Bridges before 0.6.4 don't send it.
• capabilities tell the bridge what you can do. Be honest: the bridge works around what you can't.

Bridge → adapter

All of these but thread.status are requests: answer each with a result or an error.

One notification, only when your capabilities say "status": true:

An emoji is {"kind": "unicode", "value": "👀"} or {"kind": "custom", "name": "claude"} (a custom emoji you know by name, such as an agent's logo).

→ {"jsonrpc":"2.0","id":7,"method":"message.post","params":{"place":{"kind":"thread","thread":"-1001234567890/45"},"text":"🔐 Permission: approve Bash: pnpm test","actions":[{"id":"prompt:3:allow","label":"Allow","style":"success"},{"id":"prompt:3:deny","label":"Deny","style":"danger"}]}}
← {"jsonrpc":"2.0","id":7,"result":{"message":"-1001234567890/45/9001"}}

Adapter → bridge

Report only what the owner did. Notifications are handled in order.

• attachments are {"name", "url", "size?", "contentType?"}; the bridge downloads url and puts the file beside the agent.
• Don't report threads you created or deleted yourself through thread.ensure / thread.delete (watch out for platforms that announce a new channel before your API call returns). A thread the owner deletes closes its tab; a thread the owner creates in one of your rooms opens a new one.
• A new thread opens a tab in its room's space. Without agent, a leading agent emoji in name picks the agent (✳️fix-login), else the bridge asks "Who works here?"; messages written in the thread before the tab starts become its agent's first message. With agent (a configured agent's name, such as claude), the tab starts at once, named name, and task is its first message: what a program that drives agents wants.
• A room the owner deletes closes its herdr space, with every tab in it. Don't report your own room.delete.
• space.create makes a herdr space in folder (~ allowed), with a first tab running agent on task when given (tab names it; default: the agent's name). The answer comes once the space exists: its room (if you have rooms) and the first tab's thread, already made through your room.ensure / thread.ensure, so expect those calls before the result. Errors: -32602 for an unknown agent, -32603 when herdr refuses (the Herdr app must be running).
• Acknowledge button presses on your platform yourself (Discord, for example, wants an answer within 3 seconds); the bridge does not wait for that.
• Platforms with short reply deadlines for commands: defer, then send the result of command.invoked when it comes.

← {"jsonrpc":"2.0","method":"message.received","params":{"place":{"kind":"thread","thread":"-1001234567890/45"},"message":"-1001234567890/45/9002","text":"run the tests","attachments":[]}}

Driving agents from a program

An adapter needn't be a chat app. A program with its own interface (a pipeline that runs every step of a ticket in its own tab, a board, a script) is an adapter too: to herdr-link it is a chat that happens to be written by code. It can:

1. make a space for a piece of work: space.create with the folder and the first step's agent and prompt;
2. start the next step: thread.created in that room, with agent and task;
3. follow it: thread.status (with "status": true in its capabilities) says when the agent works, waits for the owner, or is done; the agent's reply comes as message.post in the thread, prompts and questions with their buttons, which it may press (action.pressed) or leave to the owner;
4. talk to it: message.received in the thread;
5. clean up: thread.deleted closes a tab, room.deleted the whole space.

Run several adapters at once: the owner's Discord shows the same spaces and tabs, and can step in from the phone.

Errors

Standard JSON-RPC codes, plus:

A minimal adapter

test/fixtures/fake-adapter.mjs is a complete one in 50 lines of plain Node, used by the tests. The same skeleton in Python:

#!/usr/bin/env python3
import json, sys

def send(message):
    sys.stdout.write(json.dumps({"jsonrpc": "2.0", **message}) + "\n")
    sys.stdout.flush()

def log(text):
    print(text, file=sys.stderr, flush=True)

def hello(params):
    config = params["config"]
    if "owner" not in config:
        raise RpcError(-32003, "set `owner` in [adapters.mychat]")
    # connect to the platform here, then answer
    return {"protocol": 1, "adapter": {"name": "mychat", "version": "0.1.0"},
            "capabilities": {"rooms": False, "direct": True, "threadCreation": False, "actions": False,
                             "reactions": False, "customEmoji": False, "commands": False, "edit": False,
                             "files": False, "maxText": 4000, "maxActions": 0}}

def thread_ensure(params):
    return {"thread": params.get("thread") or "main", "created": "thread" not in params}

def message_post(params):
    log(f"post to {params['place']}: {params['text']}")
    return {"message": "1"}

class RpcError(Exception):
    def __init__(self, code, message):
        super().__init__(message)
        self.code = code

handlers = {"hello": hello, "thread.ensure": thread_ensure, "message.post": message_post}

for line in sys.stdin:  # stdin closes: the bridge wants us gone
    message = json.loads(line)
    if "method" not in message:
        continue  # a response to one of our requests
    handler = handlers.get(message["method"])
    try:
        if handler is None:
            raise RpcError(-32601, f"unknown method {message['method']}")
        result = handler(message.get("params", {}))
        if "id" in message:
            send({"id": message["id"], "result": result})
    except RpcError as error:
        if "id" in message:
            send({"id": message["id"], "error": {"code": error.code, "message": str(error)}})

# when the owner writes, from your platform's event loop:
# send({"method": "message.received", "params": {"place": {"kind": "thread", "thread": "main"},
#       "message": "42", "text": "hello", "attachments": []}})

Trying it

1. Add your section to the config (above), then herdr-link doctor checks that your command and env resolve.
2. Run the bridge in the foreground to see your stderr live: herdr-link run (stop the service first: herdr-link service uninstall, or it refuses to start a second bridge).
3. Publish it as a package with a herdr-link-<platform> binary, and tell its users: install only adapters you trust. An adapter can type into their agents' terminals.