beeper-bot

Files (10)

• SKILL.md
• opencode.json · profiles/assistant/
• profile.json · profiles/assistant/
• opencode.json · profiles/casual/
• profile.json · profiles/casual/
• opencode.json · profiles/collab/
• profile.json · profiles/collab/
• safety.md · references/
• beeper-bot.mjs · scripts/
• beeper-bot.test.mjs · test/

SKILL.md (first lines)

# Beeper Bot

Runs the auto-reply bot on ONE named Beeper chat for a bounded duration.
It watches for new inbound messages, generates a reply per message with the
local `opencode` CLI through a per-profile agent, sanitizes and guards it,
and posts it back to the same chat. It stops itself when the duration
elapses.

Contrast with `beeper-collab` (work-context tool): that skill only queues
inbound messages and sends a one-line acknowledgement with no model calls.
`beeper-bot` generates real replies with model calls and is for social and
test chats; the one exception for work conversations is the gated
`--policy acks` mode described below, which answers only bare
acknowledgements and yes/no questions and escalates everything else.

Transport: the script opens an SSH tunnel to the Beeper Desktop HTTP API on
the Beeper host (loopback-only there) and reads push notifications over a
raw-socket WebSocket with header auth, with HTTP polling as fallback. The
Beeper token is read over ssh at runtime, held in memory only, and redacted
from logs; it is never stored in the repo. That tunnel is the bot's own path
to the HTTP API, not the MCP endpoint, so the MCP routing change (a remote
`beeper` server plus a `beeper_ssh` fallback) leaves it unchanged. The
`127.0.0.1:23373` forward on this machine serves MCP clients, not the bot.

## Activation rules

The user must name the chat AND a bounded duration. Both are required.

1. Resolve the recipient first with the `beeper` skill's `search_chats` to
   get the numeric Beeper local chat id (e.g. `<chat-id>`).
2. If more than one candidate is plausible, ASK the user which — never
   guess.
3. Confirm the chat and the duration with the user before starting.
4. Default 10 minutes when the user does not care.
5. Always pass an explicit `--duration-min`.

`--chat` takes a numeric local chat id, verified server-side via
`GET /v1/chats/<id>`, or an unambiguous title query. Zero matches and
more-than-one match are both FATAL: the tool prints the candidates and
exits 2, it never guesses. A `!…:beeper.local` room id is NOT a valid
argument (it would be treated as a title query and fail).

## Pre-flight

Always run `--simulate` (and/or `--dry-run`) before going live.

```sh
node skills/beeper-bot/scripts/beeper-bot.mjs --chat <id> --profile <name> --duration-min 10 --simulate "sender|text"
```

Check the output: the truncated prompt, the raw CLI stdout, the
post-sanitize reply, and the guard verdict (passed or deny-list hit with
the deflect substitution). `--simulate` runs one generation+guard cycle
and NEVER sends. `--dry-run` runs the whole live loop but sends nothing.
`--once` polls once and exits. `--announce "<text>"` sends exactly one
message before watching.

Only go live when the simulated reply reads correctly in the profile's
register and the guard verdict is as expected.

`--model <id>` overrides the profile agent's configured model
(default `opencode/muse-spark-1.3-contributor-free`).

## Starting, checking and stopping

Live start (detached so it survives the session — a bare foreground run
dies with it):

```sh
setsid nohup node skills/beeper-bot/scripts/beeper-bot.mjs --chat <id> --profile <name> --duration-min 10 > ~/.local/state/beeper-bot/beeper-bot.log 2>&1 &
```

Check and stop (`--stop --chat` takes a NUMERIC chat id only — it
matches the local `runs/` registry with no network and no tunnel, so it
cannot resolve a title query; look the id up first, then pass the number):

```sh
node skills/beeper-bot/scripts/beeper-bot.mjs --status
node skills/beeper-bot/scripts/beeper-bot.mjs --stop --chat <chat-id>
node skills/beeper-bot/scripts/beeper-bot.mjs --stop --all
```

`--status` lists active runs (one JSON object per line). The bot also stops
by itself when `--duration-min` elapses. Ctrl-C/SIGTERM stops it early and
leaves a message held in a debounce batch unanswered for the NEXT run to
re-read (nothing sent, nothing lost); a duration-expiry stop answers
whatever is held before exiting (nothing lost either way).

## `--policy acks` (work chats)

```sh
node skills/beeper-bot/scripts/beeper-bot.mjs --chat <id> --profile collab \
  --policy acks --duration-min 10
```

`--policy acks` is the event-driven alternative to `beeper-collab` tick
mode: the bot still uses the model, but only for safe replies. What it
does:

- Every new inbound message must classify as `ACK` (bare acknowledgement:
  ok/thanks/noted/haan theek/…) or `YESNO` (a clear yes/no question). Mixed
  batches require every message to pass. Anything else (`COMMITMENT`,
  `REQUEST`, `OPEN_QUESTION`, `OTHER`) is written as one JSON line to the
  escalation log —
  `process.env.BEEPER_COLLAB_ESCALATIONS`
  (default `~/.local/state/beeper-collab/escalations.jsonl`, ≤120 chars of
  text per line) — marked processed, and never answered by the model.
- Rate cap: at most 4 replies per rolling hour; further candidates are
  denied (nothing sent) until the counter drains.
- The model may reply `NO_REPLY` for unclear cases; that is treated as
  intentional silence (logged, nothing sent).
- Each final reply is re-checked by a collab guard (≤160 chars, ≤2 lines,
  no links/deadline/money phrasing) before sending.
- A disclosure footer (`This message was sent by an assistant.`) is
  appended exactly once to every sent reply.

Use the `collab` profile with it (the agent config maps to
`opencode/glm-5.3-flash-free`; without `--policy` the other profiles keep
their existing behaviour).

From VariableThe/agent-kit-public, MIT.

More from VariableThe/agent-kit-public