# Консоль и операционные интерфейсы

## Назначение

Домен описывает центральный чат с `agent-manager`, управление проектами, репозиториями и доступами, рабочие представления по задачам, операционные статусы и диагностику, UX для запуска flow и наблюдения за выполнением, а также экраны каталогов пакетов, контура серверов и кластеров, биллинга и настроек автоматизации.

## Что входит

- центральный чат с `agent-manager`;
- управление проектами, репозиториями и доступами;
- рабочие представления по задачам;
- операционные статусы и диагностика;
- UX для запуска flow и наблюдения за выполнением;
- экраны каталогов пакетов;
- экраны контура серверов и кластеров;
- экраны биллинга и настроек автоматизации.

## Gateway-поверхность

Первый backend-контур для консоли сотрудников — `staff-gateway`. Он отдаёт `web-console` OpenAPI для входящих решений владельца: список, карточку одного решения и отправку ответа `approve`, `reject`, `request_changes` или `answer`, если это разрешено текущим request. Gateway остаётся тонким: он принимает actor/request context, вызывает `interaction-hub` по gRPC и возвращает только safe refs, статусы, краткие summaries, timestamps и version. Собственная модель решений, прямой доступ к БД доменных сервисов, управление `Run`/session/governance decision/provider write и междоменная агрегация в этот контур не входят.

Список `owner inbox` поддерживает scope-фильтр, фильтры по kind/status/source owner/assignee/correlation, `include_diagnostics` и cursor pagination. Сортировку не выбирает клиент: её фиксирует `interaction-hub`, чтобы UI получал стабильный порядок с активными и срочными карточками выше. Карточка решения возвращает безопасные детали request, delivery/callback/response summaries, `allowed_actions`, timestamps и `version`; завершённые request не должны возвращать доступные действия. Ответ владельца отправляется с `expected_version` и `command_id` или `idempotency_key`, а gateway маппит ошибки `interaction-hub` в безопасные HTTP-статусы и коды без раскрытия raw payload.

Для операторского просмотра выполнения `staff-gateway` отдаёт `GET /v1/agent-runs/{run_id}/runtime-status`. Endpoint вызывает `agent-manager.GetAgentRunRuntimeStatus` и возвращает только безопасную сводку: `run_id`, `run_status`, `runtime_job_ref`, `runtime_job_status`, safe error code/summary, timestamps, `run_version`, `human_gate_waiting` и safe refs ожидания. Prompt body, secret values, kubeconfig, workspace paths, raw provider payload и большие логи через gateway не проходят; runtime job lifecycle остаётся у `runtime-manager`, а orchestration state — у `agent-manager`.

Для экрана истории действий `staff-gateway` отдаёт `GET /v1/agent-runs/{run_id}/activities`. Endpoint вызывает `agent-manager.ListAgentActivities` с typed фильтрами `activity_kind`, `status` и cursor pagination; фильтра по временному диапазону нет, потому что текущий gRPC-контракт его не содержит. Ответ содержит safe activity entries: refs/status/timestamps/tool metadata, safe summary, payload digest, bounded error, version и correlation id. Raw tool input/output, stdout/stderr, prompt body, transcript, provider payload, workspace paths, secret values и большие логи через gateway не проходят.

Для операторской сводки governance `staff-gateway` отдаёт `GET /v1/governance/summary`. Endpoint принимает ровно один safe selector: target, project/repository context, release candidate, release decision package id или integration ref; затем вызывает `governance-manager.GetGovernanceSummary` и возвращает уже подготовленную доменную модель чтения. Gateway не вычисляет risk/gate/release правила, не читает БД соседних сервисов и не обогащает provider/runtime/agent данные. Ответ содержит pending/completed decisions, risk class, gate/release outcomes, linked provider/agent/runtime evidence refs, bounded diagnostics, timestamps и versions; raw prompt, transcript, tool input/output, provider payload, webhook body, stdout/stderr, workspace paths, kubeconfig, secret values и большие детали через gateway не проходят.

Для командного центра и экрана исполнений `staff-gateway` отдаёт `GET /v1/agent-sessions` и `GET /v1/agent-runs` без прямого чтения БД. Endpoints вызывают `agent-manager.ListAgentSessions` и `agent-manager.ListAgentRunSummaries`, прокидывают actor/request context и scope/status/provider/time filters, а наружу возвращают только session/run refs, role/stage refs, сохранённый runtime job ref, safe status/summary/error, Human gate/follow-up flags, latest activity summary, timestamps и version. Live runtime job status остаётся точечным `GET /v1/agent-runs/{run_id}/runtime-status`, чтобы список не делал fan-out в runtime, Kubernetes или provider API. Списки используют scope types, доступные в текущем `agent-manager` contract: `platform`, `organization`, `project`, `repository`; `service` scope для этих списков отображается в `web-console` как неподдержанный, пока доменный контракт не расширен.

Для self-deploy наблюдения `staff-gateway` отдаёт `GET /v1/self-deploy/summary`. Endpoint сначала вызывает `agent-manager.ListSelfDeployPlans` и возвращает latest visible plan по actor/request context и scope: provider signal ref/status, project/repository refs, source branch/commit refs, affected service keys, path categories, `services.yaml` digest, plan fingerprint, self-deploy plan status, governance gate/release refs, runtime build context/build/deploy refs и safe summary. Если plan ещё не создан, но caller передал safe project/provider signal refs, gateway уточняет readiness через `project-catalog.GetSelfDeploySignal`; если provider signal ещё не передан, но project известен, gateway проверяет active repository binding через `project-catalog.ListRepositories`. Для pending self-deploy gate gateway дополнительно читает `governance-manager.GetGovernanceSummary` по target `self_deploy_plan` и передаёт project/repository context как access scope; наружу возвращаются `gate_request_id`, `gate_request_version`, `gate_policy_ref` и `allowed_actions`, чтобы UI мог отправить optimistic command без разбора внутренних строковых refs. Ответ всегда содержит owner-facing `chain_status` и `next_step`: `not_configured`, `project_missing`, `repository_binding_missing`, `waiting_for_provider_signal`, `provider_signal_found`, `needs_services_policy_reconcile`, `plan_created`, `governance_gate_pending`, `approved_ready_for_build` или `blocked`. Runtime summary показывает безопасную строку стадий `signal`, `plan`, `gate`, `approval`, `build_context`, `build`, `deploy`, `health`, а `runtime_job_ref` указывает на последний build context, build job или deploy job ref без live-доступа к Kubernetes. Raw webhook body, provider response, diff, полный YAML, tokens, OAuth state/cookies, secret values и автоматический deploy через endpoint не доступны.

Self-deploy решение владельца отправляется через `POST /v1/self-deploy/gates/{gate_request_id}/decision`. Endpoint принимает только `approve`, `reject` или `request_changes`, bounded comment, `idempotency_key`, `expected_version`, expected pending status и safe refs, затем вызывает `governance-manager.SubmitGateDecision`. `approve` снимает governance gate; дальнейшее продвижение цепочки выполняет `agent-manager`: подготовка build context в `runtime-manager`, чтение checked build/deploy plan в `project-catalog`, постановка build/deploy jobs и запись безопасных refs/status в `SelfDeployPlan`. Gateway не хранит собственную модель решений и не записывает raw webhook body, diff, provider response, полный YAML, tokens, OAuth state/cookies или secret values.

## Web-console MVP

Первый активный `web-console` размещён в `services/staff/web-console` и использует Vue, Vite, TypeScript и Vuetify. Приложение получает типизированный API-клиент из `specs/openapi/staff-gateway.v1.yaml`, вызывает только `staff-gateway` и не обращается напрямую к БД, Kubernetes, внутренним gRPC-сервисам или сервисам-владельцам. Production-сборка не формирует доверенные `X-Kodex-Actor-*`: проверенный actor context добавляет trusted edge или backend-session слой перед `staff-gateway`. Ручные actor headers доступны только в явном local-dev режиме Vite.

Первый набор экранов:

- командный центр: каркас, карточки по текущей странице входящих и первым страницам списков `AgentSession`/`AgentRun`, отключённый диалоговый ввод и быстрые действия до появления соответствующих HTTP-контрактов;
- входящие и решения: список, карточка, безопасные детали и действия ответа через owner inbox endpoints;
- исполнения и среда: списки `AgentSession`/`AgentRun`, выбор `Run`, runtime summary и activity timeline по safe `run_id`;
- self-deploy наблюдение и решение gate: блок командного центра читает `GET /v1/self-deploy/summary`, показывает реальные safe refs/status/digests или честное `unavailable`, а при pending gate отправляет `approve`, `reject` или `request_changes` через `POST /v1/self-deploy/gates/{gate_request_id}/decision`, без кнопки автоматического deploy;
- governance: операторская сводка доступна через `staff-gateway`, экран в `web-console` остаётся следующим frontend-срезом.

Текущая интерфейсная итерация доводит эти экраны до демонстрируемого состояния: shell адаптируется под узкую ширину, командный центр показывает отдельно работающие зоны и зоны, ожидающие подключение frontend или ещё не появившиеся `staff-gateway` endpoints, owner inbox использует master-detail паттерн с безопасными ошибками и ответом только через `allowed_actions`, а экран исполнений строится от списков `AgentSession`/`AgentRun` и сохраняет ручной ввод `run_id` как дополнительный способ открыть конкретный `Run`.

Операторская наблюдаемость `Run/session` строится из безопасных полей `staff-gateway`: статусы running/waiting/completed/failed/cancelled, Human gate/follow-up flags, reason refs/codes, safe error code/summary, runtime observation state, latest activity summary и session/job/provider refs. Командный центр выделяет выполняющиеся, ожидающие и проблемные `Run`, а экран исполнений показывает причину ожидания и где смотреть дальше: session, runtime job, provider-native `Issue`/`PR/MR`, activity timeline и detail выбранного `Run`. `runtime_job_status`, включая `timed_out`, доступен только в detail endpoint `GET /v1/agent-runs/{run_id}/runtime-status`; list endpoints не делают live fan-out в runtime, Kubernetes или provider API.

Для self-deploy сценария командный центр показывает отдельный owner-facing блок наблюдения поверх `GET /v1/self-deploy/summary`. Блок отображает, где остановилась цепочка, следующий безопасный шаг, последний safe provider signal ref, связанный repository/project, branch/commit refs, изменённые service keys или path categories, `services.yaml` digest/fingerprint, deploy plan status, governance/owner decision refs/status и safe error/reason summary. Если `SelfDeployPlan` ещё не создан, `staff-gateway` может запросить pre-plan остановку через `project-catalog.GetSelfDeploySignal`; для этого self-repo onboarding выдаёт `service/staff-gateway` `project.policy.read` на `services_policy` в project scope. Когда plan уже создан, `staff-gateway` читает governance summary только через read-права `governance.risk.read` и `governance.gate.read` в том же project scope; данные выбираются через risk assessment/gate связи, а не по одному target без project-фильтра. Если governance gate находится в pending status и summary содержит `allowed_actions` с `gate_request_id`/`gate_request_version`, владелец может выбрать `approve`, `reject` или `request_changes`; UI отправляет bounded comment и idempotency key через `staff-gateway`, а затем перечитывает сводку. Если provider/project/governance/runtime цепочка ещё не дала доменный факт, карточка показывает `unavailable`, `pending` или конкретный `chain_status`, не подменяя состояние демо-данными. Raw webhook body, provider response, diff, полный YAML, tokens, OAuth state/cookies, secrets и автоматический deploy через `web-console` не доступны.

Агрегированная витрина командного центра, создание `Issue`, запуск flow, чат с `agent-manager`, проектные списки и экран governance summary не подменяются демо-данными. Пока frontend не подключил соответствующий endpoint или в `staff-gateway` нет нужной HTTP-ручки, интерфейс показывает честные пустые или отключённые состояния.

## Карта Issue

- Доменная карта: `docs/delivery/issue-map/domains/console-and-operations-ux.md`.
