# 01 — Обзор

**Русский** · [English](../01-overview.md)

iapeer держит команду агентов на одном хосте: ведёт реестр участников, маршрутизирует сообщения между ними и управляет их присутствием. Три понятия задают всю систему — пир, рантайм, идентичность.

## Пир

Пир — участник системы. Это AI-агент (Claude, Codex), человек (через Telegram) или служебный процесс (планировщик, наблюдатель). На уровне транспорта они неразличимы: адресуются одинаково, обмениваются сообщениями по одному протоколу.

У пира есть имя (`personality`) — короткое логическое имя в нижнем регистре (`assistant`, `code-reviewer`). Имя стабильно при переходе между рантаймами, выводится из имени рабочей папки и уникально: два пира одно имя носить не могут.

Природу пира задаёт атрибут `intelligence` — он едет в конверте каждого сообщения, поэтому получатель знает, с кем говорит, без внешних договорённостей:

| Значение | Кто |
|---|---|
| `artificial` | AI-агент (Claude, Codex) |
| `natural` | человек (через Telegram) |
| `absent` | программа без интеллекта (планировщик, наблюдатель) |

## Рантайм

Рантайм — способ присутствия пира. Один пир может присутствовать в нескольких рантаймах. По управлению жизненным циклом рантаймы делятся на два класса:

- **claude, codex** — AI-агенты. Сессию не держат запущенной постоянно: демон поднимает агента на входящее сообщение и закрывает сессию после часа простоя. Этим классом распоряжается демон.
- **telegram, notifier** — служебные рантаймы-роутеры (не AI). Работают постоянно: Telegram-мост принимает входящие в любой момент, notifier срабатывает по расписанию. Их держит launchd с автоперезапуском. Эти рантаймы называются инфраструктурными; демон их не трогает.

Граница — это разделение ответственности: демон управляет агентами claude/codex, launchd — инфраструктурными рантаймами. Команды `stop`/`start`/`new` поэтому работают по-разному в зависимости от класса.

## Идентичность

Идентичность — адрес живого присутствия пира, склейка рантайма и имени:

```text
PEER_IDENTITY = PEER_RUNTIME + "-" + PEER_PERSONALITY
```

Агент `assistant` в Claude — `claude-assistant`, он же в Codex — `codex-assistant`: имя одно, идентичности разные. Разбор идёт по первому дефису (в имени рантайма дефисов нет, в имени пира допустимы), поэтому `claude-code-reviewer` — это рантайм `claude` и пир `code-reviewer`.

Три значения — `PEER_PERSONALITY`, `PEER_RUNTIME`, `PEER_IDENTITY` — передаются в окружение сессии. По ним любой компонент знает своё имя и от чьего лица действует. Подробно — [03 — Пиры, рантаймы, идентичность](03-пиры-рантаймы-идентичность.md).

## Компоненты

```text
┌──────────────────────────────────────────────────────────────┐
│  CLI  iapeer <команда>                                         │
│  create · list · send · stop/start · new · connect · enable …  │
└───────────────┬──────────────────────────────────────────────┘
                │
┌───────────────▼───────────────┐     ┌──────────────────────────┐
│  Демон-роутер (работает 24/7)  │     │  Реестр пиров             │
│  • принимает send_to_peer      │◀───▶│  ~/.iapeer/               │
│  • находит получателя          │     │  peers-profiles.json      │
│  • доставляет / поднимает      │     └──────────────────────────┘
│  • надзор за пирами            │
└───────────────┬───────────────┘
                │ поднимает / усыпляет
┌───────────────▼───────────────────────────────────────────────┐
│  Рантайм-адаптеры                                              │
│ claude · codex (pty-супервизор) │ telegram · notifier (launchd)│
└────────────────────────────────────────────────────────────────┘
```

**Демон-роутер** — единственный постоянно работающий процесс ядра, под launchd. Принимает вызовы `send_to_peer`, находит получателя в реестре, доставляет сообщение в живую сессию или поднимает спящего агента. Раз в минуту обходит пиров: закрывает сессии после часа простоя, перезапускает помеченных на свежий старт, не даёт упавшему агенту войти в цикл перезапусков. См. [04 — Жизненный цикл и демон](04-жизненный-цикл-и-демон.md).

**Реестр пиров** — `~/.iapeer/peers-profiles.json`: имя, рантаймы, описание, природа, рабочая папка каждого пира. Источник истины — профиль каждого пира (`<папка>/.iapeer/peer-profile.json`); реестр пересобирается из профилей. См. [06 — Хранение](06-хранение.md).

**Рантайм-адаптеры** — слой запуска сессий. Для Claude и Codex это TUI-сессия под pty-супервизором с подменённым системным промптом; для Telegram и notifier — долгоживущий процесс-роутер под launchd. Адаптеры прячут различия рантаймов за единым интерфейсом. См. [09 — Рантаймы](09-рантаймы.md).

**CLI `iapeer`** — вход для оператора и агентов: создание пиров, обзор и состояние пиров, ручная отправка, остановка и перезапуск, подключение Telegram, установка расширений. См. [12 — CLI](12-cli-reference.md).

## Путь сообщения

1. Отправитель вызывает `send_to_peer(assistant, "...")` — вызов идёт в демон по локальному сокету или HTTP.
2. Демон находит `assistant` в реестре и проверяет наличие живой сессии.
3. **Жив** — сообщение вставляется в сессию, демон подтверждает приём, отвечает `доставлено`.
4. **Спит** — демон поднимает сессию (продолжает прежний диалог или начинает свежий), доставляет, отвечает `доставлено, разбудил`.
5. **Остановлен** оператором — демон отказывает в доставке и сообщает отправителю прямо.

Ответ `доставлено` означает, что сообщение легло в живую сессию, — очереди «на потом» в обычном случае нет. Механику разбирает [10 — Обмен сообщениями](10-обмен-сообщениями.md).

## Дальше

- Попробовать — [02 — Быстрый старт](02-быстрый-старт.md).
- Понять понятия глубже — [03 — Пиры, рантаймы, идентичность](03-пиры-рантаймы-идентичность.md).
- Разработать расширение или рантайм-пакет — [13 — Архитектура и контракт](13-архитектура-и-контракт.md).