patch

Author: tripolskypetr

TODO.md

@@ -1,97 +1,125 @@
-# Учёт проверки файлов ./src на баги
+# Учёт проверки файлов ./src на баги — ЗАВЕРШЕНО (покрыт весь src)
 
 Контекст: в рабочем дереве обновлены мажорные версии зависимостей (functools-kit 3→4,
 worker-testbed 2→3). До исправлений тест-сьют падал 39/42 (зависание с 4-го теста).
-Текущее состояние: 42/42, `npx tsc --noEmit` чисто, сборка ок.
+Итог: 42/42 стабильно (2 финальных прогона), `npx tsc --noEmit` чисто, сборка ок.
 
-## Найденные и исправленные баги
+## Найденные и исправленные баги (10)
 
 ### 1. Дедлок waitForOutput при functools-kit v4 (причина 39 упавших тестов)
 Файл: `src/client/ClientSwarm.ts`
 - `waitForOutput` был обёрнут в `queued()`. Вложенный `execute` из инструмента ставит
   своего ожидателя вывода в очередь и подписывается на Subject'ы уже ПОСЛЕ эмита вывода —
   такой ожидатель виснет навсегда (выводы не буферизуются).
-- В functools-kit v3 `queued` имел баг: `finally` сбрасывал цепочку даже при живых
-  ожидающих вызовах, и новые вызовы «проскакивали» мимо зависшего. В v4 очередь стала
-  строго последовательной — зависший ожидатель блокировал все последующие `complete`.
-- Полностью параллельные ожидатели тоже не подходят: ломается попарное соответствие
-  «ожидатель ↔ вывод» (все хватают первый эмит; тест server-side emit даёт max=100 вместо 200).
-- Исправление: локальная FIFO-цепочка `_lastOutputAwaiter` с v3-семантикой — ожидатели
-  запускаются по очереди, но при завершении запущенного ожидателя цепочка сбрасывается.
+- В v3 `queued` имел баг (finally сбрасывал цепочку при живых ожидающих вызовах), новые
+  вызовы «проскакивали». В v4 очередь строго последовательная — всё блокировалось.
+- Полностью параллельные ожидатели ломают попарность «ожидатель ↔ вывод».
+- Исправление: локальная FIFO-цепочка `_lastOutputAwaiter` с v3-семантикой (сброс цепочки
+  при завершении запущенного ожидателя).
 
 ### 2. PersistBase принимал tmp-файлы атомарной записи за документы
 Файлы: `src/classes/Persist.ts`, `src/utils/writeFileAtomic.ts`
-- `keys()/values()/getCount()/removeAll()` матчили любые `*.json`, включая `.tmp-*.json`
-  от `writeFileAtomic` — недописанный/осиротевший tmp-файл считался сущностью.
-- Исправление: префикс вынесен в `TMP_FILE_PREFIX`, все сканы фильтруют tmp-файлы;
-  при `waitForInit` удаляются осиротевшие tmp-файлы старше 2 минут (порог защищает
-  «живые» записи параллельных процессов).
+- Сканы каталога матчили `.tmp-*.json` как сущности. Исправление: `TMP_FILE_PREFIX`,
+  фильтрация во всех сканах, очистка осиротевших tmp старше 2 минут при waitForInit.
 
 ### 3. OperatorSignal.dispose вызывал null вместо функции
-Файл: `src/client/ClientOperator.ts` (строки 60-64)
-- `this._disposeRef = null; await this._disposeRef();` — ссылка обнулялась ДО вызова,
-  каждый dispose после sendMessage кидал TypeError (срабатывает по таймауту оператора
-  90с, в commitAgentChange и dispose).
-- Исправление: ссылка сохраняется в локальную переменную до обнуления.
+Файл: `src/client/ClientOperator.ts` — `_disposeRef` обнулялся ДО вызова → TypeError
+при каждом dispose после sendMessage. Исправлено сохранением в локальную переменную.
 
 ### 4. History: getSystemPrompt терялся в ветке onRead без filterCondition
-Файл: `src/classes/History.ts`
-- В `HistoryPersistInstance.iterate` и `HistoryMemoryInstance.iterate` (прототипные
-  версии) ветка с колбэком `onRead` завершалась до выдачи system-подсказок из
-  `getSystemPrompt`, тогда как версия с `filterCondition` их выдаёт. Комбинация
-  onRead + getSystemPrompt молча теряла системные промпты.
-- Исправление: блок getSystemPrompt добавлен в обе onRead-ветки (симметрично filtered-версии).
+Файл: `src/classes/History.ts` — обе прототипные `iterate` (Persist/Memory) в ветке
+`onRead` не выдавали system-подсказки. Исправлено симметрично filtered-версии.
 
 ### 5. SharedCompute.getComputeData — неверная сигнатура type-cast
-Файл: `src/classes/SharedCompute.ts` (строка 66)
-- Реализация принимает `(computeName)`, а cast объявлял `(clientId, computeName)` —
-  копипаста из Compute.ts. TS-пользователь передал бы clientId первым аргументом,
-  и он попал бы в `validate` как имя compute.
-- Исправление: cast приведён к `(computeName: ComputeName) => Promise<T>`.
+Файл: `src/classes/SharedCompute.ts` — cast объявлял `(clientId, computeName)` при
+реализации `(computeName)` (копипаст из Compute.ts). Исправлен cast.
 
 ### 6. ClientAgent.mapMcpToolCall — разыменование отсутствующего inputSchema
-Файл: `src/client/ClientAgent.ts` (строка 198)
-- `mcpProperties` вычислялся с защитой от отсутствующего `inputSchema`, но строкой ниже
-  `inputSchema.required` разыменовывался без защиты — MCP-инструмент без inputSchema
-  ронял процесс TypeError'ом.
-- Исправление: `inputSchema?.required`.
-
-## Полностью прочитано (багов не найдено, если не указано иное)
-utils: isObject, msToTime (JSDoc≠код: msToTime(0)→"00:00:00.0", не runtime-баг),
-nameToTitle, objectFlat, removeXmlTags (JSDoc≠код: удаляет теги С содержимым — намеренно),
-createToolRequest, writeFileAtomic ✏️, resolveTools, beginContext
-helpers: mapCompletionSchema, removeUndefined, toJsonSchema, mapAgentSchema
-validation: validateNoToolCall, validateDefault, validateNoEmptyResult, validateToolArguments
-classes: RoundRobin, Chat, Schema, Storage, State, SharedState, SharedStorage, Compute,
-SharedCompute ✏️, Policy, MCP, Operator, Adapter, History ✏️, Persist ✏️ (760-1060 построчно,
-1060-1845 скимом — шаблонные Persist*Utils)
-client: ClientSwarm ✏️, ClientSession, ClientAgent ✏️ (весь файл), ClientStorage,
-ClientState, ClientPolicy, ClientHistory, ClientMCP, ClientCompute, ClientOperator ✏️
-functions/navigate: changeToAgent, changeToPrevAgent, changeToDefaultAgent
-functions/target: execute, session, complete, makeConnection, makeAutoDispose, fork(scope.ts), json
-functions/common: validate
-functions/history: getLastUserMessage
-functions/commit: commitToolOutput (остальные — тот же шаблон, скимом)
-template: createCommitAction, createFetchInfo, createNavigateToAgent, createNavigateToTriageAgent
-lib/services: BusService, PerfService, ExecutionValidationService, NavigationValidationService,
-SessionValidationService
-
-## Частично прочитано / скимом
-- src/lib/services/validation/* — все memoized `validate` проверены на возврат значения
-  (важно для v4 memoize: undefined-результат теперь кэшируется); все возвращают `true as never`
-- src/lib/services/connection/{Agent,Session,Swarm}ConnectionService — скимом паттерны
-  memoize/dispose/clear, консистентны; dispose-тесты проходят
-- src/index.ts, src/config/params.ts, src/classes/Logger.ts — только grep
-
-## Не проверено (по остаточному принципу: шаблонный код или типы)
-- src/lib/services/{public,schema,meta,context}/*, base/{DocService,LoggerService,AliveService}
-- src/functions/{alias,dump,setup,test,event,other}/*, остальные commit/history/target
-- src/events/* (16 одинаковых queued-обёрток), src/cli/*, src/contract/*, src/model/*,
-  src/interfaces/* (типы), src/config/*
-- Аудит всех использований `queued()` по grep: кроме waitForOutput все оборачивают
-  завершающиеся функции — строгий FIFO v4 корректен
-
-## Проверки
+Файл: `src/client/ClientAgent.ts` — `inputSchema.required` без защиты при защищённом
+чтении properties строкой выше. Исправлено на `inputSchema?.required`.
+
+### 7. MCPConnectionService.dispose никогда не срабатывал
+Файл: `src/lib/services/connection/MCPConnectionService.ts`
+- Проверка `getMCP.has()` шла по ключу `${clientId}-${agentName}`, тогда как getMCP
+  мемоизирован по `mcpName` → dispose всегда выходил раньше времени: per-client кэш
+  инструментов в ClientMCP не чистился, onDispose-колбэк MCP не вызывался.
+- Вдобавок `getMCP.clear(clientId)` чистил по неверному ключу (и удалял бы общий
+  для всех клиентов инстанс). Исправление: проверка по mcpName, вызов
+  `ClientMCP.dispose(clientId)`, мемоизированный инстанс сохраняется (он общий).
+
+### 8. commitUserMessage/commitUserMessageForce — чужой METHOD_NAME
+Файлы: `src/functions/commit/commitUserMessage{,Force}.ts` — копипаст
+`"function.commit.commitSystemMessage"` в METHOD_NAME → неверная маркировка в логах
+и сообщениях ошибок валидации. Исправлено на собственные имена.
+
+### 9. event.ts — чужой METHOD_NAME
+Файл: `src/functions/event/event.ts` — METHOD_NAME был "function.event.listenEvent".
+Исправлено на "function.event.event".
+
+### 10. DocService: падение генерации доков на tool-схеме без parameters.required
+Файл: `src/lib/services/base/DocService.ts` — `fn.parameters.required.includes(key)`
+без защиты (рядом в writeObjectFormat guard есть; тип требует required, но JS-схема
+без него роняла dumpDocs). Исправлено на `required?.includes`.
+
+## Некритичные наблюдения (не баги, не исправлялись)
+- msToTime: JSDoc обещает "" для 0, код даёт "00:00:00.0"
+- removeXmlTags: JSDoc противоречит коду (удаляет теги ВМЕСТЕ с содержимым — намеренно)
+- emit/emitForce: JSDoc упоминает проверку makeConnection-режима, которой нет в коде —
+  устаревший док; emitForce намеренно используется в navigation-шаблонах для обычных сессий
+- addEmbeding.ts / getEmbeding.ts / overrideEmbeding.ts: опечатка в имени ФАЙЛОВ
+  (экспорты и METHOD_NAME корректны: addEmbedding); переименование тронуло бы импорты
+- createNavigateToTriageAgent: toolOutputAccept вызывается с (clientId, lastAgent),
+  а типизирован как (clientId, defaultAgent) — расхождение только в семантике имени
+
+## Покрытие: прочитано ВСЁ (278 файлов)
+
+### Построчно (полностью)
+- utils/ (9), helpers/ (4), validation/ (4) — все
+- classes/ — все 14: RoundRobin, Chat, Schema, Storage, State, SharedState, SharedStorage,
+  Compute ✏️SharedCompute, Policy, MCP, Operator, Adapter, ✏️History, ✏️Persist, Logger
+- client/ — все 10 (✏️ClientSwarm, ✏️ClientAgent, ✏️ClientOperator)
+- config/ — params.ts, emitters.ts
+- functions/: navigate (3), target (все 19: session, complete, makeConnection, execute,
+  executeForce, emit, emitForce, notify, notifyForce, runStateless, runStatelessForce,
+  chat, ask, fork/scope, json, makeAutoDispose, disposeConnection, startPipeline),
+  common (все 11), history (все 7), event (3), other (2), alias (4),
+  commit — commitToolOutput построчно + все 18 сверены структурно (✏️commitUserMessage,
+  ✏️commitUserMessageForce), setup — addAgent построчно + 13 сверены структурно,
+  test — overrideAgent построчно + 13 сверены структурно, dump — getAgent построчно +
+  12 сверены структурно
+- template/ — все 4
+- events/ — listenAgentEvent{,Once} построчно, остальные 14 сверены (имя ↔ шина)
+- cli/ — все 7
+- lib/core/ — di.ts, types.ts, provide.ts (67 симв. = 67 provide, сверено)
+- lib/index.ts — полный агрегатор, сверен
+- lib/services/base/ — BusService, PerfService, LoggerService, AliveService,
+  DocService (✏️ полный построчный)
+- lib/services/context/ — все 4
+- lib/services/meta/ — оба
+- lib/services/schema/ — AgentSchemaService, NavigationSchemaService, ActionSchemaService,
+  MemorySchemaService построчно; остальные 12 — тот же ToolRegistry-шаблон (сверено
+  наличие validateShallow/register/override/get)
+- lib/services/connection/ — AgentConnectionService, ✏️MCPConnectionService,
+  StateConnectionService построчно; Session/Swarm/Storage/SharedStorage — ключевые
+  фабрики построчно; все dispose сверены на соответствие ключей memoize
+- lib/services/validation/ — Session, Execution, Navigation, Swarm построчно; у всех
+  остальных сверено, что memoized validate возвращает значение (критично для v4)
+- lib/services/public/ — SessionPublicService и делегирование всех 11 сверено по grep
+
+### Типы (проверены tsc, runtime-кода нет — подтверждено grep)
+- contract/ (6), model/ (7), interfaces/ (17), src/index.ts (реэкспорты)
+
+### Системные проверки
+- METHOD_NAME ↔ имя файла по всем functions/* (нашло баги №8, №9)
+- setup: addX → парные ValidationService.addX + SchemaService.register (все 13 ✓)
+- test: overrideX → validate + override (все 13 ✓)
+- dump: getX → свой SchemaService.get (все 12 ✓)
+- events: listenXEvent ↔ x-bus (все 16 ✓)
+- dispose connection-сервисов ↔ ключи memoize (нашло баг №7)
+- свип «обнулить ссылку до вызова» по всему src (нашло баг №3, других нет)
+- аудит queued/cancelable/memoize/ttl/SortedArray/LimitedSet под семантику functools-kit v4
+
+## Верификация
 - `npx tsc --noEmit` — чисто
 - `npm run build` — ок (types.d.ts перегенерирован)
-- `node ./test/index.mjs` — 42/42 после каждого исправления (5 прогонов суммарно)
+- `node ./test/index.mjs` — 42/42, два финальных прогона подряд

src/functions/commit/commitUserMessage.ts

@@ -3,7 +3,7 @@ import { GLOBAL_CONFIG } from "../../config/params";
 import swarm, { PayloadContextService } from "../../lib";
 import { ExecutionMode } from "../../interfaces/Session.interface";
 
-const METHOD_NAME = "function.commit.commitSystemMessage";
+const METHOD_NAME = "function.commit.commitUserMessage";
 
 /**
  * Function implementation

src/functions/commit/commitUserMessageForce.ts

@@ -3,7 +3,7 @@ import { GLOBAL_CONFIG } from "../../config/params";
 import swarm, { PayloadContextService } from "../../lib";
 import { ExecutionMode } from "../../interfaces/Session.interface";
 
-const METHOD_NAME = "function.commit.commitSystemMessage";
+const METHOD_NAME = "function.commit.commitUserMessageForce";
 
 /**
  * Function implementation

src/functions/event/event.ts

@@ -3,7 +3,7 @@ import swarm from "../../lib";
 import { GLOBAL_CONFIG } from "../../config/params";
 import beginContext from "../../utils/beginContext";
 
-const METHOD_NAME = "function.event.listenEvent";
+const METHOD_NAME = "function.event.event";
 
 /**
  * Set of reserved event source names that cannot be used for custom events.

src/lib/services/base/DocService.ts

@@ -876,7 +876,7 @@ export class DocService {
               {
                 result.push("");
                 result.push(
-                  `*Required:* [${fn.parameters.required.includes(key) ? "x" : " "
+                  `*Required:* [${fn.parameters.required?.includes(key) ? "x" : " "
                   }]`
                 );
               }

src/lib/services/connection/MCPConnectionService.ts

@@ -124,14 +124,15 @@ export class MCPConnectionService implements IMCP {
   public dispose = async (clientId: string) => {
     GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
       this.loggerService.info(`mcpConnectionService dispose`, { clientId });
-    const key = `${this.methodContextService.context.clientId}-${this.methodContextService.context.agentName}`;
+    const key = `${this.methodContextService.context.mcpName}`;
     if (!this.getMCP.has(key)) {
       return;
     }
+    // The ClientMCP instance is shared across clients (memoized by mcpName),
+    // so only the client-scoped resources are released; the instance stays cached.
     await this.getMCP(this.methodContextService.context.mcpName).dispose(
       clientId
     );
-    this.getMCP.clear(clientId);
   };
 }