mirror of
https://github.com/hanzoai/dev.git
synced 2026-10-17 15:34:54 +00:00
docs: reset roadmap and add maintenance guides
This commit is contained in:
James Peter
@@ -1,18 +0,0 @@
|
||||
# `code-*` vs `codex-*` Crate Parity Tracker
|
||||
|
||||
Goal: delete `code-*` crates once the forked implementation matches the new
|
||||
upstream baseline (or the upstream crate already covers our needs).
|
||||
|
||||
| Crate | Diff summary (code vs codex) | Ready to delete `code-*`? | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| ansi-escape | Renamed crate IDs (`code-ansi-escape` vs `codex-ansi-escape`), otherwise same API but we ship fork-specific spinner assets. | No | Wait until spinner grouping lands upstream or we can fully adopt theirs. |
|
||||
| arg0 | Fork keeps `--code-run-as-apply-patch` flag; upstream uses `codex`. | No | Needs flag rename adapters before deleting. |
|
||||
| browser | Fork-only feature. | No | Upstream lacks browser integration. |
|
||||
| core | Diverges heavily (executor/tool router, approval policy). | No | Bridge in progress (see `docs/subsystem-migration-status.md`). |
|
||||
| exec | Fork adds policy prompts + streaming bridges. | No | Depends on core migration. |
|
||||
| login | Fork adds approval + device flow tweaks; upstream gained OAuth helpers. | No | Reconcile after validating new helpers in fork. |
|
||||
| protocol | Upstream introducing new tool schema (ACP). | No | Needs schema audit before removal. |
|
||||
| tui | Fork retains browser UI, streaming invariants. | No | Must port status UI first. |
|
||||
|
||||
Update this table as diffs shrink. When “Yes” appears, schedule deletion in the
|
||||
next release window and update documentation accordingly.
|
||||
@@ -1,26 +0,0 @@
|
||||
# `code-rs` Dead-Code Sweep Plan
|
||||
|
||||
We now carry the upstream tree side-by-side. To keep `code-rs/` lean while
|
||||
we bridge to the upstream crates, run focused dead-code sweeps on a schedule.
|
||||
|
||||
## Cadence
|
||||
|
||||
| Window | Focus areas | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2025-10-20 → 2025-10-24 | `code-rs/tui/*` legacy render helpers, unused history cell modules. | TUI pod |
|
||||
| 2025-11-17 → 2025-11-21 | `code-rs/core/*` legacy executor adapters after the upstream router lands. | Core runtime pod |
|
||||
| 2025-12-15 → 2025-12-19 | Remaining crates (CLI, browser, app-server) post-executor migration. | Repo maintainers |
|
||||
|
||||
Add follow-up rows as additional migrations finish.
|
||||
|
||||
## Sweep checklist
|
||||
|
||||
1. Run `rg --files-without-match` patterns to detect unused modules (e.g. `mod
|
||||
` declarations).
|
||||
2. Confirm no crate-level `pub use` exposes the target symbol externally.
|
||||
3. Delete the dead module/file and rerun `./build-fast.sh --workspace code`.
|
||||
4. If the removal mirrors an upstream deletion, record it in
|
||||
`docs/subsystem-migration-status.md` so future merges know the fork matches
|
||||
upstream.
|
||||
|
||||
Track outcomes in PR descriptions so we know which areas are already cleaned.
|
||||
@@ -1,91 +0,0 @@
|
||||
# Code/Core Refactor – Wrapper-first Reset Plan
|
||||
|
||||
## Goals
|
||||
|
||||
- Keep upstream `codex-*` crates pristine so we can fast-forward to
|
||||
`openai/codex:main` without hand-merging fork logic every time.
|
||||
- Host all fork-only functionality (binaries, features, modules, assets)
|
||||
under parallel `code-*` crates that depend on the upstream crates.
|
||||
- Preserve a working build throughout the transition so we can ship fixes
|
||||
while the migration is underway.
|
||||
|
||||
## High-Level Strategy
|
||||
|
||||
We briefly diverged with piecemeal module copies. To simplify, we will:
|
||||
|
||||
### What to Avoid
|
||||
|
||||
We already tried copying modules into `code-*` while leaving the originals in `codex-*`; nothing pointed at the new copies, merges stayed painful, and the workspace exploded in size. This plan keeps the forked tree separate from the start so every step removes upstream churn instead of doubling it.
|
||||
|
||||
1. **Duplicate the tree once, then freeze upstream**
|
||||
- Move (via `git mv`) the existing `codex-rs/` working tree into
|
||||
`code-rs/` so history follows the forked code.
|
||||
- Run a scripted rename that turns every crate/package prefix
|
||||
`codex-` → `code-` inside the moved tree (Cargo manifests, feature
|
||||
names, `use` statements, module paths, tool configs).
|
||||
- Update workspace manifests, scripts, and build tooling so the renamed
|
||||
crates compile from their new location. Verify with `./build-fast.sh`.
|
||||
|
||||
2. **Restore upstream into `codex-rs/`**
|
||||
- Check out the latest `openai/codex:main` tree into `codex-rs/`.
|
||||
- Confirm `codex-rs/` contains zero fork-only files (just upstream).
|
||||
- Keep both trees side by side: `code-rs/` (fork) and `codex-rs/`
|
||||
(baseline).
|
||||
|
||||
3. **Bridge and prune incrementally**
|
||||
- Point binaries and downstream crates at the `code-*` versions first so
|
||||
the product keeps working.
|
||||
- For each fork feature area (TUI, app-server, CLI, core, browser, etc.)
|
||||
decide whether we can extend upstream `codex-*` code or must keep the
|
||||
forked implementation. Favor reusing large upstream sections where the
|
||||
integration cost is manageable; otherwise, maintain the fork logic and
|
||||
document why it diverges.
|
||||
- When we do integrate, prefer targeted extension points or light
|
||||
wrappers instead of one-to-one rewrites, and retire duplicate modules
|
||||
only after the shared path is verified.
|
||||
- After each feature area decision, re-run `./build-fast.sh` and capture
|
||||
any remaining fork patches in the matching `codex-*` crate for future
|
||||
cleanup.
|
||||
|
||||
4. **Ongoing maintenance**
|
||||
- Pull upstream changes directly into `codex-rs/`, resolve conflicts only
|
||||
in `code-rs/` when APIs shift, and document deltas in
|
||||
`docs/fork-enhancements.md`.
|
||||
- Track remaining wrapper-only surface in a status doc (e.g.
|
||||
`docs/tui-module-migration-status.md`).
|
||||
|
||||
## Execution Checklist
|
||||
|
||||
1. **DONE (2025-10-04):** Snapshot current state (branch + optional tag) so
|
||||
we can recover if the reset uncovers regressions. Created
|
||||
`snapshot/pre-upstream-reset-20251004` (branch) and
|
||||
`snapshot-pre-upstream-reset-20251004` (tag) before upstream restore
|
||||
work begins.
|
||||
2. **DONE (2025-10-04):** Duplicate `codex-rs/` into `code-rs/` so history
|
||||
follows the fork. Bulk-renamed all crates/binaries from `codex-*` to
|
||||
`code-*`, fixed module/file names, updated manifests, and confirmed
|
||||
`./build-fast.sh --workspace code` passes.
|
||||
3. **DONE (2025-10-04):** Update shared tooling (`build-fast.sh`) to target
|
||||
both workspaces and keep existing `codex` builds green (`./build-fast.sh`).
|
||||
4. **DONE (2025-10-04):** Audited all scripts, docs, and SDK samples to swap
|
||||
`codex-rs/…` references over to `code-rs/…` (see commits touching
|
||||
`build-fast.sh`, `scripts/ci-tests.sh`, TypeScript SDK, installation docs).
|
||||
5. **DONE (2025-10-04):** Checked out upstream `codex-rs/` at
|
||||
`openai/codex@d7acd146` and re-ran `./build-fast.sh --workspace codex`
|
||||
plus `./build-fast.sh --workspace code` to confirm both workspaces build.
|
||||
6. **DONE (2025-10-04):** Captured subsystem decisions in
|
||||
`docs/subsystem-migration-status.md`, highlighting where we will reuse
|
||||
upstream code versus keep fork-specialised wrappers.
|
||||
7. **DONE (2025-10-04):** Scheduled recurring `code-rs/` dead-code sweeps and
|
||||
documented the cadence in `docs/code-dead-code-sweeps.md`.
|
||||
8. **DONE (2025-10-04):** Opened `docs/code-crate-parity-tracker.md` to record
|
||||
when forked crates reach parity with upstream so we can delete duplicates
|
||||
ahead of releases.
|
||||
|
||||
## Tracking
|
||||
|
||||
- Maintain per-area migration status docs under `docs/`.
|
||||
- Record any upstream patches we must keep in `codex-*` (policy/legal) so
|
||||
future merges understand why they exist.
|
||||
- Treat `./build-fast.sh` as the sole required validation step after each
|
||||
migration chunk; fix all warnings before landing.
|
||||
@@ -0,0 +1,271 @@
|
||||
# Upstream Tracking and Diff Pipeline
|
||||
|
||||
This document describes the process for tracking differences between the fork (`code-rs`) and upstream (`codex-rs`), identifying critical changes, and planning merges.
|
||||
|
||||
## Overview
|
||||
|
||||
The fork maintains parallel crate trees:
|
||||
- **`codex-rs/`** - Upstream baseline (synced from `https://github.com/openai/codex.git`)
|
||||
- **`code-rs/`** - Fork implementation with enhancements
|
||||
|
||||
The tracking pipeline helps identify:
|
||||
1. **Structural differences** - Which crates have diverged
|
||||
2. **Critical changes** - Changes affecting prompts, API surface, or executor
|
||||
3. **Merge decisions** - Historical log of what was adopted/adapted/preserved
|
||||
|
||||
## Pipeline Scripts
|
||||
|
||||
All scripts are located in `scripts/upstream-merge/`:
|
||||
|
||||
### 1. `diff-crates.sh` - Structural Diff
|
||||
|
||||
Compares codex-rs vs code-rs on a per-crate basis.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
# Compare a single crate
|
||||
./scripts/upstream-merge/diff-crates.sh core
|
||||
|
||||
# Compare all shared crates
|
||||
./scripts/upstream-merge/diff-crates.sh --all
|
||||
|
||||
# Generate summary report
|
||||
./scripts/upstream-merge/diff-crates.sh --summary
|
||||
```
|
||||
|
||||
**Output:**
|
||||
- Individual diff files: `.github/auto/upstream-diffs/<crate>.diff`
|
||||
- Summary report: `.github/auto/upstream-diffs/SUMMARY.md`
|
||||
|
||||
**What it tracks:**
|
||||
- Line-by-line differences between matching crates
|
||||
- Added/removed lines count
|
||||
- Files present in one tree but not the other
|
||||
|
||||
### 2. `highlight-critical-changes.sh` - Critical Change Detection
|
||||
|
||||
Analyzes diffs to highlight changes in sensitive subsystems.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
# Analyze a specific crate
|
||||
./scripts/upstream-merge/highlight-critical-changes.sh core
|
||||
|
||||
# Analyze all crates
|
||||
./scripts/upstream-merge/highlight-critical-changes.sh --all
|
||||
```
|
||||
|
||||
**Output:**
|
||||
- Per-crate critical changes: `.github/auto/upstream-diffs/critical-changes/<crate>-critical.md`
|
||||
- Summary: `.github/auto/upstream-diffs/critical-changes/CRITICAL-SUMMARY.md`
|
||||
|
||||
**What it tracks:**
|
||||
- **Prompts**: Changes to `prompts/*.md`, `openai_tools.rs`, `agent_tool.rs`
|
||||
- **API Surface**: Changes to `protocol.rs`, `app-server-protocol`, `mcp-types`
|
||||
- **Executor**: Changes to `codex.rs`, `exec`, `apply-patch`, `acp.rs`
|
||||
- **Config**: Changes to config types and behavior toggles
|
||||
- Function signature changes
|
||||
- Enum/struct definition changes
|
||||
- Protocol message changes (EventMsg, Op variants)
|
||||
|
||||
### 3. `log-merge.sh` - Merge Activity Logger
|
||||
|
||||
Tracks merge decisions and resolutions for future reference.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
# Start a new merge
|
||||
./scripts/upstream-merge/log-merge.sh init upstream/main
|
||||
|
||||
# Add notes during merge
|
||||
./scripts/upstream-merge/log-merge.sh note conflict "core/src/codex.rs has protocol changes"
|
||||
|
||||
# Log decisions
|
||||
./scripts/upstream-merge/log-merge.sh decision core preserve "Keep fork's QueueUserInput support"
|
||||
./scripts/upstream-merge/log-merge.sh decision exec adopt "Upstream exec improvements compatible"
|
||||
|
||||
# Finalize when done
|
||||
./scripts/upstream-merge/log-merge.sh finalize
|
||||
|
||||
# View historical logs
|
||||
./scripts/upstream-merge/log-merge.sh summary
|
||||
```
|
||||
|
||||
**Output:**
|
||||
- Timestamped log: `docs/maintenance/upstream-merge-logs/merge-YYYYMMDD.md`
|
||||
|
||||
**What it tracks:**
|
||||
- Upstream ref and commit being merged
|
||||
- Fork state at merge start
|
||||
- Critical changes identified
|
||||
- Decisions made (adopt/adapt/preserve) with rationale
|
||||
- Post-merge checklist status
|
||||
|
||||
### 4. `verify.sh` - Post-Merge Verification
|
||||
|
||||
Validates that the fork still builds and maintains critical functionality after a merge.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
./scripts/upstream-merge/verify.sh
|
||||
```
|
||||
|
||||
**What it verifies:**
|
||||
- Build passes (`build-fast.sh`)
|
||||
- Core API surface compiles
|
||||
- Static guards (browser/agent tools still registered)
|
||||
- Version handling intact
|
||||
- Branding consistency
|
||||
|
||||
## Typical Workflow
|
||||
|
||||
### Weekly Upstream Check
|
||||
|
||||
```bash
|
||||
# Fetch latest upstream
|
||||
git fetch upstream
|
||||
|
||||
# Check for new commits
|
||||
git log HEAD..upstream/main --oneline
|
||||
|
||||
# If changes exist, start tracking
|
||||
./scripts/upstream-merge/diff-crates.sh --all
|
||||
./scripts/upstream-merge/highlight-critical-changes.sh --all
|
||||
```
|
||||
|
||||
### Planning a Merge
|
||||
|
||||
```bash
|
||||
# 1. Initialize merge log
|
||||
./scripts/upstream-merge/log-merge.sh init upstream/main
|
||||
|
||||
# 2. Review diffs
|
||||
cat .github/auto/upstream-diffs/SUMMARY.md
|
||||
cat .github/auto/upstream-diffs/critical-changes/CRITICAL-SUMMARY.md
|
||||
|
||||
# 3. For each critical crate, make decisions
|
||||
# Actions: adopt (take upstream), adapt (merge changes), preserve (keep fork)
|
||||
./scripts/upstream-merge/log-merge.sh decision core adapt "Merge ACP support while preserving QueueUserInput"
|
||||
./scripts/upstream-merge/log-merge.sh decision protocol adapt "Add new ACP variants, keep existing Op types"
|
||||
./scripts/upstream-merge/log-merge.sh decision tui preserve "Fork-only Rust TUI, ignore upstream TS changes"
|
||||
|
||||
# 4. Apply changes crate-by-crate
|
||||
# (Manual or scripted - depends on complexity)
|
||||
|
||||
# 5. Verify after each crate
|
||||
./scripts/upstream-merge/verify.sh
|
||||
|
||||
# 6. Finalize and document
|
||||
./scripts/upstream-merge/log-merge.sh finalize
|
||||
git add .
|
||||
git commit -m "chore(codex-rs): sync with upstream main
|
||||
|
||||
See docs/maintenance/upstream-merge-logs/merge-YYYYMMDD.md"
|
||||
```
|
||||
|
||||
### Integration Strategies
|
||||
|
||||
**Adopt (take upstream as-is):**
|
||||
- Upstream change is a strict improvement
|
||||
- No fork-specific functionality conflicts
|
||||
- Example: Performance improvements, bug fixes in non-critical paths
|
||||
|
||||
**Adapt (merge both):**
|
||||
- Upstream adds new capability, fork has extensions
|
||||
- Combine both sets of features
|
||||
- Example: Upstream adds ACP events, fork keeps existing event types
|
||||
|
||||
**Preserve (keep fork):**
|
||||
- Upstream removes/changes functionality fork depends on
|
||||
- Fork behavior is intentionally different
|
||||
- Example: Rust TUI vs TypeScript TUI, fork-specific tools
|
||||
|
||||
## Critical Subsystems
|
||||
|
||||
Pay special attention to changes in:
|
||||
|
||||
### Prompts and Tools
|
||||
- `prompts/*.md` - System prompts
|
||||
- `codex-rs/core/src/openai_tools.rs` - Tool definitions
|
||||
- `codex-rs/core/src/agent_tool.rs` - Agent-specific tools
|
||||
|
||||
Changes here affect LLM behavior and available capabilities.
|
||||
|
||||
### Protocol and API
|
||||
- `codex-rs/core/src/protocol.rs` - Core event types
|
||||
- `codex-rs/app-server-protocol/` - Frontend communication
|
||||
- `codex-rs/mcp-types/` - MCP protocol definitions
|
||||
|
||||
Changes here affect client compatibility and event flow.
|
||||
|
||||
### Executor
|
||||
- `codex-rs/core/src/codex.rs` - Main execution loop
|
||||
- `codex-rs/exec/src/` - Command execution
|
||||
- `codex-rs/apply-patch/src/` - File modification
|
||||
- `codex-rs/core/src/acp.rs` - Agent Client Protocol bridge
|
||||
|
||||
Changes here affect how tools execute and side effects are managed.
|
||||
|
||||
### Configuration
|
||||
- `codex-rs/core/src/config.rs` - Config loading
|
||||
- `codex-rs/core/src/config_types.rs` - Config schema
|
||||
|
||||
Changes here affect default behavior and user-facing options.
|
||||
|
||||
## Parity Tracking
|
||||
|
||||
After each merge, update `docs/code-crate-parity-tracker.md`:
|
||||
- Note which crates moved closer to parity
|
||||
- Update "Ready to delete code-*?" column
|
||||
- Add notes about remaining divergence
|
||||
|
||||
Goal: Eventually delete `code-rs/*` crates that match upstream, consolidating to single implementation.
|
||||
|
||||
## References
|
||||
|
||||
- **Upstream ACP Integration**: `docs/upstream-acp-merge.md` - Detailed notes on integrating Agent Client Protocol
|
||||
- **Parity Tracker**: `docs/code-crate-parity-tracker.md` - Per-crate divergence status
|
||||
- **Merge Prompts**: `prompts/MERGE.md` - Guidance for resolving conflicts
|
||||
- **Triage Prompts**: `prompts/TRIAGE.md` - Categorizing upstream changes
|
||||
|
||||
## Automation Opportunities
|
||||
|
||||
Future enhancements to pipeline:
|
||||
- Auto-detect upstream releases via GitHub API
|
||||
- Generate merge preview PRs automatically
|
||||
- Classify changes by semantic impact (breaking/compatible/internal)
|
||||
- Extract commit messages for changelog integration
|
||||
- Cross-reference with fork's issue tracker
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Diff shows everything changed:**
|
||||
- Check line endings (CRLF vs LF)
|
||||
- Verify both trees are clean (`git status`)
|
||||
- Ensure upstream remote is correctly configured
|
||||
|
||||
**Critical changes not detected:**
|
||||
- Update patterns in `highlight-critical-changes.sh`
|
||||
- Check that diff files exist in `.github/auto/upstream-diffs/`
|
||||
|
||||
**Verify script fails:**
|
||||
- Review `.github/auto/VERIFY.json` for specific failures
|
||||
- Check logs in `.github/auto/VERIFY_*.log`
|
||||
- Ensure all fork-specific guards are still valid
|
||||
|
||||
**Merge log not found:**
|
||||
- Logs are in `docs/maintenance/upstream-merge-logs/`
|
||||
- Initialize with `log-merge.sh init` before logging notes/decisions
|
||||
|
||||
## Maintenance
|
||||
|
||||
Update these scripts when:
|
||||
- New critical files/patterns emerge (update `CRITICAL_PATTERNS` in `highlight-critical-changes.sh`)
|
||||
- New crates are added to either tree (update `SHARED_CRATES` in `diff-crates.sh`)
|
||||
- New verification guards needed (update `verify.sh`)
|
||||
- Merge workflow evolves (update this doc and `log-merge.sh`)
|
||||
|
||||
---
|
||||
|
||||
Document created: 2025-10-05
|
||||
Last updated: 2025-10-05
|
||||
@@ -1,18 +0,0 @@
|
||||
# Subsystem Migration Status (2025-10-05)
|
||||
|
||||
This tracker documents how each major area of the fork compares against the
|
||||
fresh upstream snapshot in `codex-rs/` and whether we plan to reuse the upstream
|
||||
implementation or keep a forked variant living under `code-rs/`.
|
||||
|
||||
| Subsystem | Upstream delta summary | Decision | Immediate next steps |
|
||||
| --- | --- | --- | --- |
|
||||
| Core runtime (`core/`, `exec/`, `protocol/`, `apply-patch/`) | Upstream added a unified `executor` module, tool router, and richer MCP hooks. Fork keeps pre-refactor pipeline plus fork-only policy/approval features. | **Hybrid** — adopt upstream executor/tool router incrementally while preserving fork-only approval flow. | Diff `code-rs/core` vs `codex-rs/core` focusing on `executor/*` and `tools/*`; design an adapter so forked approval + sandbox policy can plug into the upstream router without copy-pasting. |
|
||||
| TUI (`tui/`) | Upstream reorganised history cells into typed renderers, added status dashboards/tests, and removed the older per-cell module tree. Fork still uses the legacy layout with Code-specific UX. | **Fork-primary** — keep `code-rs/tui` as the shipping implementation; cherry-pick upstream status widgets/tests once we add equivalent APIs in `code-rs`. | ✅ History/approval/event facade adapters landed behind `code-fork`. Next: finish routing remaining direct imports through compat modules, run manual smoke checklist, and continue pruning legacy test suites once replacements exist. |
|
||||
| CLI (`cli/`, `login/`, `mcp-*`, `responses-api-proxy/`) | Upstream refreshed auth flows (OAuth helpers in `rmcp-client`) and expanded MCP tooling; fork adds policy prompts, approval gating. | **Hybrid** — reuse upstream auth/mcp client improvements by wiring them behind feature flags in `code-rs` while keeping fork-only prompts. | Prototype re-export of `codex-rs/rmcp-client` login helpers inside `code-rs/login`; confirm CLI flag parity before deleting fork copies. |
|
||||
| Browser tooling (`browser/`, TUI browser events) | Upstream still lacks the browser agent; fork-only feature. | **Fork-only** — retain `code-rs/browser` and related TUI integrations. | Document browser integration in `docs/fork-enhancements.md` (already tracked); no upstream merge needed. |
|
||||
| App server (`app-server`, `app-server-protocol`) | Upstream rewrote message processor to use new executor/tool traits. Fork still references old pipeline. | **Monitor** — do not adopt until core executor bridge (above) lands; otherwise duplicate effort. | Once the core adapter is ready, revisit to see if we can reuse upstream app-server entirely. |
|
||||
| SDK / tooling (`sdk/typescript`, `scripts/*`) | Upstream scripts now assume `codex-*` bins. Fork updated to `code-*`. | **Fork-primary** with compatibility fallbacks. | Ensure scripts that read templates (e.g., `test-responses.js`) load both paths (already updated). Review future upstream changes quarterly. |
|
||||
| Build & release tooling (`build-fast.sh`, nix flakes) | Upstream still targets a single workspace. Fork must handle both. | **Fork-only** — maintain dual-workspace script. | Keep script in sync with upstream bugfixes manually; add regression tests later. |
|
||||
|
||||
Last updated **2025-10-04**. Update this table whenever a subsystem decision
|
||||
changes or a milestone completes.
|
||||
@@ -0,0 +1,369 @@
|
||||
# Upstream MCP Client Implementation Guide
|
||||
|
||||
Quick reference for implementing the upstream reuse strategy.
|
||||
|
||||
## Quick Start: Migrate to Upstream Dependencies
|
||||
|
||||
### 1. Update Workspace Cargo.toml
|
||||
|
||||
```toml
|
||||
# code-rs/Cargo.toml
|
||||
[workspace.dependencies]
|
||||
# Replace fork dependencies with upstream
|
||||
codex-mcp-client = { path = "../codex-rs/mcp-client" }
|
||||
codex-responses-api-proxy = { path = "../codex-rs/responses-api-proxy" }
|
||||
codex-process-hardening = { path = "../codex-rs/process-hardening" }
|
||||
|
||||
# Optional: Keep re-export aliases for gradual migration
|
||||
code-mcp-client = { path = "../codex-rs/mcp-client", package = "codex-mcp-client" }
|
||||
code-responses-api-proxy = { path = "../codex-rs/responses-api-proxy", package = "codex-responses-api-proxy" }
|
||||
code-process-hardening = { path = "../codex-rs/process-hardening", package = "codex-process-hardening" }
|
||||
```
|
||||
|
||||
### 2. Update Core Dependencies
|
||||
|
||||
```toml
|
||||
# code-rs/core/Cargo.toml
|
||||
[dependencies]
|
||||
# Option A: Direct migration
|
||||
codex-mcp-client = { workspace = true }
|
||||
|
||||
# Option B: Gradual migration with alias
|
||||
code-mcp-client = { workspace = true }
|
||||
```
|
||||
|
||||
### 3. Handle Binary Naming (If Required)
|
||||
|
||||
#### Option A: Build Script Rename
|
||||
|
||||
```rust
|
||||
// code-rs/cli/build.rs
|
||||
use std::env;
|
||||
use std::fs;
|
||||
use std::path::PathBuf;
|
||||
|
||||
fn main() {
|
||||
// If embedding binary
|
||||
let out_dir = PathBuf::from(env::var("OUT_DIR").unwrap());
|
||||
|
||||
// Copy upstream binary with code- prefix
|
||||
let upstream_bin = "../target/release/codex-responses-api-proxy";
|
||||
let renamed_bin = out_dir.join("code-responses-api-proxy");
|
||||
|
||||
if PathBuf::from(upstream_bin).exists() {
|
||||
fs::copy(upstream_bin, renamed_bin)
|
||||
.expect("Failed to copy responses-api-proxy binary");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Option B: Accept Upstream Naming
|
||||
|
||||
```rust
|
||||
// code-rs/cli/src/whatever_uses_the_binary.rs
|
||||
// Simply use codex- prefix everywhere
|
||||
const PROXY_BINARY: &str = "codex-responses-api-proxy";
|
||||
```
|
||||
|
||||
### 4. Create Buffer Size Wrapper (If Needed)
|
||||
|
||||
Test first if default buffer is sufficient. If not:
|
||||
|
||||
```rust
|
||||
// code-rs/core/src/mcp/client_wrapper.rs
|
||||
use codex_mcp_client::McpClient;
|
||||
use std::collections::HashMap;
|
||||
use std::ffi::OsString;
|
||||
|
||||
/// Creates MCP client optimized for large responses (code-rs specific)
|
||||
pub async fn create_large_response_client(
|
||||
program: OsString,
|
||||
args: Vec<OsString>,
|
||||
env: Option<HashMap<String, String>>,
|
||||
) -> std::io::Result<McpClient> {
|
||||
// For now, upstream implementation may already handle this well
|
||||
// TODO: Benchmark with actual large responses before customizing
|
||||
McpClient::new_stdio_client(program, args, env).await
|
||||
}
|
||||
|
||||
// If buffer customization proves necessary, contribute upstream PR
|
||||
// See: upstream-mcp-reuse-strategy.md Strategy B
|
||||
```
|
||||
|
||||
### 5. Update Imports
|
||||
|
||||
```rust
|
||||
// Before (code-rs fork)
|
||||
use code_mcp_client::McpClient;
|
||||
use code_process_hardening;
|
||||
|
||||
// After (upstream direct)
|
||||
use codex_mcp_client::McpClient;
|
||||
use codex_process_hardening;
|
||||
|
||||
// Or with re-export alias (no code changes needed)
|
||||
use code_mcp_client::McpClient; // Still works via Cargo.toml alias
|
||||
use code_process_hardening; // Still works via Cargo.toml alias
|
||||
```
|
||||
|
||||
## Testing the Migration
|
||||
|
||||
### 1. Unit Tests
|
||||
|
||||
```bash
|
||||
cd code-rs
|
||||
cargo test -p core # Test MCP client integration
|
||||
cargo test -p cli # Test proxy binary handling
|
||||
```
|
||||
|
||||
### 2. Integration Tests with Large Payloads
|
||||
|
||||
```rust
|
||||
// code-rs/core/tests/mcp_large_response_test.rs
|
||||
#[tokio::test]
|
||||
async fn test_large_tool_response() {
|
||||
// Generate 2MB JSON response
|
||||
let large_payload = generate_large_json_payload(2 * 1024 * 1024);
|
||||
|
||||
// Test MCP client handles it without truncation
|
||||
let client = create_test_mcp_client().await.unwrap();
|
||||
let result = client.call_tool(
|
||||
"large_data_tool".to_string(),
|
||||
Some(large_payload),
|
||||
Some(Duration::from_secs(30))
|
||||
).await;
|
||||
|
||||
assert!(result.is_ok());
|
||||
// Validate full payload received
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Security Validation
|
||||
|
||||
```bash
|
||||
# Verify process hardening still active
|
||||
cargo build --release
|
||||
./target/release/code-responses-api-proxy --help
|
||||
|
||||
# On Linux: Verify non-dumpable
|
||||
cat /proc/$(pgrep code-responses)/status | grep Dumpable
|
||||
# Should show: Dumpable: 0
|
||||
|
||||
# On macOS: Verify ptrace protection
|
||||
# Attempt: lldb -p $(pgrep code-responses)
|
||||
# Should fail: "Operation not permitted"
|
||||
```
|
||||
|
||||
## Upstream Contribution Workflow
|
||||
|
||||
### Proposing Buffer Configuration Feature
|
||||
|
||||
```rust
|
||||
// Proposed upstream change for codex-rs/mcp-client
|
||||
// File: codex-rs/mcp-client/src/mcp_client.rs
|
||||
|
||||
/// Configuration options for MCP client
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct McpClientConfig {
|
||||
/// Buffer capacity for reading server responses.
|
||||
/// Default: 8KB (Tokio default)
|
||||
/// Use larger values (e.g., 1MB) for servers with large tool responses
|
||||
pub buffer_capacity: Option<usize>,
|
||||
}
|
||||
|
||||
impl Default for McpClientConfig {
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
buffer_capacity: None,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl McpClient {
|
||||
// Existing method unchanged for compatibility
|
||||
pub async fn new_stdio_client(
|
||||
program: OsString,
|
||||
args: Vec<OsString>,
|
||||
env: Option<HashMap<String, String>>,
|
||||
) -> std::io::Result<Self> {
|
||||
Self::new_stdio_client_with_config(
|
||||
program,
|
||||
args,
|
||||
env,
|
||||
McpClientConfig::default()
|
||||
).await
|
||||
}
|
||||
|
||||
// New method with configuration
|
||||
pub async fn new_stdio_client_with_config(
|
||||
program: OsString,
|
||||
args: Vec<OsString>,
|
||||
env: Option<HashMap<String, String>>,
|
||||
config: McpClientConfig,
|
||||
) -> std::io::Result<Self> {
|
||||
// ... existing setup code ...
|
||||
|
||||
let reader_handle = {
|
||||
let pending = pending.clone();
|
||||
let mut lines = match config.buffer_capacity {
|
||||
Some(capacity) => BufReader::with_capacity(capacity, stdout).lines(),
|
||||
None => BufReader::new(stdout).lines(),
|
||||
};
|
||||
|
||||
// ... rest of implementation ...
|
||||
};
|
||||
|
||||
// ... rest of implementation ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### PR Description Template
|
||||
|
||||
```markdown
|
||||
## Add buffer configuration to MCP client
|
||||
|
||||
### Motivation
|
||||
When working with MCP servers that return large tool responses (>100KB),
|
||||
the default buffer size can impact performance. This PR adds optional
|
||||
buffer configuration while maintaining backward compatibility.
|
||||
|
||||
### Changes
|
||||
- Add `McpClientConfig` struct with optional buffer_capacity
|
||||
- Add `new_stdio_client_with_config` method
|
||||
- Keep existing `new_stdio_client` method unchanged (uses default config)
|
||||
|
||||
### Testing
|
||||
- Existing tests pass (backward compatibility verified)
|
||||
- New test: large response handling with 1MB buffer
|
||||
- Benchmark: 2MB response ~30% faster with larger buffer
|
||||
|
||||
### Breaking Changes
|
||||
None - existing API unchanged, new method is additive
|
||||
|
||||
### Use Case (code-rs)
|
||||
We use this in code-rs for MCP servers that return large file contents
|
||||
or extensive analysis results. Setting buffer to 1MB eliminates multiple
|
||||
read syscalls for these responses.
|
||||
```
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
If migration causes issues:
|
||||
|
||||
```toml
|
||||
# Revert to fork in code-rs/Cargo.toml
|
||||
[workspace.dependencies]
|
||||
code-mcp-client = { path = "mcp-client" }
|
||||
code-responses-api-proxy = { path = "responses-api-proxy" }
|
||||
code-process-hardening = { path = "process-hardening" }
|
||||
```
|
||||
|
||||
```bash
|
||||
# Restore fork code
|
||||
git checkout main -- code-rs/mcp-client
|
||||
git checkout main -- code-rs/responses-api-proxy
|
||||
git checkout main -- code-rs/process-hardening
|
||||
```
|
||||
|
||||
## Performance Benchmarks
|
||||
|
||||
Before migration, establish baseline:
|
||||
|
||||
```rust
|
||||
// code-rs/benches/mcp_client_bench.rs
|
||||
use criterion::{black_box, criterion_group, criterion_main, Criterion};
|
||||
|
||||
fn benchmark_large_response(c: &mut Criterion) {
|
||||
c.bench_function("mcp_client_1mb_response", |b| {
|
||||
b.iter(|| {
|
||||
// Test current fork implementation
|
||||
let client = create_fork_client();
|
||||
let result = client.call_tool_with_large_response();
|
||||
black_box(result)
|
||||
})
|
||||
});
|
||||
}
|
||||
|
||||
criterion_group!(benches, benchmark_large_response);
|
||||
criterion_main!(benches);
|
||||
```
|
||||
|
||||
After migration, compare:
|
||||
|
||||
```bash
|
||||
cargo bench --bench mcp_client_bench > before.txt
|
||||
# Apply migration
|
||||
cargo bench --bench mcp_client_bench > after.txt
|
||||
# Compare results
|
||||
diff before.txt after.txt
|
||||
```
|
||||
|
||||
## Monitoring Post-Migration
|
||||
|
||||
### CI/CD Checks
|
||||
|
||||
```yaml
|
||||
# .github/workflows/mcp-upstream-health.yml
|
||||
name: MCP Upstream Health Check
|
||||
on:
|
||||
schedule:
|
||||
- cron: '0 8 * * 1' # Weekly Monday 8am
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
check-upstream:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
with:
|
||||
submodules: true
|
||||
|
||||
- name: Check for upstream changes
|
||||
run: |
|
||||
cd codex-rs
|
||||
git fetch origin
|
||||
git diff origin/main -- mcp-client/ responses-api-proxy/ process-hardening/
|
||||
|
||||
- name: Run MCP integration tests
|
||||
run: |
|
||||
cargo test -p core -- mcp::
|
||||
cargo test -p cli -- proxy::
|
||||
|
||||
- name: Security audit
|
||||
run: cargo audit
|
||||
```
|
||||
|
||||
### Alerting
|
||||
|
||||
Set up GitHub notifications:
|
||||
1. Watch codex-rs repository
|
||||
2. Custom notification rules:
|
||||
- All activity in `mcp-client/`
|
||||
- All activity in `responses-api-proxy/`
|
||||
- All activity in `process-hardening/`
|
||||
- Security advisories
|
||||
|
||||
## Summary Checklist
|
||||
|
||||
- [ ] Update workspace dependencies to point to codex-rs
|
||||
- [ ] Test with default buffer size first
|
||||
- [ ] Implement wrapper only if needed (benchmark first)
|
||||
- [ ] Update imports or use Cargo.toml aliases
|
||||
- [ ] Run full test suite
|
||||
- [ ] Validate process hardening on all platforms
|
||||
- [ ] Benchmark performance before/after
|
||||
- [ ] Set up upstream monitoring
|
||||
- [ ] Prepare upstream PR for buffer config (if needed)
|
||||
- [ ] Document migration in CHANGELOG
|
||||
- [ ] Update internal documentation references
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Immediate**: Test upstream `codex-mcp-client` with code-rs workloads
|
||||
2. **Week 1**: Migrate mcp-client dependency if tests pass
|
||||
3. **Week 2**: Migrate responses-api-proxy with binary rename
|
||||
4. **Week 3**: Propose upstream buffer config PR
|
||||
5. **Ongoing**: Monitor upstream changes weekly
|
||||
|
||||
See [upstream-mcp-reuse-strategy.md](./upstream-mcp-reuse-strategy.md) for detailed analysis and rationale.
|
||||
@@ -0,0 +1,325 @@
|
||||
# Upstream MCP Client Reuse Strategy
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This document analyzes the feasibility of reusing `codex-rs/mcp-client` and `codex-rs/responses-api-proxy` directly from code-rs without maintaining separate forks. The investigation reveals **minimal divergence** between implementations, making upstream reuse highly feasible with a thin wrapper/patch strategy.
|
||||
|
||||
## Analysis of Current Divergence
|
||||
|
||||
### 1. MCP Client (`mcp-client`)
|
||||
|
||||
**Differences Found:**
|
||||
- **Buffer Size**: code-rs uses 1MB buffer (`BufReader::with_capacity(1024 * 1024, stdout)`) vs codex-rs default buffer
|
||||
- Location: `mcp-client/src/mcp_client.rs:145`
|
||||
- Reason: Handle large tool responses without truncation
|
||||
- Impact: Performance optimization for specific use cases
|
||||
|
||||
**Similarities:**
|
||||
- Identical package structure and dependencies
|
||||
- Same API surface and MCP protocol implementation
|
||||
- Same JSON-RPC message handling
|
||||
- Same environment variable filtering logic
|
||||
- File sizes: 476 vs 475 lines (virtually identical)
|
||||
|
||||
### 2. Responses API Proxy (`responses-api-proxy`)
|
||||
|
||||
**Differences Found:**
|
||||
- **None** - The lib.rs files are byte-for-byte identical
|
||||
|
||||
**Naming Differences:**
|
||||
- Package name: `code-responses-api-proxy` vs `codex-responses-api-proxy`
|
||||
- Binary name: `code-responses-api-proxy` vs `codex-responses-api-proxy`
|
||||
- Library name: `code_responses_api_proxy` vs `codex_responses_api_proxy`
|
||||
- Process hardening dependency: `code-process-hardening` vs `codex-process-hardening`
|
||||
|
||||
### 3. Process Hardening (`process-hardening`)
|
||||
|
||||
**Differences Found:**
|
||||
- **Minor style difference** in filter_map closure (code-rs uses compact `.then_some()`, codex-rs uses verbose if/else)
|
||||
- Location: `process-hardening/src/lib.rs:44-50` (Linux), `77-84` (macOS)
|
||||
- Functional equivalence: Identical behavior
|
||||
- Comment difference: Line 113 has `TODO(mbolin):` in codex-rs vs `TODO:` in code-rs
|
||||
|
||||
**Similarities:**
|
||||
- Identical hardening strategy (core dumps, ptrace, env vars)
|
||||
- Same platform-specific implementations
|
||||
- Same error handling and exit codes
|
||||
|
||||
## Proposed Wrapper/Patch Strategy
|
||||
|
||||
### Strategy A: Direct Upstream Dependency (Recommended)
|
||||
|
||||
Use codex-rs crates directly with minimal wrapper to handle fork-specific needs.
|
||||
|
||||
**Implementation:**
|
||||
|
||||
1. **MCP Client**: Add configuration parameter for buffer size
|
||||
```rust
|
||||
// In code-rs workspace Cargo.toml
|
||||
[dependencies]
|
||||
codex-mcp-client = { path = "../codex-rs/mcp-client" }
|
||||
|
||||
// Create thin wrapper in code-rs if buffer config needed
|
||||
pub fn create_mcp_client_large_responses(
|
||||
program: OsString,
|
||||
args: Vec<OsString>,
|
||||
env: Option<HashMap<String, String>>,
|
||||
) -> std::io::Result<codex_mcp_client::McpClient> {
|
||||
// Option 1: Use as-is (upstream buffer may be sufficient)
|
||||
codex_mcp_client::McpClient::new_stdio_client(program, args, env)
|
||||
|
||||
// Option 2: Propose buffer size config upstream
|
||||
// codex_mcp_client::McpClient::with_buffer_capacity(1024*1024)
|
||||
// .new_stdio_client(program, args, env)
|
||||
}
|
||||
```
|
||||
|
||||
2. **Responses API Proxy**: Use upstream with renamed binary
|
||||
```rust
|
||||
// In code-rs/cli binary embedding
|
||||
#[cfg(feature = "embed-binaries")]
|
||||
const RESPONSES_PROXY_BINARY: &[u8] =
|
||||
include_bytes!(concat!(env!("OUT_DIR"), "/codex-responses-api-proxy"));
|
||||
|
||||
// Or: Copy/symlink binary during build with code- prefix
|
||||
```
|
||||
|
||||
3. **Process Hardening**: Direct dependency, re-export if needed
|
||||
```rust
|
||||
// In code-rs workspace
|
||||
pub use codex_process_hardening as code_process_hardening;
|
||||
```
|
||||
|
||||
**Advantages:**
|
||||
- Zero maintenance burden for core logic
|
||||
- Automatic upstream security fixes and improvements
|
||||
- Minimal code duplication
|
||||
|
||||
**Disadvantages:**
|
||||
- Dependency on external codebase structure
|
||||
- Binary naming requires build script handling
|
||||
|
||||
### Strategy B: Feature-Flag in Upstream
|
||||
|
||||
Contribute buffer configuration as optional feature to codex-rs.
|
||||
|
||||
**Upstream PR Proposal:**
|
||||
```rust
|
||||
// In codex-rs/mcp-client/src/mcp_client.rs
|
||||
pub struct McpClientConfig {
|
||||
pub buffer_capacity: Option<usize>,
|
||||
// Future: timeout configs, retry logic, etc.
|
||||
}
|
||||
|
||||
impl Default for McpClientConfig {
|
||||
fn default() -> Self {
|
||||
Self { buffer_capacity: None }
|
||||
}
|
||||
}
|
||||
|
||||
impl McpClient {
|
||||
pub async fn new_stdio_client_with_config(
|
||||
program: OsString,
|
||||
args: Vec<OsString>,
|
||||
env: Option<HashMap<String, String>>,
|
||||
config: McpClientConfig,
|
||||
) -> std::io::Result<Self> {
|
||||
// ... existing code ...
|
||||
|
||||
let mut lines = if let Some(capacity) = config.buffer_capacity {
|
||||
BufReader::with_capacity(capacity, stdout).lines()
|
||||
} else {
|
||||
BufReader::new(stdout).lines()
|
||||
};
|
||||
|
||||
// ... rest of implementation ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Advantages:**
|
||||
- Cleanest long-term solution
|
||||
- Benefits both codebases
|
||||
- No wrapper needed
|
||||
|
||||
**Disadvantages:**
|
||||
- Requires upstream acceptance
|
||||
- Timeline depends on upstream review
|
||||
|
||||
### Strategy C: Minimal Fork with Automated Sync
|
||||
|
||||
Maintain current fork structure but automate sync from upstream.
|
||||
|
||||
**Implementation:**
|
||||
```bash
|
||||
# .github/workflows/sync-upstream-mcp.yml
|
||||
name: Sync Upstream MCP Components
|
||||
on:
|
||||
schedule:
|
||||
- cron: '0 0 * * 1' # Weekly
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
sync:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Sync mcp-client
|
||||
run: |
|
||||
rsync -av --exclude=Cargo.toml \
|
||||
../codex-rs/mcp-client/src/ \
|
||||
./code-rs/mcp-client/src/
|
||||
# Apply code-rs specific patches
|
||||
patch -p1 < patches/mcp-client-buffer-size.patch
|
||||
```
|
||||
|
||||
**Patch file** (`patches/mcp-client-buffer-size.patch`):
|
||||
```diff
|
||||
--- a/code-rs/mcp-client/src/mcp_client.rs
|
||||
+++ b/code-rs/mcp-client/src/mcp_client.rs
|
||||
@@ -141,7 +141,8 @@
|
||||
let reader_handle = {
|
||||
let pending = pending.clone();
|
||||
- let mut lines = BufReader::new(stdout).lines();
|
||||
+ // Use a larger buffer size (1MB) to handle large tool responses
|
||||
+ let mut lines = BufReader::with_capacity(1024 * 1024, stdout).lines();
|
||||
```
|
||||
|
||||
**Advantages:**
|
||||
- Automated tracking of upstream changes
|
||||
- Clear patch management
|
||||
- Fork-specific customization preserved
|
||||
|
||||
**Disadvantages:**
|
||||
- Still maintains separate crate
|
||||
- Patch conflicts require manual resolution
|
||||
|
||||
## Fork-Specific Modifications Required
|
||||
|
||||
### 1. Binary/Package Naming
|
||||
|
||||
**Current Naming:**
|
||||
| Component | codex-rs | code-rs |
|
||||
|-----------|----------|---------|
|
||||
| MCP client package | `codex-mcp-client` | `code-mcp-client` |
|
||||
| Proxy package | `codex-responses-api-proxy` | `code-responses-api-proxy` |
|
||||
| Proxy binary | `codex-responses-api-proxy` | `code-responses-api-proxy` |
|
||||
| Process hardening | `codex-process-hardening` | `code-process-hardening` |
|
||||
|
||||
**Resolution Strategies:**
|
||||
1. **Build-time rename**: Copy and rename binaries during build
|
||||
2. **Cargo alias**: Use `[[bin]]` section with custom name
|
||||
3. **Accept upstream names**: Use `codex-*` binaries in code-rs (simplest)
|
||||
|
||||
### 2. Buffer Size Configuration
|
||||
|
||||
**Options:**
|
||||
1. **Environment variable**: `MCP_BUFFER_SIZE=1048576`
|
||||
2. **Config file parameter**: Add to MCP server config
|
||||
3. **Upstream contribution**: Add to McpClientConfig (Strategy B)
|
||||
4. **Accept default**: Test if upstream buffer is sufficient
|
||||
|
||||
### 3. Process Hardening Integration
|
||||
|
||||
**Current approach:**
|
||||
```rust
|
||||
// code-rs binaries
|
||||
use code_process_hardening;
|
||||
|
||||
#[ctor::ctor]
|
||||
fn pre_main() {
|
||||
code_process_hardening::pre_main_hardening();
|
||||
}
|
||||
```
|
||||
|
||||
**Upstream reuse:**
|
||||
```rust
|
||||
// Option 1: Re-export
|
||||
pub use codex_process_hardening as code_process_hardening;
|
||||
|
||||
// Option 2: Direct use
|
||||
use codex_process_hardening;
|
||||
|
||||
#[ctor::ctor]
|
||||
fn pre_main() {
|
||||
codex_process_hardening::pre_main_hardening();
|
||||
}
|
||||
```
|
||||
|
||||
## Recommended Approach
|
||||
|
||||
**Phase 1: Immediate (Low-Risk Migration)**
|
||||
1. Depend on `codex-mcp-client` directly from code-rs
|
||||
2. Test with default buffer size - may already be sufficient
|
||||
3. If buffer issues arise, implement thin wrapper (Strategy A, Option 1)
|
||||
4. Use `codex-process-hardening` via re-export
|
||||
|
||||
**Phase 2: Short-Term (1-2 weeks)**
|
||||
1. Propose upstream PR for buffer configuration (Strategy B)
|
||||
2. Migrate responses-api-proxy to use upstream with build-time binary rename
|
||||
3. Document any remaining customization needs
|
||||
|
||||
**Phase 3: Long-Term Maintenance**
|
||||
1. Establish weekly automated checks for upstream changes
|
||||
2. Participate in upstream development for shared needs
|
||||
3. Maintain minimal patch set (ideally zero) for fork-specific requirements
|
||||
|
||||
## Upstream Parity Maintenance Checklist
|
||||
|
||||
### Weekly Tasks
|
||||
- [ ] Check codex-rs commits to mcp-client, responses-api-proxy, process-hardening
|
||||
- [ ] Review upstream issues/PRs that may affect code-rs usage
|
||||
- [ ] Run integration tests with latest upstream commits
|
||||
- [ ] Update dependency pins if changes detected
|
||||
|
||||
### Per-Upstream-Release Tasks
|
||||
- [ ] Review changelog for breaking changes
|
||||
- [ ] Test buffer size behavior with new release
|
||||
- [ ] Validate process hardening still meets security requirements
|
||||
- [ ] Update code-rs documentation if API changes
|
||||
- [ ] Run full test suite with new upstream version
|
||||
|
||||
### Monthly Tasks
|
||||
- [ ] Measure and document any performance differences
|
||||
- [ ] Review need for fork-specific customizations
|
||||
- [ ] Propose upstream contributions for shared needs
|
||||
- [ ] Audit dependency tree for security updates
|
||||
|
||||
### Monitoring Triggers
|
||||
- [ ] Set up GitHub notifications for codex-rs MCP-related commits
|
||||
- [ ] Create alerts for upstream security advisories
|
||||
- [ ] Track upstream issue tracker for relevant bug reports
|
||||
- [ ] Monitor codex-rs release notes for MCP changes
|
||||
|
||||
### Testing Requirements
|
||||
- [ ] Verify large tool response handling (>1MB payloads)
|
||||
- [ ] Test MCP client with various server implementations
|
||||
- [ ] Validate process hardening on all target platforms (Linux, macOS, Windows)
|
||||
- [ ] Benchmark buffer size impact on performance
|
||||
- [ ] Security audit of responses-api-proxy authentication
|
||||
|
||||
### Documentation Maintenance
|
||||
- [ ] Keep this document updated with any new divergences
|
||||
- [ ] Document reasons for any fork-specific patches
|
||||
- [ ] Maintain migration guide for upstream API changes
|
||||
- [ ] Track technical debt and sunset timeline for workarounds
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation |
|
||||
|------|------------|--------|------------|
|
||||
| Upstream breaks API | Low | High | Pin versions, automated testing |
|
||||
| Buffer size regression | Medium | Medium | Integration tests with large payloads |
|
||||
| Binary rename conflicts | Low | Low | Build script validation |
|
||||
| Security patch delay | Low | High | Automated weekly sync, subscribe to advisories |
|
||||
| Upstream abandonment | Very Low | High | Fork maintained as fallback (current state) |
|
||||
|
||||
## Conclusion
|
||||
|
||||
**The investigation reveals that code-rs can effectively reuse codex-rs MCP components with minimal overhead.** The primary difference (1MB buffer) is a trivial configuration change that can be:
|
||||
1. Tested to determine if even necessary
|
||||
2. Implemented as a thin wrapper
|
||||
3. Proposed upstream for mutual benefit
|
||||
|
||||
**Recommended Action**: Proceed with **Strategy A** (Direct Upstream Dependency) for immediate benefits, while pursuing **Strategy B** (Feature-Flag in Upstream) for long-term sustainability.
|
||||
|
||||
**Expected Outcome**: Reduced maintenance burden, automatic security updates, and stronger collaboration with upstream codex-rs development.
|
||||
Reference in New Issue
Block a user