From 2af6dd78bae95170628b76098475205e196e3235 Mon Sep 17 00:00:00 2001 From: admin Date: Wed, 11 Nov 2026 04:44:47 +0000 Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8=D1=82?= =?UTF-8?q?=D1=8C=20=D0=B4=D0=B8=D0=B7=D0=B0=D0=B9=D0=BD=20Invest=20Harnes?= =?UTF-8?q?s=20=D0=B8=20=D0=BA=D0=BE=D0=BD=D1=82=D1=80=D0=B0=D0=BA=D1=82?= =?UTF-8?q?=D1=8B=20=D0=BF=D0=BB=D0=B0=D1=82=D1=84=D0=BE=D1=80=D0=BC=D1=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 6 +- designDocument/api/agents-api.md | 31 ++ designDocument/api/catalog-api.md | 37 ++ designDocument/api/conventions.md | 33 ++ designDocument/api/executor-api.md | 37 ++ designDocument/api/runs-api.md | 33 ++ designDocument/catalog.md | 29 ++ designDocument/configuration-ui.md | 38 ++ designDocument/contracts/domain-model.md | 44 ++ .../contracts/examples/config.defaults.json | 5 + .../contracts/examples/config.schema.json | 34 ++ .../contracts/examples/execution-spec.json | 44 ++ .../contracts/examples/template-manifest.json | 27 ++ .../contracts/examples/ui.schema.json | 17 + .../contracts/execution-spec.schema.json | 143 ++++++ .../contracts/package-manifest.schema.json | 188 ++++++++ .../contracts/run-event.schema.json | 46 ++ designDocument/design.md | 408 ++++++++++++++++++ designDocument/execution.md | 35 ++ designDocument/scaling.md | 58 +++ designDocument/security.md | 31 ++ 21 files changed, 1322 insertions(+), 2 deletions(-) create mode 100644 designDocument/api/agents-api.md create mode 100644 designDocument/api/catalog-api.md create mode 100644 designDocument/api/conventions.md create mode 100644 designDocument/api/executor-api.md create mode 100644 designDocument/api/runs-api.md create mode 100644 designDocument/catalog.md create mode 100644 designDocument/configuration-ui.md create mode 100644 designDocument/contracts/domain-model.md create mode 100644 designDocument/contracts/examples/config.defaults.json create mode 100644 designDocument/contracts/examples/config.schema.json create mode 100644 designDocument/contracts/examples/execution-spec.json create mode 100644 designDocument/contracts/examples/template-manifest.json create mode 100644 designDocument/contracts/examples/ui.schema.json create mode 100644 designDocument/contracts/execution-spec.schema.json create mode 100644 designDocument/contracts/package-manifest.schema.json create mode 100644 designDocument/contracts/run-event.schema.json create mode 100644 designDocument/design.md create mode 100644 designDocument/execution.md create mode 100644 designDocument/scaling.md create mode 100644 designDocument/security.md diff --git a/README.md b/README.md index a3f0be0..7f5f0ce 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ -# invest-harness +# Invest Harness -Invest Harness — платформа инвестиционных ИИ-агентов. Архитектура и контракты системы. \ No newline at end of file +Платформа инвестиционных ИИ-агентов: каталог harness’ов, плагинов, скиллов и шаблонов, настройка через формы и запуск локально или удалённо. + +Проект на стадии проектирования. [Дизайн системы](designDocument/design.md). diff --git a/designDocument/api/agents-api.md b/designDocument/api/agents-api.md new file mode 100644 index 0000000..24f1348 --- /dev/null +++ b/designDocument/api/agents-api.md @@ -0,0 +1,31 @@ +# API экземпляров агентов + +Общие правила: [conventions.md](conventions.md). Все ресурсы scoped к tenant. Viewer читает разрешённые агенты; operator создаёт и настраивает свои, admin — разрешённые tenant-агенты. + +| Метод и путь | Запрос | Ответ | Поведение | +|---|---|---|---| +| POST /v1/agents | name, templateVersionId, config, connections | 201 Agent | Создаёт revision=1 после проверки | +| GET /v1/agents | cursor, limit | 200 Page | Только доступные | +| GET /v1/agents/{id} | — | 200 Agent с currentRevision | Проверка owner/tenant | +| POST /v1/agents/{id}/config/validate | config, templateVersionId? | 200 ValidationResult | Без сохранения | +| PUT /v1/agents/{id}/config | config, connections; If-Match | 200 AgentRevision | Полная конфигурация; 412 lost update | +| GET /v1/agents/{id}/revisions/{revision} | — | 200 AgentRevision | Неизменяемый snapshot | +| POST /v1/agents/{id}/upgrade-preview | targetTemplateVersionId | 200 UpgradePreview | Diff, requiredPermissions, ошибки | +| POST /v1/agents/{id}/upgrade | targetTemplateVersionId, config, connections; If-Match | 200 AgentRevision | Новая ревизия, старые Run не меняются | +| DELETE /v1/agents/{id} | If-Match | 202 operationId | Архивирует; активные Run требуют отдельной отмены | + +Agent: id, tenantId, ownerId, name, currentRevision, archivedAt?, createdAt. AgentRevision: id, agentId, revision, templateVersionId, configSchemaDigest, config, connections, createdAt. Connections — map логического имени на connectionId, без секретов. + +ValidationResult: valid:boolean, errors:[{path, code, message}], effectiveConfig. При семантически невалидной конфигурации endpoint validate возвращает 200 valid=false; endpoints сохранения возвращают 422. Ссылки на чужие подключения не раскрываются в errors. + +UpgradePreview: fromVersionId, toVersionId, changes:[{path, kind}], validation, addedPermissions. Preview не разрешает новые доступы автоматически. Принятие upgrade заново проверяет rights и policy. + +## Пример создания + +```json +{"name":"Обзор компаний","templateVersionId":"version_company_1","config":{"lookbackDays":90,"reportLanguage":"ru","includeSources":true},"connections":{}} +``` + +## Подключения + +GET /v1/connections возвращает доступные ConnectionSummary (id, provider, label, grantedScopes, expiresAt), не credentials. POST /v1/connections создаёт подключение через provider authorization flow или защищённую передачу ключа; конкретные provider payload задаются отдельными адаптерами и не входят в универсальную config schema. DELETE /v1/connections/{id} отзывает платформенный доступ и при возможности выполняет revoke у провайдера. Повторное использование в новом Run после отзыва запрещено. diff --git a/designDocument/api/catalog-api.md b/designDocument/api/catalog-api.md new file mode 100644 index 0000000..dac385d --- /dev/null +++ b/designDocument/api/catalog-api.md @@ -0,0 +1,37 @@ +# API каталога + +Общие правила: [conventions.md](conventions.md). Автор публикации — publisher соответствующего tenant. Читатель видит public или разрешённые tenant/private пакеты. + +| Метод и путь | Запрос | Ответ | Доступ / особые ошибки | +|---|---|---|---| +| GET /v1/packages | kind, query, cursor, limit | 200 Page | Доступные пакеты | +| GET /v1/packages/{id} | — | 200 Package | 404 для скрытого | +| POST /v1/packages | kind, name, description, visibility | 201 Package | Publisher; 409 имя занято | +| PATCH /v1/packages/{id} | description?, visibility?; If-Match | 200 Package | Publisher; нельзя менять kind | +| GET /v1/packages/{id}/versions | cursor, limit | 200 Page | Читатель | +| GET /v1/packages/{id}/versions/{version} | — | 200 PackageVersion | Читатель | +| POST /v1/packages/{id}/versions | version, manifest | 201 VersionDraft | Publisher; Idempotency-Key | +| POST /v1/packages/{id}/versions/{version}/upload | mediaType, sizeBytes, digest | 201 UploadGrant | Publisher; ограниченный путь | +| POST /v1/packages/{id}/versions/{version}/publish | artifactRef, digest | 200 PackageVersion | Publisher; 409 другая версия; 422 несовместимость | +| POST /v1/packages/{id}/versions/{version}/policy | status, reason; If-Match | 200 VersionPolicy | Admin; status deprecated/blocked/published | +| POST /v1/resolutions | templateVersionId, environment | 200 Resolution | Читатель всех зависимостей; 422 conflict | +| GET /v1/package-versions/{id}/config | — | 200 ConfigBundle | Закреплённые schema, defaults, uiSchema и digest | +| POST /v1/package-versions/{id}/download | artifactDigest | 200 DownloadGrant | Повторная проверка policy и доступа | + +## Формы + +Package: id, tenantId, kind (harness/plugin/skill/template), name, description, visibility (public/tenant/private), ownerId, createdAt, revision. + +VersionDraft: id, packageId, version, manifest, status=draft. PackageVersion: те же идентификаторы, artifactRef, artifactDigest, schemaDigest?, publishedAt. VersionPolicy хранится отдельно: status, reason?, revision. Поле version не разрешает перезапись содержимого. + +Resolution: resolutionId, templateVersionId, packages:[{packageVersionId, kind, digest, artifactRef}], configSchemaDigest, requiredCapabilities, requiredPermissions. environment: os, architecture, protocolVersion, availableCapabilities. Resolution не содержит credentials и не обещает бессрочное право скачать заблокированный пакет. + +ConfigBundle: schema (JSON Schema), defaults (object), uiSchema (object|null), schemaDigest. UI schema необязательна. OCI upload использует стандартный registry API с ограниченным токеном; upload ручка для него выдаёт registry reference и scope, а не S3 URL. + +## Пример resolve + +```json +{"templateVersionId":"version_company_1","environment":{"os":"linux","architecture":"amd64","protocolVersion":"1","availableCapabilities":["oci-v1","cancel-v1"]}} +``` + +Публикация возвращает успех только после проверки артефакта. Если загрузка завершилась, а запрос publish потерялся, повтор с тем же ключом безопасен. Удаление пакета, на который ссылаются сохранённые запуски, не входит в MVP; вместо него используются deprecated/blocked. diff --git a/designDocument/api/conventions.md b/designDocument/api/conventions.md new file mode 100644 index 0000000..ade02be --- /dev/null +++ b/designDocument/api/conventions.md @@ -0,0 +1,33 @@ +# Общие правила API v1 + +Это проектируемые публичные контракты Invest Harness. Базовый путь /v1; JSON UTF-8; HTTPS обязателен. Внутренние API движка не являются публичным контрактом. + +## Типы и ошибки + +Id — непрозрачная строка 1–128 символов; Timestamp — RFC3339 UTC; Digest — sha256: и 64 hex-символа; Revision — положительное целое. Денежные суммы задаются integer minor units + currency; CPU в millicores, память и файлы в bytes, интервалы в seconds. Дата расписания содержит отдельно IANA timezone. + +Ошибка: {"error":{"code":"CONFIG_INVALID","message":"Настройки не соответствуют схеме","details":[{"path":"/lookbackDays","code":"maximum"}],"requestId":"req_example"}}. Никаких секретов или stack trace в ответе. + +| HTTP | Значение | +|---|---| +| 400 | Невалидный синтаксис запроса | +| 401 | Нет действительной идентичности | +| 403 | Нет прав на известную разрешённую к раскрытию операцию | +| 404 | Ресурс отсутствует или скрыт от вызывающего | +| 409 | Конфликт состояния, digest, lease или idempotency payload | +| 412 | Устаревший If-Match | +| 422 | Валидный JSON нарушает контракт, зависимости или policy | +| 429 | Квота / rate limit, Retry-After | +| 503 | Временная недоступность зависимости | + +## Доступ и повторные запросы + +Сессия пользователя или сервисный bearer token. Membership и ресурсный tenant проверяются на каждой операции. Публичное чтение каталога не даёт доступ к приватным зависимостям. Cookie-мутации требуют CSRF-защиты. Запросы публикации, запуска, retry и resume требуют Idempotency-Key; область ключа tenant + principal + method + path. Hash тела связывается с ключом; другое тело → 409. Результат хранится минимум 7 дней, а уникальность attemptId и schedule occurrence действует независимо от TTL ключа. + +PATCH/PUT изменяемых ресурсов требуют If-Match, ответ содержит ETag. Списки: limit 1..100, непрозрачный cursor, ответ {items:[], nextCursor:null}. Cursor фиксирует сортировку createdAt,id и фильтры, не заменяет авторизацию. DELETE с асинхронной очисткой возвращает 202 и operationId. + +## События и файлы + +SSE endpoint принимает Last-Event-ID; event id монотонен в пределах Run. После retention слишком старый cursor возвращает 410 с указанием получить snapshot. Повторные события дедуплицируются по eventId. SSE не является источником истины о состоянии: GET Run возвращает канонический snapshot. + +Binary upload выполняется по scoped grant. Он содержит uploadId, url, expiresAt, maxBytes, requiredHeaders; постоянные записи хранят artifactId, не подписанный URL. Grant не считается подтверждением загрузки: finalize проверяет размер, digest и объект. По умолчанию ошибки не повторяются автоматически, кроме явных transient ошибок с ограниченным backoff и jitter. diff --git a/designDocument/api/executor-api.md b/designDocument/api/executor-api.md new file mode 100644 index 0000000..3a2d85a --- /dev/null +++ b/designDocument/api/executor-api.md @@ -0,0 +1,37 @@ +# Runner Protocol v1 + +Новый контракт Invest Harness для заменяемых исполнителей. Стандартный движок подключается адаптером; он не обязан понимать этот API напрямую. ExecutionSpec одинаков для удалённой и локальной реализации. + +## Регистрация + +Admin создаёт POST /v1/runner-pools/{poolId}/registration-grants с {expiresInSeconds:600}; ответ 201 {grant, expiresAt}. Grant одноразовый, не журналируется. Runner вызывает POST /v1/runners/register с {grant, name, protocolVersion:"1", capabilities}; ответ 201 {runnerId, poolId, credential, expiresAt}. Долгоживущая идентичность хранится в защищённом хранилище исполнителя; credential обновляется через POST /v1/runners/{id}/credentials/rotate с текущей идентичностью и отзывается через DELETE /v1/runners/{id} администратором. + +Capabilities: os, architecture, executionKinds:["oci"], features:["cancel-v1"], maxConcurrency. checkpoint-v1 и input-v1 опциональны. Профиль пула задаёт доверенную изоляцию и квоты отдельно от заявления capabilities. + +## Выполнение + +| Метод и путь | Запрос | Ответ | +|---|---|---| +| POST /v1/runner-jobs/claim | runnerId, availableSlots, capabilitiesRevision | 200 Assignment или 204 | +| POST /v1/attempts/{id}/heartbeat | leaseEpoch, sequence, progress? | 200 {leaseUntil, cancelRequested} | +| POST /v1/attempts/{id}/started | leaseEpoch, sequence | 200 Attempt | +| POST /v1/attempts/{id}/events | leaseEpoch, events:[RunEvent] | 200 {acceptedThrough} | +| POST /v1/attempts/{id}/uploads | leaseEpoch, purpose, mediaType, sizeBytes, digest | 201 UploadGrant | +| POST /v1/attempts/{id}/complete | leaseEpoch, completionId, outcome, resultManifest?, error? | 200 Attempt | +| POST /v1/attempts/{id}/suspend | leaseEpoch, checkpointArtifactId, inputRequest | 200 Run | + +Assignment: attemptId, runId, leaseEpoch, leaseUntil, executionSpec, executionToken. Execution token scoped к Attempt. Запрос claim authenticated идентичностью Runner; последующие операции — execution token. Назначение создаётся сервером атомарно; один claim выдаёт максимум один Attempt, availableSlots не разрешает превысить maxConcurrency пула. + +Outcome: succeeded/failed/cancelled. Success требует ResultManifest и сохранённых объектов, даже если artifacts пуст. Error: code, message, retryableHint; решение о retry принимает платформа. Complete повторяется с тем же completionId и телом; другой payload после terminal state → 409. Поздние heartbeat, события и complete с прежним epoch → 409 LEASE_EXPIRED. События могут доставляться повторно; уникальны по attemptId + eventId. + +Suspend допустим только для checkpoint-v1 + input-v1. InputRequest: id, schema, prompt, expiresAt. Платформа принимает checkpoint, переводит Run в waiting_input, отзывает lease; новый Attempt получает checkpointRef и проверенный ответ. Без checkpoint протокол не обещает сохранение памяти процесса. + +## Локальный процесс + +Адаптер materialize-ит immutable ExecutionSpec в /input/execution.json, входные файлы — read-only /input/files; вывод — /output. Разрешённые secrets передаются отдельным каналом и не сериализуются в spec. Entrypoint — массив аргументов, не shell-строка. События JSONL поступают через отдельный pipe или файл адаптера, stdout/stderr считаются логами. Адаптер читает /output/result.json и загружает разрешённые артефакты; ссылки вне /output и symlink traversal запрещены. + +Соглашение путей относится к стандартному OCI-адаптеру. Другой Runner может реализовать иной транспорт при сохранении семантики ExecutionSpec и результатов. Локальный offline Runner не вызывает облачные claim/heartbeat, но ведёт эквивалентное локальное состояние. + +## Минимальная проверка совместимости + +Runner обязан показать: корректный success; failure; отказ при несовместимом spec; отмену; тайм-аут; повтор complete без дублей; отказ с просроченным lease; изоляцию файлов между задачами; корректный upload digest; отсутствие secrets в событиях. Resume проверяется только при соответствующей capability. Managed и customer-managed пулы отображаются раздельно. diff --git a/designDocument/api/runs-api.md b/designDocument/api/runs-api.md new file mode 100644 index 0000000..59a23e5 --- /dev/null +++ b/designDocument/api/runs-api.md @@ -0,0 +1,33 @@ +# API запусков и расписаний + +Общие правила: [conventions.md](conventions.md). Operator запускает и отменяет доступные ему агенты; viewer читает разрешённые Run. Доступ к самому агенту не заменяет проверку прав на его connections. + +| Метод и путь | Запрос | Ответ | Особенности | +|---|---|---|---| +| POST /v1/runs | agentId, agentRevision, input, poolId?, limits? | 202 Run | Idempotency-Key, policy и квоты | +| GET /v1/runs | agentId?, status?, cursor, limit | 200 Page | Tenant-scoped | +| GET /v1/runs/{id} | — | 200 Run | Каноническое состояние | +| GET /v1/runs/{id}/events | Last-Event-ID | SSE RunEvent | 410 при истёкшем cursor | +| GET /v1/runs/{id}/artifacts | cursor, limit | 200 Page | Без долгоживущих URL | +| POST /v1/runs/{id}/artifacts/{artifactId}/download | — | 200 DownloadGrant | Повторная проверка прав | +| POST /v1/runs/{id}/cancel | reason? | 202 Run | Идемпотентная команда; terminal run → 409 | +| POST /v1/runs/{id}/retry | acknowledgedExternalEffects:boolean | 202 новый Run | parentRunId, новый ключ, проверка policy | +| POST /v1/runs/{id}/responses | responseId, inputRequestId, value | 202 Run | Только waiting_input; схема ответа и права | +| POST /v1/schedules | agentId, cron, timezone, overlapPolicy | 201 Schedule | operator; cron и timezone валидируются | +| PATCH /v1/schedules/{id} | cron?, timezone?, enabled?, overlapPolicy?; If-Match | 200 Schedule | 412 conflict | +| GET /v1/schedules | cursor, limit | 200 Page | Tenant-scoped | +| DELETE /v1/schedules/{id} | If-Match | 204 | Останавливает будущие, не текущие Run | + +Run: id, tenantId, agentId, agentRevisionId, status, specDigest, createdAt, startedAt?, finishedAt?, attemptCount, parentRunId?, error?, resultManifest?, inputRequest?. Полный spec доступен только субъектам с run:read-config; обычный status не содержит конфигурацию. + +Schedule: id, tenantId, agentId, cron, timezone, overlapPolicy (skip/queue), enabled, nextRunAt, revision. Каждое срабатывание фиксирует текущую ревизию агента; уже созданный Run не меняется при обновлении агента. Cron интерпретируется как пять полей (минута, час, день месяца, месяц, день недели); шаг менее минуты не поддерживается. + +Limits: cpuMillis, memoryBytes, timeoutSeconds, outputBytes. Пользователь может запросить меньше предела policy; превышение даёт 422, а не скрытое повышение прав. Input — JSON по input schema template. PoolId не даёт доступ к чужому пулу. + +## Пример + +```json +{"agentId":"agent_company","agentRevision":1,"input":{"company":"Example Company"},"limits":{"cpuMillis":1000,"memoryBytes":1073741824,"timeoutSeconds":900,"outputBytes":104857600}} +``` + +Отмена не гарантирует отмену уже совершённого внешнего действия. Reconcile технического статуса выполняет сервис исполнения; пользовательский запрос не переписывает состояние Runner произвольно. diff --git a/designDocument/catalog.md b/designDocument/catalog.md new file mode 100644 index 0000000..118a17a --- /dev/null +++ b/designDocument/catalog.md @@ -0,0 +1,29 @@ +# Каталог пакетов + +Каталог — отдельный Go-сервис со своей PostgreSQL БД. Он владеет метаданными harness, plugin, skill и template. OCI-образы обслуживает registry, архивы — S3. Прямой доступ других сервисов к таблицам каталога запрещён; используется API. + +## Пакет и версия + +Package содержит id, tenantId, kind, name, description, visibility и ownerId. Имя уникально внутри tenant и kind. PackageVersion содержит version, manifest, artifactDigest, artifactRef, schemaDigest, createdAt и publisherId. Содержимое версии неизменяемо. Отдельная запись VersionPolicy хранит status, reason и changedAt: блокировка не переписывает исходный пакет. + +Harness описывает поддерживаемый runtime, entrypoint и протокол ввода/вывода. Plugin описывает расширение и совместимость с harness. Skill содержит инструкции, ресурсы и при необходимости скрипты. Template объединяет точные или ограниченные версии зависимостей, инструкции и схему конфигурации. Skill с исполняемым кодом проходит те же проверки, что plugin. + +## Публикация + +Автор с ролью publisher создаёт draft, получает ограниченный upload grant и загружает артефакт. Для OCI он использует стандартный registry push. Publish проверяет размер, digest, формат манифеста, ссылки внутри архива, схему конфигурации, доступ к зависимостям и отсутствие циклов. Архив не может содержать выходящие за корень пути, абсолютные пути или небезопасные symlink. + +Только после проверки артефакта транзакция публикует версию. Повтор Publish с тем же Idempotency-Key возвращает прежний результат. То же имя версии с другим digest даёт 409. Объекты без опубликованной версии очищаются после 24 часов — исходное значение, настраиваемое администратором. + +## Resolve + +Resolver принимает templateVersionId и профиль среды. Он строит ацикличный граф зависимостей, проверяет совместимость, выбирает конкретные версии и возвращает lock со всеми digest. Диапазоны версий разрешены на входе публикации шаблона, но не в ExecutionSpec. Конфликт версий возвращается с цепочками зависимостей; молчаливый выбор несовместимого пакета запрещён. + +Доступ проверяется при resolve, выдаче download grant и назначении Attempt. Публичный шаблон не должен требовать недоступную аудитории приватную зависимость. Блокировка версии запрещает новые назначения; для уже работающих Attempt администратор выбирает policy cancel или allow_finish с аудитом. + +## Обновления и хранение + +Обновление шаблона не изменяет существующие AgentRevision. Пользователь получает preview изменений и ошибок валидации. Новая ревизия создаётся только после успешной проверки. В MVP миграция ручная через форму; исполняемые миграции автора не запускаются в браузере. + +Deprecated версия доступна закреплённым агентам, но скрыта из стандартного выбора. Удаление referenced-версии возвращает 409. Физическая очистка допускается после retention запусков, проверки ссылок и grace period. Immutable артефакты адресуются по digest; signed URL не сохраняется в постоянном lock. + +API: [catalog-api.md](api/catalog-api.md). Все диаграммы: [design.md](design.md). diff --git a/designDocument/configuration-ui.md b/designDocument/configuration-ui.md new file mode 100644 index 0000000..63fe6ea --- /dev/null +++ b/designDocument/configuration-ui.md @@ -0,0 +1,38 @@ +# Пользовательская конфигурация + +## Контракт автора + +Шаблон содержит config.schema.json, config.defaults.json и необязательную ui.schema.json. JSON Schema описывает данные, UI Schema — только представление. Собственные параметры harness и plugins располагаются в пространствах имён harness и plugins.; схема template объединяет их без конфликтов имён. + +Базовый диалект — JSON Schema Draft 2020-12. MVP renderer поддерживает object, string, number, integer, boolean, array, enum, required, additionalProperties, minimum/maximum, minLength/maxLength, minItems/maxItems и локальные $ref/$defs. oneOf и условные секции включаются только после проверки renderer и валидатора. Неизвестные UI-компоненты и неподдерживаемые keywords отвергаются при публикации, а не игнорируются. Удалённые $ref запрещены. Ограничиваются размер, вложенность и сложность схемы. На старте запрещены пользовательские regex pattern, пока не реализованы лимиты их выполнения. + +## Применение значений + +1. Загрузить схему и defaults, закреплённые по digest. +2. Создать конфигурацию из defaults и явных значений пользователя: objects объединяются по ключам, arrays заменяются целиком; null допустим только по схеме и не означает удаление. +3. Проверить итоговую конфигурацию одним согласованным набором правил. +4. Проверить права на подключения и ограничения организации. +5. Сохранить полный результат как новую AgentRevision с schemaDigest. + +JSON Schema default — аннотация, а не команда валидатору. defaults-файл при публикации обязан соответствовать схеме после объединения с обязательными вводимыми полями; отсутствующие обязательные поля пользователь заполняет до сохранения. Сервер не доверяет клиентской валидации. + +## UI + +Web UI: TypeScript, React, JSON Forms; серверный валидатор — совместимая Go-библиотека Draft 2020-12, точная реализация выбирается по общему корпусу контрактных примеров. UI schema использует только встроенные контролы и layout, без JavaScript, HTML и внешних скриптов. Описания отображаются как безопасный текст. + +Поля для подключения к сервису отображают selector ConnectionRef. Секретные значения не входят в JSON конфигурации, defaults, пример или URL. readOnly, writeOnly и скрытие поля в UI не заменяют server-side permission checks. Пользователь не может через config повысить лимит ресурсов, изменить tenantId или разрешить новые сетевые доступы. + +## Версии и изменения + +PUT конфигурации требует If-Match. При конфликте ревизии сервер возвращает 412. UI показывает различия, пользователь повторно сохраняет результат. Запуск фиксирует agentRevisionId, schemaDigest и effectiveConfig; последующие изменения агента не влияют на Run. + +Новая версия шаблона сначала проверяется на копии конфигурации. При несовместимости показываются JSON Pointer путей и сообщения ошибок. Старая ревизия остаётся рабочей до явного обновления. В MVP автоматических исполняемых миграций нет. + +## Источники и пример + +- [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12) +- [Аннотации и default](https://json-schema.org/understanding-json-schema/reference/annotations) +- [JSON Forms UI Schema](https://jsonforms.io/docs/uischema/) +- [Пример схемы](contracts/examples/config.schema.json) +- [Начальные значения](contracts/examples/config.defaults.json) +- [Представление формы](contracts/examples/ui.schema.json) diff --git a/designDocument/contracts/domain-model.md b/designDocument/contracts/domain-model.md new file mode 100644 index 0000000..038cb80 --- /dev/null +++ b/designDocument/contracts/domain-model.md @@ -0,0 +1,44 @@ +# Модель данных + +Типы в этой таблице определяют семантику API. JSON Schema ниже задают машиночитаемую основу контракта; дополнительные межресурсные проверки выполняются сервисами. + +| Сущность | Ключевые поля | Владелец | +|---|---|---| +| Tenant | id, name, policyRevision | Platform API | +| Membership | tenantId, userId, roles | Identity / Platform API | +| Package | id, tenantId, kind, name, visibility, ownerId | Catalog | +| PackageVersion | id, packageId, version, manifest, artifactDigest | Catalog | +| VersionPolicy | versionId, status, reason, revision | Catalog | +| Agent | id, tenantId, ownerId, name, currentRevision | Platform API | +| AgentRevision | id, agentId, revision, templateVersionId, config, connections, schemaDigest | Platform API | +| Connection | id, tenantId, provider, scopes, encryptedSecretRef | Secrets / Platform API | +| Run | id, tenantId, agentRevisionId, status, specDigest, parentRunId | Platform API | +| Attempt | id, runId, runnerId, leaseEpoch, leaseUntil, status | Dispatcher | +| RunnerPool | id, tenantId, trustPolicy, quotas | Dispatcher | +| Runner | id, poolId, capabilities, credentialStatus, lastSeenAt | Dispatcher | +| Artifact | id, runId, attemptId, objectKey, digest, sizeBytes, mediaType | Platform API | +| Schedule | id, agentId, cron, timezone, nextRunAt, overlapPolicy | Dispatcher | +| Outbox | id, aggregateId, eventType, payload, deliveredAt | Пишущий сервис | + +## Инварианты + +- Между БД нет внешних ключей: идентификаторы проверяются API. Каждый сервис владеет своими транзакциями и outbox. +- Run ссылается на immutable AgentRevision и ExecutionSpec; повторная проверка прав не изменяет их содержимое. +- Published PackageVersion не перезаписывается. Политика блокировки хранится отдельно. +- Попытка имеет только одного текущего владельца lease; epoch монотонно растёт при новом назначении. +- Terminal report и смена состояния сохраняются одной транзакцией вместе с событием outbox. +- Resource ID не является доказательством доступа. Tenant scope проверяется независимо. +- ConnectionRef никогда не содержит значение секрета. +- Artifact считается готовым после проверки объекта и digest, а не после выдачи upload URL. + +## Схемы + +- [Манифест пакета](package-manifest.schema.json) — общий envelope четырёх видов пакетов. +- [ExecutionSpec](execution-spec.schema.json) — конкретный состав запуска. +- [Событие](run-event.schema.json) — события исполнителя. +- [Пример manifest](examples/template-manifest.json). +- [Пример ExecutionSpec](examples/execution-spec.json). + +Id — opaque string. Version — SemVer строка; разрешение диапазонов выполняет resolver до фиксации ExecutionSpec. Digest — SHA-256. Timestamps — RFC3339 UTC. UUID не навязывается публичным контрактом. + +Package manifest с kind=template обязан указать harnessVersionId, configSchemaRef и зависимости. Harness обязан указать entrypoint и executionKind. Plugin и skill указывают совместимость supportedHarnesses. Отсутствующая optional capability означает, что возможность недоступна; поле не может быть выведено из названия пакета. diff --git a/designDocument/contracts/examples/config.defaults.json b/designDocument/contracts/examples/config.defaults.json new file mode 100644 index 0000000..e1d22cc --- /dev/null +++ b/designDocument/contracts/examples/config.defaults.json @@ -0,0 +1,5 @@ +{ + "lookbackDays": 90, + "reportLanguage": "ru", + "includeSources": true +} diff --git a/designDocument/contracts/examples/config.schema.json b/designDocument/contracts/examples/config.schema.json new file mode 100644 index 0000000..ce0742b --- /dev/null +++ b/designDocument/contracts/examples/config.schema.json @@ -0,0 +1,34 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "title": "Настройки обзора компаний", + "additionalProperties": false, + "required": [ + "lookbackDays", + "reportLanguage", + "includeSources" + ], + "properties": { + "lookbackDays": { + "type": "integer", + "title": "Период анализа в днях", + "minimum": 1, + "maximum": 365, + "default": 90 + }, + "reportLanguage": { + "type": "string", + "title": "Язык отчёта", + "enum": [ + "ru", + "en" + ], + "default": "ru" + }, + "includeSources": { + "type": "boolean", + "title": "Показывать источники", + "default": true + } + } +} diff --git a/designDocument/contracts/examples/execution-spec.json b/designDocument/contracts/examples/execution-spec.json new file mode 100644 index 0000000..8147799 --- /dev/null +++ b/designDocument/contracts/examples/execution-spec.json @@ -0,0 +1,44 @@ +{ + "protocolVersion": "1", + "runId": "run_example", + "agentRevisionId": "revision_example_1", + "templateVersionId": "template_example_1", + "packages": [ + { + "packageVersionId": "template_example_1", + "kind": "template", + "digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "artifactRef": "artifact_template_example" + }, + { + "packageVersionId": "harness_example_1", + "kind": "harness", + "digest": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", + "artifactRef": "registry.example.invalid/invest/runtime@sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" + } + ], + "configSchemaDigest": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", + "config": { + "lookbackDays": 90, + "reportLanguage": "ru", + "includeSources": true + }, + "input": { + "company": "Example Company" + }, + "connections": {}, + "limits": { + "cpuMillis": 1000, + "memoryBytes": 1073741824, + "timeoutSeconds": 900, + "outputBytes": 104857600 + }, + "requiredCapabilities": [ + "oci-v1", + "cancel-v1" + ], + "entrypoint": [ + "/app/entrypoint", + "/input/execution.json" + ] +} diff --git a/designDocument/contracts/examples/template-manifest.json b/designDocument/contracts/examples/template-manifest.json new file mode 100644 index 0000000..51f3613 --- /dev/null +++ b/designDocument/contracts/examples/template-manifest.json @@ -0,0 +1,27 @@ +{ + "manifestVersion": "1", + "kind": "template", + "name": "company-review", + "version": "1.0.0", + "artifact": { + "ref": "artifact_template_example", + "digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "mediaType": "application/gzip" + }, + "dependencies": [ + { + "packageVersionId": "harness_example_1", + "digest": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" + } + ], + "harnessVersionId": "harness_example_1", + "configSchemaRef": "config.schema.json", + "defaultsRef": "config.defaults.json", + "uiSchemaRef": "ui.schema.json", + "requiredCapabilities": [ + "oci-v1", + "cancel-v1" + ], + "requiredPermissions": [], + "retrySafe": false +} diff --git a/designDocument/contracts/examples/ui.schema.json b/designDocument/contracts/examples/ui.schema.json new file mode 100644 index 0000000..920cdac --- /dev/null +++ b/designDocument/contracts/examples/ui.schema.json @@ -0,0 +1,17 @@ +{ + "type": "VerticalLayout", + "elements": [ + { + "type": "Control", + "scope": "#/properties/lookbackDays" + }, + { + "type": "Control", + "scope": "#/properties/reportLanguage" + }, + { + "type": "Control", + "scope": "#/properties/includeSources" + } + ] +} diff --git a/designDocument/contracts/execution-spec.schema.json b/designDocument/contracts/execution-spec.schema.json new file mode 100644 index 0000000..060b147 --- /dev/null +++ b/designDocument/contracts/execution-spec.schema.json @@ -0,0 +1,143 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "ExecutionSpec v1", + "type": "object", + "additionalProperties": false, + "required": [ + "protocolVersion", + "runId", + "agentRevisionId", + "templateVersionId", + "packages", + "configSchemaDigest", + "config", + "input", + "connections", + "limits", + "requiredCapabilities", + "entrypoint" + ], + "properties": { + "protocolVersion": { + "const": "1" + }, + "runId": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "agentRevisionId": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "templateVersionId": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "packages": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "packageVersionId", + "kind", + "digest", + "artifactRef" + ], + "properties": { + "packageVersionId": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "kind": { + "enum": [ + "harness", + "plugin", + "skill", + "template" + ] + }, + "digest": { + "type": "string", + "pattern": "^sha256:[a-f0-9]{64}$" + }, + "artifactRef": { + "type": "string", + "minLength": 1 + } + } + } + }, + "configSchemaDigest": { + "type": "string", + "pattern": "^sha256:[a-f0-9]{64}$" + }, + "config": { + "type": "object" + }, + "input": {}, + "connections": { + "type": "object", + "additionalProperties": { + "type": "string", + "minLength": 1, + "maxLength": 128 + } + }, + "limits": { + "type": "object", + "additionalProperties": false, + "required": [ + "cpuMillis", + "memoryBytes", + "timeoutSeconds", + "outputBytes" + ], + "properties": { + "cpuMillis": { + "type": "integer", + "minimum": 1 + }, + "memoryBytes": { + "type": "integer", + "minimum": 1 + }, + "timeoutSeconds": { + "type": "integer", + "minimum": 1 + }, + "outputBytes": { + "type": "integer", + "minimum": 1 + } + } + }, + "requiredCapabilities": { + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "minLength": 1 + } + }, + "entrypoint": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + } + }, + "checkpointRef": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "resumeInput": {} + } +} diff --git a/designDocument/contracts/package-manifest.schema.json b/designDocument/contracts/package-manifest.schema.json new file mode 100644 index 0000000..f797c8b --- /dev/null +++ b/designDocument/contracts/package-manifest.schema.json @@ -0,0 +1,188 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Invest Harness package manifest v1", + "type": "object", + "additionalProperties": false, + "required": [ + "manifestVersion", + "kind", + "name", + "version", + "artifact", + "dependencies" + ], + "properties": { + "manifestVersion": { + "const": "1" + }, + "kind": { + "enum": [ + "harness", + "plugin", + "skill", + "template" + ] + }, + "name": { + "type": "string", + "minLength": 1 + }, + "version": { + "type": "string", + "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?(\\+[0-9A-Za-z.-]+)?$" + }, + "artifact": { + "type": "object", + "additionalProperties": false, + "required": [ + "ref", + "digest", + "mediaType" + ], + "properties": { + "ref": { + "type": "string", + "minLength": 1 + }, + "digest": { + "type": "string", + "pattern": "^sha256:[a-f0-9]{64}$" + }, + "mediaType": { + "type": "string", + "minLength": 1 + } + } + }, + "dependencies": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "packageVersionId", + "digest" + ], + "properties": { + "packageVersionId": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "digest": { + "type": "string", + "pattern": "^sha256:[a-f0-9]{64}$" + } + } + } + }, + "harnessVersionId": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "configSchemaRef": { + "type": "string", + "minLength": 1 + }, + "defaultsRef": { + "type": "string", + "minLength": 1 + }, + "uiSchemaRef": { + "type": "string", + "minLength": 1 + }, + "executionKind": { + "enum": [ + "oci", + "native" + ] + }, + "entrypoint": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + } + }, + "supportedHarnesses": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1, + "maxLength": 128 + } + }, + "requiredCapabilities": { + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "minLength": 1 + } + }, + "requiredPermissions": { + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "minLength": 1 + } + }, + "retrySafe": { + "type": "boolean" + } + }, + "allOf": [ + { + "if": { + "properties": { + "kind": { + "const": "template" + } + } + }, + "then": { + "required": [ + "harnessVersionId", + "configSchemaRef" + ] + } + }, + { + "if": { + "properties": { + "kind": { + "const": "harness" + } + } + }, + "then": { + "required": [ + "executionKind", + "entrypoint" + ] + } + }, + { + "if": { + "properties": { + "kind": { + "enum": [ + "plugin", + "skill" + ] + } + } + }, + "then": { + "required": [ + "supportedHarnesses" + ] + } + } + ] +} diff --git a/designDocument/contracts/run-event.schema.json b/designDocument/contracts/run-event.schema.json new file mode 100644 index 0000000..dbe7b6b --- /dev/null +++ b/designDocument/contracts/run-event.schema.json @@ -0,0 +1,46 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "RunEvent v1", + "type": "object", + "additionalProperties": false, + "required": [ + "eventId", + "attemptId", + "sequence", + "occurredAt", + "type", + "payload" + ], + "properties": { + "eventId": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "attemptId": { + "type": "string", + "minLength": 1, + "maxLength": 128 + }, + "sequence": { + "type": "integer", + "minimum": 1 + }, + "occurredAt": { + "type": "string", + "format": "date-time" + }, + "type": { + "enum": [ + "progress", + "log", + "artifact_ready", + "input_requested", + "diagnostic" + ] + }, + "payload": { + "type": "object" + } + } +} diff --git a/designDocument/design.md b/designDocument/design.md new file mode 100644 index 0000000..696c931 --- /dev/null +++ b/designDocument/design.md @@ -0,0 +1,408 @@ +# Invest Harness + +## Определения + +| Термин | Значение | +|---|---| +| Harness | Движок и обвязка агента: цикл выполнения, управление контекстом, состоянием и вызовами инструментов | +| Runtime | Среда выполнения программы: например, Node.js или Python; определяется пакетом harness’а | +| Plugin | Программное расширение, добавляющее инструменты, интеграции или возможности | +| Skill | Инструкции и вспомогательные материалы для конкретной задачи; может содержать скрипты, но сам по себе не предоставляет доступы | +| Шаблон агента | Инструкции, совместимый harness, плагины, скиллы и схема пользовательских настроек | +| Экземпляр агента | Шаблон с настройками и подключениями пользователя | +| Run | Логический запуск с неизменяемым снимком версий, входных данных и настроек | +| Attempt | Одна попытка исполнения Run, назначенная конкретному Runner | +| Runner | Заменяемый исполнитель, подготавливающий окружение и запускающий harness | +| Каталог | Сервис метаданных пакетов, версий, совместимости и прав доступа с собственной БД | +| Registry | API доставки OCI-образов; байты образов находятся в отдельном хранилище | +| ExecutionSpec | Неизменяемое описание запуска, общее для локального и удалённого исполнения | +| Capability | Проверяемая возможность исполнителя: среда, протокол, отмена, checkpoint | +| Tenant | Организация или персональное пространство с отдельной границей доступа | +| Lease | Ограниченное по времени назначение Attempt исполнителю | + +## Концепция и статус + +Invest Harness — платформа агентов для инвестиций. Автор публикует шаблон и его зависимости, пользователь выбирает шаблон, настраивает его через автоматически построенную форму и запускает локально или удалённо. Оба режима используют один формат пакетов и ExecutionSpec. + +Документ задаёт целевую архитектуру и контракты первой версии. Реализация сервисов пока не входит в этот репозиторий. Выбранные технологии — проектные решения; численные показатели масштабирования — гипотезы до измерений. + +Для платформы содержимое окружения Runner — чёрный ящик. Внутри могут работать агентские цепочки, произвольные программы, разные модели и интеграции. Платформа отвечает за доставку пакетов, доступы, ресурсы, состояния и результаты. Она не задаёт инвестиционную стратегию и не гарантирует корректность финансовых выводов или внешних действий. Способность продолжить работу после сбоя должна быть явно объявлена пакетом. + +Локальный запуск уже загруженного публичного пакета не требует облачного аккаунта. Сеть может требоваться модели или инструментам. Публичность описания пакета не означает доступ к пользовательским данным. + +## Пользовательские сценарии + +1. Автор загружает версию пакета и схемы, проверяет зависимости и публикует версию. +2. Пользователь выбирает шаблон, заполняет форму и подключает разрешённые интеграции. Сохраняется ревизия экземпляра агента. +3. Пользователь запускает агента локально, в управляемом пуле или на своём Runner. +4. Платформа показывает состояние, события, файлы и итог, позволяет отменить запуск. +5. Если harness поддерживает запрос ввода и checkpoint, пользователь может ответить и продолжить выполнение отдельной попыткой. +6. Обновление шаблона создаёт новую ревизию агента после проверки настроек; текущие запуски не меняются. + +## Архитектура C4 + +Контейнер в C4 — отдельно запускаемое приложение или хранилище, не обязательно Docker-контейнер. Диаграммы используют нотацию Mermaid с явными типами элементов C4. C3 раскрывает логические модули, а не отдельные микросервисы. + +### C1 Контекст + +```mermaid +flowchart LR + U["Пользователь / Person"] + A["Автор и администратор / Person"] + P["Invest Harness / Software System"] + M["Модели и внешние интеграции / External System"] + L["Локальное окружение пользователя / External System"] + U -->|Выбор, настройка, запуск| P + A -->|Публикация и управление| P + P -->|Разрешённые вызовы| M + P -->|Пакеты и конфигурация| L + L -->|Вызовы по локальным доступам| M +``` + +### C2 Контейнеры и хранилища + +```mermaid +flowchart TB + U["Пользователь / Person"] + subgraph P["Invest Harness / Software System"] + G["Gateway / Container / Nginx"] + W["Web UI / Container / React, TypeScript, JSON Forms"] + I["Identity / Logical component of platform API / Sessions, OIDC"] + B["Platform API / Container / Go, REST"] + DB[("Platform DB / PostgreSQL / роли, агенты, запуски, аудит")] + C["Каталог / Container / Go, REST"] + CD[("Catalog DB / PostgreSQL / пакеты и версии")] + PS[("Package Storage / S3 / архивы плагинов, скиллов, шаблонов")] + D["Диспетчер / Container / Go"] + E["Сервис исполнения / Container / Go / workflow, jobs, адаптер"] + ED[("Execution DB / PostgreSQL / назначения и статусы движка")] + R["Registry API / Component of execution service / Go, OCI"] + RS[("Registry Storage / S3 / манифесты и слои образов")] + ES[("Execution Storage / S3 / логи и технические артефакты")] + X["Runner pool / Containers / стандартный адаптер или свой Runner"] + J["Job / Ephemeral container / harness и зависимости"] + T["Опциональный шлюз инструментов / Container / Go"] + S["Secrets / Managed service / KMS-backed encryption"] + F[("User Storage / S3 / вход, результат, checkpoint")] + O["Наблюдаемость / OTel, Prometheus, Grafana, Loki"] + end + L["Local client / Container on user device / Go CLI, Docker"] + M["LLM и внешние API / External Systems"] + U --> G + G --> W + G --> B + W -->|Вход| I + I --> DB + B -->|Проверка личности| I + B --> DB + B --> C + C --> CD + C --> PS + D -->|Готовые задания| DB + D -->|Зафиксировать версии| C + D -->|Назначение через адаптер| E + E --> ED + E --> ES + R -->|Метаданные| ED + R -->|Байты образов| RS + X -->|Runner Protocol, lease, heartbeat| D + X -->|OCI pull через API| R + X --> J + J -->|Токен запуска| B + J --> F + J --> T + J -->|При явно разрешённом прямом доступе| M + T -->|Проверка прав и бюджета| B + T --> S + T --> M + B --> F + D --> S + B -.-> O + C -.-> O + E -.-> O + X -.-> O + T -.-> O + U --> L + L -->|Пакеты| C + L -->|Образы| R + L -->|Локальные credentials| M +``` + +Путь X → D обозначает публичный протокол собственной реализации Runner. Стандартный исполнитель соединяется со своим движком через адаптер внутри сервиса исполнения; он не обязан нативно поддерживать этот протокол. Диспетчер остаётся единственным владельцем бизнес-решения о назначении. Нельзя одновременно выдавать один Attempt через обе системы очередей. + +Gateway логически обслуживает публичные HTTPS-маршруты; внутренние стрелки сокращены. Авторизация выполняется в принимающем сервисе и не заменяется наличием Gateway. Registry на схеме вынесен для наглядности, но может работать в одном процессе с сервисом исполнения. S3 buckets логически отдельны; физический сервис может быть общим. + +### C3 Каталог + +```mermaid +flowchart LR + U["Platform API / Author"] + subgraph C["Каталог / Container"] + A["REST API / Go"] + P["Проверка прав и видимости"] + V["Проверка манифеста, схем и digest"] + Q["Resolver зависимостей и совместимости"] + N["Публикация неизменяемой версии"] + end + DB[("Catalog DB / PostgreSQL")] + S[("Package Storage / S3")] + R["Registry API / OCI"] + U --> A + A --> P + P --> V + P --> Q + V --> N + V --> S + V --> R + N --> DB + Q --> DB +``` + +### C3 Исполнение и registry + +```mermaid +flowchart TB + D["Диспетчер / Go"] + X["Стандартный исполнитель или свой Runner"] + OCI["OCI client / Docker Engine"] + subgraph E["Сервис исполнения / Container"] + A["Execution adapter API / Go"] + P["Сервисная авторизация"] + W["Workflow и jobs"] + L["Назначения и состояния движка"] + H["Приём событий, логов и завершения"] + R["Registry API / OCI push и pull"] + end + DB[("Execution DB / PostgreSQL")] + RS[("Registry Storage / S3 / image bytes")] + ES[("Execution Storage / S3 / logs and artifacts")] + D --> A + A --> P + P --> W + W --> L + X -->|Через соответствующий адаптер| L + X --> H + H --> L + L --> DB + H --> ES + OCI --> R + R --> P + R -->|Метаданные| DB + R -->|Манифесты и слои| RS +``` + +### Технологии и границы реализации + +| Система | Стек | Как создаётся | +|---|---|---| +| Web UI | TypeScript, React, JSON Forms | Новый интерфейс | +| Platform API и identity | Go, REST, OpenAPI, сессии, OIDC | Продуктовый API с адаптацией существующих механизмов аккаунтов | +| Каталог | Go, PostgreSQL, S3 API | Новый отдельный сервис | +| Диспетчер | Go, PostgreSQL, transactional outbox | Новый слой квот и назначений | +| Сервис исполнения | Go, SQL, существующие workflow/jobs | Адаптация готового ядра; внутренние детали скрыты контрактом | +| Registry | Go, OCI Distribution API, PostgreSQL, S3 | Переиспользуемый компонент ядра | +| Стандартный Runner | Go, Docker Engine | Готовый исполнитель с адаптером | +| Собственный Runner | Любой язык, HTTPS Runner Protocol v1 | Независимая реализация; требуется проверка совместимости | +| Локальный клиент | Go CLI, Docker Engine | Общий resolver и ExecutionSpec; локальное состояние в файлах | +| Хранилища | PostgreSQL; S3-совместимое хранилище | Отдельные базы, buckets и сервисные учётные записи | +| Secrets | Envelope encryption, KMS; локально OS keychain | Провайдер выбирается при развёртывании | +| Шлюз инструментов | Go, HTTPS | Опциональный новый сервис | +| Наблюдаемость | OpenTelemetry, Prometheus, Grafana, Loki | Интеграция; без payload и секретов по умолчанию | +| Начальное развёртывание | Linux, Docker Compose, Nginx | Управление и исполнители на разных машинах | + +Runtime внутри harness’а не ограничен языком платформы. Kubernetes — будущая реализация Runner, не зависимость MVP. Kafka и отдельный координатор кластера в MVP не требуются. + +## Публикация пакета + +```mermaid +sequenceDiagram + participant A as Автор + participant C as Каталог + participant S as Package Storage / Registry + participant D as Catalog DB + A->>C: Создать draft и запросить upload + C-->>A: Ограниченный адрес загрузки + A->>S: Загрузить архив или OCI-образ + A->>C: Publish с digest и манифестом + C->>S: Проверить наличие, размер и digest + C->>C: Проверить схему и зависимости + C->>D: Зафиксировать immutable version + C-->>A: Published version +``` + +Метаданные опубликованы только после проверки объекта. Незавершённые загрузки убирает сборщик мусора после grace period. Каталог хранит четыре типа пакетов: harness, plugin, skill, template. Версии неизменяемы; блокировка — изменяемая политика доступа поверх версии. Детали: [каталог](catalog.md). + +## Настройка через JSON Schema + +Автор шаблона задаёт config.schema.json, config.defaults.json и необязательную ui.schema.json. Схемы настроек harness’а и плагинов подключаются шаблоном в отдельные пространства имён. Пользователь меняет значения, не схему автора. Secret-поля содержат ссылки на подключения, а не значения credentials. + +```mermaid +sequenceDiagram + participant U as Пользователь + participant W as Web / локальная форма + participant C as Каталог + participant B as Platform API / локальный валидатор + W->>C: Загрузить закреплённую схему и defaults + C-->>W: JSON Schema и UI Schema + W-->>U: Форма настроек + U->>W: Значения и ссылки на подключения + W->>B: Сохранить конфигурацию + B->>B: Проверить схему, права и policy + B-->>W: Новая immutable revision +``` + +Сервер повторно валидирует данные. Скрытое поле формы не является защитой. Defaults применяются отдельным шагом: JSON Schema default не заполняет данные автоматически. [Конфигурация и UI](configuration-ui.md). + +## Локальный запуск + +```mermaid +sequenceDiagram + participant U as Пользователь + participant L as Local client + participant C as Каталог / локальный кеш + participant R as Local Runner + participant H as Harness + U->>L: Запустить экземпляр агента + L->>C: Resolve и проверить digest + L->>L: Валидировать config, собрать ExecutionSpec + L->>R: Spec и локальные secret bindings + R->>H: Запустить в ограниченном окружении + H-->>R: События и результат + R-->>L: Итог и локальные файлы +``` + +## Удалённый запуск + +```mermaid +sequenceDiagram + participant U as Пользователь + participant B as Platform API + participant C as Каталог + participant D as Диспетчер + participant R as Runner / адаптер + participant S as Хранилища + U->>B: Создать Run с Idempotency-Key + B->>C: Resolve точных версий + B->>B: Сохранить Run и outbox в одной транзакции + D->>B: Обработать готовый Run + R->>D: Claim с capabilities + D-->>R: Attempt, lease, ExecutionSpec + R->>S: Загрузить пакеты по digest + R->>D: Heartbeat и события + R->>S: Загрузить результаты + R->>D: Complete с lease epoch и manifest результатов + D->>B: Финализировать Run + B-->>U: Статус и доступ к файлам +``` + +Обработка допускает повторную доставку; exactly-once внешних действий не обещается. Отзыв lease блокирует поздние записи в платформу, но не может отменить уже отправленный запрос во внешний сервис. [Исполнение](execution.md). + +## Авторизация + +```mermaid +sequenceDiagram + participant U as Пользователь + participant I as Identity + participant B as API + participant R as Runner + participant T as Tool gateway + participant S as Secrets + U->>I: Вход + I-->>U: Сессия + U->>B: Создать запуск + B->>B: Tenant, роль, пакет, подключения, квоты + B-->>R: Токен только назначенного Attempt + R->>T: Разрешённая операция + T->>B: Проверить права и актуальность Attempt + T->>S: Получить нужный credential + T-->>R: Результат без долгоживущего ключа +``` + +Прямые интеграции разрешаются явно: секрет может потребоваться внутри окружения. В таком режиме runner-owner становится частью границы доверия, а стоимость внешних вызовов нельзя ограничить только платформенным счётчиком. [Доступы и изоляция](security.md). + +## Состояния запуска + +```mermaid +stateDiagram-v2 + [*] --> queued + queued --> preparing: назначение + preparing --> running: окружение готово + running --> waiting_input: checkpoint и запрос ввода + waiting_input --> queued: подтверждённое продолжение + running --> succeeded: результат принят + preparing --> failed: ошибка подготовки + running --> failed: ошибка + preparing --> interrupted: потеря lease + running --> interrupted: потеря lease + interrupted --> queued: разрешённый повтор + interrupted --> failed: повтор запрещён + queued --> cancelled: отмена + waiting_input --> cancelled: отмена + preparing --> cancelling: запрос отмены + running --> cancelling: запрос отмены + cancelling --> cancelled: остановка подтверждена + cancelling --> interrupted: остановка не подтверждена + succeeded --> [*] + failed --> [*] + cancelled --> [*] +``` + +Переход в waiting_input освобождает исполнителя только после durable checkpoint. Для harness без checkpoint этот режим не предоставляется. При потере lease от собственного Runner результат внешних действий может остаться неизвестным. + +## Замена исполнителей + +```mermaid +flowchart TB + D["Диспетчер / tenant policy, capabilities, quotas"] + P["Runner Protocol v1 / HTTPS"] + A["Адаптер стандартного движка"] + R["Собственный Runner"] + K["Kubernetes Runner / после MVP"] + L["Local Runner"] + D --> P + P --> A + P --> R + P --> K + P --> L +``` + +Нативный Runner и адаптер не создают две независимые аренды одного Attempt: платформа хранит lease, адаптер сопоставляет его с executionId движка и подавляет дубликаты. Локальный автономный режим использует тот же ExecutionSpec, но не обязан регистрироваться в облаке. [Протокол Runner](api/executor-api.md). + +## Масштабирование + +```mermaid +flowchart LR + API["API replicas"] --> DB[("PostgreSQL / runs + outbox")] + D["Dispatcher replicas / atomic claims"] --> DB + D --> Q["Логические очереди tenants / fair scheduling"] + Q --> A["Управляемый пул"] + Q --> B["Собственные пулы tenants"] + A --> S[("S3 + локальные кеши образов")] + B --> S + A --> M["Внешние API / rate limits"] + B --> M +``` + +Ёмкость определяется активными запусками, длительностью и ресурсами; добавление исполнителей ограничено квотами внешних API. Реализации движка с одной активной репликой не масштабируются простым дублированием процесса: сначала проверяются ограничения ядра, затем шардирование по пулам. Формулы, отказы, SLO и retention: [масштабирование](scaling.md). + +## MVP и развитие + +MVP: четыре типа пакетов; immutable versions; конфигурация через формы; экземпляры агентов; ручной и регулярный запуск; стандартный и локальный Runner; документированный протокол своей реализации; отмена, события и результаты; tenant isolation; registry и buckets; аудит. + +Следующий этап: возобновление через checkpoint, пользовательский ввод, автоматическая миграция конфигураций, Kubernetes Runner, автоматическое масштабирование и коммерческий биллинг. Протокол заранее резервирует эти возможности, но UI не предлагает их без подтверждённой capability. + +Открытые решения: провайдер KMS и S3, конкретные версии зависимостей, политика модерации публичных пакетов, целевые SLO после нагрузочных измерений, перечень лицензий распространяемых runtime и пакетов. Публичный доступ к этому проекту сам по себе не задаёт лицензию его дальнейшего использования. + +## Подробные спецификации + +- [Каталог и версии](catalog.md) +- [JSON Schema Driven UI](configuration-ui.md) +- [Исполнение](execution.md) +- [Авторизация и изоляция](security.md) +- [Масштабирование](scaling.md) +- [Общие правила API](api/conventions.md) +- [API каталога](api/catalog-api.md) +- [API агентов](api/agents-api.md) +- [API запусков](api/runs-api.md) +- [Runner Protocol](api/executor-api.md) +- [Модель данных и JSON Schema](contracts/domain-model.md) diff --git a/designDocument/execution.md b/designDocument/execution.md new file mode 100644 index 0000000..7a9ba44 --- /dev/null +++ b/designDocument/execution.md @@ -0,0 +1,35 @@ +# Исполнение + +## Граница чёрного ящика + +Harness получает ExecutionSpec и разрешённые ресурсы. Его внутренний цикл не управляется платформой. Для участия в платформе пакет предоставляет entrypoint и адаптер событий. Exit code 0 означает успешное завершение процесса, но Run становится succeeded только после проверки ResultManifest и сохранения артефактов. Ошибка финансового рассуждения не определяется статусом процесса. + +## Планирование + +API в одной транзакции записывает Run, reservation квоты и outbox. Диспетчер обрабатывает outbox идемпотентно по runId. Resolve выполняется до создания снимка; назначение повторно проверяет block policy и права. Попытка захватывается атомарно с leaseEpoch. Стандартный execution adapter использует runId/attemptId как ключ дедупликации, хранит соответствие с executionId движка и сверяет состояние при неоднозначном ответе. + +Расписания хранят IANA timezone, cron expression, nextRunAt и overlapPolicy: skip или queue. В MVP catch-up после простоя создаёт не более одного пропущенного запуска. Уникальный ключ scheduleId + scheduledAt предотвращает дубли. При переходах DST пропущенное локальное время пропускается, повторённое выполняется один раз; scheduledAt фиксируется как UTC instant. Ручной запуск имеет отдельный ключ. + +## Lease и повторы + +Начальные настройки: lease 90 секунд, heartbeat каждые 20 секунд, maxAttempts 3 только для явно retry-safe задач. Важна серверная шкала времени. Каждый heartbeat и terminal report содержит attemptId, leaseEpoch и sequence. Устаревший epoch возвращает 409 и не может изменить состояние Run. + +Потеря lease переводит Run в interrupted. Автоповтор разрешён, только если template объявил retrySafe и policy организации позволяет; иначе нужен явный retry пользователя после предупреждения о возможном повторе внешних действий. Checkpoint continuation создаёт новый Attempt того же Run. Retry terminal Run создаёт новый Run с parentRunId и тем же снимком, но с актуальной проверкой прав. + +Fencing защищает записи платформы, но не останавливает старый процесс на недоступной машине и не обеспечивает exactly-once сторонних API. Повторные внешние действия должен защищать сам harness или поддерживающий idempotency key шлюз. + +## Отмена и ожидание + +Cancel queued снимает reservation и сразу завершает Run. Cancel running устанавливает cancelling; Runner прекращает процесс и возвращает подтверждение. Для управляемого Runner после grace period выполняется принудительная остановка. Без подтверждения собственного Runner состояние становится interrupted, а не falsely cancelled. Поздний success после принятой отмены не отменяет запрос пользователя. + +Waiting_input поддерживается только с capability checkpoint-v1: Runner сохраняет checkpoint, передаёт его digest и input schema, получает подтверждение, затем освобождает lease. Ответ пользователя валидируется, разрешение проверяется заново. Повтор responseId не создаёт ещё одну попытку. Новое продолжение закрепляется за исходным ExecutionSpec. + +## Локальный режим + +Клиент скачивает lock и артефакты, проверяет digest и разрешения, сохраняет ExecutionSpec, запускает локальный Runner. Credentials поступают из OS keychain или выбранного пользователем провайдера. Облачная регистрация не обязательна для кешированных публичных пакетов. Синхронизация результатов с облаком — отдельное явное действие, не поведение по умолчанию. + +## Артефакты + +Runner запрашивает upload grant для конкретного Attempt и назначения файла. Grant ограничен размером, сроком и префиксом. ResultManifest содержит artifactId, digest, size и mediaType, без произвольных URL. Сервис проверяет существование объектов до terminal success. Логи доставляются отдельно и не являются единственным источником состояния. + +[Runner Protocol](api/executor-api.md) · [Состояния и диаграммы](design.md). diff --git a/designDocument/scaling.md b/designDocument/scaling.md new file mode 100644 index 0000000..63f7b23 --- /dev/null +++ b/designDocument/scaling.md @@ -0,0 +1,58 @@ +# Масштабирование Invest Harness + +## Модель нагрузки + +Число аккаунтов не определяет ёмкость. Измеряем arrival rate λ, среднюю и p95 длительность T, CPU и память Attempt, размер образа, объём логов, количество внешних запросов и число одновременных подключений. Раздельные классы: короткие интерактивные задачи, длинные фоновые, периодические и сборка пакетов. + +По Little’s law среднее число активных задач L = λ × T. Для целевой загрузки слотов ρ начальная оценка slots ≥ λ × T / ρ. Пример-гипотеза: 120 запусков/мин, 180 секунд на запуск, ρ=0.7 → около 515 слотов. Это не 515 серверов: число слотов на узле ограничено одновременно CPU, RAM, диском и квотами API. Хвосты длительности требуют нагрузочного измерения, а не подстановки p95 в доказательство SLO. + +## Очереди и backpressure + +Admission control резервирует tenant concurrency и бюджет перед назначением. Weighted fair scheduling чередует tenants; внутри tenant приоритет + возраст. Ограничены queue depth и max queue age. При превышении пользователь получает 429 с Retry-After либо явный queued status по принятой policy. Бесконечного скрытого backlog быть не должно. + +Учитываем лимиты внешних API, токены/мин, соединения и доступность источников. Шлюз контролирует свои вызовы. Для прямых вызовов Runner платформа гарантирует только ресурсные/временные лимиты, а финансовый предел зависит от провайдера credentials. + +## Масштабирование компонентов + +| Компонент | Стратегия | Ограничение | +|---|---|---| +| Stateless API и каталог | Несколько реплик за Gateway | Пулы SQL и согласованность прав | +| Диспетчер | Atomic claims, partitioning по tenant/pool | Единственное назначение Attempt и fencing | +| Сервис исполнения | Сначала ресурсы и отдельные пулы, затем проверенное шардирование | Нельзя предполагать поддержку active-active ядром | +| Runner | Масштабирование по ready queue age и свободным ресурсам | Внешние API и время загрузки образа | +| PostgreSQL | Индексы, bounded pagination, архивирование; read replicas для допустимо устаревших чтений | Назначения и авторизация читаются из актуального источника | +| S3 / registry | Прямые scoped grants, кеш по digest, лимит параллельных загрузок | Bandwidth, egress, cache isolation | + +Горячие индексы: Run(tenantId, createdAt, id), Run(status, nextEligibleAt, id), Attempt(poolId, leaseUntil), Package(tenantId, kind, name), уникальный PackageVersion(packageId, version). Большие события и логи не хранятся целиком в строке Run. + +## Прогрев и масштабирование исполнителей + +Managed pool хранит небольшой warm reserve. Scale-out — по времени ожидания совместимых задач, scale-in — после drain: новые задания не выдаются, активные завершаются. Кеш неизменяемых образов по digest экономит загрузки. Приватные образы и архивы не выдаются другому tenant без проверки доступа. Garbage collection кеша использует размер и last-used; pinned active layers не удаляются. + +Собственный пул имеет независимые лимиты и SLA владельца. Недоступность такого пула не переносит задание автоматически в управляемый: credentials и политика размещения могут запрещать перенос. + +## Отказы + +| Сбой | Поведение | +|---|---| +| API после записи Run | Повтор Idempotency-Key возвращает прежний Run | +| Dispatcher после отправки job | Reconcile по attemptId, без второго внешнего запуска | +| Runner потерял связь | Lease expires → interrupted; retry только по policy | +| S3 недоступен при завершении | Нет succeeded до проверки ResultManifest | +| Catalog недоступен | Новые resolve ждут/ошибка; закреплённые запускать только при актуальной policy | +| Registry недоступен | Кеш допустим при проверке digest и актуальных прав; иначе очередь | +| SQL недоступен | Новые назначения остановлены; terminal reports повторяются идемпотентно | + +## Retention и восстановление + +Исходные настраиваемые значения: orphan uploads 24 часа; debug-логи 14 дней; результаты 30 дней; аудит 180 дней. Это проектные значения, а не юридические обязательства. Активные Run и checkpoints защищены от очистки. Образы удаляются только после проверки ссылок, grace period и доступности backup. + +Backup включает БД, объекты, ключевые конфигурации и возможность восстановления ключей шифрования. Проверяется согласованное восстановление metadata → digest → object. Цели для первой проверки: RPO 1 час, RTO 4 часа, без обещания до rehearsal. + +## Метрики и проверка + +Предлагаемые цели пилота: p95 control API <500 мс без внешних вызовов; p95 queue wait <30 секунд при нагрузке в пределах квоты и доступном пуле. Время выполнения чёрного ящика не включается в API SLO. Следим за queue age, interrupted rate, attempts/run, event lag, orphan bytes, cache hit, SQL saturation и стоимостью на Run. + +Нагрузочные сценарии: равномерный поток, массовый scheduled burst с jitter, один шумный tenant, недоступный внешний API, перезапуск dispatcher, потеря Runner, медленный S3, дубли terminal reports. Отдельно проверяем отсутствие чужих артефактов и credentials. + +Стоимость = вычисления + хранение + egress + управляемые вызовы моделей. Цена прямых сторонних вызовов может быть неизвестна. Биллинг не строится исключительно на недоверенных отчётах пользовательского Runner. diff --git a/designDocument/security.md b/designDocument/security.md new file mode 100644 index 0000000..fda5073 --- /dev/null +++ b/designDocument/security.md @@ -0,0 +1,31 @@ +# Доступы и изоляция + +## Идентичность и роли + +Tenant — персональное или организационное пространство. Роли: owner управляет доступами и удалением; admin — настройками и Runner; publisher — публикацией пакетов; operator — запуском и отменой доступных агентов; viewer — чтением разрешённых ресурсов. Сервер получает tenant из проверенного membership, а не доверяет tenantId в запросе. Каждый доступ к agent, run, package, connection и artifact проверяется отдельно. + +Identity в MVP — модуль Platform API с существующими механизмами аккаунтов и сессий; внешний OIDC подключается при необходимости. Web использует HttpOnly Secure SameSite cookie и CSRF-защиту мутаций. CLI использует ограниченный токен; device authorization добавляется при поддержке identity-провайдером. Подписанный токен проверяется по issuer, audience, expiry и revocation policy. + +## Исполнители + +Владелец tenant создаёт одноразовый registration grant для пула. Runner обменивает grant на собственную служебную идентичность. Отзыв блокирует новые задания и доступы. Capabilities — заявление исполнителя, а не доказательство изоляции; управляемые пулы проходят conformance checks. Пользовательские пулы явно маркируются как customer-managed. + +Каждому Attempt выдаётся короткоживущий токен с runId, attemptId, tenantId, leaseEpoch, audience и scope. Он не предоставляет чтение чужих Run и доступ к администрированию. Сервер проверяет активность lease при чувствительных операциях. + +## Секреты и интеграции + +ConnectionRef указывает на запись подключения. Секрет хранится с envelope encryption, ключ расшифровки управляется KMS. Значения не попадают в config, логи, схемы, артефакты и signed URL. Доступ ограничивается интеграцией и операцией. Шлюз по возможности вызывает API сам; для прямого доступа выдаются scoped credentials или секрет монтируется только в окружение конкретной попытки. + +Own Runner имеет техническую возможность прочитать выданные ему credentials; эта граница доверия показывается владельцу при назначении подключений. Отзыв токена платформы не отзывает уже раскрытый сторонний ключ: для этого нужен revoke у провайдера. + +## Изоляция + +Управляемое выполнение: отдельная рабочая директория и контейнер, non-root, лимиты CPU/RAM/PIDs/диска/времени, отсутствие host mounts, privileged mode и Docker socket внутри job. Сетевые политики ограничивают обращения к внутренним адресам и metadata endpoints. Для недоверенного кода выбирается усиленный sandbox runtime; один обычный контейнер не считается полной защитой от побега. + +Runner Protocol не навязывает реализацию sandbox, но диспетчер не назначает защищённые задачи пулу без нужной trust policy. Невозможность обеспечить ограничение должна приводить к отказу до запуска. + +## Аудит и данные + +Аудит: actor, tenant, action, resource, result, timestamp, requestId. Без содержимого prompts и secrets по умолчанию. История публикаций, выдачи credentials, назначения, отмены, обновления настроек и изменений прав сохраняется отдельно от debug-логов. + +Удаление tenant сначала блокирует новые запуски, отзывает доступ, останавливает задачи и удаляет данные по retention policy. Backup retention и сроки окончательного удаления явно сообщаются пользователю. Публичность пакета не распространяется на Run, connections или результаты.