@route_33/opencode 0.4.6 → 0.4.7-rc.11

package/docs/gateway-limits-variants-broadcast.md

@@ -1,146 +0,0 @@
-# Gateway model metadata broadcast
-
-**To:** R33 gateway team  
-**From:** opencode-route33 plugin maintainers  
-**Date:** 2026-08-10  
-**Subject:** Shipped per-model metadata in `GET /v1/models`
-
-## Problem
-
-This document is the limits and variants sibling of the [gateway pricing broadcast proposal](./gateway-pricing-proposal.md) from 2026-07-07. That contract shipped and proved that extra JSON fields on the standard OpenAI-compatible `/v1/models` response do not break clients.
-
-The opencode-route33 plugin previously kept a static seed catalog with hardcoded `context_window`, `max_output_tokens`, capability flags, and variant definitions. That file has been deleted. The gateway already persists `context_window` and `max_output_tokens` on `canonical_models`, and the catalog now needs to treat variants as platform-curated data (for example, `kimi-k3`'s `max` variant that sets `reasoningEffort: "max"`). Without a broadcast contract, plugin consumers fall back to stale seed data or fabricated defaults, which violates the never-accept-loss principle for model metadata.
-
-This creates three gaps:
-
-1. **Stale or fabricated limits.** The plugin has no source of truth for token ceilings once the seed catalog is gone.
-2. **Variants out of sync.** Model-specific parameter variants (max reasoning effort, output style presets, and so on) must live with the curated catalog, not in a plugin-side JSON file.
-3. **New-model lag.** A model that appears in the gateway catalog without published limit/variant metadata is treated as a lossy fallback.
-
-## Recommendation
-
-**Status: shipped.** Each entry of the existing `GET /v1/models` response supports these optional metadata fields:
-
-- `limits`: `{ "context": number, "output": number }`, present only when both values are positive integers.
-- `variants`: `Record<string, Record<string, unknown>>`, passed through verbatim from the platform's curated catalog.
-- `modalities`: `{ "input": ["text"|"audio"|"image"|"video"|"pdf"], "output": ["text"|"audio"|"image"|"video"|"pdf"] }`.
-- `attachment`: boolean, derived by the gateway as true when `modalities.input` contains `image` or `pdf`.
-
-Existing unchanged fields (`id`, `object`, `created`, `owned_by`, plus optional `display_name`, `pricing`, `capabilities`, and `endpoints`) remain unchanged. Extra JSON fields still do not break OpenAI-compatible clients, so the catalog stays one round trip and atomically consistent.
-
-### Concrete JSON example
-
-```json
-{
-  "object": "list",
-  "data": [
-    {
-      "id": "anthropic/claude-opus-4-8",
-      "object": "model",
-      "created": 1767225600,
-      "owned_by": "anthropic",
-      "display_name": "Claude Opus 4.8",
-      "pricing": {
-        "input": 5,
-        "output": 25,
-        "cache_read": 0.5,
-        "cache_write": 6.25
-      },
-      "capabilities": {
-        "modality": "text",
-        "context_tier": "large",
-        "tool_support": true,
-        "structured_output": true,
-        "generation_class": "chat",
-        "reasoning": true
-      },
-      "endpoints": ["chat", "messages"],
-      "limits": {
-        "context": 1000000,
-        "output": 128000
-      },
-      "variants": {
-        "max": {
-          "reasoningEffort": "max"
-        }
-      },
-      "modalities": { "input": ["text", "image"], "output": ["text"] },
-      "attachment": true
-    }
-  ]
-}
-```
-
-### Field semantics
-
-| Field | Type | Meaning |
-| --- | --- | --- |
-| `id` | string | Canonical model identifier in `vendor/slug` form |
-| `object` | string | Always `"model"` |
-| `created` | integer | Unix epoch timestamp when the model was added to the catalog |
-| `owned_by` | string | Model vendor, matching the `vendor` portion of `id` |
-| `display_name` | string or omitted | Human-readable model label |
-| `pricing` | object or omitted | Pricing object as defined in the 2026-07-07 pricing broadcast |
-| `capabilities` | object or omitted | Structured capability flags |
-| `capabilities.modality` | string | Input/output modality, for example `"text"` |
-| `capabilities.context_tier` | string | Qualitative size class, for example `"large"` |
-| `capabilities.tool_support` | boolean | Native tool calling; mapped to opencode `tool_call` when `true` |
-| `capabilities.structured_output` | boolean | Native structured / JSON mode support |
-| `capabilities.generation_class` | string | Interaction style, for example `"chat"` |
-| `capabilities.reasoning` | boolean | Exposes reasoning or extended thinking; mapped to opencode `reasoning` when `true` |
-| `endpoints` | array of strings or omitted | Supported gateway endpoints, for example `["chat", "messages"]` |
-| `limits` | object or omitted | Per-model token limits |
-| `limits.context` | positive integer | Maximum context-window tokens |
-| `limits.output` | positive integer | Maximum completion tokens |
-| `variants` | object or omitted | Per-model parameter variants, a record of records |
-| `modalities` | object or omitted | Exact supported input and output media types |
-| `modalities.input` | array | Zero or more of `text`, `audio`, `image`, `video`, `pdf` |
-| `modalities.output` | array | Zero or more of `text`, `audio`, `image`, `video`, `pdf` |
-| `attachment` | boolean or omitted | Gateway-derived file/image support (`input` includes `image` or `pdf`) |
-
-### Consumer parse rules
-
-The opencode-route33 plugin consumes this shape with the following rules:
-
-- `limits` is accepted only when both `context` and `output` are present and are positive integers. Partial or invalid `limits` objects are ignored. This mirrors the models.dev `normalizeLimit` rule.
-- `capabilities.reasoning` with the boolean value `true` maps to opencode's `reasoning` flag. Any non-boolean value is skipped.
-- `capabilities.tool_support` with the boolean value `true` maps to opencode's `tool_call` flag. Any non-boolean value is skipped.
-- `variants` is accepted only when it is a `Record<string, Record<string, unknown>>` and is passed through verbatim. Malformed variants are skipped.
-- `modalities` is accepted only as an object with array `input` and `output` fields. Consumers drop unrecognized modality values; malformed modality shapes are omitted for that one model.
-- `attachment` is accepted only when boolean; a non-boolean value is omitted for that one model.
-- `capabilities.modality` is legacy qualitative metadata. `modalities` is the authoritative exact media contract.
-- Unknown or malformed fields are ignored. Parsing is never fatal.
-
-### Why embed limits and variants on `/v1/models`
-
-- **Single round trip.** The plugin fetches the catalog anyway, so embedding removes a second request for limit and variant metadata.
-- **No client breakage.** OpenAI-compatible consumers ignore unknown keys, so existing integrations keep working exactly as before.
-- **Curator is the source of truth.** The platform owns `canonical_models.context_window`, `canonical_models.max_output_tokens`, and the JSONB variants column, so the broadcast comes from the same place the gateway already trusts.
-- **No unit conversion or schema drift.** `limits.context` and `limits.output` are plain token counts, identical to opencode's internal limit schema, and `variants` is a passthrough of the platform JSONB value.
-
-## Curated-limits audit reference (models.dev parity, verified 2026-08-10)
-
-These entries were cross-checked against models.dev on 2026-08-10 and should be the values broadcast by the gateway:
-
-- Anthropic `claude-opus-4-8`, `claude-sonnet-5`, `claude-fable-5`: `1,000,000` context / `128,000` output
-- Anthropic `claude-haiku-4-5`: `200,000` context / `64,000` output
-- `moonshotai/kimi-k3`: `1,048,576` context / `131,072` output, with the `max` variant (`reasoningEffort: "max"`)
-- `minimax/minimax-m3`, `nvidia/nemotron-3-ultra`, and `mistralai/mistral-medium-3.5` keep their curated values (none of these appear in models.dev, so platform values stand).
-
-## Alternative: separate metadata endpoint
-
-If the gateway team prefers not to extend the standard `/v1/models` shape, a separate endpoint is acceptable:
-
-```
-GET /v1/models/metadata
-```
-
-It should return the same per-model fields and types documented above (`id`, `object`, `created`, `owned_by`, optional `display_name`, `pricing`, `capabilities`, `endpoints`, `limits`, and `variants`). The plugin would fetch this endpoint and merge the additional metadata with the catalog. The parse rules remain identical, only the HTTP envelope changes.
-
-## Secondary option (later)
-
-Publish route33 limit and variant metadata on models.dev via a community TOML PR. This is useful for non-gateway consumers, but it does not solve the key-scoped freshness problem or the single-round-trip goal. Recommended as a follow-up, not a substitute.
-
-## Future direction
-
-Broadcasting `reasoning_options` is deferred. The current shipped contract intentionally limits itself to limits, variants, modalities, attachment, pricing, and capabilities.

package/docs/gateway-pricing-proposal.md

@@ -1,96 +0,0 @@
-# Gateway pricing broadcast proposal
-
-**To:** R33 gateway team  
-**From:** opencode-route33 plugin maintainers  
-**Date:** 2026-07-07 (rev 2 — switched to the `input`/`output` per-1M vocabulary)  
-**Subject:** Embedding per-model pricing in `GET /v1/models`
-
-## Problem
-
-The route33.ai gateway exposes `GET /v1/models` for key-scoped catalog discovery, but the response carries no pricing metadata today. Downstream consumers (the opencode-route33 plugin, bench cost aggregation, and user-facing cost estimates) must source prices from an external registry (models.dev) and a hard-coded seed catalog. This creates three gaps:
-
-1. **Stale prices** — models.dev is community-maintained and can lag behind gateway rate changes.
-2. **Key-scoped pricing mismatch** — the gateway may offer tiered or negotiated rates per key; a global registry cannot express that.
-3. **New-model lag** — a model that appears in the gateway catalog but not in models.dev reports $0 cost until someone manually adds it to the seed.
-
-## Recommendation
-
-Embed a `pricing` object inside each entry of the existing `GET /v1/models` response, using the models.dev vocabulary: `input`, `output`, `cache_read`, `cache_write` as **numeric USD per 1M tokens**. Extra JSON fields do not break OpenAI-compatible clients, and key-scoped pricing rides the same key-scoped catalog response (one round trip, atomic catalog-plus-pricing consistency).
-
-### Concrete JSON example
-
-```json
-{
-  "object": "list",
-  "data": [
-    {
-      "id": "openai/gpt-5.5",
-      "object": "model",
-      "created": 1751234567,
-      "owned_by": "openai",
-      "pricing": {
-        "input": 5.0,
-        "output": 30.0,
-        "cache_read": 0.5,
-        "cache_write": 1.0
-      }
-    },
-    {
-      "id": "anthropic/claude-opus-4-8",
-      "object": "model",
-      "created": 1751234568,
-      "owned_by": "anthropic",
-      "pricing": {
-        "input": 5.0,
-        "output": 25.0,
-        "cache_read": 0.5,
-        "cache_write": 6.25
-      }
-    }
-  ]
-}
-```
-
-**Field semantics** (numeric USD **per 1M tokens**):
-
-| Field         | Meaning           |
-| ------------- | ----------------- |
-| `input`       | Input token rate  |
-| `output`      | Output token rate |
-| `cache_read`  | Cache read rate   |
-| `cache_write` | Cache write rate  |
-
-All values are JSON numbers representing the cost of **one million tokens** in USD. `input` and `output` are required for a pricing entry to be consumed; the cache fields are optional.
-
-### Why `input`/`output` per-1M numbers
-
-- **Terminology match** — `input`/`output` is route33's own token vocabulary, and the modern industry direction (OpenAI's Responses API and Anthropic's Messages API both report `input_tokens`/`output_tokens`).
-- **Consumer match** — this is byte-identical to opencode's native cost schema and the models.dev registry vocabulary, so the opencode-route33 plugin passes values through with **zero unit conversion**.
-- **Human-scale numbers** — `5.0` per 1M reads and reviews better than `"0.000005"` per token, and sidesteps the ecosystem trap of conflating per-token with per-1M values, which has caused real underpricing bugs in other provider plugins.
-
-### One vocabulary only (do not mix)
-
-The plugin also recognizes the OpenRouter vocabulary (`prompt`, `completion`, `input_cache_read`, `input_cache_write` as string USD **per token**) as an accepted alternative shape. **Pick exactly one vocabulary.** A payload mixing keys from both sets is ambiguous about units and is deliberately ignored by the plugin.
-
-### Alternative: byte-pure OpenAI surface
-
-If the gateway team prefers not to extend the standard `/v1/models` shape, a separate endpoint is acceptable:
-
-```
-GET /v1/models/pricing
-```
-
-With the **same vocabulary** (`input`, `output`, `cache_read`, `cache_write` as numeric USD-per-1M fields) and the same key-scoped semantics. The plugin would fetch this endpoint alongside the catalog and merge the pricing layer.
-
-## Zero plugin changes needed
-
-The opencode-route33 plugin already ships a **dual-shape pricing extractor** (decision D14) that is dormant today and will activate automatically the moment recognizable pricing fields appear:
-
-- **models.dev vocabulary** (numeric USD per 1M) → passed through unchanged. **(recommended)**
-- **OpenRouter vocabulary** (string USD per token) → converted `×1,000,000` to opencode's per-1M numbers.
-
-Adopting either the embedded or the separate-endpoint contract above requires **zero changes** to the plugin — the dormant path becomes active without a version bump.
-
-## Secondary option (later)
-
-Register route33 in models.dev via a community TOML PR. This is useful for non-gateway consumers, but it does not solve the key-scoped-pricing or stale-data problems. Recommended as a follow-up, not a substitute.