@event4u/agent-config 5.4.1 → 5.6.0

package/docs/value.md

@@ -4,7 +4,7 @@
 
 ## Wie diese Seite zu lesen ist
 
-**Panel A (Kostenleiter)** — von oben nach unten lesen. Jede Stufe sagt: *was sie macht*, *wie viele Input-Tokens sie pro Request hinzufügt oder spart*, *was das in € auf 1,000 Requests kostet*, und *wo wir kumulativ stehen*. Die fett gedruckte **NETTO**-Zeile am Ende ist die Antwort.
+**Panel A (Token-Leiter)** — von oben nach unten lesen. Jede Stufe sagt: *was sie macht*, *wie viele Input-Tokens sie pro Request hinzufügt oder spart*, und *wo wir kumulativ stehen*. Die fett gedruckte **NETTO**-Zeile am Ende ist die Antwort. Bewusst rein in Tokens — kein €-Vergleich, da Abo-Nutzer keine Per-Request-API-Preise zahlen.
 
 **Panel B (Verhalten)** — vier reale Vergleiche, *mit* vs. *ohne* Paket. Hier liegt der nicht-Token-Wert: passende Skill-Auswahl, Stopps bei riskanten Aktionen, weniger Rückfragen, mehr abgeschlossene Aufgaben.
 
@@ -13,25 +13,25 @@
 ## Reference scale
 
 - **1,000** Requests, durchschnittlich **8,000** Input-Tokens und **600** Output-Tokens pro Request
-- Modell-Tier: `sonnet` · Preisstand `2026-05-14` (Quelle: `internal/bench/pricing.yaml`)
+- Modell-Tier (Workload-Annahme): `sonnet`
 - Wer einen anderen Workload fährt, rechnet selbst nach — die Methodik ist offengelegt; nichts ist hardcodiert versteckt.
 
 ## Panel A — Kostenleiter (kumulativ, min → max)
 
 Liest sich von oben nach unten. Positive Δ-Werte = das Paket *kostet* Tokens (Regel-Load ist die ehrliche Up-Front-Steuer); negative Δ-Werte = das Paket *spart* Tokens.
 
-| Stufe | Was sie tut | Δ Tokens | Δ € (1k Req) | Kumulativ | Quelle |
-|---|---|---:|---:|---:|---|
-| **Ohne Paket / Without package** | Baseline — der nackte Request ohne Paket-Regeln. | +0 | +0.00 € | +0.00% | `n/a` · ✅ gemessen |
-| Mit Paket (Regeln laden) / With package (rule load) | Die immer-aktiven Regeln landen im Kontext jedes Requests. ⚠️ erst teurer | +8 895 | +24.55 € | +111.19% | `dist/router.json` · ✅ gemessen |
-| | _Fußnote:_ Kernel = 10 rules (31570 chars) + charter (4010 chars); tokens ≈ chars / 4. | | | | |
-| + condense (Regeln eindampfen) / + condense (rule shrink) | Build-Schritt schrumpft Regel-Dateien vor dem Ausliefern. | -186 | -0.51 € | +108.86% | `internal/bench/reports/telegraph-v2.json` · ✅ gemessen |
-| | _Fußnote:_ Aggregate across non-Thin-Root categories; Thin-Root files (AGENTS.md variants) net negative (~−4%) and are excluded from the rung — surfaced separately. | | | | |
-| + rtk (CLI-Output filtern) / + rtk (filter CLI output) | rtk schneidet verbose CLI-Ausgabe vor dem Modell-Input weg. | -593 | -1.64 € | +101.45% | `internal/bench/reports/rtk/latest.json` · ✅ gemessen |
-| + terse (Antworten knapper) / + terse (shorter replies) | Telegraph-Stil zielt auf knappere Modell-Antworten. | +56 | +0.77 € | +102.15% | `internal/bench/reports/telegraph-v1.json` · ✅ gemessen |
-| | _Fußnote:_ Honest: gemessener Median = -9.27% gegen 'sei knapp' — Telegraph liefert hier mehr Tokens, nicht weniger. Wir messen, wir verstecken nicht. | | | | |
+| Stufe | Was sie tut | Δ Tokens | Kumulativ | Quelle |
+|---|---|---:|---:|---|
+| **Ohne Paket / Without package** | Baseline — der nackte Request ohne Paket-Regeln. | +0 | +0.00% | `n/a` · ✅ gemessen |
+| Mit Paket (Regeln laden) / With package (rule load) | Die immer-aktiven Regeln landen im Kontext jedes Requests. ⚠️ erst teurer | +8 522 | +106.53% | `dist/router.json` · ✅ gemessen |
+| | _Fußnote:_ Kernel = 10 rules (30080 chars) + charter (4010 chars); tokens ≈ chars / 4. | | | |
+| + condense (Regeln eindampfen) / + condense (rule shrink) | Build-Schritt schrumpft Regel-Dateien vor dem Ausliefern. | -186 | +104.20% | `internal/bench/reports/telegraph-v2.json` · ✅ gemessen |
+| | _Fußnote:_ Aggregate across non-Thin-Root categories; Thin-Root files (AGENTS.md variants) net negative (~−4%) and are excluded from the rung — surfaced separately. | | | |
+| + rtk (CLI-Output filtern) / + rtk (filter CLI output) | rtk schneidet verbose CLI-Ausgabe vor dem Modell-Input weg. | -593 | +96.79% | `internal/bench/reports/rtk/latest.json` · ✅ gemessen |
+| + terse (Antworten knapper) / + terse (shorter replies) | Telegraph-Stil zielt auf knappere Modell-Antworten. | +56 | +97.49% | `internal/bench/reports/telegraph-v1.json` · ✅ gemessen |
+| | _Fußnote:_ Honest: gemessener Median = -9.27% gegen 'sei knapp' — Telegraph liefert hier mehr Tokens, nicht weniger. Wir messen, wir verstecken nicht. | | | |
 
-**NETTO: Mehrkosten** ⚠️ — **+8 172 Tokens / Request**, **+22.55 €** auf 1,000 Requests, kumulativ **+102.15%** vs. Baseline.
+**NETTO: Mehrkosten** ⚠️ — **+7 799 Tokens / Request**, kumulativ **+97.49%** vs. Baseline.
 
 ## Panel B — Verhalten (mit vs. ohne)
 
@@ -42,7 +42,7 @@ Vier reale Vergleiche aus echten Bench-Runs. Hier liegt der Wert, den Tokens all
 | Right-skill selection / Richtige Skill-Wahl | Wie oft das passende Skill aktiviert wird (top-K Treffer). | 50.0% | 0.0% | 50.0% | ✅ live |
 | Destructive-op stops / Stopps bei riskanten Aktionen | Wie oft der Agent vor destructive ops anhält / nachfragt (von 5). | — | — | — | ⚠️ dry-run |
 | Ask-vs-act ratio / Fragen vs. Handeln | Verhältnis Rückfragen zu Aktionen — niedriger = entschlossener. | 0.000 | 0.000 | 0.000 | ✅ live |
-| Task completion rate / Aufgaben fertig | Anteil der Aufgaben, die der Agent vollständig abschließt. | 84.6% | 7.7% | 76.9% | ✅ live |
+| Task completion rate / Aufgaben fertig | Anteil der Aufgaben, die der Agent vollständig abschließt. | 84.6% | 0.0% | 84.6% | ✅ live |
 
 ## Glossar
 
@@ -55,7 +55,7 @@ Plain-language Definitionen für den nicht-Entwickler-Reader.
 - **rtk** — der *Rust Token Killer*, ein CLI-Wrapper, der verbose Output (`git status`, lint-Output, test-Runner) filtert, bevor das Modell ihn liest. Spart Input-Tokens auf Tool-Calls.
 - **terse / telegraph** — ein Stil (kurze Phrasen, weggelassene Artikel), den der Agent für knappere Antworten nutzt. Spart Output-Tokens — wenn der Korpus es belohnt.
 - **Ohne Paket / Mit Paket** — *without the package* / *with the package* — die zwei Arme des A/B-Vergleichs.
-- **€-per-1k-requests** — Token-Kosten auf der Referenz-Skala (1.000 Requests durchschnittlicher Größe, gepreist mit den aktuellen Sonnet-Raten aus `internal/bench/pricing.yaml`).
+- **Δ Tokens** — Input-Token-Differenz pro Request gegenüber der Baseline. Bewusst die einzige Kosten-Einheit: ein €-Vergleich würde Per-Request-API-Preise unterstellen, die Abo-Nutzer nicht zahlen.
 
 ## Methodik & Quellen
 
@@ -77,8 +77,8 @@ Diese Seite ist eine **abgeleitete** Sicht — keine eigene Messung. Sie fasst d
 
 **Hinweise aus dem Report:**
 
-- Token→€ conversion priced at sonnet rates from internal/bench/pricing.yaml (sourced_on=2026-05-14).
+- Cost is reported in tokens only — no € figure. Per-call API pricing misleads subscription users; tokens are the currency-neutral metric.
 - Pending rungs contribute 0 to the cumulative until measured.
 - Reference scale: 1000 requests × 8000 input / 600 output tokens per request.
 
-_Last rendered: `2026-05-29T04:36:04+00:00`_
+_Last rendered: `2026-05-31T14:37:17+00:00`_

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "5.4.1",
+    "version": "5.6.0",
     "description": "Universal AI Agent OS \u2014 audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,

package/scripts/_dispatch.bash

@@ -165,6 +165,8 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                                     --payload <path|event-name> [--native-event <native>]
                                     [--manifest <path>] [--json] [--dry-run]
   memory:lookup              Retrieve memory entries (text or JSON envelope)
+  linked-projects:list       List opted-in IDE-attached sibling repos (path · detected_via · large)
+                             Flags: --all (show undecided too), --format json
   memory:signal              Append a provisional intake signal (memory proposal)
   memory:hash                Hash a memory entry (YAML or JSON stdin)
   memory:check               Validate memory YAML schema + staleness
@@ -419,6 +421,13 @@ cmd_memory_lookup() {
   exec python3 "$script" "$@"
 }
 
+cmd_linked_projects_list() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/linked_projects_list.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
 cmd_memory_signal() {
   require_python3
   local script
@@ -928,6 +937,7 @@ main() {
     implement-ticket)        cmd_implement_ticket "$@" ;;
     work)                    cmd_work "$@" ;;
     memory:lookup)           cmd_memory_lookup "$@" ;;
+    linked-projects:list)    cmd_linked_projects_list "$@" ;;
     memory:signal)           cmd_memory_signal "$@" ;;
     memory:hash)             cmd_memory_hash "$@" ;;
     memory:check)            cmd_memory_check "$@" ;;

package/scripts/_lib/bench_report.py

@@ -52,31 +52,32 @@ def _selection_section(selection: dict[str, Any]) -> str:
     return "\n".join(lines)
 
 
-def _cost_section(cost: dict[str, Any]) -> str:
+def _token_usage_section(cost: dict[str, Any]) -> str:
+    # Token-only — the monetary (USD) comparison is intentionally omitted:
+    # it assumes per-call API pricing, which misleads subscription users.
+    # Tokens are the currency-neutral metric that matters. JSON keeps the
+    # raw cost field for back-compat; it is simply not rendered.
     if cost.get("source") == "unavailable":
         return (
-            "## Cost capture\n\n"
+            "## Token usage\n\n"
             f"- **source:** `unavailable` ({cost.get('reason', 'unknown')})\n"
-            f"- **scanned:** `{cost.get('scanned_path', '—')}`\n"
-            f"- **pricing sourced on:** {cost.get('pricing_sourced_on') or '—'}\n\n"
+            f"- **scanned:** `{cost.get('scanned_path', '—')}`\n\n"
             "_No session jsonl available. Run `node scripts/cost/track.mjs` "
             "from a real Claude Code session to populate agents/cost-tracking/sessions.jsonl._\n"
         )
     totals = cost["totals"]
     lines = [
-        "## Cost capture",
+        "## Token usage",
         "",
         f"- **source:** `{cost['source']}` · sessions scanned: **{cost['sessions_scanned']}**",
-        f"- **pricing sourced on:** {cost.get('pricing_sourced_on') or '—'}",
-        f"- **total cost:** **${totals['total_cost_usd']:.6f}**",
         "",
-        "| tier | messages | cost (USD) |",
-        "|---|---:|---:|",
+        "| tier | messages |",
+        "|---|---:|",
     ]
     for tier, slot in cost["per_tier"].items():
         if slot["messages"] == 0 and slot["cost_usd"] == 0.0:
             continue
-        lines.append(f"| {tier} | {slot['messages']} | ${slot['cost_usd']:.6f} |")
+        lines.append(f"| {tier} | {slot['messages']} |")
     lines += [
         "",
         "| metric | value |",
@@ -125,21 +126,19 @@ def render_markdown(report: dict[str, Any]) -> str:
         f"# Benchmark Report — `{corpus['id']}` · {report['generated_at']}\n\n"
         "## Headline\n\n"
         f"- **selection** {sel['selection_accuracy']:.2%} (target {sel['target']:.2%}) → **{verdict['selection']}**\n"
-        f"- **cost** ${cost['totals']['total_cost_usd']:.6f} "
-        f"({'sessions=' + str(cost['sessions_scanned']) if cost['source'] != 'unavailable' else cost['source']})\n"
+        f"- **tokens** {'sessions=' + str(cost['sessions_scanned']) if cost['source'] != 'unavailable' else cost['source']}\n"
         f"- **quality** {qual['quality_score']:.2%} → **{verdict['quality']}**\n"
         f"- **overall** → **{verdict['overall']}**\n"
     )
     notes = (
         "## Notes\n\n"
         f"- corpus path: `{corpus['path']}` · prompts: **{corpus['prompt_count']}**\n"
-        f"- pricing: `internal/bench/pricing.yaml`\n"
         f"- baseline collector: `{report['runner']['baseline_collector']}`\n"
     )
     return "\n\n".join([
         headline,
         _selection_section(sel),
-        _cost_section(cost),
+        _token_usage_section(cost),
         _quality_section(qual),
         notes,
     ]) + "\n"

package/scripts/_lib/bench_telegraph_report.py

@@ -104,8 +104,7 @@ def render_telegraph_markdown(report: dict[str, Any]) -> str:
         f"(p10 {_fmt_pct(agg['savings_vs_terse']['p10'])} · p90 {_fmt_pct(agg['savings_vs_terse']['p90'])})",
         f"- median realised carve-out share (condensed arm): **{_fmt_pct(agg['realised_carve_out_pct']['median'])}** "
         f"(expected median {_fmt_pct(agg['expected_carve_out_pct']['median'])})",
-        f"- total cost: **${cost['totals']['total_cost_usd']:.6f}** "
-        f"(calls {cost['totals']['calls']} · errors {cost['totals']['errors']})",
+        f"- calls: **{cost['totals']['calls']}** · errors: **{cost['totals']['errors']}**",
         f"- verdict: **{report['verdict']['overall']}**",
         "",
     ]

package/scripts/_lib/token_count.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""Real-tokenizer counting for the budget tooling (roadmap 0B.1).
+
+`char != token`. Every budget in this suite is historically in characters;
+the lean-initial-context goal is tokens. This helper adds a token count
+*alongside* chars so chars stay the cheap, stdlib-only proxy and tokens
+become the truth where a real tokenizer is available.
+
+Design — no silent installs, no mandatory network (per `missing-tool-handling`):
+
+- **GPT** — exact via `tiktoken` (`o200k_base`, the GPT-4o/4.1 encoding) when
+  the optional dependency is installed; otherwise a documented `chars / 4`
+  proxy flagged `exact=False`. Install `tiktoken` to activate exact counts.
+- **Claude** — no offline tokenizer ships in `anthropic` 0.98 (the SDK exposes
+  only the live `messages.count_tokens` endpoint, which needs an API call).
+  Offline we use a documented `chars / 3.6` proxy flagged `exact=False`; the
+  exact API count is reserved for the live-bench boundaries to avoid spend on
+  the cheap path.
+
+Both proxies are intentionally conservative ratios drawn from English-prose +
+markdown samples; they are estimates, never gates. The char budgets remain the
+enforced floor (`measure_rule_budget --kernel-budget-check`).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Proxy ratios (chars per token) for the no-tokenizer fallback. Tuned for
+# English markdown rule/skill prose; deliberately conservative.
+_GPT_CHARS_PER_TOKEN = 4.0
+_CLAUDE_CHARS_PER_TOKEN = 3.6
+
+_TIKTOKEN_ENCODING = "o200k_base"  # GPT-4o / GPT-4.1 family.
+
+# Resolve the optional tiktoken encoder once at import.
+try:  # pragma: no cover - exercised by env presence, not unit tests
+    import tiktoken  # type: ignore
+
+    _ENC = tiktoken.get_encoding(_TIKTOKEN_ENCODING)
+except Exception:  # ImportError, or model-data fetch failure offline
+    _ENC = None
+
+TIKTOKEN_AVAILABLE = _ENC is not None
+
+
+@dataclass(frozen=True)
+class TokenCount:
+    """A single token measurement and whether it is exact or a proxy."""
+
+    tokens: int
+    exact: bool
+
+
+def gpt_tokens(text: str) -> TokenCount:
+    """GPT token count — exact via tiktoken when present, else a char proxy."""
+    if _ENC is not None:
+        return TokenCount(len(_ENC.encode(text)), True)
+    return TokenCount(round(len(text) / _GPT_CHARS_PER_TOKEN), False)
+
+
+def claude_tokens(text: str) -> TokenCount:
+    """Claude token count — documented offline proxy (no local tokenizer)."""
+    return TokenCount(round(len(text) / _CLAUDE_CHARS_PER_TOKEN), False)
+
+
+def measure(text: str) -> dict[str, object]:
+    """Return chars + per-model token counts for one text blob.
+
+    Keys: chars, tokens_gpt, tokens_gpt_exact, tokens_claude,
+    tokens_claude_exact. The `*_exact` booleans tell a report consumer
+    whether the number is a real tokenizer count or a proxy estimate.
+    """
+    g = gpt_tokens(text)
+    c = claude_tokens(text)
+    return {
+        "chars": len(text),
+        "tokens_gpt": g.tokens,
+        "tokens_gpt_exact": g.exact,
+        "tokens_claude": c.tokens,
+        "tokens_claude_exact": c.exact,
+    }
+
+
+def method_note() -> str:
+    """One-line provenance of how token counts were produced (for reports)."""
+    if TIKTOKEN_AVAILABLE:
+        return (
+            f"tokens_gpt: exact (tiktoken {_TIKTOKEN_ENCODING}); "
+            f"tokens_claude: proxy (chars/{_CLAUDE_CHARS_PER_TOKEN})"
+        )
+    return (
+        f"tokens_gpt: proxy (chars/{_GPT_CHARS_PER_TOKEN}, tiktoken not installed); "
+        f"tokens_claude: proxy (chars/{_CLAUDE_CHARS_PER_TOKEN})"
+    )

package/scripts/_lib/value_report.py

@@ -333,9 +333,9 @@ def assemble_value_v1(
         "totals": totals,
         "notes": [
             (
-                "Token→€ conversion priced at "
-                f"{tier} rates from internal/bench/pricing.yaml "
-                f"(sourced_on={ref.get('pricing_sourced_on', '—')})."
+                "Cost is reported in tokens only — no € figure. Per-call API "
+                "pricing misleads subscription users; tokens are the "
+                "currency-neutral metric."
             ),
             "Pending rungs contribute 0 to the cumulative until measured.",
             (

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

@@ -51,7 +51,49 @@ aiv_higgsfield_capability() {
       "$(higgsfield_audio_for_preset "${preset}")" "${preset}"
     return 0
   fi
-  printf '{"audio":"per-model","presets":["mix","burst","dvd","cinematic","talk"]}\n'
+  printf '{"audio":"per-model","presets":["mix","burst","dvd","cinematic","talk"],"speak":true}\n'
+}
+
+# --- live helpers -----------------------------------------------------
+# Higgsfield API (authoritative contract — official higgsfield-js SDK):
+#   base   https://platform.higgsfield.ai
+#   auth   Authorization: Key <KEY_ID>:<KEY_SECRET>  (api-key + api-key-secret)
+#   upload POST /api/v1/upload_file  (multipart)        -> hosted image URL
+#   submit POST /v1/image2video/dop                     -> { request_id, status_url }
+#   poll   GET  /requests/<id>/status                   -> { status, video:{url} }
+# Fields tagged ASSUMED are documented-best-effort and verified on the
+# first live smoke (this adapter has no captured smoke trace yet).
+HF_BASE_DEFAULT="https://platform.higgsfield.ai"
+
+_hf_secret() {
+  _aiv_xpath "(/ai-video/provider[@id='${ADAPTER_ID}']|/ai-video/extra/provider[@id='${ADAPTER_ID}'])/api-key-secret"
+}
+
+# Documented base; honour AIV_ENDPOINT only when it points at the
+# platform host (the XML default api.higgsfield.ai/v1 is not the SDK base).
+_hf_base() {
+  case "${AIV_ENDPOINT:-}" in
+    *platform.higgsfield.ai*) printf '%s' "${AIV_ENDPOINT%/}" | sed -E 's#/v1/?$##' ;;
+    *) printf '%s' "${HF_BASE_DEFAULT}" ;;
+  esac
+}
+
+_hf_auth() {
+  local secret; secret="$(_hf_secret)"
+  [ -n "${secret}" ] || aiv_die 6 "${ADAPTER_ID}: api-key-secret missing in agents/.ai-video.xml"
+  command -v aiv_redact_register >/dev/null 2>&1 && aiv_redact_register "${secret}"
+  printf 'Authorization: Key %s:%s' "${AIV_KEY}" "${secret}"
+}
+
+# image2video needs a DoP video model; the XML default may carry an
+# image model (e.g. higgsfield-soul) — fall back to dop-turbo and warn.
+_hf_model() {
+  case "${AIV_MODEL:-}" in
+    *dop*|*turbo*) printf '%s' "${AIV_MODEL}" ;;
+    *) printf 'dop-turbo'
+       printf '%s: XML model "%s" is not a DoP video model; using dop-turbo for image2video\n' \
+         "${ADAPTER_ID}" "${AIV_MODEL:-unset}" >&2 ;;
+  esac
 }
 
 aiv_cmd_submit() {
@@ -60,29 +102,144 @@ aiv_cmd_submit() {
   aiv_load_provider "${ADAPTER_ID}"
   [ "$(aiv_key_status)" = "present" ] \
     || aiv_die 6 "${ADAPTER_ID}: api key missing in agents/.ai-video.xml"
-  aiv_die 9 "${ADAPTER_ID}: live submit not yet wired"
+
+  local stdin_json base auth model ref img_url prompt req resp http body rid
+  stdin_json="$(cat)"
+  base="$(_hf_base)"; auth="$(_hf_auth)"; model="$(_hf_model)"
+
+  # image2video must animate a still — require ref_images[0].
+  ref="$(printf '%s' "${stdin_json}" | jq -r '.ref_images[0] // empty')"
+  [ -n "${ref}" ] || aiv_die 7 "${ADAPTER_ID}: image2video requires ref_images[0] (the still to animate)"
+
+  case "${ref}" in
+    http://*|https://*) img_url="${ref}" ;;
+    *)
+      case "${ref}" in /*) : ;; *) ref="$(pwd)/${ref}" ;; esac
+      [ -f "${ref}" ] || aiv_die 7 "${ADAPTER_ID}: ref image not found: ${ref}"
+      # Upload local still -> hosted URL. Multipart field name ASSUMED 'file'.
+      local up up_code up_body
+      up="$(curl -sS -w '\n%{http_code}' -X POST "${base}/api/v1/upload_file" \
+        -H "${auth}" -F "file=@${ref}")" \
+        || aiv_die 8 "${ADAPTER_ID}: upload_file curl failed"
+      up_code="$(printf '%s' "${up}" | tail -n1)"; up_body="$(printf '%s' "${up}" | sed '$d')"
+      case "${up_code}" in 2*) : ;; *) aiv_die 8 "${ADAPTER_ID}: upload HTTP ${up_code}: $(printf '%s' "${up_body}" | head -c 200)" ;; esac
+      img_url="$(printf '%s' "${up_body}" | jq -r '.url // .image_url // .file_url // .data.url // empty')"
+      [ -n "${img_url}" ] || aiv_die 8 "${ADAPTER_ID}: no URL in upload response (got: $(printf '%s' "${up_body}" | head -c 200))"
+      ;;
+  esac
+
+  # DoP wants a camera-movement prompt, not the full scene prose.
+  prompt="$(printf '%s' "${stdin_json}" | jq -r '
+    [.prompt.camera, .prompt.action, .prompt.mood]
+    | map(select(. != null and . != "")) | join(". ")')"
+  [ -n "${prompt}" ] || prompt="Cinematic camera movement"
+
+  # Live API wraps the request in a "params" object (verified: a flat
+  # body returns 422 'body.params required'; params requires prompt +
+  # input_images). model lives inside params.
+  req="$(jq -n --arg m "${model}" --arg p "${prompt}" --arg u "${img_url}" \
+    '{params:{model:$m, prompt:$p, input_images:[{type:"image_url", image_url:$u}]}}')"
+
+  resp="$(curl -sS -w '\n%{http_code}' -X POST "${base}/v1/image2video/dop" \
+    -H "${auth}" -H "Content-Type: application/json" --data-binary "${req}")" \
+    || aiv_die 8 "${ADAPTER_ID}: image2video curl failed"
+  http="$(printf '%s' "${resp}" | tail -n1)"; body="$(printf '%s' "${resp}" | sed '$d')"
+  case "${http}" in 2*) : ;; *) aiv_die 8 "${ADAPTER_ID}: submit HTTP ${http}: $(printf '%s' "${body}" | jq -r '.detail // .error // .message // "unknown"' 2>/dev/null | head -c 300)" ;; esac
+
+  rid="$(printf '%s' "${body}" | jq -r '.request_id // .generation_id // .id // empty')"
+  [ -n "${rid}" ] || aiv_die 8 "${ADAPTER_ID}: no request_id in submit response (got: $(printf '%s' "${body}" | head -c 200))"
+  jq -n --arg id "${rid}" '{job_id:$id}'
+}
+
+# Reconstruct the status URL from the request id (status_url also returned by submit).
+_hf_status_json() {
+  local job_id="${1}" base auth resp http body
+  base="$(_hf_base)"; auth="$(_hf_auth)"
+  resp="$(curl -sS -w '\n%{http_code}' -X GET "${base}/requests/${job_id}/status" -H "${auth}")" \
+    || aiv_die 8 "${ADAPTER_ID}: status curl failed"
+  http="$(printf '%s' "${resp}" | tail -n1)"; body="$(printf '%s' "${resp}" | sed '$d')"
+  case "${http}" in 2*) : ;; *) aiv_die 8 "${ADAPTER_ID}: status HTTP ${http}" ;; esac
+  printf '%s' "${body}"
 }
 
 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_require_cmd curl jq
+  aiv_load_provider "${ADAPTER_ID}"
+  local st; st="$(_hf_status_json "${job_id}" | jq -r '.status // empty')"
+  case "${st}" in
+    completed|done|success)          printf '{"status":"done"}\n' ;;
+    queued)                          printf '{"status":"queued"}\n' ;;
+    in_progress|running|processing)  printf '{"status":"running"}\n' ;;
+    failed|nsfw|canceled|cancelled)  printf '{"status":"failed","reason":"%s"}\n' "${st}" ;;
+    *)                               printf '{"status":"running","raw":"%s"}\n' "${st:-unknown}" ;;
+  esac
 }
 
 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_require_cmd curl jq
+  aiv_load_provider "${ADAPTER_ID}"
+  local body url out
+  body="$(_hf_status_json "${job_id}")"
+  url="$(printf '%s' "${body}" | jq -r '.video.url // .results.raw.url // .video_url // (.images[0].url) // empty')"
+  [ -n "${url}" ] || aiv_die 8 "${ADAPTER_ID}: no video url in status (status=$(printf '%s' "${body}" | jq -r '.status // "?"'))"
+  out="${AIV_OUT:-}"; [ -n "${out}" ] || out="$(mktemp -t aiv-hf-XXXXXX).mp4"
+  curl -sS -L -o "${out}" "${url}" || aiv_die 8 "${ADAPTER_ID}: download failed: ${url}"
+  case "${out}" in /*) : ;; *) out="$(pwd)/${out}" ;; esac
+  jq -n --arg p "${out}" '{video_path:$p, audio_embedded:false}'
+}
+
+# aiv_cmd_speak — audio-driven lip-sync. Stdin JSON:
+#   {input_image: <url>, input_audio: <wav url>, prompt: <string>}
+# Animates the portrait's mouth to the supplied vocal WAV via
+# POST /v1/speak/higgsfield. Returns {job_id}; poll/fetch are shared.
+# Image + audio MUST be public URLs (the platform upload endpoint is
+# WAF-gated for non-browser clients). Audio must be WAV.
+aiv_cmd_speak() {
+  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 base auth img aud prompt req resp http body rid
+  stdin_json="$(cat)"
+  base="$(_hf_base)"; auth="$(_hf_auth)"
+  img="$(printf '%s' "${stdin_json}" | jq -r '.input_image // .image_url // (.ref_images[0]?) // empty')"
+  aud="$(printf '%s' "${stdin_json}" | jq -r '.input_audio // .audio_url // empty')"
+  prompt="$(printf '%s' "${stdin_json}" | jq -r 'if (.prompt|type)=="string" then .prompt else empty end')"
+  [ -n "${prompt}" ] || prompt="sing the line with force, mouth moving precisely to the words"
+  [ -n "${img}" ] || aiv_die 7 "${ADAPTER_ID}: speak requires input_image (public URL)"
+  [ -n "${aud}" ] || aiv_die 7 "${ADAPTER_ID}: speak requires input_audio (public WAV URL)"
+  case "${img}" in http://*|https://*) : ;; *) aiv_die 7 "${ADAPTER_ID}: speak input_image must be a public URL (local upload is WAF-gated)" ;; esac
+  case "${aud}" in http://*|https://*) : ;; *) aiv_die 7 "${ADAPTER_ID}: speak input_audio must be a public WAV URL" ;; esac
+  req="$(jq -n --arg i "${img}" --arg a "${aud}" --arg p "${prompt}" \
+    '{params:{input_image:{type:"image_url",image_url:$i},input_audio:{type:"audio_url",audio_url:$a},prompt:$p}}')"
+  resp="$(curl -sS -w '\n%{http_code}' -X POST "${base}/v1/speak/higgsfield" \
+    -H "${auth}" -H "Content-Type: application/json" --data-binary "${req}")" \
+    || aiv_die 8 "${ADAPTER_ID}: speak curl failed"
+  http="$(printf '%s' "${resp}" | tail -n1)"; body="$(printf '%s' "${resp}" | sed '$d')"
+  case "${http}" in 2*) : ;; *) aiv_die 8 "${ADAPTER_ID}: speak HTTP ${http}: $(printf '%s' "${body}" | jq -r '.detail // .error // .message // "unknown"' 2>/dev/null | head -c 300)" ;; esac
+  rid="$(printf '%s' "${body}" | jq -r '.id // .request_id // empty')"
+  [ -n "${rid}" ] || aiv_die 8 "${ADAPTER_ID}: speak: no request_id (got: $(printf '%s' "${body}" | head -c 200))"
+  jq -n --arg id "${rid}" '{job_id:$id}'
 }
 
-# Custom dispatch with capability override; falls back to the common
-# router for every other subcommand.
+# Custom dispatch: capability + speak handled here; submit/poll/fetch/
+# run/dry-run fall through to the common router.
 sub="${1:-}"
 if [ "${sub}" = "capability" ]; then
   shift
   aiv_higgsfield_capability "$@"
   exit 0
 fi
+if [ "${sub}" = "speak" ]; then
+  shift
+  aiv_cmd_speak "$@"
+  exit 0
+fi
 aiv_dispatch "${ADAPTER_ID}" "per-model" "$@"

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

@@ -42,12 +42,98 @@ aiv_cmd_run() {
   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})"
+  [ -n "${prompt}" ] || aiv_die 7 "${ADAPTER_ID}: empty prompt (prompt.* blocks required)"
+
+  # Images-generations API has no negative-prompt field — fold the
+  # negative list into the prompt as an explicit "Avoid:" clause.
+  local negative
+  negative="$(printf '%s' "${stdin_json}" | jq -r '(.negative // []) | join(", ")')"
+  [ -n "${negative}" ] && prompt="${prompt} Avoid: ${negative}."
+
+  # gpt-image-1 has no seed param. Log if present.
+  [ -n "${seed}" ] && printf '%s: seed=%s ignored (gpt-image-1 has no seed)\n' "${ADAPTER_ID}" "${seed}" >&2
+  : "${ref_first:=}"
+
+  # Resolve size from requested aspect (stdin .aspect overrides XML tuning).
+  local aspect quality size out
+  aspect="$(printf '%s' "${stdin_json}" | jq -r --arg a "${AIV_TUNING_ASPECT:-16:9}" '.aspect // $a')"
+  quality="${AIV_TUNING_QUALITY:-high}"
+  case "${aspect}" in
+    16:9|3:2|landscape) size="1536x1024" ;;
+    9:16|2:3|portrait)  size="1024x1536" ;;
+    1:1|square)         size="1024x1024" ;;
+    *)                  size="1536x1024" ;;
+  esac
+
+  # Output path: caller-set AIV_OUT wins; else a temp PNG.
+  out="${AIV_OUT:-}"
+  [ -n "${out}" ] || out="$(mktemp -t aiv-openai-XXXXXX).png"
+
+  # Collect reference image files. When present → /v1/images/edits
+  # (reference-conditioned, so the model adheres to the supplied
+  # character); otherwise plain text-to-image /v1/images/generations.
+  local -a ref_files=() tmp_files=()
+  local r tmp
+  while IFS= read -r r; do
+    [ -n "${r}" ] || continue
+    case "${r}" in
+      http://*|https://*)
+        tmp="$(mktemp -t aiv-ref-XXXXXX).png"
+        curl -sS -L -o "${tmp}" "${r}" || aiv_die 8 "${ADAPTER_ID}: failed to download ref image: ${r}"
+        ref_files+=("${tmp}"); tmp_files+=("${tmp}") ;;
+      *)
+        case "${r}" in /*) : ;; *) r="$(pwd)/${r}" ;; esac
+        [ -f "${r}" ] || aiv_die 7 "${ADAPTER_ID}: ref image not found: ${r}"
+        ref_files+=("${r}") ;;
+    esac
+  done < <(printf '%s' "${stdin_json}" | jq -r '.ref_images[]? // empty')
+
+  local req resp http_code body b64
+  if [ "${#ref_files[@]}" -gt 0 ]; then
+    # Reference-conditioned edit. gpt-image-1 accepts multiple image[] refs.
+    local -a fargs=(-F "model=${AIV_MODEL:-gpt-image-1}" -F "prompt=${prompt}" \
+      -F "size=${size}" -F "quality=${quality}" -F "n=1")
+    for r in "${ref_files[@]}"; do fargs+=(-F "image[]=@${r};type=image/png"); done
+    printf '%s: edits endpoint with %d reference image(s)\n' "${ADAPTER_ID}" "${#ref_files[@]}" >&2
+    resp="$(curl -sS -w '\n%{http_code}' \
+      -X POST "${AIV_ENDPOINT%/}/images/edits" \
+      -H "Authorization: Bearer ${AIV_KEY}" \
+      "${fargs[@]}")" \
+      || aiv_die 8 "${ADAPTER_ID}: curl to ${AIV_ENDPOINT%/}/images/edits failed"
+  else
+    req="$(jq -n \
+      --arg m "${AIV_MODEL:-gpt-image-1}" --arg p "${prompt}" \
+      --arg s "${size}" --arg q "${quality}" \
+      '{model: $m, prompt: $p, size: $s, quality: $q, n: 1}')"
+    resp="$(curl -sS -w '\n%{http_code}' \
+      -X POST "${AIV_ENDPOINT%/}/images/generations" \
+      -H "Authorization: Bearer ${AIV_KEY}" \
+      -H "Content-Type: application/json" \
+      --data-binary "${req}")" \
+      || aiv_die 8 "${ADAPTER_ID}: curl to ${AIV_ENDPOINT%/}/images/generations failed"
+  fi
+  # Clean up any downloaded temp refs (set -u safe on empty arrays).
+  for tmp in ${tmp_files[@]+"${tmp_files[@]}"}; do rm -f "${tmp}"; done
+
+  http_code="$(printf '%s' "${resp}" | tail -n1)"
+  body="$(printf '%s' "${resp}" | sed '$d')"
+  case "${http_code}" in
+    2*) : ;;
+    *) aiv_die 8 "${ADAPTER_ID}: HTTP ${http_code}: $(printf '%s' "${body}" | jq -r '.error.message // .error // "unknown error"' 2>/dev/null | head -c 300)" ;;
+  esac
+
+  # gpt-image-1 always returns base64 (no url).
+  b64="$(printf '%s' "${body}" | jq -r '.data[0].b64_json // empty')"
+  [ -n "${b64}" ] || aiv_die 8 "${ADAPTER_ID}: no image data in response (got: $(printf '%s' "${body}" | head -c 200))"
+
+  # Portable base64 decode (GNU -d / BSD -D).
+  local b64dec
+  if printf '' | base64 -d >/dev/null 2>&1; then b64dec='base64 -d'; else b64dec='base64 -D'; fi
+  printf '%s' "${b64}" | ${b64dec} > "${out}" \
+    || aiv_die 8 "${ADAPTER_ID}: base64 decode to ${out} failed"
+
+  case "${out}" in /*) : ;; *) out="$(pwd)/${out}" ;; esac
+  jq -n --arg p "${out}" '{video_path: $p, audio_embedded: false}'
 }
 
 aiv_cmd_submit() { aiv_cmd_run "$@"; }