@event4u/agent-config 2.23.0 → 2.24.0

package/scripts/ai-video/adapters/kling.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# kling.sh — Kuaishou Kling motion-tuned video generation adapter.
+#
+# Capability: audio=none by default (Kling current generation does not
+# emit native audio); the orchestrator muxes operator-supplied dialogue
+# / ambient at stitch time. Max duration is model-dependent; clip-time
+# clamping happens in motion-choreographer (it tunes the prompt to fit).
+#
+# Contract: scripts/ai-video/lib/adapter-contract.md
+# Provider: top-level <provider id="kling" kind="video"> in
+# agents/.ai-video.xml.
+
+set -euo pipefail
+
+# shellcheck source=../lib/adapter-common.sh
+. "$(dirname "$0")/../lib/adapter-common.sh"
+
+ADAPTER_ID="kling"
+KLING_MAX_DURATION="${KLING_MAX_DURATION:-10}"
+
+aiv_cmd_submit() {
+  aiv_assert_dryrun
+  aiv_require_cmd curl jq
+  aiv_load_provider "${ADAPTER_ID}"
+  [ "$(aiv_key_status)" = "present" ] \
+    || aiv_die 6 "${ADAPTER_ID}: api key missing in agents/.ai-video.xml"
+
+  local stdin_json duration
+  stdin_json="$(cat)"
+  duration="$(printf '%s' "${stdin_json}" | jq -r '.duration // empty')"
+  if [ -n "${duration}" ]; then
+    awk -v d="${duration}" -v m="${KLING_MAX_DURATION}" \
+      'BEGIN { if (d+0 > m+0) exit 1; exit 0 }' \
+      || aiv_die 3 "${ADAPTER_ID}: duration ${duration}s exceeds model max ${KLING_MAX_DURATION}s"
+  fi
+
+  aiv_die 9 "${ADAPTER_ID}: live submit not yet wired (max duration ${KLING_MAX_DURATION}s honored)"
+}
+
+aiv_cmd_poll() {
+  local job_id="${1:-}"
+  [ -n "${job_id}" ] || aiv_die 2 "${ADAPTER_ID}: poll <job_id> required"
+  aiv_assert_dryrun
+  aiv_die 9 "${ADAPTER_ID}: live poll not yet wired (job=${job_id})"
+}
+
+aiv_cmd_fetch() {
+  local job_id="${1:-}"
+  [ -n "${job_id}" ] || aiv_die 2 "${ADAPTER_ID}: fetch <job_id> required"
+  aiv_assert_dryrun
+  aiv_die 9 "${ADAPTER_ID}: live fetch not yet wired (job=${job_id})"
+}
+
+aiv_dispatch "${ADAPTER_ID}" "none" "$@"

package/scripts/ai-video/adapters/openai-images.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# openai-images.sh — image generation adapter (DALL-E / gpt-image-1).
+#
+# Capability: audio=none (still images only — motion handled by a
+# downstream video adapter). Ref-image and seed reuse are passed
+# through verbatim so character-consistency can lock a face across
+# scenes by reusing the same seed.
+#
+# Contract: scripts/ai-video/lib/adapter-contract.md
+# Provider: top-level <provider id="openai-images" kind="image"> in
+# agents/.ai-video.xml.
+
+set -euo pipefail
+
+# shellcheck source=../lib/adapter-common.sh
+. "$(dirname "$0")/../lib/adapter-common.sh"
+
+ADAPTER_ID="openai-images"
+
+aiv_cmd_run() {
+  aiv_assert_dryrun
+  aiv_require_cmd curl jq
+  aiv_load_provider "${ADAPTER_ID}"
+  [ "$(aiv_key_status)" = "present" ] \
+    || aiv_die 6 "${ADAPTER_ID}: api key missing in agents/.ai-video.xml"
+
+  # Read contract stdin JSON; compose a single text prompt from the
+  # eight prose blocks. Ref-image + seed are passed verbatim.
+  local stdin_json prompt seed ref_first
+  stdin_json="$(cat)"
+  prompt="$(printf '%s' "${stdin_json}" | jq -r '
+    [.prompt.style, .prompt.subject, .prompt.environment, .prompt.action,
+     .prompt.camera, .prompt.lens, .prompt.lighting, .prompt.mood]
+    | map(select(. != null and . != ""))
+    | join(". ")
+  ')"
+  seed="$(printf '%s' "${stdin_json}" | jq -r '.seed // empty')"
+  ref_first="$(printf '%s' "${stdin_json}" | jq -r '.ref_images[0] // empty')"
+
+  # Live mode is implementation-scaffolded: we do NOT yet POST to the
+  # OpenAI Images API from inside this adapter. The cost-floor gate
+  # (Phase 5 Step 6) refuses live mode unless the operator explicitly
+  # confirms in-turn; this branch surfaces a clear stub error so the
+  # contract surface stays stable while the live path is wired later.
+  aiv_die 9 "${ADAPTER_ID}: live mode not yet wired (prompt=${#prompt} chars, seed=${seed:-unset}, ref=${ref_first:-none})"
+}
+
+aiv_cmd_submit() { aiv_cmd_run "$@"; }
+aiv_cmd_fetch()  { aiv_cmd_run "$@"; }
+aiv_cmd_poll()   { printf '{"status":"done"}\n'; }
+
+aiv_dispatch "${ADAPTER_ID}" "none" "$@"

package/scripts/ai-video/adapters/sora.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# sora.sh — OpenAI Sora structural-prompt video adapter.
+#
+# Capability: audio=native. Sora-class models produce muxed MP4 with
+# dialogue + ambient sound; we pass the audio block straight through.
+# Structural-prompt path informed by upstream `awesome-sora-prompts`
+# (attribution in agents/ai-video/prompts/cinematic-blueprint.md).
+#
+# Contract: scripts/ai-video/lib/adapter-contract.md
+# Provider: top-level <provider id="sora" kind="video"> in
+# agents/.ai-video.xml.
+
+set -euo pipefail
+
+# shellcheck source=../lib/adapter-common.sh
+. "$(dirname "$0")/../lib/adapter-common.sh"
+
+ADAPTER_ID="sora"
+
+aiv_cmd_submit() {
+  aiv_assert_dryrun
+  aiv_require_cmd curl jq
+  aiv_load_provider "${ADAPTER_ID}"
+  [ "$(aiv_key_status)" = "present" ] \
+    || aiv_die 6 "${ADAPTER_ID}: api key missing in agents/.ai-video.xml"
+
+  local stdin_json
+  stdin_json="$(cat)"
+  # Sora's structural-prompt path expects all eight blocks present;
+  # fail loud if the blueprint parser dropped any.
+  printf '%s' "${stdin_json}" \
+    | jq -e '.prompt.style and .prompt.subject and .prompt.environment and
+             .prompt.action and .prompt.camera and .prompt.lens and
+             .prompt.lighting and .prompt.mood' >/dev/null \
+    || aiv_die 3 "${ADAPTER_ID}: stdin JSON missing one or more required prompt blocks"
+
+  aiv_die 9 "${ADAPTER_ID}: live submit not yet wired"
+}
+
+aiv_cmd_poll() {
+  local job_id="${1:-}"
+  [ -n "${job_id}" ] || aiv_die 2 "${ADAPTER_ID}: poll <job_id> required"
+  aiv_assert_dryrun
+  aiv_die 9 "${ADAPTER_ID}: live poll not yet wired (job=${job_id})"
+}
+
+aiv_cmd_fetch() {
+  local job_id="${1:-}"
+  [ -n "${job_id}" ] || aiv_die 2 "${ADAPTER_ID}: fetch <job_id> required"
+  aiv_assert_dryrun
+  aiv_die 9 "${ADAPTER_ID}: live fetch not yet wired (job=${job_id})"
+}
+
+aiv_dispatch "${ADAPTER_ID}" "native" "$@"

package/scripts/ai-video/lib/adapter-common.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# adapter-common.sh — shared boilerplate sourced by every adapter under
+# scripts/ai-video/adapters/. Keeps individual adapters thin and makes
+# the contract surface (subcommand dispatch, dry-run plumbing, stdout
+# shape) uniform across providers.
+#
+# Sourced; never executed directly. Strict-mode flags are the caller's
+# responsibility (every adapter starts with `set -euo pipefail`).
+
+if [ -n "${AIV_ADAPTER_COMMON_LOADED:-}" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+AIV_ADAPTER_COMMON_LOADED=1
+
+# Resolve the lib dir from this file's location so adapters can source
+# us via the canonical `$(dirname "$0")/../lib/...` path.
+_aiv_lib_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "${_aiv_lib_dir}/redact.sh"
+# shellcheck source=/dev/null
+. "${_aiv_lib_dir}/load-config.sh"
+
+AIV_LIB_DIR="${_aiv_lib_dir}"
+AIV_FIXTURE_ROOT="${_aiv_lib_dir}/fixtures"
+export AIV_LIB_DIR AIV_FIXTURE_ROOT
+
+# aiv_die <exit-code> <message> — write redacted message to stderr.
+aiv_die() {
+  local code="${1:-1}"; shift || true
+  printf 'adapter: %s\n' "$*" | aiv_redact_stream >&2
+  exit "${code}"
+}
+
+# aiv_require_cmd <cmd> [<cmd> ...] — fail fast on missing dependency.
+aiv_require_cmd() {
+  local cmd
+  for cmd in "$@"; do
+    command -v "${cmd}" >/dev/null 2>&1 \
+      || aiv_die 3 "required tool not found: ${cmd}"
+  done
+}
+
+# aiv_emit_dry_run <adapter-id> — print contract-shaped stdout JSON
+# pointing at the adapter's fixture directory. Used by every adapter's
+# `dry-run` subcommand.
+aiv_emit_dry_run() {
+  local adapter="${1:-}"
+  [ -n "${adapter}" ] || aiv_die 3 "aiv_emit_dry_run: adapter id required"
+  local fixture_dir="${AIV_FIXTURE_ROOT}/${adapter}"
+  local result="${fixture_dir}/result.json"
+  if [ ! -f "${result}" ]; then
+    aiv_die 3 "fixture missing: ${result}"
+  fi
+  cat "${result}"
+}
+
+# aiv_capability <flag> — print the capability JSON for `--help`-style
+# discovery: `{"audio": "native|none|per-model"}`.
+aiv_capability() {
+  local flag="${1:-none}"
+  printf '{"audio":"%s"}\n' "${flag}"
+}
+
+# aiv_assert_dryrun — refuse to run a network path unless the caller
+# explicitly opted in (AIV_DRYRUN=false set in this turn).
+aiv_assert_dryrun() {
+  case "${AIV_DRYRUN:-true}" in
+    false|FALSE|0|no|NO) return 0 ;;
+    *) aiv_die 4 "live call refused: AIV_DRYRUN=${AIV_DRYRUN:-true}; use dry-run subcommand or set AIV_DRYRUN=false" ;;
+  esac
+}
+
+# aiv_dispatch <adapter-id> <capability> "$@" — generic subcommand router.
+# Adapters override individual subcommands by defining bash functions
+# named `aiv_cmd_submit` / `aiv_cmd_poll` / `aiv_cmd_fetch` / `aiv_cmd_run`
+# BEFORE calling aiv_dispatch. Anything not overridden falls through to
+# a stub that exits non-zero with a clear message.
+aiv_dispatch() {
+  local adapter="${1:-}"; shift || true
+  local cap="${1:-none}"; shift || true
+  local sub="${1:-}"; shift || true
+  case "${sub}" in
+    capability)
+      aiv_capability "${cap}"
+      ;;
+    dry-run)
+      aiv_emit_dry_run "${adapter}"
+      ;;
+    submit)
+      declare -F aiv_cmd_submit >/dev/null \
+        && aiv_cmd_submit "$@" \
+        || aiv_die 5 "${adapter}: submit not implemented"
+      ;;
+    poll)
+      declare -F aiv_cmd_poll >/dev/null \
+        && aiv_cmd_poll "$@" \
+        || aiv_die 5 "${adapter}: poll not implemented"
+      ;;
+    fetch)
+      declare -F aiv_cmd_fetch >/dev/null \
+        && aiv_cmd_fetch "$@" \
+        || aiv_die 5 "${adapter}: fetch not implemented"
+      ;;
+    run)
+      declare -F aiv_cmd_run >/dev/null \
+        && aiv_cmd_run "$@" \
+        || aiv_die 5 "${adapter}: run not implemented"
+      ;;
+    "")
+      aiv_die 2 "${adapter}: subcommand required (capability|dry-run|submit|poll|fetch|run)"
+      ;;
+    *)
+      aiv_die 2 "${adapter}: unknown subcommand '${sub}'"
+      ;;
+  esac
+}

package/scripts/ai-video/lib/adapter-contract.md

@@ -0,0 +1,163 @@
+# Adapter Contract (v1)
+
+> Single source of truth for every adapter under
+> `scripts/ai-video/adapters/`. Phase 4 Step 1 finalizes any open
+> point in this draft; **breaking changes bump the version pin
+> and require every adapter to be rerun against the fixture set**
+> (`scripts/ai-video/lib/fixtures/`).
+
+## Scope
+
+Every backend (OpenAI Images, Gemini Veo, Kling, Higgsfield, Sora,
+…) ships as one executable shell entry under
+`scripts/ai-video/adapters/<id>.sh`. The orchestrator never speaks
+to a network API directly — it speaks to one of these scripts.
+
+## Capability flag
+
+Each adapter declares its audio capability via a top-of-file
+comment and via the `capability` subcommand:
+
+```
+# capability: audio=native | audio=none
+```
+
+`audio=native` — the provider returns a muxed MP4 with synchronized
+dialogue / ambient. `audio=none` — video-only output; the
+orchestrator muxes the operator-supplied track at stitch time.
+
+A per-model adapter (e.g. Higgsfield) MAY declare `audio=per-model`
+and surface the capability via `capability --model <id>`.
+
+## Subcommands
+
+Every adapter implements four:
+
+| Subcommand | Purpose | I/O |
+|---|---|---|
+| `submit` | Submit a render job to the backend | stdin JSON · stdout `{job_id}` |
+| `poll <job_id>` | Poll job status | stdout `{status: queued\|running\|done\|failed, progress?}` |
+| `fetch <job_id>` | Download artifacts after `status=done` | stdout `{video_path, audio_path?, audio_embedded}` |
+| `dry-run` | Return a deterministic fixture path without network | stdout same shape as `fetch` |
+
+`submit` + `poll` + `fetch` may be collapsed into a single
+`run` for synchronous backends (OpenAI Images) — the wrapper exposes
+the same stdout shape on stdout and an exit code on completion.
+
+## Stdin JSON (consumed by `submit` / `run`)
+
+```json
+{
+  "prompt": {
+    "style": "...",
+    "subject": "...",
+    "environment": "...",
+    "action": "...",
+    "camera": "...",
+    "lens": "...",
+    "lighting": "...",
+    "mood": "..."
+  },
+  "ref_images": ["/abs/path/frame.png", "..."],
+  "duration": 4.5,
+  "aspect": "16:9",
+  "seed": 1234567,
+  "audio": {
+    "dialogue": ["speaker: \"line\"", "..."],
+    "ambient": ["rain on metal", "..."],
+    "language": "en",
+    "enable_native_audio": true
+  },
+  "negative": ["centered framing", "..."]
+}
+```
+
+`ref_images`, `duration`, `aspect`, `seed`, `audio`, `negative` are
+optional. `prompt.*` blocks are mandatory. Unknown top-level keys
+are logged to stderr and ignored.
+
+## Stdout JSON (emitted by `fetch` / `run` / `dry-run`)
+
+```json
+{
+  "video_path": "/abs/path/scene-0001.mp4",
+  "audio_path": "/abs/path/scene-0001.wav",
+  "audio_embedded": true
+}
+```
+
+Semantics:
+
+- `audio_embedded: true` — `video_path` is a muxed MP4 with audio;
+  `audio_path` is omitted or echoes the same path. Stitcher
+  pass-through.
+- `audio_embedded: false` with `audio_path` — separate track to mux
+  at stitch time via `ffmpeg`.
+- `audio_embedded: false` without `audio_path` — video-only;
+  operator supplies the audio bed at stitch time.
+
+## Error contract
+
+Adapter failure: **non-zero exit code** AND a JSON file at
+`<project>/scenes/<scene_id>/error.json`:
+
+```json
+{
+  "adapter": "gemini-veo",
+  "subcommand": "fetch",
+  "job_id": "...",
+  "exit_code": 7,
+  "stderr_tail": "...",
+  "retryable": true,
+  "user_action": "regenerate-prompt | retry | skip | abort"
+}
+```
+
+`retryable: false` means a prompt or input change is required —
+the orchestrator MUST NOT auto-retry. `retryable: true` does **not**
+authorize auto-retry either; the orchestrator surfaces a single
+numbered-options block (retry · regenerate prompt · skip · abort)
+per `non-destructive-by-default` and waits.
+
+## Dry-run
+
+`AIV_DRYRUN=true` (set by command default; see Phase 5 Step 6) OR
+the explicit `dry-run` subcommand:
+
+- No network call.
+- Stdout JSON points at a deterministic fixture under
+  `scripts/ai-video/lib/fixtures/<adapter-id>/`.
+- Exit code 0.
+
+Fixtures are committed and cover one happy path per adapter.
+Phase 6 golden runs assert byte-identical stdout under
+`AIV_DRYRUN=true`.
+
+## Logging & redaction
+
+- **stderr only** for log output. Stdout is reserved for the
+  contract JSON.
+- Every adapter MUST source `scripts/ai-video/lib/redact.sh` and
+  pipe network responses through `aiv_redact_stream` before any
+  `>&2` write. API keys, bearer tokens, and operator-registered
+  secrets are masked.
+
+## Strict-mode shell
+
+Every adapter:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+. "$(dirname "$0")/../lib/redact.sh"
+. "$(dirname "$0")/../lib/load-config.sh"
+```
+
+`shellcheck` clean (Phase 4 Step 9).
+
+## Versioning
+
+This contract is `v1`. Backward-incompatible changes (renamed
+field, removed subcommand, changed stdout shape) bump to `v2` and
+require an `adapter-contract` migration note plus a rerun of every
+adapter against the fixture set.

package/scripts/ai-video/lib/fixtures/gemini-veo/result.json

@@ -0,0 +1 @@
+{"video_path":"scripts/ai-video/lib/fixtures/gemini-veo/scene-0001.mp4","audio_embedded":true}

package/scripts/ai-video/lib/fixtures/gemini-veo/scene-0001.mp4

@@ -0,0 +1 @@
+FIXTURE-gemini-veo-mp4

package/scripts/ai-video/lib/fixtures/higgsfield/result.json

@@ -0,0 +1 @@
+{"video_path":"scripts/ai-video/lib/fixtures/higgsfield/scene-0001.mp4","audio_embedded":false}

package/scripts/ai-video/lib/fixtures/higgsfield/scene-0001.mp4

@@ -0,0 +1 @@
+FIXTURE-higgsfield-mp4

package/scripts/ai-video/lib/fixtures/kling/result.json

@@ -0,0 +1 @@
+{"video_path":"scripts/ai-video/lib/fixtures/kling/scene-0001.mp4","audio_embedded":false}

package/scripts/ai-video/lib/fixtures/kling/scene-0001.mp4

@@ -0,0 +1 @@
+FIXTURE-kling-mp4

package/scripts/ai-video/lib/fixtures/openai-images/result.json

@@ -0,0 +1 @@
+{"video_path":"scripts/ai-video/lib/fixtures/openai-images/scene-0001.png","audio_embedded":false}

package/scripts/ai-video/lib/fixtures/openai-images/scene-0001.png

@@ -0,0 +1,3 @@
+�PNG
+
+FIXTURE-openai-images

package/scripts/ai-video/lib/fixtures/sora/result.json

@@ -0,0 +1 @@
+{"video_path":"scripts/ai-video/lib/fixtures/sora/scene-0001.mp4","audio_embedded":true}

package/scripts/ai-video/lib/fixtures/sora/scene-0001.mp4

@@ -0,0 +1 @@
+FIXTURE-sora-mp4

package/scripts/ai-video/lib/load-config.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# scripts/ai-video/lib/load-config.sh — provider config loader for /video:*.
+#
+# Parses agents/.ai-video.xml with xmllint --xpath and surfaces a single
+# provider's settings as AIV_KEY / AIV_ENDPOINT / AIV_MODEL / AIV_DRYRUN
+# env vars to its caller. The key is NEVER echoed — status output is only
+# `present` or `missing`.
+#
+# Usage (sourced):
+#
+#   . scripts/ai-video/lib/load-config.sh
+#   aiv_load_provider gemini-veo
+#   echo "key: $(aiv_key_status)"     # → present | missing
+#   echo "endpoint: $AIV_ENDPOINT"
+#   echo "dryrun: $AIV_DRYRUN"
+#
+# Usage (CLI status check, no key echoed):
+#
+#   bash scripts/ai-video/lib/load-config.sh status gemini-veo
+#   → provider=gemini-veo key=present dryrun=true model=veo-3.0-generate-001
+#
+# Defaults:
+#   - AIV_DRYRUN defaults to `true` when not set in XML
+#   - AIV_DRYRUN can be overridden by the AIV_DRYRUN env var set by caller
+#   - missing file is non-fatal in `status` mode (prints all-missing line)
+
+set -u
+
+AIV_CONFIG_PATH="${AIV_CONFIG_PATH:-agents/.ai-video.xml}"
+
+_aiv_xpath() {
+  # $1 = xpath expression; reads from $AIV_CONFIG_PATH
+  # Returns text content or empty string. Never errors on missing path.
+  if [ ! -f "${AIV_CONFIG_PATH}" ]; then
+    printf ''
+    return 0
+  fi
+  if ! command -v xmllint >/dev/null 2>&1; then
+    printf ''
+    return 0
+  fi
+  xmllint --xpath "string(${1})" "${AIV_CONFIG_PATH}" 2>/dev/null || printf ''
+}
+
+aiv_default_image_provider() {
+  _aiv_xpath '/ai-video/default-image-provider'
+}
+
+aiv_default_video_provider() {
+  _aiv_xpath '/ai-video/default-video-provider'
+}
+
+aiv_load_provider() {
+  local pid="${1:-}"
+  if [ -z "${pid}" ]; then
+    echo "aiv_load_provider: provider id required" >&2
+    return 2
+  fi
+
+  # Resolve from the top-level <provider> blocks OR the <extra> slot.
+  local base="(/ai-video/provider[@id='${pid}']|/ai-video/extra/provider[@id='${pid}'])"
+
+  AIV_PROVIDER_ID="${pid}"
+  AIV_KEY="$(_aiv_xpath "${base}/api-key")"
+  AIV_ENDPOINT="$(_aiv_xpath "${base}/endpoint")"
+  AIV_MODEL="$(_aiv_xpath "${base}/default-model")"
+  AIV_KIND="$(_aiv_xpath "${base}/@kind")"
+
+  local dryrun_xml
+  dryrun_xml="$(_aiv_xpath "${base}/dry-run")"
+  # Caller-set AIV_DRYRUN takes precedence; otherwise XML; otherwise true.
+  if [ -n "${AIV_DRYRUN:-}" ]; then
+    : # respect caller
+  elif [ -n "${dryrun_xml}" ]; then
+    AIV_DRYRUN="${dryrun_xml}"
+  else
+    AIV_DRYRUN="true"
+  fi
+  export AIV_DRYRUN
+
+  # Tuning fields — adapters read these directly when present.
+  AIV_TUNING_ASPECT="$(_aiv_xpath "${base}/tuning/aspect")"
+  AIV_TUNING_FPS="$(_aiv_xpath "${base}/tuning/fps")"
+  AIV_TUNING_MAX_DURATION="$(_aiv_xpath "${base}/tuning/max-duration")"
+  AIV_TUNING_AUDIO_NATIVE="$(_aiv_xpath "${base}/tuning/audio-native")"
+  AIV_TUNING_PRESET="$(_aiv_xpath "${base}/tuning/preset")"
+  AIV_TUNING_QUALITY="$(_aiv_xpath "${base}/tuning/quality")"
+  AIV_TUNING_BEST_OF_N="$(_aiv_xpath "${base}/tuning/best-of-n")"
+  export AIV_TUNING_ASPECT AIV_TUNING_FPS AIV_TUNING_MAX_DURATION \
+    AIV_TUNING_AUDIO_NATIVE AIV_TUNING_PRESET AIV_TUNING_QUALITY \
+    AIV_TUNING_BEST_OF_N
+
+  # Register key with redact.sh if loaded — adapters always source both.
+  if command -v aiv_redact_register >/dev/null 2>&1; then
+    aiv_redact_register "${AIV_KEY}"
+  fi
+
+  return 0
+}
+
+aiv_key_status() {
+  case "${AIV_KEY:-}" in
+    ""|"REPLACE-ME"|*"-REPLACE-ME") printf 'missing' ;;
+    *) printf 'present' ;;
+  esac
+}
+
+# CLI mode — only `status <provider-id>` is supported; never echoes the key.
+if [ "${BASH_SOURCE[0]:-}" = "${0}" ]; then
+  cmd="${1:-}"
+  case "${cmd}" in
+    status)
+      pid="${2:-}"
+      if [ -z "${pid}" ]; then
+        echo "usage: load-config.sh status <provider-id>" >&2
+        exit 2
+      fi
+      aiv_load_provider "${pid}" >/dev/null
+      printf 'provider=%s key=%s dryrun=%s model=%s endpoint=%s kind=%s\n' \
+        "${AIV_PROVIDER_ID}" \
+        "$(aiv_key_status)" \
+        "${AIV_DRYRUN:-true}" \
+        "${AIV_MODEL:-}" \
+        "${AIV_ENDPOINT:-}" \
+        "${AIV_KIND:-}"
+      ;;
+    defaults)
+      printf 'default-image-provider=%s\n' "$(aiv_default_image_provider)"
+      printf 'default-video-provider=%s\n' "$(aiv_default_video_provider)"
+      ;;
+    "")
+      echo "usage: load-config.sh {status <id> | defaults}" >&2
+      exit 2
+      ;;
+    *)
+      echo "load-config.sh: unknown subcommand '${cmd}'" >&2
+      exit 2
+      ;;
+  esac
+fi