@optima-chat/optima-agent 0.8.91 → 0.8.93

package/.claude/skills/video-clone/references/gate-enforcement.md

@@ -0,0 +1,144 @@
+# Gate Enforcement
+
+This skill enforces its HARD-GATE mechanically, not textually. Every
+executor script that costs money or generates output calls `require_gate()`
+at startup and exits with code 1 if the gate isn't set. You cannot
+rationalize past a CLI that won't produce output.
+
+## State location
+
+Each project has its own state file:
+
+```
+gen-output/video-clone/<project>/.state/phase.json
+```
+
+## Schema (single-gate model — PR #65)
+
+```json
+{
+  "schema_version": 1,
+  "project": "handheld-phone-swap",
+  "task_type": "video_clone",
+  "created_at": "2026-04-11T16:55:00Z",
+  "current_phase": 0,
+  "gates": {
+    "preview_confirmed": {"status": false, "confirmed_at": null, "user_quote": null}
+  },
+  "history": []
+}
+```
+
+There is **one gate**: `preview_confirmed`. It is set by `confirm.py`
+after the user reviews the complete prep preview (analysis + grid +
+prompt + edited frame). The prep scripts (analyze_source, extract_frames,
+edit_first_frame) run freely before confirmation — only the generation
+scripts are gated.
+
+Gates are never un-set. Each set operation appends an entry to `history`
+with timestamp + user quote + caller script name, giving you an audit
+trail to answer "did the user actually confirm this?"
+
+## Which script needs which gate
+
+| Script | Required gate |
+|---|---|
+| `analyze_source.py` | (none — prep runs freely) |
+| `extract_frames.py` | (none — prep runs freely) |
+| `edit_first_frame.py` | (none — prep runs freely) |
+| `preview.py` | (none — collects artifacts, no cost) |
+| `kling_generate.py` | **preview_confirmed** |
+| `gen_video.py` | **preview_confirmed** |
+| `save_workflow.py` | **preview_confirmed** |
+| `assemble.py` | (none — post-processes already-generated videos) |
+| `init_project.py` | (none — must run before any gate exists) |
+| `confirm.py` | (none — sets the gate) |
+| `preflight.py` | (none — environment check) |
+| `status.py` | (none — read-only) |
+
+## How to set the gate
+
+```bash
+python scripts/confirm.py --project <name> --quote "<user's actual words>"
+```
+
+- **`--quote` is required** and must be non-empty.
+- **Quote heuristic**: if the quote contains negation markers (`不`, `改`,
+  `no`, `not`, `change`, `modify`, `wrong`, …), the script refuses to set
+  the gate unless you also pass `--force`. This prevents Claude from
+  using a correction ("不需要音频") as a confirmation.
+- **Use `--force` sparingly**: only when the user said something like
+  "no audio, otherwise good" — a genuine confirmation that contains a
+  negation word.
+- The gate records `caller` (the script name) in history. Fabricated
+  quotes are detectable in post-mortem review.
+
+## How a blocked script looks
+
+```
+[HARD-GATE BLOCKED] kling_generate.py needs preview_confirmed=True
+Current state: preview_confirmed=False
+Project: /abs/path/to/gen-output/video-clone/handheld-phone-swap
+
+To proceed:
+  1. Show the preview bundle to the user and wait for their confirmation.
+  2. Run: python scripts/confirm.py --project <name> --quote "<user's actual words>"
+  3. Retry this command.
+
+Claude: do NOT rationalize past this. The gate exists because text
+instructions alone did not stop prior bypass attempts. Go get the real
+user confirmation.
+```
+
+Exit code is always 1. Downstream pipes will break; you can't accidentally
+feed "locked" output into the next step.
+
+## Old 3-gate schema (pre-PR #65)
+
+If you have a project created before the single-gate refactor, the state
+file will have `plan_confirmed`, `prompt_confirmed`, `frame_confirmed`
+instead of `preview_confirmed`. Any gated script will exit 1 with:
+
+```
+[HARD-GATE BLOCKED] expected gate 'preview_confirmed' but it is not
+present. This is most likely an old 3-gate schema project.
+Either: complete this project with PR #65 scripts, or start a new project.
+```
+
+Do NOT manually edit old phase.json files to add `preview_confirmed`.
+Start a new project with `init_project.py` and re-run prep.
+
+## Common bypass attempts (and why the gate still wins)
+
+| Attempt | Outcome |
+|---|---|
+| "analyze_source is just analysis, no cost" | Runs freely — no gate on prep scripts. Correct behavior. |
+| "I'll edit phase.json to set the gate" | Possible, but leaves a gap in `history`. Audit trail shows no `confirm.py` call. |
+| `confirm.py --quote 'ok'` without asking user | Sets gate with `user_quote: "ok"`. No user types that in isolation — obvious in post-mortem. |
+| "I'll skip preview.py and confirm directly" | `confirm.py` doesn't require preview_v*.md — but `preview.py` must have run first for artifacts to be present for the user to review. |
+| "I'll symlink phase.json to /dev/null" | Exit 1 on read. |
+| "I'll delete .state/" | Exit 1 — "phase.json not found". |
+
+The cheapest path is always to actually get the user's confirmation.
+
+## When to read history
+
+The `history` array is append-only. Useful cases:
+
+- **Resuming a multi-session project** — read history to know what gate
+  is set and what the user said. Use `status.py` for a human-readable view.
+- **Debugging bad output** — if a video is wrong, history shows the exact
+  quote the user gave when confirming the preview.
+- **Verifying gate authenticity** — `caller` field shows which script set
+  the gate. `confirm.py` is the only legitimate caller.
+
+## Why this exists
+
+Previous versions had HARD-GATE rules in SKILL.md text with a
+Rationalization Counter table. They did not stop Claude from running
+ffprobe / downloading videos / calling `gen image` before the user
+confirmed. The failure mode was always the same: Claude decided "my action
+doesn't count as execution" and rationalized past the text rule.
+
+Mechanical gates end the argument. The script either runs or it doesn't,
+and the decision doesn't depend on how Claude interprets the rules.

package/.claude/skills/video-clone/references/kling-api.md

@@ -1,85 +1,85 @@
-# Kling 3.0 API 实现（PiAPI）
+# Video generation with audio — what the script handles + what you need to know
 
-需要音频/口型同步时使用 Kling 3.0，否则用 gen video。
+The `kling_generate.py` script calls the **Optima generation backend**, which
+routes to Kling 3.0 internally. The script itself knows nothing about the
+upstream provider — only the backend does.
 
-## Step 1: 上传首帧获取公开 URL
+```bash
+python scripts/kling_generate.py --project <name> --frame <confirmed-frame.png>
+# options: --duration 5|10  --aspect-ratio 9:16  --mode std|pro
+#          --cfg-scale 0.5  --no-audio
+```
 
-Kling 不接受 base64，需要公开 URL。**用 freeimage.host，不要用 catbox.moe**（PiAPI 服务器访问不了）。
+## When to use `kling_generate.py` vs `gen_video.py`
 
-```python
-import requests, base64
+| Need audio / lip sync? | Use |
+|---|---|
+| Yes | `kling_generate.py` ($0.15/s ≈ $1.50 per 10s equivalent) |
+| No | `gen_video.py` (~$0.02 per 10s equivalent) |
 
-frame_path = 'gen-output/video-clone/{project}/frames/frame_v1_s42.png'
-img_b64 = base64.b64encode(open(frame_path, 'rb').read()).decode()
-resp = requests.post('https://freeimage.host/api/1/upload', data={
-    'key': '6d207e02198a847aa98d0a2a901485a5',
-    'action': 'upload',
-    'source': img_b64,
-    'format': 'json',
-})
-img_url = resp.json()['image']['url']
-```
+Both scripts go through the same generation backend and the same billing
+middleware — the difference is server-side provider selection.
 
-## Step 2: 提交生成任务
-
-```python
-resp = requests.post('https://api.piapi.ai/api/v1/task',
-    headers={'x-api-key': PIAPI_KEY, 'Content-Type': 'application/json'},
-    json={
-        'model': 'kling',
-        'task_type': 'video_generation',
-        'input': {
-            'prompt': open('gen-output/video-clone/{project}/prompt.md').read(),
-            'negative_prompt': 'slow motion, dreamy, ethereal, cinematic, blurry, '
-                               'distorted, deformed hands, extra fingers',
-            'image_url': img_url,
-            'duration': 10,         # 多片段时用 5
-            'aspect_ratio': '9:16',
-            'mode': 'std',          # 720p
-            'version': '3.0',
-            'cfg_scale': 0.5,       # 必须 float！string → 500
-            'enable_audio': True,
-        },
-        'config': {'service_mode': 'public'},
-    }, timeout=60)
-task_id = resp.json()['data']['task_id']
-```
+## Auth + API URL discovery
 
-## Step 3: 轮询等待
-
-```python
-import time
-while True:
-    r = requests.get(f'https://api.piapi.ai/api/v1/task/{task_id}',
-        headers={'x-api-key': PIAPI_KEY})
-    d = r.json().get('data', {})
-    status = d.get('status', '')
-    if status == 'completed':       # 小写！
-        video_url = d['output']['video']  # 3.0 用 video，2.6 用 video_url
-        break
-    if status == 'failed':
-        raise RuntimeError(d.get('error', {}))
-    time.sleep(15)
-```
+`kling_generate.py` mirrors the `@optima-chat/gen-cli` auth convention, so
+any user who has run `optima login` is automatically ready — no extra env
+setup needed.
 
-## Step 4: 下载视频（CDN 不稳定需重试）
-
-```python
-output_path = 'gen-output/video-clone/{project}/videos/video_v1_10s.mp4'
-for attempt in range(3):
-    try:
-        data = requests.get(video_url, timeout=300).content
-        open(output_path, 'wb').write(data)
-        break
-    except Exception:
-        time.sleep(5)
-```
+Token resolution (first match wins):
+
+1. `OPTIMA_TOKEN` env var
+2. `~/.optima/token.json` (`access_token` field)
+
+Generation API URL resolution (first match wins):
+
+1. `GENERATION_API_URL` env var
+2. `~/.optima/token.json` `env` field → `ci` / `stage` / `prod` mapping
+3. default: `https://gen-api.optima.onl` (prod)
+
+If neither token source resolves, the script exits 1 with a clear hint
+(`Run `optima login` or set OPTIMA_TOKEN`). **No fallback to direct upstream
+calls** — that would bypass billing.
+
+Run `scripts/preflight.py` to verify the auth state and other deps.
+
+The `requests` Python package is also required.
+
+## Billing
+
+Billing is entirely server-side. When `kling_generate.py` calls
+`POST /api/video/generate`, the backend's billing middleware pre-deducts
+credits from the user's Optima wallet based on `metadata.duration`. If the
+upstream task later fails, the server refunds the credits automatically
+(see `billingClient.refund()` in the generation service worker).
+
+This means the skill never sees raw USD pricing — it just sends a request
+and waits. The user's wallet is the source of truth for how much was spent.
+
+## Error handling
+
+`_submit()` translates the common billing errors into readable messages:
+
+- HTTP 402 `INSUFFICIENT_CREDITS` — user does not have enough credits
+- HTTP 403 `PLAN_RESTRICTED` — user's plan does not include video generation
+
+Other HTTP errors propagate via `raise_for_status()`. Polling uses the
+backend's unified `GET /api/task/{id}` endpoint.
+
+## Non-obvious traps (now handled server-side)
+
+The `cfg_scale`-must-be-float / lowercase-status / 3.0-vs-2.6 response
+differences / freeimage-vs-catbox quirks are all handled by the server's
+PiAPI adapter (`optima-gen: packages/generation/src/adapters/piapi-video.ts`).
+The skill no longer has to know about them.
+
+## What changed vs the old direct-PiAPI version
 
-## 关键陷阱
+Before: script uploaded to freeimage.host, submitted to PiAPI, polled PiAPI,
+downloaded from Kling CDN. No billing. Shared PiAPI key hardcoded in the
+skill.
 
-- `cfg_scale` 必须 float，传 string 会变 500
-- `enable_audio` 只有 3.0 支持
-- 状态是小写 `"completed"`
-- 输出字段：3.0 用 `output.video`，2.6 用 `output.video_url`
-- freeimage.host key: `6d207e02198a847aa98d0a2a901485a5`
-- 国内网络通过服务器中转 API，本地大 payload 会断连
+After: script sends one POST + polls one endpoint on the Optima backend.
+Billing is automatic. No upstream API keys in the skill. Provider switches
+(if the Kling API ever changes) happen server-side without touching any
+client code.

package/.claude/skills/video-clone/references/url-parsing.md

@@ -1,13 +1,32 @@
-# URL 解析规则
-
-**不要用 WebFetch**（反爬/登录墙），按平台处理：
-
-| URL 特征 | 处理 |
-|----------|------|
-| TikTok `tiktok.com/@xxx/video/数字` | `scout tiktok video-detail <id>` → wget |
-| TikTok 短链 `vm.tiktok.com/xxx` | `curl -sI` → Location → 提取 id |
-| 抖音 `douyin.com/video/数字` | `scout douyin video-download <id>` → wget |
-| 抖音短链 `v.douyin.com/xxx` | `scout douyin video-by-url "<url>"` |
-| Instagram Reels | `scout instagram download-reel "<url>"` |
-| 小红书视频 | `scout xhs note-detail <id>` → 视频链接 |
-| 本地文件 | 直接使用 |
+# URL / Source Download — decision table
+
+**Do not use WebFetch** for source videos (anti-scraping, auth walls).
+Choose the right tool based on the URL shape and use it manually — there
+is no script wrapper because the right approach varies by platform.
+
+| URL shape | Command |
+|---|---|
+| `tiktok.com/@user/video/<id>` | `scout tiktok video-detail <id>` → grab video URL → `wget` |
+| `vm.tiktok.com/<short>` | `curl -sI <url>` → `Location:` header → extract id → see TikTok row |
+| `douyin.com/video/<id>` | `scout douyin video-download <id>` → `wget` |
+| `v.douyin.com/<short>` | `scout douyin video-by-url "<url>"` |
+| Instagram Reels (`instagram.com/reel/...`) | `scout instagram download-reel "<url>"` |
+| 小红书视频 (`xiaohongshu.com/explore/<id>`) | `scout xhs note-detail <id>` → grab video link → `wget` |
+| Local file path | Pass directly to `--video` |
+
+After download, save to `gen-output/video-clone/<project>/source/` and
+then feed the local path to `analyze_source.py --video <path>`.
+
+## Why the script pipeline starts after download
+
+Downloading is the *only* step that remains manual because platform APIs
+change faster than the script would. Everything downstream of
+`--video <local-file>` is automated by the Python scripts.
+
+## Sanity checks before running analyze_source.py
+
+1. File size > 0
+2. `ffprobe -v error <file>` returns no errors
+3. Duration makes sense for the source (`ffprobe -show_entries format=duration`)
+
+If any of these fail, re-download with a different tool before proceeding.

package/.claude/skills/video-clone/scripts/_confirm.py

@@ -0,0 +1,96 @@
+"""Shared implementation for confirm.py.
+
+run_confirm() handles:
+    - argparse with --project / --quote / --force
+    - quote validation (non-empty)
+    - negation heuristic (refuses quotes that sound like corrections unless --force)
+    - resolving the project directory via GEN_OUTPUT_ROOT
+    - automatically passing caller=Path(sys.argv[0]).name to _gate.set_gate()
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+import _gate
+
+NEGATION_MARKERS = (
+    "不", "别", "改", "调整", "不行", "不对", "再", "换",
+    "no", "not", "don't", "dont", "modify", "change", "different", "wrong",
+)
+
+GATE_NAME = "preview_confirmed"
+
+
+def _gen_output_root() -> Path:
+    override = os.environ.get("GEN_OUTPUT_ROOT")
+    if override:
+        return Path(override)
+    return Path.cwd() / "gen-output"
+
+
+def _looks_like_negation(quote: str) -> bool:
+    low = quote.lower()
+    return any(m in low for m in NEGATION_MARKERS)
+
+
+def run_confirm() -> int:
+    ap = argparse.ArgumentParser(
+        description=f"Record user confirmation for {GATE_NAME}."
+    )
+    ap.add_argument("--project", required=True, help="Project name under video-clone/")
+    ap.add_argument(
+        "--quote", required=True,
+        help="The user's actual confirmation words (verbatim). Required.",
+    )
+    ap.add_argument(
+        "--force", action="store_true",
+        help="Required if the quote contains negation markers "
+             "(used when user said something like 'no audio, rest is fine').",
+    )
+    args = ap.parse_args()
+
+    quote = args.quote.strip()
+    if not quote:
+        print(
+            "ERROR: --quote is empty. You must pass the user's actual "
+            "confirmation words.",
+            file=sys.stderr,
+        )
+        return 1
+
+    if _looks_like_negation(quote) and not args.force:
+        print(
+            f"ERROR: quote looks like a correction / negation: {quote!r}\n"
+            f"If the user really confirmed (e.g. 'no audio, rest is fine'), "
+            f"re-run with --force. Otherwise, go back and get a cleaner "
+            f"confirmation from the user.",
+            file=sys.stderr,
+        )
+        return 1
+
+    project_dir = _gen_output_root() / "video-clone" / args.project
+    if not project_dir.is_dir():
+        print(
+            f"ERROR: project directory not found at {project_dir}\n"
+            f"Run init_project.py first.",
+            file=sys.stderr,
+        )
+        return 1
+
+    # IMPORTANT: caller is sys.argv[0] (the entry script), not __file__.
+    # We want the audit to record "confirm.py", not "_confirm.py".
+    caller = Path(sys.argv[0]).name if sys.argv and sys.argv[0] else "<unknown>"
+
+    try:
+        _gate.set_gate(project_dir, GATE_NAME, quote, caller=caller)
+    except (ValueError, FileNotFoundError, KeyError) as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        return 1
+
+    print(f"OK: {GATE_NAME} recorded for project {args.project}")
+    print(f"    quote:  {quote}")
+    print(f"    caller: {caller}")
+    return 0

package/.claude/skills/video-clone/scripts/_confirm_test.py

@@ -0,0 +1,125 @@
+"""Unit tests for _confirm.run_confirm() — caller injection + quote validation."""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+from unittest.mock import patch
+
+SCRIPTS_DIR = Path(__file__).parent
+sys.path.insert(0, str(SCRIPTS_DIR))
+
+import _confirm  # noqa: E402
+import _gate  # noqa: E402
+
+TEMPLATE = json.loads(
+    (SCRIPTS_DIR.parent / "assets" / "phase-state-template.json").read_text(encoding="utf-8")
+)
+
+
+def _make_project(root: Path, name: str = "p1") -> Path:
+    proj = root / "video-clone" / name
+    (proj / ".state").mkdir(parents=True)
+    state = json.loads(json.dumps(TEMPLATE))
+    state["project"] = name
+    state["task_type"] = "video_clone"
+    (proj / ".state" / "phase.json").write_text(json.dumps(state), encoding="utf-8")
+    return proj
+
+
+def _run_with_argv(argv, env=None):
+    old_argv = sys.argv
+    old_env = dict(os.environ)
+    try:
+        sys.argv = argv
+        if env:
+            os.environ.update(env)
+        return _confirm.run_confirm()
+    finally:
+        sys.argv = old_argv
+        os.environ.clear()
+        os.environ.update(old_env)
+
+
+def test_run_confirm_injects_caller_from_argv0():
+    with tempfile.TemporaryDirectory() as td:
+        _make_project(Path(td))
+        rc = _run_with_argv(
+            ["confirm.py", "--project", "p1", "--quote", "OK 开始"],
+            env={"GEN_OUTPUT_ROOT": td},
+        )
+        assert rc == 0
+        state = _gate.load_state(Path(td) / "video-clone" / "p1")
+        history = state["history"]
+        assert history[-1]["caller"] == "confirm.py"
+        assert history[-1]["user_quote"] == "OK 开始"
+    print("PASS test_run_confirm_injects_caller_from_argv0")
+
+
+def test_run_confirm_empty_quote_returns_one():
+    with tempfile.TemporaryDirectory() as td:
+        _make_project(Path(td))
+        rc = _run_with_argv(
+            ["confirm.py", "--project", "p1", "--quote", "   "],
+            env={"GEN_OUTPUT_ROOT": td},
+        )
+        assert rc == 1
+    print("PASS test_run_confirm_empty_quote_returns_one")
+
+
+def test_run_confirm_negation_without_force_returns_one():
+    with tempfile.TemporaryDirectory() as td:
+        _make_project(Path(td))
+        rc = _run_with_argv(
+            ["confirm.py", "--project", "p1", "--quote", "不要这样改"],
+            env={"GEN_OUTPUT_ROOT": td},
+        )
+        assert rc == 1
+    print("PASS test_run_confirm_negation_without_force_returns_one")
+
+
+def test_run_confirm_negation_with_force_returns_zero():
+    with tempfile.TemporaryDirectory() as td:
+        _make_project(Path(td))
+        rc = _run_with_argv(
+            ["confirm.py", "--project", "p1", "--quote", "no audio, rest is fine", "--force"],
+            env={"GEN_OUTPUT_ROOT": td},
+        )
+        assert rc == 0
+    print("PASS test_run_confirm_negation_with_force_returns_zero")
+
+
+def test_run_confirm_missing_project_returns_one():
+    with tempfile.TemporaryDirectory() as td:
+        rc = _run_with_argv(
+            ["confirm.py", "--project", "does-not-exist", "--quote", "ok"],
+            env={"GEN_OUTPUT_ROOT": td},
+        )
+        assert rc == 1
+    print("PASS test_run_confirm_missing_project_returns_one")
+
+
+def test_run_confirm_success_writes_history_with_caller():
+    with tempfile.TemporaryDirectory() as td:
+        _make_project(Path(td), "p2")
+        rc = _run_with_argv(
+            ["confirm.py", "--project", "p2", "--quote", "好的，开始"],
+            env={"GEN_OUTPUT_ROOT": td},
+        )
+        assert rc == 0
+        state = _gate.load_state(Path(td) / "video-clone" / "p2")
+        assert state["gates"]["preview_confirmed"]["status"] is True
+        assert state["history"][-1]["caller"] == "confirm.py"
+    print("PASS test_run_confirm_success_writes_history_with_caller")
+
+
+if __name__ == "__main__":
+    test_run_confirm_injects_caller_from_argv0()
+    test_run_confirm_empty_quote_returns_one()
+    test_run_confirm_negation_without_force_returns_one()
+    test_run_confirm_negation_with_force_returns_zero()
+    test_run_confirm_missing_project_returns_one()
+    test_run_confirm_success_writes_history_with_caller()
+    print("All 6 _confirm tests passed.")