Struct Runtime 

pub struct Runtime {
    pub store: MemoryStore,
    pub registry: ToolRegistry,
    pub budget: BudgetLimits,
    pub sandbox: Box<dyn SandboxExecutor>,
}

Fields

store: MemoryStore

registry: ToolRegistry

budget: BudgetLimits

sandbox: Box<dyn SandboxExecutor>

Implementations

impl Runtime

pub fn new() -> Self

Examples found in repository

examples/three_minute_demo.rs (line 21)

fn main() -> agentledger::Result<()> {
    let mut runtime = Runtime::new();
    runtime.register_tool(
        ToolSpec::new(
            "ticket.create",
            Box::new(|args| {
                Ok(Value::Object(state(&[
                    ("external_id", "TICKET-1".into()),
                    ("title", args["title"].clone()),
                ])))
            }),
        )
        .side_effect("external_write")
        .idempotency_required(true)
        .input_schema(Value::Object(state(&[
            ("type", "object".into()),
            (
                "required",
                Value::Array(vec![Value::String("title".to_string())]),
            ),
        ]))),
    );
    let (run_id, _) = runtime.create_run(State::new());

    let first_claim = runtime.store.claim_step("worker-before-crash", &run_id, 60.0)?;
    let first_ctx = AgentContext {
        run_id: run_id.clone(),
        session_id: first_claim.session_id.clone(),
        step_id: first_claim.step_id.clone(),
        agent_role: "SupportAgent".to_string(),
        lease_token: first_claim.lease_token.clone(),
        attempt: first_claim.attempt,
        state_version: first_claim.state_version,
        pending_patch: State::new(),
    };
    let ticket = runtime.call_tool(
        &first_ctx,
        "ticket.create",
        state(&[
            ("title", "Investigate failed payment".into()),
            ("_logical_operation", "open-payment-ticket".into()),
        ]),
    )?;
    runtime.store.mark_retry(
        &run_id,
        &first_ctx.step_id,
        "RetryableAgentError",
        "after external ticket create, before state commit",
    );

    let second_claim = runtime.store.claim_step("worker-after-restart", &run_id, 60.0)?;
    let mut second_ctx = AgentContext {
        run_id: run_id.clone(),
        session_id: second_claim.session_id.clone(),
        step_id: second_claim.step_id.clone(),
        agent_role: "SupportAgent".to_string(),
        lease_token: second_claim.lease_token.clone(),
        attempt: second_claim.attempt,
        state_version: second_claim.state_version,
        pending_patch: State::new(),
    };
    let replayed_ticket = runtime.call_tool(
        &second_ctx,
        "ticket.create",
        state(&[
            ("title", "Investigate failed payment".into()),
            ("_logical_operation", "open-payment-ticket".into()),
        ]),
    )?;
    second_ctx.write_state("ticket", replayed_ticket);
    second_ctx.write_state("recovered", true.into());
    runtime.store.commit_state_patch(
        &run_id,
        &second_ctx.step_id,
        &second_ctx.lease_token,
        second_ctx.state_version,
        second_ctx.pending_patch,
    )?;

    let summary = replay(&runtime.store, &run_id)?;
    let ledger = runtime.store.ledger(&run_id);
    let final_state = runtime.store.final_state(&run_id)?;
    println!(
        "{{\n  \"run_id\": \"{}\",\n  \"first_attempt_ok\": false,\n  \"second_attempt_ok\": true,\n  \"external_ticket_count\": 1,\n  \"actual_tool_executions\": 1,\n  \"tool_ledger_count\": {},\n  \"tool_ledger_status\": \"{}\",\n  \"first_ticket_external_id\": \"{}\",\n  \"final_state_recovered\": {},\n  \"replay\": {{\n    \"safe\": {},\n    \"event_count\": {},\n    \"tool_call_count\": {}\n  }}\n}}",
        run_id,
        ledger.len(),
        ledger.first().map(|row| row.status.as_str()).unwrap_or(""),
        get_string(&ticket, "external_id"),
        final_state.get("recovered") == Some(&Value::Bool(true)),
        summary.replay_safe,
        summary.event_count,
        summary.tool_call_count
    );
    Ok(())
}

examples/mcp_governance.rs (line 34)

fn main() -> agentledger::Result<()> {
    let mut runtime = Runtime::new();
    runtime.set_sandbox(Box::new(DemoSandboxExecutor));
    let mut server = InMemoryMCPToolServer::new();
    server.add_tool(
        state(&[
            ("name", "mcp.github.create_pr".into()),
            (
                "inputSchema",
                Value::Object(state(&[
                    ("type", "object".into()),
                    (
                        "required",
                        Value::Array(vec![Value::String("title".to_string())]),
                    ),
                    (
                        "properties",
                        Value::Object(state(&[(
                            "title",
                            Value::Object(state(&[
                                ("type", "string".into()),
                                ("minLength", 1_i64.into()),
                            ])),
                        )])),
                    ),
                ])),
            ),
            (
                "annotations",
                Value::Object(state(&[
                    ("side_effect", "external_write".into()),
                    ("risk_level", "high".into()),
                    ("idempotency_required", true.into()),
                    ("approval_required", true.into()),
                    ("sandbox_required", true.into()),
                    (
                        "sandbox_policy",
                        Value::Object(state(&[
                            ("network", "deny".into()),
                            ("filesystem", "read-only".into()),
                        ])),
                    ),
                ])),
            ),
        ]),
        create_pr,
    );
    let adapter = MCPToolAdapter { client_call: create_pr };
    for descriptor in server.list_tools() {
        runtime.register_tool(adapter.tool_spec_from_descriptor(&descriptor));
    }

    let (run_id, _) = runtime.create_run(State::new());
    let first_claim = runtime.store.claim_step("worker-before-approval", &run_id, 60.0)?;
    let first_ctx = AgentContext {
        run_id: run_id.clone(),
        session_id: first_claim.session_id.clone(),
        step_id: first_claim.step_id.clone(),
        agent_role: "MCPAgent".to_string(),
        lease_token: first_claim.lease_token.clone(),
        attempt: first_claim.attempt,
        state_version: first_claim.state_version,
        pending_patch: State::new(),
    };
    let first = runtime.call_tool(
        &first_ctx,
        "mcp.github.create_pr",
        state(&[
            ("title", "Update runtime docs".into()),
            ("_logical_operation", "docs-pr".into()),
        ]),
    );
    let approval_id = first
        .unwrap_err()
        .0
        .trim_start_matches("approval required:")
        .to_string();
    runtime.store.mark_waiting_human(
        &run_id,
        &first_ctx.step_id,
        "approval required for tool mcp.github.create_pr",
        &approval_id,
    );
    runtime
        .store
        .approve_request(&approval_id, "maintainer", "demo approval")?;

    let second_claim = runtime.store.claim_step("worker-after-approval", &run_id, 60.0)?;
    let mut second_ctx = AgentContext {
        run_id: run_id.clone(),
        session_id: second_claim.session_id.clone(),
        step_id: second_claim.step_id.clone(),
        agent_role: "MCPAgent".to_string(),
        lease_token: second_claim.lease_token.clone(),
        attempt: second_claim.attempt,
        state_version: second_claim.state_version,
        pending_patch: State::new(),
    };
    let result = runtime.call_tool(
        &second_ctx,
        "mcp.github.create_pr",
        state(&[
            ("title", "Update runtime docs".into()),
            ("_logical_operation", "docs-pr".into()),
        ]),
    )?;
    second_ctx.write_state("pull_request", result);
    runtime.store.commit_state_patch(
        &run_id,
        &second_ctx.step_id,
        &second_ctx.lease_token,
        second_ctx.state_version,
        second_ctx.pending_patch,
    )?;

    let approvals = runtime.store.approval_requests(&run_id);
    println!(
        "{{\n  \"run_id\": \"{}\",\n  \"first_attempt_waited_for_approval\": true,\n  \"second_attempt_ok\": true,\n  \"approval_count\": {},\n  \"approval_status\": \"{}\",\n  \"external_action_count\": 1,\n  \"final_state_has_pull_request\": {}\n}}",
        run_id,
        approvals.len(),
        approvals.first().map(|row| row.status.as_str()).unwrap_or(""),
        runtime
            .store
            .final_state(&run_id)?
            .contains_key("pull_request")
    );
    Ok(())
}

examples/omp_bridge.rs (line 14)

fn main() -> agentledger::Result<()> {
    let runtime = Runtime::new();
    let mut bridge = OmpLedgerBridge::new(runtime, "omp-demo");
    let run_id = bridge.record_session_started(OmpSession {
        session_id: "omp-session-1".to_string(),
        initial_state: state(&[("task", "review contract".into())]),
        metadata: state(&[("runtime", "synthetic-omp".into())]),
        ..Default::default()
    })?;
    bridge.record_turn_started(OmpTurn {
        session_id: "omp-session-1".to_string(),
        turn_id: "turn-1".to_string(),
        agent_role: "OMPPlanner".to_string(),
        metadata: state(&[("phase", "planning".into())]),
        ..Default::default()
    })?;
    bridge.record_model_call(OmpModelCall {
        session_id: "omp-session-1".to_string(),
        turn_id: "turn-1".to_string(),
        provider: "openai-compatible-gateway".to_string(),
        model: "legal-router".to_string(),
        request: state(&[(
            "messages",
            Value::Array(vec![Value::Object(state(&[
                ("role", "user".into()),
                ("content", "find payment clause".into()),
            ]))]),
        )]),
        response: state(&[(
            "tool_calls",
            Value::Array(vec![Value::Object(state(&[
                ("name", "contract.search".into()),
                (
                    "arguments",
                    Value::Object(state(&[("clause", "payment".into())])),
                ),
            ]))]),
        )]),
        usage: state(&[
            ("input_tokens", Value::Number(12.0)),
            ("output_tokens", Value::Number(7.0)),
            ("total_tokens", Value::Number(19.0)),
        ]),
        total_usd: 0.003,
        ..Default::default()
    })?;
    bridge.record_tool_proposal(OmpToolProposal {
        session_id: "omp-session-1".to_string(),
        turn_id: "turn-1".to_string(),
        tool_name: "contract.search".to_string(),
        arguments: state(&[("clause", "payment".into())]),
        provider: Some("openai-compatible-gateway".to_string()),
        model: Some("legal-router".to_string()),
        reason: Some("model proposed a contract search".to_string()),
        ..Default::default()
    })?;
    bridge.record_tool_execution(OmpToolExecution {
        session_id: "omp-session-1".to_string(),
        turn_id: "turn-1".to_string(),
        tool_name: "contract.search".to_string(),
        arguments: state(&[("clause", "payment".into())]),
        result: Some(Value::Object(state(&[
            ("matches", Value::Array(vec!["Section 9.2".into()])),
            ("external_id", "search-001".into()),
        ]))),
        ledger_status: Some("SUCCEEDED".to_string()),
        ..Default::default()
    })?;
    bridge.record_state_change(OmpStateChange {
        session_id: "omp-session-1".to_string(),
        turn_id: Some("turn-1".to_string()),
        reason: "persist normalized runtime-adjacent state".to_string(),
        patch: state(&[("memory_version", Value::Number(1.0))]),
        before_snapshot: Some(Value::Object(state(&[("memory_version", Value::Number(0.0))]))),
        after_snapshot: Some(Value::Object(state(&[("memory_version", Value::Number(1.0))]))),
        diff: Some(Value::Object(state(&[(
            "memory_version",
            Value::Array(vec![Value::Number(0.0), Value::Number(1.0)]),
        )]))),
        ..Default::default()
    })?;
    bridge.record_turn_completed(OmpTurn {
        session_id: "omp-session-1".to_string(),
        turn_id: "turn-1".to_string(),
        state_patch: state(&[("last_tool", "contract.search".into())]),
        ..Default::default()
    })?;

    let events = bridge
        .runtime
        .store
        .events(&run_id)
        .iter()
        .map(|event| event.event_type.clone())
        .collect::<Vec<_>>();
    let final_state = bridge.runtime.store.final_state(&run_id)?;
    let rendered_events = format!("{:?}", events);
    let memory_version = match final_state.get("memory_version") {
        Some(Value::Number(value)) => *value,
        _ => 0.0,
    };
    let last_tool = match final_state.get("last_tool") {
        Some(Value::String(value)) => value.as_str(),
        _ => "",
    };
    println!(
        concat!(
            "{{\n",
            "  \"run_id\": \"{}\",\n",
            "  \"events\": {},\n",
            "  \"tool_ledger_count\": {},\n",
            "  \"final_state_memory_version\": {},\n",
            "  \"final_state_last_tool\": \"{}\"\n",
            "}}"
        ),
        run_id,
        rendered_events,
        bridge.runtime.store.ledger(&run_id).len(),
        memory_version,
        last_tool
    );
    Ok(())
}

examples/travel_assistant.rs (line 505)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args: Vec<String> = std::env::args().collect();
    let root = if args.len() > 1 {
        PathBuf::from(&args[1])
    } else {
        std::env::temp_dir().join(format!("agentledger-rust-{}", std::process::id()))
    };
    let _ = fs::create_dir_all(&root);

    // Intro
    println!(
        "\n{}{}  ╔════════════════════════════════════════════════════╗{}",
        C_BOLD, C_C, C_RST
    );
    println!(
        "{}{}  ║   AgentLedger Travel Assistant (Rust) — Interactive Demo  ║{}",
        C_BOLD, C_C, C_RST
    );
    println!(
        "{}{}  ║   See real database state at every step                 ║{}",
        C_BOLD, C_C, C_RST
    );
    println!(
        "{}{}  ╚════════════════════════════════════════════════════╝{}",
        C_BOLD, C_C, C_RST
    );

    println!(
        "\n  {}AgentLedger — Durable Execution Runtime for AI Agents{}",
        C_DIM, C_RST
    );
    println!("  ┌────────────────────────────────────────────────────┐");
    println!(
        "  │  {}✓{} Durable execution — crash recovery              │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Tool Ledger — idempotent replay                │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Approval gates — human-in-the-loop              │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Policy engine — risk-based access               │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Budget control — tool call limits               │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Evidence export — full audit trail              │",
        C_G, C_RST
    );
    println!("  └────────────────────────────────────────────────────┘");

    wait("Press Enter to start / 按 Enter 开始");

    // ════════════════════════════════════════════════════════
    // Step 1: Setup
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_B,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 1: Initialize — Register tools, configure policy{}",
        C_BOLD, C_B, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_B,
        "═".repeat(60)
    );

    let mut runtime = Runtime::new();
    runtime.set_budget(BudgetLimits {
        max_tool_calls: Some(25.0),
        max_model_tokens: None,
        max_total_usd: None,
    });

    // Register tools
    runtime.register_tool(
        ToolSpec::new("travel.search_flights", Box::new(search_flights))
            .side_effect("none")
            .risk_level("low")
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                (
                    "required",
                    Value::Array(vec!["from".into(), "to".into()]),
                ),
            ]))),
    );
    runtime.register_tool(
        ToolSpec::new("travel.search_hotels", Box::new(search_hotels))
            .side_effect("none")
            .risk_level("low")
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                ("required", Value::Array(vec!["city".into()])),
            ]))),
    );
    runtime.register_tool(
        ToolSpec::new("travel.check_weather", Box::new(check_weather))
            .side_effect("none")
            .risk_level("low")
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                ("required", Value::Array(vec!["city".into()])),
            ]))),
    );
    runtime.register_tool(
        ToolSpec::new("travel.book_flight", Box::new(book_flight))
            .side_effect("external_write")
            .risk_level("high")
            .idempotency_required(true)
            .approval_required(true)
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                (
                    "required",
                    Value::Array(vec!["flight_id".into(), "passenger".into()]),
                ),
            ]))),
    );
    runtime.register_tool(
        ToolSpec::new("travel.book_hotel", Box::new(book_hotel))
            .side_effect("external_write")
            .risk_level("high")
            .idempotency_required(true)
            .approval_required(true)
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                (
                    "required",
                    Value::Array(vec!["hotel_id".into(), "guest".into()]),
                ),
            ]))),
    );

    println!("\n  {}Registered 5 tools:{}", C_C, C_RST);
    for (name, risk, approval) in [
        ("travel.search_flights", "low", false),
        ("travel.search_hotels", "low", false),
        ("travel.check_weather", "low", false),
        ("travel.book_flight", "high", true),
        ("travel.book_hotel", "high", true),
    ] {
        let rc = if risk == "low" { C_G } else { C_R };
        let ac = if approval {
            format!("{}needs approval{}", C_R, C_RST)
        } else {
            format!("{}no approval{}", C_G, C_RST)
        };
        println!(
            "    {}•{} {}  [{}{}{}] [{}]",
            C_DIM, C_RST, name, rc, risk, C_RST, ac
        );
    }
    println!(
        "  {}Policy: Rust uses risk-based policy (low=allow, high=deny+approval){}",
        C_DIM, C_RST
    );
    println!("  {}Budget: max 25 tool calls{}", C_DIM, C_RST);

    let (run_id, _step_id) = runtime.create_run(make_state(&[
        ("trip", "Tokyo".into()),
        ("budget_usd", Value::Number(3000.0)),
    ]));
    println!(
        "\n  {}Run created: {}{}{}",
        C_B, C_BOLD, run_id, C_RST
    );
    show_db(&runtime.store, &run_id);
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 2: Attempt 1 — Approval interception
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_R,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 2: Attempt 1 — Agent runs → Approval triggered{}",
        C_BOLD, C_R, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_R,
        "═".repeat(60)
    );
    println!(
        "\n  {}Agent executing: search flights → search hotels → check weather → book flight...{}",
        C_DIM, C_RST
    );

    {
        let mut ctx = claim_context(&mut runtime, &run_id, "worker-rust", "TravelPlanner");
        let result = travel_planner(&mut runtime, &mut ctx, 1);
        match result {
            Err(err) if err.0.starts_with("approval required:") => {
                let approval_id = err.0.trim_start_matches("approval required:");
                runtime
                    .store
                    .mark_waiting_human(&run_id, &ctx.step_id, &err.0, approval_id);
            }
            Err(err) => return Err(format!("unexpected error at step 2: {}", err.0).into()),
            Ok(()) => {}
        }
    }

    println!(
        "\n  {}book_flight triggered approval! Runtime paused, waiting for human.{}",
        C_R, C_RST
    );
    show_db(&runtime.store, &run_id);
    println!(
        "  {}Note: Tool Ledger has RESERVED entry, approval status is PENDING{}",
        C_R, C_RST
    );
    wait("Press Enter to approve / 按 Enter 审批");

    for req in runtime.store.approval_requests(&run_id) {
        if req.status == "PENDING" {
            runtime
                .store
                .approve_request(&req.approval_id, "traveler", "Within budget, approved")?;
            println!(
                "\n  {}✅ Approved: {} — by traveler{}",
                C_G, req.tool_name, C_RST
            );
        }
    }
    show_db(&runtime.store, &run_id);
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 3: Attempt 2 — Execute + Crash
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_Y,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 3: Attempt 2 — Approved → Execute booking → Simulated crash{}",
        C_BOLD, C_Y, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_Y,
        "═".repeat(60)
    );
    println!(
        "\n  {}Re-running agent (approval passed, book_flight will execute)...{}",
        C_DIM, C_RST
    );

    {
        let mut ctx = claim_context(&mut runtime, &run_id, "worker-rust", "TravelPlanner");
        let result = travel_planner(&mut runtime, &mut ctx, 2);
        match result {
            Err(err) if err.0 == "retryable" => {
                runtime.store.mark_retry(
                    &run_id,
                    &ctx.step_id,
                    "RetryableAgentError",
                    "after flight booking",
                );
            }
            Err(err) if err.0.starts_with("approval required:") => {
                let approval_id = err.0.trim_start_matches("approval required:");
                runtime
                    .store
                    .mark_waiting_human(&run_id, &ctx.step_id, &err.0, approval_id);
            }
            Err(err) => return Err(format!("unexpected error at step 3: {}", err.0).into()),
            Ok(()) => {}
        }
    }

    println!(
        "\n  {}Agent booked flight, then crashed before committing state!{}",
        C_Y, C_RST
    );
    println!(
        "  {}Flight is booked in external system, but agent state was NOT persisted.{}",
        C_Y, C_RST
    );
    show_db(&runtime.store, &run_id);
    println!(
        "  {}Key: Tool Ledger book_flight status = {}SUCCEEDED{} (external side effect executed){}",
        C_Y, C_G, C_Y, C_RST
    );
    println!(
        "  {}      Step status = retry_scheduled (state not committed, waiting for retry){}",
        C_Y, C_RST
    );
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 4: Attempt 3 — Recovery + Hotel approval
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 4: Attempt 3 — Crash recovery → Tool Ledger idempotent replay{}",
        C_BOLD, C_G, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "\n  {}Agent re-executes. book_flight: Tool Ledger sees SUCCEEDED record...{}",
        C_DIM, C_RST
    );
    println!(
        "  {}{}→ Returns cached result, no duplicate API call, no double charge!{}",
        C_DIM, C_G, C_RST
    );

    {
        let mut ctx = claim_context(&mut runtime, &run_id, "worker-rust", "TravelPlanner");
        let result = travel_planner(&mut runtime, &mut ctx, 3);
        match result {
            Err(err) if err.0.starts_with("approval required:") => {
                let approval_id = err.0.trim_start_matches("approval required:");
                runtime
                    .store
                    .mark_waiting_human(&run_id, &ctx.step_id, &err.0, approval_id);
            }
            Err(err) => return Err(format!("unexpected error at step 4: {}", err.0).into()),
            Ok(()) => {}
        }
    }

    println!(
        "\n  {}✅ Flight idempotent replay successful! (no duplicate _book_flight call){}",
        C_G, C_RST
    );
    println!("  {}Hotel booking → triggers approval again{}", C_R, C_RST);

    for req in runtime.store.approval_requests(&run_id) {
        if req.status == "PENDING" {
            runtime
                .store
                .approve_request(&req.approval_id, "traveler", "Hotel within budget, approved")?;
            println!(
                "\n  {}✅ Approved: {} — by traveler{}",
                C_G, req.tool_name, C_RST
            );
        }
    }
    show_db(&runtime.store, &run_id);
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 5: Attempt 4 — Complete
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 5: Attempt 4 — Hotel approved → Full execution → State committed{}",
        C_BOLD, C_G, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );

    {
        let mut ctx = claim_context(&mut runtime, &run_id, "worker-rust", "TravelPlanner");
        travel_planner(&mut runtime, &mut ctx, 4)?;
        runtime.store.commit_state_patch(
            &run_id,
            &ctx.step_id,
            &ctx.lease_token,
            ctx.state_version,
            ctx.pending_patch,
        )?;
    }

    {
        let db = BOOKING_DB.lock().unwrap();
        if db.len() != 2 {
            return Err(format!("Expected 2 bookings, got {}", db.len()).into());
        }
    }

    println!(
        "\n  {}✅ Travel planning complete! State persisted to database.{}",
        C_G, C_RST
    );
    show_db(&runtime.store, &run_id);
    println!(
        "  {}Step status = completed, State has bookings + trip_status{}",
        C_G, C_RST
    );
    let db = BOOKING_DB.lock().unwrap();
    let keys: Vec<String> = db.keys().cloned().collect();
    println!(
        "  {}External bookings: {:?} ({} total, no duplicates){}",
        C_G,
        keys,
        keys.len(),
        C_RST
    );
    drop(db);
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 6: Evidence + Cost + Replay
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_M,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 6: Evidence export + Cost attribution + Replay verification{}",
        C_BOLD, C_M, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_M,
        "═".repeat(60)
    );

    let bundle = export_evidence(&runtime.store, &run_id)?;
    let replay_result = replay(&runtime.store, &run_id)?;
    let cost = agentledger::cost_attribution(&runtime.store, &run_id);

    println!(
        "\n  {}Cost attribution: {} tool calls{}",
        C_M, cost.total.tool_calls, C_RST
    );
    println!(
        "  {}Replay: {} events, safe={}{}{}",
        C_M, replay_result.event_count, C_G, replay_result.replay_safe, C_RST
    );
    println!(
        "  {}Evidence bundle: {} events total{}",
        C_M,
        bundle.events.len(),
        C_RST
    );

    // Write evidence HTML
    let html_path = root.join("evidence.html");
    let html = debug_html(&bundle);
    fs::write(&html_path, html)?;
    let html_abs = html_path.canonicalize().unwrap_or_else(|_| html_path.clone());

    // Final summary
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "{}{}  Summary: What AgentLedger (Rust) did in this demo{}",
        C_BOLD, C_G, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "
  ┌──────────────────────────────────────────────────────────┐
  │                                                          │
  │  {g}✓ Durable execution{rst}  Crash → auto retry, state preserved         │
  │                   Step: retry_scheduled → completed           │
  │                                                          │
  │  {g}✓ Tool Ledger{rst}      Idempotent replay, flight booked {bold}1x{rst} only       │
  │                   SUCCEEDED → cached result on retry        │
  │                                                          │
  │  {g}✓ Approval gates{rst}    Flight + hotel each trigger approval          │
  │                   approval_requests records in store        │
  │                                                          │
  │  {g}✓ Policy engine{rst}     Risk-based policy (high → deny+approval)     │
  │                   low-risk tools auto-allowed              │
  │                                                          │
  │  {g}✓ Budget control{rst}    Tracked {tc} tool calls                       │
  │                   BudgetController.before_tool_call()       │
  │                                                          │
  │  {g}✓ Evidence export{rst}   {ec} events recorded                         │
  │                   events stored in memory store             │
  │                                                          │
  │  {g}✓ Cost attribution{rst}  Auto-recorded per run                        │
  │                   CostAttribution by agent                │
  │                                                          │
  │  {g}✓ Replay engine{rst}     Event hash verification passed                │
  │                   Verify history without re-running       │
  │                                                          │
  └──────────────────────────────────────────────────────────┘
",
        g = C_G,
        rst = C_RST,
        bold = C_BOLD,
        tc = cost.total.tool_calls,
        ec = bundle.events.len()
    );

    println!("  {}Storage: in-memory (MemoryStore){}", C_DIM, C_RST);
    println!("  {}Evidence HTML: {:?}{}", C_DIM, html_abs, C_RST);
    println!();

    Ok(())
}

pub fn register_tool(&mut self, spec: ToolSpec)

Examples found in repository

examples/three_minute_demo.rs (lines 22-41)

fn main() -> agentledger::Result<()> {
    let mut runtime = Runtime::new();
    runtime.register_tool(
        ToolSpec::new(
            "ticket.create",
            Box::new(|args| {
                Ok(Value::Object(state(&[
                    ("external_id", "TICKET-1".into()),
                    ("title", args["title"].clone()),
                ])))
            }),
        )
        .side_effect("external_write")
        .idempotency_required(true)
        .input_schema(Value::Object(state(&[
            ("type", "object".into()),
            (
                "required",
                Value::Array(vec![Value::String("title".to_string())]),
            ),
        ]))),
    );
    let (run_id, _) = runtime.create_run(State::new());

    let first_claim = runtime.store.claim_step("worker-before-crash", &run_id, 60.0)?;
    let first_ctx = AgentContext {
        run_id: run_id.clone(),
        session_id: first_claim.session_id.clone(),
        step_id: first_claim.step_id.clone(),
        agent_role: "SupportAgent".to_string(),
        lease_token: first_claim.lease_token.clone(),
        attempt: first_claim.attempt,
        state_version: first_claim.state_version,
        pending_patch: State::new(),
    };
    let ticket = runtime.call_tool(
        &first_ctx,
        "ticket.create",
        state(&[
            ("title", "Investigate failed payment".into()),
            ("_logical_operation", "open-payment-ticket".into()),
        ]),
    )?;
    runtime.store.mark_retry(
        &run_id,
        &first_ctx.step_id,
        "RetryableAgentError",
        "after external ticket create, before state commit",
    );

    let second_claim = runtime.store.claim_step("worker-after-restart", &run_id, 60.0)?;
    let mut second_ctx = AgentContext {
        run_id: run_id.clone(),
        session_id: second_claim.session_id.clone(),
        step_id: second_claim.step_id.clone(),
        agent_role: "SupportAgent".to_string(),
        lease_token: second_claim.lease_token.clone(),
        attempt: second_claim.attempt,
        state_version: second_claim.state_version,
        pending_patch: State::new(),
    };
    let replayed_ticket = runtime.call_tool(
        &second_ctx,
        "ticket.create",
        state(&[
            ("title", "Investigate failed payment".into()),
            ("_logical_operation", "open-payment-ticket".into()),
        ]),
    )?;
    second_ctx.write_state("ticket", replayed_ticket);
    second_ctx.write_state("recovered", true.into());
    runtime.store.commit_state_patch(
        &run_id,
        &second_ctx.step_id,
        &second_ctx.lease_token,
        second_ctx.state_version,
        second_ctx.pending_patch,
    )?;

    let summary = replay(&runtime.store, &run_id)?;
    let ledger = runtime.store.ledger(&run_id);
    let final_state = runtime.store.final_state(&run_id)?;
    println!(
        "{{\n  \"run_id\": \"{}\",\n  \"first_attempt_ok\": false,\n  \"second_attempt_ok\": true,\n  \"external_ticket_count\": 1,\n  \"actual_tool_executions\": 1,\n  \"tool_ledger_count\": {},\n  \"tool_ledger_status\": \"{}\",\n  \"first_ticket_external_id\": \"{}\",\n  \"final_state_recovered\": {},\n  \"replay\": {{\n    \"safe\": {},\n    \"event_count\": {},\n    \"tool_call_count\": {}\n  }}\n}}",
        run_id,
        ledger.len(),
        ledger.first().map(|row| row.status.as_str()).unwrap_or(""),
        get_string(&ticket, "external_id"),
        final_state.get("recovered") == Some(&Value::Bool(true)),
        summary.replay_safe,
        summary.event_count,
        summary.tool_call_count
    );
    Ok(())
}

examples/mcp_governance.rs (line 82)

fn main() -> agentledger::Result<()> {
    let mut runtime = Runtime::new();
    runtime.set_sandbox(Box::new(DemoSandboxExecutor));
    let mut server = InMemoryMCPToolServer::new();
    server.add_tool(
        state(&[
            ("name", "mcp.github.create_pr".into()),
            (
                "inputSchema",
                Value::Object(state(&[
                    ("type", "object".into()),
                    (
                        "required",
                        Value::Array(vec![Value::String("title".to_string())]),
                    ),
                    (
                        "properties",
                        Value::Object(state(&[(
                            "title",
                            Value::Object(state(&[
                                ("type", "string".into()),
                                ("minLength", 1_i64.into()),
                            ])),
                        )])),
                    ),
                ])),
            ),
            (
                "annotations",
                Value::Object(state(&[
                    ("side_effect", "external_write".into()),
                    ("risk_level", "high".into()),
                    ("idempotency_required", true.into()),
                    ("approval_required", true.into()),
                    ("sandbox_required", true.into()),
                    (
                        "sandbox_policy",
                        Value::Object(state(&[
                            ("network", "deny".into()),
                            ("filesystem", "read-only".into()),
                        ])),
                    ),
                ])),
            ),
        ]),
        create_pr,
    );
    let adapter = MCPToolAdapter { client_call: create_pr };
    for descriptor in server.list_tools() {
        runtime.register_tool(adapter.tool_spec_from_descriptor(&descriptor));
    }

    let (run_id, _) = runtime.create_run(State::new());
    let first_claim = runtime.store.claim_step("worker-before-approval", &run_id, 60.0)?;
    let first_ctx = AgentContext {
        run_id: run_id.clone(),
        session_id: first_claim.session_id.clone(),
        step_id: first_claim.step_id.clone(),
        agent_role: "MCPAgent".to_string(),
        lease_token: first_claim.lease_token.clone(),
        attempt: first_claim.attempt,
        state_version: first_claim.state_version,
        pending_patch: State::new(),
    };
    let first = runtime.call_tool(
        &first_ctx,
        "mcp.github.create_pr",
        state(&[
            ("title", "Update runtime docs".into()),
            ("_logical_operation", "docs-pr".into()),
        ]),
    );
    let approval_id = first
        .unwrap_err()
        .0
        .trim_start_matches("approval required:")
        .to_string();
    runtime.store.mark_waiting_human(
        &run_id,
        &first_ctx.step_id,
        "approval required for tool mcp.github.create_pr",
        &approval_id,
    );
    runtime
        .store
        .approve_request(&approval_id, "maintainer", "demo approval")?;

    let second_claim = runtime.store.claim_step("worker-after-approval", &run_id, 60.0)?;
    let mut second_ctx = AgentContext {
        run_id: run_id.clone(),
        session_id: second_claim.session_id.clone(),
        step_id: second_claim.step_id.clone(),
        agent_role: "MCPAgent".to_string(),
        lease_token: second_claim.lease_token.clone(),
        attempt: second_claim.attempt,
        state_version: second_claim.state_version,
        pending_patch: State::new(),
    };
    let result = runtime.call_tool(
        &second_ctx,
        "mcp.github.create_pr",
        state(&[
            ("title", "Update runtime docs".into()),
            ("_logical_operation", "docs-pr".into()),
        ]),
    )?;
    second_ctx.write_state("pull_request", result);
    runtime.store.commit_state_patch(
        &run_id,
        &second_ctx.step_id,
        &second_ctx.lease_token,
        second_ctx.state_version,
        second_ctx.pending_patch,
    )?;

    let approvals = runtime.store.approval_requests(&run_id);
    println!(
        "{{\n  \"run_id\": \"{}\",\n  \"first_attempt_waited_for_approval\": true,\n  \"second_attempt_ok\": true,\n  \"approval_count\": {},\n  \"approval_status\": \"{}\",\n  \"external_action_count\": 1,\n  \"final_state_has_pull_request\": {}\n}}",
        run_id,
        approvals.len(),
        approvals.first().map(|row| row.status.as_str()).unwrap_or(""),
        runtime
            .store
            .final_state(&run_id)?
            .contains_key("pull_request")
    );
    Ok(())
}

examples/travel_assistant.rs (lines 513-524)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args: Vec<String> = std::env::args().collect();
    let root = if args.len() > 1 {
        PathBuf::from(&args[1])
    } else {
        std::env::temp_dir().join(format!("agentledger-rust-{}", std::process::id()))
    };
    let _ = fs::create_dir_all(&root);

    // Intro
    println!(
        "\n{}{}  ╔════════════════════════════════════════════════════╗{}",
        C_BOLD, C_C, C_RST
    );
    println!(
        "{}{}  ║   AgentLedger Travel Assistant (Rust) — Interactive Demo  ║{}",
        C_BOLD, C_C, C_RST
    );
    println!(
        "{}{}  ║   See real database state at every step                 ║{}",
        C_BOLD, C_C, C_RST
    );
    println!(
        "{}{}  ╚════════════════════════════════════════════════════╝{}",
        C_BOLD, C_C, C_RST
    );

    println!(
        "\n  {}AgentLedger — Durable Execution Runtime for AI Agents{}",
        C_DIM, C_RST
    );
    println!("  ┌────────────────────────────────────────────────────┐");
    println!(
        "  │  {}✓{} Durable execution — crash recovery              │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Tool Ledger — idempotent replay                │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Approval gates — human-in-the-loop              │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Policy engine — risk-based access               │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Budget control — tool call limits               │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Evidence export — full audit trail              │",
        C_G, C_RST
    );
    println!("  └────────────────────────────────────────────────────┘");

    wait("Press Enter to start / 按 Enter 开始");

    // ════════════════════════════════════════════════════════
    // Step 1: Setup
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_B,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 1: Initialize — Register tools, configure policy{}",
        C_BOLD, C_B, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_B,
        "═".repeat(60)
    );

    let mut runtime = Runtime::new();
    runtime.set_budget(BudgetLimits {
        max_tool_calls: Some(25.0),
        max_model_tokens: None,
        max_total_usd: None,
    });

    // Register tools
    runtime.register_tool(
        ToolSpec::new("travel.search_flights", Box::new(search_flights))
            .side_effect("none")
            .risk_level("low")
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                (
                    "required",
                    Value::Array(vec!["from".into(), "to".into()]),
                ),
            ]))),
    );
    runtime.register_tool(
        ToolSpec::new("travel.search_hotels", Box::new(search_hotels))
            .side_effect("none")
            .risk_level("low")
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                ("required", Value::Array(vec!["city".into()])),
            ]))),
    );
    runtime.register_tool(
        ToolSpec::new("travel.check_weather", Box::new(check_weather))
            .side_effect("none")
            .risk_level("low")
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                ("required", Value::Array(vec!["city".into()])),
            ]))),
    );
    runtime.register_tool(
        ToolSpec::new("travel.book_flight", Box::new(book_flight))
            .side_effect("external_write")
            .risk_level("high")
            .idempotency_required(true)
            .approval_required(true)
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                (
                    "required",
                    Value::Array(vec!["flight_id".into(), "passenger".into()]),
                ),
            ]))),
    );
    runtime.register_tool(
        ToolSpec::new("travel.book_hotel", Box::new(book_hotel))
            .side_effect("external_write")
            .risk_level("high")
            .idempotency_required(true)
            .approval_required(true)
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                (
                    "required",
                    Value::Array(vec!["hotel_id".into(), "guest".into()]),
                ),
            ]))),
    );

    println!("\n  {}Registered 5 tools:{}", C_C, C_RST);
    for (name, risk, approval) in [
        ("travel.search_flights", "low", false),
        ("travel.search_hotels", "low", false),
        ("travel.check_weather", "low", false),
        ("travel.book_flight", "high", true),
        ("travel.book_hotel", "high", true),
    ] {
        let rc = if risk == "low" { C_G } else { C_R };
        let ac = if approval {
            format!("{}needs approval{}", C_R, C_RST)
        } else {
            format!("{}no approval{}", C_G, C_RST)
        };
        println!(
            "    {}•{} {}  [{}{}{}] [{}]",
            C_DIM, C_RST, name, rc, risk, C_RST, ac
        );
    }
    println!(
        "  {}Policy: Rust uses risk-based policy (low=allow, high=deny+approval){}",
        C_DIM, C_RST
    );
    println!("  {}Budget: max 25 tool calls{}", C_DIM, C_RST);

    let (run_id, _step_id) = runtime.create_run(make_state(&[
        ("trip", "Tokyo".into()),
        ("budget_usd", Value::Number(3000.0)),
    ]));
    println!(
        "\n  {}Run created: {}{}{}",
        C_B, C_BOLD, run_id, C_RST
    );
    show_db(&runtime.store, &run_id);
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 2: Attempt 1 — Approval interception
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_R,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 2: Attempt 1 — Agent runs → Approval triggered{}",
        C_BOLD, C_R, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_R,
        "═".repeat(60)
    );
    println!(
        "\n  {}Agent executing: search flights → search hotels → check weather → book flight...{}",
        C_DIM, C_RST
    );

    {
        let mut ctx = claim_context(&mut runtime, &run_id, "worker-rust", "TravelPlanner");
        let result = travel_planner(&mut runtime, &mut ctx, 1);
        match result {
            Err(err) if err.0.starts_with("approval required:") => {
                let approval_id = err.0.trim_start_matches("approval required:");
                runtime
                    .store
                    .mark_waiting_human(&run_id, &ctx.step_id, &err.0, approval_id);
            }
            Err(err) => return Err(format!("unexpected error at step 2: {}", err.0).into()),
            Ok(()) => {}
        }
    }

    println!(
        "\n  {}book_flight triggered approval! Runtime paused, waiting for human.{}",
        C_R, C_RST
    );
    show_db(&runtime.store, &run_id);
    println!(
        "  {}Note: Tool Ledger has RESERVED entry, approval status is PENDING{}",
        C_R, C_RST
    );
    wait("Press Enter to approve / 按 Enter 审批");

    for req in runtime.store.approval_requests(&run_id) {
        if req.status == "PENDING" {
            runtime
                .store
                .approve_request(&req.approval_id, "traveler", "Within budget, approved")?;
            println!(
                "\n  {}✅ Approved: {} — by traveler{}",
                C_G, req.tool_name, C_RST
            );
        }
    }
    show_db(&runtime.store, &run_id);
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 3: Attempt 2 — Execute + Crash
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_Y,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 3: Attempt 2 — Approved → Execute booking → Simulated crash{}",
        C_BOLD, C_Y, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_Y,
        "═".repeat(60)
    );
    println!(
        "\n  {}Re-running agent (approval passed, book_flight will execute)...{}",
        C_DIM, C_RST
    );

    {
        let mut ctx = claim_context(&mut runtime, &run_id, "worker-rust", "TravelPlanner");
        let result = travel_planner(&mut runtime, &mut ctx, 2);
        match result {
            Err(err) if err.0 == "retryable" => {
                runtime.store.mark_retry(
                    &run_id,
                    &ctx.step_id,
                    "RetryableAgentError",
                    "after flight booking",
                );
            }
            Err(err) if err.0.starts_with("approval required:") => {
                let approval_id = err.0.trim_start_matches("approval required:");
                runtime
                    .store
                    .mark_waiting_human(&run_id, &ctx.step_id, &err.0, approval_id);
            }
            Err(err) => return Err(format!("unexpected error at step 3: {}", err.0).into()),
            Ok(()) => {}
        }
    }

    println!(
        "\n  {}Agent booked flight, then crashed before committing state!{}",
        C_Y, C_RST
    );
    println!(
        "  {}Flight is booked in external system, but agent state was NOT persisted.{}",
        C_Y, C_RST
    );
    show_db(&runtime.store, &run_id);
    println!(
        "  {}Key: Tool Ledger book_flight status = {}SUCCEEDED{} (external side effect executed){}",
        C_Y, C_G, C_Y, C_RST
    );
    println!(
        "  {}      Step status = retry_scheduled (state not committed, waiting for retry){}",
        C_Y, C_RST
    );
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 4: Attempt 3 — Recovery + Hotel approval
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 4: Attempt 3 — Crash recovery → Tool Ledger idempotent replay{}",
        C_BOLD, C_G, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "\n  {}Agent re-executes. book_flight: Tool Ledger sees SUCCEEDED record...{}",
        C_DIM, C_RST
    );
    println!(
        "  {}{}→ Returns cached result, no duplicate API call, no double charge!{}",
        C_DIM, C_G, C_RST
    );

    {
        let mut ctx = claim_context(&mut runtime, &run_id, "worker-rust", "TravelPlanner");
        let result = travel_planner(&mut runtime, &mut ctx, 3);
        match result {
            Err(err) if err.0.starts_with("approval required:") => {
                let approval_id = err.0.trim_start_matches("approval required:");
                runtime
                    .store
                    .mark_waiting_human(&run_id, &ctx.step_id, &err.0, approval_id);
            }
            Err(err) => return Err(format!("unexpected error at step 4: {}", err.0).into()),
            Ok(()) => {}
        }
    }

    println!(
        "\n  {}✅ Flight idempotent replay successful! (no duplicate _book_flight call){}",
        C_G, C_RST
    );
    println!("  {}Hotel booking → triggers approval again{}", C_R, C_RST);

    for req in runtime.store.approval_requests(&run_id) {
        if req.status == "PENDING" {
            runtime
                .store
                .approve_request(&req.approval_id, "traveler", "Hotel within budget, approved")?;
            println!(
                "\n  {}✅ Approved: {} — by traveler{}",
                C_G, req.tool_name, C_RST
            );
        }
    }
    show_db(&runtime.store, &run_id);
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 5: Attempt 4 — Complete
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 5: Attempt 4 — Hotel approved → Full execution → State committed{}",
        C_BOLD, C_G, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );

    {
        let mut ctx = claim_context(&mut runtime, &run_id, "worker-rust", "TravelPlanner");
        travel_planner(&mut runtime, &mut ctx, 4)?;
        runtime.store.commit_state_patch(
            &run_id,
            &ctx.step_id,
            &ctx.lease_token,
            ctx.state_version,
            ctx.pending_patch,
        )?;
    }

    {
        let db = BOOKING_DB.lock().unwrap();
        if db.len() != 2 {
            return Err(format!("Expected 2 bookings, got {}", db.len()).into());
        }
    }

    println!(
        "\n  {}✅ Travel planning complete! State persisted to database.{}",
        C_G, C_RST
    );
    show_db(&runtime.store, &run_id);
    println!(
        "  {}Step status = completed, State has bookings + trip_status{}",
        C_G, C_RST
    );
    let db = BOOKING_DB.lock().unwrap();
    let keys: Vec<String> = db.keys().cloned().collect();
    println!(
        "  {}External bookings: {:?} ({} total, no duplicates){}",
        C_G,
        keys,
        keys.len(),
        C_RST
    );
    drop(db);
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 6: Evidence + Cost + Replay
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_M,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 6: Evidence export + Cost attribution + Replay verification{}",
        C_BOLD, C_M, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_M,
        "═".repeat(60)
    );

    let bundle = export_evidence(&runtime.store, &run_id)?;
    let replay_result = replay(&runtime.store, &run_id)?;
    let cost = agentledger::cost_attribution(&runtime.store, &run_id);

    println!(
        "\n  {}Cost attribution: {} tool calls{}",
        C_M, cost.total.tool_calls, C_RST
    );
    println!(
        "  {}Replay: {} events, safe={}{}{}",
        C_M, replay_result.event_count, C_G, replay_result.replay_safe, C_RST
    );
    println!(
        "  {}Evidence bundle: {} events total{}",
        C_M,
        bundle.events.len(),
        C_RST
    );

    // Write evidence HTML
    let html_path = root.join("evidence.html");
    let html = debug_html(&bundle);
    fs::write(&html_path, html)?;
    let html_abs = html_path.canonicalize().unwrap_or_else(|_| html_path.clone());

    // Final summary
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "{}{}  Summary: What AgentLedger (Rust) did in this demo{}",
        C_BOLD, C_G, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "
  ┌──────────────────────────────────────────────────────────┐
  │                                                          │
  │  {g}✓ Durable execution{rst}  Crash → auto retry, state preserved         │
  │                   Step: retry_scheduled → completed           │
  │                                                          │
  │  {g}✓ Tool Ledger{rst}      Idempotent replay, flight booked {bold}1x{rst} only       │
  │                   SUCCEEDED → cached result on retry        │
  │                                                          │
  │  {g}✓ Approval gates{rst}    Flight + hotel each trigger approval          │
  │                   approval_requests records in store        │
  │                                                          │
  │  {g}✓ Policy engine{rst}     Risk-based policy (high → deny+approval)     │
  │                   low-risk tools auto-allowed              │
  │                                                          │
  │  {g}✓ Budget control{rst}    Tracked {tc} tool calls                       │
  │                   BudgetController.before_tool_call()       │
  │                                                          │
  │  {g}✓ Evidence export{rst}   {ec} events recorded                         │
  │                   events stored in memory store             │
  │                                                          │
  │  {g}✓ Cost attribution{rst}  Auto-recorded per run                        │
  │                   CostAttribution by agent                │
  │                                                          │
  │  {g}✓ Replay engine{rst}     Event hash verification passed                │
  │                   Verify history without re-running       │
  │                                                          │
  └──────────────────────────────────────────────────────────┘
",
        g = C_G,
        rst = C_RST,
        bold = C_BOLD,
        tc = cost.total.tool_calls,
        ec = bundle.events.len()
    );

    println!("  {}Storage: in-memory (MemoryStore){}", C_DIM, C_RST);
    println!("  {}Evidence HTML: {:?}{}", C_DIM, html_abs, C_RST);
    println!();

    Ok(())
}

pub fn set_budget(&mut self, budget: BudgetLimits)

Examples found in repository

examples/travel_assistant.rs (lines 506-510)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args: Vec<String> = std::env::args().collect();
    let root = if args.len() > 1 {
        PathBuf::from(&args[1])
    } else {
        std::env::temp_dir().join(format!("agentledger-rust-{}", std::process::id()))
    };
    let _ = fs::create_dir_all(&root);

    // Intro
    println!(
        "\n{}{}  ╔════════════════════════════════════════════════════╗{}",
        C_BOLD, C_C, C_RST
    );
    println!(
        "{}{}  ║   AgentLedger Travel Assistant (Rust) — Interactive Demo  ║{}",
        C_BOLD, C_C, C_RST
    );
    println!(
        "{}{}  ║   See real database state at every step                 ║{}",
        C_BOLD, C_C, C_RST
    );
    println!(
        "{}{}  ╚════════════════════════════════════════════════════╝{}",
        C_BOLD, C_C, C_RST
    );

    println!(
        "\n  {}AgentLedger — Durable Execution Runtime for AI Agents{}",
        C_DIM, C_RST
    );
    println!("  ┌────────────────────────────────────────────────────┐");
    println!(
        "  │  {}✓{} Durable execution — crash recovery              │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Tool Ledger — idempotent replay                │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Approval gates — human-in-the-loop              │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Policy engine — risk-based access               │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Budget control — tool call limits               │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Evidence export — full audit trail              │",
        C_G, C_RST
    );
    println!("  └────────────────────────────────────────────────────┘");

    wait("Press Enter to start / 按 Enter 开始");

    // ════════════════════════════════════════════════════════
    // Step 1: Setup
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_B,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 1: Initialize — Register tools, configure policy{}",
        C_BOLD, C_B, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_B,
        "═".repeat(60)
    );

    let mut runtime = Runtime::new();
    runtime.set_budget(BudgetLimits {
        max_tool_calls: Some(25.0),
        max_model_tokens: None,
        max_total_usd: None,
    });

    // Register tools
    runtime.register_tool(
        ToolSpec::new("travel.search_flights", Box::new(search_flights))
            .side_effect("none")
            .risk_level("low")
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                (
                    "required",
                    Value::Array(vec!["from".into(), "to".into()]),
                ),
            ]))),
    );
    runtime.register_tool(
        ToolSpec::new("travel.search_hotels", Box::new(search_hotels))
            .side_effect("none")
            .risk_level("low")
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                ("required", Value::Array(vec!["city".into()])),
            ]))),
    );
    runtime.register_tool(
        ToolSpec::new("travel.check_weather", Box::new(check_weather))
            .side_effect("none")
            .risk_level("low")
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                ("required", Value::Array(vec!["city".into()])),
            ]))),
    );
    runtime.register_tool(
        ToolSpec::new("travel.book_flight", Box::new(book_flight))
            .side_effect("external_write")
            .risk_level("high")
            .idempotency_required(true)
            .approval_required(true)
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                (
                    "required",
                    Value::Array(vec!["flight_id".into(), "passenger".into()]),
                ),
            ]))),
    );
    runtime.register_tool(
        ToolSpec::new("travel.book_hotel", Box::new(book_hotel))
            .side_effect("external_write")
            .risk_level("high")
            .idempotency_required(true)
            .approval_required(true)
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                (
                    "required",
                    Value::Array(vec!["hotel_id".into(), "guest".into()]),
                ),
            ]))),
    );

    println!("\n  {}Registered 5 tools:{}", C_C, C_RST);
    for (name, risk, approval) in [
        ("travel.search_flights", "low", false),
        ("travel.search_hotels", "low", false),
        ("travel.check_weather", "low", false),
        ("travel.book_flight", "high", true),
        ("travel.book_hotel", "high", true),
    ] {
        let rc = if risk == "low" { C_G } else { C_R };
        let ac = if approval {
            format!("{}needs approval{}", C_R, C_RST)
        } else {
            format!("{}no approval{}", C_G, C_RST)
        };
        println!(
            "    {}•{} {}  [{}{}{}] [{}]",
            C_DIM, C_RST, name, rc, risk, C_RST, ac
        );
    }
    println!(
        "  {}Policy: Rust uses risk-based policy (low=allow, high=deny+approval){}",
        C_DIM, C_RST
    );
    println!("  {}Budget: max 25 tool calls{}", C_DIM, C_RST);

    let (run_id, _step_id) = runtime.create_run(make_state(&[
        ("trip", "Tokyo".into()),
        ("budget_usd", Value::Number(3000.0)),
    ]));
    println!(
        "\n  {}Run created: {}{}{}",
        C_B, C_BOLD, run_id, C_RST
    );
    show_db(&runtime.store, &run_id);
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 2: Attempt 1 — Approval interception
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_R,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 2: Attempt 1 — Agent runs → Approval triggered{}",
        C_BOLD, C_R, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_R,
        "═".repeat(60)
    );
    println!(
        "\n  {}Agent executing: search flights → search hotels → check weather → book flight...{}",
        C_DIM, C_RST
    );

    {
        let mut ctx = claim_context(&mut runtime, &run_id, "worker-rust", "TravelPlanner");
        let result = travel_planner(&mut runtime, &mut ctx, 1);
        match result {
            Err(err) if err.0.starts_with("approval required:") => {
                let approval_id = err.0.trim_start_matches("approval required:");
                runtime
                    .store
                    .mark_waiting_human(&run_id, &ctx.step_id, &err.0, approval_id);
            }
            Err(err) => return Err(format!("unexpected error at step 2: {}", err.0).into()),
            Ok(()) => {}
        }
    }

    println!(
        "\n  {}book_flight triggered approval! Runtime paused, waiting for human.{}",
        C_R, C_RST
    );
    show_db(&runtime.store, &run_id);
    println!(
        "  {}Note: Tool Ledger has RESERVED entry, approval status is PENDING{}",
        C_R, C_RST
    );
    wait("Press Enter to approve / 按 Enter 审批");

    for req in runtime.store.approval_requests(&run_id) {
        if req.status == "PENDING" {
            runtime
                .store
                .approve_request(&req.approval_id, "traveler", "Within budget, approved")?;
            println!(
                "\n  {}✅ Approved: {} — by traveler{}",
                C_G, req.tool_name, C_RST
            );
        }
    }
    show_db(&runtime.store, &run_id);
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 3: Attempt 2 — Execute + Crash
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_Y,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 3: Attempt 2 — Approved → Execute booking → Simulated crash{}",
        C_BOLD, C_Y, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_Y,
        "═".repeat(60)
    );
    println!(
        "\n  {}Re-running agent (approval passed, book_flight will execute)...{}",
        C_DIM, C_RST
    );

    {
        let mut ctx = claim_context(&mut runtime, &run_id, "worker-rust", "TravelPlanner");
        let result = travel_planner(&mut runtime, &mut ctx, 2);
        match result {
            Err(err) if err.0 == "retryable" => {
                runtime.store.mark_retry(
                    &run_id,
                    &ctx.step_id,
                    "RetryableAgentError",
                    "after flight booking",
                );
            }
            Err(err) if err.0.starts_with("approval required:") => {
                let approval_id = err.0.trim_start_matches("approval required:");
                runtime
                    .store
                    .mark_waiting_human(&run_id, &ctx.step_id, &err.0, approval_id);
            }
            Err(err) => return Err(format!("unexpected error at step 3: {}", err.0).into()),
            Ok(()) => {}
        }
    }

    println!(
        "\n  {}Agent booked flight, then crashed before committing state!{}",
        C_Y, C_RST
    );
    println!(
        "  {}Flight is booked in external system, but agent state was NOT persisted.{}",
        C_Y, C_RST
    );
    show_db(&runtime.store, &run_id);
    println!(
        "  {}Key: Tool Ledger book_flight status = {}SUCCEEDED{} (external side effect executed){}",
        C_Y, C_G, C_Y, C_RST
    );
    println!(
        "  {}      Step status = retry_scheduled (state not committed, waiting for retry){}",
        C_Y, C_RST
    );
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 4: Attempt 3 — Recovery + Hotel approval
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 4: Attempt 3 — Crash recovery → Tool Ledger idempotent replay{}",
        C_BOLD, C_G, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "\n  {}Agent re-executes. book_flight: Tool Ledger sees SUCCEEDED record...{}",
        C_DIM, C_RST
    );
    println!(
        "  {}{}→ Returns cached result, no duplicate API call, no double charge!{}",
        C_DIM, C_G, C_RST
    );

    {
        let mut ctx = claim_context(&mut runtime, &run_id, "worker-rust", "TravelPlanner");
        let result = travel_planner(&mut runtime, &mut ctx, 3);
        match result {
            Err(err) if err.0.starts_with("approval required:") => {
                let approval_id = err.0.trim_start_matches("approval required:");
                runtime
                    .store
                    .mark_waiting_human(&run_id, &ctx.step_id, &err.0, approval_id);
            }
            Err(err) => return Err(format!("unexpected error at step 4: {}", err.0).into()),
            Ok(()) => {}
        }
    }

    println!(
        "\n  {}✅ Flight idempotent replay successful! (no duplicate _book_flight call){}",
        C_G, C_RST
    );
    println!("  {}Hotel booking → triggers approval again{}", C_R, C_RST);

    for req in runtime.store.approval_requests(&run_id) {
        if req.status == "PENDING" {
            runtime
                .store
                .approve_request(&req.approval_id, "traveler", "Hotel within budget, approved")?;
            println!(
                "\n  {}✅ Approved: {} — by traveler{}",
                C_G, req.tool_name, C_RST
            );
        }
    }
    show_db(&runtime.store, &run_id);
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 5: Attempt 4 — Complete
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 5: Attempt 4 — Hotel approved → Full execution → State committed{}",
        C_BOLD, C_G, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );

    {
        let mut ctx = claim_context(&mut runtime, &run_id, "worker-rust", "TravelPlanner");
        travel_planner(&mut runtime, &mut ctx, 4)?;
        runtime.store.commit_state_patch(
            &run_id,
            &ctx.step_id,
            &ctx.lease_token,
            ctx.state_version,
            ctx.pending_patch,
        )?;
    }

    {
        let db = BOOKING_DB.lock().unwrap();
        if db.len() != 2 {
            return Err(format!("Expected 2 bookings, got {}", db.len()).into());
        }
    }

    println!(
        "\n  {}✅ Travel planning complete! State persisted to database.{}",
        C_G, C_RST
    );
    show_db(&runtime.store, &run_id);
    println!(
        "  {}Step status = completed, State has bookings + trip_status{}",
        C_G, C_RST
    );
    let db = BOOKING_DB.lock().unwrap();
    let keys: Vec<String> = db.keys().cloned().collect();
    println!(
        "  {}External bookings: {:?} ({} total, no duplicates){}",
        C_G,
        keys,
        keys.len(),
        C_RST
    );
    drop(db);
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 6: Evidence + Cost + Replay
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_M,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 6: Evidence export + Cost attribution + Replay verification{}",
        C_BOLD, C_M, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_M,
        "═".repeat(60)
    );

    let bundle = export_evidence(&runtime.store, &run_id)?;
    let replay_result = replay(&runtime.store, &run_id)?;
    let cost = agentledger::cost_attribution(&runtime.store, &run_id);

    println!(
        "\n  {}Cost attribution: {} tool calls{}",
        C_M, cost.total.tool_calls, C_RST
    );
    println!(
        "  {}Replay: {} events, safe={}{}{}",
        C_M, replay_result.event_count, C_G, replay_result.replay_safe, C_RST
    );
    println!(
        "  {}Evidence bundle: {} events total{}",
        C_M,
        bundle.events.len(),
        C_RST
    );

    // Write evidence HTML
    let html_path = root.join("evidence.html");
    let html = debug_html(&bundle);
    fs::write(&html_path, html)?;
    let html_abs = html_path.canonicalize().unwrap_or_else(|_| html_path.clone());

    // Final summary
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "{}{}  Summary: What AgentLedger (Rust) did in this demo{}",
        C_BOLD, C_G, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "
  ┌──────────────────────────────────────────────────────────┐
  │                                                          │
  │  {g}✓ Durable execution{rst}  Crash → auto retry, state preserved         │
  │                   Step: retry_scheduled → completed           │
  │                                                          │
  │  {g}✓ Tool Ledger{rst}      Idempotent replay, flight booked {bold}1x{rst} only       │
  │                   SUCCEEDED → cached result on retry        │
  │                                                          │
  │  {g}✓ Approval gates{rst}    Flight + hotel each trigger approval          │
  │                   approval_requests records in store        │
  │                                                          │
  │  {g}✓ Policy engine{rst}     Risk-based policy (high → deny+approval)     │
  │                   low-risk tools auto-allowed              │
  │                                                          │
  │  {g}✓ Budget control{rst}    Tracked {tc} tool calls                       │
  │                   BudgetController.before_tool_call()       │
  │                                                          │
  │  {g}✓ Evidence export{rst}   {ec} events recorded                         │
  │                   events stored in memory store             │
  │                                                          │
  │  {g}✓ Cost attribution{rst}  Auto-recorded per run                        │
  │                   CostAttribution by agent                │
  │                                                          │
  │  {g}✓ Replay engine{rst}     Event hash verification passed                │
  │                   Verify history without re-running       │
  │                                                          │
  └──────────────────────────────────────────────────────────┘
",
        g = C_G,
        rst = C_RST,
        bold = C_BOLD,
        tc = cost.total.tool_calls,
        ec = bundle.events.len()
    );

    println!("  {}Storage: in-memory (MemoryStore){}", C_DIM, C_RST);
    println!("  {}Evidence HTML: {:?}{}", C_DIM, html_abs, C_RST);
    println!();

    Ok(())
}

pub fn set_sandbox(&mut self, sandbox: Box<dyn SandboxExecutor>)

Examples found in repository

examples/mcp_governance.rs (line 35)

fn main() -> agentledger::Result<()> {
    let mut runtime = Runtime::new();
    runtime.set_sandbox(Box::new(DemoSandboxExecutor));
    let mut server = InMemoryMCPToolServer::new();
    server.add_tool(
        state(&[
            ("name", "mcp.github.create_pr".into()),
            (
                "inputSchema",
                Value::Object(state(&[
                    ("type", "object".into()),
                    (
                        "required",
                        Value::Array(vec![Value::String("title".to_string())]),
                    ),
                    (
                        "properties",
                        Value::Object(state(&[(
                            "title",
                            Value::Object(state(&[
                                ("type", "string".into()),
                                ("minLength", 1_i64.into()),
                            ])),
                        )])),
                    ),
                ])),
            ),
            (
                "annotations",
                Value::Object(state(&[
                    ("side_effect", "external_write".into()),
                    ("risk_level", "high".into()),
                    ("idempotency_required", true.into()),
                    ("approval_required", true.into()),
                    ("sandbox_required", true.into()),
                    (
                        "sandbox_policy",
                        Value::Object(state(&[
                            ("network", "deny".into()),
                            ("filesystem", "read-only".into()),
                        ])),
                    ),
                ])),
            ),
        ]),
        create_pr,
    );
    let adapter = MCPToolAdapter { client_call: create_pr };
    for descriptor in server.list_tools() {
        runtime.register_tool(adapter.tool_spec_from_descriptor(&descriptor));
    }

    let (run_id, _) = runtime.create_run(State::new());
    let first_claim = runtime.store.claim_step("worker-before-approval", &run_id, 60.0)?;
    let first_ctx = AgentContext {
        run_id: run_id.clone(),
        session_id: first_claim.session_id.clone(),
        step_id: first_claim.step_id.clone(),
        agent_role: "MCPAgent".to_string(),
        lease_token: first_claim.lease_token.clone(),
        attempt: first_claim.attempt,
        state_version: first_claim.state_version,
        pending_patch: State::new(),
    };
    let first = runtime.call_tool(
        &first_ctx,
        "mcp.github.create_pr",
        state(&[
            ("title", "Update runtime docs".into()),
            ("_logical_operation", "docs-pr".into()),
        ]),
    );
    let approval_id = first
        .unwrap_err()
        .0
        .trim_start_matches("approval required:")
        .to_string();
    runtime.store.mark_waiting_human(
        &run_id,
        &first_ctx.step_id,
        "approval required for tool mcp.github.create_pr",
        &approval_id,
    );
    runtime
        .store
        .approve_request(&approval_id, "maintainer", "demo approval")?;

    let second_claim = runtime.store.claim_step("worker-after-approval", &run_id, 60.0)?;
    let mut second_ctx = AgentContext {
        run_id: run_id.clone(),
        session_id: second_claim.session_id.clone(),
        step_id: second_claim.step_id.clone(),
        agent_role: "MCPAgent".to_string(),
        lease_token: second_claim.lease_token.clone(),
        attempt: second_claim.attempt,
        state_version: second_claim.state_version,
        pending_patch: State::new(),
    };
    let result = runtime.call_tool(
        &second_ctx,
        "mcp.github.create_pr",
        state(&[
            ("title", "Update runtime docs".into()),
            ("_logical_operation", "docs-pr".into()),
        ]),
    )?;
    second_ctx.write_state("pull_request", result);
    runtime.store.commit_state_patch(
        &run_id,
        &second_ctx.step_id,
        &second_ctx.lease_token,
        second_ctx.state_version,
        second_ctx.pending_patch,
    )?;

    let approvals = runtime.store.approval_requests(&run_id);
    println!(
        "{{\n  \"run_id\": \"{}\",\n  \"first_attempt_waited_for_approval\": true,\n  \"second_attempt_ok\": true,\n  \"approval_count\": {},\n  \"approval_status\": \"{}\",\n  \"external_action_count\": 1,\n  \"final_state_has_pull_request\": {}\n}}",
        run_id,
        approvals.len(),
        approvals.first().map(|row| row.status.as_str()).unwrap_or(""),
        runtime
            .store
            .final_state(&run_id)?
            .contains_key("pull_request")
    );
    Ok(())
}

pub fn create_run(&mut self, initial_state: State) -> (String, String)

Examples found in repository

examples/three_minute_demo.rs (line 42)

fn main() -> agentledger::Result<()> {
    let mut runtime = Runtime::new();
    runtime.register_tool(
        ToolSpec::new(
            "ticket.create",
            Box::new(|args| {
                Ok(Value::Object(state(&[
                    ("external_id", "TICKET-1".into()),
                    ("title", args["title"].clone()),
                ])))
            }),
        )
        .side_effect("external_write")
        .idempotency_required(true)
        .input_schema(Value::Object(state(&[
            ("type", "object".into()),
            (
                "required",
                Value::Array(vec![Value::String("title".to_string())]),
            ),
        ]))),
    );
    let (run_id, _) = runtime.create_run(State::new());

    let first_claim = runtime.store.claim_step("worker-before-crash", &run_id, 60.0)?;
    let first_ctx = AgentContext {
        run_id: run_id.clone(),
        session_id: first_claim.session_id.clone(),
        step_id: first_claim.step_id.clone(),
        agent_role: "SupportAgent".to_string(),
        lease_token: first_claim.lease_token.clone(),
        attempt: first_claim.attempt,
        state_version: first_claim.state_version,
        pending_patch: State::new(),
    };
    let ticket = runtime.call_tool(
        &first_ctx,
        "ticket.create",
        state(&[
            ("title", "Investigate failed payment".into()),
            ("_logical_operation", "open-payment-ticket".into()),
        ]),
    )?;
    runtime.store.mark_retry(
        &run_id,
        &first_ctx.step_id,
        "RetryableAgentError",
        "after external ticket create, before state commit",
    );

    let second_claim = runtime.store.claim_step("worker-after-restart", &run_id, 60.0)?;
    let mut second_ctx = AgentContext {
        run_id: run_id.clone(),
        session_id: second_claim.session_id.clone(),
        step_id: second_claim.step_id.clone(),
        agent_role: "SupportAgent".to_string(),
        lease_token: second_claim.lease_token.clone(),
        attempt: second_claim.attempt,
        state_version: second_claim.state_version,
        pending_patch: State::new(),
    };
    let replayed_ticket = runtime.call_tool(
        &second_ctx,
        "ticket.create",
        state(&[
            ("title", "Investigate failed payment".into()),
            ("_logical_operation", "open-payment-ticket".into()),
        ]),
    )?;
    second_ctx.write_state("ticket", replayed_ticket);
    second_ctx.write_state("recovered", true.into());
    runtime.store.commit_state_patch(
        &run_id,
        &second_ctx.step_id,
        &second_ctx.lease_token,
        second_ctx.state_version,
        second_ctx.pending_patch,
    )?;

    let summary = replay(&runtime.store, &run_id)?;
    let ledger = runtime.store.ledger(&run_id);
    let final_state = runtime.store.final_state(&run_id)?;
    println!(
        "{{\n  \"run_id\": \"{}\",\n  \"first_attempt_ok\": false,\n  \"second_attempt_ok\": true,\n  \"external_ticket_count\": 1,\n  \"actual_tool_executions\": 1,\n  \"tool_ledger_count\": {},\n  \"tool_ledger_status\": \"{}\",\n  \"first_ticket_external_id\": \"{}\",\n  \"final_state_recovered\": {},\n  \"replay\": {{\n    \"safe\": {},\n    \"event_count\": {},\n    \"tool_call_count\": {}\n  }}\n}}",
        run_id,
        ledger.len(),
        ledger.first().map(|row| row.status.as_str()).unwrap_or(""),
        get_string(&ticket, "external_id"),
        final_state.get("recovered") == Some(&Value::Bool(true)),
        summary.replay_safe,
        summary.event_count,
        summary.tool_call_count
    );
    Ok(())
}

examples/mcp_governance.rs (line 85)

fn main() -> agentledger::Result<()> {
    let mut runtime = Runtime::new();
    runtime.set_sandbox(Box::new(DemoSandboxExecutor));
    let mut server = InMemoryMCPToolServer::new();
    server.add_tool(
        state(&[
            ("name", "mcp.github.create_pr".into()),
            (
                "inputSchema",
                Value::Object(state(&[
                    ("type", "object".into()),
                    (
                        "required",
                        Value::Array(vec![Value::String("title".to_string())]),
                    ),
                    (
                        "properties",
                        Value::Object(state(&[(
                            "title",
                            Value::Object(state(&[
                                ("type", "string".into()),
                                ("minLength", 1_i64.into()),
                            ])),
                        )])),
                    ),
                ])),
            ),
            (
                "annotations",
                Value::Object(state(&[
                    ("side_effect", "external_write".into()),
                    ("risk_level", "high".into()),
                    ("idempotency_required", true.into()),
                    ("approval_required", true.into()),
                    ("sandbox_required", true.into()),
                    (
                        "sandbox_policy",
                        Value::Object(state(&[
                            ("network", "deny".into()),
                            ("filesystem", "read-only".into()),
                        ])),
                    ),
                ])),
            ),
        ]),
        create_pr,
    );
    let adapter = MCPToolAdapter { client_call: create_pr };
    for descriptor in server.list_tools() {
        runtime.register_tool(adapter.tool_spec_from_descriptor(&descriptor));
    }

    let (run_id, _) = runtime.create_run(State::new());
    let first_claim = runtime.store.claim_step("worker-before-approval", &run_id, 60.0)?;
    let first_ctx = AgentContext {
        run_id: run_id.clone(),
        session_id: first_claim.session_id.clone(),
        step_id: first_claim.step_id.clone(),
        agent_role: "MCPAgent".to_string(),
        lease_token: first_claim.lease_token.clone(),
        attempt: first_claim.attempt,
        state_version: first_claim.state_version,
        pending_patch: State::new(),
    };
    let first = runtime.call_tool(
        &first_ctx,
        "mcp.github.create_pr",
        state(&[
            ("title", "Update runtime docs".into()),
            ("_logical_operation", "docs-pr".into()),
        ]),
    );
    let approval_id = first
        .unwrap_err()
        .0
        .trim_start_matches("approval required:")
        .to_string();
    runtime.store.mark_waiting_human(
        &run_id,
        &first_ctx.step_id,
        "approval required for tool mcp.github.create_pr",
        &approval_id,
    );
    runtime
        .store
        .approve_request(&approval_id, "maintainer", "demo approval")?;

    let second_claim = runtime.store.claim_step("worker-after-approval", &run_id, 60.0)?;
    let mut second_ctx = AgentContext {
        run_id: run_id.clone(),
        session_id: second_claim.session_id.clone(),
        step_id: second_claim.step_id.clone(),
        agent_role: "MCPAgent".to_string(),
        lease_token: second_claim.lease_token.clone(),
        attempt: second_claim.attempt,
        state_version: second_claim.state_version,
        pending_patch: State::new(),
    };
    let result = runtime.call_tool(
        &second_ctx,
        "mcp.github.create_pr",
        state(&[
            ("title", "Update runtime docs".into()),
            ("_logical_operation", "docs-pr".into()),
        ]),
    )?;
    second_ctx.write_state("pull_request", result);
    runtime.store.commit_state_patch(
        &run_id,
        &second_ctx.step_id,
        &second_ctx.lease_token,
        second_ctx.state_version,
        second_ctx.pending_patch,
    )?;

    let approvals = runtime.store.approval_requests(&run_id);
    println!(
        "{{\n  \"run_id\": \"{}\",\n  \"first_attempt_waited_for_approval\": true,\n  \"second_attempt_ok\": true,\n  \"approval_count\": {},\n  \"approval_status\": \"{}\",\n  \"external_action_count\": 1,\n  \"final_state_has_pull_request\": {}\n}}",
        run_id,
        approvals.len(),
        approvals.first().map(|row| row.status.as_str()).unwrap_or(""),
        runtime
            .store
            .final_state(&run_id)?
            .contains_key("pull_request")
    );
    Ok(())
}

examples/travel_assistant.rs (lines 597-600)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let args: Vec<String> = std::env::args().collect();
    let root = if args.len() > 1 {
        PathBuf::from(&args[1])
    } else {
        std::env::temp_dir().join(format!("agentledger-rust-{}", std::process::id()))
    };
    let _ = fs::create_dir_all(&root);

    // Intro
    println!(
        "\n{}{}  ╔════════════════════════════════════════════════════╗{}",
        C_BOLD, C_C, C_RST
    );
    println!(
        "{}{}  ║   AgentLedger Travel Assistant (Rust) — Interactive Demo  ║{}",
        C_BOLD, C_C, C_RST
    );
    println!(
        "{}{}  ║   See real database state at every step                 ║{}",
        C_BOLD, C_C, C_RST
    );
    println!(
        "{}{}  ╚════════════════════════════════════════════════════╝{}",
        C_BOLD, C_C, C_RST
    );

    println!(
        "\n  {}AgentLedger — Durable Execution Runtime for AI Agents{}",
        C_DIM, C_RST
    );
    println!("  ┌────────────────────────────────────────────────────┐");
    println!(
        "  │  {}✓{} Durable execution — crash recovery              │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Tool Ledger — idempotent replay                │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Approval gates — human-in-the-loop              │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Policy engine — risk-based access               │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Budget control — tool call limits               │",
        C_G, C_RST
    );
    println!(
        "  │  {}✓{} Evidence export — full audit trail              │",
        C_G, C_RST
    );
    println!("  └────────────────────────────────────────────────────┘");

    wait("Press Enter to start / 按 Enter 开始");

    // ════════════════════════════════════════════════════════
    // Step 1: Setup
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_B,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 1: Initialize — Register tools, configure policy{}",
        C_BOLD, C_B, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_B,
        "═".repeat(60)
    );

    let mut runtime = Runtime::new();
    runtime.set_budget(BudgetLimits {
        max_tool_calls: Some(25.0),
        max_model_tokens: None,
        max_total_usd: None,
    });

    // Register tools
    runtime.register_tool(
        ToolSpec::new("travel.search_flights", Box::new(search_flights))
            .side_effect("none")
            .risk_level("low")
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                (
                    "required",
                    Value::Array(vec!["from".into(), "to".into()]),
                ),
            ]))),
    );
    runtime.register_tool(
        ToolSpec::new("travel.search_hotels", Box::new(search_hotels))
            .side_effect("none")
            .risk_level("low")
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                ("required", Value::Array(vec!["city".into()])),
            ]))),
    );
    runtime.register_tool(
        ToolSpec::new("travel.check_weather", Box::new(check_weather))
            .side_effect("none")
            .risk_level("low")
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                ("required", Value::Array(vec!["city".into()])),
            ]))),
    );
    runtime.register_tool(
        ToolSpec::new("travel.book_flight", Box::new(book_flight))
            .side_effect("external_write")
            .risk_level("high")
            .idempotency_required(true)
            .approval_required(true)
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                (
                    "required",
                    Value::Array(vec!["flight_id".into(), "passenger".into()]),
                ),
            ]))),
    );
    runtime.register_tool(
        ToolSpec::new("travel.book_hotel", Box::new(book_hotel))
            .side_effect("external_write")
            .risk_level("high")
            .idempotency_required(true)
            .approval_required(true)
            .input_schema(Value::Object(make_state(&[
                ("type", "object".into()),
                (
                    "required",
                    Value::Array(vec!["hotel_id".into(), "guest".into()]),
                ),
            ]))),
    );

    println!("\n  {}Registered 5 tools:{}", C_C, C_RST);
    for (name, risk, approval) in [
        ("travel.search_flights", "low", false),
        ("travel.search_hotels", "low", false),
        ("travel.check_weather", "low", false),
        ("travel.book_flight", "high", true),
        ("travel.book_hotel", "high", true),
    ] {
        let rc = if risk == "low" { C_G } else { C_R };
        let ac = if approval {
            format!("{}needs approval{}", C_R, C_RST)
        } else {
            format!("{}no approval{}", C_G, C_RST)
        };
        println!(
            "    {}•{} {}  [{}{}{}] [{}]",
            C_DIM, C_RST, name, rc, risk, C_RST, ac
        );
    }
    println!(
        "  {}Policy: Rust uses risk-based policy (low=allow, high=deny+approval){}",
        C_DIM, C_RST
    );
    println!("  {}Budget: max 25 tool calls{}", C_DIM, C_RST);

    let (run_id, _step_id) = runtime.create_run(make_state(&[
        ("trip", "Tokyo".into()),
        ("budget_usd", Value::Number(3000.0)),
    ]));
    println!(
        "\n  {}Run created: {}{}{}",
        C_B, C_BOLD, run_id, C_RST
    );
    show_db(&runtime.store, &run_id);
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 2: Attempt 1 — Approval interception
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_R,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 2: Attempt 1 — Agent runs → Approval triggered{}",
        C_BOLD, C_R, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_R,
        "═".repeat(60)
    );
    println!(
        "\n  {}Agent executing: search flights → search hotels → check weather → book flight...{}",
        C_DIM, C_RST
    );

    {
        let mut ctx = claim_context(&mut runtime, &run_id, "worker-rust", "TravelPlanner");
        let result = travel_planner(&mut runtime, &mut ctx, 1);
        match result {
            Err(err) if err.0.starts_with("approval required:") => {
                let approval_id = err.0.trim_start_matches("approval required:");
                runtime
                    .store
                    .mark_waiting_human(&run_id, &ctx.step_id, &err.0, approval_id);
            }
            Err(err) => return Err(format!("unexpected error at step 2: {}", err.0).into()),
            Ok(()) => {}
        }
    }

    println!(
        "\n  {}book_flight triggered approval! Runtime paused, waiting for human.{}",
        C_R, C_RST
    );
    show_db(&runtime.store, &run_id);
    println!(
        "  {}Note: Tool Ledger has RESERVED entry, approval status is PENDING{}",
        C_R, C_RST
    );
    wait("Press Enter to approve / 按 Enter 审批");

    for req in runtime.store.approval_requests(&run_id) {
        if req.status == "PENDING" {
            runtime
                .store
                .approve_request(&req.approval_id, "traveler", "Within budget, approved")?;
            println!(
                "\n  {}✅ Approved: {} — by traveler{}",
                C_G, req.tool_name, C_RST
            );
        }
    }
    show_db(&runtime.store, &run_id);
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 3: Attempt 2 — Execute + Crash
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_Y,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 3: Attempt 2 — Approved → Execute booking → Simulated crash{}",
        C_BOLD, C_Y, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_Y,
        "═".repeat(60)
    );
    println!(
        "\n  {}Re-running agent (approval passed, book_flight will execute)...{}",
        C_DIM, C_RST
    );

    {
        let mut ctx = claim_context(&mut runtime, &run_id, "worker-rust", "TravelPlanner");
        let result = travel_planner(&mut runtime, &mut ctx, 2);
        match result {
            Err(err) if err.0 == "retryable" => {
                runtime.store.mark_retry(
                    &run_id,
                    &ctx.step_id,
                    "RetryableAgentError",
                    "after flight booking",
                );
            }
            Err(err) if err.0.starts_with("approval required:") => {
                let approval_id = err.0.trim_start_matches("approval required:");
                runtime
                    .store
                    .mark_waiting_human(&run_id, &ctx.step_id, &err.0, approval_id);
            }
            Err(err) => return Err(format!("unexpected error at step 3: {}", err.0).into()),
            Ok(()) => {}
        }
    }

    println!(
        "\n  {}Agent booked flight, then crashed before committing state!{}",
        C_Y, C_RST
    );
    println!(
        "  {}Flight is booked in external system, but agent state was NOT persisted.{}",
        C_Y, C_RST
    );
    show_db(&runtime.store, &run_id);
    println!(
        "  {}Key: Tool Ledger book_flight status = {}SUCCEEDED{} (external side effect executed){}",
        C_Y, C_G, C_Y, C_RST
    );
    println!(
        "  {}      Step status = retry_scheduled (state not committed, waiting for retry){}",
        C_Y, C_RST
    );
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 4: Attempt 3 — Recovery + Hotel approval
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 4: Attempt 3 — Crash recovery → Tool Ledger idempotent replay{}",
        C_BOLD, C_G, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "\n  {}Agent re-executes. book_flight: Tool Ledger sees SUCCEEDED record...{}",
        C_DIM, C_RST
    );
    println!(
        "  {}{}→ Returns cached result, no duplicate API call, no double charge!{}",
        C_DIM, C_G, C_RST
    );

    {
        let mut ctx = claim_context(&mut runtime, &run_id, "worker-rust", "TravelPlanner");
        let result = travel_planner(&mut runtime, &mut ctx, 3);
        match result {
            Err(err) if err.0.starts_with("approval required:") => {
                let approval_id = err.0.trim_start_matches("approval required:");
                runtime
                    .store
                    .mark_waiting_human(&run_id, &ctx.step_id, &err.0, approval_id);
            }
            Err(err) => return Err(format!("unexpected error at step 4: {}", err.0).into()),
            Ok(()) => {}
        }
    }

    println!(
        "\n  {}✅ Flight idempotent replay successful! (no duplicate _book_flight call){}",
        C_G, C_RST
    );
    println!("  {}Hotel booking → triggers approval again{}", C_R, C_RST);

    for req in runtime.store.approval_requests(&run_id) {
        if req.status == "PENDING" {
            runtime
                .store
                .approve_request(&req.approval_id, "traveler", "Hotel within budget, approved")?;
            println!(
                "\n  {}✅ Approved: {} — by traveler{}",
                C_G, req.tool_name, C_RST
            );
        }
    }
    show_db(&runtime.store, &run_id);
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 5: Attempt 4 — Complete
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 5: Attempt 4 — Hotel approved → Full execution → State committed{}",
        C_BOLD, C_G, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );

    {
        let mut ctx = claim_context(&mut runtime, &run_id, "worker-rust", "TravelPlanner");
        travel_planner(&mut runtime, &mut ctx, 4)?;
        runtime.store.commit_state_patch(
            &run_id,
            &ctx.step_id,
            &ctx.lease_token,
            ctx.state_version,
            ctx.pending_patch,
        )?;
    }

    {
        let db = BOOKING_DB.lock().unwrap();
        if db.len() != 2 {
            return Err(format!("Expected 2 bookings, got {}", db.len()).into());
        }
    }

    println!(
        "\n  {}✅ Travel planning complete! State persisted to database.{}",
        C_G, C_RST
    );
    show_db(&runtime.store, &run_id);
    println!(
        "  {}Step status = completed, State has bookings + trip_status{}",
        C_G, C_RST
    );
    let db = BOOKING_DB.lock().unwrap();
    let keys: Vec<String> = db.keys().cloned().collect();
    println!(
        "  {}External bookings: {:?} ({} total, no duplicates){}",
        C_G,
        keys,
        keys.len(),
        C_RST
    );
    drop(db);
    wait("Press Enter to continue");

    // ════════════════════════════════════════════════════════
    // Step 6: Evidence + Cost + Replay
    // ════════════════════════════════════════════════════════
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_M,
        "═".repeat(60)
    );
    println!(
        "{}{}  Step 6: Evidence export + Cost attribution + Replay verification{}",
        C_BOLD, C_M, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_M,
        "═".repeat(60)
    );

    let bundle = export_evidence(&runtime.store, &run_id)?;
    let replay_result = replay(&runtime.store, &run_id)?;
    let cost = agentledger::cost_attribution(&runtime.store, &run_id);

    println!(
        "\n  {}Cost attribution: {} tool calls{}",
        C_M, cost.total.tool_calls, C_RST
    );
    println!(
        "  {}Replay: {} events, safe={}{}{}",
        C_M, replay_result.event_count, C_G, replay_result.replay_safe, C_RST
    );
    println!(
        "  {}Evidence bundle: {} events total{}",
        C_M,
        bundle.events.len(),
        C_RST
    );

    // Write evidence HTML
    let html_path = root.join("evidence.html");
    let html = debug_html(&bundle);
    fs::write(&html_path, html)?;
    let html_abs = html_path.canonicalize().unwrap_or_else(|_| html_path.clone());

    // Final summary
    println!(
        "\n{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "{}{}  Summary: What AgentLedger (Rust) did in this demo{}",
        C_BOLD, C_G, C_RST
    );
    println!(
        "{}{}{}",
        C_BOLD,
        C_G,
        "═".repeat(60)
    );
    println!(
        "
  ┌──────────────────────────────────────────────────────────┐
  │                                                          │
  │  {g}✓ Durable execution{rst}  Crash → auto retry, state preserved         │
  │                   Step: retry_scheduled → completed           │
  │                                                          │
  │  {g}✓ Tool Ledger{rst}      Idempotent replay, flight booked {bold}1x{rst} only       │
  │                   SUCCEEDED → cached result on retry        │
  │                                                          │
  │  {g}✓ Approval gates{rst}    Flight + hotel each trigger approval          │
  │                   approval_requests records in store        │
  │                                                          │
  │  {g}✓ Policy engine{rst}     Risk-based policy (high → deny+approval)     │
  │                   low-risk tools auto-allowed              │
  │                                                          │
  │  {g}✓ Budget control{rst}    Tracked {tc} tool calls                       │
  │                   BudgetController.before_tool_call()       │
  │                                                          │
  │  {g}✓ Evidence export{rst}   {ec} events recorded                         │
  │                   events stored in memory store             │
  │                                                          │
  │  {g}✓ Cost attribution{rst}  Auto-recorded per run                        │
  │                   CostAttribution by agent                │
  │                                                          │
  │  {g}✓ Replay engine{rst}     Event hash verification passed                │
  │                   Verify history without re-running       │
  │                                                          │
  └──────────────────────────────────────────────────────────┘
",
        g = C_G,
        rst = C_RST,
        bold = C_BOLD,
        tc = cost.total.tool_calls,
        ec = bundle.events.len()
    );

    println!("  {}Storage: in-memory (MemoryStore){}", C_DIM, C_RST);
    println!("  {}Evidence HTML: {:?}{}", C_DIM, html_abs, C_RST);
    println!();

    Ok(())
}

pub fn run_once( &mut self, run_id: &str, worker_id: &str, agent_role: &str, lease_seconds: f64, agent: AgentFunc, ) -> Result<bool>

pub fn call_tool( &mut self, ctx: &AgentContext, tool_name: &str, args: State, ) -> Result<Value>

Examples found in repository

examples/travel_assistant.rs (lines 232-235)

fn travel_planner(
    runtime: &mut Runtime,
    ctx: &mut AgentContext,
    attempt: u64,
) -> agentledger::Result<()> {
    // Phase 1: Research
    let flights = runtime.call_tool(ctx, "travel.search_flights", make_state(&[
        ("from", "Beijing".into()),
        ("to", "Tokyo".into()),
    ]))?;
    let hotels = runtime.call_tool(ctx, "travel.search_hotels", make_state(&[
        ("city", "Tokyo".into()),
    ]))?;
    let weather = runtime.call_tool(ctx, "travel.check_weather", make_state(&[
        ("city", "Tokyo".into()),
    ]))?;

    let fc = get_number(&flights, "count") as i64;
    let hc = get_number(&hotels, "count") as i64;
    let wt = get_number(&weather, "temp_c");
    ctx.write_state("research", Value::Object(make_state(&[
        ("flights", Value::Number(fc as f64)),
        ("hotels", Value::Number(hc as f64)),
        ("weather", Value::Number(wt)),
    ])));

    // Phase 2: Book flight (approval required)
    let flight = runtime.call_tool(ctx, "travel.book_flight", make_state(&[
        ("flight_id", "FL-002".into()),
        ("passenger", "Demo User".into()),
        ("_logical_operation", "book-demo-flight".into()),
    ]))?;

    // Phase 3: Simulated crash on attempt 2
    if attempt == 2 {
        return Err(RuntimeError("retryable".to_string()));
    }

    // Phase 4: Book hotel (approval required)
    let hotel = runtime.call_tool(ctx, "travel.book_hotel", make_state(&[
        ("hotel_id", "HT-002".into()),
        ("check_in", "2025-06-15".into()),
        ("check_out", "2025-06-20".into()),
        ("guest", "Demo User".into()),
        ("_logical_operation", "book-demo-hotel".into()),
    ]))?;

    let flight_ref = get_string(&flight, "booking_ref");
    let hotel_ref = get_string(&hotel, "booking_ref");
    ctx.write_state("bookings", Value::Object(make_state(&[
        ("flight", Value::String(flight_ref)),
        ("hotel", Value::String(hotel_ref)),
    ])));
    ctx.write_state("trip_status", Value::String("confirmed".into()));
    Ok(())
}

examples/three_minute_demo.rs (lines 55-62)

fn main() -> agentledger::Result<()> {
    let mut runtime = Runtime::new();
    runtime.register_tool(
        ToolSpec::new(
            "ticket.create",
            Box::new(|args| {
                Ok(Value::Object(state(&[
                    ("external_id", "TICKET-1".into()),
                    ("title", args["title"].clone()),
                ])))
            }),
        )
        .side_effect("external_write")
        .idempotency_required(true)
        .input_schema(Value::Object(state(&[
            ("type", "object".into()),
            (
                "required",
                Value::Array(vec![Value::String("title".to_string())]),
            ),
        ]))),
    );
    let (run_id, _) = runtime.create_run(State::new());

    let first_claim = runtime.store.claim_step("worker-before-crash", &run_id, 60.0)?;
    let first_ctx = AgentContext {
        run_id: run_id.clone(),
        session_id: first_claim.session_id.clone(),
        step_id: first_claim.step_id.clone(),
        agent_role: "SupportAgent".to_string(),
        lease_token: first_claim.lease_token.clone(),
        attempt: first_claim.attempt,
        state_version: first_claim.state_version,
        pending_patch: State::new(),
    };
    let ticket = runtime.call_tool(
        &first_ctx,
        "ticket.create",
        state(&[
            ("title", "Investigate failed payment".into()),
            ("_logical_operation", "open-payment-ticket".into()),
        ]),
    )?;
    runtime.store.mark_retry(
        &run_id,
        &first_ctx.step_id,
        "RetryableAgentError",
        "after external ticket create, before state commit",
    );

    let second_claim = runtime.store.claim_step("worker-after-restart", &run_id, 60.0)?;
    let mut second_ctx = AgentContext {
        run_id: run_id.clone(),
        session_id: second_claim.session_id.clone(),
        step_id: second_claim.step_id.clone(),
        agent_role: "SupportAgent".to_string(),
        lease_token: second_claim.lease_token.clone(),
        attempt: second_claim.attempt,
        state_version: second_claim.state_version,
        pending_patch: State::new(),
    };
    let replayed_ticket = runtime.call_tool(
        &second_ctx,
        "ticket.create",
        state(&[
            ("title", "Investigate failed payment".into()),
            ("_logical_operation", "open-payment-ticket".into()),
        ]),
    )?;
    second_ctx.write_state("ticket", replayed_ticket);
    second_ctx.write_state("recovered", true.into());
    runtime.store.commit_state_patch(
        &run_id,
        &second_ctx.step_id,
        &second_ctx.lease_token,
        second_ctx.state_version,
        second_ctx.pending_patch,
    )?;

    let summary = replay(&runtime.store, &run_id)?;
    let ledger = runtime.store.ledger(&run_id);
    let final_state = runtime.store.final_state(&run_id)?;
    println!(
        "{{\n  \"run_id\": \"{}\",\n  \"first_attempt_ok\": false,\n  \"second_attempt_ok\": true,\n  \"external_ticket_count\": 1,\n  \"actual_tool_executions\": 1,\n  \"tool_ledger_count\": {},\n  \"tool_ledger_status\": \"{}\",\n  \"first_ticket_external_id\": \"{}\",\n  \"final_state_recovered\": {},\n  \"replay\": {{\n    \"safe\": {},\n    \"event_count\": {},\n    \"tool_call_count\": {}\n  }}\n}}",
        run_id,
        ledger.len(),
        ledger.first().map(|row| row.status.as_str()).unwrap_or(""),
        get_string(&ticket, "external_id"),
        final_state.get("recovered") == Some(&Value::Bool(true)),
        summary.replay_safe,
        summary.event_count,
        summary.tool_call_count
    );
    Ok(())
}

examples/mcp_governance.rs (lines 97-104)

fn main() -> agentledger::Result<()> {
    let mut runtime = Runtime::new();
    runtime.set_sandbox(Box::new(DemoSandboxExecutor));
    let mut server = InMemoryMCPToolServer::new();
    server.add_tool(
        state(&[
            ("name", "mcp.github.create_pr".into()),
            (
                "inputSchema",
                Value::Object(state(&[
                    ("type", "object".into()),
                    (
                        "required",
                        Value::Array(vec![Value::String("title".to_string())]),
                    ),
                    (
                        "properties",
                        Value::Object(state(&[(
                            "title",
                            Value::Object(state(&[
                                ("type", "string".into()),
                                ("minLength", 1_i64.into()),
                            ])),
                        )])),
                    ),
                ])),
            ),
            (
                "annotations",
                Value::Object(state(&[
                    ("side_effect", "external_write".into()),
                    ("risk_level", "high".into()),
                    ("idempotency_required", true.into()),
                    ("approval_required", true.into()),
                    ("sandbox_required", true.into()),
                    (
                        "sandbox_policy",
                        Value::Object(state(&[
                            ("network", "deny".into()),
                            ("filesystem", "read-only".into()),
                        ])),
                    ),
                ])),
            ),
        ]),
        create_pr,
    );
    let adapter = MCPToolAdapter { client_call: create_pr };
    for descriptor in server.list_tools() {
        runtime.register_tool(adapter.tool_spec_from_descriptor(&descriptor));
    }

    let (run_id, _) = runtime.create_run(State::new());
    let first_claim = runtime.store.claim_step("worker-before-approval", &run_id, 60.0)?;
    let first_ctx = AgentContext {
        run_id: run_id.clone(),
        session_id: first_claim.session_id.clone(),
        step_id: first_claim.step_id.clone(),
        agent_role: "MCPAgent".to_string(),
        lease_token: first_claim.lease_token.clone(),
        attempt: first_claim.attempt,
        state_version: first_claim.state_version,
        pending_patch: State::new(),
    };
    let first = runtime.call_tool(
        &first_ctx,
        "mcp.github.create_pr",
        state(&[
            ("title", "Update runtime docs".into()),
            ("_logical_operation", "docs-pr".into()),
        ]),
    );
    let approval_id = first
        .unwrap_err()
        .0
        .trim_start_matches("approval required:")
        .to_string();
    runtime.store.mark_waiting_human(
        &run_id,
        &first_ctx.step_id,
        "approval required for tool mcp.github.create_pr",
        &approval_id,
    );
    runtime
        .store
        .approve_request(&approval_id, "maintainer", "demo approval")?;

    let second_claim = runtime.store.claim_step("worker-after-approval", &run_id, 60.0)?;
    let mut second_ctx = AgentContext {
        run_id: run_id.clone(),
        session_id: second_claim.session_id.clone(),
        step_id: second_claim.step_id.clone(),
        agent_role: "MCPAgent".to_string(),
        lease_token: second_claim.lease_token.clone(),
        attempt: second_claim.attempt,
        state_version: second_claim.state_version,
        pending_patch: State::new(),
    };
    let result = runtime.call_tool(
        &second_ctx,
        "mcp.github.create_pr",
        state(&[
            ("title", "Update runtime docs".into()),
            ("_logical_operation", "docs-pr".into()),
        ]),
    )?;
    second_ctx.write_state("pull_request", result);
    runtime.store.commit_state_patch(
        &run_id,
        &second_ctx.step_id,
        &second_ctx.lease_token,
        second_ctx.state_version,
        second_ctx.pending_patch,
    )?;

    let approvals = runtime.store.approval_requests(&run_id);
    println!(
        "{{\n  \"run_id\": \"{}\",\n  \"first_attempt_waited_for_approval\": true,\n  \"second_attempt_ok\": true,\n  \"approval_count\": {},\n  \"approval_status\": \"{}\",\n  \"external_action_count\": 1,\n  \"final_state_has_pull_request\": {}\n}}",
        run_id,
        approvals.len(),
        approvals.first().map(|row| row.status.as_str()).unwrap_or(""),
        runtime
            .store
            .final_state(&run_id)?
            .contains_key("pull_request")
    );
    Ok(())
}

pub fn create_artifact( &mut self, ctx: &AgentContext, name: &str, content: State, metadata: State, ) -> Result<String>

pub fn create_media_artifact( &mut self, ctx: &AgentContext, name: &str, kind: &str, options: MediaArtifactOptions, ) -> Result<String>

pub fn create_stream_checkpoint( &mut self, ctx: &AgentContext, name: &str, options: StreamCheckpointOptions, ) -> Result<String>

pub fn record_model_call( &mut self, ctx: &AgentContext, model: &str, input_tokens: f64, output_tokens: f64, total_usd: f64, ) -> Result<()>

pub fn record_model_call_evidence( &mut self, ctx: &AgentContext, provider: &str, model: &str, request: State, response: State, usage: State, total_usd: f64, metadata: State, ) -> Result<()>

pub fn record_model_failure( &mut self, ctx: &AgentContext, provider: &str, model: &str, error_type: &str, message: &str, retryable: Option<bool>, request: State, usage: State, total_usd: f64, metadata: State, ) -> Result<()>

pub fn record_tool_call_proposal( &mut self, ctx: &AgentContext, tool_name: &str, arguments: State, provider: Option<&str>, model: Option<&str>, model_call_ref: Option<&str>, confidence: Option<f64>, reason: Option<&str>, metadata: State, )

Trait Implementations

impl Default for Runtime

fn default() -> Self

Returns the “default value” for a type.