✨ Add ScheduledTaskTool with global scheduler and frontend polling

[2862282695gjh-afk]

Summary

Add a ScheduledTaskTool that enables Nexent agents to create, list, and cancel cron-based or one-shot scheduled tasks.

Architecture

ScheduledTaskTool (thin CRUD)
  ├── create → write to scheduled_tasks_t
  ├── list   → read by agent_id + tenant_id
  └── cancel → update status

Global SchedulerService (singleton, survives agent runs)
  └── 10s DB poll → find due tasks → new agent run → save messages

Frontend Polling
  ├── Layer 1: 5s poll active conversation (refresh + scroll)
  └── Layer 2: 10s batch-poll background conversations (silent cache update)

Why not just a tool module?

Nexent creates a new agent instance per message — tools, scheduler threads, and all state are GCd after each run. A scheduled task tool needs to survive beyond a single agent run, which requires:

1. DB persistence — task data outlives any agent instance
2. Global scheduler — independent singleton thread, started at runtime_service startup
3. Frontend polling — SSE is request-response only, no persistent connection for push

Key Design Decisions

Decision	Rationale
Global scheduler, not per-tool	Agent instances are ephemeral — per-tool schedulers die with the agent
Scheduler strips ScheduledTaskTool from triggered agent	Prevents recursive task creation (agent sees the prompt and tries to create another task)
message_idx from DB max()	Original save_messages computes idx from history=[] → always 0, causing collisions
Two-layer frontend polling	Active conversation gets fast updates; background conversations get silent cache refresh
Ownership check in polling API	get_new_messages_service validates conversation.created_by == user_id

Multi-Tenant Compatibility

• ScheduledTaskRecord includes tenant_id and user_id fields
• query_tasks_by_agent and cancel_task filter by tenant_id
• Scheduler is global (polls all pending tasks) but uses each tasks own tenant_id/user_id for agent runs
• Frontend polling API validates conversation ownership

Files Changed (15 files, +877 lines, all additive)

New files (3):

• backend/database/scheduled_task_db.py — 5 CRUD functions
• backend/services/scheduled_task_scheduler.py — global scheduler singleton
• sdk/nexent/core/tools/scheduled_task_tool.py — tool with cron parser

Modified files (12, no existing logic changed):

• backend/database/db_models.py — ScheduledTaskRecord model
• backend/database/conversation_db.py — get_max_message_index()
• backend/services/conversation_management_service.py — get_new_messages_service()
• backend/apps/conversation_management_app.py — polling endpoints
• backend/apps/runtime_app.py — scheduler lifecycle
• backend/agents/create_agent_info.py — conversation_id passthrough
• sdk/nexent/core/agents/nexent_agent.py — ScheduledTaskTool metadata injection
• sdk/nexent/core/tools/__init__.py — export ScheduledTaskTool
• docker/init.sql — scheduled_tasks_t table
• frontend/services/api.ts — new endpoints
• frontend/services/conversationService.ts — polling methods
• frontend/app/[locale]/chat/internal/chatInterface.tsx — polling useEffect

Testing

Tested with Docker (v2.2.0 image + bind mounts):

• Created "remind me every 5 minutes" task → agent created task in DB ✅
• Scheduler detected due task → triggered agent run → wrote messages to DB ✅
• Frontend polling detected new messages → refreshed display ✅
• Switched conversation → background polling updated cache ✅
• No ScheduledTaskTool not found errors ✅
• No recursive task creation ✅

[JasonW404]

Cron 解析器只支持精确数字和 *，不支持 */15、1-5、1,3,5 等标准 cron 语法。用户尝试这些时会抛 ValueError。建议在 description 中说明支持的语法子集，或使用 croniter 库。

[JasonW404]

性能问题：逐分钟遍历计算下次触发时间，最多 525,960 次循环。建议直接用 datetime 算术计算下一个匹配时间点。

[JasonW404]

串行阻塞：t.join(timeout=300) 让调度器为每个任务阻塞最多 5 分钟。10 个任务同时到期时，最后一个要等 50 分钟。建议用 ThreadPoolExecutor 并行执行。

[JasonW404]

asyncio.run() 和手动 new_event_loop() 混用会导致事件循环冲突和资源泄漏。建议统一在一个 async 函数中执行：

async def _execute():
    agent_run_info = await create_agent_run_info(...)
    async for chunk in agent_run(agent_run_info):
        chunks.append(chunk)
asyncio.run(_execute())

[YehongPan]

[代码规范] except Exception: 过于宽泛，建议捕获更具体的异常类型，避免掩盖潜在错误。

[YehongPan]

[代码规范] except Exception: 过于宽泛，建议捕获更具体的异常类型，避免掩盖潜在错误。

[YehongPan]

[代码规范] except Exception: 过于宽泛，建议捕获更具体的异常类型，避免掩盖潜在错误。

[YehongPan]

[逻辑漏洞] _run_scheduled_task_from_db 中先使用 asyncio.run() 创建了一个事件循环，随后又用 asyncio.new_event_loop() 创建了另一个事件循环。asyncio.run() 会自动创建并管理事件循环，在同一函数中混用两种方式可能导致事件循环冲突。建议统一使用 asyncio.new_event_loop() + loop.run_until_complete() 的方式，或统一使用 asyncio.run()。

[YehongPan]

[代码规范] @app.on_event("startup") 和 @app.on_event("shutdown") 在 FastAPI 中已被标记为弃用（deprecated），建议使用 lifespan 上下文管理器替代。参考：https://fastapi.tiangolo.com/advanced/events/

[YehongPan]

[代码规范] batch_check_new_messages_endpoint 的请求体使用了 Dict[str, Any]，缺少类型约束和输入验证。建议使用 Pydantic 模型定义请求结构（如 BatchMessageCheckRequest），确保 checks 列表中的每个元素都包含必要的字段和类型校验。

[JasonW404]

ScheduledTaskTool 使用 asyncio.run() 在同步 forward 方法中执行异步任务，但如果 forward 已经在异步上下文中被调用（如通过 asyncio.to_thread），会抛出 RuntimeError。建议检查调用上下文，或使用 asyncio.get_event_loop().run_until_complete() 替代。

[WMC001]

Good addition. The ScheduledTaskTool integration with cron support looks reasonable. Please ensure the cron expression validation is covered by tests before merging.

[2862282695gjh-afk]

Thanks @WMC001! Added unit tests covering cron expression validation and next-fire-time computation in test/sdk/core/tools/test_scheduled_task_tool.py (27 test cases, all passing).

Coverage includes:

• _expand_cron_field: *, exact values, ranges (1-5), steps (*/15, 1-30/10), comma lists (1,3,5, mixed), Sunday normalization (7→0), and invalid inputs (out-of-range, zero step)
• _parse_cron: valid 5-field expressions, complex expressions (*/15 9-18 * * 1-5), and 7 invalid-expression cases (out-of-range fields, wrong field count, non-numeric, zero step)
• _compute_next_fire: daily scheduling, step intervals, weekday filtering, skipping to next allowed day/month, rolling to next year, impossible-expression fallback, and past-hour jump-to-tomorrow

The tests load the tool module via importlib with a stubbed smolagents.tools.Tool base class, so they run without the full SDK/memory dependency chain.

[WMC001]

Bug 1: batch_check_new_messages_endpoint has no error isolation

backend/apps/conversation_management_app.py line 196-201 — the loop over request.checks has no try/except. If get_new_messages_service raises for any single conversation, the entire batch fails and the caller gets a 500 with no partial results:

for check in request.checks[:50]:
    results[str(check.conversation_id)] = get_new_messages_service(  # <-- no try/except
        check.conversation_id, user_id, check.since_index
    )

Fix: wrap the call in a try/except and record an error indicator per conversation instead of propagating the exception.

[WMC001]

Bug 2: cron _compute_next_fire incorrect for day_of_month and day_of_week interaction

sdk/nexent/core/tools/scheduled_task_tool.py line 1165-1168 — when candidate.day not in allowed_dom, the code advances to tomorrow at 00:00. But this skips over days that might match day_of_week. For example, cron "0 9 15 * 1" (9am on the 15th OR any Monday): advancing day-by-day from June 24 could skip past the next Monday if it lands on a non-matching day. The algorithm should consider both day-of-month and day-of-week simultaneously, or follow standard cron OR logic (if both fields are restricted, either matching satisfies the condition).

Note: Python's croniter library and standard cron treat day-of-month and day-of-week with OR semantics by default (unless L or # modifiers are used). The current logic treats them as AND, which is incorrect.

Fix: when both day_of_month and day_of_week have restricted values (non-*), use OR logic — accept the day if it matches either field.

[2862282695gjh-afk]

Thanks @WMC001, both issues fixed in the latest commit:

Bug 1 (batch error isolation) — batch_check_new_messages_endpoint now wraps each conversation check in its own try/except. A failing conversation returns {"error": "check_failed"} instead of propagating and failing the whole batch with a 500.

Bug 2 (day-of-month / day-of-week OR semantics) — good catch, the previous AND logic was non-standard. Now _parse_cron records day_of_month_restricted / day_of_week_restricted flags (true when the field was not a bare *), and _compute_next_fire applies standard cron OR semantics: when both day fields are restricted, a day matches if it satisfies either field; when only one is restricted, that field must match.

Added 5 new tests covering this:

• 0 9 15 * 1 (15th OR Monday) → matches the next Monday (06-29)
• 0 9 26 * 1 (26th OR Monday) → matches the earlier day-of-month hit (06-26)
• 0 9 29 * * (only dom restricted) → still requires the 29th
• 0 9 * * 1 (only dow restricted) → next Monday
• parse records the restriction flags correctly

All 32 tests passing locally.

[2862282695gjh-afk]

Pushed a follow-up commit (f67afb71) fixing usability bugs found while driving the full scheduled-task flow end-to-end. These are the issues that actually blocked the feature from working in practice:

1. task_type auto-inference (_resolve_task_type)
Passing only cron_expression was silently treated as oneshot (the default) and then demanded delay_seconds, so cron-task creation kept failing with a confusing error. The task type is now inferred from whichever time field is present, and task_type can be omitted entirely. Tool input descriptions rewritten to be pure contract (no scenario examples) and to state the cron/delay mutual-exclusion clearly.

2. cancel accepts task_uuid OR task_name
Callers frequently pass the task id via task_name. Cancel now tries the uuid directly, then falls back to a name lookup, so the first attempt succeeds instead of erroring.

3. Assistant message rendering (_save_assistant_chunks)
The scheduler was dumping raw JSON chunk strings as the assistant content. Now chunks are parsed, metadata chunks (step_count/token_count/agent_new_run) filtered out, and same-type units folded — matching save_conversation_assistant. Also fixed a NameError (MESSAGE_ROLE import).

4. Trigger message split into display vs. query
The internal instruction prompt was being shown in the chat bubble. Now a short human-readable line is stored as the user message, while the full instruction is passed only to the agent as the run query.

5. Frontend polling races
Polling no longer overwrites a conversation that is actively streaming (which wiped in-progress tool-call rendering), and the refresh path reuses the standard message extractors so tool-call steps survive refresh instead of collapsing to just the final answer.

Tests: added coverage for _resolve_task_type (inference + rejection cases) and _handle_cancel (uuid / name-fallback / not-found). 44 unit tests passing locally.

[2862282695gjh-afk]

Heads-up for reviewers on the cancel reliability of this tool, based on end-to-end testing:

This feature's reliability depends on the backing LLM's tool-use discipline. The scheduled_task tool is invoked via smolagents' prompt-based tool calling (the model emits Python code to call it), so there is no framework-level tool_choice forcing a call. With a weaker model we observed that "cancel this task" could occasionally be short-circuited: the model emitted a final_answer claiming success without actually calling the tool (a hallucination). The tool code, DB layer, and scheduler all behave correctly when the tool is called — this is purely an LLM-behavior issue.

Mitigations already in this PR (code-side, model-independent):

• cancel_task accepts both pending and fired, so a task can be cancelled even mid-execution.
• reschedule_if_active re-arms a cron task only while still fired, so a cancelled task is never resurrected on its next cycle.
• The tool description keeps the cancel flow explicit and concise (list → cancel by uuid → verify).

In testing, switching the agent from qwen-plus to qwen3-max eliminated the hallucination — confirming the root cause is model tier, not the tool.

If a deployment uses a weaker model and needs a hard guarantee, the next step would be a verification hook in the agent run: intercept a final_answer that claims a scheduled_task outcome when no matching tool call exists in the step trace, and force a retry. That is intentionally out of scope for this PR (it touches the agent run pipeline and is model-agnostic infra), but I wanted to flag it as the recommended follow-up rather than expand this PR's surface.