Skip to content

zenstory-ai/drama-skills / skills/short-drama-produce

short-drama-produce

Verified

在创作者明确确认后,单条或按批调用已配置接口执行图片、视频、配音或配乐生成并保存产物与运行记录。用于“生成图/视频/配音/音乐”“开始跑图/跑视频”“把定稿提示词送去生成”;不写提示词、不改台词,不把预览或定稿当扣费确认。

FileKindSize
SKILL.mdskill md8.2 KB
agents/openai.yamlconfig292 B
references/adapter-contract.mdmarkdown9.0 KB
references/builtin-providers.mdmarkdown6.6 KB
scripts/production_tool.pyexecutablescript137.2 KB
scripts/provider_adapters.pyexecutablescript79.6 KB

scripts/provider_adapters.py

View on GitHub
#!/usr/bin/env python3
"""Stdlib-only production adapters for supported media providers.

The public ``compile_*`` functions are deterministic and perform no I/O.  The
CLI reads the confirmed production job from stdin and writes only the adapter
contract JSON to stdout after a provider result has been saved to a temporary
regular file.
"""

from __future__ import annotations

import argparse
import base64
import binascii
import json
import math
import mimetypes
import os
import re
import secrets
import socket
import stat
import sys
import time
import urllib.error
import urllib.parse
import urllib.request
from collections.abc import Collection, Mapping, Sequence
from pathlib import Path
from typing import Any

OPENAI_MODEL = "gpt-image-2"
MINIMAX_MUSIC_MODEL = "music-3.0"
OPENAI_BASE_URL = "https://api.openai.com/v1"
SEEDANCE_BASE_URL = "https://ark.cn-beijing.volces.com/api/v3"
MINIMAX_BASE_URL = "https://api.minimax.io/v1"
MINIMAX_VIDEO_BASE_URL = "https://api.minimax.io/v2"
MAX_JSON_RESPONSE = 128 * 1024 * 1024
MAX_OUTPUT_BYTES = 512 * 1024 * 1024
MAX_REFERENCE_BYTES = 50 * 1024 * 1024
MAX_MULTIPART_BYTES = 200 * 1024 * 1024
MAX_ERROR_BODY_BYTES = 64 * 1024
TERMINAL_FAILURES = {"failed", "cancelled", "canceled", "timeout", "expired"}
SEEDANCE_RATIOS = {"adaptive", "1:1", "3:4", "4:3", "9:16", "16:9", "21:9"}
SEEDANCE_REFERENCE_ROLES = {
    "first_frame": "image_url",
    "last_frame": "image_url",
    "reference_image": "image_url",
    "reference_video": "video_url",
    "reference_audio": "audio_url",
}
# One opening frame and one closing frame, because each names a single position
# in the take. Note what is deliberately absent: the sibling adapter forbids
# mixing frame conditioning with reference conditioning, and that rule belongs
# to that provider's reference, not to this one. Do not carry it across.
SEEDANCE_SINGULAR_ROLES = {"first_frame", "last_frame"}
MINIMAX_VIDEO_RATIOS = {"adaptive", "1:1", "3:4", "4:3", "9:16", "16:9", "21:9"}
MINIMAX_VIDEO_RESOLUTIONS = {"480P", "768P", "2K"}
MINIMAX_VIDEO_PROMPT_LIMIT = 7000
MINIMAX_SPEECH_TEXT_LIMIT = 5000
MINIMAX_VIDEO_ROLES = {
    "first_frame": "image_url",
    "last_frame": "image_url",
    "reference_image": "image_url",
    "reference_video": "video_url",
    "reference_audio": "audio_url",
}
# Both providers document a `data:<mime>;base64,<...>` URI as an accepted media
# input alongside a public URL, so a local project reference needs no upload
# service to reach them. The caps are MiniMax's published per-modality limits;
# Seedance publishes no numbers, so the same conservative guard is applied there
# and can be raised per deployment. Base64 inflates bytes by about a third, so
# the request cap is checked against the encoded size.
INLINE_REFERENCE_LIMITS = {
    "image_url": 30 * 1024 * 1024,
    "video_url": 50 * 1024 * 1024,
    "audio_url": 15 * 1024 * 1024,
}
INLINE_REFERENCE_BODY_LIMIT = 64 * 1024 * 1024
INLINE_REFERENCE_MIME = {
    ".png": "image/png",
    ".jpg": "image/jpeg",
    ".jpeg": "image/jpeg",
    ".webp": "image/webp",
    ".mp4": "video/mp4",
    ".mov": "video/quicktime",
    ".webm": "video/webm",
    ".wav": "audio/wav",
    ".mp3": "audio/mpeg",
    ".m4a": "audio/mp4",
    ".aac": "audio/aac",
    ".flac": "audio/flac",
    ".opus": "audio/ogg",
}
PUBLIC_ERROR_TOKEN_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,199}")
GPT_IMAGE_MIN_PIXELS = 655_360
GPT_IMAGE_MAX_PIXELS = 8_294_400
MINIMUM_PYTHON = (3, 9)
if sys.version_info < MINIMUM_PYTHON:
    raise SystemExit("provider_adapters.py requires Python 3.9 or newer")


class AdapterFailure(RuntimeError):
    """A safe-to-report adapter failure without provider response contents."""

    def __init__(
        self,
        message: str,
        *,
        category: str = "provider_response",
        code: str = "adapter_failure",
        http_status: int | None = None,
        request_id: str | None = None,
        retryable: bool = False,
        submitted: bool | None = None,
        detail: str | None = None,
    ) -> None:
        super().__init__(message)
        self.category = category
        self.code = _safe_token(code) or "adapter_failure"
        self.http_status = http_status
        self.request_id = _safe_token(request_id)
        self.retryable = retryable
        self.submitted = submitted
        self.detail = _safe_detail(detail)

    def public(self, provider: str) -> dict[str, Any]:
        result: dict[str, Any] = {
            "provider": provider,
            "category": self.category,
            "code": self.code,
            "retryable": self.retryable,
        }
        if self.http_status is not None:
            result["http_status"] = self.http_status
        if self.request_id is not None:
            result["request_id"] = self.request_id
        if self.submitted is not None:
            result["submitted"] = self.submitted
        if self.detail is not None:
            result["detail"] = self.detail
        return result


AdapterError = AdapterFailure
MINIMAX_H3_REFERENCE_LIMITS = {
    "image_url": 9,
    "video_url": 3,
    "audio_url": 3,
}


def _safe_detail(value: object) -> str | None:
    if not isinstance(value, str):
        return None
    collapsed = " ".join(value.split())
    if not collapsed or len(collapsed) > 160:
        return None
    if any(ord(ch) < 32 or ord(ch) == 127 for ch in collapsed):
        return None
    if re.search(
        r"://|(?<![\w.])/(?:Users|home|private|var|tmp)/|\b[A-Za-z]:[\\/]"
        r"|\bbearer\s+\S+|\bsk-[A-Za-z0-9_-]{8,}"
        r"|\b(?:authorization|password|passwd|secret|api[_-]?key|access[_-]?token)\s*[:=]",
        collapsed,
        re.IGNORECASE,
    ):
        return None
    return collapsed


def _safe_public_id(value: object) -> str | None:
    if isinstance(value, str) and PUBLIC_ERROR_TOKEN_RE.fullmatch(value) is not None:
        return value
    return None


def _safe_token(value: object) -> str | None:
    if isinstance(value, str) and PUBLIC_ERROR_TOKEN_RE.fullmatch(value) is not None:
        return value
    if isinstance(value, int) and not isinstance(value, bool) and value >= 0:
        return str(value)
    return None


def _request_id(headers: Mapping[str, Any]) -> str | None:
    folded = {str(key).casefold(): value for key, value in headers.items()}
    for name in ("x-request-id", "x-tt-logid", "x-trace-id", "trace-id"):
        value = _safe_token(folded.get(name))
        if value is not None:
            return value
    return None


def _provider_code(document: object) -> str | None:
    if not isinstance(document, Mapping):
        return None
    error = document.get("error")
    if isinstance(error, Mapping):
        value = _safe_token(error.get("code"))
        if value is not None:
            return value
    base_resp = document.get("base_resp")
    if isinstance(base_resp, Mapping):
        value = _safe_token(base_resp.get("status_code"))
        if value not in {None, "0"}:
            return value
    return _safe_token(document.get("code"))


def _http_failure(provider: str, error: urllib.error.HTTPError) -> AdapterFailure:
    status = error.code
    try:
        raw = error.read(MAX_ERROR_BODY_BYTES + 1)
        document = json.loads(raw) if len(raw) <= MAX_ERROR_BODY_BYTES else None
    except (OSError, UnicodeError, json.JSONDecodeError):
        document = None
    if status == 401:
        category = "authentication"
    elif status == 403:
        category = "permission"
    elif status == 429:
        category = "rate_limit"
    elif 500 <= status <= 599:
        category = "server"
    elif 400 <= status <= 499:
        category = "invalid_request"
    else:
        category = "provider_response"
    return AdapterFailure(
        f"{provider} HTTP request failed",
        category=category,
        code=_provider_code(document) or f"http_{status}",
        http_status=status,
        request_id=_request_id(
            dict(error.headers.items()) if error.headers is not None else {}
        ),
        retryable=status == 429 or 500 <= status <= 599,
    )


def _require_job(
    job: Mapping[str, Any], modality: str, *, max_outputs: int = 1
) -> tuple[str, dict[str, Any]]:
    if not isinstance(job, Mapping) or job.get("modality") != modality:
        raise ValueError(f"adapter requires a {modality} job")
    prompt = job.get("prompt")
    if not isinstance(prompt, str) or not prompt.strip():
        raise ValueError("job prompt must be non-empty")
    parameters = job.get("parameters", {})
    if not isinstance(parameters, Mapping):
        raise ValueError("job parameters must be an object")
    outputs = job.get("outputs")
    if not isinstance(outputs, list) or not outputs or any(
        not isinstance(item, str) for item in outputs
    ):
        raise ValueError("provider adapter requires at least one output")
    if max_outputs == 1 and len(outputs) != 1:
        raise ValueError("provider adapter requires exactly one output")
    if len(outputs) > max_outputs:
        raise ValueError(f"provider adapter accepts at most {max_outputs} outputs")
    return prompt, dict(parameters)


ZH_ROLE_LABELS = {
    "first_frame": "首帧",
    "last_frame": "尾帧",
    "start_frame": "首帧",
    "end_frame": "尾帧",
    "reference_image": "参考图",
    "reference_video": "参考视频",
    "reference_audio": "参考音频",
    "identity": "外貌",
    "identity_and_look": "外貌与造型",
    "look_state": "造型状态",
    "look": "造型",
    "geography": "空间布局",
    "spatial_geography": "空间布局",
    "composition": "构图",
    "scale": "尺度",
    "effect": "效果",
    "style": "风格",
    "subject": "主体",
    "continuity_video": "前序接戏视频",
    "actual_tail_frame": "前镜实际尾帧",
}


def _prompt_already_binds_references(
    prompt: str,
    bindings: Sequence[Mapping[str, Any]],
    reference_tokens: Sequence[str],
) -> bool:
    if "retention_analysis:" in prompt:
        return True
    if reference_tokens:
        return all(
            re.search(rf"{re.escape(token)}(?!\d)", prompt) is not None
            for token in reference_tokens
        )
    count = len(bindings)
    return bool(count) and (
        all(
            re.search(rf"<Picture {index}>(?!\d)", prompt) is not None
            for index in range(1, count + 1)
        )
        or all(
            re.search(rf"@图片{index}(?!\d)", prompt) is not None
            for index in range(1, count + 1)
        )
        or all(
            re.search(rf"图{index}(?!\d)", prompt) is not None
            for index in range(1, count + 1)
        )
    )


def _prompt_with_reference_contract(
    prompt: str,
    job: Mapping[str, Any],
    *,
    prompt_language: str | None = None,
    reference_tokens: Sequence[str] = (),
    zh_reference_prefix: str = "参考",
    zh_heading: str = "参考约束:",
) -> str:
    bindings = job.get("reference_bindings", [])
    references = job.get("references", [])
    if not bindings:
        return prompt
    if (
        not isinstance(bindings, list)
        or not isinstance(references, list)
        or len(bindings) != len(references)
    ):
        raise ValueError("reference bindings must match job references")
    if reference_tokens and len(reference_tokens) != len(references):
        raise ValueError("reference tokens must match job references")
    language = (prompt_language or "en").casefold()
    instructions: list[str] = []
    for index, binding in enumerate(bindings, 1):
        if not isinstance(binding, Mapping) or binding.get("order") != index:
            raise ValueError("reference binding order is invalid")
        if binding.get("path") != references[index - 1]:
            raise ValueError("reference binding path does not match job references")
        label = binding.get("label")
        role = binding.get("role")
        may_control = binding.get("may_control")
        must_not_control = binding.get("must_not_control")
        if (
            not isinstance(label, str)
            or not label.strip()
            or not isinstance(role, str)
            or not role.strip()
            or not isinstance(may_control, list)
            or not may_control
            or not all(isinstance(item, str) and item.strip() for item in may_control)
            or not isinstance(must_not_control, list)
            or not must_not_control
            or not all(isinstance(item, str) and item.strip() for item in must_not_control)
        ):
            raise ValueError("reference binding semantics are invalid")
        character = binding.get("character")
        if character is not None:
            if role != "reference_audio" or not isinstance(character, str) or not character.strip():
                raise ValueError("reference audio character is invalid")
            # The source's explicit speaker wins over the free-form asset label.
            label = f"{character.strip()}音色参考"
        role_text = role.strip()
        values = {
            "order": index,
            "reference": reference_tokens[index - 1] if reference_tokens else str(index),
            "label": label.strip(),
            "role": role_text,
            "may": ", ".join(item.strip() for item in may_control),
            "must": ", ".join(item.strip() for item in must_not_control),
        }
        if language.startswith("zh"):
            zh_values = {
                **values,
                "role": ZH_ROLE_LABELS.get(role_text, role_text),
            }
            instructions.append(
                f"{zh_reference_prefix} "
                + (
                    "{reference}({label}),用途:{role}。允许控制:{may}。"
                    "不得控制:{must}。".format(**zh_values)
                )
            )
        elif language.startswith("en"):
            instructions.append(
                "Reference {reference} ({label}), role {role}. May control: {may}. "
                "Must not control: {must}.".format(**values)
            )
        else:
            instructions.append(
                "[REF {order} | {label} | {role}] [+] {may} [-] {must}".format(
                    **values
                )
            )
    if _prompt_already_binds_references(prompt, bindings, reference_tokens):
        return prompt
    if language.startswith("zh"):
        heading = zh_heading
    elif language.startswith("en"):
        heading = "Reference contract:"
    else:
        heading = "<REF_CONTRACT>"
    return f"{prompt}\n\n{heading}\n" + "\n".join(instructions)


def _pop_prompt_language(parameters: dict[str, Any]) -> str | None:
    value = parameters.pop("prompt_language", None)
    if value is None:
        return None
    if not isinstance(value, str) or not value.strip() or len(value) > 64:
        raise ValueError("prompt_language must be a non-empty bounded language tag")
    return value.strip()


def _take(parameters: dict[str, Any], allowed: set[str]) -> dict[str, Any]:
    unknown = set(parameters) - allowed
    if unknown:
        raise ValueError("unsupported provider parameters: " + ", ".join(sorted(unknown)))
    return parameters


def compile_seedance_payload(
    job: Mapping[str, Any],
    *,
    model: str,
    reference_urls: Sequence[str] = (),
    reference_roles: Sequence[str] = (),
    allowed_ratios: Collection[str] | None = None,
    duration_range: tuple[int, int] | None = None,
) -> dict[str, Any]:
    """Compile a video production job into the official Seedance task body.

    ``model`` is deliberately mandatory: callers must obtain it from explicit
    runtime configuration rather than assuming any Seedance release.
    """
    prompt, parameters = _require_job(job, "video")
    if not isinstance(model, str) or not model.strip():
        raise ValueError("Seedance model must be explicitly configured")
    references = job.get("references", [])
    if not isinstance(references, list) or len(reference_urls) != len(references):
        raise ValueError("Seedance reference URLs must match job references")
    if len(reference_roles) != len(reference_urls):
        raise ValueError("Seedance reference roles must match job references")
    if Path(job["outputs"][0]).suffix.casefold() != ".mp4":
        raise ValueError("Seedance adapter requires an MP4 target")
    parameters = _take(
        parameters,
        {
            "duration",
            "ratio",
            "generate_audio",
            "omni_reference_task_type",
            "prompt_language",
        },
    )
    prompt_language = _pop_prompt_language(parameters)
    duration = parameters.get("duration")
    if duration is not None and (
        not isinstance(duration, int)
        or isinstance(duration, bool)
        or (duration != -1 and not 1 <= duration <= 30)
    ):
        raise ValueError("Seedance duration must be -1 or an integer from 1 to 30")
    if duration is not None and duration != -1:
        minimum, maximum = (1, 30) if duration_range is None else duration_range
        if not 1 <= minimum <= maximum <= 30 or not minimum <= duration <= maximum:
            raise ValueError("Seedance duration is outside the configured model profile")
    ratio = parameters.get("ratio")
    if ratio is not None and (
        not isinstance(ratio, str) or ratio.strip() not in SEEDANCE_RATIOS
    ):
        raise ValueError("Seedance ratio is outside the supported profile")
    if ratio is not None:
        configured_ratios = (
            set(SEEDANCE_RATIOS) if allowed_ratios is None else set(allowed_ratios)
        )
        if not configured_ratios or not configured_ratios <= SEEDANCE_RATIOS or ratio.strip() not in configured_ratios:
            raise ValueError("Seedance ratio is outside the configured model profile")
        ratio = ratio.strip()
    generate_audio = parameters.get("generate_audio")
    if generate_audio is not None and not isinstance(generate_audio, bool):
        raise ValueError("Seedance generate_audio must be a boolean")
    task_type = parameters.get("omni_reference_task_type")
    if task_type is not None and task_type not in {"auto", "reference", "edit", "extend"}:
        raise ValueError("Seedance omni reference task type is invalid")
    counters = {"image_url": 0, "video_url": 0, "audio_url": 0}
    labels = {"image_url": "图片", "video_url": "视频", "audio_url": "音频"}
    reference_tokens: list[str] = []
    singular_seen: set[str] = set()
    for role in reference_roles:
        field = SEEDANCE_REFERENCE_ROLES.get(role)
        if field is None:
            raise ValueError(f"unsupported Seedance reference role: {role}")
        if role in SEEDANCE_SINGULAR_ROLES:
            if role in singular_seen:
                raise ValueError(f"Seedance accepts one {role} reference")
            singular_seen.add(role)
        # A frame role still occupies a picture slot, so it keeps counting: the
        # tokens are positional, and skipping one would point every later
        # `@图片N` in the prose at the wrong picture.
        counters[field] += 1
        reference_tokens.append(f"@{labels[field]}{counters[field]}")
    if task_type in {"edit", "extend"} and "reference_video" not in reference_roles:
        raise ValueError(f"Seedance {task_type} requires a reference video")
    if task_type == "edit" and (ratio != "adaptive" or duration != -1):
        raise ValueError("Seedance edit requires adaptive ratio and duration -1")
    if task_type == "extend" and ratio != "adaptive":
        raise ValueError("Seedance extend requires an adaptive ratio")
    text = _prompt_with_reference_contract(
        prompt,
        job,
        prompt_language=prompt_language,
        reference_tokens=reference_tokens,
        zh_reference_prefix=(
            "输入素材" if task_type in {"edit", "extend"} else "参考"
        ),
        zh_heading=(
            "输入素材约束:" if task_type in {"edit", "extend"} else "参考约束:"
        ),
    )
    content: list[dict[str, Any]] = [{"type": "text", "text": text}]
    for index, url in enumerate(reference_urls):
        if not isinstance(url, str) or not url:
            raise ValueError("Seedance reference URL must be non-empty")
        role = reference_roles[index]
        field = SEEDANCE_REFERENCE_ROLES[role]
        suffix = Path(str(references[index])).suffix.casefold()
        expected = {
            "image_url": {".png", ".jpg", ".jpeg", ".webp"},
            "video_url": {".mp4", ".mov", ".webm"},
            "audio_url": {".wav", ".mp3", ".m4a", ".aac", ".flac", ".opus"},
        }[field]
        if suffix not in expected:
            raise ValueError(f"Seedance {role} does not match the reference file type")
        parsed = urllib.parse.urlparse(url)
        if not (
            (parsed.scheme == "https" and parsed.netloc)
            or (
                parsed.scheme == "asset"
                and parsed.netloc.startswith("asset-")
                and not parsed.path
            )
            or _is_inline_reference(url)
        ):
            raise ValueError(
                "Seedance reference URL must be HTTPS, asset:// or a base64 data URI"
            )
        content.append({"type": field, field: {"url": url}, "role": role})
    body: dict[str, Any] = {"model": model.strip(), "content": content}
    if ratio is not None:
        body["ratio"] = ratio
    if duration is not None:
        body["duration"] = duration
    if generate_audio is not None:
        body["generate_audio"] = generate_audio
    if task_type is not None:
        body["omni_reference_task_type"] = task_type
    return body


def _seedance_runtime_profile(
) -> tuple[frozenset[str] | None, tuple[int, int] | None]:
    raw_ratios = os.environ.get("SEEDANCE_ALLOWED_RATIOS")
    allowed_ratios = (
        frozenset(item.strip() for item in raw_ratios.split(",") if item.strip())
        if raw_ratios is not None
        else None
    )
    minimum_raw = os.environ.get("SEEDANCE_MIN_DURATION")
    maximum_raw = os.environ.get("SEEDANCE_MAX_DURATION")
    if (minimum_raw is None) != (maximum_raw is None):
        raise AdapterFailure(
            "Seedance duration profile is incomplete",
            category="configuration",
            code="invalid_model_profile",
            submitted=False,
            detail="SEEDANCE_MIN_DURATION and SEEDANCE_MAX_DURATION must be set together",
        )
    try:
        duration_range = (
            (int(minimum_raw), int(maximum_raw))
            if minimum_raw is not None and maximum_raw is not None
            else None
        )
    except ValueError as exc:
        raise AdapterFailure(
            "Seedance duration profile is invalid",
            category="configuration",
            code="invalid_model_profile",
            submitted=False,
            detail="Seedance duration profile must be integer seconds",
        ) from exc
    if allowed_ratios is not None and (
        not allowed_ratios or not allowed_ratios <= SEEDANCE_RATIOS
    ):
        raise AdapterFailure(
            "Seedance ratio profile is invalid",
            category="configuration",
            code="invalid_model_profile",
            submitted=False,
            detail="SEEDANCE_ALLOWED_RATIOS contains unsupported ratios",
        )
    if duration_range is not None and not (
        1 <= duration_range[0] <= duration_range[1] <= 30
    ):
        raise AdapterFailure(
            "Seedance duration profile is invalid",
            category="configuration",
            code="invalid_model_profile",
            submitted=False,
            detail="Seedance duration profile must be within 1..30 seconds",
        )
    return allowed_ratios, duration_range


def compile_minimax_h3_payload(
    job: Mapping[str, Any],
    *,
    model: str,
    reference_urls: Sequence[str] = (),
    reference_roles: Sequence[str] = (),
    allowed_ratios: Collection[str] | None = None,
    allowed_resolutions: Collection[str] | None = None,
    duration_range: tuple[int, int] | None = None,
) -> dict[str, Any]:
    """Compile a video job into the official MiniMax video-generation task body.

    ``model`` is mandatory for the same reason it is for Seedance: which release
    is enabled, and what it accepts, is deployment configuration, never an
    assumption made here.
    """
    prompt, parameters = _require_job(job, "video")
    if not isinstance(model, str) or not model.strip():
        raise ValueError("MiniMax video model must be explicitly configured")
    references = job.get("references", [])
    if not isinstance(references, list) or len(reference_urls) != len(references):
        raise ValueError("MiniMax reference URLs must match job references")
    if len(reference_roles) != len(reference_urls):
        raise ValueError("MiniMax reference roles must match job references")
    if Path(job["outputs"][0]).suffix.casefold() != ".mp4":
        raise ValueError("MiniMax video adapter requires an MP4 target")
    parameters = _take(
        parameters, {"duration", "ratio", "resolution", "prompt_language"}
    )
    prompt_language = _pop_prompt_language(parameters)

    duration = parameters.get("duration")
    if not isinstance(duration, int) or isinstance(duration, bool):
        raise ValueError("MiniMax video duration must be an integer number of seconds")
    minimum, maximum = (1, 30) if duration_range is None else duration_range
    if not 1 <= minimum <= maximum <= 30 or not minimum <= duration <= maximum:
        raise ValueError("MiniMax video duration is outside the configured model profile")

    resolution = parameters.get("resolution")
    if not isinstance(resolution, str) or resolution.strip() not in MINIMAX_VIDEO_RESOLUTIONS:
        raise ValueError("MiniMax video resolution is outside the supported profile")
    configured_resolutions = (
        set(MINIMAX_VIDEO_RESOLUTIONS)
        if allowed_resolutions is None
        else set(allowed_resolutions)
    )
    if (
        not configured_resolutions
        or not configured_resolutions <= MINIMAX_VIDEO_RESOLUTIONS
        or resolution.strip() not in configured_resolutions
    ):
        raise ValueError("MiniMax video resolution is outside the configured model profile")

    ratio = parameters.get("ratio")
    if ratio is not None:
        if not isinstance(ratio, str) or ratio.strip() not in MINIMAX_VIDEO_RATIOS:
            raise ValueError("MiniMax video ratio is outside the supported profile")
        configured_ratios = (
            set(MINIMAX_VIDEO_RATIOS)
            if allowed_ratios is None
            else set(allowed_ratios)
        )
        if (
            not configured_ratios
            or not configured_ratios <= MINIMAX_VIDEO_RATIOS
            or ratio.strip() not in configured_ratios
        ):
            raise ValueError("MiniMax video ratio is outside the configured model profile")

    counters = {"image_url": 0, "video_url": 0, "audio_url": 0}
    labels = {"image_url": "Picture", "video_url": "Video", "audio_url": "Audio"}
    reference_tokens: list[str] = []
    for role in reference_roles:
        field = MINIMAX_VIDEO_ROLES.get(role)
        if field is None:
            raise ValueError(f"unsupported MiniMax reference role: {role}")
        counters[field] += 1
        reference_tokens.append(f"<{labels[field]} {counters[field]}>")
    if all(role not in {"first_frame", "last_frame"} for role in reference_roles):
        for field, limit in MINIMAX_H3_REFERENCE_LIMITS.items():
            if counters[field] > limit:
                detail = (
                    f"MiniMax H3 accepts at most {limit} {field} reference"
                    + ("s" if limit != 1 else "")
                )
                raise AdapterError(
                    detail,
                    category="invalid_request",
                    code="too_many_references",
                    retryable=False,
                    submitted=False,
                    detail=detail,
                )
    text = _prompt_with_reference_contract(
        prompt,
        job,
        prompt_language=prompt_language,
        reference_tokens=reference_tokens,
    )
    if len(text) > MINIMAX_VIDEO_PROMPT_LIMIT:
        raise ValueError("MiniMax video prompt exceeds the provider limit")
    content: list[dict[str, Any]] = [{"type": "text", "text": text}]
    seen_roles: list[str] = []
    for index, url in enumerate(reference_urls):
        role = reference_roles[index]
        if role not in MINIMAX_VIDEO_ROLES:
            raise ValueError(f"unsupported MiniMax reference role: {role}")
        if role in {"first_frame", "last_frame"} and role in seen_roles:
            raise ValueError(f"MiniMax accepts one {role} reference")
        seen_roles.append(role)
        if not isinstance(url, str) or not url:
            raise ValueError("MiniMax reference URL must be non-empty")
        parsed = urllib.parse.urlparse(url)
        if not (
            (parsed.scheme == "https" and parsed.netloc)
            or (parsed.scheme == "mm_file" and parsed.netloc and not parsed.path)
            or _is_inline_reference(url)
        ):
            raise ValueError(
                "MiniMax reference URL must be HTTPS, mm_file:// or a base64 data URI"
            )
        field = MINIMAX_VIDEO_ROLES[role]
        content.append({"type": field, field: {"url": url}, "role": role})
    frame_roles = {"first_frame", "last_frame"}
    reference_roles_present = {"reference_image", "reference_video", "reference_audio"}
    if frame_roles.intersection(seen_roles) and reference_roles_present.intersection(
        seen_roles
    ):
        raise ValueError(
            "MiniMax frame conditioning cannot be mixed with reference conditioning"
        )
    if ratio is None and len(content) == 1:
        raise ValueError("MiniMax text-to-video requires an explicit ratio")
    body: dict[str, Any] = {
        "model": model.strip(),
        "content": content,
        "duration": duration,
        "resolution": resolution.strip(),
    }
    if ratio is not None:
        if ratio.strip() == "adaptive" and len(content) == 1:
            raise ValueError("MiniMax text-to-video cannot use an adaptive ratio")
        body["ratio"] = ratio.strip()
    return body


def _minimax_video_runtime_profile() -> tuple[
    frozenset[str] | None, frozenset[str] | None, tuple[int, int] | None
]:
    def _set(names: Sequence[str], supported: Collection[str]) -> frozenset[str] | None:
        chosen_name = next((name for name in names if name in os.environ), None)
        if chosen_name is None:
            return None
        raw = os.environ[chosen_name]
        values = frozenset(item.strip() for item in raw.split(",") if item.strip())
        if not values or not values <= set(supported):
            raise AdapterFailure(
                f"MiniMax video profile is invalid: {chosen_name}",
                category="configuration",
                code="invalid_model_profile",
                submitted=False,
                detail=f"MiniMax video profile is invalid: {chosen_name}",
            )
        return values

    allowed_ratios = _set(
        ("MINIMAX_VIDEO_ALLOWED_RATIOS", "MINIMAX_VIDEO_RATIOS"),
        MINIMAX_VIDEO_RATIOS,
    )
    allowed_resolutions = _set(
        ("MINIMAX_VIDEO_ALLOWED_RESOLUTIONS", "MINIMAX_VIDEO_RESOLUTIONS"),
        MINIMAX_VIDEO_RESOLUTIONS,
    )
    minimum_raw = os.environ.get("MINIMAX_VIDEO_MIN_DURATION")
    maximum_raw = os.environ.get("MINIMAX_VIDEO_MAX_DURATION")
    if (minimum_raw is None) != (maximum_raw is None):
        raise AdapterFailure(
            "MiniMax video duration profile is incomplete",
            category="configuration",
            code="invalid_model_profile",
            submitted=False,
            detail="MINIMAX_VIDEO_MIN_DURATION and MINIMAX_VIDEO_MAX_DURATION must be set together",
        )
    try:
        duration_range = (
            (int(minimum_raw), int(maximum_raw))
            if minimum_raw is not None and maximum_raw is not None
            else None
        )
    except ValueError as exc:
        raise AdapterFailure(
            "MiniMax video duration profile is invalid",
            category="configuration",
            code="invalid_model_profile",
            submitted=False,
            detail="MiniMax video duration profile must be integer seconds",
        ) from exc
    if duration_range is not None and not (
        1 <= duration_range[0] <= duration_range[1] <= 30
    ):
        raise AdapterFailure(
            "MiniMax video duration profile is invalid",
            category="configuration",
            code="invalid_model_profile",
            submitted=False,
            detail="MiniMax video duration profile must be within 1..30 seconds",
        )
    return allowed_ratios, allowed_resolutions, duration_range


def compile_gpt_image_2_payload(job: Mapping[str, Any]) -> dict[str, Any]:
    """Compile an image job into GPT Image 2 generation/edit fields."""
    prompt, parameters = _require_job(job, "image", max_outputs=16)
    parameters = _take(
        parameters,
        {
            "width",
            "height",
            "size",
            "quality",
            "background",
            "moderation",
            "prompt_language",
        },
    )
    prompt_language = _pop_prompt_language(parameters)
    prompt = _prompt_with_reference_contract(
        prompt, job, prompt_language=prompt_language
    )
    if len(prompt) > 32000:
        raise ValueError("GPT Image prompt exceeds the provider limit")
    width = parameters.pop("width", None)
    height = parameters.pop("height", None)
    if (width is None) != (height is None) or (width is not None and "size" in parameters):
        raise ValueError("use either both width/height or size")
    if width is not None:
        if not isinstance(width, int) or not isinstance(height, int) or width <= 0 or height <= 0:
            raise ValueError("image dimensions must be positive integers")
        if width % 16 or height % 16 or not (1 / 3 <= width / height <= 3):
            raise ValueError("GPT Image dimensions must be divisible by 16 with ratio between 1:3 and 3:1")
        parameters["size"] = f"{width}x{height}"
    size = parameters.get("size")
    if size != "auto" and size is not None:
        if not isinstance(size, str) or "x" not in size:
            raise ValueError("GPT Image size is invalid")
        try:
            parsed_width, parsed_height = (int(part) for part in size.split("x", 1))
        except ValueError as exc:
            raise ValueError("GPT Image size is invalid") from exc
        if (
            parsed_width <= 0
            or parsed_height <= 0
            or parsed_width % 16
            or parsed_height % 16
            or not (1 / 3 <= parsed_width / parsed_height <= 3)
            or parsed_width > 3840
            or parsed_height > 3840
            or not (
                GPT_IMAGE_MIN_PIXELS
                <= parsed_width * parsed_height
                <= GPT_IMAGE_MAX_PIXELS
            )
        ):
            raise ValueError("GPT Image size violates official dimension constraints")
    if parameters.get("background") == "transparent":
        raise ValueError("GPT Image 2 transparent background is unsupported")
    if "background" in parameters and parameters["background"] not in {"auto", "opaque"}:
        raise ValueError("GPT Image background is invalid")
    if "quality" in parameters and parameters["quality"] not in {"auto", "low", "medium", "high"}:
        raise ValueError("GPT Image quality is invalid")
    if "moderation" in parameters and parameters["moderation"] not in {"auto", "low"}:
        raise ValueError("GPT Image moderation is invalid")
    formats = {".png": "png", ".jpg": "jpeg", ".jpeg": "jpeg", ".webp": "webp"}
    output_formats: set[str] = set()
    for target in job["outputs"]:
        suffix = Path(target).suffix.casefold()
        if suffix not in formats:
            raise ValueError("unsupported GPT Image output extension")
        output_formats.add(formats[suffix])
    if len(output_formats) != 1:
        raise ValueError("GPT Image outputs in one job must share an output format")
    output_format = next(iter(output_formats))
    references = job.get("references", [])
    if not isinstance(references, list) or len(references) > 16:
        raise ValueError("GPT Image accepts at most sixteen references")
    if any(
        not isinstance(reference, str)
        or Path(reference).suffix.casefold() not in {".png", ".jpg", ".jpeg", ".webp"}
        for reference in references
    ):
        raise ValueError("GPT Image references must be supported image files")
    return {
        "model": OPENAI_MODEL,
        "prompt": prompt,
        "n": len(job["outputs"]),
        "output_format": output_format,
        **parameters,
    }


MINIMAX_SPEECH_EMOTIONS = {
    "happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral",
}


def compile_minimax_speech_payload(job: Mapping[str, Any]) -> dict[str, Any]:
    """Compile a tts job into the official MiniMax speech JSON body.

    The voice catalogue is deliberately not enumerated here. Which preset voices
    an account can reach depends on the model and the account, no published list
    is authoritative for both, and a list frozen into this file would either
    refuse a voice that works or vouch for one that does not. The document owns
    the value and a reviewer reads it; the adapter only checks its shape.
    """

    text, parameters = _require_job(job, "tts")
    parameters = _take(
        parameters,
        {"model", "voice_id", "speed", "vol", "pitch", "emotion",
         "sample_rate", "bitrate", "format"},
    )
    model = parameters.pop("model", "")
    if not isinstance(model, str) or not model.strip():
        raise ValueError("MiniMax speech model must be explicitly configured")
    voice_id = parameters.pop("voice_id", "")
    if not isinstance(voice_id, str) or not voice_id.strip() or voice_id != voice_id.strip():
        raise ValueError("MiniMax speech requires a confirmed voice_id")
    if len(text) > MINIMAX_SPEECH_TEXT_LIMIT:
        raise ValueError("MiniMax speech text exceeds the provider limit")

    target_format = Path(job["outputs"][0]).suffix.casefold().lstrip(".")
    requested_format = parameters.pop("format", target_format)
    if requested_format != target_format or requested_format not in {"mp3", "wav"}:
        raise ValueError("MiniMax output format must match a supported target extension")
    sample_rate = parameters.pop("sample_rate", 32000)
    bitrate = parameters.pop("bitrate", 128000)
    if sample_rate not in {16000, 24000, 32000, 44100}:
        raise ValueError("unsupported MiniMax sample rate")
    if bitrate not in {32000, 64000, 128000, 256000}:
        raise ValueError("unsupported MiniMax bitrate")

    voice_setting: dict[str, Any] = {"voice_id": voice_id}
    emotion = parameters.pop("emotion", None)
    if emotion is not None:
        if emotion not in MINIMAX_SPEECH_EMOTIONS:
            raise ValueError("unsupported MiniMax speech emotion")
        voice_setting["emotion"] = emotion
    for name, low, high in (("speed", 0.5, 2.0), ("vol", 0.1, 10.0)):
        value = parameters.pop(name, None)
        if value is None:
            continue
        if isinstance(value, bool) or not isinstance(value, (int, float)):
            raise ValueError(f"MiniMax speech {name} must be a number")
        if not low <= float(value) <= high:
            raise ValueError(f"MiniMax speech {name} is outside the supported range")
        voice_setting[name] = float(value)
    pitch = parameters.pop("pitch", None)
    if pitch is not None:
        if isinstance(pitch, bool) or not isinstance(pitch, int) or not -12 <= pitch <= 12:
            raise ValueError("MiniMax speech pitch is outside the supported range")
        voice_setting["pitch"] = pitch

    return {
        "model": model.strip(),
        "text": text,
        "stream": False,
        "output_format": "hex",
        "voice_setting": voice_setting,
        "audio_setting": {
            "sample_rate": sample_rate,
            "bitrate": bitrate,
            "format": requested_format,
        },
    }


def compile_minimax_music_payload(job: Mapping[str, Any]) -> dict[str, Any]:
    """Compile an audio job into the official MiniMax Music 3.0 JSON body."""
    prompt, parameters = _require_job(job, "music")
    parameters = _take(
        parameters,
        {"lyrics", "sample_rate", "bitrate", "format", "lyrics_optimizer", "is_instrumental"},
    )
    target_format = Path(job["outputs"][0]).suffix.casefold().lstrip(".")
    requested_format = parameters.pop("format", target_format)
    if requested_format != target_format or requested_format not in {"mp3", "wav"}:
        raise ValueError("MiniMax output format must match a supported target extension")
    lyrics = parameters.pop("lyrics", None)
    instrumental = parameters.pop("is_instrumental", False)
    optimizer = parameters.pop("lyrics_optimizer", False)
    if not isinstance(instrumental, bool) or not isinstance(optimizer, bool):
        raise ValueError("MiniMax boolean parameters must be booleans")
    if optimizer:
        raise ValueError("MiniMax lyrics_optimizer is forbidden for confirmed production")
    if instrumental and lyrics not in {None, ""}:
        raise ValueError("MiniMax instrumental music must not carry lyrics")
    if not instrumental and (not isinstance(lyrics, str) or not lyrics.strip()):
        raise ValueError("MiniMax vocal music requires confirmed lyrics")
    if len(prompt) > 2000 or (isinstance(lyrics, str) and len(lyrics) > 3500):
        raise ValueError("MiniMax prompt or lyrics exceeds the provider limit")
    sample_rate = parameters.pop("sample_rate", 44100)
    bitrate = parameters.pop("bitrate", 256000)
    if sample_rate not in {16000, 24000, 32000, 44100}:
        raise ValueError("unsupported MiniMax sample rate")
    if bitrate not in {32000, 64000, 128000, 256000}:
        raise ValueError("unsupported MiniMax bitrate")
    body: dict[str, Any] = {
        "model": MINIMAX_MUSIC_MODEL,
        "prompt": prompt,
        "stream": False,
        "output_format": "hex",
        "audio_setting": {
            "sample_rate": sample_rate,
            "bitrate": bitrate,
            "format": requested_format,
        },
        "lyrics_optimizer": False,
        "is_instrumental": instrumental,
    }
    if lyrics is not None:
        if not isinstance(lyrics, str):
            raise ValueError("MiniMax lyrics must be a string")
        body["lyrics"] = lyrics
    return body


def _base_url(env_name: str, default: str) -> str:
    value = os.environ.get(env_name, default).rstrip("/")
    parsed = urllib.parse.urlparse(value)
    if parsed.scheme != "https" or not parsed.netloc or parsed.username or parsed.password:
        raise AdapterFailure(
            "provider base URL is invalid",
            category="configuration",
            code="invalid_base_url",
            submitted=False,
            detail=f"{env_name} must be an HTTPS base URL without credentials",
        )
    return value


def _credential(name: str) -> str:
    value = os.environ.get(name)
    if not value:
        raise AdapterFailure(
            "provider credential is not configured",
            category="configuration",
            code="missing_credential",
            submitted=False,
            detail=f"{name} is not configured",
        )
    return value


def _is_timeout_error(exc: BaseException) -> bool:
    return isinstance(exc, (TimeoutError, socket.timeout)) or (
        isinstance(exc, urllib.error.URLError)
        and isinstance(getattr(exc, "reason", None), (TimeoutError, socket.timeout))
    )


def _request_json(
    url: str,
    *,
    provider: str,
    method: str = "POST",
    body: Mapping[str, Any] | None = None,
    token: str,
) -> tuple[dict[str, Any], Mapping[str, str]]:
    data = None if body is None else json.dumps(body, ensure_ascii=False).encode("utf-8")
    request = urllib.request.Request(url, data=data, method=method)  # noqa: S310  # HTTPS enforced by _base_url
    request.add_header("Authorization", f"Bearer {token}")
    if body is not None:
        request.add_header("Content-Type", "application/json")
    try:
        with urllib.request.urlopen(request, timeout=180) as response:  # noqa: S310  # HTTPS enforced by _base_url
            raw = response.read(MAX_JSON_RESPONSE + 1)
            headers = dict(response.headers.items())
    except urllib.error.HTTPError as exc:
        raise _http_failure(provider, exc) from exc
    except (TimeoutError, socket.timeout, urllib.error.URLError, OSError) as exc:
        if _is_timeout_error(exc):
            raise AdapterFailure(
                f"{provider} HTTP request timed out",
                category="timeout",
                code="request_timeout",
                retryable=True,
            ) from exc
        raise AdapterFailure(
            f"{provider} HTTP request failed",
            category="network",
            code="network_error",
            retryable=True,
        ) from exc
    if len(raw) > MAX_JSON_RESPONSE:
        raise AdapterFailure(
            f"{provider} response is too large", code="response_too_large"
        )
    try:
        document = json.loads(raw)
    except (UnicodeError, json.JSONDecodeError) as exc:
        raise AdapterFailure(
            f"{provider} returned invalid JSON", code="invalid_json"
        ) from exc
    if not isinstance(document, dict):
        raise AdapterFailure(
            f"{provider} returned an invalid response", code="invalid_response"
        )
    return document, headers


def _read_reference(path: Path) -> bytes:
    try:
        before = path.lstat()
        if stat.S_ISLNK(before.st_mode) or not stat.S_ISREG(before.st_mode):
            raise ValueError("reference is not a regular file")
        if before.st_size > MAX_REFERENCE_BYTES:
            raise ValueError("reference exceeds the provider input size limit")
        # Windows opens files in text mode unless told otherwise, which stops the
        # read at the first 0x1A byte -- the seventh byte of every PNG signature.
        flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0)
        descriptor = os.open(path, flags)
        try:
            opened = os.fstat(descriptor)
            if (
                not stat.S_ISREG(opened.st_mode)
                or (opened.st_dev, opened.st_ino) != (before.st_dev, before.st_ino)
            ):
                raise ValueError("reference changed while opening")
            chunks: list[bytes] = []
            size = 0
            while chunk := os.read(descriptor, 1024 * 1024):
                size += len(chunk)
                if size > MAX_REFERENCE_BYTES:
                    raise ValueError("reference exceeds the provider input size limit")
                chunks.append(chunk)
            return b"".join(chunks)
        finally:
            os.close(descriptor)
    except OSError as exc:
        raise AdapterFailure(
            "could not read reference file",
            category="invalid_request",
            code="unreadable_reference",
            submitted=False,
            detail="could not read reference file",
        ) from exc


def _multipart(fields: Mapping[str, Any], paths: Sequence[Path]) -> tuple[bytes, str]:
    boundary = "short-drama-" + secrets.token_hex(16)
    chunks: list[bytes] = []
    for name, value in fields.items():
        chunks.extend(
            [
                f"--{boundary}\r\n".encode(),
                f'Content-Disposition: form-data; name="{name}"\r\n\r\n'.encode(),
                str(value).lower().encode() if isinstance(value, bool) else str(value).encode("utf-8"),
                b"\r\n",
            ]
        )
    image_limit = INLINE_REFERENCE_LIMITS["image_url"]
    for path in paths:
        content = _read_reference(path)
        if not content:
            raise AdapterFailure(
                "OpenAI reference image is empty",
                category="invalid_request",
                code="empty_reference",
                submitted=False,
                detail="reference image is empty",
            )
        if len(content) > image_limit:
            raise AdapterFailure(
                f"OpenAI reference image exceeds the {image_limit // (1024 * 1024)}MB limit",
                category="invalid_request",
                code="reference_too_large",
                submitted=False,
                detail=f"reference image exceeds the {image_limit // (1024 * 1024)}MB limit",
            )
        try:
            _validate_media_content(path.name, content)
        except AdapterFailure as exc:
            raise AdapterFailure(
                str(exc),
                category="invalid_request",
                code="invalid_reference_media",
                submitted=False,
                detail="reference file bytes do not match its file extension",
            ) from exc
        media_type = (
            INLINE_REFERENCE_MIME.get(path.suffix.casefold())
            or mimetypes.guess_type(path.name)[0]
            or "application/octet-stream"
        )
        safe_filename = re.sub(r'[\x00-\x1f\x7f"\\]', "_", path.name) or "reference"
        chunks.extend(
            [
                f"--{boundary}\r\n".encode(),
                f'Content-Disposition: form-data; name="image[]"; filename="{safe_filename}"\r\n'.encode(),
                f"Content-Type: {media_type}\r\n\r\n".encode(),
                content,
                b"\r\n",
            ]
        )
    chunks.append(f"--{boundary}--\r\n".encode())
    encoded = b"".join(chunks)
    if len(encoded) > MAX_MULTIPART_BYTES:
        raise AdapterFailure(
            "multipart provider input exceeds the total size limit",
            category="invalid_request",
            code="multipart_too_large",
            submitted=False,
            detail="multipart provider input exceeds the total size limit",
        )
    return encoded, f"multipart/form-data; boundary={boundary}"


def _reference_paths(job: Mapping[str, Any]) -> list[Path]:
    raw_root = job.get("project_root")
    if not isinstance(raw_root, str) or not Path(raw_root).is_absolute():
        raise ValueError("project_root is invalid")
    root = Path(raw_root).resolve()
    if not root.is_dir():
        raise ValueError("project_root is invalid")
    result: list[Path] = []
    for reference in job.get("references", []):
        if not isinstance(reference, str):
            raise ValueError("reference path is invalid")
        path = (root / reference).resolve()
        try:
            path.relative_to(root)
        except ValueError as exc:
            raise ValueError("reference escapes project root") from exc
        if not path.is_file() or path.is_symlink():
            raise ValueError("reference is not a regular file")
        result.append(path)
    return result


def _binding_roles(
    job: Mapping[str, Any], *, allowed: Mapping[str, str], provider: str
) -> list[str]:
    """The provider role of each reference, taken from the confirmed job.

    `role` is the production-side translation of the creator document's 用途, so
    it is the job -- not this adapter -- that decides what a picture is for.
    """
    bindings = job.get("reference_bindings", [])
    references = job.get("references", [])
    if not isinstance(bindings, list) or len(bindings) != len(references):
        raise AdapterFailure(
            f"{provider} references need one reference_bindings entry each, "
            "carrying the provider role for that file",
            category="configuration",
            code="missing_reference_roles",
            submitted=False,
            detail=f"{provider} references require matching reference_bindings",
        )
    roles: list[str] = []
    for binding in bindings:
        role = binding.get("role") if isinstance(binding, Mapping) else None
        if not isinstance(role, str) or role not in allowed:
            raise AdapterFailure(
                f"{provider} reference role must be one of "
                + ", ".join(sorted(allowed))
                + f"; got {role!r}",
                category="configuration",
                code="invalid_reference_role",
                submitted=False,
                detail=f"{provider} reference role is unsupported",
            )
        roles.append(role)
    return roles


def _inline_reference_urls(
    paths: Sequence[Path], roles: Sequence[str], *, allowed: Mapping[str, str], provider: str
) -> list[str]:
    """Encode local project references as `data:` URIs the provider accepts."""
    urls: list[str] = []
    total = 0
    for path, role in zip(paths, roles):
        field = allowed[role]
        suffix = path.suffix.casefold()
        mime = INLINE_REFERENCE_MIME.get(suffix)
        expected = field.split("_", 1)[0]
        if mime is None or not mime.startswith(expected):
            raise AdapterFailure(
                f"{provider} {role} does not accept a {suffix or 'suffixless'} file",
                category="configuration",
                code="invalid_reference_type",
                submitted=False,
                detail=f"{provider} {role} does not accept a {suffix or 'suffixless'} file",
            )
        try:
            content = path.read_bytes()
        except OSError as exc:
            raise AdapterFailure(
                f"{provider} could not read a project reference",
                category="configuration",
                code="unreadable_reference",
                submitted=False,
                detail=f"{provider} could not read a project reference",
            ) from exc
        if not content:
            raise AdapterFailure(
                f"{provider} project reference is empty",
                category="configuration",
                code="empty_reference",
                submitted=False,
                detail=f"{provider} project reference is empty",
            )
        # The bytes have to be the media type the extension claims, or the
        # provider rejects a request this adapter said was well formed.
        try:
            _validate_media_content(path.name, content)
        except AdapterFailure as exc:
            raise AdapterFailure(
                str(exc),
                category="configuration",
                code=(
                    "invalid_reference_media"
                    if exc.code == "adapter_failure"
                    else exc.code
                ),
                submitted=False,
                detail="reference file bytes do not match its file extension",
            ) from exc
        limit = INLINE_REFERENCE_LIMITS[field]
        if len(content) > limit:
            raise AdapterFailure(
                f"{provider} reference exceeds the {limit // (1024 * 1024)}MB inline "
                "limit; host it and bind an HTTPS URL instead",
                category="configuration",
                code="reference_too_large",
                submitted=False,
                detail=f"{provider} reference exceeds the {limit // (1024 * 1024)}MB inline limit",
            )
        encoded = base64.b64encode(content).decode("ascii")
        total += len(encoded)
        if total > INLINE_REFERENCE_BODY_LIMIT:
            raise AdapterFailure(
                f"{provider} inline references exceed the request body limit; "
                "host the largest ones and bind HTTPS URLs instead",
                category="configuration",
                code="reference_body_too_large",
                submitted=False,
                detail=f"{provider} inline references exceed the 64MB request body limit",
            )
        urls.append(f"data:{mime};base64,{encoded}")
    return urls


def _is_inline_reference(url: str) -> bool:
    return bool(re.fullmatch(r"data:[\w.+-]+/[\w.+-]+;base64,[A-Za-z0-9+/]+=*", url))


def _validate_media_content(target: str, content: bytes) -> None:
    suffix = Path(target).suffix.casefold()
    signatures = {
        ".png": content.startswith(b"\x89PNG\r\n\x1a\n"),
        ".jpg": content.startswith(b"\xff\xd8\xff"),
        ".jpeg": content.startswith(b"\xff\xd8\xff"),
        ".webp": len(content) >= 12
        and content.startswith(b"RIFF")
        and content[8:12] == b"WEBP",
        ".mp3": content.startswith(b"ID3")
        or (
            len(content) >= 2
            and content[0] == 0xFF
            and content[1] & 0xE0 == 0xE0
        ),
        ".wav": len(content) >= 12
        and content.startswith(b"RIFF")
        and content[8:12] == b"WAVE",
        ".flac": content.startswith(b"fLaC"),
        ".m4a": len(content) >= 8 and content[4:8] == b"ftyp",
        ".aac": content.startswith(b"ID3")
        or (
            len(content) >= 2
            and content[0] == 0xFF
            and (content[1] & 0xF6) == 0xF0
        ),
        ".opus": content.startswith(b"OggS") and b"OpusHead" in content[:64],
        ".mp4": len(content) >= 12 and content[4:8] == b"ftyp",
        ".mov": len(content) >= 8
        and content[4:8]
        in {b"ftyp", b"moov", b"mdat", b"wide", b"free", b"skip", b"pnot"},
        ".webm": content.startswith(b"\x1a\x45\xdf\xa3"),
    }
    if not signatures.get(suffix, False):
        raise AdapterFailure("provider output does not match the target media type")


def _output_root(job: Mapping[str, Any]) -> Path:
    raw = job.get("output_root")
    if not isinstance(raw, str):
        raise ValueError("output_root is invalid")
    root = Path(raw)
    if not root.is_absolute():
        raise ValueError("output_root is invalid")
    try:
        details = root.lstat()
    except OSError as exc:
        raise ValueError("output_root is missing") from exc
    if stat.S_ISLNK(details.st_mode) or not stat.S_ISDIR(details.st_mode):
        raise ValueError("output_root is unsafe")
    return root


def _temporary_output(
    job: Mapping[str, Any], target: str, content: bytes, *, index: int | None = None
) -> Path:
    if not content or len(content) > MAX_OUTPUT_BYTES:
        raise AdapterFailure("provider output is too large")
    _validate_media_content(target, content)
    stem = "result" if index is None else f"result-{index}"
    path = _output_root(job) / (stem + Path(target).suffix.casefold())
    with path.open("xb") as handle:
        handle.write(content)
    return path


def _download(
    job: Mapping[str, Any],
    url: str,
    target: str,
    *,
    provider: str = "seedance",
) -> Path:
    parsed = urllib.parse.urlparse(url)
    if parsed.scheme != "https" or not parsed.netloc:
        raise AdapterFailure("provider output URL is invalid")
    path = _output_root(job) / ("result" + Path(target).suffix.casefold())
    size = 0
    try:
        with urllib.request.urlopen(url, timeout=180) as response, path.open("xb") as handle:  # noqa: S310  # HTTPS checked above
            while chunk := response.read(1024 * 1024):
                size += len(chunk)
                if size > MAX_OUTPUT_BYTES:
                    raise AdapterFailure("provider output is too large")
                handle.write(chunk)
    except AdapterFailure:
        path.unlink(missing_ok=True)
        raise
    except urllib.error.HTTPError as exc:
        path.unlink(missing_ok=True)
        raise _http_failure(provider, exc) from exc
    except (TimeoutError, socket.timeout, urllib.error.URLError, OSError) as exc:
        path.unlink(missing_ok=True)
        if _is_timeout_error(exc):
            raise AdapterFailure(
                "provider output download timed out",
                category="timeout",
                code="download_timeout",
                retryable=True,
            ) from exc
        raise AdapterFailure(
            "provider output download failed",
            category="network",
            code="download_failed",
            retryable=True,
        ) from exc
    if size == 0:
        raise AdapterFailure("provider output is empty")
    with path.open("rb") as handle:
        _validate_media_content(target, handle.read(64))
    return path


def _record_handle(job: Mapping[str, Any], provider_job_id: str) -> None:
    """Write the provider task id where the caller can find it after a crash.

    A video task is billed at submission. Everything after that — polling,
    downloading — can be interrupted, and without this the caller is left with a
    live, already-paid task it has no id for. Written before the first poll, and
    deliberately best-effort: failing to record the handle must not fail a task
    that was submitted successfully.
    """

    destination = job.get("handle_path")
    if not isinstance(destination, str) or not destination:
        return
    try:
        path = Path(destination)
        path.parent.mkdir(parents=True, exist_ok=True)
        temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
        temporary.write_text(
            json.dumps({"provider_job_id": provider_job_id}, ensure_ascii=True),
            encoding="utf-8",
        )
        temporary.replace(path)
    except OSError:
        return


def _collect_target(job: Mapping[str, Any]) -> str | None:
    value = job.get("collect_provider_job_id")
    if value is None or value == "":
        return None
    token = _safe_public_id(value)
    if token is None:
        raise ValueError("collect_provider_job_id is invalid")
    return token


def _polling_config(
    interval_env: str,
    timeout_env: str,
    *,
    provider: str,
) -> tuple[float, float]:
    try:
        interval = float(os.environ.get(interval_env, "5"))
        timeout_seconds = float(os.environ.get(timeout_env, "1800"))
    except ValueError as exc:
        raise AdapterFailure(
            f"{provider} polling configuration is invalid",
            category="configuration",
            code="invalid_polling_config",
            submitted=False,
            detail=f"{interval_env} and {timeout_env} must be positive numbers",
        ) from exc
    if (
        not math.isfinite(interval)
        or interval <= 0
        or not math.isfinite(timeout_seconds)
        or timeout_seconds <= 0
    ):
        raise AdapterFailure(
            f"{provider} polling configuration is invalid",
            category="configuration",
            code="invalid_polling_config",
            submitted=False,
            detail=f"{interval_env} and {timeout_env} must be positive numbers",
        )
    return interval, timeout_seconds


def _run_seedance(job: Mapping[str, Any]) -> tuple[Path, str]:
    token = _credential("ARK_API_KEY")
    base = _base_url("SEEDANCE_BASE_URL", SEEDANCE_BASE_URL)
    interval, timeout_seconds = _polling_config(
        "SEEDANCE_POLL_INTERVAL",
        "SEEDANCE_TIMEOUT_SECONDS",
        provider="Seedance",
    )
    collecting = _collect_target(job)
    if collecting is not None:
        return _poll_seedance(
            job,
            base=base,
            token=token,
            task_id=collecting,
            interval=interval,
            timeout_seconds=timeout_seconds,
        )
    model = os.environ.get("SEEDANCE_MODEL", "")
    references = _reference_paths(job)
    reference_roles = (
        _binding_roles(job, allowed=SEEDANCE_REFERENCE_ROLES, provider="Seedance")
        if references
        else []
    )
    reference_urls = _inline_reference_urls(
        references, reference_roles, allowed=SEEDANCE_REFERENCE_ROLES, provider="Seedance"
    )
    allowed_ratios, duration_range = _seedance_runtime_profile()
    body = compile_seedance_payload(
        job,
        model=model,
        reference_urls=reference_urls,
        reference_roles=reference_roles,
        allowed_ratios=allowed_ratios,
        duration_range=duration_range,
    )
    created, _ = _request_json(
        f"{base}/contents/generations/tasks",
        provider="seedance",
        body=body,
        token=token,
    )
    task_id = _safe_public_id(created.get("id"))
    if task_id is None:
        raise AdapterFailure(
            "Seedance did not return a task id", code="missing_task_id"
        )
    # Billed from here on. Record the id before the first poll.
    _record_handle(job, task_id)
    return _poll_seedance(
        job,
        base=base,
        token=token,
        task_id=task_id,
        interval=interval,
        timeout_seconds=timeout_seconds,
    )


def _poll_seedance(
    job: Mapping[str, Any],
    *,
    base: str,
    token: str,
    task_id: str,
    interval: float | None = None,
    timeout_seconds: float | None = None,
) -> tuple[Path, str]:
    if interval is None or timeout_seconds is None:
        interval, timeout_seconds = _polling_config(
            "SEEDANCE_POLL_INTERVAL",
            "SEEDANCE_TIMEOUT_SECONDS",
            provider="Seedance",
        )
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        status_doc, _ = _request_json(
            f"{base}/contents/generations/tasks/{urllib.parse.quote(task_id, safe='')}",
            provider="seedance",
            method="GET",
            token=token,
        )
        status = status_doc.get("status")
        if status == "succeeded":
            content = status_doc.get("content")
            url = content.get("video_url") if isinstance(content, Mapping) else None
            if not isinstance(url, str):
                raise AdapterFailure(
                    "Seedance succeeded without a video URL",
                    code="missing_video_url",
                    request_id=task_id,
                )
            return _download(
                job,
                url,
                job["outputs"][0],
                provider="seedance",
            ), task_id
        if isinstance(status, str) and status.casefold() in TERMINAL_FAILURES:
            raise AdapterFailure(
                "Seedance task failed",
                code="task_" + status.casefold(),
                request_id=task_id,
            )
        if status not in {"queued", "in_progress", "running", "processing", "pending"}:
            raise AdapterFailure(
                "Seedance returned an unknown task status",
                code="unknown_task_status",
                request_id=task_id,
            )
        time.sleep(interval)
    raise AdapterFailure(
        "Seedance task polling timed out",
        category="timeout",
        code="task_poll_timeout",
        request_id=task_id,
        retryable=True,
    )


def _run_openai(job: Mapping[str, Any]) -> tuple[Path | list[Path], str | None]:
    if _collect_target(job) is not None:
        raise AdapterFailure(
            "gpt-image-2 uses synchronous generation and cannot collect a prior task",
            category="invalid_request",
            code="collect_not_supported",
            submitted=False,
            detail="gpt-image-2 does not support collect",
        )
    token = _credential("OPENAI_API_KEY")
    body = compile_gpt_image_2_payload(job)
    base = _base_url("OPENAI_BASE_URL", OPENAI_BASE_URL)
    references = _reference_paths(job)
    if references:
        encoded, content_type = _multipart(body, references)
        request = urllib.request.Request(f"{base}/images/edits", data=encoded, method="POST")  # noqa: S310  # HTTPS enforced by _base_url
        request.add_header("Authorization", f"Bearer {token}")
        request.add_header("Content-Type", content_type)
        try:
            with urllib.request.urlopen(request, timeout=300) as response:  # noqa: S310  # HTTPS enforced by _base_url
                raw = response.read(MAX_JSON_RESPONSE + 1)
                request_id = _request_id(dict(response.headers.items()))
        except urllib.error.HTTPError as exc:
            raise _http_failure("gpt-image-2", exc) from exc
        except (TimeoutError, socket.timeout, urllib.error.URLError, OSError) as exc:
            if _is_timeout_error(exc):
                raise AdapterFailure(
                    "OpenAI HTTP request timed out",
                    category="timeout",
                    code="request_timeout",
                    retryable=True,
                ) from exc
            raise AdapterFailure(
                "OpenAI HTTP request failed",
                category="network",
                code="network_error",
                retryable=True,
            ) from exc
        if len(raw) > MAX_JSON_RESPONSE:
            raise AdapterFailure(
                "OpenAI response is too large",
                code="response_too_large",
                request_id=request_id,
            )
        try:
            result = json.loads(raw)
        except (UnicodeError, json.JSONDecodeError) as exc:
            raise AdapterFailure(
                "OpenAI returned invalid JSON",
                code="invalid_json",
                request_id=request_id,
            ) from exc
    else:
        result, headers = _request_json(
            f"{base}/images/generations",
            provider="gpt-image-2",
            body=body,
            token=token,
        )
        request_id = _request_id(headers)
    targets = job["outputs"]
    expected_count = len(targets)
    data = result.get("data") if isinstance(result, Mapping) else None
    if (
        not isinstance(data, list)
        or len(data) != expected_count
        or any(
            not isinstance(item, Mapping) or not isinstance(item.get("b64_json"), str)
            for item in data
        )
    ):
        raise AdapterFailure(
            "OpenAI did not return the requested images",
            code="missing_image",
            request_id=request_id,
        )
    decoded_images: list[bytes] = []
    for item in data:
        try:
            decoded_images.append(base64.b64decode(item["b64_json"], validate=True))
        except (ValueError, binascii.Error) as exc:
            raise AdapterFailure(
                "OpenAI returned invalid image data",
                code="invalid_image_data",
                request_id=request_id,
            ) from exc
    if expected_count == 1:
        return _temporary_output(job, targets[0], decoded_images[0]), request_id
    return (
        [
            _temporary_output(job, target, content, index=idx)
            for idx, (target, content) in enumerate(zip(targets, decoded_images), 1)
        ],
        request_id,
    )


def _run_minimax(job: Mapping[str, Any]) -> tuple[Path, str | None]:
    if _collect_target(job) is not None:
        raise AdapterFailure(
            "minimax-music uses synchronous generation and cannot collect a prior task",
            category="invalid_request",
            code="collect_not_supported",
            submitted=False,
            detail="minimax-music does not support collect",
        )
    token = _credential("MINIMAX_API_KEY")
    body = compile_minimax_music_payload(job)
    base = _base_url("MINIMAX_BASE_URL", MINIMAX_BASE_URL)
    result, _ = _request_json(
        f"{base}/music_generation",
        provider="minimax-music",
        body=body,
        token=token,
    )
    base_resp = result.get("base_resp")
    if not isinstance(base_resp, Mapping) or base_resp.get("status_code") != 0:
        raise AdapterFailure(
            "MiniMax music generation failed",
            code=_provider_code(result) or "generation_failed",
            request_id=_safe_token(result.get("trace_id")),
        )
    data = result.get("data")
    audio = data.get("audio") if isinstance(data, Mapping) else None
    if not isinstance(data, Mapping) or data.get("status") != 2 or not isinstance(audio, str):
        raise AdapterFailure(
            "MiniMax did not return audio data",
            code="missing_audio",
            request_id=_safe_token(result.get("trace_id")),
        )
    try:
        content = bytes.fromhex(audio)
    except ValueError as exc:
        raise AdapterFailure("MiniMax returned invalid audio data") from exc
    if not content:
        raise AdapterFailure("MiniMax returned empty audio data")
    trace_id = _safe_public_id(result.get("trace_id"))
    return (
        _temporary_output(job, job["outputs"][0], content),
        trace_id,
    )


def _run_minimax_speech(job: Mapping[str, Any]) -> tuple[Path, str | None]:
    if _collect_target(job) is not None:
        raise AdapterFailure(
            "minimax-speech uses synchronous generation and cannot collect a prior task",
            category="invalid_request",
            code="collect_not_supported",
            submitted=False,
            detail="minimax-speech does not support collect",
        )
    token = _credential("MINIMAX_API_KEY")
    body = compile_minimax_speech_payload(job)
    base = _base_url("MINIMAX_BASE_URL", MINIMAX_BASE_URL)
    result, _ = _request_json(
        f"{base}/t2a_v2",
        provider="minimax-speech",
        body=body,
        token=token,
    )
    base_resp = result.get("base_resp")
    if not isinstance(base_resp, Mapping) or base_resp.get("status_code") != 0:
        raise AdapterFailure(
            "MiniMax speech synthesis failed",
            code=_provider_code(result) or "generation_failed",
            request_id=_safe_token(result.get("trace_id")),
        )
    data = result.get("data")
    audio = data.get("audio") if isinstance(data, Mapping) else None
    if not isinstance(audio, str) or not audio:
        raise AdapterFailure(
            "MiniMax did not return audio data",
            code="missing_audio",
            request_id=_safe_token(result.get("trace_id")),
        )
    try:
        content = bytes.fromhex(audio)
    except ValueError as exc:
        raise AdapterFailure("MiniMax returned invalid audio data") from exc
    if not content:
        raise AdapterFailure("MiniMax returned empty audio data")
    trace_id = _safe_public_id(result.get("trace_id"))
    return (
        _temporary_output(job, job["outputs"][0], content),
        trace_id,
    )


def _run_minimax_video(job: Mapping[str, Any]) -> tuple[Path, str]:
    token = _credential("MINIMAX_API_KEY")
    base = _base_url("MINIMAX_VIDEO_BASE_URL", MINIMAX_VIDEO_BASE_URL)
    interval, timeout_seconds = _polling_config(
        "MINIMAX_VIDEO_POLL_INTERVAL",
        "MINIMAX_VIDEO_TIMEOUT_SECONDS",
        provider="MiniMax",
    )
    collecting = _collect_target(job)
    if collecting is not None:
        return _poll_minimax_video(
            job,
            base=base,
            token=token,
            task_id=collecting,
            interval=interval,
            timeout_seconds=timeout_seconds,
        )
    model = os.environ.get("MINIMAX_VIDEO_MODEL", "")
    references = _reference_paths(job)
    reference_roles = (
        _binding_roles(job, allowed=MINIMAX_VIDEO_ROLES, provider="MiniMax")
        if references
        else []
    )
    reference_urls = _inline_reference_urls(
        references, reference_roles, allowed=MINIMAX_VIDEO_ROLES, provider="MiniMax"
    )
    ratios, resolutions, duration_range = _minimax_video_runtime_profile()
    body = compile_minimax_h3_payload(
        job,
        model=model,
        reference_urls=reference_urls,
        reference_roles=reference_roles,
        allowed_ratios=ratios,
        allowed_resolutions=resolutions,
        duration_range=duration_range,
    )
    created, _ = _request_json(
        f"{base}/video_generation",
        provider="minimax-h3",
        body=body,
        token=token,
    )
    task_id = _safe_public_id(created.get("task_id"))
    if task_id is None:
        raise AdapterFailure(
            "MiniMax did not return a task id",
            code=_provider_code(created) or "missing_task_id",
        )
    # Billed from here on. Record the id before the first poll.
    _record_handle(job, task_id)
    return _poll_minimax_video(
        job,
        base=base,
        token=token,
        task_id=task_id,
        interval=interval,
        timeout_seconds=timeout_seconds,
    )


def _poll_minimax_video(
    job: Mapping[str, Any],
    *,
    base: str,
    token: str,
    task_id: str,
    interval: float | None = None,
    timeout_seconds: float | None = None,
) -> tuple[Path, str]:
    if interval is None or timeout_seconds is None:
        interval, timeout_seconds = _polling_config(
            "MINIMAX_VIDEO_POLL_INTERVAL",
            "MINIMAX_VIDEO_TIMEOUT_SECONDS",
            provider="MiniMax",
        )
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        document, _ = _request_json(
            f"{base}/query/video_generation/"
            + urllib.parse.quote(task_id, safe=""),
            provider="minimax-h3",
            method="GET",
            token=token,
        )
        task = document.get("task")
        status = task.get("status") if isinstance(task, Mapping) else None
        if status == "succeeded":
            content = task.get("content") if isinstance(task, Mapping) else None
            url = content.get("url") if isinstance(content, Mapping) else None
            if not isinstance(url, str):
                raise AdapterFailure(
                    "MiniMax succeeded without a video URL",
                    code="missing_video_url",
                    request_id=task_id,
                )
            return _download(
                job, url, job["outputs"][0], provider="minimax-h3"
            ), task_id
        if isinstance(status, str) and status.casefold() in TERMINAL_FAILURES:
            raise AdapterFailure(
                "MiniMax video task failed",
                code="task_" + status.casefold(),
                request_id=task_id,
            )
        if status not in {"queued", "running", "processing", "pending", "in_progress"}:
            raise AdapterFailure(
                "MiniMax returned an unknown task status",
                code="unknown_task_status",
                request_id=task_id,
            )
        time.sleep(interval)
    raise AdapterFailure(
        "MiniMax video task polling timed out",
        category="timeout",
        code="task_poll_timeout",
        request_id=task_id,
        retryable=True,
    )


def main(argv: Sequence[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "provider",
        choices=(
            "seedance", "gpt-image-2", "minimax-music", "minimax-h3",
            "minimax-speech",
        ),
    )
    args = parser.parse_args(argv)
    effective_provider: str = args.provider
    try:
        raw_stdin: bytes | str = (
            sys.stdin.buffer.read()
            if hasattr(sys.stdin, "buffer")
            else sys.stdin.read()
        )
        job = json.loads(raw_stdin)
        if not isinstance(job, Mapping):
            raise ValueError("adapter input must be an object")
        adapter_name = _safe_public_id(job.get("adapter"))
        if adapter_name is not None:
            effective_provider = adapter_name
        runners = {
            "seedance": _run_seedance,
            "gpt-image-2": _run_openai,
            "minimax-music": _run_minimax,
            "minimax-h3": _run_minimax_video,
            "minimax-speech": _run_minimax_speech,
        }
        result_paths, provider_job_id = runners[args.provider](job)
        paths = result_paths if isinstance(result_paths, list) else [result_paths]
        response: dict[str, Any] = {
            "outputs": [
                {"target": target, "source": str(path)}
                for target, path in zip(job["outputs"], paths)
            ]
        }
        safe_job_id = _safe_public_id(provider_job_id)
        if safe_job_id is not None:
            response["provider_job_id"] = safe_job_id
        json.dump(response, sys.stdout, ensure_ascii=True)
        return 0
    except AdapterFailure as exc:
        # Provider bodies and credentials are intentionally never reflected.
        json.dump({"error": exc.public(effective_provider)}, sys.stdout, ensure_ascii=True)
        print("provider adapter failed safely", file=sys.stderr)
        return 1
    except (KeyError, TypeError, UnicodeError, json.JSONDecodeError):
        json.dump(
            {
                "error": {
                    "provider": effective_provider,
                    "category": "invalid_request",
                    "code": "invalid_job",
                    "retryable": False,
                    "submitted": False,
                }
            },
            sys.stdout,
            ensure_ascii=True,
        )
        print("provider adapter failed safely", file=sys.stderr)
        return 1
    except ValueError as exc:
        error_payload: dict[str, Any] = {
            "provider": effective_provider,
            "category": "invalid_request",
            "code": "invalid_job",
            "retryable": False,
            "submitted": False,
        }
        detail = _safe_detail(str(exc))
        if detail is not None:
            error_payload["detail"] = detail
        json.dump({"error": error_payload}, sys.stdout, ensure_ascii=True)
        print("provider adapter failed safely", file=sys.stderr)
        return 1


if __name__ == "__main__":
    raise SystemExit(main())
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall