thepopebot 1.2.76-beta.8 → 1.2.77

package/README.md

@@ -1,194 +1,217 @@
-# ThePopeBot
+# thepopebot
 
-Build autonomous AI agents that work for you 24/7, individually or in teams.
+Your personal agent, coding environment, and communication platform — all in
+one app. Works with any LLM or coding agent. Designed to be simple, unified,
+secure, and easy.
 
-### What You Get
+- 💬 **Smart chat integrations** — Telegram today; Slack and Discord coming soon. Plus the built-in web chat.
+- 🧠 **Any LLM** — Anthropic, OpenAI, Google, DeepSeek, MiniMax, Mistral, xAI, Kimi, OpenRouter, NVIDIA, or any OpenAI-compatible endpoint.
+- 🤖 **Any coding agent** — Claude Code, Codex, Gemini, OpenCode, Pi, or Kimi.
+- 💻 **Live coding workspaces** — open a terminal in your browser, attach to a running container, share the same session as your chat.
+- 🔧 **Real work, not just chat** — agent writes code, opens a PR, auto-merges, DMs you when it's done.
+- 🔐 **Yours, fully** — runs on your hardware, your repo, your tokens.
 
-- **Runs 24/7** — set up tasks and your agent handles them around the clock, no babysitting
-- **Does real work** — writes code, opens pull requests, completes multi-step tasks end to end
-- **Agent clusters** — build teams of agents that coordinate and work together on bigger jobs
-- **Full visibility** — every action is a commit you can review, approve, or undo
-
-<a href="https://www.skool.com/ai-architects"><img src="docs/hero.png" width="100" alt="ThePopeBot" /></a>
+<a href="https://www.skool.com/ai-architects"><img src="docs/hero.png" width="100" alt="thepopebot" /></a>
 
 [Get priority support HERE](https://www.skool.com/ai-architects)
 
 ---
 
-## How It Works
+## How it works
+
+Three doors, one brain:
 
 ```
-┌──────────────────────────────────────────────────────────────────────┐
-│                                                                      │
-│  ┌─────────────────┐         ┌─────────────────┐                     │
-│  │  Event Handler  │ ──1──►  │     GitHub      │                     │
-│  │ (creates branch)│         │(agent-job/* br) │                     │
-│  └────────▲────────┘         └─────────────────┘                     │
-│           │                                                          │
-│           │  2 (launches Docker container locally)                   │
-│           │                                                          │
-│           ▼                                                          │
-│  ┌─────────────────┐                                                 │
-│  │  Docker Agent   │                                                 │
-│  │ (coding agent)  │                                                 │
-│  └────────┬────────┘                                                 │
-│           │                                                          │
-│           │  3 (commits, pushes, creates PR)                         │
-│           │                                                          │
-│           ▼                                                          │
-│  ┌─────────────────┐                                                 │
-│  │     GitHub      │                                                 │
-│  │   (PR opened)   │                                                 │
-│  └────────┬────────┘                                                 │
-│           │                                                          │
-│           │  4a (auto-merge.yml)                                     │
-│           │  4b (rebuild-event-handler.yml)                          │
-│           │                                                          │
-│           5 (notify-pr-complete.yml →                                │
-│           │  webhook to event handler)                               │
-│           └──────────────────────────►  Event Handler                │
-│                                                                      │
-└──────────────────────────────────────────────────────────────────────┘
+      ┌── Browser chat ──┐                  ┌── Telegram (verified per-user)
+      │                  ▼                  ▼
+      │            ┌──────────────────────────────────┐
+      │  attach    │           The Brain              │
+      │  a live    │     (your event handler)         │
+      │  terminal  │                                  │
+      │            │   • picks the coding agent       │
+      │            │   • picks the coding agent       │
+      │            │   • remembers the session        │
+      │            │   • runs Docker for you          │
+      └── Code ────┤                                  │
+        workspace  └──────────────┬───────────────────┘
+                                  │
+                         ┌────────┴────────┐
+                         ▼                 ▼
+                  ┌─────────────┐   ┌─────────────────┐
+                  │  Live chat  │   │   Agent job     │
+                  │ (right now) │   │  (background)   │
+                  │             │   │                 │
+                  │ same coding │   │ same coding     │
+                  │ agent runs  │   │ agent runs in   │
+                  │ in-process  │   │ a fresh Docker  │
+                  │ or in a     │   │ container,      │
+                  │ headless    │   │ opens a PR,     │
+                  │ container   │   │ DMs you back    │
+                  └─────────────┘   └─────────────────┘
 ```
 
-You interact with your bot via the web chat interface or Telegram (optional). The Event Handler creates an agent-job branch and launches a Docker container locally with the coding agent. The agent does the work, commits the results, pushes, and opens a PR. Auto-merge handles the rest. You get a notification when it's done.
+### Live chat vs. agent job
 
----
+| Path           | When                          | What happens                                       |
+|----------------|-------------------------------|----------------------------------------------------|
+| **Live chat**  | Quick questions, small edits  | Coding agent runs now, streams to your screen      |
+| **Agent job**  | "Build it. DM me when done."  | Background worker opens a PR, auto-merges, DMs you |
 
-## Star History
+### Two flavors of chat (`chatMode`)
 
-[![Star History Chart](https://api.star-history.com/svg?repos=stephengpope/thepopebot&type=date&legend=top-left)](https://www.star-history.com/#stephengpope/thepopebot&type=date&legend=top-left)
+| `chatMode` | Repo & branch              | Use it for                                  |
+|------------|----------------------------|---------------------------------------------|
+| `agent`    | Your bot's own repo        | Talking *to* your bot — config, skills, ops |
+| `code`     | Any repo + branch you pick | Real coding sessions on a project           |
+
+### Live coding workspaces
+
+Open a workspace from any code-mode chat and the browser attaches a terminal
+to a persistent container running your coding agent of choice. Workspace and
+chat share the same session — fire a question in chat, hop into the terminal,
+the agent already knows what you were just talking about.
+
+### When you ask for a job
+
+```
+  you ──► chat ──► event handler ──► creates `agent-job/<id>` branch
+                                              │
+                                              ▼
+                                    launches a Docker container
+                                    locally (your chosen agent)
+                                              │
+                                              ▼
+                                    agent commits, pushes,
+                                    opens a PR
+                                              │
+                                              ▼
+                                    auto-merge.yml ──► merged
+                                              │
+                                              ▼
+                                    notify-pr-complete.yml ──► DM to you
+```
 
 ---
 
-## Get Started
+## Install
 
 ### Prerequisites
 
 | Requirement | Install |
 |-------------|---------|
 | **Node.js 18+** | [nodejs.org](https://nodejs.org) |
-| **npm** | Included with Node.js |
 | **Git** | [git-scm.com](https://git-scm.com) |
 | **GitHub CLI** | [cli.github.com](https://cli.github.com) |
-| **Docker + Docker Compose** | [docker.com](https://docs.docker.com/get-docker/) (installer requires admin password) |
-| **ngrok*** | [ngrok.com](https://ngrok.com/download) (free account + authtoken required) |
+| **Docker + Docker Compose** | [docker.com](https://docs.docker.com/get-docker/) |
+| **ngrok*** | [ngrok.com](https://ngrok.com/download) (free account + authtoken) |
 
-*\*ngrok is only required for local installs without port forwarding. VPS/cloud deployments don't need it. [Sign up](https://dashboard.ngrok.com/signup) for a free ngrok account, then run `ngrok config add-authtoken <YOUR_TOKEN>` before starting setup.*
+*\*ngrok is only needed for local installs without port forwarding. VPS/cloud deployments don't need it.*
 
 ### Two steps
 
-**Step 1** — Scaffold a new project:
-
 ```bash
 mkdir my-agent && cd my-agent
-npx thepopebot@latest init
+npx thepopebot@latest init   # scaffold project
+npm run setup                 # interactive wizard
 ```
 
-This creates a Next.js project with configuration files, GitHub Actions workflows, and agent templates. You don't need to create a GitHub repo first — the setup wizard handles that.
+The wizard checks prerequisites, creates a GitHub repo, generates a PAT, configures your URL, and starts Docker. Visit your APP_URL when it finishes.
+
+> **Local installs**: your server needs to be reachable from the internet for GitHub webhooks and Telegram. Use [ngrok](https://ngrok.com) (`ngrok http 80`). If your ngrok URL changes, run `npx thepopebot set-var APP_URL <new-url>` and re-register the Telegram webhook from `/admin/event-handler/telegram`.
 
-**Step 2** — Run the setup wizard:
+---
+
+## Upgrade
 
 ```bash
-npm run setup
+npx thepopebot upgrade          # latest stable
+npx thepopebot upgrade @beta    # latest beta
+npx thepopebot upgrade 1.2.72   # specific version
+```
+
+Installs the new package, syncs managed files, rebuilds, restarts Docker.
+
+### What's protected, what gets updated
+
+Two kinds of files behave differently — by design, so an upgrade never blows
+away your customizations.
+
+```
+   ┌─ Managed files ──────────────┐   ┌─ Your files ─────────────────┐
+   │  .github/workflows/          │   │  agent-job/SYSTEM.md         │
+   │  docker-compose.yml          │   │  agent-job/CRONS.json        │
+   │  .gitignore                  │   │  event-handler/TRIGGERS.json │
+   │                              │   │  agents/                     │
+   │  Always replaced with the    │   │  skills-library/, skills/    │
+   │  latest version on every     │   │  .env, secrets               │
+   │  init / upgrade.             │   │  Never touched by upgrade.   │
+   └──────────────────────────────┘   └──────────────────────────────┘
 ```
 
-The wizard walks you through everything:
-- Checks prerequisites (Node.js, Git, GitHub CLI, Docker)
-- Creates a GitHub repository and pushes your initial commit
-- Creates a GitHub Personal Access Token (scoped to your repo)
-- Configures your public URL and webhook secret
-- Syncs settings to `.env`, database, and GitHub secrets/variables
-- Starts Docker for you
+So you never lose your work — but you might miss a useful template change.
+Three commands let you pull updates in deliberately:
 
-**That's it.** Visit your APP_URL when the wizard finishes.
+```bash
+npx thepopebot audit          # show what's drifted from the templates
+npx thepopebot diff <file>    # show the diff for one file
+npx thepopebot reset <file>   # replace one file with the latest template
+npx thepopebot reset-all      # ⚠ nuclear: wipe local edits, restore everything
+```
 
-- **Web Chat**: Visit your APP_URL to chat with your agent, create jobs, upload files
-- **Telegram** (optional): Run `npm run setup-telegram` to connect a Telegram bot
-- **Webhook**: Send a POST to `/api/create-agent-job` with your API key to create jobs programmatically
-- **Cron**: Edit `agent-job/CRONS.json` to schedule recurring jobs
+Use them when release notes mention a SYSTEM.md or workflow improvement you want.
 
-### Chat vs Agent LLM
+> **Upgrade failed?** See [Recovering from a Failed Upgrade](docs/UPGRADE.md#recovering-from-a-failed-upgrade).
 
-Your bot has two sides — a **chat** side and an **agent** side.
+---
 
-**Chat** is the conversational part. When you talk to your bot in the web UI or Telegram, it uses the chat LLM. This runs on your server and responds in real time.
+## How LLMs are wired
 
-**Agent** is the worker. When your bot needs to write code, modify files, or do a bigger task, it spins up a separate job that runs in a Docker container on GitHub. That job uses the agent LLM.
+Two slots, you pick whether they share a model.
 
-By default, both use the same model. But during setup, you can choose different models for each — for example, a faster model for chat and a more capable one for agent jobs. The wizard asks "Would you like agent jobs to use different LLM settings?" and lets you pick.
+- **Coding agent** — drives **everything you actually talk to**: live chat in the browser/Telegram, code workspaces, and background agent jobs. One agent, one model. For Claude Code the chat runs in-process via the Claude Agent SDK; for any other agent (Pi, Codex, Gemini, OpenCode, Kimi) it runs in an ephemeral headless container — same chunk shape either way. Configured at `/admin/event-handler/coding-agents`.
+- **Helper LLM** — small one-shot calls only: chat auto-titles, agent-job titles, PR-merge summaries. Independent provider/model from the coding agent. Configured at `/admin/event-handler/helper-llm`.
 
-### Using a Claude Subscription (OAuth Token)
+A coding-agent task can override its model per-run via `agent_backend` + `llm_model` on a cron, trigger, or chained agent job.
 
-If you have a Claude Pro ($20/mo) or Max ($100+/mo) subscription, you can use it to power your agent jobs instead of paying per API call. During setup, choose Anthropic as your agent provider and say yes when asked about a subscription.
+### Using a Claude subscription
 
-You'll need to generate a token:
+If you have Claude Pro or Max, you can power Claude Code with your subscription instead of API billing. Generate a token:
 
 ```bash
-# Install Claude Code CLI (if you don't have it)
 npm install -g @anthropic-ai/claude-code
-
-# Generate your token (opens browser to log in)
 claude setup-token
 ```
 
-Paste the token (starts with `sk-ant-oat01-`) into the setup wizard. Your agent jobs will now run through your subscription. Note that usage counts toward your Claude.ai limits, and you still need an API key for the chat side.
-
-See [Coding Agents](docs/CODING_AGENTS.md) for details on all five agent backends.
+Paste it (starts with `sk-ant-oat01-`) into Admin > Event Handler > Coding Agents > Claude Code (auth mode: OAuth). The same token drives live chat *and* background agent jobs — no separate API key needed for chat. Add multiple tokens and they rotate LRU on each container launch.
 
-> **Local installs**: Your server needs to be reachable from the internet for GitHub webhooks and Telegram. On a VPS/cloud server, your APP_URL is just your domain. For local development, use [ngrok](https://ngrok.com) (`ngrok http 80`) or port forwarding to expose your machine.
->
-> **If your ngrok URL changes** (it changes every time you restart ngrok on the free plan), you must update APP_URL everywhere:
->
-> ```bash
-> # Update .env and GitHub variable in one command:
-> npx thepopebot set-var APP_URL https://your-new-url.ngrok.io
-> # If Telegram is configured, re-register the webhook:
-> npm run setup-telegram
-> ```
+See [Coding Agents](docs/CODING_AGENTS.md) for details on all six agent backends.
 
 ---
 
-## Updating
+## Connect Telegram (optional)
 
-```bash
-npx thepopebot upgrade          # latest stable
-npx thepopebot upgrade @beta    # latest beta
-npx thepopebot upgrade 1.2.72   # specific version
-```
-
-Saves your local changes, syncs with GitHub, installs the new version, rebuilds, pushes, and restarts Docker.
-
-**What it does:**
+Talk to your bot from your phone. Two steps:
 
-1. Saves any local changes you've made
-2. Pulls the latest from GitHub (stops if there are conflicts)
-3. Installs the new version and updates project files
-4. Rebuilds your project
-5. Pushes everything to GitHub
-6. Restarts Docker containers (if running)
+1. **Wire up the bot** — at `/admin/event-handler/telegram`, paste the bot token from [@BotFather](https://t.me/BotFather) and click **Register webhook**.
+2. **Verify your account** — at `/profile/telegram`, generate a one-time code and send `/verify <code>` to your bot. The bot only responds to verified users; unbound chats are silently dropped.
 
-Pushing to `main` triggers the `rebuild-event-handler.yml` workflow on your server. It detects the version change, runs `thepopebot init`, updates `THEPOPEBOT_VERSION` in the server's `.env`, pulls the new Docker image, restarts the container, rebuilds `.next`, and reloads PM2 — no manual `docker compose` needed.
+Once verified: `/session` lists your active threads, `/session <id>` switches the thread your messages route to. Voice notes are transcribed when an `ASSEMBLYAI_API_KEY` is set in `/admin/event-handler/voice`.
 
-> **Upgrade failed?** See [Recovering from a Failed Upgrade](docs/UPGRADE.md#recovering-from-a-failed-upgrade).
-
-See [CLI Reference](docs/CLI.md) for full details on `init`, managed vs user files, template conventions, and all CLI commands.
+See [Chat Integrations](docs/CHAT_INTEGRATIONS.md) for the channel adapter pattern and how to add new channels (Slack, Discord coming soon).
 
 ---
 
 ## Security
 
-thepopebot includes API key authentication, webhook secret validation (fail-closed), session encryption, secret filtering in the Docker agent, and auto-merge path restrictions. However, all software carries risk — thepopebot is provided as-is, and you are responsible for securing your own infrastructure. If you're running locally with a tunnel (ngrok, Cloudflare Tunnel, port forwarding), be aware that your dev server endpoints are publicly accessible with no rate limiting and no TLS on the local hop.
+thepopebot includes API key authentication, webhook secret validation (fail-closed), session encryption (AES-256-GCM keyed off `AUTH_SECRET`), per-job API keys with maintenance-cron expiry, and auto-merge path restrictions. All software carries risk — thepopebot is provided as-is, and you are responsible for securing your own infrastructure. If you're running locally with a tunnel, your dev server endpoints are publicly accessible with no rate limiting and no TLS on the local hop.
 
-See [Security](docs/SECURITY.md) for full details on what's exposed, the risks, and recommendations.
+See [Security](docs/SECURITY.md) for full details.
 
 ---
 
-## Different Models
-
-thepopebot supports 9 built-in LLM providers (Anthropic, OpenAI, Google, DeepSeek, MiniMax, Mistral, xAI, Kimi, OpenRouter) plus custom OpenAI-compatible endpoints. The chat layer and coding agents are independent — use Claude for interactive chat and a different model for code tasks, or run everything on a single provider.
+## Star History
 
-See [Different Models](docs/RUNNING_DIFFERENT_MODELS.md) for the full provider reference, admin UI configuration, per-job overrides, and custom provider setup.
+[![Star History Chart](https://api.star-history.com/svg?repos=stephengpope/thepopebot&type=date&legend=top-left)](https://www.star-history.com/#stephengpope/thepopebot&type=date&legend=top-left)
 
 ---
 
@@ -198,8 +221,8 @@ See [Different Models](docs/RUNNING_DIFFERENT_MODELS.md) for the full provider r
 
 SQLite can't create or open its shared-memory (`.shm`) file. Common causes:
 
-- **Antivirus** (Windows Defender, etc.) locking the database files — add your project folder to the exclusion list
-- **Cloud-synced folders** (OneDrive, Dropbox, Google Drive) — move your project to a non-synced directory like `C:\Projects\`
+- **Antivirus** locking the database — add your project folder to the exclusion list
+- **Cloud-synced folders** (OneDrive, Dropbox, Google Drive) — move your project to a non-synced directory
 
 ---
 
@@ -209,13 +232,13 @@ SQLite can't create or open its shared-memory (`.shm`) file. Common causes:
 |----------|-------------|
 | [Architecture](docs/ARCHITECTURE.md) | Two-layer design, file structure, API endpoints, GitHub Actions, Docker agent |
 | [CLI Reference](docs/CLI.md) | `init`, managed vs user files, template conventions, all CLI commands |
-| [Configuration](docs/CONFIGURATION.md) | Admin UI, DB-backed config, infrastructure variables, GitHub secrets, Docker Compose |
-| [Customization](docs/CUSTOMIZATION.md) | Personality, skills, operating system files, using your bot, security details |
+| [Configuration](docs/CONFIGURATION.md) | Admin UI, DB-backed config, infrastructure variables, Docker Compose |
+| [Customization](docs/CUSTOMIZATION.md) | Personality, skills, operating system files, using your bot |
 | [Chat Integrations](docs/CHAT_INTEGRATIONS.md) | Web chat, Telegram, adding new channels |
-| [Different Models](docs/RUNNING_DIFFERENT_MODELS.md) | 9 built-in LLM providers, chat vs coding agent config, per-job overrides, custom providers |
+| [Different Models](docs/RUNNING_DIFFERENT_MODELS.md) | 10 built-in LLM providers, helper LLM vs coding agent split, per-job overrides, custom providers |
 | [Auto-Merge](docs/AUTO_MERGE.md) | Auto-merge controls, ALLOWED_PATHS configuration |
 | [Deployment](docs/DEPLOYMENT.md) | VPS setup, Docker Compose, HTTPS with Let's Encrypt |
-| [Coding Agents](docs/CODING_AGENTS.md) | 5 coding agent backends, OAuth tokens, LiteLLM proxy, per-agent config |
+| [Coding Agents](docs/CODING_AGENTS.md) | 6 coding agent backends, OAuth tokens, LiteLLM proxy, per-agent config |
 | [How to Build Skills](docs/HOW_TO_BUILD_SKILLS.md) | Guide to building and activating agent skills |
 | [Pre-Release](docs/PRE_RELEASE.md) | Installing beta/alpha builds |
 | [Code Workspaces](docs/CODE_WORKSPACES.md) | Interactive Docker containers with in-browser terminal |

package/api/CLAUDE.md

@@ -4,31 +4,42 @@ This directory contains the route handlers for all `/api/*` endpoints. These rou
 
 ## Auth
 
-All routes (except `/telegram/webhook` and `/github/webhook`, which use their own webhook secrets) require a valid API key passed via the `x-api-key` header. API keys are stored in the SQLite database and managed through the admin UI — they are NOT environment variables.
+Most routes require a valid API key passed via the `x-api-key` header. API keys are stored in the SQLite database and managed through the admin UI — they are NOT environment variables.
 
-Auth flow: `x-api-key` header -> `verifyApiKey()` -> database lookup (hashed, timing-safe comparison).
+**Public routes** (no API key needed): `/ping`, `/telegram/webhook` (Telegram webhook secret), `/github/webhook` (GitHub webhook secret), `/oauth/callback` (validated via short-lived `state` token).
+
+Auth flow: `x-api-key` header → `verifyApiKey()` → DB lookup (hashed, timing-safe comparison). Two key types exist:
+
+- **User-owned API keys** — long-lived, created via the admin UI, used by external callers (cURL, GitHub Actions, Telegram register).
+- **Per-job agent API keys** (`agent_job_api_key`) — short-lived, auto-created when an agent-job container launches (`createAgentJobApiKey()` in `lib/db/api-keys.js`), tied to the container name, and cleaned up by the maintenance cron after expiry. Routes that read agent-job secrets (`/api/get-agent-job-secret`, `/api/agent-job-list-secrets`) reject any other key type.
 
 ## Do NOT use these routes for browser UI
 
 Browser-facing data fetching uses **fetch route handlers** colocated with pages (`route.js` files in `web/app/`). These check `auth()` session — never use `/api` routes from the browser. Server actions (`'use server'`) are used only for **mutations** (rename, delete, star, config updates) — never for data fetching (causes page refresh issues). Handler implementations live in `lib/chat/api.js`; route files are thin re-exports.
 
+Mutation server actions in `lib/chat/actions.js` use `requireAdmin()` for settings/config writes and `requireAuth()` for chat CRUD on user-owned rows. Reads stay open to any logged-in user. Sidebar items like Upgrade are gated on `user.role === 'admin'`.
+
 | Caller | Mechanism | Auth |
 |--------|-----------|------|
 | External (cURL, GitHub Actions, Telegram) | `/api` route | `x-api-key` header |
 | Browser UI (data fetching) | Fetch route handler colocated with page | `auth()` session |
-| Browser UI (mutations) | Server action | `requireAuth()` session |
-| Browser UI (streaming) | `/stream/chat`, `/stream/containers`, `/stream/cluster/*/logs` | `auth()` session |
+| Browser UI (mutations) | Server action | `requireAuth()` / `requireAdmin()` |
+| Browser UI (streaming) | `/stream/chat`, `/stream/containers`, `/stream/containers/logs`, `/stream/cluster/*/logs` | `auth()` session |
 
 ## Routes
 
 | Method | Path | Auth | Handler |
 |--------|------|------|---------|
 | GET | `/api/ping` | None | Health check |
-| POST | `/api/create-agent-job` | `x-api-key` | Create agent job |
-| GET | `/api/get-agent-job-secret` | `x-api-key` | Get an agent job secret; oauth2 credentials return only the access_token (auto-refreshed) |
-| GET | `/api/agent-job-list-secrets` | `x-api-key` | List agent job secret keys (no values); returns `{secrets: [{key, isSet, updatedAt, secretType}]}` |
+| POST | `/api/create-agent-job` | `x-api-key` | Create agent job. Body: `{ agent_job, llm_model?, agent_backend?, scope?, user_id? }`. `user_id` attributes the job to that user — the PR-merge webhook reads it back to DM the originator instead of broadcasting. |
+| GET | `/api/get-agent-job-secret` | `agent_job_api_key` only | Get an agent job secret. `key` query param is upper-cased before lookup (admin form already saves uppercase). `oauth2` credentials return only the access_token (auto-refreshed under a per-key lock; rotated refresh tokens are persisted back). Other secret types return the raw value. |
+| GET | `/api/agent-job-list-secrets` | `agent_job_api_key` only | List agent job secret keys (no values); returns `{secrets: [{key, isSet, updatedAt, secretType}]}` |
 | GET | `/api/agent-jobs/status` | `x-api-key` | Agent job status (query: `?agent_job_id=`) |
-| POST | `/api/telegram/webhook` | Telegram webhook secret | Telegram message handler |
-| POST | `/api/telegram/register` | `x-api-key` | Register bot token + webhook URL |
-| POST | `/api/github/webhook` | GitHub webhook secret | GitHub event handler |
+| GET | `/api/users` | `x-api-key` | List users with verified DM channels: `{users: [{id, email, first_name, last_name, nickname, role, channels: ['telegram', ...]}]}`. Used by the `agent-job-dm` skill. |
+| POST | `/api/send-dm` | `x-api-key` | Dispatch a message. Body: `{ user_id?, message, payload?, system_message? }`. With `user_id`: write 1 row + push to that user's default channel. Without: fan out 1 row per admin where `subscribedToSystemMessages=1`, each pushed to their default channel. `system_message: true` (default false) marks it as a system notification — channels with `systemMessagesEnabled=0` skip the push (inbox row still written). Returns `{ok, recipients}`. |
+| POST | `/api/telegram/webhook` | Telegram webhook secret | Telegram message handler (per-user routing via `user_channels`; verifies via `/verify <code>`, dispatches `/session` commands) |
+| POST | `/api/github/webhook` | GitHub webhook secret | GitHub event handler. PR-merge events read `user_id` from `agent-job.config.json` and dispatch the completion message via `dispatchMessage` (per-user when set; broadcast to subscribed admins when absent). Agent-job completions are broadcasts, not system messages — they always push regardless of per-channel `systemMessagesEnabled`. |
 | POST | `/api/cluster/:clusterId/role/:roleId/webhook` | `x-api-key` | Trigger cluster role execution |
+| GET/POST | `/api/oauth/callback` | `state` token | OAuth provider redirect target. Exchanges `code` for tokens, persists via `setAgentJobSecret(name, stored, 'oauth')`. |
+
+Telegram bot configuration (token + webhook registration) is done from the admin UI at `/admin/event-handler/telegram`, not via an API route.