Add codex app-server ChatGPT OAuth provider path by chiggly007 · Pull Request #265 · NousResearch/hermes-agent

chiggly007 · 2026-03-02T03:01:55Z

Background

codex app-server is Codex’s stateful JSON-RPC integration surface for rich clients. Instead of calling model endpoints directly, a client talks to app-server, and app-server manages auth/account state, thread/turn lifecycle, streaming item events, approvals, and Codex config layering (~/.codex/config.toml + project .codex/config.toml in trusted repos).

Hermes historically ran through direct OpenAI-compatible client calls. This PR adds an explicit codex-app-server provider path so Hermes can operate as an app-server client.

Why this change

adds a first-class ChatGPT OAuth path via app-server auth endpoints
aligns Hermes with Codex-native thread/turn/event model
preserves existing providers and keeps this rollout opt-in (--provider codex-app-server)

What changed

Added runtime provider support for codex-app-server
Added stdio JSON-RPC app-server client (hermes_cli/codex_app_server.py)
CLI integration:
- initialize handshake
- account/read + ChatGPT login flow (if required)
- thread/start + turn/start lifecycle
- streamed deltas and final completion handling
Added app-server logging:
- stderr: ~/.hermes/logs/codex-app-server.log
- optional RPC transcript: ~/.hermes/logs/codex-app-server-rpc.log (enable with HERMES_CODEX_APP_SERVER_RPC_LOG=1)
Added session persistence for codex-app-server path in SQLite
Added hermes model support for selecting codex-app-server
Added hermes setup provider flow for codex-app-server (including model selection and keep-current detection)
Gateway integration:
- supports codex-app-server execution path (instead of attempting HTTP calls to stdio://...)
- session-scoped app-server client/thread lifecycle
- cleanup on gateway stop
Tool progress integration for codex-app-server:
- maps app-server item/started + item/completed events into Hermes progress modes (off|new|all|verbose) in CLI and gateway
Reasoning effort integration for codex-app-server:
- maps Hermes agent.reasoning_effort to app-server turn/start.effort
- mapping: xhigh -> high, minimal -> low, high|medium|low -> unchanged, none -> omit
CLI flag ambiguity fix:
- hermes chat now uses --model only (removed -m alias) to avoid model vs max_turns ambiguity

Compatibility note

Hermes currently sets these fields explicitly on app-server thread/start/turn/start requests:

model
cwd
approvalPolicy=never
sandboxPolicy=workspaceWrite+networkEnabled

If those are also configured in ~/.codex/config.toml, Hermes request-level values win for those fields. Other Codex behavior still follows app-server config layering.

For reasoning effort:

if agent.reasoning_effort is set in Hermes config, Hermes sends effort on turn/start
if unset or none, Hermes omits effort, allowing Codex defaults/config layering to apply

Tests

pytest -q tests/test_codex_app_server_cli.py
pytest -q tests/test_codex_app_server_cli.py tests/test_cli_provider_resolution.py tests/test_runtime_provider_resolution.py tests/test_auth_codex_provider.py tests/test_codex_models.py tests/test_codex_execution_paths.py
pytest -q tests/test_codex_models.py tests/test_runtime_provider_resolution.py
pytest -q tests/test_runtime_provider_resolution.py tests/test_codex_app_server_cli.py tests/gateway/test_channel_directory.py
pytest -q tests/test_codex_app_server_cli.py tests/test_runtime_provider_resolution.py tests/test_cli_provider_resolution.py tests/gateway/test_channel_directory.py

Latest targeted run in this branch: 30 passed.

- add codex-app-server runtime provider and stdio JSON-RPC client - integrate Hermes CLI auth/thread/turn flow via app-server - support ChatGPT OAuth login + existing-session detection - persist codex-app-server sessions/messages in SQLite - add stderr logging and optional RPC transcript logging - update launcher and provider/model selection UX - show explicit per-turn override notice for model/cwd/approval/sandbox - add focused tests for auth, turn lifecycle, and failure handling

teknium1 · 2026-03-05T05:45:19Z

Im a bit confused as to why we want this when this would require the codex-cli being installed, and our current doesn't rely on it at all?

chiggly007 · 2026-03-06T01:40:43Z

@teknium1 this doesn't require the codex-cli at all. This would spin up the codex app server

teknium1 · 2026-03-07T07:42:21Z

What is the app server exactly I guess I'm still confused xD

chiggly007 · 2026-03-08T15:57:52Z

The app server is Codex's backend for rich clients, not the Codex terminal UI itself. It speaks JSON-RPC over stdio by default, and it handles things like auth, conversation history, approvals, and streamed agent events. The VS Code extension uses this same surface.

In this PR, Hermes becomes a client of that backend. Hermes launches codex app-server, sends initialize, then uses thread/start and turn/start to run the conversation and read the streamed item/* and turn/* events. So the point is not "make Hermes use the Codex CLI UX". The point is "let Hermes reuse Codex's native client/runtime layer."

One important clarification, though: this path does require the local codex binary to be installed, because Hermes starts codex app-server as a subprocess. But Hermes is still the user-facing interface here; codex app-server is just the local backend/provider layer behind it.

teknium1 · 2026-03-09T02:19:24Z

Closing this — Hermes already has a working Codex OAuth path (the openai-codex provider) that talks directly to the Codex Responses API. This PR would add a second, parallel path via codex app-server that:

Requires users to install the Codex CLI as a dependency
Replaces direct API calls with a stdio JSON-RPC subprocess (app-server), adding a process management layer
Introduces an entirely different conversation model (thread/turn/event lifecycle) that doesn't align with how Hermes manages sessions
Adds 1500+ lines of complexity for functionality we already have

The existing openai-codex provider handles auth, model selection, and streaming without requiring any external CLI tools. We don't see the value in adding a second Codex integration path that burdens users with an extra install and reimplements conversation management in a fundamentally different way.

Appreciate the thorough work though — the PR is well-structured.

Phase 2 Feature 3 backend ST1. Purelymail outbound via aiosmtplib SMTP. - kora_cli/clients/purelymail_types.py: Attachment dataclass + SendResult Pydantic. - kora_cli/clients/purelymail_client.py (595 LOC): PurelymailClient + send_email_internal + sanitize/parse helpers. - tests/kora_cli/clients/test_purelymail_client.py: 40 tests. - pyproject.toml: aiosmtplib==4.0.1 runtime dep (NOT under extra — same lesson as task NousResearch#265). Key contracts pinned by tests: - Fail-CLOSED at __init__ (missing/empty/whitespace username or password). - Unset KORA_EMAIL_KORA_ALLOWED_FROM_DOMAINS = operator-config error (NOT silent allow-all). - Per-attachment 10 MiB / total batch 25 MiB caps. - Retry once on SMTP 421/450/451/452 transient + connection-tier errors; no retry on 5xx permanent / auth error. - Per-call 30s timeout. - Message-ID generated locally via email.utils.make_msgid. - Body NEVER in JSONL log (subject + recipients only). - Password absent from error/repr/log after every diverse failure mode (auth-fail / 5xx-with-echo / connection / disconnect / 421-transient). 40/40 tests pass, 270/270 cross-bucket regression.

…tigation (#125) Two-part cleanup. Part A (tsc drift): HeartbeatPanel.tsx + DashboardPage.tsx now handle all 4 fields KR-FEAT-HEARTBEAT ST2 (#118) added: unknown status arm (muted probe-pending pill + CircleDashed icon), nullable last_check_at (never checked — matching #117 convention), error field rendered as destructive <pre> in expanded view (plain text, no dangerouslySetInnerHTML), cache_warming Probes warming up… banner + dashboard headline-tone suppression. tsc -b clean. Part B (mcp_clients tests): investigation only, STOPPED per spec rule. Root cause is NOT stale assertions — all 13 failures + 5 errors collapse on ModuleNotFoundError: No module named slowapi from the unconditional import chain web_server → listeners/__init__ → listeners/webhooks → slowapi. Verified by installing --extra web: 19/19 mcp_clients tests pass. This is task NousResearch#265 (slowapi placement). Recommended 1-line fix: move slowapi to runtime deps. Will dispatch as standalone KR-SLOWAPI-DEP-FIX bucket. 3 files, +267/-14 panel + dashboard + 11 new source-pin tests. 260/260 admin-panel tests pass across 22 suites (with --extra web installed). tsc -b + vite build both clean.

Closes BOTH task NousResearch#265 (slowapi placement) AND task NousResearch#269 (mcp_clients test failures — confirmed downstream of same import-chain issue per CC#2 investigation in PR #125). - pyproject.toml: slowapi==0.1.9 moves from [web] optional-deps to runtime deps (next to aiosmtplib pin that set the precedent in PR #124). - uv.lock regenerated. - Exact-equals pin per the security policy in the dependencies-block header (2026-05-12 Mini Shai-Hulud response). Base-install verification (uv sync --frozen --extra dev, NO --extra web): mcp_clients 19/19 pass (was 13 fail + 5 err); full admin-panel regression 271/271 across 23 suites.

chiggly007 added 6 commits March 1, 2026 22:01

cli: require --model flag for chat

dee8299

docs: use hermes command in launcher usage

310e734

revert: keep launcher script aligned with main

7cc23ba

setup: add codex-app-server provider flow

c0e790e

codex-app-server: add gateway support, tool progress, and effort mapping

8171627

teknium1 closed this Mar 9, 2026

tymrtn mentioned this pull request Apr 17, 2026

feat(gateway): optional micro interrupt router for busy-session messages #11639

Open

This was referenced May 22, 2026

feat(kora): KR-FEAT-EMAIL ST1 — Purelymail outbound via SMTP rafe-walker/kora#124

Merged

chore(kora): KR-FRONTEND-CLEANUP — tsc drift + stale mcp_clients tests rafe-walker/kora#125

Merged

rafe-walker mentioned this pull request May 22, 2026

chore(kora): KR-SLOWAPI-DEP-FIX — move slowapi to runtime deps rafe-walker/kora#128

Merged

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add codex app-server ChatGPT OAuth provider path#265

Add codex app-server ChatGPT OAuth provider path#265
chiggly007 wants to merge 6 commits into
NousResearch:mainfrom
chiggly007:codex-app-server-chatgpt-oauth

chiggly007 commented Mar 2, 2026 •

edited

Loading

Uh oh!

teknium1 commented Mar 5, 2026

Uh oh!

chiggly007 commented Mar 6, 2026

Uh oh!

teknium1 commented Mar 7, 2026

Uh oh!

chiggly007 commented Mar 8, 2026

Uh oh!

teknium1 commented Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

chiggly007 commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

Why this change

What changed

Compatibility note

Tests

Uh oh!

teknium1 commented Mar 5, 2026

Uh oh!

chiggly007 commented Mar 6, 2026

Uh oh!

teknium1 commented Mar 7, 2026

Uh oh!

chiggly007 commented Mar 8, 2026

Uh oh!

teknium1 commented Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

chiggly007 commented Mar 2, 2026 •

edited

Loading