Crate nanocodex_agent

Expand description

§Nanocodex Agent

The owned lifecycle for one headless OpenAI coding agent.

nanocodex-agent composes the Tower-native Responses state machine from nanocodex-oai-api with the runtime from nanocodex-tools. A normal consumer builds one agent, receives a cheap cloneable Nanocodex handle and an independent AgentEvents stream, then submits ordered prompts.

§Quick start

use nanocodex_agent::{Nanocodex, OpenAi};

let openai = OpenAi::new(std::env::var("OPENAI_API_KEY")?)?;
let (agent, _events) = Nanocodex::builder(openai)
    .instructions(
        "You are a Rust coding agent. Preserve unrelated work and run relevant tests.",
    )
    .workspace(std::env::current_dir()?)
    .build()?;

let result = agent
    .prompt("Explain the cause of the failing parser test.")
    .await?
    .await?;
println!("{}", result.final_message());
agent.shutdown().await?;

The first await means the private driver accepted and ordered the prompt. Turn is both a per-turn event stream and a future for TurnResult. Awaiting the turn waits only for its result; event consumption is independent.

The private driver is the sole owner of mutable conversation, transport, tool, and process state. Cloning Nanocodex only clones its command capability; Nanocodex::spawn creates a clean sibling and Nanocodex::fork creates an independent branch from committed history.

§Remote tool environments

When tools execute in a VM or remote workspace, provide one coherent snapshot of the facts described to the model. This prevents host time and AGENTS.md discovery from being mixed with a different tool filesystem:

use nanocodex_agent::{ExecutionEnvironment, Nanocodex, OpenAi};

let environment = ExecutionEnvironment::new("2026-07-29", "Etc/UTC")
    .project_instructions("Preserve generated files under build/.");
let (_agent, _events) = Nanocodex::builder(openai)
    .execution_environment(environment)
    .build()?;

Omit ExecutionEnvironment::project_instructions when the remote workspace has no project instructions. Without an execution environment, native agents continue discovering date, timezone, and project instructions from the local embedding host.

§Typed events

AgentEvents is optional and independent from turn results. Its raw JSONL-compatible envelope remains lossless, while AgentEvent::data provides a normalized domain view:

use futures_util::StreamExt;
use nanocodex_agent::{
    Nanocodex, OpenAi,
    events::{AgentEventData, AssistantEvent},
};

let openai = OpenAi::new(std::env::var("OPENAI_API_KEY")?)?;
let (agent, mut events) = Nanocodex::builder(openai)
    .instructions("Answer concisely and preserve exact identifiers.")
    .build()?;
let turn = agent.prompt("Explain the identifier req_7f3.").await?;

while let Some(event) = events.next().await {
    if let AgentEventData::Assistant(AssistantEvent::Delta(delta)) = event.data()? {
        print!("{}", delta.text);
    }
    if event.kind.is_terminal() {
        break;
    }
}
let _result = turn.await?;
agent.shutdown().await?;

§Components

events contains the complete typed lifecycle event taxonomy.
input contains prompts and multimodal user input.
session contains session identities and serializable resume snapshots.
execution is the neutral model/tool/checkpoint interception seam implemented by optional higher-layer policies.
usage contains token accounting and USD estimates.
rollout records and restores Codex-compatible sessions.
transport exposes advanced Responses and Tower configuration.
tools exposes the complete tool implementation surface.

OpenAI API-key and managed ChatGPT credentials belong to nanocodex_oai_api::auth, independently of this lifecycle crate. Portable journals, durable admission, and recovery policy belong to nanocodex-durability, which depends on this crate; the agent never depends on that optional layer. An attached execution policy is owned by exactly one agent. A clean spawn deliberately creates an ordinary in-memory child without that policy; fork returns an explicit error because inherited committed context requires an independently owned policy.

Re-exports§

pub use usage::ReportedTurnUsage;
pub use usage::TurnUsage;

Modules§

events: Complete typed lifecycle events emitted by an agent.
executionopenai: Neutral interception contract implemented by optional execution layers.
input: Prompts and multimodal user input accepted by the agent.
rolloutopenai and non-target_family=wasm: Codex-compatible durable rollout recording and restoration.
session: Serializable local session snapshots returned when a backend supports them.
toolsopenai: Complete tool contracts, registry, built-ins, Code Mode, and MCP.
transportopenai and non-target_family=wasm: Advanced Responses transport and Tower service configuration.
usage: Per-turn token accounting and USD estimates.

Structs§

AgentEvents: The receiving half of an agent’s typed event stream.
AgentHandleopenai: Weak child-agent capability for the driver that owns one tool runtime.
AgentSessionContext: Read-only model context exposed to session adapters.
EstimatedUsdCost: Exact estimated USD cost for provider-reported token usage.
ExecutionEnvironmentopenai: Model-visible facts owned by a remote tool-execution environment.
Nanocodex: Cheap, cloneable command handle for an owned agent driver.
NanocodexBuilderopenai: Builder for one owned agent lifecycle.
OpenAiopenai: Configured, cloneable OpenAI client recipe.
PromptRequest: One prompt submission with an optional execution identity.
ResponseErroropenai: Cloneable typed failure returned by a response stream and its completed future.
SpawnOptions: Optional model policy for a newly spawned clean agent.
Toolsopenai: Declarative selection of the built-in tools installed for an agent.
Turn: Completion handle for an accepted turn.
TurnControl: Cheap cloneable control capability for one accepted turn.
TurnResult: Final result of a completed turn.
UsdAmount: An exact non-negative amount of United States dollars.

Enums§

CostStatus: Availability of the automatic local USD estimate.
ExecutionPolicyDisposition: Recovery action attached by a higher-layer execution policy.
Model: Supported OpenAI coding models.
NanocodexError: Error returned by the Nanocodex library boundary.
PromptRoute: Outcome of routing live user input into an agent session.
ReasoningMode: Responses reasoning execution mode for the supported model family.
ResponseErrorKindopenai: Stable classification for one failed Responses operation.
ServiceTier: OpenAI service tiers supported by Nanocodex.
Thinking: Requested model reasoning effort.

Traits§

BuilderBackend: Input that selects the concrete builder returned by Nanocodex::builder.
Toolopenai: A caller-defined model-visible tool.

Type Aliases§

Result: Result type returned by the owned agent lifecycle.

Attribute Macros§

toolopenai and non-target_family=wasm: Defines a typed JSON function tool from an async Rust function.