feat: add gpt-5.1-codex-max support with xhigh reasoning and persistent logging

[riatzukiza]

Summary

• Codex Max Integration: Add gpt-5.1-codex-max as new default model with exclusive xhigh reasoning effort
• Persistent Logging: Implement always-on file logging with rolling log files and optional console output
• Comprehensive Testing: Full test coverage for model normalization, reasoning effort handling, and logging behavior

Key Changes

• Model Support: Normalize all codex-max variants to canonical gpt-5.1-codex-max
• Reasoning Efforts: Add xhigh reasoning exclusive to Codex Max, auto-downgrade for other models
• Configuration: Update sample configs to use Codex Max as default
• Documentation: Refresh all docs to reflect new flagship model and logging behavior
• Logging: Always write to ~/.opencode/logs/codex-plugin/ with optional console mirroring

Files Modified

• Core: lib/request/request-transformer.ts, lib/types.ts, lib/logger.ts
• Config: config/full-opencode.json, config/minimal-opencode.json
• Tests: Comprehensive updates across all test files
• Docs: AGENTS.md, README.md, CONFIG_FIELDS.md, TESTING.md
• Scripts: scripts/test-all-models.sh

Testing

• All existing tests pass
• New tests cover Codex Max normalization and xhigh reasoning
• Logger tests verify persistent file logging behavior
• Integration tests confirm reasoning effort auto-downgrade

Breaking Changes

• Default model in minimal config changes from gpt-5.1-codex to gpt-5.1-codex-max
• New xhigh reasoning effort type added to TypeScript interfaces

[coderabbitai]

Caution

Review failed

The pull request is closed.

Summary by CodeRabbit

Release Notes

• New Features

  • Added new logging functions: logInfo, logWarn, and logError for explicit message logging.
  • Added "xhigh" reasoning effort level for more granular control over reasoning behavior.
  • Added support for Codex Max model variant with specialized reasoning configurations.

• Improvements

  • Upgraded logging system to use asynchronous rolling logs with automatic rotation and queue-based flushing for improved performance.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Walkthrough

The PR introduces an asynchronous rolling log system replacing synchronous file I/O, adds Codex Max model variant support with xhigh reasoning effort granularity, and updates test infrastructure to support the new logging mechanics and model handling.

Changes

Cohort / File(s)	Summary
Logging System Refactor lib/logger.ts, test/logger.test.ts	Replaced synchronous file I/O with asynchronous rolling log system using queue-based flushing, size-based rotation, and structured log entries; added logInfo, logWarn, logError exports; introduced DEBUG_FLAG_ENABLED and CONSOLE_LOGGING_ENABLED gating; reorganized test suite with comprehensive beforeEach setup and expanded coverage for rotation, queue overflow, and error handling.
Model Variant & Reasoning Configuration lib/request/request-transformer.ts, lib/types.ts	Added Codex Max (gpt-5.1-codex-max) variant detection and normalization in request transformation; introduced xhigh reasoning effort level; extended reasoning config branching to handle Codex Max-specific effort downgrade logic; updated type unions in ConfigOptions and ReasoningConfig.
Test Infrastructure Updates test/plugin-config.test.ts, test/prompts-codex.test.ts, test/prompts-opencode-codex.test.ts, test/request-transformer.test.ts	Expanded fs module mocks to include appendFileSync alongside existing sync operations; fixed TypeScript type casting for global.fetch; added Codex Max variant test coverage and wrapper function for transformRequestBody; reorganized request-transformer tests to cover fork-aware cache key derivation and model-specific defaults.

Sequence Diagram(s)

sequenceDiagram
    participant App as Application Code
    participant LogQueue as Log Queue
    participant FileIO as Async File I/O
    participant Console as Console
    participant OpencodeClient as OpencodeClient

    App->>LogQueue: enqueueLog(entry)
    LogQueue->>LogQueue: Check queue size
    alt Queue Full
        LogQueue->>Console: Warn queue overflow
        LogQueue->>LogQueue: Drop oldest entry
    else Queue OK
        LogQueue->>LogQueue: Add entry
    end

    App->>FileIO: triggerFlush() or size limit reached
    FileIO->>FileIO: maybeRotate()
    alt Rotation Needed
        FileIO->>FileIO: rotateLogs() - rename, remove old
    end
    FileIO->>FileIO: appendFile() to rolling log
    FileIO->>OpencodeClient: emit(entry) if available
    alt OpencodeClient unavailable
        FileIO->>Console: Log failure
    end

    App->>FileIO: flushRollingLogsForTest()
    FileIO->>FileIO: Drain queue
    FileIO->>FileIO: Rotate if needed
    FileIO-->>App: Promise resolved

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~70 minutes

• lib/logger.ts: Dense async state management with queue mechanics, file rotation, size tracking, and error routing. Multiple interacting concerns (rotation logic, queue overflow, gating flags).
• Test reorganization: Significant refactor across four test files with new mock structures and expanded coverage patterns for rotation and queue behavior.
• Request transformer logic: Additional branching for Codex Max variant with conditional effort downgrades requires tracing through control flow.
• Type changes: Straightforward but their impact on the request transformer logic requires verification in context.

Areas requiring extra attention:

• Queue overflow handling and dropped entry notifications
• Log rotation triggering and file cleanup semantics (especially rename/rm ordering)
• Codex Max effort downgrade logic interaction with user-provided reasoning effort values
• Test mock reset state between tests to prevent false positives/negatives

Possibly related issues

• Feature: Add support for GPT-5.1-Codex-Max model #26: The Codex Max normalization (gpt-5.1-codex-max) and xhigh reasoning effort additions directly implement the model variant and granular reasoning configuration requested in this feature issue.

Possibly related PRs

• Device/stealth #20: Both PRs modify lib/request/request-transformer.ts for request body transformation and lib/logger.ts for logging behavior, suggesting coordinated changes to the same core transformation and logging pipeline.

Poem

📝 Logs now roll asynchronously with grace,
Queue by queue, they find their place,
Codex Max shines in reasoning's light,
xhigh effort climbs to new height,
Rotation spins as files take flight. ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the three main changes: Codex Max model support, xhigh reasoning, and persistent logging, directly matching the PR's core objectives.
Description check	✅ Passed	The description comprehensively covers the PR's scope including model integration, logging implementation, testing approach, and breaking changes, all aligned with the actual changeset.

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 774bcfa and c9b80f8.

⛔ Files ignored due to path filters (2)

• docs/configuration.md is excluded by none and included by none
• spec/logging-rotation-async-io.md is excluded by none and included by none

📒 Files selected for processing (2)

• lib/logger.ts (3 hunks)
• test/logger.test.ts (1 hunks)

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 058f596 and d451b3d.

⛔ Files ignored due to path filters (10)

• AGENTS.md is excluded by none and included by none
• CHANGELOG.md is excluded by none and included by none
• README.md is excluded by none and included by none
• config/full-opencode.json is excluded by none and included by none
• config/minimal-opencode.json is excluded by none and included by none
• docs/development/CONFIG_FIELDS.md is excluded by none and included by none
• docs/development/TESTING.md is excluded by none and included by none
• scripts/test-all-models.sh is excluded by none and included by none
• spec/gpt-51-codex-max.md is excluded by none and included by none
• spec/persistent-logging.md is excluded by none and included by none

📒 Files selected for processing (9)

• lib/logger.ts (3 hunks)
• lib/request/request-transformer.ts (4 hunks)
• lib/types.ts (2 hunks)
• test/codex-fetcher.test.ts (1 hunks)
• test/logger.test.ts (1 hunks)
• test/plugin-config.test.ts (1 hunks)
• test/prompts-codex.test.ts (3 hunks)
• test/prompts-opencode-codex.test.ts (2 hunks)
• test/request-transformer.test.ts (3 hunks)

🧰 Additional context used

🧬 Code graph analysis (4)

test/prompts-codex.test.ts (1)

lib/cache/session-cache.ts (1)

• codexInstructionsCache (76-76)

test/request-transformer.test.ts (2)

lib/request/request-transformer.ts (3)

• normalizeModel (307-344)
• getReasoningConfig (376-444)
• transformRequestBody (839-974)

lib/types.ts (2)

• RequestBody (131-153)
• UserConfig (24-31)

test/logger.test.ts (1)

lib/logger.ts (5)

• LOGGING_ENABLED (7-7)
• logRequest (58-74)
• logDebug (76-78)
• logWarn (84-86)
• logInfo (80-82)

lib/logger.ts (2)

lib/utils/file-system-utils.ts (1)

• getOpenCodePath (22-24)

lib/constants.ts (1)

• PLUGIN_NAME (7-7)

🔇 Additional comments (23)

lib/logger.ts (5)

8-10: LGTM: Debug flag logic updated correctly.

The debug flag logic now enables debug mode when either DEBUG_CODEX_PLUGIN or ENABLE_PLUGIN_REQUEST_LOGGING is set, and console logging is controlled separately. This provides flexible logging control.

---

22-28: LGTM: RollingLogEntry structure is well-defined.

The RollingLogEntry type provides a clean structure for both file persistence and transmission to the client. The optional extra field allows for flexible metadata attachment.

---

80-90: LGTM: New logging functions provide convenient API.

The new logInfo, logWarn, and logError functions provide a convenient public API that properly normalizes data and delegates to the emit function.

---

92-117: Verify error handling in client log forwarding.

The async log forwarding to loggerClient.app.log() uses void and catches errors, logging them via logToConsole. This prevents the forwarding from blocking the main flow, but be aware that if the console logging is disabled and the client fails, the log entry will only be persisted to file.

This is the intended behavior based on the design, but verify that this matches your requirements:

1. File logging always happens (if enabled)
2. Client forwarding is best-effort
3. Failures fall back to console only if console logging is enabled or level is warn/error

---

169-178: LGTM: appendRollingLog handles errors gracefully.

The function properly creates the log directory, appends entries as newline-delimited JSON, and falls back to console logging on failure.

test/prompts-codex.test.ts (2)

9-9: LGTM: Filesystem mock extended for rolling logs.

The test properly extends the filesystem mock to include appendFileSync, aligning with the new rolling log functionality in lib/logger.ts. The mock is correctly cleared in beforeEach.

Also applies to: 19-20, 25-26, 44-44

---

48-48: LGTM: Type-safe global fetch assignment.

Using (global as any).fetch resolves TypeScript type constraints while maintaining the test's functionality.

test/prompts-opencode-codex.test.ts (1)

13-16: LGTM: Comprehensive filesystem mock setup.

The test file properly mocks the node:fs module with both default and named exports, covering all filesystem operations used by the logger. Mocks are correctly reset in beforeEach.

Also applies to: 24-35, 70-73

test/plugin-config.test.ts (1)

12-12: LGTM: Mock updated for consistency.

The appendFileSync mock is added to maintain consistency with other test files and support the new rolling log functionality.

lib/types.ts (1)

37-37: LGTM: Type definitions extended for xhigh reasoning effort.

The xhigh option is properly added to both ConfigOptions.reasoningEffort and ReasoningConfig.effort as a literal union type, maintaining type safety.

Also applies to: 47-47

test/request-transformer.test.ts (3)

65-70: LGTM: Comprehensive codex-max normalization tests.

The tests verify that various codex-max input patterns (gpt-5.1-codex-max, gpt51-codex-max, gpt-5-codex-max, codex-max) all normalize to the canonical gpt-5.1-codex-max.

---

134-158: LGTM: gpt-5.1-codex-max reasoning config tests cover key scenarios.

The test suite verifies:

• Default medium effort for codex-max
• xhigh is allowed for codex-max
• minimal/none downgrades to low for codex-max
• xhigh downgrades to high for non-codex-max models

---

785-813: LGTM: Integration tests validate xhigh handling in transformation.

The tests verify that transformRequestBody correctly preserves xhigh for codex-max and downgrades it to high for other models, ensuring the reasoning configuration is properly applied end-to-end.

test/logger.test.ts (8)

3-15: Mock setup looks correct.

The addition of appendFileSync to the filesystem mocks properly supports the new rolling log functionality. The mock structure is consistent between the fsMocks object and the vi.mock registration.

---

17-20: Home directory mock is appropriate.

Using a fixed /mock-home path provides predictable assertions for log file paths throughout the test suite.

---

22-37: Test setup is thorough and correct.

The module-level spy setup combined with beforeEach cleanup provides proper test isolation. Using vi.resetModules() is the right approach for testing environment-dependent module state like LOGGING_ENABLED.

---

50-69: Test coverage for logRequest is comprehensive.

This test properly verifies that logRequest writes both a stage-specific JSON file and appends to the rolling log. The assertions check paths, encoding, payload structure, and the absence of console output.

Minor: The test name "by default" could be more specific since it explicitly mocks existsSync to return false, but this is a nitpick.

---

71-79: logDebug test correctly verifies silent rolling log behavior.

The test confirms that logDebug appends to the rolling log without console output when logging is not explicitly enabled, which matches the expected behavior.

---

81-88: logWarn test validates console output behavior.

Correctly verifies that warnings are emitted to console even without environment variable overrides, which is appropriate for the warn level.

---

90-102: logInfo test properly validates environment-dependent console mirroring.

The test correctly uses vi.resetModules() to reload the logger module with different environment state. This is the right pattern for testing the LOGGING_ENABLED constant behavior.

---

104-115: Persistence failure test validates error resilience.

This test properly verifies that when stage file persistence fails, the system logs a warning and continues with the rolling log append. This ensures partial failures don't completely break logging.

lib/request/request-transformer.ts (2)

307-344: Codex‑max normalization order and heuristics look correct

The hasCodexMax detection plus early if (hasCodexMax) branch ensures all common codex-max/codexmax variants (with dots, spaces, underscores, or suffixes) are canonicalized to gpt-5.1-codex-max before the generic codex branches run, without changing behavior for existing codex/codex‑mini mappings. This segment looks sound and backward‑compatible.

---

376-444: xhigh reasoning effort handling for Codex Max is consistent and contained

The new isCodexMax flag and requestedXHigh gate cleanly enforce that xhigh only survives for Codex Max, while all other models transparently downgrade xhigh to high. The Codex‑max branch’s clamping of minimal/none to low preserves the prior “never below low for codex family” behavior, and other codex / non‑codex branches remain unchanged. I don’t see any logic gaps or regressions here.

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

test/prompts-codex.test.ts (1)

52-56: The review concern is valid—fix the test isolation violation.

Verification confirms that delete (global as any).fetch permanently removes the global fetch, breaking test isolation. While other tests in the suite set fetch fresh in their beforeEach (so they won't immediately fail), this approach violates proper cleanup patterns and can cause issues with test execution order or when tests run in different contexts.

The codebase already demonstrates the better pattern: test/auth.test.ts preserves and restores console.error using the same technique suggested here. Apply the fix as indicated in the review comment.

lib/request/request-transformer.ts (1)

290-356: Fix: xhigh is not a valid reasoning effort level per official Codex docs

Blocker found: The code accepts and may return "xhigh" for Codex Max models, but official Codex CLI config and OpenAI/Azure reasoning guidance specify effort values as "minimal", "low", "medium" (default), or "high" only.

The xhigh check downgrade non-Codex Max to high, but Codex Max can still receive and return xhigh unchecked (lines 309-311 and return statement). Either:

• Remove the xhigh branch entirely and reject/normalize it to high for all models, or
• Confirm xhigh is a valid internal value and normalize it to high before returning.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d451b3d and 4406707.

⛔ Files ignored due to path filters (1)

• README.md is excluded by none and included by none

📒 Files selected for processing (6)

• lib/logger.ts (4 hunks)
• lib/request/request-transformer.ts (4 hunks)
• lib/types.ts (2 hunks)
• test/codex-fetcher.test.ts (1 hunks)
• test/plugin-config.test.ts (1 hunks)
• test/prompts-codex.test.ts (3 hunks)

🧰 Additional context used

🧬 Code graph analysis (2)

test/prompts-codex.test.ts (1)

lib/cache/session-cache.ts (1)

• codexInstructionsCache (76-76)

lib/logger.ts (2)

lib/utils/file-system-utils.ts (1)

• getOpenCodePath (22-24)

lib/constants.ts (1)

• PLUGIN_NAME (7-7)

🪛 GitHub Actions: CI

lib/logger.ts

[error] 126-126: TS2367: This comparison appears to be unintentional because the types '"debug" | "info"' and '"error"' have no overlap.

🪛 GitHub Check: Lint & Typecheck

lib/logger.ts

[failure] 126-126:
This comparison appears to be unintentional because the types '"debug" | "info"' and '"error"' have no overlap.

🔇 Additional comments (5)

test/codex-fetcher.test.ts (1)

55-65: Re-seeding createCodexHeadersMock after reset keeps tests stable

Re‑applying the Headers-returning implementation after mockReset() ensures every test still sees a concrete Headers instance even if previous tests adjusted the mock. No blockers here; this setup is robust for the Codex fetch flow tests.

test/prompts-codex.test.ts (1)

5-27: FS and fetch mocks look consistent with new logging behavior

The new appendFileSync mock and its export wiring mirror the existing fs mocks and give you a clean hook for rolling-log writes. Clearing it (and the other fs mocks) plus explicitly assigning (global as any).fetch in beforeEach keeps state isolated per test. No issues here.

Also applies to: 39-45, 48-50

test/plugin-config.test.ts (1)

8-14: Extending the node:fs mock with appendFileSync is correct

Adding appendFileSync to the mocked node:fs export aligns this test harness with code paths that append to files (e.g., logging). It avoids unexpected “undefined is not a function” failures without changing existing expectations.

lib/types.ts (1)

52-65: Blocker: Public documentation cannot be verified in this environment

The xhigh addition is properly implemented in lib/types.ts (lines 53, 63) and tested in test/request-transformer.test.ts with correct model-specific behavior (preserved for gpt-5.1-codex-max, downgraded for others). However, I cannot access this repository's public documentation or configuration schemas to confirm that "xhigh" is now documented as a valid reasoningEffort value.

You must verify that any external docs, configuration schemas, or API documentation this project publishes have been updated to include "xhigh" as a valid value alongside the code changes.

lib/request/request-transformer.ts (1)

221-258: Codex Max model normalization is correct and well-tested

Tests confirm all expected variants normalize properly to the canonical "gpt-5.1-codex-max": including 'gpt-5.1-codex-max', 'gpt51-codex-max', 'gpt-5-codex-max', and 'codex-max'. The hasCodexMax heuristic correctly detects both hyphenated (codex-max) and compact (codexmax) forms, and early return prevents interference with mini/family branches. Reasoning config tests also confirm Codex Max behavior (defaults to medium effort, allows xhigh, downgrades minimal/none to low).

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e3144f8 and 774bcfa.

📒 Files selected for processing (1)

• lib/logger.ts (4 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

lib/logger.ts (2)

lib/utils/file-system-utils.ts (1)

• getOpenCodePath (22-24)

lib/constants.ts (1)

• PLUGIN_NAME (7-7)

🔇 Additional comments (3)

lib/logger.ts (3)

80-90: Clean public API addition.

The new logInfo, logWarn, and logError functions provide a well-structured logging interface that routes through the unified emit path.

---

92-117: Well-structured unified emit path.

The refactored emit function provides a clean separation of concerns: persist to rolling log, forward to remote client (with fallback), and console output. The error handling appropriately uses logToConsole directly to avoid recursion.

---

125-128: Past TypeScript error successfully resolved.

The redundant type guard level !== "error" has been removed from line 126, resolving the TS2367 compilation error flagged in the previous review. The current logic correctly narrows the type and handles test environment filtering appropriately.