wtt-connect 0.1.0

package/src/shell-runner.js

@@ -0,0 +1,184 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { spawn } from 'node:child_process';
+
+const READONLY_COMMANDS = new Set([
+  'pwd', 'ls', 'find', 'cat', 'sed', 'grep', 'egrep', 'fgrep', 'rg',
+  'head', 'tail', 'wc', 'du', 'df', 'stat', 'file', 'tree',
+  'git', 'node', 'npm', 'python', 'python3', 'which', 'whoami',
+  'hostname', 'date', 'env', 'printenv',
+]);
+
+const READONLY_GIT_SUBCOMMANDS = new Set([
+  '', '--version', '-v', 'status', 'branch', 'rev-parse', 'log', 'show',
+  'diff', 'describe', 'remote', 'ls-files', 'ls-tree', 'grep', 'config',
+]);
+
+const READONLY_NPM_SUBCOMMANDS = new Set(['', '--version', '-v', 'version', 'view', 'list', 'ls', 'root', 'prefix']);
+
+const BLOCKED_PATTERNS = [
+  /\brm\s+-[^\n;|&]*r/i,
+  /\bsudo\b/i,
+  /\bsu\s+/i,
+  /\bchmod\s+777\b/i,
+  /\bchown\b/i,
+  /\bmkfs\b/i,
+  /\bdd\s+if=/i,
+  /\bshutdown\b/i,
+  /\breboot\b/i,
+  /\bcurl\b[\s\S]*\|\s*(sh|bash)\b/i,
+  /\bwget\b[\s\S]*\|\s*(sh|bash)\b/i,
+  /:\s*\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}/,
+  /`|\$\(/,
+];
+
+export async function runShellCommand(config, request) {
+  if (!config.enableShell) {
+    throw new Error('wtt-connect shell is disabled');
+  }
+
+  const command = String(request.command || '').trim();
+  if (!command) throw new Error('command is required');
+  validateCommand(command, config.shellMode);
+
+  const baseDir = resolveDir(config.workDir);
+  const cwd = resolveCwd(baseDir, request.cwd);
+  const timeoutMs = Math.max(1000, Math.min(Number(request.timeout_ms || 0) || config.shellTimeoutSeconds * 1000, config.shellTimeoutSeconds * 1000));
+  const maxOutput = Math.max(1000, Number(config.shellMaxOutputChars || 20000));
+  const startedAt = Date.now();
+
+  return await new Promise((resolve) => {
+    const child = spawn(command, {
+      cwd,
+      shell: process.env.SHELL || '/bin/sh',
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let killed = false;
+    const append = (current, chunk) => {
+      const next = current + chunk.toString('utf8');
+      if (next.length <= maxOutput) return next;
+      return next.slice(0, Math.floor(maxOutput / 2)) + '\n...[output truncated]...\n' + next.slice(-Math.floor(maxOutput / 2));
+    };
+
+    const timer = setTimeout(() => {
+      killed = true;
+      child.kill('SIGTERM');
+      setTimeout(() => {
+        if (!child.killed) child.kill('SIGKILL');
+      }, 1000);
+    }, timeoutMs);
+
+    child.stdout.on('data', (chunk) => { stdout = append(stdout, chunk); });
+    child.stderr.on('data', (chunk) => { stderr = append(stderr, chunk); });
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      resolve({
+        command,
+        cwd,
+        exit_code: 127,
+        stdout,
+        stderr: stderr || err.message,
+        duration_ms: Date.now() - startedAt,
+        timed_out: false,
+      });
+    });
+    child.on('close', (code, signal) => {
+      clearTimeout(timer);
+      resolve({
+        command,
+        cwd,
+        exit_code: killed ? 124 : (code ?? 1),
+        signal: signal || '',
+        stdout,
+        stderr: killed ? `${stderr}${stderr ? '\n' : ''}command timed out after ${timeoutMs}ms` : stderr,
+        duration_ms: Date.now() - startedAt,
+        timed_out: killed,
+      });
+    });
+  });
+}
+
+function validateCommand(command, mode) {
+  const effectiveMode = String(mode || 'unsafe').toLowerCase();
+  if (effectiveMode === 'off') throw new Error('wtt-connect shell mode is off');
+  if (effectiveMode === 'unsafe') return;
+
+  for (const pattern of BLOCKED_PATTERNS) {
+    if (pattern.test(command)) throw new Error('command is blocked by wtt-connect shell policy');
+  }
+
+  if (effectiveMode === 'readonly' && hasWriteOperator(command)) {
+    throw new Error('write/redirection operators are blocked in readonly shell mode');
+  }
+
+  for (const segment of commandSegments(command)) {
+    validateReadonlySegment(segment, effectiveMode);
+  }
+}
+
+function commandSegments(command) {
+  return String(command)
+    .split(/&&|\|\||;|\|/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+function validateReadonlySegment(segment, mode) {
+  const first = firstCommandToken(segment);
+  if (!READONLY_COMMANDS.has(first)) {
+    throw new Error(`command '${first || segment}' is not allowed in ${mode} shell mode`);
+  }
+
+  const tokens = segmentTokens(segment);
+  const subcommand = tokens.find((token, idx) => idx > 0 && !token.startsWith('-')) || tokens[1] || '';
+  if (first === 'git' && !READONLY_GIT_SUBCOMMANDS.has(subcommand)) {
+    throw new Error(`git ${subcommand} is not allowed in readonly shell mode`);
+  }
+  if (first === 'npm' && !READONLY_NPM_SUBCOMMANDS.has(subcommand)) {
+    throw new Error(`npm ${subcommand} is not allowed in readonly shell mode`);
+  }
+  if ((first === 'node' || first === 'python' || first === 'python3') && subcommand && !subcommand.startsWith('-')) {
+    throw new Error(`${first} scripts are blocked in readonly shell mode`);
+  }
+}
+
+function firstCommandToken(command) {
+  const trimmed = command.trim().replace(/^\s*(time|command|env)\s+/, '');
+  return (trimmed.match(/^([A-Za-z0-9_./-]+)/)?.[1] || '').split('/').pop() || '';
+}
+
+function segmentTokens(command) {
+  return command.trim().replace(/^\s*(time|command|env)\s+/, '').split(/\s+/).filter(Boolean).map((token) => token.split('/').pop() || token);
+}
+
+function hasWriteOperator(command) {
+  return /(^|[^<])>(?!>)|>>|\btee\b|\bxargs\b|\bmv\b|\bcp\b|\btouch\b|\bmkdir\b|\brmdir\b|\binstall\b|\bpatch\b|\bnpm\s+(install|i|add|run|publish|pack|link|unlink|ci|update|dedupe)\b|\bgit\s+(add|commit|checkout|switch|reset|restore|clean|pull|push|merge|rebase|cherry-pick|stash|tag|worktree)\b/i.test(command);
+}
+
+function resolveDir(dir) {
+  const resolved = path.resolve(String(dir || process.cwd()));
+  try {
+    return fs.realpathSync(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+function resolveCwd(baseDir, requested) {
+  if (!requested) return baseDir;
+  const joined = path.resolve(baseDir, String(requested));
+  let resolved = joined;
+  try {
+    resolved = fs.realpathSync(joined);
+  } catch {
+    // Directory may not exist; keep resolved path and let spawn fail.
+  }
+  if (resolved !== baseDir && !resolved.startsWith(`${baseDir}${path.sep}`)) {
+    throw new Error('cwd must stay inside agent workdir');
+  }
+  return resolved;
+}

package/src/smoke.js

@@ -0,0 +1,99 @@
+import { WTTApi } from './wtt-api.js';
+
+export async function smokeTask(config, argv = {}) {
+  if (!config.agentId) throw new Error('WTT_AGENT_ID is required');
+  const expected = argv.expected || 'WTT_CONNECT_TASK_READY';
+  const api = new WTTApi(config);
+  const task = await api.createTask({
+    title: 'wtt-connect task smoke',
+    description: argv.prompt || `请只回复 ${expected}。不要修改文件，不要运行命令。`,
+    task_type: 'code', priority: 'P3', status: 'todo',
+    owner_agent_id: config.agentId, runner_agent_id: config.agentId,
+    exec_mode: config.adapter || 'codex',
+  });
+  const taskId = task.id;
+  console.log(`created task=${taskId} topic=${task.topic_id || ''}`);
+  await api.runTask(taskId, { runner_agent_id: config.agentId, exec_mode: config.adapter || 'codex', note: 'wtt-connect smoke' });
+  const deadline = Date.now() + Number(argv.timeout || 180000);
+  let last = '';
+  while (Date.now() < deadline) {
+    await sleep(3000);
+    const payload = await api.getTask(taskId);
+    const status = payload?.status || '';
+    if (status !== last) { console.log(`status=${status}`); last = status; }
+    const output = payload?.output || payload?.summary || payload?.notes || '';
+    if (['review', 'done', 'approved'].includes(status)) {
+      console.log(output);
+      if (!String(output).includes(expected)) throw new Error(`expected ${expected} not found`);
+      console.log(`OK task=${taskId}`);
+      return;
+    }
+  }
+  throw new Error(`timeout waiting for task smoke`);
+}
+
+export async function smokeChat(config, argv = {}) {
+  const senderId = argv.senderAgentId || process.env.WTT_SMOKE_SENDER_AGENT_ID;
+  const senderToken = argv.senderToken || process.env.WTT_SMOKE_SENDER_TOKEN;
+  if (!senderId || !senderToken) throw new Error('WTT_SMOKE_SENDER_AGENT_ID/TOKEN required for chat smoke');
+  if (!config.agentId) throw new Error('WTT_AGENT_ID is required');
+  const expected = argv.expected || 'WTT_CONNECT_CHAT_READY';
+  const ws = new WebSocket(wsUrl(config.wttBaseUrl, senderId));
+  await onceOpen(ws, 15000);
+  await send(ws, { action: 'auth', request_id: rid('auth'), token: senderToken });
+  const topic = await action(ws, 'p2p', { target_agent_id: config.agentId, content: argv.message || `请只回复 ${expected}` });
+  const topicId = topic.topic_id || topic.id || topic.topic?.id;
+  console.log(`sent p2p topic=${topicId}`);
+  const deadline = Date.now() + Number(argv.timeout || 180000);
+  while (Date.now() < deadline) {
+    const raw = await recv(ws, Math.min(30000, Math.max(1000, deadline - Date.now())));
+    if (raw === 'pong') continue;
+    const msg = JSON.parse(raw);
+    if (msg.type !== 'new_message') continue;
+    const m = msg.message || {};
+    const content = String(m.content || '');
+    if (m.sender_id === config.agentId && content.includes(expected)) {
+      console.log(content);
+      console.log('OK');
+      ws.close();
+      return;
+    }
+  }
+  ws.close();
+  throw new Error('timeout waiting for chat smoke');
+}
+
+function wsUrl(base, agentId) {
+  const b = String(base).replace(/\/$/, '').replace(/^https:/, 'wss:').replace(/^http:/, 'ws:');
+  return `${b}/ws/${agentId}`;
+}
+function rid(prefix) { return `${prefix}-${crypto.randomUUID().slice(0, 8)}`; }
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+function send(ws, obj) { ws.send(JSON.stringify(obj)); }
+function recv(ws, timeout) {
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(() => reject(new Error('websocket recv timeout')), timeout);
+    ws.addEventListener('message', (ev) => { clearTimeout(t); resolve(String(ev.data)); }, { once: true });
+    ws.addEventListener('error', () => { clearTimeout(t); reject(new Error('websocket error')); }, { once: true });
+  });
+}
+function onceOpen(ws, timeout) {
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(() => reject(new Error('websocket open timeout')), timeout);
+    ws.addEventListener('open', () => { clearTimeout(t); resolve(); }, { once: true });
+    ws.addEventListener('error', () => { clearTimeout(t); reject(new Error('websocket open error')); }, { once: true });
+  });
+}
+async function action(ws, name, payload) {
+  const requestId = rid(name);
+  send(ws, { action: name, request_id: requestId, ...payload });
+  while (true) {
+    const raw = await recv(ws, 20000);
+    if (raw === 'pong') continue;
+    const msg = JSON.parse(raw);
+    if (msg.type === 'action_result' && msg.request_id === requestId) {
+      if (!msg.ok) throw new Error(String(msg.error || 'action failed'));
+      return msg.data;
+    }
+  }
+}

package/src/store.js

@@ -0,0 +1,58 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export class DurableStore {
+  constructor(file) {
+    this.file = file;
+    this.data = { version: 1, sessions: {}, seen: {}, artifacts: [] };
+    this.loaded = false;
+  }
+
+  load() {
+    if (this.loaded) return this;
+    this.loaded = true;
+    try {
+      if (fs.existsSync(this.file)) this.data = { ...this.data, ...JSON.parse(fs.readFileSync(this.file, 'utf8')) };
+    } catch {
+      this.data = { version: 1, sessions: {}, seen: {}, artifacts: [] };
+    }
+    return this;
+  }
+
+  save() {
+    fs.mkdirSync(path.dirname(this.file), { recursive: true });
+    const tmp = `${this.file}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(this.data, null, 2));
+    fs.renameSync(tmp, this.file);
+  }
+
+  getSession(sessionKey) {
+    this.load();
+    return this.data.sessions[sessionKey] || {};
+  }
+
+  patchSession(sessionKey, patch) {
+    this.load();
+    this.data.sessions[sessionKey] = { ...(this.data.sessions[sessionKey] || {}), ...patch, updatedAt: new Date().toISOString() };
+    this.save();
+  }
+
+  hasSeen(id, ttlMs = 24 * 3600_000) {
+    this.load();
+    const now = Date.now();
+    for (const [k, ts] of Object.entries(this.data.seen || {})) {
+      if (now - Number(ts) > ttlMs) delete this.data.seen[k];
+    }
+    if (this.data.seen[id]) return true;
+    this.data.seen[id] = now;
+    this.save();
+    return false;
+  }
+
+  addArtifact(item) {
+    this.load();
+    this.data.artifacts.push({ ...item, createdAt: new Date().toISOString() });
+    this.data.artifacts = this.data.artifacts.slice(-500);
+    this.save();
+  }
+}

package/src/stt.js

@@ -0,0 +1,146 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+export class STTManager {
+  constructor(config) {
+    this.config = config;
+  }
+
+  async transcribe(file) {
+    const provider = normalizeProvider(this.config.stt.provider);
+    if (!provider || provider === 'none') return '';
+    if (provider === 'command') return runCommandTemplate(this.config.stt.command, file.path);
+    if (provider === 'openai') return transcribeWithOpenAI(this.config.stt, file);
+    throw new Error(`unsupported STT provider: ${this.config.stt.provider}`);
+  }
+
+  async transcribeAll(files = []) {
+    const audio = files.filter((f) => String(f.mimeType || '').startsWith('audio/'));
+    const out = [];
+    for (const f of audio) {
+      const text = (await this.transcribe(f)).trim();
+      if (text) out.push({ file: f, text });
+    }
+    return out;
+  }
+}
+
+function normalizeProvider(provider) {
+  const p = String(provider || '').trim().toLowerCase();
+  if (['openai', 'whisper', 'openai-whisper'].includes(p)) return 'openai';
+  return p;
+}
+
+async function transcribeWithOpenAI(sttConfig, file) {
+  const apiKey = sttConfig.openaiApiKey || process.env.OPENAI_API_KEY;
+  if (!apiKey) throw new Error('OPENAI_API_KEY is required for OpenAI STT provider');
+  const base = String(sttConfig.openaiBaseUrl || process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1').replace(/\/$/, '');
+  const model = sttConfig.openaiModel || 'whisper-1';
+  const timeoutMs = Number(sttConfig.timeoutMs || 120000);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const bytes = await fs.readFile(file.path);
+    const form = new FormData();
+    form.append('file', new Blob([bytes], { type: file.mimeType || 'application/octet-stream' }), file.name || path.basename(file.path));
+    form.append('model', model);
+    if (sttConfig.language) form.append('language', sttConfig.language);
+    if (sttConfig.prompt) form.append('prompt', sttConfig.prompt);
+    if (sttConfig.responseFormat) form.append('response_format', sttConfig.responseFormat);
+    const transport = String(sttConfig.openaiTransport || 'auto').toLowerCase();
+    if (transport === 'curl') return parseOpenAITranscript(await runOpenAICurl({ sttConfig, file, apiKey, base, model }));
+    try {
+      const response = await fetch(`${base}/audio/transcriptions`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${apiKey}` },
+        body: form,
+        signal: controller.signal,
+      });
+      const raw = await response.text();
+      if (!response.ok) throw new Error(`OpenAI STT failed: ${response.status} ${sanitizeProviderError(raw)}`);
+      return parseOpenAITranscript(raw);
+    } catch (err) {
+      if (transport === 'fetch') throw err;
+      return parseOpenAITranscript(await runOpenAICurl({ sttConfig, file, apiKey, base, model }));
+    }
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function parseOpenAITranscript(raw) {
+  try {
+    const json = JSON.parse(raw);
+    return String(json.text || json.transcript || '').trim();
+  } catch {
+    return String(raw || '').trim();
+  }
+}
+
+async function runOpenAICurl({ sttConfig, file, apiKey, base, model }) {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'wtt-connect-stt-'));
+  const cfg = path.join(tmpDir, 'curl.conf');
+  const lines = [
+    `url = ${curlQuote(`${base}/audio/transcriptions`)}`,
+    'request = "POST"',
+    'silent',
+    'show-error',
+    'fail-with-body',
+    `max-time = ${Math.ceil(Number(sttConfig.timeoutMs || 120000) / 1000)}`,
+    `header = ${curlQuote(`Authorization: Bearer ${apiKey}`)}`,
+    `form = ${curlQuote(`file=@${file.path};type=${file.mimeType || 'application/octet-stream'};filename=${file.name || path.basename(file.path)}`)}`,
+    `form = ${curlQuote(`model=${model}`)}`,
+  ];
+  if (sttConfig.language) lines.push(`form = ${curlQuote(`language=${sttConfig.language}`)}`);
+  if (sttConfig.prompt) lines.push(`form = ${curlQuote(`prompt=${sttConfig.prompt}`)}`);
+  if (sttConfig.responseFormat) lines.push(`form = ${curlQuote(`response_format=${sttConfig.responseFormat}`)}`);
+  await fs.writeFile(cfg, `${lines.join('\n')}\n`, { mode: 0o600 });
+  try {
+    return await runCommand('curl', ['--config', cfg]);
+  } finally {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+}
+
+function curlQuote(value) {
+  return `"${String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\n', ' ')}"`;
+}
+
+function runCommand(command, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => { stdout += d.toString(); });
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+    child.on('error', reject);
+    child.on('close', (code) => code === 0 ? resolve(stdout) : reject(new Error(`${command} exited ${code}: ${sanitizeProviderError(`${stderr}\n${stdout}`)}`)));
+  });
+}
+
+function runCommandTemplate(template, file) {
+  if (!template) throw new Error('WTT_CONNECT_STT_COMMAND is required for command STT provider');
+  const command = template.replaceAll('{file}', shellQuote(file));
+  return new Promise((resolve, reject) => {
+    const child = spawn('/bin/sh', ['-lc', command], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => { stdout += d.toString(); });
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+    child.on('error', reject);
+    child.on('close', (code) => code === 0 ? resolve(stdout) : reject(new Error(`STT command exited ${code}: ${stderr}`)));
+  });
+}
+
+function sanitizeProviderError(text) {
+  return String(text || '')
+    .replace(/sk-[A-Za-z0-9_-]{8,}/g, 'sk-***')
+    .replace(/wtt-tok-[A-Za-z0-9_-]{8,}/g, 'wtt-tok-***')
+    .trim();
+}
+
+function shellQuote(s) {
+  return `'${String(s).replaceAll("'", "'\\''")}'`;
+}

package/src/terminal-session.js

@@ -0,0 +1,152 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import * as pty from 'node-pty';
+import { log } from './logger.js';
+
+const require = createRequire(import.meta.url);
+
+export class TerminalSessionManager {
+  constructor(config, sendJson) {
+    this.config = config;
+    this.sendJson = sendJson;
+    this.sessions = new Map();
+  }
+
+  async open(msg) {
+    if (!this.config.enableShell) {
+      await this.sendError(msg.session_id, 'wtt-connect shell is disabled');
+      return;
+    }
+
+    const sessionId = String(msg.session_id || '');
+    if (!sessionId) return;
+    if (this.sessions.has(sessionId)) this.close(sessionId);
+
+    const baseDir = resolveDir(this.config.workDir);
+    const cwd = resolveCwd(baseDir, msg.cwd);
+    const shell = process.env.SHELL || (os.platform() === 'win32' ? 'powershell.exe' : '/bin/sh');
+    const cols = clampInt(msg.cols, 40, 240, 100);
+    const rows = clampInt(msg.rows, 10, 80, 28);
+
+    try {
+      ensureNodePtyHelperExecutable();
+      const proc = pty.spawn(shell, [], {
+        name: 'xterm-256color',
+        cols,
+        rows,
+        cwd,
+        env: {
+          ...process.env,
+          TERM: 'xterm-256color',
+          WTT_TERMINAL_SESSION_ID: sessionId,
+          WTT_CONNECT_AGENT_ID: this.config.agentId,
+        },
+      });
+
+      const session = { id: sessionId, proc, cwd, closed: false };
+      this.sessions.set(sessionId, session);
+
+      proc.onData((data) => {
+        this.sendJson({ type: 'terminal_output', session_id: sessionId, data }).catch((err) => {
+          log('warn', 'terminal output relay failed', { sessionId, error: err.message });
+        });
+      });
+
+      proc.onExit(({ exitCode, signal }) => {
+        this.sessions.delete(sessionId);
+        this.sendJson({
+          type: 'terminal_exit',
+          session_id: sessionId,
+          exit_code: exitCode,
+          signal: signal || '',
+        }).catch(() => {});
+      });
+
+      await this.sendJson({
+        type: 'terminal_output',
+        session_id: sessionId,
+        data: `\r\n[WTT terminal attached: ${cwd}]\r\n`,
+      });
+      log('info', 'terminal opened', { sessionId, cwd, shell });
+    } catch (err) {
+      await this.sendError(sessionId, err.message || String(err));
+    }
+  }
+
+  input(msg) {
+    const session = this.sessions.get(String(msg.session_id || ''));
+    if (!session) return;
+    session.proc.write(String(msg.data || ''));
+  }
+
+  resize(msg) {
+    const session = this.sessions.get(String(msg.session_id || ''));
+    if (!session) return;
+    const cols = clampInt(msg.cols, 40, 240, 100);
+    const rows = clampInt(msg.rows, 10, 80, 28);
+    try {
+      session.proc.resize(cols, rows);
+    } catch (err) {
+      log('warn', 'terminal resize failed', { sessionId: session.id, error: err.message });
+    }
+  }
+
+  close(sessionId) {
+    const sid = String(sessionId || '');
+    const session = this.sessions.get(sid);
+    if (!session) return;
+    this.sessions.delete(sid);
+    try {
+      session.proc.kill();
+    } catch {
+      // process may already be gone
+    }
+  }
+
+  closeAll() {
+    for (const sid of Array.from(this.sessions.keys())) this.close(sid);
+  }
+
+  async sendError(sessionId, error) {
+    if (!sessionId) return;
+    await this.sendJson({
+      type: 'terminal_error',
+      session_id: sessionId,
+      error: String(error || 'terminal error'),
+    });
+  }
+}
+
+function resolveDir(dir) {
+  const resolved = path.resolve(String(dir || process.cwd()));
+  if (!fs.existsSync(resolved)) fs.mkdirSync(resolved, { recursive: true });
+  return fs.realpathSync(resolved);
+}
+
+function resolveCwd(baseDir, requested) {
+  if (!requested) return baseDir;
+  const raw = String(requested);
+  const resolved = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(baseDir, raw);
+  const real = fs.existsSync(resolved) ? fs.realpathSync(resolved) : resolved;
+  return fs.existsSync(real) ? real : baseDir;
+}
+
+function clampInt(value, min, max, fallback) {
+  const n = Number.parseInt(String(value || ''), 10);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.max(min, Math.min(max, n));
+}
+
+function ensureNodePtyHelperExecutable() {
+  if (os.platform() !== 'darwin') return;
+  try {
+    const pkg = require.resolve('node-pty/package.json');
+    const arch = os.arch() === 'arm64' ? 'arm64' : 'x64';
+    const helper = path.join(path.dirname(pkg), 'prebuilds', `darwin-${arch}`, 'spawn-helper');
+    if (fs.existsSync(helper)) fs.chmodSync(helper, 0o755);
+  } catch {
+    // node-pty may be source-built or installed in a different layout.
+  }
+}

package/src/tts.js

@@ -0,0 +1,40 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+export class TTSManager {
+  constructor(config) {
+    this.config = config;
+  }
+
+  async synthesize(text, name = 'speech') {
+    const provider = this.config.tts.provider;
+    if (!provider || provider === 'none') return null;
+    await fs.mkdir(this.config.tts.outDir, { recursive: true });
+    if (provider === 'macos-say') return this.macosSay(text, name);
+    throw new Error(`unsupported TTS provider: ${provider}`);
+  }
+
+  async macosSay(text, name) {
+    const out = path.join(this.config.tts.outDir, `${safeName(name)}-${Date.now()}.wav`);
+    const args = [];
+    if (this.config.tts.voice) args.push('-v', this.config.tts.voice);
+    args.push('-o', out, '--file-format=WAVE', text);
+    await run('say', args);
+    return { path: out, mimeType: 'audio/wav' };
+  }
+}
+
+function safeName(s) {
+  return String(s || 'speech').replace(/[^a-zA-Z0-9._-]+/g, '-').slice(0, 80);
+}
+
+function run(bin, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+    let stderr = '';
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+    child.on('error', reject);
+    child.on('close', (code) => code === 0 ? resolve() : reject(new Error(`${bin} exited ${code}: ${stderr}`)));
+  });
+}