Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Keep inline system reminders cache-stable across providers (#1154)

Ali Khokhar0de7608b5285
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index bad4ffb9..8bd007f0 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -699,13 +699,17 @@ usage quirks such as DeepSeek prompt-cache counters.
stream ledger, Anthropic SSE emitter, continuation-body construction, and tool repair;
- token counting and Anthropic-owned failure-kind-to-wire mapping.
-Anthropic request models validate transcript data without merging, hoisting, or
-reordering semantically meaningful message roles. Top-level `system` content
-stays distinct from inline `system` messages. Target-protocol conversion owns
-their representation: neutral OpenAI Chat conversion preserves inline role and
-order, and rejects unrepresentable blocks instead of dropping them. Any
-provider-specific deviation belongs in an explicit request policy backed by a
-known upstream incompatibility.
+`MessagesRequest` is an ingress model; no current provider sends Anthropic wire
+requests downstream. Anthropic request models validate transcript data without
+merging, hoisting, or reordering semantically meaningful message roles.
+Top-level `system` content stays distinct from inline `system` messages.
+Target-protocol conversion owns their representation: neutral OpenAI Chat
+conversion emits top-level `system` content as the sole leading system message
+and maps inline `system` content into ordered `user` turns. After tool-result
+dependencies are ordered, adjacent user content is coalesced into one turn so
+strict chat templates do not receive consecutive user roles. Conversion
+preserves content order and rejects unrepresentable blocks instead of dropping
+them. Provider policies do not reinterpret this role mapping.
User image conversion is a pure protocol operation. Core maps Anthropic base64
and URL image sources to ordered OpenAI `image_url` content parts without
diff --git a/pyproject.toml b/pyproject.toml
index a62d32cc..de3b4fa8 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "4.8.0"
+version = "4.8.1"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/src/free_claude_code/core/anthropic/conversion.py b/src/free_claude_code/core/anthropic/conversion.py
index eb07ac60..e760353a 100644
--- a/src/free_claude_code/core/anthropic/conversion.py
+++ b/src/free_claude_code/core/anthropic/conversion.py
@@ -219,6 +219,55 @@ def _openai_user_image_part(block: Any) -> dict[str, Any]:
return {"type": "image_url", "image_url": {"url": url}}
+def _openai_user_content_parts(content: Any) -> list[dict[str, Any]]:
+ """Return an owned content-part list for one converted user message."""
+ if isinstance(content, str):
+ return [{"type": "text", "text": content}]
+ if isinstance(content, list) and all(isinstance(part, dict) for part in content):
+ return deepcopy(content)
+ raise OpenAIConversionError(
+ "OpenAI chat conversion produced unsupported user message content."
+ )
+
+
+def _merge_openai_user_content(first: Any, second: Any) -> str | list[dict[str, Any]]:
+ """Combine adjacent user content while preserving multimodal part order."""
+ if isinstance(first, str) and isinstance(second, str):
+ return f"{first}\n\n{second}"
+
+ first_parts = _openai_user_content_parts(first)
+ second_parts = _openai_user_content_parts(second)
+ first_ends_in_text = bool(first_parts) and first_parts[-1].get("type") == "text"
+ second_starts_with_text = (
+ bool(second_parts) and second_parts[0].get("type") == "text"
+ )
+ if first_ends_in_text and second_starts_with_text:
+ first_text = first_parts[-1].get("text", "")
+ second_text = second_parts.pop(0).get("text", "")
+ first_parts[-1]["text"] = f"{first_text}\n\n{second_text}"
+ return [*first_parts, *second_parts]
+
+
+def _coalesce_openai_user_messages(
+ messages: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+ """Combine adjacent user messages after transcript ordering is complete."""
+ result: list[dict[str, Any]] = []
+ for message in messages:
+ if (
+ message.get("role") == "user"
+ and result
+ and result[-1].get("role") == "user"
+ ):
+ previous = result[-1]
+ previous["content"] = _merge_openai_user_content(
+ previous.get("content"), message.get("content")
+ )
+ continue
+ result.append(message)
+ return result
+
+
class _OpenAIChatHistoryLedger:
"""Assemble OpenAI chat history while respecting tool-result dependencies."""
@@ -382,7 +431,7 @@ class AnthropicToOpenAIConverter:
else:
ledger.add_tool_turn(segment)
- return ledger.finish()
+ return _coalesce_openai_user_messages(ledger.finish())
@staticmethod
def _convert_message_to_segments(
@@ -402,7 +451,8 @@ class AnthropicToOpenAIConverter:
"OpenAI chat conversion requires an inline Anthropic system "
"message to contain text."
)
- return [_PlainSegment([{"role": "system", "content": system_text}])]
+ # Reserve the downstream system role for request.system at index zero.
+ return [_PlainSegment([{"role": "user", "content": system_text}])]
if role == "assistant" and isinstance(content, list):
if (first_i := _index_first_tool_use(content)) is not None:
for block in content:
diff --git a/tests/providers/test_converter.py b/tests/providers/test_converter.py
index 23124bc9..52a663a8 100644
--- a/tests/providers/test_converter.py
+++ b/tests/providers/test_converter.py
@@ -59,16 +59,18 @@ def test_convert_system_prompt_none():
assert AnthropicToOpenAIConverter.convert_system_prompt(None) is None
-def test_openai_build_preserves_top_level_and_inline_system_message_order() -> None:
+def test_openai_build_uses_only_top_level_system_role() -> None:
request = MessagesRequest.model_validate(
{
"model": "model",
"system": "Conversation-wide instructions",
"messages": [
{"role": "user", "content": "First question"},
- {"role": "assistant", "content": "First answer"},
{"role": "system", "content": "Instructions from this point"},
+ {"role": "system", "content": "A second reminder"},
+ {"role": "assistant", "content": "First answer"},
{"role": "user", "content": "Second question"},
+ {"role": "system", "content": "A final reminder"},
],
}
)
@@ -77,14 +79,18 @@ def test_openai_build_preserves_top_level_and_inline_system_message_order() -> N
assert body["messages"] == [
{"role": "system", "content": "Conversation-wide instructions"},
- {"role": "user", "content": "First question"},
+ {
+ "role": "user",
+ "content": (
+ "First question\n\nInstructions from this point\n\nA second reminder"
+ ),
+ },
{"role": "assistant", "content": "First answer"},
- {"role": "system", "content": "Instructions from this point"},
- {"role": "user", "content": "Second question"},
+ {"role": "user", "content": "Second question\n\nA final reminder"},
]
-def test_openai_build_joins_inline_system_text_blocks_without_repositioning() -> None:
+def test_openai_build_demotes_inline_system_text_blocks_without_repositioning() -> None:
request = MessagesRequest.model_validate(
{
"model": "model",
@@ -97,17 +103,18 @@ def test_openai_build_joins_inline_system_text_blocks_without_repositioning() ->
{"type": "text", "text": "Second instruction"},
],
},
- {"role": "user", "content": "After"},
],
}
)
body = build_base_request_body(request)
- assert body["messages"][1] == {
- "role": "system",
- "content": "First instruction\n\nSecond instruction",
- }
+ assert body["messages"] == [
+ {
+ "role": "user",
+ "content": "Before\n\nFirst instruction\n\nSecond instruction",
+ }
+ ]
def test_inline_system_message_preserves_existing_openai_cache_prefix() -> None:
@@ -128,8 +135,14 @@ def test_inline_system_message_preserves_existing_openai_cache_prefix() -> None:
"messages": [
{"role": "user", "content": "First question"},
{"role": "assistant", "content": "First answer"},
- {"role": "system", "content": "Instructions from this point"},
{"role": "user", "content": "Second question"},
+ {
+ "role": "system",
+ "content": (
+ "<system-reminder>Instructions from this point"
+ "</system-reminder>"
+ ),
+ },
],
}
)
@@ -139,8 +152,57 @@ def test_inline_system_message_preserves_existing_openai_cache_prefix() -> None:
assert continued[: len(prefix)] == prefix
assert continued[len(prefix) :] == [
- {"role": "system", "content": "Instructions from this point"},
- {"role": "user", "content": "Second question"},
+ {
+ "role": "user",
+ "content": (
+ "Second question\n\n<system-reminder>Instructions from this point"
+ "</system-reminder>"
+ ),
+ }
+ ]
+
+
+def test_inline_system_message_coalesces_with_multimodal_user_content() -> None:
+ request = MessagesRequest.model_validate(
+ {
+ "model": "model",
+ "messages": [
+ {"role": "user", "content": "Existing context."},
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "image",
+ "source": {
+ "type": "url",
+ "url": "https://example.com/image.png",
+ },
+ },
+ {"type": "text", "text": "Inspect this image."},
+ ],
+ },
+ {"role": "system", "content": "Focus on correctness."},
+ ],
+ }
+ )
+
+ body = build_base_request_body(request)
+
+ assert body["messages"] == [
+ {
+ "role": "user",
+ "content": [
+ {"type": "text", "text": "Existing context."},
+ {
+ "type": "image_url",
+ "image_url": {"url": "https://example.com/image.png"},
+ },
+ {
+ "type": "text",
+ "text": "Inspect this image.\n\nFocus on correctness.",
+ },
+ ],
+ }
]
@@ -149,6 +211,7 @@ def test_inline_system_message_follows_completed_tool_result() -> None:
{
"model": "model",
"messages": [
+ {"role": "user", "content": "Use the tool"},
{
"role": "assistant",
"content": [
@@ -178,10 +241,12 @@ def test_inline_system_message_follows_completed_tool_result() -> None:
body = build_base_request_body(request)
assert [message["role"] for message in body["messages"]] == [
+ "user",
"assistant",
"tool",
- "system",
+ "user",
]
+ assert body["messages"][-1]["content"] == "New instructions"
def test_openai_build_rejects_non_text_inline_system_blocks() -> None:
diff --git a/uv.lock b/uv.lock
index 1bed0e4a..e316a2b0 100644
--- a/uv.lock
+++ b/uv.lock
@@ -561,7 +561,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "4.8.0"
+version = "4.8.1"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },