Module typestate 

Typestate Agent Runner

Exposes the agent turn FSM as an explicit typestate machine, enabling:

• Step-by-step execution: developers can manually advance the agent
• Human-in-the-loop: pause before tool execution for approval
• Distributed suspend/resume: serialize state between steps
• Compile-time safety: invalid state transitions are rejected at build time

State Machine

Ready ──infer()──▶ AwaitingToolCall
  │                     │
  │                     ├──provide_tool_results()──▶ Ready
  │                     │
  │                     └──require_approval()──▶ AwaitingApproval
  │                                                  │
  │                                                  ├──approve()──▶ AwaitingToolCall
  │                                                  │
  │                                                  └──deny()──▶ Finished
  │
  └──infer()──▶ Finished (when no tool calls)

Example

use bob_runtime::typestate::*;

// High-level: run to completion
let result = AgentRunner::new(context, llm, tools)
    .run_to_completion()
    .await?;

// Low-level: step-by-step control
let runner = AgentRunner::new(context, llm, tools);
let step = runner.infer().await?;
match step {
    AgentStepResult::Finished(runner) => {
        println!("done: {}", runner.response().content);
    }
    AgentStepResult::RequiresTool(runner) => {
        // Human-in-the-loop: ask for approval
        let results = execute_tools_with_approval(runner.pending_calls()).await;
        let runner = runner.provide_tool_results(results);
        // Continue to next step...
    }
}

Structs

AgentRunner

Typestate-parameterized agent runner.

AwaitingApproval

Agent is waiting for human approval before executing tool calls.

AwaitingToolCall

Agent has requested tool calls and is waiting for results.

Finished

Agent has finished execution with a final response.

Ready

Agent is ready to perform LLM inference.

RunnerContext

Immutable execution context carried through the typestate machine.

Enums

AgentStepResult

Result of an inference step — either finished or needs tools.