fix: migrate Codex references to @agentclientprotocol/codex-acp

[RAIT-09]

Description

@zed-industries/codex-acp is deprecated on npm ("replaced by @agentclientprotocol/codex-acp" — same maintainer team, codex-acp bin name unchanged). This updates every reference to the successor package:

• Setup guide install command, plus a migration tip for removing the old package first (both ship the same codex-acp binary)
• Agent tables aligned with the Claude row ("via ACP adapter")
• In-app install hint (preset registry)
• Update checker: version checks now query the new package, and users still on the old adapter get an in-app "Package Migration Required" notice

The migration notice needed some care: the adapter kept its bin name across the move, so the reported name alone can't always tell old from new. DEPRECATED_PACKAGES became structured DEPRECATION_RULES with an onlyBelow: "1.0.0" version gate for codex (the old package never published 1.x), and the uninstall target is carried separately from the reported name. The Claude rules are behavior-identical. Added offline unit tests for the rules (195 tests total), and a debug log of the connected agent's reported name/version.

Related issue

#380 — keeping it open until the fix ships with the release (the docs site deploys from master).

Type of change

• Bug fix
• New feature
• Documentation
• Refactor
• Other

Checklist

• npm run lint passes ("Use sentence case for UI text" errors are acceptable for brand names)
• npm run build passes
• Tested in Obsidian
• Existing functionality still works
• Documentation updated if needed

Testing environment

• Agent: Codex — full migration path verified end-to-end: the old adapter (0.16.0) shows the migration notice, running the suggested command migrates cleanly, and the new adapter (reports @agentclientprotocol/codex-acp 1.1.9) connects with no false notice
• OS: macOS

Screenshots

N/A

Summary by CodeRabbit

• Documentation

  • Updated Codex setup instructions, links, and supported-agent references to use the current ACP adapter package.
  • Added migration guidance for replacing the deprecated Codex package.

• Bug Fixes

  • Added automatic detection and migration guidance for deprecated agent packages, including version-aware checks.
  • Improved connection diagnostics by reporting metadata from connected agents.

• Tests

  • Added coverage for package migrations, supported versions, unknown agents, and indeterminate versions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 87f54907-e477-40fc-b22a-55ae4b5fae91

📥 Commits

Reviewing files that changed from the base of the PR and between 4e73435 and d58f106.

📒 Files selected for processing (10)

• AGENTS.md
• docs/agent-setup/codex.md
• docs/agent-setup/index.md
• docs/getting-started/quick-start.md
• docs/index.md
• src/acp/acp-client.ts
• src/services/preset-agents.ts
• src/services/update-checker.ts
• test/stubs/obsidian.ts
• test/update-checker.test.ts

---

📝 Walkthrough

Walkthrough

The PR replaces the deprecated Codex ACP package with @agentclientprotocol/codex-acp, adds version-aware migration handling, updates documentation and installation hints, logs ACP agent metadata, and adds related tests and network stubs.

Changes

Codex ACP migration

Layer / File(s)	Summary
Package migration rules and tests src/services/update-checker.ts, test/update-checker.test.ts, test/stubs/obsidian.ts	Structured deprecation rules now support version-bounded Codex migration. Tests cover deprecated, supported, indeterminate, and unknown-agent cases.
Codex package references and installation guidance docs/..., AGENTS.md, src/services/preset-agents.ts	Installation commands, links, tables, and migration guidance now use @agentclientprotocol/codex-acp.
ACP agent metadata logging src/acp/acp-client.ts	Successful ACP initialization logs the connected agent name and version metadata.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related issues

• RAIT-09/obsidian-agent-client#380 — The PR replaces archived Codex ACP references and adds migration guidance.

Possibly related PRs

• RAIT-09/obsidian-agent-client#348 — The PR extends the preset-agent and update-checker migration handling introduced there.

Poem

A rabbit hops past old package names,
While Codex finds new ACP lanes.
Versions guide the upgrade trail,
Tests check each migration detail.
Agent metadata shines bright—
Documentation points it right.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the migration of Codex references to the replacement package.
Description check	✅ Passed	The description explains the changes, motivation, issue, testing, checklist results, environment, and documentation updates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/codex-acp-package-rename

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}