Merge 76bf2e0be5 into sapling-pr-archive-bolinfest

This commit is contained in:
Michael Bolin
2026-04-03 19:54:33 -07:00
committed by GitHub
18 changed files with 908 additions and 43 deletions
+1
View File
@@ -2552,6 +2552,7 @@ dependencies = [
"codex-process-hardening",
"ctor 0.6.3",
"libc",
"pretty_assertions",
"reqwest",
"serde",
"serde_json",
+8 -1
View File
@@ -524,6 +524,9 @@
"include_apps_instructions": {
"type": "boolean"
},
"include_environment_context": {
"type": "boolean"
},
"include_permissions_instructions": {
"type": "boolean"
},
@@ -2278,6 +2281,10 @@
"description": "Whether to inject the `<apps_instructions>` developer block.",
"type": "boolean"
},
"include_environment_context": {
"description": "Whether to inject the `<environment_context>` user block.",
"type": "boolean"
},
"include_permissions_instructions": {
"description": "Whether to inject the `<permissions instructions>` developer block.",
"type": "boolean"
@@ -2641,4 +2648,4 @@
},
"title": "ConfigToml",
"type": "object"
}
}
+39 -10
View File
@@ -332,6 +332,7 @@ use codex_protocol::config_types::ServiceTier;
use codex_protocol::config_types::WindowsSandboxLevel;
use codex_protocol::models::ContentItem;
use codex_protocol::models::DeveloperInstructions;
use codex_protocol::models::MessagePhase;
use codex_protocol::models::ResponseInputItem;
use codex_protocol::models::ResponseItem;
use codex_protocol::openai_models::ReasoningEffort as ReasoningEffortConfig;
@@ -3688,16 +3689,18 @@ impl Session {
.serialize_to_text(),
);
}
let subagents = self
.services
.agent_control
.format_environment_context_subagents(self.conversation_id)
.await;
contextual_user_sections.push(
EnvironmentContext::from_turn_context(turn_context, shell.as_ref())
.with_subagents(subagents)
.serialize_to_xml(),
);
if turn_context.config.include_environment_context {
let subagents = self
.services
.agent_control
.format_environment_context_subagents(self.conversation_id)
.await;
contextual_user_sections.push(
EnvironmentContext::from_turn_context(turn_context, shell.as_ref())
.with_subagents(subagents)
.serialize_to_xml(),
);
}
let mut items = Vec::with_capacity(3);
if let Some(developer_message) =
@@ -7424,6 +7427,25 @@ async fn try_run_sampling_request(
cancellation_token: cancellation_token.child_token(),
};
let preempt_for_mailbox_mail = match &item {
ResponseItem::Message { role, phase, .. } => {
role == "assistant" && matches!(phase, Some(MessagePhase::Commentary))
}
ResponseItem::Reasoning { .. } => true,
ResponseItem::LocalShellCall { .. }
| ResponseItem::FunctionCall { .. }
| ResponseItem::ToolSearchCall { .. }
| ResponseItem::FunctionCallOutput { .. }
| ResponseItem::CustomToolCall { .. }
| ResponseItem::CustomToolCallOutput { .. }
| ResponseItem::ToolSearchOutput { .. }
| ResponseItem::WebSearchCall { .. }
| ResponseItem::ImageGenerationCall { .. }
| ResponseItem::GhostSnapshot { .. }
| ResponseItem::Compaction { .. }
| ResponseItem::Other => false,
};
let output_result = handle_output_item_done(&mut ctx, item, previously_active_item)
.instrument(handle_responses)
.await?;
@@ -7434,6 +7456,13 @@ async fn try_run_sampling_request(
last_agent_message = Some(agent_message);
}
needs_follow_up |= output_result.needs_follow_up;
// todo: remove before stabilizing multi-agent v2
if preempt_for_mailbox_mail && sess.mailbox_rx.lock().await.has_pending() {
break Ok(SamplingRequestResult {
needs_follow_up: true,
last_agent_message,
});
}
}
ResponseEvent::OutputItemAdded(item) => {
if let Some(turn_item) = handle_non_tool_response_item(
+52 -22
View File
@@ -283,6 +283,23 @@ fn developer_input_texts(items: &[ResponseItem]) -> Vec<&str> {
.collect()
}
fn user_input_texts(items: &[ResponseItem]) -> Vec<&str> {
items
.iter()
.filter_map(|item| match item {
ResponseItem::Message { role, content, .. } if role == "user" => {
Some(content.as_slice())
}
_ => None,
})
.flat_map(|content| content.iter())
.filter_map(|item| match item {
ContentItem::InputText { text } => Some(text.as_str()),
_ => None,
})
.collect()
}
fn test_tool_runtime(session: Arc<Session>, turn_context: Arc<TurnContext>) -> ToolCallRuntime {
let router = Arc::new(ToolRouter::from_config(
&turn_context.tools_config,
@@ -3774,17 +3791,9 @@ async fn build_settings_update_items_emits_environment_item_for_network_changes(
.build_settings_update_items(Some(&reference_context_item), &current_context)
.await;
let environment_update = update_items
.iter()
.find_map(|item| match item {
ResponseItem::Message { role, content, .. } if role == "user" => {
let [ContentItem::InputText { text }] = content.as_slice() else {
return None;
};
text.contains("<environment_context>").then_some(text)
}
_ => None,
})
let environment_update = user_input_texts(&update_items)
.into_iter()
.find(|text| text.contains("<environment_context>"))
.expect("environment update item should be emitted");
assert!(environment_update.contains("<network enabled=\"true\">"));
assert!(environment_update.contains("<allowed>api.example.com</allowed>"));
@@ -3809,22 +3818,43 @@ async fn build_settings_update_items_emits_environment_item_for_time_changes() {
.build_settings_update_items(Some(&reference_context_item), &current_context)
.await;
let environment_update = update_items
.iter()
.find_map(|item| match item {
ResponseItem::Message { role, content, .. } if role == "user" => {
let [ContentItem::InputText { text }] = content.as_slice() else {
return None;
};
text.contains("<environment_context>").then_some(text)
}
_ => None,
})
let environment_update = user_input_texts(&update_items)
.into_iter()
.find(|text| text.contains("<environment_context>"))
.expect("environment update item should be emitted");
assert!(environment_update.contains("<current_date>2026-02-27</current_date>"));
assert!(environment_update.contains("<timezone>Europe/Berlin</timezone>"));
}
#[tokio::test]
async fn build_settings_update_items_omits_environment_item_when_disabled() {
let (session, previous_context) = make_session_and_context().await;
let previous_context = Arc::new(previous_context);
let mut current_context = previous_context
.with_model(
previous_context.model_info.slug.clone(),
&session.services.models_manager,
)
.await;
let mut config = (*current_context.config).clone();
config.include_environment_context = false;
current_context.config = Arc::new(config);
current_context.current_date = Some("2026-02-27".to_string());
let reference_context_item = previous_context.to_turn_context_item();
let update_items = session
.build_settings_update_items(Some(&reference_context_item), &current_context)
.await;
let user_texts = user_input_texts(&update_items);
assert!(
!user_texts
.iter()
.any(|text| text.contains("<environment_context>")),
"did not expect environment context updates when disabled, got {user_texts:?}"
);
}
#[tokio::test]
async fn build_settings_update_items_emits_realtime_start_when_session_becomes_live() {
let (session, previous_context) = make_session_and_context().await;
+7
View File
@@ -4495,6 +4495,7 @@ fn test_precedence_fixture_with_o3_profile() -> std::io::Result<()> {
guardian_developer_instructions: None,
include_permissions_instructions: true,
include_apps_instructions: true,
include_environment_context: true,
compact_prompt: None,
commit_attribution: None,
forced_chatgpt_workspace_id: None,
@@ -4639,6 +4640,7 @@ fn test_precedence_fixture_with_gpt3_profile() -> std::io::Result<()> {
guardian_developer_instructions: None,
include_permissions_instructions: true,
include_apps_instructions: true,
include_environment_context: true,
compact_prompt: None,
commit_attribution: None,
forced_chatgpt_workspace_id: None,
@@ -4781,6 +4783,7 @@ fn test_precedence_fixture_with_zdr_profile() -> std::io::Result<()> {
guardian_developer_instructions: None,
include_permissions_instructions: true,
include_apps_instructions: true,
include_environment_context: true,
compact_prompt: None,
commit_attribution: None,
forced_chatgpt_workspace_id: None,
@@ -4909,6 +4912,7 @@ fn test_precedence_fixture_with_gpt5_profile() -> std::io::Result<()> {
guardian_developer_instructions: None,
include_permissions_instructions: true,
include_apps_instructions: true,
include_environment_context: true,
compact_prompt: None,
commit_attribution: None,
forced_chatgpt_workspace_id: None,
@@ -5799,10 +5803,12 @@ async fn prompt_instruction_blocks_can_be_disabled_from_config_and_profiles() ->
codex_home.path().join(CONFIG_TOML_FILE),
r#"include_permissions_instructions = false
include_apps_instructions = false
include_environment_context = false
profile = "chatty"
[profiles.chatty]
include_permissions_instructions = true
include_environment_context = true
"#,
)?;
@@ -5814,6 +5820,7 @@ include_permissions_instructions = true
assert!(config.include_permissions_instructions);
assert!(!config.include_apps_instructions);
assert!(config.include_environment_context);
Ok(())
}
+11
View File
@@ -286,6 +286,9 @@ pub struct Config {
/// Whether to inject the `<apps_instructions>` developer block.
pub include_apps_instructions: bool,
/// Whether to inject the `<environment_context>` user block.
pub include_environment_context: bool,
/// Compact prompt override.
pub compact_prompt: Option<String>,
@@ -1195,6 +1198,9 @@ pub struct ConfigToml {
/// Whether to inject the `<apps_instructions>` developer block.
pub include_apps_instructions: Option<bool>,
/// Whether to inject the `<environment_context>` user block.
pub include_environment_context: Option<bool>,
/// Optional path to a file containing model instructions that will override
/// the built-in instructions for the selected model. Users are STRONGLY
/// DISCOURAGED from using this field, as deviating from the instructions
@@ -2472,6 +2478,10 @@ impl Config {
.include_apps_instructions
.or(cfg.include_apps_instructions)
.unwrap_or(true);
let include_environment_context = config_profile
.include_environment_context
.or(cfg.include_environment_context)
.unwrap_or(true);
let guardian_developer_instructions = guardian_developer_instructions_from_requirements(
config_layer_stack.requirements_toml(),
);
@@ -2640,6 +2650,7 @@ impl Config {
commit_attribution,
include_permissions_instructions,
include_apps_instructions,
include_environment_context,
// The config.toml omits "_mode" because it's a config file. However, "_mode"
// is important in code to differentiate the mode from the store implementation.
cli_auth_credentials_store_mode: cfg.cli_auth_credentials_store.unwrap_or_default(),
+1
View File
@@ -51,6 +51,7 @@ pub struct ConfigProfile {
pub include_apply_patch_tool: Option<bool>,
pub include_permissions_instructions: Option<bool>,
pub include_apps_instructions: Option<bool>,
pub include_environment_context: Option<bool>,
pub experimental_use_unified_exec_tool: Option<bool>,
pub experimental_use_freeform_apply_patch: Option<bool>,
pub tools_view_image: Option<bool>,
@@ -16,6 +16,10 @@ fn build_environment_update_item(
next: &TurnContext,
shell: &Shell,
) -> Option<ResponseItem> {
if !next.config.include_environment_context {
return None;
}
let prev = previous?;
let prev_context = EnvironmentContext::from_turn_context_item(prev, shell);
let next_context = EnvironmentContext::from_turn_context(next, shell);
+39
View File
@@ -1348,6 +1348,45 @@ async fn omits_apps_guidance_when_configured_off() {
);
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn omits_environment_context_when_configured_off() {
let server = MockServer::start().await;
let resp_mock = mount_sse_once(
&server,
sse(vec![ev_response_created("resp1"), ev_completed("resp1")]),
)
.await;
let mut builder = test_codex().with_config(|config| {
config.include_environment_context = false;
});
let codex = builder
.build(&server)
.await
.expect("create new conversation")
.codex;
codex
.submit(Op::UserInput {
items: vec![UserInput::Text {
text: "hello".into(),
text_elements: Vec::new(),
}],
final_output_json_schema: None,
})
.await
.unwrap();
wait_for_event(&codex, |ev| matches!(ev, EventMsg::TurnComplete(_))).await;
let request = resp_mock.single_request();
assert!(
!message_input_text_contains(&request, "user", "<environment_context>"),
"did not expect environment context when include_environment_context = false, got {:?}",
request.body_json()["input"]
);
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn skills_append_to_developer_message() {
skip_if_no_network!();
+282
View File
@@ -1,17 +1,31 @@
use std::sync::Arc;
use codex_core::CodexThread;
use codex_protocol::AgentPath;
use codex_protocol::items::TurnItem;
use codex_protocol::protocol::EventMsg;
use codex_protocol::protocol::InterAgentCommunication;
use codex_protocol::protocol::Op;
use codex_protocol::user_input::UserInput;
use core_test_support::context_snapshot;
use core_test_support::context_snapshot::ContextSnapshotOptions;
use core_test_support::responses;
use core_test_support::responses::ev_completed;
use core_test_support::responses::ev_function_call;
use core_test_support::responses::ev_message_item_added;
use core_test_support::responses::ev_output_text_delta;
use core_test_support::responses::ev_reasoning_item;
use core_test_support::responses::ev_reasoning_item_added;
use core_test_support::responses::ev_response_created;
use core_test_support::streaming_sse::StreamingSseChunk;
use core_test_support::streaming_sse::StreamingSseServer;
use core_test_support::streaming_sse::start_streaming_sse_server;
use core_test_support::test_codex::test_codex;
use core_test_support::wait_for_event;
use pretty_assertions::assert_eq;
use serde_json::Value;
use serde_json::from_slice;
use serde_json::json;
use tokio::sync::oneshot;
fn ev_message_item_done(id: &str, text: &str) -> Value {
@@ -44,6 +58,115 @@ fn message_input_texts(body: &Value, role: &str) -> Vec<String> {
.collect()
}
fn chunk(event: Value) -> StreamingSseChunk {
StreamingSseChunk {
gate: None,
body: responses::sse(vec![event]),
}
}
fn gated_chunk(gate: oneshot::Receiver<()>, events: Vec<Value>) -> StreamingSseChunk {
StreamingSseChunk {
gate: Some(gate),
body: responses::sse(events),
}
}
fn response_completed_chunks(response_id: &str) -> Vec<StreamingSseChunk> {
vec![
chunk(ev_response_created(response_id)),
chunk(ev_completed(response_id)),
]
}
async fn build_codex(server: &StreamingSseServer) -> Arc<CodexThread> {
test_codex()
.with_model("gpt-5.1")
.build_with_streaming_server(server)
.await
.unwrap_or_else(|err| panic!("build streaming Codex test session: {err}"))
.codex
}
async fn submit_user_input(codex: &CodexThread, text: &str) {
codex
.submit(Op::UserInput {
items: vec![UserInput::Text {
text: text.to_string(),
text_elements: Vec::new(),
}],
final_output_json_schema: None,
})
.await
.unwrap_or_else(|err| panic!("submit user input: {err}"));
}
async fn submit_queue_only_agent_mail(codex: &CodexThread, text: &str) {
codex
.submit(Op::InterAgentCommunication {
communication: InterAgentCommunication::new(
AgentPath::try_from("/root/worker")
.unwrap_or_else(|err| panic!("worker path should parse: {err}")),
AgentPath::root(),
Vec::new(),
text.to_string(),
/*trigger_turn*/ false,
),
})
.await
.unwrap_or_else(|err| panic!("submit queue-only agent mail: {err}"));
}
async fn wait_for_reasoning_item_started(codex: &CodexThread) {
wait_for_event(codex, |event| {
matches!(
event,
EventMsg::ItemStarted(item_started)
if matches!(&item_started.item, TurnItem::Reasoning(_))
)
})
.await;
}
async fn wait_for_agent_message(codex: &CodexThread, text: &str) {
let final_message = wait_for_event(
codex,
|event| matches!(event, EventMsg::AgentMessage(message) if message.message == text),
)
.await;
assert!(matches!(final_message, EventMsg::AgentMessage(_)));
}
async fn wait_for_turn_complete(codex: &CodexThread) {
wait_for_event(codex, |event| matches!(event, EventMsg::TurnComplete(_))).await;
}
fn assert_two_responses_input_snapshot(snapshot_name: &str, requests: &[Vec<u8>]) {
assert_eq!(requests.len(), 2);
let options = ContextSnapshotOptions::default().strip_capability_instructions();
let first: Value =
from_slice(&requests[0]).unwrap_or_else(|err| panic!("parse first request: {err}"));
let second: Value =
from_slice(&requests[1]).unwrap_or_else(|err| panic!("parse second request: {err}"));
let first_items = first["input"]
.as_array()
.unwrap_or_else(|| panic!("first request input"))
.clone();
let second_items = second["input"]
.as_array()
.unwrap_or_else(|| panic!("second request input"))
.clone();
let snapshot = context_snapshot::format_labeled_items_snapshot(
"/responses POST bodies (input only, redacted like other suite snapshots)",
&[
("First request", first_items.as_slice()),
("Second request", second_items.as_slice()),
],
&options,
);
insta::assert_snapshot!(snapshot_name, snapshot);
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
#[ignore = "TODO(aibrahim): flaky"]
async fn injected_user_input_triggers_follow_up_request_with_deltas() {
@@ -144,3 +267,162 @@ async fn injected_user_input_triggers_follow_up_request_with_deltas() {
server.shutdown().await;
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn queued_inter_agent_mail_triggers_follow_up_after_reasoning_item() {
let (gate_reasoning_done_tx, gate_reasoning_done_rx) = oneshot::channel();
let first_chunks = vec![
chunk(ev_response_created("resp-1")),
chunk(ev_reasoning_item_added("reason-1", &["thinking"])),
gated_chunk(
gate_reasoning_done_rx,
vec![
ev_reasoning_item("reason-1", &["thinking"], &[]),
ev_function_call(
"call-stale",
"shell",
r#"{"command":"echo stale tool call"}"#,
),
ev_message_item_added("msg-stale", ""),
ev_output_text_delta("stale final"),
ev_message_item_done("msg-stale", "stale final"),
ev_completed("resp-1"),
],
),
];
let (server, _completions) =
start_streaming_sse_server(vec![first_chunks, response_completed_chunks("resp-2")]).await;
let codex = build_codex(&server).await;
submit_user_input(&codex, "first prompt").await;
wait_for_reasoning_item_started(&codex).await;
submit_queue_only_agent_mail(&codex, "queued child update").await;
let _ = gate_reasoning_done_tx.send(());
wait_for_turn_complete(&codex).await;
let requests = server.requests().await;
assert_two_responses_input_snapshot("pending_input_queued_mail_after_reasoning", &requests);
server.shutdown().await;
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn queued_inter_agent_mail_triggers_follow_up_after_commentary_message_item() {
let (gate_message_done_tx, gate_message_done_rx) = oneshot::channel();
let first_chunks = vec![
chunk(ev_response_created("resp-1")),
chunk(ev_message_item_added("msg-1", "")),
gated_chunk(
gate_message_done_rx,
vec![
ev_output_text_delta("first answer"),
json!({
"type": "response.output_item.done",
"item": {
"type": "message",
"role": "assistant",
"id": "msg-1",
"content": [{"type": "output_text", "text": "first answer"}],
"phase": "commentary",
}
}),
ev_function_call(
"call-stale",
"shell",
r#"{"command":"echo stale tool call"}"#,
),
ev_message_item_added("msg-stale", ""),
ev_output_text_delta("stale final"),
ev_message_item_done("msg-stale", "stale final"),
ev_completed("resp-1"),
],
),
];
let (server, _completions) =
start_streaming_sse_server(vec![first_chunks, response_completed_chunks("resp-2")]).await;
let codex = build_codex(&server).await;
submit_user_input(&codex, "first prompt").await;
wait_for_event(&codex, |event| {
matches!(
event,
EventMsg::ItemStarted(item_started)
if matches!(&item_started.item, TurnItem::AgentMessage(_))
)
})
.await;
submit_queue_only_agent_mail(&codex, "queued child update").await;
let _ = gate_message_done_tx.send(());
wait_for_agent_message(&codex, "first answer").await;
wait_for_turn_complete(&codex).await;
let requests = server.requests().await;
assert_two_responses_input_snapshot("pending_input_queued_mail_after_commentary", &requests);
server.shutdown().await;
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn user_input_does_not_preempt_after_reasoning_item() {
let (gate_reasoning_done_tx, gate_reasoning_done_rx) = oneshot::channel();
let first_chunks = vec![
chunk(ev_response_created("resp-1")),
chunk(ev_reasoning_item_added("reason-1", &["thinking"])),
gated_chunk(
gate_reasoning_done_rx,
vec![
ev_reasoning_item("reason-1", &["thinking"], &[]),
ev_function_call(
"call-preserved",
"shell",
r#"{"command":"echo preserved tool call"}"#,
),
ev_message_item_added("msg-1", ""),
ev_output_text_delta("first answer"),
ev_message_item_done("msg-1", "first answer"),
ev_completed("resp-1"),
],
),
];
let (server, _completions) =
start_streaming_sse_server(vec![first_chunks, response_completed_chunks("resp-2")]).await;
let codex = build_codex(&server).await;
submit_user_input(&codex, "first prompt").await;
wait_for_reasoning_item_started(&codex).await;
submit_user_input(&codex, "second prompt").await;
let _ = gate_reasoning_done_tx.send(());
wait_for_agent_message(&codex, "first answer").await;
wait_for_turn_complete(&codex).await;
let requests = server.requests().await;
assert_two_responses_input_snapshot(
"pending_input_user_input_no_preempt_after_reasoning",
&requests,
);
server.shutdown().await;
}
@@ -0,0 +1,17 @@
---
source: core/tests/suite/pending_input.rs
expression: snapshot
---
Scenario: /responses POST bodies (input only, redacted like other suite snapshots)
## First request
00:message/developer:<PERMISSIONS_INSTRUCTIONS>
01:message/user:<ENVIRONMENT_CONTEXT:cwd=<CWD>>
02:message/user:first prompt
## Second request
00:message/developer:<PERMISSIONS_INSTRUCTIONS>
01:message/user:<ENVIRONMENT_CONTEXT:cwd=<CWD>>
02:message/user:first prompt
03:message/assistant:first answer
04:message/assistant:{"author":"/root/worker","recipient":"/root","other_recipients":[],"content":"queued child update","trigger_turn":false}
@@ -0,0 +1,17 @@
---
source: core/tests/suite/pending_input.rs
expression: snapshot
---
Scenario: /responses POST bodies (input only, redacted like other suite snapshots)
## First request
00:message/developer:<PERMISSIONS_INSTRUCTIONS>
01:message/user:<ENVIRONMENT_CONTEXT:cwd=<CWD>>
02:message/user:first prompt
## Second request
00:message/developer:<PERMISSIONS_INSTRUCTIONS>
01:message/user:<ENVIRONMENT_CONTEXT:cwd=<CWD>>
02:message/user:first prompt
03:reasoning:summary=thinking:encrypted=true
04:message/assistant:{"author":"/root/worker","recipient":"/root","other_recipients":[],"content":"queued child update","trigger_turn":false}
@@ -0,0 +1,20 @@
---
source: core/tests/suite/pending_input.rs
expression: snapshot
---
Scenario: /responses POST bodies (input only, redacted like other suite snapshots)
## First request
00:message/developer:<PERMISSIONS_INSTRUCTIONS>
01:message/user:<ENVIRONMENT_CONTEXT:cwd=<CWD>>
02:message/user:first prompt
## Second request
00:message/developer:<PERMISSIONS_INSTRUCTIONS>
01:message/user:<ENVIRONMENT_CONTEXT:cwd=<CWD>>
02:message/user:first prompt
03:reasoning:summary=thinking:encrypted=true
04:function_call/shell
05:message/assistant:first answer
06:function_call_output:failed to parse function arguments: invalid type: string "echo preserved tool call", expected a sequence at line 1 column 37
07:message/user:second prompt
+3
View File
@@ -26,3 +26,6 @@ serde = { workspace = true, features = ["derive"] }
serde_json = { workspace = true }
tiny_http = { workspace = true }
zeroize = { workspace = true }
[dev-dependencies]
pretty_assertions = { workspace = true }
+3 -1
View File
@@ -35,18 +35,20 @@ curl --fail --silent --show-error "${PROXY_BASE_URL}/shutdown"
- Listens on the provided port or an ephemeral port if `--port` is not specified.
- Accepts exactly `POST /v1/responses` (no query string). The request body is forwarded to `https://api.openai.com/v1/responses` with `Authorization: Bearer <key>` set. All original request headers (except any incoming `Authorization`) are forwarded upstream, with `Host` overridden to `api.openai.com`. For other requests, it responds with `403`.
- Optionally writes a single-line JSON file with server info, currently `{ "port": <u16>, "pid": <u32> }`.
- Optionally writes request/response JSON dumps to a directory. Each accepted request gets a pair of files that share a sequence/timestamp prefix, for example `000001-1846179912345-request.json` and `000001-1846179912345-response.json`. Header values are dumped in full except `Authorization` and any header whose name includes `cookie`, which are redacted. Bodies are written as parsed JSON when possible, otherwise as UTF-8 text.
- Optional `--http-shutdown` enables `GET /shutdown` to terminate the process with exit code `0`. This allows one user (e.g., `root`) to start the proxy and another unprivileged user on the host to shut it down.
## CLI
```
codex-responses-api-proxy [--port <PORT>] [--server-info <FILE>] [--http-shutdown] [--upstream-url <URL>]
codex-responses-api-proxy [--port <PORT>] [--server-info <FILE>] [--http-shutdown] [--upstream-url <URL>] [--dump-dir <DIR>]
```
- `--port <PORT>`: Port to bind on `127.0.0.1`. If omitted, an ephemeral port is chosen.
- `--server-info <FILE>`: If set, the proxy writes a single line of JSON with `{ "port": <PORT>, "pid": <PID> }` once listening.
- `--http-shutdown`: If set, enables `GET /shutdown` to exit the process with code `0`.
- `--upstream-url <URL>`: Absolute URL to forward requests to. Defaults to `https://api.openai.com/v1/responses`.
- `--dump-dir <DIR>`: If set, writes one request JSON file and one response JSON file per accepted proxy call under this directory. Filenames use a shared sequence/timestamp prefix so each pair is easy to correlate.
- Authentication is fixed to `Authorization: Bearer <key>` to match the Codex CLI expectations.
For Azure, for example (ensure your deployment accepts `Authorization: Bearer <key>`):
+360
View File
@@ -0,0 +1,360 @@
use std::fs;
use std::io;
use std::io::Read;
use std::path::PathBuf;
use std::sync::atomic::AtomicU64;
use std::sync::atomic::Ordering;
use std::time::SystemTime;
use std::time::UNIX_EPOCH;
use reqwest::header::HeaderMap;
use serde::Serialize;
use serde_json::Value;
use tiny_http::Header;
use tiny_http::Method;
const AUTHORIZATION_HEADER_NAME: &str = "authorization";
const REDACTED_HEADER_VALUE: &str = "[REDACTED]";
pub(crate) struct ExchangeDumper {
dump_dir: PathBuf,
next_sequence: AtomicU64,
}
impl ExchangeDumper {
pub(crate) fn new(dump_dir: PathBuf) -> io::Result<Self> {
fs::create_dir_all(&dump_dir)?;
Ok(Self {
dump_dir,
next_sequence: AtomicU64::new(1),
})
}
pub(crate) fn dump_request(
&self,
method: &Method,
url: &str,
headers: &[Header],
body: &[u8],
) -> io::Result<ExchangeDump> {
let sequence = self.next_sequence.fetch_add(1, Ordering::Relaxed);
let timestamp_ms = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map_or(0, |duration| duration.as_millis());
let prefix = format!("{sequence:06}-{timestamp_ms}");
let request_path = self.dump_dir.join(format!("{prefix}-request.json"));
let response_path = self.dump_dir.join(format!("{prefix}-response.json"));
let request_dump = RequestDump {
method: method.as_str().to_string(),
url: url.to_string(),
headers: headers.iter().map(HeaderDump::from).collect(),
body: dump_body(body),
};
write_json_dump(&request_path, &request_dump)?;
Ok(ExchangeDump { response_path })
}
}
pub(crate) struct ExchangeDump {
response_path: PathBuf,
}
impl ExchangeDump {
pub(crate) fn tee_response_body<R: Read>(
self,
status: u16,
headers: &HeaderMap,
response_body: R,
) -> ResponseBodyDump<R> {
ResponseBodyDump {
response_body,
response_path: self.response_path,
status,
headers: headers.iter().map(HeaderDump::from).collect(),
body: Vec::new(),
dump_written: false,
}
}
}
pub(crate) struct ResponseBodyDump<R> {
response_body: R,
response_path: PathBuf,
status: u16,
headers: Vec<HeaderDump>,
body: Vec<u8>,
dump_written: bool,
}
impl<R> ResponseBodyDump<R> {
fn write_dump_if_needed(&mut self) {
if self.dump_written {
return;
}
self.dump_written = true;
let response_dump = ResponseDump {
status: self.status,
headers: std::mem::take(&mut self.headers),
body: dump_body(&self.body),
};
if let Err(err) = write_json_dump(&self.response_path, &response_dump) {
eprintln!(
"responses-api-proxy failed to write {}: {err}",
self.response_path.display()
);
}
}
}
impl<R: Read> Read for ResponseBodyDump<R> {
fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
let bytes_read = self.response_body.read(buf)?;
if bytes_read == 0 {
self.write_dump_if_needed();
return Ok(0);
}
self.body.extend_from_slice(&buf[..bytes_read]);
Ok(bytes_read)
}
}
impl<R> Drop for ResponseBodyDump<R> {
fn drop(&mut self) {
self.write_dump_if_needed();
}
}
#[derive(Serialize)]
struct RequestDump {
method: String,
url: String,
headers: Vec<HeaderDump>,
body: Value,
}
#[derive(Serialize)]
struct ResponseDump {
status: u16,
headers: Vec<HeaderDump>,
body: Value,
}
#[derive(Debug, Serialize)]
struct HeaderDump {
name: String,
value: String,
}
impl From<&Header> for HeaderDump {
fn from(header: &Header) -> Self {
let name = header.field.as_str().to_string();
let value = if should_redact_header(&name) {
REDACTED_HEADER_VALUE.to_string()
} else {
header.value.as_str().to_string()
};
Self { name, value }
}
}
impl From<(&reqwest::header::HeaderName, &reqwest::header::HeaderValue)> for HeaderDump {
fn from(header: (&reqwest::header::HeaderName, &reqwest::header::HeaderValue)) -> Self {
let name = header.0.as_str();
let value = if should_redact_header(name) {
REDACTED_HEADER_VALUE.to_string()
} else {
String::from_utf8_lossy(header.1.as_bytes()).into_owned()
};
Self {
name: name.to_string(),
value,
}
}
}
fn should_redact_header(name: &str) -> bool {
name.eq_ignore_ascii_case(AUTHORIZATION_HEADER_NAME)
|| name.to_ascii_lowercase().contains("cookie")
}
fn dump_body(body: &[u8]) -> Value {
serde_json::from_slice(body)
.unwrap_or_else(|_| Value::String(String::from_utf8_lossy(body).into_owned()))
}
fn write_json_dump(path: &PathBuf, dump: &impl Serialize) -> io::Result<()> {
let mut bytes = serde_json::to_vec_pretty(dump)
.map_err(|err| io::Error::new(io::ErrorKind::InvalidData, err))?;
bytes.push(b'\n');
fs::write(path, bytes)
}
#[cfg(test)]
mod tests {
use std::fs;
use std::io::Cursor;
use std::io::Read;
use std::sync::atomic::AtomicU64;
use std::sync::atomic::Ordering;
use pretty_assertions::assert_eq;
use reqwest::header::AUTHORIZATION;
use reqwest::header::CONTENT_TYPE;
use reqwest::header::HeaderMap;
use reqwest::header::HeaderValue;
use serde_json::json;
use tiny_http::Header;
use tiny_http::Method;
use super::ExchangeDumper;
static NEXT_TEST_DIR: AtomicU64 = AtomicU64::new(0);
#[test]
fn dump_request_writes_redacted_headers_and_json_body() {
let dump_dir = test_dump_dir();
let dumper = ExchangeDumper::new(dump_dir.clone()).expect("create dumper");
let headers = vec![
Header::from_bytes(&b"Authorization"[..], &b"Bearer secret"[..])
.expect("authorization header"),
Header::from_bytes(&b"Cookie"[..], &b"user-session=secret"[..]).expect("cookie header"),
Header::from_bytes(&b"Content-Type"[..], &b"application/json"[..])
.expect("content-type header"),
];
let exchange_dump = dumper
.dump_request(
&Method::Post,
"/v1/responses",
&headers,
br#"{"model":"gpt-5.4"}"#,
)
.expect("dump request");
let request_dump = fs::read_to_string(dump_file_with_suffix(&dump_dir, "-request.json"))
.expect("read request dump");
assert_eq!(
serde_json::from_str::<serde_json::Value>(&request_dump).expect("parse request dump"),
json!({
"method": "POST",
"url": "/v1/responses",
"headers": [
{
"name": "Authorization",
"value": "[REDACTED]"
},
{
"name": "Cookie",
"value": "[REDACTED]"
},
{
"name": "Content-Type",
"value": "application/json"
}
],
"body": {
"model": "gpt-5.4"
}
})
);
assert!(
exchange_dump
.response_path
.file_name()
.expect("response dump file name")
.to_string_lossy()
.ends_with("-response.json")
);
fs::remove_dir_all(dump_dir).expect("remove test dump dir");
}
#[test]
fn response_body_dump_streams_body_and_writes_response_file() {
let dump_dir = test_dump_dir();
let dumper = ExchangeDumper::new(dump_dir.clone()).expect("create dumper");
let exchange_dump = dumper
.dump_request(&Method::Post, "/v1/responses", &[], b"{}")
.expect("dump request");
let mut headers = HeaderMap::new();
headers.insert(CONTENT_TYPE, HeaderValue::from_static("text/event-stream"));
headers.insert(AUTHORIZATION, HeaderValue::from_static("Bearer secret"));
headers.insert(
"set-cookie",
HeaderValue::from_static("user-session=secret"),
);
let mut response_body = String::new();
exchange_dump
.tee_response_body(
/*status*/ 200,
&headers,
Cursor::new(b"data: hello\n\n".to_vec()),
)
.read_to_string(&mut response_body)
.expect("read response body");
let response_dump = fs::read_to_string(dump_file_with_suffix(&dump_dir, "-response.json"))
.expect("read response dump");
assert_eq!(response_body, "data: hello\n\n");
assert_eq!(
serde_json::from_str::<serde_json::Value>(&response_dump).expect("parse response dump"),
json!({
"status": 200,
"headers": [
{
"name": "content-type",
"value": "text/event-stream"
},
{
"name": "authorization",
"value": "[REDACTED]"
},
{
"name": "set-cookie",
"value": "[REDACTED]"
}
],
"body": "data: hello\n\n"
})
);
fs::remove_dir_all(dump_dir).expect("remove test dump dir");
}
fn test_dump_dir() -> std::path::PathBuf {
let test_id = NEXT_TEST_DIR.fetch_add(1, Ordering::Relaxed);
let dump_dir = std::env::temp_dir().join(format!(
"codex-responses-api-proxy-dump-test-{}-{test_id}",
std::process::id()
));
fs::create_dir_all(&dump_dir).expect("create test dump dir");
dump_dir
}
fn dump_file_with_suffix(dump_dir: &std::path::Path, suffix: &str) -> std::path::PathBuf {
let mut matches = fs::read_dir(dump_dir)
.expect("read dump dir")
.map(|entry| entry.expect("read dump entry").path())
.filter(|path| path.to_string_lossy().ends_with(suffix))
.collect::<Vec<_>>();
matches.sort();
assert_eq!(matches.len(), 1);
matches.pop().expect("single dump file")
}
}
+42 -4
View File
@@ -1,5 +1,6 @@
use std::fs::File;
use std::fs::{self};
use std::io::Read;
use std::io::Write;
use std::net::SocketAddr;
use std::net::TcpListener;
@@ -27,7 +28,9 @@ use tiny_http::Response;
use tiny_http::Server;
use tiny_http::StatusCode;
mod dump;
mod read_api_key;
use dump::ExchangeDumper;
use read_api_key::read_auth_header_from_stdin;
/// CLI arguments for the proxy.
@@ -49,6 +52,10 @@ pub struct Args {
/// Absolute URL the proxy should forward requests to (defaults to OpenAI).
#[arg(long, default_value = "https://api.openai.com/v1/responses")]
pub upstream_url: String,
/// Directory where request/response dumps should be written as JSON.
#[arg(long, value_name = "DIR")]
pub dump_dir: Option<PathBuf>,
}
#[derive(Serialize)]
@@ -79,6 +86,12 @@ pub fn run_main(args: Args) -> Result<()> {
upstream_url,
host_header,
});
let dump_dir = args
.dump_dir
.map(ExchangeDumper::new)
.transpose()
.context("creating --dump-dir")?
.map(Arc::new);
let (listener, bound_addr) = bind_listener(args.port)?;
if let Some(path) = args.server_info.as_ref() {
@@ -100,13 +113,20 @@ pub fn run_main(args: Args) -> Result<()> {
for request in server.incoming_requests() {
let client = client.clone();
let forward_config = forward_config.clone();
let dump_dir = dump_dir.clone();
std::thread::spawn(move || {
if http_shutdown && request.method() == &Method::Get && request.url() == "/shutdown" {
let _ = request.respond(Response::new_empty(StatusCode(200)));
std::process::exit(0);
}
if let Err(e) = forward_request(&client, auth_header, &forward_config, request) {
if let Err(e) = forward_request(
&client,
auth_header,
&forward_config,
dump_dir.as_deref(),
request,
) {
eprintln!("forwarding error: {e}");
}
});
@@ -144,6 +164,7 @@ fn forward_request(
client: &Client,
auth_header: &'static str,
config: &ForwardConfig,
dump_dir: Option<&ExchangeDumper>,
mut req: Request,
) -> Result<()> {
// Only allow POST /v1/responses exactly, no query string.
@@ -159,8 +180,18 @@ fn forward_request(
// Read request body
let mut body = Vec::new();
let mut reader = req.as_reader();
std::io::Read::read_to_end(&mut reader, &mut body)?;
let reader = req.as_reader();
reader.read_to_end(&mut body)?;
let exchange_dump = dump_dir.and_then(|dump_dir| {
dump_dir
.dump_request(&method, &url_path, req.headers(), &body)
.map_err(|err| {
eprintln!("responses-api-proxy failed to dump request: {err}");
err
})
.ok()
});
// Build headers for upstream, forwarding everything from the incoming
// request except Authorization (we replace it below).
@@ -224,10 +255,17 @@ fn forward_request(
}
});
let response_body: Box<dyn Read + Send> = if let Some(exchange_dump) = exchange_dump {
let headers = upstream_resp.headers().clone();
Box::new(exchange_dump.tee_response_body(status.as_u16(), &headers, upstream_resp))
} else {
Box::new(upstream_resp)
};
let response = Response::new(
StatusCode(status.as_u16()),
response_headers,
upstream_resp,
response_body,
content_length,
None,
);