feat(core): turn experimental_image_generate on by default (#60258)

Author: rekram1-node

packages/core/src/session/execution/restart.ts

@@ -159,7 +159,7 @@ export const layer = (options?: Options) =>
               body,
             }),
             metadata: {
-              source: "image_generate",
+              source: "experimental_image_generate",
               jobID: background.id,
               state: background.status === "running" ? "cancelled" : background.status,
               path: recovery.path,

packages/core/src/tool/plugin/image-generate.ts

@@ -23,7 +23,7 @@ import { SessionMessage } from "../../session/message.js"
 import { SessionSchema } from "../../session/schema.js"
 import { collectBoundedResponseBody } from "../http-body.js"
 
-export const name = "image_generate"
+export const name = "experimental_image_generate"
 export const MAX_INPUT_BYTES = 20 * 1024 * 1024
 const DOWNLOAD_TIMEOUT = Duration.seconds(30)
 const GENERATE_TIMEOUT = Duration.minutes(30)
@@ -224,7 +224,8 @@ export const Plugin = {
       Effect.forkIn(scope, { startImmediately: true }),
     )
 
-    // Opt-in through experimental.image_generate. Internal plugins are not re-run on config changes, so reload the
+    // On by default. `experimental.image_generate: false` is still honored for configs from when the tool was opt-in;
+    // permissions are the supported way to turn it off. Internal plugins are not re-run on config changes, so reload the
     // tool transform instead.
     const loaded = yield* ConfigEntryObserver.observe(config, ctx.event, ctx.tool.reload())
 
@@ -247,7 +248,7 @@ export const Plugin = {
 
     yield* ctx.tool
       .transform((editor) => {
-        if (!enabled || !optedIn(loaded.entries)) return
+        if (!enabled || imageGenerate(loaded.entries) === false) return
         editor.add({
           name,
           options: { codemode: false },
@@ -399,11 +400,6 @@ function imageGenerate(entries: readonly Entry[]) {
   )?.info.experimental?.image_generate
 }
 
-function optedIn(entries: readonly Entry[]) {
-  const value = imageGenerate(entries)
-  return value !== undefined && value !== false
-}
-
 function configuredModel(entries: readonly Entry[]) {
   const value = imageGenerate(entries)
   return typeof value === "object" ? value.model : undefined

packages/core/test/session-execution.test.ts

@@ -549,15 +549,15 @@ describe("SessionRestart background recovery", () => {
       const recovery = (path: string) => ({ kind: "image" as const, sessionID, path, model: "test/painter" })
       yield* jobs.start({
         id: "image_done",
-        type: "image_generate",
+        type: "experimental_image_generate",
         recovery: recovery("/tmp/done.png"),
         run: Effect.succeed("Image request finished. Saved image: /tmp/done.png (test/painter)."),
       })
       yield* jobs.background("image_done")
       yield* jobs.wait({ id: "image_done" })
       yield* jobs.start({
         id: "image_running",
-        type: "image_generate",
+        type: "experimental_image_generate",
         recovery: recovery("/tmp/running.png"),
         run: Effect.never,
       })

packages/core/test/tool-image-generate.test.ts

@@ -96,10 +96,6 @@ const setup = (providerID = "test") =>
     const plugins = yield* Plugin.Service
     const sessions = yield* Session.Service
     const location = yield* Location.Service
-    const config = yield* Config.Test
-    const entries = yield* config.entries()
-    if (!entries.some((entry) => entry.type === "document" && entry.info.experimental?.image_generate !== undefined))
-      yield* configure(true)
     const host = yield* PluginHost.make(plugins)
     yield* ImageGenerateTool.Plugin.effect(host)
     yield* OpenCodeTools.Plugin.effect(host)
@@ -167,7 +163,7 @@ const text = (result: { readonly content?: ReadonlyArray<Tool.Content> }) =>
   result.content?.[0]?.type === "text" ? result.content[0].text : undefined
 const failure = (result: { readonly error?: { readonly message: string } }) => result.error?.message
 
-describe("image_generate", () => {
+describe("experimental_image_generate", () => {
   it.live("is registered only while an image model is available", () =>
     Effect.gen(function* () {
       yield* setup()
@@ -180,20 +176,20 @@ describe("image_generate", () => {
     }),
   )
 
-  it.live("is offered only when experimental.image_generate is enabled", () =>
+  it.live("is on by default and off with experimental.image_generate: false", () =>
     Effect.gen(function* () {
       yield* imageModel("test", "painter")
-      yield* configure(false)
       yield* setup()
-      expect(yield* registered).toBe(false)
+      expect(yield* until(true)).toBe(true)
+      yield* configure(false)
+      expect(yield* until(false)).toBe(false)
+      // Older configs that set true or a model keep working and keep the tool on.
       yield* configure(true)
       expect(yield* until(true)).toBe(true)
       yield* configure(false)
       expect(yield* until(false)).toBe(false)
       yield* configure({})
       expect(yield* until(true)).toBe(true)
-      yield* configure(undefined)
-      expect(yield* until(false)).toBe(false)
     }),
   )
 
@@ -266,7 +262,7 @@ describe("image_generate", () => {
         },
       ])
       expect(fixture.assertions.map((item) => [item.action, item.resources])).toEqual([
-        ["image_generate", ["test/painter"]],
+        ["experimental_image_generate", ["test/painter"]],
         ["edit", ["out.png"]],
         ["read", ["in.png"]],
       ])
@@ -360,7 +356,7 @@ describe("image_generate", () => {
       fixture.deny = "edit"
       const result = yield* run({ prompt: "x", path: "out.png" })
       expect(result.status).toBe("error")
-      expect(fixture.assertions.map((item) => item.action)).toEqual(["image_generate", "edit"])
+      expect(fixture.assertions.map((item) => item.action)).toEqual(["experimental_image_generate", "edit"])
       expect(fixture.requests).toEqual([])
     }),
   )
@@ -454,7 +450,7 @@ describe("image_generate", () => {
       const result = yield* run({ prompt: "x", images: ["https://example.invalid/cat.png"] })
       expect(result.status).toBe("error")
       expect(fixture.assertions.map((item) => [item.action, item.resources])).toEqual([
-        ["image_generate", ["test/painter"]],
+        ["experimental_image_generate", ["test/painter"]],
         ["webfetch", ["https://example.invalid/cat.png"]],
       ])
       expect(fixture.requests).toEqual([])

packages/schema/src/config/experimental.ts

@@ -25,14 +25,14 @@ export class Info extends Schema.Class<Info>("ConfigExperimental.Info")({
     Schema.Struct({
       model: ConfigModel.Selection.pipe(optional).annotate({
         description:
-          "Default model for the image_generate tool when the agent doesn't choose one, as providerID/modelID. Falls back to automatic selection when it isn't available.",
+          "Default model for the experimental_image_generate tool when the agent doesn't choose one, as providerID/modelID. Falls back to automatic selection when it isn't available.",
       }),
     }),
   ])
     .pipe(optional)
     .annotate({
       description:
-        "Enable the experimental image_generate tool, offered while a connected provider has an image model. Set to true, or to an object with an optional default model. Defaults to false.",
+        "Settings for the experimental_image_generate tool, which is offered while a connected provider has an image model.",
     }),
   schedules: Schema.Boolean.pipe(optional).annotate({
     description: "Enable experimental scheduled tasks that wake a session with a prompt. Defaults to false.",

services/www/src/docs/content/config.mdx

@@ -627,7 +627,7 @@ All experimental settings live under the `experimental` key:
     "subagent_depth": 2,
     "portable_shell_scanner": true,
     "background_compaction": true,
-    "image_generate": true,
+    "image_generate": { "model": "openai/gpt-image-2" },
     "location_idle_timeout": "4 hours",
   },
 }
@@ -663,11 +663,9 @@ automatic compaction doesn't pause the session. Defaults to `false`. See
 
 ### Image generation
 
-Set `image_generate` to `true` to give agents the [`image_generate`](/tools#image-generate) tool for creating and
-editing images. It is offered only while a connected provider has an image model. Defaults to `false`.
-
-To set a default model, use an object with `model` as `providerID/modelID`, optionally with `#variant`. When that model
-isn't available or can't handle a request, OpenCode picks another image model automatically.
+`image_generate` sets the default model for the [`experimental_image_generate`](/tools#image-generate) tool, as
+`providerID/modelID`, optionally with `#variant`. When that model isn't available or can't handle a request, OpenCode
+picks another image model automatically.
 
 ```jsonc
 {

services/www/src/docs/content/permissions.mdx

@@ -118,7 +118,7 @@ currently use these actions and resources:
 | `question`           | `*`                                                                         |
 | `webfetch`           | Requested URL                                                               |
 | `websearch`          | Search query                                                                |
-| `image_generate`     | Selected image model as `providerID/modelID`, plus `#variant` when set      |
+| `experimental_image_generate` | Selected image model as `providerID/modelID`, plus `#variant` when set |
 | `external_directory` | Canonical external directory boundary, normally ending in `/*`              |
 | `<server>_<tool>`    | `*` for an MCP tool; unsupported characters in both names become `_`        |
 | `opencode_list_mcp_resources` | MCP server name                                                    |

services/www/src/docs/content/tools.mdx

@@ -161,10 +161,10 @@ for providers, selection, rate limits, and disabling the tool.
 
 ### Image generate
 
-`image_generate` creates a new image from a prompt, or edits existing ones. It
-is experimental and off by default; turn it on with
-[`experimental.image_generate`](/config#image-generation). It appears only
-while a connected provider has an image model.
+`experimental_image_generate` creates a new image from a prompt, or edits
+existing ones. It is experimental and appears while a connected provider has an
+image model. To choose its default model, see
+[`experimental.image_generate`](/config#image-generation).
 
 ```text
 Generate a flat app icon of a paper plane on a blue background and save it to assets/icon.png.
@@ -174,7 +174,7 @@ Give it a `prompt`, and optionally `images` to edit or use as references, a
 specific `model`, or a `path` to save to. It runs in the background and
 notifies the session with the saved path when the image is ready.
 
-Permission: `image_generate` with the selected model as its resource.
+Permission: `experimental_image_generate` with the selected model as its resource.
 
 ## Interaction