@bitseek/hermes-webui 0.1.0-beta.0 → 0.1.0-beta.1

package/vendor/agent-frontend-shell/docker-compose.yml

@@ -27,6 +27,8 @@ services:
       - ${HERMES_HOME:-${HOME}/.hermes}:/home/hermeswebui/.hermes
       # Your workspace directory shown on first launch (adapt if yours is different, the container will use the mounted /workspace)
       - ${HERMES_WORKSPACE:-${HOME}/workspace}:/workspace
+      # Mount extensions directory for custom themes/scripts
+      - ./extensions:/app/extensions
     environment:
       # Set to your host user ID: run `id -u` and `id -g` to find them.
       # On macOS, UIDs start at 501 (not 1000), so set UID and GID in a .env file:
@@ -44,6 +46,12 @@ services:
 #      - HERMES_WEBUI_DEFAULT_WORKSPACE=/workspace
       # Optional: set a password for remote access
       # - HERMES_WEBUI_PASSWORD=your-secret-password
+      # Extension configuration
+      - HERMES_WEBUI_EXTENSION_DIR=/app/extensions
+      - HERMES_WEBUI_EXTENSION_STYLESHEET_URLS=${HERMES_WEBUI_EXTENSION_STYLESHEET_URLS}
+      - HERMES_WEBUI_EXTENSION_SCRIPT_URLS=${HERMES_WEBUI_EXTENSION_SCRIPT_URLS}
+      - HERMES_WEBUI_BOT_NAME=${HERMES_WEBUI_BOT_NAME}
+      - HERMES_WEBUI_SKIP_ONBOARDING=${HERMES_WEBUI_SKIP_ONBOARDING}
       #
       # Bind-mount permission handling (fixes #1389, #1399):
       #   When you mount an EXISTING ~/.hermes directory (the common case),

package/vendor/agent-frontend-shell/docker_init.bash

@@ -196,6 +196,7 @@ chown_home_hermeswebui() {
   # ownership alignment.
   find /home/hermeswebui \
     -path "/home/hermeswebui/.hermes/hermes-agent" -prune \
+    -o -name ".git" -prune \
     -o -exec chown -h "${WANTED_UID}:${WANTED_GID}" {} +
 }
 

package/vendor/agent-frontend-shell/docs/rfcs/hermes-run-adapter-contract.md

@@ -956,28 +956,34 @@ Non-goals for Slice 4e:
 
 #### Slice 4f: Supervised local runner client backend gate
 
-Status as of 2026-05-28: client transport proposed in #3073 behind
-`HERMES_WEBUI_RUNNER_BASE_URL`; it should be described as under review until a
-release PR actually ships it.
-`runner-local` still remains default-off and returns the bounded not-configured
-path unless that endpoint is explicitly configured. When configured, WebUI uses a
-JSON HTTP client boundary for start / observe / status / controls and bridges
-observed runner events through the existing SSE stream route rather than adding
-main-process runner-owned maps.
+Status as of 2026-05-31: shipped in v0.51.188 via #3073 / #3274. The client
+transport is now implemented behind `HERMES_WEBUI_RUNNER_BASE_URL` and remains
+default-off. With no endpoint configured, `runner-local` still returns the
+bounded not-configured path and the live in-process `_run_agent_streaming` path
+is unchanged. When configured, WebUI uses a JSON HTTP client boundary for start /
+observe / status / controls and bridges observed runner events through the
+existing SSE stream route rather than adding main-process runner-owned maps.
+
+The release added two security hardening checks while absorbing #3073:
+`HttpRunnerClient` rejects non-`http(s)` base URL schemes and uses an opener that
+does not follow redirects, so a misconfigured or compromised runner cannot leak a
+Bearer token to a redirected host. The release gate reported full pytest passing
+and independent default-off/inert-path review.
+
 This bridge is intentionally a WebUI consumer transport seam: the configured
 runner must emit events that are already compatible with the browser SSE event
 names/payloads, or a later runner-owned normalization layer must translate
 Hermes runtime families such as `token.delta`, `tool.started`, and `done` before
 they reach this route.
 
-After the route-selection harness ships, the next reviewable step is not to make
-`runner-local` the default. It is to define the first concrete supervised/local
-runner client backend that can replace the bounded 501 path under the existing
-feature flag and prove execution ownership has moved out of the main WebUI
-request process.
+After the configured runner-client boundary ships, the next reviewable step is
+not to make `runner-local` the default. It is to define the first supervised
+runner process harness that can actually own `AIAgent` execution behind that
+client boundary and prove restart/reattach with a real local runner, not just a
+configured external endpoint or fake-runner fixture.
 
-This slice is a contract gate before backend code lands. The goal is to pin the
-minimum runner client behavior so the implementation cannot become a renamed
+This slice was the client-boundary implementation gate. The goal was to pin the
+minimum runner client behavior so the implementation could not become a renamed
 `STREAMS` / `CANCEL_FLAGS` / cached `AIAgent` surrogate inside `api/routes.py`.
 
 Scope:
@@ -1027,6 +1033,59 @@ Non-goals for Slice 4f:
 - no permanent WebUI-owned active-run discovery cache that duplicates runner or
   future Hermes Runtime API responsibility.
 
+#### Slice 4g: Supervised local runner process harness gate
+
+After #3073 / #3274, WebUI has an explicit configured-runner HTTP client and SSE
+consumer bridge, but it still does not ship the supervised runner process itself.
+The next gate should define the smallest local runner harness that can own
+`AIAgent` execution outside the main WebUI request process while being consumed
+through the already-shipped `runner-local` client boundary.
+
+Scope:
+
+- define the local runner process lifecycle: spawn/start, health check, run
+  ownership, graceful shutdown, crash classification, and cleanup;
+- keep WebUI as a client of `HERMES_WEBUI_RUNNER_BASE_URL`, not the owner of
+  process-local runner execution state;
+- persist run/session lookup, ordered events, terminal state, and active controls
+  in runner-owned or journal-backed state that a restarted WebUI can discover;
+- carry explicit profile, workspace, attachments, provider/model, toolset,
+  source, and metadata payloads into the runner without WebUI process-global
+  environment mutation;
+- prove cancel as the first live control for active runner-owned runs, with
+  approval, clarify, goal, and queue either mapped to explicit runner
+  capabilities or returned as bounded unsupported/conflict `ControlResult`
+  values.
+
+Acceptance tests for Slice 4g:
+
+1. **Process ownership moved.** A local runner process, not `hermes-webui`, owns
+   `AIAgent` construction/reuse and active run execution for `runner-local` runs.
+2. **Restart/reattach with a real runner.** Start a non-trivial `runner-local`
+   run, restart only `hermes-webui`, reload the session, rediscover the active or
+   terminal runner-owned run, replay/catch up from cursor without duplicate
+   transcript/tool/reasoning state, and preserve cancel if still active.
+3. **No runtime-surrogate globals in WebUI.** The main WebUI server still does not
+   gain new module-level maps for runner-owned streams, cancel flags,
+   approval/clarify callbacks, cached agents, child process run registries, goal
+   state, or queue schedulers.
+4. **Default-off and reversible.** Unset `HERMES_WEBUI_RUNNER_BASE_URL` or switch
+   the adapter mode back to legacy and the existing in-process path remains
+   available without session or journal migration.
+5. **Runner health and failure are observable.** A missing, unhealthy, or crashed
+   runner returns bounded diagnostics and terminal/interrupted state rather than
+   silently falling back to WebUI-owned execution for a runner-selected run.
+
+Non-goals for Slice 4g:
+
+- no default-on runner mode;
+- no removal of `legacy-direct` or `legacy-journal`;
+- no server-side queue scheduler just for adapter symmetry;
+- no broad WebUI product-surface migration;
+- no claim that this is the canonical Hermes Agent Runtime API; if Hermes Agent
+  later ships `/v1/runs`, this local runner remains a replaceable backend behind
+  the same adapter/client boundary.
+
 ## First Meaningful Success Criteria
 
 The first meaningful milestones are deliberately split.

package/vendor/agent-frontend-shell/extensions/common/index.css

@@ -0,0 +1,6 @@
+
+.app-titlebar-inner {width:100%;}
+.app-titlebar-icon {flex: 1;}
+.app-titlebar-inner::after {content: ""; flex: 1;}
+
+#btnCheckUpdatesNow {display: none !important; }

package/vendor/agent-frontend-shell/extensions/manifest.json

@@ -1,5 +1,11 @@
 {
   "extensions": [
+    {
+      "id": "common",
+      "order": 1,
+      "css": ["/extensions/common/index.css"],
+      "js": []
+    },
     {
       "id": "branding",
       "order": 1,

package/vendor/agent-frontend-shell/extensions/pages/ai-teammates/page.js

@@ -26,6 +26,11 @@
       ai_teammates_create_title: 'Create AI Teammate',
       ai_teammates_confirm_delete: 'Are you sure you want to delete this AI teammate?',
       ai_teammates_profile_prefix: 'bitseek_',
+      ai_teammates_cat_hr_ops: 'HR & Operations',
+      ai_teammates_cat_finance_tax: 'Finance & Tax',
+      ai_teammates_cat_biz_growth: 'Business Growth',
+      ai_teammates_cat_compliance: 'Policy & Compliance',
+      ai_teammates_cat_im: 'IM & Collaboration',
     });
 
     addTranslations('zh', {
@@ -43,6 +48,11 @@
       ai_teammates_create_title: '创建 AI 同事',
       ai_teammates_confirm_delete: '确定要删除这个 AI 同事吗？',
       ai_teammates_profile_prefix: 'bitseek_',
+      ai_teammates_cat_hr_ops: '人力资源与运营',
+      ai_teammates_cat_finance_tax: '财务与税务',
+      ai_teammates_cat_biz_growth: '业务增长',
+      ai_teammates_cat_compliance: '合规与政策',
+      ai_teammates_cat_im: '即时通讯',
     });
 
     addTranslations('ja', {
@@ -60,6 +70,11 @@
       ai_teammates_create_title: 'AI同僚を作成',
       ai_teammates_confirm_delete: 'このAI同僚を削除してもよろしいですか？',
       ai_teammates_profile_prefix: 'bitseek_',
+      ai_teammates_cat_hr_ops: '人事・オペレーション',
+      ai_teammates_cat_finance_tax: '財務・税務',
+      ai_teammates_cat_biz_growth: '事業成長',
+      ai_teammates_cat_compliance: 'コンプライアンス',
+      ai_teammates_cat_im: 'インスタントメッセージ',
     });
 
     addTranslations('ru', {
@@ -77,6 +92,11 @@
       ai_teammates_create_title: 'Создать AI коллегу',
       ai_teammates_confirm_delete: 'Вы уверены, что хотите удалить этого AI коллегу?',
       ai_teammates_profile_prefix: 'bitseek_',
+      ai_teammates_cat_hr_ops: 'HR и операции',
+      ai_teammates_cat_finance_tax: 'Финансы и налоги',
+      ai_teammates_cat_biz_growth: 'Рост бизнеса',
+      ai_teammates_cat_compliance: 'Политика и комплаенс',
+      ai_teammates_cat_im: 'Мгновенные сообщения',
     });
 
     addTranslations('es', {
@@ -94,6 +114,11 @@
       ai_teammates_create_title: 'Crear colega AI',
       ai_teammates_confirm_delete: '¿Estás seguro de que quieres eliminar este colega AI?',
       ai_teammates_profile_prefix: 'bitseek_',
+      ai_teammates_cat_hr_ops: 'RRHH y Operaciones',
+      ai_teammates_cat_finance_tax: 'Finanzas y Fiscalidad',
+      ai_teammates_cat_biz_growth: 'Crecimiento del Negocio',
+      ai_teammates_cat_compliance: 'Política y Cumplimiento',
+      ai_teammates_cat_im: 'Mensajería Instantánea',
     });
 
     addTranslations('de', {
@@ -111,6 +136,11 @@
       ai_teammates_create_title: 'AI-Kollegen erstellen',
       ai_teammates_confirm_delete: 'Sind Sie sicher, dass Sie diesen AI-Kollegen löschen möchten?',
       ai_teammates_profile_prefix: 'bitseek_',
+      ai_teammates_cat_hr_ops: 'Personal & Betrieb',
+      ai_teammates_cat_finance_tax: 'Finanzen & Steuern',
+      ai_teammates_cat_biz_growth: 'Unternehmenswachstum',
+      ai_teammates_cat_compliance: 'Richtlinien & Compliance',
+      ai_teammates_cat_im: 'Instant Messaging',
     });
 
     addTranslations('it', {
@@ -128,6 +158,11 @@
       ai_teammates_create_title: 'Crea collega AI',
       ai_teammates_confirm_delete: 'Sei sicuro di voler eliminare questo collega AI?',
       ai_teammates_profile_prefix: 'bitseek_',
+      ai_teammates_cat_hr_ops: 'Risorse Umane & Operazioni',
+      ai_teammates_cat_finance_tax: 'Finanza & Fiscalità',
+      ai_teammates_cat_biz_growth: 'Crescita Aziendale',
+      ai_teammates_cat_compliance: 'Politica & Conformità',
+      ai_teammates_cat_im: 'Messaggistica',
     });
   }
 
@@ -155,9 +190,14 @@
   }
 
   /**
-   * Parse a bitseek profile name into { category, displayName, initials }
+   * Parse a bitseek profile name into { category, categoryDisplay, displayName, initials }
    * Pattern: bitseek_[category]_[displayName]
-   * e.g. bitseek_collaboration_dingtalk → { category: '协作办公', displayName: '钉钉助手' }
+   * e.g. bitseek_collaboration_dingtalk → { category: 'ai_teammates_cat_im', displayName: 'Dingtalk' }
+   * Categories: hr/operations/support → HR & Operations
+   *             collaboration → IM & Collaboration
+   *             finance → Finance & Tax
+   *             marketing/sales/product → Business Growth
+   *             tech/data → Policy & Compliance
    */
   function parseBitseekName(name) {
     var prefix = 'bitseek_';
@@ -171,22 +211,25 @@
     var rawCategory = parts[0];
     var rawDisplayName = parts.slice(1).join('_');
 
-    // Map English category keys to Chinese display names
+    // Map English category keys to i18n category keys
     var categoryMap = {
-      'collaboration': '协作办公',
-      'marketing': '营销增长',
-      'sales': '销售营收',
-      'support': '客户服务',
-      'hr': '人力资源',
-      'finance': '财务法务',
-      'product': '产品设计',
-      'tech': '技术研发',
-      'operations': '运营管理',
-      'data': '数据分析',
+      'hr':         'ai_teammates_cat_hr_ops',
+      'operations': 'ai_teammates_cat_hr_ops',
+      'support':    'ai_teammates_cat_hr_ops',
+      'im': 'ai_teammates_cat_im',
+      'finance':    'ai_teammates_cat_finance_tax',
+      'marketing':  'ai_teammates_cat_biz_growth',
+      'sales':      'ai_teammates_cat_biz_growth',
+      'product':    'ai_teammates_cat_biz_growth',
+      'tech':       'ai_teammates_cat_compliance',
+      'data':       'ai_teammates_cat_compliance',
     };
 
     var category = categoryMap[rawCategory] || rawCategory;
 
+    // Resolve i18n key to display name
+    var categoryDisplay = (category.indexOf('ai_teammates_cat_') === 0) ? t(category) : category;
+
     // Convert raw display name to readable (snake_case → title case as fallback)
     var displayName = rawDisplayName
       .replace(/_/g, ' ')
@@ -197,6 +240,7 @@
 
     return {
       category: category,
+      categoryDisplay: categoryDisplay,
       displayName: displayName,
       initials: initials,
       rawName: name,
@@ -265,6 +309,7 @@
           return {
             name: p.name,
             category: parsed.category,
+            categoryDisplay: parsed.categoryDisplay,
             displayName: parsed.displayName,
             initials: getInitials(parsed.displayName),
             description: p.description || '',
@@ -343,11 +388,12 @@
     } else {
       _categoryOrder.forEach(function(category) {
         var roles = _groupedRoles[category];
+        var categoryLabel = (category.indexOf('ai_teammates_cat_') === 0) ? t(category) : category;
 
         html += '<div class="at-category">';
         html += '  <div class="at-category-header">';
         html += '    <span class="at-category-dot"></span>';
-        html += '    <span class="at-category-name">' + esc(category) + '</span>';
+        html += '    <span class="at-category-name">' + esc(categoryLabel) + '</span>';
         html += '    <span class="at-category-count">' + esc(t('ai_teammates_role_count', roles.length)) + '</span>';
         html += '  </div>';
         html += '  <div class="at-role-grid">';

package/vendor/agent-frontend-shell/readme-simple.md

@@ -0,0 +1,103 @@
+# Hermes Web UI (Simplified) / 简化版说明
+
+> **Repository / 仓库**: [https://github.com/adv-org/agent-frontend-shell](https://github.com/adv-org/agent-frontend-shell)
+
+A lightweight web interface for Hermes Agent. No build step, no framework — just Python and vanilla JS.
+
+Hermes Agent 的轻量级 Web 界面。无需构建步骤，无框架依赖 —— 仅使用 Python 和原生 JavaScript。
+
+---
+
+## Quick Start / 快速开始
+
+### 1. Clone / 克隆
+
+```bash
+git clone https://github.com/adv-org/agent-frontend-shell.git
+cd agent-frontend-shell
+```
+
+### 2. Local Run / 本地运行
+
+**Requirements / 环境要求:** Python 3.12+
+
+```bash
+# Option 1: Direct Python / 方式一：直接运行 Python
+python3 bootstrap.py
+
+# Option 2: Shell wrapper (same as above) / 方式二：包装脚本（效果相同）
+./start.sh
+```
+
+Access at / 访问地址: **http://127.0.0.1:8787**
+
+---
+
+## Docker Run / Docker 运行
+
+### Single container / 单容器模式
+
+```bash
+# Edit .env first / 先编辑 .env
+cp .env.example .env
+# Modify HERMES_HOME, HERMES_WORKSPACE, UID, GID as needed
+# 按需修改 HERMES_HOME、HERMES_WORKSPACE、UID、GID
+
+docker compose -f docker-compose.local.yml up -d --build
+```
+
+### Two-container (WebUI + Agent) / 双容器模式
+
+```bash
+docker compose -f docker-compose.two-container.yml up -d
+```
+
+### Three-container (WebUI + Agent + DB) / 三容器模式
+
+```bash
+docker compose -f docker-compose.three-container.yml up -d
+```
+
+---
+
+## Configuration / 配置
+
+Key environment variables / 关键环境变量:
+
+| Variable | Description / 说明 | Default / 默认值 |
+|---|---|---|
+| `HERMES_WEBUI_PORT` | Server port / 服务端口 | `8787` |
+| `HERMES_WEBUI_PASSWORD` | Access password / 访问密码 | (none) |
+| `HERMES_HOME` | Hermes data dir / 数据目录 | `~/.hermes` |
+| `HERMES_WORKSPACE` | Workspace path / 工作区路径 | `~/workspace` |
+| `UID` / `GID` | User/Group ID for permissions / 权限映射 | `1000` |
+
+Full config reference / 完整配置参考: [README.md](README.md) → Configuration section
+
+---
+
+## Common Commands / 常用命令
+
+```bash
+# Check health / 健康检查
+curl http://127.0.0.1:8787/health
+
+# View logs / 查看日志
+docker logs -f hermes-webui-custom
+
+# Stop / 停止
+docker compose -f docker-compose.local.yml down
+
+# Rebuild / 重新构建
+docker compose -f docker-compose.local.yml up -d --build
+```
+
+---
+
+## Architecture / 架构
+
+- **Backend / 后端**: Python (Flask-like), file-based state
+- **Frontend / 前端**: Vanilla JS, no bundler
+- **State / 状态**: Local filesystem (`~/.hermes`)
+
+For full details / 完整详情: [ARCHITECTURE.md](ARCHITECTURE.md) | [TESTING.md](TESTING.md)

package/vendor/agent-frontend-shell/requirements.txt

@@ -1,5 +1,10 @@
 # Hermes Web UI -- minimal Python dependencies
 # The server uses PyYAML plus cryptography for optional local passkey/WebAuthn support.
 # All heavy ML/agent deps live in the Hermes agent venv.
+#
+# OPTIONAL: the Edge TTS speech engine (Settings -> Voice -> TTS Engine -> "Edge TTS")
+# needs `edge-tts`. It is intentionally NOT a hard dependency — the /api/tts
+# endpoint returns 503 with an install hint when it's absent. Install it only if
+# you want server-side Microsoft neural voices:  pip install edge-tts
 pyyaml>=6.0
 cryptography>=42.0

package/vendor/agent-frontend-shell/server.py

@@ -581,6 +581,13 @@ def main() -> None:
     except Exception as e:
         print(f'[!!] WARNING: Gateway watcher failed to start: {e}', flush=True)
 
+    # Load WebUI dashboard plugins
+    try:
+        from api.plugins import load_plugins
+        load_plugins()
+    except Exception as e:
+        print(f'[!!] WARNING: Plugin loading failed: {e}', flush=True)
+
     httpd = QuietHTTPServer((HOST, PORT), Handler)
 
     # ── TLS/HTTPS setup (optional) ─────────────────────────────────────────

package/vendor/agent-frontend-shell/static/boot.js

@@ -1,3 +1,6 @@
+// Early boot initialization that must run before any other code.
+// These run during script evaluation to handle server-stopped state
+// and cross-tab shutdown broadcasts as early as possible.
 (function(){
   // Clear stale stop-server flag on successful page load (server is reachable)
   try{localStorage.removeItem('hermes-webui-server-stopped');}catch(_){}
@@ -889,7 +892,56 @@ window._micPendingSend=window._micPendingSend||false;
         .trim();
     }
     if(!clean){ _startListening(); return; }
-
+    const engine=localStorage.getItem("hermes-tts-engine")||"browser";
+    if(engine==="edge"){
+      const voice=localStorage.getItem("hermes-tts-voice")||"zh-CN-XiaoxiaoNeural";
+      const savedRate=parseFloat(localStorage.getItem("hermes-tts-rate"));
+      const savedPitch=parseFloat(localStorage.getItem("hermes-tts-pitch"));
+      let rate='', pitch='';
+      if(!isNaN(savedRate)){const pct=Math.round((savedRate-1)*100);const sign=pct>=0?'+':'';rate=sign+pct+'%';}
+      if(!isNaN(savedPitch)){const hz=Math.round((savedPitch-1)*50);const sign=hz>=0?'+':'';pitch=sign+hz+'Hz';}
+      _ttsSpeaking=true;
+      fetch(new URL('api/tts', document.baseURI || location.href).href, {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({text: clean, voice, rate, pitch})
+      })
+      .then(r => {
+        if(!r.ok) throw new Error('TTS request failed: ' + r.status);
+        return r.blob();
+      })
+      .then(blob => {
+        const url = URL.createObjectURL(blob);
+        const audio = new Audio(url);
+        // Register with the shared handle (declared in ui.js, same global scope;
+        // both scripts are fully evaluated before any voice interaction) so
+        // stopTTS() — called from _deactivate() — can actually pause hands-free
+        // Edge playback. Without this the audio is local here and unstoppable.
+        _playingEdgeAudio=audio;
+        audio.onended = () => {
+          _ttsSpeaking=false;
+          if(_playingEdgeAudio===audio) _playingEdgeAudio=null;
+          URL.revokeObjectURL(url);
+          if(_voiceModeActive) setTimeout(()=>_startListening(),500);
+        };
+        audio.onerror = () => {
+          _ttsSpeaking=false;
+          if(_playingEdgeAudio===audio) _playingEdgeAudio=null;
+          URL.revokeObjectURL(url);
+          if(_voiceModeActive) setTimeout(()=>_startListening(),1000);
+        };
+        audio.play().catch(e => {
+          _ttsSpeaking=false;
+          if(_playingEdgeAudio===audio) _playingEdgeAudio=null;
+          if(_voiceModeActive) setTimeout(()=>_startListening(),1000);
+        });
+      })
+      .catch(() => {
+        _ttsSpeaking=false;
+        if(_voiceModeActive) setTimeout(()=>_startListening(),1000);
+      });
+      return;
+    }
     const utter=new SpeechSynthesisUtterance(clean);
 
     // Apply saved voice preferences

package/vendor/agent-frontend-shell/static/commands.js

@@ -322,6 +322,24 @@ function cmdClear(){
   showToast(t('conversation_cleared'));
 }
 
+// Find the best matching model <option> for a slash-command query.
+// Returns an exact id/label match if present, otherwise the shortest option
+// whose value or label contains the query. Preferring the shortest match keeps
+// a specific query like "mimo-v2.5" from being shadowed by a longer variant
+// such as "mimo-v2.5-pro". See issue #3368.
+function _bestModelMatch(options,query){
+  let best=null;
+  for(const opt of options){
+    const value=opt.value.toLowerCase();
+    const text=opt.textContent.toLowerCase();
+    if(value===query||text===query) return opt.value;
+    if(value.includes(query)||text.includes(query)){
+      if(best===null||opt.value.length<best.length) best=opt.value;
+    }
+  }
+  return best;
+}
+
 async function cmdModel(args){
   if(!args){showToast(t('model_usage'));return;}
   const sel=$('modelSelect');
@@ -348,21 +366,13 @@ async function cmdModel(args){
   let match=(typeof _findModelInDropdown==='function')?_findModelInDropdown(q,sel,preferred):null;
   // Fallback: fuzzy match across all options
   if(!match){
-    for(const opt of sel.options){
-      if(opt.value.toLowerCase().includes(q)||opt.textContent.toLowerCase().includes(q)){
-        match=opt.value;break;
-      }
-    }
+    match=_bestModelMatch(sel.options,q);
   }
   // Fallback: if q has provider/ prefix (e.g. "deepseek/deepseek-v4-flash"),
   // try the bare model name (which is how options appear for the active provider)
   if(!match && q.includes('/')){
     const bare=q.slice(q.lastIndexOf('/')+1);
-    for(const opt of sel.options){
-      if(opt.value.toLowerCase().includes(bare)||opt.textContent.toLowerCase().includes(bare)){
-        match=opt.value;break;
-      }
-    }
+    match=_bestModelMatch(sel.options,bare);
     // Cross-provider fallback: if still no match, the model is from a
     // different provider not in the dropdown. Call /api/session/update directly.
     if(!match && S&&S.session&&S.session.session_id){