Theteia — the Discord ocbot

Getting started

Thu, 15 Oct 2026 21:30:54 +0000

# Getting started

Audience: a new operator or contributor who has never run ocbot. Purpose: get from a clean machine to a verified running bot. Prerequisites: Linux is the supported host (the production units are systemd); the bot is built for a single operator — you need a chat surface to talk on (Discord, Signal, or both) and a host you control.

# Prerequisites

Requirement	Version	How you get it
rustup + Rust	1.98.1, pinned via `rust-toolchain.toml`	rustup↗ ; the pinned toolchain is fetched automatically on first build
opencode server	v2, current pin 2.0.24	install opencode; see client COMPAT↗ for the version policy
git	any recent	your package manager; `git --version`
Discord account	—	yours, plus a bot application (step 1) — only if `channel` selects `discord`
A phone number	—	for `channel = "signal"`: the bot’s own number (registered or linked on the daemon host) plus yours as the allowlisted sender — see DEPLOYMENT

# Step 1 — Create the Discord bot

Create an application in the Discord developer portal↗ .
Open the Bot tab, reset the token, and copy it — this is DISCORD_TOKEN.
Enable the Message Content privileged intent. The bot needs it to map replies to inbox reports back to sessions.
Under OAuth2 → URL generator, select the scopes bot and applications.commands, and at minimum the permissions Send Messages, Attach Files, and Add Reactions. Open the generated URL to invite the bot to a private server you own.
In Discord, enable Developer Mode (user settings → Appearance), right-click your own name, and Copy User ID — this is ALLOWED_USER_ID.

# Step 2 — Start the opencode server

ocbot expects the server on loopback with a password. The minimal manual start:

Architecture

Thu, 15 Oct 2026 21:24:30 +0000

# Architecture

Audience: contributors who want to change ocbot and reviewers who want to judge it. Purpose: show how the system is built, where state lives, and why the load-bearing decisions were made. Prerequisites: What is ocbot?↗ and the glossary .

# System overview

ocbot runs as one process on the same host as the opencode server. It talks to exactly five things: two chat surfaces (Discord and Signal), the opencode server, git, and SQLite.

Deployment

Thu, 15 Oct 2026 21:26:46 +0000

# Deployment

Audience: the operator installing ocbot on a host. Purpose: take a built binary to a running, self-healing, backed-up production deployment. Prerequisites: Getting started (the concepts: config, secrets, the chat surfaces); a Linux host with systemd and root.

# Environments

	Development	Production
Runs as	your user	dedicated `ocbot` / `opencode` users
Command	`cargo run --release` from the repo root	`/usr/local/bin/ocbot` via systemd
Config	`config/config.toml` in the repo	`/srv/ocbot/config/config.toml`
Secrets	shell environment	`/etc/ocbot/ocbot.env`, mode `0600`
Restarts	manual	`Restart=on-failure` + SIGTERM drain
Backups	none expected	nightly timer, 14-day retention
Chat surfaces	whatever `channel` selects	the same, plus `signal-cli.service` when `signal` is selected

# Deployment diagram

flowchart LR
    subgraph systemd["systemd"]
        u1["opencode.service<br/>user: opencode, 1500M cap"]
        u4["signal-cli.service<br/>user: ocbot, 512M cap<br/>socket /run/signal-cli/socket"]
        u2["ocbot.service<br/>user: ocbot, 200M cap"]
        u3["ocbot-backup.timer + .service<br/>nightly 03:30"]
    end
    u1 -- "serve 127.0.0.1:8080" --> oc["opencode v2"]
    u2 -- "REST + SSE (loopback)" --> oc
    u2 -- "JSON-RPC (unix socket)" --> u4
    u4 -- "E2E" --> phone["operator phone"]
    u2 --> repos["operator git repositories"]
    u2 --> db[("/srv/ocbot/ocbot.db<br/>WAL")]
    u3 -- "VACUUM INTO nightly" --> db
    u3 -- "identity keys nightly" --> u4
    u3 --> bk[("/srv/ocbot/backups<br/>14-day retention")]

ocbot.service wants opencode.service, but the order is a soft preference: if the server is not up yet, the bot starts in degraded mode and recovers on its own. signal-cli.service is optional: install it only when channel selects signal. ocbot.service orders itself after it when it exists, but does not require it — a dead daemon refuses the Signal surface and nothing else (D-10).

Operations

Thu, 15 Oct 2026 21:29:33 +0000

# Operations

Audience: the operator running a deployed bot. Purpose: know what to watch, what each signal means, and what to do when something breaks. Prerequisites: a running deployment (DEPLOYMENT ); the glossary .

# The three health surfaces

The chat surfaces — /status in Discourse server reachability and version, active actions, held locks, and pending gates. Announcements (server down, stream down) arrive as posts, once each.
The metrics endpoint — curl http://127.0.0.1:9464/metrics (loopback only, gate G18).
The logs — one JSON line per event via journalctl -u ocbot -o cat.

# Metrics reference

Every family exposed on 127.0.0.1:9464 (names are load-bearing — see crates/ocbot/src/app/metrics.rs):

Backup & restore runbook (NFR-12 / P15)

Thu, 15 Oct 2026 21:28:03 +0000

# Backup & restore runbook (NFR-12 / P15)

Git is the source of truth for accepted work; the SQLite file is the operator’s diary (labels, prompts, session mappings, decisions). Losing it loses no accepted work (P2) — but restoring it is cheap, so do it.

The nightly backup also archives the signal-cli identity keys, because those are the one thing no git history can rebuild: losing them means re-linking the number and re-verifying the safety number.

Testing

Fri, 30 Oct 2026 03:35:24 +0000

# Testing

Audience: contributors writing or running tests. Purpose: know which suite proves what, how to run it, and what a change must add. Prerequisites: a building workspace (CONTRIBUTING ); test crates are named there.

# The testing estate

ocbot’s tests are layered by how much of the world is real. Lower layers are fast and run on every PR; the top layers need a live server or a nightly runner.

Contributing

Tue, 13 Oct 2026 04:27:31 +0000

# Contributing

Audience: anyone who wants to change ocbot’s code or docs. Purpose: set up a dev environment, meet the quality floor, and get a PR merged. Prerequisites: Getting started through Step 3 (a building workspace); Architecture for the mental model.

# Dev setup

Install rustup↗ . The pinned toolchain (1.98.1) is selected automatically from rust-toolchain.toml — do not override it.

Clone and build:

git clone <TODO: repo URL>
cd ocbot
cargo build
cargo test --workspace

Install the auxiliary checkers CI uses (optional locally, required to reproduce CI):

Tool	What it does	Install
cargo-nextest	Faster test runner	`cargo install cargo-nextest --locked`
cargo-deny	Advisory/license/ban checks	`cargo install cargo-deny --locked`
cargo-machete	Unused dependency check	`cargo install cargo-machete`
cargo-llvm-cov	Coverage	`cargo install cargo-llvm-cov`
cargo-mutants	Mutation testing	`cargo install cargo-mutants`
typos-cli	Docs spelling	`cargo install typos-cli`

NFR measurements & enforcement

Thu, 08 Oct 2026 08:42:20 +0000

# NFR measurements & enforcement

Measured on the development host (Linux, sqlite 3.53.4, toolchain 1.98.1) on 2026-10-08. Each row names the mechanism that enforces the budget and, where it is a runtime number, the command that produced it.

NFR	Budget	Mechanism / measurement	Recorded
NFR-1 interaction ack	p99 < 1 s to defer; never > 3 s	The adapter defers before any handler work (ack discipline, §6.6), and the pre-defer plan phase is one SQLite read with no port call (`guard.rs` AC-1). `e2e_report_latency::plan_phase_stays_under_the_ack_budget` measures it over 1,000 button interactions and holds p99 < 50 ms.	p99 < 50 ms
NFR-2 idle→report	p95 < 5 s (polling fallback ≤ interval + 2 s)	`cargo test -p ocbot --test e2e_report_latency`: 100 cycles through the real client + adapter against wiremock; the test asserts p95 < 5 s. Suite wall time 0.24 s for 100 cycles ≈ 2.4 ms/cycle (≈3 orders under budget).	0.24 s / 100 cycles
NFR-3 report delivery	at-least-once; < 1 duplicate / 200	P9: the `report_msg_id IS NULL` CAS plus `notified` dedupe keys make detection exactly-once; only the Discord POST↔txn crash gap can duplicate (once per crash, never steady-state). `deliver_report` is covered by `store_cas::deliver_report_is_exactly_once` and `reconcile_boot`.	design + tests
NFR-4 decisions exactly-once	0 duplicate commits / 1,000 double-taps	`cargo test -p ocbot --test double_tap`: 1,000 randomized interleavings, exactly one commit (AC-5).	1,000 trials green
NFR-5 crash recovery	SIGKILL anywhere ⇒ consistent < 10 s, no lost work	`chaos_full` (11 labelled CP points, snapshot half) + `chaos_sigkill` (real SIGKILL at accept/park/reset). Boot reconcile is synchronous; the suites finish in < 0.1 s.	14 chaos tests green
NFR-6 memory	< 200 MB RSS steady	`scripts/measure-rss.sh` releases the binary against a dead opencode and reads `VmRSS`. 19,988 kB at 3 s. `deploy/ocbot.service` enforces `MemoryMax=200M` as the ceiling.	~20 MB
NFR-7 availability	single process, systemd `Restart=on-failure`, 99%/month	`deploy/ocbot.service`, `deploy/opencode.service`; no HA (self-hosted, single operator).	units committed
NFR-8 coverage/mutation	core ≥ 90% line+branch; proptest; scoped mutants	`scripts/coverage.sh` gates core ≥ 90, client ≥ 90, shell ≥ 70 (per-crate line coverage). Core is 94.72% by its own tests; mutation: `plan.rs` 52 mutants 0 missed, `paths.rs` 95/100, `stall.rs` 10/10 (residuals in COMPAT/PHASE-7).	gates green
NFR-9 observability	JSON logs; metrics on `127.0.0.1:9464`; every transition logged	`metrics.rs` asserts the HTTP endpoint exposes every §6.8 family; `logging.rs` writes JSON with a secret-scrubbing writer (`redaction.rs`).	endpoint test green
NFR-10 security gates	zero secrets in logs; spawn/exit confined; no `unwrap` in core; `clippy -D warnings`	`scripts/gates.sh` G3–G19; clippy restriction lints; `logging` scrub layer.	gates green
NFR-11 layering	`ocbot-core` declares no I/O deps	`gates.sh` G2: `cargo tree -e normal -p ocbot-core` fails on serenity/tokio/reqwest/rusqlite/opencode-v2-client.	gap 2 green
NFR-12 backup	nightly `VACUUM INTO`, 14-day retention, restore drilled	`deploy/ocbot-backup.{service,timer}` + `scripts/backup.sh`; `scripts/restore-drill.sh` run recorded in `docs/RESTORE.md`.	drill green

# Coverage by crate

Measured per crate (each runner’s own tests) and gated by scripts/coverage.sh (2026-10-08). The gate floor is per crate: a crate’s gate reflects its own tests, not coverage donated by another crate’s integration suite.

Search

Mon, 01 Jan 0001 00:00:00 +0000

Type to search the full documentation index. Results are ranked by title and content matches. Without JavaScript, the complete page list is rendered below the search box — use your browser’s find-in-page.