M06: Codex adapter: CLI/App Server with Desktop and VS Code installations #91

New issue

Closed

opened 2026-09-19 13:07:36 +00:00 by kilo · 1 comment

kilo commented

2026-09-19 13:07:36 +00:00

Member

Goal

Support users who have Codex through CLI, VS Code, or Codex Desktop — without automating the GUI and without falsely claiming OpenAI compatibility.

Module of the execution-gateway program; architecture and contracts come from A0 (#85).

User value

Subscription-included Codex capacity — where owner/instance policy allows unattended execution (cf. D-039's eligibility contract, issue #82) — becomes executable through the router from any OpenAI-compatible client.

Relationship to current code

Builds directly on the existing Codex capacity collector (providers/openai_codex*.py), the D-018 bounded auth-recovery exception, U-001 discovery evidence and the D-039 eligibility parser (providers/openai_eligibility.py, eligibility.py).
Execution runs through the worker (M05) or the server where the app-server is reachable; discovery knowledge is reused, not duplicated.

Two-stage approach (within this issue)

Stage 1 — short technical verification. No Forgejo dependency on A0/M05; this evidence may start immediately and feeds A0. Verify: runtime discovery; authentication; Desktop-only installation; CLI installation; VS Code integration; Windows versus WSL profiles; model selection; reasoning/effort selection; quota scope; conversation roles/history; streaming; cancellation; isolation; tool-call behavior; structured output; usage reporting; stable versus experimental App Server protocol fields.
Stage 2 — implementation of the verified supported subset. Depends on A0 (#85) and M05 (Forgejo dependency edges). Prefer official Codex App Server / CLI mechanisms. Reuse knowledge and code from the existing Codex capacity collector where appropriate.

Non-goals

No GUI automation; no credential/token extraction shortcuts where an official remediation step exists; no adoption of unrelated conversations, global plugins or user projects by default; no promotional-eligibility assumptions.

Contracts / interfaces affected

Execution adapter contract (A0); OpenAI compatibility matrix (M03); D-018 recovery boundary (unchanged); worker dispatch (M05).

Dependencies

Stage 1: none (independent evidence track).
Stage 2 (Forgejo dependency): A0 (#85), M05.
Feeds: M10 (Windows/WSL scenarios).

Acceptance criteria

Separate documented scenarios for Desktop-only Codex, CLI, VS Code, Windows and WSL.
If a required official component is missing, a clear installation/remediation step is provided — never manual extraction/copying of authentication tokens.
OpenAI compatibility is never inferred merely because the model produced text; the matrix (M03) records PASS/PARTIAL/UNSUPPORTED/UNKNOWN with tested version and evidence.
Promotional eligibility is never inferred merely because execution succeeded.
If required isolation cannot be provided, only the affected adapter/mode is marked ineligible — the rest of the router keeps working.
Full validation gate green; redacted fixtures only.

Security considerations

The default CLI-backed execution mode must not automatically receive access to user projects, arbitrary filesystem paths, shell, global MCP configuration, plugins, browser integrations or unrelated conversation history. A read-only sandbox alone is not necessarily proof of sufficient isolation. Credentials stay provider-managed (the D-018 boundary is unchanged: Scarcity Router never receives, reads, stores or exposes tokens). No root execution; no uncontrolled subprocess flags/environment variables.

Risks

The app-server protocol is not a stable public API — mitigated by generation-aware parsing (the D-019/U-011 pattern) and safe disable on contract change.

Evidence still required

Official documentation, re-verified with date and tested version at implementation time: https://developers.openai.com/codex/app-server and https://developers.openai.com/codex/auth; local capability probes preferred; only credentials authorized for this work may be used.

## Goal Support users who have Codex through CLI, VS Code, or Codex Desktop — without automating the GUI and without falsely claiming OpenAI compatibility. Module of the execution-gateway program; architecture and contracts come from A0 (#85). ## User value Subscription-included Codex capacity — where owner/instance policy allows unattended execution (cf. D-039's eligibility contract, issue #82) — becomes executable through the router from any OpenAI-compatible client. ## Relationship to current code - Builds directly on the existing Codex capacity collector (`providers/openai_codex*.py`), the D-018 bounded auth-recovery exception, U-001 discovery evidence and the D-039 eligibility parser (`providers/openai_eligibility.py`, `eligibility.py`). - Execution runs through the worker (M05) or the server where the app-server is reachable; discovery knowledge is reused, not duplicated. ## Two-stage approach (within this issue) 1. **Stage 1 — short technical verification.** No Forgejo dependency on A0/M05; this evidence may start immediately and feeds A0. Verify: runtime discovery; authentication; Desktop-only installation; CLI installation; VS Code integration; Windows versus WSL profiles; model selection; reasoning/effort selection; quota scope; conversation roles/history; streaming; cancellation; isolation; tool-call behavior; structured output; usage reporting; stable versus experimental App Server protocol fields. 2. **Stage 2 — implementation of the verified supported subset.** Depends on A0 (#85) and M05 (Forgejo dependency edges). Prefer official Codex App Server / CLI mechanisms. Reuse knowledge and code from the existing Codex capacity collector where appropriate. ## Non-goals - No GUI automation; no credential/token extraction shortcuts where an official remediation step exists; no adoption of unrelated conversations, global plugins or user projects by default; no promotional-eligibility assumptions. ## Contracts / interfaces affected Execution adapter contract (A0); OpenAI compatibility matrix (M03); D-018 recovery boundary (unchanged); worker dispatch (M05). ## Dependencies - Stage 1: none (independent evidence track). - Stage 2 (Forgejo dependency): A0 (#85), M05. - Feeds: M10 (Windows/WSL scenarios). ## Acceptance criteria - [ ] Separate documented scenarios for Desktop-only Codex, CLI, VS Code, Windows and WSL. - [ ] If a required official component is missing, a clear installation/remediation step is provided — never manual extraction/copying of authentication tokens. - [ ] OpenAI compatibility is never inferred merely because the model produced text; the matrix (M03) records PASS/PARTIAL/UNSUPPORTED/UNKNOWN with tested version and evidence. - [ ] Promotional eligibility is never inferred merely because execution succeeded. - [ ] If required isolation cannot be provided, only the affected adapter/mode is marked ineligible — the rest of the router keeps working. - [ ] Full validation gate green; redacted fixtures only. ## Security considerations The default CLI-backed execution mode must not automatically receive access to user projects, arbitrary filesystem paths, shell, global MCP configuration, plugins, browser integrations or unrelated conversation history. A read-only sandbox alone is not necessarily proof of sufficient isolation. Credentials stay provider-managed (the D-018 boundary is unchanged: Scarcity Router never receives, reads, stores or exposes tokens). No root execution; no uncontrolled subprocess flags/environment variables. ## Risks - The app-server protocol is not a stable public API — mitigated by generation-aware parsing (the D-019/U-011 pattern) and safe disable on contract change. ## Evidence still required - Official documentation, re-verified with date and tested version at implementation time: https://developers.openai.com/codex/app-server and https://developers.openai.com/codex/auth; local capability probes preferred; only credentials authorized for this work may be used.

kilo referenced this issue

2026-09-19 13:11:01 +00:00

A0: Architecture, decisions, and contracts for the optional execution gateway #85

kilo added the

enhancement

label

2026-09-19 13:11:41 +00:00

kilo added a new dependency

2026-09-19 13:12:16 +00:00

#85 A0: Architecture, decisions, and contracts for the optional execution gateway

kilo added a new dependency

2026-09-19 13:12:16 +00:00

#90 M05: Native worker, pairing, and execution transport