Agent Module

Core agent logic for orchestrating jobs, sessions, and tool execution

Overview

The agent module orchestrates the core functionality of IronClaw:

• Message routing from channels
• Job scheduling and execution
• Tool invocation with safety guardrails
• Self-repair for stuck jobs
• Proactive heartbeat execution
• Routine-based scheduled and reactive jobs
• Turn-based session management with undo
• Context compaction for long conversations

Core Types

Agent

The main agent orchestrator that processes incoming messages and manages execution.

user_id · String

User identifier for the agent session

session · Session

Current session state with threads and turns

workspace · Workspace

Persistent memory storage for the agent

tools · ToolRegistry

Available tools for the agent to use

Example

use ironclaw::agent::{Agent, AgentDeps};

let deps = AgentDeps {
    llm: Arc::new(llm_provider),
    workspace: Arc::new(workspace),
    tools: Arc::new(tool_registry),
};

let agent = Agent::new("user_123", deps);

Session

A session contains one or more threads representing conversations with the agent.

id · Uuid

Unique session identifier

user_id · String

User who owns this session

active_thread · Option<Uuid>

Currently active thread ID

threads · HashMap<Uuid, Thread>

All threads in this session

auto_approved_tools · HashSet<String>

Tools that have been auto-approved for this session

Methods

new · fn(user_id: impl Into<String>) -> Self

Create a new session for a user

create_thread · fn(&mut self) -> &mut Thread

Create a new thread in this session and make it active

active_thread · fn(&self) -> Option<&Thread>

Get the currently active thread

is_tool_auto_approved · fn(&self, tool_name: &str) -> bool

Check if a tool has been auto-approved

auto_approve_tool · fn(&mut self, tool_name: impl Into<String>)

Add a tool to the auto-approved set

Example

use ironclaw::agent::Session;

let mut session = Session::new("user_123");
let thread = session.create_thread();

// Auto-approve a tool for this session
session.auto_approve_tool("file_read");
assert!(session.is_tool_auto_approved("file_read"));

Thread

A thread represents a conversation sequence with turns (request/response pairs).

id · Uuid

Unique thread identifier

session_id · Uuid

Parent session ID

turns · Vec<Turn>

Conversation history as turns

state · ThreadState

Current state (Active, Interrupted, Completed)

Turn

A single request/response pair in a conversation.

id · Uuid

Unique turn identifier

user_message · String

User’s input message

assistant_message · Option<String>

Agent’s response (None if turn incomplete)

tool_calls · Vec<ToolCall>

Tool invocations made during this turn

state · TurnState

Current state (Pending, InProgress, Completed, Failed)

Routine

A scheduled or reactive job that runs automatically.

id · Uuid

Unique routine identifier

name · String

Human-readable routine name

trigger · Trigger

When this routine should execute

action · RoutineAction

What the routine should do

Trigger Types

Cron · String

Execute on a cron schedule (e.g., “0 9 * * *”)

Interval · Duration

Execute every N seconds/minutes/hours

Event · String

Execute when a specific event occurs

Example

use ironclaw::agent::{Routine, RoutineAction, Trigger};
use std::time::Duration;

let routine = Routine {
    id: Uuid::new_v4(),
    name: "Daily standup reminder".to_string(),
    trigger: Trigger::Cron("0 9 * * 1-5".to_string()),
    action: RoutineAction::SendMessage {
        content: "Time for standup!".to_string(),
    },
};

ContextCompactor

Compacts conversation history to save context window space.

compact · async fn(thread: &Thread) -> Result<CompactionResult>

Compact a thread’s conversation history by summarizing old turns

should_compact · fn(thread: &Thread) -> bool

Check if a thread should be compacted based on size

CompactionResult

original_turns · usize

Number of turns before compaction

compacted_turns · usize

Number of turns after compaction

summary · String

Summary of compacted content

tokens_saved · u32

Approximate tokens saved by compaction

Example

use ironclaw::agent::ContextCompactor;

let compactor = ContextCompactor::new(llm_provider);
if compactor.should_compact(&thread) {
    let result = compactor.compact(&thread).await?;
    println!("Saved {} tokens", result.tokens_saved);
}

UndoManager

Manages checkpoints and undo operations for sessions.

create_checkpoint · fn(&mut self, session: &Session) -> Checkpoint

Create a checkpoint of the current session state

restore_checkpoint · fn(&mut self, checkpoint_id: Uuid) -> Result<Session>

Restore session to a previous checkpoint

list_checkpoints · fn(&self) -> Vec<Checkpoint>

List all available checkpoints

Example

use ironclaw::agent::UndoManager;

let mut undo_mgr = UndoManager::new();

// Create checkpoint before risky operation
let checkpoint = undo_mgr.create_checkpoint(&session);

// If something goes wrong, restore
if needs_undo {
    let restored_session = undo_mgr.restore_checkpoint(checkpoint.id)?;
}

SelfRepair

Detects and repairs stuck jobs and broken tools.

detect_stuck_jobs · async fn() -> Vec<StuckJob>

Find jobs that have been running too long

repair · async fn(task: RepairTask) -> Result<RepairResult>

Attempt to repair a stuck job or broken tool

RepairTask Types

StuckJob · { job_id: Uuid, reason: String }

A job that needs to be unstuck

BrokenTool · { tool_name: String, error: ToolError }

A tool that failed and needs repair

Example

use ironclaw::agent::SelfRepair;

let repair = SelfRepair::new();
let stuck = repair.detect_stuck_jobs().await;

for job in stuck {
    let result = repair.repair(RepairTask::StuckJob {
        job_id: job.id,
        reason: "Timeout".to_string(),
    }).await?;
}

Related Modules

Workspace Module

Persistent memory storage for agents

Tools Module

Extensible tool system for agent capabilities

LLM Module

Language model integration and providers