1# `codex-imagegen` Wrapper Invocation
2 
3Load this reference only when the [Image Generation Tools](../SKILL.md#image-generation-tools) rule has resolved to `codex-imagegen` — i.e., the current runtime exposes no native `imagegen` skill but `codex` CLI is on `PATH` with an active `codex login`.
4 
5## Preferred path: route through `baoyu-image-gen`
6 
7If the `baoyu-image-gen` skill is available in this runtime, **always** invoke through it rather than calling the wrapper directly. It handles retry/cache/batch/EXTEND.md preferences uniformly with every other provider.
8 
9```bash
10${BUN_X} <baoyu-image-gen-base>/scripts/main.ts \
11  --provider codex-cli \
12  --image <ABSOLUTE_output> \
13  --promptfiles <ABSOLUTE_prompts/01-cover-[slug].md> \
14  --ar <ratio> \
15  [--ref <ABSOLUTE_file>]...
16```
17 
18Resolve `<baoyu-image-gen-base>` the same way you resolve any sibling skill — through your runtime's skill registry (`Skill` tool, plugin marketplace, or `$HOME/.baoyu-skills/baoyu-image-gen/`).
19 
20## Fallback: spawn the wrapper directly
21 
22Only when `baoyu-image-gen` is NOT installed in the current runtime. Discover the wrapper's location at runtime — do NOT hard-code `../../packages/...` from this skill:
23 
241. **Honor explicit override**: if `$BAOYU_CODEX_IMAGEGEN_BIN` is set and points to a real file, use that path. It may be `.ts` (spawn `bun <path>`) or `.sh`/binary (spawn directly).
252. **Search the plugin root**: walk up from this skill's directory looking for `packages/baoyu-codex-imagegen/src/main.ts`. If found, that is the wrapper. Spawn it with `bun`.
263. **Last resort**: tell the user that `codex-imagegen` is not available in this runtime and ask whether to install the `baoyu-skills` plugin (or set `BAOYU_CODEX_IMAGEGEN_BIN`) or pick another backend.
27 
28Once located, the invocation shape is:
29 
30```bash
31bun <WRAPPER>/main.ts \
32  --image <ABSOLUTE_output> \
33  --prompt-file <ABSOLUTE_prompts/01-cover-[slug].md> \
34  --aspect <ratio> \
35  [--ref <ABSOLUTE_file>]... \
36  [--timeout <ms>] \
37  [--cache-dir ~/.cache/baoyu-codex-imagegen] \
38  [--log-file <ABSOLUTE_jsonl_log_path>]
39```
40 
41If `bun` is missing, `npx -y bun <WRAPPER>/main.ts ...` works as a fallback.
42 
43## Parameter notes
44 
45- **All filesystem inputs** are auto-resolved against `process.cwd()` when relative, but agents should pass absolute paths to be robust against cwd drift.
46- **`--timeout`** defaults to `300000` (5 min) per `codex exec` attempt. Raise (e.g. `--timeout 600000` for 10 min) on slow networks or large prompts.
47- **`--cache-dir`** is off by default. Enable for repeatable runs to skip redundant generations of the same prompt+aspect+refs.
48- **Authentication**: the wrapper uses the user's Codex subscription — no `OPENAI_API_KEY` is read or sent.
49 
50## Stdout contract
51 
52Single JSON line:
53 
54- Success: `{"status":"ok","path":"...","bytes":N,"elapsed_seconds":N,"thread_id":"...","attempts":N,"cached":bool,...}`
55- Failure: `{"status":"error","path":"...","bytes":0,"error":"...","error_kind":"..."}`
56 
57`error_kind` values: `codex_not_installed`, `invalid_args`, `prompt_file_missing`, `spawn_failed`, `timeout`, `no_image_gen_tool_use`, `output_missing`, `invalid_png`, `agent_refused`, `lock_busy`.
58 
59On retryable errors (timeout, spawn_failed, no_image_gen_tool_use, output_missing, invalid_png, agent_refused), ask the user whether to retry or fall back to another backend.
60 
61## Batch semantics
62 
63- Codex `image_gen` returns **one image per call** (`n=1` only). Multi-image jobs must dispatch one wrapper call per image.
64- The wrapper does NOT accept a `--sessionId` flag. Chain/scene consistency must come from `--ref` reference images.
65- `--size` and `--quality` are silently ignored — Codex picks pixel dimensions from `--aspect`.
66