lp-product-ad-images 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evan Yan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,242 @@
+# lp-product-ad-images
+
+A [loopengine](https://github.com/loopengine-co/loopengine) ability: a
+tool for generating Google-Ads-ready product images from a real product
+photo, plus a skill that teaches an agent how to turn a request — a
+single image, a batch of one format, or a full 18-20 image asset set —
+into one shot list and one batch job, instead of only knowing how to
+plan one shape of batch.
+
+## What's in it
+
+- **Tool** — `generate_google_ad_images(product_image_url, shots, quality?)`.
+  Starts a **whole batch as one job**, not one job per shot: `shots` is
+  the full shot list for the request (one entry for a single-image
+  request, dozens for a full set), each with its own `shot_type`,
+  `scene_prompt`, and `aspect_ratios`. Returns immediately with
+  `{ job_id, status: "processing" }` instead of blocking until every
+  image is ready — a batch of dozens of shots can take several minutes,
+  and jobs run with bounded concurrency (`AD_IMAGE_CONCURRENCY`, default
+  4 at a time) rather than firing every generation at once. Poll
+  `check_google_ad_image_job({ job_id })` for progress and results:
+  - `{ status: "processing", progress, results }` — `results` fills in
+    incrementally as each (shot, ratio) unit finishes; check it even
+    mid-run, don't wait for the job to fully settle to see what's ready.
+  - `{ status: "done", progress, results }` — every unit succeeded.
+  - `{ status: "partial", progress, results }` — a mix; each `results`
+    entry has its own `status`/`path`/`error`, so successes and failures
+    are both visible per-unit, not collapsed into one job-level verdict.
+  - `{ status: "failed", progress, results }` — every unit failed (most
+    often a dead `product_image_url` or bad API key, since that applies
+    identically to every shot).
+
+  Each `results` entry is
+  `{ shot_index, shot_type, aspect_ratio, status, path?, width?, height?, error? }`.
+  `path` is where the file actually landed — a local filesystem path
+  (`AD_IMAGE_OUTPUT_DIR`, the default) or a `gs://bucket/object` URI
+  (`AD_IMAGE_STORAGE=gcs`) — never a URL or inline base64, so a full
+  multi-format batch doesn't blow the conversation's own context budget.
+  The background generation sends the real product photo to an
+  image-edit model along with a `shot_type`-specific instruction to keep
+  the product exactly as shown — not a text-only reinterpretation of it.
+  `shot_type` is one of:
+  - `product_only` — clean, product-alone shot.
+  - `lifestyle_product` — the product in realistic, plausible use.
+  - `cover_lifestyle` — an aspirational hero/cover shot; the product is
+    present but the scene carries the mood.
+
+  **Two providers**, chosen once via `AD_IMAGE_PROVIDER` (a deployment
+  setting, not a per-call argument):
+  - `openai` (default) — `gpt-image-1` by default, configurable via
+    `OPENAI_IMAGE_MODEL`. Generates at one of three fixed native pixel
+    sizes (landscape 1536×1024, square 1024×1024, portrait 1024×1536).
+  - `google` — Google's Gemini image models, aka "Nano Banana":
+    `gemini-3.1-flash-image` (**Nano Banana 2**, the default) or
+    `gemini-3-pro-image` (**Nano Banana Pro**, higher quality and cost)
+    via `GOOGLE_IMAGE_MODEL`. Supports a real `aspect_ratio` parameter
+    with ten presets — square and both portrait specs (`4:5`, `9:16`)
+    are exact presets here, so those need no cropping at all; only
+    landscape still gets a small trim from the nearest preset (`16:9`).
+
+  Each shot's `aspect_ratios` is an array, not a single value — but each
+  ratio in it is its own independent, separately generated image-edit
+  call, not cropped from a shared source, so a landscape and a square
+  version of "the same shot" can still drift in composition, lighting,
+  even framing, exactly as two separate shots would. Combining ratios
+  into one shot is a bookkeeping convenience only — each ratio is its
+  own billed generation regardless. Whichever provider is active, each
+  ratio's generation targets whichever native size/preset is closest to
+  it, then center-crops down to the exact ratio — never upscaled or
+  padded. Supports all three Google Ads image formats: `"1.91:1"`
+  (landscape, the default), `"1:1"` (square), and `"4:5"`/`"9:16"`
+  (portrait).
+
+  **Storage**, chosen once via `AD_IMAGE_STORAGE` (default `local`):
+  - `local` — writes each PNG under `AD_IMAGE_OUTPUT_DIR`; `path` in each
+    result is a real filesystem path.
+  - `gcs` — uploads each PNG to `AD_IMAGE_GCS_BUCKET` (optionally under
+    `AD_IMAGE_GCS_PREFIX`) instead; `path` is a `gs://bucket/object` URI.
+    Requires `npm install @google-cloud/storage` in your own project
+    (lazily imported, so `local` users never need it) and standard
+    Google Cloud auth (Application Default Credentials or
+    `GOOGLE_APPLICATION_CREDENTIALS`) — this ability doesn't take a
+    credentials env var of its own. Job-status files always stay local
+    under `AD_IMAGE_OUTPUT_DIR/.jobs/` regardless of this setting.
+- **Tool** — `check_google_ad_image_job(job_id)`. Reads back the status
+  of a job `generate_google_ad_images` started, from a JSON file under
+  `AD_IMAGE_OUTPUT_DIR/.jobs/` — read-only, safe to poll as often as
+  needed.
+- **Skill** — `product-google-ad-images`: how to size a request (one
+  image, a batch of one format, or a full set) into one `shots` array,
+  how to read a job's incremental progress and handle a `partial`
+  result, a suggested shot-type mix, how to write a `scene_prompt` that
+  actually varies shot to shot, and why the tool needs the real product
+  photo rather than a description of it.
+- **actauth rules** — `generate-google-ad-images-allowed` and
+  `check-google-ad-images-job-allowed`, both `decision: allow`.
+  Deliberately not gated behind a human `ask` — see the rule file's own
+  comments for why (this is a cost-per-shot tool, not a destructive one,
+  and the whole point is generating a full batch in one unattended run).
+
+## Install
+
+```
+npx loopengine add-ability lp-product-ad-images --agent <your-agent>
+```
+
+Then:
+
+1. Pick a provider and set its key (via the Admin UI's Environment tab,
+   or directly in `.env`):
+   - OpenAI (default, no `AD_IMAGE_PROVIDER` needed): `OPENAI_API_KEY`,
+     optionally `OPENAI_IMAGE_MODEL`.
+   - Google/Nano Banana: `AD_IMAGE_PROVIDER=google`, `GEMINI_API_KEY`,
+     optionally `GOOGLE_IMAGE_MODEL=gemini-3-pro-image` for Nano Banana
+     Pro instead of the default Nano Banana 2.
+   - Optionally `AD_IMAGE_OUTPUT_DIR` if you don't want generated
+     images (when storage is `local`) or job-status files (always)
+     landing under `./generated/ad-images`.
+   - Optionally `AD_IMAGE_STORAGE=gcs` plus `AD_IMAGE_GCS_BUCKET` (and
+     optionally `AD_IMAGE_GCS_PREFIX`) to upload images to GCS instead
+     of writing them locally.
+   - Optionally `AD_IMAGE_CONCURRENCY` (default `4`) to raise or lower
+     how many generations one batch job runs at once — tune it against
+     your actual provider rate limits.
+2. `npm install sharp` in your own project — this ability's tool uses
+   it for the center-crop step, for both providers and both storage
+   backends. If you set `AD_IMAGE_STORAGE=gcs`, also
+   `npm install @google-cloud/storage`. Installing an ability copies
+   its files in, it doesn't manage your project's own `package.json`,
+   so these are one-time manual steps (see loopengine's own
+   `ABILITIES.md` on why abilities are copied rather than imported).
+3. If using `local` storage, add wherever generated images land
+   (`AD_IMAGE_OUTPUT_DIR`, default `generated/ad-images`) to your
+   project's own `.gitignore` if you don't want to commit generated
+   creative. Either way, that same directory's `.jobs/` subdirectory
+   holds job-status files and is worth ignoring too.
+
+Every shot costs real money against whichever provider/model you've
+configured — see the actauth rule's own comment if you want a per-batch
+approval instead of the default unattended behavior.
+
+A job keeps running only as long as the agent process that started it
+stays alive — fine under a long-lived server (`npx loopengine
+dev`/`serve`), but a job started right before a short-lived, single-shot
+CLI invocation exits may never get the chance to finish.
+
+## Example requests
+
+The agent — not the end user — constructs this JSON: a user just says
+something like "generate a full set from this photo" in plain language,
+and the skill guides the agent through sizing that into a `shots` array
+and writing each `scene_prompt`. These are what the agent ends up
+calling `generate_google_ad_images` with, for a few different request
+shapes:
+
+**"Generate one landscape image with product_only style from this
+image: `https://cdn.example.com/mug.png`"**
+
+```json
+{
+  "product_image_url": "https://cdn.example.com/mug.png",
+  "shots": [
+    { "shot_type": "product_only", "scene_prompt": "on a clean marble countertop, soft natural window light, straight-on angle", "aspect_ratios": ["1.91:1"] }
+  ]
+}
+```
+
+**"Generate a batch of 6 landscape images"** (no style specified —
+the agent applies the shot-type mix itself)
+
+```json
+{
+  "product_image_url": "https://cdn.example.com/mug.png",
+  "shots": [
+    { "shot_type": "product_only", "scene_prompt": "flat lay, marble surface, overhead angle", "aspect_ratios": ["1.91:1"] },
+    { "shot_type": "product_only", "scene_prompt": "three-quarter angle on dark wood, studio lighting", "aspect_ratios": ["1.91:1"] },
+    { "shot_type": "lifestyle_product", "scene_prompt": "hand reaching for the mug on a kitchen counter, morning light", "aspect_ratios": ["1.91:1"] },
+    { "shot_type": "lifestyle_product", "scene_prompt": "mug mid-use on a desk beside a laptop, soft afternoon light", "aspect_ratios": ["1.91:1"] },
+    { "shot_type": "cover_lifestyle", "scene_prompt": "cozy reading nook, blanket, rain on the window, mug on the armrest", "aspect_ratios": ["1.91:1"] },
+    { "shot_type": "cover_lifestyle", "scene_prompt": "outdoor patio at sunrise, steam rising from the mug", "aspect_ratios": ["1.91:1"] }
+  ]
+}
+```
+
+**"Generate 4 portrait images at 9:16 for Performance Max"**
+
+```json
+{
+  "product_image_url": "https://cdn.example.com/mug.png",
+  "shots": [
+    { "shot_type": "product_only", "scene_prompt": "centered on a pedestal, vertical studio backdrop", "aspect_ratios": ["9:16"] },
+    { "shot_type": "lifestyle_product", "scene_prompt": "held upright in hand, tiled kitchen wall behind", "aspect_ratios": ["9:16"] },
+    { "shot_type": "cover_lifestyle", "scene_prompt": "tall bookshelf backdrop, mug on a side table, evening lamp light", "aspect_ratios": ["9:16"] },
+    { "shot_type": "cover_lifestyle", "scene_prompt": "standing on a windowsill, city skyline blurred behind", "aspect_ratios": ["9:16"] }
+  ]
+}
+```
+
+**"Generate a full Google Ads image set from this photo"** — still
+**one** call and one `job_id`, `shots` combining every format:
+
+```json
+{
+  "product_image_url": "https://cdn.example.com/mug.png",
+  "shots": [
+    { "shot_type": "product_only", "scene_prompt": "flat lay, marble surface", "aspect_ratios": ["1.91:1", "1:1"] },
+    { "shot_type": "product_only", "scene_prompt": "three-quarter angle, dark wood", "aspect_ratios": ["1.91:1", "1:1"] },
+    { "shot_type": "lifestyle_product", "scene_prompt": "hand reaching for it on a counter", "aspect_ratios": ["1.91:1", "1:1"] },
+    { "shot_type": "cover_lifestyle", "scene_prompt": "cozy reading nook, rain on the window", "aspect_ratios": ["1.91:1", "1:1"] },
+    { "shot_type": "product_only", "scene_prompt": "centered on a pedestal, vertical backdrop", "aspect_ratios": ["9:16"] },
+    { "shot_type": "lifestyle_product", "scene_prompt": "held upright, tiled kitchen wall", "aspect_ratios": ["9:16"] },
+    { "shot_type": "cover_lifestyle", "scene_prompt": "windowsill, city skyline blurred behind", "aspect_ratios": ["9:16"] }
+  ]
+}
+```
+(Shown abbreviated — a real full set repeats this pattern out to 18-20
+landscape+square shots and 12-15 portrait shots, ~30-35 entries total.)
+
+**"Generate 3 draft square images, doesn't need to be high quality"**
+
+```json
+{
+  "product_image_url": "https://cdn.example.com/mug.png",
+  "shots": [
+    { "shot_type": "product_only", "scene_prompt": "flat lay, plain white background", "aspect_ratios": ["1:1"] },
+    { "shot_type": "product_only", "scene_prompt": "three-quarter angle, light gray background", "aspect_ratios": ["1:1"] },
+    { "shot_type": "lifestyle_product", "scene_prompt": "on a desk beside a notebook", "aspect_ratios": ["1:1"] }
+  ],
+  "quality": "low"
+}
+```
+`quality` applies to every shot in the batch — there's no per-shot
+override.
+
+## Upgrading
+
+```
+npx loopengine upgrade-ability lp-product-ad-images --agent <your-agent>
+```
+
+See loopengine's own `ABILITIES.md` for how abilities, installs, and
+upgrades work in general.

package/actauth/rules.yml

@@ -0,0 +1,25 @@
+# decision: allow, not ask — deliberately, and worth being explicit about
+# why. This tool has no destructive real-world side effect the way
+# issue_refund/send_email do (see loopengine's own ABILITIES.md on
+# cost-vs-danger gating); the actual risk is pure API spend, and one call
+# can already cover a full 18-20+ shot batch (one job, many shots) —
+# gating it behind human approval would mean approving the whole batch's
+# cost up front in one shot anyway, not per-image, so "ask" here doesn't
+# buy finer-grained control the way it might look like it would.
+#
+# If you want a cost ceiling instead, the two real options: change this
+# rule's decision to "ask" (one approval per batch, not per image), or
+# don't grant this tool at all and generate in smaller, human-supervised
+# batches by calling it from outside a single unattended run.
+- name: generate-google-ad-images-allowed
+  scope: "*/*"
+  tool: generate_google_ad_images
+  decision: allow
+
+# Read-only status check on a job the rule above already allowed
+# starting — gating this one too would mean approving twice for the same
+# generation (once to start it, once to see if it's done).
+- name: check-google-ad-images-job-allowed
+  scope: "*/*"
+  tool: check_google_ad_image_job
+  decision: allow

package/loopengine.ability.json

@@ -0,0 +1,18 @@
+{
+  "loopengineVersion": "^0.1.24",
+  "tools": ["tools/generate_google_ad_images.ts", "tools/check_google_ad_image_job.ts"],
+  "skills": ["skills/product-google-ad-images"],
+  "actauth": "actauth/rules.yml",
+  "env": [
+    { "name": "AD_IMAGE_PROVIDER", "description": "Which image model actually generates: \"openai\" (default) or \"google\" (Nano Banana 2 / Nano Banana Pro). Only one provider's API key below is required, matching whichever you pick.", "secret": false },
+    { "name": "OPENAI_API_KEY", "description": "OpenAI API key — required when AD_IMAGE_PROVIDER=openai (the default).", "secret": true },
+    { "name": "OPENAI_IMAGE_MODEL", "description": "Which OpenAI image model to call. Defaults to gpt-image-1 if unset.", "secret": false },
+    { "name": "GEMINI_API_KEY", "description": "Google AI Studio / Gemini API key — required when AD_IMAGE_PROVIDER=google.", "secret": true },
+    { "name": "GOOGLE_IMAGE_MODEL", "description": "Which Gemini image model to call when AD_IMAGE_PROVIDER=google: gemini-3.1-flash-image (Nano Banana 2, the default) or gemini-3-pro-image (Nano Banana Pro, higher quality and cost).", "secret": false },
+    { "name": "AD_IMAGE_OUTPUT_DIR", "description": "Where job-status files always live, and where generated images are written when AD_IMAGE_STORAGE=local. Defaults to ./generated/ad-images if unset.", "secret": false },
+    { "name": "AD_IMAGE_STORAGE", "description": "Where generated images are saved: \"local\" (default, under AD_IMAGE_OUTPUT_DIR) or \"gcs\" (a Google Cloud Storage bucket). Job-status files stay local either way.", "secret": false },
+    { "name": "AD_IMAGE_GCS_BUCKET", "description": "GCS bucket name to upload generated images to — required when AD_IMAGE_STORAGE=gcs. Auth is via Application Default Credentials / GOOGLE_APPLICATION_CREDENTIALS, same as any other Google Cloud client.", "secret": false },
+    { "name": "AD_IMAGE_GCS_PREFIX", "description": "Optional object name prefix inside the GCS bucket (e.g. \"campaigns/summer/\"). Only used when AD_IMAGE_STORAGE=gcs.", "secret": false },
+    { "name": "AD_IMAGE_CONCURRENCY", "description": "Max number of image generations run at once within a single batch job. Defaults to 4 if unset — raise it for faster batches if your provider quota allows, lower it if you're hitting rate limits.", "secret": false }
+  ]
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "lp-product-ad-images",
+  "version": "3.0.0",
+  "description": "A loopengine ability: a generate_google_ad_images + check_google_ad_image_job tool pair — one job per whole batch (not per shot), bounded concurrency, incremental progress, OpenAI or Google Nano Banana image-edit, real product photo in, every ratio independently generated, saved locally or to GCS — plus a skill for sizing and generating anything from one image to a full Google Ads asset set.",
+  "license": "MIT",
+  "keywords": ["loopengine", "loopengine-ability", "google-ads", "product-photography", "image-generation", "openai", "nano-banana", "gemini", "gcs"],
+  "files": [
+    "loopengine.ability.json",
+    "tools",
+    "skills",
+    "actauth",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "sharp": "^0.35.0"
+  },
+  "optionalDependencies": {
+    "@google-cloud/storage": "^8.0.0"
+  }
+}

package/skills/product-google-ad-images/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: product-google-ad-images
+description: How to turn a request — one image, a batch of one format, or a full asset set — into one generate_google_ad_images call with a full shot list, how to poll check_google_ad_image_job for progress and results, plus the shot-type mix, how to write a good scene_prompt, and why every shot needs the real product photo.
+---
+
+# Product ad images
+
+`generate_google_ad_images` takes the **whole shot list for the request** —
+one or more shots, each its own `shot_type`/`scene_prompt`/`aspect_ratios` —
+in a single call, and tracks the entire thing as **one job**, not one job per
+shot. Every (shot, ratio) pair is still its own independent, real generation
+under the hood — two shots, or two ratios of the same shot, can still come
+out with different composition, lighting, even framing, exactly as separate
+calls would (image generation isn't deterministic) — grouping them into one
+call only changes how many `job_id`s you have to track, never how many
+billed generations happen or whether they match each other.
+
+The tool returns immediately with that one `job_id`, not the finished
+images — see "Starting the job and polling it" below. Planning the shot
+list itself (how many shots, what mix of `shot_type`s, what each
+`scene_prompt` says) is still your job before you call the tool — a good
+asset set is dozens of genuinely different compositions, not the same idea
+repeated, and the tool has no opinion on what makes a good shot list, only
+on how to execute one.
+
+## Sizing the request
+
+Requests come in at three different scopes — read which one you got before
+building the shot list, since each implies a different `shots` array:
+
+- **"Generate one/a single `<format>` image..."** (optionally "with `<style>`
+  style") — one call, `shots` has exactly one entry. Map the format to
+  `aspect_ratios` (table below), take `shot_type` from the wording if it
+  named one (default `product_only` if not), and write the `scene_prompt`
+  yourself if none was given — don't stop to demand a creative brief for a
+  single image; a reasonable scene beats no image.
+- **"Generate a batch (N) of `<format>` images..."** — one call, `shots` has
+  N entries, all at that one format's `aspect_ratios` only. A request
+  scoped to one format stays scoped to it — don't fold in the other formats
+  just because the full-set table below combines landscape+square
+  elsewhere. Apply the shot-type mix below across the N entries, and give
+  each its own distinct `scene_prompt`; N shots sharing one scene defeats
+  the point of a batch.
+- **"Generate a full Google Ads image set..."** (or "all formats",
+  "everything") — still **one call**: `shots` has every entry from both
+  rows of the table below combined — 18-20 entries at
+  `["1.91:1", "1:1"]` plus 12-15 entries at `["9:16"]` (or `["4:5"]`) — all
+  in the same `shots` array, all under the one job this call starts.
+
+Only ask the operator something before generating when it would actually
+change what you'd otherwise do — the product's category/audience if neither
+is obvious from the image or title and the shot mix would look wrong without
+it, or which portrait ratio (`4:5` vs `9:16`) if the request needs portrait
+and doesn't say which. Don't ask just to reconfirm a scope the request
+already stated plainly; when scope genuinely isn't stated at all, default to
+assuming the full set is wanted rather than guessing at a smaller one.
+
+| Say | `aspect_ratios` |
+| --- | --- |
+| "landscape" | `["1.91:1"]` |
+| "square" | `["1:1"]` |
+| "landscape and square" (or the full-set landscape row) | `["1.91:1", "1:1"]` |
+| "portrait" | `["9:16"]` or `["4:5"]` — ask only if both are plausible and the request doesn't say |
+
+## Starting the job and polling it
+
+One call starts the whole thing:
+
+```json
+{
+  "product_image_url": "https://...",
+  "shots": [
+    { "shot_type": "product_only", "scene_prompt": "...", "aspect_ratios": ["1.91:1", "1:1"] },
+    { "shot_type": "lifestyle_product", "scene_prompt": "...", "aspect_ratios": ["1.91:1", "1:1"] },
+    { "shot_type": "cover_lifestyle", "scene_prompt": "...", "aspect_ratios": ["9:16"] }
+  ]
+}
+```
+
+It returns immediately — `{ "job_id": "...", "status": "processing" }` —
+before any image exists. The real work (fetching the product photo once,
+then every shot's every ratio as its own generation, a few at a time in the
+background) keeps running after the call returns; a batch of dozens of
+shots can take several minutes. Poll
+`check_google_ad_image_job({ "job_id": "..." })` to track it:
+
+```json
+{
+  "status": "processing",
+  "progress": { "total": 36, "done": 22, "failed": 1, "processing": 13 },
+  "results": [
+    { "shot_index": 0, "shot_type": "product_only", "aspect_ratio": "1.91:1", "status": "done", "path": "...", "width": 1536, "height": 804 },
+    { "shot_index": 3, "shot_type": "lifestyle_product", "aspect_ratio": "1:1", "status": "failed", "error": "..." }
+  ]
+}
+```
+
+`results` fills in incrementally as each (shot, ratio) unit finishes — check
+it even while `status` is still `"processing"` to see what's already ready,
+rather than treating the whole job as opaque until the end. `status`
+settles once `progress.processing` hits 0:
+
+- `"done"` — every unit succeeded.
+- `"partial"` — a mix; some units are `"done"` (with a real `path`), some
+  are `"failed"` (with their own `error`). Don't wait for `"done"` before
+  reporting a `"partial"` batch — the images that succeeded are real and
+  usable; call out the failed ones by their `error` rather than silently
+  dropping them.
+- `"failed"` — every unit failed (most often a dead `product_image_url` or
+  a missing/invalid API key, since that failure applies identically to
+  every shot).
+
+This background work only continues for as long as the underlying agent
+process stays running — fine for a long-lived server (`npx loopengine
+dev`/`serve`), but a job started right before a short-lived, single-shot
+CLI invocation exits may never get the chance to finish.
+
+## Why image-edit, not text-to-image
+
+Every shot is a real edit of the actual `product_image_url` you pass in,
+not a text description of the product. Each shot-type prompt explicitly
+tells the model to keep the product exactly as shown in that reference
+image — same shape, colors, proportions, any printed text or logo. Do
+not try to describe the product yourself in `scene_prompt`; the
+reference image already establishes what it looks like, and repeating a
+text description of it just invites the model to drift from the real
+thing. `scene_prompt` is for the *scene* only: where it is, what's
+around it, the lighting, the mood.
+
+## The three formats
+
+Every format — landscape, square, portrait — is generated at its own
+native size/preset regardless of how shots are grouped, since generating at
+the ratio's own native canvas (rather than cropping it out of a different
+one) keeps the most composition and resolution for that ratio. There's no
+format-pairing rule: a shot with `aspect_ratios: ["1.91:1", "1:1"]`
+produces two files from **two independent generations**, not one shared
+photo cropped two ways — combining ratios into one shot just means one
+`shot_index`'s worth of results to read together, not a cost or
+consistency shortcut.
+
+| Format | Shots | `aspect_ratios` per shot | Generations (billed) | Files produced |
+| --- | --- | --- | --- | --- |
+| Landscape + Square (grouped per shot) | 18-20 | `["1.91:1", "1:1"]` | 36-40 (2 per shot) | 36-40 |
+| Portrait | 12-15 | `["9:16"]` or `["4:5"]` | 12-15 (1 per shot) | 12-15 |
+
+Google Ads uses both `4:5` and `9:16` for different placements — see
+"Sizing the request" above for when to ask which one versus just picking.
+
+## The shot-type mix
+
+Apply this mix separately to the landscape+square shots and to the
+portrait shots in the `shots` array — a reasonable starting split, adjust
+based on what the product and campaign actually call for, this isn't a
+fixed formula:
+
+- **`product_only`** (~35% of that format's count): clean, no ambiguity
+  about what's for sale. Vary the surface, background color/texture,
+  and camera angle across these — flat lay, three-quarter angle,
+  straight-on — so they don't read as the same shot repeated.
+- **`lifestyle_product`** (~35%): the product in real, plausible use.
+  Vary the setting and who/what is interacting with it (a hand reaching
+  for it, it sitting mid-use on a counter, etc.) — this is where most
+  of the "does someone actually want this" persuasion in an ad image
+  set comes from.
+- **`cover_lifestyle`** (~30%): the hero/cover shots — aspirational
+  scenes where the product is present but the mood of the scene is
+  doing the work, not a tight product close-up. These are what a
+  campaign's top-performing creative is usually built around.
+
+Ask the operator for the product's category and target audience first
+if neither is obvious from context — a kitchen gadget's lifestyle shots
+look nothing like a skincare product's, and a generic prompt produces
+generic (and less effective) ad creative either way.
+
+## Writing a good `scene_prompt`
+
+Be concrete about the same things a real photo brief would specify:
+
+- **Setting** — where, specifically (a sunlit kitchen counter, not just
+  "kitchen"; a gym locker room, not just "gym").
+- **Styling** — what else is in frame and why (props that make sense
+  for the product's actual use case, not generic clutter).
+- **Lighting/mood** — morning light, moody evening, bright and clean
+  studio — this does more to make 18-20 images look like a real,
+  varied set than almost anything else.
+- **Composition**, only if it matters for this shot — off-center,
+  close crop, negative space for ad text overlay.
+
+Keep each `scene_prompt` to one clear idea. A prompt trying to cover
+three different moods at once tends to produce a muddled result, not
+three ideas blended well.
+
+## After generating
+
+Once the job's `status` is `"done"` or `"partial"` (see "Starting the job
+and polling it" above for when to stop polling), each successful `results`
+entry's `path` is where the file actually landed — a local filesystem
+path under `AD_IMAGE_OUTPUT_DIR` by default, or a `gs://bucket/object`
+URI if the deployment has `AD_IMAGE_STORAGE=gcs` set — never a URL or
+inline image data either way. Report the full list of generated paths
+back, grouped by format (`aspect_ratio`) and then `shot_type` within
+each, so the operator can review the actual files rather than having to
+reconstruct what got made from one long `results` array. Call out any
+`failed` entries by their `error` rather than silently dropping them
+from the report.

package/tools/check_google_ad_image_job.ts

@@ -0,0 +1,40 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { ToolDefinition } from 'loopengine'
+
+// Mirrors generate_google_ad_images.ts's own jobPath — the two tools
+// can't share a module (add-ability copies each tool file standalone,
+// flattened, with no shared-module support), so this on-disk path
+// convention is the actual contract between them, not a shared function.
+function jobPath(outputDir: string, jobId: string): string {
+  return join(outputDir, '.jobs', `${jobId}.json`)
+}
+
+export const checkGoogleAdImageJob: ToolDefinition = {
+  name: 'check_google_ad_image_job',
+  description:
+    'Check the status of a job started by generate_google_ad_images — one job covers the whole batch (every shot, every ratio), not just one image. Returns {"status":"processing"|"done"|"partial"|"failed", "progress":{"total","done","failed","processing"}, "results":[...]}. results fills in incrementally as each shot/ratio finishes — check it even while status is still "processing" to see what\'s ready so far. "partial" means some units succeeded and some failed; check each result entry\'s own "status"/"error" to see which. Poll this rather than assuming the batch finished right away — a batch of many shots can take several minutes.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      job_id: {
+        type: 'string',
+        description: 'The job_id returned by generate_google_ad_images.',
+      },
+    },
+    required: ['job_id'],
+  },
+  execute: async (input) => {
+    const jobId = String(input.job_id)
+    const outputDir = process.env.AD_IMAGE_OUTPUT_DIR || './generated/ad-images'
+    try {
+      return await readFile(jobPath(outputDir, jobId), 'utf8')
+    } catch {
+      throw new Error(
+        `check_google_ad_image_job: no job found for job_id "${jobId}" — check the id, and that AD_IMAGE_OUTPUT_DIR hasn't changed since the job was started.`,
+      )
+    }
+  },
+  // Read-only — never writes anything, safe to run alongside anything else.
+  safe: true,
+}

package/tools/generate_google_ad_images.ts

@@ -0,0 +1,583 @@
+import { randomUUID } from 'node:crypto'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import sharp from 'sharp'
+import type { ToolDefinition } from 'loopengine'
+
+type ShotType = 'product_only' | 'lifestyle_product' | 'cover_lifestyle'
+
+interface ShotSpec {
+  shotType: ShotType
+  scenePrompt: string
+  aspectRatioSpecs: string[]
+  targetRatios: number[]
+}
+
+interface UnitResult {
+  shot_index: number
+  shot_type: ShotType
+  aspect_ratio: string
+  status: 'done' | 'failed'
+  // A local filesystem path (default, AD_IMAGE_STORAGE=local), or a
+  // gs://bucket/object URI when AD_IMAGE_STORAGE=gcs. Present only when
+  // status is "done".
+  path?: string
+  width?: number
+  height?: number
+  error?: string
+}
+
+interface JobRecord {
+  job_id: string
+  // "processing" until every unit (one shot × one of its aspect_ratios)
+  // has settled. "done" only if every unit succeeded, "failed" only if
+  // every unit failed, "partial" if it's a mix — a batch of 30+
+  // independent generations WILL sometimes have a handful fail without
+  // the rest being any less usable, so collapsing that into a binary
+  // done/failed would either hide real failures or throw away good
+  // images.
+  status: 'processing' | 'done' | 'partial' | 'failed'
+  created_at: string
+  finished_at?: string
+  progress: { total: number; done: number; failed: number; processing: number }
+  // Grows incrementally as each unit finishes — a caller polling mid-run
+  // already sees every unit that's settled so far, not just a bare
+  // "processing" flag with no visibility for however many minutes a big
+  // batch takes.
+  results: UnitResult[]
+}
+
+// Job files live alongside the images themselves, under the same
+// AD_IMAGE_OUTPUT_DIR — check_google_ad_image_job re-derives this same
+// path independently (it can't import this file; add-ability copies each
+// tool file standalone, flattened, with no shared-module support), so
+// the on-disk path convention here is the actual contract between the
+// two tools, not a shared function.
+function jobPath(outputDir: string, jobId: string): string {
+  return join(outputDir, '.jobs', `${jobId}.json`)
+}
+
+async function writeJob(outputDir: string, record: JobRecord): Promise<void> {
+  await mkdir(join(outputDir, '.jobs'), { recursive: true })
+  await writeFile(jobPath(outputDir, record.job_id), JSON.stringify(record, null, 2))
+}
+
+// Job status files always stay local regardless of AD_IMAGE_STORAGE —
+// they're small operational bookkeeping, not the generated creative
+// itself, so there's no reason to route them through GCS too.
+function validateStorageConfig(): void {
+  const storage = process.env.AD_IMAGE_STORAGE || 'local'
+  if (storage !== 'local' && storage !== 'gcs') {
+    throw new Error(`generate_google_ad_images: AD_IMAGE_STORAGE must be "local" or "gcs" — got "${storage}"`)
+  }
+  if (storage === 'gcs' && !process.env.AD_IMAGE_GCS_BUCKET) {
+    throw new Error('generate_google_ad_images: AD_IMAGE_GCS_BUCKET is not set (required when AD_IMAGE_STORAGE=gcs)')
+  }
+}
+
+// Saves one generated image and returns where it landed — a local
+// filesystem path by default, or a gs://bucket/object URI when
+// AD_IMAGE_STORAGE=gcs. @google-cloud/storage is imported lazily, not at
+// the top of the file, so installing it is only required for callers
+// who actually turn GCS storage on — everyone else (the local default)
+// never needs it, same reasoning as why sharp is a manual `npm install`
+// rather than something add-ability manages.
+async function saveImage(args: { buffer: Buffer; filename: string; outputDir: string }): Promise<string> {
+  const storage = process.env.AD_IMAGE_STORAGE || 'local'
+  if (storage === 'gcs') {
+    const bucketName = process.env.AD_IMAGE_GCS_BUCKET as string // validateStorageConfig already required this
+    const objectName = `${process.env.AD_IMAGE_GCS_PREFIX || ''}${args.filename}`
+    // Imported by a variable, not a string literal, so tsc treats this as
+    // `Promise<any>` instead of trying to resolve @google-cloud/storage's
+    // own types at compile time — installing it is only required at
+    // runtime for callers who actually set AD_IMAGE_STORAGE=gcs; everyone
+    // else (the local default) would otherwise fail `tsc` just for not
+    // having a package they never use.
+    const gcsModuleName = '@google-cloud/storage'
+    let gcs: any
+    try {
+      gcs = await import(gcsModuleName)
+    } catch {
+      throw new Error(
+        'generate_google_ad_images: AD_IMAGE_STORAGE=gcs requires the @google-cloud/storage package — npm install @google-cloud/storage in your own project.',
+      )
+    }
+    const client = new gcs.Storage()
+    await client.bucket(bucketName).file(objectName).save(args.buffer, { contentType: 'image/png' })
+    return `gs://${bucketName}/${objectName}`
+  }
+  await mkdir(args.outputDir, { recursive: true })
+  const outputPath = join(args.outputDir, args.filename)
+  await writeFile(outputPath, args.buffer)
+  return outputPath
+}
+
+// Keeps the actual product accurate across every shot instead of letting
+// the model reinterpret it from a text description each time — see
+// SKILL.md's own "Why image-edit, not text-to-image" note for the
+// reasoning. Each prefix constrains what the edit is allowed to change;
+// scene_prompt (the caller's own input) supplies the rest — the specific
+// setting, styling, and mood for this one shot.
+const SHOT_TYPE_PREFIX: Record<ShotType, string> = {
+  product_only:
+    'Photorealistic e-commerce product photography. Keep the product exactly as shown in the reference image — same shape, colors, proportions, and any printed text or logo, unchanged. No people, no hands, no added props beyond a simple surface and background. Clean studio lighting, sharp focus on the product, commercial ad quality.',
+  lifestyle_product:
+    'Photorealistic lifestyle product photography for an ad. Keep the product exactly as shown in the reference image — same shape, colors, proportions, and any printed text or logo, unchanged. Show it in realistic natural use — a hand, partial body, or its real-world setting interacting with it plausibly. The product stays clearly recognizable and is not obscured.',
+  cover_lifestyle:
+    'Photorealistic lifestyle hero/cover photography for an ad campaign. Keep the product exactly as shown in the reference image — same shape, colors, proportions, and any printed text or logo, unchanged. Aspirational, editorial setting and natural lighting; the product is present and identifiable but the scene itself carries the mood, not a tight product close-up.',
+}
+
+function parseAspectRatio(spec: string): number {
+  const match = spec.match(/^(\d+(?:\.\d+)?)\s*:\s*(\d+(?:\.\d+)?)$/)
+  if (!match) throw new Error(`generate_google_ad_images: aspect_ratio must look like "1.91:1" — got "${spec}"`)
+  const w = Number(match[1])
+  const h = Number(match[2])
+  if (w <= 0 || h <= 0) throw new Error(`generate_google_ad_images: aspect_ratio must be positive — got "${spec}"`)
+  return w / h
+}
+
+// Center-crop only, off whichever size a provider actually generated —
+// this ability's whole point is that the product itself must stay
+// exactly as generated, so cropping never resizes or distorts it, only
+// trims from whichever axis the target ratio is narrower on (often
+// nothing at all, when the target matches what was generated exactly,
+// like the square case usually does).
+function cropRectFor(
+  targetRatio: number,
+  source: { width: number; height: number },
+): { left: number; top: number; width: number; height: number } {
+  const { width: srcW, height: srcH } = source
+  const srcRatio = srcW / srcH
+
+  if (targetRatio >= srcRatio) {
+    // Target is wider (or equal) than the source — keep full width,
+    // crop height down.
+    const height = Math.round(srcW / targetRatio)
+    return { left: 0, top: Math.round((srcH - height) / 2), width: srcW, height: Math.min(height, srcH) }
+  }
+  // Target is narrower/taller than the source — keep full height, crop
+  // width down.
+  const width = Math.round(srcH * targetRatio)
+  return { left: Math.round((srcW - width) / 2), top: 0, width: Math.min(width, srcW), height: srcH }
+}
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40)
+}
+
+function ratioLabel(spec: string): string {
+  return spec.replace(/[^0-9]+/g, '-').replace(/^-+|-+$/g, '')
+}
+
+interface Generation {
+  buffer: Buffer
+  width: number
+  height: number
+}
+
+interface GenerationArgs {
+  productBytes: Buffer
+  productContentType: string
+  prompt: string
+  targetRatio: number
+  quality: string
+}
+
+// gpt-image-* only ever generates at a small fixed set of native pixel
+// sizes — there is no way to request an arbitrary ratio like Google
+// Ads' 1.91:1 landscape or 9:16 portrait specs directly. Every ratio
+// gets its own independent generation at whichever native size is
+// *closest* to it — never a shared landscape generation cropped down to
+// other ratios — since cropping a 9:16 frame out of a 1536x1024
+// landscape source would throw away most of the composition, and
+// generating at the native 1024x1536 portrait size instead keeps nearly
+// all of it. The same reasoning applies to every ratio, not just
+// portrait: two ratios generated independently are two independently
+// composed photos, never guaranteed to match, but each is the fullest,
+// least-cropped version of its own ratio.
+const OPENAI_NATIVE_SIZES = [
+  { width: 1536, height: 1024 }, // landscape
+  { width: 1024, height: 1024 }, // square
+  { width: 1024, height: 1536 }, // portrait
+] as const
+
+async function generateWithOpenAI({ productBytes, productContentType, prompt, targetRatio, quality }: GenerationArgs): Promise<Generation> {
+  const apiKey = process.env.OPENAI_API_KEY
+  if (!apiKey) throw new Error('generate_google_ad_images: OPENAI_API_KEY is not set (required when AD_IMAGE_PROVIDER=openai, the default)')
+  const model = process.env.OPENAI_IMAGE_MODEL || 'gpt-image-1'
+
+  const nativeSize = OPENAI_NATIVE_SIZES.reduce((best, size) => {
+    const bestDiff = Math.abs(best.width / best.height - targetRatio)
+    const diff = Math.abs(size.width / size.height - targetRatio)
+    return diff < bestDiff ? size : best
+  })
+
+  const form = new FormData()
+  form.set('model', model)
+  form.set('prompt', prompt)
+  form.set('size', `${nativeSize.width}x${nativeSize.height}`)
+  form.set('quality', quality)
+  form.set('image', new Blob([productBytes], { type: productContentType }), 'product')
+
+  const res = await fetch('https://api.openai.com/v1/images/edits', {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${apiKey}` },
+    body: form,
+  })
+  if (!res.ok) {
+    const detail = await res.text().catch(() => '')
+    throw new Error(`generate_google_ad_images: OpenAI image edit failed (HTTP ${res.status}) ${detail.slice(0, 300)}`)
+  }
+  const body = (await res.json()) as { data?: { b64_json?: string }[] }
+  const b64 = body.data?.[0]?.b64_json
+  if (!b64) throw new Error('generate_google_ad_images: OpenAI response carried no image data')
+
+  return { buffer: Buffer.from(b64, 'base64'), width: nativeSize.width, height: nativeSize.height }
+}
+
+// Google's Gemini image models ("Nano Banana") — gemini-3.1-flash-image
+// (Nano Banana 2) and gemini-3-pro-image (Nano Banana Pro) — support a
+// real aspect_ratio parameter with a fixed set of presets, unlike
+// OpenAI's three pixel sizes. Every ratio still gets its own independent
+// generation at whichever preset is nearest to it, same as the OpenAI
+// path — square and both portrait specs (4:5, 9:16) are exact presets
+// here so those need no crop at all; only 1.91:1 isn't itself a preset,
+// so 16:9 (the closest) still gets a small trim afterward.
+const GOOGLE_ASPECT_PRESETS = ['1:1', '16:9', '9:16', '3:2', '2:3', '3:4', '4:3', '4:5', '5:4', '21:9']
+
+function nearestGooglePreset(targetRatio: number): string {
+  return GOOGLE_ASPECT_PRESETS.reduce((best, preset) => {
+    const bestDiff = Math.abs(parseAspectRatio(best) - targetRatio)
+    const diff = Math.abs(parseAspectRatio(preset) - targetRatio)
+    return diff < bestDiff ? preset : best
+  })
+}
+
+// Walks the Interactions API's steps[].content[] shape for the first
+// image content block, rather than assuming a fixed index — a response
+// can interleave text/image blocks, and which position the image lands
+// in isn't a contract worth hardcoding against.
+function findImageData(body: unknown): string | undefined {
+  if (!body || typeof body !== 'object') return undefined
+  for (const value of Object.values(body as Record<string, unknown>)) {
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item && typeof item === 'object') {
+          const obj = item as Record<string, unknown>
+          if (obj.type === 'image' && typeof obj.data === 'string') return obj.data
+          const nested = findImageData(obj)
+          if (nested) return nested
+        }
+      }
+    } else if (value && typeof value === 'object') {
+      const nested = findImageData(value)
+      if (nested) return nested
+    }
+  }
+  return undefined
+}
+
+async function generateWithGoogle({ productBytes, productContentType, prompt, targetRatio, quality }: GenerationArgs): Promise<Generation> {
+  const apiKey = process.env.GEMINI_API_KEY
+  if (!apiKey) throw new Error('generate_google_ad_images: GEMINI_API_KEY is not set (required when AD_IMAGE_PROVIDER=google)')
+  const model = process.env.GOOGLE_IMAGE_MODEL || 'gemini-3.1-flash-image' // Nano Banana 2; set to gemini-3-pro-image for Nano Banana Pro
+
+  const aspectRatio = nearestGooglePreset(targetRatio)
+  const imageSize = quality === 'high' ? '2K' : '1K'
+
+  const res = await fetch('https://generativelanguage.googleapis.com/v1beta/interactions', {
+    method: 'POST',
+    headers: { 'x-goog-api-key': apiKey, 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      model,
+      input: [
+        { type: 'text', text: prompt },
+        { type: 'image', mime_type: productContentType, data: productBytes.toString('base64') },
+      ],
+      response_format: { type: 'image', mime_type: 'image/png', aspect_ratio: aspectRatio, image_size: imageSize },
+    }),
+  })
+  if (!res.ok) {
+    const detail = await res.text().catch(() => '')
+    throw new Error(`generate_google_ad_images: Google image edit failed (HTTP ${res.status}) ${detail.slice(0, 300)}`)
+  }
+  const body: unknown = await res.json()
+  const b64 = findImageData(body)
+  if (!b64) throw new Error('generate_google_ad_images: Google response carried no image data')
+
+  const buffer = Buffer.from(b64, 'base64')
+  // Read real dimensions off the actual bytes rather than assuming what
+  // a given aspect_ratio+image_size pair produces — the crop step below
+  // needs the truth, not a guess.
+  const meta = await sharp(buffer).metadata()
+  if (!meta.width || !meta.height) throw new Error('generate_google_ad_images: could not read generated image dimensions')
+
+  return { buffer, width: meta.width, height: meta.height }
+}
+
+interface WorkUnit {
+  shotIndex: number
+  shotType: ShotType
+  scenePrompt: string
+  aspectRatioSpec: string
+  targetRatio: number
+}
+
+// Runs `items` through `worker`, at most `limit` concurrently — a plain
+// `Promise.all` over every unit in a 30+ shot batch would fire that many
+// simultaneous provider calls at once and likely trip rate limits;
+// this instead keeps `limit` workers alive, each pulling the next
+// not-yet-started item off the shared list until it's exhausted.
+async function runWithConcurrency<T>(items: T[], limit: number, worker: (item: T) => Promise<void>): Promise<void> {
+  let next = 0
+  async function runOne(): Promise<void> {
+    while (next < items.length) {
+      const item = items[next++]
+      await worker(item)
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, runOne))
+}
+
+// The actual work — fetching the product photo once, then every shot's
+// every requested ratio as its own independent generation — all happens
+// here, after generate_google_ad_images has already returned a job_id to
+// the caller. Progress is persisted after each unit settles (not just
+// once at the very end), so a caller polling mid-run sees real partial
+// results instead of a bare "processing" flag for however long the
+// whole batch takes.
+async function runJob(args: {
+  jobId: string
+  outputDir: string
+  provider: string
+  productImageUrl: string
+  shots: ShotSpec[]
+  quality: string
+  concurrency: number
+  createdAt: string
+}): Promise<void> {
+  const { jobId, outputDir, provider, productImageUrl, shots, quality, concurrency, createdAt } = args
+
+  const results: UnitResult[] = []
+  const progress = { total: 0, done: 0, failed: 0, processing: 0 }
+  for (const shot of shots) progress.total += shot.aspectRatioSpecs.length
+  progress.processing = progress.total
+
+  // Writes are chained (not fired independently) so two units finishing
+  // close together can't race and leave the file with an earlier,
+  // less-complete snapshot overwriting a later one — each chained write
+  // reads `results`/`progress` fresh at the moment it actually runs, by
+  // which point every synchronous push that happened before it in
+  // program order is already reflected.
+  let writeChain: Promise<void> = Promise.resolve()
+  function persist(finished: boolean): void {
+    writeChain = writeChain.then(() =>
+      writeJob(outputDir, {
+        job_id: jobId,
+        status: !finished
+          ? 'processing'
+          : progress.failed === 0
+            ? 'done'
+            : progress.done === 0
+              ? 'failed'
+              : 'partial',
+        created_at: createdAt,
+        finished_at: finished ? new Date().toISOString() : undefined,
+        progress: { ...progress },
+        results: [...results],
+      }),
+    )
+  }
+
+  let productBytes: Buffer
+  let productContentType: string
+  try {
+    const productRes = await fetch(productImageUrl)
+    if (!productRes.ok) throw new Error(`could not fetch product_image_url (HTTP ${productRes.status})`)
+    productBytes = Buffer.from(await productRes.arrayBuffer())
+    productContentType = productRes.headers.get('content-type') || 'image/png'
+  } catch (err) {
+    // The product photo is shared by every unit — if it can't be
+    // fetched at all, every unit fails identically rather than each
+    // independently re-attempting (and re-failing) the same fetch.
+    const message = err instanceof Error ? err.message : String(err)
+    shots.forEach((shot, shotIndex) => {
+      for (const aspectRatioSpec of shot.aspectRatioSpecs) {
+        results.push({ shot_index: shotIndex, shot_type: shot.shotType, aspect_ratio: aspectRatioSpec, status: 'failed', error: message })
+        progress.failed++
+        progress.processing--
+      }
+    })
+    persist(true)
+    await writeChain
+    return
+  }
+
+  const generate = provider === 'google' ? generateWithGoogle : generateWithOpenAI
+  const stamp = Date.now()
+
+  const units: WorkUnit[] = []
+  shots.forEach((shot, shotIndex) => {
+    shot.aspectRatioSpecs.forEach((aspectRatioSpec, i) => {
+      units.push({ shotIndex, shotType: shot.shotType, scenePrompt: shot.scenePrompt, aspectRatioSpec, targetRatio: shot.targetRatios[i] })
+    })
+  })
+
+  await runWithConcurrency(units, concurrency, async (unit) => {
+    try {
+      const prompt = `${SHOT_TYPE_PREFIX[unit.shotType]}\n\nScene: ${unit.scenePrompt}`
+      const generation = await generate({ productBytes, productContentType, prompt, targetRatio: unit.targetRatio, quality })
+      // Still a crop, not a resize — the provider's native size/preset
+      // for this ratio is rarely pixel-exact (e.g. 1.91:1 has no native
+      // OpenAI size and no Google preset), so this trims the small
+      // remainder rather than stretching or padding.
+      const crop = cropRectFor(unit.targetRatio, generation)
+      const cropped = await sharp(generation.buffer).extract(crop).png().toBuffer()
+
+      const sceneSlug = slugify(unit.scenePrompt) || 'shot'
+      const filename = `${stamp}-shot${unit.shotIndex}-${unit.shotType}-${sceneSlug}-${ratioLabel(unit.aspectRatioSpec)}.png`
+      const path = await saveImage({ buffer: cropped, filename, outputDir })
+
+      results.push({
+        shot_index: unit.shotIndex,
+        shot_type: unit.shotType,
+        aspect_ratio: unit.aspectRatioSpec,
+        status: 'done',
+        path,
+        width: crop.width,
+        height: crop.height,
+      })
+      progress.done++
+    } catch (err) {
+      results.push({
+        shot_index: unit.shotIndex,
+        shot_type: unit.shotType,
+        aspect_ratio: unit.aspectRatioSpec,
+        status: 'failed',
+        error: err instanceof Error ? err.message : String(err),
+      })
+      progress.failed++
+    } finally {
+      progress.processing--
+      persist(progress.processing === 0)
+    }
+  })
+
+  // Best-effort: if even the final write fails (e.g. the output dir was
+  // removed mid-run), there's nothing further to do —
+  // check_google_ad_image_job will just report the job as not found.
+  await writeChain.catch(() => {})
+}
+
+export const generateGoogleAdImages: ToolDefinition = {
+  name: 'generate_google_ad_images',
+  description:
+    'Start a whole batch of Google Ads product photo shoots — one or more shots, each with its own shot_type/scene_prompt/aspect_ratios — as ONE job covering the entire request, not one job per shot. Every (shot, ratio) pair is its own independent, separately generated image-edit call, run with bounded concurrency in the background. Returns immediately with a job_id and status "processing"; poll check_google_ad_image_job with that job_id for progress and results — it fills in incrementally as each shot finishes, so a big batch is never a black box mid-run. For a single image, pass one shot with one ratio.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      product_image_url: {
+        type: 'string',
+        description: 'Publicly reachable URL of the real product photo every shot in this batch is based on.',
+      },
+      shots: {
+        type: 'array',
+        minItems: 1,
+        items: {
+          type: 'object',
+          properties: {
+            shot_type: {
+              type: 'string',
+              enum: ['product_only', 'lifestyle_product', 'cover_lifestyle'],
+              description:
+                'product_only: clean product-alone shot. lifestyle_product: product shown in realistic use. cover_lifestyle: aspirational hero/cover shot, product present but not the sole focus.',
+            },
+            scene_prompt: {
+              type: 'string',
+              description:
+                'The specific setting, styling, mood, and composition for this one shot (e.g. "on a rustic wooden table with soft morning light, a coffee cup beside it"). Describe the scene only — do not restate what the product looks like, the reference photo already establishes that.',
+            },
+            aspect_ratios: {
+              type: 'array',
+              items: { type: 'string' },
+              description:
+                'One or more target ratios as "W:H" for this shot, each generated independently — not cropped from a shared source. Default ["1.91:1"]. Google Ads\' three standard formats: "1.91:1" (landscape), "1:1" (square), "4:5" or "9:16" (portrait).',
+            },
+          },
+          required: ['shot_type', 'scene_prompt'],
+        },
+        description: 'The full shot list for this batch — one entry per shot. A single-image request is just one entry.',
+      },
+      quality: {
+        type: 'string',
+        enum: ['low', 'medium', 'high'],
+        description: 'Generation quality, also the main cost lever, applied to every shot in this batch — default "high" for ad-ready output.',
+      },
+    },
+    required: ['product_image_url', 'shots'],
+  },
+  execute: async (input) => {
+    const outputDir = process.env.AD_IMAGE_OUTPUT_DIR || './generated/ad-images'
+    // Which model actually does the generation — OpenAI's gpt-image-*
+    // (default) or Google's Nano Banana 2 / Nano Banana Pro. This is a
+    // deployment-wide choice, not a per-call one: set once via env, not
+    // exposed as a tool argument, since an operator picks a provider for
+    // cost/quality/quota reasons that don't vary shot to shot.
+    const provider = process.env.AD_IMAGE_PROVIDER || 'openai'
+    if (provider !== 'openai' && provider !== 'google') {
+      throw new Error(`generate_google_ad_images: AD_IMAGE_PROVIDER must be "openai" or "google" — got "${provider}"`)
+    }
+    validateStorageConfig()
+
+    const concurrencyRaw = Number(process.env.AD_IMAGE_CONCURRENCY || '4')
+    const concurrency = Number.isFinite(concurrencyRaw) && concurrencyRaw > 0 ? Math.floor(concurrencyRaw) : 4
+
+    const productImageUrl = String(input.product_image_url)
+    const shotsInput = Array.isArray(input.shots) ? input.shots : []
+    if (shotsInput.length === 0) throw new Error('generate_google_ad_images: shots must be a non-empty array')
+
+    const shots: ShotSpec[] = shotsInput.map((raw, i) => {
+      const shotObj = (raw ?? {}) as Record<string, unknown>
+      const shotType = String(shotObj.shot_type) as ShotType
+      if (!(shotType in SHOT_TYPE_PREFIX)) {
+        throw new Error(`generate_google_ad_images: shots[${i}].shot_type must be one of ${Object.keys(SHOT_TYPE_PREFIX).join(', ')} — got "${shotType}"`)
+      }
+      if (typeof shotObj.scene_prompt !== 'string' || !shotObj.scene_prompt) {
+        throw new Error(`generate_google_ad_images: shots[${i}].scene_prompt is required`)
+      }
+      const aspectRatioSpecs =
+        Array.isArray(shotObj.aspect_ratios) && shotObj.aspect_ratios.length > 0 ? shotObj.aspect_ratios.map(String) : ['1.91:1']
+      const targetRatios = aspectRatioSpecs.map(parseAspectRatio) // throws synchronously on a bad ratio spec, at any shot index
+      return { shotType, scenePrompt: shotObj.scene_prompt, aspectRatioSpecs, targetRatios }
+    })
+    const quality = typeof input.quality === 'string' && input.quality ? input.quality : 'high'
+
+    const jobId = randomUUID()
+    const createdAt = new Date().toISOString()
+    const total = shots.reduce((n, shot) => n + shot.aspectRatioSpecs.length, 0)
+    await writeJob(outputDir, {
+      job_id: jobId,
+      status: 'processing',
+      created_at: createdAt,
+      progress: { total, done: 0, failed: 0, processing: total },
+      results: [],
+    })
+
+    // Not awaited — see runJob's own comment for why. Errors inside it
+    // are caught per-unit and written into the job record itself, never
+    // thrown here, since by this point the caller has already moved on.
+    void runJob({ jobId, outputDir, provider, productImageUrl, shots, quality, concurrency, createdAt })
+
+    return JSON.stringify({ job_id: jobId, status: 'processing' })
+  },
+  // Each call is independent — writes its own uniquely-named job file
+  // and (once each unit's background work finishes) image file(s),
+  // reads nothing shared, no risk of two calls conflicting — so it's
+  // fine in ToolLane's parallel lane despite not being "read-only" in
+  // the usual sense that flag is for.
+  safe: true,
+}