zames_pro 1.0.0

package/src/self-review.js

@@ -0,0 +1,304 @@
+import path from 'path'
+import fs from 'fs/promises'
+import chalk from 'chalk'
+import { fileURLToPath } from 'url'
+
+import { createTools } from './tools.js'
+import { runAgentLoop } from './agent-loop.js'
+import { ZAMES_HOME } from './config.js'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const SRC_DIR = __dirname
+const SNAP_ROOT = path.join(ZAMES_HOME, 'snapshots')
+
+async function ensureDir(p) {
+  await fs.mkdir(p, { recursive: true })
+}
+
+async function copyDirJsFiles(from, to) {
+  await ensureDir(to)
+  const entries = await fs.readdir(from)
+  const copied = []
+  for (const e of entries) {
+    if (!e.endsWith('.js')) continue
+    const data = await fs.readFile(path.join(from, e), 'utf-8')
+    await fs.writeFile(path.join(to, e), data, 'utf-8')
+    copied.push(e)
+  }
+  return copied
+}
+
+
+// ---------- /self-review ----------
+
+export async function selfReview({ browser, config, focus, transcript }) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+  const snapRoot = path.join(SNAP_ROOT)
+  const snapDir = path.join(snapRoot, `run-${stamp}`)
+  await ensureDir(snapRoot)
+  await ensureDir(snapDir)
+
+  const copied = await copyDirJsFiles(SRC_DIR, snapDir)
+
+  if (copied.length === 0) {
+    console.error(
+      chalk.red(
+        `\n✖ Самообзор отменён: в ${SRC_DIR} нет .js файлов.\n` +
+          `Проверь, что src/ не пуст и ты запускаешь агента из корня проекта.\n`,
+      ),
+    )
+    throw new Error('SRC_DIR пуст — нечего ревьюить')
+  }
+
+  // Копируем package.json для контекста — чтобы агент видел зависимости
+  try {
+    const pkg = await fs.readFile(
+      path.resolve(SRC_DIR, '..', 'package.json'),
+      'utf-8',
+    )
+    await fs.writeFile(path.join(snapDir, 'package.json'), pkg, 'utf-8')
+  } catch {}
+
+  console.log(chalk.gray(`\n📸 Снапшот: ${snapDir}`))
+  console.log(chalk.gray(`Файлов: ${copied.length} — ${copied.join(', ')}`))
+  console.log(chalk.gray('Начинаю самообзор...\n'))
+
+  const taskPrompt = buildReviewPrompt({ focus, snapDir })
+
+  const tools = createTools(snapDir, { undo: null })
+  let finalMessage = ''
+
+  await runAgentLoop({
+    browser,
+    tools,
+    task: taskPrompt,
+    workdir: snapDir,
+    maxIterations: 80,
+    freshChat: true,
+    sendSystemPrompt: true,
+    transcript,
+    onThinking: () => {},
+    onToolCall: (name, args) => {
+      const preview = JSON.stringify(args).slice(0, 120)
+      console.log(chalk.yellow(`🔧 ${name}`), chalk.gray(preview))
+    },
+    onToolResult: (r) => {
+      const t = typeof r === 'string' ? r : JSON.stringify(r)
+      console.log(chalk.gray(`   → ${t.slice(0, 200).replace(/\n/g, ' ↵ ')}\n`))
+    },
+    onAssistantMessage: (msg) => {
+      finalMessage = msg
+      console.log(chalk.green('\n📋 Отчёт:\n'))
+      console.log(msg)
+      console.log()
+    },
+  })
+
+  // Сохраняем отчёт
+  const reportPath = path.join(snapDir, '_report.md')
+  await fs.writeFile(reportPath, finalMessage || '(пусто)', 'utf-8')
+
+  // Считаем, что изменилось
+  const changed = await diffFiles(SRC_DIR, snapDir)
+
+  console.log(chalk.gray('─'.repeat(60)))
+  console.log(chalk.gray(`Отчёт:       ${reportPath}`))
+  console.log(chalk.gray(`Снапшот:     ${snapDir}`))
+  if (changed.length) {
+    console.log(
+      chalk.green(
+        `Изменено:    ${changed.length} файл(ов): ${changed.join(', ')}`,
+      ),
+    )
+  } else {
+    console.log(chalk.gray('Изменено:    (ничего — только отчёт)'))
+  }
+  console.log(chalk.cyan(`\nДальше:`))
+  console.log(
+    chalk.cyan(
+      `  /self-diff ${path.basename(snapDir)}   — посмотреть различия`,
+    ),
+  )
+  console.log(
+    chalk.cyan(
+      `  /self-apply ${path.basename(snapDir)}  — применить к живому src/`,
+    ),
+  )
+  console.log()
+
+  return { snapDir, reportPath, changed }
+}
+
+// ---------- /self-diff ----------
+
+export async function selfDiff({ config, name }) {
+  const snapDir = path.join(SNAP_ROOT, name)
+  const snapStat = await fs.stat(snapDir).catch(() => null)
+  if (!snapStat) throw new Error(`Снапшот не найден: ${snapDir}`)
+
+  const { unifiedDiff, colorDiff } = await import('./diff.js')
+  const files = await fs.readdir(snapDir)
+  let anyDiff = false
+
+  for (const f of files) {
+    if (!f.endsWith('.js')) continue
+    const orig = await fs
+      .readFile(path.join(SRC_DIR, f), 'utf-8')
+      .catch(() => '')
+    const next = await fs
+      .readFile(path.join(snapDir, f), 'utf-8')
+      .catch(() => '')
+    if (orig === next) continue
+
+    anyDiff = true
+    console.log(chalk.bold(`\n=== src/${f} ===`))
+    const diff = unifiedDiff(orig, next, { label: f })
+    console.log(colorDiff(diff, chalk))
+  }
+
+  if (!anyDiff) {
+    console.log(chalk.gray('Различий нет.'))
+  }
+}
+
+// ---------- /self-apply ----------
+
+export async function selfApply({ config, name }) {
+  const snapDir = path.join(SNAP_ROOT, name)
+  const snapStat = await fs.stat(snapDir).catch(() => null)
+  if (!snapStat) throw new Error(`Снапшот не найден: ${snapDir}`)
+
+  // Бэкап текущего src перед перезаписью
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+  const backupDir = path.join(
+    SNAP_ROOT,
+    `backup-before-apply-${stamp}`,
+  )
+  await copyDirJsFiles(SRC_DIR, backupDir)
+
+  const files = await fs.readdir(snapDir)
+  const jsFiles = files.filter((f) => f.endsWith('.js'))
+
+  if (jsFiles.length === 0) {
+    throw new Error(
+      `В снапшоте ${snapDir} нет .js файлов. Apply отменён, чтобы не стирать src/.`,
+    )
+  }
+
+  const applied = []
+  for (const f of jsFiles) {
+    const data = await fs.readFile(path.join(snapDir, f), 'utf-8')
+    await fs.writeFile(path.join(SRC_DIR, f), data, 'utf-8')
+    applied.push(f)
+  }
+
+  console.log(chalk.green(`\n✅ Применено: ${applied.length} файл(ов)`))
+  console.log(chalk.gray(applied.join(', ')))
+  console.log(chalk.gray(`Бэкап: ${backupDir}`))
+  console.log(
+    chalk.yellow(`\nПерезапусти агента, чтобы изменения вступили в силу.\n`),
+  )
+}
+
+// ---------- /self-list ----------
+
+export async function selfList({ config }) {
+  const snapRoot = path.join(SNAP_ROOT)
+  let entries = []
+  try {
+    entries = await fs.readdir(snapRoot)
+  } catch {
+    console.log(chalk.gray('Снапшотов нет.'))
+    return
+  }
+
+  if (!entries.length) {
+    console.log(chalk.gray('Снапшотов нет.'))
+    return
+  }
+
+  entries.sort()
+  console.log(chalk.gray('Снапшоты самообзора:'))
+  for (const e of entries) {
+    const full = path.join(snapRoot, e)
+    const stat = await fs.stat(full).catch(() => null)
+    if (!stat || !stat.isDirectory()) continue
+    const report = path.join(full, '_report.md')
+    const hasReport = await fs
+      .stat(report)
+      .then(() => true)
+      .catch(() => false)
+    const changedCount = (await diffFiles(SRC_DIR, full)).length
+    const tag = changedCount
+      ? chalk.green(`[${changedCount} изменено]`)
+      : chalk.gray('[без правок]')
+    const rep = hasReport ? chalk.cyan('📋') : '  '
+    console.log(`  ${rep} ${e}  ${tag}`)
+  }
+  console.log()
+  console.log(chalk.gray('Команды: /self-diff <name>, /self-apply <name>\n'))
+}
+
+// ---------- helpers ----------
+
+async function diffFiles(origDir, newDir) {
+  const files = await fs.readdir(newDir).catch(() => [])
+  const changed = []
+  for (const f of files) {
+    if (!f.endsWith('.js')) continue
+    const a = await fs.readFile(path.join(origDir, f), 'utf-8').catch(() => '')
+    const b = await fs.readFile(path.join(newDir, f), 'utf-8').catch(() => '')
+    if (a !== b) changed.push(f)
+  }
+  return changed
+}
+
+function buildReviewPrompt({ focus, snapDir }) {
+  const focusLine = focus
+    ? `\nThe user asked you to focus especially on: ${focus}\n`
+    : ''
+
+  return `You are a senior JavaScript/Node.js engineer. You are reviewing your own source code — a Playwright-based coding agent that talks to the DeepSeek web chat as an LLM backend.
+
+All source files are in your working directory: ${snapDir}
+${focusLine}
+## Your job
+
+1. Read EVERY .js file in your working directory. Use Glob("**/*.js") to list them, then Read each one. Do not skip files.
+2. Identify real, concrete problems. Focus on:
+   - Race conditions and async/promise bugs (missing await, unhandled rejections, timing issues)
+   - Error handling gaps: places that can throw and crash the agent
+   - JSON parsing edge cases in agent-loop.js (LLM output is unreliable)
+   - Fragile DOM selectors in browser.js (DeepSeek changes layout)
+   - Cross-platform issues (Windows paths, cmd.exe vs bash, encoding)
+   - Undo/transcript consistency: could undo leave files in bad state?
+   - Self-review mode safety: could /self-apply corrupt src/?
+   - Anything that breaks state between interactive tasks (chat context, workdir, spinner)
+3. Fix what you can fix confidently. Use Edit (small targeted change) or Write (rewrite a file only if really needed). Keep the existing architecture and naming.
+4. Do NOT invent problems. If you're not sure, mention it in the report, don't change it.
+5. Do NOT touch package.json, node_modules, or files outside the working directory.
+
+## Constraints
+
+- You CANNOT run the agent itself (node_modules is not here). But you CAN use \`node --check <file>\` via Bash to verify syntax after edits.
+- Always read a file before editing it.
+- After all edits, run \`node --check\` on every file you changed. If any fails, fix the syntax error.
+
+## Report format
+
+When done, respond with a markdown report as the message:
+
+## Найдено
+- (bullet list of issues you found, with file:line if possible)
+
+## Исправлено
+- (bullet list: file — что именно изменил)
+
+## Не исправлено (осознанно)
+- (bullet list: what you left alone and why)
+
+## Проверка
+- (bullet list: what you verified, e.g. \`node --check\` results)
+
+Be honest and specific. If the code is fine in some area, say so.`
+}

package/src/spinner.js

@@ -0,0 +1,55 @@
+import ora from 'ora'
+import chalk from 'chalk'
+
+export function createSpinner() {
+  let spinner = null
+
+  const start = (text) => {
+    if (!spinner) spinner = ora(text).start()
+    else spinner.start(text)
+  }
+
+  const stop = () => {
+    if (spinner) spinner.stop()
+  }
+
+  const succeed = (text) => {
+    if (spinner) spinner.succeed(text)
+  }
+
+  const fail = (text) => {
+    if (spinner) spinner.fail(text)
+  }
+
+  return {
+    // Единственный метод, который ЗАПУСКАЕТ спиннер
+    thinking: () => start(chalk.gray('Думаю...')),
+
+    // Оба метода только останавливают и печатают — не перезапускают
+    toolCall: (name, args) => {
+      stop()
+      const preview = JSON.stringify(args).slice(0, 120)
+      console.log(chalk.yellow(`🔧 ${name}`), chalk.gray(preview))
+    },
+
+    toolResult: (result) => {
+      stop()
+      const text = typeof result === 'string' ? result : JSON.stringify(result)
+      const preview = text.slice(0, 200).replace(/\n/g, ' ↵ ')
+      console.log(chalk.gray(`   → ${preview}\n`))
+    },
+
+    assistant: (msg) => {
+      stop()
+      console.log(chalk.green('\n✅ ' + msg) + '\n')
+    },
+
+    taskHeader: (task) => {
+      console.log(chalk.bold.cyan(`\n🎯 Задача: ${task}\n`))
+    },
+
+    stop,
+    succeed,
+    fail,
+  }
+}

package/src/system-prompt.js

@@ -0,0 +1,84 @@
+export function buildSystemPrompt({ workdir, tools, gitContext = null }) {
+  const toolDescriptions = tools
+    .map(
+      (t) =>
+        `### ${t.name}\n${t.description}\nПараметры: ${JSON.stringify(t.parameters)}`,
+    )
+    .join('\n\n')
+
+  const gitSection = gitContext
+    ? `\n## Git context\n\n${gitContext}\n`
+    : '\n## Git context\n\nNot a git repository (or git is not installed).\n'
+
+  return `You are a coding agent running in a terminal. You help the user with software engineering tasks by reading files, writing code, running commands, and iterating until the task is done.
+
+You work in the directory: ${workdir}
+
+You have access to the following tools:
+
+${toolDescriptions}
+${gitSection}
+## How to use tools
+
+To call ONE tool, respond with ONLY a JSON object (no markdown fences, no extra text):
+
+{"tool": "tool_name", "args": {"param1": "value1"}}
+
+To call MULTIPLE tools at once (only if they are independent — e.g. reading several files), respond with a JSON array:
+
+[{"tool": "Read", "args": {"path": "a.js"}}, {"tool": "Read", "args": {"path": "b.js"}}]
+
+After the tool result(s) come back, decide the next action.
+
+To give a final answer to the user, respond with:
+
+{"tool": "respond", "args": {"message": "your final answer here"}}
+
+## Git
+
+- You CAN commit and push using GitAdd / GitCommit / GitPush. Prefer these over raw \`git\` through Bash.
+- Do NOT run \`git push --force\`, \`git reset --hard\`, \`git clean -fd\`, or rewrite history (rebase, amend published commits) unless the user explicitly asks.
+- Do NOT commit or push unless the user asked for it, or the task clearly implies it.
+- Before committing, check GitStatus and GitDiff so you know what goes in.
+- Commit messages: short imperative subject line, then optional body. Use \`git commit\` style, not emoji.
+- If \`git push\` fails due to credentials or non-fast-forward, report it to the user and stop — do NOT try to work around it.
+
+## CRITICAL: JSON escaping
+
+Your response MUST be valid JSON. This means:
+- Backslashes MUST be escaped: "C:\\\\Users\\\\name\\\\project"
+- OR use forward slashes for Windows paths: "C:/Users/name/project"
+- Quotes inside strings MUST be escaped: \\"
+- Newlines inside strings must be \\n
+
+When in doubt — use forward slashes for all file paths.
+
+## CRITICAL: quoting inside shell commands
+
+When you call Bash, put the whole shell command in a single JSON string.
+Inside that string:
+- Escape any double quote as \\"
+- Escape any backslash as \\\\
+- OR avoid quotes entirely. For Windows paths use forward slashes.
+- Pipes, redirects and chained commands work: "cd dir && dir /b"
+
+## Rules
+
+- Always read a file before editing it.
+- Prefer targeted edits over rewriting entire files.
+- Run tests or commands to verify your changes when possible.
+- If a tool call fails, read the error and try a different approach.
+- Keep responses concise. The user sees the terminal output.
+- Never output anything except JSON when you want to call a tool.
+- Your ENTIRE response must be exactly one JSON object (or array of objects).
+
+REMINDER: respond with exactly one JSON object or array. No text, no markdown, no explanations.
+## Web access
+
+- You have WebSearch and WebFetch. Use them when the answer requires current information (versions, changelogs, recent bugs, docs).
+- WebSearch uses DuckDuckGo. If results look stale or missing, try a different phrasing.
+- WebFetch strips HTML. If a page is JS-rendered and text comes back empty, call WebFetch again with render=true.
+- Do NOT fetch the same URL repeatedly. If content is missing, report that instead.
+- Do NOT use WebFetch on localhost, private IPs, or 'file://' — it will fail.
+`
+}

package/src/tools.js

@@ -0,0 +1,206 @@
+import fs from 'fs/promises'
+import path from 'path'
+import { exec } from 'child_process'
+import { createGitTools } from './gitTools.js'
+import { createWebTools } from './web.js'
+
+export function createTools(workdir, { undo } = {}) {
+  const root = path.resolve(workdir)
+  const safe = (p) => {
+    const resolved = path.resolve(root, p)
+    // startsWith(root) пропускал бы соседние пути с общим префиксом
+    // (C:\work\proj vs C:\work\proj-old). Считаем через relative().
+    const rel = path.relative(root, resolved)
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+      throw new Error(`Доступ за пределы рабочей директории: ${p}`)
+    }
+    return resolved
+  }
+
+  // Sandbox (вариант A): не даём команде выйти выше root.
+  // Это защитный барьер, а не полноценная изоляция ОС.
+  const assertCommandInsideRoot = (command) => {
+    const cmd = String(command || '')
+    const cdRe = /(?:^|[;&|]|\s)(?:cd|pushd)\s+([^;&|]+)/gi
+    let m
+    while ((m = cdRe.exec(cmd))) {
+      const raw = m[1].trim()
+      if (!raw || raw === '-') continue
+      const target = path.resolve(root, raw)
+      const rel = path.relative(root, target)
+      if (rel.startsWith('..') || path.isAbsolute(rel)) {
+        throw new Error('Sandbox: выход за пределы ' + root + ' запрещён (cd ' + raw + ')')
+      }
+    }
+  }
+  const runShell = (command, timeout = 30_000) =>
+    new Promise((resolve) => {
+      const options = {
+        cwd: workdir,
+        timeout,
+        maxBuffer: 1024 * 1024 * 8,
+        windowsHide: true,
+        env: { ...process.env },
+      }
+
+      if (process.platform === 'win32') {
+        options.shell = process.env.ComSpec || 'C:\\Windows\\System32\\cmd.exe'
+      } else {
+        options.shell = '/bin/sh'
+      }
+
+      exec(command, options, (err, stdout, stderr) => {
+        const out = (stdout || '').toString()
+        const errStr = (stderr || '').toString()
+
+        if (!err) {
+          const combined = (out + errStr).trim()
+          resolve(combined || '(команда выполнена без вывода)')
+          return
+        }
+
+        const parts = []
+
+        if (err.killed) {
+          parts.push(`⏱ Таймаут после ${timeout}ms — процесс убит.`)
+        } else if (err.code !== undefined && err.code !== null) {
+          parts.push(`Exit code: ${err.code}`)
+        } else if (err.signal) {
+          parts.push(`Убит сигналом: ${err.signal}`)
+        } else {
+          parts.push(`Ошибка: ${err.message}`)
+        }
+
+        if (out.trim()) parts.push(`stdout:\n${out.trim()}`)
+        if (errStr.trim()) parts.push(`stderr:\n${errStr.trim()}`)
+
+        resolve(parts.join('\n'))
+      })
+    })
+
+  const baseTools = [
+    {
+      name: 'Read',
+      description:
+        'Прочитать содержимое файла. Опционально: offset и limit (строки).',
+      parameters: { path: 'string', offset: 'number?', limit: 'number?' },
+      fn: async ({ path: p, offset, limit }) => {
+        const file = safe(p)
+        const content = await fs.readFile(file, 'utf-8')
+        const lines = content.split('\n')
+        const start = offset ?? 0
+        const end = limit ? start + limit : lines.length
+        return lines.slice(start, end).join('\n')
+      },
+    },
+
+    {
+      name: 'Write',
+      description: 'Создать или перезаписать файл.',
+      parameters: { path: 'string', content: 'string' },
+      fn: async ({ path: p, content }) => {
+        const file = safe(p)
+        if (undo) await undo.backup(file)
+        await fs.mkdir(path.dirname(file), { recursive: true })
+        await fs.writeFile(file, content, 'utf-8')
+        return `Файл записан: ${p}`
+      },
+    },
+
+    {
+      name: 'Edit',
+      description:
+        'Точечная замена строки в файле. old_string должен встречаться один раз.',
+      parameters: {
+        path: 'string',
+        old_string: 'string',
+        new_string: 'string',
+      },
+      fn: async ({ path: p, old_string, new_string }) => {
+        const file = safe(p)
+        if (typeof old_string !== 'string' || old_string === '') {
+          throw new Error('old_string пустой — нечего заменять.')
+        }
+        let content = await fs.readFile(file, 'utf-8')
+        const occurrences = content.split(old_string).length - 1
+        if (occurrences === 0) {
+          throw new Error(
+            `Строка не найдена в ${p}: "${old_string.slice(0, 60)}..."`,
+          )
+        }
+        if (occurrences > 1) {
+          throw new Error(
+            `Строка встречается ${occurrences} раз в ${p}. Уточните old_string.`,
+          )
+        }
+        if (undo) await undo.backup(file)
+        content = content.replace(old_string, new_string)
+        await fs.writeFile(file, content, 'utf-8')
+        return `Отредактирован: ${p}`
+      },
+    },
+
+    {
+      name: 'Bash',
+      description:
+        'Выполнить shell-команду в рабочей директории (cmd.exe на Windows, sh на Linux/macOS). ' +
+        'Не использовать для long-running процессов (серверы) — уйдут в таймаут. ' +
+        'Не использовать для команд, требующих интерактивного ввода. ' +
+        'Для git — инструменты Git*. Для интернета — WebFetch / WebSearch.',
+      parameters: { command: 'string', timeout: 'number?' },
+      fn: async ({ command, timeout }) => {
+        assertCommandInsideRoot(command)
+        return runShell(command, timeout)
+      },
+    },
+
+    {
+      name: 'Glob',
+      description: 'Найти файлы по glob-паттерну (например, "**/*.js").',
+      parameters: { pattern: 'string' },
+      fn: async ({ pattern }) => {
+        const { glob } = await import('fs/promises')
+        const results = []
+        for await (const f of glob(pattern, { cwd: workdir })) {
+          // Sandbox: игнорируем всё, что выходит за пределы root.
+          const abs = path.resolve(workdir, f)
+          const rel = path.relative(root, abs)
+          if (rel.startsWith('..') || path.isAbsolute(rel)) continue
+          results.push(f)
+        }
+        return results.length ? results.join('\n') : 'Ничего не найдено.'
+      },
+    },
+
+    {
+      name: 'Grep',
+      description: 'Поиск по содержимому файлов (регулярное выражение).',
+      parameters: { pattern: 'string', path: 'string?' },
+      fn: async ({ pattern, path: searchPath }) => {
+        const target = searchPath ? safe(searchPath) : workdir
+        if (process.platform === 'win32') {
+          const escaped = pattern.replace(/"/g, '\\"')
+          const scope = searchPath
+            ? '"' + target + '\\*'
+            : '*'
+          return runShell(`findstr /s /n /r /c:"${escaped}" ` + scope)
+        }
+        return runShell(
+          `grep -rn -E ${JSON.stringify(pattern)} ${JSON.stringify(target)} || true`,
+        )
+      },
+    },
+  ]
+
+  const gitTools = createGitTools(workdir)
+  const webTools = createWebTools()
+
+  const respondTool = {
+    name: 'respond',
+    description: 'Дать финальный ответ пользователю и завершить задачу.',
+    parameters: { message: 'string' },
+    fn: async ({ message }) => message,
+  }
+
+  return [...baseTools, ...gitTools, ...webTools, respondTool]
+}

package/src/transcript.js

@@ -0,0 +1,46 @@
+import fs from 'fs'
+import path from 'path'
+
+export class Transcript {
+  constructor({ dir, enabled = true, sessionName = 'session' } = {}) {
+    this.enabled = enabled
+    this.file = null
+    this.stream = null
+    this.startedAt = Date.now()
+
+    if (!enabled) return
+
+    try {
+      fs.mkdirSync(dir, { recursive: true })
+      const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+      this.file = path.join(dir, `${sessionName}-${stamp}.jsonl`)
+      this.stream = fs.createWriteStream(this.file, { flags: 'a' })
+      // Ошибки записи (диск переполнен, файл удалён и т.п.) приходят
+      // событием 'error'; без слушателя это uncaught exception.
+      this.stream.on('error', (e) => {
+        console.error(`transcript: ошибка записи: ${e.message}`)
+        this.enabled = false
+      })
+    } catch (e) {
+      console.error(`transcript: не удалось создать файл: ${e.message}`)
+      this.enabled = false
+    }
+  }
+
+  log(type, data = {}) {
+    if (!this.enabled || !this.stream) return
+    const entry = {
+      ts: new Date().toISOString(),
+      elapsed: Date.now() - this.startedAt,
+      type,
+      ...data,
+    }
+    try {
+      this.stream.write(JSON.stringify(entry) + '\n')
+    } catch {}
+  }
+
+  close() {
+    if (this.stream) this.stream.end()
+  }
+}