Standardize model-visible fragments

Fold Apps, Skills, and Plugins into the model-visible fragment registry as ordered developer-envelope fragments, keep the turn-state/contextual-user framework intact, and refresh prompt layout snapshots/docs around the new shape.

Co-authored-by: Codex <noreply@openai.com>

Author: charley-oai

AGENTS.md

@@ -36,6 +36,23 @@ In the codex-rs folder where the rust code lives:
   - When extracting code from a large module, move the related tests and module/type docs toward
     the new implementation so the invariants stay close to the code that owns them.
 
+### Model-visible context fragments
+
+- Model-visible prompt context should go through the shared fragment abstractions described in `docs/model-visible-context.md`.
+- Every named fragment type should implement `ModelVisibleContextFragment` and set `type Role`.
+- Turn-state model-visible context assembly should produce exactly two envelopes (one developer message + one contextual-user message) via the shared envelope builders.
+- Define and register current fragment types in `codex-rs/core/src/model_visible_fragments.rs`. `REGISTERED_MODEL_VISIBLE_FRAGMENTS` is the integration point for contextual-user detection and registry-driven turn-state assembly.
+- If a fragment represents durable turn/session state that should be rebuilt correctly across resume/fork/compaction/backtracking, implement `ModelVisibleContextFragment::build(...)`.
+- If a fragment is contextual-user, it must provide stable detection: prefer `contextual_user_markers()` when fixed markers are sufficient, and override `matches_contextual_user_text()` only for genuinely custom matching (for example AGENTS.md).
+- Use the developer envelope for developer guidance. Custom override text (for example config/app-server `developer_instructions`) should use `CustomDeveloperInstructions`; system-generated developer context should use typed fragments plus the neutral `developer_*_text` helpers rather than reusing the custom override type.
+- Use contextual-user fragments for contextual user-role state. Turn-state contextual-user fragments such as custom user instructions, AGENTS instructions, JS REPL guidance, child-agent guidance, and environment context belong in the contextual-user envelope. Runtime contextual-user fragments should still use typed fragments so history parsing treats them as contextual state rather than user intent; examples include skills triggered at runtime, shell-command records, and turn-aborted notices.
+- Use `<environment_context>` specifically for environment facts derived from `TurnContext` that may need turn-to-turn diffs (`cwd`, `shell`, optional `current_date`, optional `timezone`, optional network allow/deny domain summaries). Do not put policy text, plugin/skill listings, or other guidance into `<environment_context>`; those should use dedicated fragments.
+- Runtime/session-prefix fragments that are not turn-state diffs should usually leave `ModelVisibleContextFragment::build(...)` as `None`.
+- Register every current fragment exactly once in `REGISTERED_MODEL_VISIBLE_FRAGMENTS`, in the rough order it should appear in model-visible context.
+- Prefer dedicated typed fragments over plain strings. Developer-only one-off text is acceptable only when it is truly isolated, does not need contextual-user detection, and does not participate in turn-state diff reconstruction.
+- Do not hand-construct model-visible `ResponseItem::Message` payloads in new turn-state code; use fragment conversion and the shared envelope builders.
+- Do not inject raw strings directly into the initial-context or settings-update builders, and do not call fragment wrapping helpers ad hoc from new code.
+
 Run `just fmt` (in `codex-rs` directory) automatically after you have finished making Rust code changes; do not ask for approval to run it. Additionally, run the tests:
 
 1. Run the test for the specific project that was changed. For example, if changes were made in `codex-rs/tui`, run `cargo test -p codex-tui`.

codex-rs/app-server-protocol/schema/json/ClientRequest.json

@@ -2547,6 +2547,7 @@
           ]
         },
         "developerInstructions": {
+          "description": "Custom developer override for this thread session. Takes precedence over `~/.codex/config.toml` `developer_instructions`.",
           "type": [
             "string",
             "null"
@@ -2795,7 +2796,7 @@
       "type": "object"
     },
     "ThreadResumeParams": {
-      "description": "There are three ways to resume a thread: 1. By thread_id: load the thread from disk by thread_id and resume it. 2. By history: instantiate the thread from memory and resume it. 3. By path: load the thread from disk by path and resume it.\n\nThe precedence is: history > path > thread_id. If using history or path, the thread_id param will be ignored.\n\nPrefer using thread_id whenever possible.",
+      "description": "There are three ways to resume a thread: 1. By thread_id: load the thread from disk by thread_id and resume it. 2. By history: instantiate the thread from memory and resume it. 3. By path: load the thread from disk by path and resume it.\n\nThe precedence is: history > path > thread_id. If using history or path, the thread_id param will be ignored.\n\nPrefer using thread_id whenever possible.\n\nWhen resuming a thread that is already loaded/running, override fields are ignored and reported as mismatch warnings rather than being reapplied mid-session.",
       "properties": {
         "approvalPolicy": {
           "anyOf": [
@@ -2838,6 +2839,7 @@
           ]
         },
         "developerInstructions": {
+          "description": "Custom developer override for this thread session. Takes precedence over `~/.codex/config.toml` `developer_instructions`.",
           "type": [
             "string",
             "null"
@@ -3000,6 +3002,7 @@
           ]
         },
         "developerInstructions": {
+          "description": "Custom developer override for this thread session. Takes precedence over `~/.codex/config.toml` `developer_instructions`.",
           "type": [
             "string",
             "null"

codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json

@@ -11863,6 +11863,7 @@
             ]
           },
           "developerInstructions": {
+            "description": "Custom developer override for this thread session. Takes precedence over `~/.codex/config.toml` `developer_instructions`.",
             "type": [
               "string",
               "null"
@@ -12958,7 +12959,7 @@
       },
       "ThreadResumeParams": {
         "$schema": "http://json-schema.org/draft-07/schema#",
-        "description": "There are three ways to resume a thread: 1. By thread_id: load the thread from disk by thread_id and resume it. 2. By history: instantiate the thread from memory and resume it. 3. By path: load the thread from disk by path and resume it.\n\nThe precedence is: history > path > thread_id. If using history or path, the thread_id param will be ignored.\n\nPrefer using thread_id whenever possible.",
+        "description": "There are three ways to resume a thread: 1. By thread_id: load the thread from disk by thread_id and resume it. 2. By history: instantiate the thread from memory and resume it. 3. By path: load the thread from disk by path and resume it.\n\nThe precedence is: history > path > thread_id. If using history or path, the thread_id param will be ignored.\n\nPrefer using thread_id whenever possible.\n\nWhen resuming a thread that is already loaded/running, override fields are ignored and reported as mismatch warnings rather than being reapplied mid-session.",
         "properties": {
           "approvalPolicy": {
             "anyOf": [
@@ -13001,6 +13002,7 @@
             ]
           },
           "developerInstructions": {
+            "description": "Custom developer override for this thread session. Takes precedence over `~/.codex/config.toml` `developer_instructions`.",
             "type": [
               "string",
               "null"
@@ -13254,6 +13256,7 @@
             ]
           },
           "developerInstructions": {
+            "description": "Custom developer override for this thread session. Takes precedence over `~/.codex/config.toml` `developer_instructions`.",
             "type": [
               "string",
               "null"

codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json

@@ -9580,6 +9580,7 @@
           ]
         },
         "developerInstructions": {
+          "description": "Custom developer override for this thread session. Takes precedence over `~/.codex/config.toml` `developer_instructions`.",
           "type": [
             "string",
             "null"
@@ -10675,7 +10676,7 @@
     },
     "ThreadResumeParams": {
       "$schema": "http://json-schema.org/draft-07/schema#",
-      "description": "There are three ways to resume a thread: 1. By thread_id: load the thread from disk by thread_id and resume it. 2. By history: instantiate the thread from memory and resume it. 3. By path: load the thread from disk by path and resume it.\n\nThe precedence is: history > path > thread_id. If using history or path, the thread_id param will be ignored.\n\nPrefer using thread_id whenever possible.",
+      "description": "There are three ways to resume a thread: 1. By thread_id: load the thread from disk by thread_id and resume it. 2. By history: instantiate the thread from memory and resume it. 3. By path: load the thread from disk by path and resume it.\n\nThe precedence is: history > path > thread_id. If using history or path, the thread_id param will be ignored.\n\nPrefer using thread_id whenever possible.\n\nWhen resuming a thread that is already loaded/running, override fields are ignored and reported as mismatch warnings rather than being reapplied mid-session.",
       "properties": {
         "approvalPolicy": {
           "anyOf": [
@@ -10718,6 +10719,7 @@
           ]
         },
         "developerInstructions": {
+          "description": "Custom developer override for this thread session. Takes precedence over `~/.codex/config.toml` `developer_instructions`.",
           "type": [
             "string",
             "null"
@@ -10971,6 +10973,7 @@
           ]
         },
         "developerInstructions": {
+          "description": "Custom developer override for this thread session. Takes precedence over `~/.codex/config.toml` `developer_instructions`.",
           "type": [
             "string",
             "null"

codex-rs/app-server-protocol/schema/json/v2/ThreadForkParams.json

@@ -118,6 +118,7 @@
       ]
     },
     "developerInstructions": {
+      "description": "Custom developer override for this thread session. Takes precedence over `~/.codex/config.toml` `developer_instructions`.",
       "type": [
         "string",
         "null"

codex-rs/app-server-protocol/schema/json/v2/ThreadResumeParams.json

@@ -998,7 +998,7 @@
       "type": "string"
     }
   },
-  "description": "There are three ways to resume a thread: 1. By thread_id: load the thread from disk by thread_id and resume it. 2. By history: instantiate the thread from memory and resume it. 3. By path: load the thread from disk by path and resume it.\n\nThe precedence is: history > path > thread_id. If using history or path, the thread_id param will be ignored.\n\nPrefer using thread_id whenever possible.",
+  "description": "There are three ways to resume a thread: 1. By thread_id: load the thread from disk by thread_id and resume it. 2. By history: instantiate the thread from memory and resume it. 3. By path: load the thread from disk by path and resume it.\n\nThe precedence is: history > path > thread_id. If using history or path, the thread_id param will be ignored.\n\nPrefer using thread_id whenever possible.\n\nWhen resuming a thread that is already loaded/running, override fields are ignored and reported as mismatch warnings rather than being reapplied mid-session.",
   "properties": {
     "approvalPolicy": {
       "anyOf": [
@@ -1041,6 +1041,7 @@
       ]
     },
     "developerInstructions": {
+      "description": "Custom developer override for this thread session. Takes precedence over `~/.codex/config.toml` `developer_instructions`.",
       "type": [
         "string",
         "null"

codex-rs/app-server-protocol/schema/json/v2/ThreadStartParams.json

@@ -142,6 +142,7 @@
       ]
     },
     "developerInstructions": {
+      "description": "Custom developer override for this thread session. Takes precedence over `~/.codex/config.toml` `developer_instructions`.",
       "type": [
         "string",
         "null"

codex-rs/app-server-protocol/schema/typescript/v2/ThreadForkParams.ts

@@ -27,7 +27,11 @@ model?: string | null, modelProvider?: string | null, serviceTier?: ServiceTier
  * Override where approval requests are routed for review on this thread
  * and subsequent turns.
  */
-approvalsReviewer?: ApprovalsReviewer | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null, developerInstructions?: string | null, ephemeral?: boolean, /**
+approvalsReviewer?: ApprovalsReviewer | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null, /**
+ * Custom developer override for this thread session.
+ * Takes precedence over `~/.codex/config.toml` `developer_instructions`.
+ */
+developerInstructions?: string | null, ephemeral?: boolean, /**
  * If true, persist additional rollout EventMsg variants required to
  * reconstruct a richer thread history on subsequent resume/fork/read.
  */

codex-rs/app-server-protocol/schema/typescript/v2/ThreadResumeParams.ts

@@ -19,6 +19,10 @@ import type { SandboxMode } from "./SandboxMode";
  * If using history or path, the thread_id param will be ignored.
  *
  * Prefer using thread_id whenever possible.
+ *
+ * When resuming a thread that is already loaded/running, override fields are
+ * ignored and reported as mismatch warnings rather than being reapplied
+ * mid-session.
  */
 export type ThreadResumeParams = {threadId: string, /**
  * [UNSTABLE] FOR CODEX CLOUD - DO NOT USE.
@@ -36,7 +40,11 @@ model?: string | null, modelProvider?: string | null, serviceTier?: ServiceTier
  * Override where approval requests are routed for review on this thread
  * and subsequent turns.
  */
-approvalsReviewer?: ApprovalsReviewer | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null, developerInstructions?: string | null, personality?: Personality | null, /**
+approvalsReviewer?: ApprovalsReviewer | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, baseInstructions?: string | null, /**
+ * Custom developer override for this thread session.
+ * Takes precedence over `~/.codex/config.toml` `developer_instructions`.
+ */
+developerInstructions?: string | null, personality?: Personality | null, /**
  * If true, persist additional rollout EventMsg variants required to
  * reconstruct a richer thread history on subsequent resume/fork/read.
  */

codex-rs/app-server-protocol/schema/typescript/v2/ThreadStartParams.ts

@@ -12,7 +12,11 @@ export type ThreadStartParams = {model?: string | null, modelProvider?: string |
  * Override where approval requests are routed for review on this thread
  * and subsequent turns.
  */
-approvalsReviewer?: ApprovalsReviewer | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, serviceName?: string | null, baseInstructions?: string | null, developerInstructions?: string | null, personality?: Personality | null, ephemeral?: boolean | null, /**
+approvalsReviewer?: ApprovalsReviewer | null, sandbox?: SandboxMode | null, config?: { [key in string]?: JsonValue } | null, serviceName?: string | null, baseInstructions?: string | null, /**
+ * Custom developer override for this thread session.
+ * Takes precedence over `~/.codex/config.toml` `developer_instructions`.
+ */
+developerInstructions?: string | null, personality?: Personality | null, ephemeral?: boolean | null, /**
  * If true, opt into emitting raw Responses API items on the event stream.
  * This is for internal use only (e.g. Codex Cloud).
  */