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
refactor: use cron turn naming internally
chengyongru271b3651d7be
diff --git a/.agent/cron-session-memory.md b/.agent/cron-session-memory.mdindex ecc2ee75a..57f5afc17 100644--- a/.agent/cron-session-memory.md+++ b/.agent/cron-session-memory.md@@ -1,7 +1,7 @@# Cron / Session / Memory Design DecisionsThis note records the agreed design direction for fixing the mismatch between-scheduled automations and chat session memory.+scheduled cron jobs and chat session memory.## Problem@@ -14,7 +14,7 @@ The visible failure mode is awkward: a cron job reports something into a chat,the user discusses it in that chat, and the next cron run behaves as if thatdiscussion never happened.-The fix is not to make cron a separate delivery system. A user automation should+The fix is not to make cron a separate delivery system. A user cron job shouldbe a scheduled input into a session.## Core Model@@ -39,11 +39,11 @@ These fields are legacy-only. New cron creation should not depend on them.Use explicit branching:-- **Bound user automation**: `payload.kind == "agent_turn"`,+- **Bound user cron job**: `payload.kind == "agent_turn"`,`payload.session_key` is present, and no legacy delivery fields(`deliver`, `channel`, `to`, or `channel_meta`) are set. This uses the newsession-turn model.-- **Legacy unbound automation**: user job with no `payload.session_key`. Keep the+- **Legacy unbound cron job**: user job with no `payload.session_key`. Keep theexisting behavior. Do not migrate, infer, bind, or add UI for these jobs inthis change.- **System job**: `payload.kind == "system_event"` or known internal jobs such@@ -54,7 +54,7 @@ The project should not grow a compatibility subsystem for legacy jobs. Missing## New Job Creation-`CronTool` must create user automations with a `session_key`.+`CronTool` must create user cron jobs with a `session_key`.- If no request/session context exists, `cron action=add` should fail.- Do not create new unbound jobs.@@ -66,16 +66,16 @@ The project should not grow a compatibility subsystem for legacy jobs. Missing## Execution Path-Bound user automations should execute through `AgentLoop` as internal inbound+Bound user cron jobs should execute through `AgentLoop` as internal inboundsession events, not as an out-of-band `agent.process_direct()` call.The intended flow is:```text-cron due -> create automation inbound -> AgentLoop dispatches session turn+cron due -> create cron inbound -> AgentLoop dispatches session turn```-The inbound event should carry metadata identifying the automation, such as:+The inbound event should carry metadata identifying the cron run, such as:- job id- job name@@ -93,28 +93,28 @@ to legacy `payload.channel`, `payload.to`, or `payload.channel_meta` for boundjobs. Those fields are only for the legacy unbound path.The scheduler must not mark a bound job run as complete just because the inbound-event was queued. It should either wait for the automation turn to complete and+event was queued. It should either wait for the cron turn to complete andrecord the real outcome, or explicitly model the run as separate states such as-`queued` and `turn_completed`. A failed automation turn must be reflected in the+`queued` and `turn_completed`. A failed cron turn must be reflected in thecron run record/job state, not hidden behind a successful enqueue.## Active Session BehaviorCron must not interrupt an active session turn.-- If the target session is idle, run the automation turn immediately.-- If the target session is running, defer the automation until the current turn+- If the target session is idle, run the cron turn immediately.+- If the target session is running, defer the cron turn until the current turncompletes.-- Do not inject the automation into the active turn's runtime context.-- Do not route automation messages into the existing mid-turn pending injection+- Do not inject the cron turn into the active turn's runtime context.+- Do not route cron messages into the existing mid-turn pending injectionqueue.-- UI/runtime status may show that an automation is queued, but the current LLM- call should not see the queued automation.+- UI/runtime status may show that a cron run is queued, but the current LLM+ call should not see the queued cron turn.-Automation inbound events need explicit metadata, for example-`_automation_trigger` plus `_defer_until_session_idle`. `AgentLoop.run()` must+Cron inbound events need explicit metadata, for example+`_cron_trigger` plus `_cron_defer_until_session_idle`. `AgentLoop.run()` mustrecognize that metadata before the existing `_pending_queues` mid-turn injection-branch. If the session is active, the event goes to a deferred automation queue,+branch. If the session is active, the event goes to a deferred cron queue,not the pending injection queue.The user experience goal is: cron can run after the current answer, but it@@ -124,17 +124,17 @@ should not take over an answer already in progress.Do not persist the raw internal execution prompt as a normal user message.-Instead, persist a readable automation trigger event, for example:+Instead, persist a readable cron trigger event, for example:```json{"role": "user",- "content": "Scheduled automation triggered: daily monitor\n\nCheck ...",- "_automation_turn": true,- "automation_id": "abc123",- "automation_name": "daily monitor",- "automation_run_id": "abc123:1770000000000",- "automation_prompt_ref": {+ "content": "Scheduled cron job triggered: daily monitor\n\nCheck ...",+ "_cron_turn": true,+ "cron_job_id": "abc123",+ "cron_job_name": "daily monitor",+ "cron_run_id": "abc123:1770000000000",+ "cron_prompt_ref": {"id": "cron.agent_turn.reminder","version": 1,"sha256": "..."@@ -160,7 +160,7 @@ Preferred direction:- Move the cron execution prompt out of `commands.py` into a named template.- Use a stable prompt id such as `cron.agent_turn.reminder`.-- Store `prompt_ref` and `automation_run_id` in session history.+- Store `prompt_ref` and `cron_run_id` in session history.- Store the full rendered prompt, prompt variables, and errors in an internalrun record.@@ -169,15 +169,15 @@ cron store grow without bound.## Visibility and Evaluation-A bound user automation is a real session turn.+A bound user cron job is a real session turn.- If it succeeds, save and publish the assistant response.-- Do not pass bound automation responses through `evaluate_response()`.+- Do not pass bound cron responses through `evaluate_response()`.- Keep `evaluate_response()` only for system/legacy paths where the old behaviorstill applies.- Avoid states where session history contains a response the user never saw.-If a bound automation starts executing, it must leave a visible closure in the+If a bound cron job starts executing, it must leave a visible closure in thesession:- success response@@ -189,9 +189,10 @@ the user-facing transcript.## Deleting Sessions-Deleting a session with bound automations should be a two-step operation.+Deleting a session with bound cron jobs should be a two-step operation.-Default delete behavior should block and return the associated automations:+Default delete behavior should block and return the associated cron jobs.+Existing WebUI/API response field names are kept for compatibility:```json{@@ -203,7 +204,7 @@ Default delete behavior should block and return the associated automations:}```-After explicit confirmation, the API may delete the bound user automations and+After explicit confirmation, the API may delete the bound user cron jobs andthen delete the session/thread.Rules:@@ -212,18 +213,18 @@ Rules:session being deleted.- Do not block on system jobs.- Do not block on legacy unbound jobs.-- In unified-session mode, WebUI chats display automations owned by+- In unified-session mode, WebUI chats display cron jobs owned by`unified:default`, but deleting an individual `websocket:*` thread should not- block on or delete those unified automations.+ block on or delete those unified cron jobs.- If the user manually deletes files outside the WebUI/API, do not try tocompensate.## Unified Session Mode-When `unified_session` is enabled, WebUI-created automations should bind to the+When `unified_session` is enabled, WebUI-created cron jobs should bind to thesame unified session as normal WebUI chat turns: `unified:default`.-- All WebUI chats should display automations owned by `unified:default`.+- All WebUI chats should display cron jobs owned by `unified:default`.- Individual WebUI thread deletion should remain scoped to the concrete`websocket:*` thread being deleted.- Toggling `unified_session` does not migrate existing cron jobs. Existing jobs@@ -232,15 +233,15 @@ same unified session as normal WebUI chat turns: `unified:default`.## WebUI Scope-This change should not grow into a full automation manager.+This change should not grow into a global scheduler/task manager.Keep the scope focused:- Fix cron/session/memory semantics for new bound jobs.- Preserve legacy job behavior.-- Add deletion protection for sessions with bound automations.-- Update the existing session automation panel only as needed for the new- bound-job status.+- Add deletion protection for sessions with bound cron jobs.+- Update the existing WebUI panel that lists scheduled jobs only as needed for+ the new bound-job status.Do not add deterministic legacy migration, legacy binding UI, or a globalcalendar/task manager in this change.@@ -258,6 +259,6 @@ execution path that behaves differently from scheduled runs.- No legacy migration.- No automatic binding of legacy jobs.- No runtime-context prompt asking the model to bind jobs.-- No new global automation manager.+- No new global scheduler/task manager.- No new delivery-target abstraction.- No user-visible manual cron run.diff --git a/nanobot/agent/cron_turns.py b/nanobot/agent/cron_turns.pynew file mode 100644index 000000000..54c34095e--- /dev/null+++ b/nanobot/agent/cron_turns.py@@ -0,0 +1,88 @@+"""Coordination for scheduled cron turns."""++from __future__ import annotations++import asyncio+from collections.abc import Awaitable, Callable, Iterable++from nanobot.bus.events import InboundMessage, OutboundMessage+from nanobot.cron.session_turns import cron_run_id, defer_cron_until_session_idle+++class CronTurnCoordinator:+ """Manage scheduled cron turns without mixing them into live injections."""++ def __init__(+ self,+ *,+ publish_inbound: Callable[[InboundMessage], Awaitable[None]],+ dispatch: Callable[[InboundMessage], Awaitable[object]],+ is_running: Callable[[], bool],+ ) -> None:+ self._publish_inbound = publish_inbound+ self._dispatch = dispatch+ self._is_running = is_running+ self.deferred_queues: dict[str, list[InboundMessage]] = {}+ self._waiters: dict[str, asyncio.Future[OutboundMessage | None]] = {}++ async def submit(self, msg: InboundMessage) -> OutboundMessage | None:+ """Submit a scheduled cron turn and wait for its session response."""+ run_id = cron_run_id(msg.metadata)+ if not run_id:+ raise ValueError("cron turn metadata must include a run_id")+ if run_id in self._waiters:+ raise RuntimeError(f"cron run {run_id!r} is already pending")++ loop = asyncio.get_running_loop()+ future: asyncio.Future[OutboundMessage | None] = loop.create_future()+ self._waiters[run_id] = future+ try:+ if self._is_running():+ await self._publish_inbound(msg)+ else:+ await self._dispatch(msg)+ return await future+ finally:+ self._waiters.pop(run_id, None)++ def should_defer(+ self,+ msg: InboundMessage,+ *,+ session_key: str,+ active_session_keys: Iterable[str],+ ) -> bool:+ return (+ defer_cron_until_session_idle(msg.metadata)+ and session_key in active_session_keys+ )++ def complete(+ self,+ msg: InboundMessage,+ *,+ response: OutboundMessage | None = None,+ error: BaseException | None = None,+ ) -> None:+ run_id = cron_run_id(msg.metadata)+ if not run_id:+ return+ future = self._waiters.get(run_id)+ if future is None or future.done():+ return+ if error is not None:+ future.set_exception(error)+ else:+ future.set_result(response)++ def defer(self, session_key: str, msg: InboundMessage) -> None:+ self.deferred_queues.setdefault(session_key, []).append(msg)++ async def publish_next_deferred(self, session_key: str) -> None:+ queue = self.deferred_queues.get(session_key)+ if not queue:+ return+ msg = queue.pop(0)+ if not queue:+ self.deferred_queues.pop(session_key, None)+ await self._publish_inbound(msg)diff --git a/nanobot/agent/loop.py b/nanobot/agent/loop.pyindex 2c1cf2375..fddc8180e 100644--- a/nanobot/agent/loop.py+++ b/nanobot/agent/loop.py@@ -19,6 +19,7 @@ from nanobot.agent import context as agent_contextfrom nanobot.agent import model_presets as preset_helpersfrom nanobot.agent.autocompact import AutoCompactfrom nanobot.agent.context import ContextBuilder+from nanobot.agent.cron_turns import CronTurnCoordinatorfrom nanobot.agent.hook import AgentHook, CompositeHookfrom nanobot.agent.memory import Consolidatorfrom nanobot.agent.progress_hook import AgentProgressHook@@ -39,11 +40,9 @@ from nanobot.bus.runtime_events import ()from nanobot.command import CommandContext, CommandRouter, register_builtin_commandsfrom nanobot.config.schema import AgentDefaults, ModelPresetConfig-from nanobot.cron.automation import (- AUTOMATION_HISTORY_META,- automation_run_id,- automation_trigger,- defer_until_session_idle,+from nanobot.cron.session_turns import (+ CRON_HISTORY_META,+ cron_trigger,)from nanobot.providers.base import LLMProviderfrom nanobot.providers.factory import ProviderSnapshot@@ -306,10 +305,11 @@ class AgentLoop:# When a session has an active task, new messages for that session# are routed here instead of creating a new task.self._pending_queues: dict[str, asyncio.Queue] = {}- # Scheduled automations wait for the current visible turn to finish.- # They must not be injected into the active model call as follow-up text.- self._deferred_automation_queues: dict[str, list[InboundMessage]] = {}- self._automation_waiters: dict[str, asyncio.Future[OutboundMessage | None]] = {}+ self._cron_turns = CronTurnCoordinator(+ publish_inbound=self.bus.publish_inbound,+ dispatch=self._dispatch,+ is_running=lambda: self._running,+ )# NANOBOT_MAX_CONCURRENT_REQUESTS: <=0 means unlimited; default 3._max = int(os.environ.get("NANOBOT_MAX_CONCURRENT_REQUESTS", "3"))self._concurrency_gate: asyncio.Semaphore | None = (@@ -573,54 +573,8 @@ class AgentLoop:def _runtime_events(self) -> RuntimeEventPublisher:return ensure_runtime_event_publisher(self)- async def submit_automation_turn(self, msg: InboundMessage) -> OutboundMessage | None:- """Submit a scheduled automation as an internal session turn and wait for it."""- run_id = automation_run_id(msg.metadata)- if not run_id:- raise ValueError("automation turn metadata must include a run_id")- loop = asyncio.get_running_loop()- future: asyncio.Future[OutboundMessage | None] = loop.create_future()- if run_id in self._automation_waiters:- raise RuntimeError(f"automation run {run_id!r} is already pending")- self._automation_waiters[run_id] = future- try:- if self._running:- await self.bus.publish_inbound(msg)- else:- await self._dispatch(msg)- return await future- finally:- self._automation_waiters.pop(run_id, None)-- def _complete_automation_turn(- self,- msg: InboundMessage,- *,- response: OutboundMessage | None = None,- error: BaseException | None = None,- ) -> None:- run_id = automation_run_id(msg.metadata)- if not run_id:- return- future = self._automation_waiters.get(run_id)- if future is None or future.done():- return- if error is not None:- future.set_exception(error)- else:- future.set_result(response)-- def _defer_automation_turn(self, session_key: str, msg: InboundMessage) -> None:- self._deferred_automation_queues.setdefault(session_key, []).append(msg)-- async def _publish_next_deferred_automation(self, session_key: str) -> None:- queue = self._deferred_automation_queues.get(session_key)- if not queue:- return- msg = queue.pop(0)- if not queue:- self._deferred_automation_queues.pop(session_key, None)- await self.bus.publish_inbound(msg)+ async def submit_cron_turn(self, msg: InboundMessage) -> OutboundMessage | None:+ return await self._cron_turns.submit(msg)def _persist_user_message_early(self,@@ -640,16 +594,16 @@ class AgentLoop:extra: dict[str, Any] = ({"media": list(media_paths)} if media_paths else {}) | agent_context.session_extra(msg.metadata)extra.update(kwargs)text = msg.content if isinstance(msg.content, str) else ""- if trigger := automation_trigger(msg.metadata):+ if trigger := cron_trigger(msg.metadata):persist_content = trigger.get("persist_content")if isinstance(persist_content, str) and persist_content.strip():text = persist_contentextra.update({- AUTOMATION_HISTORY_META: True,- "automation_id": trigger.get("job_id"),- "automation_name": trigger.get("job_name"),- "automation_run_id": trigger.get("run_id"),- "automation_prompt_ref": trigger.get("prompt_ref"),+ CRON_HISTORY_META: True,+ "cron_job_id": trigger.get("job_id"),+ "cron_job_name": trigger.get("job_name"),+ "cron_run_id": trigger.get("run_id"),+ "cron_prompt_ref": trigger.get("prompt_ref"),})session.add_message("user", text, **extra)self._mark_pending_user_turn(session)@@ -951,9 +905,10 @@ class AgentLoop:self.commands.dispatch_priority,)continue- if (- defer_until_session_idle(msg.metadata)- and effective_key in self._pending_queues+ if self._cron_turns.should_defer(+ msg,+ session_key=effective_key,+ active_session_keys=self._pending_queues.keys(),):pending_msg = msgif effective_key != msg.session_key:@@ -961,9 +916,9 @@ class AgentLoop:msg,session_key_override=effective_key,)- self._defer_automation_turn(effective_key, pending_msg)+ self._cron_turns.defer(effective_key, pending_msg)logger.info(- "Deferred automation turn for active session {}",+ "Deferred cron turn for active session {}",effective_key,)continue@@ -1080,9 +1035,9 @@ class AgentLoop:session_key=session_key,metadata=msg.metadata,)- self._complete_automation_turn(msg, response=response)+ self._cron_turns.complete(msg, response=response)except asyncio.CancelledError:- self._complete_automation_turn(+ self._cron_turns.complete(msg,error=asyncio.CancelledError(),)@@ -1124,7 +1079,7 @@ class AgentLoop:session_key=session_key,metadata=msg.metadata,)- self._complete_automation_turn(msg, error=exc)+ self._cron_turns.complete(msg, error=exc)finally:# Drain any messages still in the pending queue and re-publish# them to the bus so they are processed as fresh inbound messages@@ -1155,14 +1110,14 @@ class AgentLoop:msg, session_key, "idle")self._runtime_events().clear_turn(session_key)- await self._publish_next_deferred_automation(session_key)+ await self._cron_turns.publish_next_deferred(session_key)finally:if pending is None:await self._runtime_events().run_status_changed(msg, session_key, "idle")self._runtime_events().clear_turn(session_key)- await self._publish_next_deferred_automation(session_key)+ await self._cron_turns.publish_next_deferred(session_key)async def close_mcp(self) -> None:"""Drain pending background archives, then close MCP connections."""diff --git a/nanobot/agent/tools/cron.py b/nanobot/agent/tools/cron.pyindex b1d3b41e2..07584b71e 100644--- a/nanobot/agent/tools/cron.py+++ b/nanobot/agent/tools/cron.py@@ -71,7 +71,7 @@ class CronTool(Tool, ContextAware):return cls(cron_service=ctx.cron_service, default_timezone=ctx.timezone)def set_context(self, ctx: RequestContext) -> None:- """Set the current session context for scheduled automation ownership."""+ """Set the current session context for scheduled cron job ownership."""self._channel.set(ctx.channel)self._chat_id.set(ctx.chat_id)self._metadata.set(ctx.metadata)@@ -166,7 +166,7 @@ class CronTool(Tool, ContextAware):)session_key = self._session_key.get()if not session_key:- return "Error: scheduled automations must be created from a chat session"+ return "Error: scheduled cron jobs must be created from a chat session"if tz and not cron_expr:return "Error: tz can only be used with cron_expr"if tz:diff --git a/nanobot/cli/commands.py b/nanobot/cli/commands.pyindex 0f48635e2..9de150115 100644--- a/nanobot/cli/commands.py+++ b/nanobot/cli/commands.py@@ -979,12 +979,12 @@ def _run_gateway(from nanobot.bus.queue import MessageBusfrom nanobot.bus.runtime_events import RuntimeEventBusfrom nanobot.channels.manager import ChannelManager- from nanobot.cron.automation import (- AUTOMATION_DEFER_UNTIL_IDLE_META,- AUTOMATION_TRIGGER_META,- is_bound_agent_job,- )from nanobot.cron.service import CronService+ from nanobot.cron.session_turns import (+ CRON_DEFER_UNTIL_IDLE_META,+ CRON_TRIGGER_META,+ is_bound_cron_job,+ )from nanobot.cron.types import CronJobfrom nanobot.providers.factory import build_provider_snapshot, load_provider_snapshotfrom nanobot.providers.image_generation import image_gen_provider_configs@@ -1093,7 +1093,7 @@ def _run_gateway(return channel, rest, metadata- def _automation_prompt_ref(prompt: str) -> dict[str, Any]:+ def _cron_prompt_ref(prompt: str) -> dict[str, Any]:return {"id": "cron.agent_turn.reminder","version": 1,@@ -1110,23 +1110,23 @@ def _run_gateway(strip=True,message=job.payload.message,)- prompt_ref = _automation_prompt_ref(prompt)+ prompt_ref = _cron_prompt_ref(prompt)run_id = f"{job.id}:{int(time.time() * 1000)}:{uuid.uuid4().hex[:8]}"channel, chat_id, metadata = _bound_session_delivery_context(session_key,turn_seed=f"cron:{job.id}",source_label=job.name,)- metadata[AUTOMATION_TRIGGER_META] = {+ metadata[CRON_TRIGGER_META] = {"job_id": job.id,"job_name": job.name,"run_id": run_id,"prompt_ref": prompt_ref,"persist_content": (- f"Scheduled automation triggered: {job.name}\n\n{job.payload.message}"+ f"Scheduled cron job triggered: {job.name}\n\n{job.payload.message}"),}- metadata[AUTOMATION_DEFER_UNTIL_IDLE_META] = True+ metadata[CRON_DEFER_UNTIL_IDLE_META] = Truerun_record_base: dict[str, Any] = {"job_id": job.id,"job_name": job.name,@@ -1149,7 +1149,7 @@ def _run_gateway(if isinstance(cron_tool, CronTool):cron_token = cron_tool.set_cron_context(True)try:- resp = await agent.submit_automation_turn(+ resp = await agent.submit_cron_turn(InboundMessage(channel=channel,sender_id="cron",@@ -1345,7 +1345,7 @@ def _run_gateway(logger.info("Heartbeat: silenced by post-run evaluation")return response- if is_bound_agent_job(job):+ if is_bound_cron_job(job):return await _run_bound_cron_job(job)reminder_note = (diff --git a/nanobot/cron/automation.py b/nanobot/cron/automation.pydeleted file mode 100644index f619870ff..000000000--- a/nanobot/cron/automation.py+++ /dev/null@@ -1,49 +0,0 @@-"""Shared metadata helpers for scheduled automation turns."""--from __future__ import annotations--from typing import Any, Mapping--from nanobot.cron.types import CronJob--AUTOMATION_TRIGGER_META = "_automation_trigger"-AUTOMATION_DEFER_UNTIL_IDLE_META = "_defer_until_session_idle"-AUTOMATION_HISTORY_META = "_automation_turn"---def automation_trigger(metadata: Mapping[str, Any] | None) -> dict[str, Any] | None:- """Return structured automation trigger metadata when present."""- raw = (metadata or {}).get(AUTOMATION_TRIGGER_META)- return raw if isinstance(raw, dict) else None---def is_automation_turn(metadata: Mapping[str, Any] | None) -> bool:- return automation_trigger(metadata) is not None---def defer_until_session_idle(metadata: Mapping[str, Any] | None) -> bool:- return bool(- is_automation_turn(metadata)- and (metadata or {}).get(AUTOMATION_DEFER_UNTIL_IDLE_META) is True- )---def automation_run_id(metadata: Mapping[str, Any] | None) -> str | None:- trigger = automation_trigger(metadata)- if not trigger:- return None- value = trigger.get("run_id")- return value if isinstance(value, str) and value else None---def is_bound_agent_job(job: CronJob) -> bool:- """True for new session-bound user automations, excluding legacy delivery payloads."""- payload = job.payload- if payload.kind != "agent_turn" or not payload.session_key:- return False- return not (- payload.deliver- or payload.channel- or payload.to- or payload.channel_meta- )diff --git a/nanobot/cron/service.py b/nanobot/cron/service.pyindex 30ee7aea9..57c4dc204 100644--- a/nanobot/cron/service.py+++ b/nanobot/cron/service.py@@ -14,7 +14,7 @@ from typing import Any, Callable, Coroutine, Literalfrom filelock import FileLockfrom loguru import logger-from nanobot.cron.automation import is_bound_agent_job+from nanobot.cron.session_turns import is_bound_cron_jobfrom nanobot.cron.types import (CronJob,CronJobState,@@ -499,17 +499,17 @@ class CronService:jobs = store.jobs if include_disabled else [j for j in store.jobs if j.enabled]return sorted(jobs, key=lambda j: j.state.next_run_at_ms or float('inf'))- def list_bound_agent_jobs_for_session(+ def list_bound_cron_jobs_for_session(self,session_key: str,*,include_disabled: bool = True,) -> list[CronJob]:- """Return user-created bound automation jobs owned by *session_key*."""+ """Return user-created bound cron jobs owned by *session_key*."""return [jobfor job in self.list_jobs(include_disabled=include_disabled)- if is_bound_agent_job(job)+ if is_bound_cron_job(job)and job.payload.session_key == session_key]diff --git a/nanobot/cron/session_turns.py b/nanobot/cron/session_turns.pynew file mode 100644index 000000000..7a55e36ef--- /dev/null+++ b/nanobot/cron/session_turns.py@@ -0,0 +1,49 @@+"""Shared metadata helpers for scheduled cron session turns."""++from __future__ import annotations++from typing import Any, Mapping++from nanobot.cron.types import CronJob++CRON_TRIGGER_META = "_cron_trigger"+CRON_DEFER_UNTIL_IDLE_META = "_cron_defer_until_session_idle"+CRON_HISTORY_META = "_cron_turn"+++def cron_trigger(metadata: Mapping[str, Any] | None) -> dict[str, Any] | None:+ """Return structured cron trigger metadata when present."""+ raw = (metadata or {}).get(CRON_TRIGGER_META)+ return raw if isinstance(raw, dict) else None+++def is_cron_turn(metadata: Mapping[str, Any] | None) -> bool:+ return cron_trigger(metadata) is not None+++def defer_cron_until_session_idle(metadata: Mapping[str, Any] | None) -> bool:+ return bool(+ is_cron_turn(metadata)+ and (metadata or {}).get(CRON_DEFER_UNTIL_IDLE_META) is True+ )+++def cron_run_id(metadata: Mapping[str, Any] | None) -> str | None:+ trigger = cron_trigger(metadata)+ if not trigger:+ return None+ value = trigger.get("run_id")+ return value if isinstance(value, str) and value else None+++def is_bound_cron_job(job: CronJob) -> bool:+ """True for new session-bound cron jobs, excluding legacy delivery payloads."""+ payload = job.payload+ if payload.kind != "agent_turn" or not payload.session_key:+ return False+ return not (+ payload.deliver+ or payload.channel+ or payload.to+ or payload.channel_meta+ )diff --git a/nanobot/session/routing.py b/nanobot/session/routing.pyindex 5ae53c552..5d7c97791 100644--- a/nanobot/session/routing.py+++ b/nanobot/session/routing.py@@ -5,7 +5,7 @@ from __future__ import annotationsfrom typing import Any, Mappingfrom nanobot.bus.events import InboundMessage-from nanobot.cron.automation import is_automation_turn+from nanobot.cron.session_turns import is_cron_turnfrom nanobot.session.manager import Sessionfrom nanobot.session.metadata import SESSION_ROUTING_METADATA_KEY@@ -26,7 +26,7 @@ _ROUTING_METADATA_KEYS = {}_CHANNEL_ROUTING_METADATA_KEYS = {# Feishu needs a message anchor to reply into an existing topic. Other- # channels should avoid stale reply anchors for scheduled automation turns.+ # channels should avoid stale reply anchors for scheduled cron turns."feishu": {"message_id"},}_SLACK_ROUTING_KEYS = {"channel_type", "thread_ts"}@@ -74,8 +74,8 @@ def routing_context_for_message(msg: InboundMessage) -> dict[str, Any]:def persist_routing_context(session: Session, msg: InboundMessage) -> bool:- """Persist the latest non-automation delivery context for a session."""- if is_automation_turn(msg.metadata):+ """Persist the latest non-cron delivery context for a session."""+ if is_cron_turn(msg.metadata):return Falsecontext = routing_context_for_message(msg)if session.metadata.get(SESSION_ROUTING_METADATA_KEY) == context:diff --git a/nanobot/templates/agent/cron_reminder.md b/nanobot/templates/agent/cron_reminder.mdindex af9803d5a..64f94f21b 100644--- a/nanobot/templates/agent/cron_reminder.md+++ b/nanobot/templates/agent/cron_reminder.md@@ -1,4 +1,4 @@-The scheduled time has arrived. Execute this scheduled automation now and report the result to the user in the same session.+The scheduled time has arrived. Execute this scheduled cron job now and report the result to the user in the same session.Rules:- Speak directly to the user in their language.@@ -6,4 +6,4 @@ Rules:- Do not include user IDs.- Do not add status reports like "Done" or "Reminded" unless they are the natural response.-Automation: {{ message }}+Cron job: {{ message }}diff --git a/nanobot/webui/session_automations.py b/nanobot/webui/session_automations.pyindex 19af69a64..3eb56e5b2 100644--- a/nanobot/webui/session_automations.py+++ b/nanobot/webui/session_automations.py@@ -8,7 +8,7 @@ from nanobot.cron.types import CronJobclass _CronServiceLike(Protocol):- def list_bound_agent_jobs_for_session(+ def list_bound_cron_jobs_for_session(self,session_key: str,*,@@ -23,7 +23,7 @@ def session_automation_jobs("""Return user automations attached to the WebUI session."""if cron_service is None:return []- return cron_service.list_bound_agent_jobs_for_session(+ return cron_service.list_bound_cron_jobs_for_session(session_key,include_disabled=True,)diff --git a/tests/agent/test_loop_save_turn.py b/tests/agent/test_loop_save_turn.pyindex 0b212f5fc..5295065d0 100644--- a/tests/agent/test_loop_save_turn.py+++ b/tests/agent/test_loop_save_turn.py@@ -8,7 +8,7 @@ from nanobot.agent.context import ContextBuilderfrom nanobot.agent.loop import AgentLoopfrom nanobot.bus.events import InboundMessagefrom nanobot.bus.queue import MessageBus-from nanobot.cron.automation import AUTOMATION_HISTORY_META, AUTOMATION_TRIGGER_META+from nanobot.cron.session_turns import CRON_HISTORY_META, CRON_TRIGGER_METAfrom nanobot.providers.base import LLMResponsefrom nanobot.session.goal_state import GOAL_STATE_KEYfrom nanobot.session.manager import Session, SessionManager@@ -66,7 +66,7 @@ def test_agent_loop_llm_runtime_reflects_current_provider_and_model(tmp_path: Paassert runtime.model == "next-model"-def test_persist_automation_turn_uses_distinct_history_marker(tmp_path: Path) -> None:+def test_persist_cron_turn_uses_distinct_history_marker(tmp_path: Path) -> None:loop = _make_full_loop(tmp_path)session = loop.sessions.get_or_create("websocket:auto")prompt_ref = {"id": "cron.agent_turn.reminder", "version": 1, "sha256": "abc"}@@ -76,14 +76,14 @@ def test_persist_automation_turn_uses_distinct_history_marker(tmp_path: Path) ->channel="websocket",sender_id="cron",chat_id="auto",- content="Automation: internal prompt",+ content="Cron job: internal prompt",metadata={- AUTOMATION_TRIGGER_META: {+ CRON_TRIGGER_META: {"job_id": "job-1","job_name": "Daily check","run_id": "job-1:1","prompt_ref": prompt_ref,- "persist_content": "Scheduled automation triggered: Daily check",+ "persist_content": "Scheduled cron job triggered: Daily check",}},),@@ -92,13 +92,13 @@ def test_persist_automation_turn_uses_distinct_history_marker(tmp_path: Path) ->assert persisted is Truemessage = session.messages[-1]- assert message["content"] == "Scheduled automation triggered: Daily check"- assert message[AUTOMATION_HISTORY_META] is True- assert AUTOMATION_TRIGGER_META not in message- assert message["automation_id"] == "job-1"- assert message["automation_name"] == "Daily check"- assert message["automation_run_id"] == "job-1:1"- assert message["automation_prompt_ref"] == prompt_ref+ assert message["content"] == "Scheduled cron job triggered: Daily check"+ assert message[CRON_HISTORY_META] is True+ assert CRON_TRIGGER_META not in message+ assert message["cron_job_id"] == "job-1"+ assert message["cron_job_name"] == "Daily check"+ assert message["cron_run_id"] == "job-1:1"+ assert message["cron_prompt_ref"] == prompt_refdef test_clean_generated_title_strips_reasoning_tags() -> None:diff --git a/tests/agent/test_runner_injections.py b/tests/agent/test_runner_injections.pyindex 3133a1698..97d653f3a 100644--- a/tests/agent/test_runner_injections.py+++ b/tests/agent/test_runner_injections.py@@ -617,12 +617,12 @@ async def test_followup_routed_to_pending_queue(tmp_path):@pytest.mark.asyncio-async def test_automation_turn_deferred_while_session_active(tmp_path):- """Automation turns wait for the active session instead of becoming injections."""+async def test_cron_turn_deferred_while_session_active(tmp_path):+ """Cron turns wait for the active session instead of becoming injections."""from nanobot.bus.events import InboundMessage- from nanobot.cron.automation import (- AUTOMATION_DEFER_UNTIL_IDLE_META,- AUTOMATION_TRIGGER_META,+ from nanobot.cron.session_turns import (+ CRON_DEFER_UNTIL_IDLE_META,+ CRON_TRIGGER_META,)loop = _make_loop(tmp_path)@@ -639,15 +639,15 @@ async def test_automation_turn_deferred_while_session_active(tmp_path):chat_id="chat-1",content="scheduled work",metadata={- AUTOMATION_TRIGGER_META: {"run_id": "run-1"},- AUTOMATION_DEFER_UNTIL_IDLE_META: True,+ CRON_TRIGGER_META: {"run_id": "run-1"},+ CRON_DEFER_UNTIL_IDLE_META: True,},session_key_override=session_key,)await loop.bus.publish_inbound(msg)for _ in range(20):- if loop._deferred_automation_queues.get(session_key):+ if loop._cron_turns.deferred_queues.get(session_key):breakawait asyncio.sleep(0.05)@@ -656,12 +656,12 @@ async def test_automation_turn_deferred_while_session_active(tmp_path):assert pending.empty()assert loop._dispatch.await_count == 0- assert loop._deferred_automation_queues[session_key] == [msg]+ assert loop._cron_turns.deferred_queues[session_key] == [msg]- await loop._publish_next_deferred_automation(session_key)+ await loop._cron_turns.publish_next_deferred(session_key)queued = await asyncio.wait_for(loop.bus.consume_inbound(), timeout=0.5)assert queued is msg- assert session_key not in loop._deferred_automation_queues+ assert session_key not in loop._cron_turns.deferred_queues@pytest.mark.asynciodiff --git a/tests/agent/test_task_cancel.py b/tests/agent/test_task_cancel.pyindex 0111c2f59..e6a59d5e1 100644--- a/tests/agent/test_task_cancel.py+++ b/tests/agent/test_task_cancel.py@@ -10,6 +10,7 @@ from unittest.mock import AsyncMock, MagicMock, patchimport pytestfrom nanobot.config.schema import AgentDefaults+from nanobot.session.keys import UNIFIED_SESSION_KEY_MAX_TOOL_RESULT_CHARS = AgentDefaults().max_tool_result_chars@@ -450,12 +451,12 @@ class TestSubagentAnnounceSessionKey:so the result matches the pending queue key."""mgr, bus = self._make_mgr()- origin = {"channel": "telegram", "chat_id": "111", "session_key": "unified:default"}+ origin = {"channel": "telegram", "chat_id": "111", "session_key": UNIFIED_SESSION_KEY}await mgr._announce_result("sub-1", "label", "task", "result", origin, "ok")msg = await bus.consume_inbound()- assert msg.session_key_override == "unified:default"- assert msg.session_key == "unified:default"+ assert msg.session_key_override == UNIFIED_SESSION_KEY+ assert msg.session_key == UNIFIED_SESSION_KEY@pytest.mark.asyncioasync def test_announce_uses_raw_key_in_normal_mode(self):@@ -505,9 +506,9 @@ class TestSubagentAnnounceSessionKey:)await mgr._run_subagent("sub-4", "task", "label",- {"channel": "telegram", "chat_id": "444", "session_key": "unified:default"},+ {"channel": "telegram", "chat_id": "444", "session_key": UNIFIED_SESSION_KEY},status,)msg = await bus.consume_inbound()- assert msg.session_key_override == "unified:default"+ assert msg.session_key_override == UNIFIED_SESSION_KEYdiff --git a/tests/agent/test_unified_session.py b/tests/agent/test_unified_session.pyindex 48fd91bdc..d6059f747 100644--- a/tests/agent/test_unified_session.py+++ b/tests/agent/test_unified_session.py@@ -25,9 +25,9 @@ from nanobot.bus.queue import MessageBusfrom nanobot.command.builtin import cmd_new, register_builtin_commandsfrom nanobot.command.router import CommandContext, CommandRouterfrom nanobot.config.schema import AgentDefaults, Config+from nanobot.session.keys import UNIFIED_SESSION_KEYfrom nanobot.session.manager import Session, SessionManager-# ---------------------------------------------------------------------------# Helpers# ---------------------------------------------------------------------------@@ -39,8 +39,8 @@ def _make_loop(tmp_path: Path, unified_session: bool = False) -> AgentLoop:provider.get_default_model.return_value = "test-model"with patch("nanobot.agent.loop.SessionManager"), \- patch("nanobot.agent.loop.SubagentManager") as MockSubMgr:- MockSubMgr.return_value.cancel_by_session = AsyncMock(return_value=0)+ patch("nanobot.agent.loop.SubagentManager") as mock_sub_mgr:+ mock_sub_mgr.return_value.cancel_by_session = AsyncMock(return_value=0)loop = AgentLoop(bus=bus,provider=provider,@@ -415,10 +415,8 @@ class TestStopCommandWithUnifiedSession:@pytest.mark.asyncioasync def test_active_tasks_use_effective_key_in_unified_mode(self, tmp_path: Path):"""When unified_session=True, tasks are stored under UNIFIED_SESSION_KEY."""- from nanobot.agent.loop import UNIFIED_SESSION_KEY-loop = _make_loop(tmp_path, unified_session=True)-+# Create a message from telegram channelmsg = _make_msg(channel="telegram", chat_id="123456")@@ -443,7 +441,6 @@ class TestStopCommandWithUnifiedSession:@pytest.mark.asyncioasync def test_stop_command_finds_task_in_unified_mode(self, tmp_path: Path):"""cmd_stop can cancel tasks when unified_session=True."""- from nanobot.agent.loop import UNIFIED_SESSION_KEYfrom nanobot.command.builtin import cmd_stoploop = _make_loop(tmp_path, unified_session=True)@@ -476,7 +473,6 @@ class TestStopCommandWithUnifiedSession:@pytest.mark.asyncioasync def test_stop_command_uses_effective_key_without_session_override(self, tmp_path: Path):"""Priority /stop must cancel the unified session even before dispatch rewrites the message."""- from nanobot.agent.loop import UNIFIED_SESSION_KEYfrom nanobot.command.builtin import cmd_stoploop = _make_loop(tmp_path, unified_session=True)@@ -502,7 +498,6 @@ class TestStopCommandWithUnifiedSession:@pytest.mark.asyncioasync def test_stop_command_cross_channel_in_unified_mode(self, tmp_path: Path):"""In unified mode, /stop from one channel cancels tasks from another channel."""- from nanobot.agent.loop import UNIFIED_SESSION_KEYfrom nanobot.command.builtin import cmd_stoploop = _make_loop(tmp_path, unified_session=True)diff --git a/tests/channels/test_websocket_http_routes.py b/tests/channels/test_websocket_http_routes.pyindex f8fd70c15..50e935f8d 100644--- a/tests/channels/test_websocket_http_routes.py+++ b/tests/channels/test_websocket_http_routes.py@@ -749,7 +749,7 @@ async def test_session_delete_blocks_when_bound_automation_exists(assert body["blocked_by_automations"] is Trueassert [job["name"] for job in body["automations"]] == ["Daily check"]assert path.exists()- assert cron.list_bound_agent_jobs_for_session("websocket:doomed")+ assert cron.list_bound_cron_jobs_for_session("websocket:doomed")finally:await channel.stop()await server_task@@ -792,7 +792,7 @@ async def test_session_delete_can_cascade_bound_automations(assert resp.status_code == 200assert resp.json()["deleted"] is Trueassert not path.exists()- assert cron.list_bound_agent_jobs_for_session("websocket:doomed") == []+ assert cron.list_bound_cron_jobs_for_session("websocket:doomed") == []assert [job.name for job in cron.list_jobs(include_disabled=True)] == ["Legacy same target"]@@ -837,7 +837,7 @@ async def test_session_delete_does_not_cascade_unified_automations(assert resp.status_code == 200assert resp.json()["deleted"] is Trueassert not path.exists()- assert [job.name for job in cron.list_bound_agent_jobs_for_session(UNIFIED_SESSION_KEY)] == [+ assert [job.name for job in cron.list_bound_cron_jobs_for_session(UNIFIED_SESSION_KEY)] == ["Shared daily check"]finally:diff --git a/tests/cli/test_commands.py b/tests/cli/test_commands.pyindex 975126ad8..74d623696 100644--- a/tests/cli/test_commands.py+++ b/tests/cli/test_commands.py@@ -11,7 +11,7 @@ from typer.testing import CliRunnerfrom nanobot.bus.events import InboundMessage, OutboundMessagefrom nanobot.cli.commands import _proactive_delivery_metadata, appfrom nanobot.config.schema import Config-from nanobot.cron.automation import AUTOMATION_DEFER_UNTIL_IDLE_META, AUTOMATION_TRIGGER_META+from nanobot.cron.session_turns import CRON_DEFER_UNTIL_IDLE_META, CRON_TRIGGER_METAfrom nanobot.cron.types import CronJob, CronPayloadfrom nanobot.providers.factory import ProviderSnapshot, make_providerfrom nanobot.providers.openai_codex_provider import _strip_model_prefix@@ -1430,8 +1430,8 @@ def test_gateway_legacy_cron_payloads_with_session_key_stay_legacy(content="Legacy response.",)- async def submit_automation_turn(self, _msg: InboundMessage):- raise AssertionError("legacy cron payload must not run as bound automation")+ async def submit_cron_turn(self, _msg: InboundMessage):+ raise AssertionError("legacy cron payload must not run as bound cron turn")async def close_mcp(self) -> None:return None@@ -1601,8 +1601,8 @@ def test_gateway_bound_cron_runs_as_session_turn(self.tools = {}seen["agent"] = self- async def submit_automation_turn(self, msg: InboundMessage):- seen["automation_msg"] = msg+ async def submit_cron_turn(self, msg: InboundMessage):+ seen["cron_msg"] = msgreturn OutboundMessage(channel=msg.channel,chat_id=msg.chat_id,@@ -1646,26 +1646,26 @@ def test_gateway_bound_cron_runs_as_session_turn(response = asyncio.run(cron.on_job(job))assert response == "Checked the repo."- msg = seen["automation_msg"]+ msg = seen["cron_msg"]assert isinstance(msg, InboundMessage)assert msg.channel == "websocket"assert msg.chat_id == "chat-1"assert msg.sender_id == "cron"assert msg.session_key_override == "websocket:chat-1"- assert "Automation: Check repository health." in msg.content+ assert "Cron job: Check repository health." in msg.contentassert msg.metadata["webui"] is Trueassert msg.metadata["workspace_scope"]["project_path"] == str(tmp_path)assert msg.metadata[WEBUI_MESSAGE_SOURCE_METADATA_KEY] == {"kind": "cron","label": "Repo check",}- trigger = msg.metadata[AUTOMATION_TRIGGER_META]+ trigger = msg.metadata[CRON_TRIGGER_META]assert trigger["job_id"] == "repo-check"assert trigger["job_name"] == "Repo check"assert trigger["persist_content"] == (- "Scheduled automation triggered: Repo check\n\nCheck repository health."+ "Scheduled cron job triggered: Repo check\n\nCheck repository health.")- assert msg.metadata[AUTOMATION_DEFER_UNTIL_IDLE_META] is True+ assert msg.metadata[CRON_DEFER_UNTIL_IDLE_META] is Truestatuses = [record["status"] for _run_id, record in seen["run_records"]]assert statuses == ["queued", "ok"]assert seen["run_records"][0][0] == seen["run_records"][1][0]@@ -1682,7 +1682,7 @@ def test_gateway_bound_cron_runs_as_session_turn(response = asyncio.run(cron.on_job(discord_job))assert response == "Checked the repo."- msg = seen["automation_msg"]+ msg = seen["cron_msg"]assert isinstance(msg, InboundMessage)assert msg.channel == "discord"assert msg.chat_id == "777"diff --git a/tests/cron/test_cron_service.py b/tests/cron/test_cron_service.pyindex f258fdd22..98e37dc13 100644--- a/tests/cron/test_cron_service.py+++ b/tests/cron/test_cron_service.py@@ -84,7 +84,7 @@ def test_list_bound_agent_jobs_excludes_legacy_delivery_payloads(tmp_path) -> Nosession_key="websocket:chat-1",)- assert service.list_bound_agent_jobs_for_session("websocket:chat-1") == [bound]+ assert service.list_bound_cron_jobs_for_session("websocket:chat-1") == [bound]@pytest.mark.asynciodiff --git a/tests/cron/test_cron_tool_list.py b/tests/cron/test_cron_tool_list.pyindex 499979a66..4af4de13a 100644--- a/tests/cron/test_cron_tool_list.py+++ b/tests/cron/test_cron_tool_list.py@@ -349,7 +349,7 @@ def test_add_job_requires_session_key(tmp_path) -> None:result = tool._add_job(None, "Background refresh", 60, None, None, None)- assert result == "Error: scheduled automations must be created from a chat session"+ assert result == "Error: scheduled cron jobs must be created from a chat session"assert tool._cron.list_jobs() == []