Struct Client 

pub struct Client {
    pub auth: AuthClient,
    pub core: CoreClient,
    pub control: ControlClient,
    /* private fields */
}

Fields

auth: AuthClient

core: CoreClient

control: ControlClient

Implementations

impl Client

pub fn new(config: ClientConfig) -> Result<Self>

Examples found in repository

examples/support/utils.rs (line 78)

pub async fn create_client() -> Result<Client, Box<dyn Error>> {
    let endpoint =
        env::var("MUBIT_ENDPOINT").unwrap_or_else(|_| "http://127.0.0.1:3000".to_string());
    let grpc_endpoint =
        env::var("MUBIT_GRPC_ENDPOINT").unwrap_or_else(|_| "127.0.0.1:50051".to_string());
    let timeout_ms = env::var("MUBIT_TIMEOUT_MS")
        .ok()
        .and_then(|raw| raw.parse::<u64>().ok())
        .unwrap_or(30_000);

    let api_key =
        env::var("MUBIT_API_KEY").map_err(|_| boxed_error("MUBIT_API_KEY must be set"))?;

    let mut cfg = ClientConfig::new(endpoint).transport("http");
    cfg.grpc_endpoint = Some(grpc_endpoint);
    cfg.timeout_ms = timeout_ms;
    cfg.api_key = Some(api_key.clone());

    let client = Client::new(cfg)?;
    client.set_transport(TransportMode::Http);
    client.set_api_key(Some(api_key));

    let _ = client.auth.health().await?;

    Ok(client)
}

pub fn set_api_key(&self, api_key: Option<String>)

Examples found in repository

examples/support/utils.rs (line 80)

pub async fn create_client() -> Result<Client, Box<dyn Error>> {
    let endpoint =
        env::var("MUBIT_ENDPOINT").unwrap_or_else(|_| "http://127.0.0.1:3000".to_string());
    let grpc_endpoint =
        env::var("MUBIT_GRPC_ENDPOINT").unwrap_or_else(|_| "127.0.0.1:50051".to_string());
    let timeout_ms = env::var("MUBIT_TIMEOUT_MS")
        .ok()
        .and_then(|raw| raw.parse::<u64>().ok())
        .unwrap_or(30_000);

    let api_key =
        env::var("MUBIT_API_KEY").map_err(|_| boxed_error("MUBIT_API_KEY must be set"))?;

    let mut cfg = ClientConfig::new(endpoint).transport("http");
    cfg.grpc_endpoint = Some(grpc_endpoint);
    cfg.timeout_ms = timeout_ms;
    cfg.api_key = Some(api_key.clone());

    let client = Client::new(cfg)?;
    client.set_transport(TransportMode::Http);
    client.set_api_key(Some(api_key));

    let _ = client.auth.health().await?;

    Ok(client)
}

pub fn set_token(&self, token: Option<String>)

pub fn set_run_id(&self, run_id: Option<String>)

Examples found in repository

examples/control_query_direct_bypass_matrix.rs (line 78)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "control_query_direct_bypass_matrix";
    let started = Instant::now();
    let config = ScenarioConfig::from_env();
    let client = create_client().await?;
    let run_id = new_run_id("control_query_direct_bypass");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated control query direct bypass semantic lane".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let semantic = run_lane(
            &client,
            &run_id,
            "semantic direct bypass probe",
            config.expect_direct_search_enabled,
        )
        .await?;

        metrics = json!({
            "run_id": run_id,
            "expect_direct_search_enabled": config.expect_direct_search_enabled,
            "semantic": semantic,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/internal/goal_tree_and_goal_update.rs (line 16)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "internal_goal_tree_and_goal_update";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("internal_goal_tree");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);
    let mut passed = true;
    let mut detail = "validated raw goal tree lifecycle".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let parent = client.control.add_goal(json!({"run_id": run_id, "description": "Resolve claim", "priority": "high"})).await?;
        let parent_id = parent.get("id").and_then(Value::as_str).ok_or_else(|| boxed_error(format!("add_goal parent failed: {parent}")))?.to_string();
        let child = client.control.add_goal(json!({"run_id": run_id, "description": "Verify receipts", "priority": "medium", "parent_goal_id": parent_id})).await?;
        let child_id = child.get("id").and_then(Value::as_str).ok_or_else(|| boxed_error(format!("add_goal child failed: {child}")))?.to_string();
        let updated = client.control.update_goal(json!({"run_id": run_id, "goal_id": child_id, "status": "achieved"})).await?;
        let listed = client.control.list_goals(json!({"run_id": run_id})).await?;
        let tree = client.control.get_goal_tree(json!({"run_id": run_id, "root_goal_id": parent_id})).await?;
        require(updated.get("success").and_then(Value::as_bool).unwrap_or(true), format!("update_goal failed: {updated}"))?;
        require(listed.get("goals").and_then(|v| v.as_array()).map(|items| items.iter().any(|item| item.get("id").and_then(|v| v.as_str()) == Some(child_id.as_str()))).unwrap_or(false), format!("list_goals missing child: {listed}"))?;
        require(tree.get("goals").is_some() || tree.get("root").is_some() || tree.get("nodes").is_some(), format!("goal tree malformed: {tree}"))?;
        metrics = json!({"run_id": run_id, "parent_goal_id": parent_id, "child_goal_id": child_id});
        Ok::<(), Box<dyn Error>>(())
    }.await;

    if let Err(err) = scenario { passed = false; detail = err.to_string(); }
    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok { passed = false; detail = format!("{detail} | cleanup failures"); }
    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);
    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/core_direct_search_optional.rs (line 31)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "core_direct_search_optional";
    let started = Instant::now();
    let config = ScenarioConfig::from_env();
    let client = create_client().await?;
    let run_id = new_run_id("core_direct_search_optional");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated optional core direct-search".to_string();
    let mut metrics = json!({});

    let scenario = async {
        match client
            .core
            .search(json!({
                "query": "direct core semantic search probe",
                "k": 5,
            }))
            .await
        {
            Ok(payload) => {
                require(
                    payload.is_array() || payload.is_object(),
                    format!("core.search payload must be dict/list: {payload}"),
                )?;

                metrics = json!({
                    "run_id": run_id,
                    "enabled": true,
                    "result_count": extract_result_count(&payload),
                });
                detail = "validated optional core direct-search (enabled)".to_string();
            }
            Err(err) => {
                if config.expect_direct_search_enabled {
                    return Err(boxed_error(format!(
                        "core.search expected enabled but failed: {err}"
                    )));
                }
                let message = err.to_string();
                require(
                    is_permission_denied_like(&message),
                    format!(
                        "core.search should fail with permission denied when disabled: {message}"
                    ),
                )?;

                metrics = json!({
                    "run_id": run_id,
                    "enabled": false,
                    "message": message,
                });
                detail = "validated optional core direct-search (disabled)".to_string();
            }
        }

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/internal/core_direct_search.rs (line 31)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "internal_core_direct_search";
    let started = Instant::now();
    let config = ScenarioConfig::from_env();
    let client = create_client().await?;
    let run_id = new_run_id("internal_core_direct_search");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated optional core direct-search".to_string();
    let mut metrics = json!({});

    let scenario = async {
        match client
            .core
            .search(json!({
                "query": "direct core semantic search probe",
                "k": 5,
            }))
            .await
        {
            Ok(payload) => {
                require(
                    payload.is_array() || payload.is_object(),
                    format!("core.search payload must be dict/list: {payload}"),
                )?;

                metrics = json!({
                    "run_id": run_id,
                    "enabled": true,
                    "result_count": extract_result_count(&payload),
                });
                detail = "validated optional core direct-search (enabled)".to_string();
            }
            Err(err) => {
                if config.expect_direct_search_enabled {
                    return Err(boxed_error(format!(
                        "core.search expected enabled but failed: {err}"
                    )));
                }
                let message = err.to_string();
                require(
                    is_permission_denied_like(&message),
                    format!(
                        "core.search should fail with permission denied when disabled: {message}"
                    ),
                )?;

                metrics = json!({
                    "run_id": run_id,
                    "enabled": false,
                    "message": message,
                });
                detail = "validated optional core direct-search (disabled)".to_string();
            }
        }

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/internal/lessons_lifecycle.rs (line 17)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "internal_lessons_lifecycle";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("internal_lessons_lifecycle");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);
    let mut passed = true;
    let mut detail = "validated raw lessons lifecycle".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Always verify the stored deductible before approving reimbursement.");
        remember.run_id = Some(run_id.clone());
        remember.intent = Some("lesson".into());
        remember.lesson_type = Some("success".into());
        remember.lesson_scope = Some("session".into());
        client.remember(remember).await?;

        let mut lessons = serde_json::Value::Null;
        for _ in 0..24 {
            let current = client
                .control
                .lessons(json!({"run_id": run_id, "limit": 10}))
                .await?;
            let has_lesson = current
                .get("lessons")
                .and_then(|v| v.as_array())
                .map(|items| !items.is_empty())
                .unwrap_or(false);
            lessons = current;
            if has_lesson {
                break;
            }
            sleep(Duration::from_millis(500)).await;
        }
        let lesson_id = lessons.get("lessons").and_then(|v| v.as_array()).and_then(|items| items.iter().find_map(|item| item.get("id").and_then(|v| v.as_str()))).ok_or_else(|| boxed_error(format!("expected lesson in lifecycle test: {lessons}")))?.to_string();
        let deleted = client.control.delete_lesson(json!({"lesson_id": lesson_id})).await?;
        let remaining = client.control.lessons(json!({"run_id": run_id, "limit": 10})).await?;
        require(deleted.get("success").and_then(Value::as_bool).unwrap_or(true), format!("delete_lesson failed: {deleted}"))?;
        require(!remaining.get("lessons").and_then(|v| v.as_array()).map(|items| items.iter().any(|item| item.get("id").and_then(|v| v.as_str()) == Some(lesson_id.as_str()))).unwrap_or(false), format!("lesson still present after delete: {remaining}"))?;
        metrics = json!({"run_id": run_id, "lesson_id": lesson_id});
        Ok::<(), Box<dyn Error>>(())
    }.await;

    if let Err(err) = scenario { passed = false; detail = err.to_string(); }
    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok { passed = false; detail = format!("{detail} | cleanup failures"); }
    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);
    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/helper_remember_recall.rs (line 16)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_remember_recall";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_remember_recall");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper remember -> recall flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new(
            "Before retrying cache rebuilds, verify the token signer has rotated cleanly.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("helper-example".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("success".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.metadata = Some(json!({ "source": "rust-helper-example" }));
        remember.occurrence_time = Some(std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() as i64 - 86400);

        let remembered = client.remember(remember).await?;
        require(
            remembered
                .get("done")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("remember should wait for ingest completion: {remembered}"),
        )?;

        let mut recall = RecallOptions::new("What should I verify before retrying cache rebuilds?");
        recall.run_id = Some(run_id.clone());
        recall.entry_types = vec!["lesson".to_string(), "fact".to_string()];
        let answer = client.recall(recall).await?;
        let evidence = answer
            .get("evidence")
            .and_then(|value| value.as_array())
            .ok_or_else(|| boxed_error(format!("evidence missing: {answer}")))?;
        require(!evidence.is_empty(), format!("evidence missing: {answer}"))?;
        require(
            answer
                .get("final_answer")
                .and_then(|value| value.as_str())
                .is_some(),
            format!("final answer missing: {answer}"),
        )?;

        metrics = json!({
            "run_id": run_id,
            "evidence_count": evidence.len(),
            "confidence": answer.get("confidence").cloned().unwrap_or(serde_json::Value::Null),
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

Additional examples can be found in:

• examples/control_state_structured_variables.rs
• examples/internal/control_ingest_batch_job_lifecycle.rs
• examples/helper_archive_dereference.rs
• examples/public/07_archive_dereference.rs
• examples/public/04_memory_health_and_diagnose.rs
• examples/helper_context_diagnose_memory_health.rs
• examples/helper_handoff_feedback.rs
• examples/public/06_handoff_feedback.rs
• examples/public/01_remember_recall.rs
• examples/control_ingest_idempotency.rs
• examples/internal/upsert_key_idempotency.rs
• examples/helper_mas_learning_loop.rs
• examples/public/03_checkpoint_reflect_outcome.rs
• examples/public/09_user_scoping_and_isolation.rs
• examples/public/02_context_budget_and_sections.rs
• examples/public/11_temporal_entity_mental_model.rs
• examples/public/05_agent_registration_and_scoped_access.rs
• examples/control_batch_insert_semantic_direct.rs
• examples/control_ingest_job_lifecycle.rs
• examples/control_query_agent_routed.rs
• examples/internal/legacy_state_compatibility.rs
• examples/control_legacy_state_compat.rs
• examples/public/08_multi_agent_claims_or_support_flow.rs
• examples/public/10_full_learning_loop_smoke.rs
• examples/helper_all_helpers.rs

pub fn set_transport(&self, transport: TransportMode)

Examples found in repository

examples/support/utils.rs (line 79)

pub async fn create_client() -> Result<Client, Box<dyn Error>> {
    let endpoint =
        env::var("MUBIT_ENDPOINT").unwrap_or_else(|_| "http://127.0.0.1:3000".to_string());
    let grpc_endpoint =
        env::var("MUBIT_GRPC_ENDPOINT").unwrap_or_else(|_| "127.0.0.1:50051".to_string());
    let timeout_ms = env::var("MUBIT_TIMEOUT_MS")
        .ok()
        .and_then(|raw| raw.parse::<u64>().ok())
        .unwrap_or(30_000);

    let api_key =
        env::var("MUBIT_API_KEY").map_err(|_| boxed_error("MUBIT_API_KEY must be set"))?;

    let mut cfg = ClientConfig::new(endpoint).transport("http");
    cfg.grpc_endpoint = Some(grpc_endpoint);
    cfg.timeout_ms = timeout_ms;
    cfg.api_key = Some(api_key.clone());

    let client = Client::new(cfg)?;
    client.set_transport(TransportMode::Http);
    client.set_api_key(Some(api_key));

    let _ = client.auth.health().await?;

    Ok(client)
}

examples/control_query_direct_bypass_matrix.rs (line 79)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "control_query_direct_bypass_matrix";
    let started = Instant::now();
    let config = ScenarioConfig::from_env();
    let client = create_client().await?;
    let run_id = new_run_id("control_query_direct_bypass");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated control query direct bypass semantic lane".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let semantic = run_lane(
            &client,
            &run_id,
            "semantic direct bypass probe",
            config.expect_direct_search_enabled,
        )
        .await?;

        metrics = json!({
            "run_id": run_id,
            "expect_direct_search_enabled": config.expect_direct_search_enabled,
            "semantic": semantic,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/internal/goal_tree_and_goal_update.rs (line 17)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "internal_goal_tree_and_goal_update";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("internal_goal_tree");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);
    let mut passed = true;
    let mut detail = "validated raw goal tree lifecycle".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let parent = client.control.add_goal(json!({"run_id": run_id, "description": "Resolve claim", "priority": "high"})).await?;
        let parent_id = parent.get("id").and_then(Value::as_str).ok_or_else(|| boxed_error(format!("add_goal parent failed: {parent}")))?.to_string();
        let child = client.control.add_goal(json!({"run_id": run_id, "description": "Verify receipts", "priority": "medium", "parent_goal_id": parent_id})).await?;
        let child_id = child.get("id").and_then(Value::as_str).ok_or_else(|| boxed_error(format!("add_goal child failed: {child}")))?.to_string();
        let updated = client.control.update_goal(json!({"run_id": run_id, "goal_id": child_id, "status": "achieved"})).await?;
        let listed = client.control.list_goals(json!({"run_id": run_id})).await?;
        let tree = client.control.get_goal_tree(json!({"run_id": run_id, "root_goal_id": parent_id})).await?;
        require(updated.get("success").and_then(Value::as_bool).unwrap_or(true), format!("update_goal failed: {updated}"))?;
        require(listed.get("goals").and_then(|v| v.as_array()).map(|items| items.iter().any(|item| item.get("id").and_then(|v| v.as_str()) == Some(child_id.as_str()))).unwrap_or(false), format!("list_goals missing child: {listed}"))?;
        require(tree.get("goals").is_some() || tree.get("root").is_some() || tree.get("nodes").is_some(), format!("goal tree malformed: {tree}"))?;
        metrics = json!({"run_id": run_id, "parent_goal_id": parent_id, "child_goal_id": child_id});
        Ok::<(), Box<dyn Error>>(())
    }.await;

    if let Err(err) = scenario { passed = false; detail = err.to_string(); }
    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok { passed = false; detail = format!("{detail} | cleanup failures"); }
    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);
    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/core_direct_search_optional.rs (line 32)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "core_direct_search_optional";
    let started = Instant::now();
    let config = ScenarioConfig::from_env();
    let client = create_client().await?;
    let run_id = new_run_id("core_direct_search_optional");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated optional core direct-search".to_string();
    let mut metrics = json!({});

    let scenario = async {
        match client
            .core
            .search(json!({
                "query": "direct core semantic search probe",
                "k": 5,
            }))
            .await
        {
            Ok(payload) => {
                require(
                    payload.is_array() || payload.is_object(),
                    format!("core.search payload must be dict/list: {payload}"),
                )?;

                metrics = json!({
                    "run_id": run_id,
                    "enabled": true,
                    "result_count": extract_result_count(&payload),
                });
                detail = "validated optional core direct-search (enabled)".to_string();
            }
            Err(err) => {
                if config.expect_direct_search_enabled {
                    return Err(boxed_error(format!(
                        "core.search expected enabled but failed: {err}"
                    )));
                }
                let message = err.to_string();
                require(
                    is_permission_denied_like(&message),
                    format!(
                        "core.search should fail with permission denied when disabled: {message}"
                    ),
                )?;

                metrics = json!({
                    "run_id": run_id,
                    "enabled": false,
                    "message": message,
                });
                detail = "validated optional core direct-search (disabled)".to_string();
            }
        }

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/internal/core_direct_search.rs (line 32)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "internal_core_direct_search";
    let started = Instant::now();
    let config = ScenarioConfig::from_env();
    let client = create_client().await?;
    let run_id = new_run_id("internal_core_direct_search");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated optional core direct-search".to_string();
    let mut metrics = json!({});

    let scenario = async {
        match client
            .core
            .search(json!({
                "query": "direct core semantic search probe",
                "k": 5,
            }))
            .await
        {
            Ok(payload) => {
                require(
                    payload.is_array() || payload.is_object(),
                    format!("core.search payload must be dict/list: {payload}"),
                )?;

                metrics = json!({
                    "run_id": run_id,
                    "enabled": true,
                    "result_count": extract_result_count(&payload),
                });
                detail = "validated optional core direct-search (enabled)".to_string();
            }
            Err(err) => {
                if config.expect_direct_search_enabled {
                    return Err(boxed_error(format!(
                        "core.search expected enabled but failed: {err}"
                    )));
                }
                let message = err.to_string();
                require(
                    is_permission_denied_like(&message),
                    format!(
                        "core.search should fail with permission denied when disabled: {message}"
                    ),
                )?;

                metrics = json!({
                    "run_id": run_id,
                    "enabled": false,
                    "message": message,
                });
                detail = "validated optional core direct-search (disabled)".to_string();
            }
        }

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/internal/lessons_lifecycle.rs (line 18)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "internal_lessons_lifecycle";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("internal_lessons_lifecycle");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);
    let mut passed = true;
    let mut detail = "validated raw lessons lifecycle".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Always verify the stored deductible before approving reimbursement.");
        remember.run_id = Some(run_id.clone());
        remember.intent = Some("lesson".into());
        remember.lesson_type = Some("success".into());
        remember.lesson_scope = Some("session".into());
        client.remember(remember).await?;

        let mut lessons = serde_json::Value::Null;
        for _ in 0..24 {
            let current = client
                .control
                .lessons(json!({"run_id": run_id, "limit": 10}))
                .await?;
            let has_lesson = current
                .get("lessons")
                .and_then(|v| v.as_array())
                .map(|items| !items.is_empty())
                .unwrap_or(false);
            lessons = current;
            if has_lesson {
                break;
            }
            sleep(Duration::from_millis(500)).await;
        }
        let lesson_id = lessons.get("lessons").and_then(|v| v.as_array()).and_then(|items| items.iter().find_map(|item| item.get("id").and_then(|v| v.as_str()))).ok_or_else(|| boxed_error(format!("expected lesson in lifecycle test: {lessons}")))?.to_string();
        let deleted = client.control.delete_lesson(json!({"lesson_id": lesson_id})).await?;
        let remaining = client.control.lessons(json!({"run_id": run_id, "limit": 10})).await?;
        require(deleted.get("success").and_then(Value::as_bool).unwrap_or(true), format!("delete_lesson failed: {deleted}"))?;
        require(!remaining.get("lessons").and_then(|v| v.as_array()).map(|items| items.iter().any(|item| item.get("id").and_then(|v| v.as_str()) == Some(lesson_id.as_str()))).unwrap_or(false), format!("lesson still present after delete: {remaining}"))?;
        metrics = json!({"run_id": run_id, "lesson_id": lesson_id});
        Ok::<(), Box<dyn Error>>(())
    }.await;

    if let Err(err) = scenario { passed = false; detail = err.to_string(); }
    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok { passed = false; detail = format!("{detail} | cleanup failures"); }
    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);
    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

Additional examples can be found in:

• examples/helper_remember_recall.rs
• examples/control_state_structured_variables.rs
• examples/internal/control_ingest_batch_job_lifecycle.rs
• examples/helper_archive_dereference.rs
• examples/public/07_archive_dereference.rs
• examples/public/04_memory_health_and_diagnose.rs
• examples/helper_context_diagnose_memory_health.rs
• examples/helper_handoff_feedback.rs
• examples/public/06_handoff_feedback.rs
• examples/public/01_remember_recall.rs
• examples/control_ingest_idempotency.rs
• examples/internal/upsert_key_idempotency.rs
• examples/helper_mas_learning_loop.rs
• examples/public/03_checkpoint_reflect_outcome.rs
• examples/public/09_user_scoping_and_isolation.rs
• examples/public/02_context_budget_and_sections.rs
• examples/public/11_temporal_entity_mental_model.rs
• examples/public/05_agent_registration_and_scoped_access.rs
• examples/control_batch_insert_semantic_direct.rs
• examples/control_ingest_job_lifecycle.rs
• examples/control_query_agent_routed.rs
• examples/internal/legacy_state_compatibility.rs
• examples/control_legacy_state_compat.rs
• examples/public/08_multi_agent_claims_or_support_flow.rs
• examples/public/10_full_learning_loop_smoke.rs
• examples/helper_all_helpers.rs

impl Client

pub async fn remember(&self, options: RememberOptions) -> Result<Value>

Examples found in repository

examples/internal/lessons_lifecycle.rs (line 29)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "internal_lessons_lifecycle";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("internal_lessons_lifecycle");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);
    let mut passed = true;
    let mut detail = "validated raw lessons lifecycle".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Always verify the stored deductible before approving reimbursement.");
        remember.run_id = Some(run_id.clone());
        remember.intent = Some("lesson".into());
        remember.lesson_type = Some("success".into());
        remember.lesson_scope = Some("session".into());
        client.remember(remember).await?;

        let mut lessons = serde_json::Value::Null;
        for _ in 0..24 {
            let current = client
                .control
                .lessons(json!({"run_id": run_id, "limit": 10}))
                .await?;
            let has_lesson = current
                .get("lessons")
                .and_then(|v| v.as_array())
                .map(|items| !items.is_empty())
                .unwrap_or(false);
            lessons = current;
            if has_lesson {
                break;
            }
            sleep(Duration::from_millis(500)).await;
        }
        let lesson_id = lessons.get("lessons").and_then(|v| v.as_array()).and_then(|items| items.iter().find_map(|item| item.get("id").and_then(|v| v.as_str()))).ok_or_else(|| boxed_error(format!("expected lesson in lifecycle test: {lessons}")))?.to_string();
        let deleted = client.control.delete_lesson(json!({"lesson_id": lesson_id})).await?;
        let remaining = client.control.lessons(json!({"run_id": run_id, "limit": 10})).await?;
        require(deleted.get("success").and_then(Value::as_bool).unwrap_or(true), format!("delete_lesson failed: {deleted}"))?;
        require(!remaining.get("lessons").and_then(|v| v.as_array()).map(|items| items.iter().any(|item| item.get("id").and_then(|v| v.as_str()) == Some(lesson_id.as_str()))).unwrap_or(false), format!("lesson still present after delete: {remaining}"))?;
        metrics = json!({"run_id": run_id, "lesson_id": lesson_id});
        Ok::<(), Box<dyn Error>>(())
    }.await;

    if let Err(err) = scenario { passed = false; detail = err.to_string(); }
    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok { passed = false; detail = format!("{detail} | cleanup failures"); }
    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);
    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/helper_remember_recall.rs (line 35)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_remember_recall";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_remember_recall");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper remember -> recall flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new(
            "Before retrying cache rebuilds, verify the token signer has rotated cleanly.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("helper-example".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("success".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.metadata = Some(json!({ "source": "rust-helper-example" }));
        remember.occurrence_time = Some(std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() as i64 - 86400);

        let remembered = client.remember(remember).await?;
        require(
            remembered
                .get("done")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("remember should wait for ingest completion: {remembered}"),
        )?;

        let mut recall = RecallOptions::new("What should I verify before retrying cache rebuilds?");
        recall.run_id = Some(run_id.clone());
        recall.entry_types = vec!["lesson".to_string(), "fact".to_string()];
        let answer = client.recall(recall).await?;
        let evidence = answer
            .get("evidence")
            .and_then(|value| value.as_array())
            .ok_or_else(|| boxed_error(format!("evidence missing: {answer}")))?;
        require(!evidence.is_empty(), format!("evidence missing: {answer}"))?;
        require(
            answer
                .get("final_answer")
                .and_then(|value| value.as_str())
                .is_some(),
            format!("final answer missing: {answer}"),
        )?;

        metrics = json!({
            "run_id": run_id,
            "evidence_count": evidence.len(),
            "confidence": answer.get("confidence").cloned().unwrap_or(serde_json::Value::Null),
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/04_memory_health_and_diagnose.rs (line 36)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_04_memory_health_and_diagnose";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_04_memory_health_and_diagnose");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper context + diagnose + memory health flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new(
            "Deploys fail when the migration checksum is stale after a force-push.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("observer".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("failure".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.lesson_importance = Some("high".to_string());
        remember.metadata = Some(json!({ "source": "rust-helper-example" }));
        client.remember(remember).await?;

        let mut context_opts = GetContextOptions::default();
        context_opts.run_id = Some(run_id.clone());
        context_opts.query = Some("Why did the deploy fail?".to_string());
        context_opts.entry_types = vec!["lesson".to_string()];
        context_opts.mode = Some("summary".to_string());
        let context = client.get_context(context_opts).await?;

        let mut diagnose = DiagnoseOptions::new("deploy failed because migration checksum is stale");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("deploy".to_string());
        diagnose.limit = 5;
        let diagnosis = client.diagnose(diagnose).await?;

        let mut health_opts = MemoryHealthOptions::default();
        health_opts.run_id = Some(run_id.clone());
        health_opts.limit = 100;
        let health = client.memory_health(health_opts).await?;

        let section_summaries = context
            .get("section_summaries")
            .and_then(|value| value.as_array())
            .ok_or_else(|| boxed_error(format!("section summaries missing: {context}")))?;
        require(
            diagnosis
                .get("total_failure_lessons")
                .and_then(|value| value.as_u64())
                .unwrap_or(0)
                >= 1,
            format!("diagnose should surface a failure lesson: {diagnosis}"),
        )?;
        require(
            health.get("entry_counts").and_then(|value| value.as_object()).is_some(),
            format!("memory health missing entry counts: {health}"),
        )?;

        metrics = json!({
            "run_id": run_id,
            "section_count": section_summaries.len(),
            "total_failure_lessons": diagnosis.get("total_failure_lessons").cloned().unwrap_or(serde_json::Value::Null),
            "entry_count_keys": health.get("entry_counts").and_then(|value| value.as_object()).map(|map| map.len()).unwrap_or(0),
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/helper_context_diagnose_memory_health.rs (line 36)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_context_diagnose_memory_health";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_context_diagnose_memory_health");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper context + diagnose + memory health flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new(
            "Deploys fail when the migration checksum is stale after a force-push.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("observer".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("failure".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.lesson_importance = Some("high".to_string());
        remember.metadata = Some(json!({ "source": "rust-helper-example" }));
        client.remember(remember).await?;

        let mut context_opts = GetContextOptions::default();
        context_opts.run_id = Some(run_id.clone());
        context_opts.query = Some("Why did the deploy fail?".to_string());
        context_opts.entry_types = vec!["lesson".to_string()];
        context_opts.mode = Some("summary".to_string());
        let context = client.get_context(context_opts).await?;

        let mut diagnose = DiagnoseOptions::new("deploy failed because migration checksum is stale");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("deploy".to_string());
        diagnose.limit = 5;
        let diagnosis = client.diagnose(diagnose).await?;

        let mut health_opts = MemoryHealthOptions::default();
        health_opts.run_id = Some(run_id.clone());
        health_opts.limit = 100;
        let health = client.memory_health(health_opts).await?;

        let section_summaries = context
            .get("section_summaries")
            .and_then(|value| value.as_array())
            .ok_or_else(|| boxed_error(format!("section summaries missing: {context}")))?;
        require(
            diagnosis
                .get("total_failure_lessons")
                .and_then(|value| value.as_u64())
                .unwrap_or(0)
                >= 1,
            format!("diagnose should surface a failure lesson: {diagnosis}"),
        )?;
        require(
            health.get("entry_counts").and_then(|value| value.as_object()).is_some(),
            format!("memory health missing entry counts: {health}"),
        )?;

        metrics = json!({
            "run_id": run_id,
            "section_count": section_summaries.len(),
            "total_failure_lessons": diagnosis.get("total_failure_lessons").cloned().unwrap_or(serde_json::Value::Null),
            "entry_count_keys": health.get("entry_counts").and_then(|value| value.as_object()).map(|map| map.len()).unwrap_or(0),
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/01_remember_recall.rs (line 36)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_01_remember_recall";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_01_remember_recall");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper remember -> recall flow with upsert_key idempotency".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let upsert_key = format!("remember-recall-{run_id}");
        let mut remember = RememberOptions::new(
            "Before retrying cache rebuilds, verify the token signer has rotated cleanly.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("helper-example".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("success".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.upsert_key = Some(upsert_key.clone());
        remember.metadata = Some(json!({ "source": "rust-helper-example" }));

        let remembered = client.remember(remember).await?;
        require(
            remembered
                .get("done")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("remember should wait for ingest completion: {remembered}"),
        )?;

        let mut updated = RememberOptions::new(
            "Before retrying cache rebuilds, verify the signer rotation completed and invalidate stale cache tokens.",
        );
        updated.run_id = Some(run_id.clone());
        updated.agent_id = Some("helper-example".to_string());
        updated.intent = Some("lesson".to_string());
        updated.lesson_type = Some("success".to_string());
        updated.lesson_scope = Some("session".to_string());
        updated.upsert_key = Some(upsert_key.clone());
        updated.metadata = Some(json!({ "source": "rust-helper-example", "revision": 2 }));

        let updated_response = client.remember(updated).await?;
        require(
            updated_response
                .get("done")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("upsert remember should wait for ingest completion: {updated_response}"),
        )?;

        let mut recall = RecallOptions::new("What should I verify before retrying cache rebuilds?");
        recall.run_id = Some(run_id.clone());
        recall.entry_types = vec!["lesson".to_string(), "fact".to_string()];
        let answer = client.recall(recall).await?;
        let evidence = answer
            .get("evidence")
            .and_then(|value| value.as_array())
            .ok_or_else(|| boxed_error(format!("evidence missing: {answer}")))?;
        require(!evidence.is_empty(), format!("evidence missing: {answer}"))?;
        let rendered = evidence
            .iter()
            .filter_map(|item| item.get("content").and_then(|value| value.as_str()))
            .collect::<Vec<_>>()
            .join(" ");
        require(
            rendered.contains("invalidate stale cache tokens"),
            format!("upserted lesson should be recalled: {answer}"),
        )?;
        require(
            answer
                .get("final_answer")
                .and_then(|value| value.as_str())
                .is_some(),
            format!("final answer missing: {answer}"),
        )?;

        metrics = json!({
            "run_id": run_id,
            "evidence_count": evidence.len(),
            "confidence": answer.get("confidence").cloned().unwrap_or(serde_json::Value::Null),
            "upsert_key": upsert_key,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/helper_mas_learning_loop.rs (line 44)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_mas_learning_loop";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_mas_learning_loop");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper MAS checkpoint/outcome/strategies flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["rule".to_string(), "lesson".to_string(), "fact".to_string()];
        register.write_scopes = vec!["lesson".to_string(), "trace".to_string()];
        register.shared_memory_lanes = vec!["knowledge".to_string(), "history".to_string()];
        client.register_agent(register).await?;

        let mut remember = RememberOptions::new(
            "If a retry succeeds after token signer rotation, record it as a reusable recovery pattern.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("success".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.lesson_importance = Some("high".to_string());
        client.remember(remember).await?;

        let mut checkpoint = CheckpointOptions::new(
            "Planner isolated the recovery path to token signer rotation.",
        );
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction-1".to_string());
        checkpoint.metadata = Some(json!({ "stage": "analysis" }));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents = client.list_agents(list_agents).await?;

        let lessons = client.control.lessons(json!({ "run_id": run_id, "limit": 10 })).await?;
        let lesson_id = lessons
            .get("lessons")
            .and_then(|value| value.as_array())
            .and_then(|items| items.first())
            .and_then(|item| item.get("id"))
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("expected at least one lesson to record outcome against: {lessons}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Recovery succeeded after following the stored lesson.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "failure".to_string()];
        strategies.max_strategies = 5;
        let strategy_response = client.surface_strategies(strategies).await?;

        require(
            checkpoint_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("checkpoint failed: {checkpoint_response}"),
        )?;
        let agent_count = agents
            .get("agents")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);
        require(agent_count == 1, format!("agent registration missing: {agents}"))?;
        require(
            outcome_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("record_outcome failed: {outcome_response}"),
        )?;
        let strategy_count = strategy_response
            .get("strategies")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "checkpoint_id": checkpoint_response.get("checkpoint_id").cloned().unwrap_or(serde_json::Value::Null),
            "agent_count": agent_count,
            "strategy_count": strategy_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

Additional examples can be found in:

• examples/public/03_checkpoint_reflect_outcome.rs
• examples/public/09_user_scoping_and_isolation.rs
• examples/public/02_context_budget_and_sections.rs
• examples/public/11_temporal_entity_mental_model.rs
• examples/public/05_agent_registration_and_scoped_access.rs
• examples/public/08_multi_agent_claims_or_support_flow.rs
• examples/public/10_full_learning_loop_smoke.rs
• examples/helper_all_helpers.rs

pub async fn recall(&self, options: RecallOptions) -> Result<Value>

Examples found in repository

examples/helper_remember_recall.rs (line 47)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_remember_recall";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_remember_recall");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper remember -> recall flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new(
            "Before retrying cache rebuilds, verify the token signer has rotated cleanly.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("helper-example".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("success".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.metadata = Some(json!({ "source": "rust-helper-example" }));
        remember.occurrence_time = Some(std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() as i64 - 86400);

        let remembered = client.remember(remember).await?;
        require(
            remembered
                .get("done")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("remember should wait for ingest completion: {remembered}"),
        )?;

        let mut recall = RecallOptions::new("What should I verify before retrying cache rebuilds?");
        recall.run_id = Some(run_id.clone());
        recall.entry_types = vec!["lesson".to_string(), "fact".to_string()];
        let answer = client.recall(recall).await?;
        let evidence = answer
            .get("evidence")
            .and_then(|value| value.as_array())
            .ok_or_else(|| boxed_error(format!("evidence missing: {answer}")))?;
        require(!evidence.is_empty(), format!("evidence missing: {answer}"))?;
        require(
            answer
                .get("final_answer")
                .and_then(|value| value.as_str())
                .is_some(),
            format!("final answer missing: {answer}"),
        )?;

        metrics = json!({
            "run_id": run_id,
            "evidence_count": evidence.len(),
            "confidence": answer.get("confidence").cloned().unwrap_or(serde_json::Value::Null),
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/01_remember_recall.rs (line 68)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_01_remember_recall";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_01_remember_recall");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper remember -> recall flow with upsert_key idempotency".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let upsert_key = format!("remember-recall-{run_id}");
        let mut remember = RememberOptions::new(
            "Before retrying cache rebuilds, verify the token signer has rotated cleanly.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("helper-example".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("success".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.upsert_key = Some(upsert_key.clone());
        remember.metadata = Some(json!({ "source": "rust-helper-example" }));

        let remembered = client.remember(remember).await?;
        require(
            remembered
                .get("done")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("remember should wait for ingest completion: {remembered}"),
        )?;

        let mut updated = RememberOptions::new(
            "Before retrying cache rebuilds, verify the signer rotation completed and invalidate stale cache tokens.",
        );
        updated.run_id = Some(run_id.clone());
        updated.agent_id = Some("helper-example".to_string());
        updated.intent = Some("lesson".to_string());
        updated.lesson_type = Some("success".to_string());
        updated.lesson_scope = Some("session".to_string());
        updated.upsert_key = Some(upsert_key.clone());
        updated.metadata = Some(json!({ "source": "rust-helper-example", "revision": 2 }));

        let updated_response = client.remember(updated).await?;
        require(
            updated_response
                .get("done")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("upsert remember should wait for ingest completion: {updated_response}"),
        )?;

        let mut recall = RecallOptions::new("What should I verify before retrying cache rebuilds?");
        recall.run_id = Some(run_id.clone());
        recall.entry_types = vec!["lesson".to_string(), "fact".to_string()];
        let answer = client.recall(recall).await?;
        let evidence = answer
            .get("evidence")
            .and_then(|value| value.as_array())
            .ok_or_else(|| boxed_error(format!("evidence missing: {answer}")))?;
        require(!evidence.is_empty(), format!("evidence missing: {answer}"))?;
        let rendered = evidence
            .iter()
            .filter_map(|item| item.get("content").and_then(|value| value.as_str()))
            .collect::<Vec<_>>()
            .join(" ");
        require(
            rendered.contains("invalidate stale cache tokens"),
            format!("upserted lesson should be recalled: {answer}"),
        )?;
        require(
            answer
                .get("final_answer")
                .and_then(|value| value.as_str())
                .is_some(),
            format!("final answer missing: {answer}"),
        )?;

        metrics = json!({
            "run_id": run_id,
            "evidence_count": evidence.len(),
            "confidence": answer.get("confidence").cloned().unwrap_or(serde_json::Value::Null),
            "upsert_key": upsert_key,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/09_user_scoping_and_isolation.rs (line 66)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_09_user_scoping_and_isolation";
    let started = Instant::now();
    let client = create_client().await?;
    let user_a = "sdk-user-a".to_string();
    let user_b = "sdk-user-b".to_string();
    let seed_run = new_run_id("public_user_scope_seed");
    let allowed_run = new_run_id("public_user_scope_allowed");
    let blocked_run = new_run_id("public_user_scope_blocked");
    client.set_transport(TransportMode::Http);
    client.set_run_id(Some(seed_run.clone()));

    let mut passed = true;
    let mut detail = "validated user scoping and same-user cross-run reuse".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut lesson = RememberOptions::new("When a claim is missing a city, check the original intake note before escalating.");
        lesson.run_id = Some(seed_run.clone());
        lesson.user_id = Some(user_a.clone());
        lesson.agent_id = Some("planner".into());
        lesson.intent = Some("lesson".into());
        lesson.lesson_type = Some("success".into());
        lesson.lesson_scope = Some("global".into());
        lesson.lesson_importance = Some("high".into());
        lesson.metadata = Some(json!({"source": "public-example", "family": "user-scope"}));
        let lesson_write = client.remember(lesson).await?;

        let mut lessons = serde_json::Value::Null;
        for _ in 0..24 {
            let current = client
                .control
                .lessons(json!({"run_id": seed_run, "user_id": user_a, "limit": 10}))
                .await?;
            let has_lesson = current
                .get("lessons")
                .and_then(|v| v.as_array())
                .map(|items| !items.is_empty())
                .unwrap_or(false);
            lessons = current;
            if has_lesson {
                break;
            }
            sleep(Duration::from_millis(500)).await;
        }
        let lesson_id = lessons.get("lessons").and_then(|v| v.as_array()).and_then(|items| items.iter().find_map(|item| item.get("id").and_then(|v| v.as_str()))).ok_or_else(|| boxed_error(format!("expected lesson for isolation scenario: {lessons}")))?.to_string();

        let mut allowed = RecallOptions::new(
            "A claim is missing a city. Before escalating, what note should I check?",
        );
        allowed.run_id = Some(allowed_run.clone());
        allowed.user_id = Some(user_a.clone());
        allowed.entry_types = vec!["lesson".into()];
        allowed.limit = 10;
        let allowed_response = client.recall(allowed).await?;

        let mut blocked = RecallOptions::new(
            "A claim is missing a city. Before escalating, what note should I check?",
        );
        blocked.run_id = Some(blocked_run.clone());
        blocked.user_id = Some(user_b.clone());
        blocked.entry_types = vec!["lesson".into()];
        blocked.limit = 10;
        let blocked_response = client.recall(blocked).await?;

        let allowed_text = format!("{} {}",
            allowed_response.get("final_answer").and_then(|v| v.as_str()).unwrap_or(""),
            allowed_response.get("evidence").and_then(|v| v.as_array()).map(|items| items.iter().filter_map(|item| item.get("content").and_then(|v| v.as_str())).collect::<Vec<_>>().join(" ")).unwrap_or_default()
        ).to_lowercase();
        let blocked_text = format!("{} {}",
            blocked_response.get("final_answer").and_then(|v| v.as_str()).unwrap_or(""),
            blocked_response.get("evidence").and_then(|v| v.as_array()).map(|items| items.iter().filter_map(|item| item.get("content").and_then(|v| v.as_str())).collect::<Vec<_>>().join(" ")).unwrap_or_default()
        ).to_lowercase();

        require(lesson_write.get("accepted").and_then(|v| v.as_bool()).unwrap_or(false) || lesson_write.get("job_id").is_some(), format!("lesson write failed: {lesson_write}"))?;
        require(allowed_text.contains("original intake note"), format!("same-user cross-run lesson reuse failed: {allowed_response}"))?;
        require(!blocked_text.contains("original intake note"), format!("cross-user leak detected: {blocked_response}"))?;

        metrics = json!({
            "seed_run": seed_run,
            "allowed_run": allowed_run,
            "blocked_run": blocked_run,
            "lesson_id": lesson_id,
            "allowed_evidence_count": allowed_response.get("evidence").and_then(|v| v.as_array()).map(|items| items.len()).unwrap_or(0),
            "blocked_evidence_count": blocked_response.get("evidence").and_then(|v| v.as_array()).map(|items| items.len()).unwrap_or(0),
        });
        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let mut cleanup_ok = true;
    for run_id in [&seed_run, &allowed_run, &blocked_run] {
        cleanup_ok = cleanup_ok && cleanup_run(&client, run_id).await;
    }
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);
    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/public/11_temporal_entity_mental_model.rs (line 70)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_11_temporal_entity_mental_model";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_temporal_entity");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail =
        "validated temporal queries, entity aliasing, and mental model priority".to_string();
    let mut metrics = json!({});

    let scenario = async {
        // 1. Store facts with occurrence_time
        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .unwrap()
            .as_secs() as i64;

        let mut fact1 =
            RememberOptions::new("Alice Chen joined the platform team in March 2024.");
        fact1.run_id = Some(run_id.clone());
        fact1.intent = Some("fact".to_string());
        fact1.occurrence_time = Some(now - 86400 * 365); // ~1 year ago
        fact1.metadata = Some(json!({"speaker": "Alice Chen"}));
        client.remember(fact1).await?;

        let mut fact2 =
            RememberOptions::new("Alice was promoted to Senior Engineer in January 2025.");
        fact2.run_id = Some(run_id.clone());
        fact2.intent = Some("fact".to_string());
        fact2.occurrence_time = Some(now - 86400 * 60); // ~2 months ago
        fact2.metadata = Some(json!({"speaker": "Alice Chen"}));
        client.remember(fact2).await?;

        let mut fact3 =
            RememberOptions::new("Dr. Chen published a paper on distributed consensus.");
        fact3.run_id = Some(run_id.clone());
        fact3.intent = Some("fact".to_string());
        fact3.metadata = Some(json!({"speaker": "Alice Chen"}));
        client.remember(fact3).await?;

        // 2. Store a mental model (curated summary)
        let mut mental = RememberOptions::new(
            "Alice Chen (Dr. Chen) is a Senior Engineer on the platform team. \
             She specializes in distributed consensus and was promoted in January 2025.",
        );
        mental.run_id = Some(run_id.clone());
        mental.intent = Some("mental_model".to_string());
        mental.importance = Some("critical".to_string());
        mental.metadata = Some(json!({"entity": "alice chen", "consolidated": true}));
        client.remember(mental).await?;

        // 3. Recall with temporal bounds (last 90 days)
        let mut temporal_recall = RecallOptions::new("What happened recently with Alice?");
        temporal_recall.run_id = Some(run_id.clone());
        temporal_recall.min_timestamp = Some(now - 86400 * 90);
        temporal_recall.max_timestamp = Some(now);
        let temporal_result = client.recall(temporal_recall).await?;
        let temporal_evidence = temporal_result
            .get("evidence")
            .and_then(|v| v.as_array())
            .ok_or_else(|| {
                boxed_error("temporal recall missing evidence".to_string())
            })?;
        require(
            !temporal_evidence.is_empty(),
            format!("temporal recall should return evidence: {temporal_result}"),
        )?;

        // 4. Recall with budget tier
        let mut budget_recall = RecallOptions::new("Tell me about Alice Chen");
        budget_recall.run_id = Some(run_id.clone());
        budget_recall.budget = Some("high".to_string());
        let budget_result = client.recall(budget_recall).await?;
        let budget_evidence = budget_result
            .get("evidence")
            .and_then(|v| v.as_array())
            .ok_or_else(|| {
                boxed_error("budget recall missing evidence".to_string())
            })?;
        require(
            !budget_evidence.is_empty(),
            format!("budget recall should return evidence: {budget_result}"),
        )?;

        // 5. get_context should show Mental Models section first
        let mut ctx_opts = GetContextOptions::default();
        ctx_opts.run_id = Some(run_id.clone());
        ctx_opts.query = Some("Who is Alice Chen?".to_string());
        ctx_opts.entry_types = vec!["mental_model".to_string(), "fact".to_string()];
        ctx_opts.limit = Some(10);
        let ctx = client.get_context(ctx_opts).await?;
        let context_block = ctx
            .get("context_block")
            .and_then(|v| v.as_str())
            .unwrap_or("");
        // Mental Models section should appear before Facts
        let has_mental = context_block.contains("Mental Model");
        require(
            has_mental || context_block.contains("mental_model"),
            format!(
                "context should include mental model section: {}",
                &context_block[..context_block.len().min(300)]
            ),
        )?;

        metrics = json!({
            "run_id": run_id,
            "temporal_evidence_count": temporal_evidence.len(),
            "budget_evidence_count": budget_evidence.len(),
            "context_has_mental_model": has_mental,
            "context_block_length": context_block.len(),
        });
        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );
    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/08_multi_agent_claims_or_support_flow.rs (line 94)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_08_multi_agent_claims_or_support_flow";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_claims_flow");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated multi-agent claims/support flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        for (agent_id, role, read_scopes, write_scopes) in [
            ("intake", "intake", vec!["fact", "archive_block"], vec!["fact", "archive_block", "trace"]),
            ("coverage", "coverage", vec!["fact", "rule", "archive_block", "handoff", "feedback"], vec!["fact", "trace", "lesson"]),
            ("reviewer", "reviewer", vec!["fact", "archive_block", "handoff", "feedback", "rule"], vec!["feedback", "rule"]),
        ] {
            let mut agent = RegisterAgentOptions::new(agent_id);
            agent.run_id = Some(run_id.clone());
            agent.role = role.to_string();
            agent.read_scopes = read_scopes.into_iter().map(String::from).collect();
            agent.write_scopes = write_scopes.into_iter().map(String::from).collect();
            agent.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
            client.register_agent(agent).await?;
        }

        let mut fact = RememberOptions::new("Policy P-8842 covers windshield damage with a 250 GBP deductible.");
        fact.run_id = Some(run_id.clone());
        fact.agent_id = Some("intake".into());
        fact.intent = Some("fact".into());
        fact.metadata = Some(json!({"claim_id": "CLM-8842", "source": "intake-form"}));
        client.remember(fact).await?;

        let mut archive = ArchiveOptions::new("Exact adjuster note: customer confirmed the damage happened on the motorway and no third party was involved.", "adjuster_note");
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("intake".into());
        archive.origin_agent_id = Some("intake".into());
        archive.source_attempt_id = Some("attempt-1".into());
        archive.source_tool = Some("claim-review".into());
        archive.labels = vec!["claims".into(), "coverage".into()];
        archive.family = Some("windshield".into());
        let archived = client.archive(archive).await?;
        let reference_id = archived.get("reference_id").and_then(|v| v.as_str()).ok_or_else(|| boxed_error(format!("archive reference missing: {archived}")))?.to_string();

        let mut checkpoint = CheckpointOptions::new("Coverage verified deductible and adjuster note before escalation.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-review".into());
        checkpoint.agent_id = Some("coverage".into());
        checkpoint.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let mut handoff = HandoffOptions::new("claim-8842", "coverage", "reviewer", "Review whether the adjuster note is enough to approve the claim.");
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".into();
        handoff.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response.get("handoff_id").and_then(|v| v.as_str()).ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?.to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.from_agent_id = Some("reviewer".into());
        feedback.comments = "Deductible and adjuster note are sufficient for routing.".into();
        feedback.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let feedback_response = client.feedback(feedback).await?;

        let mut context_opts = GetContextOptions::default();
        context_opts.run_id = Some(run_id.clone());
        context_opts.query = Some("Prepare the final claims routing summary.".into());
        context_opts.agent_id = Some("coverage".into());
        context_opts.sections = vec!["archive".into(), "facts".into(), "handoffs".into(), "feedback".into()];
        context_opts.mode = Some("sections".into());
        let context = client.get_context(context_opts).await?;

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("coverage".into());
        let exact = client.dereference(dereference).await?;

        let mut recall = RecallOptions::new("What deductible applies and what did the adjuster confirm?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("coverage".into());
        recall.entry_types = vec!["fact".into(), "archive_block".into(), "feedback".into()];
        let recall_response = client.recall(recall).await?;

        require(checkpoint_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(handoff_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;
        require(exact.get("found").and_then(|v| v.as_bool()).unwrap_or(false), format!("dereference failed: {exact}"))?;
        let context_text = context.get("context_block").and_then(|v| v.as_str()).unwrap_or("").to_lowercase();
        let recall_text = recall_response.get("final_answer").and_then(|v| v.as_str()).unwrap_or("").to_lowercase();
        let has_archive_source = context
            .get("sources")
            .and_then(|v| v.as_array())
            .map(|sources| {
                sources.iter().any(|source| {
                    source
                        .get("entry_type")
                        .and_then(|v| v.as_str())
                        == Some("archive_block")
                })
            })
            .unwrap_or(false);
        let exact_refs_surfaced = context
            .get("exact_references_surfaced")
            .and_then(|v| v.as_u64())
            .unwrap_or(0);
        require(
            context_text.contains("adjuster note")
                || context_text.contains("motorway")
                || has_archive_source
                || exact_refs_surfaced > 0,
            format!("expected explicit or telemetry-backed exact reuse in context: {context}"),
        )?;
        require(recall_text.contains("250") && (recall_text.contains("motorway") || recall_text.contains("third party")), format!("expected recall to include fact + archive content: {recall_response}"))?;

        metrics = json!({
            "run_id": run_id,
            "handoff_id": handoff_id,
            "reference_id": reference_id,
            "feedback_id": feedback_response.get("feedback_id").cloned().unwrap_or(serde_json::Value::Null),
        });
        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);
    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/public/10_full_learning_loop_smoke.rs (line 62)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_10_full_learning_loop_smoke";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_10_full_learning_loop_smoke");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        remember.occurrence_time = Some(std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() as i64 - 86400);
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut mental_model = RememberOptions::new(
            "Claims case overview: Policy limit 5000 GBP, claimant city Leeds, \
             missing-city branch resolved via stored claim facts. Lesson: check stored facts before escalating.",
        );
        mental_model.run_id = Some(run_id.clone());
        mental_model.agent_id = Some("planner".to_string());
        mental_model.intent = Some("mental_model".to_string());
        mental_model.importance = Some("critical".to_string());
        mental_model.metadata = Some(json!({"suite": "all-helpers", "entity": "claims-case", "consolidated": true}));
        let mental_model_response = client.remember(mental_model).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "mental_model".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(mental_model_response.get("job_id").is_some() || mental_model_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("mental_model remember failed: {mental_model_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

Additional examples can be found in:

• examples/helper_all_helpers.rs

pub async fn get_context(&self, options: GetContextOptions) -> Result<Value>

Examples found in repository

examples/public/04_memory_health_and_diagnose.rs (line 43)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_04_memory_health_and_diagnose";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_04_memory_health_and_diagnose");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper context + diagnose + memory health flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new(
            "Deploys fail when the migration checksum is stale after a force-push.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("observer".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("failure".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.lesson_importance = Some("high".to_string());
        remember.metadata = Some(json!({ "source": "rust-helper-example" }));
        client.remember(remember).await?;

        let mut context_opts = GetContextOptions::default();
        context_opts.run_id = Some(run_id.clone());
        context_opts.query = Some("Why did the deploy fail?".to_string());
        context_opts.entry_types = vec!["lesson".to_string()];
        context_opts.mode = Some("summary".to_string());
        let context = client.get_context(context_opts).await?;

        let mut diagnose = DiagnoseOptions::new("deploy failed because migration checksum is stale");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("deploy".to_string());
        diagnose.limit = 5;
        let diagnosis = client.diagnose(diagnose).await?;

        let mut health_opts = MemoryHealthOptions::default();
        health_opts.run_id = Some(run_id.clone());
        health_opts.limit = 100;
        let health = client.memory_health(health_opts).await?;

        let section_summaries = context
            .get("section_summaries")
            .and_then(|value| value.as_array())
            .ok_or_else(|| boxed_error(format!("section summaries missing: {context}")))?;
        require(
            diagnosis
                .get("total_failure_lessons")
                .and_then(|value| value.as_u64())
                .unwrap_or(0)
                >= 1,
            format!("diagnose should surface a failure lesson: {diagnosis}"),
        )?;
        require(
            health.get("entry_counts").and_then(|value| value.as_object()).is_some(),
            format!("memory health missing entry counts: {health}"),
        )?;

        metrics = json!({
            "run_id": run_id,
            "section_count": section_summaries.len(),
            "total_failure_lessons": diagnosis.get("total_failure_lessons").cloned().unwrap_or(serde_json::Value::Null),
            "entry_count_keys": health.get("entry_counts").and_then(|value| value.as_object()).map(|map| map.len()).unwrap_or(0),
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/helper_context_diagnose_memory_health.rs (line 43)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_context_diagnose_memory_health";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_context_diagnose_memory_health");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper context + diagnose + memory health flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new(
            "Deploys fail when the migration checksum is stale after a force-push.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("observer".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("failure".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.lesson_importance = Some("high".to_string());
        remember.metadata = Some(json!({ "source": "rust-helper-example" }));
        client.remember(remember).await?;

        let mut context_opts = GetContextOptions::default();
        context_opts.run_id = Some(run_id.clone());
        context_opts.query = Some("Why did the deploy fail?".to_string());
        context_opts.entry_types = vec!["lesson".to_string()];
        context_opts.mode = Some("summary".to_string());
        let context = client.get_context(context_opts).await?;

        let mut diagnose = DiagnoseOptions::new("deploy failed because migration checksum is stale");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("deploy".to_string());
        diagnose.limit = 5;
        let diagnosis = client.diagnose(diagnose).await?;

        let mut health_opts = MemoryHealthOptions::default();
        health_opts.run_id = Some(run_id.clone());
        health_opts.limit = 100;
        let health = client.memory_health(health_opts).await?;

        let section_summaries = context
            .get("section_summaries")
            .and_then(|value| value.as_array())
            .ok_or_else(|| boxed_error(format!("section summaries missing: {context}")))?;
        require(
            diagnosis
                .get("total_failure_lessons")
                .and_then(|value| value.as_u64())
                .unwrap_or(0)
                >= 1,
            format!("diagnose should surface a failure lesson: {diagnosis}"),
        )?;
        require(
            health.get("entry_counts").and_then(|value| value.as_object()).is_some(),
            format!("memory health missing entry counts: {health}"),
        )?;

        metrics = json!({
            "run_id": run_id,
            "section_count": section_summaries.len(),
            "total_failure_lessons": diagnosis.get("total_failure_lessons").cloned().unwrap_or(serde_json::Value::Null),
            "entry_count_keys": health.get("entry_counts").and_then(|value| value.as_object()).map(|map| map.len()).unwrap_or(0),
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/helper_handoff_feedback.rs (line 64)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_handoff_feedback";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_handoff_feedback");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper handoff + feedback flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut planner = RegisterAgentOptions::new("planner");
        planner.run_id = Some(run_id.clone());
        planner.role = "planner".to_string();
        client.register_agent(planner).await?;

        let mut reviewer = RegisterAgentOptions::new("reviewer");
        reviewer.run_id = Some(run_id.clone());
        reviewer.role = "reviewer".to_string();
        client.register_agent(reviewer).await?;

        let mut handoff = HandoffOptions::new(
            "task-1",
            "planner",
            "reviewer",
            "Review the retry policy patch before rollout.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({ "source": "rust-helper-example" }));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Patch looks safe for rollout.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({ "source": "rust-helper-example" }));
        let feedback_response = client.feedback(feedback).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("What coordination artifacts were recorded for this review handoff?".to_string());
        context.mode = Some("sections".to_string());
        context.sections = vec!["handoffs".to_string(), "feedback".to_string()];
        let context_response = client.get_context(context).await?;

        require(
            handoff_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("handoff failed: {handoff_response}"),
        )?;
        require(
            feedback_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("feedback failed: {feedback_response}"),
        )?;
        let section_count = context_response
            .get("section_summaries")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "handoff_id": handoff_id,
            "feedback_id": feedback_response.get("feedback_id").cloned().unwrap_or(serde_json::Value::Null),
            "section_count": section_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/06_handoff_feedback.rs (line 64)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_06_handoff_feedback";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_06_handoff_feedback");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper handoff + feedback flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut planner = RegisterAgentOptions::new("planner");
        planner.run_id = Some(run_id.clone());
        planner.role = "planner".to_string();
        client.register_agent(planner).await?;

        let mut reviewer = RegisterAgentOptions::new("reviewer");
        reviewer.run_id = Some(run_id.clone());
        reviewer.role = "reviewer".to_string();
        client.register_agent(reviewer).await?;

        let mut handoff = HandoffOptions::new(
            "task-1",
            "planner",
            "reviewer",
            "Review the retry policy patch before rollout.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({ "source": "rust-helper-example" }));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Patch looks safe for rollout.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({ "source": "rust-helper-example" }));
        let feedback_response = client.feedback(feedback).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("What coordination artifacts were recorded for this review handoff?".to_string());
        context.mode = Some("sections".to_string());
        context.sections = vec!["handoffs".to_string(), "feedback".to_string()];
        let context_response = client.get_context(context).await?;

        require(
            handoff_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("handoff failed: {handoff_response}"),
        )?;
        require(
            feedback_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("feedback failed: {feedback_response}"),
        )?;
        let section_count = context_response
            .get("section_summaries")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "handoff_id": handoff_id,
            "feedback_id": feedback_response.get("feedback_id").cloned().unwrap_or(serde_json::Value::Null),
            "section_count": section_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/02_context_budget_and_sections.rs (line 63)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_02_context_budget_and_sections";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_context_budget");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated context budgeting and sectioned disclosure".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut rule = RememberOptions::new("Always lead with policy facts before escalation notes.");
        rule.run_id = Some(run_id.clone());
        rule.agent_id = Some("planner".to_string());
        rule.intent = Some("rule".to_string());
        rule.metadata = Some(json!({"source": "public-example", "section": "rules"}));
        rule.importance = Some("critical".to_string());
        client.remember(rule).await?;

        let mut fact = RememberOptions::new("Claim CLM-4242 has a policy limit of 5000 GBP and a deductible of 250 GBP.");
        fact.run_id = Some(run_id.clone());
        fact.agent_id = Some("planner".to_string());
        fact.intent = Some("fact".to_string());
        fact.metadata = Some(json!({"source": "public-example", "section": "facts"}));
        fact.importance = Some("high".to_string());
        client.remember(fact).await?;

        let mut trace = RememberOptions::new("Planner noted that the claimant is waiting on a same-day callback.");
        trace.run_id = Some(run_id.clone());
        trace.agent_id = Some("planner".to_string());
        trace.intent = Some("trace".to_string());
        trace.metadata = Some(json!({"source": "public-example", "section": "traces"}));
        trace.importance = Some("medium".to_string());
        client.remember(trace).await?;

        let mut mental = RememberOptions::new("Claim CLM-4242 overview: 5000 GBP policy limit, 250 GBP deductible, claimant awaiting same-day callback. Priority: high.");
        mental.run_id = Some(run_id.clone());
        mental.agent_id = Some("planner".to_string());
        mental.intent = Some("mental_model".to_string());
        mental.metadata = Some(json!({"source": "public-example", "section": "mental_models"}));
        mental.importance = Some("critical".to_string());
        client.remember(mental).await?;

        let mut summary_opts = GetContextOptions::default();
        summary_opts.run_id = Some(run_id.clone());
        summary_opts.query = Some("Prepare a claims summary.".to_string());
        summary_opts.mode = Some("summary".to_string());
        summary_opts.entry_types = vec!["rule".to_string(), "fact".to_string(), "trace".to_string()];
        summary_opts.max_token_budget = Some(220);
        summary_opts.limit = Some(6);
        let summary = client.get_context(summary_opts).await?;

        let mut sections_opts = GetContextOptions::default();
        sections_opts.run_id = Some(run_id.clone());
        sections_opts.query = Some("Prepare a claims summary.".to_string());
        sections_opts.mode = Some("sections".to_string());
        sections_opts.sections = vec!["mental_models".to_string(), "rules".to_string(), "facts".to_string()];
        sections_opts.entry_types = vec!["rule".to_string(), "fact".to_string(), "trace".to_string()];
        sections_opts.max_token_budget = Some(220);
        sections_opts.limit = Some(6);
        let sections = client.get_context(sections_opts).await?;

        require(summary.get("context_block").and_then(|v| v.as_str()).unwrap_or("").is_empty(), format!("summary mode should suppress context_block: {summary}"))?;
        let summary_sections = summary.get("section_summaries").and_then(|v| v.as_array()).ok_or_else(|| boxed_error(format!("summary mode missing section summaries: {summary}")))?;
        let section_sources = sections.get("sources").and_then(|v| v.as_array()).ok_or_else(|| boxed_error(format!("sections mode missing sources: {sections}")))?;
        require(!summary_sections.is_empty(), format!("summary mode missing section summaries: {summary}"))?;
        require(!section_sources.is_empty(), format!("sections mode missing sources: {sections}"))?;
        require(sections.get("budget_used").and_then(|v| v.as_u64()).unwrap_or(0) >= 1, format!("budget_used missing: {sections}"))?;
        require(sections.get("budget_remaining").and_then(|v| v.as_u64()).unwrap_or(0) <= 220, format!("budget_remaining missing: {sections}"))?;
        require(section_sources.iter().any(|s| s.get("entry_type").and_then(|v| v.as_str()) == Some("rule")), format!("expected rule source in sections mode: {sections}"))?;

        metrics = json!({
            "run_id": run_id,
            "summary_section_count": summary_sections.len(),
            "section_source_count": section_sources.len(),
            "budget_used": sections.get("budget_used").cloned().unwrap_or(serde_json::Value::Null),
            "budget_remaining": sections.get("budget_remaining").cloned().unwrap_or(serde_json::Value::Null),
        });
        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);
    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/public/11_temporal_entity_mental_model.rs (line 104)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_11_temporal_entity_mental_model";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_temporal_entity");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail =
        "validated temporal queries, entity aliasing, and mental model priority".to_string();
    let mut metrics = json!({});

    let scenario = async {
        // 1. Store facts with occurrence_time
        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .unwrap()
            .as_secs() as i64;

        let mut fact1 =
            RememberOptions::new("Alice Chen joined the platform team in March 2024.");
        fact1.run_id = Some(run_id.clone());
        fact1.intent = Some("fact".to_string());
        fact1.occurrence_time = Some(now - 86400 * 365); // ~1 year ago
        fact1.metadata = Some(json!({"speaker": "Alice Chen"}));
        client.remember(fact1).await?;

        let mut fact2 =
            RememberOptions::new("Alice was promoted to Senior Engineer in January 2025.");
        fact2.run_id = Some(run_id.clone());
        fact2.intent = Some("fact".to_string());
        fact2.occurrence_time = Some(now - 86400 * 60); // ~2 months ago
        fact2.metadata = Some(json!({"speaker": "Alice Chen"}));
        client.remember(fact2).await?;

        let mut fact3 =
            RememberOptions::new("Dr. Chen published a paper on distributed consensus.");
        fact3.run_id = Some(run_id.clone());
        fact3.intent = Some("fact".to_string());
        fact3.metadata = Some(json!({"speaker": "Alice Chen"}));
        client.remember(fact3).await?;

        // 2. Store a mental model (curated summary)
        let mut mental = RememberOptions::new(
            "Alice Chen (Dr. Chen) is a Senior Engineer on the platform team. \
             She specializes in distributed consensus and was promoted in January 2025.",
        );
        mental.run_id = Some(run_id.clone());
        mental.intent = Some("mental_model".to_string());
        mental.importance = Some("critical".to_string());
        mental.metadata = Some(json!({"entity": "alice chen", "consolidated": true}));
        client.remember(mental).await?;

        // 3. Recall with temporal bounds (last 90 days)
        let mut temporal_recall = RecallOptions::new("What happened recently with Alice?");
        temporal_recall.run_id = Some(run_id.clone());
        temporal_recall.min_timestamp = Some(now - 86400 * 90);
        temporal_recall.max_timestamp = Some(now);
        let temporal_result = client.recall(temporal_recall).await?;
        let temporal_evidence = temporal_result
            .get("evidence")
            .and_then(|v| v.as_array())
            .ok_or_else(|| {
                boxed_error("temporal recall missing evidence".to_string())
            })?;
        require(
            !temporal_evidence.is_empty(),
            format!("temporal recall should return evidence: {temporal_result}"),
        )?;

        // 4. Recall with budget tier
        let mut budget_recall = RecallOptions::new("Tell me about Alice Chen");
        budget_recall.run_id = Some(run_id.clone());
        budget_recall.budget = Some("high".to_string());
        let budget_result = client.recall(budget_recall).await?;
        let budget_evidence = budget_result
            .get("evidence")
            .and_then(|v| v.as_array())
            .ok_or_else(|| {
                boxed_error("budget recall missing evidence".to_string())
            })?;
        require(
            !budget_evidence.is_empty(),
            format!("budget recall should return evidence: {budget_result}"),
        )?;

        // 5. get_context should show Mental Models section first
        let mut ctx_opts = GetContextOptions::default();
        ctx_opts.run_id = Some(run_id.clone());
        ctx_opts.query = Some("Who is Alice Chen?".to_string());
        ctx_opts.entry_types = vec!["mental_model".to_string(), "fact".to_string()];
        ctx_opts.limit = Some(10);
        let ctx = client.get_context(ctx_opts).await?;
        let context_block = ctx
            .get("context_block")
            .and_then(|v| v.as_str())
            .unwrap_or("");
        // Mental Models section should appear before Facts
        let has_mental = context_block.contains("Mental Model");
        require(
            has_mental || context_block.contains("mental_model"),
            format!(
                "context should include mental model section: {}",
                &context_block[..context_block.len().min(300)]
            ),
        )?;

        metrics = json!({
            "run_id": run_id,
            "temporal_evidence_count": temporal_evidence.len(),
            "budget_evidence_count": budget_evidence.len(),
            "context_has_mental_model": has_mental,
            "context_block_length": context_block.len(),
        });
        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );
    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

Additional examples can be found in:

• examples/public/05_agent_registration_and_scoped_access.rs
• examples/public/08_multi_agent_claims_or_support_flow.rs
• examples/public/10_full_learning_loop_smoke.rs
• examples/helper_all_helpers.rs

pub async fn archive(&self, options: ArchiveOptions) -> Result<Value>

Examples found in repository

examples/helper_archive_dereference.rs (line 35)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_archive_dereference";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_archive_dereference");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper archive + dereference flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let content =
            "AssertionError: expected queryset ordering to preserve annotated alias.";
        let mut archive = ArchiveOptions::new(content, "failing_test_summary");
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("solver".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("pytest".to_string());
        archive.labels = vec!["django".to_string(), "query".to_string()];
        archive.family = Some("patch-repair".to_string());
        archive.metadata = Some(json!({ "source": "rust-helper-example" }));

        let archived = client.archive(archive).await?;
        let reference_id = archived
            .get("reference_id")
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archived}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("solver".to_string());
        let exact = client.dereference(dereference).await?;

        require(
            archived
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("archive failed: {archived}"),
        )?;
        require(
            exact.get("found")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("dereference failed: {exact}"),
        )?;
        require(
            exact.get("evidence")
                .and_then(|value| value.get("content"))
                .and_then(|value| value.as_str())
                == Some(content),
            format!("dereferenced content mismatch: {exact}"),
        )?;

        metrics = json!({
            "run_id": run_id,
            "reference_id": reference_id,
            "entry_type": archived.get("entry_type").cloned().unwrap_or(serde_json::Value::Null),
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/07_archive_dereference.rs (line 35)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_07_archive_dereference";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_07_archive_dereference");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper archive + dereference flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let content =
            "AssertionError: expected queryset ordering to preserve annotated alias.";
        let mut archive = ArchiveOptions::new(content, "failing_test_summary");
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("solver".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("pytest".to_string());
        archive.labels = vec!["django".to_string(), "query".to_string()];
        archive.family = Some("patch-repair".to_string());
        archive.metadata = Some(json!({ "source": "rust-helper-example" }));

        let archived = client.archive(archive).await?;
        let reference_id = archived
            .get("reference_id")
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archived}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("solver".to_string());
        let exact = client.dereference(dereference).await?;

        require(
            archived
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("archive failed: {archived}"),
        )?;
        require(
            exact.get("found")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("dereference failed: {exact}"),
        )?;
        require(
            exact.get("evidence")
                .and_then(|value| value.get("content"))
                .and_then(|value| value.as_str())
                == Some(content),
            format!("dereferenced content mismatch: {exact}"),
        )?;

        metrics = json!({
            "run_id": run_id,
            "reference_id": reference_id,
            "entry_type": archived.get("entry_type").cloned().unwrap_or(serde_json::Value::Null),
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/08_multi_agent_claims_or_support_flow.rs (line 53)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_08_multi_agent_claims_or_support_flow";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_claims_flow");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated multi-agent claims/support flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        for (agent_id, role, read_scopes, write_scopes) in [
            ("intake", "intake", vec!["fact", "archive_block"], vec!["fact", "archive_block", "trace"]),
            ("coverage", "coverage", vec!["fact", "rule", "archive_block", "handoff", "feedback"], vec!["fact", "trace", "lesson"]),
            ("reviewer", "reviewer", vec!["fact", "archive_block", "handoff", "feedback", "rule"], vec!["feedback", "rule"]),
        ] {
            let mut agent = RegisterAgentOptions::new(agent_id);
            agent.run_id = Some(run_id.clone());
            agent.role = role.to_string();
            agent.read_scopes = read_scopes.into_iter().map(String::from).collect();
            agent.write_scopes = write_scopes.into_iter().map(String::from).collect();
            agent.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
            client.register_agent(agent).await?;
        }

        let mut fact = RememberOptions::new("Policy P-8842 covers windshield damage with a 250 GBP deductible.");
        fact.run_id = Some(run_id.clone());
        fact.agent_id = Some("intake".into());
        fact.intent = Some("fact".into());
        fact.metadata = Some(json!({"claim_id": "CLM-8842", "source": "intake-form"}));
        client.remember(fact).await?;

        let mut archive = ArchiveOptions::new("Exact adjuster note: customer confirmed the damage happened on the motorway and no third party was involved.", "adjuster_note");
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("intake".into());
        archive.origin_agent_id = Some("intake".into());
        archive.source_attempt_id = Some("attempt-1".into());
        archive.source_tool = Some("claim-review".into());
        archive.labels = vec!["claims".into(), "coverage".into()];
        archive.family = Some("windshield".into());
        let archived = client.archive(archive).await?;
        let reference_id = archived.get("reference_id").and_then(|v| v.as_str()).ok_or_else(|| boxed_error(format!("archive reference missing: {archived}")))?.to_string();

        let mut checkpoint = CheckpointOptions::new("Coverage verified deductible and adjuster note before escalation.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-review".into());
        checkpoint.agent_id = Some("coverage".into());
        checkpoint.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let mut handoff = HandoffOptions::new("claim-8842", "coverage", "reviewer", "Review whether the adjuster note is enough to approve the claim.");
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".into();
        handoff.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response.get("handoff_id").and_then(|v| v.as_str()).ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?.to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.from_agent_id = Some("reviewer".into());
        feedback.comments = "Deductible and adjuster note are sufficient for routing.".into();
        feedback.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let feedback_response = client.feedback(feedback).await?;

        let mut context_opts = GetContextOptions::default();
        context_opts.run_id = Some(run_id.clone());
        context_opts.query = Some("Prepare the final claims routing summary.".into());
        context_opts.agent_id = Some("coverage".into());
        context_opts.sections = vec!["archive".into(), "facts".into(), "handoffs".into(), "feedback".into()];
        context_opts.mode = Some("sections".into());
        let context = client.get_context(context_opts).await?;

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("coverage".into());
        let exact = client.dereference(dereference).await?;

        let mut recall = RecallOptions::new("What deductible applies and what did the adjuster confirm?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("coverage".into());
        recall.entry_types = vec!["fact".into(), "archive_block".into(), "feedback".into()];
        let recall_response = client.recall(recall).await?;

        require(checkpoint_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(handoff_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;
        require(exact.get("found").and_then(|v| v.as_bool()).unwrap_or(false), format!("dereference failed: {exact}"))?;
        let context_text = context.get("context_block").and_then(|v| v.as_str()).unwrap_or("").to_lowercase();
        let recall_text = recall_response.get("final_answer").and_then(|v| v.as_str()).unwrap_or("").to_lowercase();
        let has_archive_source = context
            .get("sources")
            .and_then(|v| v.as_array())
            .map(|sources| {
                sources.iter().any(|source| {
                    source
                        .get("entry_type")
                        .and_then(|v| v.as_str())
                        == Some("archive_block")
                })
            })
            .unwrap_or(false);
        let exact_refs_surfaced = context
            .get("exact_references_surfaced")
            .and_then(|v| v.as_u64())
            .unwrap_or(0);
        require(
            context_text.contains("adjuster note")
                || context_text.contains("motorway")
                || has_archive_source
                || exact_refs_surfaced > 0,
            format!("expected explicit or telemetry-backed exact reuse in context: {context}"),
        )?;
        require(recall_text.contains("250") && (recall_text.contains("motorway") || recall_text.contains("third party")), format!("expected recall to include fact + archive content: {recall_response}"))?;

        metrics = json!({
            "run_id": run_id,
            "handoff_id": handoff_id,
            "reference_id": reference_id,
            "feedback_id": feedback_response.get("feedback_id").cloned().unwrap_or(serde_json::Value::Null),
        });
        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);
    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/public/10_full_learning_loop_smoke.rs (line 111)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_10_full_learning_loop_smoke";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_10_full_learning_loop_smoke");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        remember.occurrence_time = Some(std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() as i64 - 86400);
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut mental_model = RememberOptions::new(
            "Claims case overview: Policy limit 5000 GBP, claimant city Leeds, \
             missing-city branch resolved via stored claim facts. Lesson: check stored facts before escalating.",
        );
        mental_model.run_id = Some(run_id.clone());
        mental_model.agent_id = Some("planner".to_string());
        mental_model.intent = Some("mental_model".to_string());
        mental_model.importance = Some("critical".to_string());
        mental_model.metadata = Some(json!({"suite": "all-helpers", "entity": "claims-case", "consolidated": true}));
        let mental_model_response = client.remember(mental_model).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "mental_model".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(mental_model_response.get("job_id").is_some() || mental_model_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("mental_model remember failed: {mental_model_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/helper_all_helpers.rs (line 99)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_all_helpers";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_all_helpers");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        let scratch_run = format!("{run_id}_forget");
        let mut scratch = RememberOptions::new("Scratch run for forget helper coverage.");
        scratch.run_id = Some(scratch_run.clone());
        scratch.agent_id = Some("planner".to_string());
        scratch.intent = Some("fact".to_string());
        scratch.metadata = Some(json!({"suite": "all-helpers", "temporary": true}));
        let scratch_response = client.remember(scratch).await?;

        let forget_response = client
            .forget(ForgetOptions::for_run(scratch_run.clone()))
            .await?;

        let mut forgotten = RecallOptions::new("What temporary scratch fact exists?");
        forgotten.run_id = Some(scratch_run.clone());
        forgotten.limit = 3;
        let forgotten_response = client.recall(forgotten).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;
        require(scratch_response.get("job_id").is_some() || scratch_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("scratch remember failed: {scratch_response}"))?;
        require(forget_response.get("success").and_then(Value::as_bool).unwrap_or(true), format!("forget failed: {forget_response}"))?;
        let scratch_fact_visible = forgotten_response
            .get("evidence")
            .and_then(Value::as_array)
            .map(|items| {
                items.iter().any(|item| {
                    item.get("run_id").and_then(Value::as_str) == Some(scratch_run.as_str())
                        || item
                            .get("content")
                            .and_then(Value::as_str)
                            .map(|content| {
                                content
                                    .to_ascii_lowercase()
                                    .contains("scratch run for forget helper coverage")
                            })
                            .unwrap_or(false)
                })
            })
            .unwrap_or(false);
        require(!scratch_fact_visible, format!("scratch fact should be forgotten even if same-user lessons still surface: {forgotten_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
            "forgotten_run": scratch_run,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

pub async fn archive_block(&self, options: ArchiveOptions) -> Result<Value>

pub async fn dereference(&self, options: DereferenceOptions) -> Result<Value>

Examples found in repository

examples/helper_archive_dereference.rs (line 45)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_archive_dereference";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_archive_dereference");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper archive + dereference flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let content =
            "AssertionError: expected queryset ordering to preserve annotated alias.";
        let mut archive = ArchiveOptions::new(content, "failing_test_summary");
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("solver".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("pytest".to_string());
        archive.labels = vec!["django".to_string(), "query".to_string()];
        archive.family = Some("patch-repair".to_string());
        archive.metadata = Some(json!({ "source": "rust-helper-example" }));

        let archived = client.archive(archive).await?;
        let reference_id = archived
            .get("reference_id")
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archived}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("solver".to_string());
        let exact = client.dereference(dereference).await?;

        require(
            archived
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("archive failed: {archived}"),
        )?;
        require(
            exact.get("found")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("dereference failed: {exact}"),
        )?;
        require(
            exact.get("evidence")
                .and_then(|value| value.get("content"))
                .and_then(|value| value.as_str())
                == Some(content),
            format!("dereferenced content mismatch: {exact}"),
        )?;

        metrics = json!({
            "run_id": run_id,
            "reference_id": reference_id,
            "entry_type": archived.get("entry_type").cloned().unwrap_or(serde_json::Value::Null),
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/07_archive_dereference.rs (line 45)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_07_archive_dereference";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_07_archive_dereference");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper archive + dereference flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let content =
            "AssertionError: expected queryset ordering to preserve annotated alias.";
        let mut archive = ArchiveOptions::new(content, "failing_test_summary");
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("solver".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("pytest".to_string());
        archive.labels = vec!["django".to_string(), "query".to_string()];
        archive.family = Some("patch-repair".to_string());
        archive.metadata = Some(json!({ "source": "rust-helper-example" }));

        let archived = client.archive(archive).await?;
        let reference_id = archived
            .get("reference_id")
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archived}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("solver".to_string());
        let exact = client.dereference(dereference).await?;

        require(
            archived
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("archive failed: {archived}"),
        )?;
        require(
            exact.get("found")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("dereference failed: {exact}"),
        )?;
        require(
            exact.get("evidence")
                .and_then(|value| value.get("content"))
                .and_then(|value| value.as_str())
                == Some(content),
            format!("dereferenced content mismatch: {exact}"),
        )?;

        metrics = json!({
            "run_id": run_id,
            "reference_id": reference_id,
            "entry_type": archived.get("entry_type").cloned().unwrap_or(serde_json::Value::Null),
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/08_multi_agent_claims_or_support_flow.rs (line 88)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_08_multi_agent_claims_or_support_flow";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_claims_flow");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated multi-agent claims/support flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        for (agent_id, role, read_scopes, write_scopes) in [
            ("intake", "intake", vec!["fact", "archive_block"], vec!["fact", "archive_block", "trace"]),
            ("coverage", "coverage", vec!["fact", "rule", "archive_block", "handoff", "feedback"], vec!["fact", "trace", "lesson"]),
            ("reviewer", "reviewer", vec!["fact", "archive_block", "handoff", "feedback", "rule"], vec!["feedback", "rule"]),
        ] {
            let mut agent = RegisterAgentOptions::new(agent_id);
            agent.run_id = Some(run_id.clone());
            agent.role = role.to_string();
            agent.read_scopes = read_scopes.into_iter().map(String::from).collect();
            agent.write_scopes = write_scopes.into_iter().map(String::from).collect();
            agent.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
            client.register_agent(agent).await?;
        }

        let mut fact = RememberOptions::new("Policy P-8842 covers windshield damage with a 250 GBP deductible.");
        fact.run_id = Some(run_id.clone());
        fact.agent_id = Some("intake".into());
        fact.intent = Some("fact".into());
        fact.metadata = Some(json!({"claim_id": "CLM-8842", "source": "intake-form"}));
        client.remember(fact).await?;

        let mut archive = ArchiveOptions::new("Exact adjuster note: customer confirmed the damage happened on the motorway and no third party was involved.", "adjuster_note");
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("intake".into());
        archive.origin_agent_id = Some("intake".into());
        archive.source_attempt_id = Some("attempt-1".into());
        archive.source_tool = Some("claim-review".into());
        archive.labels = vec!["claims".into(), "coverage".into()];
        archive.family = Some("windshield".into());
        let archived = client.archive(archive).await?;
        let reference_id = archived.get("reference_id").and_then(|v| v.as_str()).ok_or_else(|| boxed_error(format!("archive reference missing: {archived}")))?.to_string();

        let mut checkpoint = CheckpointOptions::new("Coverage verified deductible and adjuster note before escalation.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-review".into());
        checkpoint.agent_id = Some("coverage".into());
        checkpoint.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let mut handoff = HandoffOptions::new("claim-8842", "coverage", "reviewer", "Review whether the adjuster note is enough to approve the claim.");
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".into();
        handoff.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response.get("handoff_id").and_then(|v| v.as_str()).ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?.to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.from_agent_id = Some("reviewer".into());
        feedback.comments = "Deductible and adjuster note are sufficient for routing.".into();
        feedback.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let feedback_response = client.feedback(feedback).await?;

        let mut context_opts = GetContextOptions::default();
        context_opts.run_id = Some(run_id.clone());
        context_opts.query = Some("Prepare the final claims routing summary.".into());
        context_opts.agent_id = Some("coverage".into());
        context_opts.sections = vec!["archive".into(), "facts".into(), "handoffs".into(), "feedback".into()];
        context_opts.mode = Some("sections".into());
        let context = client.get_context(context_opts).await?;

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("coverage".into());
        let exact = client.dereference(dereference).await?;

        let mut recall = RecallOptions::new("What deductible applies and what did the adjuster confirm?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("coverage".into());
        recall.entry_types = vec!["fact".into(), "archive_block".into(), "feedback".into()];
        let recall_response = client.recall(recall).await?;

        require(checkpoint_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(handoff_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;
        require(exact.get("found").and_then(|v| v.as_bool()).unwrap_or(false), format!("dereference failed: {exact}"))?;
        let context_text = context.get("context_block").and_then(|v| v.as_str()).unwrap_or("").to_lowercase();
        let recall_text = recall_response.get("final_answer").and_then(|v| v.as_str()).unwrap_or("").to_lowercase();
        let has_archive_source = context
            .get("sources")
            .and_then(|v| v.as_array())
            .map(|sources| {
                sources.iter().any(|source| {
                    source
                        .get("entry_type")
                        .and_then(|v| v.as_str())
                        == Some("archive_block")
                })
            })
            .unwrap_or(false);
        let exact_refs_surfaced = context
            .get("exact_references_surfaced")
            .and_then(|v| v.as_u64())
            .unwrap_or(0);
        require(
            context_text.contains("adjuster note")
                || context_text.contains("motorway")
                || has_archive_source
                || exact_refs_surfaced > 0,
            format!("expected explicit or telemetry-backed exact reuse in context: {context}"),
        )?;
        require(recall_text.contains("250") && (recall_text.contains("motorway") || recall_text.contains("third party")), format!("expected recall to include fact + archive content: {recall_response}"))?;

        metrics = json!({
            "run_id": run_id,
            "handoff_id": handoff_id,
            "reference_id": reference_id,
            "feedback_id": feedback_response.get("feedback_id").cloned().unwrap_or(serde_json::Value::Null),
        });
        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);
    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/public/10_full_learning_loop_smoke.rs (line 121)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_10_full_learning_loop_smoke";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_10_full_learning_loop_smoke");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        remember.occurrence_time = Some(std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() as i64 - 86400);
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut mental_model = RememberOptions::new(
            "Claims case overview: Policy limit 5000 GBP, claimant city Leeds, \
             missing-city branch resolved via stored claim facts. Lesson: check stored facts before escalating.",
        );
        mental_model.run_id = Some(run_id.clone());
        mental_model.agent_id = Some("planner".to_string());
        mental_model.intent = Some("mental_model".to_string());
        mental_model.importance = Some("critical".to_string());
        mental_model.metadata = Some(json!({"suite": "all-helpers", "entity": "claims-case", "consolidated": true}));
        let mental_model_response = client.remember(mental_model).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "mental_model".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(mental_model_response.get("job_id").is_some() || mental_model_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("mental_model remember failed: {mental_model_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/helper_all_helpers.rs (line 109)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_all_helpers";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_all_helpers");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        let scratch_run = format!("{run_id}_forget");
        let mut scratch = RememberOptions::new("Scratch run for forget helper coverage.");
        scratch.run_id = Some(scratch_run.clone());
        scratch.agent_id = Some("planner".to_string());
        scratch.intent = Some("fact".to_string());
        scratch.metadata = Some(json!({"suite": "all-helpers", "temporary": true}));
        let scratch_response = client.remember(scratch).await?;

        let forget_response = client
            .forget(ForgetOptions::for_run(scratch_run.clone()))
            .await?;

        let mut forgotten = RecallOptions::new("What temporary scratch fact exists?");
        forgotten.run_id = Some(scratch_run.clone());
        forgotten.limit = 3;
        let forgotten_response = client.recall(forgotten).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;
        require(scratch_response.get("job_id").is_some() || scratch_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("scratch remember failed: {scratch_response}"))?;
        require(forget_response.get("success").and_then(Value::as_bool).unwrap_or(true), format!("forget failed: {forget_response}"))?;
        let scratch_fact_visible = forgotten_response
            .get("evidence")
            .and_then(Value::as_array)
            .map(|items| {
                items.iter().any(|item| {
                    item.get("run_id").and_then(Value::as_str) == Some(scratch_run.as_str())
                        || item
                            .get("content")
                            .and_then(Value::as_str)
                            .map(|content| {
                                content
                                    .to_ascii_lowercase()
                                    .contains("scratch run for forget helper coverage")
                            })
                            .unwrap_or(false)
                })
            })
            .unwrap_or(false);
        require(!scratch_fact_visible, format!("scratch fact should be forgotten even if same-user lessons still surface: {forgotten_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
            "forgotten_run": scratch_run,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

pub async fn memory_health(&self, options: MemoryHealthOptions) -> Result<Value>

Examples found in repository

examples/public/04_memory_health_and_diagnose.rs (line 54)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_04_memory_health_and_diagnose";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_04_memory_health_and_diagnose");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper context + diagnose + memory health flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new(
            "Deploys fail when the migration checksum is stale after a force-push.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("observer".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("failure".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.lesson_importance = Some("high".to_string());
        remember.metadata = Some(json!({ "source": "rust-helper-example" }));
        client.remember(remember).await?;

        let mut context_opts = GetContextOptions::default();
        context_opts.run_id = Some(run_id.clone());
        context_opts.query = Some("Why did the deploy fail?".to_string());
        context_opts.entry_types = vec!["lesson".to_string()];
        context_opts.mode = Some("summary".to_string());
        let context = client.get_context(context_opts).await?;

        let mut diagnose = DiagnoseOptions::new("deploy failed because migration checksum is stale");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("deploy".to_string());
        diagnose.limit = 5;
        let diagnosis = client.diagnose(diagnose).await?;

        let mut health_opts = MemoryHealthOptions::default();
        health_opts.run_id = Some(run_id.clone());
        health_opts.limit = 100;
        let health = client.memory_health(health_opts).await?;

        let section_summaries = context
            .get("section_summaries")
            .and_then(|value| value.as_array())
            .ok_or_else(|| boxed_error(format!("section summaries missing: {context}")))?;
        require(
            diagnosis
                .get("total_failure_lessons")
                .and_then(|value| value.as_u64())
                .unwrap_or(0)
                >= 1,
            format!("diagnose should surface a failure lesson: {diagnosis}"),
        )?;
        require(
            health.get("entry_counts").and_then(|value| value.as_object()).is_some(),
            format!("memory health missing entry counts: {health}"),
        )?;

        metrics = json!({
            "run_id": run_id,
            "section_count": section_summaries.len(),
            "total_failure_lessons": diagnosis.get("total_failure_lessons").cloned().unwrap_or(serde_json::Value::Null),
            "entry_count_keys": health.get("entry_counts").and_then(|value| value.as_object()).map(|map| map.len()).unwrap_or(0),
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/helper_context_diagnose_memory_health.rs (line 54)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_context_diagnose_memory_health";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_context_diagnose_memory_health");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper context + diagnose + memory health flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new(
            "Deploys fail when the migration checksum is stale after a force-push.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("observer".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("failure".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.lesson_importance = Some("high".to_string());
        remember.metadata = Some(json!({ "source": "rust-helper-example" }));
        client.remember(remember).await?;

        let mut context_opts = GetContextOptions::default();
        context_opts.run_id = Some(run_id.clone());
        context_opts.query = Some("Why did the deploy fail?".to_string());
        context_opts.entry_types = vec!["lesson".to_string()];
        context_opts.mode = Some("summary".to_string());
        let context = client.get_context(context_opts).await?;

        let mut diagnose = DiagnoseOptions::new("deploy failed because migration checksum is stale");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("deploy".to_string());
        diagnose.limit = 5;
        let diagnosis = client.diagnose(diagnose).await?;

        let mut health_opts = MemoryHealthOptions::default();
        health_opts.run_id = Some(run_id.clone());
        health_opts.limit = 100;
        let health = client.memory_health(health_opts).await?;

        let section_summaries = context
            .get("section_summaries")
            .and_then(|value| value.as_array())
            .ok_or_else(|| boxed_error(format!("section summaries missing: {context}")))?;
        require(
            diagnosis
                .get("total_failure_lessons")
                .and_then(|value| value.as_u64())
                .unwrap_or(0)
                >= 1,
            format!("diagnose should surface a failure lesson: {diagnosis}"),
        )?;
        require(
            health.get("entry_counts").and_then(|value| value.as_object()).is_some(),
            format!("memory health missing entry counts: {health}"),
        )?;

        metrics = json!({
            "run_id": run_id,
            "section_count": section_summaries.len(),
            "total_failure_lessons": diagnosis.get("total_failure_lessons").cloned().unwrap_or(serde_json::Value::Null),
            "entry_count_keys": health.get("entry_counts").and_then(|value| value.as_object()).map(|map| map.len()).unwrap_or(0),
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/10_full_learning_loop_smoke.rs (line 75)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_10_full_learning_loop_smoke";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_10_full_learning_loop_smoke");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        remember.occurrence_time = Some(std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() as i64 - 86400);
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut mental_model = RememberOptions::new(
            "Claims case overview: Policy limit 5000 GBP, claimant city Leeds, \
             missing-city branch resolved via stored claim facts. Lesson: check stored facts before escalating.",
        );
        mental_model.run_id = Some(run_id.clone());
        mental_model.agent_id = Some("planner".to_string());
        mental_model.intent = Some("mental_model".to_string());
        mental_model.importance = Some("critical".to_string());
        mental_model.metadata = Some(json!({"suite": "all-helpers", "entity": "claims-case", "consolidated": true}));
        let mental_model_response = client.remember(mental_model).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "mental_model".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(mental_model_response.get("job_id").is_some() || mental_model_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("mental_model remember failed: {mental_model_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/helper_all_helpers.rs (line 63)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_all_helpers";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_all_helpers");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        let scratch_run = format!("{run_id}_forget");
        let mut scratch = RememberOptions::new("Scratch run for forget helper coverage.");
        scratch.run_id = Some(scratch_run.clone());
        scratch.agent_id = Some("planner".to_string());
        scratch.intent = Some("fact".to_string());
        scratch.metadata = Some(json!({"suite": "all-helpers", "temporary": true}));
        let scratch_response = client.remember(scratch).await?;

        let forget_response = client
            .forget(ForgetOptions::for_run(scratch_run.clone()))
            .await?;

        let mut forgotten = RecallOptions::new("What temporary scratch fact exists?");
        forgotten.run_id = Some(scratch_run.clone());
        forgotten.limit = 3;
        let forgotten_response = client.recall(forgotten).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;
        require(scratch_response.get("job_id").is_some() || scratch_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("scratch remember failed: {scratch_response}"))?;
        require(forget_response.get("success").and_then(Value::as_bool).unwrap_or(true), format!("forget failed: {forget_response}"))?;
        let scratch_fact_visible = forgotten_response
            .get("evidence")
            .and_then(Value::as_array)
            .map(|items| {
                items.iter().any(|item| {
                    item.get("run_id").and_then(Value::as_str) == Some(scratch_run.as_str())
                        || item
                            .get("content")
                            .and_then(Value::as_str)
                            .map(|content| {
                                content
                                    .to_ascii_lowercase()
                                    .contains("scratch run for forget helper coverage")
                            })
                            .unwrap_or(false)
                })
            })
            .unwrap_or(false);
        require(!scratch_fact_visible, format!("scratch fact should be forgotten even if same-user lessons still surface: {forgotten_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
            "forgotten_run": scratch_run,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

pub async fn diagnose(&self, options: DiagnoseOptions) -> Result<Value>

Examples found in repository

examples/public/04_memory_health_and_diagnose.rs (line 49)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_04_memory_health_and_diagnose";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_04_memory_health_and_diagnose");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper context + diagnose + memory health flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new(
            "Deploys fail when the migration checksum is stale after a force-push.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("observer".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("failure".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.lesson_importance = Some("high".to_string());
        remember.metadata = Some(json!({ "source": "rust-helper-example" }));
        client.remember(remember).await?;

        let mut context_opts = GetContextOptions::default();
        context_opts.run_id = Some(run_id.clone());
        context_opts.query = Some("Why did the deploy fail?".to_string());
        context_opts.entry_types = vec!["lesson".to_string()];
        context_opts.mode = Some("summary".to_string());
        let context = client.get_context(context_opts).await?;

        let mut diagnose = DiagnoseOptions::new("deploy failed because migration checksum is stale");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("deploy".to_string());
        diagnose.limit = 5;
        let diagnosis = client.diagnose(diagnose).await?;

        let mut health_opts = MemoryHealthOptions::default();
        health_opts.run_id = Some(run_id.clone());
        health_opts.limit = 100;
        let health = client.memory_health(health_opts).await?;

        let section_summaries = context
            .get("section_summaries")
            .and_then(|value| value.as_array())
            .ok_or_else(|| boxed_error(format!("section summaries missing: {context}")))?;
        require(
            diagnosis
                .get("total_failure_lessons")
                .and_then(|value| value.as_u64())
                .unwrap_or(0)
                >= 1,
            format!("diagnose should surface a failure lesson: {diagnosis}"),
        )?;
        require(
            health.get("entry_counts").and_then(|value| value.as_object()).is_some(),
            format!("memory health missing entry counts: {health}"),
        )?;

        metrics = json!({
            "run_id": run_id,
            "section_count": section_summaries.len(),
            "total_failure_lessons": diagnosis.get("total_failure_lessons").cloned().unwrap_or(serde_json::Value::Null),
            "entry_count_keys": health.get("entry_counts").and_then(|value| value.as_object()).map(|map| map.len()).unwrap_or(0),
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/helper_context_diagnose_memory_health.rs (line 49)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_context_diagnose_memory_health";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_context_diagnose_memory_health");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper context + diagnose + memory health flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new(
            "Deploys fail when the migration checksum is stale after a force-push.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("observer".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("failure".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.lesson_importance = Some("high".to_string());
        remember.metadata = Some(json!({ "source": "rust-helper-example" }));
        client.remember(remember).await?;

        let mut context_opts = GetContextOptions::default();
        context_opts.run_id = Some(run_id.clone());
        context_opts.query = Some("Why did the deploy fail?".to_string());
        context_opts.entry_types = vec!["lesson".to_string()];
        context_opts.mode = Some("summary".to_string());
        let context = client.get_context(context_opts).await?;

        let mut diagnose = DiagnoseOptions::new("deploy failed because migration checksum is stale");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("deploy".to_string());
        diagnose.limit = 5;
        let diagnosis = client.diagnose(diagnose).await?;

        let mut health_opts = MemoryHealthOptions::default();
        health_opts.run_id = Some(run_id.clone());
        health_opts.limit = 100;
        let health = client.memory_health(health_opts).await?;

        let section_summaries = context
            .get("section_summaries")
            .and_then(|value| value.as_array())
            .ok_or_else(|| boxed_error(format!("section summaries missing: {context}")))?;
        require(
            diagnosis
                .get("total_failure_lessons")
                .and_then(|value| value.as_u64())
                .unwrap_or(0)
                >= 1,
            format!("diagnose should surface a failure lesson: {diagnosis}"),
        )?;
        require(
            health.get("entry_counts").and_then(|value| value.as_object()).is_some(),
            format!("memory health missing entry counts: {health}"),
        )?;

        metrics = json!({
            "run_id": run_id,
            "section_count": section_summaries.len(),
            "total_failure_lessons": diagnosis.get("total_failure_lessons").cloned().unwrap_or(serde_json::Value::Null),
            "entry_count_keys": health.get("entry_counts").and_then(|value| value.as_object()).map(|map| map.len()).unwrap_or(0),
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/10_full_learning_loop_smoke.rs (line 81)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_10_full_learning_loop_smoke";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_10_full_learning_loop_smoke");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        remember.occurrence_time = Some(std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() as i64 - 86400);
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut mental_model = RememberOptions::new(
            "Claims case overview: Policy limit 5000 GBP, claimant city Leeds, \
             missing-city branch resolved via stored claim facts. Lesson: check stored facts before escalating.",
        );
        mental_model.run_id = Some(run_id.clone());
        mental_model.agent_id = Some("planner".to_string());
        mental_model.intent = Some("mental_model".to_string());
        mental_model.importance = Some("critical".to_string());
        mental_model.metadata = Some(json!({"suite": "all-helpers", "entity": "claims-case", "consolidated": true}));
        let mental_model_response = client.remember(mental_model).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "mental_model".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(mental_model_response.get("job_id").is_some() || mental_model_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("mental_model remember failed: {mental_model_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/helper_all_helpers.rs (line 69)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_all_helpers";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_all_helpers");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        let scratch_run = format!("{run_id}_forget");
        let mut scratch = RememberOptions::new("Scratch run for forget helper coverage.");
        scratch.run_id = Some(scratch_run.clone());
        scratch.agent_id = Some("planner".to_string());
        scratch.intent = Some("fact".to_string());
        scratch.metadata = Some(json!({"suite": "all-helpers", "temporary": true}));
        let scratch_response = client.remember(scratch).await?;

        let forget_response = client
            .forget(ForgetOptions::for_run(scratch_run.clone()))
            .await?;

        let mut forgotten = RecallOptions::new("What temporary scratch fact exists?");
        forgotten.run_id = Some(scratch_run.clone());
        forgotten.limit = 3;
        let forgotten_response = client.recall(forgotten).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;
        require(scratch_response.get("job_id").is_some() || scratch_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("scratch remember failed: {scratch_response}"))?;
        require(forget_response.get("success").and_then(Value::as_bool).unwrap_or(true), format!("forget failed: {forget_response}"))?;
        let scratch_fact_visible = forgotten_response
            .get("evidence")
            .and_then(Value::as_array)
            .map(|items| {
                items.iter().any(|item| {
                    item.get("run_id").and_then(Value::as_str) == Some(scratch_run.as_str())
                        || item
                            .get("content")
                            .and_then(Value::as_str)
                            .map(|content| {
                                content
                                    .to_ascii_lowercase()
                                    .contains("scratch run for forget helper coverage")
                            })
                            .unwrap_or(false)
                })
            })
            .unwrap_or(false);
        require(!scratch_fact_visible, format!("scratch fact should be forgotten even if same-user lessons still surface: {forgotten_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
            "forgotten_run": scratch_run,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

pub async fn reflect(&self, options: ReflectOptions) -> Result<Value>

Examples found in repository

examples/public/10_full_learning_loop_smoke.rs (line 85)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_10_full_learning_loop_smoke";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_10_full_learning_loop_smoke");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        remember.occurrence_time = Some(std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() as i64 - 86400);
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut mental_model = RememberOptions::new(
            "Claims case overview: Policy limit 5000 GBP, claimant city Leeds, \
             missing-city branch resolved via stored claim facts. Lesson: check stored facts before escalating.",
        );
        mental_model.run_id = Some(run_id.clone());
        mental_model.agent_id = Some("planner".to_string());
        mental_model.intent = Some("mental_model".to_string());
        mental_model.importance = Some("critical".to_string());
        mental_model.metadata = Some(json!({"suite": "all-helpers", "entity": "claims-case", "consolidated": true}));
        let mental_model_response = client.remember(mental_model).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "mental_model".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(mental_model_response.get("job_id").is_some() || mental_model_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("mental_model remember failed: {mental_model_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/helper_all_helpers.rs (line 73)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_all_helpers";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_all_helpers");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        let scratch_run = format!("{run_id}_forget");
        let mut scratch = RememberOptions::new("Scratch run for forget helper coverage.");
        scratch.run_id = Some(scratch_run.clone());
        scratch.agent_id = Some("planner".to_string());
        scratch.intent = Some("fact".to_string());
        scratch.metadata = Some(json!({"suite": "all-helpers", "temporary": true}));
        let scratch_response = client.remember(scratch).await?;

        let forget_response = client
            .forget(ForgetOptions::for_run(scratch_run.clone()))
            .await?;

        let mut forgotten = RecallOptions::new("What temporary scratch fact exists?");
        forgotten.run_id = Some(scratch_run.clone());
        forgotten.limit = 3;
        let forgotten_response = client.recall(forgotten).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;
        require(scratch_response.get("job_id").is_some() || scratch_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("scratch remember failed: {scratch_response}"))?;
        require(forget_response.get("success").and_then(Value::as_bool).unwrap_or(true), format!("forget failed: {forget_response}"))?;
        let scratch_fact_visible = forgotten_response
            .get("evidence")
            .and_then(Value::as_array)
            .map(|items| {
                items.iter().any(|item| {
                    item.get("run_id").and_then(Value::as_str) == Some(scratch_run.as_str())
                        || item
                            .get("content")
                            .and_then(Value::as_str)
                            .map(|content| {
                                content
                                    .to_ascii_lowercase()
                                    .contains("scratch run for forget helper coverage")
                            })
                            .unwrap_or(false)
                })
            })
            .unwrap_or(false);
        require(!scratch_fact_visible, format!("scratch fact should be forgotten even if same-user lessons still surface: {forgotten_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
            "forgotten_run": scratch_run,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

pub async fn forget(&self, options: ForgetOptions) -> Result<Value>

Examples found in repository

examples/helper_all_helpers.rs (line 171)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_all_helpers";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_all_helpers");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        let scratch_run = format!("{run_id}_forget");
        let mut scratch = RememberOptions::new("Scratch run for forget helper coverage.");
        scratch.run_id = Some(scratch_run.clone());
        scratch.agent_id = Some("planner".to_string());
        scratch.intent = Some("fact".to_string());
        scratch.metadata = Some(json!({"suite": "all-helpers", "temporary": true}));
        let scratch_response = client.remember(scratch).await?;

        let forget_response = client
            .forget(ForgetOptions::for_run(scratch_run.clone()))
            .await?;

        let mut forgotten = RecallOptions::new("What temporary scratch fact exists?");
        forgotten.run_id = Some(scratch_run.clone());
        forgotten.limit = 3;
        let forgotten_response = client.recall(forgotten).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;
        require(scratch_response.get("job_id").is_some() || scratch_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("scratch remember failed: {scratch_response}"))?;
        require(forget_response.get("success").and_then(Value::as_bool).unwrap_or(true), format!("forget failed: {forget_response}"))?;
        let scratch_fact_visible = forgotten_response
            .get("evidence")
            .and_then(Value::as_array)
            .map(|items| {
                items.iter().any(|item| {
                    item.get("run_id").and_then(Value::as_str) == Some(scratch_run.as_str())
                        || item
                            .get("content")
                            .and_then(Value::as_str)
                            .map(|content| {
                                content
                                    .to_ascii_lowercase()
                                    .contains("scratch run for forget helper coverage")
                            })
                            .unwrap_or(false)
                })
            })
            .unwrap_or(false);
        require(!scratch_fact_visible, format!("scratch fact should be forgotten even if same-user lessons still surface: {forgotten_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
            "forgotten_run": scratch_run,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

pub async fn checkpoint(&self, options: CheckpointOptions) -> Result<Value>

Examples found in repository

examples/helper_mas_learning_loop.rs (line 53)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_mas_learning_loop";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_mas_learning_loop");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper MAS checkpoint/outcome/strategies flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["rule".to_string(), "lesson".to_string(), "fact".to_string()];
        register.write_scopes = vec!["lesson".to_string(), "trace".to_string()];
        register.shared_memory_lanes = vec!["knowledge".to_string(), "history".to_string()];
        client.register_agent(register).await?;

        let mut remember = RememberOptions::new(
            "If a retry succeeds after token signer rotation, record it as a reusable recovery pattern.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("success".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.lesson_importance = Some("high".to_string());
        client.remember(remember).await?;

        let mut checkpoint = CheckpointOptions::new(
            "Planner isolated the recovery path to token signer rotation.",
        );
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction-1".to_string());
        checkpoint.metadata = Some(json!({ "stage": "analysis" }));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents = client.list_agents(list_agents).await?;

        let lessons = client.control.lessons(json!({ "run_id": run_id, "limit": 10 })).await?;
        let lesson_id = lessons
            .get("lessons")
            .and_then(|value| value.as_array())
            .and_then(|items| items.first())
            .and_then(|item| item.get("id"))
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("expected at least one lesson to record outcome against: {lessons}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Recovery succeeded after following the stored lesson.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "failure".to_string()];
        strategies.max_strategies = 5;
        let strategy_response = client.surface_strategies(strategies).await?;

        require(
            checkpoint_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("checkpoint failed: {checkpoint_response}"),
        )?;
        let agent_count = agents
            .get("agents")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);
        require(agent_count == 1, format!("agent registration missing: {agents}"))?;
        require(
            outcome_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("record_outcome failed: {outcome_response}"),
        )?;
        let strategy_count = strategy_response
            .get("strategies")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "checkpoint_id": checkpoint_response.get("checkpoint_id").cloned().unwrap_or(serde_json::Value::Null),
            "agent_count": agent_count,
            "strategy_count": strategy_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/03_checkpoint_reflect_outcome.rs (line 53)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_03_checkpoint_reflect_outcome";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_03_checkpoint_reflect_outcome");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper MAS checkpoint/outcome/strategies flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["rule".to_string(), "lesson".to_string(), "fact".to_string()];
        register.write_scopes = vec!["lesson".to_string(), "trace".to_string()];
        register.shared_memory_lanes = vec!["knowledge".to_string(), "history".to_string()];
        client.register_agent(register).await?;

        let mut remember = RememberOptions::new(
            "If a retry succeeds after token signer rotation, record it as a reusable recovery pattern.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("success".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.lesson_importance = Some("high".to_string());
        client.remember(remember).await?;

        let mut checkpoint = CheckpointOptions::new(
            "Planner isolated the recovery path to token signer rotation.",
        );
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction-1".to_string());
        checkpoint.metadata = Some(json!({ "stage": "analysis" }));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents = client.list_agents(list_agents).await?;

        let lessons = client.control.lessons(json!({ "run_id": run_id, "limit": 10 })).await?;
        let lesson_id = lessons
            .get("lessons")
            .and_then(|value| value.as_array())
            .and_then(|items| items.first())
            .and_then(|item| item.get("id"))
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("expected at least one lesson to record outcome against: {lessons}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Recovery succeeded after following the stored lesson.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "failure".to_string()];
        strategies.max_strategies = 5;
        let strategy_response = client.surface_strategies(strategies).await?;

        require(
            checkpoint_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("checkpoint failed: {checkpoint_response}"),
        )?;
        let agent_count = agents
            .get("agents")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);
        require(agent_count == 1, format!("agent registration missing: {agents}"))?;
        require(
            outcome_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("record_outcome failed: {outcome_response}"),
        )?;
        let strategy_count = strategy_response
            .get("strategies")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "checkpoint_id": checkpoint_response.get("checkpoint_id").cloned().unwrap_or(serde_json::Value::Null),
            "agent_count": agent_count,
            "strategy_count": strategy_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/08_multi_agent_claims_or_support_flow.rs (line 61)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_08_multi_agent_claims_or_support_flow";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_claims_flow");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated multi-agent claims/support flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        for (agent_id, role, read_scopes, write_scopes) in [
            ("intake", "intake", vec!["fact", "archive_block"], vec!["fact", "archive_block", "trace"]),
            ("coverage", "coverage", vec!["fact", "rule", "archive_block", "handoff", "feedback"], vec!["fact", "trace", "lesson"]),
            ("reviewer", "reviewer", vec!["fact", "archive_block", "handoff", "feedback", "rule"], vec!["feedback", "rule"]),
        ] {
            let mut agent = RegisterAgentOptions::new(agent_id);
            agent.run_id = Some(run_id.clone());
            agent.role = role.to_string();
            agent.read_scopes = read_scopes.into_iter().map(String::from).collect();
            agent.write_scopes = write_scopes.into_iter().map(String::from).collect();
            agent.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
            client.register_agent(agent).await?;
        }

        let mut fact = RememberOptions::new("Policy P-8842 covers windshield damage with a 250 GBP deductible.");
        fact.run_id = Some(run_id.clone());
        fact.agent_id = Some("intake".into());
        fact.intent = Some("fact".into());
        fact.metadata = Some(json!({"claim_id": "CLM-8842", "source": "intake-form"}));
        client.remember(fact).await?;

        let mut archive = ArchiveOptions::new("Exact adjuster note: customer confirmed the damage happened on the motorway and no third party was involved.", "adjuster_note");
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("intake".into());
        archive.origin_agent_id = Some("intake".into());
        archive.source_attempt_id = Some("attempt-1".into());
        archive.source_tool = Some("claim-review".into());
        archive.labels = vec!["claims".into(), "coverage".into()];
        archive.family = Some("windshield".into());
        let archived = client.archive(archive).await?;
        let reference_id = archived.get("reference_id").and_then(|v| v.as_str()).ok_or_else(|| boxed_error(format!("archive reference missing: {archived}")))?.to_string();

        let mut checkpoint = CheckpointOptions::new("Coverage verified deductible and adjuster note before escalation.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-review".into());
        checkpoint.agent_id = Some("coverage".into());
        checkpoint.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let mut handoff = HandoffOptions::new("claim-8842", "coverage", "reviewer", "Review whether the adjuster note is enough to approve the claim.");
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".into();
        handoff.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response.get("handoff_id").and_then(|v| v.as_str()).ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?.to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.from_agent_id = Some("reviewer".into());
        feedback.comments = "Deductible and adjuster note are sufficient for routing.".into();
        feedback.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let feedback_response = client.feedback(feedback).await?;

        let mut context_opts = GetContextOptions::default();
        context_opts.run_id = Some(run_id.clone());
        context_opts.query = Some("Prepare the final claims routing summary.".into());
        context_opts.agent_id = Some("coverage".into());
        context_opts.sections = vec!["archive".into(), "facts".into(), "handoffs".into(), "feedback".into()];
        context_opts.mode = Some("sections".into());
        let context = client.get_context(context_opts).await?;

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("coverage".into());
        let exact = client.dereference(dereference).await?;

        let mut recall = RecallOptions::new("What deductible applies and what did the adjuster confirm?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("coverage".into());
        recall.entry_types = vec!["fact".into(), "archive_block".into(), "feedback".into()];
        let recall_response = client.recall(recall).await?;

        require(checkpoint_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(handoff_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;
        require(exact.get("found").and_then(|v| v.as_bool()).unwrap_or(false), format!("dereference failed: {exact}"))?;
        let context_text = context.get("context_block").and_then(|v| v.as_str()).unwrap_or("").to_lowercase();
        let recall_text = recall_response.get("final_answer").and_then(|v| v.as_str()).unwrap_or("").to_lowercase();
        let has_archive_source = context
            .get("sources")
            .and_then(|v| v.as_array())
            .map(|sources| {
                sources.iter().any(|source| {
                    source
                        .get("entry_type")
                        .and_then(|v| v.as_str())
                        == Some("archive_block")
                })
            })
            .unwrap_or(false);
        let exact_refs_surfaced = context
            .get("exact_references_surfaced")
            .and_then(|v| v.as_u64())
            .unwrap_or(0);
        require(
            context_text.contains("adjuster note")
                || context_text.contains("motorway")
                || has_archive_source
                || exact_refs_surfaced > 0,
            format!("expected explicit or telemetry-backed exact reuse in context: {context}"),
        )?;
        require(recall_text.contains("250") && (recall_text.contains("motorway") || recall_text.contains("third party")), format!("expected recall to include fact + archive content: {recall_response}"))?;

        metrics = json!({
            "run_id": run_id,
            "handoff_id": handoff_id,
            "reference_id": reference_id,
            "feedback_id": feedback_response.get("feedback_id").cloned().unwrap_or(serde_json::Value::Null),
        });
        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);
    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/public/10_full_learning_loop_smoke.rs (line 128)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_10_full_learning_loop_smoke";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_10_full_learning_loop_smoke");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        remember.occurrence_time = Some(std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() as i64 - 86400);
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut mental_model = RememberOptions::new(
            "Claims case overview: Policy limit 5000 GBP, claimant city Leeds, \
             missing-city branch resolved via stored claim facts. Lesson: check stored facts before escalating.",
        );
        mental_model.run_id = Some(run_id.clone());
        mental_model.agent_id = Some("planner".to_string());
        mental_model.intent = Some("mental_model".to_string());
        mental_model.importance = Some("critical".to_string());
        mental_model.metadata = Some(json!({"suite": "all-helpers", "entity": "claims-case", "consolidated": true}));
        let mental_model_response = client.remember(mental_model).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "mental_model".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(mental_model_response.get("job_id").is_some() || mental_model_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("mental_model remember failed: {mental_model_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/helper_all_helpers.rs (line 116)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_all_helpers";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_all_helpers");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        let scratch_run = format!("{run_id}_forget");
        let mut scratch = RememberOptions::new("Scratch run for forget helper coverage.");
        scratch.run_id = Some(scratch_run.clone());
        scratch.agent_id = Some("planner".to_string());
        scratch.intent = Some("fact".to_string());
        scratch.metadata = Some(json!({"suite": "all-helpers", "temporary": true}));
        let scratch_response = client.remember(scratch).await?;

        let forget_response = client
            .forget(ForgetOptions::for_run(scratch_run.clone()))
            .await?;

        let mut forgotten = RecallOptions::new("What temporary scratch fact exists?");
        forgotten.run_id = Some(scratch_run.clone());
        forgotten.limit = 3;
        let forgotten_response = client.recall(forgotten).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;
        require(scratch_response.get("job_id").is_some() || scratch_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("scratch remember failed: {scratch_response}"))?;
        require(forget_response.get("success").and_then(Value::as_bool).unwrap_or(true), format!("forget failed: {forget_response}"))?;
        let scratch_fact_visible = forgotten_response
            .get("evidence")
            .and_then(Value::as_array)
            .map(|items| {
                items.iter().any(|item| {
                    item.get("run_id").and_then(Value::as_str) == Some(scratch_run.as_str())
                        || item
                            .get("content")
                            .and_then(Value::as_str)
                            .map(|content| {
                                content
                                    .to_ascii_lowercase()
                                    .contains("scratch run for forget helper coverage")
                            })
                            .unwrap_or(false)
                })
            })
            .unwrap_or(false);
        require(!scratch_fact_visible, format!("scratch fact should be forgotten even if same-user lessons still surface: {forgotten_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
            "forgotten_run": scratch_run,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

pub async fn register_agent( &self, options: RegisterAgentOptions, ) -> Result<Value>

Examples found in repository

examples/helper_handoff_feedback.rs (line 29)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_handoff_feedback";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_handoff_feedback");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper handoff + feedback flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut planner = RegisterAgentOptions::new("planner");
        planner.run_id = Some(run_id.clone());
        planner.role = "planner".to_string();
        client.register_agent(planner).await?;

        let mut reviewer = RegisterAgentOptions::new("reviewer");
        reviewer.run_id = Some(run_id.clone());
        reviewer.role = "reviewer".to_string();
        client.register_agent(reviewer).await?;

        let mut handoff = HandoffOptions::new(
            "task-1",
            "planner",
            "reviewer",
            "Review the retry policy patch before rollout.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({ "source": "rust-helper-example" }));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Patch looks safe for rollout.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({ "source": "rust-helper-example" }));
        let feedback_response = client.feedback(feedback).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("What coordination artifacts were recorded for this review handoff?".to_string());
        context.mode = Some("sections".to_string());
        context.sections = vec!["handoffs".to_string(), "feedback".to_string()];
        let context_response = client.get_context(context).await?;

        require(
            handoff_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("handoff failed: {handoff_response}"),
        )?;
        require(
            feedback_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("feedback failed: {feedback_response}"),
        )?;
        let section_count = context_response
            .get("section_summaries")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "handoff_id": handoff_id,
            "feedback_id": feedback_response.get("feedback_id").cloned().unwrap_or(serde_json::Value::Null),
            "section_count": section_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/06_handoff_feedback.rs (line 29)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_06_handoff_feedback";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_06_handoff_feedback");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper handoff + feedback flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut planner = RegisterAgentOptions::new("planner");
        planner.run_id = Some(run_id.clone());
        planner.role = "planner".to_string();
        client.register_agent(planner).await?;

        let mut reviewer = RegisterAgentOptions::new("reviewer");
        reviewer.run_id = Some(run_id.clone());
        reviewer.role = "reviewer".to_string();
        client.register_agent(reviewer).await?;

        let mut handoff = HandoffOptions::new(
            "task-1",
            "planner",
            "reviewer",
            "Review the retry policy patch before rollout.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({ "source": "rust-helper-example" }));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Patch looks safe for rollout.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({ "source": "rust-helper-example" }));
        let feedback_response = client.feedback(feedback).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("What coordination artifacts were recorded for this review handoff?".to_string());
        context.mode = Some("sections".to_string());
        context.sections = vec!["handoffs".to_string(), "feedback".to_string()];
        let context_response = client.get_context(context).await?;

        require(
            handoff_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("handoff failed: {handoff_response}"),
        )?;
        require(
            feedback_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("feedback failed: {feedback_response}"),
        )?;
        let section_count = context_response
            .get("section_summaries")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "handoff_id": handoff_id,
            "feedback_id": feedback_response.get("feedback_id").cloned().unwrap_or(serde_json::Value::Null),
            "section_count": section_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/helper_mas_learning_loop.rs (line 33)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_mas_learning_loop";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_mas_learning_loop");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper MAS checkpoint/outcome/strategies flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["rule".to_string(), "lesson".to_string(), "fact".to_string()];
        register.write_scopes = vec!["lesson".to_string(), "trace".to_string()];
        register.shared_memory_lanes = vec!["knowledge".to_string(), "history".to_string()];
        client.register_agent(register).await?;

        let mut remember = RememberOptions::new(
            "If a retry succeeds after token signer rotation, record it as a reusable recovery pattern.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("success".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.lesson_importance = Some("high".to_string());
        client.remember(remember).await?;

        let mut checkpoint = CheckpointOptions::new(
            "Planner isolated the recovery path to token signer rotation.",
        );
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction-1".to_string());
        checkpoint.metadata = Some(json!({ "stage": "analysis" }));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents = client.list_agents(list_agents).await?;

        let lessons = client.control.lessons(json!({ "run_id": run_id, "limit": 10 })).await?;
        let lesson_id = lessons
            .get("lessons")
            .and_then(|value| value.as_array())
            .and_then(|items| items.first())
            .and_then(|item| item.get("id"))
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("expected at least one lesson to record outcome against: {lessons}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Recovery succeeded after following the stored lesson.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "failure".to_string()];
        strategies.max_strategies = 5;
        let strategy_response = client.surface_strategies(strategies).await?;

        require(
            checkpoint_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("checkpoint failed: {checkpoint_response}"),
        )?;
        let agent_count = agents
            .get("agents")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);
        require(agent_count == 1, format!("agent registration missing: {agents}"))?;
        require(
            outcome_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("record_outcome failed: {outcome_response}"),
        )?;
        let strategy_count = strategy_response
            .get("strategies")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "checkpoint_id": checkpoint_response.get("checkpoint_id").cloned().unwrap_or(serde_json::Value::Null),
            "agent_count": agent_count,
            "strategy_count": strategy_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/03_checkpoint_reflect_outcome.rs (line 33)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_03_checkpoint_reflect_outcome";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_03_checkpoint_reflect_outcome");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper MAS checkpoint/outcome/strategies flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["rule".to_string(), "lesson".to_string(), "fact".to_string()];
        register.write_scopes = vec!["lesson".to_string(), "trace".to_string()];
        register.shared_memory_lanes = vec!["knowledge".to_string(), "history".to_string()];
        client.register_agent(register).await?;

        let mut remember = RememberOptions::new(
            "If a retry succeeds after token signer rotation, record it as a reusable recovery pattern.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("success".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.lesson_importance = Some("high".to_string());
        client.remember(remember).await?;

        let mut checkpoint = CheckpointOptions::new(
            "Planner isolated the recovery path to token signer rotation.",
        );
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction-1".to_string());
        checkpoint.metadata = Some(json!({ "stage": "analysis" }));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents = client.list_agents(list_agents).await?;

        let lessons = client.control.lessons(json!({ "run_id": run_id, "limit": 10 })).await?;
        let lesson_id = lessons
            .get("lessons")
            .and_then(|value| value.as_array())
            .and_then(|items| items.first())
            .and_then(|item| item.get("id"))
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("expected at least one lesson to record outcome against: {lessons}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Recovery succeeded after following the stored lesson.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "failure".to_string()];
        strategies.max_strategies = 5;
        let strategy_response = client.surface_strategies(strategies).await?;

        require(
            checkpoint_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("checkpoint failed: {checkpoint_response}"),
        )?;
        let agent_count = agents
            .get("agents")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);
        require(agent_count == 1, format!("agent registration missing: {agents}"))?;
        require(
            outcome_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("record_outcome failed: {outcome_response}"),
        )?;
        let strategy_count = strategy_response
            .get("strategies")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "checkpoint_id": checkpoint_response.get("checkpoint_id").cloned().unwrap_or(serde_json::Value::Null),
            "agent_count": agent_count,
            "strategy_count": strategy_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/05_agent_registration_and_scoped_access.rs (line 30)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_05_agent_registration_and_scoped_access";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_agent_scopes");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated agent registration and scoped access".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut planner = RegisterAgentOptions::new("planner");
        planner.run_id = Some(run_id.clone());
        planner.role = "planner".to_string();
        planner.read_scopes = vec!["fact".into(), "lesson".into()];
        planner.write_scopes = vec!["fact".into(), "lesson".into()];
        planner.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        client.register_agent(planner).await?;

        let mut reviewer = RegisterAgentOptions::new("reviewer");
        reviewer.run_id = Some(run_id.clone());
        reviewer.role = "reviewer".to_string();
        reviewer.read_scopes = vec!["rule".into(), "trace".into()];
        reviewer.write_scopes = vec!["rule".into(), "trace".into()];
        reviewer.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        client.register_agent(reviewer).await?;

        let mut planner_fact = RememberOptions::new("Claim requires police report only when payout exceeds 3000 GBP.");
        planner_fact.run_id = Some(run_id.clone());
        planner_fact.agent_id = Some("planner".into());
        planner_fact.intent = Some("fact".into());
        planner_fact.metadata = Some(json!({"source": "planner"}));
        let planner_write = client.remember(planner_fact).await?;

        let mut reviewer_rule = RememberOptions::new("Escalate to compliance if a police report is missing after payout approval.");
        reviewer_rule.run_id = Some(run_id.clone());
        reviewer_rule.agent_id = Some("reviewer".into());
        reviewer_rule.intent = Some("rule".into());
        reviewer_rule.metadata = Some(json!({"source": "reviewer"}));
        let reviewer_write = client.remember(reviewer_rule).await?;

        let mut planner_context_opts = GetContextOptions::default();
        planner_context_opts.run_id = Some(run_id.clone());
        planner_context_opts.query = Some("What should planner know before triage?".into());
        planner_context_opts.agent_id = Some("planner".into());
        planner_context_opts.entry_types = vec!["fact".into(), "lesson".into(), "rule".into()];
        planner_context_opts.mode = Some("sections".into());
        planner_context_opts.sections = vec!["facts".into(), "rules".into()];
        let planner_context = client.get_context(planner_context_opts).await?;

        let mut reviewer_context_opts = GetContextOptions::default();
        reviewer_context_opts.run_id = Some(run_id.clone());
        reviewer_context_opts.query = Some("What should reviewer know before approval?".into());
        reviewer_context_opts.agent_id = Some("reviewer".into());
        reviewer_context_opts.entry_types = vec!["fact".into(), "lesson".into(), "rule".into(), "trace".into()];
        reviewer_context_opts.mode = Some("sections".into());
        reviewer_context_opts.sections = vec!["facts".into(), "rules".into()];
        let reviewer_context = client.get_context(reviewer_context_opts).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents = client.list_agents(list_agents).await?;

        require(planner_write.get("accepted").and_then(|v| v.as_bool()).unwrap_or(false) || planner_write.get("job_id").is_some(), format!("planner remember failed: {planner_write}"))?;
        require(reviewer_write.get("accepted").and_then(|v| v.as_bool()).unwrap_or(false) || reviewer_write.get("job_id").is_some(), format!("reviewer remember failed: {reviewer_write}"))?;
        let agent_count = agents.get("agents").and_then(|v| v.as_array()).map(|items| items.len()).unwrap_or(0);
        require(agent_count == 2, format!("agent registration failed: {agents}"))?;

        let planner_types: Vec<&str> = planner_context.get("sources").and_then(|v| v.as_array()).into_iter().flatten().filter_map(|source| source.get("entry_type").and_then(|v| v.as_str())).collect();
        let reviewer_types: Vec<&str> = reviewer_context.get("sources").and_then(|v| v.as_array()).into_iter().flatten().filter_map(|source| source.get("entry_type").and_then(|v| v.as_str())).collect();
        require(planner_types.iter().any(|t| *t == "fact"), format!("planner should see facts: {planner_context}"))?;
        require(!planner_types.iter().any(|t| *t == "rule"), format!("planner should not see reviewer rule scope: {planner_context}"))?;
        require(reviewer_types.iter().any(|t| *t == "rule"), format!("reviewer should see rules: {reviewer_context}"))?;

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "planner_source_types": planner_types,
            "reviewer_source_types": reviewer_types,
        });
        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);
    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/public/08_multi_agent_claims_or_support_flow.rs (line 35)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_08_multi_agent_claims_or_support_flow";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_claims_flow");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated multi-agent claims/support flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        for (agent_id, role, read_scopes, write_scopes) in [
            ("intake", "intake", vec!["fact", "archive_block"], vec!["fact", "archive_block", "trace"]),
            ("coverage", "coverage", vec!["fact", "rule", "archive_block", "handoff", "feedback"], vec!["fact", "trace", "lesson"]),
            ("reviewer", "reviewer", vec!["fact", "archive_block", "handoff", "feedback", "rule"], vec!["feedback", "rule"]),
        ] {
            let mut agent = RegisterAgentOptions::new(agent_id);
            agent.run_id = Some(run_id.clone());
            agent.role = role.to_string();
            agent.read_scopes = read_scopes.into_iter().map(String::from).collect();
            agent.write_scopes = write_scopes.into_iter().map(String::from).collect();
            agent.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
            client.register_agent(agent).await?;
        }

        let mut fact = RememberOptions::new("Policy P-8842 covers windshield damage with a 250 GBP deductible.");
        fact.run_id = Some(run_id.clone());
        fact.agent_id = Some("intake".into());
        fact.intent = Some("fact".into());
        fact.metadata = Some(json!({"claim_id": "CLM-8842", "source": "intake-form"}));
        client.remember(fact).await?;

        let mut archive = ArchiveOptions::new("Exact adjuster note: customer confirmed the damage happened on the motorway and no third party was involved.", "adjuster_note");
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("intake".into());
        archive.origin_agent_id = Some("intake".into());
        archive.source_attempt_id = Some("attempt-1".into());
        archive.source_tool = Some("claim-review".into());
        archive.labels = vec!["claims".into(), "coverage".into()];
        archive.family = Some("windshield".into());
        let archived = client.archive(archive).await?;
        let reference_id = archived.get("reference_id").and_then(|v| v.as_str()).ok_or_else(|| boxed_error(format!("archive reference missing: {archived}")))?.to_string();

        let mut checkpoint = CheckpointOptions::new("Coverage verified deductible and adjuster note before escalation.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-review".into());
        checkpoint.agent_id = Some("coverage".into());
        checkpoint.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let mut handoff = HandoffOptions::new("claim-8842", "coverage", "reviewer", "Review whether the adjuster note is enough to approve the claim.");
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".into();
        handoff.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response.get("handoff_id").and_then(|v| v.as_str()).ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?.to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.from_agent_id = Some("reviewer".into());
        feedback.comments = "Deductible and adjuster note are sufficient for routing.".into();
        feedback.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let feedback_response = client.feedback(feedback).await?;

        let mut context_opts = GetContextOptions::default();
        context_opts.run_id = Some(run_id.clone());
        context_opts.query = Some("Prepare the final claims routing summary.".into());
        context_opts.agent_id = Some("coverage".into());
        context_opts.sections = vec!["archive".into(), "facts".into(), "handoffs".into(), "feedback".into()];
        context_opts.mode = Some("sections".into());
        let context = client.get_context(context_opts).await?;

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("coverage".into());
        let exact = client.dereference(dereference).await?;

        let mut recall = RecallOptions::new("What deductible applies and what did the adjuster confirm?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("coverage".into());
        recall.entry_types = vec!["fact".into(), "archive_block".into(), "feedback".into()];
        let recall_response = client.recall(recall).await?;

        require(checkpoint_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(handoff_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;
        require(exact.get("found").and_then(|v| v.as_bool()).unwrap_or(false), format!("dereference failed: {exact}"))?;
        let context_text = context.get("context_block").and_then(|v| v.as_str()).unwrap_or("").to_lowercase();
        let recall_text = recall_response.get("final_answer").and_then(|v| v.as_str()).unwrap_or("").to_lowercase();
        let has_archive_source = context
            .get("sources")
            .and_then(|v| v.as_array())
            .map(|sources| {
                sources.iter().any(|source| {
                    source
                        .get("entry_type")
                        .and_then(|v| v.as_str())
                        == Some("archive_block")
                })
            })
            .unwrap_or(false);
        let exact_refs_surfaced = context
            .get("exact_references_surfaced")
            .and_then(|v| v.as_u64())
            .unwrap_or(0);
        require(
            context_text.contains("adjuster note")
                || context_text.contains("motorway")
                || has_archive_source
                || exact_refs_surfaced > 0,
            format!("expected explicit or telemetry-backed exact reuse in context: {context}"),
        )?;
        require(recall_text.contains("250") && (recall_text.contains("motorway") || recall_text.contains("third party")), format!("expected recall to include fact + archive content: {recall_response}"))?;

        metrics = json!({
            "run_id": run_id,
            "handoff_id": handoff_id,
            "reference_id": reference_id,
            "feedback_id": feedback_response.get("feedback_id").cloned().unwrap_or(serde_json::Value::Null),
        });
        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);
    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

Additional examples can be found in:

• examples/public/10_full_learning_loop_smoke.rs
• examples/helper_all_helpers.rs

pub async fn list_agents(&self, options: ListAgentsOptions) -> Result<Value>

Examples found in repository

examples/helper_mas_learning_loop.rs (line 57)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_mas_learning_loop";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_mas_learning_loop");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper MAS checkpoint/outcome/strategies flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["rule".to_string(), "lesson".to_string(), "fact".to_string()];
        register.write_scopes = vec!["lesson".to_string(), "trace".to_string()];
        register.shared_memory_lanes = vec!["knowledge".to_string(), "history".to_string()];
        client.register_agent(register).await?;

        let mut remember = RememberOptions::new(
            "If a retry succeeds after token signer rotation, record it as a reusable recovery pattern.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("success".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.lesson_importance = Some("high".to_string());
        client.remember(remember).await?;

        let mut checkpoint = CheckpointOptions::new(
            "Planner isolated the recovery path to token signer rotation.",
        );
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction-1".to_string());
        checkpoint.metadata = Some(json!({ "stage": "analysis" }));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents = client.list_agents(list_agents).await?;

        let lessons = client.control.lessons(json!({ "run_id": run_id, "limit": 10 })).await?;
        let lesson_id = lessons
            .get("lessons")
            .and_then(|value| value.as_array())
            .and_then(|items| items.first())
            .and_then(|item| item.get("id"))
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("expected at least one lesson to record outcome against: {lessons}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Recovery succeeded after following the stored lesson.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "failure".to_string()];
        strategies.max_strategies = 5;
        let strategy_response = client.surface_strategies(strategies).await?;

        require(
            checkpoint_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("checkpoint failed: {checkpoint_response}"),
        )?;
        let agent_count = agents
            .get("agents")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);
        require(agent_count == 1, format!("agent registration missing: {agents}"))?;
        require(
            outcome_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("record_outcome failed: {outcome_response}"),
        )?;
        let strategy_count = strategy_response
            .get("strategies")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "checkpoint_id": checkpoint_response.get("checkpoint_id").cloned().unwrap_or(serde_json::Value::Null),
            "agent_count": agent_count,
            "strategy_count": strategy_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/03_checkpoint_reflect_outcome.rs (line 57)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_03_checkpoint_reflect_outcome";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_03_checkpoint_reflect_outcome");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper MAS checkpoint/outcome/strategies flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["rule".to_string(), "lesson".to_string(), "fact".to_string()];
        register.write_scopes = vec!["lesson".to_string(), "trace".to_string()];
        register.shared_memory_lanes = vec!["knowledge".to_string(), "history".to_string()];
        client.register_agent(register).await?;

        let mut remember = RememberOptions::new(
            "If a retry succeeds after token signer rotation, record it as a reusable recovery pattern.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("success".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.lesson_importance = Some("high".to_string());
        client.remember(remember).await?;

        let mut checkpoint = CheckpointOptions::new(
            "Planner isolated the recovery path to token signer rotation.",
        );
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction-1".to_string());
        checkpoint.metadata = Some(json!({ "stage": "analysis" }));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents = client.list_agents(list_agents).await?;

        let lessons = client.control.lessons(json!({ "run_id": run_id, "limit": 10 })).await?;
        let lesson_id = lessons
            .get("lessons")
            .and_then(|value| value.as_array())
            .and_then(|items| items.first())
            .and_then(|item| item.get("id"))
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("expected at least one lesson to record outcome against: {lessons}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Recovery succeeded after following the stored lesson.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "failure".to_string()];
        strategies.max_strategies = 5;
        let strategy_response = client.surface_strategies(strategies).await?;

        require(
            checkpoint_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("checkpoint failed: {checkpoint_response}"),
        )?;
        let agent_count = agents
            .get("agents")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);
        require(agent_count == 1, format!("agent registration missing: {agents}"))?;
        require(
            outcome_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("record_outcome failed: {outcome_response}"),
        )?;
        let strategy_count = strategy_response
            .get("strategies")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "checkpoint_id": checkpoint_response.get("checkpoint_id").cloned().unwrap_or(serde_json::Value::Null),
            "agent_count": agent_count,
            "strategy_count": strategy_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/05_agent_registration_and_scoped_access.rs (line 74)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_05_agent_registration_and_scoped_access";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_agent_scopes");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated agent registration and scoped access".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut planner = RegisterAgentOptions::new("planner");
        planner.run_id = Some(run_id.clone());
        planner.role = "planner".to_string();
        planner.read_scopes = vec!["fact".into(), "lesson".into()];
        planner.write_scopes = vec!["fact".into(), "lesson".into()];
        planner.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        client.register_agent(planner).await?;

        let mut reviewer = RegisterAgentOptions::new("reviewer");
        reviewer.run_id = Some(run_id.clone());
        reviewer.role = "reviewer".to_string();
        reviewer.read_scopes = vec!["rule".into(), "trace".into()];
        reviewer.write_scopes = vec!["rule".into(), "trace".into()];
        reviewer.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        client.register_agent(reviewer).await?;

        let mut planner_fact = RememberOptions::new("Claim requires police report only when payout exceeds 3000 GBP.");
        planner_fact.run_id = Some(run_id.clone());
        planner_fact.agent_id = Some("planner".into());
        planner_fact.intent = Some("fact".into());
        planner_fact.metadata = Some(json!({"source": "planner"}));
        let planner_write = client.remember(planner_fact).await?;

        let mut reviewer_rule = RememberOptions::new("Escalate to compliance if a police report is missing after payout approval.");
        reviewer_rule.run_id = Some(run_id.clone());
        reviewer_rule.agent_id = Some("reviewer".into());
        reviewer_rule.intent = Some("rule".into());
        reviewer_rule.metadata = Some(json!({"source": "reviewer"}));
        let reviewer_write = client.remember(reviewer_rule).await?;

        let mut planner_context_opts = GetContextOptions::default();
        planner_context_opts.run_id = Some(run_id.clone());
        planner_context_opts.query = Some("What should planner know before triage?".into());
        planner_context_opts.agent_id = Some("planner".into());
        planner_context_opts.entry_types = vec!["fact".into(), "lesson".into(), "rule".into()];
        planner_context_opts.mode = Some("sections".into());
        planner_context_opts.sections = vec!["facts".into(), "rules".into()];
        let planner_context = client.get_context(planner_context_opts).await?;

        let mut reviewer_context_opts = GetContextOptions::default();
        reviewer_context_opts.run_id = Some(run_id.clone());
        reviewer_context_opts.query = Some("What should reviewer know before approval?".into());
        reviewer_context_opts.agent_id = Some("reviewer".into());
        reviewer_context_opts.entry_types = vec!["fact".into(), "lesson".into(), "rule".into(), "trace".into()];
        reviewer_context_opts.mode = Some("sections".into());
        reviewer_context_opts.sections = vec!["facts".into(), "rules".into()];
        let reviewer_context = client.get_context(reviewer_context_opts).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents = client.list_agents(list_agents).await?;

        require(planner_write.get("accepted").and_then(|v| v.as_bool()).unwrap_or(false) || planner_write.get("job_id").is_some(), format!("planner remember failed: {planner_write}"))?;
        require(reviewer_write.get("accepted").and_then(|v| v.as_bool()).unwrap_or(false) || reviewer_write.get("job_id").is_some(), format!("reviewer remember failed: {reviewer_write}"))?;
        let agent_count = agents.get("agents").and_then(|v| v.as_array()).map(|items| items.len()).unwrap_or(0);
        require(agent_count == 2, format!("agent registration failed: {agents}"))?;

        let planner_types: Vec<&str> = planner_context.get("sources").and_then(|v| v.as_array()).into_iter().flatten().filter_map(|source| source.get("entry_type").and_then(|v| v.as_str())).collect();
        let reviewer_types: Vec<&str> = reviewer_context.get("sources").and_then(|v| v.as_array()).into_iter().flatten().filter_map(|source| source.get("entry_type").and_then(|v| v.as_str())).collect();
        require(planner_types.iter().any(|t| *t == "fact"), format!("planner should see facts: {planner_context}"))?;
        require(!planner_types.iter().any(|t| *t == "rule"), format!("planner should not see reviewer rule scope: {planner_context}"))?;
        require(reviewer_types.iter().any(|t| *t == "rule"), format!("reviewer should see rules: {reviewer_context}"))?;

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "planner_source_types": planner_types,
            "reviewer_source_types": reviewer_types,
        });
        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);
    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/public/10_full_learning_loop_smoke.rs (line 97)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_10_full_learning_loop_smoke";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_10_full_learning_loop_smoke");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        remember.occurrence_time = Some(std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() as i64 - 86400);
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut mental_model = RememberOptions::new(
            "Claims case overview: Policy limit 5000 GBP, claimant city Leeds, \
             missing-city branch resolved via stored claim facts. Lesson: check stored facts before escalating.",
        );
        mental_model.run_id = Some(run_id.clone());
        mental_model.agent_id = Some("planner".to_string());
        mental_model.intent = Some("mental_model".to_string());
        mental_model.importance = Some("critical".to_string());
        mental_model.metadata = Some(json!({"suite": "all-helpers", "entity": "claims-case", "consolidated": true}));
        let mental_model_response = client.remember(mental_model).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "mental_model".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(mental_model_response.get("job_id").is_some() || mental_model_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("mental_model remember failed: {mental_model_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/helper_all_helpers.rs (line 85)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_all_helpers";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_all_helpers");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        let scratch_run = format!("{run_id}_forget");
        let mut scratch = RememberOptions::new("Scratch run for forget helper coverage.");
        scratch.run_id = Some(scratch_run.clone());
        scratch.agent_id = Some("planner".to_string());
        scratch.intent = Some("fact".to_string());
        scratch.metadata = Some(json!({"suite": "all-helpers", "temporary": true}));
        let scratch_response = client.remember(scratch).await?;

        let forget_response = client
            .forget(ForgetOptions::for_run(scratch_run.clone()))
            .await?;

        let mut forgotten = RecallOptions::new("What temporary scratch fact exists?");
        forgotten.run_id = Some(scratch_run.clone());
        forgotten.limit = 3;
        let forgotten_response = client.recall(forgotten).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;
        require(scratch_response.get("job_id").is_some() || scratch_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("scratch remember failed: {scratch_response}"))?;
        require(forget_response.get("success").and_then(Value::as_bool).unwrap_or(true), format!("forget failed: {forget_response}"))?;
        let scratch_fact_visible = forgotten_response
            .get("evidence")
            .and_then(Value::as_array)
            .map(|items| {
                items.iter().any(|item| {
                    item.get("run_id").and_then(Value::as_str) == Some(scratch_run.as_str())
                        || item
                            .get("content")
                            .and_then(Value::as_str)
                            .map(|content| {
                                content
                                    .to_ascii_lowercase()
                                    .contains("scratch run for forget helper coverage")
                            })
                            .unwrap_or(false)
                })
            })
            .unwrap_or(false);
        require(!scratch_fact_visible, format!("scratch fact should be forgotten even if same-user lessons still surface: {forgotten_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
            "forgotten_run": scratch_run,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

pub async fn record_outcome( &self, options: RecordOutcomeOptions, ) -> Result<Value>

Examples found in repository

examples/helper_mas_learning_loop.rs (line 74)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_mas_learning_loop";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_mas_learning_loop");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper MAS checkpoint/outcome/strategies flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["rule".to_string(), "lesson".to_string(), "fact".to_string()];
        register.write_scopes = vec!["lesson".to_string(), "trace".to_string()];
        register.shared_memory_lanes = vec!["knowledge".to_string(), "history".to_string()];
        client.register_agent(register).await?;

        let mut remember = RememberOptions::new(
            "If a retry succeeds after token signer rotation, record it as a reusable recovery pattern.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("success".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.lesson_importance = Some("high".to_string());
        client.remember(remember).await?;

        let mut checkpoint = CheckpointOptions::new(
            "Planner isolated the recovery path to token signer rotation.",
        );
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction-1".to_string());
        checkpoint.metadata = Some(json!({ "stage": "analysis" }));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents = client.list_agents(list_agents).await?;

        let lessons = client.control.lessons(json!({ "run_id": run_id, "limit": 10 })).await?;
        let lesson_id = lessons
            .get("lessons")
            .and_then(|value| value.as_array())
            .and_then(|items| items.first())
            .and_then(|item| item.get("id"))
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("expected at least one lesson to record outcome against: {lessons}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Recovery succeeded after following the stored lesson.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "failure".to_string()];
        strategies.max_strategies = 5;
        let strategy_response = client.surface_strategies(strategies).await?;

        require(
            checkpoint_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("checkpoint failed: {checkpoint_response}"),
        )?;
        let agent_count = agents
            .get("agents")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);
        require(agent_count == 1, format!("agent registration missing: {agents}"))?;
        require(
            outcome_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("record_outcome failed: {outcome_response}"),
        )?;
        let strategy_count = strategy_response
            .get("strategies")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "checkpoint_id": checkpoint_response.get("checkpoint_id").cloned().unwrap_or(serde_json::Value::Null),
            "agent_count": agent_count,
            "strategy_count": strategy_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/03_checkpoint_reflect_outcome.rs (line 74)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_03_checkpoint_reflect_outcome";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_03_checkpoint_reflect_outcome");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper MAS checkpoint/outcome/strategies flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["rule".to_string(), "lesson".to_string(), "fact".to_string()];
        register.write_scopes = vec!["lesson".to_string(), "trace".to_string()];
        register.shared_memory_lanes = vec!["knowledge".to_string(), "history".to_string()];
        client.register_agent(register).await?;

        let mut remember = RememberOptions::new(
            "If a retry succeeds after token signer rotation, record it as a reusable recovery pattern.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("success".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.lesson_importance = Some("high".to_string());
        client.remember(remember).await?;

        let mut checkpoint = CheckpointOptions::new(
            "Planner isolated the recovery path to token signer rotation.",
        );
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction-1".to_string());
        checkpoint.metadata = Some(json!({ "stage": "analysis" }));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents = client.list_agents(list_agents).await?;

        let lessons = client.control.lessons(json!({ "run_id": run_id, "limit": 10 })).await?;
        let lesson_id = lessons
            .get("lessons")
            .and_then(|value| value.as_array())
            .and_then(|items| items.first())
            .and_then(|item| item.get("id"))
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("expected at least one lesson to record outcome against: {lessons}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Recovery succeeded after following the stored lesson.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "failure".to_string()];
        strategies.max_strategies = 5;
        let strategy_response = client.surface_strategies(strategies).await?;

        require(
            checkpoint_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("checkpoint failed: {checkpoint_response}"),
        )?;
        let agent_count = agents
            .get("agents")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);
        require(agent_count == 1, format!("agent registration missing: {agents}"))?;
        require(
            outcome_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("record_outcome failed: {outcome_response}"),
        )?;
        let strategy_count = strategy_response
            .get("strategies")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "checkpoint_id": checkpoint_response.get("checkpoint_id").cloned().unwrap_or(serde_json::Value::Null),
            "agent_count": agent_count,
            "strategy_count": strategy_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/10_full_learning_loop_smoke.rs (line 143)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_10_full_learning_loop_smoke";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_10_full_learning_loop_smoke");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        remember.occurrence_time = Some(std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() as i64 - 86400);
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut mental_model = RememberOptions::new(
            "Claims case overview: Policy limit 5000 GBP, claimant city Leeds, \
             missing-city branch resolved via stored claim facts. Lesson: check stored facts before escalating.",
        );
        mental_model.run_id = Some(run_id.clone());
        mental_model.agent_id = Some("planner".to_string());
        mental_model.intent = Some("mental_model".to_string());
        mental_model.importance = Some("critical".to_string());
        mental_model.metadata = Some(json!({"suite": "all-helpers", "entity": "claims-case", "consolidated": true}));
        let mental_model_response = client.remember(mental_model).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "mental_model".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(mental_model_response.get("job_id").is_some() || mental_model_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("mental_model remember failed: {mental_model_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/helper_all_helpers.rs (line 131)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_all_helpers";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_all_helpers");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        let scratch_run = format!("{run_id}_forget");
        let mut scratch = RememberOptions::new("Scratch run for forget helper coverage.");
        scratch.run_id = Some(scratch_run.clone());
        scratch.agent_id = Some("planner".to_string());
        scratch.intent = Some("fact".to_string());
        scratch.metadata = Some(json!({"suite": "all-helpers", "temporary": true}));
        let scratch_response = client.remember(scratch).await?;

        let forget_response = client
            .forget(ForgetOptions::for_run(scratch_run.clone()))
            .await?;

        let mut forgotten = RecallOptions::new("What temporary scratch fact exists?");
        forgotten.run_id = Some(scratch_run.clone());
        forgotten.limit = 3;
        let forgotten_response = client.recall(forgotten).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;
        require(scratch_response.get("job_id").is_some() || scratch_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("scratch remember failed: {scratch_response}"))?;
        require(forget_response.get("success").and_then(Value::as_bool).unwrap_or(true), format!("forget failed: {forget_response}"))?;
        let scratch_fact_visible = forgotten_response
            .get("evidence")
            .and_then(Value::as_array)
            .map(|items| {
                items.iter().any(|item| {
                    item.get("run_id").and_then(Value::as_str) == Some(scratch_run.as_str())
                        || item
                            .get("content")
                            .and_then(Value::as_str)
                            .map(|content| {
                                content
                                    .to_ascii_lowercase()
                                    .contains("scratch run for forget helper coverage")
                            })
                            .unwrap_or(false)
                })
            })
            .unwrap_or(false);
        require(!scratch_fact_visible, format!("scratch fact should be forgotten even if same-user lessons still surface: {forgotten_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
            "forgotten_run": scratch_run,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

pub async fn record_step_outcome( &self, options: RecordStepOutcomeOptions, ) -> Result<Value>

pub async fn surface_strategies( &self, options: SurfaceStrategiesOptions, ) -> Result<Value>

Examples found in repository

examples/helper_mas_learning_loop.rs (line 80)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_mas_learning_loop";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_mas_learning_loop");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper MAS checkpoint/outcome/strategies flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["rule".to_string(), "lesson".to_string(), "fact".to_string()];
        register.write_scopes = vec!["lesson".to_string(), "trace".to_string()];
        register.shared_memory_lanes = vec!["knowledge".to_string(), "history".to_string()];
        client.register_agent(register).await?;

        let mut remember = RememberOptions::new(
            "If a retry succeeds after token signer rotation, record it as a reusable recovery pattern.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("success".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.lesson_importance = Some("high".to_string());
        client.remember(remember).await?;

        let mut checkpoint = CheckpointOptions::new(
            "Planner isolated the recovery path to token signer rotation.",
        );
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction-1".to_string());
        checkpoint.metadata = Some(json!({ "stage": "analysis" }));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents = client.list_agents(list_agents).await?;

        let lessons = client.control.lessons(json!({ "run_id": run_id, "limit": 10 })).await?;
        let lesson_id = lessons
            .get("lessons")
            .and_then(|value| value.as_array())
            .and_then(|items| items.first())
            .and_then(|item| item.get("id"))
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("expected at least one lesson to record outcome against: {lessons}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Recovery succeeded after following the stored lesson.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "failure".to_string()];
        strategies.max_strategies = 5;
        let strategy_response = client.surface_strategies(strategies).await?;

        require(
            checkpoint_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("checkpoint failed: {checkpoint_response}"),
        )?;
        let agent_count = agents
            .get("agents")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);
        require(agent_count == 1, format!("agent registration missing: {agents}"))?;
        require(
            outcome_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("record_outcome failed: {outcome_response}"),
        )?;
        let strategy_count = strategy_response
            .get("strategies")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "checkpoint_id": checkpoint_response.get("checkpoint_id").cloned().unwrap_or(serde_json::Value::Null),
            "agent_count": agent_count,
            "strategy_count": strategy_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/03_checkpoint_reflect_outcome.rs (line 80)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_03_checkpoint_reflect_outcome";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_03_checkpoint_reflect_outcome");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper MAS checkpoint/outcome/strategies flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["rule".to_string(), "lesson".to_string(), "fact".to_string()];
        register.write_scopes = vec!["lesson".to_string(), "trace".to_string()];
        register.shared_memory_lanes = vec!["knowledge".to_string(), "history".to_string()];
        client.register_agent(register).await?;

        let mut remember = RememberOptions::new(
            "If a retry succeeds after token signer rotation, record it as a reusable recovery pattern.",
        );
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("lesson".to_string());
        remember.lesson_type = Some("success".to_string());
        remember.lesson_scope = Some("session".to_string());
        remember.lesson_importance = Some("high".to_string());
        client.remember(remember).await?;

        let mut checkpoint = CheckpointOptions::new(
            "Planner isolated the recovery path to token signer rotation.",
        );
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction-1".to_string());
        checkpoint.metadata = Some(json!({ "stage": "analysis" }));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents = client.list_agents(list_agents).await?;

        let lessons = client.control.lessons(json!({ "run_id": run_id, "limit": 10 })).await?;
        let lesson_id = lessons
            .get("lessons")
            .and_then(|value| value.as_array())
            .and_then(|items| items.first())
            .and_then(|item| item.get("id"))
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("expected at least one lesson to record outcome against: {lessons}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Recovery succeeded after following the stored lesson.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "failure".to_string()];
        strategies.max_strategies = 5;
        let strategy_response = client.surface_strategies(strategies).await?;

        require(
            checkpoint_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("checkpoint failed: {checkpoint_response}"),
        )?;
        let agent_count = agents
            .get("agents")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);
        require(agent_count == 1, format!("agent registration missing: {agents}"))?;
        require(
            outcome_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("record_outcome failed: {outcome_response}"),
        )?;
        let strategy_count = strategy_response
            .get("strategies")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "checkpoint_id": checkpoint_response.get("checkpoint_id").cloned().unwrap_or(serde_json::Value::Null),
            "agent_count": agent_count,
            "strategy_count": strategy_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/10_full_learning_loop_smoke.rs (line 149)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_10_full_learning_loop_smoke";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_10_full_learning_loop_smoke");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        remember.occurrence_time = Some(std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() as i64 - 86400);
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut mental_model = RememberOptions::new(
            "Claims case overview: Policy limit 5000 GBP, claimant city Leeds, \
             missing-city branch resolved via stored claim facts. Lesson: check stored facts before escalating.",
        );
        mental_model.run_id = Some(run_id.clone());
        mental_model.agent_id = Some("planner".to_string());
        mental_model.intent = Some("mental_model".to_string());
        mental_model.importance = Some("critical".to_string());
        mental_model.metadata = Some(json!({"suite": "all-helpers", "entity": "claims-case", "consolidated": true}));
        let mental_model_response = client.remember(mental_model).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "mental_model".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(mental_model_response.get("job_id").is_some() || mental_model_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("mental_model remember failed: {mental_model_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/helper_all_helpers.rs (line 137)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_all_helpers";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_all_helpers");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        let scratch_run = format!("{run_id}_forget");
        let mut scratch = RememberOptions::new("Scratch run for forget helper coverage.");
        scratch.run_id = Some(scratch_run.clone());
        scratch.agent_id = Some("planner".to_string());
        scratch.intent = Some("fact".to_string());
        scratch.metadata = Some(json!({"suite": "all-helpers", "temporary": true}));
        let scratch_response = client.remember(scratch).await?;

        let forget_response = client
            .forget(ForgetOptions::for_run(scratch_run.clone()))
            .await?;

        let mut forgotten = RecallOptions::new("What temporary scratch fact exists?");
        forgotten.run_id = Some(scratch_run.clone());
        forgotten.limit = 3;
        let forgotten_response = client.recall(forgotten).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;
        require(scratch_response.get("job_id").is_some() || scratch_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("scratch remember failed: {scratch_response}"))?;
        require(forget_response.get("success").and_then(Value::as_bool).unwrap_or(true), format!("forget failed: {forget_response}"))?;
        let scratch_fact_visible = forgotten_response
            .get("evidence")
            .and_then(Value::as_array)
            .map(|items| {
                items.iter().any(|item| {
                    item.get("run_id").and_then(Value::as_str) == Some(scratch_run.as_str())
                        || item
                            .get("content")
                            .and_then(Value::as_str)
                            .map(|content| {
                                content
                                    .to_ascii_lowercase()
                                    .contains("scratch run for forget helper coverage")
                            })
                            .unwrap_or(false)
                })
            })
            .unwrap_or(false);
        require(!scratch_fact_visible, format!("scratch fact should be forgotten even if same-user lessons still surface: {forgotten_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
            "forgotten_run": scratch_run,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

pub async fn handoff(&self, options: HandoffOptions) -> Result<Value>

Examples found in repository

examples/helper_handoff_feedback.rs (line 45)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_handoff_feedback";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_handoff_feedback");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper handoff + feedback flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut planner = RegisterAgentOptions::new("planner");
        planner.run_id = Some(run_id.clone());
        planner.role = "planner".to_string();
        client.register_agent(planner).await?;

        let mut reviewer = RegisterAgentOptions::new("reviewer");
        reviewer.run_id = Some(run_id.clone());
        reviewer.role = "reviewer".to_string();
        client.register_agent(reviewer).await?;

        let mut handoff = HandoffOptions::new(
            "task-1",
            "planner",
            "reviewer",
            "Review the retry policy patch before rollout.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({ "source": "rust-helper-example" }));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Patch looks safe for rollout.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({ "source": "rust-helper-example" }));
        let feedback_response = client.feedback(feedback).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("What coordination artifacts were recorded for this review handoff?".to_string());
        context.mode = Some("sections".to_string());
        context.sections = vec!["handoffs".to_string(), "feedback".to_string()];
        let context_response = client.get_context(context).await?;

        require(
            handoff_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("handoff failed: {handoff_response}"),
        )?;
        require(
            feedback_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("feedback failed: {feedback_response}"),
        )?;
        let section_count = context_response
            .get("section_summaries")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "handoff_id": handoff_id,
            "feedback_id": feedback_response.get("feedback_id").cloned().unwrap_or(serde_json::Value::Null),
            "section_count": section_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/06_handoff_feedback.rs (line 45)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_06_handoff_feedback";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_06_handoff_feedback");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper handoff + feedback flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut planner = RegisterAgentOptions::new("planner");
        planner.run_id = Some(run_id.clone());
        planner.role = "planner".to_string();
        client.register_agent(planner).await?;

        let mut reviewer = RegisterAgentOptions::new("reviewer");
        reviewer.run_id = Some(run_id.clone());
        reviewer.role = "reviewer".to_string();
        client.register_agent(reviewer).await?;

        let mut handoff = HandoffOptions::new(
            "task-1",
            "planner",
            "reviewer",
            "Review the retry policy patch before rollout.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({ "source": "rust-helper-example" }));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Patch looks safe for rollout.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({ "source": "rust-helper-example" }));
        let feedback_response = client.feedback(feedback).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("What coordination artifacts were recorded for this review handoff?".to_string());
        context.mode = Some("sections".to_string());
        context.sections = vec!["handoffs".to_string(), "feedback".to_string()];
        let context_response = client.get_context(context).await?;

        require(
            handoff_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("handoff failed: {handoff_response}"),
        )?;
        require(
            feedback_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("feedback failed: {feedback_response}"),
        )?;
        let section_count = context_response
            .get("section_summaries")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "handoff_id": handoff_id,
            "feedback_id": feedback_response.get("feedback_id").cloned().unwrap_or(serde_json::Value::Null),
            "section_count": section_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/08_multi_agent_claims_or_support_flow.rs (line 67)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_08_multi_agent_claims_or_support_flow";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_claims_flow");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated multi-agent claims/support flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        for (agent_id, role, read_scopes, write_scopes) in [
            ("intake", "intake", vec!["fact", "archive_block"], vec!["fact", "archive_block", "trace"]),
            ("coverage", "coverage", vec!["fact", "rule", "archive_block", "handoff", "feedback"], vec!["fact", "trace", "lesson"]),
            ("reviewer", "reviewer", vec!["fact", "archive_block", "handoff", "feedback", "rule"], vec!["feedback", "rule"]),
        ] {
            let mut agent = RegisterAgentOptions::new(agent_id);
            agent.run_id = Some(run_id.clone());
            agent.role = role.to_string();
            agent.read_scopes = read_scopes.into_iter().map(String::from).collect();
            agent.write_scopes = write_scopes.into_iter().map(String::from).collect();
            agent.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
            client.register_agent(agent).await?;
        }

        let mut fact = RememberOptions::new("Policy P-8842 covers windshield damage with a 250 GBP deductible.");
        fact.run_id = Some(run_id.clone());
        fact.agent_id = Some("intake".into());
        fact.intent = Some("fact".into());
        fact.metadata = Some(json!({"claim_id": "CLM-8842", "source": "intake-form"}));
        client.remember(fact).await?;

        let mut archive = ArchiveOptions::new("Exact adjuster note: customer confirmed the damage happened on the motorway and no third party was involved.", "adjuster_note");
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("intake".into());
        archive.origin_agent_id = Some("intake".into());
        archive.source_attempt_id = Some("attempt-1".into());
        archive.source_tool = Some("claim-review".into());
        archive.labels = vec!["claims".into(), "coverage".into()];
        archive.family = Some("windshield".into());
        let archived = client.archive(archive).await?;
        let reference_id = archived.get("reference_id").and_then(|v| v.as_str()).ok_or_else(|| boxed_error(format!("archive reference missing: {archived}")))?.to_string();

        let mut checkpoint = CheckpointOptions::new("Coverage verified deductible and adjuster note before escalation.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-review".into());
        checkpoint.agent_id = Some("coverage".into());
        checkpoint.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let mut handoff = HandoffOptions::new("claim-8842", "coverage", "reviewer", "Review whether the adjuster note is enough to approve the claim.");
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".into();
        handoff.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response.get("handoff_id").and_then(|v| v.as_str()).ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?.to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.from_agent_id = Some("reviewer".into());
        feedback.comments = "Deductible and adjuster note are sufficient for routing.".into();
        feedback.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let feedback_response = client.feedback(feedback).await?;

        let mut context_opts = GetContextOptions::default();
        context_opts.run_id = Some(run_id.clone());
        context_opts.query = Some("Prepare the final claims routing summary.".into());
        context_opts.agent_id = Some("coverage".into());
        context_opts.sections = vec!["archive".into(), "facts".into(), "handoffs".into(), "feedback".into()];
        context_opts.mode = Some("sections".into());
        let context = client.get_context(context_opts).await?;

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("coverage".into());
        let exact = client.dereference(dereference).await?;

        let mut recall = RecallOptions::new("What deductible applies and what did the adjuster confirm?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("coverage".into());
        recall.entry_types = vec!["fact".into(), "archive_block".into(), "feedback".into()];
        let recall_response = client.recall(recall).await?;

        require(checkpoint_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(handoff_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;
        require(exact.get("found").and_then(|v| v.as_bool()).unwrap_or(false), format!("dereference failed: {exact}"))?;
        let context_text = context.get("context_block").and_then(|v| v.as_str()).unwrap_or("").to_lowercase();
        let recall_text = recall_response.get("final_answer").and_then(|v| v.as_str()).unwrap_or("").to_lowercase();
        let has_archive_source = context
            .get("sources")
            .and_then(|v| v.as_array())
            .map(|sources| {
                sources.iter().any(|source| {
                    source
                        .get("entry_type")
                        .and_then(|v| v.as_str())
                        == Some("archive_block")
                })
            })
            .unwrap_or(false);
        let exact_refs_surfaced = context
            .get("exact_references_surfaced")
            .and_then(|v| v.as_u64())
            .unwrap_or(0);
        require(
            context_text.contains("adjuster note")
                || context_text.contains("motorway")
                || has_archive_source
                || exact_refs_surfaced > 0,
            format!("expected explicit or telemetry-backed exact reuse in context: {context}"),
        )?;
        require(recall_text.contains("250") && (recall_text.contains("motorway") || recall_text.contains("third party")), format!("expected recall to include fact + archive content: {recall_response}"))?;

        metrics = json!({
            "run_id": run_id,
            "handoff_id": handoff_id,
            "reference_id": reference_id,
            "feedback_id": feedback_response.get("feedback_id").cloned().unwrap_or(serde_json::Value::Null),
        });
        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);
    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/public/10_full_learning_loop_smoke.rs (line 160)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_10_full_learning_loop_smoke";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_10_full_learning_loop_smoke");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        remember.occurrence_time = Some(std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() as i64 - 86400);
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut mental_model = RememberOptions::new(
            "Claims case overview: Policy limit 5000 GBP, claimant city Leeds, \
             missing-city branch resolved via stored claim facts. Lesson: check stored facts before escalating.",
        );
        mental_model.run_id = Some(run_id.clone());
        mental_model.agent_id = Some("planner".to_string());
        mental_model.intent = Some("mental_model".to_string());
        mental_model.importance = Some("critical".to_string());
        mental_model.metadata = Some(json!({"suite": "all-helpers", "entity": "claims-case", "consolidated": true}));
        let mental_model_response = client.remember(mental_model).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "mental_model".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(mental_model_response.get("job_id").is_some() || mental_model_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("mental_model remember failed: {mental_model_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/helper_all_helpers.rs (line 148)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_all_helpers";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_all_helpers");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        let scratch_run = format!("{run_id}_forget");
        let mut scratch = RememberOptions::new("Scratch run for forget helper coverage.");
        scratch.run_id = Some(scratch_run.clone());
        scratch.agent_id = Some("planner".to_string());
        scratch.intent = Some("fact".to_string());
        scratch.metadata = Some(json!({"suite": "all-helpers", "temporary": true}));
        let scratch_response = client.remember(scratch).await?;

        let forget_response = client
            .forget(ForgetOptions::for_run(scratch_run.clone()))
            .await?;

        let mut forgotten = RecallOptions::new("What temporary scratch fact exists?");
        forgotten.run_id = Some(scratch_run.clone());
        forgotten.limit = 3;
        let forgotten_response = client.recall(forgotten).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;
        require(scratch_response.get("job_id").is_some() || scratch_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("scratch remember failed: {scratch_response}"))?;
        require(forget_response.get("success").and_then(Value::as_bool).unwrap_or(true), format!("forget failed: {forget_response}"))?;
        let scratch_fact_visible = forgotten_response
            .get("evidence")
            .and_then(Value::as_array)
            .map(|items| {
                items.iter().any(|item| {
                    item.get("run_id").and_then(Value::as_str) == Some(scratch_run.as_str())
                        || item
                            .get("content")
                            .and_then(Value::as_str)
                            .map(|content| {
                                content
                                    .to_ascii_lowercase()
                                    .contains("scratch run for forget helper coverage")
                            })
                            .unwrap_or(false)
                })
            })
            .unwrap_or(false);
        require(!scratch_fact_visible, format!("scratch fact should be forgotten even if same-user lessons still surface: {forgotten_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
            "forgotten_run": scratch_run,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

pub async fn feedback(&self, options: FeedbackOptions) -> Result<Value>

Examples found in repository

examples/helper_handoff_feedback.rs (line 57)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_handoff_feedback";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_handoff_feedback");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper handoff + feedback flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut planner = RegisterAgentOptions::new("planner");
        planner.run_id = Some(run_id.clone());
        planner.role = "planner".to_string();
        client.register_agent(planner).await?;

        let mut reviewer = RegisterAgentOptions::new("reviewer");
        reviewer.run_id = Some(run_id.clone());
        reviewer.role = "reviewer".to_string();
        client.register_agent(reviewer).await?;

        let mut handoff = HandoffOptions::new(
            "task-1",
            "planner",
            "reviewer",
            "Review the retry policy patch before rollout.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({ "source": "rust-helper-example" }));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Patch looks safe for rollout.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({ "source": "rust-helper-example" }));
        let feedback_response = client.feedback(feedback).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("What coordination artifacts were recorded for this review handoff?".to_string());
        context.mode = Some("sections".to_string());
        context.sections = vec!["handoffs".to_string(), "feedback".to_string()];
        let context_response = client.get_context(context).await?;

        require(
            handoff_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("handoff failed: {handoff_response}"),
        )?;
        require(
            feedback_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("feedback failed: {feedback_response}"),
        )?;
        let section_count = context_response
            .get("section_summaries")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "handoff_id": handoff_id,
            "feedback_id": feedback_response.get("feedback_id").cloned().unwrap_or(serde_json::Value::Null),
            "section_count": section_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/06_handoff_feedback.rs (line 57)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_06_handoff_feedback";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_06_handoff_feedback");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated helper handoff + feedback flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut planner = RegisterAgentOptions::new("planner");
        planner.run_id = Some(run_id.clone());
        planner.role = "planner".to_string();
        client.register_agent(planner).await?;

        let mut reviewer = RegisterAgentOptions::new("reviewer");
        reviewer.run_id = Some(run_id.clone());
        reviewer.role = "reviewer".to_string();
        client.register_agent(reviewer).await?;

        let mut handoff = HandoffOptions::new(
            "task-1",
            "planner",
            "reviewer",
            "Review the retry policy patch before rollout.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({ "source": "rust-helper-example" }));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(|value| value.as_str())
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Patch looks safe for rollout.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({ "source": "rust-helper-example" }));
        let feedback_response = client.feedback(feedback).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("What coordination artifacts were recorded for this review handoff?".to_string());
        context.mode = Some("sections".to_string());
        context.sections = vec!["handoffs".to_string(), "feedback".to_string()];
        let context_response = client.get_context(context).await?;

        require(
            handoff_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("handoff failed: {handoff_response}"),
        )?;
        require(
            feedback_response
                .get("success")
                .and_then(|value| value.as_bool())
                .unwrap_or(false),
            format!("feedback failed: {feedback_response}"),
        )?;
        let section_count = context_response
            .get("section_summaries")
            .and_then(|value| value.as_array())
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "handoff_id": handoff_id,
            "feedback_id": feedback_response.get("feedback_id").cloned().unwrap_or(serde_json::Value::Null),
            "section_count": section_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(
        name,
        passed,
        &detail,
        &metrics,
        started.elapsed().as_secs_f64(),
        cleanup_ok,
    );

    if passed {
        Ok(())
    } else {
        Err(boxed_error(detail))
    }
}

examples/public/08_multi_agent_claims_or_support_flow.rs (line 75)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_08_multi_agent_claims_or_support_flow";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_claims_flow");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated multi-agent claims/support flow".to_string();
    let mut metrics = json!({});

    let scenario = async {
        for (agent_id, role, read_scopes, write_scopes) in [
            ("intake", "intake", vec!["fact", "archive_block"], vec!["fact", "archive_block", "trace"]),
            ("coverage", "coverage", vec!["fact", "rule", "archive_block", "handoff", "feedback"], vec!["fact", "trace", "lesson"]),
            ("reviewer", "reviewer", vec!["fact", "archive_block", "handoff", "feedback", "rule"], vec!["feedback", "rule"]),
        ] {
            let mut agent = RegisterAgentOptions::new(agent_id);
            agent.run_id = Some(run_id.clone());
            agent.role = role.to_string();
            agent.read_scopes = read_scopes.into_iter().map(String::from).collect();
            agent.write_scopes = write_scopes.into_iter().map(String::from).collect();
            agent.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
            client.register_agent(agent).await?;
        }

        let mut fact = RememberOptions::new("Policy P-8842 covers windshield damage with a 250 GBP deductible.");
        fact.run_id = Some(run_id.clone());
        fact.agent_id = Some("intake".into());
        fact.intent = Some("fact".into());
        fact.metadata = Some(json!({"claim_id": "CLM-8842", "source": "intake-form"}));
        client.remember(fact).await?;

        let mut archive = ArchiveOptions::new("Exact adjuster note: customer confirmed the damage happened on the motorway and no third party was involved.", "adjuster_note");
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("intake".into());
        archive.origin_agent_id = Some("intake".into());
        archive.source_attempt_id = Some("attempt-1".into());
        archive.source_tool = Some("claim-review".into());
        archive.labels = vec!["claims".into(), "coverage".into()];
        archive.family = Some("windshield".into());
        let archived = client.archive(archive).await?;
        let reference_id = archived.get("reference_id").and_then(|v| v.as_str()).ok_or_else(|| boxed_error(format!("archive reference missing: {archived}")))?.to_string();

        let mut checkpoint = CheckpointOptions::new("Coverage verified deductible and adjuster note before escalation.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-review".into());
        checkpoint.agent_id = Some("coverage".into());
        checkpoint.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let mut handoff = HandoffOptions::new("claim-8842", "coverage", "reviewer", "Review whether the adjuster note is enough to approve the claim.");
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".into();
        handoff.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response.get("handoff_id").and_then(|v| v.as_str()).ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?.to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.from_agent_id = Some("reviewer".into());
        feedback.comments = "Deductible and adjuster note are sufficient for routing.".into();
        feedback.metadata = Some(json!({"claim_id": "CLM-8842"}));
        let feedback_response = client.feedback(feedback).await?;

        let mut context_opts = GetContextOptions::default();
        context_opts.run_id = Some(run_id.clone());
        context_opts.query = Some("Prepare the final claims routing summary.".into());
        context_opts.agent_id = Some("coverage".into());
        context_opts.sections = vec!["archive".into(), "facts".into(), "handoffs".into(), "feedback".into()];
        context_opts.mode = Some("sections".into());
        let context = client.get_context(context_opts).await?;

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("coverage".into());
        let exact = client.dereference(dereference).await?;

        let mut recall = RecallOptions::new("What deductible applies and what did the adjuster confirm?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("coverage".into());
        recall.entry_types = vec!["fact".into(), "archive_block".into(), "feedback".into()];
        let recall_response = client.recall(recall).await?;

        require(checkpoint_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(handoff_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(|v| v.as_bool()).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;
        require(exact.get("found").and_then(|v| v.as_bool()).unwrap_or(false), format!("dereference failed: {exact}"))?;
        let context_text = context.get("context_block").and_then(|v| v.as_str()).unwrap_or("").to_lowercase();
        let recall_text = recall_response.get("final_answer").and_then(|v| v.as_str()).unwrap_or("").to_lowercase();
        let has_archive_source = context
            .get("sources")
            .and_then(|v| v.as_array())
            .map(|sources| {
                sources.iter().any(|source| {
                    source
                        .get("entry_type")
                        .and_then(|v| v.as_str())
                        == Some("archive_block")
                })
            })
            .unwrap_or(false);
        let exact_refs_surfaced = context
            .get("exact_references_surfaced")
            .and_then(|v| v.as_u64())
            .unwrap_or(0);
        require(
            context_text.contains("adjuster note")
                || context_text.contains("motorway")
                || has_archive_source
                || exact_refs_surfaced > 0,
            format!("expected explicit or telemetry-backed exact reuse in context: {context}"),
        )?;
        require(recall_text.contains("250") && (recall_text.contains("motorway") || recall_text.contains("third party")), format!("expected recall to include fact + archive content: {recall_response}"))?;

        metrics = json!({
            "run_id": run_id,
            "handoff_id": handoff_id,
            "reference_id": reference_id,
            "feedback_id": feedback_response.get("feedback_id").cloned().unwrap_or(serde_json::Value::Null),
        });
        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);
    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/public/10_full_learning_loop_smoke.rs (line 172)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "public_10_full_learning_loop_smoke";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("public_10_full_learning_loop_smoke");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        remember.occurrence_time = Some(std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() as i64 - 86400);
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut mental_model = RememberOptions::new(
            "Claims case overview: Policy limit 5000 GBP, claimant city Leeds, \
             missing-city branch resolved via stored claim facts. Lesson: check stored facts before escalating.",
        );
        mental_model.run_id = Some(run_id.clone());
        mental_model.agent_id = Some("planner".to_string());
        mental_model.intent = Some("mental_model".to_string());
        mental_model.importance = Some("critical".to_string());
        mental_model.metadata = Some(json!({"suite": "all-helpers", "entity": "claims-case", "consolidated": true}));
        let mental_model_response = client.remember(mental_model).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "mental_model".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(mental_model_response.get("job_id").is_some() || mental_model_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("mental_model remember failed: {mental_model_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

examples/helper_all_helpers.rs (line 160)

async fn main() -> Result<(), Box<dyn Error>> {
    let name = "helper_all_helpers";
    let started = Instant::now();
    let client = create_client().await?;
    let run_id = new_run_id("helper_all_helpers");
    client.set_run_id(Some(run_id.clone()));
    client.set_transport(TransportMode::Http);

    let mut passed = true;
    let mut detail = "validated all helper flows".to_string();
    let mut metrics = json!({});

    let scenario = async {
        let mut remember = RememberOptions::new("Policy limit is 5000 and claimant city is Leeds.");
        remember.run_id = Some(run_id.clone());
        remember.agent_id = Some("planner".to_string());
        remember.intent = Some("fact".to_string());
        remember.metadata = Some(json!({"suite": "all-helpers", "family": "claims"}));
        remember.importance = Some("high".to_string());
        let remember_response = client.remember(remember).await?;

        let mut lesson = RememberOptions::new("If city is missing from the latest step, check stored claim facts before escalating.");
        lesson.run_id = Some(run_id.clone());
        lesson.agent_id = Some("planner".to_string());
        lesson.intent = Some("lesson".to_string());
        lesson.lesson_type = Some("success".to_string());
        lesson.lesson_scope = Some("session".to_string());
        lesson.lesson_importance = Some("high".to_string());
        let lesson_response = client.remember(lesson).await?;

        let mut recall = RecallOptions::new("What is the policy limit?");
        recall.run_id = Some(run_id.clone());
        recall.agent_id = Some("planner".to_string());
        recall.limit = 5;
        let recall_response = client.recall(recall).await?;

        let mut context = GetContextOptions::default();
        context.run_id = Some(run_id.clone());
        context.query = Some("Prepare a short adjuster summary".to_string());
        context.agent_id = Some("planner".to_string());
        context.limit = Some(6);
        context.max_token_budget = Some(700);
        let context_response = client.get_context(context).await?;

        let mut health = MemoryHealthOptions::default();
        health.run_id = Some(run_id.clone());
        health.limit = 50;
        let health_response = client.memory_health(health).await?;

        let mut diagnose = DiagnoseOptions::new("policy limit lookup returned empty");
        diagnose.run_id = Some(run_id.clone());
        diagnose.error_type = Some("retrieval".to_string());
        diagnose.limit = 5;
        let diagnose_response = client.diagnose(diagnose).await?;

        let mut reflect = ReflectOptions::default();
        reflect.run_id = Some(run_id.clone());
        let reflect_response = client.reflect(reflect).await?;

        let mut register = RegisterAgentOptions::new("planner");
        register.run_id = Some(run_id.clone());
        register.role = "planner".to_string();
        register.read_scopes = vec!["fact".into(), "lesson".into(), "rule".into(), "archive_block".into(), "handoff".into(), "feedback".into()];
        register.write_scopes = vec!["fact".into(), "trace".into(), "lesson".into(), "observation".into(), "archive_block".into()];
        register.shared_memory_lanes = vec!["knowledge".into(), "history".into()];
        let register_response = client.register_agent(register).await?;

        let mut list_agents = ListAgentsOptions::default();
        list_agents.run_id = Some(run_id.clone());
        let agents_response = client.list_agents(list_agents).await?;

        let mut archive = ArchiveOptions::new(
            "Exact adjuster note: claimant confirmed city is Leeds during triage.",
            "adjuster_note",
        );
        archive.run_id = Some(run_id.clone());
        archive.agent_id = Some("planner".to_string());
        archive.origin_agent_id = Some("planner".to_string());
        archive.source_attempt_id = Some("attempt-1".to_string());
        archive.source_tool = Some("phone_call".to_string());
        archive.labels = vec!["claims".to_string(), "triage".to_string()];
        archive.family = Some("claims-adjustment".to_string());
        archive.metadata = Some(json!({"case": "all-helpers"}));
        let archive_response = client.archive(archive).await?;
        let reference_id = archive_response
            .get("reference_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("archive reference missing: {archive_response}")))?
            .to_string();

        let mut dereference = DereferenceOptions::new(reference_id.clone());
        dereference.run_id = Some(run_id.clone());
        dereference.agent_id = Some("planner".to_string());
        let dereference_response = client.dereference(dereference).await?;

        let mut checkpoint = CheckpointOptions::new("Planner captured claim facts before window compaction.");
        checkpoint.run_id = Some(run_id.clone());
        checkpoint.label = Some("pre-compaction".to_string());
        checkpoint.metadata = Some(json!({"stage": "analysis"}));
        checkpoint.agent_id = Some("planner".to_string());
        let checkpoint_response = client.checkpoint(checkpoint).await?;

        let lessons_response = client.control.lessons(json!({"run_id": run_id, "limit": 20})).await?;
        let lesson_id = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .and_then(|items| items.iter().find_map(|item| item.get("id").and_then(Value::as_str)))
            .ok_or_else(|| boxed_error(format!("expected lesson id for outcome flow: {lessons_response}")))?
            .to_string();

        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
        outcome.run_id = Some(run_id.clone());
        outcome.signal = 0.75;
        outcome.rationale = "Planner reused stored claim fact and resolved the missing-city branch.".to_string();
        outcome.agent_id = Some("planner".to_string());
        let outcome_response = client.record_outcome(outcome).await?;

        let mut strategies = SurfaceStrategiesOptions::default();
        strategies.run_id = Some(run_id.clone());
        strategies.lesson_types = vec!["success".to_string(), "rule".to_string()];
        strategies.max_strategies = 5;
        let strategies_response = client.surface_strategies(strategies).await?;

        let mut handoff = HandoffOptions::new(
            "claim-1",
            "planner",
            "reviewer",
            "Review whether the stored claimant city is sufficient for routing.",
        );
        handoff.run_id = Some(run_id.clone());
        handoff.requested_action = "review".to_string();
        handoff.metadata = Some(json!({"team": "claims"}));
        let handoff_response = client.handoff(handoff).await?;
        let handoff_id = handoff_response
            .get("handoff_id")
            .and_then(Value::as_str)
            .ok_or_else(|| boxed_error(format!("handoff id missing: {handoff_response}")))?
            .to_string();

        let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
        feedback.run_id = Some(run_id.clone());
        feedback.comments = "Stored fact is sufficient; proceed without escalation.".to_string();
        feedback.from_agent_id = Some("reviewer".to_string());
        feedback.metadata = Some(json!({"team": "claims"}));
        let feedback_response = client.feedback(feedback).await?;

        let scratch_run = format!("{run_id}_forget");
        let mut scratch = RememberOptions::new("Scratch run for forget helper coverage.");
        scratch.run_id = Some(scratch_run.clone());
        scratch.agent_id = Some("planner".to_string());
        scratch.intent = Some("fact".to_string());
        scratch.metadata = Some(json!({"suite": "all-helpers", "temporary": true}));
        let scratch_response = client.remember(scratch).await?;

        let forget_response = client
            .forget(ForgetOptions::for_run(scratch_run.clone()))
            .await?;

        let mut forgotten = RecallOptions::new("What temporary scratch fact exists?");
        forgotten.run_id = Some(scratch_run.clone());
        forgotten.limit = 3;
        let forgotten_response = client.recall(forgotten).await?;

        require(remember_response.get("job_id").is_some() || remember_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("remember failed: {remember_response}"))?;
        require(lesson_response.get("job_id").is_some() || lesson_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("lesson remember failed: {lesson_response}"))?;
        require(recall_response.get("final_answer").is_some() || recall_response.get("evidence").is_some(), format!("recall failed: {recall_response}"))?;
        require(context_response.get("sources").and_then(Value::as_array).is_some(), format!("context malformed: {context_response}"))?;
        require(health_response.get("entry_counts").and_then(Value::as_object).is_some(), format!("memory_health malformed: {health_response}"))?;
        require(diagnose_response.get("failure_lessons").and_then(Value::as_array).is_some(), format!("diagnose malformed: {diagnose_response}"))?;
        require(reflect_response.get("lessons").and_then(Value::as_array).is_some(), format!("reflect malformed: {reflect_response}"))?;
        require(register_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("register_agent failed: {register_response}"))?;
        require(agents_response.get("agents").and_then(Value::as_array).map(|items| !items.is_empty()).unwrap_or(false), format!("list_agents failed: {agents_response}"))?;
        require(archive_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("archive failed: {archive_response}"))?;
        require(dereference_response.get("found").and_then(Value::as_bool).unwrap_or(false), format!("dereference failed: {dereference_response}"))?;
        require(checkpoint_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("checkpoint failed: {checkpoint_response}"))?;
        require(outcome_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("record_outcome failed: {outcome_response}"))?;
        require(strategies_response.get("strategies").and_then(Value::as_array).is_some(), format!("surface_strategies malformed: {strategies_response}"))?;
        require(handoff_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("handoff failed: {handoff_response}"))?;
        require(feedback_response.get("success").and_then(Value::as_bool).unwrap_or(false), format!("feedback failed: {feedback_response}"))?;
        require(scratch_response.get("job_id").is_some() || scratch_response.get("accepted").and_then(Value::as_bool).unwrap_or(false), format!("scratch remember failed: {scratch_response}"))?;
        require(forget_response.get("success").and_then(Value::as_bool).unwrap_or(true), format!("forget failed: {forget_response}"))?;
        let scratch_fact_visible = forgotten_response
            .get("evidence")
            .and_then(Value::as_array)
            .map(|items| {
                items.iter().any(|item| {
                    item.get("run_id").and_then(Value::as_str) == Some(scratch_run.as_str())
                        || item
                            .get("content")
                            .and_then(Value::as_str)
                            .map(|content| {
                                content
                                    .to_ascii_lowercase()
                                    .contains("scratch run for forget helper coverage")
                            })
                            .unwrap_or(false)
                })
            })
            .unwrap_or(false);
        require(!scratch_fact_visible, format!("scratch fact should be forgotten even if same-user lessons still surface: {forgotten_response}"))?;

        let strategy_count = strategies_response
            .get("strategies")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let agent_count = agents_response
            .get("agents")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);
        let lesson_count = lessons_response
            .get("lessons")
            .and_then(Value::as_array)
            .map(|items| items.len())
            .unwrap_or(0);

        metrics = json!({
            "run_id": run_id,
            "agent_count": agent_count,
            "strategy_count": strategy_count,
            "reference_id": reference_id,
            "lesson_count": lesson_count,
            "forgotten_run": scratch_run,
        });

        Ok::<(), Box<dyn Error>>(())
    }
    .await;

    if let Err(err) = scenario {
        passed = false;
        detail = err.to_string();
    }

    let cleanup_ok = cleanup_run(&client, &run_id).await;
    if !cleanup_ok {
        passed = false;
        detail = format!("{detail} | cleanup failures");
    }

    print_summary(name, passed, &detail, &metrics, started.elapsed().as_secs_f64(), cleanup_ok);

    if passed { Ok(()) } else { Err(boxed_error(detail)) }
}

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.