# Codex Copilot Web Search Compatibility Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add an opt-in `dev-util/codex[copilot-web-search]` build that sends hosted Responses API web-search tools through `copilot-api` instead of calling the ChatGPT-only `/alpha/search` endpoint.

**Architecture:** The personal overlay mirrors the current GURU Codex ebuild and conditionally applies one focused Rust patch. The patch disables selection of the standalone `web.run` executor, leaving Codex's existing hosted `web_search` specification visible to the Responses provider; `copilot-api` already forwards that hosted tool to GitHub Copilot.

**Tech Stack:** Gentoo EAPI 8, Portage USE flags and patches, Rust/Cargo, Codex tool-planning tests.

---

## File map

- Create `dev-util/codex/codex-0.144.6.ebuild`: overlay-owned package and conditional patch application.
- Create `dev-util/codex/metadata.xml`: package metadata and `copilot-web-search` USE-flag documentation.
- Create `dev-util/codex/files/codex-0.144.6-copilot-web-search.patch`: test and minimal Codex tool-selection change.
- Create `dev-util/codex/Manifest`: source and crate distfile checksums generated by Portage.
- Generate `metadata/md5-cache/dev-util/codex`: overlay cache entry generated from the ebuild.
- Modify `/etc/portage/package.use/codex`: locally enable the opt-in flag; this machine-local file is not committed to the overlay.

### Task 1: Add the overlay package skeleton

**Files:**
- Create: `dev-util/codex/codex-0.144.6.ebuild`
- Create: `dev-util/codex/metadata.xml`

- [ ] **Step 1: Copy the current GURU package inputs**

Run:

```bash
mkdir -p dev-util/codex/files
cp /var/db/repos/guru/dev-util/codex/codex-0.144.6.ebuild dev-util/codex/
cp /var/db/repos/guru/dev-util/codex/metadata.xml dev-util/codex/
```

Expected: the overlay contains the same source URI, crate bundle, dependencies, build steps, and upstream metadata as the installed `0.144.6` package.

- [ ] **Step 2: Declare the opt-in USE flag**

Add this line after `SLOT="0"` in `dev-util/codex/codex-0.144.6.ebuild`:

```bash
IUSE="copilot-web-search"
```

Add this block before `<upstream>` in `dev-util/codex/metadata.xml`:

```xml
	<use>
		<flag name="copilot-web-search">Use the hosted Responses API web-search tool instead of the ChatGPT-specific standalone search endpoint</flag>
	</use>
```

- [ ] **Step 3: Verify package metadata**

Run:

```bash
pkgcheck scan --net-restrict dev-util/codex
```

Expected: no invalid USE-flag, XML, or ebuild syntax report. Network-only upstream checks may be skipped by `--net-restrict`.

- [ ] **Step 4: Commit the package skeleton**

```bash
git add dev-util/codex/codex-0.144.6.ebuild dev-util/codex/metadata.xml
git commit -m "dev-util/codex: add 0.144.6 package skeleton"
```

### Task 2: Prove the desired tool-selection behavior fails upstream

**Files:**
- Test in temporary source: `codex-rs/core/src/tools/spec_plan_tests.rs`
- Final patch target: `dev-util/codex/files/codex-0.144.6-copilot-web-search.patch`

- [ ] **Step 1: Prepare a disposable upstream source tree**

Run:

```bash
work_dir=$(mktemp -d /tmp/codex-copilot-web-search.XXXXXX)
tar -xzf /var/cache/distfiles/codex-0.144.6.tar.gz -C "$work_dir"
cd "$work_dir/codex-rust-v0.144.6"
git init
git add codex-rs/core/src/tools/spec_plan.rs codex-rs/core/src/tools/spec_plan_tests.rs
git commit -m baseline
```

Expected: a temporary Git repository records the two pristine upstream files.

- [ ] **Step 2: Change the existing standalone-search expectation first**

In `codex-rs/core/src/tools/spec_plan_tests.rs`, replace:

```rust
    standalone_web_search.assert_visible_lacks(&["web_search"]);
```

with:

```rust
    standalone_web_search.assert_visible_contains(&["web_search"]);
    assert_eq!(
        standalone_web_search.namespace_function_names("web"),
        &[] as &[String],
    );
```

This test states that even when the experimental standalone feature and `web.run` extension are present, the compatibility build retains hosted search and hides the namespace executor.

- [ ] **Step 3: Run the focused test and verify RED**

Prepare the offline crate source using the same crate archive as the ebuild, then run:

```bash
tar -xJf /var/cache/distfiles/codex-rust-v0.144.6-crates.tar.xz -C "$work_dir"
cd "$work_dir/codex-rust-v0.144.6/codex-rs"
CARGO_NET_OFFLINE=true cargo test -p codex-core hosted_web_search_and_standalone_image_generation_follow_runtime_gates
```

Expected: FAIL because `web_search` is absent and the standalone `web.run` namespace is still visible. A dependency/setup error is not RED; correct the offline Cargo source configuration and rerun until the assertion fails for the expected reason.

### Task 3: Implement the minimal compatibility patch

**Files:**
- Modify in temporary source: `codex-rs/core/src/tools/spec_plan.rs`
- Create: `dev-util/codex/files/codex-0.144.6-copilot-web-search.patch`

- [ ] **Step 1: Disable standalone selection in the compatibility build**

In the temporary `codex-rs/core/src/tools/spec_plan.rs`, replace:

```rust
fn standalone_web_search_enabled(turn_context: &TurnContext) -> bool {
    namespace_tools_enabled(turn_context)
        && (turn_context.model_info.use_responses_lite
            || turn_context
                .config
                .features
                .get()
                .enabled(Feature::StandaloneWebSearch))
}
```

with:

```rust
fn standalone_web_search_enabled(_turn_context: &TurnContext) -> bool {
    false
}
```

The source patch is only applied when the USE flag is enabled, so no additional runtime switch is required inside Rust.

- [ ] **Step 2: Run the focused test and verify GREEN**

Run the same focused command established in Task 2:

```bash
CARGO_NET_OFFLINE=true cargo test -p codex-core hosted_web_search_and_standalone_image_generation_follow_runtime_gates
```

Expected: PASS; hosted `web_search` is visible and `web.run` is absent.

- [ ] **Step 3: Run relevant tool-planning and web-search tests**

Run:

```bash
CARGO_NET_OFFLINE=true cargo test -p codex-core tools::spec_plan_tests
CARGO_NET_OFFLINE=true cargo test -p codex-core --test all web_search
```

Expected: PASS for both commands. If the package's documented OpenSSL/ring conflict affects an unrelated test binary, retain the focused passing evidence and record the exact unrelated failure before proceeding.

- [ ] **Step 4: Export the final patch**

From the temporary `codex-rust-v0.144.6` repository, run:

```bash
git diff -- codex-rs/core/src/tools/spec_plan.rs codex-rs/core/src/tools/spec_plan_tests.rs > /home/deftera/Projects/deftera-overlay/dev-util/codex/files/codex-0.144.6-copilot-web-search.patch
```

Expected: the patch contains exactly one production-function change and one focused expectation change.

- [ ] **Step 5: Make patch application conditional**

In `dev-util/codex/codex-0.144.6.ebuild`, add immediately after `default` in `src_prepare()`:

```bash
	use copilot-web-search && eapply "${FILESDIR}/${P}-copilot-web-search.patch"
```

- [ ] **Step 6: Verify both patch modes**

Run:

```bash
ebuild dev-util/codex/codex-0.144.6.ebuild clean unpack prepare
USE=copilot-web-search ebuild dev-util/codex/codex-0.144.6.ebuild clean unpack prepare
```

Expected: both commands complete; the first leaves upstream source unchanged and the second applies the compatibility patch. If Portage requires root for its build directory, rerun these exact commands with scoped elevation.

- [ ] **Step 7: Commit the tested patch**

```bash
git add dev-util/codex/codex-0.144.6.ebuild dev-util/codex/files/codex-0.144.6-copilot-web-search.patch
git commit -m "dev-util/codex: add Copilot hosted search flag"
```

### Task 4: Generate overlay metadata and validate package resolution

**Files:**
- Create: `dev-util/codex/Manifest`
- Generate: `metadata/md5-cache/dev-util/codex`

- [ ] **Step 1: Generate the Manifest**

Run from the overlay root:

```bash
ebuild dev-util/codex/codex-0.144.6.ebuild manifest
```

Expected: `dev-util/codex/Manifest` contains the required DIST entries without duplicating source files into the repository.

- [ ] **Step 2: Regenerate the overlay cache**

Run:

```bash
egencache --repo deftera --update dev-util/codex
```

Expected: `metadata/md5-cache/dev-util/codex-0.144.6` reflects `IUSE=copilot-web-search` and the overlay ebuild hash.

- [ ] **Step 3: Validate overlay selection and USE resolution**

Run:

```bash
emerge -pv '=dev-util/codex-0.144.6::deftera'
```

Expected: Portage selects `::deftera` and lists `copilot-web-search` as an available disabled flag.

- [ ] **Step 4: Run final overlay QA**

Run:

```bash
pkgcheck scan --net-restrict dev-util/codex
git diff --check
```

Expected: no package errors and no whitespace errors.

- [ ] **Step 5: Commit generated package metadata**

```bash
git add dev-util/codex/Manifest metadata/md5-cache/dev-util/codex-0.144.6
git commit -m "dev-util/codex: generate package metadata"
```

### Task 5: Enable, install, and verify the compatibility build

**Files:**
- Modify outside repository: `/etc/portage/package.use/codex`

- [ ] **Step 1: Enable the USE flag locally**

Ensure `/etc/portage/package.use/codex` contains exactly one applicable entry:

```text
=dev-util/codex-0.144.6::deftera copilot-web-search
```

Use a root-owned editor or a scoped privileged write. Do not overwrite unrelated existing entries.

- [ ] **Step 2: Preview the installation**

Run:

```bash
emerge -pv '=dev-util/codex-0.144.6::deftera'
```

Expected: `copilot-web-search` is enabled and the package is selected from `::deftera`.

- [ ] **Step 3: Build and install through Portage**

Run with scoped elevation:

```bash
emerge --oneshot '=dev-util/codex-0.144.6::deftera'
```

Expected: the package compiles and installs successfully.

- [ ] **Step 4: Verify installed provenance and version**

Run:

```bash
equery belongs /usr/bin/codex
codex --version
```

Expected: `/usr/bin/codex` belongs to `dev-util/codex-0.144.6` and reports `codex-cli 0.144.6`.

- [ ] **Step 5: Start a fresh session and run the original reproduction**

Restart Codex so the newly installed binary is active, then request a simple live search such as `OpenAI official website`.

Expected: search results are returned; `copilot-api` does not return `Provider 'codex' not found or disabled`, and no ChatGPT OAuth prompt appears.

- [ ] **Step 6: Check repository cleanliness**

Run:

```bash
git status --short
git log -4 --oneline
```

Expected: only the pre-existing untracked `.omo/` remains; the design, plan, package, patch, and generated metadata are committed.