Skip to content

docs: clarify Codex App backend contract #315

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
SSBrouhard wants to merge 7 commits into from
Closed

docs: clarify Codex App backend contract #315

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
a180cdf
docs: reconcile Codex App backend contract
Jul 3, 2026
9d55377
no-mistakes(document): Sync backend docs
Jul 3, 2026
df92ee7
docs: clarify Codex Desktop bridge blocker
Jul 3, 2026
98197cc
no-mistakes(document): Align Codex App backend docs
Jul 3, 2026
b368903
no-mistakes(document): Document Codex App backend contract
Jul 5, 2026
27abfb5
no-mistakes(document): Captain, document blocked codex-app coverage
Jul 5, 2026
afc81f8
docs: make Codex App contract doc authoritative
Jul 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 15 additions & 2 deletions docs/codex-app-backend.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,19 @@ read_thread after archive:
transcript still included the initial and follow-up completed turns.
```

Separate 2026-07-06 shell-harness rerun attempt evidence: this harness did not expose callable `create_thread`, `read_thread`, `send_message_to_thread`, or `archive` host tools, so it could not perform an independent same-day rerun from shell.
Targeted tool discovery for those names surfaced GitHub and Gmail connector tools only, not Codex Desktop thread host tools.
The requested shell-harness smoke output files were absent:

```text
$ ls -l state/codex-app-host-smoke-20260706.status data/codex-app-host-smoke-20260706/report.md
ls: data/codex-app-host-smoke-20260706/report.md: No such file or directory
ls: state/codex-app-host-smoke-20260706.status: No such file or directory
```

Prior 2026-07-03 host-tool smoke evidence is preserved as historical confirmation.
That run used thread id `019f2947-f75e-78b2-aebc-f57ef1b5b399`, wrote `state/codex-app-host-smoke-j3.status` and `data/codex-app-host-smoke-j3/report.md`, appended `working: host thread wrote status` and `done: follow-up delivered`, and archive/read-after-archive still returned the transcript with the thread no longer loaded.

Result: a Desktop-owned Codex thread can write Firstmate status files when the prompt gives it the absolute status path and the Desktop permission context can write that checkout.
The return channel is real at the Codex Desktop host-tool layer.

Expand All @@ -167,10 +180,10 @@ The available Codex CLI and app-server probes found useful pieces but not a supp
- A raw proxy attempt against the Desktop control socket did not accept plain JSON-RPC framing.

That is not enough to add `codex-app` to `FM_BACKEND_KNOWN` or `FM_BACKEND_SPAWN`.
A Firstmate backend must be able to create a thread, start or continue turns, read live state while turns run, and archive/stop the same endpoint through a Codex Desktop-supported shell-callable API.
A Firstmate backend must be able to create a thread, start or continue turns, read live state while turns run, and archive/stop the same endpoint through a stable Codex Desktop-supported shell-callable API.
Shipping a local ledger would only record intentions; it would not supervise the actual Desktop thread.

## Required Codex Desktop bridge
## Required Codex Desktop bridge before implementation

Firstmate should implement a Codex App adapter only after Codex Desktop exposes one of these supported interfaces:

Expand Down