docs: add 11 new documentation files across all categories
New reference docs: - agents/ref-btmsg.md: inter-agent messaging schema and CLI - agents/ref-bttask.md: kanban task board operations - providers/ref-providers.md: Claude/Codex/Ollama/Aider comparison - config/ref-settings.md: (already committed) New guides: - contributing/dual-repo-workflow.md: community vs commercial repos - plugins/guide-developing.md: Web Worker sandbox API and publishing New pro docs: - pro/features/knowledge-base.md: persistent memory + symbol graph - pro/features/git-integration.md: context injection + branch policy - pro/marketplace/README.md: 13 plugins catalog Split files: - architecture/data-model.md: from architecture.md (schemas, layout) - production/hardening.md: from production.md (supervisor, sandbox, WAL) - production/features.md: from production.md (FTS5, plugins, secrets, audit)
This commit is contained in:
Hibryda
parent
8251321dac
commit
b6c1d4b6af
11 changed files with 2198 additions and 0 deletions
186
docs/agents/ref-btmsg.md
Normal file
186
docs/agents/ref-btmsg.md
Normal file
|
|
@ -0,0 +1,186 @@
|
|||
# btmsg Reference
|
||||
|
||||
btmsg is the inter-agent messaging system for Agents Orchestrator. It enables
|
||||
management agents (Tier 1) and project agents (Tier 2) to communicate via direct
|
||||
messages and broadcast channels.
|
||||
|
||||
## Overview
|
||||
|
||||
btmsg uses a shared SQLite database at `~/.local/share/agor/btmsg.db`. Both the
|
||||
Python CLI tools (used by agents) and the Rust backend (Tauri app) access the
|
||||
same database concurrently. WAL mode and a 5-second busy timeout handle
|
||||
contention.
|
||||
|
||||
Agents must register before sending or receiving messages. Registration creates
|
||||
an entry in the `agents` table with the agent's ID, name, role, group, and tier.
|
||||
|
||||
## Database schema
|
||||
|
||||
### agents
|
||||
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `id` | TEXT PK | Unique agent identifier |
|
||||
| `name` | TEXT | Display name |
|
||||
| `role` | TEXT | Agent role (manager, architect, tester, reviewer, or project) |
|
||||
| `group_id` | TEXT | Group this agent belongs to |
|
||||
| `tier` | INTEGER | 1 = management, 2 = project |
|
||||
| `model` | TEXT | Model identifier (nullable) |
|
||||
| `status` | TEXT | Current status (active, sleeping, stopped) |
|
||||
|
||||
### messages
|
||||
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `id` | TEXT PK | UUID |
|
||||
| `from_agent` | TEXT FK | Sender agent ID |
|
||||
| `to_agent` | TEXT FK | Recipient agent ID |
|
||||
| `content` | TEXT | Message body |
|
||||
| `read` | INTEGER | 0 = unread, 1 = read |
|
||||
| `reply_to` | TEXT | Parent message ID (nullable, for threading) |
|
||||
| `sender_group_id` | TEXT | Sender's group ID (nullable, added by migration) |
|
||||
| `created_at` | TEXT | ISO timestamp |
|
||||
|
||||
### channels
|
||||
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `id` | TEXT PK | Channel identifier |
|
||||
| `name` | TEXT | Channel name (e.g. `#review-queue`) |
|
||||
| `group_id` | TEXT | Group this channel belongs to |
|
||||
| `created_by` | TEXT FK | Agent that created the channel |
|
||||
| `created_at` | TEXT | ISO timestamp |
|
||||
|
||||
### contacts
|
||||
|
||||
ACL table controlling which agents can see and message each other.
|
||||
|
||||
### heartbeats
|
||||
|
||||
Liveness tracking. Agents send periodic heartbeats; the health store uses these
|
||||
to detect stalled agents.
|
||||
|
||||
### dead_letter_queue
|
||||
|
||||
Messages that could not be delivered (recipient not found, agent stopped).
|
||||
Surfaced in the agent health monitoring UI.
|
||||
|
||||
### audit_log
|
||||
|
||||
Records agent actions for compliance and debugging. Entries include agent ID,
|
||||
action type, target, and timestamp.
|
||||
|
||||
### seen_messages
|
||||
|
||||
Per-message read tracking with session-level granularity.
|
||||
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `session_id` | TEXT | Reading session identifier |
|
||||
| `message_id` | TEXT FK | Message that was seen |
|
||||
| `seen_at` | INTEGER | Unix timestamp |
|
||||
|
||||
Primary key: `(session_id, message_id)`. This enables per-message acknowledgment
|
||||
rather than bulk "mark all read" operations.
|
||||
|
||||
## CLI usage
|
||||
|
||||
The `btmsg` CLI is a Python script installed at `~/.local/bin/btmsg`. Agents
|
||||
invoke it via shell commands in their sessions. The `BTMSG_AGENT_ID` environment
|
||||
variable identifies the calling agent.
|
||||
|
||||
### Register an agent
|
||||
|
||||
```bash
|
||||
btmsg register --id mgr-1 --name "Manager" --role manager \
|
||||
--group my-team --tier 1
|
||||
```
|
||||
|
||||
### Send a direct message
|
||||
|
||||
```bash
|
||||
btmsg send --to architect-1 --content "Review the auth module architecture"
|
||||
```
|
||||
|
||||
### Send to a channel
|
||||
|
||||
```bash
|
||||
btmsg channel-post --channel review-queue \
|
||||
--content "Task T-42 moved to review"
|
||||
```
|
||||
|
||||
### Read unread messages
|
||||
|
||||
```bash
|
||||
btmsg read
|
||||
```
|
||||
|
||||
Returns all unread messages for the agent identified by `BTMSG_AGENT_ID`.
|
||||
|
||||
### List channels
|
||||
|
||||
```bash
|
||||
btmsg channels
|
||||
```
|
||||
|
||||
### Send a heartbeat
|
||||
|
||||
```bash
|
||||
btmsg heartbeat
|
||||
```
|
||||
|
||||
Updates the agent's liveness timestamp. The health store marks agents as stalled
|
||||
if no heartbeat arrives within the configured `stallThresholdMin`.
|
||||
|
||||
### Mark messages as seen
|
||||
|
||||
```bash
|
||||
btmsg ack --message-id <uuid>
|
||||
```
|
||||
|
||||
Records an entry in `seen_messages` for per-message tracking.
|
||||
|
||||
## Role permissions
|
||||
|
||||
Agent capabilities depend on their role:
|
||||
|
||||
| Capability | Manager | Architect | Tester | Reviewer | Project |
|
||||
|------------|---------|-----------|--------|----------|---------|
|
||||
| Send DMs | Yes | Yes | Yes | Yes | Yes |
|
||||
| Read own DMs | Yes | Yes | Yes | Yes | Yes |
|
||||
| Post to channels | Yes | Yes | Yes | Yes | Yes |
|
||||
| Create channels | Yes | No | No | No | No |
|
||||
| Delete messages | Yes | No | No | No | No |
|
||||
| List all agents | Yes | Yes | Yes | Yes | Read-only |
|
||||
| Update agent status | Yes | No | No | No | No |
|
||||
|
||||
The Manager role has full CRUD on all btmsg resources. Other roles can read
|
||||
messages addressed to them and post to channels.
|
||||
|
||||
## Rust backend integration
|
||||
|
||||
The Tauri backend reads btmsg data via `src-tauri/src/btmsg.rs`. Key functions:
|
||||
|
||||
- `get_agents(group_id)` -- List agents with unread counts
|
||||
- `unread_count(agent_id)` -- Unread message count
|
||||
- `unread_messages(agent_id)` -- Full unread message list with sender metadata
|
||||
- `get_feed(group_id)` -- Recent messages across the group
|
||||
- `get_channels(group_id)` -- List channels with member counts
|
||||
- `get_channel_messages(channel_id)` -- Messages in a channel
|
||||
|
||||
All queries use named column access (`row.get("column_name")`) and return
|
||||
`#[serde(rename_all = "camelCase")]` structs for direct JSON serialization to the
|
||||
frontend.
|
||||
|
||||
## Frontend
|
||||
|
||||
The frontend accesses btmsg through `src/lib/adapters/btmsg-bridge.ts`, which
|
||||
wraps Tauri IPC commands. The CommsTab component in ProjectBox displays messages
|
||||
and channels for management agents.
|
||||
|
||||
## Review queue integration
|
||||
|
||||
When a task transitions to `review` status via bttask, the system auto-posts a
|
||||
notification to the `#review-queue` channel. The `ensure_review_channels`
|
||||
function creates `#review-queue` and `#review-log` idempotently. See
|
||||
[bttask reference](ref-bttask.md) for details.
|
||||
161
docs/agents/ref-bttask.md
Normal file
161
docs/agents/ref-bttask.md
Normal file
|
|
@ -0,0 +1,161 @@
|
|||
# bttask Reference
|
||||
|
||||
bttask is the kanban task board for Agents Orchestrator. It provides structured
|
||||
task tracking for multi-agent workflows, with optimistic locking to prevent
|
||||
concurrent update conflicts.
|
||||
|
||||
## Overview
|
||||
|
||||
Tasks are stored in the shared `btmsg.db` SQLite database at
|
||||
`~/.local/share/agor/btmsg.db`. The `bttask` CLI (Python, installed at
|
||||
`~/.local/bin/bttask`) gives agents direct access. The Rust backend
|
||||
(`src-tauri/src/bttask.rs`) provides read/write access for the Tauri frontend.
|
||||
|
||||
## Task schema
|
||||
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `id` | TEXT PK | UUID |
|
||||
| `title` | TEXT | Short task title |
|
||||
| `description` | TEXT | Detailed description |
|
||||
| `status` | TEXT | Current column (see below) |
|
||||
| `priority` | TEXT | `low`, `medium`, or `high` |
|
||||
| `assigned_to` | TEXT | Agent ID (nullable) |
|
||||
| `created_by` | TEXT | Agent ID that created the task |
|
||||
| `group_id` | TEXT | Group this task belongs to |
|
||||
| `parent_task_id` | TEXT | Parent task for subtasks (nullable) |
|
||||
| `sort_order` | INTEGER | Display order within column |
|
||||
| `version` | INTEGER | Optimistic locking version (default 1) |
|
||||
| `created_at` | TEXT | ISO timestamp |
|
||||
| `updated_at` | TEXT | ISO timestamp |
|
||||
|
||||
### Task comments
|
||||
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `id` | TEXT PK | UUID |
|
||||
| `task_id` | TEXT FK | Parent task |
|
||||
| `agent_id` | TEXT | Commenting agent |
|
||||
| `content` | TEXT | Comment body |
|
||||
| `created_at` | TEXT | ISO timestamp |
|
||||
|
||||
## Kanban columns
|
||||
|
||||
Tasks move through 5 statuses:
|
||||
|
||||
```
|
||||
backlog -> todo -> in_progress -> review -> done
|
||||
```
|
||||
|
||||
The frontend (`TaskBoardTab.svelte`) renders these as columns in a kanban board,
|
||||
polling every 5 seconds for updates.
|
||||
|
||||
## Operations
|
||||
|
||||
### list_tasks
|
||||
|
||||
Returns all tasks for a group, ordered by `sort_order` then `created_at DESC`.
|
||||
|
||||
### create_task
|
||||
|
||||
Creates a new task with the given title, description, priority, and optional
|
||||
assignment. Returns the created task with its generated ID.
|
||||
|
||||
### update_task_status
|
||||
|
||||
Moves a task to a new status. Uses optimistic locking: the caller must provide
|
||||
the current `version` value. If the version in the database does not match, the
|
||||
update is rejected with a conflict error. On success, the version is
|
||||
incremented.
|
||||
|
||||
```
|
||||
update_task_status(task_id, new_status, expected_version)
|
||||
```
|
||||
|
||||
### delete_task
|
||||
|
||||
Removes a task by ID.
|
||||
|
||||
### add_comment
|
||||
|
||||
Adds a comment to a task. Any agent can comment regardless of role.
|
||||
|
||||
### task_comments
|
||||
|
||||
Returns all comments for a task, ordered by `created_at ASC`.
|
||||
|
||||
### review_queue_count
|
||||
|
||||
Returns the number of tasks currently in `review` status for a group. Used by
|
||||
the health store to calculate reviewer attention scoring (10 points per review
|
||||
task, capped at 50).
|
||||
|
||||
## CLI usage
|
||||
|
||||
Agents interact with bttask through shell commands. The `BTMSG_AGENT_ID`
|
||||
environment variable identifies the calling agent.
|
||||
|
||||
```bash
|
||||
# List all tasks
|
||||
bttask list
|
||||
|
||||
# Create a task
|
||||
bttask create --title "Fix auth bug" --priority high \
|
||||
--description "Token refresh fails after 24h"
|
||||
|
||||
# Move a task to in_progress
|
||||
bttask status --id T-42 --status in_progress --version 1
|
||||
|
||||
# Add a comment
|
||||
bttask comment --id T-42 --content "Root cause identified: expired refresh token"
|
||||
|
||||
# Delete a task
|
||||
bttask delete --id T-42
|
||||
```
|
||||
|
||||
## Role permissions
|
||||
|
||||
| Capability | Manager | Reviewer | Others |
|
||||
|------------|---------|----------|--------|
|
||||
| List tasks | Yes | Yes | Yes |
|
||||
| Create tasks | Yes | No | No |
|
||||
| Update status | Yes | Yes | Read-only |
|
||||
| Delete tasks | Yes | No | No |
|
||||
| Add comments | Yes | Yes | Yes |
|
||||
|
||||
The Manager role has full CRUD. The Reviewer can change task status (to move
|
||||
items through the review pipeline) and add comments. Other roles have read-only
|
||||
access to tasks but can add comments.
|
||||
|
||||
## Review queue integration
|
||||
|
||||
When a task moves to `review` status, the system auto-posts a notification to
|
||||
the `#review-queue` btmsg channel. This triggers the Reviewer agent's attention
|
||||
scoring. The `ensure_review_channels` function creates `#review-queue` and
|
||||
`#review-log` channels idempotently on first use.
|
||||
|
||||
The `review_queue_count` is polled every 10 seconds by ProjectBox for reviewer
|
||||
agents and fed into the health store's `setReviewQueueDepth()` for attention
|
||||
scoring. Review tasks contribute to the reviewer's attention score:
|
||||
|
||||
- 10 points per task in review status
|
||||
- Capped at 50 points total
|
||||
- Priority rank: between `file_conflict` (70) and `context_high` (40)
|
||||
|
||||
## Optimistic locking
|
||||
|
||||
Every task has a `version` field starting at 1. When an agent updates a task's
|
||||
status, it must pass the expected version. If another agent modified the task
|
||||
since it was read, the version will not match and the update fails with a
|
||||
conflict error. The calling agent should re-read the task and retry.
|
||||
|
||||
This prevents race conditions when multiple agents attempt to move the same task
|
||||
simultaneously.
|
||||
|
||||
## Frontend
|
||||
|
||||
The kanban board is rendered by `src/lib/components/Workspace/TaskBoardTab.svelte`,
|
||||
available in the Tasks tab for Manager-role agents. It polls `list_tasks` every
|
||||
5 seconds and supports drag-style status transitions between columns.
|
||||
|
||||
IPC adapter: `src/lib/adapters/bttask-bridge.ts`.
|
||||
Loading…
Add table
Add a link
Reference in a new issue