Documentation
¶
Overview ¶
Package codex runs the Codex CLI as an agent.Backend and derives the strict structured-output schema it passes to OpenAI.
Index ¶
- Constants
- func SignedIn(ctx context.Context, binary string) (signedIn, known bool)
- func StrictSchema(schema []byte) ([]byte, error)
- type Backend
- func (c *Backend) Check(ctx context.Context) (version string, err error)
- func (c *Backend) Complete(ctx context.Context, request agent.CompleteRequest) (agent.Completion, error)
- func (c *Backend) ConcurrentCalls() bool
- func (c *Backend) Fix(ctx context.Context, request agent.Request) (agent.Result, error)
- func (*Backend) Name() string
- func (c *Backend) Run(ctx context.Context, request agent.Request) (agent.Result, error)
- type Profile
Constants ¶
const MinimumVersion = "0.156.1"
MinimumVersion is the oldest Codex the Local profile runs. It is the release the hosted review agent image pins (tools/codex-cli/package.json), which runs every flag Run passes in production apart from --sandbox. Checked by installing @openai/codex 0.156.1 and 0.162.1: both list --ephemeral, --ignore-user-config, --ignore-rules and --output-schema for `codex exec`, and both accept `codex sandbox -P :read-only`, which the preflight uses. An older release that lacks one of the flags exits with an unknown-option error, which Run maps to the same upgrade request.
Variables ¶
This section is empty.
Functions ¶
func SignedIn ¶
SignedIn asks Codex whether it is signed in, with the environment a Local run gets: a ChatGPT sign-in or an API key saved with `codex login` counts. known is false when the answer could not be read.
func StrictSchema ¶
StrictSchema derives the schema Codex passes to OpenAI's strict structured outputs from the lenient authored contract. Strict mode requires every property and a closed object, and rejects conditionals, oneOf and most string formats and uniqueItems; it also fails on chained $refs, so they are inlined. Optional properties become nullable, and normalization removes the nulls. Dropped constraints stay with the validator and the repair loop. schema is a JSON Schema whose $refs point into its own $defs; a host that calls a provider's strict structured outputs itself, such as a stack review, uses it too.
Types ¶
type Backend ¶
type Backend struct {
// Binary is the codex executable. The Local profile resolves it with
// exec.LookPath and defaults to "codex".
Binary, Model string
Profile Profile
// Effort is the model_reasoning_effort; empty
// leaves it to Codex.
Effort string
// Env are the user's agent variables (agent.WithUserEnv), for the Local
// profile only.
Env []string
// contains filtered or unexported fields
}
Backend runs the Codex CLI over a request's directory.
The child runs in its own process group, so a terminal's Ctrl-C (SIGINT) does not reach it. A local caller must cancel the context it passes to Run on SIGINT and SIGTERM, for example with signal.NotifyContext, or the CLI keeps running after baum exits. Cancelling kills the group on Unix, and on Windows only the child itself.
func (*Backend) Check ¶
Check resolves the executable, checks its version and that its read-only sandbox starts, as the first Run does, and returns the installed version. Only the Local profile has a check; the Container profile returns "" and nil. A host calls it before assembling anything, so a missing or old installation fails at once instead of as a provider failure retried by the loop.
func (*Backend) Complete ¶
func (c *Backend) Complete(ctx context.Context, request agent.CompleteRequest) (agent.Completion, error)
Complete runs `codex exec` once for a single structured reply (agent.Completer): ephemeral, without the user's config, rules or hooks, in its read-only sandbox, with the shell and other tools turned off, the Backend's reasoning effort (Codex's own when empty), the request's system prompt as the model instructions and the request's schema as the output schema, in an empty temporary directory. The prompt goes on stdin and starts with sessions.GenerationRunMarker. Only the Local profile completes.
func (*Backend) ConcurrentCalls ¶
ConcurrentCalls reports whether calls may run over one run directory at once (agent.ConcurrentCaller): the Local profile writes each call's output schema to a temporary directory of its own. The Container profile writes it to CODEX_HOME under the run directory, shared by every call, so it runs them one at a time.
func (*Backend) Fix ¶
Fix runs Codex with write access to the request's directory, for a fix a person asked for (agent.Fixer). Codex's workspace-write sandbox lets the commands it runs write to that directory and to Request.Scratch, which becomes their TMPDIR, and nowhere else (not /tmp or the caller's TMPDIR), with the network off. As in a review, they can read any file the user can. Its final message is the result's Document. Only the Local profile fixes.
type Profile ¶
type Profile int
Profile selects the sandbox, environment and credentials the Codex process gets.
const ( // Local is for local runs and the zero value. Codex runs in its read-only // sandbox: commands it starts cannot write or reach the network, but they // can read any file the user can, not only the working directory. The // process gets the user's own HOME and CODEX_HOME (or ~/.codex), so // `codex login` auth works, an allowlisted copy of the environment // (agent.LocalEnvironment, plus CODEX_HOME) and the binary found on PATH. // CODEX_API_KEY and the base URL are set only when the request names an // Endpoint. The output schema goes to a private temporary file removed // after the run, never into CODEX_HOME. Before the first run the installed version is // checked and a trivial command is run under the read-only sandbox, once // per Backend; a machine where the sandbox cannot start is refused. Local Profile = iota // Container is for a host that already runs the process inside its own // boundary, such as the hosted review agent container. Codex runs with its // sandbox disabled: Docker's default seccomp profile blocks the user // namespaces the sandbox needs. The CLI may execute commands, so the child // receives only the run's endpoint token and run files: HOME and CODEX_HOME // under <run>/home, a fixed PATH and CODEX_API_KEY from the Endpoint, which // it requires. It never inherits the caller's environment and does not // check the installed version. Never use it outside such a container. Container )
Source Files