Your lightweight open-source personal agent.
Python agent-frameworkai-agentai-agentschatbotchatopsdiscord-botllm-agentsllmslocal-llmmcpmodel-context-protocolmulti-agentopenai-compatibleopenclawpersonal-ai-assistantpythonself-hostedtelegram-bot-ai-assistantwebuiworkflow-automation
feat(cron): expose recent run history to the agent
david-dev6669a9117967e3c
diff --git a/docs/automations.md b/docs/automations.mdindex 5e6c72748..25ee6a24c 100644--- a/docs/automations.md+++ b/docs/automations.md@@ -68,6 +68,12 @@ Ask nanobot to pause a scheduled task instead of removing it. The agent can useDisabling affects future runs. It does not cancel a running task or recall an already queued result. System-managed heartbeat and Dream jobs remain protected; change their configuration instead.+### Inspect Recent Runs++Ask nanobot, "Show the last five runs of my daily report." The agent can use `cron(action="history", job_id="...", limit=5)` to read the retained execution time, status, duration, and error for that task. Results are newest first, using the task's timezone or the runtime default. The default is five records; `limit` accepts 1–20.++This also works for disabled tasks and does not change their schedule or state. Only retained execution records are available: deleted jobs and automatically deleted one-time tasks cannot be queried. Run history does not include the generated reply or confirm message delivery.+### Scheduled Result DeliveryThe gateway saves final scheduled messages before it accepts them into the outgoing queue. This includes explicit `message` calls in existing tasks. Each recipient has a separate delivery record. Progress, reasoning, and streaming events do not enter this queue. WebUI streaming and saved chat history keep their existing behavior. External channels receive a complete scheduled reply instead of a streamed reply. Ordinary chat streaming is unchanged.diff --git a/nanobot/agent/tools/cron.py b/nanobot/agent/tools/cron.pyindex f5b59844a..08139a00f 100644--- a/nanobot/agent/tools/cron.py+++ b/nanobot/agent/tools/cron.py@@ -22,7 +22,9 @@ from nanobot.cron.types import CronJob, CronJobState, CronSchedulefrom nanobot.session.keys import UNIFIED_SESSION_KEY_CRON_PARAMETERS = tool_parameters_schema(- action=StringSchema("Action to perform", enum=["add", "list", "remove", "update", "enable", "disable"]),+ action=StringSchema(+ "Action to perform", enum=["add", "list", "remove", "update", "enable", "disable", "history"]+ ),name=StringSchema("Job label; generated from message for add if omitted."),message=StringSchema("REQUIRED when action='add': non-empty instruction to execute when the job triggers. "@@ -43,9 +45,11 @@ _CRON_PARAMETERS = tool_parameters_schema("Naive values use the tool's default timezone."),job_id=StringSchema(- "REQUIRED when action='remove', 'update', 'enable', or 'disable'. Job ID (obtain via action='list')."+ "REQUIRED when action='remove', 'update', 'enable', 'disable', or 'history'. "+ "Job ID (obtain via action='list')."),include_disabled=BooleanSchema(description="Include disabled jobs when action='list'."),+ limit=IntegerSchema(description="Maximum runs for action='history'; defaults to 5.", minimum=1, maximum=20),required=["action"],description=("add requires exactly one schedule: every_seconds, cron_expr, or at. "@@ -113,7 +117,7 @@ class CronTool(Tool):@propertydef description(self) -> str:return (- "Schedule reminders and recurring tasks. Actions: add, list, remove, update, enable, disable. "+ "Schedule reminders and recurring tasks. Actions: add, list, remove, update, enable, disable, history. "f"New cron schedules and naive ISO times default to {self._default_timezone}. ""Updates retain the existing cron timezone when tz is omitted.")@@ -123,7 +127,7 @@ class CronTool(Tool):action = params.get("action")if action == "add" and not str(params.get("message") or "").strip():errors.append("message is required when action='add'")- if action in {"remove", "update", "enable", "disable"} and not str(params.get("job_id") or "").strip():+ if action in {"remove", "update", "enable", "disable", "history"} and not str(params.get("job_id") or "").strip():errors.append(f"job_id is required when action='{action}'")return errors@@ -138,6 +142,7 @@ class CronTool(Tool):at: str | None = None,job_id: str | None = None,include_disabled: bool = False,+ limit: int = 5,) -> str:if action == "add":request = current_request_context()@@ -152,6 +157,8 @@ class CronTool(Tool):return self._update_job(job_id, name, message, every_seconds, cron_expr, tz, at)elif action in {"enable", "disable"}:return self._set_job_enabled(job_id, enabled=action == "enable")+ elif action == "history":+ return self._job_history(job_id, limit)return f"Unknown action: {action}"def _add_job(@@ -340,6 +347,23 @@ class CronTool(Tool):self._cron.enable_job(job_id, enabled=enabled)return f"{'Enabled' if enabled else 'Disabled'} job {job_id}"+ def _job_history(self, job_id: str | None, limit: int) -> str:+ if not job_id:+ return ToolResult.error("Error: job_id is required for history")+ job = self._cron.get_job(job_id)+ if job is None:+ return ToolResult.error(f"Error: job {job_id} not found")+ if not job.state.run_history:+ return f"No recorded runs for job {job_id}."+ lines = [f"Recent runs for '{job.name}' (id: {job.id}), newest first:"]+ display_tz = self._display_timezone(job.schedule)+ for run in reversed(job.state.run_history[-limit:]):+ timestamp = self._format_timestamp(run.run_at_ms, display_tz)+ lines.append(f"- {timestamp} — {run.status} ({run.duration_ms}ms)")+ if run.error:+ lines.append(f" Error: {run.error}")+ return "\n".join(lines)+def _remove_job(self, job_id: str | None) -> str:if not job_id:return ToolResult.error("Error: job_id is required for remove")diff --git a/nanobot/skills/cron/SKILL.md b/nanobot/skills/cron/SKILL.mdindex bf617bdca..3fb30d37a 100644--- a/nanobot/skills/cron/SKILL.md+++ b/nanobot/skills/cron/SKILL.md@@ -76,3 +76,9 @@ Use `tz` with `cron_expr` to schedule in a specific IANA timezone. New tasks useUse `cron(action="update", job_id="...", cron_expr="0 10 * * *")` to change an existing task. Supply only the fields to change: `name`, `message`, or exactly one of `every_seconds`, `cron_expr`, and `at`. Omitted fields keep their values; empty names and instructions are rejected. A cron edit retains the existing timezone unless `tz` is supplied with `cron_expr`. Naive `at` values use the runtime default timezone.Updates preserve the task ID, linked chat, history, enabled state, and automatic-deletion setting. Changing only the name or instruction does not move the next run. System-managed tasks cannot be edited.++## Run History++Use `cron(action="history", job_id="...", limit=5)` to inspect recent executions, newest first. Each entry includes its time, status, duration in milliseconds, and any error. `job_id` is required; `limit` defaults to 5 and accepts 1–20. Listing jobs still shows only the last run.++History can be inspected for disabled jobs too. The scheduler retains at most 20 runs per job; deleted jobs, including automatically deleted one-time tasks, cannot be queried. This reads execution records, not task output or delivery receipts.diff --git a/tests/cron/test_cron_tool_history.py b/tests/cron/test_cron_tool_history.pynew file mode 100644index 000000000..5c27574e9--- /dev/null+++ b/tests/cron/test_cron_tool_history.py@@ -0,0 +1,97 @@+"""Inspect persisted cron executions through the agent tool."""++from datetime import datetime+from pathlib import Path+from zoneinfo import ZoneInfo++import pytest++from nanobot.agent.tools.cron import CronTool+from nanobot.agent.tools.registry import ToolRegistry+from nanobot.cron import service as cron_service+from nanobot.cron.service import CronJobSkippedError, CronService+from nanobot.cron.types import CronSchedule+++def _registry(service: CronService) -> ToolRegistry:+ registry = ToolRegistry()+ registry.register(CronTool(service))+ return registry+++def _job(service: CronService):+ return service.add_job(+ name="Daily report",+ schedule=CronSchedule(kind="cron", expr="0 9 * * *", tz="America/Denver"),+ message="Check open pull requests",+ session_key="websocket:chat-1", origin_channel="websocket", origin_chat_id="chat-1",+ )+++async def test_history_reads_recent_runs_without_changing_job(tmp_path: Path, monkeypatch) -> None:+ now = 1773673200000+ monkeypatch.setattr(cron_service, "_now_ms", lambda: now)+ outcomes = iter(["ok"] * 5 + ["error", "skipped"])++ async def run(_job):+ nonlocal now+ now += 125+ outcome = next(outcomes)+ if outcome == "error":+ raise RuntimeError("Report failed")+ if outcome == "skipped":+ raise CronJobSkippedError("Chat busy")+ return "Report ready"++ path = tmp_path / "jobs.json"+ service = CronService(path, on_job=run)+ job = _job(service)+ for _ in range(7):+ await service.run_job(job.id, force=True)+ now += 60_000+ service.enable_job(job.id, enabled=False)+ reloaded = CronService(path)+ saved_job = reloaded.get_job(job.id)+ assert saved_job is not None+ before = path.read_bytes()+ registry = _registry(reloaded)++ default = await registry.execute("cron", {"action": "history", "job_id": job.id})+ assert len([line for line in default.splitlines() if line.startswith("- ")]) == 5+ limited = await registry.execute("cron", {"action": "history", "job_id": job.id, "limit": 2})+ assert "Report failed" in limited and "Chat busy" in limited+ assert "125ms" in limited and "America/Denver" in limited+ assert "ok" not in limited+ assert limited.index("skipped") < limited.index("error")+ latest = saved_job.state.run_history[-1]+ timestamp = datetime.fromtimestamp(latest.run_at_ms / 1000, ZoneInfo("America/Denver")).isoformat()+ assert timestamp in limited+ assert path.read_bytes() == before+++async def test_history_reports_no_runs_for_existing_job(tmp_path: Path) -> None:+ service = CronService(tmp_path / "jobs.json")+ job = _job(service)+ result = await _registry(service).execute("cron", {"action": "history", "job_id": job.id})+ assert "No recorded runs" in result+ assert job.id in result+++async def test_history_requires_job_id(tmp_path: Path) -> None:+ result = await _registry(CronService(tmp_path / "jobs.json")).execute("cron", {"action": "history"})+ assert "job_id is required" in result+++async def test_history_reports_unknown_job(tmp_path: Path) -> None:+ result = await _registry(CronService(tmp_path / "jobs.json")).execute(+ "cron", {"action": "history", "job_id": "missing"},+ )+ assert "job missing not found" in result++[email protected]("limit", [0, 21])+async def test_history_validates_limit(tmp_path: Path, limit: int) -> None:+ result = await _registry(CronService(tmp_path / "jobs.json")).execute(+ "cron", {"action": "history", "job_id": "test", "limit": limit},+ )+ assert "limit must be" in result