@kaiba-cloud/orbital-harness-codex 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# Orbital harness: Codex
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@kaiba-cloud/orbital-harness-codex` runs the agents of an [Orbital](https://www.npmjs.com/package/@kaiba-cloud/orbital) team on the OpenAI Codex CLI.
+It is a harness plugin for the `harnesses` port of Orbital.
+It has the harness id `codex` and the harness folder `.codex`.
+
+Each turn runs `codex exec --json` in the workspace of the session.
+Codex signs in with its own login, so Orbital asks for no provider key.
+Codex has its own shell and file edits.
+The turn also gives Codex the orbital tools over MCP.
+
+The package is not a program of its own.
+It needs `@kaiba-cloud/orbital`, and Orbital runs it.
+It also needs the `codex` program on the machine, signed in.
+
+## Install
+
+1. Install Orbital.
+
+   ```bash
+   npm i -g @kaiba-cloud/orbital
+   ```
+
+2. In your repository, install the harness.
+
+   ```bash
+   orbital install codex
+   ```
+
+   The command does these steps:
+
+   - It installs `@kaiba-cloud/orbital-harness-codex` at the version of Orbital in the plugin cache of the Orbital home.
+   - It writes `.codex/orbital.yaml` when the file is absent.
+   - It names the plugin in `.codex/orbital.yaml` as `npm:@kaiba-cloud/orbital-harness-codex@<version>`, so a clone of the project finds it.
+   - It writes the MCP server `orbital` in `.codex/config.toml`.
+
+   The block in `.codex/config.toml` is:
+
+   ```toml
+   [mcp_servers.orbital]
+   command = "orbital"
+   args = ["mcp", "--attach", "--harness", "codex", "--agent", "codex"]
+   ```
+
+   The install keeps every other line of the file.
+   A second run writes nothing.
+   If the file defines `orbital` in another way, the install keeps the file and prints a note.
+   Add `--force` to replace the definition of `orbital` when it differs.
+
+| Flag | Meaning |
+|---|---|
+| `--plugin <source>` | Take the adapter from this plugin: an npm package, a git URL or a folder. |
+| `--user` | Name the plugin in your user config, not in `.codex/orbital.yaml`. |
+| `--force` | Overwrite a file or a setting that Orbital did not write. |
+| `--workspace <path>` | The project. Default: the current directory. |
+
+A Codex turn that Orbital runs reaches the orbital tools through `-c mcp_servers.orbital.*` options of the turn.
+So the block in `.codex/config.toml` serves a person who runs Codex by hand in the project.
+
+## The login
+
+Codex uses its own login, not a key of Orbital.
+Sign in to Codex on the machine first.
+Then `auth.json` is in your Codex home.
+
+- The Codex home is `CODEX_HOME` when the turn environment has it, and `~/.codex` otherwise.
+- Each turn runs Codex with a home in the session folder, `codex/home`.
+- That home links `auth.json` and `config.toml` of your Codex home. No other file of your Codex home is linked.
+- Orbital asks for no provider key for a member on `codex`, and passes it none.
+- The harness asks the sandbox for the hosts `api.openai.com`, `chatgpt.com` and `auth.openai.com`.
+
+## The model
+
+Write the model in the agent file as `<provider>:<model>`.
+A provider other than `openai` selects the model provider of that id in your `config.toml`.
+If the agent has no model, Codex uses its own default model.
+
+## An agent on Codex
+
+An agent file in `.codex/agents` runs on `codex` by default.
+The body of the file is the system prompt.
+The turn gives it to Codex as `developer_instructions`.
+
+```markdown
+---
+name: reviewer
+description: Reviews a change and reports the problems.
+---
+You review a change in the workspace. You report each problem with its file and line.
+```
+
+## A team member on Codex
+
+A member of a team runs on the harness that its charter names.
+The charter is a harness folder file, such as `.claude/teams/review/CHARTER.md`.
+The member `reviewer` runs on Codex, and the lead runs on Claude Code:
+
+```markdown
+---
+apiVersion: orbital/v1alpha1
+name: review
+objective: Review each change before it merges.
+lead: lead
+members:
+  - name: lead
+    harness: claude
+  - name: reviewer
+    harness: codex
+---
+The lead hands each change to the reviewer and reports the result.
+```
+
+The agent file of `reviewer` can be in any harness folder of the project.
+An agent name is unique in a project.
+Run `orbital check` to check the team.
+
+## What the harness supports
+
+| Feature | Support |
+|---|---|
+| Transcript | Supported. A reasoning summary is a thinking part. A message is a text part. A command is a tool call named `Bash`. A file change is a tool call named `apply_patch`. An orbital tool call is named `mcp__<server>__<tool>`. Each call has a tool result, and a command or tool that fails gives a result marked as an error. |
+| Tools | Codex runs its own shell and file edits. The orbital tools come from the MCP server `orbital`. The turn turns off the sub-agent tools and the goal tools of Codex, so the children of an agent stay sessions of the node. |
+| Telemetry | Supported. Each turn reports the input, output, cache read and cache write tokens, and one model call. The cost is zero, because Codex reports no cost. |
+| Resume | Supported. The harness keeps the thread id of Codex in `codex/state.json` of the session folder. A later turn runs `codex exec resume` on that thread. |
+| Stop | Supported. SIGTERM goes to the Codex process, SIGKILL follows after three seconds, and the turn exits with code 143. |
+| Shared browser | Supported. See below. |
+
+### The shared browser
+
+The harness declares `browser: true`, so a turn gets the shared browser of the node.
+The turn writes a `config.toml` in the session home.
+In that file, the shared browser replaces each `chrome-devtools` MCP server of your `config.toml`.
+Your own file stays as it is.
+If your `config.toml` has no `chrome-devtools` server, the session gets no browser tools.
+To let your own Codex sessions share the connection, run `orbital browser install`.
+
+## Known limits
+
+- A turn runs Codex with `--dangerously-bypass-approvals-and-sandbox`. The sandbox of the node isolates the turn, and a run with no person cannot answer an approval.
+- Codex reports the token total of the thread. The usage of a turn is the difference from the stored total.
+- If the Codex thread id is not stored, the next turn starts a new thread.
+- The cost of a turn is zero in the telemetry of Orbital.
+- A turn fails when `codex` is not on the machine. The error is `codex exited with code 127.`
+- A turn that ends with no completed answer fails with `Codex answered nothing.`
+- The harness lists three hosts as egress: `api.openai.com`, `chatgpt.com` and `auth.openai.com`.