# Архитектура Agent Control Center

**Версия:** 0.1.0-draft
**Дата:** 2026-07-19
**Нормативность:** supporting architecture; при конфликте приоритет у `SPECIFICATION.md`.

## 1. Контекст

Система разделяется на центральный Control Plane и один или несколько Connector, установленных рядом с серверными агентами. Клиенты не подключаются к агентам напрямую. Connector устанавливает исходящее mTLS/WebSocket-соединение, поэтому MVP не требует открывать входящий порт на каждом сервере агента.

```mermaid
flowchart LR
  W[Web / PWA] -->|HTTPS + WSS| API[Control Plane API]
  D[Desktop] -->|HTTPS + WSS| API
  M[Android] -->|HTTPS + WSS| API
  API --> IAM[Identity & Policy]
  API --> CORE[Projects / Tasks / Runs]
  API --> CTX[Context Broker]
  API --> REG[Memory / Skills / Wiki]
  CORE --> BUS[Durable Event Bus]
  CTX --> BUS
  BUS --> GW[Connector Gateway]
  GW <-->|outbound mTLS WSS| C1[Server Connector]
  C1 --> H[Hermes adapter]
  C1 --> O[OpenClaw adapter]
  C1 --> C[Claude adapter]
  C1 --> X[Codex adapter]
  C1 --> G[Gemini adapter]
  C1 --> P[Generic API/CLI/MCP adapter]
  CORE --> PG[(PostgreSQL)]
  REG --> OBJ[(Object Storage)]
  REG --> VEC[(Vector Index)]
```

## 2. Клиенты

Предлагаемый baseline, подлежащий утверждению ADR:

- **UI core:** React + TypeScript, responsive design, offline-capable read cache.
- **Web:** PWA, основной административный клиент.
- **Desktop:** Tauri wrapper для native notifications, secure local storage и controlled file pickers.
- **Android:** Capacitor wrapper над тем же UI core; native bridge только для push, biometrics, share/open-file и encrypted storage.

Запрещено помещать provider/server credentials в web bundle. Desktop/Android хранят только refresh credential устройства в OS keystore. Все provider credentials остаются на Connector или в серверном secret manager.

## 3. Control Plane компоненты

| Компонент | Ответственность | Не отвечает за |
|---|---|---|
| API Gateway | REST/WS, schema validation, idempotency, rate limits | бизнес-оркестрацию |
| Identity & Policy | OIDC/local bootstrap, RBAC/ABAC, device sessions, approvals | provider auth внутри Connector |
| Project Service | workspaces, projects, tasks, dependencies, artifacts | запуск runtime |
| Run Orchestrator | run state machine, leases, retries, cancel, handoff | интерпретацию vendor payload |
| Connector Gateway | регистрацию Connector, command/event delivery, health | исполнение adapter process |
| Context Broker | сбор bounded context bundle, redaction, token budgeting | хранение скрытого chain-of-thought |
| Memory Service | scoped/versioned memory, provenance, conflicts, retrieval | автоматическое объявление непроверенных выводов фактами |
| Skill Registry | immutable versions, review/signature state, compatibility | молчаливое выполнение skill-кода |
| Wiki Service | Markdown pages, versions, links, search | замена source artifacts |
| Usage Service | нормализованные usage/quota/budget signals | обещание точного остатка при отсутствии API |
| Audit Service | append-only security and lifecycle events | хранение секретов и полного sensitive content |
| Notification Service | in-app/push/email hooks, dedupe | authoritative task state |

## 4. Connector

### 4.1 Trust boundary

Connector — отдельный сервис с уникальной identity и минимальными правами. Он:

1. устанавливает только исходящее соединение;
2. исполняет команды с lease/idempotency key;
3. запускает adapters в отдельных OS identities/containers, где возможно;
4. не передаёт секреты в Control Plane;
5. redacts события до отправки;
6. хранит короткий encrypted spool при разрыве связи;
7. не принимает новый destructive action без policy/approval token.

### 4.2 Agent Adapter Protocol (AAP)

Версионированный внутренний контракт:

```text
handshake() -> identity, adapter_version, runtime_version, capabilities
health() -> status, latency, active_runs
start(run_spec, context_bundle, approval_token?) -> native_run_ref
stream(native_run_ref, cursor) -> ordered normalized events
checkpoint(native_run_ref, reason) -> observable checkpoint
cancel(native_run_ref, mode) -> outcome
resume(native_run_ref | checkpoint) -> outcome
usage(scope) -> measured|estimated|unknown signal
artifacts(native_run_ref) -> metadata + content references
```

Обязательные envelope-поля: `schema_version`, `connector_id`, `agent_id`, `run_id`, `event_id`, `sequence`, `occurred_at`, `classification`, `payload`, `vendor_extension`. Команды идемпотентны; события дедуплицируются по `(connector_id,event_id)`.

Capabilities включают как минимум: `stream`, `cancel`, `native_resume`, `checkpoint`, `approvals`, `tools`, `mcp`, `artifacts`, `usage_exact`, `usage_estimated`, `filesystem_scope`, `structured_output`. Отсутствующая capability никогда не симулируется молча.

## 5. Run и handoff state machine

```mermaid
stateDiagram-v2
  [*] --> queued
  queued --> dispatching
  dispatching --> running
  running --> waiting_approval
  waiting_approval --> running
  running --> checkpointing
  checkpointing --> handoff_ready
  handoff_ready --> dispatching: target selected
  running --> succeeded
  running --> failed
  running --> cancelling
  cancelling --> cancelled
  dispatching --> blocked
  handoff_ready --> blocked
  blocked --> handoff_ready: user requests target selection
```

Handoff — новая attempt в рамках той же TaskRun lineage, а не перенос непрозрачной provider session. Handoff bundle содержит objective, acceptance criteria, bounded conversation, verified memory, decisions, completed/pending work, artifact refs, observed errors и provenance. Target adapter подтверждает ingestion; только после этого lease предыдущего attempt закрывается.

Автоматический fallback в MVP может **предложить** target, но не запускает платный или более привилегированный runtime без policy и, где требуется, user approval. Из `blocked` пользователь возвращает run в `handoff_ready`, чтобы выбрать совместимый target, либо явно отменяет run через обычный cancel flow.

## 6. Общий контекст

### 6.1 Scopes

`organization -> workspace -> project -> task -> run`; отдельно существуют `user-private` и `agent-private`. Более узкая область наследует разрешённые записи широкой области, но не наоборот.

### 6.2 Memory entry

Поля: `id`, `scope`, `kind`, `content`, `summary`, `provenance`, `confidence`, `verification_state`, `sensitivity`, `valid_from`, `valid_until`, `supersedes`, `acl`, `created_by`, `created_at`, `content_hash`.

Kinds: fact, decision, constraint, preference, lesson, entity, artifact_reference, run_summary. Непроверенный вывод агента имеет `verification_state=unverified`; conflict не перезаписывается, а создаёт новую версию и conflict record.

### 6.3 Skills

Skill package содержит manifest, Markdown instructions, optional assets/scripts, compatibility, permissions, provenance, digest, signature/review state. Версии immutable. Активация executable части требует policy review; downloaded/untrusted package по умолчанию quarantined.

### 6.4 Wiki

Markdown source, immutable revisions, backlinks, aliases, attachments, ACL и full-text/semantic search. Автосформированная страница сначала draft и показывает источники; публикация в authoritative namespace требует review.

## 7. Данные

Основные сущности:

- Organization, User, DeviceSession, RoleBinding;
- Workspace, Project, Task, TaskDependency, AcceptanceCriterion;
- Connector, Agent, Adapter, CapabilitySnapshot, CredentialReference;
- Conversation, Message, TaskRun, RunAttempt, RunEvent, Approval, Checkpoint;
- Artifact, ArtifactVersion;
- MemoryEntry, MemoryVersion, MemoryConflict;
- Skill, SkillVersion, SkillActivation;
- WikiPage, WikiRevision, WikiLink;
- UsageSignal, BudgetPolicy, AuditEvent, Notification.

PostgreSQL — authoritative metadata; object storage — artifacts/packages; vector index — derived retrieval index. Удаление vector index не должно уничтожать source content; индекс полностью перестраиваем.

## 8. API baseline

REST commands используют `Idempotency-Key`; event subscriptions — WSS с resume cursor.

```text
POST   /v1/workspaces
GET    /v1/projects/{projectId}
POST   /v1/projects/{projectId}/tasks
PATCH  /v1/tasks/{taskId}
POST   /v1/connectors/enrollment-tokens
GET    /v1/agents?project_id=&capability=
POST   /v1/tasks/{taskId}/runs
POST   /v1/runs/{runId}/approvals/{approvalId}
POST   /v1/runs/{runId}/checkpoint
POST   /v1/runs/{runId}/handoffs
POST   /v1/runs/{runId}/cancel
GET    /v1/runs/{runId}/events?cursor=
POST   /v1/memory/query
POST   /v1/memory/entries
POST   /v1/skills/{skillId}/versions
POST   /v1/skills/{skillId}/activations
PUT    /v1/wiki/pages/{pageId}
GET    /v1/usage/summary
GET    /v1/audit/events
WS     /v1/events?cursor=
```

Error envelope: `code`, `message`, `correlation_id`, `retryable`, `details`. Optimistic writes use `If-Match`/revision. Server timestamps are authoritative.

## 9. Deployment baseline

- self-hosted single-node MVP: container compose, PostgreSQL, S3-compatible storage, embedded/managed queue;
- production profile: redundant stateless API, managed PostgreSQL/object store, durable queue, separate workers;
- Connector upgrades are staged, signed, rollback-capable and never forced during active run;
- configuration is declarative; secrets supplied only through secret manager/file descriptors, not committed env files;
- migrations are forward-compatible for one release and have restore-tested rollback/roll-forward procedure.

## 10. Threat model summary

Threat actors: compromised agent, malicious skill, prompt injection in artifact/wiki, stolen device, rogue Connector, tenant user exceeding privilege, supply-chain compromise, replayed command, poisoned memory.

Controls: tenant isolation, mTLS device identity, short-lived command tokens, RBAC/ABAC, human approvals, immutable audit, content classification/redaction, egress policy, adapter sandbox, skill quarantine/signatures, provenance-aware retrieval, idempotency/replay protection, secret references, encrypted backup, revocation.

## 11. ADRs required before implementation

1. ADR-001 UI wrappers: Tauri + Capacitor versus alternative shared-client stack.
2. ADR-002 deployment topology and supported database/queue profile.
3. ADR-003 authentication: local bootstrap, OIDC providers, enterprise SSO phase.
4. ADR-004 vector backend and embedding data residency.
5. ADR-005 Connector sandbox baseline for Linux/Windows/macOS servers.
6. ADR-006 adapter SDK language and process isolation model.