[alexey-belkin]

Problem and behavior

A GridCraft workbook served by Codex still showed Claude setup/Waiting, and it could not show which actual Desktop chat would receive its questions. This adds an opt-in Codex context with live connection status, saved creator-chat provenance and a runtime working-chat route displayed in Agent.

The companion bridge, shared App Server launcher, workbook links, global experimental skill and installation guide are in anton-belkin/aitocraft#1. This PR intentionally targets agent-layer; the native changes are Rust only.

Changes

• GRIDCRAFT_AGENT_PROVIDER=codex scopes the runtime to one launched instance, skips Claude setup and avoids persisting its preferences into global defaults. Explicit Off remains respected.
• Optional creator-chat fields round-trip with the existing workbook agent metadata and are cleared from inherited defaults for new workbooks. Creator metadata cannot be rewritten by an answering agent.
• agent.codexRoute maintains an expiring runtime-only route. Agent shows the actual chat, missing/other-chat states and an Open Chat action. A stale answered ping cannot make Codex Ready; a recent Desktop bridge listener is required.
• Connect Codex starts the configured external question worker for this GUI instance. AItoCraft discovery can use an isolated AITOCRAFT_REGISTRY_DIR.
• Native command/environment contract and companion installation, architecture and reboot guide.

The working chat chosen by a link is separate from creator provenance. Unavailable targets use a visibly different real Desktop chat rather than importing history into a CLI session. Existing proposal acceptance/rejection commands remain person actions. No global Claude configuration changes are required.

Validation

• cargo xtask ci: all 8 steps passed — fmt, Clippy -D warnings, 1686 workspace tests, assets, layers, WASM, parity and keytips. This includes 58 agent-layer and 14 Agent UI tests. The first sandboxed run refused a local TCP bind in an existing MCP test; the full rerun with loopback access passed.
• Companion AItoCraft: 19 library + 1 stdio tests passed, 11 Python tests passed, Node syntax checks, native Swift compile, skill validation and isolated installer verification passed.

The companion live test delivered five unique questions into the same actual Desktop chat: formula explanation; draft 60→70 (profit 40→30); draft 70→90 (profit 10), rejection comment; and a question after saving/reopening. Acceptance/rejection, formula, answers, decisions and provenance survived save/reopen. The final pass used native person-action commands corresponding to the buttons, without claiming fresh UI clicks while Desktop UI automation was unavailable.

Scope and compatibility

The companion macOS example was exercised on Desktop 26.1007.30912 / bundled App Server 0.162.0-alpha.17.2. Its shared-transport override is version-sensitive and experimental. Existing files without the new fields still read; older GridCraft versions that do not recognize kind=codex are not supported readers of that new context metadata. No real chat IDs, tickets, user workbooks or private paths are included.

[anton-belkin]

Thanks for this! A Codex context is welcome, and the fork rules are respected: only fork files are
touched, the fork:agent markers are unchanged, and rebase.sh --check is green on the current
agent-layer. A few changes are needed before we merge.

Please change

1. Make it really opt-in. The Codex row shows in everyone's Context menu even without
   GRIDCRAFT_AGENT_PROVIDER=codex (crates/agent-ui/src/ribbon.rs:477). Picking it saves the new
   kind, and Connect Codex then fails. Show the row only when the mode is enabled.
2. English UI text. Russian strings are hard-coded in crates/agent-ui/src/context.rs:264-300 and
   crates/agent-ui/src/ribbon.rs:520-536. The rest of the UI is English.
3. The Ready lamp must not depend on a label. It turns on only for a listener whose label starts
   with "Codex desktop bridge ·" (crates/agent-ui/src/context.rs:241). The rule in PROTOCOL.md
   §7 is simply a listener for this document seen recently. Please use that, so any client works.
4. Smaller:
   • don't hard-code /usr/bin/python3 (crates/agent/src/context.rs:565): find python on PATH or
     make it configurable;
   • move docs/codex-desktop.md out of upstream's docs/ into agent-layer/, and drop the links
     to personal branches.

Please discuss before coding

5. Generic fields instead of Codex-specific ones. "Creator chat" and "current chat route" are
   useful for any client and any app (WordCraft and DeckCraft too). Let's describe them in
   PROTOCOL.md as generic, optional fields (for example origin: {client, chat, url?} on the
   document and route on the listener) and store them in that form. See the aitocraft#1 reply for
   the bigger picture.

On our side

• An older build that meets an unknown value such as "kind":"codex" currently drops the whole
  agent layer. That's our bug, not yours, and we're fixing it in agent-layer (unknown values are
  kept, never wiped). No change needed in this PR.

When 1–4 are done (and 5 agreed), we'll merge.