Module api 

Beans Library API

Programmatic access to beans operations. Use this module when embedding beans in another application (e.g., a GUI, MCP server, or custom tooling).

The API is organized into layers:

• Types — Core data structures (Bean, Index, Status, etc.)
• Discovery — Find .beans/ directories and bean files
• Query — Read-only operations (list, get, tree, status, graph)
• Mutations — Write operations (create, update, close, delete)
• Orchestration — Agent dispatch, monitoring, and control

Quick Start

use bn::api::*;

// Find the .beans/ directory
let beans_dir = find_beans_dir(std::path::Path::new(".")).unwrap();

// Load the index (cached, rebuilds if stale)
let index = Index::load_or_rebuild(&beans_dir).unwrap();

// Get a specific bean
let bean = get_bean(&beans_dir, "1").unwrap();
println!("{}: {}", bean.id, bean.title);

Design Principles

• No I/O side effects — Library functions never print to stdout/stderr. All output is returned as structured data.
• Structured params and results — Each operation takes a Params struct and returns a Result type. No raw CLI argument passing.
• Serializable — All types derive Serialize/Deserialize for easy IPC (Tauri, JSON-RPC, MCP).
• Composable — Functions take &Path (beans_dir) and return owned data. No global state, no singletons.

Re-exports

pub use crate::bean::AttemptOutcome;

pub use crate::bean::AttemptRecord;

pub use crate::bean::Bean;

pub use crate::bean::OnCloseAction;

pub use crate::bean::OnFailAction;

pub use crate::bean::RunRecord;

pub use crate::bean::RunResult;

pub use crate::bean::Status;

pub use crate::index::Index;

pub use crate::index::IndexEntry;

pub use crate::config::Config;

pub use crate::discovery::archive_path_for_bean;

pub use crate::discovery::find_archived_bean;

pub use crate::discovery::find_bean_file;

pub use crate::discovery::find_beans_dir;

pub use crate::graph::build_dependency_tree;

pub use crate::graph::build_full_graph;

pub use crate::graph::count_subtree_attempts;

pub use crate::graph::detect_cycle;

pub use crate::graph::find_all_cycles;

pub use crate::bean::validate_priority;

Functions

get_archived_bean

Load a bean from the archive by ID.

get_bean

Load a bean by ID.

load_index

Load the index, rebuilding from bean files if stale.