@lardexx/arenacode 0.0.0-stage → 2.5.3

package/src/config.js

@@ -0,0 +1,141 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const VERSION = '2.5.2';
+const CLIENT_NAME = `ArenaCode ${VERSION}`;
+
+/**
+ * Config file location. Mirrors the desktop client (which uses
+ * %APPDATA%\ArenaCode\config.ini) but stores JSON so it stays portable
+ * between Windows, macOS and Linux.
+ */
+function configPath() {
+  if (process.env.ARENACODE_CONFIG) return path.resolve(process.env.ARENACODE_CONFIG);
+  if (process.platform === 'win32') {
+    const base = process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming');
+    return path.join(base, 'ArenaCode', 'config.json');
+  }
+  return path.join(os.homedir(), '.arenacode', 'config.json');
+}
+
+const DEFAULTS = {
+  url: '',
+  key: '',
+  folder: '',
+  lang: 'it',
+  mode: 'agent',
+  pc_access: true,
+  device: '',
+  vision: false,
+  idle_timeout: 180,
+};
+
+function readConfig() {
+  const file = configPath();
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return { ...DEFAULTS, ...raw };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+function writeConfig(cfg) {
+  const file = configPath();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const clean = { ...DEFAULTS, ...cfg };
+  fs.writeFileSync(file, JSON.stringify(clean, null, 2), 'utf8');
+  try {
+    fs.chmodSync(file, 0o600);
+  } catch {
+    /* Windows: no POSIX modes */
+  }
+  return file;
+}
+
+function patchConfig(patch) {
+  return writeConfig({ ...readConfig(), ...patch });
+}
+
+/**
+ * X-Arena-Device: the desktop client sends the Windows MachineGuid, which is what
+ * binds an API key to one PC. We use the same value where it exists, and fall back
+ * to the machine-id / a generated id elsewhere. Must match ^[A-Za-z0-9-]{8,128}$.
+ */
+function readMachineGuid() {
+  if (process.platform === 'win32') {
+    try {
+      const out = execFileSync('reg', ['query', 'HKLM\\SOFTWARE\\Microsoft\\Cryptography', '/v', 'MachineGuid'], {
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: 5000,
+      });
+      const match = /MachineGuid\s+REG_SZ\s+([0-9a-fA-F-]{8,})/.exec(out);
+      if (match) return match[1];
+    } catch {
+      /* fall through */
+    }
+  }
+  try {
+    const id = fs.readFileSync('/etc/machine-id', 'utf8').trim();
+    if (id) return id;
+  } catch {
+    /* fall through */
+  }
+  return '';
+}
+
+function deviceId(cfg = readConfig()) {
+  const valid = (v) => /^[A-Za-z0-9-]{8,128}$/.test(String(v || ''));
+  if (valid(cfg.device)) return cfg.device;
+  const guid = readMachineGuid();
+  if (valid(guid)) {
+    try {
+      patchConfig({ device: guid });
+    } catch {
+      /* read-only config: keep it in memory */
+    }
+    return guid;
+  }
+  const generated = crypto.createHash('sha256').update(`${os.hostname()}:${os.userInfo().username}`).digest('hex').slice(0, 32);
+  try {
+    patchConfig({ device: generated });
+  } catch {
+    /* ignore */
+  }
+  return generated;
+}
+
+/** Bridge base URL: --url flag, then ARENACODE_URL, then config. */
+function resolveUrl(cfg, flagUrl) {
+  const url = String(flagUrl || process.env.ARENACODE_URL || cfg.url || '').trim().replace(/\/+$/, '');
+  return url;
+}
+
+function resolveKey(cfg, flagKey) {
+  return String(flagKey || process.env.ARENACODE_KEY || cfg.key || '').trim();
+}
+
+function openFolder(cfg, flagFolder) {
+  const folder = path.resolve(flagFolder || process.env.ARENACODE_FOLDER || cfg.folder || process.cwd());
+  return folder;
+}
+
+module.exports = {
+  VERSION,
+  CLIENT_NAME,
+  DEFAULTS,
+  configPath,
+  readConfig,
+  writeConfig,
+  patchConfig,
+  deviceId,
+  resolveUrl,
+  resolveKey,
+  openFolder,
+};

package/src/local.js

@@ -0,0 +1,507 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn, execFileSync } = require('node:child_process');
+
+const { c, ask, askKey, write, indentLines } = require('./ui');
+
+const MAX_READ_BYTES = 2 * 1024 * 1024;
+const MAX_MATCHES = 200;
+const SKIP_DIRS = new Set(['.git', 'node_modules', '.venv', 'venv', '__pycache__', 'dist', 'build', 'target', '.next']);
+
+const REFUSED = {
+  it: "[ArenaCode] Comando non eseguito: rifiutato dall'utente",
+  en: '[ArenaCode] Command not run: rejected by the user',
+  es: '[ArenaCode] Comando no ejecutado: rechazado por el usuario',
+};
+
+function t(lang, it, en, es) {
+  if (lang === 'en') return en;
+  if (lang === 'es') return es;
+  return it;
+}
+
+/** Resolve a path inside the open folder, refusing escapes and absolute paths. */
+function resolveInRoot(root, rel) {
+  const clean = String(rel || '').replace(/\\/g, '/').trim();
+  const abs = path.isAbsolute(clean) ? clean : path.resolve(root, clean);
+  const rootResolved = path.resolve(root);
+  if (abs !== rootResolved && !abs.startsWith(rootResolved + path.sep)) {
+    throw new Error(`path outside the open folder: ${rel}`);
+  }
+  return abs;
+}
+
+function relativize(root, abs) {
+  const rel = path.relative(root, abs).replace(/\\/g, '/');
+  return rel === '' ? '.' : rel;
+}
+
+// --------------------------------------------------------------------------- //
+// Local terminal (local-exec)
+// --------------------------------------------------------------------------- //
+
+function shellCommand(shell, command) {
+  if (process.platform === 'win32') {
+    switch (shell) {
+      case 'cmd':
+        return { file: 'cmd.exe', args: ['/d', '/s', '/c', command] };
+      case 'wsl':
+        return { file: 'wsl.exe', args: ['sh', '-lc', command] };
+      case 'powershell':
+      default:
+        return {
+          file: shell === 'pwsh' ? 'pwsh.exe' : 'powershell.exe',
+          args: ['-NoProfile', '-NonInteractive', '-Command', command],
+        };
+    }
+  }
+  return { file: '/bin/sh', args: ['-lc', command] };
+}
+
+/** Runs a command and collects stdout+stderr and the exit code. */
+function runShell(command, { cwd, shell, quiet = false } = {}) {
+  const { file, args } = shellCommand(shell, command);
+  return new Promise((resolve) => {
+    let out = '';
+    let child;
+    try {
+      child = spawn(file, args, { cwd, windowsHide: true, env: process.env });
+    } catch (e) {
+      resolve({ output: `${e.message}\n`, code: 127 });
+      return;
+    }
+    child.stdout.on('data', (d) => {
+      out += d.toString();
+      // in the TUI the output is rendered inside the card, never written raw to the screen
+      if (!quiet && !process.env.ARENACODE_QUIET_STREAM) process.stdout.write(c.gray(d.toString()));
+    });
+    child.stderr.on('data', (d) => {
+      out += d.toString();
+      if (!quiet) process.stderr.write(c.gray(d.toString()));
+    });
+    child.on('error', (e) => resolve({ output: `${out}${e.message}\n`, code: 127 }));
+    child.on('close', (code) => resolve({ output: out, code: code === null ? 1 : code }));
+  });
+}
+
+async function handleLocalExec(bridge, taskId, request, opts) {
+  const { rid, command, cwd: reqCwd, shell, admin, sandbox_reason: sandboxReason } = request;
+  const lang = opts.lang;
+  const dir = reqCwd ? resolveInRoot(opts.folder, reqCwd) : opts.folder;
+
+  write('');
+  write(`  ${c.bold(c.yellow('⌘ terminal'))} ${c.dim('·')} ${c.cyan(shell || 'shell')} ${c.dim('·')} ${c.gray(dir)}`);
+  write(indentLines(command, '    '));
+  if (admin) write(`  ${c.yellow('!')} ${t(lang, 'Richiede i permessi di amministratore: qui il comando gira senza UAC.', 'Needs administrator rights: here it runs without UAC.', 'Necesita permisos de administrador: aquí se ejecuta sin UAC.')}`);
+  if (sandboxReason) write(`  ${c.yellow('!')} ${t(lang, 'L’agente chiede di installare sul PC', 'The agent asks to install on the PC', 'El agente pide instalar en el PC')}: ${c.gray(sandboxReason)}`);
+
+  let approved = opts.yes === true;
+  if (!approved) {
+    const key = await askKey(`  ${t(lang, 'Eseguo? [r] sì  [d] no', 'Run it? [r] yes  [d] no', '¿Ejecuto? [r] sí  [d] no')} `, ['r', 'd']);
+    approved = key === 'r';
+  }
+  if (!approved) {
+    await bridge.localResult(taskId, { rid, output: REFUSED[lang] || REFUSED.it, code: -1 });
+    write(`  ${c.red('✗')} ${t(lang, 'rifiutato', 'rejected', 'rechazado')}`);
+    return true;
+  }
+
+  const { output, code } = await runShell(command, { cwd: dir, shell });
+  await bridge.localResult(taskId, { rid, output, code });
+  write(`  ${code === 0 ? c.green('✓') : c.red('✗')} ${c.gray(`exit ${code}`)}`);
+  return true;
+}
+
+// --------------------------------------------------------------------------- //
+// Local files (local-fs)
+// --------------------------------------------------------------------------- //
+
+function looksBinary(buffer) {
+  const slice = buffer.subarray(0, 4096);
+  for (const byte of slice) if (byte === 0) return true;
+  return false;
+}
+
+function walk(root, dir, depth, out, maxDepth) {
+  if (depth > maxDepth) return;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name)) continue;
+    const abs = path.join(dir, entry.name);
+    out.push({ abs, dir: entry.isDirectory() });
+    if (entry.isDirectory() && out.length < 5000) walk(root, abs, depth + 1, out, maxDepth);
+  }
+}
+
+function globToRegex(glob) {
+  const escaped = String(glob).replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*').replace(/\?/g, '.');
+  return new RegExp(`^${escaped}$`, 'i');
+}
+
+function git(args, cwd) {
+  try {
+    const out = execFileSync('git', args, { cwd, encoding: 'utf8', timeout: 30_000, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    return { ok: true, output: out };
+  } catch (e) {
+    return { ok: false, output: `${(e.stdout || '') + (e.stderr || '') || e.message}`.trim(), code: e.status };
+  }
+}
+
+/** Executes one local-fs operation and returns the JSON the agent expects. */
+function runFsOp(op, body, root) {
+  const rel = body.path || '';
+  const abs = rel ? resolveInRoot(root, rel) : root;
+
+  switch (op) {
+    case 'ls': {
+      const entries = [];
+      const target = abs;
+      if (!fs.existsSync(target)) return { ok: false, error: `not found: ${rel}` };
+      const maxDepth = Number.isFinite(body.depth) ? body.depth : 1;
+      const list = [{ abs: target, dir: true }];
+      for (let d = 0; d < maxDepth; d += 1) {
+        const snapshot = list.slice();
+        for (const item of snapshot) {
+          if (!item.dir) continue;
+          let children = [];
+          try {
+            children = fs.readdirSync(item.abs, { withFileTypes: true });
+          } catch {
+            continue;
+          }
+          for (const child of children) {
+            if (child.name.startsWith('.') || SKIP_DIRS.has(child.name)) continue;
+            list.push({ abs: path.join(item.abs, child.name), dir: child.isDirectory() });
+          }
+        }
+      }
+      const seen = new Set();
+      for (const item of list.slice(1)) {
+        if (seen.has(item.abs)) continue;
+        seen.add(item.abs);
+        let size = 0;
+        try {
+          size = item.dir ? 0 : fs.statSync(item.abs).size;
+        } catch {
+          /* ignore */
+        }
+        entries.push({ path: relativize(root, item.abs), name: path.basename(item.abs), dir: item.dir, size });
+      }
+      return { ok: true, path: rel || '.', root: path.basename(root), entries, truncated: false };
+    }
+
+    case 'stat': {
+      if (!fs.existsSync(abs)) return { ok: false, error: `not found: ${rel}` };
+      const st = fs.statSync(abs);
+      return { ok: true, path: rel, dir: st.isDirectory(), size: st.isDirectory() ? 0 : st.size, mtime: Math.floor(st.mtimeMs / 1000) };
+    }
+
+    case 'read':
+    case 'pull': {
+      if (!fs.existsSync(abs)) return { ok: false, error: `not found: ${rel}` };
+      const st = fs.statSync(abs);
+      if (st.isDirectory()) return { ok: false, error: `is a directory: ${rel}` };
+      const raw = fs.readFileSync(abs);
+      const binary = looksBinary(raw);
+      const truncated = raw.length > MAX_READ_BYTES;
+      const slice = truncated ? raw.subarray(0, MAX_READ_BYTES) : raw;
+      return {
+        ok: true,
+        path: rel,
+        size: st.size,
+        binary,
+        truncated,
+        content: binary ? undefined : slice.toString('utf8'),
+        b64: binary ? slice.toString('base64') : undefined,
+      };
+    }
+
+    case 'write': {
+      const data = body.b64 ? Buffer.from(String(body.content || ''), 'base64') : Buffer.from(String(body.content ?? ''), 'utf8');
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      if (body.append) fs.appendFileSync(abs, data);
+      else fs.writeFileSync(abs, data);
+      return { ok: true, path: rel, size: data.length };
+    }
+
+    case 'replace': {
+      if (!fs.existsSync(abs)) return { ok: false, error: `not found: ${rel}` };
+      const before = fs.readFileSync(abs, 'utf8');
+      const oldText = String(body.old ?? '');
+      const newText = String(body.new ?? '');
+      if (!oldText) return { ok: false, error: 'old is empty' };
+      if (!before.includes(oldText)) return { ok: false, error: 'old text not found in the file', path: rel };
+      const count = before.split(oldText).length - 1;
+      const after = body.all ? before.split(oldText).join(newText) : before.replace(oldText, newText);
+      fs.writeFileSync(abs, after, 'utf8');
+      return { ok: true, path: rel, replaced: body.all ? count : 1, size: Buffer.byteLength(after) };
+    }
+
+    case 'mkdir':
+      fs.mkdirSync(abs, { recursive: true });
+      return { ok: true, path: rel };
+
+    case 'mv': {
+      const dest = resolveInRoot(root, body.to);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.renameSync(abs, dest);
+      return { ok: true, path: rel, to: body.to };
+    }
+
+    case 'rm': {
+      if (abs === path.resolve(root)) return { ok: false, error: 'refusing to delete the open folder' };
+      if (!fs.existsSync(abs)) return { ok: false, error: `not found: ${rel}` };
+      fs.rmSync(abs, { recursive: Boolean(body.recursive) || fs.statSync(abs).isDirectory(), force: false });
+      return { ok: true, path: rel };
+    }
+
+    case 'find': {
+      const pattern = body.pattern ? new RegExp(String(body.pattern), 'i') : null;
+      const glob = body.glob ? globToRegex(body.glob) : null;
+      const max = Number.isFinite(body.max) ? body.max : MAX_MATCHES;
+      const files = [];
+      walk(root, abs, 0, files, 12);
+      const matches = [];
+      for (const entry of files) {
+        if (entry.dir) continue;
+        const relPath = relativize(root, entry.abs);
+        if (glob && !glob.test(path.basename(entry.abs)) && !glob.test(relPath)) continue;
+        if (!pattern) {
+          matches.push({ path: relPath });
+          if (matches.length >= max) return { ok: true, matches, truncated: true };
+          continue;
+        }
+        let text = '';
+        try {
+          const buf = fs.readFileSync(entry.abs);
+          if (looksBinary(buf)) continue;
+          text = buf.toString('utf8');
+        } catch {
+          continue;
+        }
+        const lines = text.split('\n');
+        for (let i = 0; i < lines.length; i += 1) {
+          if (pattern.test(lines[i])) {
+            matches.push({ path: relPath, line: i + 1, text: lines[i].slice(0, 400) });
+            if (matches.length >= max) return { ok: true, matches, truncated: true };
+          }
+        }
+      }
+      return { ok: true, matches, truncated: false };
+    }
+
+    // --- git ---------------------------------------------------------------
+    case 'git_status': {
+      const r = git(['status', '--short', '--branch'], root);
+      return { ok: r.ok, output: r.output };
+    }
+    case 'git_log': {
+      const args = ['log', '--pretty=%h %s', '-n', String(body.count || 15)];
+      if (body.ref) args.push(`--grep=${body.ref}`, '-i');
+      const r = git(args, root);
+      return { ok: r.ok, output: r.output, commits: r.output.split('\n').filter(Boolean).map((l) => l.trim()) };
+    }
+    case 'git_diff': {
+      const args = ['diff'];
+      if (body.ref) args.push(`${body.ref}~1`, body.ref);
+      if (body.path) args.push('--', body.path);
+      const r = git(args, root);
+      return { ok: r.ok, output: r.output };
+    }
+    case 'git_commit': {
+      const add = git(['add', '-A'], root);
+      if (!add.ok) return { ok: false, error: add.output };
+      const commit = git(['commit', '-m', String(body.content || 'ArenaCode')], root);
+      return { ok: commit.ok, output: commit.output };
+    }
+    case 'git_revert': {
+      const r = git(['revert', '--no-edit', String(body.ref)], root);
+      return { ok: r.ok, output: r.output };
+    }
+    case 'git_publish': {
+      if (!execFileSyncSafe('gh')) {
+        return { ok: false, error: 'GitHub CLI (gh) is not installed on this PC' };
+      }
+      const name = body.content || path.basename(root);
+      const create = git(['remote', 'get-url', 'origin'], root);
+      if (!create.ok) {
+        const args = ['repo', 'create', name, '--source', '.', '--push'];
+        if (String(body.ref || '') === 'public') args.push('--public');
+        else args.push('--private');
+        try {
+          const out = execFileSync('gh', args, { cwd: root, encoding: 'utf8', timeout: 120_000, windowsHide: true });
+          return { ok: true, output: out };
+        } catch (e) {
+          return { ok: false, error: `${(e.stdout || '') + (e.stderr || '') || e.message}`.trim() };
+        }
+      }
+      const push = git(['push', '-u', 'origin', 'HEAD'], root);
+      return { ok: push.ok, output: push.output };
+    }
+
+    default:
+      return { ok: false, error: `unsupported op: ${op}` };
+  }
+}
+
+function execFileSyncSafe(cmd) {
+  try {
+    execFileSync(process.platform === 'win32' ? 'where' : 'which', [cmd], { stdio: 'ignore', timeout: 3000, windowsHide: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function handleLocalFs(bridge, taskId, request, opts) {
+  const { rid, op } = request;
+  const lang = opts.lang;
+  write('');
+  write(`  ${c.bold(c.yellow('▤ files'))} ${c.dim('·')} ${c.cyan(op)} ${c.gray(request.path || '.')}${request.to ? c.gray(` → ${request.to}`) : ''}`);
+
+  const mutating = ['write', 'replace', 'rm', 'mv', 'mkdir'].includes(op);
+  if (mutating && opts.confirmWrites) {
+    const key = await askKey(`  ${t(lang, 'Applico? [s] sì  [n] no', 'Apply? [y] yes  [n] no', '¿Aplico? [s] sí  [n] no')} `, ['s', 'y', 'n']);
+    if (key === 'n') {
+      await bridge.localResult(taskId, { rid, output: JSON.stringify({ ok: false, error: 'rejected by the user' }), code: 1 });
+      return true;
+    }
+  }
+
+  let result;
+  try {
+    result = runFsOp(op, request, opts.folder);
+  } catch (e) {
+    result = { ok: false, error: e.message };
+  }
+
+  const payload = JSON.stringify(result);
+  const code = result.ok ? 0 : 1;
+  await bridge.localResult(taskId, { rid, output: payload, code });
+
+  if (result.ok) {
+    const extra = result.size ? c.gray(` ${result.size} B`) : '';
+    write(`  ${c.green('✓')} ${c.gray(op)}${extra}`);
+  } else {
+    write(`  ${c.red('✗')} ${c.gray(result.error || 'failed')}`);
+  }
+  return true;
+}
+
+// --------------------------------------------------------------------------- //
+// Local UI (local-ui) — the terminal cannot drive the mouse, but plan approval,
+// waits and system info work.
+// --------------------------------------------------------------------------- //
+
+async function handleLocalUi(bridge, taskId, request, opts) {
+  const { rid, op } = request;
+  const lang = opts.lang;
+
+  if (op === 'plan') {
+    write('');
+    write(`  ${c.bold(c.magenta('✦ plan'))} ${c.dim('·')} ${t(lang, 'da approvare', 'to approve', 'para aprobar')}`);
+    write(indentLines(request.text || '', '    '));
+    write('');
+    const key = await askKey(
+      `  ${t(lang, '[a] Approva  [r] Rifiuta  [f] Riformula', '[a] Approve  [r] Reject  [f] Revise', '[a] Aprobar  [r] Rechazar  [f] Reformular')} `,
+      ['a', 'r', 'f'],
+    );
+    if (key === 'a') {
+      await bridge.localResult(taskId, { rid, output: JSON.stringify({ ok: true, approved: true }), code: 0 });
+      write(`  ${c.green('✓')} ${t(lang, 'piano approvato', 'plan approved', 'plan aprobado')}`);
+    } else if (key === 'f') {
+      const feedback = await ask(`  ${t(lang, 'Come riformularlo? ', 'How should it be revised? ', '¿Cómo reformularlo? ')}`);
+      await bridge.localResult(taskId, {
+        rid,
+        output: JSON.stringify({ ok: false, approved: false, revise: true, feedback: feedback || '' }),
+        code: 1,
+      });
+      write(`  ${c.yellow('↻')} ${t(lang, 'riformulazione inviata', 'revision sent', 'reformulación enviada')}`);
+    } else {
+      await bridge.localResult(taskId, { rid, output: JSON.stringify({ ok: false, approved: false }), code: 1 });
+      write(`  ${c.red('✗')} ${t(lang, 'piano rifiutato', 'plan rejected', 'plan rechazado')}`);
+    }
+    return true;
+  }
+
+  if (op === 'wait') {
+    let duration = 1;
+    try {
+      duration = JSON.parse(request.args_json || '{}').duration ?? 1;
+    } catch {
+      duration = 1;
+    }
+    await new Promise((r) => setTimeout(r, Math.min(60, Math.max(0, duration)) * 1000));
+    await bridge.localResult(taskId, { rid, output: JSON.stringify({ ok: true }), code: 0 });
+    return true;
+  }
+
+  if (op === 'sysinfo') {
+    const info = {
+      ok: true,
+      os: `${process.platform} ${available()}`,
+      hostname: os.hostname(),
+      arch: os.arch(),
+      cpus: os.cpus().length,
+      memory_mb: Math.round(os.totalmem() / 1048576),
+      node: process.version,
+      shell: require('./meta').which('pwsh') ? 'pwsh' : process.platform === 'win32' ? 'powershell' : 'sh',
+    };
+    await bridge.localResult(taskId, { rid, output: JSON.stringify(info), code: 0 });
+    write(`  ${c.green('✓')} ${c.gray('sysinfo')}`);
+    return true;
+  }
+
+  // control / type / keystroke / screenshot / app / state / apps / multi_*
+  const error = t(
+    lang,
+    `operazione "${op}" non disponibile nel client da terminale: serve il client grafico ArenaCode`,
+    `operation "${op}" is not available in the terminal client: the ArenaCode desktop client is required`,
+    `la operación "${op}" no está disponible en el cliente de terminal: requiere el cliente gráfico ArenaCode`,
+  );
+  await bridge.localResult(taskId, { rid, output: JSON.stringify({ ok: false, error }), code: 1 });
+  write(`  ${c.red('✗')} ${c.gray(op)} ${c.gray('— ' + error)}`);
+  return true;
+}
+
+function available() {
+  return os.release();
+}
+
+// --------------------------------------------------------------------------- //
+// Files sent from the agent workspace to this PC (local_file)
+// --------------------------------------------------------------------------- //
+
+async function handleLocalFile(bridge, taskId, request, opts) {
+  const remote = String(request.remote || '');
+  const dest = String(request.dest || request.name || path.basename(remote));
+  const res = await bridge.fileRaw(remote);
+  if (res.status !== 200) {
+    write(`  ${c.red('✗')} ${c.gray(`download failed: ${remote}`)}`);
+    return true;
+  }
+  const target = resolveInRoot(opts.folder, dest);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, res.buffer);
+  write(`  ${c.green('✓')} ${c.gray(`${remote} → ${relativize(opts.folder, target)} (${res.buffer.length} B)`)}`);
+  return true;
+}
+
+module.exports = {
+  REFUSED,
+  resolveInRoot,
+  runShell,
+  runFsOp,
+  handleLocalExec,
+  handleLocalFs,
+  handleLocalUi,
+  handleLocalFile,
+};