Struct Agent 

pub struct Agent {
    pub spec: AgentSpec,
    /* private fields */
}

Fields

spec: AgentSpec

Implementations

impl Agent

pub fn new(spec: AgentSpec) -> Self

pub fn with_instructions(self, text: &str) -> Self

Carry this run’s instructions, here and on the stand in.

The fallback gets them too. It answers in this agent’s place, so a run told not to wait on something should not start waiting the moment the primary hands over.

pub fn name(&self) -> &str

pub fn fallback(&self) -> Option<&Agent>

The stand in, if one is configured.

pub fn program(&self) -> &str

The program the template names, before any resolution. What somebody has to install when spar reports it missing.

pub fn env_key(&self) -> String

The environment variable that points this agent’s binary somewhere else.

pub fn resolve_bin(&self) -> Result<&Path>

SPAR_<NAME>_BIN first, then the template’s own program name on PATH or as an absolute path, then the preset’s search paths. Never guess silently: a miss reports every location tried, because a tool that quietly runs the wrong binary is worse than one that fails.

pub fn render(&self, values: &Placeholders) -> Result<Vec<String>>

Substitute placeholders. A group whose placeholder is unset is dropped whole, so omitting model drops --model with it rather than passing an empty string that the CLI would reject or, worse, accept.

pub fn supports_schema(&self) -> bool

True when the template has somewhere to put a schema, meaning the CLI can do structured output natively rather than being asked in the prompt.

Either form counts: a path for a CLI that reads the schema from disk, or the schema itself for one that takes it as an argument.

pub fn extract(&self, stdout: &str) -> Result<String>

pub fn ask(&self, prompt: &str, cwd: &Path, effort: &Effort) -> Result<String>

pub fn edit(&self, prompt: &str, cwd: &Path, effort: &Effort) -> Result<String>

Ask for a call that may modify the working tree.

The caller commits accepted edits after validating the response.

pub fn effort(&self, cfg: &Config, call: Call) -> Effort

What this agent, and its stand in, are asked for on one call.

Both at once, because the fallback runs a different CLI: its effort word has to come from its own configuration rather than from the agent that just failed.

pub fn ask_json<T: DeserializeOwned>( &self, prompt: &str, schema: &Value, cwd: &Path, effort: &Effort, ) -> Result<T>

Structured output through the CLI’s own mechanism when the template exposes one, otherwise by asking for JSON in the prompt and parsing it back out.

pub fn ask_json_alongside<T: DeserializeOwned>( &self, prompt: &str, schema: &Value, cwd: &Path, effort: &Effort, ) -> Result<T>

ask_json for a call that shares its checkout with others running at the same time.

Two reviewers read one checkout at once, and judging each call on its own snapshot blamed the one that finished first for a repro test the other still had open: a whole review was thrown away over a file its author deleted half a minute later. A new untracked file is the caller’s to judge here, once both are done. Everything else is still judged per call.

pub fn edit_json<T: DeserializeOwned>( &self, prompt: &str, schema: &Value, cwd: &Path, effort: &Effort, ) -> Result<T>

Ask for a structured call that may modify the working tree.

The caller commits accepted edits after validating the response.

pub fn review<T: DeserializeOwned>( &self, base: &str, prompt: &str, schema: &Value, cwd: &Path, effort: &Effort, ) -> Result<T>

Review the branch against base.

Deliberately generic. codex exec review was tried and rejected: it refuses a custom prompt alongside --base and returns prose regardless of --output-schema, so it cannot yield a machine checkable verdict. Running inside the worktree is what makes an agent repo aware, not a subcommand.

The call has write access, so the paragraph saying not to write is not decoration: an agent that commits while reviewing ends up holding the head it is about to be handed back, which is the one thing the alternating loop exists to prevent. review::review_loop rolls back what this asks for anyway, because a prompt is not a permission.

pub fn review_alongside<T: DeserializeOwned>( &self, base: &str, prompt: &str, schema: &Value, cwd: &Path, effort: &Effort, ) -> Result<T>

review for a reviewer that shares its checkout with another reading it at the same time. ask_json_alongside says what that changes.

Trait Implementations

impl Debug for Agent

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.