@thegitai/cli 1.0.0-beta.9 → 1.0.0-preview.1

package/dist/src/background-jobs.js

@@ -0,0 +1,410 @@
+import chalk from './colors.js';
+import { spawn } from 'child_process';
+import { buildCommandEnv, commandUsesSudo, sanitizeCommandText, terminateChild, } from './executor.js';
+import { isTuiMode } from './runtime-mode.js';
+import { redactConnectionStringCredentials } from './secret-preview.js';
+const MAX_RUNNING_JOBS = 8;
+const MAX_FINISHED_JOBS = 20;
+const MAX_JOB_BUFFER_CHARS = 200 * 1024;
+export const DEFAULT_STARTUP_WAIT_MS = 5000;
+export const MAX_JOB_WAIT_MS = 30_000;
+const KILL_ESCALATION_MS = 2000;
+const jobs = new Map();
+let jobCounter = 0;
+let activeSessionId = null;
+let updateHook = null;
+let exitCleanupRegistered = false;
+let pendingModelNotifications = [];
+export function setBackgroundJobUpdateHook(hook) {
+    updateHook = hook;
+}
+function normalizeSessionId(sessionId) {
+    return String(sessionId ?? activeSessionId ?? 'default').trim() || 'default';
+}
+function sessionFilter(sessionId) {
+    const value = String(sessionId ?? activeSessionId ?? '').trim();
+    return value || null;
+}
+function belongsToSession(record, sessionId) {
+    const filter = sessionFilter(sessionId);
+    return !filter || record.sessionId === filter;
+}
+export function setBackgroundJobSession(sessionId) {
+    const next = String(sessionId ?? '').trim() || null;
+    if (activeSessionId && activeSessionId !== next) {
+        killAllBackgroundJobs({ sessionId: activeSessionId, remove: true });
+        pendingModelNotifications = pendingModelNotifications.filter((snapshot) => snapshot.sessionId === next);
+    }
+    activeSessionId = next;
+}
+function snapshotOf(record) {
+    return {
+        id: record.id,
+        sessionId: record.sessionId,
+        command: record.command,
+        status: record.status,
+        pid: record.child.pid ?? null,
+        exitCode: record.exitCode,
+        signal: record.signal,
+        startedAt: record.startedAt,
+        endedAt: record.endedAt,
+    };
+}
+function notifyUpdate(record) {
+    if (!belongsToSession(record))
+        return;
+    try {
+        updateHook?.(snapshotOf(record));
+    }
+    catch { }
+}
+function logJobStatus(record) {
+    if (isTuiMode())
+        return;
+    if (record.status === 'running') {
+        console.log(chalk.cyan(`\n  ⚙ Background job ${record.id} started: ${record.command}`));
+        return;
+    }
+    if (record.status === 'killed') {
+        console.log(chalk.dim(`\n  ■ Background job ${record.id} killed.`));
+        return;
+    }
+    if (record.status === 'error') {
+        console.log(chalk.red(`\n  ✖ Background job ${record.id} failed to run.`));
+        return;
+    }
+    const color = record.exitCode === 0 ? chalk.green : chalk.red;
+    console.log(color(`\n  ${record.exitCode === 0 ? '✓' : '✖'} Background job ${record.id} exited with code ${record.exitCode ?? 1}`));
+}
+function appendJobOutput(record, chunk) {
+    if (!chunk)
+        return;
+    if (record.firstOutputLine == null) {
+        record.firstOutputFragment = `${record.firstOutputFragment}${chunk}`.slice(0, 8000);
+        const firstLine = record.firstOutputFragment
+            .split(/\r?\n/)
+            .find((line) => line.trim().length > 0);
+        if (firstLine) {
+            record.firstOutputLine = firstLine;
+        }
+    }
+    record.totalCaptured += chunk.length;
+    record.buffer += chunk;
+    if (record.buffer.length > MAX_JOB_BUFFER_CHARS) {
+        record.buffer = record.buffer.slice(record.buffer.length - MAX_JOB_BUFFER_CHARS);
+    }
+    const waiters = record.outputWaiters;
+    record.outputWaiters = [];
+    for (const waiter of waiters)
+        waiter();
+}
+function settleJob(record, status, exitCode, signal) {
+    if (record.status !== 'running')
+        return;
+    record.status = status;
+    record.exitCode = exitCode;
+    record.signal = signal;
+    record.endedAt = Date.now();
+    const waiters = [...record.exitWaiters, ...record.outputWaiters];
+    record.exitWaiters = [];
+    record.outputWaiters = [];
+    for (const waiter of waiters)
+        waiter();
+    if (jobs.has(record.id) && belongsToSession(record)) {
+        pendingModelNotifications.push(snapshotOf(record));
+    }
+    logJobStatus(record);
+    if (status === 'killed' || record.removeOnSettle) {
+        jobs.delete(record.id);
+    }
+    else {
+        pruneFinishedJobs();
+    }
+    notifyUpdate(record);
+}
+function pruneFinishedJobs() {
+    const finished = [...jobs.values()].filter((record) => record.status !== 'running');
+    if (finished.length <= MAX_FINISHED_JOBS)
+        return;
+    finished.sort((a, b) => (a.endedAt ?? 0) - (b.endedAt ?? 0));
+    for (const record of finished.slice(0, finished.length - MAX_FINISHED_JOBS)) {
+        jobs.delete(record.id);
+    }
+}
+function registerExitCleanup() {
+    if (exitCleanupRegistered)
+        return;
+    exitCleanupRegistered = true;
+    process.on('exit', () => {
+        for (const record of jobs.values()) {
+            if (record.status !== 'running')
+                continue;
+            terminateChild(record.child, 'SIGKILL');
+        }
+    });
+}
+function sanitizeJobText(record, raw) {
+    return redactConnectionStringCredentials(sanitizeCommandText(record.command, raw, record.cwd));
+}
+function readNewOutput(record) {
+    const dropped = record.totalCaptured - record.buffer.length;
+    const droppedUnread = Math.max(dropped - record.readOffset, 0);
+    const start = Math.max(record.readOffset - dropped, 0);
+    const raw = record.buffer.slice(start);
+    record.readOffset = record.totalCaptured;
+    return {
+        newOutput: sanitizeJobText(record, raw),
+        droppedChars: droppedUnread,
+    };
+}
+function waitForJobEvent(record, waitMs, kind) {
+    if (record.status !== 'running' || waitMs <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const waiters = kind === 'exit' ? record.exitWaiters : record.outputWaiters;
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const index = waiters.indexOf(finish);
+            if (index !== -1)
+                waiters.splice(index, 1);
+            resolve();
+        };
+        const timer = setTimeout(finish, Math.min(waitMs, MAX_JOB_WAIT_MS));
+        timer.unref?.();
+        waiters.push(finish);
+    });
+}
+export async function startBackgroundJob(command, cwd, { startupWaitMs, sessionId, } = {}) {
+    if (commandUsesSudo(command)) {
+        return {
+            ok: false,
+            error: 'sudo commands cannot run as background jobs because the password prompt is interactive. Run it in the foreground instead.',
+        };
+    }
+    const running = [...jobs.values()].filter((record) => record.status === 'running' && belongsToSession(record, sessionId));
+    if (running.length >= MAX_RUNNING_JOBS) {
+        return {
+            ok: false,
+            error: `Too many background jobs are already running (${running.length}). Kill one with shell_job_kill first.`,
+        };
+    }
+    registerExitCleanup();
+    const id = `bg_${++jobCounter}`;
+    const child = spawn(command, {
+        cwd,
+        shell: true,
+        detached: process.platform !== 'win32',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: buildCommandEnv(cwd),
+    });
+    child.stdin?.end();
+    const record = {
+        id,
+        sessionId: normalizeSessionId(sessionId),
+        command,
+        cwd,
+        child,
+        status: 'running',
+        exitCode: null,
+        signal: null,
+        startedAt: Date.now(),
+        endedAt: null,
+        buffer: '',
+        totalCaptured: 0,
+        readOffset: 0,
+        firstOutputLine: null,
+        firstOutputFragment: '',
+        killRequested: false,
+        removeOnSettle: false,
+        exitWaiters: [],
+        outputWaiters: [],
+    };
+    jobs.set(id, record);
+    child.stdout?.on('data', (chunk) => {
+        appendJobOutput(record, chunk.toString('utf-8'));
+    });
+    child.stderr?.on('data', (chunk) => {
+        appendJobOutput(record, chunk.toString('utf-8'));
+    });
+    child.on('error', (error) => {
+        appendJobOutput(record, error.message ? `${error.message}\n` : '');
+        terminateChild(child, 'SIGKILL');
+        settleJob(record, 'error', 1, null);
+    });
+    child.on('close', (code, signal) => {
+        settleJob(record, record.killRequested ? 'killed' : 'exited', code ?? (signal ? 1 : 0), signal);
+    });
+    logJobStatus(record);
+    notifyUpdate(record);
+    const waitMs = Math.min(Math.max(startupWaitMs ?? DEFAULT_STARTUP_WAIT_MS, 0), MAX_JOB_WAIT_MS);
+    await waitForJobEvent(record, waitMs, 'exit');
+    const { newOutput, droppedChars } = readNewOutput(record);
+    return {
+        ok: true,
+        snapshot: snapshotOf(record),
+        startupOutput: newOutput,
+        droppedChars,
+    };
+}
+export function getBackgroundJob(id, { sessionId } = {}) {
+    const record = jobs.get(String(id ?? '').trim());
+    return record && belongsToSession(record, sessionId) ? snapshotOf(record) : null;
+}
+export function listBackgroundJobs({ sessionId, } = {}) {
+    return [...jobs.values()]
+        .filter((record) => belongsToSession(record, sessionId))
+        .sort((a, b) => a.startedAt - b.startedAt)
+        .map(snapshotOf);
+}
+export function getJobOutputTail(id, maxLines) {
+    const record = jobs.get(String(id ?? '').trim());
+    if (!record || !belongsToSession(record) || maxLines <= 0)
+        return [];
+    const lines = sanitizeJobText(record, record.buffer)
+        .split('\n')
+        .filter((line) => line.trim().length > 0);
+    return lines.slice(-maxLines);
+}
+export function getJobOutputPreview(id, maxTailLines) {
+    const record = jobs.get(String(id ?? '').trim());
+    if (!record || !belongsToSession(record))
+        return null;
+    const firstLine = record.firstOutputLine
+        ? sanitizeJobText(record, record.firstOutputLine).trim()
+        : '';
+    return {
+        firstLine,
+        tailLines: getJobOutputTail(id, maxTailLines),
+    };
+}
+export function getJobBufferedOutput(id) {
+    const record = jobs.get(String(id ?? '').trim());
+    if (!record || !belongsToSession(record))
+        return null;
+    return {
+        output: sanitizeJobText(record, record.buffer),
+        droppedChars: Math.max(record.totalCaptured - record.buffer.length, 0),
+    };
+}
+export async function readBackgroundJobOutput(id, { waitMs, sessionId } = {}) {
+    const record = jobs.get(String(id ?? '').trim());
+    if (!record || !belongsToSession(record, sessionId)) {
+        return { ok: false, error: unknownJobError(id) };
+    }
+    if (waitMs && waitMs > 0 && record.status === 'running') {
+        const hasUnread = record.totalCaptured > record.readOffset;
+        if (!hasUnread)
+            await waitForJobEvent(record, waitMs, 'output');
+    }
+    const { newOutput, droppedChars } = readNewOutput(record);
+    return { ok: true, snapshot: snapshotOf(record), newOutput, droppedChars };
+}
+export async function killBackgroundJob(id, { waitMs = 5000, sessionId, } = {}) {
+    const record = jobs.get(String(id ?? '').trim());
+    if (!record || !belongsToSession(record, sessionId)) {
+        return { ok: false, error: unknownJobError(id) };
+    }
+    if (record.status !== 'running') {
+        const { newOutput, droppedChars } = readNewOutput(record);
+        const snapshot = snapshotOf(record);
+        if (record.status === 'killed') {
+            jobs.delete(record.id);
+        }
+        return {
+            ok: true,
+            alreadyFinished: true,
+            snapshot,
+            finalOutput: newOutput,
+            droppedChars,
+        };
+    }
+    record.killRequested = true;
+    terminateChild(record.child, 'SIGTERM');
+    const killTimer = setTimeout(() => {
+        if (record.status === 'running') {
+            terminateChild(record.child, 'SIGKILL');
+        }
+    }, KILL_ESCALATION_MS);
+    killTimer.unref?.();
+    await waitForJobEvent(record, Math.max(waitMs, KILL_ESCALATION_MS + 1000), 'exit');
+    clearTimeout(killTimer);
+    const { newOutput, droppedChars } = readNewOutput(record);
+    return {
+        ok: true,
+        snapshot: snapshotOf(record),
+        finalOutput: newOutput,
+        droppedChars,
+    };
+}
+export function killAllBackgroundJobs({ sessionId, remove = false, } = {}) {
+    for (const record of jobs.values()) {
+        if (!belongsToSession(record, sessionId))
+            continue;
+        if (record.status !== 'running')
+            continue;
+        record.killRequested = true;
+        record.removeOnSettle = record.removeOnSettle || remove;
+        terminateChild(record.child, 'SIGTERM');
+        const killTimer = setTimeout(() => {
+            if (record.status === 'running') {
+                terminateChild(record.child, 'SIGKILL');
+            }
+        }, KILL_ESCALATION_MS);
+        killTimer.unref?.();
+    }
+}
+export function hasRunningBackgroundJobs({ sessionId, } = {}) {
+    for (const record of jobs.values()) {
+        if (!belongsToSession(record, sessionId))
+            continue;
+        if (record.status === 'running')
+            return true;
+    }
+    return false;
+}
+function formatRunTime(snapshot) {
+    const ms = (snapshot.endedAt ?? Date.now()) - snapshot.startedAt;
+    const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+    if (totalSeconds < 60)
+        return `${totalSeconds}s`;
+    const minutes = Math.floor(totalSeconds / 60);
+    if (minutes < 60)
+        return `${minutes}m${String(totalSeconds % 60).padStart(2, '0')}s`;
+    return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, '0')}m`;
+}
+export function drainBackgroundJobNotifications({ sessionId } = {}) {
+    if (pendingModelNotifications.length === 0)
+        return null;
+    const filter = sessionFilter(sessionId);
+    const pending = filter
+        ? pendingModelNotifications.filter((snapshot) => snapshot.sessionId === filter)
+        : pendingModelNotifications;
+    pendingModelNotifications = filter
+        ? pendingModelNotifications.filter((snapshot) => snapshot.sessionId !== filter)
+        : [];
+    if (pending.length === 0)
+        return null;
+    const lines = pending.map((snapshot) => {
+        const ran = formatRunTime(snapshot);
+        if (snapshot.status === 'error') {
+            return `Background job ${snapshot.id} (${snapshot.command}) failed to start.`;
+        }
+        if (snapshot.status === 'killed') {
+            return `Background job ${snapshot.id} (${snapshot.command}) was killed after ${ran}.`;
+        }
+        return `Background job ${snapshot.id} (${snapshot.command}) exited with code ${snapshot.exitCode ?? 1} after ${ran}.`;
+    });
+    const hasReadableFinalOutput = pending.some((snapshot) => snapshot.status !== 'killed');
+    return `${lines.join(' ')}${hasReadableFinalOutput ? ' Use shell_job_output to read any final output.' : ''}`;
+}
+function unknownJobError(id) {
+    const known = listBackgroundJobs().map((job) => job.id);
+    const hint = known.length
+        ? ` Known jobs: ${known.join(', ')}.`
+        : ' No background jobs have been started this session.';
+    return `Unknown background job id: ${String(id ?? '').trim() || '(empty)'}.${hint}`;
+}

package/dist/src/cli-args.js

@@ -39,11 +39,6 @@ export function parseArgs(argv) {
             usage = true;
             continue;
         }
-        // An unrecognized dashed token is a mistyped flag, not prompt text. Without
-        // an auth subcommand (whose flags are parsed separately) it would otherwise
-        // be swept into the prompt and silently start a billable session. Flag the
-        // first one so the caller can fail fast instead. Quoted prompts are a single
-        // argv entry with spaces, so they never look like a bare option here.
         if (command === null && unknownOption === null && /^-/.test(arg)) {
             unknownOption = arg;
             continue;

package/dist/src/client-environment.js

@@ -1,6 +1,7 @@
 import { accessSync, constants, readFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { ensureSessionScratchDir } from './scratch-dir.js';
 const PACKAGE_MANAGER_CANDIDATES = [
     'apt',
     'apt-get',
@@ -123,5 +124,6 @@ export function collectClientEnvironment(options = {}) {
         shell: detectShell(platform, env),
         ...linuxDistro,
         packageManagers: detectPackageManagers(env, platform, executableExists),
+        scratchDir: options.scratchDir ?? ensureSessionScratchDir(),
     };
 }

package/dist/src/colors.js

@@ -0,0 +1,50 @@
+const STYLE_NAMES = ['bold', 'dim', 'red', 'green', 'yellow', 'cyan'];
+const OPEN = {
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    cyan: '\x1b[36m',
+};
+const CLOSE = {
+    bold: '\x1b[22m',
+    dim: '\x1b[22m',
+    red: '\x1b[39m',
+    green: '\x1b[39m',
+    yellow: '\x1b[39m',
+    cyan: '\x1b[39m',
+};
+function colorEnabled() {
+    const force = process.env.FORCE_COLOR;
+    if (force !== undefined)
+        return force !== '0' && force !== 'false';
+    if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== '') {
+        return false;
+    }
+    return Boolean(process.stdout.isTTY);
+}
+function applyStyle(name, text) {
+    const open = OPEN[name];
+    const close = CLOSE[name];
+    const body = text.includes(close) ? text.split(close).join(close + open) : text;
+    return open + body + close;
+}
+function createStyler(styles) {
+    const fn = ((text) => {
+        const value = String(text);
+        if (!colorEnabled() || styles.length === 0)
+            return value;
+        return styles.reduceRight((acc, name) => applyStyle(name, acc), value);
+    });
+    for (const name of STYLE_NAMES) {
+        Object.defineProperty(fn, name, {
+            configurable: true,
+            enumerable: false,
+            get: () => createStyler([...styles, name]),
+        });
+    }
+    return fn;
+}
+const colors = createStyler([]);
+export default colors;

package/dist/src/core/clipboard.js

@@ -1,4 +1,6 @@
 import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
 const MAX_IMAGE_SIZE_BYTES = 10 * 1024 * 1024;
 const MIME_BY_EXT = {
     '.png': 'image/png',
@@ -262,3 +264,20 @@ export function writeClipboardText(text, platform = process.platform) {
     }
     throw new ClipboardError(`Clipboard text copy is not supported on ${platform}.`, 'NO_TOOL');
 }
+export function loadImageFromFile(filePath) {
+    const resolved = path.resolve(filePath);
+    if (!existsSync(resolved)) {
+        throw new ClipboardError(`Image file not found: ${resolved}`, 'READ_FAILED');
+    }
+    const stat = statSync(resolved);
+    if (stat.size > MAX_IMAGE_SIZE_BYTES) {
+        throw new ClipboardError(`Image file exceeds 10MB limit (${(stat.size / 1024 / 1024).toFixed(1)}MB): ${resolved}`, 'READ_FAILED');
+    }
+    const ext = path.extname(resolved).toLowerCase();
+    const mimeType = MIME_BY_EXT[ext];
+    if (!mimeType) {
+        throw new ClipboardError(`Unsupported image format "${ext}". Supported: PNG, JPEG, GIF, WebP.`, 'READ_FAILED');
+    }
+    const buf = readFileSync(resolved);
+    return { base64Data: buf.toString('base64'), mimeType };
+}

package/dist/src/core/image-path-extractor.js

@@ -0,0 +1,144 @@
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadImageFromFile } from './clipboard.js';
+const EXT = '(?:png|jpe?g|gif|webp)';
+const BARE_CHAR = "[^\\s\"'<>,:;!?()\\[\\]{}]";
+const BARE_PATH = `(?:[A-Za-z]:[\\\\/])?(?:\\\\ |${BARE_CHAR})+\\.${EXT}`;
+const IMAGE_PATH_PATTERN = new RegExp(`"([^"]*\\.${EXT})"` +
+    `|'([^']*\\.${EXT})'` +
+    `|file://(\\S*\\.${EXT})` +
+    `|(${BARE_PATH})`, 'gi');
+const EXTENSION_TOKEN = new RegExp(`^(?:[A-Za-z]:[\\\\/])?(?:\\\\ |${BARE_CHAR})+$`);
+const MAX_EXTENSION_TOKENS = 8;
+function isFile(p) {
+    try {
+        return statSync(p, { throwIfNoEntry: false })?.isFile() ?? false;
+    }
+    catch {
+        return false;
+    }
+}
+function extendBareMatchAcrossSpaces(input, matchStart, raw, cwd) {
+    const baseInner = raw.replace(/\\ /g, ' ');
+    const baseExists = isFile(path.isAbsolute(baseInner) ? baseInner : path.resolve(cwd, baseInner));
+    let best = null;
+    let candidate = raw;
+    let start = matchStart;
+    let addedSeparator = false;
+    for (let hops = 0; hops < MAX_EXTENSION_TOKENS; hops++) {
+        if (start < 2 || input[start - 1] !== ' ' || /\s/.test(input[start - 2]))
+            break;
+        let i = start - 2;
+        while (i >= 0 && !/\s/.test(input[i]))
+            i--;
+        const tokenStart = i + 1;
+        const token = input.slice(tokenStart, start - 1);
+        if (!EXTENSION_TOKEN.test(token))
+            break;
+        candidate = `${token} ${candidate}`;
+        start = tokenStart;
+        addedSeparator = addedSeparator || /[\\/]/.test(token);
+        if (baseExists && !addedSeparator)
+            continue;
+        const inner = candidate.replace(/\\ /g, ' ');
+        const resolved = path.isAbsolute(inner) ? inner : path.resolve(cwd, inner);
+        if (isFile(resolved))
+            best = candidate;
+    }
+    return best ?? raw;
+}
+function detectImagePaths(input, cwd) {
+    const regex = new RegExp(IMAGE_PATH_PATTERN.source, IMAGE_PATH_PATTERN.flags);
+    const detected = [];
+    let match;
+    while ((match = regex.exec(input)) !== null) {
+        let raw = match[0];
+        if (match[4] != null && raw.includes('://'))
+            continue;
+        let inner;
+        if (match[1] != null || match[2] != null) {
+            const quoted = (match[1] ?? match[2]);
+            if (/^file:\/\//i.test(quoted)) {
+                try {
+                    inner = fileURLToPath(quoted);
+                }
+                catch {
+                    continue;
+                }
+            }
+            else {
+                inner = quoted;
+            }
+        }
+        else if (match[3] != null) {
+            try {
+                inner = fileURLToPath(raw);
+            }
+            catch {
+                try {
+                    inner = decodeURIComponent(match[3]);
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+        else {
+            raw = extendBareMatchAcrossSpaces(input, match.index, raw, cwd);
+            inner = raw.replace(/\\ /g, ' ');
+        }
+        const resolvedPath = path.isAbsolute(inner) ? inner : path.resolve(cwd, inner);
+        const start = match.index - (raw.length - match[0].length);
+        while (detected.length > 0) {
+            const prev = detected[detected.length - 1];
+            if (prev.start + prev.raw.length <= start)
+                break;
+            detected.pop();
+        }
+        detected.push({ resolvedPath, raw, start });
+    }
+    const rawsByPath = new Map();
+    for (const { resolvedPath, raw } of detected) {
+        const existing = rawsByPath.get(resolvedPath);
+        if (existing) {
+            existing.push(raw);
+        }
+        else {
+            rawsByPath.set(resolvedPath, [raw]);
+        }
+    }
+    return rawsByPath;
+}
+export function autoAttachImages(input, cwd, existing = []) {
+    const max = 2;
+    const rawsByPath = detectImagePaths(input, cwd);
+    let sanitizedInput = input;
+    const attachments = [];
+    const errors = [];
+    const maxExistingIndex = existing.reduce((highest, a) => Math.max(highest, a.index ?? 0), 0);
+    for (const [resolvedPath, rawForms] of rawsByPath) {
+        if (existing.length + attachments.length >= max)
+            break;
+        if (!existsSync(resolvedPath))
+            continue;
+        try {
+            const loaded = loadImageFromFile(resolvedPath);
+            const idx = maxExistingIndex + attachments.length + 1;
+            attachments.push({
+                index: idx,
+                mimeType: loaded.mimeType,
+                base64Data: loaded.base64Data,
+                source: 'file',
+                filePath: resolvedPath,
+            });
+            for (const raw of rawForms) {
+                sanitizedInput = sanitizedInput.replace(raw, `[Image #${idx}]`);
+            }
+        }
+        catch (err) {
+            errors.push(err.message);
+        }
+    }
+    return { sanitizedInput, attachments, errors };
+}