AgentSkillsCN

patch-codex-app-server-observability

当 Codex 以应用服务器模式运行时，尤其在 VS Code 扩展使用时，应使用此技能，确保 Codex 能够输出集中的可观测性日志（sse_lines.jsonl）。

SKILL.md
--- frontmatter
name: patch-codex-app-server-observability
description: This skill should be used when ensuring Codex emits centralized observability logs (sse_lines.jsonl) while running in app-server mode, especially when used by the VS Code extension.

Patch Codex App Server Observability

[Created by Codex: 019be564-39d9-7b12-a4cf-fb7a7f1af223 2026-01-22]

Purpose

Enable or restore centralized observability (writes sse_lines.jsonl) for the long-lived codex app-server process used by VS Code.

When to Use

  • •VS Code Codex “New Thread” works but subsequent turns stop producing events in ~/centralized-logs/codex/sse_lines.jsonl.
  • •codex app-server runs fine but the process never opens sse_lines.jsonl.
  • •A regression between Codex versions removed app-server logging.
  • •The user sets "chatgpt.cliExecutable" to a custom codex binary and expects the same observability behavior as terminal runs.

Workflow

  1. •Confirm which codex binary VS Code is running:
    • •Check settings for "chatgpt.cliExecutable" in:
      • •~/Library/Application Support/Code/User/settings.json
      • •<repo>/.vscode/settings.json
    • •Record the resolved path and codex --version.
    • •If the path points to a local repo build, ask the user to confirm the intended repo/branch/commit.
  2. •Confirm the running app-server process and whether it is logging:
    • •Find the VS Code-started PID (search for codex app-server).
    • •Check whether the process has the log file open:
      • •lsof -p <pid> | rg 'sse_lines\\.jsonl|centralized-logs/codex'
  3. •Choose the patch location (prefer least invasive):
    • •Preferred (matches codex-cli 0.77.0 behavior): initialize observability in the root CLI when launching codex app-server (no sub-subcommand).
    • •Alternative: initialize observability inside the codex-app-server crate (requires a decision on how to choose/configure log dir).
  4. •Implement the root CLI patch:
    • •In codex-rs/cli/src/main.rs, before launching the server:
      • •resolve the effective log dir (root --log-dir if set, otherwise default via observability::resolve_log_dir)
      • •call observability::init(log_dir)
    • •Keep failure non-fatal (print a warning and continue).
    • •Keep SIGTERM handler behavior consistent.
  5. •Build and validate:
    • •cargo build -p codex-cli --release
    • •Ensure VS Code points at the rebuilt binary if "chatgpt.cliExecutable" is set.
  6. •Restart VS Code to pick up the new binary:
    • •VS Code keeps codex app-server alive; reload the window (or kill the app-server PID and let the extension respawn it).
  7. •Re-test:
    • •Confirm lsof shows sse_lines.jsonl opened by the app-server process.
    • •Run multiple turns in one thread; confirm the JSONL file continues to append across turns.

Evidence to Include in RCA

  • •The exact codex path VS Code ran (bundled binary vs "chatgpt.cliExecutable" override).
  • •The codex app-server command line and PID.
  • •Whether lsof shows sse_lines.jsonl open.
  • •Any stderr warnings emitted when observability initialization fails.