Struct ToolSpec 

pub struct ToolSpec {
    pub name: String,
    pub version: String,
    pub side_effect: String,
    pub risk_level: String,
    pub idempotency_required: bool,
    pub approval_required: bool,
    pub sandbox_required: bool,
    pub sandbox_executor: String,
    pub sandbox_policy: State,
    pub input_schema: Option<Value>,
    pub output_schema: Option<Value>,
    pub func: ToolFunc,
}

Fields

name: String

version: String

side_effect: String

risk_level: String

idempotency_required: bool

approval_required: bool

sandbox_required: bool

sandbox_executor: String

sandbox_policy: State

input_schema: Option<Value>

output_schema: Option<Value>

func: ToolFunc

Implementations

impl ToolSpec

pub fn new(name: &str, func: ToolFunc) -> Self

Examples found in repository

examples/three_minute_demo.rs (lines 23-31)

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/travel_assistant.rs (line 514)

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 side_effect(self, side_effect: &str) -> Self

Examples found in repository

examples/three_minute_demo.rs (line 32)

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/travel_assistant.rs (line 515)

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 risk_level(self, risk_level: &str) -> Self

Examples found in repository

examples/travel_assistant.rs (line 516)

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 idempotency_required(self, required: bool) -> Self

Examples found in repository

examples/three_minute_demo.rs (line 33)

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/travel_assistant.rs (line 547)

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 approval_required(self, required: bool) -> Self

Examples found in repository

examples/travel_assistant.rs (line 548)

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 sandbox_required(self, required: bool) -> Self

pub fn sandbox_executor(self, executor: &str) -> Self

pub fn sandbox_policy(self, policy: State) -> Self

pub fn input_schema(self, schema: Value) -> Self

Examples found in repository

examples/three_minute_demo.rs (lines 34-40)

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/travel_assistant.rs (lines 517-523)

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 output_schema(self, schema: Value) -> Self