Skip to content

Commit 7fd141f

Browse files
authored
Merge pull request #3260 from lidge-jun/codex/promote-preview-24000902
release: promote dev to preview for v2.40.0-preview.20260902
2 parents 75f3895 + 84b48d6 commit 7fd141f

975 files changed

Lines changed: 45919 additions & 2742 deletions

File tree

Some content is hidden

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

‎.github/workflows/dev-version-bump.yml‎

Lines changed: 25 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -14,18 +14,35 @@ name: Dev version bump
1414
# sign-off that a bot cannot supply. Until that merge the red persists. This converts a
1515
# forgotten chore into a queued, reviewable change - not into an automatic repair.
1616
#
17-
# A `release` event resolves this workflow file from the repository DEFAULT branch
18-
# (`main`), not from `dev` - the same trap documented in cleanup-closed-pr-branches.yml.
19-
# So merging this file to `dev` installs it but arms nothing; it first fires after an
20-
# ordinary dev -> main promotion carries it there.
17+
# WHY THIS IS CALLED, NOT TRIGGERED. It used to listen for `release: published`, and in
18+
# that form it ran ZERO times across v2.37.0, v2.38.0 and v2.39.0 - every one of those
19+
# bumps was still opened by hand (#3045, #3076, #3127). The workflow was not broken; the
20+
# event never existed. `release.yml` creates the GitHub release with
21+
# `GH_TOKEN: ${{ github.token }}`, and GitHub does not start workflow runs from events
22+
# raised by the default `GITHUB_TOKEN`. A `release: published` listener therefore cannot
23+
# observe a release this repository publishes itself, no matter which branch it sits on.
24+
#
25+
# The fix keeps the credential surface unchanged: no PAT, no app token, no
26+
# `contents: write` on the release job. `release.yml` CALLS this workflow directly after
27+
# a successful publish, so the run is a child of the release run instead of a reaction to
28+
# an event that is never delivered.
29+
#
30+
# A `workflow_call` body resolves from the CALLER's ref, and `release.yml` only ever runs
31+
# on `main` or `preview` (its own branch gate). So this file must be on `main` to take
32+
# effect - the same promotion requirement the old comment described, now for a different
33+
# reason.
2134
#
2235
# There is deliberately no `workflow_dispatch`: a branch-selected manual run executes
2336
# THAT branch body with `contents: write`. Re-drive a missed run by running
2437
# `bun scripts/bump-dev-version.ts <released> package.json` locally and opening the pull
2538
# request normally.
2639
on:
27-
release:
28-
types: [published]
40+
workflow_call:
41+
inputs:
42+
released-version:
43+
description: "The tag that just published, e.g. v2.39.0"
44+
required: true
45+
type: string
2946

3047
permissions: {}
3148

@@ -69,7 +86,7 @@ jobs:
6986
- name: Decide the version dev should carry
7087
id: decide
7188
env:
72-
RELEASED_VERSION: ${{ github.event.release.tag_name }}
89+
RELEASED_VERSION: ${{ inputs.released-version }}
7390
run: |
7491
set -euo pipefail
7592
bun scripts/bump-dev-version.ts "${RELEASED_VERSION}" package.json
@@ -88,7 +105,7 @@ jobs:
88105
env:
89106
GH_TOKEN: ${{ github.token }}
90107
NEXT_VERSION: ${{ steps.decide.outputs.version }}
91-
RELEASED_VERSION: ${{ github.event.release.tag_name }}
108+
RELEASED_VERSION: ${{ inputs.released-version }}
92109
run: |
93110
set -euo pipefail
94111

‎.github/workflows/release.yml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,41 @@ concurrency:
3636
cancel-in-progress: false
3737

3838
jobs:
39+
# Move `dev` past the version that just published.
40+
#
41+
# This is a CALL, not a `release: published` listener. The release is created with
42+
# `github.token`, and GitHub does not start workflow runs from events that token
43+
# raises - so a listener cannot observe a release this repository publishes itself. In
44+
# that form it ran ZERO times across v2.37.0, v2.38.0 and v2.39.0 while every one of
45+
# those bumps was opened by hand (#3045, #3076, #3127).
46+
#
47+
# `needs: publish` means this is skipped unless the publish job succeeded, so a failed
48+
# publish or a failed release creation never opens a bump pull request; the explicit
49+
# condition only adds the dry-run case. The called workflow declares its own
50+
# `contents: write` / `pull-requests: write` for its own job, so nothing here gains
51+
# write access.
52+
#
53+
# Both channels call this, and the double-call is safe because `bump-dev-version.ts`
54+
# compares against what `dev` already carries. In the usual train `dev` is already at
55+
# the stable core when the preview publishes, so that call returns `changed=false`
56+
# ("dev already carries 2.40.0, which is ahead of the published 2.40.0-preview.*") and
57+
# every later step is gated on that output. The stable call returns `changed=true` and
58+
# opens the one pull request. A preview publishing while `dev` is genuinely behind
59+
# still bumps it, which is the point.
60+
#
61+
# It is declared FIRST in this file, ahead of the jobs it depends on, because
62+
# tests/ci-workflows.test.ts splits the workflow on `- name:` and reads each `run:`
63+
# block to the start of the next one when it checks that dispatch inputs never
64+
# interpolate into shell source. A job declared between two steps lands inside that
65+
# window and reads as shell. Job order in YAML carries no execution meaning - `needs`
66+
# does - so declaring it before its own dependency costs nothing.
67+
bump-dev-version:
68+
needs: publish
69+
if: ${{ inputs.dry-run != true }}
70+
uses: ./.github/workflows/dev-version-bump.yml
71+
with:
72+
released-version: v${{ inputs.version }}
73+
3974
validate-dispatch:
4075
runs-on: ubuntu-latest
4176
permissions:

‎README.md‎

Lines changed: 49 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -14,27 +14,55 @@ npm install -g @bitkyc08/opencodex
1414
ocx start # proxy + dashboard on localhost:10100
1515
```
1616

17-
<table align="center">
18-
<tr>
19-
<td width="50%" align="center">
20-
<img src="assets/claude-code-models.gif" alt="Claude Code running a routed model through opencodex — the status bar shows gpt-5.6-luna-medium as the active model" width="410"><br>
21-
<sub><b>Claude Code, running any model.</b><br>The picker is stock Claude Code. The brain behind it isn't.</sub>
22-
</td>
23-
<td width="50%" align="center">
24-
<img src="https://raw.githubusercontent.com/lidge-jun/opencodex/main/assets/demo.gif" alt="opencodex demo — running a task in the Codex app on a routed non-OpenAI model" width="410"><br>
25-
<sub><b>Codex, running any model.</b><br>Pick a provider and go — same workflow, different brain.</sub>
26-
</td>
27-
</tr>
28-
<tr>
29-
<td width="50%" align="center">
30-
<img src="https://raw.githubusercontent.com/lidge-jun/opencodex/main/assets/claude-desktop-subagent.gif" alt="Claude Desktop answering as Claude Opus 4.8, then dispatching a GPT-5.6 Sol subagent through opencodex" width="410"><br>
31-
<sub><b>Claude Desktop, running any model.</b><br>Opus answers, then hands the task to a GPT-5.6 Sol subagent.</sub>
32-
</td>
33-
<td width="50%" align="center">
34-
<img src="https://raw.githubusercontent.com/lidge-jun/opencodex/main/assets/grok-build-subagent.gif" alt="Grok Build running GPT-5.6 Sol through opencodex and calling a Kimi K3 subagent" width="410"><br>
35-
<sub><b>Grok Build, running any model.</b><br>Sol drives the session and calls a Kimi K3 subagent.</sub>
36-
</td>
37-
</tr>
17+
<table>
18+
<tr>
19+
<td width="50%" valign="middle">
20+
21+
### Claude Code, running any model
22+
23+
The picker is stock Claude Code. The brain behind it isn't.
24+
25+
</td>
26+
<td width="50%">
27+
<img src="assets/claude-code-models.gif" alt="Claude Code running a routed model through opencodex — the status bar shows gpt-5.6-luna-medium as the active model" width="100%">
28+
</td>
29+
</tr>
30+
<tr>
31+
<td width="50%" valign="middle">
32+
33+
### Codex, running any model
34+
35+
Pick a provider and go — same workflow, different brain.
36+
37+
</td>
38+
<td width="50%">
39+
<img src="https://raw.githubusercontent.com/lidge-jun/opencodex/main/assets/demo.gif" alt="opencodex demo — running a task in the Codex app on a routed non-OpenAI model" width="100%">
40+
</td>
41+
</tr>
42+
<tr>
43+
<td width="50%" valign="middle">
44+
45+
### Claude Desktop, running any model
46+
47+
Opus answers, then hands the task to a GPT-5.6 Sol subagent.
48+
49+
</td>
50+
<td width="50%">
51+
<img src="https://raw.githubusercontent.com/lidge-jun/opencodex/main/assets/claude-desktop-subagent.gif" alt="Claude Desktop answering as Claude Opus 4.8, then dispatching a GPT-5.6 Sol subagent through opencodex" width="100%">
52+
</td>
53+
</tr>
54+
<tr>
55+
<td width="50%" valign="middle">
56+
57+
### Grok Build, running any model
58+
59+
Sol drives the session and calls a Kimi K3 subagent.
60+
61+
</td>
62+
<td width="50%">
63+
<img src="https://raw.githubusercontent.com/lidge-jun/opencodex/main/assets/grok-build-subagent.gif" alt="Grok Build running GPT-5.6 Sol through opencodex and calling a Kimi K3 subagent" width="100%">
64+
</td>
65+
</tr>
3866
</table>
3967

4068
<p align="center">
Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# 000 — Research: remote hub mode (evidence base)
2+
3+
Unit: 260827_remote_hub · Branch: codex/remote-hub-design · Status: research
4+
5+
## Motivation (user request, 2026-08-27)
6+
7+
Run one ocx as a central HUB (Oracle VM / Mac mini / Docker — any machine), keep every
8+
provider key, OAuth credential, and shared config there, and let other machines connect
9+
with only a pointer + token ("ocx connect <tailnet-dns>"). The dashboard on a client
10+
machine must still work at localhost:10100 with a two-plane split: shared pages operate
11+
the hub, machine pages operate local file integration. Explicit constraint from the user:
12+
today a Tailscale-bound GUI is unusable for some operations even WITH the admin token —
13+
the design must fix remote GUI operability without collapsing the consent boundary.
14+
15+
## In-repo evidence (verified 2026-08-27 on dev @ 8b1b65b8d)
16+
17+
- Non-loopback bind forces the data token: `isApiAuthRequired` returns true whenever the
18+
bind hostname is not loopback (src/server/auth-cors.ts:260-262), and startup refuses a
19+
public bind without a configured data credential.
20+
- The remote-GUI limitation is a deliberate restriction, not an unreported weakness, and
21+
it is already visible in shipped public code: `issueGuiSession` returns null when
22+
`isApiAuthRequired(config)` is true and additionally requires a loopback Host
23+
(src/server/management-auth.ts, `issueGuiSession`). The published dashboard guide
24+
states the same boundary in user terms.
25+
26+
The consequence is a capability gap rather than an exposure: on a remote bind the
27+
principal `gui-session` is unobtainable, so consent-bearing routes requiring
28+
`ctx.principal === "gui-session"` (src/server/management/sidebar-routes.ts:42,
29+
src/server/management/codex-prompt-routes.ts:298) answer 403 even to the admin token.
30+
That 403 is correct and stays correct — the admin token must never be able to spend the
31+
user's consent (AGENTS.md user-consent boundary). What is missing is any path for a
32+
*browser* to mint a session remotely, which is what this unit designs.
33+
34+
Stated precisely: the current behavior fails closed. Nothing here describes a way to
35+
obtain authority one should not have, so this note is a design rationale rather than
36+
pre-disclosure material, and `AGENTS.md`'s scratch-space rule for unfixed defects does
37+
not apply to it. Anything in this unit that WOULD describe an unfixed exploitable
38+
weakness belongs in scratch space, not in `devlog/`.
39+
- `managementRequestOrigin` returns null for a non-loopback Host when apiAuth is NOT
40+
required (src/server/auth-cors.ts:118-129); when apiAuth IS required it derives the
41+
origin from the request, which a TLS terminator breaks (http observed vs https public).
42+
- The GUI attaches credentials only same-origin: `needsApiAuth` refuses absolute
43+
cross-origin URLs (gui/src/api.ts:53-60). A two-plane GUI therefore needs an explicit
44+
multi-target API layer, not a base-URL swap.
45+
- The GUI needs a secure context in places: `crypto.subtle.digest` at
46+
gui/src/log-conversation-id.ts:26, `navigator.clipboard` at
47+
gui/src/oauth-health-display.ts:133 (with execCommand fallback).
48+
- Injector already supports non-loopback targets: dedicated provider block with
49+
`env_key = "OPENCODEX_API_AUTH_TOKEN"` and `model_catalog_json` requiring a LOCAL
50+
absolute path (src/codex/inject.ts:186-247, 622+).
51+
- `GET /api/catalog` and `GET /api/client-config` already exist behind management auth
52+
(src/server/management/model-routes.ts:334-420).
53+
- Headless OAuth exists: `oauthOpenBrowser: false` (src/oauth/open-browser-choice.ts) and
54+
`POST /api/oauth/login/code` (src/server/management/oauth-account-routes.ts:208).
55+
- Allowlist-listener precedent: the unauthenticated loopback listener enumerates exactly
56+
the routes it serves (src/server/index.ts, loopbackRouteAllowed) — the machine-plane
57+
listener should copy this failure mode (default-404).
58+
- Token-file delivery precedent: `OCX_API_TOKEN_FILE` (src/lib/service-secrets.ts,
59+
src/service.ts:1571+).
60+
- CLI already talks to the management API over HTTP with injectable baseUrl
61+
(src/cli/runtime-api.ts, RuntimeApiDeps.baseUrl) — client-mode remote management
62+
commands are a URL + credential change, not a new client.
63+
64+
## External evidence (Luna swarm, 3 lanes, sources opened 2026-08-27)
65+
66+
Peer proxies separate UI sessions from master keys:
67+
- LiteLLM: LITELLM_MASTER_KEY for API/admin, separate UI login minting expiring
68+
virtual keys; per-user/per-device virtual keys with budgets, central key custody.
69+
https://docs.litellm.com.cn/docs/proxy/ui , virtual_keys.md / access_control.md in
70+
BerriAI/litellm-docs (opened 2026-08-27).
71+
- sub2api: admin web UI uses JWT session; automation uses a separate global Admin API
72+
Key (x-api-key). https://github.com/Wei-Shaw/sub2api (opened 2026-08-27).
73+
- One API broken-access-control reports (#2410, #2423) show central key custody makes
74+
route-level authz the main defense.
75+
76+
Tailscale transport facts (official docs, verified dates in page footers):
77+
- `tailscale serve` = tailnet-only reverse proxy to a localhost backend; injects
78+
Tailscale-User-* identity headers; backend must bind loopback or headers are
79+
spoofable. https://tailscale.com/docs/features/tailscale-serve
80+
- `tailscale cert` issues public CA certs only for the ts.net FQDN (not bare MagicDNS
81+
short names); names land in Certificate Transparency logs.
82+
https://tailscale.com/docs/how-to/set-up-https-certificates
83+
- Funnel is public-internet exposure (ports 443/8443/10000) — out of scope here.
84+
85+
Browser platform facts (MDN/WHATWG/IETF, opened 2026-08-27):
86+
- Plain-HTTP non-localhost origins are NOT secure contexts: no crypto.subtle, no
87+
async clipboard, Secure cookies unavailable. http://localhost IS potentially
88+
trustworthy. https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Secure_Contexts
89+
- Header-token SPAs avoid ambient-cookie CSRF but still need exact-origin allowlists
90+
and Origin checks on mutations (WHATWG Fetch; RFC 9700 OAuth BCP).
91+
- RFC 8628 device flow is the reference pattern for headless-hub OAuth; ocx's
92+
oauthOpenBrowser:false + /api/oauth/login/code is already equivalent in shape.
93+
94+
## Design consequences (carried into 010)
95+
96+
1. Two credential worlds stay separate: data-plane admission (client machines) vs
97+
management (admin token / gui-session). Peers (LiteLLM, sub2api) validate this split.
98+
2. Remote GUI needs a NEW session-issuance path, not a weakening of requireManagementAuth:
99+
the loopback-only refusal in issueGuiSession is the single gate to generalize.
100+
3. HTTPS via tailscale serve against a loopback-only management ingress is the
101+
recommended browser path; plain-HTTP tailnet operation must exist as a documented
102+
opt-in because usability on a private tailnet was the user's explicit complaint.
103+
4. localhost:10100 client GUI + direct-to-hub shared plane is cross-origin; the hub
104+
needs management CORS for an allowlisted client origin, or the client listener
105+
relays. Both appear in 010 with the relay constrained to a fixed target.
Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# 001 — Interview record (2026-08-28)
2+
3+
Answers captured from the maintainer (session 01a0439a, I-phase round 2):
4+
5+
- **Scope: ALL 6 phases, full implementation including hardening (P6).** Delivery as a
6+
stacked PR chain grown from this branch (codex/remote-hub-design is the stack base;
7+
each phase PR targets the previous head; retarget to dev as parents land —
8+
DEV-STACK / enforce-target child rules).
9+
- Q2 (plain-HTTP pairing): accepted — rung 4 ships in Phase 2 with rung 3.
10+
- Q3 (per-client keys): recommendation accepted BUT see new usage requirement below,
11+
which pulls toward auto-issuing per-client keys at connect.
12+
- Q4 (URL split): accepted — separate managementUrl allowed, /readyz advertises it.
13+
- Q5 (remote session TTL): accepted — renewable long-lived remote sessions.
14+
- Q6 (hub local integration): accepted — hub does not inject locally by default.
15+
- Q7 (Claude): launcher-scope first confirmed; maintainer notes it is machine-local
16+
anyway — clean separation is the requirement, not persistent integration.
17+
- Q8 (deployment): **dogfood on clisu-oracle as part of this work**, AND the protocol
18+
must tolerate release-build peers: a released client against a dev-build hub (and
19+
the reverse) must interoperate "어느정도" — i.e. protocol-version negotiation in
20+
/readyz is a hard requirement, not polish (Phase 1 scope).
21+
- **NEW requirement (usage attribution):** the client GUI usage page should reflect
22+
"my machine's usage" while connected, and after `ocx disconnect` the GUI (back in
23+
standalone mode) shows the local proxy's own usage again. Feasibility confirmed in
24+
code: usage attempts already persist `apiKeyId` for configured-key admissions
25+
(src/server/management/api-key-usage.ts:78-89, admissionFields in
26+
src/server/auth-cors.ts:369-375), so a per-client filtered usage view is a query
27+
over existing data — it requires the machine to authenticate with its OWN key,
28+
which is why connect should default to per-client key issuance.
29+
30+
Open contradiction (to resolve this round): shared-token-allowed (Q3 answer) vs
31+
per-machine usage view (new requirement) — attribution is keyed on apiKeyId, so a
32+
shared token collapses all machines into one bucket.
33+
34+
## Round 3 answers (2026-08-28)
35+
36+
- **Q-A = a (auto-issue per-client key at connect).** Storage question resolved in
37+
code: the key is NEVER written to config.toml (env_key contract); it lands in the
38+
existing owner-only token file (serviceApiTokenFilePath, src/lib/service-secrets.ts:5,
39+
0600 + ACL hardening) which the shim already reads into OPENCODEX_API_AUTH_TOKEN when
40+
the env is empty (src/codex/shim.ts:699-701 unix, :1000-1001 batch, :1043 ps).
41+
disconnect deletes the file. The shared-token-vs-attribution contradiction is CLOSED:
42+
per-client keys are the connect default, so per-machine usage attribution works.
43+
- **Q-C = a.** Protocol v1 negotiated via /readyz; same-major interop with
44+
feature-detection; guaranteed pair = dev hub ↔ latest release client; older peers get
45+
an explicit "hub protocol too new/old, upgrade ocx" error. Phase 1 hard requirement.
46+
- **Q-B: OPEN ASSUMPTION (low)** — usage page default while connected = "this machine"
47+
slice with a toggle to hub-wide; not answered explicitly, adopting the recommended
48+
default; reversible in Phase 4 GUI work.
49+
50+
## Final contradiction rescan (round 3)
51+
52+
- Shared-token vs attribution: RESOLVED (per-client default; shared token remains a
53+
degraded documented mode where usage collapses into one bucket).
54+
- Pairing-grant issuance vs POST /api/keys authority: connect needs admin-class
55+
authority ONCE — satisfied by pairing code (rung 3/4) or admin token; neither is
56+
persisted on the client. No contradiction.
57+
- Dogfood release-compat vs stacked delivery: protocol version lives in Phase 1 (stack
58+
base), so every later phase rides it. No ordering conflict.
59+
- Remaining OPEN ASSUMPTIONS: Q-B default; session TTL exact value (12h sliding,
60+
tunable); relay streaming backpressure deferred to Phase 6.
61+
62+
Interview readiness: Goal/Constraint/Success/Ontology all covered by asked-and-answered
63+
rounds 1-3. Ready for I -> P.
64+
65+
## Round 4 answer (2026-08-28) — usage rendering settled
66+
67+
Maintainer's rule, adopted verbatim as the design: **connected → render the hub's
68+
usage (my apiKeyId slice); not connected → render the local usage.jsonl.** No local
69+
mirroring of the connect-period usage (option b rejected as unnecessary complexity);
70+
the connect-period history lives on the hub and is visible there. Grounding:
71+
usage persists where the serving proxy runs (appendUsageEntry →
72+
~/.opencodex/usage.jsonl, src/usage/log.ts:166-167, 521-523), so this rule is just
73+
"render the store that actually recorded the traffic" — zero data duplication,
74+
no schema change. Q-B default (this-machine slice with hub-wide toggle) stands as
75+
the connected view's default.

0 commit comments

Comments
 (0)