@sogni-ai/sogni-creative-agent-skill 3.3.5 → 3.4.0

package/README.md

@@ -70,14 +70,23 @@ With this skill, an agent can:
 ## Quick Start
 
 1. Get a Sogni API key from [dashboard.sogni.ai](https://dashboard.sogni.ai) (open the account menu) and save it — see [Setup](#setup-sogni-api-key).
-2. Install the CLI:
+2. Install (one command):
+
+   ```bash
+   npx setup-sogni-agent-skill
+   ```
+
+   This auto-detects Claude Code, Codex CLI, and Hermes; installs the CLI globally;
+   registers the skill into each detected runtime; and prompts for your API key.
+
+   Prefer to do it manually? Install the CLI directly:
 
    ```bash
    npm install -g @sogni-ai/sogni-creative-agent-skill@latest
    sogni-agent --version
    ```
 
-3. Point your agent runtime at this repository's [`SKILL.md`](./SKILL.md).
+   Then point your agent runtime at this repository's [`SKILL.md`](./SKILL.md).
 
 Then ask your agent to do something:
 
@@ -133,6 +142,8 @@ openclaw plugins install sogni-creative-agent-skill
 
 The installed plugin loads its behavior from [`SKILL.md`](./SKILL.md) via [`openclaw.plugin.json`](./openclaw.plugin.json).
 
+> **API key under OpenClaw:** the plugin config holds non-secret defaults only (models, timeouts, paths) — it does **not** carry your API key. Provide `SOGNI_API_KEY` via the environment the OpenClaw gateway passes to the CLI, or save it to `~/.config/sogni/credentials` (`SOGNI_API_KEY=<your-key>`). This keeps your key out of plugin config files.
+
 For a local checkout that you want to update continuously, link the minimal OpenClaw surface (`.openclaw-link/`) — not the repository root, which contains development tests that OpenClaw correctly blocks during plugin safety scanning:
 
 ```bash
@@ -451,7 +462,7 @@ LTX-2.3 prompt: "A medium cinematic shot frames a woman in her 30s standing in a
 
 ## Photobooth (Face Transfer)
 
-Generate stylized portraits from a face photo using InstantID ControlNet:
+Generate new stylized portraits from a face photo using InstantID ControlNet:
 
 ```bash
 sogni-agent --photobooth --ref face.jpg "80s fashion portrait"
@@ -460,6 +471,8 @@ sogni-agent --photobooth --ref face.jpg -n 4 "LinkedIn professional headshot"
 
 Uses SDXL Turbo (`coreml-sogniXLturbo_alpha1_ad`) at 1024×1024 by default. The face image is passed via `--ref` and styled by the prompt. Cannot be combined with `--video` or `-c` / `--context`.
 
+`--photobooth` is face-reference generation, not full-image editing. If the request is "same image, different style" — for example an anime version that must keep the same face, pose, clothing, background, framing, and composition — use Qwen image editing with `-c/--context` instead.
+
 Multi-angle mode (`--multi-angle` / `--angles-360`) auto-builds the `<sks>` prompt and applies the `multiple_angles` LoRA. `--angles-360-video` generates i2v clips between consecutive angles (including last → first) and concatenates them with `ffmpeg` into a seamless loop.
 
 `--balance` / `--balances` does not require a prompt and prints current `SPARK` and `SOGNI` balances before exiting.
@@ -577,7 +590,7 @@ Use `--token-type auto` to retry native Sogni models with SOGNI tokens when SPAR
 sogni-agent --token-type auto "a dragon eating tacos"
 ```
 
-Tries SPARK first (free daily tokens), then falls back to SOGNI if the balance is too low. Vendor models such as Seedance and GPT Image 2 require Premium Spark eligibility and never use SOGNI fallback.
+Tries SPARK first, then falls back to SOGNI if the balance is too low. Vendor models such as Seedance and GPT Image 2 require Premium Spark eligibility and never use SOGNI fallback. If usable balance is still insufficient, buy Spark Packs at https://docs.sogni.ai/pricing/#spark-packs.
 
 ---
 
@@ -632,6 +645,15 @@ Reusable workflow rules should come from the shared Sogni runtime before they ar
 
 Public-skill regex should stay limited to CLI argument/fact extraction such as file paths, URLs, extensions, dimensions, durations, and explicit positions. Hosted-style decisions such as latest-video continuation, uploaded-video modification, image-selection waits, stitch-after-batch state, and repair/control routing belong upstream in typed planner/runtime fields before they are synced here.
 
+### Execution boundaries: local CLI vs. hosted surfaces
+
+`sogni-agent.mjs` is a **local command-line tool** (`#!/usr/bin/env node`, the package `bin`). It is the only place that may assume a local filesystem and a local `ffmpeg`/`ffprobe` binary. Flags like `--concat-videos`, `--remix-audio`, `--extract-first-frame`, `--extract-last-frame`, and `--angles-360-video` shell out to ffmpeg behind `ensureFfmpegAvailable()` and run only when those flags are passed.
+
+Hosted surfaces — including the chat.sogni.ai web app — do **not** run `sogni-agent.mjs`. They consume `@sogni-ai/sogni-intelligence-client` and the hosted `/v1/chat/completions` and `/v1/creative-agent/workflows` APIs, where there is no local ffmpeg and no local filesystem. Therefore:
+
+- Keep ffmpeg- and filesystem-dependent helpers (frame extraction, concat, audio remux, media listing) **local to `sogni-agent.mjs`**. Do not move them into the shared runtime or `@sogni-ai/sogni-intelligence-client`, and never make hosted code paths depend on a local binary.
+- Server-side equivalents of these capabilities (e.g. `stitch_video`, `overlay_video`, `extend_video`) live in the hosted creative-agent tool surface and belong upstream, not in the CLI.
+
 Issues and feature requests: [github.com/Sogni-AI/sogni-creative-agent-skill/issues](https://github.com/Sogni-AI/sogni-creative-agent-skill/issues).
 
 ---

package/SKILL.md

@@ -2,7 +2,7 @@
 name: sogni-creative-agent-skill
 description: "Sogni Creative Agent Skill: agent skill and CLI for image, video, and music generation using Sogni AI's decentralized GPU network. Supports personas (named people with saved reference photos and voice clips), persistent memories, custom personality, style transfer, angle synthesis, Seedance/LTX/WAN video, music/lyrics, hosted chat, durable workflows, replay records, and multi-step creative workflows. Ask the agent to \"draw\", \"generate\", \"create an image\", \"make a video/animate\", \"make music\", \"apply a style\", or \"generate me as a superhero\"."
 metadata:
-  version: "3.3.5"
+  version: "3.4.0"
   homepage: https://sogni.ai
   clawdbot:
     emoji: "🎨"
@@ -72,6 +72,10 @@ npm --prefix "$DEST" install
 
 If that checkout does not exist, prefer the npm-based local skill install below, or ask before cloning.
 
+## Uninstall Request Policy
+
+When a user asks to uninstall, run `npx setup-sogni-agent-skill --uninstall --remove-cli --purge`. This removes the skill files, the global CLI, and the user's data in `~/.config/sogni/` after backing it up to `~/.config/sogni.backup-<timestamp>.tar.gz`. Always tell the user the backup path and that it contains their API key. To keep their data, omit `--purge`.
+
 ## Setup
 
 1. **Get your Sogni API key** by logging into https://dashboard.sogni.ai and opening the account menu.
@@ -463,9 +467,19 @@ positions.
 | `--strict-size` | Do not auto-adjust i2v video size for reference resizing constraints | false |
 | `-q, --quiet` | No progress output | false |
 | `--extract-last-frame <video> <image>` | Extract last frame from video (safe ffmpeg wrapper) | - |
-| `--concat-videos <out> <clips...>` | Concatenate video clips (safe ffmpeg wrapper) | - |
+| `--extract-first-frame <video> <image>` | Extract first frame from video (safe ffmpeg wrapper) | - |
+| `--concat-videos <out> <clips...>` | Concatenate video clips; normalizes fps/size and fills silent audio so mismatched clips stitch cleanly (safe ffmpeg wrapper) | - |
+| `--concat-fps <n>` | Override target fps for `--concat-videos` | highest clip fps |
 | `--concat-audio <path>` | Optional audio track to mux over `--concat-videos` output | - |
 | `--concat-audio-start <sec>` | Start offset into `--concat-audio` | - |
+| `--remix-audio <in> <out>` | Rebuild a video's audio (loop/fade/mix) without re-encoding video (safe ffmpeg wrapper) | - |
+| `--bed-audio <path>` | Audio bed for `--remix-audio` (path or video; defaults to input's own audio) | - |
+| `--audio-loop` | Loop the bed to cover the full video duration (`--remix-audio`) | false |
+| `--audio-fade-in <sec>` | Fade the bed in over `<sec>` (`--remix-audio`) | - |
+| `--audio-fade-out <sec>` | Fade the bed out over `<sec>` at the tail (`--remix-audio`) | - |
+| `--mix-audio <path>` | Overlay one extra audio track, mixed with the bed (`--remix-audio`) | - |
+| `--mix-at <sec>` | Start offset for `--mix-audio` | 0 |
+| `--mix-gain <db>` | Gain in dB applied to `--mix-audio` | 0 |
 | `--list-media [type]` | List recent inbound media (images\|audio\|all) | images |
 | `--api-chat` | Call OpenAI-compatible `/v1/chat/completions`; CLI default sends the hosted `creative-agent` tool surface | - |
 | `--durable-chat` | Start and stream a durable `/v1/chat/runs` record through SDK transport; requires `SOGNI_SKILL_USE_SDK_TRANSPORT=1` | - |
@@ -665,9 +679,17 @@ sogni-agent --last-image "make it more vibrant"
 
 When context images are provided without `-m`, defaults to `qwen_image_edit_2511_fp8_lightning`. Select `-m gpt-image-2` for GPT Image 2's higher reference-image limit and OpenAI-backed image editing.
 
+Use context-image editing for source-preserving edits. If the user says "use this image as the base", "keep everything the same", "only change the style", "anime version of this image", or asks to preserve pose, clothing, background, framing, or composition, use `-c/--context` with a Qwen image edit model instead of `--photobooth`. For stronger preservation than the lightning default, prefer:
+
+```bash
+sogni-agent -c photo.jpg -m qwen_image_edit_2511_fp8 "turn this into anime style; keep the same face, pose, clothing, background, framing, and composition"
+```
+
 ## Photobooth (Face Transfer)
 
-Generate stylized portraits from a face photo using InstantID ControlNet. When a user mentions "photobooth", wants a stylized portrait of themselves, or asks to transfer their face into a style, use `--photobooth` with `--ref` pointing to their face image.
+Generate new stylized portraits from a face photo using InstantID ControlNet. Use `--photobooth` with `--ref` when the user explicitly asks for photobooth/face-transfer mode, wants a new portrait or headshot based on their face, or asks to place their face identity into a different portrait concept.
+
+Do not use `--photobooth` for full-image style edits where the original photo must stay intact. `--photobooth` treats the input as a face reference, not as a base image, so it can change pose, clothing, background, framing, and composition. For "same image, different style" requests, route to Qwen context editing with `-c/--context`.
 
 ```bash
 # Basic photobooth
@@ -744,7 +766,7 @@ When a user requests a "360 video", follow this workflow:
 
 ### Transition Video Rule
 
-For **any transition video work**, always use the **Sogni skill/plugin** (not raw ffmpeg or other shell commands). Use the built-in `--extract-last-frame`, `--concat-videos`, and `--looping` flags for video manipulation.
+For **any transition video work**, always use the **Sogni skill/plugin** (not raw ffmpeg or other shell commands). Use the built-in `--extract-last-frame`, `--extract-first-frame`, `--concat-videos`, `--remix-audio`, and `--looping` flags for video and audio manipulation.
 
 ### Insufficient Funds Handling
 
@@ -752,7 +774,9 @@ Use `--token-type auto` to automatically retry native Sogni models with SOGNI to
 
 When you see **"Debit Error: Insufficient funds"** even with auto-fallback, reply:
 
-"Insufficient funds. Claim 50 free daily Spark points at https://app.sogni.ai/"
+"Insufficient funds. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
+
+Do not collect payment details, quote a custom price, or simulate a purchase in the terminal.
 
 ## Video Generation
 
@@ -877,10 +901,11 @@ sogni-agent --json --list-media images
 
 **Do NOT use `ls`, `cp`, or other shell commands to browse user files.** Always use `--list-media` to find inbound media.
 
-## IMPORTANT KEYWORD RULE
+## Photobooth Routing Rule
 
-- If the user message includes the word "photobooth" (case-insensitive), always use `--photobooth` mode with `--ref` set to the user-provided face image.
-- Prioritize this rule over generic image-edit flows (`-c`) for that request.
+- If the user explicitly asks to use "photobooth", "photobooth path", or "face transfer", use `--photobooth` with `--ref` set to the user-provided face image.
+- If the same request also requires preserving the whole source image (same pose, clothes, background, framing, composition, or "keep everything the same"), explain that photobooth is face-reference generation and prefer Qwen context editing unless the user insists on photobooth.
+- Do not route to `--photobooth` merely because the user asks to preserve a face in a style edit. Face-preserving full-image edits should use `-c/--context` with Qwen image edit.
 
 ## LTX-2.3 Prompt Rule
 
@@ -1017,7 +1042,7 @@ If clips need different source images, end frames, durations, audio windows, or
 
 ### Token Auto-Fallback
 
-Use `--token-type auto` when the user's SPARK balance might be low. It tries SPARK first (free daily tokens) and automatically retries with SOGNI if insufficient.
+Use `--token-type auto` when the user's SPARK balance might be low. It tries SPARK first and automatically retries with SOGNI if insufficient.
 
 ## High-Res Video Routing
 
@@ -1032,7 +1057,7 @@ When the user asks for video in **"hd"**, **"1080p"**, **"4k"**, **"uhd"**, or *
 - Rewrite the user's request using the **LTX-2.3 Prompt Rule** before invoking the command. Do not send short slogan-style prompts to LTX.
 - Treat "4k" as a signal to use the highest practical LTX path exposed by this skill, even though the current wrapper caps non-WAN video dimensions at 2048px on the long side.
 
-**Security:** Agents must use the CLI's built-in flags (`--extract-last-frame`, `--concat-videos`, `--list-media`) for all file operations and video manipulation. Never run raw shell commands (`ffmpeg`, `ls`, `cp`, etc.) directly.
+**Security:** Agents must use the CLI's built-in flags (`--extract-last-frame`, `--extract-first-frame`, `--concat-videos`, `--remix-audio`, `--list-media`) for all file operations and video/audio manipulation. Never run raw shell commands (`ffmpeg`, `ls`, `cp`, etc.) directly.
 
 ## Animate Between Two Images (First-Frame / Last-Frame)
 
@@ -1071,6 +1096,50 @@ When the final stitched output needs a single external soundtrack, add `--concat
 - User says "animate this video to this image" → extract last frame, use as `--ref`, target image as `--ref-end`, then stitch
 - User says "continue this video" with a target image → same as above
 
+### Transition Between Two Videos (Bridge Clip)
+
+When a user asks to **create a transition between two existing videos** (A → B), bridge them with a generated clip anchored on both boundary frames:
+
+1. **Extract the last frame of video A** and the **first frame of video B**:
+   ```bash
+   sogni-agent --extract-last-frame ./videoA.mp4 ./A_last.png
+   sogni-agent --extract-first-frame ./videoB.mp4 ./B_first.png
+   ```
+2. **Generate the transition** with i2v, anchoring start→end so both seams are clean. Match `--fps` to the surrounding clips:
+   ```bash
+   sogni-agent -q --video -m wan_v2.2-14b-fp8_i2v_lightx2v \
+     --ref ./A_last.png --ref-end ./B_first.png --fps 24 \
+     -o ./transition.mp4 "descriptive morph between the two scenes"
+   ```
+3. **Concatenate A → transition → B**:
+   ```bash
+   sogni-agent --concat-videos ./merged.mp4 ./videoA.mp4 ./transition.mp4 ./videoB.mp4
+   ```
+
+> **i2v clips are silent and use the model's own frame rate** (often not 24). `--concat-videos` now normalizes fps/size and fills silent audio automatically, so mismatched clips stitch correctly — but passing `--fps` to the transition generation keeps things clean from the start. Use `--concat-fps <n>` to force a specific output frame rate.
+
+### Remix / Layer Audio After Stitching
+
+After concatenating, use `--remix-audio` to rebuild the audio track **without re-encoding the video** (it is stream-copied, so it is fast and lossless on the picture). Combine the audio flags:
+
+```bash
+# Loop one clip's audio across the whole merged video and fade it out at the end
+sogni-agent --remix-audio ./merged.mp4 ./final.mp4 \
+  --bed-audio ./clip1.mp4 --audio-loop --audio-fade-out 2
+
+# Same, but also layer a second clip's original audio back in starting at 18s
+sogni-agent --remix-audio ./merged.mp4 ./final.mp4 \
+  --bed-audio ./clip1.mp4 --audio-loop --audio-fade-out 2 \
+  --mix-audio ./clip3.mp4 --mix-at 18.01 --mix-gain -3
+```
+
+- `--bed-audio` accepts a video or audio file; if omitted, the input video's own audio is the bed.
+- `--audio-loop` loops the bed to cover the full video; `--audio-fade-in` / `--audio-fade-out` fade it.
+- `--mix-audio` overlays one extra track (mixed at full level with a peak limiter so it never clips); position it with `--mix-at` and adjust level with `--mix-gain` (dB).
+- To mix more than two layers, chain `--remix-audio` passes (each only re-encodes audio).
+
+**Do NOT run raw `ffmpeg` commands** for any of this. Use `--extract-first-frame`, `--extract-last-frame`, `--concat-videos`, and `--remix-audio`.
+
 ## JSON Output
 
 ```json

package/generated/creative-agent-runtime.mjs

@@ -556,7 +556,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "edit_image.cost_limit_exceeded",
@@ -565,7 +565,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "restore_photo.cost_limit_exceeded",
@@ -574,7 +574,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "apply_style.cost_limit_exceeded",
@@ -583,7 +583,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "refine_result.cost_limit_exceeded",
@@ -592,7 +592,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "animate_photo.cost_limit_exceeded",
@@ -601,7 +601,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "change_angle.cost_limit_exceeded",
@@ -610,7 +610,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "generate_video.cost_limit_exceeded",
@@ -619,7 +619,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "sound_to_video.cost_limit_exceeded",
@@ -628,7 +628,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "video_to_video.cost_limit_exceeded",
@@ -637,7 +637,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "generate_music.cost_limit_exceeded",
@@ -646,7 +646,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "extend_video.cost_limit_exceeded",
@@ -655,7 +655,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "replace_video_segment.cost_limit_exceeded",
@@ -664,7 +664,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "overlay_video.cost_limit_exceeded",
@@ -673,7 +673,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "add_subtitles.cost_limit_exceeded",
@@ -682,7 +682,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "stitch_video.cost_limit_exceeded",
@@ -691,7 +691,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "orbit_video.cost_limit_exceeded",
@@ -700,7 +700,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "dance_montage.cost_limit_exceeded",
@@ -709,7 +709,7 @@ const REPAIR_RECIPES = [
         "errorCode": "COST_LIMIT_EXCEEDED",
         "mode": "stopAndAsk",
         "maxRetries": 0,
-        "repairNoteTemplate": "You have hit the credit limit for this turn. Top up credits or wait for the daily refill."
+        "repairNoteTemplate": "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs"
     },
     {
         "recipeId": "generate_image.asset_not_found",
@@ -2550,6 +2550,38 @@ const PROMPT_CONTRACTS = [
 // '../public-skill-runtime/index.js' (and downstream consumers that still
 // reference the creative-agent subpath) keep working unchanged.
 export * from '@sogni-ai/sogni-intelligence-client/public-skill-runtime';
+
+// PUBLIC_SKILL_SPARK_PACKS_COST_LIMIT_OVERRIDE
+import {
+  PUBLIC_SKILL_DEFAULT_POLICIES as SOGNI_PUBLIC_SKILL_DEFAULT_POLICIES,
+  PUBLIC_SKILL_DEFAULT_PROMPT_CONTRACTS as SOGNI_PUBLIC_SKILL_DEFAULT_PROMPT_CONTRACTS,
+  PUBLIC_SKILL_DEFAULT_REPAIR_RECIPES as SOGNI_PUBLIC_SKILL_DEFAULT_REPAIR_RECIPES,
+  createPublicSkillContractRuntime as createSogniPublicSkillContractRuntime,
+} from '@sogni-ai/sogni-intelligence-client/public-skill-runtime';
+
+export const PUBLIC_SKILL_DEFAULT_REPAIR_RECIPES = SOGNI_PUBLIC_SKILL_DEFAULT_REPAIR_RECIPES.map((recipe) =>
+  recipe.errorCode === 'COST_LIMIT_EXCEEDED'
+    ? { ...recipe, message: "You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs" }
+    : recipe
+);
+
+export function createPublicSkillDefaultContractRuntime(input = {}) {
+  return createSogniPublicSkillContractRuntime({
+    policies: [
+      ...SOGNI_PUBLIC_SKILL_DEFAULT_POLICIES,
+      ...(input.policies ?? []),
+    ],
+    promptContracts: [
+      ...SOGNI_PUBLIC_SKILL_DEFAULT_PROMPT_CONTRACTS,
+      ...(input.promptContracts ?? []),
+    ],
+    repairRecipes: [
+      ...PUBLIC_SKILL_DEFAULT_REPAIR_RECIPES,
+      ...(input.repairRecipes ?? []),
+    ],
+  });
+}
+
 // Moved to @sogni-ai/sogni-intelligence-client/skill-runtime-source in Phase 8.4 follow-up.
 // This file is kept as a thin re-export so existing internal `testing/`
 // callers keep working. New code should import from the public mid-tier:

package/node-version-check.mjs

@@ -0,0 +1,37 @@
+// Zero-dependency Node.js version guard.
+//
+// This module is imported FIRST by sogni-agent.mjs (before `sharp` and the
+// Sogni SDK). ES modules evaluate their dependencies in source order, so this
+// runs — and can exit cleanly — before any modern-syntax/native dependency is
+// loaded. That turns "wrong Node version" from a cryptic native/ESM stack
+// trace into a one-line, actionable message.
+//
+// Keep this file import-free and syntactically conservative so it parses and
+// runs on old Node versions too.
+
+var MIN_NODE_VERSION = [22, 11, 0];
+
+function isVersionAtLeast(current, required) {
+  for (var i = 0; i < required.length; i++) {
+    var currentValue = current[i] || 0;
+    var requiredValue = required[i] || 0;
+    if (currentValue > requiredValue) return true;
+    if (currentValue < requiredValue) return false;
+  }
+  return true;
+}
+
+try {
+  var raw = (process && process.versions && process.versions.node) || '0';
+  var current = String(raw).split('.').map(function (part) { return Number(part); });
+  if (!isVersionAtLeast(current, MIN_NODE_VERSION)) {
+    var required = MIN_NODE_VERSION.join('.');
+    process.stderr.write(
+      'Error: Sogni requires Node.js >= ' + required + ' (you have ' + raw + ').\n' +
+      'Hint: Upgrade Node — e.g. with nvm (`nvm install ' + MIN_NODE_VERSION[0] + '`), fnm, or volta — then re-run.\n'
+    );
+    process.exit(1);
+  }
+} catch (err) {
+  // Never let the guard itself crash the CLI; fall through to normal startup.
+}

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "sogni-creative-agent-skill",
   "name": "Sogni Creative Agent Skill — Image, Video & Music Generation",
   "description": "Agent skill and CLI for Sogni AI image, video, and music generation.",
-  "version": "3.3.5",
+  "version": "3.4.0",
   "skills": [
     "."
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sogni-ai/sogni-creative-agent-skill",
-  "version": "3.3.5",
+  "version": "3.4.0",
   "description": "Sogni Creative Agent Skill: agent skill and CLI for Sogni AI image, video, and music generation.",
   "type": "module",
   "main": "sogni-agent.mjs",
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "openclaw:sync": "node scripts/sync-openclaw-plugin.mjs",
-    "sync:creative-agent-runtime": "node ../sogni-creative-agent/scripts/sync-skill-runtime.mjs",
+    "sync:creative-agent-runtime": "node scripts/sync-creative-agent-runtime.mjs",
     "check:creative-agent-source": "node scripts/check-creative-agent-source.mjs",
     "check:creative-agent-source:strict": "node scripts/check-creative-agent-source.mjs --strict-network",
     "check:creative-agent-runtime": "node scripts/check-creative-agent-runtime.mjs",
@@ -56,6 +56,7 @@
     "skill-package.json",
     "scripts/check-creative-agent-runtime.mjs",
     "scripts/check-creative-agent-source.mjs",
+    "scripts/sync-creative-agent-runtime.mjs",
     "version.mjs",
     "scripts/sync-openclaw-plugin.mjs",
     "openclaw-plugin.mjs",
@@ -63,11 +64,12 @@
     "env.mjs",
     "ssrf-guard.mjs",
     "update-check.mjs",
+    "node-version-check.mjs",
     "generated/creative-agent-runtime.mjs",
     "sogni-agent.mjs"
   ],
   "dependencies": {
-    "@sogni-ai/sogni-intelligence-client": "^3.0.11",
+    "@sogni-ai/sogni-intelligence-client": "^3.0.13",
     "execa": "^9.6.1",
     "json5": "^2.2.3",
     "sharp": "^0.34.5"

package/scripts/check-creative-agent-runtime.mjs

@@ -4,9 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 
 const repoRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-const syncScript = process.env.SOGNI_CREATIVE_AGENT_SYNC_SCRIPT
-  ? process.env.SOGNI_CREATIVE_AGENT_SYNC_SCRIPT
-  : join(repoRoot, '..', 'sogni-creative-agent', 'scripts', 'sync-skill-runtime.mjs');
+const syncScript = join(repoRoot, 'scripts', 'sync-creative-agent-runtime.mjs');
 const generatedPath = join(repoRoot, 'generated', 'creative-agent-runtime.mjs');
 const generatedRelativePath = 'generated/creative-agent-runtime.mjs';
 

package/scripts/sync-creative-agent-runtime.mjs

@@ -0,0 +1,98 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const repoRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const upstreamSyncScript = process.env.SOGNI_CREATIVE_AGENT_SYNC_SCRIPT
+  ? process.env.SOGNI_CREATIVE_AGENT_SYNC_SCRIPT
+  : join(repoRoot, '..', 'sogni-creative-agent', 'scripts', 'sync-skill-runtime.mjs');
+const generatedPath = join(repoRoot, 'generated', 'creative-agent-runtime.mjs');
+
+const STALE_COST_LIMIT_REPAIR_NOTE =
+  'You have hit the credit limit for this turn. Top up credits or wait for the daily refill.';
+const SPARK_PACKS_COST_LIMIT_REPAIR_NOTE =
+  'You have hit the credit limit for this turn. Buy Spark Packs to continue: https://docs.sogni.ai/pricing/#spark-packs';
+const PUBLIC_RUNTIME_REEXPORT = "export * from '@sogni-ai/sogni-intelligence-client/public-skill-runtime';";
+const PUBLIC_RUNTIME_OVERRIDE_MARKER = 'PUBLIC_SKILL_SPARK_PACKS_COST_LIMIT_OVERRIDE';
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    ...options,
+  });
+  if (result.error) throw result.error;
+  return result;
+}
+
+function applyPublicRuntimeOverrides(source) {
+  let updated = source.replaceAll(STALE_COST_LIMIT_REPAIR_NOTE, SPARK_PACKS_COST_LIMIT_REPAIR_NOTE);
+  if (updated.includes(PUBLIC_RUNTIME_REEXPORT) && !updated.includes(PUBLIC_RUNTIME_OVERRIDE_MARKER)) {
+    const costLimitMessage = JSON.stringify(SPARK_PACKS_COST_LIMIT_REPAIR_NOTE);
+    const overrideBlock = `
+// ${PUBLIC_RUNTIME_OVERRIDE_MARKER}
+import {
+  PUBLIC_SKILL_DEFAULT_POLICIES as SOGNI_PUBLIC_SKILL_DEFAULT_POLICIES,
+  PUBLIC_SKILL_DEFAULT_PROMPT_CONTRACTS as SOGNI_PUBLIC_SKILL_DEFAULT_PROMPT_CONTRACTS,
+  PUBLIC_SKILL_DEFAULT_REPAIR_RECIPES as SOGNI_PUBLIC_SKILL_DEFAULT_REPAIR_RECIPES,
+  createPublicSkillContractRuntime as createSogniPublicSkillContractRuntime,
+} from '@sogni-ai/sogni-intelligence-client/public-skill-runtime';
+
+export const PUBLIC_SKILL_DEFAULT_REPAIR_RECIPES = SOGNI_PUBLIC_SKILL_DEFAULT_REPAIR_RECIPES.map((recipe) =>
+  recipe.errorCode === 'COST_LIMIT_EXCEEDED'
+    ? { ...recipe, message: ${costLimitMessage} }
+    : recipe
+);
+
+export function createPublicSkillDefaultContractRuntime(input = {}) {
+  return createSogniPublicSkillContractRuntime({
+    policies: [
+      ...SOGNI_PUBLIC_SKILL_DEFAULT_POLICIES,
+      ...(input.policies ?? []),
+    ],
+    promptContracts: [
+      ...SOGNI_PUBLIC_SKILL_DEFAULT_PROMPT_CONTRACTS,
+      ...(input.promptContracts ?? []),
+    ],
+    repairRecipes: [
+      ...PUBLIC_SKILL_DEFAULT_REPAIR_RECIPES,
+      ...(input.repairRecipes ?? []),
+    ],
+  });
+}
+`;
+    updated = updated.replace(PUBLIC_RUNTIME_REEXPORT, `${PUBLIC_RUNTIME_REEXPORT}\n${overrideBlock}`);
+  }
+  return updated;
+}
+
+if (!existsSync(upstreamSyncScript)) {
+  console.error(`Missing Sogni Creative Agent runtime sync script: ${upstreamSyncScript}`);
+  console.error('Set SOGNI_CREATIVE_AGENT_SYNC_SCRIPT or check out sogni-creative-agent as a sibling repo.');
+  process.exit(1);
+}
+
+const syncResult = run(process.execPath, [upstreamSyncScript], {
+  env: {
+    ...process.env,
+    SOGNI_CREATIVE_AGENT_SKILL_DIR: repoRoot,
+  },
+  stdio: 'inherit',
+});
+if (syncResult.status !== 0) {
+  process.exit(syncResult.status || 1);
+}
+
+if (!existsSync(generatedPath)) {
+  console.error('Runtime sync completed but generated/creative-agent-runtime.mjs was not created.');
+  process.exit(1);
+}
+
+const generated = readFileSync(generatedPath, 'utf8');
+const updated = applyPublicRuntimeOverrides(generated);
+if (updated !== generated) {
+  mkdirSync(dirname(generatedPath), { recursive: true });
+  writeFileSync(generatedPath, updated);
+  console.log(`Applied public skill runtime overrides to ${generatedPath}`);
+}

package/skill-package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@sogni-ai/sogni-intelligence-client": "^3.0.11",
+    "@sogni-ai/sogni-intelligence-client": "^3.0.13",
     "execa": "^9.6.1",
     "json5": "^2.2.3",
     "sharp": "^0.34.5"