codex

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: AGPL-3.0 Imports: 23 Imported by: 0

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

View Source
const (
	AuthSubscription = "subscription"
	AuthAPIKey       = "apiKey"
)

Auth modes in a HarnessOffer.

View Source
const DefaultKillGrace = 5 * time.Second

DefaultKillGrace is how long codex gets to exit after SIGTERM before its process group is killed.

View Source
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).

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 New

func New(o Options) *Adapter

New returns the adapter.

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) Name

func (a *Adapter) Name() string

Name implements harness.Adapter.

func (*Adapter) Prepare

func (a *Adapter) Prepare(_ context.Context, ws harness.Workspace, t v1alpha1.Task) error

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

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL