Merge pull request #365 from SlanchaAI/agent/codex-wire-plugin

Add Codex plugin ergonomics for Wire

Author: laulpogan

.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "wire",
+  "interface": {
+    "displayName": "Wire"
+  },
+  "plugins": [
+    {
+      "name": "wire",
+      "source": {
+        "source": "local",
+        "path": "./"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "wire",
   "displayName": "Wire",
-  "version": "0.15.0",
-  "description": "Magic-wormhole for AI agents — bilateral signed-message bus over a mailbox relay. Rust-native MCP server with Ed25519-rooted operator + organization identity (RFC-001), bilateral SAS pairing, multi-relay federation. Discover, pair, and message other Claude / Codex / Copilot agents from this session.",
+  "version": "0.17.0",
+  "description": "Magic-wormhole for AI agents — bilateral signed-message bus over local and federated mailbox relays. Rust-native MCP server with Ed25519-rooted identity. Discover, pair, and message Claude, Codex, and Copilot agents from this session.",
   "author": {
     "name": "Paul Logan",
     "email": "paul@slancha.ai"

.codex-plugin/plugin.json

@@ -0,0 +1,40 @@
+{
+  "name": "wire",
+  "version": "0.17.0",
+  "description": "Bilateral signed-message bus for local and federated AI-agent sessions.",
+  "author": {
+    "name": "Slancha AI",
+    "email": "paul@slancha.ai",
+    "url": "https://slancha.ai"
+  },
+  "homepage": "https://wireup.net",
+  "repository": "https://github.com/SlanchaAi/wire",
+  "license": "AGPL-3.0-or-later AND Apache-2.0 AND MIT",
+  "keywords": [
+    "agent",
+    "p2p",
+    "ed25519",
+    "mailbox",
+    "mcp",
+    "identity"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Wire",
+    "shortDescription": "Secure agent-to-agent messaging",
+    "longDescription": "Discover, pair, and exchange signed messages with local or federated AI-agent sessions through Wire.",
+    "developerName": "Slancha AI",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://wireup.net",
+    "defaultPrompt": [
+      "Show my Wire identity and nearby agents.",
+      "Dial another agent over Wire.",
+      "Send a message to a paired Wire peer."
+    ]
+  }
+}

.gitignore

@@ -14,6 +14,7 @@
 # Local state
 *.local.md
 .claude/
+.worktrees/
 
 # Secrets / keys (defensive — operator keys live in $HOME/.config/wire/, never the repo)
 *.key

README.md

@@ -58,6 +58,7 @@ Wire integrates at the harness layer — your agent's tool-calling loop, not you
 | If you use… | Install path | First-run smoke |
 |---|---|---|
 | **Claude Code** | `cargo install slancha-wire`, then `/plugin install @SlanchaAi/wire` (also accepts the install.sh path) | SessionStart hook prints `wire <version>` ✓ |
+| **Codex App / CLI / IDE** | `cargo install slancha-wire`, `codex plugin marketplace add SlanchaAi/wire`, then `codex plugin add wire@wire` | Start a new task; ask “Show my Wire identity” |
 | **Cursor / Aider / generic MCP host** | `wire setup --apply` | Restart client; `wire_*` tools appear in MCP list |
 | **GitHub Copilot CLI** | [docs/integrations/COPILOT_CLI.md](docs/integrations/COPILOT_CLI.md) | `gh copilot` → "Call wire_whoami" |
 | **GitHub Copilot (VS Code)** | [docs/integrations/GITHUB_COPILOT.md](docs/integrations/GITHUB_COPILOT.md) | Restart VS Code; toolbar shows wire MCP |
@@ -67,6 +68,14 @@ Wire integrates at the harness layer — your agent's tool-calling loop, not you
 | **Pure terminal** | `wire up`, `wire dial`, `wire monitor` | local message appears |
 | **Custom harness / non-Node** | CLI `--json` mode + filesystem contract — see [docs/AGENT_INTEGRATION.md](docs/AGENT_INTEGRATION.md) | `wire whoami --json` + `wire tail --json` |
 
+Codex users who want only the tool surface can skip plugin packaging:
+
+```bash
+codex mcp add wire -- wire mcp
+```
+
+The plugin adds shared Wire skills and marketplace discovery; both routes run the same local `wire mcp`. Keep one Wire MCP registration enabled to avoid duplicate tool catalogs.
+
 ## Trust model (one paragraph)
 
 Knowing a handle (`alice@wireup.net`) and being able to resolve it to a signed agent-card is the authentication ceremony — same shape as discovering someone's Mastodon account via WebFinger or their PGP key via WKD. The card carries an Ed25519 verify-key, signed by that key, so the resolver knows the relay isn't lying about who claims the nick. FCFS on nicks; same-DID re-claims allowed. **Bilateral consent:** a stranger can leave one pair request in your `wire pending` list but can NEVER auto-pin themselves into your trust ring or get write access to your inbox until you `wire accept`. For threat models where the discovery channel itself can't be trusted (suspect DNS, distrustful operator), verify the resolved card fingerprint out-of-band (or pair via a one-time invite URL — see [Alternative flows](#alternative-flows)). Full threat model: [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md).

SESSION_LOG_2026_07_14.md

@@ -0,0 +1,50 @@
+# Session Log — 2026-07-14
+
+## Codex Wire ergonomics
+
+### What
+
+Investigated whether Wire already ships a Codex plugin. Repository had a Claude Code plugin (`.claude-plugin/plugin.json`) and shared MCP config (`.mcp.json`), but no `.codex-plugin/plugin.json` or Codex marketplace entry. Local Codex already had `wire -> wire mcp` enabled, confirming protocol/runtime capability existed without plugin packaging.
+
+### Why add a plugin
+
+MCP supplies tools. Plugin packaging supplies discovery, installation, shared workflow skills, and safety guidance. Product target is repository-distributed Codex support for other Wire users, not a personal-only setup.
+
+### Decision
+
+Use a root-level Codex manifest alongside the Claude manifest. Reuse `.mcp.json` and `skills/`; do not create a nested copied plugin tree. Keep Claude’s `SessionStart` hook out of the Codex manifest because current Codex validation rejects `hooks`. Make shared skill prose harness-neutral where necessary and preserve bilateral consent.
+
+Rejected:
+
+- nested `plugins/wire`: duplicates or fragile-links package assets;
+- MCP-only docs: capability works, but distribution and behavioral ergonomics remain weak.
+
+Design: `docs/superpowers/specs/2026-07-14-codex-plugin-design.md`.
+
+### Current phase
+
+Implementation and verification complete: packaging, shared-skill modernization, install documentation, isolated Codex install smoke, plugin/skill validation, and full Rust regression suite.
+
+### Implementation findings
+
+- Codex packaging reuses the repository root through marketplace source `./`.
+- Codex skill validation requires explicit `name` frontmatter.
+- Shared skills advertised removed SAS/init commands; corrected before Codex distribution.
+- `wire mcp` keeps data synchronized, while Codex ingests messages through `wire_pull` and `wire_tail` at task checkpoints.
+- The local plugin validator requires PyYAML; `uv run --with pyyaml` provides it without changing project dependencies.
+- Isolated `CODEX_HOME` smoke discovered `wire@wire` v0.17.0, installed it into plugin cache, and reported it enabled without touching normal Codex configuration.
+- Final `cargo test -q` exited 0 across unit, integration, stress, and doctest batches; only pre-existing ignored tests remained ignored.
+
+### Implementation artifacts
+
+- `.codex-plugin/plugin.json` — Codex plugin manifest.
+- `.agents/plugins/marketplace.json` — repository marketplace entry.
+- `tests/plugin_contract.rs` — packaging and documentation contract tests.
+- `skills/*/SKILL.md` — shared Claude/Codex workflows.
+- `README.md` and `docs/PLUGIN.md` — install and operation guidance.
+
+## Artifacts
+
+- `docs/superpowers/specs/2026-07-14-codex-plugin-design.md` — product design, invariants, packaging, and verification criteria.
+- `docs/superpowers/plans/2026-07-14-codex-plugin.md` — test-first implementation and verification plan.
+- `SESSION_LOG_2026_07_14.md` — session decisions and artifact catalog.

docs/PLUGIN.md

@@ -1,8 +1,8 @@
-# Wire as a Claude plugin
+# Wire agent plugins
 
-Wire is publishable as a [Claude Code plugin](https://code.claude.com/docs/en/plugins.md). The plugin manifest + skills + MCP server declaration live at the root of this repo; the actual wire binary is installed separately via Cargo.
+Wire packages its shared skills and MCP server for Claude Code and Codex. Harness-specific manifests live at the repository root; the actual `wire` binary is installed separately via Cargo.
 
-## Install (end-user UX)
+## Claude Code plugin
 
 Two steps:
 
@@ -23,15 +23,44 @@ The plugin ships six skills, all namespaced under `/wire:`:
 | Command | Purpose |
 |---|---|
 | `/wire:wire-init` | Initialize wire — mint session DID + Ed25519 keypair, optionally bind a public relay |
-| `/wire:wire-pair` | Pair this session with another wire agent (bilateral, signed, with optional SAS) |
+| `/wire:wire-pair` | Dial another Wire agent or handle an inbound consent decision |
 | `/wire:wire-monitor` | Arm the persistent inbox watcher per wire MCP session-start directive |
 | `/wire:wire-send` | Send a signed message to a paired peer (auto-pair on miss) |
 | `/wire:wire-enroll` | Enroll operator + organization identity (RFC-001 v0.14 identity layer) |
 | `/wire:wire-quiet` | Silence wire desktop toasts (file + env-based kill switches) |
 
+## Codex plugin
+
+The Codex manifest lives at `.codex-plugin/plugin.json` and reuses `.mcp.json` plus `skills/`. The binary remains a separate install:
+
+```bash
+cargo install slancha-wire
+codex plugin marketplace add SlanchaAi/wire
+codex plugin add wire@wire
+```
+
+Start a new task. Ask “Show my Wire identity,” then dial only a real operator-supplied persona. Inbound requests remain pending until explicit accept or reject.
+
+### MCP-only Codex setup
+
+```bash
+codex mcp add wire -- wire mcp
+```
+
+MCP-only gives the same tools without bundled skills or marketplace UX. Do not enable direct `mcp_servers.wire` and plugin-provided Wire MCP together unless testing duplicate registrations.
+
+### Local Codex development
+
+```bash
+codex plugin marketplace add /absolute/path/to/wire
+codex plugin add wire@wire
+```
+
+Reinstall after manifest or skill changes, then start a new task.
+
 ### MCP server tools
 
-Claude Code auto-starts `wire mcp` on session start (declared in `.mcp.json`). Identity auto-provisions and the sync daemon arms on first start — no manual init needed. Tools (all prefixed `mcp__wire__` over MCP):
+Claude Code and Codex auto-start `wire mcp` from `.mcp.json`. Identity auto-provisions and the sync daemon arms on first start — no manual init needed. Tool names:
 
 - **Orient / read** — `wire_whoami`, `wire_here` (who am I, who's around?), `wire_peers`, `wire_status`, `wire_tail`, `wire_pull`, `wire_verify`
 - **Connect** — `wire_dial` (the one to reach for: pairs a local sister or a `nick@domain` peer), `wire_pending`, `wire_accept`, `wire_reject`. `wire_add` is `wire_dial`'s federation backend; `wire_invite_mint` / `wire_invite_accept` cover the invite-URL path.
@@ -43,7 +72,7 @@ This list is verified against the live catalog by a test (`agent_docs_match_adve
 
 Resource: `wire://inbox/<peer>` exposes each pinned peer's verified inbox as JSONL.
 
-## Publishing channels
+## Claude publishing channels
 
 The plugin is publishable via three paths (all working from the same `.claude-plugin/plugin.json` manifest):
 
@@ -71,7 +100,7 @@ The three channels coexist. Community submission is recommended as the first pub
 
 Omitting the `version` field would make Claude Code use the git commit SHA — every commit is a new version. Slancha pins explicit semver for predictable rollouts.
 
-## Plugin install vs `wire setup` — pick one
+## Claude plugin install vs `wire setup` — pick one
 
 The plugin's `.mcp.json` declares the wire MCP server entry. If you previously ran `wire setup --apply` (which writes the same entry into `~/.claude.json`), you'll end up with two `mcpServers.wire` entries — global + plugin-scoped. Claude Code resolves them deterministically (plugin-scoped wins for the current session), but the duplicate is confusing and the global entry stops being maintained.
 
@@ -94,7 +123,7 @@ EOF
 
 A future `wire setup --apply` will detect a plugin install and skip writing the global entry; pre-v0.14.2 `wire setup` doesn't yet know about the plugin path. Tracking in v0.14.2 backlog.
 
-## Plugin development
+## Claude plugin development
 
 To work on the plugin scaffold without affecting end-user sessions: