GenServer wrapper for long-running multi-turn sessions.
Holds a CodexWrapper.Session in state and provides a process-based
interface for OTP applications, supervision trees, and concurrent access.
Usage
config = CodexWrapper.Config.new(working_dir: "/path/to/project")
{:ok, pid} = CodexWrapper.SessionServer.start_link(
config: config,
exec_opts: [model: "o3", full_auto: true]
)
{:ok, result} = CodexWrapper.SessionServer.send_message(pid, "What files are here?")
{:ok, result} = CodexWrapper.SessionServer.send_message(pid, "Add tests for lib/foo.ex")
CodexWrapper.SessionServer.total_cost(pid)
#=> 0.0Supervision
children = [
{CodexWrapper.SessionServer,
name: :my_agent,
config: config,
exec_opts: [model: "o3"]}
]
Supervisor.start_link(children, strategy: :one_for_one)
# Then use the registered name
CodexWrapper.SessionServer.send_message(:my_agent, "hello")Summary
Functions
Returns a specification to start this module under a supervisor.
Get the underlying %Session{} struct (snapshot).
Get the full conversation history.
Get the last result, if any.
Send a message in the session. Blocks until the CLI responds.
Get the session ID (if established).
Start a session server.
Get the total cost across all turns.
Get the number of completed turns.
Types
@type option() :: {:config, CodexWrapper.Config.t()} | {:exec_opts, keyword()} | {:session_id, String.t()} | {:name, GenServer.name()} | GenServer.option()
@type server() :: GenServer.server()
Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
@spec get_session(server()) :: CodexWrapper.Session.t()
Get the underlying %Session{} struct (snapshot).
@spec history(server()) :: [CodexWrapper.Result.t()]
Get the full conversation history.
@spec last_result(server()) :: CodexWrapper.Result.t() | nil
Get the last result, if any.
@spec send_message(server(), String.t(), keyword()) :: {:ok, CodexWrapper.Result.t()} | {:error, term()}
Send a message in the session. Blocks until the CLI responds.
Returns {:ok, %Result{}} or {:error, reason}.
Get the session ID (if established).
@spec start_link([option()]) :: GenServer.on_start()
Start a session server.
Options
:config- (required)%Config{}struct:exec_opts- Exec options applied to every turn (e.g.model,sandbox):session_id- Resume an existing session by ID:name- Register the process with a name
Also accepts standard GenServer.start_link/3 options.
Get the total cost across all turns.
@spec turn_count(server()) :: non_neg_integer()
Get the number of completed turns.