openclacky 1.2.8 → 1.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '080944ed788d584c01c97ba01a27a63b2d2ab341ecf88140a63424460dcb105e'
-  data.tar.gz: 3c2b51bde81be7c18b3384297609f0163d5e6ed40de7121185a4cc374e576f10
+  metadata.gz: b2060d694267d0947681785d2e2ffe730d0b241a9ac2ec68e218eb037478bf27
+  data.tar.gz: 0b3e301010e16752da0bd64a9603b06010c2a23c5bd81884c7719d74f8f1bd67
 SHA512:
-  metadata.gz: c21e88b443f05ae75979ca4b890142ad15283382ba39fba434a3478f9f3a7f08b13c50fd5760d128662dee26374d69695e6b35e0d25e8f92cdad7351517f564f
-  data.tar.gz: fd37b0b3d64bc68ac777c84beef22be2c6f10c260b5e959273b953aae739c1f176bce7dae5c01c738acb332c5eded97eb973250f51576accbce58ee5f9e12139
+  metadata.gz: 386e2359d904b9a6bc81e56429cd585aaef59b7174f5dbc93e51cdd2bf97df703fd8145910759f50427632fcc90a307ed3ec6b19e48f0230d7e0c39987d3e7a8
+  data.tar.gz: 15413b83259ef7a39acac101597149cbf2144473da691d885f14d3b271076399da14c924db19201a1b99d8bf264542b56f3619b6cb6b903dfdac462e46f15a97

data/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.9] - 2026-06-01
+
+### Added
+- Image generation support via model tool calls
+- Startup telemetry now reports launch source for better usage analytics
+
+### Improved
+- Feishu channel setup simplified with Agent App flow — fewer manual steps and no redirect URL config needed
+
+### Fixed
+- Network region detection hardened with CDN fallback to handle edge cases and improve reliability
+
 ## [1.2.8] - 2026-06-01
 
 ### Added

data/lib/clacky/agent_config.rb

@@ -318,7 +318,9 @@ module Clacky
         end
       end
 
-      new(**constructor_args)
+      instance = new(**constructor_args)
+      instance.derive_media_models!
+      instance
     end
 
     # Auto-injection of provider-preset lite models into @models has been
@@ -585,12 +587,94 @@ module Clacky
       }.compact
     end
 
-    # Find model by type (default or lite)
-    # Returns the model hash or nil if not found
+    # Find model by type (default or lite or media kind)
+    # Returns the model hash or nil if not found.
+    # For media kinds (image/video/audio): explicit user-configured (custom)
+    # entries win; otherwise an auto-derived virtual entry is returned
+    # based on the default model's provider — mirroring how lite is
+    # virtually derived via #lite_model_config_for_current.
     def find_model_by_type(type)
+      kind = type.to_s
+      if Clacky::Providers::MEDIA_KINDS.include?(kind)
+        custom = @models.find { |m| m["type"] == kind }
+        return custom if custom
+        return derive_media_model(kind)
+      end
       @models.find { |m| m["type"] == type }
     end
 
+    private def derive_media_model(kind)
+      default = find_model_by_type("default")
+      return nil unless default
+
+      provider_id = Clacky::Providers.resolve_provider(
+        base_url: default["base_url"],
+        api_key:  default["api_key"]
+      )
+      return nil unless provider_id
+
+      model_name = Clacky::Providers.default_media_model(provider_id, kind)
+      return nil if model_name.nil? || model_name.to_s.empty?
+
+      {
+        "model"         => model_name,
+        "base_url"      => default["base_url"],
+        "api_key"       => default["api_key"],
+        "type"          => kind,
+        "auto_injected" => true
+      }
+    end
+
+    # Kept as a no-op for backward compatibility. Media auto entries are
+    # now derived virtually on read; nothing is materialized into @models.
+    def derive_media_models!
+      @models.reject! { |m| m["auto_injected"] && Clacky::Providers::MEDIA_KINDS.include?(m["type"].to_s) }
+    end
+
+    # Returns the configured/derived media model entry for `kind`, plus a
+    # hint about its source. UI uses this to render the tri-state control.
+    # @param kind [String] one of "image" / "video" / "audio"
+    # @return [Hash{String=>Object}] keys:
+    #   "configured" [Boolean]            — anything available?
+    #   "source"     [String]             — "off" | "auto" | "custom"
+    #   "model"      [String, nil]
+    #   "base_url"   [String, nil]
+    #   "provider"   [String, nil]        — provider id
+    #   "available"  [Array<String>]      — auto-source candidates from preset
+    def media_state(kind)
+      kind = kind.to_s
+      custom = @models.find { |m| m["type"] == kind }
+      auto   = custom ? nil : derive_media_model(kind)
+      entry  = custom || auto
+
+      provider_id = if entry
+                      Clacky::Providers.resolve_provider(
+                        base_url: entry["base_url"],
+                        api_key:  entry["api_key"]
+                      )
+                    end
+
+      available_provider_id = if custom
+                                provider_id
+                              else
+                                default = find_model_by_type("default")
+                                default && Clacky::Providers.resolve_provider(
+                                  base_url: default["base_url"],
+                                  api_key:  default["api_key"]
+                                )
+                              end
+      available = available_provider_id ? Clacky::Providers.media_models(available_provider_id, kind) : []
+
+      {
+        "configured" => !entry.nil?,
+        "source"     => custom ? "custom" : (auto ? "auto" : "off"),
+        "model"      => entry && entry["model"],
+        "base_url"   => entry && entry["base_url"],
+        "provider"   => provider_id,
+        "available"  => available
+      }
+    end
+
     # Find model by composite key (model name + base_url).
     # Used when restoring a session to match its original model without relying
     # on the runtime-only id (which changes on every process restart).
@@ -896,14 +980,14 @@ module Clacky
       Clacky::Providers.supports?(provider_id, capability, model_name: m["model"])
     end
 
-    # Set a model's type (default or lite)
-    # Ensures only one model has each type
+    # Set a model's type (default, lite, image, video, or audio).
+    # At most one model carries each type at a time.
     # @param index [Integer] the model index
-    # @param type [String, nil] "default", "lite", or nil to remove type
+    # @param type [String, nil] type tag, or nil to clear
     # Returns true if successful
     def set_model_type(index, type)
       return false if index < 0 || index >= @models.length
-      return false unless ["default", "lite", nil].include?(type)
+      return false unless ["default", "lite", "image", "video", "audio", nil].include?(type)
 
       if type
         # Remove type from any other model that has it

data/lib/clacky/client.rb

@@ -561,10 +561,14 @@ module Clacky
     # ── Error handling ────────────────────────────────────────────────────────
 
     def handle_test_response(response)
-      return { success: true } if response.status == 200
+      return { success: true, status: response.status } if response.status == 200
 
       error_body = JSON.parse(response.body) rescue nil
-      { success: false, error: extract_error_message(error_body, response.body) }
+      {
+        success: false,
+        status:  response.status,
+        error:   extract_error_message(error_body, response.body)
+      }
     end
 
     def raise_error(response)

data/lib/clacky/default_skills/channel-manager/SKILL.md

@@ -99,128 +99,51 @@ Ask:
 
 ### Feishu setup
 
-#### Step 1 — Try automated setup (script)
+Feishu now offers a one-click **Agent App** (智能体应用) that auto-configures all
+required permissions, events, and publishing for you — no Bot capability toggle,
+no permission JSON, no event subscription, no version/release steps. Just create
+the app and copy the credentials. The connection mode is unchanged (long
+connection / WebSocket), handled entirely by the server.
 
-Run the setup script (full path is available in the supporting files list above):
-```bash
-ruby "SKILL_DIR/feishu_setup.rb"
-```
-**Important**: call `terminal` with `timeout: 180` — the script may wait up to 90s for a WebSocket connection in Phase 4.
-
-**If exit code is 0:**
-- The script completed successfully.
-- Config is already written to `~/.clacky/channels.yml`.
-- Tell the user: "✅ Feishu channel configured automatically! The channel is ready."
-- **Skip Step 2 (manual fallback) and continue to Step 3.**
-
-**If exit code is non-0:**
-- Check stdout for the error message.
-- **If the error contains "Browser not configured" or "browser tool":**
-  - Tell the user: "The browser tool is not configured yet. Let me help you set it up first..."
-  - Invoke the `browser-setup` skill: `invoke_skill("browser-setup", "setup")`.
-  - After browser-setup completes, tell the user: "Browser is ready! Let me retry the Feishu setup..."
-  - **Retry the script** (same command, same timeout). If it succeeds this time, stop. If it fails again, check the new error and proceed accordingly.
-- **If the error contains "No cookies found" or "Please log in":**
-  - Open Feishu login page using browser tool:
-    ```
-    browser(action="navigate", url="https://open.feishu.cn/app")
-    ```
-  - Tell the user: "I've opened Feishu in your browser. Please log in, then reply 'done'."
-  - Wait for "done".
-  - **Retry the script** (same command, same timeout). Repeat this login-wait-retry loop up to **3 times total**.
-    - If any attempt succeeds (exit code 0), stop — setup is complete.
-    - If an attempt fails with a **different** error (not a login error), break out of the loop and continue to Step 2.
-    - If all 3 attempts fail with login errors, tell the user: "Automated setup was unable to detect a Feishu login after 3 attempts. Switching to guided setup..." and continue to Step 2.
-- **Otherwise (non-login, non-browser error):**
-  - Tell the user: "Automated setup encountered an issue: `<error message>`. Switching to guided setup..."
-  - Continue to Step 2 (manual flow) below.
-
----
-
-#### Step 2 — Manual guided setup (fallback)
-
-Only reach here if the automated script failed.
-
-##### Phase 1 — Open Feishu Open Platform
-
-1. Navigate: `open https://open.feishu.cn/app`. Pass `isolated: true`.
-2. If a login page or QR code is shown, tell the user to log in and wait for "done".
-3. Confirm the app list is visible.
-
-##### Phase 2 — Create a new app
-
-4. **Always create a new app** — do NOT reuse existing apps. Guide the user: "Click 'Create Enterprise Self-Built App', fill in name (e.g. Open Clacky) and description (e.g. AI assistant powered by openclacky), then submit. Reply done." Wait for "done".
-
-##### Phase 3 — Enable Bot capability
-
-5. Feishu opens Add App Capabilities by default after creating an app. Guide the user: "Find the Bot capability card and click the Add button next to it, then reply done." Wait for "done".
-
-##### Phase 4 — Get credentials
-
-6. Navigate to Credentials & Basic Info in the left menu.
-7. Guide the user: "Copy App ID and App Secret, then paste here. Reply with: App ID: xxx, App Secret: xxx" Wait for the reply. Parse `app_id` and `app_secret`.
+#### Step 1 — Open the Agent App creation page
 
-##### Phase 5 — Add message permissions
+1. Navigate: `open https://open.feishu.cn/page/launcher?from=backend_oneclick`. Pass `isolated: true`. If the browser is not configured (the `open` call fails), just give the user the URL and ask them to open it manually in any browser — the rest of the flow is fully manual and does not need browser automation.
+2. If a login page or QR code is shown, tell the user to scan/log in and wait for "done".
 
-8. Navigate to Permission Management and open the bulk import dialog.
-9. Guide the user: "In the bulk import dialog, clear the existing example first (select all, delete), then paste the following JSON. Reply done." Wait for "done". Do NOT try to clear or edit via browser — user does it.
+#### Step 2 — Create the Agent App
 
-```json
-{
-  "scopes": {
-    "tenant": [
-      "im:message",
-      "im:message.p2p_msg:readonly",
-      "im:message:send_as_bot"
-    ],
-    "user": []
-  }
-}
-```
+3. After login, the page lands on **创建飞书智能体应用 (Create Feishu Agent App)**.
+   Guide the user: "Enter an app name (e.g. Open Clacky), then click **立即创建 (Create Now)**. Reply done."
+   (The avatar is auto-assigned at random and can be changed anytime — it does not affect setup.)
+   Wait for "done".
 
-##### Phase 6 — Configure event subscription (Long Connection)
+#### Step 3 — Copy credentials
 
-**CRITICAL**: Feishu requires the long connection to be established *before* you can save the event config. The platform shows "No application connection detected" until `clacky server` is running and connected.
+4. The page jumps to **创建成功 (Created Successfully)**, showing `App ID` and `App Secret`.
+   The Secret is masked by default. Guide the user: "Click the eye icon next to **App Secret** to reveal it,
+   then copy both values and paste here. Reply with: App ID: xxx, App Secret: xxx"
+   Wait for the reply. Parse `app_id` (starts with `cli_`) and `app_secret`. Trim whitespace and
+   make sure the two values are not swapped.
 
-10. **Apply config and establish connection** — Run:
-    ```bash
-    curl -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/feishu \
-      -H "Content-Type: application/json" \
-      -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>","domain":"https://open.feishu.cn"}'
-    ```
-    **CRITICAL: This curl call is the ONLY way to save credentials. NEVER write `~/.clacky/channels.yml` or any file under `~/.clacky/channels/` directly. The server API handles persistence and hot-reload.**
-11. **Wait for connection** — Poll until log shows `[feishu-ws] WebSocket connected ✅`:
-    ```bash
-    for i in $(seq 1 20); do
-      grep -q "\[feishu-ws\] WebSocket connected" ~/.clacky/logger/clacky-$(date +%Y-%m-%d).log 2>/dev/null && echo "CONNECTED" && break
-      sleep 1
-    done
-    ```
-12. **Configure events** — Guide the user: "In Events & Callbacks, select 'Long Connection' mode. Click Save. Then click Add Event, search `im.message.receive_v1`, select it, click Add. Reply done." Wait for "done".
+#### Step 4 — Save credentials
 
-##### Phase 7 — Publish the app
-
-13. Navigate to Version Management & Release. Guide the user: "Create a new version (e.g. 1.0.0, note: Initial release for Open Clacky) and publish it. Reply done." Wait for "done".
-
-##### Phase 8 — Validate
-
-```bash
-curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
-  -H "Content-Type: application/json" \
-  -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>"}'
-```
-
-Check for `"code":0`. On success: continue to Step 3 (below).
-
-##### Phase 9 — done
+5. Run:
+   ```bash
+   curl -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/feishu \
+     -H "Content-Type: application/json" \
+     -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>","domain":"https://open.feishu.cn"}'
+   ```
+   **CRITICAL: This curl call is the ONLY way to save credentials. NEVER write `~/.clacky/channels.yml`
+   or any file under `~/.clacky/channels/` directly. The server API handles persistence, hot-reload,
+   and establishing the long connection.**
 
-Step 2 ends here. **Continue to Step 3.**
+On success: tell the user "✅ Feishu channel configured!" and **continue to Step 5 (Feishu CLI)**.
 
 ---
 
-#### Step 3 — Optional: install Feishu CLI
+#### Step 5 — Optional: install Feishu CLI
 
-Reach here from either Step 1 success or end of Step 2. Read `app_id` and `app_secret` from `~/.clacky/channels.yml` (under `channels.feishu`) for the install commands below.
+Reach here after the channel is configured (Step 4 succeeded). Read `app_id` and `app_secret` from `~/.clacky/channels.yml` (under `channels.feishu`) for the install commands below.
 
 Call `request_user_feedback`:
 
@@ -269,7 +192,7 @@ When `lark-cli auth login` returns successfully, tell the user:
 
 ### WeCom setup
 
-1. Navigate: `open https://work.weixin.qq.com/wework_admin/frame#/aiHelper/create`. Pass `isolated: true`.
+1. Navigate: `open https://work.weixin.qq.com/wework_admin/frame#/aiHelper/create`. Pass `isolated: true`. If the browser is not configured (the `open` call fails), just give the user the URL and ask them to open it manually in any browser — the rest of the flow is fully manual and does not need browser automation.
 2. If a login page or QR code is shown, tell the user to log in and wait for "done".
 3. Guide the user: "Scroll to the bottom of the right panel and click 'API mode creation'. Reply done." Wait for "done".
 4. Guide the user: "Click 'Add' next to 'Visible Range'. Select the top-level company node. Click Confirm. Reply done." Wait for "done".

data/lib/clacky/default_skills/media-gen/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: media-gen
+description: 'Generate images (and later videos / audio) inside the current task. Use this skill whenever the user asks to create, generate, or produce a picture / image / illustration / cover / poster / icon / artwork — including phrases like 生成图片, 画一张, 做封面, 来张配图, generate image, make a picture, draw, create artwork, design a cover. Also use when building documents (slides, PPT, posters, marketing pages, README hero shots) where an image is needed inline. Routes calls through the local Clacky HTTP server, which uses the user-configured `type=image` model — you do NOT need to know which provider; the server handles it.'
+disable-model-invocation: false
+user-invocable: true
+---
+
+# media-gen
+
+Generate images on demand by calling the local Clacky HTTP server, which dispatches to whichever image-generation model the user configured (`type=image` in their model settings).
+
+## Endpoint
+
+```
+POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/media/image
+GET  http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/media/types
+```
+
+## Step 1 — Verify a backend is configured
+
+Before generating anything, confirm the user has a `type=image` model set up:
+
+```bash
+curl -s http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/media/types
+```
+
+If the response shows `image.configured = false`, stop and tell the user:
+
+> 还没有配置生图模型。请打开 Clacky 设置页 → 添加模型 → 类型选 `image`（推荐 `or-gemini-3-pro-image` 或 `or-gpt-image-1`）。配好后再让我生图。
+
+Do NOT try to fall back to `terminal` + a hand-written `curl https://api.openai.com/...` — that bypasses the user's configured backend and won't be billed correctly.
+
+## Step 2 — Generate the image
+
+```bash
+curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/media/image \
+  -H "Content-Type: application/json" \
+  -d '{
+    "prompt": "A clean, modern hero illustration for a tech startup landing page. Soft gradient background, abstract geometric shapes in blue and purple, minimal style, 4K quality.",
+    "aspect_ratio": "landscape"
+  }'
+```
+
+### Request fields
+
+| Field          | Required | Values                              | Notes |
+|----------------|----------|-------------------------------------|-------|
+| `prompt`       | yes      | string                              | Be detailed and concrete. See prompt tips below. |
+| `aspect_ratio` | no       | `landscape` / `square` / `portrait` | Defaults to `landscape`. |
+| `output_dir`   | no       | absolute path                       | Defaults to the current working directory. The image is saved under `<output_dir>/assets/generated/`. |
+
+### Response shape (success)
+
+```json
+{
+  "success": true,
+  "image": "/abs/path/to/working_dir/assets/generated/img_20260525_011820_a1b2c3d4.png",
+  "model": "or-gemini-3-pro-image",
+  "provider": "openclacky",
+  "prompt": "A clean, modern hero illustration ...",
+  "aspect_ratio": "landscape",
+  "size": "1536x1024",
+  "usage": {
+    "prompt_tokens": 50,
+    "completion_tokens": 4500,
+    "cache_read_tokens": 0,
+    "cache_write_tokens": 0,
+    "total_tokens": 4550
+  }
+}
+```
+
+The `image` field is an absolute path on disk. To embed it in markdown, slides, or HTML, convert it to a path relative to the document you're writing.
+
+`usage` may be absent when the configured backend doesn't return token counts. Treat it as optional.
+
+### Response shape (failure)
+
+```json
+{
+  "success": false,
+  "image": null,
+  "error": "Upstream 401: Invalid API key",
+  "error_type": "api_error",
+  "model": "...",
+  "provider": "..."
+}
+```
+
+Common `error_type` values: `not_configured`, `auth_required`, `network_error`, `api_error`, `empty_response`. Tell the user the error plainly; if it's `auth_required` or `api_error 401/403`, point them at settings to fix the api_key.
+
+## Step 3 — Show the image
+
+`Read` does NOT show the image to the user — it only feeds it into your own context. To make the user actually see it, write a markdown tag in your reply:
+
+```markdown
+![](file:///abs/path/from/response.png)
+```
+
+Take the `image` field from the response and prefix `file://` (three slashes, since the path is absolute).
+
+If you're also embedding it in a document (README, PPT, etc.), use a relative path: `![](./assets/generated/xxx.png)`.
+
+## Prompt writing tips
+
+A good image prompt has 4 layers, in this order:
+
+1. **Subject** — what is in the image, concretely. ("a golden retriever puppy", "a stylized icon of a rocket")
+2. **Style / medium** — photo / illustration / 3D render / watercolor / flat vector / line art
+3. **Composition / lighting** — close-up / wide shot / overhead / soft natural light / dramatic backlight
+4. **Mood / palette** — minimal / playful / corporate / pastel / high-contrast monochrome
+
+For PPT / slide decks specifically:
+- Hero / cover slides: `aspect_ratio: landscape`, prompt should emphasise "clean", "minimal", "negative space" so text overlays well
+- Section dividers: `aspect_ratio: landscape`, abstract or pattern-style works better than literal subjects
+- Inline figures: `aspect_ratio: square` or `portrait`, more literal subject is fine
+
+When the user gives a vague request like "给我配张图", ask one clarifying question (subject? style?) before calling the API — costs real money per image.
+
+## When NOT to use this skill
+
+- The user asks to **edit** an existing image (this skill is text-to-image only today)
+- The user wants a **diagram / chart** with specific data — use a charting library (matplotlib, mermaid, etc.) instead; image gen is for illustrations, not data viz
+- The user asks for **screenshots** of real software — use the browser tool
+
+## Future modalities
+
+The same `/api/media/` namespace will gain `video` and `audio` endpoints. The pattern is identical: the user configures `type=video` / `type=audio` models in settings, this skill (or its successor) calls the matching endpoint.

data/lib/clacky/media/base.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "base64"
+require "securerandom"
+
+module Clacky
+  module Media
+    # Abstract base for media (image / video / audio) generation providers.
+    #
+    # Subclasses implement #generate_image (and later #generate_video,
+    # #generate_audio). The base class supplies the uniform success/error
+    # response shape and the on-disk persistence helper, mirroring the
+    # design used by Hermes' image_gen_provider so the surface stays
+    # learnable across modalities.
+    class Base
+      # @param model_entry [Hash] one entry from AgentConfig#models — must
+      #   include "model", "base_url", "api_key" keys.
+      def initialize(model_entry)
+        @model_entry = model_entry
+        @model       = model_entry["model"]
+        @base_url    = model_entry["base_url"]
+        @api_key     = model_entry["api_key"]
+      end
+
+      # @return [Hash] either success_response(...) or error_response(...)
+      def generate_image(prompt:, aspect_ratio: "landscape", output_dir: nil, **_kwargs)
+        raise NotImplementedError, "#{self.class.name} must implement #generate_image"
+      end
+
+      # Persist a base64-encoded image under <output_dir>/assets/generated/.
+      # Returns the absolute path on disk.
+      private def save_b64_image(b64_data, output_dir:, prefix: "img", extension: "png")
+        target_dir = File.join(output_dir, "assets", "generated")
+        FileUtils.mkdir_p(target_dir)
+        ts    = Time.now.strftime("%Y%m%d_%H%M%S")
+        short = SecureRandom.hex(4)
+        path  = File.join(target_dir, "#{prefix}_#{ts}_#{short}.#{extension}")
+        File.binwrite(path, Base64.decode64(b64_data))
+        path
+      end
+
+      private def success_response(image:, prompt:, aspect_ratio:, provider:, extra: {})
+        {
+          "success"      => true,
+          "image"        => image,
+          "model"        => @model,
+          "prompt"       => prompt,
+          "aspect_ratio" => aspect_ratio,
+          "provider"     => provider
+        }.merge(extra)
+      end
+
+      private def error_response(error:, error_type: "provider_error", provider: "", prompt: "", aspect_ratio: "landscape")
+        {
+          "success"      => false,
+          "image"        => nil,
+          "error"        => error,
+          "error_type"   => error_type,
+          "model"        => @model,
+          "prompt"       => prompt,
+          "aspect_ratio" => aspect_ratio,
+          "provider"     => provider
+        }
+      end
+    end
+  end
+end

data/lib/clacky/media/gemini.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require_relative "base"
+
+module Clacky
+  module Media
+    # Native Google Gemini image generation adapter.
+    #
+    # Reserved for users who configure a direct Google AI Studio base_url
+    # (e.g. https://generativelanguage.googleapis.com) with a raw Google API
+    # key. The official endpoints are:
+    #   POST /v1beta/models/<model>:generateContent  — image-out via Gemini
+    #   POST /v1beta/models/<model>:predict          — Imagen
+    # with x-goog-api-key auth, contents[].parts[] request schema, and
+    # candidates[].content.parts[].inlineData response schema. Completely
+    # different from the OpenAI /v1/images/generations contract.
+    #
+    # Today every shipping path (openclacky gateway, OpenRouter) wraps Gemini
+    # behind an OpenAI-compatible facade, so OpenAICompat handles them and
+    # this class is intentionally a stub. We surface a clear error rather
+    # than silently 404 against Google's actual host.
+    class Gemini < Base
+      def generate_image(prompt:, aspect_ratio: "landscape", output_dir: nil, **_kwargs)
+        error_response(
+          error: "Direct Google AI Studio (generativelanguage.googleapis.com) image generation is not yet supported. Use the openclacky or OpenRouter gateway instead — set base_url to https://api.openclacky.com or https://openrouter.ai/api/v1 and pick a Gemini image model (e.g. or-gemini-3-pro-image, google/gemini-3-pro-image-preview).",
+          error_type: "not_implemented",
+          provider: "gemini-direct",
+          prompt: prompt,
+          aspect_ratio: aspect_ratio
+        )
+      end
+    end
+  end
+end

data/lib/clacky/media/generator.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "openai_compat"
+require_relative "gemini"
+
+module Clacky
+  module Media
+    # Top-level dispatcher: takes an AgentConfig and a request, picks the
+    # right provider class based on the configured image model's base_url,
+    # and delegates.
+    #
+    # Adding a new modality (video / audio) means:
+    #   1. add a generate_<modality> method here that resolves the correct
+    #      type=<modality> entry and class
+    #   2. add a provider class under lib/clacky/media/ implementing the call
+    class Generator
+      # Hosts that speak the native Google AI Studio API instead of an
+      # OpenAI-compatible facade. Matched as a substring against the
+      # configured base_url so any regional / staging variant is caught.
+      GOOGLE_NATIVE_HOSTS = [
+        "generativelanguage.googleapis.com",
+        "aiplatform.googleapis.com"
+      ].freeze
+
+      # @param agent_config [Clacky::AgentConfig]
+      def initialize(agent_config)
+        @agent_config = agent_config
+      end
+
+      # @return [Hash, nil] the type=image model entry, or nil if not configured
+      def image_model_entry
+        @agent_config.find_model_by_type("image")
+      end
+
+      def generate_image(prompt:, aspect_ratio: "landscape", output_dir: nil, **kwargs)
+        entry = image_model_entry
+        if entry.nil?
+          return {
+            "success"    => false,
+            "image"      => nil,
+            "error"      => "No image model configured. Add a model with type=image in settings.",
+            "error_type" => "not_configured",
+            "provider"   => "",
+            "model"      => "",
+            "prompt"     => prompt
+          }
+        end
+
+        provider = build_provider_for(entry)
+        provider.generate_image(
+          prompt: prompt,
+          aspect_ratio: aspect_ratio,
+          output_dir: output_dir,
+          **kwargs
+        )
+      end
+
+      # Pick the adapter class for a media model entry.
+      #
+      # Routing rules:
+      #   • base_url points directly at a Google AI Studio host → Gemini
+      #     (native /v1beta/models/<m>:generateContent schema).
+      #   • everything else → OpenAICompat. This covers OpenAI itself, the
+      #     openclacky gateway, OpenRouter, and any third-party proxy that
+      #     re-exposes Gemini / Imagen / DALL-E behind /v1/images/generations.
+      #     OpenAICompat#generate_image branches internally on model id to
+      #     drop OpenAI-only params (size) when talking to Gemini families.
+      private def build_provider_for(entry)
+        url = entry["base_url"].to_s
+        if GOOGLE_NATIVE_HOSTS.any? { |host| url.include?(host) }
+          Gemini.new(entry)
+        else
+          OpenAICompat.new(entry)
+        end
+      end
+    end
+  end
+end