Metadata-Version: 2.4
Name: wanzi-codex
Version: 0.8.2
Summary: Drive Cursor's latest mixed-model mode straight from codex / claude / cursor: one install, then just talk.
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp
Requires-Dist: pydantic>=2.10.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: wanzi-mcp>=1.0.12
Requires-Dist: websocket-client>=1.7.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# wanzi-codex

**Drive Cursor's latest mixed‑model mode — and a whole team of AI sessions — straight from codex / Claude / Cursor. One install, then just talk.**

`wanzi-codex` ships an MCP server (plus a JSON‑first CLI and an embedded provider) that turns "open Cursor and click around" into "say one sentence." Register it once with your AI client (Codex CLI, Claude Desktop, Claude Code, or Cursor) and you can arm Cursor's newest mixed roster (latest Claude Opus + GPT, past the historical N=8 cap), run **multi‑session collaboration teams**, drive **unattended overnight autopilot**, and pursue **one‑line goals** to completion — without touching Cursor's UI and **without modifying a single Cursor file** (everything is done on disk + via CDP).

---

## Quick start (two commands, then just talk)

```bash
pip install wanzi-codex
wanzi-codex install all
```

`install all` registers the MCP server into every supported client config in one shot — Cursor `mcp.json`, Claude Desktop, Claude Code `~/.claude.json`, Codex CLI `~/.codex/config.toml` (idempotent; `--force` to overwrite). The MCP **embeds the provider in‑process** (state at `~/.wanzi-codex/`), so you do **not** need to run a separate daemon. Set `WANZI_PROVIDER_URL` only to point at an external HTTP provider.

Then, in any of those clients, just talk.

---

## Three verbs cover 95% of usage

| Verb | What it does |
|---|---|
| **`wanzi`** (mix) | Launch Cursor and arm the latest **mixed** Claude+GPT roster with "Use Multiple Models" on. |
| **`wanzi run`** | Decompose‑and‑execute a plan (or a persona template) across collaborating sessions. |
| **`wanzi check`** | One‑screen health/diagnostics view (runtime + model selection + readiness). |

Available as CLI subcommands (`wanzi`, `wanzi run`, `wanzi check`), as MCP tools (`wanzi_mix` / `wanzi_run` / `wanzi_check`, with `wz_*` compatibility aliases), and via natural language — say *"open 16 mixed models"* or *"用 claude 单模型卡控制台"* and the `wanzi_route` intent resolver maps it to the right tool.

---

## What's inside (v0.8)

- **Mixed‑model arming past N=8** — normalizes Cursor's `bestOfNEnsemblePreferences` on disk to the newest Claude Opus + GPT family, qualifies any folder for Cursor's GitHub‑gated multi‑model option, launches with a debug port, and toggles "Use Multiple Models" via CDP. No Cursor file modified.
- **Multi‑session collaboration runtime** (`wanzi_codex_provider.collab`) — `SessionTeam` topologies (star / pipeline / mesh / blackboard), a cross‑session message bus with addressing + backpressure, task allocation strategies, a propose→review→revise→decide round protocol with convergence detection + Moderator, a shared blackboard, result aggregation, observability + deadlock detection, plus production hardening (budget guard, human‑in‑the‑loop escalation, resumable snapshots, capability profiles, record/replay, scope security).
- **Unattended autopilot** (`wanzi_codex_provider.autopilot`) — one switch (`off / assisted / full`), a scheduler + watchdog, hard guardrails (no irreversible ops), tiered alerting, stop conditions with graceful finish, and a morning digest. Run it overnight, wake up to a report.
- **Goal‑driven execution** (`wanzi_codex_provider.goal`) — `wanzi goal "<objective>"` becomes persistent state that iterates plan→act→verify→review until acceptance or budget exhaustion (`budget_limited` wrap‑up + clean resume). Parity with codex `/goal`, differentiated by running the goal across a **multi‑session team**.
- **Console keepalive** (`console_hold` / `console_send` / `console_status`) — long‑poll "hold" that keeps an MCP conversation alive across many parallel sessions (mixed or single model), with `auto_continue` self‑healing that **replaces the purple‑button** rerun/continue path.
- **Cross‑client command compatibility** — a registry mapping codex (~40) + Claude Code (60+) slash commands to wanzi equivalents, with `command_compat`, a slash front‑end, `/init` scaffolding, `/feedback`→repro, and a compatibility matrix.
- **Enterprise orchestrator** (`wanzi_codex_provider.orchestrator`) — a DAG of scope‑bounded tasks + interface contracts, dependency‑ordered parallel waves, a global ledger, family‑aware role specialization (Claude writes / GPT reviews architecture), per‑wave Moderator adjudication with four conflict strategies (majority / score‑weighted / later‑writer / higher‑score) plus an optional **LLM‑as‑judge** moderator, and D‑tier verification gates.
- **Onboarding & ops** — `doctor` (offline health check + live Cursor/CDP/provider probes) and a `setup` wizard that turns the report into an ordered fix‑it checklist; a **collaboration postmortem** (5 metrics + per‑model audit table); persistent **usage/cost/ROI** accounting fed from runtime token counts; a read‑only HTML **dashboard**; and an auto‑generated **reference** doc (never drifts — rendered from the live tool + command registries).
- **Extensible & portable** — a **plugin** registry (capability packs), a vendor‑neutral **LLM backend** registry with a fallback chain, **i18n** message catalogs, a **cloud‑agent** run config with safety guardrails, multi‑member **team** configs, and a **multi‑project** cross‑collaboration registry (shared‑contract surfacing).
- **Engineering foundation** — atomic writes + advisory store locks for concurrent sessions, schema versioning/migration, graceful‑shutdown snapshots, offline‑by‑default egress policy, tool authorization tiers, OTLP log export, SBOM, health probes, timestamped backup/restore, and optional store encryption at rest.

---

## Console scripts

| Script | Role |
|---|---|
| `wanzi` / `wz` / `wanzi-codex` | JSON‑first CLI: `mix` / `run` / `check` / `goal` / `autopilot` / `commands` / `init` / diagnostics / install. |
| `wanzi-codex-mcp` | Stdio MCP server (registered into codex / claude / cursor by `install all`). |
| `wanzi-codex-provider` | Standalone HTTP provider (optional — the MCP embeds it by default). |
| `wanzi-codex-cursor-mixed` | One‑shot: launch Cursor and toggle mixed mode on. |
| `wanzi-codex-cursor-enforce` | Watchdog that re‑arms the latest mixed roster across relaunches. |

## Python packages

| Package | Purpose |
|---|---|
| `wanzi_codex_provider` | FastAPI provider, JSONL store, Cursor runtime adapter, CDP driver, `state.vscdb` writers, model ranking, **orchestrator / collab / autopilot / goal / commands** subpackages. |
| `wanzi_codex_mcp` | FastMCP server (in‑process or HTTP), console keepalive, intent routing, tool authorization. |
| `wanzi_codex_core` | `ProviderClient`, atomic IO, store locking, schema migration, secrets redaction, cost/ROI, resource governor, retry/backoff, structured logging, health, backup, store crypto. |
| `wanzi_codex_cli` | argparse CLI (`install all` + the verbs + goal/autopilot/commands). |

---

## How model selection reaches Cursor's backend

When you pick a model in Cursor's UI, the choice is persisted to Cursor's SQLite `state.vscdb`, then materialized into each composer's `modelConfig` before any backend request:

1. **UI pick** → `cursor/lastSingleModelPreference` (single) or `cursor/bestOfNEnsemblePreferences` + `cursor/bestOfNCountPreference` (multi‑model roster).
2. **Composer creation** → the preference materializes into `composerData.modelConfig.modelName` (single) or `subComposerIds[]` (each sub‑composer carrying its own `modelConfig.modelName`).
3. **Message send** → the composer's `modelConfig` is included in the agent/stream request body.

`wanzi-codex` intercepts at stage 1 by writing the preference keys directly, then uses a live CDP toggle so the UI reflects the change without a window reload — **no Cursor file is modified** (which is why it survives Cursor's integrity protection).

---

## Tests

```bash
python -m pytest -q
```

1311 passed, 2 skipped at the time of this release (the 2 skips are live wanzi‑desktop integration tests gated behind `WANZI_CODEX_LIVE_TESTS=1`). The full non‑live suite runs without a Cursor instance.

## Safety

No Cursor installation file is ever modified. `state.vscdb` is backed up before risky writes. Egress is offline‑by‑default (localhost + your configured gateway only; telemetry off unless you opt in). Nothing is committed or published without you asking. See the requirements spec in `docs/` for the full constraint list.
