dsh-vision

Capability-aware vision + paste extension for DeepSeek Harness, ported 1:1 from @gitawego/pi-vision. Published on npm as @gitawego/dsh-vision.

• describe_image tool (single + batch image_paths) — hidden on multimodal primaries (native pass-through), visible on text-only primaries (delegation with cache/retry/fallback).
• Paste UX: [Image-#N] markers, hint/auto/off modes.
• Cache, audit log, local-only mode, batch concurrency, auto-detect, /vision command, Web Settings (data-driven, no hardcoded provider/model ids).

Installation

Install the plugin into a profile (the harness composes plugins per profile; the web profile backs the Web GUI). Pick one:

1. npm registry (recommended)

The package is published; add it from the registry and let the harness reconcile the bundle list:

dsh plugin --profile <name> add @gitawego/dsh-vision
dsh plugin --profile <name> install

Verify it composed, then restart the harness so the plugin (and its Web client) load:

dsh --profile <name> --dump-config   # expect a row for @gitawego/dsh-vision
dsh --profile <name>                 # restart, e.g. dsh web

2. Direct install (local path / no registry)

Useful for development or offline hosts: depend on a local checkout with a file: spec (exactly what pnpm would write for pnpm add file:...) and list the package in the profile's bundles, then run the official install command:

1. Edit ~/.dsh/profiles/<name>/package.json:

{
  "dependencies": {
    "@gitawego/dsh-vision": "file:/absolute/path/to/dsh-vision"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "@gitawego/dsh-vision"
      ]
    }
  }
}

1. Install + verify + restart:

dsh plugin --profile <name> install
dsh --profile <name> --dump-config   # expect a row for @gitawego/dsh-vision
dsh --profile <name>                 # restart

Note: after rebuilding a local checkout, re-run dsh plugin --profile <name> install (pnpm copies file: dependencies into its store — not a live link).

Configuration

Configure the vision provider/model and behavior in the Settings → Vision page, or with the /vision command (/vision show, /vision config provider <id>, ...).

• provider / model — an image-capable model from the live harness catalog (data-driven; auto-detect offers a default). Used by the native sub-agent delegation.
• delegation — auto (native sub-agent with the vision model; falls back to the direct http endpoint when the harness cannot deliver images natively), native (sub-agent only), http (plugin-owned direct endpoint call).
• http block — baseUrl, credential (a DSH credential-ref name), model, protocol (openai | anthropic).

Example http configuration (any OpenAI-compatible vision endpoint):

/vision config delegation http
/vision config http.baseUrl https://api.example.com/v1
/vision config http.model vision-model
/vision config http.credential VISION_API_KEY   # a DSH credential ref

Android/Termux note: the harness attachment store cannot write under /data/data (its durability walk hits EACCES — a raw Android permission), so the native sub-agent path cannot deliver images there. Use delegation=http with the http block on Termux; auto falls back to http automatically when the store is unavailable. The same rule drives image routing: on Termux even a multimodal primary (e.g. MiniMax-M3) is treated as effectively text-only — it cannot receive native ImageBlocks, so describe_image becomes visible and your existing textOnlyPasteMode governs (hint = on-demand delegation via http, auto = automatic, off = markers only). The hint names native delivery as the reason instead of blaming the model, and pasted images are never silently dropped as a bare [Image-#N] marker. On hosts with a working attachment store, multimodal models keep native passthrough.

Routing & model-switch behavior

The plugin routes images by the current session model's capability (detected from the live harness catalog, never hardcoded):

Session primary model	Image behavior
Multimodal (e.g. a vision "luna")	Native pass-through: pasted path tokens become [Image-#N] markers + ImageBlock attachments; the model sees the raw image. describe_image is hidden (delegation would be wasteful).
Text-only (e.g. glm-5.2)	Convert to text: path tokens and GUI image blocks are delegated to the configured vision model (cache/retry/fallback) or surfaced as hint markers for describe_image. The tool is visible.

Mid-session model switches are detected at the earliest point of the next step (system-prompt/assemble, which fires before the paste hook and before tool visibility is frozen), so the first step after a switch already routes correctly — paste auto-converts (or attaches natively), and describe_image is shown/hidden accordingly. /vision session-status reports the tracked model, the logged request header, and flags a switch that is still pending detection.

Harness (GUI) constraints on rc.6 — the dsh-host-apiproxy wire refuses two operations before this plugin ever sees the message, independent of the plugin:

• sending a prompt with images while the session model is text-only → attachment-error "Model X does not support image input";
• switching to a text-only model while the session already contains images → model-unavailable "…but this session already contains images".

So via the GUI, "upload an image while on glm-5.2" and "switch to glm-5.2 in an image session" are blocked by design. The plugin's supported route for those flows is image paths + textOnlyPasteMode: auto (paste the path; the vision model describes it; the text-only model reads the description), or switching models before images enter the session. Image blocks that DO reach the paste hook on a text-only primary (tui/headless/direct API, or future wires) are materialized to hash-named temp files under <DSH_HOME>/tmp/dsh-vision/ (Termux-safe: the OS tmpdir may be unwritable) and converted through the same pipeline — a raw image block never reaches a text-only model's request boundary. Auto-converted temp files are removed after delegation; hint-mode files are retained (content-hash-deduped) so the model can name them with describe_image.

Platform support

The harness loads client bundles only for platform: "web" (dsh-client-modules skips every other platform), so the plugin's Web client is available only in the web profile:

Surface	web	tui / headless
describe_image tool	✓	✓ (host tool)
/vision command	✓	✓ (host command)
Paste markers / auto	✓	✓ (agent/pre-step hook)
Delegation (subagent/http)	✓	✓
Settings page (Vision)	✓	— (web-only slot)
Tool call card	✓	— (web-only slot)

For tui / headless profiles, configure everything with the /vision command (/vision show, /vision config ...) or by editing vision: in ~/.dsh/settings.yaml — the settings page is a Web-only convenience, not a requirement.

Development

npm ci
npm run typecheck
npm test
npm run build      # server + client bundles (lib/ incl. lib/client.js)

Publishing is automated via GitHub Actions: tag v* to run typecheck/tests/build and publish @gitawego/dsh-vision to npm with provenance (OIDC trusted publishing), plus a GitHub Release.

Docs

• SPEC.md — full implementation spec (feature parity, architecture, KV-cache requirements).
• AGENTS.md — project architecture and design rules.
• LESSONS.md — session history, debugging deep-dives, tooling pitfalls.