# Плагин — единица расширения Ивы

Harness остаётся тонким, способности приходят снаружи (philosophy.md). Иву дописывает
её владелец, и дописывает не правкой Authored tree, а папкой, которую можно принести
откуда угодно и унести куда угодно. Единица такой папки — плагин. Один агент по-прежнему
служит одному человеку; расти он умеет сам, чужими руками и без форка.

## Что решено

**Формат — Agent Plugins 1.0.0** (agent-plugins.org, опубликован 06.08.2026). Предложила
Vercel, довели вместе AWS, Anysphere, GitHub, Microsoft, OpenAI и Vercel; читают уже Kiro
и VS Code. Своего формата не придумываем: готовый стандарт даёт нам плагины соседних
экосистем даром, а свой стоил бы спеки, валидатора и вечных объяснений, чем он лучше.

Плагин — папка с `plugin.json`. Обязательны в манифесте два поля, `$schema` и `name`;
остальное (`version`, `description`, `author`, `homepage`, `repository`, `license`,
`keywords`, `extensions`) по желанию автора. Рядом:

- `skills/` по спеке Agent Skills (agentskills.io): `SKILL.md` в каждой дочерней папке.
- `mcp.json` — MCP-серверы плагина, транспорт `stdio`, `streamable-http` или `sse`.
- Клиентские добавки — под reverse-domain: ключ в `extensions` манифеста и/или папка
  с тем же именем. Чужой клиент такой ключ просто не читает.

Два правила спеки берём как есть. Первое: каждый файл резолвится внутри корня плагина,
даже когда путь идёт через симлинк, — выход за корень это ошибка, а не хитрая установка.
Второе: сломанная компонента не валит остальные. Плагин с битым `mcp.json` всё равно
отдаёт свои скиллы.

**Рантайм для кода — eve Extensions.** Механизм уже есть в eve 0.30.8: `defineExtension`,
сборка `eve extension build`, монтирование файлом `agent/extensions/<ns>.ts`, префикс
`<ns>__` у тулов и коннекшенов, конфиг на zod, снятие лишнего через `disableTool()`,
аддитивные хуки и инструкции. Мы этим пока не пользуемся — папки `agent/extensions/`
в дереве нет. Своего рантайма плагинов Ива не пишет: он принадлежит eve upstream
(правила границ, philosophy.md). Пересмотрено ADR-0023 (10.10.2026): чего плагинам не хватает
в eve, Ива дописывает сама — в eve или рядом с ней.

**Живёт плагин в Custom layer** (`data/custom/`). Оттуда он переживает `iva update`,
не трогает Authored tree и не просит менять harness. Коробка остаётся священной
(ADR-0003): установка плагина не может сломать install и update.

**Ставится из git-URL или локальной папки.** Реестра нет и не планируется. Agent Plugins
намеренно не определяет распространение, и центральный список нам не нужен: он требует
модерации, доверия и живого мейнтейнера, а даёт одно удобство поиска.

## Что отвергнуто

DeepSeek Harness (Cordis DI, типизированные события, disposers). Это плагины для тех,
кто пишет harness, а не для тех, кому нужна способность. У eve уже есть свой контейнер,
свои хуки и свой жизненный цикл; второй слой поверх — новая трущаяся деталь, которую
придётся тестировать, ревьюить и мигрировать у сотен чужих инсталляций (принцип колеса,
philosophy.md). Разница в цене видна сразу: способность у нас — папка со скиллом, а не
класс с внедрением зависимостей.

Свой формат плагина отвергнут вместе с ним, по той же причине плюс изоляция: формат,
который никто не читает, закрывает нас от чужих плагинов.

## Что это меняет в терминах

Skill перестал быть единицей поставки и стал содержимым: скилл приходит либо из ядра,
либо из плагина. Плагин — то, что ставят и удаляют целиком; скилл — то, что внутри
него знает, как делать работу. Термин Plugin записан в CONTEXT.md рядом со Skill,
слово «расширение» как термин запрещено обоим: за ним стоит слишком много разных вещей.

## Принятый риск

Bash внутри скилла плагина видит env процесса со всеми ключами инсталляции. Ступень 2
ADR-0005 (изоляция секретов от шелла) отложена владельцем 15.08.2026, и плагины её
не приближают. Значит, поставить чужой плагин — отдать ему токены Telegram, провайдера
модели и всё остальное, что лежит в окружении. Проверка манифеста от этого не спасает:
`plugin.json` описывает состав, а не поведение.

Пишем это прямо, в доке установки и в SECURITY.md. Для своего плагина риск свой,
для чужого — чужой, и решать за self-hoster'а мы не будем (ADR-0001). MCP-сервер
из `mcp.json` в этом смысле устроен лучше: он получает только те переменные, которые
ему выдали в конфиге, а не весь env агента.

## Что придётся достроить

Три расхождения между спекой и сегодняшним кодом. Закрывать их — работа волны реализации,
не этого решения.

- Custom layer знает пять слотов: `agent/instructions.md`, `agent/skills/`,
  `agent/connections/`, `agent/tools/`, `agent/subagents/` (`scripts/lib/authored-paths.ts`).
  `agent/extensions/` в списке нет, поэтому точка монтирования eve Extension сегодня
  не переживёт апдейт.
- eve Extension — npm-пакет: его объявляют зависимостью и собирают до сборки агента.
  Папка, принесённая из git, этому контракту сама по себе не отвечает.
- MCP-клиент eve только сетевой: `defineMcpClientConnection` требует Streamable HTTP
  или SSE. Записям `stdio` из `mcp.json` опереться сегодня не на что.

## Открытые вопросы

- **Namespace Ивы в манифесте.** Предварительно `sh.iva`, по домену проекта
  (smixs.github.io/iva). Явного подтверждения владельца нет. Подтвердить до первой
  реализации: ключ уезжает в чужие манифесты и потом не переименовывается.
- **`schedules/` внутри плагина.** В спеке Agent Plugins их нет, у eve расписания
  живут только в корне агента. Плагину, которому нужен ночной ход, опереться не на что.
  Выбор между «не поддерживать вовсе» и «свой слот Ивы поверх спеки» — за волной
  реализации.
- **Порядок при совпадении имён, плагин против бандла.** Предварительно побеждает
  ближний слой: так уже работает eve (одноимённый тул потребителя выигрывает у тула
  Extension), так же решает DeepSeek Harness. Утвердить вместе с реализацией.

## Обновление 17.08.2026

Три расхождения и открытые вопросы закрыты в ADR-0009: namespace — `sh.iva`;
`schedules/` в плагине не поддерживаем (eve сам запрещает); при совпадении имён
побеждает ближний слой (плагин над ядром), одноимённые скиллы двух плагинов — отказ
установки. К «git-URL или локальной папке» добавлен Marketplace в конвенции Codex —
это список в git-репо, не центральный реестр; фраза «реестра нет и не планируется»
остаётся в силе про реестр.

Статус: решение принято 15.08.2026, рельсы — ADR-0009, первый плагин — ADR-0010.

Helper rights and the removal of bundled planner/default task tools are defined in [ADR-0025](0025-helper-turn-rights.md).