provider-openai
v1.2.24OpenAI Responses provider worker with Chat Completions compatibility; implements provider::openai::stream and provider::openai::refresh_models behind llm-router.
Install
bash
iii trigger compose::add worker=provider-openai@1.2.24Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.
Agent-ready brief for v1.2.24
Install, config, dependencies, readme, skills and API reference, all in one place. Fetch as agent-context.md for an LLM to consume.
Full markdown
The same content rendered as discrete blocks below is exposed as a single markdown document at
/workers/provider-openai.md?version=1.2.24. Paste it into an LLM prompt or pipe it through curl from a worker.Install
iii trigger compose::add worker=provider-openai@1.2.24Dependencies
Dependency · 2Version
Readme
README.md
provider-openai
OpenAI Responses provider worker behind llm-router, with a
Chat Completions compatibility path for custom gateways.
Implements the provider protocol from
tech-specs/2026-06-agentic/llm-router.md: provider::openai::stream
(SSE chunks → AssistantMessageEvent frames into a router-owned channel),
provider::openai::refresh_models (live GET /v1/models filtered to
chat/reasoning families ∪ curated capability snapshot →
router::models::reconcile), provider::openai::embed (batch text
embeddings behind router::embed; the endpoint derives from the configured
api_url, so OpenAI-compatible local servers — llama.cpp --embeddings,
Ollama, vLLM, LM Studio — and gateways work through the same surface), and
provider::openai::count_tokens (local prompt token estimation with the
tiktoken tokenizers behind router::count_tokens; never runs the model,
costs nothing, and needs no network).
Behavior
- Registration: self-declares via
router::provider::registerwith backoff until acked, and re-declares on therouter::readytrigger type. The model slice is populated from live discovery and the declaration carriescredential_env_var: OPENAI_API_KEY. - Transport: the default
https://api.openai.com/v1/responsesendpoint uses Responses items and typed streaming events. An explicitly configured endpoint that does not end in/responseskeeps the Chat Completions wire format for compatible gateways that have not migrated. - Identity binding: the router returns a
registration_tokenon first registration; it is persisted in state (scopeprovider-openai, keyregistration_token) and presented on every laterregister/resolve/reconcile. If that state is lost the router rejects re-registration — the operator must clear the binding on the router side. - Credentials: resolved per request via
router::provider::resolve(config slice →OPENAI_API_KEYenv on the router → none). Bothapi_keyandoauthcredential shapes are sent asAuthorization: Bearer; v1 performs no OAuth refresh. - Liveness:
pingat least every 30s of upstream silence; a failed channel write (caller gone /router::abort) drops the SSE receiver and aborts the in-flight HTTP request. - Errors: 401/403 →
auth_expired, 429 →rate_limited(exceptinsufficient_quota, a billing wall →permanent),context_length_exceeded→context_overflow, 5xx/network →transient, other 4xx →permanent. No transport retries here — the router owns retry policy. - Structured output: native. A
response_formatwith a schema maps to strictjson_schemamode; without one,json_objectmode (the caller must mention "JSON" in the prompt per OpenAI's rules). Every curated record declaressupports_structured_output: true. - Reasoning:
thinking_levelmaps to the selected transport's reasoning field per model family (src/reasoning.rs— the ladders encode real 400s: o1 and chat-tuned variants take no param, pro is high-only, xhigh is gpt-5.2+). Responses reasoning summaries are relayed as thinking blocks. Chat Completions still exposes onlycompletion_tokens_details.reasoning_tokensasusage.reasoning. Luna requests with function tools on the legacy path forcereasoning_effort: none, matching that endpoint's compatibility rule. - Prompt caching: automatic on OpenAI's side — no request markers.
prompt_cache_keyroutes requests that share a prefix to one cache shard: a caller'sprovider_options.openai.prompt_cache_keywins, else a key derived from the router'scache_intent.surface_digest(the frozen agent-profile prefix, so independent sessions on one profile share a shard), else a key derived from the session id. On GPT-5.6 and later (official endpoint only) the router'ssystem_sectionsgo out as one developer message each, withprompt_cache_breakpoint: {"mode":"explicit"}on the block flaggedcache_boundary: those models look up the cache only at message-level boundaries — explicit breakpoints, the implicit breakpoint on the latest eligible message, up to 20 earlier eligible message endings, and the end of the initial developer block — so a single system message ending with per-session text never matched across sessions (every new session paid a 1.25× cache write and read nothing). Implicit caching stays on for the conversation history; the key is accounting-only there. On the models that document extended retention (gpt-5.5, gpt-5.4, gpt-5.2, gpt-5.1*, gpt-5, gpt-5-codex, gpt-4.1 and their dated snapshots, official endpoint only) every request sendsprompt_cache_retention: "24h"so an entry lives up to a day instead of 5-10 minutes, at no extra write charge;PROVIDER_OPENAI_CACHE_RETENTION(in_memory|off) overrides it. GPT-5.6 and later takeprompt_cache_options.ttl, whose only value (30m) is already the default, so nothing is sent.prompt_tokens_details.cached_tokenslands onusage.cache_read. - Curated snapshot:
src/curated.rscarries windows / output ceilings / capability flags / pricing (USD per MTok). Update it against the official model specifications when OpenAI ships new models — discovery only supplies bare ids. GPT-5.4 / Pro, GPT-5.5 / Pro, GPT-5.6 / Sol / Terra / Luna, GPT-6 Astra / Sol / Luna and GPT-6.1 Sol have 1,050,000-token context windows. GPT-5.3 Codex and GPT-5.4 Mini / Nano have 400,000-token context windows. All of these models have 128,000-token output ceilings. Context-tiered pricing is intentionally omitted from the flat-rate catalog fields.
Image generation
provider::openai::image::generate and provider::openai::image::read are
the agent-callable functions of this worker (images have no router front
door, and the calls touch none of the router's accounting). generate posts
to the Images API sibling of the configured api_url
(…/v1/images/generations) with the router-resolved credential and writes
the picture, at full resolution, to
data/provider-openai/images/ (relative to the
Compose project directory, III_COMPOSE_DIR; the process cwd outside
Compose). The result names that file and carries no image bytes: base64
in a function result only inflates the conversation context.
// request
{ "model": "gpt-image-2.5-sunburst", // or gpt-image-2.5-flare (anything else is rejected)
"prompt": "a lighthouse at dusk, oil painting",
"size": "1536x1024", // 1024x1024 | 1536x1024 | 1024x1536 | auto
"quality": "high", // low | medium | high | auto
"output_format": "png", // png (default) | jpeg | webp
"background": "opaque", // transparent | opaque | auto
"file_name": "lighthouse" } // optional stem for the saved file
// response — the same envelope as browser::screenshot, minus the picture
{ "content": [
{ "type": "text", "text": "Image generated by gpt-image-2.5-sunburst (1536x1024, 1834021 bytes, image/png) saved to /…/data/provider-openai/images/lighthouse-1790171000000-3f9a2c1e.png; view with provider::openai::image::read { path }" } ],
"details": { "model", "path", "mime", "bytes", "size", "quality", "width", "height", "inline": "none", "revised_prompt?", "usage?" } }Preview in the chat. This worker ships an injected console renderer
(ui/, served through src/ui.rs): the chat card for a generate call
fetches a downscaled JPEG from the worker itself through image::read and
shows it beside the file path (copyable), dimensions, size and model — the
bytes travel worker → console, never through the model.
Looking at the picture from an agent. image::read { path, variant? }
takes the details.path a generate call returned (or the bare file name)
and returns viewable content blocks: variant: "preview" (default; a JPEG
≤512px / ~80 KB, which fits the harness's 256 KiB result cap — base64 is
counted twice there, content + details) or variant: "full". Anything
outside data/provider-openai/images/ is refused, symlinks included. For
one-shot use, generate also accepts inline: "preview" | "full" to embed
the picture in its own result.
Tests
cargo test # unit (pure modules + TCP stubs)
III_ENGINE_BIN=$(which iii) cargo test --test integration -- --test-threads=1The integration suite spawns a real engine, the real router (path dep), this provider, and a local stub upstream — no external API calls anywhere.
Running
The binary takes the standard worker CLI flags: --url (engine WebSocket,
default ws://127.0.0.1:49134, falls back to the III_WS_URL environment
variable), --manifest (print the registry manifest and exit), and
--config (accepted but ignored with a warning — provider config comes
from the llm-router configuration entry).
API reference (JSON)
agent-api-reference.json
{
"functions": [
{
"description": "Serve the provider-openai worker's injected console UI assets (content function for its console:script / console:style / console:module triggers).",
"metadata": {
"internal": true
},
"name": "provider-openai::ui-content",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Input of the content function: the console asks for one asset by path.",
"properties": {
"path": {
"description": "The asset path from the trigger config (e.g. `state/page.js`).",
"type": "string"
}
},
"required": [
"path"
],
"title": "UiContentInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Output of the content function.",
"properties": {
"content": {
"description": "The asset source, verbatim.",
"type": "string"
},
"content_type": {
"description": "MIME type the console should serve the asset with.",
"type": "string"
}
},
"required": [
"content",
"content_type"
],
"title": "UiContentResult",
"type": "object"
}
},
{
"description": "Cancel the in-flight upstream stream for a request_id (router::abort fan-out), stopping billed generation immediately.",
"metadata": {
"internal": true
},
"name": "provider::openai::abort",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Input of a provider's `provider::<id>::abort`: actively cancel the in-flight upstream stream for `request_id` (the router's `request_id`, delivered to the provider as `resolution_key`) so billed generation stops immediately instead of waiting for the provider to notice the closed channel on its next write.",
"properties": {
"request_id": {
"type": "string"
}
},
"required": [
"request_id"
],
"title": "ProviderAbortRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Output of `provider::<id>::abort`. `aborted: false` means the request was unknown — already finished, never started, or aborted before (idempotent).",
"properties": {
"aborted": {
"type": "boolean"
}
},
"required": [
"aborted"
],
"title": "ProviderAbortResponse",
"type": "object"
}
},
{
"description": "Count prompt tokens for {model, system_prompt?, tools?, messages} locally with the tiktoken tokenizers; never runs the model and costs nothing.",
"metadata": {
"internal": true
},
"name": "provider::openai::count_tokens",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"AgentFunction": {
"description": "Function invocation schema — what a provider sees as a `tools` array entry (README § Function invocation schema; adapter boundary). These describe iii functions exposed to the model, not provider-native tools.",
"properties": {
"description": {
"type": "string"
},
"execution_mode": {
"type": [
"string",
"null"
]
},
"label": {
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
},
"parameters": true
},
"required": [
"description",
"name",
"parameters"
],
"type": "object"
},
"AgentMessage": {
"anyOf": [
{
"$ref": "#/definitions/AssistantMessage"
},
{
"$ref": "#/definitions/FunctionResultMessage"
},
{
"$ref": "#/definitions/CustomMessage"
},
{
"$ref": "#/definitions/UserMessage"
}
],
"description": "The canonical transcript message union. Untagged: the single-variant role tags disambiguate deserialization."
},
"AssistantMessage": {
"properties": {
"content": {
"items": {
"$ref": "#/definitions/ContentBlock"
},
"type": "array"
},
"error_kind": {
"anyOf": [
{
"$ref": "#/definitions/ErrorKind"
},
{
"type": "null"
}
]
},
"error_message": {
"type": [
"string",
"null"
]
},
"model": {
"type": "string"
},
"native_stop_reason": {
"type": [
"string",
"null"
]
},
"provider": {
"type": "string"
},
"role": {
"$ref": "#/definitions/AssistantRoleTag"
},
"stop_reason": {
"$ref": "#/definitions/StopReason"
},
"timestamp": {
"format": "int64",
"type": "integer"
},
"usage": {
"anyOf": [
{
"$ref": "#/definitions/Usage"
},
{
"type": "null"
}
]
},
"warnings": {
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
}
},
"required": [
"content",
"model",
"provider",
"role",
"stop_reason",
"timestamp"
],
"type": "object"
},
"AssistantRoleTag": {
"enum": [
"assistant"
],
"type": "string"
},
"ContentBlock": {
"description": "Content blocks — the atomic units of message content (README § Content blocks).",
"oneOf": [
{
"properties": {
"text": {
"type": "string"
},
"type": {
"enum": [
"text"
],
"type": "string"
}
},
"required": [
"text",
"type"
],
"type": "object"
},
{
"properties": {
"attachment_id": {
"description": "Optional link to the stored original in the session-manager attachment store. Transcript bookkeeping for lazy readers only: the harness clears it before `router::chat`, and no provider mapping reads it. Tolerated here so a block that still carries it deserializes instead of failing the request; omitted on the wire when absent.",
"type": [
"string",
"null"
]
},
"data": {
"type": "string"
},
"mime": {
"type": "string"
},
"type": {
"enum": [
"image"
],
"type": "string"
}
},
"required": [
"data",
"mime",
"type"
],
"type": "object"
},
{
"description": "Reference to an original upload in the session-manager attachment store. A REFERENCE ONLY (never inline bytes); the harness strips it before `router::chat`. Tolerated here so a stray block deserializes instead of failing the request; every counter/mapping emits nothing for it.",
"properties": {
"attachment_id": {
"type": "string"
},
"mime": {
"type": "string"
},
"name": {
"type": "string"
},
"size": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"type": {
"enum": [
"file"
],
"type": "string"
}
},
"required": [
"attachment_id",
"mime",
"name",
"size",
"type"
],
"type": "object"
},
{
"properties": {
"signature": {
"type": [
"string",
"null"
]
},
"text": {
"type": "string"
},
"type": {
"enum": [
"thinking"
],
"type": "string"
}
},
"required": [
"text",
"type"
],
"type": "object"
},
{
"description": "Opaque redacted thinking payload — replayed verbatim on the Anthropic wire.",
"properties": {
"data": {
"type": "string"
},
"type": {
"enum": [
"redacted_thinking"
],
"type": "string"
}
},
"required": [
"data",
"type"
],
"type": "object"
},
{
"properties": {
"arguments": true,
"function_id": {
"type": "string"
},
"id": {
"type": "string"
},
"type": {
"enum": [
"function_call"
],
"type": "string"
}
},
"required": [
"arguments",
"function_id",
"id",
"type"
],
"type": "object"
},
{
"properties": {
"content": {
"items": {
"$ref": "#/definitions/ContentBlock"
},
"type": "array"
},
"function_call_id": {
"type": "string"
},
"is_error": {
"type": [
"boolean",
"null"
]
},
"type": {
"enum": [
"function_result"
],
"type": "string"
}
},
"required": [
"content",
"function_call_id",
"type"
],
"type": "object"
}
]
},
"CustomMessage": {
"properties": {
"content": {
"items": {
"$ref": "#/definitions/ContentBlock"
},
"type": "array"
},
"custom_type": {
"type": "string"
},
"details": true,
"display": {
"type": [
"string",
"null"
]
},
"role": {
"$ref": "#/definitions/CustomRoleTag"
},
"timestamp": {
"format": "int64",
"type": "integer"
}
},
"required": [
"content",
"custom_type",
"role",
"timestamp"
],
"type": "object"
},
"CustomRoleTag": {
"enum": [
"custom"
],
"type": "string"
},
"ErrorKind": {
"enum": [
"auth_expired",
"rate_limited",
"context_overflow",
"transient",
"permanent"
],
"type": "string"
},
"FunctionResultMessage": {
"properties": {
"content": {
"items": {
"$ref": "#/definitions/ContentBlock"
},
"type": "array"
},
"details": true,
"function_call_id": {
"type": "string"
},
"function_id": {
"type": "string"
},
"is_error": {
"type": "boolean"
},
"role": {
"$ref": "#/definitions/FunctionResultRoleTag"
},
"timestamp": {
"format": "int64",
"type": "integer"
}
},
"required": [
"content",
"details",
"function_call_id",
"function_id",
"is_error",
"role",
"timestamp"
],
"type": "object"
},
"FunctionResultRoleTag": {
"enum": [
"function_result"
],
"type": "string"
},
"StopReason": {
"enum": [
"end",
"length",
"function_call",
"aborted",
"error"
],
"type": "string"
},
"Usage": {
"properties": {
"cache_read": {
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"cache_write": {
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"cost_usd": {
"format": "double",
"type": [
"number",
"null"
]
},
"input": {
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"output": {
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"reasoning": {
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"type": "object"
},
"UserMessage": {
"properties": {
"content": {
"items": {
"$ref": "#/definitions/ContentBlock"
},
"type": "array"
},
"role": {
"$ref": "#/definitions/UserRoleTag"
},
"timestamp": {
"format": "int64",
"type": "integer"
}
},
"required": [
"content",
"role",
"timestamp"
],
"type": "object"
},
"UserRoleTag": {
"description": "Single-variant role tags: exact-match on deserialize, correct wire string on serialize, and they let `AgentMessage` be an untagged union.",
"enum": [
"user"
],
"type": "string"
}
},
"properties": {
"messages": {
"description": "Wire agent messages, the same shape `provider::openai::stream` accepts. Must be non-empty.",
"items": {
"$ref": "#/definitions/AgentMessage"
},
"type": "array"
},
"model": {
"description": "Model id the prompt targets; selects the tokenizer (o200k_base for gpt-4o/gpt-5/o-series and anything unknown-modern, cl100k_base for gpt-3.5 and non-o gpt-4 families).",
"type": "string"
},
"system_prompt": {
"default": null,
"description": "System prompt counted as its own wire message when present.",
"type": [
"string",
"null"
]
},
"tools": {
"default": null,
"description": "Function invocation schemas; each serialized schema counts toward the total.",
"items": {
"$ref": "#/definitions/AgentFunction"
},
"type": [
"array",
"null"
]
}
},
"required": [
"messages",
"model"
],
"title": "CountTokensRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"estimator": {
"description": "Always `tiktoken`: a local tokenizer produced the estimate.",
"type": "string"
},
"model": {
"type": "string"
},
"tokens": {
"description": "Estimated prompt tokens for the assembled request.",
"format": "uint64",
"minimum": 0,
"type": "integer"
}
},
"required": [
"estimator",
"model",
"tokens"
],
"title": "CountTokensResponse",
"type": "object"
}
},
{
"description": "Batch text embeddings via the OpenAI embeddings endpoint, using the router-resolved credential. One vector per input, order preserved. Default model text-embedding-3-small.",
"metadata": {
"internal": true
},
"name": "provider::openai::embed",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"input": {
"description": "Texts to embed, one vector returned per input, order preserved.",
"items": {
"type": "string"
},
"type": "array"
},
"model": {
"default": null,
"description": "Embedding model id; the provider default when omitted.",
"type": [
"string",
"null"
]
}
},
"required": [
"input"
],
"title": "EmbedRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"embeddings": {
"description": "One embedding per input, in input order.",
"items": {
"items": {
"format": "float",
"type": "number"
},
"type": "array"
},
"type": "array"
},
"model": {
"type": "string"
}
},
"required": [
"embeddings",
"model"
],
"title": "EmbedResponse",
"type": "object"
}
},
{
"description": "Generate one image from a text prompt with gpt-image-2.5-sunburst or gpt-image-2.5-flare (OpenAI Images API, router-resolved credential). Returns viewable content blocks (image + caption) that render inline, and saves the file under data/provider-openai/images/ (details.path) for other processes to pick up.",
"metadata": {},
"name": "provider::openai::image::generate",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"background": {
"default": null,
"description": "`transparent`, `opaque`, or `auto`; transparency needs png or webp.",
"type": [
"string",
"null"
]
},
"file_name": {
"default": null,
"description": "File stem for the persisted image (letters, digits, `.`, `_`, `-`; anything else becomes `-`). A timestamp and a random suffix are always appended so files never collide. Defaults to `image`.",
"type": [
"string",
"null"
]
},
"inline": {
"default": null,
"description": "Whether the result embeds image bytes: `none` (default — the file is saved, `details.path` names it, and the console fetches its own preview), `preview` (a JPEG at most 512px / ~80 KB, for an agent that must look at the picture; fits the harness result cap), or `full` (the original bytes — over a megabyte for a 1024px PNG).",
"type": [
"string",
"null"
]
},
"model": {
"description": "Image model: `gpt-image-2.5-sunburst` or `gpt-image-2.5-flare`.",
"type": "string"
},
"output_format": {
"default": null,
"description": "`png` (default), `jpeg`, or `webp`: the format of the file saved under data/ (and of the inline picture when `inline` is `full`).",
"type": [
"string",
"null"
]
},
"prompt": {
"description": "What to draw (up to 32k characters).",
"type": "string"
},
"quality": {
"default": null,
"description": "`low`, `medium`, `high`, or `auto`; the model default when omitted.",
"type": [
"string",
"null"
]
},
"size": {
"default": null,
"description": "`1024x1024`, `1536x1024` (landscape), `1024x1536` (portrait), or `auto`; the model default when omitted.",
"type": [
"string",
"null"
]
}
},
"required": [
"model",
"prompt"
],
"title": "ImageGenerateRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"ContentBlock": {
"description": "One block of a viewable response: an image block plus a text line — the shape the harness renders inline (same as `browser::screenshot`).",
"properties": {
"data": {
"type": [
"string",
"null"
]
},
"mime": {
"type": [
"string",
"null"
]
},
"text": {
"type": [
"string",
"null"
]
},
"type": {
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"ImageDetails": {
"properties": {
"bytes": {
"description": "Saved file size in bytes.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"height": {
"description": "Pixel height of the saved file, when decodable.",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"inline": {
"description": "`preview`, `full`, or `none`: what the inline image block carries.",
"type": "string"
},
"mime": {
"description": "Mime of the saved file: `image/png`, `image/jpeg`, or `image/webp`.",
"type": "string"
},
"model": {
"description": "Image model that produced the picture.",
"type": "string"
},
"path": {
"description": "Absolute path of the full-resolution file under `data/provider-openai/images/`.",
"type": "string"
},
"preview": {
"anyOf": [
{
"$ref": "#/definitions/PreviewDetails"
},
{
"type": "null"
}
],
"description": "Present when `inline` is `preview` and the preview could be built."
},
"quality": {
"description": "Requested quality (`auto` when left to the model).",
"type": "string"
},
"revised_prompt": {
"description": "The prompt as the model actually rendered it, when upstream reports one.",
"type": [
"string",
"null"
]
},
"size": {
"description": "Requested size (`auto` when left to the model).",
"type": "string"
},
"usage": {
"anyOf": [
{
"$ref": "#/definitions/ImageUsage"
},
{
"type": "null"
}
]
},
"width": {
"description": "Pixel width of the saved file, when decodable.",
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"bytes",
"inline",
"mime",
"model",
"path",
"quality",
"size"
],
"type": "object"
},
"ImageUsage": {
"description": "Token usage reported by the Images API (absent on gateways that omit it).",
"properties": {
"input_tokens": {
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"output_tokens": {
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"total_tokens": {
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"type": "object"
},
"PreviewDetails": {
"description": "What the inline image block actually holds when it is a preview.",
"properties": {
"bytes": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"height": {
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"mime": {
"type": "string"
},
"width": {
"format": "uint32",
"minimum": 0,
"type": "integer"
}
},
"required": [
"bytes",
"height",
"mime",
"width"
],
"type": "object"
}
},
"properties": {
"content": {
"description": "`[image block, text line]` (`[text line]` with `inline: none`) — render `content` and the picture shows.",
"items": {
"$ref": "#/definitions/ContentBlock"
},
"type": "array"
},
"details": {
"$ref": "#/definitions/ImageDetails"
}
},
"required": [
"content",
"details"
],
"title": "ImageGenerateResponse",
"type": "object"
}
},
{
"description": "Read back an image saved by image::generate (its details.path or bare file name under data/provider-openai/images/) as viewable content blocks: a JPEG preview (default, fits the harness result cap) or the full bytes. Refuses any path outside that folder.",
"metadata": {},
"name": "provider::openai::image::read",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Read a generated image back. Callers pass the `details.path` a generate call returned (or just its file name); anything outside `IMAGE_DATA_DIR` is refused, symlinks included, so this never becomes a general file reader. The console renderer uses it for the chat preview; an agent uses it when it needs to look at a picture it generated without `inline`.",
"properties": {
"path": {
"description": "Absolute path returned by `image::generate`, or the bare file name inside `data/provider-openai/images/`.",
"type": "string"
},
"variant": {
"default": null,
"description": "`preview` (default; a JPEG at most 512px / ~80 KB that fits the harness result cap) or `full` (the saved bytes as they are).",
"type": [
"string",
"null"
]
}
},
"required": [
"path"
],
"title": "ImageReadRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"ContentBlock": {
"description": "One block of a viewable response: an image block plus a text line — the shape the harness renders inline (same as `browser::screenshot`).",
"properties": {
"data": {
"type": [
"string",
"null"
]
},
"mime": {
"type": [
"string",
"null"
]
},
"text": {
"type": [
"string",
"null"
]
},
"type": {
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"ImageReadDetails": {
"properties": {
"bytes": {
"description": "Saved file size in bytes.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"height": {
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"mime": {
"description": "Mime of the saved file.",
"type": "string"
},
"path": {
"description": "Absolute path of the file that was read.",
"type": "string"
},
"preview": {
"anyOf": [
{
"$ref": "#/definitions/PreviewDetails"
},
{
"type": "null"
}
]
},
"variant": {
"description": "`preview` or `full`: what the image block carries.",
"type": "string"
},
"width": {
"format": "uint32",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"bytes",
"mime",
"path",
"variant"
],
"type": "object"
},
"PreviewDetails": {
"description": "What the inline image block actually holds when it is a preview.",
"properties": {
"bytes": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"height": {
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"mime": {
"type": "string"
},
"width": {
"format": "uint32",
"minimum": 0,
"type": "integer"
}
},
"required": [
"bytes",
"height",
"mime",
"width"
],
"type": "object"
}
},
"properties": {
"content": {
"description": "`[image block, text line]` — the same viewable envelope as generate.",
"items": {
"$ref": "#/definitions/ContentBlock"
},
"type": "array"
},
"details": {
"$ref": "#/definitions/ImageReadDetails"
}
},
"required": [
"content",
"details"
],
"title": "ImageReadResponse",
"type": "object"
}
},
{
"description": "Internal: router::ready subscriber that re-declares this provider and refreshes its catalog.",
"metadata": {
"internal": true
},
"name": "provider::openai::on_router_ready",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Event delivered to a provider's `provider::<id>::on_router_ready` (the `router::ready` trigger payload, currently `{}`). Unknown fields are ignored.",
"title": "RouterReadyEvent",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Ack returned by a provider's `provider::<id>::on_router_ready`.",
"properties": {
"ok": {
"type": "boolean"
}
},
"required": [
"ok"
],
"title": "ProviderReadyAck",
"type": "object"
}
},
{
"description": "Refresh the OpenAI catalog slice from GET /v1/models and reconcile it through the router; returns the model count written.",
"metadata": {
"internal": true
},
"name": "provider::openai::refresh_models",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Input of a provider's `provider::<id>::refresh_models` — takes no arguments. A struct (not `Value`) keeps the request schema concrete; unknown fields (e.g. the engine-injected `_caller_worker_id`) are ignored.",
"title": "RefreshModelsRequest",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Output of `provider::<id>::refresh_models`.",
"properties": {
"count": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"ok": {
"type": "boolean"
}
},
"required": [
"count",
"ok"
],
"title": "RefreshModelsResponse",
"type": "object"
}
},
{
"description": "Stream an OpenAI response: resolve credentials, call the configured Responses or Chat Completions endpoint, and relay AssistantMessageEvent frames to writer_ref.",
"metadata": {
"internal": true
},
"name": "provider::openai::stream",
"request_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"AgentFunction": {
"description": "Function invocation schema — what a provider sees as a `tools` array entry (README § Function invocation schema; adapter boundary). These describe iii functions exposed to the model, not provider-native tools.",
"properties": {
"description": {
"type": "string"
},
"execution_mode": {
"type": [
"string",
"null"
]
},
"label": {
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
},
"parameters": true
},
"required": [
"description",
"name",
"parameters"
],
"type": "object"
},
"AgentMessage": {
"anyOf": [
{
"$ref": "#/definitions/AssistantMessage"
},
{
"$ref": "#/definitions/FunctionResultMessage"
},
{
"$ref": "#/definitions/CustomMessage"
},
{
"$ref": "#/definitions/UserMessage"
}
],
"description": "The canonical transcript message union. Untagged: the single-variant role tags disambiguate deserialization."
},
"AssistantMessage": {
"properties": {
"content": {
"items": {
"$ref": "#/definitions/ContentBlock"
},
"type": "array"
},
"error_kind": {
"anyOf": [
{
"$ref": "#/definitions/ErrorKind"
},
{
"type": "null"
}
]
},
"error_message": {
"type": [
"string",
"null"
]
},
"model": {
"type": "string"
},
"native_stop_reason": {
"type": [
"string",
"null"
]
},
"provider": {
"type": "string"
},
"role": {
"$ref": "#/definitions/AssistantRoleTag"
},
"stop_reason": {
"$ref": "#/definitions/StopReason"
},
"timestamp": {
"format": "int64",
"type": "integer"
},
"usage": {
"anyOf": [
{
"$ref": "#/definitions/Usage"
},
{
"type": "null"
}
]
},
"warnings": {
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
}
},
"required": [
"content",
"model",
"provider",
"role",
"stop_reason",
"timestamp"
],
"type": "object"
},
"AssistantRoleTag": {
"enum": [
"assistant"
],
"type": "string"
},
"ChannelDirection": {
"enum": [
"read",
"write"
],
"type": "string"
},
"ContentBlock": {
"description": "Content blocks — the atomic units of message content (README § Content blocks).",
"oneOf": [
{
"properties": {
"text": {
"type": "string"
},
"type": {
"enum": [
"text"
],
"type": "string"
}
},
"required": [
"text",
"type"
],
"type": "object"
},
{
"properties": {
"attachment_id": {
"description": "Optional link to the stored original in the session-manager attachment store. Transcript bookkeeping for lazy readers only: the harness clears it before `router::chat`, and no provider mapping reads it. Tolerated here so a block that still carries it deserializes instead of failing the request; omitted on the wire when absent.",
"type": [
"string",
"null"
]
},
"data": {
"type": "string"
},
"mime": {
"type": "string"
},
"type": {
"enum": [
"image"
],
"type": "string"
}
},
"required": [
"data",
"mime",
"type"
],
"type": "object"
},
{
"description": "Reference to an original upload in the session-manager attachment store. A REFERENCE ONLY (never inline bytes); the harness strips it before `router::chat`. Tolerated here so a stray block deserializes instead of failing the request; every counter/mapping emits nothing for it.",
"properties": {
"attachment_id": {
"type": "string"
},
"mime": {
"type": "string"
},
"name": {
"type": "string"
},
"size": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"type": {
"enum": [
"file"
],
"type": "string"
}
},
"required": [
"attachment_id",
"mime",
"name",
"size",
"type"
],
"type": "object"
},
{
"properties": {
"signature": {
"type": [
"string",
"null"
]
},
"text": {
"type": "string"
},
"type": {
"enum": [
"thinking"
],
"type": "string"
}
},
"required": [
"text",
"type"
],
"type": "object"
},
{
"description": "Opaque redacted thinking payload — replayed verbatim on the Anthropic wire.",
"properties": {
"data": {
"type": "string"
},
"type": {
"enum": [
"redacted_thinking"
],
"type": "string"
}
},
"required": [
"data",
"type"
],
"type": "object"
},
{
"properties": {
"arguments": true,
"function_id": {
"type": "string"
},
"id": {
"type": "string"
},
"type": {
"enum": [
"function_call"
],
"type": "string"
}
},
"required": [
"arguments",
"function_id",
"id",
"type"
],
"type": "object"
},
{
"properties": {
"content": {
"items": {
"$ref": "#/definitions/ContentBlock"
},
"type": "array"
},
"function_call_id": {
"type": "string"
},
"is_error": {
"type": [
"boolean",
"null"
]
},
"type": {
"enum": [
"function_result"
],
"type": "string"
}
},
"required": [
"content",
"function_call_id",
"type"
],
"type": "object"
}
]
},
"CustomMessage": {
"properties": {
"content": {
"items": {
"$ref": "#/definitions/ContentBlock"
},
"type": "array"
},
"custom_type": {
"type": "string"
},
"details": true,
"display": {
"type": [
"string",
"null"
]
},
"role": {
"$ref": "#/definitions/CustomRoleTag"
},
"timestamp": {
"format": "int64",
"type": "integer"
}
},
"required": [
"content",
"custom_type",
"role",
"timestamp"
],
"type": "object"
},
"CustomRoleTag": {
"enum": [
"custom"
],
"type": "string"
},
"ErrorKind": {
"enum": [
"auth_expired",
"rate_limited",
"context_overflow",
"transient",
"permanent"
],
"type": "string"
},
"FunctionResultMessage": {
"properties": {
"content": {
"items": {
"$ref": "#/definitions/ContentBlock"
},
"type": "array"
},
"details": true,
"function_call_id": {
"type": "string"
},
"function_id": {
"type": "string"
},
"is_error": {
"type": "boolean"
},
"role": {
"$ref": "#/definitions/FunctionResultRoleTag"
},
"timestamp": {
"format": "int64",
"type": "integer"
}
},
"required": [
"content",
"details",
"function_call_id",
"function_id",
"is_error",
"role",
"timestamp"
],
"type": "object"
},
"FunctionResultRoleTag": {
"enum": [
"function_result"
],
"type": "string"
},
"Model": {
"description": "The capability record (README § Model descriptor).",
"properties": {
"context_window": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"display_name": {
"type": [
"string",
"null"
]
},
"id": {
"type": "string"
},
"input_limit": {
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"max_output_tokens": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"pricing": {
"anyOf": [
{
"$ref": "#/definitions/Pricing"
},
{
"type": "null"
}
]
},
"provider": {
"type": "string"
},
"reasoning_efforts": {
"items": {
"$ref": "#/definitions/ReasoningEffort"
},
"type": [
"array",
"null"
]
},
"speech": {
"anyOf": [
{
"$ref": "#/definitions/SpeechModel"
},
{
"type": "null"
}
],
"description": "Set on speech models only; see [`SpeechModel`]."
},
"supports_cache": {
"type": [
"boolean",
"null"
]
},
"supports_structured_output": {
"type": [
"boolean",
"null"
]
},
"supports_thinking": {
"type": [
"boolean",
"null"
]
},
"supports_thinking_off": {
"description": "Whether `thinking_level: off` can switch the model's reasoning off. `Some(true)`: a native off switch exists. `Some(false)`: the model always reasons, or the provider has no switch. `None`: the provider does not know; consoles show the choice disabled.",
"type": [
"boolean",
"null"
]
},
"supports_tools": {
"type": [
"boolean",
"null"
]
},
"supports_vision": {
"type": [
"boolean",
"null"
]
},
"supports_xhigh": {
"type": [
"boolean",
"null"
]
},
"thinking_budgets": {
"additionalProperties": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"type": [
"object",
"null"
]
}
},
"required": [
"context_window",
"id",
"max_output_tokens",
"provider"
],
"type": "object"
},
"Pricing": {
"properties": {
"cache_read": {
"format": "double",
"type": [
"number",
"null"
]
},
"cache_write": {
"format": "double",
"type": [
"number",
"null"
]
},
"input": {
"format": "double",
"type": [
"number",
"null"
]
},
"output": {
"format": "double",
"type": [
"number",
"null"
]
}
},
"type": "object"
},
"PromptCacheIntent": {
"description": "Why a request's stable prefix is shareable across sessions: `surface_digest` is the caller's content identity for the text before the boundary (`sha256:<hex>`). A routing/accounting hint only — never a provider cache handle, and never evidence of a cache hit.",
"properties": {
"surface_digest": {
"type": "string"
}
},
"required": [
"surface_digest"
],
"type": "object"
},
"PromptSection": {
"description": "One ordered system-prompt section. `cache_boundary` marks the end of a cumulative prefix worth its own provider cache entry (the frozen agent-profile surface). Adapters without a boundary concept read the sections joined with \"\\n\\n\", which must equal `system_prompt` when both forms are sent.",
"properties": {
"cache_boundary": {
"default": false,
"type": "boolean"
},
"text": {
"type": "string"
}
},
"required": [
"text"
],
"type": "object"
},
"ReasoningEffort": {
"description": "One provider-native reasoning effort advertised for a specific model.\n\nValues intentionally remain strings: provider catalogs can add efforts without requiring a router-wide enum release first.",
"properties": {
"description": {
"type": [
"string",
"null"
]
},
"effort": {
"type": "string"
}
},
"required": [
"effort"
],
"type": "object"
},
"ResponseFormat": {
"properties": {
"schema": true,
"type": {
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"SpeechModality": {
"description": "What a speech model does. Chat models carry no `speech` block.",
"oneOf": [
{
"description": "Speech to text, served through `router::transcribe`.",
"enum": [
"stt"
],
"type": "string"
},
{
"description": "Text to speech, served through `router::speak`.",
"enum": [
"tts"
],
"type": "string"
}
]
},
"SpeechModel": {
"description": "Facts about a speech model. Present only on models served through `router::transcribe` / `router::speak`; such models report `context_window` and `max_output_tokens` as 0.",
"properties": {
"languages": {
"description": "BCP-47 tags of the languages the model handles; empty when the provider does not say.",
"items": {
"type": "string"
},
"type": "array"
},
"modality": {
"$ref": "#/definitions/SpeechModality"
},
"streaming": {
"default": false,
"description": "Realtime input (stt) or streamed audio output (tts) is available.",
"type": "boolean"
}
},
"required": [
"modality"
],
"type": "object"
},
"StopReason": {
"enum": [
"end",
"length",
"function_call",
"aborted",
"error"
],
"type": "string"
},
"StreamChannelRef": {
"properties": {
"access_key": {
"type": "string"
},
"channel_id": {
"type": "string"
},
"direction": {
"$ref": "#/definitions/ChannelDirection"
}
},
"required": [
"access_key",
"channel_id",
"direction"
],
"type": "object"
},
"ThinkingLevel": {
"description": "\"off\" asks the provider not to reason at all and is honoured only where the model advertises `Model::supports_thinking_off` (elsewhere the provider falls back to its own lowest setting, or omits the parameter, and warns). \"minimal\" requests the lowest reasoning effort and needs only `thinking` support; levels map to provider-native knobs via `Model::thinking_budgets`.",
"enum": [
"off",
"minimal",
"low",
"medium",
"high",
"xhigh"
],
"type": "string"
},
"Usage": {
"properties": {
"cache_read": {
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"cache_write": {
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"cost_usd": {
"format": "double",
"type": [
"number",
"null"
]
},
"input": {
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"output": {
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"reasoning": {
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"type": "object"
},
"UserMessage": {
"properties": {
"content": {
"items": {
"$ref": "#/definitions/ContentBlock"
},
"type": "array"
},
"role": {
"$ref": "#/definitions/UserRoleTag"
},
"timestamp": {
"format": "int64",
"type": "integer"
}
},
"required": [
"content",
"role",
"timestamp"
],
"type": "object"
},
"UserRoleTag": {
"description": "Single-variant role tags: exact-match on deserialize, correct wire string on serialize, and they let `AgentMessage` be an untagged union.",
"enum": [
"user"
],
"type": "string"
}
},
"description": "Input of a provider worker's `provider::<id>::stream` iii function — what the router forwards per attempt. (No `PartialEq`: `iii_sdk::StreamChannelRef` doesn't implement it.)",
"properties": {
"cache_intent": {
"anyOf": [
{
"$ref": "#/definitions/PromptCacheIntent"
},
{
"type": "null"
}
]
},
"max_output_tokens": {
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
},
"messages": {
"items": {
"$ref": "#/definitions/AgentMessage"
},
"type": "array"
},
"model": {
"type": "string"
},
"model_meta": {
"anyOf": [
{
"$ref": "#/definitions/Model"
},
{
"type": "null"
}
]
},
"provider_options": true,
"resolution_key": {
"type": [
"string",
"null"
]
},
"response_format": {
"anyOf": [
{
"$ref": "#/definitions/ResponseFormat"
},
{
"type": "null"
}
]
},
"session_id": {
"description": "Stable conversation identity for provider cache affinity.",
"type": [
"string",
"null"
]
},
"system_prompt": {
"type": [
"string",
"null"
]
},
"system_sections": {
"description": "Ordered sections behind `system_prompt` (always forwarded alongside the flat string, which equals the sections joined with \"\\n\\n\").",
"items": {
"$ref": "#/definitions/PromptSection"
},
"type": [
"array",
"null"
]
},
"thinking_level": {
"anyOf": [
{
"$ref": "#/definitions/ThinkingLevel"
},
{
"type": "null"
}
]
},
"tools": {
"items": {
"$ref": "#/definitions/AgentFunction"
},
"type": [
"array",
"null"
]
},
"writer_ref": {
"$ref": "#/definitions/StreamChannelRef"
}
},
"required": [
"messages",
"model",
"writer_ref"
],
"title": "ProviderStreamInput",
"type": "object"
},
"response_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Output of a provider's `provider::<id>::stream` (spec § stream contract): the function streams frames to `writer_ref` and returns this ack.",
"properties": {
"ok": {
"type": "boolean"
}
},
"required": [
"ok"
],
"title": "ProviderStreamOutput",
"type": "object"
}
}
],
"triggers": []
}