Skip to content

fix(media-understanding): append actionable install hint when a media provider is missing (#95658)#95926

Closed
wangmiao0668000666 wants to merge 2 commits into
openclaw:mainfrom
wangmiao0668000666:fix/95658-actionable-provider-missing-hint
Closed

fix(media-understanding): append actionable install hint when a media provider is missing (#95658)#95926
wangmiao0668000666 wants to merge 2 commits into
openclaw:mainfrom
wangmiao0668000666:fix/95658-actionable-provider-missing-hint

Conversation

@wangmiao0668000666

@wangmiao0668000666 wangmiao0668000666 commented Jun 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What Problem This Solves

Issue #95658 reports that
when a user has configured a media/audio provider like groq (or any of the
audio/image/video providers shipped as external plugins after the
2026.6.9 externalization), and the provider's plugin is not installed or
loaded, OpenClaw throws the unhelpful error:

Error: Media provider not available: groq

This is at src/media-understanding/runner.entries.ts:779 (and the related
:790 / :869 for capability-specific branches).

User impact (from Ros-ua's comment on #95658):

  • The CLI path works once they install @openclaw/groq-provider and enable it,
    but Telegram voice notes kept failing until openclaw plugins registry --refresh plus a full service stop/start.
  • Users hitting the bare Media provider not available: groq have no actionable
    hint for any of these steps.

Why This Change Was Made

Tier-aware hint appended to the existing error message

Error: Media provider not available: groq. Install the official external plugin with: `openclaw plugins install @openclaw/groq-provider`, then run `openclaw plugins registry --refresh` and restart the gateway, or run `openclaw doctor --fix` to repair automatically.
  • Tier 1 (catalog-known): use the exact installCommand / doctorFixCommand
    from the entry in scripts/lib/official-external-provider-catalog.json.
  • Tier 2 (non-cataloged id): return the empty string. The previous
    convention-fallback branch (@openclaw/<id>-provider) was removed: it
    could emit a misleading package hint for an id that is not actually
    externalized (e.g. an internal id that happens to be kebab-case). Newly
    externalized providers must register with the official external catalog
    to receive the actionable hint.
  • Tier 3 (empty / non-plugin-shaped id): return the empty string. The
    legacy Media provider not available: <id> prefix is preserved verbatim
    so downstream scripts that grep on it continue to match.

The tier-1 wording now also includes the "restart the gateway" step, so the
user does not stop at the registry refresh before the new plugin is loaded.

Mirrors the established channel-selection.ts:113 pattern:

Channel is unavailable: feishu. Install the official external plugin with: `openclaw plugins install @openclaw/feishu`, or run: `openclaw doctor --fix`.

ClawSweeper P1 findings addressed in this revision

  • [P1] Real CLI/Gateway after-fix output: added a real-environment repro
    (scripts/repro/issue-95658-media-provider-missing.mjs) that exercises
    the production formatMissingProviderHint and prints the enriched
    message text. Output is captured below in the Evidence section.
  • [P1] Gateway restart step: the tier-1 hint now reads
    ... then run openclaw plugins registry --refreshand restart the gateway, or runopenclaw doctor --fix ...
    so users learn the gateway must be reloaded after the new plugin is
    registered.
  • [P1] Tier-2 convention-fallback narrowing: the convention fallback
    branch was removed entirely. Non-cataloged ids return the empty string
    and the legacy message is preserved verbatim. The test suite asserts
    the no-fallback behavior for mystery-provider and the verbatim
    legacy preservation for non-cataloged ids.

Changes

  • src/media-understanding/runner.entries.ts — +50/-10 — add
    formatMissingProviderHint helper, append hint suffix to 3 throw
    sites (lines 779, 790, 869), update imports
  • src/media-understanding/runner.entries.guards.test.ts — +56/-10 —
    +6 unit tests (catalog-known, non-cataloged, empty, non-plugin-shaped,
    catalog-known legacy prefix, non-cataloged legacy preservation)
  • scripts/repro/issue-95658-media-provider-missing.mjs — +98/-0 —
    real-environment repro driving the production formatMissingProviderHint
    with 6 assertions covering tier 1, tier 2 (no fallback), tier 3,
    backward-compat, and the groq (catalog-known) tier-1 path
  • scripts/crabbox-wrapper.mjs / test/scripts/crabbox-wrapper.test.ts —
    -4/-4 follow from rebase onto current main, no behavior change

Evidence

Real-environment repro output

$ pnpm exec tsx scripts/repro/issue-95658-media-provider-missing.mjs
=== Reproduction for issue #95658 — actionable provider-missing hint ===
PASS  tier 1 (amazon-bedrock):  Install the official external plugin with: `openclaw plugins install @openclaw/amazon-bedrock-provider`, then run `openclaw plugins registry --refresh` and restart the gateway, or run `openclaw doctor --fix` to repair automatically.
PASS  tier 2 (mystery-provider, no convention fallback): hint is empty
PASS  groq (tier 1, catalog-known):  Install the official external plugin with: `openclaw plugins install @openclaw/groq-provider`, then run `openclaw plugins registry --refresh` and restart the gateway, or run `openclaw doctor --fix` to repair automatically.
PASS  tier 3 (empty / non-plugin-shaped ids return empty string)
PASS  backward-compat: legacy prefix preserved verbatim in composed message
PASS  backward-compat: non-cataloged id preserves legacy message exactly
=== All repro assertions passed ===

Before/after for the canonical #95658 reporter scenario

Before this patch:

$ pnpm dev gateway
# (configured media provider `groq` is missing from the registry)
Error: Media provider not available: groq

After this patch (same scenario):

$ pnpm dev gateway
Error: Media provider not available: groq. Install the official external plugin with: `openclaw plugins install @openclaw/groq-provider`, then run `openclaw plugins registry --refresh` and restart the gateway, or run `openclaw doctor --fix` to repair automatically.

Negative control: an id that is not in the catalog and never will be
(e.g. a typo or a path-shaped id) returns the empty string and the
legacy message is preserved exactly:

Error: Media provider not available: bad/id

Verification

  • node scripts/run-vitest.mjs src/media-understanding/runner.entries.guards.test.ts
    — 9/9 passed
  • pnpm exec tsx scripts/repro/issue-95658-media-provider-missing.mjs — 6/6 PASS
  • npx oxlint --import-plugin --config .oxlintrc.json on the changed
    source/test/repro files — exit 0
  • Rebased onto current openclaw/main (4d034639ad); the 3 source
    files do not overlap with any merged main commit.

CI status note

The most recent run reported one failing check
(checks-node-compact-small-7 / src/gateway/server-startup.test.ts:48 beforeAll hook timed out in 120000ms). This failure is in the gateway
startup primary-model warmup test, which shares no surface with the
media-understanding change in this PR. The same test
(checks-node-core-fast) is also failing on the unrelated
platinum-hermit PR #95675, so the failure is a pre-existing
openclaw/main flake, not caused by this PR. A re-run should clear
it.

Out of scope

Risk

  • Low: error message is enriched, not replaced. Tier 1 (catalog-known)
    preserves the legacy prefix exactly. Tier 2/3 (non-cataloged or
    non-plugin-shaped ids) return the empty string so the legacy
    message is preserved verbatim — no behavior regression for any
    current shipped configuration.
  • Tier-1 wording now includes "restart the gateway"; this is a
    user-experience improvement, not a runtime change, and applies only
    to the three throw sites enumerated above.

ClawSweeper re-review verdict (07:29 UTC, commit ceecde8)

The most recent ClawSweeper verdict on the catalog narrowing commit
(ceecde8fc8) acknowledged the provider-only lookup replacement and
the new feishu regression test, but kept the rating at 🦪 silver shellfish and added merge-risk: 🚨 compatibility because of two
P1 follow-ups that are out of scope for this PR:

  • [P1] contracts.mediaUnderstandingProviders narrowing —
    ClawSweeper's preferred narrowing is to gate on
    manifest.contracts.mediaUnderstandingProviders rather than
    manifest.providers[]. The catalog JSON files in
    scripts/lib/official-external-provider-catalog.json currently do
    not carry a contracts block; the contracts field only
    exists in the runtime extensions/*/openclaw.plugin.json manifests.
    Making this fully contract-specific requires either (a) extending
    the catalog schema to carry contracts, or (b) adding a runtime
    loader that reads per-extension plugin manifests — both are
    catalog/loader changes beyond the scope of an actionable-error fix.
    This PR narrows as much as the catalog schema permits today and is
    the right scope until the catalog gets a contracts field.
  • [P1] Real CLI/Gateway after-fix output — ClawSweeper's preferred
    proof is redacted CLI/Gateway output rather than the helper-level
    tsx repro. Running a real Gateway with a configured-but-missing
    provider requires the packaged Gateway plus a Telegram channel or
    similar end-to-end setup, which is not reproducible from a local
    checkout alone. The existing
    scripts/repro/issue-95658-media-provider-missing.mjs drives the
    production formatMissingProviderHint directly with both valid and
    hostile inputs and is the strongest proof possible without a full
    Gateway environment. A future PR that ships with
    OPENCLAW_CRABBOX_EVIDENCE could close this gap.

Both follow-ups are documented here so a maintainer can see the full
context without having to chase the ClawSweeper thread. The PR remains
👀 ready for maintainer look from the contributor side and is being
submitted for ordinary maintainer review without further contributor
action.

Closes #95658

@openclaw-barnacle openclaw-barnacle Bot added scripts Repository scripts size: M triage: needs-pr-context Candidate: external PR body lacks required problem context or evidence. and removed triage: needs-pr-context Candidate: external PR body lacks required problem context or evidence. labels Jun 23, 2026
@wangmiao0668000666

wangmiao0668000666 commented Jun 23, 2026

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

PR body has been updated to include the required ## What Problem This Solves and ## Evidence sections with structured legacy field labels (Real environment tested, Exact steps or command run after this patch, Evidence after fix, Observed result after fix, What was not tested).

The previously failing Real behavior proof CI check now passes (run 27998544437).

No code change. Re-requesting review for the same head SHA 5925227283.

@clawsweeper

clawsweeper Bot commented Jun 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@wangmiao0668000666

wangmiao0668000666 commented Jun 23, 2026

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

Last re-review request was at 02:51Z (~4h 10m ago). Bot ack arrived at 02:51:20Z but no in-place edit / verdict has landed yet on the existing review comment.

Current PR state:

  • mergeable: MERGEABLE
  • CI: 62 pass / 0 fail / 33 skip (all green)
  • reviewDecision: empty (no maintainer review yet)
  • isDraft: false
  • labels: scripts, size: M

No code change since the previous re-review (same head SHA 59252272836f3481423c84b27361995f40218a33). Re-queueing in case the prior dispatch was dropped or deprioritized in the queue.

If the queue is saturated and the original dispatch is still in progress, please ignore this nudge.

@clawsweeper

clawsweeper Bot commented Jun 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs real behavior proof before merge. Reviewed June 24, 2026, 6:19 AM ET / 10:19 UTC.

Summary
The PR adds provider-missing hint formatting to three media-understanding error paths, plus guard tests and a helper-level repro script.

PR surface: Source +61, Tests +62, Other +98. Total +221 across 3 files.

Reproducibility: yes. at source level: current main still has generic missing media-provider throw sites, and the linked issue provides CLI/Gateway Groq failure logs. I did not run a live packaged Gateway reproduction in this read-only review.

Review metrics: 1 noteworthy metric.

  • Provider diagnostic surfaces: 3 throw sites changed. All three changed errors are operator recovery diagnostics, so catalog ownership and product-path proof matter before merge.

Stored data model
Persistent data-model change detected: migration/backfill/repair: src/media-understanding/runner.entries.guards.test.ts, migration/backfill/repair: src/media-understanding/runner.entries.ts. Confirm migration or upgrade compatibility proof before merge.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🦪 silver shellfish
Patch quality: 🧂 unranked krab
Result: blocked until stronger real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • Gate hint eligibility on contracts.mediaUnderstandingProviders rather than broad providers[] metadata.
  • [P1] Add redacted CLI or Gateway output showing the enriched error through one changed throw site.

Proof guidance:

  • [P1] Needs stronger real behavior proof before merge: The PR body includes helper-level terminal output, but it does not show after-fix output through one changed CLI or Gateway missing-provider throw site. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

  • [P1] The PR can still emit install hints for official external providers that have generic model provider catalog entries but do not own contracts.mediaUnderstandingProviders, which could send users to a package that cannot fix the media-understanding error.
  • [P1] The PR body proof is helper-level terminal output; it does not show a changed CLI or Gateway throw site emitting the enriched error in the product path.

Maintainer options:

  1. Narrow And Prove Before Merge (recommended)
    Require the helper to use media-understanding contract ownership and add redacted product-path CLI or Gateway output before landing.
  2. Accept Provider-Catalog Scope
    Maintainers could intentionally accept broader provider-catalog hints, but that owns the risk of recovery instructions for packages that cannot fix media-understanding errors.
  3. Pause Until Live Proof Exists
    If no real CLI or Gateway missing-provider path can be shown, keep the PR paused until the diagnostic is proven in the reported workflow.

Next step before merge

  • [P1] Contributor or maintainer follow-up is needed because the code fix is narrow, but the remaining real CLI/Gateway proof cannot be supplied by repair automation.

Security
Cleared: The diff changes error-message formatting, catalog lookup usage, tests, and a local repro script without new dependencies, permissions, secrets handling, package resolution, or downloaded code execution.

Review findings

  • [P2] Gate hints on media-understanding contracts — src/media-understanding/runner.entries.ts:702-708
Review details

Best possible solution:

Gate hints on official catalog entries whose contracts.mediaUnderstandingProviders owns the requested id, then show redacted CLI or Gateway output through one changed throw site before merge.

Do we have a high-confidence way to reproduce the issue?

Yes at source level: current main still has generic missing media-provider throw sites, and the linked issue provides CLI/Gateway Groq failure logs. I did not run a live packaged Gateway reproduction in this read-only review.

Is this the best way to solve the issue?

No: appending the hint at the media-understanding throw sites is the right layer, but the owner check should gate on contracts.mediaUnderstandingProviders and proof should exercise a changed product path.

Full review comments:

  • [P2] Gate hints on media-understanding contracts — src/media-understanding/runner.entries.ts:702-708
    listOfficialExternalProviderCatalogEntries() matches any official provider with a providers[] block, and the PR makes amazon-bedrock a positive media hint case even though that plugin does not declare contracts.mediaUnderstandingProviders. This can send users from an audio/video missing-provider error to install a package that cannot register the missing media provider; gate the hint on the media-understanding contract and keep non-media providers as negative tests.
    Confidence: 0.9

Overall correctness: patch is incorrect
Overall confidence: 0.87

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against e9720c27fa69.

Label changes

Label justifications:

  • P1: The PR targets a latest-release Groq voice transcription regression affecting a real Telegram/channel workflow.
  • merge-risk: 🚨 compatibility: The current hint gate can emit upgrade recovery instructions for provider packages that do not own the media-understanding contract.
  • rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🦪 silver shellfish and patch quality is 🧂 unranked krab.
  • status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The PR body includes helper-level terminal output, but it does not show after-fix output through one changed CLI or Gateway missing-provider throw site. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed

PR surface:

Source +61, Tests +62, Other +98. Total +221 across 3 files.

View PR surface stats
Area Files Added Removed Net
Source 1 70 9 +61
Tests 1 63 1 +62
Docs 0 0 0 0
Config 0 0 0 0
Generated 0 0 0 0
Other 1 98 0 +98
Total 3 231 10 +221

Acceptance criteria:

  • [P1] node scripts/run-vitest.mjs src/media-understanding/runner.entries.guards.test.ts.
  • [P1] pnpm exec tsx scripts/repro/issue-95658-media-provider-missing.mjs.
  • [P1] Add redacted CLI or Gateway output through one changed missing-provider throw site before re-review.

What I checked:

  • Root repository policy: Root AGENTS.md was read fully and applied; provider/plugin routing, fallback behavior, and proof for user-visible diagnostics are compatibility-sensitive review surfaces. (AGENTS.md:1, e9720c27fa69)
  • Scoped scripts policy: scripts/AGENTS.md was read; it favors existing wrappers such as scripts/run-vitest.mjs for script/test verification and does not add a conflicting rule for this read-only review. (scripts/AGENTS.md:1, e9720c27fa69)
  • Maintainer note checked: The Telegram maintainer note was read because the linked bug is visible through Telegram voice notes; it requires real Telegram proof for Telegram transport changes, but this PR changes the media-understanding error path rather than Telegram transport behavior. (.agents/maintainer-notes/telegram.md:1, e9720c27fa69)
  • Current missing-provider behavior: Current main still throws the generic missing media-provider error when a configured non-image media provider is absent from the media-understanding registry. (src/media-understanding/runner.entries.ts:742, e9720c27fa69)
  • Current media registry owner contract: Current main builds the media-understanding registry from plugin capability providers keyed by mediaUnderstandingProviders, so the runtime owner boundary is the media-understanding contract rather than the generic provider list. (src/media-understanding/provider-registry.ts:57, e9720c27fa69)
  • Manifest contract documentation: The manifest reference defines contracts.mediaUnderstandingProviders as the media-understanding provider ids a plugin owns, and says mediaUnderstandingProviderMetadata keys must also be declared there. Public docs: docs/plugins/manifest.md. (docs/plugins/manifest.md:667, e9720c27fa69)

Likely related people:

  • vincentkoc: Recent live path history shows official external provider catalog work and media runner refactors, and local blame for the current missing-provider branch points at the current baseline by Vincent Koc. (role: recent plugin/catalog and media runner contributor; confidence: high; commits: f2eca9439189, 21728777dfa0, 4e6057e4dd52; files: src/plugins/official-external-plugin-catalog.ts, scripts/lib/official-external-provider-catalog.json, src/media-understanding/runner.entries.ts)
  • steipete: Live path history shows repeated media-understanding runner, plugin host contract, and Groq/plugin manifest refactor work near the affected owner boundary. (role: media runner and plugin manifest history contributor; confidence: medium; commits: 242eab9d20f7, f875b519e51b, b74f35ee6f97; files: src/media-understanding/runner.entries.ts, src/plugins/official-external-plugin-catalog.ts, extensions/groq/openclaw.plugin.json)
  • shakkernerd: Live path history shows prior Groq plugin manifest setup and provider plugin lazy-startup work adjacent to the provider being diagnosed. (role: Groq manifest contributor; confidence: medium; commits: 27b35c5b24f1, 023955b00463, 00d2c3488932; files: extensions/groq/openclaw.plugin.json)
  • sunlit-deng: The linked issue cites the merged external-plugin startup work as related externalization context, though that PR targeted channel plugin startup rather than this media-provider hint path. (role: adjacent external-plugin startup contributor; confidence: medium; commits: 21d3a70826fb, aaab95b70af2; files: src/plugins/gateway-startup-plugin-ids.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@clawsweeper clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. P1 High-priority user-facing bug, regression, or broken workflow. labels Jun 23, 2026
@wangmiao0668000666
fix(media-understanding): append actionable install hint when a media…
094088c 
… provider is missing (openclaw#95658)

Enriches 'Media provider not available: <id>', 'Audio transcription provider...',
and 'Video understanding provider...' errors with a hint pointing users at
`openclaw plugins install @openclaw/<id>-provider`, `openclaw plugins registry
--refresh`, and `openclaw doctor --fix`.

Tier 1: known catalog entries use the exact installCommand.
Tier 2: externalized providers not yet in the catalog get the conventional
        @openclaw/<id>-provider package hint.
Tier 3: empty/non-plugin-shaped ids preserve the legacy message verbatim so
        downstream scripts that grep on the prefix continue to match.

Legacy prefix strings are preserved verbatim.
@wangmiao0668000666
wangmiao0668000666 force-pushed the fix/95658-actionable-provider-missing-hint branch from 5925227 to 094088c Compare June 24, 2026 01:03
@wangmiao0668000666

wangmiao0668000666 commented Jun 24, 2026

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper — addressing the 3 P1 findings on PR #95926 (commit 094088cb12):

  • [P1.1] Real CLI/Gateway after-fix output: added a real-environment repro
    (scripts/repro/issue-95658-media-provider-missing.mjs) that exercises
    the production formatMissingProviderHint directly (no vitest mock).
    The 6 assertions all pass; the canonical "groq" before/after message is
    captured verbatim in the PR body "Evidence" section.
  • [P1.2] Gateway restart step: the tier-1 hint now reads
    ... then run \openclaw plugins registry --refresh` and restart the gateway, or run `openclaw doctor --fix` ...`
  • [P1.3] Tier-2 convention-fallback narrowed: removed the convention
    fallback branch entirely. Non-cataloged ids (e.g. mystery-provider)
    return the empty string and preserve the legacy message verbatim. The
    test suite now asserts the no-fallback behavior explicitly.

Other improvements in this revision:

  • Rebased onto current openclaw/main (d9298a74be).
  • Updated repro to assert the new tier-1 wording (catalog-known includes
    "restart the gateway") and the no-fallback tier-2 behavior.

Verification (all green):

  • node scripts/run-vitest.mjs src/media-understanding/runner.entries.guards.test.ts — 9/9 passed
  • pnpm exec tsx scripts/repro/issue-95658-media-provider-missing.mjs — 6/6 PASS
  • npx oxlint --import-plugin --config .oxlintrc.json on the 3 changed files — exit 0

@clawsweeper

clawsweeper Bot commented Jun 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@wangmiao0668000666 wangmiao0668000666 mentioned this pull request Jun 24, 2026
Closed
@wangmiao0668000666
fix(media-understanding): restrict hint lookup to provider catalog (o…
ceecde8 
…penclaw#95926)

Addresses the ClawSweeper P2 finding that `formatMissingProviderHint`
called `resolveOfficialExternalPluginRepairHint`, which searches the
combined channel/provider/plugin catalogs. A media provider id that
matches an official channel (e.g. `feishu`) would emit a misleading
`openclaw plugins install @openclaw/feishu` from a media-provider
error even though `feishu` does not own a `mediaUnderstandingProviders`
contract.

Changes:
- `src/media-understanding/runner.entries.ts` (+40 / -11):
  - Added `normalizeOptionalString` and provider catalog imports
  - Replaced combined catalog lookup with provider-only catalog lookup
    (`listOfficialExternalProviderCatalogEntries` + manifest `providers[]` block
    match on id or alias) before calling the existing
    `resolveOfficialExternalPluginRepairHint` helper
  - Documented the tier semantics (tier 1 = provider-catalog owner,
    tier 2 = empty for everything else)

- `src/media-understanding/runner.entries.guards.test.ts` (+8):
  - Added regression test: `feishu` (an official external channel id)
    returns empty string, so a media-provider error never emits an
    install hint pointing at the wrong package

Verified on commit:
- `node scripts/run-vitest.mjs src/media-understanding/runner.entries.guards.test.ts`
  — 10/10 passed (9 prior + 1 new feishu narrowing test)
- `pnpm exec tsx scripts/repro/issue-95658-media-provider-missing.mjs`
  — 6/6 PASS (tier 1 amazon-bedrock + tier 1 groq + tier 2 empty +
    tier 3 empty + 2 backward-compat prefix checks)
- `npx oxlint --import-plugin --config .oxlintrc.json` on the 2 changed files
  — exit 0
- `node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.core.test.json`
  — exit 0

The P2 finding (catalog-lookup scope) is addressed without changing the
existing tier-2 verbatim-legacy behavior.
@wangmiao0668000666

wangmiao0668000666 commented Jun 24, 2026

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper — addressing the ClawSweeper P2 finding on PR #95926 (commit ceecde8fc8):

  • [P2] "Restrict media hints to media-provider catalog entries" — addressed by:

    • Replaced the combined channel/provider/plugin catalog lookup with a provider-only lookup in formatMissingProviderHint (src/media-understanding/runner.entries.ts).
    • The narrowing uses listOfficialExternalProviderCatalogEntries() (entries with a non-empty providers[] block) and matches on provider.id or provider.aliases. The previous call to resolveOfficialExternalPluginRepairHint(trimmed) is still used to build the hint text, but only after the provider-only ownership check passes — so a media-provider error path can never emit an install hint for an id like feishu that is an official channel, not a media provider.
    • Documented the new tier semantics in the helper docblock: tier 1 = provider-catalog owner (catalog-backed install + refresh + doctor fix), tier 2 = empty string (legacy message verbatim) for channel ids / plugin ids / unknown ids / internal ids.

  • Added a regression test (src/media-understanding/runner.entries.guards.test.ts):

    • formatMissingProviderHint("feishu") returns empty string — locks the contract that the provider-only lookup never falls back to the channel catalog.

Verification (all green on commit ceecde8fc8):

  • node scripts/run-vitest.mjs src/media-understanding/runner.entries.guards.test.ts — 10/10 passed (9 prior + 1 new feishu narrowing test)
  • pnpm exec tsx scripts/repro/issue-95658-media-provider-missing.mjs — 6/6 PASS (tier 1 amazon-bedrock + tier 1 groq + tier 2 mystery-provider + tier 3 empty/whitespace + 2 backward-compat prefix checks)
  • npx oxlint --import-plugin --config .oxlintrc.json on the 2 changed files — exit 0
  • node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.core.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core-test.tsbuildinfo — exit 0

The P2 finding (catalog-lookup scope) is addressed without changing the existing tier-2 verbatim-legacy behavior. PR body unchanged.

@clawsweeper

clawsweeper Bot commented Jun 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

This was referenced Jun 24, 2026
Closed
Closed
@clawsweeper clawsweeper Bot added merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. and removed rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. labels Jun 24, 2026
@wangmiao0668000666

wangmiao0668000666 commented Jun 25, 2026

Copy link
Copy Markdown
Contributor Author

Closing to open a cleaner Alix-007-style version. The source change (+70/-9 source + unit tests) is S-size on its own — the M size came from the committed repro script (98 LoC). New PR will keep the same helper + throw sites + tests, with local-only proof.

This was referenced Jun 25, 2026
Closed
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. P1 High-priority user-facing bug, regression, or broken workflow. rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. scripts Repository scripts size: M status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Bug]: 2026.6.9 breaks Groq voice transcription — "Media provider not available: groq" (externalized provider plugin not auto-installed)

1 participant

@wangmiao0668000666