AgentSkillsCN

codex-app-server-persisted

当使用 `codex app-server`（通过 stdio 实现 JSON-RPC）构建低延迟、长生命周期的 Codex 控制器时，应使用此技能——在各轮次之间保持单个 PID 活跃，同时确保 `sse_lines.jsonl` 的可观测性。

SKILL.md
--- frontmatter
name: codex-app-server-persisted
description: This skill should be used when building a low-latency, long-lived Codex controller using `codex app-server` (JSON-RPC over stdio) to keep one PID alive across turns while preserving `sse_lines.jsonl` observability.

Codex App Server Persisted

[Created by Codex: 019b74f5-a7d5-7121-ac48-8e66cd2bdc92]

Purpose

Provide a repeatable workflow to keep a single Codex process running in memory via codex app-server, and drive multi-turn interactions by sending thread/start once and turn/start repeatedly on the same threadId.

When To Use

  • •Need a warm, long-lived Codex PID to minimize turn-to-turn latency
  • •Need programmatic control over turns (JSON-RPC over stdio) instead of a TUI
  • •Need built-in observability via sse_lines.jsonl (works with app-server, not with mcp-server)

Workflow

1) Confirm requirements

  • •Identify whether the goal is: single-controller (one process drives Codex) or multi-client daemon/broker.
  • •Identify whether approvals must be supported or bypassed (risk/permissions).
  • •Identify desired observability target: centralized ~/centralized-logs/codex/sse_lines.jsonl or isolated --log-dir.

2) Start a long-lived app-server process

  • •Spawn codex app-server as a subprocess with stdin=PIPE and keep stdin open for the lifetime of the controller.
  • •Read stdout line-by-line and parse each line as JSON (JSON-RPC-like).
  • •Treat stderr as inherited or actively drained to avoid deadlocks.

3) Create a thread once, then reuse it

  • •Send initialize.
  • •Send thread/start and store threadId.
  • •For each user prompt, send turn/start with the same threadId.

4) Stream events and detect completion

  • •Expect notifications interleaved with responses on stdout.
  • •Print/collect assistant output using codex/event/agent_message_content_delta.
  • •Consider a turn complete when either:
    • •notification method codex/event/task_complete arrives, or
    • •notification method turn/completed arrives.

5) Handle approvals if enabled

  • •Detect server→client JSON-RPC requests (messages that include both method and id but no result).
  • •For V2 approval requests, handle at least:
    • •item/commandExecution/requestApproval
    • •item/fileChange/requestApproval
  • •Reply with a JSON-RPC response { "id": <same>, "result": { "decision": "accept" | "decline" } }.

6) Validate observability logging

  • •Prefer to run codex with --log-dir when isolation is needed (creates sse_lines.jsonl under that directory).
  • •Otherwise, verify the centralized ~/centralized-logs/codex/sse_lines.jsonl changes while the app-server PID stays alive.

Bundled Resources

  • •Reference guide: references/codex-app-server-persisted-process.md
  • •Starter script: scripts/app_server_persisted_repl.py