@leo000001/codex-mcp 2.1.6 → 2.1.7

package/dist/index.js

@@ -340,6 +340,7 @@ var SESSION_ACTIONS = [
   "cancel",
   "interrupt",
   "fork",
+  "clean",
   "clean_background_terminals"
 ];
 var CHECK_ACTIONS = ["poll", "respond_permission", "respond_user_input"];
@@ -393,7 +394,7 @@ var DEFAULT_TERMINAL_CLEANUP_MS = 5 * 60 * 1e3;
 var CLEANUP_INTERVAL_MS = 6e4;
 
 // src/app-server/client.ts
-var CLIENT_VERSION = true ? "2.1.6" : "0.0.0-dev";
+var CLIENT_VERSION = true ? "2.1.7" : "0.0.0-dev";
 var DEFAULT_REQUEST_TIMEOUT = 3e4;
 var STARTUP_REQUEST_TIMEOUT = 9e4;
 var MAX_WRITE_QUEUE_BYTES = 5 * 1024 * 1024;
@@ -844,6 +845,31 @@ function resolveAndValidateFilePath(inputPath, baseDir, label = "path") {
   return resolved;
 }
 
+// src/utils/turn-compat.ts
+function classifyTurnCompatibilityError(err) {
+  const message = (err instanceof Error ? err.message : String(err)).toLowerCase();
+  const mentionsMinimal = message.includes("minimal");
+  const mentionsWebSearch = message.includes("web_search") || message.includes("web search");
+  const mentionsEffort = message.includes("effort") || message.includes("reasoning_effort") || message.includes("reasoning effort");
+  return mentionsMinimal && mentionsWebSearch && mentionsEffort ? "minimal_web_search" : void 0;
+}
+function compatibilityErrorMessage(kind) {
+  switch (kind) {
+    case "minimal_web_search":
+      return `Error [${"INVALID_ARGUMENT" /* INVALID_ARGUMENT */}]: effort=minimal is incompatible with the Codex web_search tool in this CLI build. Use effort=low or higher, or let codex-mcp auto-upgrade it.`;
+  }
+}
+function toFriendlyTurnCompatibilityError(err) {
+  const kind = classifyTurnCompatibilityError(err);
+  if (kind) {
+    return new Error(compatibilityErrorMessage(kind));
+  }
+  return err instanceof Error ? err : new Error(String(err));
+}
+function buildEffortFallbackWarning(from, to) {
+  return `effort=${from} is incompatible with the Codex web_search tool in this CLI build; automatically retried with effort=${to}.`;
+}
+
 // src/session/manager.ts
 var COALESCED_PROGRESS_DELTA_METHODS = /* @__PURE__ */ new Set([
   Methods.COMMAND_OUTPUT_DELTA,
@@ -851,6 +877,14 @@ var COALESCED_PROGRESS_DELTA_METHODS = /* @__PURE__ */ new Set([
   Methods.REASONING_TEXT_DELTA,
   Methods.REASONING_SUMMARY_DELTA
 ]);
+var SKIPPABLE_DELTA_METHODS = /* @__PURE__ */ new Set([
+  Methods.AGENT_MESSAGE_DELTA,
+  Methods.COMMAND_OUTPUT_DELTA,
+  Methods.FILE_CHANGE_OUTPUT_DELTA,
+  Methods.REASONING_TEXT_DELTA,
+  Methods.REASONING_SUMMARY_DELTA,
+  Methods.PLAN_DELTA
+]);
 var MAX_COALESCED_DELTA_CHARS = 16384;
 var AUTH_REFRESH_UNSUPPORTED_CODE = -32e3;
 var AUTH_REFRESH_UNSUPPORTED_MESSAGE = "account/chatgptAuthTokens/refresh unsupported: codex-mcp does not manage external ChatGPT auth tokens";
@@ -883,6 +917,22 @@ function stripShellNoise(delta) {
 }
 var MAX_WAITERS_PER_SESSION = 4;
 var MAX_WAIT_MS = 12e4;
+var EFFORT_FALLBACK_LEVEL = "low";
+var CLEANABLE_SESSION_STATUSES = ["idle", "error", "cancelled"];
+var REASONING_PROGRESS_METHODS = /* @__PURE__ */ new Set([
+  Methods.REASONING_TEXT_DELTA,
+  Methods.REASONING_SUMMARY_DELTA,
+  Methods.REASONING_SUMMARY_PART_ADDED,
+  Methods.PLAN_DELTA
+]);
+var ACTING_PROGRESS_METHODS = /* @__PURE__ */ new Set([
+  Methods.COMMAND_OUTPUT_DELTA,
+  Methods.COMMAND_TERMINAL_INTERACTION,
+  Methods.FILE_CHANGE_OUTPUT_DELTA,
+  Methods.MCP_TOOL_PROGRESS,
+  Methods.TURN_DIFF_UPDATED,
+  Methods.TURN_PLAN_UPDATED
+]);
 var SessionManager = class {
   sessions = /* @__PURE__ */ new Map();
   clients = /* @__PURE__ */ new Map();
@@ -937,7 +987,12 @@ var SessionManager = class {
         sandbox: rec.meta.sandbox,
         eventBuffer: createEventBuffer(),
         pendingRequests: /* @__PURE__ */ new Map(),
-        lastResult: rec.result
+        lastResult: rec.result,
+        lastAgentMessageText: typeof rec.result?.text === "string" ? rec.result.text : typeof rec.result?.output === "string" ? rec.result.output : void 0,
+        progressState: {
+          lastEventAt: rec.meta.lastActiveAt ?? now,
+          tokens: extractTokens(rec.result?.turn)
+        }
       };
       this.sessions.set(rec.sessionId, session);
       if (rec.lastSeq >= 0) {
@@ -972,6 +1027,26 @@ var SessionManager = class {
     } catch {
     }
   }
+  async startTurnWithCompatibilityFallback(client, turnParams) {
+    try {
+      return { turnStartResult: await client.turnStart(turnParams) };
+    } catch (err) {
+      if (turnParams.effort === "minimal" && classifyTurnCompatibilityError(err) === "minimal_web_search") {
+        try {
+          return {
+            turnStartResult: await client.turnStart({
+              ...turnParams,
+              effort: EFFORT_FALLBACK_LEVEL
+            }),
+            compatWarnings: [buildEffortFallbackWarning("minimal", EFFORT_FALLBACK_LEVEL)]
+          };
+        } catch (retryErr) {
+          throw toFriendlyTurnCompatibilityError(retryErr);
+        }
+      }
+      throw toFriendlyTurnCompatibilityError(err);
+    }
+  }
   // ── Session Creation ─────────────────────────────────────────────
   async createSession(prompt, cwd, spawnOpts, effort, advanced) {
     const sessionId = `sess_${randomUUID().slice(0, 12)}`;
@@ -993,7 +1068,9 @@ var SessionManager = class {
       sandbox: spawnOpts.sandbox,
       config: spawnOpts.config,
       eventBuffer: createEventBuffer(),
-      pendingRequests: /* @__PURE__ */ new Map()
+      pendingRequests: /* @__PURE__ */ new Map(),
+      lastAgentMessageText: void 0,
+      progressState: { lastEventAt: now }
     };
     this.sessions.set(sessionId, session);
     this.clients.set(sessionId, client);
@@ -1029,20 +1106,23 @@ var SessionManager = class {
           input.push({ type: "localImage", path: imagePath });
         }
       }
-      const turnStartResult = await client.turnStart({
+      const turnStart = await this.startTurnWithCompatibilityFallback(client, {
         threadId,
         input,
         effort,
         summary: advanced?.summary,
         outputSchema: advanced?.outputSchema
       });
+      const turnStartResult = turnStart.turnStartResult;
       const startedTurnId = extractTurnId(turnStartResult);
       if (startedTurnId) session.activeTurnId = startedTurnId;
       return {
         sessionId,
         threadId,
         status: "running",
-        pollInterval: DEFAULT_POLL_INTERVAL
+        pollInterval: DEFAULT_POLL_INTERVAL,
+        compatWarnings: turnStart.compatWarnings,
+        progress: this.getProgress(sessionId)
       };
     } catch (err) {
       session.status = "error";
@@ -1075,6 +1155,7 @@ var SessionManager = class {
       );
     }
     clearTerminalEvents(session.eventBuffer);
+    session.lastAgentMessageText = void 0;
     session.status = "running";
     session.lastActiveAt = (/* @__PURE__ */ new Date()).toISOString();
     this.persistSessionIfChanged(session);
@@ -1094,8 +1175,11 @@ var SessionManager = class {
     if (overrides?.sandbox) {
       turnParams.sandboxPolicy = toSandboxPolicy(overrides.sandbox);
     }
+    let compatWarnings;
     try {
-      const turnStartResult = await client.turnStart(turnParams);
+      const turnStart = await this.startTurnWithCompatibilityFallback(client, turnParams);
+      compatWarnings = turnStart.compatWarnings;
+      const turnStartResult = turnStart.turnStartResult;
       const startedTurnId = extractTurnId(turnStartResult);
       if (startedTurnId) session.activeTurnId = startedTurnId;
       const canOverride = client.supportsTurnOverrides;
@@ -1120,7 +1204,9 @@ var SessionManager = class {
       sessionId,
       threadId: session.threadId,
       status: "running",
-      pollInterval: DEFAULT_POLL_INTERVAL
+      pollInterval: DEFAULT_POLL_INTERVAL,
+      compatWarnings,
+      progress: this.getProgress(sessionId)
     };
   }
   // ── Session Management ───────────────────────────────────────────
@@ -1166,6 +1252,9 @@ var SessionManager = class {
   getLastResult(sessionId) {
     return this.getSessionOrThrow(sessionId).lastResult;
   }
+  getProgress(sessionId) {
+    return buildProgressInfo(this.getSessionOrThrow(sessionId));
+  }
   getPendingActionTypes(sessionId) {
     const session = this.getSessionOrThrow(sessionId);
     const actionTypes = /* @__PURE__ */ new Set();
@@ -1285,6 +1374,50 @@ var SessionManager = class {
       true
     );
   }
+  async cleanSessions(options) {
+    const statuses = new Set(options?.statuses ?? CLEANABLE_SESSION_STATUSES);
+    const olderThanMs = options?.olderThanMs;
+    const dryRun = options?.dryRun ?? false;
+    const includeDisk = options?.includeDisk ?? true;
+    const now = Date.now();
+    const matchedSessionIds = [];
+    for (const [sessionId, session] of Array.from(this.sessions.entries())) {
+      if (!statuses.has(session.status)) continue;
+      if (typeof olderThanMs === "number" && olderThanMs > 0) {
+        const lastActive = new Date(session.lastActiveAt).getTime();
+        if (!Number.isFinite(lastActive)) continue;
+        if (now - lastActive < olderThanMs) continue;
+      }
+      matchedSessionIds.push(sessionId);
+    }
+    if (dryRun) {
+      return {
+        matchedSessionIds,
+        removedSessionIds: [],
+        removedCount: 0,
+        diskSessionsRemoved: 0,
+        dryRun: true
+      };
+    }
+    let diskSessionsRemoved = 0;
+    const removedSessionIds = [];
+    for (const sessionId of matchedSessionIds) {
+      const evicted = this.evictSession(sessionId, includeDisk);
+      if (evicted.deleted) {
+        removedSessionIds.push(sessionId);
+      }
+      if (evicted.diskRemoved) {
+        diskSessionsRemoved++;
+      }
+    }
+    return {
+      matchedSessionIds,
+      removedSessionIds,
+      removedCount: removedSessionIds.length,
+      diskSessionsRemoved,
+      dryRun: false
+    };
+  }
   async forkSession(sessionId) {
     const session = this.getSessionOrThrow(sessionId);
     const originalClient = this.getClientOrThrow(sessionId);
@@ -1408,26 +1541,48 @@ var SessionManager = class {
     const buf = session.eventBuffer;
     const responseMode = options.responseMode ?? "full";
     const pollOptions = options.pollOptions;
-    const includeEvents = pollOptions?.includeEvents ?? true;
+    const finalOnly = pollOptions?.finalOnly ?? false;
+    const skipDeltas = pollOptions?.skipDeltas ?? false;
+    const includeEvents = finalOnly ? false : pollOptions?.includeEvents ?? true;
     const includeActions = pollOptions?.includeActions ?? true;
-    const includeResult = pollOptions?.includeResult ?? true;
+    const includeResult = finalOnly ? true : pollOptions?.includeResult ?? true;
     const maxBytes = pollOptions?.maxBytes;
     const effectiveCursor = cursor ?? session.lastEventCursor;
-    let events = includeEvents ? buf.events.filter((e) => e.id >= effectiveCursor) : [];
+    const unseenEvents = buf.events.filter((e) => e.id >= effectiveCursor);
+    let events = includeEvents ? unseenEvents : [];
     let cursorResetTo;
-    if (includeEvents && buf.events.length > 0) {
+    if (buf.events.length > 0) {
       const earliest = buf.events[0].id;
       if (earliest > effectiveCursor) {
         cursorResetTo = earliest;
-        events = buf.events;
+        if (includeEvents) {
+          events = buf.events;
+        }
       }
     }
     const cursorFloor = cursorResetTo ?? effectiveCursor;
-    if (events.length > maxEvents) {
-      events = events.slice(0, maxEvents);
+    let highestConsumedEventId;
+    if (includeEvents) {
+      if (skipDeltas) {
+        const filtered = [];
+        for (const event of events) {
+          highestConsumedEventId = event.id;
+          if (isSkippableDeltaEvent(event)) continue;
+          filtered.push(event);
+          if (filtered.length >= maxEvents) break;
+        }
+        events = filtered;
+      } else if (events.length > maxEvents) {
+        events = events.slice(0, maxEvents);
+        highestConsumedEventId = events.length > 0 ? events[events.length - 1]?.id : void 0;
+      } else if (events.length > 0) {
+        highestConsumedEventId = events[events.length - 1]?.id;
+      }
+    } else if (finalOnly && unseenEvents.length > 0) {
+      highestConsumedEventId = unseenEvents[unseenEvents.length - 1]?.id;
     }
     let nextCursor = clampCursorToLatest(
-      events.length > 0 ? events[events.length - 1].id + 1 : cursorFloor,
+      typeof highestConsumedEventId === "number" ? highestConsumedEventId + 1 : cursorFloor,
       buf.nextId
     );
     const actions = [];
@@ -1457,6 +1612,7 @@ var SessionManager = class {
       sessionId,
       status: session.status,
       pollInterval: pollIntervalForStatus(session.status),
+      progress: buildProgressInfo(session),
       events: events.map((event) => serializeEventForMode(event, responseMode)),
       nextCursor,
       cursorResetTo,
@@ -1483,6 +1639,10 @@ var SessionManager = class {
           result.result = void 0;
           truncatedFields.push("result");
         }
+        if (typeof result.progress !== "undefined" && payloadByteSize(result) > normalizedMaxBytes) {
+          result.progress = void 0;
+          truncatedFields.push("progress");
+        }
         if (typeof result.actions !== "undefined" && payloadByteSize(result) > normalizedMaxBytes) {
           if (session.status === "waiting_approval") {
             result.actions = compactActionsForBudget(result.actions);
@@ -1510,7 +1670,7 @@ var SessionManager = class {
         }
       }
     }
-    if (includeEvents) {
+    if (includeEvents || finalOnly) {
       session.lastEventCursor = persistMonotonicCursor(
         session.lastEventCursor,
         result.nextCursor,
@@ -1739,6 +1899,7 @@ var SessionManager = class {
     client.onNotification((method, params) => {
       session.lastActiveAt = (/* @__PURE__ */ new Date()).toISOString();
       const p = params;
+      recordProgressObservation(session, method, p);
       switch (method) {
         case Methods.THREAD_STARTED: {
           const thread = isRecord(p.thread) ? p.thread : void 0;
@@ -1782,17 +1943,21 @@ var SessionManager = class {
           if (session.status === "cancelled") break;
           const turnObj = p.turn;
           const completedTurnId = turnObj?.id ?? session.activeTurnId ?? "";
+          const rawTurnOutput = normalizeOptionalString(turnObj?.output);
+          const finalText = normalizeOptionalString(turnObj?.output) ?? session.lastAgentMessageText;
           session.status = "idle";
           session.activeTurnId = void 0;
           session.lastResult = {
             turnId: completedTurnId,
-            output: turnObj?.output,
+            text: finalText,
+            output: rawTurnOutput,
             structuredOutput: turnObj?.structuredOutput,
             turn: p.turn,
             status: turnObj?.status,
             turnError: turnObj?.error,
             completedAt: (/* @__PURE__ */ new Date()).toISOString()
           };
+          mergeProgressTokens(session, extractTokens(turnObj?.usage));
           pushEvent(
             session.eventBuffer,
             "result",
@@ -1847,6 +2012,10 @@ var SessionManager = class {
             const item = p.item;
             const itemType = item && typeof item.type === "string" ? item.type : void 0;
             const status = normalizeOptionalString(item?.status);
+            const completedItem = method === Methods.ITEM_COMPLETED || method === Methods.RAW_RESPONSE_ITEM_COMPLETED;
+            if (itemType === "agentMessage" && completedItem && status === "completed" && typeof item?.text === "string") {
+              session.lastAgentMessageText = item.text;
+            }
             const eventType = itemType === "agentMessage" || itemType === "userMessage" ? "output" : "progress";
             pushEvent(session.eventBuffer, eventType, {
               method,
@@ -1890,6 +2059,7 @@ var SessionManager = class {
       }
       session.lastActiveAt = (/* @__PURE__ */ new Date()).toISOString();
       const p = params;
+      recordProgressObservation(session, method, p);
       switch (method) {
         case Methods.COMMAND_APPROVAL: {
           const requestId = `req_${randomUUID().slice(0, 8)}`;
@@ -2176,16 +2346,7 @@ var SessionManager = class {
         this.ttlWarningEmitted.delete(id);
         this.requestCancellation(id, "Running timeout");
       } else if ((session.status === "cancelled" || session.status === "error") && age > DEFAULT_TERMINAL_CLEANUP_MS) {
-        this.ttlWarningEmitted.delete(id);
-        this.clients.get(id)?.destroy().catch((err) => {
-          console.error(
-            `[codex-mcp] Failed to destroy app-server client during cleanup: session=${id} error=${err instanceof Error ? err.message : String(err)}`
-          );
-        });
-        this.clients.delete(id);
-        this.sessions.delete(id);
-        this.lastPersistedStatus.delete(id);
-        this.ttlWarningEmitted.delete(id);
+        this.evictSession(id, true);
       } else {
         let ttlMs;
         if (session.status === "idle") {
@@ -2216,6 +2377,34 @@ var SessionManager = class {
       );
     });
   }
+  evictSession(sessionId, removeDisk) {
+    const session = this.sessions.get(sessionId);
+    if (!session) return { deleted: false, diskRemoved: false };
+    clearSessionPendingRequests(session);
+    this.notifyWaiters(sessionId);
+    this.clients.get(sessionId)?.destroy().catch((err) => {
+      console.error(
+        `[codex-mcp] Failed to destroy app-server client during cleanup: session=${sessionId} error=${err instanceof Error ? err.message : String(err)}`
+      );
+    });
+    this.clients.delete(sessionId);
+    const deleted = this.sessions.delete(sessionId);
+    this.lastPersistedStatus.delete(sessionId);
+    this.ttlWarningEmitted.delete(sessionId);
+    this.sessionNotifiers.delete(sessionId);
+    this.cancellationInFlight.delete(sessionId);
+    let diskRemoved = false;
+    if (removeDisk) {
+      try {
+        if (this.persistence) {
+          this.persistence.removeSession(sessionId);
+          diskRemoved = true;
+        }
+      } catch {
+      }
+    }
+    return { deleted, diskRemoved };
+  }
 };
 function pollIntervalForStatus(status) {
   if (status === "waiting_approval") return WAITING_APPROVAL_POLL_INTERVAL;
@@ -2230,6 +2419,114 @@ function createEventBuffer() {
     nextId: 0
   };
 }
+function buildProgressInfo(session) {
+  const storedTokens = session.progressState?.tokens;
+  const resultTokens = extractTokens(session.lastResult?.turn);
+  return {
+    phase: deriveProgressPhase(session),
+    lastEventAt: session.progressState?.lastEventAt ?? session.lastActiveAt,
+    activeTurnId: session.activeTurnId,
+    pendingActionCount: countPendingRequests(session),
+    lastMethod: session.progressState?.lastMethod,
+    percent: session.progressState?.percent,
+    tokens: mergeTokens(storedTokens, resultTokens)
+  };
+}
+function countPendingRequests(session) {
+  let count = 0;
+  for (const req of session.pendingRequests.values()) {
+    if (!req.resolved) count++;
+  }
+  return count;
+}
+function deriveProgressPhase(session) {
+  if (session.status === "waiting_approval") return "waiting_approval";
+  if (session.status === "cancelled") return "cancelled";
+  if (session.status === "error") return "error";
+  if (session.status === "idle") return "finished";
+  if (!session.activeTurnId) return "starting";
+  const lastMethod = session.progressState?.lastMethod;
+  if (typeof lastMethod === "string") {
+    if (REASONING_PROGRESS_METHODS.has(lastMethod)) return "reasoning";
+    if (ACTING_PROGRESS_METHODS.has(lastMethod)) return "acting";
+  }
+  return "running";
+}
+function recordProgressObservation(session, method, params) {
+  const next = session.progressState ?? { lastEventAt: (/* @__PURE__ */ new Date()).toISOString() };
+  next.lastEventAt = (/* @__PURE__ */ new Date()).toISOString();
+  if (method !== Methods.THREAD_TOKEN_USAGE_UPDATED) {
+    next.lastMethod = method;
+  }
+  const percent = extractPercent(params);
+  if (typeof percent === "number") next.percent = percent;
+  mergeProgressTokens(session, extractTokens(params));
+  session.progressState = next;
+}
+function mergeProgressTokens(session, tokens) {
+  if (!tokens) return;
+  const next = session.progressState ?? { lastEventAt: (/* @__PURE__ */ new Date()).toISOString() };
+  next.tokens = mergeTokens(next.tokens, tokens);
+  session.progressState = next;
+}
+function mergeTokens(base, extra) {
+  if (!base && !extra) return void 0;
+  return {
+    input: extra?.input ?? base?.input,
+    output: extra?.output ?? base?.output,
+    total: extra?.total ?? base?.total
+  };
+}
+function extractPercent(value) {
+  if (!isRecord(value)) return void 0;
+  const candidates = [value.percent, value.percentage, value.progress, value.fractionComplete];
+  for (const candidate of candidates) {
+    if (typeof candidate !== "number" || !Number.isFinite(candidate)) continue;
+    if (candidate >= 0 && candidate <= 1) return Math.round(candidate * 100);
+    if (candidate >= 0 && candidate <= 100) return candidate;
+  }
+  return void 0;
+}
+function extractTokens(value) {
+  if (!isRecord(value)) return void 0;
+  const usage = isRecord(value.usage) ? value.usage : void 0;
+  const source = usage ?? value;
+  const input = pickNumber(source, [
+    "inputTokens",
+    "input_tokens",
+    "promptTokens",
+    "prompt_tokens"
+  ]);
+  const output = pickNumber(source, [
+    "outputTokens",
+    "output_tokens",
+    "completionTokens",
+    "completion_tokens"
+  ]);
+  const total = pickNumber(source, [
+    "totalTokens",
+    "total_tokens",
+    "tokenCount",
+    "token_count",
+    "total"
+  ]);
+  if (typeof input !== "number" && typeof output !== "number" && typeof total !== "number") {
+    return void 0;
+  }
+  return { input, output, total };
+}
+function pickNumber(source, keys) {
+  for (const key of keys) {
+    const value = source[key];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return void 0;
+}
+function isSkippableDeltaEvent(event) {
+  if (!isRecord(event.data)) return false;
+  const method = event.data.method;
+  return typeof method === "string" && SKIPPABLE_DELTA_METHODS.has(method);
+}
 function clearTerminalEvents(buf) {
   buf.events = buf.events.filter((e) => e.type !== "result" && e.type !== "error");
 }
@@ -2719,6 +3016,20 @@ function buildExecutionInfo(waitForResultMs, status, fallbackReason) {
     fallbackReason: effective === "background" ? fallbackReason : void 0
   };
 }
+function coerceProgressForStatus(status, progress, options) {
+  if (!progress) return void 0;
+  let phase = progress.phase;
+  if (status === "idle") phase = "finished";
+  else if (status === "error") phase = "error";
+  else if (status === "cancelled") phase = "cancelled";
+  else if (status === "waiting_approval") phase = "waiting_approval";
+  return {
+    ...progress,
+    phase,
+    lastEventAt: options?.completedAt ?? progress.lastEventAt,
+    pendingActionCount: status === "waiting_approval" ? Math.max(progress.pendingActionCount, options?.pendingActionCount ?? 0) : status === "running" ? progress.pendingActionCount : 0
+  };
+}
 async function waitForCodexSessionForegroundResult(sessionManager, sessionId, waitForResultMs, signal) {
   const deadline = Date.now() + Math.min(waitForResultMs, 3e5);
   while (Date.now() < deadline) {
@@ -2761,6 +3072,9 @@ async function waitForCodexSessionForegroundResult(sessionManager, sessionId, wa
 }
 
 // src/tools/codex.ts
+function safeGetProgress(sessionManager, sessionId) {
+  return typeof sessionManager.getProgress === "function" ? sessionManager.getProgress(sessionId) : void 0;
+}
 async function executeCodex(args, sessionManager, serverCwd, requestSignal) {
   const cwd = resolveAndValidateCwd(args.cwd, serverCwd);
   const spawnOpts = extractSpawnOptions(args);
@@ -2775,6 +3089,10 @@ async function executeCodex(args, sessionManager, serverCwd, requestSignal) {
   const waitMs = args.advanced?.waitForResult;
   const baseResult = {
     ...startResult,
+    progress: coerceProgressForStatus(
+      "running",
+      safeGetProgress(sessionManager, startResult.sessionId) ?? startResult.progress
+    ),
     execution: buildExecutionInfo(waitMs, "running"),
     interactionState: interactionStateForStatus("running"),
     recommendedNextAction: recommendedNextActionForStatus("running")
@@ -2792,6 +3110,15 @@ async function executeCodex(args, sessionManager, serverCwd, requestSignal) {
     result: foreground.result,
     status: foreground.status,
     completedAt: foreground.completedAt,
+    compatWarnings: startResult.compatWarnings,
+    progress: coerceProgressForStatus(
+      foreground.status,
+      safeGetProgress(sessionManager, startResult.sessionId) ?? startResult.progress,
+      {
+        completedAt: foreground.completedAt,
+        pendingActionCount: foreground.pendingActionTypes?.length ?? 0
+      }
+    ),
     pollInterval: foreground.status === "waiting_approval" ? WAITING_APPROVAL_POLL_INTERVAL : foreground.status === "running" ? startResult.pollInterval : void 0,
     execution: buildExecutionInfo(waitMs, foreground.status, foreground.fallbackReason),
     interactionState: interactionStateForStatus(foreground.status),
@@ -2803,6 +3130,9 @@ async function executeCodex(args, sessionManager, serverCwd, requestSignal) {
 }
 
 // src/tools/codex-reply.ts
+function safeGetProgress2(sessionManager, sessionId) {
+  return typeof sessionManager.getProgress === "function" ? sessionManager.getProgress(sessionId) : void 0;
+}
 async function executeCodexReply(args, sessionManager, requestSignal) {
   const startResult = await sessionManager.replyToSession(args.sessionId, args.prompt, {
     model: args.model,
@@ -2817,6 +3147,10 @@ async function executeCodexReply(args, sessionManager, requestSignal) {
   const waitMs = args.waitForResult;
   const baseResult = {
     ...startResult,
+    progress: coerceProgressForStatus(
+      "running",
+      safeGetProgress2(sessionManager, startResult.sessionId) ?? startResult.progress
+    ),
     execution: buildExecutionInfo(waitMs, "running"),
     interactionState: interactionStateForStatus("running"),
     recommendedNextAction: recommendedNextActionForStatus("running")
@@ -2834,6 +3168,15 @@ async function executeCodexReply(args, sessionManager, requestSignal) {
     sessionId: startResult.sessionId,
     threadId: startResult.threadId,
     status: foreground.status,
+    compatWarnings: startResult.compatWarnings,
+    progress: coerceProgressForStatus(
+      foreground.status,
+      safeGetProgress2(sessionManager, startResult.sessionId) ?? startResult.progress,
+      {
+        completedAt: foreground.completedAt,
+        pendingActionCount: foreground.pendingActionTypes?.length ?? 0
+      }
+    ),
     pollInterval: foreground.status === "waiting_approval" ? WAITING_APPROVAL_POLL_INTERVAL : foreground.status === "running" ? startResult.pollInterval : void 0,
     result: foreground.result,
     completedAt: foreground.completedAt,
@@ -2885,6 +3228,13 @@ async function executeCodexSession(args, sessionManager) {
         };
       }
       return await sessionManager.forkSession(args.sessionId);
+    case "clean":
+      return await sessionManager.cleanSessions({
+        statuses: args.statuses,
+        olderThanMs: args.olderThanMs,
+        dryRun: args.dryRun,
+        includeDisk: args.includeDisk
+      });
     case "clean_background_terminals":
       if (!args.sessionId) {
         return {
@@ -2920,24 +3270,15 @@ function executeCodexCheck(args, sessionManager, requestSignal) {
       const maxEvents = typeof args.maxEvents === "number" ? Math.max(POLL_MIN_MAX_EVENTS, Math.floor(args.maxEvents)) : POLL_DEFAULT_MAX_EVENTS;
       const waitMs = pollOptions?.waitMs;
       if (typeof waitMs === "number" && waitMs > 0) {
-        const firstCheck = sessionManager.pollEvents(args.sessionId, args.cursor, maxEvents, {
-          responseMode,
-          pollOptions
-        });
-        const hasData = firstCheck.events.length > 0 || firstCheck.actions !== void 0 && firstCheck.actions.length > 0 || firstCheck.result !== void 0;
-        if (!hasData) {
-          const clampedWait = Math.min(waitMs, 12e4);
-          return sessionManager.waitForChange(args.sessionId, clampedWait, requestSignal).catch(() => void 0).then(
-            () => enrichCheckResult(
-              sessionManager,
-              sessionManager.pollEvents(args.sessionId, args.cursor, maxEvents, {
-                responseMode,
-                pollOptions
-              })
-            )
-          );
-        }
-        return enrichCheckResult(sessionManager, firstCheck);
+        return pollWithWait(
+          sessionManager,
+          args.sessionId,
+          args.cursor,
+          maxEvents,
+          { responseMode, pollOptions },
+          Math.min(waitMs, 12e4),
+          requestSignal
+        ).then((result) => enrichCheckResult(sessionManager, result));
       }
       return enrichCheckResult(
         sessionManager,
@@ -3058,6 +3399,31 @@ function executeCodexCheck(args, sessionManager, requestSignal) {
       };
   }
 }
+function hasVisibleData(result) {
+  return result.events.length > 0 || result.actions !== void 0 && result.actions.length > 0 || result.result !== void 0;
+}
+async function pollWithWait(sessionManager, sessionId, cursor, maxEvents, options, waitMs, signal) {
+  const deadline = Date.now() + waitMs;
+  let currentCursor = cursor;
+  while (true) {
+    const result = sessionManager.pollEvents(sessionId, currentCursor, maxEvents, options);
+    if (hasVisibleData(result)) {
+      return result;
+    }
+    if (signal?.aborted) {
+      return result;
+    }
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      return result;
+    }
+    currentCursor = result.nextCursor;
+    await sessionManager.waitForChange(sessionId, remainingMs, signal).catch(() => void 0);
+    if (signal?.aborted) {
+      return sessionManager.pollEvents(sessionId, currentCursor, maxEvents, options);
+    }
+  }
+}
 function enrichCheckResult(sessionManager, result) {
   const actionTypes = result.status === "waiting_approval" ? sessionManager.getPendingActionTypes(result.sessionId) : [];
   return {
@@ -3541,8 +3907,11 @@ function buildConfigGuideText() {
     "- `codex_check.pollOptions.includeEvents`: default `true`.",
     "- `codex_check.pollOptions.includeActions`: default `true`.",
     "- `codex_check.pollOptions.includeResult`: default `true`.",
+    "- `codex_check.pollOptions.skipDeltas`: default `false`.",
+    "- `codex_check.pollOptions.finalOnly`: default `false`.",
     "- `codex_check.pollOptions.maxBytes`: default unlimited.",
     "- `codex_check.cursor`: default is session last consumed cursor when omitted.",
+    "- `progress` is included on `codex`, `codex_reply`, and `codex_check` responses.",
     ""
   ].join("\n");
 }
@@ -3556,6 +3925,8 @@ function buildGotchasText() {
     `- Poll enforces minimum \`maxEvents=${POLL_MIN_MAX_EVENTS}\`; sending \`0\` is normalized to \`${POLL_MIN_MAX_EVENTS}\`.`,
     `- \`respond_permission\` and \`respond_user_input\` default to compact ACK with \`maxEvents=${RESPOND_DEFAULT_MAX_EVENTS}\`.`,
     "- Default response mode is `minimal`; use `full` if you need full raw event payloads.",
+    "- Use `pollOptions.skipDeltas=true` to suppress delta-heavy stream chunks while still advancing the cursor.",
+    "- Use `pollOptions.finalOnly=true` when you only care about actions + terminal result; it also advances the cursor past hidden events.",
     "- respond_* uses monotonic cursor handling: `max(cursor, sessionLastCursor)`.",
     "- If `cursorResetTo` is present, your cursor is stale (old events were evicted); restart from that value.",
     "- **Poll frequency guidance**: Adapt poll interval to task complexity and previous poll results. For `running` sessions, start at 2 minutes and increase for long tasks. Only poll frequently (~1s) when `waiting_approval`. Do NOT high-frequency poll \u2014 it wastes tokens and provides no benefit.",
@@ -3570,6 +3941,8 @@ function buildGotchasText() {
     "## Event model",
     "",
     "- Top-level `events[].type` is one of: `output`, `progress`, `approval_request`, `approval_result`, `result`, `error`.",
+    "- Terminal `result.text` provides a stable final assistant message, even when the backend omits `turn.output`; `result.output` remains the raw backend field.",
+    "- `progress` normalizes the current phase, pending action count, last observed method, and token totals when available.",
     "- Fine-grained stream semantics are in `events[].data.method` (for example command output delta, reasoning delta, turn updates).",
     '- Retryable interruptions surface as `progress` with `method="codex-mcp/reconnect"` and include retry fields.',
     "- During reconnect/retry, continue polling normally; if retries stop (`willRetry=false`), session transitions to error path.",
@@ -3586,7 +3959,8 @@ function buildGotchasText() {
     `- Idle sessions are auto-cleaned after ${msToMinutes(DEFAULT_IDLE_CLEANUP_MS)} minutes.`,
     `- Running/waiting sessions are auto-cleaned after ${msToMinutes(DEFAULT_RUNNING_CLEANUP_MS)} minutes.`,
     `- Error/cancelled sessions are retained for about ${msToMinutes(DEFAULT_TERMINAL_CLEANUP_MS)} minutes, then removed.`,
-    "- Session state is in-memory. Restarting codex-mcp drops all existing sessions.",
+    '- Use `codex_session(action="clean")` to batch-remove idle/error/cancelled sessions on demand.',
+    "- Session metadata/results are persisted for recovery; manual clean can also delete those disk artifacts.",
     "",
     "## Capacity",
     "",
@@ -3673,6 +4047,7 @@ function buildQuickstartText() {
     "```",
     "",
     "5. Continue polling until terminal status (`idle`, `error`, or `cancelled`), respecting the >=2 minute interval while `running`.",
+    "6. Read `progress.phase` / `progress.tokens` for a coarse execution snapshot without parsing raw delta events.",
     "",
     "## Cursor notes",
     "",
@@ -3681,6 +4056,13 @@ function buildQuickstartText() {
     "- Omit `responseMode`: default is `minimal`.",
     "- Use returned `nextCursor` for the next call.",
     "- If `cursorResetTo` appears, reset to that value and continue.",
+    "- If you need schema-constrained results, pass `advanced.outputSchema` (or top-level `outputSchema` in `codex_reply`) and read terminal `result.structuredOutput`.",
+    "",
+    "## Read next",
+    "",
+    "- `codex-mcp:///config`: parameter-by-parameter guide, including `advanced.*` mapping and reply overrides.",
+    "- `codex-mcp:///delegation-guide`: task presets for approvalPolicy/sandbox selection.",
+    "- `codex-mcp:///gotchas`: polling, approval timeout, cursor, and exec-mode failure modes.",
     ""
   ].join("\n");
 }
@@ -3729,6 +4111,13 @@ function buildDelegationGuideText() {
     "",
     "**Key rule:** `read-only` sandbox already prevents writes, so `approvalPolicy: 'never'` is safe with it. Avoid `untrusted` + `read-only` \u2014 every read command triggers approval for no safety gain.",
     "",
+    "## Approval policy quick guide",
+    "- `never`: no interactive prompts. Best for read-only review or tightly scoped trusted tasks.",
+    "- `on-failure`: pragmatic default for implementation work when you still want some safety rails.",
+    "- `on-request`: use when a human or outer agent will actively poll and answer approvals.",
+    "- `untrusted`: strictest interactive mode; expect frequent prompts and higher timeout sensitivity.",
+    `- Default approval timeout is ${DEFAULT_APPROVAL_TIMEOUT_MS}ms. If interactive approvals are possible, raise \`advanced.approvalTimeoutMs\` to at least 300000 so requests do not expire between normal running-session polls.`,
+    "",
     "## Quick mode: `waitForResult`",
     "For short tasks (< 2 min), set `advanced.waitForResult` to get the final result in a single tool call:",
     "```json",
@@ -3756,6 +4145,11 @@ function buildDelegationGuideText() {
     "",
     "**Approval timeout:** Default is 60s; infrequent polling causes silent auto-decline. See `codex-mcp:///gotchas`.",
     "",
+    "## Read next",
+    "- `codex-mcp:///quickstart` for the exact start -> poll -> respond loop",
+    "- `codex-mcp:///config` for parameter mapping and override persistence",
+    "- `codex-mcp:///gotchas` for timeout, cursor, and exec-mode caveats",
+    "",
     "## Security notes",
     "- `sandbox: 'read-only'` is the strongest isolation \u2014 blocks all writes regardless of approval policy",
     "- `approvalPolicy: 'never'` + `sandbox: 'workspace-write'` gives the agent full write access with no human oversight \u2014 use only for well-defined, low-risk tasks",
@@ -3943,9 +4337,13 @@ function registerResources(server, deps) {
 }
 
 // src/server.ts
-var SERVER_VERSION = true ? "2.1.6" : "0.0.0-dev";
+var SERVER_VERSION = true ? "2.1.7" : "0.0.0-dev";
 function formatErrorMessage(err) {
   const message = err instanceof Error ? err.message : String(err);
+  const compatibilityKind = classifyTurnCompatibilityError(err);
+  if (compatibilityKind) {
+    return compatibilityErrorMessage(compatibilityKind);
+  }
   const m = /^Error \[([A-Z_]+)\]:\s*(.*)$/.exec(message);
   if (m) {
     const [, code, rest] = m;
@@ -3997,6 +4395,28 @@ function createServer(serverCwd, options) {
   });
   const interactionStateSchema = z.enum(["working", "waiting_input", "finished"]);
   const nextActionSchema = z.enum(["poll", "respond_permission", "respond_user_input", "none"]);
+  const progressSchema = z.object({
+    phase: z.enum([
+      "starting",
+      "running",
+      "reasoning",
+      "acting",
+      "waiting_approval",
+      "finished",
+      "error",
+      "cancelled"
+    ]),
+    lastEventAt: z.string(),
+    activeTurnId: z.string().optional(),
+    pendingActionCount: z.number().int(),
+    lastMethod: z.string().optional(),
+    percent: z.number().optional(),
+    tokens: z.object({
+      input: z.number().optional(),
+      output: z.number().optional(),
+      total: z.number().optional()
+    }).optional()
+  });
   const setupResultShape = {
     ready: z.boolean(),
     cwd: z.string(),
@@ -4033,6 +4453,8 @@ function createServer(serverCwd, options) {
     ),
     result: z.unknown().optional().describe("Final result when waitForResult is set and session completed."),
     completedAt: z.string().optional().describe("ISO timestamp when the session completed (only when waitForResult succeeded)."),
+    compatWarnings: z.array(z.string()).optional(),
+    progress: progressSchema.optional(),
     execution: executionInfoSchema.optional(),
     interactionState: interactionStateSchema.optional(),
     recommendedNextAction: nextActionSchema.optional(),
@@ -4042,6 +4464,10 @@ function createServer(serverCwd, options) {
     includeEvents: z.boolean().optional().describe("Default: true. Include events[] in response."),
     includeActions: z.boolean().optional().describe("Default: true. Include actions[] in response."),
     includeResult: z.boolean().optional().describe("Default: true. Include result in response."),
+    skipDeltas: z.boolean().optional().describe(
+      "Default: false. Drop delta-heavy streaming events while still advancing the cursor."
+    ),
+    finalOnly: z.boolean().optional().describe("Default: false. Omit events and focus on actions + terminal result."),
     maxBytes: z.number().int().positive().optional().describe("Default: unlimited. Best-effort response payload cap in bytes."),
     waitMs: z.number().int().nonnegative().optional().describe(
       "Long-poll: block up to this many ms for new events (max 120000). Omit or 0 for immediate return."
@@ -4187,7 +4613,7 @@ function createServer(serverCwd, options) {
     "codex",
     {
       title: "Start Codex Session",
-      description: "Start session asynchronously and return `{ sessionId, threadId, status, pollInterval }`. Use `pollInterval` as a minimum hint: `running` >=120000ms (increase for long tasks), `waiting_approval` ~=1000ms.",
+      description: "Start a Codex session asynchronously and return `{ sessionId, threadId, status, pollInterval }`. Poll with `codex_check(action='poll')` until terminal status, and treat `pollInterval` as a minimum hint: `running` >=120000ms, `waiting_approval` ~=1000ms. See `codex-mcp:///quickstart` for the main loop, `codex-mcp:///config` for parameter guidance, and `codex-mcp:///delegation-guide` for approval/sandbox presets.",
       inputSchema: {
         prompt: z.string().describe("Task or question"),
         approvalPolicy: z.enum(APPROVAL_POLICIES).describe("Required enum: untrusted/on-failure/on-request/never."),
@@ -4315,18 +4741,23 @@ function createServer(serverCwd, options) {
     "codex_session",
     {
       title: "Manage Sessions",
-      description: `Session actions: list, get, cancel, interrupt, fork, clean_background_terminals.
+      description: `Session actions: list, get, cancel, interrupt, fork, clean, clean_background_terminals.
 
 - list: sessions in memory.
 - get: details. includeSensitive defaults to false; true adds threadId/cwd/profile/config.
 - cancel: terminal.
 - interrupt: stop current turn.
 - fork: clone current thread into a new session; source remains unchanged.
+- clean: batch-remove idle/error/cancelled sessions, optionally from disk too.
 - clean_background_terminals: ask app-server to clean stale background terminals for this thread.`,
       inputSchema: {
         action: z.enum(SESSION_ACTIONS),
         sessionId: z.string().optional().describe("Required for get/cancel/interrupt/fork/clean_background_terminals"),
-        includeSensitive: z.boolean().default(false).optional().describe("Include cwd/config/threadId/profile in get (default: false)")
+        includeSensitive: z.boolean().default(false).optional().describe("Include cwd/config/threadId/profile in get (default: false)"),
+        statuses: z.array(z.enum(["idle", "error", "cancelled"])).optional().describe("For clean only. Default: idle/error/cancelled."),
+        olderThanMs: z.number().int().nonnegative().optional().describe("For clean only. Remove sessions idle for at least this many ms."),
+        dryRun: z.boolean().optional().describe("For clean only. Preview matched sessions."),
+        includeDisk: z.boolean().optional().describe("For clean only. Default: true. Also remove persisted session state.")
       },
       outputSchema: {
         sessions: z.array(publicSessionInfoSchema).optional(),
@@ -4347,6 +4778,11 @@ function createServer(serverCwd, options) {
         pollInterval: z.number().int().optional().describe(
           "Recommended minimum delay before next poll (ms): running >=120000, waiting_approval ~=1000."
         ),
+        matchedSessionIds: z.array(z.string()).optional(),
+        removedSessionIds: z.array(z.string()).optional(),
+        removedCount: z.number().int().optional(),
+        diskSessionsRemoved: z.number().int().optional(),
+        dryRun: z.boolean().optional(),
         success: z.boolean().optional(),
         message: z.string().optional(),
         ...errorOutputShape
@@ -4382,7 +4818,7 @@ function createServer(serverCwd, options) {
     "codex_check",
     {
       title: "Poll & Respond",
-      description: `Poll session for events or respond to approval/input requests. Use pollInterval as a minimum hint; stop polling on terminal status (idle/error/cancelled). See codex-mcp:///gotchas for poll frequency guidance.
+      description: `Poll session for events or respond to approval/input requests. Use pollInterval as a minimum hint; stop polling on terminal status (idle/error/cancelled). WARNING: running sessions usually poll at >=120000ms, but approvalTimeoutMs defaults to ${DEFAULT_APPROVAL_TIMEOUT_MS}ms, so approvals can expire between polls unless you raise the timeout or use non-interactive policies. See codex-mcp:///quickstart and codex-mcp:///gotchas.
 
 poll: events since cursor. Default maxEvents=${POLL_DEFAULT_MAX_EVENTS}.
 respond_permission: approval decision. Default maxEvents=${RESPOND_DEFAULT_MAX_EVENTS} (compact ACK).
@@ -4394,6 +4830,7 @@ respond_user_input: user-input answers. Default maxEvents=${RESPOND_DEFAULT_MAX_
         pollInterval: z.number().int().optional().describe(
           "Recommended minimum delay before next poll (ms): running >=120000, waiting_approval ~=1000."
         ),
+        progress: progressSchema.optional(),
         interactionState: interactionStateSchema.optional(),
         recommendedNextAction: nextActionSchema.optional(),
         events: z.array(
@@ -4429,6 +4866,7 @@ respond_user_input: user-input answers. Default maxEvents=${RESPOND_DEFAULT_MAX_
         ).optional(),
         result: z.object({
           turnId: z.string(),
+          text: z.string().optional(),
           output: z.string().optional(),
           structuredOutput: z.unknown().optional(),
           turn: z.unknown().optional(),
@@ -5027,7 +5465,7 @@ var ExecClient = class extends EventEmitter2 {
 
 // src/session/persistence.ts
 import { join as join5 } from "path";
-import { mkdirSync as mkdirSync4, existsSync as existsSync7 } from "fs";
+import { mkdirSync as mkdirSync4, existsSync as existsSync7, rmSync as rmSync3 } from "fs";
 import { homedir as homedir2 } from "os";
 
 // src/persistence/atomic-writer.ts
@@ -5474,6 +5912,11 @@ var SessionPersistence = class {
       this.eventLogs.delete(sessionId);
     }
   }
+  /** Remove a persisted session directory from disk. */
+  removeSession(sessionId) {
+    this.destroySessionLog(sessionId);
+    rmSync3(join5(this.sessionsDir, sessionId), { recursive: true, force: true });
+  }
   /** Clean up: flush all logs, release lock. */
   destroy() {
     for (const log of this.eventLogs.values()) {