Add baoyu-skills package

baoyu-skills/packages/baoyu-codex-imagegen/README.md

@@ -0,0 +1,102 @@
+# baoyu-codex-imagegen
+
+Generate images via Codex CLI's built-in `image_gen` tool from non-Codex runtimes (e.g., Claude Code). The wrapper spawns `codex exec --json` and lets the user's existing Codex subscription drive image generation — **no `OPENAI_API_KEY` required**.
+
+This package implements the `preferred_image_backend: codex-imagegen` config key referenced across the `baoyu-skills` plugin and is the engine behind `baoyu-image-gen --provider codex-cli`.
+
+## Layout
+
+```
+packages/baoyu-codex-imagegen/
+├── src/
+│   ├── main.ts             # CLI orchestrator (executable via `#!/usr/bin/env bun`)
+│   ├── spawn.ts            # codex exec child-process wrapper
+│   ├── parser.ts           # JSONL event-stream parser
+│   ├── validator.ts        # Output PNG / image_gen-invocation verification
+│   ├── cache.ts            # SHA256 idempotency cache + file lock
+│   ├── logger.ts           # Structured JSONL logging
+│   ├── types.ts            # Shared types and `GenError`
+│   └── *.test.ts           # Bun unit tests
+└── package.json            # `bin` points to `src/main.ts`
+```
+
+## Prerequisites
+
+```bash
+npm install -g @openai/codex
+codex login            # signs in with your OpenAI account (subscription)
+codex --version        # confirm >= 0.130
+```
+
+`bun` is required for running the wrapper:
+
+```bash
+brew install oven-sh/bun/bun
+```
+
+If `bun` is not on `PATH`, `npx -y bun src/main.ts …` works as a fallback.
+
+## Usage
+
+```bash
+# Inline prompt (executes via shebang once bun is on PATH)
+./src/main.ts \
+  --image /tmp/cat.png \
+  --prompt "A friendly orange cat, watercolor"
+
+# Or invoke bun explicitly
+bun src/main.ts \
+  --image cover.png \
+  --prompt-file prompts/01-cover.md \
+  --aspect 16:9 \
+  --cache-dir ~/.cache/baoyu-codex-imagegen
+
+# Without bun installed
+npx -y bun src/main.ts --image cover.png --prompt "..."
+```
+
+Stdout emits a single JSON line:
+
+```json
+{"status":"ok","path":"…","bytes":1234567,"elapsed_seconds":62,"thread_id":"…","attempts":1,"cached":false,"usage":{…}}
+```
+
+On failure:
+
+```json
+{"status":"error","path":"…","bytes":0,"error":"…","error_kind":"timeout"}
+```
+
+`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`.
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--image <path>` | Output PNG path (required) |
+| `--prompt <text>` | Prompt text |
+| `--prompt-file <path>` | Read prompt from file (mutually exclusive with `--prompt`) |
+| `--aspect <ratio>` | Aspect ratio (`1:1`, `16:9`, `9:16`, `4:3`, `2.35:1`). Default: `1:1` |
+| `--ref <file>` | Reference image (repeatable) |
+| `--timeout <ms>` | Codex exec timeout in ms. Default: `300000` |
+| `--retries <n>` | Retry attempts on retryable errors. Default: `2` |
+| `--retry-delay <ms>` | Base retry delay (exponential). Default: `1500` |
+| `--cache-dir <path>` | Enable idempotency cache. Disabled by default. |
+| `--log-file <path>` | Append structured JSONL log |
+| `-v, --verbose` | Verbose stderr logging |
+| `-h, --help` | Show help |
+
+## Test
+
+```bash
+cd packages/baoyu-codex-imagegen
+bun test
+```
+
+## Trade-offs
+
+- 5–10× slower than direct OpenAI API calls (except on cache hits)
+- Uses your Codex subscription — programmatic use of `codex exec` falls into the same terms as interactive use
+- Requires `codex` CLI and active login session
+
+See [`docs/codex-imagegen-backend.md`](../../docs/codex-imagegen-backend.md) for the full background.

baoyu-skills/packages/baoyu-codex-imagegen/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "baoyu-codex-imagegen",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "Generate images via Codex CLI's built-in image_gen tool from non-Codex runtimes (Claude Code, Hermes, …).",
+  "bin": {
+    "codex-imagegen": "./src/main.ts"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/main.ts",
+      "default": "./src/main.ts"
+    },
+    "./src/*": "./src/*"
+  },
+  "scripts": {
+    "test": "bun test",
+    "smoke": "bun src/main.ts --help"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JimLiu/baoyu-skills.git",
+    "directory": "packages/baoyu-codex-imagegen"
+  },
+  "bugs": {
+    "url": "https://github.com/JimLiu/baoyu-skills/issues"
+  },
+  "homepage": "https://github.com/JimLiu/baoyu-skills/tree/main/packages/baoyu-codex-imagegen#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  }
+}

baoyu-skills/packages/baoyu-codex-imagegen/src/cache.test.ts

@@ -0,0 +1,63 @@
+import { test, expect } from "bun:test";
+import { mkdtemp, writeFile, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { cacheKey, lookupCache, storeCache, FileLock } from "./cache.ts";
+
+test("cacheKey is deterministic and order-independent for refs", () => {
+  const k1 = cacheKey("hello", "16:9", ["a.png", "b.png"]);
+  const k2 = cacheKey("hello", "16:9", ["b.png", "a.png"]);
+  expect(k1).toBe(k2);
+  const k3 = cacheKey("hello", "16:9", []);
+  expect(k3).not.toBe(k1);
+  const k4 = cacheKey("hello", "1:1", []);
+  expect(k4).not.toBe(k3);
+});
+
+test("lookupCache returns null on miss, path on hit", async () => {
+  const dir = await mkdtemp(path.join(tmpdir(), "cig-test-"));
+  try {
+    expect(await lookupCache(dir, "abc")).toBeNull();
+    const fake = path.join(dir, "abc.png");
+    await writeFile(fake, Buffer.alloc(2000));
+    expect(await lookupCache(dir, "abc")).toBe(fake);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("storeCache copies source into cache", async () => {
+  const dir = await mkdtemp(path.join(tmpdir(), "cig-test-"));
+  const src = path.join(dir, "src.png");
+  try {
+    await writeFile(src, Buffer.from("xxxx".repeat(1000)));
+    await storeCache(dir, "key1", src);
+    const cached = await lookupCache(dir, "key1");
+    expect(cached).not.toBeNull();
+    const a = await readFile(src);
+    const b = await readFile(cached!);
+    expect(a.equals(b)).toBe(true);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("FileLock prevents concurrent acquisition", async () => {
+  const dir = await mkdtemp(path.join(tmpdir(), "cig-lock-"));
+  try {
+    const lockPath = path.join(dir, "x.lock");
+    const lock1 = new FileLock(lockPath);
+    const lock2 = new FileLock(lockPath);
+    await lock1.acquire(1000);
+    let lock2Acquired = false;
+    const p = lock2.acquire(500).then(() => (lock2Acquired = true)).catch(() => {});
+    await new Promise((r) => setTimeout(r, 300));
+    expect(lock2Acquired).toBe(false);
+    await lock1.release();
+    await p;
+    expect(lock2Acquired).toBe(true);
+    await lock2.release();
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

baoyu-skills/packages/baoyu-codex-imagegen/src/cache.ts

@@ -0,0 +1,80 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile, copyFile, stat } from "node:fs/promises";
+import { existsSync, openSync, closeSync } from "node:fs";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+
+export function cacheKey(prompt: string, aspect: string, refs: string[]): string {
+  const h = createHash("sha256");
+  h.update(prompt);
+  h.update("|");
+  h.update(aspect);
+  h.update("|");
+  for (const r of [...refs].sort()) h.update(r);
+  return h.digest("hex").slice(0, 16);
+}
+
+export async function lookupCache(cacheDir: string, key: string): Promise<string | null> {
+  const entry = path.join(cacheDir, `${key}.png`);
+  try {
+    const s = await stat(entry);
+    if (s.size > 1000) return entry;
+  } catch {}
+  return null;
+}
+
+export async function storeCache(cacheDir: string, key: string, sourcePath: string): Promise<void> {
+  await mkdir(cacheDir, { recursive: true });
+  const entry = path.join(cacheDir, `${key}.png`);
+  await copyFile(sourcePath, entry);
+}
+
+export class FileLock {
+  private fd: number | null = null;
+  constructor(private lockPath: string) {}
+
+  async acquire(timeoutMs = 30_000): Promise<void> {
+    const start = Date.now();
+    await mkdir(path.dirname(this.lockPath), { recursive: true });
+    while (Date.now() - start < timeoutMs) {
+      try {
+        this.fd = openSync(this.lockPath, "wx");
+        return;
+      } catch (e: any) {
+        if (e.code !== "EEXIST") throw e;
+        if (await this.isStale()) {
+          try {
+            await this.release(true);
+          } catch {}
+          continue;
+        }
+        await delay(200);
+      }
+    }
+    throw new Error(`Failed to acquire lock at ${this.lockPath} within ${timeoutMs}ms`);
+  }
+
+  private async isStale(): Promise<boolean> {
+    try {
+      const s = await stat(this.lockPath);
+      return Date.now() - s.mtimeMs > 10 * 60 * 1000;
+    } catch {
+      return true;
+    }
+  }
+
+  async release(force = false): Promise<void> {
+    if (this.fd != null) {
+      try {
+        closeSync(this.fd);
+      } catch {}
+      this.fd = null;
+    }
+    if (existsSync(this.lockPath) || force) {
+      const { unlink } = await import("node:fs/promises");
+      try {
+        await unlink(this.lockPath);
+      } catch {}
+    }
+  }
+}

baoyu-skills/packages/baoyu-codex-imagegen/src/logger.ts

@@ -0,0 +1,39 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+
+export interface LogEntry {
+  ts: string;
+  level: "info" | "warn" | "error";
+  event: string;
+  [k: string]: unknown;
+}
+
+export class JsonLogger {
+  constructor(private logFile: string | null, public verbose: boolean) {}
+
+  async log(level: LogEntry["level"], event: string, extra: Record<string, unknown> = {}): Promise<void> {
+    const entry: LogEntry = { ts: new Date().toISOString(), level, event, ...extra };
+    const line = JSON.stringify(entry);
+    if (this.verbose) process.stderr.write(`[${level}] ${event} ${jsonExtras(extra)}\n`);
+    if (this.logFile) {
+      await mkdir(path.dirname(this.logFile), { recursive: true });
+      await appendFile(this.logFile, line + "\n", "utf-8");
+    }
+  }
+
+  info(event: string, extra?: Record<string, unknown>) {
+    return this.log("info", event, extra);
+  }
+  warn(event: string, extra?: Record<string, unknown>) {
+    return this.log("warn", event, extra);
+  }
+  error(event: string, extra?: Record<string, unknown>) {
+    return this.log("error", event, extra);
+  }
+}
+
+function jsonExtras(extra: Record<string, unknown>): string {
+  const entries = Object.entries(extra);
+  if (entries.length === 0) return "";
+  return entries.map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`).join(" ");
+}

baoyu-skills/packages/baoyu-codex-imagegen/src/main.ts

@@ -0,0 +1,332 @@
+#!/usr/bin/env bun
+import { readFile, mkdir, copyFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { setTimeout as delay } from "node:timers/promises";
+import { GenError, type CliOptions, type GenerateResult } from "./types.ts";
+import { runCodexExec } from "./spawn.ts";
+import { hasImageGenEvidence, verifyImageGenWasInvoked, verifyOutput } from "./validator.ts";
+import { cacheKey, lookupCache, storeCache, FileLock } from "./cache.ts";
+import { JsonLogger } from "./logger.ts";
+
+const HELP = `codex-imagegen — generate images via Codex CLI's image_gen tool
+
+Usage:
+  codex-imagegen --image <output.png> [--prompt <text> | --prompt-file <path>] [options]
+
+Required:
+  --image <path>          Output PNG path
+  --prompt <text>         Prompt text (or use --prompt-file)
+  --prompt-file <path>    Read prompt from file
+
+Options:
+  --aspect <ratio>        Aspect ratio (1:1, 16:9, 9:16, 4:3, 2.35:1). Default: 1:1
+  --ref <file>            Reference image (repeatable)
+  --timeout <ms>          Codex exec timeout in ms. Default: 300000
+  --retries <n>           Retry attempts on retryable errors. Default: 2
+  --retry-delay <ms>      Base retry delay (exponential). Default: 1500
+  --cache-dir <path>      Enable idempotency cache. Disabled by default.
+  --log-file <path>       Append JSONL log
+  -v, --verbose           Verbose stderr logging
+  -h, --help              Show this help
+
+Stdout: single JSON line on success or failure.
+`;
+
+const SHELL_METACHAR = /[;|&`$<>\n\r()'"]/;
+
+function assertSafePath(label: string, value: string): void {
+  if (SHELL_METACHAR.test(value)) {
+    throw new GenError(
+      "invalid_args",
+      `${label} contains shell metacharacters and would be unsafe to interpolate into the codex instruction: ${value}`,
+      false,
+    );
+  }
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  const opts: CliOptions = {
+    prompt: "",
+    promptFile: null,
+    outputPath: "",
+    aspect: "1:1",
+    refImages: [],
+    timeoutMs: 300_000,
+    retries: 2,
+    retryDelayMs: 1500,
+    cacheDir: null,
+    logFile: null,
+    verbose: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => argv[++i];
+    switch (a) {
+      case "--prompt": opts.prompt = next(); break;
+      case "--prompt-file": opts.promptFile = next(); break;
+      case "--image": opts.outputPath = next(); break;
+      case "--aspect": opts.aspect = next(); break;
+      case "--ref": opts.refImages.push(next()); break;
+      case "--timeout": opts.timeoutMs = Number(next()); break;
+      case "--retries": opts.retries = Number(next()); break;
+      case "--retry-delay": opts.retryDelayMs = Number(next()); break;
+      case "--cache-dir": opts.cacheDir = next(); break;
+      case "--log-file": opts.logFile = next(); break;
+      case "-v":
+      case "--verbose": opts.verbose = true; break;
+      case "-h":
+      case "--help": process.stdout.write(HELP); process.exit(0);
+      default: throw new GenError("invalid_args", `Unknown argument: ${a}`, false);
+    }
+  }
+  if (!opts.outputPath) throw new GenError("invalid_args", "--image is required", false);
+  if (opts.prompt && opts.promptFile) {
+    throw new GenError("invalid_args", "--prompt and --prompt-file are mutually exclusive", false);
+  }
+  if (!opts.prompt && !opts.promptFile) {
+    throw new GenError("invalid_args", "--prompt or --prompt-file required", false);
+  }
+
+  // Resolve every filesystem path to absolute up front, so behavior is
+  // independent of the caller's cwd. This matters when the wrapper is
+  // invoked from a skill running in an arbitrary working directory.
+  const cwd = process.cwd();
+  const toAbs = (p: string) => (path.isAbsolute(p) ? p : path.resolve(cwd, p));
+
+  opts.outputPath = toAbs(opts.outputPath);
+  if (opts.promptFile) opts.promptFile = toAbs(opts.promptFile);
+  opts.refImages = opts.refImages.map(toAbs);
+  if (opts.cacheDir) opts.cacheDir = toAbs(opts.cacheDir);
+  if (opts.logFile) opts.logFile = toAbs(opts.logFile);
+
+  // The output and ref paths are interpolated raw into the agent instruction
+  // sent to `codex exec --sandbox danger-full-access`. A path containing shell
+  // metacharacters could be misread by the agent's shell when it cp's the
+  // result into place. Reject upfront rather than trusting the agent to quote.
+  assertSafePath("--image path", opts.outputPath);
+  for (const ref of opts.refImages) assertSafePath("--ref path", ref);
+
+  return opts;
+}
+
+async function loadPrompt(opts: CliOptions): Promise<string> {
+  if (opts.prompt) return opts.prompt;
+  const file = opts.promptFile!;
+  try {
+    return await readFile(file, "utf-8");
+  } catch {
+    throw new GenError("prompt_file_missing", `Prompt file not found: ${file}`, false);
+  }
+}
+
+function buildInstruction(prompt: string, opts: CliOptions): string {
+  const refHint = opts.refImages.length > 0
+    ? `\nREFERENCE IMAGES (attached above): ${opts.refImages.length} image(s) provided for style/composition guidance.\n`
+    : "";
+  return `You have an internal tool called image_gen for image generation. You MUST call it before doing anything else.
+
+TASK: Generate an image with the spec below, then save to disk.
+
+PROMPT:
+${prompt}
+
+ASPECT RATIO: ${opts.aspect}
+OUTPUT PATH: ${opts.outputPath}
+${refHint}
+STEPS:
+1. Call image_gen with the prompt and aspect ratio above${opts.refImages.length > 0 ? " (using the attached reference images for guidance)" : ""}.
+2. Move or copy ONLY the image produced by that image_gen call from Codex default location ($CODEX_HOME/generated_images/...) to: ${opts.outputPath}
+3. Verify with: ls -la ${opts.outputPath}
+4. Reply with ONLY this JSON line (no markdown fences, no other text):
+   {"status":"ok","path":"${opts.outputPath}","bytes":<file_size_in_bytes>}
+
+HARD CONSTRAINTS:
+- Do NOT search for, find, inspect, reuse, or copy any pre-existing files from $CODEX_HOME/generated_images/ or any other directory.
+- Do NOT run ls/find/rg/grep/glob over $CODEX_HOME/generated_images/ before image_gen has been called.
+- You MUST call image_gen first. Only after image_gen completes may you copy the newly created file from this turn.
+- Do NOT use curl, wget, Python, or any external API.
+- Do NOT use bash to fabricate an image; only image_gen produces real pixels.
+- Use ONLY the image_gen internal tool.`;
+}
+
+async function attemptGenerate(
+  opts: CliOptions,
+  instruction: string,
+  attempt: number,
+  log: JsonLogger,
+): Promise<{ bytes: number; threadId: string | null; usage: any; toolCalls: any[] }> {
+  await log.info("attempt.start", { attempt, output: opts.outputPath, aspect: opts.aspect });
+
+  const run = await runCodexExec({
+    instruction,
+    timeoutMs: opts.timeoutMs,
+    refImages: opts.refImages,
+  });
+
+  await log.info("codex.completed", {
+    duration_ms: run.durationMs,
+    thread_id: run.threadId,
+    tool_calls: run.toolCalls.length,
+    usage: run.usage,
+    raw_log: run.rawLogPath,
+  });
+
+  // verify: thread id must be present
+  if (!run.threadId) {
+    throw new GenError("agent_refused", "No thread id in event stream");
+  }
+
+  // verify image_gen ran in THIS thread. A PNG in this thread's
+  // generated_images dir is the real signal (image_gen does not surface as a
+  // stream item); the stream check is a forward-compatible fallback. The #185
+  // shortcut (copying an unrelated history image) yields neither.
+  const ver = await verifyImageGenWasInvoked(run.threadId);
+  if (!hasImageGenEvidence(run.toolCalls, ver.ok)) {
+    throw new GenError(
+      "no_image_gen_tool_use",
+      `image_gen was not invoked (no image_gen event in stream; ${ver.reason})`,
+    );
+  }
+
+  // verify output
+  const { bytes } = await verifyOutput(opts.outputPath);
+
+  return {
+    bytes,
+    threadId: run.threadId,
+    usage: run.usage,
+    toolCalls: run.toolCalls.map((tc) => ({ tool: tc.tool, status: tc.status })),
+  };
+}
+
+async function generate(opts: CliOptions, log: JsonLogger): Promise<GenerateResult> {
+  const startEpoch = Date.now();
+  const prompt = await loadPrompt(opts);
+
+  // Cache lookup
+  if (opts.cacheDir) {
+    const key = cacheKey(prompt, opts.aspect, opts.refImages);
+    const cached = await lookupCache(opts.cacheDir, key);
+    if (cached) {
+      await mkdir(path.dirname(opts.outputPath), { recursive: true });
+      await copyFile(cached, opts.outputPath);
+      const s = await stat(opts.outputPath);
+      await log.info("cache.hit", { key, source: cached });
+      return {
+        status: "ok",
+        path: opts.outputPath,
+        bytes: s.size,
+        elapsed_seconds: 0,
+        thread_id: null,
+        attempts: 0,
+        cached: true,
+        usage: null,
+        tool_calls: [],
+      };
+    }
+    await log.info("cache.miss", { key });
+  }
+
+  // lock to prevent concurrent codex exec
+  const lockDir = opts.cacheDir ?? path.join(homedir(), ".cache", "baoyu-codex-imagegen");
+  const lock = new FileLock(path.join(lockDir, "codex-exec.lock"));
+  try {
+    await lock.acquire(60_000);
+  } catch (e) {
+    throw new GenError("lock_busy", String(e), false);
+  }
+
+  await mkdir(path.dirname(opts.outputPath), { recursive: true });
+  const instruction = buildInstruction(prompt, opts);
+
+  let lastErr: GenError | null = null;
+  let lastAttempt = 0;
+  try {
+    for (let attempt = 1; attempt <= opts.retries + 1; attempt++) {
+      lastAttempt = attempt;
+      try {
+        const result = await attemptGenerate(opts, instruction, attempt, log);
+
+        // write to cache
+        if (opts.cacheDir) {
+          const key = cacheKey(prompt, opts.aspect, opts.refImages);
+          await storeCache(opts.cacheDir, key, opts.outputPath);
+          await log.info("cache.stored", { key });
+        }
+
+        return {
+          status: "ok",
+          path: opts.outputPath,
+          bytes: result.bytes,
+          elapsed_seconds: Math.round((Date.now() - startEpoch) / 1000),
+          thread_id: result.threadId,
+          attempts: attempt,
+          cached: false,
+          usage: result.usage,
+          tool_calls: result.toolCalls,
+        };
+      } catch (e) {
+        lastErr = e instanceof GenError ? e : new GenError("spawn_failed", String(e));
+        await log.warn("attempt.failed", {
+          attempt,
+          kind: lastErr.kind,
+          retryable: lastErr.retryable,
+          error: lastErr.message,
+        });
+        if (!lastErr.retryable || attempt > opts.retries) break;
+        const wait = opts.retryDelayMs * Math.pow(2, attempt - 1);
+        await log.info("retry.wait", { wait_ms: wait, next_attempt: attempt + 1 });
+        await delay(wait);
+      }
+    }
+  } finally {
+    await lock.release();
+  }
+
+  const err = lastErr ?? new GenError("spawn_failed", "Unknown failure");
+  err.attempts = lastAttempt;
+  throw err;
+}
+
+async function main() {
+  let opts: CliOptions;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+  } catch (e) {
+    const err = e instanceof GenError ? e : new GenError("invalid_args", String(e), false);
+    process.stderr.write(`Error: ${err.message}\n`);
+    process.exit(2);
+  }
+
+  const log = new JsonLogger(opts.logFile, opts.verbose);
+  await log.info("start", { output: opts.outputPath, aspect: opts.aspect, refs: opts.refImages.length });
+
+  try {
+    const result = await generate(opts, log);
+    await log.info("done", { bytes: result.bytes, attempts: result.attempts, cached: result.cached });
+    process.stdout.write(JSON.stringify(result) + "\n");
+    process.exit(0);
+  } catch (e) {
+    const err = e instanceof GenError ? e : new GenError("spawn_failed", String(e));
+    await log.error("failed", { kind: err.kind, error: err.message, attempts: err.attempts ?? 0 });
+    const out: GenerateResult = {
+      status: "error",
+      path: opts.outputPath,
+      bytes: 0,
+      elapsed_seconds: 0,
+      thread_id: null,
+      attempts: err.attempts ?? 0,
+      cached: false,
+      usage: null,
+      tool_calls: [],
+      error: err.message,
+      error_kind: err.kind,
+    };
+    process.stdout.write(JSON.stringify(out) + "\n");
+    process.exit(1);
+  }
+}
+
+main();

baoyu-skills/packages/baoyu-codex-imagegen/src/parser.test.ts

@@ -0,0 +1,58 @@
+import { test, expect } from "bun:test";
+import { parseEventStream, hasImageGenInvocation } from "./parser.ts";
+
+const REAL_PoC_STREAM = `{"type":"thread.started","thread_id":"019e40d3-30e3-7030-874d-773bc0d6d1eb"}
+{"type":"turn.started"}
+{"type":"item.started","item":{"id":"item_0","type":"command_execution","command":"sed -n '1,5p' /tmp/x.md","status":"in_progress"}}
+{"type":"item.completed","item":{"id":"item_0","type":"command_execution","command":"sed -n '1,5p' /tmp/x.md","exit_code":0,"status":"completed"}}
+{"type":"item.started","item":{"id":"item_1","type":"command_execution","command":"cp /Users/x/.codex/generated_images/019e40d3/ig_abc.png /tmp/out.png","status":"in_progress"}}
+{"type":"item.completed","item":{"id":"item_1","type":"command_execution","command":"cp /Users/x/.codex/generated_images/019e40d3/ig_abc.png /tmp/out.png","exit_code":0,"status":"completed"}}
+{"type":"item.completed","item":{"id":"item_2","type":"agent_message","text":"{\\"status\\":\\"ok\\",\\"path\\":\\"/tmp/out.png\\",\\"bytes\\":1234567}"}}
+{"type":"turn.completed","usage":{"input_tokens":100000,"cached_input_tokens":80000,"output_tokens":500,"reasoning_output_tokens":50}}`;
+
+test("parseEventStream extracts threadId, toolCalls, agentMessage, usage", () => {
+  const r = parseEventStream(REAL_PoC_STREAM);
+  expect(r.threadId).toBe("019e40d3-30e3-7030-874d-773bc0d6d1eb");
+  expect(r.toolCalls.length).toBe(3);
+  expect(r.usage).toEqual({
+    input: 100000,
+    cached_input: 80000,
+    output: 500,
+    reasoning: 50,
+  });
+  expect(r.agentMessage).toContain('"status":"ok"');
+});
+
+test("parseEventStream tolerates malformed lines", () => {
+  const stream = `not json at all
+{"type":"thread.started","thread_id":"abc"}
+{partial json
+{"type":"turn.completed","usage":{"input_tokens":1,"cached_input_tokens":0,"output_tokens":1,"reasoning_output_tokens":0}}`;
+  const r = parseEventStream(stream);
+  expect(r.threadId).toBe("abc");
+  expect(r.usage?.input).toBe(1);
+});
+
+test("hasImageGenInvocation does not infer image_gen from shell copies", () => {
+  const r = parseEventStream(REAL_PoC_STREAM);
+  const hasCp = r.toolCalls.some((tc) => tc.command?.includes("generated_images"));
+  expect(hasCp).toBe(true);
+  expect(hasImageGenInvocation(r.toolCalls)).toBe(false);
+});
+
+test("hasImageGenInvocation detects real image_gen tool calls only", () => {
+  expect(hasImageGenInvocation([{ id: "1", tool: "shell", status: "completed" }])).toBe(false);
+  expect(
+    hasImageGenInvocation([{ id: "1", tool: "image_gen", status: "completed" }]),
+  ).toBe(true);
+});
+
+test("parseEventStream normalizes an image_generation item to image_gen", () => {
+  const stream = `{"type":"thread.started","thread_id":"t1"}
+{"type":"item.started","item":{"id":"g0","type":"image_generation","status":"in_progress"}}
+{"type":"item.completed","item":{"id":"g0","type":"image_generation","status":"completed"}}
+{"type":"item.completed","item":{"id":"m0","type":"agent_message","text":"done"}}`;
+  const r = parseEventStream(stream);
+  expect(r.toolCalls.some((tc) => tc.tool === "image_gen")).toBe(true);
+  expect(hasImageGenInvocation(r.toolCalls)).toBe(true);
+});

baoyu-skills/packages/baoyu-codex-imagegen/src/parser.ts

@@ -0,0 +1,64 @@
+import type { CodexRunResult, ToolCall, TokenUsage } from "./types.ts";
+
+export function parseEventStream(raw: string): Omit<CodexRunResult, "rawLogPath" | "durationMs"> {
+  const lines = raw.split("\n").filter((l) => l.trim().length > 0);
+  let threadId: string | null = null;
+  let agentMessage: string | null = null;
+  let usage: TokenUsage | null = null;
+  const toolCallsById = new Map<string, ToolCall>();
+
+  for (const line of lines) {
+    let event: any;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const type = event?.type;
+    if (type === "thread.started") {
+      threadId = event.thread_id ?? null;
+    } else if (type === "item.started" || type === "item.completed") {
+      const item = event.item;
+      if (!item?.id) continue;
+      const tc: ToolCall = {
+        id: item.id,
+        tool: deriveToolName(item),
+        status: item.status ?? (type === "item.completed" ? "completed" : "in_progress"),
+        command: item.command,
+      };
+      toolCallsById.set(item.id, tc);
+      if (item.type === "agent_message" && type === "item.completed") {
+        agentMessage = String(item.text ?? "");
+      }
+    } else if (type === "turn.completed") {
+      const u = event.usage;
+      if (u) {
+        usage = {
+          input: u.input_tokens ?? 0,
+          cached_input: u.cached_input_tokens ?? 0,
+          output: u.output_tokens ?? 0,
+          reasoning: u.reasoning_output_tokens ?? 0,
+        };
+      }
+    }
+  }
+
+  return {
+    threadId,
+    toolCalls: Array.from(toolCallsById.values()),
+    agentMessage,
+    usage,
+  };
+}
+
+function deriveToolName(item: any): string {
+  if (item.type === "command_execution") return "shell";
+  if (item.type === "agent_message") return "agent_message";
+  if (item.type === "image_gen" || item.type === "image_generation") return "image_gen";
+  if (typeof item.tool === "string") return item.tool;
+  return item.type ?? "unknown";
+}
+
+export function hasImageGenInvocation(toolCalls: ToolCall[]): boolean {
+  return toolCalls.some((tc) => tc.tool === "image_gen");
+}

baoyu-skills/packages/baoyu-codex-imagegen/src/spawn.ts

@@ -0,0 +1,81 @@
+import { spawn } from "node:child_process";
+import { writeFile, mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { GenError, type CodexRunResult } from "./types.ts";
+import { parseEventStream } from "./parser.ts";
+
+export interface SpawnInput {
+  instruction: string;
+  timeoutMs: number;
+  refImages?: string[];
+}
+
+export async function runCodexExec(input: SpawnInput): Promise<CodexRunResult> {
+  const start = Date.now();
+  const logDir = await mkdtemp(path.join(tmpdir(), "codex-imggen-"));
+  const rawLogPath = path.join(logDir, "stream.jsonl");
+
+  // --skip-git-repo-check: lets the wrapper run from non-git cwds
+  //   (e.g. /tmp, or a skill installed under ~/.claude/plugins/...).
+  //   Without it, codex refuses with "Not inside a trusted directory".
+  const args = [
+    "exec",
+    "--json",
+    "--sandbox",
+    "danger-full-access",
+    "--skip-git-repo-check",
+  ];
+  for (const img of input.refImages ?? []) {
+    args.push("--image", img);
+  }
+  args.push("-");
+
+  let timedOut = false;
+  const child = spawn("codex", args, { stdio: ["pipe", "pipe", "pipe"] });
+
+  let stdout = "";
+  let stderr = "";
+  child.stdout.on("data", (chunk) => {
+    stdout += chunk.toString();
+  });
+  child.stderr.on("data", (chunk) => {
+    stderr += chunk.toString();
+  });
+
+  child.stdin.write(input.instruction);
+  child.stdin.end();
+
+  const timer = setTimeout(() => {
+    timedOut = true;
+    child.kill("SIGTERM");
+    setTimeout(() => child.kill("SIGKILL"), 2000);
+  }, input.timeoutMs);
+
+  const exit = await new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve) => {
+    child.on("close", (code, signal) => resolve({ code, signal }));
+  });
+  clearTimeout(timer);
+
+  await writeFile(rawLogPath, stdout + (stderr ? `\n--- stderr ---\n${stderr}` : ""));
+
+  if (timedOut) {
+    throw new GenError("timeout", `codex exec exceeded ${input.timeoutMs}ms (log: ${rawLogPath})`);
+  }
+  if (exit.code !== 0) {
+    if (stderr.includes("command not found") || stderr.includes("not found: codex")) {
+      throw new GenError("codex_not_installed", "codex CLI not installed", false);
+    }
+    throw new GenError(
+      "spawn_failed",
+      `codex exec exited ${exit.code} signal=${exit.signal} (log: ${rawLogPath})`,
+    );
+  }
+
+  const parsed = parseEventStream(stdout);
+  return {
+    ...parsed,
+    rawLogPath,
+    durationMs: Date.now() - start,
+  };
+}

baoyu-skills/packages/baoyu-codex-imagegen/src/types.ts

@@ -0,0 +1,79 @@
+export interface CliOptions {
+  prompt: string;
+  promptFile: string | null;
+  outputPath: string;
+  aspect: string;
+  refImages: string[];
+  timeoutMs: number;
+  retries: number;
+  retryDelayMs: number;
+  cacheDir: string | null;
+  logFile: string | null;
+  verbose: boolean;
+}
+
+export interface ToolCall {
+  id: string;
+  tool: string;
+  status: string;
+  command?: string;
+}
+
+export interface TokenUsage {
+  input: number;
+  cached_input: number;
+  output: number;
+  reasoning: number;
+}
+
+export interface CodexRunResult {
+  threadId: string | null;
+  toolCalls: ToolCall[];
+  agentMessage: string | null;
+  usage: TokenUsage | null;
+  rawLogPath: string;
+  durationMs: number;
+}
+
+export interface GenerateResult {
+  status: "ok" | "error";
+  path: string;
+  bytes: number;
+  elapsed_seconds: number;
+  thread_id: string | null;
+  attempts: number;
+  cached: boolean;
+  usage: TokenUsage | null;
+  tool_calls: { tool: string; status: string }[];
+  error?: string;
+  error_kind?: ErrorKind;
+}
+
+export type ErrorKind =
+  | "codex_not_installed"
+  | "invalid_args"
+  | "prompt_file_missing"
+  | "spawn_failed"
+  | "timeout"
+  | "no_image_gen_tool_use"
+  | "output_missing"
+  | "invalid_png"
+  | "agent_refused"
+  | "lock_busy";
+
+export const RETRYABLE: ReadonlySet<ErrorKind> = new Set([
+  "spawn_failed",
+  "timeout",
+  "no_image_gen_tool_use",
+  "output_missing",
+  "invalid_png",
+  "agent_refused",
+]);
+
+export class GenError extends Error {
+  attempts?: number;
+  constructor(public kind: ErrorKind, message: string, public retryable?: boolean) {
+    super(message);
+    this.retryable = retryable ?? RETRYABLE.has(kind);
+  }
+}

baoyu-skills/packages/baoyu-codex-imagegen/src/validator.test.ts

@@ -0,0 +1,116 @@
+import { test, expect } from "bun:test";
+import { mkdtemp, writeFile, rm, mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { verifyOutput, verifyImageGenWasInvoked, hasImageGenEvidence } from "./validator.ts";
+import { parseEventStream } from "./parser.ts";
+import { GenError } from "./types.ts";
+
+const PNG_HEADER = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+// Condensed + sanitized capture of a REAL successful `codex exec --json` run
+// (thread 019edc1c…, 16:9 maple-tree image, single attempt). The image_gen
+// tool leaves NO stream item — success shows only reasoning / command_execution
+// / agent_message, and a `cp` from generated_images/<FULL-thread-id>/ig_*.png.
+const REAL_SUCCESS_STREAM = `{"type":"thread.started","thread_id":"019edc1c-e7a3-74f0-a276-13bea71d32d6"}
+{"type":"turn.started"}
+{"type":"item.completed","item":{"id":"r0","type":"reasoning"}}
+{"type":"item.completed","item":{"id":"r1","type":"reasoning"}}
+{"type":"item.completed","item":{"id":"m0","type":"agent_message","text":"Image generation is complete. Locating the newly produced image and copying it to the requested path."}}
+{"type":"item.started","item":{"id":"c0","type":"command_execution","command":"ls $CODEX_HOME/generated_images","status":"in_progress"}}
+{"type":"item.completed","item":{"id":"c0","type":"command_execution","command":"ls $CODEX_HOME/generated_images","exit_code":1,"status":"failed"}}
+{"type":"item.started","item":{"id":"c1","type":"command_execution","command":"cp $CODEX_HOME/generated_images/019edc1c-e7a3-74f0-a276-13bea71d32d6/ig_03eda661.png /Users/x/out/maple.png","status":"in_progress"}}
+{"type":"item.completed","item":{"id":"c1","type":"command_execution","command":"cp $CODEX_HOME/generated_images/019edc1c-e7a3-74f0-a276-13bea71d32d6/ig_03eda661.png /Users/x/out/maple.png","exit_code":0,"status":"completed"}}
+{"type":"item.completed","item":{"id":"m1","type":"agent_message","text":"{\\"status\\":\\"ok\\",\\"path\\":\\"/Users/x/out/maple.png\\",\\"bytes\\":1317377}"}}
+{"type":"turn.completed","usage":{"input_tokens":49489,"cached_input_tokens":34432,"output_tokens":2463,"reasoning_output_tokens":1990}}`;
+
+test("real success stream carries no image_gen item — gating on the stream alone would false-negative (#185)", () => {
+  const r = parseEventStream(REAL_SUCCESS_STREAM);
+  expect(r.threadId).toBe("019edc1c-e7a3-74f0-a276-13bea71d32d6");
+  // success path tools: reasoning / shell / agent_message — never image_gen
+  expect(r.toolCalls.map((tc) => tc.tool).sort()).toEqual([
+    "agent_message",
+    "agent_message",
+    "reasoning",
+    "reasoning",
+    "shell",
+    "shell",
+  ]);
+  expect(r.toolCalls.some((tc) => tc.tool === "image_gen")).toBe(false);
+  // filesystem evidence (PNG in this thread's dir) is what must let it through
+  expect(hasImageGenEvidence(r.toolCalls, true)).toBe(true);
+  // with no filesystem evidence and no stream item, it is rejected (the shortcut)
+  expect(hasImageGenEvidence(r.toolCalls, false)).toBe(false);
+});
+
+test("hasImageGenEvidence accepts a real image_gen stream item even without a dir PNG", () => {
+  expect(hasImageGenEvidence([{ id: "1", tool: "image_gen", status: "completed" }], false)).toBe(true);
+  expect(hasImageGenEvidence([{ id: "1", tool: "shell", status: "completed" }], false)).toBe(false);
+});
+
+test("verifyOutput passes for valid PNG", async () => {
+  const dir = await mkdtemp(path.join(tmpdir(), "cig-val-"));
+  try {
+    const p = path.join(dir, "good.png");
+    await writeFile(p, Buffer.concat([PNG_HEADER, Buffer.alloc(5000)]));
+    const r = await verifyOutput(p);
+    expect(r.bytes).toBeGreaterThan(1000);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("verifyOutput rejects missing file", async () => {
+  await expect(verifyOutput("/no/such/file.png")).rejects.toBeInstanceOf(GenError);
+});
+
+test("verifyOutput rejects tiny file", async () => {
+  const dir = await mkdtemp(path.join(tmpdir(), "cig-val-"));
+  try {
+    const p = path.join(dir, "tiny.png");
+    await writeFile(p, "tiny");
+    await expect(verifyOutput(p)).rejects.toThrow(/too small/);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("verifyOutput rejects non-PNG magic", async () => {
+  const dir = await mkdtemp(path.join(tmpdir(), "cig-val-"));
+  try {
+    const p = path.join(dir, "fake.png");
+    await writeFile(p, Buffer.concat([Buffer.from("GIF89a"), Buffer.alloc(5000)]));
+    await expect(verifyOutput(p)).rejects.toThrow(/not a valid PNG/);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("verifyImageGenWasInvoked false when no thread directory", async () => {
+  const orig = process.env.CODEX_HOME;
+  const tempHome = await mkdtemp(path.join(tmpdir(), "cig-home-"));
+  process.env.CODEX_HOME = tempHome;
+  try {
+    const r = await verifyImageGenWasInvoked("no-such-thread");
+    expect(r.ok).toBe(false);
+  } finally {
+    process.env.CODEX_HOME = orig;
+    await rm(tempHome, { recursive: true, force: true });
+  }
+});
+
+test("verifyImageGenWasInvoked true when PNG exists in thread dir", async () => {
+  const orig = process.env.CODEX_HOME;
+  const tempHome = await mkdtemp(path.join(tmpdir(), "cig-home-"));
+  process.env.CODEX_HOME = tempHome;
+  try {
+    const threadDir = path.join(tempHome, "generated_images", "thread-xyz");
+    await mkdir(threadDir, { recursive: true });
+    await writeFile(path.join(threadDir, "ig_abc.png"), Buffer.alloc(100));
+    const r = await verifyImageGenWasInvoked("thread-xyz");
+    expect(r.ok).toBe(true);
+  } finally {
+    process.env.CODEX_HOME = orig;
+    await rm(tempHome, { recursive: true, force: true });
+  }
+});

baoyu-skills/packages/baoyu-codex-imagegen/src/validator.ts

@@ -0,0 +1,56 @@
+import { stat, readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { GenError } from "./types.ts";
+import type { ToolCall } from "./types.ts";
+import { hasImageGenInvocation } from "./parser.ts";
+
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+export function codexHome(): string {
+  return process.env.CODEX_HOME ?? path.join(homedir(), ".codex");
+}
+
+export async function verifyImageGenWasInvoked(threadId: string | null): Promise<{ ok: boolean; reason?: string }> {
+  if (!threadId) return { ok: false, reason: "no thread id" };
+  const dir = path.join(codexHome(), "generated_images", threadId);
+  try {
+    const entries = await readdir(dir);
+    const pngs = entries.filter((e) => e.toLowerCase().endsWith(".png"));
+    if (pngs.length === 0) return { ok: false, reason: `no PNG in ${dir}` };
+    return { ok: true };
+  } catch (e: any) {
+    return { ok: false, reason: `cannot read ${dir}: ${e?.code ?? e?.message}` };
+  }
+}
+
+// Real evidence that image_gen ran in THIS thread. Codex's image_gen tool does
+// not surface as a stream item, so a successful run shows only reasoning/shell/
+// agent_message — `dirHasImage` (a PNG in this thread's generated_images dir) is
+// what proves it. The stream check is kept as a forward-compatible signal in
+// case a future Codex version emits the item. The #185 shortcut (copying an
+// unrelated history image, which lives under a different thread id) yields
+// neither, so it is correctly rejected.
+export function hasImageGenEvidence(toolCalls: ToolCall[], dirHasImage: boolean): boolean {
+  return dirHasImage || hasImageGenInvocation(toolCalls);
+}
+
+export async function verifyOutput(outputPath: string): Promise<{ bytes: number }> {
+  let s;
+  try {
+    s = await stat(outputPath);
+  } catch {
+    throw new GenError("output_missing", `Output file not created: ${outputPath}`);
+  }
+  if (s.size < 1000) {
+    throw new GenError("invalid_png", `Output file too small (${s.size} bytes)`);
+  }
+  const file = Bun.file(outputPath);
+  const head = new Uint8Array(await file.slice(0, 8).arrayBuffer());
+  for (let i = 0; i < PNG_MAGIC.length; i++) {
+    if (head[i] !== PNG_MAGIC[i]) {
+      throw new GenError("invalid_png", `Output is not a valid PNG (magic mismatch)`);
+    }
+  }
+  return { bytes: s.size };
+}