Return image URL from view_image tool (#15072)

Cleanup image semantics in code mode.

`view_image` now returns `{image_url:string, details?: string}` 

`image()` now allows both string parameter and `{image_url:string,
details?: string}`

codex-rs/core/src/tools/code_mode/description.md

@@ -11,7 +11,7 @@
 - Global helpers:
 - `exit()`: Immediately ends the current script successfully (like an early return from the top level).
 - `text(value: string | number | boolean | undefined | null)`: Appends a text item and returns it. Non-string values are stringified with `JSON.stringify(...)` when possible.
-- `image(imageUrl: string)`: Appends an image item and returns it. `image_url` can be an HTTPS URL or a base64-encoded `data:` URL.
+- `image(imageUrlOrItem: string | { image_url: string; detail?: "auto" | "low" | "high" | "original" | null })`: Appends an image item and returns it. `image_url` can be an HTTPS URL or a base64-encoded `data:` URL.
 - `store(key: string, value: any)`: stores a serializable value under a string key for later `exec` calls in the same session.
 - `load(key: string)`: returns the stored value for a string key, or `undefined` if it is missing.
 - `notify(value: string | number | boolean | undefined | null)`: immediately injects an extra `custom_tool_call_output` for the current `exec` call. Values are stringified like `text(...)`.

codex-rs/core/src/tools/code_mode/runner.cjs

@@ -223,14 +223,48 @@ function codeModeWorkerMain() {
     return String(value);
   }
 
-  function normalizeOutputImageUrl(value) {
-    if (typeof value !== 'string' || !value) {
-      throw new TypeError('image expects a non-empty image URL string');
+  function normalizeOutputImage(value) {
+    let imageUrl;
+    let detail;
+    if (typeof value === 'string') {
+      imageUrl = value;
+    } else if (
+      value &&
+      typeof value === 'object' &&
+      !Array.isArray(value)
+    ) {
+      if (typeof value.image_url === 'string') {
+        imageUrl = value.image_url;
+      }
+      if (typeof value.detail === 'string') {
+        detail = value.detail;
+      } else if (
+        Object.prototype.hasOwnProperty.call(value, 'detail') &&
+        value.detail !== null &&
+        typeof value.detail !== 'undefined'
+      ) {
+        throw new TypeError('image detail must be a string when provided');
+      }
     }
-    if (/^(?:https?:\/\/|data:)/i.test(value)) {
-      return value;
+
+    if (typeof imageUrl !== 'string' || !imageUrl) {
+      throw new TypeError(
+        'image expects a non-empty image URL string or an object with image_url and optional detail'
+      );
     }
-    throw new TypeError('image expects an http(s) or data URL');
+    if (!/^(?:https?:\/\/|data:)/i.test(imageUrl)) {
+      throw new TypeError('image expects an http(s) or data URL');
+    }
+
+    if (typeof detail !== 'undefined' && !/^(?:auto|low|high|original)$/i.test(detail)) {
+      throw new TypeError('image detail must be one of: auto, low, high, original');
+    }
+
+    const normalized = { image_url: imageUrl };
+    if (typeof detail === 'string') {
+      normalized.detail = detail.toLowerCase();
+    }
+    return normalized;
   }
 
   function createCodeModeHelpers(context, state, toolCallId) {
@@ -258,10 +292,7 @@ function codeModeWorkerMain() {
       return item;
     };
     const image = (value) => {
-      const item = {
-        type: 'input_image',
-        image_url: normalizeOutputImageUrl(value),
-      };
+      const item = Object.assign({ type: 'input_image' }, normalizeOutputImage(value));
       ensureContentItems(context).push(item);
       return item;
     };