Documentation
¶
Overview ¶
Package codex is the Codex CLI harness adapter (design/workstreams/agent/LLD/ harness-adapters.md §Codex). It runs only in a VM workspace (`factory-agent run`, workspace-run.md §Harnesses in the VM), where the VM is the boundary.
Prepare lays out a scratch CODEX_HOME in the workspace: a placeholder auth.json (placeholderAuth: the account's identifiers in an unsigned id_token, harness.Placeholder as the tokens, and a fresh last_refresh, so codex never refreshes), a generated config.toml (no update check, the run's environment for commands, the Effector's MCP server), AGENTS.md with the headless preamble, and the task's skills flattened from the pipeline's plugin layout. Run starts `codex exec --json` with the resolved model and effort, without codex's own sandbox (`--sandbox danger-full-access`), from the pipeline's WorkDir, streams its JSONL into the EventSink, stops on a rate or plan limit, and kills the whole process group when its context ends. Repair resumes the same session with the validation problems. The gateway outside the VM replaces the bearer and the account header with the owner's, and refreshes the real token itself.
Every codex flag, config key and event name the adapter relies on is in flags.go, each marked UNVERIFIED until a VM workspace run exercises it.
Index ¶
- Constants
- type Adapter
- func (a *Adapter) Capabilities() v1alpha1.AdapterCapabilities
- func (a *Adapter) Name() string
- func (a *Adapter) Prepare(_ context.Context, ws harness.Workspace, t v1alpha1.Task) error
- func (a *Adapter) Repair(ctx context.Context, ws harness.Workspace, problems []string, ...) (harness.Raw, error)
- func (a *Adapter) Run(ctx context.Context, ws harness.Workspace, t v1alpha1.Task, prompt string, ...) (harness.Raw, error)
- type Options
Constants ¶
const ( AuthSubscription = "subscription" AuthAPIKey = "apiKey" )
Auth modes in a HarnessOffer.
const DefaultKillGrace = 5 * time.Second
DefaultKillGrace is how long codex gets to exit after SIGTERM before its process group is killed.
const DefaultThrottle = clirun.DefaultThrottle
DefaultThrottle is how long a rate-limited agent waits when the error gives no reset (harness-adapters.md: else +15 min).
const Name = config.HarnessCodex
Name is the harness's name.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Adapter ¶
type Adapter struct {
// contains filtered or unexported fields
}
Adapter is the codex harness adapter. It keeps no per-run state in memory (the session to resume is in the workspace), so one Adapter serves concurrent runs.
func (*Adapter) Capabilities ¶
func (a *Adapter) Capabilities() v1alpha1.AdapterCapabilities
Capabilities implements harness.Adapter: the LLD's effort mapping (max → high, xhigh for the models that take it) and codex's features.
func (*Adapter) Prepare ¶
Prepare implements harness.Adapter: the task must run on the subscription (an API-key run has no gateway injection in the PoC) and the adapter must have the account, and the scratch CODEX_HOME gets placeholderAuth's auth.json (0600, never over an existing file), renderConfig's config.toml, AGENTS.md (the headless preamble), skills/<name>/ for every skill the pipeline materialised in its plugin layout and skills/<plugin>/bin linked to each plugin's bin/ (linkPluginBins).
func (*Adapter) Repair ¶
func (a *Adapter) Repair(ctx context.Context, ws harness.Workspace, problems []string, sink harness.EventSink) (harness.Raw, error)
Repair implements harness.Adapter: the same session resumed (`codex exec resume <thread>`) with the problems, asking for a valid Result only. Without a thread to resume, a new exec gets the original prompt followed by the problems. The sandbox and working directory are the Run's, from the session record.
func (*Adapter) Run ¶
func (a *Adapter) Run(ctx context.Context, ws harness.Workspace, t v1alpha1.Task, prompt string, sink harness.EventSink) (harness.Raw, error)
Run implements harness.Adapter: `codex exec --json` on the prompt (stdin) with the task's resolved model and effort, danger-full-access (the VM is the boundary) from workDir's directory.
type Options ¶
type Options struct {
// Config is the codex harness's config: vmrun makes it from the task's resolved harness
// (Default is the model when the task names none).
Config config.Harness
// Binary is the codex executable. Default: "codex" on PATH.
Binary string
// Clock stamps events and rate-limit resets. Default: clock.Real.
Clock clock.Clock
// KillGrace is the SIGTERM-to-SIGKILL delay on cancel. Default: DefaultKillGrace.
KillGrace time.Duration
// Throttle is the wait on a rate limit without a reset. Default: DefaultThrottle.
Throttle time.Duration
// Account is the ChatGPT account codex runs as: the run bundle's codex/account.json,
// identifiers only (P1 §5). Its id_token claims pick codex's workspace, which fails
// without the real ones (Phase 0, Q5). Required.
Account *runbundle.CodexAccount
}
Options configure an Adapter. Account is required.