CH 03 · Building the Prompt · 07/12
Read as one pageReal code: the environment is resent only when it changes
The PromptBuilder you just built puts a fresh environment string at the front of input on every call, and that string only knows the working directory and the shell. Codex writes an <environment_context> user message into the conversation. The first turn injects the full context. A later turn adds another message only when a value changed.
let turn_context_values_changed = current.shell_version != previous.shell_version
|| current.current_date != previous.current_date
|| current.timezone != previous.timezone
|| current.network != previous.network
|| current.filesystem != previous.filesystem;
// ... (which environments were added, removed, or edited)
let fragment = (!updates.is_empty() || turn_context_values_changed).then(|| {
Box::new(RenderedEnvironments {
// ... (the changed environments, plus network and filesystem)
}) as Box<dyn ContextualUserFragment>
});
(
Some(current),
WorldStateUpdate::optional_boxed_fragment(fragment), // [1]
)
Source: openai/codex, codex-rs/core/src/context/world_state/environment.rs (Apache-2.0)
When a message is sent, the directory and the shell are written as XML, with the characters escaped.
fn push_environment_values(rendered: &mut String, environment: &EnvironmentState, indent: &str) {
rendered.push_str(indent);
rendered.push_str("<cwd>");
push_xml_escaped_text(rendered, &environment.cwd.inferred_native_path_string()); // [2]
rendered.push_str("</cwd>\n");
if environment.status == EnvironmentStatus::Starting {
rendered.push_str(indent);
rendered.push_str("<status>starting</status>\n");
}
if environment.status == EnvironmentStatus::Failed { // [3]
rendered.push_str(indent);
rendered.push_str("<status>failed</status>\n");
}
if let Some(error) = &environment.error {
rendered.push_str(indent);
rendered.push_str("<error>");
push_xml_escaped_text(rendered, error);
rendered.push_str("</error>\n");
}
if let Some(shell) = &environment.shell {
rendered.push_str(indent);
rendered.push_str("<shell>");
push_xml_escaped_text(rendered, shell);
rendered.push_str("</shell>\n");
}
}
Source: openai/codex, codex-rs/core/src/context/world_state/environment.rs (Apache-2.0)
What to notice
- [1]
optional_boxed_fragmentturns a missing fragment into no update at all. If no environment was added, removed, or edited, and the shell version, date, timezone, network rules, and filesystem rules are the same, this section adds nothing. The old message stays where it was.record_context_updates_and_set_reference_context_itemrecords new items onto the conversation only when that list is non-empty. ThePromptBuilderyou just built rebuilds the environment string at the front ofinputon every call. Change the directory and those bytes move, so the prefix the cache depends on changes with them. - [2]
<cwd>is the working directory in the platform's path spelling, passed throughpush_xml_escaped_text(&,<,>, quotes). A folder nameda<bcannot close the tag early. The f-string in yourPromptBuilderpastes the raw characters. - [3] The same block can say the environment is still starting or has failed, and it can include a short
<error>. The shell line is the shell's name, such aszsh, not a full path. Network allow and deny lists, and the filesystem permission profile, are copied onto this same update and rendered as their own tags. Your builder has nowhere to put any of that.
The whole message is role user, between <environment_context> and </environment_context>. One available environment is written as bare <cwd> and <shell>. Two or more environments are wrapped in <environment id="...">. The first ready environment for the turn is marked primary="true". A failed environment is stored with is_primary false, so that attribute is primary="false" when the wrapper includes one.
Read it yourself: In environment.rs, search for push_optional_element and list the extra tags (shell_version, current_date, timezone). Then open session/mod.rs at emits only context diffs. A later turn should add a message only for what changed, leaving the earlier items in place.
Finished this idea?
Your learning progress stays in this browser.