crate 治理，一条不许往核心加代码的禁令

1[workspace]2members = [3    "aws-auth",4    "analytics",5    "agent-graph-store",6    "agent-identity",7    "backend-client",8    "bwrap",9    "build-info",10    "ansi-escape",11    "async-utils",12    "app-server",13    "app-server-transport",14    "app-server-daemon",15    "app-server-client",16    "app-server-protocol",17    "app-server-protocol-noop-macros",18    "app-server-test-client",19    "apply-patch",20    "arg0",

130    "terminal-detection",131    "test-binary-support",132    "thread-manager-sample",133    "thread-store",134    "uds",135    "codex-experimental-api-macros",136    "plugin",137    "model-provider",138]139resolver = "2"

1# Rust/codex-rs23In the codex-rs folder where the rust code lives:45- Crate names are prefixed with `codex-`. For example, the `core` folder's crate is named `codex-core`

1[package]2edition.workspace = true3license.workspace = true4name = "codex-core"5version.workspace = true67[lib]8name = "codex_core"9path = "src/lib.rs"

141[workspace.package]142version = "0.0.0"143# Track the edition for all workspace crates in one place. Individual144# crates can still override this value, but keeping it here means new145# crates created with `cargo new -w ...` automatically inherit the 2024146# edition.147edition = "2024"148license = "Apache-2.0"

1//! Root of the `codex-core` library.23// Prevent accidental direct writes to stdout/stderr in library code. All4// user-visible output must go through the appropriate abstraction (e.g.,5// the TUI or the tracing stack).6#![deny(clippy::print_stdout, clippy::print_stderr)]78mod apply_patch;9mod apps;10mod client;

41codex-core = { workspace = true }42codex-core-plugins = { workspace = true }

16codex-app-server = { workspace = true }17codex-app-server-protocol = { workspace = true }18codex-arg0 = { workspace = true }19codex-config = { workspace = true }20codex-core = { workspace = true }21codex-exec-server = { workspace = true }

30codex-app-server-client = { workspace = true }31codex-app-server-protocol = { workspace = true }

26codex-analytics = { workspace = true }27codex-agent-graph-store = { workspace = true }28codex-api = { workspace = true }29codex-app-server-protocol = { workspace = true }30codex-apply-patch = { workspace = true }31codex-async-utils = { workspace = true }32codex-client = { workspace = true }33codex-code-mode = { workspace = true }34codex-connectors = { workspace = true }35codex-context-fragments = { workspace = true }36codex-config = { workspace = true }37codex-core-plugins = { workspace = true }38codex-diagnostics = { workspace = true }39codex-exec-server = { workspace = true }40codex-extension-api = { workspace = true }41codex-extension-items = { workspace = true }42codex-features = { workspace = true }

72## The `codex-core` crate7374Over time, the `codex-core` crate (defined in `codex-rs/core/`) has become bloated because it is the largest crate, so it is often easier to add something new to `codex-core` rather than refactor out the library code you need so your new code neither takes a dependency on, nor contributes to the size of, `codex-core`.7576To that end: **resist adding code to codex-core**!7778Particularly when introducing a new concept/feature/API, before adding to `codex-core`, consider whether:7980- There is an existing crate other than `codex-core` that is an appropriate place for your new code to live.81- It is time to introduce a new crate to the Cargo workspace for your new functionality. Refactor existing code as necessary to make this happen.8283Likewise, when reviewing code, do not hesitate to push back on PRs that would unnecessarily add code to `codex-core`.

1[package]2edition.workspace = true3license.workspace = true4name = "codex-context-fragments"5version.workspace = true67[lib]8name = "codex_context_fragments"9path = "src/lib.rs"

1mod additional_context;2mod fragment;34pub use additional_context::AdditionalContextDeveloperFragment;5pub use additional_context::AdditionalContextUserFragment;6pub use fragment::ContextualUserFragment;

1[package]2edition.workspace = true3license.workspace = true4name = "codex-features"5version.workspace = true67[lib]8doctest = false9name = "codex_features"10path = "src/lib.rs"

41/// High-level lifecycle stage for a feature.42#[derive(Debug, Clone, Copy, PartialEq, Eq)]43pub enum Stage {44    /// Features that are still under development, not ready for external use45    UnderDevelopment,46    /// Experimental features made available to users through the `/experimental` menu47    Experimental {48        name: &'static str,49        menu_description: &'static str,50        announcement: &'static str,51    },52    /// Stable features. The feature flag is kept for ad-hoc enabling/disabling53    Stable,54    /// Deprecated feature that should not be used anymore.55    Deprecated,56    /// The feature flag is useless but kept for backward compatibility reason.57    Removed,58}

60impl Stage {61    pub fn experimental_menu_name(self) -> Option<&'static str> {62        match self {63            Stage::Experimental { name, .. } => Some(name),64            Stage::UnderDevelopment | Stage::Stable | Stage::Deprecated | Stage::Removed => None,65        }66    }

1//! Public facade for thread management APIs built on `codex-core`.

85## Code Review Rules8687### Crate API surface8889Keep crate API surfaces as small as possible. Avoid proliferating test-only helpers.

49- Avoid large modules:50  - Prefer adding new modules instead of growing existing ones.51  - Target Rust modules under 500 LoC, excluding tests.52  - If a file exceeds roughly 800 LoC, add new functionality in a new module instead of extending53    the existing file unless there is a strong documented reason not to.54  - This rule applies especially to high-touch files that already attract unrelated changes, such55    as `codex-rs/tui/src/app.rs`, `codex-rs/tui/src/bottom_pane/chat_composer.rs`,56    `codex-rs/tui/src/bottom_pane/footer.rs`, `codex-rs/tui/src/chatwidget.rs`,57    `codex-rs/tui/src/bottom_pane/mod.rs`, and similarly central orchestration modules.58  - When extracting code from a large module, move the related tests and module/type docs toward59    the new implementation so the invariants stay close to the code that owns them.60  - Avoid adding new standalone methods to `codex-rs/tui/src/chatwidget.rs` unless the change is61    trivial; prefer new modules/files and keep `chatwidget.rs` focused on orchestration.

1//! Top-level TUI application state and runtime wiring.2//!3//! This module owns the `App` struct, shared imports, and the high-level run loop that coordinates4//! the focused app submodules.

1//! The main Codex TUI chat surface.2//!3//! `ChatWidget` consumes protocol events, builds and updates history cells, and drives rendering4//! for both the main viewport and overlay UIs.

1//! The chat composer is the bottom-pane text input state machine.2//!3//! It is responsible for:4//!5//! - Editing the input buffer (a [`TextArea`]), including placeholder "elements" for attachments.6//! - Routing keys to the active popup (slash commands, file search, skill/apps mentions).7//! - Promoting typed slash commands into atomic elements when the command name is completed.8//! - Handling submit vs newline on Enter.9//! - Turning raw key streams into explicit paste operations on platforms where terminals10//!   don't provide reliable bracketed paste (notably Windows).

4925#[cfg(test)]4926#[path = "chat_composer_effort_tests.rs"]4927mod effort_tests;49284929#[cfg(test)]4930mod tests {

125### Change size guidance (800 lines)126127Unless the change is mechanical the total number of changed lines should not exceed 800 lines.128For complex logic changes the size should be under 500 lines.129130If the change is larger, explore whether it can be split into reviewable stages and identify the smallest coherent stage to land first.131Base the staging suggestion on the actual diff, dependencies, and affected call sites.

37- If you change Rust dependencies (`Cargo.toml` or `Cargo.lock`), run `just bazel-lock-update` from the38  repo root to refresh `MODULE.bazel.lock`, and include that lockfile update in the same change. CI39  verifies lockfile drift.40- Bazel does not automatically make source-tree files available to compile-time Rust file access. If41  you add `include_str!`, `include_bytes!`, `sqlx::migrate!`, or similar build-time file or42  directory reads, update the crate's `BUILD.bazel` (`compile_data`, `build_script_data`, or test43  data) or Bazel may fail even when Cargo passes.

143[no-cd]144bazel-lock-update:145    bazel mod deps --lockfile_mode=update146147[no-cd]148[unix]149bazel-lock-check:150    {{ justfile_directory() }}/scripts/check-module-bazel-lock.sh151152[windows]153bazel-lock-check:154    bazel mod deps --lockfile_mode=error; if ($LASTEXITCODE -ne 0) { Write-Error "MODULE.bazel.lock is out of date. Run 'just bazel-lock-update' and commit the updated lockfile."; exit 1 }

1#!/usr/bin/env bash2set -euo pipefail34repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"5if ! "${repo_root}/.github/scripts/run_bazel_with_buildbuddy.py" mod deps --lockfile_mode=error; then6  echo "MODULE.bazel.lock is out of date."7  echo "Run 'just bazel-lock-update' and commit the updated lockfile."8  exit 19fi

1{2  "lockFileVersion": 26,3  "registryFileHashes": {

23const RAW_TOOLTIPS: &str = include_str!("../tooltips.txt");

3codex_rust_crate(4    name = "tui",5    compile_data = glob(6        include = ["**"],7        allow_empty = True,8        exclude = [9            "**/* *",10            "BUILD.bazel",11            "Cargo.toml",12        ],13    ) + [14        "//codex-rs/collaboration-mode-templates:templates/default.md",15        "//codex-rs/collaboration-mode-templates:templates/plan.md",16    ],

8codex_rust_crate(9    name = "cargo-bin",10    compile_data = ["repo_root.marker"],11    crate_name = "codex_utils_cargo_bin",12    lib_data_extra = ["repo_root.marker"],13    rustc_env = {14        "CODEX_REPO_ROOT_MARKER": "$(rlocationpath :repo_root.marker)",15    },16    test_data_extra = ["repo_root.marker"],17)

216### Spawning workspace binaries in tests (Cargo vs Bazel)217218- Prefer `codex_utils_cargo_bin::cargo_bin("...")` over `assert_cmd::Command::cargo_bin(...)` or `escargot` when tests need to spawn first-party binaries.219  - Under Bazel, binaries and resources may live under runfiles; use `codex_utils_cargo_bin::cargo_bin` to resolve absolute paths that remain stable after `chdir`.220- When locating fixture files or test resources under Bazel, avoid `env!("CARGO_MANIFEST_DIR")`. Prefer `codex_utils_cargo_bin::find_resource!` so paths resolve correctly under both Cargo and Bazel runfiles.

11#[derive(Debug, thiserror::Error)]12pub enum CargoBinError {13    #[error("failed to read current exe")]14    CurrentExe {15        #[source]16        source: std::io::Error,17    },18    #[error("failed to read current directory")]19    CurrentDir {20        #[source]21        source: std::io::Error,22    },23    #[error("CARGO_BIN_EXE env var {key} resolved to {path:?}, but it does not exist")]24    ResolvedPathDoesNotExist { key: String, path: PathBuf },25    #[error("could not locate binary {name:?}; tried env vars {env_keys:?}; {fallback}")]26    NotFound {27        name: String,28        env_keys: Vec<String>,29        fallback: String,30    },31}

33/// Returns an absolute path to a binary target built for the current test run.34///35/// In `cargo test`, `CARGO_BIN_EXE_*` env vars are absolute.36/// In `bazel test`, `CARGO_BIN_EXE_*` env vars are rlocationpaths, intended to be consumed by `rlocation`.37/// This helper allows callers to transparently support both.38#[allow(deprecated)]39pub fn cargo_bin(name: &str) -> Result<PathBuf, CargoBinError> {40    let env_keys = cargo_bin_env_keys(name);41    for key in &env_keys {42        if let Some(value) = std::env::var_os(key) {43            return resolve_bin_from_env(key, value);44        }45    }46    match assert_cmd::Command::cargo_bin(name) {47        Ok(cmd) => {48            let mut path = PathBuf::from(cmd.get_program());49            if !path.is_absolute() {50                path = std::env::current_dir()51                    .map_err(|source| CargoBinError::CurrentDir { source })?52                    .join(path);53            }54            if path.exists() {55                Ok(path)56            } else {57                Err(CargoBinError::ResolvedPathDoesNotExist {58                    key: "assert_cmd::Command::cargo_bin".to_owned(),59                    path,60                })61            }62        }63        Err(err) => Err(CargoBinError::NotFound {64            name: name.to_owned(),65            env_keys,66            fallback: format!("assert_cmd fallback failed: {err}"),67        }),68    }69}

71fn cargo_bin_env_keys(name: &str) -> Vec<String> {72    let mut keys = Vec::with_capacity(2);73    keys.push(format!("CARGO_BIN_EXE_{name}"));7475    // Cargo replaces dashes in target names when exporting env vars.76    let underscore_name = name.replace('-', "_");77    if underscore_name != name {78        keys.push(format!("CARGO_BIN_EXE_{underscore_name}"));79    }8081    keys82}

114/// Macro that derives the path to a test resource at runtime, the value of115/// which depends on whether Cargo or Bazel is being used to build and run a116/// test. Note the return value may be a relative or absolute path.117/// (Incidentally, this is a macro rather than a function because it reads118/// compile-time environment variables that need to be captured at the call119/// site.)120///121/// This is expected to be used exclusively in test code because Codex CLI is a122/// standalone binary with no packaged resources.123#[macro_export]124macro_rules! find_resource {125    ($resource:expr) => {{126        let resource = std::path::Path::new(&$resource);127        if $crate::runfiles_available() {128            // When this code is built and run with Bazel:129            // - we inject `BAZEL_PACKAGE` as a compile-time environment variable130            //   that points to native.package_name()131            // - at runtime, Bazel will set runfiles-related env vars132            $crate::resolve_bazel_runfile(option_env!("BAZEL_PACKAGE"), resource)133        } else {134            let manifest_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));135            Ok(manifest_dir.join(resource))136        }137    }};138}

317## Platform Support318319Tests and features must support Linux, macOS and Windows unless feature is explicitly OS-specific.320321Codex supports running connected app-server and exec-server on different operating systems. See the322`$remote-tests` skill for details about integration testing these configurations.

1# AGENTS.md23DeepSeek Harness is a plugin-based agent harness on vendored Cordis: **everything is a plugin**. Read [docs/architecture.md](docs/architecture.md) before changing `packages/`; follow [docs/AGENTS.md](docs/AGENTS.md) for documentation.

9## Cordis1011[Cordis](cordis-primer.md) is the framework under dsh: plugins contribute services, typed events, and reversible effects to a shared context. Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself, so every part is replaceable from configuration.1213There is no privileged core to patch: you extend dsh by mounting a plugin beside the others, and registrations are effects that unwind when their plugin unloads.

11  "workspaces": [12    "vendor/*",13    "packages/*/*",14    "native/landlock-run",15    "native/landlock-run/packages/*",16    "apps/*",17    "website"18  ],

39Covered automatically by globs or package-manifest discovery — no edits needed: root `package.json` workspaces, `scripts/publint-all.ts`, `tsdown.config.ts`, `.oxlintrc.json`, `scripts/check-workspace-constraints.ts`.

5- **Plugin exports:** service packages default-export their service class; function plugins named-export `name` / `inject` / `Config` / `apply` and have no default export. Mixing the forms makes the Loader discard the function plugin's namespace ([postmortem](../docs/postmortem/0001-acp-default-export-drops-inject.md)).

18- **Every package owns `./invariant`.** Register the manifest name; check an event/data relation or give empty installers package-specific `No runtime invariant:` reasons. Generated companions, unexplained empties, and ignored reporters fail [`verify-package-invariants`](../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md).

172  showLog(entry: Entry, type: string) {173    if (entry.options.group || !entry.parent.tree.enableLogs) return174    this.ctx.root.logger?.('loader').info('%s plugin %C', type, entry.options.name)175  }

13In-box bundles resolve from the dsh installation; out-of-tree bundles install into a profile through `dsh plugin --profile <name> add <package>`.

1# Auto-generated workspace root. Prefer editing per-crate Cargo.toml files.23[workspace]4resolver = "2"5members = [6    "crates/build/xai-proto-build",7    "crates/codegen/ptyctl",8    "crates/codegen/ptyctl-cli",9    "crates/codegen/xai-acp-lib",10    "crates/codegen/xai-agent-lifecycle",

80    "prod/mc/cli-chat-proxy-types",81    "third_party/dagre_rust",82    "third_party/graphlib_rust",83    "third_party/mermaid-to-svg",84    "third_party/ordered_hashmap",85]

83## Repository layout8485| Path | Contents |86|------|----------|87| `crates/codegen/xai-grok-pager-bin` | Composition-root package; builds the `xai-grok-pager` binary |88| `crates/codegen/xai-grok-pager` | The TUI: scrollback, prompt, modals, rendering |89| `crates/codegen/xai-grok-shell` | Agent runtime + leader/stdio/headless entry points |90| `crates/codegen/xai-grok-tools` | Tool implementations (terminal, file edit, search, ...) |91| `crates/codegen/xai-grok-workspace` | Host filesystem, VCS, execution, checkpoints |92| `crates/codegen/...` | The rest of the CLI crate closure (config, MCP, markdown, sandbox, ...) |93| `crates/common/`, `crates/build/`, `prod/mc/` | Small shared leaf crates pulled in by the closure |94| `third_party/` | Vendored upstream source (Mermaid diagram stack) — see below |9596> [!IMPORTANT]97> The root `Cargo.toml` (workspace members, dependency versions, lints,98> profiles) is **generated** — treat it as read-only. Prefer editing per-crate99> `Cargo.toml` files.

9# Composition-root binary for the Grok Build TUI. The artifact is still named10# `xai-grok-pager`. This package exists so the binary can link both the pager11# library and the optional `xai-grok-pager-minimal` render mode: `minimal`12# depends on `xai-grok-pager`, so the pager library cannot depend back on it13# (cargo cycle). The binary installs the minimal-mode IoC hooks at startup.14[[bin]]15name = "xai-grok-pager"16path = "src/main.rs"

1# `xai-grok-agent`23Agent builder, definition parsing, and system prompt assembly.45This crate extracts a first-class `Agent` type from `xai-grok-shell`.6An `Agent` bundles tools, system prompt, system-reminder policy,7compaction policy, and model configuration into a single, portable8object that any host can consume — whether that host is9`xai-grok-shell`, another in-process host, or a headless batch runner.