@event4u/agent-config 2.21.0 → 2.24.0

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

package/scripts/ai-video/lib/operator-pick.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# operator-pick.sh — best-of-N selection checkpoint invoked after image
+# render by /video:from-script and /video:scene. Renders a thumbnail
+# contact-sheet PNG of the candidates under a scene, then waits for the
+# operator to write <project>/scenes/<id>/selection.json.
+#
+# Dry-run mode (AIV_DRYRUN=true, default) auto-picks candidate 1 and
+# writes the same selection.json so smoke tests stay unattended.
+#
+# Usage:
+#   operator-pick.sh <project-dir> <scene-id>
+#
+# Inputs:
+#   <project-dir>/scenes/<scene-id>/candidates/*.png   (N>=1 image files)
+#
+# Outputs (stdout, one path per line so callers can capture both):
+#   sheet=<project-dir>/scenes/<scene-id>/contact-sheet.png
+#   selected=<absolute path to locked image>
+#
+# Exit codes:
+#   0   selection.json present, locked image path emitted
+#   2   missing candidates directory or empty
+#   3   selection.json malformed or names an unknown candidate
+#   4   operator declined (selection.json absent in live mode)
+
+set -euo pipefail
+
+if [ "$#" -ne 2 ]; then
+  printf 'operator-pick: usage: %s <project-dir> <scene-id>\n' "$0" >&2
+  exit 2
+fi
+
+project_dir="$1"
+scene_id="$2"
+scene_dir="${project_dir}/scenes/${scene_id}"
+cand_dir="${scene_dir}/candidates"
+sheet="${scene_dir}/contact-sheet.png"
+sel_file="${scene_dir}/selection.json"
+
+if [ ! -d "${cand_dir}" ]; then
+  printf 'operator-pick: missing candidate dir: %s\n' "${cand_dir}" >&2
+  exit 2
+fi
+
+# Collect candidates in deterministic order (lexical). Portable to
+# macOS bash 3.2 — no `mapfile`.
+candidates=()
+while IFS= read -r _p; do
+  candidates+=("${_p}")
+done < <(find "${cand_dir}" -maxdepth 1 -type f -name '*.png' | LC_ALL=C sort)
+if [ "${#candidates[@]}" -eq 0 ]; then
+  printf 'operator-pick: no candidate PNGs under %s\n' "${cand_dir}" >&2
+  exit 2
+fi
+
+# Build the contact-sheet PNG via ffmpeg. ceil(sqrt(N)) columns.
+n="${#candidates[@]}"
+cols=1
+while [ $((cols * cols)) -lt "${n}" ]; do cols=$((cols + 1)); done
+
+# ffmpeg's `tile` filter needs an input concat; use `-pattern_type glob`.
+if command -v ffmpeg >/dev/null 2>&1; then
+  ffmpeg -y -loglevel error \
+    -pattern_type glob -i "${cand_dir}/*.png" \
+    -filter_complex "tile=${cols}x0:padding=8:margin=16" \
+    "${sheet}" || {
+      printf 'operator-pick: ffmpeg tile failed; falling back to first candidate as sheet\n' >&2
+      cp "${candidates[0]}" "${sheet}"
+    }
+else
+  # ffmpeg absent (e.g. minimal CI). Copy the first candidate as the sheet.
+  cp "${candidates[0]}" "${sheet}"
+fi
+
+# Dry-run: auto-select candidate 1 and write selection.json verbatim so
+# downstream resume reads it identically to a real operator pick.
+if [ "${AIV_DRYRUN:-true}" = "true" ]; then
+  first="$(basename "${candidates[0]}")"
+  cat > "${sel_file}" <<JSON
+{
+  "selected": "${first}",
+  "reason": "auto-selected by operator-pick.sh (AIV_DRYRUN=true)"
+}
+JSON
+fi
+
+# Wait-loop is not appropriate here — the caller (command file) decides
+# whether to poll or hand back. We assert selection.json exists and
+# resolve it; if missing in live mode, we exit non-zero so the caller
+# can pause and re-invoke.
+if [ ! -f "${sel_file}" ]; then
+  printf 'operator-pick: selection.json absent; write %s with {"selected":"<filename>"} and re-run\n' "${sel_file}" >&2
+  exit 4
+fi
+
+# Read selection.json (jq required — already a hard dep for adapters).
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'operator-pick: jq is required\n' >&2
+  exit 3
+fi
+selected_name="$(jq -r '.selected // empty' "${sel_file}")"
+if [ -z "${selected_name}" ]; then
+  printf 'operator-pick: selection.json missing "selected" field\n' >&2
+  exit 3
+fi
+
+selected_path="${cand_dir}/${selected_name}"
+if [ ! -f "${selected_path}" ]; then
+  printf 'operator-pick: selected candidate not found: %s\n' "${selected_path}" >&2
+  exit 3
+fi
+
+# Also write a stable locked.png symlink/copy at the scene root so the
+# motion step can resolve the locked image without re-reading selection.json.
+locked="${scene_dir}/locked.png"
+cp -f "${selected_path}" "${locked}"
+
+printf 'sheet=%s\n' "${sheet}"
+printf 'selected=%s\n' "${locked}"

package/scripts/ai-video/lib/parse-blueprint.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# parse-blueprint.sh — read a 12-block Cinematic Scene Blueprint
+# from stdin (or a file arg) and emit adapter-contract JSON on
+# stdout. Pure POSIX-compatible bash (no associative arrays, runs
+# on macOS bash 3.2); jq required for JSON safety.
+#
+# Schema: .agent-src.uncompressed/skills/scene-expander/scene-blueprint.schema.yaml
+# Contract: scripts/ai-video/lib/adapter-contract.md
+#
+# Usage:
+#   parse-blueprint.sh < prompt.txt > blueprint.json
+#   parse-blueprint.sh prompt.txt > blueprint.json
+#
+# Exit codes:
+#   0   valid blueprint, JSON emitted on stdout
+#   2   missing required block — name on stderr
+#   3   parse error (unknown block, malformed DURATION, etc.)
+
+set -euo pipefail
+
+command -v jq >/dev/null 2>&1 || {
+  echo "parse-blueprint: jq required" >&2
+  exit 3
+}
+
+input="${1:-/dev/stdin}"
+[ -r "$input" ] || { echo "parse-blueprint: cannot read $input" >&2; exit 3; }
+
+V_STYLE=""; V_SUBJECT=""; V_ENVIRONMENT=""; V_ACTION=""
+V_CAMERA=""; V_LENS=""; V_LIGHTING=""; V_MOOD=""
+V_DIALOGUE=""; V_AMBIENT_SOUND=""; V_DURATION=""; V_NEGATIVE=""
+
+append_to() {
+  local name="$1"; local line="$2"
+  local cur; eval "cur=\${$name}"
+  if [ -z "$cur" ]; then
+    eval "$name=\$line"
+  else
+    eval "$name=\"\${$name}
+\$line\""
+  fi
+}
+
+set_var() {
+  eval "$1=\$2"
+}
+
+current=""
+while IFS= read -r line || [ -n "$line" ]; do
+  stripped="$(printf '%s' "$line" | sed -E 's/^[[:space:]]*//; s/^\*\*//; s/\*\*[[:space:]]*$//')"
+  label="$(printf '%s' "$stripped" | sed -nE 's/^([A-Z][A-Z ]+)[[:space:]]*:.*$/\1/p')"
+  if [ -n "$label" ]; then
+    key="$(printf '%s' "$label" | tr ' ' '_' | tr '[:lower:]' '[:upper:]')"
+    case "$key" in
+      STYLE|SUBJECT|ENVIRONMENT|ACTION|CAMERA|LENS|LIGHTING|MOOD|DIALOGUE|AMBIENT_SOUND|DURATION|NEGATIVE)
+        current="V_$key"
+        rest="$(printf '%s' "$stripped" | sed -E "s/^${label}[[:space:]]*:[[:space:]]*//")"
+        set_var "$current" "$rest"
+        continue
+        ;;
+    esac
+  fi
+  if [ -n "$current" ] && [ -n "$line" ]; then
+    append_to "$current" "$line"
+  fi
+done < "$input"
+
+for short in STYLE SUBJECT ENVIRONMENT ACTION CAMERA LENS LIGHTING MOOD DURATION NEGATIVE; do
+  eval "v=\$V_$short"
+  if [ -z "$v" ]; then
+    echo "parse-blueprint: missing required block: $short" >&2
+    exit 2
+  fi
+done
+
+if ! printf '%s' "$V_DURATION" | grep -Eq '^[0-9]+(\.[0-9])?$'; then
+  echo "parse-blueprint: DURATION not numeric: $V_DURATION" >&2
+  exit 3
+fi
+
+negative_json="$(printf '%s' "$V_NEGATIVE" | tr ',\n' '\n\n' | sed '/^[[:space:]]*$/d' | sed -E 's/^[[:space:]]*//; s/[[:space:]]*$//' | jq -R . | jq -s .)"
+
+to_array_or_null() {
+  if [ -z "$1" ]; then
+    printf '%s' "null"
+  else
+    printf '%s\n' "$1" | sed '/^[[:space:]]*$/d' | jq -R . | jq -s .
+  fi
+}
+dialogue_json="$(to_array_or_null "$V_DIALOGUE")"
+ambient_json="$(to_array_or_null "$V_AMBIENT_SOUND")"
+
+audio_native=false
+if [ "$dialogue_json" != "null" ] || [ "$ambient_json" != "null" ]; then
+  audio_native=true
+fi
+
+jq -n \
+  --arg style       "$V_STYLE" \
+  --arg subject     "$V_SUBJECT" \
+  --arg environment "$V_ENVIRONMENT" \
+  --arg action      "$V_ACTION" \
+  --arg camera      "$V_CAMERA" \
+  --arg lens        "$V_LENS" \
+  --arg lighting    "$V_LIGHTING" \
+  --arg mood        "$V_MOOD" \
+  --argjson dialogue "$dialogue_json" \
+  --argjson ambient  "$ambient_json" \
+  --argjson duration "$V_DURATION" \
+  --argjson negative "$negative_json" \
+  --argjson native   "$audio_native" \
+  '{
+    prompt: {
+      style: $style, subject: $subject, environment: $environment,
+      action: $action, camera: $camera, lens: $lens,
+      lighting: $lighting, mood: $mood
+    },
+    audio: { dialogue: $dialogue, ambient: $ambient, enable_native_audio: $native },
+    duration: $duration,
+    negative: $negative,
+    requires: { audio_native: $native }
+  }'

package/scripts/ai-video/lib/redact.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# scripts/ai-video/lib/redact.sh — secret-scrubbing helper for /video:* adapters.
+#
+# Sourced by every adapter under scripts/ai-video/adapters/*.sh. Provides
+# two helpers:
+#
+#   aiv_redact_register <secret>   — register a string to scrub (idempotent)
+#   aiv_redact <text>              — print text with every registered
+#                                    secret replaced by ***REDACTED***
+#
+# Iron Law: an API key must never reach stdout/stderr verbatim. Adapters
+# pipe every network response, curl error, and trace through aiv_redact
+# before printing. Empty / unset values are skipped silently — an unset
+# secret cannot leak.
+#
+# Pure bash, no external dependencies. Safe under `set -euo pipefail`.
+
+# Guard against double-source.
+if [ -n "${AIV_REDACT_LOADED:-}" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+AIV_REDACT_LOADED=1
+
+# Registry of secrets to scrub. Newline-separated; populated by
+# aiv_redact_register. Never echoed.
+AIV_REDACT_SECRETS=""
+
+aiv_redact_register() {
+  local secret="${1:-}"
+  # Treat empty / placeholder values as no-op so adapters can call this
+  # unconditionally without leaking the placeholder string.
+  case "${secret}" in
+    ""|"REPLACE-ME"|*"-REPLACE-ME") return 0 ;;
+  esac
+  # Require a minimum length so single characters do not nuke the log.
+  if [ "${#secret}" -lt 8 ]; then
+    return 0
+  fi
+  # Idempotent — skip if already registered.
+  case "${AIV_REDACT_SECRETS}" in
+    *"${secret}"*) return 0 ;;
+  esac
+  AIV_REDACT_SECRETS="${AIV_REDACT_SECRETS}${secret}
+"
+}
+
+aiv_redact() {
+  local input
+  if [ "$#" -gt 0 ]; then
+    input="$*"
+  else
+    input="$(cat)"
+  fi
+  if [ -z "${AIV_REDACT_SECRETS}" ]; then
+    printf '%s\n' "${input}"
+    return 0
+  fi
+  # Apply replacements one secret at a time using awk so special chars
+  # in the secret cannot break a sed expression. Use a here-string to
+  # avoid running the loop in a subshell (which would discard mutations
+  # to ${input}).
+  local secret
+  while IFS= read -r secret; do
+    [ -z "${secret}" ] && continue
+    input="$(printf '%s' "${input}" | awk -v s="${secret}" '
+      {
+        out = ""
+        rest = $0
+        while ((i = index(rest, s)) > 0) {
+          out = out substr(rest, 1, i - 1) "***REDACTED***"
+          rest = substr(rest, i + length(s))
+        }
+        print out rest
+      }')"
+  done <<< "${AIV_REDACT_SECRETS}"
+  printf '%s\n' "${input}"
+}
+
+# Convenience wrapper: pipe stdin through aiv_redact line by line so
+# adapters can do `curl … 2>&1 | aiv_redact_stream`.
+aiv_redact_stream() {
+  while IFS= read -r line; do
+    aiv_redact "${line}"
+  done
+}