#11990: Fix media understanding file path suppression + image tool bare-ID validation

## Summary - **Problem:** When media understanding pre-analyzes an image, `buildInboundMediaNote` fully strips the suppressed entry, removing the file path from the agent's context. If the LLM later needs the original image for follow-up analysis, it has no way to reference the file. It may then try using a message ID as an image reference, causing a noisy ENOENT error. - **Why it matters:** Agents lose the ability to do follow-up image analysis on pre-processed attachments, and bare numeric inputs cause confusing filesystem errors. - **What changed:** Suppressed media entries now render as `[media source: /path/to/file]` instead of being fully filtered. The image tool now validates bare numeric strings and returns a graceful error. - **What did NOT change (scope boundary):** No changes to media understanding itself, transcription flow, or any other channel-specific logic. ## Change Type (select all) - [x] Bug fix - [ ] Feature - [ ] Refactor - [ ] Docs - [ ] Security hardening - [ ] Chore/infra ## Scope (select all touched areas) - [ ] Gateway / orchestration - [x] Skills / tool execution - [ ] Auth / tokens - [ ] Memory / storage - [ ] Integrations - [ ] API / contracts - [ ] UI / DX - [ ] CI/CD / infra ## Linked Issue/PR - Closes #11989 ## User-visible / Behavior Changes - Suppressed media attachments now appear as `[media source: /path/to/file]` in the agent context instead of being fully removed, allowing follow-up image tool calls. - The image tool now returns a clear validation error when given a bare numeric string (e.g., a Discord message ID) instead of an ENOENT filesystem error. ## Security Impact (required) - New permissions/capabilities? No - Secrets/tokens handling changed? No - New/changed network calls? No - Command/tool execution surface changed? No — the image tool already validated inputs; this adds an earlier guard for a specific invalid input pattern. - Data access scope changed? No ## Repro + Verification ### Environment - OS: Windows 11 - Runtime/container: Node.js - Model/provider: Any - Integration/channel (if any): Discord (or any channel with media understanding) - Relevant config (redacted): Default media understanding enabled ### Steps 1. Send an image via Discord that triggers media understanding 2. Media understanding pre-analyzes the image and suppresses the attachment 3. Ask the agent a follow-up question that requires re-examining the original image ### Expected - The agent context includes `[media source: /path/to/file]` so the image tool can reference the original file - Bare numeric strings passed to the image tool return a clear validation error ### Actual (before fix) - `buildInboundMediaNote` fully filters out suppressed entries, removing the file path entirely - The image tool attempts `fs.readFile` on bare numeric strings, producing a noisy ENOENT error ## Evidence - [x] Failing test/log before + passing after - [ ] Trace/log snippets - [ ] Screenshot/recording - [ ] Perf numbers (if relevant) Tests added/updated: - `src/auto-reply/media-note.test.ts` — updated 2 existing tests, added 1 new test for all-suppressed case - `src/agents/tools/image-tool.e2e.test.ts` — added test for bare numeric string validation ## Human Verification (required) - Verified scenarios: Ran `vitest run src/auto-reply/media-note.test.ts` (6 passing) and `vitest run src/agents/tools/image-tool.e2e.test.ts` (15 passing). Typecheck passes. - Edge cases checked: All attachments suppressed (no unsuppressed entries), mixed suppressed/unsuppressed, transcribed audio not emitting media source lines, single unsuppressed entry formatting. - What you did **not** verify: Live end-to-end test with an actual Discord channel and media understanding provider. ## Compatibility / Migration - Backward compatible? Yes - Config/env changes? No - Migration needed? No ## Failure Recovery (if this breaks) - How to disable/revert this change quickly: Revert this PR - Files/config to restore: `src/auto-reply/media-note.ts`, `src/agents/tools/image-tool.ts` - Known bad symptoms reviewers should watch for: Media source lines appearing unexpectedly in agent context, or image tool rejecting valid numeric file names (unlikely — real image files have extensions) ## Risks and Mitigations None