🤖 refactor: remove experimental image tools

[ThomasK33]

Summary

Remove the failed experimental Image Tools feature from Mux. This deletes the image_generate / image_edit tools, the Image Tools experiment/config UI, generated-image transcript presentation, image-tool backend runtime wiring, the built-in imagegen skill, and the related ADR/docs entries while preserving generic image attachment, screenshot, lightbox, and token metadata support.

Background

We experimented with Image Tools in Mux, but we were not happy with how the first implementation turned out, and the value from the feature was not clear enough to keep carrying it forward right now.

We're not opposed to having image tools in the future, but this first iteration was not good enough, so this PR removes the experiment.

Closes #3270

Implementation

• Removed the Image Tools experiment from settings, send options, persisted task experiment schemas, and stream options.
• Removed image tool definitions, runtime implementations, image artifact helpers, provider image-model creation paths, and generated/edited image display rows.
• Removed imagegen-specific built-in skill filtering and regenerated the built-in skill snapshot after deleting the imagegen skill and image ADR docs.
• Left generic image surfaces intact: attachments, screenshots, ToolResultImages, ImageLightbox, raster resizing, and upstream token/model metadata.

Validation

• make static-check
• Targeted tests for tool definitions, config/API schemas, stream context, agent skill loading, message rendering/aggregation, provider model factory, and model stats.
• Dogfooded a clean dev-server sandbox and verified Settings → Experiments no longer shows Image Tools or image model/upload controls.

Pains

• make test was attempted locally; it did not complete cleanly because of unrelated existing/suite-order failures. The previously failing hook and UI tests passed in isolation, while WorkspaceService fork > cleans up init state when orchestrateFork rejects reproduced independently of this change.

Risks

Low-to-medium. This removes a product experiment and many direct callsites; old persisted image tool outputs now render as generic tool rows rather than first-class image preview rows. Generic image attachment/screenshot previews were intentionally preserved.

---

📋 Implementation Plan

Plan: remove failed Image Tools experiment and close PRD issue

Context and evidence

• User intent: treat the Image Tools experiment as failed, remove Image Tools/image-tool-related code from Mux first, then comment on and close the related GitHub PRD issue.
• GitHub PRD issue found: 🤖 feat: PRD experimental image generation tool #3270 — 🤖 feat: PRD experimental image generation tool in coder/mux, currently open with no comments. Evidence: issue body explicitly describes the experimental image_generate tool, Settings-configured image model, generated-image transcript display, temporary artifacts, usage reporting, provider policy enforcement, and /imagegen skill.
• Repo investigation found the implementation spans experiment config, send-option plumbing, tool definitions/implementations, backend stream/tool registration, built-in skill filtering, model/config schemas, Settings UI, message rendering, stories/tests, and docs/ADRs.
• Constraint: do not remove existing generic image support used outside this experiment, such as image attachments, screenshot previews, ToolResultImages, ImageLightbox, and raster resize utilities.
• Public GitHub update constraint: before closing/commenting, check MUX_MODEL_STRING, MUX_THINKING_LEVEL, and MUX_COSTS_USD; include the repository-required mux attribution footer in the issue close comment.

Recommended approach

Surgical full removal of the experiment and its direct product surfaces. Remove the feature rather than leaving it hidden behind a flag, while preserving unrelated image attachment/screenshot functionality.

• Estimated product-code net LoC: approximately -1,800 to -2,500 LoC.
  • Excludes tests and docs from the estimate.
  • Includes deletion of image tool implementations/artifact helpers, image-tool types/utilities, Settings UI, generated-image transcript UI, built-in imagegen skill, and config/stream/tool-registration plumbing.

Implementation phases

1. Remove experiment/config surfaces

1. Remove the Image Tools experiment entry from src/common/constants/experiments.ts.
2. Remove imageGenerationTool send-option plumbing from:
   • src/browser/utils/messages/sendOptions.ts
   • src/browser/utils/messages/buildSendMessageOptions.ts
   • src/browser/hooks/useSendMessageOptions.ts
   • src/common/schemas/project.ts
   • src/common/orpc/schemas/stream.ts
   • src/node/services/taskService.ts
3. Remove imageGeneration project/app config surfaces from:
   • src/common/types/project.ts
   • src/common/types/imageGeneration.ts (delete if no longer referenced)
   • src/common/config/schemas/appConfigOnDisk.ts
   • src/common/orpc/schemas/api.ts
   • src/node/config.ts
   • src/node/orpc/router.ts
4. Preserve compatibility with existing on-disk config by confirming schema behavior; if unknown keys are rejected, keep a small defensive parse/drop path so old imageGeneration config does not brick startup.

2. Remove image tool definitions and runtime tools

1. Delete direct image-tool implementation files:
   • src/node/services/tools/image_generate.ts
   • src/node/services/tools/image_edit.ts
   • src/node/services/tools/imageArtifacts.ts
2. Remove image tool definition entries and schemas from:
   • src/common/utils/tools/tools.ts
   • src/common/utils/tools/toolDefinitions.ts
   • src/common/types/tools.ts
3. Delete image-tool result helper if no remaining non-test imports exist:
   • src/common/utils/imageGenerationToolResult.ts
4. Remove image_generate/image_edit from available-tool calculations and model/tool registration.
5. Remove image-specific output redaction branches from src/browser/utils/messages/applyToolOutputRedaction.ts only if they exclusively served these removed tools.

3. Remove backend stream and skill gating

1. In src/node/services/aiService.ts, remove image-generation experiment availability calculation and stop passing image runtime/editing options into getToolsForModel.
2. In src/node/services/streamContextBuilder.ts, remove imageGenerationToolAvailable option and imagegen skill filtering.
3. In src/node/services/agentSession.ts and src/node/services/agentSkills/agentSkillsService.ts, remove built-in imagegen availability/filtering logic.
4. Delete the built-in skill file src/node/builtinSkills/imagegen.md.
5. Keep generic agent skill mechanisms intact; only remove the imagegen special case.

4. Remove UI/product presentation

1. Delete src/browser/features/Settings/Sections/ImageGenerationExperimentConfig.tsx.
2. Update src/browser/features/Settings/Sections/ExperimentsSection.tsx and related stories/mocks to remove the special Image Tools configuration block.
3. Delete src/browser/features/Messages/GeneratedImageMessage.tsx if generated-image messages are only produced by removed tools.
4. Update src/browser/features/Messages/MessageRenderer.tsx, message builders, stories, and tests to remove generated-image transcript handling tied to image tools.
5. Keep src/browser/components/ImageLightbox.tsx and src/browser/features/Tools/Shared/ToolResultImages.tsx because they support non-image-tool features like attach_file, desktop screenshots, and generic tool result image previews.

5. Remove docs/tests/stories tied to the experiment

1. Delete image-tool-specific tests alongside deleted implementation files:
   • src/node/services/tools/image_generate.test.ts
   • src/node/services/tools/image_edit.test.ts
   • src/common/types/imageGeneration.test.ts
   • src/common/utils/imageGenerationToolResult.test.ts
2. Update tests for changed behavior:
   • src/common/utils/tools/toolDefinitions.test.ts
   • src/node/services/streamContextBuilder.test.ts
   • src/node/services/agentSession.agentSkillSnapshot.test.ts
   • src/node/services/tools/agent_skill_read.test.ts
   • src/node/services/tools/agent_skill_read_file.test.ts
   • src/browser/features/Messages/MessageRenderer.test.tsx
   • src/browser/utils/messages/StreamingMessageAggregator.test.ts
   • src/browser/utils/messages/applyToolOutputRedaction.test.ts
3. Remove or regenerate docs sections for removed tools:
   • docs/hooks/tools.mdx image tool entries
   • docs/config/models.mdx experimental image tools model section
   • docs/adr/0001-experimental-image-generation-tool.md
   • docs/adr/0002-image-editing-visual-mockups.md
   • docs/docs.json ADR navigation entries
   • src/node/builtinSkills/mux-docs.md references to removed image ADRs
4. Be conservative with image model metadata (models.json, token stats, provider factory): remove image-model-only factory/config code only if it is exclusively reachable from the removed tools; otherwise leave model catalog entries alone unless validation shows they are dead or user-facing inappropriately.

Validation and quality gates

Gate A: static and targeted automated checks after code removal

Run targeted tests first to catch local fallout:

bun test src/common/utils/tools/toolDefinitions.test.ts
bun test src/common/config/schemas/appConfigOnDisk.test.ts src/common/orpc/schemas/api.test.ts
bun test src/node/services/streamContextBuilder.test.ts src/node/services/agentSession.agentSkillSnapshot.test.ts
bun test src/node/services/tools/agent_skill_read.test.ts src/node/services/tools/agent_skill_read_file.test.ts
bun test src/browser/features/Messages/MessageRenderer.test.tsx src/browser/utils/messages/StreamingMessageAggregator.test.ts src/browser/utils/messages/applyToolOutputRedaction.test.ts
bun test src/node/services/providerModelFactory.test.ts

Then run repository-wide checks:

make typecheck
make lint
make fmt-check
make test

If time or environment prevents the full suite, at minimum run make typecheck, make lint, make fmt-check, and all targeted tests above; report any blocker exactly.

Gate B: search-based removal audit

Run read-only audits and resolve any remaining direct product references:

rg -n "image_generate|image_edit|imagegen|imageGeneration|IMAGE_GENERATION|ImageGeneration|GeneratedImageMessage|image-generation-tool|Image Tools" src docs tests || true

Expected remaining hits, if any, should be explicitly justified as unrelated generic image attachment/screenshot support or historical external references. Do not remove generic image attachment/resizing/lightbox code unless the audit proves it exists only for the failed experiment.

Dogfooding / self-verification

Skill-backed workflow notes:

• Use make dev-server-sandbox rather than a shared dev server so the run gets a temporary MUX_ROOT, copied provider/project config when available, free BACKEND_PORT/VITE_PORT, and sandbox-safe host settings.
• Use the direct agent-browser binary, never npx agent-browser.
• Before browser automation, load the installed CLI's current browser workflow with agent-browser skills get core (or --full if command details are needed), because the global agent-browser skill is only a discovery stub.
• Store dogfood evidence under a dedicated output directory such as dogfood-output/image-tools-removal/ with screenshots/, videos/, and a short report.

Concrete dogfood pass:

1. Start the sandboxed app server:

   make dev-server-sandbox

   If the dogfood pass should avoid copying existing user projects/providers, use:

   make dev-server-sandbox DEV_SERVER_SANDBOX_ARGS="--clean-providers --clean-projects"

2. Initialize dogfood artifacts and a named browser session:

   mkdir -p dogfood-output/image-tools-removal/screenshots dogfood-output/image-tools-removal/videos
   agent-browser skills get core
   agent-browser --session image-tools-removal open <sandbox-url>
   agent-browser --session image-tools-removal wait --load networkidle
   agent-browser --session image-tools-removal screenshot --annotate dogfood-output/image-tools-removal/screenshots/initial.png
   agent-browser --session image-tools-removal snapshot -i

3. Open Settings and verify:

   • The Image Tools experiment no longer appears.
   • No image generation model/editor controls appear.
   • Other experiment toggles still render and can be changed.
   • Capture an annotated screenshot of the Settings state.

4. Open a workspace/chat and verify:

   • Available tools no longer include image_generate or image_edit.
   • /imagegen or imagegen built-in skill is no longer listed/readable.
   • Normal text chat still sends.
   • Capture screenshots before and after sending a normal message.

5. Verify generic image functionality still works:

   • Attach or paste an image into a prompt if that feature exists in the current dev build.
   • Confirm desktop screenshot/generic image tool result previews still render through existing image preview components.
   • Capture screenshots of the generic image path to prove this unrelated functionality survived.

6. Record reviewer video evidence for the happy path:

   agent-browser --session image-tools-removal record start dogfood-output/image-tools-removal/videos/removal-happy-path.webm
   # Navigate Settings -> chat/tool checks -> normal send at human pace.
   agent-browser --session image-tools-removal record stop

7. During the pass, check browser health after major pages/actions:

   agent-browser --session image-tools-removal errors
   agent-browser --session image-tools-removal console

8. Close the session and include artifact paths in the final implementation report:

   agent-browser --session image-tools-removal close

GitHub issue closure plan

Preferred flow: do not manually close issue #3270 before merge. Instead, put the rationale and a GitHub closing keyword in the PR body so the issue auto-closes when the removal PR is merged into the default branch.

1. Check attribution environment variables before creating/updating the PR body:

printf 'model=%s\nthinking=%s\ncosts=%s\n' "$MUX_MODEL_STRING" "$MUX_THINKING_LEVEL" "$MUX_COSTS_USD"

2. Include a PR body section equivalent to:

## Issue closure

We experimented with Image Tools in Mux, but we were not happy with how the first implementation turned out, and the value from the feature was not clear enough to keep carrying it forward right now.

We're not opposed to having image tools in the future, but this first iteration was not good enough, so this PR removes the experiment.

Closes #3270

3. Keep the normal PR attribution footer in the PR body, using the values from MUX_MODEL_STRING, MUX_THINKING_LEVEL, and MUX_COSTS_USD:

---

_Generated with `mux` • Model: `<modelString>` • Thinking: `<thinkingLevel>` • Cost: `$<costs>`_

<!-- mux-attribution: model=<modelString> thinking=<thinkingLevel> costs=<costs> -->

4. Only fall back to an explicit gh issue close 3270 --reason "not planned" --comment ... if the user decides not to use a PR, the PR is not targeting the default branch, or GitHub automatic issue closing is disabled for the repository.

Acceptance criteria

• Image Tools experiment is removed from Settings, config, send options, backend streaming, tool registration, built-in skills, generated-image transcript UI, and docs.
• image_generate and image_edit are unavailable and no longer appear in tool definitions, available-tool lists, or model runtime wiring.
• Existing generic image attachments/screenshots/previews remain functional.
• Targeted tests and static checks pass, or any environmental blocker is reported precisely.
• Dogfooding evidence includes screenshots and a short video recording.
• The PR body contains the requested rationale plus Closes #3270, so GitHub closes the PRD issue automatically when the removal PR merges into the default branch; no manual issue close happens beforehand unless that fallback is needed.

---

Generated with mux • Model: openai:gpt-5.5 • Thinking: xhigh • Cost: $51.46

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[ThomasK33]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e29321bb2f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Mux	🟢 Ready	View Preview	May 29, 2026, 12:59 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[ThomasK33]

Addressed Codex finding PRRT_kwDOPxxmWM6Fr1WI: restored a small legacy provider-bound scrubber in applyToolOutputRedaction so old persisted image tool payloads still drop thumbnails and source.resolvedPath before history is replayed to providers. Added a regression test covering both nested code_execution.toolCalls results and nestedCalls.

[ThomasK33]

@codex review

Please take another look.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Keep it up!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".