🤖 AI-assisted (built with Codex via Hermes orchestration). Test level: lightly tested. Prompt summary available on request.

Summary

• Problem: When a non-visual model is configured with a separate image understanding model, the ACP dispatch path fails to invoke the media understanding pipeline because applyMediaUnderstanding is called without the agentDir parameter. Without agentDir, the pipeline cannot locate agent-specific models.json and auth profiles, so image understanding silently falls back to raw content.
• Why it matters: Users with multi-agent setups and non-visual models (e.g., MiniMax-M2.7) configured with image understanding models cannot process images through the ACP path — the pipeline silently does nothing.
• What changed: Added agentDir: resolveAgentDir(params.cfg, acpAgentId) to the applyMediaUnderstanding call in dispatch-acp.ts, aligning it with the non-ACP reply path in get-reply.ts which already passes agentDir correctly.
• What did NOT change (scope boundary): No changes to the media understanding pipeline itself, no changes to the non-ACP reply path, no changes to auth profile resolution logic.

Change Type (select all)

• Bug fix

Scope (select all touched areas)

• Agent loop / reply pipeline

Linked Issue/PR

• Closes [Bug]: Media Understanding Pipeline is not working for non-visual models #55046
• This PR fixes a bug or regression

Root Cause

• Root cause: dispatch-acp.ts calls applyMediaUnderstanding({ ctx, cfg }) without the optional agentDir parameter. When agentDir is missing, the media understanding pipeline falls back to resolveOpenClawAgentDir() which requires the OPENCLAW_AGENT_DIR environment variable — absent in most setups. Without it, the pipeline cannot find models.json or auth credentials for the configured image understanding model.
• Missing detection / guardrail: The non-ACP path (get-reply.ts) already passes agentDir correctly (line 250), but the ACP path was not updated to match when media understanding support was added to it.
• Contributing context: The agentDir parameter is optional in applyMediaUnderstanding's signature, so the omission does not cause a type error — it silently degrades.

Regression Test Plan

• Coverage level that should have caught this:
  • Unit test
• Target test or file: src/auto-reply/reply/dispatch-acp.test.ts
• Scenario the test should lock in: An ACP dispatch turn with inbound media should pass the agent-scoped directory to the media understanding call.
• Why this is the smallest reliable guardrail: The existing test mocks applyMediaUnderstanding as a pass-through; adding an argument assertion would verify agentDir is forwarded.
• Existing test that already covers this (if any): N/A — dispatch-acp tests do not currently exercise the media understanding path.
• If no new test is added, why not: The existing test infrastructure mocks the entire media understanding module; the fix is a 1-line parameter addition that aligns with the already-tested get-reply.ts path. The applyMediaUnderstanding function's internal use of agentDir is covered by src/media-understanding/apply.ts tests.

User-visible / Behavior Changes

• Image understanding now works correctly for non-visual models in ACP dispatch sessions (e.g., MiniMax-M2.7 with a configured image understanding model). Previously, images were silently passed as raw content without description.

Diagram (if applicable)

N/A

Security Impact (required)

• New permissions/capabilities? No
• This fix passes the same agentDir that is already used in the non-ACP path. No new file access, no new permissions — just consistent behavior between the two reply paths.