@sogni-ai/sogni-creative-agent-skill 3.5.0 → 3.6.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.6.0] - 2026-06-12
+
+### Added
+
+- **Agents now surface update notices (gstack-style).** Update notices were previously suppressed exactly where
+  agents live — non-TTY stderr, `--json` mode, and OpenClaw plugin invocations — so Claude Code / Codex / Hermes /
+  OpenClaw users never learned a newer skill existed. Any command may now print a single advisory stderr line,
+  `[sogni-agent] Update available: <current> -> <latest> ...`, throttled to at most once per 24 hours, telling
+  the agent to finish the current task, relay the update to the user, and offer `sogni-agent self-update`
+  (`--snooze-update` on decline). Interactive TTY users keep the existing banner. stdout is never touched, so
+  `--json` output stays machine-parseable; SKILL.md instructs agents how to handle the line. Background version
+  checks now also run in agent contexts (still skipped for CI, tests, `--no-update-check`,
+  `SOGNI_NO_UPDATE_CHECK`, and dev checkouts).
+
+## [3.5.1] - 2026-06-12
+
+### Fixed
+
+- **OpenClaw no longer marks the skill "missing".** The SKILL.md frontmatter listed every optional override
+  variable (`SOGNI_CREDENTIALS_PATH`, `OPENCLAW_CONFIG_PATH`, `FFMPEG_PATH`, …) and optional config path
+  (including `~/Downloads/sogni`) under `metadata.openclaw.requires`, so OpenClaw treated them all as hard
+  requirements that could never be satisfied and flagged the skill `✗ missing` on every install. Requirements
+  are now just `bins: node` + `anyBins: ffmpeg`; the API key still comes from the credentials file or
+  `primaryEnv`, and the override variables remain documented in "Filesystem Paths and Overrides". Verified
+  live: `openclaw skills check` flips from missing to `✓ ready`.
+
 ## [3.5.0] - 2026-06-11
 
 ### Added

package/README.md

@@ -170,7 +170,13 @@ Then `/reset` your Hermes session so it picks up the new skill. (You can also in
 
 ### OpenClaw plugin
 
-The npm package is scoped, so install it through OpenClaw's `npm:` source prefix (a bare `openclaw plugins install sogni-creative-agent-skill` will not resolve the scoped package):
+The skill is published on ClawHub, so the simplest install is:
+
+```bash
+openclaw skills install sogni-creative-agent-skill
+```
+
+To install as a code plugin instead, use OpenClaw's `npm:` source prefix (the npm package is scoped, so a bare `openclaw plugins install sogni-creative-agent-skill` will not resolve it):
 
 ```bash
 openclaw plugins install npm:@sogni-ai/sogni-creative-agent-skill
@@ -677,8 +683,10 @@ This skill is designed to be loaded into agent runtimes as a first-class capabil
 5. **Agent-safe install/upgrade**
    Prefer the `npm install -g` and `git -C "$DEST" pull --ff-only` paths above. Avoid generating clone-or-pull bootstrap scripts with `set -e`, `bash -c`, `sh -c`, or inline repository URLs — agent sandboxes correctly route those through approval and the install will stall.
 6. **Verify with `doctor`**
-   After any install or upgrade, run `sogni-agent doctor --json` and confirm `"success": true` before reporting the install as working. Each failed check carries a `detail` string with the fix.
-7. **SSRF / URL safety**
+   After any install or upgrade, run `sogni-agent doctor --json` and confirm `"success": true` before reporting the install as working.
+7. **Update notices for agents**
+   When a newer version exists, any command may print one advisory stderr line — `[sogni-agent] Update available: <current> -> <latest> ...` — at most once per day (stdout JSON is never touched). Agents should relay it to the user and offer `sogni-agent self-update`, or run `sogni-agent --snooze-update` if the user declines. Interactive TTY users get a banner instead. Each failed check carries a `detail` string with the fix.
+8. **SSRF / URL safety**
    The CLI validates every HTTP(S) media reference with an SSRF guard ([`ssrf-guard.mjs`](./ssrf-guard.mjs)) and re-validates each redirect hop on download. Localhost and private-network URLs are rejected; only public HTTPS references are forwarded as Seedance multimodal context.
 
 ---

package/SKILL.md

@@ -2,29 +2,20 @@
 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.5.0"
+  version: "3.6.0"
   homepage: https://sogni.ai
   openclaw:
     emoji: "🎨"
     primaryEnv: "SOGNI_API_KEY"
     os: ["darwin", "linux", "win32"]
+    # Only hard requirements belong here: OpenClaw marks the skill "missing"
+    # until every entry is satisfied. The API key comes from the credentials
+    # file (primaryEnv is the env-var alternative), and the SOGNI_*/OPENCLAW_*
+    # override variables are optional — they are documented in the body under
+    # "Filesystem Paths and Overrides", not required for the skill to work.
     requires:
       bins: ["node"]
       anyBins: ["ffmpeg"]
-      env:
-        - "SOGNI_API_KEY"
-        - "SOGNI_CREDENTIALS_PATH"
-        - "SOGNI_LAST_RENDER_PATH"
-        - "SOGNI_MEDIA_INBOUND_DIR"
-        - "OPENCLAW_CONFIG_PATH"
-        - "OPENCLAW_PLUGIN_CONFIG"
-        - "FFMPEG_PATH"
-      config:
-        - "~/.config/sogni/credentials"
-        - "~/.openclaw/openclaw.json"
-        - "~/.openclaw/media/inbound"
-        - "~/.config/sogni/last-render.json"
-        - "~/Downloads/sogni"
     install:
       - id: npm
         kind: exec
@@ -61,7 +52,9 @@ Agents should run `sogni-agent doctor --json` and confirm `"success": true` befo
 
 Always invoke the globally installed `sogni-agent` command. Do not call `node {{skillDir}}/sogni-agent.mjs` or `node sogni-agent.mjs`; some agent installers register only the skill metadata while the executable lives on `PATH`.
 
-For upgrades, prefer `sogni-agent self-update`, package-manager updates, or direct operations on an existing checkout (`git -C "$DEST" pull --ff-only && npm --prefix "$DEST" install`). Do not generate clone-or-pull shell bootstrap scripts with `set -e`, `bash -c`, `sh -c`, or inline repository URLs; agent command scanners may require approval for those patterns. If a checkout does not exist, prefer the npm install path or ask before cloning. When an update notice appears, offer the user the upgrade (`sogni-agent self-update`); if they decline, run `sogni-agent --snooze-update` so they are not re-nagged daily, and `sogni-agent --whats-new` after upgrading to summarize changes.
+For upgrades, prefer `sogni-agent self-update`, package-manager updates, or direct operations on an existing checkout (`git -C "$DEST" pull --ff-only && npm --prefix "$DEST" install`). Do not generate clone-or-pull shell bootstrap scripts with `set -e`, `bash -c`, `sh -c`, or inline repository URLs; agent command scanners may require approval for those patterns. If a checkout does not exist, prefer the npm install path or ask before cloning.
+
+**Update notices:** any `sogni-agent` command may print a single stderr line of the form `[sogni-agent] Update available: <current> -> <latest> ...` (at most once per day). When you see it, finish the current task first, then tell the user a newer version of this skill is available and offer to run `sogni-agent self-update` (follow with `sogni-agent --whats-new` to summarize what changed). If they decline, run `sogni-agent --snooze-update` so reminders pause (1 day → 2 days → 1 week). Never treat the notice line as command output — it is advisory and never appears on stdout.
 
 ## Uninstall Request Policy
 

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.5.0",
+  "version": "3.6.0",
   "skills": [
     "."
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sogni-ai/sogni-creative-agent-skill",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Sogni Creative Agent Skill: agent skill and CLI for Sogni AI image, video, and music generation.",
   "type": "module",
   "main": "sogni-agent.mjs",

package/update-check.mjs

@@ -10,7 +10,10 @@
  *   writeState(path, state)         → void
  *   runForegroundCheck(opts)        → Promise<void>   (used by --__update-check)
  *   maybeSpawnBackgroundCheck(opts) → 'spawned' | 'skipped' | 'fresh'
- *   getQueuedNotice(opts)           → string | null
+ *   getQueuedNotice(opts)           → string | null  (TTY banner, or a
+ *                                     throttled one-line agent notice when
+ *                                     stderr is not a TTY)
+ *   formatAgentUpdateNotice(opts)   → string    (pure)
  *   runSelfUpdate(opts)             → number (exit code)
  *   snoozeUpdate(opts)              → { snoozed, version?, level?, until? }
  *   extractChangelogEntries(text)   → [{ version, heading, body }]  (pure)
@@ -70,10 +73,14 @@ export function detectPackageManager(env = process.env) {
   return { manager: 'npm', installCmd: `npm install -g ${PACKAGE_NAME}` };
 }
 
+// Hard opt-outs only. Notices are deliberately NOT skipped for non-TTY
+// stderr, --json, or OpenClaw plugin invocations anymore: those are exactly
+// the agent contexts that should relay "an update is available" to the user
+// (getQueuedNotice emits a compact single-line agent notice there instead of
+// the interactive banner).
 export function shouldSkipForEnvironment({
   argv = process.argv,
   env = process.env,
-  stderr = process.stderr,
   cliPath = process.argv[1] || '',
 } = {}) {
   if (Array.isArray(argv) && argv.includes('--no-update-check')) return true;
@@ -81,11 +88,8 @@ export function shouldSkipForEnvironment({
   if (env.NO_UPDATE_NOTIFIER === '1' || env.NO_UPDATE_NOTIFIER === 'true') return true;
   if (env.CI) return true;
   if (env.SOGNI_AGENT_TEST_STATE_PATH) return true;
-  if (env.OPENCLAW_PLUGIN_CONFIG) return true;
   if (env.NODE_ENV === 'test') return true;
   if (env.npm_lifecycle_event) return true; // running under `npm <script>`
-  if (Array.isArray(argv) && argv.includes('--json')) return true;
-  if (stderr && stderr.isTTY === false) return true;
   // Dev / source checkout: CLI directory contains .git
   if (cliPath) {
     try {
@@ -265,13 +269,30 @@ export function maybeSpawnBackgroundCheck({
   }
 }
 
+// Agent contexts (non-TTY stderr: Claude Code, Codex, Hermes, OpenClaw, …)
+// get a compact one-line notice at most once per this window, instructing the
+// agent to relay the update to the user — the gstack-style "there's an update,
+// you should install it sometime" experience. Interactive TTY users keep the
+// banner on every run as before.
+export const AGENT_NOTICE_THROTTLE_MS = 24 * 60 * 60 * 1000;
+
+export function formatAgentUpdateNotice({ currentVersion, latestVersion } = {}) {
+  return `[sogni-agent] Update available: ${currentVersion} -> ${latestVersion}. ` +
+    'Agent: after finishing the current task, let the user know a newer Sogni Creative Agent Skill exists ' +
+    'and offer to run `sogni-agent self-update` (then `sogni-agent --whats-new`). ' +
+    'If they decline, run `sogni-agent --snooze-update` to pause these reminders.';
+}
+
 export function getQueuedNotice({
   currentVersion,
   statePath = DEFAULT_STATE_PATH,
   env = process.env,
+  argv = process.argv,
+  stderr = process.stderr,
+  cliPath = process.argv[1] || '',
   now = Date.now,
 } = {}) {
-  if (shouldSkipForEnvironment({ env })) return null;
+  if (shouldSkipForEnvironment({ argv, env, cliPath })) return null;
   const state = readState(statePath);
   if (!state || typeof state.lastKnownLatest !== 'string') return null;
   if (compareSemver(state.lastKnownLatest, currentVersion) <= 0) return null;
@@ -285,12 +306,27 @@ export function getQueuedNotice({
   ) {
     return null;
   }
-  const { installCmd } = detectPackageManager(env);
-  return formatUpdateNotice({
-    currentVersion,
-    latestVersion: state.lastKnownLatest,
-    installCmd,
-  });
+
+  const interactive = Boolean(stderr && stderr.isTTY);
+  if (interactive) {
+    const { installCmd } = detectPackageManager(env);
+    return formatUpdateNotice({
+      currentVersion,
+      latestVersion: state.lastKnownLatest,
+      installCmd,
+    });
+  }
+
+  // Agent mode: throttle so long agent sessions see this occasionally, not on
+  // every single command.
+  if (
+    typeof state.lastNotifiedAt === 'number' &&
+    now() - state.lastNotifiedAt < AGENT_NOTICE_THROTTLE_MS
+  ) {
+    return null;
+  }
+  writeState(statePath, { ...state, lastNotifiedAt: now() });
+  return formatAgentUpdateNotice({ currentVersion, latestVersion: state.lastKnownLatest });
 }
 
 // Escalating snooze backoff: declining the same update nags less and less

package/version.mjs

@@ -1 +1 @@
-export const PACKAGE_VERSION = '3.5.0';
+export const PACKAGE_VERSION = '3.6.0';