team-chat 0.0.0-stage → 0.3.0

package/server/dist/src/mcp/chat-tools.js

@@ -0,0 +1,282 @@
+"use strict";
+// Инструменты MCP — те же сервисы, что у HTTP: правило живёт в одном месте. Имена,
+// описания и аргументы — как были у PHP-сервера (laravel/mcp): агенты на них опираются.
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatTools = void 0;
+const common_1 = require("@nestjs/common");
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const drizzle_orm_1 = require("drizzle-orm");
+const node_fs_1 = __importDefault(require("node:fs"));
+const zod_1 = require("zod");
+const attachment_store_1 = require("../attachments/attachment-store");
+const chats_service_1 = require("../chats/chats.service");
+const database_module_1 = require("../db/database.module");
+const schema_1 = require("../db/schema");
+const decisions_service_1 = require("../decisions/decisions.service");
+const documents_service_1 = require("../documents/documents.service");
+const knowledge_service_1 = require("../knowledge/knowledge.service");
+const mentions_service_1 = require("../mentions/mentions.service");
+const message_presenter_1 = require("../messages/message.presenter");
+const messages_service_1 = require("../messages/messages.service");
+const directory_service_1 = require("../participants/directory.service");
+const participants_service_1 = require("../participants/participants.service");
+const INSTRUCTIONS = `Командный чат: владелец и агенты обсуждают работу. Чатов несколько — по одному
+на проект (list-chats). У каждого свой тред, журнал решений и документы, поэтому
+инструментам передавай chat — slug чата из задания. Отвечая с reply_to_id, chat
+можно не указывать: ответ уходит в чат вопроса.
+
+Две сущности, и путать их не следует:
+  * ТРЕД — разговор. Здесь можно сомневаться, спорить и передумывать.
+  * ЖУРНАЛ РЕШЕНИЙ — только утверждённое владельцем. Правке не подлежит: решение
+    отменяется выпуском нового. Фиксировать решения может ТОЛЬКО владелец,
+    поэтому инструмента для этого здесь нет — предлагай сообщением в треде.
+
+С чего начинать: read_thread отдаёт журнал решений целиком (он маленький и
+авторитетный) плюс окно последних сообщений. Всю историю тащить не нужно —
+за старым иди в search_thread.
+
+ДОКУМЕНТЫ проекта (планы, аудиты, хендоффы, отчёты) живут здесь же, а не в
+репозиториях: list-documents, read-document, write-document. В репозиториях остаётся
+только то, что читает машина (CLAUDE.md, AGENTS.md) и что описывает код. Смотри на
+status документа: current — актуально, draft — не подтверждено, archived — протухло.
+
+ОПЫТ КОМАНДЫ — уроки прошлых запусков агентов: в чём была причина, что сработало,
+где был тупик. Берёшься за задачу, похожую на уже решённую, — find-knowledge.
+
+Отвечать положено, когда тебя упомянули: pending_mentions покажет адресованное
+тебе. После опубликованного ответа подтверди обращение через acknowledge_mention,
+иначе оно останется висеть.`;
+const CHAT_ARG = 'Slug чата-проекта — из задания или list-chats. У каждого проекта свой тред, журнал решений и документы.';
+/** Ошибка инструмента: агент видит её текстом и сам решает, что делать дальше. */
+class ToolError extends Error {
+}
+const json = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data) }] });
+const text = (value) => ({ content: [{ type: 'text', text: value }] });
+/**
+ * Сервер MCP для одного участника — на каждый запрос свой: инструменты действуют от
+ * имени того, чей токен пришёл. Решения фиксировать нечем — так задумано: это право
+ * владельца, и надёжнее отсутствие инструмента, чем запрет в его описании.
+ */
+let ChatTools = class ChatTools {
+    db;
+    chats;
+    messages;
+    mentions;
+    decisions;
+    documents;
+    knowledge;
+    attachments;
+    presenter;
+    directories;
+    constructor(db, chats, messages, mentions, decisions, documents, knowledge, attachments, presenter, directories) {
+        this.db = db;
+        this.chats = chats;
+        this.messages = messages;
+        this.mentions = mentions;
+        this.decisions = decisions;
+        this.documents = documents;
+        this.knowledge = knowledge;
+        this.attachments = attachments;
+        this.presenter = presenter;
+        this.directories = directories;
+    }
+    serverFor(me) {
+        const server = new mcp_js_1.McpServer({ name: 'Team Chat', version: '1.0.0' }, { instructions: INSTRUCTIONS });
+        // Типы SDK выводят обработчик из схемы каждого инструмента; общей обёртке это не по силам,
+        // поэтому регистрация — через упрощённую сигнатуру. Аргументы проверяет сам SDK по схеме.
+        const register = server.registerTool.bind(server);
+        const tool = (name, title, description, inputSchema, handler) => register(name, { title, description, inputSchema }, args => guarded(() => handler(args)));
+        tool('list-chats', 'List Chats', 'Чаты-проекты: slug, название, описание проекта и каталог с его кодом. У каждого чата свой тред, '
+            + 'журнал решений и документы — остальным инструментам передавай chat.', {}, async () => json({ chats: (await this.chats.all()).map(chats_service_1.chatApi) }));
+        tool('read-thread', 'Read Thread', 'Ввести себя в курс дела: журнал решений целиком плюс окно последних сообщений треда и список '
+            + 'участников. С этого начинают, прежде чем отвечать.', {
+            chat: zod_1.z.string().optional().describe(CHAT_ARG),
+            limit: zod_1.z.number().int().optional().describe('Сколько последних сообщений вернуть (1–200, по умолчанию 50).'),
+        }, async ({ chat: slug, limit }) => {
+            const chat = await this.resolveChat(slug);
+            const [members, directory] = await Promise.all([
+                this.db.select().from(schema_1.participants).where((0, drizzle_orm_1.ne)(schema_1.participants.kind, participants_service_1.KIND_HOST)).orderBy((0, drizzle_orm_1.asc)(schema_1.participants.id)),
+                this.directories.load(),
+            ]);
+            return json({
+                chat: (0, chats_service_1.chatApi)(chat),
+                you: me.handle,
+                participants: members.map(p => ({ handle: p.handle, name: p.name, role: directory.roleIn(p, chat.id), disabled: p.disabledAt !== null })),
+                decisions: await this.decisions.list(chat),
+                messages: await this.messages.window(chat, Math.max(1, Math.min(200, limit || 50))),
+            });
+        });
+        tool('post-message', 'Post Message', 'Написать в тред. Упоминание @handle адресует сообщение участнику: @claude, @codex, @javlon или @all. '
+            + 'Упоминай, только если действительно нужен ответ.', {
+            chat: zod_1.z.string().optional().describe('Slug чата-проекта. Отвечая с reply_to_id, можно не указывать — возьмётся чат вопроса.'),
+            body: zod_1.z.string().describe('Текст сообщения.'),
+            reply_to_id: zod_1.z.number().int().optional().describe('Id сообщения, на которое отвечаешь. Отвечая на обращение, указывай его обязательно.'),
+            ask_owner: zod_1.z.boolean().optional().describe('true — в сообщении вопрос владельцу, без ответа на который работа не продолжится. Попадёт в список '
+                + '«Нужен ответ владельца» и будет висеть, пока владелец не ответит именно на это сообщение. Упоминание '
+                + '@javlon в тексте такой пометки не заменяет. Не ставь для отчётов, предложений и риторических вопросов.'),
+        }, async ({ chat: slug, body, reply_to_id, ask_owner }) => {
+            // Ответ живёт в чате вопроса — chat тогда можно не указывать. Указан и не совпадает —
+            // это ошибка агента, а не повод писать в чужой проект.
+            const question = reply_to_id === undefined ? null : await this.message(reply_to_id);
+            const chat = question && !slug ? await this.chatById(question.chatId) : await this.resolveChat(slug);
+            if (question && question.chatId !== chat.id) {
+                const questionChat = await this.chatById(question.chatId);
+                throw new ToolError(`Сообщение #${question.id} — в чате «${questionChat.slug}», а не «${chat.slug}». Отвечай в чате вопроса.`);
+            }
+            const message = await this.messages.publish(chat, me, { body, reply_to_id, ask_owner });
+            return json(await this.presenter.presentOne(message));
+        });
+        tool('list-decisions', 'List Decisions', 'Журнал принятых решений. Это авторитетная память проекта: решения неизменяемы, отменённое помечено '
+            + 'флагом superseded. Не спорь с зафиксированным — если не согласен, предложи в треде выпустить новое '
+            + 'решение взамен старого.', { chat: zod_1.z.string().optional().describe(CHAT_ARG) }, async ({ chat: slug }) => json({
+            decisions: await this.decisions.list(await this.resolveChat(slug)),
+            note: 'Фиксировать решения может только владелец.',
+        }));
+        tool('search-thread', 'Search Thread', 'Поиск по треду. Нужен, чтобы достать старое обсуждение, не затаскивая в контекст всю историю ради пары фактов.', {
+            chat: zod_1.z.string().optional().describe(CHAT_ARG),
+            query: zod_1.z.string().min(2).describe('Подстрока для поиска по тексту сообщений.'),
+        }, async ({ chat: slug, query }) => {
+            const found = await this.messages.search(await this.resolveChat(slug), { q: query }, 50);
+            return json({ count: found.length, messages: found });
+        });
+        tool('pending-mentions', 'Pending Mentions', 'Обращения, адресованные лично тебе и пока не обработанные. Чтение обращение НЕ гасит — после '
+            + 'опубликованного ответа подтверди его acknowledge_mention.', {}, async () => {
+            const open = await this.mentions.openFor(me, 50);
+            return json({ count: open.length, mentions: open });
+        });
+        tool('acknowledge-mention', 'Acknowledge Mention', 'Подтвердить, что обращение обработано. Вызывать ТОЛЬКО после того, как ответ действительно '
+            + 'опубликован в треде: иначе вопрос исчезнет из очереди без ответа.', { mention_id: zod_1.z.number().int().describe('Id обращения из pending_mentions.') }, async ({ mention_id }) => json(await this.mentions.acknowledge(me, mention_id)));
+        tool('list-documents', 'List Documents', 'Документы проекта: планы, аудиты, хендоффы, отчёты. Тела не отдаёт — только список, чтобы не тащить '
+            + 'в контекст лишнее. Смотри на status: current — актуально, draft — не подтверждено, archived — '
+            + 'протухло, ссылаться нельзя.', {
+            chat: zod_1.z.string().optional().describe(CHAT_ARG),
+            status: zod_1.z.enum(documents_service_1.STATUSES).optional().describe('Фильтр по состоянию: draft, current, archived.'),
+            kind: zod_1.z.enum(documents_service_1.KINDS).optional().describe('Фильтр по типу: plan, audit, handoff, report, reference.'),
+        }, async ({ chat: slug, status, kind }) => {
+            const documents = await this.documents.list(await this.resolveChat(slug), { status, kind });
+            return json({ count: documents.length, documents });
+        });
+        tool('read-document', 'Read Document', 'Прочитать документ целиком по slug из list-documents.', {
+            chat: zod_1.z.string().optional().describe(CHAT_ARG),
+            slug: zod_1.z.string().describe('Идентификатор документа.'),
+        }, async ({ chat: slug, slug: document }) => {
+            const found = await this.documents.read(await this.resolveChat(slug), document);
+            if (!found)
+                throw new ToolError(`Документа «${document}» нет. Список — в list-documents.`);
+            return json(found);
+        });
+        tool('read-attachment', 'Read Attachment', 'Открыть файл, приложенный к сообщению: id — из поля attachments сообщения. Картинку вернёт '
+            + 'изображением, небольшой текстовый файл — текстом. Остальное (PDF, архивы, таблицы) скачивается '
+            + 'по url из attachments с твоим токеном: curl -H "Authorization: Bearer $CHAT_TOKEN" -o <файл> <url>.', { id: zod_1.z.number().int().describe('Id вложения из поля attachments сообщения.') }, async ({ id }) => {
+            const attachment = await this.attachments.find(id);
+            if (!attachment)
+                throw new ToolError(`Вложения #${id} нет.`);
+            const file = this.attachments.absolute(attachment);
+            if ((0, attachment_store_1.isImage)(attachment)) {
+                return { content: [{ type: 'image', data: node_fs_1.default.readFileSync(file).toString('base64'), mimeType: attachment.mime }] };
+            }
+            if ((0, attachment_store_1.isText)(attachment))
+                return text(node_fs_1.default.readFileSync(file, 'utf8'));
+            const url = this.presenter.attachmentApi(attachment).url;
+            return text(`«${attachment.name}» (${attachment.mime}, ${attachment.size} байт) напрямую не читается. `
+                + `Скачай: curl -H "Authorization: Bearer $CHAT_TOKEN" -o '${attachment.name}' ${url}`);
+        });
+        tool('write-document', 'Write Document', 'Создать документ или добавить новую редакцию существующему. Прошлые редакции не переписываются — '
+            + 'они остаются в истории. Статус current ставит только владелец: агент пишет черновик, актуальность '
+            + 'подтверждает человек.', {
+            chat: zod_1.z.string().optional().describe(CHAT_ARG),
+            slug: zod_1.z.string().describe('Идентификатор; существующий — добавит редакцию.'),
+            title: zod_1.z.string().describe('Заголовок.'),
+            body: zod_1.z.string().describe('Текст документа (markdown).'),
+            kind: zod_1.z.enum(documents_service_1.KINDS).describe('Тип документа.'),
+            status: zod_1.z.enum(documents_service_1.STATUSES).optional().describe('По умолчанию draft.'),
+            note: zod_1.z.string().optional().describe('Чем вызвана правка.'),
+            path: zod_1.z.string().optional().describe('Путь в репозитории для выгрузки, напр. qurbuz-backend/docs/plan.md. Выгружаются только документы со статусом current.'),
+        }, async ({ chat: slug, ...document }) => json(await this.documents.writeFromAgent(await this.resolveChat(slug), me, document)));
+        tool('find-knowledge', 'Find Knowledge', 'Опыт команды: уроки прошлых запусков агентов, похожие на запрос, — симптом, причина, что сработало, '
+            + 'тупики и правило. Ищет по всем проектам (урок обобщён), уроки своего проекта выше. Опиши задачу или '
+            + 'ошибку словами — поиск по словам, не по смыслу. Урок — подсказка: сверь его с задачей.', {
+            query: zod_1.z.string().min(2).describe('Задача, симптом или ошибка — словами, можно с названиями технологий.'),
+            chat: zod_1.z.string().optional().describe('Slug чата-проекта: его уроки поднимутся выше.'),
+            category: zod_1.z.string().optional().describe(`Только уроки этого типа задач: ${knowledge_service_1.CATEGORIES}.`),
+            limit: zod_1.z.number().int().optional().describe('Сколько уроков вернуть (1–20, по умолчанию 5).'),
+        }, async ({ query, chat: slug, category, limit }) => {
+            const chat = slug ? await this.resolveChat(slug) : undefined;
+            const lessons = await this.knowledge.search(query, { chat, limit: limit ?? 5, category });
+            return json({ count: lessons.length, lessons });
+        });
+        return server;
+    }
+    /**
+     * Чат из аргумента. Без него — единственный чат, пока он один. Когда чатов несколько,
+     * молча подставить первый нельзя: агент ответил бы в чужой проект и решил бы, что всё
+     * в порядке. Лучше ошибка со списком.
+     */
+    async resolveChat(slug) {
+        const all = await this.chats.all();
+        const list = () => all.map(c => `${c.slug} (${c.name})`).join(', ');
+        if (slug) {
+            const chat = all.find(c => c.slug === slug);
+            if (!chat)
+                throw new ToolError(`Чата «${slug}» нет. Есть: ${list()}.`);
+            return chat;
+        }
+        if (all.length === 1)
+            return all[0];
+        throw new ToolError(`Чатов несколько — укажи chat (slug чата из задания). Есть: ${list()}.`);
+    }
+    async message(id) {
+        const [row] = await this.db.select().from(schema_1.messages).where((0, drizzle_orm_1.eq)(schema_1.messages.id, id));
+        if (!row)
+            throw new ToolError(`Сообщения #${id} нет.`);
+        return row;
+    }
+    async chatById(id) {
+        return (await this.chats.all()).find(c => c.id === id);
+    }
+};
+exports.ChatTools = ChatTools;
+exports.ChatTools = ChatTools = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(database_module_1.DATABASE)),
+    __metadata("design:paramtypes", [Object, chats_service_1.ChatsService,
+        messages_service_1.MessagesService,
+        mentions_service_1.MentionsService,
+        decisions_service_1.DecisionsService,
+        documents_service_1.DocumentsService,
+        knowledge_service_1.KnowledgeService,
+        attachment_store_1.AttachmentStore,
+        message_presenter_1.MessagePresenter,
+        directory_service_1.DirectoryService])
+], ChatTools);
+/** Ошибки правил (нет прав, неверные данные) — ответом инструмента с isError, а не сбоем протокола. */
+async function guarded(run) {
+    try {
+        return await run();
+    }
+    catch (e) {
+        if (e instanceof ToolError)
+            return { isError: true, content: [{ type: 'text', text: e.message }] };
+        if (e instanceof common_1.HttpException) {
+            const response = e.getResponse();
+            const message = typeof response === 'string' ? response : response.message ?? e.message;
+            return { isError: true, content: [{ type: 'text', text: message }] };
+        }
+        throw e;
+    }
+}

package/server/dist/src/mcp/mcp.controller.js

@@ -0,0 +1,58 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpController = void 0;
+const common_1 = require("@nestjs/common");
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+const participant_guard_1 = require("../auth/participant.guard");
+const chat_tools_1 = require("./chat-tools");
+/**
+ * MCP-сервер чата — тем же входом, что и HTTP API: адрес плюс токен.
+ *
+ *   claude mcp add --transport http qbazar-chat http://localhost:8600/mcp --header "Authorization: Bearer <токен>"
+ *   codex  mcp add qbazar-chat --url http://localhost:8600/mcp --bearer-token-env-var QBAZAR_CHAT_TOKEN
+ *
+ * Без сессий: каждый запрос самодостаточен, ответ — обычный JSON, как у PHP-сервера.
+ */
+let McpController = class McpController {
+    tools;
+    constructor(tools) {
+        this.tools = tools;
+    }
+    async handle(me, req, res) {
+        const server = this.tools.serverFor(me);
+        const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+        res.on('close', () => {
+            void transport.close();
+            void server.close();
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+    }
+};
+exports.McpController = McpController;
+__decorate([
+    (0, common_1.All)(),
+    __param(0, (0, participant_guard_1.Me)()),
+    __param(1, (0, common_1.Req)()),
+    __param(2, (0, common_1.Res)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object, Object]),
+    __metadata("design:returntype", Promise)
+], McpController.prototype, "handle", null);
+exports.McpController = McpController = __decorate([
+    (0, common_1.Controller)('mcp'),
+    (0, common_1.UseGuards)(participant_guard_1.ParticipantGuard),
+    __metadata("design:paramtypes", [chat_tools_1.ChatTools])
+], McpController);

package/server/dist/src/mcp/mcp.module.js

@@ -0,0 +1,24 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpModule = void 0;
+const common_1 = require("@nestjs/common");
+const conversation_module_1 = require("../conversation.module");
+const knowledge_module_1 = require("../knowledge/knowledge.module");
+const chat_tools_1 = require("./chat-tools");
+const mcp_controller_1 = require("./mcp.controller");
+let McpModule = class McpModule {
+};
+exports.McpModule = McpModule;
+exports.McpModule = McpModule = __decorate([
+    (0, common_1.Module)({
+        imports: [conversation_module_1.ConversationModule, knowledge_module_1.KnowledgeModule],
+        providers: [chat_tools_1.ChatTools],
+        controllers: [mcp_controller_1.McpController],
+    })
+], McpModule);

package/server/dist/src/mentions/mention-state.js

@@ -0,0 +1,80 @@
+"use strict";
+// Состояние обработки обращения — выводится из фактов при каждом чтении и нигде не
+// хранится готовой надписью. Иначе упавший мост оставил бы «работает» навсегда, то есть
+// соврал бы ровно тогда, когда правда нужнее всего.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BEAT_TTL = exports.REPORTS = void 0;
+exports.beatFresh = beatFresh;
+exports.stateOf = stateOf;
+exports.stateSince = stateSince;
+exports.beat = beat;
+exports.finish = finish;
+/**
+ * Чем мост отчитывается. «working» продлевает сигнал жизни, остальное — исходы и отказ
+ * запускать по бюджету. «Ответ опубликован» сюда не входит намеренно: его нельзя
+ * сообщить, он проверяется по наличию ответа в треде.
+ */
+exports.REPORTS = ['working', 'done', 'failed', 'deferred', 'paused'];
+/**
+ * Сколько сигнал жизни свеж без продления. Мост продлевает его втрое чаще: один
+ * пропущенный удар индикатор не гасит, упавший мост гаснет через полторы минуты.
+ */
+exports.BEAT_TTL = 90;
+function beatFresh(m, at) {
+    return m.beatAt !== null && m.beatAt.getTime() + (m.beatTtl ?? exports.BEAT_TTL) * 1000 > at.getTime();
+}
+/**
+ * Порядок проверок — и есть смысл:
+ *   1. есть ответ → «опубликован», чем бы ни кончился процесс;
+ *   2. мост доложил исход (или паузу) → его, а не догадку; снимает исход только новый запуск;
+ *   3. сигнал свежий → «работает»;
+ *   4. запуск был, сигнала нет → «нет подтверждения активности»;
+ *   5. иначе → «ожидает запуска».
+ */
+function stateOf(m, reply, at) {
+    if (reply)
+        return 'answered';
+    if (m.outcome !== null) {
+        return m.outcome === 'failed' || m.outcome === 'deferred' || m.outcome === 'paused' ? m.outcome : 'finished';
+    }
+    if (beatFresh(m, at))
+        return 'working';
+    return m.runStartedAt !== null ? 'stalled' : 'queued';
+}
+/** С какого момента идёт ТЕКУЩЕЕ состояние: «ожидает 3 мин» и «работает 3 мин» отсчитываются от разного. */
+function stateSince(m, state, reply) {
+    switch (state) {
+        case 'answered': return reply?.createdAt ?? null;
+        case 'working': return m.runStartedAt;
+        case 'stalled': return m.beatAt;
+        case 'queued': return m.createdAt;
+        default: return m.outcomeAt ?? m.createdAt;
+    }
+}
+/**
+ * Сигнал жизни. Повторный — продление, а не новый запуск: иначе «работает 4 минуты»
+ * не выросло бы больше нуля. Удар после исхода или после протухшего сигнала — уже
+ * СЛЕДУЮЩИЙ запуск: время начала заново, попытка засчитывается.
+ */
+function beat(m, note, ttl, at) {
+    const continues = m.outcome === null && beatFresh(m, at);
+    return {
+        runStartedAt: continues ? m.runStartedAt : at,
+        attempts: continues ? m.attempts : m.attempts + 1,
+        beatAt: at,
+        beatTtl: Math.max(5, Math.min(3600, ttl)),
+        outcome: null,
+        outcomeAt: null,
+        note,
+    };
+}
+/**
+ * Исход запуска — «кончился», а не «ответил»: ответ проверяется отдельно. Тот же исход
+ * повторно — не новое событие: мост напоминает об отложенном каждый проход, и «отложено
+ * 5 с назад» вечно врало бы о сроке.
+ */
+function finish(m, outcome, note, at) {
+    if (m.outcome === outcome)
+        return null;
+    return { outcome, outcomeAt: at, note };
+}

package/server/dist/src/mentions/mentions.controller.js

@@ -0,0 +1,100 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MentionsController = void 0;
+const common_1 = require("@nestjs/common");
+const participant_guard_1 = require("../auth/participant.guard");
+const chats_service_1 = require("../chats/chats.service");
+const clock_1 = require("../common/clock");
+const format_1 = require("../common/format");
+const http_1 = require("../common/http");
+const messages_service_1 = require("../messages/messages.service");
+const mentions_service_1 = require("./mentions.service");
+/** Адресация: кто должен ответить, и ход обработки — от моста. */
+let MentionsController = class MentionsController {
+    chats;
+    mentions;
+    messages;
+    constructor(chats, mentions, messages) {
+        this.chats = chats;
+        this.mentions = mentions;
+        this.messages = messages;
+    }
+    /**
+     * Необработанные обращения ко мне — по всем чатам сразу: мост у агента один. Чтение
+     * обращение НЕ гасит: агент, упавший между запросом и ответом, иначе потерял бы вопрос.
+     */
+    async mine(me, limit) {
+        const mentions = await this.mentions.openFor(me, (0, http_1.limitFrom)(limit));
+        return { mentions, count: mentions.length, server_time: (0, format_1.iso)((0, clock_1.now)()) };
+    }
+    handled(me, mentionId) {
+        return this.mentions.acknowledge(me, mentionId);
+    }
+    /** Что открыто. Без чата в адресе — по всем чатам: «что открыто вообще». */
+    async activity(slug) {
+        const chat = slug ? await this.chats.bySlug(slug) : null;
+        return this.openItems(chat?.slug);
+    }
+    /** Отчёт моста: working продлевает сигнал жизни, остальное — исходы и пауза. */
+    async beacon(me, body) {
+        await this.mentions.report(me, body);
+        return this.openItems();
+    }
+    async openItems(chatSlug) {
+        const [activity, ownerWait] = await Promise.all([this.mentions.snapshot(chatSlug), this.messages.awaitingOwner(chatSlug)]);
+        return { activity, owner_wait: ownerWait, server_time: (0, format_1.iso)((0, clock_1.now)()) };
+    }
+};
+exports.MentionsController = MentionsController;
+__decorate([
+    (0, common_1.Get)('mentions'),
+    __param(0, (0, participant_guard_1.Me)()),
+    __param(1, (0, common_1.Query)('limit')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, String]),
+    __metadata("design:returntype", Promise)
+], MentionsController.prototype, "mine", null);
+__decorate([
+    (0, common_1.Post)('mentions/:mention/handled'),
+    (0, common_1.HttpCode)(200),
+    __param(0, (0, participant_guard_1.Me)()),
+    __param(1, (0, common_1.Param)('mention', common_1.ParseIntPipe)),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Number]),
+    __metadata("design:returntype", void 0)
+], MentionsController.prototype, "handled", null);
+__decorate([
+    (0, common_1.Get)(['activity', 'chats/:chat/activity']),
+    __param(0, (0, common_1.Param)('chat')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], MentionsController.prototype, "activity", null);
+__decorate([
+    (0, common_1.Post)('activity'),
+    (0, common_1.HttpCode)(200),
+    __param(0, (0, participant_guard_1.Me)()),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], MentionsController.prototype, "beacon", null);
+exports.MentionsController = MentionsController = __decorate([
+    (0, common_1.Controller)('api'),
+    (0, common_1.UseGuards)(participant_guard_1.ParticipantGuard),
+    __metadata("design:paramtypes", [chats_service_1.ChatsService,
+        mentions_service_1.MentionsService,
+        messages_service_1.MessagesService])
+], MentionsController);