bug: safely materialize URL-only video assets after upstream SDK contract decision

[ekinnee]

Summary

The plugin forwards provider-returned video URLs as GeneratedVideoAsset URLs, while its declared OpenClaw compatibility range includes older hosts whose CLI downloads those URLs with bare fetch. This tracker covers the downstream compatibility repair.

The intended repair is to materialize URL-only video results through OpenClaw's existing guarded public media-store API and return buffered assets. OpenClaw owns SSRF protection, redirects, and managed-media lifecycle; the plugin must not implement a parallel downloader or infer host safety from release ancestry.

Current status — September 8, 2026

Blocked on the SDK/security-owner contract decision in openclaw/openclaw#132601. No plugin implementation PR is open.

• Current plugin main still forwards URLs and prefers url when a response supplies both url and b64_json.
• Package version remains 2.1.4; peer/plugin API floor remains >=2026.7.1-0, with minimum gateway version 2026.7.1.
• The focused plugin-sdk/media-store exports saveMediaSource and readMediaBuffer in released OpenClaw v2026.9.3. API availability is no longer the main blocker.
• The September 4 upstream review keeps the contract request open. No subsequent human maintainer decision is recorded in that discussion as of this check.
• This status is based on tracker and source inspection; no new packed-artifact or runtime video proof has been run.

Decisions required upstream

1. Explicit byte bound: confirm the supported limit for both URL ingestion and buffer reading. The upstream request proposes 16 MiB; the media-store default is 5 MiB. Treat 16 MiB as a proposal until the owner settles the contract.
2. Retention and cleanup owner: define what happens to the managed item after its bytes are returned. The upstream review found that general TTL cleanup requires attachments.ttlHours; automatic cleanup cannot be assumed. The focused SDK does not expose deletion in the inspected release.
3. Legacy compatibility: decide whether dynamically resolving the deprecated-but-public plugin-sdk/media-runtime.saveMediaSource on older supported hosts is acceptable, or whether a declared host floor is required. Do not silently establish a new fallback support promise.

Intended plugin behavior and acceptance criteria

After the upstream contract is settled:

1. Keep inline b64_json support and prefer supplied inline bytes over a URL when both are available.
2. Materialize URL-only results through public saveMediaSource, then bounded readMediaBuffer, and return a buffered GeneratedVideoAsset consistently for CLI and agent consumers.
3. Pass the approved explicit byte limit to both operations and follow the documented cleanup/lifetime contract.
4. Use the focused plugin-sdk/media-store entrypoint. Add a legacy public fallback only if upstream explicitly supports it; otherwise document and test the approved host compatibility boundary.
5. Add focused coverage for inline-only success, inline preference when both forms are present, URL-only buffered success, guarded-ingestion rejection, byte-limit failures, and the selected cleanup and host-compatibility behavior.
6. Update package/manifest compatibility metadata only if the approved contract requires it, and update README/support documentation to describe the resulting behavior.
7. Freeze exact supported host versions and run packed-artifact video proof across the approved minimum, current stable, and beta, including any approved legacy fallback. Publish through the normal release-triggered process only after that proof succeeds.

Superseded plan

The August 29 cross-owner plan requested api.runtime.videoGeneration.supportsProviderUrlAssets. That proposal was withdrawn in #132601: a boolean conflates intentional URL forwarding with guarded downloading across different consumers. This body supersedes that comment's boolean-based acceptance criteria and release sequence.

A blanket version-floor bump or waiting only for the guarded CLI downloader release does not settle the remaining materialization, retention, and legacy-support contract.

Original reproduction and evidence

The original affected snapshot was OpenClaw v2026.7.1-2 (0790d9f), admitted by the plugin's compatibility range:

1. Use a provider that returns { "data": [{ "url": "https://provider.example/video.mp4" }] }.
2. The plugin forwards the URL as a generated-video asset.
3. The affected host CLI dereferences it with bare fetch(video.url, ...), allowing a malicious or compromised provider response to target an unintended network destination.

OpenClaw PR #101854 merged the guarded CLI downloader. This issue remains the downstream compatibility tracker, not a duplicate upstream security report.

• Plugin video adapter
• Plugin compatibility metadata
• Originally affected CLI source
• Focused media-store export PR #125278
• Upstream materialization contract request #132601

[ekinnee]

Cross-owner compatibility plan

The release-line divergence means this issue should not be resolved by a broad version-floor bump or by treating upstream main as a release proxy.

Upstream contract: openclaw/openclaw#132601 requests a public semantic capability adjacent to the plugin video-generation runtime. The host owns whether a provider-supplied generated-video URL is safe to consume; the plugin must not recreate SSRF policy or maintain a release-branch ancestry table.

Plugin PR acceptance criteria

1. Keep one package and the existing minimum import floor.
2. Feature-detect the optional public URL-asset capability structurally. A missing value is legacy-safe false.
3. On a legacy host, prefer b64_json when it is supplied. If the response is URL-only, fail before handing the URL to the host, with an actionable upgrade message.
4. On a host advertising the capability, preserve the existing URL-asset result behavior.
5. Add focused regressions for legacy buffer success, legacy URL-only rejection, and guarded-host URL success. Keep the packed-artifact matrix for the legacy release, the first stable release advertising the capability, current stable, and beta.
6. Document the two video-result bands and publish only after the first stable host release and packed-artifact proof are available.

PR sequence

1. OpenClaw PR: add and test the public host capability from #132601.
2. OmniRoute plugin PR: consume the capability in one runtime adapter, add behavior tests/matrix/docs, and keep all existing provider surfaces unchanged.
3. OmniRoute release PR: after the upstream capability appears in a stable release, freeze the exact host versions, run the packed-artifact proof, and publish the plugin through the normal release-triggered path.

The plugin PR is intentionally blocked on acceptance of the upstream public contract; a version-only workaround would repeat the divergence this issue records.

[ekinnee]

Upstream status recheck — September 17, 2026

The blocking OpenClaw contract decision remains unresolved. openclaw/openclaw#132601 is still open with product- and security-decision labels. No maintainer guidance has settled the matching byte bound, temporary managed-media cleanup owner, or supported legacy fallback.

Recent upstream media and delivery changes do not answer those questions, so the issue's current implementation boundary remains correct: keep inline b64_json handling, do not add a plugin-owned downloader, and do not implement URL materialization until the public lifecycle and compatibility contract is explicit.

No plugin source change or compatibility-floor change is warranted from this recheck.