@milpa/comal 0.0.0-stage → 0.1.1

package/src/tui/brand.mjs

@@ -0,0 +1,51 @@
+import { t } from '../i18n/index.mjs';
+import { clip, createTones, width } from './text.mjs';
+
+export const BRAND_FRAME_INTERVAL_MS = 240;
+export const BRAND_WELCOME_FRAMES = 12;
+
+// The 13 grains and positions follow the original 5×5 Milpa symbol, not a generic M.
+export const MILPA_GRAIN_GRID = Object.freeze(['10001', '11011', '10101', '10001', '10001']);
+
+export function brandMotionEnabled({ motion, env = process.env, stream = process.stdout } = {}) {
+  if (Object.hasOwn(env, 'NO_COLOR') || env.TERM === 'dumb' || /^(1|true|yes|on|reduce)$/i.test(env.COMAL_REDUCED_MOTION || '')) return false;
+  if (motion === false || !stream?.isTTY) return false;
+  return true;
+}
+
+const safeFrame = frame => Number.isFinite(frame) ? Math.max(0, Math.floor(frame)) : 0;
+function animationPhase({ frame = 0, active = false, ...options }) {
+  if (!brandMotionEnabled(options)) return 0;
+  const tick = safeFrame(frame);
+  return !active && tick >= BRAND_WELCOME_FRAMES ? 0 : tick % 4;
+}
+
+/** Pure, bounded presentation: callers own timing and stop welcome timers after 12 frames.
+ * active=true permits the small heat loop only while actual work is running.
+ * No counters, progress percentages, tool calls or terminal image protocols are emitted.
+ */
+export function brandingWelcome({ columns = 80, frame = 0, active = false, motion, env = process.env, stream = process.stdout } = {}) {
+  const room = Number.isFinite(columns) ? Math.max(0, Math.floor(columns)) : 80;
+  if (!room) return [];
+  const tones = createTones({ env, stream });
+  const ascii = env.TERM === 'dumb';
+  const phase = animationPhase({ frame, active, motion, env, stream });
+  if (room < 24) return [clip(tones.accent('COMAL') + tones.muted(' · Milpa'), room)];
+  const steam = ascii ? ['   .   .   .', '    . . .', '   .  .  .', '    .   .'] : ['   ˙   ·   ˙', '    · ˙ ·', '   ·  ˙  ·', '    ˙   ·'];
+  const mark = MILPA_GRAIN_GRID.map(row => row.split('').map(cell => cell === '1' ? (ascii ? '[]' : '██') : '  ').join(' '));
+  const plate = ascii ? ['.----------------.', " '--------------'"] : ['╭────────────────╮', ' ╰──────────────╯'];
+  const heat = ascii ? ['     . . .', '      . .', '     . . .', '    . . .'] : ['     · · ·', '      ˙ ·', '     · ˙ ·', '    ˙ · ˙'];
+  const icon = [tones.muted(steam[phase]), ...mark.map(line => '  ' + tones.accent(line)), tones.tierra(plate[0]), tones.tierra(plate[1]), tones.secondary(heat[phase])];
+  const label = tones.bold(tones.accent('COMAL'));
+  const caption = [t("Operations with intent."), t("Every turn leaves a receipt.")];
+  const rows = room >= 61 ? icon.map((line, index) => line + ' '.repeat(Math.max(1, 24 - width(line))) + (index === 2 ? label : index === 4 ? tones.muted(caption[0]) : index === 5 ? tones.muted(caption[1]) : '')) : [...icon, '', label, ...caption.map(line => tones.muted(line))];
+  return rows.map(line => clip(line, room));
+}
+
+/** Tiny activity accent; the caller supplies the real state label separately. */
+export function brandingStatus({ frame = 0, active = false, motion, env = process.env, stream = process.stdout } = {}) {
+  const tones = createTones({ env, stream });
+  if (!active) return tones.accent(env.TERM === 'dumb' ? 'M' : '▪');
+  const phase = animationPhase({ frame, active, motion, env, stream });
+  return tones.accent(env.TERM === 'dumb' ? 'M' : ['▪', '▴', '▪', '▾'][phase]);
+}

package/src/tui/clipboard.mjs

@@ -0,0 +1,29 @@
+import { t } from '../i18n/index.mjs';
+import { spawn } from 'node:child_process';
+import { safeText } from './text.mjs';
+
+// Write only. Text travels over stdin, never through shell arguments.
+export async function copyText(text, { env = process.env, platform = process.platform, spawnProcess = spawn, timeoutMs = 3000 } = {}) {
+  const value = safeText(text, { preserveTabs: true });
+  if (!value.trim()) throw new Error(t("No response text to copy."));
+  const candidates = platform === 'darwin' ? [['pbcopy', []]] : [
+    ...(env.WAYLAND_DISPLAY ? [['wl-copy', []]] : []),
+    ...(env.DISPLAY ? [['xclip', ['-selection', 'clipboard']], ['xsel', ['--clipboard', '--input']]] : []),
+  ];
+  for (const [command, args] of candidates) {
+    try {
+      await new Promise((resolve, reject) => {
+        const child = spawnProcess(command, args, { env, stdio: ['pipe', 'ignore', 'ignore'], shell: false });
+        let settled = false;
+        const finish = error => { if (settled) return; settled = true; clearTimeout(timer); error ? reject(error) : resolve(); };
+        const timer = setTimeout(() => { child.kill(); finish(new Error(t("Timed out."))); }, timeoutMs);
+        child.once('error', finish);
+        child.once('close', code => finish(code === 0 ? null : new Error(t("Code {v0}", {v0: code}))));
+        child.stdin.on('error', error => { child.kill(); finish(error); });
+        child.stdin.end(value);
+      });
+      return command;
+    } catch { /* Try the next installed desktop clipboard provider. */ }
+  }
+  throw new Error(t("Could not write to the clipboard. Use F5, select with the mouse and copy from your terminal. On Linux you can install wl-clipboard (Wayland) or xclip (X11)."));
+}

package/src/tui/composer.mjs

@@ -0,0 +1,143 @@
+import { t } from '../i18n/index.mjs';
+import { clip, graphemes, safeText, width } from './text.mjs';
+
+const normalize = text => safeText(String(text).replace(/\r\n?/g, '\n'), { preserveTabs: true });
+const IMAGE_COUNT = 2;
+const imageLabel = /^\[Image ([1-9]\d*)\]$/;
+
+export class Composer {
+  constructor(text = '') { this.history = []; this.historyAttachments = []; this.historyIndex = -1; this.scratch = ''; this.nextImage = 1; this.setText(text); }
+  get text() { return this.buffer.join(''); }
+  // Positions are UTF-16 offsets in display text, not filesystem paths. Only
+  // explicit host metadata may restore an attachment; a typed label is text.
+  get attachments() {
+    const result = []; let start = 0;
+    for (const atom of this.buffer) {
+      const descriptor = this.attachmentMap.get(atom);
+      if (descriptor) result.push({ ...structuredClone(descriptor), start, end: start + atom.length });
+      start += atom.length;
+    }
+    return result;
+  }
+  get attachmentDescriptors() { return this.attachments; }
+  snapshot() { return { text: this.text, cursor: this.cursor, attachments: this.attachments }; }
+  setText(text, cursor, attachments = []) {
+    const clean = normalize(text); this.attachmentMap = new Map();
+    const spans = [];
+    for (const candidate of attachments || []) {
+      if (!candidate || typeof candidate !== 'object' || !imageLabel.test(candidate.label || '') || spans.length >= IMAGE_COUNT || this.attachmentMap.has(candidate.label)) continue;
+      const start = Number.isInteger(candidate.start) ? candidate.start : clean.indexOf(candidate.label);
+      const end = start + candidate.label.length;
+      if (start < 0 || clean.slice(start, end) !== candidate.label || spans.some(span => start < span.end && end > span.start)) continue;
+      // Refuse offsets inside another grapheme, including joined emoji.
+      const boundaries = new Set([0]); let offset = 0;
+      for (const atom of graphemes(clean)) { offset += atom.length; boundaries.add(offset); }
+      if (!boundaries.has(start) || !boundaries.has(end)) continue;
+      const { start: _start, end: _end, ...descriptor } = structuredClone(candidate);
+      this.attachmentMap.set(candidate.label, descriptor); spans.push({ start, end, label: candidate.label });
+      this.nextImage = Math.max(this.nextImage, Number(imageLabel.exec(candidate.label)[1]) + 1);
+    }
+    spans.sort((a, b) => a.start - b.start); this.buffer = []; let offset = 0;
+    for (const span of spans) { this.buffer.push(...graphemes(clean.slice(offset, span.start)), span.label); offset = span.end; }
+    this.buffer.push(...graphemes(clean.slice(offset)));
+    this.cursor = Math.max(0, Math.min(cursor ?? this.buffer.length, this.buffer.length));
+  }
+  addAttachment(descriptor, range) {
+    if (!descriptor || typeof descriptor !== 'object') throw new Error(t("Invalid image attachment."));
+    if (this.attachments.length >= IMAGE_COUNT) throw new Error(t("Attach up to two images per message."));
+    const source = this.text;
+    const start = range?.start ?? this.buffer.slice(0, this.cursor).join('').length;
+    const end = range?.end ?? start;
+    let offset = 0; const boundaries = new Map([[0, 0]]);
+    for (let i = 0; i < this.buffer.length; i++) { offset += this.buffer[i].length; boundaries.set(offset, i + 1); }
+    if (!Number.isInteger(start) || !Number.isInteger(end) || start > end || !boundaries.has(start) || !boundaries.has(end)) throw new Error(t("Invalid image attachment position."));
+    let label = descriptor.label;
+    if (!imageLabel.test(label || '') || source.includes(label)) {
+      do { label = `[Image ${this.nextImage++}]`; } while (source.includes(label));
+    } else this.nextImage = Math.max(this.nextImage, Number(imageLabel.exec(label)[1]) + 1);
+    const next = source.slice(0, start) + label + source.slice(end);
+    if (Buffer.byteLength(next) > 1024 * 1024) throw new Error(t("The composer supports up to 1 MiB."));
+    const first = boundaries.get(start), last = boundaries.get(end);
+    this.buffer.splice(first, last - first, label);
+    if (this.cursor >= last) this.cursor += 1 - (last - first);
+    else if (this.cursor > first) this.cursor = first + 1;
+    const { start: _start, end: _end, ...value } = structuredClone(descriptor);
+    this.attachmentMap.set(label, { ...value, label }); this.historyIndex = -1; this.pruneAttachments();
+    return this.attachments.find(attachment => attachment.label === label);
+  }
+  pruneAttachments() { for (const label of this.attachmentMap.keys()) if (!this.buffer.includes(label)) this.attachmentMap.delete(label); }
+  insert(text) {
+    const inserted = graphemes(safeText(String(text).replace(/\r\n?/g, '\n'), { preserveTabs: true }));
+    if (Buffer.byteLength(this.text + inserted.join('')) > 1024 * 1024) throw new Error(t("The composer supports up to 1 MiB."));
+    this.buffer = this.buffer.slice(0, this.cursor).concat(inserted, this.buffer.slice(this.cursor)); this.cursor += inserted.length; this.historyIndex = -1;
+  }
+  clear() { this.setText(''); this.historyIndex = -1; }
+  remember(text, attachments = text === this.text ? this.attachments : []) {
+    if (text.trim()) {
+      if (this.history.at(-1) !== text) { this.history.push(text); this.historyAttachments.push(structuredClone(attachments)); }
+      else this.historyAttachments[this.history.length - 1] = structuredClone(attachments);
+    }
+    this.history = this.history.slice(-100); this.historyAttachments = this.historyAttachments.slice(-100); this.historyIndex = -1;
+  }
+  boundary(direction) {
+    let cursor = this.cursor;
+    if (direction < 0) { while (cursor > 0 && /^\s+$/.test(this.buffer[cursor - 1])) cursor--; while (cursor > 0 && !/^\s+$/.test(this.buffer[cursor - 1])) cursor--; }
+    else { while (cursor < this.buffer.length && !/^\s+$/.test(this.buffer[cursor])) cursor++; while (cursor < this.buffer.length && /^\s+$/.test(this.buffer[cursor])) cursor++; }
+    return cursor;
+  }
+  lineStart() { let c = this.cursor; while (c > 0 && this.buffer[c - 1] !== '\n') c--; return c; }
+  lineEnd() { let c = this.cursor; while (c < this.buffer.length && this.buffer[c] !== '\n') c++; return c; }
+  vertical(direction, columns) {
+    if (columns) {
+      const layout = this.layout(columns), target = layout.cursorRow + direction;
+      const candidates = layout.positions.filter(position => position.row === target);
+      if (!candidates.length) return false;
+      this.cursor = (candidates.filter(position => position.column <= layout.cursorColumn).at(-1) || candidates[0]).index;
+      return true;
+    }
+    const start = this.lineStart(), column = this.cursor - start;
+    if (direction < 0 && start > 0) { let previous = start - 1; while (previous > 0 && this.buffer[previous - 1] !== '\n') previous--; this.cursor = previous + Math.min(column, start - previous - 1); }
+    else if (direction > 0 && this.lineEnd() < this.buffer.length) {
+      const next = this.lineEnd() + 1; let end = next; while (end < this.buffer.length && this.buffer[end] !== '\n') end++; this.cursor = next + Math.min(column, end - next);
+    } else return false;
+    return true;
+  }
+  recall(direction) {
+    if (!this.history.length) return;
+    if (this.historyIndex === -1) { if (direction > 0) return; this.scratch = this.text; this.scratchAttachments = this.attachments; this.historyIndex = this.history.length; }
+    this.historyIndex = Math.max(0, Math.min(this.history.length, this.historyIndex + direction));
+    this.setText(this.historyIndex === this.history.length ? this.scratch : this.history[this.historyIndex], undefined, this.historyIndex === this.history.length ? this.scratchAttachments : this.historyAttachments[this.historyIndex]);
+  }
+  key(text, key = {}, columns) {
+    const name = key.name;
+    if (name === 'left') this.cursor = key.ctrl || key.meta ? this.boundary(-1) : Math.max(0, this.cursor - 1);
+    else if (name === 'right') this.cursor = key.ctrl || key.meta ? this.boundary(1) : Math.min(this.buffer.length, this.cursor + 1);
+    else if (name === 'home' || (key.ctrl && name === 'a')) this.cursor = this.lineStart();
+    else if (name === 'end' || (key.ctrl && name === 'e')) this.cursor = this.lineEnd();
+    else if (name === 'backspace') { const start = key.ctrl || key.meta ? this.boundary(-1) : Math.max(0, this.cursor - 1); this.buffer.splice(start, this.cursor - start); this.cursor = start; }
+    else if (name === 'delete') this.buffer.splice(this.cursor, key.ctrl ? this.boundary(1) - this.cursor : 1);
+    else if (key.ctrl && name === 'u') { const start = this.lineStart(); this.buffer.splice(start, this.cursor - start); this.cursor = start; }
+    else if (key.ctrl && name === 'k') this.buffer.splice(this.cursor, this.lineEnd() - this.cursor);
+    else if (key.ctrl && name === 'w') { const start = this.boundary(-1); this.buffer.splice(start, this.cursor - start); this.cursor = start; }
+    else if (name === 'up' || (key.ctrl && name === 'p')) { if (key.ctrl || !this.vertical(-1, columns)) this.recall(-1); }
+    else if (name === 'down' || (key.ctrl && name === 'n')) { if (key.ctrl || !this.vertical(1, columns)) this.recall(1); }
+    else if ((name === 'return' && (key.meta || key.shift)) || name === 'linefeed' || (key.ctrl && name === 'j')) this.insert('\n');
+    else if (!key.ctrl && !key.meta && text && !text.startsWith('\x1b')) this.insert(text);
+    this.pruneAttachments();
+  }
+  layout(columns) {
+    columns = Math.max(2, columns); const lines = [''], positions = []; let row = 0, column = 0, cursorRow = 0, cursorColumn = 0;
+    for (let i = 0; i <= this.buffer.length; i++) {
+      const atom = this.buffer[i], visible = this.attachmentMap.has(atom) ? clip(atom, columns, columns > 1 ? '…' : '') : atom === '\t' ? '    ' : atom;
+      const size = atom && atom !== '\n' ? width(visible) : 0;
+      if (atom && atom !== '\n' && column + size > columns) { lines.push(''); row++; column = 0; }
+      positions.push({ index: i, row, column });
+      if (i === this.cursor) { cursorRow = row; cursorColumn = column; }
+      if (i === this.buffer.length) break;
+      if (atom === '\n') { lines.push(''); row++; column = 0; continue; }
+      lines[row] += visible; column += size;
+      if (column === columns) { lines.push(''); row++; column = 0; }
+    }
+    return { lines, cursorRow, cursorColumn, positions };
+  }
+}

package/src/tui/controller.mjs

@@ -0,0 +1,230 @@
+import { t } from '../i18n/index.mjs';
+import { mkdtemp, writeFile, readFile, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { MessageQueue, QueueRunner } from './message-queue.mjs';
+import { shellCommands } from '../auto-guard.mjs';
+import { findImageCandidates } from '../image-attachments.mjs';
+import { Composer } from './composer.mjs';
+import { isRemoteCommand } from '../remote-commands.mjs';
+
+const IMMEDIATE = new Set(['cloud', 'remote-control', 'rc', 'help', 'copy', 'select', 'status', 'context', 'tools', 'house', 'state', 'audit', 'board', 'tasks', 'work', 'operations', 'plugins', 'sessions', 'resume', 'clear', 'model', 'models', 'effort', 'capabilities', 'login', 'logout', 'permissions', 'rename', 'table', 'queue', 'agents', 'mcp','list-agents','inbox','providers','provider', 'exit', 'quit']);
+
+export class InteractiveController {
+  constructor(ui, backend) { this.ui = ui; this.backend = backend; this.closed = false; this.switching = false; this.draftTimer = null; this.pendingDraft = null; }
+  async start(session, initialPrompt = '') {
+    this.attachSession(session);
+    this.ui.configure({ onSubmit: (text, attachments) => this.submit(text, attachments), onPrepareSubmit: snapshot => this.prepareSubmit(snapshot), onAction: (name, arg) => this.action(name, arg), onDraft: (text, attachments) => this.scheduleDraft(text, attachments), onDiscover: () => this.refreshDiscovery(), onCapabilitiesChanged: () => this.previewImages() });
+    this.previewImages();
+    if(this.backend.hasPeerMessages){this.peerTimer=setInterval(()=>this.kickPeers(),300);this.peerTimer.unref();}
+    if (initialPrompt.trim()) await this.submit(initialPrompt);
+    else if (session.goal?.status === 'active') await this.submit('/goal resume');
+    return this.ui.finished;
+  }
+  modalOverlay() { return this.ui.hasModalOverlay?.() ?? Boolean(this.ui.overlay); }
+  refreshDiscovery() { const context = this.backend.discovery?.(); if (context) this.ui.setDiscovery?.(context); }
+  attachSession(session) {
+    this.session = session; this.ui.loadSession(session); this.ui.updateMetadata(this.backend.metadata());
+    const id = session.id;
+    this.queue = new MessageQueue(session.queue, snapshot => this.backend.saveQueue(id, snapshot));
+    this.runner = new QueueRunner(this.queue, async item => {
+      if(item.remote){await this.backend.validateRemote(item);if(item.text.trimStart().startsWith('/')&&!isRemoteCommand(item.text))throw new Error('This command is only available in the local terminal.');}
+      this.ui.setBusy(true);
+      try { return await this.backend.execute(item.text, { userIntent: item.text, attachments: item.attachments || [], shouldYield: () => this.queue.items.length > 0 }); }
+      finally { this.ui.setBusy(false); }
+    }, { blocked: () => Boolean(this.peerProcessing || this.ui.selecting || this.modalOverlay() || this.ui.editingQueue || this.switching || this.closed), onChange: () => { this.syncQueue(); this.refreshDiscovery(); }, onError: error => this.ui.notice(error.message, true) });
+    this.syncQueue(); this.refreshDiscovery();
+    if (this.queue.items.length || this.queue.interrupted.length) this.ui.notice(t("The recovered queue is paused. Check F4 before resuming; interrupted messages were not resent."));
+  }
+  kickPeers(){
+    if(this.peerProcessing || this.ui.busy || this.runner.processing || this.queue.paused || this.queue.items.length || this.modalOverlay() || this.ui.selecting || this.ui.editingQueue || this.switching || this.closed)return;
+    this.peerProcessing=(async()=>{
+      if(!await this.backend.hasPeerMessages() || this.closed)return;
+      this.ui.setBusy(true);
+      try{await this.backend.executePeer({shouldYield:()=>this.queue.items.length>0 || this.closed});}
+      finally{this.ui.setBusy(false);}
+    })().catch(error=>this.ui.notice(error.message,true)).finally(()=>{this.peerProcessing=null;this.runner.kick();});
+  }
+  syncQueue() { this.ui.setQueue(this.queue.snapshot()); if (this.ui.overlay?.kind === 'queue') this.ui.overlay.index = Math.min(this.ui.overlay.index, Math.max(0, this.queue.items.length - 1)); }
+  scheduleDraft(text, attachments = this.ui.composer.attachments || []) {
+    clearTimeout(this.draftTimer); this.pendingDraft = { id: this.session.id, text, attachments };
+    this.draftTimer = setTimeout(() => { this.flushDraft().catch(e => this.ui.notice(e.message, true)); }, 500);
+    clearTimeout(this.imageTimer);
+    if (this.backend.stageAttachment) this.imageTimer = setTimeout(() => this.previewImages(), 80);
+  }
+  async flushDraft() { clearTimeout(this.draftTimer); const pending = this.pendingDraft; this.pendingDraft = null; if (pending) await this.backend.saveDraft(pending.id, pending.text, pending.attachments); }
+  imageStatus(status) { this.ui.setAttachmentStatus?.(status); }
+  async normalizeImages(snapshot) {
+    if (!this.backend.stageAttachment) return snapshot;
+    const id = this.session.id, signature = JSON.stringify([id, snapshot.text, snapshot.attachments]);
+    if (this.imagePending?.signature === signature) return this.imagePending.promise;
+    const promise = (async () => {
+      const draft = new Composer(); draft.setText(snapshot.text, snapshot.cursor, snapshot.attachments);
+      const candidates = /^\/[a-z][\w-]*(?:\s|$)/i.test(snapshot.text.trimStart()) ? [] : findImageCandidates(snapshot.text, { cwd: this.backend.metadata().cwd });
+      for (const candidate of candidates.reverse()) {
+        if (draft.attachments.length >= 2) throw new Error(t('Attach up to two images per message.'));
+        if (this.closed || this.session.id !== id) throw new Error(t('The session changed; the image was not attached.'));
+        const descriptor = await this.backend.stageAttachment(candidate, id);
+        draft.addAttachment(descriptor, candidate);
+      }
+      return draft.snapshot();
+    })();
+    const pending = { signature, promise }; this.imagePending = pending;
+    try { return await promise; } finally { if (this.imagePending === pending) this.imagePending = null; }
+  }
+  async visionStatus(snapshot) {
+    const generation = this.visionGeneration = (this.visionGeneration || 0) + 1;
+    if (!snapshot.attachments?.length) { this.imageStatus(null); return true; }
+    const id = this.session.id, model = this.backend.metadata().model;
+    this.imageStatus({ state: 'checking', message: t('Checking vision support…') });
+    let capability;
+    try { capability = await this.backend.attachmentCapability?.(); }
+    catch { capability = { supported: false, source: 'unknown' }; }
+    if (this.closed || this.session.id !== id || this.backend.metadata().model !== model || this.visionGeneration !== generation) return false;
+    const supported = capability?.supported === true;
+    const message = supported ? t('{count} image(s) attached · Backspace removes a label', { count: snapshot.attachments.length })
+      : t('This model cannot receive images or vision is unverified. Switch model or remove the image before sending.');
+    if (this.ui.composer.text === snapshot.text) this.imageStatus({ state: supported ? 'ready' : 'unsupported', message });
+    return supported;
+  }
+  async previewImages() {
+    if (this.closed || this.switching || !this.backend.stageAttachment) return;
+    const id = this.session.id, snapshot = this.ui.composer.snapshot(), stamp = JSON.stringify(snapshot);
+    try {
+      if (findImageCandidates(snapshot.text, { cwd: this.backend.metadata().cwd }).length) this.imageStatus({ state: 'checking', message: t('Attaching image…') });
+      const prepared = await this.normalizeImages(snapshot);
+      if (this.closed || this.session.id !== id || JSON.stringify(this.ui.composer.snapshot()) !== stamp) return;
+      if (prepared.text !== snapshot.text) {
+        this.ui.composer.setText(prepared.text, prepared.cursor, prepared.attachments);
+        this.scheduleDraft(prepared.text, prepared.attachments); this.ui.schedule?.();
+      }
+      await this.visionStatus(prepared);
+    } catch (error) { if (!this.closed && this.session.id === id && this.ui.composer.text === snapshot.text) this.imageStatus({ state: 'invalid', message: error.message }); }
+  }
+  async prepareSubmit(snapshot) {
+    const id = this.session.id, prepared = await this.normalizeImages(snapshot);
+    if (this.closed || this.switching || this.session.id !== id) throw new Error(t('The session changed; the message was not sent.'));
+    if (JSON.stringify(this.ui.composer.snapshot()) === JSON.stringify(snapshot) && prepared.text !== snapshot.text) {
+      this.ui.composer.setText(prepared.text, prepared.cursor, prepared.attachments); this.scheduleDraft(prepared.text, prepared.attachments); this.ui.schedule?.();
+    }
+    if (!await this.visionStatus(prepared)) throw new Error(t('Image not sent: the current model does not support verified vision.'));
+    if (prepared.attachments?.length && prepared.text.trimStart().startsWith('/')) throw new Error(t('Use a plain message with images; commands do not accept image attachments.'));
+    return prepared;
+  }
+  async submit(text, attachments) {
+    if (this.closed || this.switching) throw new Error(t("The session is changing; keep the message and resend it."));
+    if (attachments === undefined && this.backend.stageAttachment) {
+      const prepared = await this.prepareSubmit({ text, attachments: [], cursor: undefined }); text = prepared.text; attachments = prepared.attachments;
+    }
+    attachments ||= [];
+    if (this.ui.editingQueue) {
+      const editing = this.ui.editingQueue; await this.queue.update(editing.id, text, attachments); this.ui.editingQueue = null;
+      this.ui.setDraft(editing.draft, editing.attachments); this.scheduleDraft(editing.draft, editing.attachments); await this.queue.setPaused(editing.wasPaused); this.syncQueue(); this.runner.kick(); return;
+    }
+    const trimmed = text.trim(), match = /^\/(\S+)(?:\s+([\s\S]*))?$/.exec(trimmed);
+    const mcpMutation = match?.[1] === 'mcp' && match[2] && !/^(?:status|list|config)(?:\s|$)/.test(match[2]);
+    const workResume = match?.[1] === 'work' && match[2]?.trim() === 'resume';
+    const pluginMutation = match?.[1] === 'plugins' && match[2] && !/^(?:status|list)(?:\s|$)/.test(match[2]);
+    const modelMutation = match && (['model', 'effort', 'provider'].includes(match[1]) && match[2]?.trim() || ['login', 'logout'].includes(match[1]));
+    const modelBusy = modelMutation && (this.peerProcessing || this.ui.busy || this.queue.running || this.runner.processing);
+    if (match && IMMEDIATE.has(match[1]) && !mcpMutation && !pluginMutation && !workResume && !modelBusy) { await this.command(match[1], match[2] || ''); return; }
+    if (match?.[1] === 'goal' && (!match[2] || ['status', 'pause', 'clear', 'stop', 'off', 'reset', 'none', 'cancel'].includes(match[2].trim().toLowerCase()))) {
+      const arg = match[2]?.trim().toLowerCase() || 'status';
+      if (this.ui.busy && arg !== 'status') { await this.queue.setPaused(true); this.backend.interrupt(); await this.runner.processing; }
+      await this.backend.goalControl(arg); this.syncQueue(); return;
+    }
+    await this.queue.enqueue(text, attachments); this.syncQueue(); this.runner.kick();
+  }
+  async requireIdle() { if (this.peerProcessing || this.ui.busy || this.queue.running || this.runner.processing) throw new Error(t("Cancel the turn with Esc or Ctrl+C before switching session or model.")); }
+  async admitRemote(input, remote) {
+    if(this.closed || this.switching)throw new Error('Local session unavailable.');
+    const accepted=await this.queue.enqueueRemote(input.text,remote);this.syncQueue();this.runner.kick();return accepted;
+  }
+  async stopRemote(turnId) {
+    if(this.closed || !this.backend.remoteTurnMatches(turnId))return false;
+    await this.queue.setPaused(true);if(!this.backend.remoteTurnMatches(turnId))return false;this.backend.interrupt();this.syncQueue();return true;
+  }
+  async command(command, arg) {
+    if (['exit', 'quit'].includes(command)) return this.exit();
+    if (command === 'copy' || command === 'select') {
+      if (arg.trim()) throw new Error(t("Use /{v0} without arguments.", {v0: command}));
+      if (command === 'copy') await this.ui.copyResponse(); else this.ui.setSelection();
+      return;
+    }
+    if (['rc','remote-control'].includes(command) && ['', 'start'].includes(arg.trim()))await this.requireIdle();
+    if (command === 'help') { this.ui.showHelp(); return; }
+    if (command === 'sessions' || (command === 'resume' && !arg)) { this.ui.showSessions(await this.backend.listSessions()); return; }
+    if (command === 'resume' || command === 'clear') {
+      await this.requireIdle(); this.switching = true;
+      try { await this.backend.detachRemote?.(); await this.flushDraft(); const next = await this.backend.activate(command === 'clear' ? null : arg); this.ui.overlay = null; this.ui.editingQueue = null; this.attachSession(next); }
+      finally { this.switching = false; }
+      return;
+    }
+    if (command === 'queue') {
+      if (!arg) this.ui.showQueue();
+      else if (arg === 'pause') await this.queue.setPaused(true);
+      else if (arg === 'resume') { await this.queue.setPaused(false); this.ui.closeOverlay(); this.runner.kick(); }
+      else if (arg === 'clear') await this.queue.clear();
+      else if (/^edit \d+$/.test(arg)) { const item = this.queue.items[Number(arg.slice(5)) - 1]; if (!item) throw new Error(t("Invalid message number.")); await this.action('queueEdit', item.id); }
+      else throw new Error(t("Use /queue, /queue pause|resume|clear or /queue edit N."));
+      this.syncQueue(); return;
+    }
+    if (['board', 'tasks', 'work'].includes(command)) { this.ui.showBoard(JSON.parse(await this.backend.control('board', ''))); return; }
+    if (['cloud', 'model', 'effort', 'provider', 'login', 'logout'].includes(command) && (arg.trim() || ['login', 'logout'].includes(command))) await this.requireIdle();
+    if (command === 'table') { if (!arg) throw new Error(t("Use /table file.csv|tsv|json|md.")); const table = await this.backend.readTable(arg); this.ui.addTable(table.text, table.format, arg); return; }
+    const changing=(['cloud','model','effort','provider','login','logout'].includes(command) && (arg.trim() || ['login','logout'].includes(command))) || (['rc','remote-control'].includes(command) && ['', 'start'].includes(arg.trim()));
+    if(changing)this.switching=true;
+    try {
+      const output=await this.backend.control(command,arg);if(output)this.ui.notice(output);
+      this.ui.updateMetadata(this.backend.metadata()); this.refreshDiscovery();
+    } finally {if(changing){this.switching=false;this.runner.kick();}}
+
+  }
+  async action(name, arg) {
+    if (name === 'exit') return this.exit();
+    if (name === 'interrupt') { this.backend.interrupt(); await this.queue.setPaused(true); this.syncQueue(); return; }
+    if (name === 'cycleMode') { await this.backend.cycleMode(); this.ui.updateMetadata(this.backend.metadata()); this.refreshDiscovery(); return; }
+    if (name === 'board') return this.command('board', '');
+    if (name === 'sessions') { this.ui.showSessions(await this.backend.listSessions()); return; }
+    if (name === 'resume') return this.command('resume', arg);
+    if (name === 'queueKick') return this.runner.kick();
+    if (name === 'queueEdit') {
+      const item = this.queue.items.find(item => item.id === arg); if (!item) throw new Error(t("That message is already running or has left the queue."));
+      const wasPaused = this.queue.paused; await this.queue.setPaused(true);
+      this.ui.editingQueue = { id: arg, draft: this.ui.composer.text, attachments: this.ui.composer.attachments, wasPaused };
+      this.ui.overlay = null; this.ui.setDraft(item.text, item.attachments); this.scheduleDraft(item.text, item.attachments); this.syncQueue(); return;
+    }
+    if (name === 'queueEditCancel') {
+      const editing = this.ui.editingQueue; if (!editing) return;
+      this.ui.editingQueue = null; this.ui.setDraft(editing.draft, editing.attachments); this.scheduleDraft(editing.draft, editing.attachments); await this.queue.setPaused(editing.wasPaused); this.syncQueue(); this.runner.kick(); return;
+    }
+    if (name === 'queueRemove') await this.queue.remove(arg);
+    if (name === 'queueMove') { await this.queue.move(arg.id, arg.delta); if (this.ui.overlay?.kind === 'queue') this.ui.overlay.index = Math.max(0, this.queue.items.findIndex(item => item.id === arg.id)); }
+    if (name === 'queueToggle') await this.queue.setPaused(!this.queue.paused);
+    if (name === 'queueRetry') await this.queue.retryInterrupted(arg);
+    if (name === 'editor') { await this.externalEditor(); return; }
+    this.syncQueue(); this.runner.kick();
+  }
+  async externalEditor() {
+    const attachments = this.ui.composer.attachments || [];
+    const commands = shellCommands(process.env.VISUAL || process.env.EDITOR || 'vi');
+    if (!commands || commands.length !== 1 || !commands[0].length) throw new Error(t("$VISUAL/$EDITOR must be an executable with arguments, without shell expansions."));
+    const dir = await mkdtemp(path.join(os.tmpdir(), 'comal-composer-')), file = path.join(dir, 'message.md');
+    await writeFile(file, this.ui.composer.text, { mode: 0o600 });
+    const wasPaused = this.queue.paused; await this.queue.setPaused(true); this.syncQueue(); this.ui.suspend();
+    try {
+      const [command, ...args] = commands[0], child = spawn(command, [...args, file], { stdio: 'inherit' });
+      const [code] = await once(child, 'close');
+      if (code !== 0) throw new Error(t("The editor exited with code {v0}; the previous draft is kept.", {v0: code}));
+      const text = await readFile(file, 'utf8'); if (Buffer.byteLength(text) > 1024 * 1024) throw new Error(t("The editor produced more than 1 MiB; the previous draft is kept."));
+      const restored = attachments.map(({start,end,...attachment}) => attachment);
+      this.ui.setDraft(text, restored); this.scheduleDraft(text, this.ui.composer.attachments);
+    } finally { await rm(dir, { recursive: true, force: true }); this.ui.resume(); await this.queue.setPaused(wasPaused); this.syncQueue(); this.runner.kick(); }
+  }
+  async exit() {
+    if (this.closed) return; this.closed = true; clearInterval(this.peerTimer);clearTimeout(this.imageTimer);this.runner.stopped = true; this.backend.interrupt();
+    this.ui.permission?.finish(false); await this.runner.processing;await this.peerProcessing; await this.flushDraft(); await this.queue.save(); this.ui.close();
+  }
+}