As a user, I want AI to guide me about credit consumption when I use Imagify MCP so that I am not blocked without being assisted

[MathieuLamiot]

Context

Imagify 2.3.1 MCP abilities can consume user's credits fast. We must ensure the user experience remains good and they don't get out of quota without knowgly triggering it.

Expected behavior

TBD @raahulbasu

Acceptance Criteria

TBD @raahulbasu

[raahulbasu]

Expected Behavior

When an MCP operation may consume Imagify credits, users should understand the impact before the action is executed. The AI assistant should guide users through the decision; helping them make an informed choice rather than unexpectedly consuming their available quota.

Acceptance Criteria

• Users are informed when a requested operation may consume Imagify credits.
• The expected action is clearly explained before execution.
• Credit-consuming operations require explicit user confirmation before they begin.
• If the operation cannot proceed (e.g. insufficient credits), the AI clearly explains why and suggests the next step.
• The AI clearly communicates whether the operation was started successfully or why it could not be completed.

[Honemo]

Note

Generated by the AI delivery pipeline (grooming-agent · claude-sonnet-5).

Grooming Plan — Issue #1178 (Plan v1)

Approach: Gate the three quota-consuming MCP abilities (imagify/optimize-media, imagify/bulk-optimize, imagify/generate-missing-nextgen) behind a shared AbstractAbility::guard_credit_confirmation() template method. Since a single MCP tool call cannot pause mid-flight for a human confirmation dialog, "explicit confirmation" is implemented as a two-call protocol pattern: the first call (no confirm argument) returns a confirmation_required preview describing the expected impact and current quota; a second call with confirm: true re-checks quota/API-key validity and only then executes. If quota is already exhausted, the ability returns insufficient_quota with the next quota-reset date and an upgrade URL instead of attempting the spend. RestoreMedia, UpdateSettings, and the read-only Get* abilities are unaffected — none of them consume Imagify quota.

Effort: M · Risk: MEDIUM · Complexity: MEDIUM

Key decisions (confirmed by the assignee):

• New CreditConsumingAbilityInterface + a shared guard on AbstractAbility avoid duplicating the confirmation/quota logic three times.
• BulkOptimize and GenerateMissingNextgen will be migrated to extend AbstractAbility (currently implement AbilitiesInterface directly, unlike OptimizeMedia/GetAccount), so all three share the guard and also gain the existing imagify_mcp_ability_executed/imagify_mcp_permission_denied tracking hooks for free.
• The preview must show an exact "images remaining vs. total images" count for BulkOptimize and GenerateMissingNextgen — no count: null fallback. If no existing cheap query provides this for a given context, a minimal read-only count query is added rather than skipping the requirement.
• Reuses existing Imagify_Requirements::is_over_quota() / is_api_key_valid() and Imagify\User\User quota fields — no new "credit cost" model is invented; Imagify quota is tracked as a monthly MB percentage, not a fixed per-image credit.

Relevant files: classes/Abilities/AbstractAbility.php, classes/Abilities/OptimizeMedia.php, classes/Abilities/BulkOptimize.php, classes/Abilities/GenerateMissingNextgen.php, new classes/Abilities/CreditConsumingAbilityInterface.php, docs/api/mcp.md.

Test plan: Targeted unit tests for the new guard (insufficient_quota / invalid_api_key / confirmation_required / pass-through-on-confirm paths) plus regression coverage on the three abilities' existing success/error paths, and integration tests asserting the new confirm input field, the exact remaining/total impact fields, and the expanded status enum are registered correctly.
composer test-unit -- --filter="AbstractAbility|OptimizeMedia|BulkOptimize|GenerateMissingNextgen" && composer test-integration -- --filter="OptimizeMedia|BulkOptimize|GenerateMissingNextgen"

Full spec: .ai/issues/1178/spec.md

[Honemo]

Note

Generated by the AI delivery pipeline (orchestrator · Claude Sonnet 5).

PR: #1185 | Status: READY FOR REVIEW

Stage	Result	Notes
Grooming	✅	effort: L, risk: MEDIUM (4 revision rounds to resolve challenger-found bugs before implementation)
Challenger	✅ Approved (after 3 revision loops)	fixed: wrong stats source, wrong count-source functions, understated migration effort, missing DI wiring, private-method callable-visibility bug
Implementation	✅	branch: enhancement/1178-ai-guides-credit-consumption
DOD L2	✅ PASS (after 1 fix)	PR "What was tested" section filled in — no code issues found
Lead Review	✅ PASS	details on PR #1185
CI	✅ All Pass	Codacy gates show non-blocking ACTION_REQUIRED (not required checks)
QA	✅ PASS	all 5 acceptance criteria verified live; details on PR #1185
Follow-up tickets	#1186	cosmetic label/count consistency in preview responses

[MathieuLamiot]

@raahulbasu Should we bypass the warning/validation step when the user is Infinite (unlimited quota)?
@Miraeld @Honemo I'm not sure this is taken into account in the current PR?

[Miraeld]

Umm, if I may add my thought on your question @MathieuLamiot

First, the user plan isn't taken into consideration. So your suspicion is right.

I agree the quota protection purpose of this feature is meaningless for Infinite Users. However, if an AI agent triggers bulk-optimize on thousands of images, it is still an heavy process, hard-to-undo operation regardless of plan (server load, re-compression of the whole library).

So a full bypass for Infinite users would remove a useful safety net for the most destructive abilities.
I would say: keep the confirmation step for everyone, but adapt the messaging for Infinite accounts: drop the quota-consumption wording and quota_remaining, and say something like "This will re-optimize N of M images. Add confirm: true to proceed."

It is a cheap change: one $user->is_infinite() branch in confirmation_required_response(). What do you think @MathieuLamiot @raahulbasu

PS: Current PR is Ready for QA. Either we do a follow up issue for this or we put back this PR in progress. Your call.

[MathieuLamiot]

would say: keep the confirmation step for everyone, but adapt the messaging for Infinite accounts: drop the quota-consumption wording and quota_remaining, and say something like "This will re-optimize N of M images. Add confirm: true to proceed."

sounds good to me 👍
Moving it back to In Progress, and let's also have @raahulbasu 's confirmation on the copy.

[raahulbasu]

Thanks @Miraeld @MathieuLamiot I think its good to have the confirmation step for everyone.
For Infinite users, we can simply remove the credit messaging and focus on what the operation will do. The confirmation is still valuable for large or irreversible actions.