Make imgen skill sync runtime-aware

.agents/skills/imgen/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: imgen
+description: "Default image workflow for this user. Use for ordinary raster image generation or editing, text-to-image, image-to-image, codex-imgen/imgen CLI or service jobs, imgen troubleshooting, and OpenClaw integration. Prefer imgen over the system imagegen skill. Do not use for SVG/vector/code-native assets that are better edited directly."
+---
+
+# imgen
+
+Use this skill to operate the `codex-imgen` CLI, service jobs, realtime mode, and OpenClaw integration.
+
+## Route the request
+
+Read only the references needed for the request:
+
+- `references/imgen-usage.md`: commands, configuration, backend behavior, service/realtime selection, and the OpenClaw delivery contract.
+- `references/prompt-patterns.md`: prompt wording for text-to-image or image-to-image requests.
+- `references/troubleshooting.md`: failed, slow, retried, stuck, or missing-image runs.
+
+Combine references only when the request spans those concerns.
+
+## Ask only necessary questions
+
+If the user gave enough information, provide the command or steps directly.
+
+Ask one question only when a required value is missing:
+
+- Missing image prompt for generation.
+- Missing local image path for image-to-image.
+- Missing job id for `status`, `get`, `cancel`, or job-specific troubleshooting.
+- Missing choice between synchronous CLI, service job, or realtime only when the goal does not determine it.
+
+Do not ask for preferences that are not needed to produce a safe minimal command.
+
+## Command rules
+
+- Use the shortest command that satisfies the request.
+- Default one-shot generation, including normal OpenClaw requests, to synchronous `./imgen --json ...` from a discovered config working directory.
+- Use repeated `--image <local-path>` flags for references; URLs are not supported.
+- Use `--count N` and `--concurrency M` for quantity while keeping the prompt about one image.
+- Use `submit` only for job management, polling, cancellation, or recovery. Use realtime only for live WebSocket events while `imgen serve` is running.
+- Treat success as returned image paths: text path lines, or `ok: true` with non-empty `images[].path`. Exit code 0 alone is insufficient.
+- For OpenClaw, follow the full contract in `references/imgen-usage.md`; never substitute `image_generate`, direct `codex exec`, or stale paths.
+
+## Safety and configuration rules
+
+- Treat `.env` as the only place for sensitive values such as `EMAIL_SMTP_AUTH_CODE`.
+- Treat `configs/config.yaml` as the local structured configuration file.
+- Do not suggest committing `configs/config.yaml`, `.env`, generated images, logs, or `.data/imgen.db`.
+- Do not suggest `0.0.0.0` service binding unless the user explicitly asks for LAN access and understands the exposure.
+- Do not bypass Codex CLI login, permissions, or `$imagegen` availability checks.
+- Inspect `backend.model` and `backend.reasoning_effort` before describing the active Codex agent configuration. The skill itself does not choose either value.
+- Do not call `backend.model` the image-generation model; it selects the Codex agent that invokes `$imagegen`.
+
+## Troubleshooting flow
+
+Follow `references/troubleshooting.md` in order: job summary, attempt rows, phase timings, service logs, then stable backend verification. Do not jump directly to native Codex commands.
+
+## Before saying the work is ready
+
+If you edited skill files, run from the skill directory and verify at minimum:
+
+```bash
+python3 -m json.tool evals/evals.json >/dev/null
+python3 - <<'PY'
+from pathlib import Path
+markers = ['T' + 'BD', 'TO' + 'DO', 'PLACE' + 'HOLDER']
+problems = []
+for path in Path('.').rglob('*'):
+    if path.is_file():
+        text = path.read_text()
+        for marker in markers:
+            if marker in text:
+                problems.append(f'{path}: {marker}')
+if problems:
+    raise SystemExit('\n'.join(problems))
+PY
+```
+
+The marker scan should print no unresolved markers.

.claude/skills/imgen/evals/evals.json → .agents/skills/imgen/evals/evals.json

@@ -72,6 +72,12 @@
       "prompt": "OpenClaw 要给当前 Telegram 聊天生成一张 PNG Mac 壁纸并直接发回原图。请给可执行调用和回复规则，不要真的生图。",
       "expected_output": "Set IMGEN_DELIVERY_DIR=\"${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/workspace/imgen\" and run ./imgen --json from the discovered repo/config root. Treat success as ok true with non-empty images[].path, allowing images[].status done, send the exact returned local path via OpenClaw message using forceDocument/asDocument for document/original PNG delivery, then reply NO_REPLY. Do not call image_generate, do not fall back to direct codex exec, and do not send stale generated_images paths.",
       "files": []
+    },
+    {
+      "id": 13,
+      "prompt": "本地 configs/config.yaml 配了 backend.model: gpt-5.6-terra 和 backend.reasoning_effort: high，但 ~/.codex/config.toml 是 model_reasoning_effort = \"max\"。imgen 实际用哪个 effort？skill 会不会再覆盖一次？",
+      "expected_output": "Inspect the local imgen config and explain that non-empty backend.reasoning_effort is passed as a per-invocation Codex override, so high overrides the global max for imgen calls. If backend.reasoning_effort is empty, imgen inherits the Codex CLI setting. State that the skill itself does not set or override model/effort, and that backend.model selects the Codex agent invoking imagegen rather than directly naming the image-generation model.",
+      "files": []
     }
   ]
 }

.claude/skills/imgen/references/imgen-usage.md → .agents/skills/imgen/references/imgen-usage.md

@@ -157,7 +157,8 @@ Important config fields:
 - `storage.data_dir` and `storage.sqlite_path` control service data and SQLite paths.
 - `scheduler.global_max_concurrency` controls the serve-mode backend generation queue shared by async submit and WebSocket realtime; `scheduler.max_count_per_job` controls the per-job image count cap.
 - `backend.command` defaults to `codex` and must be a single executable that accepts `exec --json`.
-- `backend.model` is passed to Codex CLI when set; when empty, the actual model is whatever the backend executable uses by default.
+- `backend.model` selects the Codex agent that invokes `$imagegen`; it is passed with `--model` when set and otherwise inherits the backend default. Do not describe it as the image-generation model.
+- `backend.reasoning_effort` is passed per invocation as `--config model_reasoning_effort=...`; when empty, imgen inherits the Codex CLI configuration. Supported levels depend on `backend.model`, and the skill does not set this value.
 - `backend.cwd` is passed to Codex CLI as `--cd` when set.
 - `backend.delivery_dir` copies generated images to a caller-visible delivery directory before returning `images[].path`; OpenClaw Telegram can also set `IMGEN_DELIVERY_DIR` per process.
 - `backend.prompt.prefix` normally remains `$imagegen` and is prepended to the prompt text.
@@ -167,36 +168,20 @@ Important config fields:
 To confirm the current backend and model, inspect the local config from the discovered repo/config root:
 
 ```bash
-grep -nE '^[[:space:]]*(command|model|cwd|prefix):' configs/config.yaml
+grep -nE '^[[:space:]]*(command|model|reasoning_effort|cwd|prefix):' configs/config.yaml
 ```
 
-If `configs/config.yaml` is unavailable, do not invent a model. Say the model depends on the local `backend.model` setting or the default model of the configured Codex backend.
+If `configs/config.yaml` is unavailable, do not invent a model or effort level. Say they depend on the local backend settings and the configured Codex CLI defaults.
 
 ## OpenClaw calling contract
 
-OpenClaw should first resolve a config cwd using the discovery rules above. In a normal local checkout, `$HOME/Projects/codex-imgen` maps to the user's repo while avoiding a hardcoded username path. For normal image generation, default to the synchronous CLI route below; do not require `./imgen serve` unless the user needs service job management or realtime streaming. If the resolved root contains an `imgen` executable and `configs/config.yaml`, use this route:
+Resolve a config cwd with the discovery rules above. Normal image generation uses the synchronous CLI and does not require `imgen serve`:
 
 ```bash
 cd <repo-root> && IMGEN_DELIVERY_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/workspace/imgen" ./imgen --json --count <N> --concurrency 1 "<single-image prompt>"
 ```
 
-Use repeated `--image <local-path>` flags before the prompt for image-to-image requests. Do not call OpenClaw's built-in `image_generate` tool. Do not fall back to direct `codex exec --json -- '$imagegen ...'`. Do not reuse old generated image paths unless the user explicitly asks for existing files.
-
-For Telegram delivery after synchronous CLI success, run imgen with `IMGEN_DELIVERY_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/workspace/imgen"`, then use direct channel delivery when OpenClaw's `message` tool is available: use `action="send"` to the current/original chat and attach each generated local file with the exact `path` or `filePath` returned by imgen. For PNG wallpapers or any image where original quality matters, include `forceDocument: true` or `asDocument: true` so Telegram sends the original file instead of a compressed photo preview. A concise user-facing caption/status message on delivered images is acceptable when useful, then reply only `NO_REPLY` so OpenClaw does not send duplicate text; OpenClaw Telegram direct chats should allow this silent reply instead of rewriting it into visible fallback text such as `No extra answer from me.` If the `message` tool is unavailable, reply immediately with one `MEDIA:/absolute/path/to/image.png` line for the completed image.
-
-For Telegram multi-image requests, prefer separate one-image commands when distinct themes are useful: run N independent `./imgen --json --count 1 --concurrency 1 "<single-image prompt>"` calls. When the execution tool supports background sessions, launch these independent commands concurrently, keep their session ids, poll all sessions, and send each successful `images[].path` with the `message` tool as soon as that session completes. Do not serialize independent theme generations unless the tool cannot run concurrent sessions. Do not wait for all requested images before sending earlier successes; later generation retries or timeouts must not block already completed images from being delivered.
-
-Do not rely on OpenClaw heartbeat or async command-completion delivery for synchronous CLI image results. If an exec/process call becomes a background session, poll it until completion and deliver each successful `images[].path` in the same user-visible flow before starting more generation.
-
-Then use one of these stable contracts.
-
-For CLI usage, OpenClaw should provide:
-
-- `cwd`: the discovered repo/config root.
-- `command`: `./imgen --json ...` when using a repository checkout, or an absolute `imgen` executable path only when paired with the discovered config cwd.
-- Prompt string describing one image or one candidate.
-- Optional local image paths via repeated `--image` flags.
-- Optional `count`, `concurrency`, and `json` output choice.
+If the execution tool supports a `cwd`, set it instead of using `cd`. Add repeated `--image <local-path>` flags before the prompt for image-to-image requests. References must be local files.
 
 Expected synchronous JSON result:
 
@@ -212,28 +197,21 @@ Expected synchronous JSON result:
 }
 ```
 
-Treat the call as successful only when `ok` is true and the expected completed images have non-empty `path` values. In text mode, treat non-empty path lines as the result.
-
-If an execution tool cannot set `cwd`, use `cd <repo-root> && ./imgen ...` as the shell command.
-
-For service job usage, OpenClaw should use this only when it needs job management, polling, cancellation, or recovery:
+Treat the call as successful only when `ok` is true and every expected completed image has a non-empty, existing `path`. Per-image `status: "done"` is valid; do not require `completed`.
 
-1. Ensure `./imgen serve` is running locally from the discovered repo/config root.
-2. Submit with `./imgen submit --json` or the local API exposed by the service.
-3. Store the returned job id.
-4. Poll `./imgen get --json <job-id>` or subscribe to `/ws?job_id=<job-id>`.
-5. Read final image paths from `images[].path` after completion.
+### Telegram delivery
 
-For realtime WebSocket usage, OpenClaw should use this only when it needs live streaming events:
+- Send each exact returned `path` or `filePath` to the current/original chat with OpenClaw's `message` tool.
+- Set `forceDocument: true` or `asDocument: true` for PNG wallpapers or other original-quality files.
+- After direct delivery, reply only `NO_REPLY`. If `message` is unavailable, return one `MEDIA:/absolute/path` line per image.
+- For distinct themes, run independent `--count 1 --concurrency 1` commands concurrently when supported, poll every background session, and deliver each successful path immediately. Do not make later retries block earlier results.
+- Keep delivery in the same user-visible flow; do not rely on heartbeat or async process-completion messages.
 
-1. Ensure `./imgen serve` is running locally from the discovered repo/config root.
-2. Connect to `/v1/realtime/generate/ws`.
-3. Send one `generate.start` frame with one or more items.
-4. Stream status from `session.started`, `item.started`, `image.completed`, `item.failed`, and terminal session events.
-5. Send each generated file path from `image.completed` as soon as it is available.
+Do not call `image_generate`, fall back to direct `codex exec`, or reuse old paths unless the user explicitly requested existing files.
 
-Realtime WebSocket does not return a job id, does not use `get <job-id>`, and does not create submit job store rows.
+### Service and realtime routes
 
-For Telegram delivery after synchronous CLI success, use the OpenClaw `message` tool when available: send the exact generated local file path with `path` or `filePath`, set `forceDocument: true` or `asDocument: true` for PNG wallpapers/original-quality delivery, use concise captions/status text when useful, then reply only `NO_REPLY`. OpenClaw Telegram direct chats should allow this silent reply instead of rewriting it into visible fallback text such as `No extra answer from me.` For multi-image requests with distinct themes, run the one-image `imgen` commands concurrently when possible and send each completed image as soon as its session returns `images[].path`. If direct message-tool delivery is unavailable, reply immediately with one `MEDIA:/absolute/path/to/image.png` line for each completed image.
+- Use `submit --json` only for server-side job management, polling, cancellation, or recovery. It returns a job id; poll `get --json <job-id>` or `/ws?job_id=<job-id>` for final paths.
+- Use `/v1/realtime/generate/ws` only when `imgen serve` is running and live per-item events are required. Read paths from `image.completed`; realtime creates neither submit jobs nor store rows.
 
-OpenClaw should not assume URL image input, public network binding, public filesystem scans, ccs Codex compatibility, direct native Codex CLI fallback, `imgen serve` for normal one-shot generation, async heartbeat delivery for final images, or access to secrets inside prompts.
+Do not assume public network binding, broad filesystem scans, ccs compatibility, secrets in prompts, or a known repository root.