agent-relay-codex 0.6.0 → 0.10.0

package/README.md

@@ -1,177 +1,13 @@
-# agent-relay-codex
+# Agent Relay Codex Compatibility Package
 
-Codex integration for [Agent Relay](https://github.com/edimuj/agent-relay): auto-registers Codex sessions as agents and delivers incoming messages as live turns.
+Codex lifecycle is now owned by `agent-relay-runner`.
 
-## Install
+Use:
 
 ```bash
-# one-time setup (requires bun + codex CLI)
-curl -fsSL https://unpkg.com/agent-relay-codex@latest/install-codex.sh | bash
+codex-relay --cwd /path/to/project
+codex-relay --headless --cwd /path/to/project
+agent-relay provider wrap codex
 ```
 
-Windows PowerShell:
-
-```powershell
-irm https://unpkg.com/agent-relay-codex@latest/install-codex.ps1 | iex
-```
-
-The installer adds a `codex-relay` launcher and asks whether plain `codex` should also route through Agent Relay.
-
-## Usage
-
-```bash
-# start the relay server (separate terminal)
-bunx agent-relay-server@latest
-
-# start Codex with Agent Relay (after restarting your shell)
-codex-relay
-
-# start a relay-only Codex agent without opening a TUI
-codex-relay --headless
-```
-
-Without restarting your shell:
-
-```bash
-bunx -p agent-relay-codex@latest codex-relay
-```
-
-## Configuration
-
-| Env var | Default | Purpose |
-|---------|---------|---------|
-| `AGENT_RELAY_URL` | `http://localhost:4850` | Relay server URL |
-| `AGENT_RELAY_TOKEN` | — | Auth token (for remote relays) |
-| `AGENT_RELAY_CAPS` | `chat` | Comma-separated capabilities |
-| `AGENT_RELAY_APPROVAL` | `open` | Approval mode: `open`, `guarded`, `read-only` |
-
-These env vars are shared with the [Claude plugin](https://www.npmjs.com/package/agent-relay-plugin). Agent profiles are also shared:
-
-| Env var | Default | Purpose |
-|---------|---------|---------|
-| `AGENT_RELAY_PROFILE` | — | Profile name from the profiles file |
-| `AGENT_RELAY_PROFILES_FILE` | `~/.config/agent-relay/profiles.json` | JSON profile file |
-| `AGENT_RELAY_TAGS` | — | Extra comma-separated tags |
-| `AGENT_RELAY_LABEL` | — | Human-friendly label |
-| `AGENT_RELAY_CHANNELS` | all | Comma-separated channel subscriptions |
-
-Example profile:
-
-```json
-{
-  "frontend-developer": {
-    "label": "frontend dev",
-    "tags": ["frontend", "ui"],
-    "capabilities": ["chat", "review", "frontend"],
-    "channels": ["frontend"],
-    "approval": "guarded"
-  }
-}
-```
-
-Run with `AGENT_RELAY_PROFILE=frontend-developer agent-relay-codex start`.
-
-### Codex-specific
-
-| Env var | Default | Purpose |
-|---------|---------|---------|
-| `CODEX_MODEL` | — | Model override |
-| `CODEX_THREAD_MODE` | `start` | Thread attach: `start`, `resume`, `auto` |
-| `CODEX_THREAD_ID` | — | Pin to a specific thread |
-| `CODEX_APP_SERVER_URL` | `ws://127.0.0.1:4501` | App-server WebSocket URL |
-| `AGENT_RELAY_CODEX_HEADLESS` | — | Set to `1` to run without opening a TUI |
-| `AGENT_RELAY_DISABLED` | — | Set to `1` to bypass Agent Relay hooks and launcher shims |
-
-### Advanced tuning
-
-| Env var | Default | Purpose |
-|---------|---------|---------|
-| `AGENT_RELAY_CODEX_RIG` | `codex-live` | Rig name on agent card |
-| `AGENT_RELAY_CODEX_POLL_INTERVAL_MS` | `2000` | Inbox poll cadence |
-| `AGENT_RELAY_CODEX_HEARTBEAT_INTERVAL_MS` | `30000` | Heartbeat cadence |
-| `AGENT_RELAY_CODEX_COALESCE_WINDOW_MS` | `600` | Message batch window |
-| `AGENT_RELAY_CODEX_RELAY_BACKOFF_INITIAL_MS` | `2000` | Relay API retry backoff |
-| `AGENT_RELAY_CODEX_RELAY_BACKOFF_MAX_MS` | `60000` | Relay API retry backoff cap |
-
-## Approval mode
-
-`codex-relay` maps `AGENT_RELAY_APPROVAL` to Codex runtime flags:
-
-| Mode | Codex flags |
-|------|-------------|
-| `open` | `--ask-for-approval never --sandbox danger-full-access` |
-| `guarded` | `--ask-for-approval on-request --sandbox workspace-write` |
-| `read-only` | `--ask-for-approval never --sandbox read-only` |
-
-Pass explicit Codex flags to override:
-
-```bash
-# trusted private rig: no sandbox
-codex-relay -- --dangerously-bypass-approvals-and-sandbox
-
-# full-auto mode
-codex-relay -- --full-auto
-```
-
-If `AGENT_RELAY_APPROVAL` is set, explicit Codex permission flags must resolve
-to the same effective mode.
-
-The approval mode is registered on the agent card as `meta.approvalMode` (`open`, `guarded`, or `read-only`), visible in the dashboard.
-
-## Uninstall
-
-```bash
-agent-relay-codex uninstall          # remove hooks, plugins, shims
-agent-relay-codex uninstall --purge  # also remove runtime state and PATH entries
-```
-
-## How it works
-
-`codex-relay` launches `codex app-server`, then opens the TUI with `codex --remote <app-server-url>`. The normal SessionStart hook registers the visible TUI thread with Agent Relay, so Agent Relay messages and direct TUI messages share the same Codex context.
-
-Use `codex-relay --headless` on servers where Agent Relay is the only interaction surface. It starts the same app-server and sidecar session but does not open a TUI; the launcher prints `codex resume --remote <app-server-url>` if you later want to attach one.
-
-The installed SessionStart hook remains for plain `codex` launches. In that mode, the hook registers the visible Codex session with Agent Relay without requiring the managed `codex-relay` launcher.
-
-The live sidecar:
-
-- Registers the session as an Agent Relay agent
-- Polls the relay inbox and delivers messages into the active Codex thread
-- Coalesces rapid message bursts into a single turn
-- Claims claimable tasks before delivery
-- Reconnects with exponential backoff after disconnects
-- Marks the agent offline on exit
-
-Message delivery adapts to thread state: `turn/start` when idle, `turn/steer` when active, `turn/interrupt` for urgent messages.
-
-## Command Skills
-
-The Codex plugin ships command skills for Agent Relay slash commands:
-
-```bash
-/pair codex "Debug flaky tests"
-/message codex "Can you look at that failing action?"
-/send-claimable tag:backend "Please claim and fix the failing API test"
-/disconnect
-/status
-/label backend-fixer
-/tags backend tests urgent
-```
-
-If another installed skill uses the same name, invoke the prefixed form such as
-`/agent-relay:pair`, `/agent-relay:message`,
-`/agent-relay:send-claimable`, `/agent-relay:disconnect`,
-`/agent-relay:status`, `/agent-relay:label`, or `/agent-relay:tags`.
-
-## Development
-
-```bash
-# run sidecar directly
-bash codex/start-live.sh
-
-# run tests
-bun test codex/
-
-# doctor check
-bun run codex/bin/agent-relay-codex.ts doctor
-```
+The old standalone live sidecar, SessionStart hook, and Codex plugin marketplace install path have been removed.