API & Architecture

REST endpoints, WebSocket protocol, MCP tools, and system design.

System Overview

architecture
Angular UI
Port 4200
Bun Server
Port 3000
Claude SDK
Subprocess
SQLite DB
Persistence
MCP Server
9 Tools
AlgoChat
(optional)

Project Structure

tree 
corvid-agent/
├── server/              # Bun HTTP + WebSocket server
│   ├── algochat/        # On-chain messaging layer
│   ├── db/              # SQLite schema & queries
│   ├── lib/             # Logger, crypto, validation
│   ├── mcp/             # MCP tool server & handlers
│   ├── middleware/       # Auth, CORS
│   ├── process/         # Agent lifecycle & SDK integration
│   ├── routes/          # REST API endpoints
│   ├── work/            # Git worktree & work tasks
│   ├── ws/              # WebSocket handler
│   └── index.ts         # Entry point
├── client/              # Angular 21 SPA
├── shared/              # Shared types & WS protocol
├── deploy/              # Docker, systemd, nginx, Caddy
└── e2e/                 # Playwright tests

REST API

All endpoints prefixed with /api. Auth via Authorization: Bearer <API_KEY> when remote.

Agents

GET /api/agents List all agents
POST /api/agents Create agent
GET /api/agents/:id Get agent by ID
PUT /api/agents/:id Update agent
DEL /api/agents/:id Delete agent
GET /api/agents/:id/balance Check wallet balance
POST /api/agents/:id/fund Fund agent wallet
POST /api/agents/:id/invoke Send message to agent
GET /api/agents/:id/messages Agent-to-agent message history

Sessions

GET /api/sessions List sessions (?projectId filter)
POST /api/sessions Create & start session
GET /api/sessions/:id Get session details
PUT /api/sessions/:id Update session
DEL /api/sessions/:id Delete session
GET /api/sessions/:id/messages Get message history
POST /api/sessions/:id/stop Stop running session
POST /api/sessions/:id/resume Resume paused session

Projects

GET /api/projects List projects
POST /api/projects Create project
GET /api/projects/:id Get project
PUT /api/projects/:id Update project
DEL /api/projects/:id Delete project

Councils

GET /api/councils List councils
POST /api/councils Create council
GET /api/councils/:id Get council
PUT /api/councils/:id Update council
DEL /api/councils/:id Delete council
POST /api/councils/:id/launch Launch deliberation
GET /api/councils/:id/launches List launches for council

Council Launches

GET /api/council-launches List launches (?councilId filter)
GET /api/council-launches/:id Get launch details
GET /api/council-launches/:id/logs Get launch logs
GET /api/council-launches/:id/discussion-messages Get discussion messages
POST /api/council-launches/:id/abort Abort launch
POST /api/council-launches/:id/review Start review stage
POST /api/council-launches/:id/synthesize Start synthesis stage
POST /api/council-launches/:id/chat Follow-up chat on completed council

Work Tasks

GET /api/work-tasks List tasks (?agentId filter)
POST /api/work-tasks Create work task
GET /api/work-tasks/:id Get task status
POST /api/work-tasks/:id/cancel Cancel running task

Wallets

GET /api/wallets/summary External wallet summary (?search)
GET /api/wallets/:address/messages Messages for wallet (?limit, ?offset)

Allowlist

GET /api/allowlist List allowlisted addresses
POST /api/allowlist Add address to allowlist
PUT /api/allowlist/:address Update allowlist entry
DEL /api/allowlist/:address Remove from allowlist

System

GET /api/health Server health check
GET /api/browse-dirs Browse filesystem directories
GET /api/operational-mode Get operational mode
POST /api/operational-mode Set operational mode
GET /api/escalation-queue List pending approvals
POST /api/escalation-queue/:id/resolve Resolve escalation
GET /api/feed/history Activity feed history
POST /api/backup Create database backup
POST /api/selftest/run Run self-tests (unit/e2e/all)

AlgoChat

GET /api/algochat/status Connection status
POST /api/algochat/network Switch network (testnet/mainnet)
POST /api/algochat/conversations List conversations

MCP API

POST /api/mcp/send-message Send message via MCP
POST /api/mcp/save-memory Save memory via MCP
POST /api/mcp/recall-memory Recall memory via MCP
GET /api/mcp/list-agents List agents via MCP

WebSocket Protocol

Connect to ws://localhost:3000. All messages are JSON.

Client → Server

// Subscribe to session events
{ "type": "subscribe",
  "sessionId": "..." }

// Unsubscribe from session
{ "type": "unsubscribe",
  "sessionId": "..." }

// Send message to session
{ "type": "send_message",
  "sessionId": "...",
  "content": "..." }

// Quick chat with agent
{ "type": "chat_send",
  "agentId": "...",
  "content": "..." }

// Approve/deny tool use
{ "type": "approval_response",
  "requestId": "...",
  "behavior": "allow" }

// Agent-to-agent invoke
{ "type": "agent_invoke",
  "fromAgentId": "...",
  "toAgentId": "...",
  "content": "..." }

// Reward agent (ALGO)
{ "type": "agent_reward",
  "agentId": "...",
  "microAlgos": 1000000 }

// Create work task
{ "type": "create_work_task",
  "agentId": "...",
  "description": "..." }

Server → Client

// Session stream events
{ "type": "session_event",
  "sessionId": "...",
  "event": { ... } }

// Session status changes
{ "type": "session_status",
  "sessionId": "...",
  "status": "running" }

// AlgoChat messages
{ "type": "algochat_message",
  "participant": "...",
  "direction": "inbound" }

// Approval requests
{ "type": "approval_request",
  "request": { "id": "...",
    "toolName": "..." } }

// Chat stream / tool / thinking
{ "type": "chat_stream",
  "agentId": "...",
  "chunk": "...", "done": false }
{ "type": "chat_tool_use" }
{ "type": "chat_thinking" }

// Work task & council updates
{ "type": "work_task_update" }
{ "type": "council_stage_change" }
{ "type": "council_log" }
{ "type": "council_discussion_message" }

// Balance & errors
{ "type": "agent_balance" }
{ "type": "error",
  "message": "..." }

MCP Tools

Tools available to agents via the Model Context Protocol. 7 default + 2 privileged.

corvid_send_message

Send a message to another agent and wait for response. Supports threaded conversations.

to_agent message thread

corvid_save_memory

Save an encrypted private note. Persists across sessions with optional on-chain audit.

key content

corvid_recall_memory

Recall previously saved memories. Exact key lookup or keyword search.

key query

corvid_list_agents

Discover available agents. Returns names, IDs, and wallet addresses.

corvid_extend_timeout

Request more time for the current session. Max 120 minutes per call.

minutes

corvid_check_credits

Check credit balance for a wallet address. Credits are consumed per turn.

wallet_address

corvid_create_work_task

Spawn a new agent on a dedicated branch. Implements changes, validates, and opens a PR.

description project_id

Privileged Tools

Require explicit grant in mcp_tool_permissions:

corvid_grant_credits — Grant free credits to a wallet (max 1M per call)
corvid_credit_config — View or update credit system configuration

Session Lifecycle

lifecycle
Created
Running
Paused
Resumed
context reset
(every 8 turns)
Timeout
Stopped
Running
Auto-resume backoff: 5m → 15m → 45m → 60m cap
Default timeout: 30 minutes (configurable)

Sources

Sessions can originate from: web (UI), algochat (on-chain), or agent (inter-agent).

Context Reset

After 8 turns, the SDK process is killed and restarted to prevent context window bloat.

Protected Files

Agents cannot modify critical files like package.json, schema.ts, or .env even in full-auto mode.

Database Schema

SQLite via bun:sqlite. Schema version 23. Auto-migrates on startup.

Core

projects — workingDir, env_vars
agents — name, model, wallet
sessions — status, cost, source
session_messages — role, content
daily_spending — date, total
escalation_queue — pending approvals

Messaging

algochat_conversations
algochat_messages — content, txid
algochat_psk_state_v2 — PSK handshake
algochat_allowlist — address, label
agent_messages — from, to, txid
agent_memories — encrypted

Advanced

councils — members, rounds
council_members
council_launches — stage
council_launch_logs
council_discussion_messages
credit_ledger — wallet, balance
credit_transactions
credit_config
work_tasks — status, branch

Related Docs

Getting Started →

Installation, configuration, and first steps.

AlgoChat Explainer →

On-chain messaging, PSK encryption, and commands.

Source Code →

Browse the full repository on GitHub.