Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

26.3 KB
Raw Blame
//! `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);
}