Struct Agent 

pub struct Agent { /* private fields */ }

Agent for deterministic AI-driven code operations.

The agent follows a strict loop:

1. Observe: Gather context from the graph
2. Constrain: Apply policy rules
3. Plan: Generate execution steps
4. Mutate: Apply changes
5. Verify: Validate results
6. Commit: Finalize transaction

Runtime Integration

The agent can integrate with ForgeRuntime for coordinated file watching and caching:

let (agent, mut runtime) = Agent::with_runtime("./project").await?;
let result = agent.run_with_runtime(&mut runtime, "refactor function").await?;

Implementations

impl Agent

pub async fn with_runtime( codebase_path: impl AsRef<Path>, ) -> Result<(Self, ForgeRuntime), AgentError>

Creates agent with runtime for file watching and caching.

This method initializes both the Agent and ForgeRuntime, allowing the agent to leverage runtime services like query caching and coordinated file watching.

Arguments

• codebase_path - Path to the codebase

Returns

Returns a tuple of (Agent, ForgeRuntime) on success.

Example

use forge_agent::Agent;

let (agent, mut runtime) = Agent::with_runtime("./project").await?;

// Start file watching
runtime.watch().await?;

// Run agent with runtime coordination
let result = agent.run_with_runtime(&mut runtime, "refactor function").await?;

pub async fn run_with_runtime( &self, _runtime: &mut ForgeRuntime, query: &str, ) -> Result<LoopResult>

Runs agent loop with runtime coordination.

This method coordinates with ForgeRuntime for optimal performance:

• Query cache access for faster graph operations
• Metrics collection for observability

Note: For v0.4, watcher pause/resume is deferred to future versions. The runtime provides cache access and metrics, but file watching coordination is a future enhancement.

Arguments

• runtime - Mutable reference to the ForgeRuntime
• query - The natural language query or request

Returns

Returns LoopResult with transaction ID, modified files, and audit trail.

Example

use forge_agent::Agent;

let (agent, mut runtime) = Agent::with_runtime("./project").await?;
let result = agent.run_with_runtime(&mut runtime, "add error handling").await?;

pub fn runtime_cache(&self) -> Option<()>

Gets reference to runtime cache if available.

This method provides access to the runtime’s query cache for optimization of repeated graph queries.

Returns

Returns None - cache access requires runtime association (not yet implemented).

Note: This is a placeholder for future functionality.

pub fn runtime_stats(&self) -> Option<()>

Gets runtime statistics if available.

This method provides access to runtime metrics including cache size, watch status, and reindex count.

Returns

Returns None - stats access requires runtime association (not yet implemented).

Note: This is a placeholder for future functionality.

impl Agent

pub async fn new(codebase_path: impl AsRef<Path>) -> Result<Self>

Creates a new agent for the given codebase.

Arguments

• codebase_path - Path to the codebase

pub async fn observe(&self, query: &str) -> Result<Observation>

Observes the codebase to gather context for a query.

Arguments

• query - The natural language query or request

pub async fn constrain( &self, observation: Observation, policies: Vec<Policy>, ) -> Result<ConstrainedPlan>

Applies policy constraints to the observation.

Arguments

• observation - The observation to constrain
• policies - The policies to validate

pub async fn plan(&self, constrained: ConstrainedPlan) -> Result<ExecutionPlan>

Generates an execution plan from the constrained observation.

pub async fn mutate(&self, plan: ExecutionPlan) -> Result<MutationResult>

Executes the mutation phase of the plan.

pub async fn verify( &self, _result: MutationResult, ) -> Result<VerificationResult>

Verifies the mutation result.

pub async fn commit(&self, result: VerificationResult) -> Result<CommitResult>

Commits the verified mutation.

pub async fn run(&self, query: &str) -> Result<LoopResult>

Runs the full agent loop: Observe -> Constrain -> Plan -> Mutate -> Verify -> Commit

This is the main entry point for executing a complete agent operation. Each phase receives the output of the previous phase, and failures trigger rollback with audit trail entries.

Arguments

• query - The natural language query or request

Returns

Returns LoopResult with transaction ID, modified files, and audit trail.

Example

use forge_agent::Agent;

let agent = Agent::new(".").await?;
let result = agent.run("Add error handling to the parser").await?;
println!("Transaction ID: {}", result.transaction_id);