chat-thread Card

Processing Chat Threads

A chat thread is an accumulating conversation from a messaging connector (e.g. Telegram). Your job references a thread file — read it to see the conversation.

Thread structure (YAML frontmatter)

Top-level fields:

• chat-id: and connector: — identify the chat
• description: — what this chat is (e.g. "Family group chat")
• participants: — array of {ref: /people/...} linking to people cards
• entries: — chronological array of messages and seen-markers

Each entry has a kind discriminator:

• kind: message with fields sender, sender-id?, time?, sent?, id?, text
• kind: seen with fields callback-in?, wait-for?, text?

Guidelines

Check for a chat.guide.card file in the same directory as the thread file. If it exists, read it — it contains per-chat behavioral guidelines (when to respond, tone, topics to watch for). Follow those guidelines when deciding how to respond.

Finding new messages

Scan backward from the end of the entries: array. The last kind: seen or kind: message with sender: agent marks the boundary of what was previously processed. Everything after that boundary is new.

If the last entry is already yours (seen or agent message) and there are no new messages after it, check whether the seen entry has a text: — that's a note from your previous self about what to do next.

Responding

You MUST leave exactly one trailing entry at the end of entries::

• A message entry with kind: message, sender: agent, text: "Your response" — to send a message. Do NOT set sent or id; the connector handles delivery.
• A seen entry with kind: seen — to acknowledge without responding. Use this for casual/social messages, messages not directed at you, or when there's nothing useful to add.

When to respond vs. acknowledge

• Respond to direct questions, requests, or when you have genuinely useful information
• Acknowledge (kind: seen) casual chatter, messages between other people, or when silence is appropriate
• When in doubt, acknowledge rather than respond — unsolicited messages are annoying

Scheduling follow-ups

• {kind: seen, callback-in: 30m, text: "Check if anyone answered Alice's question"} — you'll be re-invoked in 30 minutes if no new messages arrive
• The text of a seen entry is a note to your future self — write what you plan to check or do

Important rules

• Only append ONE entry to the end of entries: (one message or one seen)
• Do NOT modify or remove existing entries in the thread
• Do NOT modify description, participants, or other metadata — the connector manages those
• Do NOT set sent or id on agent messages — the connector stamps those after delivery
• Commit the thread file, then run bbx finish {jobFile} to complete the job