Codex: move system prompts into user input for Responses API

openhands-sdk/openhands/sdk/llm/llm.py

@@ -1010,6 +1010,12 @@ def format_messages_for_responses(
         - Uses Message.to_responses_value to get either instructions (system)
          or input items (others)
         - Concatenates system instructions into a single instructions string
+
+        Codex subscription endpoints can reject complex/long `instructions`
+        ("Instructions are not valid"). When using the ChatGPT subscription
+        transport (chatgpt.com/backend-api/codex), avoid sending system prompts
+        as top-level instructions and instead prepend them to the first user
+        message.
         """
         msgs = copy.deepcopy(messages)
 
@@ -1019,18 +1025,86 @@ def format_messages_for_responses(
         # Assign system instructions as a string, collect input items
         instructions: str | None = None
         input_items: list[dict[str, Any]] = []
+        system_chunks: list[str] = []
+
+        # Subscription transport gate: only apply this workaround when calling
+        # ChatGPT subscription Codex backend (not the standard OpenAI API).
+        base = (self.base_url or "").lower()
+        is_subscription_codex_transport = (
+            "chatgpt.com" in base and "backend-api" in base and "codex" in base
+        )
+
+        DEFAULT_CODEX_INSTRUCTIONS = (
+            "You are OpenHands agent, a helpful AI assistant that can interact "
+            "with a computer to solve tasks."
+        )
+
         for m in msgs:
             val = m.to_responses_value(vision_enabled=vision_active)
             if isinstance(val, str):
                 s = val.strip()
                 if not s:
                     continue
-                instructions = (
-                    s if instructions is None else f"{instructions}\n\n---\n\n{s}"
-                )
+                if is_subscription_codex_transport:
+                    system_chunks.append(s)
+                else:
+                    instructions = (
+                        s
+                        if instructions is None
+                        else f"{instructions}\n\n---\n\n{s}"
+                    )
             else:
                 if val:
                     input_items.extend(val)
+
+        if is_subscription_codex_transport and system_chunks:
+            merged_system = "\n\n---\n\n".join(system_chunks).strip()
+            if merged_system:
+                prefix = f"Context (system prompt):\n{merged_system}\n\n"
+                injected = False
+                for item in input_items:
+                    if item.get("type") == "message" and item.get("role") == "user":
+                        content = item.get("content")
+                        if not isinstance(content, list):
+                            content = [content] if content else []
+                        item["content"] = (
+                            [{"type": "input_text", "text": prefix}] + content
+                        )
+                        injected = True
+                        break
+
+                if not injected:
+                    input_items.insert(
+                        0,
+                        {
+                            "role": "user",
+                            "content": [{"type": "input_text", "text": prefix}],
+                        },
+                    )
+
+        # For subscription Codex transport, normalize message items to match
+        # the shape used by OpenCode's Codex client:
+        #   {"role": "user", "content": [{"type": "input_text", ...}]}
+        # instead of our generic {"type": "message", ...} wrapper.
+        if is_subscription_codex_transport and input_items:
+            normalized: list[dict[str, Any]] = []
+            for item in input_items:
+                if item.get("type") == "message":
+                    normalized.append(
+                        {
+                            "role": item.get("role"),
+                            "content": item.get("content") or [],
+                        }
+                    )
+                else:
+                    normalized.append(item)
+            input_items = normalized
+
+        # For subscription Codex transport, use a small, stable instructions string
+        # (required by the endpoint) and move the full system prompt into user content.
+        if is_subscription_codex_transport:
+            return DEFAULT_CODEX_INSTRUCTIONS, input_items
+
         return instructions, input_items
 
     def get_token_count(self, messages: list[Message]) -> int:

tests/sdk/llm/test_responses_serialization.py

@@ -48,6 +48,47 @@ def test_system_to_responses_value_instructions_concat():
     assert inputs == []
 
 
+def test_subscription_codex_transport_does_not_use_top_level_instructions_and_prepend_system_to_user():  # noqa: E501
+    m_sys = Message(role="system", content=[TextContent(text="SYS")])
+    m_user = Message(role="user", content=[TextContent(text="USER")])
+
+    llm = LLM(model="gpt-5.1-codex", base_url="https://chatgpt.com/backend-api/codex")
+    instr, inputs = llm.format_messages_for_responses([m_sys, m_user])
+
+    assert instr is not None
+    assert "OpenHands agent" in instr
+    assert len(inputs) >= 1
+    first_user = next(it for it in inputs if it.get("role") == "user")
+    content = first_user.get("content")
+    assert isinstance(content, list)
+    assert content[0]["type"] == "input_text"
+    assert "SYS" in content[0]["text"]
+
+
+def test_subscription_codex_transport_injects_synthetic_user_message_when_none_exists():
+    m_sys = Message(role="system", content=[TextContent(text="SYS")])
+    m_asst = Message(role="assistant", content=[TextContent(text="ASST")])
+
+    llm = LLM(model="gpt-5.1-codex", base_url="https://chatgpt.com/backend-api/codex")
+    instr, inputs = llm.format_messages_for_responses([m_sys, m_asst])
+
+    assert instr is not None
+    assert "OpenHands agent" in instr
+    assert len(inputs) >= 1
+    first = inputs[0]
+    assert first.get("role") == "user"
+    assert "SYS" in first["content"][0]["text"]
+
+
+def test_api_codex_models_keep_system_as_instructions():
+    m_sys = Message(role="system", content=[TextContent(text="SYS")])
+    llm = LLM(model="gpt-5.1-codex")
+    instr, inputs = llm.format_messages_for_responses([m_sys])
+
+    assert instr == "SYS"
+    assert inputs == []
+
+
 def test_user_to_responses_dict_with_and_without_vision():
     m = Message(
         role="user",