openrouter-genimage-kote-opencode 0.1.0

package/.opencode/skills/openrouter-image-generation/SKILL.md

@@ -0,0 +1,379 @@
+---
+name: openrouter-image-generation
+description: Use when the user explicitly asks to generate, create, draw, render, edit, transform, redraw, or restyle an image, or requests new visual assets for a project.
+license: MIT
+compatibility: opencode
+metadata:
+  plugin: openrouter-genimage-kote-opencode
+  edit-tool: openrouter_edit_image
+  generate-tool: openrouter_generate_image
+---
+
+# OpenRouter Image Generation
+
+Use the image tools provided by `openrouter-genimage-kote-opencode`.
+
+Image-to-image is the primary workflow.
+
+## Available tools
+
+### `openrouter_edit_image`
+
+Use when one or more existing images should influence the result.
+
+Typical scenarios:
+
+- edit an attached image;
+- redraw or restyle an image;
+- create a variation;
+- change the background;
+- recolor an asset;
+- add or remove an object;
+- preserve a character while changing the pose;
+- preserve an object while changing its state;
+- create another asset in the same style;
+- use several visual references;
+- create a new asset based on an existing image.
+
+### `openrouter_generate_image`
+
+Use only when the user requests a completely new image and no existing image
+needs to be preserved or used as a visual reference.
+
+## When to use image tools
+
+Use an image tool when:
+
+1. The user explicitly asks to generate, create, draw, render, edit, transform,
+   redraw, or restyle an image.
+2. The user requests new visual assets.
+3. The user requests game assets such as:
+   - characters;
+   - sprites;
+   - inventory icons;
+   - ability icons;
+   - textures;
+   - backgrounds;
+   - environment art;
+   - concept art;
+   - loading screens;
+   - promotional art.
+4. The user requests application or website assets such as:
+   - UI illustrations;
+   - empty-state illustrations;
+   - thumbnails;
+   - banners;
+   - avatars;
+   - hero images;
+   - decorative graphics.
+5. The user attaches an image and requests a visible change.
+
+The request may be written in any language. Follow the user's intent rather
+than relying on exact English trigger words.
+
+## When not to use image tools
+
+Do not call image tools when:
+
+- the user only asks to discuss an idea;
+- the user asks to analyze an image without changing it;
+- the user asks to find an existing image online;
+- the user asks for factual information about an image;
+- the task should be solved with deterministic SVG, HTML, CSS, a chart, or a
+  technical diagram;
+- the user did not request a new or modified visual result.
+
+Do not call `openrouter_balance` after every generation. Use it only when the
+user asks about balance, usage, credits, spending, or limits.
+
+## Choosing the correct tool
+
+Use `openrouter_edit_image` when:
+
+- an image is attached;
+- the user references an image inside the project;
+- the user provides an image URL;
+- the user asks to preserve visual properties;
+- the user asks for a variation;
+- the user asks to match an existing style.
+
+Use `openrouter_generate_image` when:
+
+- the user requests a completely new image;
+- no visual reference is required;
+- nothing from an existing image must be preserved.
+
+When the user attaches images and asks to edit "this image", omit the
+`references` argument. The tool will use all image attachments from the current
+user message.
+
+When only some attached images should be used, pass explicit attachment
+indexes.
+
+## Image-to-image prompt structure
+
+Clearly separate:
+
+1. The role of every reference.
+2. What must be preserved.
+3. What must be changed.
+4. What may change if necessary.
+5. What must not appear.
+6. The intended use of the result.
+
+Recommended structure:
+
+> Reference image 1 is the primary source.
+>
+> Preserve: [identity, face, hairstyle, silhouette, proportions, camera angle,
+> composition, art style, palette, lighting, materials].
+>
+> Change: [specific requested changes].
+>
+> Final result: [pose, composition, background, framing, asset purpose].
+>
+> Avoid: [unwanted changes or additions].
+
+Do not describe the entire source image from scratch when the user wants most
+of it preserved. Excessive redescription can cause the image model to replace
+details that should remain unchanged.
+
+Use explicit preservation phrases:
+
+- preserve the same character identity;
+- keep the facial features unchanged;
+- preserve the original proportions;
+- keep the camera angle;
+- maintain the same illustration style;
+- retain the original color palette;
+- change only the requested element;
+- do not add extra characters;
+- do not crop the subject.
+
+## Multiple references
+
+Always explain the role of every reference by order.
+
+Example:
+
+- Reference image 1: character identity and face.
+- Reference image 2: clothing design only.
+- Reference image 3: pose only.
+- Reference image 4: visual style and color palette.
+- Reference image 5: background composition.
+
+Do not assume that the image model knows why each reference was supplied.
+
+The first reference should normally be the primary subject.
+
+## Text-to-image prompt structure
+
+Build the prompt in this order:
+
+1. Asset type and intended use.
+2. Main subject.
+3. Action, pose, or state.
+4. Composition, camera, viewpoint, and crop.
+5. Environment or background.
+6. Visual style and shape language.
+7. Materials and important details.
+8. Color palette and lighting.
+9. Technical constraints.
+10. Short exclusions.
+
+Template:
+
+> [Asset type and purpose]. [Main subject and action]. [Composition and
+> viewpoint]. [Environment]. [Visual style and shape language]. [Materials and
+> details]. [Palette and lighting]. [Technical constraints]. [Short
+> exclusions].
+
+## General prompt rules
+
+### Be concrete
+
+Specify:
+
+- how many subjects are present;
+- what they are doing;
+- where they are positioned;
+- whether the result is full-body, portrait, top-down, side-view, isometric,
+  or orthographic;
+- whether cropping is allowed;
+- what the background should contain;
+- where empty space is required.
+
+Avoid prompts consisting only of adjectives such as:
+
+> beautiful, epic, amazing, highly detailed, cinematic
+
+Replace vague adjectives with visible instructions.
+
+### State the asset purpose
+
+Mention whether the result is:
+
+- an inventory icon;
+- a character portrait;
+- a full-body character;
+- a sprite;
+- a side-scrolling background;
+- a seamless texture;
+- a loading screen;
+- a UI illustration;
+- a thumbnail;
+- promotional art.
+
+The purpose affects composition, padding, readability, and detail level.
+
+### Use tool parameters
+
+Do not rely on prompt text alone for:
+
+- aspect ratio;
+- transparent background;
+- output format;
+- resolution;
+- number of results.
+
+Describe the visual requirement in the prompt and also pass the appropriate
+tool arguments.
+
+### Transparent assets
+
+For isolated assets:
+
+- request one isolated subject;
+- request a clean silhouette;
+- leave padding around the subject;
+- avoid cropped edges;
+- avoid unwanted shadows extending beyond the asset;
+- use PNG or WebP;
+- set `background` to `transparent`.
+
+### Game sprites
+
+Specify:
+
+- side-view, front-view, top-down, or isometric orientation;
+- full body and no cropping;
+- neutral or explicit pose;
+- consistent scale;
+- readable silhouette;
+- intended gameplay context.
+
+Generate separate assets instead of a sprite sheet unless the user explicitly
+requests a sprite sheet.
+
+### UI icons
+
+Specify:
+
+- one central object;
+- strong silhouette;
+- controlled detail;
+- clear margins;
+- no text;
+- no watermark;
+- transparent background when appropriate;
+- readability at small sizes.
+
+### Backgrounds
+
+Specify:
+
+- aspect ratio;
+- viewpoint;
+- depth layers;
+- areas that should remain visually quiet for UI overlays;
+- whether characters or text must be absent.
+
+### Seamless textures
+
+Explicitly request:
+
+- seamless;
+- tileable;
+- uniform scale;
+- no borders;
+- no perspective;
+- no large lighting gradient;
+- no unique object that makes repetition obvious.
+
+### Text inside images
+
+Keep text to a minimum.
+
+When text is required:
+
+- include the exact text in quotation marks;
+- specify placement;
+- specify typography;
+- inspect the generated result;
+- do not claim that the spelling is correct without checking it.
+
+### Consistent asset series
+
+Preserve a reusable style block containing:
+
+- visual medium;
+- shape language;
+- outline treatment;
+- palette;
+- lighting direction;
+- camera or viewpoint;
+- level of detail;
+- background treatment.
+
+Change only the subject-specific section.
+
+Use separate tool calls for separate assets unless the user explicitly requests
+a combined sheet.
+
+### Exclusions
+
+Keep exclusions short and specific.
+
+Good example:
+
+> no text, no watermark, no additional objects, no cropped edges
+
+Avoid long and contradictory negative-prompt lists.
+
+## Number of results
+
+Generate one image by default.
+
+Use `n > 1` only when the user explicitly requests:
+
+- alternatives;
+- variations;
+- several concepts;
+- multiple options.
+
+Remember that additional images may increase cost.
+
+## Output path
+
+Use an existing project asset directory when it is obvious.
+
+Otherwise save under:
+
+`assets/generated`
+
+Use a meaningful filename.
+
+Never overwrite the source image.
+
+## After generation
+
+1. Report the exact paths returned by the tool.
+2. Report how many images were requested and returned.
+3. Report the configured image model when available.
+4. Report routing mode when available.
+5. Report OpenRouter cost only when the tool provides it.
+6. Inspect returned image attachments when the active model supports image
+   input.
+7. Do not invent visual details that were not inspected.
+8. Do not claim success when no file was returned.
+9. Clearly report partial success and warnings.

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## 0.1.0 - 2026-08-23
+
+- Publish the initial release.
+- Add image-to-image and text-to-image OpenRouter tools for OpenCode.
+- Add direct and fail-closed KoteGateway routing.
+- Add balance reporting, skill installer, and package verification.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Koteyye
+
+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,229 @@
+# openrouter-genimage-kote-opencode
+
+OpenRouter image generation and image-to-image tools for OpenCode, with optional fail-closed routing through KoteGateway. Image-to-image is the primary workflow: attached images, project files, and public HTTPS URLs are sent to the configured OpenRouter image model as ordered `input_references`. Text-to-image is also available when no visual reference is needed.
+
+The plugin registers:
+
+- `openrouter_edit_image` — edit or create from one or more visual references;
+- `openrouter_generate_image` — create a new image from text only;
+- `openrouter_balance` — show current-key usage and, when authorized, account credits;
+- `/openrouter-balance` — invoke the balance tool without generating an image.
+
+The operation may incur OpenRouter charges. The OpenRouter model, API keys, and routing mode are configuration only; they are never tool arguments.
+
+## Installation
+
+Add the npm package to the `plugin` array in `opencode.jsonc`, then configure it as a tuple as shown below. OpenCode installs npm plugins referenced by its configuration.
+
+Use permissions that ask before paid image operations while allowing balance checks:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "openrouter_edit_image": "ask",
+    "openrouter_generate_image": "ask",
+    "openrouter_balance": "allow"
+  }
+}
+```
+
+## Direct configuration
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "openrouter-genimage-kote-opencode@0.1.0",
+      {
+        "routing": "direct",
+        "model": "openai/gpt-image-1",
+        "apiKey": "{env:OPENROUTER_API_KEY}",
+        "managementApiKey": "{env:OPENROUTER_MANAGEMENT_API_KEY}",
+        "outputDirectory": "assets/generated",
+        "defaults": {
+          "n": 1,
+          "output_format": "png"
+        }
+      }
+    ]
+  ]
+}
+```
+
+Direct mode sends HTTPS requests straight to the fixed OpenRouter API origin. It does not obtain a KoteGateway descriptor or use the gateway as a fallback.
+
+## Proxy configuration
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "openrouter-genimage-kote-opencode@0.1.0",
+      {
+        "routing": "proxy",
+        "model": "openai/gpt-image-1",
+        "apiKey": "{env:OPENROUTER_API_KEY}",
+        "outputDirectory": "assets/generated",
+        "input": {
+          "maxReferences": 16,
+          "maxFileBytes": 20971520,
+          "maxTotalBytes": 52428800
+        },
+        "requestTimeoutMs": 300000
+      }
+    ]
+  ]
+}
+```
+
+Proxy mode obtains a signed KoteGateway descriptor and uses an HTTPS CONNECT tunnel for every OpenRouter endpoint used by this plugin. It is fail-closed: bootstrap, signature, CONNECT, or proxy timeout errors end the request and never trigger a direct retry. OpenRouter keys, prompts, references, and results remain inside the TLS connection to OpenRouter and are not proxy headers.
+
+## API keys
+
+Create an OpenRouter generation key and expose it as `OPENROUTER_API_KEY`. Resolution order is `apiKey` in plugin options, then the environment variable. An absent key produces `GENIMAGE_OPENROUTER_KEY_MISSING` before any paid request.
+
+Full account credits require a management key. Set `managementApiKey` or `OPENROUTER_MANAGEMENT_API_KEY`. The generation key may be used for credits only if `/key` explicitly reports that it is a management key. Do not commit either key to `opencode.jsonc`; use OpenCode's `{env:NAME}` substitution.
+
+## Choosing an image model
+
+Set `model` to an OpenRouter image-model ID. The model is deliberately not exposed to tools, so an agent cannot silently select a different or more expensive model. Before the first paid request, the plugin discovers image-model capabilities and checks image output, image input for edit calls, and requested parameters. It does not substitute another model when a capability is missing.
+
+Provider support can be narrower than the OpenRouter API limits. In particular, a provider may accept fewer results or fewer parameters than another endpoint for the same model.
+
+## Image-to-image (primary workflow)
+
+`openrouter_edit_image` requires at least one image input. It never falls back to text-to-image. If `references` is omitted, the plugin uses all image attachments from the parent user message, in their original order. If none exist, it returns `GENIMAGE_REFERENCE_REQUIRED`.
+
+### Attached images
+
+Attach one or more images to the current user message and ask OpenCode to edit them. To select specific image attachments, references use one-based indexing among image attachments only:
+
+```json
+{
+  "prompt": "Reference image 1 defines the character. Reference image 2 defines clothing only. Preserve the face and illustration style.",
+  "references": [
+    { "type": "message_attachment", "index": 1 },
+    { "type": "message_attachment", "index": 2 }
+  ]
+}
+```
+
+The plugin supports trusted attachment representations supplied by OpenCode. It does not accept arbitrary `file:`, `data:`, or `blob:` URLs as tool arguments.
+
+### Project files
+
+Paths are relative to the current OpenCode worktree:
+
+```json
+{
+  "prompt": "Preserve the isometric angle, proportions, and palette. Create a damaged version with broken boards.",
+  "references": [
+    { "type": "project_file", "path": "assets/props/crate.png" }
+  ],
+  "output_path": "assets/props/crate-damaged.png"
+}
+```
+
+PNG, JPEG, and WebP inputs are accepted after size and magic-byte validation. Absolute paths, traversal, symlink escapes, directories, and files outside the worktree are rejected. Source images and existing outputs are never overwritten.
+
+### Multiple references and HTTPS URLs
+
+References are sent in exactly the order supplied. The first is the primary reference; describe each reference's role in the prompt because the plugin does not reorder, combine, or infer roles.
+
+```json
+{
+  "prompt": "Reference 1 defines identity and face. Reference 2 defines clothing only. Reference 3 defines palette and lighting.",
+  "references": [
+    { "type": "project_file", "path": "assets/character.png" },
+    { "type": "message_attachment", "index": 1 },
+    { "type": "https_url", "url": "https://example.com/palette.webp" }
+  ]
+}
+```
+
+Only public HTTPS URLs without embedded credentials are accepted. Explicit HTTPS references are passed to OpenRouter unchanged; local images are encoded in memory as base64 data URLs. No external storage service is required.
+
+See [Image-to-image guide](docs/image-to-image.md) for prompt patterns and limits.
+
+## Text-to-image
+
+Use `openrouter_generate_image` only for a completely new image with no visual reference. It accepts a prompt and output parameters, but no references, paths, attachment indexes, base64, or URLs.
+
+## Install the model skill
+
+The skill ships in the npm tarball but OpenCode discovers skills from project or user skill directories. Install it explicitly:
+
+```bash
+npx openrouter-genimage-kote-opencode install-skill
+npx openrouter-genimage-kote-opencode check-skill
+```
+
+For the user-wide directory:
+
+```bash
+npx openrouter-genimage-kote-opencode install-skill --global
+npx openrouter-genimage-kote-opencode check-skill --global
+```
+
+Project install writes `.opencode/skills/openrouter-image-generation/SKILL.md`; global install always writes `~/.config/opencode/skills/openrouter-image-generation/SKILL.md`, including on Windows. An identical SHA-256 is a no-op. `check-skill` exits nonzero when the skill is missing or modified. Use `--force` only to atomically replace a locally modified skill. The CLI has no postinstall hook, needs no API key, and performs no network request.
+
+## Balance and usage
+
+Run `/openrouter-balance` or call `openrouter_balance`. The result keeps two concepts separate:
+
+- `/key` reports usage and the spending limit of the configured API key, including the remaining API-key limit;
+- `/credits` reports total account credits and total account usage, and requires a management key.
+
+The remaining spending limit of one key is not the OpenRouter account balance. Without management authorization, account credits are reported as unavailable. A successful `/key` response is still returned if `/credits` fails.
+
+## Security
+
+- Production requests are fixed to `https://openrouter.ai/api/v1`; custom base URLs are rejected.
+- Redirects are rejected. Paid `POST /images` requests are never retried automatically.
+- Proxy mode is fail-closed and never retries directly.
+- The plugin does not replace `globalThis.fetch` or intercept other providers.
+- Keys, full prompts, base64, binary data, unredacted upstream bodies, and full URLs with query strings are excluded from logs and metadata.
+- Local input and output paths are confined to the worktree; real paths are checked to prevent symlink escape.
+- Output uses atomic writes and never overwrites a source or existing file.
+
+See [Security](docs/security.md) and [SECURITY.md](SECURITY.md).
+
+## Version 0.1.0 limitations
+
+No masks or pixel-local inpainting, interactive editor, LoRA training, video, streaming generation, SVG results, provider-specific options, automatic credit purchase, automatic model selection, hidden fallback, or external object storage are included. Only PNG, JPEG, and WebP raster inputs/results are supported. Seeds do not promise reproducibility across providers. OpenRouter may return fewer images than requested; valid partial results are preserved with warnings.
+
+## Troubleshooting
+
+- `GENIMAGE_REFERENCE_REQUIRED`: attach an image or pass at least one ordered reference to `openrouter_edit_image`.
+- `GENIMAGE_MODEL_DOES_NOT_SUPPORT_IMAGE_INPUT`: choose an image-to-image capable model in configuration; the plugin will not switch models.
+- `GENIMAGE_PARAMETER_UNSUPPORTED`: remove the unsupported argument/default or choose a compatible configured model.
+- `GENIMAGE_OPENROUTER_KEY_MISSING`: expose `OPENROUTER_API_KEY` to the OpenCode process or set `apiKey` through an environment substitution.
+- `GENIMAGE_*_TOO_LARGE` / `GENIMAGE_TOTAL_REFERENCE_SIZE_EXCEEDED`: compress or resize inputs, use fewer references, or supply a public HTTPS URL.
+- `GENIMAGE_GATEWAY_*`: repair KoteGateway/bootstrap/connectivity; proxy mode intentionally does not fall back to direct.
+- Output path errors: use a relative worktree path that neither exists nor names a source image.
+
+See the complete [Troubleshooting guide](docs/troubleshooting.md), [Configuration reference](docs/configuration.md), and [Testing guide](docs/testing.md).
+
+## Compatibility status
+
+- OpenCode smoke-test baseline: **1.18.21**. CI verifies the installed npm tarball on that baseline and the latest stable release. TUI and Desktop attachment rendering still require manual release checks; Web is tested when available.
+- This package consumes only the reusable `/core` export from `@koteye/kote-gateway-opencode` **0.1.1**. The gateway adapter package declares an OpenCode/SDK ceiling of **1.18.18**, so this package pins `@opencode-ai/plugin` **1.18.18** to satisfy that peer metadata. The core export does not import the OpenCode adapter at runtime, and the complete installed tarball is smoke-tested on OpenCode **1.18.21** and latest.
+- Synthetic TLS/CONNECT tests pass for signed bootstrap, fail-closed routing, one CONNECT, and both plugin load orders. They complement the real OpenCode registration smokes; paid OpenRouter E2E and client UI attachment rendering remain separate opt-in/manual checks.
+- Node.js 20 or newer is declared by the package. The implementation is intended to be Bun-compatible and to support Windows, macOS, and Linux; release artifacts must be tested on the supported matrix.
+
+## Documentation
+
+- [Architecture](docs/architecture.md)
+- [Configuration](docs/configuration.md)
+- [Image-to-image](docs/image-to-image.md)
+- [Security](docs/security.md)
+- [Testing](docs/testing.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Русская версия](README.ru.md)
+
+## License
+
+MIT. See [LICENSE](LICENSE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).