@lardexx/arenacode 2.5.10 → 2.6.0

package/README.md

@@ -106,16 +106,34 @@ How the copy is built and tested: [`docs/TUI.md`](docs/TUI.md).
 |---|---|
 | `enter` | send · `shift+enter` newline |
 | `esc` | interrupt the turn · clear the input · quit |
-| `tab` | switch agent ↔ plan |
+| `tab` | switch mode: Build → Plan → Computer |
 | `ctrl+p` | command palette (`↑↓` select, `enter` run, `esc` close) |
 | `/` | slash commands with an inline list above the prompt |
-| `@file` | attach a file from the open folder |
+| `@file` | attach a file from the open folder (uploaded to `uploads/`) |
+| `@folder` | inline the folder listing in the task |
+| `ctrl+v` | paste: a clipboard image becomes `images/clipboard-*.png` and is attached |
 | `!command` | run a command locally |
 | `↑` / `↓` | prompt history (or move through the slash list) |
 | `pgup` / `pgdn` | scroll the transcript |
 | `ctrl+x` then | `q` quit · `n` new session · `l` task queue · `t` theme · `d` tool output · `b` sidebar · `s` stop |
 | `ctrl+c` | interrupt, then quit |
 
+**The same four flows as the desktop client.** The Windows app is the reference for how a task reaches the bridge,
+so the port reproduces it byte for byte:
+
+- **Paste an image.** `ctrl+v` reads the clipboard image, saves it as `<folder>/images/clipboard-YYYYMMDD-HHMMSS.png`
+  (the desktop's naming), uploads it and lists it in the task, so the agent can open it with `read`.
+- **Switch agent.** `tab` cycles the three modes of the desktop client — Build (`[ArenaCode mode: agent]`),
+  Plan (`[ArenaCode mode: plan]`) and Computer (`[ArenaCode mode: computer-agent]`) — and the first line of every
+  task is the desktop's own mode line, verbatim.
+- **Send a message.** `POST /task` carries `instruction`, `meta`, `agent_prompt` and `project_context`, the same
+  body the desktop client builds.
+- **Mention something.** `@file` is uploaded to `uploads/<timestamp>/` and named in `[attachments in the workspace: …]`;
+  `@folder` is inlined as `[folder contents … (n files, list only, not attached): …]`; missing paths outside the
+  folder are reported under `[paths on the PC: …]`. Messages follow the interface language (`it`, `en`, `es`).
+
+The exact strings are checked by `test/parity.js` against the ones extracted from `ArenaCode-x64.exe`.
+
 **Dialogs.** Local actions open opencode-shaped dialogs — panel background, title on the left, `esc` on the right,
 the selected row painted in the primary colour, hints underneath: `Run once / Don't run` for terminal commands,
 `Approve / Reject / Revise` for the agent's plan, and file operations reported back to the bridge. `--yes` skips the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lardexx/arenacode",
-  "version": "2.5.10",
+  "version": "2.6.0",
   "description": "Terminal client for ArenaCode: talks to an arena-bridge, streams the Agent Mode timeline, and runs local commands and file operations on your PC. Node port of the ArenaCode desktop client.",
   "license": "MIT",
   "type": "commonjs",
@@ -19,7 +19,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node test/integration.js"
+    "test": "node test/integration.js && node test/parity.js"
   },
   "keywords": [
     "arenacode",

package/src/attach.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { stamp } = require('./clipboard');
+
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '__pycache__',
+  '.git',
+  '.venv',
+  '.next',
+  '.cache',
+  '.idea',
+  '.vscode',
+  'dist',
+  'build',
+]);
+
+const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.bmp', '.webp']);
+const MAX_FILES = 300;
+const MAX_BYTES = 64 * 1024 * 1024;
+
+const TEXT = {
+  it: {
+    attachments: '[allegati nel workspace: ',
+    folder: '[contenuto della cartella ',
+    empty: '[cartella vuota: ',
+    other: ' (altri %d file, solo elenco, non allegati): ',
+    paths: '[percorsi sul PC: ',
+    tooMany: 'troppi file (max %d) o file oltre %d MB',
+    noImage: 'Immagine negli appunti non leggibile.',
+    pasted: 'immagine allegata',
+  },
+  en: {
+    attachments: '[attachments in the workspace: ',
+    folder: '[folder contents ',
+    empty: '[empty folder: ',
+    other: ' (%d files, list only, not attached): ',
+    paths: '[paths on the PC: ',
+    tooMany: 'too many files (max %d) or files over %d MB',
+    noImage: 'Clipboard image could not be read.',
+    pasted: 'image attached',
+  },
+  es: {
+    attachments: '[adjuntos en el espacio de trabajo: ',
+    folder: '[contenido de la carpeta ',
+    empty: '[carpeta vacía: ',
+    other: ' (%d archivos, solo lista, no adjuntos): ',
+    paths: '[rutas en el PC: ',
+    tooMany: 'demasiados archivos (máx %d) o archivos de más de %d MB',
+    noImage: 'La imagen del portapapeles no se pudo leer.',
+    pasted: 'imagen adjunta',
+  },
+};
+
+function strings(lang) {
+  return TEXT[lang] || TEXT.en;
+}
+
+/** Lists the files of a folder the way the desktop client inlines them. */
+function folderListing(folder, rel, lang) {
+  const s = strings(lang);
+  const root = path.resolve(folder, rel);
+  const names = [];
+  let truncated = false;
+
+  const walk = (dir, prefix, depth) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+      if (names.length >= MAX_FILES) {
+        truncated = true;
+        return;
+      }
+      if (e.name.startsWith('.') && depth === 0 && SKIP_DIRS.has(e.name)) continue;
+      if (SKIP_DIRS.has(e.name)) continue;
+      const childRel = prefix ? `${prefix}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        walk(path.join(dir, e.name), childRel, depth + 1);
+      } else {
+        names.push(childRel);
+      }
+    }
+  };
+  walk(root, '', 0);
+
+  if (!names.length) return `${s.empty}${rel || '.'}]`;
+  const total = names.length + (truncated ? 1 : 0);
+  return `${s.folder}${rel || '.'}${s.other.replace('%d', total)}${names.join(', ')}${truncated ? ', …' : ''}]`;
+}
+
+function isInside(folder, abs) {
+  const rel = path.relative(folder, abs);
+  return rel && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+async function upload(bridge, folder, abs, name) {
+  const stat = fs.statSync(abs);
+  if (stat.size > MAX_BYTES) return { error: 'size' };
+  const dir = `uploads/${stamp()}`;
+  const remote = `${dir}/${name}`;
+  const res = await bridge.upload(remote, fs.readFileSync(abs));
+  if (res.status !== 200) return { error: `HTTP ${res.status}` };
+  return { remote: (res.json && res.json.path) || remote, size: stat.size };
+}
+
+/**
+ * Turns `@refs` into the same instruction blocks the desktop client produces:
+ * files land in the bridge workspace, folders are inlined as a listing.
+ */
+async function attachRefs(bridge, folder, refs, { lang = 'en' } = {}) {
+  const s = strings(lang);
+  const uploaded = [];
+  const blocks = [];
+  const paths = [];
+  const warnings = [];
+
+  for (const ref of refs) {
+    const abs = path.resolve(folder, ref);
+    let exists = true;
+    let stat = null;
+    try {
+      stat = fs.statSync(abs);
+    } catch {
+      exists = false;
+    }
+    if (!exists) {
+      if (/^[a-zA-Z]:[\\/]/.test(ref) || ref.startsWith('/')) paths.push(ref);
+      else warnings.push(`not found: ${ref}`);
+      continue;
+    }
+    if (stat.isDirectory()) {
+      blocks.push(folderListing(folder, ref, lang));
+      continue;
+    }
+    const up = await upload(bridge, folder, abs, path.basename(abs));
+    if (up.error === 'size') {
+      warnings.push(s.tooMany.replace('%d', MAX_FILES).replace('%d', MAX_BYTES / (1024 * 1024)));
+      continue;
+    }
+    if (up.error) {
+      warnings.push(`upload failed: ${ref} (${up.error})`);
+      continue;
+    }
+    uploaded.push(up.remote);
+  }
+
+  return { uploaded, blocks, paths, warnings, s };
+}
+
+/** Moves a clipboard PNG into <folder>/images and uploads it, like the desktop. */
+async function attachImage(bridge, folder, tmpPng, { lang = 'en', name } = {}) {
+  const id = name || `clipboard-${stamp()}.png`;
+  const localDir = path.join(folder, 'images');
+  fs.mkdirSync(localDir, { recursive: true });
+  const local = path.join(localDir, id);
+  try {
+    fs.renameSync(tmpPng, local);
+  } catch {
+    fs.copyFileSync(tmpPng, local);
+    try {
+      fs.unlinkSync(tmpPng);
+    } catch {
+      /* ignore */
+    }
+  }
+  const up = await upload(bridge, folder, local, id);
+  if (up.error) return { error: up.error, local };
+  return { local, rel: path.relative(folder, local), remote: up.remote };
+}
+
+/** Appends the blocks the desktop appends to the instruction text. */
+function decorate(text, { uploaded = [], blocks = [], paths = [], lang = 'en' } = {}) {
+  const s = strings(lang);
+  const extra = [...blocks];
+  if (uploaded.length) extra.push(`${s.attachments}${uploaded.join(', ')}]`);
+  if (paths.length) extra.push(`${s.paths}${paths.join(', ')}]`);
+  if (!extra.length) return text;
+  return `${text}\n\n${extra.join('\n\n')}`;
+}
+
+module.exports = { attachRefs, attachImage, decorate, folderListing, strings, IMAGE_EXT, MAX_FILES, MAX_BYTES };

package/src/cli.js

@@ -9,6 +9,8 @@ const {
   resolveUrl, resolveKey, openFolder,
 } = require('./config');
 const { Bridge } = require('./bridge');
+const { MODE_LINES, MODES, normaliseMode } = require('./modes');
+const { attachRefs, decorate } = require('./attach');
 const { buildMeta, readProjectContext } = require('./meta');
 const { followTask } = require('./turn');
 const { c, write, ask, banner, truncate, indentLines } = require('./ui');
@@ -30,17 +32,6 @@ const INSTALL_HINT = process.platform === 'win32'
   ? 'npm install -g @lardexx/arenacode   (then reopen the terminal)'
   : 'npm install -g @lardexx/arenacode';
 
-const MODE_LINES = {
-  agent:
-    '[ArenaCode mode: agent]\n' +
-    'AGENT MODE (not plan mode). Carry the task out directly: do not make a plan, do not send ui plan, ' +
-    'do not write a plan. This line overrides any plan instruction from earlier tasks or from the chat, ' +
-    'even if you remember one. Work, verify each change, and reply.',
-  plan:
-    '[ArenaCode mode: plan]\n' +
-    'PLAN MODE. Send the plan first with `ui plan`: the steps, the files involved, the risks and what you ' +
-    'will not do. Then stop and wait for the user to approve it before acting.',
-};
 
 // --------------------------------------------------------------------------- //
 // argument parsing
@@ -104,7 +95,7 @@ function context(flags) {
     folder,
     device,
     lang: flags.lang || cfg.lang || 'it',
-    mode: flags.mode === 'plan' ? 'plan' : flags.mode === 'agent' ? 'agent' : cfg.mode || 'agent',
+    mode: normaliseMode(flags.mode || cfg.mode || 'agent'),
     pcAccess: flags['no-pc'] ? false : cfg.pc_access !== false,
     yes: Boolean(flags.yes),
     json: Boolean(flags.json),
@@ -303,23 +294,15 @@ async function runInstruction(ctx, text, { attachments = [] } = {}) {
   let instruction = `${MODE_LINES[ctx.mode] || MODE_LINES.agent}\n${text}`;
 
   if (attachments.length) {
-    const uploaded = [];
-    for (const file of attachments) {
-      const abs = path.resolve(file);
-      if (!fs.existsSync(abs)) {
-        write(c.yellow(`  ! missing attachment: ${file}`));
-        continue;
-      }
-      const name = `attachments/${Date.now()}-${path.basename(abs)}`;
-      const res = await ctx.bridge.upload(name, fs.readFileSync(abs));
-      if (res.status !== 200) {
-        write(c.yellow(`  ! upload failed: ${file}`));
-        continue;
-      }
-      uploaded.push(res.json.path);
-      write(`  ${c.green('↑')} ${c.gray(`${path.basename(abs)} → ${res.json.path} (${res.json.size} B)`)}`);
-    }
-    if (uploaded.length) instruction += `\n\n[attachments in the workspace: ${uploaded.join(', ')}]`;
+    const att = await attachRefs(ctx.bridge, ctx.folder, attachments, { lang: ctx.lang });
+    for (const w of att.warnings) write(c.yellow(`  ! ${w}`));
+    for (const remote of att.uploaded) write(`  ${c.green('↑')} ${c.gray(remote)}`);
+    instruction = decorate(instruction, {
+      uploaded: att.uploaded,
+      blocks: att.blocks,
+      paths: att.paths,
+      lang: ctx.lang,
+    });
   }
 
   let taskId = null;
@@ -756,7 +739,7 @@ function help() {
   write(`  ${c.cyan('options')}`);
   write(`    --folder <dir>             open folder (the project the agent works on)`);
   write(`    --url <url> --key <key>    override the saved bridge settings`);
-  write(`    --mode agent|plan          task mode (default: ${c.gray('agent')})`);
+  write(`    --mode agent|plan|computer-agent   task mode (default: ${c.gray('agent')})`);
   write(`    --lang it|en|es            language for instructions and cards`);
   write(`    --no-pc                    tell the agent the PC terminal is off`);
   write(`    --yes                      run local commands without asking`);

package/src/clipboard.js

@@ -0,0 +1,133 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+// The desktop client stores a pasted screenshot as <folder>\images\clipboard-YYYYMMDD-HHMMSS.png
+function stamp(d = new Date()) {
+  const p = (n) => String(n).padStart(2, '0');
+  return (
+    `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-` +
+    `${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`
+  );
+}
+
+function isPng(buf) {
+  return Buffer.isBuffer(buf) && buf.length > 8 && buf.subarray(0, 8).equals(PNG_MAGIC);
+}
+
+// Windows: System.Windows.Forms.Clipboard needs an STA thread, so run
+// PowerShell with -STA. The image is written straight to `dest`.
+function grabWindows(dest) {
+  const script = [
+    'Add-Type -AssemblyName System.Windows.Forms',
+    'Add-Type -AssemblyName System.Drawing',
+    '$img = [System.Windows.Forms.Clipboard]::GetImage()',
+    'if ($null -eq $img) { Write-Output "none"; exit 2 }',
+    `$img.Save('${dest.replace(/'/g, "''")}', [System.Drawing.Imaging.ImageFormat]::Png)`,
+    '$img.Dispose()',
+    'Write-Output "ok"',
+  ].join('; ');
+  for (const exe of ['powershell', 'pwsh']) {
+    const r = spawnSync(exe, ['-NoProfile', '-NonInteractive', '-STA', '-Command', script], {
+      timeout: 20_000,
+      windowsHide: true,
+    });
+    if (r.error && r.error.code === 'ENOENT') continue;
+    if (r.status === 0 && fs.existsSync(dest) && fs.statSync(dest).size > 0) return true;
+    // No image on the clipboard, or no PowerShell: nothing to paste.
+    if (r.status === 2) return false;
+    return false;
+  }
+  return false;
+}
+
+function grabUnix(dest) {
+  const attempts = [
+    ['wl-paste', ['--no-newline', '--type', 'image/png']],
+    ['xclip', ['-selection', 'clipboard', '-t', 'image/png', '-o']],
+  ];
+  for (const [cmd, args] of attempts) {
+    const r = spawnSync(cmd, args, { timeout: 10_000, maxBuffer: 64 * 1024 * 1024 });
+    if (r.error) continue;
+    if (r.status === 0 && isPng(r.stdout)) {
+      fs.writeFileSync(dest, r.stdout);
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Saves the image currently on the clipboard as a PNG in `dest`.
+ * Returns true when an image was written, false when the clipboard holds
+ * no image (or the platform has no clipboard access).
+ */
+function grabImage(dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  // test/automation hook: treat this file as the clipboard image
+  const hook = process.env.ARENACODE_CLIPBOARD_IMAGE;
+  if (hook) {
+    try {
+      if (fs.existsSync(hook)) {
+        fs.copyFileSync(hook, dest);
+        return true;
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+  try {
+    if (process.platform === 'win32') return grabWindows(dest);
+    return grabUnix(dest);
+  } catch {
+    return false;
+  }
+}
+
+/** Text on the clipboard, or '' when there is none. */
+function readClipboardText() {
+  try {
+    if (process.platform === 'win32') {
+      for (const exe of ['powershell', 'pwsh']) {
+        const r = spawnSync(exe, ['-NoProfile', '-NonInteractive', '-Command', 'Get-Clipboard -Raw'], {
+          timeout: 10_000,
+          encoding: 'utf8',
+          windowsHide: true,
+        });
+        if (r.error && r.error.code === 'ENOENT') continue;
+        return r.status === 0 && r.stdout ? r.stdout.replace(/\r\n/g, '\n').replace(/\n$/, '') : '';
+      }
+      return '';
+    }
+    for (const [cmd, args] of [
+      ['wl-paste', ['--no-newline']],
+      ['xclip', ['-selection', 'clipboard', '-o']],
+    ]) {
+      const r = spawnSync(cmd, args, { timeout: 10_000, encoding: 'utf8' });
+      if (!r.error && r.status === 0) return r.stdout || '';
+    }
+  } catch {
+    /* ignore */
+  }
+  return '';
+}
+
+/** True when the clipboard looks like it holds an image (cheap check, no write). */
+function hasImage() {
+  const tmp = path.join(require('os').tmpdir(), `arenacode-probe-${process.pid}-${Date.now()}.png`);
+  const ok = grabImage(tmp);
+  if (ok) {
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+      /* ignore */
+    }
+  }
+  return ok;
+}
+
+module.exports = { grabImage, readClipboardText, hasImage, stamp, isPng };

package/src/modes.js

@@ -0,0 +1,55 @@
+'use strict';
+
+// Mode lines copied verbatim from the Windows client (ArenaCode-x64.exe, UTF-16
+// string table). The first line of every task must be one of these: the agent
+// treats it as the only valid mode for that task.
+const MODE_LINES = {
+  agent:
+    '[ArenaCode mode: agent]\n' +
+    'AGENT MODE (not plan mode). Carry the task out directly: do not make a plan, do not send ui plan, ' +
+    'do not write a plan. This line overrides any plan instruction from earlier tasks or from the chat, ' +
+    'even if you remember one. Work, verify each change, and reply.',
+  plan:
+    '[ArenaCode mode: plan]\n' +
+    'PLAN ONLY until the plan is approved. Do not edit files, do not run commands and do not change ' +
+    'anything on the PC. Study the request and the project (read-only), then send a short numbered plan ' +
+    'with the command python3 bridge/agentctl.py ui plan <task id> --text "..." (steps, files involved, ' +
+    'risks, what you will not do). Wait for its result. If it says ok:true, the user approved: carry the ' +
+    'plan out now, in this same turn, step by step, and report what you changed. If it says revise:true ' +
+    'with feedback, the user wants a different plan: reword the plan taking the feedback into account and ' +
+    'send it again with ui plan, in this same turn. If it is refused or returns an error, do not change ' +
+    'anything and reply.',
+  'computer-agent': '[ArenaCode mode: computer-agent]',
+  'plan-approved':
+    '[ArenaCode mode: plan approved]\n' +
+    'The user approved the plan in your previous message. Carry it out now, step by step, following that ' +
+    'plan. At the end, report what you changed.',
+};
+
+// The three modes the desktop client can start a task in, in the order tab
+// cycles through them.
+const MODES = ['agent', 'plan', 'computer-agent'];
+
+const MODE_LABELS = {
+  agent: 'Build',
+  plan: 'Plan',
+  'computer-agent': 'Computer',
+};
+
+function modeLabel(mode) {
+  return MODE_LABELS[mode] || MODE_LABELS.agent;
+}
+
+function nextMode(mode) {
+  const i = MODES.indexOf(mode);
+  return MODES[(i < 0 ? 0 : i + 1) % MODES.length];
+}
+
+function normaliseMode(mode) {
+  const m = String(mode || '').toLowerCase();
+  if (m === 'computer' || m === 'computer-agent' || m === 'computer_agent') return 'computer-agent';
+  if (m === 'plan') return 'plan';
+  return 'agent';
+}
+
+module.exports = { MODE_LINES, MODES, MODE_LABELS, modeLabel, nextMode, normaliseMode };

package/src/tui/app.js

@@ -17,6 +17,10 @@ const { buildMeta, readProjectContext } = require('../meta');
 const { runShell, runFsOp, resolveInRoot } = require('../local');
 const { readConfig, patchConfig, deviceId, resolveUrl, resolveKey, openFolder, VERSION } = require('../config');
 
+const { MODE_LINES, modeLabel, nextMode, normaliseMode } = require('../modes');
+const { attachRefs, attachImage, decorate, strings } = require('../attach');
+const { grabImage, readClipboardText, stamp } = require('../clipboard');
+
 const AGENT_PROMPT = (() => {
   try {
     return fs.readFileSync(path.join(__dirname, '..', 'prompts', 'agent-prompt.md'), 'utf8');
@@ -25,18 +29,6 @@ const AGENT_PROMPT = (() => {
   }
 })();
 
-const MODE_LINES = {
-  agent:
-    '[ArenaCode mode: agent]\n' +
-    'AGENT MODE (not plan mode). Carry the task out directly: do not make a plan, do not send ui plan, ' +
-    'do not write a plan. This line overrides any plan instruction from earlier tasks or from the chat, ' +
-    'even if you remember one. Work, verify each change, and reply.',
-  plan:
-    '[ArenaCode mode: plan]\n' +
-    'PLAN MODE. Send the plan first with `ui plan`: the steps, the files involved, the risks and what you ' +
-    'will not do. Then stop and wait for the user to approve it before acting.',
-};
-
 const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -56,11 +48,12 @@ class App {
     this.confirmWrites = Boolean(opts.confirmWrites);
 
     this.state = {
-      mode: opts.mode === 'plan' ? 'plan' : cfg.mode || 'agent',
+      mode: normaliseMode(opts.mode || cfg.mode || 'agent'),
       status: 'idle',
       details: true,
       items: [],
       seqItems: new Map(),
+      pendingImages: [],
       input: '',
       cursor: 0,
       history: [],
@@ -224,9 +217,13 @@ class App {
       this.invalidate();
       return undefined;
     }
+    if (key.ctrl && key.name === 'v') {
+      this.pasteClipboard();
+      return undefined;
+    }
     if (key.name === 'tab') {
-      st.mode = st.mode === 'agent' ? 'plan' : 'agent';
-      this.toast(`mode: ${st.mode}`);
+      st.mode = nextMode(st.mode);
+      this.toast(`mode: ${modeLabel(st.mode)}`);
       return undefined;
     }
     if (key.name === 'f1') return this.openHelp();
@@ -449,9 +446,9 @@ class App {
         this.state.details = !this.state.details;
         this.toast(`details ${this.state.details ? 'on' : 'off'}`);
       } },
-      { title: 'Switch mode (agent / plan)', hint: 'tab', run: () => {
-        this.state.mode = this.state.mode === 'agent' ? 'plan' : 'agent';
-        this.toast(`mode: ${this.state.mode}`);
+      { title: 'Switch mode (Build / Plan / Computer)', hint: 'tab', run: () => {
+        this.state.mode = nextMode(this.state.mode);
+        this.toast(`mode: ${modeLabel(this.state.mode)}`);
       } },
       { title: 'Theme', hint: 'ctrl+x t', run: () => {
         const names = themeNames();
@@ -565,6 +562,42 @@ class App {
     }
   }
 
+  /** ctrl+v: a clipboard image becomes an attachment, otherwise text is pasted. */
+  async pasteClipboard() {
+    const st = this.state;
+    if (st.status === 'running') {
+      this.toast('a turn is running: press esc to stop', 'warn');
+      return;
+    }
+    if (!this.url) {
+      this.toast('no bridge URL: run arenacode init', 'error');
+      return;
+    }
+    const tmp = path.join(require('os').tmpdir(), `arenacode-clip-${stamp()}-${process.pid}.png`);
+    if (grabImage(tmp)) {
+      const res = await attachImage(this.bridge, this.folder, tmp, { lang: this.lang });
+      if (res.error) {
+        this.toast(strings(this.lang).noImage, 'error');
+        return;
+      }
+      st.pendingImages.push(res.remote);
+      this.push({ kind: 'system', text: `${strings(this.lang).pasted}: ${res.rel}` });
+      this.toast(`${strings(this.lang).pasted}: ${res.rel}`);
+      this.invalidate();
+      return;
+    }
+    const text = readClipboardText();
+    if (text) {
+      const before = st.input.slice(0, st.cursor);
+      const after = st.input.slice(st.cursor);
+      st.input = before + text + after;
+      st.cursor += text.length;
+      this.invalidate();
+    } else {
+      this.toast(strings(this.lang).noImage, 'warn');
+    }
+  }
+
   // ---------------------------------------------------------------- turn
   async submit(text) {
     const st = this.state;
@@ -590,18 +623,19 @@ class App {
       return;
     }
 
-    let instruction = text;
-    const attachments = [];
+    // @file uploads the file, @folder inlines its listing, exactly like the desktop client
     const refs = [...text.matchAll(/@([^\s]+)/g)].map((m) => m[1]);
-    for (const ref of refs) {
-      const abs = path.resolve(this.folder, ref);
-      if (!fs.existsSync(abs)) continue;
-      const name = `attachments/${Date.now()}-${path.basename(abs)}`;
-      const up = await this.bridge.upload(name, fs.readFileSync(abs));
-      if (up.status === 200) attachments.push(up.json.path);
-    }
-    if (attachments.length) {
-      instruction += `\n\n[attachments in the workspace: ${attachments.join(', ')}]`;
+    let instruction = text;
+    if (refs.length || st.pendingImages.length) {
+      const att = await attachRefs(this.bridge, this.folder, refs, { lang: this.lang });
+      for (const w of att.warnings) this.toast(w, 'warn');
+      const images = st.pendingImages.splice(0, st.pendingImages.length);
+      instruction = decorate(text, {
+        uploaded: [...att.uploaded, ...images],
+        blocks: att.blocks,
+        paths: att.paths,
+        lang: this.lang,
+      });
     }
 
     this.push({ kind: 'user', text: text.replace(/@([^\s]+)/g, '$1') });
@@ -1032,12 +1066,14 @@ class App {
   }
 
   agentName() {
-    return this.state.mode === 'plan' ? 'Plan' : 'Build';
+    return modeLabel(this.state.mode);
   }
 
   agentColor() {
     // opencode gives each agent its own colour; Build is the secondary blue, Plan the accent violet
-    return this.state.mode === 'plan' ? this.theme.c.accent : this.theme.c.secondary;
+    if (this.state.mode === 'plan') return this.theme.c.accent;
+    if (this.state.mode === 'computer-agent') return this.theme.c.success;
+    return this.theme.c.secondary;
   }
 
   promptWidth(W) {
@@ -1054,7 +1090,7 @@ class App {
     const hints = busy
       ? []
       : [
-          ['tab', st.mode === 'plan' ? 'plan' : 'agents'],
+          ['tab', modeLabel(st.mode).toLowerCase()],
           ['ctrl+p', 'commands'],
         ];
     const block = W2.promptBlock(t, {