@cat-factory/binary-generators 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Savin
+
+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,119 @@
+# @cat-factory/binary-generators
+
+The **generative binary integrations** the platform ships, plus the seam a deployment writes its
+own with. These are the metered vendor APIs a [binary-output step](https://github.com/kibertoad/cat-factory/blob/main/docs/initiatives/binary-output-foundational-storage.md)
+calls to _produce_ its artifacts, as opposed to the foundational service the artifacts are then
+_stored_ through.
+
+| id            | What it makes                                                          | Modalities                          |
+| ------------- | ---------------------------------------------------------------------- | ----------------------------------- |
+| `nano-banana` | Images with legible text in them, and conversational editing, up to 4K | `image` (`image/png`, `image/jpeg`) |
+
+## Why the platform ships one at all
+
+`defaultBinaryGeneratorRegistry()` is still empty, and the reasoning that kept it empty still
+holds: no image API is one every organisation runs, and every one of them is metered. What changed
+is the Media task type. It ships a generating agent kind, a preset and the storage underneath, and
+its step selected nothing, so the platform's most demonstrable capability was reachable only by a
+deployment that first wrote an integration, an OpenAPI document and a credential declaration.
+
+Metered is answered by the credential rather than by the registry. With no key resolved the agent
+is told the integration is unavailable and reports it as the reason an artifact is missing, so a
+deployment that ignores this package pays nothing and sees one extra row in a picker.
+
+## Using it
+
+Every facade defaults its registry to the shipped set, so nothing is needed to get `nano-banana`:
+
+```ts
+await start({/* … */}) // binaryGeneratorRegistry defaults to binaryGeneratorRegistryWithBuiltins()
+```
+
+An **injected** registry REPLACES the default rather than merging with it, so a deployment adding
+its own integrations starts from the built-ins:
+
+```ts
+import { binaryGeneratorRegistryWithBuiltins } from '@cat-factory/node-server'
+
+const binaryGeneratorRegistry = binaryGeneratorRegistryWithBuiltins()
+binaryGeneratorRegistry.registerAll(myIntegrations)
+await start({ binaryGeneratorRegistry })
+```
+
+That matters more here than for the gate or prompt-fragment registries, because the shipped
+`pl_media` preset SELECTS `nano-banana` by id: a registry without it refuses that pipeline's runs
+at admission (`binary_output_generator_invalid`) rather than degrading quietly. Dropping the
+shipped integration is a legitimate choice; editing that preset's step is the other half of it.
+
+Register **once per deployment**, on the process that owns the registry. In mothership mode that is
+the mothership: a node resolves integrations over `/internal/binary-generators` and consults no
+registry of its own, so the set the pipeline builder offers and the set admission resolves are one
+set however far behind the node's build has drifted.
+
+On the **Worker** the registry is also held process-wide
+(`infrastructure/binaryGenerators.ts`), the same way the deployment's binary artifact stores are
+and for the same reason: that runtime builds a container per entry point, and a binary-output
+step's dispatch brief is composed on the durable path, which takes no options at all.
+`createWorker({ overrides: { binaryGeneratorRegistry } })` registers on your behalf, so a
+deployment using the documented seam needs to know none of that. What made this one easy to miss
+is that an override-less build resolves the SHIPPED set rather than nothing, so an unregistered
+integration is absent from a brief that otherwise looks populated.
+
+## The credential
+
+`nano-banana` authenticates with `GEMINI_API_KEY`, an API key from
+[Google AI Studio](https://aistudio.google.com/apikey), sent as the `x-goog-api-key` header. The
+name is the vendor's own, so an agent reaching for `google-genai` finds the value where the library
+looks.
+
+Set it either as a workspace **capability credential** (subject `binary-generator`, id
+`nano-banana`, key `GEMINI_API_KEY`) or in the environment the deployment dispatches runs from. The
+value travels on the job body alone and is injected into the agent's process for that job; it is
+never written to the checkout, the prompt or a log.
+
+Do **not** add it to `docs/environment-variables.md`: every variable documented there is reserved
+by `check-reserved-env-keys.mjs`, which would make this key unresolvable.
+
+Billing must be enabled on the Google project. None of these models has a free tier, so an
+unbilled key gets `FAILED_PRECONDITION` on the first call, which the agent reports as the reason
+nothing was generated.
+
+## Writing your own
+
+`defineBinaryGenerator` is exported for exactly this, and re-exported from each facade so a
+deployment reaches it from the package it already depends on. It runs the platform's OWN
+registration rules at import (the definition schema, plus `binaryGeneratorDetailIssues`: the
+endpoint policy, the contract-set rules, the media-type classifier, the harness check and the
+capability-versus-accepted-values pairing), so a definition that would fail a boot fails a test
+instead:
+
+```ts
+import { defineBinaryGenerator, openApiContract } from '@cat-factory/binary-generators'
+
+export const acmeImages = defineBinaryGenerator({
+  id: 'acme-images',
+  name: 'Acme Images',
+  summary: 'One line the picker and the agent brief show.',
+  description: 'What it is good at, what it is NOT for, and its cost profile.',
+  modalities: ['image'],
+  mediaTypes: ['image/png'],
+  capabilities: ['seed', 'exact-size'],
+  endpoint: 'https://api.acme.example',
+  credentials: [{ key: 'ACME_IMAGE_API_KEY', usage: 'Authorization: Bearer <value>' }],
+  contracts: [
+    openApiContract({ contractId: 'acme-api', title: 'Acme API', document: ACME_OPENAPI }),
+  ],
+  guidance: 'Operating notes folded into the agent’s brief verbatim.',
+})
+```
+
+Two rules the seam cannot check for you, both pinned per integration in the tests here:
+
+- **A capability is a claim about the endpoint's REQUEST.** Declare one only where the registered
+  contract carries the parameter, or a step is admitted and the agent is left holding an option it
+  cannot send. `nano-banana.test.ts` names each capability's evidence in the document.
+- **An `accepts` set is a REFUSAL.** State one only where the endpoint genuinely enumerates its
+  values, and read it off the contract rather than restating it, so the two cannot drift.
+
+Everything that does not gate an option ("good at pixel art", "cheap below 2K", "rate limited to
+five a second") stays prose in `description` and `guidance`, where a sentence can say what it means.

package/dist/contracts/nano-banana.openapi.d.ts

@@ -0,0 +1,3 @@
+/** The catalog-facing OpenAPI document for Nano Banana on `https://generativelanguage.googleapis.com`. */
+export declare const NANO_BANANA_OPENAPI: Record<string, unknown>;
+//# sourceMappingURL=nano-banana.openapi.d.ts.map

package/dist/contracts/nano-banana.openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nano-banana.openapi.d.ts","sourceRoot":"","sources":["../../src/contracts/nano-banana.openapi.ts"],"names":[],"mappings":"AAoDA,0GAA0G;AAC1G,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAyYxB,CAAA"}

package/dist/contracts/nano-banana.openapi.js

@@ -0,0 +1,416 @@
+// Google's Gemini Interactions API, narrowed to Nano Banana image generation, as an OpenAPI 3.1
+// document.
+//
+// Authored here because Google publishes this surface as prose, curl snippets and SDK reference
+// pages rather than as a machine-readable spec a registry can hand to an agent. The document is
+// what a run actually reads: the registry renders it into `.cat-context/` beside the brief, and
+// the agent writes its request from this and nothing else.
+//
+// WHAT IS IN IT is one operation, and that is not a small integration written small: it is the
+// whole of what a step needs. Generation here is SYNCHRONOUS, so the response to
+// `POST /v1beta/interactions` carries the image bytes inline as base64. There is no task to poll,
+// no signed URL to race, and correspondingly no second endpoint.
+//
+// The Interactions API is a great deal more than image generation, and the rest is deliberately
+// absent: text and audio and video generation, function calling, code execution, computer use,
+// the Deep Research and Antigravity agents, file search, streaming, `background` execution with
+// its `GET`/`DELETE`/`cancel` lifecycle, and stored multi-turn interactions
+// (`previous_interaction_id`). Grounding tools (Google Search, Google Maps, URL context) are the
+// omission worth naming twice, because they are the one that bills: 5,000 free searches a month
+// across all Gemini 3.x usage on the key, then $14 per 1,000. A step asked to draw a scout has no
+// business searching the web to do it, and an interface an agent is handed is an interface it
+// will use.
+//
+// MODEL NAMES ARE BAKED IN HERE, which wants its reason because a vendor's model list is usually
+// the first thing a document like this gets wrong. `model` is a REQUIRED enum field on every
+// request, there is no discovery operation registered, and the three image models are a cost
+// ladder rather than a price list, so an agent that cannot name one cannot make a request at all.
+//
+// `satisfies OpenAPIV3_1.Document` is what makes "authored in TypeScript" worth anything: a typo'd
+// `$ref` or a parameter with no `in` is a compile error here rather than a garbled context file at
+// dispatch. The ANNOTATION stays `Record<string, unknown>` so `openapi-types` does not reach
+// consumers through this package's `.d.ts`: the checking is ours, and the shipped shape is what
+// `openApiContract` takes.
+//
+// WHAT NO TEST HERE CAN HOLD, listed because an unlisted unchecked fact is one nobody re-checks.
+// The type system holds this document's shape and `openapi-documents.test.ts` holds its internal
+// references, but every NAME and NUMBER below was transcribed from Google's docs and will go stale
+// without failing anything:
+//
+//   - the three image model ids, and the resolutions each supports (Lite is 1K only);
+//   - 14 reference images, and the per-model split between objects, characters and style refs;
+//   - the ten aspect ratios and the four `image_size` values;
+//   - the per-image prices in the generator's description, and the $60 / $120 per 1M output
+//     token rates behind them;
+//   - SynthID watermarking of every generated image.
+//
+// A vendor that changes one of these ships an integration that still compiles, still passes, and
+// is wrong at dispatch. Re-read them against https://ai.google.dev/gemini-api/docs/image-generation
+// when touching this file.
+/** The catalog-facing OpenAPI document for Nano Banana on `https://generativelanguage.googleapis.com`. */
+export const NANO_BANANA_OPENAPI = {
+    openapi: '3.1.0',
+    info: {
+        title: 'Gemini Interactions API (Nano Banana image generation)',
+        version: 'v1beta',
+        description: 'Text-to-image and reference-guided image generation and editing, through the one ' +
+            '`interactions` endpoint. Every request carries the `x-goog-api-key` header. Generation is ' +
+            'SYNCHRONOUS: the response carries the finished image inline as base64, so there is no ' +
+            'task, no poll and no expiring link. A request the model declines is not an error status: ' +
+            'it answers 200 with a text block explaining the refusal and no image block at all.',
+    },
+    servers: [{ url: 'https://generativelanguage.googleapis.com' }],
+    security: [{ googleApiKey: [] }],
+    paths: {
+        '/v1beta/interactions': {
+            post: {
+                operationId: 'createImageInteraction',
+                summary: 'Generate or edit an image and receive the bytes inline',
+                description: 'One call, one image. Send the brief as a `text` block and any reference images as ' +
+                    '`image` blocks in the same `input` array; the response carries the result as base64 ' +
+                    'in `output_image`, and `usage` reports what it cost in tokens. There is no balance ' +
+                    'read on this API and no dry run, so the request that discovers an exhausted quota is ' +
+                    'a real one.',
+                requestBody: {
+                    required: true,
+                    content: {
+                        'application/json': {
+                            schema: { $ref: '#/components/schemas/ImageInteractionRequest' },
+                        },
+                    },
+                },
+                responses: {
+                    '200': {
+                        description: 'The interaction completed. It carries an image when the model produced one and ' +
+                            'text alone when it declined, so check for the image rather than assuming it.',
+                        content: {
+                            'application/json': { schema: { $ref: '#/components/schemas/Interaction' } },
+                        },
+                    },
+                    '400': { $ref: '#/components/responses/BadRequest' },
+                    '403': { $ref: '#/components/responses/PermissionDenied' },
+                    '429': { $ref: '#/components/responses/RateLimited' },
+                    '500': { $ref: '#/components/responses/ServerError' },
+                    '503': { $ref: '#/components/responses/Unavailable' },
+                },
+            },
+        },
+    },
+    components: {
+        securitySchemes: {
+            googleApiKey: {
+                type: 'apiKey',
+                in: 'header',
+                name: 'x-goog-api-key',
+                description: 'An API key from Google AI Studio. Send it as this header rather than as a `?key=` ' +
+                    'query parameter, which puts the credential in logs and referrers.',
+            },
+        },
+        responses: {
+            BadRequest: {
+                description: 'The request was rejected. `INVALID_ARGUMENT` is a malformed body, and also what an ' +
+                    'invalid API key returns, so read `error.message` rather than assuming the body is at ' +
+                    'fault. `FAILED_PRECONDITION` is billing not enabled on the project, which every image ' +
+                    'model requires since none has a free tier.',
+                content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } },
+            },
+            PermissionDenied: {
+                description: '`PERMISSION_DENIED`: the key is valid but not entitled to this model. A rewrite of ' +
+                    'the request will not fix it; report it as a gap.',
+                content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } },
+            },
+            RateLimited: {
+                description: '`RESOURCE_EXHAUSTED`, a rate limit on any of four dimensions: requests per minute, ' +
+                    'input tokens per minute, requests per day, and IMAGES per minute, which is the one ' +
+                    'peculiar to these models. Back off exponentially; the daily one does not clear by ' +
+                    'waiting a minute.',
+                content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } },
+            },
+            ServerError: {
+                description: '`INTERNAL`: a fault on Google’s side. Retry with backoff.',
+                content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } },
+            },
+            Unavailable: {
+                description: '`UNAVAILABLE`: the model is temporarily overloaded. Retry with backoff rather than ' +
+                    'switching models mid-set, since a different model draws a different picture.',
+                content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorEnvelope' } } },
+            },
+        },
+        schemas: {
+            ImageInteractionRequest: {
+                type: 'object',
+                required: ['model', 'input'],
+                properties: {
+                    model: { $ref: '#/components/schemas/ImageModel' },
+                    input: {
+                        type: 'array',
+                        description: 'The prompt, as an ordered list of blocks. One `text` block is the brief; each ' +
+                            '`image` block is a reference the model composes from or edits, up to 14 of them ' +
+                            'on one request (the pro model reads them as roughly six objects, five characters ' +
+                            'and three style references).',
+                        items: { $ref: '#/components/schemas/InputBlock' },
+                    },
+                    response_format: { $ref: '#/components/schemas/ImageResponseFormat' },
+                    generation_config: { $ref: '#/components/schemas/GenerationConfig' },
+                },
+            },
+            ImageModel: {
+                type: 'string',
+                enum: ['gemini-3.1-flash-image', 'gemini-3.1-flash-lite-image', 'gemini-3-pro-image'],
+                description: 'Which image model draws it: a cost ladder, not a feature list. ' +
+                    '`gemini-3.1-flash-image` (Nano Banana 2) is the default working model and reaches 4K. ' +
+                    '`gemini-3.1-flash-lite-image` is the cheapest and is 1K ONLY, so pairing it with a ' +
+                    'larger `image_size` is a request that cannot be served. `gemini-3-pro-image` (Nano ' +
+                    'Banana Pro) is the premium model: the best text rendering and identity consistency, ' +
+                    'roughly twice the price, and the one to reach for when the image has to carry legible ' +
+                    'words. `gemini-2.5-flash-image` (the original Nano Banana) is legacy and not offered ' +
+                    'here.',
+            },
+            InputBlock: {
+                description: 'One block of the prompt: the written brief, or a reference image.',
+                oneOf: [
+                    { $ref: '#/components/schemas/TextInput' },
+                    { $ref: '#/components/schemas/ImageInput' },
+                ],
+            },
+            TextInput: {
+                type: 'object',
+                required: ['type', 'text'],
+                properties: {
+                    type: { type: 'string', const: 'text' },
+                    text: {
+                        type: 'string',
+                        description: 'What the image IS: subject, framing, materials, lighting, and the words to render ' +
+                            'if any. Describe the picture rather than listing keywords; these models read a ' +
+                            'paragraph better than a tag soup, and they render text in the brief literally.',
+                    },
+                },
+            },
+            ImageInput: {
+                type: 'object',
+                required: ['type'],
+                properties: {
+                    type: { type: 'string', const: 'image' },
+                    data: {
+                        type: 'string',
+                        description: 'The reference image as RAW base64, with no `data:` prefix. Send bytes this way ' +
+                            'rather than by `uri`, since a bearer-gated storage link is not something Google’s ' +
+                            'network can fetch.',
+                    },
+                    uri: {
+                        type: 'string',
+                        description: 'A Files API URI for an image already uploaded to this project. Not a general ' +
+                            'URL fetcher.',
+                    },
+                    mime_type: {
+                        type: 'string',
+                        enum: ['image/png', 'image/jpeg', 'image/webp', 'image/heic', 'image/heif'],
+                        description: 'The format of `data`. Declare it; do not leave it to be sniffed.',
+                    },
+                },
+            },
+            ImageResponseFormat: {
+                type: 'object',
+                description: 'What to produce. Omitting it entirely yields a 1:1 1K PNG, which is rarely the size ' +
+                    'the deliverable actually wants.',
+                properties: {
+                    type: {
+                        type: 'string',
+                        const: 'image',
+                        description: 'Ask for an image. Without it the model may answer with text.',
+                    },
+                    mime_type: {
+                        type: 'string',
+                        enum: ['image/png', 'image/jpeg'],
+                        description: 'The container. `image/png` for flat colour, transparency, or anything a later ' +
+                            'step will cut up; `image/jpeg` only for a finished photographic image, since its ' +
+                            'artefacts survive every edit after it.',
+                    },
+                    aspect_ratio: {
+                        type: 'string',
+                        enum: ['1:1', '3:2', '2:3', '3:4', '4:3', '4:5', '5:4', '9:16', '16:9', '21:9'],
+                        description: 'The shape. This is a CLOSED list, not a free-form ratio: a deliverable whose ' +
+                            'required proportions are not on it is generated at the nearest ratio and cropped ' +
+                            'afterwards, never requested directly.',
+                    },
+                    image_size: {
+                        type: 'string',
+                        enum: ['512px', '1K', '2K', '4K'],
+                        description: 'The resolution, and the price. The `K` is capitalised and the values are exact ' +
+                            'strings. `gemini-3.1-flash-lite-image` serves `1K` alone; the other two serve all ' +
+                            'four.',
+                    },
+                },
+            },
+            GenerationConfig: {
+                type: 'object',
+                properties: {
+                    thinking_level: {
+                        type: 'string',
+                        enum: ['minimal', 'low', 'medium', 'high'],
+                        description: 'How much the model reasons before drawing. `minimal` is the default and is right ' +
+                            'for a brief that already says what the picture is; `high` earns its keep on ' +
+                            'composition-heavy work and on images with a lot of text in them. The interim ' +
+                            'images it draws while thinking are not charged, but the thinking TOKENS are.',
+                    },
+                    seed: {
+                        type: 'integer',
+                        description: 'Reuse to iterate on one composition while the prompt changes. It does not hold a ' +
+                            'character; reference images do.',
+                    },
+                },
+            },
+            Interaction: {
+                type: 'object',
+                description: 'One completed generation. The image is inline; nothing here expires.',
+                properties: {
+                    id: { type: 'string', description: 'The interaction id, for support and for logs.' },
+                    object: { type: 'string', description: 'Always `interaction`.' },
+                    model: { $ref: '#/components/schemas/ImageModel' },
+                    status: {
+                        type: 'string',
+                        enum: [
+                            'completed',
+                            'in_progress',
+                            'queued',
+                            'requires_action',
+                            'incomplete',
+                            'failed',
+                            'cancelled',
+                            'budget_exceeded',
+                        ],
+                        description: 'For a plain image request this is `completed`. The asynchronous states belong to ' +
+                            '`background` interactions, which this integration does not use.',
+                    },
+                    output_image: {
+                        $ref: '#/components/schemas/OutputImage',
+                    },
+                    output_text: {
+                        type: 'string',
+                        description: 'The model’s text, concatenated. On a successful generation it is commentary; when ' +
+                            'there is NO `output_image` it is the refusal, and it is the only thing that says ' +
+                            'why.',
+                    },
+                    steps: {
+                        type: 'array',
+                        description: 'The full interleaved transcript. `output_image` is the last image out of it, ' +
+                            'which is what a single-image request wants; read this only when a request ' +
+                            'produced several.',
+                        items: { $ref: '#/components/schemas/Step' },
+                    },
+                    usage: { $ref: '#/components/schemas/Usage' },
+                    created: { type: 'string', description: 'ISO 8601 creation timestamp.' },
+                },
+            },
+            Step: {
+                type: 'object',
+                properties: {
+                    id: { type: 'string' },
+                    type: {
+                        type: 'string',
+                        enum: ['model_output', 'user_input', 'function_call'],
+                        description: 'Generated images are on the `model_output` steps.',
+                    },
+                    content: {
+                        type: 'array',
+                        description: 'The blocks of this step, in order.',
+                        items: { $ref: '#/components/schemas/OutputContent' },
+                    },
+                },
+            },
+            OutputContent: {
+                description: 'One block of a step’s output.',
+                oneOf: [
+                    { $ref: '#/components/schemas/OutputImage' },
+                    { $ref: '#/components/schemas/OutputText' },
+                ],
+            },
+            OutputImage: {
+                type: 'object',
+                description: 'A generated image, inline. Every one carries an invisible SynthID watermark, which ' +
+                    'survives ordinary edits and is not something to try to remove.',
+                properties: {
+                    type: { type: 'string', const: 'image' },
+                    data: {
+                        type: 'string',
+                        description: 'The image as RAW base64 with no `data:` prefix. DECODE IT before storing: ' +
+                            'storing the base64 text is a corrupt asset that looks like a successful run.',
+                    },
+                    mime_type: {
+                        type: 'string',
+                        enum: ['image/png', 'image/jpeg'],
+                        description: 'What the bytes actually are. Store this as the asset’s content type rather than ' +
+                            'the one you asked for.',
+                    },
+                },
+            },
+            OutputText: {
+                type: 'object',
+                properties: {
+                    type: { type: 'string', const: 'text' },
+                    text: { type: 'string' },
+                },
+            },
+            Usage: {
+                type: 'object',
+                description: 'What the interaction cost, in tokens. This is the only accounting the API offers, ' +
+                    'there is no balance endpoint anywhere on this surface.',
+                properties: {
+                    total_input_tokens: { type: 'integer', description: 'Prompt and reference images.' },
+                    total_output_tokens: {
+                        type: 'integer',
+                        description: 'The image, billed at the model’s image-output rate. Roughly 1,120 tokens for a 1K ' +
+                            'image on the flash model and 2,520 for a 4K one, so resolution IS the bill.',
+                    },
+                    total_thought_tokens: {
+                        type: 'integer',
+                        description: 'Reasoning, when `thinking_level` asked for any. Billed.',
+                    },
+                    total_tokens: { type: 'integer' },
+                    output_tokens_by_modality: {
+                        type: 'array',
+                        description: 'The output split by kind, which is how the image half is isolated.',
+                        items: { $ref: '#/components/schemas/ModalityTokens' },
+                    },
+                },
+            },
+            ModalityTokens: {
+                type: 'object',
+                properties: {
+                    modality: {
+                        type: 'string',
+                        description: 'e.g. `TEXT`, `IMAGE`.',
+                    },
+                    token_count: { type: 'integer' },
+                },
+            },
+            ErrorEnvelope: {
+                type: 'object',
+                description: 'Google’s standard error wrapper. Every failure on this API arrives in it.',
+                properties: {
+                    error: {
+                        type: 'object',
+                        properties: {
+                            code: { type: 'integer', description: 'The HTTP status, repeated.' },
+                            message: {
+                                type: 'string',
+                                description: 'The human-readable reason. Read it, since the status alone is ambiguous.',
+                            },
+                            status: {
+                                type: 'string',
+                                description: 'The canonical code, e.g. `INVALID_ARGUMENT`, `PERMISSION_DENIED`, ' +
+                                    '`RESOURCE_EXHAUSTED`, `FAILED_PRECONDITION`, `INTERNAL`, `UNAVAILABLE`.',
+                            },
+                            details: {
+                                type: 'array',
+                                description: 'Structured detail, when the service attaches any.',
+                                items: { type: 'object', additionalProperties: true },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+};
+//# sourceMappingURL=nano-banana.openapi.js.map

package/dist/contracts/nano-banana.openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nano-banana.openapi.js","sourceRoot":"","sources":["../../src/contracts/nano-banana.openapi.ts"],"names":[],"mappings":"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"}

package/dist/define.d.ts

@@ -0,0 +1,94 @@
+import type { BinaryGeneratorCapability, BinaryGeneratorCredential, BinaryGeneratorDefinition, UploadApiContract } from '@cat-factory/contracts';
+/**
+ * A validated integration definition: structurally a {@link BinaryGeneratorDefinition} (exactly
+ * what `BinaryGeneratorRegistry.register` takes), with the four optional COLLECTIONS settled so
+ * consumers never branch on `undefined`.
+ *
+ * `accepts` is the one optional field left unsettled, and the asymmetry is deliberate: it is a
+ * record of sets rather than a collection, and the platform reads an absent entry as "not stated"
+ * while refusing an empty array inside one. Settling it would turn a definition that declares no
+ * value sets into one that declares empty ones, which is the difference between "unjudged" and
+ * "refuses everything".
+ */
+export interface BinaryGeneratorEntry extends BinaryGeneratorDefinition {
+    mediaTypes: string[];
+    capabilities: BinaryGeneratorCapability[];
+    contracts: UploadApiContract[];
+    credentials: BinaryGeneratorCredential[];
+}
+/** What {@link defineBinaryGenerator} accepts, before defaults are settled. */
+export interface BinaryGeneratorInput {
+    /** Lower-kebab slug a step names in `stepOptions.binaryOutput.generatorIds`. */
+    id: string;
+    name: string;
+    /** One line; what the picker and the agent's brief show. */
+    summary: string;
+    /** What it is good at, what it is NOT for, and its cost profile. */
+    description: string;
+    /** The content types it produces. At least one. */
+    modalities: readonly BinaryGeneratorDefinition['modalities'][number][];
+    /** The concrete formats it emits, when the integration pins them down. */
+    mediaTypes?: readonly string[];
+    /**
+     * What it can be ASKED FOR while generating: the per-step generation options a step may point
+     * at it. Omitted (or empty) means "only the coarse facts are known": every option requirement
+     * against it is reported as unverifiable rather than refused, which is what lets an integration
+     * registered before this axis existed go on running unchanged.
+     */
+    capabilities?: readonly BinaryGeneratorCapability[];
+    /**
+     * For the options whose domain is a CLOSED SET, which values this endpoint takes. The axis
+     * beside {@link capabilities} rather than part of it: that one says the request can CARRY the
+     * value, this says the endpoint will take the one being asked for.
+     *
+     * Omitted per option means "not stated", and it is the right answer for an endpoint that renders
+     * anything inside limits no list can enumerate: those belong in `guidance`. A set is a REFUSAL,
+     * so declare one only where the endpoint genuinely has one.
+     */
+    accepts?: BinaryGeneratorDefinition['accepts'];
+    /** The API's base URL. `https` (or loopback) only: the credentials ride this request. */
+    endpoint?: string;
+    /** Operating notes folded into the agent's brief verbatim. */
+    guidance?: string;
+    /**
+     * The credentials it authenticates with, by NAME. A list because a vendor account is not always
+     * one string, and injection names must be distinct, which the schema refuses case-insensitively.
+     */
+    credentials?: readonly BinaryGeneratorCredential[];
+    /** API contract documents, injected as `.cat-context/` files beside the brief. */
+    contracts?: readonly UploadApiContract[];
+}
+/**
+ * Validate an integration definition and freeze it.
+ *
+ * Two checks, and they are the SAME two the engine makes at boot rather than an approximation of
+ * them. `binaryGeneratorDefinitionSchema` is the shape every write path shares, and
+ * `binaryGeneratorDetailIssues` is the rule set a parse structurally cannot make (a cleartext
+ * endpoint, a contract set that reads as garbage to the agent handed it, a media type whose
+ * modality contradicts the declared ones, a harness with no generation tool, an accepted-value set
+ * with no capability behind it). Calling them rather than restating them is the whole point of the
+ * seam: a rule the platform adds fails this definition on the version bump instead of on the boot
+ * that follows a deploy.
+ *
+ * What it does NOT check is the one thing no schema could: whether a declared capability is one the
+ * registered CONTRACT can actually be asked for. That is a claim about a vendor's request body, so
+ * it is pinned per integration in a test beside the document.
+ */
+export declare function defineBinaryGenerator(input: BinaryGeneratorInput): BinaryGeneratorEntry;
+/**
+ * Turn an OpenAPI document written as a TypeScript object into the uploadable contract shape.
+ *
+ * The document stays a VALUE in source rather than a string, and this is the one place it becomes
+ * the text the registry stores: a typo'd `operationId` or a parameter with no `in` is then a
+ * compile error at the document, where `satisfies OpenAPIV3_1.Document` can see it.
+ *
+ * `document` is deliberately structural here rather than typed against `openapi-types`, which
+ * would put that package in every consumer's type resolution for a helper that only serializes.
+ * Two-space indentation because an agent reads the body verbatim.
+ */
+export declare function openApiContract(params: {
+    contractId: string;
+    title: string;
+    document: Record<string, unknown>;
+}): UploadApiContract;
+//# sourceMappingURL=define.d.ts.map

package/dist/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,yBAAyB,EACzB,yBAAyB,EACzB,yBAAyB,EACzB,iBAAiB,EAClB,MAAM,wBAAwB,CAAA;AAoB/B;;;;;;;;;;GAUG;AACH,MAAM,WAAW,oBAAqB,SAAQ,yBAAyB;IACrE,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,YAAY,EAAE,yBAAyB,EAAE,CAAA;IACzC,SAAS,EAAE,iBAAiB,EAAE,CAAA;IAC9B,WAAW,EAAE,yBAAyB,EAAE,CAAA;CACzC;AAED,+EAA+E;AAC/E,MAAM,WAAW,oBAAoB;IACnC,gFAAgF;IAChF,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAA;IACf,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAA;IACnB,mDAAmD;IACnD,UAAU,EAAE,SAAS,yBAAyB,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,EAAE,CAAA;IACtE,0EAA0E;IAC1E,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAA;IACnD;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,yBAAyB,CAAC,SAAS,CAAC,CAAA;IAC9C,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,WAAW,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAA;IAClD,kFAAkF;IAClF,SAAS,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAA;CACzC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,oBAAoB,GAAG,oBAAoB,CA6BvF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE;IACtC,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC,GAAG,iBAAiB,CAOpB"}

package/dist/define.js

@@ -0,0 +1,69 @@
+import { binaryGeneratorDefinitionSchema } from '@cat-factory/contracts';
+import { binaryGeneratorDetailIssues } from '@cat-factory/kernel';
+import * as v from 'valibot';
+/**
+ * Validate an integration definition and freeze it.
+ *
+ * Two checks, and they are the SAME two the engine makes at boot rather than an approximation of
+ * them. `binaryGeneratorDefinitionSchema` is the shape every write path shares, and
+ * `binaryGeneratorDetailIssues` is the rule set a parse structurally cannot make (a cleartext
+ * endpoint, a contract set that reads as garbage to the agent handed it, a media type whose
+ * modality contradicts the declared ones, a harness with no generation tool, an accepted-value set
+ * with no capability behind it). Calling them rather than restating them is the whole point of the
+ * seam: a rule the platform adds fails this definition on the version bump instead of on the boot
+ * that follows a deploy.
+ *
+ * What it does NOT check is the one thing no schema could: whether a declared capability is one the
+ * registered CONTRACT can actually be asked for. That is a claim about a vendor's request body, so
+ * it is pinned per integration in a test beside the document.
+ */
+export function defineBinaryGenerator(input) {
+    const parsed = v.parse(binaryGeneratorDefinitionSchema, {
+        ...input,
+        modalities: [...input.modalities],
+        mediaTypes: [...(input.mediaTypes ?? [])],
+        capabilities: [...(input.capabilities ?? [])],
+        credentials: (input.credentials ?? []).map((credential) => ({ ...credential })),
+        contracts: (input.contracts ?? []).map((contract) => ({ ...contract })),
+    });
+    const issues = binaryGeneratorDetailIssues(parsed);
+    if (issues.length > 0) {
+        throw new Error(`Binary generator '${parsed.id}': ${issues.map((i) => i.message).join('; ')}`);
+    }
+    return Object.freeze({
+        ...parsed,
+        mediaTypes: parsed.mediaTypes ?? [],
+        // Settled to an array like the two beside it, and settling it changes NOTHING about how it is
+        // read: the coverage rule treats an empty capability list and an absent one as the same
+        // documented state ("only the coarse facts are known"), and the registry's own projection
+        // settles it to `[]` on the way to the engine either way.
+        capabilities: parsed.capabilities ?? [],
+        contracts: parsed.contracts ?? [],
+        // Settled for the same reason `contracts` is: every reader here loops rather than branching on
+        // one optional object, and a loop over `undefined` is the one shape that does not degrade
+        // quietly. `accepts` is deliberately NOT settled beside these, since an empty object and an
+        // absent one are the same fact there while an empty ARRAY inside one is refused, so
+        // manufacturing one would invent a refusal nobody declared.
+        credentials: parsed.credentials ?? [],
+    });
+}
+/**
+ * Turn an OpenAPI document written as a TypeScript object into the uploadable contract shape.
+ *
+ * The document stays a VALUE in source rather than a string, and this is the one place it becomes
+ * the text the registry stores: a typo'd `operationId` or a parameter with no `in` is then a
+ * compile error at the document, where `satisfies OpenAPIV3_1.Document` can see it.
+ *
+ * `document` is deliberately structural here rather than typed against `openapi-types`, which
+ * would put that package in every consumer's type resolution for a helper that only serializes.
+ * Two-space indentation because an agent reads the body verbatim.
+ */
+export function openApiContract(params) {
+    return {
+        contractId: params.contractId,
+        format: 'openapi',
+        title: params.title,
+        body: `${JSON.stringify(params.document, null, 2)}\n`,
+    };
+}
+//# sourceMappingURL=define.js.map

package/dist/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,+BAA+B,EAAE,MAAM,wBAAwB,CAAA;AACxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAA;AACjE,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AA8E5B;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAA2B;IAC/D,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,+BAA+B,EAAE;QACtD,GAAG,KAAK;QACR,UAAU,EAAE,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC;QACjC,UAAU,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;QACzC,YAAY,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC;QAC7C,WAAW,EAAE,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,UAAU,EAAE,CAAC,CAAC;QAC/E,SAAS,EAAE,CAAC,KAAK,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;KACxE,CAAC,CAAA;IACF,MAAM,MAAM,GAAG,2BAA2B,CAAC,MAAM,CAAC,CAAA;IAClD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,qBAAqB,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAChG,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,MAAM;QACT,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,EAAE;QACnC,8FAA8F;QAC9F,wFAAwF;QACxF,0FAA0F;QAC1F,0DAA0D;QAC1D,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,EAAE;QACvC,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,EAAE;QACjC,+FAA+F;QAC/F,0FAA0F;QAC1F,4FAA4F;QAC5F,oFAAoF;QACpF,4DAA4D;QAC5D,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,EAAE;KACtC,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,MAI/B;IACC,OAAO;QACL,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,MAAM,EAAE,SAAS;QACjB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI;KACtD,CAAA;AACH,CAAC"}

package/dist/generators/nano-banana.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The environment variable the Gemini API key is delivered as.
+ *
+ * Both what the deployment's `ToolSecretResolver` is asked for and the variable name the agent
+ * reads inside its run container, which is why it is a POSIX identifier rather than the header it
+ * ends up in (`x-goog-api-key`).
+ *
+ * Named for the VENDOR rather than for this definition's id: `GEMINI_API_KEY` is the variable
+ * Google's own `google-genai` client libraries read from the environment, so an agent that reaches
+ * for a library instead of writing the request by hand finds the value where the library looks.
+ * That is also why this definition needs no `envName`: the lookup key and the injected name are
+ * already the same string.
+ *
+ * It sits outside `isReservedPlatformEnvKey`'s set, which the tests assert rather than assume. The
+ * platform's own Google models are reached through OpenRouter (`OPENROUTER_*`), so no family here
+ * covers this name; if one ever does, the lookup resolves nothing and "no credential" looks exactly
+ * like an unset variable. Never document it in `docs/environment-variables.md` either: every
+ * variable named there is reserved by `check-reserved-env-keys.mjs`, which would retire this key.
+ *
+ * A workspace sets it as a capability credential (`binary-generator` subject, key `GEMINI_API_KEY`)
+ * or the deployment sets it in the environment its runs dispatch from.
+ */
+export declare const NANO_BANANA_CREDENTIAL_KEY = "GEMINI_API_KEY";
+/**
+ * The registry id a step names in `stepOptions.binaryOutput.generatorIds`, re-exported from
+ * `@cat-factory/contracts` rather than spelled here.
+ *
+ * The id has two authors that must agree: this definition, and the built-in `pl_media` preset in
+ * kernel's seed catalog, which selects it. Kernel cannot import this package (this package depends
+ * on kernel), so the shared layer below both owns the string and each side reads it.
+ */
+export { NANO_BANANA_GENERATOR_ID } from '@cat-factory/contracts';
+/**
+ * `nano-banana`: Google's Gemini image models, and the platform's FIRST shipped generative binary
+ * integration.
+ *
+ * Three facts about where it sits.
+ *
+ * **It is the only one the platform ships**, which is a change of position rather than a first
+ * step down a list. The registry stayed empty on the argument that no image generator is one every
+ * organisation runs and every one of them is metered. Both halves are still true and neither one
+ * decides this: what shipping the Media task type showed is that a step selecting NOTHING leaves
+ * the deployment's most demonstrable capability reachable only by a deployment that first writes
+ * an integration, an OpenAPI document and a credential declaration. Metered is handled by the
+ * credential (unset means the agent is told the integration is unavailable and reports the gap),
+ * so the cost of shipping one is a picker entry a deployment can ignore, against a task type that
+ * generates nothing out of the box.
+ *
+ * **It is SYNCHRONOUS**, which is unusual for this class of API and is most of what its guidance
+ * spends its words on. No task id, no polling loop, no signed URL with minutes on it: the bytes
+ * come back on the create call. The failure mode that replaces them is quieter than any of those,
+ * because a refused prompt answers 200 with text and no image at all.
+ *
+ * **It emits `image/png` and `image/jpeg`**, the two values `response_format.mime_type` takes and
+ * the whole of what this API returns. A step needing a vector or an animated GIF is refused for
+ * holding this alone, correctly, and pointed at whatever the deployment registered beside it.
+ *
+ * @see https://ai.google.dev/gemini-api/docs/image-generation
+ */
+export declare const nanoBananaGenerator: import("../define.js").BinaryGeneratorEntry;
+//# sourceMappingURL=nano-banana.d.ts.map

package/dist/generators/nano-banana.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nano-banana.d.ts","sourceRoot":"","sources":["../../src/generators/nano-banana.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,0BAA0B,mBAAmB,CAAA;AAE1D;;;;;;;GAOG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAA;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,mBAAmB,6CA8G9B,CAAA"}

package/dist/generators/nano-banana.js

@@ -0,0 +1,173 @@
+import { NANO_BANANA_GENERATOR_ID } from '@cat-factory/contracts';
+import { NANO_BANANA_OPENAPI } from '../contracts/nano-banana.openapi.js';
+import { defineBinaryGenerator, openApiContract } from '../define.js';
+/**
+ * The environment variable the Gemini API key is delivered as.
+ *
+ * Both what the deployment's `ToolSecretResolver` is asked for and the variable name the agent
+ * reads inside its run container, which is why it is a POSIX identifier rather than the header it
+ * ends up in (`x-goog-api-key`).
+ *
+ * Named for the VENDOR rather than for this definition's id: `GEMINI_API_KEY` is the variable
+ * Google's own `google-genai` client libraries read from the environment, so an agent that reaches
+ * for a library instead of writing the request by hand finds the value where the library looks.
+ * That is also why this definition needs no `envName`: the lookup key and the injected name are
+ * already the same string.
+ *
+ * It sits outside `isReservedPlatformEnvKey`'s set, which the tests assert rather than assume. The
+ * platform's own Google models are reached through OpenRouter (`OPENROUTER_*`), so no family here
+ * covers this name; if one ever does, the lookup resolves nothing and "no credential" looks exactly
+ * like an unset variable. Never document it in `docs/environment-variables.md` either: every
+ * variable named there is reserved by `check-reserved-env-keys.mjs`, which would retire this key.
+ *
+ * A workspace sets it as a capability credential (`binary-generator` subject, key `GEMINI_API_KEY`)
+ * or the deployment sets it in the environment its runs dispatch from.
+ */
+export const NANO_BANANA_CREDENTIAL_KEY = 'GEMINI_API_KEY';
+/**
+ * The registry id a step names in `stepOptions.binaryOutput.generatorIds`, re-exported from
+ * `@cat-factory/contracts` rather than spelled here.
+ *
+ * The id has two authors that must agree: this definition, and the built-in `pl_media` preset in
+ * kernel's seed catalog, which selects it. Kernel cannot import this package (this package depends
+ * on kernel), so the shared layer below both owns the string and each side reads it.
+ */
+export { NANO_BANANA_GENERATOR_ID } from '@cat-factory/contracts';
+/**
+ * `nano-banana`: Google's Gemini image models, and the platform's FIRST shipped generative binary
+ * integration.
+ *
+ * Three facts about where it sits.
+ *
+ * **It is the only one the platform ships**, which is a change of position rather than a first
+ * step down a list. The registry stayed empty on the argument that no image generator is one every
+ * organisation runs and every one of them is metered. Both halves are still true and neither one
+ * decides this: what shipping the Media task type showed is that a step selecting NOTHING leaves
+ * the deployment's most demonstrable capability reachable only by a deployment that first writes
+ * an integration, an OpenAPI document and a credential declaration. Metered is handled by the
+ * credential (unset means the agent is told the integration is unavailable and reports the gap),
+ * so the cost of shipping one is a picker entry a deployment can ignore, against a task type that
+ * generates nothing out of the box.
+ *
+ * **It is SYNCHRONOUS**, which is unusual for this class of API and is most of what its guidance
+ * spends its words on. No task id, no polling loop, no signed URL with minutes on it: the bytes
+ * come back on the create call. The failure mode that replaces them is quieter than any of those,
+ * because a refused prompt answers 200 with text and no image at all.
+ *
+ * **It emits `image/png` and `image/jpeg`**, the two values `response_format.mime_type` takes and
+ * the whole of what this API returns. A step needing a vector or an animated GIF is refused for
+ * holding this alone, correctly, and pointed at whatever the deployment registered beside it.
+ *
+ * @see https://ai.google.dev/gemini-api/docs/image-generation
+ */
+export const nanoBananaGenerator = defineBinaryGenerator({
+    id: NANO_BANANA_GENERATOR_ID,
+    name: 'Nano Banana',
+    summary: 'Google’s Gemini image models: conversational generation and reference-guided editing up to 4K, with strong in-image text rendering, returned synchronously as inline bytes and charged per image.',
+    modalities: ['image'],
+    // The two values `response_format.mime_type` takes. Declare only what a step may REQUIRE: both
+    // of these can be asked for by name, so both are safe to state. An integration whose container
+    // is whatever the response happens to carry declares the one it always produces and no more.
+    mediaTypes: ['image/png', 'image/jpeg'],
+    // What a step may ASK this integration for. One operation carries all of it, where most image
+    // APIs split the same work across two calls or lack a piece of it.
+    //
+    //  - `reference-image` / `multi-reference`: `image` blocks in `input`, up to fourteen on one
+    //    request.
+    //  - `instruction-edit`: the same operation, an `image` block plus a `text` block saying what to
+    //    change. Editing is not a separate endpoint here, which is what makes "the same character,
+    //    now facing left" a request rather than a re-roll.
+    //  - `seed`: `generation_config.seed`.
+    //  - `aspect-ratio`: `response_format.aspect_ratio`, a CLOSED list of ten, stated as an `accepts`
+    //    set below so a ratio outside it is refused by name rather than generated at the nearest one
+    //    and silently cropped.
+    //
+    // Absent, and each for a reason the endpoint states rather than a preference:
+    //
+    //  - `mask-edit`: no mask parameter. Conversational editing rewrites the whole picture, which is
+    //    a different act from repainting a named region.
+    //  - `negative-prompt`: no such field; what to keep out goes in the brief.
+    //  - `candidate-batch`: one interaction returns one image. Several candidates are several
+    //    requests, each charged, which is what the comparison surface does with it.
+    //  - `exact-size`: `image_size` is a resolution LADDER (`512px`, `1K`, `2K`, `4K`) rather than a
+    //    width and a height, so this endpoint cannot be handed dimensions at all. A step needing
+    //    96x96 is refused here rather than served a 1K render downscaled by whoever wrote the call.
+    //  - `upscale`: the same ladder, for the same reason: it is not a multiple of a native size.
+    //  - `transparent-background`: PNG is offered, alpha is not a request parameter.
+    //  - `tileable`: no parameter.
+    capabilities: ['reference-image', 'multi-reference', 'instruction-edit', 'seed', 'aspect-ratio'],
+    // The enum is declared VERBATIM rather than pre-reduced, and `21:9` is why that is safe: it
+    // reduces to `7:3`, the platform compares in lowest terms at both ends, so a step asking for
+    // `7:3` is served. Reducing the set by hand would gain nothing and lose the correspondence to the
+    // document beside it, which is what the tests check.
+    //
+    // No `outputSizes` beside it, deliberately: this endpoint takes no dimensions, so it declares
+    // neither `exact-size` nor a size set.
+    accepts: {
+        aspectRatios: ['1:1', '3:2', '2:3', '3:4', '4:3', '4:5', '5:4', '9:16', '16:9', '21:9'],
+    },
+    endpoint: 'https://generativelanguage.googleapis.com',
+    credentials: [
+        {
+            key: NANO_BANANA_CREDENTIAL_KEY,
+            usage: 'x-goog-api-key: <value> (an API key from Google AI Studio)',
+            required: true,
+        },
+    ],
+    contracts: [
+        openApiContract({
+            contractId: 'nano-banana-api',
+            title: 'Gemini Interactions API (Nano Banana image generation and editing)',
+            document: NANO_BANANA_OPENAPI,
+        }),
+    ],
+    description: `Generates and EDITS images from a written brief and up to fourteen reference images, and hands the bytes back on the same call. Two things make it worth reaching for: it renders long, legible text inside a picture better than most image APIs (signage, UI mockups, labelled diagrams, a title card that has to say the actual title), and it edits conversationally, so "the same character, now facing left, keep the armour" is a request rather than a re-roll.
+
+## Which model
+
+| Model | Resolutions | ~Cost / image | Use it for |
+| --- | --- | --- | --- |
+| **\`gemini-3.1-flash-lite-image\`** | 1K only | $0.034 | Drafting and thumbnails, where several cheap tries beat one considered one. |
+| **\`gemini-3.1-flash-image\`** | 512px, 1K, 2K, 4K | $0.045-0.151 | The default. Everything that is not specifically a typography or identity problem. |
+| **\`gemini-3-pro-image\`** | 1K, 2K, 4K | $0.134-0.24 | The image you keep when it has words in it, or when a character has to survive into a set. |
+
+Cost is per IMAGE and rises with resolution, so the size is the budget. \`image_size\` is a closed set of four strings rather than a pixel count, so a deliverable's real dimensions are reached by generating the nearest one and resizing.
+
+## Getting the same thing twice
+
+Reference images, and a conversation. Up to fourteen ride a single request (the pro model reads them as roughly six objects, five characters and three style references), which is how a character, a prop or a palette survives into a second generation. Reusing a \`seed\` holds a composition while the prompt changes; it does not hold a subject.
+
+## What it is not for
+
+- **Not pixel art.** This returns a smooth render, and shrinking one to 32px is a different asset that costs the same. Sprites, tilesets and item icons want an integration that draws on a pixel grid at native size, which a deployment registers beside this one.
+- **Not a vector, and not an animation.** It emits \`image/png\` and \`image/jpeg\` and nothing else, so a step declaring \`image/svg+xml\` or \`image/gif\` is refused for holding this alone.
+- **Not a deliverable at an exact pixel size.** \`image_size\` is a ladder of four buckets, so a step whose requirement IS 96x96 is refused rather than handed a downscale nobody chose.
+- **Not a masked editor.** Editing here rewrites the whole picture from a sentence, so a step whose work is "fix this corner and touch nothing else" is refused at admission rather than handed a whole-image regeneration that looks like a fix.
+- **Not 3D, audio, video or documents.** It declares \`image\` alone. A step that must also deliver a mesh needs an integration that makes one selected too, and admission refuses the step rather than letting it discover the gap at the end of a paid run.
+- **Not a general Gemini client.** The registered contract is one operation. Text generation, function calling, code execution, the research agents, streaming and stored multi-turn interactions are all on this endpoint and none is registered. Grounding with Google Search is the pointed omission: it bills separately once the monthly free searches are gone, and a step asked to draw a scout has no business searching the web to do it.
+- **Not unwatermarked.** Every image carries an invisible SynthID watermark. It is a fact to know about the deliverable, not a problem to route around.
+- **Not free, and not free-tier.** None of these models has one, so a project without billing enabled gets \`FAILED_PRECONDITION\` on the first call. There is no balance read and no dry run on this API at all: the request that discovers an exhausted quota is a real one.
+- **Not a source of art direction.** It renders the brief it is given. What the subject looks like comes from the task and the step's context services, not from here.`,
+    guidance: `Base URL \`https://generativelanguage.googleapis.com\`. Send \`x-goog-api-key: $${NANO_BANANA_CREDENTIAL_KEY}\` as a HEADER on every request, not as a \`?key=\` query parameter, which puts the credential in logs. If that variable is unset the platform could not provide the credential: do NOT call the API and do not invent a key; report the gap as the reason the artifact is missing.
+
+**This one is synchronous.** \`POST /v1beta/interactions\` returns the finished image inline. There is no task id, no polling loop, no expiring link, and nothing to recover if a response is lost, so a dropped connection is a charge with no artifact: treat one request as one attempt.
+
+**The loop that works**
+
+1. Pick the model from the job, not from habit: \`gemini-3.1-flash-lite-image\` to draft, \`gemini-3.1-flash-image\` by default, \`gemini-3-pro-image\` when the image carries text or a character has to stay recognisable. The lite model serves \`1K\` alone, so asking it for \`4K\` is a request that cannot be served.
+2. Size the request from the TARGET. \`image_size\` takes \`512px\`, \`1K\`, \`2K\` or \`4K\` and \`aspect_ratio\` takes one of ten fixed ratios, so pick the smallest bucket that covers what the step asked for and resize the bytes afterwards rather than expecting an exact pixel count.
+3. Send the brief as one \`text\` block describing the PICTURE: subject, framing, materials, lighting, and the words to render if any. A paragraph beats a keyword list here, and text in the brief is rendered literally.
+4. Set \`response_format\` deliberately: \`"type": "image"\` so the model does not answer in prose, and \`mime_type\` \`image/png\` for flat colour, transparency or anything a later step cuts up. \`image/jpeg\` only for a finished photographic image.
+5. Leave \`thinking_level\` at \`minimal\` for a brief that already says what the picture is; raise it to \`high\` for dense composition or a lot of in-image text. The interim images it draws are not charged, but the thinking tokens are.
+6. **Check that you got an image.** A declined request is not an error status: it answers 200 with \`output_text\` explaining and NO \`output_image\`. Treat that as terminal and REWRITE the brief, since resubmitting the same words buys the same refusal at the same price.
+7. Decode \`output_image.data\` from raw base64 (there is no \`data:\` prefix) and store the bytes, using \`output_image.mime_type\` as the content type rather than the one you asked for. Read \`usage.total_output_tokens\` for what it cost; it is the only accounting this API gives.
+
+**Where this step's generation options land on this API.** The brief lists them once, in the platform's words; these are the fields that carry them here, and all of them ride the ONE request. Reference images are \`image\` blocks in \`input\`, up to fourteen, as raw base64 \`data\` rather than a \`uri\`. An instruction edit is an \`image\` block plus the \`text\` block saying what to change; there is no separate edit operation to switch to. A fixed seed is \`generation_config.seed\`. An aspect ratio is \`response_format.aspect_ratio\`, whose ten values are the whole of the list. A negative prompt, a masked edit, a transparent background and a tiling texture have no parameter here at all: report any of them as unmet rather than writing them into the brief and hoping.
+
+**Holding a set together.** Send the first image back as an \`image\` block in the next request's \`input\`, alongside the text that says what to change: that is the edit path, and it is how a turnaround or a variant stays the same character. Send bytes as base64 \`data\` rather than \`uri\`, because Google fetches a \`uri\` from its own network and cannot read a link that needs the platform's credentials.
+
+**Storing what you generated.** Bytes go to the step's configured storage service, never to the repository and never inline in a report, and the storage contract in your context says how. Declare the real content type (\`image/png\` or \`image/jpeg\`) rather than \`application/octet-stream\`.
+
+**Failures worth telling apart.** They all arrive as \`{"error": {"code", "message", "status"}}\`, and the status matters more than the HTTP code. \`INVALID_ARGUMENT\` (400) is a malformed body AND what an invalid key returns, so read the message. \`FAILED_PRECONDITION\` (400) is billing not enabled, which is a gap to report rather than a retry. \`PERMISSION_DENIED\` (403) is a key with no entitlement to that model. \`RESOURCE_EXHAUSTED\` (429) is a rate limit on one of four dimensions (requests, input tokens, requests per DAY, and images per minute, which is the one peculiar to these models), so back off exponentially and do not assume a minute clears it. \`INTERNAL\` (500) and \`UNAVAILABLE\` (503) are transient: retry with backoff rather than switching models, since a different model draws a different picture.`,
+});
+//# sourceMappingURL=nano-banana.js.map

package/dist/generators/nano-banana.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nano-banana.js","sourceRoot":"","sources":["../../src/generators/nano-banana.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAA;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAA;AACzE,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAErE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,gBAAgB,CAAA;AAE1D;;;;;;;GAOG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAA;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,qBAAqB,CAAC;IACvD,EAAE,EAAE,wBAAwB;IAC5B,IAAI,EAAE,aAAa;IACnB,OAAO,EACL,mMAAmM;IACrM,UAAU,EAAE,CAAC,OAAO,CAAC;IACrB,+FAA+F;IAC/F,+FAA+F;IAC/F,6FAA6F;IAC7F,UAAU,EAAE,CAAC,WAAW,EAAE,YAAY,CAAC;IACvC,8FAA8F;IAC9F,mEAAmE;IACnE,EAAE;IACF,6FAA6F;IAC7F,cAAc;IACd,iGAAiG;IACjG,+FAA+F;IAC/F,uDAAuD;IACvD,uCAAuC;IACvC,kGAAkG;IAClG,iGAAiG;IACjG,2BAA2B;IAC3B,EAAE;IACF,8EAA8E;IAC9E,EAAE;IACF,iGAAiG;IACjG,qDAAqD;IACrD,2EAA2E;IAC3E,0FAA0F;IAC1F,gFAAgF;IAChF,iGAAiG;IACjG,6FAA6F;IAC7F,gGAAgG;IAChG,6FAA6F;IAC7F,iFAAiF;IACjF,+BAA+B;IAC/B,YAAY,EAAE,CAAC,iBAAiB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,EAAE,cAAc,CAAC;IAChG,4FAA4F;IAC5F,6FAA6F;IAC7F,kGAAkG;IAClG,qDAAqD;IACrD,EAAE;IACF,8FAA8F;IAC9F,uCAAuC;IACvC,OAAO,EAAE;QACP,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;KACxF;IACD,QAAQ,EAAE,2CAA2C;IACrD,WAAW,EAAE;QACX;YACE,GAAG,EAAE,0BAA0B;YAC/B,KAAK,EAAE,4DAA4D;YACnE,QAAQ,EAAE,IAAI;SACf;KACF;IACD,SAAS,EAAE;QACT,eAAe,CAAC;YACd,UAAU,EAAE,iBAAiB;YAC7B,KAAK,EAAE,oEAAoE;YAC3E,QAAQ,EAAE,mBAAmB;SAC9B,CAAC;KACH;IACD,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;uKA0BwJ;IACrK,QAAQ,EAAE,mFAAmF,0BAA0B;;;;;;;;;;;;;;;;;;;;yzBAoBgsB;CACxzB,CAAC,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+import type { BinaryGeneratorRegistry } from '@cat-factory/kernel';
+import type { BinaryGeneratorEntry } from './define.js';
+export { type BinaryGeneratorEntry, type BinaryGeneratorInput, defineBinaryGenerator, openApiContract, } from './define.js';
+export { NANO_BANANA_CREDENTIAL_KEY, NANO_BANANA_GENERATOR_ID, nanoBananaGenerator, } from './generators/nano-banana.js';
+export { NANO_BANANA_OPENAPI } from './contracts/nano-banana.openapi.js';
+/**
+ * The integrations the platform ships, in registration order.
+ *
+ * Exported as data so a deployment can register a SUBSET (or none) onto its own registry instance
+ * without reaching into this package's internals, and so a test can assert over the shipped set
+ * rather than over whatever a helper happened to install.
+ */
+export declare const BUILTIN_BINARY_GENERATORS: readonly BinaryGeneratorEntry[];
+/**
+ * Install the built-in integrations onto an app-owned registry instance, and return it.
+ *
+ * Idempotent by id: registering twice replaces rather than duplicates, so an entry point a test
+ * also drives is safe to call again. Registration ORDER is what makes a deployment's own
+ * definition of a shipped id an override, so the built-ins go first.
+ */
+export declare function registerBuiltinBinaryGenerators(registry: BinaryGeneratorRegistry, generators?: readonly BinaryGeneratorEntry[]): BinaryGeneratorRegistry;
+/**
+ * A fresh {@link BinaryGeneratorRegistry} carrying the shipped integrations.
+ *
+ * What each facade defaults to when a deployment injects no registry of its own, exactly as
+ * `gateRegistryWithBuiltins()` and `promptFragmentRegistryWithBuiltins()` are. An INJECTED registry
+ * replaces this one rather than merging with it, so a deployment that wants its own integrations
+ * AND the shipped ones starts from this call and registers onto the same instance:
+ *
+ *     const binaryGeneratorRegistry = binaryGeneratorRegistryWithBuiltins()
+ *     binaryGeneratorRegistry.registerAll(myIntegrations)
+ *     startLocal({ binaryGeneratorRegistry })
+ *
+ * That matters more here than for the other two registries, because the shipped `pl_media` preset
+ * SELECTS `nano-banana` by id: a registry without it refuses that pipeline's runs at admission
+ * (`binary_output_generator_invalid`) rather than degrading, which is the correct disposition for
+ * a step naming an integration nobody registered and a loud one to meet on upgrade.
+ *
+ * Registered ONCE per deployment, on the process that owns the registry. In mothership mode that
+ * is the mothership: a node resolves integrations over `/internal/binary-generators` and consults
+ * no registry of its own, so the set the pipeline builder offers and the set admission resolves
+ * are one set however far behind the node's build has drifted.
+ */
+export declare function binaryGeneratorRegistryWithBuiltins(): BinaryGeneratorRegistry;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAA;AAElE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AA2BvD,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,qBAAqB,EACrB,eAAe,GAChB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAA;AAExE;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,oBAAoB,EAA0B,CAAA;AAE/F;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,uBAAuB,EACjC,UAAU,GAAE,SAAS,oBAAoB,EAA8B,GACtE,uBAAuB,CAGzB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mCAAmC,IAAI,uBAAuB,CAE7E"}

package/dist/index.js

@@ -0,0 +1,73 @@
+import { defaultBinaryGeneratorRegistry } from '@cat-factory/kernel';
+import { nanoBananaGenerator } from './generators/nano-banana.js';
+// ---------------------------------------------------------------------------
+// The built-in generative binary integrations, authored ENTIRELY through the public
+// binary-generator seam: this package depends on @cat-factory/kernel + @cat-factory/contracts and
+// never on the engine. It is the same dogfood `@cat-factory/gates` and
+// `@cat-factory/prompt-fragments` are: if the platform's own image integration can be expressed as
+// an external package, so can a deployment's, and the seam cannot rot for consumers only because
+// every boot exercises it.
+//
+// The registry itself stays EMPTY by default (`defaultBinaryGeneratorRegistry()`). A facade
+// chooses: `binaryGeneratorRegistryWithBuiltins()` is what the shipped runtimes default to, and a
+// deployment that wants a different set news its own instance. The two are opposite deployments
+// and both are legitimate, which is why neither is baked into the registry class.
+//
+// WHY THE PLATFORM SHIPS ONE AT ALL. The registry shipped empty on the argument that no image
+// generator is one every organisation runs and that every one of them is metered. Both halves
+// are still true. What changed is that the Media task type shipped a generating agent, a preset
+// and the storage under it, and left the selection blank: the platform's most demonstrable
+// capability was the one nothing shipped could exercise, and closing that gap took a deployment
+// writing an integration, an OpenAPI document and a credential declaration first. Metered is
+// answered by the credential rather than by the registry: with no key resolved the agent is told
+// the integration is unavailable and reports it as the reason an artifact is missing, so a
+// deployment that ignores this entry pays nothing and sees one extra row in a picker.
+// ---------------------------------------------------------------------------
+export { defineBinaryGenerator, openApiContract, } from './define.js';
+export { NANO_BANANA_CREDENTIAL_KEY, NANO_BANANA_GENERATOR_ID, nanoBananaGenerator, } from './generators/nano-banana.js';
+export { NANO_BANANA_OPENAPI } from './contracts/nano-banana.openapi.js';
+/**
+ * The integrations the platform ships, in registration order.
+ *
+ * Exported as data so a deployment can register a SUBSET (or none) onto its own registry instance
+ * without reaching into this package's internals, and so a test can assert over the shipped set
+ * rather than over whatever a helper happened to install.
+ */
+export const BUILTIN_BINARY_GENERATORS = [nanoBananaGenerator];
+/**
+ * Install the built-in integrations onto an app-owned registry instance, and return it.
+ *
+ * Idempotent by id: registering twice replaces rather than duplicates, so an entry point a test
+ * also drives is safe to call again. Registration ORDER is what makes a deployment's own
+ * definition of a shipped id an override, so the built-ins go first.
+ */
+export function registerBuiltinBinaryGenerators(registry, generators = BUILTIN_BINARY_GENERATORS) {
+    registry.registerAll(generators);
+    return registry;
+}
+/**
+ * A fresh {@link BinaryGeneratorRegistry} carrying the shipped integrations.
+ *
+ * What each facade defaults to when a deployment injects no registry of its own, exactly as
+ * `gateRegistryWithBuiltins()` and `promptFragmentRegistryWithBuiltins()` are. An INJECTED registry
+ * replaces this one rather than merging with it, so a deployment that wants its own integrations
+ * AND the shipped ones starts from this call and registers onto the same instance:
+ *
+ *     const binaryGeneratorRegistry = binaryGeneratorRegistryWithBuiltins()
+ *     binaryGeneratorRegistry.registerAll(myIntegrations)
+ *     startLocal({ binaryGeneratorRegistry })
+ *
+ * That matters more here than for the other two registries, because the shipped `pl_media` preset
+ * SELECTS `nano-banana` by id: a registry without it refuses that pipeline's runs at admission
+ * (`binary_output_generator_invalid`) rather than degrading, which is the correct disposition for
+ * a step naming an integration nobody registered and a loud one to meet on upgrade.
+ *
+ * Registered ONCE per deployment, on the process that owns the registry. In mothership mode that
+ * is the mothership: a node resolves integrations over `/internal/binary-generators` and consults
+ * no registry of its own, so the set the pipeline builder offers and the set admission resolves
+ * are one set however far behind the node's build has drifted.
+ */
+export function binaryGeneratorRegistryWithBuiltins() {
+    return registerBuiltinBinaryGenerators(defaultBinaryGeneratorRegistry());
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,8BAA8B,EAAE,MAAM,qBAAqB,CAAA;AAEpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAEjE,8EAA8E;AAC9E,oFAAoF;AACpF,kGAAkG;AAClG,uEAAuE;AACvE,mGAAmG;AACnG,iGAAiG;AACjG,2BAA2B;AAC3B,EAAE;AACF,4FAA4F;AAC5F,kGAAkG;AAClG,gGAAgG;AAChG,kFAAkF;AAClF,EAAE;AACF,8FAA8F;AAC9F,8FAA8F;AAC9F,gGAAgG;AAChG,2FAA2F;AAC3F,gGAAgG;AAChG,6FAA6F;AAC7F,iGAAiG;AACjG,2FAA2F;AAC3F,sFAAsF;AACtF,8EAA8E;AAE9E,OAAO,EAGL,qBAAqB,EACrB,eAAe,GAChB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAA;AAExE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAoC,CAAC,mBAAmB,CAAC,CAAA;AAE/F;;;;;;GAMG;AACH,MAAM,UAAU,+BAA+B,CAC7C,QAAiC,EACjC,UAAU,GAAoC,yBAAyB;IAEvE,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,CAAA;IAChC,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,mCAAmC;IACjD,OAAO,+BAA+B,CAAC,8BAA8B,EAAE,CAAC,CAAA;AAC1E,CAAC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@cat-factory/binary-generators",
+  "version": "0.2.0",
+  "description": "The built-in generative binary integrations (Nano Banana, Google's Gemini image models) plus the authoring seam a deployment defines its own with, written entirely through the public BinaryGeneratorRegistry seam: depends only on @cat-factory/kernel + @cat-factory/contracts, never the engine.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kibertoad/cat-factory.git",
+    "directory": "backend/packages/binary-generators"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "valibot": "^1.4.2",
+    "@cat-factory/contracts": "0.317.0",
+    "@cat-factory/kernel": "0.305.0"
+  },
+  "devDependencies": {
+    "openapi-types": "^12.1.3",
+    "typescript": "7.0.2",
+    "vitest": "^4.1.10",
+    "@cat-factory/orchestration": "0.276.0",
+    "@cat-factory/agents": "0.133.1"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run"
+  }
+}