feat: add /loop slash command, cron scheduler, and SDK scheduled task APIs (v1.2.2)

- Add CronScheduler: session-scoped recurring prompt scheduler with lazy-start
  background ticker (no reactor required at session creation time)
- Add /loop, /cron-list, /cron-cancel slash commands
- Expose listCommands / list_commands in Node.js and Python SDKs
- Expose scheduleTask / schedule_task (programmatic scheduler API) in SDKs
- Expose listScheduledTasks / list_scheduled_tasks in SDKs
- Expose cancelScheduledTask / cancel_scheduled_task in SDKs
- Add register_command in Python SDK for custom slash command handlers
- Add test_loop_commands.py and test_loop_commands.ts integration examples
- Update docs and README: test count 1458->1500, slash commands and scheduled
  tasks sections in sessions.mdx (en + cn)

Author: RoyLin

README.md

@@ -11,7 +11,7 @@ let result = session.send("Refactor auth to use JWT").await?;
 [![Crates.io](https://img.shields.io/crates/v/a3s-code-core.svg)](https://crates.io/crates/a3s-code-core)
 [![Documentation](https://docs.rs/a3s-code-core/badge.svg)](https://docs.rs/a3s-code-core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-[![Tests](https://img.shields.io/badge/tests-1458%20passing-brightgreen.svg)](./core/tests)
+[![Tests](https://img.shields.io/badge/tests-1500%20passing-brightgreen.svg)](./core/tests)
 
 ---
 
@@ -255,6 +255,38 @@ Interactive session commands dispatched before the LLM. Custom commands via the
 | `/cron-list` | List all scheduled recurring prompts |
 | `/cron-cancel <id>` | Cancel a scheduled task by ID |
 
+### Programmatic Scheduler API (SDK)
+
+```typescript
+// TypeScript
+const commands = session.listCommands();   // CommandInfo[]
+
+const taskId = session.scheduleTask('check deployment status', 30);   // every 30s
+const tasks  = session.listScheduledTasks();   // ScheduledTaskInfo[]
+const ok     = session.cancelScheduledTask(taskId);   // boolean
+
+// Also via slash commands:
+await session.send('/loop 5m summarize recent commits');
+await session.send('/cron-list');
+await session.send(`/cron-cancel ${taskId}`);
+```
+
+```python
+# Python
+commands = session.list_commands()   # list[dict] — name, description, usage
+session.register_command("status", "Show session status",
+    lambda args, ctx: f"Model: {ctx['model']}, History: {ctx['history_len']} msgs")
+
+task_id = session.schedule_task("check deployment status", 30)   # every 30s
+tasks   = session.list_scheduled_tasks()   # list[dict] — id, prompt, interval_secs, fire_count, next_fire_in_secs
+ok      = session.cancel_scheduled_task(task_id)   # True
+
+# Also via slash commands:
+session.send("/loop 5m summarize recent commits")
+session.send("/cron-list")
+session.send(f"/cron-cancel {task_id}")
+```
+
 ```rust
 use a3s_code_core::commands::{SlashCommand, CommandContext, CommandOutput};
 
@@ -947,7 +979,8 @@ SessionOptions::new().with_security_provider(Arc::new(MyProvider))
 
 ```
 Agent (config-driven)
-  ├── CommandRegistry (slash commands: /help, /cost, /model, /clear, ...)
+  ├── CommandRegistry (slash commands: /help, /model, /loop, /cron-list, /cron-cancel, ...)
+  │     └── CronScheduler (session-scoped recurring prompts, lazy-start background ticker)
   └── AgentSession (workspace-bound)
         ├── AgentLoop (core execution engine)
         │     ├── ToolExecutor (13 built-in tools, batch parallel execution)
@@ -1082,6 +1115,10 @@ let id = session.session_id();
 // Slash commands
 session.register_command(Arc::new(MyCommand));
 let registry = session.command_registry();
+for (name, desc, usage) in registry.list_full() { ... }
+
+// Scheduled tasks (programmatic)
+// (Use /loop, /cron-list, /cron-cancel slash commands from send() — or via SDK:)
 
 // Skills (dynamic load by name — must be a built-in or loaded from skill_dirs)
 session.load_skill("delegate-task");
@@ -1220,9 +1257,24 @@ result = session.tool("git_worktree", {"command": "list"})
 session.remember_success("task", ["tool"], "result")
 items = session.recall_similar("auth", 5)
 
+# Slash commands
+commands = session.list_commands()   # list[dict] — name, description, usage
+session.register_command("status", "Show session status",
+    lambda args, ctx: f"Model: {ctx['model']}, History: {ctx['history_len']} msgs")
+result = session.send("/status")
+
 # Hooks
 session.register_hook("audit", "pre_tool_use", handler_fn)
 
+# Scheduled tasks (programmatic)
+task_id = session.schedule_task("check deployment status", 30)   # every 30s
+tasks   = session.list_scheduled_tasks()   # list[dict] — id, prompt, interval_secs, fire_count, next_fire_in_secs
+ok      = session.cancel_scheduled_task(task_id)   # True
+# Also via slash commands:
+session.send("/loop 5m summarize recent commits")
+session.send("/cron-list")
+session.send(f"/cron-cancel {task_id}")
+
 # MCP management
 count  = session.add_mcp_server("filesystem", command="npx", args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"])
 status = session.mcp_status()        # {name: {connected, tool_count, error}}
@@ -1313,6 +1365,18 @@ const items = await session.recallSimilar('auth', 5);
 // Hooks
 session.registerHook('audit', 'pre_tool_use', handlerFn);
 
+// Slash commands
+const commands = session.listCommands();   // CommandInfo[]
+
+// Scheduled tasks (programmatic)
+const taskId = session.scheduleTask('check deployment status', 30);   // every 30s
+const tasks  = session.listScheduledTasks();   // ScheduledTaskInfo[]
+const ok     = session.cancelScheduledTask(taskId);   // boolean
+// Also via slash commands:
+await session.send('/loop 5m summarize recent commits');
+await session.send('/cron-list');
+await session.send(`/cron-cancel ${taskId}`);
+
 // MCP management
 const count  = await session.addMcpServer('filesystem', 'stdio', 'npx', ['-y', '@modelcontextprotocol/server-filesystem', '/tmp']);
 const status = await session.mcpStatus();   // McpServerStatusEntry[]
@@ -1384,6 +1448,8 @@ cargo run --example 02_streaming
 | Node.js | `sdk/node/examples/test_run_team_kimi.ts` | Orchestrator.runTeam() with AgentSlot array (Lead/Worker/Reviewer) |
 | Node.js | `sdk/node/examples/test_run_team_tool.ts` | `run_team` built-in tool via session.tool() + LLM-driven |
 | Node.js | `sdk/node/examples/test_run_team_tool_kimi.ts` | `run_team` tool smoke test with external LLM |
+| Python | `sdk/python/examples/test_loop_commands.py` | Slash commands: /loop, /cron-list, /cron-cancel, list_commands, register_command, schedule_task |
+| Node.js | `sdk/node/examples/test_loop_commands.ts` | Slash commands: /loop, /cron-list, /cron-cancel, listCommands, scheduleTask |
 
 ### Integration & Feature Tests
 
@@ -1412,7 +1478,7 @@ cargo test          # All tests
 cargo test --lib    # Unit tests only
 ```
 
-**Test Coverage:** 1458 tests, 100% pass rate
+**Test Coverage:** 1500 tests, 100% pass rate
 
 ---
 

core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "a3s-code-core"
-version = "1.2.1"
+version = "1.2.2"
 edition = "2021"
 authors = ["A3S Lab Team"]
 license = "MIT"

core/src/agent_api.rs

@@ -1202,8 +1202,9 @@ impl Agent {
         };
 
         // Build the cron scheduler and register scheduler-backed commands.
+        // The background ticker is started lazily on the first send() call
+        // to ensure tokio::spawn is called from within an async context.
         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),
@@ -1243,6 +1244,7 @@ impl Agent {
             cron_scheduler,
             cron_rx: tokio::sync::Mutex::new(cron_rx),
             is_processing_cron: AtomicBool::new(false),
+            cron_started: AtomicBool::new(false),
         })
     }
 }
@@ -1290,6 +1292,10 @@ pub struct AgentSession {
     cron_rx: tokio::sync::Mutex<mpsc::UnboundedReceiver<ScheduledFire>>,
     /// Guard: prevents nested cron processing when a scheduled prompt itself calls send().
     is_processing_cron: AtomicBool,
+    /// Whether the background cron ticker has been started.
+    /// The ticker is started lazily on the first `send()` call so that
+    /// `tokio::spawn` is always called from within an async runtime context.
+    cron_started: AtomicBool,
 }
 
 impl std::fmt::Debug for AgentSession {
@@ -1382,6 +1388,16 @@ impl AgentSession {
         &self.cron_scheduler
     }
 
+    /// Start the background cron ticker if it hasn't been started yet.
+    ///
+    /// Must be called from within an async context (inside `tokio::spawn` or
+    /// equivalent) so that `tokio::spawn` inside `CronScheduler::start` succeeds.
+    fn ensure_cron_started(&self) {
+        if !self.cron_started.swap(true, Ordering::Relaxed) {
+            CronScheduler::start(Arc::clone(&self.cron_scheduler));
+        }
+    }
+
     /// Send a prompt and wait for the complete response.
     ///
     /// When `history` is `None`, uses (and auto-updates) the session's
@@ -1391,6 +1407,10 @@ impl AgentSession {
     /// If the prompt starts with `/`, it is dispatched as a slash command
     /// and the result is returned without calling the LLM.
     pub async fn send(&self, prompt: &str, history: Option<&[Message]>) -> Result<AgentResult> {
+        // Lazily start the cron background ticker on the first send() — we are
+        // guaranteed to be inside a tokio async context here.
+        self.ensure_cron_started();
+
         // Slash command interception
         if CommandRegistry::is_command(prompt) {
             let ctx = self.build_command_context();
@@ -1541,6 +1561,8 @@ impl AgentSession {
         prompt: &str,
         history: Option<&[Message]>,
     ) -> Result<(mpsc::Receiver<AgentEvent>, JoinHandle<()>)> {
+        self.ensure_cron_started();
+
         // Slash command interception for streaming
         if CommandRegistry::is_command(prompt) {
             let ctx = self.build_command_context();

sdk/node/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "a3s-code-node"
-version = "1.2.1"
+version = "1.2.2"
 edition = "2021"
 authors = ["A3S Lab Team"]
 license = "MIT"

sdk/node/examples/test_loop_commands.ts

@@ -0,0 +1,134 @@
+/**
+ * Test /loop and related slash commands via Node.js SDK.
+ * Uses the kimi model from ~/.a3s/config.hcl.
+ */
+
+import { Agent } from "@a3s-lab/code";
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { fileURLToPath } from "url";
+import { dirname } from "path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function findConfig(): string {
+  const candidates = [
+    join(homedir(), ".a3s", "config.hcl"),
+    join(__dirname, "..", "..", "..", "..", "..", ".a3s", "config.hcl"),
+  ];
+  for (const p of candidates) {
+    if (existsSync(p)) return p;
+  }
+  throw new Error(`config.hcl not found in: ${candidates.join(", ")}`);
+}
+
+const CONFIG_PATH = findConfig();
+
+function sep(title: string) {
+  console.log("=".repeat(60));
+  console.log(title);
+  console.log("=".repeat(60));
+}
+
+async function main() {
+  console.log(`Config: ${CONFIG_PATH}\n`);
+
+  const agent = await Agent.create(CONFIG_PATH);
+  const session = agent.session("/tmp/test-loop-node");
+
+  // ── 1. listCommands() ──────────────────────────────────────────
+  sep("1. listCommands() — all registered slash commands");
+  const commands = session.listCommands();
+  for (const cmd of commands) {
+    const usage = cmd.usage ? `  usage: ${cmd.usage}` : "";
+    console.log(`  /${cmd.name.padEnd(15)} ${cmd.description}${usage}`);
+  }
+  console.log();
+
+  // ── 2. /help via send() ────────────────────────────────────────
+  sep("2. /help via send()");
+  {
+    const r = await session.send("/help");
+    console.log(r.text);
+  }
+  console.log();
+
+  // ── 3. /loop via send() ────────────────────────────────────────
+  sep("3. /loop via send() — schedule a 10-second recurring prompt");
+  {
+    const r = await session.send("/loop 10s say 'tick' and report the time");
+    console.log(r.text);
+  }
+  console.log();
+
+  // ── 4. scheduleTask() — programmatic API ──────────────────────
+  sep("4. scheduleTask() — programmatic API (15s interval)");
+  const taskId = session.scheduleTask("print current working directory", 15);
+  console.log(`Scheduled task ID: ${taskId}`);
+  console.log();
+
+  // ── 5. listScheduledTasks() + /cron-list ──────────────────────
+  sep("5. listScheduledTasks() + /cron-list");
+  const tasks = session.listScheduledTasks();
+  console.log(`Active tasks: ${tasks.length}`);
+  for (const t of tasks) {
+    console.log(
+      `  [${t.id}] every ${t.intervalSecs}s — fires in ${t.nextFireInSecs}s — "${t.prompt.slice(0, 50)}"`
+    );
+  }
+  console.log();
+  {
+    const r = await session.send("/cron-list");
+    console.log("/cron-list output:");
+    console.log(r.text);
+  }
+  console.log();
+
+  // ── 6. Real LLM turn (exercises cron drain path) ──────────────
+  sep("6. Real LLM turn — exercises cron drain path");
+  {
+    const r = await session.send("Say hello in one sentence.");
+    console.log(`LLM: ${r.text.slice(0, 200)}`);
+  }
+  console.log();
+
+  // ── 7. /model + /cost + /history (other slash commands) ───────
+  sep("7. Other slash commands: /model, /cost, /history");
+  for (const cmd of ["/model", "/cost", "/history"]) {
+    const r = await session.send(cmd);
+    console.log(`${cmd}: ${r.text.split("\n")[0]}`);
+  }
+  console.log();
+
+  // ── 8. cancelScheduledTask() + /cron-cancel ───────────────────
+  sep("8. cancelScheduledTask() + /cron-cancel");
+  const cancelled = session.cancelScheduledTask(taskId);
+  console.log(`cancelScheduledTask(${taskId}): ${cancelled}`);
+
+  const remaining = session.listScheduledTasks();
+  if (remaining.length > 0) {
+    const loopId = remaining[0].id;
+    const r = await session.send(`/cron-cancel ${loopId}`);
+    console.log(`/cron-cancel ${loopId}: ${r.text}`);
+  }
+  console.log();
+
+  // ── 9. Verify empty ───────────────────────────────────────────
+  sep("9. Verify all tasks cancelled");
+  const tasksAfter = session.listScheduledTasks();
+  console.log(`Remaining tasks: ${tasksAfter.length}`);
+  {
+    const r = await session.send("/cron-list");
+    console.log(r.text);
+  }
+  console.log();
+
+  sep("All tests passed!");
+}
+
+main().catch((e) => {
+  console.error("Test failed:", e);
+  process.exit(1);
+});