feat: per-job event stream + watchdog + compact recovery (1.1.0)

.claude-plugin/marketplace.json

@@ -5,13 +5,13 @@
   },
   "metadata": {
     "description": "Codex plugins to use in Claude Code for delegation and code review.",
-    "version": "1.0.4"
+    "version": "1.1.0"
   },
   "plugins": [
     {
       "name": "codex",
       "description": "Use Codex from Claude Code to review code or delegate tasks.",
-      "version": "1.0.4",
+      "version": "1.1.0",
       "author": {
         "name": "OpenAI"
       },

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openai/codex-plugin-cc",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "private": true,
   "type": "module",
   "description": "Use Codex from Claude Code to review code or delegate tasks.",

plugins/codex/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "Use Codex from Claude Code to review code or delegate tasks.",
   "author": {
     "name": "OpenAI"

plugins/codex/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 1.1.0
+
+Observability rework for the main-loop orchestration case: the consumer of
+"what is codex doing right now" is the calling Claude session, not a human
+dashboard. Adds a per-job NDJSON event stream the main loop can poll, plus
+a protocol-native recovery path for context overflow.
+
+- `/codex:events <job-id>`: new slash command. Streams normalized codex
+  notifications from `{stateDir}/jobs/{jobId}.events.ndjson`. Supports
+  `--since <iso>` / `--after-seq <n>` / `--limit <n>` / `--json` for
+  incremental polling. Each event carries `seq`, `ts`, `method`, `phase`,
+  `itemType`, `message`, and the raw payload.
+- `/codex:compact <thread-id>`: new slash command wrapping codex
+  app-server's `thread/compact/start`. Protocol-native recovery for
+  "prompt too long" — typical flow is cancel → compact → resume with an
+  amended prompt via `/codex:rescue --resume`.
+- `/codex:rescue` now defaults to `--background`. The main Claude loop
+  receives a job id immediately and polls `/codex:events` instead of
+  blocking on a synchronous Bash call; this removes the deadlock when
+  codex stalls or errors silently.
+- Per-job stall watchdog (60s default, override via
+  `CODEX_COMPANION_STALL_SECONDS`) emits a `{type:"watchdog",
+  phase:"stuck"}` event when codex produces no new notifications inside
+  the window. The watchdog never cancels — the main loop decides whether
+  to continue, compact, or cancel.
+- New `{type:"job/exited"}` terminal event with `phase: completed|failed`
+  and `exitCode`. This is the single source of truth for end-of-job;
+  callers should not infer terminal state from job-level `status` alone.
+- Surfaces token usage as a top-level field on `runAppServerTurn` and
+  streams real-time usage via `thread/tokenUsage/updated` events
+  (`phase: "metering"`).
+- Coverage of codex CLI 0.131 notification methods extended to
+  `thread/status/changed`, `warning`, `thread/tokenUsage/updated`, plus
+  item types `userMessage`, `assistantMessage`/`agentMessage`, and
+  `reasoning`. The `agentMessage` item now surfaces a content preview so
+  the main loop can recognize codex's final reply from the event stream
+  without fetching `/codex:result`.
+- Test isolation: `tests/helpers.mjs` now unsets `CLAUDE_PLUGIN_DATA` and
+  `CODEX_COMPANION_SESSION_ID` at module load. Plugin host runtimes (e.g.
+  Claude Code) inject these vars; without isolation, two existing tests
+  fail when contributors run `npm test` from inside a host.
+
 ## 1.0.0
 
 - Initial version of the Codex plugin for Claude Code

plugins/codex/agents/codex-rescue.md

@@ -20,8 +20,7 @@ Selection guidance:
 Forwarding rules:
 
 - Use exactly one `Bash` call to invoke `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task ...`.
-- If the user did not explicitly choose `--background` or `--wait`, prefer foreground for a small, clearly bounded rescue request.
-- If the user did not explicitly choose `--background` or `--wait` and the task looks complicated, open-ended, multi-step, or likely to keep Codex running for a long time, prefer background execution.
+- Default to background execution: if the user did not explicitly choose `--background` or `--wait`, append `--background`. The companion command returns a job id immediately so the main Claude loop can monitor progress via `/codex:events <job-id>` and `/codex:status <job-id>` instead of blocking on the synchronous Bash call. Honor `--wait` only when the user explicitly asks for foreground execution.
 - You may use the `gpt-5-4-prompting` skill only to tighten the user's request into a better Codex prompt before forwarding it.
 - Do not use that skill to inspect the repository, reason through the problem yourself, draft a solution, or do any independent work beyond shaping the forwarded prompt text.
 - Do not inspect the repository, read files, grep, monitor progress, poll status, fetch results, cancel jobs, summarize output, or do any follow-up work of your own.

plugins/codex/commands/compact.md

@@ -0,0 +1,33 @@
+---
+description: Trigger codex's protocol-native context compaction on a thread (recovery path for "prompt too long")
+argument-hint: '<thread-id> [--json]'
+disable-model-invocation: true
+allowed-tools: Bash(node:*)
+---
+
+!`node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" compact "$ARGUMENTS"`
+
+When to use:
+
+- A Codex task has stalled or failed with a context-overflow error and you want to recover the thread without losing its history.
+- `/codex:events <job-id>` shows `phase:"stuck"` for an extended period and `phase:"metering"` records indicate the token budget is near the limit.
+- A previous turn returned `phase:"failed"` with a context-length error and you want to compact before resuming.
+
+Typical recovery sequence:
+
+1. `/codex:cancel <job-id>` if a turn is still running and stuck.
+2. `/codex:compact <thread-id>` — this command. Returns immediately after the codex app-server acknowledges the compaction request.
+3. `/codex:rescue --resume <amended prompt>` — resume the (now compacted) thread with a tighter prompt.
+
+Output format:
+
+- Without `--json`: prints `Compaction started on <thread-id>.` and a hint for the resume flow.
+- With `--json`: returns `{attempted, compacted, transport, result, detail}`.
+
+If the thread id is malformed or the app-server rejects the request, the command exits non-zero and emits the codex-side error in `stderr` (or in `detail` under `--json`).
+
+Notes:
+
+- Compaction runs codex-side after this command returns; it is not a synchronous wait.
+- `thread/compact/start` is a streaming RPC in the app-server protocol, but this wrapper does not consume the stream — codex completes compaction in the background regardless of whether a stream consumer is active.
+- The exact success payload shape from codex CLI is preserved verbatim under `result` for forward-compat; downstream consumers should not depend on its keys beyond what they have observed.

plugins/codex/commands/events.md

@@ -0,0 +1,24 @@
+---
+description: Stream Codex notifications as a per-job NDJSON event log for poll-based monitoring
+argument-hint: '<job-id> [--since <iso>] [--after-seq <n>] [--limit <n>] [--json]'
+disable-model-invocation: true
+allowed-tools: Bash(node:*)
+---
+
+!`node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" events "$ARGUMENTS"`
+
+How to use the output:
+
+- Each line in the stream is a normalized notification: `seq`, `ts`, `method`, `phase`, `itemType`, `message`, and `raw`.
+- Treat `{type:"job/exited"}` as the single source of truth for terminal state — its `phase` is `completed` or `failed`, and `exitCode` reflects the codex turn outcome. Do not infer end-of-job from job-level `status` alone.
+- `phase:"stuck"` records (emitted by the worker's stall watchdog) mean codex produced no new notifications for the configured stall window (default 60s, override with `CODEX_COMPANION_STALL_SECONDS`). The job is not cancelled — the main loop decides whether to keep waiting, run `/codex:compact <thread-id>` to recover from context overflow, or `/codex:cancel <job-id>` to abort.
+- `phase:"warning"` records carry codex-side non-fatal conditions (context budget exceeded, capabilities removed). They are informational, not failures.
+- `phase:"metering"` records come from `thread/tokenUsage/updated` and stream real-time token usage; poll them to detect "this turn is burning a lot of tokens" before hitting context overflow.
+- Use `--after-seq <last-seq>` for incremental polling. If both `--after-seq` and `--since` are supplied, `--after-seq` wins. Default (no filter) returns all events for the job; the main loop is responsible for dedupe-by-seq.
+
+Output format:
+
+- Without `--json`: one human-readable line per event.
+- With `--json`: `{jobId, eventsFile, count, events: [...]}`.
+
+If no events exist yet for the job id, the command prints `No events yet for <job-id>.` and exits 0.

plugins/codex/commands/rescue.md

@@ -15,7 +15,7 @@ Execution mode:
 
 - If the request includes `--background`, run the `codex:codex-rescue` subagent in the background.
 - If the request includes `--wait`, run the `codex:codex-rescue` subagent in the foreground.
-- If neither flag is present, default to foreground.
+- If neither flag is present, default to background. The companion returns a job id immediately; poll progress with `/codex:events <job-id> --since <last-seq> --json` (or `/codex:status <job-id>`) instead of blocking on a synchronous Bash call. This prevents the main Claude loop from deadlocking when Codex stalls or fails silently.
 - `--background` and `--wait` are execution flags for Claude Code. Do not forward them to `task`, and do not treat them as part of the natural-language task text.
 - `--model` and `--effort` are runtime-selection flags. Preserve them for the forwarded `task` call, but do not treat them as part of the natural-language task text.
 - If the request includes `--resume`, do not ask whether to continue. The user already chose.