use super::sessions::is_prefixed_id;
use crate::output::{OutputFormat, print_field};
use anyhow::{Context, Result};
use clap::Subcommand;
use everruns_core::agent_package::{ALLOWED_DOT_ENTRIES, DENIED_DOT_ENTRIES};
use serde::Deserialize;
use std::path::Path;
const DEFAULT_AGENT_FILE_NAME: &str = "agent.toml";
mod packages;
use packages::print_package_report;
pub use packages::run_local;
#[derive(Subcommand)]
pub enum AgentsCommand {
Import {
#[arg(value_name = "PATH", conflicts_with = "content")]
file: Option<String>,
#[arg(long, conflicts_with = "file")]
content: Option<String>,
#[arg(long)]
target: Option<String>,
#[arg(long)]
format: Option<String>,
#[arg(long, value_name = "TEXT")]
reason: Option<String>,
},
Export {
agent: String,
#[arg(long, default_value = "markdown", value_parser = ["markdown", "toml", "yaml", "json", "zip", "folder"])]
format: String,
#[arg(long)]
out: Option<std::path::PathBuf>,
},
Validate {
file: String,
#[arg(long)]
remote: bool,
},
Diff {
file: String,
#[arg(long, conflicts_with = "target")]
against: Option<String>,
#[arg(long, conflicts_with = "against")]
target: Option<String>,
},
Create {
#[arg(short, long)]
file: Option<String>,
#[arg(long)]
initial_files_dir: Option<String>,
#[arg(long)]
writable: bool,
#[arg(long)]
name: Option<String>,
#[arg(long = "instructions", alias = "system-prompt")]
system_prompt: Option<String>,
#[arg(long)]
description: Option<String>,
#[arg(long)]
model: Option<String>,
#[arg(long, short = 'H')]
harness: Option<String>,
#[arg(long, short)]
tag: Vec<String>,
#[arg(long, value_name = "TEXT")]
reason: Option<String>,
},
Update {
agent_id: Option<String>,
#[arg(short, long)]
file: Option<String>,
#[arg(long)]
initial_files_dir: Option<String>,
#[arg(long)]
writable: bool,
#[arg(long)]
name: Option<String>,
#[arg(long = "instructions", alias = "system-prompt")]
system_prompt: Option<String>,
#[arg(long)]
description: Option<String>,
#[arg(long)]
model: Option<String>,
#[arg(long, short = 'H')]
harness: Option<String>,
#[arg(long, short)]
tag: Vec<String>,
#[arg(long, value_name = "TEXT")]
reason: Option<String>,
},
}
#[derive(Debug, Deserialize, serde::Serialize)]
struct ImportedAgent {
id: String,
name: String,
}
pub async fn run(
command: AgentsCommand,
api_url: &str,
api_key: &str,
org_id: Option<&str>,
output: OutputFormat,
quiet: bool,
) -> Result<()> {
match command {
command @ (AgentsCommand::Import { .. }
| AgentsCommand::Export { .. }
| AgentsCommand::Validate { .. }
| AgentsCommand::Diff { .. }) => {
packages::run(command, api_url, api_key, org_id, output).await
}
AgentsCommand::Create {
file,
initial_files_dir,
writable,
name,
system_prompt,
description,
model,
harness,
tag,
reason,
} => {
let use_default_file = name.is_none()
&& system_prompt.is_none()
&& description.is_none()
&& model.is_none()
&& harness.is_none()
&& tag.is_empty();
let file = resolve_agent_file(file, use_default_file);
if let Some(path) = file {
if name.is_some()
|| system_prompt.is_some()
|| description.is_some()
|| model.is_some()
|| harness.is_some()
|| !tag.is_empty()
{
eprintln!("Warning: CLI flag overrides are ignored when --file is used");
}
import_from_file(
api_url,
api_key,
org_id,
&path,
initial_files_dir.as_deref(),
writable,
reason.as_deref(),
output,
quiet,
)
.await
} else {
if initial_files_dir.is_some() {
anyhow::bail!("--initial-files-dir requires --file");
}
let client = super::api::ApiClient::new(api_url, api_key, org_id);
save_from_flags(
&client,
None,
output,
quiet,
name,
system_prompt,
description,
model,
harness,
tag,
reason,
)
.await
}
}
AgentsCommand::Update {
agent_id,
file,
initial_files_dir,
writable,
name,
system_prompt,
description,
model,
harness,
tag,
reason,
} => {
let use_default_file = agent_id.is_none()
&& name.is_none()
&& system_prompt.is_none()
&& description.is_none()
&& model.is_none()
&& harness.is_none()
&& tag.is_empty();
let file = resolve_agent_file(file, use_default_file);
if let Some(path) = file {
if agent_id.is_some()
|| name.is_some()
|| system_prompt.is_some()
|| description.is_some()
|| model.is_some()
|| harness.is_some()
|| !tag.is_empty()
{
eprintln!("Warning: CLI flag overrides are ignored when --file is used");
}
import_from_file(
api_url,
api_key,
org_id,
&path,
initial_files_dir.as_deref(),
writable,
reason.as_deref(),
output,
quiet,
)
.await
} else {
if initial_files_dir.is_some() {
anyhow::bail!("--initial-files-dir requires --file");
}
let id = agent_id.context("Agent ID is required for update without --file")?;
let client = super::api::ApiClient::new(api_url, api_key, org_id);
save_from_flags(
&client,
Some(&id),
output,
quiet,
name,
system_prompt,
description,
model,
harness,
tag,
reason,
)
.await
}
}
}
}
#[allow(clippy::too_many_arguments)]
async fn import_from_file(
api_url: &str,
api_key: &str,
org_id: Option<&str>,
path: &str,
initial_files_dir: Option<&str>,
writable: bool,
reason: Option<&str>,
output: OutputFormat,
quiet: bool,
) -> Result<()> {
let client = super::api::ApiClient::new(api_url, api_key, org_id);
let legacy_hidden_policy = std::fs::read_to_string(path)
.ok()
.is_some_and(|s| s.contains("initial_files_allow_hidden"));
if initial_files_dir.is_none() && !legacy_hidden_policy {
let package = everruns_core::agent_package::AgentPackage::load(path)?;
let mut payload: serde_json::Value =
serde_json::from_str(&package.to_string(everruns_core::agent_package::Format::Json)?)?;
if let Some(id) = package.legacy_id {
payload
.as_object_mut()
.context("manifest")?
.remove("schema_version");
payload["id"] = serde_json::json!(id);
}
if let Some(id) = package.legacy_model_id {
payload
.as_object_mut()
.context("manifest")?
.remove("schema_version");
payload["default_model_id"] = serde_json::json!(id);
}
if let Some(id) = package.legacy_harness_id {
payload
.as_object_mut()
.context("manifest")?
.remove("schema_version");
payload["harness_id"] = serde_json::json!(id);
}
if writable && let Some(files) = payload["files"].as_array_mut() {
for file in files {
file["is_readonly"] = serde_json::json!(false);
}
}
let response = client
.post_with_reason("/v1/agents/import", Some(&payload), reason)
.await?;
print_package_report(output, &response);
return Ok(());
}
let file_path = Path::new(path);
let content =
std::fs::read_to_string(path).with_context(|| format!("Failed to read file: {}", path))?;
let file_dir = std::fs::canonicalize(path)
.with_context(|| format!("Cannot resolve file path: {}", path))?
.parent()
.map(|p| p.to_path_buf())
.unwrap_or_else(|| std::path::PathBuf::from("."));
let parsed_agent = parse_agent_file_as_json(file_path, &content).ok();
let has_glob_initial_files = parsed_agent.as_ref().is_some_and(initial_files_has_globs);
let should_send_json =
initial_files_dir.is_some() || has_glob_initial_files || is_toml_agent_file(file_path);
let (body, content_type) = if should_send_json {
let mut agent = if let Some(agent) = parsed_agent {
agent
} else {
parse_agent_file_as_json(file_path, &content).context("Failed to parse agent file")?
};
if let Some(dir) = initial_files_dir {
let allow_hidden = extract_allow_hidden_extras(&agent);
let files = glob_initial_files(dir, writable, &allow_hidden)?;
agent["initial_files"] = serde_json::to_value(&files)?;
} else if has_glob_initial_files {
let files = expand_initial_files_globs(&agent, &file_dir, writable)?;
agent["initial_files"] = serde_json::to_value(&files)?;
}
if let Some(obj) = agent.as_object_mut() {
obj.remove("initial_files_allow_hidden");
}
(serde_json::to_string(&agent)?, "application/json")
} else {
(content, "text/plain")
};
let resp = super::api::with_change_reason(
client.request(reqwest::Method::POST, "/v1/agents/import"),
reason,
)
.header("Content-Type", content_type)
.body(body)
.send()
.await
.context("Failed to send import request")?;
let status = resp.status();
if !status.is_success() {
let body = resp.text().await.unwrap_or_default();
anyhow::bail!("Import failed ({}): {}", status, body);
}
let was_created = status == reqwest::StatusCode::CREATED;
let agent: ImportedAgent = resp
.json()
.await
.context("Failed to parse import response")?;
let verb = if was_created { "Created" } else { "Applied" };
if output.is_text() {
if quiet {
println!("{}", agent.id);
} else {
println!("{} agent: {}", verb, agent.id);
print_field("Name", &agent.name);
}
} else {
let json = serde_json::json!({
"id": agent.id,
"name": agent.name,
"action": verb.to_lowercase(),
});
output.print_value(&json);
}
Ok(())
}
fn resolve_agent_file(file: Option<String>, use_default: bool) -> Option<String> {
file.or_else(|| {
if use_default && Path::new(DEFAULT_AGENT_FILE_NAME).is_file() {
Some(DEFAULT_AGENT_FILE_NAME.to_string())
} else {
None
}
})
}
#[derive(Debug, serde::Serialize, serde::Deserialize)]
struct CollectedFile {
path: String,
content: String,
encoding: String,
is_readonly: bool,
}
fn extract_allow_hidden_extras(agent: &serde_json::Value) -> Vec<String> {
let Some(arr) = agent
.get("initial_files_allow_hidden")
.and_then(|v| v.as_array())
else {
return Vec::new();
};
arr.iter()
.filter_map(|v| v.as_str().map(|s| s.to_string()))
.filter(|s| is_valid_basename_extra(s))
.filter(|s| !DENIED_DOT_ENTRIES.contains(&s.as_str()))
.collect()
}
fn is_valid_basename_extra(s: &str) -> bool {
if !s.starts_with('.') || s == "." || s == ".." {
return false;
}
!s.contains('/') && !s.contains('\\')
}
struct HiddenPathPolicy {
allowed: std::collections::HashSet<String>,
}
impl HiddenPathPolicy {
fn new(extras: &[String]) -> Self {
let mut allowed: std::collections::HashSet<String> = ALLOWED_DOT_ENTRIES
.iter()
.map(|s| (*s).to_string())
.collect();
for extra in extras {
if is_valid_basename_extra(extra) && !DENIED_DOT_ENTRIES.contains(&extra.as_str()) {
allowed.insert(extra.clone());
}
}
Self { allowed }
}
fn allow_walk_names(&self) -> impl Iterator<Item = &String> {
self.allowed.iter()
}
fn component_is_disallowed(&self, component: &str) -> bool {
if !component.starts_with('.') {
return false;
}
if DENIED_DOT_ENTRIES.contains(&component) {
return true;
}
!self.allowed.contains(component)
}
fn path_has_disallowed_component(&self, path: &Path) -> bool {
path.components().any(|component| {
let std::path::Component::Normal(name) = component else {
return false;
};
self.component_is_disallowed(&name.to_string_lossy())
})
}
}
fn glob_initial_files(
dir: &str,
writable: bool,
allow_hidden_extras: &[String],
) -> Result<Vec<CollectedFile>> {
let base =
std::fs::canonicalize(dir).with_context(|| format!("Cannot resolve directory: {}", dir))?;
if !base.is_dir() {
anyhow::bail!("Not a directory: {}", base.display());
}
let policy = HiddenPathPolicy::new(allow_hidden_extras);
let walker = ignore::WalkBuilder::new(&base)
.hidden(true) .git_ignore(true) .git_global(false) .git_exclude(false) .build();
let dot_walkers: Vec<_> = policy
.allow_walk_names()
.filter_map(|name| {
let dot_path = base.join(name);
if dot_path.is_dir() {
Some(
ignore::WalkBuilder::new(&dot_path)
.hidden(false) .git_ignore(true)
.git_global(false)
.git_exclude(false)
.build(),
)
} else {
None
}
})
.collect();
let mut files = Vec::new();
let all_entries = walker.chain(dot_walkers.into_iter().flatten());
for entry in all_entries {
let entry = entry.context("Failed to read directory entry")?;
let path = entry.path();
if !path.is_file() {
continue;
}
let canonical = std::fs::canonicalize(path)
.with_context(|| format!("Cannot resolve file: {}", path.display()))?;
if !canonical.starts_with(&base) {
eprintln!(
"Warning: skipping symlink outside base directory: {}",
path.display()
);
continue;
}
let rel = canonical
.strip_prefix(&base)
.context("File outside base directory")?;
if policy.path_has_disallowed_component(rel) {
eprintln!(
"Warning: skipping hidden path: {} (allowed: {:?})",
canonical.display(),
ALLOWED_DOT_ENTRIES
);
continue;
}
let rel_normalized = rel.to_string_lossy().replace('\\', "/");
let workspace_path = format!("/workspace/{}", rel_normalized);
match std::fs::read_to_string(path) {
Ok(content) => {
files.push(CollectedFile {
path: workspace_path,
content,
encoding: "text".to_string(),
is_readonly: !writable,
});
}
Err(_) => {
eprintln!(
"Warning: skipping binary or unreadable file: {}",
path.display()
);
}
}
}
if files.is_empty() {
anyhow::bail!("No files found in directory: {}", dir);
}
files.sort_by(|a, b| a.path.cmp(&b.path));
Ok(files)
}
fn initial_files_has_globs(agent: &serde_json::Value) -> bool {
let Some(arr) = agent.get("initial_files").and_then(|v| v.as_array()) else {
return false;
};
arr.iter().any(|v| v.is_string())
}
fn is_toml_agent_file(path: &Path) -> bool {
path.extension()
.and_then(|ext| ext.to_str())
.is_some_and(|ext| ext.eq_ignore_ascii_case("toml"))
}
fn glob_base_dir(pattern: &str) -> &str {
if let Some(pos) = pattern.find(['*', '?', '[']) {
let prefix = &pattern[..pos];
prefix.trim_end_matches('/').trim_end_matches('\\')
} else {
pattern
}
}
fn expand_initial_files_globs(
agent: &serde_json::Value,
base_dir: &Path,
writable: bool,
) -> Result<Vec<CollectedFile>> {
let Some(arr) = agent.get("initial_files").and_then(|v| v.as_array()) else {
return Ok(vec![]);
};
let allow_hidden_extras = extract_allow_hidden_extras(agent);
let policy = HiddenPathPolicy::new(&allow_hidden_extras);
let base_canonical = std::fs::canonicalize(base_dir)?;
let mut all_files: Vec<CollectedFile> = Vec::new();
for entry in arr {
if let Some(pattern) = entry.as_str() {
let clean_path = glob_base_dir(pattern);
let resolved = base_dir.join(clean_path);
let resolved = std::fs::canonicalize(&resolved).with_context(|| {
format!(
"Cannot resolve initial_files path: {} (relative to {})",
pattern,
base_dir.display()
)
})?;
if resolved.is_dir() {
let rel = resolved.strip_prefix(&base_canonical)?;
if policy.path_has_disallowed_component(rel) {
eprintln!(
"Warning: skipping hidden directory: {} (allowed: {:?}; user opt-ins: {:?})",
resolved.display(),
ALLOWED_DOT_ENTRIES,
allow_hidden_extras,
);
continue;
}
collect_dir_files(
&resolved,
&base_canonical,
writable,
&policy,
&mut all_files,
)?;
} else if resolved.is_file() {
collect_single_file(
&resolved,
&base_canonical,
writable,
&policy,
&mut all_files,
)?;
} else {
anyhow::bail!(
"initial_files pattern resolved to non-existent path: {}",
resolved.display()
);
}
} else if entry.is_object() {
let file: CollectedFile = serde_json::from_value(entry.clone())
.context("Invalid initial_files entry object")?;
all_files.push(file);
} else {
anyhow::bail!("initial_files entries must be strings (paths/globs) or objects");
}
}
let mut seen = std::collections::HashSet::new();
all_files.retain(|f| seen.insert(f.path.clone()));
if all_files.is_empty() {
anyhow::bail!("initial_files patterns matched no files");
}
all_files.sort_by(|a, b| a.path.cmp(&b.path));
Ok(all_files)
}
fn collect_dir_files(
dir: &Path,
workspace_base: &Path,
writable: bool,
policy: &HiddenPathPolicy,
files: &mut Vec<CollectedFile>,
) -> Result<()> {
let walker = ignore::WalkBuilder::new(dir)
.hidden(true)
.git_ignore(true)
.git_global(false)
.git_exclude(false)
.build();
let dot_walkers: Vec<_> = policy
.allow_walk_names()
.filter_map(|name| {
let dot_path = dir.join(name);
if dot_path.is_dir() {
Some(
ignore::WalkBuilder::new(&dot_path)
.hidden(false)
.git_ignore(true)
.git_global(false)
.git_exclude(false)
.build(),
)
} else {
None
}
})
.collect();
let all_entries = walker.chain(dot_walkers.into_iter().flatten());
for entry in all_entries {
let entry = entry.context("Failed to read directory entry")?;
let path = entry.path();
if !path.is_file() {
continue;
}
let canonical = std::fs::canonicalize(path)
.with_context(|| format!("Cannot resolve file: {}", path.display()))?;
if !canonical.starts_with(workspace_base) {
eprintln!(
"Warning: skipping symlink outside base directory: {}",
path.display()
);
continue;
}
let rel = canonical
.strip_prefix(workspace_base)
.context("File outside base directory")?;
if policy.path_has_disallowed_component(rel) {
eprintln!(
"Warning: skipping hidden path: {} (allowed: {:?})",
canonical.display(),
ALLOWED_DOT_ENTRIES
);
continue;
}
let rel_normalized = rel.to_string_lossy().replace('\\', "/");
let workspace_path = format!("/workspace/{}", rel_normalized);
match std::fs::read_to_string(path) {
Ok(content) => {
files.push(CollectedFile {
path: workspace_path,
content,
encoding: "text".to_string(),
is_readonly: !writable,
});
}
Err(_) => {
eprintln!(
"Warning: skipping binary or unreadable file: {}",
path.display()
);
}
}
}
Ok(())
}
fn collect_single_file(
file_path: &Path,
workspace_base: &Path,
writable: bool,
policy: &HiddenPathPolicy,
files: &mut Vec<CollectedFile>,
) -> Result<()> {
let canonical = std::fs::canonicalize(file_path)
.with_context(|| format!("Cannot resolve file: {}", file_path.display()))?;
if !canonical.starts_with(workspace_base) {
eprintln!(
"Warning: skipping file outside base directory: {}",
file_path.display()
);
return Ok(());
}
let rel = canonical.strip_prefix(workspace_base)?;
if policy.path_has_disallowed_component(rel) {
eprintln!(
"Warning: skipping hidden file: {} (allowed: {:?})",
file_path.display(),
ALLOWED_DOT_ENTRIES,
);
return Ok(());
}
let rel_normalized = rel.to_string_lossy().replace('\\', "/");
let workspace_path = format!("/workspace/{}", rel_normalized);
match std::fs::read_to_string(file_path) {
Ok(content) => {
files.push(CollectedFile {
path: workspace_path,
content,
encoding: "text".to_string(),
is_readonly: !writable,
});
}
Err(_) => {
eprintln!(
"Warning: skipping binary or unreadable file: {}",
file_path.display()
);
}
}
Ok(())
}
fn parse_agent_file_as_json(path: &Path, content: &str) -> Result<serde_json::Value> {
let content = content.trim();
{
let mut lines = content.lines();
if let Some(first) = lines.next()
&& first.trim() == "---"
{
let mut frontmatter_lines = Vec::new();
let mut found_end = false;
for line in &mut lines {
if line.trim() == "---" {
found_end = true;
break;
}
frontmatter_lines.push(line);
}
if found_end {
let frontmatter = frontmatter_lines.join("\n");
let body: String = lines.collect::<Vec<_>>().join("\n");
let body = body.trim();
let mut obj: serde_json::Value = serde_yaml::from_str(&frontmatter)
.context("Failed to parse YAML frontmatter")?;
if !obj.is_object() {
anyhow::bail!(
"Agent file frontmatter must be a YAML mapping, not a scalar or array"
);
}
if !body.is_empty()
&& (obj.get("system_prompt").is_none()
|| obj["system_prompt"].as_str().is_none_or(|s| s.is_empty()))
{
obj["system_prompt"] = serde_json::Value::String(body.to_string());
}
return Ok(obj);
}
}
}
if content.starts_with('{') {
return serde_json::from_str(content).context("Failed to parse JSON");
}
if is_toml_agent_file(path) {
let val: toml::Value = toml::from_str(content).context("Failed to parse TOML")?;
let val = serde_json::to_value(val).context("Failed to convert TOML to JSON")?;
if !val.is_object() {
anyhow::bail!("Agent file must be a TOML object");
}
return Ok(val);
}
let val: serde_json::Value = serde_yaml::from_str(content).context("Failed to parse YAML")?;
if !val.is_object() {
anyhow::bail!("Agent file must be a YAML/JSON object");
}
Ok(val)
}
#[allow(clippy::too_many_arguments)]
async fn save_from_flags(
client: &super::api::ApiClient<'_>,
agent_id: Option<&str>,
output: OutputFormat,
quiet: bool,
name: Option<String>,
system_prompt: Option<String>,
description: Option<String>,
model: Option<String>,
harness: Option<String>,
tags: Vec<String>,
reason: Option<String>,
) -> Result<()> {
let without_file = if agent_id.is_some() {
" for update without --file"
} else {
""
};
let name = name.with_context(|| format!("--name is required{without_file}"))?;
let system_prompt =
system_prompt.with_context(|| format!("--system-prompt is required{without_file}"))?;
let params = crate::contract::with_reason(
agent_params(
agent_id,
name,
system_prompt,
description,
model,
harness,
tags,
),
reason.as_deref(),
);
let command = if agent_id.is_some() {
"upsert_agent"
} else {
"create_agent"
};
let agent = crate::contract::execute(client, command, params).await?;
if output.is_text() {
let id = agent["id"].as_str().unwrap_or_default();
if quiet {
println!("{id}");
} else {
let verb = if agent_id.is_some() {
"Applied"
} else {
"Created"
};
println!("{verb} agent: {id}");
print_field("Name", agent["name"].as_str().unwrap_or_default());
}
} else {
output.print_value(&agent);
}
Ok(())
}
fn agent_params(
agent_id: Option<&str>,
name: String,
system_prompt: String,
description: Option<String>,
model: Option<String>,
harness: Option<String>,
tags: Vec<String>,
) -> serde_json::Value {
let mut params = serde_json::json!({ "name": name, "system_prompt": system_prompt });
if let Some(id) = agent_id {
params["id"] = id.into();
}
if let Some(description) = description {
params["description"] = description.into();
}
if let Some(model) = model {
params["default_model_id"] = model.into();
}
match harness {
Some(h) if is_prefixed_id(&h, "harness") => params["harness_id"] = h.into(),
Some(h) => params["harness_name"] = h.into(),
None => {}
}
if !tags.is_empty() {
params["tags"] = tags.into();
}
params
}
#[cfg(test)]
mod tests;