ethagent 2.3.0 → 2.4.0

package/README.md

@@ -112,6 +112,17 @@ ethagent works with OpenAI, Anthropic, Gemini, and local GGUF models served thro
 - The featured local model is [Qwen3.5-9B-Uncensored](https://huggingface.co/HauhauCS/Qwen3.5-9B-Uncensored-HauhauCS-Aggressive); other Hugging Face GGUF models work by repo ID or direct URL.
 - Cloud API keys live in the OS keyring when one is available, with an encrypted local file under `~/.ethagent` as fallback.
 
+### Image Input
+
+Press `Alt+V` to paste an image from the clipboard. A marker like `[Image #1]` appears in the prompt; delete it to drop the attachment.
+
+Vision support is available on:
+
+- **OpenAI** (Chat Completions and Responses API): `gpt-4o`, `gpt-4.1`, `gpt-4-turbo`, `gpt-4-vision`, `gpt-5`, `o1`, `o3`, `o4`, `chatgpt-4`.
+- **Anthropic**: `claude-3`, `claude-sonnet-4`, `claude-opus-4`, `claude-haiku-4`.
+- **Gemini**: `gemini-1.5`, `gemini-2.0`, `gemini-2.5`.
+- **Local llama.cpp**: vision works when both the main GGUF and a `mmproj-*.gguf` projector are loaded. The picker recommends the bundle during install; if you skipped, open `Alt+P` and any installed model with a vision encoder available shows an `Add Vision Encoder` row directly beneath it.
+
 ## Tools and Sessions
 
 - File ops, shell, clipboard, and MCP tools all run through the same permission layer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ethagent",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "A privacy-first AI agent with a portable Ethereum identity",
   "type": "module",
   "main": "bin/ethagent.js",

package/src/app/FirstRun.tsx

@@ -435,6 +435,7 @@ function configFromModelPickerSelection(selection: ModelPickerSelection, base: E
       provider: 'llamacpp',
       model: selection.model,
       baseUrl: defaultBaseUrlFor('llamacpp'),
+      localMmprojPath: selection.mmprojPath,
     }
   }
   return {
@@ -442,6 +443,7 @@ function configFromModelPickerSelection(selection: ModelPickerSelection, base: E
     provider: selection.provider,
     model: selection.model,
     baseUrl: undefined,
+    localMmprojPath: undefined,
   }
 }
 

package/src/chat/ChatBottomPane.tsx

@@ -13,6 +13,7 @@ import { ChatInput } from './input/ChatInput.js'
 import { IdentityHub, type IdentityHubInitialAction, type IdentityHubResult } from '../identity/hub/IdentityHub.js'
 import type { CopyResult } from '../utils/clipboard.js'
 import { getSlashSuggestions } from './commands.js'
+import { modelSupportsImages } from '../utils/images.js'
 import { Box, Text } from 'ink'
 import { theme } from '../ui/theme.js'
 import { Spinner } from '../ui/Spinner.js'
@@ -270,6 +271,14 @@ export function ChatBottomPane({
         cwd={cwd}
         seedText={pendingInputDraft}
         onSeedConsumed={onInputDraftConsumed}
+        onImagePaste={() => {
+          if (!modelSupportsImages(config.provider, config.model, { mmprojPath: config.localMmprojPath })) {
+            const hint = config.provider === 'llamacpp'
+              ? ' · run "Add Vision Encoder" in alt+p to enable image input on this model'
+              : ' · switch via alt+p'
+            pushNote(`current model "${config.model}" does not accept image input${hint}`, 'error')
+          }
+        }}
       />
       <Box marginLeft={2} marginTop={0} flexDirection="column">
         <Text>

package/src/chat/ChatScreen.tsx

@@ -1197,7 +1197,7 @@ export const ChatScreen: React.FC<ChatScreenProps> = ({ config: initialConfig, o
       clearTranscript()
       overlayRef.current = 'none'
       setOverlay('none')
-      pushNote('Cleared saved chat logs and resume context from this machine.', 'dim')
+      pushNote('Cleared saved sessions and resume context from this machine.', 'dim')
     },
     [clearTranscript, pushNote],
   )
@@ -1517,17 +1517,23 @@ export const ChatScreen: React.FC<ChatScreenProps> = ({ config: initialConfig, o
 
   const exitHint = exitState.pending ? 'ctrl+c again to quit' : null
   const runtimeModeLabel = sessionModeLabel(mode)
+  const runtimeModeColor =
+    mode === 'plan'
+      ? theme.modePlan
+      : mode === 'accept-edits'
+        ? theme.modeAcceptEdits
+        : theme.text
   const footerRight = (
     <Box flexDirection="row">
       {exitHint ? (
         <>
-          <Text color={theme.text}>{exitHint}</Text>
+          <Text color={theme.accentPeriwinkle}>{exitHint}</Text>
           <Text color={theme.dim}> · </Text>
         </>
       ) : null}
       {runtimeModeLabel ? (
         <>
-          <Text bold>{runtimeModeLabel}</Text>
+          <Text color={runtimeModeColor} bold>{runtimeModeLabel}</Text>
           <Text color={theme.dim}> (</Text>
           <Text color={theme.accentPeriwinkle}>shift+tab to cycle</Text>
           <Text color={theme.dim}>) · </Text>
@@ -1613,7 +1619,7 @@ export const ChatScreen: React.FC<ChatScreenProps> = ({ config: initialConfig, o
 }
 
 export function chatFooterShortcutText(canScrollTranscript: boolean): string {
-  return `${canScrollTranscript ? 'pgup/pgdn scroll · ' : ''}alt+p model · alt+i identity`
+  return 'alt+p model · alt+i identity'
 }
 
 function formatContextLabel(usage: ContextUsage): string {

package/src/chat/chatSessionState.ts

@@ -39,6 +39,7 @@ export function resolveModelSelection(
       selection.model === currentConfig.model
       && currentConfig.provider === 'llamacpp'
       && currentConfig.baseUrl === baseUrl
+      && currentConfig.localMmprojPath === selection.mmprojPath
     ) {
       return { kind: 'noop' }
     }
@@ -49,8 +50,9 @@ export function resolveModelSelection(
         provider: 'llamacpp',
         model: selection.model,
         baseUrl,
+        localMmprojPath: selection.mmprojPath,
       },
-      notice: `Local Hugging Face model ready. Now using ${formatModelDisplayName('llamacpp', selection.model, { maxLength: 64 })}.`,
+      notice: `Local Hugging Face model ready. Now using ${formatModelDisplayName('llamacpp', selection.model, { maxLength: 64 })}${selection.mmprojPath ? ' with vision encoder' : ''}.`,
       tone: 'info',
     }
   }
@@ -65,6 +67,7 @@ export function resolveModelSelection(
     provider: nextProvider,
     model: selection.model,
     baseUrl: nextBaseUrl,
+    localMmprojPath: undefined,
   }
 
   return {

package/src/chat/chatTurnOrchestrator.ts

@@ -15,6 +15,7 @@ import {
   createTurnCheckpoint,
   type TurnCheckpoint,
 } from './chatScreenUtils.js'
+import { collapseImagePathsToRefs, userTextToContentBlocks } from '../utils/images.js'
 
 type MutableRef<T> = { current: T }
 
@@ -101,10 +102,13 @@ export async function runStreamingTurn(
   const activeCheckpoint = createTurnCheckpoint(sessionId, userText)
   setActiveCheckpoint(activeCheckpoint)
 
-  updateRows(prev => [...prev, { role: 'user', id: nextRowId(), content: userText }])
+  const userContent = userTextToContentBlocks(userText)
+  const displayText = collapseImagePathsToRefs(userText)
+  updateRows(prev => [...prev, { role: 'user', id: nextRowId(), content: displayText }])
   await persistTurnMessage({
     role: 'user',
-    content: userText,
+    content: displayText,
+    providerContent: typeof userContent === 'string' ? undefined : userContent,
     createdAt: nowIso(),
     turnId: activeCheckpoint.turnId,
   })

package/src/chat/input/ChatInput.tsx

@@ -33,6 +33,12 @@ import {
   shouldCollapsePastedText,
   type PastedTextRef,
 } from './chatPaste.js'
+import {
+  expandImageRefs,
+  formatImageRefMarker,
+  pruneImageRefs,
+  type ImageRef,
+} from './imageRefs.js'
 
 type PromptInputProps = {
   onSubmit: (value: string) => void
@@ -48,6 +54,7 @@ type PromptInputProps = {
   cwd?: string
   seedText?: string | null
   onSeedConsumed?: () => void
+  onImagePaste?: (path: string) => void
 }
 
 const MAX_LENGTH = 32_768
@@ -76,6 +83,7 @@ export const ChatInput: React.FC<PromptInputProps> = ({
   cwd,
   seedText,
   onSeedConsumed,
+  onImagePaste,
 }) => {
   const { stdout } = useStdout()
   const [buffer, setBuffer] = useState<ChatBuffer>(emptyBuffer)
@@ -100,6 +108,8 @@ export const ChatInput: React.FC<PromptInputProps> = ({
   const pasteTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
   const pastedTextRefsRef = useRef<Map<number, PastedTextRef>>(new Map())
   const nextPastedTextRefIdRef = useRef(1)
+  const imageRefsRef = useRef<Map<number, ImageRef>>(new Map())
+  const nextImageRefIdRef = useRef(1)
 
   useEffect(() => { bufferRef.current = buffer }, [buffer])
   useEffect(() => { historyIndexRef.current = historyIndex }, [historyIndex])
@@ -107,6 +117,11 @@ export const ChatInput: React.FC<PromptInputProps> = ({
   useEffect(() => { historyPreviewActiveRef.current = historyPreviewActive }, [historyPreviewActive])
   useEffect(() => { preferredColumnRef.current = preferredColumn }, [preferredColumn])
 
+  useEffect(() => {
+    pruneImageRefs(imageRefsRef.current, value)
+    if (imageRefsRef.current.size === 0) nextImageRefIdRef.current = 1
+  }, [value])
+
   useEffect(() => {
     const handleResize = () => {
       setColumns(stdout.columns ?? process.stdout.columns ?? 80)
@@ -217,6 +232,8 @@ export const ChatInput: React.FC<PromptInputProps> = ({
     })
     pastedTextRefsRef.current.clear()
     nextPastedTextRefIdRef.current = 1
+    imageRefsRef.current.clear()
+    nextImageRefIdRef.current = 1
   }, [applyBuffer, applyHistoryState])
 
   const handlePaste = useCallback((text: string) => {
@@ -257,7 +274,8 @@ export const ChatInput: React.FC<PromptInputProps> = ({
   const submit = useCallback(() => {
     const trimmed = value.trim()
     if (!trimmed) return
-    onSubmit(expandPastedTextRefs(trimmed, pastedTextRefsRef.current))
+    const withText = expandPastedTextRefs(trimmed, pastedTextRefsRef.current)
+    onSubmit(expandImageRefs(withText, imageRefsRef.current))
     resetBuffer()
   }, [value, onSubmit, resetBuffer])
 
@@ -388,7 +406,12 @@ export const ChatInput: React.FC<PromptInputProps> = ({
     if (key.meta && inputText === 'v') {
       void (async () => {
         const image = await readClipboardImage()
-        if (image.ok) insertText(`[image: ${image.path}]`)
+        if (image.ok) {
+          const id = nextImageRefIdRef.current++
+          imageRefsRef.current.set(id, { path: image.path })
+          insertText(formatImageRefMarker(id))
+          onImagePaste?.(image.path)
+        }
       })()
       return
     }

package/src/chat/input/imageRefs.ts

@@ -0,0 +1,30 @@
+export type ImageRef = { path: string; mimeType?: string }
+
+const IMAGE_REF_MARKER_RE = /\[Image\s+#(\d+)\]/g
+
+export function expandImageRefs(text: string, refs: Map<number, ImageRef>): string {
+  return text.replace(IMAGE_REF_MARKER_RE, (full, raw: string) => {
+    const ref = refs.get(Number(raw))
+    return ref ? `[image: ${ref.path}]` : full
+  })
+}
+
+export function referencedImageIds(text: string): Set<number> {
+  const out = new Set<number>()
+  for (const match of text.matchAll(IMAGE_REF_MARKER_RE)) {
+    const id = Number(match[1])
+    if (Number.isFinite(id)) out.add(id)
+  }
+  return out
+}
+
+export function pruneImageRefs(refs: Map<number, ImageRef>, text: string): void {
+  const referenced = referencedImageIds(text)
+  for (const id of [...refs.keys()]) {
+    if (!referenced.has(id)) refs.delete(id)
+  }
+}
+
+export function formatImageRefMarker(id: number): string {
+  return `[Image #${id}]`
+}

package/src/chat/views/ResumeView.tsx

@@ -48,8 +48,8 @@ export const ResumeView: React.FC<ResumeViewProps> = ({ currentSessionId, onResu
 
   if (state.kind === 'loading') {
     return (
-      <Surface title="Resume Session" subtitle="Loading projects and directories...">
-        <Spinner label="loading sessions..." />
+      <Surface title="Resume Session" subtitle="Recent chats and directories." footer="esc closes">
+        <Spinner label="loading..." />
       </Surface>
     )
   }
@@ -65,7 +65,7 @@ export const ResumeView: React.FC<ResumeViewProps> = ({ currentSessionId, onResu
   if (state.kind === 'confirmClear') {
     return (
       <Surface
-        title="Clear All Chat Logs?"
+        title="Clear All Saved Sessions?"
         subtitle={`${state.sessions.length} saved session${state.sessions.length === 1 ? '' : 's'} will be removed.`}
         tone="error"
         footer="enter selects · esc returns to resume"
@@ -76,9 +76,10 @@ export const ResumeView: React.FC<ResumeViewProps> = ({ currentSessionId, onResu
           {state.error ? <Text color={theme.accentError}>{state.error}</Text> : null}
         </Box>
         <Select<'back' | 'clear'>
+          hintLayout="inline"
           options={[
-            { value: 'back', label: 'back to sessions' },
-            { value: 'clear', label: 'clear all chat logs', hint: 'cannot be undone' },
+            { value: 'back', label: 'Back to Sessions' },
+            { value: 'clear', label: 'Clear All Saved Sessions', hint: 'Cannot be undone' },
           ]}
           onSubmit={choice => {
             if (choice === 'back') {
@@ -155,11 +156,18 @@ export function buildResumeOptions(
     label: '',
     disabled: true,
   }
+  const manageHeader: SelectOption<string> = {
+    value: 'separator:manage',
+    label: 'Manage',
+    role: 'section',
+    bold: true,
+    disabled: true,
+  }
 
   const clearOption: SelectOption<string> = {
     value: CLEAR_ALL_SESSIONS_VALUE,
-    label: 'Clear All Chat Logs',
-    hint: 'removes saved chats and resume context',
+    label: 'Clear All Saved Sessions',
+    hint: 'Removes saved chats and resume context',
     role: 'utility',
   }
 
@@ -202,6 +210,7 @@ export function buildResumeOptions(
   }
 
   options.push(manageSpacer)
+  options.push(manageHeader)
   options.push(clearOption)
 
   return options

package/src/models/ModelPicker.tsx

@@ -13,6 +13,7 @@ import {
   installLlamaCppRunner,
   setLlamaCppServerPath,
   startLlamaCppServer,
+  stopLlamaCppServer,
   type LlamaCppInstallProgress,
   type LlamaCppInstallResult,
   type LlamaCppStartResult,
@@ -32,6 +33,8 @@ import { defaultModelFor, type EthagentConfig, type ProviderId } from '../storag
 import { clearModelCatalogCache, discoverProviderModels, isOpenAIOAuthAllowedModel, OPENAI_OAUTH_DEFAULT_MODEL, type ModelCatalogResult } from './catalog.js'
 import { contextWindowInfo } from '../runtime/compaction.js'
 import {
+  addMmprojToInstalledModel,
+  backfillMmprojForModels,
   createHfDownloadPlan,
   downloadHfModel,
   fetchHuggingFaceRepoInfo,
@@ -68,7 +71,7 @@ import { formatLocalHfModelDisplayName, formatModelDisplayName } from './modelDi
 import { fetchUncensoredGgufCatalog, type UncensoredCatalogEntry } from './uncensoredCatalog.js'
 
 export type ModelPickerSelection =
-  | { kind: 'llamacpp'; model: string }
+  | { kind: 'llamacpp'; model: string; mmprojPath?: string }
   | { kind: 'cloud'; provider: CloudProviderId; model: string; keyJustSet: boolean }
 
 type ModelPickerProps = {
@@ -113,6 +116,9 @@ type State =
   | { kind: 'localRunnerPathEntry'; data: LoadedData; model: LocalHfModel; submitting: boolean; error?: string }
   | { kind: 'localRunnerStarting'; data: LoadedData; model: LocalHfModel; startedAt: number }
   | { kind: 'localRunnerStartFail'; data: LoadedData; model: LocalHfModel; result: Extract<LlamaCppStartResult, { ok: false }> }
+  | { kind: 'mmprojOffer'; data: LoadedData; model: LocalHfModel }
+  | { kind: 'mmprojDownloading'; data: LoadedData; model: LocalHfModel; progress: HfDownloadProgress }
+  | { kind: 'mmprojError'; data: LoadedData; model: LocalHfModel; message: string }
 
 export const ModelPicker: React.FC<ModelPickerProps> = ({
   currentConfig,
@@ -244,6 +250,7 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
     const canDownload = plan.review.risk !== 'high' && plan.review.runtime === 'llama.cpp runnable'
     const fit = state.data.machineSpec ? estimateGgufMachineFit(plan.sizeBytes, state.data.machineSpec) : null
     const recommended = state.data.machineSpec ? recommendGgufFile(plan.repo, ggufFiles(plan.repo), state.data.machineSpec) : null
+    const mmproj = plan.mmprojCandidate
     return (
       <Surface
         title="Review Model Link"
@@ -260,15 +267,22 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
           <Text color={riskColor(plan.review.risk)}>safety: {safetyLabel(plan.review.risk)} · source: {credibilityLabel(plan.review.credibility)}</Text>
           <Text color={theme.dim}>signals: {formatSignals(plan.repo.downloads, plan.repo.likes)}</Text>
           <Text color={theme.dim}>notes: {friendlyReasons(plan.review.reasons).join('; ')}</Text>
+          {mmproj ? (
+            <Text color={theme.dim}>vision encoder available: {friendlyFileName(mmproj.filename)} (+{formatBytes(mmproj.sizeBytes)})</Text>
+          ) : null}
         </Box>
-        <Select<'download' | 'pick' | 'cancel'>
+        <Select<'download' | 'downloadWithMmproj' | 'pick' | 'cancel'>
           options={[
-            { value: 'download', label: 'Download This Model', disabled: !canDownload },
+            ...(mmproj ? [{ value: 'downloadWithMmproj' as const, label: `Download Model + Vision Encoder (+${formatBytes(mmproj.sizeBytes)}) · recommended`, disabled: !canDownload }] : []),
+            { value: 'download', label: mmproj ? 'Download Without Vision Encoder' : 'Download This Model', disabled: !canDownload },
             { value: 'pick', label: 'Pick Another File' },
             { value: 'cancel', label: 'Cancel' },
           ]}
           onSubmit={choice => {
             if (choice === 'download') void startHfDownload(state, setState, hfAbortRef, onPick)
+            else if (choice === 'downloadWithMmproj') {
+              void startHfDownload({ ...state, plan: { ...plan, includeMmproj: true } }, setState, hfAbortRef, onPick)
+            }
             else if (choice === 'pick') void inspectHfInput({ kind: 'hfInput', data: state.data }, plan.repoId, setState)
             else setState({ kind: 'list', data: state.data })
           }}
@@ -291,6 +305,68 @@ export const ModelPicker: React.FC<ModelPickerProps> = ({
     )
   }
 
+  if (state.kind === 'mmprojOffer') {
+    const sizeLabel = state.model.mmprojSizeBytes ? `+${formatBytes(state.model.mmprojSizeBytes)}` : 'additional download'
+    return (
+      <Surface
+        title="Add Image Support?"
+        subtitle={`${state.model.displayName} has a vision encoder available in its Hugging Face repo.`}
+        footer="enter select · esc back"
+      >
+        <Box flexDirection="column" marginBottom={1}>
+          <Text color={theme.dim}>Loading the vision encoder lets this model accept pasted images.</Text>
+          <Text color={theme.dim}>Without it, image paste is declined at submit time.</Text>
+        </Box>
+        <Select<'add' | 'skip' | 'cancel'>
+          options={[
+            { value: 'add', label: `Add Vision Encoder (${sizeLabel}) And Use` },
+            { value: 'skip', label: 'Use Without Image Support' },
+            { value: 'cancel', label: 'Cancel' },
+          ]}
+          onSubmit={choice => {
+            if (choice === 'add') void downloadMmprojAndContinue(state, setState, onPick)
+            else if (choice === 'skip') void startAndPickHfModel({ ...state.model, mmprojAvailable: false }, state, setState, onPick)
+            else setState({ kind: 'list', data: state.data })
+          }}
+          onCancel={() => setState({ kind: 'list', data: state.data })}
+        />
+      </Surface>
+    )
+  }
+
+  if (state.kind === 'mmprojDownloading') {
+    const total = state.progress.total ?? state.model.mmprojSizeBytes ?? 0
+    const completed = state.progress.completed ?? 0
+    const progress = total > 0 ? completed / total : 0
+    const suffix = total > 0 ? `${formatBytes(completed)} / ${formatBytes(total)}` : formatBytes(completed)
+    return (
+      <Surface title="Downloading Vision Encoder" subtitle={state.model.displayName}>
+        <Text color={theme.dim}>{state.progress.status}</Text>
+        <ProgressBar progress={progress} suffix={suffix} />
+      </Surface>
+    )
+  }
+
+  if (state.kind === 'mmprojError') {
+    return (
+      <Surface title="Vision Encoder Download Failed" subtitle={state.message} tone="error" footer="enter select · esc back">
+        <Select<'retry' | 'skip' | 'back'>
+          options={[
+            { value: 'retry', label: 'Retry Download' },
+            { value: 'skip', label: 'Use Without Image Support' },
+            { value: 'back', label: 'Back To Picker' },
+          ]}
+          onSubmit={choice => {
+            if (choice === 'retry') setState({ kind: 'mmprojOffer', data: state.data, model: state.model })
+            else if (choice === 'skip') void startAndPickHfModel({ ...state.model, mmprojAvailable: false }, state, setState, onPick)
+            else setState({ kind: 'list', data: state.data })
+          }}
+          onCancel={() => setState({ kind: 'list', data: state.data })}
+        />
+      </Surface>
+    )
+  }
+
   if (state.kind === 'hfDone') {
     return (
       <Surface
@@ -834,6 +910,18 @@ function handleSubmit(
     })()
     return
   }
+  if (value.startsWith('hfmmproj:') && state.kind === 'list') {
+    const id = value.slice('hfmmproj:'.length)
+    void (async () => {
+      const local = await findLocalHfModel(id)
+      if (!local) {
+        setState({ kind: 'hfError', data: state.data, message: 'local model metadata was not found' })
+        return
+      }
+      setState({ kind: 'mmprojOffer', data: state.data, model: local })
+    })()
+    return
+  }
   if (value.startsWith('uc:') && state.kind === 'localCatalog') {
     const entry = state.catalog.find(item => catalogOptionValue(item.repo.repoId, item.file.filename) === value)
     if (entry) void reviewCatalogModel(state, entry, setState)
@@ -1250,6 +1338,8 @@ function localRunnerStartFailureSubtitle(result: Extract<LlamaCppStartResult, {
       return result.message
     case 'runner-not-installed':
       return 'this machine still needs a local runner'
+    case 'untracked-server':
+      return result.message
   }
 }
 
@@ -1445,6 +1535,39 @@ async function uninstallLocalModel(
   }
 }
 
+async function downloadMmprojAndContinue(
+  state: Extract<State, { kind: 'mmprojOffer' }>,
+  setState: (s: State) => void,
+  onPick: (sel: ModelPickerSelection) => void,
+): Promise<void> {
+  setState({ kind: 'mmprojDownloading', data: state.data, model: state.model, progress: { status: 'starting' } })
+  try {
+    for await (const progress of addMmprojToInstalledModel(state.model.id)) {
+      setState({ kind: 'mmprojDownloading', data: state.data, model: state.model, progress })
+    }
+  } catch (err: unknown) {
+    setState({ kind: 'mmprojError', data: state.data, model: state.model, message: (err as Error).message })
+    return
+  }
+  const updated = await findLocalHfModel(state.model.id)
+  if (!updated || !updated.mmprojPath) {
+    setState({ kind: 'mmprojError', data: state.data, model: state.model, message: 'projector downloaded but path was not persisted' })
+    return
+  }
+  const stopResult = await stopLlamaCppServer().catch(() => null)
+  if (stopResult && stopResult.ok && stopResult.reason === 'untracked-server') {
+    setState({
+      kind: 'mmprojError',
+      data: state.data,
+      model: updated,
+      message: 'Vision encoder downloaded, but a llama-server is already running and ethagent did not launch it. Quit ethagent, stop the external llama-server (taskkill /F /IM llama-server.exe on Windows, pkill llama-server on macOS or Linux), then reopen ethagent to load the projector.',
+    })
+    return
+  }
+  const data = { ...state.data, hfModels: await loadHfPickerModels() }
+  await startAndPickHfModel(updated, { kind: 'mmprojOffer', data, model: updated }, setState, onPick)
+}
+
 async function refreshLocalModelData(data: LoadedData): Promise<LoadedData> {
   const hfModels = await loadHfPickerModels()
   return {
@@ -1455,7 +1578,7 @@ async function refreshLocalModelData(data: LoadedData): Promise<LoadedData> {
 
 async function startAndPickHfModel(
   model: LocalHfModel,
-  state: Extract<State, { kind: 'list' | 'localCatalog' | 'hfDone' }>,
+  state: Extract<State, { kind: 'list' | 'localCatalog' | 'hfDone' | 'mmprojOffer' | 'mmprojError' }>,
   setState: (s: State) => void,
   onPick: (sel: ModelPickerSelection) => void,
 ): Promise<void> {
@@ -1463,10 +1586,15 @@ async function startAndPickHfModel(
     setState({ kind: 'hfError', data: state.data, message: 'blocked high-risk model; choose a model from a more credible source' })
     return
   }
+  if (model.mmprojAvailable && !model.mmprojPath && state.kind !== 'mmprojOffer' && state.kind !== 'mmprojError') {
+    setState({ kind: 'mmprojOffer', data: state.data, model })
+    return
+  }
   setState({ kind: 'localRunnerStarting', data: state.data, model, startedAt: Date.now() })
   const result = await startLlamaCppServer({
     modelPath: model.localPath,
     modelAlias: model.id,
+    mmprojPath: model.mmprojPath,
   })
   const llamaCpp = await probeLlamaCpp()
   const data = { ...state.data, llamaCpp }
@@ -1478,7 +1606,7 @@ async function startAndPickHfModel(
     setState({ kind: 'localRunnerStartFail', data, model, result })
     return
   }
-  onPick({ kind: 'llamacpp', model: model.id })
+  onPick({ kind: 'llamacpp', model: model.id, mmprojPath: model.mmprojPath })
 }
 
 async function installRunnerAndStart(
@@ -1576,7 +1704,8 @@ function formatContextWindow(tokens: number): string {
 
 async function loadHfPickerModels(): Promise<ModelPickerOptionsData['hfModels']> {
   const installed = await loadLocalHfModels()
-  return installed.map(model => ({
+  const backfilled = await backfillMmprojForModels(installed)
+  return backfilled.map(model => ({
     id: model.id,
     displayName: model.displayName,
     sizeBytes: model.sizeBytes,
@@ -1584,6 +1713,9 @@ async function loadHfPickerModels(): Promise<ModelPickerOptionsData['hfModels']>
     risk: model.risk,
     task: model.task,
     status: model.status,
+    mmprojPath: model.mmprojPath,
+    mmprojAvailable: model.mmprojAvailable,
+    mmprojSizeBytes: model.mmprojSizeBytes,
   }))
 }