mirror of
https://github.com/openai/codex.git
synced 2026-04-26 15:45:02 +00:00
## Summary
App-server v2 already receives turn-scoped `clientMetadata`, but the
Rust app-server was dropping it before the outbound Responses request.
This change keeps the fix lightweight by threading that metadata through
the existing turn-metadata path rather than inventing a new transport.
## What we're trying to do and why
We want turn-scoped metadata from the app-server protocol layer,
especially fields like Hermes/GAAS run IDs, to survive all the way to
the actual Responses API request so it is visible in downstream
websocket request logging and analytics.
The specific bug was:
- app-server protocol uses camelCase `clientMetadata`
- Responses transport already has an existing turn metadata carrier:
`x-codex-turn-metadata`
- websocket transport already rewrites that header into
`request.request_body.client_metadata["x-codex-turn-metadata"]`
- but the Rust app-server never parsed or stored `clientMetadata`, so
nothing from the app-server request was making it into that existing
path
This PR fixes that without adding a new header or a second metadata
channel.
## How we did it
### Protocol surface
- Add optional `clientMetadata` to v2 `TurnStartParams` and
`TurnSteerParams`
- Regenerate the JSON schema / TypeScript fixtures
- Update app-server docs to describe the field and its behavior
### Runtime plumbing
- Add a dedicated core op for app-server user input carrying turn-scoped
metadata: `Op::UserInputWithClientMetadata`
- Wire `turn/start` and `turn/steer` through that op / signature path
instead of dropping the metadata at the message-processor boundary
- Store the metadata in `TurnMetadataState`
### Transport behavior
- Reuse the existing serialized `x-codex-turn-metadata` payload
- Merge the new app-server `clientMetadata` into that JSON additively
- Do **not** replace built-in reserved fields already present in the
turn metadata payload
- Keep websocket behavior unchanged at the outer shape level: it still
sends only `client_metadata["x-codex-turn-metadata"]`, but that JSON
string now contains the merged fields
- Keep HTTP fallback behavior unchanged except that the existing
`x-codex-turn-metadata` header now includes the merged fields too
### Request shape before / after
Before, a websocket `response.create` looked like:
```json
{
"type": "response.create",
"client_metadata": {
"x-codex-turn-metadata": "{\"session_id\":\"...\",\"turn_id\":\"...\"}"
}
}
```
Even if the app-server caller supplied `clientMetadata`, it was not
represented there.
After, the same request shape is preserved, but the serialized payload
now includes the new turn-scoped fields:
```json
{
"type": "response.create",
"client_metadata": {
"x-codex-turn-metadata": "{\"session_id\":\"...\",\"turn_id\":\"...\",\"fiber_run_id\":\"fiber-start-123\",\"origin\":\"gaas\"}"
}
}
```
## Validation
### Targeted tests added / updated
- protocol round-trip coverage for `clientMetadata` on `turn/start` and
`turn/steer`
- protocol round-trip coverage for `Op::UserInputWithClientMetadata`
- `TurnMetadataState` merge test proving client metadata is added
without overwriting reserved built-in fields
- websocket request-shape test proving outbound `response.create`
contains merged metadata inside
`client_metadata["x-codex-turn-metadata"]`
- app-server integration tests proving:
- `turn/start` forwards `clientMetadata` into the outbound Responses
request path
- websocket warmup + real turn request both behave correctly
- `turn/steer` updates the follow-up request metadata
### Commands run
- `just write-app-server-schema`
- `cargo test -p codex-app-server-protocol`
- `cargo test -p codex-protocol`
- `cargo test -p codex-core
turn_metadata_state_merges_client_metadata_without_replacing_reserved_fields
--lib`
- `cargo test -p codex-core --test all
responses_websocket_preserves_custom_turn_metadata_fields`
- `cargo test -p codex-app-server --test all client_metadata`
- `cargo test -p codex-app-server --test all
turn_start_forwards_client_metadata_to_responses_websocket_request_body_v2
-- --nocapture`
- `just fmt`
- `just fix -p codex-core -p codex-protocol -p codex-app-server-protocol
-p codex-app-server`
- `just fix -p codex-exec -p codex-tui-app-server`
- `just argument-comment-lint`
### Full suite note
`cargo test` in `codex-rs` still fails in:
-
`suite::v2::turn_interrupt::turn_interrupt_resolves_pending_command_approval_request`
I verified that same failure on a clean detached `HEAD` worktree with an
isolated `CARGO_TARGET_DIR`, so it is not caused by this patch.
81 lines
2.7 KiB
Rust
81 lines
2.7 KiB
Rust
#![cfg(not(target_os = "windows"))]
|
||
|
||
use std::os::unix::fs::PermissionsExt;
|
||
|
||
use codex_protocol::protocol::EventMsg;
|
||
use codex_protocol::protocol::Op;
|
||
use codex_protocol::user_input::UserInput;
|
||
use core_test_support::fs_wait;
|
||
use core_test_support::responses;
|
||
use core_test_support::skip_if_no_network;
|
||
use core_test_support::test_codex::TestCodex;
|
||
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::json;
|
||
use tempfile::TempDir;
|
||
|
||
use responses::ev_assistant_message;
|
||
use responses::ev_completed;
|
||
use responses::sse;
|
||
use responses::start_mock_server;
|
||
use std::time::Duration;
|
||
|
||
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
|
||
async fn summarize_context_three_requests_and_instructions() -> anyhow::Result<()> {
|
||
skip_if_no_network!(Ok(()));
|
||
|
||
let server = start_mock_server().await;
|
||
|
||
let sse1 = sse(vec![ev_assistant_message("m1", "Done"), ev_completed("r1")]);
|
||
|
||
responses::mount_sse_once(&server, sse1).await;
|
||
|
||
let notify_dir = TempDir::new()?;
|
||
// write a script to the notify that touches a file next to it
|
||
let notify_script = notify_dir.path().join("notify.sh");
|
||
std::fs::write(
|
||
¬ify_script,
|
||
r#"#!/bin/bash
|
||
set -e
|
||
payload_path="$(dirname "${0}")/notify.txt"
|
||
tmp_path="${payload_path}.tmp"
|
||
echo -n "${@: -1}" > "${tmp_path}"
|
||
mv "${tmp_path}" "${payload_path}""#,
|
||
)?;
|
||
std::fs::set_permissions(¬ify_script, std::fs::Permissions::from_mode(0o755))?;
|
||
|
||
let notify_file = notify_dir.path().join("notify.txt");
|
||
let notify_script_str = notify_script.to_str().unwrap().to_string();
|
||
|
||
let TestCodex { codex, .. } = test_codex()
|
||
.with_config(move |cfg| cfg.notify = Some(vec![notify_script_str]))
|
||
.build(&server)
|
||
.await?;
|
||
|
||
// 1) Normal user input – should hit server once.
|
||
codex
|
||
.submit(Op::UserInput {
|
||
items: vec![UserInput::Text {
|
||
text: "hello world".into(),
|
||
text_elements: Vec::new(),
|
||
}],
|
||
final_output_json_schema: None,
|
||
responsesapi_client_metadata: None,
|
||
})
|
||
.await?;
|
||
wait_for_event(&codex, |ev| matches!(ev, EventMsg::TurnComplete(_))).await;
|
||
|
||
// We fork the notify script, so we need to wait for it to write to the file.
|
||
fs_wait::wait_for_path_exists(¬ify_file, Duration::from_secs(5)).await?;
|
||
let notify_payload_raw = tokio::fs::read_to_string(¬ify_file).await?;
|
||
let payload: Value = serde_json::from_str(¬ify_payload_raw)?;
|
||
|
||
assert_eq!(payload["type"], json!("agent-turn-complete"));
|
||
assert_eq!(payload["input-messages"], json!(["hello world"]));
|
||
assert_eq!(payload["last-assistant-message"], json!("Done"));
|
||
|
||
Ok(())
|
||
}
|