team-chat 0.0.0-stage → 0.3.0

package/host/bridge/bridge.js

@@ -0,0 +1,326 @@
+// Мост «чат → агент».
+//
+// Сам мост модель НИКОГДА не вызывает: он опрашивает обращения обычным HTTP и запускает
+// агента, только когда обращение есть, — холостая проверка не стоит ни токена.
+//
+// Три свойства, ради которых он существует:
+//   * обращение гасится не чтением, а подтверждением после опубликованного ответа;
+//   * ответ привязан к КОНКРЕТНОМУ обращению (reply_to_id): два вопроса подряд не схлопнутся;
+//   * текст чужого сообщения уходит агенту через stdin, а не подстановкой в команду.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { buildCard } from '../knowledge/card.js';
+import { distillLesson } from '../knowledge/lesson.js';
+import { compactTranscript } from '../knowledge/transcript.js';
+import { ChatApi } from '../lib/chat-api.js';
+import { splitWords } from '../lib/shell-words.js';
+import { AttemptStore } from './attempts.js';
+import { KnowledgeOutbox } from './knowledge-outbox.js';
+import { AgentLauncher } from './launcher.js';
+import { Beacon, ProgressReporter } from './progress.js';
+import { buildPrompt } from './prompt.js';
+import { RunArchive } from './run-archive.js';
+import { Thread } from './thread.js';
+import { deferredNote, triage, triageRules } from './triage.js';
+import { resolveAgentCwd } from './workdir.js';
+
+export class Bridge {
+  #config;
+  #api;
+  #thread;
+  #launcher;
+  #archive;
+  #outbox;
+  /** Работа после ответа: урок, отправка карточки. Ответ её не ждёт. */
+  #background = new Set();
+  #reporter;
+  #rules;
+  #log;
+  #print;
+
+  /**
+   * @param {object} deps
+   * @param {ReturnType<import('./config.js').bridgeConfig>} deps.config
+   * @param {ChatApi} deps.api
+   * @param {Thread} deps.thread
+   * @param {AgentLauncher} deps.launcher
+   * @param {RunArchive} deps.archive записи запусков
+   * @param {KnowledgeOutbox} deps.outbox карточки опыта по дороге в чат
+   * @param {ProgressReporter} deps.reporter
+   * @param {(...parts: any[]) => void} deps.log журнал моста
+   * @param {(text: string) => void} deps.print вывод для человека (--dry-run)
+   */
+  constructor({ config, api, thread, launcher, archive, outbox, reporter, log, print }) {
+    this.#config = config;
+    this.#api = api;
+    this.#thread = thread;
+    this.#launcher = launcher;
+    this.#archive = archive;
+    this.#outbox = outbox;
+    this.#reporter = reporter;
+    this.#rules = triageRules(config);
+    this.#log = log;
+    this.#print = print;
+  }
+
+  /**
+   * Один проход: разобрать открытые обращения и запустить агента — по разу на чат.
+   * @returns {Promise<number>} сколько обращений ушло агенту
+   */
+  async cycle({ dryRun = false } = {}) {
+    const mentions = await this.#api.mentions();
+    await this.#outbox.flush(); // чат отвечает — заодно дослать карточки, которые до него не дошли
+    if (mentions.length === 0) return 0;
+
+    const attempts = AttemptStore.load(this.#config.stateFile);
+    const context = {
+      attempts,
+      answered: message => this.#thread.answered(message),
+      // Бюджет считается лениво и один раз на чат за проход: на обращениях владельца он не нужен.
+      turnsInChat: memoize(chat => this.#thread.agentTurnsSinceOwner(chat)),
+    };
+
+    const toRun = [];
+    for (const mention of mentions) {
+      const verdict = await triage(mention, this.#rules, context);
+      if (verdict.kind === 'run') toRun.push(mention);
+      else await this.#apply(verdict, mention, attempts);
+    }
+
+    if (toRun.length) {
+      const groups = groupByChat(toRun);
+      const chats = [...groups.keys()].some(Boolean) ? await this.#chatSettings() : new Map();
+      for (const [slug, group] of groups) {
+        await this.#runGroup(group, chats.get(slug) ?? null, attempts, dryRun);
+      }
+    }
+
+    attempts.save();
+    return toRun.length;
+  }
+
+  async #apply(verdict, mention, attempts) {
+    if (verdict.kind === 'acknowledge') {
+      await this.#api.acknowledge(mention.id);
+      if (verdict.forget) attempts.forget(mention.id);
+      this.#log(`обращение #${mention.id}: ${verdict.reason}`);
+      return;
+    }
+    await this.#reporter.report([mention.id], verdict.state, { note: verdict.note });
+    if (verdict.reason) this.#log(`обращение #${mention.id}: ${verdict.reason}`);
+  }
+
+  /** Один запуск агента на все обращения одного чата: у каждого проекта свой контекст и каталог. */
+  async #runGroup(mentions, chat, attempts, dryRun) {
+    const ids = mentions.map(m => `#${m.message.id}`).join(', ');
+    this.#log(`обращений к обработке${chat ? ` в чате ${chat.slug}` : ''}: ${mentions.length} (${ids})`);
+
+    const prompt = this.#prompt(mentions, chat, await this.#experience(mentions));
+    if (dryRun) {
+      this.#log('--dry-run: агент не запускается, промпт ниже');
+      this.#print(`----- промпт -----\n${prompt}\n------------------`);
+      return;
+    }
+
+    const beacon = new Beacon(this.#reporter, {
+      mentionIds: mentions.map(m => m.id),
+      note: `работает над ${ids}`,
+      ttl: this.#config.beaconTtl,
+      intervalMs: this.#config.beaconIntervalMs,
+    });
+    const cwd = resolveAgentCwd(chat, this.#config, this.#log);
+    const record = this.#archive.begin({
+      handle: this.#config.handle,
+      runtime: this.#config.runtime,
+      executable: splitWords(this.#config.agentCommand)[0] ?? '',
+      chat,
+      mentions,
+      prompt,
+      cwd,
+    });
+
+    let code;
+    try {
+      code = await this.#launcher.run(prompt, { cwd, output: record.output, onStart: () => beacon.start() });
+    } finally {
+      await beacon.stop();
+    }
+    record.finish(code);
+
+    const outcome = outcomeOf(code);
+    try {
+      for (const mention of mentions) record.settle(mention.id, await this.#settle(mention, outcome, attempts));
+    } finally {
+      record.save();
+    }
+    this.#keepExperience(record, cwd, mentions.map(m => m.message.body));
+  }
+
+  /** Дождаться работы в фоне — уроков и отправки карточек: для тестов и чистой остановки. */
+  async settled() {
+    // Урок, дописавшись, сам отправляет карточку — новая работа появляется, пока ждём старую.
+    while (this.#background.size) await Promise.allSettled([...this.#background]);
+  }
+
+  /**
+   * Карточка опыта по запуску: факты — сразу, урок от нейросети — в фоне, чтобы следующее
+   * обращение его не ждало. Обе версии уходят в базу знаний чата. Сбой здесь не задевает
+   * ответ: ответ уже в треде и подтверждён, а карточка — польза на будущее.
+   */
+  #keepExperience(record, cwd, questions) {
+    let card;
+    let output;
+    try {
+      output = fs.readFileSync(record.output.stdout, 'utf8');
+      card = buildCard({ run: record.data, output, workdir: cwd ?? process.cwd() });
+      record.attachCard(card);
+    } catch (e) {
+      return this.#log(`карточка опыта не собралась: ${e.message}`);
+    }
+    this.#share(record);
+    if (!this.#config.distillCommand || !worthALesson(card)) return;
+
+    this.#inBackground(distillLesson(this.#config.distillCommand, compactTranscript(card.process.engine, output, questions), { cwd: os.tmpdir() })
+      .then(found => {
+        if (!found) return this.#log('урок: обобщать нечего');
+        record.attachCard({ ...card, ...found });
+        this.#share(record);
+        this.#log(`урок записан: ${found.solution.rule}`);
+      })
+      .catch(e => this.#log(`урок не получился: ${e.message}`)));
+  }
+
+  /** Карточку — в базу знаний чата. Сервер старше нескольких чатов её не примет — не шлём. */
+  #share(record) {
+    const chat = record.data.chat?.slug;
+    if (chat) this.#inBackground(this.#outbox.send({ chat, key: record.key, file: record.cardFile }));
+  }
+
+  #inBackground(promise) {
+    this.#background.add(promise);
+    promise.finally(() => this.#background.delete(promise));
+  }
+
+  /**
+   * Уроки прошлых запусков, похожие на эти обращения, — в задание. Не достали — работаем
+   * без них: ответить без подсказки лучше, чем не ответить.
+   */
+  async #experience(mentions) {
+    const chat = mentions[0].message.chat?.slug;
+    if (!chat) return [];
+    try {
+      return await this.#api.knowledge(chat, mentions.map(m => m.message.body).join('\n'), { limit: 3 });
+    } catch (e) {
+      this.#log(`опыт команды недоступен (${e.message}) — запускаю без него`);
+      return [];
+    }
+  }
+
+  /**
+   * Закрывает обращение только ответ на НЕГО, а не код возврата: нулевой код не значит,
+   * что ответ дошёл до треда, ненулевой — что не дошёл.
+   *
+   * @returns {Promise<{outcome: string, attempt: number, answerMessageId?: number}>} для записи запуска
+   */
+  async #settle(mention, outcome, attempts) {
+    const id = mention.id;
+    const answer = await this.#thread.answerTo(mention.message);
+    if (answer) {
+      const attempt = attempts.count(id) + 1;
+      await this.#api.acknowledge(id);
+      attempts.forget(id);
+      this.#log(`обращение #${id} подтверждено`);
+      return { outcome: 'answered', attempt, answerMessageId: answer.id };
+    }
+
+    const { maxAttempts, stateFile } = this.#config;
+    const count = attempts.fail(id);
+    if (count >= maxAttempts) {
+      this.#log(`обращение #${id}: ${count} неудач подряд — откладываю. `
+        + `Разобраться и снять: удалить ключ из ${path.basename(stateFile)}`);
+      await this.#reporter.report([id], 'deferred', { note: deferredNote(count, maxAttempts, outcome.note) });
+      return { outcome: 'deferred', attempt: count };
+    }
+    this.#log(`обращение #${id}: ответа нет, попытка ${count} из ${maxAttempts}`);
+    await this.#reporter.report([id], outcome.state, { note: `${outcome.note}; попытка ${count} из ${maxAttempts}` });
+    return { outcome: outcome.state, attempt: count };
+  }
+
+  #prompt(mentions, chat, experience) {
+    const { handle, mcpName, rulesFile, runtimeNotesFile } = this.#config;
+    return buildPrompt({
+      mentions,
+      chat,
+      handle,
+      mcpName,
+      experience,
+      rules: fs.readFileSync(rulesFile, 'utf8'),
+      runtimeNotes: runtimeNotesFile && fs.existsSync(runtimeNotesFile) ? fs.readFileSync(runtimeNotesFile, 'utf8') : '',
+    });
+  }
+
+  /**
+   * Настройки чатов: название, описание проекта, каталог, команда. Не достали — работаем
+   * без них: ответить без описания проекта лучше, чем не ответить вовсе.
+   */
+  async #chatSettings() {
+    try {
+      return new Map((await this.#api.chats()).map(c => [c.slug, c]));
+    } catch (e) {
+      this.#log(`список чатов недоступен (${e.message}) — запускаю без описания проекта`);
+      return new Map();
+    }
+  }
+}
+
+/**
+ * Стоит ли запуск урока: агент работал — читал, искал, правил, запускал — или натыкался на
+ * ошибки. «Прочитал тред и ответил» — не опыт: лимиты на него тратить незачем.
+ */
+function worthALesson(card) {
+  const { steps, tools, errors } = card.process;
+  return steps - (tools.chat ?? 0) >= 2 || errors.length > 0;
+}
+
+/** Мост в сборе — из настроек. */
+export function createBridge(config, { log, print = text => console.log(text) }) {
+  const api = new ChatApi({ url: config.api, token: config.token });
+  return new Bridge({
+    config,
+    api,
+    thread: new Thread(api, config.handle),
+    launcher: new AgentLauncher(config, log),
+    archive: new RunArchive(config.runsDir),
+    outbox: new KnowledgeOutbox(config.outboxFile, api, log),
+    reporter: new ProgressReporter(api, log),
+    log,
+    print,
+  });
+}
+
+/** Исход запуска, пока не проверено, есть ли ответ. */
+function outcomeOf(code) {
+  if (code === null) return { state: 'failed', note: 'не удалось запустить агента' };
+  if (code !== 0) return { state: 'failed', note: `агент завершился с кодом ${code}` };
+  return { state: 'done', note: 'обработка завершилась без ответа' };
+}
+
+/** slug → обращения; null — сервер старше нескольких чатов. */
+function groupByChat(mentions) {
+  const groups = new Map();
+  for (const mention of mentions) {
+    const slug = mention.message.chat?.slug ?? null;
+    groups.set(slug, [...(groups.get(slug) ?? []), mention]);
+  }
+  return groups;
+}
+
+function memoize(fn) {
+  const cache = new Map();
+  return key => {
+    if (!cache.has(key)) cache.set(key, fn(key));
+    return cache.get(key);
+  };
+}

package/host/bridge/config.js

@@ -0,0 +1,105 @@
+// Настройки моста — только из окружения процесса: .env мост не читает. Окружение задаёт
+// тот, кто мост запускает: раннер, юнит systemd или человек в терминале.
+
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = fileURLToPath(new URL('../../', import.meta.url));
+
+export class ConfigError extends Error {}
+
+/**
+ * @param {NodeJS.ProcessEnv} env
+ * @param {object} overrides поля поверх окружения: флаги командной строки, тесты
+ */
+export function bridgeConfig(env = process.env, overrides = {}) {
+  if (!env.CHAT_TOKEN) throw new ConfigError('нужен CHAT_TOKEN');
+
+  const api = env.CHAT_API || 'http://localhost:8600/api';
+  const runtime = env.CHAT_RUNTIME || '';
+  const beaconTtl = int(env, 'CHAT_BEACON_TTL', 90);
+
+  const config = {
+    api,
+    token: env.CHAT_TOKEN,
+    handle: env.CHAT_HANDLE || 'claude',
+
+    // Общие правила чата — одни на всех агентов. Роль (за что агент отвечает) приходит
+    // с сервером в каждом обращении: роли заводит владелец в интерфейсе.
+    rulesFile: env.CHAT_SETTINGS || path.join(ROOT, 'agents', 'rules.md'),
+    // Движок (claude, codex…) и его особенности — песочница, доступы. Они про движок, а не про роль.
+    runtime,
+    runtimeNotesFile: runtime ? path.join(ROOT, 'agents', 'runtimes', `${runtime}.md`) : null,
+
+    // MCP-подключение к чату для {mcp_config}: у агентов на движке claude оно собирается
+    // на каждый запуск под токеном агента — иначе все они писали бы под одним именем.
+    mcpUrl: env.CHAT_MCP_URL || `${api.replace(/\/api\/?$/, '')}/mcp`,
+    // Под этим именем агент видит инструменты чата (mcp__<имя>__…); оно же стоит
+    // в --allowedTools команды. qbazar-chat — имя первой установки.
+    mcpName: env.CHAT_MCP_NAME || 'qbazar-chat',
+
+    // Команда запуска агента. Промпт ВСЕГДА уходит через stdin, поэтому в шаблоне его нет.
+    // В режиме -p список --allowedTools — это ВЕСЬ белый список: без mcp__qbazar-chat
+    // инструменты чата отказывают по правам. Edit/Write — по решению владельца (#67).
+    agentCommand: env.CHAT_AGENT_CMD || 'claude -p --allowedTools Bash Read Grep Glob Edit Write mcp__qbazar-chat',
+    // {session} в команде — продолжение сессии. Пусто — свежая сессия: дёшево, память
+    // берётся из контекста чата и репозиториев.
+    resume: env.CHAT_RESUME || '',
+
+    // Каталог агента, заданный машиной. Главнее каталога проекта: у Codex это песочница,
+    // и сервер не должен её отменять. Нужен и агенту-Windows из WSL: WSL-путь для него
+    // не годится как cwd, и процесс молча падает в C:\Windows\Temp.
+    agentCwd: env.CHAT_AGENT_CWD || '',
+    // Каталог проекта приходит с сервером (workdir чата). Сервер не должен уметь отправить
+    // агента куда угодно: принимаем только существующий каталог внутри этого корня.
+    workdirRoot: env.CHAT_WORKDIR_ROOT || os.homedir(),
+
+    // Защита от переклички: ответы агентов сами содержат @упоминания и породили бы новые
+    // обращения — и так по кругу. По умолчанию запускаемся только на сообщения владельца.
+    triggerRoles: (env.CHAT_TRIGGER_ROLES || 'owner').split(','),
+    maxAttempts: int(env, 'CHAT_MAX_ATTEMPTS', 3),
+    // Бюджет ходов на разговор агентов между собой, от последней реплики владельца.
+    // Исчерпан — агенты молчат, пока владелец не скажет следующее слово.
+    turnBudget: int(env, 'CHAT_AGENT_TURN_BUDGET', 3),
+
+    // Индикатор «агент работает»: срок годности отметки и как часто её продлевать.
+    // Втрое чаще срока — один пропущенный удар индикатор не гасит, а упавший мост
+    // гасит его сам за полторы минуты.
+    beaconTtl,
+    beaconIntervalMs: Math.max(5, Math.floor(beaconTtl / 3)) * 1000,
+
+    intervalMs: int(env, 'CHAT_INTERVAL', 10) * 1000,
+    // Счётчики попыток и замок. При установке пакетом код лежит там, куда писать
+    // не стоит, — тогда они живут в каталоге данных.
+    stateDir: env.CHAT_STATE_DIR || ROOT,
+    // Записи запусков агента (run-archive.js): задание, ход работы, исход. Это данные,
+    // а не временный лог, — поэтому не /tmp и не каталог кода.
+    runsDir: env.CHAT_RUNS_DIR || path.join(os.homedir(), 'agent-workspace', 'runs'),
+    // Команда урока для карточки опыта — дешёвая модель без инструментов (distill в runner.json).
+    // Пусто — карточка без урока: только факты.
+    distillCommand: env.CHAT_DISTILL_CMD || '',
+
+    ...overrides,
+  };
+
+  if (config.resume && !config.agentCommand.includes('{session}')) {
+    throw new ConfigError('CHAT_RESUME задан, но в CHAT_AGENT_CMD нет плейсхолдера {session}');
+  }
+
+  return Object.freeze({
+    ...config,
+    stateFile: path.join(config.stateDir, `.bridge-state-${config.handle}.json`),
+    lockFile: path.join(config.stateDir, `.bridge-${config.handle}.lock`),
+    // Карточки опыта, которые не дошли до чата: уйдут, когда он ответит.
+    outboxFile: path.join(config.stateDir, `.bridge-outbox-${config.handle}.json`),
+  });
+}
+
+function int(env, name, fallback) {
+  const raw = env[name];
+  if (raw === undefined || raw === '') return fallback;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0) throw new ConfigError(`${name}=${raw} — нужно целое число`);
+  return value;
+}

package/host/bridge/knowledge-outbox.js

@@ -0,0 +1,96 @@
+// Карточки опыта по дороге в чат. Чат может не ответить — перезапуск, сеть, — и карточка
+// не должна от этого пропасть: она ждёт в файле очереди и уходит при следующем проходе.
+//
+// Отправки идут строго по одной: факты и урок одного запуска уходят разными запросами,
+// и опоздавшие факты не должны затереть уже дошедший урок.
+
+import fs from 'node:fs';
+import { ChatHttpError } from '../lib/chat-api.js';
+
+export class KnowledgeOutbox {
+  #file;
+  #api;
+  #log;
+  /** key записи запуска → {chat, key, file}: сама карточка — в файле, там всегда последняя версия. */
+  #pending;
+  #tail = Promise.resolve();
+
+  /**
+   * @param {string} file файл очереди
+   * @param {import('../lib/chat-api.js').ChatApi} api
+   * @param {(...parts: any[]) => void} log
+   */
+  constructor(file, api, log) {
+    this.#file = file;
+    this.#api = api;
+    this.#log = log;
+    this.#pending = new Map(load(file).map(entry => [entry.key, entry]));
+  }
+
+  /** Отправить карточку запуска; не дошла — останется в очереди. */
+  send({ chat, key, file }) {
+    return this.#serial(async () => {
+      const entry = { chat, key, file };
+      if (await this.#deliver(entry)) this.#pending.delete(key);
+      else this.#pending.set(key, entry);
+      this.#save();
+    });
+  }
+
+  /** Дослать то, что не дошло. Чат снова не ответил — остальное ждёт следующего раза. */
+  flush() {
+    if (this.#pending.size === 0) return this.#tail;
+    return this.#serial(async () => {
+      for (const entry of [...this.#pending.values()]) {
+        if (!await this.#deliver(entry)) break;
+        this.#pending.delete(entry.key);
+      }
+      this.#save();
+    });
+  }
+
+  /** @returns {Promise<boolean>} true — дошла или повторять бессмысленно; false — повторить позже */
+  async #deliver({ chat, key, file }) {
+    let card;
+    try {
+      card = JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
+      this.#log(`карточка ${key}: файла нет — отправлять нечего`);
+      return true;
+    }
+    try {
+      await this.#api.saveCard(chat, key, card);
+      return true;
+    } catch (e) {
+      // Отказ (4xx) повтором не исправить: старый сервер без базы знаний, неверная карточка.
+      if (e instanceof ChatHttpError && e.status < 500) {
+        this.#log(`карточка ${key}: ${e.message} — не отправлена`);
+        return true;
+      }
+      this.#log(`карточка ${key}: ${e.message} — отправлю позже`);
+      return false;
+    }
+  }
+
+  #serial(task) {
+    this.#tail = this.#tail.then(task).catch(e => this.#log(`очередь карточек: ${e.message}`));
+    return this.#tail;
+  }
+
+  #save() {
+    if (this.#pending.size === 0) {
+      fs.rmSync(this.#file, { force: true });
+      return;
+    }
+    fs.writeFileSync(this.#file, JSON.stringify([...this.#pending.values()], null, 2) + '\n', { mode: 0o600 });
+  }
+}
+
+function load(file) {
+  try {
+    const entries = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return Array.isArray(entries) ? entries.filter(e => e?.chat && e?.key && e?.file) : [];
+  } catch {
+    return []; // очереди нет или она испорчена — карточки остались в записях запусков
+  }
+}

package/host/bridge/launcher.js

@@ -0,0 +1,126 @@
+// Запуск агента: команда из настроек машины, задание — через stdin, вывод — в файлы,
+// которые назовёт мост (запись запуска).
+
+import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { splitWords } from '../lib/shell-words.js';
+
+/** Переменные, которые агент получает от моста: ими он ходит в чат. */
+const CHAT_VARS = ['CHAT_TOKEN', 'CHAT_API', 'QBAZAR_CHAT_TOKEN'];
+
+export class AgentLauncher {
+  #config;
+  #log;
+
+  /** @param {ReturnType<import('./config.js').bridgeConfig>} config */
+  constructor(config, log) {
+    this.#config = config;
+    this.#log = log;
+  }
+
+  /**
+   * Запустить агента и дождаться его.
+   *
+   * @param {string} prompt задание — только через stdin: текст чужого сообщения в аргументах
+   *   команды был бы подстановкой в командную строку
+   * @param {object} options
+   * @param {string|null} options.cwd
+   * @param {{stdout: string, stderr: string}} options.output куда писать вывод агента. Раздельно:
+   *   stdout у движков — ход работы построчным JSON, и ошибки его не должны портить
+   * @param {() => void} [options.onStart] сразу после создания процесса, не раньше
+   * @returns {Promise<number|null>} код возврата; null — процесс не создан
+   */
+  async run(prompt, { cwd, output, onStart = () => {} }) {
+    const mcpFile = this.#needsMcpConfig() ? this.#writeMcpConfig() : null;
+    const out = fs.openSync(output.stdout, 'w', 0o600);
+    const err = fs.openSync(output.stderr, 'w', 0o600);
+    this.#log(`запускаю агента — десятки секунд или минуты, запись: ${path.dirname(output.stdout)}`);
+    const started = Date.now();
+
+    try {
+      const [command, ...args] = this.#command(mcpFile);
+      const child = spawn(command, args, { cwd: cwd ?? undefined, env: this.#env(), stdio: ['pipe', out, err] });
+      // Агент вправе выйти, не дочитав задание: EPIPE здесь — не ошибка моста.
+      child.stdin.on('error', () => {});
+
+      try {
+        await spawned(child);
+      } catch (e) {
+        this.#log(`агента запустить не удалось: ${e.message}`);
+        return null;
+      }
+
+      onStart();
+      child.stdin.end(prompt);
+
+      const code = await exited(child);
+      const took = Math.round((Date.now() - started) / 1000);
+      this.#log(code === 0
+        ? `агент отработал за ${took} с`
+        : `агент завершился с кодом ${code} за ${took} с — см. ${output.stderr}`);
+      return code;
+    } finally {
+      fs.closeSync(out);
+      fs.closeSync(err);
+      if (mcpFile) fs.rmSync(mcpFile, { force: true });
+    }
+  }
+
+  /**
+   * Подстановки — в уже разобранные слова, а не в строку: путь с пробелом или
+   * кавычкой не развалит команду и не допишет в неё лишнего.
+   */
+  #command(mcpFile) {
+    const words = splitWords(this.#config.agentCommand);
+    const filled = words.map(word => word
+      .replaceAll('{session}', this.#config.resume)
+      .replaceAll('{mcp_config}', mcpFile ?? ''));
+    // Плейсхолдер без значения (свежая сессия) — не пустой аргумент, а его отсутствие.
+    return filled.filter((word, i) => word !== '' || words[i] === '');
+  }
+
+  #env() {
+    const { token, api } = this.#config;
+    // QBAZAR_CHAT_TOKEN — под этим именем токен ждёт MCP-клиент Codex (--bearer-token-env-var).
+    const env = { ...process.env, CHAT_TOKEN: token, CHAT_API: api, QBAZAR_CHAT_TOKEN: token };
+    // Через границу WSL→Windows переменные сами НЕ проходят — нужен WSLENV.
+    // Агенту на Linux эта строка безвредна.
+    const wslenv = new Set((env.WSLENV ?? '').split(':').filter(Boolean));
+    env.WSLENV = [...new Set([...wslenv, ...CHAT_VARS])].sort().join(':');
+    return env;
+  }
+
+  #needsMcpConfig() {
+    return this.#config.agentCommand.includes('{mcp_config}');
+  }
+
+  /**
+   * Подключение к чату под токеном ЭТОГО агента. Файлом, а не аргументом: токен в командной
+   * строке виден любому процессу через ps. Права 600, удаляется после запуска.
+   */
+  #writeMcpConfig() {
+    const { handle, mcpName, mcpUrl, token } = this.#config;
+    const file = path.join(os.tmpdir(), `chat-mcp-${handle}-${crypto.randomBytes(6).toString('hex')}.json`);
+    fs.writeFileSync(file, JSON.stringify({
+      mcpServers: { [mcpName]: { type: 'http', url: mcpUrl, headers: { Authorization: `Bearer ${token}` } } },
+    }), { mode: 0o600, flag: 'wx' });
+    return file;
+  }
+}
+
+function spawned(child) {
+  return new Promise((resolve, reject) => {
+    child.once('spawn', resolve);
+    child.once('error', reject);
+  });
+}
+
+/** Код возврата; убитый сигналом — отрицательный номер сигнала, как у Python. */
+function exited(child) {
+  return new Promise(resolve => {
+    child.once('close', (code, signal) => resolve(code ?? -(os.constants.signals[signal] ?? 1)));
+  });
+}