Struct Agent 

pub struct Agent { /* private fields */ }

A stateful agent: configuration, a model transport, a tool set, and the running conversation. Drive it with Agent::send.

Implementations

impl Agent

pub fn new(config: Config) -> Result<Self>

Build an agent backed by an OpenAI-compatible endpoint (OpenRouter by default). The API key is taken from Config::api_key or the configured environment variable.

pub fn with_provider(config: Config, provider: Box<dyn Provider>) -> Self

Build an agent with an explicit provider and the built-in tools. Handy for tests (inject a mock provider) or custom transports.

pub fn with_parts( config: Config, provider: Box<dyn Provider>, registry: ToolRegistry, ) -> Self

Build an agent from all three parts.

pub fn provider_arc(&self) -> Arc<dyn Provider>

A handle to this agent’s model transport, for sharing with subagents.

pub async fn run_subagent( &self, system: impl Into<String>, task: impl Into<String>, ) -> Result<String>

Spawn a subagent that shares this agent’s model transport, runs task to completion with its own fresh conversation (seeded with system), and returns its final answer. The analog of Agent / spawn_agent.

pub fn with_provider_arc(config: Config, provider: Arc<dyn Provider>) -> Self

Like Self::with_provider but sharing an existing transport handle.

pub fn run_in_background( self, prompt: impl Into<String>, ) -> JoinHandle<(Self, Result<String>)>

where Self: Send + 'static,

Run a prompt on a background task, returning a handle that resolves to the final answer (and the agent, so the caller can continue it). The analog of background/async agent runs.

pub fn resume(config: Config, session: Session) -> Result<Self>

Build an agent and seed it with a previously-recorded Session so it can continue where Claude Code or Codex left off.

pub fn load_session(&mut self, session: Session)

Replace the conversation with a loaded session, keeping this agent’s own system prompt at the front. The session’s own system/developer turns are preserved after it for context.

pub fn save_transcript(&self, path: impl AsRef<Path>) -> Result<()>

Persist the live conversation to path as JSONL (one ChatMessage per line) so the session can be resumed later — supercode’s own sessions become first-class, resumable artifacts.

pub fn load_transcript(&mut self, path: impl AsRef<Path>) -> Result<()>

Restore a conversation previously written with Self::save_transcript, replacing the current history.

pub fn checkpoint(&self) -> usize

Take a checkpoint of the current conversation position. Pass it to Self::rewind_to to discard everything sent since (the rewind/undo analog of fork/checkpoint).

pub fn rewind_to(&mut self, checkpoint: usize)

Rewind the conversation to a Self::checkpoint, discarding later turns.

pub async fn send_with_files( &mut self, text: impl Into<String>, files: &[PathBuf], ) -> Result<String>

Send a message with file inputs attached — the --file / -i analog. Each file’s contents are injected into the prompt: UTF-8 text inline, binary (e.g. images) noted with a size marker. (Native image vision would additionally require multimodal content parts.)

pub async fn send_with_images( &mut self, text: impl Into<String>, image_urls: &[String], ) -> Result<String>

Send a message with image inputs to a vision model — the -i/--image analog. image_urls may be https://… links or data:image/…;base64,… URLs; they’re attached as multimodal image_url content parts.

pub fn expand_prompt(&self, input: &str) -> String

Expand a /<name> <args> slash command against the registered prompt templates ({args} is replaced with the trailing text). Non-matching input is returned unchanged.

pub fn maybe_compact(&mut self) -> bool

Compact the conversation if it has grown past the configured threshold: keep the system prompt and the most recent turns, and replace the older middle turns with a single summary marker. Returns whether it compacted.

pub fn register_tool(&mut self, tool: impl Tool + 'static)

Register an additional tool (e.g. your own capability).

pub fn history(&self) -> &[ChatMessage]

The current conversation, including the system prompt.

pub async fn send(&mut self, user_input: impl Into<String>) -> Result<String>

Send a user message and run the loop until the model produces a final answer (text with no tool calls) or the iteration budget is exhausted.

pub fn turn_count(&self) -> usize

Number of non-system messages exchanged so far.

pub fn total_output_tokens(&self) -> u64

Cumulative output (completion) tokens reported by the provider across every send on this agent. Zero if the provider reports no usage.