subrouter-cli 0.0.0-stage → 0.1.0

package/src/commandpolicy.ts

@@ -0,0 +1,272 @@
+import { constants } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export interface CommandPolicyResult { auto: boolean; reason: string }
+
+const MAX_COMMAND = 8192;
+const MAX_MANIFEST = 64 * 1024;
+const MAX_DEPTH = 8;
+const MAX_COUNT = 64;
+const MAX_TEXT = 32 * 1024;
+const ASK: CommandPolicyResult = { auto: false, reason: 'This command requires explicit approval.' };
+const TRUSTED: CommandPolicyResult = {
+  auto: true,
+  reason: 'Recognized project check or build; it runs trusted project code and is not sandboxed.',
+};
+const INSPECT: CommandPolicyResult = {
+  auto: true,
+  reason: 'Recognized inspection command; trusted tool configuration still applies and this is not a sandbox.',
+};
+interface Context { root: string; count: number; text: number; active: Set<string> }
+
+// Deliberately not a shell parser: only whole literal/quoted tokens and &&.
+// Reject even quoted metacharacters rather than try to model shell expansions.
+function lex(command: string): string[][] | undefined {
+  if (!command || command.length > MAX_COMMAND || /[^\x20-\x7e]|[$`\\;|<>#~!*?()[\]{}^]/.test(command)) return;
+  const segments: string[][] = [[]];
+  let i = 0;
+  while (i < command.length) {
+    if (command[i] === ' ') { i++; continue; }
+    if (command.slice(i, i + 2) === '&&') {
+      if (!segments.at(-1)!.length || segments.length >= 16) return;
+      segments.push([]); i += 2; continue;
+    }
+    let token = '';
+    const quote = command[i] === '"' || command[i] === "'" ? command[i++] : undefined;
+    if (quote) {
+      const start = i;
+      while (i < command.length && command[i] !== quote) i++;
+      if (i === command.length) return;
+      token = command.slice(start, i++);
+      if (!token || !/^[A-Za-z0-9_./:@%+,= -]+$/.test(token)) return;
+    } else {
+      const start = i;
+      while (i < command.length && command[i] !== ' ' && command[i] !== '&') i++;
+      token = command.slice(start, i);
+      if (!token || !/^[A-Za-z0-9_./:@%+,=-]+$/.test(token)) return;
+    }
+    if (i < command.length && command[i] !== ' ' && command.slice(i, i + 2) !== '&&') return;
+    const segment = segments.at(-1)!;
+    if (segment.length >= 128) return;
+    segment.push(token);
+  }
+  return segments.at(-1)!.length ? segments : undefined;
+}
+
+// No absolute paths, parent components, option-like paths, or Git pathspec magic.
+// Existing paths must also resolve inside cwd (including through symlinks).
+async function localPath(value: string, ctx: Context, kind: 'any' | 'script' | 'json' = 'any'): Promise<boolean> {
+  if (!value || value.startsWith('-') || path.isAbsolute(value) || !/^[A-Za-z0-9_./@+ -]+$/.test(value)) return false;
+  if (value.split('/').some((part) => part === '..' || part.startsWith('-'))) return false;
+  if (kind === 'script' && !/\.[cm]?[jt]s$/.test(value)) return false;
+  if (kind === 'json' && !value.endsWith('.json')) return false;
+  try {
+    const real = await fs.realpath(path.resolve(ctx.root, value));
+    const relative = path.relative(ctx.root, real);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return false;
+    const stat = await fs.stat(real);
+    return kind === 'any' ? stat.isFile() || stat.isDirectory() : stat.isFile();
+  } catch { return false; }
+}
+
+async function readScripts(root: string): Promise<Record<string, unknown> | undefined> {
+  // O_NONBLOCK prevents a FIFO from hanging before fstat; O_NOFOLLOW rejects a
+  // symlinked manifest. Read one bounded buffer, not readFile (files can grow).
+  if (typeof constants.O_NOFOLLOW !== 'number' || typeof constants.O_NONBLOCK !== 'number') return;
+  let handle: Awaited<ReturnType<typeof fs.open>> | undefined;
+  try {
+    handle = await fs.open(path.join(root, 'package.json'), constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size > MAX_MANIFEST) return;
+    const buffer = Buffer.alloc(MAX_MANIFEST + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, length, buffer.length - length, null);
+      if (!bytesRead) break;
+      length += bytesRead;
+    }
+    if (length > MAX_MANIFEST) return;
+    const manifest: unknown = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, length)));
+    if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) return;
+    const scripts = (manifest as Record<string, unknown>).scripts;
+    if (!scripts || typeof scripts !== 'object' || Array.isArray(scripts)) return;
+    return scripts as Record<string, unknown>;
+  } catch { return; }
+  finally { await handle?.close().catch(() => {}); }
+}
+
+async function npmPolicy(args: string[], ctx: Context, depth: number): Promise<CommandPolicyResult> {
+  const script = args.length === 1 && args[0] === 'test' ? 'test'
+    : args.length === 2 && args[0] === 'run' && ['build', 'test', 'lint', 'typecheck', 'check'].includes(args[1]) ? args[1] : undefined;
+  if (!script || depth >= MAX_DEPTH || ctx.active.has(script)) return ASK;
+  const scripts = await readScripts(ctx.root);
+  if (!scripts || !Object.hasOwn(scripts, script)) return ASK;
+  ctx.active.add(script);
+  try {
+    for (const name of [`pre${script}`, script, `post${script}`]) {
+      if (!Object.hasOwn(scripts, name)) continue;
+      const text = scripts[name];
+      if (typeof text !== 'string' || !(await inspect(text, ctx, depth + 1)).auto) return ASK;
+    }
+    return TRUSTED;
+  } finally { ctx.active.delete(script); }
+}
+
+function positive(value: string, max: number): boolean {
+  return /^[1-9][0-9]*$/.test(value) && Number(value) <= max;
+}
+
+async function nodePolicy(args: string[], ctx: Context): Promise<boolean> {
+  if (args.shift() !== '--test') return false;
+  const seen = new Set<string>();
+  let paths = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!paths && arg === '--') { paths = true; continue; }
+    if (!paths && arg.startsWith('-')) {
+      const eq = arg.indexOf('=');
+      const flag = eq < 0 ? arg : arg.slice(0, eq);
+      if (seen.has(flag)) return false;
+      seen.add(flag);
+      if (flag === '--test-only' && eq < 0) continue;
+      if (!['--test-concurrency', '--test-reporter', '--test-timeout', '--test-name-pattern', '--test-skip-pattern'].includes(flag)) return false;
+      const value = eq < 0 ? args[++i] : arg.slice(eq + 1);
+      if (!value) return false;
+      if (flag === '--test-reporter' && !['dot', 'spec', 'tap'].includes(value)) return false;
+      if (flag === '--test-concurrency' && !positive(value, 256)) return false;
+      if (flag === '--test-timeout' && !positive(value, 600000)) return false;
+      if (flag.endsWith('-pattern') && !/^[A-Za-z0-9_][A-Za-z0-9_ .-]*$/.test(value)) return false;
+    } else if (!(await localPath(arg, ctx, 'script'))) return false;
+  }
+  return true;
+}
+
+async function tscPolicy(args: string[], ctx: Context): Promise<boolean> {
+  const seen = new Set<string>();
+  let build = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--build' || arg === '-b') {
+      if (i !== 0 || seen.has('project')) return false;
+      build = true; continue;
+    }
+    if (arg === '--project' || arg === '-p') {
+      if (build || seen.has('project') || !args[i + 1] || !(await localPath(args[++i], ctx, 'json'))) return false;
+      seen.add('project'); continue;
+    }
+    if (build && !arg.startsWith('-')) {
+      if (!(await localPath(arg, ctx, 'json'))) return false;
+      continue;
+    }
+    if (!['--noEmit', '--pretty', '--strict', '--skipLibCheck', '--incremental', '--composite'].includes(arg) || seen.has(arg)) return false;
+    seen.add(arg);
+    if (args[i + 1] === 'true' || args[i + 1] === 'false') {
+      if (arg === '--noEmit' && args[i + 1] === 'false') return false;
+      i++;
+    }
+  }
+  return true;
+}
+
+async function eslintPolicy(args: string[], ctx: Context): Promise<boolean> {
+  let paths = 0;
+  let positional = false;
+  const seen = new Set<string>();
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!positional && arg === '--') { positional = true; continue; }
+    if (!positional && arg.startsWith('-')) {
+      const eq = arg.indexOf('=');
+      const flag = eq < 0 ? arg : arg.slice(0, eq);
+      if (seen.has(flag)) return false;
+      seen.add(flag);
+      if (['--quiet', '--no-fix', '--no-warn-ignored'].includes(flag) && eq < 0) continue;
+      if (!['--max-warnings', '--ext', '--format', '-f'].includes(flag)) return false;
+      const value = eq < 0 ? args[++i] : arg.slice(eq + 1);
+      if (!value) return false;
+      if (flag === '--max-warnings' && !/^(0|[1-9][0-9]{0,3})$/.test(value)) return false;
+      if (flag === '--ext' && !/^\.[cm]?[jt]sx?(,\.[cm]?[jt]sx?)*$/.test(value)) return false;
+      if ((flag === '--format' || flag === '-f') && !['stylish', 'json'].includes(value)) return false;
+    } else {
+      if (!(await localPath(arg, ctx))) return false;
+      paths++;
+    }
+  }
+  return paths > 0;
+}
+
+async function gitPolicy(args: string[], ctx: Context): Promise<boolean> {
+  // Do not silently rewrite commands. Require callback-disabling flags in the
+  // actual command: pager for all forms, external diff/textconv for patch tools.
+  if (args.shift() !== '--no-pager') return false;
+  const sub = args.shift();
+  if (!sub || !['status', 'diff', 'log', 'show', 'ls-files'].includes(sub)) return false;
+  if ((sub === 'diff' || sub === 'show') && (!args.includes('--no-ext-diff') || !args.includes('--no-textconv'))) return false;
+  const flags: Record<string, string[]> = {
+    status: ['--short', '-s', '--branch', '-b', '--porcelain', '--porcelain=v1', '--porcelain=v2', '--untracked-files=no', '--untracked-files=normal', '--untracked-files=all'],
+    diff: ['--no-ext-diff', '--no-textconv', '--no-color', '--cached', '--staged', '--stat', '--shortstat', '--numstat', '--name-only', '--name-status', '--check'],
+    log: ['--oneline', '--no-color', '--no-decorate', '--decorate=no'],
+    show: ['--no-ext-diff', '--no-textconv', '--no-color', '--stat', '--name-only', '--name-status'],
+    'ls-files': ['--cached', '-c', '--modified', '-m', '--deleted', '-d', '--others', '-o', '--exclude-standard', '--stage', '-s'],
+  };
+  const seen = new Set<string>();
+  let positional = false;
+  let revisions = 0;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!positional && arg === '--') { positional = true; continue; }
+    if (!positional && flags[sub].includes(arg)) {
+      if (seen.has(arg)) return false;
+      seen.add(arg); continue;
+    }
+    if (!positional && sub === 'log' && (arg === '-n' || arg === '--max-count' || arg.startsWith('--max-count='))) {
+      if (seen.has('count')) return false;
+      seen.add('count');
+      const value = arg.startsWith('--max-count=') ? arg.slice(12) : args[++i];
+      if (!value || !positive(value, 1000)) return false;
+      continue;
+    }
+    if (positional) {
+      if (!(await localPath(arg, ctx))) return false;
+    } else if ((sub === 'log' || sub === 'show') && revisions++ === 0 && /^[A-Za-z0-9][A-Za-z0-9_./-]*$/.test(arg) && !arg.includes('..')) {
+      continue;
+    } else return false;
+  }
+  return true;
+}
+
+async function inspect(command: string, ctx: Context, depth: number): Promise<CommandPolicyResult> {
+  ctx.text += command.length;
+  if (ctx.text > MAX_TEXT || depth > MAX_DEPTH) return ASK;
+  const segments = lex(command);
+  if (!segments) return ASK;
+  let project = false;
+  for (const [executable, ...args] of segments) {
+    if (++ctx.count > MAX_COUNT) return ASK;
+    let result: CommandPolicyResult = ASK;
+    if (executable === 'pwd' && args.length === 0) result = INSPECT;
+    else if (executable === 'git' && await gitPolicy(args, ctx)) result = INSPECT;
+    else if (executable === 'node' && await nodePolicy(args, ctx)) result = TRUSTED;
+    else if (executable === 'tsc' && await tscPolicy(args, ctx)) result = TRUSTED;
+    else if (executable === 'vite' && args.length === 1 && args[0] === 'build') result = TRUSTED;
+    else if (executable === 'eslint' && await eslintPolicy(args, ctx)) result = TRUSTED;
+    else if (executable === 'npm') result = await npmPolicy(args, ctx, depth);
+    if (!result.auto) return ASK;
+    project ||= result === TRUSTED;
+  }
+  return project ? TRUSTED : INSPECT;
+}
+
+/** A conservative approval heuristic, not an OS sandbox or executable verifier.
+ * Tests/builds and tool configuration are trusted; executors must recheck at
+ * approval/execution time because package scripts can change. Nothing is cached.
+ */
+export async function commandPolicy(command: string, cwd: string): Promise<{ auto: boolean; reason: string }> {
+  try {
+    if (typeof command !== 'string' || typeof cwd !== 'string') return { ...ASK };
+    const root = await fs.realpath(cwd);
+    if (!(await fs.stat(root)).isDirectory()) return { ...ASK };
+    return { ...await inspect(command, { root, count: 0, text: 0, active: new Set() }, 0) };
+  } catch { return { ...ASK }; }
+}

package/src/commands.ts

@@ -0,0 +1,18 @@
+// One catalog for the command palette; no command text is sent to the agent.
+export const COMMANDS = [
+  { id: '/model', description: 'Choose a model' },
+  { id: '/models', description: 'Browse the model catalog' },
+  { id: '/usage', description: 'Live provider usage and account limits' },
+  { id: '/effort', description: 'Choose reasoning effort' },
+  { id: '/mode', description: 'Permissions: ask, files, auto, or absolute (warning required)' },
+  { id: '/clear', description: 'Start a fresh conversation' },
+  { id: '/exit', description: 'Exit sub' },
+];
+
+export function matchingCommands(text: string): typeof COMMANDS {
+  if (!text.startsWith('/') || /\s/.test(text)) return [];
+  const matches = COMMANDS.filter((command) => command.id.startsWith(text.toLowerCase()));
+  // /mode is also a prefix of /model: a fully typed command must win.
+  const exact = matches.find((command) => command.id === text.toLowerCase());
+  return exact ? [exact, ...matches.filter((command) => command !== exact)] : matches;
+}

package/src/config.ts

@@ -0,0 +1,107 @@
+// Config loading. Key precedence: SUBROUTER_API_KEY env > ~/.config/subrouter-cli/config.json.
+// The real key is never logged or printed — not even in masked form (see CLAUDE.md).
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { parseEffort, type EffortLevel } from './effort.ts';
+
+export interface SubConfig {
+  base_url: string;
+  api_key: string | null;
+  default_model: string | null;
+  reasoning_effort: EffortLevel;
+  max_output_tokens: number;
+  max_tool_rounds: number;
+  auto_approve: boolean;
+}
+
+export interface ResolvedConfig {
+  baseUrl: string; // OpenAI-compatible root (with /v1)
+  apiKey: string;
+  defaultModel: string | null;
+  reasoningEffort: EffortLevel;
+  maxOutputTokens: number;
+  maxToolRounds: number;
+  autoApprove: boolean;
+  configPath: string | null; // where the config file lives (null when only env was used)
+}
+
+const DEFAULTS: SubConfig = {
+  base_url: 'https://router.eva.pink/v1',
+  api_key: null,
+  default_model: null,
+  reasoning_effort: 'auto',
+  max_output_tokens: 8192,
+  max_tool_rounds: 25,
+  auto_approve: false,
+};
+
+export function configDir(): string {
+  return path.join(os.homedir(), '.config', 'subrouter-cli');
+}
+
+export function configPath(): string {
+  return path.join(configDir(), 'config.json');
+}
+
+function loadConfigFile(): SubConfig | null {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(configPath(), 'utf8');
+  } catch {
+    return null; // no file yet — normal on first run
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return null;
+    return { ...DEFAULTS, ...(parsed as Record<string, unknown>) };
+  } catch {
+    return null; // corrupt file — caller warns
+  }
+}
+
+/** Merge a patch into the config file, creating it (chmod 600) if needed. */
+export function saveConfigFile(patch: Partial<SubConfig>): void {
+  const dir = configDir();
+  fs.mkdirSync(dir, { recursive: true });
+  const current = loadConfigFile() ?? DEFAULTS;
+  const next = { ...current, ...patch };
+  const file = configPath();
+  fs.writeFileSync(file, JSON.stringify(next, null, 2) + '\n');
+  fs.chmodSync(file, 0o600);
+}
+
+export function resolveConfig(): { config: ResolvedConfig; warnings: string[] } {
+  const warnings: string[] = [];
+  const file = loadConfigFile();
+  if (file === null && fs.existsSync(configPath())) {
+    warnings.push('config file is unreadable or invalid — using defaults');
+  }
+  const reasoningEffort = parseEffort(file?.reasoning_effort) ?? DEFAULTS.reasoning_effort;
+  if (file && parseEffort(file.reasoning_effort) === undefined)
+    warnings.push('invalid reasoning_effort in config — using auto');
+  const envKey = process.env.SUBROUTER_API_KEY?.trim() || null;
+  const fileKey = (file?.api_key || '').trim() || null;
+  if (envKey && fileKey && envKey !== fileKey) {
+    warnings.push('SUBROUTER_API_KEY env overrides the key in the config file');
+  }
+  const baseUrl = (
+    process.env.SUBROUTER_BASE_URL?.trim() ||
+    file?.base_url ||
+    DEFAULTS.base_url
+  ).replace(/\/+$/, '');
+  return {
+    config: {
+      baseUrl,
+      apiKey: envKey ?? fileKey ?? '',
+      defaultModel: (file?.default_model || '').trim() || null,
+      reasoningEffort,
+      maxOutputTokens: file?.max_output_tokens ?? DEFAULTS.max_output_tokens,
+      maxToolRounds: file?.max_tool_rounds ?? DEFAULTS.max_tool_rounds,
+      autoApprove: file?.auto_approve ?? DEFAULTS.auto_approve,
+      configPath: file ? configPath() : null,
+    },
+    warnings,
+  };
+}

package/src/effort.ts

@@ -0,0 +1,18 @@
+// Local preferences, not a promise that every routed model supports every level.
+export const EFFORT_LEVELS = ['auto', 'low', 'medium', 'high', 'xhigh', 'max'] as const;
+export type EffortLevel = typeof EFFORT_LEVELS[number];
+
+export const EFFORT_DESCRIPTIONS: Record<EffortLevel, string> = {
+  auto: 'Use the provider default',
+  low: 'Fast, lightweight reasoning',
+  medium: 'Balance reasoning and latency',
+  high: 'More thorough reasoning',
+  xhigh: 'Extra-high reasoning · model support varies',
+  max: 'Maximum reasoning · model support varies',
+};
+
+export function parseEffort(value: unknown): EffortLevel | undefined {
+  if (typeof value !== 'string') return undefined;
+  const level = value.trim().toLowerCase();
+  return EFFORT_LEVELS.find((effort) => effort === level);
+}

package/src/images.ts

@@ -0,0 +1,77 @@
+// Explicit user-selected local attachments, separate from the agent's confined file tools.
+import fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { stripVTControlCharacters } from 'node:util';
+
+export type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
+export interface ImageAttachment {
+  name: string;
+  mediaType: ImageMediaType;
+  data: string; // base64; never rendered in the terminal
+}
+
+export const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+export const MAX_ATTACHED_IMAGES = 4;
+export const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+
+function mediaType(bytes: Buffer): ImageMediaType | undefined {
+  if (bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) return 'image/png';
+  if (bytes.length >= 3 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) return 'image/jpeg';
+  if (['GIF87a', 'GIF89a'].includes(bytes.subarray(0, 6).toString('ascii'))) return 'image/gif';
+  if (bytes.subarray(0, 4).toString('ascii') === 'RIFF' && bytes.subarray(8, 12).toString('ascii') === 'WEBP') return 'image/webp';
+  return undefined;
+}
+
+export function attachmentPath(value: string, cwd: string): string {
+  let file = value.trim();
+  if (file.length >= 2 && (file[0] === '"' && file.at(-1) === '"' || file[0] === "'" && file.at(-1) === "'"))
+    file = file.slice(1, -1);
+  else file = file.replace(/\\([\\ '"()])/g, '$1'); // macOS drag-and-drop shell escaping
+  if (!file || file.includes('\0')) throw new Error('provide a local image path');
+  if (file === '~' || file.startsWith('~/')) file = path.join(os.homedir(), file.slice(1));
+  return path.resolve(cwd, file);
+}
+
+export function imageFromBytes(bytes: Buffer, name: string): ImageAttachment {
+  if (bytes.length > MAX_IMAGE_BYTES) throw new Error('image exceeds the 10 MiB attachment limit');
+  const type = mediaType(bytes);
+  if (!type) throw new Error('unsupported image — use PNG, JPEG, WebP, or GIF (HEIC is not supported)');
+  return { name: stripVTControlCharacters(path.basename(name)).replace(/[\x00-\x1f\x7f]/g, ' '), mediaType: type, data: bytes.toString('base64') };
+}
+
+export async function loadImage(value: string, cwd: string): Promise<ImageAttachment> {
+  const file = attachmentPath(value, cwd);
+  let handle: Awaited<ReturnType<typeof fs.open>>;
+  try { handle = await fs.open(file, constants.O_RDONLY | constants.O_NONBLOCK); }
+  catch { throw new Error('could not open that image — check the path and file permissions'); }
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile()) throw new Error('attachments must be regular image files');
+    if (stat.size > MAX_IMAGE_BYTES) throw new Error('image exceeds the 10 MiB attachment limit');
+    const chunks: Buffer[] = [];
+    let size = 0;
+    while (true) {
+      const buffer = Buffer.alloc(Math.min(64 * 1024, MAX_IMAGE_BYTES + 1 - size));
+      const { bytesRead } = await handle.read(buffer);
+      if (!bytesRead) break;
+      size += bytesRead;
+      if (size > MAX_IMAGE_BYTES) throw new Error('image exceeds the 10 MiB attachment limit');
+      chunks.push(buffer.subarray(0, bytesRead));
+    }
+    return imageFromBytes(Buffer.concat(chunks, size), file);
+  } finally { await handle.close(); }
+}
+
+export function imageBytes(image: ImageAttachment): number {
+  return Buffer.byteLength(image.data, 'base64');
+}
+
+export function addImages(current: ImageAttachment[], added: ImageAttachment[]): ImageAttachment[] {
+  const images = [...current, ...added];
+  if (images.length > MAX_ATTACHED_IMAGES) throw new Error('attach at most 4 images per prompt — Ctrl+X clears pending images');
+  if (images.reduce((total, image) => total + imageBytes(image), 0) > MAX_ATTACHMENT_BYTES)
+    throw new Error('attached images exceed the 20 MiB total limit — Ctrl+X clears pending images');
+  return images;
+}