team-chat 0.0.0-stage → 0.3.0

package/host/bridge/main.js

@@ -0,0 +1,87 @@
+// Точка входа моста.
+//
+//   CHAT_TOKEN=… node host/bridge/main.js             один проход и выход
+//   CHAT_TOKEN=… node host/bridge/main.js --watch     дежурство, по умолчанию раз в 10 с
+//   CHAT_TOKEN=… node host/bridge/main.js --dry-run   показать задание, не тратя токенов
+//
+// Остальные настройки — переменные CHAT_* (см. config.js).
+
+import { parseArgs } from 'node:util';
+import { ChatUnavailableError } from '../lib/chat-api.js';
+import { log } from '../lib/log.js';
+import { LockBusyError, PidLock } from '../lib/pid-lock.js';
+import { createBridge } from './bridge.js';
+import { bridgeConfig, ConfigError } from './config.js';
+
+const { values: flags } = parseArgs({
+  options: {
+    watch: { type: 'boolean', default: false },
+    interval: { type: 'string' },
+    'dry-run': { type: 'boolean', default: false },
+  },
+});
+const dryRun = flags['dry-run'];
+
+let config;
+try {
+  config = bridgeConfig(process.env, flags.interval ? { intervalMs: seconds(flags.interval) * 1000 } : {});
+} catch (e) {
+  if (!(e instanceof ConfigError)) throw e;
+  exit(e.message);
+}
+
+// Показ задания агента не запускает — ему замок не нужен.
+if (!dryRun) holdLock(config.lockFile);
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.on(signal, () => {
+    log('остановлен');
+    process.exit(0);
+  });
+}
+
+const bridge = createBridge(config, { log });
+
+if (!flags.watch) {
+  if (!await pass()) process.exitCode = 1;
+} else {
+  log(`дежурство: проверка раз в ${config.intervalMs / 1000} с. Холостой проход не стоит токенов. Ctrl+C — выход.`);
+  for (;;) {
+    // Дежурство не должно умирать из-за одного плохого прохода.
+    if (!await pass()) log(`повтор через ${config.intervalMs / 1000} с`);
+    await new Promise(resolve => setTimeout(resolve, config.intervalMs));
+  }
+}
+
+/** Проход с разбором сбоя. → удался ли. */
+async function pass() {
+  try {
+    await bridge.cycle({ dryRun });
+    return true;
+  } catch (e) {
+    log(e instanceof ChatUnavailableError ? e.message : `ошибка прохода: ${e.stack}`);
+    return false;
+  }
+}
+
+/** Один мост на участника — иначе агент запускался бы дважды на одно обращение. */
+function holdLock(file) {
+  let lock;
+  try {
+    lock = PidLock.acquire(file);
+  } catch (e) {
+    if (!(e instanceof LockBusyError)) throw e;
+    exit(`мост @${config.handle} уже запущен (pid ${e.pid}) — второй экземпляр запускал бы агента дважды`);
+  }
+  process.on('exit', () => lock.release());
+}
+
+function seconds(raw) {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 1) exit(`--interval ${raw} — нужно целое число секунд`);
+  return value;
+}
+
+function exit(message) {
+  console.error(message);
+  process.exit(1);
+}

package/host/bridge/progress.js

@@ -0,0 +1,74 @@
+// Ход обработки обращений на сервер и сигнал жизни, пока агент работает.
+//
+// О работе сообщает МОСТ, а не агент: агент не может отметиться о своём падении —
+// в этот момент его уже нет. Мост же видит и создание процесса, и код возврата.
+//
+// «Ответ опубликован» сюда не входит и входить не может: его сервер выводит сам,
+// по сообщению с reply_to_id конкретного обращения.
+
+export class ProgressReporter {
+  #api;
+  #log;
+
+  constructor(api, log) {
+    this.#api = api;
+    this.#log = log;
+  }
+
+  /**
+   * Сбой индикатора не должен ронять ответ: чат без «работает» живёт, ответ без чата —
+   * нет. Поэтому ошибка здесь только пишется в журнал.
+   *
+   * @param {number[]} mentionIds
+   * @param {'working'|'done'|'failed'|'deferred'|'paused'} state
+   */
+  async report(mentionIds, state, { note, ttl } = {}) {
+    try {
+      await this.#api.report({ state, mentions: mentionIds, note, ttl });
+      return true;
+    } catch (e) {
+      this.#log(`индикатор: не удалось отметить ${state} по ${mentionIds.join(', ')}: ${e.message}`);
+      return false;
+    }
+  }
+}
+
+/**
+ * «Работает» по обращениям запуска — с продлением, пока агент жив. Пропажу сигнала сервер
+ * судит по сроку годности, так что упавший мост гасит индикатор сам.
+ */
+export class Beacon {
+  #reporter;
+  #mentionIds;
+  #note;
+  #ttl;
+  #intervalMs;
+  #timer = null;
+  #inFlight = Promise.resolve();
+
+  constructor(reporter, { mentionIds, note, ttl, intervalMs }) {
+    this.#reporter = reporter;
+    this.#mentionIds = mentionIds;
+    this.#note = note;
+    this.#ttl = ttl;
+    this.#intervalMs = intervalMs;
+  }
+
+  /** Только после того, как процесс агента создан: не запустившаяся команда «работает» не показывает. */
+  start() {
+    this.#beat();
+    this.#timer = setInterval(() => this.#beat(), this.#intervalMs);
+  }
+
+  /** Дожидается последнего удара: иначе «работает» могло бы прийти на сервер позже исхода. */
+  async stop() {
+    clearInterval(this.#timer);
+    this.#timer = null;
+    await this.#inFlight;
+  }
+
+  #beat() {
+    this.#inFlight = this.#inFlight.then(() =>
+      this.#reporter.report(this.#mentionIds, 'working', { note: this.#note, ttl: this.#ttl }));
+  }
+}

package/host/bridge/prompt.js

@@ -0,0 +1,97 @@
+// Задание агенту. Чистая функция: всё, что нужно, приходит аргументами — файлы читает
+// тот, кто её зовёт.
+//
+// Инструкций про API, токены и формат запроса здесь нет: агент подключён к чату по MCP
+// и знает свои инструменты сам. Чем короче задание, тем дешевле каждый запуск и тем
+// меньше способов ошибиться.
+
+/**
+ * Все обращения одного прохода в одном чате — в ОДНО задание: три сообщения подряд,
+ * написанные, пока агент думает над первым, не должны стоить трёх запусков.
+ *
+ * @param {object} p
+ * @param {object[]} p.mentions обращения одного чата, как их отдаёт /api/mentions
+ * @param {object|null} p.chat настройки чата из /api/chats: name, slug, workdir, description, team
+ * @param {string} p.handle кто мы
+ * @param {string} p.rules общие правила чата (agents/rules.md)
+ * @param {string} p.runtimeNotes особенности движка (agents/runtimes/<движок>.md) или ''
+ * @param {string} p.mcpName имя MCP-сервера чата у агента
+ * @param {object[]} [p.experience] уроки прошлых похожих задач, как их отдаёт /api/knowledge
+ */
+export function buildPrompt({ mentions, chat, handle, rules, runtimeNotes, mcpName, experience = [] }) {
+  const plural = mentions.length > 1 ? 'обращения' : 'обращение';
+  const ids = mentions.map(m => `#${m.message.id}`).join(', ');
+
+  return `${rules}\n\n`
+    + (runtimeNotes ? `${runtimeNotes.trim()}\n\n` : '')
+    + '---\n\n'
+    + whoAmI(handle, mentions[0].role ?? {}, chat?.team ?? []) + '\n'
+    + aboutProject(chat)
+    + `Тебя упомянули в чате. Необработанных ${plural}: ${mentions.length} (${ids}).\n\n`
+    + mentions.map(m => messageBlock(m.message)).join('\n\n')
+    + experienceBlock(experience)
+    + '\n\n---\n\n'
+    + `Инструменты чата у тебя есть (MCP-сервер ${mcpName}): read-thread для контекста, `
+    + 'post-message для ответа, search-thread для старых обсуждений, '
+    + 'read-attachment для приложенных файлов, find-knowledge для опыта команды в похожих задачах.\n'
+    + 'На КАЖДОЕ перечисленное сообщение ответь отдельным post-message со своим reply_to_id — '
+    + 'иначе обращение останется висеть.\n'
+    + 'Обращения не подтверждай: это сделает мост, убедившись, что ответ действительно опубликован.';
+}
+
+/** Роль в этом чате и состав команды: в тексте роли имён нет — команда меняется. */
+function whoAmI(handle, role, team) {
+  let text = `Ты — @${handle}`;
+  if (role.name) text += `, роль в этом чате — «${role.name}»`;
+  text += '.\n';
+  if (role.instructions) text += `\n${role.instructions.trim()}\n`;
+  if (team.length) {
+    text += '\nКоманда этого чата:\n'
+      + team.map(t => `  • @${t.handle} — ${t.name}, ${t.role_name}${t.handle === handle ? ' (это ты)' : ''}`).join('\n')
+      + '\n';
+  }
+  return text;
+}
+
+/** Что за проект — из настроек чата: инструкции агента про роль, а проектов много. */
+function aboutProject(chat) {
+  if (!chat) return '';
+  return `Чат «${chat.name}» (chat: ${chat.slug}). Передавай chat=${chat.slug} `
+    + 'инструментам чата — у каждого проекта свой тред, журнал решений и документы.\n'
+    + (chat.workdir ? `Код проекта: ${chat.workdir}\n` : '')
+    + (chat.description ? `\nО проекте:\n${chat.description.trim()}\n` : '')
+    + '\n';
+}
+
+/**
+ * Уроки прошлых запусков, похожие на эти обращения. Подсказка, а не правило: задача может
+ * только казаться похожей, поэтому — с оговоркой.
+ */
+function experienceBlock(lessons) {
+  if (!lessons.length) return '';
+  return '\n\nОпыт команды — уроки из похожих задач (сверь с задачей, прежде чем применять):\n'
+    + lessons.map(({ problem, solution }) => {
+      let text = `  • ${solution.rule}`;
+      const was = [problem?.symptom, problem?.root_cause && `причина — ${problem.root_cause}`].filter(Boolean).map(clause);
+      if (was.length) text += `\n    Было: ${was.join('; ')}.`;
+      if (solution.applies_when) text += `\n    Когда применять: ${clause(solution.applies_when)}.`;
+      return text;
+    }).join('\n');
+}
+
+/** Фраза внутри предложения: без точки на конце — её поставит предложение. */
+function clause(text) {
+  return String(text).trim().replace(/[.\s]+$/, '');
+}
+
+function messageBlock(message) {
+  let block = `Сообщение #${message.id} от ${message.author.name} (${message.author.role}):\n${message.body}`;
+  // Файл часто и есть вопрос («что тут не так?» + скриншот) — агент должен знать,
+  // что он есть, ещё до первого вызова инструментов.
+  const files = message.attachments ?? [];
+  if (files.length) {
+    block += '\nВложения (открыть — read-attachment по id):\n'
+      + files.map(a => `  • id ${a.id}: ${a.name} (${a.mime}, ${a.size} байт)`).join('\n');
+  }
+  return block;
+}

package/host/bridge/run-archive.js

@@ -0,0 +1,200 @@
+// Записи запусков агента — сырьё для своего агента владельца.
+//
+// В треде остаётся только итоговый ответ, а ценное — ход работы: что агент читал,
+// какие команды запускал, где ошибся и как поправился. Его движки отдают в stdout
+// построчным JSON (claude --output-format stream-json, codex exec --json). Мост кладёт
+// каждый запуск в свой каталог:
+//
+//   <runsDir>/<чат>/<дата UTC>/<время>-<handle>-<обращения>/
+//     run.json     что за запуск и чем кончился — по каждому обращению (формат ниже)
+//     prompt.md    задание, ушедшее агенту
+//     stdout       ход работы агента — как есть
+//     stderr       ошибки движка
+//     card.json    карточка опыта — что из запуска остаётся надолго (host/knowledge/card.js)
+//
+// run.json пишется дважды: при запуске и по итогам. Запуск, оборвавшийся вместе с мостом,
+// остаётся с finished_at: null — тоже факт о работе агента.
+//
+// Сырьё (prompt.md, stdout, stderr) живёт ограниченный срок — его чистит раннер
+// (pruneRuns ниже); card.json и run.json остаются: в них опыт, а не содержимое проекта.
+//
+// Внутри — чужой код и переписка: каталоги 700, файлы 600. Команда запуска целиком не
+// сохраняется: runner.json — настройки машины, в нём может оказаться что угодно.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Версия формата run.json: записи будут переезжать в базу, и разбирать их надо уметь. */
+export const FORMAT = 1;
+
+export class RunArchive {
+  #dir;
+  #now;
+
+  /** @param {string} dir корень записей (CHAT_RUNS_DIR) */
+  constructor(dir, { now = () => new Date() } = {}) {
+    this.#dir = dir;
+    this.#now = now;
+  }
+
+  /**
+   * Завести запись запуска — до создания процесса: задание сохранено, даже если агент
+   * не запустится.
+   *
+   * @param {object} p
+   * @param {string} p.handle
+   * @param {string} p.runtime движок
+   * @param {string} p.executable чем запускали — первое слово команды, без аргументов
+   * @param {object|null} p.chat настройки чата
+   * @param {object[]} p.mentions обращения запуска
+   * @param {string} p.prompt
+   * @param {string|null} p.cwd
+   */
+  begin({ handle, runtime, executable, chat, mentions, prompt, cwd }) {
+    const started = this.#now();
+    const stamp = started.toISOString();
+    const dir = path.join(
+      this.#dir,
+      safe(chat?.slug ?? 'default'),
+      stamp.slice(0, 10),
+      `${stamp.slice(11, 23).replaceAll(':', '')}-${safe(handle)}-${mentions.map(m => m.id).join('-')}`,
+    );
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+    const record = new RunRecord(dir, path.relative(this.#dir, dir).split(path.sep).join('/'), this.#now, started, {
+      format: FORMAT,
+      handle,
+      runtime: runtime || null,
+      executable: path.basename(executable),
+      chat: chat ? { slug: chat.slug, name: chat.name } : null,
+      cwd,
+      started_at: stamp,
+      finished_at: null,
+      duration_ms: null,
+      exit_code: null,
+      mentions: mentions.map(m => ({
+        mention_id: m.id,
+        message_id: m.message.id,
+        author: { handle: m.message.author.handle ?? null, role: m.message.author.role },
+        agent_role: m.role?.slug ?? null,
+        attempt: null,
+        outcome: null,
+        answer_message_id: null,
+      })),
+    });
+    writePrivate(path.join(dir, 'prompt.md'), prompt);
+    record.save();
+    return record;
+  }
+}
+
+/** Запись одного запуска. Заполняется по ходу, сохраняется save(). */
+export class RunRecord {
+  #dir;
+  #key;
+  #now;
+  #data;
+  #started;
+
+  constructor(dir, key, now, started, data) {
+    this.#dir = dir;
+    this.#key = key;
+    this.#now = now;
+    this.#started = started;
+    this.#data = data;
+  }
+
+  get dir() {
+    return this.#dir;
+  }
+
+  /** Имя записи внутри корня записей: «чат/дата/время-handle-обращения». Им же карточка зовётся на сервере. */
+  get key() {
+    return this.#key;
+  }
+
+  get cardFile() {
+    return path.join(this.#dir, 'card.json');
+  }
+
+  /** Куда агенту писать вывод. */
+  get output() {
+    return { stdout: path.join(this.#dir, 'stdout'), stderr: path.join(this.#dir, 'stderr') };
+  }
+
+  /** @param {number|null} exitCode null — процесс не создан */
+  finish(exitCode) {
+    const finished = this.#now();
+    this.#data.finished_at = finished.toISOString();
+    this.#data.duration_ms = finished - this.#started;
+    this.#data.exit_code = exitCode;
+  }
+
+  /**
+   * Исход по обращению.
+   * @param {number} mentionId
+   * @param {{outcome: 'answered'|'done'|'failed'|'deferred', attempt: number, answerMessageId?: number|null}} result
+   */
+  settle(mentionId, { outcome, attempt, answerMessageId = null }) {
+    const mention = this.#data.mentions.find(m => m.mention_id === mentionId);
+    Object.assign(mention, { outcome, attempt, answer_message_id: answerMessageId });
+  }
+
+  save() {
+    writePrivate(path.join(this.#dir, 'run.json'), JSON.stringify(this.#data, null, 2) + '\n');
+  }
+
+  /** Сведения о запуске — то, что лежит в run.json. */
+  get data() {
+    return structuredClone(this.#data);
+  }
+
+  attachCard(card) {
+    writePrivate(this.cardFile, JSON.stringify(card, null, 2) + '\n');
+  }
+}
+
+/** Что остаётся от записи после срока хранения: опыт и сведения о запуске, без содержимого. */
+const KEPT = new Set(['card.json', 'run.json']);
+
+/**
+ * Удалить сырьё записей старше keepDays: задание, ход работы, ошибки. Возраст — по дате в
+ * пути (<чат>/<дата UTC>/…), читать каждую запись незачем. Повторный проход ничего не ломает.
+ *
+ * @param {string} root корень записей (CHAT_RUNS_DIR)
+ * @param {{keepDays: number, now?: Date}} options
+ * @returns {number} у скольких запусков удалено сырьё
+ */
+export function pruneRuns(root, { keepDays, now = new Date() }) {
+  const cutoff = new Date(now.getTime() - keepDays * 86_400_000).toISOString().slice(0, 10);
+  let pruned = 0;
+  for (const chat of subdirs(root)) {
+    for (const day of subdirs(path.join(root, chat))) {
+      if (!/^\d{4}-\d{2}-\d{2}$/.test(day) || day >= cutoff) continue;
+      for (const run of subdirs(path.join(root, chat, day))) {
+        const dir = path.join(root, chat, day, run);
+        const raw = fs.readdirSync(dir, { withFileTypes: true }).filter(f => f.isFile() && !KEPT.has(f.name));
+        for (const file of raw) fs.rmSync(path.join(dir, file.name));
+        if (raw.length) pruned++;
+      }
+    }
+  }
+  return pruned;
+}
+
+function subdirs(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name).sort();
+  } catch {
+    return []; // записей ещё нет
+  }
+}
+
+/** Имя для пути: slug и handle приходят с сервера — без «..» и разделителей. */
+function safe(name) {
+  return String(name).replace(/[^\w.-]/g, '_').replace(/^\.+/, '_') || '_';
+}
+
+function writePrivate(file, text) {
+  fs.writeFileSync(file, text, { mode: 0o600 });
+}

package/host/bridge/thread.js

@@ -0,0 +1,44 @@
+// Вопросы моста к ленте чата: ответил ли агент и сколько агенты наговорили без владельца.
+
+/** Страница ленты — максимум, который отдаёт сервер (ChatController::limit). */
+export const PAGE = 500;
+
+export class Thread {
+  #api;
+  #handle;
+
+  constructor(api, handle) {
+    this.#api = api;
+    this.#handle = handle;
+  }
+
+  /**
+   * Отвечал ли я ИМЕННО на это сообщение — по reply_to_id, а не «есть ответ позже».
+   *
+   * Ленту после вопроса листаем до конца: ответ, оказавшийся за границей страницы,
+   * иначе выглядел бы как «ответа нет» — и мост запустил бы агента второй раз.
+   */
+  async answered(message) {
+    return (await this.answerTo(message)) !== null;
+  }
+
+  /** Мой ответ на это сообщение или null. */
+  async answerTo(message) {
+    const chat = message.chat?.slug ?? null;
+    let after = message.id;
+    for (;;) {
+      const page = await this.#api.messages(chat, { afterId: after, limit: PAGE });
+      const answer = page.find(m => m.author.handle === this.#handle && m.reply_to_id === message.id);
+      if (answer) return answer;
+      if (page.length < PAGE) return null;
+      after = page.at(-1).id;
+    }
+  }
+
+  /** Сколько раз агенты высказались после последней реплики владельца — в этом чате. */
+  async agentTurnsSinceOwner(chat) {
+    const recent = await this.#api.messages(chat, { limit: 100 });
+    const lastOwner = recent.findLastIndex(m => m.author.role === 'owner');
+    return recent.slice(lastOwner + 1).filter(m => m.author.kind === 'ai').length;
+  }
+}

package/host/bridge/triage.js

@@ -0,0 +1,97 @@
+// Разбор обращения до запуска агента — цепочка правил. Каждое правило отвечает на один
+// вопрос и либо выносит вердикт, либо передаёт обращение дальше. Дошло до конца —
+// агента надо запускать.
+//
+// Правило только решает; исполняет вердикт мост. Так каждое правило проверяется
+// без сети и без процессов, а все побочные эффекты — в одном месте.
+
+/** Погасить обращение без запуска. reason — для журнала. */
+export const acknowledge = (reason, { forget = false } = {}) => ({ kind: 'acknowledge', reason, forget });
+
+/** Не запускать и не гасить: показать на странице, почему обращение ждёт (note). */
+export const hold = (state, note, reason = null) => ({ kind: 'hold', state, note, reason });
+
+export const RUN = Object.freeze({ kind: 'run' });
+
+/**
+ * @typedef {object} TriageContext
+ * @property {import('./attempts.js').AttemptStore} attempts
+ * @property {(message: object) => Promise<boolean>} answered
+ * @property {(chat: string|null) => Promise<number>} turnsInChat ходы агентов после владельца
+ *
+ * @typedef {(mention: object, context: TriageContext) => Promise<object|null>|object|null} Rule
+ */
+
+/** Порядок важен: дешёвые и окончательные вердикты — раньше. */
+export function triageRules({ triggerRoles, maxAttempts, turnBudget }) {
+  return [
+    fromTriggerRole(triggerRoles),
+    notAnsweredYet(),
+    withinAttempts(maxAttempts),
+    withinTurnBudget(turnBudget),
+  ];
+}
+
+/** @param {Rule[]} rules */
+export async function triage(mention, rules, context) {
+  for (const rule of rules) {
+    const verdict = await rule(mention, context);
+    if (verdict) return verdict;
+  }
+  return RUN;
+}
+
+export function deferredNote(attempts, maxAttempts, last = null) {
+  return `попыток ${attempts} из ${maxAttempts}${last ? `, последняя: ${last}` : ''} — автоматического запуска не будет`;
+}
+
+/**
+ * Обращение от того, чьи сообщения агента не поднимают (по умолчанию — от другого
+ * агента), остаётся в треде как контекст, но в очереди ему не место: очередь отвечает
+ * на вопрос «что требует ответа», а не «где меня упомянули». Гасим сразу, иначе такие
+ * обращения копятся и прячут настоящие.
+ */
+function fromTriggerRole(roles) {
+  return mention => {
+    const role = mention.message.author.role;
+    return roles.includes('any') || roles.includes(role)
+      ? null
+      : acknowledge(`сообщение от ${role} — контекст, ответ не требуется; подтверждено`);
+  };
+}
+
+/** Ответ опубликован, а подтвердить мост не успел: повторный запуск дал бы дубль. */
+function notAnsweredYet() {
+  return async (mention, { answered }) => (await answered(mention.message)
+    ? acknowledge('ответ уже в треде — подтверждено без запуска агента', { forget: true })
+    : null);
+}
+
+/**
+ * Попытки исчерпаны: не долбим по кругу, вопрос остаётся в очереди. Но страница должна
+ * это видеть, а не показывать «ожидает запуска» того, чего не будет. Повтор каждый проход
+ * идемпотентен: сервер не сдвигает время исхода.
+ */
+function withinAttempts(maxAttempts) {
+  return (mention, { attempts }) => {
+    const count = attempts.count(mention.id);
+    return count >= maxAttempts ? hold('deferred', deferredNote(count, maxAttempts)) : null;
+  };
+}
+
+/**
+ * Обращение от другого агента тратит бюджет разговора, обращение владельца — нет: его
+ * реплика бюджет обнуляет, поэтому он всегда может нас позвать. Исчерпан — НЕ гасим:
+ * это отложено до слова владельца, а не «не требует ответа».
+ */
+function withinTurnBudget(turnBudget) {
+  return async (mention, { turnsInChat }) => {
+    const { role } = mention.message.author;
+    if (role === 'owner') return null;
+    const turns = await turnsInChat(mention.message.chat?.slug ?? null);
+    return turns >= turnBudget
+      ? hold('paused', `ходов агентов после реплики владельца: ${turns} из ${turnBudget}`,
+        `сообщение от ${role}, бюджет разговора исчерпан (${turns} из ${turnBudget}) — ждём слова владельца`)
+      : null;
+  };
+}

package/host/bridge/workdir.js

@@ -0,0 +1,41 @@
+// Где запускать агента. Каталог проекта присылает сервер, поэтому ему не верим на слово:
+// сервер не должен уметь отправить агента в произвольный каталог машины.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * @param {object|null} chat настройки чата (workdir — каталог проекта)
+ * @param {{agentCwd: string, workdirRoot: string}} config
+ * @returns {string|null} null — запускать в каталоге моста
+ */
+export function resolveAgentCwd(chat, { agentCwd, workdirRoot }, log) {
+  // Каталог машины главнее каталога проекта: у Codex это песочница.
+  if (agentCwd) return agentCwd;
+
+  const workdir = chat?.workdir;
+  if (!workdir) return null;
+
+  const dir = realDirectory(workdir);
+  const root = realDirectory(workdirRoot) ?? path.resolve(workdirRoot);
+  if (!dir || !isInside(dir, root)) {
+    log(`каталог проекта ${workdir} не годится (нет такого или вне ${root}) — запускаю без него`);
+    return null;
+  }
+  return dir;
+}
+
+/** Настоящий путь каталога — после ссылок: ссылка внутри корня может вести наружу. */
+function realDirectory(dir) {
+  try {
+    const real = fs.realpathSync(dir);
+    return fs.statSync(real).isDirectory() ? real : null;
+  } catch {
+    return null;
+  }
+}
+
+function isInside(dir, root) {
+  const relative = path.relative(root, dir);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}