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
use crate::config::Config;
use crate::cron::job_builder::{create_agent_job, AgentJobInput};
use crate::cron::origin::{current_job_origin, current_turn_may_skip_approval};
use crate::security::SecurityPolicy;
use async_trait::async_trait;
use serde_json::json;
use std::sync::Arc;
use tinyagents_harness_tools::static_schema;
use tinytools::{PermissionLevel, Tool, ToolCallOptions, ToolExposure, ToolResult};
use {
crate::cron, tinyflows_bus::schedule::types::DeliveryConfig,
tinyflows_bus::schedule::types::JobType, tinyflows_bus::schedule::types::Schedule,
tinyflows_bus::schedule::types::SessionTarget,
};
pub struct CronAddTool {
config: Arc<Config>,
security: Arc<SecurityPolicy>,
}
impl CronAddTool {
pub fn new(config: Arc<Config>, security: Arc<SecurityPolicy>) -> Self {
Self { config, security }
}
}
#[async_trait]
impl Tool for CronAddTool {
/// Superseded by the `cron` tool, which dispatches every scheduler
/// operation on one `action` field. Kept registered and dispatchable so a
/// replayed transcript or a saved skill naming `cron_*` keeps working;
/// hidden from the wire so six schemas do not ship where one does.
fn exposure(&self) -> ToolExposure {
ToolExposure::Hidden
}
fn name(&self) -> &str {
"cron_add"
}
fn description(&self) -> &str {
"Create a scheduled cron job (shell or agent) with cron/at/every schedules. \
Standardizes on device-local timezone unless 'tz' is set. The scheduler polls on an \
interval (default 15s, minimum 5s) and does not 'catch up' missed runs.\n\
Delivery: an agent job created inside a conversation (web chat or a channel such as \
Telegram, Discord, Slack) sends each run's reply back to that same conversation \
automatically; do not set `delivery` or copy a reply target for that. Only set \
`delivery` to override it (`proactive` for an in-app notification, `none` for silent). \
A job created with no conversation defaults to `proactive`. In its scheduled run the \
agent's final reply is what gets delivered. Reminders and recurring messages always \
deliver. A conditional check must put its condition and \"otherwise reply NO_REPLY\" \
in its `prompt`; only such a job can skip a run.\n\
Agent jobs must be scheduled at least 5 minutes apart; a tighter cron expression or \
every_ms is rejected."
}
fn parameters_schema(&self) -> serde_json::Value {
static_schema!(include_str!("parameters/cron_add.json"))
}
fn supports_markdown(&self) -> bool {
true
}
fn permission_level(&self) -> PermissionLevel {
// Scheduling a job persists a command or agent prompt that will
// execute on the host. Treat it as Execute so channel-level
// permission caps are honoured and the approval gate is consulted.
PermissionLevel::Execute
}
fn external_effect(&self) -> bool {
// Creating a cron job is a durable, persistent side-effect: the
// scheduler will later run the stored command or agent prompt on the
// host. Marking this true ensures ApprovalGate::intercept is called
// before the job is written to disk, even when the turn originated
// from an inbound channel message (GHSA-f46p-6vf9-64mm).
true
}
fn external_effect_with_args(&self, args: &serde_json::Value) -> bool {
// An agent job that replies only into the channel conversation that
// asked for it needs no approval: the asker is the sole recipient and
// its runs stay gated as that channel's turns. Everything else keeps
// the unconditional gate above.
// The trait predicate carries no run context, so it reads the calling
// task's turn scope.
!current_turn_may_skip_approval(
args,
crate::core::runtime::DispatchCtx::ambient_turn()
.turn_origin()
.as_ref(),
)
}
async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult> {
self.execute_with_options(args, ToolCallOptions::default())
.await
}
async fn execute_with_options(
&self,
args: serde_json::Value,
options: ToolCallOptions,
) -> anyhow::Result<ToolResult> {
self.execute_with_context(args, options, None).await
}
async fn execute_with_context(
&self,
args: serde_json::Value,
options: ToolCallOptions,
tool_context: Option<&dyn tinytools::ToolRunContext>,
) -> anyhow::Result<ToolResult> {
let origin =
crate::agent::tinyagents::host::run_context::turn_origin_for_tool(tool_context);
if !self.config.cron.enabled {
return Ok(ToolResult::error(
"cron is disabled by config (cron.enabled=false)".to_string(),
));
}
let schedule = match args.get("schedule") {
Some(v) => match serde_json::from_value::<Schedule>(v.clone()) {
Ok(schedule) => schedule,
Err(e) => {
return Ok(ToolResult::error(format!("Invalid schedule: {e}")));
}
},
None => {
return Ok(ToolResult::error(
"Missing 'schedule' parameter".to_string(),
));
}
};
let name = args
.get("name")
.and_then(serde_json::Value::as_str)
.map(str::to_string)
.or_else(|| {
// Derive a name from the prompt so cron jobs are never unnamed.
args.get("prompt")
.and_then(serde_json::Value::as_str)
.map(|p| {
let slug: String = p
.chars()
.map(|c| {
if c.is_alphanumeric() {
c.to_ascii_lowercase()
} else {
'_'
}
})
.take(48)
.collect();
slug.trim_matches('_').to_string()
})
.filter(|s| !s.is_empty())
});
let job_type = match args.get("job_type").and_then(serde_json::Value::as_str) {
Some("agent") => JobType::Agent,
Some("shell") => JobType::Shell,
Some(other) => {
return Ok(ToolResult::error(format!("Invalid job_type: {other}")));
}
None => {
if args.get("prompt").is_some() {
JobType::Agent
} else {
JobType::Shell
}
}
};
let default_delete_after_run = matches!(schedule, Schedule::At { .. });
let delete_after_run = args
.get("delete_after_run")
.and_then(serde_json::Value::as_bool)
.unwrap_or(default_delete_after_run);
let result = match job_type {
JobType::Shell => {
let command = match args.get("command").and_then(serde_json::Value::as_str) {
Some(command) if !command.trim().is_empty() => command,
_ => {
return Ok(ToolResult::error(
"Missing 'command' for shell job".to_string(),
));
}
};
if let Err(reason) = super::super::scheduler::shell_job::authorize_shell_command(
&self.config,
&self.security,
command,
)
.await
{
return Ok(ToolResult::error(reason));
}
cron::add_shell_job(&self.config, name, schedule, command)
}
JobType::Agent => {
let prompt = match args.get("prompt").and_then(serde_json::Value::as_str) {
Some(prompt) if !prompt.trim().is_empty() => prompt,
_ => {
return Ok(ToolResult::error(
"Missing 'prompt' for agent job".to_string(),
));
}
};
let session_target = match args.get("session_target") {
Some(v) => match serde_json::from_value::<SessionTarget>(v.clone()) {
Ok(target) => Some(target),
Err(e) => {
return Ok(ToolResult::error(format!("Invalid session_target: {e}")));
}
},
None => None,
};
let model = args
.get("model")
.and_then(serde_json::Value::as_str)
.map(str::to_string);
let delivery = match args.get("delivery") {
Some(v) => match serde_json::from_value::<DeliveryConfig>(v.clone()) {
Ok(cfg) => Some(cfg),
Err(e) => {
return Ok(ToolResult::error(format!("Invalid delivery config: {e}")));
}
},
None => None,
};
create_agent_job(
&self.config,
AgentJobInput {
name,
schedule,
prompt: prompt.to_string(),
session_target,
model,
delivery,
delete_after_run,
},
current_job_origin(origin.as_ref()),
)
.map_err(anyhow::Error::msg)
}
// `job_type` above is derived only from `Some("agent")`/`Some("shell")`/
// the `prompt`-presence heuristic, so this arm is unreachable in
// practice — `JobType::Flow` rows are created internally by
// `flows::ops::flows_set_enabled` (via `cron::add_flow_schedule_job`),
// never through this agent-facing tool. Kept as an explicit error
// (not `unreachable!()`) so a future change to the heuristic above
// fails loudly with a clear message instead of panicking.
JobType::Flow => Err(anyhow::anyhow!(
"flow-type cron jobs are managed by the Workflows feature and cannot be \
created via cron_add"
)),
};
match result {
Ok(job) => {
let payload = json!({
"id": job.id,
"name": job.name,
"job_type": job.job_type,
"schedule": job.schedule,
"next_run": job.next_run,
"enabled": job.enabled,
"session_target": job.session_target,
"delivery_mode": job.delivery.mode
});
let mut tr = ToolResult::success(serde_json::to_string_pretty(&payload)?);
if options.prefer_markdown {
let md = format!(
"Created cron job **{}** (`{}`).\n- **next_run**: {}\n- **enabled**: {}",
job.name.as_deref().unwrap_or(&job.id),
job.id,
job.next_run.format("%Y-%m-%d %H:%M:%S UTC"),
job.enabled,
);
tr.markdown_formatted = Some(md);
}
Ok(tr)
}
Err(e) => Ok(ToolResult::error(e.to_string())),
}
}
}
#[cfg(test)]
#[path = "add_tests.rs"]
mod tests;
#[cfg(test)]
#[path = "add_schema_tests.rs"]
mod schema_tests;