# beaver-gateway

A gateway for personal agents built on the Claude Agent SDK: conversations
with a lifecycle, windows to talk through, jobs, memory hooks, and a policy
boundary - without an opinion about what the agent is for. A setup is one
`config.py` (or a package next to it) that assembles a `Gateway`; this repo
holds the primitives, [beaver-agent](https://git.kotikot.com/beaver/beaver-agent)
is a full setup built on them.

## What it gives a setup

- **agents/** - what an agent is: a Claude agent with a prompt per
  conversation kind, skill sets per kind, gateway tools, a `PreToolUse`
  policy; a Raycast agent for cheap fast answers.
- **backends/** - how a turn runs: the Claude Agent SDK subprocess with a
  session pool, transcripts and session stores; the Raycast wire.
- **conversations/** - the model of a conversation: kinds (master, branch,
  deep, job, fork), rows and windows, the inject queue with priorities,
  seeds, turns, questions, closing through a distiller, master rotation,
  the envelope, the in-process gateway tools.
- **jobs/** - cron, webhook and event jobs on pgqueuer, deferred injects,
  the subscription budget.
- **frontends/** - the windows: Telegram (master = General, topic = branch),
  markdown files in a vault, `/api` + the admin SPA, an Anthropic-compatible
  `/anthropic/v1/messages`, MCP re-exposure at `/mcp/<name>`.
- **mcp/** - MCP servers a setup declares (stdio, http, python tools),
  aggregated in-process and handed to agents by name.
- **vault/** - watching a directory of notes for the envelope.
- **security/** - bearer tokens, the audit log, credential redaction.
- **events/** - the in-process bus every frontend taps, and the stream
  event protocol backends emit.
- **storage/** - SQLModel tables and the Postgres session store.

`config.py` defines `Gateway` and loads a setup; `app.py` builds the runtime
from it; `cli.py` is the entrypoint. Every string the gateway puts in front of
a model or a user has an English default and is overridable
(`ConversationTexts`, `TelegramTexts`).

## Run

```sh
uv sync                       # python
cd ui && bun install && cd .. # admin + panel SPA, built into ui/build
cp examples/config.py /config/config.py
DATABASE_URL=postgresql+psycopg://... CONFIG_PATH=/config/config.py uv run beaver-gateway
```

`examples/config.py` is the smallest setup that starts. The setup's own
secrets come from `.env` (`load_dotenv` runs before the config is executed).

## Develop

```sh
make check   # ruff format --check, ruff check, ty, pytest
make fix
```

No comments in code: modules carry a one-line docstring saying what they are
for, public configuration fields carry a one-line docstring saying what they
mean; everything else is the code.