Skip to content

Commit e44d234

Browse files
authored
Merge pull request #949 from chrisae9/split/426-03-account-catalog
feat(codex): add account-qualified catalog entries
2 parents de7f5c8 + e8df978 commit e44d234

54 files changed

Lines changed: 2307 additions & 346 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs-site/src/content/docs/guides/codex-app-models.md‎

Lines changed: 30 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -7,20 +7,28 @@ opencodex does not patch Codex App. It writes the same Codex configuration and m
77
Codex CLI/TUI already use. Because Codex App reads that shared state, routed models can appear in the
88
App's model picker as normal Codex catalog entries.
99

10-
OpenAI entries have two stable identities: one bare native `openai` group whose Pool(default) or
11-
Direct account selection is controlled by `codexAccountMode`, and namespaced
12-
`openai-apikey/<model>` API-key transport. Changing the account mode does not change picker ids.
10+
OpenAI entries use two credential routes: native Codex login and the namespaced
11+
`openai-apikey/<model>` API-key transport. Changing `codexAccountMode` between Pool and Direct by
12+
itself does not change picker ids. When `codexAccountNamespaces` has eligible selectors whose
13+
mapped accounts still exist, however,
14+
opencodex adds separate `<selector>/<native-openai-model>` rows for the mapped accounts and hides
15+
the bare native rows from the Codex picker. Selector labels are user-chosen public names with no
16+
built-in account-role meaning. Selecting a qualified row uses only its mapped account, does not
17+
change the active Pool account, and fails closed instead of switching accounts when the target is
18+
unavailable. See [Exact Codex account selectors](/reference/configuration/routing/#exact-codex-account-selectors).
1319
API GPT-5.6 entries use
1420
1,050,000 context / 922,000 max input, and `*-pro` picker ids resolve to the base wire model with
1521
`reasoning.mode: "pro"` while logs, usage, and picker state keep the virtual id.
1622
The API catalog is fixed to exactly eight ids: `gpt-5.5`, `gpt-5.6`, Sol/Terra/Luna, and their
1723
three Pro virtual ids; there is no generic `gpt-5.6-pro` alias.
1824
Compact requests keep the selected tier but send the base model without a reasoning object.
1925

20-
Select a credential route explicitly; change Pool/Direct on the Providers page:
26+
Select the credential route represented by the picker id. Change Pool/Direct on the Providers page;
27+
`<selector>` below is a user-chosen public label mapped through `codexAccountNamespaces`:
2128

2229
```text
23-
gpt-5.6-sol # openai (Pool or Direct option)
30+
gpt-5.6-sol # bare Codex-login route via Pool or Direct
31+
<selector>/gpt-5.6-sol # stored Codex account mapped by that selector
2432
openai-apikey/gpt-5.6-sol # API key
2533
```
2634

@@ -64,7 +72,8 @@ metadata instead of an older-template approximation.
6472

6573
| Route | Picker ids and catalog metadata |
6674
| --- | --- |
67-
| Codex login (Pool or Direct) | `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` (372,000-token catalog window) |
75+
| Codex login (no eligible account selectors) | Bare native ids such as `gpt-5.6-sol`, `gpt-5.6-terra`, and `gpt-5.6-luna`; Pool or Direct is selected through `codexAccountMode`. GPT-5.6 rows use a 372,000-token catalog window. |
76+
| Codex login (eligible account selectors) | One `<selector>/<native-openai-model>` row per eligible selector and supported native model; each row uses only its mapped account, and bare native rows are hidden from the picker. Native metadata and context windows are preserved. |
6877
| OpenAI (API key) | Exactly eight namespaced rows: `gpt-5.5`, `gpt-5.6`, Sol/Terra/Luna, and the three `*-pro` virtual ids (1,050,000 context; 922,000 max input for all eight) |
6978
| OpenRouter | `openrouter/openai/gpt-5.6-sol`, `openrouter/openai/gpt-5.6-terra`, `openrouter/openai/gpt-5.6-luna` (1,050,000) |
7079
| Cursor | Static fallback includes `cursor/gpt-5.6-sol`, `cursor/gpt-5.6-terra`, and `cursor/gpt-5.6-luna` (1,000,000), plus `cursor/grok-4.5` and `cursor/grok-4.5-fast` (500,000); live account discovery decides which remain visible. |
@@ -78,13 +87,18 @@ must still be entitled to use that model.
7887

7988
## Native and routed model toggles
8089

81-
The dashboard Models page uses `disabledModels` for both model families:
90+
The dashboard Models page exposes `disabledModels` toggles for bare native ids and routed
91+
`provider/model` ids. Account-qualified `<selector>/<native-openai-model>` ids are also supported by
92+
`disabledModels`, but the dashboard does not list or toggle those exact selector rows; add them to
93+
the configuration manually:
8294

8395
- Routed ids are namespaced (`provider/model`). Disabling one excludes it from the synced catalog
8496
and `/v1/models`.
85-
- Native GPT ids are bare slugs. Disabling one keeps its catalog entry but changes
86-
`visibility` to `hide`, preserving the exact entry for a later re-enable; the bare OpenAI list
87-
shape omits it while disabled.
97+
- Account-qualified native ids use `<selector>/<native-openai-model>`. Adding one to
98+
`disabledModels` hides only that selector row.
99+
- Native GPT ids are bare slugs. Disabling one keeps its catalog entry but changes `visibility` to
100+
`hide`, preserving the exact entry for a later re-enable; it hides the bare row and every
101+
selector-qualified clone for that model from discovery.
88102
- Native rows come from the supported static set, so a disabled native model stays visible in the
89103
dashboard and can be turned back on.
90104

@@ -129,9 +143,12 @@ never advertised where it cannot be honored, and custom gateways can opt in expl
129143
## Subagent selection
130144

131145
Codex sorts picker-visible catalog entries by ascending `priority` and advertises the first five as
132-
`spawn_agent` model overrides. Pick up to five bare native ids or namespaced `provider/model` ids
133-
through `subagentModels` or the dashboard Subagents page; opencodex gives those entries priorities
134-
0-4 in the chosen order. Other models remain callable by exact id.
146+
`spawn_agent` model overrides. The dashboard Subagents page can select and save up to five bare
147+
native ids or routed `provider/model` ids. Manually configured `subagentModels` also accepts
148+
account-qualified `<selector>/<native-openai-model>` ids, but the dashboard does not offer those
149+
exact ids; saving the page replaces the list with dashboard-visible choices. opencodex assigns low
150+
catalog priorities in the selected order; when account selectors are active, bare native selections
151+
expand into selector-qualified groups. Other models remain callable by exact id.
135152

136153
The featured-model list is separate from the Dashboard's **Sub-agent delegation** selection. It
137154
controls which overrides Codex offers first; it does not select a model or trigger delegation by

‎docs-site/src/content/docs/guides/model-ordering.md‎

Lines changed: 21 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,15 @@ it earlier in the picker. The implementation records this constraint directly in
1515
`src/codex/catalog/sync.ts`.
1616

1717
opencodex therefore controls featured placement by assigning lower priorities, not by relying on
18-
array position. The relevant priorities are:
18+
array position. Unless noted otherwise, the fixed priorities and worked example below describe a
19+
catalog with no eligible Codex account selectors. With `N` eligible selectors, featured priorities
20+
use `N` as a stride: a bare native choice at configured rank `i` expands to selector rows at
21+
priorities `i * N + j`, where `j` is the selector's zero-based position; a routed choice uses
22+
`i * N`; and an exact selector-qualified choice uses `i * N + j` for its selector. Unselected routed
23+
rows are moved outside those selector groups. Codex still advertises only the first five
24+
picker-visible rows.
25+
26+
The relevant no-selector priorities are:
1927

2028
| Catalog entry | Priority | Source |
2129
| --- | ---: | --- |
@@ -57,7 +65,7 @@ only change whether a model is included.
5765

5866
## Effective picker pattern
5967

60-
With a non-empty featured list, the resulting order is:
68+
With no eligible account selectors and a non-empty featured list, the resulting order is:
6169

6270
1. Models in the exact configured `subagentModels` order, with priorities `0` through `4`.
6371
2. All remaining routed models, ordered alphabetically by provider and then model id, at priority `5`.
@@ -95,16 +103,19 @@ The picker begins as follows:
95103
| After routed models | Remaining native models | `featured.length + 100` or higher | Unselected natives are moved below the featured block |
96104

97105
The first five entries are the overrides advertised to `spawn_agent`; the rest continue in the
98-
normal picker order.
106+
normal picker order. With account selectors, the five-entry limit applies after bare native choices
107+
have expanded into selector-qualified groups.
99108

100109
## Changing the order
101110

102-
The only supported way to customize leading model order is to reorder `subagentModels`. You can do
103-
that on the dashboard's **Sub-agents** page or in the opencodex configuration. The list accepts at
104-
most five models, and its order is significant.
111+
The supported way to customize leading model order is to reorder `subagentModels`. The dashboard's
112+
**Sub-agents** page can reorder bare native and routed ids. Use `ocx agent subagents set` or edit the
113+
opencodex configuration for exact `<selector>/<native-openai-model>` choices; the dashboard does not
114+
list those choices and omits them if it saves the roster. Use at most five configured ids. With
115+
account selectors, one bare native choice can expand into multiple selector-qualified catalog rows,
116+
so configured choices and advertised rows are not necessarily one-to-one.
105117

106118
There is currently no general `modelOrder`, `providerOrder`, or priority-map setting in `OcxConfig`.
107-
The supported ordering field is `subagentModels` (`src/types.ts:238-246`); `disabledModels` and each
108-
provider's `selectedModels` are visibility fields (`src/types.ts:276-282` and
109-
`src/types.ts:439-446`). To change the rest of the picker order would require a code-level behavior
110-
change rather than a configuration edit.
119+
The supported ordering field is `subagentModels`; `disabledModels` and each provider's
120+
`selectedModels` are visibility fields. Changing the remaining picker order would require a
121+
code-level behavior change rather than a configuration edit.

‎docs-site/src/content/docs/guides/model-routing.md‎

Lines changed: 41 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,31 @@ description: How opencodex decides which provider serves a given model id.
66
When Codex asks for a model, `router.ts` resolves it to exactly one configured provider. The rules are
77
checked **in order**; the first match wins.
88

9-
For OpenAI, bare `gpt-*` ids select one `openai` provider. Its `codexAccountMode` chooses
10-
Pool(default, main plus added accounts) or Direct(current caller/main bearer) without changing the
11-
model id. `openai-apikey/<model>` explicitly selects API-key transport. The two credential routes
12-
do not fall through to one another.
9+
For OpenAI, a configured `<selector>/gpt-*` id maps through `codexAccountNamespaces` to exactly one
10+
stored Codex account before combo or provider namespaces are considered. Bare `gpt-*` ids select
11+
the canonical `openai` provider instead. Its `codexAccountMode` chooses Pool (default, main plus
12+
added accounts) or Direct (current caller/main bearer) without changing the model id.
13+
`openai-apikey/<model>` explicitly selects API-key transport. These credential routes do not fall
14+
through to one another.
1315

1416
## Precedence
1517

16-
1. **Explicit `provider/model`** — if the id contains `/` and the part before it is the name of a
18+
1. **Exact Codex account selector** — if the id is
19+
`<selector>/<native-openai-model>` and the selector is configured in `codexAccountNamespaces`,
20+
the request uses only the mapped stored account and sends the bare native model upstream.
21+
Unavailable exact targets fail closed instead of continuing through Pool, Direct, or provider
22+
routing.
23+
24+
```text
25+
side/gpt-5.6-sol → provider "openai", model "gpt-5.6-sol", account selector "side"
26+
```
27+
28+
2. **Combo id or alias** — while at least one combo is configured, a canonical `combo/<id>` or
29+
configured combo alias selects its concrete target before provider namespaces are checked. With
30+
no configured combos, a legacy physical provider literally named `combo` remains a normal
31+
provider namespace. See [Combos](/guides/combos/) for target selection and failover behavior.
32+
33+
3. **Explicit `provider/model`** — if the id contains `/` and the part before it is the name of a
1734
configured provider, that provider is used and the id is stripped to the part after the slash.
1835

1936
```text
@@ -22,29 +39,32 @@ do not fall through to one another.
2239
openrouter/openai/gpt-5.6-sol → provider "openrouter", model "openai/gpt-5.6-sol"
2340
```
2441

25-
This is the unambiguous form, and the one Codex's model picker uses for routed models.
26-
If the named provider is disabled, this explicit form throws instead of routing.
42+
This is the explicit routed-provider form, and the one Codex's model picker uses for routed
43+
models. If the same public id is a configured combo alias, rule 2 wins. If the named provider is
44+
disabled, this explicit form throws instead of routing.
45+
46+
4. **Bare native OpenAI-family id** — an id such as `gpt-*`, `o1-*`, `o3-*`, or `o4-*` uses the
47+
canonical enabled `openai` provider and its configured Pool or Direct account mode.
2748

28-
2. **A provider's `defaultModel`** — if any provider's `defaultModel` equals the id, that provider
49+
5. **A provider's `defaultModel`** — if any provider's `defaultModel` equals the id, that provider
2950
is used (id passed through unchanged).
3051

31-
3. **Built-in prefix patterns** — the id is matched against known model-family prefixes, then routed
52+
6. **Built-in prefix patterns** — the id is matched against known model-family prefixes, then routed
3253
to a configured provider of that name (or name-prefix):
3354

3455
| Prefixes | Provider |
3556
| --- | --- |
3657
| `claude-`, `claude-sonnet-`, `claude-opus-`, `claude-haiku-` | `anthropic` |
37-
| `gpt-`, `o1-`, `o3-`, `o4-` | bare ids use the configured `openai` account mode; use `openai-apikey/` for API-key transport |
3858
| `llama-`, `mixtral-`, `gemma-` | `groq` |
3959

4060
This matcher is name-based and, unlike the `defaultModel` / `models[]` scans, currently does not
4161
filter a matching provider whose `disabled` flag is true.
4262

43-
4. **A provider's `models[]`** — if no prefix rule won and an active provider lists the id in its
44-
`models[]`, that provider is used. This order matters: with an OpenAI-named provider configured,
45-
a bare `gpt-*` id reaches it before another provider's `models[]` claim.
63+
7. **A provider's `models[]`** — if no prefix rule won and an active provider lists the id in its
64+
`models[]`, that provider is used. Rule 4 already sends a bare `gpt-*` id to the canonical enabled
65+
`openai` provider before another provider's `models[]` claim can match.
4666

47-
5. **Default provider** — if nothing matched, the id is sent to `config.defaultProvider` unchanged.
67+
8. **Default provider** — if nothing matched, the id is sent to `config.defaultProvider` unchanged.
4868
(If no default provider is configured, or it is disabled, routing throws.)
4969

5070
## API keys and environment variables
@@ -81,11 +101,14 @@ Routing and catalog visibility are separate controls:
81101

82102
## Tips
83103

84-
- **Be explicit for routed models.** Prefer `provider/model` (rule 1) — it's unambiguous and
85-
matches what Codex shows in its picker after a catalog sync.
86-
- **Seed `models[]` or `defaultModel`** on a provider so short ids (rule 2/4) resolve without the
104+
- **Target a Codex account explicitly** with `<selector>/<native-openai-model>` (rule 1). That route
105+
is exact and fails closed; it never silently switches to another account.
106+
- **Be explicit for routed models.** Prefer `provider/model` (rule 3) when that exact public id is
107+
not a combo alias. It directly names the provider and matches what Codex shows in its picker after
108+
a catalog sync.
109+
- **Seed `models[]` or `defaultModel`** on a provider so short ids (rules 5/7) resolve without the
87110
`provider/` prefix.
88111
- **Prefix patterns are a convenience**, not a guarantee: they only resolve if a provider with that
89-
name (e.g. `anthropic`, `openai`, `groq`) is actually configured.
112+
name (e.g. `anthropic` or `groq`) is actually configured.
90113

91114
See [Configuration](/reference/configuration/) for the provider fields these rules read.

‎docs-site/src/content/docs/guides/sub-agent-surface.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -60,15 +60,16 @@ Custom `injectionPrompt` text can use all four placeholders:
6060

6161
| Placeholder | Replaced with |
6262
| --- | --- |
63-
| `{{model}}` | The configured `injectionModel`, or an empty string |
63+
| `{{model}}` | The effective preferred model for this request. A bare native `injectionModel` is account-qualified only when the request itself targets an explicit account selector. An unresolved or ambiguous bare value becomes an empty string; an unresolved explicit account-qualified or routed id remains unchanged |
6464
| `{{effort}}` | The configured `injectionEffort`, or an empty string |
6565
| `{{roster}}` | The resolved picker-visible, surface-compatible roster |
6666
| `{{fallback}}` | The configured global fallback guidance |
6767

6868
The built-in v2 guidance has a 700-character budget. If it would exceed the budget, opencodex drops
69-
the roster first rather than truncating the core spawn instructions. Guidance fires only when a
70-
preferred model, eligible roster, or fallback chain resolves. A custom prompt does not bypass that
71-
gate.
69+
the roster first rather than truncating the core spawn instructions. Built-in guidance fires only
70+
when a preferred model, eligible roster, or fallback chain resolves. A configured `injectionModel`
71+
is sufficient to render a custom prompt; if a bare value cannot resolve uniquely, `{{model}}`
72+
expands to an empty string.
7273

7374
On v1, opencodex injects only the upstream-style proactive delegation guidance at `max` or `ultra`
7475
effort. It does not add a preferred model, roster, fallback list, or custom prompt on v1.

0 commit comments

Comments
 (0)