feat(vision): add vision tool using MiniCPM-V 4.6 (1.3B) via llama-mtmd-cli (#22)

* feat(vision): add vision tool using MiniCPM-V 4.6 (1.3B) via llama-mtmd-cli

Adds a `vision` built-in tool that analyses images and videos locally using
MiniCPM-V 4.6 — a 1.3B multimodal model running via llama.cpp's
llama-mtmd-cli, with no cloud API required.

## What's new

**Tool (`vision`)**
- Accepts images (JPEG, PNG, GIF, WebP, BMP) and videos (MP4, MOV, AVI,
  MKV, WebM)
- Videos: ffprobe reads duration, ffmpeg extracts N evenly-spaced frames,
  all frames sent as a multi-image call to the model (configurable via
  `video_frames`, default 8)
- Security: O_NOFOLLOW open (symlink protection), danger.CheckOperation
  classification, all output wrapped in wrapUntrusted() with provenance tag
- Setup instructions in every error path (missing binary, missing model,
  missing mmproj, missing ffmpeg)

**Docker (`docker/Dockerfile`)**
- New `minicpm` multi-stage build: downloads pre-built llama-mtmd-cli
  (llama.cpp b9549) for amd64/arm64 from the official GitHub release, then
  fetches MiniCPM-V-4_6-Q4_K_M.gguf (529 MB) and mmproj-model-f16.gguf
  (1.1 GB) from HuggingFace into /usr/local/share/minicpm-v/models/
- Overridable via --build-arg MINICPM_QUANT=Q8_0 and LLAMA_VERSION
- Runtime stage copies binary + models; no new runtime deps (libstdc++6
  already present for whisper)

**Config (`internal/config/loader.go`)**
- New VisionConfig struct: ModelsDir, BinaryPath, VideoFrames
- Wired into FileConfig, ResolvedConfig, resolveVision(), mergeFile()

**Tests**
- 13 tests in cmd/odek/vision_tool_test.go: empty path, invalid JSON, file
  not found, symlink rejected, missing binary, missing model, missing mmproj,
  mock happy-path image (4 extensions), custom prompt, mock happy-path video
  (with mock ffprobe+ffmpeg via PATH override), missing ffmpeg fallback,
  schema shape
- 3 tests in internal/config/vision_test.go: resolveVision defaults,
  zero-frames backfill, custom values round-trip

**Docs**
- docs/CHEATSHEET.md: new Image & Video Understanding section with config
  snippet and field reference
- docs/SECURITY.md: vision added to untrusted-content table, always-untrusted
  list, and skills provenance gate paragraph
- docs/CONFIG.md + docs/TELEGRAM.md: smart-previews bullet updated
- docker/README.md: new Image & video understanding (out of the box) section
- README.md: vision added to external-content ingestion list

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(vision): pin MiniCPM-V HuggingFace downloads to a specific revision hash

Replace `resolve/main/` with `resolve/<sha>/` (78e02f0) so Docker builds
are reproducible — a future model update on the main branch won't silently
change the binary image.

vprotocol auto-repair: finding D001 (Axis 2.6 Dependency Integrity).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: jkyberneees

README.md

@@ -36,7 +36,7 @@ odek is not a framework. It's a **runtime** — the smallest possible surface ar
 Every session can run in an isolated Docker container: no network, no host mounts beyond the working directory, zero capabilities, destroyed on exit. `odek serve` enables the sandbox **by default**; `odek run` keeps it opt-in but warns when running unsandboxed. `--ctx` files are auto-injected into the container at `/workspace/`. Full security model in [docs/SANDBOXING.md](docs/SANDBOXING.md).
 
 ### 🛡️ Prompt-Injection-Aware
-External content the agent ingests (`browser`, `read_file`, `shell`, `search_files`, `multi_grep`, `transcribe`, `session_search`, MCP tools) is wrapped in per-call nonce'd `<untrusted_content>` boundaries so the model can distinguish data from instructions. Redirect hops are re-classified (`browser`/`http_batch`), MCP tool descriptions are scanned for injection at registration, and the MCP error channel is wrapped too. The danger classifier resists 8 known shell-evasion tricks (`$()`, backticks, `$IFS`, `command`/`exec`, `\rm`, basenamed absolute paths). Approvers engage friction mode after 3 same-class approvals in 60 s. Memory episodes from tainted sessions are stored but never auto-replayed. Skill auto-save tracks provenance and pins untrusted suggestions for explicit `odek skill promote`. `odek audit <session-id>` surfaces every ingest + per-turn divergence heuristic. Full threat model in [docs/SECURITY.md](docs/SECURITY.md).
+External content the agent ingests (`browser`, `read_file`, `shell`, `search_files`, `multi_grep`, `transcribe`, `vision`, `session_search`, MCP tools) is wrapped in per-call nonce'd `<untrusted_content>` boundaries so the model can distinguish data from instructions. Redirect hops are re-classified (`browser`/`http_batch`), MCP tool descriptions are scanned for injection at registration, and the MCP error channel is wrapped too. The danger classifier resists 8 known shell-evasion tricks (`$()`, backticks, `$IFS`, `command`/`exec`, `\rm`, basenamed absolute paths). Approvers engage friction mode after 3 same-class approvals in 60 s. Memory episodes from tainted sessions are stored but never auto-replayed. Skill auto-save tracks provenance and pins untrusted suggestions for explicit `odek skill promote`. `odek audit <session-id>` surfaces every ingest + per-turn divergence heuristic. Full threat model in [docs/SECURITY.md](docs/SECURITY.md).
 
 ### 🧩 Sub-Agent Delegation
 Parallel OS-process sub-agents via `delegate_tasks`. True isolation — each sub-agent is a fresh `odek subagent` process with its own config, tools, and termination timeout. Up to 8 concurrent workers. [docs/SUBAGENTS.md](docs/SUBAGENTS.md)

cmd/odek/injection_hardening_test.go

@@ -244,7 +244,7 @@ func TestBuiltinTools_SessionSearchWrappedAsUntrusted(t *testing.T) {
 	store, cleanup := seedSessionStore(t)
 	defer cleanup()
 
-	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 4, "", config.TranscriptionConfig{}, store)
+	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 4, "", config.TranscriptionConfig{}, config.VisionConfig{}, store)
 
 	var ss odek.Tool
 	for _, tool := range tools {

cmd/odek/main.go

@@ -779,7 +779,7 @@ func run(args []string) error {
 
 	// Sandbox setup
 	var sandboxCleanup func() error
-	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, resolved.Transcription, nil)
+	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, resolved.Transcription, resolved.Vision, nil)
 
 	// MCP server tools
 	var mcpCleanup func()
@@ -1054,7 +1054,7 @@ func setupSandbox(tools []odek.Tool, cfg sandboxConfig) (containerName string, c
 	return containerName, cleanup, nil
 }
 
-func builtinTools(dc danger.DangerousConfig, sm *skills.SkillManager, approver danger.Approver, maxConcurrency int, apiKey string, tc config.TranscriptionConfig, store *session.Store) []odek.Tool {
+func builtinTools(dc danger.DangerousConfig, sm *skills.SkillManager, approver danger.Approver, maxConcurrency int, apiKey string, tc config.TranscriptionConfig, vc config.VisionConfig, store *session.Store) []odek.Tool {
 	tools := []odek.Tool{
 		&shellTool{
 			dangerousConfig: dc,
@@ -1089,6 +1089,7 @@ func builtinTools(dc danger.DangerousConfig, sm *skills.SkillManager, approver d
 		&trTool{dangerousConfig: dc},
 		&wordCountTool{dangerousConfig: dc},
 		newTranscribeTool(dc, tc),
+		newVisionTool(dc, vc),
 		// session_search returns content from arbitrary past sessions —
 		// including sessions that ingested untrusted content. That path
 		// otherwise bypasses the memory taint gate and the audit log, so
@@ -1598,7 +1599,7 @@ func continueCmd(args []string) error {
 			"./.odek/skills",
 		)
 	}
-	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, resolved.Transcription, store)
+	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, resolved.Transcription, resolved.Vision, store)
 	var sandboxCleanup func() error
 
 	// MCP server tools

cmd/odek/main_test.go

@@ -203,7 +203,7 @@ func TestRun_NoAPIKey(t *testing.T) {
 }
 
 func TestBuiltinTools(t *testing.T) {
-	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 3, "", config.TranscriptionConfig{}, nil)
+	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 3, "", config.TranscriptionConfig{}, config.VisionConfig{}, nil)
 	if len(tools) == 0 {
 		t.Fatal("builtinTools() returned empty slice")
 	}

cmd/odek/mcp.go

@@ -73,7 +73,7 @@ Flags:
 	}
 
 	// Build tools
-	toolSet := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, config.TranscriptionConfig{}, nil)
+	toolSet := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, config.TranscriptionConfig{}, config.VisionConfig{}, nil)
 
 	// MCP server tools — connect and discover before sandbox
 	var mcpCleanup func()

cmd/odek/repl.go

@@ -77,7 +77,7 @@ func replCmd(args []string) error {
 			"./.odek/skills",
 		)
 	}
-	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, config.TranscriptionConfig{}, nil)
+	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, config.TranscriptionConfig{}, config.VisionConfig{}, nil)
 	var sandboxCleanup func() error
 
 	// MCP server tools

cmd/odek/schedule.go

@@ -570,7 +570,7 @@ func runTaskHeadless(ctx context.Context, resolved config.ResolvedConfig, system
 		resolved.Dangerous.NonInteractive = &deny
 	}
 
-	tools := builtinTools(resolved.Dangerous, nil, nil, resolved.MaxConcurrency, resolved.APIKey, resolved.Transcription, nil)
+	tools := builtinTools(resolved.Dangerous, nil, nil, resolved.MaxConcurrency, resolved.APIKey, resolved.Transcription, resolved.Vision, nil)
 	tools = append(tools, mcpTools...)
 
 	// Capture cumulative token usage from the final iteration so the Runner

cmd/odek/serve.go

@@ -267,7 +267,7 @@ func newServeAgent(resolved config.ResolvedConfig, system string, sendFn func(v
 	approver := newWSApprover(sendFn)
 	resolved.Dangerous.Approver = approver
 
-	tools := builtinTools(resolved.Dangerous, sm, approver, resolved.MaxConcurrency, resolved.APIKey, config.TranscriptionConfig{}, nil)
+	tools := builtinTools(resolved.Dangerous, sm, approver, resolved.MaxConcurrency, resolved.APIKey, config.TranscriptionConfig{}, config.VisionConfig{}, nil)
 
 	// Find the delegateTasksTool to wire up sub-agent log streaming
 	var subagentTool *delegateTasksTool

cmd/odek/subagent.go

@@ -291,7 +291,7 @@ func subagentCmd(args []string) error {
 			"./.odek/skills",
 		)
 	}
-	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, config.TranscriptionConfig{}, nil)
+	tools := builtinTools(resolved.Dangerous, sm, nil, resolved.MaxConcurrency, resolved.APIKey, config.TranscriptionConfig{}, config.VisionConfig{}, nil)
 	var sandboxCleanup func() error
 
 	// MCP server tools

cmd/odek/subagent_contract_test.go

@@ -320,7 +320,7 @@ func TestSubagent_ExitCodeThree(t *testing.T) {
 // ── 4. delegate_tasks Tool Schema ───────────────────────────────────
 
 func TestDelegateTasksTool_Exists(t *testing.T) {
-	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 3, "", config.TranscriptionConfig{}, nil)
+	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 3, "", config.TranscriptionConfig{}, config.VisionConfig{}, nil)
 	if len(tools) == 0 {
 		t.Fatal("builtinTools() returned empty slice")
 	}
@@ -338,7 +338,7 @@ func TestDelegateTasksTool_Exists(t *testing.T) {
 }
 
 func TestDelegateTasksTool_HasSchema(t *testing.T) {
-	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 3, "", config.TranscriptionConfig{}, nil)
+	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 3, "", config.TranscriptionConfig{}, config.VisionConfig{}, nil)
 
 	var tool odek.Tool
 	for _, t2 := range tools {
@@ -432,7 +432,7 @@ func TestDelegateTasksTool_HasSchema(t *testing.T) {
 }
 
 func TestDelegateTasksTool_Description(t *testing.T) {
-	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 3, "", config.TranscriptionConfig{}, nil)
+	tools := builtinTools(danger.DangerousConfig{}, nil, nil, 3, "", config.TranscriptionConfig{}, config.VisionConfig{}, nil)
 
 	var tool odek.Tool
 	for _, t2 := range tools {