@event4u/agent-config 14.9.0 → 14.11.0

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

@@ -11,10 +11,30 @@
 #   parse-blueprint.sh < prompt.txt > blueprint.json
 #   parse-blueprint.sh prompt.txt > blueprint.json
 #
+# Optional CONTINUITY block — how this scene joins the PREVIOUS one:
+#
+#   CONTINUITY: cut         hard cut (default; the value assumed when the
+#                           block is absent, so every existing blueprint
+#                           keeps its exact meaning)
+#   CONTINUITY: handoff     this scene's ref_images[0] is the extracted last
+#                           frame of the PREVIOUS scene's rendered clip, not
+#                           its own still — so the two clips must render
+#                           sequentially
+#   CONTINUITY: connector   handoff plus one extra generated clip bridging the
+#                           two, which needs a probed end_frame:true on both
+#                           adjacent models (seam-plan.sh gates it)
+#
+# The value is emitted as the top-level `continuity` key. An unknown value is
+# a parse error naming the value — never a silent downgrade to `cut`, because a
+# caller who asked for continuity and got a cut has no way to see it. The seam
+# plan (which boundaries hand off, the generation count, the sequential trade)
+# is printed by the sibling `seam-plan.sh` over an ordered list of these JSONs;
+# this script parses ONE scene and knows nothing about its neighbours.
+#
 # Exit codes:
 #   0   valid blueprint, JSON emitted on stdout
 #   2   missing required block — name on stderr
-#   3   parse error (unknown block, malformed DURATION, etc.)
+#   3   parse error (unknown block, malformed DURATION, unknown CONTINUITY)
 
 set -euo pipefail
 
@@ -23,12 +43,24 @@ command -v jq >/dev/null 2>&1 || {
   exit 3
 }
 
-input="${1:-/dev/stdin}"
-[ -r "$input" ] || { echo "parse-blueprint: cannot read $input" >&2; exit 3; }
+# A file argument is opened; with no argument the ALREADY-OPEN stdin is
+# inherited rather than re-opened through /dev/stdin. Re-opening it is what the
+# documented `parse-blueprint.sh < prompt.txt` form used to do, and it is not
+# portable: on a Linux CI runner whose stdin is a pipe supplied by the test
+# harness, `/dev/stdin` is not openable and the script died with
+# "No such device or address" — the documented interface was broken on the one
+# platform nothing had exercised it on. `exec` keeps the readable-path check
+# meaningful for the argument form while leaving fd 0 untouched otherwise.
+input="${1:-}"
+if [ -n "$input" ]; then
+  [ -r "$input" ] || { echo "parse-blueprint: cannot read $input" >&2; exit 3; }
+  exec < "$input"
+fi
 
 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=""
+V_CONTINUITY=""
 
 append_to() {
   local name="$1"; local line="$2"
@@ -52,7 +84,7 @@ while IFS= read -r line || [ -n "$line" ]; do
   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)
+      STYLE|SUBJECT|ENVIRONMENT|ACTION|CAMERA|LENS|LIGHTING|MOOD|DIALOGUE|AMBIENT_SOUND|DURATION|NEGATIVE|CONTINUITY)
         current="V_$key"
         rest="$(printf '%s' "$stripped" | sed -E "s/^${label}[[:space:]]*:[[:space:]]*//")"
         set_var "$current" "$rest"
@@ -63,7 +95,7 @@ while IFS= read -r line || [ -n "$line" ]; do
   if [ -n "$current" ] && [ -n "$line" ]; then
     append_to "$current" "$line"
   fi
-done < "$input"
+done
 
 for short in STYLE SUBJECT ENVIRONMENT ACTION CAMERA LENS LIGHTING MOOD DURATION NEGATIVE; do
   eval "v=\$V_$short"
@@ -78,6 +110,19 @@ if ! printf '%s' "$V_DURATION" | grep -Eq '^[0-9]+(\.[0-9])?$'; then
   exit 3
 fi
 
+# CONTINUITY is optional; absent means `cut`, which is what every blueprint
+# written before this block existed meant. An unknown value is refused with the
+# value named rather than downgraded to `cut`.
+V_CONTINUITY="$(printf '%s' "$V_CONTINUITY" | sed -E 's/^[[:space:]]*//; s/[[:space:]]*$//' | tr '[:upper:]' '[:lower:]')"
+[ -n "$V_CONTINUITY" ] || V_CONTINUITY="cut"
+case "$V_CONTINUITY" in
+  cut|handoff|connector) ;;
+  *)
+    echo "parse-blueprint: unknown CONTINUITY value: $V_CONTINUITY (expected cut|handoff|connector)" >&2
+    exit 3
+    ;;
+esac
+
 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() {
@@ -109,6 +154,7 @@ jq -n \
   --argjson duration "$V_DURATION" \
   --argjson negative "$negative_json" \
   --argjson native   "$audio_native" \
+  --arg continuity   "$V_CONTINUITY" \
   '{
     prompt: {
       style: $style, subject: $subject, environment: $environment,
@@ -118,5 +164,6 @@ jq -n \
     audio: { dialogue: $dialogue, ambient: $ambient, enable_native_audio: $native },
     duration: $duration,
     negative: $negative,
+    continuity: $continuity,
     requires: { audio_native: $native }
   }'

package/src/scripts/ai-video/lib/resume-scan.sh

@@ -22,12 +22,33 @@
 #   failed   error.json present.
 #   missing  in the plan but no green artifact on disk.
 #
+# Seam sentinels (handoff chains) — same filesystem-as-state idiom:
+#
+#   <project>/seams/<from>__<to>.json
+#     {"from","to","mode":"handoff|connector",
+#      "from_input_sha256","to_input_sha256"}
+#
+# A seam is DECLARED when scene <to>'s prompt.json carries
+# `continuity: handoff|connector` — the value parse-blueprint.sh emits — and
+# <from> is its immediate predecessor in scene-id order. Clip <to> was
+# conditioned on the RENDERED last frame of clip <from>, so the join is a fact
+# about a pair, which no per-scene sentinel can express. Classification:
+#
+#   green    sentinel present, both hashes match what is on disk now, and both
+#            adjacent scenes are green
+#   stale    either adjacent scene is not green, or a recorded hash no longer
+#            matches — i.e. a failed or re-rolled clip invalidates exactly the
+#            seams it touches, and no others
+#   missing  the seam is declared but no sentinel exists
+#
 # Usage:
 #   resume-scan.sh scan <project-dir> [--plan <plan.json>]
 #     plan.json: [{"scene_id":"0001","input_sha256":"<hex>"}, …]
 #     stdout: {"scenes":[{scene_id,state,reason?,charged_usd?}],
 #              "green":N,"stale":N,"failed":N,"missing":N,
-#              "spent_usd":X.YZ}
+#              "spent_usd":X.YZ,
+#              "seams":[{from,to,mode,state,reason?}],
+#              "seams_green":N,"seams_stale":N,"seams_missing":N}
 #
 #   resume-scan.sh hash [< prompt.json]
 #     Canonical input hash: jq -S over prompt.json with the
@@ -172,13 +193,81 @@ _rs_scan() {
         else . end)' "${plan}")"
   fi
 
-  printf '%s' "${rows}" | jq '{
+  # --- seam pass ------------------------------------------------------------
+  # Walks the scene dirs in id order; a seam exists between consecutive scenes
+  # when the LATER one declares a handoff continuity. Scene states come from
+  # ${rows} above, so a seam can never disagree with its own scenes.
+  local seam_rows="[]" prev_id="" prev_state="" cur_id cur_state cont sentinel
+  local seam_state seam_reason rec_from rec_to cur_hash prev_hash seam_mode
+  if [ -d "${project_abs}/scenes" ]; then
+    for scene_dir in "${project_abs}"/scenes/*/; do
+      [ -d "${scene_dir}" ] || continue
+      cur_id="$(basename "${scene_dir}")"
+      case "${cur_id}" in
+        *[!A-Za-z0-9._-]*|..|.) continue ;;
+      esac
+      cur_state="$(printf '%s' "${rows}" | jq -r --arg id "${cur_id}" \
+        'map(select(.scene_id == $id)) | (.[0].state // "")')"
+
+      cont="cut"
+      if [ -f "${scene_dir}prompt.json" ]; then
+        cont="$(jq -r '.continuity // "cut"' "${scene_dir}prompt.json" 2>/dev/null || printf 'cut')"
+      fi
+
+      if [ -n "${prev_id}" ] && { [ "${cont}" = "handoff" ] || [ "${cont}" = "connector" ]; }; then
+        seam_mode="${cont}"
+        sentinel="${project_abs}/seams/${prev_id}__${cur_id}.json"
+        seam_state="" seam_reason=""
+        if [ ! -f "${sentinel}" ]; then
+          seam_state="missing"
+          seam_reason="declared ${seam_mode} seam with no sentinel at seams/${prev_id}__${cur_id}.json"
+        else
+          rec_from="$(jq -r '.from_input_sha256 // empty' "${sentinel}" 2>/dev/null || true)"
+          rec_to="$(jq -r '.to_input_sha256 // empty' "${sentinel}" 2>/dev/null || true)"
+          prev_hash="$(jq -r '.input_sha256 // empty' "${project_abs}/scenes/${prev_id}/prompt.json" 2>/dev/null || true)"
+          cur_hash="$(jq -r '.input_sha256 // empty' "${scene_dir}prompt.json" 2>/dev/null || true)"
+          if [ "${prev_state}" != "green" ]; then
+            seam_state="stale"
+            seam_reason="scene ${prev_id} is ${prev_state:-unknown} — the handoff frame it supplies is not a rendered frame"
+          elif [ "${cur_state}" != "green" ]; then
+            seam_state="stale"
+            seam_reason="scene ${cur_id} is ${cur_state:-unknown} — re-render before the seam can be trusted"
+          elif [ -z "${rec_from}" ] || [ -z "${rec_to}" ]; then
+            seam_state="stale"
+            seam_reason="sentinel records no input hashes — never reuse unverifiable state (ADR-059)"
+          elif [ "${rec_from}" != "${prev_hash}" ]; then
+            seam_state="stale"
+            seam_reason="scene ${prev_id} was re-rolled after the seam was built (input hash changed)"
+          elif [ "${rec_to}" != "${cur_hash}" ]; then
+            seam_state="stale"
+            seam_reason="scene ${cur_id} was re-rolled after the seam was built (input hash changed)"
+          else
+            seam_state="green"
+          fi
+        fi
+        seam_rows="$(printf '%s' "${seam_rows}" | jq \
+          --arg from "${prev_id}" --arg to "${cur_id}" --arg mode "${seam_mode}" \
+          --arg st "${seam_state}" --arg rs "${seam_reason}" \
+          '. + [{from:$from, to:$to, mode:$mode, state:$st}
+                + (if $rs == "" then {} else {reason:$rs} end)]')"
+      fi
+
+      prev_id="${cur_id}"
+      prev_state="${cur_state}"
+    done
+  fi
+
+  printf '%s' "${rows}" | jq --argjson seams "${seam_rows}" '{
     scenes: .,
     green:   (map(select(.state == "green"))   | length),
     stale:   (map(select(.state == "stale"))   | length),
     failed:  (map(select(.state == "failed"))  | length),
     missing: (map(select(.state == "missing")) | length),
-    spent_usd: (map(.charged_usd // 0) | add // 0)
+    spent_usd: (map(.charged_usd // 0) | add // 0),
+    seams: $seams,
+    seams_green:   ($seams | map(select(.state == "green"))   | length),
+    seams_stale:   ($seams | map(select(.state == "stale"))   | length),
+    seams_missing: ($seams | map(select(.state == "missing")) | length)
   }'
 }
 

package/src/scripts/ai-video/lib/seam-plan.sh

@@ -0,0 +1,212 @@
+#!/usr/bin/env bash
+# seam-plan.sh — print the seam plan for an ordered chain of scene JSONs.
+#
+# `parse-blueprint.sh` parses ONE scene and emits its `continuity` value (how
+# that scene joins the PREVIOUS one). Nothing there can see a chain, so nothing
+# there can answer the two questions an operator needs BEFORE any spend:
+#
+#   - which boundaries hand off and which cut (a handoff forces the two clips
+#     to render sequentially — the chain loses all parallelism);
+#   - how many generations the chain costs (N, or up to 2N-1 with connectors).
+#
+# This script answers both, reads nothing but local files, and calls no
+# provider. Pure POSIX-compatible bash (no associative arrays, runs on macOS
+# bash 3.2); jq required.
+#
+# Usage:
+#   seam-plan.sh <scene-1.json> <scene-2.json> [...]
+#                [--capabilities-dir <dir>]
+#                [--json]
+#
+#   Scene JSONs are given in RENDER ORDER — the argument order IS the chain.
+#   `--capabilities-dir` defaults to this script's `model-capabilities/`
+#   sibling; it is a flag so a fixture tree can be planned without touching
+#   the shipped manifests.
+#   `--json` emits the machine shape instead of the human plan.
+#
+# The connector gate (`null` is never `true`):
+#   A `connector` boundary generates an extra clip conditioned on an end frame,
+#   so BOTH adjacent models must report a probed `end_frame: true` in their
+#   capability manifest. Anything else — `false`, `null`, a missing `end_frame`
+#   key, a missing model entry, a missing manifest, or a scene that does not
+#   name its adapter/model at all — REFUSES, naming the model. An unknown
+#   capability is not a usable capability, and a connector silently downgraded
+#   to a handoff is a generation the operator did not approve.
+#
+# Exit codes:
+#   0   plan printed
+#   2   usage error, or a refused plan (first-scene continuity, connector gate)
+#   3   tool missing
+#   7   unreadable / invalid scene JSON
+set -euo pipefail
+
+_sp_die() { local code="$1"; shift; printf 'seam-plan: %s\n' "$*" >&2; exit "${code}"; }
+
+command -v jq >/dev/null 2>&1 || _sp_die 3 "jq required"
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+CAP_DIR="${HERE}/model-capabilities"
+AS_JSON=0
+# Scene paths go to a line-delimited temp file rather than into one
+# space-separated string: re-splitting a string on IFS would break the moment a
+# project path contains a space, which on macOS it routinely does.
+SCENE_LIST="$(mktemp -t aiv-seam-plan-XXXXXX)"
+trap 'rm -f "${SCENE_LIST}"' EXIT
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --capabilities-dir) CAP_DIR="${2:-}"; shift 2 ;;
+    --json) AS_JSON=1; shift ;;
+    -h|--help)
+      sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//'
+      exit 0 ;;
+    --*) _sp_die 2 "unknown flag '$1'" ;;
+    *) printf '%s\n' "$1" >> "${SCENE_LIST}"; shift ;;
+  esac
+done
+
+N="$(wc -l < "${SCENE_LIST}" | tr -d ' ')"
+[ "${N}" -ge 1 ] || _sp_die 2 "usage: seam-plan.sh <scene-1.json> <scene-2.json> [...] [--capabilities-dir <dir>] [--json]"
+
+# --- read the chain -----------------------------------------------------------
+# Parallel positional lists (bash 3.2 has no associative arrays): one
+# newline-separated record per scene, `label<TAB>continuity<TAB>adapter<TAB>model`.
+CHAIN=""
+while IFS= read -r scene_file; do
+  [ -n "${scene_file}" ] || continue
+  [ -r "${scene_file}" ] || _sp_die 7 "scene JSON not readable: ${scene_file}"
+  jq -e 'type == "object"' "${scene_file}" >/dev/null 2>&1 \
+    || _sp_die 7 "scene JSON must be an object: ${scene_file}"
+  label="$(basename "${scene_file}")"
+  label="${label%.json}"
+  # A missing `continuity` means `cut` — the value every blueprint written
+  # before the block existed meant.
+  cont="$(jq -r '.continuity // "cut"' "${scene_file}")"
+  case "${cont}" in
+    cut|handoff|connector) ;;
+    *) _sp_die 7 "scene ${label}: unknown continuity value '${cont}' (expected cut|handoff|connector)" ;;
+  esac
+  adapter="$(jq -r '.adapter // ""' "${scene_file}")"
+  model="$(jq -r '.model_id // ""' "${scene_file}")"
+  CHAIN="${CHAIN}${label}	${cont}	${adapter}	${model}
+"
+done < "${SCENE_LIST}"
+
+_sp_field() { # _sp_field <index-1-based> <field-1-based>
+  printf '%s' "${CHAIN}" | sed -n "$1p" | cut -f"$2"
+}
+
+# --- refusal: a non-cut continuity on the first scene -------------------------
+first_label="$(_sp_field 1 1)"
+first_cont="$(_sp_field 1 2)"
+if [ "${first_cont}" != "cut" ]; then
+  _sp_die 2 "scene ${first_label} declares continuity=${first_cont} but has no previous scene to hand off from — the first scene of a chain is always a cut"
+fi
+
+# --- end_frame lookup ---------------------------------------------------------
+# Returns the literal manifest value, or `null` for every kind of not-knowing:
+# missing manifest, missing model entry, missing key, unnamed model. Phase 1's
+# schema keys may not exist yet, so a missing key is read defensively — it is
+# indistinguishable from `null` on purpose.
+_sp_end_frame() { # _sp_end_frame <adapter> <model>
+  local adapter="$1" model="$2" file
+  if [ -z "${adapter}" ] || [ -z "${model}" ]; then printf 'null'; return 0; fi
+  case "${adapter}" in
+    */*|..|.|"") printf 'null'; return 0 ;;
+  esac
+  file="${CAP_DIR}/${adapter}.json"
+  [ -r "${file}" ] || { printf 'null'; return 0; }
+  # `// null` would be WRONG here: jq's alternative operator treats `false` as
+  # absent, so a probed `end_frame: false` would be reported as `null` and the
+  # refusal message would name the wrong reason. `has` distinguishes them.
+  jq -r --arg m "${model}" \
+    '(.models[$m] // {}) | (if has("end_frame") then .end_frame else null end) | tostring' \
+    "${file}" 2>/dev/null || printf 'null'
+}
+
+# --- walk the seams -----------------------------------------------------------
+handoff_count=0
+connector_count=0
+cut_count=0
+PLAN_LINES=""
+SEAM_JSON="[]"
+refusals=""
+
+i=2
+while [ "${i}" -le "${N}" ]; do
+  prev=$((i - 1))
+  from_label="$(_sp_field "${prev}" 1)"
+  to_label="$(_sp_field "${i}" 1)"
+  cont="$(_sp_field "${i}" 2)"
+
+  case "${cont}" in
+    cut) cut_count=$((cut_count + 1)) ;;
+    handoff) handoff_count=$((handoff_count + 1)) ;;
+    connector)
+      connector_count=$((connector_count + 1))
+      from_adapter="$(_sp_field "${prev}" 3)"; from_model="$(_sp_field "${prev}" 4)"
+      to_adapter="$(_sp_field "${i}" 3)";     to_model="$(_sp_field "${i}" 4)"
+      from_ef="$(_sp_end_frame "${from_adapter}" "${from_model}")"
+      to_ef="$(_sp_end_frame "${to_adapter}" "${to_model}")"
+      for side in from to; do
+        if [ "${side}" = "from" ]; then
+          ef="${from_ef}"; m="${from_model}"; a="${from_adapter}"; s="${from_label}"
+        else
+          ef="${to_ef}"; m="${to_model}"; a="${to_adapter}"; s="${to_label}"
+        fi
+        if [ "${ef}" != "true" ]; then
+          [ -n "${m}" ] || m="<unnamed model>"
+          [ -n "${a}" ] || a="<unnamed adapter>"
+          refusals="${refusals}connector refused at seam ${prev}->${i} (${from_label} -> ${to_label}): scene ${s} model '${m}' (adapter ${a}) reports end_frame=${ef} — a connector needs a probed end_frame:true on both sides, and null is not true
+"
+        fi
+      done
+      ;;
+  esac
+
+  PLAN_LINES="${PLAN_LINES}  seam ${prev}->${i} (${from_label} -> ${to_label}): ${cont}
+"
+  SEAM_JSON="$(printf '%s' "${SEAM_JSON}" | jq \
+    --arg from "${from_label}" --arg to "${to_label}" --arg mode "${cont}" \
+    --argjson index "${prev}" \
+    '. + [{index: $index, from: $from, to: $to, mode: $mode}]')"
+  i=$((i + 1))
+done
+
+if [ -n "${refusals}" ]; then
+  printf '%s' "${refusals}" | while IFS= read -r line; do
+    [ -n "${line}" ] && printf 'seam-plan: %s\n' "${line}" >&2
+  done
+  exit 2
+fi
+
+# --- generation count ---------------------------------------------------------
+# Each scene is one generation; each connector seam adds one bridging clip. A
+# chain where EVERY boundary is a connector costs 2N-1, which is the number the
+# operator has to see before approving spend.
+GENS=$((N + connector_count))
+GENS_NOTE=""
+if [ "${N}" -gt 1 ] && [ "${connector_count}" -eq $((N - 1)) ]; then
+  GENS_NOTE=" (2N-1)"
+fi
+
+SEQUENTIAL=false
+if [ $((handoff_count + connector_count)) -gt 0 ]; then SEQUENTIAL=true; fi
+
+if [ "${AS_JSON}" -eq 1 ]; then
+  printf '%s' "${SEAM_JSON}" | jq \
+    --argjson scenes "${N}" --argjson gens "${GENS}" \
+    --argjson handoff "${handoff_count}" --argjson connector "${connector_count}" \
+    --argjson cut "${cut_count}" --argjson sequential "${SEQUENTIAL}" \
+    '{scenes: $scenes, seams: ., handoff: $handoff, connector: $connector,
+      cut: $cut, sequential: $sequential, gens: $gens}'
+  exit 0
+fi
+
+printf 'seam-plan: scenes=%d seams=%d cut=%d handoff=%d connector=%d sequential=%s\n' \
+  "${N}" "$((N > 0 ? N - 1 : 0))" "${cut_count}" "${handoff_count}" "${connector_count}" "${SEQUENTIAL}"
+printf '%s' "${PLAN_LINES}"
+if [ "${SEQUENTIAL}" = "true" ]; then
+  printf 'seam-plan: handoff/connector seams render SEQUENTIALLY — the chain loses parallelism\n'
+fi
+printf 'gens: %d%s\n' "${GENS}" "${GENS_NOTE}"