docs(cursor): document exec policy and catalog troubleshooting - #321
Conversation
📝 WalkthroughWalkthroughDocumentation updates clarify Cursor native execution policy and add Codex catalog troubleshooting guidance covering model visibility, discovery, ordering, and cache refresh behavior. ChangesDocumentation guidance
Estimated code review effort: 1 (Trivial) | ~5 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs-site/src/content/docs/guides/codex-integration.md`:
- Around line 170-171: Reword the “Cache and ocx sync” guidance to clarify that
ocx sync rebuilds the on-disk Codex catalog and invalidates Codex’s
models_cache.json, but does not force live provider discovery. State that
gatherRoutedModels() continues using the per-provider modelCacheTtlMs cache,
with fresh discovery occurring only when that cache is stale or cleared.
In `@docs-site/src/content/docs/reference/adapters.md`:
- Around line 137-139: Update the nativeLocalExec resolver so any explicitly
provided unrecognized value disables the broader executor and never falls back
to unsafeAllowNativeLocalExec; retain legacy fallback only when nativeLocalExec
is unset. Align docs-site/src/content/docs/reference/adapters.md lines 137-139,
docs-site/src/content/docs/reference/configuration.md lines 190-191, and
docs-site/src/content/docs/reference/configuration.md lines 269-271 with this
fail-closed behavior, preserving “explicit value always wins” only for valid
explicit values.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 8b5a4dc3-6ba7-48ac-9aec-baa9fdb22b35
📒 Files selected for processing (3)
docs-site/src/content/docs/guides/codex-integration.mddocs-site/src/content/docs/reference/adapters.mddocs-site/src/content/docs/reference/configuration.md
| 5. **Cache and `ocx sync`** — live catalogs are cached for about five minutes (`modelCacheTtlMs`, | ||
| default `300000`). Run `ocx sync` to force a fresh fetch and rewrite the catalog immediately. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n -C 6 \
'modelCacheTtlMs|ocx sync|invalidate|force.?fetch|cache' .Repository: lidge-jun/opencodex
Length of output: 50378
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== docs snippet ==\n'
sed -n '160,180p' docs-site/src/content/docs/guides/codex-integration.md
printf '\n== sync references ==\n'
rg -n -C 3 '\bocx sync\b|/api/sync|modelCacheTtlMs|clearModelCache|invalidate.*cache|stale the Codex model cache|rewrite the catalog' \
docs-site src tests --glob '!**/dist/**' --glob '!**/build/**'
printf '\n== model cache implementation ==\n'
rg -n -C 4 'modelCacheTtlMs|clearModelCache|getStaleCached|setCached|cache.*ttl|ttl.*cache|invalidate.*model cache' src tests --glob '!**/dist/**' --glob '!**/build/**'Repository: lidge-jun/opencodex
Length of output: 50378
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== sync command files ==\n'
fd -a 'sync' src docs-site tests | sed -n '1,120p'
printf '\n== direct references to ocx sync command ==\n'
rg -n -C 4 'ocx sync|sync command|command.*sync|/api/sync|stale the Codex model cache' src docs-site tests
printf '\n== model-cache file outline ==\n'
fd -a 'model-cache' src testsRepository: lidge-jun/opencodex
Length of output: 50377
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== candidate model-cache file ==\n'
fd -a 'model-cache.ts' src
printf '\n== candidate sync implementation files ==\n'
fd -a 'sync' src | sed -n '1,120p'Repository: lidge-jun/opencodex
Length of output: 315
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n -C 5 '/api/sync|stale the Codex model cache|clearModelCache\(|modelCacheTtlMs: 0|sync.*model cache|refresh.*catalog' \
src docs-site testsRepository: lidge-jun/opencodex
Length of output: 50377
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n -C 4 'clearModelCache|setCached\(|getStaleCached\(|modelCacheTtlMs|sync' src/codex src/cli src | head -n 200Repository: lidge-jun/opencodex
Length of output: 12880
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== src/codex/sync.ts ==\n'
sed -n '1,140p' src/codex/sync.ts
printf '\n== src/codex/model-cache.ts ==\n'
sed -n '1,180p' src/codex/model-cache.ts
printf '\n== refreshCodexModelCatalog references ==\n'
rg -n -C 6 'refreshCodexModelCatalog|syncModelsToCodex|clearModelCache\(' src/codex src/server src/cliRepository: lidge-jun/opencodex
Length of output: 31145
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== src/codex/refresh.ts ==\n'
sed -n '1,220p' src/codex/refresh.ts
printf '\n== sync/catalog call sites ==\n'
rg -n -C 4 'syncCatalogModels|refreshCodexModelCatalog|gatherRoutedModels|modelCacheTtlMs' src/codex src/server src/cli
printf '\n== model-cache usage in refresh path ==\n'
rg -n -C 4 'clearModelCache\(|setCached\(|getFreshCached\(|getStaleCached\(' src/codex src/serverRepository: lidge-jun/opencodex
Length of output: 23832
Clarify ocx sync here. src/codex/sync.ts only rebuilds the on-disk Codex catalog and invalidates Codex’s models_cache.json; it still calls gatherRoutedModels() through the normal per-provider cache path, so a warm modelCacheTtlMs entry can be reused instead of forcing a live fetch. Reword this to say ocx sync refreshes the catalog and Codex cache, while live provider discovery still honors the TTL unless the provider cache is stale or cleared.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs-site/src/content/docs/guides/codex-integration.md` around lines 170 -
171, Reword the “Cache and ocx sync” guidance to clarify that ocx sync rebuilds
the on-disk Codex catalog and invalidates Codex’s models_cache.json, but does
not force live provider discovery. State that gatherRoutedModels() continues
using the per-provider modelCacheTtlMs cache, with fresh discovery occurring
only when that cache is stale or cleared.
Source: Path instructions
| and `desktopExecutor` integrations have separate opt-ins; `nativeLocalExec: "on"` enables the | ||
| broader built-in executor and bypasses Codex approval/sandbox semantics, and legacy | ||
| `unsafeAllowNativeLocalExec: true` remains equivalent only when `nativeLocalExec` is unset. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Make legacy precedence fail closed for invalid selectors.
The documentation says the legacy boolean applies only when nativeLocalExec is unset and that explicit values always win, but the resolver falls back to the legacy opt-in for any unrecognized value. A malformed selector combined with unsafeAllowNativeLocalExec: true can therefore enable the broader executor unexpectedly.
docs-site/src/content/docs/reference/adapters.md#L137-L139: keep the documented precedence only after the resolver treats invalid explicit values as fail-closed.docs-site/src/content/docs/reference/configuration.md#L190-L191: align the field contract with the resolver’s actual invalid-value behavior.docs-site/src/content/docs/reference/configuration.md#L269-L271: retain “explicit value always wins” only after invalid values no longer fall through to the legacy flag.
📍 Affects 2 files
docs-site/src/content/docs/reference/adapters.md#L137-L139(this comment)docs-site/src/content/docs/reference/configuration.md#L190-L191docs-site/src/content/docs/reference/configuration.md#L269-L271
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs-site/src/content/docs/reference/adapters.md` around lines 137 - 139,
Update the nativeLocalExec resolver so any explicitly provided unrecognized
value disables the broader executor and never falls back to
unsafeAllowNativeLocalExec; retain legacy fallback only when nativeLocalExec is
unset. Align docs-site/src/content/docs/reference/adapters.md lines 137-139,
docs-site/src/content/docs/reference/configuration.md lines 190-191, and
docs-site/src/content/docs/reference/configuration.md lines 269-271 with this
fail-closed behavior, preserving “explicit value always wins” only for valid
explicit values.
Source: Path instructions
|
Maintainer validation complete. This preserves #303 author attribution, is rebased onto current |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a2c8b3895a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 3. **`liveModels: false` with empty `models`** — when live discovery is off and `models` is empty or | ||
| omitted, opencodex exposes no routed models for that provider. |
There was a problem hiding this comment.
This is not true for every provider: when a built-in provider such as kiro or moonshot omits models, gatherRoutedModels() calls enrichProviderFromRegistry(), which restores that provider's registry-seeded models before honoring liveModels: false; openai-apikey can also add its trusted registry rows even when models is explicitly empty. Users troubleshooting those providers will therefore be told to expect an empty catalog while routed entries remain visible. Please limit this guidance to providers without registry seeds and document the built-in/OpenAI exceptions.
Useful? React with 👍 / 👎.
| - **`"on"` (trusted-local opt-in)** — always allows Cursor-native local execution for this provider. | ||
| Use it only for a trusted local experiment on a host where every data-plane caller is trusted. |
There was a problem hiding this comment.
In normal Codex requests that advertise apply_patch, this mode does not always allow every listed native operation: LiveCursorTransport.run() sets rejectNativeFileMutations, and handleCursorNativeExec() then rejects Cursor-native write and delete calls even when the exec policy resolves to "on". The unconditional wording can make operators expect a fully enabled native executor while mutations continue to fail; document that write and delete remain delegated to apply_patch whenever that client tool is available.
Useful? React with 👍 / 👎.
| The legacy `unsafeAllowNativeLocalExec: true` boolean is still accepted and is equivalent to | ||
| `nativeLocalExec: "on"` when `nativeLocalExec` is unset; an explicit `nativeLocalExec` value always | ||
| wins. Prefer `nativeLocalExec` for new configs. |
There was a problem hiding this comment.
The newly documented precedence makes the existing provider guide incorrect for users who first copy this page's example with nativeLocalExec: "off": guides/providers.md still tells them to enable execution by adding only unsafeAllowNativeLocalExec: true, but the explicit "off" wins and execution remains disabled. The Japanese, Korean, Russian, and Chinese provider/reference pages repeat the same unconditional legacy instruction and omit the new modes, so update those pages to use nativeLocalExec: "on" or clearly explain the precedence.
AGENTS.md reference: AGENTS.md:L78-L79
Useful? React with 👍 / 👎.
| If a model is missing from Codex, or the catalog order/visibility looks wrong, check in order: | ||
|
|
||
| 1. **`selectedModels`** on the provider — a non-empty allowlist exposes only those ids to Codex; |
There was a problem hiding this comment.
A provider-level disabled: true is another direct cause of every model from that provider disappearing: gatherRoutedModels() removes disabled providers before discovery, filtering, and catalog generation. Because this new section tells users with missing models to check these items in order but never mentions the provider's disabled switch, they can exhaust the checklist without finding the actual cause. Add the provider-level switch before selectedModels in the sequence.
Useful? React with 👍 / 👎.
The previous commit (79cafcb) placed useRef(t) and tRef.current = t inside a useEffect body. React 19 throws error lidge-jun#321 (Invalid hook call) when a hook runs outside the component body, which crashed the root and left the login screen blank. Move useRef + ref assignment to the component top level, next to where t is defined. The probe effect still reads tRef.current so it sees the latest translations while keeping an empty dep array.
Summary
Current-
devreplacement for #303, preserving Diego Cantarero as the commit author.nativeLocalExecmodes and legacy precedence;codex-sandboxbehavior and loopback trust boundary;Validation
git diff --checkSupersedes #303.
Summary by CodeRabbit
nativeLocalExecsetting, including its available modes, security implications, and configuration examples.unsafeAllowNativeLocalExecoption remains supported when the new setting is unset.