normalizeNullableString,

} from "@openclaw/normalization-core/string-coerce";

import { normalizeStringEntries } from "@openclaw/normalization-core/string-normalization";

import { MediaUnderstandingSkipError } from "../../packages/media-understanding-common/src/errors.js";

import { extractGeminiResponse } from "../../packages/media-understanding-common/src/output-extract.js";

import {

estimateBase64Size,

resolveVideoMaxBase64Bytes,

} from "../../packages/media-understanding-common/src/video.js";

import {

collectProviderApiKeysForExecution,

executeWithApiKeyRotation,

} from "../agents/provider-request-config.js";

import type { MsgContext } from "../auto-reply/templating.js";

import { applyTemplate } from "../auto-reply/templating.js";

import { formatCliCommand } from "../cli/command-format.js";

import type { ModelProviderConfig, OpenClawConfig } from "../config/types.js";

import type {

MediaUnderstandingConfig,

import { resolveProxyFetchFromEnv } from "../infra/net/proxy-fetch.js";

import { resolvePreferredOpenClawTmpDir } from "../infra/tmp-openclaw-dir.js";

import { runFfmpeg } from "../media/media-services.js";

import {

getOfficialExternalPluginCatalogManifest,

listOfficialExternalProviderCatalogEntries,

} from "../plugins/official-external-plugin-catalog.js";

import { resolveOfficialExternalPluginRepairHint } from "../plugins/official-external-plugin-repair-hints.js";

import { runExec } from "../process/exec.js";

import { providerOperationRetryConfig } from "../provider-runtime/operation-retry.js";

import { MediaUnderstandingSkipError } from "../../packages/media-understanding-common/src/errors.js";

import { extractGeminiResponse } from "../../packages/media-understanding-common/src/output-extract.js";

import {

estimateBase64Size,

resolveVideoMaxBase64Bytes,

} from "../../packages/media-understanding-common/src/video.js";

import { MediaAttachmentCache } from "./attachments.js";

import {

CLI_OUTPUT_MAX_BUFFER,

);

}

/**

* Build an actionable hint suffix for "provider not available" errors.

*

* Restricts the hint to ids that are owned by the official external

* provider catalog — NOT the combined channel/plugin catalog — so a media

* provider id like `feishu` (an official channel, not a media provider)

* never emits a misleading install hint from a media-provider error.

*

* Tier 1: provider id is owned by an official external provider entry that

* declares a `contracts.mediaUnderstandingProviders` block listing the

* id — emit the catalog-backed install + registry refresh + doctor fix

* commands.

* Tier 2: empty string — keeps the legacy message verbatim for ids that

* are not in the provider catalog (channel ids, plugin ids, unknown

* ids, internal ids, etc.). Newly externalized media providers must

* register with the official external provider catalog to receive the

* actionable hint.

*/

export function formatMissingProviderHint(providerId: string): string {

const trimmed = providerId.trim();

if (!trimmed) {

return "";

}

// Look up the id only in catalog entries that declare

// `contracts.mediaUnderstandingProviders`. This ensures the install hint

// only fires for provider packages that actually own the missing

// media-understanding capability. Providers that have a generic `providers[]`

// catalog entry but no media-understanding contract (e.g. Amazon Bedrock)

// will not emit misleading hints.

const providerEntry = listOfficialExternalProviderCatalogEntries().find((entry) => {

const manifest = getOfficialExternalPluginCatalogManifest(entry);

const mediaProviders = manifest?.contracts?.mediaUnderstandingProviders ?? [];

return mediaProviders.some((mediaId) => mediaId === trimmed);

});

if (!providerEntry) {

return "";

}

// `resolveOfficialExternalPluginRepairHint` is contract-agnostic but we

// already validated ownership via the provider-only catalog, so the

// returned hint is for the correct provider entry.

const catalogHint = resolveOfficialExternalPluginRepairHint(trimmed);

if (!catalogHint) {

return "";

}

return ` Install the official external plugin with: ${formatCliCommand(catalogHint.installCommand)}, then run ${formatCliCommand("openclaw plugins registry --refresh")} and stop and start the gateway service, or run ${formatCliCommand(catalogHint.doctorFixCommand)} to repair automatically.`;

}

/** Executes one provider-backed media-understanding entry for one attachment. */

export async function runProviderEntry(params: {

capability: MediaUnderstandingCapability;

const provider = getMediaUnderstandingProvider(providerId, params.providerRegistry);

if (!provider) {

throw new Error(`Media provider not available: ${providerId}`);

throw new Error(

`Media provider not available: ${providerId}${formatMissingProviderHint(providerId)}`,

);

}

// Resolve proxy-aware fetch from env vars (HTTPS_PROXY, HTTP_PROXY, etc.)