mios-show-image: one canonical call for "show me a picture of X"

Operator chat 2026-05-17 paste -- "Bring up a picture of cute dog on
the left of my screen" -- ran 13 tool calls (skill_view + skill_manage
+ web_extract loops + terminal pipelines), tried to download/save the
image, hit WSL filesystem read-only errors, then declared defeat with
"I'm sorry, but I couldn't capture a screenshot due to technical
issues with the Windows filesystem". The operator's correction: "Should
just open the image directly in a browser window then!! (localhost
browser on windows or Local MiOS linux browser(s)(if multiple
present))".

mios-show-image collapses the whole flow to one tool call:
  1. SearXNG image search via probe-list (local containers + DNS aliases)
  2. Pick first usable img_src / thumbnail_src / url
  3. mios-open-url <img> -- uses the operator's MiOS-defined default
     browser (mios.toml [[desktop.apps]] role=browser default=true)
  4. Optional --position left|right|center|top|bottom|maximize:
     waits 1.2s for the window to surface, then mios-window <pos>
     "<host-pattern>" against the URL's hostname.

Probe list defaults to all common searxng endpoints (loopback +
container DNS); MIOS_SEARXNG_URL overrides. Exit codes:
  0 = opened (+ optional position applied)
  1 = no results
  2 = searxng unreachable / non-JSON
  3 = mios-open-url failed
-- so the agent can distinguish "nothing matched" from "infrastructure
down" without parsing prose.

SOUL.md additions:
* New section "Show me an image / picture of X" -- one-call rule
  with the Crew Motorfest-style "Don't" list (no curl -O, no
  browser_navigate, no mios-screenshot, no /mnt/c writes). Falls
  back to web_search categories=images manually if mios-show-image
  exits 2.
* Helpers table picks up the four new shims it didn't have yet:
  mios-show-image, mios-discord-status, mios-hermes-browser ensure,
  mios-cache-clear.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mios-dev

usr/libexec/mios/mios-show-image

@@ -0,0 +1,164 @@
+#!/bin/bash
+# /usr/libexec/mios/mios-show-image <query> [--position left|right|center|top|bottom] [--engine images|videos]
+#
+# Operator directive 2026-05-17: "should just open the image directly
+# in a browser window then!! (localhost browser on windows or Local
+# MiOS linux browser(s)(if multiple present))". The agent was running
+# 13 tool calls trying to download + save + screenshot images, hitting
+# WSL filesystem read-only errors, when the operator's actual ask was:
+# search -> open URL in browser. Done.
+#
+# Flow:
+#   1. SearXNG image search via the local mios-searxng service
+#      (NO cloud APIs, NO file downloads, NO image saves)
+#   2. Pick the top result's img_src
+#   3. Open that URL via mios-open-url (resolves the MiOS-defined
+#      default browser per mios.toml -- could be Windows-side Chrome
+#      or a Linux flatpak; operator's choice)
+#   4. (optional) After 1.2s, mios-window move "<title-pattern>" to
+#      the requested screen-half via mios-window
+#
+# Exit codes:
+#   0 = found + opened (+ optional position applied)
+#   1 = searxng returned no images
+#   2 = searxng unreachable / parse failure
+#   3 = mios-open-url failed
+#
+# Env-overridable:
+#   MIOS_SEARXNG_URL   probe-list, comma-separated. Defaults:
+#                      "http://127.0.0.1:8888,http://mios-searxng:8888,
+#                       http://mios-searxng:8080,http://localhost:8888"
+#   MIOS_IMAGE_TIMEOUT seconds per searxng call (default 8)
+
+set -uo pipefail
+
+usage() {
+    cat <<'USAGE'
+usage: mios-show-image <query> [options]
+
+  <query>             Image search query (quote multi-word).
+
+Options:
+  --position <pos>    Move the browser window after open. One of:
+                      left | right | center | top | bottom | maximize.
+                      Default: no positioning.
+  --engine <engine>   SearXNG category. Default: images.
+                      Also: videos (some engines support).
+  --browser <name>    Override the default browser (passed to
+                      mios-open-url). Useful when multiple browsers
+                      exist (e.g. windows-chrome vs chromedev).
+  -h, --help          Show this help.
+
+Examples:
+  mios-show-image "cute dog"
+  mios-show-image "cute dog" --position left
+  mios-show-image "neon city" --position right --browser chromedev
+USAGE
+}
+
+if [ "$#" -lt 1 ] || [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
+    usage
+    [ "$#" -lt 1 ] && exit 64 || exit 0
+fi
+
+QUERY="$1"
+shift
+POSITION=""
+ENGINE="images"
+BROWSER=""
+
+while [ "$#" -gt 0 ]; do
+    case "$1" in
+        --position) POSITION="${2:-}"; shift 2 ;;
+        --engine)   ENGINE="${2:-images}"; shift 2 ;;
+        --browser)  BROWSER="${2:-}"; shift 2 ;;
+        *) echo "mios-show-image: unknown arg: $1" >&2; exit 64 ;;
+    esac
+done
+
+TIMEOUT="${MIOS_IMAGE_TIMEOUT:-8}"
+PROBE_LIST="${MIOS_SEARXNG_URL:-http://127.0.0.1:8888,http://mios-searxng:8888,http://mios-searxng:8080,http://localhost:8888}"
+
+# --- 1. SearXNG image search -------------------------------------
+
+pick_img_src() {
+    # Parse JSON, surface the first usable image URL. Prefers
+    # img_src (full-res) over thumbnail_src; falls back to url.
+    python3 - <<'PY'
+import json, sys
+try:
+    d = json.load(sys.stdin)
+except Exception as e:
+    print("", file=sys.stderr); sys.exit(2)
+for r in (d.get("results") or []):
+    for k in ("img_src", "thumbnail_src", "url"):
+        v = (r.get(k) or "").strip()
+        if v.startswith(("http://", "https://")):
+            print(v); sys.exit(0)
+sys.exit(1)
+PY
+}
+
+IMG_URL=""
+for url in ${PROBE_LIST//,/ }; do
+    body=$(curl -sS --max-time "$TIMEOUT" -G "$url/search" \
+        --data-urlencode "q=$QUERY" \
+        --data-urlencode "format=json" \
+        --data-urlencode "categories=$ENGINE" \
+        --data-urlencode "safesearch=1" 2>/dev/null) || continue
+    [ -z "$body" ] && continue
+    candidate=$(printf '%s' "$body" | pick_img_src 2>/dev/null) || continue
+    if [ -n "$candidate" ]; then
+        IMG_URL="$candidate"
+        echo "[mios-show-image] using searxng=$url"
+        break
+    fi
+done
+
+if [ -z "$IMG_URL" ]; then
+    echo "mios-show-image: no image results from any SearXNG endpoint" >&2
+    echo "  probed: $PROBE_LIST" >&2
+    echo "  hint:   curl '$PROBE_LIST/search?q=test&format=json&categories=images' to debug" >&2
+    exit 2
+fi
+
+echo "[mios-show-image] query=$QUERY -> $IMG_URL"
+
+# --- 2. Open in default browser ----------------------------------
+
+OPEN_ARGS=("$IMG_URL")
+[ -n "$BROWSER" ] && OPEN_ARGS+=("$BROWSER")
+if ! mios-open-url "${OPEN_ARGS[@]}"; then
+    echo "mios-show-image: mios-open-url failed for $IMG_URL" >&2
+    exit 3
+fi
+echo "[mios-show-image] opened in default browser"
+
+# --- 3. Optional positioning -------------------------------------
+
+if [ -n "$POSITION" ]; then
+    # Browser takes a moment to render the window. mios-window-active
+    # --present waits for the window to actually surface before
+    # mios-window can target it.
+    sleep 1.2
+    # Pull the browser window by host title (image hostname or "image")
+    HOST=$(printf '%s' "$IMG_URL" | sed -nE 's|^https?://([^/]+).*|\1|p')
+    TITLE_PAT="${HOST:-image}"
+    case "$POSITION" in
+        left|right|top|bottom|center|maximize)
+            if mios-window "$POSITION" "$TITLE_PAT" 2>/dev/null; then
+                echo "[mios-show-image] positioned: $POSITION"
+            else
+                # Fallback: try by short title fragments most browsers use
+                for pat in "$QUERY" "image" "search"; do
+                    mios-window "$POSITION" "$pat" 2>/dev/null && break
+                done
+            fi
+            ;;
+        *)
+            echo "mios-show-image: unknown --position '$POSITION' (left|right|top|bottom|center|maximize)" >&2
+            ;;
+    esac
+fi
+
+exit 0

usr/share/mios/ai/hermes-soul.md

@@ -154,6 +154,10 @@ fields. If you don't have the number from a tool's stdout, say
 | `mios-env-probe` | Runtime snapshot. |
 | `mios-skill-clone <name> [--as <new>]` | Fork a vendor skill into `$HERMES_HOME/skills/` so you can edit it. Same-name fork overrides on next load. |
 | `mios-tool-clone <name> [--as <new>]` | Fork a vendor shim into `/usr/local/bin/` (precedes `/usr/libexec/mios` on PATH). |
+| `mios-show-image "<q>" [--position left\|right\|center]` | Image search + open in operator's default browser. Single canonical call for "show me a picture of X". |
+| `mios-discord-status` | Self-check the Discord integration (token, guilds, default channel, directory mtime). |
+| `mios-hermes-browser ensure` | Idempotent: bring CDP up on :9222 if not responding. Required before any `browser_*` tool call. |
+| `mios-cache-clear [--dry-run] [--all]` | Wipe regenerable state (chats/sessions/caches); preserves users, models, tools, ollama, skills, configs. |
 
 State paths (read freely):
 - `/var/lib/mios/scratch/` — inter-agent shared scratch (mode 1777)
@@ -228,6 +232,30 @@ in the user's tone (1-2 sentences). DO NOT:
 "what GPU do I have", "list ollama models", "what services are
 running", "how much disk left", "system status".
 
+## Show me an image / picture of X
+
+ONE call: `terminal: mios-show-image "<query>" [--position left|right|center]`.
+
+That helper does: SearXNG image search → first result's `img_src` →
+opens via `mios-open-url` (uses the operator's MiOS-defined default
+browser). No file download, no screenshot, no save-to-disk path.
+
+Operator-flagged 2026-05-17: agent ran 13 tool calls trying to
+download + save + screenshot a "cute dog" image, hit "WSL filesystem
+read-only" errors, and declared defeat. The operator's actual ask
+was "open in browser" -- exactly one tool call's worth of work.
+
+Don't:
+* `web_search` then try to fetch the URL with `terminal: curl -O`
+* `browser_navigate` (CDP headless -- operator can't see it)
+* `mios-screenshot` (that's for capturing the operator's screen,
+  not for fetching a remote image)
+* Anything writing to `/mnt/c/Users/...` -- you don't need a file
+
+If `mios-show-image` returns exit 2 ("no image results"), THEN
+fall back to `web_search categories=images` and pass any returned
+URL through `mios-open-url` manually.
+
 ## Native tools vs `terminal` — don't confuse the surfaces
 
 Native tools (`memory_save`, `kanban_create`, `web_search`,