@leo000001/codex-mcp 2.1.6 → 2.1.7

package/README.md

@@ -204,7 +204,7 @@ Start a Codex agent session asynchronously. Returns immediately with `sessionId`
 
 </details>
 
-**Returns:** `{ sessionId, threadId, status, pollInterval?, execution?, interactionState?, recommendedNextAction? }`
+**Returns:** `{ sessionId, threadId, status, pollInterval?, progress?, execution?, interactionState?, recommendedNextAction? }`
 
 ```json
 {
@@ -217,6 +217,40 @@ Start a Codex agent session asynchronously. Returns immediately with `sessionId`
 }
 ```
 
+Structured output example:
+
+```json
+{
+  "prompt": "Return a short health summary",
+  "approvalPolicy": "on-failure",
+  "sandbox": "workspace-write",
+  "advanced": {
+    "outputSchema": {
+      "type": "object",
+      "properties": {
+        "ok": { "type": "boolean" },
+        "summary": { "type": "string" }
+      },
+      "required": ["ok", "summary"]
+    }
+  }
+}
+```
+
+If the backend accepts the schema, the terminal `result` includes `structuredOutput`:
+
+```json
+{
+  "result": {
+    "text": "Health check complete.",
+    "structuredOutput": {
+      "ok": true,
+      "summary": "Repository is healthy"
+    }
+  }
+}
+```
+
 ### Resources
 
 If your MCP client supports resources, this server exposes a few **read-only** resources:
@@ -246,13 +280,14 @@ Send a follow-up message to an existing session.
 | `outputSchema`   | object | No       | JSON Schema for structured output                                                                                                                                                                       |
 | `waitForResult`  | number | No       | Wait up to this many ms for the reply turn to complete and return the result directly. Max `300000` (5 min). Falls back to polling when the turn does not finish in time or needs interactive approval. |
 
-**Returns:** `{ sessionId, threadId, status, pollInterval?, result?, completedAt?, execution?, interactionState?, recommendedNextAction? }`
+**Returns:** `{ sessionId, threadId, status, pollInterval?, progress?, result?, completedAt?, execution?, interactionState?, recommendedNextAction? }`
 
 Additional orchestration hints may be present in `codex`, `codex_reply`, and `codex_check` responses:
 
 - `execution`: whether foreground waiting was requested/effective, and whether it fell back to background polling
 - `interactionState`: `working`, `waiting_input`, or `finished`
 - `recommendedNextAction`: `poll`, `respond_permission`, `respond_user_input`, or `none`
+- `progress`: normalized phase metadata, pending-action count, last observed method, and token totals when the backend exposes them
 
 ```json
 {
@@ -263,13 +298,17 @@ Additional orchestration hints may be present in `codex`, `codex_reply`, and `co
 
 ### `codex_session` — Manage sessions
 
-List, inspect, cancel, interrupt, fork sessions, or clean background terminals.
+List, inspect, cancel, interrupt, fork, batch-clean sessions, or clean background terminals.
 
-| Parameter          | Type    | Required                                                 | Description                                                                               |
-| ------------------ | ------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| `action`           | string  | Yes                                                      | `"list"`, `"get"`, `"cancel"`, `"interrupt"`, `"fork"`, or `"clean_background_terminals"` |
-| `sessionId`        | string  | For get/cancel/interrupt/fork/clean_background_terminals | Target session ID                                                                         |
-| `includeSensitive` | boolean | No                                                       | Include `cwd`/`profile`/`config`/`threadId` in `get`. Default: `false`                    |
+| Parameter          | Type     | Required                                                 | Description                                                                                          |
+| ------------------ | -------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `action`           | string   | Yes                                                      | `"list"`, `"get"`, `"cancel"`, `"interrupt"`, `"fork"`, `"clean"`, or `"clean_background_terminals"` |
+| `sessionId`        | string   | For get/cancel/interrupt/fork/clean_background_terminals | Target session ID                                                                                    |
+| `includeSensitive` | boolean  | No                                                       | Include `cwd`/`profile`/`config`/`threadId` in `get`. Default: `false`                               |
+| `statuses`         | string[] | No                                                       | For `clean` only. Terminal statuses to remove: `"idle"`, `"error"`, `"cancelled"`                    |
+| `olderThanMs`      | number   | No                                                       | For `clean` only. Only match sessions older than this many ms                                        |
+| `dryRun`           | boolean  | No                                                       | For `clean` only. Preview matches without deleting                                                   |
+| `includeDisk`      | boolean  | No                                                       | For `clean` only. Default: `true`; also remove persisted session state                               |
 
 **Returns:**
 
@@ -277,6 +316,7 @@ List, inspect, cancel, interrupt, fork sessions, or clean background terminals.
 - `action="get"` → `PublicSessionInfo` (or `SensitiveSessionInfo` when `includeSensitive=true`)
 - `action="cancel"|"interrupt"` → `{ success: true, message }`
 - `action="fork"` → `{ sessionId, threadId, status: "idle", pollInterval }`
+- `action="clean"` → `{ matchedSessionIds, removedSessionIds, removedCount, diskSessionsRemoved, dryRun }`
 - `action="clean_background_terminals"` → `{ success: true, message }`
 
 ```json
@@ -285,6 +325,7 @@ List, inspect, cancel, interrupt, fork sessions, or clean background terminals.
 { "action": "cancel", "sessionId": "sess_abc123" }
 { "action": "interrupt", "sessionId": "sess_abc123" }
 { "action": "fork", "sessionId": "sess_abc123" }
+{ "action": "clean", "statuses": ["cancelled"], "olderThanMs": 3600000 }
 { "action": "clean_background_terminals", "sessionId": "sess_abc123" }
 ```
 
@@ -299,7 +340,7 @@ Query a running session for events, respond to approval requests, or answer user
 | `cursor`                   | number   | No                                | Event cursor for incremental polling (`action="poll"`). For `respond_*`, codex-mcp applies monotonic cursor progression: `max(cursor, sessionLastCursor)`.                                                                        |
 | `maxEvents`                | number   | No                                | Keep this small. `poll` default: `1` (minimum `1`; increase only for catch-up). `respond_*` default: `0` (recommended; compact ACK, no event replay).                                                                             |
 | `responseMode`             | string   | No                                | Response shaping mode: `minimal` (default), `delta_compact`, `full`                                                                                                                                                               |
-| `pollOptions`              | object   | No                                | Optional controls: `includeEvents` (default `true`), `includeActions` (default `true`), `includeResult` (default `true`), `maxBytes` (default unlimited)                                                                          |
+| `pollOptions`              | object   | No                                | Optional controls: `includeEvents` (default `true`), `includeActions` (default `true`), `includeResult` (default `true`), `skipDeltas`, `finalOnly`, `maxBytes` (default unlimited)                                               |
 | `requestId`                | string   | For respond_permission/user_input | Request ID from `actions[]`                                                                                                                                                                                                       |
 | `decision`                 | string   | For respond_permission            | For command approvals: `"accept"`, `"acceptForSession"`, `"acceptWithExecpolicyAmendment"`, `"applyNetworkPolicyAmendment"`, `"decline"`, `"cancel"`; for file changes: `"accept"`, `"acceptForSession"`, `"decline"`, `"cancel"` |
 | `execpolicy_amendment`     | string[] | For acceptWithExecpolicyAmendment | Exec policy amendment list (required when `decision="acceptWithExecpolicyAmendment"`)                                                                                                                                             |
@@ -307,7 +348,7 @@ Query a running session for events, respond to approval requests, or answer user
 | `denyMessage`              | string   | No                                | Internal note on deny (not sent to app-server)                                                                                                                                                                                    |
 | `answers`                  | object   | For respond_user_input            | For `respond_user_input`: `question-id -> { answers: string[] }`                                                                                                                                                                  |
 
-**Returns (poll and respond\_\*):** `{ sessionId, status, pollInterval?, interactionState?, recommendedNextAction?, cursorResetTo?, events, nextCursor, actions?, result? }`
+**Returns (poll and respond\_\*):** `{ sessionId, status, pollInterval?, progress?, interactionState?, recommendedNextAction?, cursorResetTo?, events, nextCursor, actions?, result? }`
 
 ```json
 { "action": "poll", "sessionId": "sess_abc123", "cursor": 0 }
@@ -336,7 +377,11 @@ Query a running session for events, respond to approval requests, or answer user
 - If `cursor` is omitted, codex-mcp continues from that session's last consumed cursor.
 - If `responseMode` is omitted, codex-mcp uses `minimal`.
 - `pollOptions.includeEvents/includeActions/includeResult` default to `true`.
+- `pollOptions.skipDeltas=true` drops streaming delta events but still advances the cursor past them.
+- `pollOptions.finalOnly=true` omits `events[]`, focuses on `actions[]` plus terminal `result`, and advances the cursor past hidden events.
 - `pollOptions.maxBytes` is optional and enforces best-effort payload truncation (`truncated`, `truncatedFields`).
+- `progress.phase` gives a coarse execution snapshot (`starting`, `reasoning`, `acting`, `waiting_approval`, `finished`, etc.).
+- `progress.tokens` is populated when the backend exposes token counts.
 - `respond_*` defaults to compact ACK (`events: []`, no cursor advance) unless you explicitly pass `maxEvents`.
 - `poll` defaults to `maxEvents=1` to keep payloads small; increase temporarily (for example `10-20`) when you need to catch up faster.
 - If `poll` is called with `maxEvents=0`, codex-mcp treats it as `1` to avoid no-op polling loops.
@@ -345,6 +390,7 @@ Query a running session for events, respond to approval requests, or answer user
 
 Event types include `output`, `progress`, `approval_request`, `approval_result`, `result`, `error`.
 Approvals/results/errors are pinned to reduce eviction risk.
+When a turn completes, `result.text` provides a stable final assistant message. It falls back to the last completed `agentMessage` item when the backend omits `turn.output`. `result.output` remains the raw backend `turn.output` value when present.
 
 ## Approvals & User Input