feat: add /loop slash command with session-scoped cron scheduler

Adds three new slash commands backed by a lightweight CronScheduler:

- /loop [interval] <prompt> [every <interval>] — schedule a recurring
  prompt at a given interval (e.g. /loop 5m check the deployment)
- /cron-list — list all active scheduled tasks with next-fire countdown
- /cron-cancel <id> — cancel a scheduled task by ID

CronScheduler design:
- std::sync::Mutex inner state for sync access from command handlers
- Background tokio task ticks every 1s, holds Weak<CronScheduler> so
  it exits automatically when the session is dropped
- Fires prompts via tokio::sync::mpsc::UnboundedSender<ScheduledFire>
- AgentSession drains the channel after each send() call and runs fired
  prompts via Box::pin(self.send(...)) to break the recursive future size
- AtomicBool guard prevents nested cron processing

Interval syntax:
- Leading: /loop 5m check the build
- Trailing every-clause: /loop check the build every 2h
- No interval: defaults to 10 minutes

Features:
- Deterministic jitter: 0-10% of period (capped at 15 min), derived
  from task ID hash to avoid thundering herd
- Max 50 tasks per session; recurring tasks auto-expire after 3 days
- Supported units: s, m, h, d
- 11 new unit tests in scheduler.rs

Adds 1500 → 1500 passing tests (11 new in scheduler module).

Author: RoyLin

Cargo.lock

@@ -251,6 +251,9 @@ Interactive session commands dispatched before the LLM. Custom commands via the
 | `/history` | Show conversation turn count and token stats |
 | `/tools` | List registered tools |
 | `/mcp` | List connected MCP servers and their tools |
+| `/loop [interval] <prompt>` | Schedule a recurring prompt (e.g., `/loop 5m check build`) |
+| `/cron-list` | List all scheduled recurring prompts |
+| `/cron-cancel <id>` | Cancel a scheduled task by ID |
 
 ```rust
 use a3s_code_core::commands::{SlashCommand, CommandContext, CommandOutput};

README.md

@@ -17,7 +17,9 @@
 //! ```
 
 use crate::agent::{AgentConfig, AgentEvent, AgentLoop, AgentResult};
-use crate::commands::{CommandContext, CommandRegistry};
+use crate::commands::{
+    CommandContext, CommandRegistry, CronCancelCommand, CronListCommand, LoopCommand,
+};
 use crate::config::CodeConfig;
 use crate::error::{read_or_recover, write_or_recover, Result};
 use crate::llm::{LlmClient, Message};
@@ -26,12 +28,14 @@ use crate::queue::{
     ExternalTask, ExternalTaskResult, LaneHandlerConfig, SessionLane, SessionQueueConfig,
     SessionQueueStats,
 };
+use crate::scheduler::{CronScheduler, ScheduledFire};
 use crate::session_lane_queue::SessionLaneQueue;
 use crate::tools::{ToolContext, ToolExecutor};
 use a3s_lane::{DeadLetter, MetricsSnapshot};
 use a3s_memory::{FileMemoryStore, MemoryStore};
 use anyhow::Context;
 use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, RwLock};
 use tokio::sync::{broadcast, mpsc};
 use tokio::task::JoinHandle;
@@ -1197,6 +1201,20 @@ impl Agent {
             None
         };
 
+        // Build the cron scheduler and register scheduler-backed commands.
+        let (cron_scheduler, cron_rx) = CronScheduler::new();
+        CronScheduler::start(Arc::clone(&cron_scheduler));
+        let mut command_registry = CommandRegistry::new();
+        command_registry.register(Arc::new(LoopCommand {
+            scheduler: Arc::clone(&cron_scheduler),
+        }));
+        command_registry.register(Arc::new(CronListCommand {
+            scheduler: Arc::clone(&cron_scheduler),
+        }));
+        command_registry.register(Arc::new(CronCancelCommand {
+            scheduler: Arc::clone(&cron_scheduler),
+        }));
+
         Ok(AgentSession {
             llm_client,
             tool_executor,
@@ -1211,7 +1229,7 @@ impl Agent {
             auto_save: opts.auto_save,
             hook_engine: Arc::new(crate::hooks::HookEngine::new()),
             init_warning,
-            command_registry: CommandRegistry::new(),
+            command_registry,
             model_name: opts
                 .model
                 .clone()
@@ -1222,6 +1240,9 @@ impl Agent {
                 .clone()
                 .or_else(|| self.global_mcp.clone())
                 .unwrap_or_else(|| Arc::new(crate::mcp::manager::McpManager::new())),
+            cron_scheduler,
+            cron_rx: tokio::sync::Mutex::new(cron_rx),
+            is_processing_cron: AtomicBool::new(false),
         })
     }
 }
@@ -1262,6 +1283,12 @@ pub struct AgentSession {
     model_name: String,
     /// Shared MCP manager — all add_mcp_server / remove_mcp_server calls go here.
     mcp_manager: Arc<crate::mcp::manager::McpManager>,
+    /// Session-scoped prompt scheduler (backs /loop, /cron-list, /cron-cancel).
+    cron_scheduler: Arc<CronScheduler>,
+    /// Receiver for scheduled prompt fires; drained after each `send()`.
+    cron_rx: tokio::sync::Mutex<mpsc::UnboundedReceiver<ScheduledFire>>,
+    /// Guard: prevents nested cron processing when a scheduled prompt itself calls send().
+    is_processing_cron: AtomicBool,
 }
 
 impl std::fmt::Debug for AgentSession {
@@ -1340,6 +1367,11 @@ impl AgentSession {
         self.command_registry.register(cmd);
     }
 
+    /// Access the session's cron scheduler (backs `/loop`, `/cron-list`, `/cron-cancel`).
+    pub fn cron_scheduler(&self) -> &Arc<CronScheduler> {
+        &self.cron_scheduler
+    }
+
     /// Send a prompt and wait for the complete response.
     ///
     /// When `history` is `None`, uses (and auto-updates) the session's
@@ -1390,6 +1422,34 @@ impl AgentSession {
             }
         }
 
+        // Drain scheduled prompt fires.
+        // The `is_processing_cron` guard prevents recursive processing when a
+        // cron-fired prompt itself calls send() (which would otherwise try to
+        // drain again on return).
+        if !self.is_processing_cron.swap(true, Ordering::Relaxed) {
+            let fires = {
+                let mut rx = self.cron_rx.lock().await;
+                let mut fires: Vec<ScheduledFire> = Vec::new();
+                while let Ok(fire) = rx.try_recv() {
+                    fires.push(fire);
+                }
+                fires
+            };
+            for fire in fires {
+                tracing::debug!(
+                    task_id = %fire.task_id,
+                    "Firing scheduled cron task"
+                );
+                if let Err(e) = Box::pin(self.send(&fire.prompt, None)).await {
+                    tracing::warn!(
+                        task_id = %fire.task_id,
+                        "Scheduled task failed: {e}"
+                    );
+                }
+            }
+            self.is_processing_cron.store(false, Ordering::Relaxed);
+        }
+
         Ok(result)
     }
 

core/src/agent_api.rs

@@ -16,6 +16,9 @@
 //! | `/history` | Show conversation turn count and token stats |
 //! | `/tools` | List registered tools |
 //! | `/mcp` | List connected MCP servers and their tools |
+//! | `/loop` | Schedule a recurring prompt |
+//! | `/cron-list` | List all scheduled recurring prompts |
+//! | `/cron-cancel` | Cancel a scheduled task by ID |
 //!
 //! ## Custom Commands
 //!
@@ -33,6 +36,7 @@
 //! }
 //! ```
 
+use crate::scheduler::{format_duration, parse_loop_args, CronScheduler};
 use std::collections::HashMap;
 use std::sync::Arc;
 
@@ -411,6 +415,129 @@ impl SlashCommand for McpCommand {
     }
 }
 
+// ─── Scheduler-backed Commands ───────────────────────────────────────────────
+//
+// These commands require a shared `Arc<CronScheduler>` and are registered by
+// `AgentSession::build_session()` after the scheduler is created, NOT by
+// `CommandRegistry::new()`.
+
+/// `/loop` — Schedule a recurring prompt.
+///
+/// Syntax (all equivalent):
+/// - `/loop 5m check the deployment`
+/// - `/loop check the deployment every 5m`
+/// - `/loop check the deployment`  (defaults to every 10 minutes)
+pub struct LoopCommand {
+    pub scheduler: Arc<CronScheduler>,
+}
+
+impl SlashCommand for LoopCommand {
+    fn name(&self) -> &str {
+        "loop"
+    }
+    fn description(&self) -> &str {
+        "Schedule a recurring prompt at a given interval"
+    }
+    fn usage(&self) -> Option<&str> {
+        Some("/loop [interval] <prompt> [every <interval>]")
+    }
+    fn execute(&self, args: &str, _ctx: &CommandContext) -> CommandOutput {
+        let args = args.trim();
+        if args.is_empty() {
+            return CommandOutput::text(concat!(
+                "Usage: /loop [interval] <prompt> [every <interval>]\n\n",
+                "Examples:\n",
+                "  /loop 5m check the deployment status\n",
+                "  /loop monitor memory usage every 2h\n",
+                "  /loop check the build   (defaults to every 10m)\n\n",
+                "Supported units: s (seconds), m (minutes), h (hours), d (days)",
+            ));
+        }
+        let (interval, prompt) = parse_loop_args(args);
+        match self.scheduler.create_task(prompt.clone(), interval, true) {
+            Ok(id) => CommandOutput::text(format!(
+                "Scheduled [{id}]: \"{prompt}\" — fires every {}",
+                format_duration(interval.as_secs())
+            )),
+            Err(e) => CommandOutput::text(format!("Error: {e}")),
+        }
+    }
+}
+
+/// `/cron-list` — List all active scheduled tasks.
+pub struct CronListCommand {
+    pub scheduler: Arc<CronScheduler>,
+}
+
+impl SlashCommand for CronListCommand {
+    fn name(&self) -> &str {
+        "cron-list"
+    }
+    fn description(&self) -> &str {
+        "List all scheduled recurring prompts"
+    }
+    fn execute(&self, _args: &str, _ctx: &CommandContext) -> CommandOutput {
+        let tasks = self.scheduler.list_tasks();
+        if tasks.is_empty() {
+            return CommandOutput::text(
+                "No scheduled tasks. Use /loop to schedule a recurring prompt.",
+            );
+        }
+        let mut out = format!("Scheduled tasks ({}):\n", tasks.len());
+        for t in &tasks {
+            let next = format_duration(t.next_fire_in_secs);
+            let cadence = if t.recurring {
+                format!("every {}", format_duration(t.interval_secs))
+            } else {
+                "once".to_string()
+            };
+            let preview = if t.prompt.len() > 60 {
+                format!("{}…", &t.prompt[..60])
+            } else {
+                t.prompt.clone()
+            };
+            out.push_str(&format!(
+                "  [{id}] {cadence} — fires in {next} (×{fires}) — \"{preview}\"\n",
+                id = t.id,
+                fires = t.fire_count,
+            ));
+        }
+        CommandOutput::text(out.trim_end().to_string())
+    }
+}
+
+/// `/cron-cancel <id>` — Cancel a scheduled task.
+pub struct CronCancelCommand {
+    pub scheduler: Arc<CronScheduler>,
+}
+
+impl SlashCommand for CronCancelCommand {
+    fn name(&self) -> &str {
+        "cron-cancel"
+    }
+    fn description(&self) -> &str {
+        "Cancel a scheduled task by ID"
+    }
+    fn usage(&self) -> Option<&str> {
+        Some("/cron-cancel <task-id>")
+    }
+    fn execute(&self, args: &str, _ctx: &CommandContext) -> CommandOutput {
+        let id = args.trim();
+        if id.is_empty() {
+            return CommandOutput::text(
+                "Usage: /cron-cancel <task-id>\nUse /cron-list to see active task IDs.",
+            );
+        }
+        if self.scheduler.cancel_task(id) {
+            CommandOutput::text(format!("Cancelled task [{id}]"))
+        } else {
+            CommandOutput::text(format!(
+                "No task found with ID [{id}]. Use /cron-list to see active tasks."
+            ))
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

core/src/commands.rs

@@ -73,6 +73,7 @@ pub(crate) mod prompts;
 pub mod queue;
 pub(crate) mod retry;
 pub mod sandbox;
+pub mod scheduler;
 pub mod security;
 pub mod session;
 pub mod session_lane_queue;
@@ -93,7 +94,10 @@ pub use agent_teams::{
     AgentExecutor, AgentTeam, TeamConfig, TeamMember, TeamMemberOptions, TeamMessage, TeamRole,
     TeamRunResult, TeamRunner, TeamTaskBoard,
 };
-pub use commands::{CommandAction, CommandContext, CommandOutput, CommandRegistry, SlashCommand};
+pub use commands::{
+    CommandAction, CommandContext, CommandOutput, CommandRegistry, CronCancelCommand,
+    CronListCommand, LoopCommand, SlashCommand,
+};
 pub use config::{CodeConfig, ModelConfig, ModelCost, ModelLimit, ModelModalities, ProviderConfig};
 pub use error::{CodeError, Result};
 pub use hooks::HookEngine;
@@ -108,6 +112,7 @@ pub use queue::{
     SessionQueueConfig, SessionQueueStats, TaskHandlerMode,
 };
 pub use sandbox::SandboxConfig;
+pub use scheduler::{CronScheduler, ScheduledFire, ScheduledTask, ScheduledTaskInfo};
 pub use session::{SessionConfig, SessionManager, SessionState};
 pub use session_lane_queue::SessionLaneQueue;
 pub use skills::{builtin_skills, Skill, SkillKind};