Bee Box documentation · directory: https://beebox.run/docs/reference/cards/ · index: https://beebox.run/docs/reference/cards/index.md · root: https://beebox.run/llms.txt

# 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