Skip to content

Agent Zero AI framework

Preserve Codex OAuth prompt cache affinity

Alessandro7cd38be5f147
diff --git a/plugins/_oauth/AGENTS.md b/plugins/_oauth/AGENTS.md
index e4d717311..dcbb39472 100644
--- a/plugins/_oauth/AGENTS.md
+++ b/plugins/_oauth/AGENTS.md
@@ -44,6 +44,8 @@
- Browser callback providers must support manual callback paste when the browser cannot reach the local callback route.
- Local proxy routes must remain loopback or token protected and must not add broad CORS access.
- Codex Responses proxy requests must include Codex client metadata and compatibility headers such as `client_metadata`, `x-codex-installation-id`, `originator`, `session-id`, and `thread-id`, and must forward `input` as a list for upstream Codex compatibility.
+- `chat_model_call_before/_20_codex_session.py` gives Codex main-model turns stable per-chat, per-agent session/thread IDs for cache routing. Preserve explicit caller session/thread IDs through both proxy routes, including Chat Completions conversion, while keeping installation/window metadata plugin-owned.
+- Default `prompt_cache_key` to a caller-supplied session ID (hash IDs longer than 64 characters); preserve explicit keys and do not derive keys from randomly generated fallback metadata. Codex provider defaults use local Responses state because its backend requires `store: false`.
- Codex Responses proxy requests must translate the legacy top-level `reasoning_effort` field to `reasoning.effort`; an explicit native `reasoning` field takes precedence.
- Codex Responses proxy defaults for reasoning effort, reasoning summary, and text verbosity come from the `codex` plugin config; explicit native request values take precedence.
- Codex request shaping tightens an already-advertised native `response` tool to a strict required `text` schema; it must not add tools omitted by the framework tool policy.
diff --git a/plugins/_oauth/conf/model_providers.yaml b/plugins/_oauth/conf/model_providers.yaml
index 058ad71af..2ad9045e0 100644
--- a/plugins/_oauth/conf/model_providers.yaml
+++ b/plugins/_oauth/conf/model_providers.yaml
@@ -7,6 +7,7 @@ chat:
endpoint_url: "/models"
kwargs:
a0_api_mode: responses
+ responses_state: local
api_base: "http://127.0.0.1/oauth/codex/v1"
github_copilot_oauth:
name: GitHub Copilot Account
diff --git a/plugins/_oauth/extensions/python/chat_model_call_before/_20_codex_session.py b/plugins/_oauth/extensions/python/chat_model_call_before/_20_codex_session.py
new file mode 100644
index 000000000..ac47ced48
--- /dev/null
+++ b/plugins/_oauth/extensions/python/chat_model_call_before/_20_codex_session.py
@@ -0,0 +1,17 @@
+from helpers.extension import Extension
+
+
+class CodexSession(Extension):
+ def execute(self, call_data: dict, **kwargs):
+ model = call_data.get("model")
+ config = getattr(model, "a0_model_conf", None)
+ if not self.agent or getattr(config, "provider", "") != "codex_oauth":
+ return
+
+ extra_body = dict(model.kwargs.get("extra_body") or {})
+ metadata = dict(extra_body.get("client_metadata") or {})
+ session_id = f"agent-zero-{self.agent.context.id}-{self.agent.number}"
+ metadata.setdefault("session_id", session_id)
+ metadata.setdefault("thread_id", session_id)
+ extra_body["client_metadata"] = metadata
+ model.kwargs["extra_body"] = extra_body
diff --git a/plugins/_oauth/helpers/codex.py b/plugins/_oauth/helpers/codex.py
index dfb5b67ef..aaf608f78 100644
--- a/plugins/_oauth/helpers/codex.py
+++ b/plugins/_oauth/helpers/codex.py
@@ -729,7 +729,11 @@ def prepare_responses_body(body: dict[str, Any], *, force_stream: bool) -> dict[
normalized["input"] = []
normalized.setdefault("instructions", "")
normalized.setdefault("store", False)
- normalized["client_metadata"] = merge_client_metadata(normalized.get("client_metadata"))
+ metadata = normalized.get("client_metadata")
+ if isinstance(metadata, dict) and (session_id := _string(metadata.get("session_id"))):
+ cache_key = session_id if len(session_id) <= 64 else hashlib.sha256(session_id.encode()).hexdigest()
+ normalized.setdefault("prompt_cache_key", cache_key)
+ normalized["client_metadata"] = merge_client_metadata(metadata)
if force_stream:
normalized["stream"] = True
if isinstance(normalized.get("reasoning"), dict):
@@ -758,7 +762,11 @@ def merge_client_metadata(value: Any) -> dict[str, str]:
for key, item in (value.items() if isinstance(value, dict) else [])
if item is not None and str(item)
}
- metadata.update(build_client_metadata())
+ defaults = build_client_metadata()
+ for key in ("session_id", "thread_id"):
+ if key in metadata:
+ defaults[key] = metadata[key]
+ metadata.update(defaults)
return metadata
@@ -956,6 +964,9 @@ def chat_messages_to_response_body(body: dict[str, Any]) -> dict[str, Any]:
"instructions": "\n\n".join(instructions),
"store": False,
}
+ for key in ("client_metadata", "prompt_cache_key"):
+ if key in body:
+ response_body[key] = body[key]
if body.get("temperature") is not None:
response_body["temperature"] = body["temperature"]
if body.get("top_p") is not None:
diff --git a/tests/test_oauth_codex.py b/tests/test_oauth_codex.py
index 989745b53..7b43704cc 100644
--- a/tests/test_oauth_codex.py
+++ b/tests/test_oauth_codex.py
@@ -8,6 +8,7 @@ import sys
import threading
import time
from pathlib import Path
+from types import SimpleNamespace
import pytest
import yaml
@@ -19,6 +20,9 @@ from plugins._oauth.helpers.providers import codex as codex_provider
from plugins._oauth.extensions.python._functions.models.get_api_key.end import (
_20_oauth_account_dummy_key as oauth_dummy_key,
)
+from plugins._oauth.extensions.python.chat_model_call_before._20_codex_session import (
+ CodexSession,
+)
@pytest.fixture(autouse=True)
@@ -72,6 +76,7 @@ def test_build_authorize_url_uses_existing_a0_origin_callback(monkeypatch):
def test_chat_messages_to_response_body_extracts_instructions():
+ metadata = {"session_id": "chat-session", "thread_id": "chat-thread"}
body = codex.chat_messages_to_response_body(
{
"model": "gpt-5.2",
@@ -81,6 +86,8 @@ def test_chat_messages_to_response_body_extracts_instructions():
],
"temperature": 0.2,
"reasoning_effort": "high",
+ "client_metadata": metadata,
+ "prompt_cache_key": "caller-cache",
}
)
@@ -89,6 +96,8 @@ def test_chat_messages_to_response_body_extracts_instructions():
assert body["input"] == [{"role": "user", "content": "Hello"}]
assert body["temperature"] == 0.2
assert body["reasoning"] == {"effort": "high"}
+ assert body["client_metadata"] == metadata
+ assert body["prompt_cache_key"] == "caller-cache"
def test_chat_messages_to_response_body_uses_current_codex_default_model():
@@ -209,6 +218,65 @@ def test_prepare_responses_body_adds_codex_client_metadata(monkeypatch):
assert body["include"] == ["output_text", "reasoning.encrypted_content"]
+def test_codex_session_metadata_is_stable_and_scoped(monkeypatch):
+ monkeypatch.setattr(codex, "codex_config", lambda: {})
+ monkeypatch.setattr(codex, "resolve_installation_id", lambda: "install-1")
+
+ def prepare(context_id="chat-1", number=0, provider="codex_oauth", metadata=None):
+ extra_body = {"client_metadata": dict(metadata or {}), "other": "keep"}
+ model = SimpleNamespace(
+ a0_model_conf=SimpleNamespace(provider=provider),
+ kwargs={"extra_body": extra_body},
+ )
+ agent = SimpleNamespace(context=SimpleNamespace(id=context_id), number=number)
+ CodexSession(agent=agent).execute(call_data={"model": model})
+ assert extra_body == {"client_metadata": dict(metadata or {}), "other": "keep"}
+ assert model.kwargs["extra_body"]["other"] == "keep"
+ if provider != "codex_oauth":
+ assert model.kwargs["extra_body"] is extra_body
+ return None
+ return codex.prepare_responses_body(
+ {"input": [], **model.kwargs["extra_body"]}, force_stream=True
+ )["client_metadata"]
+
+ first = prepare()
+ assert first == prepare()
+ assert first["session_id"] == first["thread_id"] == "agent-zero-chat-1-0"
+ assert first["session_id"] != prepare(context_id="chat-2")["session_id"]
+ assert first["session_id"] != prepare(number=1)["session_id"]
+ explicit = prepare(metadata={
+ "session_id": "caller-session", "thread_id": "caller-thread",
+ "caller": "keep", "x-codex-installation-id": "stale",
+ })
+ assert explicit["session_id"] == "caller-session"
+ assert explicit["thread_id"] == "caller-thread"
+ assert explicit["caller"] == "keep"
+ assert explicit["x-codex-installation-id"] == "install-1"
+ assert prepare(provider="openai") is None
+
+
[email protected]("session_id", ["chat-session", "x" * 100])
+def test_codex_cache_key_uses_caller_session_without_mutating_input(monkeypatch, session_id):
+ monkeypatch.setattr(codex, "codex_config", lambda: {})
+ monkeypatch.setattr(codex, "build_client_metadata", lambda: {"session_id": "random-fallback"})
+ source = {"input": [], "client_metadata": {"session_id": session_id}}
+ first = codex.prepare_responses_body(source, force_stream=True)
+ second = codex.prepare_responses_body(source, force_stream=True)
+
+ assert first["prompt_cache_key"] == second["prompt_cache_key"]
+ assert first["prompt_cache_key"] == (
+ session_id if len(session_id) <= 64 else codex.hashlib.sha256(session_id.encode()).hexdigest()
+ )
+ assert len(first["prompt_cache_key"]) <= 64
+ assert "prompt_cache_key" not in source
+ assert codex.prepare_responses_body(
+ {**source, "prompt_cache_key": "caller-cache"}, force_stream=True
+ )["prompt_cache_key"] == "caller-cache"
+ assert "prompt_cache_key" not in codex.prepare_responses_body(
+ {"input": []}, force_stream=True
+ )
+
+
def test_prepare_responses_body_tightens_existing_response_tool_only(monkeypatch):
monkeypatch.setattr(codex, "codex_config", lambda: {})
monkeypatch.setattr(codex, "build_client_metadata", lambda: {})
@@ -1060,6 +1128,7 @@ def test_provider_config_uses_container_local_agent_zero_origin():
assert codex_provider["name"] == "Codex/ChatGPT Account"
assert codex_provider["models_list"]["endpoint_url"] == "/models"
assert codex_provider["kwargs"]["api_base"] == "http://127.0.0.1/oauth/codex/v1"
+ assert codex_provider["kwargs"]["responses_state"] == "local"
assert "50001" not in json.dumps(codex_provider)