diff --git a/crates/switchyard-translation/src/codecs/openai_chat/buffered.rs b/crates/switchyard-translation/src/codecs/openai_chat/buffered.rs
index 923bb2578b..f3a816cca0 100644
--- a/crates/switchyard-translation/src/codecs/openai_chat/buffered.rs
+++ b/crates/switchyard-translation/src/codecs/openai_chat/buffered.rs
@@ -150,15 +150,14 @@ impl FormatCodec for OpenAiChatCodec {
));
continue;
}
- match role {
- Role::System | Role::Developer => {
- request
- .instructions
- .push(InstructionBlock { role, content });
- }
- Role::User | Role::Assistant | Role::Tool => {
- request.messages.push(Message::new(role, content));
- }
+ // Leading system and developer messages are top-level instructions.
+ // Later ones stay in place as messages.
+ if matches!(role, Role::System | Role::Developer) && request.messages.is_empty() {
+ request
+ .instructions
+ .push(InstructionBlock { role, content });
+ } else {
+ request.messages.push(Message::new(role, content));
}
}
}
diff --git a/crates/switchyard-translation/tests/request_translation.rs b/crates/switchyard-translation/tests/request_translation.rs
index d1a4654cef..28fddaddbd 100644
--- a/crates/switchyard-translation/tests/request_translation.rs
+++ b/crates/switchyard-translation/tests/request_translation.rs
@@ -2196,6 +2196,81 @@ fn responses_rebuild_preserves_inline_instructions() -> TestResult {
Ok(())
}
+#[test]
+fn chat_rebuild_preserves_inline_instructions() -> TestResult {
+ let engine = TranslationEngine::default();
+ let policy = TranslationPolicy::default();
+ let body = json!({
+ "model": "gpt-4",
+ "messages": [
+ {"role": "system", "content": "Initial system."},
+ {"role": "developer", "content": "Initial developer."},
+ {"role": "user", "content": "Hello."},
+ {"role": "system", "content": "Later system."},
+ {"role": "developer", "content": "Later developer."},
+ {"role": "developer", "content": "Separate message."},
+ {"role": "user", "content": "Original suffix."}
+ ]
+ });
+ let mut request = engine
+ .decode_request(WireFormat::OpenAiChat, &body, &policy)?
+ .request;
+ request.preservation.requests.clear();
+
+ // Leading instructions stay top-level. Later ones stay in place.
+ assert_eq!(request.instructions.len(), 2);
+ assert_eq!(request.messages[1].role, Role::System);
+ assert_eq!(request.messages[2].role, Role::Developer);
+
+ assert_eq!(
+ engine
+ .encode_request(WireFormat::OpenAiChat, &request, &policy)?
+ .body,
+ body
+ );
+
+ let responses = engine
+ .encode_request(WireFormat::OpenAiResponses, &request, &policy)?
+ .body;
+ assert_eq!(
+ responses,
+ json!({
+ "model": "gpt-4",
+ "instructions": "Initial system.\n\nInitial developer.",
+ "input": [
+ {"type": "message", "role": "user", "content": "Hello."},
+ {"type": "message", "role": "system", "content": "Later system."},
+ {"type": "message", "role": "developer", "content": "Later developer."},
+ {"type": "message", "role": "developer", "content": "Separate message."},
+ {"type": "message", "role": "user", "content": "Original suffix."}
+ ]
+ })
+ );
+
+ let anthropic = engine
+ .encode_request(WireFormat::AnthropicMessages, &request, &policy)?
+ .body;
+ assert_eq!(
+ anthropic["system"],
+ "Initial system.\n\nInitial developer.\n\nLater system.\n\nLater developer.\n\nSeparate message."
+ );
+ assert_eq!(anthropic["messages"].as_array().map(Vec::len), Some(2));
+
+ // A suffix-only edit leaves earlier messages unchanged.
+ request.messages.last_mut().ok_or("missing suffix")?.content = vec![ContentBlock::Text {
+ text: "Edited suffix.".into(),
+ }];
+ let mut expected = body.clone();
+ expected["messages"][6]["content"] = json!("Edited suffix.");
+ assert_eq!(
+ engine
+ .encode_request(WireFormat::OpenAiChat, &request, &policy)?
+ .body,
+ expected
+ );
+ Ok(())
+}
+
// Anthropic `system` is text only, so non-text instruction content is lossy.
#[test]
fn anthropic_reports_dropped_instruction_content() -> TestResult {
diff --git a/docs/reference/protocols/llm_requests.md b/docs/reference/protocols/llm_requests.md
index f2432d5d44..685605b2d0 100644
--- a/docs/reference/protocols/llm_requests.md
+++ b/docs/reference/protocols/llm_requests.md
@@ -27,8 +27,8 @@ the destination model. Select a Rust field or type for its full crate definition
| Protocol field and type | Meaning | Anthropic Messages | OpenAI Responses | Chat Completions |
|---|---|---|---|---|
| LlmRequest.model: Option<String> | Addressed model; the host can replace it with the selected target. | `model` | `model` | `model` |
-| LlmRequest.instructions: Vec<InstructionBlock> | Top-level system and developer instructions. | Top-level `system`; no distinct developer authority | `instructions` | System/developer messages in `messages` |
-| LlmRequest.messages: Vec<Message> | Ordered turns, each with a role and content blocks. | `messages[]`; inline system/developer messages are added to top-level `system` on encode | Messages, including system/developer messages, and tool items in `input` | `messages[]` |
+| LlmRequest.instructions: Vec<InstructionBlock> | Top-level system and developer instructions. | Top-level `system`; no distinct developer authority | `instructions` | Leading system/developer messages in `messages` |
+| LlmRequest.messages: Vec<Message> | Ordered turns, each with a role and content blocks. | `messages[]`; inline system/developer messages are added to top-level `system` on encode | Messages, including system/developer messages, and tool items in `input` | `messages[]`, including later system/developer messages |
| LlmRequest.tools: Vec<Tool> | Available functions, MCP toolsets, or retained provider definitions. | `tools[]` | `tools[]` | `tools[]`; function definitions are nested in `function` |
| LlmRequest.tool_choice: Option<ToolChoice> | Let the model choose, require a call, forbid calls, or select a named tool. | `auto`, `any`, `none`, or `tool` | `auto`, `required`, `none`, or `function` | `auto`, `required`, `none`, or `function` |
| LlmRequest.stream: bool | Request incremental output. | `stream` | `stream` | `stream` |
diff --git a/examples/dynamo-preproc/src/request.rs b/examples/dynamo-preproc/src/request.rs
index f8b5916173..6a69109fc2 100644
--- a/examples/dynamo-preproc/src/request.rs
+++ b/examples/dynamo-preproc/src/request.rs
@@ -109,7 +109,8 @@ mod tests {
headers.insert("x-switchyard-session-id", "session-1".parse().unwrap());
let request = decode(&raw, &headers).unwrap();
let ir = request.llm_request;
- assert_eq!(ir.instructions.len(), 2);
+ assert_eq!(ir.instructions.len(), 1);
+ assert_eq!(ir.messages[2].role, switchyard_protocol::Role::Developer);
assert_eq!(ir.sampling.temperature, Some(0.2));
assert_eq!(ir.output.max_output_tokens, Some(64));
assert_eq!(ir.tool_choice, Some(ToolChoice::Required));
@@ -121,7 +122,7 @@ mod tests {
panic!("missing tool call")
};
assert_eq!(call.arguments, json!({"command": "pytest"}));
- for (index, flag) in [(1, true), (2, false)] {
+ for (index, flag) in [(1, true), (3, false)] {
let ContentBlock::ToolResult(result) = &ir.messages[index].content[0] else {
panic!("missing tool result")
};