codex

Documentation

Overview

Package codex wraps the OpenAI Codex CLI as an a2a-adapter Driver.

It drives codex through the long-lived `codex app-server` JSON-RPC transport via the pmenglund/codex-sdk-go SDK (whose generated protocol tracks a pinned codex release). A session owns one app-server process and one thread; each turn is a thread turn whose notification stream is mapped to agent.Event values. The app-server's approval requests (command execution, file changes) arrive as synchronous server->client RPCs; this driver turns each into an agent.Approval event and blocks on it until RespondApproval feeds the decision back — the same approval seam claude exposes via can_use_tool. The SDK is fully hidden behind the agent.Driver/Session interface.

Index

• type Driver
  • func New(opts ...Option) *Driver
  • func (*Driver) ID() string
  • func (d *Driver) Open(ctx context.Context, opts agent.SessionOptions) (agent.Session, error)
  • func (d *Driver) Probe(ctx context.Context) (agent.Manifest, error)
  • func (*Driver) ValidateProfile(profile agent.Profile) error
• type Option
  • func WithBinary(bin string) Option
  • func WithElicitation(enabled bool) Option
  • func WithEnv(env map[string]string) Option
  • func WithModel(m string) Option
  • func WithPermissionMode(mode string) Option
  • func WithSensitiveWireTranscript(w io.Writer) Option
  • func WithWorkspace(w string) Option

Types

type Driver

type Driver struct {
	// contains filtered or unexported fields
}

Driver wraps the codex CLI via the app-server control protocol.

func New

func New(opts ...Option) *Driver

New returns a codex driver.

func (*Driver) ID

func (*Driver) ID() string

ID implements agent.Driver.

func (*Driver) Open

func (d *Driver) Open(ctx context.Context, opts agent.SessionOptions) (agent.Session, error)

Open implements agent.Driver. It spawns a codex app-server, performs the initialize handshake, and starts (or resumes) a thread. The ctx bounds only the handshake; the session outlives it.

func (*Driver) Probe

func (d *Driver) Probe(ctx context.Context) (agent.Manifest, error)

Probe implements agent.Driver.

func (*Driver) ValidateProfile

func (*Driver) ValidateProfile(profile agent.Profile) error

ValidateProfile rejects policy fields this driver would otherwise ignore. Model is supported; driver-specific knobs are configured through typed Driver options so misspelled registration policy cannot silently degrade.

type Option

type Option func(*Driver)

Option configures a Driver.

func WithBinary

func WithBinary(bin string) Option

WithBinary overrides the codex executable name/path (default "codex").

func WithElicitation

func WithElicitation(enabled bool) Option

WithElicitation controls Codex's request_user_input integration. It is enabled by default so the built-in Driver works as advertised. Disabling it both suppresses the vendor feature for every started/resumed thread and removes elicitation from the advertised Manifest.

func WithEnv

func WithEnv(env map[string]string) Option

WithEnv sets driver-level environment variables applied to the codex app-server process (e.g. OPENAI_BASE_URL to route through a gateway, or OPENAI_API_KEY). Per-session SessionOptions.Env overrides these.

func WithModel

func WithModel(m string) Option

WithModel pins the model. Empty = CLI default.

func WithPermissionMode

func WithPermissionMode(mode string) Option

WithPermissionMode maps a claude-style default permission mode (default, plan, acceptEdits, bypassPermissions) to codex's approval policy + sandbox when SessionOptions.Profile.Access is empty. A registration-scoped non-empty AccessLevel remains authoritative.

func WithSensitiveWireTranscript

func WithSensitiveWireTranscript(w io.Writer) Option

WithSensitiveWireTranscript tees the Codex app-server's complete native JSON-RPC traffic to w. The transcript is deliberately unredacted and can contain full user prompts, assistant output, tool names/arguments/results, file paths and contents, model metadata, and authentication material carried by future protocol revisions. nil (the default) disables capture.

The caller owns this diagnostic sink and MUST protect it as sensitive data: restrict access, encrypt it where appropriate, and apply an explicit retention/deletion policy. Calls from both protocol directions and every session opened by this Driver are serialized before reaching w. Writes are synchronous and best effort (writer errors and panics are ignored), so a blocking writer can stall the Codex protocol; use a bounded, promptly returning sink. This is not an operational logging API and must not be directed to an ordinary shared application log.

func WithWorkspace

func WithWorkspace(w string) Option

WithWorkspace sets the default working directory codex runs in.