184 lines
15 KiB
Markdown
184 lines
15 KiB
Markdown
> Создан 2026-09-28. Статус: **📋 ПЛАН, ЖДЁТ ОДОБРЕНИЯ ALEX.**
|
||
> Ветка: `fix/hosted-toolsets-duplicate-endpoint` (@ `b01bdc6`, 2 файла, +263)
|
||
> **PR normahq/runtime#5** — OPEN, `CHANGES_REQUESTED` от **metalagman** (2026-09-28T09:04:10Z)
|
||
> Репо: `~/Developer/runtime-local`. Связано: [[personal/plans/runtime-pr4-openai-toolcalls-fixes]].
|
||
|
||
---
|
||
|
||
## 0. Что говорит ревью (дословно, 3 пункта)
|
||
|
||
| # | Severity | Суть |
|
||
|---|---|---|
|
||
| 1 | **P1 — blocking** | `mcpEndpointKey` выбрасывает **все** query-параметры, а группировка игнорирует `Headers`. И query, и headers могут выбирать тенанта / авторизационный контекст / режим сервера. `/mcp?tenant=a` и `/mcp?tenant=b` схлопываются в один произвольный конфиг → **доступ к чужому tool-set / пересечение границы доступа**. Ревьюер: *«keep generic endpoint identity exact»* и *«resolve the Balda-specific duplicate in the Balda composition layer, or introduce explicit alias/replacement metadata»*. |
|
||
| 2 | **P2 — test gap** | `selectScopedOnly` **повторяет алгоритм продакшена** внутри теста и вычисляет ожидаемого победителя сам. Не проверяет, что реально удержанный toolset/транспорт — именно scoped URL. Ассерт вакуумный. |
|
||
| 3 | **P2 — test gap** | Локальный интерфейс `ProcessRequest(ctx any, req any) error` — Go требует **точных** типов параметров, поэтому реальный метод `ProcessRequest(agent.Context, *model.LLMRequest) error` **всё равно не удовлетворит** интерфейс. Тест не может поймать регрессию. |
|
||
|
||
**Validation ревьюера:** `go test -race ./...`, `go vet ./...`, `go tool golangci-lint run ./...` — проходят. `GitHub currently reports no check runs/statuses` (тот же fork-блокер, что в PR #4).
|
||
|
||
---
|
||
|
||
## 1. Подтверждение фактами
|
||
|
||
### P1 — ключ стирает query и не смотрит Headers
|
||
`agentfactory/agentfactory.go` (`b01bdc6`), функция `mcpEndpointKey`:
|
||
```go
|
||
u.RawQuery = ""
|
||
u.Fragment = ""
|
||
return u.String()
|
||
```
|
||
→ `http://h:1/mcp/balda?ctx=abc123` и `http://h:1/mcp/balda?tenant=b` дают **один ключ**.
|
||
`Headers` в ключе не участвуют вообще: `MCPServerConfig.Headers` есть
|
||
(`toRuntimeMCPServers` его клонирует, `httpClientWithHeaders` его применяет) — значит разные
|
||
`Authorization` на одном URL сейчас считаются «тем же сервером». **Это реальная дыра, ревью право.**
|
||
|
||
Побочный эффект `mcpURLIsScoped`: «scoped» = «есть хоть какой-то query». Это тоже выводит
|
||
семантику из формы хоста/пути/строки — ровно то, против чего ревьюер.
|
||
|
||
### P2-1 — тест дублирует прод
|
||
`duplicate_toolset_test.go:49,57-94`: `selectScopedOnly` — **копия** цикла `hostedToolsets`
|
||
(`keeperOf`/`skip`/`mcpURLIsScoped`). Тест проверяет копию алгоритма, а не результат работы
|
||
`hostedToolsets` (который вернул непрозрачные `tool.Toolset`; тест лишь считает `len(toolsets)`).
|
||
Замечание верное: если поменять приоритет в проде и в копии синхронно — тест останется зелёным.
|
||
|
||
### P2-2 — вакуумный ассерт
|
||
```go
|
||
type requestProcessor interface { ProcessRequest(ctx any, req any) error }
|
||
```
|
||
Продакшн-сигнатура (подтверждено в модульном кэше
|
||
`adk/v2@v2.4.0/internal/toolinternal/tool.go:41` и `tool/tool.go:192`):
|
||
```go
|
||
ProcessRequest(ctx agent.Context, req *model.LLMRequest) error
|
||
```
|
||
`any` ≠ `agent.Context` → метод **не** реализует интерфейс ни в каком случае. `if _, ok := ...; ok`
|
||
всегда `false`, `Fatalf` недостижим. **Вакуумный.**
|
||
|
||
---
|
||
|
||
## 2. План правок
|
||
|
||
### Фикс 1 (P1) — точная идентичность на generic-слое + явный алиас на слое Balda
|
||
|
||
Разделяем **«когда схлопывать»** и **«какой именно дубль схлопывать»**.
|
||
|
||
**(a) `agentfactory`: убрать умозаключения из хоста/пути.**
|
||
- Удалить `mcpEndpointKey` (стирание query) и `mcpURLIsScoped`.
|
||
- Ввести **явное** объявление эквивалентности, а не вывод из формы URL. Два кандидата:
|
||
- `MCPServerConfig.Aliases []string` — «id этого конфига дублирует id X» (аддитивно к
|
||
`agentconfig`; правка публичного API → документировать в `README.md` по правилу `AGENTS.md`);
|
||
- либо поле `DedupKey string` — «схлопывать только конфиги с одинаковым непустым ключом».
|
||
- **Рекомендация: `DedupKey string`** (`omitempty`). Почему: не требует знания id-ов,
|
||
не создаёт транзитивных связей, неинвазивно для остальных потребителей (пусто → не схлопывается
|
||
никогда). Generic-слой больше ничего не выводит — кто задал ключ, тот и отвечает за смысл.
|
||
- Схлопывание: только `key != "" && key == key` → **детерминированный** победитель (см. ниже).
|
||
|
||
**(b) `balda` (composition layer) — объявить дубль явно.**
|
||
В `internal/apps/balda/agent/runtime_manager.go:344` (место `registry.Set(binding.ID, binding.Config)`)
|
||
проставлять `DedupKey` = endpoint **без** query, но **только** для связки
|
||
`bundledBaldaServerID` → session-scoped binding. Это то самое «resolve in the Balda composition
|
||
layer», чего просит ревьюер. Разные `?tenant=`/`Authorization` в общем слое остаются разными.
|
||
|
||
**(c) Детерминированный победитель — без «scoped эвристики».**
|
||
Вместо `mcpURLIsScoped` (снова форма URL) — при `DedupKey`-группе размером >1 выбирать
|
||
**лексикографически меньший id** и логировать остальные как skipped. В Balda это даст
|
||
`balda` (стабильно, не зависит от случайного токена). 🔴 **Следствие для Balda:** session-токен
|
||
перестанет попадать в URL активного тулсета — надо подтвердить, что context-broker доставляет
|
||
контекст иначе (см. §3, риск 1). Если нет — победителя задавать явным полем
|
||
`DedupPreferred bool`, а не эвристикой.
|
||
|
||
**Обоснование смены победителя (было: scoped, стало: явное/lexicographic):**
|
||
старый выбор «scoped» — это тоже неявный вывод, и ревьюер его отвергает по духу P1.
|
||
Явное поле/детерминированный порядок — предсказуемо и тестируемо.
|
||
|
||
### Фикс 2 (P2-1) — тест на фактический результат
|
||
|
||
Вместо копии алгоритма проверять **то, что реально вернул `hostedToolsets`**:
|
||
- поднять **два httptest-HTTP-сервера** (MCP handler) с *разными* tool-листами по разным путям;
|
||
настоящий `hostedToolsets` → вызвать `Tools()`/`Name()` полученных тулсетов и убедиться, что
|
||
виден tool-set сервера с ожидаемого URL;
|
||
- либо, если поднять MCP-сервер дорого, — прокинуть наружу фактически использованный endpoint через
|
||
**инъектируемый конструктор транспорта** (`var mcpTransportForConfig = ...` + подмена в тесте),
|
||
и ассертить `Transport.Endpoint`. Тогда тест падает, если прод удержал не тот конфиг.
|
||
- 🔴 Предпочтение: инъекция конструктора — дешевле, детерминированнее и не тянет сеть. Реализовать
|
||
как тестовый хук в `agentfactory` (тонкая обёртка), без изменения публичного API.
|
||
|
||
### Фикс 3 (P2-2) — точная сигнатура
|
||
|
||
Заменить вакуумный интерфейс:
|
||
```go
|
||
import (
|
||
"google.golang.org/adk/v2/agent"
|
||
"google.golang.org/adk/v2/model"
|
||
)
|
||
type requestProcessor interface {
|
||
ProcessRequest(ctx agent.Context, req *model.LLMRequest) error
|
||
}
|
||
```
|
||
Продакшн-типы (`agent.Context`, `*model.LLMRequest`) подтверждены в модульном кэше.
|
||
Плюс **позитивный контроль**: если ассерт вакуумный, тест должен падать. Добавить в тот же тест
|
||
проверку, что интерфейс **реализуется** заведомо подходящим типом (например,
|
||
`tool.SetRequestProcessor`-совместимой обёрткой или `*mcpTool` из `mcptoolset`) — если сигнатура
|
||
разъедется с продакшном, тест это покажет, а не будет молчать.
|
||
|
||
### Тесты (контрактные)
|
||
| Тест | Что фиксирует |
|
||
|---|---|
|
||
| `TestDistinctQueryParamsNeverCollapseWithoutAlias` | `/mcp?tenant=a` vs `/mcp?tenant=b` (без `DedupKey`) → **2** тулсета |
|
||
| `TestDistinctHeadersNeverCollapseWithoutAlias` | один URL, разные `Authorization` → **2** тулсета |
|
||
| `TestSameDedupKeyCollapses` | два конфига с одинаковым `DedupKey` → **1**, и удержан **детерминированный** |
|
||
| `TestEmptyDedupKeyNeverCollapses` | `DedupKey:""` + одинаковые URL → **2** (generic-слой ничего не выводит) |
|
||
| `TestHostedToolsetsKeepsRetainedEndpoint` | через хук транспорта: удержан именно ожидаемый endpoint/id (замена `selectScopedOnly`) |
|
||
| `TestMcpToolsetRequestProcessorSignature` | точная сигнатура `agent.Context`/`*model.LLMRequest` + позитивный контроль |
|
||
|
||
### Гейты
|
||
```
|
||
gofmt -l agentfactory/ agentconfig/
|
||
go build ./...
|
||
go test ./... && go test -race ./...
|
||
go vet ./...
|
||
go tool golangci-lint run ./...
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Риски / питфоллы
|
||
|
||
1. 🔴 **Смена победителя в Balda — поведенческий риск, не косметика.** Сейчас в URL живёт
|
||
`ctx=<токен>` (`binding.Config.URL`, ставит context-broker). Если удержать `balda` (без токена),
|
||
session-memory/context может перестать доставляться. **Перед реализацией (b/c) — проверить,
|
||
как композируется `binding.Config.URL` и нужен ли токен в URL вообще.**
|
||
Развилка: (i) токен не нужен → lexicographic-победитель; (ii) токен нужен → явное
|
||
`DedupPreferred` на scoped-конфиге. **Решение за Alex.**
|
||
2. ⚠️ Правка `agentconfig.MCPServerConfig` = **публичный API** модуля. По `AGENTS.md`: сохранять
|
||
публичные API, изменения документировать в `README.md`. `DedupKey string` — аддитивно, но
|
||
документировать обязательно.
|
||
3. ⚠️ Правки делать **только дельта-апплаером** (`tools/run-project-deltas.sh`, `check` → `apply`),
|
||
не sed/in-place (правило Alex).
|
||
4. 🔴 **Ветка PR #5 ≠ текущая локальная ветка.** Сейчас checked out `feat/openai-tool-calls-v2`
|
||
(PR #4). Нужен `git switch fix/hosted-toolsets-duplicate-endpoint` **до** правок; `git status`
|
||
чистый (untracked `tools/` — не коммитить).
|
||
5. ⚠️ **PR #4 и PR #5 оба открыты и оба форк-PR** → CI не запускается без одобрения мейнтейнера
|
||
(см. §0в в [[personal/plans/runtime-pr4-openai-toolcalls-fixes]]). Локальные гейты — эквивалент CI.
|
||
6. ⚠️ Ревьюер — **metalagman**. Ревью опубликовано в PR (в отличие от PR #4, где работали по тексту
|
||
Alex). Ответ ревьюеру писать в PR.
|
||
|
||
---
|
||
|
||
## 4. Порядок (после одобрения)
|
||
|
||
1. ⛔ **Ожидание решения Alex по §3.1** (нужен ли `ctx`-токен в URL удержанного тулсета)
|
||
2. ⛔ Ожидание решения по §2-Фикс1(a): `DedupKey` vs `Aliases`
|
||
3. `git switch fix/hosted-toolsets-duplicate-endpoint`; бэкап-коммит текущего состояния (проверить, что нет своих правок)
|
||
4. `agentconfig`: добавить поле (+ документировать в `README.md`)
|
||
5. `agentfactory`: убрать `mcpEndpointKey`/`mcpURLIsScoped`; схлопывание по явному ключу; детерминированный победитель; тестовый хук транспорта
|
||
6. `balda`: проставить `DedupKey` в composition layer (`runtime_manager.go:344`)
|
||
7. Переписать тесты: удалить `selectScopedOnly`, добавить 6 контрактных; фикс сигнатуры
|
||
8. Гейты (§2) — все зелёные
|
||
9. Коммит (Conventional Commits) → push → `gh pr checks 5`
|
||
10. Ответ ревьюеру в PR + обновить Obsidian (этот файл + [[personal/tech/adk-hostedagent-openai-mcp]])
|
||
|
||
## Связанные заметки
|
||
|
||
- [[personal/plans/runtime-pr4-openai-toolcalls-fixes]] — PR #4, контекст форка и fork-CI-блокера
|
||
- [[personal/tech/adk-hostedagent-openai-mcp]] — архитектура MCP/toolset, `runtime.mcp_servers`
|
||
- [[personal/tech/balda-go-fx-pitfalls]] — метод дельт, питфоллы
|