Summary

• Problem: the image and PDF tools looked up models in the Pi registry using raw provider/model refs instead of the normalized refs the rest of the runtime uses.
• Why it matters: valid configured Ollama vision models could be rejected as Unknown model, which broke the built-in image tool and the PDF path that shares the same lookup helper.
• What changed: resolveModelFromRegistry() now normalizes the provider/model pair before registry lookup and error reporting, and a focused unit test locks that seam in.
• What did NOT change (scope boundary): I did not carry the auth helper refactor from fix(tools): normalize model reference before registry lookup #66165, because it introduced real PDF-tool breakage and was unrelated to the actual lookup bug.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes image tool returns 'Unknown model' for configured ollama models with image input #59943
• Related fix(tools): normalize model reference before registry lookup #66165
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: src/agents/tools/media-tool-shared.ts called modelRegistry.find() with raw tool-path refs, while the discovered-model registry expects the same normalized provider/model identity used elsewhere.
• Missing detection / guardrail: there was no direct unit test around the shared media-tool registry lookup helper, so a normalization mismatch could slip through without tripping tool tests.
• Contributing context (if known): src/media-understanding/image.ts already normalized before registry lookup; the shared media-tool helper had drifted from that working pattern.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/tools/media-tool-shared.model-resolution.test.ts
• Scenario the test should lock in: the helper normalizes the provider/model ref before registry lookup and reports misses with the normalized ref.
• Why this is the smallest reliable guardrail: it exercises the exact shared seam used by both image and PDF tools without needing full tool/runtime setup.
• Existing test that already covers this (if any): nearby image/PDF tool suites verify the surrounding paths still stay green.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• Configured Ollama vision models stop failing the built-in image/PDF tool lookup with Unknown model when the ref only differs by normalization.

Diagram (if applicable)

Before:
[tool config ref] -> resolveModelFromRegistry -> raw modelRegistry.find(provider, model) -> Unknown model

After:
[tool config ref] -> resolveModelFromRegistry -> normalizeModelRef(...) -> modelRegistry.find(normalized provider, normalized model)

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS 26.4 local maintainer worktree
• Runtime/container: Node 22+, pnpm
• Model/provider: Ollama vision-model lookup path
• Integration/channel (if any): built-in image/PDF tools
• Relevant config (redacted): configured image-model / PDF shared lookup path

Steps

1. Resolve a configured image/PDF tool model through the shared media-tool helper.
2. Ensure the helper normalizes the ref before hitting the registry.
3. Verify the surrounding image/PDF tool suites still pass.

Expected

• Valid configured models resolve from the registry after normalization.

Actual

• Before this change, the shared helper used the raw ref and could throw Unknown model even when the configured model existed.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios: pnpm test:serial src/agents/tools/media-tool-shared.test.ts src/agents/tools/media-tool-shared.model-resolution.test.ts; pnpm test:serial src/agents/tools/image-tool.test.ts src/agents/tools/pdf-tool.test.ts src/agents/tools/pdf-tool.model-config.test.ts src/agents/tools/pdf-tool.model-catalog.test.ts src/agents/tools/pdf-tool.helpers.test.ts; pnpm build
• Edge cases checked: the shared helper now reports misses with the normalized ref, and nearby image/PDF suites stayed green.
• What you did not verify: I did not run a live Ollama image-tool invocation end-to-end.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: the helper now relies on the standard model-ref normalization path before lookup.
  • Mitigation: this mirrors the existing media-understanding lookup path and is covered by both a new unit seam test and the surrounding tool suites.