The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
//! `openhuman agent` — developer CLI for inspecting agent definitions and
//! the system prompts the context engine produces for them.
//!
//! This is intentionally scoped to *debugging*: no execution, no provider
//! calls, no server boot. Every subcommand boils down to reading config /
//! agent definitions / tool registry and printing something.
//!
//! Usage:
//! openhuman agent dump-prompt --agent <id> [--workspace <path>] [--json] [--with-tools] [--wire] [-v]
//! openhuman agent dump-all --out <dir> [--workspace <path>] [--model <name>] [-v]
//! openhuman agent prompt-size [--agent <id>] [--workspace <path>] [--json] [-v]
//! openhuman agent list [--json] [-v]
//!
//! `dump-prompt` is the main tool: it renders the current-turn system prompt
//! through the same prelude builder the runtime uses for a cold model request.
//! Pass
//! `--agent orchestrator` for the orchestrator prompt; otherwise pass
//! any built-in or workspace-custom agent id (e.g. `orchestrator`, `researcher`).
use anyhow::{anyhow, Result};
use std::path::PathBuf;
use crate::agent_registry::host_definition::AgentDefinitionRegistry;
use crate::core::agent_cli::debug::prompt_size::{render_text, PromptSizeReport};
use crate::core::agent_cli::debug::{
dump_agent_prompt, dump_all_agent_prompts, write_prompt_dumps, DumpPromptOptions, DumpedPrompt,
};
pub(crate) mod debug;
/// Entry point for `openhuman agent <subcommand>`.
pub fn run_agent_command(args: &[String]) -> Result<()> {
if args.is_empty() || is_help(&args[0]) {
print_agent_help();
return Ok(());
}
match args[0].as_str() {
"dump-prompt" => run_dump_prompt(&args[1..]),
"dump-all" => run_dump_all(&args[1..]),
"prompt-size" => run_prompt_size(&args[1..]),
"list" => run_list(&args[1..]),
other => Err(anyhow!(
"unknown agent subcommand '{other}'. Run `openhuman agent --help`."
)),
}
}
// ---------------------------------------------------------------------------
// prompt-size
// ---------------------------------------------------------------------------
/// How many rows the human-readable section / tool tables print.
///
/// `--json` always carries every row; these caps only keep the terminal
/// output readable. The orchestrator advertises well over a hundred tools and
/// a full dump scrolls the interesting rows off the screen, which defeats the
/// point of a diagnostic.
const PROMPT_SIZE_SECTION_ROWS: usize = 15;
const PROMPT_SIZE_TOOL_ROWS: usize = 20;
/// Where `--hermetic` puts the config file, relative to the workspace's parent.
///
/// Mirrors the layout `Config::load_or_init` produces and `Harness` reproduces:
/// `config.toml` beside the `workspace` directory, not inside it.
const HERMETIC_CONFIG_FILENAME: &str = "config.toml";
struct PromptSizeFlags {
/// `None` means "every registered agent" — the fleet-wide view the ratchet
/// consumes.
agent: Option<String>,
workspace: Option<PathBuf>,
model: Option<String>,
json: bool,
verbose: bool,
/// Also relocate `config_path` beside the workspace, so credentials and
/// integration toggles come from the temp dir rather than `~/.openhuman`.
hermetic: bool,
}
fn parse_prompt_size_flags(args: &[String]) -> Result<PromptSizeFlags> {
let mut agent: Option<String> = None;
let mut workspace: Option<PathBuf> = None;
let mut model: Option<String> = None;
let mut json = false;
let mut verbose = false;
let mut hermetic = false;
let mut i = 0usize;
while i < args.len() {
match args[i].as_str() {
"--hermetic" => {
hermetic = true;
i += 1;
}
"--agent" | "-a" => {
agent = Some(
args.get(i + 1)
.ok_or_else(|| anyhow!("missing value for --agent"))?
.clone(),
);
i += 2;
}
"--workspace" | "-w" => {
workspace = Some(PathBuf::from(
args.get(i + 1)
.ok_or_else(|| anyhow!("missing value for --workspace"))?,
));
i += 2;
}
"--model" | "-m" => {
model = Some(
args.get(i + 1)
.ok_or_else(|| anyhow!("missing value for --model"))?
.clone(),
);
i += 2;
}
"--json" => {
json = true;
i += 1;
}
"-v" | "--verbose" => {
verbose = true;
i += 1;
}
"-h" | "--help" => {
print_prompt_size_help();
std::process::exit(0);
}
other => return Err(anyhow!("unknown prompt-size arg: {other}")),
}
}
Ok(PromptSizeFlags {
agent,
workspace,
model,
json,
verbose,
hermetic,
})
}
/// `openhuman agent prompt-size` — report where an agent's fixed per-turn
/// budget goes.
///
/// With `--agent`, renders one agent. Without it, renders every registered
/// agent through the same `dump_all_agent_prompts` path `dump-all` uses, so
/// the fleet view and the per-agent view cannot disagree.
fn run_prompt_size(args: &[String]) -> Result<()> {
let flags = parse_prompt_size_flags(args)?;
init_quiet_logging(flags.verbose);
let rt = tokio::runtime::Builder::new_multi_thread()
.enable_all()
.thread_stack_size(crate::core::runtime::AGENT_WORKER_STACK_BYTES)
.max_blocking_threads(crate::core::runtime::MAX_BLOCKING_THREADS)
.build()?;
// `--hermetic` without `--workspace` would silently measure the real
// install, which is the failure this flag exists to prevent — so refuse
// rather than guess.
let config_path = if flags.hermetic {
let Some(workspace) = flags.workspace.as_ref() else {
return Err(anyhow!("--hermetic requires --workspace <dir>"));
};
let parent = workspace.parent().unwrap_or(workspace.as_path());
Some(parent.join(HERMETIC_CONFIG_FILENAME))
} else {
None
};
let reports: Vec<PromptSizeReport> = match &flags.agent {
Some(agent_id) => {
let mut options = DumpPromptOptions::new(agent_id.clone());
options.workspace_dir_override = flags.workspace.clone();
options.config_path_override = config_path.clone();
options.model_override = flags.model.clone();
vec![rt.block_on(PromptSizeReport::build(options))?]
}
None => {
let dumps: Vec<DumpedPrompt> = rt.block_on(async {
dump_all_agent_prompts(
flags.workspace.clone(),
config_path.clone(),
flags.model.clone(),
)
.await
})?;
dumps.iter().map(PromptSizeReport::from_dump).collect()
}
};
if flags.json {
// A bare array for a single agent would force every consumer to
// special-case arity. The ratchet reads `agents`, always a list.
let total: usize = reports.iter().map(|r| r.fixed_prefix_bytes).sum();
println!(
"{}",
serde_json::to_string_pretty(&serde_json::json!({
"agents": reports,
"fixed_prefix_bytes_total": total,
}))?
);
return Ok(());
}
for (idx, report) in reports.iter().enumerate() {
if idx > 0 {
println!("\n{}\n", "-".repeat(72));
}
print!(
"{}",
render_text(report, PROMPT_SIZE_SECTION_ROWS, PROMPT_SIZE_TOOL_ROWS)
);
}
if reports.len() > 1 {
let total: usize = reports.iter().map(|r| r.fixed_prefix_bytes).sum();
println!("\n{}\n", "=".repeat(72));
println!(
"{} agents, {} B of fixed prefix in total",
reports.len(),
total
);
}
Ok(())
}
fn print_prompt_size_help() {
println!("openhuman agent prompt-size — where an agent's fixed per-turn budget goes");
println!();
println!("Reports the system prompt AND the advertised tool schemas, which ride");
println!("alongside it in every request and are typically the larger half.");
println!();
println!("Usage:");
println!(" openhuman agent prompt-size [--agent <id>] [options]");
println!();
println!("Options:");
println!(" --agent, -a <id> One agent. Omit to report every registered agent.");
println!(" --workspace, -w <p> Workspace to resolve identity/memory files against.");
println!(" --model, -m <name> Override the resolved model name.");
println!(" --hermetic Also resolve config + credentials from the --workspace");
println!(" parent, not ~/.openhuman. REQUIRED for a reproducible");
println!(" number: ~20 backend-proxied integration tools appear or");
println!(" vanish with whether you happen to be signed in.");
println!(" --json Full machine-readable breakdown (every row).");
println!(" -v, --verbose Restore normal logging.");
println!();
println!("Bytes are the unit of record; the `~tok` column is an estimate for reading.");
}
// ---------------------------------------------------------------------------
// dump-all
// ---------------------------------------------------------------------------
struct DumpAllFlags {
out: PathBuf,
workspace: Option<PathBuf>,
model: Option<String>,
verbose: bool,
}
fn parse_dump_all_flags(args: &[String]) -> Result<DumpAllFlags> {
let mut out: Option<PathBuf> = None;
let mut workspace: Option<PathBuf> = None;
let mut model: Option<String> = None;
let mut verbose = false;
let mut i = 0usize;
while i < args.len() {
match args[i].as_str() {
"--out" | "-o" => {
out = Some(PathBuf::from(
args.get(i + 1)
.ok_or_else(|| anyhow!("missing value for --out"))?,
));
i += 2;
}
"--workspace" | "-w" => {
workspace = Some(PathBuf::from(
args.get(i + 1)
.ok_or_else(|| anyhow!("missing value for --workspace"))?,
));
i += 2;
}
"--model" | "-m" => {
model = Some(
args.get(i + 1)
.ok_or_else(|| anyhow!("missing value for --model"))?
.clone(),
);
i += 2;
}
"-v" | "--verbose" => {
verbose = true;
i += 1;
}
"-h" | "--help" => {
println!(
"Usage: openhuman agent dump-all --out <dir> [--workspace <path>] [--model <name>] [-v]"
);
println!();
println!("Render every registered agent's turn-1 system prompt into <dir>.");
std::process::exit(0);
}
other => return Err(anyhow!("unknown dump-all arg: {other}")),
}
}
Ok(DumpAllFlags {
out: out.ok_or_else(|| anyhow!("--out <dir> is required"))?,
workspace,
model,
verbose,
})
}
fn run_dump_all(args: &[String]) -> Result<()> {
let flags = parse_dump_all_flags(args)?;
init_quiet_logging(flags.verbose);
log::debug!(
"[agent-cli] run_dump_all entry: out={} workspace={:?} model={:?}",
flags.out.display(),
flags.workspace,
flags.model
);
let rt = tokio::runtime::Builder::new_multi_thread()
.enable_all()
.thread_stack_size(crate::core::runtime::AGENT_WORKER_STACK_BYTES)
.max_blocking_threads(crate::core::runtime::MAX_BLOCKING_THREADS)
.build()?;
log::debug!("[agent-cli] run_dump_all: calling dump_all_agent_prompts");
let dumps = rt.block_on(async {
dump_all_agent_prompts(flags.workspace.clone(), None, flags.model.clone()).await
})?;
log::debug!(
"[agent-cli] run_dump_all: dump_all_agent_prompts returned {} prompt(s)",
dumps.len()
);
write_prompt_dumps(&flags.out, &dumps)?;
log::debug!(
"[agent-cli] run_dump_all exit: wrote {} prompt(s) + SUMMARY.txt",
dumps.len()
);
Ok(())
}
// ---------------------------------------------------------------------------
// dump-prompt
// ---------------------------------------------------------------------------
struct DumpFlags {
agent: Option<String>,
workspace: Option<PathBuf>,
model: Option<String>,
json: bool,
with_tools: bool,
wire: bool,
verbose: bool,
}
fn parse_dump_flags(args: &[String]) -> Result<DumpFlags> {
let mut out = DumpFlags {
agent: None,
workspace: None,
model: None,
json: false,
with_tools: false,
wire: false,
verbose: false,
};
let mut i = 0usize;
while i < args.len() {
match args[i].as_str() {
"--agent" | "-a" => {
out.agent = Some(
args.get(i + 1)
.ok_or_else(|| anyhow!("missing value for --agent"))?
.clone(),
);
i += 2;
}
"--workspace" | "-w" => {
out.workspace = Some(PathBuf::from(
args.get(i + 1)
.ok_or_else(|| anyhow!("missing value for --workspace"))?,
));
i += 2;
}
"--model" | "-m" => {
out.model = Some(
args.get(i + 1)
.ok_or_else(|| anyhow!("missing value for --model"))?
.clone(),
);
i += 2;
}
"--json" => {
out.json = true;
i += 1;
}
"--with-tools" => {
out.with_tools = true;
i += 1;
}
"--wire" => {
out.wire = true;
i += 1;
}
"-v" | "--verbose" => {
out.verbose = true;
i += 1;
}
"-h" | "--help" => {
print_dump_prompt_help();
std::process::exit(0);
}
other => return Err(anyhow!("unknown dump-prompt arg: {other}")),
}
let _ = i; // silence unused-warning in the `help` branch
}
Ok(out)
}
fn run_dump_prompt(args: &[String]) -> Result<()> {
let flags = parse_dump_flags(args)?;
let agent = flags
.agent
.clone()
.ok_or_else(|| anyhow!("--agent <id> is required (e.g. `orchestrator`, `researcher`)"))?;
init_quiet_logging(flags.verbose);
log::debug!(
"[agent-cli] run_dump_prompt entry: agent={} workspace={:?} model={:?}",
agent,
flags.workspace,
flags.model
);
let options = DumpPromptOptions {
agent_id: agent,
workspace_dir_override: flags.workspace.clone(),
// `dump-prompt` deliberately keeps reading the real install: its job is
// to show what the signed-in user's agent actually receives, including
// their connected integrations. `prompt-size --hermetic` is the one
// that needs reproducibility.
config_path_override: None,
model_override: flags.model.clone(),
};
let rt = tokio::runtime::Builder::new_multi_thread()
.enable_all()
.thread_stack_size(crate::core::runtime::AGENT_WORKER_STACK_BYTES)
.max_blocking_threads(crate::core::runtime::MAX_BLOCKING_THREADS)
.build()?;
log::debug!("[agent-cli] run_dump_prompt: calling dump_agent_prompt");
let dumped = rt.block_on(async { dump_agent_prompt(options).await })?;
log::debug!(
"[agent-cli] run_dump_prompt: dump returned (tools={}, skill_tools={}, prompt_bytes={})",
dumped.tool_names.len(),
dumped.skill_tool_count,
dumped.text.len()
);
if flags.wire {
// Everything on stdout, deliberately: this artefact is one document
// and splitting the header onto stderr the way `print_human` does
// would make `> turn.txt` drop the byte counts that give the payload
// its meaning.
print!(
"{}",
crate::core::agent_cli::debug::render_wire_dump(&dumped)
);
} else if flags.json {
print_json(&dumped, flags.with_tools)?;
} else {
print_human(&dumped, flags.with_tools);
}
Ok(())
}
fn print_human(dumped: &DumpedPrompt, with_tools: bool) {
// Banner on stderr so `openhuman agent dump-prompt ... > file.md` stays
// clean — stdout is the prompt, stderr is the metadata. This matches
// the pattern already used by `run_call_command` / `run_server_command`
// in `core/cli.rs` (banner to stderr, JSON result to stdout).
eprintln!("# Agent prompt dump");
eprintln!("agent: {}", dumped.agent_id);
eprintln!("mode: {}", dumped.mode);
eprintln!("model: {}", dumped.model);
eprintln!("workspace: {}", dumped.workspace_dir.display());
eprintln!("tool_count: {}", dumped.tool_names.len());
eprintln!("skill_tools: {}", dumped.skill_tool_count);
if with_tools {
eprintln!("tools:");
for name in &dumped.tool_names {
eprintln!(" - {name}");
}
}
eprintln!();
eprintln!("─── BEGIN SYSTEM PROMPT ───");
println!("{}", dumped.text);
eprintln!("─── END SYSTEM PROMPT ───");
}
fn print_json(dumped: &DumpedPrompt, with_tools: bool) -> Result<()> {
// Use a plain serde_json::Value so we don't need to add Serialize to
// DumpedPrompt (which would pull the agent harness types into our
// serde surface). This output is stable and scriptable from bash.
let mut obj = serde_json::Map::new();
obj.insert(
"agent_id".into(),
serde_json::Value::String(dumped.agent_id.clone()),
);
obj.insert(
"mode".into(),
serde_json::Value::String(dumped.mode.to_string()),
);
obj.insert(
"model".into(),
serde_json::Value::String(dumped.model.clone()),
);
obj.insert(
"workspace_dir".into(),
serde_json::Value::String(dumped.workspace_dir.display().to_string()),
);
obj.insert(
"tool_count".into(),
serde_json::Value::Number(dumped.tool_names.len().into()),
);
obj.insert(
"skill_tool_count".into(),
serde_json::Value::Number(dumped.skill_tool_count.into()),
);
obj.insert(
"system_prompt".into(),
serde_json::Value::String(dumped.text.clone()),
);
if with_tools {
obj.insert(
"tools".into(),
serde_json::Value::Array(
dumped
.tool_names
.iter()
.cloned()
.map(serde_json::Value::String)
.collect(),
),
);
// The schemas, not just the names: they ride alongside the prompt on
// every request and for a few-hundred-tool agent they are the larger
// half of the fixed cost. Emitting only `tools` measures the smaller.
obj.insert(
"tool_specs".into(),
serde_json::Value::Array(dumped.tool_specs.clone()),
);
}
println!(
"{}",
serde_json::to_string_pretty(&serde_json::Value::Object(obj))?
);
Ok(())
}
// ---------------------------------------------------------------------------
// list
// ---------------------------------------------------------------------------
fn run_list(args: &[String]) -> Result<()> {
let mut as_json = false;
let mut workspace: Option<PathBuf> = None;
let mut verbose = false;
let mut i = 0usize;
while i < args.len() {
match args[i].as_str() {
"--json" => {
as_json = true;
i += 1;
}
"--workspace" | "-w" => {
workspace = Some(PathBuf::from(
args.get(i + 1)
.ok_or_else(|| anyhow!("missing value for --workspace"))?,
));
i += 2;
}
"-v" | "--verbose" => {
verbose = true;
i += 1;
}
"-h" | "--help" => {
println!("Usage: openhuman agent list [--workspace <path>] [--json] [-v]");
println!();
println!(
" List every built-in agent plus any custom `<workspace>/agents/*.toml` overrides."
);
return Ok(());
}
other => return Err(anyhow!("unknown list arg: {other}")),
}
}
// Silence the logger so Config::load_or_init and AgentDefinitionRegistry::load
// don't write warnings/info to stdout, which would corrupt --json output.
// (The project's CLI logger writes to stdout, not stderr.)
init_quiet_logging(verbose);
// Resolve workspace-custom overrides the same way the runtime does
// at spawn time. When --workspace is explicit we load against it
// directly; otherwise the registry helper does the Config dance.
let registry = if let Some(ws) = workspace {
AgentDefinitionRegistry::load(&ws)?
} else {
let rt = tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()?;
rt.block_on(AgentDefinitionRegistry::load_for_default_workspace())?
};
if as_json {
let mut arr = Vec::new();
for def in registry.list() {
let mut obj = serde_json::Map::new();
obj.insert("id".into(), serde_json::Value::String(def.id.clone()));
obj.insert(
"display_name".into(),
serde_json::Value::String(def.display_name().to_string()),
);
obj.insert(
"when_to_use".into(),
serde_json::Value::String(def.when_to_use.clone()),
);
obj.insert(
"omit_safety_preamble".into(),
serde_json::Value::Bool(def.extensions.omit_safety_preamble),
);
obj.insert(
"omit_identity".into(),
serde_json::Value::Bool(def.extensions.omit_identity),
);
arr.push(serde_json::Value::Object(obj));
}
println!(
"{}",
serde_json::to_string_pretty(&serde_json::Value::Array(arr))?
);
} else {
println!("{:<20} WHEN TO USE", "ID");
println!("{}", "-".repeat(90));
for def in registry.list() {
let when = def.when_to_use.chars().take(68).collect::<String>();
println!("{:<20} {}", def.id, when);
}
println!();
println!("{} agent(s) registered.", registry.len());
}
Ok(())
}
// ---------------------------------------------------------------------------
// Help
// ---------------------------------------------------------------------------
fn print_agent_help() {
println!("openhuman agent — inspect agents and the prompts they receive");
println!();
println!("Usage:");
println!(" openhuman agent list [--workspace <path>] [--json]");
println!(
" openhuman agent dump-prompt --agent <id> [--workspace <path>] [--model <name>] [--with-tools] [--wire] [--json] [-v]"
);
println!(" openhuman agent dump-all --out <dir> [--workspace <path>] [--model <name>] [-v]");
println!(" openhuman agent prompt-size [--agent <id>] [--workspace <path>] [--json] [-v]");
println!();
println!("Run `openhuman agent <subcommand> --help` for details.");
}
fn print_dump_prompt_help() {
println!("openhuman agent dump-prompt — render the exact system prompt an agent receives");
println!();
println!("Usage:");
println!(" openhuman agent dump-prompt --agent <id> [options]");
println!();
println!("Required:");
println!(" --agent, -a <id> Target agent id — any built-in or workspace-custom id");
println!(" (e.g. `orchestrator`, `researcher`).");
println!();
println!("Options:");
println!(" --workspace, -w <p> Override the workspace directory (defaults to");
println!(" Config::workspace_dir / ~/.openhuman/workspace).");
println!(" --model, -m <name> Override the resolved model name (affects only the");
println!(" `## Runtime` section).");
println!(
" --with-tools Also print the full list of tool names the agent sees.
--wire Print the ENTIRE fixed prefix exactly as the model
receives it: the system prompt verbatim, then every
advertised tool schema minified the way it is sent,
with byte counts for each half. This is the whole
per-turn cost in one document."
);
println!(" --json Emit a machine-readable JSON object on stdout.");
println!(" -v, --verbose Enable debug logging on stderr.");
println!();
println!("Examples:");
println!(" # Orchestrator prompt, JSON for scripting.");
println!(" openhuman agent dump-prompt --agent orchestrator --json");
println!();
println!(" # Orchestrator prompt with its tool list.");
println!(" openhuman agent dump-prompt --agent orchestrator --with-tools");
}
fn is_help(value: &str) -> bool {
matches!(value, "-h" | "--help" | "help")
}
/// Quiet logging: only `error` unless verbose. We pin this lower than
/// `warn` (the default in `skills_cli::init_quiet_logging`) because
/// `agent dump-prompt` is designed to be redirected into a file, and
/// expected warnings like `[integrations] no auth token available …`
/// would otherwise interleave with the rendered prompt body on stdout
/// (the project's CLI logger writes to stdout, not stderr). Verbose
/// users can opt back in with `-v` or `RUST_LOG=…`.
fn init_quiet_logging(verbose: bool) {
if !verbose && std::env::var_os("RUST_LOG").is_none() {
std::env::set_var("RUST_LOG", "error");
}
crate::core::logging::init_for_cli_run(verbose, crate::core::logging::CliLogDefault::Global);
}