21 Commits

• path-uri: normalize parent segments in absolute joins (#29903)

  ## Why
  
  `PathUri::join` normalized `..` for relative paths, but its
  absolute-path branch rebuilt URIs through `url::PathSegmentsMut::push`,
  which skips dot segments. `/tmp/a/../b` therefore resolved to `/tmp/a/b`
  instead of `/tmp/b`.
  
  ## What changed
  
  Normalize absolute native path segments before constructing the file
  URI. Parent traversal now clamps at POSIX roots, Windows drive roots,
  and UNC share roots, including paths with repeated separators.
  
  Add platform-independent coverage for POSIX, drive, UNC, root-clamping,
  and repeated-separator cases.
  
  ## Manual validation
  
  - `just test -p codex-utils-path-uri`

  Adam Perry @ OpenAI · 2026-06-24 22:33:18 +00:00
  81f340436c
• Make selected plugin roots URI-native (#28918)

  ## Why
  
  Selected capability roots belong to the executor filesystem, not the
  app-server host. Converting their path strings into the host's native
  `Path` breaks whenever the two machines use different path conventions,
  such as a Windows executor behind a Unix app-server.
  
  This PR establishes `PathUri` as the selected-plugin boundary so the
  executor remains authoritative for its paths.
  
  ## What changed
  
  - Require `selectedCapabilityRoots[].location.path` to be a canonical
  `file:` URI and deserialize it directly as `PathUri`; native path
  strings are rejected.
  - Update the app-server schema, generated TypeScript, examples, and
  request coverage for the URI contract.
  - Keep selected roots, resolved plugin locations, manifest paths, and
  manifest resources as `PathUri`.
  - Inspect and read plugin roots and manifests only through the selected
  environment's `ExecutorFileSystem`.
  - Parse executor manifests with the shared URI-native parser from #29620
  instead of projecting them onto the host filesystem.
  - Enforce resource containment lexically and preserve the root URI's
  POSIX or Windows path convention.
  - Cover foreign Windows plugin roots and URI-native manifest resources.
  
  ```text
  thread/start
    selectedCapabilityRoots[].location.path = "file:///C:/plugins/demo"
                                | PathUri
                                v
                      ExecutorFileSystem
                                |
                                +--> plugin.json
                                +--> manifest resources
  ```
  
  This PR stops at the shared selected-plugin representation. The next two
  PRs remove the remaining host-path projections in the skill and MCP
  consumers.
  
  ## Stack
  
  1. #29614 — add lexical `PathUri` containment.
  2. #29620 — share URI-native manifest path resolution.
  3. **This PR** — keep selected plugin roots and resources URI-native.
  4. #29626 — load executor skills without host path conversion.
  5. #29628 — resolve executor MCP working directories without host path
  conversion.

  jif · 2026-06-23 22:51:19 +01:00
  2e69966cd8
• path-uri: remove legacy path deserialization (#29158)

  ## Why
  
  I'd originally added `PathUri` legacy path deserialization thinking we'd
  want it for having `PathUri` in public app-server APIs. Since then we've
  added `LegacyAppPathString` to handle the messy conversions that we need
  for backcompat. It's confusing for `PathUri` to support deserializing
  legacy paths when we don't yet want to actually expose app-server
  callers or rollout storage to the new URI format.
  
  Stacked on top of #29472 to avoid breaking compatibility in case those
  types ended up stored somewhere for someone.
  
  ## What changed
  
  - Parse deserialized `PathUri` values exclusively as valid `file:` URIs.
  - Replace legacy acceptance coverage with rejection coverage for
  top-level filesystem paths and sandbox working directories.
  - Serialize CWDs in hand-built exec-server process requests as `PathUri`
  values.

  Adam Perry @ OpenAI · 2026-06-23 21:47:00 +00:00
  c26f961b85
• Decouple plugin manifest path resolution (#29620)

  ## Why
  
  Plugin manifests use the same schema whether the package lives on the
  host or in an executor. Only the path representation differs: host
  callers need native `Path` inputs and `AbsolutePathBuf` outputs, while
  executor callers need `PathUri` throughout.
  
  Maintaining separate parsing or resolver implementations would duplicate
  the manifest rules and allow them to drift. This PR instead makes
  URI-native resolution the single parsing path and keeps host conversion
  at the boundary.
  
  ## What changed
  
  - Make `parse_plugin_manifest_uri` the shared manifest parser and
  resolve every path-bearing field as `PathUri`.
  - Keep the existing host entrypoint as a thin adapter: convert its
  native root and manifest path to `PathUri`, run the shared parser, then
  map resources back to `AbsolutePathBuf`.
  - Expose `PluginManifest::try_map_resources` so callers can convert the
  generic resource type without duplicating manifest construction.
  - Resolve relative manifest paths using the root URI's convention:
  backslashes are separators for Windows roots and ordinary filename
  characters for POSIX roots.
  - Apply lexical containment after URI resolution, rejecting absolute
  paths and parent traversal outside the plugin root.
  - Make encoded backslashes fail containment only for Windows URIs;
  encoded `/` remains unsafe for every convention.
  - Use a host-native synthetic root for marketplace fallback manifests so
  the host adapter also works on Windows.
  
  ```text
  host Path --------> PathUri --\
                                +--> one manifest parser --> PluginManifest<PathUri>
  executor PathUri -------------/
  
  host result: PluginManifest<PathUri> --> PluginManifest<AbsolutePathBuf>
  ```
  
  Existing host manifest behavior is preserved; #28918 is the first
  executor consumer.
  
  ## Verification
  
  - `just test -p codex-utils-path-uri`
  - `just test -p codex-plugin`
  - `just test -p codex-core-plugins`
  
  ## Stack
  
  1. #29614 — add lexical `PathUri` containment.
  2. **This PR** — share URI-native manifest path resolution.
  3. #28918 — keep selected plugin roots and resources URI-native.
  4. #29626 — load executor skills without host path conversion.
  5. #29628 — resolve executor MCP working directories without host path
  conversion.

  jif · 2026-06-23 20:33:59 +00:00
  f6500886b7
• core: resolve view_image paths in selected environment (#29526)

  ## Why
  
  view_image needs to support foreign OS remote executors.
  
  ## What
  
  - resolve image paths against the selected environment as `PathUri` and
  read them through that environment's filesystem
  - keep app-server's public path field wire-compatible as
  `LegacyAppPathString`, with purpose-specific UI rendering
  - cover relative and absolute target-native paths in the core
  integration test and run the full `view_image` suite under wine-exec
  without skips

  Adam Perry @ OpenAI · 2026-06-23 19:52:37 +00:00
  510bce9927
• path-uri: add lexical containment (#29614)

  ## Why
  
  Executor-owned paths must stay portable while the orchestrator reasons
  about them. Converting a Windows or remote path to the orchestrator
  host's native path just to check containment breaks that boundary.
  
  ## What changed
  
  - Add lexical containment to `PathUri`.
  - Compare URI authorities and complete path segments, so `plugin-other`
  is not treated as a child of `plugin`.
  - Fail closed for encoded path separators and opaque fallback URIs.
  
  For example:
  
  ```text
  file:///C:/plugins/foo/assets/icon.svg
    is below file:///C:/plugins/foo
  
  file:///C:/plugins/foo2/icon.svg
    is not below file:///C:/plugins/foo
  ```
  
  This is the shared foundation for keeping executor-owned plugin
  resources URI-native without consulting the orchestrator filesystem.

  jif · 2026-06-23 14:59:39 +01:00
  4147824509
• mcp: accept foreign absolute cwd for remote stdio (#29493)

  ## Why
  
  Remote stdio MCP servers can run in an environment whose path convention
  differs from the Codex host. A Windows cwd such as
  `C:\Users\openai\share` is absolute for the executor but was rejected by
  a POSIX orchestrator.
  
  Built on #29501, now merged, which only clarifies the host-native
  `PathUri` constructor name.
  
  ## What changed
  
  - Deserialize MCP cwd values as `LegacyAppPathString` so config does not
  apply host path rules.
  - Interpret that spelling as host-native for local launches and convert
  it to `PathUri` at executor launch.
  - Skip host filesystem and command resolution checks for remote stdio in
  `codex doctor`.
  - Add host-independent config and executor-boundary coverage using the
  foreign path convention for each test platform.
  
  ## Validation
  
  - `just test -p codex-utils-path-uri -p codex-config -p codex-mcp -p
  codex-rmcp-client` (408 passed)
  - `just test -p codex-cli -p codex-rmcp-client` (372 passed)
  - `cargo check --workspace --tests`
  - `just test` (11,311 passed; 43 unrelated environment/timing failures)
  - `just fix -p codex-cli -p codex-config -p codex-core -p codex-mcp -p
  codex-mcp-extension -p codex-rmcp-client -p codex-tui`

  Adam Perry @ OpenAI · 2026-06-23 01:33:51 +00:00
  67009bc53f
• path-uri: clarify host-native path conversion (#29501)

  ## Why
  
  Downstream refactors are producing confusing code with this
  functionality having a very generic name. Encoding the specific
  conversion approach in the method name makes it clearer.
  
  ## What
  
  Rename `PathUri::from_path` to `PathUri::from_host_native_path` and
  update its Rust call sites.

  Adam Perry @ OpenAI · 2026-06-23 00:02:33 +00:00
  11fab432be
• core: load AGENTS.md from foreign environments (#28958)

  ## Why
  
  Make it possible to load AGENTS.md from remote exec-servers whose OS is
  different than app-server.
  
  ## What
  
  - keep `AGENTS.md` discovery and provenance as `PathUri`, with
  root-aware parent and ancestor traversal
  - expose lifecycle instruction sources as legacy app-server path strings
  in events while retaining `PathUri` internally
  - preserve and test mixed POSIX and Windows paths in model context and
  TUI status output
  - cover remote Windows loading end to end by seeding the Wine prefix
  through host filesystem APIs
  - fix bug in `PathUri`'s parent() implementation that would erase
  Windows drive letters

  Adam Perry @ OpenAI · 2026-06-18 15:06:23 -07:00
  dce673905a
• apply-patch: carry paths as PathUri (#28854)

  ## Why
  
  Allows the model to edit files that are hosted on a different OS than
  where app-server is running.
  
  ## What
  
  * Use `PathUri` for apply_patch-internal data structures
  * Limit `PathUri` -> `AbsolutePathBuf` conversion to cases where the
  inferred path convention matches the host OS, allows requiring valid
  paths to pass to perms check
  * Adds `PathConvention::path_segments()` for iterating over path
  segments regardless of OS
  * Handle cross-platform relative paths in path filename parsing for
  sniffing a shell
  * Ensure we can apply patches in the wine e2e test

  Adam Perry @ OpenAI · 2026-06-18 19:31:19 +00:00
  0f89dd768c
• unified-exec: retain PathUri in command events (#28780)

  ## Why
  
  App-server must report command events containing foreign-platform paths
  without changing existing client or rollout path-string formats.
  
  ## What changed
  
  - retain `PathUri` through exec command begin/end events
  - convert cwd values to `LegacyAppPathString` at the app-server
  compatibility boundary
  - drop command actions with foreign paths and log them
  - serialize rollout-trace cwd values using their inferred native path
  representation
  - restore Wine coverage for retained Windows cwd values and successful
  completion

  Adam Perry @ OpenAI · 2026-06-18 05:00:04 +00:00
  3931bc2bde
• path-uri: decouple native path parsing (#28778)

  ## Why
  
  `PathUri::join` should not depend on the app-server compatibility
  wrapper `LegacyAppPathString` to parse native paths. Native path parsing
  belongs to the URI abstraction that it constructs.
  
  ## What
  
  Move platform-independent native path parsing into the root `PathUri`
  module. `PathUri::join` and `LegacyAppPathString` now share the
  crate-private `PathUri::from_absolute_native_path` constructor.

  Adam Perry @ OpenAI · 2026-06-17 22:17:07 +00:00
  e7b6e0d859
• unified-exec: preserve PathUri through exec-server (#28681)

  ## Why
  
  It should be possible for app-server to handle "foreign" OS paths in
  unified_exec working directories, allowing e.g. a Linux app-server to
  run processes on e.g. a Windows exec-server.
  
  ## What
  
  Convert the core unified_exec cwd values to use `PathUri`.
  
  Adds fallible path conversion in several places to try to minimize the
  scope of this change. The only time this change suppresses errors from
  converting `PathUri` to an `AbsolutePathBuf` is when the turn is
  configured with no sandboxing at all to allow us to make progress
  testing without sandboxing.
  
  Future changes to apply_patch and sandboxing will clean up these error
  paths.
  
  A tool's cwd is resolved from joining a model-provided workdir to the
  environment's cwd. When using `AbsolutePathBuf::join()`, an
  absolute-path workdir would overwrite the environment's cwd and we would
  resolve permissions/sandboxing against the model-provided path. This
  change extends `PathUri::join()` to also treat an absolute rhs as an
  override of the base/lhs.
  
  This also removes some coverage from the remove_env_windows tests until
  a follow-up converts foreign paths in command exec events correctly.
  
  ## Breaking Changes
  
  When using `AbsolutePathBuf::join()` for workdir resolution, we ended up
  resolving tilde-prefixed paths against the app-server's `$HOME`, e.g.
  `~/foo/bar` becomes `/home/anp/foo/bar`. It's difficult to do this with
  `PathUri` joining, so after offline discussion this PR no longer
  implements it.
  
  A quick check of some power users' rollouts suggests that models don't
  actually generate home-prefixed absolute working directories for their
  spawns, so this shouldn't have any real blast radius.

  Adam Perry @ OpenAI · 2026-06-17 19:36:16 +00:00
  5867b529ae
• core: render remote environment cwd natively (#28152)

  ## Why
  
  Model-visible `<environment_context>` should match the environment of
  the executor, not of the app server.
  
  Stacked on #28146.
  
  ## What
  
  - Keep selected environment cwd values as `PathUri` while building
  environment context.
  - Render cwd text using the path convention represented by the URI, with
  the canonical URI as a fallback.
  - Preserve compatibility with legacy `TurnContextItem.cwd` values when
  reconstructing and diffing context.
  - Extend the Wine-backed remote Windows test to assert that the model
  sees `powershell` and `C:\windows`.

  Adam Perry @ OpenAI · 2026-06-16 16:17:47 -07:00
  4c79527e31
• Clarify model-generated and legacy app path types (#28577)

  ## Why
  
  `ApiPathString` kind of implies that it can be used anywhere we pull a
  path out of JSON, but it's not really appropriate for tool arguments
  when the model might generate relative paths.
  
  Prefer `String` for model-generated paths and we can handle the
  conversion per feature for now and define a shared abstraction later if
  it makes sense.
  
  # What
  
  Rename `ApiPathString` to `AppLegacyPathString` to clarify its role.
  
  Expand the `path-types` skill to tell the model to leave tool args as
  bare strings.

  Adam Perry @ OpenAI · 2026-06-16 20:47:43 +00:00
  322b83de5e
• path-uri: clarify invalid host path errors (#28473)

  ## Why
  
  Ensure a consistent string format when exposing path conversion errors
  to the model.
  
  ## What
  
  - Render `PathUriParseError::InvalidFileUriPath` as `'$PATH' is invalid
  on '$OS'`.

  Adam Perry @ OpenAI · 2026-06-16 09:03:44 -07:00
  7162030b37
• Use ApiPathString in app-server filesystem permission paths (#28367)

  ## Why
  
  Clients running an app-server on one OS and an exec-server on another OS
  need to be able to pass sandbox config to app-server that refers to
  resources on the executor's foreign OS.
  
  ## What
  
  `AbsolutePathBuf` can't represent these paths and we don't want users to
  be exposed to `PathUri` yet, so this moves the public app-server API to
  be expressed in terms of `ApiPathString`.
  
  Stacked on #28165.
  
  - change app-server v2 filesystem permission paths, including legacy
  read/write roots, to `ApiPathString`
  - localize API paths through `PathUri` when converting into the current
  native core permission types
  - make path-bearing permission conversions fallible and surface
  localization failures instead of silently treating malformed grants as
  ordinary denials
  - propagate conversion failures through app-server and TUI approval
  handling
  - regenerate the app-server JSON and TypeScript schemas
  - leave migration TODOs on native-path conversions so they can be
  removed once core permission paths use `PathUri`

  Adam Perry @ OpenAI · 2026-06-15 19:25:54 -07:00
  ecfe174d5f
• path-uri: render native paths across platforms (#27819)

  ## Why
  
  We're moving to `PathUri` in more places to support cross-OS
  app-server/exec-server, but we don't want to expose the URI encoding to
  users of app-server's public APIs yet.
  
  We'll need to translate at the app-server API boundary between
  client-visible "regular" paths that are appropriate for the OS of the
  environment for which the paths make sense, which means using the
  environment's path personality to do the conversion.
  
  `PathUri` doesn't yet attempt to encode environment ID, so for now we'll
  sniff the most likely path convention for a given path.
  
  ## What
  
  - Add `PathConvention` and `NativePathString` with host-independent
  POSIX, Windows drive, and UNC rendering.
  - Cover cross-host rendering, encoding, Unicode, invalid components.

  Adam Perry @ OpenAI · 2026-06-14 05:26:49 +00:00
  5e9249ec02
• [codex] make PathUri::from_abs_path infallible (#27976)

  ## Why
  
  `PathUri::from_abs_path` can fail for absolute paths that do not have a
  normal `file:` URI representation, forcing filesystem call sites to
  handle a conversion error even though the original path can be preserved
  losslessly.
  
  ## What
  
  Make `from_abs_path` infallible and migrate its callers. Unrepresentable
  paths use `file:///%00/bad/path/<base64>`, encoding Unix bytes or
  Windows UTF-16LE; `to_abs_path` validates and decodes that fallback. The
  leading encoded null reserves a namespace that cannot collide with a
  real Unix or Windows path, and fallback URIs remain opaque to lexical
  path operations.
  
  ## Validation
  
  Added path-URI coverage for Unix null and non-UTF-8 paths, Windows
  device/verbatim and non-Unicode paths, serialization, malformed
  fallbacks, opaque lexical operations, invalid native payloads, and
  literal `/bad/path` collision resistance.

  Adam Perry @ OpenAI · 2026-06-12 16:58:42 -07:00
  968a3ac9c1
• [codex] add io PathUri native conversion APIs (#27280)

  ## Why
  
  Discovered some rough edges in the API while making use of it more
  widely within exec-server. It would be a lot more convenient for
  existing users of `AbsolutePathBuf` if `PathUri` conversion methods
  returned `std::io::Result`s.
  
  ## What
  
  * `PathUri::to_native_path()` -> `PathUri::to_abs_path()`
  * `PathUri::from_file_path()` -> `PathUri::from_abs_path()`

  Adam Perry @ OpenAI · 2026-06-10 08:51:17 -07:00
  0428e20a0b
• Add typed file URIs (#26840)

  ## Why
  
  Codex needs stable `file:` URI identifiers that can cross process and
  operating-system boundaries without eagerly interpreting them as native
  paths. Existing fields also need to keep accepting absolute path strings
  during migration.
  
  ## What changed
  
  - Add `codex-utils-path-uri` with a validated, immutable `PathUri`
  wrapper that currently accepts only `file:` URLs.
  - Expose URI-level `basename`, `parent`, and `join` operations that
  preserve authorities and percent encoding without guessing the source
  operating system.
  - Keep native conversion explicit through `AbsolutePathBuf` and the
  current host rules.
  - Serialize as canonical URI text while accepting both URI text and
  legacy absolute native paths during deserialization.
  - Add adversarial coverage for Windows-looking and POSIX paths, UNC
  authorities, encoded metadata characters, non-UTF-8 POSIX paths, URI
  hierarchy operations, and legacy serde round trips.

  Adam Perry @ OpenAI · 2026-06-08 16:33:41 -07:00
  ffec7c0933