Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

docs(agents): keep blocking work off the service event loop (#2533)

Call White9cfacad93bd8
diff --git a/AGENTS.md b/AGENTS.md
index b7cc09690..e2ffc38e1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -241,6 +241,34 @@ Source-of-truth rule:
- add new IM integrations under `modules/im/` and new agent backends under `modules/agents/`
- no repo-wide formatter is enforced; keep diffs focused if you use Black/Ruff
+### Controller Event Loop
+
+- The controller's asyncio loop (`core/controller.py`) runs every session's
+ turns, the scheduler, and the local Model Hub gateway, so anything that blocks
+ it stalls all of them at once. IM transports run on their own threads and
+ loops.
+- Code reachable on that loop must not block it. Synchronous waits
+ (`time.sleep`, `subprocess.run` and similar, `Future.result()`, lock waits),
+ reads or rewrites of files that grow with use, and SQLite work that is not a
+ bounded, index-keyed statement belong on a thread (an existing executor or
+ `asyncio.to_thread`). Async-native equivalents such as `await asyncio.sleep()`
+ and `asyncio.create_subprocess_exec` are fine on the loop.
+- A query on a per-turn, per-message, or per-tick path must touch only rows
+ bounded by the work in hand, not by history. In `EXPLAIN QUERY PLAN`, a
+ growing table such as `messages`, `agent_events`, or `agent_runs` must be
+ reached by a `SEARCH` whose keys bound the matched rows that way, such as a
+ session or turn id, or a status that only live work has. An
+ `ORDER BY ... LIMIT` must not need a `USE TEMP B-TREE` over a growing set. Pin
+ the plan in a test, and add indexes through an alembic migration.
+- Keep write transactions short, and build them from such bounded statements.
+ While one holds SQLite's write lock, other writers wait for it, including
+ those on the loop, for up to the 5 s `busy_timeout` set in `storage/db.py`.
+- `core/loop_watchdog.py` reports controller-loop stalls in
+ `~/.avibe/logs/vibe_remote.log`; its module documents the detection threshold
+ and rate limits. A stall reported while the loop is serving work is a defect.
+ One reported during shutdown cleanup, after the loop has stopped, comes from
+ an expected bounded wait.
+
### Web UI Server
- `vibe/ui_server.py` is served by FastAPI/uvicorn; new UI routes should use native async FastAPI patterns where practical.