You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Operators can now set defaults for generated routed (non-native) Codex catalog rows in config.json, so ocx sync stops discarding hand edits of these fields (owner decision on #6872: the three instruction flags plus verbosity, config-first, provider limits always win, no Dashboard UI yet).
Allowlist only. The four camelCase fields map to include_skills_usage_instructions, include_apps_usage_instructions, include_plugin_usage_instructions and default_verbosity. Verbosity support is not a setting: supportVerbosity is rejected, so support always stays the provider's, model's or template's own value. The schema is strict: an unknown key (including snake_case spellings or other row fields) or a bad value drops the whole block with a load warning and a diagnostics entry, and config writes reject it (the workflowBudget pattern). Tool mode, search, truncation, auto review and identity contracts are untouched.
Precedence. Defaults are applied after routed normalization and before provider/model metadata: provider or model declaration > routedCatalogDefaults > native template value > strict-field fallback. defaultVerbosity only reaches rows that already support verbosity: the final strict pass removes default_verbosity whenever support_verbosity is false, and a test pins that a default on a model without verbosity support advertises nothing.
Scope. Ordinary routed rows only, on both derivation paths (with and without a native template), in catalog sync (convergence.ts), retained sync and the Codex-shaped /v1/models list. Native rows, account-bound native clones and Codex-forward native-capability aliases (custom openai/<native> rows that mirror the native contract) are left alone. Rows retained during a provider outage keep their values until they are regenerated. The Ultra Fast retention from fix(catalog): retain operator Ultra Fast declarations across regeneration #6819 is unchanged.
Captured once per build. Each writer resolves the block once into a frozen snapshot and passes it in; derivation never reads config. Omitting the block, or leaving it empty, reproduces today's rows exactly, and explicit false stays false.
Choices worth a look:
Field name:routedCatalogDefaults (the issue's routedDefaults could read as routing defaults).
Docs: a new "Routed row defaults" section in reference/configuration/catalog.md (EN, ES; Spanish is the only locale with that page), and a new structure/catalog-routed-defaults.md registered in the manifest with INDEX.md regenerated. structure/catalog.md and structure/config.md sit at their 600-line budget, so they gain only cross-references on existing lines.
The new tests tests/config/config-routed-catalog-defaults.test.ts and tests/codex-integration/catalog-routed-defaults.test.ts failed before the implementation (missing module; 10 catalog cases red, 3 no-op controls green). They cover unset vs explicit false, each flag, verbosity enum validation, a provider that disowns verbosity winning, native and native-alias non-interference, no-template derivation, idempotent repeated regeneration, clearing the block and strict-schema rejection.
After rebasing onto origin/dev595de1e: the new tests, both layout guards, the file-size ratchet and the Spanish docs guard pass (86 pass, 0 fail). Existing catalog/verbosity suites (codex-catalog, catalog-verbosity-default, ollama-native, kiro-adapter) pass 494, 0 fail. bun run structure:check and bun run privacy:scan pass.
Before the rebase: bun run typecheck reported no errors.
bun run test:changed hit the runner's 15-minute limit on a heavily loaded shared host (exit 124) after every selected file reported: 55,915 pass, 60 fail. An isolated rerun of the 16 files with failures left 24 failing, mostly npm/subprocess, filesystem-watch, image and live-relay timeouts that varied between runs, in files that never set the block. That they are load-related is inferred, not proven against the base commit. CI's test shards on this head are the authoritative check.
supportVerbosity removal (cf31cfc8e4, after the merge-manager review): the routed-defaults config and catalog tests pass (19 pass, 0 fail). Against the previous source the new rejection case fails. codex-catalog, catalog-verbosity-default, the Spanish docs guard, the layout guard and the file-size ratchet pass (385 pass, 0 fail). bun run typecheck, structure:check and privacy:scan pass.
CI on the previous head 555b574d1c passed all 32 checks; CI is re-running on cf31cfc8e4.
NOT RUN: full local bun run test (host load); the CI shards above cover the suite.
Checklist
Scope stays focused and avoids unrelated cleanup.
Docs or release notes were updated when needed.
Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.
Summary by CodeRabbit
New Features
Added an optional configuration for default settings on routed catalog rows, including skills, apps, plugin instructions, and verbosity.
Defaults respect explicit provider or model settings, apply only to supported routed rows, and preserve existing values when omitted. Invalid settings trigger a warning when loaded and are rejected when saving.
Documentation
Expanded configuration guidance with details on supported settings, how defaults apply, and their limitations.
Routed Codex catalog rows are regenerated on every sync, so a hand edit to
include_*_usage_instructions or the verbosity fields in opencodex-catalog.json
was lost on the next ocx sync. Add a typed top-level routedCatalogDefaults
block to config.json that sets exactly the owner-approved allowlist on every
freshly derived routed row:
- includeSkillsUsageInstructions -> include_skills_usage_instructions
- includeAppsUsageInstructions -> include_apps_usage_instructions
- includePluginUsageInstructions -> include_plugin_usage_instructions
- supportVerbosity -> support_verbosity
- defaultVerbosity ("low" | "medium" | "high") -> default_verbosity
Omitted fields keep today's derivation and explicit false stays false. The
strict schema rejects unknown fields and invalid enum values at the write
boundary; a malformed hand edit drops the whole block with a load warning
and a diagnostics entry.
Catalog writers capture the block once per build (resolveRoutedCatalogDefaults)
and pass it into buildCatalogEntriesFromObservedState; derivation never reads
config. deriveEntry applies it on both routed paths (template clone after
routed normalization, and the no-template fallback) before provider/model
metadata, so concrete provider declarations win and the final strict pass
still drops default_verbosity whenever support_verbosity is false. Native,
account-bound and Codex-forward native-capability rows are untouched, and
rows retained during a provider outage keep their values until regenerated.
Convergence, retained sync and Codex-shaped /v1/models discovery all pass
the captured value. No Dashboard UI in this change.
Closes#6872
No actionable comments were generated in the recent review.
Walkthrough
Adds the routedCatalogDefaults configuration block for selected routed catalog row fields. Validated values flow through catalog generation and model-list construction. Native rows and retained rows are excluded from default application. Tests and documentation cover configuration, precedence, and catalog behavior.
Adds the optional configuration type and strict schema for three instruction flags and defaultVerbosity. Invalid values are dropped during schema parsing, warned about during loading and diagnostics, and rejected at the write boundary. Tests cover valid and invalid values, resolution, and frozen snapshots.
Passes resolved defaults into routed row derivation and applies allowlisted values in templated and fallback paths. Provider/model metadata takes precedence; native aliases, native rows, and outage-retained rows are excluded. Tests cover derivation, convergence, retained sync, live model lists, repeat writes, and clearing the defaults.
Document the configuration and behavior structure/catalog-routed-defaults.md, structure/INDEX.md, structure/catalog.md, structure/config.md, structure/manifest.json, docs-site/src/content/docs/reference/configuration/catalog.md
Documents the configuration fields, validation, precedence, affected catalog paths, excluded rows, and reload behavior. Adds the contract document to the structure index and links to it from related catalog and configuration references.
This adds an opt-in config block for routed catalog row defaults. Omitting the block leaves behavior unchanged. No concrete merge-blocking risk was found.
Pre-merge checks: 3 · 1
Failed checks: 1 inconclusive
Check name
Status
Explanation
Resolution
Linked Issues check
Only #6872 is directly linked, and it is open. Its config-side requirements are met at reviewed head cf31cfc.
Met: - Config block: routedCatalogDefaults is added to OcxConfig (src/types/config…
Provide evidence of the owner decision that defers the Dashboard UI, such as a link to the #6872 comment. If the decision does not defer it, the PR must add a Dashboard section that reads and writes routedCatalogDefaults, with an inherit-…
Passed checks: 3 passed
Check name
Status
Explanation
Description Check
Check skipped - CodeRabbit’s high-level summary is enabled.
Title check
The title "feat(catalog): config-first routed catalog row defaults" matches the main change: a new config-driven routedCatalogDefaults block that sets instruction flags and defaultVerbosity on ord…
Out of Scope Changes check
Every changed area maps to #6872 or supports it: - Config and types: src/types/routed-catalog-defaults.ts, src/types/config.ts, src/config/schema/routed-catalog-defaults.ts, src/config/schema/config-s…
Full details: Title check
Explanation
The title "feat(catalog): config-first routed catalog row defaults" matches the main change: a new config-driven routedCatalogDefaults block that sets instruction flags and defaultVerbosity on ordinary routed catalog rows. The changeset adds the config schema, types, derivation hooks in derive-entry.ts and routed-defaults.ts, catalog writer wiring, validation diagnostics, docs, and tests, all of which fit this title. The title is specific and concise, and it follows a conventional commit style. Nothing in the changeset falls outside what the title describes.
Full details: Out of Scope Changes check
Explanation
Every changed area maps to #6872 or supports it:
Config and types: src/types/routed-catalog-defaults.ts, src/types/config.ts, src/config/schema/routed-catalog-defaults.ts, src/config/schema/config-schema.ts. These define and validate the block.
Load and diagnostics: src/config/diagnostics.ts and src/config/load-degrade.ts warn on an invalid block. Config writes reject it.
Derivation and writers: src/codex/catalog/routed-defaults.ts, derive-entry.ts, build-entries.ts, retained-sync.ts, convergence.ts, and src/server/codex-model-list.ts apply the snapshot to ordinary routed rows only.
Tests: tests/config/config-routed-catalog-defaults.test.ts and tests/codex-integration/catalog-routed-defaults.test.ts cover the requirements.
Supporting files: layout JSON, the layout fixture, structure docs, manifest, and INDEX. These register the new files for the layout guards. The fixture also adds an existing responses test to its group. It is a registration change only, with no code effect.
Docs: EN and ES catalog reference pages describe the block and its limits.
No change adds unrelated behavior. Tool mode, search, truncation, auto review, and identity fields are not touched.
Full details: Linked Issues check
Explanation
Only #6872 is directly linked, and it is open. Its config-side requirements are met at reviewed head cf31cfc.
Met:
Config block: routedCatalogDefaults is added to OcxConfig (src/types/config.ts). A strict Zod schema (src/config/schema/routed-catalog-defaults.ts) accepts only the three include_*_usage_instructions flags and defaultVerbosity. Tool, search, truncation, and identity fields are not accepted.
Durable: applyRoutedCatalogDefaults (src/codex/catalog/routed-defaults.ts) writes the values during derivation. They are not stored in the generated catalog file.
Unset fields keep current behavior. Explicit false stays false, because the check is typeof === "boolean".
Precedence: the function runs after routed normalization and before provider/model metadata. This gives provider/model > defaults > template > strict fallback, as the issue asks.
Verbosity: the final ensureStrictCatalogFields pass removes default_verbosity when support_verbosity is false. supportVerbosity was removed as a setting, per the PR description.
Native rows, account-bound clones, and Codex-forward native aliases are excluded, per the PR description.
Writers: defaults reach convergence, retained sync, and buildCodexModelList through a snapshot captured once per build.
Not established:
#6872 asks for a Dashboard page or panel with an "inherit template" option per field. The PR adds no Dashboard surface. The PR and the supplied objectives say the owner deferred the UI. That decision is not in the linked issue text supplied, so it cannot be verified here.
The issue name routedDefaults became routedCatalogDefaults. This is a naming change only.
The author reports the cited tests as passing. I did not run them. Exact-head CI status is not established.
Resolution
Provide evidence of the owner decision that defers the Dashboard UI, such as a link to the #6872 comment. If the decision does not defer it, the PR must add a Dashboard section that reads and writes routedCatalogDefaults, with an inherit-template option for each field. Also confirm that CI passes on cf31cfc.
Finishing Touches
Generate unit tests (beta)
Commit to this branch
Create a new PR
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 4 remain after this review.
Merge-manager review against the #6872 owner decision ("expose the three instruction flags plus verbosity as config-first routed-row defaults (provider limits always win). Dashboard UI later."): send back for one change.
The allowlist in src/codex/catalog/routed-defaults.ts writes five fields: the three instruction flags (includeSkillsUsageInstructions, includeAppsUsageInstructions, includePluginUsageInstructions), defaultVerbosity, and supportVerbosity. The decision names one verbosity default, and supportVerbosity is not a structural enable/scope key — it writes the row's support_verbosity capability flag. It also runs against "provider limits always win": defaults are applied before provider/model metadata, so an explicit provider declaration still wins, but for a provider that declares nothing, supportVerbosity: true turns on verbosity the row/provider never claimed. Because ensureStrictCatalogFields already strips default_verbosity whenever support_verbosity ends up false, the only thing supportVerbosity adds is the ability to override that limit.
Please drop supportVerbosity from the schema (src/config/schema/routed-catalog-defaults.ts), types, applyRoutedCatalogDefaults, docs (en + es), structure/catalog-routed-defaults.md and the tests, keeping defaultVerbosity so it applies only to rows that already support verbosity; add a test that defaultVerbosity on a row with support_verbosity: false advertises nothing. If the owner explicitly wants a support override, it needs its own decision. Everything else (no dashboard UI, routed rows only, native rows and Codex-forward native aliases untouched, invalid shapes ignored with a warning) matches the decision; the merge waits for the change, green exact-head CI and dev being green.
The #6872 decision exposes the three instruction flags plus a verbosity
default, with provider limits always winning. supportVerbosity let an
operator turn verbosity support on for a model whose provider declares
nothing, which goes past the decision. Remove it from the type, schema,
apply function, docs (en, es) and structure doc; the strict schema now
rejects it. defaultVerbosity only reaches rows that already support
verbosity: the final strict pass drops it elsewhere, and a new test pins
that a default on a model without verbosity support advertises nothing.
Merge-manager re-review of 555b574..cf31cfc against the #6872 owner decision: cleared.
supportVerbosity is removed from the type, the strict schema, applyRoutedCatalogDefaults, the English and Spanish docs and the structure doc. The block now accepts exactly the three instruction flags plus defaultVerbosity, and {supportVerbosity: true|false} is rejected as an unknown key.
defaultVerbosity never turns verbosity support on. The new test "a default on a model without verbosity support advertises nothing" checks that a restrictive template row with a default is identical to the same row without one. A provider that declares supportsVerbosity: true still receives the configured level.
The block is new on this branch, so no saved config contains supportVerbosity and nothing needs migrating.
The PR merges after the repaired dev passes its batched lane=all and the full CI for this exact head is green.
Maintainer integration of #8797 at cf31cfc (closes #6872, config-first routedCatalogDefaults), reviewed against the #6872 owner decision.
Scope: the block accepts exactly the three instruction flags plus defaultVerbosity. supportVerbosity was removed after the owner review, and the strict schema rejects it. defaultVerbosity reaches only rows that already support verbosity and never turns support on, which a test pins. Provider and model declarations always win, and there is no dashboard UI.
Gate: CI is green on this exact head, including enforce-target. Codex completed on this head with no unresolved findings, CodeRabbit reviewed this head with no actionable comments, and no thread is open. assert-mergeable-review: OK. The simulated merge onto the dev of this moment is clean, with no file over its size cap. Dev: batch lane=all 43896659099 on 8c948a4 was fully green, and only fix(images): enforce the resolved destination for video submit and poll #8838 has merged since.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Operators can now set defaults for generated routed (non-native) Codex catalog rows in
config.json, soocx syncstops discarding hand edits of these fields (owner decision on #6872: the three instruction flags plus verbosity, config-first, provider limits always win, no Dashboard UI yet).{ "routedCatalogDefaults": { "includeSkillsUsageInstructions": true, "includeAppsUsageInstructions": true, "includePluginUsageInstructions": false, "defaultVerbosity": "low" } }include_skills_usage_instructions,include_apps_usage_instructions,include_plugin_usage_instructionsanddefault_verbosity. Verbosity support is not a setting:supportVerbosityis rejected, so support always stays the provider's, model's or template's own value. The schema is strict: an unknown key (including snake_case spellings or other row fields) or a bad value drops the whole block with a load warning and a diagnostics entry, and config writes reject it (theworkflowBudgetpattern). Tool mode, search, truncation, auto review and identity contracts are untouched.routedCatalogDefaults> native template value > strict-field fallback.defaultVerbosityonly reaches rows that already support verbosity: the final strict pass removesdefault_verbositywheneversupport_verbosityis false, and a test pins that a default on a model without verbosity support advertises nothing.convergence.ts), retained sync and the Codex-shaped/v1/modelslist. Native rows, account-bound native clones and Codex-forward native-capability aliases (customopenai/<native>rows that mirror the native contract) are left alone. Rows retained during a provider outage keep their values until they are regenerated. The Ultra Fast retention from fix(catalog): retain operator Ultra Fast declarations across regeneration #6819 is unchanged.falsestaysfalse.Choices worth a look:
routedCatalogDefaults(the issue'sroutedDefaultscould read as routing defaults).src/types/routed-catalog-defaults.ts, andsrc/types/config.tsstays at 1993 lines. The two new test files are registered in domain layout shards, solayout.jsonis unchanged, leaving file-size headroom for the sibling PRs feat(images): route video_gen to images.videoProvider #8783 and feat(codex): give Luna Reserve its own setting, seeded once from authless #8788.Docs: a new "Routed row defaults" section in
reference/configuration/catalog.md(EN, ES; Spanish is the only locale with that page), and a newstructure/catalog-routed-defaults.mdregistered in the manifest withINDEX.mdregenerated.structure/catalog.mdandstructure/config.mdsit at their 600-line budget, so they gain only cross-references on existing lines.Closes #6872
Verification
tests/config/config-routed-catalog-defaults.test.tsandtests/codex-integration/catalog-routed-defaults.test.tsfailed before the implementation (missing module; 10 catalog cases red, 3 no-op controls green). They cover unset vs explicit false, each flag, verbosity enum validation, a provider that disowns verbosity winning, native and native-alias non-interference, no-template derivation, idempotent repeated regeneration, clearing the block and strict-schema rejection.origin/dev595de1e: the new tests, both layout guards, the file-size ratchet and the Spanish docs guard pass (86 pass, 0 fail). Existing catalog/verbosity suites (codex-catalog,catalog-verbosity-default,ollama-native,kiro-adapter) pass 494, 0 fail.bun run structure:checkandbun run privacy:scanpass.bun run typecheckreported no errors.bun run test:changedhit the runner's 15-minute limit on a heavily loaded shared host (exit 124) after every selected file reported: 55,915 pass, 60 fail. An isolated rerun of the 16 files with failures left 24 failing, mostly npm/subprocess, filesystem-watch, image and live-relay timeouts that varied between runs, in files that never set the block. That they are load-related is inferred, not proven against the base commit. CI's test shards on this head are the authoritative check.supportVerbosityremoval (cf31cfc8e4, after the merge-manager review): the routed-defaults config and catalog tests pass (19 pass, 0 fail). Against the previous source the new rejection case fails.codex-catalog,catalog-verbosity-default, the Spanish docs guard, the layout guard and the file-size ratchet pass (385 pass, 0 fail).bun run typecheck,structure:checkandprivacy:scanpass.555b574d1cpassed all 32 checks; CI is re-running oncf31cfc8e4.bun run test(host load); the CI shards above cover the suite.Checklist
Summary by CodeRabbit