From 41a4397ed2b1a28426ac28dd8fd9b2534c18e33f Mon Sep 17 00:00:00 2001 From: admin Date: Wed, 11 Nov 2026 05:24:36 +0000 Subject: [PATCH] =?UTF-8?q?=D0=A3=D1=82=D0=BE=D1=87=D0=BD=D0=B8=D1=82?= =?UTF-8?q?=D1=8C=20DSH,=20=D0=BF=D0=BB=D0=B0=D0=B3=D0=B8=D0=BD=D1=8B,=20r?= =?UTF-8?q?oadmap=20=D0=B8=20=D0=BA=D0=BE=D0=BD=D1=82=D1=80=D0=B0=D0=BA?= =?UTF-8?q?=D1=82=D1=8B=20=D0=B8=D1=81=D0=BF=D0=BE=D0=BB=D0=BD=D0=B5=D0=BD?= =?UTF-8?q?=D0=B8=D1=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- designDocument/api/agents-api.md | 2 +- designDocument/api/conventions.md | 2 +- designDocument/api/executor-api.md | 20 ++- designDocument/api/provider-api.md | 35 ++++ designDocument/api/runs-api.md | 16 +- designDocument/catalog.md | 6 + designDocument/configuration-ui.md | 2 + designDocument/contracts/domain-model.md | 18 ++- .../contracts/examples/input.schema.json | 15 ++ .../contracts/examples/output.schema.json | 15 ++ .../contracts/examples/template-manifest.json | 4 +- .../contracts/execution-spec.schema.json | 8 +- .../contracts/package-manifest.schema.json | 43 ++++- .../contracts/result-manifest.schema.json | 44 +++++ .../contracts/run-event.schema.json | 153 +++++++++++++++++- .../contracts/runner-assignment.schema.json | 83 ++++++++++ designDocument/design.md | 107 +++++++++++- designDocument/dsh-foundation.md | 39 +++++ designDocument/execution.md | 16 +- designDocument/plugins.md | 49 ++++++ designDocument/provider-edge-cases.md | 25 +++ designDocument/review.md | 40 +++++ designDocument/roadmap.md | 26 +++ designDocument/scaling.md | 4 +- designDocument/security.md | 8 +- 25 files changed, 743 insertions(+), 37 deletions(-) create mode 100644 designDocument/api/provider-api.md create mode 100644 designDocument/contracts/examples/input.schema.json create mode 100644 designDocument/contracts/examples/output.schema.json create mode 100644 designDocument/contracts/result-manifest.schema.json create mode 100644 designDocument/contracts/runner-assignment.schema.json create mode 100644 designDocument/dsh-foundation.md create mode 100644 designDocument/plugins.md create mode 100644 designDocument/provider-edge-cases.md create mode 100644 designDocument/review.md create mode 100644 designDocument/roadmap.md diff --git a/designDocument/api/agents-api.md b/designDocument/api/agents-api.md index 24f1348..7521189 100644 --- a/designDocument/api/agents-api.md +++ b/designDocument/api/agents-api.md @@ -28,4 +28,4 @@ UpgradePreview: fromVersionId, toVersionId, changes:[{path, kind}], validation, ## Подключения -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 после отзыва запрещено. +GET /v1/connections возвращает Page с cursor и limit, без credentials. Подключения создаются через provider authorization flow; единый контракт и защищённая передача API key описаны в [Provider API](provider-api.md). DELETE /v1/connections/{id} отзывает платформенный доступ и при возможности выполняет revoke у провайдера. Повторное использование в новом Run после отзыва запрещено. diff --git a/designDocument/api/conventions.md b/designDocument/api/conventions.md index ade02be..2ba6a9e 100644 --- a/designDocument/api/conventions.md +++ b/designDocument/api/conventions.md @@ -28,6 +28,6 @@ PATCH/PUT изменяемых ресурсов требуют If-Match, отв ## События и файлы -SSE endpoint принимает Last-Event-ID; event id монотонен в пределах Run. После retention слишком старый cursor возвращает 410 с указанием получить snapshot. Повторные события дедуплицируются по eventId. SSE не является источником истины о состоянии: GET Run возвращает канонический snapshot. +SSE endpoint принимает Last-Event-ID; SSE cursor монотонен в пределах Run и назначается сервером, отдельно от runner eventId. После retention слишком старый cursor возвращает 410 с указанием получить snapshot. Повторные runner events дедуплицируются по attemptId + eventId. SSE data содержит RunEvent, а transport id — серверный cursor; клиент хранит cursor для reconnect. 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 index 3a2d85a..cebfe1a 100644 --- a/designDocument/api/executor-api.md +++ b/designDocument/api/executor-api.md @@ -12,19 +12,19 @@ Capabilities: os, architecture, executionKinds:["oci"], features:["cancel-v1"], | Метод и путь | Запрос | Ответ | |---|---|---| -| POST /v1/runner-jobs/claim | runnerId, availableSlots, capabilitiesRevision | 200 Assignment или 204 | -| POST /v1/attempts/{id}/heartbeat | leaseEpoch, sequence, progress? | 200 {leaseUntil, cancelRequested} | +| POST /v1/runner-jobs/claim | runnerId, claimRequestId, availableSlots, capabilitiesRevision | 200 Assignment или 204 | +| POST /v1/attempts/{id}/heartbeat | leaseEpoch, sequence, progress? | 200 {leaseUntil, executionToken, tokenExpiresAt, 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 пула. +Assignment: attemptId, runId, leaseEpoch, leaseUntil, executionSpec, attemptContext, executionToken, tokenExpiresAt. См. [схему](../contracts/runner-assignment.schema.json). 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. +Outcome: succeeded/failed/cancelled. Success требует ResultManifest и сохранённых объектов, даже если artifacts пуст. Error: code, message, retryableHint; решение о retry принимает платформа. Complete повторяется с тем же completionId и телом; другой payload после terminal state → 409. Поздние heartbeat и события с прежним epoch → 409 LEASE_EXPIRED. Повтор уже принятого complete с тем же completionId и телом возвращает сохранённый ответ даже после истечения lease, но никогда не меняет состояние. Для этого replay допускается с действующей идентичностью назначенного Runner; новый terminal report с устаревшим epoch запрещён. События могут доставляться повторно; уникальны по attemptId + eventId. -Suspend допустим только для checkpoint-v1 + input-v1. InputRequest: id, schema, prompt, expiresAt. Платформа принимает checkpoint, переводит Run в waiting_input, отзывает lease; новый Attempt получает checkpointRef и проверенный ответ. Без checkpoint протокол не обещает сохранение памяти процесса. +Suspend допустим только для checkpoint-v1 + input-v1. InputRequest: id, schema, prompt, expiresAt. Платформа принимает checkpoint, переводит Run в waiting_input, отзывает lease; новый Attempt получает checkpointRef и проверенный ответ в AttemptContext, отдельно от ExecutionSpec. Без checkpoint протокол не обещает сохранение памяти процесса. ## Локальный процесс @@ -35,3 +35,13 @@ Suspend допустим только для checkpoint-v1 + input-v1. InputRequ ## Минимальная проверка совместимости Runner обязан показать: корректный success; failure; отказ при несовместимом spec; отмену; тайм-аут; повтор complete без дублей; отказ с просроченным lease; изоляцию файлов между задачами; корректный upload digest; отсутствие secrets в событиях. Resume проверяется только при соответствующей capability. Managed и customer-managed пулы отображаются раздельно. + +## Восстановление потерянного ответа + +claimRequestId уникален в пределах runnerId. Повтор claim с тем же ID и телом возвращает то же назначение (или исходный 204), не занимает новый слот. Дедупликация хранится 24 часа; перед повторным получением работы после reconnect Runner вызывает GET /v1/runners/{id}/assignments (200 {items:[Assignment]}) со своей идентичностью. Endpoint возвращает только активные назначения этого Runner и перевыпускает их короткие токены. Если lease уже утрачен, старую работу прекращают; восстановление не продлевает истёкший lease. + +Heartbeat продлевает lease и executionToken не дальше deadlineAt. Complete ID и хеш тела сохраняются до удаления Run. Sequence монотонен внутри потока событий; heartbeat/started имеют отдельный счётчик controlSequence (поле sequence в этих запросах), чтобы доставка логов не блокировала lease. Повтор с тем же номером и другим телом — 409. Конфликт события по eventId либо sequence также даёт 409. Клиент сериализует control-запросы. + +ResultManifest валидируется по [схеме](../contracts/result-manifest.schema.json), а output — дополнительно по outputSchemaRef шаблона. InputRequest schema использует тот же ограниченный профиль, что формы настроек. Событие input_requested информационное; только успешный suspend меняет состояние. + +Повтор claim не возобновляет утраченную аренду: если сохранённое назначение уже неактивно, сервер возвращает 409 ASSIGNMENT_EXPIRED. Перед запуском из повторного ответа Runner проверяет leaseUntil по серверному времени. ClaimRequestId с иным телом возвращает 409. Поля runId в Assignment и вложенном ExecutionSpec должны совпадать; server validator проверяет это отдельно от JSON Schema. diff --git a/designDocument/api/provider-api.md b/designDocument/api/provider-api.md new file mode 100644 index 0000000..5b609bd --- /dev/null +++ b/designDocument/api/provider-api.md @@ -0,0 +1,35 @@ +# Provider API v1 + +Platform identity и provider identity независимы. Все операции требуют текущего actor и tenant; запрос к provider mode допускается только если матрица разрешает local/on_prem/managed_remote. Provider broker — модуль Platform API для управляемых credentials, локальный аналог — sidecar; provider plugin вызывается в изолированном host, а не внутри API-процесса. + +| Метод и путь | Запрос | Ответ | +|---|---|---| +| GET /v1/providers | deploymentMode | 200 {items:[ProviderDescriptor]} | +| POST /v1/provider-auth-flows | providerId, methodId, placement, returnRoute | 201 AuthFlow | +| GET /v1/provider-auth-flows/{id} | — | 200 AuthFlow с текущим status | +| DELETE /v1/provider-auth-flows/{id} | — | 204, flow cancelled | +| GET /v1/provider-auth/callback/{providerId} | state, code или error | 303 на allowlisted внутренний returnRoute | +| GET /v1/connections/{id} | — | 200 ConnectionSummary | +| POST /v1/connections/{id}/verify | — | 200 {status, capabilities, checkedAt} | +| GET /v1/connections/{id}/models | cursor, limit | 200 Page | +| DELETE /v1/connections/{id} | — | 204 после платформенного revoke; remote revoke best effort с аудитом | + +ProviderDescriptor: id, pluginVersionId, methods:[{id, kind:api_key/oauth_pkce/device_code/official_client, allowedPlacements, status:enabled/gated/unsupported, reason?}], capabilitiesRevision. methodId определяется provider adapter; браузер не выбирает произвольный OAuth endpoint. + +AuthFlow: id, providerId, methodId, status:pending/connected/failed/expired/cancelled, expiresAt, action:{type:open_url/device_code/local_client, url?, userCode?, intervalSeconds?}, connectionId?. PKCE verifier, refresh token и client secret не возвращаются клиенту. returnRoute — относительный allowlisted путь. API-key создаётся через защищённый POST /v1/connections, описанный ниже, не через GET callback. + +ConnectionSummary: id, tenantId, ownerId, providerId, pluginVersionId, authMode, placement, bindingId?, status:active/reauth_required/revoked/error, scopes, accountLabel, expiresAt?, capabilitiesRevision. bindingId для runner_private_store привязывает к одному разрешённому пулу/пользовательскому окружению. Verify не выполняет платный inference без отдельного opt-in; model list не гарантирует entitlement. + +POST auth flow и verify принимают Idempotency-Key. OAuth callback одноразовый, проверяет state, expiry, actor binding и exact redirect URI; при потере пользовательской сессии завершение требует reauth владельца. Device polling выполняет broker по interval, не каждая открытая вкладка. Authentication errors возвращаются нормализованно без raw provider token response. + +## Инференс как внутренний контракт + +ProviderInvocation: invocationId, runId, attemptId, connectionId, modelId, request, deadlineAt, capabilityRequirements. Доступ проверяется по executionToken и активному lease. Обёртка DSH нормализует stream events, usageStatus и terminal outcome. Credentials доступны только разрешённому adapter/официальному клиенту; shared глобального аккаунта нет. Внешний provider request id сохраняется для диагностики и дедупликации, если API поддерживает её. + +## Передача API key + +POST /v1/connections принимает {providerId, methodId, placement, label, credentialInput?, bindingId?}; ответ 201 ConnectionSummary. Для server_vault credentialInput={apiKey:string} передаётся только в TLS body, исключается из access/error logs, tracing и сохранения idempotency payload; сервер хранит только хеш запроса и зашифрованный ключ. Для local_keychain/runner_private_store ключ принимает локальный broker, облачный API получает только подтверждённый bindingId. Переданный клиентом bindingId проверяется на владельца и proof-of-possession от доверенного broker. API не принимает локальный путь к чужому файлу или произвольный vault URI. + +GET /v1/connections принимает cursor/limit и возвращает Page. ModelDescriptor: id, providerId, displayName, capabilities, contextWindow?, availability:unknown/available/unavailable, checkedAt?. Поля capabilities — набор поддержанных операций (text, tools, image_input, structured_output), а не гарантия доступа к модели по подписке. + +AuthFlow создаётся только для oauth_pkce/device_code/official_client. Callback OAuth использует GET только для провайдеров с query response mode; иной response mode требует отдельного адаптера и conformance. По истечении expiresAt flow больше не может создавать connection. Внешний callback без пользовательской cookie проверяет flow binding, а выдача connection пользователю требует исходную сессию либо повторный вход владельца. diff --git a/designDocument/api/runs-api.md b/designDocument/api/runs-api.md index 59a23e5..8aa9491 100644 --- a/designDocument/api/runs-api.md +++ b/designDocument/api/runs-api.md @@ -13,14 +13,14 @@ | 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 | +| POST /v1/schedules | agentId, agentRevision, cron, timezone, overlapPolicy, misfirePolicy? | 201 Schedule | operator; cron и timezone валидируются | +| PATCH /v1/schedules/{id} | agentRevision?, cron?, timezone?, enabled?, overlapPolicy?, misfirePolicy?; 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 интерпретируется как пять полей (минута, час, день месяца, месяц, день недели); шаг менее минуты не поддерживается. +Schedule: id, tenantId, agentId, agentRevisionId, cron, timezone, overlapPolicy (skip/queue), misfirePolicy (skip/coalesce), enabled, nextRunAt, revision. Расписание закрепляет agentRevisionId при создании. Новая ревизия применяется только явным PATCH расписания; уже созданные Run не меняются. Cron интерпретируется как пять полей (минута, час, день месяца, месяц, день недели); шаг менее минуты не поддерживается. Limits: cpuMillis, memoryBytes, timeoutSeconds, outputBytes. Пользователь может запросить меньше предела policy; превышение даёт 422, а не скрытое повышение прав. Input — JSON по input schema template. PoolId не даёт доступ к чужому пулу. @@ -31,3 +31,13 @@ Limits: cpuMillis, memoryBytes, timeoutSeconds, outputBytes. Пользоват ``` Отмена не гарантирует отмену уже совершённого внешнего действия. Reconcile технического статуса выполняет сервис исполнения; пользовательский запрос не переписывает состояние Runner произвольно. + +## Семантика расписаний + +GET /v1/schedules/{id} возвращает Schedule. POST /v1/schedules/preview принимает cron, timezone, from, count (1–10) и возвращает {occurrences:[UTC timestamp], warnings:[]}; сохранения не выполняет. Pause — PATCH enabled=false, resume — PATCH enabled=true; оба требуют If-Match. Возобновление не догоняет периоды явной паузы. + +Cron: пять полей; день недели 0–6 (0 — воскресенье); если day-of-month и day-of-week ограничены одновременно, применяется OR. DST: несуществующее локальное время пропускается, двойное — первое вхождение. Обновление tzdata пересчитывает только будущие occurrences; версия tzdata записывается в аудит. Первый релиз не поддерживает jitter и интервалы меньше минуты. + +Skip отбрасывает occurrence, если у расписания есть нетерминальный Run. Queue допускает один активный и максимум один ожидающий Run; лишние occurrences объединяются с ожидающим. При простое misfirePolicy=coalesce (default) выбирает последний пропущенный occurrence, skip не создаёт Run. Уникальность (scheduleId, scheduledAt) гарантируется БД. Проверка overlap и создание Run выполняются под блокировкой строки Schedule в одной транзакции. Ручные Run не учитываются в overlap, но учитываются в квотах tenant. + +Отзыв доступа к агенту/connection, блокировка пакета и архивирование агента останавливают расписание с reason, не создавая бесконечную череду failed Run. Любой запуск повторно проверяет права владельца расписания. Локальное расписание требует работающего daemon; перенос в облако отключает прежнего владельца до включения нового. diff --git a/designDocument/catalog.md b/designDocument/catalog.md index 118a17a..0f67ee0 100644 --- a/designDocument/catalog.md +++ b/designDocument/catalog.md @@ -27,3 +27,9 @@ Resolver принимает templateVersionId и профиль среды. Он Deprecated версия доступна закреплённым агентам, но скрыта из стандартного выбора. Удаление referenced-версии возвращает 409. Физическая очистка допускается после retention запусков, проверки ссылок и grace period. Immutable артефакты адресуются по digest; signed URL не сохраняется в постоянном lock. API: [catalog-api.md](api/catalog-api.md). Все диаграммы: [design.md](design.md). + +## DSH и схемы ввода/вывода + +Каталог хранит оригинальный DSH plugin artifact вместе с платформенным manifest envelope. Поля dshCompatibility фиксируют диапазон DSH, runtime, entry module и поддержанный профиль; tested versions и digest находятся в отчёте проверки каталога. Декларация автора не даёт badge совместимости. Плагины с зависимостью от API платформы явно объявляют endpoint и scopes; offline режим может не поддерживаться. + +Template публикует inputSchemaRef и outputSchemaRef в том же архиве. Resolver включает архив по digest в lock, а API валидирует input до создания Run и output до success. UI схемы относятся к настройкам; дополнительные права не могут выдаваться значениями формы. См. [DSH foundation](dsh-foundation.md) и [плагины](plugins.md). diff --git a/designDocument/configuration-ui.md b/designDocument/configuration-ui.md index 63fe6ea..93111da 100644 --- a/designDocument/configuration-ui.md +++ b/designDocument/configuration-ui.md @@ -36,3 +36,5 @@ PUT конфигурации требует If-Match. При конфликте - [Пример схемы](contracts/examples/config.schema.json) - [Начальные значения](contracts/examples/config.defaults.json) - [Представление формы](contracts/examples/ui.schema.json) + +Ограниченный набор JSON Schema keywords относится к пользовательским формам config/input. Служебные схемы протокола могут использовать allOf/if/then и не передаются renderer. Версия профиля валидатора закрепляется вместе с шаблоном; несовместимая схема отвергается при публикации. diff --git a/designDocument/contracts/domain-model.md b/designDocument/contracts/domain-model.md index 038cb80..c226416 100644 --- a/designDocument/contracts/domain-model.md +++ b/designDocument/contracts/domain-model.md @@ -11,13 +11,13 @@ | 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 | +| Connection | id, tenantId, ownerId, providerId, authMode, placement, status, secretBindingRef | 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 | +| Attempt | id, runId, runnerId, leaseEpoch, leaseUntil, status | Dispatcher / Platform DB | +| RunnerPool | id, tenantId, trustPolicy, quotas | Dispatcher / Platform DB | +| Runner | id, poolId, capabilities, credentialStatus, lastSeenAt | Dispatcher / Platform DB | | Artifact | id, runId, attemptId, objectKey, digest, sizeBytes, mediaType | Platform API | -| Schedule | id, agentId, cron, timezone, nextRunAt, overlapPolicy | Dispatcher | +| Schedule | id, agentId, agentRevisionId, cron, timezone, nextRunAt, overlapPolicy, misfirePolicy | Dispatcher / Platform DB | | Outbox | id, aggregateId, eventType, payload, deliveredAt | Пишущий сервис | ## Инварианты @@ -42,3 +42,11 @@ 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 означает, что возможность недоступна; поле не может быть выведено из названия пакета. + +Run, Attempt, Schedule и reservations составляют одну транзакционную область Platform DB. Внешние Execution DB и Catalog DB не принимают бизнес-переходы Run. Подробнее: [исполнение](../execution.md). + +- [Assignment и AttemptContext](runner-assignment.schema.json): контекст попытки отдельно от неизменяемого spec. +- [ResultManifest](result-manifest.schema.json): результат и проверяемые артефакты. +- [Provider API](../api/provider-api.md): канонический ConnectionSummary; secretBindingRef остаётся серверным полем. + +inputSchemaRef и outputSchemaRef обязательны для template. Все schemaRef — пути внутри проверенного архива версии; произвольные сетевые $ref запрещены. DSH-плагин указывает dshCompatibility; статус совместимости выставляется каталогом по отдельному отчёту, а не самим автором. diff --git a/designDocument/contracts/examples/input.schema.json b/designDocument/contracts/examples/input.schema.json new file mode 100644 index 0000000..c673810 --- /dev/null +++ b/designDocument/contracts/examples/input.schema.json @@ -0,0 +1,15 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Company input", + "type": "object", + "additionalProperties": false, + "required": [ + "company" + ], + "properties": { + "company": { + "type": "string", + "minLength": 1 + } + } +} diff --git a/designDocument/contracts/examples/output.schema.json b/designDocument/contracts/examples/output.schema.json new file mode 100644 index 0000000..5633c48 --- /dev/null +++ b/designDocument/contracts/examples/output.schema.json @@ -0,0 +1,15 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Research output", + "type": "object", + "additionalProperties": false, + "required": [ + "summary" + ], + "properties": { + "summary": { + "type": "string", + "minLength": 1 + } + } +} diff --git a/designDocument/contracts/examples/template-manifest.json b/designDocument/contracts/examples/template-manifest.json index 51f3613..1ead660 100644 --- a/designDocument/contracts/examples/template-manifest.json +++ b/designDocument/contracts/examples/template-manifest.json @@ -23,5 +23,7 @@ "cancel-v1" ], "requiredPermissions": [], - "retrySafe": false + "retrySafe": false, + "inputSchemaRef": "input.schema.json", + "outputSchemaRef": "output.schema.json" } diff --git a/designDocument/contracts/execution-spec.schema.json b/designDocument/contracts/execution-spec.schema.json index 060b147..a44d3cd 100644 --- a/designDocument/contracts/execution-spec.schema.json +++ b/designDocument/contracts/execution-spec.schema.json @@ -132,12 +132,6 @@ "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 index f797c8b..5325c41 100644 --- a/designDocument/contracts/package-manifest.schema.json +++ b/designDocument/contracts/package-manifest.schema.json @@ -134,6 +134,45 @@ }, "retrySafe": { "type": "boolean" + }, + "inputSchemaRef": { + "type": "string", + "minLength": 1 + }, + "outputSchemaRef": { + "type": "string", + "minLength": 1 + }, + "dshCompatibility": { + "type": "object", + "additionalProperties": false, + "required": [ + "dshVersionRange", + "nodeVersionRange", + "entryModule", + "profile" + ], + "properties": { + "dshVersionRange": { + "type": "string", + "minLength": 1 + }, + "nodeVersionRange": { + "type": "string", + "minLength": 1 + }, + "entryModule": { + "type": "string", + "minLength": 1 + }, + "profile": { + "enum": [ + "headless", + "web", + "both" + ] + } + } } }, "allOf": [ @@ -148,7 +187,9 @@ "then": { "required": [ "harnessVersionId", - "configSchemaRef" + "configSchemaRef", + "inputSchemaRef", + "outputSchemaRef" ] } }, diff --git a/designDocument/contracts/result-manifest.schema.json b/designDocument/contracts/result-manifest.schema.json new file mode 100644 index 0000000..8c50e49 --- /dev/null +++ b/designDocument/contracts/result-manifest.schema.json @@ -0,0 +1,44 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "ResultManifest v1", + "type": "object", + "additionalProperties": false, + "required": [ + "output", + "artifacts" + ], + "properties": { + "output": {}, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "artifactId", + "digest", + "sizeBytes", + "mediaType" + ], + "properties": { + "artifactId": { + "type": "string", + "minLength": 1 + }, + "digest": { + "type": "string", + "pattern": "^sha256:[a-f0-9]{64}$" + }, + "sizeBytes": { + "type": "integer", + "minimum": 0 + }, + "mediaType": { + "type": "string", + "minLength": 1 + } + } + } + } + } +} diff --git a/designDocument/contracts/run-event.schema.json b/designDocument/contracts/run-event.schema.json index dbe7b6b..7beb099 100644 --- a/designDocument/contracts/run-event.schema.json +++ b/designDocument/contracts/run-event.schema.json @@ -42,5 +42,156 @@ "payload": { "type": "object" } - } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "const": "progress" + } + } + }, + "then": { + "properties": { + "payload": { + "type": "object", + "additionalProperties": false, + "required": [ + "message" + ], + "properties": { + "message": { + "type": "string", + "minLength": 1 + }, + "fraction": { + "type": "number", + "minimum": 0, + "maximum": 1 + } + } + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "log" + } + } + }, + "then": { + "properties": { + "payload": { + "type": "object", + "additionalProperties": false, + "required": [ + "level", + "message" + ], + "properties": { + "level": { + "enum": [ + "debug", + "info", + "warn", + "error" + ] + }, + "message": { + "type": "string", + "minLength": 1 + } + } + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "artifact_ready" + } + } + }, + "then": { + "properties": { + "payload": { + "type": "object", + "additionalProperties": false, + "required": [ + "artifactId" + ], + "properties": { + "artifactId": { + "type": "string", + "minLength": 1 + } + } + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "input_requested" + } + } + }, + "then": { + "properties": { + "payload": { + "type": "object", + "additionalProperties": false, + "required": [ + "inputRequestId" + ], + "properties": { + "inputRequestId": { + "type": "string", + "minLength": 1 + } + } + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "diagnostic" + } + } + }, + "then": { + "properties": { + "payload": { + "type": "object", + "additionalProperties": false, + "required": [ + "code", + "message" + ], + "properties": { + "code": { + "type": "string", + "minLength": 1 + }, + "message": { + "type": "string", + "minLength": 1 + } + } + } + } + } + } + ] } diff --git a/designDocument/contracts/runner-assignment.schema.json b/designDocument/contracts/runner-assignment.schema.json new file mode 100644 index 0000000..7ce16b7 --- /dev/null +++ b/designDocument/contracts/runner-assignment.schema.json @@ -0,0 +1,83 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Runner Assignment v1", + "type": "object", + "additionalProperties": false, + "required": [ + "attemptId", + "runId", + "leaseEpoch", + "leaseUntil", + "executionSpec", + "attemptContext", + "executionToken", + "tokenExpiresAt" + ], + "properties": { + "attemptId": { + "type": "string", + "minLength": 1 + }, + "runId": { + "type": "string", + "minLength": 1 + }, + "leaseEpoch": { + "type": "integer", + "minimum": 1 + }, + "leaseUntil": { + "type": "string", + "format": "date-time" + }, + "executionSpec": { + "$ref": "execution-spec.schema.json" + }, + "attemptContext": { + "type": "object", + "additionalProperties": false, + "required": [ + "deadlineAt" + ], + "properties": { + "deadlineAt": { + "type": "string", + "format": "date-time" + }, + "continuation": { + "type": "object", + "additionalProperties": false, + "required": [ + "checkpointRef", + "inputRequestId", + "responseId", + "resumeInput" + ], + "properties": { + "checkpointRef": { + "type": "string", + "minLength": 1 + }, + "inputRequestId": { + "type": "string", + "minLength": 1 + }, + "responseId": { + "type": "string", + "minLength": 1 + }, + "resumeInput": {} + } + } + } + }, + "executionToken": { + "type": "string", + "minLength": 1 + }, + "tokenExpiresAt": { + "type": "string", + "format": "date-time" + } + } +} diff --git a/designDocument/design.md b/designDocument/design.md index 696c931..43b12c9 100644 --- a/designDocument/design.md +++ b/designDocument/design.md @@ -5,6 +5,9 @@ | Термин | Значение | |---|---| | Harness | Движок и обвязка агента: цикл выполнения, управление контекстом, состоянием и вызовами инструментов | +| DSH | DeepSeek Harness — исходная база стандартного agent runtime Invest Harness | +| Connection | Подключение к провайдеру: способ входа, права, место хранения credentials и их состояние | +| AttemptContext | Deadline и данные продолжения конкретной попытки, отдельно от ExecutionSpec | | Runtime | Среда выполнения программы: например, Node.js или Python; определяется пакетом harness’а | | Plugin | Программное расширение, добавляющее инструменты, интеграции или возможности | | Skill | Инструкции и вспомогательные материалы для конкретной задачи; может содержать скрипты, но сам по себе не предоставляет доступы | @@ -22,7 +25,7 @@ ## Концепция и статус -Invest Harness — платформа агентов для инвестиций. Автор публикует шаблон и его зависимости, пользователь выбирает шаблон, настраивает его через автоматически построенную форму и запускает локально или удалённо. Оба режима используют один формат пакетов и ExecutionSpec. +Invest Harness — платформа агентов для инвестиций. Автор публикует шаблон и его зависимости, пользователь выбирает шаблон, настраивает его через автоматически построенную форму и запускает локально или удалённо. Оба режима используют один формат пакетов и ExecutionSpec. Стандартный агент строится на DSH с собственным интерфейсом и исправленным разделением ядра, конфигурации, credentials и исполнения. Плагины сохраняют совместимость с публичным API DSH в проверенном профиле; другие harness также допускаются. Документ задаёт целевую архитектуру и контракты первой версии. Реализация сервисов пока не входит в этот репозиторий. Выбранные технологии — проектные решения; численные показатели масштабирования — гипотезы до измерений. @@ -69,13 +72,13 @@ flowchart TB 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 / роли, агенты, запуски, аудит")] + DB[("Platform DB / PostgreSQL / роли, агенты, Run, Attempt, расписания, аудит")] C["Каталог / Container / Go, REST"] CD[("Catalog DB / PostgreSQL / пакеты и версии")] PS[("Package Storage / S3 / архивы плагинов, скиллов, шаблонов")] D["Диспетчер / Container / Go"] E["Сервис исполнения / Container / Go / workflow, jobs, адаптер"] - ED[("Execution DB / PostgreSQL / назначения и статусы движка")] + ED[("Execution DB / PostgreSQL / executionId mapping и технические статусы")] R["Registry API / Component of execution service / Go, OCI"] RS[("Registry Storage / S3 / манифесты и слои образов")] ES[("Execution Storage / S3 / логи и технические артефакты")] @@ -116,7 +119,7 @@ flowchart TB T --> S T --> M B --> F - D --> S + B --> S B -.-> O C -.-> O E -.-> O @@ -195,6 +198,9 @@ flowchart TB | Система | Стек | Как создаётся | |---|---|---| +| DSH adapter / plugin host | TypeScript, Node.js, DSH / Cordis | Переработанные границы ядра; публичный plugin API сохраняется | +| Standalone app | TypeScript, React; Electron / Capacitor | Общие формы, desktop sidecar; mobile управляет Runner | +| Provider broker | Go API + изолированные TypeScript provider plugins | Вход, хранение bindings, обновление и отзыв credentials | | Web UI | TypeScript, React, JSON Forms | Новый интерфейс | | Platform API и identity | Go, REST, OpenAPI, сессии, OIDC | Продуктовый API с адаптацией существующих механизмов аккаунтов | | Каталог | Go, PostgreSQL, S3 API | Новый отдельный сервис | @@ -329,6 +335,9 @@ stateDiagram-v2 preparing --> running: окружение готово running --> waiting_input: checkpoint и запрос ввода waiting_input --> queued: подтверждённое продолжение + waiting_input --> failed: INPUT_EXPIRED или deadline + preparing --> failed: deadline и остановка подтверждена + running --> failed: deadline и остановка подтверждена running --> succeeded: результат принят preparing --> failed: ошибка подготовки running --> failed: ошибка @@ -389,10 +398,91 @@ flowchart LR MVP: четыре типа пакетов; immutable versions; конфигурация через формы; экземпляры агентов; ручной и регулярный запуск; стандартный и локальный Runner; документированный протокол своей реализации; отмена, события и результаты; tenant isolation; registry и buckets; аудит. -Следующий этап: возобновление через checkpoint, пользовательский ввод, автоматическая миграция конфигураций, Kubernetes Runner, автоматическое масштабирование и коммерческий биллинг. Протокол заранее резервирует эти возможности, но UI не предлагает их без подтверждённой capability. +Полный MVP достигается поэтапно (P0–P5 ниже), а не одним релизом. Следующий этап: возобновление через checkpoint, пользовательский ввод, автоматическая миграция конфигураций, Kubernetes Runner, автоматическое масштабирование и коммерческий биллинг. Протокол заранее резервирует эти возможности, но UI не предлагает их без подтверждённой capability. Открытые решения: провайдер KMS и S3, конкретные версии зависимостей, политика модерации публичных пакетов, целевые SLO после нагрузочных измерений, перечень лицензий распространяемых runtime и пакетов. Публичный доступ к этому проекту сам по себе не задаёт лицензию его дальнейшего использования. +## DSH: интерфейс и внутренняя архитектура + +Свой UI показывает шаблоны, настройки, подключения, расписания и результаты. Внутри DSH сохраняются публичные точки подключения плагинов; platform adapter изолирует конфигурацию, credentials, запуск и состояния сессий. Runner остаётся заменяемым, а внутренний agent loop — чёрным ящиком для диспетчера. + +```mermaid +flowchart LR + UI["UI / React + JSON Forms"] --> API["Platform API / Go"] + API --> SPEC["Immutable ExecutionSpec + AttemptContext"] + SPEC --> RUN["Runner / Go adapter или своя реализация"] + subgraph JOB["Job / изолированное окружение"] + AD["Invest Harness adapter / TypeScript"] + CORE["DSH core / Node.js, Cordis"] + PL["DSH-compatible plugins / TypeScript"] + SK["Skills / инструкции и ресурсы"] + AD --> CORE + CORE --> PL + CORE --> SK + end + RUN --> AD + PL --> BROKER["Provider broker / изолированный plugin host"] + BROKER --> STORE["KMS vault или локальное secret storage"] + BROKER --> EXT["LLM / официальный клиент / API"] +``` + +Совместимость подтверждается для конкретных версий DSH, runtime и плагина. Непроверенные пакеты не получают отметку совместимости; зависимость от платформенного API объявляется явно. Детали и исходные источники: [DSH foundation](dsh-foundation.md). + +## Плагины и авторизация провайдеров + +Первая линейка: provider-claude, provider-codex, provider-xai, provider-generic, recurring-tasks и package-discovery. Provider plugins поддерживают API keys и отдельно разрешённые способы входа в аккаунт. Наличие подписки само по себе не делает её доступной стороннему приложению; неподтверждённые режимы не включаются. Плагин расписаний обращается к единому Scheduler, а discovery ищет пакеты и показывает зависимости/разрешения до установки. + +```mermaid +sequenceDiagram + participant U as Пользователь + participant UI as Web / Desktop / Mobile + participant B as Provider broker / сервер или sidecar + participant P as Провайдер / официальный клиент + participant S as Разрешённое secret storage + U->>UI: Выбрать провайдера и способ входа + UI->>B: Создать AuthFlow + B->>B: Проверить deployment mode и права + B-->>UI: URL / device code / official client action + U->>P: Подтвердить вход + P-->>B: Результат поддержанного auth flow + B->>S: Сохранить credentials или локальный binding + B-->>UI: ConnectionSummary без секретов +``` + +Для official_client авторизация завершается внутри неизменённого клиента; broker получает только статус/binding, не извлекает его tokens. Для API key используется отдельная защищённая передача. Полная матрица и правила: [плагины](plugins.md), [Provider API](api/provider-api.md), [API edge cases](provider-edge-cases.md). + +## Режимы приложения и развёртывания + +```mermaid +flowchart TB + WEB["Web / PWA / React"] --> CLOUD["Облачный control plane / Go, PostgreSQL, S3"] + MOBILE["Mobile / Capacitor + React"] --> CLOUD + MOBILE --> ONPREM["On-prem control plane / тот же стек"] + DESKTOP["Desktop / Electron + React"] --> SIDE["Локальный sidecar / Go"] + DESKTOP --> CLOUD + SIDE --> LOCAL["Local Runner / DSH Node.js или OCI"] + CLOUD --> MANAGED["Managed Runner"] + CLOUD --> OWN["Свой Runner"] + ONPREM --> PRIVATE["Runner внутри инфраструктуры клиента"] +``` + +Desktop выполняет локально через sidecar; mobile/PWA управляют Runner. On-prem означает размещение всей платформы у клиента; свой Runner при облачном API — отдельный режим. Local CLI остаётся самостоятельным способом запуска без обязательной облачной учётки. + +## Roadmap и готовность + +| Этап | Результат | +|---|---| +| P0 | DSH spike, фиксация версий, plugin compatibility и контракты | +| P1 | JSON Schema Driven компоненты и редактор конфигураций | +| P2 | Реестры harness/plugin/skill/template и discovery | +| P3 | Локальный и on-premise запуск | +| P4 | Managed и собственные Runner, регулярные задачи | +| P5 | Provider plugins и допущенные account modes | +| P6 | Standalone JS: desktop, mobile, PWA | +| P7 | Расширение API edge cases, нагрузка и эксплуатация | + +Проверки ошибок и изоляции входят в каждый этап, а не откладываются до P7. [Roadmap с критериями выхода](roadmap.md). Начинать можно с P0–P2; [результат проверки дизайна](review.md) разделяет принятые решения и оставшиеся проверки реализации. + ## Подробные спецификации - [Каталог и версии](catalog.md) @@ -406,3 +496,10 @@ MVP: четыре типа пакетов; immutable versions; конфигур - [API запусков](api/runs-api.md) - [Runner Protocol](api/executor-api.md) - [Модель данных и JSON Schema](contracts/domain-model.md) + +- [База DSH](dsh-foundation.md) +- [Плагины](plugins.md) +- [Provider API](api/provider-api.md) +- [API edge cases](provider-edge-cases.md) +- [Roadmap](roadmap.md) +- [Проверка готовности](review.md) diff --git a/designDocument/dsh-foundation.md b/designDocument/dsh-foundation.md new file mode 100644 index 0000000..84f750f --- /dev/null +++ b/designDocument/dsh-foundation.md @@ -0,0 +1,39 @@ +# DSH как базовый harness + +## Решение + +Invest Harness использует DeepSeek Harness (DSH) как базовый движок агентов. Изменяем интерфейс и внутренние границы, сохраняя публичные контракты плагинов. Это целевой дизайн нашей сборки, а не утверждение, что все необходимые возможности уже реализованы в upstream. + +Исходный ориентир spike — @deepseek-ai/dsh 0.2.2-rc.1, указанный в проверенном манифесте на 11.11.2026. Перед первым runtime-релизом фиксируются исходный commit, версии всех DSH-пакетов, lock зависимостей и digest сборки. Плавающий master не используется в опубликованных harness’ах. Сама версия пакета без проверки целостности недостаточна. + +## Исправления интерфейса + +Собственный JS-интерфейс строится вокруг пользователя: каталог → шаблон → настройки → подключения → запуск → результаты. Пользователь не редактирует внутреннюю конфигурацию движка. JSON Schema Driven UI обслуживает настройки harness, plugins и template с одинаковыми сообщениями об ошибках. Экран подключения явно различает API key, вход через аккаунт и локальный официальный клиент. История показывает состояние запуска и попыток, запросы ввода и источник расхода. + +## Исправления архитектуры + +| Граница | Решение Invest Harness | Критерий | +|---|---|---| +| Ядро и интерфейс | DSH session/agent/tools через runtime adapter; UI работает по продуктовым API | Замена UI не меняет ExecutionSpec | +| Конфигурация | Валидируемый config → детерминированная композиция DSH | Один lock даёт одинаковый состав пакетов | +| Credentials | Provider broker и хранилище отдельно от config | Секреты отсутствуют в snapshot и событиях | +| Планирование | DSH plugin обращается к сервису расписаний | Нет второго cloud cron внутри каждого job | +| Исполнение | Runner adapter отделён от agent loop | Один и тот же harness запускается локально и удалённо | +| Контекст | Отдельный workspace и DSH state directory для каждого Agent/Run с явной политикой сохранения | Нет смешения tenant-сессий | +| Обновления | Собственная версия сборки + upstream baseline + compatibility report | Плагин не ломается после незаметного обновления | + +В DSH уже есть профили запуска и отдельный headless-режим. Платформенный адаптер нормализует поток событий и результат; он не считает произвольный stderr машинным протоколом. Продолжение сохранённой DSH-сессии требует исходных state files и совместимого workspace; оно не равно переносимому checkpoint без проверенного адаптера. + +## Совместимость с DSH + +Плагины реализуют публичные DSH/Cordis interfaces, объявляют peer dependencies и требования к сервисам. Каталог добавляет envelope публикации, не заменяя формат самого DSH-пакета. Наши стандартные плагины должны загружаться в проверенном upstream DSH с теми же public interfaces; платформенные операции требуют настроенного endpoint Invest Harness. При отсутствии endpoint плагин сообщает capability unavailable, не ломая запуск DSH. + +Входящая совместимость не означает запуск любого стороннего плагина. Матрица фиксирует DSH version, plugin version, Node version, OS/architecture, permissions и surfaces: headless/web/local. Проверки: load/dispose, регистрация tools, config validation, streaming, cancellation, credential refresh, отсутствие зависимостей от private APIs. Плагин, требующий внутренний UI DSH, получает ui-specific статус и адаптер; он не объявляется автоматически совместимым с новым UI. + +Несовместимая смена API меняет compatibility profile; resolver отказывает до запуска. Lifecycle адаптации и возможности безопасности остаются частью сборки, а не требуют silent monkey patch каждого плагина. + +## Основа и ограничения лицензирования + +DSH опубликован под MIT; сохраняем copyright и license notices в сборках. Состав сторонних пакетов проверяется для каждого распространяемого образа. Это не определяет лицензию всего Invest Harness и не заменяет условия моделей и провайдеров. + +Источники: [CLI manifest](https://raw.githubusercontent.com/deepseek-ai/deepseek-harness/master/apps/cli/package.json), [Headless](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/headless/README.md), [Authorization service](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/credentials/authorization/README.md), [MIT](https://github.com/deepseek-ai/deepseek-harness/blob/master/LICENSE). diff --git a/designDocument/execution.md b/designDocument/execution.md index 7a9ba44..7cb08c2 100644 --- a/designDocument/execution.md +++ b/designDocument/execution.md @@ -6,15 +6,15 @@ Harness получает ExecutionSpec и разрешённые ресурсы. ## Планирование -API в одной транзакции записывает Run, reservation квоты и outbox. Диспетчер обрабатывает outbox идемпотентно по runId. Resolve выполняется до создания снимка; назначение повторно проверяет block policy и права. Попытка захватывается атомарно с leaseEpoch. Стандартный execution adapter использует runId/attemptId как ключ дедупликации, хранит соответствие с executionId движка и сверяет состояние при неоднозначном ответе. +API в одной транзакции записывает Run, reservation бюджета/места в очереди и outbox. Слот активного исполнения резервируется только при claim. Диспетчер обрабатывает 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. Ручной запуск имеет отдельный ключ. +Расписания закрепляют agentRevisionId, IANA timezone, cron expression, nextRunAt и overlapPolicy: skip или queue. Политика misfire: skip либо coalesce (по умолчанию), создающая не более одного запуска за простой. Queue удерживает максимум одно ожидающее срабатывание; следующие объединяются с ним. Уникальный ключ 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 и тем же снимком, но с актуальной проверкой прав. +Потеря lease переводит Run в interrupted. Автоповтор разрешён, только если template объявил retrySafe и policy организации позволяет; иначе нужен явный retry пользователя после предупреждения о возможном повторе внешних действий. Checkpoint continuation создаёт новый Attempt того же Run. Retry terminal Run создаёт новый Run с parentRunId и копией настроек и зависимостей, новым runId и specDigest и актуальной проверкой прав. Fencing защищает записи платформы, но не останавливает старый процесс на недоступной машине и не обеспечивает exactly-once сторонних API. Повторные внешние действия должен защищать сам harness или поддерживающий idempotency key шлюз. @@ -30,6 +30,14 @@ Waiting_input поддерживается только с capability checkpoint ## Артефакты -Runner запрашивает upload grant для конкретного Attempt и назначения файла. Grant ограничен размером, сроком и префиксом. ResultManifest содержит artifactId, digest, size и mediaType, без произвольных URL. Сервис проверяет существование объектов до terminal success. Логи доставляются отдельно и не являются единственным источником состояния. +Runner запрашивает upload grant для конкретного Attempt и назначения файла. Grant ограничен размером, сроком и префиксом. ResultManifest содержит artifactId, digest, sizeBytes и mediaType, без произвольных URL. Сервис проверяет существование объектов до terminal success. Логи доставляются отдельно и не являются единственным источником состояния. [Runner Protocol](api/executor-api.md) · [Состояния и диаграммы](design.md). + +## Владение состоянием и продолжение + +Run, Attempt, Schedule, reservations и их outbox находятся в Platform DB. API и диспетчер используют общий модуль переходов состояния и транзакций. Execution DB хранит только техническое соответствие attemptId → executionId и состояние движка, а не второй источник истины Run. Финализация Attempt, Run, освобождение активного слота и outbox атомарны в Platform DB; события движка проходят тот же путь. + +ExecutionSpec неизменяем на протяжении Run. Checkpoint и ответ пользователя передаются отдельно в AttemptContext внутри Assignment. Deadline фиксируется при первом назначении: timeoutSeconds ограничивает время Run с первого назначения, включая ожидание ввода и последующие очереди; продолжение не обнуляет deadline. Подтверждённая остановка по deadline завершает Run как failed с DEADLINE_EXCEEDED; неподтверждённая — interrupted без автоматического повтора. Истечение inputRequest.expiresAt завершает waiting_input как failed с INPUT_EXPIRED. Ошибка подготовки без внешних эффектов допускает bounded retry внутри preparing до maxAttempts; после исчерпания — failed. + +После принятой отмены автоматический retry запрещён даже при interrupted. Reconciler проверяет deadline, протухшие lease и outbox; изменение статуса выполняется условно по текущему состоянию и epoch. diff --git a/designDocument/plugins.md b/designDocument/plugins.md new file mode 100644 index 0000000..451795a --- /dev/null +++ b/designDocument/plugins.md @@ -0,0 +1,49 @@ +# Плагины Invest Harness + +Плагины совместимы с публичным DSH plugin API в проверенной матрице версий. Harness — движок, template — состав агента, skill — инструкции, plugin — исполняемое расширение. Подключение аккаунта провайдера не является входом в Invest Harness. + +## Первая линейка + +| Плагин | Назначение | Результат | +|---|---|---| +| provider-claude | Claude API и поддерживаемая работа с аккаунтом через официальный клиент | ConnectionSummary, model capability profile | +| provider-codex | OpenAI API и согласованные account-based способы через Codex/Sign in with ChatGPT | ConnectionSummary с mode и execution placement | +| provider-xai | xAI API и исследуемый account flow официального клиента | Доступные способы входа, проверенные capabilities | +| provider-generic | Другие провайдеры через отдельные адаптеры; OpenAI-compatible не означает полную эквивалентность | Нормализованный адаптер моделей | +| recurring-tasks | Планирование регулярных задач из агента и формы | Сохранённое Schedule, preview ближайших запусков | +| package-discovery | Поиск плагинов, harness’ов, скиллов и шаблонов | Доступные пакеты, совместимость, preview установки | + +Это план разработки, а не список уже установленных расширений. Account-based режим включается отдельно для каждой комбинации provider, deploymentMode, integrationPath. Если путь недоступен, UI показывает причину и API-вариант без скрытого переключения способа оплаты. + +## Авторизация провайдеров + +Методы провайдера перечисляет adapter discovery; браузер не получает client secret или refresh token. OAuth flow хранит state, PKCE, nonce где применимо, redirect allowlist, срок и tenant/actor binding. Device flow соблюдает polling interval и slow_down. Отмена и expiry завершают flow. Refresh выполняется single-flight на connectionId с атомарной заменой refresh token. invalid_grant переводит Connection в reauth_required; повторные login попытки не создаются автоматически. + +Credential placement: local_keychain, runner_private_store или server_vault. Переход между ними требует нового разрешённого связывания; локальная подписка не переносится на hosted Runner неявно. Для official-client-mode provider broker хранит статус и binding, а не извлекает закрытые токены клиента. + +| Провайдер | Подтверждённая основа | Решение для Invest Harness | +|---|---|---| +| Claude | Официальные условия различают API и подписку, запрещают стороннему приложению собирать Claude.ai session tokens; допускают собственный вход пользователя в неизменённый официальный клиент | API — базовый путь. Account plugin интегрирует официальный клиент в отдельном окружении после проверки условий; не подменяет его DSH OAuth-прокси | +| Codex / OpenAI | Официально описаны app-server и отдельный Sign in with ChatGPT для планового использования | Локальный/open-source app-server путь проверяется отдельно. Коммерческий hosted режим использует одобренную интеграцию Sign in with ChatGPT либо API; старый app-server login не считается разрешением на hosted сервис | +| xAI | Официальный Grok Build описывает browser/device login и API key | Наличие login у клиента не доказывает доступность произвольного DSH subscription adapter. Remote account mode gated до проверки; API доступен как отдельный режим | +| Другие | Условия и протокол определяет провайдер | Новый адаптер проходит ту же матрицу auth, scopes, quotas, refresh и deployment modes | + +Источники, проверенные 11.11.2026: [Claude authentication and credential use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use), [Codex app-server auth](https://learn.chatgpt.com/docs/app-server), [Sign in with ChatGPT integration](https://developers.openai.com/siwc/token-sharing-open-source/codex-app-server), [Grok Build authentication](https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/02-authentication.md). + +## Регулярные задачи + +Плагин предоставляет preview_schedule, create_schedule, list_schedules, update_schedule, pause_schedule. Перед записью отображает timezone, следующие 5 occurrences, overlap и catch-up policy, ревизию агента и бюджет. Действия выполняются с actor-scoped разрешением schedules:write, не полномочиями администратора. + +В cloud/on-prem единственный владелец времени — диспетчер. Локально тот же модуль расчёта работает в Local Scheduler с локальной БД; закрытое приложение не обещает фоновые запуски без установленного daemon. Расписание принадлежит одному placement. Перенос требует pause старого, handover cursor и activation нового; просто копировать active Schedule нельзя. В MVP blackout/exchange calendars не гарантируются; инвестиционный календарь добавляется отдельным адаптером позже. + +## Поиск и установка + +Tools search_packages, inspect_package, resolve_dependencies, preview_install возвращают только доступные пользователю версии. Выдача включает kind, owner, digest, runtime compatibility, permissions и review status. MVP использует PostgreSQL full-text/trigram поиск, не отдельную поисковую инфраструктуру. + +Описание найденного пакета — данные, не инструкция агенту. Поиск не запускает код. Установка создаёт новую AgentRevision после подтверждения изменения permissions; работающий Run не меняется. Результат resolve ещё раз проверяется при записи ревизии и назначении Runner. + +## Контракт адаптера провайдера + +Adapter interface version 1: listAuthMethods, startAuth, pollAuth, cancelAuth, getConnectionStatus, disconnect, listModels, invoke, cancelInvocation. Инференс нормализует текст, tool calls, structured output и usage, сохраняя provider-specific metadata в ограниченном namespace. Capabilities определяют поддержку tools, stream, JSON Schema, images, cancellation и resume. Provider passwords не входят в этот интерфейс. + +Подробные ручки: [provider-api.md](api/provider-api.md). Граничные случаи: [provider-edge-cases.md](provider-edge-cases.md). diff --git a/designDocument/provider-edge-cases.md b/designDocument/provider-edge-cases.md new file mode 100644 index 0000000..a53009e --- /dev/null +++ b/designDocument/provider-edge-cases.md @@ -0,0 +1,25 @@ +# Граничные случаи провайдеров + +Эта матрица — обязательные проверки adapter conformance, а не утверждение, что все API одинаковы. + +| Случай | Поведение платформы / адаптера | Проверка | +|---|---|---| +| 401 и истечение токена | Один refresh, затем reauth_required; без бесконечного replay | Два параллельных вызова не теряют новый refresh token | +| 403 / отсутствие модели в плане | AUTH_SCOPE_DENIED или MODEL_UNAVAILABLE | Каталог моделей не считается entitlement | +| 429 / Retry-After | Ограниченный backoff + jitter в пределах дедлайна | Не больше maxAttempts, отмена прерывает backoff | +| 5xx до принятия запроса | Повтор только безопасной операции | Сохранение invocationId и provider request id | +| Сеть оборвалась после отправки | outcome_unknown; не повторять автоматически tool side effects | Нет двойной сделки/письма при неопределённом ответе | +| Обрыв SSE/WebSocket | Сохранить partial output; resume только при поддержке провайдера | Partial output не становится final result | +| Разные tool-call форматы | Адаптер нормализует id/name/arguments; schema validation до выполнения | Фрагменты JSON и несколько параллельных tools | +| Structured output не поддержан | Явный capability mismatch либо согласованный validate/repair режим | Нет обещания строгой схемы при text-only API | +| Превышение контекста | CONTEXT_LIMIT; адаптация только по policy template | Не теряются обязательные инструкции и источники | +| Usage отсутствует | usageStatus=unknown, не 0 | Биллинг не принимает неизвестный расход за бесплатный | +| Разные модели или цены | Только явная fallbackPolicy | Не меняются провайдер/аккаунт/платёжный режим молча | +| Отмена запроса | Локальный abort + доступный remote cancel | Отмена не обещает отсутствия списания | +| OAuth callback повторён | Одноразовый code/state; replay отвергается | Binding tenant + actor + placement | +| Device flow pending / slow_down | Соблюдать interval, expiry и cancel | Нет polling storm | +| Пользовательский base URL | Allowlist или egress policy; запрет metadata/private ranges по умолчанию | Redirect не обходит SSRF-проверку | +| Mobile background / sleep | Клиент переподключается по cursor, job живёт на Runner | Закрытие экрана не считается отменой Run | +| API dialect version drift | Закреплённая adapter version, capability probe и контрактные fixtures | Несовместимость отключает конкретный mode | + +Каждый новый provider mode сначала проходит fake-provider fixtures без реальных списаний, затем минимальный opt-in live smoke с бюджетом. Артефакты проверки содержат redacted status, timings, capabilities, версии и date; не токены и не полные prompts. Provider mode включается независимо по local/on_prem/managed_remote. diff --git a/designDocument/review.md b/designDocument/review.md new file mode 100644 index 0000000..385db6a --- /dev/null +++ b/designDocument/review.md @@ -0,0 +1,40 @@ +# Проверка дизайна перед реализацией + +Проверено 11.11.2026. Это проверка согласованности спецификации, не подтверждение работоспособности ещё не созданной платформы. Можно начинать P0–P2; поддержка DSH и account modes требует проверок из roadmap. + +## Исправленные противоречия и пробелы + +| Проблема | Принятое решение | +|---|---| +| Неясно, что меняем в DSH | Собственный UI и внутренние границы; public plugin API сохраняем в проверенном профиле — [DSH](dsh-foundation.md) | +| Совместимость обещана без версии/проверки | Manifest metadata + отдельный compatibility report; gate публикации — [каталог](catalog.md) | +| Подписка приравнивалась к универсальному API-доступу | Отдельная матрица provider/auth/deployment; gated modes — [плагины](plugins.md) | +| Resume менял неизменяемый ExecutionSpec | Checkpoint и ответ вынесены в AttemptContext; retry нового Run меняет runId/specDigest — [исполнение](execution.md) | +| Run и Attempt могли иметь два источника истины | Общая транзакционная область Platform DB; engine mapping в Execution DB — [модель](contracts/domain-model.md) | +| Потерянный ответ claim мог занять второй слот | claimRequestId, восстановление assignments и fencing — [Runner API](api/executor-api.md) | +| Длинная задача переживала срок execution token | Heartbeat обновляет токен до общего deadline; терминальный replay отдельно от новых записей — [Runner API](api/executor-api.md) | +| ResultManifest и input/output отсутствовали в схемах | Добавлены схемы результата, Assignment, input/output refs и примеры — [контракты](contracts/domain-model.md) | +| Расписание не определяло ревизию, DST и переполнение | Pinned revision, preview/pause, skip/queue, bounded coalesce — [API](api/runs-api.md) | +| Timeout, ожидание ввода и отмена имели неоднозначные исходы | Deadline общий для Run; подтверждение остановки отличает failed/cancelled от interrupted — [исполнение](execution.md) | +| Mobile подразумевал полный локальный runtime | JS-клиент управляет Runner; desktop имеет sidecar — [roadmap](roadmap.md) | +| Схема формы смешивалась со схемами протокола | Ограниченный UI profile отдельно от служебного JSON Schema — [UI](configuration-ui.md) | + +## Gate перед выпуском соответствующей функции + +| Проверка | Когда обязательна | Что фиксируем | +|---|---|---| +| DSH baseline | P0, до публикации runtime | Exact commit, lock, image digest, load/run/cancel/dispose и plugin compatibility report | +| Provider account integration | P5, до включения конкретного mode | Регистрация/допуск интеграции, способ входа, размещение credentials, ограничения подписки, conformance | +| Runtime и SDK контракты | P0–P1 | OpenAPI, generated types, одинаковые fixtures JS/Go, межресурсные инварианты | +| KMS/S3 и секреты | P3, до real credentials | Выбранные реализации, ротация, backup/restore, изоляция tenant | +| Недоверенные публичные плагины | P2 до открытия исполнения публичного кода | Политика модерации, sandbox/trust profile и процедура отзыва версии | +| Собственный Runner | P4 до допуска пула | Protocol conformance плюс явное подтверждение владельцем trust policy | +| Нагрузка и восстановление | P7 до эксплуатационных обещаний | Нагрузочный профиль, реальные SLO, restore rehearsal | + +Выбор лицензии Invest Harness остаётся решением владельца проекта; публичный репозиторий не заменяет разрешение на распространение. Версии библиотек и deploy images закрепляются в реализации, а не остаются плавающими ссылками из документа. + +## Первый вертикальный срез + +Автор публикует DSH harness, один совместимый plugin и template с config/input/output schemas. Пользователь создаёт ревизию через форму, связывает тестовый provider и запускает тот же состав локально и на одном Runner. Сохраняются события и валидный результат. Повтор POST Run и claim не создаёт дубликаты; чужой tenant не читает результат; cancel останавливает процесс; потеря lease запрещает позднюю запись; credentials отсутствуют в snapshot и логах. + +Машиночитаемые схемы здесь задают основу протокола, но не полный SDK. До реализации endpoint его request/response и ошибки переносятся в OpenAPI и проверяются контрактными fixtures. Проверки JSON Schema не доказывают корректность OAuth, sandbox или финансовых действий внутри harness. diff --git a/designDocument/roadmap.md b/designDocument/roadmap.md new file mode 100644 index 0000000..0542b3b --- /dev/null +++ b/designDocument/roadmap.md @@ -0,0 +1,26 @@ +# Roadmap Invest Harness + +Этапы выражают зависимости и критерии готовности, не календарные обещания. Названия компонентов и схемы всей системы находятся в [основной диздоке](design.md). + +| Этап | Результат | Критерий выхода | +|---|---|---| +| P0 Контракты и DSH spike | Зафиксированная сборка DSH; adapter harness; Runner Protocol; исправленные границы UI, config, credentials и agent loop | Load/run/cancel/dispose одного DSH-плагина; один и тот же ExecutionSpec локально и в тестовом Runner; pinned commit, digest и compatibility report | +| P1 JSON Schema Driven компоненты | Общие формы config, connections selectors, validation errors и revision editor | Общий корпус fixtures в JS/Go, defaults, nested objects, secrets refs, upgrade preview; неизвестные keywords отвергаются | +| P2 Реестры пакетов | Каталоги harness, plugin, skill, template; OCI registry и package storage; discovery plugin | Publish/resolve/download по digest, permissions, блокировка, immutable versions, проверка DSH-совместимости | +| P3 Локально и on-premise | CLI, локальный DSH, self-hosted control plane, PostgreSQL и S3, bootstrap admin, backup/restore | Установка на чистой машине, запуск без облачной учётки, обновление/rollback, restore rehearsal; изолированный режим с кешированными пакетами | +| P4 Запуск на Runner’ах | Managed и customer-managed pools, стандартный adapter, lease/fencing, events, quotas, scheduling plugin | Повтор claim/complete, потеря связи, отмена, тайм-аут, дедупликация occurrence, отказ чужому tenant; нет двойного dispatch | +| P5 Provider plugins | Claude, Codex, xAI и другие; API и отдельно допущенные account modes | Матрица deploymentMode/authMode, refresh/revoke, доказанная возможность официальной интеграции; неподтверждённый mode скрыт/disabled | +| P6 Standalone JS app | Общий TypeScript/React UI: PWA, desktop shell, mobile shell | Desktop через Electron и локальный sidecar; mobile через Capacitor как клиент Runner; безопасный IPC, deep links, login/cancel/reconnect | +| P7 API edge cases и эксплуатация | Provider conformance, нагрузка, отказоустойчивость, observability | Выполнена матрица edge cases, лимиты подтверждены измерениями; Kubernetes Runner только после потребности и отдельной проверки | + +Edge cases не откладываются целиком до P7: auth/stream/retry проверки являются gate каждого провайдера уже на P5. P7 расширяет сочетания и нагрузку. Работа над UI и provider spikes может идти параллельно после P0, но publication gate не пропускается. + +## Standalone не означает одинаковый runtime везде + +Desktop UI общается с локальным Go sidecar и DSH Node runtime через ограниченный IPC. Node integration в renderer выключена; изоляция контекста включена. Mobile и PWA управляют удалённым или доступным on-prem Runner; Docker и полный DSH на телефоне не обещаются. Offline mobile — кеш каталога/черновиков, не выполнение произвольного harness. Локальное выполнение на мобильном устройстве требует отдельного capability и будущего runtime. + +On-prem control plane размещается у клиента. Собственный Runner, подключённый к облачному control plane, — другой режим и сам по себе не является on-prem установкой всей платформы. + +## Готовность к началу реализации + +Можно начинать P0–P2 по текущим контрактам. Нельзя объявлять готовыми универсальную DSH-совместимость, перенос сессии между средами и вход по подписке любого провайдера до выполнения соответствующих gate. Функциональность без подтверждённого mode не блокирует API-key путь и базовую платформу. diff --git a/designDocument/scaling.md b/designDocument/scaling.md index 63f7b23..2430342 100644 --- a/designDocument/scaling.md +++ b/designDocument/scaling.md @@ -8,7 +8,7 @@ ## Очереди и backpressure -Admission control резервирует tenant concurrency и бюджет перед назначением. Weighted fair scheduling чередует tenants; внутри tenant приоритет + возраст. Ограничены queue depth и max queue age. При превышении пользователь получает 429 с Retry-After либо явный queued status по принятой policy. Бесконечного скрытого backlog быть не должно. +Admission control при создании Run резервирует место в очереди и бюджет; tenant concurrency резервируется атомарно при назначении Attempt. Weighted fair scheduling чередует tenants; внутри tenant приоритет + возраст. Ограничены queue depth и max queue age. При превышении пользователь получает 429 с Retry-After либо явный queued status по принятой policy. Бесконечного скрытого backlog быть не должно. Учитываем лимиты внешних API, токены/мин, соединения и доступность источников. Шлюз контролирует свои вызовы. Для прямых вызовов Runner платформа гарантирует только ресурсные/временные лимиты, а финансовый предел зависит от провайдера credentials. @@ -53,6 +53,6 @@ Backup включает БД, объекты, ключевые конфигур Предлагаемые цели пилота: 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. +Нагрузочные сценарии: равномерный поток, массовый scheduled burst без jitter (MVP), один шумный tenant, недоступный внешний API, перезапуск dispatcher, потеря Runner, медленный S3, дубли terminal reports. Отдельно проверяем отсутствие чужих артефактов и credentials. Jitter расписаний оценивается будущим экспериментом. Стоимость = вычисления + хранение + egress + управляемые вызовы моделей. Цена прямых сторонних вызовов может быть неизвестна. Биллинг не строится исключительно на недоверенных отчётах пользовательского Runner. diff --git a/designDocument/security.md b/designDocument/security.md index fda5073..dea84bc 100644 --- a/designDocument/security.md +++ b/designDocument/security.md @@ -14,7 +14,7 @@ Identity в MVP — модуль Platform API с существующими ме ## Секреты и интеграции -ConnectionRef указывает на запись подключения. Секрет хранится с envelope encryption, ключ расшифровки управляется KMS. Значения не попадают в config, логи, схемы, артефакты и signed URL. Доступ ограничивается интеграцией и операцией. Шлюз по возможности вызывает API сам; для прямого доступа выдаются scoped credentials или секрет монтируется только в окружение конкретной попытки. +ConnectionRef указывает на запись подключения. Для server_vault секрет хранится с envelope encryption, ключ расшифровки управляется KMS. local_keychain и runner_private_store хранят секрет только в выбранной среде; сервер видит ссылку и состояние подключения. Значения не попадают в config, логи, схемы, артефакты и signed URL. Доступ ограничивается интеграцией и операцией. Шлюз по возможности вызывает API сам; для прямого доступа выдаются scoped credentials или секрет монтируется только в окружение конкретной попытки. Own Runner имеет техническую возможность прочитать выданные ему credentials; эта граница доверия показывается владельцу при назначении подключений. Отзыв токена платформы не отзывает уже раскрытый сторонний ключ: для этого нужен revoke у провайдера. @@ -29,3 +29,9 @@ Runner Protocol не навязывает реализацию sandbox, но д Аудит: actor, tenant, action, resource, result, timestamp, requestId. Без содержимого prompts и secrets по умолчанию. История публикаций, выдачи credentials, назначения, отмены, обновления настроек и изменений прав сохраняется отдельно от debug-логов. Удаление tenant сначала блокирует новые запуски, отзывает доступ, останавливает задачи и удаляет данные по retention policy. Backup retention и сроки окончательного удаления явно сообщаются пользователю. Публичность пакета не распространяется на Run, connections или результаты. + +## Подключения аккаунтов провайдеров + +Вход в Invest Harness не равен входу в аккаунт модели. Допустимый способ авторизации проверяется отдельно для провайдера и deployment mode. Собственный OAuth используется только при поддерживаемой регистрации приложения; credentials официальных клиентов не извлекаются и не копируются на сервер. Подробности: [плагины](plugins.md), [Provider API](api/provider-api.md). + +Conformance собственного Runner проверяет протокол, но не доказывает защищённость чужой машины. Администратор явно утверждает trust policy пула. Доступы плагинов ограничены actor/tenant/Run; установка discovery-плагина не разрешает ему автоматически исполнять найденный пакет.