feat(protocol): define experimental image and decision generation endpoints - #59190

The contract works as described. I ran the server and client tests closest to the change (all pass) and typecheck:tsc in schema, protocol, client, plugin and server (clean). I also probed the real server: the old /api/experimental/generate now returns 404; image and decision bodies that are malformed or missing fields return 400 InvalidRequestError; valid bodies return 501 NotImplementedError.

Public API impact

• Moved (breaking): POST /api/experimental/generate → POST /api/experimental/generate/text (operation experimental.generate.text). Callers of the old path get 404; the generated clients are updated, and the endpoint is experimental.
• Added: POST /api/experimental/generate/image (experimental.generate.image) and POST /api/experimental/generate/decisions (experimental.generate.decisions), with client methods generate.image / generate.decisions and their types.
• Added: the @opencode/schema/generate module, and the protocol errors ModelNotFoundError (404), UnsupportedModelError (422), ProviderRequestError (502) and NotImplementedError (501).
• Plugins: Context.generate is narrowed to Pick<GenerateApi, "text">, the same surface as before, so plugins are unaffected.

One small concern: duplicate question names currently get through to 501 instead of the 400 the description promises (see inline).

Related: #49549, #47366

The new commit addresses the earlier point: DecisionRequest now rejects duplicate question names, so they return 400 instead of reaching the 501. The added test checks this, and it passes. typecheck:tsc is clean in schema, protocol, client and server.

Public API: the only change since my last review is that experimental.generate.decisions now rejects duplicate question names with 400. The generated OpenAPI spec and clients don't change.

Nothing new to raise.

Duplicate question names are still rejected with 400 InvalidRequestError (field: "questions"), now in the decisions handler instead of the schema, and the uniqueness rule is described on the questions field in the OpenAPI spec. That covers the earlier point. bun test test/generate.test.ts in packages/server passes, including the duplicate-name check, and typecheck:tsc is clean in schema, protocol, client and server.

Public API: nothing new since the last review. experimental.generate.decisions still returns 400 for duplicate names; only the spec's field description changed.

Nothing new to raise.

The old POST /api/experimental/generate path is now a deprecated alias of /generate/text, so the path move is backwards compatible. Both paths share one handler and contract, and the alias is left out of the generated clients. The server generate tests (including a request on the old path) and the client promise tests pass, and typecheck:tsc is clean in protocol, client, plugin and server. Running bun run generate left nothing changed in the committed generated clients or openapi.json.

Public API: text generation is now at POST /api/experimental/generate/text, and the old path is kept as a deprecated alias (experimental.generate.textLegacy, not in the generated clients). Everything else is the same as before and all additive: experimental.generate.image and experimental.generate.decisions with their client methods, ModelNotFoundError, UnsupportedModelError, ProviderRequestError, NotImplementedError, and the @opencode/schema/generate module. Nothing breaks for existing callers.

Nothing new to raise.

The latest commit reshapes the image and decision schemas without changing behaviour. The server generate tests and client promise tests pass, and typecheck:tsc is clean in schema, protocol, client, plugin and server. Running bun run generate left nothing changed, so the committed generated clients and openapi.json are up to date.

Public API changes in this push, all to endpoints this PR adds that haven't shipped, so nothing existing breaks:

• Generate.Media (base64 or url) → Generate.File { data, mime, name? }. URL inputs are no longer accepted.
• Decision part media → file.
• providerOptions removed from both requests.
• usage / providerMetadata → cost / tokens / native on both results.

Nothing new to raise.

The latest commit is a small change to the decisions result schema. The server generate tests pass, typecheck:tsc is clean in schema, protocol, client, plugin and server, and running bun run generate left nothing changed in the committed generated types and openapi.json.

Public API changes in this push, both to the decisions endpoint this PR adds (not shipped yet), so nothing existing breaks:

• Generate.ErrorAnswer.reason: "refusal" → any string, with a new optional message.
• Generate.DecisionResult.tokens: TokenUsage.Info → optional { input?, output? }.

Nothing new to raise.

The latest commit makes a few small changes to the image and decision result schemas. The server generate tests pass, typecheck:tsc is clean in schema, protocol, client, plugin and server, and running bun run generate left nothing changed in the committed generated types and openapi.json.

Public API changes in this push, all to endpoints this PR adds (not shipped yet), so nothing existing breaks:

• New Generate.Usage { input?, output? }, now used for tokens on both results. On ImageResult this replaces TokenUsage.Info.
• ImageResult.images items: Generate.File → Generate.ImageOutput (adds type: "image").
• Removed: ImageResult.notices and Generate.Notice.

Nothing new to raise.

The only change in this push reverts the PR's edit to V2_HTTP_API_AUDIT.md. Code, tests and generated output are unchanged, so there was nothing to run. Row 138 now lists /api/experimental/generate for experimental.generate.text, but this PR moves that operation to /api/experimental/generate/text and keeps the old path as a deprecated alias. If the revert is intentional, the audit can be updated separately.

Public API: unchanged since the last review.

Nothing else to raise.

This push only merges dev. The PR's changes are the same as before; its two-line Generate type registration now sits in the renamed packages/client/script/generate.ts. The server generate tests and client promise tests pass, typecheck:tsc is clean in schema, protocol, client, plugin and server, and running bun run generate left nothing changed, so the committed generated clients and openapi.json still match the merged code.

Public API: unchanged since the last review.

Nothing new to raise.

The core wiring works: image and decision requests now run through the catalog models instead of returning 501. The duplicate-names point is covered in the server handler (400 before plugins load) and by @opencode/ai's Decision schema, which the plugin path also goes through. Core, server and client tests pass, typecheck:tsc is clean in ai, schema, protocol, client, plugin, core and server, and running bun run generate left nothing changed. On a real server, an unknown model returns 404 ModelNotFoundError and duplicate question names return 400. I couldn't run a real provider call (no credentials); the core tests cover that path with a stubbed HTTP client.

Public API changes in this push, all additive to what this PR introduces:

• experimental.generate.image and experimental.generate.decisions now generate results instead of returning 501, and NotImplementedError is removed from their error lists.
• The plugin Context.generate now includes image and decisions, no longer just text.

Concerns:

• A model on a provider with no credentials returns a misleading 404 (see inline).
• NotImplementedError is still exported from packages/protocol/src/errors.ts but nothing uses it now.
• The PR description still says the routes always return 501 and that core wiring is out of scope.

Both new commits work as intended: NotImplementedError is gone, and text generation now uses the same errors as images and decisions. Core, server and SDK tests pass, typecheck:tsc is clean in core, protocol, client, plugin, server and sdk, and running bun run generate left nothing changed.

Thread 2 (misleading 404 when a provider has no credentials) still applies, and now covers text too. On a real server, POST /api/experimental/generate/text with openai/gpt-5 and no OpenAI key returns 404 Model not found: openai/gpt-5; before this push it returned 400 Model unavailable.

Public API: this push changes the errors of the existing text endpoint, on both /api/experimental/generate/text and the deprecated /api/experimental/generate:

• unknown model: 400 InvalidRequestError → 404 ModelNotFoundError
• model of the wrong type: 400 → 422 UnsupportedModelError
• provider failure: 503 ServiceUnavailableError → 502 ProviderRequestError
• no model given and none available: 400 → 503
• the provider rejecting the request as invalid now returns 400

Callers that branch on the old status codes would need updating; the endpoint is experimental. Also removed: the protocol NotImplementedError (never shipped) and the core Generate.ModelSelectionError.

This push only tightens the types of aspect and resolution; decoding is unchanged. 16:9 and 1.5:1 are accepted, wide, 1e3:1 and -1:2 are rejected, and any resolution string still passes. The core and server generate tests pass, typecheck:tsc is clean in schema, core, protocol, client and server, and running bun run generate left nothing changed.

Public API: the client's generate.image input types narrow from aspect: string to Generate.ImageAspect (${number}:${number}) and from resolution: string to Generate.ImageResolution ("1K" | "2K" | "4K" | string). The HTTP contract accepts the same requests as before, and the OpenAPI spec now names both schemas.

Nothing new to raise.

This push makes image and decision results plain JSON before the server sends them: provider metadata (native) is copied through JSON, image tokens only appear when a count is reported, and the server's error mapping leaves out optional fields that aren't set. The core generate tests pass, including a new JSON round-trip check on the image result, the server generate tests pass, typecheck:tsc is clean in core and server, and running bun run generate left nothing changed. I couldn't reproduce the original failure, since it needs real provider metadata (no credentials here).

Public API: unchanged.

Nothing new to raise.

This push fixes the file type of images that providers return as URLs: core now detects it from the downloaded bytes. The new core test fails on the mime value with the previous generate.ts and passes with this commit (image/png). The core generate tests pass (16) and typecheck:tsc is clean in core.

Public API: unchanged.

Nothing new to raise.

This push makes the image, speech and transcription protocols in @opencode/ai report no usage when a provider sends a usage object with no counts. The new tokenUsage helper is applied the same way in every protocol it touches. The new usage test, the full packages/ai suite (1933 pass) and the core generate tests pass, and typecheck:tsc is clean in ai and core.

Public API: the HTTP API and generated clients are unchanged.

Nothing new to raise.

The Gemini change is sound: image requests stopped for safety or recitation now fail as content-policy refusals (502 content_filter) instead of a malformed-response error, and the updated ai image test checks it. The ai image tests and core generate tests pass, and typecheck:tsc is clean in ai and core.

Public API: no endpoint, schema or client changes.

One point worth confirming: image and decision calls now use the text retry policy, which also retries provider 5xx errors and failures after the request was delivered, so they may be billed more than once (see inline).

This push only merges dev, and the merge went through cleanly. In models-dev.ts, image and decision models still prefer the API matching their type, now only among the packages this build can load (from dev). dev's new schema-error.test.ts gets image and decisions on its mock service and still passes on the deprecated /api/experimental/generate path. The server and core generate tests and the core model tests pass, typecheck:tsc is clean in ai, protocol, client, plugin, core and server, and running bun run generate left nothing changed.

Public API: unchanged since the last review.

Nothing new to raise.

Most of this push is a sound cleanup, with one regression: requests are now built with Image.request / Decision.request outside the tryRequest wrapper that Image.generate / Decision.generate used. A request that fails validation when it's built now crashes as an unhandled defect instead of returning a typed 400-style error. With a temporary core test, generate.decisions with two questions both named a returned Generate.InvalidRequestError on the previous commit and now dies with a defect. The HTTP route still returns 400 because its handler checks for duplicate names first, but plugins calling ctx.generate.decisions (or images with any construction-time validation failure) now crash (see inline). The core generate tests pass and typecheck:tsc is clean in core; the existing tests don't cover this case.

Public API: unchanged.

Invalid image and decision requests return a typed error again: core goes back to Image.generate / Decision.generate, and a new core test checks that duplicate question names give Generate.InvalidRequestError. Stateless generation for plugins now lives under ctx.experimental.generate (text, image, decisions), and ctx.generate is text-only and deprecated. Core generate and plugin tests and the packages/plugin suite pass, and typecheck:tsc is clean in core, plugin, sdk and server.

Public API in this push: the plugin Context gains experimental.generate (text, image, decisions); generate is marked deprecated and keeps only text. That matches the base, so existing plugins are unaffected; ctx.generate.image / ctx.generate.decisions only existed on this branch. The HTTP API is unchanged.

Nothing new to raise. The description's verification list still mentions a plugin calling ctx.generate.decisions, which no longer exists.

The earlier retry concern is addressed. Stateless text, image and decision calls now go through ModelRetry.retryOneShot, which retries only failures the provider clearly never ran (rate limits, 503/529, requests not sent or to an unreachable host, or x-should-retry: true), at most 3 times, with the existing backoff and retry-after handling. Stateless text no longer gets up to 10 retries on failures the provider may already have run, as the description notes. The core generate tests (18) cover the retry and no-retry cases and the cap, and typecheck:tsc is clean in core.

Public API: unchanged; only retry behaviour changes.

Nothing new to raise.