Codex

@@ -0,0 +1,427 @@+# Codex Bridge++**Codex Desktop, reachable through Adom Bridge. A compiled Rust binary owned by adom/codex.**++Codex Bridge lets an Adom assistant manage a Codex Desktop installation on a+selected Windows host, talk to its native tools, and use its bundled backend for+accounts, plugins, skills, and conversations. Your assistant can run elsewhere:+the tested desktop lives on **arav-rog**, not on AdomLapper.++![The signed-in Codex Desktop home on arav-rog](https://wiki.adom.inc/api/pages/adom/codex/files/bridge/screenshots/01-desktop-home.png)++*The real Windows application after first-run setup. The tested Store package is+named ChatGPT and includes this Codex workspace. This is not the Hydrogen dock+dashboard or a mockup.*++The seven screenshots in this guide are real, unretouched window captures from+the arav-rog test on 2026-09-08. The Home image was refreshed for this guide;+onboarding and conversation images preserve the earlier verified run. We did not+repeat UAC, install plugins, create schedules, or import other apps just to stage+pictures. The gallery illustrates observed UI, not every API operation below.+See [capture provenance and checksums](https://wiki.adom.inc/adom/codex/files/bridge/screenshots/README.md)+for dates and the distinction between the original setup run and bridge 0.1.1's+later toast guidance.++[Back to adom/codex](https://wiki.adom.inc/adom/codex) ·+[Technical setup](https://wiki.adom.inc/adom/codex/files/docs/DESKTOP-BRIDGE.md) ·+[Command catalog](https://wiki.adom.inc/adom/codex/files/bridge/verbs.json) ·+[Setup skill](https://wiki.adom.inc/adom/codex/files/skills/codex-desktop-bridge/SKILL.md)++## At a glance++| Workflow | What the bridge does | Verification boundary |+| --- | --- | --- |+| Install and launch | Finds the official Windows package, installs with WinGet, opens the native app | Install, uninstall, reinstall and visible first-run completion tested |+| Sign in | Imports a user-authorized native auth cache without overwriting credentials; offers native login as fallback | Cache import and signed-in account/app verified; not universal VS Code SSO |+| Desktop conversations | Discovers native schemas and calls the running app over a PID-verified pipe | Desktop-created test conversation and persisted reply verified |+| Plugins | Searches catalogs, inspects details, installs, reads back and removes plugins | LaTeX install/read-back/remove/read-back tested; third-party OAuth not tested |+| Projects and worktrees | Exposes the desktop's live project, fork and handoff tools | Schemas discovered; worktree mutations not exercised in the baseline |+| Scheduled tasks | Exposes the desktop's automation tools | Schemas discovered; no recurring task created for this guide |+| Panels and organization | Exposes file/review/terminal panels and thread/sidebar tools | Availability follows the running app's catalog; not every action tested |+| Progress and approvals | Tracks bridge jobs, backend events and pending native requests | Native approvals remain user decisions; bridge responses do not grant consent |+| Remove safely | Removes desktop or bridge separately while retaining Codex home | Running-app refusal and retained account/history after reinstall tested |++## 1. Three installations, not one++| Component | Runs where | Installed by |+| --- | --- | --- |+| `adom/codex` integration | Your Adom workspace | `adom-wiki pkg install adom/codex` |+| `codex-bridge.exe` and `bridge.json` | AB on the selected Windows desktop | A separately built bridge ZIP and AB's runtime lifecycle |+| OpenAI Codex Desktop | The same Windows desktop | Official Microsoft Store package, managed through `codex_desktop_install` |++The Rust bridge does **not** need Node or Python on the target. It uses Windows+PowerShell/WinGet for package operations and the desktop's activated native+`codex.exe` for its separate app-server connection. Other Adom components can+have their own runtime requirements.++### Build the bridge++From a current source checkout of adom/codex:++```sh+bash bridge/build.sh+```++Linux cross-building requires Rust's `x86_64-pc-windows-gnu` target, MinGW-w64,+`zip`, and `sha256sum`. The script runs tests and builds a Windows x64 release.+It produces `bridge/dist/codex-bridge-windows-x64.zip` and `SHA256SUMS`.+The ZIP root contains `bridge.json` and `codex-bridge.exe`.++**Distribution status:** the tested runtime is development-pinned on arav-rog.+There is no published public runtime release/update manifest yet. Do not assume+the wiki package installer deploys this ZIP, and do not invent a download URL.+The [technical guide](https://wiki.adom.inc/adom/codex/files/docs/DESKTOP-BRIDGE.md)+describes the AB SDK development-cache deployment and safe update sequence.+Preserve existing development pins and do not replace a bridge owned by another task.++### Select the desktop explicitly++First discover the reachable AB targets and choose the relay that reaches your+host. The examples below use the dedicated test machine. Replace it deliberately+for another installation; your container hostname is not target discovery.++```sh+ab --target arav-rog --ai-thread codex-bridge-guide codex_status '{}'+ab --target arav-rog --ai-thread codex-bridge-guide codex_readiness '{}'+ab --target arav-rog --ai-thread codex-bridge-guide codex_describe '{}'+```++`adom-bridge` can be used instead of `ab`. Use the **same caller identity** for an+operation and its job polls. `codex_status` reports package/version, windows,+auth-cache presence, backend ownership and connection mode. A present auth cache+is not proof of a valid account; a running process is not proof of completed setup.++## 2. Install, sign in, and finish Windows setup++```sh+ab --target arav-rog --ai-thread codex-bridge-guide codex_desktop_install '{}'+ab --target arav-rog --ai-thread codex-bridge-guide codex_progress '{"jobId":"<returned-job-id>"}'+ab --target arav-rog --ai-thread codex-bridge-guide codex_desktop_open '{}'+```++The tested official Store ID is `9PLM9XGG6VKS`, package `OpenAI.Codex`.+Its displayed Store/app name was **ChatGPT** in this test. If the installer asks+for package agreements, obtain the user's actual acceptance before retrying with+`{"acceptAgreements":true}`. Existing installations are detected and retained.++### Reuse an existing Codex sign-in++![The signed-in desktop confirming the existing Engineering role during first-run setup](https://wiki.adom.inc/api/pages/adom/codex/files/bridge/screenshots/09-signed-in-onboarding.png)++*Historical setup capture: the native app recognized the account and asked to+confirm the existing role. Sign-in worked, but OS setup was not complete yet.*++Being signed in to the VS Code extension is helpful only when there is a+transferable native Codex auth cache. This is not password scraping or a promise+that every extension login can be silently reused across machines.++1. With the user's authorization, transfer their native `$CODEX_HOME/auth.json`+   (usually `~/.codex/auth.json`) to private staging on the **selected host** using AB.+2. Keep the bridge backend disconnected. Import with `codex_auth_import` and the+   absolute host staging path. Existing destination credentials are never overwritten.+3. Delete the staging copy promptly. Do not print tokens or put credentials in+   chat, command arguments, source files, screenshots, or wiki uploads.+4. Connect and verify `codex_account_read`, then verify the visible signed-in app.+   An already-running desktop may need a normal quit/relaunch; preserve active work.++The importer sets an owner-only Windows ACL. If no transferable cache exists,+start the native `chatgpt` or `chatgptDeviceCode` login via `codex_login_start`+after connecting. Let the user complete authentication. Refresh/revocation and+connected-service authentication can still require the user's involvement.++### Give advance notice before UAC++![The native Finish Windows setup page explaining the upcoming administrator prompt](https://wiki.adom.inc/api/pages/adom/codex/files/bridge/screenshots/12-before-uac.png)++*Historical capture of the app's pre-UAC page. The pictured dialog is the app's+own instructional illustration, not a capture of Windows' secure desktop. This+is the point where the AI must send the advance AB toast before continuing.*++Before **Finish setup**, or another action expected to request elevation, send+the `_beforeUac` payload returned by `codex_describe`, status, readiness, install+or open as an AB `notify_user` call on the same target and caller.++```json+{+  "title": "Codex setup needs your approval",+  "body": "A Windows administrator (UAC) prompt is coming for Codex setup. Please approve the native Windows prompt for OpenAI's Codex/ChatGPT app to continue. This notification cannot approve it.",+  "level": "warning",+  "durationLong": true,+  "focus": { "app": "ChatGPT" }+}+```++Prefer the currently discovered app HWND for `focus` when one is available.+Send the toast **before elevation**, while the normal desktop is visible, and+also tell the user in chat because Windows may suppress notification banners.+Wait for the native Windows decision and then inspect the resulting app.++This is conditional AI guidance, not an unconditional automatic toast on every+status check. A toast acknowledgment does not approve UAC. Do not send a false+upcoming-UAC warning on an already-configured host or bypass the secure desktop.+The baseline user approved the real setup prompt; this guide does not re-trigger it.++## 3. Talk to the actual desktop++![The desktop test conversation and its native reply](https://wiki.adom.inc/api/pages/adom/codex/files/bridge/screenshots/02-native-thread.png)++*The baseline created "Adom Rust bridge test" through the desktop's native tools.+Its `DESKTOP_BRIDGE_OK` reply was read back and survived uninstall/reinstall.*++There are two different connections. Choose the one that matches the result you want.++```text+Adom assistant -> named AB target -> codex-bridge.exe+                                    |+                                    +-- Desktop-native pipe -> running Codex Desktop+                                    |   native threads, projects, panels, automations+                                    |+                                    +-- app-server --stdio -> separate bundled backend+                                        accounts, plugins, skills, MCP, backend turns+```++The native route verifies the named pipe's server PID against the installed+package's visible desktop process. It uses length-prefixed JSON-RPC, implemented+in Rust. It is **experimental app internals, not a documented stable public API**.+Rediscover schemas after desktop updates or restarts.++```sh+ab --target arav-rog --ai-thread codex-bridge-guide codex_desktop_tools '{}'+```++If multiple verified endpoints exist, the bridge lists them and requires+`desktopPipe`. Do not guess or persist a pipe name across restarts. PID verification+does not guarantee every endpoint serves the same tool methods; a stale or+non-serving endpoint can still report a native handler error.++The app exposes tools such as `list_threads`, `read_thread`, `create_thread`,+`send_message_to_thread`, and `wait_threads`. Discover their current schemas.+An invocation has this shape:++```json+{+  "tool": "read_thread",+  "threadId": "<native-caller-thread-id>",+  "desktopPipe": "<verified-endpoint-if-required>",+  "arguments": {+    "threadId": "<native-thread-to-read>",+    "turnLimit": 1,+    "includeOutputs": false+  }+}+```++Pass that object to `codex_desktop_tool_call` and poll its job. The outer+`threadId` is native caller context, not the human-readable AB `--ai-thread` name.+Use real IDs from discovery or an authorized seed; never fabricate them.+Tool calls may have additional native instructions and approval requirements.++For a requested conversation, create it, retain the returned thread/host IDs,+wait for completion or attention, and read the result back. To show it, use the+native navigation tool and verify an actual window capture. An acknowledgment+such as `navigated:true` is not sufficient: during guide preparation an endpoint+acknowledged navigation while the captured page stayed on Home.++## 4. Find and manage plugins++The Home screenshot's **Plugins** entry is the native app's catalog entry point.+The bridge also exposes catalog management directly, without needing to click+through that page. Catalog contents and availability can vary by account and+app version; seeing an entry does not mean it is installed.++Plugin operations use the separate bridge-owned native app-server. Connect once,+poll the returned job, and verify its result before issuing backend commands:++```sh+ab --target arav-rog --ai-thread codex-bridge-guide codex_connect '{"mode":"standalone"}'+ab --target arav-rog --ai-thread codex-bridge-guide codex_progress '{"jobId":"<connect-job-id>"}'+ab --target arav-rog --ai-thread codex-bridge-guide codex_plugin_list '{"query":"latex","limit":10}'+```++Read details using the exact marketplace returned by discovery:++```json+{"pluginName":"latex","marketplacePath":"<discovered-local-marketplace-path>"}+```++Send this to `codex_plugin_read`. For a remote marketplace use+`remoteMarketplaceName` instead of `marketplacePath`. Inspect availability,+installation policy, terms, interstitials, and connected apps before installation.++After authorization, use the same identifiers with `codex_plugin_install`, poll+the job, then read the plugin again. Verify+`result.plugin.summary.installed`, rather than treating queue acceptance as an+installation. `appsNeedingAuth` means the user still needs to authenticate to a+connected service. Do not silently approve OAuth or claim it is ready early.++For removal, discover the exact installed `pluginId` and pass it to+`codex_plugin_uninstall`. Poll and read back the absent state. The baseline used+`latex@openai-bundled`, verified installation/enabled state, and removed that+temporary test plugin. No paid service or third-party OAuth workflow was exercised.++## 5. Projects, worktrees, and review++Project selection belongs to the remote desktop's environment. The Home view+shows **Choose project** and an empty Projects sidebar on this test installation.+A container path on your assistant's machine is not automatically a directory on+arav-rog.++Discover `list_projects` before selecting a project. Native thread creation can+target a saved project or projectless work. Worktree and handoff tools can affect+real checkouts, branches and active tasks, so follow the live schemas and user+intent. Do not invent a project ID, branch name, or destination host.++The baseline discovered `fork_thread` and `handoff_thread` but did not exercise+checkout changes. Treat this as exposed capability, not a tested cross-machine+handoff promise. A handoff may interrupt its source task; inspect ownership and+current activity first.++The app also has a **Pull requests** entry. Its presence is not evidence that the+bridge created, reviewed, or merged a GitHub pull request.++`open_in_codex` can expose native file, terminal, browser and review panels when+available in the app's catalog. Opening a panel is a UI action; it does not itself+inspect the content, run a command, or prove a code review was completed.++### Native imports are a separate decision++![The native optional import screen offering to bring work from another AI app](https://wiki.adom.inc/api/pages/adom/codex/files/bridge/screenshots/11-optional-imports.png)++*Historical setup capture: the desktop offered to import work from another app.+We skipped it. The visible default switches do not mean import or sync was+authorized or executed.*++The bridge's auth-cache import is not this cross-app project/history import.+Keep credentials reuse, project selection, and importing another app's data+separate. Do not accept defaults that broaden data access as an incidental setup step.++## 6. Scheduled work and desktop-only surfaces++![The native onboarding page suggesting spreadsheet, messaging, calendar, and desktop-file tasks](https://wiki.adom.inc/api/pages/adom/codex/files/bridge/screenshots/10-optional-tasks.png)++*Historical onboarding suggestions, not completed tasks. We selected Skip rather+than running a spreadsheet task, sending a message, or scheduling a calendar+event. A calendar suggestion here is not proof of a Codex automation run.*++The discovered `automation_update` tool supports viewing, creating, updating and+deleting automations. Its native instructions distinguish ongoing thread+follow-ups from standalone scheduled project work. Inspect existing automations,+preserve unrelated fields and notification preferences, and ask before creating+recurring activity that the user has not requested. The bridge does not add an+independent cron scheduler or guarantee wake-from-sleep execution.++![The signed-in desktop offering its optional voice experience](https://wiki.adom.inc/api/pages/adom/codex/files/bridge/screenshots/13-desktop-voice-offer.png)++*Historical post-setup Home view. Start Voice is the native app's optional offer;+no voice session was started. The bridge does not enable the microphone merely+because voice tools appear in the discovered catalog.*++The native catalog also exposes thread organization, archive/restore, usage+inspection, and other app-specific actions. Availability and policy follow the+installed app. Voice-only tools are for an active voice session, not ordinary text+automation. Sharing, consuming usage-reset credits, and changing recurring jobs+need the user's intent; catalog discovery is not permission to invoke everything.++## 7. Models, skills, MCP, and the separate backend++The screenshots show the native composer with its model/effort selector and+**Ask for approval** control. Model availability is account/build dependent;+these captures are not a permanent model list or a subscription entitlement.++Once `codex_connect` completes, use `codex_models`, `codex_skills_list`,+`codex_mcp_status`, and `codex_config_read` to inspect the bundled backend's+effective environment. `codex_account_read` verifies sign-in. These commands are+inspection APIs; a config read is not a general-purpose settings editor.++On Windows, `codex_connect` launches the activated desktop-bundled+`codex.exe app-server --stdio` as a **separate bridge-owned process** sharing+Codex home. It does not attach to desktop-owned active sessions. `mode:desktop`+fails explicitly on Windows rather than silently substituting a backend.++Backend conversations use `codex_thread_start`, `codex_turn_start`,+`codex_thread_read`, `codex_thread_turns`, and `codex_thread_items`. Steering,+interrupting, forking, archiving and releasing subscriptions are also available.+Only operate on authorized work. Never resume an active desktop-owned thread in+this separate backend. The backend test reply was `CODEX_BRIDGE_OK`; the actual+desktop test reply was separately verified as `DESKTOP_BRIDGE_OK`.++## 8. Follow progress and preserve approvals++Long-running bridge calls return a `jobId`. Poll `codex_progress` until+`stillRunning:false`, then inspect **`result.success`** and any nested native+`result.success` or error. Top-level success can mean only that the poll worked.++```sh+ab --target arav-rog --ai-thread codex-bridge-guide codex_progress '{"jobId":"<job-id>"}'+ab --target arav-rog --ai-thread codex-bridge-guide codex_events '{"sinceSeq":0}'+ab --target arav-rog --ai-thread codex-bridge-guide codex_requests '{}'+```++Omit `jobId` to list the current caller's jobs. Job history is bounded and retained+for one hour in the bridge process; it does not survive a bridge restart.+After a timeout, inspect the existing job and native state before retrying a+mutation. Event streams use sequence cursors; compare `oldestSeq` to detect gaps.++Pending native approval/user-input requests are returned by `codex_requests`.+Use `codex_request_reply` with the native response shape only after the appropriate+user decision. No automatic execution approval, OAuth approval or UAC bypass is+part of this bridge. Disconnect refuses active turns and pending requests rather+than abandoning them silently.++## 9. Uninstall without deleting your work++Desktop removal and bridge removal are separate operations:++| Request | Operation | What remains |+| --- | --- | --- |+| Remove Codex Desktop | `codex_desktop_uninstall {"confirm":true}` after disconnecting and normally quitting the app | Codex home, credentials, plugins, saved threads and projects |+| Remove the AB bridge | AB `bridge_uninstall {"name":"codex"}` invokes its lifecycle hook | OpenAI desktop installation and user data |+| Delete account data or projects | Not part of either uninstall | Requires a separate explicit decision |++Quit the desktop normally, including tray/background package processes, and+preserve any active work first. The bridge refuses desktop removal while package+processes or its own backend are running. Do not kill unrelated Codex processes+to force an uninstall. The live baseline verified refusal while running, then+uninstall/reinstall on the idle test installation with account/history retained.++## Troubleshooting++| Symptom | Next check |+| --- | --- |+| Wrong machine or missing bridge | Rediscover AB targets, select the correct relay, inspect `bridge_list`; do not default to the local laptop |+| Multiple desktop pipes | Select a verified endpoint from fresh discovery; inspect native errors; rediscover after restart |+| Navigation says success but nothing changes | Capture the current window and inspect its actual state; acknowledgment alone is insufficient |+| `connected:false` while desktop is open | This describes the separate backend connection, not whether the desktop exists |+| Auth cache exists but app needs login | Verify account validity; finish native login/setup; do not overwrite an existing cache |+| Store agreements or Windows setup blocks | Get the user's real decision; send the advance UAC toast before the elevation step |+| Plugin installed but unavailable | Read details and `appsNeedingAuth`; connected-service authentication may remain |+| A job or event disappeared | Check process restart, retention, caller identity and cursor gaps before repeating work |+| Removal is refused | Inspect active turns, pending requests, tray processes and task ownership; quit normally |++## Verified baseline and source map++Baseline: **2026-09-08**, arav-rog, AB **2.1.72**, bridge **0.1.1**,+OpenAI.Codex **26.901.6511.0**, bundled native CLI **0.153.4**.+Fourteen tests passed, including unit/mock and HTTP integration coverage;+Windows-target Clippy and the Windows x64 release build passed. The screenshot+tour illustrates native UI; the workflow table above distinguishes it from+end-to-end mutation tests. No Codex Desktop installation was made on AdomLapper.++| File | Responsibility |+| --- | --- |+| `src/main.rs` | Loopback HTTP, routing, jobs, caller attribution, setup/UAC hints |+| `src/desktop.rs` | Windows package lifecycle, process detection, protected auth import |+| `src/app_tools.rs` | PID-verified native desktop pipe and structured RPC |+| `src/rpc.rs` | Separate app-server connection, events, requests and ownership |+| `src/process.rs` | Bounded process output and timeouts |+| `bridge.json`, `verbs.json` | AB executable lifecycle and the 40-command catalog |+| `tests/http.rs`, `build.sh` | HTTP contract verification and Windows release packaging |++The HTTP listener binds loopback and rejects browser Origin requests. AB caller+identity provides attribution and ownership, not isolation from other processes+running as the same OS user. Screenshots contain no credential cache contents.++Windows x64 is the tested platform. Other OS installers, a dedicated bridge dock+UI, full worktree/automation testing, third-party OAuth and a public runtime+update channel remain outside this verified baseline. The existing CAD videos+on the main adom/codex page were recorded in Hydrogen, not this desktop app.